diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 93ff0c8a..8ee4b39f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -149,8 +149,30 @@ jobs: name: Install worker dependencies run: bun install --frozen-lockfile --ignore-scripts + # Restore on every run, SAVE ONLY ON MAIN — the split `build-daemon.yml` + # already uses, for a second reason that turned out to matter more. + # + # A combined `actions/cache@v6` writes a ref-scoped copy from every branch + # that misses the exact key, and this entry carries `target/`, so each copy + # is 1.5-2.3 GiB. Five PR refs held one at once (677, 679, 680, 681 and + # main) — ~10.7 GiB of a repo cache that GitHub caps at 10 GiB, which puts + # the store permanently in LRU eviction. + # + # What that evicted was not another cargo build. It was the 13 KB + # translation cache, touched once every 24 hours by the nightly + # `translate-docs` run and therefore always the least-recently-used thing + # in the store. Losing it re-translated all 48 pages into all 14 languages + # the next morning: ~125 runner-minutes and a full LLM pass per language, + # against a 4-minute baseline when the cache survives. Six consecutive days + # of it, Aug 6-11, cost ~750 runner-minutes and six full translation passes + # through the gateway. + # + # Restoring without saving costs a PR whose `Cargo.lock` moved a rebuild + # from a stale-but-close main cache — which is already what `restore-keys` + # hands it today. - if: steps.crates.outputs.present == 'true' - uses: actions/cache@v6 + id: cargo-cache + uses: actions/cache/restore@v6 with: path: | ~/.cargo/registry/index @@ -172,6 +194,25 @@ jobs: if: steps.crates.outputs.present == 'true' run: cargo test --workspace + # Paired with the restore above. `cache-hit != 'true'` skips the write when + # the exact key already exists, so a run that changed nothing does not + # re-upload 2 GiB; a push to main whose Cargo.lock moved is the only thing + # that writes here. + - name: Save cargo cache + if: >- + steps.crates.outputs.present == 'true' + && github.event_name == 'push' + && github.ref == 'refs/heads/main' + && steps.cargo-cache.outputs.cache-hit != 'true' + uses: actions/cache/save@v6 + with: + path: | + ~/.cargo/registry/index + ~/.cargo/registry/cache + ~/.cargo/git/db + target + key: cargo-${{ runner.os }}-${{ hashFiles('rust-toolchain.toml', 'Cargo.lock', 'crates/*/Cargo.toml') }} + test: runs-on: ubuntu-latest strategy: diff --git a/.github/workflows/translate-docs.yml b/.github/workflows/translate-docs.yml index b732b2aa..318a986c 100644 --- a/.github/workflows/translate-docs.yml +++ b/.github/workflows/translate-docs.yml @@ -80,12 +80,32 @@ jobs: # hook, which builds the full Next.js application once per language. run: bun install --frozen-lockfile --ignore-scripts + # The old primary key was + # `translation-cache-${{ hashFiles('scripts/translate-docs/.translation-cache.json') }}`, + # which ALWAYS evaluated to the bare literal `translation-cache-`: the file + # is gitignored (.gitignore:68), so it is absent at checkout and + # `hashFiles` returns "". Every restore that ever worked was a + # `restore-keys` prefix match, and a total miss is indistinguishable from a + # hit — nothing fails, nothing warns, the job just spends nine minutes and + # a full LLM pass. Hence the explicit warning step below: a miss is the + # expensive case and it should say so in the run summary. - name: Restore translation cache + id: restore-cache uses: actions/cache/restore@v6 with: path: scripts/translate-docs/.translation-cache.json - key: translation-cache-${{ hashFiles('scripts/translate-docs/.translation-cache.json') }} - restore-keys: translation-cache- + # Per language, newest-first, falling back to the merged entry that + # `consolidate` still writes. `github.run_id` is monotonic, so the + # prefix match returns this language's most recent fragment. + key: translation-cache-${{ matrix.lang }}-${{ github.run_id }} + restore-keys: | + translation-cache-${{ matrix.lang }}- + translation-cache- + + - name: Warn on translation cache miss + if: steps.restore-cache.outputs.cache-matched-key == '' + run: | + echo "::warning title=Translation cache MISS::${{ matrix.lang }} will re-translate every page (~9 runner-minutes and one full LLM pass)" - name: Translate ${{ matrix.lang }} run: bun run translate --languages ${{ matrix.lang }} ${{ inputs.force == true && '--force' || '' }} @@ -99,6 +119,29 @@ jobs: - name: Validate translated pages parse and images resolve run: bun run validate:mdx + # Save HERE, per language, in the job that produced the work and directly + # after the step that proved it good. + # + # The only save used to be `consolidate`'s, downstream of BOTH the matrix + # gate (`if: needs.translate.result == 'success'`) and `mintlify validate`. + # So one page failing validation in one language threw away the cache for + # all fourteen — Aug 6 lost ~110 minutes of completed translation to a + # single `ko` page — and a nav mismatch in consolidate did the same on + # Aug 12. Each fragment is already authoritative for its own language, so + # there is nothing a merge has to happen first for. + # + # The `cache-hit` guard is the same one `build-daemon.yml:137` carries, and + # it is load-bearing here for a specific reason: the key embeds + # `github.run_id`, which is REUSED when someone re-runs a failed job. On + # that second attempt the primary key already exists, so the restore above + # scores an exact hit and this save would collide with itself. + - name: Save translation cache fragment + if: steps.restore-cache.outputs.cache-hit != 'true' + uses: actions/cache/save@v6 + with: + path: scripts/translate-docs/.translation-cache.json + key: translation-cache-${{ matrix.lang }}-${{ github.run_id }} + - name: Upload translated files uses: actions/upload-artifact@v7 with: @@ -106,7 +149,7 @@ jobs: path: | docs/${{ matrix.lang }}/ docs/i18n/README.${{ matrix.lang }}.md - retention-days: 1 + retention-days: 7 if-no-files-found: error - name: Upload cache fragment @@ -114,7 +157,7 @@ jobs: with: name: cache-${{ matrix.lang }} path: scripts/translate-docs/.translation-cache.json - retention-days: 1 + retention-days: 7 if-no-files-found: error include-hidden-files: true diff --git a/CHANGELOG.md b/CHANGELOG.md index a9e93431..ee051362 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 1.0.1-beta.0 — 2026-08-12 + +### Fixes + +- Stop the nightly doc translation re-translating everything, most days. Runs cost **4 minutes** on Aug 3-5 and **118-136 minutes** every day from Aug 6-11 — ~750 wasted runner-minutes and six full-corpus passes through the LLM gateway in six days. Three causes compound, and none of them was the translation cache's own logic, which is sound. **First, the cache was being evicted between runs.** `ci.yml` cached `target/` under a combined `actions/cache@v6`, so every PR ref that missed the exact key wrote its own 1.5-2.3 GiB copy; five were live at once (#677, #679, #680, #681 and main), putting the repo at **11.56 GiB against GitHub's 10 GiB cap** and so permanently in LRU eviction. What that evicted was the 13 KB translation cache — touched once every 24 hours, therefore always the least-recently-used thing in the store. The restore/save split is the one `build-daemon.yml:117-144` already uses, and its comment there already gives the second reason to want it. **Second, the cache was saved once, at the end of a serial pipeline.** The only save sat in `consolidate`, downstream of both the matrix gate and `mintlify validate`, so a single page failing in a single language discarded all fourteen languages' work: Aug 6 lost ~110 completed minutes to one `ko` page. Each language now saves its own fragment in the job that produced it, immediately after the step that proved it good; the merged entry stays as a cross-language fallback. **Third, a cache HIT never checked that the translated file exists.** `isCached` is a pure function of the English source hash — it records that a page was translated once, not that it is on disk — and translations land on an auto-translate PR branch. With #682 unmerged, `main` lacked `docs//cli/{update,migrate}.mdx` while the cache reported them done, so they were never regenerated, `--update-nav` (which reads the *English* tree) emitted nav entries pointing at them, and `mintlify validate` failed on 28 missing files. That is non-convergent: **a cache hit fails validation and only a full 120-minute miss goes green**, which is exactly what Aug 12 did. Statting the output makes the cache self-healing against any "translated once, never landed" gap. Also: a cache miss is now a visible `::warning` rather than silent — the old restore key always evaluated to the bare literal `translation-cache-`, since the file is gitignored and `hashFiles` returns `""` for an absent path, so every restore that ever worked was a prefix fallback and a total miss looked identical to a hit. Artifact retention goes 1 → 7 days so a run that dies mid-pipeline leaves a manual recovery path. (#685) + ## 1.0.0 — 2026-08-12 The first stable release. Everything below this heading shipped across the diff --git a/__tests__/scripts/translate-docs/mdx-translator.test.ts b/__tests__/scripts/translate-docs/mdx-translator.test.ts index e7e09164..e5658dee 100644 --- a/__tests__/scripts/translate-docs/mdx-translator.test.ts +++ b/__tests__/scripts/translate-docs/mdx-translator.test.ts @@ -31,6 +31,7 @@ import { translateMdxPage, } from "@/scripts/translate-docs/mdx-translator"; import type { TranslationCache } from "@/scripts/translate-docs/types"; +import { setCacheEntry } from "@/scripts/translate-docs/cache"; /** Queue ONE `end_turn` translation response; call once per expected attempt. */ function queueTranslation(text: string): void { @@ -522,6 +523,43 @@ describe("translateMdxPage validation gate", () => { expect(Object.keys(cache.translations)).toHaveLength(0); }); + // A cache entry says a page was TRANSLATED ONCE, never that the file is on + // disk now — and the two came apart in production. Translations land on an + // auto-translate PR branch; while that sits unmerged, `main` lacks the file + // and the cache still reports it done, so the page is never regenerated while + // `--update-nav` (which reads the ENGLISH tree) emits a nav entry pointing at + // it. `mintlify validate` then fails, and because the cache save sat + // downstream of that step, the day's cache was discarded — making a cache HIT + // the failing case and a full 120-minute MISS the only way to a green run. + // These two tests pin both directions of the fix. + it("re-translates a cached page whose output file is missing", async () => { + const cache = emptyCache(); + setCacheEntry(cache, REL, "de", EN_SOURCE, 10, 20); + expect(existsSync(outputPath)).toBe(false); + + queueTranslation(VALID_DE); + const result = await translateMdxPage(srcPath, "de", { docsDir, cache }); + + // Cache says done, disk says otherwise — disk wins. + expect(result.cached).toBe(false); + expect(streamMock).toHaveBeenCalledTimes(1); + expect(existsSync(outputPath)).toBe(true); + }); + + it("still skips a cached page when the output file is present", async () => { + const cache = emptyCache(); + setCacheEntry(cache, REL, "de", EN_SOURCE, 10, 20); + mkdirSync(dirname(outputPath), { recursive: true }); + writeFileSync(outputPath, VALID_DE); + + const result = await translateMdxPage(srcPath, "de", { docsDir, cache }); + + // The whole point of the cache. If this regresses, every run is a full + // re-translation and the existsSync guard has become a cache bypass. + expect(result.cached).toBe(true); + expect(streamMock).not.toHaveBeenCalled(); + }); + it("validates the sanitized, link-rewritten bytes rather than the raw model output", async () => { // Raw output has a stray doubled quote in a JSX attribute (invalid MDX); // sanitizeJsxAttributes fixes it before validation, so it passes on the diff --git a/docs/ar/agenteye/alerts.mdx b/docs/ar/agenteye/alerts.mdx index 7e2f9959..ddd5734f 100644 --- a/docs/ar/agenteye/alerts.mdx +++ b/docs/ar/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "التنبيهات" -description: "اكتشف اللحظة التي يتجاوز فيها شيء ما حدك، على القناة التي يراقبها فريقك بالفعل، بدلاً من سماعها من العميل." +description: "اكتشف اللحظة التي يتجاوز فيها شيء ما حدك، على القناة التي تراقبها فريقك بالفعل، بدلاً من سماعها من العميل." --- -اكتشف اللحظة التي يتجاوز فيها شيء ما حدك، على القناة التي يراقبها فريقك بالفعل، بدلاً من سماعها من العميل. عيّن قاعدة مرة واحدة و Failproof AI Observability تفحصها وفقاً لجدول زمني، ثم ترسل إليك تنبيهاً عبر البريد الإلكتروني أو Slack أو webhook أو مباشرة في لوحة التحكم. +اكتشف اللحظة التي يتجاوز فيها شيء ما حدك، على القناة التي تراقبها فريقك بالفعل، بدلاً من سماعها من العميل. عيّن قاعدة مرة واحدة وتحقق Failproof AI Observability من تطبيقها على جدول زمني، ثم أرسل إليك تنبيهات عبر البريد الإلكتروني أو Slack أو webhook أو مباشرة في لوحة المعلومات. -![صفحة التنبيهات: شبكة من بطاقات قواعد التنبيهات، تعرض كل منها محفزها ونافذة التقييم والقنوات وشارة الخطورة (معلومات أو تحذير أو حرج)](/agenteye/images/alerts.png) -*كل قاعدة تنبيه في نظرة واحدة: ما الذي تراقبه وعدد المرات والقنوات ومستوى الإلحاح.* +![صفحة التنبيهات: شبكة من بطاقات قواعد التنبيه، كل منها يعرض محفزها، نافذة التقييم، القنوات، وشارة الخطورة (معلومة، تحذير، أو حرجة)](/agenteye/images/alerts.png) +*كل قاعدة تنبيه في لمحة: ما الذي تراقبه، وكم مرة، وأين تُرسل التنبيهات، وما مدى الاستعجالية.* -## اعرف عن المشاكل قبل مستخدميك +## اعرف عن المشاكل قبل المستخدمين -توقف عن تحديث لوحة التحكم على أمل اكتشاف انحدار. استخدم تنبيهاً كلما كانت هناك إشارة تريد أن تسمع عنها حتى لو لم يكن أحد يراقب، واجعلها تصل إلى حيث أنت بالفعل: +توقف عن تحديث لوحة المعلومات آملاً في اكتشاف تراجع. استخدم التنبيه كلما كانت هناك إشارة تود سماعها حتى عندما لا ينظر أحد، واجعلها تصل إلى حيث أنت بالفعل: -- **البريد الإلكتروني**، لمن يجب أن يعرف. -- **Slack**، رسالة غنية بزر ينقلك مباشرة إلى الحادثة. -- **Webhook**، POST JSON لـ PagerDuty أو Opsgenie أو نقطة نهاية خاصة بك، مع توقيع اختياري حتى يتمكن المستقبل من الوثوق به. -- **داخل لوحة التحكم**، هادئة بالتصميم، عندما تكون تضبط قاعدة ولا تريد إزعاج أحد حتى الآن. +- **البريد الإلكتروني**، إلى من يجب أن يعرف. +- **Slack**، رسالة غنية مع زر ينقلك مباشرة إلى الحادثة. +- **Webhook**، طلب JSON POST لـ PagerDuty أو Opsgenie أو نقطة نهايتك الخاصة، مع توقيع اختياري حتى يتمكن المستقبل من الوثوق به. +- **في لوحة المعلومات**، صامت بالتصميم، عندما تكون تعديل قاعدة ولا تريد إزعاج أحد حالياً. -قم بإرفاق أي مزيج لقاعدة واحدة، وشدتها (معلومات أو تحذير أو حرج) تنتقل معها حتى تبدو الحالات الملحة ملحة. +قم بإرفاق أي مجموعة إلى قاعدة واحدة، وسيتم نقل درجة الخطورة (معلومة، تحذير، أو حرجة) معها حتى تبدو الحالات العاجلة عاجلة فعلاً. ## بناء القاعدة في نموذج، وليس JSON -تصف ما معنى أن يكون الشيء "معطلاً" في نموذج، و Failproof AI Observability تكتب القاعدة الأساسية لك. مواصفات JSON ليست سوى ما ينتجه هذا النموذج تحت الغطاء، حتى تتمكن من قراءتها لفهم قاعدة لكن نادراً ما تكتبها. +تصف ما تعنيه كلمة "معطل" في نموذج، و Failproof AI Observability تكتب القاعدة الأساسية لك. مواصفات JSON هي فقط ما ينتجه هذا النموذج تحت الغطاء، لذلك يمكنك قراءتها لفهم القاعدة لكنك نادراً ما تكتبها. -![نموذج التنبيه الجديد: الاسم والوصف وزر التفعيل واختيار المحفز يعرض عتبة المقياس والـ SQL المخصص ودرجة التقييم والتقييم المركب والشروط لكل حدث](/agenteye/images/alert-new.png) -*اختر محفزاً والنموذج يعدّل الحقول المناسبة؛ الحفظ يكتب القاعدة.* +![نموذج التنبيه الجديد: الاسم والوصف، مفتاح تفعيل، واختيار محفز يقدم عتبة مترية، SQL مخصص، درجة التقييم، تقييم مركب، وشروط لكل حدث](/agenteye/images/alert-new.png) +*اختر محفزاً والنموذج يبدل الحقول الصحيحة؛ الحفظ يكتب القاعدة.* -المسار السعيد سريع: سمِّه، اختر **محفز** (ما يجب مراقبته)، عيّن **العتبة والنافذة** (مدى السوء وعلى مدى كم من الوقت)، أرفق قناة واحدة على الأقل، ثم **احفظ** و**اختبر** لإرسال إخطار تركيبي وتأكيد أن كل وجهة متصلة. تحت الغطاء ينتج عن هذا مواصفات صغيرة مثل: +المسار السعيد سريع: أعطه اسماً، اختر **محفزاً** (ما الذي تراقبه)، عيّن **العتبة والنافذة** (كم السوء، على مدى كم من الوقت)، أرفق **قناة واحدة على الأقل**، ثم **احفظ** واضغط **اختبر** لإطلاق إخطار اصطناعي وتأكيد أن كل وجهة متصلة. تحت الغطاء، ينتج عن ذلك مواصفات صغيرة مثل: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -لا تقتصر على نوع إشارة واحد. اختر المحفز الذي يطابق طريقة تفكيرك حول الخلل: +أنت لا تقتصر على نوع واحد من الإشارات. اختر المحفز الذي يتطابق مع طريقة تفكيرك حول الفشل: -| المحفز | ينطلق عندما | +| المحفز | يطلق عندما | |---|---| -| **عتبة المقياس** | يتجاوز مقياس محدد مسبقاً (معدل الخطأ أو كمون p95 أو p99 أو عدد الأحداث أو الأخطاء أو إنفاق الرموز) حدك على مدى نافذة | -| **SQL مخصص** | الاستعلام المخصص للقراءة فقط يعيد صفاً أو قيمة يحسبها تتجاوز عتبة | -| **درجة التقييم** | متوسط درجة المقيّم (مثل الهلوسة) يتجاوز عتبة | -| **التقييم المركب** | عدة فحوصات درجات تجتمع مع أي أو الكل أو على الأقل منطق N، لاكتشاف انحدار يظهر فقط عبر الدرجات | -| **لكل حدث** | يصل حدث واحد مطابق: وكيل محدد أو نوع خطأ محدد أو جزء رسالة | +| **عتبة مترية** | تتجاوز مترية محددة مسبقاً (معدل الأخطاء، كمون p95 أو p99، عد الأحداث أو الأخطاء، إنفاق الرموز) خطك على مدى نافذة | +| **SQL مخصص** | يُرجع استعلامك المخصص للقراءة فقط صفاً، أو تتجاوز القيمة التي يحسبها عتبة | +| **درجة التقييم** | يتجاوز متوسط درجة المقيّم (مثل الهلوسة) عتبة | +| **تقييم مركب** | عدة فحوصات درجات تتحد بمنطق أي، الكل، أو على الأقل N، لاكتشاف تراجع يظهر فقط عبر الدرجات | +| **لكل حدث** | يصل حدث مطابق واحد: وكيل محدد، نوع خطأ محدد، أو بحث نصي في الرسالة | -تحدق بالفعل في خلل على [صفحة الأخطاء](/ar/agenteye/error-tracking)؟ كل صف هناك به زر **+ تنبيه** يفتح نفس النموذج معبأ مسبقاً لاكتشاف هذا الخلل بالضبط مرة أخرى، حتى الحادثة التي قمت بفحصها للتو تصبح الحادثة التي ستنبهك في المرة القادمة. +هل تحدق فعلاً في فشل ما على [صفحة الأخطاء](/ar/agenteye/error-tracking)؟ كل صف هناك لديه زر **+ تنبيه** يفتح هذا النموذج نفسه معبأ مسبقاً لاكتشاف ذلك الفشل بالضبط مرة أخرى، بحيث تصبح الحادثة التي قمت بتقييمها للتو هي التي ستنبهك في المرة القادمة. -**حيث تجده:** التنبيهات موجودة في `//alerts`. إنشاء وتحرير وحذف واختبار القواعد يتطلب `alerts:write`؛ `alerts:read` كافٍ للمراقبة. منتقي المستقبل يسرد أعضاء منظمتك حسب الاسم، حتى تتمكن من إنذار شخص ما دون مغادرة النموذج. +**أين تجده:** التنبيهات موجودة في `//alerts`. الإنشاء والتحرير والحذف والاختبار يحتاج **`alerts:write`**؛ `alerts:read` كافٍ للمراجعة. قائمة اختيار المتلقي تعرض أعضاء منظمتك بالاسم، لذلك يمكنك إرسال تنبيه إلى شخص دون ترك النموذج. -## أنبهني فقط عندما يكون حقيقياً +## نبهني فقط عندما يكون حقيقياً -قياس خاطئ واحد يجب ألا يوقظك. **M من N** مرشح الضوضاء يتحكم في عدد الفحوصات القليلة الأخيرة التي يجب أن تفشل قبل أن ينطلق التنبيه فعلاً. عيّنه على **3 من 5** والقاعدة تنطلق فقط بعد أن تخترق ثلاثة من آخر خمس فحوصات، حتى تتوقف الإشارة المتذبذبة عن استدعاء الذئب؛ اتركه على الافتراضي **1 من 1** لينطلق عند أول انتهاك. تختار أيضاً عدد مرات تشغيل القاعدة، من إعدادات مسبقة بـ 1 دقيقة أو 5 دقائق أو 15 دقيقة أو ساعة واحدة، مطابقة لمدى سرعة حركة الإشارة الفعلية. +قياس واحد سيء يجب ألا يوقظك. يتحكم مرشح الضوضاء **M من N** في عدد الفحوصات القليلة الأخيرة التي يجب أن تفشل قبل أن يرسل التنبيه إليك فعلاً. عيّنه على **3 من 5** والقاعدة تطلق فقط بعد اختراق ثلاثة من آخر خمسة فحوصات، لذا تتوقف الإشارة المرتجفة عن البكاء؛ اتركه في الافتراضي **1 من 1** لإطلاق عند أول اختراق. تختار أيضاً مدى سرعة تشغيل القاعدة، من إعدادات مسبقة من 1m و5m و15m و1h، مطابقة لسرعة حركة الإشارة فعلاً. -## ما يحدث عندما ينطلق تنبيه +## ما يحدث عندما يطلق التنبيه -يفتح انتهاك **حادثة** وينبه قنواتك مرة واحدة. من هناك يعترف فريقك بها ويعين مالكاً ويناقشها ويحلها، كل ذلك ضد سجل نظيف ومنسوب. لهذا سير العمل في الفحص منزل خاص به: انظر [الحوادث](/ar/agenteye/incidents). +يفتح الاختراق **حادثة** وينبه قنواتك مرة واحدة. من هناك، يعترف فريقك بها، ويعين مالكاً، يناقشونها، ويحلونها، كل ذلك مقابل سجل نظيف مسند. لهذا سير عمل الفرز بيت خاص به: راجع [الحوادث](/ar/agenteye/incidents). ## ذات صلة -- [الحوادث](/ar/agenteye/incidents): تتبع تنبيه منطلق من مفتوح إلى معترف به إلى محلول. -- [تتبع الأخطاء](/ar/agenteye/error-tracking): تجميع إخفاقات الوكيل وترقية واحد إلى تنبيه بنقرة واحدة. -- [لوحات التحكم](/ar/agenteye/dashboards): راقب اللوحات المشتركة التي تأتي منها العتبات التي تنبه عليها. -- [CLI والوكلاء](/ar/agenteye/cli-and-agents): أنشئ تنبيهات وأقرّ الحوادث من محطتك الطرفية أو أدخلها في CI. \ No newline at end of file +- [الحوادث](/ar/agenteye/incidents): تتبع التنبيه المطلق من الفتح إلى الإقرار إلى الحل. +- [تتبع الأخطاء](/ar/agenteye/error-tracking): مجموعة فشل الوكيل والترقية لأحدها إلى تنبيه بضغطة زر. +- [لوحات المعلومات](/ar/agenteye/dashboards): راقب اللوحات المشتركة التي تأتي منها العتبات التي تنبهها. +- [CLI والوكلاء](/ar/agenteye/cli-and-agents): أنشئ تنبيهات واعترف بالحوادث من الطرفية، أو أدمجها في CI. \ No newline at end of file diff --git a/docs/ar/agenteye/api-keys.mdx b/docs/ar/agenteye/api-keys.mdx index 05043f71..06ea32a0 100644 --- a/docs/ar/agenteye/api-keys.mdx +++ b/docs/ar/agenteye/api-keys.mdx @@ -1,172 +1,172 @@ --- title: "مفاتيح API" -description: "تتحكم مفاتيح API بمن وما يمكنه الوصول إلى خادم Failproof AI Observability، بحيث يمكن لأداة جمع البيانات إرسال الأحداث دون الحصول على صلاحيات القراءة أو الإدارة." +description: "تتحكم مفاتيح API في من وما يمكنه الوصول إلى خادم Failproof AI Observability، بحيث يمكن لمجمع البيانات إرسال الأحداث دون الحصول أبداً على صلاحيات القراءة أو الإدارة." --- -تتحكم مفاتيح API بمن وما يمكنه الوصول إلى خادم Failproof AI Observability، بحيث يمكن لأداة جمع البيانات إرسال الأحداث دون الحصول على صلاحيات القراءة أو الإدارة. يحمل كل مفتاح واحداً أو أكثر من الصلاحيات، وكل صلاحية تتحكم في مسارات خادم محددة؛ فأنت تمنح فقط ما تحتاجه المهمة. تنشئ معظم عمليات النشر ثلاثة أنواع من المفاتيح فقط. +تتحكم مفاتيح API في من وما يمكنه الوصول إلى خادم Failproof AI Observability، بحيث يمكن لمجمع البيانات إرسال الأحداث دون الحصول أبداً على صلاحيات القراءة أو الإدارة. يحمل كل مفتاح واحداً أو أكثر من الأذونات، وكل إذن يتحكم في مسارات خادم محددة؛ تمنح فقط ما يحتاجه المهمة. تنشئ معظم النشريات ثلاثة أنواع فقط من المفاتيح. -## المفاتيح الثلاثة التي تحتاجها معظم عمليات النشر +## المفاتيح الثلاثة التي تحتاجها معظم النشريات -| المفتاح | الصلاحيات | من يستخدمه | +| المفتاح | الأذونات | من يستخدمه | |---|---|---| -| مفتاح جامع البيانات | `events:add` | `agenteye-collector` على كل جهاز وكيل، لإرسال الأحداث. | -| مفتاح قراءة لوحة التحكم | `events:read`, `keys:read` | عامل تشغيل أو تكامل يقرأ فقط يستعلم عن البيانات دون تغييرها. | -| مفتاح إدارة التمهيد | جميع الصلاحيات | عامل التشغيل الذي يبدأ المثيل أولاً (ولوحة التحكم). يتم تغذيته من متغير البيئة `ADMIN_KEY`. راجع [مفتاح إدارة التمهيد](#bootstrap-admin-key). | +| مفتاح المجمع | `events:add` | `agenteye-collector` على كل جهاز agent، لإرسال الأحداث. | +| مفتاح قراءة لوحة المعلومات | `events:read`, `keys:read` | مشغل أو تكامل للقراءة فقط يستعلم البيانات دون تغييرها. | +| مفتاح بدء الإدارة | جميع الأذونات | المشغل الذي يبدئ النسخة أولاً (ولوحة المعلومات). محمل من متغير البيئة `ADMIN_KEY`. انظر [مفتاح بدء الإدارة](#bootstrap-admin-key). | -ابدأ هنا. استخدم قائمة الصلاحيات الكاملة أدناه فقط عندما تحتاج إلى مفتاح مخصص أقل نطاقاً. راجع أيضاً [تخطيط المفتاح الموصى به](#recommended-key-layout) و[إنشاء المفاتيح](#creating-keys). +ابدأ هنا. استخدم فهرس الأذونات الكامل أدناه فقط عندما تحتاج إلى مفتاح مخصص بنطاق أضيق. انظر أيضاً [تخطيط المفتاح الموصى به](#recommended-key-layout) و[إنشاء المفاتيح](#creating-keys). --- -## الصلاحيات +## الأذونات -يفرض الخادم قائمة ثابتة من الصلاحيات؛ تتحكم كل واحدة في مسارات HTTP محددة. يحمل **مفتاح الإدارة** جميعها؛ يحمل المفتاح ذو النطاق المحدد المجموعة الفرعية التي تمنحها عند الإنشاء. يتم رفض سلاسل الصلاحيات غير المعروفة عند إنشاء مفتاح. +يفرض الخادم فهرساً ثابتاً من الأذونات؛ كل منها يتحكم في مسارات HTTP محددة. يحمل **مفتاح الإدارة** جميعها؛ يحمل المفتاح المحدود المجموعة الفرعية التي تمنحها عند الإنشاء. يتم رفض سلاسل الأذونات غير المعروفة عند إنشاء مفتاح. -> **ملاحظة:** صلاحيتان صحيحتان مخصصتان للعاملين البشريين/لوحة التحكم فقط ولا يمكن منحهما لمفتاح API: `orgs:admin` (إدارة المثيل، وهي حصرية للعاملين) و`keys:update`. يتم رفض الطلب إلى `POST /keys` أو `PATCH /keys/:id` الذي يحاول منح أي منهما برمز HTTP 422. راجع صف `keys:update` أدناه لمعرفة السبب في أن مفتاح الحامل قد ينشئ مفاتيح لكن لا يمكنه تعديلها. +> **ملاحظة:** هناك إذنان صحيحان فقط مخصصان للإنسان/لوحة المعلومات ولا يمكن منحهما لمفتاح API: `orgs:admin` (إدارة النسخة، والتي تقتصر على المشغل فقط) و`keys:update`. يتم رفض الطلب إلى `POST /keys` أو `PATCH /keys/:id` الذي يحاول منح أي منهما برمز HTTP 422. انظر صف `keys:update` أدناه لمعرفة سبب السماح لمفتاح التوكن بإنشاء مفاتيح ولكن عدم تحريرها أبداً. -### بث الأحداث والاستعلام عنها +### استقبال الأحداث والاستعلام عنها -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `events:add` | `POST /events` | بث دفعات من الأحداث من جامع البيانات. الصلاحية الوحيدة التي يحتاجها جامع البيانات. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | الاستعلام عن الأحداث، وإدراج البيئات المعروفة، وإدراج معرفات النموذج المرئية في البيانات (تستخدمها عرض النماذج ومرشحات النموذج)، وحساب إجمالي الكمون الذي يقوي خريطة الحرارة / نطاق النسب المئوية، وتصدير جلسة عمل كـ JSONL. تكون نقاط نهاية facet شريط التصفية المشترك `GET /events/environments` و`GET /events/agent_ids` قابلة للوصول **باستخدام** `events:read` **أو** `evaluations:read`، بحيث تعيد صفحة الجلسات (المحدودة `evaluations:read`) استخدام نفس facet لكل منظمة. `GET /events/models` ليست واحدة منها: تتطلب `events:read`، لذا فإن المبدأ الذي يحتفظ بـ `evaluations:read` فقط يحصل على 403 منها. | +| `events:add` | `POST /events` | استقبال دفعات من الأحداث من مجمع. الإذن الوحيد الذي يحتاجه المجمع. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | الاستعلام عن الأحداث، وسرد البيئات المعروفة، وسرد معرّفات النماذج المشاهدة في البيانات (المستخدمة بواسطة عرض النماذج ومرشحات النموذج)، وحساب مجموع الكمون الذي يشغل خريطة الحرارة / نطاق النسبة المئوية، وتصدير جلسة بصيغة JSONL. نقاط نهاية facet شريط المرشح المشترك `GET /events/environments` و`GET /events/agent_ids` قابلة للوصول بـ **إما** `events:read` **أو** `evaluations:read`، لذا تعيد صفحة الجلسات (المحدودة `evaluations:read`) استخدام نفس facet لكل منظمة. `GET /events/models` ليست واحدة منها: تتطلب `events:read`، لذا الأصحاب الذين يحملون فقط `evaluations:read` يحصلون على 403 منها. | ### الجلسات والتقييمات -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | إدراج الجلسات، وقراءة نتائج التقييم، وصحة التقييم المجمعة التي تستخدمها لوحات التحكم، وحالة قائمة انتظار عمل التقييم. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | إعادة تقييم يدوية لجلسة منتهية. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | سرد الجلسات، وقراءة نتائج التقييم، وصحة التقييم المجمعة المستخدمة بواسطة لوحات المعلومات، وحالة قائمة انتظار عامل وظائف التقييم. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | إدراج تقييم إعادة يدوي لجلسة منتهية. | -### لوحات التحكم +### لوحات المعلومات -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | إدراج لوحات التحكم، وتحميل واحدة، وقراءة بلاطاتها. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | إنشاء وتعديل لوحات التحكم، وإضافة / تعديل / إزالة البلاطات، وإعادة ترتيب شبكة البلاطات. | -| `dashboards:delete` | `DELETE /dashboards/:id` | حذف لوحة تحكم بالكامل (حذف على مستوى البلاطة موجود تحت `dashboards:write`). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | سرد لوحات المعلومات، وتحميل واحدة، وقراءة مراطيها. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | إنشاء وتحرير لوحات المعلومات، إضافة / تحرير / إزالة المراطي، وإعادة ترتيب شبكة المراطي. | +| `dashboards:delete` | `DELETE /dashboards/:id` | حذف لوحة معلومات بأكملها (حذف مستوى المرطى يندرج تحت `dashboards:write`). | ### الاستعلامات المحفوظة (محرر SQL) -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | إدراج الاستعلامات المحفوظة، وتحميل واحد، وفحص المخطط المقروء فقط الذي يستهدفه محرر الاستعلام. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | إنشاء وتعديل الاستعلامات المحفوظة. لا يزال SQL يتم توجيهه من خلال نفس الدور المقروء فقط والتحقق من SQL المحمي كما هو الحال في استدعاء `queries:run`. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | سرد الاستعلامات المحفوظة، وتحميل واحدة، وفحص مخطط القراءة فقط الذي يستهدفه المحرر. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | إنشاء وتحرير الاستعلامات المحفوظة. SQL لا يزال يتم توجيهه عبر نفس دور القراءة فقط والفحوصات المحمية مثل استدعاء `queries:run`. | | `queries:delete` | `DELETE /queries/:id` | حذف استعلام محفوظ. | -| `queries:run` | `POST /queries/run` | تنفيذ استعلامات SQL محفوظة أو مرتجلة ضد الدور المقروء فقط الذي يستخدمه محرر الاستعلام. | +| `queries:run` | `POST /queries/run` | تنفيذ SQL المحفوظ أو المخصص ضد دور القراءة فقط المستخدم بواسطة المحرر. | -### مساعد ذكي +### مساعد AI -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | التحدث إلى المساعد الذكي وإدارة محادثاتك الخاصة (الخاصة). مطلوب على **المستخدم** لرؤية لوحة المساعد؛ مفتاح المساعد نفسه هو `dashboard-assistant` ويتم تغذيته بشكل منفصل (انظر أدناه). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | التحدث مع مساعد AI وإدارة محادثاتك الخاصة (الخاصة). مطلوب على **المستخدم** لرؤية حوض المساعد؛ مفتاح المساعد نفسه هو `dashboard-assistant` ويتم تحميله بشكل منفصل (انظر أدناه). | ### مفاتيح API -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `keys:create` | `POST /keys` | إنشاء مفتاح API جديد محدد النطاق. لا يمنح **تعديل صلاحيات مفتاح موجود (هذا هو `keys:update`). | -| `keys:read` | `GET /keys` | إدراج المفاتيح الموجودة. لا يتم إرجاع الأسرار من قبل هذا الجانب. | -| `keys:update` | `PATCH /keys/:id` | تعديل صلاحيات مفتاح موجود. صلاحية **حصرية للعاملين البشريين/لوحة التحكم**؛ لا يمكن تعيينها لمفتاح API (قد يقوم مفتاح الحامل بإنشاء مفاتيح لكن لا يمكنه تعديلها). | -| `keys:disable` | `POST /keys/:id/disable` | إلغاء مفتاح. لا يمكن تعطيل المفاتيح المحمية (`admin`, `dashboard-assistant`); قم بتدويرها عبر متغير البيئة + إعادة تشغيل. | -| `keys:regenerate` | `POST /keys/:id/regenerate` | تدوير سر المفتاح. لا يمكن إعادة إنشاء المفاتيح المحمية من خلال هذا الجانب. | +| `keys:create` | `POST /keys` | إنشاء مفتاح API محدود جديد. **لا** يمنح تحرير أذونات مفتاح موجود (ذلك هو `keys:update`). | +| `keys:read` | `GET /keys` | سرد المفاتيح الموجودة. لا يتم إرجاع الأسرار من قبل هذا الطلب أبداً. | +| `keys:update` | `PATCH /keys/:id` | تحرير أذونات مفتاح موجود. إذن **إنسان/لوحة معلومات فقط**؛ لا يمكن تعيينه لمفتاح API (قد يقوم مفتاح التوكن بإنشاء مفاتيح ولكن لا يحررها أبداً). | +| `keys:disable` | `POST /keys/:id/disable` | إلغاء مفتاح. لا يمكن تعطيل المفاتيح المحمية (`admin`, `dashboard-assistant`)؛ قم بتدويرها عبر متغير البيئة + إعادة التشغيل. | +| `keys:regenerate` | `POST /keys/:id/regenerate` | تدوير سر المفتاح. لا يمكن إعادة إنشاء المفاتيح المحمية من خلال هذا المسار. | -### مستخدمو لوحة التحكم +### مستخدمو لوحة المعلومات -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | دعوة مستخدم لوحة تحكم جديد (إصدار رمز بريد + رمز لمرة واحدة (OTP) تسجيل دخول) وقراءة مجموعة الصلاحيات الافتراضية المكونة بلوحة التحكم المستخدمة لتمرير نموذج الدعوة. | -| `users:read` | `GET /users`, `GET /users/:id` | إدراج المستخدمين وتحميل سجل مستخدم واحد. | -| `users:update` | `PUT /users/:id` | تعديل صلاحيات المستخدم. تُرسل التحديثات رسالة بريد تغيير الصلاحيات للمستخدم المتأثر وتصبح سارية عند طلبهم التالي؛ لا يلزم إعادة تسجيل الدخول. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | تعطيل مستخدم (إلغاء جلساته على الفور) وإعادة تفعيل مستخدم تم تعطيله سابقاً. | +| `users:create` | `POST /users`, `GET /users/defaults` | دعوة مستخدم لوحة معلومات جديد (إصدار بريد إلكتروني + تسجيل دخول بكلمة مرور لمرة واحدة (OTP)) وقراءة مجموعة الأذونات الافتراضية المكونة على لوحة المعلومات المستخدمة لتحديد نموذج نموذج الدعوة. | +| `users:read` | `GET /users`, `GET /users/:id` | سرد المستخدمين وتحميل سجل مستخدم واحد. | +| `users:update` | `PUT /users/:id` | تحرير أذونات المستخدم. تقوم التحديثات بإرسال بريد إلكتروني لتغيير الأذونات إلى المستخدم المتأثر وتصبح فعالة عند طلبهم التالي؛ لا يلزم إعادة تسجيل الدخول. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | تعطيل مستخدم (إلغاء جلساتهم على الفور) وإعادة تفعيل مستخدم معطل سابقاً. | -تدعم هذه الصلاحيات صفحة لوحة التحكم **المستخدمون**، حيث يتم عرض النطاقات الممنوحة لكل عضو كرقائق: +تدعم هذه الأذونات صفحة لوحة المعلومات **المستخدمون**، حيث يتم عرض الأذونات الممنوحة لكل عضو كرقائق: -![صفحة المستخدمون: بطاقة لكل مستخدم لوحة تحكم مع بريده الإلكتروني والصلاحيات الممنوحة والتحكم في التعديل/التعطيل](/agenteye/images/users.png) +![صفحة المستخدمين: بطاقة لكل مستخدم لوحة معلومات مع بريده الإلكتروني والأذونات الممنوحة وعناصر التحكم في التحرير/التعطيل](/agenteye/images/users.png) -### الإعدادات التشغيلية +### إعدادات التشغيل -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | عرض الإعدادات التشغيلية المدارة بلوحة التحكم وبيانات التعريف الخاصة بها؛ إدراج تجاوزات نافذة السياق حسب النموذج؛ وحل النافذة الفعالة للنموذج. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | تعديل الإعدادات التشغيلية وإضافة أو تغيير أو إزالة تجاوزات نافذة السياق حسب النموذج. تؤثر التغييرات على الأحداث الجديدة دون إعادة تشغيل الخادم. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | عرض إعدادات التشغيل المدارة من لوحة المعلومات وبيانات وصفها؛ سرد تجاوزات نافذة السياق لكل نموذج؛ وحل النافذة الفعالة للنموذج. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | تحرير إعدادات التشغيل وإضافة أو تغيير أو إزالة تجاوزات نافذة السياق لكل نموذج. تؤثر التغييرات على الأحداث الجديدة دون إعادة تشغيل الخادم. | -![صفحة الإعدادات: إعدادات تشغيلية مدارة بلوحة التحكم مثل عمليات تسجيل الدخول المسموحة وأعمار الجلسات / OTP، قابلة للتعديل دون إعادة تشغيل](/agenteye/images/settings.png) +![صفحة الإعدادات: إعدادات التشغيل المدارة من لوحة المعلومات مثل عمليات تسجيل الدخول المسموحة وأعمار الجلسة/OTP، قابلة للتحرير دون إعادة تشغيل](/agenteye/images/settings.png) ### التنبيهات والحوادث -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | عرض تعريفات التنبيهات المكونة. | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | إنشاء وتعديل وحذف وتشغيل تنبيهات تجريبية. | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | عرض الحوادث وأثر الفحص الخاص بها. | -| `incidents:write` | `POST /alerts/:id/incidents` | فتح حادثة يدوية ضد تنبيه موجود. | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | الإقرار بالحوادث وتعيينها وحلها والتعليق عليها. | +| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | عرض تعاريف التنبيهات المكونة. | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | إنشاء وتحرير وحذف واختبار إطلاق تعاريف التنبيهات. | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | عرض الحوادث ومسار التصنيف الخاص بها. | +| `incidents:write` | `POST /alerts/:id/incidents` | فتح حادثة يدوياً ضد تنبيه موجود. | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | الاعتراف بالحوادث وتعيينها وحلها والتعليق عليها. | ### التدقيقات -| الصلاحية | مسارات HTTP | ما تسمح به | +| الإذن | مسارات HTTP | ما يسمح به | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | عرض تعريفات التدقيق وسجل التشغيل والنتائج. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | إنشاء وتعديل وحذف وتشغيل التدقيقات؛ فحص النتائج (إقرار / كتم صوت / رفض / حل / إعادة فتح / تعيين). | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | عرض تعاريف التدقيق وسجل التشغيل والنتائج. | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | إنشاء وتحرير وحذف وتشغيل التدقيقات؛ تصنيف النتائج (الاعتراف / كتم الصوت / رفض / حل / إعادة فتح / تعيين). | -> **ملاحظة:** لإعطاء مفتاح سطح التدقيق، امنح `audits:*` بشكل صريح. راجع [ملاحظات الترقية والتوافق للخلف](#upgrade-and-backward-compatibility-notes) لمعرفة كيف تمت ترقية المستفيدين الموجودين عند شحن التدقيقات. +> **ملاحظة:** لمنح مفتاح سطح التدقيق، امنح `audits:*` له بوضوح. انظر [ملاحظات الترقية والتوافقية العكسية](#upgrade-and-backward-compatibility-notes) لمعرفة كيف تم نقل المنحين الموجودين عند شحن التدقيقات. -> نقطة نهاية منتقي المستقبل `GET /alerts/recipients` (التي تسرد رسائل بريد الأعضاء التي يمكن لمحرر التنبيهات إخطارهم) قابلة للوصول من قبل صاحب **إما** `alerts:read` **أو** `alerts:write`، لذا يمكن لمحررات التنبيهات ملء المنتقي دون منح `users:read`. +> نقطة نهاية منتقي المستقبل `GET /alerts/recipients` (التي تسرد رسائل البريد الإلكتروني للأعضاء التي يمكن لمحرر التنبيه إخطارهم) قابلة للوصول من قبل حامل **إما** `alerts:read` **أو** `alerts:write`، لذا يمكن لمحررات التنبيه ملء المنتقي دون الحصول على `users:read`. -> مشاهد لوحة التحكم يحتاج **كل من** `dashboards:read` (لتحميل العروض المحفوظة) و`evaluations:read` (يتم حساب مقاييس الصحة من بيانات التقييم). امنح `dashboards:write` للسماح للمستخدم بإنشاء أو تعديل لوحات التحكم، و`dashboards:delete` لإزالتها. +> يحتاج مشاهد لوحات المعلومات إلى **كلا** `dashboards:read` (لتحميل العروض المحفوظة) و`evaluations:read` (يتم حساب مقاييس الصحة من بيانات التقييم). امنح `dashboards:write` للسماح للمستخدم بإنشاء أو تحرير لوحات المعلومات، و`dashboards:delete` لإزالتها. -> `/health` و`/auth/*` (طلب OTP، التحقق من OTP، فحص الجلسة، تسجيل الخروج) غير معاثة بالتصميم؛ إنها تدفق تسجيل الدخول واختبار الحيوية. `GET /access-granters` يتطلب مفتاحاً صحيحاً لكن لا توجد صلاحية محددة، بحيث يمكن لأي مستخدم مسجل دخول أن يرى الإداريين الذين يجب الاتصال بهم بخصوص تغييرات الوصول. +> `/health` و `/auth/*` (طلب OTP، التحقق من OTP، فحص الجلسة، تسجيل الخروج) غير مصرح بها بالتصميم؛ إنها تدفق تسجيل الدخول ومسبار الحياة. `GET /access-granters` يتطلب مفتاح صحيح ولكن بدون إذن محدد، لذا يمكن لأي مستخدم مسجل دخول أن يرى أي مسؤولين يتصل بهم حول تغييرات الوصول. --- -## مجموعات الصلاحيات +## مجموعات الأذونات -تتيح لك مجموعات الصلاحيات تطبيق دور محدد اسم بدلاً من انتقاء رموز فردية يدوياً في كل مرة. بدلاً من تحديد عشرات الصلاحيات واحدة تلو الأخرى لكل مستخدم جديد لوحة تحكم أو مفتاح API، تختار مجموعة، ويحمل كل شخص معين لها منحة متسقة وقابلة للمراجعة. يؤدي تعديل مجموعة مخصصة إلى إعادة تطبيق المنحة الجديدة على كل مستخدم معين لها بالفعل، بحيث يكون تغيير الدور تعديلاً واحداً بدلاً من مسح عبر كل عضو. +تتيح لك مجموعات الأذونات تطبيق دور مسمى بدلاً من اختيار التوكنات الفردية يدوياً في كل مرة. بدلاً من اختيار عشرات الأذونات واحدة تلو الأخرى لكل مستخدم لوحة معلومات جديد أو مفتاح API، تختار مجموعة، ويحمل الجميع المعينون لها منحة متسقة وقابلة للمراجعة. يعيد تحرير مجموعة مخصصة تطبيق المنحة الجديدة على كل مستخدم معين لها بالفعل، لذا تغيير الدور هو تحرير واحد وليس مسح عبر كل عضو. -يتم تغذية كل منظمة بثلاث مجموعات مدمجة: +يتم تحديد كل منظمة بثلاث مجموعات مدمجة: -| المجموعة | الصلاحيات | المقصود ل | +| المجموعة | الأذونات | المقصود من أجل | |---|---|---| -| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | وصول العرض فقط عبر كل سطح تشغيلي. | -| `standard` | كل شيء في `read-only`، بالإضافة إلى `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | قراءة فقط بالإضافة إلى إجراءات في الوقت المناسب اليومية: تشغيل الاستعلامات وإعادة تقييم الجلسات والإقرار بالحوادث واستخدام المساعد الذكي. | -| `admin` | كل صلاحية قابلة للتعيين | التحكم الكامل بالمنظمة. | +| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | الوصول للعرض فقط عبر كل سطح تشغيل. | +| `standard` | كل شيء في `read-only`، بالإضافة إلى `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | القراءة فقط بالإضافة إلى إجراءات على المدقق اليومية: تشغيل الاستعلامات، إعادة تقييم الجلسات، الاعتراف بالحوادث، واستخدام مساعد AI. | +| `admin` | كل إذن قابل للتعيين | التحكم الكامل في المنظمة. | -المجموعات المدمجة الثلاث **غير قابلة للتغيير**؛ أسماؤها تعني دائماً نفس الشيء، لذا فإن `read-only` و`standard` و`admin` آمنة للرجوع إليها في السياسة والتمهيد. يمكن لعامل التشغيل إنشاء **مجموعات مخصصة** إضافية لنمذجة أدوار محددة لمنظمتك (على سبيل المثال، دور "مؤلف لوحة التحكم" أو دور "جامع البيانات فقط"). +المجموعات الثلاث المدمجة **غير قابلة للتغيير**؛ أسماؤها تعني دائماً نفس الشيء، لذا `read-only` و`standard` و`admin` آمنة للإشارة إليها في السياسة والإعداد. يمكن لمشغل إنشاء **مجموعات مخصصة** إضافية لنمذجة أدوار محددة لمنظمتك (على سبيل المثال، دور مؤلف لوحة معلومات أو دور مجمع فقط). -يتم عرض المجموعات في لوحة التحكم وإدارتها عبر API في `GET /permission-sets` (الإدراج، المحدود بـ `users:read`) و`POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (إنشاء وتعديل وحذف مجموعة مخصصة، المحدودة بـ `settings:write`). يتم رفض حذف أو تعديل مجموعة مدمجة. +يتم عرض المجموعات في لوحة المعلومات والإدارة عبر API في `GET /permission-sets` (القائمة، المحدودة بـ `users:read`) و`POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (إنشاء وتحرير وحذف مجموعة مخصصة، المحدودة بـ `settings:write`). يتم رفض حذف أو تحرير مجموعة مدمجة. عضوية المجموعة هي ما يدعم ميزتين أخريين: -- **`DEFAULT_USER_PERMISSIONS`** (المنحة المحددة مسبقاً عندما يفتح المسؤول **+ مستخدم جديد**) تقتصر على مجموعة `standard`. -- **الحد `--set`** على `agenteye-orgctl` (إدارة أعضاء المشغل) يبدأ عضواً من مجموعة محددة، والتي يمكنك بعد ذلك ضبطها بدقة باستخدام `--add` / `--remove`. +- **`DEFAULT_USER_PERMISSIONS`** (المنحة المحددة مسبقاً عند فتح المشغل **+ مستخدم جديد**) تفترض مجموعة `standard`. +- **علامة `--set`** على `agenteye-orgctl` (إدارة عضو المشغل) تبدأ عضواً من مجموعة مسماة، والتي يمكنك بعد ذلك الضبط الدقيق باستخدام `--add` / `--remove`. -> **ملاحظة:** عندما تتضمن مجموعة صلاحية غير قابلة لتعيين المفاتيح (على سبيل المثال مجموعة مخصصة تحمل `keys:update`)، يسقط تغذية مفتاح من تلك المجموعة الرموز غير القابلة للتعيين؛ سيتم رفض الخادم المفتاح برمز HTTP 422. مستخدمو لوحة التحكم ليسوا خاضعين لهذا القيد. +> **ملاحظة:** عندما تتضمن مجموعة إذن غير قابل للتعيين للمفتاح (على سبيل المثال مجموعة مخصصة تحمل `keys:update`)، فإن تحديد مفتاح من تلك المجموعة يسقط التوكنات غير القابلة للتعيين؛ وإلا سيرفض الخادم المفتاح برمز HTTP 422. مستخدمو لوحة المعلومات ليسوا خاضعين لهذا التقييد. --- -## مفتاح إدارة التمهيد +## مفتاح بدء الإدارة -مفتاح الإدارة هو بيانات اعتماد جذر واحدة تسمح لعامل التشغيل بإحضار الوصول من لا شيء: باستخدامه يمكنك صك كل مفتاح محدود النطاق آخر، ودعوة أول مستخدمي لوحة تحكم، وتكوين المثيل قبل وجود أي مفتاح آخر. إنه المفتاح الوحيد الذي لا تقوم بإنشاؤه من خلال مفاتيح API؛ يتم توفيره من البيئة بحيث يكون الخادم قابلاً للوصول عند بدء التشغيل الأول. +مفتاح الإدارة هو بيانات الاعتماد الجذرية الوحيدة التي تسمح للمشغل بإحضار الوصول من لا شيء: يمكنك صك كل مفتاح محدود آخر، وعرض دعوة لأول مستخدمي لوحة المعلومات، وتكوين النسخة قبل أن يكون أي مفتاح آخر موجوداً. إنه المفتاح الوحيد الذي لا تنشئه من خلال API للمفاتيح؛ يتم توفيره من البيئة بحيث يكون الخادم قابلاً للوصول عند الإقلاع الأول. -اضبط متغير البيئة `ADMIN_KEY` على الخادم. في كل بدء تشغيل، يقوم الخادم بـ upsert هذه القيمة كمفتاح إدارة مع جميع الصلاحيات. +عيّن متغير البيئة `ADMIN_KEY` على الخادم. عند كل بدء تشغيل، يقوم الخادم بـ upsert هذه القيمة كمفتاح إدارة مع جميع الأذونات. -للتدوير: غيّر `ADMIN_KEY` إلى سر جديد وأعد تشغيل الخادم. +لتدوير: غيّر `ADMIN_KEY` إلى سر جديد وأعد تشغيل الخادم. --- ## نطاق المنظمة -**يتم إنشاء المنظمات وإدارتها خارج النطاق من قبل عامل التشغيل، وليس من خلال API المفاتيح هذا.** دورة حياة المنظمة والعضو (إنشاء / إعادة تسمية / حذف / تنظيف منظمة؛ إضافة / تحديث / إزالة عضو) يتم بـ **`agenteye-orgctl`** CLI؛ لا توجد واجهة HTTP API أو زر لوحة تحكم لذلك. ما لم يتغير: **يتم سك مفاتيح API لكل منظمة في لوحة التحكم (أو عبر API المفاتيح هذا)** من قبل أعضاء المنظمة. +**يتم إنشاء المنظمات وإدارتها خارج نطاق هذا API للمفاتيح من قبل مشغل، وليس من خلاله.** دورة حياة المنظمة والعضو (إنشاء / إعادة تسمية / حذف / مسح منظمة؛ إضافة / تحديث / إزالة عضو) يتم باستخدام CLI **`agenteye-orgctl`**؛ لا توجد واجهة HTTP API أو زر لوحة معلومات لذلك. ما *لم يتغير*: **مفاتيح API لكل منظمة يتم سكها في لوحة المعلومات (أو عبر هذا API للمفاتيح)** من قبل أعضاء المنظمة. -في نشر متعدد المنظمات، يملك كل مفتاح ينشئه عضو المنظمة (من خلال API المفاتيح هذا أو صفحة لوحة التحكم **المفاتيح**) **منظمة واحدة** ولا يمكنه أبداً قراءة أو كتابة بيانات تلك المنظمة فقط؛ يتم وضع الختم على المنظمة على المفتاح عند الإنشاء وتطبيقه على كل طلب. الاستثناء الوحيد هو المفاتيح الاستهلاكية الاثنان: مفتاح `admin` (المحدثة من `ADMIN_KEY`) ومفتاح `dashboard-assistant` (المحدثة من `AGENT_API_KEY`) هما **نطاق المثيل** (لا يحملان أي منظمة). تتحقق لوحة التحكم مع مفتاح `admin` بحيث يمكنها توكيل الطلبات لكل منظمة نيابة عن الأعضاء المسجلين. لا تحتاج عمليات النشر للتأجير الواحد إلى التفكير في هذا؛ جميع المفاتيح تابعة للمنظمة المدمجة `default`. +في نشر متعدد المنظمات، كل مفتاح ينشئه عضو منظمة (من خلال هذا API للمفاتيح أو صفحة لوحة المعلومات **المفاتيح**) ينتمي إلى **منظمة واحدة** ويمكنه فقط قراءة أو كتابة بيانات تلك المنظمة؛ يتم ختم المنظمة على المفتاح عند الإنشاء وفرضها عند كل طلب. الاستثناء الوحيد هو المفتاحان الأساسيان: مفتاح `admin` (محمل من `ADMIN_KEY`) ومفتاح `dashboard-assistant` (محمل من `AGENT_API_KEY`) هما **ذات نطاق النسخة** (لا يحملان منظمة). تتحقق لوحة المعلومات من خلال مفتاح `admin` بحيث يمكنها عكس الطلبات لكل منظمة نيابة عن الأعضاء المسجلين. لا تحتاج النشريات ذات المستأجر الواحد إلى التفكير في هذا؛ تنتمي جميع المفاتيح إلى منظمة `default` المدمجة. --- ## إنشاء المفاتيح -استخدم مفتاح الإدارة (أو أي مفتاح به صلاحية `keys:create`) لإنشاء مفاتيح محدودة النطاق إضافية. +استخدم مفتاح الإدارة (أو أي مفتاح بـ إذن `keys:create`) لإنشاء مفاتيح محدودة إضافية. -### مفتاح جامع البيانات (البث فقط) +### مفتاح المجمع (الاستقبال فقط) ```bash curl -s -X POST http://your-server/keys \ @@ -179,7 +179,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### مفتاح لوحة التحكم (قراءة فقط) +### مفتاح لوحة المعلومات (قراءة فقط) ```bash curl -s -X POST http://your-server/keys \ @@ -192,7 +192,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -عند إنشاء مفتاح عبر HTTP API، تقدم قيمة `key` بنفسك؛ اختر سراً قوياً وخزّنه بأمان. (لوحة التحكم تعمل بالطريقة الأخرى: فهي تنتج سراً قوياً لك وتعرضه مرة واحدة عند الإنشاء؛ انظر [إدارة المفاتيح في لوحة التحكم](#key-management-in-the-dashboard).) يؤكد الرد أنه تم إنشاء المفتاح: +عند إنشاء مفتاح عبر HTTP API، تقدم قيمة `key` بنفسك؛ اختر سراً قوياً وخزنه بشكل آمن. (تعمل لوحة المعلومات بطريقة أخرى: تولد سراً قوياً لك وتعرضه مرة واحدة عند الإنشاء؛ انظر [إدارة المفاتيح في لوحة المعلومات](#key-management-in-the-dashboard).) يؤكد الرد أن المفتاح تم إنشاؤه: ```json { @@ -205,20 +205,20 @@ curl -s -X POST http://your-server/keys \ --- -## إدراج المفاتيح +## قائمة المفاتيح ```bash curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -لا يتم إرجاع أسرار المفاتيح في استجابات الإدراج، فقط المعرفات والأسماء والصلاحيات. +لا يتم إرجاع أسرار المفاتيح في ردود القائمة، فقط المعرّفات والأسماء والأذونات. --- -## تعطيل مفتاح +## تعطيل المفتاح -يؤدي التعطيل إلى إلغاء الوصول على الفور دون حذف سجل المفتاح. +يلغي التعطيل الوصول على الفور دون حذف سجل المفتاح. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -229,51 +229,51 @@ curl -s -X POST http://your-server/keys//disable \ ## إعادة إنشاء مفتاح -ينتج سراً جديداً لمفتاح موجود. يتم إلغاء السر القديم على الفور. +ينشئ سراً جديداً لمفتاح موجود. يتم إلغاء السر القديم على الفور. ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -تتضمن الاستجابة السر الجديد بنص عادي، **معروض مرة واحدة فقط**. +يتضمن الرد السر النصي الجديد، **معروض مرة واحدة فقط**. --- -## إدارة المفاتيح في لوحة التحكم +## إدارة المفاتيح في لوحة المعلومات -توفر صفحة **المفاتيح** في لوحة التحكم واجهة مستخدم لجميع العمليات المذكورة أعلاه. تحتاج مفتاح به صلاحية `keys:read` لعرض القائمة، و`keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` لإجراءات الإنشاء / التعديل / التعطيل / إعادة الإنشاء على التوالي. يختلف تعديل صلاحيات المفتاح (`keys:update`) عن إنشاء واحد (`keys:create`)، بحيث يمكنك منح عامل تشغيل القدرة على سك مفاتيح دون القدرة على إعادة تحديد نطاق الموجودة، أو العكس. يغطي مفتاح الإدارة كل هذه. +توفر صفحة **المفاتيح** في لوحة المعلومات واجهة مستخدم لجميع العمليات أعلاه. تحتاج إلى مفتاح بـ إذن `keys:read` لعرض القائمة، و`keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` لإجراءات الإنشاء / التحرير / التعطيل / إعادة الإنشاء على التوالي. تحرير أذونات المفتاح (`keys:update`) منفصل عن إنشاء واحد (`keys:create`)، لذا يمكنك منح مشغل القدرة على سك المفاتيح دون القدرة على إعادة نطاق الأذونات الموجودة، أو العكس. مفتاح الإدارة يغطي كل هذه. -عند إنشاء مفتاح من لوحة التحكم لا تقدم السر؛ تنتج لوحة التحكم سراً قوياً لك وتعرضه **مرة واحدة** عند الإنشاء. انسخه فوراً وخزّنه بأمان؛ لا يتم عرضه أبداً مرة أخرى، تماماً كما هو الحال مع إعادة الإنشاء. لا يزال بإمكانك انتقاء صلاحيات المفتاح مباشرة، أو تغذيتها من مجموعة صلاحيات (انظر أدناه). +عند إنشاء مفتاح من لوحة المعلومات، لا توفر السر؛ تولد لوحة المعلومات سراً قوياً لك وتعرضه **مرة واحدة** عند الإنشاء. انسخه على الفور وخزنه بشكل آمن؛ لا يتم عرضه أبداً مرة أخرى، تماماً كما هو الحال مع إعادة إنشاء. يمكنك بعد ذلك اختيار أذونات المفتاح مباشرة، أو تحديدها من مجموعة أذونات (انظر أدناه). -![صفحة مفاتيح API: بطاقة لكل مفتاح توضح اسمه والصلاحيات الممنوحة ووقت الإنشاء، مع إجراءات إعادة الإنشاء والتعطيل؛ يتم وضع علامة على المفاتيح المحمية مثل `admin`](/agenteye/images/api-keys.png) +![صفحة مفاتيح API: بطاقة لكل مفتاح تعرض اسمه والأذونات الممنوحة ووقت الإنشاء، مع إجراءات إعادة إنشاء وتعطيل؛ المفاتيح المحمية مثل `admin` مميزة](/agenteye/images/api-keys.png) --- ## تخطيط المفتاح الموصى به -| المفتاح | الصلاحيات | يستخدمه | +| المفتاح | الأذونات | يستخدمه | |---|---|---| -| `admin` (التمهيد عبر متغير بيئة `ADMIN_KEY`) | الكل | العمليات / الإعداد، ولوحة التحكم (المصادقة باستخدام `ADMIN_KEY`، توكيل طلبات المستخدم مع فحوصات الصلاحية) | -| مفتاح جامع البيانات لكل مضيف | `events:add` | جامع البيانات على كل جهاز وكيل | -| `dashboard-assistant` (التمهيد عبر متغير بيئة `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | المساعد الذكي، المحدثة تلقائياً، **محمي**؛ لا يمكن تعديله من خلال API | -| مفتاح قياس مساعد (اختياري) | `events:add` | قياس ذاتي للمساعد الذكي، إن تم تفعيله | +| `admin` (بدء عبر متغير البيئة `ADMIN_KEY`) | الكل | Ops/الإعداد، ولوحة المعلومات (المصادقة مع `ADMIN_KEY`، عكس طلبات المستخدم مع فحوصات الأذونات) | +| مفتاح المجمع لكل مضيف | `events:add` | المجمع على كل جهاز agent | +| `dashboard-assistant` (بدء عبر متغير البيئة `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | مساعد AI، محمل تلقائياً، **محمي**؛ لا يمكن تحريره من خلال API | +| مفتاح التلمترية للمساعد (اختياري) | `events:add` | آلية قياس المساعد الذاتية، إن كانت مفعلة | -> **ملاحظة:** يتم **تغذية مفتاح المساعد تلقائياً** من قبل الخادم من متغير بيئة `AGENT_API_KEY` (نفس السر الذي يقدمه الوكيل باسم `AGENTEYE_API_KEY`); لا يوجد خطوة سك مفاتيح يدويّة ولا مفتاح إدارة متورط. تم إصلاح صلاحياته في كود المصدر بحيث لا يمكن توسيع النطاق من خلال سوء التكوين: قراءة عبر الأحداث / التقييمات / لوحات التحكم، بالإضافة إلى dashboards-write و queries-read / write / run لتدفق الإنشاء من قبل استخدام "اطلب من AI كتابة استعلام". لا يزال كل SQL يمر عبر نفس الدور المقروء فقط والمسار SQL المحمي كما هو الحال مع الاستعلام المكتوب من قبل المستخدم، لذا فإن هذا يوسع سطح الإنشاء، وليس سطح البيانات؛ تبقى العمليات المدمّرة (`queries:delete`, `dashboards:delete`) عن قصد بعيداً عن مفتاح المساعد. مثل مفتاح `admin`، فهو **محمي**: لا يمكن تعطيله أو إعادة إنشاؤه من خلال API المفاتيح، فقط تدويره بتغيير `AGENT_API_KEY` وإعادة تشغيل. مستخدمو لوحة التحكم **بالإضافة إلى** يحتاجون إلى صلاحية `agent:use` لرؤية واستخدام المساعد. إذا قمت بتفعيل قياس ذاتي، امنح المساعد مفتاحاً منفصلاً `events:add` فقط. +> **ملاحظة:** مفتاح المساعد **محمل تلقائياً** من قبل الخادم من متغير البيئة `AGENT_API_KEY` (نفس السر الذي يقدمه agent كـ `AGENTEYE_API_KEY`); لا توجد خطوة صك مفتاح يدوية ولا مفتاح إدارة متضمن. تم إصلاح أذوناته في كود المصدر لذا لا يمكن توسيع النطاق من خلال سوء التكوين: القراءة عبر الأحداث / التقييمات / لوحات المعلومات، بالإضافة إلى dashboards-write و queries-read / write / run لتدفق تأليف لـ Ask AI to write a query. كل SQL لا يزال يمر عبر نفس دور القراءة فقط والمسار SQL المحمي كما هو الحال مع الاستعلام المكتوب من قبل المستخدم، لذا هذا يوسع *سطح التأليف*، ليس سطح البيانات؛ العمليات المدمرة (`queries:delete`, `dashboards:delete`) تبقى بقصد خارج مفتاح المساعد. مثل مفتاح `admin`، إنه **محمي**: لا يمكن تعطيله أو إعادة إنشاء من خلال API للمفاتيح، فقط تدويره بتغيير `AGENT_API_KEY` وإعادة التشغيل. مستخدمو لوحة المعلومات **إضافة** يحتاجون إلى إذن `agent:use` لرؤية واستخدام المساعد. إذا فعلت آلية القياس الذاتية، امنح المساعد مفتاح `events:add`-فقط منفصلاً. --- -## ملاحظات الترقية والتوافق للخلف +## ملاحظات الترقية والتوافقية العكسية -أنت بحاجة فقط إلى هذه إذا كنت ترقي مثيلاً موجوداً؛ يمكن لعمليات النشر الجديدة تخطيها. +تحتاج هذه فقط إذا كنت ترقي نسخة موجودة؛ النشريات الجديدة يمكنها تخطيها. -> عند شحن التدقيقات، تمت توسيع المستفيدين الموجودين على طول نفس أشكال الأدوار مثل التنبيهات: اكتسب كل مستخدم ومجموعة صلاحيات تحمل `alerts:read` على `audits:read`، واكتسب كل صاحب `alerts:write` على `audits:write`. **لم يتم توسيع** مفاتيح API الموجودة. امنح `audits:*` لمفتاح بشكل صريح إذا كان يحتاج إلى سطح التدقيق. +> عند شحن التدقيقات، تم توسيع المنحين الموجودين على طول أشكال الأدوار نفسها كما هو الحال مع التنبيهات: حصل كل مستخدم ومجموعة أذونات على `alerts:read` على `audits:read`، وحصل كل حامل لـ `alerts:write` على `audits:write`. **لم يتم** توسيع مفاتيح API الموجودة. امنح `audits:*` لمفتاح بشكل صريح إذا احتاج إلى سطح التدقيق. -> يتم تحليل مانحات الرموز الموروثة لـ `alerts:ack` كـ `incidents:ack` بحيث يحتفظ في الوقت المناسب بالوصول دون إعادة صك. لم يعد الرمز قابلاً للتعيين من محرر مستخدمي لوحة التحكم؛ تقدم المصفوفة `incidents:ack` بدلاً من ذلك. +> يتم تحليل المنح المحفوظ للتوكن القديم `alerts:ack` كـ `incidents:ack` بحيث يحتفظ على المدققون بالوصول دون إعادة المفاتيح. لا يمكن تعيين التوكن من محرر مستخدم لوحة المعلومات؛ تقدم المصفوفة `incidents:ack` بدلاً منه. --- ## الخطوات التالية -- [Python SDK](/ar/agenteye/python-sdk): كيفية مصادقة كود الوكيل عند إرسال الأحداث. -- [الأمان](/ar/agenteye/security): كيف يعمل تسجيل الدخول والتحكم في الوصول وعزل البيانات لكل منظمة. \ No newline at end of file +- [Python SDK](/ar/agenteye/python-sdk): كيفية مصادقة كود agent الخاص بك عند إرسال الأحداث. +- [الأمان](/ar/agenteye/security): كيفية عمل تسجيل الدخول والتحكم في الوصول وعزل البيانات لكل منظمة. \ No newline at end of file diff --git a/docs/ar/agenteye/assistant.mdx b/docs/ar/agenteye/assistant.mdx index 25309003..86b5f02f 100644 --- a/docs/ar/agenteye/assistant.mdx +++ b/docs/ar/agenteye/assistant.mdx @@ -1,62 +1,64 @@ --- -title: "مساعد ذكاء اصطناعي" +--- +title: "مساعد ذكي" description: "اطرح سؤالاً على بيانات وكيلك بلغة إنجليزية عادية واحصل على إجابة مرتبطة مباشرة بالأدلة." --- -اطرح سؤالاً على بيانات وكيلك بلغة إنجليزية عادية واحصل على إجابة مرتبطة مباشرة بالأدلة. لا حاجة لكتابة SQL، ولا حاجة للحفر في لوحات المعلومات — مساعد **Failproof AI Observability** هو أسرع طريقة لأي شخص في فريقك للحصول على إجابات حول وكلائك. -![مساعد Failproof AI Observability يجيب على سؤال بلغة إنجليزية عادية داخل لوحة المعلومات، يعرض جدول نشاط الوكيل المباشر، وتفصيل استخدام النموذج لكل وكيل، والخلاصات المكتوبة، مع عرض الاستعلامات التي أجراها بشكل مدمج](/agenteye/images/assistant.png) -*اطرح السؤال بلغة إنجليزية عادية واحصل على إجابة مبنية من بياناتك الخاصة. هنا يقسم أي الوكلاء الأكثر انشغالاً وأي نماذج يستخدمونها، ويعرض الاستعلامات التي أجراها حتى تتمكن من التحقق من كل رقم.* +اطرح سؤالاً على بيانات وكيلك بلغة إنجليزية عادية واحصل على إجابة مرتبطة مباشرة بالأدلة. لا حاجة لكتابة SQL، ولا حاجة للبحث في لوحات التحكم — مساعد **Failproof AI Observability** هو الطريقة الأسرع لأي شخص في فريقك للحصول على إجابات حول وكلائك. + +![مساعد Failproof AI Observability يجيب على سؤال باللغة الإنجليزية العادية داخل لوحة التحكم، ويعرض جدول نشاط الوكيل المباشر، وتفصيل استخدام النموذج لكل وكيل، والنقاط الرئيسية المكتوبة، مع عرض الاستعلامات التي نفذها بشكل مضمن](/agenteye/images/assistant.png) +*اطرح السؤال بلغة إنجليزية عادية واحصل على إجابة مبنية من بياناتك الخاصة. هنا، تحلل أي الوكلاء الأكثر انشغالاً وأي النماذج التي يستخدمونها، وتعرض الاستعلامات التي نفذتها حتى تتمكن من التحقق من كل رقم.* -لا شيء لتعلمه. افتح الدردشة، اكتب ما تريد معرفته، واتبع الروابط التي يعطيها لك: +لا يوجد شيء تحتاج لتعلمه. افتح الدردشة، اكتب ما تريد معرفته، واتبع الروابط التي تعطيك إياها: ``` -You: which sessions errored today? -AI: 5 sessions errored today, newest first. Each one is linked: - • checkout-agent 14:02 tool timeout - • billing-agent 11:47 unhandled error - • ...and 3 more - -You: summarize this session (asked while viewing a run) -AI: This run took 12 steps across 3 tools and failed near the end when a - payment tool returned an error. It scored low on your "resolved" eval. - Links: the session, the failing event, and that evaluation. +أنت: أي جلسات حدث بها خطأ اليوم؟ +الذكاء الاصطناعي: 5 جلسات حدث بها خطأ اليوم، الأحدث أولاً. كل واحدة مرتبطة: + • checkout-agent 14:02 انتهاء المهلة الزمنية للأداة + • billing-agent 11:47 خطأ غير معالج + • ...و 3 أخرى + +أنت: لخص هذه الجلسة (تم السؤال عند عرض تشغيل) +الذكاء الاصطناعي: استغرق هذا التشغيل 12 خطوة عبر 3 أدوات وفشل بالقرب من النهاية عندما + أرجعت أداة الدفع خطأ. حصل على درجة منخفضة في تقييم "تم حله". + الروابط: الجلسة، الحدث الفاشل، وهذا التقييم. ``` -## فقط اسأل، وانتقل مباشرة إلى الدليل +## فقط اطرح السؤال وانتقل مباشرة إلى الدليل -تتوقف عن التخمين وتتوقف عن كتابة الاستعلامات. اسأل "كيف تتجه الجودة في الإنتاج هذا الأسبوع؟" أو "ما الجلسات التي حدثت فيها أخطاء اليوم؟" أو "لخص هذه الجلسة"، وتحصل على إجابة مباشرة في ثوان بدلاً من بناء استعلام وقراءته بنفسك. +توقف عن التخمين وتوقف عن كتابة الاستعلامات. اطرح "كيف تتجه الجودة في الإنتاج هذا الأسبوع؟"، "أي جلسات حدث بها خطأ اليوم؟"، أو "لخص هذه الجلسة"، واحصل على إجابة مباشرة في ثوان بدلاً من بناء استعلام وقراءته بنفسك. -تأتي كل إجابة مع إثباتاتها. يربط المساعد الجلسات الدقيقة والاستعلامات المحفوظة ولوحات المعلومات التي استخدمها للوصول إلى الإجابة، حتى تتمكن من النقر والتحقق بدلاً من الثقة بكلامه. كما أنه **يدرك الصفحة**: اسأل عن "هذه الجلسة" وأنت تشاهد واحدة وهو يعرف بالفعل أي عملية تقصد. أعد فتح أي محادثة سابقة لاحقاً من محول السجل والتقط من حيث توقفت. +كل إجابة تأتي مع إيصالاتها. يربط المساعد الجلسات الدقيقة والاستعلامات المحفوظة ولوحات التحكم التي استخدمها للوصول إلى الإجابة، لذا يمكنك النقر والتحقق بدلاً من أخذ كلامه كمسلم به. كما أنه **ملم بالصفحة**: اطرح سؤالاً حول "هذه الجلسة" أثناء عرض جلسة وهو يعرف بالفعل أي تشغيل تقصد. أعد فتح أي محادثة سابقة لاحقاً من محول السجل والتقط من حيث انقطعت. -## حول إجابة جيدة إلى استعلام محفوظ أو لوحة معلومات +## حول إجابة جيدة إلى استعلام محفوظ أو لوحة تحكم -عندما تستحق إجابة الاحتفاظ بها، اطلب من المساعد حفظها. يصيغ SQL لاستعلام محفوظ، أو يجمع لوحة معلومات من تلك الاستعلامات، ثم يعرض لك بطاقة **Approve / Reject**. لا شيء يُكتب حتى تنقر على Approve، لذا تحصل على سرعة "فقط اسأل" مع الكلمة الأخيرة دائماً لك. +عندما تستحق إجابة ما الاحتفاظ بها، اطلب من المساعد حفظها. يصيغ SQL لاستعلام محفوظ، أو ينشئ لوحة تحكم من تلك الاستعلامات، ثم يعرض عليك بطاقة **الموافقة / الرفض**. لا يتم كتابة أي شيء حتى تنقر على الموافقة، لذا تحصل على سرعة "اطرح فقط" مع الكلمة الأخيرة دائماً لك. -في صفحة **Queries** يذهب خطوة أبعد ويصبح مؤلف SQL: صف الاستعلام الذي تريده ("عرض معدل الخطأ حسب الوكيل لآخر 7 أيام") وسيحول SQL مباشرة إلى المحرر، فاتحاً عرض diff حتى تتمكن من **Accept** أو **Reject** التغيير قبل أن يتم تطبيقه. +في صفحة **الاستعلامات** يذهب إلى أبعد من ذلك ويصبح مؤلف SQL: صف الاستعلام الذي تريده ("عرض معدل الخطأ حسب الوكيل لآخر 7 أيام") وسيبث SQL مباشرة إلى المحرر، ويفتح عرض الفروقات حتى تتمكن من **قبول** أو **رفض** التغيير قبل أن يتم تطبيقه. -![صفحة Observability Queries ومحررها SQL](/agenteye/images/query-lab.png) -*صفحة Queries: هذا المحرر هو المكان الذي يحول فيه المساعد مسودة استعلام للقراءة فقط بالنسبة لك لقبولها أو رفضها.* +![صفحة Observability Queries ومحرر SQL الخاص بها](/agenteye/images/query-lab.png) +*صفحة الاستعلامات: هذا المحرر هو المكان الذي يبث فيه المساعد مسودة استعلام للقراءة فقط لتقبلها أو ترفضها.* -كتابة SQL بالسؤال هنا يستخدم إذن `queries:run`، وهو نفس الإذن خلف زر **Run** في المحرر. الدردشة في أي مكان آخر تحتاج `agent:use`. +إنشاء SQL بالسؤال هنا يستخدم إذن `queries:run`، نفس الإذن الموجود خلف زر المحرر **تشغيل**. الدردشة في أي مكان آخر تحتاج `agent:use`. -## آمن للعطاء لكامل الفريق +## آمن للتسليم للفريق بأكمله يمكنك فتح المساعد للجميع دون القلق بشأن ما قد يلمسه: -- **يقرأ فقط ما يمكنك رؤيته بالفعل.** الإجابات مقيدة بأذوناتك القراءة الخاصة، لذا لا تتسع سطح البيانات أبداً. -- **كل كتابة تنتظر لك.** الاستعلامات المحفوظة ولوحات المعلومات يتم إنشاؤها فقط بعد نقرك Approve الصريح، ولا توجد إعدادات تطفئ هذه البوابة. -- **لا يمكنه حذف أي شيء.** لا يتم الكشف عن أداة حذف والمساعد لا يحتفظ بإذن حذف. عمليات الحذف تبقى في يديك، في لوحة المعلومات. -- **يبقى داخل مؤسستك.** المساعد يرى فقط المؤسسة التي تشاهدها حالياً. -- **أسئلتك تبقى لك.** الطلبات والإجابات تعيش في قاعدة بيانات Observability الخاصة بك؛ تسجيل تحليلات المنتج فقط بيانات وصفية الاستخدام، أبداً نص الطلب الخاص بك. +- **يقرأ فقط ما يمكنك بالفعل أن ترى.** الإجابات محدودة بأذوناتك الخاصة للقراءة، لذا فهو لا يوسع سطح بياناتك. +- **كل عملية كتابة تنتظر منك.** يتم إنشاء الاستعلامات المحفوظة ولوحات التحكم فقط بعد نقرة الموافقة الصريحة منك، وليس هناك إعداد يغلق هذه البوابة. +- **لا يمكنه حذف أي شيء.** لا توجد أداة حذف معروضة والمساعد لا يحمل إذن حذف. يبقى الحذف في يديك، في لوحة التحكم. +- **يبقى داخل مؤسستك.** يرى المساعد فقط المؤسسة التي تعرضها حالياً. +- **أسئلتك تبقى ملكك.** تعيش الرسائل والإجابات في قاعدة بيانات Observability الخاصة بك؛ تسجل تحليلات المنتج بيانات وصفية الاستخدام فقط، ليس نص الرسالة الخاصة بك. -## مكان البحث عنها +## أين تجده -يركب المساعد على الحافة اليمنى لكل صفحة تحت مؤسستك (`//...`). انقر على السكة، أو اضغط على `⌘J` / `Ctrl+J`، لتوسيع لوحة الدردشة الكاملة، واسحب حافتها لتغيير الحجم؛ سيتم تذكر عرضك عند إعادة التحميل. تحتاج إلى إذن **`agent:use`** لاستخدامها، وإلا ستكون السكة رمادية. إذا لم يتم تشغيلها بعد لنشرك (فهي تحتاج اتصال LLM)، ستشاهد سكة خافتة بدلاً من دردشة عاملة. +يتحرك المساعد على الحافة اليمنى من كل صفحة تحت مؤسستك (`//...`). انقر على السكة، أو اضغط على `⌘J` / `Ctrl+J`، لتوسيع لوحة الدردشة الكاملة، واسحب حافتها لتغيير حجمها؛ يتم تذكر عرضك عبر إعادة التحميل. تحتاج إلى إذن **`agent:use`** لاستخدامه، وإلا فإن السكة ستكون رمادية. إذا لم يتم تشغيله للنشر الخاص بك حتى الآن (فهو يحتاج إلى اتصال LLM)، ستشهد سكة خافتة بدلاً من دردشة عاملة. ## ذات صلة - [CLI والوكلاء](/ar/agenteye/cli-and-agents) - [الاستعلامات](/ar/agenteye/queries) -- [لوحات المعلومات](/ar/agenteye/dashboards) +- [لوحات التحكم](/ar/agenteye/dashboards) - [مجموعة التقييم](/ar/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/ar/agenteye/audits.mdx b/docs/ar/agenteye/audits.mdx index 0b2b1efe..b28a99ea 100644 --- a/docs/ar/agenteye/audits.mdx +++ b/docs/ar/agenteye/audits.mdx @@ -1,55 +1,55 @@ --- --- -title: "التدقيق: محلل الموثوقية التلقائي الخاص بك" -description: "Failproof AI Observability يبحث عن الأعطال التي لم تكتب قاعدة لها ويسلمك قائمة مهام مرتبة ومدعومة بالأدلة حول ما يجب إصلاحه بالضبط." +title: "التدقيقات: محلل موثوقيتك الآلي" +description: "يبحث Failproof AI Observability عن الأعطال التي لم تكتب قواعد لها أبداً، ويسلمك قائمة مهام مرتبة وموثقة بالأدلة بشأن ما يجب إصلاحه بالضبط." --- -يبحث Failproof AI Observability عن الأعطال التي لم تكتب قاعدة لها ويسلمك قائمة مهام مرتبة ومدعومة بالأدلة حول ما يجب إصلاحه بالضبط. إنه مثل وجود محلل يمر عبر السجلات الخاصة بك كل ليلة، ثم يترك القائمة المختصرة على مكتبك في الصباح. +يبحث Failproof AI Observability عن الأعطال التي لم تكتب قواعد لها أبداً، ويسلمك قائمة مهام مرتبة وموثقة بالأدلة بشأن ما يجب إصلاحه بالضبط. إنه مثل وجود محلل يمشط سجلاتك كل ليلة، ثم يترك القائمة القصيرة على مكتبك في الصباح.
-*جولة مدتها دقيقتان: من تشغيل مجدول إلى إصلاح يمكنك العمل عليه.* +*جولة لمدة دقيقتين: من تشغيل مجدول إلى إصلاح يمكنك اتخاذ إجراء بشأنه.* -![صفحة التدقيق: وظائف متكررة تفحص جلساتك بحثاً عن أنماط الفشل، كل منها مع جدول زمني وحساسية](/agenteye/images/audits.png) -*كل تدقيق هو وظيفة متكررة تستكشف جلساتك وتكتب توصيات مرتبة ومدعومة بالأدلة.* +![صفحة التدقيقات: وظائف متكررة تفحص جلساتك بحثاً عن أنماط الفشل، كل منها مع جدول زمني وحساسية](/agenteye/images/audits.png) +*كل تدقيق هو عمل متكرر ينقب عن جلساتك ويكتب توصيات مرتبة وموثقة بالأدلة.* ## توقف عن التخمين بشأن ما يجب إصلاحه بعد ذلك -تمسك التنبيهات بالمشاكل التي تعرفها بالفعل أنك تراقبها. التدقيق يمسك بتلك التي لا تعرفها. في جدول زمني تحدده، يقرأ التدقيق عبر جميع جلسات الوكيل الخاصة بك ويبحث عن الأنماط التي تستحق الإصلاح، حتى تتمكن من قضاء وقتك في التصرف بناءً على النتائج بدلاً من التمرير عبر السجلات على أمل اكتشافها بنفسك. +تمسك التنبيهات بالمشاكل التي تعرف بالفعل أنه يجب عليك الانتباه لها. تمسك التدقيقات بالمشاكل التي لا تعرفها. وفقاً لجدول زمني تحدده، يقرأ التدقيق جميع جلسات وكلائك ويبحث عن الأنماط التي تستحق الإصلاح، بحيث تقضي وقتك في التصرف بناءً على النتائج بدلاً من التمرير عبر السجلات على أمل اكتشافها بنفسك. يستهدف التشغيل الواحد أنماط الفشل التي تكسر الوكلاء فعلاً في الإنتاج: - **مجموعات الأخطاء**: نفس الفشل يتكرر تحت سبب جذري مشترك. -- **الانجراف مقابل الأساس**: السلوك ينزلق بهدوء بعيداً عن نطاق معروف جيد. -- **فشل الهدف في النصوص**: التشغيل الذي انتهى تقنياً لكن لم يؤدِ المهمة أبداً. +- **الانحراف عن خط الأساس**: السلوك ينزلق بهدوء بعيداً عن نافذة معروفة الجودة. +- **فشل الهدف في النصوص**: عمليات تنتهي تقنياً لكنها لم تؤدِ المهمة أبداً. - **سوء استخدام الأداة**: الأداة الخاطئة أو الحجج السيئة أو الحلقات التي تحرق الاستدعاءات. -- **المقايضات بين الجودة والتكلفة**: حيث تدفع أكثر من اللازم للمخرجات التي يمكنك الحصول عليها بأرخص. +- **المقارنات بين الجودة والتكلفة**: حيث تدفع مبالغ زائدة للحصول على مخرجات يمكنك الحصول عليها بأرخص. - **فجوات التغطية**: السلوك الذي لا يراقبه أي تقييم أو تنبيه. -تقرر مدى صعوبة البحث باستخدام إعداد **الحساسية** الفردي (منخفض أو متوسط أو مرتفع)، حتى يتمكن الوكيل في بيئة الاختبار الضوضائية والوكيل المقيد في الإنتاج من أن يتم ضبط كل منهما إلى الإشارة التي تريدها. +تحدد أنت مدى قوة البحث باستخدام إعداد **الحساسية** الواحد (منخفض أو متوسط أو مرتفع)، بحيث يمكن ضبط وكيل في بيئة الاختبار الصاخبة ووكيل مقفول الإنتاج لكل منهما على الإشارة التي تريدها. -## كل توصية تأتي مع الإيصالات +## كل توصية تأتي مع الأدلة -لا تضطر أبداً إلى تقبل النتيجة بحسن نية. كل توصية تستشهد بالجلسات الدقيقة التي جاءت منها و SQL التي أظهرتها، حتى تتمكن من فتح الدليل والتأكد من المشكلة بنقرة واحدة بدلاً من عكس هندسة مطالبة. +لا تحتاج أبداً إلى الوثوق بالنتيجة على الإيمان. تستشهد كل توصية بالجلسات الدقيقة التي جاءت منها وSQL التي كشفتها، بحيث يمكنك فتح الأدلة والتأكد من المشكلة بنقرة واحدة بدلاً من العكس الهندسي. -عندما تتعلق النتيجة بأوراق اعتماد مسربة، تذهب خطوة أبعد وتربط أحداث الفرد التي طابقتها. انقر فوق واحد وستهبط على تلك اللحظة بالذات في الجلسة، محددة بالفعل، وليس أعلى نص طويل للتمرير خلاله. يسمي الرابط الحدث؛ لا ينسخ أبداً السر المكتشف إلى النتيجة، لذا فإن قراءة النتيجة لا تحدث في مكان ثانٍ حيث يتم كتابة بيانات اعتمادك. إذا لم يعد الحدث موجوداً لأن الجلسة مرت نافذة الاحتفاظ بك، تقول الصفحة ذلك بوضوح بدلاً من تركك تتساءل عما إذا كنت قد نقرت الشيء الخطأ. +عندما تكون النتيجة حول بيانات اعتماد مسربة، فإنها تذهب خطوة أبعد وترتبط بالأحداث الفردية التي طابقتها. انقر على واحدة وستصل إلى تلك اللحظة الدقيقة في الجلسة، محددة بالفعل — وليس أعلى نص طويل للتمرير خلاله. يسمي الرابط الحدث؛ لا ينسخ أبداً السر المكتشف في النتيجة، لذا فإن قراءة النتيجة ليست المكان الثاني الذي تُكتب فيه بيانات اعتمادك. إذا لم يعد الحدث موجوداً لأن الجلسة تجاوزت نافذة الاحتفاظ بك، فإن الصفحة تقول ذلك بوضوح بدلاً من تركك تتساءل عما إذا كنت قد نقرت الشيء الخاطئ. -هذا أيضاً ما يحافظ على صدق التدقيق. يتحقق الخادم من أن كل جلسة مذكورة موجودة بالفعل **ويتجاهل أي توصية لا تصمد أدلتها**، لذا فإن التدقيق يحقق ولكن لا يخترع أبداً. ما يصل إلى قائمتك حقيقي وقابل للتكرار ومرتب حسب أهميته، مع أكبر الأرباح في الأعلى. +هذا أيضاً ما يحافظ على نزاهة التدقيقات. يتحقق الخادم من أن كل جلسة مستشهد بها موجودة فعلاً و**يتخلص من أي توصية لا تتماشى أدلتها**، لذا يحقق التدقيق لكن لا يخترع أبداً. ما ينزل على قائمتك حقيقي وقابل للتكرار ومرتب حسب أهميته، مع أكبر الفوائز في الأعلى. -## حول الإصلاح إلى درع حماية +## حول الإصلاح إلى حماية -إصلاح مشكلة هو فقط نصف الفوز. النصف الآخر هو التأكد من أنه لا يمكنه العودة بهدوء. كل نتيجة تحمل **اختصار بنقرة واحدة يصيغ تنبيه تكرار**، مملوء مسبقاً بحافز بداية معقول يمكنك ضبطه. أغلق النتيجة، وسلح التنبيه، والمرة القادمة التي يظهر فيها هذا النمط ستتلقى إخطار بدلاً من اكتشافه مرة أخرى في تدقيق مستقبلي. +إصلاح المشكلة هو فقط نصف الفوز. النصف الآخر هو التأكد من أنها لا تستطيع العودة بهدوء. كل نتيجة تحمل **اختصار بنقرة واحدة يصيغ تنبيه تكرار**، مملوء بأداة تشغيل معقولة في البداية يمكنك ضبطها. أغلق النتيجة وشغّل التنبيه، والمرة القادمة التي يظهر فيها هذا النمط ستتلقى صفحة بدلاً من إعادة اكتشافه في تدقيق مستقبلي. ## أين تجده -يعيش التدقيق في لوحة التحكم في **`//audits`** (الشريط الجانبي إلى *تحليل* إلى *التدقيق*). عرض التشغيل والنتائج يحتاج **`audits:read`**؛ إنشاء وتحرير وفرز التدقيق يحتاج **`audits:write`**. عين نطاق التدقيق والوتيرة، ثم اضغط **تشغيل الآن** عندما تريد النتائج على الفور بدلاً من انتظار الممر المجدول التالي. +تعيش التدقيقات في لوحة المعلومات على **`//audits`** (الشريط الجانبي إلى *analyze* إلى *audits*). لعرض التشغيلات والنتائج يتطلب **`audits:read`**؛ إنشاء وتعديل وفرز التدقيقات يتطلب **`audits:write`**. اضبط نطاق التدقيق وتكراره، ثم اضغط على **Run now** في أي وقت تريد نتائج فوراً بدلاً من الانتظار للمسار المجدول التالي. -## ذات صلة +## ذات الصلة -- [التنبيهات](/ar/agenteye/alerts): احصل على إخطار في اللحظة التي يتم فيها تجاوز حد تعرفه بالفعل. -- [التقييمات](/ar/agenteye/evaluations): سجل كل عملية تشغيل حتى تظهر انحدارات الجودة من تلقاء نفسها. -- [تتبع الأخطاء](/ar/agenteye/error-tracking): جمّع واتبع الأخطاء التي يرميها الوكلاء الخاصون بك. -- [الحوادث](/ar/agenteye/incidents): تتبع المشكلة التي يكتشفها التدقيق حتى إصلاحها. \ No newline at end of file +- [التنبيهات](/ar/agenteye/alerts): احصل على صفحة في اللحظة التي يتم فيها تجاوز الحد الذي تعرفه بالفعل. +- [التقييمات](/ar/agenteye/evaluations): قيّم كل عملية بحيث تظهر تراجعات الجودة من تلقاء نفسها. +- [تتبع الأخطاء](/ar/agenteye/error-tracking): قم بتجميع ومتابعة الأخطاء التي يرميها وكلاؤك. +- [الحوادث](/ar/agenteye/incidents): تتبع مشكلة يكتشفها التدقيق حتى يتم إصلاحها. \ No newline at end of file diff --git a/docs/ar/agenteye/cli-and-agents.mdx b/docs/ar/agenteye/cli-and-agents.mdx index 860252b6..3d14e131 100644 --- a/docs/ar/agenteye/cli-and-agents.mdx +++ b/docs/ar/agenteye/cli-and-agents.mdx @@ -1,11 +1,11 @@ --- --- -title: "واجهة سطر الأوامر" -description: "نشر Failproof AI Observability بالكامل، أمر واحد فقط." +title: "CLI" +description: "نشر Failproof AI Observability الكامل، على بعد أمر واحد فقط." --- -نشر Failproof AI Observability بالكامل، أمر واحد فقط. تحقق من بيئة الإنتاج، أنشئ مفتاح API، أو أقرّ حادثة دون مغادرة جهازك الطرفي، ثم قم بإجراء أي من ذلك في خط أنابيب CI، أو اترك لوكيل الترميز القيام به بلغة إنجليزية عادية. +نشر Failproof AI Observability الكامل، على بعد أمر واحد فقط. تحقق من الإنتاج، أنشئ مفتاح API، أو أقر حادثة دون مغادرة محطة الأوامر لديك، ثم قم بتصريف أي منها إلى CI، أو دع وكيل ترميز يفعل ذلك لك باللغة الإنجليزية العادية. ```bash pipx install agenteye @@ -13,18 +13,18 @@ agenteye login --email you@example.com # a 6-digit code lands in your inbox agenteye --json sessions --since 24h # every agent run from the last day, newest first ``` -*واجهة سطر الأوامر `agenteye` تتواصل مع لوحة التحكم. إنها أداة مختلفة عن مجمّع البيانات، الذي يرسل الأحداث إلى الخادم.* +*أداة سطر الأوامر `agenteye` تتحدث مع لوحة التحكم الخاصة بك. وهي أداة مختلفة عن الجامع، الذي يشحن الأحداث إلى الخادم.* -## نشرك بالكامل، أمر واحد فقط +## نشرك الكامل، أمر واحد بعيد -توقف عن القفز بين علامات التبويب للإجابة على سؤال سريع. واجهة سطر الأوامر `agenteye` تقرأ بيانات نظامك وتدير مؤسستك من ملف تنفيذي واحد، لذا فإن الفحص الذي كان يعني النقر عبر لوحة التحكم يصبح سطر واحد يمكنك إعادة تشغيله أو إنشاء اختصار له أو لصقه في دليل التشغيل. تحصل على أربع واجهات: +توقف عن القفز بين علامات التبويب للإجابة عن سؤال سريع. أداة سطر الأوامر `agenteye` تقرأ بياناتك وتدير مؤسستك من ملف ثنائي واحد، لذلك يصبح الفحص الذي اعتاد أن يعني النقر عبر لوحة التحكم سطراً واحداً يمكنك إعادة تشغيله أو إنشاء بديل له أو لصقه في دفتر ملاحظات. تحصل على أربع واجهات: -- **اقرأ بيانات نظامك:** `sessions` و `events` و `evals` و `errors`، مصفاة حسب الوقت والوكيل والبيئة. -- **أدر مؤسستك:** `keys` و `users` و `settings` و `alerts` و `incidents`. -- **قم بتشغيل التحليلات:** SQL المحفوظ بالإضافة إلى مشغل `query` مخصص على بيانات الأحداث لديك. +- **قراءة بياناتك:** `sessions` و`events` و`evals` و`errors`، المصفاة حسب الوقت والوكيل والبيئة. +- **إدارة مؤسستك:** `keys` و`users` و`settings` و`alerts` و`incidents`. +- **تشغيل التحليلات:** SQL محفوظ بالإضافة إلى عداء `query` خاص للحصول على بيانات الأحداث الخاصة بك. - **اسأل المساعد:** `agent ask` يصل إلى نفس محلل القراءة فقط الذي تتحدث معه في لوحة التحكم. -ثبّته مرة واحدة باستخدام `pipx`، وسجّل الدخول برمز 6 أرقام يُرسل بالبريد الإلكتروني، وأنت جاهز. تستمر الجلسة حوالي يوم واحد؛ أعد تشغيل `agenteye login` عند انتهاء صلاحيتها. استخدمه للتحقق من الإنتاج أو توفير مفتاح أو فرز حادثة نشطة، كل ذلك دون فتح متصفح: +ثبته مرة واحدة مع `pipx`، وقم بتسجيل الدخول باستخدام رمز مكون من 6 أرقام يتم إرساله عبر البريد الإلكتروني، وأنت جاهز. تستمر الجلسة حوالي يوم واحد؛ أعد تشغيل `agenteye login` عند انتهاء صلاحيتها. استخدمه للتحقق من الإنتاج، أو توفير مفتاح، أو فرز حادثة حريق، كل ذلك دون فتح متصفح: ```bash agenteye errors --since 24h --aggregate # what is breaking, grouped by error type @@ -32,25 +32,25 @@ agenteye incidents list --state firing # what is on fire right now agenteye keys create ci --add events:add # a key that can only push events, secret shown once ``` -عادة واحدة يجب معرفتها: الخيارات العامة مثل `--json` تأتي قبل الأمر. `agenteye --json sessions` صحيح؛ `agenteye sessions --json` غير صحيح. +عادة واحدة يجب معرفتها: الخيارات العامة مثل `--json` تأتي قبل الأمر. `agenteye --json sessions` صحيح؛ `agenteye sessions --json` ليس صحيحاً. -## قم بكتابة نص، ادمجه في CI +## قم بصريفه، وربطه في CI -كل أمر يقبل `--json`، وهذا يغير كل شيء. JSON نظيف يذهب إلى stdout بينما حالة النظام والتحذيرات تذهب إلى stderr، لذا فإن التقاط `--json` ينبوب مباشرة إلى `jq` بدون سطر شاذ لإزالته. هذا هو ما يجعل واجهة سطر الأوامر جيدة بنفس القدر لك في المحث ولوكيل ترميز يحلل النتيجة: +كل أمر يأخذ `--json`، وهذا يغير كل شيء. JSON نظيف يذهب إلى stdout بينما حالة بشرية وتحذيرات تذهب إلى stderr، بحيث يذهب التقاط `--json` مباشرة إلى `jq` بدون سطر شاذ للتجريد. هذا هو ما يجعل واجهة سطر الأوامر جيدة بنفس القدر بالنسبة لك عند المطالبة ولوكيل ترميز تحليل الإخراج: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -إنها مبنية للعمل دون إشراف. تخطي المطالبات الأكيدة تلقائياً عندما لا يكون هناك محطة نصية مرفقة، لذا لا شيء يتعطل في خط الأنابيب، وكل أمر يعيد رمز خروج ذي معنى: `0` نجاح، `4` لم تقم بتسجيل الدخول، `5` تفتقد صلاحية (الرسالة تسميها، على سبيل المثال `alerts:write`)، `3` لوحة التحكم غير قابلة للوصول. يمكن للنص أن يتفرع على `4` لإعادة المصادقة أو على `5` لإخبارك بالضبط بما يجب أن تطلبه من مسؤول، بدلاً من الفشل العمياني. +تم بناؤه للعمل دون مراقبة. توجيهات التأكيد تتخطى تلقائياً عند عدم توصيل أي محطة، لذا لا شيء يتدلى في خط أنابيب، وكل أمر يعود برمز خروج ذي معنى: `0` نجاح، `4` لم تقم بتسجيل الدخول، `5` في عداد المفقودين من صلاحية (الرسالة تسميها، على سبيل المثال `alerts:write`)، `3` لوحة التحكم غير قابلة للوصول. يمكن للسكريبت أن يتفرع على `4` لإعادة المصادقة أو `5` لتخبرك بالضبط ما يجب أن تطلبه من مسؤول، بدلاً من الفشل الأعمى. -## اترك وكيل ترميز يتحكم به باللغة الإنجليزية العادية +## دع وكيل ترميز يقوده باللغة الإنجليزية العادية -الأفضل من ذلك، لا يجب أن تتذكر أي من هذه الأعلام على الإطلاق. **مهارة واجهة سطر الأوامر** عبارة عن مجلد مهارة وكيل صغير يُسمى `agenteye-cli` يعلم وكيل ترميز مثل Claude Code أو Codex كيفية تشغيل واجهة سطر الأوامر من طلبات باللغة الإنجليزية البسيطة. اسأل "هل هناك أي شيء معطل اليوم؟" والوكيل يختار الأمر، ويقوم بتشغيله باسمك، ويجيب بشكل نثري. +الأفضل من ذلك، يجب ألا تضطر إلى تذكر أي من هذه الأعلام على الإطلاق. **مهارة CLI** عبارة عن مجلد Agent Skill صغير باسم `agenteye-cli` يعلم وكيل ترميز مثل Claude Code أو Codex أن يقود CLI من طلبات اللغة الإنجليزية العادية. اسأل "هل هناك أي شيء مكسور اليوم؟" والوكيل يختار الأمر، وينفذه باسمك، ويجيب بالنثر. -بالنسبة إلى Claude Code، اسحب مجلد `agenteye-cli` إلى `~/.claude/skills/` وسيتم اكتشافه تلقائياً. يوفر Failproof AI Observability المجلد؛ لا يوجد شيء إضافي للتثبيت، لأنه يقود فقط واجهة سطر الأوامر التي ثبتها بالفعل. قم بتسجيل الدخول بنفسك أولاً: المهارة لا يمكنها إكمال تسجيل الدخول برمز البريد الإلكتروني من أجلك. +بالنسبة لـ Claude Code، انسخ مجلد `agenteye-cli` إلى `~/.claude/skills/` وسيتم اكتشافه تلقائياً. يوفر Failproof AI Observability المجلد؛ لا يوجد شيء إضافي للتثبيت، لأنه يقود فقط واجهة سطر الأوامر التي قمت بتثبيتها بالفعل. قم بتسجيل الدخول بنفسك أولاً: لا يمكن للمهارة إكمال تسجيل الدخول برمز البريد الإلكتروني لك. -نظراً لأن الوكيل يقوم بتشغيل واجهة سطر الأوامر باسمك، فيمكنه القيام بكل شيء تسمح به عملية تسجيل الدخول الخاصة بك، القراءة والكتابة على حد سواء: إنشاء مفاتيح، تغيير الإعدادات، حل الحوادث. لا تظهر مطالبة "هل أنت متأكد؟" في واجهة سطر الأوامر لوكيل، لذا تمت كتابة المهارة لتوضيح الأمر الدقيق والانتظار لموافقتك قبل أي تغيير. أنت خطوة التأكيد. +لأن الوكيل يقود واجهة سطر الأوامر باسمك، يمكنه فعل كل شيء يسمح به تسجيل الدخول الخاص بك، القراءة والكتابة على حد سواء: إنشاء مفاتيح، تغيير الإعدادات، حل الحوادث. لا يتم تشغيل موجه "هل أنت متأكد؟" من واجهة سطر الأوامر بواسطة وكيل، لذا تم كتابة المهارة لذكر الأمر الدقيق والانتظار لموافقتك قبل أي تغيير. أنت خطوة التأكيد. ```text you Why did session run-001 fail? @@ -59,7 +59,7 @@ agent Running: agenteye --json events --session-id run-001 --all The checkout-agent hit a TimeoutError on its third tool call. ``` -البيانات المقروءة تبقى فورية، وكل كتابة تتوقف من أجلك: +تبقى القراءات فورية، وكل كتابة تتوقف من أجلك: ```text you Give CI a key that can only push events. @@ -73,9 +73,9 @@ you yes agent Done. Key "ci" created with events:add only. The secret is shown once, so store it now. ``` -## ذات صلة +## ذات الصلة -- [مرجع واجهة سطر الأوامر](/ar/agenteye/cli): كل أمر وعلم وشكل JSON. -- [وصفات واجهة سطر الأوامر للوكلاء](/ar/agenteye/cli-recipes): أنماط `jq` التي يمكنك نسخها بسهولة ومعالجة رموز الخروج. -- [مهارة وكيل واجهة سطر الأوامر](/ar/agenteye/cli-skill): ثبّت وقم بتشغيل مهارة `agenteye-cli`. -- [مساعد ذكاء اصطناعي](/ar/agenteye/assistant): محلل لوحة التحكم الذي يتحدث معه `agent ask`. \ No newline at end of file +- [مرجع CLI](/ar/agenteye/cli): كل أمر وعلم وشكل JSON. +- [وصفات CLI للوكلاء](/ar/agenteye/cli-recipes): انسخ والصق أنماط `jq` ومعالجة رمز الخروج. +- [مهارة وكيل CLI](/ar/agenteye/cli-skill): ثبت وقم بتشغيل مهارة `agenteye-cli`. +- [مساعد AI](/ar/agenteye/assistant): محلل لوحة التحكم الذي `agent ask` يتحدث معه. \ No newline at end of file diff --git a/docs/ar/agenteye/cli-recipes.mdx b/docs/ar/agenteye/cli-recipes.mdx index b85fc60a..030b7299 100644 --- a/docs/ar/agenteye/cli-recipes.mdx +++ b/docs/ar/agenteye/cli-recipes.mdx @@ -1,29 +1,29 @@ --- -title: "وصفات سطر الأوامر للوكلاء" -description: "انسخ والصق أنماط الاستعلام ووصفات jq التي تحول بيانات الجلسة والأحداث والتقييم إلى شيء يمكن لسكريبت أو وكيل ترميز أن يؤتمتنه." +title: "وصفات CLI للوكلاء" +description: "انسخ والصق أنماط الاستعلام ووصفات jq التي تحول بيانات الجلسة والحدث والتقييم إلى شيء يمكن لنص أو وكيل ترميز أتمتته." --- -اسحب بيانات الجلسة والأحداث والتقييم (وشغل إعادة التقييمات) مباشرة من سكريبت أو وكيل ترميز، مع JSON نظيف على stdout يتم توجيهه مباشرة إلى `jq`. هذه الوصفات تحول بيانات Failproof AI Observability إلى شيء يمكن لمستخدم المحطة الطرفية أو وكيل ترميز AI (Claude Code، Cursor) أن يستعلم عنه ويؤتمتنه، دون النقر عبر لوحة المعلومات. +اسحب بيانات الجلسة والحدث والتقييم (وشغّل إعادة التقييمات) مباشرة من نص أو وكيل ترميز، مع JSON نظيف على stdout الذي ينقل مباشرة إلى `jq`. هذه الوصفات تحول بيانات Failproof AI Observability إلى شيء يمكن لمستخدم الطرفية أو وكيل ترميز ذكي (Claude Code، Cursor) الاستعلام عنه والأتمتة، بدون النقر عبر لوحة التحكم. -الأنماط أدناه جاهزة للنسخ واللصق في سطر أوامر Failproof AI Observability (`agenteye`). للتثبيت والمصادقة وقائمة الخيارات الكاملة، انظر [CLI](/ar/agenteye/cli)؛ شغّل `agenteye -h` أو `agenteye -h` للحصول على المساعدة المدمجة. +الأنماط أدناه جاهزة للنسخ والإلصاق لـ Failproof AI Observability CLI (`agenteye`). للتثبيت والمصادقة والقائمة الكاملة للخيارات، انظر [CLI](/ar/agenteye/cli)؛ شغّل `agenteye -h` أو `agenteye -h` للمساعدة المدمجة. ## القواعد الذهبية -1. **الخيارات العامة تأتي *قبل* الأمر.** `agenteye --json sessions` صحيح؛ `agenteye sessions --json` غير صحيح. الخيارات العامة هي `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **مرّر `--json` كلما قمت بتحليل المخرجات.** البيانات تذهب إلى **stdout** كـ JSON؛ حالة المستخدم والأخطاء تذهب إلى **stderr**، لذلك يبقى stdout نظيفاً للتوجيه إلى `jq`. -3. **تفرع بناءً على رمز الخروج**، وليس على نص stderr: `0` موافق · `1` خطأ غير متوقع · `2` وسائط سيئة · `3` لا يمكن الوصول إلى لوحة المعلومات · `4` غير مسجل دخول أو انتهت صلاحية الجلسة · `5` إذن مفقود · `6` المورد غير موجود. -4. **اكتشف باستخدام `-h`.** كل أمر يوثق عوامل التصفية وصيغ القيم وشكل JSON. +1. **الخيارات العامة تأتي *قبل* الأمر.** `agenteye --json sessions` صحيح؛ `agenteye sessions --json` غير صحيح. العامات هي `--json`، `--base-url`، `--org`، `--token`، `--insecure`/`--secure`، `--timeout`، `--quiet`، `--no-color`. +2. **مرّر `--json` كلما قمت بتحليل الإخراج.** البيانات تذهب إلى **stdout** كـ JSON؛ حالة الإنسان والأخطاء تذهب إلى **stderr**، لذا يبقى stdout نظيفاً للنقل إلى `jq`. +3. **افرع على رمز الخروج، وليس على نص stderr**: `0` موافق · `1` خطأ غير متوقع · `2` وسائط سيئة · `3` لا يمكن الوصول إلى لوحة التحكم · `4` غير مسجل الدخول أو منتهي الصلاحية · `5` إذن مفقود · `6` المورد غير موجود. +4. **اكتشف مع `-h`.** كل أمر يوثق مرشحاته وصيغ القيم وشكل JSON. ## إعداد لمرة واحدة ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # كي لا تكرر --base-url -agenteye login --email you@example.com # الصق الرمز المرسل بالبريد؛ صالح ~24 ساعة +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # حتى لا تكرر --base-url +agenteye login --email you@example.com # الصق الكود المرسل بالبريد؛ صالح ~24h ``` -## تأكد المصادقة قبل القيام بالعمل +## تأكد من المصادقة قبل القيام بالعمل -`whoami` لا يخطئ على جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك، يبلغ `logged_in:false`، لذا يمكن لوكيل أن يختبر حالة المصادقة بأمان. (قد يزال يخرج بقيمة غير صفرية إذا لم يتم تعيين عنوان URL أساسي أو كانت لوحة المعلومات غير قابلة للوصول.) +`whoami` لا يخطئ أبداً في جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك يبلغ `logged_in:false`، لذا يمكن للوكيل التحقق من حالة المصادقة بأمان. (لا يزال يمكن أن يخرج برمز غير صفري إذا لم يتم تعيين عنوان URL أساسي أو كانت لوحة التحكم غير قابلة للوصول.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -34,95 +34,95 @@ fi ## ابحث عن الجلسات الفاشلة أو منخفضة التصنيف ```bash -# الجلسات في آخر 24 ساعة التي حدث فيها خطأ في التقييم +# جلسات في آخر 24 ساعة التي أخطأ تقييمها agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# التقييمات التي تسجل <= 0.5 في المساعدة، لوكيل واحد +# التقييمات التي تسجل <= 0.5 على المفيدية، لوكيل واحد agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -تصفية التصنيف موجودة على **`evals`**، وليس `sessions`. `--score KEY:MIN..MAX` قابل للتكرار ويتم دمجه بـ AND؛ أي حد اختياري (`..0.5` يعني ≤ 0.5، `0.9..` يعني ≥ 0.9). يمكنك تمرير ما يصل إلى 20 مرشح تصنيف لكل طلب؛ المزيد يعيد HTTP 400. `sessions` يشارك مرشحات `--env`, `--status`, `--agent-id`, `--session-id`، ونطاق الوقت مع `evals`، لكنه لا يحتوي على `--score`. +تصفية الدرجات تعيش على **`evals`**، وليس `sessions`. `--score KEY:MIN..MAX` قابلة للتكرار ومجتمعة بـ AND؛ أي من الحدود اختيارية (`..0.5` تعني ≤ 0.5، `0.9..` تعني ≥ 0.9). يمكنك تمرير ما يصل إلى 20 مرشح درجة لكل طلب؛ يعيد المزيد HTTP 400. `sessions` تشارك `--env`، `--status`، `--agent-id`، `--session-id`، ومرشحات النطاق الزمني مع `evals`، لكن لا توجد `--score`. ## اقرأ جلسة واحدة من البداية إلى النهاية -لا يوجد أمر `session show` واحد. اجمع بين مسار الأحداث والتقييم الخاص بالجلسة: +لا يوجد أمر واحد `session show`. دمج درب الحدث مع تقييم الجلسة: ```bash -# آخر تقييم للجلسة (الحالة + التصنيفات) +# آخر تقييم للجلسة (الحالة + الدرجات) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# كل حدث في التشغيل (رفع --limit للمسح الكامل) +# كل حدث في التشغيل (ارفع --limit لمسح كامل) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# فقط استدعاءات الأداة في جلسة (--full مطلوب للحصول على الحمل الخام) +# فقط استدعاءات الأدوات في جلسة (--full مطلوب للحصول على الحمولة الأولية) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **ملاحظة:** بشكل افتراضي، `events` يقرأ موجز سريع بدون حمول. يحمل كل حدث `summary` محسوب على الخادم من سطر واحد بالإضافة إلى علامات مثل `is_error` وعدد الرموز، لكن `payload` يعود كـ `{}`. لسحب الحمل الخام، أضف `--full` (أو `--fields payload`). الموجز الكامل أبطأ بحجم كبير، لذا اجعله محدوداً: اجمع `--full` مع `--session-id` واحد. +> **ملاحظة:** بشكل افتراضي، `events` يقرأ تغذية سريعة خالية من الحمولة. كل حدث يحمل ملخص من المخادع المحسوب بسطر واحد `summary` بالإضافة إلى علامات مثل `is_error` وعدادات التوكنات، لكن `payload` يعود كـ `{}`. لسحب الحمولة الأولية، أضف `--full` (أو `--fields payload`). التغذية الكاملة أبطأ عند النطاق، لذا احبسها: اجمع `--full` مع `--session-id` واحد. ## جلب كل شيء (الترقيم) -النتائج هي الأحدث أولاً والمُرقمة بالمؤشر. +النتائج هي الأحدث أولاً والترقيم بالمؤشر. ```bash -# دفعة واحدة: جلب ما يصل إلى 500 صف في صفحات 200 صف +# لقطة واحدة: جلب ما يصل إلى 500 صف في صفحات 200 صف agenteye --json events --session-id run-001 --limit 500 --all > events.json -# الترقيم اليدوي: مرّر next_cursor مرة أخرى +# الترقيم اليدوي: أرجع next_cursor page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## قلل المخرجات باستخدام --fields +## تنحيف الإخراج باستخدام --fields -قصر المفاتيح (في الجدول و`--json`) لتقليل ما يجب على الوكيل قراءته. +قيّد المفاتيح (في الجدول و`--json`) لتقليل ما يجب على الوكيل قراءته. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -أسماء الحقول غير المعروفة يتم رفضها (خروج `2`) مع القائمة الصحيحة، وهي طريقة رخيصة لاكتشاف أسماء الحقول. +أسماء الحقول غير المعروفة مرفوضة (خروج `2`) مع القائمة الصحيحة، طريقة رخيصة لاكتشاف أسماء الحقول. -## اكتشف قيم المرشحات الصحيحة +## اكتشف قيم المرشح الصحيحة ```bash agenteye --json list envs | jq -r '.values[]' # قيم --env -agenteye --json list tools | jq -r '.values[]' # أسماء الأدوات؛ أيضاً وكلاء وموديلات وأنواع أحداث وغيرها +agenteye --json list tools | jq -r '.values[]' # أسماء الأدوات؛ أيضاً وكلاء، نماذج، event_types، … agenteye --json list score_filters | jq -r '.values[]' # KEY صحيح لـ --score KEY:MIN..MAX ``` -## اختر المنظمة الخاصة بك (الإيجار المتعدد) +## اختر منظمتك (متعدد المستأجرين) -إذا كنت تنتمي إلى أكثر من منظمة واحدة، اختر المستأجر النشط عند تسجيل الدخول (يتم حفظه): +إذا كنت تنتمي إلى أكثر من منظمة، اختر المستأجر النشط عند تسجيل الدخول (يتم حفظه): ```bash agenteye login --org acme --email you@corp.com # عيّن المستأجر في نفس خطوة تسجيل الدخول agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # اسحب لأمر واحد +agenteye --org globex --json sessions --since 24h # تجاوز أمر واحد ``` -تسجيل دخول متعدد المنظمات بدون `--org` ينتج عنه خروج غير صفري ويطبع المنظمات للاختيار من بينها. +تسجيل دخول متعدد المنظمات بدون `--org` يخرج برمز غير صفري ويطبع المنظمات للاختيار من بينها. ## توفير مفتاح API لـ SDK/المجمع ```bash -# السر يطبع مرة واحدة فقط، مع --json إنه حقل .key +# يتم طباعة السر مرة واحدة فقط، مع --json إنه الحقل .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # التدوير؛ agenteye keys disable ci-bot --yes للإلغاء +agenteye keys regenerate ci-bot --yes # دوّر؛ agenteye keys disable ci-bot --yes للإلغاء ``` -## شغّل استعلام محفوظ أو مخصص +## قم بتشغيل استعلام محفوظ أو خاص ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # استعلام محفوظ + وسيط موضعي $1 +agenteye --json query run errs --arg prod | jq '.rows' # استعلام محفوظ + $1 موضعية ``` -## فرز الحادثة بشكل غير تفاعلي +## فحص الحادثة غير التفاعلي ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -131,9 +131,9 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **ملاحظة:** الطفرات تتخطى تلقائياً موجز التأكيد الخاص بها تحت `--json` أو عندما لا يكون stdin TTY، لذلك الوكلاء لا ينتظرون؛ مرّر `--yes`/`-y` للتخطي صراحة في مكان آخر. +> **ملاحظة:** الطفرات تتخطى تلقائياً موجه التأكيد تحت `--json` أو عندما لا يكون stdin TTY، لذا لا تتعطل الوكلاء؛ مرّر `--yes`/`-y` لتخطيها بوضوح في مكان آخر. -## معالجة رمز الخروج في سكريبت +## معالجة رمز الخروج في نص ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -146,7 +146,7 @@ case "${code:-0}" in esac ``` -## أشكال مخرجات JSON +## أشكال إخراج JSON | الأمر | stdout JSON (مع `--json`) | |---|---| @@ -157,22 +157,22 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` يظهر مرة واحدة) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` مُظهر مرة واحدة) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | | إنشاء/تحديث/حذف (أي) | كائن المورد، أو `{"deleted": true, "id"}` للحذف | | فشل (أي، مع `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` على stdout | -- كل عنصر **الحدث** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. لاحظ أن `payload` هو `{}` إلا إذا طلبت الموجز الكامل مع `--full` (أو `--fields payload`). -- كل عنصر **التقييم** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- كل عنصر **الجلسة** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- كل عنصر **حدث** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. لاحظ أن `payload` هو `{}` ما لم تطلب التغذية الكاملة مع `--full` (أو `--fields payload`). +- كل عنصر **تقييم** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- كل عنصر **جلسة** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -كل أمر `--fields` يقبل أسماء الحقول الخاصة به بالضبط. تختلف المجموعة بين `sessions` و`evals`، لذا قد يتم رفض الاسم الصالح لأحدهما من قبل الآخر. +كل أمر `--fields` يقبل بالضبط أسماء الحقول الخاصة به. المجموعة تختلف بين `sessions` و`evals`، لذا قد يكون الاسم الصحيح لأحدهما مرفوضاً من الآخر. ## الخطوات التالية -- [CLI](/ar/agenteye/cli): التثبيت والمصادقة ومرجع الخيارات الكامل لكل أمر. -- [CLI agent skill](/ar/agenteye/cli-skill): احزم هذه الوصفات كمهارة يمكن لوكيل الترميز الخاص بك تحميلها. -- [مفاتيح API](/ar/agenteye/api-keys): أنشئ وحدد نطاق المفاتيح التي يستخدمها CLI و SDK والمجمع للمصادقة. -- [Python SDK](/ar/agenteye/python-sdk): أرسل الأحداث إلى Failproof AI Observability بحيث يكون هناك بيانات لهذه الوصفات للاستعلام عنها. \ No newline at end of file +- [CLI](/ar/agenteye/cli): التثبيت والمصادقة والمرجع الكامل للخيارات لكل أمر. +- [مهارة وكيل CLI](/ar/agenteye/cli-skill): احزم هذه الوصفات كمهارة يمكن لوكيل الترميز الخاص بك تحميلها. +- [مفاتيح API](/ar/agenteye/api-keys): إنشاء وتحديد نطاق المفاتيح التي يتم المصادقة بها في CLI و SDK والمجمع. +- [Python SDK](/ar/agenteye/python-sdk): أرسل الأحداث إلى Failproof AI Observability حتى توجد بيانات لهذه الوصفات للاستعلام عنها. \ No newline at end of file diff --git a/docs/ar/agenteye/cli-skill.mdx b/docs/ar/agenteye/cli-skill.mdx index 499cc9af..caf5f99e 100644 --- a/docs/ar/agenteye/cli-skill.mdx +++ b/docs/ar/agenteye/cli-skill.mdx @@ -1,160 +1,160 @@ --- --- -title: "مهارة عامل Failproof AI Observability CLI" -description: "اسأل وكيل الترميز الخاص بك \"هل حدث عطل ما اليوم؟\" ودعه يجيب من بيانات Failproof AI Observability المباشرة، بدون الحاجة لحفظ أوامر." +title: "مهارة وكيل Failproof AI Observability CLI" +description: "اسأل وكيل التشفير الخاص بك \"هل هناك أي شيء معطوب اليوم؟\" واسمح له بالإجابة من بيانات Failproof AI Observability المباشرة، بدون الحاجة لحفظ أي أوامر." --- -اسأل وكيل الترميز الخاص بك *"هل حدث عطل ما اليوم؟"* ودعه يجيب من بيانات Failproof AI Observability المباشرة، بدون الحاجة لحفظ أوامر. **مهارة Failproof AI Observability CLI** (`agenteye-cli`) هي *مهارة عامل*: مجلد صغير يحتوي على تعليمات يحملها وكيل ترميز مثل Claude Code أو Codex عند الحاجة. تعلم الوكيل كيفية تشغيل نشر Observability الخاص بك من خلال [`agenteye` CLI](/ar/agenteye/cli) من طلبات باللغة الإنجليزية العادية مثل *"أعط CI مفتاح يمكنه فقط دفع الأحداث"* أو *"اعترف بالحادثة النشطة وعينها لي."* +اسأل وكيل التشفير الخاص بك *"هل هناك أي شيء معطوب اليوم؟"* واسمح له بالإجابة من بيانات **Failproof AI Observability** المباشرة، بدون الحاجة لحفظ أي أوامر. **مهارة Failproof AI Observability CLI** (`agenteye-cli`) هي *مهارة وكيل*: مجلد صغير من التعليمات يحمّله وكيل تشفير مثل Claude Code أو Codex حسب الطلب. تعلّم الوكيل تشغيل نشر Observability الخاص بك عبر [`agenteye` CLI](/ar/agenteye/cli) من طلبات باللغة الإنجليزية العادية مثل *"أعط CI مفتاحًا يمكنه فقط دفع الأحداث"* أو *"أقر الحادثة النشطة وأسندها إليّ."* -إنها **ليست** خدمة أو ملف تنفيذي منفصل؛ لا شيء للنشر. تعتمد على CLI الذي لديك بالفعل: يقوم الوكيل بتنفيذ `agenteye --json …`، ويحلل JSON النظيف، ويجيبك بنص عادي. كل شيء يمكنه القيام به، يمكنك القيام به بنفسك بكتابة نفس الأوامر. +إنه **ليس** خدمة أو ثنائي منفصل؛ لا توجد شيء لنشره. يعمل فوق CLI الذي قمت بتثبيته بالفعل: يقوم الوكيل بتنفيذ `agenteye --json …`، ويحلل JSON النظيف، ويجيبك بالنثر. كل شيء يمكنه فعله، يمكنك فعله بنفسك عن طريق كتابة نفس الأوامر. --- -## كيف يرتبط بواجهات Failproof AI Observability الأخرى +## كيف يتعلق بواجهات Failproof AI Observability الأخرى -Failproof AI Observability يعطيك أربع طرق للوصول إلى نفس البيانات والتحكم. تكمل بعضها بعضاً: +يوفر لك Failproof AI Observability أربع طرق للوصول إلى نفس البيانات والعناصر التحكم. تكمل بعضها البعض: -| الواجهة | ما هي | حيث تعمل | استخدمها عندما | +| الواجهة | ما هي | أين تعمل | استخدمها عندما | |---|---|---|---| -| **[CLI](/ar/agenteye/cli)** | مرجع الأوامر والخيارات لـ `agenteye` | محطة طرفية | تريد تشغيل أو كتابة أمر معين | -| **[وصفات CLI](/ar/agenteye/cli-recipes)** | أنماط `jq`/أنابيب جاهزة للنسخ | محطة طرفية / نصوص برمجية | تريد دمج CLI في أتمتة | -| **مهارة CLI** (هذا المستند) | باب أمامي بلغة طبيعية على CLI | وكيل ترميز، على محطة العمل الخاصة بك | تريد فقط أن تسأل ودع الوكيل يختار الأمر | -| **[مهارة المقيّم](/ar/agenteye/evaluator-skill)** | مهارة شقيقة تصمم وتبني خدمة التسجيل الخاصة بك | وكيل ترميز، على محطة العمل الخاصة بك | تريد **إنتاج** درجات التقييم بدلاً من قراءتها | -| **[مهارة Python SDK](/ar/agenteye/python-sdk-skill)** | مهارة شقيقة تجهز وكيلك لإصدار بيانات تلميترية | وكيل ترميز، على محطة العمل الخاصة بك | تريد من وكيلك **إنتاج** الأحداث التي تقرأها هذه المهارة | -| **[مساعد AI في لوحة المعلومات](/ar/agenteye/assistant)** | دردشة مضمنة في لوحة المعلومات | من جهة الخادم (في لوحة المعلومات) | تريد أسئلة وأجوبة داخل لوحة المعلومات حول البيانات | +| **[CLI](/ar/agenteye/cli)** | مرجع الأوامر والعلامات لـ `agenteye` | المحطة الطرفية | تريد تشغيل أو نص برنامج أمر معين | +| **[وصفات CLI](/ar/agenteye/cli-recipes)** | أنماط `jq` وأنابيب نسخ-لصق | المحطة الطرفية / النصوص | تقوم بدمج CLI في الأتمتة | +| **مهارة CLI** (هذا المستند) | بابٌ للغة طبيعية على CLI | وكيل التشفير، على محطة العمل الخاصة بك | تريد أن تسأل فقط واترك الوكيل يختار الأمر | +| **[مهارة المقيّم](/ar/agenteye/evaluator-skill)** | مهارة أخت تصمم وتبني خدمة التصحيح الخاصة بك | وكيل التشفير، على محطة العمل الخاصة بك | تريد إنتاج درجات التقييم بدلاً من قراءتها | +| **[مهارة Python SDK](/ar/agenteye/python-sdk-skill)** | مهارة أخت تقوم بقياس وكيلك بحيث ينبعث قياس في الجميع | وكيل التشفير، على محطة العمل الخاصة بك | تريد أن ينتج وكيلك الأحداث التي تقرأها هذه المهارة | +| **[مساعد AI في لوحة المعلومات](/ar/agenteye/assistant)** | دردشة مضمنة في لوحة المعلومات | جانب الخادم (في لوحة المعلومات) | تريد أسئلة وأجوبة في لوحة المعلومات على بياناتك | -المهارة نفسها ليس لديها امتيازات خاصة بها؛ فهي تحول كلماتك ببساطة إلى استدعاءات CLI يتم تشغيلها باسمك: +المهارة نفسها لا تمتلك امتيازاتها الخاصة؛ إنها تحول كلماتك إلى استدعاءات CLI تعمل بصفتك: ```mermaid flowchart TD - YOU["أنت: 'اعترف بالحادثة النشطة'"] --> AGENT["وكيل ترميز (Claude Code / Codex)
يحمل مهارة agenteye-cli"] + YOU["أنت: 'أقر الحادثة النشطة'"] --> AGENT["وكيل التشفير (Claude Code / Codex)
يحمل مهارة agenteye-cli"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|جلسة CLI موثقة لديك| API["واجهة برمجية لوحة معلومات Observability"] + CLI -->|جلسة CLI المصرح بها الخاصة بك| API["واجهة برمجة تطبيقات لوحة معلومات Observability"] ``` ### مقابل مساعد AI في لوحة المعلومات: تمييز مهم -هذان أداتان مختلفتان جداً بنطاقات انفجار مختلفة جداً: +هذان أداتان مختلفتان جداً مع نطاقات تأثير مختلفة جداً: -- **مساعد AI في لوحة المعلومات** ([مساعد AI](/ar/agenteye/assistant)) هو دردشة مضمنة في لوحة المعلومات، مدعومة بخدمة الوكيل. إنها **قراءة فقط بالإضافة إلى تأليف محمي بموافقة**: يمكنها صياغة الاستعلامات والمحاور المحفوظة، لكن كل عملية كتابة تتوقف لموافقتك الصريحة بالنقر، ولا تحذف أبداً. يتم حمايتها بواسطة إذن `agent:use` وترى فقط البيانات للمؤسسة التي تعرضها. -- **مهارة CLI** تعمل على *محطة العمل الخاصة بك* داخل *وكيل ترميز خاص بك* وتشغل CLI `agenteye` بـ **أنت**. يمكنها تنفيذ **السطح الكامل للـ CLI، بما في ذلك التغييرات** (إنشاء/تدوير/تعطيل مفاتيح API، تغيير إعدادات المؤسسة، حل الحوادث، حذف الاستعلامات المحفوظة)، محدودة فقط بأذونات تسجيل دخول CLI الخاص بك. تعامل معها بنفس الحذر الذي ستتعامل به إذا قمت بتشغيل تلك الأوامر يدوياً. +- **مساعد AI في لوحة المعلومات** ([مساعد AI](/ar/agenteye/assistant)) عبارة عن دردشة مضمنة في لوحة المعلومات، مدعومة بخدمة الوكيل. إنه **للقراءة فقط بالإضافة إلى التأليف المحمي بالموافقة**: يمكنه صياغة الاستعلامات والتحليلات المحفوظة، لكن كل عملية كتابة توقفها انتظار نقرتك الصريحة، وهو لا يحذف أبداً. يتم حمايتها بواسطة إذن `agent:use` وترى فقط البيانات الخاصة بالمنظمة التي تعرضها. +- **مهارة CLI** تعمل على *محطة العمل الخاصة بك* داخل *وكيل التشفير الخاص بك* وتشغل CLI `agenteye` كـ **أنت**. يمكنها تنفيذ **السطح الكامل للـ CLI، بما في ذلك الطفرات** (إنشاء/تدوير/تعطيل مفاتيح API، تغيير إعدادات المنظمة، حل الحوادث، حذف الاستعلامات المحفوظة)، محدودة فقط بأذونات تسجيل دخول CLI. تعامل معها بنفس الحذر الذي ستتعامل به عند تشغيل تلك الأوامر يدويًا. --- ## المتطلبات الأساسية -1. **`agenteye` CLI مثبتة** وعلى `PATH` (انظر [مرجع CLI](/ar/agenteye/cli): `pipx install agenteye`). -2. **عنوان URL لوحة المعلومات الخاصة بك** محدد (`AGENTEYE_DASHBOARD_URL`، أو يمرر الوكيل `--base-url`). -3. **جلسة مسجلة الدخول**: قم بتشغيل `agenteye login` بنفسك أولاً. المهارة **لا يمكنها** إكمال تسجيل الدخول برمز لمرة واحدة عبر البريد الإلكتروني نيابة عنك؛ ستخبرك أن تشغل `agenteye login` إذا كانت الجلسة مفقودة أو منتهية الصلاحية (رمز خروج CLI `4`). +1. **`agenteye` CLI مثبت** وفي `PATH` (انظر مرجع [CLI](/ar/agenteye/cli): `pipx install agenteye`). +2. **عنوان URL لوحة المعلومات الخاصة بك** معين (`AGENTEYE_DASHBOARD_URL`، أو يمرر الوكيل `--base-url`). +3. **جلسة عمل مسجلة**: قم بتشغيل `agenteye login` بنفسك أولاً. المهارة **لا يمكنها** إكمال تسجيل الدخول برمز لمرة واحدة عبر البريد الإلكتروني نيابة عنك؛ ستخبرك بتشغيل `agenteye login` إذا كانت الجلسة مفقودة أو منتهية الصلاحية (كود خروج CLI `4`). --- -## حيث تحصل عليها +## أين تحصل عليها تُنشر المهارة في مجموعة المهارات العامة لـ Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -لا شيء محمي في ذلك — المستودع عام والمهارة لا تحتاج إلى بيانات اعتماد خاصة بها، لأنها تشغل فقط `agenteye` CLI **العام** ضد لوحة المعلومات *الخاصة بك*، باستخدام الجلسة *التي سجلت بها الدخول*. لا تحتاج إلى طلب إذن من أحد. +لا يوجد شيء محمي بها — المستودع عام والمهارة لا تحتاج إلى بيانات اعتماد خاصة بها، لأنها تشغل فقط CLI `agenteye` **العام** مقابل لوحة المعلومات الخاصة بك، باستخدام الجلسة *التي* سجلت الدخول إليها. لا تحتاج إلى طلب الإذن من أي شخص. -لاحظ أنها تأتي كمجلد خاص بها و**ليست** داخل حزمة `pipx install agenteye`، لذا لا تبحث عنها هناك. +لاحظ أنها تأتي كمجلد خاص بها وهي **ليست** داخل حزمة `pipx install agenteye`، لذلك لا تبحث عنها هناك. ## تثبيت المهارة -أسرع طريق هي [`skills`](https://skills.sh) CLI، التي تجلب المجلد وتضعه حيث ينظر وكيلك: +الطريق الأسرع هو CLI [`skills`](https://skills.sh)، الذي يجلب المجلد ويضعه حيث ينظر وكيلك: ```bash # Claude Code، هذا المشروع فقط npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -# كل مشروع (التثبيت في ~/.claude/skills/) +# كل مشروع (يثبت إلى ~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy # Codex بدلاً من ذلك npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -ثم أدرها مثل أي مهارة أخرى: +ثم أدره مثل أي مهارة أخرى: ```bash npx skills list -a claude-code # ما هو مثبت npx skills update agenteye-cli # اسحب أحدث إصدار -npx skills remove agenteye-cli # أزلها +npx skills remove agenteye-cli # احذفه ``` -تفضل التثبيت يدوياً؟ مهارة عامل ما هي إلا مجلد يحتوي على `SKILL.md` (بالإضافة إلى مراجع اختيارية)، لذا نسخها يعمل أيضاً: +تفضل التثبيت يدويًا؟ مهارة الوكيل مجرد مجلد يحتوي على `SKILL.md` (بالإضافة إلى المراجع الاختيارية)، لذا يعمل النسخ أيضًا: -- **Claude Code**: ضع مجلد `agenteye-cli/` في `~/.claude/skills/` (كل مشروع) أو `/.claude/skills/` (ذلك المستودع فقط). Claude Code يكتشفه تلقائياً — تحقق من قائمة `/skills`، أو ببساطة اسأل سؤالاً يطابق وصفه. -- **Codex (OpenAI)**: يقرأ Codex نفس `SKILL.md`. يعيّن `agents/openai.yaml` المضمن `allow_implicit_invocation: true`، لذا يختار Codex المهارة تلقائياً عندما تطابق المهمة؛ وإلا قم باستدعاؤها بشكل صريح كـ `$agenteye-cli`. +- **Claude Code**: ضع مجلد `agenteye-cli/` في `~/.claude/skills/` (كل مشروع) أو `/.claude/skills/` (هذا المستودع فقط). Claude Code يكتشفها تلقائياً — تحقق من خلال قائمة `/skills`، أو ببساطة اسأل سؤالاً يطابق وصفها. +- **Codex (OpenAI)**: يقرأ Codex نفس `SKILL.md`. يعيّن الملف `agents/openai.yaml` المرفق `allow_implicit_invocation: true`، لذا يختار Codex المهارة تلقائياً عند مطابقة مهمة؛ وإلا استدعها بوضوح كـ `$agenteye-cli`. --- -## الأمان: التغييرات لا تطلب موافقة عندما يشغل الوكيل CLI +## الأمان: الطفرات لا تطالب عندما يشغل وكيل CLI > **تحذير:** اقرأ هذا قبل السماح لوكيل بإجراء تغييرات. -CLI `agenteye` عادة ما يسأل *"هل أنت متأكد؟"* قبل إجراء تدميري. إنه **يتخطى هذا التأكيد تلقائياً كلما لم يكن متصلاً بمحطة طرفية (وهذا بالضبط كيفية تشغيل الوكيل له)، و `--json` يتخطاه أيضاً.** لذا فإن موجه الأمان لن **ينطلق** للوكيل. +يسأل CLI `agenteye` عادةً *"هل أنت متأكد؟"* قبل إجراء مدمّر. إنه **يتخطى تلك الموافقة تلقائياً كلما لم تكن مرتبطة بجهاز محطة (وهو بالضبط كيفية تشغيل وكيل لها)، و `--json` يتخطاها أيضاً.** لذا فإن موجه الأمان **لن** يُطلق للوكيل. -تمت كتابة المهارة للتعويض: تم تعليمها بيان الأمر الدقيق الذي ستشغله والحصول على موافقتك الصريحة **OK قبل أي تغيير في الحالة**. حافظ على هذا النظام. عندما تشغل Failproof AI Observability من خلال وكيل، *أنت* خطوة التأكيد. أوامر تغيير الحالة التي يجب مراقبتها: +المهارة مكتوبة للتعويض: يتم تدريسها على ذكر الأمر الدقيق الذي ستشغله والحصول على موافقتك الصريحة **OK قبل أي تغيير الحالة**. حافظ على هذا النظام. عندما تشغل Failproof AI Observability من خلال وكيل، *أنت* هو خطوة التأكيد. أوامر تغيير الحالة التي يجب الانتباه لها: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` - `settings set` - `alerts create` / `update` / `delete` / `test` -- أوامر الكتابة في `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` +- أوامر الكتابة `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` - `query create` / `update` / `delete` - `agent rename` / `delete` - `orgs switch` -كل شيء تحت **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) للقراءة فقط ولا يغير شيء. +كل شيء تحت **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) للقراءة فقط ولا يغير شيئاً. -لأن الوكيل يتصرف ب **أنت**، يمكنه فقط القيام بما يسمح به تسجيل دخولك؛ يتم حل الأذونات **لكل منظمة** (انظر [مفاتيح API](/ar/agenteye/api-keys)). الأمر الذي لا تملك إذناً له يرجع رمز خروج `5` مع الإذن المحدد بالضبط، لذا يمكن للوكيل أن يخبرك بالضبط ما الذي يجب عليك طلبه من المسؤول بدلاً من الفشل بشكل غير واضح. +لأن الوكيل يعمل كـ **أنت**، يمكنه فعل ما يسمح به تسجيل الدخول الخاص بك فقط؛ يتم حل الأذونات **لكل منظمة** (انظر [مفاتيح API](/ar/agenteye/api-keys)). أمر تفتقد إلى إذن له يُرجع كود خروج `5` مع الإذن المسمى تماماً، لذا يمكن للوكيل أن يخبرك بالضبط ما يجب أن تطلبه من المسؤول بدلاً من الفشل بشكل غامض. --- ## ما الذي يمكنك أن تسأله -إليك ما يبدو عليه جولة ذهاب وإياب حقيقية، قراءة ثم تغيير ينتظر موافقتك: +إليك ما يبدو عليه رحلة حقيقية ذهاباً وإياباً، قراءة، ثم تغيير ينتظر موافقتك: ```text -أنت ▸ هل حدث عطل ما في اليوم الأخير؟ +أنت ▸ هل هناك أي شيء معطوب في اليوم الماضي؟ وكيل ▸ تشغيل: agenteye --json errors --since 24h --aggregate - 3 أنواع أخطاء في آخر 24 ساعة. الأكبر هو TimeoutError - (18 نقرة، جميعها على checkout-agent)، ثم RateLimited (5). - تريد الجلسات الفاشلة لـ TimeoutError؟ + 3 أنواع أخطاء في آخر 24 ساعة. الأكبر هو TimeoutError + (18 ضربة، جميعها على checkout-agent)، ثم RateLimited (5). + تريد الجلسات الفاشلة لـ TimeoutError؟ -أنت ▸ أعط CI مفتاح يمكنه فقط دفع الأحداث. +أنت ▸ أعط CI مفتاحًا يمكنه فقط دفع الأحداث. وكيل ▸ هذا ينشئ مفتاح API. سأشغل: - agenteye keys create ci --add events:add - OK للمتابعة؟ + agenteye keys create ci --add events:add + موافق على المتابعة؟ أنت ▸ نعم -وكيل ▸ تم. تم إنشاء المفتاح "ci" مع events:add فقط. - يتم عرض السر مرة واحدة فقط، لذا قم بتخزينه الآن. لا يمكنني إعادة طباعته. +وكيل ▸ تم. تم إنشاء المفتاح "ci" بـ events:add فقط. + يتم عرض السري مرة واحدة فقط، لذا احفظه الآن. لا يمكنني طباعته مرة أخرى. ``` -تعيّن المهارة كل نية باللغة الإنجليزية العادية إلى أمر `agenteye` الصحيح، واكتشف القيم الصحيحة أولاً (`list `, `whoami`) حتى لا تخمن، وحدد الأمر الدقيق قبل أي تغيير. المزيد من الأمثلة: +تعيّن المهارة كل نية باللغة الطبيعية إلى أمر `agenteye` الصحيح، اكتشف القيم الصحيحة أولاً (`list `, `whoami`) حتى لا تخمّن، وحدد الأمر الدقيق قبل أي تغيير. المزيد من الأمثلة: -- *"هل حدث عطل / فشل في آخر 24 ساعة؟"* → `errors --since 24h --aggregate`، ثم تفصيل. -- *"لماذا فشلت الجلسة `run-001`؟"* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *"كيف تتجه الجودة هذا الأسبوع؟"* → `evals --aggregate --since 7d`، ثم الحفر في التشغيلات منخفضة التسجيل. -- *"أعط CI مفتاح يمكنه فقط دفع الأحداث."* → `keys create ci --add events:add` (يحدد الأمر، ثم ينشئه ويأسر السر لمرة واحدة). -- *"من لديه حق الوصول؟ اجعل Dana للقراءة فقط."* → `users list` → `users update dana@… --permission-set read-only` (بعد التأكيد معك). -- *"اعترف بالحادثة النشطة وعينها لي."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. +- *"هل هناك أي شيء معطوب / فاشل في آخر 24 ساعة؟"* → `errors --since 24h --aggregate`، ثم تفصيل. +- *"لماذا فشلت جلسة `run-001`؟"* → `events --session-id run-001 --all` + `evals --session-id run-001`. +- *"كيف تتجه الجودة هذا الأسبوع؟"* → `evals --aggregate --since 7d`، ثم تفصيل التشغيل منخفض التصنيف. +- *"أعط CI مفتاحًا يمكنه فقط دفع الأحداث."* → `keys create ci --add events:add` (ينص على الأمر، ثم ينشئه ويلتقط السر لمرة واحدة). +- *"من لديه وصول؟ اجعل Dana للقراءة فقط."* → `users list` → `users update dana@… --permission-set read-only` (بعد التأكيد معك). +- *"أقر الحادثة النشطة وأسندها إليّ."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. -للأوامر والخيارات والأشكال JSON الدقيقة خلف هذا، انظر [مرجع CLI](/ar/agenteye/cli) و[وصفات CLI للوكلاء](/ar/agenteye/cli-recipes). +للأوامر الدقيقة والعلامات وأشكال JSON وراء هذه، انظر مرجع [CLI](/ar/agenteye/cli) و [وصفات CLI للوكلاء](/ar/agenteye/cli-recipes). --- ## الخطوات التالية -- **[CLI](/ar/agenteye/cli)**: مرجع أمر وخيار كامل لـ `agenteye`. -- **[وصفات CLI للوكلاء](/ar/agenteye/cli-recipes)**: أنماط `jq` جاهزة للنسخ ومعالجة رموز الخروج. -- **[مهارة وكيل المقيّم](/ar/agenteye/evaluator-skill)**: المهارة الشقيقة، لبناء المقيّم الذي تقرأه `agenteye evals`. -- **[مهارة وكيل Python SDK](/ar/agenteye/python-sdk-skill)**: المهارة الشقيقة، لتجهيز وكيل حتى يصدر البيانات التي يقرأها `agenteye`. -- **[مساعد AI](/ar/agenteye/assistant)**: مساعد لوحة المعلومات (لا تخلطها مع مهارة المحطة الطرفية هذه). -- **[مفاتيح API](/ar/agenteye/api-keys)**: نموذج الأذونات لكل منظمة الذي يحدد ما يمكن للمهارة القيام به. \ No newline at end of file +- **[CLI](/ar/agenteye/cli)**: مرجع أوامر وعلامات كامل لـ `agenteye`. +- **[وصفات CLI للوكلاء](/ar/agenteye/cli-recipes)**: أنماط `jq` نسخ-لصق ومعالجة كود الخروج. +- **[مهارة وكيل المقيّم](/ar/agenteye/evaluator-skill)**: المهارة الأخت، لبناء المقيّم الذي تقرأه `agenteye evals` درجاتها. +- **[مهارة وكيل Python SDK](/ar/agenteye/python-sdk-skill)**: المهارة الأخت، لقياس وكيل بحيث ينبعث قياس `agenteye` يقرأه. +- **[مساعد AI](/ar/agenteye/assistant)**: مساعد لوحة المعلومات (لا تخلط بينه وبين مهارة المحطة الطرفية هذه). +- **[مفاتيح API](/ar/agenteye/api-keys)**: نموذج الأذونات لكل منظمة الذي يحدد ما يمكن للمهارة فعله. \ No newline at end of file diff --git a/docs/ar/agenteye/cli.mdx b/docs/ar/agenteye/cli.mdx index 5f59330b..a16fb5fd 100644 --- a/docs/ar/agenteye/cli.mdx +++ b/docs/ar/agenteye/cli.mdx @@ -1,24 +1,24 @@ --- -title: "واجهة سطر الأوامر (CLI)" -description: "قم بتشغيل كل عمليات Failproof AI Observability من المحطة الطرفية أو من نص برمجي: بدون الحاجة إلى لوحة التحكم." +title: "CLI" +description: "قُد كل عمليات Failproof AI Observability من المحطة الطرفية أو من سكريبت: بدون الحاجة لزيارة لوحة التحكم." --- -قم بتشغيل كل عمليات Failproof AI Observability من المحطة الطرفية أو من نص برمجي: بدون الحاجة إلى لوحة التحكم. يستعلم CLI `agenteye` عن بيانات النظام (الجلسات وسجلات الأحداث والتقييمات) ويدير مؤسستك (مفاتيح API والمستخدمون والإعدادات والتنبيهات والحوادث والاستعلامات المحفوظة)، لذا استخدمه عندما تريد أتمتة فحص أو دمج الملاحظة في CI أو السماح لوكيل ترميز بفحص الإنتاج. يدعم كل أمر علم `--json`، لذلك يعمل بنفس الكفاءة سواء كنت في موجه الأوامر أو وكيل ترميز (Claude Code أو Cursor) يقوم بتنفيذ الأمر وتحليل النتيجة. +قُد كل عمليات Failproof AI Observability من المحطة الطرفية أو من سكريبت: بدون الحاجة لزيارة لوحة التحكم. إن CLI `agenteye` يستعلم عن بيانات لديك (الجلسات، سجلات الأحداث، التقييمات) ويدير مؤسستك (مفاتيح API، المستخدمون، الإعدادات، التنبيهات، الحوادث، الاستعلامات المحفوظة)، لذا استخدمه عندما تريد أتمتة فحص، أو دمج Observability في CI، أو السماح لوكيل برمجي بفحص الإنتاج. كل أمر يدعم علم `--json`، لذا يعمل بنفس الفعالية سواء كنت في موجه أوامر أو كنت وكيل برمجي (Claude Code أو Cursor) ينفذ الأوامر ويحلل النتائج. -باستخدام ملف ثنائي واحد يمكنك: +باستخدام ملف تنفيذي واحد يمكنك: -- **قراءة بيانانك**: `sessions` و `events` و `evals` و `errors` (تصفية حسب الوقت والوكيل والبيئة والنتيجة). +- **قراءة بيانات لديك**: `sessions` و `events` و `evals` و `errors` (تصفية حسب الوقت والوكيل والبيئة والنتيجة). - **إدارة مؤسستك**: `keys` و `users` و `settings` و `alerts` و `incidents`. -- **تشغيل التحليلات**: SQL محفوظ وأداة استعلام مخصصة (`query`). -- **اطلب من مساعد الذكاء الاصطناعي**: نفس محلل القراءة فقط الذي تتحدث معه في لوحة التحكم (`agent`). +- **تشغيل التحليلات**: SQL محفوظة وأداة استعلام مخصصة (`query`). +- **اسأل مساعد الذكاء الاصطناعي**: نفس محلل القراءة فقط الذي تتحدث معه في لوحة التحكم (`agent`). -> **ملاحظة:** هذا هو CLI `agenteye`، وهي أداة مختلفة عن عفريت المجمع (`agenteye-collector`). يتحدث CLI مع لوحة التحكم الخاصة بك؛ المجمع يرسل الأحداث إلى الخادم. +> **ملاحظة:** هذا هو CLI `agenteye`، أداة مختلفة عن مراقب التجميع (`agenteye-collector`). يتحدث CLI مع لوحة التحكم؛ يشحن المجمع الأحداث إلى الخادم. --- -## البدء السريع +## البداية السريعة -من الصفر إلى أول نتيجة في أربعة أسطر. وجه CLI إلى لوحة التحكم الخاصة بك وقم بتسجيل الدخول والتأكد من هويتك ثم اسحب آخر يوم من التشغيلات: +من العدم إلى أول نتيجة في أربعة أسطر. وجّه CLI نحو لوحة التحكم لديك، وسجّل الدخول، وأكّد من أنت، ثم اسحب آخر يوم من التشغيل: ```bash pipx install agenteye @@ -27,7 +27,7 @@ agenteye whoami agenteye --json sessions --since 24h # one row per agent run, last 24h ``` -يطبع الأمر الأخير كائن JSON للجلسات الأخيرة (الأحدث أولاً، محدود بـ 50 افتراضياً). أرسله عبر أنابيب إلى `jq` لتقطيعه، أو أزل `--json` للحصول على جدول مربع وملون. يحمل كل صف حالة التشغيل والنتائج المترية إذا قام المقيم بتقييمه (مختصرة هنا): +يطبع هذا الأمر الأخير كائن JSON بأحدث الجلسات (الأحدث أولاً، محدود بـ 50 بشكل افتراضي). أنابه في `jq` لتقسيمه، أو أزل `--json` للحصول على جدول مربع وملون. يحمل كل صف حالة التشغيل والنتائج (اختصار هنا): ```json { @@ -47,13 +47,13 @@ agenteye --json sessions --since 24h } ``` -يشرح بقية هذه الصفحة كل جزء: [التثبيت](#installation) بشكل منفصل و [تسجيل الدخول](#authentication) و [الإعدادات](#configuration) و [الاتفاقيات العامة](#global-options--conventions) التي تشاركها كل أمر و [مرجع الأمر الكامل](#command-reference). +يشرح الجزء المتبقي من هذه الصفحة كل قطعة: [التثبيت](#installation) بشكل منفصل، [تسجيل الدخول](#authentication)، [الإعدادات](#configuration)، [الخيارات العامة](#global-options--conventions) التي يشاركها كل أمر، و[مرجع الأوامر الكامل](#command-reference). --- ## التثبيت -CLI عبارة عن حزمة PyPI عامة تسمى **`agenteye`**. ثبتها في بيئة معزولة حتى يكون لديها دائماً اعتماديات خاصة بها: +CLI هي حزمة PyPI عامة باسم **`agenteye`**. ثبتها في بيئة معزولة حتى تحصل دائماً على اعتمادياتها الخاصة: ```bash pipx install agenteye @@ -61,40 +61,40 @@ pipx install agenteye uv tool install agenteye ``` -تتطلب Python 3.10+. الأمر المثبت هو **`agenteye`**: +يتطلب Python 3.10+. الأمر المثبت هو **`agenteye`**: ```bash agenteye --version agenteye --help ``` -> **ملاحظة:** SDK Python الخاص بـ Failproof AI Observability يستخدم أيضاً اسم توزيع `agenteye`. يحافظ تثبيت CLI باستخدام `pipx` أو `uv tool` (بدلاً من `pip install` في virtualenv مشترك) على عدم تضارب الاثنين. `pip install agenteye` عادي جيد فقط إذا لم يكن SDK مثبتاً في نفس البيئة. +> **ملاحظة:** Failproof AI Observability Python SDK يستخدم أيضاً اسم التوزيع `agenteye`. التثبيت عبر `pipx` أو `uv tool` (بدلاً من `pip install` في بيئة virtualenv مشتركة) يمنع التضارب بين الاثنين. `pip install agenteye` البسيط مقبول فقط إذا لم يكن SDK مثبتاً في نفس البيئة. --- ## المصادقة -يوثق CLI إلى **لوحة التحكم** باستخدام كود لمرة واحدة يتم إرساله بالبريد الإلكتروني: +يقوم CLI بمصادقة **لوحة التحكم** باستخدام رمز لمرة واحدة مرسل عبر البريد الإلكتروني: ```bash agenteye login --email you@example.com # A 6-digit code is emailed to you; paste it at the prompt. ``` -يتم حفظ رمز الجلسة في `~/.agenteye/cli.json` (قابل للقراءة فقط من قبلك، mode `0600`) وصالح لمدة 24 ساعة افتراضياً. عند انتهاء صلاحيته، قم بتشغيل `agenteye login` مرة أخرى. +يتم تخزين رمز الجلسة في `~/.agenteye/cli.json` (يمكن قراءته فقط من قِبلك، الوضع `0600`) ويكون صالحاً لمدة 24 ساعة بشكل افتراضي. عند انتهاء صلاحيته، قم بتشغيل `agenteye login` مرة أخرى. ```bash agenteye whoami # show the current user, active org, and permissions agenteye logout # revoke the session and clear the stored token ``` -لا يخطئ `whoami` أبداً في جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك يبلغ عن `logged_in: false`، لذا يمكن لنص برمجي أو وكيل التحقق من حالة المصادقة بأمان (لا يزال يمكن أن يخرج مع كود غير صفري إذا لم يتم تعيين عنوان URL أساسي أو كانت لوحة التحكم غير قابلة للوصول). +`whoami` لا يخطئ أبداً في جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك يبلغ `logged_in: false`، لذا يمكن للسكريبت أو الوكيل اختبار حالة المصادقة بأمان (لا يزال يمكن أن ينهي بكود غير صفري إذا لم يتم تعيين أساس URL أو كانت لوحة التحكم غير قابلة للوصول). -**المتطلبات:** يجب السماح لبريدك الإلكتروني بتسجيل الدخول إلى لوحة التحكم (اطلب من مسؤول Failproof AI Observability)، ويجب أن تكون لوحة التحكم قابلة للوصول على عنوان URL الأساسي الخاص بها (انظر [الإعدادات](#configuration)). إذا طلبت كوداً ولم يصل أي، فمن المحتمل أن بريدك الإلكتروني لم يتم تفعيله بعد للوصول إلى لوحة التحكم. +**المتطلبات:** يجب السماح لبريدك الإلكتروني بتسجيل الدخول إلى لوحة التحكم (اطلب من مسؤول Failproof AI Observability)، ويجب أن تكون لوحة التحكم قابلة للوصول على عنوان URL الأساسي (انظر [الإعدادات](#configuration)). إذا طلبت رمزاً ولم يصل أي شيء، فمن المحتمل أن بريدك الإلكتروني لم يتم تفعيله بعد للوصول إلى لوحة التحكم. --- -## اختيار مؤسستك (متعدد الإيجار) +## اختيار المؤسسة الخاصة بك (متعدد المستأجرين) إذا كان حسابك ينتمي إلى أكثر من مؤسسة واحدة، اختر المؤسسة النشطة **عند تسجيل الدخول**؛ يتم حفظها واستخدامها لكل أمر لاحق: @@ -105,7 +105,7 @@ agenteye orgs switch globex # change the saved default agenteye --org globex sessions # override for a single command ``` -إذا كنت تنتمي إلى مؤسسة واحدة بالضبط، يتم اختيارها تلقائياً ويمكنك تجاهل `--org` تماماً. إذا كنت تنتمي إلى عدة مؤسسات ولم تختر واحدة، يسرد CLI القائمة ويطلب منك إعادة التشغيل باستخدام `--org `. يتم إرسال المؤسسة النشطة إلى لوحة التحكم في كل طلب، وتتم معالجة أذوناتك **لكل مؤسسة**؛ `agenteye whoami` يظهر المؤسسة النشطة وأذوناتك فيها وجميع عضوياتك. +إذا كنت تنتمي إلى مؤسسة واحدة فقط، يتم اختيارها تلقائياً ويمكنك تجاهل `--org` تماماً. إذا كنت تنتمي إلى عدة ولم تختر واحدة، يسرد CLI الخيارات ويطلب منك إعادة التشغيل باستخدام `--org `. يتم إرسال المؤسسة النشطة إلى لوحة التحكم في كل طلب، ويتم حل الأذونات الخاصة بك **لكل مؤسسة**؛ `agenteye whoami` يظهر المؤسسة النشطة والأذونات الخاصة بك فيها وكل العضويات الخاصة بك. --- @@ -113,43 +113,43 @@ agenteye --org globex sessions # override for a single command | الإعداد | العلم | متغير البيئة | الافتراضي | |---|---|---|---| -| عنوان URL الأساسي للوحة التحكم | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **مطلوب** (لا يوجد افتراضي) | +| عنوان URL الأساسي للوحة التحكم | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **مطلوب** (بدون افتراضي) | | المؤسسة/المستأجر النشط | `--org` | `AGENTEYE_ORG` | مختار عند تسجيل الدخول؛ محفوظ في `~/.agenteye/cli.json` | | رمز الجلسة | `--token` | `AGENTEYE_CLI_TOKEN` | من `~/.agenteye/cli.json` | -| مخرجات JSON | `--json` | `AGENTEYE_CLI_JSON` | إيقاف | -| تخطي التحقق من TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | إيقاف (محفوظ عند تسجيل الدخول) | -| مهلة الطلب (بالثواني) | `--timeout` | _(none)_ | 30 | -| تعطيل قياس الاستخدام | _(none)_ | `AGENTEYE_ANALYTICS_DISABLED` (أو `DO_NOT_TRACK`) | قياس الاستخدام معطل حالياً؛ لا يتم إرسال شيء | +| إخراج JSON | `--json` | `AGENTEYE_CLI_JSON` | معطل | +| تخطي التحقق من TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | معطل (محفوظ عند تسجيل الدخول) | +| انتظار الطلب (بالثواني) | `--timeout` | _(none)_ | 30 | +| تعطيل القياس المستخدم | _(none)_ | `AGENTEYE_ANALYTICS_DISABLED` (أو `DO_NOT_TRACK`) | القياس معطل حالياً؛ لا يتم إرسال أي شيء | -ترتيب الدقة هو **العلم → متغير البيئة → ملف الإعدادات**. لا يوجد افتراضي؛ يجب عليك توجيه CLI إلى لوحة التحكم الخاصة بك، إما لكل أمر (`--base-url https://agenteye.example.com`) أو مرة واحدة عبر البيئة (يتم حفظها أيضاً بعد أول `login`): +ترتيب الحل هو **العلم → متغير البيئة → ملف الإعدادات**. لا يوجد افتراضي؛ يجب عليك توجيه CLI نحو لوحة التحكم الخاصة بك، إما لكل أمر (`--base-url https://agenteye.example.com`) أو مرة واحدة عبر البيئة (يتم حفظها أيضاً بعد أول `login`): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -يحترم دليل الإعدادات `AGENTEYE_HOME` (نفس الاتفاقية المستخدمة من قبل SDK والمجمع)؛ إذا تم التعيين، يعيش `cli.json` في `$AGENTEYE_HOME/cli.json`. +دليل الإعدادات يحترم `AGENTEYE_HOME` (نفس الاتفاقية المستخدمة من قِبل SDK والمجمع)؛ إذا تم تعيينه، يعيش `cli.json` في `$AGENTEYE_HOME/cli.json`. ### TLS ذاتي التوقيع أو داخلي -إذا كانت لوحة التحكم الخاصة بك تُقدم عبر HTTPS مع شهادة ذاتية التوقيع أو داخلية (على سبيل المثال، اسم مضيف موازن تحميل خام)، يرفضها التحقق من TLS مع خطأ `CERTIFICATE_VERIFY_FAILED`. مرر `--insecure` لتخطي التحقق من الشهادة: +إذا تم تقديم لوحة التحكم الخاصة بك عبر HTTPS باستخدام شهادة ذاتية التوقيع أو داخلية (على سبيل المثال، اسم مضيف موازن تحميل خام)، سيرفضها التحقق من TLS برسالة `CERTIFICATE_VERIFY_FAILED`. مرر `--insecure` لتخطي التحقق من الشهادات: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -يتم **حفظ `--insecure` إلى `cli.json` عند تسجيل الدخول**، لذلك تتخطى الأوامر اللاحقة التحقق تلقائياً؛ لا تضطر إلى تكرار العلم. مرر `--secure` لاستدعاء موثق لمرة واحدة، أو لحفظ التحقق مرة أخرى عند تسجيل الدخول التالي. يطبع CLI تحذيراً على stderr قبل أي أمر يتواصل مع لوحة التحكم أثناء تعطيل التحقق. يزيل تخطي التحقق الحماية من هجمات الرجل في الوسط؛ تأكد من أنك تثق بمسار الشبكة إلى لوحة التحكم الخاصة بك (VPN أو subnet خاص وما إلى ذلك) قبل الاعتماد عليه. +يتم **حفظ `--insecure` في `cli.json` عند تسجيل الدخول**، لذا تتخطى الأوامر اللاحقة التحقق تلقائياً؛ لا تحتاج إلى تكرار العلم. مرر `--secure` لاستدعاء تحقق مرة واحدة، أو لحفظ التحقق مرة أخرى في تسجيل الدخول التالي. يطبع CLI تحذيراً على stderr قبل أي أمر يتصل بلوحة التحكم بينما يكون التحقق معطلاً. تخطي التحقق يزيل الحماية ضد هجمات الرجل في الوسط؛ تأكد من أنك تثق في مسار الشبكة إلى لوحة التحكم الخاصة بك (VPN أو شبكة فرعية خاصة، إلخ) قبل الاعتماد عليه. --- -## قياس الاستخدام والخصوصية +## القياس والخصوصية -> **ملاحظة:** CLI المُشحون **لا يرسل قياس اليستخدام اليوم.** مفتاح القتل الرئيسي مفعل، لذلك لا يتم نقل شيء بغض النظر عن البيئة الخاصة بك. يوضح القسم أدناه إمكانية عدم الاشتراك في حالة تفعيل قياس الاستخدام في المستقبل. +> **ملاحظة:** CLI المُشحون **لا يرسل قياس استخدام اليوم.** يوجد مفتاح إيقاف رئيسي، لذا لا يتم نقل أي شيء بغض النظر عن بيئتك. يصف القسم أدناه قدرة الانسحاب في حالة تفعيل القياس يوماً ما. -حتى عند تفعيله، سيكون قياس الاستخدام **فقط تحليلات الاستخدام المجهولة**، وليس أبداً وكيلك أو جلستك أو بيانات الحدث: +حتى عند التفعيل، سيكون القياس **تحليلات استخدام مجهولة فقط**، لا بيانات الوكيل أو الجلسة أو الحدث: -- **لا تترك بيانات الوكيل أو الجلسة أو الحدث أبداً البنية التحتية الخاصة بك.** سيتم الإبلاغ عن استخدام CLI فقط: اسم الأمر والأمر الفرعي (على سبيل المثال `keys create`)، و **أسماء** الأعلام التي استخدمتها (وليس قيمها أبداً)، وحالة النجاح/الخروج والمدة، بالإضافة إلى حدث لكل إجراء للطفرات (على سبيل المثال `api_key_created` و `query_run`) يحمل فقط الأسماء الثابتة/التعداد والأعداد الإجمالية. عنوان URL لوحة التحكم الخاصة بك ورمز الجلسة والبريد الإلكتروني وslug المؤسسة وhids الموارد و SQL وأسرار المفاتيح وفلاتر الاستعلام **لن** يتم إرسالها أبداً. سيتم تحديد المشغلين فقط بواسطة معرف داخلي معتم، وليس بالبريد الإلكتروني. -- **لا تشترك مقدماً** بتعيين `AGENTEYE_ANALYTICS_DISABLED=1` في بيئة CLI (يحترم CLI أيضاً اتفاقية أداة متقاطعة `DO_NOT_TRACK=1`). يسري هذا في اللحظة التي يتم فيها تفعيل قياس الاستخدام، لذا يمكن للبيئة الواعية بالخصوصية البقاء غير مشترك إلى الأبد. -- إذا تم تفعيل قياس الاستخدام، فسيرسل CLI مباشرة إلى PostHog (`https://us.i.posthog.com`)؛ الجهاز الذي لديه هذا المضيف محظور سيرسل بصمت شيء والـ CLI لن يتأثر. +- **لا يترك بيانات الوكيل أو الجلسة أو الحدث البنية التحتية الخاصة بك أبداً.** فقط استخدام CLI سيتم الإبلاغ عنه: اسم الأمر والأوامر الفرعية (على سبيل المثال `keys create`)، **أسماء** الأعلام التي استخدمتها (لا قيم)، حالة النجاح/الخروج، والمدة، بالإضافة إلى حدث لكل إجراء للطفرات (على سبيل المثال `api_key_created` و `query_run`) تحمل فقط الأسماء الثابتة/التعداديات والأعداد الخشنة. عنوان URL لوحة التحكم الخاصة بك، رمز الجلسة، البريد الإلكتروني، شريط المؤسسة، معرّفات الموارد، SQL، أسرار المفاتيح، وعوامل تصفية الاستعلام **لن** يتم إرسالها أبداً. سيتم تحديد المشغلين فقط بمعرّف داخلي معتم، وليس بالبريد الإلكتروني. +- **الانسحاب مسبقاً** بتعيين `AGENTEYE_ANALYTICS_DISABLED=1` في بيئة CLI (يحترم CLI أيضاً اتفاقية `DO_NOT_TRACK=1` عبر الأدوات). يأخذ التأثير اللحظة التي يتم فيها تشغيل القياس، لذا يمكن للبيئة المراعية للخصوصية البقاء منسحبة بشكل دائم. +- إذا تم تشغيل القياس، فسيرسل CLI مباشرة إلى PostHog (`https://us.i.posthog.com`)؛ ستصمت آلة مع هذا المضيف المحظور تماماً ولن يتأثر CLI. --- @@ -157,35 +157,35 @@ agenteye --base-url https://agenteye.internal --insecure login اقرأ هذا مرة واحدة؛ ينطبق على كل أمر. -- **تذهب الخيارات العامة قبل الأمر.** `agenteye --json sessions` صحيح؛ `agenteye sessions --json` خطأ استخدام. العامة هي `--json` و `--base-url` و `--org` و `--token` و `--insecure`/`--secure` و `--timeout` و `--quiet` و `--no-color`. -- **`--json` يطبع JSON خالص إلى stdout، وشيء آخر.** خطوط حالة الإنسان والتحذيرات والأخطاء تذهب إلى **stderr**، لذا يبقى التقاط stdout `--json` نظيفاً لأنابيب إلى `jq` حتى عندما يتم عرض سطر حالة. بدون `--json` تحصل على عرض مربع وملون لعيون الإنسان. -- **اكتشف باستخدام `--help`.** لكل أمر وأمر فرعي `--help` (والاسم المستعار `-h`): `agenteye -h` و `agenteye sessions -h` و `agenteye keys create -h`. تسرد الشرعة عالية المستوى أيضاً أكواد الخروج والخيارات العامة. لا يوجد تفريغ سطح قابل للقراءة من الآلة عالمي؛ استخدم `--help` لكل أمر، بالإضافة إلى `agenteye query schema` و `agenteye settings schema` الخاصة بالمجال لتلك السجلات. -- **الأكثر تأكيداً للتخطي التلقائي للنصوص البرمجية والوكلاء.** إنشاء/تحديث/حذف أوامر اطلب "هل أنت متأكد؟" في محطة طرفية تفاعلية، لكن **تخطي هذا الطلب تلقائياً تحت `--json` أو عندما لا تكون stdin TTY** (TTY هي جلسة محطة طرفية تفاعلية؛ الأنابيب أو عداء CI ليست)، لذا لا تعلق النصوص البرمجية والوكلاء أبداً. مرر `--yes`/`-y` لتخطيها بشكل صريح. لأن الطلب لن يحترق لوكيل، يجب على الوكيل تأكيد الإجراءات المدمرة مع الإنسان أولاً. -- **الترقيم:** النتائج هي الأحدث أولاً والترقيم المستند إلى المؤشر (يُرجع كل صفحة رمزاً تستخدمه لجلب النتيجة التالية). `--limit N` (alias `-n`) يغطي الصفوف و **يفترض 50**؛ `--all` يصفحة تلقائياً (في أجزاء بـ 200 صف) **حتى `--limit`**، لذا `--all` مجرد يتوقف عند 50. لكنسة كاملة قم بتمرير حد أعلى صريح: `--all --limit 1000`. `--page-size N` يتحكم في الجزء لكل طلب (max 200)؛ `--cursor ` يستأنف من `next_cursor` الصفحة السابقة. -- **مرشحات الوقت:** `--since` يأخذ نافذة نسبية: `15m` أو `1h` أو `6h` أو `24h` أو `7d` أو `all` (إعدادات لوحة التحكم المسبقة). لنطاق أطول أو مخصص (قل آخر 30 يوماً)، استخدم `--from`/`--to`: طوابع زمنية UTC صريحة بصيغة ISO-8601 **مع `T` ومنطقة زمنية** (على سبيل المثال `2026-06-01T00:00:00Z`) التي تتجاوز `--since`. القيمة المفصولة بمسافة أو بدون منطقة زمنية هي خطأ استخدام. -- **`--fields a,b,c`** (على `events` و `sessions` و `evals` و `errors`) يقيد المخرجات إلى تلك المفاتيح، لكل من الجدول و `--json`. يتم رفض الأسماء غير المعروفة بالقائمة الصحيحة، طريقة رخيصة لاكتشاف أسماء الحقول. -- **`--file payload.json`** (أو `--file -` لقراءة stdin) توفر جسم طلب JSON كامل حيث يكون لدى مورد شكل معقد (على `alerts create/update` و `settings set` و `users create/update`). يستخدم SQL المحفوظ بدلاً من ذلك `--sql @file.sql`. -- **مرشحات متعددة القيم** مفصولة بفواصل → مطابقة كمجموعة (اتحاد ضمن مرشح واحد، AND عبر المرشحات): `--event-type tool_use,tool_result`. خيارات النقر ليست متغيرة الطول، لذا `--add a b` فواصل. استخدم `--add a,b` أو كرر العلم (`--add a --add b`) أو علامة اقتباس (`--add "a b"`). +- **الخيارات العامة تأتي قبل الأمر.** `agenteye --json sessions` صحيح؛ `agenteye sessions --json` خطأ في الاستخدام. الخيارات العامة هي `--json` و `--base-url` و `--org` و `--token` و `--insecure`/`--secure` و `--timeout` و `--quiet` و `--no-color`. +- **`--json` يطبع JSON نقي إلى stdout، وشيء آخر فقط.** رسائل الحالة البشرية والتحذيرات والأخطاء تذهب إلى **stderr**، لذا فإن التقاط `--json` stdout يبقى نظيفاً للأنابة إلى `jq` حتى عندما تظهر رسالة حالة. بدون `--json` تحصل على عرض مربع وملون للعيون البشرية. +- **اكتشف باستخدام `--help`.** كل أمر وأمر فرعي لديه `--help` (و `h-` بدون مسافة رمز مختصر): `agenteye -h` و `agenteye sessions -h` و `agenteye keys create -h`. تسرد الوثيقة العامة أيضاً أكواد الخروج والخيارات العامة. لا توجد وثيقة سطح شاملة قابلة للقراءة الآلية؛ استخدم `--help` لكل أمر، بالإضافة إلى `agenteye query schema` و `agenteye settings schema` الخاصين بالنطاق لهذين السجلين. +- **التأكيدات تتخطى تلقائياً للسكريبتات والوكلاء.** أوامر الإنشاء/التحديث/الحذف تطلب من يسأل في طرفية تفاعلية، لكن **تتخطى المطالبة تلقائياً تحت `--json` أو كلما لم يكن stdin TTY** (TTY هي جلسة طرفية تفاعلية؛ الأنابة أو منفذ CI ليست كذلك)، لذا لا تتوقف السكريبتات والوكلاء أبداً. مرر `--yes`/`-y` لتخطيها بشكل صريح. لأن المطالبة لن تطير لوكيل، يجب على الوكيل تأكيد الإجراءات المدمرة مع الإنسان أولاً. +- **الترقيم:** النتائج الأحدث أولاً وتستخدم قوائم المؤشرات (كل صفحة تعيد رمزاً تستخدمه لجلب التالي). `--limit N` (بدون مسافة `n-`) يحد من الصفوف و **افتراضياً 50**؛ `--all` ترقيم تلقائي (في كتل 200 صف) **حتى `--limit`**، لذا `--all` بدون مقيد يتوقف عند 50. لفسح كامل مرر حد صريح عالي: `--all --limit 1000`. `--page-size N` يتحكم في القطعة لكل طلب (الحد الأقصى 200)؛ `--cursor ` يستأنف من صفحة سابقة `next_cursor`. +- **عوامل التصفية الزمنية:** `--since` يأخذ نافذة نسبية: `15m` أو `1h` أو `6h` أو `24h` أو `7d` أو `all` (معينات لوحة التحكم). لنطاق أطول أو مخصص (مثل آخر 30 يوم)، استخدم `--from`/`--to`: طوابع زمنية UTF-8 ISO-8601 صريحة **مع `T` ومنطقة زمنية** (على سبيل المثال `2026-06-01T00:00:00Z`) التي تلغي `--since`. قيمة مفصولة بمسافة أو بدون منطقة زمنية هي خطأ في الاستخدام. +- **`--fields a,b,c`** (على `events` و `sessions` و `evals` و `errors`) يحصر الإخراج على تلك المفاتيح، لكل من الجدول و `--json`. يتم رفض الأسماء غير المعروفة بالقائمة الصحيحة، طريقة رخيصة لاكتشاف أسماء الحقول. +- **`--file payload.json`** (أو `--file -` لقراءة stdin) يوفر نص طلب JSON كامل حيث تحتوي المورد إلى شكل معقد (على `alerts create/update` و `settings set` و `users create/update`). يستخدم SQL الاستعلام المحفوظ `--sql @file.sql` بدلاً من ذلك. +- **عوامل التصفية متعددة القيم** هي مفصولة بفواصل → تطابقت كمجموعة (اتحاد داخل مرشح واحد، و بين المرشحات): `--event-type tool_use,tool_result`. خيارات النقر ليست variadic، لذا `--add a b` يكسر. استخدم `--add a,b` أو كرر العلم (`--add a --add b`) أو اقتبس (`--add "a b"`). --- -## مرجع الأمر +## مرجع الأوامر -### ستستخدم هذه 5 أوامر الأكثر +### ستستخدم هذه 5 أوامر في المقام الأول -يعمل معظم العمل اليومي من خلال حفنة من أوامر القراءة. ابدأ هنا، ثم اوصل إلى السطح الكامل أدناه عند الحاجة إليه: +معظم العمل اليومي يعمل من خلال حفنة من أوامر القراءة. ابدأ هنا، ثم توصل السطح الكامل أدناه عندما تحتاجه: -| الأمر | ما يفعله | جربه | +| الأمر | ما يفعله | جرّبه | |---|---|---| -| `sessions` | صف واحد لكل تشغيل وكيل: الوقت والبيئة والوكيل والحالة والنتيجة الأخيرة. | `agenteye --json sessions --since 24h --status error` | -| `events` | مسار لكل خطوة خام داخل تشغيل (أضف `--full` للحمولات). | `agenteye --json events --session-id run-001 --all` | -| `evals` | نتائج التقييم والنتائج؛ `--aggregate` يجمعها. | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | فقط الأحداث المُخطأة؛ `--aggregate` للعد حسب النوع. | `agenteye --json errors --since 24h --aggregate` | -| `list` | اكتشف قيم المرشح الصحيحة (الوكلاء والبيئات والنماذج وما إلى ذلك). | `agenteye list agents` | +| `sessions` | صف واحد لكل تشغيل الوكيل: الوقت والبيئة والوكيل والحالة والنتيجة الأخيرة. | `agenteye --json sessions --since 24h --status error` | +| `events` | المسار الخام لكل خطوة داخل التشغيل (أضف `--full` للحمولات). | `agenteye --json events --session-id run-001 --all` | +| `evals` | نتائج التقييم والنتائج؛ `--aggregate` يرتفع. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | فقط الأحداث المخطئة؛ `--aggregate` للأعداد حسب النوع. | `agenteye --json errors --since 24h --aggregate` | +| `list` | اكتشف قيم المرشح الصحيحة (الوكلاء والبيئات والنماذج، إلخ). | `agenteye list agents` | -### كل شيء يمكن أن يفعله CLI +### كل ما يمكن لـ CLI أن يفعله -يتبع السطح الكامل. لديها CLI **18 أمر على المستوى الأعلى**. تقبل جميع أوامر القراءة `--json` والخيارات العامة أعلاه؛ قم بتشغيل `agenteye -h` (أو ` -h`) لقائمة العلم الشاملة وشكل JSON لأي واحد. +يتبع السطح الكامل. CLI لديها **18 أمر على المستوى الأعلى**. جميع أوامر القراءة تقبل `--json` والخيارات العامة أعلاه؛ قم بتشغيل `agenteye -h` (أو ` -h`) للحصول على قائمة العلم الشاملة وشكل JSON لأي واحد. ### الهوية: `login` · `logout` · `whoami` · `orgs` · `version` · `help` @@ -197,7 +197,7 @@ agenteye version # print the CLI version (s agenteye help # top-level help (same as --help) ``` -`orgs` يفحص ويبدل المستأجر النشط: +يفحص `orgs` ويغير المستأجر النشط: ```bash agenteye orgs list # your orgs + your role in each (active one marked) @@ -208,7 +208,7 @@ agenteye orgs perms # your permissions in the active org, grouped by resou ### ملاحظة (قراءة فقط): `events` · `sessions` · `evals` · `errors` · `list` -لا يحتاج أي من هؤلاء تأكيداً. مرشحات مشتركة: `--session-id` و `--agent-id` و `--env` (**ليس** `--environment`) ونطاق الوقت (`--since` / `--from` / `--to`). +لا أحد من هؤلاء يحتاج إلى تأكيد. المرشحات المشتركة: `--session-id` و `--agent-id` و `--env` (**ليس** `--environment`) ونطاق الوقت (`--since` / `--from` / `--to`). ```bash # events (alias: the raw per-step trail), newest first @@ -231,16 +231,16 @@ agenteye --json errors --since 24h --error-type timeout --all --limit 1000 agenteye list envs # also: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (على **`evals`** وليس `sessions`) قابلة للتكرار و AND-combined؛ كل حد اختياري (`..0.5` يعني ≤ 0.5 و `0.9..` يعني ≥ 0.9). حتى 20 مرشح نتيجة لكل طلب. `evals --scores-full` هي علم عرض لـ **الجدول البشري فقط**؛ يُظهر كل زوج نتيجة بدلاً من الأول والقليل بالإضافة إلى عد `+N`. لا تأثير تحت `--json`، الذي يُرجع دائماً كائن النتيجة الكامل. لقراءة **جلسة واحدة من البداية إلى النهاية**، دمج مسار الحدث مع تقييمه: +`--score KEY:MIN..MAX` (على **`evals`** وليس `sessions`) قابل للتكرار و و-مرتبط؛ كل حد اختياري (`..0.5` يعني ≤ 0.5 و `0.9..` يعني ≥ 0.9). حتى 20 مرشح درجة لكل طلب. `evals --scores-full` هو علم عرض **لجدول الإنسان فقط**؛ يظهر كل زوج درجة بدلاً من الأول بعض و `+N` عد. ليس لها تأثير تحت `--json`، الذي يعيد دائماً كائن الدرجة الكامل. قراءة **جلسة واحدة نهاية-إلى-نهاية**، قم بدمج مسار الحدث مع تقييمه: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' agenteye --json evals --session-id run-001 # its scores + status ``` -### إدارة (تحت حراسة الأذونات): `keys` · `users` · `settings` · `alerts` · `incidents` +### إدارة (مقفولة بالأذونات): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: مفاتيح API. يتم إنشاء السر محلياً وإرساله إلى الخادم (الذي يخزن فقط تجزئة) و **يظهر مرة واحدة** على الإنشاء/إعادة الإنشاء؛ التقطها إذاً. مع `--json` يظهر فقط في حقل `key`. المرجعية ب **الاسم**. +**`keys`**: مفاتيح API. يتم توليد السر محلياً وإرساله إلى الخادم (الذي يخزن فقط هاش) و **عرضه مرة واحدة** على الإنشاء/الإعادة؛ اقبضه ثم. مع `--json` يظهر فقط في حقل `key`. المرجع ب **الاسم**. ```bash agenteye keys list # active keys first, then revoked @@ -252,9 +252,9 @@ agenteye keys regenerate ci-bot --yes # rotate the secret (the ol agenteye keys disable ci-bot --yes # revoke ``` -تعمل الأذونات كـ `(permission-set ∪ --add) − --remove`. الرموز هي `slug:action` (على سبيل المثال `events:read`) أو `slug:action.action` لتوسيع عدة على مورد واحد (`events:read.add` → `events:read` و `events:add`). الإعدادات المسبقة: `read-only` و `standard` و `admin`. الأذونات البشرية فقط (`keys:update`) لا يمكن منحها لمفتاح. +تعمل الأذونات كـ `(permission-set ∪ --add) − --remove`. الرموز هي `slug:action` (مثل `events:read`) أو `slug:action.action` لتوسيع عدة على مورد واحد (`events:read.add` → `events:read` و `events:add`). المعينات: `read-only` و `standard` و `admin`. الأذونات البشرية فقط (`keys:update`) لا يمكن منحها للمفتاح. -**`users`**: أعضاء المنظمة، المرجعية ب **البريد الإلكتروني** (يُقبل أيضاً معرف UUID). +**`users`**: أعضاء المؤسسة، المرجع ب **البريد الإلكتروني** (قبول معرّف UUID أيضاً). ```bash agenteye users list [--active-only] @@ -265,7 +265,7 @@ agenteye users disable dev@corp.com --yes # has protected/self guards agenteye users enable dev@corp.com ``` -**`settings`**: سجل ثابت (تقرأ وتغير المفاتيح الموجودة؛ لا يمكنك إنشاء واحد جديد). +**`settings`**: سجل ثابت (تقرأ وتغير المفاتيح الموجودة؛ لا يمكنك إنشاء مفاتيح جديدة). ```bash agenteye settings list # key · value · type · updated (secrets masked) @@ -273,7 +273,7 @@ agenteye settings schema # what each key accepts (ty agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: تعريفات التنبيه، المرجعية ب **الاسم**. `create` يأخذ NAME موضعي بالإضافة إلى الأعلام أو جسم JSON كامل عبر `--file`. +**`alerts`**: تعريفات التنبيه، المرجع ب **الاسم**. تأخذ `create` اسم موضعي بالإضافة إلى الأعلام أو نص طلب JSON كامل عبر `--file`. ```bash agenteye alerts list @@ -284,7 +284,7 @@ agenteye alerts test high-errors --yes # fire a test noti agenteye alerts delete high-errors --yes ``` -**`incidents`**: حوادث التنبيه، المرجعية بـ id (معرفات قصيرة مقبولة). `show` يطبع سجل النشاط الكامل؛ اقرأه قبل التصرف. +**`incidents`**: حوادث التنبيه، المرجع بـ id (تقبل معرفات قصيرة). `show` يطبع سجل النشاط الكامل؛ اقرأه قبل التصرف. ```bash agenteye incidents list --state firing # also: acknowledged, resolved @@ -301,7 +301,7 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### التحليلات والمساعد: `query` · `agent` -**`query`**: SQL محفوظ مقابل متجر التحليلات بالإضافة إلى عداء مخصص. الاستعلامات المحفوظة المرجعية ب **الاسم**؛ يتم التحقق من SQL من جانب الخادم (SELECT/WITH فقط، مهلة البيان، حد الصف). +**`query`**: SQL محفوظة ضد متجر التحليلات الخاص بك بالإضافة إلى منفذ مخصص. الاستعلامات المحفوظة هي المرجع ب **الاسم**؛ يتم التحقق من صحة SQL على خادم جانب (SELECT/WITH فقط، انتهاء بيان، حد الصف). ```bash agenteye query schema [TABLE] # column layout of the analytics views @@ -312,7 +312,7 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: يتحدث إلى **مساعد الذكاء الاصطناعي** المدمج (نفس محلل القراءة فقط الذي يمكنك الدردشة معه في لوحة التحكم). يتم الإشارة إلى الدردشات بـ chat-id قصير (قابل للدقة البادئة). +**`agent`**: يتحدث مع **مساعد الذكاء الاصطناعي** المدمج (نفس محلل القراءة فقط الذي يمكنك الدردشة معه في لوحة التحكم). المحادثات هي المرجع بـ short chat-id (حل البادئة). ```bash agenteye agent health # is the AI assistant configured/reachable @@ -330,20 +330,20 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | الكود | المعنى | |---|---| | 0 | نجاح | -| 1 | خطأ غير متوقع (على سبيل المثال، أعاد لوحة التحكم 5xx) | -| 2 | خطأ الاستخدام (حجج غير صحيحة، أمر/علم غير معروف، تضارب اسم) | +| 1 | خطأ غير متوقع (على سبيل المثال لوحة التحكم أرجعت 5xx) | +| 2 | خطأ في الاستخدام (وسائط غير صالحة، أمر/علم غير معروف، تضارب الاسم) | | 3 | لا يمكن الوصول إلى لوحة التحكم | -| 4 | غير مسجل الدخول أو انتهت صلاحية الجلسة؛ شغل `agenteye login` | -| 5 | مُصادق عليه، لكن حسابك يفتقد الأذن المطلوبة (الرسالة تسميها) | -| 6 | لم يتم العثور على المورد المطلوب (على سبيل المثال، معرف جلسة أو حادثة غير معروف) | +| 4 | لم تقم بتسجيل الدخول أو انتهت صلاحية الجلسة؛ قم بتشغيل `agenteye login` | +| 5 | موثق، ولكن حسابك يفتقر إلى الإذن المطلوب (رسالة الاسم) | +| 6 | لم يتم العثور على المورد المطلوب (مثل معرّف جلسة أو حادثة غير معروفة) | -وهذا يجعل CLI آمنة للنص البرمجي: يمكن لوكيل ترميز فرع على `4` لمطالبتك بإعادة المصادقة، أو `5` لسطح الأذن المفقودة. انظر [وصفات CLI للوكلاء](/ar/agenteye/cli-recipes) لأنماط معالجة أكواد الخروج وأشكال مخرجات JSON. +هذه تجعل CLI آمنة للسكريبت: يمكن لوكيل برمجي أن يفرع على `4` لمطالبتك بإعادة المصادقة، أو `5` لسطح الإذن المفقود. انظر [وصفات CLI للوكلاء](/ar/agenteye/cli-recipes) لأنماط معالجة exit-code وأشكال إخراج JSON. --- ## الخطوات التالية -- **[وصفات CLI للوكلاء](/ar/agenteye/cli-recipes)**: أنماط استعلام نسخ لصق، `jq` سطر واحد، إسقاطات `--fields`، معالجة أكواد الخروج وأشكال مخرجات JSON، مكتوبة لوكلاء ترميز يقودون CLI. -- **[مهارة عامل CLI](/ar/agenteye/cli-skill)**: حزم هذا CLI كمهارة قابلة للتثبيت Claude Code / Codex بحيث يقود وكيل ترميز Failproof AI Observability من طلبات اللغة الطبيعية. -- **[مفاتيح API](/ar/agenteye/api-keys)**: نموذج الأذن خلف `keys create --add …`. -- **[مساعد الذكاء الاصطناعي](/ar/agenteye/assistant)**: تفعيل المساعد الذي يتحدث معه `agent ask`. \ No newline at end of file +- **[وصفات CLI للوكلاء](/ar/agenteye/cli-recipes)**: أنماط استعلام نسخ واللصق و `jq` أحادي الاتجاه و `--fields` إسقاطات ومعالجة exit-code وأشكال إخراج JSON، مكتوبة لوكلاء البرمجة التي تقود CLI. +- **[مهارة عامل CLI](/ar/agenteye/cli-skill)**: حزم هذا CLI كمهارة قابلة للتثبيت Claude Code / Codex بحيث يقود وكيل برمجي Failproof AI Observability من طلبات اللغة الطبيعية. +- **[مفاتيح API](/ar/agenteye/api-keys)**: نموذج الأذن وراء `keys create --add …`. +- **[مساعد الذكاء الاصطناعي](/ar/agenteye/assistant)**: تفعيل المساعد الذي `agent ask` يتحدث إليه. \ No newline at end of file diff --git a/docs/ar/agenteye/codex-capture.mdx b/docs/ar/agenteye/codex-capture.mdx index 4e4c0a24..fc752b97 100644 --- a/docs/ar/agenteye/codex-capture.mdx +++ b/docs/ar/agenteye/codex-capture.mdx @@ -1,56 +1,56 @@ --- --- title: "التقاط جلسات Codex" -description: "استخدم جلسات فريقك المحلية من OpenAI Codex في AgentEye كجلسات وأحداث عادية — دون أي تغيير في طريقة تشغيل Codex." +description: "قم بتوجيه جلسات OpenAI Codex المحلية لفريقك إلى AgentEye كجلسات وأحداث عادية — دون أي تغيير في طريقة تشغيلهم لـ Codex." --- -يقوم المهندسون لديك بتشغيل OpenAI Codex يومياً بالفعل. يوفر التقاط جلسات Codex القدرة على نقل جلسات الترميز تلك إلى AgentEye كجلسات وأحداث عادية، بحيث يمكنك البحث فيها وإعادة تشغيلها وتقييمها جنباً إلى جنب مع كل ما تلاحظه آخر. يكمل هذا [Python SDK](/ar/agenteye/python-sdk): حيث يقوم SDK بتوظيف الوكلاء الذين تكتبهم، بينما يقوم هذا بالتقاط عمل Codex الذي يقوم به فريقك بالفعل — دون أي تغيير في طريقة تشغيله. +مهندسوك يقومون بتشغيل OpenAI Codex يومياً بالفعل. التقاط جلسات Codex يجلب تلك جلسات البرمجة إلى AgentEye كجلسات وأحداث عادية، حتى تتمكن من البحث والتشغيل والتقييم بجانب كل شيء آخر تراقبه. يكمل هذا [Python SDK](/ar/agenteye/python-sdk): SDK يقوم بتجهيز الوكلاء الذين تكتبهم، بينما هذا يلتقط عمل Codex الذي يقوم به فريقك بالفعل — دون أي تغيير في طريقة تشغيلهم له. -مجمع خلفي صغير يقرأ نسخ جلسات Codex المحلية كما يتم كتابتها وينقلها إلى AgentEye. مجمع واحد لكل جهاز يلتقط كل سطح Codex محلي في نفس الوقت — لا توجد عملية إعداد لكل سطح. +جامع خلفي صغير يقرأ نصوص جلسات Codex المحلية أثناء كتابتها ويرسلها إلى AgentEye. جامع واحد لكل جهاز يلتقط كل سطح Codex محلي في نفس الوقت — لا توجد إعدادات منفصلة لكل سطح. -يلتقط نفس المجمع وكلاء آخرين أيضاً — انظر [OpenClaw](/ar/agenteye/openclaw-capture) و [Hermes](/ar/agenteye/hermes-capture). فعّل كل واحد تقوم بتشغيله؛ يمكن لمجمع واحد أن يلتقط عدة منها في نفس الوقت. +نفس الجامع يلتقط وكلاء آخرين أيضاً — انظر [OpenClaw](/ar/agenteye/openclaw-capture) و [Hermes](/ar/agenteye/hermes-capture). قم بتفعيل كل واحد تشغله؛ جامع واحد يمكنه التقاط عدة منهم في نفس الوقت. --- -## ما يتم التقاطه +## ما الذي يتم التقاطه -كل سطح Codex يعمل **محلياً** ينتج نفس نسخ الجلسات على القرص، والمجمع يلتقط كل منها: +كل سطح Codex يعمل **محلياً** ينتج نفس نصوص الجلسة على القرص، والجامع يلتقطها جميعاً: -- واجهة سطر أوامر Codex **CLI** و `codex exec` -- **ملحق VS Code / IDE** -- **تطبيق سطح المكتب**، عند تشغيل جلسة محلياً +- سطر أوامر Codex **CLI** و `codex exec` +- ملحق **VS Code / IDE** +- **تطبيق سطح المكتب**، عندما يقوم بتشغيل جلسة محلياً -تصبح كل جلسة Codex [جلسة](/ar/agenteye/sessions) AgentEye؛ رسائل المستخدم والمساعد، والتفكير، واستدعاءات الأدوات، ونتائج الأدوات، واستخدام الرموز تصبح [أحداث](/ar/agenteye/event-stream) مطابقة. يتم تسجيل السطح الذي أتت منه كل جلسة (CLI أو IDE أو سطح مكتب)، حتى تتمكن من تمييزها. +كل جلسة Codex تصبح [جلسة](/ar/agenteye/sessions) AgentEye؛ رسائل المستخدم والمساعد والاستدلال واستدعاءات الأدوات ونتائج الأدوات واستخدام الرموز تصبح [الأحداث](/ar/agenteye/event-stream) المتطابقة. يتم تسجيل السطح الذي جاءت منه الجلسة (CLI أو IDE أو سطح المكتب)، حتى تتمكن من التمييز بينها. -> **لا يتم التقاط جلسات السحابة.** يقوم تطبيق سطح المكتب بشكل متزايد بتشغيل الجلسات في سحابة Codex ويحتفظ فقط بالبيانات الوصفية الخاصة بها على الجهاز — لا توجد نسخة محلية لقراءتها. يتم التقاط الجلسات المنفذة محلياً فقط. +> **لا يتم التقاط الجلسات السحابية.** يقوم تطبيق سطح المكتب بشكل متزايد بتشغيل الجلسات في سحابة Codex ويحتفظ فقط بالبيانات الوصفية الخاصة بها على الجهاز — لا توجد نصوص محلية للقراءة. يتم التقاط الجلسات المنفذة محلياً فقط. --- ## تشغيله -الالتقاط معطل حتى تقوم بتفعيله. ثبت المجمع بمفتاح API له إذن `events:add` (انظر [مفاتيح API](/ar/agenteye/api-keys))، وفعّل التقاط Codex: +التقاط الجلسات معطّل حتى تقوم بتفعيله. قم بتثبيت الجامع بمفتاح API له صلاحية `events:add` (انظر [مفاتيح API](/ar/agenteye/api-keys))، وقم بتشغيل التقاط Codex: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -يقوم هذا بتثبيت المجمع وتسجيله كخدمة خلفية وبدء الالتقاط. تأكد من أنه قيد التشغيل: +يقوم هذا بتثبيت الجامع، وتسجيله كخدمة خلفية، وبدء الالتقاط. تأكد من أنه يعمل: ```bash agenteye-collector health ``` -عند التشغيل الأول، يتم ملء جلسات Codex الموجودة لديك مرة واحدة وينتقل النشاط الجديد خلال ثوان. ملفات Codex نفسها تُقرأ فقط — لا تُعدّل أو تُنقل أو تُحذف — وكل جلسة تُنقل بالضبط مرة واحدة، حتى عبر إعادات التشغيل. +عند التشغيل الأول، يتم ملء جلساتك الموجودة في Codex مرة واحدة والأنشطة الجديدة تبدأ البث خلال ثوانٍ. ملفات Codex نفسها تُقرأ فقط — لا تُعدَّل أو تُنقَل أو تُحذَف — وكل جلسة تُرسَل مرة واحدة فقط، حتى عند إعادة التشغيل. --- -## حيث يظهر +## حيث تظهر -تظهر الجلسات المقتناة في **Sessions**، وأحداثها في تيار **Events**، وبنفس طريقة أي وكيل آخر تراقبه — لذا [إعادة تشغيل الجلسة](/ar/agenteye/sessions) و [البحث](/ar/agenteye/queries) و [التقييمات](/ar/agenteye/evaluations) و [التنبيهات](/ar/agenteye/alerts) تعمل جميعها عليها. قم بالتصفية حسب وكيل Codex لرؤيتها بمفردها. +الجلسات المُلتقطة تظهر في **Sessions**، وأحداثها في تدفق **Events**، مثل أي وكيل آخر تراقبه — لذا فإن [تشغيل الجلسات](/ar/agenteye/sessions) و [البحث](/ar/agenteye/queries) و [التقييمات](/ar/agenteye/evaluations) و [التنبيهات](/ar/agenteye/alerts) تعمل جميعاً عليها. قم بالتصفية حسب وكيل Codex لرؤيتها بمفردها. --- ## الخصوصية -تحتوي نسخ Codex على الجلسة الكاملة — بما في ذلك مخرجات الأوامر وملتويات الملفات وأي شيء قراءه أو كتبه Codex — ويمكن أن تحتوي على أسرار. يتم نقل الجلسات المقتناة كما هي، لذا فعّل الالتقاط فقط على الأجهزة والفرق التي يكون فيها تجميع هذا المحتوى في AgentEye مناسباً، وامنح المجمع مفتاحاً مقتصراً على `events:add` فقط. انظر [Security](/ar/agenteye/security) لمعرفة كيف يتم الحفاظ على عزل بيانات التشفير الخاصة بك. \ No newline at end of file +نصوص Codex تحتوي على الجلسة الكاملة — بما في ذلك مخرجات الأوامر ومحتويات الملفات وأي شيء قراءه أو كتبه Codex — وقد تحتوي على أسرار. الجلسات المُلتقطة تُرسَل كما هي، لذا قم بتفعيل الالتقاط فقط على الأجهزة والفرق التي يكون فيها تجميع هذا المحتوى في AgentEye مناسباً، وأعط الجامع مفتاحاً محدوداً لـ `events:add` فقط. انظر [الأمان](/ar/agenteye/security) لمعرفة كيفية عزل بياناتك. \ No newline at end of file diff --git a/docs/ar/agenteye/concepts.mdx b/docs/ar/agenteye/concepts.mdx index 333e1fcc..d9a9f412 100644 --- a/docs/ar/agenteye/concepts.mdx +++ b/docs/ar/agenteye/concepts.mdx @@ -1,88 +1,88 @@ --- --- title: "المفاهيم" -description: "المصطلحات المستخدمة في Failproof AI Observability — الأحداث والجلسات والتقييمات والتدقيقات والنتائج والحوادث — معرّفة في مكان واحد." +description: "المصطلحات الأساسية خلف Failproof AI Observability — الأحداث والجلسات والتقييمات والتدقيقات والنتائج والحوادث — معرّفة في مكان واحد." --- -تحدد هذه الصفحة المصطلحات التي يستخدمها Failproof AI Observability. إذا كان هناك مصطلح غير مألوف في دليل آخر، فهو معرّف هنا. لا تحتاج إلى قراءة الصفحة كاملة: يمكنك تصفحها أو العودة إليها عند مصادفة كلمة تريد توضيحها. +تحدد هذه الصفحة المصطلحات التي تستخدمها Failproof AI Observability. إذا كان أي مصطلح في دليل آخر غير مألوف، فهو معرّف هنا. لا تحتاج إلى قراءة الصفحة كاملة: يمكنك تصفحها أو العودة إليها عندما تواجه كلمة تريد توضيحها. --- ## نموذج البيانات -**Event (الحدث)** -أصغر وحدة بيانات. يسجل حدث واحد خطوة واحدة اتخذها وكيلك: `tool_use` أو `model_request` أو `hook_completed` أو `error` وغيرها. ينبعث وكيلك الأحداث عبر [Python SDK](/ar/agenteye/python-sdk)؛ تظهر مباشرة على صفحة **Events**. +**الحدث (Event)** +أصغر وحدة بيانات. يسجل حدث واحد خطوة واحدة قام بها وكيل الذكاء الاصطناعي: `tool_use` أو `model_request` أو `hook_completed` أو `error` وما إلى ذلك. يصدر الوكيل الأحداث من خلال [Python SDK](/ar/agenteye/python-sdk)؛ وتظهر مباشرة على صفحة **الأحداث**. -**Session (الجلسة)** -تشغيل واحد للوكيل، يتم تعريفه بواسطة `session_id`. الجلسة هي جميع الأحداث التي تشترك في نفس المعرّف، مدمجة في صف واحد على صفحة **Sessions** وموضحة كرسم بياني تنفيذي في صفحة التفاصيل الخاصة بها. عادة ما تبدأ الجلسة بـ `agent_start` وتنتهي بـ `agent_end`. +**الجلسة (Session)** +تشغيل واحد للوكيل، معرّف برقم `session_id`. الجلسة هي جميع الأحداث التي تشترك في هذا المعرّف، مجمعة في صف واحد على صفحة **الجلسات** وموضحة كرسم بياني للتنفيذ على صفحة التفاصيل الخاصة بها. تبدأ الجلسة عادة بـ `agent_start` وتنتهي بـ `agent_end`. -**Agent (الوكيل)** -فاعل مُسمّى داخل التشغيل، يتم تعريفه بواسطة `agent_id`. يمكن أن يشتمل التشغيل على عدة وكلاء: على سبيل المثال، مخطط ينتج وكيل فرعي للتلخيص. يحمل الوكلاء الفرعيون `parent_id`، وهذا هو ما يسمح لـ Failproof AI Observability برسمهم على مساراتهم الخاصة في الرسم البياني التنفيذي. +**الوكيل (Agent)** +ممثل مسمى داخل تشغيل، معرّف برقم `agent_id`. يمكن أن يتضمن التشغيل عدة وكلاء: على سبيل المثال، موظف تخطيط يولد وكيل تلخيص فرعي. يحمل الوكلاء الفرعيون `parent_id`، وهذا ما يتيح لـ Failproof AI Observability رسمهم على ممرات منفصلة في رسم البياني للتنفيذ. -**Environment (البيئة)** -تصنيف للمكان الذي حدث فيه التشغيل: `production` أو `staging` أو `dev`. تعيّنها مرة واحدة عند تكوين SDK. يمكن لكل صفحة لوحة تحكم تقريباً التصفية حسب البيئة. +**البيئة (Environment)** +تسمية توضح مكان حدوث التشغيل: `production` أو `staging` أو `dev`. يمكنك تعيينها مرة واحدة عند تكوين SDK. يمكن تصفية معظم صفحات لوحة التحكم حسب البيئة. -**Context-window fill (ملء نافذة السياق)** -نسبة مئوية من نافذة السياق للنموذج التي استهلكتها الاستجابة. يضيف Failproof AI Observability الطابع الزمني لها على أحداث `model_response` للنماذج التي يتعرف عليها، بحيث يكون نمو المطالبة والانضغاط الوشيك مرئياً مباشرة في تدفق الأحداث. +**ملء نافذة السياق (Context-window fill)** +نسبة مئوية من نافذة السياق للنموذج التي استهلكتها الاستجابة. تضع Failproof AI Observability طابعاً عليها في أحداث `model_response` للنماذج التي تتعرف عليها، بحيث تكون نمو الطلب والدمج الوشيك مرئياً مباشرة في تدفق الأحداث. --- ## الجودة -**Evaluation (التقييم)** -درجة جودة لجلسة منتهية، ينتجها خدمة تسجيل تديرها. التقييمات اختيارية: حتى تقوم بربط مُقيّم، يتم تسجيل الجلسات لكن لا يتم تقديرها. يمكن لكل تقييم أن يحمل عدة درجات مسمّاة (على سبيل المثال `helpfulness` و `factuality` و `tool_efficiency`)، كل منها مع ملاحظة قصيرة للتفكير. انظر [Evaluation suite](/ar/agenteye/evaluation-suite). +**التقييم (Evaluation)** +درجة جودة لجلسة منتهية، ينتجها خدمة تسجيل تقوم بتشغيلها. التقييمات اختيارية: حتى تربط مقيماً، يتم تسجيل الجلسات ولكن لا يتم تسجيل درجاتها. يمكن لكل تقييم أن يحمل عدة درجات مسماة (على سبيل المثال `helpfulness` أو `factuality` أو `tool_efficiency`)، لكل منها ملخص تفكير قصير. انظر [Evaluation suite](/ar/agenteye/evaluation-suite). -**Score key (مفتاح الدرجة)** -اسم بُعد واحد يبلغ عنه المُقيّم، مثل `helpfulness`. يمكن للتنبيهات والتدقيقات مراقبة مفتاح درجة معين بمرور الوقت. +**مفتاح الدرجة (Score key)** +اسم بعد واحد يبلغ عنه المقيم، مثل `helpfulness`. يمكن للتنبيهات والتدقيقات مراقبة مفتاح درجة محدد بمرور الوقت. -**Evaluator (المُقيّم)** -خدمة التسجيل الخاصة بك. يرسل Failproof AI Observability نسخة نصية من التشغيل المنتهي إليها ويخزن الدرجات التي ترجعها. لا توفر مُقيّماً افتراضياً؛ منطق التسجيل خاص بك. +**المقيم (Evaluator)** +خدمة التسجيل الخاصة بك. تُرسل Failproof AI Observability نسخة نصية من التشغيل المنتهي إلى خدمتك وتخزن الدرجات التي تُرجعها. لا تأتي مع مقيم افتراضي؛ منطق التسجيل خاص بك. --- -## العثور على الأخطاء وإصلاحها +## البحث عن الأخطاء وإصلاحها -**Hook (الخطاف)** -حماية أو تأثير جانبي يقوم إطار عمل وكيلك بتشغيله حول خطوة: فحص سلامة المحتوى أو إخفاء معلومات التعريف الشخصية أو حماية الميزانية. تنبعث الخطافات من أحداث `hook_triggered` / `hook_completed` مع `outcome` (allow أو deny أو modify)، وتحصل على صفحة ملاحظة خاصة بها. +**الخطاف (Hook)** +حاجز حماية أو تأثير جانبي يقوم به إطار عمل الوكيل حول خطوة ما: فحص السلامة المحتملة أو تحرير معلومات التعريف الشخصية أو حاجز الميزانية. تصدر الخطافات أحداث `hook_triggered` / `hook_completed` برمز `outcome` (allow أو deny أو modify)، وتحصل على صفحة ملاحظة خاصة بها. -**Alert rule (قاعدة التنبيه)** -قاعدة تُطلق عندما تتجاوز مقياس حداً تعيّنه: معدل الخطأ أو كمون p95 أو تكلفة الرموز أو درجة المُقيّم. عند تفعيل القاعدة، تفتح حادثة وتُعلم القنوات المختارة لديك (البريد الإلكتروني أو Slack أو webhook أو داخل لوحة التحكم). انظر [Alerts](/ar/agenteye/alerts). +**قاعدة التنبيه (Alert rule)** +قاعدة تُطلق عندما تتجاوز مقياس حد معين تعينه: معدل الخطأ أو كمون p95 أو تكلفة الرموز أو درجة المقيم. عندما تُطلق القاعدة، تفتح حادثة وتبلغ عن قنواتك المختارة (بريد إلكتروني أو Slack أو webhook أو داخل لوحة التحكم). انظر [التنبيهات](/ar/agenteye/alerts). -**Incident (الحادثة)** -مشكلة مفتوحة يتم إنشاؤها عند تفعيل قاعدة التنبيه. للحوادث دورة حياة (الإقرار والتعيين والحل) وخط زمني للنشاط يسجل كل إجراء. يمكنك أيضاً فتح واحدة يدويّاً. +**الحادثة (Incident)** +مشكلة مفتوحة تم إنشاؤها عند إطلاق قاعدة تنبيه. للحوادث دورة حياة (الاعتراف والإسناد والحل) وخط زمني نشاط يسجل كل إجراء. يمكنك أيضاً فتح واحدة يدويّاً. -**Audit (التدقيق)** -تحقيق متكرر (كل ساعة إلى أسبوعياً) يفحص السجلات *عبر* الجلسات للبحث عن أنماط الفشل التي لم تكتب قاعدة لها: تجمعات الأخطاء والدرجات المنخفضة والقيم الشاذة للكمون وحلقات استدعاء الأدوات والتشغيلات التي لم تنتهِ أبداً. حيث يراقب التنبيه مقياساً تعرفه بالفعل، يخبرك التدقيق بما يجب أن تنظر إليه بعد ذلك. انظر [Audits](/ar/agenteye/audits). +**التدقيق (Audit)** +تحقيق متكرر (كل ساعة إلى أسبوعي) يفحص السجلات *عبر* الجلسات بحثاً عن أنماط الأخطاء التي لم تكتب قاعدة لها: مجموعات الأخطاء أو الدرجات المنخفضة أو الكمون الشاذ أو حلقات استدعاء الأدوات أو التشغيلات التي لم تنته مطلقاً. حيث يراقب التنبيه مقياساً تعرفه بالفعل، يخبرك التدقيق عما يجب البحث عنه بعد ذلك. انظر [التدقيقات](/ar/agenteye/audits). -**Finding (النتيجة)** -نتيجة واحدة مرتبة مدعومة بالأدلة من تشغيل التدقيق. تسمي النتيجة نمطاً وتربط بالجلسات الدقيقة وراءها وتحمل دورة حياة الفرز (الإقرار والحل والكتم والرفض). يقوم Failproof AI Observability بإزالة تكرار النتائج من تشغيل إلى آخر بحيث ينتج النمط المعروف تحديثاً بدلاً من التراكم. +**النتيجة (Finding)** +نتيجة واحدة مصنفة وموثقة بالأدلة من تشغيل التدقيق. تسمي النتيجة نمطاً، وتربط بالجلسات الدقيقة خلفه، وتحمل دورة فحص (الاعتراف والحل والكتم والرفض). تقوم Failproof AI Observability بإزالة التكرار من النتائج من تشغيل إلى آخر بحيث يتم تحديث النمط المعروف بدلاً من التراكم. -**The AI assistant (مساعد الذكاء الاصطناعي)** -الدردشة داخل لوحة التحكم التي تجيب على أسئلة حول وكلائك بلغة إنجليزية عادية، على بياناتك الخاصة. هو للقراءة فقط بشكل افتراضي؛ أي شيء ينشئه (استعلام محفوظ أو لوحة تحكم) مُوافق عليه، ولا يمكنه أبداً الحذف. انظر [AI assistant](/ar/agenteye/assistant). +**مساعد الذكاء الاصطناعي (The AI assistant)** +الدردشة داخل لوحة التحكم التي تجيب على أسئلة حول الوكلاء الخاصين بك باللغة الطبيعية، عبر بياناتك الخاصة. إنها للقراءة فقط بشكل افتراضي؛ أي شيء تنشئه (استعلام محفوظ أو لوحة تحكم) يخضع للموافقة، ولا يمكنه أبداً الحذف. انظر [مساعد الذكاء الاصطناعي](/ar/agenteye/assistant). --- ## تشغيله -**Organization (tenant) (المنظمة)** -مساحة عمل معزولة. يمكن لمثيل واحد من Failproof AI Observability استضافة عدة منظمات، كل منها مع المستخدمين والمفاتيح والبيانات الخاصة بها. كل عنوان URL لوحة التحكم مُحدد النطاق تحت رمز المنظمة الخاص بك (`//…`). +**المنظمة (الموجر) (Organization (tenant))** +مساحة عمل معزولة. يمكن لمثيل Failproof AI Observability واحد أن يستضيف العديد من المنظمات، كل منها بمستخدميها ومفاتيحها وبياناتها الخاصة. كل عنوان URL للوحة التحكم ينطبق على شريط المنظمة الخاص بك (`//…`). -**Collector (المجمع)** -`agenteye-collector`، الديمون الخفيف الذي يعمل على كل جهاز وكيل، يجمع الأحداث التي يكتبها SDK إلى القرص، وينقلها إلى الخادم. +**المجمّع (Collector)** +`agenteye-collector`، الخدمة الخفيفة التي تعمل على كل جهاز وكيل، وتجميع الأحداث التي يكتبها SDK على القرص، وتشحنها إلى الخادم. -**API key (مفتاح API)** -رمز مُحدد النطاق يوثّق عميل ضد الخادم. تحمل المفاتيح أذونات دقيقة (على سبيل المثال `events:add` للمجمع، نطاقات للقراءة فقط لمفتاح لوحة التحكم). انظر [API keys](/ar/agenteye/api-keys). +**مفتاح API (API key)** +رمز محدود النطاق يصرح عميل ضد الخادم. تحمل المفاتيح أذونات دقيقة (على سبيل المثال `events:add` للمجمّع أو نطاقات للقراءة فقط لمفتاح لوحة التحكم). انظر [مفاتيح API](/ar/agenteye/api-keys). -**Server (الخادم)** -خدمة البلع والـ API. تبتلع الأحداث وتخزن الحالة التشغيلية في قواعد البيانات الخاصة بك وتخدم لوحة التحكم والـ CLI. +**الخادم (Server)** +خدمة الإدراج والـ API. تدرج الأحداث وتخزن الحالة التشغيلية في قواعد البيانات الخاصة بك وتخدم لوحة التحكم والـ CLI. -**Dashboard (لوحة التحكم)** -واجهة المستخدم على الويب. كل صفحة مُحددة النطاق لمنظمة وتقرأ من خلال API الخادم. +**لوحة التحكم (Dashboard)** +واجهة المستخدم على الويب. كل صفحة ينطبق على منظمة وتقرأ من خلال API الخادم. --- ## الخطوات التالية -- [Overview](/ar/agenteye/overview): كيف تتناسب هذه الأجزاء معاً. -- [Observability](/ar/agenteye/observability): سطح الملاحظة (Events و Sessions و Models و Tools و Hooks و Errors). \ No newline at end of file +- [نظرة عامة](/ar/agenteye/overview): كيف تناسب هذه الأجزاء معاً. +- [الملاحظة](/ar/agenteye/observability): أسطح المراقبة (الأحداث والجلسات والنماذج والأدوات والخطافات والأخطاء). \ No newline at end of file diff --git a/docs/ar/agenteye/dashboards.mdx b/docs/ar/agenteye/dashboards.mdx index 6c492a41..06b7972b 100644 --- a/docs/ar/agenteye/dashboards.mdx +++ b/docs/ar/agenteye/dashboards.mdx @@ -1,46 +1,47 @@ --- -title: "لوحات التحكم" -description: "حول بيانات الوكيل المباشرة إلى صورة موحدة تراقبها فريقك بالكامل." +--- +title: "لوحات المعلومات" +description: "حول بيانات الوكيل المباشرة لديك إلى صورة مشتركة يراقبها فريقك بأكمله." --- -حول بيانات الوكيل المباشرة إلى صورة موحدة تراقبها فريقك بالكامل. ثبّت الاستعلامات المهمة كرسوم بيانية، وسيفتح الجميع نفس الأرقام في لمحة واحدة، دون تشغيل استعلام واحد مرة أخرى. +حول بيانات الوكيل المباشرة لديك إلى صورة مشتركة يراقبها فريقك بأكمله. ثبّت الاستعلامات المهمة كرسوم بيانية، وسيفتح الجميع نفس الأرقام في لمحة واحدة، دون إعادة تشغيل أي استعلام. -![لوحة تحكم مبنية من الاستعلامات المحفوظة: رسم بياني خطي للأحداث في الساعة، ورسم بياني عمودي للأخطاء حسب النوع، ورسم بياني منطقة للكمون، وتفصيل الرموز حسب النموذج](/agenteye/images/dashboard-fleet.png) +![لوحة معلومات مبنية من استعلامات محفوظة: خط أحداث في الساعة، وشريط أخطاء حسب النوع، وخريطة كثافة الكمون، وتوزيع الرموز حسب النموذج](/agenteye/images/dashboard-fleet.png) *لوحة واحدة، أربع استعلامات محفوظة: الأحداث في الساعة، والأخطاء حسب النوع، والكمون، والرموز حسب النموذج.* -## الجميع يرى نفس الحقيقة +## يرى الجميع نفس الحقيقة -توقف عن لصق لقطات الشاشة في الدردشة وتوقف عن تشغيل نفس الاستعلام خمس مرات في اليوم. لوحة التحكم هي لوحة موحدة على مستوى المؤسسة يمكن لأي شخص في فريقك فتحها لرؤية نفس المنظر بالضبط. عندما تتحرك البيانات الأساسية، تتحرك الرسوم البيانية معها، لذا تبقى اللوحة محدثة دائماً ولا أحد يختلف حول أرقام قديمة. +توقف عن لصق لقطات الشاشة في الدردشة وتوقف عن إعادة تشغيل نفس الاستعلام خمس مرات يومياً. لوحة المعلومات هي لوحة مشتركة على مستوى المؤسسة يمكن لأي فرد في فريقك فتحها للحصول على نفس العرض بالضبط. عندما تتغير البيانات الأساسية، تتحرك الرسوم البيانية معها، لذا تبقى اللوحة محدثة دائماً ولا أحد يجادل حول أرقام قديمة. -لوحة الأسطول أعلاه هي شكل جيد للبدء بالعمليات اليومية: +لوحة الأسطول أعلاه توفر شكلاً جيداً للبدء في العمليات اليومية: -- رسم بياني خطي **للأحداث في الساعة**، حتى تتمكن من مراقبة الإنتاجية واكتشاف انخفاض مفاجئ -- رسم بياني عمودي **للأخطاء حسب النوع**، حتى تبرز فئات الفشل الأكبر لديك -- رسم بياني منطقة **للكمون**، حتى تظهر التباطؤات قبل أن يشتكي المستخدمون -- تفصيل **الرموز حسب النموذج**، حتى تبقى التكلفة في الاعتبار +- سطر **أحداث في الساعة**، حتى تتمكن من مراقبة الإنتاجية واكتشاف الانخفاض المفاجئ +- شريط **أخطاء حسب النوع**، حتى تبرز فئات الأعطال الأكبر +- خريطة كثافة **الكمون**، حتى تظهر الاختناقات قبل شكاوى المستخدمين +- تفصيل **الرموز حسب النموذج**، حتى تبقى التكاليف في الصورة -ستجد لوحاتك في `//dashboards`. +ستجد لوحاتك على `//dashboards`. ## ثبّت الاستعلامات التي حفظتها بالفعل -كل بلاطة تبدأ كاستعلام محفوظ. بناء وحفظ الاستعلام الذي تهتم به في مكتبة [الاستعلامات](/ar/agenteye/queries) (الإعدادات المدمجة بالإضافة إلى إعداداتك الخاصة، فوق أحداثك وتقييماتك)، ثم ثبّته على لوحة تحكم كرسم بياني يناسب البيانات: **خط** للاتجاهات عبر الزمن، **عمود** للمقارنة بين الفئات، **منطقة** للحجم، أو **دائرة** لتفصيل النسبة. +كل بلاطة تبدأ كاستعلام محفوظ. ابن واحفظ الاستعلام الذي تهتم به في مكتبة [الاستعلامات](/ar/agenteye/queries) (مع الإعدادات المدمجة المسبقة بالإضافة إلى استعلاماتك الخاصة، على أحداثك والتقييمات)، ثم ثبّته على لوحة معلومات كرسم بياني يناسب البيانات: **سطر** للاتجاهات عبر الوقت، **شريط** لمقارنة الفئات، **منطقة** للحجم، أو **دائرة** لتقسيم الحصة. -لأن البلاطة ليست سوى استعلامك المحفوظ المعروض كرسم بياني، لا توجد حاجة للحفاظ على التزامن يدوياً. حدّث الاستعلام مرة واحدة وكل لوحة تحكم تستخدمه تتحدث أيضاً. +لأن البلاطة هي مجرد استعلامك المحفوظ معروض كرسم بياني، لا توجد حاجة للحفاظ على التزامن يدوياً. حدّث الاستعلام مرة واحدة وتُحدَّث كل لوحة تستخدمه أيضاً. -## راقب الجودة، ليس فقط الحجم +## راقب الجودة، وليس فقط الحجم -الحجم يخبرك أن الوكلاء مشغولون. الجودة تخبرك أنهم يقومون فعلاً بالعمل. وجّه لوحة تحكم نحو [درجات التقييم](/ar/agenteye/evaluations) الخاصة بك وستحصل على لوحة تتابع مدى جودة سير التشغيل عبر الزمن، لذا سيظهر انحدار الجودة كانخفاض على رسم بياني بدلاً من مفاجأة من عميل. +يخبرك الحجم بأن الوكلاء مشغولون. الجودة تخبرك أنهم يقومون بالعمل بالفعل. وجّه لوحة معلومات إلى [درجات التقييم](/ar/agenteye/evaluations) الخاصة بك وستحصل على لوحة تتابع مدى جودة سير التشغيل عبر الوقت، بحيث يظهر تراجع الجودة كانخفاض على الرسم البياني بدلاً من مفاجأة من العميل. -![لوحة تحكم موجهة نحو الجودة مبنية من استعلامات التقييم المحفوظة](/agenteye/images/dashboard-quality.png) +![لوحة معلومات تركز على الجودة مبنية من استعلامات التقييم المحفوظة](/agenteye/images/dashboard-quality.png) -*لوحة الجودة تبقي درجات التقييم في المقدمة والمركز، بجانب الأرقام التشغيلية مباشرة.* +*لوحة الجودة تبقي درجات التقييم في الواجهة الأمامية والمركز، بجانب الأرقام التشغيلية مباشرة.* -احفظ لوحة عمليات ولوحة جودة جنباً إلى جنب وسيكون لفريقك مكان واحد للإجابة على كلا السؤالين: "هل تعمل؟" و"هل هي جيدة؟"، دون أن يعيد أي شخص تشغيل استعلام. +احتفظ بلوحة عمليات ولوحة جودة جنباً إلى جنب وسيكون لدى فريقك مكان واحد للإجابة على كلا السؤالين "هل يعمل؟" و "هل هو جيد؟"، دون أن يضطر أحد لإعادة تشغيل استعلام. -## ذات الصلة +## ذات صلة -- [الاستعلامات](/ar/agenteye/queries): بناء وحفظ الاستعلامات التي تصبح بلاطاتك. -- [التقييمات](/ar/agenteye/evaluations): سجّل عمليات التشغيل الخاصة بك حتى تتمكن من رسم الجودة عبر الزمن. -- [التنبيهات](/ar/agenteye/alerts): حول حد على أي من هذه المقاييس إلى صفحة. \ No newline at end of file +- [الاستعلامات](/ar/agenteye/queries): بناء واحفظ الاستعلامات التي تصبح بلاطاتك. +- [التقييمات](/ar/agenteye/evaluations): سجّل تقييم التشغيلات الخاصة بك حتى تتمكن من رسم الجودة عبر الوقت. +- [التنبيهات](/ar/agenteye/alerts): حول حد معين على أي من هذه المقاييس إلى صفحة. \ No newline at end of file diff --git a/docs/ar/agenteye/error-tracking.mdx b/docs/ar/agenteye/error-tracking.mdx index f0db6694..c225fe69 100644 --- a/docs/ar/agenteye/error-tracking.mdx +++ b/docs/ar/agenteye/error-tracking.mdx @@ -1,41 +1,42 @@ --- +--- title: "تتبع الأخطاء" -description: "اطّلع على كل الأخطاء التي ينتجها وكلاؤك في مكان واحد، مجمّعة بحيث تظهر الدفقة الصاخبة كمشكلة واحدة." +description: "اطّلع على كل الأخطاء التي تنتجها وكلاؤك في مكان واحد، مجمّعة بحيث تظهر الفترة المشحونة كمشكلة واحدة." --- -اطّلع على كل الأخطاء التي ينتجها وكلاؤك في مكان واحد، مجمّعة بحيث تظهر الدفقة الصاخبة كمشكلة واحدة. تحصل على مسار بنقرة واحدة من "هناك شيء احمر" إلى التشغيل الدقيق الذي تعطّل، دون الحاجة للتمرير عبر تغذية مباشرة للعثور عليه. +اطّلع على كل الأخطاء التي تنتجها وكلاؤك في مكان واحد، مجمّعة بحيث تظهر الفترة المشحونة كمشكلة واحدة. ستحصل على مسار بنقرة واحدة من "شيء ما باللون الأحمر" إلى عملية التشغيل الدقيقة التي توقفت، دون الحاجة للتمرير عبر تغذية مباشرة للعثور عليها. -![صفحة الأخطاء: رسم بياني يعرض الأخطاء عبر الزمن أعلاه، مع صفوف الأخطاء الحمراء المجمّعة، كل منها بزر "+تنبيه" بنقرة واحدة](/agenteye/images/errors.png) -*صفحة الأخطاء: رسم بياني يعرض الأخطاء عبر الزمن، مع انهيار الأخطاء المتكررة في صف واحد لكل حادثة.* +![صفحة الأخطاء: رسم بياني للفشل عبر الزمن أعلاه صفوف أخطاء حمراء مجمّعة، كل منها مع زر "+ تنبيه" بنقرة واحدة](/agenteye/images/errors.png) +*صفحة الأخطاء: رسم بياني للفشل عبر الزمن، مع طي الأخطاء المتكررة في صف واحد لكل حادثة.* ## كل خطأ، تم جمعه لك بالفعل -عندما يتعطل الوكيل، لا يجب عليك التمرير عبر تدفق الأحداث المباشر على أمل اكتشاف الصفوف الحمراء قبل أن تختفي. تقوم صفحة **الأخطاء** بالجمع نيابة عنك. فهي تجمع كل شيء قد تعرضه لوحة المعلومات باللون الأحمر في سطح فحص واحد، بحيث يكون أول ما تراه هو ما يتعطل، وليس أين تذهب للبحث عنه. +عندما ينقطع الوكيل، لا يجب أن تضطر للتمرير عبر تدفق أحداث مباشر على أمل اكتشاف الصفوف الحمراء قبل أن تختفي. تقوم صفحة **الأخطاء** بالجمع نيابة عنك. تجمع كل شيء سيظهره لوحة التحكم باللون الأحمر في سطح واحد للفحص السريع، بحيث يكون أول شيء تراه هو ما ينقطع، وليس أين تذهب للبحث عنه. -وهي تعثر على أكثر من الواضح منها. إلى جانب أحداث `error` الصريحة، تطبيق Failproof AI Observability يسلّط الضوء على الأخطاء الصامتة أيضًا: أي `tool_result` أو `hook_completed` أو `agent_end` يحمل حمولته فشل يظهر هنا. أداة أرجعت خطأ، أو خطاف انتهى بشكل سيء، لا يمكن أن ينزلق بعيدًا عنك فقط لأنه لم يرمِ استثناء صاخبًا. +وتكتشف أكثر من الأخطاء الواضحة. بالإضافة إلى أحداث `error` الصريحة، توفر ملاحظات Failproof AI أيضًا الأخطاء الصامتة: أي `tool_result` أو `hook_completed` أو `agent_end` يحتوي حمله على فشل يظهر هنا. أداة أرجعت خطأ، أو hook انتهى بشكل سيء، لم تعد تمر بجانبك دون أن يتم رفع استثناء عالي الصوت. -عبر الأعلى، رسم بياني يحتسب الأخطاء عبر الزمن. نظرة واحدة تخبرك ما إذا كان هذا تسربًا ثابتًا في الخلفية أم ارتفاعًا بدأ قبل بضع دقائق، بحيث تعرف على الفور ما إذا كان يجب عليك إسقاط ما تفعله. +عبر الأعلى، يرسم رسم بياني الأخطاء عبر الزمن. تخبرك نظرة واحدة ما إذا كان هذا تدفقًا خلفيًا ثابتًا أم ارتفاعًا بدأ قبل دقائق قليلة، بحيث تعرف على الفور ما إذا كنت بحاجة للتوقف عما تفعله. -مثل كل سطح مراقبة، صفحة الأخطاء محدودة بنطاق مؤسستك وتصفية حسب نطاق التاريخ والبيئة والوكيل والجلسة. هذا يعني أنه يمكنك أخذ قائمة على مستوى الأسطول وتضييقها إلى الوكيل الواحد أو البيئة الواحدة التي تهمك فعلاً. +مثل كل سطح ملاحظة، صفحة الأخطاء محدودة بالنطاق لمؤسستك وتصفيتها حسب نطاق التاريخ والبيئة والوكيل والجلسة. هذا يعني أنه يمكنك الحصول على قائمة بحجم الأسطول وتضييقها إلى الوكيل الواحد أو البيئة الواحدة التي تهمك فعلاً. ## حادثة واحدة، وليس مئة صف متطابق -يمكن لتبعية مكسورة واحدة أن تطلق نفس الخطأ مئات المرات في الدقيقة. إذا تركت خامًا، فهي جدار من الخطوط المتشابهة جدًا التي تدفن الشيء الوحيد الذي تحتاج فعلاً إلى رؤيته. +اعتماد واحد منقطع يمكن أن يطلق نفس الخطأ مئات المرات في الدقيقة. إذا تركت الأمر في شكله الخام، فستواجه جدارًا من الأسطر المتطابقة تقريبًا التي تطمس الشيء الواحد الذي تحتاج إليه بالفعل. -يطبيق Failproof AI Observability ينهار الأخطاء المتكررة التي تشترك في نفس الجلسة ونوع الخطأ في صف واحد. الدفقة تقرأ كحادثة واحدة. ينتهي بك الحال بعد عد المشاكل، وليس سطور السجل، والإشارة التي تهم تبقى في الأعلى بدلاً من أن تغرق تحت وزنها الخاص. +تطوي ملاحظات Failproof AI الأخطاء المتكررة التي تشترك في نفس الجلسة ونوع الخطأ في صف واحد. يقرأ الانفجار كحادثة واحدة. ينتهي بك الحال بعد عد المشاكل، وليس سطور السجلات، والإشارة التي تهم تبقى في الأعلى بدلاً من أن تغرق في حجمها الخاص. -## من "هناك شيء احمر" إلى الحدث الدقيق +## من "شيء ما باللون الأحمر" إلى الحدث الدقيق -انقر على أي صف للوصول مباشرة إلى جلسة هذا التشغيل، محددًا على الحدث الدقيق الذي فشل. لا نسخ معرفات الجلسة، لا التمرير للبحث عن اللحظة التي ساءت: تصل إليها مباشرة، مع الرسم البياني التنفيذي الكامل على بُعد نظرة واحدة بحيث يمكنك رؤية ما الذي قام به الوكيل في اللحظات قبل أن يتعطل. +انقر على أي صف للوصول مباشرة إلى جلسة هذا التشغيل، محددة على الحدث الدقيق الذي فشل. لا نسخ معرّفات الجلسة، لا تمرير للبحث عن اللحظة التي توقف فيها: تصل إليها مباشرة، مع رسم بياني التنفيذ الكامل في نظرة واحدة لتتمكن من رؤية ما فعله الوكيل في اللحظات قبل انقطاعه. -إذا كان لديك `alerts:write`، فإن كل صف يحمل أيضًا زر **+ alert**. انقر عليه وتطبيق Observability يفتح قاعدة تنبيه جديدة مملوءة بالفعل للقبض على نفس الفشل مرة أخرى. الحادثة التي قمت بفحصها للتو تصبح الحادثة التي تنبهك في المرة القادمة، بدلاً من مفاجأتك مرتين. +إذا كانت لديك `alerts:write`، فكل صف يحمل أيضًا زر **+ تنبيه**. انقر عليه وستفتح ملاحظات قاعدة تنبيه جديدة مملوءة بالفعل للقبض على نفس الفشل مرة أخرى. تصبح الحادثة التي فحصتها للتو هي التي ستنبهك في المرة القادمة، بدلاً من مفاجأتك مرتين. -**أين تجده:** صفحة **الأخطاء** توجد في قسم المراقبة من لوحة المعلومات، في `//errors`. +**أين تجده:** تقع صفحة **الأخطاء** في قسم الملاحظات في لوحة التحكم، في `//errors`. -## ذات صلة +## ذات الصلة -- [التنبيهات](/ar/agenteye/alerts): حول أي فشل إلى قاعدة نداء. -- [الحوادث](/ar/agenteye/incidents): تتبع التنبيه الناشط من الفتح إلى الحل. +- [التنبيهات](/ar/agenteye/alerts): حوّل أي فشل إلى قاعدة تنبيه. +- [الحوادث](/ar/agenteye/incidents): تتبع تنبيه يطلق من فتح إلى حل. - [الجلسات](/ar/agenteye/sessions): افتح التشغيل الكامل خلف أي خطأ. -- [المراجعات](/ar/agenteye/audits): دع تطبيق Observability يعثر على أنماط الفشل عبر تشغيلاتك نيابة عنك. \ No newline at end of file +- [عمليات التدقيق](/ar/agenteye/audits): دع ملاحظات تجد أنماط الفشل عبر تشغيلاتك لك. \ No newline at end of file diff --git a/docs/ar/agenteye/evaluation-suite.mdx b/docs/ar/agenteye/evaluation-suite.mdx index fb5b05b1..3817416b 100644 --- a/docs/ar/agenteye/evaluation-suite.mdx +++ b/docs/ar/agenteye/evaluation-suite.mdx @@ -1,21 +1,21 @@ --- title: "مجموعة التقييم" -description: "يمكن لـ Failproof AI Observability تسجيل كل جلسة وكيل مكتملة تلقائياً من حيث الجودة: أنت توفر خدمة تسجيل صغيرة، وتتعامل Observability مع الباقي." +description: "يمكن لـ Failproof AI Observability تسجيل كل تشغيل وكيل منتهٍ تلقائياً من حيث الجودة: أنت توفر خدمة تسجيل صغيرة، و Observability يتعامل مع الباقي." --- -يمكن لـ Failproof AI Observability تسجيل كل جلسة وكيل مكتملة تلقائياً من حيث الجودة: أنت توفر خدمة تسجيل صغيرة، وتتعامل Observability مع الباقي. استخدمها لتتبع الأبعاد التي تهمك (الفائدة، كفاءة الأدوات، الدقة، الأمان؛ اختر أنت)، اكتشف الانحدار مبكراً، وقارن الوكلاء أو البيئات في لمحة واحدة. التسجيل اختياري: لا يفعل خط الأنابيب شيئاً حتى تعيّن `EVALUATOR_ENDPOINT` على الخادم. +يمكن لـ Failproof AI Observability تسجيل كل تشغيل وكيل منتهٍ تلقائياً من حيث الجودة: أنت توفر خدمة تسجيل صغيرة، و Observability يتعامل مع الباقي. استخدمها لتتبع الأبعاد التي تهمك (الفائدة، كفاءة الأدوات، دقة الحقائق، الأمان؛ أنت من تختار)، التقط الانحدارات مبكراً، وقارن بين الوكلاء أو البيئات بنظرة واحدة. التسجيل اختياري: لا يفعل المسار شيئاً حتى تعين `EVALUATOR_ENDPOINT` على الخادم. -> **ملاحظة:** أنت تحدد أبعاد النقاط. يمكن لمُقيّمك إرجاع أي مفاتيح رقمية يريدها؛ تخزن Observability وتتجه وتعرض كل ما تُرسله مرة أخرى. +> **ملاحظة:** أنت تحدد أبعاد التسجيل. يمكن لمقيّمك إرجاع أي مفاتيح رقمية يفضلها؛ يخزن Observability ويرسم البيانات ويعرض كل ما تعيده. -## لمحة سريعة +## نظرة عامة -1. **اكتب مُسجّل.** أنشئ خدمة HTTP صغيرة تقرأ نسخة من جلسة وترجع نقاط. تشحن Observability مرجعاً يعمل يمكنك نسخه. انظر [كتابة مُقيّم مع SDK](#writing-an-evaluator-with-the-sdk). +1. **اكتب محقق الجودة.** أنشئ خدمة HTTP صغيرة تقرأ نص جلسة وترجع التقييمات. يأتي Observability مع مرجع عملي يمكنك نسخه. انظر [كتابة مقيّم باستخدام SDK](#writing-an-evaluator-with-the-sdk). 2. **وجّه Observability إليه.** عيّن `EVALUATOR_ENDPOINT` (و`EVALUATOR_TOKEN` مشترك) على عملية الخادم. -3. **راقب النقاط تصل.** كل جلسة مكتملة يتم تسجيلها تلقائياً؛ تظهر النتائج على صفحة تفاصيل الجلسة، شبكة الجلسات، والقوائم المحفوظة. +3. **راقب التقييمات.** يتم تقييم كل جلسة مكتملة تلقائياً؛ تظهر النتائج على صفحة تفاصيل الجلسة، شبكة الجلسات، والملاحظات المحفوظة. -![عرض تفاصيل الجلسة مع ملخص التقييم، أشرطة نقاط لكل بعد، ونص التبرير في الشريط الأيمن](/agenteye/images/session-detail.png) +![عرض تفاصيل جلسة مع ملخص التقييم، أشرطة النتائج حسب البعد، ونص التفكير في الجزء الأيمن](/agenteye/images/session-detail.png) -*بمجرد تكوين مُقيّم، يتم تسجيل كل عملية مكتملة وتظهر النتائج في الشريط الأيمن للجلسة: الملخص في الأعلى، ثم أشرطة نقاط لكل بعد مع التبرير.* +*بمجرد تكوين مقيّم، يتم تقييم كل تشغيل مكتمل وتظهر النتائج في الشريط الأيمن للجلسة: الملخص في الأعلى، ثم أشرطة النتائج حسب البعد مع التفكير.* --- @@ -31,44 +31,44 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -عندما يُصدر Failproof AI Observability SDK حدث `agent_end` لجلسة، يجدول الخادم تقييماً. ثم يُرسل نسخة الحدث الكاملة إلى خدمة المُقيّم الخاصة بك، والتي يمكنها إما: +عندما يصدر SDK Observability حدث `agent_end` لجلسة، يجدول الخادم تقييماً. ثم يرسل نص الحدث الكامل إلى خدمة المقيّم، التي يمكنها إما: -- **إرجاع النتيجة مباشرة** مع `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. تُلحق النتيجة بجدول تقييم الجلسة. `reasoning` و `summary` اختياريين. -- **تأجيل** مع `{"status":"pending", "job_id":"abc-123"}`. ثم تستدعي Observability `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` حتى يُرجع مُقيّمك `{"status":"done", ...}` أو `{"status":"error", "error":"..."}`. +- **إرجاع النتيجة مباشرة** باستخدام `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. تُضاف النتيجة إلى جدول زمني التقييم للجلسة. `reasoning` و `summary` اختياريان. +- **تأجيل** باستخدام `{"status":"pending", "job_id":"abc-123"}`. ثم يستدعي Observability `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` حتى يعيد المقيّم `{"status":"done", ...}` أو `{"status":"error", "error":"..."}`. - وتيرة الاستقصاء لكل وظيفة: قد تتضمن استجابة `pending` `next_poll_secs` للتجاوز؛ وإلا فتستخدم Observability قيمة `default_poll_interval_secs` من `GET /config`؛ وإلا يعود الخادم إلى `EVALUATOR_POLLING_INTERVAL_SECS` (افتراضي 10 ثانية). جميع القيم محصورة في [1 ثانية، 1 ساعة]. + تكرار الاستطلاع يكون لكل وظيفة: قد تتضمن استجابة `pending` `next_poll_secs` للتجاوز؛ وإلا يستخدم Observability قيمة `default_poll_interval_secs` من `GET /config`؛ وإلا يعود الخادم إلى `EVALUATOR_POLLING_INTERVAL_SECS` (افتراضي 10 ثوانٍ). جميع القيم محصورة في [1 ثانية، 1 ساعة]. -يمكن أيضاً التقاط الجلسات التي لم تُصدر أبداً `agent_end` (على سبيل المثال، عملية وكيل منهارة): قد يُرجع `GET /config` الخاص بالمُقيّم `{"inactivity_timeout_secs": 1800}`، وستقيّم Observability أي جلسة خاملة لتلك المدة. عيّن الحقل إلى `null` أو احذفه لتعطيل هذا البديل. +يمكن التقاط الجلسات التي لم تصدر أبداً `agent_end` (على سبيل المثال، عملية وكيل متعطلة) أيضاً: قد يعيد `GET /config` للمقيّم `{"inactivity_timeout_secs": 1800}`، و Observability سيقيّم أي جلسة لم تنشط لفترة طويلة. اضبط الحقل على `null` أو حذفه لتعطيل هذا الخيار. -خط الأنابيب عديم التأثير تماماً عندما يكون `EVALUATOR_ENDPOINT` غير محدد. +المسار بالكامل عدم تشغيلي عندما لا يكون `EVALUATOR_ENDPOINT` معيناً. -يمكن للجلسة تجميع **تقييمات نهائية متعددة بمرور الوقت**: كل حدث `agent_end` (وكل إعادة تقييم يدوية من القوائس) تُلحق صف تقييم جديد. هذه هي الطريقة المدعومة لتقييم محادثة مستأنفة: ينهي المستخدم وكيلاً، ويعود لاحقاً، يُرسل المزيد من الأحداث، ينهي الوكيل مرة أخرى، ويعمل تقييم ثانٍ ضد النسخة الكاملة المحدثة. تُصيّر القوائس أحدث تقييم كعنوان رئيسي والتقييمات السابقة كجدول زمني قابل للطي. بينما يعمل تقييم واحد لجلسة، تُتجاهل أحداث `agent_end` الإضافية لتلك الجلسة؛ الحدث التالي بعد انتهاء التقييم الجاري سيُدرج تقييماً جديداً كالمعتاد. +يمكن لجلسة تراكم **تقييمات نهائية متعددة عبر الوقت**: كل حدث `agent_end` (وكل إعادة تقييم يدوية من لوحة التحكم) تضيف صف تقييم جديد. هذه هي الطريقة المدعومة لتقييم محادثة مستأنفة: ينهي المستخدم وكيلاً، يعود لاحقاً، يرسل المزيد من الأحداث، ينهي الوكيل مرة أخرى، وينفذ التقييم الثاني ضد النص المحدث الكامل. تعرض لوحة التحكم آخر تقييم كعنوان رئيسي والتقييمات السابقة كجدول زمني قابل للطي. بينما يعمل تقييم واحد لجلسة ما، يتم تجاهل أحداث `agent_end` الإضافية لتلك الجلسة؛ سيؤدي الحدث التالي بعد انتهاء التقييم قيد التشغيل إلى إدراج تقييم جديد كالمعتاد. -يُعاد تفعيل بديل عدم النشاط على الجلسات المستأنفة أيضاً: إذا وصلت أحداث جديدة بعد تقييم نهائي سابق وذهبت الجلسة خاملة بعد `inactivity_timeout_secs`، يُدرج تقييم جديد في الطابور. +يعاود التفاعل الخيار الاحتياطي للخمول في الجلسات المستأنفة أيضاً: إذا وصلت أحداث جديدة بعد تقييم نهائي سابق وذهبت الجلسة بعد ذلك خامدة بعد `inactivity_timeout_secs`، يتم إدراج تقييم جديد. -الأعطال العابرة (5xx، 429، انتهاءات المهلة الزمنية، أخطاء الشبكة) تُعاد محاولتها مع تراجع أسي حتى `EVALUATOR_MAX_ATTEMPTS`؛ استجابات 4xx نهائية. Observability آمن للتشغيل مع خوادم متعددة مقسمة أفقياً؛ يُقسم العمل بحيث لا تُرسل نفس الجلسة مرتين معاً. +يتم إعادة محاولة الأعطال العابرة (5xx، 429، انتهاء المهلة الزمنية، أخطاء الشبكة) مع تراجع أسي يصل إلى `EVALUATOR_MAX_ATTEMPTS`؛ استجابات 4xx نهائية. من الآمن تشغيل Observability مع عدة خوادم مقيّمة بشكل أفقي؛ يتم تقسيم العمل بحيث لا تُرسل نفس الجلسة مرتين بالتزامن. --- ## عقد HTTP -كل مسار مصادق يستخدم **مصادقة رمز الحامل**. يجب أن تكون نفس القيمة مُعدة على كلا الجانبين: +كل مسار مصرح عليه يستخدم **مصادقة رمز حامل**. يجب أن تكون نفس القيمة معيّنة على كلا الجانبين: -- خادم Observability: متغير env `EVALUATOR_TOKEN` -- خدمة المُقيّم: معدة بنفس الطريقة (يقرأ `EVALUATOR_TOKEN` SDK `agenteye-evaluator` حسب الاتفاقية) +- خادم Observability: متغير البيئة `EVALUATOR_TOKEN` +- خدمة المقيّم: معيّن بنفس الطريقة (يقرأ SDK `agenteye-evaluator` `EVALUATOR_TOKEN` بالاتفاقية) -إذا كان `EVALUATOR_TOKEN` غير محدد، لا يُرسل الخادم رأس `Authorization`؛ قد يقبل المُقيّم طلبات مجهولة، وهذا جيد لشبكة داخلية فقط لكن غير موصى به على الإنترنت العام. +إذا لم يكن `EVALUATOR_TOKEN` معيناً، لا يرسل الخادم رأس `Authorization`؛ قد يقبل المقيّم طلبات مجهولة، وهي بخير لشبكة داخلية فقط لكن غير موصى بها على الإنترنت العام. -### المسارات التي يجب أن يخدمها المُقيّم +### الطرق التي يجب أن يخدمها المقيّم | المسار | الجسم / المعاملات | الاستجابة | |---|---|---| -| `GET /health` | بلا | `{"status":"ok"}` (مفتوح، بدون مصادقة) | -| `GET /config` | بلا | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | -| `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` أو `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | بلا | نفس شكل الاستجابة `/evaluate` | +| `GET /health` | لا شيء | `{"status":"ok"}` (مفتوح، بدون مصادقة) | +| `GET /config` | لا شيء | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | +| `POST /evaluate` | JSON `EvalRequest` | `{"status":"done", ...}` أو `{"status":"pending", "job_id":"..."}` | +| `GET /evaluate/{id}` | لا شيء | نفس شكل الاستجابة مثل `/evaluate` | -### جسم `EvalRequest` المُرسل من الخادم +### جسم `EvalRequest` الذي يرسله الخادم ```json { @@ -87,7 +87,7 @@ flowchart LR ### أشكال الاستجابة -**متزامن (مكتمل):** +**متزامن (تم):** ```json { @@ -101,7 +101,7 @@ flowchart LR } ``` -`reasoning` (خريطة تبرير لكل نقطة) و `summary` (سرد واحد شامل) كلاهما اختياري. يجب أن تعكس المفاتيح في `reasoning` المفاتيح في `scores`؛ تُصيّر القوائس كل إدخال مباشرة تحت شريط النقاط الخاص به. المُقيّمون الأقدم الذين يُرجعون `scores` فقط يستمرون في العمل بدون تغيير؛ `reasoning` و `summary` ببساطة يُقرآن كـ null وتُحذف تسهيلات الواجهة المقابلة. +`reasoning` (خريطة تبرير لكل نقطة) و `summary` (رواية شاملة لفقرة واحدة) كلاهما اختياري. يجب أن تعكس المفاتيح في `reasoning` المفاتيح في `scores`؛ تعرض لوحة التحكم كل إدخال مدمجاً تحت شريط النقاط الخاص به. تستمر المقيّمات الأقدم التي ترجع فقط `scores` في العمل دون تغيير؛ ببساطة قراءة `reasoning` و `summary` كـ null وحذف التأثيرات المقابلة للواجهة. **غير متزامن (مؤجل):** @@ -109,25 +109,25 @@ flowchart LR { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` اختياري؛ إذا تم حذفه يعود الخادم إلى `default_poll_interval_secs` الخاص بالمُقيّم من `/config`، ثم إلى متغير env `EVALUATOR_POLLING_INTERVAL_SECS` الخاص به. +`next_poll_secs` اختياري؛ إذا تم حذفه يعود الخادم إلى `default_poll_interval_secs` للمقيّم من `/config`، ثم إلى متغير البيئة `EVALUATOR_POLLING_INTERVAL_SECS` الخاص به. -**خطأ نهائي من جانب المُقيّم:** +**خطأ نهائي من جانب المقيّم:** ```json { "status": "error", "error": "model service unavailable" } ``` -يتعامل الخادم مع أي جسم 2xx آخر كخطأ بروتوكول ويسجل `error` نهائي للجلسة. +يعامل الخادم أي جسم 2xx آخر كخطأ في البروتوكول ويسجل `error` نهائي للجلسة. --- -## كتابة مُقيّم مع SDK +## كتابة مقيّم باستخدام SDK -لا يجب أن تُطبق عقد HTTP باليد. حزمة `agenteye-evaluator` Python توفر لك غلاف FastAPI مكتوب يتعامل مع المصادقة والتوجيه وأشكال الطلب/الاستجابة لك. +لا تضطر إلى تنفيذ عقد HTTP يدوياً. تعطيك حزمة `agenteye-evaluator` Python غلافاً FastAPI مكتوباً بأنواع يتعامل مع المصادقة والتوجيه وأشكال الطلب/الاستجابة نيابة عنك. -تشحن Failproof AI Observability أيضاً **مُقيّم مرجعي يعمل** يسجل `helpfulness` و `tool_efficiency` و `factuality` من شكل النسخة. انسخه كنقطة بداية وبدّل منطقك الخاص: قاضٍ LLM، محرك قواعد، أي شيء يناسب معيار الجودة لديك. +يأتي Failproof AI Observability أيضاً مع **مقيّم مرجعي عملي** يسجل `helpfulness` و `tool_efficiency` و `factuality` من شكل النص. انسخه كنقطة بداية واستبدل بمنطقك الخاص: حكم LLM، محرك قواعد، أي شيء يناسب معيار جودتك. -مُقيّم قابل للحياة الدنيا: +الحد الأدنى المقيّم القابل للحياة: ```python import os @@ -146,60 +146,60 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -مثيل `app` يعمل تحت أي خادم ASGI، لذا `uvicorn module:app` يبدئه. +تعمل نسخة `app` تحت أي خادم ASGI، لذا `uvicorn module:app` يبدأها. -بالنسبة للمُقيّمين الذين يحتاجون تأجيل عمل مكلف، أرجع `JobPending` بدلاً من ذلك وسجل معالج `@app.job_lookup`؛ يستقصي خادم Observability `GET /evaluate/{job_id}` حتى تُرجع حالة نهائية أو تنقضي قيمة حد `EVALUATOR_MAX_POLL_DURATION_SECS` (افتراضي 1 ساعة). +بالنسبة للمقيّمين الذين يحتاجون إلى تأجيل العمل المكلف، أرجع `JobPending` بدلاً من ذلك وسجل معالج `@app.job_lookup`؛ يستطلع خادم Observability `GET /evaluate/{job_id}` حتى تعيد حالة نهائية أو حتى ينقضي حد `EVALUATOR_MAX_POLL_DURATION_SECS` (افتراضي 1 ساعة). -مرجع الـ API الكامل والنمط غير المتزامن وشماء الحدث موثقة في قراءة `agenteye-evaluator` SDK. +توثق مرجعية API الكاملة والنمط غير المتزامن ومخطط الحدث في ملف README SDK `agenteye-evaluator`. --- -## تشغيل مُقيّمك +## تشغيل المقيّم -المُقيّم هو **خدمتك** — لا تشحن Failproof AI Observability مُقيّماً افتراضياً، لذا تبني وتشغل أينما تشغل خدماتك. يعمل تحت أي خادم ASGI (على سبيل المثال `uvicorn my_evaluator:app`؛ خدم المسارات `/health` و `/config` و `/evaluate` من [عقد HTTP](#http-contract)، ثم وجّه الخادم إليه (انظر [تكوين الخادم](#configuring-the-server)). +المقيّم هو **خدمتك** — Failproof AI Observability لا يأتي مع مقيّم افتراضي، لذا تبنيه وتشغله أينما تشغل خدماتك الخاصة. يعمل تحت أي خادم ASGI (على سبيل المثال `uvicorn my_evaluator:app`؛ قدّم مسارات `/health` و `/config` و `/evaluate` من [عقد HTTP](#http-contract)، ثم وجّه الخادم إليه (انظر [تكوين الخادم](#configuring-the-server)). -بمجرد وصول المُقيّم، `GET /health` يُرجع `{"status":"ok"}`. بعد انتهاء الوكيل من البداية إلى النهاية، `GET /evaluations` على الخادم يُرجع صفاً مع `status: "done"` والنقاط التي أنتجها مُقيّمك. +بمجرد وصول المقيّم، `GET /health` يعيد `{"status":"ok"}`. بعد انتهاء تشغيل وكيل من النهاية إلى النهاية، `GET /evaluations` على الخادم يعيد صفاً مع `status: "done"` والتقييمات التي أنتجها المقيّم. --- ## تكوين الخادم -عيّن على عملية الخادم: +اضبط على عملية الخادم: -| متغير Env | المعنى | +| متغير البيئة | المعنى | |---|---| -| `EVALUATOR_ENDPOINT` | URL الأساسي لمُقيّمك (`http://evaluator:9000`). غير محدد = خط أنابيب معطل. | -| `EVALUATOR_TOKEN` | رمز الحامل. يجب أن يساوي القيمة التي عُدت خدمة المُقيّم معها. | -| `EVALUATOR_WORKERS` | مهام العامل لكل مثيل خادم (افتراضي 2). | -| `EVALUATOR_CLAIM_BATCH` | الصفوف المُستقاة لكل تطبيق عامل (افتراضي 4). تُعالج الدفعات **معاً**؛ الدرجة الفعالة على نقطة المُقيّم هي `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | مدة نوم العامل بين محاولات الإرسال عند عدم وجود تقييم مستحق (افتراضي 2 ثانية). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | التراجع النهائي لوتيرة `GET /evaluate/{id}` عند عدم تعيين كل من `next_poll_secs` في الاستجابة أو `default_poll_interval_secs` الخاص بالمُقيّم (افتراضي 10 ثانية). | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | انتهاء مهلة زمنية لكل طلب (افتراضي 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | بعد هذا العديد من الأعطال العابرة يُسجل الناتج كـ `error` نهائي (افتراضي 5). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | وتيرة `GET /config` (افتراضي 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | الحد الأقصى من الوقت الحقيقي الذي يمكن أن تبقى الجلسة في طابور الاستقصاء قبل إنهاؤها كـ `timeout` (افتراضي 3600 ثانية). حماية من مُقيّم يستمر في إرجاع `pending` للأبد. | +| `EVALUATOR_ENDPOINT` | عنوان URL الأساسي للمقيّم (`http://evaluator:9000`). غير معيّن = خط أنابيب معطل. | +| `EVALUATOR_TOKEN` | رمز حامل. يجب أن تساوي القيمة التي تم تكوين خدمة المقيّم بها. | +| `EVALUATOR_WORKERS` | مهام العاملين لكل نسخة خادم (افتراضي 2). | +| `EVALUATOR_CLAIM_BATCH` | الصفوف المطالب بها لكل تكرار عامل (افتراضي 4). يتم معالجة الدفعات **بالتزامن**؛ المزامنة الفعلية على نقطة نهاية المقيّم هي `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | كم من الوقت ينام العامل بين محاولات الإرسال عندما لا يكون التقييم مستحقاً (افتراضي 2 ثانية). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | الخيار الاحتياطي النهائي لتكرار `GET /evaluate/{id}` عندما لا يكون `next_poll_secs` للاستجابة ولا `default_poll_interval_secs` للمقيّم معيناً (افتراضي 10 ثوانٍ). | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | انتهاء مهلة لكل طلب (افتراضي 30000). | +| `EVALUATOR_MAX_ATTEMPTS` | بعد هذا العدد من الأعطال العابرة تُسجل النتيجة كخطأ نهائي (افتراضي 5). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | تكرار `GET /config` (افتراضي 300). | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | أقصى وقت حائط لبقاء جلسة في قائمة الاستطلاع قبل إنهاؤها كـ `timeout` (افتراضي 3600 ثانية). يحمي من مقيّم يستمر في إرجاع `pending` إلى الأبد. | -لتفعيل التسجيل التلقائي، عيّن كلاً من `EVALUATOR_ENDPOINT` و `EVALUATOR_TOKEN` على الخادم، ثم أعد تشغيله لاستقبال التغيير. مع عدم تعيين `EVALUATOR_ENDPOINT` يبقى خط الأنابيب عديم التأثير. +لتشغيل التسجيل التلقائي، عيّن كلاً من `EVALUATOR_ENDPOINT` و `EVALUATOR_TOKEN` على الخادم، ثم أعد تشغيله لالتقاط التغيير. مع عدم تعيين `EVALUATOR_ENDPOINT` يبقى المسار عدم تشغيلي. -أزرار المعايرة أعلاه اختيارية؛ عيّن متغيرات البيئة المقابلة على الخادم فقط إذا اضطررت لتجاوز الافتراضيات. +أزرار الضبط أعلاه اختيارية؛ عيّن متغيرات البيئة المقابلة على الخادم فقط إذا كنت بحاجة إلى تجاوز الافتراضيات. --- ## مرجع API -| الطريقة | المسار | الصلاحية المطلوبة | الغرض | +| الطريقة | المسار | الإذن المطلوب | الغرض | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | الاستعلام النتائج النهائية. يدعم `session_id` و `agent_id` و `environment` و `status` (`done`/`error`/`timeout`) و `ts_from` و `ts_to` و `cursor` و `limit` و `score_filters` و `latest_per_session`. `limit` افتراضي 50 ومحصور عند 200 (لاحظ هذا يختلف عن `/events` الذي يحد عند 1000). `environment` يقبل قائمة مفصولة بفواصل (مثل `environment=prod,staging`)؛ القيم الفردية لا تزال تعمل. مع `latest_per_session=true` تحتوي الاستجابة على صف واحد على الأكثر لكل `session_id` (الأحدث بـ `completed_at`) يُستخدم من صفحة قائمة الجلسات لطي جدول الجلسة الزمني إلى عنوانها الحالي. افتراضي false (يُرجع السجل الكامل). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | صحة تقييم مدرجة لشريحة مصفاة: إجمالي العدد، تفصيل done/error/timeout، إحصائيات لكل مفتاح نقطة (عدد/متوسط/min/max/p50 على مفاتيح `scores` التعسفية)، وجدول زمني مقسم بالوقت. يقبل **نفس معاملات تصفية `/evaluations`** بالإضافة إلى `featured_keys` (CSV من مفاتيح النقاط للاتجاه) و `latest_per_session`. يقوي ميزة القوائس؛ المقاييس دقيقة على المجموعة المطابقة بأكملها، وليست مُأخوذة عينات. | -| `GET` | `/evaluations/environments` | `evaluations:read` | قيم البيئة المميزة من جدول `evaluations`. يُستخدم لملء القوائس المنسدلة للتصفية المقيدة بالبيانات القابلة للقراءة للتقييم. | -| `GET` | `/evaluation-jobs` | `evaluations:read` | رؤية في التقييمات قيد الطيران. صفّي حسب `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | بث أحداث جلسة خام. يدعم `session_id` و `agent_id` و `event_type` (CSV) و `environment` (CSV) و `ts_from` و `ts_to` و `cursor` و `limit` و `order`. `order` هو `desc` (الأحدث أولاً، الافتراضي) أو `asc` (الأقدم أولاً)؛ تعود القيمة غير المعروفة إلى `desc`. استقصاء المؤشر عبر `next_cursor` الاستجابة (معرف حدث): مرره مرة أخرى كـ `cursor` للحصول على الصفحة التالية؛ مع `asc` الصفحة التالية هي الأحداث بعد ذلك المعرف، مع `desc` الأحداث قبله. `limit` افتراضي 50 ومحصور عند 1000. | -| `GET` | `/sessions/:session_id/export` | `events:read` | يُرجع جسم JSON الدقيق الذي سيستقبله المُقيّم لهذه الجلسة، مخدوماً كملحق قابل للتنزيل باسم `session-.json`. مفيد لإعادة تشغيل جلسات الإنتاج عبر `agenteye-evaluator` للاختبار دون الاتصال. البايتات متطابقة بايت لبايت مع ما يُرسله خط أنابيب المُقيّم. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | اطلب تقييماً جديداً لجلسة؛ يعمل سواء كان لدينا تقييم سابق أم لا. تُلحق النتيجة الجديدة **بـ** جدول تقييم الجلسة الزمني بدلاً من الكتابة فوق الجلسة السابقة، لذا تبقى النقاط السابقة مرئية كسجل. يُرجع `202` عند الإدراج، `404` لجلسة مجهولة، `409` إذا كان تقييم قيد الطيران بالفعل. استخدم هذا بعد نشر مُقيّم جديد، أو لجلسات لم تُصدر أبداً `agent_end`. | +| `GET` | `/evaluations` | `evaluations:read` | نتائج نهائية. يدعم `session_id` و `agent_id` و `environment` و `status` (`done`/`error`/`timeout`) و `ts_from` و `ts_to` و `cursor` و `limit` و `score_filters` و `latest_per_session`. الافتراضي `limit` 50 ومحدود بـ 200 (لاحظ أن هذا يختلف عن `/events`، الذي يحد بـ 1000). يقبل `environment` قائمة مفصولة بفواصل (مثل `environment=prod,staging`؛ القيم الفردية لا تزال تعمل. مع `latest_per_session=true` تحتوي الاستجابة على صف واحد على الأكثر لكل `session_id` (الأحدث حسب `completed_at`) يستخدمه صفحة قائمة الجلسات لطي جدول زمني تقييم الجلسة إلى عنوانها الحالي. الافتراضي خطأ (يعيد السجل الكامل). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | صحة التقييم المدرجة لشريحة مفلترة: إجمالي العدد وتفصيل done/error/timeout وإحصائيات لكل مفتاح نقطة (العدد/المتوسط/الحد الأدنى/الحد الأقصى/p50 عبر مفاتيح `scores` العشوائية)، وجدول زمني مقسم إلى وقت. يقبل **نفس معاملات التصفية مثل `/evaluations`** بالإضافة إلى `featured_keys` (CSV من مفاتيح النقاط للاتجاه) و `latest_per_session`. يشغّل ميزة الملاحظات؛ المقاييس دقيقة على مجموعة المطابقة الكاملة وليست مأخوذة عينات. | +| `GET` | `/evaluations/environments` | `evaluations:read` | قيم environment متميزة من جدول `evaluations`. يستخدم لملء قوائم تصفية مسحوبة من البيانات القابلة للقراءة التقييمية. | +| `GET` | `/evaluation-jobs` | `evaluations:read` | الرؤية في التقييمات أثناء التنفيذ. تصفية حسب `status` (`pending`/`polling`). | +| `GET` | `/events` | `events:read` | تدفق أحداث جلسة خام. يدعم `session_id` و `agent_id` و `event_type` (CSV) و `environment` (CSV) و `ts_from` و `ts_to` و `cursor` و `limit` و `order`. `order` هو `desc` (الأحدث أولاً، الافتراضي) أو `asc` (الأقدم أولاً)؛ قيمة غير معروفة تعود إلى `desc`. استطلاع Cursor عبر `next_cursor` للاستجابة (معرف حدث): مرره مرة أخرى كـ `cursor` للحصول على الصفحة التالية؛ مع `asc` الصفحة التالية هي الأحداث بعد هذا المعرف، مع `desc` الأحداث قبله. الافتراضي `limit` 50 ومحدود بـ 1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | يعيد جسم JSON الدقيق الذي سيستقبله المقيّم لهذه الجلسة، مقدم كمرفق قابل للتحميل باسم `session-.json`. مفيد لإعادة تشغيل جلسات الإنتاج من خلال `agenteye-evaluator` للاختبار غير المتصل. البايتات هي نفس ما يرسله خط أنابيب المقيّم. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | إدراج تقييم جديد لجلسة؛ ينفذ سواء كان هناك تقييم سابق أم لا. تُضاف النتيجة الجديدة **إلى** جدول زمني تقييم الجلسة بدلاً من استبدال النتيجة السابقة، لذا تبقى النقاط السابقة مرئية كسجل. يعيد `202` عند الإدراج و `404` لجلسة غير معروفة و `409` إذا كان تقييم قيد التنفيذ بالفعل. استخدم هذا بعد نشر مقيّم جديد أو للجلسات التي لم تصدر `agent_end` أبداً. | -### التصفية حسب نطاق النقاط: `score_filters` +### تصفية حسب نطاق النقاط: `score_filters` -يقبل `GET /evaluations` معامل `score_filters` اختياري يضيق النتائج حسب القيم الرقمية داخل كائن `scores`. المعامل هو قائمة مفصولة بفواصل من إدخالات `key:min..max`؛ يمكن حذف أي من الحد. تجمع الإدخالات المتعددة مع AND منطقي. تُستثنى الصفوف حيث المفتاح المسمى غائب أو غير رقمي. قد يحمل طلب واحد 20 إدخال تصفية على الأكثر؛ تجاوز ذلك يُرجع HTTP 400. +`GET /evaluations` يقبل معامل `score_filters` اختياري يضيق النتائج بقيم رقمية داخل كائن `scores`. المعامل هو قائمة مفصولة بفواصل من إدخالات `key:min..max`؛ قد يكون حد ما محذوفاً. تجتمع إدخالات متعددة مع AND منطقي. يتم استبعاد الصفوف حيث المفتاح المسمى غائب أو غير رقمي. قد يحمل الطلب 20 إدخال تصفية على الأكثر؛ يعيد تجاوز هذا HTTP 400. أمثلة: ```text @@ -217,83 +217,83 @@ GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. | الحقل | النوع | ملاحظات | |---|---|---| -| `evaluation_id` | string (UUID) | المعرّف الأساسي لهذا التقييم النهائي. يحصل كل تقييم نهائي على UUID جديد؛ يمكن للجلسة الواحدة أن تحمل متعددة. | -| `id` | string (UUID) | اسم مستعار للتوافقية للخلف يحمل نفس قيمة `evaluation_id`. | -| `session_id` | string | الجلسة التي عمل التقييم ضدها. يمكن للجلسة الواحدة أن تحمل تقييمات متعددة في الجدول الزمني. | -| `agent_id` | string | يعرّف الوكيل الذي أنتج الجلسة. | -| `environment` | string | علامة البيئة المنسوخة من الجلسة. | -| `status` | enum | واحد من `"done"` أو `"error"` أو `"timeout"`. | -| `scores` | object \| null | النقاط المُرجعة من قبل مُقيّمك. | -| `reasoning` | object \| null | خريطة تبرير اختيارية لكل نقطة مُرجعة من قبل مُقيّمك. تعكس المفاتيح عادة تلك في `scores`. تُصيّر القوائس كل إدخال تحت شريط النقاط الخاص به. | -| `summary` | string \| null | سرد واحد شامل اختياري مُرجع من قبل مُقيّمك. تُصيّر القوائس هذا فوق التفصيل لكل نقطة كعنوان التقييم. | -| `error` | string \| null | ممتلأ على `"error"` / `"timeout"` فقط. | +| `evaluation_id` | string (UUID) | المعرّف الأساسي لهذا التقييم النهائي. يحصل كل تقييم نهائي على UUID جديد؛ يمكن لجلسة واحدة أن تحتفظ بتقييمات متعددة. | +| `id` | string (UUID) | اسم مستعار للتوافقية العكسية يحمل نفس قيمة `evaluation_id`. | +| `session_id` | string | الجلسة التي أجري عليها التقييم. يمكن لجلسة أن تحتوي على تقييمات متعددة في الجدول الزمني. | +| `agent_id` | string | يحدد الوكيل الذي أنتج الجلسة. | +| `environment` | string | تسمية البيئة المنسوخة من الجلسة. | +| `status` | enum | واحد من `"done"` و `"error"` و `"timeout"`. | +| `scores` | object \| null | النقاط التي عاد بها المقيّم. | +| `reasoning` | object \| null | خريطة تبرير اختيارية لكل نقطة يعيدها المقيّم. عادة ما تعكس المفاتيح تلك في `scores`. تعرض لوحة التحكم كل إدخال تحت شريط نقاطه. | +| `summary` | string \| null | سرد اختياري شامل لفقرة واحدة يعيده المقيّم. تعرض لوحة التحكم هذا فوق تفصيل النقاط لكل عنصر كعنوان التقييم. | +| `error` | string \| null | يُملأ على `"error"` / `"timeout"` فقط. | | `attempt_count` | integer | عدد محاولات الإرسال (≥ 1). | -| `duration_ms` | integer \| null | مدة المحاولة الأخيرة. | -| `completed_at` | string (ISO 8601 UTC) | عندما تم تسجيل النتيجة النهائية. تُرتب النتائج حسب `completed_at` (الأحدث أولاً). | -| `created_at` | string (ISO 8601 UTC) | يحمل نفس الطابع الزمني كـ `completed_at` (دلالات الكتابة مرة واحدة). | +| `duration_ms` | integer \| null | مدة المحاولة النهائية. | +| `completed_at` | string (ISO 8601 UTC) | عندما تم تسجيل النتيجة النهائية. يتم ترتيب النتائج حسب `completed_at` (الأحدث أولاً). | +| `created_at` | string (ISO 8601 UTC) | يحمل نفس الطابع الزمني مثل `completed_at` (دلالات الكتابة مرة واحدة). | --- -## الصلاحيات +## الأذونات -| الصلاحية | تمنح | +| الإذن | الامتيازات | |---|---| -| `evaluations:read` | قائمة نتائج التقييم، عرض النقاط في القوائس، وتحميل مقاييس صحة القوائس. | -| `evaluations:trigger` | اطلب يدوياً تقييماً لجلسة عبر `POST /sessions/:session_id/re-evaluate` أو زر إعادة تقييم القوائس. | -| `dashboards:read` | عرض القوائس المحفوظة (يحتاج أيضاً `evaluations:read` لتحميل مقاييسها). | -| `dashboards:write` | إنشاء وتعديل القوائس. | -| `dashboards:delete` | حذف القوائس. | +| `evaluations:read` | قائمة نتائج التقييم وعرض النقاط في لوحة التحكم وتحميل مقاييس صحة لوحة التحكم. | +| `evaluations:trigger` | إدراج تقييم يدوي لجلسة عبر `POST /sessions/:session_id/re-evaluate` أو زر إعادة التقييم بلوحة التحكم. | +| `dashboards:read` | عرض الملاحظات المحفوظة (يحتاج أيضاً إلى `evaluations:read` لتحميل مقاييسها). | +| `dashboards:write` | إنشاء وتحرير الملاحظات. | +| `dashboards:delete` | حذف الملاحظات. | -يحصل المسؤول التمهيدي (`ADMIN_KEY` و `ADMIN_EMAIL`) تلقائياً على هذه. +يستقبل المسؤول التمهيدي (`ADMIN_KEY` و `ADMIN_EMAIL`) هذه تلقائياً. --- ## عرض النتائج -- **`/sessions/`**: جدول زمني للأحداث + شريط أيمن يعرض نقاط الجلسة وأي خطأ من محاولة الإرسال. إذا كان مفتاحك يملك `evaluations:trigger`، يظهر زر **إعادة تقييم** بجانب زر التصدير، مفيد للجلسات التي لم تُصدر أبداً `agent_end`، أو لتحديث النقاط بعد نشر مُقيّم جديد. تستقصي القوائس النتيجة الجديدة وتحدّث الشريط الأيمن عند وصولها. -- **`/sessions`**: شبكة جلسات قابلة للتصفية؛ عمود النقاط يعرض حالة تقييم كل جلسة ونقاطها في لمحة. -- **`/dashboards`**: عروض صحة تقييم محفوظة (انظر [القوائس](#dashboards) أدناه). +- **`/sessions/`**: جدول زمني للأحداث + شريط أيمن يعرض نقاط الجلسة وأي خطأ من محاولة الإرسال. إذا كان مفتاحك يحتوي على `evaluations:trigger`، يظهر زر **إعادة تقييم** بجانب زر التصدير، مفيد للجلسات التي لم تصدر `agent_end` أبداً أو لتحديث النقاط بعد نشر مقيّم جديد. تستطلع لوحة التحكم النتيجة الجديدة وتحدث الشريط الأيمن عند وصولها. +- **`/sessions`**: شبكة جلسة قابلة للتصفية؛ عمود النقاط يعرض حالة التقييم والنقاط لكل جلسة بنظرة واحدة. +- **`/dashboards`**: طرق صحة التقييم المحفوظة (انظر [الملاحظات](#dashboards) أدناه). -![شبكة الجلسات مع حبوب حالة تقييم لكل جلسة وشارات نقاط ملونة (helpfulness، factuality، tool_efficiency، safety، coherence)](/agenteye/images/sessions-list.png) +![شبكة الجلسات مع حبات حالة التقييم لكل جلسة وشارات النقاط ملونة (الفائدة والصحة والكفاءة والأمان والتماسك)](/agenteye/images/sessions-list.png) -*تعرض شبكة الجلسات حالة تقييم كل جلسة ونقاطها في لمحة؛ جعل الشارات الحمراء/الكهرمانية/الخضراء النقاط المنخفضة تبرز.* +*تعرض شبكة الجلسات حالة التقييم والنقاط لكل تشغيل بنظرة واحدة؛ شارات حمراء/برتقالية/خضراء تجعل النقاط المنخفضة تبرز.* --- -## القوائس +## الملاحظات -تسمح صفحة **القوائس** (`/dashboards`) بحفظ مزيج من تصافي التقييم كعرض مسمى وقابل لإعادة الاستخدام ومراقبة كيفية تطور تلك الشريحة من التقييمات في لمحة. **تُشاركت القوائس عبر منظمتك بأكملها**؛ يرى الجميع لديهم `dashboards:read` نفس المجموعة. +توفر صفحة **الملاحظات** (`/dashboards`) مجموعة محفوظة من مرشحات التقييم كعرض مسمى وقابل لإعادة الاستخدام ومراقبة أداء تلك الشريحة من التقييمات بنظرة واحدة. **الملاحظات مشتركة عبر منظمتك بالكاملة**؛ الجميع الذين لديهم `dashboards:read` يرى نفس المجموعة. -تثبت كل لوحة: +تثبت كل ملاحظة: -- **التصافي**: نفس الضوابط كصفحة الجلسات: البيئة والحالة والوكيل ونافذة زمنية متدرجة وتصافي نطاق النقاط (`key:min..max`). -- **تشكيل عرض**: مفاتيح النقاط التي تميز، أعتاب صحة أخضر/كهرماني/أحمر، أي لوحات تعرض، وما إذا كنت تطوي إلى أحدث تقييم لكل جلسة. +- **المرشحات**: نفس عناصر التحكم كصفحة الجلسات: البيئة والحالة والوكيل نافذة زمنية متدحرجة ومرشحات نطاق النقاط (`key:min..max`). +- **تكوين العرض**: مفاتيح النقاط المميزة وعتبات الصحة الخضراء/برتقالية/الحمراء والألواح المراد عرضها وما إذا كان يجب الطي لآخر تقييم لكل جلسة. -يعرض كل بطاقة عدد الجلسات المطابقة، تفصيل done/error/timeout، متوسط كل نقطة مميزة، وخط اتجاه صغير. فتح لوحة يعرض اللوحات بحجم كامل؛ **تفتح في جلسات** توديعك في صفحة الجلسات المصفاة مسبقاً لتلك الشريحة تماماً. تُحسب المقاييس على جانب الخادم على المجموعة المطابقة بأكملها (عبر `GET /evaluations/aggregate`)، لذا تكون الأرقام دقيقة بدلاً من أخذ عينات. +تعرض كل بطاقة عدد الجلسات المطابقة وتفصيل done/error/timeout ومتوسط كل نقطة مميزة وخط اتجاه صغير. يؤدي فتح ملاحظة إلى عرض الألواح بحجم كامل؛ **افتح في الجلسات** يأخذك إلى صفحة الجلسات مع تصفية دقيقة لتلك الشريحة بالضبط. يتم حساب المقاييس من جانب الخادم على مجموعة المطابقة الكاملة (عبر `GET /evaluations/aggregate`)، لذا الأرقام دقيقة وليست مأخوذة عينات. -![لوحة صحة تقييم مع متوسط أشرطة نقاط لكل بعد مقيّم، تفصيل أداة ok-vs-error، أفضل الأدوات واتجاه أحداث لكل ساعة](/agenteye/images/dashboard-quality.png) +![ملاحظة صحة التقييم مع أشرطة النقاط المتوسطة لكل بعد المقيّم وتفصيل الأداة موافق مقابل الخطأ والأدوات العليا واتجاه الأحداث لكل ساعة](/agenteye/images/dashboard-quality.png) -**الصلاحيات:** العرض يحتاج كلاً من `dashboards:read` و `evaluations:read`؛ الإنشاء والتعديل يحتاج `dashboards:write`؛ الحذف يحتاج `dashboards:delete`. يستقبل المسؤول التمهيدي جميع هذه تلقائياً. +**الأذونات:** العرض يحتاج إلى كل من `dashboards:read` و `evaluations:read`؛ الإنشاء والتحرير يحتاج `dashboards:write`؛ الحذف يحتاج `dashboards:delete`. يستقبل المسؤول التمهيدي كل هذه تلقائياً. --- -## استكشاف الأخطاء والإصلاح +## استكشاف الأخطاء -**توجد جلسات لكن لا تُنشأ تقييمات.** تأكد من تعيين `EVALUATOR_ENDPOINT` على عملية الخادم، وأن الخادم والمُقيّم يتشاركان نفس قيمة `EVALUATOR_TOKEN`، وأن نقطة المسار `/health` الخاصة بالمُقيّم قابلة للوصول من الخادم. مع عدم تعيين `EVALUATOR_ENDPOINT` خط الأنابيب عديم التأثير. +**جلسات موجودة لكن لا توجد تقييمات منشأة.** تأكد من تعيين `EVALUATOR_ENDPOINT` على عملية الخادم وأن الخادم والمقيّم يشتركان في نفس قيمة `EVALUATOR_TOKEN` وأن نقطة نهاية `/health` للمقيّم يمكن الوصول إليها من الخادم. مع عدم تعيين `EVALUATOR_ENDPOINT` يكون المسار عدم تشغيلي. -**تقييمات قيد الطيران تتراكم.** استعلم `GET /evaluation-jobs` لترى طابور الطيران. فتش `attempt_count` و `next_attempt_at` و `last_error` على كل صف. الأسباب الشائعة: خدمة المُقيّم غير قابلة للوصول أو تُرجع 5xx (أعيدت محاولتها مع تراجع)، `EVALUATOR_TOKEN` خاطئ (401 نهائي)، أو مُقيّم غير متزامن يُرجع `pending` إلى الأبد (انظر أدناه). +**التقييمات أثناء التنفيذ تتراكم.** استعلم `GET /evaluation-jobs` لرؤية قائمة الانتظار. افحص `attempt_count` و `next_attempt_at` و `last_error` على كل صف. الأسباب الشائعة: خدمة المقيّم غير قابلة للوصول أو إرجاع 5xx (إعادة محاولة مع تراجع)، `EVALUATOR_TOKEN` خاطئ (401 نهائي)، أو مقيّم غير متزامن يعيد `pending` إلى الأبد (انظر أدناه). -**اكتملت الجلسات لكن لا تقييم نهائي.** استعلم `GET /evaluation-jobs?status=polling`؛ النتيجة قد لا تزال قيد الطيران. إذا علقت وظيفة في `pending`، يواجه الخادم مشكلة في الوصول إلى المُقيّم؛ تحقق من أن المُقيّم مرفوع وأن `EVALUATOR_TOKEN` يطابق. +**جلسات مكتملة لكن لا توجد تقييمات نهائية.** استعلم `GET /evaluation-jobs?status=polling`؛ قد تكون النتيجة لا تزال قيد التنفيذ. إذا كانت وظيفة عالقة في `pending`، يواجه الخادم مشكلة في الوصول إلى المقيّم؛ تحقق من أن المقيّم يعمل وأن `EVALUATOR_TOKEN` يطابق. -**`HTTP 401 from evaluator: invalid bearer token`.** `EVALUATOR_TOKEN` على الخادم لا يطابق القيمة التي عُدت خدمة المُقيّم معها. يجب أن تكون متطابقة. +**`HTTP 401 من المقيّم: رمز حامل غير صالح`.** لا يطابق `EVALUATOR_TOKEN` على الخادم القيمة التي تم تكوين خدمة المقيّم بها. يجب أن تكون متطابقة. -**مُقيّم غير متزامن يُرجع `pending` للأبد.** يستقصي الخادم `GET /evaluate/{job_id}` حتى يُرجع المُقيّم `done` أو `error`، أو حتى تنقضي `EVALUATOR_MAX_POLL_DURATION_SECS` (افتراضي 1 ساعة). بعد الحد يُسجل التقييم كـ `timeout` ويُزال من طابور الطيران. ارفع `EVALUATOR_MAX_POLL_DURATION_SECS` إذا كان مُقيّمك بشكل شرعي يحتاج أكثر من الافتراضي. +**مقيّم غير متزامن يعيد `pending` إلى الأبد.** يستطلع الخادم `GET /evaluate/{job_id}` حتى يعيد المقيّم `done` أو `error`، أو حتى ينقضي حد `EVALUATOR_MAX_POLL_DURATION_SECS` (افتراضي 1 ساعة). بعد الحد يتم تسجيل التقييم كـ `timeout` وإزالته من قائمة الانتظار أثناء التنفيذ. ارفع `EVALUATOR_MAX_POLL_DURATION_SECS` إذا كان المقيّم بحاجة بشكل فعلي إلى وقت أطول من الافتراضي. --- ## الخطوات التالية -- [مهارة وكيل المُقيّم](/ar/agenteye/evaluator-skill): اطلب من وكيل ترميز أن يصمم أبعادك ضد جلسات حقيقية وينشئ هذه الخدمة لك. -- [Python SDK](/ar/agenteye/python-sdk): أصدر أحداث `agent_end` التي تُثير التسجيل. -- [مفاتيح API](/ar/agenteye/api-keys): صلاحيات `evaluations:read` و `evaluations:trigger`. -- [عمليات التدقيق](/ar/agenteye/audits): ميزة جودة مؤتمتة أخرى من Observability، للمراجعة المستندة إلى السياسة. \ No newline at end of file +- [مهارة الوكيل المقيّم](/ar/agenteye/evaluator-skill): اجعل وكيل الترميز يصمم أبعادك ضد جلسات حقيقية وينشئ هذه الخدمة لك. +- [Python SDK](/ar/agenteye/python-sdk): أرسل أحداث `agent_end` التي تشغّل التسجيل. +- [مفاتيح API](/ar/agenteye/api-keys): أذونات `evaluations:read` و `evaluations:trigger`. +- [التدقيقات](/ar/agenteye/audits): ميزة الجودة الآلية الأخرى بـ Observability، للمراجعة القائمة على السياسة. \ No newline at end of file diff --git a/docs/ar/agenteye/evaluations.mdx b/docs/ar/agenteye/evaluations.mdx index 9f292548..be94bdb0 100644 --- a/docs/ar/agenteye/evaluations.mdx +++ b/docs/ar/agenteye/evaluations.mdx @@ -1,51 +1,51 @@ --- title: "التقييمات" -description: "مشاكل الجودة تجدك الآن، بدلاً من سماعك عنها في شكوى من مستخدم." +description: "مشاكل الجودة تجدك الآن، بدلاً من أن تسمع عنها من شكوى العميل." --- -مشاكل الجودة تجدك الآن، بدلاً من سماعك عنها في شكوى من مستخدم. اربط خدمة التسجيل الخاصة بك مرة واحدة و Failproof AI Observability يقيّم كل عملية منتهية تلقائياً، بحيث ينخفاض في الفائدة أو ارتفاع حاد في الهلوسات يظهر من تلقاء نفسه، قبل أن يشعر به العميل. +مشاكل الجودة تجدك الآن، بدلاً من أن تسمع عنها من شكوى العميل. اربط خدمة التسجيل الخاصة بك مرة واحدة وتقييمات Failproof AI Observability كل عملية منتهية تلقائياً، لذا فإن انخفاض الفائدة أو ارتفاع الهلوسات يظهر من تلقاء نفسه، قبل أن يشعر به العميل. -![شبكة الجلسات مع عمود النقاط: كل عملية تحمل شارة حالة التقييم وشارات ملونة بالرمز (أحمر وأصفر وأخضر) للفائدة والدقة وكفاءة الأداة](/agenteye/images/sessions-list.png) +![شبكة الجلسات مع عمود النقاط: كل عملية تحمل شارة حالة التقييم وشارات ملونة بالأحمر والأصفر والأخضر للفائدة والدقة وكفاءة الأدوات](/agenteye/images/sessions-list.png) -*كل عملية في شبكة الجلسات تحمل نقاطها؛ الشارات الحمراء والصفراء والخضراء تجعل العمليات الضعيفة تبرز دون فتح نص واحد.* +*كل عملية على شبكة الجلسات تحمل نقاطها؛ الشارات الحمراء والبرتقالية والخضراء تجعل العمليات الضعيفة تبرز دون فتح نص واحد.* -## توقف عن أخذ عينات من العمليات يدويّاً +## توقف عن فحص العمليات يدويًا -كنت تفحص عدداً قليلاً من العمليات وتأمل أن تكون البقية بخير. الآن كل جلسة مكتملة يتم تقييمها اللحظة التي تنتهي، على الأبعاد التي تهمك: الفائدة وكفاءة الأداة والدقة والأمان وأي معيار جودة لديك. أنت تعرّف مفاتيح النقاط؛ Failproof AI Observability يخزن وينظر ويعرض أي شيء يرسله المقيّم الخاص بك. لا عملية تتسلل بدون نقاط، وتتوقف عن معرفة الانحدار من تذكرة دعم. +اعتدت على فحص عدد قليل من العمليات وتأمل أن تكون الباقي بخير. الآن كل جلسة منتهية يتم تسجيلها في اللحظة التي تنتهي فيها، على الأبعاد التي تهمك: الفائدة، كفاءة الأدوات، الدقة، الأمان، كل ما يعتبر معيار جودتك. أنت تحدد مفاتيح النقاط؛ Failproof AI Observability تخزن وتتابع وتعرض أي شيء يرسله المقيّم. لا توجد عملية تمر دون تقييم، وتتوقف عن معرفة الانحدار من تذكرة الدعم. -النقاط تظهر على شبكة الجلسات في **`//sessions`** (الشريط الجانبي → *مراقبة* → *جلسات*)، مجموعة شارات واحدة لكل صف. تريد فقط العمليات التي أخفقت؟ صفّي الشبكة حسب نطاق النقاط، على سبيل المثال الفائدة أقل من 0.5، واسحب العمليات التي تستحق القراءة بالضبط. يتطلب عرض النقاط صلاحية `evaluations:read`. +النقاط تظهر على شبكة الجلسات في **`//sessions`** (الشريط الجانبي → *observe* → *sessions*)، مجموعة شارات واحدة لكل صف. هل تريد فقط العمليات التي لم ترتقِ للمستوى؟ رشح الشبكة حسب نطاق النقاط، على سبيل المثال الفائدة أقل من 0.5، واحصل على العمليات التي تستحق القراءة فقط. عرض النقاط يتطلب صلاحية `evaluations:read`. -## انظر لماذا سجلت العملية منخفضة +## انظر لماذا حصلت العملية على نقاط منخفضة -الرقم يخبرك أن العملية كانت ضعيفة؛ صفحة الجلسة تخبرك لماذا. افتح أي عملية والسكة الجانبية اليمنى تبدأ بملخص العنوان الرئيسي، ثم تعرض شريطاً لكل بُعد مع المنطق الخاص بمقيّمك تحت كل واحد، حتى تنتقل من "هذا سجل 0.4 على الدقة" إلى الادعاء الدقيق الذي أخطأ فيه في ثوانٍ. +الرقم يخبرك أن العملية كانت ضعيفة؛ صفحة الجلسة تخبرك السبب. افتح أي عملية والسكة اليمنى تبدأ بملخص العنوان، ثم تعرض شريط لكل بُعد مع استدلالات المقيّم الخاصة به تحت كل واحد، لذا تنتقل من "هذه حصلت على 0.4 في الدقة" إلى الادعاء الدقيق الذي أخطأت فيه في ثوانٍ. -![السكة الجانبية اليمنى للجلسة: ملخص التقييم في الأعلى، ثم أشرطة النقاط لكل بُعد مع سطر من المنطق، بجانب خط الأحداث الكامل](/agenteye/images/session-detail.png) +![السكة اليمنى للجلسة: ملخص التقييم في الأعلى، ثم أشرطة النقاط حسب البُعد كل منها مع سطر من الاستدلال، بجانب الخط الزمني الكامل للأحداث](/agenteye/images/session-detail.png) -*عرض تفاصيل الجلسة: الملخص وأشرطة النقاط لكل بُعد والمنطق خلف كل نقاط، بجانب خط أحداث العملية.* +*عرض تفاصيل الجلسة: الملخص، أشرطة النقاط حسب البُعد، والمنطق خلف كل نقاط، بجانب الخط الزمني لعملية التشغيل.* -هل شحنت مقيّماً أحد؟ أم تبحث عن عملية توقفت قبل أن يمكن تقييمها؟ زر **إعادة تقييم** (تم قيده بـ `evaluations:trigger`) يعيد تقييم الجلسة في مكانها وإضافة النتيجة الطازجة إلى الخط الزمني، بحيث تبقى النقاط السابقة مرئية كسجل. ستجده في **`//sessions/`**. +هل طرحت مقيّماً أفضل، أو تنظر إلى عملية توقفت قبل أن يتم تقييمها؟ زر **re-evaluate** (محدود بـ `evaluations:trigger`) يعيد تقييم الجلسة في المكان ويضيف النتيجة الجديدة إلى خط زمنها، لذا النقاط السابقة تبقى مرئية كسجل. ستجده في **`//sessions/`**. ## راقب اتجاه الجودة عبر الأسطول -عملية واحدة بنقاط منخفضة هي ضوضاء؛ مجموعة كاملة تنزلق هي إشارة. لوحات المعلومات المحفوظة تحول نقاطك إلى اتجاه يمكنك مراقبته بنظرة واحدة: متوسط الفائدة هذا الأسبوع مقابل الأسبوع الماضي، لكل وكيل، لكل بيئة. +عملية واحدة تحصل على نقاط منخفضة هي ضجيج؛ مجموعة كاملة تنزلق هي إشارة. لوحات المعلومات المحفوظة تحول نقاطك إلى اتجاه يمكنك مراقبته في لمحة: متوسط الفائدة هذا الأسبوع مقابل الأسبوع الماضي، لكل عامل، لكل بيئة. -![لوحة معلومات الجودة: أشرطة متوسط النقاط لكل بُعد مقيّم بجانب اتجاه عبر الزمن](/agenteye/images/dashboard-quality.png) +![لوحة معلومات الجودة: أشرطة متوسط النقاط لكل بُعد مقيّم بجانب اتجاه عبر الوقت](/agenteye/images/dashboard-quality.png) -*لوحة معلومات جودة محفوظة تعطي اتجاهاً لمفاتيح النقاط التي تعرضها، بحيث يكون الانجراف البطيء واضحاً قبل وقت طويل من أن يصبح حادثة.* +*لوحة معلومات جودة محفوظة تتابع مفاتيح النقاط التي تميزها، لذا الانجراف البطيء يصبح واضحاً قبل وقت طويل من أن يصبح حادثة.* -لوحات المعلومات تعيش في **`//dashboards`** (الشريط الجانبي → *تحليل* → *لوحات المعلومات*)، يتم مشاركتها عبر المنظمة بأكملها، وكل بطاقة تجمع الجلسات المطابقة: كم عدد، ومتوسط كل نقطة معروضة، والخط الزمني للاتجاه. "فتح في الجلسات" يسقطك مباشرة في العمليات المصفاة مسبقاً خلف أي رقم. يتطلب العرض `dashboards:read` و `evaluations:read`. +لوحات المعلومات تعيش في **`//dashboards`** (الشريط الجانبي → *analyze* → *dashboards*)، تُشاركها عبر مؤسستك بأكملها، وكل بطاقة تجمع الجلسات المطابقة: كم عدد، متوسط كل نقاط مميزة، وسطر اتجاه صغير. "Open in sessions" يأخذك مباشرة إلى العمليات المرشحة مسبقاً خلف أي رقم. العرض يتطلب `dashboards:read` بالإضافة إلى `evaluations:read`. -## اربط مقيّماً مرة واحدة +## ربط المقيّم مرة واحدة -التسجيل اختياري ويبقى معطلاً تماماً حتى تشير Failproof AI Observability إلى مسجل. تقيم خدمة HTTP صغيرة واحدة (Observability تشحن مرجعاً عاملاً يمكنك نسخه)، وتعيين قيمتين على الخادم الخاص بك، وكل عملية من ذلك الحين فصاعداً يتم تقييمها لك. الإرشادات الكاملة والعقد التسجيل و SDK يعيشان في الدليل العميق. +التسجيل اختياري وبقي مغلقاً تماماً حتى تشير Failproof AI Observability إلى مسجل نقاط. أنت تشغل خدمة HTTP صغيرة واحدة (Observability تشحن مرجعاً يعمل يمكنك نسخه)، تعيّن قيمتين على خادمك، وكل عملية من بعدها يتم تسجيلها لك. الشرح الكامل والعقد المسجل والمكتبة البرمجية تعيش في الدليل المتقدم. -لا تعرف أي الأبعاد تستحق التسجيل في البداية؟ [مهارة وكيل المقيّم](/ar/agenteye/evaluator-skill) لديها وكيل الترميز الخاص بك ينقب عن ذلك ضد جلساتك الخاصة، ثم يبني وينشر الخدمة. +غير متأكد من أي أبعاد تستحق التسجيل في المقام الأول؟ [مهارة عامل التقييم](/ar/agenteye/evaluator-skill) تقوم بذلك مقابل جلساتك الخاصة، ثم تبني وتطبق الخدمة. ## ذات صلة -- [مجموعة التقييم](/ar/agenteye/evaluation-suite): اربط مقيّمك وعقد التسجيل و SDK. -- [مهارة وكيل المقيّم](/ar/agenteye/evaluator-skill): دع وكيل الترميز يختار أبعاد النقاط الخاصة بك ويبني المقيّم. -- [الجلسات](/ar/agenteye/sessions): شبكة تشغيل تظهر بها النقاط. -- [لوحات المعلومات](/ar/agenteye/dashboards): احفظ وشارك اتجاهات الجودة عبر المنظمة. -- [عمليات التدقيق](/ar/agenteye/audits): ميزة الجودة التلقائية الأخرى لـ Observability، للتحقيقات عبر الجلسات. \ No newline at end of file +- [مجموعة التقييم](/ar/agenteye/evaluation-suite): ربط المقيّم، العقد المسجل، والمكتبة البرمجية. +- [مهارة عامل التقييم](/ar/agenteye/evaluator-skill): اترك عامل الترميز يختار أبعاد نقاطك وينشئ المقيّم. +- [الجلسات](/ar/agenteye/sessions): شبكة العمليات حيث تظهر النقاط. +- [لوحات المعلومات](/ar/agenteye/dashboards): احفظ وشارك اتجاهات الجودة عبر مؤسستك. +- [عمليات التدقيق](/ar/agenteye/audits): ميزة الجودة الآلية الأخرى في Observability، للتحقيقات عبر الجلسات. \ No newline at end of file diff --git a/docs/ar/agenteye/evaluator-skill.mdx b/docs/ar/agenteye/evaluator-skill.mdx index 12e610be..b480e90a 100644 --- a/docs/ar/agenteye/evaluator-skill.mdx +++ b/docs/ar/agenteye/evaluator-skill.mdx @@ -1,62 +1,61 @@ --- --- -title: "مهارة وكيل Failproof AI Observability Evaluator" -description: "انتقل من \"أعتقد أن وكيلنا سيء أحياناً\" إلى خدمة تقييم مُنتشرة، مع قيام وكيل البرمجة بكل من القرار والبناء." +title: "مهارة وكيل تقييم قابلية الملاحظة في Failproof AI" +description: "انتقل من \"أعتقد أن وكيلنا سيء أحياناً\" إلى خدمة تصنيف منتشرة، حيث يقوم وكيل الترميز الخاص بك بكل من اتخاذ القرار والبناء." --- +انتقل من *"أعتقد أن وكيلنا سيء أحياناً"* إلى خدمة تصنيف منتشرة، حيث يقوم وكيل الترميز الخاص بك بكل من اتخاذ القرار والبناء. **مهارة وكيل تقييم قابلية الملاحظة في Failproof AI** (`agenteye-evaluator`) هي *مهارة وكيل*: مجلد صغير من التعليمات يحمله وكيل ترميز مثل Claude Code أو Codex عند الحاجة. تعلّم الوكيل تحديد أي أبعاد جودة تستحق التتبع لـ *وكيلك*، ثم كتابة واختبار ونشر [خدمة التقييم](/ar/agenteye/evaluation-suite) التي تصنفها. -انتقل من *"أعتقد أن وكيلنا سيء أحياناً"* إلى خدمة تقييم مُنتشرة، مع قيام وكيل البرمجة بكل من القرار والبناء. **مهارة Failproof AI Observability evaluator** (`agenteye-evaluator`) هي *مهارة وكيل*: مجلد صغير من التعليمات يحمّله وكيل برمجة مثل Claude Code أو Codex عند الحاجة. تعلّم الوكيل كيفية تحديد أي أبعاد جودة تستحق التتبع لـ *وكيلك*، ثم كتابة واختبار ونشر [خدمة المُقيّم](/ar/agenteye/evaluation-suite) التي تقيّمها. - -إنها **ليست** محدد درجات مستضاف، ولا سجل تحمّل عليه، ولا نظام إضافات. يبقى المُقيّم خدمة HTTP خاصة بك على البنية الأساسية الخاصة بك، بالضبط كما هو موضح في دليل [مجموعة التقييم](/ar/agenteye/evaluation-suite). تعلّم المهارة وكيلك فقط ليبنيها بشكل جيد، لذلك كل ما تفعله يمكنك أن تفعله بنفسك بكتابة الكود ذاته. +**ليس** محقق مستضاف أو سجل تحمّل إليه أو نظام إضافات. يبقى المقيّم الخاص بك خدمة HTTP خاصة بك على بنيتك التحتية الخاصة، تماماً كما هو موصوف في دليل [جناح التقييم](/ar/agenteye/evaluation-suite). تعلم المهارة وكيلك فقط لبناؤها بشكل جيد، لذا كل ما تفعله، يمكنك فعله بنفسك بكتابة نفس الكود. --- -## الجزء الصعب هو تحديد ما يجب تقييمه +## الجزء الصعب هو تقرير ما يتم تصنيفه -سطح SDK صغير — ديكوريتور ونموذجان — والوكيل يمكنه كتابة ذلك من [العقد](/ar/agenteye/evaluation-suite#http-contract) وحده. هذا ليس حيث يفشل المُقيّمون. يفشلون لأنهم يقيّمون الشيء الخطأ، والمُقيّم الذي يقيّم الشيء الخطأ أسوأ من لا شيء: فهو ينتج لوحة معلومات يتعلم الجميع تجاهلها. +سطح SDK صغير — مزخرف واثنان من النماذج — ويمكن لوكيل كتابة ذلك من [العقد](/ar/agenteye/evaluation-suite#http-contract) وحده. هذا ليس حيث يفشل المقيّمون. يفشلون لأنهم يصنفون الشيء الخطأ، والمقيّم الذي يصنف الشيء الخطأ أسوأ من لا شيء: ينتج لوحة تحكم يتعلم الجميع تجاهلها. -لذلك معظم المهارة هي الجزء قبل وجود أي كود. يحتوي على الوكيل الذي يقابلك (*"اصف تشغيلاً سار بشكل جيد؛ الآن واحداً سار بشكل سيء"*) ثم يسحب جلساتك الفعلية من خلال [`agenteye` CLI](/ar/agenteye/cli) ويقرأها من البداية إلى النهاية. هذان النصفان عادة ما يختلفان، والفجوة هي النقطة: ما تنوي قياسه مقابل ما يمكن لنصوصك فعلاً دعمه. يبقى البعد فقط إذا كان **قابلاً للحساب** من الأحداث و**تمييزياً** — إذا حقق 0.9 على جلستك الجيدة والسيئة معاً، فهو لا يعلم شيئاً ويتم حذفه. +لذا معظم المهارة هي الجزء قبل أن يكون أي كود موجوداً. لديها الوكيل يجري مقابلة معك (*"صِف عملية سارت بشكل جيد؛ الآن واحدة سارت بشكل سيء"*)، ثم يسحب جلساتك الحقيقية من خلال [`agenteye` CLI](/ar/agenteye/cli) ويقرأها من النهاية إلى النهاية. يختلف النصفان عادة، والفجوة هي النقطة: ما تقصد قياسه مقابل ما يمكن لنصوصك فعلياً دعمه. يبقى البعد فقط إذا كان **قابلاً للحساب** من الأحداث و**مميزاً** — إذا حصل على 0.9 على عمليتك الجيدة وعمليتك السيئة، فهو لا يعلم شيئاً ويتم حذفه. -ما يعود عليك هو اقتراح 2-4 أبعاد مع التفكير المرفق، لتصديق عليها قبل كتابة سطر واحد. +ما يعود عليه هو اقتراح بـ 2-4 أبعاد مع التفكير المرفق، لتوقعك عليها قبل كتابة سطر واحد. ```mermaid flowchart TD - YOU["أنت: 'أريد تقييمات لـ support bot الخاص بي'"] --> AGENT["وكيل البرمجة (Claude Code / Codex)
يحمّل مهارة agenteye-evaluator"] - AGENT -->|"مقابلة: كيف يبدو الجيد مقابل السيء؟"| YOU - AGENT -->|"agenteye --json sessions / events"| DATA["جلساتك الفعلية
ما يحدث فعلاً"] - DATA --> DIMS["2-4 أبعاد، أنت توافق"] - DIMS --> SVC["خدمة المُقيّم الخاصة بك
agenteye-evaluator SDK"] - SVC --> SCORES["الدرجات تهبط في لوحة المعلومات
و agenteye evals"] + YOU["أنت: 'أريد تقييمات لروبوت الدعم الخاص بي'"] --> AGENT["وكيل ترميز (Claude Code / Codex)
يحمل مهارة agenteye-evaluator"] + AGENT -->|"المقابلة: كيف يبدو الجيد مقابل السيء؟"| YOU + AGENT -->|"agenteye --json sessions / events"| DATA["جلساتك الحقيقية
ما يحدث فعلاً"] + DATA --> DIMS["2-4 أبعاد، توقيعك"] + DIMS --> SVC["خدمة المقيّم الخاصة بك
agenteye-evaluator SDK"] + SVC --> SCORES["النقاط تصل إلى لوحة التحكم
وتقييمات agenteye"] ``` --- -## كيفية ارتباطها بأجزاء التقييم الأخرى +## كيف يرتبط بأجزاء التقييم الأخرى -أربعة مستندات تغطي التقييم، وتسلمها لبعضها البعض بالترتيب: +تغطي أربع وثائق التصنيف، وتسلم بعضها إلى بعض بالترتيب: | الصفحة | ما هي | استخدمها عندما | |---|---|---| -| **[التقييمات](/ar/agenteye/evaluations)** | الميزة: درجات على شبكة الجلسات، لوحات المعلومات، إعادة تقييم | تريد معرفة ما يحصل عليه التقييم التلقائي | -| **[مجموعة التقييم](/ar/agenteye/evaluation-suite)** | عقد HTTP، SDK، متغيرات بيئة الخادم | تقوم بتطبيق أو تصحيح المُقيّم بنفسك | -| **مهارة المُقيّم** (هذا المستند) | باب باللغة الطبيعية لتصميم *وبناء* المقيّم | تريد الانتقال من "أريد تقييمات" إلى خدمة قيد التشغيل | -| **[مهارة CLI](/ar/agenteye/cli-skill)** | باب باللغة الطبيعية على `agenteye` CLI | تريد *قراءة* الدرجات التي لديك بالفعل | -| **[مهارة Python SDK](/ar/agenteye/python-sdk-skill)** | باب باللغة الطبيعية على جهاز وكيلك | وكيلك لا ينبت جلسات حتى الآن — لا يوجد شيء لتقييمه | +| **[التقييمات](/ar/agenteye/evaluations)** | الميزة: نقاط على شبكة الجلسات، لوحات التحكم، إعادة تقييم | تريد معرفة ما يحصل عليه التصنيف التلقائي | +| **[جناح التقييم](/ar/agenteye/evaluation-suite)** | عقد HTTP، SDK، متغيرات بيئة الخادم | أنت تطبق أو تصحح المقيّم بنفسك | +| **مهارة المقيّم** (هذه الوثيقة) | باب أمامي بلغة طبيعية لتصميم *وبناء* المصنف | تريد الانتقال من "أريد تقييمات" إلى خدمة تعمل | +| **[مهارة CLI](/ar/agenteye/cli-skill)** | باب أمامي بلغة طبيعية على `agenteye` CLI | تريد *قراءة* النقاط التي لديك بالفعل | +| **[مهارة Python SDK](/ar/agenteye/python-sdk-skill)** | باب أمامي بلغة طبيعية على توصيل وكيلك | وكيلك لا يصدر جلسات حتى الآن — لا يوجد شيء لتصنيفه | -### مقابل مهارة CLI: البناء مقابل القراءة +### مقابل مهارة CLI: بناء مقابل قراءة -المهارتان متعمداً غير متداخلتان، والتثبيت كليهما هو الإعداد الطبيعي — يختار الوكيل بينهما بناءً على ما تطلبه: +المهارتان متعارضتان بقصد، والتثبيت لكليهما هو الإعداد الطبيعي — يختار الوكيل بينهما بناءً على ما تطلبه: -- **`agenteye-evaluator`** (هذا المستند) يبني الشيء الذي *ينتج* الدرجات. تنتهي وظيفته عندما تهبط الدرجات للمرة الأولى. -- **[`agenteye-cli`](/ar/agenteye/cli-skill)** يقرأ درجات موجودة بالفعل (`agenteye evals`). *"هل انخفضت الجودة هذا الأسبوع؟"* هو سؤاله، وليس سؤال هذه المهارة. +- **`agenteye-evaluator`** (هذه الوثيقة) بناء الشيء الذي *ينتج* النقاط. تنتهي وظيفتها عندما تصل النقاط للمرة الأولى. +- **[`agenteye-cli`](/ar/agenteye/cli-skill)** قراءة النقاط الموجودة بالفعل (`agenteye evals`). *"هل انخفضت الجودة هذا الأسبوع؟"* هي سؤالها، ليس سؤال هذه المهارة. --- ## المتطلبات الأساسية -1. **`agenteye` CLI مثبت وقيد التسجيل** (`pipx install agenteye`، ثم `agenteye login`). تعتمد المهارة عليها مرتين: لسحب الجلسات الفعلية التي تصممها، والتأكيد من أن درجاتك هبطت في النهاية. يحتاج تسجيلك إلى `events:read`, بالإضافة إلى `evaluations:read` للتحقق النهائي. كما هو الحال مع مهارة CLI، **لا يمكنها** إكمال تسجيل دخول الرمز أحادي الاستخدام عبر البريد الإلكتروني نيابة عنك. -2. **مكان للمُقيّم ليعيش فيه.** يتم بناؤه في صورة ويعمل كخدمة طويلة الأجل، لذا فهو يحتاج إلى ريبو حقيقي، وليس ملف مؤقت. غالباً ما تعيش المُقيّمون في ريبو خاصة بهم، منفصلة عن الوكيل الذي يتم تقييمه — تبحث المهارة عن ريبو موجود وتطلب قبل إنشاء ريبو جديد. -3. **عجلة SDK `agenteye-evaluator`** — اقرأ القسم التالي قبل أن يبدأ وكيلك بكتابة أوامر `pip`. +1. **`agenteye` CLI مثبتة وقيد التسجيل** (`pipx install agenteye`، ثم `agenteye login`). تعتمد المهارة عليها مرتين: لسحب الجلسات الحقيقية التي تصممها، وللتأكد من وصول نقاطك في النهاية. يحتاج تسجيلك إلى `events:read`، بالإضافة إلى `evaluations:read` لهذا الفحص الأخير. كما هو الحال مع مهارة CLI، **لا يمكنها** إكمال تسجيل الدخول بكود لمرة واحدة المُرسل بالبريد الإلكتروني لك. +2. **مكان لعيش المقيّم.** يتم بناؤه في صورة ويعمل كخدمة طويلة الأمد، لذا يحتاج إلى مستودع حقيقي، وليس ملف مؤقت. غالباً ما يعيش المقيّمون في مستودعهم الخاص، منفصل عن الوكيل الذي يتم تصنيفه — تبحث المهارة عن واحد موجود وتسأل قبل بناء واحد جديد. +3. **عجلة `agenteye-evaluator` SDK** — اقرأ القسم التالي قبل أن يبدأ وكيلك بكتابة أوامر `pip`. --- @@ -66,11 +65,11 @@ flowchart TD **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -المستودع عام والمهارة لا تحتاج إلى بيانات اعتماد خاصة بها — فهي فقط تشغيل `agenteye` CLI مع جلسة *أنت* قيد التسجيل، وتكتب كوداً في *ريبوك* الخاص. لاحظ أنها تُشحن كمجلد خاص بها وهي **ليست** داخل حزمة `pipx install agenteye`، لذا لا تبحث عنها هناك. +المستودع عام والمهارة لا تحتاج إلى بيانات اعتماد خاصة بها — إنها فقط تقود `agenteye` CLI مع الجلسة *التي سجلت فيها*، وتكتب الكود في *مستودعك*. لاحظ أنها تُشحن كمجلد خاص بها و**ليست** داخل حزمة `pipx install agenteye`، لذا لا تبحث عنها هناك. ## تثبيت المهارة -أسرع طريق هي CLI [`skills`](https://skills.sh)، الذي يحضر المجلد وينزله حيث يبحث وكيلك: +أسرع طريق هي [`skills`](https://skills.sh) CLI، التي تجلب المجلد وتضعه حيث ينظر وكيلك: ```bash # Claude Code، هذا المشروع فقط @@ -83,18 +82,18 @@ npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g - npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -ثم أدره مثل أي مهارة أخرى: +ثم أدره كأي مهارة أخرى: ```bash npx skills list -a claude-code # ما هو مثبت -npx skills update agenteye-evaluator # اسحب أحدث إصدار +npx skills update agenteye-evaluator # اسحب أحدث نسخة npx skills remove agenteye-evaluator # أزله ``` -تفضل التثبيت يدوياً؟ مهارة وكيل هي مجرد مجلد يحتوي على `SKILL.md` (بالإضافة إلى مراجع اختيارية)، لذا نسخه يعمل أيضاً: +تفضل التثبيت اليدوي؟ مهارة الوكيل هي مجرد مجلد يحتوي على `SKILL.md` (بالإضافة إلى مراجع اختيارية)، لذا نسخه يعمل أيضاً: -- **Claude Code**: ضع مجلد `agenteye-evaluator/` في `~/.claude/skills/` (كل مشروع) أو `/.claude/skills/` (هذا الريبو فقط). Claude Code يكتشفه تلقائياً — تحقق مع قائمة `/skills`، أو اطلب فقط تقييمات. -- **Codex (OpenAI)**: يقرأ Codex نفس `SKILL.md`. يعيّن `agents/openai.yaml` المرفق `allow_implicit_invocation: true`، لذا يختار Codex تلقائياً المهارة عندما تطابق المهمة؛ وإلا استدعِها بشكل صريح كـ `$agenteye-evaluator`. +- **Claude Code**: ضع مجلد `agenteye-evaluator/` في `~/.claude/skills/` (كل مشروع) أو `/.claude/skills/` (هذا المستودع فقط). Claude Code يكتشفه تلقائياً — تحقق مع قائمة `/skills`، أو ببساطة اطلب تقييمات. +- **Codex (OpenAI)**: يقرأ Codex نفس `SKILL.md`. ملف `agents/openai.yaml` المجموع يعيّن `allow_implicit_invocation: true`، لذا يختار Codex المهارة تلقائياً عند تطابق المهمة؛ وإلا استدعِها صراحة كـ `$agenteye-evaluator`. --- @@ -102,67 +101,67 @@ npx skills remove agenteye-evaluator # أزله > **تحذير:** اقرأ هذا قبل السماح لوكيل بتثبيت SDK. -المهارة عامة؛ SDK الذي تقوده ليس كذلك. `agenteye-evaluator` يُشحن فقط كقطعة إصدار خاصة، وخلافاً لـ `agenteye`، الاسم **غير مطالب به على PyPI العام** — لذا `pip install agenteye-evaluator` بسيط قد يسحب حزمة شخص غريب إلى الخدمة التي تقرأ نصوصك الإنتاجية. هذه مشكلة سلسلة التوريد، وليست خطأ إملائي. +المهارة عامة؛ SDK التي تقودها ليست. `agenteye-evaluator` تُشحن فقط كقطعة إصدار خاصة، وبخلاف `agenteye`، الاسم **غير مطالب عليه على PyPI العام** — لذا يمكن لـ `pip install agenteye-evaluator` المباشر أن يسحب حزمة من غريب إلى الخدمة التي تقرأ نصوصك الإنتاجية. هذه مشكلة سلسلة التوريد، وليست خطأ مطبعي. -تعرف المهارة هذا وتعمل لأسفل سلم التثبيت بدلاً من ذلك، متوقفة عند أول درجة تنطبق: مصدر أحادي الريبو إذا كنت داخل ريبو AgentEye، وإلا عجلة الإصدار الخاصة من GitHub Releases (تحتاج إلى وصول)، وإذا لم تكن متاحة فإنها **توقف وتخبرك بطلب عجلة من جهة Failproof AI الخاصة بك** بدلاً من الارتجال. +تعرف المهارة هذا وتعمل بسلم تثبيت بدلاً من ذلك، توقفاً عند أول درجة تنطبق: مصدر المونوريبو إذا كنت داخل مستودع AgentEye، وإلا عجلة الإصدار الخاصة من GitHub Releases (تحتاج إلى وصول)، وإذا لم يكن أي منهما متاحاً فإنها **توقفاً وتخبرك أن تطلب من جهة الاتصال Failproof AI الخاصة بك العجلة** بدلاً من الارتجال. -لذا إذا اقترح وكيلك `pip install agenteye-evaluator` بسيطة من PyPI العام، هذا يشير إلى أن المهارة لم تحمّل أبداً. توقف هناك وتحقق من تثبيتها. +لذا إذا اقترح وكيلك `pip install agenteye-evaluator` المباشر من PyPI العام، فهذا دليل على أن المهارة لم تحمّل أبداً. توقف هناك وتحقق من تثبيتها. --- -## ما يمكنك طلبه +## ما يمكنك أن تطلبه -جولة ذهاب وإياب حقيقية تبدأ بطلب غامض وتنتهي بتصميم موقّع، وليس بكود: +جولة حقيقية ذهاباً وإياباً تبدأ برغبة غامضة وتنتهي بتصميم موقع، وليس بكود: ```text -أنت ▸ أريد تقييمات لـ support bot الخاص بنا. أعتقد أنه سيء أحياناً. +أنت ▸ أريد تقييمات لروبوت الدعم الخاص بنا. أعتقد أنه سيء أحياناً. -وكيل ▸ قبل أن أكتب أي شيء: اصف تشغيلاً سار بشكل جيد، - وواحداً سار بشكل سيء. +وكيل ▸ قبل أن أكتب أي شيء: صِف عملية سارت بشكل جيد، + وواحدة سارت بشكل سيء. -أنت ▸ جيد: يجيب من المستندات. سيء: يختلق أشياء، +أنت ▸ جيد: يجيب من الوثائق. سيء: يختلق أشياء، أو يستسلم ويقول "اتصل بالدعم". وكيل ▸ تشغيل: agenteye --json sessions --status error --since 7d - قراءة 5 جلسات، بما في ذلك اثنتان كنت ستسميهما سيئة. + قراءة 5 جلسات، بما فيها اثنتان تعتبرهما سيئة. - كلماتك تقول دقة وتحويل. تتفق النصوص على التحويل - (اثنتان من 5 تنتهي مع تحويل دعم، وهو واضح في - model_response.content)، لكن الدقة تحتاج حقيقة - أرضية لا يحملها حدثك. + كلماتك تقول الحقيقة والتراجع. الوثائق تتفق على التراجع + (2 من 5 ينتهيان بتسليم دعم، وهو واضح في + model_response.content)، لكن الحقيقة تحتاج إلى أساس + الحقيقة الذي لا تحمله أحداثك. - إذن كنت أقيّم ثلاثة أشياء: - - deflection قواعد، رخيص، يفصل تشغيلاتك - - tool_efficiency قواعد، يمسك حلقة الإعادة في run-004 - - groundedness قاضي LLM: هل كل مطالبة في المستندات التي سحبتها؟ + إذاً سأصنف ثلاثة أشياء: + - deflection قواعد، رخيصة، تفصل بين عمليتيك + - tool_efficiency قواعد، تمسك حلقة إعادة المحاولة في run-004 + - groundedness حكم LLM: هل كل ادعاء في الوثائق التي استرجعتها؟ - كان "factuality" يحتاج حقيقة أرضية ليس لدينا؛ groundedness - هو أقرب شيء يمكن لنصوصك فعلاً دعمه. - بخير مع تلك الأسماء الثلاثة؟ إعادة التسمية لاحقاً تقسم التاريخ. + "factuality" ستحتاج إلى أساس حقيقة لا نملكه؛ groundedness + هو أقرب شيء يمكن لنصوصك فعلياً دعمه. + موافق على هذه الأسماء الثلاثة؟ إعادة تسمية لاحقة تقسم التاريخ. أنت ▸ نعم -وكيل ▸ لا يوجد مُقيّم في هذا الريبو. هل يجب أن أنشئ واحداً هنا، أم +وكيل ▸ لا يوجد مقيّم في هذا المستودع. هل يجب أن أبني واحداً هنا، أم لديك واحد في مكان آخر؟ ``` -من هناك يكتب الأبعاد القائمة على القواعد أولاً (مجاني، فوري، حتمي)، يختبرها مقابل جلسة حقيقية مأخوذة بما في ذلك الفارغة والتي لم تنتهِ أبداً التي تحطم المُقيّمين الساذجين، ولا تصل فقط إلى قاضي LLM على البعد الموضوعي. يعرف حدود [المرسل](/ar/agenteye/evaluation-suite#configuring-the-server) — مهلة 30 ثانية وثمانية استدعاءات متزامنة بنطاق النشر — لذا إذا لم يناسب القاضي بشكل موثوق، يذهب غير متزامن مع `JobPending` بدلاً من السماح لقاضيك بالإلغاء وإعادة المحاولة خمس مرات بخمسة أضعاف التكلفة. +من هناك يكتب الأبعاد المستندة إلى القواعد أولاً (مجانية، فورية، حتمية)، يختبرها على جلسة حقيقية مسجلة تشمل الفارغة والمكتملة أبداً التي تحطم المقيّمين السذج، وتصل فقط للحكم LLM على البعد الذاتي. يعرف حدود [المُرسل](/ar/agenteye/evaluation-suite#configuring-the-server) — انتظار 30 ثانية وحد 8 استدعاءات متزامنة على مستوى النشر — لذا إذا لم يناسب الحكم بشكل موثوق، ينتقل بشكل غير متزامن مع `JobPending` بدلاً من السماح لحكمك بإلغائه وإعادة محاولته خمس مرات بخمسة أضعاف التكلفة. -ثم ينشر، يعيّن متغيري بيئة الخادم، ويؤكد مع `agenteye --json evals --session-id ` أن الدرجات هبطت فعلاً. هبوط الدرجات هو الدليل الوحيد. +ثم ينشره، يضبط متغيري بيئة الخادم، ويؤكد مع `agenteye --json evals --session-id ` أن النقاط فعلاً وصلت. وصول النقاط هو الدليل الوحيد. --- ## ما يجب الانتباه له -- **أسماء الأبعاد قريبة من الدائمة.** مفاتيح الدرجات سلاسل اختيارية والمنصة تتجه أينما أرسلت، مما يعني لا شيء يصحح لاحقاً خياراً سيئاً. أعد التسمية لاحقاً وينقسم التاريخ: الجلسات القديمة تحتفظ بالمفتاح القديم وينقطع الاتجاه. هذا هو السبب في حصول المهارة على موافقة صريحة قبل كتابة الكود — خذ هذا الحث بجدية. -- **الدعائم هي نصوص إنتاجية حقيقية.** يعني التصميم مقابل جلسات حقيقية سحبها إلى الديسك، ويمكنها أن تحتوي بيانات العملاء. تطلب المهارة قبل التعهد بهم إلى git؛ إذا كنت غير متأكد، احفظ `fixtures/` خارج الريبو وليترك كل مطور سحب الخاص به. -- **الوكيل يكتب وينشر خدمة تقرأ كل نص.** يتصرف كأنك، محدود بأذونات تسجيل دخول CLI الخاصة بك، لكن مراجعة المُقيّم مثل أي كود آخر يلمس بيانات الإنتاج. +- **أسماء الأبعاد قريبة من الدائمة.** مفاتيح النقاط أسماء عشوائية والمنصة تتجه لأي شيء تُرسله، مما يعني لا شيء في اتجاه مجري يصحح خياراً سيئاً. أعد تسمية لاحقاً وينقسم التاريخ: الجلسات القديمة تحتفظ بالمفتاح القديم والاتجاه ينكسر. هذا هو السبب في أن المهارة تحصل على توقيع صريح قبل كتابة الكود — اعتبر هذا الطلب بجدية. +- **التركيبات هي نصوص إنتاجية حقيقية.** التصميم مقابل جلسات حقيقية يعني سحبها إلى القرص، ويمكنها أن تحتوي على بيانات العملاء. تسأل المهارة قبل التزامها بـ git؛ إذا كنت في شك، أبقِ `fixtures/` خارج المستودع واجعل كل مطور يسحب خاصه. +- **الوكيل يكتب وينشر خدمة تقرأ كل نص.** يتصرف كأنت، محدود بأذونات تسجيل دخول CLI الخاص بك، لكن راجع المقيّم كأي كود آخر يلمس بيانات الإنتاج. --- ## الخطوات التالية -- **[مجموعة التقييم](/ar/agenteye/evaluation-suite)**: عقد HTTP، SDK، ومتغيرات بيئة الخادم التي تقوم المهارة بتكوينها. -- **[التقييمات](/ar/agenteye/evaluations)**: حيث تظهر الدرجات مرة تهبط. -- **[مهارة CLI](/ar/agenteye/cli-skill)**: المهارة الشقيقة، لقراءة النتائج بدلاً من بناء المُقيّم. +- **[جناح التقييم](/ar/agenteye/evaluation-suite)**: عقد HTTP، SDK، ومتغيرات بيئة الخادم التي تضبطها المهارة. +- **[التقييمات](/ar/agenteye/evaluations)**: حيث تظهر النقاط بمجرد وصولها. +- **[مهارة CLI](/ar/agenteye/cli-skill)**: المهارة الشقيقة، لقراءة النتائج بدلاً من بناء المصنف. - **[CLI](/ar/agenteye/cli)**: مرجع الأوامر خلف بيانات الجلسة التي تصممها المهارة. \ No newline at end of file diff --git a/docs/ar/agenteye/event-stream.mdx b/docs/ar/agenteye/event-stream.mdx index e427ef40..b9207948 100644 --- a/docs/ar/agenteye/event-stream.mdx +++ b/docs/ar/agenteye/event-stream.mdx @@ -1,50 +1,50 @@ --- +--- title: "تدفق الأحداث" -description: "في اللحظة التي يقوم بها وكيلك بشيء ما، ترى ذلك." +description: "في اللحظة التي يقوم بها الوكيل بأي شيء، تراه." --- +في اللحظة التي يقوم بها الوكيل بأي شيء، تراه. تدفق الأحداث هو نبضك الحي على كل وكيل في الإنتاج: بدون انتظار، بدون البحث في السجلات، بدون التكهن بما حدث للتو. -في اللحظة التي يقوم بها وكيلك بشيء ما، ترى ذلك. تدفق الأحداث هو نبضك الحي لكل وكيل في الإنتاج: بدون انتظار، بدون البحث في السجلات، بدون التكهنات حول ما حدث للتو. - -![تدفق الأحداث المباشر: صفوف الأحداث الملونة بالألوان تظهر في الوقت الفعلي، قابلة للتصفية حسب البيئة والوكيل والجلسة ونوع الحدث والبحث النصي](/agenteye/images/events-stream.png) +![تدفق الأحداث المباشر: صفوف الأحداث ملونة الكود تتدفق في الوقت الفعلي، قابلة للتصفية حسب البيئة والوكيل والجلسة ونوع الحدث والنص الحر](/agenteye/images/events-stream.png) -*كل حدث من كل وكيل في مؤسستك، الأحدث أولاً، يتحدث في الوقت الفعلي.* +*كل حدث من كل وكيل في مؤسستك، الأحدث أولاً، تُحدّث وهي تحدث.* -## نبضك الحي لكل وكيل +## نبضك الحي على كل وكيل -عندما يبدأ الوكيل في تشغيل، أو يستدعي نموذجاً، أو ينطلق أداة، أو ينفذ خطاف، أو يواجه خطأ، يظهر الصف في أعلى التدفق في اللحظة التي يحدث فيها. يتابع كل حدث عبر كل وكيل في مؤسستك، الأحدث أولاً، بحيث يكون لديك دائماً صورة حالية بدلاً من صورة قديمة. +عندما يبدأ الوكيل بتشغيل، أو ينادي نموذج، أو يطلق أداة، أو ينفذ hook، أو يصطدم بخطأ، يظهر الصف في أعلى التدفق في اللحظة التي يحدث فيها. يتابع كل حدث في كل وكيل في مؤسستك، الأحدث أولاً، حتى تحصل دائماً على صورة حالية بدلاً من صورة قديمة. -هذا يعني عدم تتبع ملفات السجل على جهاز ما، عدم البحث عبر الأجهزة، عدم ربط الطوابع الزمنية يدويًا. تفتح صفحة واحدة وأنت بالفعل تراقب الإنتاج. +هذا يعني عدم الاضطرار إلى متابعة ملفات السجل على صندوق ما، وعدم البحث عبر الآلات، وعدم ربط الطوابع الزمنية معاً يدوياً. تفتح صفحة واحدة وأنت بالفعل تراقب الإنتاج. -يتم ترميز الصفوف بالألوان حسب النوع، لذا يمكنك قراءة التدفق للوهلة الأولى بدلاً من تحليل كل سطر. للوهلة الأولى، يظهر لك كل صف: +يتم تلوين الصفوف حسب النوع، حتى تتمكن من قراءة التدفق بنظرة واحدة بدلاً من تحليل كل سطر. في نظرة واحدة، يُظهر لك كل صف: -- **نوعه**، مرمز بالألوان: `agent_start`، `model_response`، `tool_use`، `hook_completed`، `error`، وغيرها. -- **ملخص من سطر واحد** لما حدث، بحيث نادراً ما تحتاج إلى فتح أي شيء فقط للحصول على الفكرة العامة. +- **نوعه**، ملون الكود: `agent_start`، `model_response`، `tool_use`، `hook_completed`، `error`، والمزيد. +- **ملخص من سطر واحد** لما حدث، حتى نادراً ما تحتاج إلى فتح أي شيء للحصول على الفكرة العامة. - **عدد الرموز** للخطوة. -- **شارة ملء نافذة السياق** حيث ينطبق ذلك، بحيث يكون نمو الموجه والضغط القادم مرئيين قبل أن يؤثروا عليك. +- **شارة ملء نافذة السياق** حيث تنطبق، بحيث يكون نمو الملخص والضغط القادم مرئيين قبل أن يسبب مشاكل. -مراقبته بشكل مباشر تعني أنك تقبض على نشر سيء أو حلقة جامحة أو انفجار أخطاء عندما يحدث، وليس في مراجعة السجل في اليوم التالي. +مراقبتها مباشرة تعني أنك تلتقط نشراً سيئاً، أو حلقة هاربة، أو انفجار أخطاء وهي تحدث، وليس في مراجعة السجل بغد الغد. ## ابحث عن التشغيل الوحيد الذي يهم -عندما يبدو شيء ما غير صحيح، لا تريد كل شيء. تريد التشغيل الوحيد الذي انكسر. التدفق يتصفى بسرعة: حسب البيئة، حسب الوكيل، حسب الجلسة، حسب نوع الحدث، أو بالبحث النصي. +عندما يبدو شيء ما خاطئاً، أنت لا تريد فيضاناً من المعلومات. تريد التشغيل الوحيد الذي انكسر. ينخفض التدفق بسرعة: حسب البيئة، والوكيل، والجلسة، ونوع الحدث، أو النص الحر. -قم بالتصفية حسب معرف الجلسة أو معرف الوكيل لمتابعة تشغيل واحد من حدثه الأول إلى الأخير. قم بالتصفية حسب نوع الحدث لعزل نوع واحد من النشاط، على سبيل المثال كل `error` عبر المؤسسة في عرض واحد. قم بتجميع المرشحات للتضييق من "كل شيء، في كل مكان" إلى "هذا الوكيل، في الإنتاج، يخطئ" في بضع نقرات، ثم تصرف بناءً على ما تجده. +صفّ حسب معرّف الجلسة أو معرّف الوكيل لمتابعة تشغيل واحد من حدثه الأول إلى الأخير. صفّ حسب نوع الحدث لعزل نوع واحد من النشاط، على سبيل المثال كل `error` في جميع أنحاء المؤسسة في عرض واحد. كدّس المرشحات للتضييق من "كل شيء، في كل مكان" إلى "هذا الوكيل، في الإنتاج، يخطئ" في نقرتين أو ثلاث، ثم تصرف بناءً على ما تجده. -يقطع البحث النصي الحر مباشرة إلى رسالة أو اسم أداة أو معرف لديك بالفعل في متناول اليد، بحيث تتحول تقارير العملاء إلى التشغيل الدقيق في ثوان. +يقطع البحث بالنص الحر مباشرة إلى رسالة، أو اسم أداة، أو معرّف لديك بالفعل في متناول اليد، لذا يتحول تقرير العميل إلى التشغيل الدقيق في ثوان. ## أين تجده -تدفق الأحداث هو منزل مؤسستك. سجل الدخول وهو أول سطح تهبط عليه، في `//`، لذا يبدأ الفرز في اللحظة التي تصل فيها. +تدفق الأحداث هو بيت مؤسستك. قم بتسجيل الدخول وهو أول سطح تهبط عليه، في `//`، بحيث تبدأ الفرز في اللحظة التي تصل فيها. -خلفه، يصدر وكلاؤك أحداثاً عبر SDK، ويشحن المجمّع إلى خادم Failproof AI Observability الخاص بك، والتدفق يتابعهم عندما يصلون إلى البنية التحتية التي تتحكم فيها. عندما تريد العرض المجمع بدلاً من المسار الأولي، تنهار أحداث كل تشغيل إلى صف واحد على الجلسات، على بعد نقرة واحدة. +خلفه، ينبعث الوكلاء الأحداث من خلال SDK، والمجمّع يشحنها إلى خادم Failproof AI Observability الخاص بك، والتدفق يتابعها وهي تصل إلى البنية الأساسية التي تتحكم فيها. عندما تريد العرض المطوي بدلاً من الأثر الخام، تنهار أحداث كل تشغيل إلى صف واحد على جلسات، نقرة واحدة بعيداً. -هذا هو مصدر الحقيقة الأولي الذي تبني عليه جميع أسطح الملاحظة الأخرى، لذا عندما يبدو الرقم خاطئاً في مكان آخر، التدفق هو المكان الذي تؤكد فيه ما حدث فعلاً. +هذا هو مصدر الحقيقة الخام الذي يبني عليه كل سطح ملاحظة آخر، لذا عندما يبدو رقم خاطئاً في مكان آخر، التدفق هو حيث تؤكد ما حدث فعلاً. -## ذات الصلة +## ذات صلة -- [الجلسات](/ar/agenteye/sessions): نفس الأحداث مجمعة في صف واحد لكل تشغيل، مع رسم بياني للتنفيذ بنمط git. -- [القياس عن بعد](/ar/agenteye/telemetry): ما يرسله وكلاؤك وكيف تصل الأحداث إلى التدفق. -- [تتبع الأخطاء](/ar/agenteye/error-tracking): سطح فرز واحد لكل ما حدث بشكل خاطئ. -- [التنبيهات](/ar/agenteye/alerts): حول أي عتبة إلى قاعدة صفحة. -- [CLI والوكلاء](/ar/agenteye/cli-and-agents): نفس المسار الحي من المحطة الطرفية. \ No newline at end of file +- [الجلسات](/ar/agenteye/sessions): نفس الأحداث المطوية إلى صف واحد لكل تشغيل، مع رسم بياني للتنفيذ بأسلوب git. +- [القياس](/ar/agenteye/telemetry): ما يرسله الوكلاء وكيف تصل الأحداث إلى التدفق. +- [تتبع الأخطاء](/ar/agenteye/error-tracking): سطح فرز واحد لكل ما حدث خطأ. +- [التنبيهات](/ar/agenteye/alerts): حوّل أي عتبة إلى قاعدة استدعاء. +- [واجهة سطر الأوامر والوكلاء](/ar/agenteye/cli-and-agents): نفس الأثر المباشر من طرفيتك. \ No newline at end of file diff --git a/docs/ar/agenteye/hermes-capture.mdx b/docs/ar/agenteye/hermes-capture.mdx index c65c2e61..fda8e3f7 100644 --- a/docs/ar/agenteye/hermes-capture.mdx +++ b/docs/ar/agenteye/hermes-capture.mdx @@ -1,54 +1,54 @@ --- --- title: "التقاط جلسات Hermes" -description: "أحضر جلسات بوابة Hermes الخاصة بفريقك — Slack و Telegram و CLI والتشغيلات المجدولة — إلى AgentEye كجلسات وأحداث عادية." +description: "استيراد جلسات بوابة Hermes لفريقك — Slack و Telegram و CLI والتشغيل المجدول — إلى AgentEye كجلسات وأحداث عادية." --- -[Hermes](https://hermes-agent.nousresearch.com) يجيب فريقك من أي مكان يعملون فيه بالفعل — Slack و Telegram و CLI والتشغيلات المجدولة. يجلب التقاط جلسات Hermes كل شيء إلى AgentEye كجلسات وأحداث عادية، بحيث يكون المساعد الذي يتحدث معه فريقك يومياً قابلاً للملاحظة مثل الوكلاء الذين تكتبهم بنفسك. +[Hermes](https://hermes-agent.nousresearch.com) يرد على فريقك من أي مكان يعملون فيه بالفعل — Slack و Telegram و CLI والتشغيل المجدول. يجلب التقاط جلسات Hermes كل ذلك إلى AgentEye كجلسات وأحداث عادية، بحيث يكون المساعد الذي يتحدث معه فريقك يومياً قابلاً للرصد مثل الوكلاء الذي تكتبه بنفسك. -يقرأ جامع خفيف محلي مخزن جلسات Hermes المحلي أثناء كتابته وينقل الجلسات إلى AgentEye. يعمل بنفس الطريقة التي تعمل بها عمليات التقاط [Codex](/ar/agenteye/codex-capture) و [OpenClaw](/ar/agenteye/openclaw-capture)، ويمكن لجامع واحد أن يلتقط عدة في نفس الوقت. +جامع محلي صغير يقرأ متجر جلسات Hermes المحلي أثناء كتابته وينقل الجلسات إلى AgentEye. يعمل بنفس الطريقة التي يعمل بها التقاط [Codex](/ar/agenteye/codex-capture) و [OpenClaw](/ar/agenteye/openclaw-capture)، ويمكن لجامع واحد أن يلتقط عدة جلسات في وقت واحد. --- -## ما الذي يتم التقاطه +## ما يتم التقاطه -يتم التقاط كل جلسة Hermes على الجهاز، بغض النظر عن القناة التي جاءت منها. تصبح كل واحدة منها [جلسة](/ar/agenteye/sessions) AgentEye؛ رسائل المستخدم والمساعد وعمليات استدعاء الأدوات ونتائج الأدوات تصبح [الأحداث](/ar/agenteye/event-stream) المطابقة. +يتم التقاط كل جلسة Hermes على الجهاز، بغض النظر عن القناة التي جاءت منها. تصبح كل واحدة منها جلسة AgentEye من [جلسة](/ar/agenteye/sessions)؛ رسائل المستخدم والمساعد فيها واستدعاءات الأدوات ونتائج الأدوات تصبح [الأحداث](/ar/agenteye/event-stream) المطابقة. -يتم تسجيل القناة التي بدأت منها الجلسة — Slack أو Telegram أو CLI أو تشغيل مجدول — على الجلسة، بحيث يمكنك التمييز بينها والتصفية إلى واحدة في كل مرة. بجانبها يأتي النموذج الذي قامت الجلسة عليه وبيانات الدردشة والشخص الذي بدأت منه، وعندما تولد جلسة أخرى، الارتباط بالجلسة الأب. +يتم تسجيل القناة التي بدأت منها الجلسة — Slack أو Telegram أو CLI أو تشغيل مجدول — على الجلسة، حتى تتمكن من تمييزها والتصفية إلى واحدة في كل مرة. بجانبها يأتي النموذج الذي تم تشغيل الجلسة عليه والدردشة والشخص الذي تم بدء الجلسة منه، وعندما تولد جلسة أخرى، يأتي الارتباط العودة إلى جلستها الأصلية. -تظهر الجلسات حالما يبدأها Hermes، سواء تم قول أي شيء أم لا، وتبقى إجابة الدور واستدعاءات أدواته بالترتيب الذي حدثت فيه بالفعل. عندما تنتهي جلسة، تحصل أيضاً على سبب إنهاؤها وتكلفتها وعدد الرموز التي استخدمتها. +تظهر الجلسات بمجرد بدء Hermes لها، سواء تم قول أي شيء أم لا، وتبقى الرد على الدور واستدعاءات الأدوات به في الترتيب الذي حدثت به بالفعل. عندما تنتهي الجلسة، تحصل أيضاً على سبب انتهائها وتكلفتها وعدد الرموز التي استخدمتها. --- -## فعّله +## تشغيله -التقاط معطل حتى تفعّله. ثبّت الجامع باستخدام مفتاح API له صلاحية `events:add` (انظر [مفاتيح API](/ar/agenteye/api-keys))، وفعّل التقاط Hermes: +التقاط الجلسات مغلق حتى تقوم بتفعيله. قم بتثبيت الجامع بمفتاح API له إذن `events:add` (انظر [مفاتيح API](/ar/agenteye/api-keys))، وقم بتشغيل التقاط Hermes: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -هذا يثبّت الجامع ويسجله كخدمة خلفية ويبدأ التقاط. تأكد من أنه يعمل: +يقوم هذا بتثبيت الجامع وتسجيله كخدمة خلفية وبدء التقاط الجلسات. تأكد من أنه يعمل: ```bash agenteye-collector health ``` -تلتقط أكثر من وكيل واحد على نفس الجهاز؟ أضف علم كل منها لنفس الأمر — على سبيل المثال `--hermes-enabled --codex-enabled`. +هل تلتقط أكثر من وكيل واحد على نفس الجهاز؟ أضف علم كل واحد إلى نفس الأمر — على سبيل المثال `--hermes-enabled --codex-enabled`. -عند التشغيل الأول، يتم ملء جلسات Hermes الموجودة لديك مرة واحدة والنشاط الجديد يبدأ في البث خلال ثوانٍ. بيانات Hermes الخاصة بها تُقرأ فقط — لا تُعدّل أو تُحذف — وكل رسالة تُنقل مرة واحدة، حتى عبر عمليات إعادة التشغيل. +عند التشغيل الأول، يتم ملء جلسات Hermes الموجودة لديك مرة واحدة وتنتقل النشاط الجديد بعد ذلك في غضون ثوان. بيانات Hermes الخاصة بها تُقرأ فقط — لا تُعدّل أبداً أو تُحذف — وترسل كل رسالة مرة واحدة، حتى عبر إعادات التشغيل. -يخبرك `health` أيضاً ما إذا كان كل شيء قام الجامع بالتقاطه وصل فعلاً إلى AgentEye. إذا تعذر تسليم دفعة، يتم الاحتفاظ بها وإعادة محاولتها بدلاً من التخلص منها، والفحص يبلّغ عن حالة غير صحيحة طالما أن أي شيء قيد الانتظار — لذا فإن "صحيح" يعني وصول بياناتك، وليس فقط أن العملية حية. +`health` يخبرك أيضاً ما إذا كان كل ما التقطه الجامع قد وصل فعلاً إلى AgentEye. إذا لم تتمكن دفعة من التسليم، يتم الاحتفاظ بها وإعادة محاولتها بدلاً من التخلص منها، ويبلغ الفحص عن حالة غير صحية طالما لا تزال هناك أي أشياء معلقة — لذلك فإن "صحي" يعني أن بيانات وصلت، وليس فقط أن العملية حية. --- ## حيث يظهر -تظهر الجلسات المقبوضة في **Sessions**، وأحداثها في تيار **Events**، تماماً مثل أي وكيل آخر تراقبه — لذلك [إعادة تشغيل الجلسات](/ar/agenteye/sessions) و [البحث](/ar/agenteye/queries) و [التقييمات](/ar/agenteye/evaluations) و [التنبيهات](/ar/agenteye/alerts) تعمل جميعها عليها. صفّ حسب وكيل Hermes لرؤيتها بمفردها. +تظهر الجلسات المقبوضة في **Sessions**، وأحداثها في تدفق **Events**، تماماً كما هو الحال مع أي وكيل آخر تراقبه — لذلك فإن [جلسة إعادة التشغيل](/ar/agenteye/sessions) و [البحث](/ar/agenteye/queries) و [التقييمات](/ar/agenteye/evaluations) و [التنبيهات](/ar/agenteye/alerts) تعمل جميعها عليها. قم بالتصفية حسب وكيل Hermes لرؤيتها بمفردها. --- ## الخصوصية -تحتوي جلسات Hermes على النص الكامل — بما في ذلك مخرجات الأوامر ومحتويات الملفات وأي شيء قرأه الوكيل أو كتبه — وقد تحتوي على أسرار. يتم نقل الجلسات المقبوضة كما هي، لذا فعّل التقاط فقط حيث يكون تركيز هذا المحتوى في AgentEye مناسباً، وأعطِ الجامع مفتاحاً محدود النطاق بـ `events:add` فقط. انظر [الأمان](/ar/agenteye/security) لمعرفة كيفية الحفاظ على بياناتك معزولة. \ No newline at end of file +تحتوي جلسات Hermes على النسخة المكتملة من الحديث — بما في ذلك مخرجات الأوامر ومحتويات الملفات وأي شيء قرأه الوكيل أو كتبه — ويمكن أن تحتوي على أسرار. يتم شحن الجلسات المقبوضة كما هي، لذلك قم بتفعيل الالتقاط فقط حيث يكون مركزة هذا المحتوى في AgentEye مناسباً، وأعط الجامع مفتاحاً محدوداً بـ `events:add` فقط. انظر [الأمان](/ar/agenteye/security) لمعرفة كيفية الحفاظ على بيانات معزولة. \ No newline at end of file diff --git a/docs/ar/agenteye/incidents.mdx b/docs/ar/agenteye/incidents.mdx index 9be50d72..661fbdfc 100644 --- a/docs/ar/agenteye/incidents.mdx +++ b/docs/ar/agenteye/incidents.mdx @@ -1,29 +1,28 @@ --- ---- title: "الحوادث" -description: "عندما يطلق تنبيه ما، يمكن للجميع رؤية أن الحادثة مفتوحة، ومن يملك الملكية، وما حدث حتى الآن — على خط زمني موحد ومنسوب." +description: "عندما تطلق تنبيهاً، يمكن للجميع رؤية أن الحادثة مفتوحة، ومن المسؤول عنها، وما حدث حتى الآن — في سجل زمني موحد." --- -عندما يطلق تنبيه ما، السؤال الأول هو دائماً "من يتولى الأمر؟" الحوادث تجيب على ذلك: في اللحظة التي يحدث خرق ما، يمكن للجميع رؤية أن الحادثة مفتوحة، ومن يملك الملكية، وبالضبط ما حدث حتى الآن، مع سجل نظيف ومنسوب يمكنك تسليمه مباشرة إلى جلسة تحليل ما بعد الحادثة. +عندما يطلق تنبيه، السؤال الأول هو دائماً "من يتولى الأمر؟" الحوادث تجيب عليه: في اللحظة التي يحدث فيها انتهاك، يمكن للجميع رؤية أن الحادثة مفتوحة، ومن المسؤول عنها، وبالضبط ما حدث حتى الآن، مع سجل نظيف وموثق يمكنك تسليمه مباشرة إلى تقرير ما بعد الحادثة. -![صندوق وارد الحوادث: بطاقات حوادث مرتبطة بالتنبيهات ومفتوحة يدويًا، مجمعة حسب الحالة، كل منها مع شارة خطورة وشخص مسؤول](/agenteye/images/incidents.png) -*يجمع الصندوق الحوادث المفتوحة حسب الحالة وينقيها حسب مستوى الخطورة والشخص المسؤول، لتري ما يحتاج تدخل بشري الآن.* +![صندوق وارد الحوادث: بطاقات حوادث مرتبطة بالتنبيهات ومفتوحة يدويًا، مجمعة حسب الحالة، كل منها مع شارة الخطورة واسم المسؤول](/agenteye/images/incidents.png) +*يجمع الصندوق الحوادث المفتوحة حسب الحالة ويرشحها حسب الخطورة واسم المسؤول، بحيث ترى ما يتطلب اهتمام الآن.* -## اعرف من يتولى الأمر، بلمحة واحدة +## تعرف من يتولى الأمر، بنظرة واحدة -لا مزيد من "هل أحد ما ينظر إلى هذا؟" في خيط دردشة. يفتح الخرق حادثة تلقائياً ويضعها في صندوق وارد مشترك، مجمعة حسب الحالة. اعترف بها واسمك عليها، لذا يعرف بقية الفريق أنه تم التعامل معها. الاعتراف مشترك: عدة مشغلين يمكنهم الاعتراف بنفس الحادثة وكل واحد يُسجل بشكل منفصل، لذا تظهر غرفة حرب كاملة بالأسماء بدلاً من التداخل. عيّن مالك واحد للفحص الأولي، وصفّي صندوق الوارد حسب مستوى الخطورة أو الشخص المسؤول لتقليصه إلى ما هو من مسؤوليتك. +لا مزيد من "هل أحد ينظر إلى هذا؟" في سلسلة محادثة. يفتح الانتهاك حادثة تلقائياً وينقلها إلى صندوق وارد مشترك، مجمعة حسب الحالة. قم بتأكيد الاستقبال واسمك سيظهر عليها، بحيث يعرف باقي الفريق أنها قيد المعالجة. التأكيد مشترك: عدة مشغلين يمكنهم تأكيد الاستقبال للحادثة ذاتها ويتم تسجيل كل منهم بشكل منفصل، بحيث يظهر غرفة الحرب الكاملة بالأسماء بدلاً من تضارب التصرفات. عيّن مسؤولاً واحداً لفرز الأولويات، واستخدم مرشح الصندوق حسب الخطورة أو المسؤول لتقليله إلى ما يخصك. -## القصة كاملة، في خط زمني واحد +## القصة كاملة، في سجل زمني واحد -عندما تنتهي الحادثة، تكون لديك بالفعل التقرير. افتح أي حادثة وستحصل على دليل الخرق، والأشخاص المسؤولين والمشتركين، وخيط تعليقات للتنسيق في نفس المكان، وخط زمني نشاط منسوب وإضافي فقط. +عندما تنتهي الحادثة، يكون لديك بالفعل التقرير. افتح أي حادثة وستحصل على دليل الانتهاك وملخص الخرق، المسؤولون والمشتركون، سلسلة تعليقات للتنسيق، وسجل نشاط زمني محفوظ بشكل كامل. -![عرض تفاصيل الحادثة: التنبيه الأب وملخص الخرق، الأشخاص المسؤولين والمشتركين، خط زمني نشاط منسوب، وخيط تعليقات](/agenteye/images/incident-detail.png) -*كل ما حدث، بالترتيب، كل سطر موقّع من قبل من قام به.* +![عرض تفاصيل الحادثة: التنبيه الأساسي وملخص الخرق، المسؤولون والمشتركون، سجل نشاط موثق زمنياً، وسلسلة تعليقات](/agenteye/images/incident-detail.png) +*كل ما حدث، بالترتيب، كل سطر موقع من قبل من قام به.* -كل إجراء (مفتوح، معترف به، تم حله، وما إلى ذلك) يُكتب في هذا الخط الزمني ولا يُعدّل أبداً. كل إدخال منسوب: إلى المشغل الذي اتخذه، برسالة البريد الإلكتروني، أو إلى **automated** لأي شيء فعلته Failproof AI تلقائياً، مثل فتح الحادثة على الخرق. لا شيء مجهول ولا شيء ضائع، لذا فإن تحليل ما بعد الحادثة يكتب نفسه تقريباً. +كل إجراء (فتح، تأكيد، حل، وما إلى ذلك) يُكتب إلى هذا السجل الزمني ولا يُحذف أبداً. كل إدخال موثق: من قبل المشغل الذي قام به، بالبريد الإلكتروني، أو إلى **automated** لأي شيء قامت به Failproof AI Observability من تلقاء نفسها، مثل فتح الحادثة عند الخرق. لا شيء مجهول ولا شيء مفقود، لذا تقرير ما بعد الحادثة يكتب نفسه بنفسه تقريباً. -## كيف تتحرك الحادثة +## كيفية تطور الحادثة ```mermaid stateDiagram-v2 @@ -34,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **مفتوحة (نشطة):** يفتح الخرق الحادثة وينبه قنواتك مرة واحدة. تطويات الخروقات المتكررة في نفس الحادثة وتحديث أدلتها بدلاً من إنبيهك مراراً وتكراراً. -- **معترف بها:** يلتقطها مشغل. تبقى مفتوحة، والخروقات اللاحقة تحدث الأدلة بهدوء. -- **تم حلها:** يغلقها مشغل. الحل التلقائي عندما تتضح الحالة مخطط له لكن لم يتم تفعيله بعد، لذا تبقى الحادثة مفتوحة حتى يحلها إنسان، مما يجعل الجميع مسؤولين عما تم حله فعلاً. يمكن أن تفتح حادثة جديدة على نفس التنبيه لاحقاً. +- **مفتوح (في الحالة النشطة):** الخرق يفتح الحادثة وينبه قنواتك مرة واحدة. الخروقات المتكررة تندمج في الحادثة ذاتها وتحدّث أدلتها بدلاً من إخطارك مراراً وتكراراً. +- **مؤكد الاستقبال:** مشغل يتولى الأمر. تبقى مفتوحة، والخروقات اللاحقة تحدّث الأدلة بصمت. +- **محل:** مشغل يغلقها. الحل التلقائي عندما تنتهي الحالة مخطط له لكن لم يُفعّل بعد، لذا تبقى الحادثة مفتوحة حتى يحلها الإنسان، مما يحافظ على المصداقية حول ما انتهى فعلاً. يمكن فتح حادثة جديدة على نفس التنبيه لاحقاً. -يحتفظ التنبيه الواحد بحادثة مفتوحة واحدة على الأكثر في المرة الواحدة، لذا فإن القاعدة المتذبذبة لا يمكنها أن تدفنك في النسخ المكررة. يمكنك أيضاً فتح حادثة يدويًا: واحدة مستقلة لشيء لم يلتقطه أي تنبيه، أو واحدة مرتبطة بتنبيه موجود، إذا كان لديك `incidents:write`. +تنبيه واحد يحمل على الأكثر حادثة مفتوحة واحدة في كل مرة، لذا قاعدة متقلبة لا يمكنها أن تغمرك بالنسخ المكررة. يمكنك أيضاً فتح حادثة يدويًا: واحدة مستقلة لشيء لم يتقطها أي تنبيه، أو واحدة مرتبطة بتنبيه موجود، إذا كان لديك `incidents:write`. ## أين تجدها -تعيش الحوادث في `//incidents`. العرض يحتاج **`incidents:read`**؛ فتح حادثة يدوية يحتاج **`incidents:write`**؛ الاعتراف والتعيين والتعليق والحل يحتاج **`incidents:ack`**. المفاتيح الأقدم التي منحت `alerts:ack` المتقاعد تستمر في العمل، حيث يتم احترامها كـ `incidents:ack`، لذا فإن دوران الحراسة لا يحتاج إلى إعادة إصدار. +الحوادث تقع في `//incidents`. العرض يحتاج **`incidents:read`**؛ فتح حادثة يدوية يحتاج **`incidents:write`**؛ تأكيد الاستقبال والتعيين والتعليق والحل يحتاجون **`incidents:ack`**. المفاتيح الأقدم التي منحت `alerts:ack` المتقاعدة تبقى تعمل، لأنه يُعترف بها كـ `incidents:ack`، بحيث لا تحتاج دورة على الاتصال إلى إعادة إصدار. ## ذات صلة -- [التنبيهات](/ar/agenteye/alerts): القواعد التي تفتح هذه الحوادث عندما يحدث خرق للحد. -- [تتبع الأخطاء](/ar/agenteye/error-tracking): شاهد كل فشل في مكان واحد وارفعه إلى تنبيه. -- [التدقيق](/ar/agenteye/audits): محلل مجدول يجد الأخطاء التي لم تراقبها أي قاعدة. \ No newline at end of file +- [التنبيهات](/ar/agenteye/alerts): القواعد التي تفتح هذه الحوادث عند انتهاك الحد. +- [تتبع الأخطاء](/ar/agenteye/error-tracking): اعرض كل فشل في مكان واحد وارتقِ بواحد إلى تنبيه. +- [التدقيقات](/ar/agenteye/audits): محلل مجدول يجد الأخطاء التي لم تكن أي قاعدة تراقبها. \ No newline at end of file diff --git a/docs/ar/agenteye/observability.mdx b/docs/ar/agenteye/observability.mdx index ad82447a..d707fe43 100644 --- a/docs/ar/agenteye/observability.mdx +++ b/docs/ar/agenteye/observability.mdx @@ -1,24 +1,23 @@ --- ---- -title: "مراقبة" -description: "أسطح المراقبة هي حيث تشاهد ما يفعله وكلاؤك الآن وتتعمق في أي تشغيل واحد." +title: "المراقبة" +description: "سطوح المراقبة هي حيث تراقب ما يفعله وكلاؤك الآن وتتعمق في أي تشغيل واحد." --- -أسطح المراقبة هي حيث تشاهد ما يفعله وكلاؤك الآن وتتعمق في أي تشغيل واحد. كل شيء هنا مباشر، وفي نطاق مؤسستك، وقابل للتصفية حسب نطاق التاريخ والبيئة والوكيل والجلسة، لذا تنتقل من "هناك شيء ما يبدو غريباً" إلى التشغيل الدقيق في ثوانٍ. +سطوح المراقبة هي حيث تراقب ما يفعله وكلاؤك الآن وتتعمق في أي تشغيل واحد. كل شيء هنا مباشر، مقتصر على مؤسستك، وقابل للتصفية حسب نطاق التاريخ والبيئة والوكيل والجلسة، لذا تنتقل من "هناك شيء خاطئ" إلى التشغيل الدقيق في ثوان. -![تدفق الأحداث المباشر، مرمز بألوان حسب النوع وقابل للتصفية حسب البيئة والوكيل والجلسة](/agenteye/images/events-stream.png) +![دفق الأحداث المباشر، مشفر بالألوان حسب النوع وقابل للتصفية حسب البيئة والوكيل والجلسة](/agenteye/images/events-stream.png) -أربعة أسطح، لكل منها صفحته الخاصة: +أربع سطوح، لكل منها صفحتها الخاصة: -- **[تدفق الأحداث](/ar/agenteye/event-stream)**: مسار مباشر خطوة تلو الخطوة لكل تشغيل عبر كل وكيل، الأحدث أولاً. منزل مؤسستك والمحطة الأولى للفرز. -- **[الجلسات والرسم البياني للتنفيذ](/ar/agenteye/sessions)**: تلك الأحداث مدمجة في صف واحد لكل تشغيل، بالإضافة إلى صورة بأسلوب git لكيفية تطور كل تشغيل. -- **[مقاييس الأداء](/ar/agenteye/telemetry)**: خرائط حرارية للكمون وحيويات p50/p95/p99 لنماذجك وأدواتك وخطافاتك، لذا تبرز ارتفاعات الذيل عن المتوسط. -- **[تتبع الأخطاء](/ar/agenteye/error-tracking)**: سطح فرز واحد لكل ما حدث خطأ، نقرة واحدة من تنبيه مُطلق إلى التشغيل الذي انكسر. +- **[دفق الأحداث](/ar/agenteye/event-stream)**: المسار المباشر، خطوة تلو الأخرى، لكل تشغيل عبر كل وكيل، الأحدث أولاً. منزل مؤسستك والمحطة الأولى للفحص السريع. +- **[الجلسات والرسم البياني التنفيذي](/ar/agenteye/sessions)**: تلك الأحداث مجمعة في صف واحد لكل تشغيل، بالإضافة إلى صورة بأسلوب git لكيفية سير كل تشغيل. +- **[مقاييس الأداء](/ar/agenteye/telemetry)**: خرائط حرارية للكمون وقياسات p50/p95/p99 الحيوية لنماذجك وأدواتك وخطافاتك، بحيث يبرز ارتفاع الذيل عن المتوسط. +- **[تتبع الأخطاء](/ar/agenteye/error-tracking)**: سطح فحص سريع واحد لكل ما حدث بشكل خاطئ، نقرة واحدة من تنبيه يطلق للتشغيل الذي انقطع. -## مرتبط +## ذات صلة - [التقييمات](/ar/agenteye/evaluations): قيّم كل تشغيل من حيث الجودة. -- [التنبيهات](/ar/agenteye/alerts): حول أي حد إلى قاعدة استدعاء. -- [عمليات التدقيق](/ar/agenteye/audits): اترك Failproof AI Observability تجد أنماط الفشل عبر الجلسات لك. -- [واجهة سطر الأوامر والوكلاء](/ar/agenteye/cli-and-agents): نفس القابلية للمراقبة من محطتك الطرفية. \ No newline at end of file +- [التنبيهات](/ar/agenteye/alerts): حول أي عتبة إلى قاعدة استدعاء. +- [عمليات التدقيق](/ar/agenteye/audits): دع Failproof AI Observability يجد أنماط الفشل عبر الجلسات نيابة عنك. +- [واجهة سطر الأوامر والوكلاء](/ar/agenteye/cli-and-agents): نفس المراقبة من محطة الطرفية الخاصة بك. \ No newline at end of file diff --git a/docs/ar/agenteye/openclaw-capture.mdx b/docs/ar/agenteye/openclaw-capture.mdx index 091183a6..eb5366f2 100644 --- a/docs/ar/agenteye/openclaw-capture.mdx +++ b/docs/ar/agenteye/openclaw-capture.mdx @@ -1,33 +1,33 @@ --- --- title: "التقاط جلسات OpenClaw" -description: "قم بتتبع جلسات OpenClaw المحلية لفريقك في AgentEye كجلسات وأحداث عادية — دون أي تغيير في طريقة تشغيل OpenClaw." +description: "اتبع جلسات OpenClaw المحلية لفريقك في AgentEye كجلسات وأحداث عادية — دون أي تغيير في طريقة تشغيل OpenClaw." --- -إذا كان فريقك يستخدم [OpenClaw](https://docs.openclaw.ai)، فإن التقاط جلسات OpenClaw يجلب تلك الجلسات إلى AgentEye كجلسات وأحداث عادية، بحيث يمكنك البحث عنها وإعادة تشغيلها وتقييمها جنباً إلى جنب مع كل شيء آخر تلاحظه. يكمل هذا [Python SDK](/ar/agenteye/python-sdk): يقوم SDK بتطبيق أدوات على الوكلاء الذين تكتبهم، بينما هذا يلتقط عمل OpenClaw الذي يقوم به فريقك بالفعل — دون أي تغيير في طريقة تشغيله. +إذا كان فريقك يشغل [OpenClaw](https://docs.openclaw.ai)، فإن التقاط جلسات OpenClaw يجلب تلك الجلسات إلى AgentEye كجلسات وأحداث عادية، حتى تتمكن من البحث عنها وإعادة تشغيلها وتقييمها جنباً إلى جنب مع كل شيء آخر تراقبه. يكمل [Python SDK](/ar/agenteye/python-sdk): يزود SDK الوكلاء الذين تكتبهم، بينما يلتقط هذا عمل OpenClaw الذي يقوم به فريقك بالفعل — دون أي تغيير في طريقة تشغيله. -يقرأ جامع خلفية صغير نصوص جلسات OpenClaw المحلية كما تُكتب وينقلها إلى AgentEye. يعمل بنفس الطريقة التي يعمل بها [التقاط Codex](/ar/agenteye/codex-capture)، ويمكن لجامع واحد أن يلتقط كليهما في نفس الوقت. +يقرأ مجمع خلفي صغير نسخ جلسات OpenClaw المحلية كما يتم كتابتها وينقلها إلى AgentEye. يعمل بنفس الطريقة مثل [التقاط Codex](/ar/agenteye/codex-capture)، ويمكن لمجمع واحد أن يلتقط كليهما في نفس الوقت. --- -## ما الذي يتم التقاطه +## ما يتم التقاطه -يتم التقاط كل وكيل تم تكوينه في إعداد OpenClaw على جهاز ما بواسطة جامع ذلك الجهاز — لا يوجد إعداد لكل وكيل. +يتم التقاط كل وكيل مُعد في إعداد OpenClaw الخاص بالجهاز بواسطة مجمع الجهاز — لا توجد عملية إعداد لكل وكيل. -تصبح كل جلسة OpenClaw [جلسة](/ar/agenteye/sessions) في AgentEye؛ رسائل المستخدم والمساعد وعمليات الأدوات ونتائج الأدوات تصبح [الأحداث](/ar/agenteye/event-stream) المطابقة. +تصبح كل جلسة OpenClaw [جلسة](/ar/agenteye/sessions) في AgentEye؛ وتصبح رسائل المستخدم والمساعد والاستدعاءات الأداتية والنتائج المقابلة [أحداث](/ar/agenteye/event-stream). --- ## تشغيله -التقاط مطفأ حتى تقوم بتفعيله. قم بتثبيت الجامع باستخدام مفتاح API له صلاحية `events:add` (راجع [مفاتيح API](/ar/agenteye/api-keys))، وقم بتشغيل التقاط OpenClaw: +التقاط معطّل حتى تقوم بتفعيله. ثبّت المجمع بمفتاح API يحتوي على إذن `events:add` (راجع [مفاتيح API](/ar/agenteye/api-keys))، وشغّل التقاط OpenClaw: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -يقوم هذا بتثبيت الجامع وتسجيله كخدمة خلفية وبدء التقاط. تأكد من أنه يعمل: +هذا يثبت المجمع ويسجله كخدمة خلفية ويبدأ الالتقاط. تأكد من أنه يعمل: ```bash agenteye-collector health @@ -35,16 +35,16 @@ agenteye-collector health هل تلتقط أكثر من وكيل واحد على نفس الجهاز؟ أضف علم كل واحد منهم إلى نفس الأمر — على سبيل المثال `--openclaw-enabled --codex-enabled`. -عند التشغيل الأول، يتم ملء جلسات OpenClaw الموجودة لديك مرة واحدة ثم يبدأ النشاط الجديد في البث خلال ثوانٍ. لا تُقرأ ملفات OpenClaw الخاصة بها أبداً — لا تُعدَّل أو تُنقل أو تُحذف — وتُرسل كل جلسة مرة واحدة بالضبط، حتى عند إعادة التشغيل. +عند التشغيل الأول، يتم ملء جلسات OpenClaw الموجودة لديك مرة واحدة ثم تتدفق النشاطات الجديدة خلال ثوان. ملفات OpenClaw تُقرأ فقط — لا تُعدّل أو تُنقل أو تُحذف — وتُرسل كل جلسة بالضبط مرة واحدة، حتى عبر إعادة التشغيل. --- -## حيث يظهر +## حيث تظهر -تظهر الجلسات المُلتقطة في **Sessions**، وأحداثها في تدفق **Events**، تماماً مثل أي وكيل آخر تلاحظه — لذا فإن [إعادة تشغيل الجلسة](/ar/agenteye/sessions) و[البحث](/ar/agenteye/queries) و[التقييمات](/ar/agenteye/evaluations) و[التنبيهات](/ar/agenteye/alerts) تعمل جميعها عليها. قم بالتصفية حسب وكيل OpenClaw لرؤيتها بمفردها. +تظهر الجلسات المُلتقطة في **Sessions**، وأحداثها في تدفق **Events**، تماماً كما هو الحال مع أي وكيل آخر تراقبه — لذا [إعادة تشغيل الجلسة](/ar/agenteye/sessions) و[البحث](/ar/agenteye/queries) و[التقييمات](/ar/agenteye/evaluations) و[التنبيهات](/ar/agenteye/alerts) جميعها تعمل عليها. صفّ حسب وكيل OpenClaw لمشاهدتها بمفردها. --- ## الخصوصية -تحتوي نصوص OpenClaw على الجلسة الكاملة — بما في ذلك مخرجات الأوامر ومحتويات الملفات وأي شيء قرأه الوكيل أو كتبه — وقد تحتوي على أسرار. يتم شحن الجلسات المُلتقطة كما هي، لذا قم بتفعيل التقاط فقط على الأجهزة والفرق حيث يكون من المناسب مركزية هذا المحتوى في AgentEye، وأعط الجامع مفتاحاً محدوداً بـ `events:add` فقط. راجع [Security](/ar/agenteye/security) لمعرفة كيفية حفاظ نظامك على بيانات معزولة. \ No newline at end of file +تحتوي نسخ OpenClaw على الجلسة الكاملة — بما في ذلك مخرجات الأوامر ومحتويات الملفات وأي شيء قرأه الوكيل أو كتبه — ويمكن أن تحتوي على أسرار. تُرسل الجلسات المُلتقطة كما هي، لذا فعّل الالتقاط فقط على الأجهزة والفرق حيث يكون تجميع هذا المحتوى في AgentEye مناسباً، وأعطِ المجمع مفتاحاً مقتصراً على `events:add` فقط. راجع [الأمان](/ar/agenteye/security) لمعرفة كيفية الحفاظ على عزل بيانك. \ No newline at end of file diff --git a/docs/ar/agenteye/overview.mdx b/docs/ar/agenteye/overview.mdx index 5ba3aa5b..1ea9a857 100644 --- a/docs/ar/agenteye/overview.mdx +++ b/docs/ar/agenteye/overview.mdx @@ -1,24 +1,24 @@ --- --- -title: "Failproof AI: مراقبة الوكلاء بحثاً عن الأعطال" -description: "Failproof AI Observability هي منصة ذاتية الاستضافة لمراقبة وتقييم وتحسين وكلائك الذكيين في بيئة الإنتاج." +title: "Failproof AI: مراقبة الوكلاء للكشف عن الأخطاء" +description: "Failproof AI Observability منصة ذاتية الاستضافة لمراقبة وتقييم وتحسين وكلائك الذكيين في بيئة الإنتاج." --- -Failproof AI Observability هي منصة ذاتية الاستضافة لمراقبة وتقييم وتحسين وكلائك الذكيين في بيئة الإنتاج. تسجل كل شيء يفعله وكلاؤك (كل استدعاء أداة، طلب نموذج، hook، وخطأ)، وتقيّم جودة كل تشغيل، وتكشف الأعطال التي لم تكن تعرف أنك بحاجة للبحث عنها، كل ذلك في لوحة تعمل داخل بنيتك التحتية الخاصة. +Failproof AI Observability منصة ذاتية الاستضافة لمراقبة وتقييم وتحسين وكلائك الذكيين في بيئة الإنتاج. تسجل كل ما يفعله وكلاؤك (كل استدعاء أداة، وطلب نموذج، وخطاف، وخطأ)، وتقيّم جودة كل تشغيل، وتسلط الضوء على الأخطاء التي لم تكن تعرف أنه يجب البحث عنها، كل ذلك في لوحة تحكم تعمل داخل البنية الأساسية الخاصة بك. -إذا كنت تطلق وكلاء ذكيين وتعبت من التخمين حول سبب فشل التشغيل، فهذه هي الصفحة المناسبة للبدء. تشرح ما يقدمه Failproof AI Observability وكيف تتناسب الأجزاء معاً، قبل تثبيت أي شيء. +إذا كنت تطلق وكلاء ذكيين وتعبت من التخمين حول سبب فشل التشغيل، فهذه هي الصفحة التي يجب أن تبدأ منها. تشرح ما يوفره Failproof AI Observability وكيف تتناسب الأجزاء معاً، قبل أن تثبت أي شيء. -> **Failproof AI Observability هو منتج للمؤسسات من Failproof AI.** هل تريد رؤيته قيد التشغيل؟ اطلب عرضاً توضيحياً: أرسل بريداً إلى [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +> **Failproof AI Observability منتج موجه للمؤسسات من Failproof AI.** هل تريد رؤيته أثناء العمل؟ اطلب عرضاً توضيحياً: أرسل بريداً إلى [nikita@befailproof.ai](mailto:nikita@befailproof.ai). -![جلسة Failproof AI Observability مرسومة كرسم بياني تنفيذي بنمط git بجانب جدول الأحداث الخاص بها، مع تفصيل لكل تشغيل للأدوات والنماذج والـ hooks في العمود الأيمن](/agenteye/images/session-detail.png) +![جلسة Failproof AI Observability مرسومة كرسم بياني للتنفيذ بأسلوب git بجانب الخط الزمني للأحداث، مع تفصيل لكل تشغيل للأدوات والنماذج والخطافات في الشريط الأيمن](/agenteye/images/session-detail.png) -*يتم رسم كل تشغيل وكيل كرسم بياني تنفيذي بنمط git (على اليسار) بجانب جدول الأحداث الخاص به. يحصل كل وكيل فرعي متوازي على خطه الخاص؛ يقدم العمود الأيمن تفصيلاً للأدوات والنماذج والـ hooks واستهلاك الرموز للتشغيل.* +*كل تشغيل للوكيل يتم رسمه كرسم بياني للتنفيذ بأسلوب git (اليسار) بجانب الخط الزمني للأحداث. يحصل كل وكيل فرعي متوازي على حارته الخاصة؛ الشريط الأيمن يفصل الأدوات والنماذج والخطافات ونفقات الرموز للتشغيل.* --- -## شاهده قيد التشغيل +## شاهده أثناء العمل -يعرض فيديان قصيران الشيئين اللذين تسعى الفرق للوصول إليهما أولاً: تتبع التشغيل والعثور على الأعطال تلقائياً. +تعرض فيديوهان قصيران الشيئين اللذين تلجأ إليهما الفريق أولاً: تتبع التشغيل والعثور على الأخطاء تلقائياً.
@@ -30,79 +30,79 @@ Failproof AI Observability هي منصة ذاتية الاستضافة لمرا
-*Failproof Audit: اترك Failproof AI Observability تُنقِّب عن السجلات عبر الجلسات وأخبرك بما يجب إصلاحه.* +*Failproof Audit: دع Failproof AI Observability تستخرج بيانات السجلات عبر الجلسات وتخبرك بما يجب إصلاحه.* --- -## لماذا تستخدمه الفرق +## لماذا تستخدمه الفريق -- **شاهد ما فعله وكيلك فعلاً.** كل تشغيل يصبح رسم بياني تنفيذي قابلاً للقراءة بنمط git: أي الأدوات تعمل بالتوازي، أي الوكلاء الفرعيين انقسموا، أين توقفت، وما الذي أنفقته. -- **اكتشف انحدارات الجودة تلقائياً.** اربط خدمة تقييم صغيرة و Failproof AI Observability ستقيّم كل تشغيل منتهٍ، بحيث ينعكس انخفاض الفائدة أو ارتفاع الهلوسة بنفسه. -- **اعثر على أعطال لم تكتب لها قاعدة.** تعمل عمليات التدقيق المتكررة على تنقيب السجلات عبر الجلسات بحثاً عن مجموعات الأخطاء ونقاط الكمون الشاذة والنتائج المنخفضة والتشغيلات المعلقة، ثم تسلمك النتائج المرتبة والمدعومة بالأدلة. -- **احصل على تنبيه عند أهمية ذلك.** تطلق قواعد الحد الأدنى على معدل الخطأ والكمون والتكلفة أو نقاط المقيّم وتفتح حوادث يمكنك الإقرار بها وتعيينها وحلها. -- **اطرح أسئلة باللغة الإنجليزية العادية.** يجيب مساعد ذكي داخل لوحة التحكم على سؤال مثل كيف تتجه الجودة في الإنتاج هذا الأسبوع على بيانات الخاصة بك. أي تغيير يقوم به يخضع لموافقة. -- **احتفظ ببيانات الخاص بك.** Failproof AI Observability ذاتية الاستضافة: تبقى الأحداث والتوجيهات والتحليلات في البنية التحتية التي تتحكم فيها. +- **انظر إلى ما فعله وكيلك فعلاً.** كل تشغيل يصبح رسم بياني تنفيذ قابلاً للقراءة بأسلوب git: أي الأدوات تعمل بالتوازي، وأي الوكلاء الفرعيين تفرعوا، حيث توقف، وماذا أنفق. +- **اكتشف انحدارات الجودة تلقائياً.** قم بتوصيل خدمة تسجيل صغيرة وسيقيّم Failproof AI Observability كل تشغيل منتهي، حتى ينخفض المساعدة أو يرتفع الهلوسات بمفردها. +- **ابحث عن أخطاء لم تكتب قاعدة لها.** تعمل التدقيقات المتكررة على استخراج السجلات عبر الجلسات للبحث عن مجموعات الأخطاء والقيم الشاذة في الكمون والنتائج المنخفضة والتشغيلات العالقة، ثم تعطيك النتائج المرتبة والمدعومة بالأدلة. +- **احصل على إشعارات عندما يكون مهماً.** تطلق قواعد الحد الأدنى على معدل الخطأ والكمون والتكلفة أو نتائج المقيّم وتفتح حوادث يمكنك الاعتراف بها وتعيينها وحلها. +- **اطرح أسئلة باللغة الإنجليزية العادية.** يجيب مساعد ذكي في لوحة التحكم على أسئلة مثل "كيف تتجه الجودة في الإنتاج هذا الأسبوع؟" على بياناتك الخاصة. أي تغيير يجريه يمر عبر بوابة الموافقة. +- **احتفظ ببياناتك.** Failproof AI Observability ذاتي الاستضافة: الأحداث والمطالبات والتحليلات تبقى في البنية الأساسية التي تتحكم بها. --- ## ما تحصل عليه -يتم تنظيم Failproof AI Observability حول ثلاث أفكار (**المراقبة** و**التحليل** و**الإدارة**)، مما يعكس الشريط الجانبي الأيسر للوحة التحكم. +يتم تنظيم Failproof AI Observability حول ثلاث أفكار (**مراقبة** و**تحليل** و**إدارة**)، معكوسة في الشريط الجانبي الأيسر من لوحة التحكم. -**المراقبة** (الحقيقة الخام لما حدث): +**مراقبة** (الحقيقة الخام لما حدث): -- **[تدفق الأحداث](/ar/agenteye/event-stream)**: مسار الحي، لكل خطوة، لكل تشغيل (استدعاءات أدوات، استدعاءات نموذج، hooks، أخطاء). -- **[الجلسات](/ar/agenteye/sessions)**: تلك الأحداث المجمعة في صف واحد لكل تشغيل، كل منها جاهز للتقييم، مع رسم بياني تنفيذي بنمط git. -- **[مقاييس الأداء](/ar/agenteye/telemetry)**: خرائط حرارية للكمون لكل سطح و p50/p95/p99 الحيويات للنماذج والأدوات والـ hooks، بحيث تبرز قمة الذيل عن الوسيط. -- **[تتبع الأخطاء](/ar/agenteye/error-tracking)**: سطح فحص واحد لكل شيء خاطئ، نقرة واحدة من تنبيه حار. +- **[تدفق الأحداث](/ar/agenteye/event-stream)**: المسار المباشر خطوة بخطوة لكل تشغيل (استدعاءات الأدوات واستدعاءات النموذج والخطافات والأخطاء). +- **[الجلسات](/ar/agenteye/sessions)**: تلك الأحداث المجمعة في صف واحد لكل تشغيل، كل منها جاهز ليتم تقييمه، مع رسم بياني تنفيذي بأسلوب git. +- **[مقاييس الأداء](/ar/agenteye/telemetry)**: خرائط حرارية للكمون لكل سطح وإحصائيات p50/p95/p99 الحيوية للنماذج والأدوات والخطافات، حتى يبرز ارتفاع الذيل من الوسيط. +- **[تتبع الأخطاء](/ar/agenteye/error-tracking)**: سطح فرز واحد لكل ما حدث خطأ، بنقرة واحدة من تنبيه الحريق. -![صفحة الملاحظات للأدوات: خريطة حرارية للكمون، وشريط حدود النسبة المئوية، وشريط توزيع الأدوات على 24 صندوق زمني](/agenteye/images/tools.png) +![صفحة مراقبة الأدوات: خريطة حرارية للكمون وفرقة النسبة المئوية وشريط توزيع الأدوات على 24 صندوق زمني](/agenteye/images/tools.png) -*يجمع كل سطح ملاحظات بين خط رقيق و p50/p95/p99 الحيويات مع خريطة حرارية للكمون وشريط حدود النسبة المئوية. معروض هنا: الأدوات.* +*يقترن كل سطح مراقبة بخط بياني ومقاييس حيوية p50/p95/p99 مع خريطة حرارية للكمون وفرقة نسبة مئوية. موضح هنا: الأدوات.* -**التحليل** (تحويل النشاط إلى إجابات): +**تحليل** (تحويل النشاط إلى إجابات): -- **[الاستعلامات](/ar/agenteye/queries)** و**[لوحات التحكم](/ar/agenteye/dashboards)**: SQL المحفوظة على أحداثك والتقييمات الخاصة بك، المرسومة في لوحات تحكم مشتركة ومحدودة بالمنظمة. -- **[التقييمات](/ar/agenteye/evaluations)**: نقاط الجودة التي ينتجها خدمة المقيّم الخاصة بك، مع الأسباب لكل نقطة. -- **[عمليات التدقيق](/ar/agenteye/audits)**: تحقيقات متكررة تكشف أنماط الأعطال عبر الجلسات. -- **[التنبيهات](/ar/agenteye/alerts)** و**[الحوادث](/ar/agenteye/incidents)**: قواعد الحد الأدنى التي تنبهك، بالإضافة إلى سير عمل الحادثة لفحصها. +- **[الاستعلامات](/ar/agenteye/queries)** و**[لوحات التحكم](/ar/agenteye/dashboards)**: SQL محفوظ عبر الأحداث والتقييمات، مرسومة في لوحات تحكم مشتركة وموجهة للمنظمة. +- **[التقييمات](/ar/agenteye/evaluations)**: درجات الجودة التي ينتجها خدمة المقيّم الخاصة بك، مع التفكير لكل درجة. +- **[التدقيقات](/ar/agenteye/audits)**: تحقيقات متكررة تسلط الضوء على أنماط الفشل عبر الجلسات. +- **[التنبيهات](/ar/agenteye/alerts)** و**[الحوادث](/ar/agenteye/incidents)**: قواعد حدود تنبهك، بالإضافة إلى سير عمل الحادث لتصنيفها. -**الواجهات** (الوصول إلى بيانات الخاصة بك بطريقتك): +**الواجهات** (الوصول إلى البيانات بطريقتك): -- **[واجهة سطر الأوامر](/ar/agenteye/cli-and-agents)**: قيادة نشرك الكامل من الطرفية أو نص، والسماح لوكيل البرمجة بفعل ذلك باللغة الإنجليزية العادية. -- **[المساعد الذكي](/ar/agenteye/assistant)**: اطرح أسئلة حول وكلائك باللغة الإنجليزية العادية، مباشرة داخل لوحة التحكم. -- **REST API**: كل ما تفعله لوحة التحكم والـ CLI يدعمه REST API يمكنك استدعاؤه مباشرة باستخدام [مفتاح API](/ar/agenteye/api-keys) محدود النطاق — ابتلع الأحداث، استعلم عن الجلسات والتقييمات، وأدر لوحات التحكم والتنبيهات وعمليات التدقيق والمستخدمين والمفاتيح، حتى تتمكن من دمج Failproof AI Observability في أدواتك الخاصة. +- **[CLI](/ar/agenteye/cli-and-agents)**: قيادة نشرك بالكامل من المحطة الطرفية أو السكريبت، واترك وكيل الترميز يفعل ذلك بلغة إنجليزية عادية. +- **[مساعد ذكي](/ar/agenteye/assistant)**: اطرح أسئلة حول وكلائك بلغة إنجليزية عادية، مباشرة داخل لوحة التحكم. +- **REST API**: كل ما تفعله لوحة التحكم و CLI يتم دعمه بواسطة REST API يمكنك استدعاؤه مباشرة باستخدام [مفتاح API](/ar/agenteye/api-keys) محدود النطاق — استقبل الأحداث واستعلم عن الجلسات والتقييمات وأدر لوحات التحكم والتنبيهات والتدقيقات والمستخدمين والمفاتيح، حتى تتمكن من دمج Failproof AI Observability في أدواتك الخاصة. **الإدارة** (قم بتشغيله لفريقك): -- **[مفاتيح API](/ar/agenteye/api-keys)**: رموز محدودة النطاق لجامع البيانات ولوحة التحكم والمساعد. -- **المستخدمون**: تسجيل الدخول بدون كلمة مرور على أساس البريد الإلكتروني مع قائمة بيضاء. +- **[مفاتيح API](/ar/agenteye/api-keys)**: رموز محدودة النطاق للمجمع ولوحة التحكم والمساعد. +- **المستخدمون**: تسجيل دخول بدون كلمة مرور وقائم على البريد الإلكتروني مع قائمة مسموحة. - **الإعدادات**: تكوين لكل منظمة، بما في ذلك تجاوزات نافذة السياق للنموذج. --- -## كيف تناسب الأجزاء معاً +## كيف تتناسب الأجزاء -تتدفق البيانات في اتجاه واحد، من رمز الوكيل الخاص بك إلى لوحة التحكم: وكيلك (عبر Python SDK) ينبعث أحداثاً إلى agenteye-collector، التي تشحنها إلى الخادم، التي تخدم لوحة التحكم. خدمتان اختياريتان تكملان الصورة — خدمة تقييم (التقييمات) وخدمة مساعد ذكي (الدردشة داخل لوحة التحكم). +تتدفق البيانات في اتجاه واحد، من كود الوكيل الخاص بك إلى لوحة التحكم: يصدر الوكيل الخاص بك (عبر Python SDK) أحداثاً إلى agenteye-collector، الذي يرسلها إلى الخادم، الذي يخدم لوحة التحكم. تجتمع خدمتان اختياريتان — خدمة التسجيل (التقييمات) وخدمة المساعد الذكي (الدردشة داخل لوحة التحكم). -- **Python SDK**: تضيف عدة استدعاءات `agenteye.event.*` إلى وكيلك؛ يتم تخزين الأحداث مؤقتاً محلياً. -- **agenteye-collector**: خيط خفيف على كل جهاز وكيل يجمع الأحداث ويشحنها إلى الخادم. -- **الخادم**: يستقبل أحداثك، يحتفظ بحالة التشغيل في قواعد البيانات الخاصة بك، ويخدم REST API الذي تستخدمه لوحة التحكم والـ CLI والتكاملات الخاصة بك. +- **Python SDK**: تضيف بعض استدعاءات `agenteye.event.*` إلى وكيلك؛ يتم تخزين الأحداث محلياً مؤقتاً. +- **agenteye-collector**: عملية خفيفة على كل جهاز وكيل تجمع الأحداث وترسلها إلى الخادم. +- **الخادم**: يستقبل أحداثك ويحتفظ بالحالة التشغيلية في قواعد البيانات الخاصة بك ويخدم REST API الذي تستخدمه لوحة التحكم و CLI والتكاملات الخاصة بك. - **لوحة التحكم**: حيث تستكشف كل شيء. -- **الخدمات الاختيارية**: خدمة تقييم (التقييمات)، وخدمة مساعد ذكي (الدردشة داخل لوحة التحكم). +- **الخدمات الاختيارية**: خدمة تسجيل (التقييمات)، وخدمة مساعد ذكي (الدردشة داخل لوحة التحكم). -للمفردات المستخدمة في جميع أنحاء المستندات (*event و session و evaluation و audit و finding و incident*)، انظر [المفاهيم](/ar/agenteye/concepts). +للمفردات المستخدمة في جميع أنحاء الوثائق (*event, session, evaluation, audit, finding, incident*)، انظر إلى [المفاهيم](/ar/agenteye/concepts). --- ## الحصول على Failproof AI Observability -Failproof AI Observability هو منتج للمؤسسات من Failproof AI، ويعمل جنباً إلى جنب مع Failproof AI Enforcement — منتج السياسة والحواجز الوقائية — تحت علامة Failproof AI. يعمل بالكامل في بيئتك الخاصة. إذا لم يكن لديك حق الوصول إلى الحزم بعد، اطلب عرضاً توضيحياً وسنحضرك للإعداد: أرسل بريداً إلى [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Failproof AI Observability منتج موجه للمؤسسات من Failproof AI، ويعمل جنباً إلى جنب مع Failproof AI Enforcement — منتج السياسات والحواجز الوقائية — تحت علامة Failproof AI التجارية. يعمل بالكامل في بيئتك الخاصة. إذا لم يكن لديك إمكانية الوصول إلى الحزم حتى الآن، فاطلب عرضاً توضيحياً وسنرتب لك: أرسل بريداً إلى [nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- ## الخطوات التالية - [المفاهيم](/ar/agenteye/concepts): مفردات Failproof AI Observability في مكان واحد. -- [الملاحظة](/ar/agenteye/observability): تابع ما يفعله وكلاؤك، تشغيل تلو الآخر. -- [الأمان](/ar/agenteye/security): كيف يحتفظ Failproof AI Observability ببيانات الخاصة بك معزولة وتحت سيطرتك. \ No newline at end of file +- [الملاحظة](/ar/agenteye/observability): تابع ما يفعله وكلاؤك، تشغيلاً تلو الآخر. +- [الأمان](/ar/agenteye/security): كيف يحافظ Failproof AI Observability على عزل بياناتك والتحكم فيها. \ No newline at end of file diff --git a/docs/ar/agenteye/python-sdk-skill.mdx b/docs/ar/agenteye/python-sdk-skill.mdx index e61c8734..50025068 100644 --- a/docs/ar/agenteye/python-sdk-skill.mdx +++ b/docs/ar/agenteye/python-sdk-skill.mdx @@ -1,129 +1,131 @@ --- -title: "مهارة Failproof AI Observability Python SDK للعامل" -description: "انتقل من عامل بدون أدوات مراقبة إلى أحداث يمكنك رؤيتها، حيث يعثر عاملك البرمجي على نقاط الأدوات، ويكتبها، ويثبت أنها عملت بنجاح." +--- +title: "مهارة Failproof AI Observability Python SDK للوكيل" +description: "انتقل من وكيل بدون أدوات مراقبة إلى أحداث يمكنك رؤيتها، مع قيام وكيل الترميز الخاص بك بالعثور على نقاط الأدوات، وكتابتها، وإثبات وصولها." --- -أخبر عاملك البرمجي *"أضف Failproof AI Observability إلى هذا العامل"* واتركه يقرأ حلقتك، ويعرّف مكان إضافة الأدوات، ويكتبها، ويتحقق من الأحداث قبل إكمال المهمة. +أخبر وكيل الترميز الخاص بك *"أضف Failproof AI Observability إلى هذا الوكيل"* واتركه يقرأ حلقتك، ويعمل على معرفة مكان وضع الأدوات، وكتابتها، والتحقق من الأحداث قبل أن ينهي المهمة. -**مهارة Python SDK** (`agenteye-python-sdk`) هي *مهارة عامل*: مجلد يحتوي على تعليمات يحملها عامل برمجي مثل Claude Code أو Codex عند الحاجة عندما تطابق المهمة. تعلم العامل كيفية استخدام [Python SDK](/ar/agenteye/python-sdk) — لا تعتبر مكتبة، وليس لها أي تأثير على طريقة عمل SDK. +**مهارة Python SDK** (`agenteye-python-sdk`) هي *Agent Skill*: مجلد من التعليمات يقوم وكيل ترميز مثل Claude Code أو Codex بتحميله عند الطلب عندما تطابق مهمة ما. تعلم الوكيل استخدام [Python SDK](/ar/agenteye/python-sdk) — إنها ليست مكتبة، ولا تغير أي شيء حول كيفية عمل SDK. -## الأدوات سهلة الكتابة وسهل الخطأ فيها بهدوء +## الأدوات من السهل كتابتها وسهل الحصول على أخطاء هادئة -SDK صغير: ثلاثة عشر طريقة حدث، جميعها بكلمات مفتاحية فقط. يمكن لعامل برمجي قراءة مرجع [Python SDK](/ar/agenteye/python-sdk) وإنتاج أدوات معقولة في دقيقة واحدة. +SDK صغيرة: ثلاثة عشر طريقة للأحداث، كلها keyword-only. يمكن لوكيل ترميز أن يقرأ مرجع [Python SDK](/ar/agenteye/python-sdk) وينتج أدوات معقولة في دقيقة واحدة. -المشكلة هي أن SDK هذا لا يرفع استثناءً عند الخطأ، والأدوات الخاطئة تبدو تماماً مثل الأدوات الصحيحة حتى يفتح أحدهم لوحة التحكم ويجدها فارغة. الأخطاء التي تستهلك وقتاً حقيقياً كلها صمتية: +المشكلة أن هذا SDK لا يرفع عندما تخطئ، والأدوات الخاطئة تبدو تماماً مثل الأدوات الصحيحة حتى يفتح شخص ما لوحة تحكم ويجدها فارغة. الأخطاء التي تستغرق وقتاً حقيقياً هي جميعها صمت: | الخطأ | ما تراه | |---|---| -| لا يوجد `agent_start` | كل حدث يهبط. صفر جلسات. | -| لم يتم تعيين البيئة أبداً | كل شيء يعمل، مرفوع ضمن `dev`. | -| `outcome="failure"` | يظهر التشغيل أخضر — فقط `failed`, `error`, `timeout`, `rejected` يتم عدها. | -| اسم حقل به خطأ إملائي | مقبول ومخزن كحقل جديد. | -| أحداث انبعثت من مجموعة خيوط | تم حذفها بهدوء. | +| لا `agent_start` | كل حدث يصل. جلسات صفرية. | +| لم يتم تعيين البيئة | كل شيء يعمل، مدرج تحت `dev`. | +| `outcome="failure"` | المسار يظهر أخضر — فقط `failed`، `error`، `timeout`، `rejected` تعتبر. | +| اسم حقل خاطئ | قبول وتخزين كحقل جديد. | +| الأحداث المرسلة من مجموعة خيوط | تم حذفها بصمت. | -لا أحد منهم يرفع استثناءً. لا أحد يظهر في الاختبارات. كل واحد منهم في المهارة، موضح كعقد مع الفحص الذي يكتشفه. +لا أحد من هذه يرفع. لا تظهر في الاختبارات. كل واحد منها موجود في المهارة، مذكور كعقد مع الفحص الذي يمسكه. -## ما تفعله، بالترتيب +## ما تفعله بالترتيب -تنفذ المهارة نفس الخطوات الثلاث التي سيتخذها مهندس حذر: +المهارة تتبع نفس الخطوات الثلاث التي سيتخذها المهندس الحذر: -1. **التخطيط.** تقرأ حلقة العامل لديك وتطرح السؤالين الذين يمكن لك وحدك الإجابة عليهما: ما الذي يعتبر تشغيلاً واحداً (`session_id`)، وَمَن الممثلون المختلفون (`agent_id`). تحصل على الموافقة قبل كتابة الكود، لأن تغييرهما لاحقاً يقسم السجل ويكسر الاتجاهات. -2. **الكتابة.** تربط الهوية مرة واحدة لكل تشغيل بدلاً من تمريرها عبر كل موقع استدعاء، وتختار شكلاً آمناً للتزامن — تفصيل مهم، لأن الاختصار الواضح يمزج بهدوء تشغيلين متداخلين في جلسة واحدة. -3. **التحقق.** تشغل عاملك وتقرأ ملفات الأحداث الناتجة، تتحقق من وجود `agent_start`، والبيئة صحيحة، وتشغيل واحد ينتج جلسة واحدة. +1. **التخطيط.** تقرأ حلقة وكيلك وتطرح السؤالين الذي يمكن فقط أنت الإجابة عليهما: ما الذي يعتبر تشغيلاً واحداً (معرّف `session_id` الخاص بك)، ومن الممثلون القابلون للتمييز (معرّف `agent_id` الخاص بك). تحصل على الاتفاق قبل كتابة الكود، لأن تغييرهما لاحقاً يقسم التاريخ ويكسر الاتجاهات. +2. **الكتابة.** تربط الهوية مرة واحدة لكل تشغيل بدلاً من تمريرها عبر كل موقع استدعاء، وتختار شكلاً آمناً للتزامن — تفصيل مهم، لأن الاختصار الواضح يمزج بصمت تشغيلين متداخلين في جلسة واحدة. +3. **التحقق.** تشغل وكيلك وتقرأ ملفات الأحداث الناتجة، للتحقق من وجود `agent_start`، صحة البيئة، وأن تشغيلاً واحداً أنتج جلسة واحدة. -تلك الخطوة الثالثة هي التي يتخطاها الناس. SDK يكتب الأحداث في ملفات محلية، لذلك يمكن إثبات تكامل كامل على جهاز محمول بدون خادم، بدون مفتاح API، وبدون شبكة — وهذا بالضبط السبب في إصرار المهارة على القيام به. +تلك الخطوة الثالثة هي التي يتخطاها الناس. SDK تكتب الأحداث إلى ملفات محلية، لذا يمكن إثبات تكامل كامل على جهاز محمول بدون خادم، بدون مفتاح API، بدون شبكة — وهذا بالضبط السبب في أن المهارة تصر على القيام بها. -## كيفية ارتباطها بالمهارات الأخرى +## كيف تتعلق بالمهارات الأخرى -ثلاث مهارات، تقسيم نظيف واحد: +ثلاث مهارات، انقسام نظيف: -| المهارة | استخدمها عندما | ما الذي تلمسه | +| المهارة | استخدمها عندما | ما تلمسه | |---|---|---| -| **مهارة Python SDK** (هذه الصفحة) | تريد من عاملك أن *ينبعث* من بيانات المراقبة — "أضف المراقبة"، "لماذا لا يظهر عاملي؟" | تكتب الكود في مستودع عاملك. لا تقرأ أي شيء. | -| **[مهارة المُقيّم](/ar/agenteye/evaluator-skill)** | تريد *تصنيف* التشغيلات — "ما الذي يجب أن نقيسه حتى؟" | تكتب الكود في مستودعك؛ تقرأ بيانات المراقبة | -| **[مهارة CLI](/ar/agenteye/cli-skill)** | تريد *قراءة* ما حدث، أو تشغيل نشرك | تقود CLI كما أنت، بما في ذلك التغييرات | +| **مهارة Python SDK** (هذه الصفحة) | تريد من وكيلك أن يصدر قياسات التلمترا — "أضف قابلية الرصد"، "لماذا لا يظهر وكيلي؟" | تكتب الكود في مستودع وكيلك. لا تقرأ شيء. | +| **[مهارة المُقيّم](/ar/agenteye/evaluator-skill)** | تريد **تقييم** التشغيلات — "ماذا يجب أن نقيس حتى؟" | تكتب الكود في مستودعك؛ تقرأ القياس | +| **[مهارة CLI](/ar/agenteye/cli-skill)** | تريد **قراءة** ما حدث، أو تشغيل نشرك | تقود CLI كأنك أنت، بما في ذلك التغييرات | -تمرر بهذا الترتيب: هذه المهارة تجعل الأحداث تتدفق، يقيّمها المُقيّم، CLI يقرأها مرة أخرى. لا يوجد شيء لتقييمه ولا شيء لقراءته حتى يصدر عاملك جلسات، لذا إذا كنت تبدأ من الصفر، ابدأ هنا. +تسليمها بهذا الترتيب: هذه المهارة تجعل الأحداث تتدفق، والمُقيّم يسجلها، CLI يقرأها مرة أخرى. لا شيء لتقييمه ولا شيء لقراءته حتى يصدر وكيلك جلسات، لذا إذا كنت تبدأ من الصفر، ابدأ هنا. ## المتطلبات الأساسية -1. **Python 3.10+** ومستودع الكود للعامل الذي تريد إضافة أدوات له. -2. **SDK.** يتم توزيعه للعملاء كعجلة خاصة بدلاً من فهرس عام — يشرح الإعداد الخاص بك كيفية الحصول عليها وتثبيتها. تعرف المهارة مسار التثبيت وستطلب منك بدلاً من التخمين إذا لم تجده. -3. **لا شيء آخر.** لا يوجد تسجيل دخول لوحة التحكم، لا مفتاح API، لا شبكة. تتحقق المهارة من ملفات الأحداث التي يكتبها SDK، لذلك يمكنها الإنهاء والإثبات بدون اتصال. +1. **Python 3.10+** وقاعدة أكواد الوكيل التي تريد أن تُدرج فيها أدوات المراقبة. +2. **SDK.** يتم توزيعها للعملاء كعجلة خاصة بدلاً من فهرس عام — يغطي الإعداد الخاص بك كيفية الحصول عليها وتثبيتها. المهارة تعرف مسار التثبيت وستسأل بدلاً من التخمين إذا لم تتمكن من إيجادها. +3. **لا شيء آخر.** لا تسجيل دخول لوحة التحكم، لا مفتاح API، لا شبكة. المهارة تتحقق من ملفات الأحداث التي يكتبها SDK، لذا يمكنها الانتهاء وإثبات عملها بدون اتصال. -## أين تجده +## أين تحصل عليها -تعيش المهارة في مجموعة [`FailproofAI/skills`](https://github.com/FailproofAI/skills) العامة: +المهارة موجودة في مجموعة [`FailproofAI/skills`](https://github.com/FailproofAI/skills) العام: ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -أضف `-g` لتثبيتها في كل مشروع بدلاً من المشروع الحالي فقط، و`--copy` إذا كانت بيئتك لا تتبع الروابط الرمزية. بالنسبة لـ Codex، مرر `-a codex`. +أضف `-g` لتثبيتها لكل مشروع بدلاً من المشروع الحالي فقط، و`--copy` إذا كانت بيئتك لا تتبع الرموز الرمزية. بالنسبة إلى Codex، مرّر `-a codex`. -## تثبيتها يدوياً +## تثبيتها يدويًا -مهارات العامل عبارة عن مجلدات تحتوي على `SKILL.md` بالإضافة إلى مراجع. إذا كنت تفضل عدم استخدام المثبت: +Agent Skills عبارة عن مجلدات تحتوي على `SKILL.md` وإضافات. إذا فضلت عدم استخدام المثبت: -- **Claude Code**: انسخ مجلد `agenteye-python-sdk/` إلى `~/.claude/skills/` (كل مشروع) أو `/.claude/skills/` (هذا المستودع فقط). يكتشفه Claude Code تلقائياً — تحقق من قائمة `/skills`، أو ببساطة اطلب شيئاً يطابقه. -- **Codex**: يقرأ Codex نفس `SKILL.md`. يعيّن `agents/openai.yaml` المدرج `allow_implicit_invocation: true`، لذا يتم تحديده تلقائياً عند مطابقة المهمة؛ وإلا استدعه كـ `$agenteye-python-sdk`. +- **Claude Code**: انسخ مجلد `agenteye-python-sdk/` إلى `~/.claude/skills/` (كل مشروع) أو `/.claude/skills/` (هذا المستودع فقط). يكتشفه Claude Code تلقائياً — تحقق من قائمة `/skills`، أو فقط اطلب شيئاً يطابقه. +- **Codex**: يقرأ Codex نفس `SKILL.md`. يضبط `agents/openai.yaml` المجموعة `allow_implicit_invocation: true`، لذا يتم اختياره تلقائياً عند مطابقة مهمة؛ وإلا استدعه باسم `$agenteye-python-sdk`. -شغّل عاملك **في المستودع الذي يحتوي على الكود الذي تريد إضافة أدوات له** — تقرأ المهارة حلقة عاملك قبل أن تقترح أي شيء. +شغّل وكيلك **في المستودع الذي يحتوي على الكود الذي تريد إدراج أدوات فيه** — تقرأ المهارة حلقة وكيلك قبل أن تقترح أي شيء. -## شكل الجلسة +## كيف تبدو الجلسة ```text -you ▸ أضف Failproof AI Observability إلى هذا العامل. +أنت ▸ أضف Failproof AI Observability إلى هذا الوكيل. -agent ▸ اقرأ حلقتك — موزع أدوات واحد في tools.py، غلاف Anthropic +الوكيل ▸ قراءة حلقتك — موزع أداة واحد في tools.py، غلاف Anthropic واحد في llm.py. سؤالان قبل أن أكتب أي شيء. - ما الذي يعتبر تشغيلاً واحداً؟ تتعامل مع الطلبات بالتزامن، لذلك سأستخدم - معرّف الطلب الذي لديك بالفعل في ctx.request_id — ثم جلسة هنا - وطلب في سجلاتك هما نفس السلسلة. + ما الذي يعتبر تشغيلاً واحداً؟ أنت تتعامل مع الطلبات بالتزامن، لذا أود + استخدام معرف الطلب الذي لديك بالفعل في ctx.request_id — ثم جلسة + هنا والطلب في السجلات هما نفس السلسلة. - ومَن الممثلون؟ أرى مسار مخطط ومسار باحث. صنّفهما بشكل منفصل، - أم هو عامل واحد بالنسبة لك؟ + ومن هم الممثلون؟ أرى مسار مُخطط ومسار باحث. + هل تصنفهما بشكل منفصل، أم هذا وكيل واحد لديك؟ -you ▸ معرّف الطلب صحيح. إنهما عامل واحد، سمّه "مساعد". +أنت ▸ معرف الطلب صحيح. إنهما وكيل واحد، اطلب عليه "assistant". -agent ▸ تم. لفّ الموزع وعميل LLM؛ يضع agent_start و - agent_end أقواس handle_request، بما في ذلك مسار الخطأ. استخدمت - سياق محلي للهوية — يشغل موزعك الأدوات في مجموعة خيوط، - والنهج الأبسط كان سيمزج التشغيلات المتزامنة في جلسة واحدة بدون شكوى. +الوكيل ▸ تم. لقد لفت الموزع وعميل LLM؛ agent_start و + agent_end يضعان قوسين حول handle_request، بما في ذلك مسار الخطأ. استخدم + context-local للهوية — موزعك يشغل الأدوات في مجموعة خيوط، والطريقة الأبسط + كانت ستمزج التشغيلات المتزامنة في جلسة واحدة بدون تحذير. - تحقق من تشغيل حقيقي: 11 حدث عبر 4 ملفات — - agent_start, model_request/response, tool_use/tool_result x3, - agent_end (outcome=success). environment=production, جلسة واحدة - لكل طلب، المدد المقترنة. + تم التحقق من تشغيل فعلي: 11 حدثاً عبر 4 ملفات — + agent_start، model_request/response، tool_use/tool_result x3، + agent_end (outcome=success). environment=production، جلسة واحدة + لكل طلب، المدد مقترنة. - شيء واحد لم أفعله: مجموعة العمال لديك في batch.py تقدم - مباشرة إلى المنفذ، لذا الأحداث من هناك ستُحذف. تريد مني أن أصلح تلك أيضاً؟ + شيء واحد لم أفعله: مجموعة العمال الخاصة بك في batch.py ترسل + مباشرة إلى المنفذ، لذا ستتم إسقاط الأحداث من هناك. + هل تريد مني أن أصلح تلك أيضاً؟ ``` -النمط الذي يجب ملاحظته: لقد قرأ الكود قبل الاقتراح، وطرح فقط الأسئلة التي يمكنك الإجابة عليها، وأعاد استخدام معرّف كان لديك بالفعل، اختار الشكل الآمن للتزامن *لأنه* رأى مجموعة خيوط، و**تحقق من خلال قراءة الأحداث الفعلية** بدلاً من التصريح بالنجاح — ثم وضع علامة على المكان الوحيد الذي عرف أنه سيفشل بهدوء. +النمط الذي يجب ملاحظته: قرأ الكود قبل الاقتراح، طرح فقط الأسئلة التي يمكنك الإجابة عليها، أعاد استخدام معرف كان لديك بالفعل، اختار الشكل الآمن للتزامن **لأنه** رأى مجموعة خيوط، و**تحقق بقراءة الأحداث الفعلية** بدلاً من التصريح بالنجاح — ثم وضع علامة على المكان الوحيد الذي يعرفه أنه سيفشل بصمت. -## ما يمكنك طلبه +## ما يمكنك أن تطلبه -- *"لماذا لا يظهر عاملي على لوحة التحكم؟"* → يسير على السلم: هل يتم كتابة الأحداث، هل يوجد `agent_start`، هل البيئة صحيحة، هل يقرأ المجمّع نفس المكان. -- *"كل شيء يهبط تحت dev."* → لم يتم تعيين البيئة، أو تم إعادة تعيينها بعد ذلك. -- *"أضف تتبع الرموز."* → يجد غلاف LLM لديك ويسجل النموذج، سبب التوقف، والاستخدام. -- *"أضف أدوات للعوامل الفرعية أيضاً."* → جلسة واحدة، تصنيفات عامل مختلفة، مدرجة تحت أبيهما. -- *"اكتب اختبارات للأدوات."* → وجّه SDK إلى دليل مؤقت ويؤكد على الأحداث التي كتبها. +- *"لماذا لا يظهر وكيلي على لوحة التحكم؟"* → يمشي السلم: هل يتم كتابة الأحداث، هل `agent_start` موجود، هل البيئة صحيحة، هل يقرأ المُجمِّع نفس المكان. +- *"كل شيء يصل تحت dev."* → لم يتم تعيين البيئة أبداً، أو تم إعادة تعيينها بواسطة استدعاء لاحق. +- *"أضف تتبع الرمزات."* → يجد غلاف LLM الخاص بك ويسجل النموذج وسبب التوقف والاستخدام. +- *"أدرج الأدوات في الوكلاء الفرعيين أيضاً."* → جلسة واحدة، تسميات وكيل متميزة، متداخلة تحت والديهما. +- *"اكتب اختبارات للأدوات."* → يشير SDK إلى دليل مؤقت ويؤكد على الأحداث التي كتبها. -## ما يجب الانتباه له +## ما يجب مراقبته -**دعها تتحقق.** الخطوة التي تجعل هذه المهارة تستحق الاستخدام هي الأخيرة — تشغيل عاملك وقراءة الأحداث مرة أخرى. عامل يكتب أدوات ويتوقف قد فعل النصف السهل، والنصف الذي يفشل بهدوء هو الآخر. +**اترك التحقق يتم.** الخطوة التي تجعل هذه المهارة تستحق الاستخدام هي الخطوة الأخيرة — تشغيل وكيلك وقراءة الأحداث مرة أخرى. الوكيل الذي يكتب الأدوات ويتوقف قد فعل النصف السهل، والنصف الذي يفشل بصمت هو النصف الآخر. -**وافق على الأسماء قبل الكود.** `session_id` و`agent_id` هما المحاور التي تجمع بها كل سطح. إعادة تسميتها لاحقاً تقسم السجل: التشغيلات القديمة تحتفظ بالتصنيفات القديمة وتنكسر الاتجاهات. ستسأل المهارة؛ الإجابة تستحق دقيقة تفكير. +**اتفق على الأسماء قبل الكود.** `session_id` و`agent_id` هما المحاور التي تجمع كل واجهة عليها. إعادة تسميتهما لاحقاً تقسم التاريخ: التشغيلات القديمة تحتفظ بالتسميات القديمة واتجاهاتك تنكسر. ستسأل المهارة؛ الإجابة تستحق دقيقة تفكير. -**إذا اقترح عاملك تثبيت SDK من فهرس عام، لم تُحمّل المهارة.** يتم توزيع SDK بشكل خاص. ذلك الاقتراح هو مؤشر موثوق على أن عاملك البرمجي يخمّن بدلاً من اتباع المهارة — توقفه هناك وتحقق من تثبيت المهارة. +**إذا اقترح وكيلك تثبيت SDK من فهرس عام، لم تُحمّل المهارة.** يتم توزيع SDK بشكل خاص. هذا الاقتراح هو مؤشر موثوق على أن وكيل الترميز الخاص بك يخمن بدلاً من اتباع المهارة — توقفه هناك وتحقق من أن المهارة مثبتة. -وراء ذلك نطاق انفجاره صغير: يكتب الكود في دليل العمل وملفات الأحداث حيث تخبره. لا يقرأ من نشرك ولا يغير شيئاً عنه. +بعيداً عن ذلك، نطاق انفجاره صغير: يكتب الكود في دليل عملك وملفات الأحداث حيث تخبره. لا يقرأ شيء من نشرك ولا يغير شيء عنه. ## الخطوات التالية -- **[Python SDK](/ar/agenteye/python-sdk)**: مرجع الحدث الكامل — كل نوع حدث وحقل — خلف ما تأتمت هذه المهارة. -- **[الجلسات](/ar/agenteye/sessions)**: ما تنتجه أدواتك مرة هبطت الأحداث. -- **[مهارة عامل المُقيّم](/ar/agenteye/evaluator-skill)**: الخطوة التالية بمجرد هبوط التشغيلات — تصنيفها. -- **[مهارة عامل CLI](/ar/agenteye/cli-skill)**: قراءة بيانات المراقبة مرة أخرى. \ No newline at end of file +- **[Python SDK](/ar/agenteye/python-sdk)**: المرجع الكامل للأحداث — كل نوع حدث وحقل — خلف ما تؤتمت هذه المهارة. +- **[الجلسات](/ar/agenteye/sessions)**: ما تنتجه أدواتك بمجرد وصول الأحداث. +- **[مهارة Evaluator Agent](/ar/agenteye/evaluator-skill)**: الخطوة التالية بمجرد وصول التشغيلات — تقييمها. +- **[مهارة CLI Agent](/ar/agenteye/cli-skill)**: قراءة قياس التلمترا الخاص بك مرة أخرى. \ No newline at end of file diff --git a/docs/ar/agenteye/python-sdk.mdx b/docs/ar/agenteye/python-sdk.mdx index e89710dd..9ff2324d 100644 --- a/docs/ar/agenteye/python-sdk.mdx +++ b/docs/ar/agenteye/python-sdk.mdx @@ -1,35 +1,36 @@ --- +--- title: "Python SDK" -description: "شاهد بالضبط ما فعلته وكلاء الذكاء الاصطناعي الخاصة بك في الإنتاج: كل تشغيل للوكيل، استدعاء أداة، طلب نموذج، خطاف، وتدخل بشري." +description: "شاهد بالضبط ما فعلته وكلاء الذكاء الاصطناعي الخاصة بك في الإنتاج: كل تشغيل للوكيل، واستدعاء أداة، وطلب نموذج، وخطاف، والتدخل البشري." --- -شاهد بالضبط ما فعلته وكلاء الذكاء الاصطناعي الخاصة بك في الإنتاج: كل تشغيل للوكيل، استدعاء أداة، طلب نموذج، خطاف، وتدخل بشري. يسجل Failproof AI Observability Python SDK هذا المسار من داخل كود الوكيل الخاص بك حتى تتمكن من تصحيح الأخطاء والتدقيق وتقييم ما حدث. استخدمه كلما أردت أن يراقب Failproof AI Observability وكلاءك. +شاهد بالضبط ما فعلته وكلاء الذكاء الاصطناعي الخاصة بك في الإنتاج: كل تشغيل للوكيل، واستدعاء أداة، وطلب نموذج، وخطاف، والتدخل البشري. يسجل SDK للرصد Failproof AI هذا المسار من داخل كود الوكيل الخاص بك بحيث يمكنك تصحيح الأخطاء والتدقيق وتقييم ما حدث. استخدمه كلما أردت أن يراقب Failproof AI Observability وكلاءك. -تحت الغطاء، يكتب SDK أحداثاً منظمة في ملفات JSONL محلية، وتلتقطها عملية جمع البيانات الخلفية وترسلها إلى المنصة تلقائياً. لا تحتاج إلى إدارة تلك الملفات بنفسك. +تحت الغطاء، يكتب SDK أحداثاً منظمة إلى ملفات JSONL محلية، وتلتقطها عملية جمع البيانات وترسلها إلى المنصة تلقائياً. أنت لا تدير هذه الملفات بنفسك. > **نصيحة:** جديد في Failproof AI Observability؟ هذه الصفحة هي مرجع أحداث SDK الكامل.
- +
--- ## التثبيت -يتم توزيع SDK على العملاء كعجلة خاصة بدلاً من فهرس حزمة عام. يغطي التكامل الخاص بك كيفية الحصول عليه وتثبيته وتثبيت إصداره — تحدث إلى جهة الاتصال Failproof AI الخاصة بك إذا كنت بحاجة إلى الوصول. +يتم توزيع SDK على العملاء كعجلة خاصة بدلاً من فهرس حزم عام. يغطي التوجيه الخاص بك كيفية الحصول عليه وتثبيته وتثبيته — تحدث إلى جهة الاتصال الخاصة بك في Failproof AI إذا كنت بحاجة إلى الوصول. -بمجرد تثبيته، تأكد من أن لديك: +بمجرد تثبيته، تأكد من أنك تملكه: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -هل تفضل السماح لوكيل ترميز بإجراء التكامل كله؟ [Python SDK Agent Skill](/ar/agenteye/python-sdk-skill) يعرف مسار التثبيت، ويخطط نقاط الأداة، ويكتبها، ويتحقق من وصول الأحداث. +هل تفضل السماح لوكيل برمجة بإجراء التكامل بالكامل؟ [مهارة وكيل Python SDK](/ar/agenteye/python-sdk-skill) تعرف مسار التثبيت، وتخطط نقاط الأداة، وتكتبها، وتتحقق من وصول الأحداث. --- -## البداية السريعة +## البدء السريع ```python import agenteye @@ -59,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### أداة استدعاء حقيقية -في الممارسة العملية، تلف كود الوكيل الموجود لديك. ضع استدعاء نموذج بين `model_request` قبل و `model_response` بعده، بحيث يمتد الحدثان على الطلب الفعلي ويمكن لـ Failproof AI Observability أن يقرن بينهما: +في الممارسة العملية تقوم بتغليف كود الوكيل الموجود لديك. قوس استدعاء نموذج مع `model_request` قبل و `model_response` بعد، بحيث يمتد الحدثان على الطلب الحقيقي ويمكن لـ Failproof AI Observability إقرانهما: ```python import anthropic @@ -94,11 +95,11 @@ agenteye.event.model_response( ) ``` -لف استدعاءات الأداة بنفس الطريقة باستخدام `tool_use` و `tool_result`، وأعد استخدام `tool_call_id` واحد عبر الزوج. +قم بتغليف استدعاءات الأدوات بنفس الطريقة مع `tool_use` و `tool_result`، إعادة استخدام واحد `tool_call_id` عبر الزوج. -إليك ما تبدو عليه تلك الأحداث بمجرد وصولها إلى لوحة التحكم، مرمزة بالألوان حسب النوع وقابلة للتصفية حسب البيئة والوكيل والجلسة: +إليك ما تبدو عليه هذه الأحداث بمجرد وصولها إلى لوحة المعلومات، مشفرة بالألوان حسب النوع وقابلة للتصفية حسب البيئة والوكيل والجلسة: -![تدفق الأحداث المباشر، مرمز بألوان حسب نوع الحدث وقابل للتصفية حسب البيئة والوكيل والجلسة](/agenteye/images/events-stream.png) +![دفق الأحداث المباشر، مشفر بالألوان حسب نوع الحدث وقابل للتصفية حسب البيئة والوكيل والجلسة](/agenteye/images/events-stream.png) --- @@ -112,18 +113,18 @@ agenteye.configure( ) ``` -استدع مرة واحدة قبل أي استدعاء `event.*`. من الآمن الحذف؛ الافتراضيات تعمل خارج الصندوق. جميع الحجج مفتاح فقط؛ مررها بالاسم كما هو موضح أعلاه. +اتصل مرة واحدة قبل أي استدعاء `event.*`. من الآمن حذفه؛ القيم الافتراضية تعمل خارج الصندوق. جميع الحجج كلمات رئيسية فقط؛ مررها بالاسم كما هو موضح أعلاه. -عندما يكون `base_dir` هو `None` (الافتراضي)، يقرأ SDK `$AGENTEYE_HOME` إذا تم تعيينه، -وإلا يعود إلى `~/.agenteye`. هذا يتطابق مع قرار جامع البيانات الخاص به، -لذا متغير بيئة `AGENTEYE_HOME` واحد يحتوي على مجلد حدث مشترك لكل من -SDK وجامع البيانات. +عندما يكون `base_dir` `None` (الافتراضي)، يقرأ SDK `$AGENTEYE_HOME` إذا تم تعيينه، +وإلا يعود إلى `~/.agenteye`. هذا يطابق دقة جامع البيانات الخاصة به، +بحيث يمكن لمتغير `AGENTEYE_HOME` بيئة واحد تكوين ملف الأحداث المشترك لكل من +SDK و جامع البيانات. --- ## البيئة -قم بتسمية كل حدث ببيئة نشر (`production`، `staging`، `qa`، `canary`، إلخ). اضبطها مرة واحدة؛ يرفقها SDK بكل حدث تلقائياً. +قم بتسمية كل حدث مع بيئة نشر (`production`, `staging`, `qa`, `canary`، إلخ). اضبطه مرة واحدة؛ يرفق SDK به كل حدث تلقائياً. **الخيار 1: عبر `configure()`:** @@ -137,49 +138,49 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**الأولوية:** `configure(environment=...)` يتغلب على متغير البيئة. إذا لم يتم تعيين أي منهما، يتم الافتراضي إلى `"dev"`. +**الأولوية:** `configure(environment=...)` يفوز على متغير البيئة. إذا لم يتم تعيين أي منهما، الافتراضي إلى `"dev"`. -تظهر قيمة البيئة كمرشح من الدرجة الأولى في لوحة التحكم وتُخزن على الخادم لعمليات الاستعلام السريعة. +تظهر قيمة البيئة كمرشح من الدرجة الأولى في لوحة المعلومات وتُخزن على الخادم للاستعلامات السريعة. -> **تحذير:** يجب ألا تحتوي قيم البيئة على فاصلة حرفية `,`. عوامل التصفية في لوحة التحكم تستخدم الاختيار المتعدد المفصول بفواصل على السلك (`?environment=prod,staging`)، لذا ستكون البيئة المسماة `prod,blue` مقسومة إلى قيمتين. يتم رفض الأحداث التي تحتوي على بيئات تحتوي على فواصل وقت الابتلاع. +> **تحذير:** يجب ألا تحتوي قيم البيئة على فاصلة حرفية `,`. مرشحات لوحة المعلومات تستخدم تحديد متعدد مفصول بفاصلة على السلك (`?environment=prod,staging`)، لذا ستُقسم بيئة باسم `prod,blue` إلى قيمتين. الأحداث التي تحتوي على بيئات تحتوي على فواصل يتم رفضها في وقت الاستقبال. --- ## البيانات والخصوصية -يسجل SDK فقط الحقول التي تمررها بشكل صريح. يتم التقاط المحفزات والرسائل ومدخلات الأداة والمخرجات ومحتوى النموذج فقط لأنك تسلمها لاستدعاء `event.*`. لا يتم قراءة أي شيء من عمليتك أو التقاطه بشكل ضمني. أي حقل تتركه غير محدد يُحذف من الحدث بالكامل؛ لم يتم كتابته إلى القرص. +يسجل SDK فقط الحقول التي تمررها بشكل صريح. يتم التقاط المحتويات والرسائل والمدخلات والمخرجات والمحتوى والأدوات فقط لأنك تسلمها إلى استدعاء `event.*`. لا يتم قراءة أي شيء من عمليتك أو التقاطه بشكل ضمني. أي حقل تتركه غير محدد يتم حذفه من الحدث بالكامل؛ لم يتم كتابته إلى القرص. -هذا يجعل الحجب خياراً ومسؤوليتك. إذا كان المحفز أو حمولة الأداة تحتوي على PII أو أسرار لا تفضل تخزينها، امسحها أو قنعها قبل تمريرها إلى طريقة الحدث. +هذا يجعل الحذف اختيارك ومسؤوليتك. إذا احتوت ملحوظة أو حمولة أداة على معلومات تعريف شخصية أو أسرار لن تخزنها، قم بتجريدها أو إخفاءها قبل تمريرها إلى طريقة الحدث. --- -## مرجع الأحداث +## مرجع الحدث -تأتي معظم الأحداث في أزواج البداية/النهاية التي تشترك في معرف الارتباط: يشترك `tool_use` و `tool_result` في `tool_call_id`، و `hook_triggered` و `hook_completed` يشتركان في `hook_id`، و `human_wait` و `human_input` يشتركان في `input_id`. أرسل حدث البداية، قم بالعمل، ثم أرسل حدث النهاية برفقة نفس المعرف. يطابق Failproof AI Observability الزوج ويحسب `duration_ms` لك، لذا لا تمرر `duration_ms` بنفسك. +معظم الأحداث تأتي في أزواج بدء/نهاية تشترك في معرّف ارتباط: `tool_use` و `tool_result` يشاركان `tool_call_id`، `hook_triggered` و `hook_completed` يشاركان `hook_id`، و `human_wait` و `human_input` يشاركان `input_id`. انبعث حدث البدء، قم بالعمل، ثم انبعث حدث النهاية مع نفس المعرف. تطابقات Failproof AI Observability الزوج وحساب `duration_ms` لك، لذا لا تمرر `duration_ms` بنفسك. -![رسم بياني لتنفيذ جلسة على طراز git بجانب الخط الزمني للحدث، تم إعادة بناؤه من الأحداث المقترنة، مع لوحة تفصيل الأداة/النموذج/الخطاف](/agenteye/images/session-detail.png) +![رسم بياني لتنفيذ على غرار git للجلسة بجانب جدول الأحداث الخاص بها، تم إعادة بنائه من الأحداث المقترنة، مع لوحة تحطيم الأداة/النموذج/الخطاف](/agenteye/images/session-detail.png) -تتطلب جميع طرق الأحداث هذين الحقلين: +جميع طرق الحدث تتطلب هذين الحقلين: | الحقل | النوع | الوصف | |---|---|---| -| `session_id` | `str` | يحدد تشغيل الوكيل من الدرجة الأولى | -| `agent_id` | `str` | يحدد أي وكيل داخل الجلسة أرسل الحدث | +| `session_id` | `str` | يحدد تشغيل الوكيل من المستوى الأعلى | +| `agent_id` | `str` | يحدد أي وكيل في الجلسة انبعث الحدث | -تقبل جميع الطرق أيضاً `**kwargs` عشوائية للبيانات الوصفية المخصصة (راجع [الحقول المخصصة](#custom-fields)). +جميع الطرق تقبل أيضاً `**kwargs` تعسفية للبيانات الوصفية المخصصة (انظر [الحقول المخصصة](#custom-fields)). --- ### `event.agent_start()` -تُطلق عند بدء الوكيل في العمل. +انبعث عندما يبدأ وكيل العمل. ```python agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - معرف وكيل الوالد للوكلاء المتداخلين + parent_id=None, # str | None - parent agent_id for nested agents ) ``` @@ -187,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -تُطلق عند انتهاء الوكيل من العمل. +انبعث عندما ينهي وكيل العمل. ```python agenteye.event.agent_end( @@ -202,14 +203,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -تُطلق عند استدعاء الوكيل لأداة. اقرن مع `tool_result`؛ يحسب SDK تلقائياً `duration_ms`. +انبعث عندما يستدعي وكيل أداة. اقرنها مع `tool_result`؛ يحسب SDK `duration_ms` تلقائياً. ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", tool_name="web_search", # str, required - tool_call_id="toolu_01", # str, required - مفتاح الارتباط للمطابقة tool_result + tool_call_id="toolu_01", # str, required - correlation key for the matching tool_result input={"query": "..."}, # dict | None ) ``` @@ -218,17 +219,17 @@ agenteye.event.tool_use( ### `event.tool_result()` -تُطلق عند عودة الأداة. يرتبط مع `tool_use` عبر `tool_call_id`. +انبعث عندما تعود أداة. يرتبط بـ `tool_use` عبر `tool_call_id`. ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # يجب أن يطابق tool_use السابق + tool_call_id="toolu_01", # must match the prior tool_use output={"results": ["..."]}, # Any | None - error=None, # str | None - اضبط إذا أطلقت الأداة - # يتم حساب duration_ms تلقائياً - لا تمرره + error=None, # str | None - set if the tool raised + # duration_ms is computed automatically - do not pass it ) ``` @@ -236,60 +237,60 @@ agenteye.event.tool_result( ### `event.model_request()` -تُطلق قبل إرسال مباشر لنموذج LLM. +انبعث قبل إرسال ملحوظة إلى LLM مباشرة. ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - أي سلسلة موفر/نموذج؛ غير معتمدة - messages=[ # list[dict] | None - أدوار المحادثة + model="claude-sonnet-4-6", # str | None - any provider/model string; not validated + messages=[ # list[dict] | None - conversation turns {"role": "user", "content": "..."}, ], - system="You are helpful.", # Any | None - str أو قائمة كتل المحتوى - tools=[ # list[dict] | None - مخططات الأداة المقدمة للنموذج + system="You are helpful.", # Any | None - str or list of content blocks + tools=[ # list[dict] | None - tool schemas offered to the model {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -تقبل إدخالات `messages` إما سلسلة عادية `content` أو قائمة كتل محتوى على طراز Anthropic. يمكن تمرير معاملات أخذ العينات (`temperature`، `max_tokens`، إلخ) كـ kwargs إضافية. +مدخلات `messages` تقبل إما `content` سلسلة عادية أو قائمة أسلوب Anthropic من كتل `content`. يمكن تمرير معاملات العينة (`temperature`, `max_tokens`، وما إلى ذلك) كـ kwargs إضافية. --- ### `event.model_response()` -تُطلق عند عودة LLM برد. +انبعث عندما يعود LLM استجابة. ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - أي سلسلة موفر/نموذج؛ غير معتمدة + model="claude-sonnet-4-6", # str | None - any provider/model string; not validated stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None - content=[ # Any | None - str، أو قائمة كتل المحتوى + content=[ # Any | None - str, or list of content blocks {"type": "text", "text": "..."}, ], role="assistant", # str | None ) ``` -يقبل `content` إما سلسلة عادية (موفرو عام) أو قائمة كتل محتوى على طراز Anthropic. تعيش استدعاءات الأداة داخل `content` كـ `{"type": "tool_use", ...}` كتل، بدون حقل منفصل `tool_calls`. +`content` يقبل إما سلسلة عادية (موفري عام) أو قائمة كتل محتوى على غرار Anthropic. استدعاءات الأدوات تعيش داخل `content` ككتل `{"type": "tool_use", ...}`، بدون حقل `tool_calls` منفصل. --- ### `event.hook_triggered()` -تُطلق عند إطلاق خطاف. اقرن مع `hook_completed`؛ يحسب SDK تلقائياً `duration_ms`. +انبعث عندما يطلق خطاف. اقرنها مع `hook_completed`؛ يحسب SDK `duration_ms` تلقائياً. ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", # str, required - hook_id="hook-abc", # str, required - مفتاح الارتباط + hook_id="hook-abc", # str, required - correlation key trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -299,18 +300,18 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -تُطلق عند انتهاء الخطاف. يرتبط مع `hook_triggered` عبر `hook_id`. +انبعث عندما ينتهي خطاف. يرتبط بـ `hook_triggered` عبر `hook_id`. ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # يجب أن يطابق hook_triggered السابق + hook_id="hook-abc", # must match the prior hook_triggered outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # يتم حساب duration_ms تلقائياً - لا تمرره + # duration_ms is computed automatically - do not pass it ) ``` @@ -318,7 +319,7 @@ agenteye.event.hook_completed( ### `event.error()` -تُطلق عند حدوث خطأ لم يتم التعامل معه. +انبعث عندما يحدث خطأ لم تتم معالجته. ```python agenteye.event.error( @@ -332,63 +333,63 @@ agenteye.event.error( --- -## أحداث التدخل البشري +## أحداث البشر في الحلقة -تمنحك أحداث التدخل البشري الإشراف على اللحظات التي يتدخل فيها الشخص في تنفيذ الوكيل (الانتظار للموافقة، توفير المدخلات، الإيقاف المؤقت، أو إيقاف الوكيل). تسمح لك بقياس المدة التي يستغرقها البشر للرد (يحسب SDK تلقائياً `duration_ms` على الأحداث المقترنة)، وتدقيق من أيقف أو قاطع الوكيل، وبناء سير عمل الموافقة والإشراف التي تظهر في لوحة التحكم. +توفر أحداث البشر في الحلقة الإشراف على اللحظات التي يتدخل فيها شخص في تنفيذ الوكيل (انتظار الموافقة، وتقديم المدخلات، والإيقاف المؤقت، أو إيقاف الوكيل). تسمح لك بقياس المدة التي يستغرقها البشر للرد (يحسب SDK `duration_ms` تلقائياً في الأحداث المقترنة)، التدقيق من أيقف أو قاطع وكيل، وبناء مسارات الموافقة والإشراف التي تظهر في لوحة المعلومات. ### `event.human_wait()` -تُطلق عندما يوقف الوكيل التنفيذ بانتظار الإنسان لتوفير مدخلات. اقرن مع `human_input`؛ يحسب SDK تلقائياً `duration_ms` (كم من الوقت استغرق الإنسان للرد). +انبعث عندما يوقف الوكيل التنفيذ لانتظار شخص لتقديم مدخلات. اقرنها مع `human_input`؛ يحسب SDK `duration_ms` تلقائياً (كم من الوقت استغرق الشخص للرد). ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - مفتاح الارتباط للمطابقة human_input - prompt="Do you approve this action?", # str | None - السؤال المعروض للإنسان - options=["approve", "reject", "defer"], # list[str] | None - الخيارات المعروضة على الإنسان - reason="approval_required", # str | None - لماذا ينتظر الوكيل + input_id="inp-abc", # str, required - correlation key for the matching human_input + prompt="Do you approve this action?", # str | None - the question shown to the human + options=["approve", "reject", "defer"], # list[str] | None - choices presented to the human + reason="approval_required", # str | None - why the agent is waiting ) ``` ### `event.human_input()` -تُطلق عندما يوفر الإنسان مدخلات ويستأنف الوكيل. يرتبط مع `human_wait` عبر `input_id`. يتم حساب `duration_ms` تلقائياً ولا يجب تمريره من قبل المتصل. +انبعث عندما يقدم شخص مدخلات ويستأنف الوكيل. يرتبط بـ `human_wait` عبر `input_id`. يتم حساب `duration_ms` تلقائياً ولا يجب تمريره من قبل المتصل. ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - يجب أن يطابق human_wait السابق - response="approve", # str | None - إجابة الإنسان (نص حر أو خيار محدد) - # يتم حساب duration_ms تلقائياً - لا تمرره + input_id="inp-abc", # str, required - must match the prior human_wait + response="approve", # str | None - the human's answer (free text or selected option) + # duration_ms is computed automatically - do not pass it ) ``` ### `event.human_pause()` -تُطلق عندما يوقف الإنسان الوكيل بنشاط (مثل عبر عنصر تحكم في لوحة التحكم). يتم تعليق الوكيل لكن لم ينته. +انبعث عندما يوقف شخص الوكيل بنشاط (مثل عبر تحكم لوحة المعلومات). يتم تعليق الوكيل لكن لم يتم إنهاؤه. ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - من أوقف الوكيل + user_id="usr_42", # str | None - who paused the agent ) ``` ### `event.human_interrupt()` -تُطلق عندما يوقف الإنسان الوكيل بشكل نشط في منتصف التنفيذ. بخلاف `human_pause`، يتم إنهاء عمل الوكيل بدلاً من تعليقه. +انبعث عندما يوقف شخص الوكيل بنشاط في منتصف التنفيذ. بخلاف `human_pause`، يتم إنهاء عمل الوكيل بدلاً من تعليقه. ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - من قاطع الوكيل - at_step="tool_use:web_search", # str | None - ما كان الوكيل يفعله عند الإيقاف + user_id="usr_42", # str | None - who interrupted the agent + at_step="tool_use:web_search", # str | None - what the agent was doing when stopped ) ``` @@ -396,7 +397,7 @@ agenteye.event.human_interrupt( ## الحقول المخصصة -أي حجج كلمة رئيسية إضافية تُلحق بالحدث بعد الحقول القياسية: +أي حجج إضافية من الكلمات الرئيسية تُلحق بالحدث بعد الحقول القياسية: ```python agenteye.event.tool_use( @@ -404,32 +405,32 @@ agenteye.event.tool_use( agent_id="planner", tool_name="db_query", tool_call_id="toolu_02", - tenant_id="acme", # حقل مخصص - region="us-east-1", # حقل مخصص + tenant_id="acme", # custom field + region="us-east-1", # custom field ) ``` -`timestamp`، و `type`، و `environment` محجوزة وترفع `ValueError` (`لا يمكن استخدام أسماء الحقول المحجوزة كحقول مخصصة: [...]`) إذا تم تمريرها كحقول مخصصة. `session_id` و `agent_id` معاملات مطلوبة في كل طريقة حدث ولا يمكن توفيرها مرة ثانية؛ يرفع Python `TypeError` إذا فعلت. اضبط البيئة باستخدام `configure(environment=...)` (أو متغير `AGENTEYE_ENVIRONMENT`) بدلاً من ذلك. +`timestamp`, `type`, و `environment` محفوظة وترفع `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) إذا تم تمريرها كحقول مخصصة. `session_id` و `agent_id` معاملات مطلوبة في كل طريقة حدث ولا يمكن تمريرها مرة ثانية؛ Python ترفع `TypeError` إذا فعلت. اضبط البيئة بـ `configure(environment=...)` (أو متغير `AGENTEYE_ENVIRONMENT`) بدلاً من ذلك. -احفظ الحمولات كـ JSON منظمة عندما تريد الاستعلام عن حقولها. القيم التي لا يدعمها JSON بشكل أصلي — مثل التواريخ، UUIDs، الكسور العشرية، المجموعات، البايتات، أو كائنات النموذج — يتم تحويلها إلى سلاسل نصية بحيث يستمر التسجيل بأمان. +احفظ الحمولات كـ JSON منظمة عندما تريد الاستعلام عن حقولها. يتم تحويل القيم التي لا يدعمها JSON بشكل أصلي—مثل datetimes و UUIDs و decimals و sets و bytes أو model objects—إلى سلاسل بحيث يستمر التسجيل بأمان. --- -## كيف يتم كتابة الأحداث +## كيفية كتابة الأحداث -يتم تخزين الأحداث مؤقتاً داخل العملية وتُغسل على القرص كل `flush_interval` ثانية (500 ملليثانية افتراضياً). كل عملية غسل تكتب ملف JSONL واحد: +يتم تخزين مؤقت الأحداث في العملية وتنظيفها إلى القرص كل `flush_interval` ثانية (افتراضي 500 مللي ثانية). كل تنظيف يكتب ملف JSONL واحد: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -يراقب جامع البيانات هذا الدليل ويرفع الملفات تلقائياً. لا تحتاج إلى إدارة هذه الملفات مباشرة. +يراقب جامع البيانات هذا الدليل ويرفع الملفات تلقائياً. أنت لا تحتاج إلى إدارة هذه الملفات مباشرة. -يتم كتابة كل ملف بشكل ذري: يكتب SDK إلى ملف مؤقت ثم يعيد تسميته في مكانه، لذا لا يرى جامع البيانات أبداً ملف نصفي. عملية غسل نهائية تعمل أيضاً عند خروج عمليتك، لذا لم تُفقد الأحداث المخزنة مؤقتاً في الفترة الأخيرة. إذا كان جامع البيانات غير متصل، تتراكم الأحداث ببساطة كملفات على القرص وتُرسل بمجرد عودته. +كل ملف يتم كتابته بشكل ذري: يكتب SDK إلى ملف مؤقت ثم يعيد تسميته في المكان، بحيث لا يرى جامع البيانات أبداً ملف نصفي الكتابة. يعمل تنظيف نهائي أيضاً عند خروج عمليتك، لذا لا تُفقد الأحداث المخزنة في الفاصل الزمني الأخير. إذا كان جامع البيانات في وضع عدم الاتصال، تتراكم الأحداث ببساطة كملفات على القرص وتُشحن بمجرد عودتها. --- ## الخطوات التالية -- [تدفق الأحداث](/ar/agenteye/event-stream): شاهد هذه الأحداث تصل مباشرة، مرمزة بألوان وقابلة للتصفية حسب البيئة والوكيل والجلسة. -- [الجلسات](/ar/agenteye/sessions): شاهد كيف يعيد الأحداث المقترنة بناء كل تشغيل وكيل كرسم بياني للتنفيذ وخط زمني. \ No newline at end of file +- [دفق الحدث](/ar/agenteye/event-stream): شاهد هذه الأحداث تصل مباشرة، مشفرة بالألوان وقابلة للتصفية حسب البيئة والوكيل والجلسة. +- [الجلسات](/ar/agenteye/sessions): شاهد كيف تعيد بناء الأحداث المقترنة كل تشغيل وكيل كرسم بياني للتنفيذ وخط زمني. \ No newline at end of file diff --git a/docs/ar/agenteye/queries.mdx b/docs/ar/agenteye/queries.mdx index 421195ac..61a90141 100644 --- a/docs/ar/agenteye/queries.mdx +++ b/docs/ar/agenteye/queries.mdx @@ -5,53 +5,53 @@ description: "اطرح أي سؤال حول بيانات وكيلك واحصل --- -اطرح أي سؤال حول بيانات وكيلك واحصل على إجابة في ثوان. يوفر لك Failproof AI Observability مكتبة من الاستعلامات المحفوظة والجاهزة للتشغيل على أحداثك وتقييماتك، لذلك تبدأ من مثال يعمل بدلاً من محرر SQL فارغ. +اطرح أي سؤال حول بيانات وكيلك واحصل على إجابة في ثوان. يوفر لك Failproof AI Observability مكتبة من الاستعلامات المحفوظة والجاهزة للتشغيل على أحداثك والتقييمات، حتى تتمكن من البدء من مثال عملي بدلاً من محرر SQL فارغ. -![مكتبة الاستعلامات المحفوظة: شبكة من الاستعلامات القابلة لإعادة الاستخدام، سواء كانت إعدادات مدمجة أو استعلامات مخصصة](/agenteye/images/queries.png) +![مكتبة الاستعلامات المحفوظة: شبكة من الاستعلامات القابلة لإعادة الاستخدام، سواء كانت إعدادات مسبقة مدمجة أو مخصصة](/agenteye/images/queries.png) -*مكتبة الاستعلامات المحفوظة لديك في `//queries`: الإعدادات المدمجة بجانب الاستعلامات التي حفظتها فريقك.* +*مكتبة الاستعلامات المحفوظة في `//queries`: إعدادات مسبقة مدمجة جنباً إلى جنب مع الاستعلامات التي حفظها فريقك.* ## ابدأ من إعداد مسبق، وليس من صفحة فارغة -لا تحتاج إلى تذكر أسماء الجداول أو كتابة SQL من الصفر. تفتح المكتبة بإعدادات مسبقة مدمجة للأسئلة التي تطرحها الفرق بشكل متكرر، وتجلس بجانب الاستعلامات التي حفظها فريقك وسماها. اختر واحداً قريباً مما تريده وستكون في منتصف الطريق تقريباً للوصول إلى إجابة. +لا تحتاج إلى تذكر أسماء الجداول أو كتابة SQL من الصفر. تفتح المكتبة مع إعدادات مسبقة مدمجة للأسئلة التي تطرحها الفرق بشكل متكرر، جنباً إلى جنب مع الاستعلامات التي حفظها فريقك وسماها. اختر واحداً قريباً مما تريد وستكون في منتصف الطريق للوصول إلى الإجابة. -كل استعلام محفوظ هو نطاق منظمة ومشترك، لذا الاستعلامات المفيدة التي يكتبها زملاؤك تصبح ملكك أيضاً. سمِّ استعلاماً وأضف له وصفاً مرة واحدة، وأي شخص في منظمتك يمكنه أن يجده أو يشغله أو يثبت نتائجه على لوحة معلومات لاحقاً. +كل استعلام محفوظ محدود بنطاق المنظمة ومشترك، لذا فإن الاستعلامات المفيدة التي يكتبها زملاؤك تصبح ملكك أيضاً. سمِّ الاستعلام وأضف وصفاً له مرة واحدة، وسيتمكن أي شخص في منظمتك من العثور عليه أو تشغيله أو تثبيت نتائجه على لوحة معلومات لاحقاً. -ابحث عنه في `//queries`. +ستجده في `//queries`. -## عدّله وشغّله في مؤلف SQL +## عدّله وشغّله في مصنّف SQL -افتح أي استعلام وسيهبط في مؤلف SQL، حيث يمكنك تعديله ورؤية الإجابة على الفور: لا توجد عمليات تصدير، لا رحلات ذهاباً وإياباً، لا انتظار لشخص آخر. +افتح أي استعلام وسيظهر في مصنّف SQL، حيث يمكنك تعديله ورؤية الإجابة فوراً: لا توجد عملية تصدير، لا توجد رحلة ذهاب وإياب، لا تنتظر شخصاً آخر. -![مؤلف استعلام SQL يقوم بتشغيل استعلام محفوظ، مع شريط جانبي للمخطط وشبكة نتائج حية](/agenteye/images/query-lab.png) +![مصنّف استعلام SQL يشغّل استعلاماً محفوظاً، مع شريط جانبي للمخطط وشبكة نتائج مباشرة](/agenteye/images/query-lab.png) -*مؤلف SQL: استعلامك على اليسار، وشريط جانبي للمخطط حتى لا تخمن اسم عمود، وشبكة نتائج حية أدناه.* +*مصنّف SQL: استعلامك على اليسار، وشريط جانبي للمخطط حتى لا تضطر لتخمين اسم العمود، وشبكة نتائج مباشرة أدناه.* -- **يعرض الشريط الجانبي للمخطط** جداول التحليلات والأعمدة الخاصة بها، لذا يمكنك تشكيل استعلام دون البحث عن أسماء الحقول. -- **شبكة النتائج الحية** تُرجع الصفوف في لحظة تشغيلك للاستعلام، لذا تتكرر في ثوان بدلاً من التخمين وإعادة التخمين. -- **للقراءة فقط بحكم التصميم.** تعمل الاستعلامات ضد متجر الأحداث الخاص بك ويتم التحقق من صحتها على الخادم: فقط عبارات `SELECT` و `WITH` مسموحة، مع مهلة زمنية للبيان وحد أقصى للصفوف. لا يمكن لاستعلام استكشافي أبداً أن يعدّل بيانات، والاستعلام الجامح يُوقف لك. +- **الشريط الجانبي للمخطط** يعرض جداول التحليلات وأعمدتها، حتى تتمكن من صياغة استعلام دون البحث عن أسماء الحقول. +- **شبكة النتائج المباشرة** تُرجع الصفوف في اللحظة التي تشغّل فيها الاستعلام، حتى تتمكن من التكرار في ثوان بدلاً من التخمين وإعادة التخمين. +- **مصمم للقراءة فقط.** تعمل الاستعلامات على متجر الأحداث الخاص بك ويتم التحقق منها على الخادم: يُسمح فقط بعبارات `SELECT` و `WITH`، مع مهلة زمنية للعبارة وحد أقصى للصفوف. لا يمكن لاستعلام استكشافي أن يعدّل بياناتك أبداً، وسيتم إيقاف الاستعلام الذي يخرج عن السيطرة تلقائياً. -راضٍ عن النتيجة؟ احفظها مرة أخرى في المكتبة حتى يرثها الفريق كله، أو ثبت إخراجها على لوحة معلومات كبلاطة خط أو شريط أو منطقة أو دائري. +راضٍ عن النتيجة؟ احفظها مرة أخرى في المكتبة حتى يستفيد منها الفريق كله، أو ثبّت ناتجها على لوحة معلومات كرسم بياني خطي أو عمودي أو منطقة أو رسم بياني دائري. -## شغّلها من المحطة الطرفية، أو دع المساعد يكتبها لك +## شغّلها من جهاز الطرفية، أو اترك المساعد يكتبها -نفس الاستعلامات المحفوظة تتبعك أينما تعمل: +نفس الاستعلامات المحفوظة تتبعك في أي مكان تعمل فيه: -- **من المحطة الطرفية.** يعرض CLI `agenteye` ويشغل ويحفظ نفس الاستعلامات بالضبط، لذا يمكنك إدراج نتيجة في برنامج نصي، أو ربطها في CI، أو تسليمها إلى وكيل ترميز. +- **من جهاز الطرفية.** واجهة سطر الأوامر `agenteye` تعرض وتشغّل وتحفظ نفس الاستعلامات، حتى تتمكن من إدراج النتيجة في سكريبت أو ربطها بـ CI أو تسليمها لوكيل ترميز. ```bash -agenteye query list # same saved queries, from your terminal -agenteye query run errs --arg prod # run one and print the rows (add --json to pipe it) +agenteye query list # نفس الاستعلامات المحفوظة، من جهاز الطرفية الخاص بك +agenteye query run errs --arg prod # شغّل واحداً واطبع الصفوف (أضف --json لتمريره عبر أنبوب) ``` - انظر [CLI والوكلاء](/ar/agenteye/cli-and-agents) للحصول على مجموعة الأوامر الكاملة. + انظر إلى [CLI والوكلاء](/ar/agenteye/cli-and-agents) للحصول على مجموعة الأوامر الكاملة. -- **من مساعد AI.** غير متأكد من كيفية صياغة SQL؟ اسأل [مساعد AI](/ar/agenteye/assistant) في لوحة المعلومات بلغة إنجليزية عادية وسيقوم بصياغة الاستعلام وحفظه في مكتبتك لك. +- **من مساعد الذكاء الاصطناعي.** غير متأكد من كيفية صياغة SQL؟ اسأل [مساعد الذكاء الاصطناعي](/ar/agenteye/assistant) داخل لوحة المعلومات باللغة الإنجليزية البسيطة وسيصيغ الاستعلام ويحفظه في مكتبتك لك. -يتم التحكم في تشغيل استعلام محفوظ بواسطة صلاحية `queries:run`، يتم فصله عن الأذونات لإنشاء أو حذف الاستعلامات، لذا يمكنك منح إمكانية الوصول للقراءة دون السماح للجميع بإعادة كتابة المكتبة. +يتم التحكم في تشغيل الاستعلام المحفوظ من خلال الإذن `queries:run`، الذي يتم الاحتفاظ به بشكل منفصل عن الأذونات لإنشاء أو حذف الاستعلامات، حتى تتمكن من منح حق الوصول للقراءة دون السماح للجميع بإعادة كتابة المكتبة. -## ذو الصلة +## ذات صلة -- [لوحات المعلومات](/ar/agenteye/dashboards): ثبت نتائج الاستعلامات في الرسوم البيانية المشتركة على مستوى المنظمة. -- [مساعد AI](/ar/agenteye/assistant): اطرح أسئلة باللغة الإنجليزية العادية واحصل على استعلام. -- [CLI والوكلاء](/ar/agenteye/cli-and-agents): شغّل واحفظ نفس الاستعلامات من محطتك الطرفية. \ No newline at end of file +- [لوحات المعلومات](/ar/agenteye/dashboards): ثبّت نتائج الاستعلامات في رسوم بيانية مشتركة على مستوى المنظمة. +- [مساعد الذكاء الاصطناعي](/ar/agenteye/assistant): اطرح أسئلة باللغة الإنجليزية البسيطة واحصل على استعلام. +- [CLI والوكلاء](/ar/agenteye/cli-and-agents): شغّل واحفظ نفس الاستعلامات من جهاز الطرفية الخاص بك. \ No newline at end of file diff --git a/docs/ar/agenteye/security.mdx b/docs/ar/agenteye/security.mdx index 51a70785..ff4fa864 100644 --- a/docs/ar/agenteye/security.mdx +++ b/docs/ar/agenteye/security.mdx @@ -1,68 +1,69 @@ --- +--- title: "الأمان" -description: "تم بناء Failproof AI Observability للعمل بالقرب من وكلائك الإنتاجيين، مما يعني أنها ترى موجهاتك ومدخلات الأدوات والمخرجات." +description: "تم بناء Failproof AI Observability ليعمل بالقرب من وكلائك في الإنتاج، مما يعني أنه يرى طلباتك ومدخلات الأدوات والمخرجات." --- -تم بناء Failproof AI Observability للعمل بالقرب من وكلائك الإنتاجيين، مما يعني أنها ترى موجهاتك ومدخلات الأدوات والمخرجات. توضح هذه الصفحة كيفية الحفاظ على عزل هذه البيانات والتحكم فيها وإبقاؤها في يديك. إذا كنت تقيّم Failproof AI Observability لمراجعة أمان، فابدأ من هنا. +تم بناء Failproof AI Observability ليعمل بالقرب من وكلائك في الإنتاج، مما يعني أنه يرى طلباتك ومدخلات الأدوات والمخرجات. تشرح هذه الصفحة كيف يحافظ على عزل هذه البيانات والتحكم فيها وبقاءها في يديك. إذا كنت تقيّم Failproof AI Observability لمراجعة أمان، فابدأ من هنا. --- -## بيانات تبقى في بيئتك +## بياناتك تبقى في بيئتك -Failproof AI Observability مستضافة ذاتياً. يتم تخزين الأحداث والموجهات واستجابات النموذج والتحليلات في قواعد بيانات خاصة بك، في بيئتك الخاصة. لا يتم إرسال أي شيء إلى طرف ثالث SaaS للتخزين، وتبقى بيانات عملك في حساب السحابة الخاص بك. +Failproof AI Observability يتم استضافته ذاتياً. يتم تخزين الأحداث والطلبات وردود النموذج والتحليلات في قواعد البيانات الخاصة بك، في بيئتك الخاصة. لا يتم إرسال أي شيء إلى خدمة SaaS من طرف ثالث للتخزين، وتبقى بيانتك في حساب السحابة الخاص بك. --- -## عزل المستأجرين +## عزل المستأجر -يمكن لمثيل واحد من Failproof AI Observability استضافة عدة منظمات، وكل منها معزولة على مستوى التخزين — مفروض من قبل قاعدة البيانات وليس من الواجهة فقط: +يمكن لمثيل واحد من Failproof AI Observability أن يستضيف العديد من المنظمات، وكل منها معزول على مستوى التخزين — يتم فرضه من قبل قاعدة البيانات، وليس فقط واجهة المستخدم: -- بيانات المنظمة التشغيلية (المستخدمون والمفاتيح لوحات التحكم والاستعلامات المحفوظة) يتم تحديد نطاقها لتلك المنظمة، وتحظر قاعدة البيانات نفسها القراءات عبر المنظمات. -- كل حدث مُدرج موسوم بمنظمته المالكة، لذا لا يمكن أبداً قراءة أحداث منظمة واحدة من قبل منظمة أخرى. +- يتم تحديد نطاق البيانات التشغيلية للمنظمة (المستخدمون والمفاتيح والعمليات وأسئلة محفوظة) على تلك المنظمة، ويتم حظر القراءات عبر المنظمات من قبل قاعدة البيانات نفسها. +- يتم وضع علامة على كل حدث يتم بلعه مع المنظمة المالكة له، بحيث لا يمكن أبداً قراءة أحداث منظمة واحدة من قبل أخرى. -كل مسار لوحة تحكم يتم تحديد نطاقه تحت شعار منظمة (`//…`). +كل مسار لوحة معلومات يقع ضمن نطاق شارة المنظمة (`//…`). --- ## تسجيل الدخول -تستخدم Failproof AI Observability تسجيل دخول بدون كلمة مرور قائم على البريد الإلكتروني. لا توجد كلمة مرور يمكن اختراقها أو تسريبها. يطلب المستخدم رمزاً لمرة واحدة (أو رابط سحر بنقرة واحدة)، والذي يُرسل إليه عبر البريد الإلكتروني وينتهي صلاحيته بسرعة. يتم حماية تسجيل الدخول بواسطة **قائمة بيضاء**: فقط عناوين البريد الإلكتروني (أو النطاقات) التي تسمح بها يمكنها المصادقة. +Failproof AI Observability يستخدم تسجيل دخول بدون كلمة مرور قائم على البريد الإلكتروني. لا توجد كلمة مرور للاختراق أو التسرب. يطلب المستخدم رمز لمرة واحدة (أو رابط سحري بنقرة واحدة)، والذي يتم إرساله إليه عبر البريد الإلكتروني وينتهي بسرعة. يتم حماية تسجيل الدخول بواسطة **قائمة بيضاء**: فقط عناوين البريد الإلكتروني (أو النطاقات) التي تسمح بها يمكنها المصادقة. -![شاشة تسجيل دخول Failproof AI Observability، التي ترسل رمزاً لمرة واحدة إلى بريدك الإلكتروني](/agenteye/images/login.png) +![شاشة تسجيل الدخول إلى Failproof AI Observability، والتي ترسل رمزاً لمرة واحدة إلى بريدك الإلكتروني](/agenteye/images/login.png) --- ## الوصول المحدود باستخدام مفاتيح API -يقوم كل عميل بالمصادقة باستخدام مفتاح API يحمل أذونات دقيقة وذات امتيازات محدودة. يحتاج المجمِّع فقط إلى `events:add`؛ يمكن أن يكون مفتاح لوحة التحكم أو المساعد بقراءة فقط؛ الإجراءات الضارة (الحذف وإعادة التوليد) هي منح منفصلة تختار تضمينها. +يقوم كل عميل بالمصادقة باستخدام مفتاح API يحمل أذونات دقيقة وقليلة الامتيازات. يحتاج جامع البيانات فقط إلى `events:add`؛ يمكن أن تكون مفاتيح لوحة المعلومات أو المساعد للقراءة فقط؛ الإجراءات المفيدة (حذف، إعادة إنشاء) هي منح منفصل تختار تضمينه. -![صفحة مفاتيح API: منحات أذونات كل مفتاح، مرمّزة بألوان حسب نطاق القراءة والكتابة والتدمير](/agenteye/images/api-keys.png) +![صفحة مفاتيح API: منح الأذونات لكل مفتاح، مشفرة بألوان حسب نطاق القراءة والكتابة والمفيد](/agenteye/images/api-keys.png) -احتفظ بمفتاح bootstrap الإداري للإعداد، واستخدم مفاتيح محدودة لكل شيء آخر. انظر [مفاتيح API](/ar/agenteye/api-keys). +احتفظ بمفتاح التمهيد الإداري للإعداد، وأصدر مفاتيح ضيقة لكل شيء آخر. انظر [مفاتيح API](/ar/agenteye/api-keys). --- -## مساعد بقراءة فقط وموافقة مبوابة +## مساعد للقراءة فقط وموافق عليه -يجيب [المساعد في لوحة التحكم](/ar/agenteye/assistant) على أسئلة حول بيانات عملك، لكنه مقيد بالتصميم: +يجيب [المساعد الذكي](/ar/agenteye/assistant) في لوحة المعلومات على أسئلة حول بيانتك، لكنه محدود بالتصميم: -- أنه **بقراءة فقط افتراضياً**: SQL الخاص به يمر عبر حراس يسمح فقط باستعلامات `SELECT`/`WITH`، بيان واحد، مع حد أقصى للصفوف. -- أي شيء ينشئه (استعلام محفوظ، لوحة تحكم) هو **موافقة مبوابة**: تراجع وتوافق على كل عملية كتابة قبل حدوثها. -- أنه **لا يمكنه أبداً الحذف**. +- إنه **للقراءة فقط بشكل افتراضي**: يعمل SQL الخاص به من خلال حارس يسمح فقط باستعلامات `SELECT`/`WITH`، بيان واحد، مع حد للصفوف. +- أي شيء ينشئه (استعلام محفوظ، لوحة معلومات) هو **موافق عليه**: تراجع وتوافق على كل كتابة قبل حدوثها. +- **لا يمكنه حذف**. -لذا يمكن لزميل في الفريق أن يسأل "أي وكلاء أخطؤوا أكثر هذا الأسبوع؟" والتصرف بناءً على الإجابة، دون أن يتمكن المساعد من تغيير أو إزالة بيانات عملك بمفرده. +بحيث يمكن لزميل أن يسأل "ما الوكلاء الذين حدثت لهم معظم الأخطاء هذا الأسبوع؟" والتصرف على أساس الإجابة، دون أن يتمكن المساعد من تغيير أو إزالة بيانتك من تلقاء نفسه. --- -## في النقل +## أثناء النقل -كل حركة المرور تعمل عبر HTTPS. تقوم بإنهاء TLS باستخدام شهاداتك الخاصة، لذلك يتم تشفير حركة المرور من المجمِّع إلى الخادم ومن المتصفح إلى الخادم أثناء النقل. +تعمل جميع حركة المرور عبر HTTPS. تنهي TLS باستخدام شهاداتك الخاصة، بحيث يتم تشفير حركة المرور من جامع البيانات إلى الخادم ومن المتصفح إلى الخادم أثناء النقل. --- ## الخطوات التالية -- [نظرة عامة](/ar/agenteye/overview): كيف تتناسب Failproof AI Observability معاً. -- [مفاتيح API](/ar/agenteye/api-keys): تحديد نطاق الوصول للمجمِّع ولوحة التحكم والمساعد. -- [القابلية للملاحظة](/ar/agenteye/observability): ما تلتقطه Failproof AI Observability من وكلائك. \ No newline at end of file +- [نظرة عامة](/ar/agenteye/overview): كيفية عمل Failproof AI Observability معاً. +- [مفاتيح API](/ar/agenteye/api-keys): تحديد نطاق الوصول لجامع البيانات ولوحة المعلومات والمساعد. +- [الرصد](/ar/agenteye/observability): ما يلتقطه Failproof AI Observability من وكلائك. \ No newline at end of file diff --git a/docs/ar/agenteye/sessions.mdx b/docs/ar/agenteye/sessions.mdx index 48d6bfb0..9149e803 100644 --- a/docs/ar/agenteye/sessions.mdx +++ b/docs/ar/agenteye/sessions.mdx @@ -1,58 +1,58 @@ --- --- -title: "الجلسات ورسم البياني للتنفيذ" -description: "كل حدث من تشغيل، مجموع في صف واحد قابل للقراءة ورسم له كرسم بياني للتنفيذ بنمط git يمكنك قراءته في ثوان." +title: "الجلسات والرسم البياني للتنفيذ" +description: "كل حدث من تشغيل واحد مجمع في صف واحد سهل القراءة ومرسوم كرسم بياني للتنفيذ بنمط git يمكنك قراءته في ثوانٍ." --- -توقف عن التخمين حول سبب فشل التشغيل. تجميع بيانات Failproof AI كل حدث من تشغيل في صف واحد قابل للقراءة، ثم يرسم التشغيل بالكامل كصورة بنمط git يمكنك قراءتها في ثوان، حتى تشاهد بالضبط ما فعله وكيلك، خطوة تلو الأخرى. +توقف عن التخمين لماذا فشل التشغيل. يجمع Failproof AI Observability كل حدث من التشغيل في صف واحد سهل القراءة، ثم يرسم التشغيل بالكامل كصورة بنمط git يمكنك قراءتها في ثوانٍ، حتى ترى بالضبط ما فعله وكيلك، خطوة بخطوة. ![قائمة الجلسات: صف واحد لكل تشغيل، عبر البيئات والوكلاء، مع شارات الحالة وشارات درجات التقييم](/agenteye/images/sessions-list.png) -*صف واحد لكل تشغيل: شارة الحالة تخبرك كيف انتهى التشغيل للوهلة الأولى، وشارة درجة تظهر بجانبه بمجرد توصيل محيّم.* +*صف واحد لكل تشغيل: شارة الحالة توضح لك كيف انتهى التشغيل في لمحة، وتظهر شارة درجة واحدة بمجرد توصيل مقيّم.*
-*تتبع الوكيل: تابع تشغيل واحد خطوة تلو الأخرى، من الهدف إلى الأدوات إلى الإجابة النهائية.* +*تتبع الوكيل: اتبع تشغيل واحد خطوة بخطوة، من الهدف إلى الأدوات إلى الإجابة النهائية.* --- -## شاهد كل تشغيل للوهلة الأولى +## شاهد كل تشغيل في لمحة -مسار الأحداث الخام هو حقيقة كل خطوة، لكن عندما يكون لديك آلاف الخطوات عبر عشرات التشغيلات، تحتاج إلى التشغيل وليس الخطوة. تجمع صفحة الجلسات كل أحداث التشغيل في صف واحد، بحيث يصبح يوم من النشاط قائمة قابلة للمسح بدلاً من فيضان. +مسار الأحداث الخام هو حقيقة كل خطوة، لكن عندما يكون لديك آلاف الخطوات عبر عشرات التشغيلات، تحتاج التشغيل وليس الخطوة. تجمع صفحة الجلسات جميع أحداث التشغيل في صف واحد، بحيث يصبح يوم من النشاط قائمة قابلة للمسح بدلاً من فيضان من البيانات. -كل صف يحمل شارة حالة، بحيث يبرز التشغيل الفاشل عن التشغيل الصحي قبل أن تنقر على أي شيء. صفّ حسب نطاق التاريخ أو البيئة أو الوكيل أو الجلسة للانتقال من "كل شيء" إلى "التشغيل الذي أهتم به" في بضع نقرات. +يحمل كل صف شارة حالة، لذا يبرز التشغيل الفاشل عن الصحي قبل أن تنقر على أي شيء. قم بالتصفية حسب نطاق التاريخ أو البيئة أو الوكيل أو الجلسة للانتقال من "كل شيء" إلى "التشغيل الذي يهمني" بنقرات قليلة. -بمجرد توصيل محيّم، يتم تسجيل كل تشغيل مكتمل تلقائياً وتظهر أحدث درجاته على الصف كشارة. يمكنك التصفية حسب أي نطاق درجات، بحيث يصبح "أظهر لي كل تشغيل إنتاجي ذي درجة منخفضة هذا الأسبوع" فلتراً وليس مراجعة يدوية. حتى تقوم بإعداد واحد، لا تزال الجلسات تلتقط التشغيل الكامل؛ فقط لا تحمل درجة حتى الآن. +بمجرد توصيل مقيّم، يتم تقييم كل تشغيل مكتمل تلقائياً وتظهر أحدث درجة له على الصف كشارة. يمكنك التصفية حسب أي نطاق درجات، لذا فإن "أظهر لي كل تشغيل إنتاج منخفض الدرجات هذا الأسبوع" هو مرشح وليس مراجعة يدوية. حتى قبل إعداد واحد، تلتقط الجلسات التشغيل الكامل؛ فقط لا تحمل درجة حتى الآن. --- ## اقرأ التشغيل بالكامل كصورة -![رسم البياني للتنفيذ بنمط git بجانب الجدول الزمني للأحداث، مع لوحة تفصيل الأداة والنموذج والـ hook](/agenteye/images/session-detail.png) +![رسم بياني للتنفيذ بنمط git للجلسة بجانب مخطط الحدث الزمني الخاص به، مع لوحة تفصيل الأدوات والنموذج والخطاف](/agenteye/images/session-detail.png) -*رسم البياني للتنفيذ (اليسار) يجلس بجانب الجدول الزمني للأحداث؛ الشريط الأيمن يفصل الأدوات والنماذج والـ hooks وإنفاق الرموز للتشغيل.* +*يقع الرسم البياني للتنفيذ (يسار) بجانب مخطط الحدث الزمني؛ يقسم السكة اليمنى الأدوات والنماذج والخطافات ونفقات الرموز للتشغيل.* -انقر على أي جلسة لفتح رسم البياني للتنفيذ: عرض بنمط git لكيفية تطور الوكلاء والأدوات والـ hooks واستدعاءات النموذج عبر الزمن. كل وكيل فرعي متوازي ينقسم إلى مساره الخاص، حتى تتمكن من رؤية أي عمل تم تشغيله جنباً إلى جنب، أي وكيل فرعي توقف، وأين انحرف التشغيل عن الطريق، دون إعادة تشغيله في رأسك من جدار السجلات. +انقر على أي جلسة لفتح رسمها البياني للتنفيذ: عرض بنمط git لكيفية تطور الوكلاء والأدوات والخطافات واستدعاءات النموذج بمرور الوقت. يتفرع كل وكيل فرعي إلى مساره الخاص، حتى تتمكن من رؤية الأعمال التي تمت بالتوازي، وأي وكيل فرعي توقف، وأين انحرف التشغيل، دون إعادة تشغيله في ذهنك من جدار من السجلات. -يعطيك الشريط الأيمن التفصيل لكل تشغيل: أي أدوات ونماذج تم تشغيلها، أي hooks أُطلق، وما أنفقه التشغيل في الرموز. هذا هو الجواب على "لماذا كلف هذا التشغيل الكثير؟" أو "أي أداة هي البطيئة؟" يجلس بجانب الرسم البياني الذي سببه. +توفر السكة اليمنى تفصيل كل تشغيل: الأدوات والنماذج التي تم تشغيلها، الخطافات التي تم تشغيلها، وما أنفقه التشغيل في الرموز. هذا هو جواب "لماذا كلف هذا التشغيل الكثير؟" أو "أي أداة بطيئة؟" يجلس بجانب الرسم البياني الذي سبب ذلك. -الأحداث الفردية قابلة للعنونة، بحيث يمكنك إعطاء شخص ما رابطاً إلى لحظة واحدة بدلاً من "الجلسة، حوالي ثلثي الطريق لأسفل". انسخ الرابط من أي حدث، أو اتبع واحداً من نتيجة [audit](/ar/agenteye/audits) أو خطأ، وستفتح الجلسة مع تحديد هذا الحدث والتمرير إليه. هذا ينطبق على التشغيلات الطويلة جداً أيضاً: الجدول الزمني يحمّل نافذة محدودة من أجل متصفحك، والرابط الذي يشير إلى ما وراء تلك النافذة يجد حدثه بدلاً من إسقاطك في البداية. إذا كان الحدث قد تقادم خارج نافذة الاحتفاظ بك، تخبرك الصفحة بذلك بدلاً من اختيار أي شيء بصمت. +الأحداث الفردية قابلة للعنونة، حتى تتمكن من إعطاء شخص ما رابط إلى لحظة واحدة بدلاً من "الجلسة، حول ثلثي الطريق لأسفل". انسخ الرابط من أي حدث، أو اتبع واحد من النتيجة [audit](/ar/agenteye/audits) أو خطأ، وتفتح الجلسة مع تحديد هذا الحدث والتمرير إليه. هذا ينطبق على التشغيلات الطويلة جداً أيضاً: يتحمل الخط الزمني نافذة محدودة من أجل متصفحك، والرابط الذي يشير بعد تلك النافذة لا يزال يجد حدثه بدلاً من إسقاطك في البداية. إذا تقادم الحدث خارج نافذة الاحتفاظ الخاصة بك، تخبرك الصفحة بذلك بدلاً من اختيار لا شيء بهدوء. --- ## حيث تجده -كل صفحة لوحة معلومات مرتبطة بمنظمتك (`//…`). الجلسات تعيش تحت **Observe** في الشريط الجانبي الأيسر، بجانب الأحداث، مع فلاتر نطاق التاريخ والبيئة والوكيل والجلسة عبر أعلى القائمة. كل صف هو نقرة واحدة من رسم البياني الكامل للتنفيذ. +كل صفحة لوحة تحكم مضبوطة على مؤسستك (`//…`). تعيش الجلسات تحت **Observe** في الشريط الجانبي الأيسر، بجانب الأحداث، مع مرشحات نطاق التاريخ والبيئة والوكيل والجلسة عبر أعلى القائمة. كل صف بنقرة واحدة من رسمه البياني للتنفيذ الكامل. -لتشغيل شارات الدرجات وتصفية نطاق الدرجات، اتصل بمحيّم: انظر [Evaluations](/ar/agenteye/evaluations). +لتشغيل شارات الدرجات والتصفية حسب نطاق الدرجات، قم بتوصيل مقيّم: انظر [Evaluations](/ar/agenteye/evaluations). --- ## ذات صلة -- [تدفق الأحداث](/ar/agenteye/event-stream): مسار كل خطوة الخام الذي يتم تجميع كل جلسة منه. -- [التقييمات](/ar/agenteye/evaluations): اتصل بمحيّم حتى يحصل كل تشغيل على شارة درجة يمكنك التصفية بها. -- [التلمترة](/ar/agenteye/telemetry): كيف ينتقل التشغيل من وكيلك إلى هذه الجلسات. \ No newline at end of file +- [Event stream](/ar/agenteye/event-stream): مسار الخطوة الخام لكل جلسة يتم تجميعها منه. +- [Evaluations](/ar/agenteye/evaluations): قم بتوصيل مقيّم بحيث يحصل كل تشغيل على شارة درجة يمكنك التصفية بواسطتها. +- [Telemetry](/ar/agenteye/telemetry): كيفية انتقال التشغيلات من وكيلك إلى هذه الجلسات. \ No newline at end of file diff --git a/docs/ar/agenteye/telemetry.mdx b/docs/ar/agenteye/telemetry.mdx index 8648e842..4dc169e9 100644 --- a/docs/ar/agenteye/telemetry.mdx +++ b/docs/ar/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- title: "مقاييس الأداء" -description: "اكتشف اللحظة التي تبطئ فيها نماذجك أو أدواتك أو خطافاتك أو تزيد الفواتير، واعترض قفزة الكمون النهائي قبل أن يشعر بها مستخدموك." +description: "شاهد اللحظة التي تبطأ فيها نماذجك أو أدواتك أو خطافاتك أو ترفع الفواتير، واكتشف ارتفاع زمن الاستجابة في الطرف قبل أن يشعر به مستخدموك." --- -اكتشف اللحظة التي تبطئ فيها نماذجك أو أدواتك أو خطافاتك أو تزيد الفواتير، واعترض قفزة الكمون النهائي قبل أن يشعر بها مستخدموك. ثلاث صفحات مخصصة تحول التوقيتات الخام إلى p50 و p95 و p99 يمكنك قراءتها في لمحة. +شاهد اللحظة التي تبطأ فيها نماذجك أو أدواتك أو خطافاتك أو ترفع الفواتير، واكتشف ارتفاع زمن الاستجابة في الطرف قبل أن يشعر به مستخدموك. تحول ثلاث صفحات مخصصة التوقيتات الخام إلى p50 و p95 و p99 يمكنك قراءتها في لمحة سريعة. -![صفحة النماذج تعرض خريطة حرارية للكمون، وشريط مئوي، وأرقام التوكن والتكلفة والنافذة السياقية لكل نموذج](/agenteye/images/models.png) -*صفحة النماذج: خريطة حرارية للكمون، وشريط مئوي، وأرقام التوكن والتكلفة المقدرة ومؤشر امتلاء النافذة السياقية لكل نموذج.* +![صفحة النماذج تعرض خريطة حرارية لزمن الاستجابة، وشريط مئوي، وأرقام الرموز والتكلفة وملء نافذة السياق لكل نموذج](/agenteye/images/models.png) +*صفحة النماذج: خريطة حرارية لزمن الاستجابة، وشريط مئوي، والرموز لكل نموذج والتكلفة المقدرة وملء نافذة السياق.* ## توقف عن السماح للمتوسطات بإخفاء أسوأ عملياتك -رقم متوسط الكمون مريح وعديم الفائدة: فهو يمسح على ما يحدث في واحدة من كل خمسين استدعاء تتعطل وتنبهك في الساعة الثانية صباحًا. صفحات النماذج والأدوات والخطافات ترفض أن تفعل ذلك. كل منها تشترك في نفس الشكل، لذلك تتعلمها مرة واحدة: +رقم متوسط زمن الاستجابة مريح وعديم الفائدة: فهو يخفي استدعاءً واحداً من كل خمسين يتعطل ويصرخ في الساعة الثانية صباحاً. صفحات النماذج والأدوات والخطافات ترفض أن تفعل ذلك. كل منها يشترك في نفس الشكل، لذا تتعلمه مرة واحدة: -- **رسم بياني صغير بـ 24 فئة** للاتجاه في لمحة: هل يزداد سوءًا؟ -- **شريط الحيويات** مع كمون p50 و p95 و p99، بحيث تجلس العملية النموذجية والنهاية جنبًا إلى جنب. -- **خريطة حرارية للكمون**، 24 فئة زمنية حسب فئات الكمون، التي تظهر *متى* تجمعت الاستدعاءات البطيئة. -- **شريط مئوي**: خط p50 مع شرائط مظللة p25 إلى p75 و p10 إلى p90 ونقاط p99، بحيث يبقى الانتشار مرئيًا بدلاً من أن يتم حساب متوسطه. +- **رسم بياني صغير بـ 24 صندوق** للاتجاه في لمحة سريعة: هل يزداد سوءاً؟ +- **شريط الحيويات** مع زمن استجابة p50 و p95 و p99، بحيث تجلس التشغيلة النموذجية والطرف جنباً إلى جنب. +- **خريطة حرارية لزمن الاستجابة**، 24 صندوق زمني على طول رزم زمن الاستجابة، يوضح *متى* تجمعت الاستدعاءات البطيئة. +- **شريط مئوي**: خط p50 مع شرائط p25 إلى p75 و p10 إلى p90 مظللة وحقاط p99، بحيث يظل الانتشار مرئياً بدلاً من أن يتم حسابه بمتوسط. -مؤشر تحرك مشترك يربط الخريطة الحرارية والشريط، بحيث يتم توصيل قفزة النهاية في الوقت عبر كليهما بدلاً من الاختباء خلف خط متوسط واحد. ابحث عن الصفحات الثلاث جميعها في قسم **المراقبة** في لوحة معلوماتك، كل منها محدد نطاق لمؤسستك وقابل للتصفية حسب نطاق التاريخ والبيئة والوكيل والجلسة. +يربط شريط المؤشر المشترك عند التحويم الخريطة الحرارية والشريط، بحيث يصطف ارتفاع الطرف بمرور الوقت عبر كلاهما بدلاً من الاختباء خلف خط متوسط واحد. ابحث عن الصفحات الثلاث في قسم **المراقبة** من لوحة التحكم الخاصة بك، كل منها مقيد بمنظمتك وقابل للتصفية حسب نطاق التاريخ والبيئة والوكيل والجلسة. -## النماذج: اكتشف بالضبط تكلفة كل نموذج +## النماذج: شاهد بالضبط ما يكلفك كل نموذج -صفحة النماذج (كما هو موضح أعلاه) تجيب على السؤالين اللذين تطرحهما الفاتورة دائمًا: أي نموذج وكم التكلفة. بالإضافة إلى عرض الكمون المشترك، فإنها تضيف **استهلاك التوكن لكل نموذج** و **التكلفة المقدرة** و **مؤشر امتلاء النافذة السياقية**، بحيث يكون نمو الطلب الجامح واقتراب الضغط مرئيًا قبل أن يفاجئك. +تجيب صفحة النماذج (الموضحة أعلاه) عن السؤالين اللذين ترفعهما الفاتورة دائماً: أي نموذج، وكم. بالإضافة إلى عرض زمن الاستجابة المشترك، تضيف **استهلاك الرموز لكل نموذج** و **التكلفة المقدرة** و **ملء نافذة السياق**، بحيث يكون نمو الفوري الجامح وضغط قادم مرئياً قبل أن يفاجئك. -يتعرف Failproof AI Observability على معرّفات النماذج الشائعة تلقائيًا. إذا بدت نافذة غير صحيحة، أو كنت تشغل نموذجك الخاص، قم بتصحيحها أو أضف واحدة ضمن **الإعدادات** في **نوافذ السياق للنموذج** والقراءات المتعلقة بالامتلاء تتبع. +يعترف Failproof AI Observability بمعرفات النموذج الشائعة تلقائياً. إذا بدت النافذة خاطئة، أو كنت تشغل نموذجاً خاصاً بك، صححها أو أضف واحداً تحت **الإعدادات**، في **نوافذ السياق للنموذج**، وتتبع قراءات الملء. -## الأدوات: ميز البطيء عن المكسور +## الأدوات: ميز البطيء عن المعطل -يمكن أن تكون استدعاءة الأداة بطيئة، أو قد تفشل بهدوء، وتريد أن تعرف أيهما في ثوانٍ، وليس بعد البحث في السجلات. +يمكن أن تكون استدعاءة الأداة بطيئة، أو قد تفشل بهدوء، وتريد أن تعرف أيهما في ثوان، وليس بعد الحفر عبر السجلات. -![صفحة الأدوات تعرض خريطة الكمون الحرارية المشتركة وشريط المئويات بجانب تفصيل النجاح والفشل وشريط توزيع الأدوات](/agenteye/images/tools.png) +![صفحة الأدوات تعرض خريطة حرارية مشتركة لزمن الاستجابة وشريط مئوي بجانب تفصيل النجاح والفشل وشريط توزيع الأدوات](/agenteye/images/tools.png) *صفحة الأدوات: نفس الخريطة الحرارية والشريط المئوي، بالإضافة إلى تفصيل النجاح والفشل وشريط توزيع الأدوات.* -إلى جانب عرض الكمون المشترك، تضيف صفحة الأدوات **تفصيل النجاح والفشل** و **شريط توزيع الأدوات**، بحيث ترى في لمحة الأدوات التي تعتمد عليها أكثر والتي تستنزف ميزانية الخطأ الخاصة بك. +إلى جانب عرض زمن الاستجابة المشترك، تضيف صفحة الأدوات **تفصيل النجاح والفشل** و **شريط توزيع الأدوات**، بحيث ترى في لمحة سريعة الأدوات التي تعتمد عليها أكثر وأيها تأكل ميزانية الأخطاء الخاصة بك. -## الخطافات: حدد الخطاف المحدد وحدث التفعيل +## الخطافات: حدد الخطاف الدقيق وحدث التفعيل -عندما يبطئ خطاف دورة حياة عملية ما، "الخطافات بطيئة" ليس شيئًا يمكنك العمل عليه. تأخذك صفحة الخطافات إلى الواحد الذي يهمك. +عندما يسحب خطاف دورة الحياة تشغيلة، لا يمكنك العمل على لا شيء من "الخطافات بطيئة". تحصل صفحة الخطافات على الواحد الذي يهمك. -![صفحة الخطافات تعرض الكمون مقسم حسب اسم الخطاف وحدث التفعيل على خريطة الكمون الحرارية المشتركة والشريط المئوي](/agenteye/images/hooks.png) -*صفحة الخطافات: الكمون مقسم حسب اسم الخطاف وحدث التفعيل.* +![صفحة الخطافات تعرض زمن الاستجابة مقسم حسب اسم الخطاف وحدث التفعيل على الخريطة الحرارية المشتركة والشريط المئوي](/agenteye/images/hooks.png) +*صفحة الخطافات: زمن الاستجابة مقسم حسب اسم الخطاف وحدث التفعيل.* -فوق نفس خريطة الكمون الحرارية والشريط المئوي، تقسم صفحة الخطافات النشاط حسب **اسم الخطاف** و **حدث التفعيل**، بحيث تهبط على الخطاف الواحد وحدث التفعيل الواحد اللذين يحتاجان إلى انتباه. +على نفس خريطة زمن الاستجابة الحرارية والشريط المئوي، تقسم صفحة الخطافات النشاط حسب **اسم الخطاف** و **حدث التفعيل**، بحيث تصل إلى الخطاف الفردي وحدث التفعيل الفردي الذي يحتاج إلى انتباه. -## ذات صلة +## مرتبط -- [دفق الأحداث](/ar/agenteye/event-stream): المسار الفوري الملون لكل حدث. -- [الجلسات](/ar/agenteye/sessions): قم بتجميع الأحداث في صف واحد لكل تشغيل وافتح رسم البياني الخاص به. -- [تتبع الأخطاء](/ar/agenteye/error-tracking): سطح تريج واحد لكل شيء يرسمه لوحة المعلومات باللون الأحمر. -- [لوحات المعلومات](/ar/agenteye/dashboards): طرق التجميع عبر أسطولك. \ No newline at end of file +- [دفق الأحداث](/ar/agenteye/event-stream): مسار مشفر بالألوان مباشر لكل حدث. +- [الجلسات](/ar/agenteye/sessions): جمع الأحداث في صف واحد لكل تشغيلة وفتح رسمها البياني للتنفيذ. +- [تتبع الأخطاء](/ar/agenteye/error-tracking): سطح فرز واحد لكل ما تضعه لوحة التحكم علامة باللون الأحمر. +- [لوحات التحكم](/ar/agenteye/dashboards): عروض ملخصة عبر أسطولك. \ No newline at end of file diff --git a/docs/ar/architecture.mdx b/docs/ar/architecture.mdx index 14dbddb2..756aa899 100644 --- a/docs/ar/architecture.mdx +++ b/docs/ar/architecture.mdx @@ -1,11 +1,11 @@ --- --- -title: المعمارية -description: "كيف يعمل معالج الخطاف وتحميل الإعدادات وتقييم السياسات داخليًا" +title: العمارة +description: "كيفية عمل معالج الخطاف وتحميل الإعدادات وتقييم السياسات بشكل داخلي" icon: sitemap --- -تشرح هذه الوثيقة كيف يعمل failproofai داخليًا: كيف يعترض نظام الخطاف استدعاءات أدوات الوكيل، وكيف يتم تحميل ودمج الإعدادات، وكيف يتم تقييم السياسات، وكيف تراقب لوحة المعلومات نشاط الوكيل. +تشرح هذه الوثيقة كيفية عمل failproofai بشكل داخلي: كيف يعترض نظام الخطافات استدعاءات أدوات الوكيل، وكيف يتم تحميل الإعدادات ودمجها، وكيفية تقييم السياسات، وكيف تراقب لوحة التحكم نشاط الوكيل. --- @@ -13,10 +13,10 @@ icon: sitemap يحتوي failproofai على نظامين فرعيين مستقلين: -1. **معالج الخطاف** - عملية CLI سريعة يستدعيها Claude Code عند كل استدعاء لأداة الوكيل. يقيّم السياسات ويعيد قرارًا. -2. **مراقب الوكيل (لوحة المعلومات)** - تطبيق ويب Next.js لمراقبة جلسات الوكيل وإدارة السياسات. +1. **معالج الخطاف** - عملية CLI سريعة يستدعيها Claude Code على كل استدعاء أداة وكيل. تقيّم السياسات وتعيد قرار. +2. **مراقب الوكيل (لوحة التحكم)** - تطبيق ويب Next.js لمراقبة جلسات الوكيل وإدارة السياسات. -يشترك كلا النظام الفرعي في ملفات الإعدادات في `~/.failproofai/` وفي مجلد `.failproofai/` للمشروع، لكنهما يعملان كعمليتين منفصلتين ولا يتواصلان إلا من خلال نظام الملفات. +يشترك كلا النظامين الفرعيين في ملفات الإعدادات في `~/.failproofai/` ومجلد `.failproofai/` في المشروع، لكنهما يعملان كعمليات منفصلة ويتواصلان فقط عبر نظام الملفات. --- @@ -45,9 +45,9 @@ icon: sitemap } ``` -ثم يستدعي Claude Code `failproofai --hook PreToolUse` كعملية فرعية قبل كل استدعاء أداة، ويمرر حمولة JSON على stdin. +ثم يستدعي Claude Code `failproofai --hook PreToolUse` كعملية فرعية قبل كل استدعاء أداة، مرراً حمولة JSON على stdin. -### تنسيق الحمولة +### صيغة الحمولة ```json { @@ -61,13 +61,13 @@ icon: sitemap } ``` -بالنسبة لأحداث `PostToolUse`، تحتوي الحمولة أيضًا على `tool_result` يحتوي على مخرجات الأداة. +بالنسبة لأحداث `PostToolUse`، تحتوي الحمولة أيضاً على `tool_result` بمخرجات الأداة. -يفرض المعالج حدًا بحجم 1 ميجابايت لـ stdin. الحمولات التي تتجاوز هذا الحد يتم تجاهلها وجميع السياسات تسمح ضمنيًا. +يفرض المعالج حد أقصى 1 ميجابايت لـ stdin. يتم تجاهل الحمولات التي تتجاوز هذا الحد وجميع السياسات بشكل ضمني تسمح. -### تنسيق الاستجابة +### صيغة الاستجابة -**الرفض (PreToolUse):** +**رفض (PreToolUse):** ```json { "hookSpecificOutput": { @@ -77,7 +77,7 @@ icon: sitemap } ``` -**الرفض (PostToolUse):** +**رفض (PostToolUse):** ```json { "hookSpecificOutput": { @@ -86,7 +86,7 @@ icon: sitemap } ``` -**التعليمات (أي حدث باستثناء Stop):** +**تعليمات (أي حدث ما عدا Stop):** ```json { "hookSpecificOutput": { @@ -95,9 +95,9 @@ icon: sitemap } ``` -**حدث التعليمات من النوع Stop:** +**تعليمات حدث الإيقاف:** - رمز الخروج: `2` -- السبب مكتوب على stderr (وليس stdout) +- السبب مكتوب إلى stderr (وليس stdout) **السماح:** - رمز الخروج: `0` @@ -105,7 +105,7 @@ icon: sitemap **السماح مع رسالة:** -`allow(message)` تتيح لسياسة ما إرسال سياق معلوماتي إلى Claude حتى عندما تكون العملية مسموحة. يكتب معالج الخطاف JSON التالي إلى **stdout** (وليس ملف إعدادات — هذه استجابة المعالج لـ Claude Code، تمامًا مثل استجابات الرفض والتعليمات أعلاه): +`allow(message)` يسمح بأن تعيد سياسة ما سياق معلومات إلى Claude حتى عند السماح بالعملية. يكتب معالج الخطاف JSON التالي إلى **stdout** (وليس ملف إعدادات — هذا هو استجابة المعالج لـ Claude Code، تماماً مثل استجابات الرفض والتعليمات أعلاه): ```json // Written to stdout by the hook handler process @@ -116,12 +116,12 @@ icon: sitemap } ``` - رمز الخروج: `0` (العملية مسموحة) -- عندما تعيد عدة سياسات `allow` برسالة، يتم دمج رسائلها بفواصل أسطر في سلسلة `additionalContext` واحدة -- إذا لم توفر أي سياسة رسالة، يكون stdout فارغًا (كما هو قبل ذلك) +- عند إرجاع عدة سياسات `allow` برسالة، يتم دمج رسائلهم بفواصل أسطر جديدة في سلسلة `additionalContext` واحدة +- إذا لم توفر أي سياسة رسالة، يكون stdout فارغاً (مثل السابق) ### خط معالجة -يُطبّق `src/hooks/handler.ts` خط المعالجة الكامل: +`src/hooks/handler.ts` ينفذ خط المعالجة الكامل: ```text stdin JSON @@ -146,7 +146,7 @@ stdin JSON ## تحميل الإعدادات -يُطبّق `src/hooks/hooks-config.ts` تحميل الإعدادات ثلاثي النطاق. +`src/hooks/hooks-config.ts` ينفذ تحميل إعدادات بثلاث نطاقات. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -155,39 +155,39 @@ stdin JSON ``` منطق الدمج: -- `enabledPolicies` - اتحاد مزيل للتكرار عبر الملفات الثلاثة -- `policyParams` - لكل سياسة، الملف الأول الذي يعرّفها يفوز بالكامل +- `enabledPolicies` - اتحاد مزيل للتكرار عبر جميع الملفات الثلاثة +- `policyParams` - لكل سياسة، الملف الأول الذي يعرّفه يفوز كلياً - `customPoliciesPath` - الملف الأول الذي يعرّفه يفوز - `llm` - الملف الأول الذي يعرّفه يفوز -تستخدم لوحة معلومات الويب `readHooksConfig()` (عام فقط) للقراءة والكتابة، لأنها لا تُستدعى مع cwd للمشروع. +تستخدم لوحة تحكم الويب `readHooksConfig()` (عام فقط) للقراءة والكتابة، لأنها لا تُستدعى مع cwd مشروع. --- ## تقييم السياسات -يُشغّل `src/hooks/policy-evaluator.ts` السياسات بالترتيب. +`src/hooks/policy-evaluator.ts` ينفذ السياسات بالترتيب. لكل سياسة: 1. ابحث عن مخطط `params` الخاص بالسياسة (إن كان لديها واحد). 2. اقرأ `policyParams[policy.name]` من الإعدادات المدمجة. -3. ادمج القيم المعطاة من المستخدم فوق قيم المخطط الافتراضية لإنتاج `ctx.params`. -4. استدعِ `policy.fn(ctx)` مع السياق المُحل. -5. إذا كانت النتيجة `deny`، توقف فورًا وأعد هذا القرار. +3. ادمج القيم المقدمة من المستخدم فوق قيم الافتراضي للمخطط لإنتاج `ctx.params`. +4. استدعِ `policy.fn(ctx)` مع السياق المحل. +5. إذا كانت النتيجة `deny`، توقف فوراً وأرجع هذا القرار. 6. إذا كانت النتيجة `instruct`، اجمع الرسالة واستمر. 7. إذا كانت النتيجة `allow`، انتقل إلى السياسة التالية. -بعد تشغيل جميع السياسات: -- إذا تم إرجاع أي `deny`، أصدر استجابة الرفض. -- إذا تم جمع أي إرجاعات `instruct`، أصدر استجابة تعليمات واحدة مع دمج جميع الرسائل. -- خلاف ذلك، أصدر استجابة سماح (stdout فارغ، الخروج 0). +بعد تنفيذ جميع السياسات: +- إذا تم إرجاع أي `deny`، أصدر استجابة رفض. +- إذا تم جمع أي عودات `instruct`، أصدر استجابة تعليمات واحدة مع دمج جميع الرسائل. +- وإلا، أصدر استجابة سماح (stdout فارغ، خروج 0). --- ## السياسات المدمجة -يُعرّف `src/hooks/builtin-policies.ts` جميع 39 سياسة مدمجة كائنات `BuiltinPolicyDefinition`: +`src/hooks/builtin-policies.ts` يعرّف جميع 39 سياسة مدمجة كائنات `BuiltinPolicyDefinition`: ```typescript interface BuiltinPolicyDefinition { @@ -205,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -السياسات التي تقبل `params` تُعلِن عن `PolicyParamsSchema` بأنواع وقيم افتراضية لكل معامل. يحقن مُقيّم السياسات القيم المُحلة في `ctx.params` قبل استدعاء `fn`. تقرأ دوال السياسة `ctx.params` دون حماية null لأن القيم الافتراضية يتم تطبيقها أولاً دائمًا. +السياسات التي تقبل `params` تعلن `PolicyParamsSchema` بأنواع وقيم افتراضية لكل معامل. معيّن السياسة يحقن القيم المحلة في `ctx.params` قبل استدعاء `fn`. تقرأ دوال السياسة `ctx.params` بدون حماية من null لأن القيم الافتراضية تُطبق دائماً أولاً. -يستخدم المطابقة النمطية داخل السياسات رموز الأوامر المُحللة (argv)، وليس المطابقة البسيطة للنصوص. يمنع هذا الالتفاف عبر حقن عاملي الصدفة (على سبيل المثال، نمط لـ `sudo systemctl status *` لا يمكن الالتفاف عليه بإضافة `; rm -rf /` إلى الأمر). +يستخدم مطابقة الأنماط داخل السياسات رموز الأوامر المحللة (argv)، وليس مطابقة السلاسل الخام. هذا يمنع المخاطر عبر حقن عامل Shell (مثلاً، نمط لـ `sudo systemctl status *` لا يمكن تجاوزه بإضافة `; rm -rf /` إلى الأمر). --- ## السياسات المخصصة -يُطبّق `src/hooks/custom-hooks-registry.ts` سجلاً يدعمه `globalThis`: +`src/hooks/custom-hooks-registry.ts` ينفذ سجل مدعوم بـ `globalThis`: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -226,25 +226,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // used in tests ``` -يحمّل `src/hooks/custom-hooks-loader.ts` ملف السياسة الخاص بالمستخدم: +`src/hooks/custom-hooks-loader.ts` يحمل ملف السياسة الخاص بالمستخدم: -1. اقرأ `customPoliciesPath` من الإعدادات؛ تخطَّ إذا كان غائبًا. -2. حلّ المسار المطلق؛ تحقق من وجود الملف. -3. أعد كتابة جميع واردات `from "failproofai"` إلى مسار dist الفعلي بحيث ينحل `customPolicies` إلى سجل `globalThis` نفسه. -4. أعد كتابة الواردات المحلية العابرة بشكل متكرر لضمان التوافق مع ESM. +1. اقرأ `customPoliciesPath` من الإعدادات؛ تجاهل إن كان غائباً. +2. احل إلى مسار مطلق؛ تحقق من وجود الملف. +3. أعد كتابة جميع استيرادات `from "failproofai"` إلى مسار dist الفعلي بحيث يحل `customPolicies` إلى سجل `globalThis` نفسه. +4. أعد كتابة الاستيرادات المحلية الانتقالية بشكل متكرر لضمان التوافق مع ESM. 5. اكتب ملفات `.mjs` مؤقتة و`import()` ملف الإدخال. 6. استدعِ `getCustomHooks()` لاسترجاع الخطافات المسجلة. 7. نظف جميع الملفات المؤقتة في كتلة `finally`. -عند حدوث أي خطأ (ملف غير موجود، خطأ في الصيغة، فشل في الاستيراد)، يتم تسجيل الخطأ إلى `~/.failproofai/hook.log` ويعيد المحمّل مصفوفة فارغة. السياسات المدمجة لا تتأثر. +في حالة حدوث أي خطأ (ملف غير موجود، خطأ صيغة، فشل الاستيراد)، يتم تسجيل الخطأ في `~/.failproofai/hook.log` ويعيد المحمل مصفوفة فارغة. السياسات المدمجة لا تتأثر. -يتم تقييم السياسات المخصصة بعد جميع السياسات المدمجة. رفض سياسة مخصصة لا يزال يعطل السياسات المخصصة الإضافية (لكن جميع المدمجات قد عملت بالفعل في تلك النقطة). +يتم تقييم السياسات المخصصة بعد جميع السياسات المدمجة. رفض سياسة مخصصة يقطع المزيد من السياسات المخصصة (لكن جميع المدمجات قد تم تنفيذها بالفعل في تلك النقطة). --- -## تسجيل النشاط +## تسجيل الأنشطة -بعد كل حدث خطاف، يضيف المعالج سطر JSONL إلى `~/.failproofai/hook-activity/current.jsonl`، والذي يدور إلى `page--.jsonl` بمجرد الوصول إلى صفحة: +بعد كل حدث خطاف، يضيف المعالج سطر JSONL إلى `~/.failproofai/hook-activity/current.jsonl`، الذي يدور إلى `page--.jsonl` بمجرد أن يصل إلى صفحة: ```json { @@ -259,13 +259,13 @@ export function clearCustomHooks(): void { ... } // used in tests } ``` -سطر واحد لكل سياسة أدت إلى قرار غير سماح. لا يتم تسجيل قرارات السماح (للحفاظ على صغر حجم الملف). +سطر واحد لكل سياسة أصدرت قرار غير السماح. قرارات السماح لا تُسجل (لإبقاء الملف صغيراً). --- -## معمارية لوحة المعلومات +## عمارة لوحة التحكم -لوحة المعلومات هي تطبيق **Next.js 16** يستخدم App Router مع React Server Components وServer Actions. +لوحة التحكم هي تطبيق **Next.js 16** يستخدم App Router مع React Server Components و Server Actions. ```text app/ @@ -287,16 +287,16 @@ app/ **تدفق البيانات:** -- تستدعي مكونات الصفحة `lib/projects.ts` و `lib/log-entries.ts` لقراءة بيانات المشروع/الجلسة مباشرة من نظام الملفات (بدون طبقة API للقراءات). -- تستخدم صفحة السياسات Server Actions لجميع التغييرات (تبديل، تحديث المعاملات، التثبيت/الإزالة). -- يُحلّل عارض الجلسة تنسيق النسخة JSONL من Claude ويعرض جدول زمني للرسائل واستدعاءات الأدوات. +- مكونات الصفحة تستدعي `lib/projects.ts` و `lib/log-entries.ts` لقراءة بيانات المشروع/الجلسة مباشرة من نظام الملفات (بدون طبقة API للقراءات). +- تستخدم صفحة السياسات Server Actions لجميع الطفرات (تبديل، تحديث المعاملات، تثبيت/إزالة). +- يحلل عارض الجلسة صيغة نص Claude JSONL ويعرض خط زمني للرسائل واستدعاءات الأدوات. **قرارات التصميم الرئيسية:** -- بدون قاعدة بيانات - جميع الحالة الدائمة في ملفات عادية (`~/.failproofai/`، `~/.claude/projects/`). -- Server Actions للتغييرات - لا حاجة لـ REST API لعمليات CRUD. -- React Server Components لصفحات القراءة - تحميل أولي أسرع، بدون مجموعة عميل للجلب البيانات. -- مكونات عميل فقط حيث يكون التفاعل مضروريًا (تبديلات السياسة، بحث النشاط، عارض السجل). +- لا قاعدة بيانات - جميع الحالات الدائمة في ملفات عادية (`~/.failproofai/`، `~/.claude/projects/`). +- Server Actions للطفرات - لا توجد حاجة لـ REST API لعمليات CRUD. +- React Server Components لصفحات القراءة - تحميل أولي أسرع، بدون حزمة عميل لجلب البيانات. +- مكونات العميل فقط حيث توجد حاجة للتفاعل (تبديلات السياسة، البحث في الأنشطة، عارض السجلات). --- diff --git a/docs/ar/built-in-policies.mdx b/docs/ar/built-in-policies.mdx index 357b3ed5..dc483c29 100644 --- a/docs/ar/built-in-policies.mdx +++ b/docs/ar/built-in-policies.mdx @@ -1,23 +1,23 @@ --- --- title: السياسات المدمجة -description: "جميع 39 سياسة مدمجة تلتقط أنماط فشل الوكيل الشائعة" +description: "جميع السياسات المدمجة الـ 39 التي تحتفظ بأنماط فشل الوكيل الشائعة" icon: shield --- -يأتي failproofai مع 39 سياسة مدمجة تلتقط أنماط فشل الوكيل الشائعة. كل سياسة تُطلق على نوع حدث hook معين واسم أداة معينة. تقبل تسع عشرة سياسة معاملات تتيح لك ضبط سلوكها دون كتابة أي كود. تفرض خمس سياسات سير عمل خط أنابيب commit → push → PR → CI قبل أن يتوقف Claude. +يأتي failproofai مع 39 سياسة مدمجة تحتفظ بأنماط فشل الوكيل الشائعة. تتفعل كل سياسة على نوع حدث hook محدد واسم أداة محدد. تقبل تسع عشرة سياسة معاملات تتيح لك ضبط سلوكها دون كتابة أي كود. تفرض خمس سياسات سير عمل ممر التزام → دفع → PR → CI قبل أن يتوقف Claude. --- ## نظرة عامة -تُجمع السياسات في فئات: +تُجمّع السياسات في فئات: | الفئة | السياسات | نوع Hook | |----------|----------|-----------| -| [الأوامر الخطرة](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | +| [الأوامر الخطيرة](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | | [أوامر البنية التحتية](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [الأسرار (المعالجات)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [الأسرار (المعقمات)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [البيئة](#environment) | block-env-files, protect-env-vars | PreToolUse | | [الوصول إلى الملفات](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | @@ -26,19 +26,18 @@ icon: shield | [مديري الحزم](#package-managers) | prefer-package-manager | PreToolUse | | [سير العمل](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — منع الوكيل من المتابعة. -- **`warn-`** — إعطاء الوكيل سياق إضافي حتى يتمكن من تصحيح نفسه. -- **`sanitize-`** — حذف البيانات الحساسة من إخراج الأداة قبل أن يراها الوكيل. +- **`block-`** — إيقاف الوكيل عن المتابعة. +- **`warn-`** — إعطاء الوكيل سياق إضافي ليتمكن من تصحيح نفسه. +- **`sanitize-`** — مسح البيانات الحساسة من مخرجات الأداة قبل أن يراها الوكيل. -### النطاقات +### المساحات -كل سياسة تعيش في فتحة `/`. تنتمي السياسات المدمجة إلى -النطاق **`failproofai/`** — على سبيل المثال، `failproofai/sanitize-jwt`. يمنع -النطاق التصادمات عند تحميل سياسات مخصصة أو من جهات خارجية +تعيش كل سياسة في فتحة `/`. تنتمي السياسات المدمجة إلى مساحة الأسماء +**`failproofai/`** — على سبيل المثال، `failproofai/sanitize-jwt`. تمنع مساحة الأسماء التضاربات عند تحميل سياسات مخصصة أو خارجية بأسماء قصيرة متشابهة. -في إعدادك يمكنك الإشارة إلى السياسة المدمجة باستخدام اسمها القصير أو -اسمها المؤهل؛ كلا النموذجين يحلان نفس السياسة: +في إعدادك، يمكنك الإشارة إلى سياسة مدمجة بأي من اسمها القصير أو اسمها +المؤهل؛ كلا الشكلين يتم حلهما للسياسة نفسها: ```json { @@ -49,41 +48,40 @@ icon: shield } ``` -إذا لم يكن للاسم علامة `/`، يعاملها failproofai كتابعة للنطاق الافتراضي -`failproofai`. الأسماء التي تحتوي بالفعل على `/` (مثل `myorg/foo`، -`custom/my-hook`) تُبقى كما هي. -- **`require-`** — منع حدث Stop حتى تُستوفى الشروط. +إذا لم يكن للاسم `/`، يعتبره failproofai كجزء من مساحة الأسماء الافتراضية `failproofai`. الأسماء التي تحتوي بالفعل على `/` (مثل `myorg/foo`، +`custom/my-hook`) يتم الاحتفاظ بها كما هي. +- **`require-`** — حجب حدث الإيقاف حتى تُستوفي الشروط. --- -تدعم كل سياسة حقل اختياري `hint` في `policyParams`. يُضاف التلميح إلى رسالة deny أو instruct التي يراها Claude، مما يوفر توجيهات قابلة للتنفيذ دون تعديل كود السياسة. يعمل مع السياسات المدمجة والمخصصة والاتفاقية. انظر [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل. +كل سياسة تدعم حقل `hint` اختياري في `policyParams`. يتم إلحاق التلميح برسالة deny أو instruct التي يراها Claude، مما يوفر إرشادات قابلة للعمل دون تعديل كود السياسة. يعمل مع السياسات المدمجة والمخصصة والاتفاقية. راجع [الإعدادات → hint](/ar/configuration#hint-cross-cutting) للمزيد من التفاصيل. --- -## الأوامر الخطرة +## الأوامر الخطيرة -منع الوكلاء من تشغيل عمليات يصعب التراجع عنها أو قد تضر النظام المضيف. +منع الوكلاء من تشغيل عمليات يصعب التراجع عنها أو قد تضر بنظام المضيف. ### `block-sudo` **الحدث:** PreToolUse (Bash) **الافتراضي:** يرفض أي أمر `sudo` أو `doas`. -يحجب أمر يشغل ملف تنفيذي للرفع في **موضع الأمر**. المطابقة هيكلية وليست نصية: يُقسم الأمر إلى قطاعات بالطريقة التي تقسمها shell، تُزال تعيينات البادئة (`FOO=bar`)، عمليات إعادة التوجيه، والمنفذات مع أعلامها (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …)، ويُقارن الملف التنفيذي الناتج **بالاسم الأساسي**. إذن `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` و `bash -c "sudo …"` كلها مرفوضة، و `doas` يُعامل كنفس الإمكانية تحت اسم مختلف. +يحجب الأمر الذي يشغل ملف ثنائي للترقية **في موضع الأمر**. المطابقة هيكلية وليست نصية: يتم تقسيم الأمر إلى مقاطع بالطريقة التي يفعلها shell، معاملات البادئة (`FOO=bar`)، عمليات إعادة التوجيه، والعدّاءات مع أعلامها (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) يتم المرور فيها، والملف الثنائي الناتج يتم مقارنته ب**basename**. لذلك `/usr/bin/sudo`، `env sudo`، `timeout 5 sudo`، `"sudo"`، `\sudo` و`bash -c "sudo …"` كلها مرفوضة، و`doas` يتم التعامل معها باعتبارها نفس القدرة تحت اسم مختلف. -لأنها تستقر على موضع الأمر وليس الكلمة التي تظهر في أي مكان، فهي **لا تُطلق** على الأوامر التي تذكره فقط — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, أو `grep` يحتوي على كلمة بديلة تُشغل عادةً. +لأنه يرسو على موضع الأمر بدلاً من الكلمة التي تظهر في أي مكان، فإنه **لا** يتفعل على الأوامر التي تذكره ببساطة — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`، أو بديل `grep` يحتوي على الكلمة كلها تعمل بشكل طبيعي. -يوقف المحاولة الواضحة؛ لا يغلق الفئة. يمكن للوكيل الذي يستطيع تشغيل shell عشوائية الوصول إلى الرفع بشكل غير مباشر — من خلال متغير (`S=sudo; $S …`)، أنبوب مفكك base64، أو سكريبت wrapper على القرص — لأن فحص سلسلة أمر واحدة لا يمكن أن يتابع تلك. تعامل مع هذا كدرابزين ضد الأخطاء والرفع العرضي، وليس حد أمان ضد وكيل مصمم. يجب أن يُفرض الحد الحقيقي أسفل shell. +هذا يوقف المحاولة الواضحة؛ إنه لا يغلق الفئة. يمكن للوكيل الذي يمكنه تشغيل shell عشوائي الوصول إلى الترقية بشكل غير مباشر — من خلال متغير (`S=sudo; $S …`)، أنبوب مشفر بـ base64، أو سكريبت wrapper على القرص — لأن فحص سلسلة أمر واحدة لا يمكنه متابعة تلك. عامل هذا كحماية ضد الأخطاء والترقية العارضة، وليس كحد أمان ضد وكيل مصمم. الحد الحقيقي يجب أن يفرضه shell أسفل. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات الأوامر الدقيقة المسموح بها. يُطابق كل إدخال مقابل الرموز المحللة argv. | +| `allowPatterns` | `string[]` | `[]` | بادئات الأوامر الدقيقة المسموحة. يتم مطابقة كل إدخال مقابل رموز argv المحللة. | **مثال:** @@ -97,10 +95,10 @@ icon: shield } ``` -مع هذا الإعداد، `sudo systemctl status nginx` مسموح، لكن `sudo rm /etc/hosts` مرفوض. +مع هذا الإعداد، `sudo systemctl status nginx` مسموح به، لكن `sudo rm /etc/hosts` مرفوض. -تُطابق الأنماط الرموز المحللة، وليس سلسلة الأمر الخام. يمنع هذا التجاوز عبر مشغلات shell المرفقة (مثل `sudo systemctl status x; rm -rf /` لا يطابق `sudo systemctl status *`). +يتم مطابقة الأنماط مقابل الرموز المحللة، وليس سلسلة الأمر الخام. هذا يمنع الالتفاف عبر عوامل shell المُلحقة (مثل `sudo systemctl status x; rm -rf /` لا يطابق `sudo systemctl status *`). --- @@ -108,13 +106,13 @@ icon: shield ### `block-rm-rf` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يرفض `rm -rf`, `rm -fr`، والأشكال الأخرى المشابهة للحذف المتكرر. +**الافتراضي:** يرفض `rm -rf`, `rm -fr`, وأشكال الحذف العودي المشابهة. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | المسارات الآمنة للحذف المتكرر (مثل `/tmp`). | +| `allowPaths` | `string[]` | `[]` | المسارات الآمنة للحذف العودي (مثل `/tmp`). | **مثال:** @@ -135,37 +133,37 @@ icon: shield **الحدث:** PreToolUse (Bash) **الافتراضي:** يرفض `curl | bash`, `curl | sh`, `wget | bash`، والأنماط المشابهة. -بدون معاملات. +لا توجد معاملات. --- ### `block-failproofai-commands` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يرفض الأوامر التي ستلغي أو تعطل failproofai نفسه (مثل `npm uninstall failproofai`, `failproofai policies --uninstall`). +**الافتراضي:** يرفض الأوامر التي قد تلغي أو تعطل failproofai نفسه (مثل `npm uninstall failproofai`, `failproofai policies --uninstall`). -بدون معاملات. +لا توجد معاملات. --- ### `block-self-pause` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يرفض `failproofai config --pause`، الذي يوقف الإنفاذ للجلسة. الإيقاف المؤقت قرار بشري — يمكن للوكيل الذي يستطيع تشغيله إيقاف كل سياسة أخرى بأمر واحد. +**الافتراضي:** يرفض `failproofai config --pause`، الذي يعلق الفرض لجلسة. الإيقاف المؤقت هو قرار بشري — وكيل قادر على تشغيله يمكنه إيقاف كل سياسة أخرى بأمر واحد. -أضيق من [`block-failproofai-commands`](#block-failproofai-commands) بقصد، وغير مغطاة بها: تلك السياسة تستقر على حد أمر، لذلك `npx -y failproofai config --pause` لا تطابقها، وكونها واسعة غالباً ما يتم إيقاف تشغيلها حتى يتمكن الوكلاء من تشغيل `failproofai audit`. `--resume` و `--status` مسموح بهما — لا يزيل أي منهما الإنفاذ. +أضيق من [`block-failproofai-commands`](#block-failproofai-commands) بقصد، وغير مغطى به: تلك السياسة ترسو على حد أمر، لذلك `npx -y failproofai config --pause` لا تطابقها، وكونها واسعة غالباً ما يتم إيقافها لذلك يمكن للوكلاء تشغيل `failproofai audit`. `--resume` و`--status` مسموحة — لا أحدهما يزيل الفرض. -يوقف المحاولة المباشرة، وليس الفئة كاملة: يمكن للوكيل الوصول لنفس الحالة من خلال اسم مستعار أو سكريبت wrapper. إغلاقها بالكامل يتطلب أن تكون الإيقافة غير قابلة للوصول من استدعاء أداة على الإطلاق. +هذا يوقف المحاولة المباشرة، وليس الفئة كلها: يمكن للوكيل الوصول إلى نفس الحالة من خلال alias أو سكريبت wrapper. إغلاقها بالكامل يتطلب أن يكون الإيقاف المؤقت غير قابل للوصول من استدعاء أداة على الإطلاق. -بدون معاملات. +لا توجد معاملات. --- ## أوامر البنية التحتية -منع وكلاء الكود من تشغيل CLIs البنية التحتية أو تفعيل خطوط أنابيب CI/CD. جميع السياسات في هذه الفئة **اختيارية** (`defaultEnabled: false`) — الوكلاء الذين يحتاجون بشرعية لاستدعاء `kubectl`, `terraform`، إلخ لن يُعطلوا ما لم تُفعل السياسة. عند التفعيل، كل استدعاء للـ CLI المطابق مرفوض ما لم يطابق الأمر إدخالاً في `allowPatterns`. +منع وكلاء الترميز من تشغيل CLIs البنية التحتية أو تفعيل خطوط أنابيب CI/CD. جميع السياسات في هذه الفئة هي **اختيارية** (`defaultEnabled: false`) — الوكلاء الذين يحتاجون بشكل شرعي إلى استدعاء `kubectl`, `terraform`, إلخ. لن يكونوا مزعجين إلا إذا قمت بتفعيل السياسة. عند التفعيل، كل استدعاء من CLI المطابقة مرفوض ما لم يطابق الأمر إدخالاً في `allowPatterns`. -نحو النمط هو نفس [`block-sudo`](#block-sudo): الرموز تُطابق مقابل argv المحللة، `*` بطاقة بدل لرمز واحد، وأي أمر يحتوي على مشغل shell مستقل (`&&`, `||`, `|`, `;`) أو رمز به أحرف metacharacters shell مدمجة مرفوض قبل تطابق قائمة المسموح به لمنع تجاوزات الحقن. +نحو القواعد هو نفسه [`block-sudo`](#block-sudo): يتم مطابقة الرموز مقابل argv المحلل، `*` هو wildcard لرمز واحد، وأي أمر يحتوي على عامل shell مستقل (`&&`, `||`, `|`, `;`) أو رمز به محارف shell مدمجة يتم رفضه قبل مطابقة القائمة البيضاء لمنع bypasses الحقن. ### `block-kubectl` @@ -176,7 +174,7 @@ icon: shield | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر kubectl المسموح بها. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر kubectl المسموحة. | **مثال:** @@ -190,7 +188,7 @@ icon: shield } ``` -مع هذا الإعداد، `kubectl get pods` مسموح لكن `kubectl apply -f deploy.yaml` مرفوض. +مع هذا الإعداد، `kubectl get pods` مسموح به لكن `kubectl apply -f deploy.yaml` مرفوض. --- @@ -203,7 +201,7 @@ icon: shield | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر terraform/tofu المسموح بها. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر terraform/tofu المسموحة. | **مثال:** @@ -222,13 +220,13 @@ icon: shield ### `block-aws-cli` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يرفض أي استدعاء AWS CLI. +**الافتراضي:** يرفض أي استدعاء CLI `aws`. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر AWS CLI المسموح بها. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر aws CLI المسموحة. | **مثال:** @@ -253,7 +251,7 @@ icon: shield | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر gcloud المسموح بها. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر gcloud المسموحة. | **مثال:** @@ -278,7 +276,7 @@ icon: shield | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر az CLI المسموح بها. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر az CLI المسموحة. | **مثال:** @@ -303,7 +301,7 @@ icon: shield | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر helm المسموح بها. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر helm المسموحة. | **مثال:** @@ -322,7 +320,7 @@ icon: shield ### `block-gh-pipeline` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يرفض أوامر CLI `gh` الفرعية التالية التي تغير الحالة أو تفعل خطوط الأنابيب: +**الافتراضي:** يرفض بدايات فرعية `gh` CLI التالية التي تعدّل الحالة أو تفعّل خطوط أنابيب: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -331,13 +329,13 @@ icon: shield - `gh cache delete` - `gh secret set`, `gh secret delete` -أوامر `gh` الفرعية للقراءة فقط مثل `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, و `gh api repos/.../...` **لا تُطابق** بهذه السياسة — مطلوبة بشكل روتيني لفحوصات سير العمل (بما في ذلك `require-ci-green-before-stop` الخاص بـ failproofai). +بدايات فرعية `gh` للقراءة فقط مثل `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, و`gh api repos/.../...` **لا** تطابقها هذه السياسة — يتم احتياجها بشكل روتيني لفحوصات سير العمل (بما في ذلك `require-ci-green-before-stop` الخاص بـ failproofai). **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | استدعاءات محددة بسكريبت للسماح بها حتى وإن كانت مرفوضة بخلاف ذلك. | +| `allowPatterns` | `string[]` | `[]` | استدعاءات scripted محددة للسماح بها حتى وإن تم رفضها بخلاف ذلك. | **مثال:** @@ -353,29 +351,29 @@ icon: shield --- -## الأسرار (المعالجات) +## الأسرار (المعقمات) -منع الوكلاء من تسريب بيانات الاعتماد إلى سياقهم أو إخراجهم. تُطلق سياسات المعالج على أحداث **PostToolUse**. عند تشغيل Claude أمر Bash أو قراءة ملف أو استدعاء أي أداة، تفحص هذه السياسات الإخراج قبل إرجاعه إلى Claude. إذا تم اكتشاف نمط سر، تُرجع السياسة قرار رفض يمنع الإخراج من الإرجاع. +منع الوكلاء من تسرب الأوراق الاعتماد إلى سياقهم أو مخرجاتهم. سياسات المعقِّم تتفعل على أحداث **PostToolUse**. عند تشغيل Claude أمر Bash، قراءة ملف، أو استدعاء أي أداة، تفتش هذه السياسات المخرجات قبل إرجاعها إلى Claude. إذا تم اكتشاف نمط سري، تُرجع السياسة قرار deny يمنع المخرجات من الإرجاع. ### `sanitize-jwt` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يحجب توكنات JWT (ثلاثة قطاعات base64url مفصولة بـ `.`). +**الافتراضي:** يحذف رموز JWT (ثلاثة مقاطع base64url مفصولة بـ `.`). -بدون معاملات. +لا توجد معاملات. --- ### `sanitize-api-keys` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يحجب صيغ مفاتيح API الشائعة: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), مفاتيح الوصول AWS (`AKIA`), مفاتيح Stripe (`sk_live_`, `sk_test_`), ومفاتيح Google API (`AIza`). +**الافتراضي:** يحذف تنسيقات مفاتيح API الشائعة: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), مفاتيح الوصول AWS (`AKIA`), مفاتيح Stripe (`sk_live_`, `sk_test_`), ومفاتيح Google API (`AIza`). **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | أنماط regex إضافية لمعاملتها كأسرار. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | أنماط regex إضافية يتم التعامل معها كأسرار. | **مثال:** @@ -384,7 +382,7 @@ icon: shield "policyParams": { "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "مفتاح API داخلي من MyCo" }, + { "regex": "myco_[A-Za-z0-9]{32}", "label": "مفتاح API الداخلي MyCo" }, { "regex": "pat_[0-9a-f]{40}", "label": "PAT داخلي" } ] } @@ -397,42 +395,42 @@ icon: shield ### `sanitize-connection-strings` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يحجب سلاسل توصيل قاعدة البيانات التي تحتوي على بيانات اعتماد مدمجة (مثل `postgresql://user:password@host/db`). +**الافتراضي:** يحذف سلاسل الاتصال بقاعدة البيانات التي تحتوي على أوراق اعتماد مدمجة (مثل `postgresql://user:password@host/db`). -بدون معاملات. +لا توجد معاملات. --- ### `sanitize-private-key-content` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يحجب كتل PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`، إلخ). +**الافتراضي:** يحذف كتل PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, إلخ). -بدون معاملات. +لا توجد معاملات. --- ### `sanitize-bearer-tokens` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يحجب رؤوس `Authorization: Bearer ` حيث التوكن 20 حرف أو أكثر. +**الافتراضي:** يحذف رؤوس `Authorization: Bearer ` حيث يكون الرمز 20 أو أكثر من الأحرف. -بدون معاملات. +لا توجد معاملات. --- ## البيئة -حماية تكوين البيئة الحساسة من القراءة أو التعريض من قبل الوكلاء. +حماية إعداد البيئة الحساسة من قراءة أو فضح بواسطة الوكلاء. ### `block-env-files` **الحدث:** PreToolUse (Bash, Read) **الافتراضي:** يرفض قراءة ملفات `.env` عبر `cat .env`, استدعاءات أداة Read مع `.env` كمسار الملف، إلخ. -لا يحجب `.envrc` أو ملفات أخرى متعلقة بالبيئة - فقط الملفات المسماة بالضبط `.env`. +لا يحجب `.envrc` أو ملفات البيئة الأخرى - فقط الملفات المسماة بدقة `.env`. -بدون معاملات. +لا توجد معاملات. --- @@ -441,24 +439,24 @@ icon: shield **الحدث:** PreToolUse (Bash) **الافتراضي:** يرفض الأوامر التي تطبع متغيرات البيئة: `printenv`, `env`, `echo $VAR`. -بدون معاملات. +لا توجد معاملات. --- ## الوصول إلى الملفات -احتفظ بالوكلاء يعملون داخل حدود المشروع بعيداً عن الملفات الحساسة. +إبقاء الوكلاء يعملون داخل حدود المشروع بعيداً عن الملفات الحساسة. ### `block-read-outside-cwd` **الحدث:** PreToolUse (Read, Bash) -**الافتراضي:** يرفض قراءة الملفات خارج جذر المشروع. الحد هو `CLAUDE_PROJECT_DIR` (مضبوط مرة واحدة لكل جلسة بواسطة Claude Code)، مع فشل على cwd الحالي للجلسة عند عدم ضبط هذا المتغير. استخدام جذر المشروع بدلاً من `cwd` الحي يعني بقاء الحد ثابتاً حتى بعد قيام Claude بـ `cd` في مجلد فرعي. +**الافتراضي:** يرفض قراءة الملفات خارج جذر المشروع. الحد هو `CLAUDE_PROJECT_DIR` (معيَّن مرة واحدة كل جلسة بواسطة Claude Code)، مع fallback إلى دليل العمل الحالي للجلسة عند عدم تعيين متغير. استخدام جذر المشروع بدلاً من `cwd` الحي يعني بقاء الحد مستقراً حتى بعد Claude الانتقال (`cd`) إلى دليل فرعي. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | بادئات المسار المطلق المسموح بها حتى خارج جذر المشروع. | +| `allowPaths` | `string[]` | `[]` | بادئات المسار المطلق المسموح بها حتى إن كانت خارج جذر المشروع. | **مثال:** @@ -477,13 +475,13 @@ icon: shield ### `block-secrets-write` **الحدث:** PreToolUse (Write, Edit) -**الافتراضي:** يرفض الكتابة إلى الملفات المستخدمة عادة للمفاتيح الخاصة والشهادات: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**الافتراضي:** يرفض الكتابة إلى الملفات المستخدمة بشكل شائع للمفاتيح الخاصة والشهادات: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | أنماط اسم ملف إضافية (نمط glob) للحجب. | +| `additionalPatterns` | `string[]` | `[]` | أنماط اسم ملف إضافية (بأسلوب glob) يتم حجبها. | **مثال:** @@ -501,18 +499,18 @@ icon: shield ## Git -منع الدفع العرضي والدفع الإجباري وأخطاء الفرع التي يصعب التراجع عنها. +منع الدفع العرضي والدفع القسري وأخطاء الفرع التي يصعب التراجع عنها. ### `block-push-master` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يرفض `git push origin main` و `git push origin master`. +**الافتراضي:** يرفض `git push origin main` و`git push origin master`. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع التي لا يمكن الدفع إليها مباشرة. | +| `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع التي لا يمكن دفعها مباشرة. | **مثال:** @@ -527,7 +525,7 @@ icon: shield ``` -للسماح بالدفع إلى جميع الفروع (تعطيل هذه السياسة فعلياً دون إزالتها من `enabledPolicies`)، اضبط `protectedBranches: []`. +للسماح بالدفع إلى جميع الفروع (بشكل فعال تعطيل هذه السياسة بدون إزالتها من `enabledPolicies`)، اضبط `protectedBranches: []`. --- @@ -535,28 +533,28 @@ icon: shield ### `block-work-on-main` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يرفض `git commit`, `git merge`, `git rebase`, و `git cherry-pick` بينما شجرة العمل على `main` أو `master`. إنشاء فرع والتبديل (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) لا تتأثر. +**الافتراضي:** يرفض `git commit`, `git merge`, `git rebase`, و`git cherry-pick` بينما شجرة العمل على `main` أو `master`. إنشاء والتبديل للفرع (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) غير متأثرة. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع التي يُرفض عليها الالتزام/الدمج/إعادة الأساس/اختيار الكرز. | +| `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع التي يتم رفض commit/merge/rebase/cherry-pick عليها. | --- ### `block-force-push` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يرفض `git push --force` و `git push -f`. +**الافتراضي:** يرفض `git push --force` و`git push -f`. -بدون معاملات خاصة بالسياسة. استخدم [`hint`](/ar/configuration#hint-cross-cutting) عابر المقاطع للاقتراح بدائل: +لا توجد معاملات محددة للسياسة. استخدم العبور [`hint`](/ar/configuration#hint-cross-cutting) لاقتراح بدائل: ```json { "policyParams": { "block-force-push": { - "hint": "أنشئ فرع جديد من HEAD الحالي (مثل `git checkout -b `) وادفع ذلك بدلاً منه." + "hint": "أنشئ فرعاً جديداً من HEAD الحالي (مثل `git checkout -b `) ودفعها بدلاً من ذلك." } } } @@ -569,64 +567,64 @@ icon: shield **الحدث:** PreToolUse (Bash) **الافتراضي:** يوجه Claude للمتابعة بحذر عند تشغيل `git commit --amend`. لا يحجب الأمر. -بدون معاملات. +لا توجد معاملات. --- ### `warn-git-stash-drop` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل `git stash drop`. لا يحجب الأمر. +**الافتراضي:** يوجه Claude للتأكد قبل تشغيل `git stash drop`. لا يحجب الأمر. -بدون معاملات. +لا توجد معاملات. --- ### `warn-all-files-staged` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يوجه Claude لمراجعة ما يرحله عند تشغيل `git add -A` أو `git add .`. لا يحجب الأمر. +**الافتراضي:** يوجه Claude لمراجعة ما يفرضه عند تشغيل `git add -A` أو `git add .`. لا يحجب الأمر. -بدون معاملات. +لا توجد معاملات. --- ## قاعدة البيانات -التقط عمليات SQL المدمرة قبل تنفيذها على قاعدة البيانات. +اكتشف عمليات SQL المدمرة قبل تنفيذها ضد قاعدة البيانات الخاصة بك. ### `warn-destructive-sql` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل SQL يحتوي على `DROP TABLE`, `DROP DATABASE`, أو `DELETE` بدون شرط `WHERE`. +**الافتراضي:** يوجه Claude للتأكد قبل تشغيل SQL يحتوي على `DROP TABLE`, `DROP DATABASE`, أو `DELETE` بدون شرط `WHERE`. -بدون معاملات. +لا توجد معاملات. --- ### `warn-schema-alteration` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل عبارات `ALTER TABLE`. +**الافتراضي:** يوجه Claude للتأكد قبل تشغيل بيانات `ALTER TABLE`. -بدون معاملات. +لا توجد معاملات. --- ## التحذيرات -أعط الوكلاء سياق إضافي قبل عمليات محتملة المخاطر لكن غير مدمرة. +أعط الوكلاء سياق إضافي قبل عمليات محتملة الخطورة ولكن غير مدمرة. ### `warn-large-file-write` **الحدث:** PreToolUse (Write) -**الافتراضي:** يوجه Claude للتأكيد قبل كتابة الملفات الأكبر من 1024 KB. +**الافتراضي:** يوجه Claude للتأكد قبل كتابة الملفات الأكبر من 1024 كيلوبايت. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | عتبة حجم الملف بالكيلوبايت التي تُصدر فوقها تحذير. | +| `thresholdKb` | `number` | `1024` | عتبة حجم الملف بالكيلوبايت التي يتم إصدار تحذير فوقها. | **مثال:** @@ -641,7 +639,7 @@ icon: shield ``` -يفرض معالج Hook حد أقصى 1 MB لـ stdin على الأحمال. لاختبار هذه السياسة مع محتوى صغير، اضبط `thresholdKb` على قيمة أقل بكثير من 1024. +معالج hook يفرض حد stdin قدره 1 ميجابايت على الحمولات. لاختبار هذه السياسة بمحتوى صغير، اضبط `thresholdKb` على قيمة أقل بكثير من 1024. --- @@ -649,27 +647,27 @@ icon: shield ### `warn-package-publish` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل `npm publish`. +**الافتراضي:** يوجه Claude للتأكد قبل تشغيل `npm publish`. -بدون معاملات. +لا توجد معاملات. --- ### `warn-background-process` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يوجه Claude للحذر عند إطلاق العمليات الخلفية عبر `nohup`, `&`, `disown`, أو `screen`. +**الافتراضي:** يوجه Claude ليكون حذراً عند إطلاق عمليات في الخلفية عبر `nohup`, `&`, `disown`, أو `screen`. -بدون معاملات. +لا توجد معاملات. --- ### `warn-global-package-install` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يوجه Claude للتأكيد قبل تشغيل `npm install -g`, `yarn global add`, أو `pip install` بدون بيئة افتراضية. +**الافتراضي:** يوجه Claude للتأكد قبل تشغيل `npm install -g`, `yarn global add`, أو `pip install` بدون بيئة افتراضية. -بدون معاملات. +لا توجد معاملات. --- @@ -680,18 +678,18 @@ icon: shield ### `prefer-package-manager` **الحدث:** PreToolUse (Bash) -**الافتراضي:** معطل. عند التفعيل، يحجب أي أمر مدير حزم ليس في قائمة `allowed` ويخبر Claude لإعادة كتابة الأمر باستخدام مدير مسموح. +**الافتراضي:** معطّل. عند التفعيل، يحجب أي أمر مدير حزم ليس في قائمة `allowed` ويخبر Claude بإعادة كتابة الأمر باستخدام مدير مسموح. يكتشف: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | المعامل | النوع | الافتراضي | الوصف | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | أسماء مديري الحزم المسموح بها. أي مدير مكتشف ليس في هذه القائمة مرفوض. عند الفراغ، السياسة بدون عملية. | -| `blocked` | string[] | `[]` | أسماء مديري إضافية للحجب بما يتجاوز القائمة المدمجة (مثل `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | أسماء مديري الحزم المسموح بها. أي مدير مكتشف ليس في هذه القائمة يتم حجبه. عند ترك فارغ، السياسة لا تفعل شيء. | +| `blocked` | string[] | `[]` | أسماء مديري إضافية يتم حجبها بخلاف القائمة المدمجة (مثل `['pdm', 'pipx']`). | -تغطي قائمة الحجب المدمجة: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. استخدم `blocked` لإضافة مديرين ليسوا في هذه القائمة. +قائمة الحجب المدمجة تغطي: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. استخدم `blocked` لإضافة مديري ليسوا في هذه القائمة. -**مثال الإعداد:** +**إعداد المثال:** ```json { @@ -705,73 +703,73 @@ icon: shield } ``` -مع هذا الإعداد، `pip install flask` و `pdm install flask` كلاهما مرفوض برسالة تخبر Claude باستخدام `uv` أو `bun` بدلاً منهما. أوامر مثل `uv pip install flask` مسموح بها لأن `uv` في قائمة المسموح به ويُفحص أولاً. +مع هذا الإعداد، `pip install flask` و`pdm install flask` كليهما مرفوضان برسالة تخبر Claude استخدام `uv` أو `bun` بدلاً من ذلك. أوامر مثل `uv pip install flask` مسموح بها لأن `uv` في قائمة السماح ويتم فحصه أولاً. --- -## سلوك الذكاء الاصطناعي +## سلوك AI -كتشف عند عدم عمل الوكلاء أو سلوكهم بشكل غير متوقع. +اكتشف عندما يعلق الوكلاء أو يتصرفون بطرق غير متوقعة. ### `warn-repeated-tool-calls` **الحدث:** PreToolUse (جميع الأدوات) -**الافتراضي:** يوجه Claude لإعادة النظر عند استدعاء نفس الأداة 3+ مرات بمعاملات متطابقة - علامة شائعة على أن الوكيل عالق في حلقة. +**الافتراضي:** يوجه Claude لإعادة النظر عند استدعاء نفس الأداة 3+ مرات بنفس المعاملات - علامة شائعة أن الوكيل عالق في حلقة. -بدون معاملات. +لا توجد معاملات. --- ## سير العمل -فرض سير عمل منضبط لنهاية الجلسة. تُطلق هذه السياسات على حدث **Stop** وترفض الوكيل من التوقف حتى استيفاء كل شرط. تتبع سلسلة اعتماد طبيعية: commit → push → PR → CI. إذا رفضت سياسة، يتم تخطي السياسات اللاحقة في السلسلة (رفض يختصر). +فرض سير عمل منظم في نهاية الجلسة. تتفعل هذه السياسات على حدث **Stop** وترفض الوكيل من الإيقاف حتى يستوفي كل شرط. تتبع سلسلة اعتماد طبيعية: commit → push → PR → CI. إذا رفضت سياسة، السياسات اللاحقة في السلسلة يتم تخطيها (deny يختصر). -جميع سياسات سير العمل **فتح-الفشل**: إذا لم تكن الأداة المطلوبة متاحة (مثل `gh` غير مثبت، لا توجد git remote)، تسمح السياسة برسالة إعلامية توضح لماذا تم تخطي الفحص. +جميع سياسات سير العمل **fail-open**: إذا لم تكن الأداة المطلوبة متاحة (مثل `gh` غير مثبت، لا remote git)، تسمح السياسة برسالة معلوماتية شرح سبب تخطي الفحص. -### دلالات Stop لكل CLI +### دلالات Stop حسب CLI -يبدو إنفاذ Stop مختلفاً قليلاً عبر ستة CLIs المدعومة لأن كل واحد يعرض عقد hook "انتهى الوكيل" مختلف. **النتيجة** متساوية — الوكيل لا يتمكن من التوقف بينما بوابة سير العمل تفشل — لكن **الآليات** تختلف. الجدول أدناه يلخص؛ فقط Pi له quirk مرئي للمستخدم يستحق الفهم قبل تفعيل سياسة `require-*-before-stop`. +فرض Stop يبدو مختلفاً قليلاً عبر ستة CLIs مدعومة لأن كل واحد يعرض عقد hook محقق مختلف. **النتيجة** هي نفسها — الوكيل لا يتمكن من الإيقاف بينما بوابة سير العمل تفشل — لكن **الآليات** تختلف. الجدول أدناه يلخص؛ فقط Pi لديه خاصية غريبة يستحق الفهم قبل تفعيل سياسة `require-*-before-stop`. -| CLI | عند إطلاق البوابة | ما تراه | +| CLI | متى تتفعل البوابة | ما تراه | |---|---|---| | Claude Code | نفس حلقة الوكيل، فوراً | يستمر Claude في العمل — يصحح المشكلة، ثم يحاول الانتهاء مرة أخرى. لا انقطاع مرئي لك. | | Codex | نفس حلقة الوكيل، فوراً | نفس Claude. | -| GitHub Copilot CLI | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة إعادة المحاولة `{decision:"block", reason}` من Copilot — تم التحقق تجريبياً مقابل Copilot CLI 1.0.41). | -| Cursor Agent | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة Cursor `{followup_message}` — محدودة بـ `loop_limit`، افتراضي 5 محاولات إعادة). | -| OpenCode | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم استدعاء SDK `client.session.prompt(...)` من OpenCode الموجه عبر `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **دورة المستخدم التالية** | **يتوقف Pi بشكل مرئي** عند إطلاق البوابة — حلقة وكيله تخرج وتُعاد للمحث. ثم تُطلق البوابة في المرة التالية التي تُرسل فيها محث: يضيف failproofai توجيه `MANDATORY ACTION REQUIRED` إلى نظام المحث لهذه الدورة، يوجه LLM لإكمال خطوة سير العمل (التزام، دفع، إلخ) قبل فعل ما طلبته. | +| GitHub Copilot CLI | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة `{decision:"block", reason}` إعادة محاولة Copilot — تم التحقق منها تجريبياً ضد Copilot CLI 1.0.41). | +| Cursor Agent | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة `{followup_message}` Cursor — مغطاة بـ `loop_limit`، افتراضي 5 إعادة محاولات). | +| OpenCode | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم استدعاء SDK `client.session.prompt(...)` موجّه عبر `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **منعطف المستخدم التالي** | **Pi يتوقف بشكل مرئي** عندما تتفعل البوابة — حلقة الوكيل الخاصة به يخرج وتعود إلى السؤال. البوابة تتفعل بعد ذلك في المرة التالية تُرسل فيها سؤالاً: failproofai يضيف توجيه `MANDATORY ACTION REQUIRED` إلى نظام السؤال لتلك المنعطف، يوجه LLM لإكمال خطوة سير العمل (commit, push, إلخ) قبل فعل ما طلبته. | -**قيد Pi.** Pi's `AgentEndEvent` (المعادل الأعلى لـ Claude's `Stop` hook) ليس له نوع Result — بحلول وقت إطلاقه، حلقة وكيل Pi قد خرجت بالفعل. لا يمكن لـ failproofai إجبار Pi على إعادة محاولة نفس الحلقة بالطريقة التي يمكن فعلها مع Claude / Copilot / Cursor / OpenCode. يحول failproofai البوابة إلى حدث Pi's `before_agent_start` (الذي يُطلق بعد المحث التالي من المستخدم) حتى فحص سير العمل لا يزال ينفذ، فقط على الدورة التالية بدلاً من الحالية. +**حد Pi.** `AgentEndEvent` لـ Pi (ما يعادل حدث `Stop` Hook لـ Claude) ليس له نوع Result — بحلول الوقت الذي يتفعل فيه، حلقة الوكيل Pi قد خرجت بالفعل. لا يمكن إجبار Pi على إعادة محاولة نفس الحلقة الطريقة التي يمكن بها Claude / Copilot / Cursor / OpenCode. يحول failproofai البوابة إلى حدث `before_agent_start` Pi (الذي يتفعل بعد السؤال التالي للمستخدم) لذلك الفحص سير العمل لا يزال يفرض، فقط في المنعطف التالي بدلاً من الحالي. **ما يعنيه هذا عملياً:** -- بعد توقف Pi، يُحفظ سبب الرفض في الذاكرة مفتاح بـ Pi session id. المحث التالي جداً الذي تُرسله في نفس عملية Pi يستنزفه: LLM يرى توجيه `MANDATORY ACTION REQUIRED` في أعلى نظام المحث، يلتزم (أو يدفع / يفتح PR / ينتظر CI)، وفقط بعد ذلك يستمر مع طلبك. سبب الرفض المحفوظ مرة واحدة — بمجرد استنزافه، البوابة واضحة. -- البوابة محدودة بعمر عملية Pi. إذا `Ctrl+C` Pi أو أقفلت بين الدورات، يتم حذف إدخال الذاكرة مع العملية والبوابة تُفتقد. Claude و Copilot و Cursor و OpenCode لها نفس الحد (اقتل الوكيل والبوابة تُفتقد) — Pi فقط يجعلها أكثر وضوحاً لأن الوكيل يخرج بشكل مرئي قبل إطلاق البوابة. -- يتم مسح رفض معلق أيضاً على `session_shutdown` لأي سبب (`new` / `resume` / `fork` / `quit`)، حتى بوابة قديمة من جلسة سابقة لا تتسرب إلى جلسة جديدة بدأت في نفس عملية Pi. +- بعد توقف Pi، يتم التقاط سبب الرفض في ذاكرة مفتاحة بـ معرّف جلسة Pi. السؤال التالي جداً تُرسله في نفس عملية Pi يستنزفه: LLM يرى توجيه `MANDATORY ACTION REQUIRED` في أعلى نظام سؤاله، يعهد (أو يدفع / يفتح PR / ينتظر CI)، وفقط ثم يستمر مع طلبك. سبب الرفض التم التقاطه one-shot — بمجرد استنزافه، البوابة واضحة. +- البوابة محدودة بحياة عملية Pi. إذا `Ctrl+C` Pi أو أغلقت بين منعطفات، الإدخال في الذاكرة يُسقط جنباً إلى جنب مع العملية والبوابة يتم تفويتها. Claude, Copilot, Cursor, و OpenCode لديها نفس الحد (اقتل الوكيل والبوابة يتم تفويتها) — Pi فقط يجعلها أكثر رؤية لأن الوكيل يخرج بشكل مرئي قبل تفعل البوابة. +- سبب رفض معلق أيضاً يُمسح على `session_shutdown` لأي سبب (`new` / `resume` / `fork` / `quit`)، لذا بوابة قديمة من جلسة سابقة لا يمكنها تسرباً إلى جلسة جديدة بدأت في نفس عملية Pi. -إذا كنت بحاجة إلى إعادة محاولة نفس حلقة على غرار Claude، شغل سياسات `Stop` تحت أي من الخمسة CLIs المدعومة الأخرى. نحن نتتبع Pi الأعلى لنوع Result مستقبلي على `AgentEndEvent` الذي سيسمح لنا بإغلاق هذا الفجوة. +إذا كنت تحتاج إلى إعادة محاولة نفس حلقة بأسلوب Claude، شغّل سياسات `Stop` تحت أي من الخمسة CLIs المدعومة الأخرى. نحن نتابع Pi upstream لنوع Result مستقبلي على `AgentEndEvent` الذي سيتيح لنا إغلاق هذه الفجوة. ### `require-commit-before-stop` **الحدث:** Stop -**الافتراضي:** يرفض التوقف عند وجود تغييرات غير مرحلة (ملفات معدلة، مرحلة، أو غير متتبعة). يرجع رسالة إعلامية عند كون مجلد العمل نظيفاً. +**الافتراضي:** يرفض الإيقاف عندما توجد تغييرات غير معهودة (ملفات معدلة، مفروضة، أو غير متتبعة). يُرجع رسالة معلوماتية عندما يكون دليل العمل نظيفاً. -بدون معاملات. +لا توجد معاملات. --- ### `require-push-before-stop` **الحدث:** Stop -**الافتراضي:** يرفض التوقف عند وجود التزامات غير مدفوعة أو عند عدم وجود فرع تتبع بعيد للفرع الحالي. يقترح `git push -u` لإنشاء فرع تتبع إن لزم. يفشل مفتوحاً إذا لم يكن remote مُعد. +**الافتراضي:** يرفض الإيقاف عندما توجد commits غير مدفوعة أو عندما الفرع الحالي ليس له فرع تتبع بعيد. يقترح `git push -u` لإنشاء فرع تتبع إن لزم الأمر. يفشل مفتوحاً إذا لم يكن remote مشكّل. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | اسم الـ remote للدفع إليه. | +| `remote` | `string` | `"origin"` | اسم Remote للدفع إليه. | **مثال:** @@ -790,14 +788,14 @@ icon: shield ### `require-pr-before-stop` **الحدث:** Stop -**الافتراضي:** يرفض التوقف عند عدم وجود طلب سحب للفرع الحالي، أو عند إغلاق طلب السحب الموجود دون دمج. يوجه Claude لإنشاء PR مع `gh pr create`. عند **دمج** PR، تسمح السياسة (الشغل شحن) والرسالة تلمح للتبديل خارج الفرع (`git checkout main && git pull`). +**الافتراضي:** يرفض الإيقاف عندما لا يوجد pull request للفرع الحالي، أو عندما PR الموجود مغلق بدون دمج. يوجه Claude لإنشاء PR مع `gh pr create`. عندما يتم **دمج** PR، تسمح السياسة (العمل قد شُحن) والرسالة تلميح للتبديل من الفرع (`git checkout main && git pull`). -بدون معاملات. +لا توجد معاملات. -تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) مثبتاً ومصرحاً. -شغل `gh auth login` مع رمز وصول شخصي يمتلك نطاق `repo` للوصول القراءة -إلى طلبات السحب. إذا لم يكن `gh` مثبتاً أو مصرحاً، تفشل السياسة مفتوحة وتبلغ السبب إلى Claude. +هذه السياسة تتطلب [GitHub CLI](https://cli.github.com/) (`gh`) ليكون مثبتاً ومصرّحاً. +شغّل `gh auth login` مع رمز وصول شخصي لديه نطاق `repo` للوصول القراءة إلى +pull requests. إذا لم يكن `gh` مثبتاً أو مصرّحاً، السياسة تفشل مفتوحة وترسل السبب إلى Claude. --- @@ -805,24 +803,24 @@ icon: shield ### `require-no-conflicts-before-stop` **الحدث:** Stop -**الافتراضي:** يرفض التوقف عند عدم القدرة على دمج الفرع الحالي نظيفاً في فرع الأساس. تؤكد السياسة أولاً وجود PR `OPEN` على GitHub للفرع — بدون واحد، لا يوجد هدف دمج لفرضه، لذلك السياسة بأكملها تختصر للسماح. بمجرد تأكيد PR `OPEN`، تُشغل اثنان من المحاولات المستقلة: +**الافتراضي:** يرفض الإيقاف عندما الفرع الحالي لا يمكن دمجه بنظافة في الفرع الأساسي. تؤكد السياسة أولاً وجود PR `OPEN` على GitHub للفرع — بدون واحد، لا هدف دمج لفرضه، لذا السياسة بكاملها اختصار للسماح. بمجرد تأكيد PR `OPEN`، اثنان من المسوح المستقلة يعملان: -1. **محلي** — `git merge-tree --write-tree --name-only origin/ HEAD`. عند التعارض، رسالة الرفض تُسمي الملفات المتعارضة حتى يعرف Claude بالضبط ما يجب حله. -2. **GitHub** — يُعيد استخدام نتيجة `gh pr view --json mergeable,state` المجلوبة بالفعل في الفحص المسبق. يمسك التعارضات التي قد يفتقدها `origin/` المحلي القديم (مثل هبوط شخص ما PR متعارض على `main` منذ الجلب الأخير). نتيجة `CONFLICTING` ترفض. نتيجة `UNKNOWN` أيضاً ترفض وتوجه Claude للانتظار ~10 ثواني وإعادة فحص قبل محاولة التوقف مرة أخرى — يمنع هذا النتائج السالبة الكاذبة بينما تُعيد GitHub الحساب. +1. **محلي** — `git merge-tree --write-tree --name-only origin/ HEAD`. عند التضارب، رسالة الرفض تسمي الملفات المتضاربة لذا Claude يعرف بالضبط ما يحل. +2. **GitHub** — يعيد استخدام نتيجة `gh pr view --json mergeable,state` المجلوبة بالفعل في الفحص المسبق. يمسك بالتضاربات التي `origin/` محلي قديم قد يفتقده (مثل شخص ما هبط PR متضارب على `main` منذ آخر جلب). نتيجة `CONFLICTING` ترفض. نتيجة `UNKNOWN` أيضاً ترفض وتوجه Claude للانتظار ~10 ثوان وإعادة فحص قبل محاولة الإيقاف مرة أخرى — هذا يمنع false negatives بينما GitHub تعيد حساب. -تتخطى بالكامل (تسمح) عند: `gh` غير مثبت، لا يوجد PR للفرع، حالة PR ليست `OPEN` (مثل `MERGED`, `CLOSED`)، أو `gh pr view` يُرجع إخراج غير قابل للتحليل. تفشل أيضاً مفتوحة عند فقدان `origin/` محلياً أو عند عدم وجود التزامات قبل الأساس — تلك تسقط الطبقة 1 لا تزال تستشير mergeable المخزن مؤقتاً للـ PR قبل السماح. +يتخطى بالكامل (يسمح) عندما: `gh` غير مثبت، لا PR موجود للفرع، حالة PR ليست `OPEN` (مثل `MERGED`, `CLOSED`)، أو `gh pr view` يُرجع مخرجات غير قابلة للتحليل. أيضاً يفشل مفتوحاً عندما `origin/` مفقود محلياً أو عندما لا commits متقدم من base — تلك Layer 1 fall-throughs لا تزال تستشير PR mergeability cached قبل السماح. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | فرع الأساس للتحقق عن التعارضات ضده. | +| `baseBranch` | `string` | `"main"` | الفرع الأساسي للفحص عن التضاربات ضده. | -GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياسة `gh pr view` لتأكيد -وجود PR `OPEN` قبل تشغيل أي محاولة تعارض — بدون `gh`، تختصر السياسة -للسماح. شغل `gh auth login` مع رمز وصول شخصي يمتلك نطاق `repo` للوصول القراءة -إلى طلبات السحب. +GitHub CLI (`gh`) مطلوب لهذه السياسة. السياسة تستخدم `gh pr view` لتأكيد +PR `OPEN` موجود قبل تشغيل أي مسح تضارب — بدون `gh`، السياسة +اختصار مفتوحة. شغّل `gh auth login` مع رمز وصول شخصي لديه +نطاق `repo` للوصول القراءة إلى pull requests. --- @@ -830,14 +828,14 @@ GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياس ### `require-ci-green-before-stop` **الحدث:** Stop -**الافتراضي:** يرفض التوقف عند فشل فحوصات CI أو لا تزال قيد التشغيل على الفرع الحالي. يفحص كلاً من تشغيلات سير العمل GitHub Actions والفحوصات من جهات خارجية (مثل CodeRabbit، SonarCloud، Codecov). يعامل الخلاصات `skipped`, `cancelled`, و `neutral` كغير فاشلة (الأخيرة تغطي مثل Socket Security تنبيهات على PRs المساهمة الخارجية، حيث التطبيق بقصد يُبلغ محايد بدلاً من النجاح/الفشل). يرجع رسالة إعلامية عند نجاح جميع الفحوصات. +**الافتراضي:** يرفض الإيقاف عندما فحوصات CI تفشل أو لا تزال تعمل على الفرع الحالي. يفحص كل من GitHub Actions workflow يعمل وفحوصات bot الخارجية (مثل CodeRabbit, SonarCloud, Codecov). يعامل `skipped`, `cancelled`, و`neutral` الخاتمات كغير فاشلة (الأخير يغطي مثل Socket Security alerts على PRs المساهم الخارجي، حيث التطبيق يعرض متعمداً neutral بدلاً من success/failure). يُرجع رسالة معلوماتية عندما جميع الفحوصات تمر. -بدون معاملات. +لا توجد معاملات. -تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) مثبتاً ومصرحاً. -شغل `gh auth login` مع رمز وصول شخصي يمتلك نطاق `repo` للوصول القراءة -إلى تشغيلات سير العمل Actions و Checks API. إذا لم يكن `gh` مثبتاً أو مصرحاً، تفشل السياسة مفتوحة وتبلغ السبب إلى Claude. +هذه السياسة تتطلب [GitHub CLI](https://cli.github.com/) (`gh`) ليكون مثبتاً ومصرّحاً. +شغّل `gh auth login` مع رمز وصول شخصي لديه نطاق `repo` للوصول القراءة إلى +GitHub Actions workflow يعمل وفحوصات API. إذا لم يكن `gh` مثبتاً أو مصرّحاً، السياسة تفشل مفتوحة وترسل السبب إلى Claude. --- @@ -846,7 +844,7 @@ GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياس ## تعطيل السياسات الفردية -أزل سياسة معينة من `enabledPolicies` في إعدادك، أو بدل تشغيلها في تبويب Policies بالـ dashboard. +أزل سياسة محددة من `enabledPolicies` في إعدادك، أو بدّلها في تبويب Policies بـ لوحة المعلومات. ```json { @@ -857,4 +855,4 @@ GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياس } ``` -السياسات غير المدرجة في `enabledPolicies` لا تعمل، حتى إذا كانت هناك إدخالات `policyParams` لها. \ No newline at end of file +السياسات غير المدرجة في `enabledPolicies` لا تعمل، حتى إن كانت إدخالات `policyParams` موجودة لها. \ No newline at end of file diff --git a/docs/ar/cli/audit.mdx b/docs/ar/cli/audit.mdx index 24e5e0ba..cb94bce8 100644 --- a/docs/ar/cli/audit.mdx +++ b/docs/ar/cli/audit.mdx @@ -1,23 +1,24 @@ --- --- title: تدقيق الجلسات السابقة (beta) -description: "عد عدد المرات التي قام فيها الوكيل بعمليات غير ضرورية أو محفوفة بالمخاطر عبر النصوص السابقة" +description: "عد عدد المرات التي قام فيها الوكيل بأشياء مهدرة أو محفوفة بالمخاطر عبر النصوص السابقة" --- - **ميزة تجريبية.** يتم شحن التدقيق كإصدار تجريبي بينما نجمع الملاحظات المبكرة. - قد تتغير كتالوج الكاشفات وتنسيق التقرير قبل الإصدار المستقر التالي. يرجى فتح مشكلة إذا بدا شيء غير صحيح. + **ميزة تجريبية.** يتم شحن التدقيق كنسخة تجريبية بينما نجمع التعليقات المبكرة. + قد يتغير فهرس الكاشف وتنسيق التقرير قبل الإصدار المستقر التالي. يرجى فتح مشكلة إذا بدا + شيء ما غير صحيح. -يعيد التدقيق تشغيل نصوص مكتب وكيل CLI الخاصة بك عبر محرك السياسة في failproofai ويعرض تقريراً مرئياً قابلاً للمشاركة على **صفحة لوحة التحكم `/audit`** — نمط الوكيل، درجة من 0-100، والسياسات التي كان يمكنها اكتشاف ما بالضبط. +يعيد التدقيق تشغيل نصوص agent-CLI السابقة الخاصة بك من خلال محرك السياسات في failproofai ويعرض تقريراً مشاركاً وبصرياً على **صفحة لوحة القيادة `/audit`** — نمط الوكيل الخاص بك، درجة من 0-100، والسياسات المحددة التي كانت ستلتقط ماذا بالضبط. -## تشغيله +## قم بتشغيله -ثلاث طرق للدخول — جميعها تصل إلى نفس تقرير `/audit`. +ثلاث طرق للدخول — جميعها تؤدي إلى نفس تقرير `/audit`. -```bash npx (no install) +```bash npx (بدون تثبيت) npx -y failproofai audit ``` @@ -25,7 +26,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (dashboard) +```bash failproofai (لوحة القيادة) failproofai ``` @@ -33,88 +34,96 @@ failproofai - `npx -y failproofai audit` يجلب failproofai ويشغل المسح ويفتح لوحة التحكم لك — لا حاجة لتثبيت أي شيء أولاً. + `npx -y failproofai audit` تجلب failproofai وتشغل المسح وتفتح لك لوحة القيادة — لا حاجة لتثبيت أولاً. - `failproofai audit` يشغل المسح في طرفيتك، ثم يفتح `localhost:8020/audit` تلقائياً عند انتهائه. + `failproofai audit` تشغل المسح في جهازك الطرفي، ثم تفتح `localhost:8020/audit` تلقائياً عند انتهائه. - - شغّل `failproofai` وانقر على **Audit** في شريط التنقل (بين Policies و Projects)، أو افتح `/audit` مباشرة. + + قم بتشغيل `failproofai` وانقر فوق **Audit** في شريط التنقل (بين السياسات والمشاريع)، أو افتح `/audit` مباشرة. - شغّل `failproofai audit -h` (أو `--help`) لرؤية الاستخدام. يعمل التدقيق **بالكامل بلا اتصال** — لا تحتاج إلى حساب أو شبكة — ولوحة التحكم تستمر في الخدمة حتى تيقفها باستخدام `Ctrl+C`. + قم بتشغيل `failproofai audit -h` (أو `--help`) لرؤية الاستخدام. يعمل التدقيق **بالكامل بلا اتصال** — لا حاجة لحساب أو شبكة — وتستمر لوحة القيادة في العمل حتى توقفها بـ `Ctrl+C`. -تفحص لوحة التحكم نصوص agent CLI السابقة على هذا الجهاز (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) وتبلغ عن عدد المرات التي قام فيها الوكيل بأشياء مُعدّة failproofai للتوقف عنها — فحوصات متغيرات البيئة، push forces، بادئات `cd ` المكررة، حلقات sleep-polling، إعادة قراءة الملفات التي تم تعديلها للتو، والمزيد. +تمسح لوحة القيادة نصوص agent CLI السابقة على هذا الجهاز (Claude Code و Codex و Copilot و Cursor و OpenCode و Pi) وتقرير عدد المرات التي قام فيها الوكيل بأشياء تم بناء failproofai للتوقف عنها — فحوصات متغيرات البيئة والضغطات القسرية وبادئات `cd ` الزائدة عن الحاجة وحلقات sleep-polling وإعادة قراءة الملفات التي تم تحريرها للتو والمزيد. -لكل نص، يتم إعادة تشغيل كل حدث استخدام أداة عبر 39 سياسة مدمجة **و** عبر 8 كاشفات خاصة بالتدقيق التي تلتقط الأنماط غير المغطاة بعد بسياسات وقت التشغيل. يتم تجميع الأعداد لكل سياسة / كاشف عبر جميع الجلسات. +بالنسبة لكل نص، يتم إعادة تشغيل كل حدث tool-use من خلال السياسات المدمجة 39 **و** من خلال 8 كواشف تدقيق فقط التي تلتقط أنماطاً لم تكن مغطاة بعد بسياسات وقت التشغيل. يتم تجميع الأعداد لكل سياسة / كاشف عبر جميع الجلسات. ## ما الذي تحصل عليه -صفحة `/audit` هي **ملصق** على شاشة واحدة قابل للمشاركة يتبعه أربعة أقسام تحت التوسيط: +صفحة `/audit` عبارة عن **ملصق** واحد على الشاشة وقابل للمشاركة متبوعاً بأربعة أقسام أسفل الطية: -1. **الملصق** — هوية الوكيل في لمحة: **النمط** (أحد 8 — `optimist`، `cowboy`، `explorer`، `goldfish`، `paranoid architect`، `precision builder`، `hammer`، `ghost`)، كلمات الشخصية الخاصة به، مدى ندرة هذا النمط، و**درجة من 0-100** مع فئة (`S` إلى `bottom tier`). مُصنع للمشاركة — انشره على X أو LinkedIn، أو حمّله كصورة PNG. -2. **`// strengths`** — ما يقوم به الوكيل جيداً بالفعل، كأرقام حقيقية من المسح (مثل clean-tool-call %، `0` push-to-main attempts)، معروضة فقط حيث تحتوي السياسة ذات الصلة على سجل نظيف. -3. **`// quirks`** — ما انزلق عبره: جدول مصنف من السلوكيات التي كان failproofai سيكتشفها — **متى** حدثت آخر مرة، **ما الذي انزلق** (والأداة المدمجة التي كانت ستحجبها)، **الخطورة**، وعدد مرات **مشاهدتها** (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — قائمة الإصلاح الموصوفة: صف واحد لكل سياسة مع `failproofai policy add ` قابل للنسخ واللصق، بالإضافة إلى زر **install all** يفعّل كل توصية في وقت واحد ويعرض **الدرجة المتوقعة** إذا قمت بذلك. -5. **`// come back better`** — بناء العادة: اضبط **تذكير** إعادة تدقيق بالبريد الإلكتروني (`3d` / `7d` / `14d` / `30d`) أو أعد التدقيق الآن، و**ادعُ صديقاً** لتشغيل التدقيق الخاص به (مرسل من failproof.ai، مع نسخة لك). التذكيرات والدعوات تتطلب تسجيل الدخول. +1. **الملصق** — هوية الوكيل الخاص بك في لمحة: **نمطه** (واحد من 8 — `optimist` أو `cowboy` أو `explorer` أو `goldfish` أو `paranoid architect` أو `precision builder` أو `hammer` أو `ghost`)، كلماته الرئيسية الشخصية، ندرة هذا النمط، و**درجة من 0-100** مع نطاق مستوى (`S` حتى `الطبقة السفلى`). تم بناؤه للمشاركة — انشره على X أو LinkedIn أو حمّله كملف PNG. +2. **`// strengths`** — ما يفعله الوكيل بالفعل بشكل جيد، كأرقام حقيقية من المسح (مثل نسبة clean-tool-call و`0` محاولات push-to-main)، معروضة فقط حيث السياسة الذات صلة لديها سجل نظيف. +3. **`// quirks`** — ما تسلل: جدول مصنف للسلوكيات التي كان failproofai سيلتقطها — **متى** حدثت آخر مرة، **ما تسلل** (والمدمج الذي كان سيحجبه)، **شدتها**، وعدد المرات **شوهدت** (`جديد` / `متكرر` / `شوهد N مرة`). +4. **`// كيفية التحسن`** — قائمة الإصلاح الموصى به: صف واحد لكل سياسة مع `failproofai policy add ` قابل للنسخ واللصق، بالإضافة إلى زر **تثبيت الكل** الذي يمكّن كل توصية في المرة الواحدة ويظهر **الدرجة المتوقعة** إذا فعلت. +5. **`// عد بشكل أفضل`** — بناء العادة: عيّن تذكير إعادة التدقيق عبر البريد الإلكتروني **تذكير** (`3d` أو `7d` أو `14d` أو `30d`) أو أعد التدقيق الآن، و**ادعُ صديقاً** لتشغيل التدقيق الخاص به (مرسل من failproof.ai، نسخة موجهة لك). تتطلب التذكيرات والدعوات تسجيل الدخول. ## التدقيقات المجدولة -إذا شغّلت **daemon failproofaid** (انظر [`failproofai config`](/ar/cli/install-policies))، -يمكنه إعادة تشغيل التدقيق لك على جدول زمني وتحديث تقرير `/audit` في -الخلفية. يكون **معطلاً بشكل افتراضي**، لأن المسح يقرأ **المحتويات** -من كل نص جلسة وكيل على هذا الجهاز — لا يفحص أي شيء على مؤقت +إذا قمت بتشغيل **failproofaid daemon** (انظر [`failproofai config`](/ar/cli/install-policies))، +فيمكنه إعادة تشغيل التدقيق لك حسب الجدول الزمني وتحديث تقرير `/audit` في +الخلفية. هو **معطل بشكل افتراضي**، لأن المسح يقرأ **محتويات** +كل نص جلسة وكيل على هذا الجهاز — لا يحدث مسح على مؤقت حتى تطلب ذلك. -شغّله في `~/.failproofai/config.toml`: +قم بتشغيله في `~/.failproofai/config.json` — أضف مفتاح `audit` جنباً إلى جنب مع +أي شيء آخر قد يحتويه الملف بالفعل: -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | المفتاح | المعنى | |---|---| -| `auto` | `true` يفعّل المسح المجدول. أي شيء آخر — غائب، `false`، `"yes"` — معطل. | -| `interval_days` | أيام بين المسح. محدود إلى 1-90؛ `0`، رقم سالب أو غير رقم يعود إلى `7`. | - -- الجدول الزمني هو **wall-clock**، لذا فهو ينجو من التعليق والتمهيد: جهاز محمول كان في وضع السكون بعد وقت استحقاقه ينفذ **مرة واحدة** عند الاستيقاظ، أبداً لا توجد قائمة انتظار. -- كل تشغيل هو عملية منفصلة ذات أولوية منخفضة (`nice 19`) — أبداً لا طريق hook الخاص بـ daemon، الذي يبقى حراً للإجابة على استدعاءات الأدوات. -- يتم تخطي المسح إذا كان `failproofai audit` أو إعادة تشغيل لوحة التحكم قيد الرحلة بالفعل؛ تتم إعادة محاولته قريباً بدلاً من اعتباره فشلاً. -- يتم كتابة التقدم إلى `~/.failproofai/state/audit-schedule.json` (آخر تشغيل، التالي المستحق). يمتلك daemon هذا الملف — غيّر الإيقاع في `config.toml`. +| `auto` | `true` تمكّن المسح المجدول. أي شيء آخر — غير موجود أو `false` أو `"yes"` — معطل. | +| `interval_days` | الأيام بين المسحات. تقتصر على 1-90؛ `0` أو سالب أو غير رقم يعود إلى `7`. | + +- الجدول الزمني هو **الساعة الحائطية**، لذلك ينجو من التعليق والتمهيد: جهاز محمول + كان نائماً بعد وقته المحدد يعمل **مرة واحدة** عند الاستيقاظ، أبداً متراكماً. +- كل عملية تشغيل عبارة عن عملية منفصلة وذات أولوية منخفضة (`nice 19`) — أبداً مسار hook الخاص بالـ daemon، + الذي يبقى حراً للإجابة على استدعاءات الأدوات. +- يتم تخطي المسح إذا كان `failproofai audit` أو إعادة التشغيل من لوحة القيادة بالفعل + قيد الطيران؛ يتم إعادة محاولته قريباً بدلاً من معاملته كفشل. +- يتم كتابة التقدم إلى `~/.failproofai/state/audit-schedule.json` (آخر عملية تشغيل، + التالي المستحق). يمتلك الـ daemon هذا الملف — غيّر الإيقاع في `config.json`. -إذا فعّلت هذا على جهاز تم إعداده بواسطة failproofai أقدم، شغّل -`failproofai config` مرة واحدة. تعريف خدمة daemon يحتاج إلى إدخال إضافي واحد -قبل أن تتمكن من تشغيل CLI، والتحديث هو جزء من هذا الأمر. +إذا قمت بتفعيل هذا على جهاز تم إعداده بواسطة failproofai أقدم، +قم بتشغيل `failproofai config` مرة واحدة. تحتاج تعريفة خدمة الـ daemon إلى مدخل إضافي واحد +قبل أن تتمكن من تشغيل CLI، والتحديث جزء من هذا الأمر. -## كاشفات خاصة بالتدقيق فقط +## كواشف التدقيق فقط -تكتشف هذه أنماط "سلوك غبي" لا يتم فرضها (حتى الآن) في الوقت الفعلي. تعمل فقط أثناء التدقيق ولا تحجب أبداً استدعاء أداة مباشرة. +هذه تكتشف أنماط السلوك "الحمقاء" غير المطبقة (حتى الآن) في الوقت الفعلي. تعمل فقط أثناء التدقيق ولا تحجب أبداً استدعاء أداة مباشر. -| الكاشف | ما يعده | +| الكاشف | ما تعده | |---|---| | `redundant-cd-cwd` | أوامر Bash تبدأ بـ `cd && …` حتى وإن كانت الأوامر تعمل بالفعل في `cwd`. | | `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` على ملف مصدر واحد — استخدم أداة `Read`. | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` تحريرات في المكان — استخدم أداة `Edit`. | -| `prefer-write-over-heredoc` | Heredoc / كتابة الملفات متعددة الأسطر `echo > file` — استخدم أداة `Write`. | -| `sleep-polling-loop` | `sleep N` طويلة (≥ 30s) أو `while …; sleep …; done` حلقات polling. | -| `find-from-root` | `find /`، `find /home`، `find /usr`، إلخ. — حدد النطاق إلى `cwd` بدلاً من ذلك. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`، تخطي الخطافات. | -| `reread-after-edit` | `Read` لملف تم `Edit`/`Write` للتو في نفس الجلسة. | +| `prefer-edit-over-sed-awk` | تحريرات `sed -i` / `awk … > file` في المكان — استخدم أداة `Edit`. | +| `prefer-write-over-heredoc` | Heredoc / كتابة ملفات متعددة الأسطر `echo > file` — استخدم أداة `Write`. | +| `sleep-polling-loop` | `sleep N` طويل (≥ 30s) أو حلقات `while …; sleep …; done` للاستقصاء. | +| `find-from-root` | `find /` أو `find /home` أو `find /usr` وما إلى ذلك — الحد النطاق إلى `cwd`. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`، تخطي hooks. | +| `reread-after-edit` | `Read` ملف تم `Edit`/`Write` للتو في نفس الجلسة. | -## التخزينات المؤقتة +## الذاكرات المؤقتة -- **تخزين مؤقت لكل نص** في `~/.failproofai/cache/audit/.json` مفهرسة بـ `(mtime, size, engineVersion, detectorVersion)` — تبطل تلقائياً عند تغيير النص أو كود السياسة/الكاشف. يخزن كل إدخال أيضاً طابع زمني `cachedAt` كـ **بيانات وصفية TTL** (ليست جزءاً من مفتاح التخزين المؤقت)؛ يتم رفض الإدخالات الأقدم من **7 أيام** عند القراءة بحيث لا تتجاوز النتائج طويلة العمر الهدف المتطور للكاشف. -- **تخزين مؤقت للنتيجة الكاملة** في `~/.failproofai/audit-dashboard.json` (mode 0600). يسمح لوحة التحكم بالعرض الفوري عند التنقل بدون إعادة تشغيل. يتم رفضه أيضاً عند القراءة بعد **7 أيام TTL** — ثم ينخفض `/audit` إلى حالته الفارغة ويطالب بتشغيل جديد. انقر على `[ re-audit now ]` بالقرب من أسفل التقرير للتحديث — تُرسل إعادة التدقيق `noCache: true`، لذا فهو يتجاوز التخزين المؤقت لكل نص ويعيد فحص كل نص بدلاً من إرجاع النتيجة المخزنة مؤقتاً؛ يتدفق التشغيل التقدم عبر شريط ثابت في الأعلى ويستبدل النتيجة في المكان عند النجاح (بدون إعادة تحميل الصفحة؛ فشل إعادة التدقيق يحتفظ بالتقرير السابق). +- **ذاكرة مؤقتة لكل نص** في `~/.failproofai/cache/audit/.json` مفتاحها `(mtime, size, engineVersion, detectorVersion)` — تبطل تلقائياً عند تغيير النص أو كود السياسة/الكاشف. يخزن كل إدخال أيضاً طابع زمني `cachedAt` كـ **بيانات وصفية TTL** (ليس جزءاً من مفتاح الذاكرة المؤقتة)؛ الإدخالات الأقدم من **7 أيام** يتم رفضها عند القراءة حتى لا تتجاوز النتائج طويلة العمر النوايا المتطورة للكاشف. +- **ذاكرة مؤقتة للنتائج الكاملة** في `~/.failproofai/audit-dashboard.json` (الوضع 0600). تسمح لوحة القيادة بالعرض الفوري عند التنقل بدون إعادة تشغيل. يتم رفضها أيضاً عند القراءة بعد **TTL من 7 أيام** — يسقط `/audit` بعد ذلك في حالته الفارغة ويطلب تشغيلاً جديداً. انقر فوق `[ re-audit now ]` بالقرب من أسفل التقرير للتحديث — تحديث إعادة التدقيق يرسل `noCache: true`، لذلك يتجاوز ذاكرة النص المؤقتة ويعيد مسح كل نص بدلاً من إرجاع النتيجة المخزنة مؤقتاً؛ يقوم التشغيل بتدفق التقدم عبر شريط علوي ثابت ويبدل النتيجة في المكان عند النجاح (لا إعادة تحميل الصفحة؛ فشل إعادة التدقيق يحتفظ بالتقرير السابق). ## ملاحظات -- **بدون تعديل.** يعاد تشغيل التدقيق في وضع القراءة فقط. يتم تخطي `warn-repeated-tool-calls` لأن الملف الجانبي لكل جلسة قد يتم تعديله بخلاف ذلك. -- **سياسات سير العمل معطلة.** سياسات `require-*-before-stop` تعمل فقط على أحداث `Stop` و `execSync` ضد حالة git الحية — ليس لديها تفسير "ماذا كان سيحدث في 2025" ذو معنى، لذا لا تظهر في عدد التدقيق. -- **السياسات المخصصة معطلة.** السنانير المخصصة المُزودة من قبل المستخدم لا تتم إعادة تشغيلها (قد تكون قد تغيرت منذ الجلسة الأصلية). \ No newline at end of file +- **لا طفرة.** يعاد التدقيق بوضع القراءة فقط. يتم تخطي `warn-repeated-tool-calls` لأن الملف الجانبي لكل جلسة سيتم تعديله بخلاف ذلك. +- **سياسات سير العمل مُخطاة.** سياسات `require-*-before-stop` تطلق فقط على أحداث `Stop` و `execSync` ضد حالة git المباشرة — ليس لديها تفسير معنوي "ماذا كان سيحدث في 2025"، لذا لا تظهر في أعداد التدقيق. +- **السياسات المخصصة مُخطاة.** لا يتم إعادة تشغيل hooks المخصصة التي يوفرها المستخدم (قد تكون قد تغيرت منذ الجلسة الأصلية). \ No newline at end of file diff --git a/docs/ar/cli/dashboard.mdx b/docs/ar/cli/dashboard.mdx index 1c95f320..d01a0a88 100644 --- a/docs/ar/cli/dashboard.mdx +++ b/docs/ar/cli/dashboard.mdx @@ -8,23 +8,23 @@ description: "قم بتشغيل لوحة التحكم لاستعراض جلسا failproofai ``` -يبدأ لوحة التحكم على الويب في `http://localhost:8020`. +يبدأ لوحة التحكم الويب على `http://localhost:8020`. ## الخيارات -| العلم | الوصف | +| الراية | الوصف | |------|-------------| | `--port ` | المنفذ المراد الاستماع عليه (الافتراضي: `8020`) | -| `--allowed-origins ` | المضيفون/عناوين IP المفصولة بفواصل المسموح لها بالوصول إلى موارد التطوير | +| `--allowed-origins ` | قائمة مفصولة بفواصل من المضيفين/عناوين IP المسموح لها بالوصول إلى موارد التطوير | -لتوجيه لوحة التحكم إلى مجلد مشروع Claude غير الافتراضي، قم بتعيين متغير البيئة `CLAUDE_PROJECTS_PATH` عند التشغيل. +لتوجيه لوحة التحكم إلى مجلد مشروع Claude غير افتراضي، قم بتعيين متغير البيئة `CLAUDE_PROJECTS_PATH` عند التشغيل. ## أمثلة ```bash -# قم بالتشغيل على منفذ مختلف +# تشغيل على منفذ مختلف failproofai --port 9000 -# استخدم مسار مشاريع Claude مخصص عبر متغير البيئة +# استخدام مسار مشاريع Claude مخصص عبر متغير البيئة CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/ar/cli/environment-variables.mdx b/docs/ar/cli/environment-variables.mdx index 157652ce..614d781b 100644 --- a/docs/ar/cli/environment-variables.mdx +++ b/docs/ar/cli/environment-variables.mdx @@ -1,70 +1,66 @@ --- ---- title: متغيرات البيئة -description: "تكوين سلوك failproofai باستخدام متغيرات البيئة" +description: "قم بتكوين سلوك failproofai باستخدام متغيرات البيئة" --- -## لوحة التحكم +## لوحة المراقبة | المتغير | الوصف | |----------|-------------| -| `PORT` | منفذ لوحة التحكم (الافتراضي: `8020`) | -| `CLAUDE_PROJECTS_PATH` | تجاوز موقع مجلدات مشاريع Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | صفحات لوحة التحكم المراد إخفاؤها مفصولة بفواصل | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | المضيفات/عناوين IP المسموحة بالوصول إلى موارد التطوير. مماثل لـ `--allowed-origins`. | +| `PORT` | منفذ لوحة المراقبة (الافتراضي: `8020`) | +| `CLAUDE_PROJECTS_PATH` | تجاوز الموقع حيث يتم البحث عن مجلدات مشاريع Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | صفحات لوحة المراقبة المفصولة بفواصل لإخفاؤها | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | المضيفات/عناوين IP المسموحة للوصول إلى موارد التطوير. نفس `--allowed-origins`. | ## تسجيل السجلات | المتغير | الوصف | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | مستوى سجل الخادم (الافتراضي: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | مسار ملف السجل المخصص، أو `true` للافتراضي (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | مسار ملف السجل المخصص، أو `true` للقيمة الافتراضية (`~/.failproofai/logs/hooks.log`) | ## قياس الاستخدام -يقدم failproofai تقارير قياس استخدام مجهولة الهوية افتراضياً. هناك طريقتان لإيقافها، -وتطبق الأكثر تقييداً — لا يمكن لمتغير بيئة أبداً إعادة تفعيل شيء أوقفته ملف التكوين. +يقوم failproofai بإرسال بيانات قياس الاستخدام المجهولة افتراضيًا. هناك طريقتان لتعطيله، وستتم تطبيق الخيار الأكثر تقييدًا — متغير البيئة لا يمكنه أبدًا إعادة تفعيل شيء قام ملف الإعدادات بتعطيله. | المتغير | الوصف | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | تعطيل قياس الاستخدام المجهول الهوية لهذه العملية | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | تعطيل قياس الاستخدام المجهول لهذه العملية | -لتعطيله بشكل دائم على الجهاز، أضف هذا إلى `~/.failproofai/config.toml`: +لتعطيله بشكل دائم على الجهاز، أضف هذا إلى `~/.failproofai/config.json`: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -ملف التكوين هو الخيار المراد استخدامه إذا كنت تشغل **failproofaid daemon**. -daemon هي خدمة على مستوى النظام، وبيئتها لا تتضمن -المتغيرات المُصدَّرة من الـ shell الخاص بك — لذا لا يمكن لـ `FAILPROOFAI_TELEMETRY_DISABLED` -الوصول إليها. `[telemetry] enabled = false` تقرأها كل من CLI و daemon. +ملف الإعدادات هو الخيار الذي يجب استخدامه إذا كنت تقوم بتشغيل خدمة failproofaid daemon. +الخدمة daemon هي خدمة على مستوى النظام، وبيئتها لا تتضمن المتغيرات المُصدَّرة من محظتك — لذا لا يمكن لـ `FAILPROOFAI_TELEMETRY_DISABLED` الوصول إليها. يتم قراءة `[telemetry] enabled = false` من قبل كل من واجهة سطر الأوامر والخدمة daemon. -يقدم daemon **دورة الحياة** الخاصة به فقط: أنها بدأت (وما إذا كان الـ run السابق أُغلق بنظافة)، -أنها توقفت، عند توليد عامل التقييم أو إعادة تشغيله، عند فشل مهمة جامع، ونتيجة -سحب السياسة السحابية. هذه تحمل قيماً منخفضة الأساسية وعددات — أبداً مسار ملف، -أو أمر، أو سياسة، أو موجه، أو أي شيء مقروء من النسخة. لا توجد حدث لكل استدعاء أداة. +تقوم الخدمة daemon بإبلاغ دورة حياتها فقط: بدء التشغيل (وما إذا كان التشغيل السابق قد توقف بشكل نظيف)، إيقاف التشغيل، عندما يتم توليد عامل التقييم أو إعادة تشغيله، عندما تفشل مهمة المجمِّع، ونتيجة سحب سياسة سحابية. تحتوي هذه على قيم منخفضة التنوع وأعداد — لا تتضمن أبدًا مسار ملف أو أمر أو سياسة أو موجه أو أي شيء مقروء من نسخة. لا توجد حدث لكل استدعاء أداة. ## المصادقة | المتغير | الوصف | |----------|-------------| -| `FAILPROOF_API_URL` | تجاوز عنوان URL الأساسي لخادم api الذي تستخدمه نافذة مصادقة لوحة التحكم. الافتراضي هو `https://api.befailproof.ai`؛ عيّن إلى `http://localhost:8080` (أو في أي مكان آخر) عند تشغيل api-server محلي. | -| `FAILPROOFAI_AUTH_DIR` | تجاوز مكان تخزين `auth.json` (الافتراضي: `~/.failproofai`). مفيد في الغالب للاختبارات المعزولة. | +| `FAILPROOF_API_URL` | تجاوز عنوان URL الأساسي لخادم API الذي تستخدمه حوار مصادقة لوحة المراقبة. الافتراضي هو `https://api.befailproof.ai`؛ عيّن إلى `http://localhost:8080` (أو أي مكان آخر) عند تشغيل خادم api محلي. | +| `FAILPROOFAI_AUTH_DIR` | تجاوز حيث يتم تخزين `auth.json` (الافتراضي: `~/.failproofai`). مفيد في الغالب للاختبارات المعزولة. | ## موجه التشغيل الأول | المتغير | الوصف | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | تخطي الموجه الذي يعرض تثبيت السياسات على استدعاء `failproofai` الأول المباشر | +| `FAILPROOFAI_NO_FIRST_RUN=1` | تخطي الموجه الذي يعرض تثبيت السياسات عند أول استدعاء failproofai عادي | -## LLM (لتقييم السياسة) +## نموذج اللغة (لتقييم السياسة) | المتغير | الوصف | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | نقطة نهاية API للـ LLM (الافتراضي: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | مفتاح API للسياسات المدعومة بـ LLM | +| `FAILPROOFAI_LLM_BASE_URL` | نقطة نهاية واجهة برمجة التطبيقات للنموذج اللغوي (الافتراضي: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | مفتاح API لسياسات مدعومة بنموذج لغة | | `FAILPROOFAI_LLM_MODEL` | اسم النموذج (الافتراضي: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/ar/cli/hook.mdx b/docs/ar/cli/hook.mdx index e38a3e0d..7780924f 100644 --- a/docs/ar/cli/hook.mdx +++ b/docs/ar/cli/hook.mdx @@ -1,16 +1,16 @@ --- --- title: معالج الخطاف (داخلي) -description: "العملية الفرعية التي يستدعيها Claude Code عند كل حدث أداة" +description: "العملية الفرعية التي يستدعيها Claude Code في كل حدث أداة" --- ```bash failproofai --hook ``` -هذا هو الأمر المسجل في `settings.json` الخاص بـ Claude Code بواسطة `failproofai policies --install`. لا تستدعيه عادةً بشكل مباشر. +هذا هو الأمر المسجل في `settings.json` الخاص بـ Claude Code بواسطة `failproofai policies --install`. عادةً لا تستدعيه مباشرةً. -يقرأ حمولة JSON من stdin، ويقيّم جميع السياسات المُفعّلة، ويُنهي العملية برمز يشير إلى القرار: +يقرأ حمولة JSON من stdin، ويقيّم جميع السياسات المفعّلة، ويخرج برمز يشير إلى القرار: | رمز الخروج | القرار | التأثير | |-----------|--------|--------| @@ -21,7 +21,7 @@ failproofai --hook ### أنواع الأحداث المدعومة | الفئة | الأحداث | -|-------|--------| +|----------|--------| | **تنفيذ الأداة** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **دورة حياة الجلسة** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **تفاعل المستخدم** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | diff --git a/docs/ar/cli/install-policies.mdx b/docs/ar/cli/install-policies.mdx index 79b5f781..b0dd3601 100644 --- a/docs/ar/cli/install-policies.mdx +++ b/docs/ar/cli/install-policies.mdx @@ -1,57 +1,58 @@ --- +--- title: تثبيت السياسات -description: "تفعيل السياسات بحيث تعمل على كل استدعاء أداة للوكيل" +description: "تفعيل السياسات بحيث تعمل على كل استدعاء أداة وكيل" --- ```bash failproofai policies --install [policy-names...] [options] ``` -يكتب إدخالات الخطاف في ملف إعدادات واجهة سطر الأوامر للوكيل المثبتة لديك (Claude Code أو OpenAI Codex أو GitHub Copilot CLI _(beta)_) بحيث يعترض failproofai استدعاءات الأدوات. +يكتب مدخلات hook في ملف الإعدادات الخاص بـ CLI الوكيل المثبت لديك (Claude Code أو OpenAI Codex أو GitHub Copilot CLI _(beta)_) بحيث يقوم failproofai باعتراض استدعاءات الأدوات. -الأسماء المستعارة: `failproofai p -i` +الأسماء المختصرة: `failproofai p -i` ## الخيارات | العلم | الوصف | |------|-------------| -| `--cli claude\|codex\|copilot` | واجهة سطر أوامر الوكيل للتثبيت عليها؛ مفصولة بمسافات (مثلاً `--cli claude codex copilot`) أو مكررة. اتركها فارغة للكشف التلقائي عن واجهات سطر الأوامر المثبتة والطلب منك الاختيار. | -| `--scope user` | التثبيت في ملف الإعدادات بنطاق المستخدم (Claude: `~/.claude/settings.json`؛ Codex: `~/.codex/hooks.json`؛ Copilot: `~/.copilot/hooks/failproofai.json`). الافتراضي. | -| `--scope project` | التثبيت في ملف إعدادات نطاق المشروع (Claude: `/.claude/settings.json`؛ Codex: `/.codex/hooks.json`؛ Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Claude فقط — يثبت في `/.claude/settings.local.json`. لا يتوفر نطاق `local` في Codex و Copilot. | -| `--custom ` / `-c` | المسار إلى ملف JavaScript يحتوي على سياسات خطاف مخصصة | +| `--cli claude\|codex\|copilot` | أداة CLI الوكيل (أو الأدوات) المراد التثبيت لها؛ مفصولة بمسافات (مثل `--cli claude codex copilot`) أو مكررة. احذف للكشف عن أدوات CLI المثبتة والمطالبة بها. | +| `--scope user` | التثبيت في ملف الإعدادات ذو النطاق الخاص بالمستخدم (Claude: `~/.claude/settings.json`؛ Codex: `~/.codex/hooks.json`؛ Copilot: `~/.copilot/hooks/failproofai.json`). الافتراضي. | +| `--scope project` | التثبيت في ملف الإعدادات ذو النطاق الخاص بالمشروع (Claude: `/.claude/settings.json`؛ Codex: `/.codex/hooks.json`؛ Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Claude فقط — يثبت في `/.claude/settings.local.json`. لا يملك Codex و Copilot نطاق `local`. | +| `--custom ` / `-c` | المسار إلى ملف JS يحتوي على سياسات hook مخصصة | ## السلوك - **بدون أسماء سياسات** - يفتح موجه تفاعلي لتحديد السياسات - **أسماء محددة** - تفعيل تلك السياسات (تضاف إلى أي سياسات مفعلة بالفعل) -- **`all`** - تفعيل كل السياسات المتاحة +- **`all`** - تفعيل كل سياسة متاحة التثبيت تراكمي: تشغيل `--install` مرة أخرى يضيف سياسات جديدة دون إزالة السياسات الموجودة. ## أمثلة ```bash -# Install all default policies globally (interactive) +# تثبيت جميع السياسات الافتراضية عالميًا (تفاعلي) failproofai policies --install -# Install specific policies for the current project +# تثبيت سياسات محددة للمشروع الحالي failproofai policies --install block-sudo sanitize-api-keys --scope project -# Enable all policies at once +# تفعيل جميع السياسات في نفس الوقت failproofai policies --install all -# Install with a custom policies file +# التثبيت مع ملف سياسات مخصص failproofai policies --install --custom ./my-policies.js -# Install for OpenAI Codex (project scope) +# التثبيت لـ OpenAI Codex (نطاق المشروع) failproofai policies --install --cli codex --scope project -# Install for GitHub Copilot CLI (beta) for the current project +# التثبيت لـ GitHub Copilot CLI (beta) للمشروع الحالي failproofai policies --install --cli copilot --scope project -# Install for all three CLIs at once +# التثبيت لأدوات CLI الثلاث في نفس الوقت failproofai policies --install --cli claude codex copilot ``` -عند توفير `--custom `، يتم التحقق من صحة الملف على الفور - يجب أن يستدعي `customPolicies.add()` مرة واحدة على الأقل. يتم حفظ المسار المحل في `policies-config.json` باسم `customPoliciesPath`. \ No newline at end of file +عند توفير `--custom `، يتم التحقق من صحة الملف فورًا - يجب أن يستدعي `customPolicies.add()` مرة واحدة على الأقل. يتم حفظ المسار المحلل في `policies-config.json` كـ `customPoliciesPath`. \ No newline at end of file diff --git a/docs/ar/cli/list-policies.mdx b/docs/ar/cli/list-policies.mdx index fbcf4cee..1c211e01 100644 --- a/docs/ar/cli/list-policies.mdx +++ b/docs/ar/cli/list-policies.mdx @@ -1,16 +1,15 @@ --- ---- title: قائمة السياسات -description: "معرفة السياسات المفعّلة وموارديها والسياسات المخصصة" +description: "اطلع على السياسات المفعّلة وعواملها والسياسات المخصصة" --- ```bash failproofai policies ``` -يعرض جميع السياسات مع حالتها والمعاملات المكوّنة والسياسات المخصصة. +يعرض جميع السياسات مع حالتها والعوامل المكونة والسياسات المخصصة. -## عينة من المخرجات +## عينة من النتيجة ```text Failproof AI Hook Policies (user) @@ -29,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -يتم التعليم هنا على المفاتيح غير المعروفة في `policyParams` حتى تتمكن من اكتشاف الأخطاء الإملائية مبكراً. \ No newline at end of file +يتم وضع علامة على المفاتيح غير المعروفة في `policyParams` هنا حتى تتمكن من اكتشاف الأخطاء الإملائية مبكراً. \ No newline at end of file diff --git a/docs/ar/cli/migrate.mdx b/docs/ar/cli/migrate.mdx new file mode 100644 index 00000000..5335928e --- /dev/null +++ b/docs/ar/cli/migrate.mdx @@ -0,0 +1,114 @@ +--- +--- +title: نقل دليل المنزل +description: "أحضر ~/.failproofai إلى التخطيط الذي تتحدثه هذه النسخة، واطّلع على ما قد يحدث أولاً" +--- + +```bash +failproofai migrate --dry-run # print the plan, change nothing +failproofai migrate # run it +``` + +معظم الناس لا يكتبون هذا أبداً. يعمل بنفسه في الأمر الأول بعد الترقية، وَ +[`failproofai update`](/ar/cli/update) يتضمنه. استخدمه مباشرة عندما تريد رؤية الخطة قبل حدوثها، أو لتشغيل الهجرة +بمفردها. + +## مفتاح على التخطيط، وليس على النسخة + +يسجل `~/.failproofai/VERSION` رقم **التخطيط** — شكل الدليل، +وليس الإصدار الذي كتبه. يتم تفعيل الهجرات على هذا الرقم، وهو ما +يجعل الفجوة الطويلة رخيصة: + +- إصدارات npm تتغير في كل إصدار، عشرات منها بين تخطيطين. +- لذا فإن الجهاز الذي يتخطى ثلاثين إصدار بـ **عدم تغيير التخطيط** يشغل **صفر** + هجرات، وليس ثلاثين عملية لا مجدية. +- والجهاز الذي يتخطى عدة تخطيطات مرة واحدة يشغل كل خطوة بالترتيب، كل + خطوة تعرف فقط طرفيها الخاصين. + +هذا مهم لأن npm لا يمكنه تحديث حزمة مثبتة بمفردها. جهاز +يبقى على نسخة واحدة لأشهر ثم يقفز عدة تخطيطات هو الحالة العادية، وليس حالة غريبة. + +## عملية التجربة الجافة + +يطبع `--dry-run` السلسلة الدقيقة والملفات التي سيتم حفظها أولاً، و +لا يغير شيئاً على الإطلاق — لا هجرة، لا نسخة احتياطية، لا إدخال دفتر: + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## ما يتم نقله وما يتم إعادة بناؤه + +كل مسار في المنزل يعلن نوع البيانات التي يحتفظ بها، وهذا يحدد +ما إذا كانت هجرة قد ترميها بعيداً. القاعدة: **المشتق والقابل إعادة الجلب قد يتم إسقاطه؛ أي شيء كتبته، +أي شيء لم يتم تسليمه بعد، وأي شيء يعرّف الجهاز يتم نقله.** + +| تم نقله | تم إعادة بناؤه أو إعادة جلبه | +|---|---| +| `config.json` — الإعدادات، `daemon.configured`، مسارات الالتقاط الإضافية | ذاكرة التدقيق | +| `credentials.json` — تسجيل الالتحاق بالسحابة | عمليات النشر المدارة بالسحابة (إعادة الجلب والتحقق من الملخص في الاستطلاع التالي) | +| `policies-config.json` — اختيار السياسة والمعاملات | حالة الخدش من الخادم | +| `policies/` — ملفات السياسة الخاصة بك والمساعدات التي تستورد | | +| `hook-activity/` — سجل القرار الذي تقرأه لوحة المعلومات | | +| الأحداث غير المسلمة لا تزال في قائمة الانتظار للتحميل | | +| `cursors/` — علامات المجمع | | +| الثنائي daemon في `bin/` | | + + + يتم نقل الأحداث غير المسلمة بدلاً من إسقاطها لأن الخسارة ستكون + دائمة، وليست بطيئة: قد تقدمت علامة المجمع بالفعل بعد + أي شيء يجلس في البكرة، لذا لن يقرأ أي شيء هذا النطاق من نسخة + النص مرة أخرى. تطلب الهجرة أيضاً من الخادم تسليم ما هو مبثوث + حالما ينتهي، لذا فإن النتيجة المعتادة هي أنه لا يوجد شيء متبقي + لنقله. + + +تم الحفاظ على المفاتيح التي كتبتها نسخة **أحدث** في `config.json`، `credentials.json` أو +`policies-config.json` أيضاً، بدلاً من إسقاطها بواسطة قارئ أقدم. + +## السجل الذي يتركه + +``` +~/.failproofai/migrations/ + applied.json one entry per step: layout, CLI, timestamp, duration, result + backup-layout/ copies of the irreplaceable files, taken before the first step +``` + +`applied.json` هو ما يجيب على السؤال: ماذا مرّ هذا الجهاز بالفعل — أول +سؤال يستحق طرحه عندما يبدو شيء ما خاطئ بعد ترقية. أرفقه +بتقرير خطأ. + +النسخة الاحتياطية صغيرة عن قصد بدلاً من نسخة الدليل بالكامل: لا تحذف الهجرة +أي شيء لا يمكن استبداله بالتصميم، لذا ما يستحق التأمين ضده هو +**عيب في خطوة**، وهذه الملفات القليلة هي حيث قد يؤذي مثل هذا العيب. + +## إذا فشلت خطوة + +تتوقف السلسلة هناك. يتم ختم `VERSION` فقط من قبل خطوة اكتملت، لذا يبقى +المنزل ملحوظاً بتخطيطه القديم والأمر التالي يعيد محاولته — لا يتم وضع علامة على المنزل أبداً +بناءً على قوة هجرة جزئية. يتم تسجيل الخطوة +في `applied.json` مع `"ok": false`، والنسخة الاحتياطية موجودة حيث تم أخذها. + +## يتم رفض المنزل الأحدث، وليس هجرته + +إذا تمت كتابة `~/.failproofai/` بواسطة **أحدث** failproofai من +الذي تقوم بتشغيله، يتوقف الأمر ويخبرك بالترقية بدلاً من ذلك. هذه البيانات +جيدة وتقرأها CLI أحدث؛ الهجرة "للأمام" منها ليست شيء موجود، +وإعادة تعيينها ستدمر شيء قابل للاسترجاع. + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +ينطبق الخادم نفس القاعدة: `failproofaid` يرفض البدء ضد تخطيط +لا يتحدثه، بدلاً من قراءة والكتابة إلى مسارات انتقلت. \ No newline at end of file diff --git a/docs/ar/cli/remove-policies.mdx b/docs/ar/cli/remove-policies.mdx index d4a51a9b..de57597f 100644 --- a/docs/ar/cli/remove-policies.mdx +++ b/docs/ar/cli/remove-policies.mdx @@ -1,31 +1,31 @@ --- --- title: إلغاء تثبيت السياسات -description: "إزالة إدخالات الخطافات من إعدادات Claude Code" +description: "إزالة مدخلات الخطاف من إعدادات Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -يزيل إدخالات خطافات failproofai من `settings.json` الخاص بـ Claude Code. +يزيل مدخلات خطاف failproofai من `settings.json` الخاص بـ Claude Code. -الاختصارات: `failproofai p -u` +الأسماء المستعارة: `failproofai p -u` ## الخيارات -| العلم | الوصف | +| الراية | الوصف | |------|-------------| -| `--scope user` | الإزالة من الإعدادات العامة (الافتراضي) | -| `--scope project` | الإزالة من إعدادات المشروع | -| `--scope local` | الإزالة من الإعدادات المحلية | -| `--scope all` | الإزالة من جميع النطاقات في وقت واحد | +| `--scope user` | إزالة من الإعدادات العامة (الافتراضي) | +| `--scope project` | إزالة من إعدادات المشروع | +| `--scope local` | إزالة من الإعدادات المحلية | +| `--scope all` | إزالة من جميع الأنطقة في نفس الوقت | | `--custom` / `-c` | مسح `customPoliciesPath` من الإعدادات | ## السلوك -- **بدون أسماء سياسات** - يزيل جميع إدخالات خطافات failproofai من ملف الإعدادات -- **أسماء محددة** - يعطل تلك السياسات لكن يبقي الخطافات مثبتة +- **بدون أسماء سياسات** - إزالة جميع مدخلات خطاف failproofai من ملف الإعدادات +- **أسماء محددة** - تعطيل تلك السياسات لكن الحفاظ على الخطافات المثبتة ## أمثلة @@ -33,7 +33,7 @@ failproofai policies --uninstall [policy-names...] [options] # إزالة جميع الخطافات عالمياً failproofai policies --uninstall -# تعطيل سياسة محددة (يبقي الخطافات مثبتة) +# تعطيل سياسة محددة (الحفاظ على الخطافات المثبتة) failproofai policies --uninstall block-sudo # إزالة الخطافات من كل نطاق diff --git a/docs/ar/cli/update.mdx b/docs/ar/cli/update.mdx new file mode 100644 index 00000000..72538020 --- /dev/null +++ b/docs/ar/cli/update.mdx @@ -0,0 +1,64 @@ +--- +title: التحديث بعد ترقية النسخة +description: "أكمل النصف الآخر من الترقية الذي لا يستطيع npm إنجازه: قم بترحيل المجلد الرئيسي ومطابقة daemon" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +هذا هو الترقية كاملة. `npm` يستبدل CLI؛ `failproofai update` يقوم بالباقي. + +## لماذا يوجد أمر ثاني + +`npm install -g` يستبدل شيء واحد فقط — CLI. هناك قطعتان أخريان من failproofai موجودة خارج الحزمة عن قصد، وكلاهما لا يتحرك عند تشغيل npm: + +- **`~/.failproofai/`**، إعداداتك، تسجيل السحابة، اختيار السياسة والسجل. قد تنظم نسخة جديدة الأشياء بطريقة مختلفة، والإعادة يجب أن تتم بواسطة رمز يعرف كلا الشكليْن. +- **ملف daemon الثنائي `failproofaid`**، في `~/.failproofai/bin/failproofaid-`. وهو متعمدًا *ليس* داخل `node_modules`: ترقية تستبدل الملف تحت خدمة قيد التشغيل ستعيد توجيه daemon حي إلى ملف ثنائي مبني من مصدر مختلف، وحذف الحزمة سيحذفه من تحت خدمة تتعطل بعد ذلك عند كل إقلاع. + +لذا بعد `npm install -g` وحده، CLI جديد و daemon ليس كذلك. `failproofaid` يرفض البدء ضد تخطيط منزلي لا يفهمه — النسخة الصاخبة من عدم التطابق بدلاً من النسخة الصامتة — لذلك يجب جمع النصفيْن معًا. `failproofai update` هي تلك الخطوة. + +## ما الذي يفعله + + + + يقرأ التخطيط المسجل في `~/.failproofai/VERSION` ويقوم بتشغيل الخطوات التي تحضره إلى الذي تتحدث به هذه النسخة. عادةً لا يوجد أي شيء — انظر [`failproofai migrate`](/ar/cli/migrate). + + + من حزمة النظام الأساسي التي قام npm بتحميلها بالفعل حيث أمكن (بدون شبكة)، وإلا من أصل الإصدار لهذه النسخة بالضبط، تم التحقق منها بـ SHA-256 قبل استخدامها. + + + يتم التحقق منها بدلاً من افتراضها — مدير الخدمة يبلغ عن عملية نشطة في اللحظة التي تتفرع فيها، وهذا ليس نفس الشيء الذي يعمل. + + + +## الخيارات + +| العلم | التأثير | +|------|--------| +| `--no-daemon` | ترحيل المجلد الرئيسي فقط، تاركًا daemon في نسخته الحالية. | + + + `--no-daemon` يترك daemon متباعد النسخة في مكانه. على آلة تم تكوينها لتتطلب daemon، كل حدث hook **يفشل مغلقًا** إذا لم يتمكن daemon من الإجابة — و daemon الذي يرفض البدء ضد منزل مهجَّر لا يستطيع الإجابة. يفضل السماح لنصف daemon بالتشغيل. + + +## إذا حدث خطأ ما + +يخرج الأمر بقيمة غير صفرية ويقول أي نصف فشل. حالتان تستحقان المعرفة: + +- **لم تنته خطوة ترحيل.** المجلد الرئيسي يُترك محددًا بتخطيطه *القديم*، لذا الأمر التالي يحاول مرة أخرى — لا يتم وضع علامة على أي منزل بالحالة الحالية على قوة ترحيل جزئي. تم حفظ نسخ من إعداداتك وتسجيل السحابة قبل تشغيل أي شيء، في `~/.failproofai/migrations/backup-layout/`. +- **لم يتمكن daemon من إعادة التشغيل بدون كلمة مرور.** `sudo -n` يُستخدم عن قصد، لذا لا شيء يطالب أبدًا من تحت عرض التقدم. يطبع الأمر السطر الدقيق لتشغيله بنفسك. + + + لا شيء هنا يحتاج إلى معالج الإعداد التفاعلي. إعداداتك، تسجيل السحابة واختيار السياسة تبقى بعد ترقية النسخة، لذا آلة مهجَّرة تطبق تمامًا كما كانت من قبل — وهذا يهم أكثر على الآلات بلا أحد يجلس عندها: عامل CI، صندوق الأسطول، بوابة بدون رأس. + + +## أتمتتها + +`failproofai update` غير تفاعلي وآمن للتشغيل عندما لا يكون هناك ما يجب فعله — فهو يبلغ "لم يكن هناك ترحيل مطلوب" ويخرج بـ 0. وضعه بعد كل ترقية نسخة في نص توفير أو Dockerfile هو الاستخدام المقصود: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` في بناء صورة، حيث لا توجد خدمة لإعادة تشغيلها حتى الآن.) \ No newline at end of file diff --git a/docs/ar/cli/version.mdx b/docs/ar/cli/version.mdx index 84573b2b..3d96ce79 100644 --- a/docs/ar/cli/version.mdx +++ b/docs/ar/cli/version.mdx @@ -1,6 +1,5 @@ --- ---- -title: التحقق من الإصدار +title: تحقق من الإصدار description: "طباعة إصدار failproofai المثبت" --- diff --git a/docs/ar/configuration.mdx b/docs/ar/configuration.mdx index c52a598e..d01854b3 100644 --- a/docs/ar/configuration.mdx +++ b/docs/ar/configuration.mdx @@ -1,25 +1,25 @@ --- --- title: الإعدادات -description: "صيغة ملف التكوين، نظام النطاقات الثلاثة، وقواعد الدمج" +description: "صيغة ملف الإعدادات، نظام النطاقات الثلاثة، وقواعد الدمج" icon: gear --- -يستخدم failproofai ملفات تكوين JSON للتحكم في السياسات النشطة وكيفية عملها ومن أين يتم تحميل السياسات المخصصة. تم تصميم الإعدادات لسهولة المشاركة مع فريقك - قم بالالتزام بها في مستودعك وسيحصل كل مطور على نفس شبكة الأمان للعامل. +يستخدم failproofai ملفات إعدادات JSON للتحكم في السياسات النشطة وكيفية عملها ومن أين يتم تحميل السياسات المخصصة. تم تصميم الإعدادات لتكون سهلة المشاركة مع فريقك - قم بإدراجها في مستودع الكود وسيحصل كل مطور على نفس شبكة الأمان للعامل. --- ## نطاقات الإعدادات -هناك ثلاثة نطاقات للإعدادات، يتم تقييمها بترتيب الأولوية: +هناك ثلاثة نطاقات إعدادات، يتم تقييمها حسب أولويتها: | النطاق | مسار الملف | الغرض | |-------|-----------|---------| -| **المشروع** | `.failproofai/policies-config.json` | إعدادات لكل مستودع، التزام في التحكم بالإصدارات | -| **محلي** | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، مُستثناة من git | +| **المشروع** | `.failproofai/policies-config.json` | إعدادات خاصة بالمستودع، مرتبطة بنظام التحكم بالإصدارات | +| **محلي** | `.failproofai/policies-config.local.json` | عمليات تجاوز شخصية خاصة بالمستودع، مستثناة من التتبع | | **عام** | `~/.failproofai/policies-config.json` | الإعدادات الافتراضية على مستوى المستخدم عبر جميع المشاريع | -عندما يتلقى failproofai حدث خطاف، يقوم بتحميل ودمج جميع الملفات الثلاثة الموجودة للمجلد الحالي. +عندما يتلقى failproofai حدث ربط، يقوم بتحميل ودمج جميع الملفات الثلاثة الموجودة في المجلد العامل الحالي. ### قواعد الدمج @@ -30,16 +30,16 @@ project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← اتحاد مُلغى التكرار +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← اتحاد منزوع التكرار ``` -**`policyParams`** - أول نطاق يحدد المعاملات لسياسة معينة يفوز بالكامل. لا يوجد دمج عميق للقيم داخل معاملات السياسة. +**`policyParams`** - أول نطاق يحدد معاملات لسياسة معينة يفوز تماماً. لا يوجد دمج عميق للقيم داخل معاملات السياسة. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← يفوز المشروع، يتم تجاهل النطاق العام +resolved: { allowPatterns: ["sudo apt-get update"] } ← المشروع ينتصر، العام يتم تجاهله ``` ```text @@ -47,14 +47,14 @@ project: (no block-sudo entry) local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← يتم الرجوع للنطاق العام +resolved: { allowPatterns: ["sudo systemctl status"] } ← ينتقل إلى العام ``` -**`customPoliciesPaths` / `customPoliciesPath`** - أول نطاق يحدد أي شكل يفوز. +**`customPoliciesPaths` / `customPoliciesPath`** - أول نطاق يحدد أي من الشكلين ينتصر. -**`disabledCustomPolicies`** - اتحاد عبر جميع النطاقات. لوحة المعلومات تكتب معرف مؤهل بالمصدر هنا عند إيقاف تشغيل سياسة فردية من ملف سياسة صريح أو حسب العرف. السياسات غير المدرجة تبقى مفعلة بشكل افتراضي؛ المعرفات تتضمن ملف المصدر بحيث يمكن التحكم في السياسات بنفس الاسم في ملفات متعددة بشكل مستقل. +**`disabledCustomPolicies`** - اتحاد عبر جميع النطاقات. لوحة المعلومات تكتب معرف مؤهل للمصدر هنا عندما تطفئ سياسة فردية من ملف سياسة صريح أو اتفاقي. السياسات غير المدرجة تبقى مفعلة بشكل افتراضي؛ المعرفات تتضمن ملف المصدر بحيث يمكن التحكم في السياسات بنفس الاسم في ملفات متعددة بشكل مستقل. -**`llm`** - أول نطاق يحددها يفوز. +**`llm`** - أول نطاق يحددها ينتصر. --- @@ -105,27 +105,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← يتم الرجوع النوع: `string[]` -قائمة أسماء السياسات المراد تفعيلها. يجب أن تطابق الأسماء تماماً معرفات السياسات التي تظهرها `failproofai policies`. راجع [السياسات المدمجة](/ar/built-in-policies) للحصول على القائمة الكاملة. +قائمة أسماء السياسات التي يجب تفعيلها. يجب أن تتطابق الأسماء تماماً مع معرفات السياسات التي تعرضها `failproofai policies`. انظر [السياسات المدمجة](/ar/built-in-policies) للقائمة الكاملة. -السياسات غير المدرجة في `enabledPolicies` غير نشطة، حتى لو كانت لديها إدخالات في `policyParams`. +السياسات التي ليست في `enabledPolicies` غير نشطة، حتى لو كانت لديها إدخالات في `policyParams`. ### `policyParams` النوع: `Record>` -تجاوزات المعاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ المفاتيح الداخلية خاصة بكل سياسة. توثق كل سياسة معاملاتها المتاحة في [السياسات المدمجة](/ar/built-in-policies). +عمليات تجاوز المعاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ المفاتيح الداخلية خاصة بالسياسة. توثق كل سياسة معاملاتها المتاحة في [السياسات المدمجة](/ar/built-in-policies). -إذا كان للسياسة معاملات لكنك لم تحددها، يتم استخدام القيم الافتراضية المدمجة للسياسة. المستخدمون الذين لا يقومون بتكوين `policyParams` على الإطلاق يحصلون على سلوك متطابق للإصدارات السابقة. +إذا كانت لسياسة ما معاملات لكنك لم تحددها، يتم استخدام الافتراضيات المدمجة للسياسة. المستخدمون الذين لا يعدلون `policyParams` على الإطلاق يحصلون على السلوك المطابق للإصدارات السابقة. -المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت في وقت إطلاق الخطاف ولكن يتم وضع علم عليها كتحذيرات عند تشغيل `failproofai policies`. +المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت في وقت إطلاق الربط ولكن يتم التحذير منها عند تشغيل `failproofai policies`. -#### `hint` (عبر الأنظمة) +#### `hint` (عابر) النوع: `string` (اختياري) -رسالة مُلحقة بالسبب عندما تُرجع السياسة `deny` أو `instruct`. استخدمها لمنح Claude إرشادات قابلة للتنفيذ دون تعديل السياسة نفسها. +رسالة تُضاف إلى السبب عندما تُرجع السياسة `deny` أو `instruct`. استخدمها لإعطاء Claude توجيهات قابلة للتنفيذ دون تعديل السياسة نفسها. -يعمل مع أي نوع سياسة — مدمجة أو مخصصة (`custom/`) أو اتفاقية المشروع (`.failproofai-project/`) أو اتفاقية المستخدم (`.failproofai-user/`). +يعمل مع أي نوع سياسة — مدمج، مخصص (`custom/`)، اتفاقي للمشروع (`.failproofai-project/`)، أو اتفاقي للمستخدم (`.failproofai-user/`). ```json { @@ -138,53 +138,59 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← يتم الرجوع "hint": "استخدم apt-get مباشرة بدون sudo." }, "custom/my-policy": { - "hint": "اطلب موافقة المستخدم أولاً." + "hint": "اطلب من المستخدم الموافقة أولاً." } } } ``` -عند رفض `block-force-push`، يرى Claude: *"دفع القوة مُحظور. جرب إنشاء فرع جديد بدلاً من ذلك."* +عندما يرفض `block-force-push`، يرى Claude: *"الفرض الدفع محظور. جرب إنشاء فرع جديد بدلاً من ذلك."* -القيم غير النصية والنصوص الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، يبقى السلوك دون تغيير (متوافق مع الإصدارات السابقة). +القيم غير النصية والنصوص الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، يكون السلوك دون تغيير (متوافق بالعودية). ### `customPoliciesPath` -النوع: `string` (المسار المطلق) +النوع: `string` (مسار مطلق) -المسار إلى ملف JavaScript يحتوي على سياسات خطاف مخصصة. يتم تعيينها تلقائياً بواسطة `failproofai policies --install --custom ` (يتم حل المسار إلى مطلق قبل تخزينه). +مسار ملف JavaScript يحتوي على سياسات ربط مخصصة. يتم تعيين هذا تلقائياً بواسطة `failproofai policies --install --custom ` (يتم حل المسار إلى مطلق قبل تخزينه). -يتم تحميل الملف بشكل جديد في كل حدث خطاف - لا يوجد تخزين مؤقت. راجع [السياسات المخصصة](/ar/custom-policies) لتفاصيل الإنشاء. +يتم تحميل الملف بشكل جديد في كل حدث ربط - لا يوجد تخزين مؤقت. انظر [السياسات المخصصة](/ar/custom-policies) للحصول على تفاصيل الإنشاء. -### سياسات قائمة على الاتفاقية +### السياسات المستندة إلى الاتفاقيات -بالإضافة إلى `customPoliciesPath` الصريح، يكتشف failproofai ويحمل ملفات السياسات تلقائياً من مجلدات `.failproofai/policies/`: +بالإضافة إلى `customPoliciesPath` الصريح، يكتشف failproofai تلقائياً ويحمل ملفات السياسات من مجلدات `.failproofai/policies/`: | المستوى | المجلد | النطاق | |-------|-----------|-------| | المشروع | `.failproofai/policies/` | مشترك مع الفريق عبر التحكم بالإصدارات | -| المستخدم | `~/.failproofai/policies/custom-policies/` | شخصي، ينطبق على جميع المشاريع | +| المستخدم | `~/.failproofai/policies/` | شخصي، ينطبق على جميع المشاريع | - تم نقل مجلد مستوى المستخدم إلى أسفل مستوى واحد في إعادة تنظيم دليل المنزل. - الملفات المتبقية في المجلد القديم `~/.failproofai/policies/` يتم نقلها إلى - `custom-policies/` تلقائياً في المرة الأولى التي تقوم فيها بتشغيل أي أمر failproofai - بعد الترقية، والأمر يخبرك بالملفات التي تم نقلها. + ضع سياساتك مباشرة في `~/.failproofai/policies/`. مجلد + `cloud-policies/` بجانبهم يحتوي على السياسات التي نشرتها مؤسستك + على هذه الآلة — الاكتشاف لا ينزل إلى المجلدات الفرعية، لذا لا يتم فحصه أبداً، و + لا شيء تضعه في `policies/` يمكنه التضارب معه. + + إذا كنت ترقي من إصدار استخدم + `~/.failproofai/policies/custom-policies/`، كل شيء في هذا المجلد — ملفات + السياسة الخاصة بك، أي `lib/` من المساعدات التي تستوردها، وأي ملفات بيانات تقرأها — + يتم نقله للخلف تلقائياً في المرة الأولى التي تشغل فيها أي أمر `failproofai`، + والأمر يخبرك بما نقله. -**مطابقة الملفات:** يتم تحميل الملفات المطابقة فقط `*policies.{js,mjs,ts}` (مثل `security-policies.mjs`، `workflow-policies.js`). يتم تجاهل الملفات الأخرى في المجلد. +**مطابقة الملفات:** يتم تحميل الملفات المطابقة لـ `*policies.{js,mjs,ts}` فقط (مثل `security-policies.mjs`, `workflow-policies.js`). الملفات الأخرى في المجلد يتم تجاهلها. -**لا حاجة للتكوين:** سياسات الاتفاقية لا تتطلب إدخالات في `policies-config.json`. ما عليك سوى إسقاط الملفات في المجلد وسيتم التقاطها في حدث الخطاف التالي. +**لا تحتاج إلى إعدادات:** سياسات الاتفاقيات لا تتطلب إدخالات في `policies-config.json`. فقط ضع الملفات في المجلد وسيتم انتقاؤها في حدث الربط التالي. -**تحميل الاتحاد:** يتم مسح كلا من مجلدات اتفاقية المشروع والمستخدم. يتم تحميل جميع الملفات المطابقة من كلا المستويين (بخلاف `customPoliciesPath` الذي يستخدم first-scope-wins). +**التحميل الموحد:** يتم فحص كل من مجلدات الاتفاقيات للمشروع والمستخدم. تُحمل جميع الملفات المطابقة من كلا المستويين (بخلاف `customPoliciesPath` الذي يستخدم أول نطاق ينتصر). -راجع [السياسات المخصصة](/ar/custom-policies) لمزيد من التفاصيل والأمثلة. +انظر [السياسات المخصصة](/ar/custom-policies) للمزيد من التفاصيل والأمثلة. ### `llm` النوع: `object` (اختياري) -إعدادات عميل LLM للسياسات التي تقوم باستدعاءات AI. غير مطلوبة لمعظم الإعدادات. +تكوين عميل LLM للسياسات التي تجري استدعاءات AI. غير مطلوب لمعظم الإعدادات. ```json { @@ -199,24 +205,24 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← يتم الرجوع ## إدارة الإعدادات من CLI -تقوم أوامر `policies --install` و `policies --uninstall` بالكتابة إلى ملف إعدادات الخطاف لـ CLI العامل الخاص بك (نقاط دخول الخطاف)، بينما `policies-config.json` هو الملف الذي تديره مباشرة. كلاهما منفصل: +تكتب أوامر `policies --install` و `policies --uninstall` إلى ملف إعدادات ربط CLI العامل (نقاط دخول الربط)، في حين أن `policies-config.json` هو الملف الذي تديره مباشرة. الاثنان منفصلان: -- **إعدادات Agent CLI** — تخبر العامل باستدعاء `failproofai --hook ` على كل استخدام أداة: +- **إعدادات CLI العامل** — تخبر العامل باستدعاء `failproofai --hook ` في كل استخدام أداة: - **Claude Code**: `~/.claude/settings.json` (مستخدم)، `/.claude/settings.json` (مشروع)، `/.claude/settings.local.json` (محلي) - - **OpenAI Codex**: `~/.codex/hooks.json` (مستخدم)، `/.codex/hooks.json` (مشروع) — Codex لا يوجد لديه نطاق محلي - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (مستخدم)، `/.github/hooks/failproofai.json` (مشروع) — Copilot لا يوجد لديه نطاق محلي. إدخالات الخطاف تستخدم حقول الأوامر الخاصة بـ Copilot المفتاحة بنظام التشغيل `bash`/`powershell` مع `timeoutSec`؛ الملف يحمل علامة `version: 1` على المستوى الأعلى. دعم Copilot CLI **بيتا** بينما نتحقق من مخطط سجل `events.jsonl` (التي لا توضحه المستندات العامة) مقابل المزيد من جلسات العالم الحقيقي. **وضع عامل VS Code Copilot Chat (معاينة)** يقرأ إعدادات الخطاف من `.github/hooks/*.json`، `~/.copilot/hooks/*.json`، و `~/.claude/settings.json` (يحكمها إعداد `chat.hookFilesLocations`) باستخدام نفس عقد Claude الشكلي `{hookSpecificOutput:{permissionDecision:"deny",…}}` — المسارات الدقيقة التي تكتبها تكامل `copilot` هذا وتكامل `claude` (`~/.claude/settings.json`) بالفعل، لذا فإن `failproofai policies --install --cli copilot` (أو `--cli claude`) **بالفعل يفرض في وضع VS Code agent** بدون الحاجة إلى تكامل منفصل `vscode` (مؤكد من سجلات اكتشاف VS Code). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (مستخدم)، `/.cursor/hooks.json` (مشروع) — Cursor لا يوجد لديه نطاق محلي. إدخالات الخطاف تستخدم شكل Claude الشكلي `{type, command, timeout}` (لا يوجد تقسيم `bash`/`powershell`)، لكن مخزنة تحت مفاتيح الأحداث camelCase (`preToolUse`، `beforeSubmitPrompt`، …) في مصفوفة مسطحة لكل [مخطط الخطافات](https://cursor.com/docs/hooks) الخاص بـ Cursor؛ الملف يحمل علامة `version: 1` على المستوى الأعلى. معالج يقوم بتحويل camelCase → PascalCase عبر `CURSOR_EVENT_MAP` لذا السياسات المدمجة الموجودة تطلق بدون تغيير. دعم Cursor Agent **بيتا** بينما نتحقق من نسخة Cursor على القرص (غير محددة في المستندات العامة) مقابل المزيد من الثبتات في العالم الحقيقي. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (مستخدم)، `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (مشروع) — OpenCode لا يوجد لديه نطاق محلي. بخلاف الـ CLIs الخمسة الأخرى، OpenCode **لا يوجد لديه نظام خطاف أوامر خارجية**: يحمل في العملية JS/TS ملحقات مسجلة بشكل صريح عبر مصفوفة `plugin: []` في `opencode.json` (الاكتشاف التلقائي من `.opencode/plugins/` **ليس** كيفية تحميل الملحقات على opencode v1.14.33). التثبيت يضع shim ملحق صغير مولد يقوم باستدعاء ثنائي failproofai في عملية فرعية ويترجم استجابة JSON للثنائي مرة أخرى إلى دلالات الملحقات: `throw new Error()` لرفض حدث الأداة (يلغي استدعاء الأداة)، `client.session.prompt(...)` لـ `instruct` و `Stop` / `SubagentStop` رفع (يرسل سبب الرفض كرسالة المستخدم التالية — القناة الوحيدة لإعادة المحاولة القسرية منذ `session.idle` إخطار فقط وإرسال من خلالها لا تؤثر)، و no-op للسماح. shim يقوم بتحويل أسماء الأدوات (lowercase → PascalCase عبر `OPENCODE_TOOL_MAP`) وعناصر إدخال الأداة (camelCase → snake_case عبر `OPENCODE_TOOL_INPUT_MAP` لـ `Read` / `Write` / `Edit`، مثل `filePath` → `file_path`، `oldString` → `old_string`) قبل التوجيه إلى الثنائي، لذا فإن مدقق المسار المدمج مثل `block-read-outside-cwd`، `block-env-files`، و `block-secrets-write` طلقات تغيير على استدعاءات أداة OpenCode. الجلسات تعيش في قاعدة بيانات SQLite الخاصة بـ opencode في `~/.local/share/opencode/opencode.db`؛ عارض جلسات لوحة المعلومات يقرأها عبر `opencode db --format json` و `opencode export `. دعم OpenCode **بيتا** بينما نتحقق من السلوك عبر الإصدارات والمزيد من جلسات العالم الحقيقي. راجع [مستندات ملحقات OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (مستخدم)، `/.pi/settings.json` (مشروع) — Pi لا يوجد لديه نطاق محلي. Pi يحمل حزم امتدادات TypeScript عند بدء التشغيل؛ ملف الإعدادات هو مصفوفة نصوص مسطحة `{"packages": ["./relative/path", …]}`. failproofai يكتب إدخال مصفوفة packages واحد يشير إلى مجلد `pi-extension/` المجمع الخاص به. امتداد داخلي يشترك في أحداث Pi `tool_call` / `user_bash` / `input` / `session_start` ويشغل الأوامر إلى `failproofai --hook --cli pi`؛ معالج يقوم بتحويل underscore_lower_snake_case → PascalCase عبر `PI_EVENT_MAP` لذا السياسات المدمجة الموجودة تطلق بدون تغيير. وسيطات إدخال الأداة أيضاً مُعادة عبر `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit توفر `path` بدلاً من `file_path`؛ تعيين المفتاح ذو المستوى الأعلى يترك `block-env-files` و `block-secrets-write` طلقات — `block-read-outside-cwd` كان بالفعل لديه fallback `path`). دعم Pi **بيتا** بينما امتدادات Pi API وتخطيط سجل الجلسة استقرار. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**نطاق المستخدم فقط** — Hermes لا يوجد لديه تكوين مشروع/محلي). Hermes هو بوابة Slack/Telegram **، لذا يعترض تثبيت واحد استدعاءات الأداة من كل منصة (Slack/Telegram/cli/cron) **و** subagents داخلي. إدخالات الخطاف هي زوج `{command, timeout}` (timeout في **ثوان**) تحت خريطة `hooks:` مفتاحة بأحداث snake_case الخاصة بـ Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`؛ معالج يقوم بتحويل الأحداث عبر `HERMES_EVENT_MAP` وأسماء الأدوات عبر `HERMES_TOOL_MAP` لذا السياسات المدمجة تطلق بدون تغيير. التكوين يتم تحريره من خلال جولة YAML `Document` حفاظ على التعليقات لذا إعدادات المشغل الأخرى تبقى، والتثبيت يعيين `hooks_auto_accept: true` لذا البوابة بدون رأس (بدون TTY) تشغيل الخطافات بدون موجه موافقة. evaluator ينبثق عقد `{"decision":"block","reason"}` stdout الخاص بـ Hermes (Hermes يتجاهل رموز الخروج). **القيود:** Hermes لا يوجد لديه حدث نهاية الدوران `Stop`، لذا المدمجات `require-*-before-stop` لا تطلق أبداً لها (غير قابلة للتطبيق، لا كسر)؛ `instruct` ينحط للسماح-مع-ملاحظة-مسجلة (لا قناة سياق إضافي)؛ وإخفاء الأسرار في الإخراج (`sanitize-*`) لا يمكنه كتابة إخراج الأداة فوق عقد الخطاف القذيفة. Hermes أيضاً مصدر تدقيق **غير محترق** — لوحة المعلومات تقرأ جلسات بوابة الخاص بها مباشرة من `~/.hermes/state.db`. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**نطاق المستخدم فقط** — OpenClaw لا يوجد لديه تكوين مشروع/محلي). مثل Hermes، OpenClaw هي بوابة multi-channel **ذاتية البناء، لذا يعترض تثبيت واحد استدعاءات الأداة من كل قناة وخوادم subagents داخليها. الإنفاذ يجري عبر **خطافات ملحقات في العملية** الخاصة بـ OpenClaw (خطافاتها المستندة إلى الملفات الداخلية هي ملاحظة فقط ولا يمكنها الحجب)، لذا — مثل OpenCode/Pi — failproofai تشحن حزمة `openclaw-plugin/` ثابتة تطلق بشكل غير متزامن الثنائي failproofai وتترجم الحكم. التثبيت يسجل مجلد الملحق المشحون في مصفوفة `plugins.load.paths[]` الخاصة بـ `openclaw.json` ويفعله تحت `plugins.entries.failproofai` (مع `hooks.allowConversationAccess: true`، مطلوب للخطافات الحوار الخام). evaluator ينبثق حكم مسطح `{permission, reason}` ويقوم shim بتعيينه إلى شكل إرجاع أصلي لكل خطاف: `before_tool_call → {block:true, blockReason}` (**PreToolUse**)، `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**)، و `before_agent_finalize → {action:"revise", reason}` (**Stop** — بوابة turn-end حقيقية، لذا مدمجات `require-*-before-stop` **تفرض** على OpenClaw، بخلاف Hermes). الأحداث وأسماء الأدوات canonicalize ثنائي-جانب عبر `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`، `read→Read`، …) لذا السياسات المدمجة تطلق بدون تغيير؛ shim يفشل مفتوح على أي spawn/parse/timeout خطأ. OpenClaw أيضاً مصدر تدقيق **غير محترق** — لوحة المعلومات تقرأ جلسات JSONL الخاصة بها في `~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (مستخدم)، `/.factory/hooks.json` (مشروع) — Factory لا يوجد لديه نطاق محلي. droid يشحن نظام خطاف أمر خارجي Claude-style، لكن مع نكتتين تحقق مباشر ضد droid v0.171.0: (1) أسماء الأحداث تعيش في **المستوى الأعلى** من `hooks.json` — لا يوجد **لا `"hooks"` غلاف** (droid يرفض واحد)؛ أحداث الأدوات (`PreToolUse`/`PostToolUse`) تحمل `"matcher": "*"`، الأحداث غير الأداة تحذفها. (2) يتم دفع الرفع برمز خروج الخطاف **2 + stderr**، وليس قرار JSON — فرع `factory` المُقيِّم يُرجع خروج 2 لأحداث أداة/موجه و `{decision:"block", reason}` فقط على حدث turn-end `Stop` (قناة إعادة القوة الوحيدة الخاصة بـ droid). الأحداث بالفعل PascalCase (لا خريطة أحداث) والحمولة هي snake_case Claude؛ فقط أسماء الأدوات مُعادة عبر `FACTORY_TOOL_MAP` (`Execute→Bash`، `Create→Write`، `FetchUrl→WebFetch`، …). Factory أيضاً مصدر تدقيق **غير محترق** — لوحة المعلومات تقرأ جلسات JSONL على القرص في `~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (مستخدم)، `/.devin/config.json` (مشروع) — Devin لا يوجد لديه نطاق محلي. Devin هو **مستنسخ Claude نقي** تحقق مباشر ضد devin v3000.1.27: يستخدم مخطط Claude `"hooks"`-wrapper معياري (الكتابات محفوظة بحيث مفاتيح ملف الإعدادات الأخرى — `org_id`، `theme_mode`، … — تبقى)، أسماء أحداث بالفعل PascalCase (لا خريطة أحداث، لا فرع معالج)، و payload stdin Claude snake_case (لا تطبيع). فرع `devin` المُقيِّم يرفع مع JSON `{"decision":"block","reason"}` على stdout في خروج 0 لـ **كل** حدث (تحقق — أسقط الكتلة على `--permission-mode dangerous`)؛ على حدث turn-end `Stop` السبب يحمل وصياغة MANDATORY-ACTION إعادة القوة لذا مدمجات `require-*-before-stop` تفرض. فقط أسماء الأدوات مُعادة عبر `DEVIN_TOOL_MAP` (`exec→Bash`؛ `tool_input.command` بالفعل canonical). Devin أيضاً مصدر تدقيق **غير محترق** — لوحة المعلومات تقرأ جلسات SQLite في `~/.local/share/devin/cli/sessions.db` (كل صف `sessions` يحمل `working_directory` حقيقي، لذا جلسات المجموعة حسب مشروع cwd مثل Claude). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (مستخدم)، `/.agents/hooks.json` (مشروع) — Antigravity لا يوجد لديه نطاق محلي. بخلاف Factory/Devin، Antigravity لديها عقدها **الخاص بها** (ليس مستنسخ Claude)، تحقق مباشر ضد agy v1.1.2. `hooks.json` يستخدم مخطط **named-hook**: المفتاح ذو المستوى الأعلى هو حمل *اسم* (`"failproofai"`) قيمته حدث→ خريطة معالجات — أحداث الأدوات (`PreToolUse`/`PostToolUse`) تلف معالجات في `{matcher:"*", hooks:[…]}`، بينما `PreInvocation`/`Stop` هي **مسطحة** مصفوفات معالج (الخطافات المسماة الأخرى محفوظة). payload stdin هو **camelCase protojson** (`toolCall:{name,args}`، `conversationId`، `workspacePaths`، `transcriptPath`) — failproofai يطبعه إلى snake_case قبل تشغيل السياسات، ويعيد أسماء PascalCase للأداة `run_command` (`CommandLine`/`Cwd`) عبر `ANTIGRAVITY_TOOL_INPUT_MAP`. فرع `antigravity` المُقيِّم يستخدم أشكال استجابة Antigravity **الخاصة بها**: `{decision:"deny", reason}` يحجب أداة/موجه (خروج 0)، `{decision:"continue", reason}` على turn-end `Stop` يعيد دخول الحلقة (لذا مدمجات `require-*-before-stop` تفرض)، و `{injectSteps:[{ephemeralMessage}]}` يحقن تعليمات على `PreInvocation` (→ `UserPromptSubmit`). أسماء الأدوات canonicalize عبر `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`، `view_file→Read`، …). Antigravity أيضاً مصدر تدقيق **غير محترق** — لوحة المعلومات تقرأ نصوص JSONL عادية في `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (مؤشر محادثة في `conversation_summaries.db`). - - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (مستخدم)، `/.agents/plugins/failproofai/hooks/hooks.json` (مشروع) — Goose لا يوجد لديه نطاق محلي. الإنفاذ يستخدم نظام **خطافات** Goose، المواصفات **Open Plugins** عبر العامل: المثبِّت يترك فقط مجلد `failproofai` والمكتشفات Goose تلقائياً عند بدء التشغيل (تسجيل ذاتي في `~/.config/goose/config.yaml`). `hooks.json` يستخدم مخطط Open Plugins **مع** غلاف `"hooks"` ذو المستوى الأعلى، والمُطابق **يُحذف** على كل حدث — regex مسطح `"*"` غير صحيح يطابق لا شيء (تحقق مباشر ضد goose v1.43.0). أسماء الأحداث بالفعل PascalCase (لا خريطة أحداث)؛ payload stdin يستخدم `event`/`working_dir`، التي معالج يطبعها إلى `hook_event_name`/`cwd`. فرع `goose` المُقيِّم يرفع مع JSON `{"decision":"block","reason"}` على stdout في خروج 0، مشرف على حدث **`PreToolUse`** فقط (شحن في goose ≥ v1.37.0) — الذي يطلق للأداة shell **وداخل subagents مفوضة**، لذا يكون نقطة الرفع الوحيدة الكافية؛ أي خطأ خطاف آخر يفشل **مفتوح**. Goose لا يوجد لديه حدث **`Stop`**، لذا مدمجات `require-*-before-stop` لا تطبق (مثل Hermes). أسماء الأدوات canonicalize عبر `GOOSE_TOOL_MAP` (`shell→Bash`، `write→Write`، `todo__todo_write→TodoWrite`، …) ومفاتيح المسار عبر `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose أيضاً مصدر تدقيق **غير محترق** — لوحة المعلومات تقرأ جلسات SQLite في `~/.local/share/goose/sessions/sessions.db` (كل صف `sessions` يحمل `working_dir` حقيقي، لذا جلسات المجموعة حسب مشروع cwd مثل Devin؛ `--no-session` جلسات خدش يتم تصفيتها). -- **`policies-config.json`** — تخبر failproofai بالسياسات المراد تقييمها وبأي معاملات (مشتركة عبر جميع agent CLIs) - -مرر `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` لاستهداف عامل معين (مفصول بمسافة أو مكرر لأي مجموعة فرعية): + - **OpenAI Codex**: `~/.codex/hooks.json` (مستخدم)، `/.codex/hooks.json` (مشروع) — Codex ليس لديه نطاق `local` + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (مستخدم)، `/.github/hooks/failproofai.json` (مشروع) — Copilot ليس لديه نطاق `local`. إدخالات الربط تستخدم حقول الأوامر `bash`/`powershell` ذات المفاتيح بواسطة النظام الأساسي في Copilot مع `timeoutSec`؛ الملف يحمل علامة `version: 1` على المستوى الأعلى. دعم Copilot CLI هو **beta** بينما نتحقق من مخطط سجل `events.jsonl` (الذي لا توضحه المستندات العامة) مقابل المزيد من الجلسات الحقيقية. **وضع عامل VS Code Copilot Chat (معاينة)** يقرأ تكوينات الربط من `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, و `~/.claude/settings.json` (يحكمه إعداد `chat.hookFilesLocations`) باستخدام نفس عقد Claude المشكلة `{hookSpecificOutput:{permissionDecision:"deny",…}}` — المسارات الدقيقة التي تكتبها بالفعل تكامل `copilot` وتكامل `claude` (`~/.claude/settings.json`)، لذا فإن `failproofai policies --install --cli copilot` (أو `--cli claude`) **بالفعل ينفذ في وضع عامل VS Code** دون الحاجة إلى تكامل `vscode` منفصل (يتم التحقق مباشرة من سجلات اكتشاف VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (مستخدم)، `/.cursor/hooks.json` (مشروع) — Cursor ليس لديه نطاق `local`. إدخالات الربط تستخدم النموذج المشكلة بواسطة Claude `{type, command, timeout}` (لا توجد قسمة `bash`/`powershell`)، لكن مخزنة تحت مفاتيح الأحداث CamelCase (`preToolUse`, `beforeSubmitPrompt`, …) في مصفوفة مسطحة لكل [مخطط ربط](https://cursor.com/docs/hooks) Cursor. الملف يحمل علامة `version: 1` على المستوى الأعلى. يقوم المعالج بتطبيع camelCase → PascalCase عبر `CURSOR_EVENT_MAP` بحيث تطلق السياسات المدمجة الموجودة دون تغيير. دعم Cursor Agent هو **beta** بينما نتحقق من نسخ Cursor على القرص (غير محدد في المستندات العامة) مقابل المزيد من التثبيتات الحقيقية. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (مستخدم)، `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (مشروع) — OpenCode ليس لديه نطاق `local`. بخلاف CLI الخمسة الأخرى، OpenCode **ليس لديه نظام ربط أمر خارجي**: يحمل مكونات إضافية JS/TS في العملية صراحة المسجلة عبر مصفوفة `plugin: []` في `opencode.json` (الاكتشاف التلقائي من `.opencode/plugins/` **ليس** كيف تحميل المكونات الإضافية على opencode v1.14.33). التثبيت ينقل تحويل مكون إضافي صغير مولد يستدعي المكون الثنائي failproofai عبر العملية الفرعية ويترجم استجابة JSON المشكلة بواسطة Claude مرة أخرى إلى دلالات المكون الإضافي: `throw new Error()` لأحداث الأداة deny (تلغي استدعاء الأداة)، `client.session.prompt(...)` للإرشاد و `Stop` / `SubagentStop` deny (تقدم سبب الرفض كرسالة المستخدم التالية — القناة الوحيدة لإعادة المحاولة القسرية منذ `session.idle` تخطير فقط وإلقاء استثناء منها هو بدون عملية)، وبدون عملية للسماح. يقوم التحويل بتطبيع أسماء الأدوات (صغير → PascalCase عبر `OPENCODE_TOOL_MAP`) ومفاتيح args أداة الإدخال (camelCase → snake_case عبر `OPENCODE_TOOL_INPUT_MAP` لـ `Read` / `Write` / `Edit`، مثل `filePath` → `file_path`, `oldString` → `old_string`) قبل الإرسال إلى البرنامج الثنائي، بحيث تطلق المدمجات الفحص بالمسار مثل `block-read-outside-cwd`, `block-env-files`, و `block-secrets-write` دون تغيير على استدعاءات أداة OpenCode. الجلسات تعيش في SQLite DB OpenCode في `~/.local/share/opencode/opencode.db`؛ عارض الجلسة بلوحة المعلومات يقرأها عبر `opencode db --format json` و `opencode export `. دعم OpenCode هو **beta** بينما نتحقق من السلوك عبر الإصدارات ومقابل المزيد من الجلسات الحقيقية. انظر [مستندات مكونات OpenCode الإضافية](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (مستخدم)، `/.pi/settings.json` (مشروع) — Pi ليس لديه نطاق `local`. Pi يحمل حزم ملحق TypeScript عند بدء التشغيل؛ ملف الإعدادات هو مصفوفة نصوص مسطحة `{"packages": ["./relative/path", …]}`. failproofai يكتب إدخال مصفوفة حزم واحد يشير إلى مجلده المجموعة `pi-extension/`. الملحق داخلياً يشترك في أحداث Pi `tool_call` / `user_bash` / `input` / `session_start` ويشغل `failproofai --hook --cli pi`؛ معالج يقوم بتطبيع snake_case underscore_lower → PascalCase عبر `PI_EVENT_MAP` بحيث تطلق السياسات المدمجة الموجودة دون تغيير. معاملات إدخال الأداة أيضاً تطبيع عبر `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit تسليم `path` بدلاً من `file_path`؛ تعيين المفتاح المستوى الأعلى يدع `block-env-files` و `block-secrets-write` إطلاق — `block-read-outside-cwd` بالفعل كان لديه `path` fallback). دعم Pi هو **beta** بينما تثبيت Pi's extension API وتخطيط سجل الجلسة على القرص. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**نطاق المستخدم فقط** — Hermes ليس لديه إعدادات مشروع/محلي). Hermes هو بوابة Slack/Telegram **gateway**، لذا تثبيت واحد يعترض استدعاءات الأداة من كل منصة (Slack/Telegram/cli/cron) **و** وكلاء فرعيين داخليين. إدخالات الربط هي زوج `{command, timeout}` (timeout في **ثانية**) تحت خريطة `hooks:` مفتاحة بواسطة أحداث snake_case Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); معالج يقوم بتطبيع الأحداث عبر `HERMES_EVENT_MAP` وأسماء الأدوات عبر `HERMES_TOOL_MAP` بحيث تطلق السياسات المدمجة دون تغيير. يتم تحرير الإعدادات عبر `Document` YAML حفظ التعليقات جولة ذهاباً وإياباً حيث أن إعدادات المشغل الأخرى تنجو، والتثبيت يحدد `hooks_auto_accept: true` بحيث تقوم البوابة بدون رأس (لا TTY) بتشغيل الخطافات دون موجه موافقة. المقيم ينبعث عقد `{"decision":"block","reason"}` stdout Hermes (Hermes تتجاهل أكواد الخروج). **التحديدات:** Hermes ليس لديها حدث نهاية الدور `Stop`، لذا فإن المدمجات `require-*-before-stop` لا تطلق أبداً لها (غير قابل للتطبيق، وليس محطماً); `instruct` تتراجع للسماح مع الملاحظة المسجلة (لا توجد قناة سياق إضافية); وإعادة كتابة سرية الإخراج (`sanitize-*`) لا يمكن إعادة كتابة إخراج الأداة على عقد shell-hook. Hermes هو **أيضاً** **audit** مصدر بدون اتصال — لوحة المعلومات تقرأ جلسات بوابتها مباشرة من `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**نطاق المستخدم فقط** — OpenClaw ليس لديه إعدادات مشروع/محلي). مثل Hermes، OpenClaw هو بوابة متعددة القنوات ذاتية الاستضافة **gateway**، لذا تثبيت واحد يعترض استدعاءات الأداة من كل قناة ووكلائها الفرعيين الداخليين. ينفذ الإنفاذ عبر **في العملية plugin hooks** OpenClaw (خطافاتها القائمة على الملفات الداخلية ملاحظة فقط ولا يمكنها أن تحظر)، لذا — مثل OpenCode/Pi — failproofai شحنات مكون إضافي ثابت `openclaw-plugin/` حزمة ذلك async-spawns البرنامج الثنائي failproofai ويترجم الحكم. تسجيل التثبيت مجلد المكون الإضافي المرسل في مصفوفة `plugins.load.paths[]` في `openclaw.json` وتمكينه تحت `plugins.entries.failproofai` (مع `hooks.allowConversationAccess: true`، مطلوب للخطافات المحادثة الخام). المقيم ينبعث حكم `{permission, reason}` مسطح والتحويل يعيينه إلى شكل العودة الأصلي لكل خطاف: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), و `before_agent_finalize → {action:"revise", reason}` (**Stop** — بوابة نهاية دور حقيقية، لذا **enforce** المدمجات `require-*-before-stop` على OpenClaw، بخلاف Hermes). الأحداث وأسماء الأدوات تطبيع ثنائي الجانب عبر `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) بحيث تطلق السياسات المدمجة دون تغيير; التحويل يفشل بشكل مفتوح على أي spawn/parse/timeout خطأ. OpenClaw هو **أيضاً** **audit** مصدر بدون اتصال — لوحة المعلومات تقرأ جلسات JSONL الخاصة بها في `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (مستخدم)، `/.factory/hooks.json` (مشروع) — Factory ليس لديه نطاق `local`. droid شحنات نظام ربط أوامر خارجي بنمط Claude، لكن مع تحذيرات اثنين التحقق من الحي مقابل droid v0.171.0: (1) أسماء الأحداث تعيش في **المستوى الأعلى** من `hooks.json` — هناك **لا `"hooks"` wrapper** (droid يرفضها); أحداث الأداة (`PreToolUse`/`PostToolUse`) تحمل `"matcher": "*"`, أحداث غير الأداة تحذفها. (2) Deny يقوده ربط **كود الخروج 2 + stderr**، وليس قرار JSON — فرع المقيم `factory` يرجع الخروج 2 لأحداث أداة/موجه و `{decision:"block", reason}` فقط على حدث نهاية الدور `Stop` (قناة إعادة المحاولة القسرية الوحيدة droid). الأحداث بالفعل PascalCase (لا خريطة حدث) والحمل هو Claude snake_case; فقط أسماء الأدوات تطبيع عبر `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory هو **أيضاً** **audit** مصدر بدون اتصال — لوحة المعلومات تقرأ جلسات JSONL على القرص في `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (مستخدم)، `/.devin/config.json` (مشروع) — Devin ليس لديه نطاق `local`. Devin هو **pure Claude-clone** التحقق من الحي مقابل devin v3000.1.27: يستخدم مخطط `"hooks"`-wrapper Claude القياسي (الكتابات محفوظة الدمج حتى مفاتيح الملف الإعدادات الأخرى — `org_id`, `theme_mode`, … — البقاء)، أسماء الأحداث بالفعل PascalCase (لا خريطة حدث، لا فرع معالج)، وحمل claude snake_case stdin (لا تطبيع). يرفع فرع المقيم `devin` مع `{"decision":"block","reason"}` JSON على stdout في الخروج 0 لـ **every** حدث (التحقق — كتلة تجاوزت `--permission-mode dangerous`); على حدث نهاية الدور `Stop` السبب يحمل وضع إعادة المحاولة القسرية MANDATORY-ACTION حتى enforce المدمجات `require-*-before-stop`. فقط أسماء الأدوات تطبيع عبر `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` بالفعل canonical). Devin هو **أيضاً** **audit** مصدر بدون اتصال — لوحة المعلومات تقرأ جلسات SQLite في `~/.local/share/devin/cli/sessions.db` (كل صف `sessions` يحمل `working_directory` حقيقي، بحيث مجموعات الجلسات حسب مشروع cwd مثل Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (مستخدم)، `/.agents/hooks.json` (مشروع) — Antigravity ليس لديه نطاق `local`. بخلاف Factory/Devin، Antigravity لديه **خاصة بها** عقد (ليس clone Claude)، التحقق من الحي مقابل agy v1.1.2. `hooks.json` يستخدم **named-hook** مخطط: المفتاح المستوى الأعلى هو اسم ربط *(`"failproofai"`) الذي قيمته هي أحداث→معالجات خريطة — أحداث الأداة (`PreToolUse`/`PostToolUse`) تغليف معالجات في `{matcher:"*", hooks:[…]}`, بينما `PreInvocation`/`Stop` **flat** مصفوفات المعالج (المسميات الأخرى خطافات محفوظة). حمل stdin هو **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai تطبيع إلى snake_case قبل تشغيل السياسات، ويعيين `run_command`'s PascalCase args (`CommandLine`/`Cwd`) عبر `ANTIGRAVITY_TOOL_INPUT_MAP`. فرع المقيم `antigravity` يستخدم **own** أشكال استجابة Antigravity: `{decision:"deny", reason}` يحظر أداة/موجه (الخروج 0), `{decision:"continue", reason}` على حدث نهاية الدور `Stop` إعادة الدخول الحلقة (حتى enforce المدمجات `require-*-before-stop`)، و `{injectSteps:[{ephemeralMessage}]}` ويحقن تعليمات على `PreInvocation` (→ `UserPromptSubmit`). أسماء الأدوات تطبيع عبر `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity هو **أيضاً** **audit** مصدر بدون اتصال — لوحة المعلومات تقرأ نصوصها plain-JSONL في `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (فهرس المحادثة في `conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (مستخدم)، `/.agents/plugins/failproofai/hooks/hooks.json` (مشروع) — Goose ليس لديه نطاق `local`. الإنفاذ يستخدم نظام **hooks** Goose، cross-agent **Open Plugins** مواصفة: المثبت ينقل فقط مجلد المكون الإضافي `failproofai` و Goose يكتشفها تلقائياً عند بدء التشغيل (تسجيل ذاتي في `~/.config/goose/config.yaml`). `hooks.json` يستخدم Open Plugins مخطط **مع** wrapper المستوى الأعلى `"hooks"`، والمطابق هو **omitted** على كل حدث — مجرد `"*"` هو regex غير صالح لا يطابق أي شيء (التحقق من الحي مقابل goose v1.43.0). أسماء الأحداث بالفعل PascalCase (لا خريطة حدث); حمل stdin يستخدم `event`/`working_dir`, التي معالج تطبيع إلى `hook_event_name`/`cwd`. فرع المقيم `goose` يرفع مع `{"decision":"block","reason"}` JSON على stdout في الخروج 0, بقي على **`PreToolUse`** حدث فقط (شحنات في goose ≥ v1.37.0) — الذي يطلق لأداة shell **و** داخل وكلاء فرعيين مفوضين، لذا فهو نقطة deny واحدة كافية; أي خطأ ربط آخر يفشل **مفتوح**. Goose ليس لديها **`Stop` حدث**, لذا المدمجات `require-*-before-stop` لا تنطبق (كما مع Hermes). أسماء الأدوات تطبيع عبر `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) ومفاتيح المسار عبر `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose هو **أيضاً** **audit** مصدر بدون اتصال — لوحة المعلومات تقرأ جلسات SQLite في `~/.local/share/goose/sessions/sessions.db` (كل صف `sessions` يحمل `working_dir` حقيقي، بحيث مجموعات الجلسات حسب مشروع cwd مثل Devin; `--no-session` جلسات خدش يتم تصفيتها). +- **`policies-config.json`** — يخبر failproofai أي السياسات التي يجب تقييمها وبأي معاملات (مشتركة عبر جميع CLIs العامل) + +تمرير `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` لاستهداف عامل معين (مفصولة بمسافات أو يكررها لأي مجموعة فرعية): ```bash failproofai policies --install --cli codex --scope project @@ -233,20 +239,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -عندما يتم حذف `--cli`، يكتشف failproofai أي agent CLIs مثبتة (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +عندما يتم حذف `--cli`، يكتشف `failproofai` أي CLIs عامل مثبتة (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **تم اكتشاف CLI واحد** — تحديد تلقائي لهذا CLI بدون موجه. -- **تم اكتشاف عدة CLIs** في محطة طرفية تفاعلية — يظهر موجه تحديد مفرد واحد محسوب إلى قسم `Detected (N)` (مع صف إجمالي `Install for all N detected` + كل CLI مكتشف على حدة) وقسم `Not installed (M) · install hooks ahead of time` يسرد كل CLI مدعوم غير مكتشف كخيار تثبيت forward (↑↓ للتحرك، Enter للتحديد، ^C للخروج). تدفق الإزالة يظهر فقط قسم Detected. -- **تم اكتشاف عدة CLIs** في تشغيل non-interactive (CI، بدون TTY) — تثبيت لجميع CLIs المكتشفة بدون موجه. -- **لم يتم اكتشاف أي منها** — fallback إلى `claude`، مع تحذير بأنه لم يتم العثور على ثنائي عامل في PATH؛ أمر الخطاف لا يزال مكتوب لذا يتم تنشيطه بمجرد تثبيت واحد. +- **CLI واحد مكتشف** — يختار هذا CLI تلقائياً دون السؤال. +- **عدة CLIs المكتشفة** في محطة تفاعلية — يعرض موجه تحديد سهم واحد مجموعة في قسم `Detected (N)` (مع صف إجمالي `Install for all N detected` + كل CLI المكتشفة بشكل فردي) وقسم `Not installed (M) · install hooks ahead of time` المدرج كل CLI مدعوم غير مكتشف كخيار تثبيت تقديم (↑↓ للتحرك، Enter للتحديد، ^C للخروج). تدفق الإلغاء يعرض قسم Detected فقط. +- **عدة CLIs المكتشفة** في مسار غير تفاعلي (CI، لا TTY) — يثبت لجميع CLIs المكتشفة دون السؤال. +- **لا أحد مكتشف** — ينسحب إلى `claude`, مع تحذير من أن لا ملف عامل ثنائي وجد في PATH; أمر الربط لا تزال مكتوبة حيث يتم تفعيلها بمجرد تثبيت واحد. -يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ التغييرات تدخل حيز التنفيذ فوراً على حدث الخطاف التالي بدون الحاجة لإعادة تشغيل. +يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ التغييرات تبدأ تسري مباشرة في حدث الربط التالي دون الحاجة إلى إعادة تشغيل. + +## الترقيات تحتفظ بإعداداتك + +قد ينظم إصدار جديد من failproofai `~/.failproofai/` بشكل مختلف. عندما يفعل ذلك، فإن الأمر الأول بعد الترقية ينقل المجلد، و **تُحمل إعداداتك، وليس إعادة تعيينها**: + +| محفوظ | أعيد البناء | +|---|---| +| اختيار السياسة والمعاملات الخاصة بك (`policies-config.json`) | ذاكرة التدقيق | +| إعداداتك، بما فيها `daemon.configured` ومسارات الالتقاط الإضافية (`config.json`) | نشرات السياسات المدارة بالسحابة — إعادة جلب وتحقق الهضم على الاستطلاع التالي | +| التسجيل السحابي الخاص بك (`credentials.json`) | حالة خدش البرنامج الثنائي | +| ملفات السياسات الخاصة بك في `policies/`, والمساعدين الذين يستوردونها | | +| سجل القرار الذي تقرأه لوحة المعلومات، والأحداث التي لم يتم تسليمها بعد | | + +يتم الحفاظ على المفاتيح المكتوبة بواسطة failproofai **أحدث** أيضاً، بدلاً من إسقاطها بواسطة قارئ أقدم — لذا الانتقال بين الإصدارات لا يسقط بصمت الإعدادات في أي اتجاه. + +أنت **لا** تحتاج إلى إعادة تشغيل الإعداد بعد ذلك: جهاز مهاجر ينفذ تماماً كما كان من قبل، الذي يجعل الترقية آمنة على الآلات مع لا أحد يجلس عليها. كل هجرة مسجلة في `~/.failproofai/migrations/applied.json`, والملفات التي لا تحتمل البديل تنسخ إلى `~/.failproofai/migrations/backup-layout/` قبل تشغيل أي شيء. + +انظر [`failproofai update`](/ar/cli/update) للترقية في سطر واحد, و [`failproofai migrate`](/ar/cli/migrate) — بما فيها `--dry-run` — للتفاصيل. --- -## مثال: إعدادات على مستوى المشروع مع إعدادات افتراضية الفريق +## مثال: تكوين مستوى المشروع مع افتراضيات الفريق -التزم `.failproofai/policies-config.json` إلى مستودعك: +التزم `.failproofai/policies-config.json` في مستودع الكود الخاص بك: ```json { @@ -265,4 +289,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her } ``` -يمكن لكل مطور بعد ذلك إنشاء `.failproofai/policies-config.local.json` (مُستثناة من git) لتجاوزات شخصية بدون التأثير على زملائهم. \ No newline at end of file +يمكن لكل مطور إنشاء `.failproofai/policies-config.local.json` (مستثنى من التتبع) لعمليات التجاوز الشخصية دون التأثير على زملاء الفريق. \ No newline at end of file diff --git a/docs/ar/custom-policies.mdx b/docs/ar/custom-policies.mdx index 73b1dd7d..08d3ec4f 100644 --- a/docs/ar/custom-policies.mdx +++ b/docs/ar/custom-policies.mdx @@ -1,11 +1,11 @@ --- --- title: السياسات المخصصة -description: "اكتب قواعدك الخاصة في JavaScript - فرض الاتفاقيات، منع الانحراف، الكشف عن الأخطاء، التكامل مع الأنظمة الخارجية" +description: "اكتب قواعدك الخاصة بلغة JavaScript - فرض الاتفاقيات، منع الانجراف، كشف الأعطال، التكامل مع الأنظمة الخارجية" icon: code --- -تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع، منع الانحراف، حماية العمليات المدمرة، الكشف عن الوكلاء العالقة، أو التكامل مع Slack وسير العمل الموافقة والمزيد. تستخدم نفس نظام أحداث الخطاف وقرارات `allow` و `deny` و `instruct` كما هو الحال في السياسات المدمجة. +تتيح السياسات المخصصة لك كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع، منع الانجراف، حظر العمليات المدمرة، كشف الوكلاء المتعثرين، أو التكامل مع Slack وسير العمل الموافقة وغيره. وهي تستخدم نفس نظام أحداث الخطافات وقرارات `allow` و `deny` و `instruct` مثل السياسات المدمجة. --- @@ -30,7 +30,7 @@ customPolicies.add({ }); ``` -ثبتها: +قم بتثبيتها: ```bash failproofai policies --install --custom ./my-policies.js @@ -40,61 +40,61 @@ failproofai policies --install --custom ./my-policies.js ## طريقتان لتحميل السياسات المخصصة -### الخيار 1: القائم على الاتفاقية (موصى به) +### الخيار 1: القائمة على الاتفاقية (موصى به) -انقل ملفات `*policies.{js,mjs,ts}` إلى `.failproofai/policies/` وسيتم تحميلها تلقائياً - لا توجد علامات أو تغييرات في الإعدادات مطلوبة. يعمل هذا مثل git hooks: انقل ملفاً، وسيعمل ببساطة. +أفلت ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وسيتم تحميلها تلقائياً - لا حاجة إلى أعلام أو تغييرات في الإعدادات. يعمل هذا مثل خطافات git: أفلت ملف، وسيعمل فقط. ``` -# مستوى المشروع - مرتكز في git، مشترك مع الفريق +# مستوى المشروع - تم التزامه بـ git، مشترك مع الفريق .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# المستوى الشخصي - شخصي، ينطبق على جميع المشاريع +# مستوى المستخدم - شخصي، ينطبق على جميع المشاريع ~/.failproofai/policies/my-policies.mjs ``` -**كيفية العمل:** -- يتم البحث في كلا المجلدين (الاتحاد - وليس الأول يفوز) -- يتم تحميل الملفات أبجدياً داخل كل دليل. بادئة بـ `01-` و `02-` للتحكم في الترتيب +**كيف يعمل:** +- يتم مسح كلا المجلدات (مشروع والمستخدم) (اتحاد - وليس الفوز الأول في الكائن) +- يتم تحميل الملفات أبجدياً داخل كل مجلد. البادئة بـ `01-`، `02-` للتحكم في الترتيب - يتم تحميل الملفات المطابقة فقط لـ `*policies.{js,mjs,ts}`؛ يتم تجاهل الملفات الأخرى -- يتم تحميل كل ملف بشكل مستقل (فتح فاشل لكل ملف) -- يعمل جنباً إلى جنب مع سياسات `--custom` الصريحة والمدمجة +- يتم تحميل كل ملف بشكل مستقل (فشل مفتوح لكل ملف) +- يعمل جنباً إلى جنب مع السياسات المخصصة الصريحة `--custom` والسياسات المدمجة -سياسات الاتفاقية هي أسهل طريقة لبناء معيار الجودة لمنظمتك. احرص على `.failproofai/policies/` في git وكل عضو فريق سيحصل على نفس القواعد تلقائياً - لا توجد إعدادات منفصلة لكل مطور مطلوبة. عندما يكتشف فريقك أنماط فشل جديدة، أضف سياسة وادفع. بمرور الوقت، تصبح هذه معيار جودة حي يتحسن مع كل مساهمة. +سياسات الاتفاقية هي أسهل طريقة لبناء معايير جودة لمؤسستك. التزم `.failproofai/policies/` بـ git وكل عضو في الفريق يحصل على نفس القواعد تلقائياً - لا حاجة إلى إعداد لكل مطور. عندما يكتشف فريقك أوضاع فشل جديدة، أضف سياسة وادفعها. بمرور الوقت، تصبح هذه معيار جودة حي يتحسن مع كل مساهمة. ### الخيار 2: مسار الملف الصريح ```bash -# التثبيت مع ملف سياسات مخصصة +# تثبيت مع ملف سياسات مخصص failproofai policies --install --custom ./my-policies.js # استبدال مسارات السياسات المخصصة failproofai policies --install --custom ./new-policies.js -# تكوين ملفات متعددة صريحة (محملة بترتيب العلم) +# تكوين ملفات صريحة متعددة (تحميلها بترتيب العلم) failproofai policies --install --custom ./security.js --custom ./workflow.js # إزالة جميع مسارات السياسات المخصصة الصريحة من الإعدادات failproofai policies --uninstall --custom ``` -يتم تخزين المسارات المطلقة المحللة في `policies-config.json` كـ `customPoliciesPaths`. كرر `--custom` لتكوين ملفات متعددة. تستمر الإعدادات الموجودة في استخدام حقل `customPoliciesPath` القديم في العمل. يتم تحميل الملفات بشكل طازج في كل حدث خطاف - لا يوجد تخزين مؤقت بين الأحداث. +يتم تخزين المسارات المطلقة المحللة في `policies-config.json` كـ `customPoliciesPaths`. كرر `--custom` لتكوين ملفات متعددة. الإعدادات الموجودة التي تستخدم حقل `customPoliciesPath` الموروث تستمر في العمل. يتم تحميل الملفات بشكل جديد في كل حدث خطاف - لا يوجد تخزين مؤقت بين الأحداث. -تظهر كل سياسة مسجلة مع تبديلها الخاص في لوحة التحكم. التبديل للسياسة يسجل معرّفها المؤهل بالمصدر في `disabledCustomPolicies`؛ يستمر الملف وسياساته الأخرى في التحميل، بينما يتم استبعاد السياسة المعطلة قبل مطابقة الأحداث. للسياسات المكررة عبر الملفات تبديلات مستقلة. +كل سياسة مسجلة تظهر مع مفتاح تبديل خاص بها في لوحة التحكم. يسجل إيقاف السياسة معرفها المؤهل بالمصدر في `disabledCustomPolicies`؛ يستمر تحميل الملف وسياساته الأخرى، بينما يتم استبعاد السياسة المعطلة قبل مطابقة الحدث. أسماء السياسات المكررة عبر الملفات لها تبديلات مستقلة. -### استخدام الاثنين معاً +### استخدام كليهما معاً -يمكن أن توجد سياسات الاتفاقية وملفات `--custom` الصريحة معاً. ترتيب التحميل: +يمكن لسياسات الاتفاقية والملفات الصريحة `--custom` أن تتعايش. ترتيب التحميل: 1. ملفات `customPoliciesPaths` الصريحة (بالترتيب المكون) -2. ملفات اتفاقية المشروع (`{cwd}/.failproofai/policies/`، أبجدياً) -3. ملفات الاتفاقية للمستخدم (`~/.failproofai/policies/`، أبجدياً) +2. ملفات اتفاقية المشروع (`{cwd}/.failproofai/policies/`, أبجدية) +3. ملفات اتفاقية المستخدم (`~/.failproofai/policies/`, أبجدية) --- -## واجهة برمجية التطبيقات +## الواجهة البرمجية ### الاستيراد @@ -104,45 +104,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -يسجل سياسة. استدعِها عدة مرات حسب الحاجة لعدة سياسات في نفس الملف. +تسجيل سياسة. استدعِ هذا عدة مرات حسب الحاجة للسياسات المتعددة في نفس الملف. ```ts customPolicies.add({ - name: string; // مطلوب - معرّف فريد + name: string; // مطلوب - معرف فريد description?: string; // معروض في مخرجات `failproofai policies` - match?: { events?: HookEventType[] }; // تصفية حسب نوع الحدث؛ حذف للمطابقة الجميع + match?: { events?: HookEventType[] }; // تصفية حسب نوع الحدث؛ احذف للمطابقة مع الكل fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` ### مساعدات القرار -| الدالة | التأثير | الاستخدام متى | +| الدالة | التأثير | الاستخدام عند | |----------|--------|----------| | `allow()` | السماح بالعملية بصمت | الإجراء آمن، لا توجد رسالة مطلوبة | -| `deny(message)` | منع العملية | الوكيل لا يجب أن يتخذ هذا الإجراء | +| `deny(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` وتسليمها معاً. -يمكنك إضافة إرشادات إضافية إلى أي رسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` - لا حاجة لتغيير الكود. يعمل هذا مع السياسات المخصصة (`custom/`)، واتفاقية المشروع (`.failproofai-project/`)، واتفاقية المستخدم (`.failproofai-user/`) أيضاً. انظر [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل. +يمكنك إلحاق توجيهات إضافية بأي رسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` - لا حاجة لتغيير الكود. يعمل هذا أيضاً مع السياسات المخصصة (`custom/`)، واتفاقية المشروع (`.failproofai-project/`)، واتفاقية المستخدم (`.failproofai-user/`). راجع [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل. ### رسائل السماح المعلوماتية -`allow(message)` يسمح بالعملية **و** يرسل رسالة إعلامية إلى Claude. يتم تسليم الرسالة كـ `additionalContext` في استجابة stdout لمعالج الخطاف - نفس الآلية المستخدمة بـ `instruct`، لكن من الناحية الدلالية مختلفة: إنه تحديث الحالة، وليس تحذير. +`allow(message)` يسمح بالعملية **و** يرسل رسالة معلوماتية مرة أخرى إلى Claude. يتم تسليم الرسالة كـ `additionalContext` في استجابة stdout لمعالج الخطاف - نفس الآلية المستخدمة بواسطة `instruct`، لكن دلالياً مختلفة: إنها تحديث حالة، وليس تحذير. -| الدالة | التأثير | الاستخدام متى | +| الدالة | التأثير | الاستخدام عند | |----------|--------|----------| | `allow(message)` | السماح وإرسال السياق إلى Claude | تأكيد نجاح الفحص، أو شرح سبب تخطي الفحص | حالات الاستخدام: - **تأكيدات الحالة:** `allow("All CI checks passed.")` - يخبر Claude أن كل شيء أخضر -- **شروحات الفتح الفاشل:** `allow("GitHub CLI not installed, skipping CI check.")` - يخبر Claude لماذا تم تخطي الفحص حتى يكون لديه السياق الكامل -- **تراكم الرسائل المتعددة:** إذا أرجعت عدة سياسات `allow(message)`، يتم ربط جميع الرسائل بفواصل أسطر وتسليمها معاً +- **شروحات الفشل المفتوح:** `allow("GitHub CLI not installed, skipping CI check.")` - يخبر Claude لماذا تم تخطي الفحص حتى يكون لديه السياق الكامل +- **الرسائل المتعددة تتراكم:** إذا أرجعت عدة سياسات `allow(message)`، يتم دمج جميع الرسائل بفواصل أسطر وتسليمها معاً ```js customPolicies.add({ @@ -165,27 +165,27 @@ customPolicies.add({ | الحقل | النوع | الوصف | |-------|------|-------------| -| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | الأداة التي يتم استدعاؤها (مثل `"Bash"`, `"Write"`, `"Read"`) | +| `eventType` | `string` | `"PreToolUse"`، `"PostToolUse"`، `"Notification"`، `"Stop"` | +| `toolName` | `string \| undefined` | الأداة التي يتم استدعاؤها (مثل `"Bash"`، `"Write"`، `"Read"`) | | `toolInput` | `Record \| undefined` | معاملات إدخال الأداة | -| `payload` | `Record` | حمل الحدث الأولي الكامل من Claude Code | +| `payload` | `Record` | حمولة الحدث الخام الكاملة من Claude Code | | `session` | `SessionMetadata \| undefined` | سياق الجلسة (انظر أدناه) | ### حقول `SessionMetadata` | الحقل | النوع | الوصف | |-------|------|-------------| -| `sessionId` | `string` | معرّف جلسة Claude Code | -| `cwd` | `string` | دليل العمل لجلسة Claude Code | -| `transcriptPath` | `string` | المسار إلى ملف نسخة JSONL للجلسة | +| `sessionId` | `string` | معرف جلسة Claude Code | +| `cwd` | `string` | مجلد العمل لجلسة Claude Code | +| `transcriptPath` | `string` | المسار إلى ملف النسخة JSONL للجلسة | ### أنواع الأحداث -| الحدث | متى يتم تشغيله | محتويات `toolInput` | +| الحدث | عند الحدوث | محتويات `toolInput` | |-------|--------------|----------------------| -| `PreToolUse` | قبل أن يقوم Claude بتشغيل أداة | إدخال الأداة (مثل `{ command: "..." }` للـ Bash) | -| `PostToolUse` | بعد انتهاء الأداة | إدخال الأداة + `tool_result` (الإخراج) | -| `Notification` | عندما يرسل Claude إخطاراً | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن ترجع الخطافات دائماً `allow()`، لا يمكنها حظر الإخطارات | +| `PreToolUse` | قبل تشغيل Claude لأداة | إدخال الأداة (مثل `{ command: "..." }` للـ Bash) | +| `PostToolUse` | بعد اكتمال الأداة | إدخال الأداة + `tool_result` (الإخراج) | +| `Notification` | عند إرسال Claude لإشعار | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن تُرجع الخطافات دائماً `allow()`، فلا يمكنها حظر الإشعارات | | `Stop` | عند انتهاء جلسة Claude | فارغ | --- @@ -196,18 +196,18 @@ customPolicies.add({ 1. السياسات المدمجة (بترتيب التعريف) 2. السياسات المخصصة الصريحة من `customPoliciesPath` (بترتيب `.add()`) -3. سياسات الاتفاقية من المشروع `.failproofai/policies/` (ملفات أبجدياً، ترتيب `.add()` داخل) -4. سياسات الاتفاقية من المستخدم `~/.failproofai/policies/` (ملفات أبجدياً، ترتيب `.add()` داخل) +3. سياسات الاتفاقية من المشروع `.failproofai/policies/` (الملفات أبجدية، ترتيب `.add()` داخل) +4. سياسات الاتفاقية من المستخدم `~/.failproofai/policies/` (الملفات أبجدية، ترتيب `.add()` داخل) -أول `deny` توقف جميع السياسات اللاحقة. يتم تجميع جميع رسائل `instruct` وتسليمها معاً. +أول `deny` يقطع جميع السياسات اللاحقة. يتم تجميع جميع رسائل `instruct` وتسليمها معاً. --- -## الاستيرادات المتعدية +## الاستيرادات العابرة -يمكن لملفات السياسات المخصصة استيراد الوحدات المحلية باستخدام المسارات النسبية: +يمكن لملفات السياسات المخصصة استيراد الوحدات المحلية باستخدام مسارات نسبية: ```js // my-policies.js @@ -224,43 +224,43 @@ customPolicies.add({ }); ``` -يتم حل جميع الاستيرادات النسبية التي يمكن الوصول إليها من ملف الإدخال. يتم تنفيذ هذا عن طريق إعادة كتابة استيرادات `from "failproofai"` إلى مسار التوزيع الفعلي وإنشاء ملفات `.mjs` مؤقتة لضمان التوافق ESM. +يتم حل جميع الاستيرادات النسبية التي يمكن الوصول إليها من ملف الدخول. يتم تنفيذ هذا بإعادة كتابة استيرادات `from "failproofai"` إلى مسار dist الفعلي وإنشاء ملفات `.mjs` مؤقتة لضمان توافق ESM. --- ## تصفية نوع الحدث -استخدم `match.events` لتحديد وقت تشغيل السياسة: +استخدم `match.events` لتحديد وقت حدوث السياسة: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // تشغيل فقط عند انتهاء الجلسة + // ينطلق فقط عند انتهاء الجلسة // ctx.session.transcriptPath يحتوي على سجل الجلسة الكامل return allow(); }, }); ``` -حذف `match` بالكامل للتشغيل على كل نوع حدث. +احذف `match` بالكامل لينطلق على كل نوع حدث. --- ## معالجة الأخطاء وأنماط الفشل -السياسات المخصصة **فتح فاشل**: الأخطاء لا تحظر السياسات المدمجة ولا تتسبب في تحطم معالج الخطاف. +السياسات المخصصة **فشل مفتوح**: الأخطاء لا تحظر السياسات المدمجة ولا تعطل معالج الخطاف. | الفشل | السلوك | |---------|----------| -| لم تعيّن `customPoliciesPath` | لا تعمل سياسات مخصصة صريحة؛ تستمر سياسات الاتفاقية والمدمجة بشكل طبيعي | -| الملف غير موجود | يتم تسجيل تحذير في `~/.failproofai/hook.log`؛ تستمر المدمجات | -| خطأ بناء جملة / استيراد (صريح) | يتم تسجيل الخطأ في `~/.failproofai/hook.log`؛ تم تخطي سياسات مخصصة صريحة | -| خطأ بناء جملة / استيراد (اتفاقية) | يتم تسجيل الخطأ؛ تم تخطي هذا الملف، لا تزال ملفات الاتفاقية الأخرى تحمل | -| `fn` يرمي في وقت التشغيل | يتم تسجيل الخطأ؛ يتم التعامل مع هذا الخطاف كـ `allow`؛ تستمر الخطافات الأخرى | -| `fn` يأخذ أكثر من 10 ثوان | يتم تسجيل انتهاء المهلة الزمنية؛ يتم التعامل معه كـ `allow` | -| دليل الاتفاقية مفقود | لا توجد سياسات اتفاقية؛ لا خطأ | +| لم يتم تعيين `customPoliciesPath` | لا تعمل السياسات المخصصة الصريحة؛ تستمر سياسات الاتفاقية والمدمجة بشكل طبيعي | +| الملف غير موجود | تحذير مسجل لـ `~/.failproofai/hook.log`؛ تستمر المدمجات | +| خطأ صيغة/استيراد (صريح) | خطأ مسجل لـ `~/.failproofai/hook.log`؛ يتم تخطي السياسات المخصصة الصريحة | +| خطأ صيغة/استيراد (اتفاقية) | خطأ مسجل؛ يتم تخطي هذا الملف، لا تزال ملفات الاتفاقية الأخرى تحمل | +| رمي `fn` في وقت التشغيل | خطأ مسجل؛ يتم معاملة هذا الخطاف كـ `allow`؛ تستمر الخطافات الأخرى | +| `fn` يستغرق أطول من 10 ثوانٍ | انتهاء مهلة زمنية مسجلة؛ معاملة كـ `allow` | +| مجلد الاتفاقية مفقود | لا تعمل سياسات الاتفاقية؛ لا خطأ | لتصحيح أخطاء السياسات المخصصة، راقب ملف السجل: @@ -278,7 +278,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", @@ -291,7 +291,7 @@ customPolicies.add({ }, }); -// ابق الوكيل على المسار: تحقق من الاختبارات قبل الالتزام +// إبقاء الوكيل على المسار: تحقق من الاختبارات قبل الالتزام customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -306,7 +306,7 @@ customPolicies.add({ }, }); -// منع التغييرات غير المخطط لها في المتطلبات أثناء التجميد +// منع تغييرات الاعتماديات غير المخططة أثناء التجميد customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -329,14 +329,14 @@ export { customPolicies }; ## أمثلة -يحتوي الدليل `examples/` على ملفات السياسات الجاهزة للتشغيل: +يحتوي مجلد `examples/` على ملفات سياسات جاهزة للتشغيل: -| الملف | المحتوى | +| الملف | المحتويات | |------|----------| -| `examples/policies-basic.js` | خمس سياسات بدء تغطي أنماط فشل الوكيل الشائعة | -| `examples/policies-advanced/index.js` | أنماط متقدمة: استيرادات متعدية، استدعاءات غير متزامنة، كشط الإخراج، خطافات نهاية الجلسة | -| `examples/convention-policies/security-policies.mjs` | سياسات الأمان القائمة على الاتفاقية (منع كتابة .env، منع إعادة كتابة سجل git) | -| `examples/convention-policies/workflow-policies.mjs` | سياسات سير العمل القائمة على الاتفاقية (تذكيرات الاختبار، ملفات الكتابة الحسابية) | +| `examples/policies-basic.js` | خمس سياسات مبتدئة تغطي أوضاع فشل الوكيل الشائعة | +| `examples/policies-advanced/index.js` | أنماط متقدمة: استيرادات عابرة، استدعاءات غير متزامنة، كشط الإخراج، خطافات نهاية الجلسة | +| `examples/convention-policies/security-policies.mjs` | سياسات أمان قائمة على الاتفاقية (حظر كتابات .env، منع إعادة تاريخ git) | +| `examples/convention-policies/workflow-policies.mjs` | سياسات سير عمل قائمة على الاتفاقية (تذكيرات الاختبار، ملفات الكتابة للتدقيق) | ### استخدام أمثلة الملفات الصريحة @@ -344,7 +344,7 @@ export { customPolicies }; failproofai policies --install --custom ./examples/policies-basic.js ``` -### استخدام أمثلة قائمة على الاتفاقية +### استخدام الأمثلة القائمة على الاتفاقية ```bash # نسخ إلى مستوى المشروع @@ -356,4 +356,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -لا توجد حاجة لأمر التثبيت - يتم التقاط الملفات تلقائياً عند حدث الخطاف التالي. \ No newline at end of file +لا حاجة إلى أمر تثبيت - يتم التقاط الملفات تلقائياً في حدث الخطاف التالي. \ No newline at end of file diff --git a/docs/ar/dashboard.mdx b/docs/ar/dashboard.mdx index a4d2e739..6b0003f7 100644 --- a/docs/ar/dashboard.mdx +++ b/docs/ar/dashboard.mdx @@ -5,7 +5,7 @@ description: "مراقبة جلسات الوكيل، ومراجعة استدعا icon: chart-line --- -لوحة تحكم failproofai هي تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي لديك وإدارة السياسات. اطّلع على ما فعله وكلاؤك أثناء غيابك. +لوحة التحكم failproofai هي تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي الخاص بك وإدارة السياسات. انظر ما فعله وكيلاؤك أثناء غيابك. --- @@ -15,9 +15,9 @@ icon: chart-line failproofai ``` -يفتح على `http://localhost:8020`. +تُفتح في `http://localhost:8020`. -تقرأ لوحة التحكم بيانات المشروع المحلية والجلسة وتكوين failproofai مباشرة من نظام الملفات. تُرسل الميزات المصرح بها الاختيارية، مثل تذكيرات التدقيق والدعوات، المعلومات المطلوبة لتلك الطلبات (بما في ذلك عناوين البريد الإلكتروني) إلى واجهات برمجية بعيدة. +تقرأ لوحة التحكم بيانات المشروع المحلي والجلسة وإعدادات failproofai مباشرة من نظام الملفات. تُرسل الميزات المصرح بها اختيارياً، مثل تذكيرات التدقيق والدعوات، المعلومات المطلوبة لتلك الطلبات (بما فيها عناوين البريد الإلكتروني) إلى واجهات برمجية بعيدة. --- @@ -25,83 +25,83 @@ failproofai ### المشاريع -يسرد جميع مشاريع Claude Code و OpenAI Codex و GitHub Copilot CLI _(beta)_ و Cursor Agent _(beta)_ و OpenCode _(beta)_ و Pi _(beta)_ و Hermes و OpenClaw و Factory Droid و Devin و Antigravity و Goose الموجودة على جهازك. يتم اكتشاف مشاريع Claude من `~/.claude/projects/` (أو المسار المحدد بواسطة `CLAUDE_PROJECTS_PATH`); يتم اكتشاف مشاريع Codex من خلال مسح كل نسخة من النصوص تحت `~/.codex/sessions///
/*.jsonl` وتجميعها حسب `cwd` المسجلة في السجل الأول لكل جلسة; يتم اكتشاف مشاريع Copilot CLI من خلال مسح كل `~/.copilot/session-state//workspace.yaml` (قابل للتكوين عبر `COPILOT_HOME`) وتجميعها حسب حقل `cwd`; يتم اكتشاف مشاريع Cursor Agent من خلال مسح البيانات الوصفية لكل جلسة تحت `~/.cursor/agent-sessions//` (قابل للتكوين عبر `CURSOR_HOME`، مع اختبار `conversations/` و `sessions/` كبدائل) للبحث عن `cwd` scalar في `meta.json` / `session.json` / `workspace.yaml`; يتم اكتشاف مشاريع OpenCode بالاستعلام عن قاعدة بيانات SQLite الخاصة بها في `~/.local/share/opencode/opencode.db` عبر `opencode db --format json` (نقرأ جداول `session` و `project` ونجمعها حسب `project_id`); يتم اكتشاف مشاريع Pi من خلال مسح نصوص JSONL لكل جلسة تحت `~/.pi/agent/sessions//_.jsonl` (قابل للتكوين عبر `PI_SESSIONS_DIR`) والحصول على `cwd` من السجل الأول لكل جلسة; يتم قراءة جلسات بوابة Hermes مباشرة من متجر SQLite لكل ملف تعريف — `~/.hermes/state.db` بالإضافة إلى `~/.hermes/profiles//state.db` (قابل للتجاوز عبر `HERMES_HOME`، أو `HERMES_DB_PATH` لقاعدة بيانات واحدة) — وتجميعها في مشاريع `hermes--` حسب الملف الشخصي و `source` (Slack/Telegram/cli/cron — جلسات البوابة لا تحتوي على cwd); يتم قراءة جلسات بوابة OpenClaw من `~/.openclaw/agents//sessions/*.jsonl` وتجميعها في مشاريع `openclaw--` حسب الوكيل والقناة (أيضًا بدون cwd); يتم اكتشاف مشاريع Factory Droid من نصوص JSONL في `~/.factory/sessions//*.jsonl` وتجميعها حسب cwd; مشاريع Devin من قاعدة بيانات SQLite الخاصة بها في `~/.local/share/devin/cli/sessions.db` (مجمعة حسب `working_directory` لكل جلسة); مشاريع Antigravity من نصوص JSONL في `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` وتجميعها حسب cwd; ومشاريع Goose من قاعدة بيانات SQLite الخاصة بها في `~/.local/share/goose/sessions/sessions.db` (مجمعة حسب `working_dir` لكل جلسة). يتم عرض المشروع الذي تم استخدامه بواسطة عدة CLIs كصف واحد بجميع الشارات المطابقة. استخدم القائمة المنسدلة **CLI** أعلى الجدول للتصفية حسب CLI وكيل محدد; يحفظ URL اختيارك كـ `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +تسرد جميع مشاريع Claude Code و OpenAI Codex و GitHub Copilot CLI _(بيتا)_ و Cursor Agent _(بيتا)_ و OpenCode _(بيتا)_ و Pi _(بيتا)_ و Hermes و OpenClaw و Factory Droid و Devin و Antigravity و Goose الموجودة على جهازك. يتم اكتشاف مشاريع Claude من `~/.claude/projects/` (أو المسار المحدد بواسطة `CLAUDE_PROJECTS_PATH`); مشاريع Codex يتم اكتشافها بمسح كل نسخة احتياطية تحت `~/.codex/sessions///
/*.jsonl` وتجميعها حسب `cwd` المسجل في السجل الأول من كل جلسة; مشاريع Copilot CLI يتم اكتشافها بمسح كل `~/.copilot/session-state//workspace.yaml` (قابل للتكوين عبر `COPILOT_HOME`) وتجميعها حسب حقل `cwd` الخاص به; مشاريع Cursor Agent يتم اكتشافها بمسح البيانات الوصفية لكل جلسة تحت `~/.cursor/agent-sessions//` (قابل للتكوين عبر `CURSOR_HOME`، مع اختبار `conversations/` و `sessions/` كبدائل) للبحث عن `cwd` في `meta.json` / `session.json` / `workspace.yaml`; مشاريع OpenCode يتم اكتشافها بالاستعلام عن قاعدة بيانات SQLite الخاصة به في `~/.local/share/opencode/opencode.db` عبر `opencode db --format json` (نقرأ جداول `session` و `project` ونجمعها حسب `project_id`); مشاريع Pi يتم اكتشافها بمسح نسخ احتياطية JSONL لكل جلسة تحت `~/.pi/agent/sessions//_.jsonl` (قابل للتكوين عبر `PI_SESSIONS_DIR`) وسحب `cwd` من السجل الأول في كل جلسة; جلسات بوابة Hermes يتم قراءتها مباشرة من متجر SQLite من كل ملف تعريف — `~/.hermes/state.db` بالإضافة إلى `~/.hermes/profiles//state.db` (قابل للتجاوز عبر `HERMES_HOME`، أو `HERMES_DB_PATH` لقاعدة بيانات واحدة) — وتجميعها في مشاريع `hermes--` حسب الملف الشخصي و `source` (Slack/Telegram/cli/cron — لا توجد cwd في جلسات البوابة); جلسات بوابة OpenClaw يتم قراءتها من `~/.openclaw/agents//sessions/*.jsonl` وتجميعها في مشاريع `openclaw--` حسب الوكيل والقناة (أيضاً بدون cwd); مشاريع Factory Droid يتم اكتشافها من نسخ احتياطية JSONL في `~/.factory/sessions//*.jsonl` وتجميعها حسب cwd; مشاريع Devin من قاعدة بيانات SQLite الخاصة به في `~/.local/share/devin/cli/sessions.db` (مجمعة حسب `working_directory` الخاص بكل جلسة); مشاريع Antigravity من نسخ احتياطية JSONL في `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` وتجميعها حسب cwd; ومشاريع Goose من قاعدة بيانات SQLite الخاصة به في `~/.local/share/goose/sessions/sessions.db` (مجمعة حسب `working_dir` الخاص بكل جلسة). يتم عرض المشروع الذي تم استخدامه بواسطة عدة واجهات سطر أوامر كصف واحد مع جميع الشارات المطابقة. استخدم القائمة المنسدلة **CLI** أعلى الجدول لتصفية حسب واجهة سطر أوامر وكيل محددة؛ يحافظ عنوان URL على اختيارك كـ `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -يكون Hermes و OpenClaw مقيدين بنطاق المستخدم ولا يوجد دليل عمل للتجميع حسبها، لذا يتم عرضهما كـ **شجرة مجلدات قابلة للطي** — الملف الشخصي (أو الوكيل) على المستوى الأعلى، وقنواته تحته — بينما يبقى كل CLI مستند إلى cwd صفًا مسطحًا. تتجمع صفوف المجلد عدد الجلسات والنشاط الأخير لكل شيء تحتها، يتم تذكر المجلدات المطويّة بين الزيارات، وتوسع البحث الكلمات الأساسية ما تطابقه. +Hermes و OpenClaw محدودة بنطاق المستخدم وليس لديها دليل عمل للتجميع، لذا يتم عرضها كـ **شجرة مجلد قابلة للطي** — الملف الشخصي (أو الوكيل) في المستوى الأعلى، قنواته تحته — بينما تبقى كل واجهة سطر أوامر مستندة إلى cwd صفًا مسطحًا. تقوم صفوف المجلدات بتجميع عدد الجلسات وأحدث نشاط لكل شيء تحتها، يتم تذكر المجلدات المطوية بين الزيارات، وتوسع بحث الكلمات الرئيسية أي شيء يطابقه. يعرض كل مشروع: - اسم المشروع (مشتق من مسار المجلد) -- شارة CLI — `Claude Code` (برتقالي)، `OpenAI Codex` (بنفسجي)، `GitHub Copilot` (أزرق)، `Cursor Agent` (أخضر زمردي)، `OpenCode` (كهرماني)، `Pi` (وردي)، و/أو `Hermes` (نيلي) -- تاريخ نشاط الجلسة الأخيرة +- شارة CLI — `Claude Code` (برتقالي)، `OpenAI Codex` (بنفسجي)، `GitHub Copilot` (أزرق)، `Cursor Agent` (زمردي)، `OpenCode` (كهرماني)، `Pi` (وردي)، و/أو `Hermes` (نيلي) +- تاريخ أحدث نشاط جلسة -انقر على مشروع لمعاينة جلساته. +انقر على مشروع لمشاهدة جلساته. ### الجلسات -يسرد جميع الجلسات ضمن مشروع. تعرض كل جلسة: +تسرد جميع الجلسات في مشروع. يعرض كل جلسة: - معرّف الجلسة - طوابع زمنية البداية والنهاية - عدد استدعاءات الأدوات -- عدد أنشطة الخطاف (السياسات التي تم تفعيلها) +- عدد نشاط الخطاف (السياسات التي تم تفعيلها) -استخدم مرشح نطاق التاريخ والبحث عن معرّف الجلسة لتضييق القائمة. يتم تقسيم الجلسات إلى صفحات. +استخدم مرشح نطاق التاريخ وبحث معرّف الجلسة لتضييق القائمة. يتم تقسيم الجلسات إلى صفحات. انقر على جلسة لفتح عارض الجلسة. ### عارض الجلسة -يجيب عارض الجلسة على السؤال الرئيسي للوكلاء المستقلين: ماذا فعل الوكيل، وهل بقي على المسار الصحيح؟ تشير شارة CLI بجوار الرأس إلى ما إذا كانت الجلسة عبارة عن نسخة Claude Code أو OpenAI Codex أو GitHub Copilot CLI أو Cursor Agent أو OpenCode أو Pi أو Hermes أو OpenClaw أو Factory Droid أو Devin أو Antigravity أو Goose. يعرض جدول زمني لكل شيء حدث في جلسة: +يجيب عارض الجلسة على السؤال الرئيسي بشأن الوكلاء المستقلين: ماذا فعل الوكيل، وهل ظل على المسار الصحيح؟ تشير شارة CLI بجانب الرأس إلى ما إذا كانت الجلسة نسخة احتياطية Claude Code أو OpenAI Codex أو GitHub Copilot CLI أو Cursor Agent أو OpenCode أو Pi أو Hermes أو OpenClaw أو Factory Droid أو Devin أو Antigravity أو Goose. يعرض جدول زمني لكل ما حدث في جلسة: -- **الرسائل** - ردود Claude النصية والطلبات من المستخدم +- **الرسائل** - رد Claude النصي وطلبات المستخدم - **استدعاءات الأدوات** - كل أداة استدعاها Claude، مع مدخلاتها ومخرجاتها -- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تفعيلها والقرار الذي أعادته +- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تفعيلها والقرار الذي عادت به -يعرض شريط الإحصائيات في الأعلى مدة الجلسة والعدد الإجمالي لاستدعاءات الأدوات وملخص قرارات الخطاف (عدد allow / deny / instruct). +يعرض شريط الإحصائيات في الأعلى مدة الجلسة وإجمالي استدعاءات الأدوات وملخص قرارات الخطاف (عدد السماح / الرفض / التعليمات). -انقر على زر **تنزيل السجلات** لتصدير الجلسة. بالنسبة لجلسات Claude Code و Codex و Copilot و Cursor و Pi، تحصل على نسخة JSONL الأصلية على القرص بالضبط؛ بالنسبة لـ OpenCode (التي تعيش جلساتها في SQLite وليس على القرص)، تحصل على مستند JSON يعكس جداول `session` / `messages` / `parts` الأساسية. +انقر على الزر **تنزيل السجلات** لتصدير الجلسة. بالنسبة لجلسات Claude Code و Codex و Copilot و Cursor و Pi، تحصل على نسخة احتياطية JSONL الأصلية على القرص بالكامل؛ بالنسبة لـ OpenCode (التي تعيش جلساتها في SQLite وليس على القرص)، تحصل على مستند JSON يعكس الجداول الأساسية `session` / `messages` / `parts`. ### التدقيق -تقرير يحركه الشخصية حول كيفية سلوك وكيلك بالفعل عبر الجلسات الماضية. يشغّل نفس المسح الذي يقوم به CLI لـ `failproofai audit` لكن يعرضه كملصق شاشة واحد قابل للمشاركة + أربعة أقسام تحت الطي: +تقرير يحركه الشخصية حول كيفية تصرف وكيلك بالفعل عبر الجلسات السابقة. يقوم بتشغيل نفس المسح مثل واجهة سطر الأوامر `failproofai audit` لكن يعرضها كملصق قابل للمشاركة على شاشة واحدة + أربعة أقسام أسفل الطية: -1. **الملصق** — يملأ منفذ العرض الأول. منطقة PNG ذاتية التضمن مع علامة failproof_ai + تسمية التدقيق · فهرس النمط الأصلي (`№ NN of 08`) + تاريخ التدقيق · درجة رقمية (0–100) + حبة تصنيف النسبة المئوية (`top 15%`) · اسم النمط الأصلي (واحد من `the optimist`، `the cowboy`، `the explorer`، `the goldfish`، `the paranoid architect`، `the precision builder`، `the hammer`، `the ghost`) + شريط 3 كلمات · `// only N% of agents are this archetype` سطر الندرة · بلاطة sigil 8×8 بكسل · `audit yours → failproof.ai` التذييل. تجلس ثلاثة أزرار مشاركة خارج صندوق الالتقاط: `post your archetype` (نية X)، `share on linkedin`، `download poster`. يتم تشغيل الالتقاط عبر `html-to-image` بحيث يطابق PNG عرض الشاشة بكسل لكل بكسل (الحدود المتقطعة، قناع شعار SVG، التدرجات، مقاييس الخطوط — الكل محفوظ). -2. **نقاط القوة** — قائمة صفوف هادئة لسلوكيات وكيلك الذي يفعلها بالفعل بشكل صحيح، مشتقة من بيانات التدقيق المباشرة (معدل استدعاء الأداة النظيف، بدون دفع مباشر إلى main، صفر تسرب بيانات اعتماد، صفر عواصف إعادة محاولة) — يتم سطح كل منها فقط عندما يكون لدى السياسة ذات الصلة سجل نظيف عبر نافذة التدقيق. -3. **الغرائب** — جدول ما تسرب، مرتب حسب الشدة: `when · what slipped + the policy that would've caught it · severity pill · seen`، حيث تقرأ التكرار `new` (مرة واحدة)، `N× seen` (2–9 مرات)، أو `recurring` (10+). -4. **كيفية التحسن** — قائمة صفوف هادئة، واحدة لكل سياسة موصى بها: اسم السياسة بالأبيض، وصف سطر واحد، أمر التثبيت + زر نسخ على الجانب الأيمن. يقرأ رأس القسم `enable all N → projected · ` (الدرجة التي ستصل إليها مع تطبيق كل إصلاح)، وزر `[install all]` الخاص به ينسخ الأمر المدمج `failproofai policy add a b c …` لكل سياسة موصى بها. -5. **العودة أفضل** — بطاقتان جنبًا إلى جنب. اليسار: ضع تذكيرًا (منتقي الإيقاع `3d` / `7d` / `14d` / `30d`; يستمر عبر `/api/auth/reminder` بمجرد المصادقة). اليمين: فتح امتيازات failproof — `invite a friend` يفتح نافذة تأخذ قائمة بريد إلكتروني للأصدقاء مفصولة بفواصل/مسافات/سطور جديدة (10 كحد أقصى لكل إرسال)، POST لهم إلى `/api/audit/invite`، الذي يحول إلى `POST /v0/invite` لخادم api. يرسل خادم api بريد إلكترونيًا واحدًا لكل مستقبل من `invite@failproof.ai` مع نسخة المرسل وتعيين `Reply-To`، بحيث يرى المستقبل من دعاهم والمرسل يحصل على نسخة في علبة الوارد الخاصة به. يتم توجيه المستخدمين المجهولين عبر `AuthDialog` أولاً بحيث يتم معرفة بريد المرسل قبل الدعوات. يعتبر الاستحقاق / تحقيق الامتيازات متابعة. +1. **الملصق** — يملأ عرض المنفذ الأول. منطقة PNG مكتفية ذاتياً مع شعار failproof_ai + تسمية التدقيق · مؤشر النموذج الأولي (`№ NN من 08`) + تاريخ التدقيق · درجة رقمية (0–100) + حبة تصنيف النسبة المئوية (`أفضل 15%`) · اسم النموذج الأولي (أحد `the optimist`، `the cowboy`، `the explorer`، `the goldfish`، `the paranoid architect`، `the precision builder`، `the hammer`، `the ghost`) + شريط كلمات رئيسية 3 · سطر ندرة `// only N% من الوكلاء هذا النموذج الأولي` · بلاط شعار 8×8 بكسل · تذييل `audit yours → failproof.ai`. ثلاثة أزرار مشاركة تجلس خارج صندوق الالتقاط: `post your archetype` (نية X)، `share on linkedin`، `download poster`. يتم الالتقاط من خلال `html-to-image` بحيث تطابق PNG العرض على الشاشة بكسل تلو الآخر (الحدود المنقوطة، قناع شعار SVG، التدرجات، مقاييس الخطوط — كل شيء محفوظ). +2. **نقاط القوة** — قائمة صفوف هادئة من السلوكيات التي يقوم بها وكيلك بالفعل بشكل صحيح، مشتقة من بيانات التدقيق المباشرة (معدل استدعاء أداة نظيف، لا دفعات مباشرة إلى main، صفر تسريب بيانات الاعتماد، صفر عاصفة إعادة محاولة) — يتم عرض كل واحد فقط عندما تحتفظ السياسة ذات الصلة بسجل نظيف عبر نافذة التدقيق. +3. **التفاصيل الغريبة** — جدول ما تسرب، مرتب حسب الشدة: `when · ما تسرب + السياسة التي كانت ستلتقطه · حبة الشدة · seen`، حيث يقرأ التكرار `new` (مرة واحدة)، `N× seen` (2–9 مرات)، أو `recurring` (10+). +4. **كيفية التحسين** — قائمة صفوف هادئة، واحدة لكل سياسة موصوفة: اسم السياسة باللون الأبيض، وصف بسطر واحد، أمر التثبيت + زر النسخ على الجانب الأيمن. يقرأ رأس القسم `enable all N → projected · ` (الدرجة التي ستصل إليها مع تطبيق كل إصلاح)، وزر `[install all]` الخاص به ينسخ أمر `failproofai policy add a b c …` المدمج لكل سياسة موصوفة. +5. **العودة بشكل أفضل** — بطاقتان جنباً إلى جنب. اليسار: اضبط تذكيراً (منتقي الإيقاع `3d` / `7d` / `14d` / `30d`؛ يستمر من خلال `/api/auth/reminder` بمجرد المصادقة). اليمين: فتح مزايا failproof — يفتح `invite a friend` نافذة منبثقة تأخذ قائمة بريد إلكترونية للأصدقاء مفصولة بفواصل/مسافات/فواصل أسطر (الحد الأقصى 10 لكل إرسال)، POSTs منها إلى `/api/audit/invite`، الذي يعيد توجيهها إلى `/v0/invite` من api-server. يرسل api-server بريداً إلكترونياً واحداً لكل مستقبل من `invite@failproof.ai` مع Cc للمرسل و `Reply-To` المحدد، بحيث يرى المستقبل من دعاهم ويحصل المرسل على نسخة في صندوق البريد الخاص به. يتم توجيه المستخدمين المجهولين عبر `AuthDialog` أولاً بحيث يتم معرفة بريد المرسل قبل إرسال الدعوات. تحقق الاستحقاق / مزايا هو متابعة. -مدفوع بوقت تشغيل `failproofai audit` — انظر [Audit CLI](/ar/cli/audit) لمحرك المسح الأساسي والأعلام المدعومة وثوابت التخزين المؤقت لكل نسخة. تخزن لوحة التحكم النتيجة الأخيرة في `~/.failproofai/audit-dashboard.json` (الوضع `0600`، فتحة واحدة، تخزين جديد يكتب فوق) بحيث تكون الزيارات الثانية فورية؛ **يتم رفض كل من التخزين المؤقت لكل نسخة ونتيجة كاملة عند القراءة بمجرد أن تصبح أقدم من 7 أيام** بحيث لا تخدم لوحة التحكم بصمت نتيجة بعمر أسبوع — بعد انتهاء الصلاحية `/audit` يسقط إلى حالته الفارغة ويطالب بتشغيل جديد. انقر على `[ re-audit now ]` بالقرب من أسفل التقرير POST `/api/audit/run` مع `noCache: true` — إعادة التدقيق تتجاوز التخزين المؤقت لكل نسخة وتعيد مسح كل نسخة من الصفر بدلاً من صامتة إرجاع النتيجة المخزنة مؤقتًا — وتستطلع لوحة التحكم `/api/audit/status` بـ 1Hz حتى ينتهي التشغيل؛ ينقر شريط تقدم وردي لاصق إلى أعلى منفذ العرض أثناء التشغيل مع موقت انقضاء، والنتيجة الطازجة تدخل في مكانها عند النجاح (لا إعادة تحميل كامل الصفحة؛ تترك إعادة التدقيق الفاشلة التقرير السابق سليمًا). عند الفشل يتحول الشريط إلى الأحمر مع نسخ مفتاح قبالة `RerunError.kind` (`timeout` / `network` / `post_failed`). يتم سطح الحالة الفارغة (لا يوجد تخزين مؤقت أو منتهي الصلاحية) وحالة الصفر جلسات (يوجد التخزين المؤقت لكن المسح لم يجد نسخ) بشكل منفصل. +مدفوعة بوقت تشغيل `failproofai audit` — انظر [Audit CLI](/ar/cli/audit) لمحرك المسح الأساسي والأعلام المدعومة وثوابت ذاكرة التخزين المؤقت لكل نسخة احتياطية. تخزن لوحة التحكم آخر نتيجة مؤقتة في `~/.failproofai/audit-dashboard.json` (الوضع `0600`، فتحة واحدة، تستبدل التشغيلات الجديدة) بحيث تكون إعادة الزيارات فورية؛ **يتم رفض كل من ذاكرة التخزين المؤقت لكل نسخة احتياطية والنتيجة الكاملة عند القراءة بمجرد أن تصبح أقدم من 7 أيام** لذا لا تخدم لوحة التحكم بصمت نتيجة قديمة بأسبوع — بعد TTL `/audit` ينخفض إلى حالة فارغة ويطالب بتشغيل جديد. ينقر `[ re-audit now ]` بالقرب من أسفل التقرير POSTs `/api/audit/run` مع `noCache: true` — يتجاوز إعادة التدقيق ذاكرة التخزين المؤقت لكل نسخة احتياطية وإعادة فحص كل نسخة احتياطية من الصفر بدلاً من إرجاع النتيجة المخزنة بصمت — والعينة البحثية تصوت `/api/audit/status` في 1Hz حتى ينتهي التشغيل؛ شريط تقدم وردي لزج ينضم إلى الجزء العلوي من المنفذ أثناء التشغيل مع مؤقت مضاقة، والنتيجة الطازجة تنبدل في المكان عند النجاح (لا إعادة تحميل كاملة للصفحة؛ إعادة تدقيق فاشلة تترك التقرير السابق سليماً). عند الفشل ينقلب الشريط إلى الأحمر مع نسخ معفى عن طريق `RerunError.kind` (`timeout` / `network` / `post_failed`). يتم عرض الحالة الفارغة (لا ذاكرة تخزين مؤقت أو منتهية الصلاحية) وحالة الصفر الجلسات (ذاكرة تخزين مؤقت موجودة لكن المسح لم يجد نسخ احتياطية) بشكل منفصل. ### السياسات -صفحة بتبويبين لإدارة السياسات ومراجعة النشاط. +صفحة ذات علامات تبويب لإدارة السياسات ومراجعة النشاط. - - - تحديد متعدد لـ CLIs الوكيل التي يحميها failproofai من لوحة واحدة — Claude Code و OpenAI Codex و GitHub Copilot و Cursor Agent و OpenCode و Pi و Hermes جميعها لها صف مع حالة التثبيت (`Active` / `Detected` / `Inactive`)، ومسار إعدادات نطاق المستخدم، وتأكيد ملون العلامة التجارية. تحقق أو قم بإلغاء تحديد CLIs التي تريدها وانقر على `Apply changes` لتثبيت/إلغاء تثبيت الفرق في خطوة واحدة. يتم فحص CLIs الذي تم الكشف عن ملفه الثنائي على PATH مسبقًا. - - تبديل السياسات الفردية على أو إيقاف تشغيلها بنقرة واحدة (يكتب إلى `~/.failproofai/policies-config.json` — مشترك بين كل CLI مثبت) - - قم بتوسيع السياسة لتكوين معاملات (للسياسات التي تدعم `policyParams`) - - تعيين مسار ملف سياسات مخصص + + - اختر من جزء واحد أي واجهات سطر أوامر وكيل يحمي failproofai — Claude Code و OpenAI Codex و GitHub Copilot و Cursor Agent و OpenCode و Pi و Hermes كل واحد منها له صف مع حالة التثبيت (`Active` / `Detected` / `Inactive`)، مسار إعدادات النطاق الخاص بالمستخدم، ولكنة مميزة بألوان العلامة التجارية. تحقق أو قم بإلغاء تحديد واجهات سطر الأوامر التي تريدها وانقر على `Apply changes` لتثبيت/إلغاء تثبيت الفرق في خطوة واحدة. يتم فحص واجهات سطر الأوامر التي يتم اكتشاف ملفها الثنائي على PATH مسبقاً. + - بدّل السياسات الفردية على أو إيقاف بنقرة واحدة (يكتب إلى `~/.failproofai/policies-config.json` — مشترك عبر كل واجهة سطر أوامر مثبتة) + - وسّع سياسة لتكوين معاملات (بالنسبة للسياسات التي تدعم `policyParams`) + - عيّن مسار ملف سياسات مخصص - - - سجل مكتمل مرقم لكل حدث خطاف تم تفعيله عبر جميع الجلسات - - التصفية حسب القرار أو نوع الحدث أو CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose) أو اسم السياسة أو معرّف الجلسة - - يعرض كل صف: الطابع الزمني، اسم السياسة، القرار، شارة CLI (برتقالي = Claude Code، بنفسجي = OpenAI Codex، أزرق = GitHub Copilot، أخضر زمردي = Cursor Agent، كهرماني = OpenCode، وردي = Pi، نيلي = Hermes، فيروزي = OpenClaw، وردي فاقع = Factory Droid، بنفسجي = Devin، سماوي = Antigravity، أخضر فاتح = Goose)، اسم الأداة، معرّف الجلسة، والسبب لقرارات deny/instruct - - انقر على معرّف الجلسة لفتح نسخته — يكتشف عارض الوكيل تلقائيًا أي CLI أطلق الخطاف (Claude `~/.claude/projects/…`، Codex `~/.codex/sessions/…`، Copilot CLI `~/.copilot/session-state//events.jsonl`، Cursor Agent `~/.cursor/agent-sessions//events.jsonl`، OpenCode `~/.local/share/opencode/opencode.db`، Pi `~/.pi/agent/sessions//.jsonl`، Hermes `~/.hermes/state.db`، OpenClaw `~/.openclaw/agents//sessions/*.jsonl`، Factory Droid `~/.factory/sessions//.jsonl`، Devin `~/.local/share/devin/cli/sessions.db`، Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`، Goose `~/.local/share/goose/sessions/sessions.db`) ويعرض شارة CLI المطابقة في الرأس + + - السجل الكامل للصفحات من كل حدث خطاف تم تفعيله عبر جميع الجلسات + - تصفية حسب القرار ونوع الحدث و CLI (Claude Code / OpenAI Codex / GitHub Copilot _(بيتا)_ / Cursor Agent _(بيتا)_ / OpenCode _(بيتا)_ / Pi _(بيتا)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose) واسم السياسة أو معرّف الجلسة + - يعرض كل صف: طابع زمني، اسم السياسة، القرار، شارة CLI (برتقالي = Claude Code، بنفسجي = OpenAI Codex، أزرق = GitHub Copilot، زمردي = Cursor Agent، كهرماني = OpenCode، وردي = Pi، نيلي = Hermes، فيروزي = OpenClaw، وردي فاتح = Factory Droid، بنفسجي = Devin، سماوي = Antigravity، أخضر فاتح = Goose)، اسم الأداة، معرّف الجلسة، والسبب لقرارات الرفض/التعليمات + - انقر على معرّف الجلسة لفتح نسخته الاحتياطية — يكتشف العارض تلقائياً أي CLI أطلق الخطاف (Claude `~/.claude/projects/…`، Codex `~/.codex/sessions/…`، Copilot CLI `~/.copilot/session-state//events.jsonl`، Cursor Agent `~/.cursor/agent-sessions//events.jsonl`، OpenCode `~/.local/share/opencode/opencode.db`، Pi `~/.pi/agent/sessions//.jsonl`، Hermes `~/.hermes/state.db`، OpenClaw `~/.openclaw/agents//sessions/*.jsonl`، Factory Droid `~/.factory/sessions//.jsonl`، Devin `~/.local/share/devin/cli/sessions.db`، Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`، Goose `~/.local/share/goose/sessions/sessions.db`) ويعرض شارة CLI المطابقة في الرأس --- -## الانتعاش التلقائي +## إعادة التحميل التلقائي -تحتوي لوحة التحكم على مبديل الانتعاش التلقائي في الملاح العلوي. عند التفعيل، تنعش الصفحة الحالية بشكل دوري لعرض الجلسات الجديدة ونشاط السياسة أثناء ظهورها. ضروري لمراقبة جلسات الوكيل المستقلة ذات المدة الطويلة. +تحتوي لوحة التحكم على مبدل إعادة تحميل تلقائي في شريط التنقل العلوي. عند التفعيل، يتم تحديث الصفحة الحالية بشكل دوري لعرض الجلسات الجديدة ونشاط السياسة عند ظهورها. ضروري لمراقبة جلسات الوكيل المستقل طويلة الأجل. --- ## تعطيل الصفحات -إذا كنت تحتاج فقط إلى بعض أجزاء لوحة التحكم، عيّن `FAILPROOFAI_DISABLE_PAGES` إلى قائمة مفصولة بفواصل لأسماء الصفحات: +إذا كنت تحتاج فقط إلى بعض أجزاء لوحة التحكم، اضبط `FAILPROOFAI_DISABLE_PAGES` على قائمة مفصولة بفواصل من أسماء الصفحات: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -113,7 +113,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## تكوين مسار المشاريع -بشكل افتراضي، تقرأ لوحة التحكم من دليل مشاريع Claude Code القياسي. تجاوز ذلك للإعدادات المخصصة: +بشكل افتراضي، تقرأ لوحة التحكم من دليل مشاريع Claude Code القياسي. استبدله للإعدادات المخصصة: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -123,30 +123,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## الوصول من مضيف غير localhost -عند تشغيل لوحة التحكم في **وضع التطوير** (`npm run dev`) والوصول إليها من اسم مضيف بخلاف `localhost` - على سبيل المثال، مجال مخصص أو IP بعيد أو URL محفور — قد تظهر تحذير مثل: +عند تشغيل لوحة التحكم في **وضع dev** (`npm run dev`) والوصول إليها من اسم مضيف بخلاف `localhost` - على سبيل المثال، مجال مخصص أو IP بعيد أو عنوان URL مفروي - قد تشاهد تحذيراً مثل: ```text -⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". +⚠ تم حظر طلب الأصل المتقاطع إلى مورد Next.js dev /_next/webpack-hmr من dashboard.example.com. ``` -هذا هو Next.js يحظر الوصول عبر الأصل إلى مورد HMR (إعادة تحميل الوحدة الساخنة) للخادم، وهي ميزة خاصة بـ dev فقط. للسماح لمضيفك، استخدم العلم `--allowed-origins`: +هذا هو Next.js يحظر الوصول عبر الأصول إلى websocket HMR (إعادة تحميل الوحدة الساخنة)، وهي ميزة dev فقط. للسماح لمضيفك، استخدم علم `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -بالنسبة لعدة مضيفين أو IPs، مرر قائمة مفصولة بفواصل: +بالنسبة لعدة مضيفات أو IP، مرر قائمة مفصولة بفواصل: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -يمكنك أيضًا تعيين متغير البيئة `FAILPROOFAI_ALLOWED_DEV_ORIGINS` بدلاً من ذلك: +يمكنك أيضاً تعيين متغير البيئة `FAILPROOFAI_ALLOWED_DEV_ORIGINS` بدلاً من ذلك: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -هذا ينطبق فقط على وضع dev. عند تشغيل `failproofai` (وضع الإنتاج)، لا يوجد websocket HMR ولا مشكلة مورد dev عبر الأصل. +ينطبق هذا فقط على وضع dev. عند تشغيل `failproofai` (وضع الإنتاج)، لا توجد websocket HMR ولا مشكلة مورد dev عبر الأصول. \ No newline at end of file diff --git a/docs/ar/examples.mdx b/docs/ar/examples.mdx index 444a2ab3..372696a4 100644 --- a/docs/ar/examples.mdx +++ b/docs/ar/examples.mdx @@ -4,13 +4,13 @@ description: "كيفية إعداد hooks لـ Claude Code و Agents SDK" icon: book-open --- -أمثلة جاهزة للاستخدام لسيناريوهات شائعة. كل واحد يوضح كيفية التثبيت وما يمكن توقعه. +أمثلة جاهزة للاستخدام لسيناريوهات شائعة. يوضح كل منها كيفية التثبيت وما يمكن توقعه. --- ## إعداد hooks لـ Claude Code -يتكامل Failproof AI مع Claude Code عبر [نظام hooks الخاص به](https://docs.anthropic.com/en/docs/claude-code/hooks). عند تشغيل `failproofai policies --install`، يسجل أوامر hook في ملف `settings.json` الخاص بـ Claude Code التي تعمل عند كل استدعاء أداة. +يتكامل Failproof AI مع Claude Code عبر [نظام hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). عند تشغيل `failproofai policies --install`، يسجل أوامر hook في `settings.json` الخاص بـ Claude Code التي تعمل على كل استدعاء أداة. @@ -28,14 +28,14 @@ icon: book-open cat ~/.claude/settings.json | grep failproofai ``` - يجب أن ترى إدخالات hook لأحداث `PreToolUse` و `PostToolUse` و `Notification` و `Stop`. + يجب أن ترى مدخلات hook لأحداث `PreToolUse` و `PostToolUse` و `Notification` و `Stop`. ```bash claude ``` - تعمل السياسات تلقائياً عند كل استدعاء أداة. حاول طلب من Claude تشغيل `sudo rm -rf /` - سيتم حظره. + تعمل السياسات تلقائياً على كل استدعاء أداة. حاول طلب Claude لتشغيل `sudo rm -rf /` - سيتم حظره. @@ -43,7 +43,7 @@ icon: book-open ## إعداد hooks لـ Agents SDK -إذا كنت تبني باستخدام [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)، يمكنك استخدام نفس نظام hooks برمجياً. +إذا كنت تبني باستخدام [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)، يمكنك استخدام نظام hooks نفسه برمجياً. @@ -52,14 +52,14 @@ icon: book-open ``` - مرر أوامر hook عند إنشاء عملية الوكيل الخاص بك. تعمل hooks بنفس الطريقة كما في Claude Code - عبر JSON في stdin/stdout: + مرر أوامر hook عند إنشاء عملية وكيلك. تعمل hooks بنفس الطريقة كما في Claude Code - عبر JSON في stdin/stdout: ```bash - failproofai --hook PreToolUse # يُستدعى قبل كل أداة - failproofai --hook PostToolUse # يُستدعى بعد كل أداة + failproofai --hook PreToolUse # called before each tool + failproofai --hook PostToolUse # called after each tool ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -88,33 +88,33 @@ icon: book-open ## حظر الأوامر المدمرة -الإعداد الأكثر شيوعاً - منع الوكلاء من إلحاق الضرر الذي لا يمكن التراجع عنه. +الإعداد الأكثر شيوعاً - منع الوكلاء من إحداث أضرار لا يمكن إرجاعها. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` ما تفعله: -- `block-sudo` - يحظر جميع أوامر `sudo` -- `block-rm-rf` - يحظر حذف الملفات العودية -- `block-force-push` - يحظر `git push --force` -- `block-curl-pipe-sh` - يحظر نقل البرامج النصية البعيدة إلى shell +- `block-sudo` - حظر جميع أوامر `sudo` +- `block-rm-rf` - حظر حذف الملفات بشكل متكرر +- `block-force-push` - حظر `git push --force` +- `block-curl-pipe-sh` - حظر توجيه البرامج النصية البعيدة إلى shell --- -## منع تسريب الأسرار +## منع تسرب الأسرار -منع الوكلاء من رؤية أو تسريب بيانات الاعتماد في مخرجات الأداة. +منع الوكلاء من رؤية أو تسرب بيانات اعتماد في مخرجات الأداة. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -تعمل هذه على `PostToolUse` - بعد تشغيل أداة، تنظف المخرجات قبل أن يراها الوكيل. +تعمل هذه على `PostToolUse` - بعد تشغيل الأداة، تزيل البيانات الحساسة من المخرجات قبل أن يراها الوكيل. --- -## احصل على تنبيهات Slack عندما يحتاج الوكلاء إلى الانتباه +## الحصول على تنبيهات Slack عندما تحتاج الوكلاء إلى الاهتمام استخدم notification hook لإعادة توجيه تنبيهات الخمول إلى Slack. @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -ثبتها: +ثبّته: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -158,7 +158,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## اجعل الوكلاء على فرع واحد +## إبقاء الوكلاء على فرع واحد منع الوكلاء من تبديل الفروع أو الدفع إلى الفروع المحمية. @@ -182,9 +182,9 @@ customPolicies.add({ --- -## طلب الاختبارات قبل الالتزام +## الطلب بإجراء الاختبارات قبل الالتزام -ذكّر الوكلاء بتشغيل الاختبارات قبل الالتزام. +تذكير الوكلاء بتشغيل الاختبارات قبل الالتزام. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -231,23 +231,23 @@ customPolicies.add({ } ``` -ثم التزم بها: +ثم التزم به: ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -كل عضو في الفريق لديه failproofai مثبت سيختار هذه القواعد تلقائياً. +كل عضو فريق لديه failproofai مثبت سيلتقط هذه القواعد تلقائياً. --- ## بناء معيار جودة على مستوى المنظمة باستخدام سياسات الاتفاقية -الإعداد الأكثر تأثيراً: التزم بـ `.failproofai/policies/` في مستودعك مع سياسات مصممة لمشروعك. يحصل كل عضو في الفريق عليها تلقائياً — بدون أوامر تثبيت، بدون تغييرات في الإعدادات. +الإعداد الأكثر تأثيراً: التزم بـ `.failproofai/policies/` في مستودعك مع سياسات مخصصة لمشروعك. يحصل كل عضو فريق عليها تلقائياً - بدون أوامر تثبيت، بدون تغييرات إعدادات. - + ```bash mkdir -p .failproofai/policies ``` @@ -283,25 +283,25 @@ git commit -m "Add failproofai team policies" }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - - عندما يواجه فريقك أنماط فشل جديدة، أضف سياسات وادفع. يحصل الجميع على التحديث في `git pull` التالي. تصبح هذه السياسات معيار جودة حي ينمو مع فريقك. + + عندما يواجه فريقك أنماط فشل جديدة، أضف سياسات وادفع. يحصل الجميع على التحديث عند `git pull` التالي. تصبح هذه السياسات معيار جودة حي ينمو مع فريقك. --- -## أمثلة أخرى +## أمثلة إضافية يحتوي دليل [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) في المستودع على: -| الملف | ما يظهره | +| الملف | ما يوضحه | |------|----------| -| `policies-basic.js` | سياسات البدء - حظر كتابات الإنتاج والدفع القسري والبرامج النصية الموجهة | -| `policies-notification.js` | تنبيهات Slack لإخطارات الخمول ونهاية الجلسة | -| `policies-advanced/index.js` | الاستيرادات الانتقالية والخطافات غير المتزامنة وتنظيف مخرجات PostToolUse ومعالجة حدث Stop | \ No newline at end of file +| `policies-basic.js` | سياسات مبتدئة - حظر عمليات الكتابة في الإنتاج، فرض الدفع، البرامج النصية الموجهة | +| `policies-notification.js` | تنبيهات Slack للإشعارات الخاملة ونهاية الجلسة | +| `policies-advanced/index.js` | الاستيرادات الانتقالية، hooks غير متزامنة، تنظيف مخرجات PostToolUse، معالجة حدث Stop | \ No newline at end of file diff --git a/docs/ar/for-agents.mdx b/docs/ar/for-agents.mdx index 769006b0..3cc07a4c 100644 --- a/docs/ar/for-agents.mdx +++ b/docs/ar/for-agents.mdx @@ -13,24 +13,24 @@ npx skills add https://docs.befailproof.ai ## ما الذي تغطيه المهارة -| المجال | ما يُتضمن | +| المجال | ما هو المتضمن | |------|----------------| | السياسات | أسماء السياسات المدمجة وأنواع الأحداث والمعاملات والتفعيل/التعطيل | -| السياسات المخصصة | `customPolicies.add()`ومرشحات المطابقة و API `allow`/`deny`/`instruct` | +| السياسات المخصصة | `customPolicies.add()` ومرشحات المطابقة و API `allow`/`deny`/`instruct` | | كائن السياق | `ctx.eventType` و `ctx.toolName` و `ctx.toolInput` و `ctx.session` | -| الإعدادات | بنية `policies-config.json` ودمج النطاقات و `policyParams` | -| سطر الأوامر | `failproofai policies --install` و `--uninstall` و `--custom` والنطاقات | -| لوحة التحكم | عارض الجلسات وأنشطة السياسة والمتغيرات البيئية | -| البنية المعمارية | تدفق معالج الخطاف وأكواد الخروج واتفاقية stdin/stdout | +| الإعدادات | هيكل `policies-config.json` ودمج الأنطقة و `policyParams` | +| واجهة سطر الأوامر | `failproofai policies --install` و `--uninstall` و `--custom` والأنطقة | +| لوحة التحكم | عارض الجلسات ونشاط السياسة ومتغيرات البيئة | +| العمارة | تدفق معالج الخطاف وأكواد الخروج وعقد stdin/stdout | ## هل المهارة كاملة؟ -يقوم Mintlify بإنشاء `llms.txt` من جميع الصفحات في التنقل. تغطي مستندات Failproof AI واجهة برمجية التطبيقات الكاملة - كل سياسة وخيار ومثال مُدرج. إذا وجدت شيئاً مفقوداً، فإن المصدر موجود في `https://docs.befailproof.ai/llms-full.txt`. +ينتج Mintlify `llms.txt` من جميع الصفحات في التنقل. توثيق Failproof AI يغطي واجهة برمجية التطبيقات الكاملة - كل سياسة وخيار ومثال مدرج. إذا وجدت شيئاً ناقصاً، المصدر موجود في `https://docs.befailproof.ai/llms-full.txt`. -للحصول على سياق موجه، قم بالربط مباشرة إلى صفحة معينة: +للحصول على سياق موجه، ارتبط مباشرة بصفحة محددة: ```bash -# API السياسات المخصصة فقط +# واجهة برمجية السياسات المخصصة فقط npx skills add https://docs.befailproof.ai/custom-policies # السياسات المدمجة فقط diff --git a/docs/ar/getting-started.mdx b/docs/ar/getting-started.mdx index c82b5df2..3035dbb0 100644 --- a/docs/ar/getting-started.mdx +++ b/docs/ar/getting-started.mdx @@ -1,6 +1,7 @@ --- +--- title: البدء السريع -description: "ثبّت failproofai، وفعّل السياسات، واترك وكلاءك يعملون بموثوقية" +description: "ثبّت failproofai، فعّل السياسات، واترك وكلاءك يعملون بموثوقية" icon: rocket --- @@ -30,16 +31,16 @@ bun add -g failproofai ## البدء السريع - - السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة وكيل. تقوم بالتقاط الأوامر المدمرة وتسريب الأسرار وأنماط الفشل الأخرى قبل أن تسبب الأضرار. + + السياسات هي قواعد تُنفّذ قبل وبعد كل استدعاء أداة للوكيل. تعترض الأوامر الضارة وتسريب الأسرار وأنماط الفشل الأخرى قبل أن تسبب أضراراً. ```bash failproofai policies --install ``` - يكتب هذا مدخلات hook في CLIs الوكيل المثبتة لديك (ملف `~/.claude/settings.json` الخاص بـ Claude Code، و `~/.codex/hooks.json` الخاص بـ OpenAI Codex، و `~/.copilot/hooks/failproofai.json` الخاص بـ GitHub Copilot CLI، و `~/.cursor/hooks.json` الخاص بـ Cursor Agent، و plugin shim المُنتج بـ `~/.config/opencode/plugins/failproofai.mjs` لـ OpenCode مع إدخال تسجيل في مصفوفة `plugin` في `~/.config/opencode/opencode.json`، و `~/.pi/agent/settings.json` الخاص بـ Pi، و `~/.hermes/config.yaml` الخاص بـ Hermes، و `~/.openclaw/openclaw.json` الخاص بـ OpenClaw، و `~/.factory/hooks.json` الخاص بـ Factory Droid، و `~/.config/devin/config.json` الخاص بـ Devin CLI، و `~/.gemini/config/hooks.json` الخاص بـ Antigravity CLI، أو دليل plugin المكتشف تلقائياً لـ Goose في `~/.agents/plugins/failproofai/hooks/hooks.json`). عند وجود أكثر من واحد ستُطالب؛ مرر `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (أي مجموعة فرعية) لتخطي الرسالة. + يكتب مدخلات hook في أدوات سطر الأوامر المثبتة للوكيل (`~/.claude/settings.json` لـ Claude Code، `~/.codex/hooks.json` لـ OpenAI Codex، `~/.copilot/hooks/failproofai.json` لـ GitHub Copilot CLI، `~/.cursor/hooks.json` لـ Cursor Agent، ملف shim البرنامج الإضافي المُنتج لـ OpenCode في `~/.config/opencode/plugins/failproofai.mjs` بالإضافة إلى مدخل تسجيل في مصفوفة `plugin` في `~/.config/opencode/opencode.json`، `~/.pi/agent/settings.json` لـ Pi، `~/.hermes/config.yaml` لـ Hermes، `~/.openclaw/openclaw.json` لـ OpenClaw، `~/.factory/hooks.json` لـ Factory Droid، `~/.config/devin/config.json` لـ Devin CLI، `~/.gemini/config/hooks.json` لـ Antigravity CLI، أو مجلد البرنامج الإضافي المكتشف تلقائياً لـ Goose في `~/.agents/plugins/failproofai/hooks/hooks.json`). عند وجود أكثر من واحد ستُطلب منك اختيار؛ مرّر `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (أي مجموعة فرعية) لتخطي الطلب. - GitHub Copilot CLI و Cursor Agent و OpenCode و Pi مدعومة بـ **beta** — ثبّت باستخدام `--cli copilot` أو `--cli cursor` أو `--cli opencode` أو `--cli pi`. Hermes (hermes-agent، بوابة Slack/Telegram) يثبّت برطاق مستخدم مع `--cli hermes` وهو **أيضاً** مصدر تدقيق غير متصل. OpenClaw (بوابة openclaw، مساعد متعدد القنوات مستضاف ذاتياً) يثبّت برطاق مستخدم مع `--cli openclaw` — الإنفاذ يعمل من خلال hooks plugin معالجته (`before_agent_finalize` هو بوابة نهاية دور حقيقية، لذا builtins `require-*-before-stop` ينفذ) — وهو **أيضاً** مصدر تدقيق غير متصل. Factory Droid (`droid`) يثبّت مع `--cli factory` (رطاق مستخدم + مشروع) وهو **أيضاً** مصدر تدقيق غير متصل. Devin CLI (`devin`، Cognition) يثبّت مع `--cli devin` (رطاق مستخدم + مشروع) وهو **أيضاً** مصدر تدقيق غير متصل. Antigravity CLI (`agy`) يثبّت مع `--cli antigravity` (رطاق مستخدم + مشروع) وهو **أيضاً** مصدر تدقيق غير متصل. Goose (codename goose، Block) يثبّت مع `--cli goose` (رطاق مستخدم + مشروع) — المثبّت يضع دليل plugin في `~/.agents/plugins/failproofai/` الذي يكتشفه Goose تلقائياً، وهو **أيضاً** مصدر تدقيق غير متصل. + دعم GitHub Copilot CLI و Cursor Agent و OpenCode و Pi متاح في نسخة **تجريبية** — ثبّت باستخدام `--cli copilot` أو `--cli cursor` أو `--cli opencode` أو `--cli pi`. يثبّت Hermes (hermes-agent، بوابة Slack/Telegram) في نطاق المستخدم باستخدام `--cli hermes` وهو **أيضاً** مصدر تدقيق غير متصل. يثبّت OpenClaw (بوابة openclaw، مساعد متعدد القنوات ذاتي الاستضافة) في نطاق المستخدم باستخدام `--cli openclaw` — يعمل الإنفاذ عبر hooks البرنامج الإضافي داخل العملية (`before_agent_finalize` هو بوابة نهاية دور حقيقية، لذا تطبقها `require-*-before-stop` المدمجة) — وهو **أيضاً** مصدر تدقيق غير متصل. يثبّت Factory Droid (`droid`) باستخدام `--cli factory` (نطاق المستخدم والمشروع) وهو **أيضاً** مصدر تدقيق غير متصل. يثبّت Devin CLI (`devin`، Cognition) باستخدام `--cli devin` (نطاق المستخدم والمشروع) وهو **أيضاً** مصدر تدقيق غير متصل. يثبّت Antigravity CLI (`agy`) باستخدام `--cli antigravity` (نطاق المستخدم والمشروع) وهو **أيضاً** مصدر تدقيق غير متصل. يثبّت Goose (اسم رمزي goose، Block) باستخدام `--cli goose` (نطاق المستخدم والمشروع) — يضع المثبّت فقط مجلد برنامج إضافي في `~/.agents/plugins/failproofai/` يكتشفه Goose تلقائياً، وهو **أيضاً** مصدر تدقيق غير متصل. ```bash failproofai policies --install --scope project @@ -57,61 +58,61 @@ bun add -g failproofai failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` - + ```bash failproofai policies ``` - يعرض كل سياسة وما إذا كانت مفعّلة وأي معاملات مكونة. + يعرض كل سياسة، وما إذا كانت مفعّلة، وأي معاملات مُعدّة. - + ```bash failproofai ``` - يفتح لوحة تحكم محلية في `http://localhost:8020` حيث يمكنك تصفح الجلسات والتفتيش على استدعاءات الأدوات وإدارة السياسات. + يفتح لوحة تحكم محلية على `http://localhost:8020` حيث يمكنك تصفح الجلسات وفحص استدعاءات الأدوات وإدارة السياسات. - - ابدأ Claude Code كالمعتاد. إذا حاول الوكيل فعل شيء محفوف بالمخاطر، فإن failproofai يعترضه تلقائياً. اتركه يعمل بلا مراقبة وراجع ما حدث في لوحة التحكم. + + شغّل Claude Code كالمعتاد. إذا حاول الوكيل شيئاً محفوفاً بالمخاطر، يعترضه failproofai تلقائياً. اتركه يعمل دون حضورك واستعرض ما حدث في لوحة التحكم. --- -## كيفية عمل السياسات +## كيف تعمل السياسات -في كل مرة يشغّل الوكيل أداة، يستدعي Claude Code failproofai كعملية فرعية: +في كل مرة يُشغّل الوكيل أداة، يستدعي Claude Code failproofai كعملية فرعية: ```text -Claude Code → failproofai --hook PreToolUse → قراءة JSON من stdin - تقييم السياسات - كتابة القرار إلى stdout +Claude Code → failproofai --hook PreToolUse → يقرأ JSON من stdin + يقيّم السياسات + يكتب القرار إلى stdout ``` -تعود كل سياسة بأحد ثلاثة قرارات: +تُرجع كل سياسة واحداً من ثلاثة قرارات: -- **allow** - يستمر الوكيل بشكل طبيعي -- **deny** - يتم حظر الإجراء، يتم إخبار الوكيل السبب -- **instruct** - يتم إضافة سياق إضافي إلى مخطط الوكيل +- **allow** - يمضي الوكيل بشكل طبيعي +- **deny** - يُحظر الإجراء، يُخبر النظام الوكيل بالسبب +- **instruct** - يُضاف سياق إضافي إلى موجّه الوكيل -السياسات تعمل في عمليتك المحلية. لا يتم إرسال أي شيء إلى خدمة بعيدة. +تعمل السياسات في عمليتك المحلية. لا يُرسل أي شيء إلى خدمة بعيدة. --- -## إعداد سياسات فريق مع السياسات القائمة على الاتفاقية +## إعداد سياسات الفريق باستخدام السياسات المستندة إلى الاتفاقية -الطريقة الأسرع لإنشاء معايير جودة عبر فريقك هي اتفاقية `.failproofai/policies/`. أسقط ملفات السياسات في هذا الدليل وسيتم تحميلها تلقائياً — بدون أعلام، بدون تغييرات في الإعدادات، بدون أوامر تثبيت. +أسرع طريقة لوضع معايير الجودة عبر فريقك هي اتفاقية `.failproofai/policies/`. ضع ملفات السياسة في هذا المجلد وسيتم تحميلها تلقائياً — بدون أعلام، بدون تغييرات إعدادات، بدون أوامر تثبيت. - + ```bash mkdir -p .failproofai/policies ``` - - انسخ أمثلة المبتدئين أو اكتب الخاصة بك: + + انسخ أمثلة البداية أو اكتب خاصتك: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -136,18 +137,18 @@ Claude Code → failproofai --hook PreToolUse → قراءة JSON من stdin }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - كل عضو في الفريق لديه failproofai مثبتاً يختار هذه السياسات تلقائياً. لا توجد حاجة إلى إعداد لكل مطور. + كل عضو في الفريق لديه failproofai مثبّت سيختار هذه السياسات تلقائياً. لا حاجة لإعداد لكل مطوّر. -التزم بـ `.failproofai/policies/` لمستودعك حتى يشارك الفريق بأكمله نفس المعايير. مع اكتشاف فريقك لأنماط فشل جديدة، أضف سياسات وادفع — يحصل الجميع على التحديث في `git pull` التالي لهم. بمرور الوقت، تصبح هذه السياسات معياراً جودة حياً يستمر في التحسن. +التزم `.failproofai/policies/` مع مستودعك لمشاركة نفس المعايير عبر الفريق. مع اكتشاف فريقك لأنماط فشل جديدة، أضف سياسات وادفع — سيحصل الجميع على التحديث عند `git pull` التالي. بمرور الوقت تصبح هذه السياسات معياراً جودة حياً يتحسّن باستمرار. --- @@ -156,13 +157,15 @@ Claude Code → failproofai --hook PreToolUse → قراءة JSON من stdin تبقى جميع الإعدادات والسجلات على جهازك: -| المسار | ما يخزنه | -|------|----------| -| `~/.failproofai/policies/local-policies/policies-config.json` | إعداد السياسة العام | -| `~/.failproofai/hook-activity/` | سجل تنفيذ Hook (JSONL مقسّم) | +| المسار | ما يخزّنه | +|--------|---------| +| `~/.failproofai/policies-config.json` | إعدادات السياسة العامة | +| `~/.failproofai/policies/` | سياساتك الخاصة — ضع `*-policies.mjs` بدون حاجة لإعداد | +| `~/.failproofai/policies/cloud-policies/` | السياسات المُنشّرة على هذا الجهاز من قبل منظمتك | +| `~/.failproofai/hook-activity/` | سجل تنفيذ hook (JSONL مُقسّم) | | `~/.failproofai/logs/` | سجلات تصحيح لأخطاء hook المخصصة | -| `.failproofai/policies-config.json` | إعداد لكل مشروع (ملتزم) | -| `.failproofai/policies-config.local.json` | التجاوزات الشخصية (مُدرج في gitignore) | +| `.failproofai/policies-config.json` | إعدادات لكل مشروع (مُلتزمة) | +| `.failproofai/policies-config.local.json` | التجاوزات الشخصية (مُتجاهلة git) | --- @@ -172,7 +175,7 @@ Claude Code → failproofai --hook PreToolUse → قراءة JSON من stdin failproofai policies --uninstall ``` -يزيل مدخلات hook من `~/.claude/settings.json`. ملفات الإعدادات في `~/.failproofai/` محتفظ بها. +يزيل مدخلات hook من `~/.claude/settings.json`. تُحتفظ ملفات الإعدادات في `~/.failproofai/`. --- @@ -181,11 +184,11 @@ failproofai policies --uninstall - الأنطقة وصيغة ملف الإعدادات + النطاقات وتنسيق ملف الإعدادات - جميع السياسات الـ 26 مع المعاملات + جميع 26 سياسة مع المعاملات diff --git a/docs/ar/introduction.mdx b/docs/ar/introduction.mdx index 96ecc271..c239f26f 100644 --- a/docs/ar/introduction.mdx +++ b/docs/ar/introduction.mdx @@ -1,37 +1,36 @@ --- ---- title: "Failproof AI" -description: "FailproofAI يعطي وكلاء الذكاء الاصطناعي 39 سياسة فشل مدمجة تمسك الحلقات والتسريبات السرية واستدعاءات الأدوات المدمرة والمزيد في تثبيت واحد." +description: "FailproofAI يمنح وكلاء الذكاء الاصطناعي 39 سياسة فشل مدمجة تلتقط الحلقات والتسريبات السرية والاستدعاءات الأداة المدمرة والمزيد في تثبيت واحد." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -خطاطيف وسياسات لـ **معالجة فشل الذكاء الاصطناعي** و **استرجاع الأخطاء** و **موثوقية نموذج اللغة الكبير**. حافظ على موثوقية وكلاء الذكاء الاصطناعي لديك وتشغيلهم بشكل مستقل عبر **Claude Code** و **OpenAI Codex** و **GitHub Copilot** و **Cursor Agent** و **OpenCode** و **Pi** و **Hermes** و **OpenClaw** و **Factory Droid** و **Devin CLI** و **Antigravity CLI** و **Agents SDK**. +خطافات وسياسات لـ **معالجة فشل الذكاء الاصطناعي**، **استعادة الأخطاء**، و **موثوقية نماذج اللغة الكبيرة**. حافظ على موثوقية وكلاء الذكاء الاصطناعي الخاصة بك وتشغيلهم بشكل مستقل عبر **Claude Code**، **OpenAI Codex**، **GitHub Copilot**، **Cursor Agent**، **OpenCode**، **Pi**، **Hermes**، **OpenClaw**، **Factory Droid**، **Devin CLI**، **Antigravity CLI**، و **Agents SDK**. -وكلاء الذكاء الاصطناعي يفشلون بطرق يمكن التنبؤ بها. يقومون بتشغيل أوامر مدمرة وتسريب الأسرار والانجراف خارج المهمة والعلق في حلقات أو الدفع مباشرة إلى الفرع الرئيسي. إذا تركت دون مراقبة، فإن الأعطال الصغيرة تتسبب في انقطاعات وتسريب بيانات الاعتماد وفقدان العمل. +وكلاء الذكاء الاصطناعي يفشلون بطرق يمكن التنبؤ بها. يقومون بتشغيل الأوامر المدمرة، أو تسريب الأسرار، أو الانجراف عن المهمة، أو الوقوع في حلقات، أو الدفع مباشرة إلى الفرع الرئيسي. عند تركها بدون مراقبة، تتحول الأخطاء الصغيرة إلى انقطاعات خدمة وتسريبات بيانات اعتماد وفقدان الأعمال. -يحل FailproofAI هذه المشكلة باستخدام **السياسات**. هذه القواعد تتصل بكل استدعاء أداة وكيل لـ **كشف الأعطال** و **تخفيفها** (الحجب أو التعليم أو التنظيف) و **تنبيهك** عند الحاجة إلى الاهتمام. يسمح لك لوحة تحكم محلية بمراجعة كل استدعاء أداة وعطل وكيل وإجراء استرجاع لاحقاً. +يحل FailproofAI هذه المشكلة باستخدام **السياسات**. هذه القواعد تندمج في كل استدعاء أداة وكيل لـ **اكتشاف الأخطاء**، **التخفيف من آثارها** (حظر، توجيه، تنظيف)، و **تنبيهك** عند الحاجة إلى اهتمام. تسمح لك لوحة التحكم المحلية بمراجعة كل استدعاء أداة وفشل وكيل وإجراء استعادة بعد ذلك. -النصوص وتقييم السياسة يبقى على جهازك. يتم إرسال البيانات فقط عند استخدامك صراحة لميزة متصلة بالإنترنت، مثل تذكيرات التدقيق المصرح بها أو الدعوات. +النصوص وتقييم السياسات تبقى على جهازك. يتم إرسال البيانات فقط عندما تستخدم بشكل صريح ميزة عبر الإنترنت، مثل تذكيرات التدقيق المصرح بها أو الدعوات. -## ابدأ الآن +## البدء السريع - احجب الأوامر المدمرة ومنع تسريب الأسرار وأبقِ الوكلاء داخل حدود المشروع والمزيد. كل شيء جاهز للاستخدام. + احظر الأوامر المدمرة، منع تسرب الأسرار، احبس الوكلاء داخل حدود المشروع، والمزيد. كل ذلك خارج الصندوق. - اكتب قواعدك الخاصة في JavaScript باستخدام واجهة برمجية سهلة allow / deny / instruct. + اكتب قواعدك الخاصة في JavaScript باستخدام واجهة برمجة تطبيقات بسيطة allow / deny / instruct. - شاهد ما فعله وكلاؤك بينما كنت بعيداً. تصفح الجلسات وفتش استدعاءات الأدوات واستعرض المكان الذي تم تفعيل السياسات فيه. + شاهد ما فعله وكلاؤك بينما كنت بعيداً. استعرض الجلسات، فتش استدعاءات الأداة، راجع المكان الذي أطلقت فيه السياسات. - - اضبط أي سياسة بدون كود. عيّن قوائم السماح أو الفروع المحمية أو عتبات لكل مشروع أو عام. + + اضبط أي سياسة بدون كود. اضبط قوائم السماح المحمية أو الفروع المحمية أو العتبات حسب المشروع أو عالمياً. @@ -51,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # فعّل السياسات (أو تخطَّ — `failproofai` سيعرض عليك الإعداد عند التشغيل الأول) -failproofai # شغّل لوحة التحكم +failproofai policies --install # تفعيل السياسات (أو تخطي — سيعرض `failproofai` عليك إعدادها عند التشغيل الأول) +failproofai # إطلاق لوحة التحكم ``` -انظر إلى دليل [ابدأ الآن](/ar/getting-started) للحصول على المسار الكامل. \ No newline at end of file +انظر إلى دليل [البدء السريع](/ar/getting-started) للحصول على الشرح الكامل. \ No newline at end of file diff --git a/docs/ar/package-aliases.mdx b/docs/ar/package-aliases.mdx index 5f669e73..adfe35ff 100644 --- a/docs/ar/package-aliases.mdx +++ b/docs/ar/package-aliases.mdx @@ -1,7 +1,7 @@ --- --- title: اسم الحزم المستعارة -description: "الأسماء المستعارة المسجلة لمنع محاولات الاستيلاء على الأسماء وكيفية عملها" +description: "الأسماء المستعارة المسجلة لمنع الهجمات وكيفية عملها" icon: copy --- @@ -17,17 +17,17 @@ bun add -g failproofai --- -## لماذا نملك أسماء الاستعارات +## لماذا نمتلك أسماء الأسماء المستعارة -محاولات الاستيلاء على الأسماء هي هجوم شائع على سلسلة التوريد، حيث يسجل ممثل خطر اسم حزمة يبعد ضغطة واحدة فقط عن حزمة شهيرة. المستخدمون غير المتنبهون الذين يخطئون في كتابة أمر التثبيت ينتهي بهم الحال بتشغيل كود يسيطر عليه المهاجم بصلاحيات وصول كاملة للنظام - تماماً نوع التهديد الذي صُمم Failproof AI للدفاع ضده. +هجوم الاستخفاف بالنطاق (Typosquatting) هو هجوم شائع على سلسلة التوريد حيث يقوم جهة فاعلة خبيثة بتسجيل اسم حزمة يبعد ضغطة واحدة فقط عن حزمة شهيرة. المستخدمون غير المدركين الذين يخطئون في كتابة أمر التثبيت ينتهي بهم الحال إلى تشغيل كود يتحكم به المهاجم مع وصول كامل للنظام - وهذا هو بالضبط نوع التهديد الذي صُمم Failproof AI للدفاع ضده. -لإزالة هذا الثغرة، **نملك مسبقاً جميع الأخطاء الإملائية والمتغيرات الشكلية الشائعة** لـ `failproofai` على npm. لا يمكن لأي طرف ثالث تسجيل أي من هذه الأسماء. كل واحد منها هو وكيل بسيط يثبت ويفوض إلى حزمة `failproofai` الحقيقية. +لإزالة هذا السطح الهجومي، **نحن نمتلك مسبقاً جميع الأخطاء الإملائية الشائعة والمتغيرات المختلفة** لاسم `failproofai` على npm. لا يمكن لأي طرف ثالث تسجيل أي من هذه الأسماء. كل واحد منها عبارة عن وكيل بسيط يقوم بتثبيت وتفويض العمل إلى حزمة `failproofai` الحقيقية. --- ## الأسماء المستعارة المسجلة -**متغيرات الصيغة** - طرق مختلفة لكتابة "failproof ai": +**متغيرات التنسيق** - طرق مختلفة لكتابة "failproof ai": | الحزمة | الحالة | |---------|--------| @@ -38,7 +38,7 @@ bun add -g failproofai | `fail_proof_ai` | ⏳ قيد انتظار دعم npm | | `fail-proofai` | ⏳ قيد انتظار دعم npm | -**أخطاء `failprof*`** - حرف `o` واحد ناقص من "proof": +**أخطاء `failprof*`** - حرف `o` واحد ناقص من كلمة "proof": | الحزمة | الحالة | |---------|--------| @@ -48,7 +48,7 @@ bun add -g failproofai | `fail-prof-ai` | ⏳ قيد انتظار دعم npm | | `failprof_ai` | ⏳ قيد انتظار دعم npm | -**أخطاء `faliproof*`** - حروف `a` و `i` مبدلة: +**أخطاء `faliproof*`** - الحروف `a` و `i` مقلوبة: | الحزمة | الحالة | |---------|--------| @@ -56,28 +56,28 @@ bun add -g failproofai | `faliproof-ai` | ✅ منشورة | | `faliproofai` | ⏳ قيد انتظار دعم npm | -> **لماذا قيد الانتظار؟** سياسة منع البريد العشوائي في npm تحظر الأسماء التي تتطبع على نفس السلسلة مثل حزمة موجودة بعد إزالة الترقيم وإجراء فحوصات التشابه. لقد تواصلنا مع دعم npm لحجز هذه الأسماء لأغراض مكافحة الاستيلاء على الأسماء. سيتم تفعيلها بمجرد الموافقة عليها. +> **لماذا قيد الانتظار؟** تمنع سياسة منع البريد العشوائي في npm الأسماء التي تُعتبر مطابقة لحزمة موجودة بعد إزالة علامات الترقيم وإجراء فحوصات التشابه. لقد تواصلنا مع فريق دعم npm لحجز هذه الأسماء لأغراض منع الاستخفاف. سيتم تفعيلها بمجرد الموافقة. -يمكنك التحقق من أن أي اسم مستعار منشور يملكه لنا: +يمكنك التحقق من أن أي اسم مستعار منشور يمتلكه: ```bash npm info failproof -# ابحث عن: "ExosphereHost Inc." في حقل المسؤولين +# ابحث عن: "ExosphereHost Inc." في حقل maintainers ``` --- -## كيفية عمل الأسماء المستعارة +## كيف تعمل الأسماء المستعارة كل حزمة مستعارة: -1. تدرج `failproofai` كاعتماد - لذا يتم تثبيت الحزمة الحقيقية وتصبح ملفاتها التنفيذية متاحة -2. تعرض ملف تنفيذي يطابق اسمها الخاص (مثل `failprof-ai`) يوكل جميع المعاملات إلى ملف `failproofai` التنفيذي +1. تسرد `failproofai` كتبعية - بحيث يتم تثبيت الحزمة الحقيقية ويصبح ملفها التنفيذي متاحاً +2. تعرّض ملفاً تنفيذياً يطابق اسمها الخاص (مثل `failprof-ai`) يوجه جميع الوسيطات إلى الملف التنفيذي `failproofai` -الوكيل هو سكريبت Node من سطرين؛ لا توجد منطق، لا توجد استدعاءات شبكية، ولا جمع بيانات بخلاف ما يقوم به `failproofai` نفسه. +الوكيل عبارة عن نص Node من سطرين؛ لا توجد منطق، ولا استدعاءات شبكة، ولا جمع بيانات خارج ما تفعله `failproofai` نفسها. --- -## إذا وجدت اسماً لم نسجله +## إذا وجدت اسماً فاتنا افتح مشكلة في [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) وسنقوم بتسجيله. \ No newline at end of file diff --git a/docs/ar/testing.mdx b/docs/ar/testing.mdx index b2169e0c..cbbbb501 100644 --- a/docs/ar/testing.mdx +++ b/docs/ar/testing.mdx @@ -1,26 +1,27 @@ --- +--- title: الاختبار -description: "اختبارات الوحدة واختبارات end-to-end ومساعدات الاختبار" +description: "اختبارات الوحدات واختبارات التكامل الشاملة ومساعدات الاختبار" icon: flask-vial --- -failproofai يحتوي على مجموعتي اختبار: **اختبارات الوحدة** (سريعة، محاكاة) و**اختبارات end-to-end** (استدعاءات عمليات فعلية). +failproofai لديه مجموعتان من الاختبارات: **اختبارات الوحدات** (سريعة، محاكاة) و**اختبارات التكامل الشاملة** (استدعاءات subprocess حقيقية). --- ## تشغيل الاختبارات ```bash -# تشغيل جميع اختبارات الوحدة مرة واحدة +# تشغيل جميع اختبارات الوحدات مرة واحدة bun run test:run -# تشغيل اختبارات الوحدة في وضع المراقبة +# تشغيل اختبارات الوحدات في وضع المراقبة bun run test -# تشغيل اختبارات E2E (يتطلب إعداد - انظر أدناه) +# تشغيل اختبارات التكامل الشاملة (يتطلب إعدادًا - انظر أدناه) bun run test:e2e -# التحقق من النوع دون البناء +# التحقق من النوع بدون البناء bunx tsc --noEmit # فحص الكود @@ -29,9 +30,9 @@ bun run lint --- -## اختبارات الوحدة +## اختبارات الوحدات -تقع اختبارات الوحدة في `__tests__/` وتستخدم [Vitest](https://vitest.dev) مع `jsdom`. +اختبارات الوحدات موجودة في `__tests__/` وتستخدم [Vitest](https://vitest.dev) مع `jsdom`. ```text __tests__/ @@ -39,12 +40,12 @@ __tests__/ builtin-policies.test.ts # منطق السياسة لكل سياسة مدمجة hooks-config.test.ts # تحميل الإعدادات ودمج النطاق policy-evaluator.test.ts # حقن المعاملات وترتيب التقييم - custom-hooks-registry.test.ts # إضافة/الحصول/مسح السجل العام - custom-hooks-loader.test.ts # محمل ESM، الاستيراد المتعدي، معالجة الأخطاء - manager.test.ts # عمليات التثبيت/الإزالة/القائمة + custom-hooks-registry.test.ts # سجل globalThis للإضافة والحصول والمسح + custom-hooks-loader.test.ts # محمل ESM والاستيرادات المتكررة ومعالجة الأخطاء + manager.test.ts # عمليات التثبيت والإزالة والقائمة components/ sessions-list.test.tsx # مكون قائمة الجلسات - project-list.test.tsx # مكون قائمة المشاريع + project-list.test.tsx # مكون قائمة المشروع ... lib/ logger.test.ts @@ -61,7 +62,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### كتابة اختبار وحدة سياسة +### كتابة اختبار وحدة للسياسة ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -108,13 +109,13 @@ describe("block-sudo", () => { --- -## اختبارات end-to-end +## اختبارات التكامل الشاملة -تستدعي اختبارات E2E الثنائي الحقيقي `failproofai` كعملية فرعية، وتوجه حمولة JSON إلى stdin، وتؤكد على مخرجات stdout وكود الخروج. يختبر هذا مسار التكامل الكامل الذي يستخدمه Claude Code. +اختبارات التكامل الشاملة تستدعي ثنائي `failproofai` الحقيقي كـ subprocess وتنقل حمولة JSON إلى stdin وتتأكد من مخرجات stdout وكود الخروج. هذا يختبر مسار التكامل الكامل الذي يستخدمه Claude Code. ### الإعداد -تشغل اختبارات E2E الثنائي مباشرة من مصدر المستودع. قبل التشغيل الأول، قم بناء حزمة CJS التي تستخدمها ملفات الخطاف المخصص عند استيرادها من `'failproofai'`: +اختبارات التكامل الشاملة تشغل الثنائي مباشرة من مصدر المستودع. قبل التشغيل الأول، بناء حزمة CJS التي تستخدمها ملفات Hook المخصصة عند الاستيراد من `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,24 +127,24 @@ bun build src/index.ts --outdir dist --target node --format cjs bun run test:e2e ``` -أعد بناء `dist/` في أي وقت تغير فيه API خطاف عام (`src/hooks/custom-hooks-registry.ts`، `src/hooks/policy-helpers.ts`، أو `src/hooks/policy-types.ts`). +أعد بناء `dist/` في كل مرة تقوم فيها بتغيير واجهة برمجة التطبيقات العامة للـ Hook (`src/hooks/custom-hooks-registry.ts` أو `src/hooks/policy-helpers.ts` أو `src/hooks/policy-types.ts`). -### هيكل اختبار E2E +### هيكل اختبار التكامل الشامل ```text __tests__/e2e/ helpers/ - hook-runner.ts # توليد الثنائي، توجيه JSON الحمولة، التقاط كود الخروج + stdout + stderr - fixture-env.ts # بيئات مؤقتة معزولة لكل اختبار مع ملفات الإعدادات - payloads.ts # مصانع حمولة دقيقة Claude لكل نوع حدث + hook-runner.ts # تشغيل الثنائي، نقل حمولة JSON، التقاط كود الخروج والمخرجات والأخطاء + fixture-env.ts # دلائل مؤقتة معزولة لكل اختبار مع ملفات الإعدادات + payloads.ts # مصانع حمولة دقيقة لـ Claude لكل نوع حدث hooks/ - builtin-policies.e2e.test.ts # كل سياسة مدمجة مع عملية فرعية حقيقية - custom-hooks.e2e.test.ts # تحميل ودمج الخطاف المخصص - config-scopes.e2e.test.ts # دمج الإعدادات عبر المشروع/المحلي/العام + builtin-policies.e2e.test.ts # كل سياسة مدمجة مع subprocess حقيقي + custom-hooks.e2e.test.ts # تحميل وتقييم Hook مخصص + config-scopes.e2e.test.ts # دمج الإعدادات عبر المشروع والمحلي والعام policy-params.e2e.test.ts # حقن المعاملات لكل سياسة ذات معاملات ``` -### استخدام مساعدات E2E +### استخدام مساعدات التكامل الشامل **`FixtureEnv`** - بيئة معزولة لكل اختبار: @@ -151,8 +152,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - مجلد مؤقت؛ مرره كـ payload.cwd لالتقاط .failproofai/policies-config.json -// env.home - مجلد منزل معزول؛ لا توجد تسريبات حقيقية من ~/.failproofai +// env.cwd - دليل مؤقت؛ مرره كـ payload.cwd لاختيار .failproofai/policies-config.json +// env.home - دليل منزل معزول؛ لا تسرب حقيقي لـ ~/.failproofai env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +163,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` يسجل تنظيف `afterEach` تلقائيًا. +`createFixtureEnv()` يسجل `afterEach` تنظيف تلقائيًا. -**`runHook`** - استدع الثنائي: +**`runHook`** - استدعاء الثنائي: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -192,7 +193,7 @@ Payloads.notification(message, cwd) Payloads.stop(cwd) ``` -### كتابة اختبار E2E +### كتابة اختبار تكامل شامل ```typescript import { describe, it, expect } from "vitest"; @@ -226,35 +227,35 @@ describe("block-rm-rf (E2E)", () => { ); expect(result.exitCode).toBe(0); - expect(result.stdout).toBe(""); // السماح → stdout فارغ + expect(result.stdout).toBe(""); // allow → empty stdout }); }); ``` -### أشكال استجابة E2E +### أشكال استجابة التكامل الشامل | القرار | كود الخروج | stdout | |----------|-----------|--------| -| `PreToolUse` رفض | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | -| `PostToolUse` رفض | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| تعليمات (غير Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| تعليمات Stop | `2` | stdout فارغ؛ السبب في stderr | -| السماح | `0` | سلسلة فارغة | +| `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 فارغ؛ السبب في stderr | +| Allow | `0` | سلسلة فارغة | -### إعدادات Vitest +### تكوين Vitest -تستخدم اختبارات E2E `vitest.config.e2e.mts` مع: +اختبارات التكامل الشامل تستخدم `vitest.config.e2e.mts` مع: -- `environment: "node"` - لا توجد متغيرات عام المتصفح المطلوبة -- `pool: "forks"` - عزل عملية حقيقي (توليد الاختبارات للعمليات الفرعية) -- `testTimeout: 20_000` - 20ث لكل اختبار (بدء الثنائي + تقييم الخطاف) +- `environment: "node"` - لا حاجة لمتغيرات المتصفح العام +- `pool: "forks"` - عزل عملية حقيقي (الاختبارات تشغل subprocesses) +- `testTimeout: 20_000` - 20 ثانية لكل اختبار (بدء الثنائي وتقييم Hook) -حزمة `forks` مهمة: العاملين القائمين على الخيوط يشاركون `globalThis`، مما قد يتداخل مع اختبارات التوليد الفرعي. عمليات forks تتجنب هذا. +حمام `forks` مهم: العمال القائمة على الخيوط تشارك `globalThis`، مما قد يتداخل مع اختبارات تشغيل subprocess. الـ forks القائمة على العملية تتجنب هذا. --- ## CI -يتطلب التشغيل الكامل للـ CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) أن يمر قبل الدمج. تشغل مجموعة E2E كمهمة CI منفصلة بالتوازي. +التشغيل الكامل للـ CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) مطلوب للنجاح قبل الدمج. مجموعة الاختبارات الشاملة تعمل كمهمة CI منفصلة بالتوازي. -انظر [المساهمة](../CONTRIBUTING.md) للحصول على قائمة التحقق الكاملة قبل الدمج. \ No newline at end of file +انظر [Contributing](../CONTRIBUTING.md) للقائمة الكاملة بالتحقق قبل الدمج. \ No newline at end of file diff --git a/docs/de/agenteye/alerts.mdx b/docs/de/agenteye/alerts.mdx index 4a2b39b6..64a3a374 100644 --- a/docs/de/agenteye/alerts.mdx +++ b/docs/de/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "Alerts" -description: "Erfahre sofort, wenn etwas deine Grenze überschreitet – auf dem Kanal, den dein Team bereits nutzt, statt es von einem Kunden zu hören." +description: "Erfahre sofort, wenn eine Grenze überschritten wird – im Kanal, den dein Team bereits nutzt – statt es von einem Kunden zu hören." --- -Erfahre sofort, wenn etwas deine Grenze überschreitet – auf dem Kanal, den dein Team bereits nutzt, statt es von einem Kunden zu hören. Lege eine Regel einmal fest, und Failproof AI Observability prüft sie nach einem Zeitplan und benachrichtigt dich per E-Mail, Slack, Webhook oder direkt im Dashboard. +Erfahre sofort, wenn eine Grenze überschritten wird – im Kanal, den dein Team bereits nutzt – statt es von einem Kunden zu hören. Lege eine Regel einmal fest, und Failproof AI Observability prüft sie im festgelegten Intervall und benachrichtigt dich per E-Mail, Slack, Webhook oder direkt im Dashboard. -![Die Alerts-Seite: ein Raster mit Alert-Regelkarten, jede mit ihrem Auslöser, dem Auswertungsfenster, den Kanälen und einem Info-, Warn- oder Kritisch-Schweregrad-Badge](/agenteye/images/alerts.png) +![Die Alerts-Seite: ein Raster aus Alert-Regelkarten, jede mit Auslöser, Auswertungsfenster, Kanälen und einem Info-, Warn- oder Kritisch-Schweregrad-Badge](/agenteye/images/alerts.png) *Alle Alert-Regeln auf einen Blick: was überwacht wird, wie oft, wohin benachrichtigt wird und wie dringend.* ## Erfahre von Problemen, bevor deine Nutzer es tun -Höre auf, ein Dashboard zu aktualisieren und auf eine Regression zu hoffen. Richte einen Alert ein, wann immer es ein Signal gibt, über das du informiert werden möchtest – auch wenn niemand hinschaut –, und lass ihn dort ankommen, wo du sowieso bist: +Hör auf, ein Dashboard zu aktualisieren und auf eine Regression zu warten. Nutze einen Alert für jedes Signal, über das du informiert werden möchtest – auch wenn niemand hinschaut –, und lass ihn dort ankommen, wo du ohnehin bist: -- **E-Mail**, an alle, die es wissen sollten. -- **Slack**, eine aussagekräftige Nachricht mit einer Schaltfläche, die direkt zum Vorfall führt. -- **Webhook**, ein JSON-POST für PagerDuty, Opsgenie oder deinen eigenen Endpunkt, optional mit Signatur, damit der Empfänger die Echtheit prüfen kann. -- **Im Dashboard**, von Haus aus dezent – für den Fall, dass du eine Regel feinjustierst und noch niemanden benachrichtigen möchtest. +- **E-Mail**, an alle, die es wissen müssen. +- **Slack**, als aussagekräftige Nachricht mit einem Button, der direkt zum Vorfall führt. +- **Webhook**, ein JSON-POST für PagerDuty, Opsgenie oder deinen eigenen Endpunkt, optional mit Signatur, damit der Empfänger die Herkunft verifizieren kann. +- **Im Dashboard**, bewusst unauffällig – für Situationen, in denen du eine Regel einstellst und noch niemanden benachrichtigen möchtest. -Kombiniere beliebige dieser Optionen für eine einzige Regel. Der Schweregrad (Info, Warnung oder Kritisch) wird dabei immer mitgeliefert, damit dringende Meldungen auch dringend wirken. +Kombiniere beliebige Kanäle für eine einzelne Regel. Der Schweregrad (Info, Warnung oder Kritisch) wird dabei immer mitgeliefert, sodass dringende Alerts auch dringend wirken. ## Regeln per Formular erstellen, nicht per JSON -Du beschreibst, was „kaputt" bedeutet, in einem Formular, und Failproof AI Observability erstellt die zugrundeliegende Regel für dich. Die JSON-Spezifikation ist lediglich das, was dieses Formular intern erzeugt – du kannst sie lesen, um eine Regel zu verstehen, aber tippst sie selten manuell ein. +Du beschreibst im Formular, was „kaputt" bedeutet, und Failproof AI Observability generiert die zugrundeliegende Regel. Die JSON-Spezifikation ist lediglich das, was das Formular im Hintergrund erzeugt – du kannst sie lesen, um eine Regel zu verstehen, musst sie aber kaum selbst schreiben. -![Das Formular für neue Alerts: Name und Beschreibung, ein Aktivierungsschalter und eine Auslöserauswahl mit Metrikschwellenwert, benutzerdefiniertem SQL, Auswertungsscore, zusammengesetzter Auswertung und ereignisbezogenen Bedingungen](/agenteye/images/alert-new.png) -*Wähle einen Auslöser und das Formular zeigt die richtigen Felder an; Speichern schreibt die Regel.* +![Das Formular für neue Alerts: Name und Beschreibung, ein Aktivierungsschalter und eine Auslöserauswahl mit Metrikschwellenwert, benutzerdefiniertem SQL, Bewertungsscore, zusammengesetzter Auswertung und ereignisbezogenen Bedingungen](/agenteye/images/alert-new.png) +*Wähle einen Auslöser und das Formular zeigt die passenden Felder an; Speichern schreibt die Regel.* -Der Standardablauf geht schnell: Name vergeben, einen **Auslöser** wählen (was überwacht werden soll), **Schwellenwert und Zeitfenster** festlegen (wie schlimm, über welchen Zeitraum), mindestens einen **Kanal** anhängen, dann **Speichern** und auf **Test** klicken, um eine synthetische Benachrichtigung auszulösen und zu bestätigen, dass jedes Ziel richtig verdrahtet ist. Intern entsteht dabei eine kleine Spezifikation wie: +Der typische Ablauf ist schnell: Gib ihr einen Namen, wähle einen **Auslöser** (was überwacht werden soll), lege **Schwellenwert und Zeitfenster** fest (wie gravierend, über welchen Zeitraum), füge mindestens einen **Kanal** hinzu, klicke dann auf **Speichern** und **Testen**, um eine synthetische Benachrichtigung auszulösen und sicherzustellen, dass alle Ziele korrekt konfiguriert sind. Im Hintergrund entsteht dabei eine kleine Spezifikation wie: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -Du bist nicht auf eine einzige Art von Signal beschränkt. Wähle den Auslöser, der dazu passt, wie du über den Fehler nachdenkst: +Du bist nicht auf eine einzige Art von Signal beschränkt. Wähle den Auslöser, der dazu passt, wie du über den Fehler nachdenken möchtest: | Auslöser | Löst aus, wenn | |---|---| -| **Metrikschwellenwert** | eine voreingestellte Metrik (Fehlerrate, p95- oder p99-Latenz, Ereignis- oder Fehlerzähler, Token-Verbrauch) über ein Zeitfenster deine Grenze überschreitet | -| **Benutzerdefiniertes SQL** | deine eigene schreibgeschützte Abfrage eine Zeile zurückgibt oder ein berechneter Wert einen Schwellenwert überschreitet | -| **Auswertungsscore** | der Durchschnittswert eines Evaluators (z. B. Halluzinierung) einen Schwellenwert überschreitet | -| **Zusammengesetzte Auswertung** | mehrere Score-Prüfungen mit Beliebig-, Alle- oder Mindestens-N-Logik kombiniert werden, um eine Regression zu erkennen, die sich erst über mehrere Scores hinweg zeigt | -| **Pro Ereignis** | ein einzelnes passendes Ereignis eintrifft: ein bestimmter Agent, ein bestimmter Fehlertyp oder ein Nachrichten-Substring | +| **Metrikschwellenwert** | eine vordefinierte Metrik (Fehlerrate, p95- oder p99-Latenz, Ereignis- oder Fehlerzähler, Token-Verbrauch) deine Grenze in einem Zeitfenster überschreitet | +| **Benutzerdefiniertes SQL** | deine eigene lesende Abfrage eine Zeile zurückgibt oder ein berechneter Wert einen Schwellenwert überschreitet | +| **Bewertungsscore** | der Durchschnittswert eines Evaluators (z. B. Halluzination) einen Schwellenwert überschreitet | +| **Zusammengesetzte Auswertung** | mehrere Score-Prüfungen mit any-, all- oder at-least-N-Logik kombiniert werden, um eine Regression zu erkennen, die sich nur über mehrere Scores zeigt | +| **Pro Ereignis** | ein einzelnes passendes Ereignis eintritt: ein bestimmter Agent, ein bestimmter Fehlertyp oder ein Nachrichtentext-Teilstring | -Schaust du gerade auf der [Errors-Seite](/de/agenteye/error-tracking) auf einen Fehler? Jede Zeile dort hat eine **+ Alert**-Schaltfläche, die dieses Formular vorausgefüllt öffnet, um genau diesen Fehler beim nächsten Auftreten abzufangen – damit der Vorfall, den du gerade triagiert hast, beim nächsten Mal direkt eine Benachrichtigung auslöst. +Schaust du bereits auf der [Fehler-Seite](/de/agenteye/error-tracking) auf einen Fehler? Jede Zeile dort hat einen **+ Alert**-Button, der dieses Formular vorausgefüllt öffnet, um genau diesen Fehler beim nächsten Mal abzufangen. So wird der gerade triagierte Vorfall zum nächsten, der dich benachrichtigt. -**Wo du es findest:** Alerts befinden sich unter `//alerts`. Zum Erstellen, Bearbeiten, Löschen und Testen von Regeln wird **`alerts:write`** benötigt; `alerts:read` reicht zum Anschauen. Die Empfängerauswahl listet die Mitglieder deiner Organisation namentlich auf, sodass du eine Person benachrichtigen kannst, ohne das Formular zu verlassen. +**Wo du ihn findest:** Alerts befinden sich unter `//alerts`. Zum Erstellen, Bearbeiten, Löschen und Testen von Regeln wird **`alerts:write`** benötigt; `alerts:read` reicht zum Anzeigen. Die Empfängerauswahl listet die Mitglieder deiner Organisation namentlich auf, sodass du eine Person benachrichtigen kannst, ohne das Formular zu verlassen. -## Benachrichtigungen nur bei echten Problemen +## Nur benachrichtigen, wenn es wirklich relevant ist -Eine einzelne fehlerhafte Messung sollte dich nicht aufwecken. Der **M von N**-Rauschfilter legt fest, wie viele der letzten Prüfungen fehlschlagen müssen, bevor der Alert tatsächlich ausgelöst wird. Stelle ihn auf **3 von 5** ein, und die Regel löst erst aus, nachdem drei der letzten fünf Prüfungen die Grenze überschritten haben – damit ein unstetes Signal aufhört, falschen Alarm zu schlagen. Belasse ihn beim Standardwert **1 von 1**, um beim ersten Verstoß sofort auszulösen. Du wählst außerdem, wie oft die Regel ausgeführt wird – aus Voreinstellungen von 1m, 5m, 15m und 1h, abgestimmt auf die tatsächliche Dynamik des Signals. +Eine einzelne fehlerhafte Messung sollte dich nicht wecken. Der **M-von-N**-Rauschfilter legt fest, wie viele der letzten Prüfungen fehlschlagen müssen, bevor der Alert tatsächlich ausgelöst wird. Stelle ihn auf **3 von 5**, und die Regel löst erst aus, wenn drei der letzten fünf Prüfungen verletzt wurden – ein unstetes Signal hört damit auf, Fehlalarm zu geben. Belasse es beim Standardwert **1 von 1**, um beim ersten Verstoß auszulösen. Du wählst außerdem, wie oft die Regel ausgeführt wird – aus Voreinstellungen von 1m, 5m, 15m und 1h, abgestimmt auf die tatsächliche Änderungsgeschwindigkeit des Signals. ## Was passiert, wenn ein Alert ausgelöst wird -Ein Verstoß öffnet einen **Incident** und benachrichtigt deine Kanäle einmalig. Von dort aus bestätigt dein Team den Vorfall, weist einen Verantwortlichen zu, bespricht ihn und löst ihn auf – alles in einem übersichtlichen, zugeordneten Protokoll. Dieser Triage-Workflow hat seine eigene Seite: siehe [Incidents](/de/agenteye/incidents). +Ein Verstoß öffnet einen **Incident** und benachrichtigt deine Kanäle einmalig. Von dort aus bestätigt dein Team den Vorfall, weist einen Verantwortlichen zu, bespricht ihn und löst ihn auf – alles in einem übersichtlichen, nachvollziehbaren Protokoll. Dieser Triage-Workflow hat seine eigene Seite: siehe [Incidents](/de/agenteye/incidents). -## Verwandte Themen +## Verwandte Seiten -- [Incidents](/de/agenteye/incidents): verfolge einen ausgelösten Alert von offen über bestätigt bis gelöst. -- [Error tracking](/de/agenteye/error-tracking): gruppiere Agent-Fehler und wandle einen mit einem Klick in einen Alert um. +- [Incidents](/de/agenteye/incidents): verfolge einen ausgelösten Alert von offen über bestätigt bis hin zu gelöst. +- [Error Tracking](/de/agenteye/error-tracking): gruppiere Agent-Fehler und überführe einen mit einem Klick in einen Alert. - [Dashboards](/de/agenteye/dashboards): beobachte die gemeinsamen Boards, aus denen die überwachten Schwellenwerte stammen. -- [CLI and agents](/de/agenteye/cli-and-agents): erstelle Alerts und bestätige Incidents über dein Terminal oder integriere sie per Skript in CI. \ No newline at end of file +- [CLI and Agents](/de/agenteye/cli-and-agents): erstelle Alerts und bestätige Incidents aus dem Terminal oder per Skript in CI. \ No newline at end of file diff --git a/docs/de/agenteye/api-keys.mdx b/docs/de/agenteye/api-keys.mdx index b12d5f5a..e5623dd9 100644 --- a/docs/de/agenteye/api-keys.mdx +++ b/docs/de/agenteye/api-keys.mdx @@ -1,106 +1,106 @@ --- title: "API Keys" -description: "API keys steuern, wer und was Ihren Failproof AI Observability-Server erreichen kann – ein Collector kann damit Events senden, ohne jemals Lese- oder Adminrechte zu erhalten." +description: "API Keys steuern, wer und was Ihren Failproof AI Observability-Server erreichen kann, sodass ein Collector Ereignisse senden kann, ohne jemals Lese- oder Adminrechte zu erlangen." --- -API keys steuern, wer und was Ihren Failproof AI Observability-Server erreichen kann – ein Collector kann damit Events senden, ohne jemals Lese- oder Adminrechte zu erhalten. Jeder Key trägt eine oder mehrere Berechtigungen, und jede Berechtigung sichert bestimmte Server-Routen ab; Sie vergeben nur die Berechtigungen, die ein Job tatsächlich benötigt. Die meisten Deployments erstellen lediglich drei Arten von Keys. +API Keys steuern, wer und was Ihren Failproof AI Observability-Server erreichen kann, sodass ein Collector Ereignisse senden kann, ohne jemals Lese- oder Adminrechte zu erlangen. Jeder Key trägt eine oder mehrere Berechtigungen, und jede Berechtigung sichert bestimmte Server-Routen ab; Sie gewähren nur die Berechtigungen, die ein Job benötigt. Die meisten Deployments erstellen lediglich drei Arten von Keys. ## Die 3 Keys, die die meisten Deployments benötigen -| Key | Berechtigungen | Wird verwendet von | +| Key | Berechtigungen | Wer ihn verwendet | |---|---|---| -| Collector-Key | `events:add` | Dem `agenteye-collector` auf jeder Agent-Maschine, um Events zu senden. | -| Dashboard-Leseschlüssel | `events:read`, `keys:read` | Einem Read-only-Operator oder einer Integration, die Daten abfragt, ohne sie zu verändern. | -| Bootstrap-Admin-Key | alle Berechtigungen | Dem Operator, der die Instanz erstmals einrichtet (zusammen mit dem Dashboard). Wird aus der Umgebungsvariable `ADMIN_KEY` befüllt. Siehe [Bootstrap-Admin-Key](#bootstrap-admin-key). | +| Collector-Key | `events:add` | Der `agenteye-collector` auf jeder Agent-Maschine, zum Senden von Ereignissen. | +| Dashboard-Leseschlüssel | `events:read`, `keys:read` | Ein schreibgeschützter Operator oder eine Integration, die Daten abfragt, ohne sie zu ändern. | +| Bootstrap-Admin-Key | alle Berechtigungen | Der Operator, der die Instanz (und das Dashboard) erstmalig in Betrieb nimmt. Wird aus der Umgebungsvariable `ADMIN_KEY` befüllt. Siehe [Bootstrap-Admin-Key](#bootstrap-admin-key). | -Beginnen Sie hier. Den vollständigen Berechtigungskatalog weiter unten benötigen Sie nur, wenn Sie einen enger gefassten, benutzerdefiniert abgegrenzten Key brauchen. Siehe auch [Empfohlenes Key-Layout](#recommended-key-layout) und [Keys erstellen](#creating-keys). +Beginnen Sie hier. Greifen Sie nur dann auf den vollständigen Berechtigungskatalog unten zurück, wenn Sie einen engeren, benutzerdefiniert zugeschnittenen Key benötigen. Siehe auch [Empfohlenes Key-Layout](#recommended-key-layout) und [Keys erstellen](#creating-keys). --- ## Berechtigungen -Der Server erzwingt einen festen Berechtigungskatalog; jede Berechtigung sichert bestimmte HTTP-Routen ab. Ein **Admin-Key** besitzt alle davon; ein scoped Key besitzt die Teilmenge, die Sie bei der Erstellung vergeben. Unbekannte Berechtigungs-Strings werden beim Erstellen eines Keys abgelehnt. +Der Server erzwingt einen festen Katalog von Berechtigungen; jede sichert bestimmte HTTP-Routen ab. Ein **Admin-Key** besitzt alle davon; ein Scoped-Key besitzt die Teilmenge, die Sie bei der Erstellung vergeben. Unbekannte Berechtigungs-Strings werden bei der Key-Erstellung abgelehnt. -> **Hinweis:** Zwei gültige Berechtigungen sind ausschließlich für Menschen/das Dashboard bestimmt und können keinem API-Key zugewiesen werden: `orgs:admin` (Instanz-Administration, die dem Operator vorbehalten ist) und `keys:update`. Eine Anfrage an `POST /keys` oder `PATCH /keys/:id`, die versucht, eine dieser Berechtigungen zu vergeben, wird mit HTTP 422 abgelehnt. Warum ein Bearer-Key zwar Keys erstellen, aber nie bearbeiten darf, erläutert die Zeile zu `keys:update` weiter unten. +> **Hinweis:** Zwei gültige Berechtigungen sind ausschließlich für Menschen/das Dashboard vorgesehen und können keinem API-Key zugewiesen werden: `orgs:admin` (Instanz-Administration, nur für Operatoren) und `keys:update`. Eine Anfrage an `POST /keys` oder `PATCH /keys/:id`, die versucht, eine davon zu vergeben, wird mit HTTP 422 abgelehnt. Warum ein Bearer-Key zwar Keys erstellen, sie aber nie bearbeiten kann, ist in der Zeile `keys:update` unten erklärt. -### Events: Ingest & Abfrage +### Ereignisse: Ingest & Abfrage | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `events:add` | `POST /events` | Batches von Events eines Collectors einlesen. Die einzige Berechtigung, die ein Collector benötigt. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Events abfragen, bekannte Umgebungen auflisten, im Datensatz gesehene Modellbezeichner auflisten (verwendet von der Models-Ansicht und Modellfiltern), das Latenz-Aggregat für die Heatmap/Perzentilband berechnen und eine Session als JSONL exportieren. Die gemeinsamen Filter-Leisten-Facet-Endpunkte `GET /events/environments` und `GET /events/agent_ids` sind sowohl mit `events:read` **als auch** mit `evaluations:read` erreichbar, sodass die Sessions-Seite (gesichert durch `evaluations:read`) dieselbe organisationsweite Facette nutzen kann. `GET /events/models` gehört nicht dazu: es erfordert `events:read`; ein Principal, der nur `evaluations:read` besitzt, erhält einen 403. | +| `events:add` | `POST /events` | Batches von Ereignissen von einem Collector einspielen. Die einzige Berechtigung, die ein Collector benötigt. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Ereignisse abfragen, bekannte Umgebungen auflisten, im Datensatz gesehene Modell-IDs auflisten (verwendet von der Modellansicht und Modellfiltern), das Latenz-Aggregat berechnen, das die Heatmap/Perzentilbandanzeige antreibt, und eine Sitzung als JSONL exportieren. Die gemeinsamen Filter-Bar-Facet-Endpunkte `GET /events/environments` und `GET /events/agent_ids` sind mit **entweder** `events:read` **oder** `evaluations:read` erreichbar, sodass die Sitzungsseite (gesichert durch `evaluations:read`) dieselbe organisationsweite Facette wiederverwendet. `GET /events/models` gehört nicht dazu: es erfordert `events:read`; ein Principal, der nur `evaluations:read` besitzt, erhält davon einen 403. | -### Sessions & Evaluierungen +### Sitzungen & Auswertungen | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Sessions auflisten, Evaluierungsergebnisse lesen, die zusammengefasste Eval-Gesundheit für Dashboards sowie den Status der Evaluierungsjob-Worker-Queue einsehen. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Eine erneute Evaluierung für eine abgeschlossene Session manuell in die Warteschlange stellen. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Sitzungen auflisten, Auswertungsergebnisse lesen, den zusammengefassten Auswertungszustand für Dashboards sowie den Status der Auswertungs-Job-Warteschlange. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Eine erneute Auswertung für eine abgeschlossene Sitzung manuell in die Warteschlange einreihen. | ### Dashboards | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Dashboards auflisten, eines laden und seine Tiles lesen. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Dashboards erstellen und bearbeiten, Tiles hinzufügen/bearbeiten/entfernen und das Tile-Raster neu anordnen. | -| `dashboards:delete` | `DELETE /dashboards/:id` | Ein gesamtes Dashboard löschen (das Löschen auf Tile-Ebene liegt unter `dashboards:write`). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Dashboards auflisten, eines laden und seine Kacheln lesen. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Dashboards erstellen und bearbeiten, Kacheln hinzufügen/bearbeiten/entfernen und das Kachel-Raster neu anordnen. | +| `dashboards:delete` | `DELETE /dashboards/:id` | Ein gesamtes Dashboard löschen (das Löschen auf Kachelebene gehört zu `dashboards:write`). | ### Gespeicherte Abfragen (SQL-Composer) | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Gespeicherte Abfragen auflisten, eine laden und das Read-only-Schema des Composers einsehen. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | Gespeicherte Abfragen erstellen und bearbeiten. SQL wird weiterhin über dieselbe Read-only-Rolle und dieselben SQL-Prüfungen wie ein `queries:run`-Aufruf geleitet. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Gespeicherte Abfragen auflisten, eine laden und das schreibgeschützte Schema des Composers einsehen. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | Gespeicherte Abfragen erstellen und bearbeiten. SQL wird weiterhin über dieselbe schreibgeschützte Rolle und dieselben SQL-Prüfungen wie bei einem `queries:run`-Aufruf geleitet. | | `queries:delete` | `DELETE /queries/:id` | Eine gespeicherte Abfrage löschen. | -| `queries:run` | `POST /queries/run` | Gespeichertes oder Ad-hoc-SQL gegen die Read-only-Rolle des Composers ausführen. | +| `queries:run` | `POST /queries/run` | Gespeichertes oder ad-hoc SQL gegen die schreibgeschützte Rolle des Composers ausführen. | ### KI-Assistent | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Mit dem KI-Assistenten sprechen und eigene (private) Konversationen verwalten. Auf **Benutzerebene** erforderlich, um das Assistenten-Dock zu sehen; der eigene Key des Assistenten ist `dashboard-assistant` und wird separat befüllt (siehe unten). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Mit dem KI-Assistenten sprechen und eigene (private) Konversationen verwalten. Auf **Benutzerebene** erforderlich, um den Assistenten-Dock zu sehen; der eigene Key des Assistenten ist `dashboard-assistant` und wird separat befüllt (siehe unten). | -### API-Keys +### API Keys | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `keys:create` | `POST /keys` | Einen neuen scoped API-Key erstellen. Gewährt **nicht** das Bearbeiten der Berechtigungen eines vorhandenen Keys (das ist `keys:update`). | -| `keys:read` | `GET /keys` | Vorhandene Keys auflisten. Secrets werden von diesem Endpunkt nie zurückgegeben. | -| `keys:update` | `PATCH /keys/:id` | Die Berechtigungen eines vorhandenen Keys bearbeiten. Eine **ausschließlich für Menschen/das Dashboard** bestimmte Berechtigung; sie kann keinem API-Key zugewiesen werden (ein Bearer-Key darf Keys erstellen, aber nie bearbeiten). | -| `keys:disable` | `POST /keys/:id/disable` | Einen Key widerrufen. Geschützte Keys (`admin`, `dashboard-assistant`) können nicht deaktiviert werden; rotieren Sie diese per Umgebungsvariable + Neustart. | +| `keys:create` | `POST /keys` | Einen neuen Scoped-API-Key erstellen. Gewährt **nicht** das Bearbeiten der Berechtigungen eines bestehenden Keys (das ist `keys:update`). | +| `keys:read` | `GET /keys` | Bestehende Keys auflisten. Secrets werden von diesem Endpunkt nie zurückgegeben. | +| `keys:update` | `PATCH /keys/:id` | Die Berechtigungen eines bestehenden Keys bearbeiten. Eine **nur für Menschen/das Dashboard** gültige Berechtigung; sie kann keinem API-Key zugewiesen werden (ein Bearer-Key darf Keys erstellen, sie aber nie bearbeiten). | +| `keys:disable` | `POST /keys/:id/disable` | Einen Key widerrufen. Geschützte Keys (`admin`, `dashboard-assistant`) können nicht deaktiviert werden; rotieren Sie diese über die Umgebungsvariable + Neustart. | | `keys:regenerate` | `POST /keys/:id/regenerate` | Das Secret eines Keys rotieren. Geschützte Keys können über diese Route nicht neu generiert werden. | ### Dashboard-Benutzer | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | Einen neuen Dashboard-Benutzer einladen (sendet eine E-Mail mit Einmalpasscode (OTP) zur Anmeldung) und den dashboard-konfigurierten Standard-Berechtigungssatz lesen, der das Einladeformular vorausfüllt. | +| `users:create` | `POST /users`, `GET /users/defaults` | Einen neuen Dashboard-Benutzer einladen (versendet eine E-Mail mit Einmal-Passcode (OTP)) und den konfigurierten Standard-Berechtigungssatz lesen, der zum Vorausfüllen des Einladungsformulars verwendet wird. | | `users:read` | `GET /users`, `GET /users/:id` | Benutzer auflisten und einen einzelnen Benutzerdatensatz laden. | -| `users:update` | `PUT /users/:id` | Die Berechtigungen eines Benutzers bearbeiten. Änderungen lösen eine Benachrichtigungs-E-Mail über Berechtigungsänderungen an den betroffenen Benutzer aus und werden bei der nächsten Anfrage wirksam; eine erneute Anmeldung ist nicht erforderlich. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Einen Benutzer deaktivieren (widerruft seine Sessions sofort) und einen zuvor deaktivierten Benutzer wieder aktivieren. | +| `users:update` | `PUT /users/:id` | Berechtigungen eines Benutzers bearbeiten. Änderungen lösen eine E-Mail-Benachrichtigung über die Berechtigungsänderung an den betroffenen Benutzer aus und werden bei dessen nächster Anfrage wirksam; kein erneutes Einloggen erforderlich. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Einen Benutzer deaktivieren (widerruft deren Sitzungen sofort) und einen zuvor deaktivierten Benutzer wieder aktivieren. | -Diese Berechtigungen unterstützen die **Users**-Seite im Dashboard, auf der die vergebenen Scopes jedes Mitglieds als Chips angezeigt werden: +Diese Berechtigungen bilden die Grundlage der **Benutzer**-Seite im Dashboard, auf der die gewährten Scopes jedes Mitglieds als Chips angezeigt werden: -![Die Users-Seite: eine Karte pro Dashboard-Benutzer mit E-Mail-Adresse, vergebenen Berechtigungen sowie Bearbeiten- und Deaktivieren-Steuerelementen](/agenteye/images/users.png) +![Die Benutzerseite: eine Karte pro Dashboard-Benutzer mit E-Mail, gewährten Berechtigungen sowie Bearbeiten- und Deaktivieren-Steuerelementen](/agenteye/images/users.png) ### Betriebliche Einstellungen | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Dashboard-verwaltete Betriebseinstellungen und ihre Metadaten anzeigen; modellspezifische Context-Window-Overrides auflisten; und das effektive Window für ein Modell auflösen. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Betriebseinstellungen bearbeiten sowie modellspezifische Context-Window-Overrides hinzufügen, ändern oder entfernen. Änderungen wirken sich auf neue Events aus, ohne den Server neu starten zu müssen. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Dashboard-verwaltete Betriebseinstellungen und deren Metadaten anzeigen; modellspezifische Kontextfenster-Überschreibungen auflisten; und das effektive Fenster für ein Modell auflösen. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Betriebliche Einstellungen bearbeiten sowie modellspezifische Kontextfenster-Überschreibungen hinzufügen, ändern oder entfernen. Änderungen wirken sich auf neue Ereignisse aus, ohne dass ein Server-Neustart erforderlich ist. | -![Die Settings-Seite: dashboard-verwaltete Betriebseinstellungen wie erlaubte Anmeldemethoden und Session-/OTP-Lebensdauern, bearbeitbar ohne Neustart](/agenteye/images/settings.png) +![Die Einstellungsseite: dashboard-verwaltete Betriebseinstellungen wie erlaubte Anmeldungen und Sitzungs-/OTP-Laufzeiten, ohne Neustart bearbeitbar](/agenteye/images/settings.png) -### Alarme & Vorfälle +### Warnmeldungen & Vorfälle | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| -| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Konfigurierte Alarm-Definitionen anzeigen. | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Alarm-Definitionen erstellen, bearbeiten, löschen und testweise auslösen. | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Vorfälle und ihren Triage-Verlauf anzeigen. | -| `incidents:write` | `POST /alerts/:id/incidents` | Einen Vorfall manuell zu einem bestehenden Alarm öffnen. | +| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Konfigurierte Warnmeldungs-Definitionen anzeigen. | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Warnmeldungs-Definitionen erstellen, bearbeiten, löschen und testweise auslösen. | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Vorfälle und deren Triage-Verlauf anzeigen. | +| `incidents:write` | `POST /alerts/:id/incidents` | Einen Vorfall manuell gegen eine bestehende Warnmeldung öffnen. | | `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Vorfälle bestätigen, zuweisen, auflösen und kommentieren. | ### Audits @@ -108,64 +108,64 @@ Diese Berechtigungen unterstützen die **Users**-Seite im Dashboard, auf der die | Berechtigung | HTTP-Routen | Was sie erlaubt | |---|---|---| | `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Audit-Definitionen, Ausführungsverlauf und Befunde anzeigen. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Audits erstellen, bearbeiten, löschen und ausführen; Befunde triagieren (bestätigen / stummschalten / verwerfen / lösen / erneut öffnen / zuweisen). | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Audits erstellen, bearbeiten, löschen und ausführen; Befunde triagieren (bestätigen / stummschalten / verwerfen / auflösen / wiedereröffnen / zuweisen). | -> **Hinweis:** Um einem Key die Audit-Oberfläche zu geben, vergeben Sie `audits:*` explizit. Wie bestehende Berechtigungsinhaber migriert wurden, als Audits eingeführt wurden, erfahren Sie unter [Upgrade- und Abwärtskompatibilitätshinweise](#upgrade-and-backward-compatibility-notes). +> **Hinweis:** Um einem Key die Audit-Oberfläche zu geben, gewähren Sie `audits:*` explizit. Wie bestehende Berechtigungsinhaber beim Rollout von Audits migriert wurden, ist unter [Upgrade- und Abwärtskompatibilitätshinweise](#upgrade-and-backward-compatibility-notes) beschrieben. -> Der Empfänger-Auswahl-Endpunkt `GET /alerts/recipients` (der die Mitglieds-E-Mail-Adressen auflistet, die ein Alarm-Editor benachrichtigen kann) ist für Inhaber von **entweder** `alerts:read` **oder** `alerts:write` erreichbar, sodass Alarm-Editoren die Auswahl befüllen können, ohne `users:read` zu benötigen. +> Der Empfänger-Auswahl-Endpunkt `GET /alerts/recipients` (der die Mitglieds-E-Mails auflistet, die ein Warnmeldungseditor benachrichtigen kann) ist für Inhaber von **entweder** `alerts:read` **oder** `alerts:write` erreichbar, sodass Alert-Editoren die Auswahl befüllen können, ohne `users:read` zu besitzen. -> Ein Dashboard-Betrachter benötigt **sowohl** `dashboards:read` (zum Laden der gespeicherten Ansichten) als auch `evaluations:read` (die Gesundheitsmetriken werden aus Evaluierungsdaten berechnet). Vergeben Sie `dashboards:write`, um einem Benutzer das Erstellen oder Bearbeiten von Dashboards zu erlauben, und `dashboards:delete` zum Löschen. +> Ein Dashboard-Betrachter benötigt **sowohl** `dashboards:read` (zum Laden der gespeicherten Ansichten) als auch `evaluations:read` (die Gesundheitsmetriken werden aus Auswertungsdaten berechnet). Vergeben Sie `dashboards:write`, damit ein Benutzer Dashboards erstellen oder bearbeiten kann, und `dashboards:delete`, um sie zu entfernen. -> `/health` und `/auth/*` (OTP-Anfrage, OTP-Verifizierung, Session-Prüfung, Logout) sind designbedingt nicht authentifiziert; sie sind der Anmeldeablauf und der Liveness-Probe. `GET /access-granters` erfordert einen gültigen Key, aber keine spezifische Berechtigung, sodass jeder angemeldete Benutzer sehen kann, welche Admins er bei Zugriffsänderungen kontaktieren soll. +> `/health` und `/auth/*` (OTP-Anfrage, OTP-Verifizierung, Sitzungsprüfung, Abmelden) sind absichtlich nicht authentifiziert; sie bilden den Anmeldefluss und den Liveness-Probe. `GET /access-granters` erfordert einen gültigen Key, aber keine bestimmte Berechtigung, sodass jeder angemeldete Benutzer sehen kann, welche Admins bei Zugriffsänderungen zu kontaktieren sind. --- -## Berechtigungs-Sets +## Berechtigungssätze -Berechtigungs-Sets ermöglichen es Ihnen, eine benannte Rolle anzuwenden, anstatt jedes Mal einzelne Tokens manuell auszuwählen. Anstatt für jeden neuen Dashboard-Benutzer oder API-Key ein Dutzend Berechtigungen einzeln auszuwählen, wählen Sie ein Set, und alle ihm zugeordneten Personen tragen eine konsistente, nachvollziehbare Zuweisung. Das Bearbeiten eines benutzerdefinierten Sets wendet die neue Zuweisung auf jeden bereits zugeordneten Benutzer erneut an, sodass eine Rollenänderung eine einzige Bearbeitung und kein Durchgehen aller Mitglieder ist. +Berechtigungssätze ermöglichen es Ihnen, eine benannte Rolle anzuwenden, anstatt jedes Mal einzelne Token manuell auszuwählen. Anstatt für jeden neuen Dashboard-Benutzer oder API-Key ein Dutzend Berechtigungen einzeln auszuwählen, wählen Sie einen Satz, und alle ihm zugewiesenen Personen tragen eine konsistente, überprüfbare Berechtigung. Das Bearbeiten eines benutzerdefinierten Satzes wendet die neue Berechtigung auf alle bereits zugewiesenen Benutzer erneut an, sodass eine Rollenänderung eine einzige Bearbeitung ist statt einer Durchsicht aller Mitglieder. -Jede Organisation wird mit drei integrierten Sets befüllt: +Jede Organisation wird mit drei integrierten Sätzen befüllt: -| Set | Berechtigungen | Gedacht für | +| Satz | Berechtigungen | Gedacht für | |---|---|---| -| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Nur-Lese-Zugriff auf alle Betriebsoberflächen. | -| `standard` | alles in `read-only`, plus `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Read-only plus die alltäglichen On-Call-Aktionen: Abfragen ausführen, Sessions neu evaluieren, Vorfälle bestätigen und den KI-Assistenten nutzen. | -| `admin` | jede zuweisbare Berechtigung | Vollständige Kontrolle über die Organisation. | +| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Nur-Lese-Zugriff auf alle betrieblichen Oberflächen. | +| `standard` | alles in `read-only`, plus `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Nur-Lese plus die alltäglichen On-Call-Aktionen: Abfragen ausführen, Sitzungen neu auswerten, Vorfälle bestätigen und den KI-Assistenten nutzen. | +| `admin` | alle zuweisbaren Berechtigungen | Vollständige Kontrolle über die Organisation. | -Die drei integrierten Sets sind **unveränderlich**; ihre Namen bedeuten immer dasselbe, sodass `read-only`, `standard` und `admin` sicher in Richtlinien und beim Onboarding referenziert werden können. Ein Operator kann zusätzliche **benutzerdefinierte Sets** erstellen, um organisationsspezifische Rollen abzubilden (z. B. eine Rolle „Dashboard-Autor" oder eine Rolle „Nur-Collector"). +Die drei integrierten Sätze sind **unveränderlich**; ihre Namen bedeuten immer dasselbe, sodass `read-only`, `standard` und `admin` sicher in Richtlinien und beim Onboarding referenziert werden können. Ein Operator kann zusätzliche **benutzerdefinierte Sätze** erstellen, um organisationsspezifische Rollen abzubilden (z.B. eine Rolle „Dashboard-Autor" oder eine Rolle „Nur-Collector"). -Sets sind im Dashboard sichtbar und werden über die API verwaltet: `GET /permission-sets` (auflisten, gesichert durch `users:read`) sowie `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (benutzerdefiniertes Set erstellen, bearbeiten, löschen, gesichert durch `settings:write`). Das Löschen oder Bearbeiten eines integrierten Sets wird abgelehnt. +Sätze werden im Dashboard angezeigt und über die API verwaltet: `GET /permission-sets` (auflisten, gesichert durch `users:read`) sowie `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (erstellen, bearbeiten, löschen eines benutzerdefinierten Satzes, gesichert durch `settings:write`). Das Löschen oder Bearbeiten eines integrierten Satzes wird abgelehnt. -Set-Mitgliedschaft unterstützt zwei weitere Funktionen: +Die Satzmitgliedschaft bildet die Grundlage zweier weiterer Funktionen: -- **`DEFAULT_USER_PERMISSIONS`** (die Zuweisung, die vorausgewählt ist, wenn ein Admin **+ neuer Benutzer** öffnet) ist standardmäßig auf das `standard`-Set gesetzt. -- **Das `--set`-Flag** bei `agenteye-orgctl` (Operator-Mitgliederverwaltung) startet ein Mitglied mit einem benannten Set, das Sie dann mit `--add` / `--remove` verfeinern. +- **`DEFAULT_USER_PERMISSIONS`** (die Berechtigung, die vorausgewählt ist, wenn ein Admin **+ neuer Benutzer** öffnet) entspricht standardmäßig dem `standard`-Satz. +- **Das `--set`-Flag** in `agenteye-orgctl` (Operator-Mitgliederverwaltung) startet ein Mitglied von einem benannten Satz aus, den Sie dann mit `--add` / `--remove` verfeinern. -> **Hinweis:** Wenn ein Set eine Berechtigung enthält, die nicht Key-zuweisbar ist (z. B. ein benutzerdefiniertes Set mit `keys:update`), werden beim Befüllen eines Keys aus diesem Set die nicht zuweisbaren Tokens weggelassen; der Server würde den Key andernfalls mit HTTP 422 ablehnen. Für Dashboard-Benutzer gilt diese Einschränkung nicht. +> **Hinweis:** Enthält ein Satz eine Berechtigung, die nicht Key-zuweisbar ist (z.B. ein benutzerdefinierter Satz, der `keys:update` trägt), werden beim Erstellen eines Keys aus diesem Satz die nicht zuweisbaren Token weggelassen; andernfalls würde der Server den Key mit HTTP 422 ablehnen. Für Dashboard-Benutzer gilt diese Einschränkung nicht. --- ## Bootstrap-Admin-Key -Der Admin-Key ist die einzige Root-Berechtigung, mit der ein Operator den Zugang von Grund auf einrichten kann: Damit können Sie jeden anderen scoped Key erstellen, die ersten Dashboard-Benutzer einladen und die Instanz konfigurieren, bevor ein anderer Key existiert. Es ist der einzige Key, den Sie nicht über die Keys-API erstellen; er wird aus der Umgebung bereitgestellt, damit der Server beim ersten Start erreichbar ist. +Der Admin-Key ist die einzige Root-Berechtigung, mit der ein Operator den Zugang von Grund auf aufbauen kann: Damit können Sie jeden anderen Scoped-Key erstellen, die ersten Dashboard-Benutzer einladen und die Instanz konfigurieren, bevor ein anderer Key existiert. Es ist der einzige Key, den Sie nicht über die Keys-API erstellen; er wird aus der Umgebung bereitgestellt, damit der Server beim ersten Start erreichbar ist. -Setzen Sie die Umgebungsvariable `ADMIN_KEY` auf dem Server. Bei jedem Start führt der Server ein Upsert dieses Werts als Admin-Key mit allen Berechtigungen durch. +Setzen Sie die Umgebungsvariable `ADMIN_KEY` auf dem Server. Bei jedem Start upserted der Server diesen Wert als Admin-Key mit allen Berechtigungen. -Zum Rotieren: Ändern Sie `ADMIN_KEY` auf ein neues Secret und starten Sie den Server neu. +Zur Rotation: Ändern Sie `ADMIN_KEY` auf ein neues Secret und starten Sie den Server neu. --- ## Organisations-Scoping -**Organisationen selbst werden vom Operator außerhalb des Bandes erstellt und verwaltet, nicht über diese Keys-API.** Der Lebenszyklus von Organisationen und Mitgliedern (erstellen/umbenennen/löschen/bereinigen einer Org; Mitglied hinzufügen/aktualisieren/entfernen) erfolgt mit der **`agenteye-orgctl`**-CLI; dafür gibt es keine HTTP-API oder Dashboard-Schaltfläche. Was *unverändert* bleibt: **Pro-Org-API-Keys werden weiterhin im Dashboard (oder über diese Keys-API)** von Org-Mitgliedern erstellt. +**Organisationen selbst werden von einem Operator außerhalb dieses Bandes verwaltet, nicht über diese Keys-API.** Der Lebenszyklus von Org und Mitgliedern (erstellen / umbenennen / löschen / bereinigen einer Org; Mitglied hinzufügen / aktualisieren / entfernen) erfolgt mit der **`agenteye-orgctl`**-CLI; es gibt dafür keine HTTP-API oder Dashboard-Schaltfläche. Was *unverändert bleibt*: **Pro-Org-API-Keys werden weiterhin im Dashboard (oder über diese Keys-API)** von Org-Mitgliedern erstellt. -In einem Multi-Org-Deployment gehört jeder Key, den ein Org-Mitglied erstellt (über diese Keys-API oder die Dashboard-**Keys**-Seite), zu **einer Organisation** und kann ausschließlich die Daten dieser Org lesen oder schreiben; die Org wird beim Erstellen auf den Key gestempelt und bei jeder Anfrage durchgesetzt. Die beiden Bootstrap-Keys sind die einzige Ausnahme: Der `admin`-Key (befüllt aus `ADMIN_KEY`) und der `dashboard-assistant`-Key (befüllt aus `AGENT_API_KEY`) sind **instanzweit gültig** (sie tragen keine Org). Das Dashboard authentifiziert sich mit dem `admin`-Key, damit es Pro-Org-Anfragen im Namen angemeldeter Mitglieder weiterleiten kann. Single-Tenant-Deployments müssen sich darum nicht kümmern; alle Keys gehören zur integrierten `default`-Org. +In einem Multi-Org-Deployment gehört jeder Key, den ein Org-Mitglied erstellt (über diese Keys-API oder die Dashboard-**Keys**-Seite), zu **einer Organisation** und kann immer nur die Daten dieser Org lesen oder schreiben; die Org wird beim Erstellen auf den Key gestempelt und bei jeder Anfrage erzwungen. Die beiden Bootstrap-Keys sind die einzige Ausnahme: der `admin`-Key (befüllt aus `ADMIN_KEY`) und der `dashboard-assistant`-Key (befüllt aus `AGENT_API_KEY`) sind **instanzweit** (sie tragen keine Org). Das Dashboard authentifiziert sich mit dem `admin`-Key, damit es Pro-Org-Anfragen im Namen angemeldeter Mitglieder weiterleiten kann. Single-Tenant-Deployments müssen darüber nicht nachdenken; alle Keys gehören zur integrierten `default`-Org. --- ## Keys erstellen -Verwenden Sie den Admin-Key (oder einen beliebigen Key mit der Berechtigung `keys:create`), um weitere scoped Keys zu erstellen. +Verwenden Sie den Admin-Key (oder einen beliebigen Key mit `keys:create`-Berechtigung), um weitere Scoped-Keys zu erstellen. ### Collector-Key (nur Ingest) @@ -193,7 +193,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -Wenn Sie einen Key über die HTTP-API erstellen, geben Sie den `key`-Wert selbst an; wählen Sie ein starkes Secret und speichern Sie es sicher. (Im Dashboard funktioniert es umgekehrt: Es generiert ein starkes Secret für Sie und zeigt es einmalig bei der Erstellung an; siehe [Key-Verwaltung im Dashboard](#key-management-in-the-dashboard).) Die Antwort bestätigt, dass der Key erstellt wurde: +Wenn Sie einen Key über die HTTP-API erstellen, geben Sie den `key`-Wert selbst an; wählen Sie ein starkes Secret und speichern Sie es sicher. (Das Dashboard funktioniert umgekehrt: Es generiert ein starkes Secret für Sie und zeigt es einmalig bei der Erstellung an; siehe [Key-Verwaltung im Dashboard](#key-management-in-the-dashboard).) Die Antwort bestätigt die Erstellung des Keys: ```json { @@ -213,13 +213,13 @@ curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -Key-Secrets werden in Listenantworten nicht zurückgegeben – nur IDs, Namen und Berechtigungen. +Key-Secrets werden in Listenabfragen nicht zurückgegeben, nur IDs, Namen und Berechtigungen. --- ## Einen Key deaktivieren -Das Deaktivieren widerruft den Zugriff sofort, ohne den Key-Datensatz zu löschen. +Die Deaktivierung widerruft den Zugang sofort, ohne den Key-Datensatz zu löschen. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -230,7 +230,7 @@ curl -s -X POST http://your-server/keys//disable \ ## Einen Key neu generieren -Generiert ein neues Secret für einen vorhandenen Key. Das alte Secret wird sofort ungültig. +Generiert ein neues Secret für einen bestehenden Key. Das alte Secret wird sofort ungültig. ```bash curl -s -X POST http://your-server/keys//regenerate \ @@ -243,24 +243,24 @@ Die Antwort enthält das neue Klartext-Secret, das **nur einmal angezeigt** wird ## Key-Verwaltung im Dashboard -Die **Keys**-Seite im Dashboard bietet eine Benutzeroberfläche für alle oben genannten Operationen. Sie benötigen einen Key mit der Berechtigung `keys:read`, um die Liste anzuzeigen, sowie `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` für die Aktionen Erstellen / Bearbeiten / Deaktivieren / Neu generieren. Das Bearbeiten der Berechtigungen eines Keys (`keys:update`) ist vom Erstellen eines Keys (`keys:create`) getrennt, sodass Sie einem Operator die Möglichkeit geben können, Keys zu erstellen, ohne bestehende neu zu scopieren – oder umgekehrt. Der Admin-Key deckt all diese Bereiche ab. +Die **Keys**-Seite im Dashboard bietet eine Benutzeroberfläche für alle oben genannten Operationen. Sie benötigen einen Key mit `keys:read`-Berechtigung, um die Liste anzuzeigen, sowie `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` für die jeweiligen Aktionen zum Erstellen / Bearbeiten / Deaktivieren / Neu-Generieren. Das Bearbeiten der Berechtigungen eines Keys (`keys:update`) ist vom Erstellen (`keys:create`) getrennt, sodass Sie einem Operator die Möglichkeit geben können, Keys zu erstellen, ohne bestehende Keys neu zuzuordnen, oder umgekehrt. Der Admin-Key deckt all diese Berechtigungen ab. -Wenn Sie einen Key im Dashboard erstellen, geben Sie das Secret nicht selbst an; das Dashboard generiert ein starkes Secret für Sie und zeigt es **einmalig** bei der Erstellung an. Kopieren Sie es sofort und speichern Sie es sicher; es wird nie wieder angezeigt – genau wie beim Neu-Generieren. Sie können die Berechtigungen des Keys trotzdem direkt auswählen oder sie aus einem Berechtigungs-Set übernehmen (siehe unten). +Wenn Sie einen Key über das Dashboard erstellen, geben Sie das Secret nicht selbst an; das Dashboard generiert ein starkes Secret für Sie und zeigt es **einmalig** bei der Erstellung an. Kopieren Sie es sofort und speichern Sie es sicher; es wird nie wieder angezeigt, genau wie bei einer Neu-Generierung. Sie können die Berechtigungen des Keys direkt auswählen oder sie aus einem Berechtigungssatz befüllen (siehe unten). -![Die API-Keys-Seite: eine Karte pro Key mit Name, vergebenen Berechtigungen und Erstellungszeitpunkt sowie Aktionen zum Neu-Generieren und Deaktivieren; geschützte Keys wie `admin` sind gekennzeichnet](/agenteye/images/api-keys.png) +![Die API-Keys-Seite: eine Karte pro Key mit Name, gewährten Berechtigungen und Erstellungszeitpunkt, mit Neu-Generieren- und Deaktivieren-Aktionen; geschützte Keys wie `admin` sind gekennzeichnet](/agenteye/images/api-keys.png) --- ## Empfohlenes Key-Layout -| Key | Berechtigungen | Wird verwendet von | +| Key | Berechtigungen | Verwendet von | |---|---|---| -| `admin` (Bootstrap via `ADMIN_KEY`-Umgebungsvariable) | alle | Ops/Einrichtung sowie dem Dashboard (authentifiziert sich mit `ADMIN_KEY`, leitet Benutzeranfragen mit Berechtigungsprüfungen weiter) | +| `admin` (Bootstrap über `ADMIN_KEY`-Umgebungsvariable) | alle | Ops/Setup und das Dashboard (authentifiziert sich mit `ADMIN_KEY`, leitet Benutzeranfragen mit Berechtigungsprüfungen weiter) | | Pro-Host-Collector-Key | `events:add` | Collector auf jeder Agent-Maschine | -| `dashboard-assistant` (Bootstrap via `AGENT_API_KEY`-Umgebungsvariable) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | KI-Assistent, automatisch befüllt, **geschützt**; kann nicht über die API bearbeitet werden | -| Assistent-Telemetrie-Key (optional) | `events:add` | KI-Assistent-Selbst-Instrumentierung, falls aktiviert | +| `dashboard-assistant` (Bootstrap über `AGENT_API_KEY`-Umgebungsvariable) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | KI-Assistent, automatisch befüllt, **geschützt**; kann nicht über die API bearbeitet werden | +| Assistent-Telemetrie-Key (optional) | `events:add` | KI-Assistent-Selbstinstrumentierung, falls aktiviert | -> **Hinweis:** Der Key des Assistenten wird **automatisch** vom Server aus der Umgebungsvariable `AGENT_API_KEY` befüllt (dasselbe Secret, das der Agent als `AGENTEYE_API_KEY` präsentiert); es gibt keinen manuellen Key-Erstellungsschritt und keinen Admin-Key dabei. Seine Berechtigungen sind im Quellcode festgelegt, sodass der Scope nicht durch Fehlkonfiguration erweitert werden kann: Lesezugriff auf Events/Evaluierungen/Dashboards, plus Dashboards-write und Queries-read/write/run für den Authoring-Flow „KI nach einer Abfrage fragen". Sämtliches SQL durchläuft weiterhin dieselbe Read-only-Rolle und denselben gesicherten SQL-Pfad wie eine benutzerverfasste Abfrage, sodass dies die *Authoring-Oberfläche*, nicht die Datenoberfläche erweitert; destruktive Operationen (`queries:delete`, `dashboards:delete`) bleiben bewusst vom Assistenten-Key ausgeschlossen. Wie der `admin`-Key ist er **geschützt**: Er kann nicht über die Keys-API deaktiviert oder neu generiert werden, sondern nur durch Ändern von `AGENT_API_KEY` und Neustart rotiert werden. Dashboard-*Benutzer* benötigen zusätzlich die Berechtigung `agent:use`, um den Assistenten zu sehen und zu nutzen. Wenn Sie die Selbst-Instrumentierung aktivieren, geben Sie dem Assistenten einen separaten Key, der nur `events:add` enthält. +> **Hinweis:** Der Key des Assistenten wird **automatisch** vom Server aus der Umgebungsvariable `AGENT_API_KEY` befüllt (dasselbe Secret, das der Agent als `AGENTEYE_API_KEY` präsentiert); es gibt keinen manuellen Key-Erstellungsschritt und keinen Admin-Key-Einbezug. Seine Berechtigungen sind im Quellcode festgelegt, sodass der Scope durch Fehlkonfiguration nicht erweitert werden kann: Lesen über Ereignisse / Auswertungen / Dashboards, plus Dashboards-Schreiben und Abfragen-Lesen / Schreiben / Ausführen für den Authoring-Flow „KI bitten, eine Abfrage zu schreiben". Alles SQL läuft weiterhin über dieselbe schreibgeschützte Rolle und denselben gesicherten SQL-Pfad wie eine vom Benutzer geschriebene Abfrage, sodass dies die *Authoring-Oberfläche* erweitert, nicht die Datenoberfläche; destruktive Operationen (`queries:delete`, `dashboards:delete`) bleiben bewusst vom Assistenten-Key ausgeschlossen. Wie der `admin`-Key ist er **geschützt**: Er kann nicht über die Keys-API deaktiviert oder neu generiert werden, sondern nur durch Ändern von `AGENT_API_KEY` und Neustart rotiert werden. Dashboard-*Benutzer* benötigen zusätzlich die `agent:use`-Berechtigung, um den Assistenten sehen und nutzen zu können. Wenn Sie Selbstinstrumentierung aktivieren, geben Sie dem Assistenten einen separaten, nur `events:add`-fähigen Key. --- @@ -268,13 +268,13 @@ Wenn Sie einen Key im Dashboard erstellen, geben Sie das Secret nicht selbst an; Diese Hinweise sind nur relevant, wenn Sie eine bestehende Instanz aktualisieren; neue Deployments können sie überspringen. -> Als Audits eingeführt wurden, wurden bestehende Berechtigungsinhaber entsprechend denselben Rollenformen wie bei Alarmen erweitert: Jeder Benutzer und jedes Berechtigungs-Set, das `alerts:read` enthielt, erhielt `audits:read`; jeder Inhaber von `alerts:write` erhielt `audits:write`. Bestehende API-Keys wurden **nicht** erweitert. Vergeben Sie `audits:*` explizit an einen Key, wenn er die Audit-Oberfläche benötigt. +> Als Audits eingeführt wurden, wurden bestehende Berechtigungsinhaber entsprechend denselben Rollenstrukturen wie Warnmeldungen erweitert: Jeder Benutzer und Berechtigungssatz mit `alerts:read` erhielt `audits:read`, und jeder Inhaber von `alerts:write` erhielt `audits:write`. Bestehende API-Keys wurden **nicht** erweitert. Vergeben Sie `audits:*` explizit an einen Key, wenn er die Audit-Oberfläche benötigt. -> Gespeicherte Zuweisungen des veralteten Tokens `alerts:ack` werden als `incidents:ack` geparst, sodass On-Caller den Zugriff ohne erneute Key-Ausgabe behalten. Das Token ist im Benutzer-Editor des Dashboards nicht mehr zuweisbar; die Matrix bietet stattdessen `incidents:ack` an. +> Gespeicherte Grants des veralteten `alerts:ack`-Tokens werden als `incidents:ack` geparst, sodass On-Caller weiterhin Zugriff behalten, ohne Keys neu ausstellen zu müssen. Das Token ist im Benutzer-Editor des Dashboards nicht mehr zuweisbar; die Matrix bietet stattdessen `incidents:ack` an. --- ## Nächste Schritte -- [Python SDK](/de/agenteye/python-sdk): Wie Ihr Agent-Code sich beim Senden von Events authentifiziert. -- [Security](/de/agenteye/security): Wie Anmeldung, Zugriffskontrolle und organisationsweite Datenisolierung funktionieren. \ No newline at end of file +- [Python SDK](/de/agenteye/python-sdk): Wie sich Ihr Agent-Code authentifiziert, wenn er Ereignisse sendet. +- [Sicherheit](/de/agenteye/security): Wie Anmeldung, Zugangskontrolle und organisationsweite Datenisolierung funktionieren. \ No newline at end of file diff --git a/docs/de/agenteye/assistant.mdx b/docs/de/agenteye/assistant.mdx index 961e49f7..b6e1ac32 100644 --- a/docs/de/agenteye/assistant.mdx +++ b/docs/de/agenteye/assistant.mdx @@ -1,15 +1,15 @@ --- title: "KI-Assistent" -description: "Stell deinen Agentendaten eine Frage auf Deutsch und erhalte eine Antwort, die direkt auf die Belege verlinkt." +description: "Stellen Sie Ihren Agentendaten eine Frage in natürlicher Sprache und erhalten Sie eine Antwort, die direkt auf die Belege verweist." --- -Stell deinen Agentendaten eine Frage in gewöhnlicher Sprache und erhalte eine Antwort, die direkt auf die Belege verlinkt. Kein SQL schreiben, kein Durchsuchen von Dashboards – der **Failproof AI Observability**-Assistent ist der schnellste Weg für jeden in deinem Team, Antworten zu euren Agenten zu bekommen. +Stellen Sie Ihren Agentendaten eine Frage in natürlicher Sprache und erhalten Sie eine Antwort, die direkt auf die Belege verweist. Kein SQL zu schreiben, keine Dashboards zu durchsuchen — der **Failproof AI Observability**-Assistent ist der schnellste Weg für jeden in Ihrem Team, Antworten zu Ihren Agenten zu erhalten. -![Der Failproof AI Observability-Assistent beantwortet eine Frage in natürlicher Sprache im Dashboard und zeigt dabei eine Live-Agenten-Aktivitätstabelle, eine Aufschlüsselung der Modellnutzung pro Agent und schriftliche Zusammenfassungen – die ausgeführten Abfragen werden inline angezeigt](/agenteye/images/assistant.png) -*Frag in natürlicher Sprache und erhalte eine Antwort, die aus deinen eigenen Daten aufgebaut ist. Hier wird aufgeschlüsselt, welche Agenten am stärksten ausgelastet sind und welche Modelle sie verwenden – die ausgeführten Abfragen werden angezeigt, damit du jede Zahl nachvollziehen kannst.* +![Der Failproof AI Observability-Assistent beantwortet eine Frage in natürlicher Sprache im Dashboard und zeigt eine Live-Agentenaktivitätstabelle, eine agentenspezifische Modellnutzungsübersicht und schriftliche Erkenntnisse sowie die ausgeführten Abfragen inline an](/agenteye/images/assistant.png) +*Fragen Sie in natürlicher Sprache und erhalten Sie eine Antwort, die auf Ihren eigenen Daten basiert. Hier wird aufgeschlüsselt, welche Agenten am aktivsten sind und welche Modelle sie verwenden – und die ausgeführten Abfragen werden angezeigt, damit Sie jede Zahl nachvollziehen können.* -Es gibt nichts zu lernen. Öffne den Chat, tippe, was du wissen möchtest, und folge den Links, die zurückgegeben werden: +Es gibt nichts zu lernen. Öffnen Sie den Chat, tippen Sie Ihre Frage ein und folgen Sie den zurückgegebenen Links: ``` You: which sessions errored today? @@ -26,38 +26,38 @@ AI: This run took 12 steps across 3 tools and failed near the end when a ## Einfach fragen und direkt zum Beweis springen -Du hörst auf zu raten und hörst auf, Abfragen zu schreiben. Frag „Wie entwickelt sich die Qualität in Produktion diese Woche?", „Welche Sessions sind heute fehlgeschlagen?" oder „Fasse diese Session zusammen" – und du erhältst in Sekunden eine direkte Antwort, anstatt selbst eine Abfrage zu erstellen und auszuwerten. +Sie hören auf zu raten und hören auf, Abfragen zu schreiben. Fragen Sie „Wie entwickelt sich die Qualität in der Produktion diese Woche?", „Welche Sessions haben heute Fehler produziert?" oder „Fasse diese Session zusammen" – und Sie erhalten in Sekunden eine direkte Antwort, statt selbst eine Abfrage zu erstellen und auszuwerten. -Jede Antwort kommt mit ihren Belegen. Der Assistent verlinkt die genauen Sessions, gespeicherten Abfragen und Dashboards, die er zur Antwort verwendet hat – so kannst du durchklicken und bestätigen, anstatt ihm blind zu vertrauen. Außerdem ist er **seitenabhängig**: Frag nach „dieser Session", während du eine betrachtest, und er weiß bereits, welchen Lauf du meinst. Öffne frühere Gespräche später über den Verlaufs-Umschalter erneut und mach dort weiter, wo du aufgehört hast. +Jede Antwort kommt mit ihren Belegen. Der Assistent verlinkt die genauen Sessions, gespeicherten Abfragen und Dashboards, die zur Antwort geführt haben, damit Sie durchklicken und bestätigen können, anstatt dem Assistenten einfach zu vertrauen. Er ist außerdem **seitenorientiert**: Fragen Sie nach „dieser Session", während Sie gerade eine betrachten, und er weiß bereits, welchen Durchlauf Sie meinen. Öffnen Sie frühere Gespräche jederzeit über den Verlaufs-Umschalter erneut und machen Sie dort weiter, wo Sie aufgehört haben. -## Eine gute Antwort in eine gespeicherte Abfrage oder ein Dashboard verwandeln +## Eine gute Antwort als gespeicherte Abfrage oder Dashboard sichern -Wenn eine Antwort es wert ist, behalten zu werden, bitte den Assistenten, sie zu speichern. Er entwirft das SQL für eine gespeicherte Abfrage oder stellt ein Dashboard aus diesen Abfragen zusammen und zeigt dir dann eine **Genehmigen / Ablehnen**-Karte. Nichts wird gespeichert, bis du auf „Genehmigen" klickst – du bekommst also die Schnelligkeit von „einfach fragen", hast aber immer das letzte Wort. +Wenn eine Antwort es wert ist, behalten zu werden, bitten Sie den Assistenten, sie zu speichern. Er entwirft das SQL für eine gespeicherte Abfrage oder stellt ein Dashboard aus diesen Abfragen zusammen und zeigt Ihnen dann eine **Genehmigen / Ablehnen**-Karte an. Nichts wird geschrieben, bis Sie auf „Genehmigen" klicken – Sie erhalten also die Schnelligkeit von „einfach fragen", behalten aber immer das letzte Wort. -Auf der **Queries**-Seite geht er noch einen Schritt weiter und wird zum SQL-Autor: Beschreibe die gewünschte Abfrage („zeige Fehlerrate nach Agent für die letzten 7 Tage") und er streamt SQL direkt in den Editor – mit einer Diff-Ansicht, damit du die Änderung **akzeptieren** oder **ablehnen** kannst, bevor sie übernommen wird. +Auf der Seite **Queries** geht er einen Schritt weiter und wird zum SQL-Autor: Beschreiben Sie die gewünschte Abfrage („Zeige die Fehlerrate nach Agent für die letzten 7 Tage") und er streamt SQL direkt in den Editor und öffnet eine Diff-Ansicht, damit Sie die Änderung **akzeptieren** oder **ablehnen** können, bevor sie übernommen wird. ![Die Observability-Queries-Seite und ihr SQL-Editor](/agenteye/images/query-lab.png) -*Die Queries-Seite: In diesem Editor streamt der Assistent einen schreibgeschützten Entwurf, den du akzeptieren oder ablehnen kannst.* +*Die Queries-Seite: Dieser Editor ist der Ort, an dem der Assistent einen schreibgeschützten Entwurf streamt, den Sie akzeptieren oder ablehnen können.* -Das Erstellen von SQL per Frage hier verwendet die Berechtigung `queries:run` – dieselbe, die hinter dem **Ausführen**-Button des Editors steckt. Der Chat überall sonst benötigt `agent:use`. +Das Erstellen von SQL durch Fragen hier verwendet die Berechtigung `queries:run`, dieselbe, die hinter dem **Ausführen**-Button des Editors steckt. Der Chat überall sonst benötigt `agent:use`. ## Sicher für das gesamte Team -Du kannst den Assistenten für alle öffnen, ohne dir Gedanken darüber machen zu müssen, was er anfassen könnte: +Sie können den Assistenten für alle öffnen, ohne sich Sorgen zu machen, was er möglicherweise berührt: -- **Er liest nur, was du bereits sehen kannst.** Antworten sind auf deine eigenen Leseberechtigungen beschränkt, er erweitert also niemals deine Datenfläche. -- **Jeder Schreibvorgang wartet auf dich.** Gespeicherte Abfragen und Dashboards werden nur nach deinem ausdrücklichen Klick auf „Genehmigen" erstellt – und es gibt keine Einstellung, die diese Schranke deaktiviert. -- **Er kann niemals etwas löschen.** Es ist kein Lösch-Tool verfügbar, und der Assistent hat keine Löschberechtigung. Löschvorgänge bleiben in deinen Händen, im Dashboard. -- **Er bleibt in deiner Organisation.** Der Assistent sieht immer nur die Organisation, die du gerade ansiehst. -- **Deine Fragen gehören dir.** Eingaben und Antworten leben in deiner eigenen Observability-Datenbank; Produktanalysen zeichnen nur Nutzungsmetadaten auf, niemals deinen Fragentext. +- **Er liest nur, was Sie bereits sehen können.** Antworten sind auf Ihre eigenen Leseberechtigungen beschränkt, sodass er Ihre Datenzugriffsebene niemals erweitert. +- **Jeder Schreibvorgang wartet auf Sie.** Gespeicherte Abfragen und Dashboards werden erst nach Ihrem ausdrücklichen Klick auf „Genehmigen" erstellt, und es gibt keine Einstellung, die dieses Tor deaktiviert. +- **Er kann niemals etwas löschen.** Es ist kein Lösch-Tool verfügbar, und der Assistent hat keine Löschberechtigung. Löschungen bleiben in Ihren Händen, im Dashboard. +- **Er bleibt in Ihrer Organisation.** Der Assistent sieht immer nur die Organisation, die Sie gerade betrachten. +- **Ihre Fragen bleiben Ihre.** Prompts und Antworten leben in Ihrer eigenen Observability-Datenbank; Produktanalysen erfassen nur Nutzungsmetadaten, niemals Ihren Prompt-Text. -## Wo du ihn findest +## Wo Sie ihn finden -Der Assistent befindet sich am rechten Rand jeder Seite unter deiner Organisation (`//...`). Klick auf die Leiste oder drücke `⌘J` / `Ctrl+J`, um sie in das vollständige Chat-Panel zu erweitern, und ziehe an ihrem Rand zum Ändern der Größe – deine Breite wird über Seitenneuladen hinweg gespeichert. Du benötigst die Berechtigung **`agent:use`**, um ihn zu nutzen, andernfalls ist die Leiste ausgegraut. Wenn er für dein Deployment noch nicht aktiviert wurde (er benötigt eine LLM-Verbindung), siehst du eine gedämpfte Leiste anstelle eines funktionierenden Chats. +Der Assistent befindet sich am rechten Rand jeder Seite unter Ihrer Organisation (`//...`). Klicken Sie auf die Leiste oder drücken Sie `⌘J` / `Ctrl+J`, um sie in das vollständige Chat-Panel auszuklappen, und ziehen Sie den Rand, um die Größe anzupassen; Ihre Breite wird über Neuladen hinweg gespeichert. Sie benötigen die Berechtigung **`agent:use`**, um ihn zu verwenden, andernfalls ist die Leiste ausgegraut. Wenn er für Ihre Bereitstellung noch nicht aktiviert wurde (er benötigt eine LLM-Verbindung), sehen Sie eine gedämpfte Leiste anstelle eines funktionierenden Chats. ## Verwandte Themen -- [CLI and agents](/de/agenteye/cli-and-agents) +- [CLI und Agenten](/de/agenteye/cli-and-agents) - [Queries](/de/agenteye/queries) - [Dashboards](/de/agenteye/dashboards) -- [Evaluation suite](/de/agenteye/evaluation-suite) \ No newline at end of file +- [Evaluierungssuite](/de/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/de/agenteye/audits.mdx b/docs/de/agenteye/audits.mdx index 41b6f14a..8bec9ca6 100644 --- a/docs/de/agenteye/audits.mdx +++ b/docs/de/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- -title: "Audits: Ihr automatischer Zuverlässigkeitsanalyst" -description: "Failproof AI Observability sucht nach den Fehlern, für die Sie nie eine Regel geschrieben haben, und liefert Ihnen eine priorisierte, evidenzbasierte Aufgabenliste mit genau dem, was behoben werden muss." +title: "Audits: dein automatischer Zuverlässigkeitsanalyst" +description: "Failproof AI Observability sucht gezielt nach Fehlern, für die du noch keine Regel geschrieben hast, und liefert dir eine priorisierte, belegbasierte To-do-Liste mit genau den Dingen, die du beheben musst." --- -Failproof AI Observability sucht nach den Fehlern, für die Sie nie eine Regel geschrieben haben, und liefert Ihnen eine priorisierte, evidenzbasierte Aufgabenliste mit genau dem, was behoben werden muss. Es ist so, als würde ein Analyst jede Nacht Ihre Logs durchforsten und Ihnen morgens die Kurzliste auf den Schreibtisch legen. +Failproof AI Observability sucht gezielt nach Fehlern, für die du noch keine Regel geschrieben hast, und liefert dir eine priorisierte, belegbasierte To-do-Liste mit genau den Dingen, die du beheben musst. Es ist, als hättest du einen Analysten, der jede Nacht deine Logs durchkämmt und dir die Kurzliste morgens auf den Schreibtisch legt.
-*Ein zweiminütiger Rundgang: vom geplanten Lauf bis zu einer umsetzbaren Lösung.* +*Ein zweiminütiger Rundgang: von einem geplanten Lauf bis zu einer umsetzbaren Lösung.* -![Die Audits-Seite: wiederkehrende Jobs, die Ihre Sessions auf Fehlermuster scannen, jeweils mit Zeitplan und Sensitivität](/agenteye/images/audits.png) -*Jedes Audit ist ein wiederkehrender Job, der Ihre Sessions auswertet und priorisierte, evidenzbasierte Empfehlungen erstellt.* +![Die Audits-Seite: wiederkehrende Jobs, die deine Sessions nach Fehlermustern durchsuchen, jeweils mit Zeitplan und Empfindlichkeitsstufe](/agenteye/images/audits.png) +*Jedes Audit ist ein wiederkehrender Job, der deine Sessions auswertet und priorisierte, belegbasierte Empfehlungen erstellt.* -## Hören Sie auf zu raten, was als Nächstes behoben werden soll +## Aufhören zu raten, was als Nächstes behoben werden soll -Alerts erfassen die Probleme, auf die Sie bereits zu achten wissen. Audits erfassen die, die Sie noch nicht kennen. In einem von Ihnen festgelegten Rhythmus liest ein Audit alle Ihre Agent-Sessions durch und sucht nach den Mustern, die es wert sind, behoben zu werden – sodass Sie Ihre Zeit damit verbringen, auf Erkenntnisse zu reagieren, anstatt Logs zu durchblättern und zu hoffen, sie selbst zu entdecken. +Alerts erfassen die Probleme, auf die du bereits achtest. Audits erfassen die, die du noch nicht kennst. In einem von dir festgelegten Rhythmus liest ein Audit alle deine Agent-Sessions durch und sucht nach Mustern, die es wert sind, behoben zu werden – damit du deine Zeit damit verbringst, auf Erkenntnisse zu reagieren, anstatt Logs zu durchscrollen und auf Zufallsfunde zu hoffen. -Ein einzelner Lauf geht die Fehlermodi an, die Agents in der Produktion tatsächlich zum Scheitern bringen: +Ein einzelner Lauf geht die Fehlermodi an, die Agents in der Produktion tatsächlich kaputtmachen: -- **Fehler-Cluster**: Dieselbe Fehlfunktion, die sich unter einer gemeinsamen Grundursache wiederholt. -- **Abweichung von einer Baseline**: Verhalten, das sich still und leise von einem bekannt-guten Zeitfenster entfernt. -- **Zielverfehlung in Transkripten**: Läufe, die technisch abgeschlossen wurden, aber den Auftrag nie erfüllt haben. -- **Tool-Missbrauch**: Das falsche Tool, fehlerhafte Argumente oder Schleifen, die Aufrufe verschwenden. -- **Qualitäts- und Kostenabwägungen**: Wo Sie für Output zu viel bezahlen, den Sie günstiger bekommen könnten. -- **Coverage-Lücken**: Verhalten, das kein Eval und kein Alert überwacht. +- **Fehler-Cluster**: Derselbe Fehler, der sich unter einer gemeinsamen Grundursache wiederholt. +- **Drift gegenüber einer Baseline**: Verhalten, das sich still und leise von einem bekannt-guten Zustand entfernt. +- **Zielverfehlung in Transkripten**: Läufe, die technisch abgeschlossen wurden, aber die eigentliche Aufgabe nie erfüllt haben. +- **Tool-Missbrauch**: Das falsche Tool, fehlerhafte Argumente oder Schleifen, die API-Aufrufe verbrennen. +- **Qualitäts- und Kosten-Trade-offs**: Wo du zu viel für Output bezahlst, den du günstiger bekommen könntest. +- **Coverage-Lücken**: Verhalten, das kein Eval oder Alert überwacht. -Mit einer einzigen **Sensitivitäts**-Einstellung (niedrig, mittel oder hoch) bestimmen Sie, wie gründlich die Suche ist – so kann ein rauschender Staging-Agent und ein abgesicherter Produktions-Agent jeweils auf das gewünschte Signal eingestellt werden. +Du bestimmst mit einer einzigen **Empfindlichkeits**-Einstellung (niedrig, mittel oder hoch), wie intensiv gesucht wird – damit ein lauter Staging-Agent und ein streng konfigurierter Produktions-Agent jeweils auf das gewünschte Signal abgestimmt werden können. ## Jede Empfehlung kommt mit Belegen -Sie müssen einem Befund niemals blind vertrauen. Jede Empfehlung zitiert die genauen Sessions, aus denen sie stammt, sowie das SQL, das sie aufgedeckt hat – so können Sie die Beweise öffnen und das Problem mit einem Klick bestätigen, anstatt eine Behauptung rückwärts analysieren zu müssen. +Du musst einen Fund nie auf Treu und Glauben akzeptieren. Jede Empfehlung zitiert die genauen Sessions, aus denen sie stammt, und das SQL, das sie zutage gefördert hat – so kannst du die Belege mit einem Klick öffnen und das Problem bestätigen, anstatt einen Befund rückwärts nachvollziehen zu müssen. -Wenn ein Befund ein durchgesickertes Credential betrifft, geht er einen Schritt weiter und verlinkt die einzelnen übereinstimmenden Events. Klicken Sie darauf und Sie landen genau an diesem Moment in der Session, bereits markiert – nicht am Anfang eines langen Transkripts, durch das Sie scrollen müssen. Der Link benennt das Event; er kopiert das erkannte Secret niemals in den Befund, sodass das Lesen eines Befunds kein zweiter Ort ist, an dem Ihr Credential aufgezeichnet ist. Falls ein Event nicht mehr vorhanden ist, weil die Session Ihr Aufbewahrungsfenster überschritten hat, teilt die Seite das klar mit, anstatt Sie im Unklaren zu lassen. +Wenn ein Fund ein durchgesickertes Credential betrifft, geht er noch einen Schritt weiter und verlinkt die einzelnen Events, die er gefunden hat. Klicke auf eines und du landest genau in jenem Moment in der Session, bereits markiert – nicht am Anfang eines langen Transkripts, das du erst durchscrollen müsstest. Der Link benennt das Event; das erkannte Secret wird niemals in den Fund kopiert, damit das Lesen eines Funds nicht zu einer zweiten Stelle wird, an der dein Credential aufgeschrieben ist. Falls ein Event nicht mehr vorhanden ist, weil die Session deinen Aufbewahrungszeitraum überschritten hat, sagt die Seite das klar und deutlich – anstatt dich im Unklaren zu lassen, ob du auf das Falsche geklickt hast. -Das ist auch das, was Audits ehrlich hält. Der Server prüft, ob jede zitierte Session tatsächlich existiert, und **verwirft jede Empfehlung, deren Beweise nicht standhalten** – das Audit untersucht also, erfindet aber nie. Was auf Ihrer Liste landet, ist real, reproduzierbar und nach Relevanz gerankt, mit den größten Verbesserungen ganz oben. +Das ist auch das, was Audits ehrlich hält. Der Server prüft, ob jede zitierte Session tatsächlich existiert, und **verwirft jede Empfehlung, deren Belege nicht standhalten** – das Audit untersucht also, erfindet aber nie. Was auf deiner Liste landet, ist real, reproduzierbar und nach Relevanz priorisiert, mit den größten Gewinnen ganz oben. -## Aus einer Lösung eine Absicherung machen +## Einen Fix in eine Guardrail umwandeln -Ein Problem zu beheben ist nur die halbe Miete. Die andere Hälfte ist sicherzustellen, dass es nicht still und leise zurückkehren kann. Jeder Befund enthält eine **Ein-Klick-Verknüpfung, die einen Wiederholungs-Alert entwirft**, vorausgefüllt mit einem sinnvollen Ausgangstrigger, den Sie anpassen können. Schließen Sie den Befund, aktivieren Sie den Alert – und wenn dieses Muster das nächste Mal auftaucht, werden Sie benachrichtigt, anstatt es bei einem zukünftigen Audit neu zu entdecken. +Ein Problem zu beheben ist nur die halbe Miete. Die andere Hälfte besteht darin, sicherzustellen, dass es nicht still und heimlich wiederkommt. Jeder Fund enthält eine **Ein-Klick-Verknüpfung, die einen Wiederholungs-Alert entwirft**, vorausgefüllt mit einem sinnvollen Starttrigger, den du anpassen kannst. Schließe den Fund, aktiviere den Alert, und beim nächsten Auftreten dieses Musters wirst du benachrichtigt, anstatt es bei einem zukünftigen Audit neu zu entdecken. -## Wo Sie es finden +## Wo du es findest -Audits befinden sich im Dashboard unter **`//audits`** (Seitenleiste zu *analyze* zu *audits*). Das Anzeigen von Läufen und Befunden erfordert **`audits:read`**; das Erstellen, Bearbeiten und Bearbeiten von Audits erfordert **`audits:write`**. Legen Sie Umfang und Rhythmus eines Audits fest und klicken Sie auf **Run now**, wenn Sie sofort Ergebnisse möchten, ohne auf den nächsten geplanten Lauf zu warten. +Audits befinden sich im Dashboard unter **`//audits`** (Seitenleiste zu *analyze* und dann zu *audits*). Das Anzeigen von Läufen und Funden erfordert **`audits:read`**; das Erstellen, Bearbeiten und Priorisieren von Audits erfordert **`audits:write`**. Lege Umfang und Rhythmus eines Audits fest und klicke dann auf **Run now**, wenn du sofort Ergebnisse möchtest, anstatt auf den nächsten geplanten Durchlauf zu warten. -## Verwandtes +## Verwandte Themen -- [Alerts](/de/agenteye/alerts): Werden Sie benachrichtigt, sobald ein Schwellenwert, den Sie bereits kennen, überschritten wird. -- [Evaluations](/de/agenteye/evaluations): Bewerten Sie jeden Lauf, damit Qualitätsregressionen von selbst auffallen. -- [Error tracking](/de/agenteye/error-tracking): Gruppieren und verfolgen Sie die Fehler, die Ihre Agents ausgeben. -- [Incidents](/de/agenteye/incidents): Verfolgen Sie ein von einem Audit aufgedecktes Problem bis zu seiner Lösung. \ No newline at end of file +- [Alerts](/de/agenteye/alerts): Werde benachrichtigt, sobald ein dir bekannter Schwellenwert überschritten wird. +- [Evaluations](/de/agenteye/evaluations): Bewerte jeden Lauf, damit Qualitätsregressionen von selbst auffallen. +- [Error tracking](/de/agenteye/error-tracking): Gruppiere und verfolge die Fehler, die deine Agents werfen. +- [Incidents](/de/agenteye/incidents): Verfolge ein von einem Audit aufgedecktes Problem bis zur Lösung. \ No newline at end of file diff --git a/docs/de/agenteye/cli-and-agents.mdx b/docs/de/agenteye/cli-and-agents.mdx index b8425520..9539fe06 100644 --- a/docs/de/agenteye/cli-and-agents.mdx +++ b/docs/de/agenteye/cli-and-agents.mdx @@ -4,7 +4,7 @@ description: "Ihr gesamtes Failproof AI Observability-Deployment, einen Befehl e --- -Ihr gesamtes Failproof AI Observability-Deployment, einen Befehl entfernt. Prüfen Sie die Produktion, erstellen Sie einen API-Schlüssel oder bestätigen Sie einen Vorfall, ohne Ihr Terminal zu verlassen – und automatisieren Sie alles in CI oder lassen Sie einen Coding-Agenten es auf Englisch erledigen. +Ihr gesamtes Failproof AI Observability-Deployment, einen Befehl entfernt. Überprüfen Sie die Produktion, erstellen Sie einen API-Key oder bestätigen Sie einen Incident, ohne Ihr Terminal zu verlassen – und automatisieren Sie das alles in CI oder lassen Sie einen Coding-Agent es auf Ihr Geheiß hin erledigen. ```bash pipx install agenteye @@ -12,44 +12,44 @@ agenteye login --email you@example.com # a 6-digit code lands in your inbox agenteye --json sessions --since 24h # every agent run from the last day, newest first ``` -*Das `agenteye` CLI kommuniziert mit Ihrem Dashboard. Es ist ein anderes Werkzeug als der Collector, der Events an den Server sendet.* +*Die `agenteye` CLI kommuniziert mit Ihrem Dashboard. Sie ist ein anderes Werkzeug als der Collector, der Events an den Server übermittelt.* ## Ihr gesamtes Deployment, einen Befehl entfernt -Hören Sie auf, zwischen Tabs zu wechseln, um eine schnelle Frage zu beantworten. Das `agenteye` CLI liest Ihre Daten und verwaltet Ihre Organisation aus einer einzigen Binary heraus – eine Überprüfung, die früher das Durchklicken des Dashboards erforderte, ist jetzt eine einzige Zeile, die Sie erneut ausführen, als Alias anlegen oder in ein Runbook einfügen können. Sie erhalten vier Bereiche: +Hören Sie auf, zwischen Tabs zu wechseln, nur um eine schnelle Frage zu beantworten. Die `agenteye` CLI liest Ihre Daten und verwaltet Ihre Organisation über eine einzige Binary – eine Prüfung, die früher bedeutete, durchs Dashboard zu klicken, wird zur einzeiligen Abfrage, die Sie wiederholen, als Alias anlegen oder in ein Runbook einfügen können. Es gibt vier Bereiche: - **Daten lesen:** `sessions`, `events`, `evals` und `errors`, gefiltert nach Zeit, Agent und Umgebung. - **Organisation verwalten:** `keys`, `users`, `settings`, `alerts` und `incidents`. -- **Analysen ausführen:** gespeichertes SQL sowie ein Ad-hoc-`query`-Runner über Ihre Event-Daten. -- **Den Assistenten befragen:** `agent ask` erreicht denselben schreibgeschützten Analysten, mit dem Sie im Dashboard chatten. +- **Analysen ausführen:** gespeichertes SQL plus ein Ad-hoc-`query`-Runner über Ihre Event-Daten. +- **Den Assistenten befragen:** `agent ask` erreicht denselben read-only-Analysten, mit dem Sie im Dashboard chatten. -Installieren Sie es einmalig mit `pipx`, melden Sie sich mit einem per E-Mail zugesandten 6-stelligen Code an, und Sie sind startklar. Die Sitzung dauert etwa einen Tag; führen Sie `agenteye login` erneut aus, wenn sie abläuft. Nutzen Sie es für schnelle Produktionsprüfungen, das Bereitstellen eines Schlüssels oder die Triage eines aktiven Vorfalls – alles ohne Browser: +Installieren Sie es einmalig mit `pipx`, melden Sie sich mit einem per E-Mail zugesandten 6-stelligen Code an, und Sie sind startklar. Die Sitzung hält etwa einen Tag; führen Sie `agenteye login` erneut aus, wenn sie abläuft. Nutzen Sie die CLI für Stichproben in der Produktion, zum Bereitstellen eines Keys oder zur Triage eines aktiven Incidents – alles ohne Browser: ```bash -agenteye errors --since 24h --aggregate # what is breaking, grouped by error type -agenteye incidents list --state firing # what is on fire right now -agenteye keys create ci --add events:add # a key that can only push events, secret shown once +agenteye errors --since 24h --aggregate # was bricht, gruppiert nach Fehlertyp +agenteye incidents list --state firing # was gerade auf fire ist +agenteye keys create ci --add events:add # ein Key, der nur Events pushen kann, Secret wird einmalig angezeigt ``` -Eine wichtige Konvention: Globale Optionen wie `--json` stehen vor dem Befehl. `agenteye --json sessions` ist korrekt; `agenteye sessions --json` ist es nicht. +Eine wichtige Gewohnheit: Globale Optionen wie `--json` kommen vor dem Befehl. `agenteye --json sessions` ist korrekt; `agenteye sessions --json` ist es nicht. -## Skripte und CI-Integration +## Automatisieren und in CI einbinden -Jeder Befehl akzeptiert `--json`, und das ändert alles. Sauberes JSON geht nach stdout, während Statusmeldungen und Warnungen für Menschen nach stderr gehen – ein `--json`-Output lässt sich also direkt in `jq` pipen, ohne störende Zeilen herausfiltern zu müssen. Das macht das CLI gleichermaßen nützlich für Sie an der Eingabeaufforderung und für einen Coding-Agenten, der die Ausgabe verarbeitet: +Jeder Befehl akzeptiert `--json`, und das verändert alles. Sauberes JSON geht auf stdout, während menschlich lesbare Statusmeldungen und Warnungen auf stderr landen – ein `--json`-Output lässt sich also direkt in `jq` pipen, ohne störende Zeilen herausfiltern zu müssen. Das macht die CLI gleichermaßen geeignet für die interaktive Nutzung am Terminal und für Coding-Agents, die den Output verarbeiten: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -Es ist für den unbeaufsichtigten Betrieb ausgelegt. Bestätigungsabfragen werden automatisch übersprungen, wenn kein Terminal angebunden ist – nichts bleibt in einer Pipeline hängen –, und jeder Befehl gibt einen aussagekräftigen Exit-Code zurück: `0` Erfolg, `4` nicht eingeloggt, `5` fehlende Berechtigung (die Meldung nennt sie, z. B. `alerts:write`), `3` Dashboard nicht erreichbar. Ein Skript kann bei `4` eine erneute Authentifizierung einleiten oder bei `5` genau sagen, was bei einem Administrator anzufragen ist, anstatt ohne Rückmeldung zu scheitern. +Sie ist für den unbeaufsichtigten Betrieb ausgelegt. Bestätigungsabfragen werden automatisch übersprungen, wenn kein Terminal angebunden ist, sodass nichts in einer Pipeline hängt. Jeder Befehl gibt einen aussagekräftigen Exit-Code zurück: `0` Erfolg, `4` nicht eingeloggt, `5` fehlende Berechtigung (die Meldung nennt sie explizit, z. B. `alerts:write`), `3` Dashboard nicht erreichbar. Ein Skript kann bei `4` eine erneute Authentifizierung anstoßen oder bei `5` genau anzeigen, welche Berechtigung Sie bei einem Admin anfragen müssen, anstatt stumm zu scheitern. -## Einen Coding-Agenten auf Englisch steuern lassen +## Einen Coding-Agent im Klartext steuern lassen -Noch besser: Sie sollten sich all diese Flags gar nicht merken müssen. Die **CLI-Skill** ist ein kleiner Agent-Skill-Ordner namens `agenteye-cli`, der einen Coding-Agenten wie Claude Code oder Codex beibringt, das CLI auf Basis von Anfragen in natürlicher Sprache zu bedienen. Fragen Sie „Ist heute etwas defekt?" und der Agent wählt den passenden Befehl, führt ihn in Ihrem Namen aus und antwortet in Prosa. +Noch besser: Sie müssen sich diese Flags gar nicht merken. Der **CLI-Skill** ist ein kleines Agent-Skill-Verzeichnis namens `agenteye-cli`, das einem Coding-Agent wie Claude Code oder Codex beibringt, die CLI auf Basis von Anfragen in natürlicher Sprache zu bedienen. Fragen Sie „Ist heute irgendetwas kaputt?" und der Agent wählt den passenden Befehl, führt ihn in Ihrem Namen aus und antwortet in Prosa. -Für Claude Code legen Sie den `agenteye-cli`-Ordner in `~/.claude/skills/` ab – er wird automatisch erkannt. Failproof AI Observability stellt den Ordner bereit; es ist nichts Zusätzliches zu installieren, da er nur das bereits installierte CLI steuert. Melden Sie sich zunächst selbst an: Die Skill kann den Login per E-Mail-Code nicht für Sie abschließen. +Für Claude Code legen Sie den `agenteye-cli`-Ordner in `~/.claude/skills/` ab – er wird automatisch erkannt. Failproof AI Observability stellt den Ordner bereit; es gibt nichts zusätzlich zu installieren, da der Skill nur die CLI steuert, die Sie bereits installiert haben. Melden Sie sich selbst zuerst an: Der Skill kann den per E-Mail versandten Code-Login nicht für Sie abschließen. -Da der Agent das CLI unter Ihrer Identität ausführt, kann er alles tun, was Ihr Login erlaubt – Lesen und Schreiben gleichermaßen: Schlüssel erstellen, Einstellungen ändern, Vorfälle auflösen. Die „Sind Sie sicher?"-Abfrage des CLI wird für einen Agenten nicht ausgelöst, daher ist die Skill so gestaltet, dass sie den genauen Befehl nennt und auf Ihre Zustimmung wartet, bevor eine Änderung vorgenommen wird. Sie sind der Bestätigungsschritt. +Da der Agent die CLI in Ihrem Namen ausführt, kann er alles tun, was Ihr Login erlaubt – Lese- und Schreibzugriffe gleichermaßen: Keys erstellen, Einstellungen ändern, Incidents auflösen. Der „Sind Sie sicher?"-Prompt der CLI wird für einen Agent nicht ausgelöst, daher ist der Skill so gestaltet, dass er den genauen Befehl benennt und Ihr OK abwartet, bevor er eine Änderung vornimmt. Sie sind der Bestätigungsschritt. ```text you Why did session run-001 fail? @@ -72,9 +72,9 @@ you yes agent Done. Key "ci" created with events:add only. The secret is shown once, so store it now. ``` -## Weiterführendes +## Weiterführende Links - [CLI-Referenz](/de/agenteye/cli): Alle Befehle, Flags und JSON-Strukturen. -- [CLI-Rezepte für Agenten](/de/agenteye/cli-recipes): Kopierfertige `jq`-Muster und Exit-Code-Behandlung. -- [CLI-Agent-Skill](/de/agenteye/cli-skill): Installation und Verwendung der `agenteye-cli`-Skill. +- [CLI-Rezepte für Agents](/de/agenteye/cli-recipes): Fertige `jq`-Muster und Exit-Code-Behandlung zum Kopieren. +- [CLI-Agent-Skill](/de/agenteye/cli-skill): Den `agenteye-cli`-Skill installieren und ausführen. - [KI-Assistent](/de/agenteye/assistant): Der Dashboard-Analyst, mit dem `agent ask` kommuniziert. \ No newline at end of file diff --git a/docs/de/agenteye/cli-recipes.mdx b/docs/de/agenteye/cli-recipes.mdx index e0645365..9b5d059a 100644 --- a/docs/de/agenteye/cli-recipes.mdx +++ b/docs/de/agenteye/cli-recipes.mdx @@ -1,77 +1,77 @@ --- -title: "CLI-Rezepte für Agenten" -description: "Copy-paste-Abfragemuster und jq-Rezepte, die Sitzungs-, Ereignis- und Auswertungsdaten in etwas umwandeln, das ein Skript oder Coding-Agent automatisieren kann." +title: "CLI-Rezepte für Agents" +description: "Kopierfertige Abfragemuster und jq-Rezepte, die Sitzungs-, Ereignis- und Auswertungsdaten in etwas verwandeln, das ein Skript oder ein Coding-Agent automatisieren kann." --- -Sitzungs-, Ereignis- und Auswertungsdaten direkt aus einem Skript oder Coding-Agenten abrufen (und Neuauswertungen auslösen), mit sauberem JSON auf stdout, das direkt in `jq` weitergeleitet werden kann. Diese Rezepte verwandeln die Daten von Failproof AI Observability in etwas, das ein Terminal-Nutzer oder ein KI-Coding-Agent (Claude Code, Cursor) abfragen und automatisieren kann – ohne durch das Dashboard zu klicken. +Sitzungs-, Ereignis- und Auswertungsdaten direkt aus einem Skript oder Coding-Agent abrufen (und Neubewertungen auslösen) – mit sauberem JSON auf stdout, das direkt in `jq` weitergeleitet werden kann. Diese Rezepte machen die Daten von Failproof AI Observability für einen Terminal-Nutzer oder einen KI-Coding-Agent (Claude Code, Cursor) abfrag- und automatisierbar, ohne durch das Dashboard zu klicken. -Die folgenden Muster sind copy-paste-bereit für die Failproof AI Observability CLI (`agenteye`). Installation, Authentifizierung und die vollständige Optionsliste finden Sie unter [CLI](/de/agenteye/cli); führen Sie `agenteye -h` oder `agenteye -h` für die integrierte Hilfe aus. +Die folgenden Muster sind kopierfertig für die Failproof AI Observability CLI (`agenteye`). Installation, Authentifizierung und die vollständige Optionsliste finden Sie unter [CLI](/de/agenteye/cli); führen Sie `agenteye -h` oder `agenteye -h` für die integrierte Hilfe aus. ## Grundregeln 1. **Globale Optionen kommen *vor* dem Befehl.** `agenteye --json sessions` ist korrekt; `agenteye sessions --json` ist es nicht. Die globalen Optionen sind `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **`--json` übergeben, wenn Sie die Ausgabe parsen.** Daten gehen als JSON an **stdout**; menschlich lesbare Statusmeldungen und Fehler gehen an **stderr**, sodass stdout sauber in `jq` weitergeleitet werden kann. -3. **Auf den Exit-Code verzweigen**, nicht auf stderr-Text: `0` ok · `1` unerwarteter Fehler · `2` ungültige Argumente · `3` Dashboard nicht erreichbar · `4` nicht angemeldet oder abgelaufen · `5` fehlende Berechtigung · `6` Ressource nicht gefunden. -4. **Mit `-h` erkunden.** Jeder Befehl dokumentiert seine Filter, Werteformate und JSON-Struktur. +2. **`--json` übergeben, wenn Sie die Ausgabe parsen.** Daten gehen als JSON an **stdout**; menschenlesbare Statusinformationen und Fehler gehen an **stderr**, sodass stdout sauber in `jq` weitergeleitet werden kann. +3. **Verzweigen Sie anhand des Exit-Codes**, nicht anhand von stderr-Text: `0` ok · `1` unerwarteter Fehler · `2` ungültige Argumente · `3` Dashboard nicht erreichbar · `4` nicht eingeloggt oder abgelaufen · `5` fehlende Berechtigung · `6` Ressource nicht gefunden. +4. **Erkunden Sie mit `-h`.** Jeder Befehl dokumentiert seine Filter, Werteformate und die JSON-Struktur. ## Einmalige Einrichtung ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # damit Sie --base-url nicht wiederholen müssen -agenteye login --email you@example.com # per E-Mail zugesandten Code einfügen; gültig ~24h +agenteye login --email you@example.com # den per E-Mail gesendeten Code einfügen; gültig ~24h ``` ## Authentifizierung vor der Arbeit prüfen -`whoami` löst bei einer fehlenden oder abgelaufenen Sitzung keinen Fehler aus; stattdessen meldet es `logged_in:false`, sodass ein Agent den Authentifizierungsstatus sicher prüfen kann. (Es kann trotzdem mit einem Nicht-Null-Exit-Code enden, wenn keine Basis-URL gesetzt ist oder das Dashboard nicht erreichbar ist.) +`whoami` gibt bei einer fehlenden oder abgelaufenen Sitzung keinen Fehler aus; stattdessen meldet es `logged_in:false`, sodass ein Agent den Auth-Status sicher abfragen kann. (Es kann dennoch mit einem Nicht-Null-Exit-Code beenden, wenn keine Basis-URL gesetzt ist oder das Dashboard nicht erreichbar ist.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then - echo "Nicht authentifiziert. Ausführen: agenteye login" >&2; exit 1 + echo "Not authenticated. Run: agenteye login" >&2; exit 1 fi ``` -## Fehlgeschlagene oder niedrig bewertete Sitzungen finden +## Fehlerhafte oder schlecht bewertete Sitzungen finden ```bash -# Sitzungen der letzten 24h, deren Auswertung einen Fehler ergab +# Sitzungen der letzten 24h, deren Auswertung fehlgeschlagen ist agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# Auswertungen mit helpfulness-Score <= 0.5, für einen Agenten +# Auswertungen mit einem Helpfulness-Score <= 0.5, für einen bestimmten Agent agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Score-Filterung liegt bei **`evals`**, nicht bei `sessions`. `--score KEY:MIN..MAX` ist wiederholbar und AND-kombiniert; beide Grenzen sind optional (`..0.5` bedeutet ≤ 0,5, `0.9..` bedeutet ≥ 0,9). Sie können bis zu 20 Score-Filter pro Anfrage übergeben; mehr gibt HTTP 400 zurück. `sessions` teilt die Filter `--env`, `--status`, `--agent-id`, `--session-id` und den Zeitbereich mit `evals`, hat aber kein `--score`. +Score-Filterung ist in **`evals`** verfügbar, nicht in `sessions`. `--score KEY:MIN..MAX` ist wiederholbar und wird mit AND verknüpft; beide Grenzen sind optional (`..0.5` bedeutet ≤ 0,5, `0.9..` bedeutet ≥ 0,9). Pro Anfrage können bis zu 20 Score-Filter übergeben werden; mehr gibt HTTP 400 zurück. `sessions` teilt die Filter `--env`, `--status`, `--agent-id`, `--session-id` und den Zeitbereich mit `evals`, hat aber kein `--score`. ## Eine Sitzung von Anfang bis Ende lesen -Es gibt keinen einzelnen `session show`-Befehl. Kombinieren Sie den Ereignisverlauf mit der Auswertung der Sitzung: +Es gibt keinen einzelnen Befehl `session show`. Kombinieren Sie den Ereignisverlauf mit der Auswertung der Sitzung: ```bash # die neueste Auswertung der Sitzung (Status + Scores) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# jedes Ereignis im Durchlauf (--limit erhöhen für einen vollständigen Sweep) +# jedes Ereignis im Durchlauf (--limit für einen vollständigen Durchlauf erhöhen) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# nur die Tool-Aufrufe in einer Sitzung (--full ist erforderlich, um den rohen Payload zu erhalten) +# nur die Tool-Aufrufe einer Sitzung (--full ist erforderlich, um den rohen Payload zu erhalten) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **Hinweis:** Standardmäßig liest `events` einen schnellen, payload-freien Feed. Jedes Ereignis enthält eine serverberechnete einzeilige `summary` sowie Flags wie `is_error` und Token-Anzahlen, aber `payload` wird als `{}` zurückgegeben. Um den rohen Payload abzurufen, fügen Sie `--full` (oder `--fields payload`) hinzu. Der vollständige Feed ist bei großen Datenmengen langsamer, daher begrenzt halten: `--full` mit einer einzelnen `--session-id` kombinieren. +> **Hinweis:** Standardmäßig liest `events` einen schnellen Feed ohne Payloads. Jedes Ereignis enthält eine serverseitig berechnete einzeilige `summary` sowie Flags wie `is_error` und Token-Anzahlen, aber `payload` wird als `{}` zurückgegeben. Um den rohen Payload abzurufen, fügen Sie `--full` (oder `--fields payload`) hinzu. Der vollständige Feed ist bei großen Datenmengen langsamer, daher sollten Sie ihn eingrenzen: Kombinieren Sie `--full` mit einer einzelnen `--session-id`. ## Alles abrufen (Paginierung) Ergebnisse sind neueste-zuerst und cursor-paginiert. ```bash -# einmalig: bis zu 500 Zeilen in 200-Zeilen-Seiten abrufen +# in einem Schritt: bis zu 500 Zeilen in 200-Zeilen-Seiten abrufen agenteye --json events --session-id run-001 --limit 500 --all > events.json -# manuelles Paginieren: next_cursor zurückführen +# manuelle Paginierung: next_cursor zurückführen page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -79,14 +79,14 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## Ausgabe mit --fields einschränken -Die Schlüssel (sowohl in der Tabelle als auch bei `--json`) einschränken, um zu reduzieren, was ein Agent lesen muss. +Die Schlüssel (sowohl in der Tabelle als auch mit `--json`) einschränken, um zu reduzieren, was ein Agent lesen muss. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Unbekannte Feldnamen werden (mit Exit `2`) zurückgewiesen und die gültige Liste angezeigt – eine einfache Möglichkeit, Feldnamen zu entdecken. +Unbekannte Feldnamen werden (mit Exit-Code `2`) zusammen mit der gültigen Liste abgelehnt – eine einfache Methode, Feldnamen zu entdecken. ## Gültige Filterwerte erkunden @@ -96,22 +96,22 @@ agenteye --json list tools | jq -r '.values[]' # Tool-Namen; auch agent agenteye --json list score_filters | jq -r '.values[]' # gültiger KEY für --score KEY:MIN..MAX ``` -## Organisation auswählen (Multi-Tenant) +## Org auswählen (Multi-Tenant) -Wenn Sie zu mehr als einer Organisation gehören, wählen Sie den aktiven Tenant beim Login (er wird gespeichert): +Wenn Sie mehr als einer Org angehören, wählen Sie den aktiven Mandanten beim Login (er wird gespeichert): ```bash -agenteye login --org acme --email you@corp.com # Tenant im gleichen Schritt wie Login setzen +agenteye login --org acme --email you@corp.com # den Mandanten im gleichen Schritt wie den Login setzen agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # für einen Befehl überschreiben +agenteye --org globex --json sessions --since 24h # für einen einzelnen Befehl überschreiben ``` -Ein Multi-Org-Login ohne `--org` endet mit einem Nicht-Null-Exit-Code und gibt die auswählbaren Organisationen aus. +Ein Multi-Org-Login ohne `--org` beendet sich mit einem Nicht-Null-Exit-Code und gibt die verfügbaren Orgs zur Auswahl aus. -## Einen API-Schlüssel für SDK/Collector bereitstellen +## Einen API-Key für das SDK/den Collector bereitstellen ```bash -# das Secret wird EINMAL ausgegeben; mit --json ist es das .key-Feld +# Das Secret wird EINMALIG ausgegeben; mit --json ist es das Feld .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # rotieren; agenteye keys disable ci-bot --yes zum Widerrufen ``` @@ -120,10 +120,10 @@ agenteye keys regenerate ci-bot --yes # rotieren; agenteye keys disable ci-bo ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # eine gespeicherte Abfrage + ein positioneller $1 +agenteye --json query run errs --arg prod | jq '.rows' # eine gespeicherte Abfrage + ein positionelles $1 ``` -## Einen Vorfall nicht-interaktiv bearbeiten +## Einen Vorfall nicht-interaktiv triagieren ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **Hinweis:** Mutationen überspringen ihre Bestätigungsaufforderung automatisch unter `--json` oder wenn stdin kein TTY ist, sodass Agenten nie hängen bleiben; übergeben Sie `--yes`/`-y`, um sie anderswo explizit zu überspringen. +> **Hinweis:** Mutationen überspringen ihre Bestätigungsaufforderung automatisch unter `--json` oder wenn stdin kein TTY ist, sodass Agents nie hängen bleiben; übergeben Sie `--yes`/`-y`, um sie anderswo explizit zu überspringen. ## Exit-Code-Behandlung in einem Skript @@ -140,10 +140,10 @@ agenteye incidents resolve "$id" --yes out=$(agenteye --json sessions --since 1h) || code=$? case "${code:-0}" in 0) echo "$out" | jq '.sessions | length' ;; - 4) echo "Sitzung abgelaufen - 'agenteye login' ausführen." >&2 ;; - 5) echo "Fehlende Berechtigung (Admin nach evaluations:read fragen)." >&2 ;; - 3) echo "Dashboard nicht erreichbar - URL prüfen." >&2 ;; - *) echo "Unerwarteter Fehler (Exit ${code})." >&2 ;; + 4) echo "Session expired - run 'agenteye login'." >&2 ;; + 5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;; + 3) echo "Dashboard unreachable - check the URL." >&2 ;; + *) echo "Unexpected error (exit ${code})." >&2 ;; esac ``` @@ -158,7 +158,7 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` einmalig angezeigt) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` wird einmalig angezeigt) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | @@ -169,11 +169,11 @@ esac - Jedes **Auswertungs**-Element (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Jedes **Sitzungs**-Element (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -Das `--fields` jedes Befehls akzeptiert genau die Feldnamen seines eigenen Elements. Der Satz unterscheidet sich zwischen `sessions` und `evals`, sodass ein für eines gültiger Name vom anderen abgelehnt werden kann. +Das `--fields` jedes Befehls akzeptiert genau die Feldnamen seines eigenen Elements. Die Menge unterscheidet sich zwischen `sessions` und `evals`, daher kann ein für eine Ressource gültiger Name von der anderen abgelehnt werden. ## Nächste Schritte - [CLI](/de/agenteye/cli): Installation, Authentifizierung und die vollständige Optionsreferenz für jeden Befehl. - [CLI-Agent-Skill](/de/agenteye/cli-skill): Diese Rezepte als Skill verpacken, den Ihr Coding-Agent laden kann. -- [API-Schlüssel](/de/agenteye/api-keys): Schlüssel erstellen und eingrenzen, mit denen sich CLI, SDK und Collector authentifizieren. +- [API-Keys](/de/agenteye/api-keys): Keys erstellen und einschränken, mit denen sich CLI, SDK und Collector authentifizieren. - [Python SDK](/de/agenteye/python-sdk): Ereignisse in Failproof AI Observability senden, damit diese Rezepte Daten zum Abfragen haben. \ No newline at end of file diff --git a/docs/de/agenteye/cli-skill.mdx b/docs/de/agenteye/cli-skill.mdx index 3a39c7e2..88533793 100644 --- a/docs/de/agenteye/cli-skill.mdx +++ b/docs/de/agenteye/cli-skill.mdx @@ -1,43 +1,43 @@ --- title: "Failproof AI Observability CLI Agent Skill" -description: "Fragen Sie Ihren Coding-Agenten, ob heute etwas nicht funktioniert, und lassen Sie ihn die Antwort aus Ihren Live-Failproof AI Observability-Daten beziehen – ohne Befehle auswendig lernen zu müssen." +description: "Fragen Sie Ihren Coding-Agent einfach: Gibt es heute Probleme? Er beantwortet die Frage direkt aus Ihren Live-Daten von Failproof AI Observability – ohne Befehle auswendig lernen zu müssen." --- -Fragen Sie Ihren Coding-Agenten *„Ist heute irgendetwas kaputt?"* und lassen Sie ihn die Antwort aus Ihren Live-Failproof AI Observability-Daten beziehen – ohne Befehle auswendig lernen zu müssen. Der **Failproof AI Observability CLI Skill** (`agenteye-cli`) ist ein *Agent Skill*: ein kleiner Ordner mit Anweisungen, den ein Coding-Agent wie Claude Code oder Codex bei Bedarf lädt. Er bringt dem Agenten bei, Ihre Observability-Deployment über die [`agenteye` CLI](/de/agenteye/cli) anhand von Anfragen in normalem Englisch zu bedienen – etwa *„Gib CI einen Schlüssel, der nur Events pushen kann"* oder *„Bestätige den ausgelösten Incident und weise ihn mir zu."* +Fragen Sie Ihren Coding-Agent einfach *„Gibt es heute irgendwelche Probleme?"* – er antwortet Ihnen direkt aus Ihren Live-Daten von Failproof AI Observability, ohne dass Sie einen einzigen Befehl auswendig kennen müssen. Der **Failproof AI Observability CLI Skill** (`agenteye-cli`) ist ein *Agent Skill*: ein kleiner Ordner mit Anweisungen, den ein Coding-Agent wie Claude Code oder Codex bei Bedarf lädt. Er bringt dem Agent bei, Ihr Observability-Deployment über die [`agenteye` CLI](/de/agenteye/cli) durch Anfragen in natürlicher Sprache zu bedienen – zum Beispiel *„Gib CI einen Schlüssel, der nur Events pushen kann"* oder *„Bestätige den aktiven Incident und weise ihn mir zu."* -Es handelt sich **nicht** um einen Dienst oder eine separate Binärdatei; es gibt nichts zu deployen. Es setzt auf der bereits installierten CLI auf: Der Agent ruft `agenteye --json …` auf, analysiert das saubere JSON und antwortet Ihnen in Prosaform. Alles, was er tun kann, könnten Sie selbst durch Eingabe derselben Befehle tun. +Dies ist **kein** Service und keine separate Binärdatei – es gibt nichts zu deployen. Der Skill setzt auf der bereits installierten CLI auf: Der Agent ruft `agenteye --json …` auf, parst das saubere JSON und antwortet Ihnen in Prosa. Alles, was er tun kann, könnten Sie auch selbst durch Eingabe derselben Befehle erreichen. --- ## Verhältnis zu den anderen Failproof AI Observability-Schnittstellen -Failproof AI Observability bietet Ihnen vier Wege, um auf dieselben Daten und Steuerungsmöglichkeiten zuzugreifen. Sie ergänzen sich gegenseitig: +Failproof AI Observability bietet vier Möglichkeiten, auf dieselben Daten und Funktionen zuzugreifen. Sie ergänzen sich gegenseitig: -| Schnittstelle | Was es ist | Wo es läuft | Verwenden Sie es, wenn | +| Schnittstelle | Was es ist | Wo es läuft | Wann Sie es verwenden | |---|---|---|---| -| **[CLI](/de/agenteye/cli)** | Die Befehls-/Flag-Referenz für `agenteye` | Ihr Terminal | Sie einen bestimmten Befehl ausführen oder skripten möchten | -| **[CLI-Rezepte](/de/agenteye/cli-recipes)** | Copy-paste-`jq`/Pipeline-Muster | Ihr Terminal / Skripte | Sie die CLI in Automatisierungen einbinden | -| **CLI Skill** (dieses Dokument) | Eine natürlichsprachige Eingabetür zur CLI | Ihr Coding-Agent, auf Ihrer Workstation | Sie einfach fragen und den Agenten den Befehl wählen lassen möchten | -| **[Evaluator Skill](/de/agenteye/evaluator-skill)** | Ein verwandter Skill, der Ihren Scoring-Dienst entwirft und aufbaut | Ihr Coding-Agent, auf Ihrer Workstation | Sie Eval-Scores *erstellen* möchten, anstatt sie zu lesen | -| **[Python SDK Skill](/de/agenteye/python-sdk-skill)** | Ein verwandter Skill, der Ihren Agenten instrumentiert, damit er überhaupt Telemetrie aussendet | Ihr Coding-Agent, auf Ihrer Workstation | Ihr Agent die Events *erzeugen* soll, die dieser Skill liest | -| **[In-Dashboard-KI-Assistent](/de/agenteye/assistant)** | Ein im Dashboard eingebetteter Chat | Serverseitig (im Dashboard) | Sie Q&A über Ihre Daten direkt im Dashboard wünschen | +| **[CLI](/de/agenteye/cli)** | Die Befehls- und Flag-Referenz für `agenteye` | Ihr Terminal | Wenn Sie einen bestimmten Befehl ausführen oder skripten möchten | +| **[CLI-Rezepte](/de/agenteye/cli-recipes)** | Copy-Paste-`jq`/Pipeline-Muster | Ihr Terminal / Skripte | Wenn Sie die CLI in Automatisierungen einbinden | +| **CLI Skill** (dieses Dokument) | Ein natürlichsprachiger Zugang zur CLI | Ihr Coding-Agent, auf Ihrer Workstation | Wenn Sie einfach fragen und den Agent den richtigen Befehl wählen lassen möchten | +| **[Evaluator Skill](/de/agenteye/evaluator-skill)** | Ein verwandter Skill, der Ihren Scoring-Service entwirft und aufbaut | Ihr Coding-Agent, auf Ihrer Workstation | Wenn Sie Eval-Scores *erzeugen* statt lesen möchten | +| **[Python SDK Skill](/de/agenteye/python-sdk-skill)** | Ein verwandter Skill, der Ihren Agent instrumentiert, sodass er Telemetrie aussendet | Ihr Coding-Agent, auf Ihrer Workstation | Wenn Ihr Agent die Events, die dieser Skill liest, erst *erzeugen* soll | +| **[In-Dashboard-KI-Assistent](/de/agenteye/assistant)** | Ein im Dashboard eingebetteter Chat | Serverseitig (im Dashboard) | Wenn Sie im Dashboard Fragen zu Ihren Daten stellen möchten | -Der Skill selbst hat keine eigenen Rechte; er übersetzt lediglich Ihre Worte in CLI-Aufrufe, die als Sie ausgeführt werden: +Der Skill selbst besitzt keine eigenen Berechtigungen; er übersetzt Ihre Worte lediglich in CLI-Aufrufe, die als Sie ausgeführt werden: ```mermaid flowchart TD - YOU["you: 'ack the firing incident'"] --> AGENT["coding agent (Claude Code / Codex)
loads the agenteye-cli skill"] + YOU["Sie: 'Bestätige den aktiven Incident'"] --> AGENT["Coding-Agent (Claude Code / Codex)
lädt den agenteye-cli Skill"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|your authenticated CLI session| API["Observability dashboard API"] + CLI -->|Ihre authentifizierte CLI-Sitzung| API["Observability Dashboard API"] ``` -### vs. dem In-Dashboard-KI-Assistenten: ein wichtiger Unterschied +### Abgrenzung zum In-Dashboard-KI-Assistenten -Dies sind zwei verschiedene Tools mit sehr unterschiedlichem Wirkungsradius: +Dies sind zwei grundlegend verschiedene Tools mit sehr unterschiedlichem Wirkungsbereich: -- Der **In-Dashboard-KI-Assistent** ([KI-Assistent](/de/agenteye/assistant)) ist ein im Dashboard eingebetteter Chat, der vom Agenten-Dienst unterstützt wird. Er ist **lesend plus genehmigungspflichtig beim Erstellen**: Er kann gespeicherte Abfragen und Dashboards entwerfen, aber jeder Schreibvorgang pausiert für Ihre ausdrückliche Klickgenehmigung, und er löscht nie. Er ist durch die Berechtigung `agent:use` geschützt und sieht immer nur Daten für die Organisation, die Sie gerade ansehen. -- Der **CLI Skill** läuft auf *Ihrer* Workstation innerhalb *Ihres* Coding-Agenten und steuert die `agenteye` CLI **als Sie**. Er kann die **gesamte CLI-Oberfläche nutzen, einschließlich Mutationen** (API-Schlüssel erstellen/rotieren/deaktivieren, Org-Einstellungen ändern, Incidents auflösen, gespeicherte Abfragen löschen) – begrenzt nur durch die Berechtigungen Ihres CLI-Logins. Gehen Sie damit genauso sorgfältig um, wie Sie diese Befehle manuell eingeben würden. +- Der **In-Dashboard-KI-Assistent** ([AI-Assistent](/de/agenteye/assistant)) ist ein im Dashboard eingebetteter Chat, der vom Agent-Service betrieben wird. Er ist **nur lesend plus genehmigungspflichtig bei Änderungen**: Er kann gespeicherte Queries und Dashboards entwerfen, aber jeder Schreibvorgang wartet auf Ihre ausdrückliche Bestätigung per Klick, und er löscht niemals. Er ist durch die Berechtigung `agent:use` geschützt und sieht ausschließlich Daten der Organisation, die Sie gerade betrachten. +- Der **CLI Skill** läuft auf *Ihrer* Workstation innerhalb *Ihres* Coding-Agents und steuert die `agenteye` CLI als **Sie**. Er kann den **vollen Funktionsumfang der CLI nutzen, einschließlich Mutationen** (API-Schlüssel erstellen/rotieren/deaktivieren, Organisationseinstellungen ändern, Incidents lösen, gespeicherte Queries löschen) – begrenzt nur durch die Berechtigungen Ihres CLI-Logins. Behandeln Sie ihn genauso sorgfältig, wie Sie die Befehle selbst eingeben würden. --- @@ -45,57 +45,57 @@ Dies sind zwei verschiedene Tools mit sehr unterschiedlichem Wirkungsradius: 1. Die **`agenteye` CLI ist installiert** und im `PATH` (siehe [CLI](/de/agenteye/cli)-Referenz: `pipx install agenteye`). 2. Ihre **Dashboard-URL** ist gesetzt (`AGENTEYE_DASHBOARD_URL`, oder der Agent übergibt `--base-url`). -3. Eine **eingeloggte Sitzung**: Führen Sie `agenteye login` selbst zuerst aus. Der Skill **kann** den per E-Mail versendeten Einmalcode-Login nicht für Sie abschließen; er wird Sie auffordern, `agenteye login` auszuführen, wenn die Sitzung fehlt oder abgelaufen ist (CLI-Exit-Code `4`). +3. Eine **aktive Sitzung**: Führen Sie zunächst selbst `agenteye login` aus. Der Skill **kann** den per E-Mail gesendeten Einmalcode-Login nicht für Sie abschließen; er weist Sie an, `agenteye login` auszuführen, wenn die Sitzung fehlt oder abgelaufen ist (CLI-Exit-Code `4`). --- -## Wo Sie ihn bekommen +## Bezugsquelle Der Skill ist in Failproof AIs öffentlicher Skills-Sammlung veröffentlicht: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -Nichts daran ist gesperrt – das Repository ist öffentlich, und der Skill benötigt keine eigenen Anmeldeinformationen, da er nur die **öffentliche** `agenteye` CLI gegen *Ihr* Dashboard treibt und dabei die Sitzung verwendet, mit der *Sie* eingeloggt sind. Sie müssen niemanden darum bitten. +Der Zugang ist nicht eingeschränkt – das Repository ist öffentlich, und der Skill benötigt keine eigenen Zugangsdaten, da er ausschließlich die **öffentliche** `agenteye` CLI gegen *Ihr* Dashboard betreibt und dabei die Sitzung nutzt, mit der *Sie* sich angemeldet haben. Sie müssen niemanden um Erlaubnis bitten. -Beachten Sie, dass er als eigener Ordner ausgeliefert wird und **nicht** im `pipx install agenteye`-Paket enthalten ist – suchen Sie dort also nicht danach. +Beachten Sie, dass der Skill als eigenständiger Ordner ausgeliefert wird und **nicht** im `pipx install agenteye`-Paket enthalten ist – suchen Sie ihn also nicht dort. ## Den Skill installieren -Der schnellste Weg ist die [`skills`](https://skills.sh) CLI, die den Ordner holt und dort ablegt, wo Ihr Agent sucht: +Der schnellste Weg ist die [`skills`](https://skills.sh) CLI, die den Ordner abruft und an den Ort legt, wo Ihr Agent sucht: ```bash # Claude Code, nur dieses Projekt npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -# jedes Projekt (installiert nach ~/.claude/skills/) +# alle Projekte (installiert nach ~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy # stattdessen Codex npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -Verwalten Sie ihn dann wie jeden anderen Skill: +Verwalten Sie ihn anschließend wie jeden anderen Skill: ```bash -npx skills list -a claude-code # was ist installiert -npx skills update agenteye-cli # neueste Version holen +npx skills list -a claude-code # installierte Skills anzeigen +npx skills update agenteye-cli # neueste Version laden npx skills remove agenteye-cli # entfernen ``` -Möchten Sie lieber manuell installieren? Ein Agent Skill ist nur ein Ordner mit einer `SKILL.md` (plus optionalen Referenzen), daher funktioniert auch das Kopieren: +Bevorzugen Sie manuelle Installation? Ein Agent Skill ist nur ein Ordner mit einer `SKILL.md` (plus optionalen Referenzen) – einfaches Kopieren funktioniert ebenfalls: -- **Claude Code**: Legen Sie den Ordner `agenteye-cli/` in `~/.claude/skills/` (jedes Projekt) oder `/.claude/skills/` (nur dieses Repository). Claude Code erkennt ihn automatisch – überprüfen Sie es mit der `/skills`-Liste oder stellen Sie einfach eine Frage, die zu seiner Beschreibung passt. -- **Codex (OpenAI)**: Codex liest dieselbe `SKILL.md`. Das enthaltene `agents/openai.yaml` setzt `allow_implicit_invocation: true`, sodass Codex den Skill automatisch auswählt, wenn eine Aufgabe passt; andernfalls rufen Sie ihn explizit als `$agenteye-cli` auf. +- **Claude Code**: Legen Sie den Ordner `agenteye-cli/` in `~/.claude/skills/` (alle Projekte) oder `/.claude/skills/` (nur dieses Repo). Claude Code erkennt ihn automatisch – prüfen Sie dies mit der `/skills`-Liste oder stellen Sie einfach eine Frage, die seiner Beschreibung entspricht. +- **Codex (OpenAI)**: Codex liest dieselbe `SKILL.md`. Das mitgelieferte `agents/openai.yaml` setzt `allow_implicit_invocation: true`, sodass Codex den Skill automatisch auswählt, wenn eine Aufgabe passt; andernfalls können Sie ihn explizit als `$agenteye-cli` aufrufen. --- -## Sicherheit: Mutationen zeigen KEINE Bestätigungsabfrage, wenn ein Agent die CLI ausführt +## Sicherheitshinweis: Mutationen fragen NICHT nach, wenn ein Agent die CLI ausführt -> **Warnung:** Lesen Sie dies, bevor Sie einen Agenten Änderungen vornehmen lassen. +> **Warnung:** Lesen Sie dies, bevor Sie einem Agent erlauben, Änderungen vorzunehmen. -Die `agenteye` CLI fragt normalerweise *„Sind Sie sicher?"* vor einer destruktiven Aktion. Sie **überspringt diese Bestätigung automatisch, wenn sie nicht an ein Terminal angehängt ist (was genau der Fall ist, wenn ein Coding-Agent sie ausführt), und `--json` überspringt sie ebenfalls.** Die Sicherheitsabfrage wird für den Agenten daher **nicht** ausgelöst. +Die `agenteye` CLI fragt normalerweise *„Sind Sie sicher?"* vor einer destruktiven Aktion. Sie **überspringt diese Bestätigung automatisch, sobald sie nicht an ein Terminal angeschlossen ist – genau so, wie ein Coding-Agent sie ausführt – und `--json` überspringt sie ebenfalls.** Die Sicherheitsabfrage wird für den Agent also **nicht** ausgelöst. -Der Skill ist so geschrieben, dass er dies ausgleicht: Er ist angewiesen, den genauen Befehl anzugeben, den er ausführen wird, und Ihre ausdrückliche **Zustimmung vor jeder Zustandsänderung** einzuholen. Halten Sie diese Disziplin aufrecht. Wenn Sie Failproof AI Observability über einen Agenten steuern, *sind Sie* der Bestätigungsschritt. Die zustandsändernden Befehle, auf die Sie achten sollten: +Der Skill ist darauf ausgelegt, dies zu kompensieren: Er ist angewiesen, den genauen auszuführenden Befehl anzugeben und Ihre ausdrückliche **Bestätigung einzuholen, bevor er irgendeinen Zustand verändert**. Halten Sie diese Disziplin aufrecht. Wenn Sie Failproof AI Observability über einen Agent steuern, *sind Sie* der Bestätigungsschritt. Die zustandsändernden Befehle, auf die Sie achten sollten: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` @@ -108,52 +108,52 @@ Der Skill ist so geschrieben, dass er dies ausgleicht: Er ist angewiesen, den ge Alles unter **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) ist schreibgeschützt und ändert nichts. -Da der Agent **als Sie** agiert, kann er nur das tun, was Ihr Login erlaubt; Berechtigungen werden **pro Org** aufgelöst (siehe [API-Schlüssel](/de/agenteye/api-keys)). Ein Befehl, für den Sie keine Berechtigung haben, gibt Exit-Code `5` mit dem genauen Berechtigungsnamen zurück, sodass der Agent Ihnen genau sagen kann, was Sie einen Administrator fragen müssen, anstatt undurchsichtig zu scheitern. +Da der Agent als **Sie** handelt, kann er nur das tun, wozu Ihr Login berechtigt ist; Berechtigungen werden **pro Organisation** aufgelöst (siehe [API-Schlüssel](/de/agenteye/api-keys)). Ein Befehl, für den Ihnen die Berechtigung fehlt, gibt Exit-Code `5` mit der genauen Berechtigungsbezeichnung zurück – der Agent kann Ihnen also präzise sagen, was Sie einen Administrator bitten müssen, anstatt undurchsichtig zu scheitern. --- ## Was Sie fragen können -So sieht ein echter Ablauf aus – zuerst eine Leseanfrage, dann eine Änderung, die auf Ihre Zustimmung wartet: +So sieht ein echter Austausch aus – erst eine Leseanfrage, dann eine Änderung, die auf Ihre Bestätigung wartet: ```text -you ▸ Is anything broken in the last day? +Sie ▸ Gibt es irgendwelche Probleme in den letzten 24 Stunden? -agent ▸ Running: agenteye --json errors --since 24h --aggregate - 3 error types in the last 24h. The biggest is TimeoutError - (18 hits, all on the checkout-agent), then RateLimited (5). - Want the failing sessions for TimeoutError? +Agent ▸ Ausführen: agenteye --json errors --since 24h --aggregate + 3 Fehlertypen in den letzten 24 Stunden. Der häufigste ist TimeoutError + (18 Treffer, alle beim checkout-agent), dann RateLimited (5). + Soll ich die fehlgeschlagenen Sessions für TimeoutError anzeigen? -you ▸ Give CI a key that can only push events. +Sie ▸ Gib CI einen Schlüssel, der nur Events pushen kann. -agent ▸ This creates an API key. I'll run: +Agent ▸ Damit wird ein API-Schlüssel erstellt. Ich werde Folgendes ausführen: agenteye keys create ci --add events:add - OK to proceed? + Fortfahren? -you ▸ yes +Sie ▸ ja -agent ▸ Done. Key "ci" created with events:add only. - The secret is shown only once, so store it now. I can't reprint it. +Agent ▸ Erledigt. Schlüssel "ci" wurde mit events:add erstellt. + Das Secret wird nur einmal angezeigt – speichern Sie es jetzt. Ich kann es nicht erneut ausgeben. ``` -Der Skill ordnet jede natürlichsprachige Absicht dem richtigen `agenteye`-Befehl zu, ermittelt dabei zuerst gültige Werte (`list `, `whoami`), rät nicht und gibt den genauen Befehl vor jeder Änderung an. Weitere Beispiele: +Der Skill ordnet jede natürlichsprachige Absicht dem richtigen `agenteye`-Befehl zu, ermittelt zunächst gültige Werte (`list `, `whoami`), um nicht zu raten, und gibt den genauen Befehl vor jeder Änderung an. Weitere Beispiele: -- *„Ist irgendetwas kaputt / fehlgeschlagen in den letzten 24 Stunden?"* → `errors --since 24h --aggregate`, dann eine Aufschlüsselung. -- *„Warum ist Sitzung `run-001` fehlgeschlagen?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *„Wie entwickelt sich die Qualität diese Woche?"* → `evals --aggregate --since 7d`, dann Drilldown in schlecht bewertete Läufe. -- *„Gib CI einen Schlüssel, der nur Events pushen kann."* → `keys create ci --add events:add` (der Befehl wird angegeben, dann erstellt und das einmalige Secret erfasst). -- *„Wer hat Zugriff? Mache Dana schreibgeschützt."* → `users list` → `users update dana@… --permission-set read-only` (nach Ihrer Bestätigung). -- *„Bestätige den ausgelösten Incident und weise ihn mir zu."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. +- *„Gibt es in den letzten 24 Stunden etwas Defektes oder Fehlgeschlagenes?"* → `errors --since 24h --aggregate`, dann eine Aufschlüsselung. +- *„Warum ist Session `run-001` fehlgeschlagen?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. +- *„Wie entwickelt sich die Qualität diese Woche?"* → `evals --aggregate --since 7d`, dann Einblick in schlecht bewertete Läufe. +- *„Gib CI einen Schlüssel, der nur Events pushen kann."* → `keys create ci --add events:add` (der Befehl wird angegeben, dann ausgeführt und das einmalige Secret gespeichert). +- *„Wer hat Zugriff? Mach Dana nur leseberechtigt."* → `users list` → `users update dana@… --permission-set read-only` (nach Ihrer Bestätigung). +- *„Bestätige den aktiven Incident und weise ihn mir zu."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. -Die genauen Befehle, Flags und JSON-Strukturen hinter diesen Beispielen finden Sie in der [CLI](/de/agenteye/cli)-Referenz und den [CLI-Rezepten für Agenten](/de/agenteye/cli-recipes). +Die genauen Befehle, Flags und JSON-Strukturen dahinter finden Sie in der [CLI](/de/agenteye/cli)-Referenz und in den [CLI-Rezepten für Agents](/de/agenteye/cli-recipes). --- ## Nächste Schritte - **[CLI](/de/agenteye/cli)**: vollständige Befehls- und Flag-Referenz für `agenteye`. -- **[CLI-Rezepte für Agenten](/de/agenteye/cli-recipes)**: Copy-paste-`jq`-Muster und Exit-Code-Behandlung. +- **[CLI-Rezepte für Agents](/de/agenteye/cli-recipes)**: Copy-Paste-`jq`-Muster und Exit-Code-Behandlung. - **[Evaluator Agent Skill](/de/agenteye/evaluator-skill)**: der verwandte Skill zum Aufbau des Evaluators, dessen Scores `agenteye evals` liest. -- **[Python SDK Agent Skill](/de/agenteye/python-sdk-skill)**: der verwandte Skill zum Instrumentieren eines Agenten, damit er die Telemetrie aussendet, die `agenteye` liest. -- **[KI-Assistent](/de/agenteye/assistant)**: der In-Dashboard-Assistent (nicht mit diesem Terminal-Skill zu verwechseln). -- **[API-Schlüssel](/de/agenteye/api-keys)**: das Berechtigungsmodell pro Org, das den Wirkungsbereich des Skills begrenzt. \ No newline at end of file +- **[Python SDK Agent Skill](/de/agenteye/python-sdk-skill)**: der verwandte Skill zur Instrumentierung eines Agents, sodass er die Telemetrie aussendet, die `agenteye` liest. +- **[KI-Assistent](/de/agenteye/assistant)**: der In-Dashboard-Assistent (nicht zu verwechseln mit diesem Terminal-Skill). +- **[API-Schlüssel](/de/agenteye/api-keys)**: das organisationsweite Berechtigungsmodell, das den Wirkungsbereich des Skills begrenzt. \ No newline at end of file diff --git a/docs/de/agenteye/cli.mdx b/docs/de/agenteye/cli.mdx index c7f03cf9..9c7329d0 100644 --- a/docs/de/agenteye/cli.mdx +++ b/docs/de/agenteye/cli.mdx @@ -1,25 +1,25 @@ --- title: "CLI" -description: "Steuere die gesamte Failproof AI Observability vom Terminal oder einem Skript aus: kein Umweg über das Dashboard." +description: "Failproof AI Observability vollständig vom Terminal oder einem Skript aus steuern: ohne Umwege über das Dashboard." --- -Steuere die gesamte Failproof AI Observability vom Terminal oder einem Skript aus: kein Umweg über das Dashboard. Die `agenteye` CLI fragt deine Daten ab (Sessions, Event-Logs, Evaluierungen) und verwaltet deine Organisation (API-Keys, Nutzer, Einstellungen, Alerts, Incidents, gespeicherte Abfragen) – greife darauf zurück, wenn du eine Prüfung automatisieren, Observability in CI einbinden oder einen Coding-Agenten die Produktion inspizieren lassen möchtest. Jeder Befehl unterstützt ein `--json`-Flag, sodass er gleichermaßen für dich an der Eingabeaufforderung oder für einen Coding-Agenten (Claude Code, Cursor) funktioniert, der das Ergebnis parst. +Failproof AI Observability vollständig vom Terminal oder einem Skript aus steuern: ohne Umwege über das Dashboard. Die `agenteye`-CLI fragt Ihre Daten ab (Sessions, Event-Logs, Evaluierungen) und verwaltet Ihre Organisation (API-Keys, Benutzer, Einstellungen, Alerts, Incidents, gespeicherte Abfragen). Greifen Sie darauf zurück, wenn Sie eine Prüfung automatisieren, Observability in CI integrieren oder einem Coding-Agent ermöglichen möchten, die Produktion zu inspizieren. Jeder Befehl unterstützt das Flag `--json`, sodass er sowohl interaktiv an der Eingabeaufforderung als auch für Coding-Agents (Claude Code, Cursor) geeignet ist, die die Ausgabe parsen. -Mit einer einzigen Binary kannst du: +Mit einem einzigen Binary können Sie: -- **Deine Daten lesen**: `sessions`, `events`, `evals`, `errors` (gefiltert nach Zeit, Agent, Umgebung, Score). -- **Deine Organisation verwalten**: `keys`, `users`, `settings`, `alerts`, `incidents`. -- **Analysen ausführen**: gespeichertes SQL und einen Ad-hoc-Query-Runner (`query`). -- **Den KI-Assistenten befragen**: denselben schreibgeschützten Analysten, mit dem du im Dashboard chattest (`agent`). +- **Ihre Daten lesen**: `sessions`, `events`, `evals`, `errors` (gefiltert nach Zeit, Agent, Umgebung, Score). +- **Ihre Organisation verwalten**: `keys`, `users`, `settings`, `alerts`, `incidents`. +- **Analysen durchführen**: gespeichertes SQL und ein Ad-hoc-Query-Runner (`query`). +- **Den KI-Assistenten befragen**: derselbe schreibgeschützte Analyst, mit dem Sie im Dashboard chatten (`agent`). -> **Hinweis:** Dies ist die `agenteye` CLI, ein anderes Werkzeug als der Collector-Daemon (`agenteye-collector`). Die CLI kommuniziert mit deinem Dashboard; der Collector sendet Events an den Server. +> **Hinweis:** Dies ist die `agenteye`-CLI, ein anderes Werkzeug als der Collector-Daemon (`agenteye-collector`). Die CLI kommuniziert mit Ihrem Dashboard; der Collector sendet Events an den Server. --- ## Schnellstart -Von null zum ersten Ergebnis in vier Zeilen. Weise die CLI auf dein Dashboard, melde dich an, bestätige deine Identität und rufe dann die letzten 24 Stunden an Runs ab: +Von null zum ersten Ergebnis in vier Zeilen. Richten Sie die CLI auf Ihr Dashboard, melden Sie sich an, bestätigen Sie Ihre Identität und rufen Sie dann die Läufe des letzten Tages ab: ```bash pipx install agenteye @@ -28,7 +28,7 @@ agenteye whoami agenteye --json sessions --since 24h # one row per agent run, last 24h ``` -Der letzte Befehl gibt ein JSON-Objekt mit den neuesten Sessions aus (neueste zuerst, standardmäßig auf 50 begrenzt). Leite es in `jq` weiter, um es zu filtern, oder lass `--json` weg für eine umrahmte, kolorierte Tabelle. Jede Zeile enthält den Status des Runs und, sofern ein Evaluator ihn bewertet hat, seine Metrik-Scores (hier gekürzt): +Der letzte Befehl gibt ein JSON-Objekt der neuesten Sessions aus (neueste zuerst, standardmäßig auf 50 begrenzt). Leiten Sie es in `jq` weiter, um es zu filtern, oder lassen Sie `--json` weg für eine eingerahmte, farbige Tabelle. Jede Zeile enthält den Status des Laufs und, falls ein Evaluator ihn bewertet hat, seine Metrik-Scores (hier abgekürzt): ```json { @@ -48,13 +48,13 @@ Der letzte Befehl gibt ein JSON-Objekt mit den neuesten Sessions aus (neueste zu } ``` -Der Rest dieser Seite erläutert die einzelnen Bestandteile: [Installation](#installation) in einer isolierten Umgebung, [Anmeldung](#authentication), [Konfiguration](#configuration), die [globalen Konventionen](#global-options--conventions), die alle Befehle teilen, sowie die [vollständige Befehlsreferenz](#command-reference). +Der Rest dieser Seite erläutert die einzelnen Bereiche: [Installation](#installation), [Anmeldung](#authentication), [Konfiguration](#configuration), die [globalen Konventionen](#global-options--conventions), die alle Befehle teilen, und die [vollständige Befehlsreferenz](#command-reference). --- ## Installation -Die CLI ist ein öffentliches PyPI-Paket namens **`agenteye`**. Installiere es in einer isolierten Umgebung, damit es stets eigene Abhängigkeiten hat: +Die CLI ist ein öffentliches PyPI-Paket namens **`agenteye`**. Installieren Sie es in einer isolierten Umgebung, damit es immer seine eigenen Abhängigkeiten hat: ```bash pipx install agenteye @@ -62,42 +62,42 @@ pipx install agenteye uv tool install agenteye ``` -Python 3.10+ ist erforderlich. Der installierte Befehl lautet **`agenteye`**: +Es erfordert Python 3.10+. Der installierte Befehl lautet **`agenteye`**: ```bash agenteye --version agenteye --help ``` -> **Hinweis:** Das Failproof AI Observability Python SDK verwendet ebenfalls den Distributionsnamen `agenteye`. Die Installation der CLI mit `pipx` oder `uv tool` (statt `pip install` in ein gemeinsames Virtualenv) verhindert Konflikte zwischen beiden. Ein einfaches `pip install agenteye` ist nur dann problemlos, wenn das SDK nicht in derselben Umgebung installiert ist. +> **Hinweis:** Das Failproof AI Observability Python SDK verwendet ebenfalls den Distributionsnamen `agenteye`. Die Installation der CLI mit `pipx` oder `uv tool` (anstatt `pip install` in ein gemeinsames Virtualenv) verhindert Konflikte zwischen beiden. Ein einfaches `pip install agenteye` ist nur dann problemlos, wenn das SDK nicht in derselben Umgebung installiert ist. --- ## Authentifizierung -Die CLI authentifiziert sich gegenüber dem **Dashboard** mit einem per E-Mail zugesandten Einmalcode: +Die CLI authentifiziert sich beim **Dashboard** mit einem per E-Mail zugesandten Einmalcode: ```bash agenteye login --email you@example.com # A 6-digit code is emailed to you; paste it at the prompt. ``` -Das Session-Token wird in `~/.agenteye/cli.json` gespeichert (nur für dich lesbar, Modus `0600`) und ist standardmäßig 24 Stunden gültig. Nach Ablauf führe erneut `agenteye login` aus. +Das Session-Token wird in `~/.agenteye/cli.json` gespeichert (nur für Sie lesbar, Modus `0600`) und ist standardmäßig 24 Stunden gültig. Nach Ablauf führen Sie erneut `agenteye login` aus. ```bash agenteye whoami # show the current user, active org, and permissions agenteye logout # revoke the session and clear the stored token ``` -`whoami` schlägt bei einer fehlenden oder abgelaufenen Session nie fehl; stattdessen meldet es `logged_in: false`, sodass ein Skript oder Agent den Auth-Status sicher abfragen kann (es kann dennoch mit einem Nicht-Null-Wert enden, wenn keine Basis-URL gesetzt oder das Dashboard nicht erreichbar ist). +`whoami` gibt bei einer fehlenden oder abgelaufenen Session keinen Fehler aus; stattdessen meldet es `logged_in: false`, sodass ein Skript oder Agent den Auth-Zustand sicher prüfen kann (es kann dennoch mit einem Fehlercode ungleich null beenden, wenn keine Base-URL gesetzt ist oder das Dashboard nicht erreichbar ist). -**Voraussetzungen:** Deine E-Mail-Adresse muss für die Anmeldung am Dashboard berechtigt sein (frage deinen Failproof AI Observability-Administrator), und das Dashboard muss über seine Basis-URL erreichbar sein (siehe [Konfiguration](#configuration)). Wenn du einen Code anforderst und keiner eintrifft, ist deine E-Mail-Adresse wahrscheinlich noch nicht für den Dashboard-Zugang freigeschalten. +**Voraussetzungen:** Ihre E-Mail-Adresse muss für die Anmeldung am Dashboard freigegeben sein (fragen Sie Ihren Failproof AI Observability-Administrator), und das Dashboard muss unter seiner Base-URL erreichbar sein (siehe [Konfiguration](#configuration)). Wenn Sie einen Code anfordern und keiner ankommt, ist Ihre E-Mail-Adresse wahrscheinlich noch nicht für den Dashboard-Zugang aktiviert. --- ## Organisation auswählen (Multi-Tenant) -Wenn dein Konto zu mehr als einer Organisation gehört, wähle die aktive **bei der Anmeldung**; sie wird gespeichert und für alle späteren Befehle verwendet: +Wenn Ihr Konto zu mehr als einer Organisation gehört, wählen Sie die aktive **beim Login**; sie wird gespeichert und für alle folgenden Befehle verwendet: ```bash agenteye login --org acme # authenticate and set the active tenant in one step @@ -106,7 +106,7 @@ agenteye orgs switch globex # change the saved default agenteye --org globex sessions # override for a single command ``` -Wenn du genau einer Organisation angehörst, wird diese automatisch ausgewählt, und du kannst `--org` vollständig ignorieren. Wenn du mehreren angehörst und keine auswählst, listet die CLI sie auf und fordert dich auf, den Befehl mit `--org ` erneut auszuführen. Die aktive Organisation wird bei jeder Anfrage an das Dashboard gesendet, und deine Berechtigungen werden **pro Organisation** aufgelöst; `agenteye whoami` zeigt die aktive Organisation, deine Berechtigungen darin und alle deine Mitgliedschaften. +Wenn Sie genau einer Organisation angehören, wird diese automatisch ausgewählt, und Sie können `--org` ignorieren. Gehören Sie mehreren Organisationen an und wählen keine aus, listet die CLI diese auf und fordert Sie auf, den Befehl mit `--org ` erneut auszuführen. Die aktive Organisation wird bei jeder Anfrage an das Dashboard übermittelt, und Ihre Berechtigungen werden **pro Organisation** aufgelöst; `agenteye whoami` zeigt die aktive Organisation, Ihre Berechtigungen darin und alle Ihre Mitgliedschaften an. --- @@ -114,15 +114,15 @@ Wenn du genau einer Organisation angehörst, wird diese automatisch ausgewählt, | Einstellung | Flag | Umgebungsvariable | Standard | |---|---|---|---| -| Dashboard-Basis-URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **erforderlich** (kein Standard) | -| Aktive Organisation/Tenant | `--org` | `AGENTEYE_ORG` | bei Anmeldung gewählt; in `~/.agenteye/cli.json` gespeichert | +| Dashboard-Base-URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **erforderlich** (kein Standard) | +| Aktive Org/Tenant | `--org` | `AGENTEYE_ORG` | beim Login gewählt; gespeichert in `~/.agenteye/cli.json` | | Session-Token | `--token` | `AGENTEYE_CLI_TOKEN` | aus `~/.agenteye/cli.json` | -| JSON-Ausgabe | `--json` | `AGENTEYE_CLI_JSON` | deaktiviert | -| TLS-Überprüfung überspringen | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | deaktiviert (bei Anmeldung gespeichert) | -| Anfrage-Timeout (Sekunden) | `--timeout` | _(keine)_ | 30 | -| Nutzungstelemetrie deaktivieren | _(keine)_ | `AGENTEYE_ANALYTICS_DISABLED` (oder `DO_NOT_TRACK`) | Telemetrie ist derzeit deaktiviert; es wird nichts gesendet | +| JSON-Ausgabe | `--json` | `AGENTEYE_CLI_JSON` | aus | +| TLS-Verifizierung überspringen | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | aus (beim Login gespeichert) | +| Request-Timeout (Sekunden) | `--timeout` | _(keiner)_ | 30 | +| Nutzungstelemetrie deaktivieren | _(keiner)_ | `AGENTEYE_ANALYTICS_DISABLED` (oder `DO_NOT_TRACK`) | Telemetrie ist derzeit deaktiviert; es wird nichts gesendet | -Die Auflösungsreihenfolge ist **Flag → Umgebungsvariable → Konfigurationsdatei**. Es gibt keinen Standard; du musst die CLI auf dein Dashboard zeigen, entweder pro Befehl (`--base-url https://agenteye.example.com`) oder einmalig über die Umgebung (wird auch nach deinem ersten `login` gespeichert): +Die Auflösungsreihenfolge ist **Flag → Umgebungsvariable → Konfigurationsdatei**. Es gibt keinen Standardwert; Sie müssen die CLI auf Ihr Dashboard verweisen, entweder pro Befehl (`--base-url https://agenteye.example.com`) oder einmalig über die Umgebungsvariable (sie wird auch nach Ihrem ersten `login` gespeichert): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com @@ -130,63 +130,63 @@ export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com Das Konfigurationsverzeichnis berücksichtigt `AGENTEYE_HOME` (dieselbe Konvention wie beim SDK und Collector); wenn gesetzt, liegt `cli.json` unter `$AGENTEYE_HOME/cli.json`. -### Selbstsignierte oder interne TLS-Zertifikate +### Selbstsigniertes oder internes TLS -Wenn dein Dashboard über HTTPS mit einem selbstsignierten oder internen Zertifikat betrieben wird (zum Beispiel ein roher Load-Balancer-Hostname), lehnt die TLS-Überprüfung es mit einem `CERTIFICATE_VERIFY_FAILED`-Fehler ab. Übergib `--insecure`, um die Zertifikatsprüfung zu überspringen: +Wenn Ihr Dashboard über HTTPS mit einem selbstsignierten oder internen Zertifikat bereitgestellt wird (z. B. ein roher Load-Balancer-Hostname), lehnt die TLS-Verifizierung es mit einem `CERTIFICATE_VERIFY_FAILED`-Fehler ab. Übergeben Sie `--insecure`, um die Zertifikatsprüfung zu überspringen: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` wird **bei der Anmeldung in `cli.json` gespeichert**, sodass spätere Befehle die Überprüfung automatisch überspringen; du musst das Flag nicht wiederholen. Übergib `--secure` für einen einmaligen verifizierten Aufruf oder um die Überprüfung bei deiner nächsten Anmeldung wieder zu aktivieren. Die CLI gibt vor jedem Befehl, der das Dashboard kontaktiert, eine Warnung an stderr aus, solange die Überprüfung deaktiviert ist. Das Überspringen der Überprüfung beseitigt den Schutz vor Man-in-the-Middle-Angriffen; stelle sicher, dass du dem Netzwerkpfad zu deinem Dashboard vertraust (VPN, privates Subnetz usw.), bevor du dich darauf verlässt. +`--insecure` wird **beim Login in `cli.json` gespeichert**, sodass spätere Befehle die Verifizierung automatisch überspringen; Sie müssen das Flag nicht wiederholen. Übergeben Sie `--secure` für einen einmaligen verifizierten Aufruf oder um die Verifizierung beim nächsten Login wieder zu aktivieren. Die CLI gibt vor jedem Befehl, der das Dashboard kontaktiert, während die Verifizierung deaktiviert ist, eine Warnung auf stderr aus. Das Überspringen der Verifizierung entfernt den Schutz vor Man-in-the-Middle-Angriffen; stellen Sie sicher, dass Sie dem Netzwerkpfad zu Ihrem Dashboard vertrauen (VPN, privates Subnetz usw.), bevor Sie sich darauf verlassen. --- ## Telemetrie & Datenschutz -> **Hinweis:** Die ausgelieferte CLI sendet **heute keine Nutzungstelemetrie.** Ein globaler Kill-Switch ist aktiviert, sodass unabhängig von deiner Umgebung nichts übertragen wird. Der folgende Abschnitt beschreibt die Opt-out-Möglichkeit für den Fall, dass Telemetrie jemals aktiviert wird. +> **Hinweis:** Die ausgelieferte CLI sendet **derzeit keine Nutzungstelemetrie.** Ein zentraler Kill-Switch ist aktiviert, sodass unabhängig von Ihrer Umgebung nichts übertragen wird. Der folgende Abschnitt beschreibt die Opt-out-Möglichkeit für den Fall, dass Telemetrie jemals aktiviert wird. -Selbst wenn aktiviert, wären Telemetriedaten **ausschließlich anonyme Nutzungsanalysen**, niemals deine Agenten-, Session- oder Event-Daten: +Selbst wenn aktiviert, wären es ausschließlich **anonyme Nutzungsanalysen**, niemals Ihre Agent-, Session- oder Event-Daten: -- **Keine Agenten-, Session- oder Event-Daten verlassen jemals deine Infrastruktur.** Nur CLI-Nutzung würde gemeldet: der Befehls- und Unterbefehls-Name (z. B. `keys create`), die **Namen** der verwendeten Flags (niemals deren Werte), Erfolgs-/Exit-Status und Dauer, sowie ein Pro-Aktion-Event für Mutationen (z. B. `api_key_created`, `query_run`), das nur statische Namen/Enums und grobe Zählwerte enthält. Deine Dashboard-URL, dein Session-Token, deine E-Mail, dein Org-Slug, Ressourcen-IDs, SQL, Key-Secrets und Abfragefilter würden **niemals** gesendet. Operatoren würden nur durch eine opaque interne ID identifiziert, niemals per E-Mail. -- **Vorab abmelden** durch Setzen von `AGENTEYE_ANALYTICS_DISABLED=1` in der Umgebung der CLI (die CLI berücksichtigt auch die toolübergreifende Konvention `DO_NOT_TRACK=1`). Dies greift sofort, wenn Telemetrie jemals aktiviert wird, sodass eine datenschutzbewusste Umgebung dauerhaft abgemeldet bleiben kann. -- Wenn Telemetrie aktiviert wäre, würde die CLI direkt an PostHog senden (`https://us.i.posthog.com`); ein Gerät, bei dem dieser Host geblockt ist, würde still nichts senden, ohne dass die CLI beeinträchtigt würde. +- **Keine Agent-, Session- oder Event-Daten verlassen jemals Ihre Infrastruktur.** Es würden nur CLI-Nutzungsdaten gemeldet: der Befehls- und Unterbefehls-Name (z. B. `keys create`), die **Namen** der verwendeten Flags (niemals ihre Werte), Erfolg/Exit-Status und Dauer, sowie ein Pro-Aktion-Event für Mutationen (z. B. `api_key_created`, `query_run`), das nur statische Namen/Enums und grobe Zählungen enthält. Ihre Dashboard-URL, Ihr Session-Token, Ihre E-Mail, Ihr Org-Slug, Ressourcen-IDs, SQL, Key-Secrets und Query-Filter würden **niemals** gesendet. Betreiber würden nur durch eine undurchsichtige interne ID identifiziert, niemals per E-Mail. +- **Opt-out im Voraus** durch Setzen von `AGENTEYE_ANALYTICS_DISABLED=1` in der Umgebung der CLI (die CLI berücksichtigt auch die übergreifende Konvention `DO_NOT_TRACK=1`). Dies greift in dem Moment, in dem Telemetrie jemals aktiviert wird, sodass eine datenschutzbewusste Umgebung dauerhaft abgemeldet bleiben kann. +- Wenn Telemetrie aktiviert wäre, würde die CLI direkt an PostHog (`https://us.i.posthog.com`) senden; ein Rechner, auf dem dieser Host blockiert ist, würde nichts senden und die CLI wäre nicht beeinträchtigt. --- ## Globale Optionen & Konventionen -Lies dies einmal; es gilt für jeden Befehl. +Lesen Sie dies einmal; es gilt für jeden Befehl. -- **Globale Optionen stehen VOR dem Befehl.** `agenteye --json sessions` ist korrekt; `agenteye sessions --json` ist ein Verwendungsfehler. Die globalen Optionen sind `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` und `--no-color`. -- **`--json` gibt reines JSON nach stdout aus, und sonst nichts.** Lesbare Statuszeilen, Warnungen und Fehler gehen an **stderr**, sodass eine `--json`-stdout-Erfassung sauber in `jq` geleitet werden kann, auch wenn eine Statuszeile angezeigt wird. Ohne `--json` erhältst du eine umrahmte, kolorierte Ansicht für menschliche Augen. -- **Erkunden mit `--help`.** Jeder Befehl und Unterbefehl hat `--help` (und das `-h`-Alias): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. Die oberste Hilfe listet auch die Exit-Codes und globalen Optionen auf. Es gibt keine globale maschinenlesbare Oberflächenauflistung; verwende `--help` pro Befehl sowie die domänenspezifischen `agenteye query schema` und `agenteye settings schema` für diese zwei Register. -- **Bestätigungen werden für Skripte und Agenten automatisch übersprungen.** Erstell-/Aktualisierungs-/Löschbefehle fragen in einem interaktiven Terminal nach, ob du sicher bist, **überspringen diese Abfrage aber automatisch unter `--json` oder wenn stdin kein TTY ist** (ein TTY ist eine interaktive Terminalsitzung; eine Pipe oder ein CI-Runner ist keins), sodass Skripte und Agenten nie hängen bleiben. Übergib `--yes`/`-y`, um es explizit zu überspringen. Da die Abfrage für einen Agenten nicht ausgelöst wird, sollte ein Agent destruktive Aktionen vorher mit dem Menschen bestätigen. -- **Paginierung:** Ergebnisse sind neueste zuerst und cursor-paginiert (jede Seite gibt ein Token zurück, das du zum Abrufen der nächsten verwendest). `--limit N` (Alias `-n`) begrenzt Zeilen und **standardmäßig auf 50**; `--all` paginiert automatisch (in 200-Zeilen-Chunks) **bis `--limit`**, sodass ein bloßes `--all` immer noch bei 50 stoppt. Für eine vollständige Abfrage übergib ein hohes explizites Limit: `--all --limit 1000`. `--page-size N` steuert den Chunk pro Anfrage (max. 200); `--cursor ` setzt ab dem `next_cursor` einer vorherigen Seite fort. -- **Zeitfilter:** `--since` nimmt ein relatives Zeitfenster: `15m`, `1h`, `6h`, `24h`, `7d` oder `all` (die Voreinstellungen des Dashboards). Für einen längeren oder benutzerdefinierten Bereich (z. B. die letzten 30 Tage) verwende `--from`/`--to`: explizite ISO-8601-UTC-Zeitstempel **mit `T` und einer Zeitzone** (z. B. `2026-06-01T00:00:00Z`), die `--since` überschreiben. Ein mit Leerzeichen getrennter oder zeitzonenloser Wert ist ein Verwendungsfehler. -- **`--fields a,b,c`** (bei `events`, `sessions`, `evals`, `errors`) schränkt die Ausgabe auf diese Schlüssel ein, sowohl für die Tabelle als auch für `--json`. Unbekannte Namen werden mit der gültigen Liste abgewiesen – eine einfache Methode, Feldnamen zu entdecken. -- **`--file payload.json`** (oder `--file -`, um stdin zu lesen) liefert einen vollständigen JSON-Request-Body, wenn eine Ressource eine komplexe Form hat (bei `alerts create/update`, `settings set` und `users create/update`). SQL für gespeicherte Abfragen verwendet stattdessen `--sql @file.sql`. -- **Mehrwertige Filter** sind kommagetrennt → als Menge abgeglichen (Union innerhalb eines Filters, UND über Filter hinweg): `--event-type tool_use,tool_result`. Click-Optionen sind nicht variadisch, daher schlägt `--add a b` fehl. Verwende `--add a,b`, wiederhole das Flag (`--add a --add b`) oder setze Anführungszeichen (`--add "a b"`). +- **Globale Optionen kommen VOR dem Befehl.** `agenteye --json sessions` ist korrekt; `agenteye sessions --json` ist ein Verwendungsfehler. Die globalen Optionen sind `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` und `--no-color`. +- **`--json` gibt reines JSON auf stdout aus, und nichts anderes.** Statusmeldungen, Warnungen und Fehler gehen auf **stderr**, sodass eine `--json`-stdout-Erfassung sauber bleibt, um sie in `jq` zu leiten, auch wenn eine Statusmeldung angezeigt wird. Ohne `--json` erhalten Sie eine eingerahmte, farbige Ansicht für menschliche Augen. +- **Mit `--help` erkunden.** Jeder Befehl und Unterbefehl hat `--help` (und den Alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. Die oberste Hilfeanzeige listet auch die Exit-Codes und globalen Optionen auf. Es gibt keine globale maschinenlesbare Oberflächenübersicht; verwenden Sie `--help` pro Befehl sowie das domänenspezifische `agenteye query schema` und `agenteye settings schema` für diese beiden Registries. +- **Bestätigungen werden für Skripte und Agents automatisch übersprungen.** Create/Update/Delete-Befehle fragen in einem interaktiven Terminal „sind Sie sicher?", **überspringen diese Abfrage jedoch automatisch unter `--json` oder wenn stdin kein TTY ist** (ein TTY ist eine interaktive Terminalsitzung; eine Pipe oder ein CI-Runner ist keines), sodass Skripte und Agents nie hängen bleiben. Übergeben Sie `--yes`/`-y`, um es explizit zu überspringen. Da die Abfrage für einen Agent nicht ausgelöst wird, sollte ein Agent destructive Aktionen zuerst mit dem Menschen bestätigen. +- **Paginierung:** Ergebnisse sind neueste-zuerst und cursor-paginiert (jede Seite gibt ein Token zurück, das Sie zum Abrufen der nächsten verwenden). `--limit N` (Alias `-n`) begrenzt Zeilen und **hat standardmäßig 50**; `--all` paginiert automatisch (in 200-Zeilen-Blöcken) **bis zu `--limit`**, sodass ein einfaches `--all` immer noch bei 50 endet. Für einen vollständigen Durchlauf übergeben Sie ein hohes explizites Limit: `--all --limit 1000`. `--page-size N` steuert den Chunk pro Anfrage (max. 200); `--cursor ` setzt von einem vorherigen `next_cursor` fort. +- **Zeitfilter:** `--since` nimmt ein relatives Fenster: `15m`, `1h`, `6h`, `24h`, `7d` oder `all` (die Dashboard-Voreinstellungen). Für einen längeren oder benutzerdefinierten Bereich (z. B. die letzten 30 Tage) verwenden Sie `--from`/`--to`: explizite ISO-8601-UTC-Zeitstempel **mit `T` und einer Zeitzone** (z. B. `2026-06-01T00:00:00Z`), die `--since` überschreiben. Ein leerzeichen-getrennter oder zeitzonenloser Wert ist ein Verwendungsfehler. +- **`--fields a,b,c`** (bei `events`, `sessions`, `evals`, `errors`) schränkt die Ausgabe auf diese Schlüssel ein, sowohl für die Tabelle als auch für `--json`. Unbekannte Namen werden mit der gültigen Liste abgelehnt – eine einfache Methode, Feldnamen zu entdecken. +- **`--file payload.json`** (oder `--file -` zum Lesen von stdin) liefert einen vollständigen JSON-Request-Body, wenn eine Ressource eine komplexe Form hat (bei `alerts create/update`, `settings set` und `users create/update`). Gespeichertes SQL verwendet stattdessen `--sql @file.sql`. +- **Multi-Wert-Filter** sind kommagetrennt → als Menge abgeglichen (Union innerhalb eines Filters, AND über Filter hinweg): `--event-type tool_use,tool_result`. Click-Optionen sind nicht variadisch, daher schlägt `--add a b` fehl. Verwenden Sie `--add a,b`, wiederholen Sie das Flag (`--add a --add b`) oder setzen Sie Anführungszeichen (`--add "a b"`). --- ## Befehlsreferenz -### Die 5 häufigsten Befehle +### Die 5 am häufigsten verwendeten Befehle -Die meisten alltäglichen Aufgaben laufen über eine Handvoll Lesebefehle. Fange hier an und greife bei Bedarf auf die vollständige Oberfläche unten zurück: +Der Großteil der täglichen Arbeit läuft über eine Handvoll Lesebefehle. Fangen Sie hier an und greifen Sie dann bei Bedarf auf die vollständige Oberfläche unten zurück: -| Befehl | Was er tut | Ausprobieren | +| Befehl | Funktion | Ausprobieren | |---|---|---| -| `sessions` | Eine Zeile pro Agent-Run: Zeit, Umgebung, Agent, Status, neuester Score. | `agenteye --json sessions --since 24h --status error` | -| `events` | Der rohe schrittweise Verlauf innerhalb eines Runs (mit `--full` für Payloads). | `agenteye --json events --session-id run-001 --all` | +| `sessions` | Eine Zeile pro Agent-Lauf: Zeit, Umgebung, Agent, Status, neuester Score. | `agenteye --json sessions --since 24h --status error` | +| `events` | Der rohe schrittweise Verlauf innerhalb eines Laufs (mit `--full` für Payloads). | `agenteye --json events --session-id run-001 --all` | | `evals` | Evaluierungsergebnisse und Scores; `--aggregate` fasst sie zusammen. | `agenteye --json evals --aggregate --since 7d --env prod` | | `errors` | Nur die fehlerhaften Events; `--aggregate` für Zählungen nach Typ. | `agenteye --json errors --since 24h --aggregate` | -| `list` | Gültige Filterwerte entdecken (Agenten, Umgebungen, Modelle, …). | `agenteye list agents` | +| `list` | Gültige Filterwerte entdecken (Agents, Umgebungen, Modelle, …). | `agenteye list agents` | ### Alles, was die CLI kann -Die vollständige Oberfläche folgt. Die CLI hat **18 Top-Level-Befehle**. Alle Lesebefehle akzeptieren `--json` und die globalen Optionen oben; führe `agenteye -h` (oder ` -h`) für die vollständige Flag-Liste und JSON-Form eines Befehls aus. +Die vollständige Oberfläche folgt. Die CLI hat **18 Top-Level-Befehle**. Alle Lesebefehle akzeptieren `--json` und die obigen globalen Optionen; führen Sie `agenteye -h` (oder ` -h`) aus, um die vollständige Flag-Liste und JSON-Form eines einzelnen Befehls zu erhalten. ### Identität: `login` · `logout` · `whoami` · `orgs` · `version` · `help` @@ -207,9 +207,9 @@ agenteye orgs current # identity card for the active org agenteye orgs perms # your permissions in the active org, grouped by resource ``` -### Beobachten (nur lesend): `events` · `sessions` · `evals` · `errors` · `list` +### Beobachten (schreibgeschützt): `events` · `sessions` · `evals` · `errors` · `list` -Keiner dieser Befehle benötigt eine Bestätigung. Gemeinsame Filter: `--session-id`, `--agent-id`, `--env` (**nicht** `--environment`) und der Zeitbereich (`--since` / `--from` / `--to`). +Keiner dieser Befehle erfordert eine Bestätigung. Gemeinsame Filter: `--session-id`, `--agent-id`, `--env` (**nicht** `--environment`) und der Zeitbereich (`--since` / `--from` / `--to`). ```bash # events (alias: the raw per-step trail), newest first @@ -232,7 +232,7 @@ agenteye --json errors --since 24h --error-type timeout --all --limit 1000 agenteye list envs # also: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (bei **`evals`**, nicht `sessions`) ist wiederholbar und UND-kombiniert; jede Grenze ist optional (`..0.5` bedeutet ≤ 0,5, `0.9..` bedeutet ≥ 0,9). Bis zu 20 Score-Filter pro Anfrage. `evals --scores-full` ist ein Anzeigeformat-Flag **nur für die menschliche Tabelle**; es zeigt jedes Score-Paar anstelle der ersten wenigen plus einer `+N`-Zählung. Es hat keine Auswirkung unter `--json`, das immer das vollständige Score-Objekt zurückgibt. Um **eine Session von Anfang bis Ende zu lesen**, kombiniere den Event-Verlauf mit seiner Evaluierung: +`--score KEY:MIN..MAX` (bei **`evals`**, nicht `sessions`) ist wiederholbar und wird AND-kombiniert; jede Grenze ist optional (`..0.5` bedeutet ≤ 0,5, `0.9..` bedeutet ≥ 0,9). Bis zu 20 Score-Filter pro Anfrage. `evals --scores-full` ist ein Anzeige-Flag **nur für die menschliche Tabelle**; es zeigt jedes Score-Paar anstatt der ersten paar plus einem `+N`-Zähler. Unter `--json` hat es keine Auswirkung, da dort immer das vollständige Score-Objekt zurückgegeben wird. Um **eine Session von Anfang bis Ende** zu lesen, kombinieren Sie den Event-Verlauf mit seiner Evaluierung: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' @@ -241,7 +241,7 @@ agenteye --json evals --session-id run-001 # its scores + ### Verwalten (berechtigungsgesteuert): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: API-Keys. Das Secret wird lokal generiert, an den Server gesendet (der nur einen Hash speichert) und beim Erstellen/Regenerieren **einmalig angezeigt**; erfasse es sofort. Mit `--json` erscheint es nur im Feld `key`. Referenziert nach **Name**. +**`keys`**: API-Keys. Das Secret wird lokal generiert, an den Server gesendet (der nur einen Hash speichert) und **einmalig** bei der Erstellung/Regenerierung angezeigt; erfassen Sie es sofort. Mit `--json` erscheint es nur im Feld `key`. Referenziert per **Name**. ```bash agenteye keys list # active keys first, then revoked @@ -253,7 +253,7 @@ agenteye keys regenerate ci-bot --yes # rotate the secret (the ol agenteye keys disable ci-bot --yes # revoke ``` -Berechtigungen funktionieren als `(permission-set ∪ --add) − --remove`. Tokens sind `slug:action` (z. B. `events:read`) oder `slug:action.action`, um mehrere für eine Ressource zu erweitern (`events:read.add` → `events:read`, `events:add`). Voreinstellungen: `read-only`, `standard`, `admin`. Rein menschliche Berechtigungen (`keys:update`) können keinem Key gewährt werden. +Berechtigungen funktionieren als `(permission-set ∪ --add) − --remove`. Tokens sind `slug:action` (z. B. `events:read`) oder `slug:action.action`, um mehrere für eine Ressource zu erweitern (`events:read.add` → `events:read`, `events:add`). Voreinstellungen: `read-only`, `standard`, `admin`. Nur für Menschen gültige Berechtigungen (`keys:update`) können einem Key nicht gewährt werden. **`users`**: Org-Mitglieder, referenziert per **E-Mail** (eine UUID-ID wird ebenfalls akzeptiert). @@ -266,7 +266,7 @@ agenteye users disable dev@corp.com --yes # has protected/self guards agenteye users enable dev@corp.com ``` -**`settings`**: Ein festes Register (du liest und ändert vorhandene Schlüssel; du kannst keine neuen erstellen). +**`settings`**: eine feste Registry (Sie lesen und ändern vorhandene Schlüssel; Sie können keine neuen erstellen). ```bash agenteye settings list # key · value · type · updated (secrets masked) @@ -274,7 +274,7 @@ agenteye settings schema # what each key accepts (ty agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: Alert-Definitionen, referenziert nach **Name**. `create` nimmt einen positionale NAME plus Flags oder einen vollständigen JSON-Body via `--file`. +**`alerts`**: Alert-Definitionen, referenziert per **Name**. `create` nimmt einen positionalen NAME plus Flags oder einen vollständigen JSON-Body über `--file`. ```bash agenteye alerts list @@ -285,7 +285,7 @@ agenteye alerts test high-errors --yes # fire a test noti agenteye alerts delete high-errors --yes ``` -**`incidents`**: Alert-Incidents, referenziert per ID (Kurzformen akzeptiert). `show` gibt das vollständige Aktivitätsprotokoll aus; lies es vor dem Handeln. +**`incidents`**: Alert-Incidents, referenziert per ID (Kurzformen werden akzeptiert). `show` gibt das vollständige Aktivitätsprotokoll aus; lesen Sie es vor dem Handeln. ```bash agenteye incidents list --state firing # also: acknowledged, resolved @@ -302,7 +302,7 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### Analysen & Assistent: `query` · `agent` -**`query`**: Gespeichertes SQL gegen deinen Analyse-Store plus einen Ad-hoc-Runner. Gespeicherte Abfragen werden nach **Name** referenziert; das SQL wird serverseitig validiert (nur SELECT/WITH, Statement-Timeout, Zeilenlimit). +**`query`**: gespeichertes SQL gegen Ihren Analytics-Store plus ein Ad-hoc-Runner. Gespeicherte Abfragen werden per **Name** referenziert; das SQL wird serverseitig validiert (nur SELECT/WITH, Statement-Timeout, Zeilenlimit). ```bash agenteye query schema [TABLE] # column layout of the analytics views @@ -313,7 +313,7 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: Kommuniziert mit dem eingebauten **KI-Assistenten** (demselben schreibgeschützten Analysten, mit dem du im Dashboard chatten kannst). Chats werden per Kurz-Chat-ID referenziert (Präfix-aufgelöst). +**`agent`**: kommuniziert mit dem eingebauten **KI-Assistenten** (derselbe schreibgeschützte Analyst, mit dem Sie im Dashboard chatten). Chats werden durch eine kurze Chat-ID referenziert (Präfix-Auflösung). ```bash agenteye agent health # is the AI assistant configured/reachable @@ -331,20 +331,20 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | Code | Bedeutung | |---|---| | 0 | Erfolg | -| 1 | Unerwarteter Fehler (z. B. Dashboard gab einen 5xx zurück) | +| 1 | Unerwarteter Fehler (z. B. das Dashboard hat einen 5xx zurückgegeben) | | 2 | Verwendungsfehler (ungültige Argumente, unbekannter Befehl/Flag, Namenskollision) | | 3 | Dashboard nicht erreichbar | -| 4 | Nicht angemeldet oder Session abgelaufen; führe `agenteye login` aus | -| 5 | Authentifiziert, aber dein Konto verfügt nicht über die erforderliche Berechtigung (die Meldung nennt sie) | +| 4 | Nicht angemeldet oder Session abgelaufen; `agenteye login` ausführen | +| 5 | Authentifiziert, aber Ihr Konto hat nicht die erforderliche Berechtigung (die Meldung nennt sie) | | 6 | Die angeforderte Ressource wurde nicht gefunden (z. B. unbekannte Session- oder Incident-ID) | -Diese machen die CLI sicher skriptfähig: Ein Coding-Agent kann bei `4` darauf reagieren, dich zur erneuten Authentifizierung aufzufordern, oder bei `5` die fehlende Berechtigung anzeigen. Siehe [CLI-Rezepte für Agenten](/de/agenteye/cli-recipes) für Exit-Code-Behandlungsmuster und JSON-Ausgabeformen. +Diese machen die CLI skriptfähig: Ein Coding-Agent kann bei einem `4` verzweigen, um Sie zur erneuten Authentifizierung aufzufordern, oder bei einem `5`, um die fehlende Berechtigung anzuzeigen. Unter [CLI-Rezepte für Agents](/de/agenteye/cli-recipes) finden Sie Exit-Code-Behandlungsmuster und JSON-Ausgabeformen. --- ## Nächste Schritte -- **[CLI-Rezepte für Agenten](/de/agenteye/cli-recipes)**: Kopierfertige Abfragemuster, `jq`-Einzeiler, `--fields`-Projektionen, Exit-Code-Behandlung und JSON-Ausgabeformen – geschrieben für Coding-Agenten, die die CLI steuern. -- **[CLI-Agent-Skill](/de/agenteye/cli-skill)**: Paketiere diese CLI als installierbaren Claude Code / Codex-*Skill*, damit ein Coding-Agent Failproof AI Observability über einfache Textanfragen steuert. +- **[CLI-Rezepte für Agents](/de/agenteye/cli-recipes)**: Kopierfertige Abfragemuster, `jq`-Einzeiler, `--fields`-Projektionen, Exit-Code-Behandlung und JSON-Ausgabeformen, geschrieben für Coding-Agents, die die CLI steuern. +- **[CLI-Agent-Skill](/de/agenteye/cli-skill)**: Packen Sie diese CLI als installierbaren Claude Code / Codex *Skill*, damit ein Coding-Agent Failproof AI Observability über Anfragen in natürlicher Sprache steuert. - **[API-Keys](/de/agenteye/api-keys)**: Das Berechtigungsmodell hinter `keys create --add …`. - **[KI-Assistent](/de/agenteye/assistant)**: Den Assistenten aktivieren, mit dem `agent ask` kommuniziert. \ No newline at end of file diff --git a/docs/de/agenteye/codex-capture.mdx b/docs/de/agenteye/codex-capture.mdx index fae232f5..e3423ff4 100644 --- a/docs/de/agenteye/codex-capture.mdx +++ b/docs/de/agenteye/codex-capture.mdx @@ -1,55 +1,55 @@ --- title: "Codex-Sitzungsaufzeichnung" -description: "Leite die lokalen OpenAI Codex-Sitzungen deines Teams als gewöhnliche Sessions und Events in AgentEye weiter – ohne Änderungen an ihrer Arbeitsweise." +description: "Übertragen Sie die lokalen OpenAI Codex-Sitzungen Ihres Teams als gewöhnliche Sitzungen und Ereignisse in AgentEye — ohne Änderungen an der Art, wie sie Codex verwenden." --- -Deine Entwickler nutzen OpenAI Codex bereits täglich. Die Codex-Sitzungsaufzeichnung bringt diese Coding-Sessions als gewöhnliche Sessions und Events in AgentEye, sodass du sie durchsuchen, wiedergeben und zusammen mit allem anderen, was du beobachtest, auswerten kannst. Sie ergänzt das [Python SDK](/de/agenteye/python-sdk): Das SDK instrumentiert Agenten, die du selbst schreibst, während dieses Feature die Codex-Arbeit deines Teams aufzeichnet – ohne dass sich an deren Arbeitsweise etwas ändert. +Ihre Entwickler nutzen OpenAI Codex bereits täglich. Die Codex-Sitzungsaufzeichnung überträgt diese Coding-Sitzungen als gewöhnliche Sitzungen und Ereignisse in AgentEye, sodass Sie sie durchsuchen, wiedergeben und zusammen mit allen anderen beobachteten Daten auswerten können. Sie ergänzt das [Python SDK](/de/agenteye/python-sdk): Das SDK instrumentiert Agents, die Sie selbst schreiben, während diese Funktion die Codex-Arbeit Ihres Teams erfasst — ohne Änderungen an deren Arbeitsweise. -Ein kleiner Hintergrundkollektor liest Codex' lokale Sitzungstranskripte, während sie geschrieben werden, und überträgt sie an AgentEye. Ein Kollektor pro Maschine erfasst alle lokalen Codex-Oberflächen gleichzeitig – es ist keine oberflächenspezifische Einrichtung erforderlich. +Ein kleiner Hintergrundkollektor liest Codex' lokale Sitzungstranskripte, während sie geschrieben werden, und übermittelt sie an AgentEye. Ein Kollektor pro Maschine erfasst gleichzeitig alle lokalen Codex-Oberflächen — es ist keine oberflächen­spezifische Einrichtung erforderlich. -Derselbe Kollektor erfasst auch andere Agenten – siehe [OpenClaw](/de/agenteye/openclaw-capture) und [Hermes](/de/agenteye/hermes-capture). Aktiviere jede Variante, die du verwendest; ein einzelner Kollektor kann mehrere gleichzeitig aufzeichnen. +Derselbe Kollektor erfasst auch andere Agents — siehe [OpenClaw](/de/agenteye/openclaw-capture) und [Hermes](/de/agenteye/hermes-capture). Aktivieren Sie jeden, den Sie einsetzen; ein einzelner Kollektor kann mehrere gleichzeitig erfassen. --- -## Was aufgezeichnet wird +## Was erfasst wird -Jede Codex-Oberfläche, die **lokal** ausgeführt wird, erzeugt dieselben Sitzungstranskripte auf der Festplatte, und der Kollektor liest alle davon: +Jede Codex-Oberfläche, die **lokal** läuft, erzeugt dieselben Sitzungstranskripte auf dem Datenträger, und der Kollektor liest sie alle: -- das Codex **CLI** und `codex exec` +- die Codex-**CLI** und `codex exec` - die **VS Code / IDE-Erweiterung** - die **Desktop-App**, wenn sie eine Sitzung lokal ausführt -Jede Codex-Sitzung wird zu einer AgentEye-[Session](/de/agenteye/sessions); ihre Nutzer- und Assistentennachrichten, das Reasoning, Tool-Aufrufe, Tool-Ergebnisse und der Token-Verbrauch werden zu den entsprechenden [Events](/de/agenteye/event-stream). Die Oberfläche, von der die jeweilige Sitzung stammt (CLI, IDE oder Desktop), wird festgehalten, damit du sie unterscheiden kannst. +Jede Codex-Sitzung wird zu einer AgentEye-[Sitzung](/de/agenteye/sessions); ihre Benutzer- und Assistenznachrichten, Überlegungen, Tool-Aufrufe, Tool-Ergebnisse und Token-Verbrauch werden zu den entsprechenden [Ereignissen](/de/agenteye/event-stream). Die Oberfläche, aus der eine Sitzung stammt (CLI, IDE oder Desktop), wird aufgezeichnet, sodass Sie sie unterscheiden können. -> **Cloud-Sitzungen werden nicht aufgezeichnet.** Die Desktop-App führt Sitzungen zunehmend in der Codex-Cloud aus und speichert lokal nur deren Metadaten – es gibt kein lokales Transkript zum Lesen. Nur lokal ausgeführte Sitzungen werden aufgezeichnet. +> **Cloud-Sitzungen werden nicht erfasst.** Die Desktop-App führt Sitzungen zunehmend in der Codex-Cloud aus und speichert nur deren Metadaten lokal — es gibt kein lokales Transkript zum Lesen. Nur lokal ausgeführte Sitzungen werden erfasst. --- ## Aktivierung -Die Aufzeichnung ist standardmäßig deaktiviert. Installiere den Kollektor mit einem API-Schlüssel, der die Berechtigung `events:add` besitzt (siehe [API-Schlüssel](/de/agenteye/api-keys)), und aktiviere die Codex-Aufzeichnung: +Die Aufzeichnung ist standardmäßig deaktiviert. Installieren Sie den Kollektor mit einem API-Key, der die Berechtigung `events:add` besitzt (siehe [API-Keys](/de/agenteye/api-keys)), und aktivieren Sie die Codex-Aufzeichnung: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -Damit wird der Kollektor installiert, als Hintergrunddienst registriert und die Aufzeichnung gestartet. Prüfe, ob er läuft: +Damit wird der Kollektor installiert, als Hintergrunddienst registriert und die Aufzeichnung gestartet. Prüfen Sie, ob er läuft: ```bash agenteye-collector health ``` -Beim ersten Start werden deine vorhandenen Codex-Sitzungen einmalig nachgefüllt, danach werden neue Aktivitäten innerhalb von Sekunden übertragen. Die Dateien von Codex werden ausschließlich gelesen – niemals verändert, verschoben oder gelöscht – und jede Sitzung wird genau einmal übertragen, auch nach einem Neustart. +Beim ersten Start werden Ihre vorhandenen Codex-Sitzungen einmalig nachträglich importiert, danach werden neue Aktivitäten innerhalb von Sekunden übertragen. Codex' eigene Dateien werden ausschließlich gelesen — nie verändert, verschoben oder gelöscht — und jede Sitzung wird genau einmal übermittelt, auch nach Neustarts. --- ## Wo die Daten erscheinen -Aufgezeichnete Sitzungen erscheinen unter **Sessions** und ihre Events im **Events**-Stream – genauso wie bei jedem anderen beobachteten Agenten. Damit funktionieren [Session-Replay](/de/agenteye/sessions), [Suche](/de/agenteye/queries), [Auswertungen](/de/agenteye/evaluations) und [Alerts](/de/agenteye/alerts) für sie ganz normal. Filtere nach dem Codex-Agenten, um nur diese anzuzeigen. +Aufgezeichnete Sitzungen erscheinen unter **Sitzungen** und ihre Ereignisse im **Ereignis**-Stream, genau wie jeder andere beobachtete Agent — sodass [Sitzungswiedergabe](/de/agenteye/sessions), [Suche](/de/agenteye/queries), [Auswertungen](/de/agenteye/evaluations) und [Benachrichtigungen](/de/agenteye/alerts) darauf anwendbar sind. Filtern Sie nach dem Codex-Agent, um nur dessen Sitzungen anzuzeigen. --- ## Datenschutz -Codex-Transkripte enthalten die vollständige Sitzung – einschließlich Befehlsausgaben, Dateiinhalten und allem, was Codex gelesen oder geschrieben hat – und können sensible Informationen enthalten. Aufgezeichnete Sitzungen werden unverändert übertragen. Aktiviere die Aufzeichnung daher nur auf Maschinen und für Teams, bei denen das Zentralisieren dieser Inhalte in AgentEye angemessen ist, und weise dem Kollektor ausschließlich einen Schlüssel mit dem Umfang `events:add` zu. Unter [Sicherheit](/de/agenteye/security) erfährst du, wie deine Daten isoliert aufbewahrt werden. \ No newline at end of file +Codex-Transkripte enthalten die vollständige Sitzung — einschließlich Befehlsausgaben, Dateiinhalte und allem, was Codex gelesen oder geschrieben hat — und können Geheimnisse enthalten. Aufgezeichnete Sitzungen werden unverändert übermittelt. Aktivieren Sie die Aufzeichnung daher nur auf Maschinen und für Teams, bei denen die zentrale Speicherung dieser Inhalte in AgentEye angemessen ist, und vergeben Sie dem Kollektor einen Key, der ausschließlich auf `events:add` beschränkt ist. Unter [Sicherheit](/de/agenteye/security) erfahren Sie, wie Ihre Daten isoliert aufbewahrt werden. \ No newline at end of file diff --git a/docs/de/agenteye/concepts.mdx b/docs/de/agenteye/concepts.mdx index 5f6c4000..dc45bd74 100644 --- a/docs/de/agenteye/concepts.mdx +++ b/docs/de/agenteye/concepts.mdx @@ -4,84 +4,84 @@ description: "Das Vokabular hinter Failproof AI Observability — Events, Sessio --- -Diese Seite definiert das Vokabular, das Failproof AI Observability verwendet. Wenn ein Begriff in einem anderen Leitfaden unbekannt ist, wird er hier erklärt. Sie müssen ihn nicht von Anfang bis Ende lesen: Überfliegen Sie ihn, oder kehren Sie zurück, wenn Sie ein Wort genauer nachschlagen möchten. +Diese Seite definiert das Vokabular, das Failproof AI Observability verwendet. Wenn ein Begriff in einer anderen Anleitung unbekannt ist, wird er hier erklärt. Sie müssen die Seite nicht von Anfang bis Ende lesen: Überfliegen Sie sie, oder springen Sie zurück, wenn Sie einen Begriff nachschlagen möchten. --- ## Das Datenmodell **Event** -Die kleinste Dateneinheit. Ein Event zeichnet einen einzelnen Schritt auf, den Ihr Agent ausgeführt hat: ein `tool_use`, ein `model_request`, ein `hook_completed`, ein `error` usw. Ihr Agent gibt Events über das [Python SDK](/de/agenteye/python-sdk) aus; sie erscheinen in Echtzeit auf der **Events**-Seite. +Die kleinste Dateneinheit. Ein Event zeichnet einen einzelnen Schritt auf, den Ihr Agent ausgeführt hat: ein `tool_use`, ein `model_request`, ein `hook_completed`, ein `error` und so weiter. Ihr Agent sendet Events über das [Python SDK](/de/agenteye/python-sdk); sie erscheinen live auf der **Events**-Seite. **Session** -Ein einzelner Agent-Lauf, identifiziert durch eine `session_id`. Eine Session umfasst alle Events, die diese ID teilen, zusammengefasst in einer einzelnen Zeile auf der **Sessions**-Seite und als Ausführungsgraph auf ihrer Detailseite dargestellt. Eine Session beginnt üblicherweise mit `agent_start` und endet mit `agent_end`. +Ein einzelner Agent-Lauf, identifiziert durch eine `session_id`. Eine Session umfasst alle Events, die dieselbe ID teilen, zusammengefasst in einer einzelnen Zeile auf der **Sessions**-Seite und als Ausführungsgraph auf der Detailseite dargestellt. Eine Session beginnt üblicherweise mit `agent_start` und endet mit `agent_end`. **Agent** -Ein benannter Akteur innerhalb eines Laufs, identifiziert durch eine `agent_id`. Ein Lauf kann mehrere Agents umfassen: zum Beispiel einen Planer, der einen Zusammenfassungs-Sub-Agenten startet. Sub-Agents tragen eine `parent_id`, die es Failproof AI Observability ermöglicht, sie in eigenen Spuren im Ausführungsgraph darzustellen. +Ein benannter Akteur innerhalb eines Laufs, identifiziert durch eine `agent_id`. Ein Lauf kann mehrere Agents umfassen: zum Beispiel ein Planer, der einen Zusammenfassungs-Sub-Agent erzeugt. Sub-Agents tragen eine `parent_id`, die es Failproof AI Observability ermöglicht, sie in eigenen Spuren im Ausführungsgraph darzustellen. **Environment** -Eine Bezeichnung für den Ort, an dem der Lauf stattgefunden hat: `production`, `staging`, `dev`. Sie legen sie einmalig bei der Konfiguration des SDK fest. Fast jede Dashboard-Seite kann nach Environment gefiltert werden. +Eine Bezeichnung dafür, wo der Lauf stattgefunden hat: `production`, `staging`, `dev`. Sie wird einmalig bei der SDK-Konfiguration festgelegt. Nahezu jede Dashboard-Seite lässt sich nach Environment filtern. **Context-Window-Auslastung** -Der prozentuale Anteil des Context-Windows eines Modells, den eine Antwort verbraucht hat. Failproof AI Observability versieht `model_response`-Events bei erkannten Modellen mit diesem Wert, sodass das Wachstum von Prompts und bevorstehende Kompaktierungen direkt im Event-Stream sichtbar sind. +Der Prozentsatz des Kontextfensters eines Modells, den eine Antwort verbraucht hat. Failproof AI Observability stempelt diesen Wert auf `model_response`-Events für bekannte Modelle, sodass das Wachstum von Prompts und eine bevorstehende Kompaktierung direkt im Event-Stream sichtbar sind. --- ## Qualität **Evaluation** -Eine Qualitätsbewertung für eine abgeschlossene Session, die von einem Scoring-Dienst erstellt wird, den Sie selbst betreiben. Evaluierungen sind optional: Bis Sie einen Evaluator anschließen, werden Sessions aufgezeichnet, aber nicht bewertet. Jede Evaluierung kann mehrere benannte Scores enthalten (zum Beispiel `helpfulness`, `factuality`, `tool_efficiency`), jeweils mit einer kurzen Begründungsnotiz. Siehe [Evaluation suite](/de/agenteye/evaluation-suite). +Ein Qualitätswert für eine abgeschlossene Session, erstellt von einem Scoring-Service, den Sie betreiben. Evaluierungen sind optional: Solange Sie keinen Evaluator angebunden haben, werden Sessions aufgezeichnet, aber nicht bewertet. Jede Evaluation kann mehrere benannte Scores enthalten (z. B. `helpfulness`, `factuality`, `tool_efficiency`), jeweils mit einer kurzen Begründungsnotiz. Siehe [Evaluation suite](/de/agenteye/evaluation-suite). -**Score-Key** -Der Name einer Dimension, über die ein Evaluator berichtet, z. B. `helpfulness`. Alerts und Audits können einen bestimmten Score-Key im Zeitverlauf beobachten. +**Score Key** +Der Name einer Dimension, die ein Evaluator meldet, z. B. `helpfulness`. Alerts und Audits können einen bestimmten Score Key im Zeitverlauf beobachten. **Evaluator** -Ihr Scoring-Dienst. Failproof AI Observability übermittelt das Transkript eines abgeschlossenen Laufs per POST an ihn und speichert die zurückgegebenen Scores. Ein Standard-Evaluator wird nicht mitgeliefert; die Bewertungslogik liegt bei Ihnen. +Ihr Scoring-Service. Failproof AI Observability sendet das Transkript eines abgeschlossenen Laufs per POST an diesen Service und speichert die zurückgegebenen Scores. Es wird kein Standard-Evaluator mitgeliefert; die Scoring-Logik liegt bei Ihnen. --- ## Fehler finden und beheben **Hook** -Eine Sicherheitsvorkehrung oder ein Nebeneffekt, den Ihr Agent-Framework um einen Schritt herum ausführt: eine Inhaltssicherheitsprüfung, PII-Schwärzung oder eine Budget-Überwachung. Hooks geben `hook_triggered`- / `hook_completed`-Events mit einem `outcome` (allow, deny, modify) aus und haben eine eigene Observe-Seite. +Eine Schutzmaßnahme oder ein Nebeneffekt, den Ihr Agent-Framework rund um einen Schritt ausführt: eine Inhaltssicherheitsprüfung, PII-Redaktion, ein Budget-Guard. Hooks senden `hook_triggered`/`hook_completed`-Events mit einem `outcome` (allow, deny, modify) und haben eine eigene Beobachtungsseite. **Alert-Regel** Eine Regel, die ausgelöst wird, wenn eine Metrik einen von Ihnen festgelegten Schwellenwert überschreitet: Fehlerrate, p95-Latenz, Token-Kosten oder ein Evaluator-Score. Wenn eine Regel ausgelöst wird, öffnet sie einen Incident und benachrichtigt Ihre gewählten Kanäle (E-Mail, Slack, Webhook, im Dashboard). Siehe [Alerts](/de/agenteye/alerts). **Incident** -Ein offenes Problem, das entsteht, wenn eine Alert-Regel ausgelöst wird. Incidents haben einen Lebenszyklus (bestätigen, zuweisen, lösen) und eine Aktivitäts-Timeline, die jede Aktion aufzeichnet. Sie können auch manuell einen öffnen. +Ein offenes Problem, das entsteht, wenn eine Alert-Regel ausgelöst wird. Incidents haben einen Lebenszyklus (bestätigen, zuweisen, lösen) und eine Aktivitätszeitachse, die jede Aktion aufzeichnet. Sie können einen Incident auch manuell öffnen. **Audit** -Eine wiederkehrende Untersuchung (stündlich bis wöchentlich), die Ihre Logs *sitzungsübergreifend* nach Fehlermustern durchsucht, für die Sie noch keine Regel geschrieben haben: Fehler-Cluster, niedrige Scores, Latenz-Ausreißer, Tool-Call-Schleifen und Läufe, die nie abgeschlossen wurden. Während ein Alert eine Metrik überwacht, die Sie bereits kennen, zeigt Ihnen ein Audit, worauf Sie als Nächstes achten sollten. Siehe [Audits](/de/agenteye/audits). +Eine wiederkehrende Untersuchung (stündlich bis wöchentlich), die Ihre Logs *sitzungsübergreifend* nach Fehlermustern durchsucht, für die Sie noch keine Regel geschrieben haben: Fehler-Cluster, niedrige Scores, Latenz-Ausreißer, Tool-Call-Schleifen und Läufe, die nie abgeschlossen wurden. Während ein Alert eine Ihnen bereits bekannte Metrik überwacht, zeigt Ihnen ein Audit, worauf Sie als Nächstes achten sollten. Siehe [Audits](/de/agenteye/audits). **Finding** -Ein priorisiertes, evidenzbasiertes Ergebnis eines Audit-Laufs. Ein Finding benennt ein Muster, verlinkt auf die genauen Sessions dahinter und trägt einen Triage-Lebenszyklus (bestätigen, lösen, stummschalten, verwerfen). Failproof AI Observability dedupliziert Findings laufübergreifend, sodass ein bekanntes Muster aktualisiert wird, anstatt sich anzuhäufen. +Ein priorisiertes, evidenzgestütztes Ergebnis eines Audit-Laufs. Ein Finding benennt ein Muster, verlinkt auf die genauen Sessions dahinter und hat einen Triage-Lebenszyklus (bestätigen, lösen, stummschalten, verwerfen). Failproof AI Observability dedupliziert Findings laufübergreifend, sodass ein bekanntes Muster aktualisiert wird, anstatt sich anzuhäufen. **Der KI-Assistent** -Der im Dashboard integrierte Chat, der auf Englisch Fragen zu Ihren Agents beantwortet — basierend auf Ihren eigenen Daten. Er ist standardmäßig schreibgeschützt; alles, was er erstellt (eine gespeicherte Abfrage, ein Dashboard), erfordert eine Genehmigung, und er kann niemals löschen. Siehe [AI assistant](/de/agenteye/assistant). +Der Dashboard-interne Chat, der Fragen zu Ihren Agents auf natürlichem Deutsch über Ihre eigenen Daten beantwortet. Er ist standardmäßig schreibgeschützt; alles, was er erstellt (eine gespeicherte Abfrage, ein Dashboard), erfordert eine Genehmigung, und er kann niemals löschen. Siehe [AI assistant](/de/agenteye/assistant). --- ## Betrieb **Organisation (Tenant)** -Ein isolierter Arbeitsbereich. Eine Failproof AI Observability-Instanz kann viele Organisationen hosten, jede mit eigenen Benutzern, Schlüsseln und Daten. Jede Dashboard-URL ist unter Ihrem Org-Slug (`//…`) eingeschränkt. +Ein isolierter Arbeitsbereich. Eine Failproof AI Observability-Instanz kann viele Organisationen hosten, jede mit ihren eigenen Nutzern, Schlüsseln und Daten. Jede Dashboard-URL ist unter Ihrem Org-Slug (`//…`) eingeschränkt. **Collector** -`agenteye-collector`, der schlanke Daemon, der auf jedem Agent-Rechner läuft, die Events bündelt, die das SDK auf die Festplatte schreibt, und sie an den Server übermittelt. +`agenteye-collector`, der schlanke Daemon, der auf jedem Agent-Rechner läuft, die vom SDK auf die Festplatte geschriebenen Events bündelt und an den Server sendet. -**API-Key** -Ein bereichsbeschränktes Token, das einen Client gegenüber dem Server authentifiziert. Keys tragen granulare Berechtigungen (zum Beispiel `events:add` für den Collector, schreibgeschützte Bereiche für einen Dashboard-Key). Siehe [API keys](/de/agenteye/api-keys). +**API-Schlüssel** +Ein bereichsbegrenztes Token, das einen Client gegenüber dem Server authentifiziert. Schlüssel tragen granulare Berechtigungen (z. B. `events:add` für den Collector, schreibgeschützte Bereiche für einen Dashboard-Schlüssel). Siehe [API keys](/de/agenteye/api-keys). **Server** -Der Ingest- und API-Dienst. Er nimmt Events entgegen, speichert den Betriebszustand in Ihren Datenbanken und stellt das Dashboard und die CLI bereit. +Der Ingest- und API-Service. Er nimmt Events entgegen, speichert den Betriebszustand in Ihren Datenbanken und bedient das Dashboard und die CLI. **Dashboard** -Die Web-Oberfläche. Jede Seite ist auf eine Organisation beschränkt und liest über die API des Servers. +Die Web-Benutzeroberfläche. Jede Seite ist auf eine Organisation beschränkt und liest über die API des Servers. --- ## Nächste Schritte -- [Overview](/de/agenteye/overview): Wie diese Teile zusammenpassen. -- [Observability](/de/agenteye/observability): Die Observe-Oberflächen (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file +- [Overview](/de/agenteye/overview): wie diese Bausteine zusammenpassen. +- [Observability](/de/agenteye/observability): die Beobachtungsoberflächen (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file diff --git a/docs/de/agenteye/dashboards.mdx b/docs/de/agenteye/dashboards.mdx index 90c4cd37..2d82741b 100644 --- a/docs/de/agenteye/dashboards.mdx +++ b/docs/de/agenteye/dashboards.mdx @@ -1,46 +1,46 @@ --- title: "Dashboards" -description: "Verwandeln Sie Ihre Live-Agentendaten in ein gemeinsames Bild, das Ihr gesamtes Team im Blick behält." +description: "Verwandeln Sie Ihre Live-Agent-Daten in ein gemeinsames Bild, das Ihr gesamtes Team im Blick behält." --- -Verwandeln Sie Ihre Live-Agentendaten in ein gemeinsames Bild, das Ihr gesamtes Team im Blick behält. Pinnen Sie die wichtigsten Abfragen als Diagramme, und alle sehen auf Anhieb dieselben Zahlen – ohne eine einzige Abfrage erneut ausführen zu müssen. +Verwandeln Sie Ihre Live-Agent-Daten in ein gemeinsames Bild, das Ihr gesamtes Team im Blick behält. Pinnen Sie die wichtigsten Abfragen als Diagramme, und jeder sieht auf Anhieb dieselben Zahlen – ohne eine einzige Abfrage erneut ausführen zu müssen. -![Ein Dashboard aus gespeicherten Abfragen: eine Ereignisse-pro-Stunde-Linie, ein Fehler-nach-Typ-Balken, ein Latenz-Flächendiagramm und Tokens nach Modell](/agenteye/images/dashboard-fleet.png) +![Ein Dashboard aus gespeicherten Abfragen: eine Linien-Darstellung der Ereignisse pro Stunde, ein Balkendiagramm der Fehler nach Typ, ein Flächen-Diagramm der Latenz und Tokens nach Modell](/agenteye/images/dashboard-fleet.png) *Ein Board, vier gespeicherte Abfragen: Ereignisse pro Stunde, Fehler nach Typ, Latenz und Tokens nach Modell.* ## Alle sehen dieselbe Wahrheit -Schluss mit Screenshots in Chat-Nachrichten und dem fünfmaligen täglichen Wiederholen derselben Abfrage. Ein Dashboard ist ein gemeinsames, organisationsweites Board, das jedes Teammitglied in exakt derselben Ansicht öffnen kann. Wenn sich die zugrunde liegenden Daten ändern, passen sich die Diagramme automatisch an – das Board ist also immer aktuell, und niemand streitet mehr über veraltete Zahlen. +Schluss mit Screenshots im Chat und mit dem fünfmaligen Ausführen derselben Abfrage pro Tag. Ein Dashboard ist ein gemeinsames, organisationsweites Board, das jedes Teammitglied öffnen kann und dabei exakt dieselbe Ansicht erhält. Wenn sich die zugrundeliegenden Daten ändern, aktualisieren sich die Diagramme automatisch – das Board ist stets aktuell, und niemand streitet mehr über veraltete Zahlen. Das Fleet-Dashboard oben ist ein guter Ausgangspunkt für den täglichen Betrieb: -- eine **Ereignisse-pro-Stunde**-Linie, um den Durchsatz zu beobachten und plötzliche Einbrüche zu erkennen -- ein **Fehler-nach-Typ**-Balken, damit die häufigsten Fehlerkategorien sofort ins Auge springen +- eine **Ereignisse-pro-Stunde**-Linie, um den Durchsatz im Blick zu behalten und plötzliche Einbrüche zu erkennen +- ein **Fehler-nach-Typ**-Balkendiagramm, damit die häufigsten Fehlerkategorien sofort ins Auge springen - ein **Latenz**-Flächendiagramm, damit Verlangsamungen sichtbar werden, bevor Nutzer sich beschweren -- eine **Tokens-nach-Modell**-Aufschlüsselung, damit die Kosten stets im Blick bleiben +- eine **Tokens-nach-Modell**-Aufschlüsselung, damit die Kosten immer im Blick bleiben Ihre Boards finden Sie unter `//dashboards`. -## Gespeicherte Abfragen pinnen +## Bereits gespeicherte Abfragen pinnen -Jede Kachel beginnt als gespeicherte Abfrage. Erstellen und speichern Sie die gewünschte Abfrage in der [Queries](/de/agenteye/queries)-Bibliothek (mit integrierten Voreinstellungen und eigenen Abfragen über Ihre Ereignisse und Auswertungen), und pinnen Sie sie dann als passendes Diagramm auf ein Dashboard: eine **Linie** für Trends über die Zeit, ein **Balken** für Kategorienvergleiche, eine **Fläche** für Volumina oder ein **Kreisdiagramm** für Anteile. +Jede Kachel beginnt als gespeicherte Abfrage. Erstellen und speichern Sie die gewünschte Abfrage in der [Queries](/de/agenteye/queries)-Bibliothek (mit integrierten Vorlagen sowie eigenen Abfragen über Ihre Ereignisse und Evaluierungen) und pinnen Sie sie dann als passendes Diagramm auf ein Dashboard: eine **Linie** für Trends über die Zeit, ein **Balkendiagramm** zum Vergleich von Kategorien, eine **Fläche** für Volumen oder ein **Kreisdiagramm** für Anteile. Da eine Kachel lediglich Ihre gespeicherte Abfrage als Diagramm darstellt, müssen Sie nichts manuell synchronisieren. Aktualisieren Sie die Abfrage einmal, und jedes Dashboard, das sie verwendet, wird automatisch aktualisiert. ## Qualität im Blick behalten, nicht nur Volumen -Das Volumen zeigt Ihnen, dass die Agenten beschäftigt sind. Die Qualität zeigt Ihnen, ob sie ihre Aufgabe tatsächlich erfüllen. Richten Sie ein Dashboard auf Ihre [Auswertungs-Scores](/de/agenteye/evaluations) aus, und Sie erhalten ein Board, das verfolgt, wie gut die Ausführungen im Laufe der Zeit laufen – sodass ein Qualitätsrückgang als Einbruch im Diagramm erscheint und nicht als böse Überraschung eines Kunden. +Das Volumen zeigt Ihnen, dass die Agents beschäftigt sind. Die Qualität zeigt, ob sie ihren Job tatsächlich erledigen. Richten Sie ein Dashboard auf Ihre [Evaluierungswerte](/de/agenteye/evaluations) aus, und Sie erhalten ein Board, das den Verlauf der Ausführungsqualität über die Zeit verfolgt – sodass eine Qualitätsverschlechterung als Dip im Diagramm sichtbar wird, anstatt als böse Überraschung von einem Kunden zu kommen. -![Ein qualitätsorientiertes Dashboard aus gespeicherten Auswertungsabfragen](/agenteye/images/dashboard-quality.png) +![Ein qualitätsorientiertes Dashboard aus gespeicherten Evaluierungsabfragen](/agenteye/images/dashboard-quality.png) -*Ein Qualitäts-Board hält Ihre Auswertungs-Scores stets im Vordergrund, direkt neben den operativen Kennzahlen.* +*Ein Qualitäts-Board hält Ihre Evaluierungswerte stets im Mittelpunkt – direkt neben den operativen Kennzahlen.* Halten Sie ein Betriebs-Board und ein Qualitäts-Board nebeneinander, und Ihr Team hat einen einzigen Ort, um sowohl „Funktioniert es?" als auch „Ist es gut?" zu beantworten – ohne dass jemand eine Abfrage erneut ausführen muss. -## Verwandtes +## Verwandte Themen -- [Queries](/de/agenteye/queries): Erstellen und speichern Sie die Abfragen, die zu Ihren Kacheln werden. -- [Evaluations](/de/agenteye/evaluations): Bewerten Sie Ihre Ausführungen, um die Qualität über die Zeit abzubilden. +- [Queries](/de/agenteye/queries): Erstellen und speichern Sie die Abfragen, aus denen Ihre Kacheln entstehen. +- [Evaluations](/de/agenteye/evaluations): Bewerten Sie Ihre Ausführungen, damit Sie die Qualität über die Zeit visualisieren können. - [Alerts](/de/agenteye/alerts): Wandeln Sie einen Schwellenwert für eine dieser Metriken in eine Benachrichtigung um. \ No newline at end of file diff --git a/docs/de/agenteye/error-tracking.mdx b/docs/de/agenteye/error-tracking.mdx index fd96ef44..4b0aeb7c 100644 --- a/docs/de/agenteye/error-tracking.mdx +++ b/docs/de/agenteye/error-tracking.mdx @@ -1,41 +1,41 @@ --- title: "Fehlerverfolgung" -description: "Sehen Sie jeden Fehler Ihrer Agenten an einem Ort, gruppiert, damit ein Fehlerstoß als ein einziges Problem erscheint." +description: "Alle Fehler Ihrer Agents auf einen Blick, gruppiert, sodass ein Fehlersturm als einzelnes Problem erscheint." --- -Sehen Sie jeden Fehler Ihrer Agenten an einem Ort, gruppiert, damit ein Fehlerstoß als ein einziges Problem erscheint. Sie erhalten einen Klick-Pfad von „etwas ist rot" bis zum genauen Lauf, der abgebrochen ist, ohne einen Live-Feed durchscrollen zu müssen. +Alle Fehler Ihrer Agents auf einen Blick, gruppiert, sodass ein Fehlersturm als einzelnes Problem erscheint. Mit einem einzigen Klick gelangen Sie von „irgendwas leuchtet rot" direkt zu dem Run, der den Fehler verursacht hat – ohne in einem Live-Feed nach dem Eintrag suchen zu müssen. -![Die Fehlerseite: ein Histogramm der Fehler über die Zeit über gruppierten roten Fehlerzeilen, jede mit einer Ein-Klick-Schaltfläche „+ alert"](/agenteye/images/errors.png) -*Die Fehlerseite: ein Histogramm der Fehler über die Zeit, wobei wiederkehrende Fehler in einer Zeile pro Vorfall zusammengefasst werden.* +![Die Errors-Seite: ein Histogramm der Fehler über die Zeit über gruppierten roten Fehlerzeilen, jede mit einem "+ alert"-Knopf per Mausklick](/agenteye/images/errors.png) +*Die Errors-Seite: ein Histogramm der Fehler über die Zeit, wobei wiederholte Fehler zu einer Zeile pro Vorfall zusammengefasst werden.* -## Jeder Fehler, bereits für Sie gesammelt +## Alle Fehler, bereits für Sie gesammelt -Wenn ein Agent abstürzt, sollten Sie keinen Live-Event-Stream durchscrollen müssen, um rote Zeilen zu finden, bevor sie verschwinden. Die **Fehlerseite** übernimmt das Sammeln für Sie. Sie bündelt alles, was das Dashboard rot markieren würde, auf einer einzigen Triage-Oberfläche – das Erste, was Sie sehen, ist, was fehlschlägt, nicht wo Sie danach suchen müssen. +Wenn ein Agent abstürzt, sollten Sie nicht in einem Live-Event-Stream scrollen müssen und hoffen, die roten Zeilen zu erwischen, bevor sie verschwinden. Die **Errors**-Seite übernimmt das Sammeln für Sie. Sie fasst alles, was das Dashboard rot markieren würde, auf einer einzigen Triage-Oberfläche zusammen – sodass das Erste, was Sie sehen, das ist, was fehlschlägt, und nicht die Suche danach, wo man anfangen soll. -Und sie erfasst mehr als die offensichtlichen Fehler. Neben expliziten `error`-Events macht Failproof AI Observability auch die stillen Fehler sichtbar: Jedes `tool_result`, `hook_completed` oder `agent_end`, dessen Payload einen Fehler enthält, wird hier angezeigt. Ein Tool, das einen Fehler zurückgegeben hat, oder ein Hook, der fehlerhaft beendet wurde, entgeht Ihnen nicht mehr, nur weil keine laute Exception ausgelöst wurde. +Dabei werden nicht nur die offensichtlichen Fehler erfasst. Zusätzlich zu expliziten `error`-Events zeigt Failproof AI Observability auch die stillen Fehler an: jedes `tool_result`, `hook_completed` oder `agent_end`, dessen Payload einen Fehler enthält, erscheint hier. Ein Tool, das einen Fehler zurückgegeben hat, oder ein Hook, der fehlerhaft beendet wurde, entgeht Ihnen nicht mehr, nur weil keine laute Exception geworfen wurde. -Am oberen Rand zeigt ein Histogramm Fehler über die Zeit. Ein Blick zeigt Ihnen, ob es sich um ein stetiges Hintergrundrauschen oder um einen Anstieg handelt, der vor wenigen Minuten begann – damit wissen Sie sofort, ob Sie alles stehen und liegen lassen müssen. +Am oberen Rand zeigt ein Histogramm Fehler über die Zeit an. Auf einen Blick sehen Sie, ob es sich um ein stetiges Hintergrundrauschen oder um einen Spike handelt, der vor wenigen Minuten begann – so wissen Sie sofort, ob Sie alles stehen und liegen lassen müssen. -Wie jede Beobachtungsoberfläche ist die Fehlerseite auf Ihre Organisation begrenzt und lässt sich nach Datumsbereich, Umgebung, Agent und Session filtern. So können Sie eine flottenweit gültige Liste auf den einen Agent oder die eine Umgebung eingrenzen, die Sie tatsächlich interessiert. +Wie jede Observe-Oberfläche ist auch die Errors-Seite auf Ihre Organisation beschränkt und lässt sich nach Datumsbereich, Umgebung, Agent und Session filtern. Das bedeutet: Sie können eine flottenweit gültige Liste nehmen und sie auf den einen Agent oder die eine Umgebung eingrenzen, auf die es wirklich ankommt. -## Ein Vorfall, nicht hundert identische Zeilen +## Ein Vorfall, keine hundert identischen Zeilen -Eine einzige defekte Abhängigkeit kann denselben Fehler hunderte Male pro Minute auslösen. Unbearbeitet ergibt das eine Wand aus nahezu identischen Zeilen, die das Wesentliche verbirgt. +Eine einzelne defekte Abhängigkeit kann denselben Fehler hunderte Male pro Minute auslösen. Unverarbeitet ist das eine Wand fast identischer Zeilen, die genau das begräbt, was Sie eigentlich sehen müssen. -Failproof AI Observability fasst wiederkehrende Fehler mit derselben Session und demselben Fehlertyp in einer einzigen Zeile zusammen. Ein Fehlerstoß erscheint als ein einziger Vorfall. Sie zählen Probleme, keine Log-Zeilen – und das Signal, das wichtig ist, bleibt oben, anstatt von seinem eigenen Volumen überwältigt zu werden. +Failproof AI Observability fasst wiederholte Fehler, die dieselbe Session und denselben Fehlertyp teilen, in einer einzigen Zeile zusammen. Ein Fehlersturm erscheint als ein einziger Vorfall. Sie zählen Probleme, keine Log-Zeilen – und das relevante Signal bleibt oben, anstatt von seiner eigenen Menge überwältigt zu werden. -## Von „etwas ist rot" zum genauen Event +## Von „irgendwas leuchtet rot" zum genauen Event -Klicken Sie auf eine beliebige Zeile, um direkt in die Session dieses Laufs zu gelangen, positioniert auf dem genauen Event, das fehlgeschlagen ist. Kein Kopieren von Session-IDs, kein Scrollen, um den Moment des Fehlers zu finden: Sie landen genau dort, mit dem vollständigen Ausführungsgraph auf einen Blick, sodass Sie sehen können, was der Agent in den Momenten vor dem Absturz getan hat. +Klicken Sie auf eine Zeile, um direkt in die Session dieses Runs zu gelangen – positioniert auf genau dem Event, das fehlgeschlagen ist. Kein Kopieren von Session-IDs, kein Scrollen auf der Suche nach dem Moment, an dem es schiefging: Sie landen genau dort, mit dem vollständigen Ausführungsgraphen auf einen Blick, sodass Sie sehen können, was der Agent in den Momenten vor dem Fehler getan hat. -Wenn Sie `alerts:write`-Berechtigung haben, enthält jede Zeile auch eine **+ alert**-Schaltfläche. Klicken Sie darauf, öffnet Observability eine neue Alert-Regel, die bereits so ausgefüllt ist, dass sie denselben Fehler beim nächsten Mal erkennt. Der Vorfall, den Sie gerade triagiert haben, wird zu dem, der Sie beim nächsten Mal benachrichtigt – anstatt Sie zweimal zu überraschen. +Wenn Sie `alerts:write`-Berechtigung haben, enthält jede Zeile auch eine **+ alert**-Schaltfläche. Klicken Sie darauf, öffnet Observability eine neue Alert-Regel, die bereits vorkonfiguriert ist, um denselben Fehler erneut abzufangen. Der Vorfall, den Sie gerade triagiert haben, wird zum nächsten, der Sie benachrichtigt – statt Sie ein zweites Mal zu überraschen. -**Wo Sie es finden:** Die **Fehlerseite** befindet sich im Beobachtungsbereich des Dashboards unter `//errors`. +**Wo Sie es finden:** Die **Errors**-Seite befindet sich im Observe-Bereich des Dashboards unter `//errors`. ## Verwandte Themen -- [Alerts](/de/agenteye/alerts): Jeden Fehler in eine Benachrichtigungsregel umwandeln. -- [Incidents](/de/agenteye/incidents): Einen ausgelösten Alert von offen bis gelöst verfolgen. -- [Sessions](/de/agenteye/sessions): Den vollständigen Lauf hinter einem Fehler öffnen. -- [Audits](/de/agenteye/audits): Observability Fehlermuster in Ihren Läufen automatisch erkennen lassen. \ No newline at end of file +- [Alerts](/de/agenteye/alerts): Verwandeln Sie jeden Fehler in eine Benachrichtigungsregel. +- [Incidents](/de/agenteye/incidents): Verfolgen Sie einen ausgelösten Alert von der Eröffnung bis zur Lösung. +- [Sessions](/de/agenteye/sessions): Öffnen Sie den vollständigen Run hinter einem Fehler. +- [Audits](/de/agenteye/audits): Lassen Sie Observability Fehlermuster in Ihren Runs für Sie finden. \ No newline at end of file diff --git a/docs/de/agenteye/evaluation-suite.mdx b/docs/de/agenteye/evaluation-suite.mdx index 917a5e29..28e5e6fc 100644 --- a/docs/de/agenteye/evaluation-suite.mdx +++ b/docs/de/agenteye/evaluation-suite.mdx @@ -1,22 +1,22 @@ --- title: "Evaluation Suite" -description: "Failproof AI Observability bewertet automatisch jeden abgeschlossenen Agenten-Lauf auf Qualität: Sie stellen einen kleinen Scoring-Dienst bereit, und Observability erledigt den Rest." +description: "Failproof AI Observability bewertet automatisch jeden abgeschlossenen Agenten-Run auf Qualität: Sie stellen einen kleinen Scoring-Service bereit, und Observability übernimmt den Rest." --- -Failproof AI Observability kann jeden abgeschlossenen Agenten-Lauf automatisch auf Qualität bewerten: Sie stellen einen kleinen Scoring-Dienst bereit, und Observability erledigt den Rest. Nutzen Sie es, um die Dimensionen zu verfolgen, die Ihnen wichtig sind (Hilfsbereitschaft, Tool-Effizienz, Faktentreue, Sicherheit – Sie entscheiden), Regressionen frühzeitig zu erkennen und Agenten oder Umgebungen auf einen Blick zu vergleichen. Scoring ist optional: Die Pipeline tut nichts, bis Sie `EVALUATOR_ENDPOINT` auf dem Server setzen. +Failproof AI Observability kann jeden abgeschlossenen Agenten-Run automatisch auf Qualität bewerten: Sie stellen einen kleinen Scoring-Service bereit, und Observability übernimmt den Rest. Nutzen Sie es, um die für Sie relevanten Dimensionen zu verfolgen (Hilfsbereitschaft, Tool-Effizienz, Faktentreue, Sicherheit – Sie bestimmen die Kriterien), Regressionen frühzeitig zu erkennen und Agenten oder Umgebungen auf einen Blick zu vergleichen. Das Scoring ist optional: Die Pipeline ist inaktiv, bis Sie `EVALUATOR_ENDPOINT` auf dem Server setzen. > **Hinweis:** Sie definieren die Score-Dimensionen. Ihr Evaluator kann beliebige numerische Schlüssel zurückgeben; Observability speichert, verfolgt und zeigt alles an, was Sie zurücksenden. ## Auf einen Blick -1. **Schreiben Sie einen Scorer.** Starten Sie einen kleinen HTTP-Dienst, der ein Sitzungsprotokoll liest und Scores zurückgibt. Observability liefert ein funktionsfähiges Referenzbeispiel, das Sie kopieren können. Siehe [Evaluator mit dem SDK schreiben](#writing-an-evaluator-with-the-sdk). -2. **Richten Sie Observability darauf aus.** Setzen Sie `EVALUATOR_ENDPOINT` (und ein gemeinsames `EVALUATOR_TOKEN`) auf dem Serverprozess. -3. **Beobachten Sie die eingehenden Scores.** Jede abgeschlossene Sitzung wird automatisch bewertet; die Ergebnisse erscheinen auf der Sitzungsdetailseite, im Sitzungsraster und in gespeicherten Dashboards. +1. **Schreiben Sie einen Scorer.** Stellen Sie einen kleinen HTTP-Service bereit, der ein Session-Transkript liest und Scores zurückgibt. Observability enthält einen funktionierenden Referenz-Evaluator, den Sie kopieren können. Siehe [Einen Evaluator mit dem SDK schreiben](#writing-an-evaluator-with-the-sdk). +2. **Richten Sie Observability darauf aus.** Setzen Sie `EVALUATOR_ENDPOINT` (und ein gemeinsames `EVALUATOR_TOKEN`) im Server-Prozess. +3. **Beobachten Sie die eintreffenden Scores.** Jede abgeschlossene Session wird automatisch bewertet; die Ergebnisse erscheinen auf der Session-Detailseite, im Sessions-Grid und in gespeicherten Dashboards. -![Eine Sitzungsdetailansicht mit der Bewertungszusammenfassung, Scores pro Dimension als Balken und Begründungstext in der rechten Spalte](/agenteye/images/session-detail.png) +![Eine Session-Detailansicht mit der Evaluierungs-Zusammenfassung, dimensionsspezifischen Score-Balken und Begründungstext in der rechten Spalte](/agenteye/images/session-detail.png) -*Sobald ein Evaluator konfiguriert ist, wird jeder abgeschlossene Lauf bewertet, und die Ergebnisse erscheinen in der rechten Spalte der Sitzung: oben die Zusammenfassung, dann Score-Balken pro Dimension mit Begründung.* +*Sobald ein Evaluator konfiguriert ist, wird jeder abgeschlossene Run bewertet und die Ergebnisse erscheinen in der rechten Spalte der Session: die Zusammenfassung oben, dann dimensionsspezifische Score-Balken mit Begründung.* --- @@ -32,33 +32,63 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Wenn das Observability SDK ein `agent_end`-Ereignis für eine Sitzung auslöst, plant der Server eine Bewertung. Er sendet dann per POST das vollständige Ereignisprotokoll an Ihren Evaluator-Dienst, der entweder: +Wenn das Observability SDK ein `agent_end`-Event für eine Session ausgibt, plant der Server eine Evaluierung. Anschließend sendet er das vollständige Event-Transkript per POST an Ihren Evaluator-Service, der entweder: -- **Das Ergebnis direkt zurückgibt** mit `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Das Ergebnis wird an die Bewertungs-Timeline der Sitzung angehängt. `reasoning` und `summary` sind optional. -- **Verzögert** mit `{"status":"pending", "job_id":"abc-123"}`. Observability ruft dann `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` auf, bis Ihr Evaluator `{"status":"done", ...}` oder `{"status":"error", "error":"..."}` zurückgibt. +- **Das Ergebnis direkt zurückgeben** kann mit `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Das + Ergebnis wird der Evaluierungs-Timeline der Session hinzugefügt. `reasoning` und + `summary` sind optional. +- **Zurückstellen** kann mit `{"status":"pending", "job_id":"abc-123"}`. Observability ruft dann + `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` auf, bis Ihr Evaluator + `{"status":"done", ...}` oder `{"status":"error", "error":"..."}` zurückgibt. - Der Abfrageintervall ist pro Job konfigurierbar: Eine `pending`-Antwort kann `next_poll_secs` enthalten, um den Standardwert zu überschreiben; andernfalls verwendet Observability den Wert `default_poll_interval_secs` aus `GET /config`; ansonsten fällt der Server auf `EVALUATOR_POLLING_INTERVAL_SECS` zurück (Standard: 10 s). Alle Werte werden auf [1 s, 1 h] begrenzt. + Die Polling-Frequenz ist pro Job konfigurierbar: Eine `pending`-Antwort kann + `next_poll_secs` enthalten, um den Standardwert zu überschreiben; andernfalls verwendet Observability den + `default_poll_interval_secs`-Wert aus `GET /config`; andernfalls fällt der Server + auf `EVALUATOR_POLLING_INTERVAL_SECS` zurück (Standard: 10s). Alle Werte + werden auf [1s, 1h] begrenzt. -Sitzungen, die niemals `agent_end` auslösen (zum Beispiel ein abgestürzter Agentenprozess), können ebenfalls erfasst werden: Das `GET /config` des Evaluators kann `{"inactivity_timeout_secs": 1800}` zurückgeben, und Observability bewertet jede Sitzung, die so lange inaktiv war. Setzen Sie das Feld auf `null` oder lassen Sie es weg, um diesen Fallback zu deaktivieren. +Sessions, die nie ein `agent_end`-Event senden (z. B. ein abgestürzter Agenten-Prozess), +können ebenfalls erfasst werden: Das `GET /config` des Evaluators kann +`{"inactivity_timeout_secs": 1800}` zurückgeben, und Observability bewertet jede Session, +die so lange inaktiv war. Setzen Sie das Feld auf `null` oder lassen Sie es weg, um +diesen Fallback zu deaktivieren. Die Pipeline ist vollständig inaktiv, wenn `EVALUATOR_ENDPOINT` nicht gesetzt ist. -Eine Sitzung kann **mehrere abschließende Bewertungen im Laufe der Zeit** ansammeln: Jedes `agent_end`-Ereignis (und jede manuelle Neubewertung über das Dashboard) fügt eine neue Bewertungszeile hinzu. Dies ist die unterstützte Methode zur Bewertung eines wiederaufgenommenen Gesprächs: Ein Benutzer beendet einen Agenten, kommt später zurück, sendet weitere Ereignisse, beendet den Agenten erneut, und eine zweite Bewertung läuft gegen das vollständig aktualisierte Protokoll. Das Dashboard zeigt die aktuellste Bewertung als Hauptanzeige und die früheren Bewertungen als aufklappbare Timeline. Während eine Bewertung für eine Sitzung läuft, werden weitere `agent_end`-Ereignisse für diese Sitzung ignoriert; das nächste nach Abschluss der laufenden Bewertung stellt wie gewohnt eine neue Bewertung in die Warteschlange. - -Der Inaktivitäts-Fallback greift auch bei wiederaufgenommenen Sitzungen: Wenn nach einer vorherigen abschließenden Bewertung neue Ereignisse eintreffen und die Sitzung dann länger als `inactivity_timeout_secs` inaktiv bleibt, wird eine neue Bewertung in die Warteschlange gestellt. - -Vorübergehende Fehler (5xx, 429, Timeouts, Netzwerkfehler) werden mit exponentiellem Backoff bis zu `EVALUATOR_MAX_ATTEMPTS` wiederholt; 4xx-Antworten sind endgültig. Observability kann sicher mit mehreren horizontal skalierten Serverinstanzen betrieben werden; die Arbeit wird so aufgeteilt, dass dieselbe Sitzung nie gleichzeitig zweimal verteilt wird. +Eine Session kann **im Laufe der Zeit mehrere abschließende Evaluierungen ansammeln**: Jedes +`agent_end`-Event (und jede manuelle Neubewertung über das Dashboard) fügt eine neue +Evaluierungszeile hinzu. Dies ist der empfohlene Weg, um ein fortgeführtes +Gespräch zu evaluieren: Ein Nutzer beendet einen Agenten, kehrt später zurück, sendet weitere Events, +beendet den Agenten erneut, und eine zweite Evaluierung wird gegen das vollständige aktualisierte +Transkript durchgeführt. Das Dashboard zeigt die aktuellste Evaluierung als Hauptanzeige +und die vorherigen Evaluierungen als ausklappbare Timeline. Während eine +Evaluierung für eine Session läuft, werden weitere `agent_end`-Events für diese +Session ignoriert; das nächste nach Abschluss der laufenden Evaluierung +stellt eine neue Evaluierung in die Warteschlange. + +Der Inaktivitäts-Fallback greift auch bei fortgeführten Sessions: Wenn nach einer +vorherigen abschließenden Evaluierung neue Events eintreffen und die Session dann +länger als `inactivity_timeout_secs` inaktiv bleibt, wird eine neue Evaluierung eingereiht. + +Vorübergehende Fehler (5xx, 429, Timeouts, Netzwerkfehler) werden mit +exponentiellem Backoff bis zu `EVALUATOR_MAX_ATTEMPTS`-mal wiederholt; 4xx-Antworten sind +endgültig. Observability lässt sich sicher mit mehreren horizontal skalierten Server-Instanzen betreiben; +die Arbeit wird so aufgeteilt, dass dieselbe Session nie gleichzeitig zweimal verarbeitet wird. --- ## HTTP-Vertrag -Alle authentifizierten Routen verwenden **Bearer-Token-Authentifizierung**. Derselbe Wert muss auf beiden Seiten konfiguriert sein: +Jede authentifizierte Route verwendet **Bearer-Token-Authentifizierung**. Derselbe Wert muss +auf beiden Seiten konfiguriert sein: - Observability-Server: Umgebungsvariable `EVALUATOR_TOKEN` -- Evaluator-Dienst: auf dieselbe Weise konfiguriert (das `agenteye-evaluator` SDK liest `EVALUATOR_TOKEN` gemäß Konvention) +- Evaluator-Service: gleich konfiguriert (das `agenteye-evaluator`-SDK + liest `EVALUATOR_TOKEN` per Konvention) -Wenn `EVALUATOR_TOKEN` nicht gesetzt ist, sendet der Server keinen `Authorization`-Header; der Evaluator kann dann anonyme Anfragen akzeptieren, was für ein rein internes Netzwerk in Ordnung ist, im öffentlichen Internet jedoch nicht empfohlen wird. +Wenn `EVALUATOR_TOKEN` nicht gesetzt ist, sendet der Server keinen `Authorization`-Header; der +Evaluator kann dann anonyme Anfragen akzeptieren, was für ein +rein internes Netzwerk akzeptabel ist, im öffentlichen Internet jedoch nicht empfohlen wird. ### Routen, die der Evaluator bereitstellen muss @@ -102,33 +132,46 @@ Wenn `EVALUATOR_TOKEN` nicht gesetzt ist, sendet der Server keinen `Authorizatio } ``` -`reasoning` (eine Begründungszuordnung pro Score) und `summary` (eine zusammenfassende Gesamterzählung) sind beide optional. Schlüssel in `reasoning` sollten die Schlüssel in `scores` widerspiegeln; das Dashboard rendert jeden Eintrag direkt unter seinem Score-Balken. Ältere Evaluatoren, die nur `scores` zurückgeben, funktionieren weiterhin unverändert; `reasoning` und `summary` werden einfach als null gelesen, und die entsprechenden UI-Elemente werden weggelassen. +`reasoning` (eine Begründungszuordnung pro Score) und `summary` (eine allgemeine +Zusammenfassung in einem Absatz) sind beide optional. Schlüssel in `reasoning` sollten +die Schlüssel in `scores` widerspiegeln; das Dashboard rendert jeden Eintrag direkt unter +dem zugehörigen Score-Balken. Ältere Evaluatoren, die nur `scores` zurückgeben, funktionieren +weiterhin unverändert; `reasoning` und `summary` werden dann als null interpretiert und +die entsprechenden UI-Elemente werden ausgeblendet. -**Asynchron (deferred):** +**Asynchron (zurückgestellt):** ```json { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` ist optional; wenn weggelassen, fällt der Server auf den `default_poll_interval_secs`-Wert des Evaluators aus `/config` zurück, dann auf seine eigene Umgebungsvariable `EVALUATOR_POLLING_INTERVAL_SECS`. +`next_poll_secs` ist optional; wenn nicht angegeben, fällt der Server auf den +`default_poll_interval_secs`-Wert des Evaluators aus `/config` zurück, dann auf seine eigene +`EVALUATOR_POLLING_INTERVAL_SECS`-Umgebungsvariable. -**Endgültiger evaluatorseitiger Fehler:** +**Abschließender Fehler auf Evaluator-Seite:** ```json { "status": "error", "error": "model service unavailable" } ``` -Der Server behandelt jeden anderen 2xx-Body als Protokollfehler und protokolliert einen endgültigen `error` für die Sitzung. +Der Server behandelt jeden anderen 2xx-Body als Protokollfehler und zeichnet einen +abschließenden `error` für die Session auf. --- -## Evaluator mit dem SDK schreiben +## Einen Evaluator mit dem SDK schreiben -Sie müssen den HTTP-Vertrag nicht manuell implementieren. Das Python-Paket `agenteye-evaluator` bietet Ihnen einen typisierten FastAPI-Wrapper, der Authentifizierung, Routing und die Anfrage-/Antwortformate für Sie übernimmt. +Sie müssen den HTTP-Vertrag nicht manuell implementieren. Das Python-Paket `agenteye-evaluator` +bietet Ihnen einen typisierten FastAPI-Wrapper, der Authentifizierung, Routing und +die Anfrage-/Antwortformate für Sie übernimmt. -Failproof AI Observability liefert auch einen **funktionsfähigen Referenz-Evaluator**, der `helpfulness`, `tool_efficiency` und `factuality` anhand der Struktur des Protokolls bewertet. Kopieren Sie ihn als Ausgangspunkt und tauschen Sie Ihre eigene Logik ein: ein LLM-Richter, eine Regelmaschine – was auch immer Ihrem Qualitätsstandard entspricht. +Failproof AI Observability enthält außerdem einen **funktionierenden Referenz-Evaluator**, der +`helpfulness`, `tool_efficiency` und `factuality` anhand der Struktur des +Transkripts bewertet. Kopieren Sie ihn als Ausgangspunkt und ersetzen Sie die Logik durch Ihre eigene: einen LLM- +Richter, eine Regelmaschine oder was auch immer Ihrem Qualitätsanspruch entspricht. -Minimal funktionsfähiger Evaluator: +Minimaler funktionsfähiger Evaluator: ```python import os @@ -147,42 +190,56 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -Die `app`-Instanz läuft unter jedem ASGI-Server, sodass `uvicorn module:app` sie startet. +Die `app`-Instanz läuft unter jedem ASGI-Server, `uvicorn module:app` startet sie. -Für Evaluatoren, die aufwändige Arbeit verzögern müssen, geben Sie stattdessen `JobPending` zurück und registrieren Sie einen `@app.job_lookup`-Handler; der Observability-Server fragt `GET /evaluate/{job_id}` ab, bis Sie einen endgültigen Status zurückgeben oder die Obergrenze `EVALUATOR_MAX_POLL_DURATION_SECS` (Standard: 1 h) erreicht wird. +Für Evaluatoren, die aufwändige Arbeit zurückstellen müssen, geben Sie stattdessen `JobPending` +zurück und registrieren Sie einen `@app.job_lookup`-Handler; der Observability-Server +pollt `GET /evaluate/{job_id}`, bis Sie einen abschließenden Status zurückgeben oder die +`EVALUATOR_MAX_POLL_DURATION_SECS`-Grenze (Standard: 1 h) erreicht wird. -Die vollständige API-Referenz, das asynchrone Muster und das Ereignisschema sind in der README des `agenteye-evaluator` SDK dokumentiert. +Die vollständige API-Referenz, das asynchrone Muster und das Event-Schema sind in der +README des `agenteye-evaluator`-SDKs dokumentiert. --- -## Ihren Evaluator betreiben +## Den Evaluator betreiben -Der Evaluator ist **Ihr Dienst** – Failproof AI Observability liefert keinen Standard-Evaluator, daher erstellen und betreiben Sie ihn dort, wo Sie Ihre eigenen Dienste betreiben. Er läuft unter jedem ASGI-Server (zum Beispiel `uvicorn my_evaluator:app`); stellen Sie die Routen `/health`, `/config` und `/evaluate` gemäß dem [HTTP-Vertrag](#http-contract) bereit, und verweisen Sie den Server darauf (siehe [Server konfigurieren](#configuring-the-server)). +Der Evaluator ist **Ihr Service** – Failproof AI Observability liefert keinen +Standard-Evaluator mit, Sie bauen und betreiben ihn dort, wo Sie Ihre eigenen Services betreiben. +Er läuft unter jedem ASGI-Server (z. B. `uvicorn my_evaluator:app`); stellen Sie +die Routen `/health`, `/config` und `/evaluate` gemäß dem +[HTTP-Vertrag](#http-contract) bereit und verweisen Sie den Server darauf (siehe +[Den Server konfigurieren](#configuring-the-server)). -Sobald der Evaluator erreichbar ist, gibt `GET /health` `{"status":"ok"}` zurück. Nachdem ein Agent vollständig durchgelaufen ist, gibt `GET /evaluations` auf dem Server eine Zeile mit `status: "done"` und den von Ihrem Evaluator erzeugten Scores zurück. +Sobald der Evaluator erreichbar ist, gibt `GET /health` `{"status":"ok"}` zurück. Nachdem +ein Agent einen vollständigen Durchlauf absolviert hat, gibt `GET /evaluations` auf dem Server eine Zeile mit +`status: "done"` und den von Ihrem Evaluator produzierten Scores zurück. --- -## Server konfigurieren +## Den Server konfigurieren -Auf dem Serverprozess setzen: +Auf dem Server-Prozess setzen: | Umgebungsvariable | Bedeutung | |---|---| | `EVALUATOR_ENDPOINT` | Basis-URL Ihres Evaluators (`http://evaluator:9000`). Nicht gesetzt = Pipeline deaktiviert. | -| `EVALUATOR_TOKEN` | Bearer-Token. Muss dem Wert entsprechen, mit dem der Evaluator-Dienst konfiguriert ist. | -| `EVALUATOR_WORKERS` | Worker-Tasks pro Serverinstanz (Standard: 2). | -| `EVALUATOR_CLAIM_BATCH` | Pro Worker-Tick beanspruchte Zeilen (Standard: 4). Batches werden **gleichzeitig** verarbeitet; die effektive Parallelität auf Ihrem Evaluator-Endpunkt beträgt `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Wie lange ein Worker zwischen Verteilungsversuchen schläft, wenn keine Bewertung fällig ist (Standard: 2 s). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Endgültiger Fallback für den `GET /evaluate/{id}`-Intervall, wenn weder das antwortspezifische `next_poll_secs` noch das `default_poll_interval_secs` des Evaluators gesetzt ist (Standard: 10 s). | +| `EVALUATOR_TOKEN` | Bearer-Token. Muss dem Wert entsprechen, mit dem der Evaluator-Service konfiguriert ist. | +| `EVALUATOR_WORKERS` | Worker-Tasks pro Server-Instanz (Standard: 2). | +| `EVALUATOR_CLAIM_BATCH` | Zeilen, die pro Worker-Tick beansprucht werden (Standard: 4). Batches werden **gleichzeitig** verarbeitet; die effektive Parallelität auf Ihrem Evaluator-Endpunkt beträgt `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Wie lange ein Worker zwischen Dispatch-Versuchen wartet, wenn keine Evaluierung fällig ist (Standard: 2s). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Letzter Fallback für die `GET /evaluate/{id}`-Frequenz, wenn weder das antwortspezifische `next_poll_secs` noch das `default_poll_interval_secs` des Evaluators gesetzt ist (Standard: 10s). | | `EVALUATOR_REQUEST_TIMEOUT_MS` | Timeout pro Anfrage (Standard: 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | Nach so vielen vorübergehenden Fehlern wird das Ergebnis als endgültiger `error` aufgezeichnet (Standard: 5). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config`-Intervall (Standard: 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Maximale Echtzeit, die eine Sitzung in der Abfragewarteschlange verbleiben kann, bevor sie als `timeout` beendet wird (Standard: 3600 s). Schützt vor einem Evaluator, der dauerhaft `pending` zurückgibt. | +| `EVALUATOR_MAX_ATTEMPTS` | Nach so vielen vorübergehenden Fehlern wird das Ergebnis als abschließender `error` aufgezeichnet (Standard: 5). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config`-Frequenz (Standard: 300). | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Maximale Echtzeit, die eine Session in der Polling-Warteschlange verbleiben darf, bevor sie als `timeout` beendet wird (Standard: 3600s). Schützt vor einem Evaluator, der dauerhaft `pending` zurückgibt. | -Um automatisches Scoring zu aktivieren, setzen Sie sowohl `EVALUATOR_ENDPOINT` als auch `EVALUATOR_TOKEN` auf dem Server und starten Sie ihn dann neu, damit die Änderungen wirksam werden. Ohne gesetztes `EVALUATOR_ENDPOINT` bleibt die Pipeline inaktiv. +Um automatisches Scoring zu aktivieren, setzen Sie sowohl `EVALUATOR_ENDPOINT` als auch +`EVALUATOR_TOKEN` auf dem Server und starten Sie ihn neu, damit die Änderung übernommen wird. Wenn +`EVALUATOR_ENDPOINT` nicht gesetzt ist, bleibt die Pipeline inaktiv. -Die obigen Feinabstimmungsoptionen sind optional; setzen Sie die entsprechenden Umgebungsvariablen auf dem Server nur, wenn Sie die Standardwerte überschreiben müssen. +Die oben genannten Konfigurationsoptionen sind optional; setzen Sie die entsprechenden Umgebungsvariablen +auf dem Server nur, wenn Sie die Standardwerte überschreiben möchten. --- @@ -190,48 +247,53 @@ Die obigen Feinabstimmungsoptionen sind optional; setzen Sie die entsprechenden | Methode | Pfad | Erforderliche Berechtigung | Zweck | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Endgültige Ergebnisse abfragen. Unterstützt `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` ist standardmäßig 50 und auf 200 begrenzt (beachten Sie, dass dies von `/events` abweicht, das auf 1000 begrenzt ist). `environment` akzeptiert eine kommagetrennte Liste (z. B. `environment=prod,staging`); einzelne Werte funktionieren weiterhin. Mit `latest_per_session=true` enthält die Antwort höchstens eine Zeile pro `session_id` (die aktuellste nach `completed_at`), die von der Sitzungsliste verwendet wird, um die Bewertungs-Timeline einer Sitzung auf ihre aktuelle Hauptanzeige zu reduzieren. Standardmäßig false (gibt den vollständigen Verlauf zurück). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | Zusammengefasste Bewertungsqualität für ein gefiltertes Segment: Gesamtanzahl, eine Aufschlüsselung nach done/error/timeout, Statistiken pro Score-Schlüssel (Anzahl/Durchschnitt/Min/Max/p50 über die beliebigen `scores`-Schlüssel) und eine zeitlich aufgeteilte Timeline. Akzeptiert **dieselben Filterparameter wie `/evaluations`** plus `featured_keys` (CSV der zu trendenden Score-Schlüssel) und `latest_per_session`. Betreibt die Dashboards-Funktion; Metriken sind über den gesamten übereinstimmenden Datensatz exakt, nicht gesampelt. | -| `GET` | `/evaluations/environments` | `evaluations:read` | Eindeutige Umgebungswerte aus der `evaluations`-Tabelle. Wird verwendet, um Filter-Dropdowns zu befüllen, die auf bewertungslesbare Daten beschränkt sind. | -| `GET` | `/evaluation-jobs` | `evaluations:read` | Einblick in laufende Bewertungen. Filtern nach `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | Die Rohereignisse einer Sitzung streamen. Unterstützt `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` und `order`. `order` ist `desc` (neueste zuerst, Standard) oder `asc` (älteste zuerst); ein unbekannter Wert fällt auf `desc` zurück. Cursor-Paginierung über den `next_cursor` der Antwort (eine Ereignis-ID): Übergeben Sie ihn als `cursor`, um die nächste Seite zu erhalten; bei `asc` sind dies die Ereignisse nach dieser ID, bei `desc` die Ereignisse davor. `limit` ist standardmäßig 50 und auf 1000 begrenzt. | -| `GET` | `/sessions/:session_id/export` | `events:read` | Gibt den genauen JSON-Body zurück, den der Evaluator für diese Sitzung erhalten würde, als herunterladbaren Anhang mit dem Namen `session-.json`. Nützlich zum Wiedergeben von Produktionssitzungen durch `agenteye-evaluator` für Offline-Tests. Die Bytes sind byteidentisch mit dem, was die Evaluator-Pipeline sendet. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Eine neue Bewertung für eine Sitzung in die Warteschlange stellen; läuft unabhängig davon, ob eine frühere Bewertung vorhanden ist. Das neue Ergebnis wird an die Bewertungs-Timeline der Sitzung **angehängt**, anstatt das vorherige zu überschreiben, sodass frühere Scores als Verlauf sichtbar bleiben. Gibt `202` bei Einstellung in die Warteschlange zurück, `404` für eine unbekannte Sitzung, `409` wenn bereits eine Bewertung läuft. Verwenden Sie dies nach der Bereitstellung eines neuen Evaluators oder für Sitzungen, die niemals `agent_end` ausgelöst haben. | +| `GET` | `/evaluations` | `evaluations:read` | Abschließende Ergebnisse abfragen. Unterstützt `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` ist standardmäßig 50 und maximal 200 (beachten Sie, dass dies von `/events` abweicht, das maximal 1000 zulässt). `environment` akzeptiert eine kommagetrennte Liste (z. B. `environment=prod,staging`); einzelne Werte funktionieren weiterhin. Mit `latest_per_session=true` enthält die Antwort höchstens eine Zeile pro `session_id` (die aktuellste nach `completed_at`), die von der Sessions-Listenseite verwendet wird, um die Evaluierungs-Timeline einer Session auf ihre aktuelle Hauptanzeige zu reduzieren. Standardmäßig false (gibt den vollständigen Verlauf zurück). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | Aggregierte Evaluierungs-Kennzahlen für einen gefilterten Bereich: Gesamtanzahl, Aufschlüsselung nach done/error/timeout, statistiken pro Score-Schlüssel (count/avg/min/max/p50 über die beliebigen `scores`-Schlüssel) und eine zeitlich gegliederte Timeline. Akzeptiert **dieselben Filterparameter wie `/evaluations`** plus `featured_keys` (CSV der Score-Schlüssel für Trends) und `latest_per_session`. Treibt die Dashboards-Funktion an; Metriken sind exakt über die gesamte übereinstimmende Menge berechnet, nicht gesampelt. | +| `GET` | `/evaluations/environments` | `evaluations:read` | Eindeutige Umgebungswerte aus der `evaluations`-Tabelle. Wird verwendet, um Filter-Dropdowns zu befüllen, die auf evaluierungslesbare Daten beschränkt sind. | +| `GET` | `/evaluation-jobs` | `evaluations:read` | Einblick in laufende Evaluierungen. Filtern nach `status` (`pending`/`polling`). | +| `GET` | `/events` | `events:read` | Rohe Events einer Session streamen. Unterstützt `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` und `order`. `order` ist `desc` (neueste zuerst, Standard) oder `asc` (älteste zuerst); ein unbekannter Wert fällt auf `desc` zurück. Cursor-Paginierung über `next_cursor` der Antwort (eine Event-ID): als `cursor` zurückgeben, um die nächste Seite zu erhalten; mit `asc` sind das die Events nach dieser ID, mit `desc` die Events davor. `limit` ist standardmäßig 50 und maximal 1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | Gibt den genauen JSON-Body zurück, den der Evaluator für diese Session erhalten würde, als herunterladbaren Anhang namens `session-.json`. Nützlich zum Wiederholen von Produktions-Sessions durch `agenteye-evaluator` für Offline-Tests. Die Bytes sind byteidentisch mit dem, was die Evaluator-Pipeline sendet. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Stellt eine neue Evaluierung für eine Session in die Warteschlange; wird ausgeführt, unabhängig davon, ob eine vorherige Evaluierung vorhanden ist. Das neue Ergebnis wird der Evaluierungs-Timeline der Session **hinzugefügt** und überschreibt die vorherige nicht, sodass frühere Scores als Verlauf sichtbar bleiben. Gibt `202` bei Einreihen zurück, `404` für eine unbekannte Session, `409` wenn bereits eine Evaluierung läuft. Verwenden Sie dies nach dem Deployment eines neuen Evaluators oder für Sessions, die nie `agent_end` gesendet haben. | ### Nach Score-Bereich filtern: `score_filters` -`GET /evaluations` akzeptiert einen optionalen `score_filters`-Parameter, der Ergebnisse nach numerischen Werten im `scores`-Objekt einschränkt. Der Parameter ist eine kommagetrennte Liste von `key:min..max`-Einträgen; jede Grenze kann weggelassen werden. Mehrere Einträge werden mit logischem UND kombiniert. Zeilen, bei denen der genannte Schlüssel fehlt oder nicht numerisch ist, werden ausgeschlossen. Eine Anfrage darf höchstens 20 Filtereinträge enthalten; bei Überschreitung wird HTTP 400 zurückgegeben. +`GET /evaluations` akzeptiert einen optionalen `score_filters`-Parameter, der +Ergebnisse nach numerischen Werten innerhalb des `scores`-Objekts einschränkt. Der +Parameter ist eine kommagetrennte Liste von `key:min..max`-Einträgen; beide +Grenzen können weggelassen werden. Mehrere Einträge werden mit logischem UND verknüpft. Zeilen, +bei denen der genannte Schlüssel fehlt oder nicht numerisch ist, werden ausgeschlossen. Eine Anfrage darf +höchstens 20 Filtereinträge enthalten; bei Überschreitung wird HTTP 400 zurückgegeben. Beispiele: ```text # helpfulness in [0.5, 0.8] GET /evaluations?score_filters=helpfulness:0.5..0.8 -# tool_efficiency at most 0.3 (no lower bound) +# tool_efficiency höchstens 0.3 (keine Untergrenze) GET /evaluations?score_filters=tool_efficiency:..0.3 -# helpfulness >= 0.5 AND factuality >= 0.9 +# helpfulness >= 0.5 UND factuality >= 0.9 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` -Jedes `/evaluations`-Antwortobjekt hat folgende Felder: +Jedes `/evaluations`-Antwortobjekt hat diese Felder: | Feld | Typ | Hinweise | |---|---|---| -| `evaluation_id` | string (UUID) | Der kanonische Bezeichner für diese endgültige Bewertung. Jede endgültige Bewertung erhält eine neue UUID; eine einzelne Sitzung kann mehrere enthalten. | -| `id` | string (UUID) | Abwärtskompatibilitäts-Alias mit demselben Wert wie `evaluation_id`. | -| `session_id` | string | Die Sitzung, gegen die diese Bewertung gelaufen ist. Eine Sitzung kann mehrere Bewertungen in der Timeline haben. | -| `agent_id` | string | Identifiziert den Agenten, der die Sitzung erzeugt hat. | -| `environment` | string | Umgebungsbezeichnung, die aus der Sitzung kopiert wurde. | +| `evaluation_id` | string (UUID) | Der kanonische Bezeichner für diese abschließende Evaluierung. Jede abschließende Evaluierung erhält eine neue UUID; eine einzelne Session kann mehrere haben. | +| `id` | string (UUID) | Rückwärtskompatibilitäts-Alias mit demselben Wert wie `evaluation_id`. | +| `session_id` | string | Die Session, gegen die diese Evaluierung durchgeführt wurde. Eine Session kann mehrere Evaluierungen in der Timeline haben. | +| `agent_id` | string | Identifiziert den Agenten, der die Session erzeugt hat. | +| `environment` | string | Aus der Session kopiertes Umgebungs-Label. | | `status` | enum | Eines von `"done"`, `"error"`, `"timeout"`. | | `scores` | object \| null | Von Ihrem Evaluator zurückgegebene Scores. | -| `reasoning` | object \| null | Optionale Begründungszuordnung pro Score, zurückgegeben von Ihrem Evaluator. Schlüssel spiegeln typischerweise die in `scores` wider. Das Dashboard rendert jeden Eintrag unter seinem Score-Balken. | -| `summary` | string \| null | Optionale zusammenfassende Gesamterzählung, zurückgegeben von Ihrem Evaluator. Das Dashboard rendert diese oberhalb der Score-Aufschlüsselung als Hauptanzeige der Bewertung. | +| `reasoning` | object \| null | Optionale, von Ihrem Evaluator zurückgegebene Begründungszuordnung pro Score. Schlüssel entsprechen typischerweise denen in `scores`. Das Dashboard rendert jeden Eintrag unter dem zugehörigen Score-Balken. | +| `summary` | string \| null | Optionale, vom Evaluator zurückgegebene allgemeine Zusammenfassung in einem Absatz. Das Dashboard rendert diese über der dimensionsspezifischen Aufschlüsselung als Evaluierungs-Überschrift. | | `error` | string \| null | Nur bei `"error"` / `"timeout"` befüllt. | -| `attempt_count` | integer | Anzahl der Verteilungsversuche (≥ 1). | +| `attempt_count` | integer | Anzahl der Dispatch-Versuche (≥ 1). | | `duration_ms` | integer \| null | Dauer des letzten Versuchs. | -| `completed_at` | string (ISO 8601 UTC) | Zeitpunkt, zu dem das endgültige Ergebnis aufgezeichnet wurde. Ergebnisse sind nach `completed_at` geordnet (neueste zuerst). | -| `created_at` | string (ISO 8601 UTC) | Enthält denselben Zeitstempel wie `completed_at` (einmalige Schreibsemantik). | +| `completed_at` | string (ISO 8601 UTC) | Zeitpunkt, zu dem das abschließende Ergebnis aufgezeichnet wurde. Ergebnisse werden nach `completed_at` geordnet (neueste zuerst). | +| `created_at` | string (ISO 8601 UTC) | Trägt denselben Zeitstempel wie `completed_at` (Einmal-Schreib-Semantik). | --- @@ -239,9 +301,9 @@ Jedes `/evaluations`-Antwortobjekt hat folgende Felder: | Berechtigung | Gewährt | |---|---| -| `evaluations:read` | Bewertungsergebnisse auflisten, Scores im Dashboard anzeigen und Dashboard-Qualitätsmetriken laden. | -| `evaluations:trigger` | Manuell eine Bewertung für eine Sitzung über `POST /sessions/:session_id/re-evaluate` oder die Neubewertungsschaltfläche im Dashboard in die Warteschlange stellen. | -| `dashboards:read` | Gespeicherte Dashboards anzeigen (benötigt auch `evaluations:read`, um deren Metriken zu laden). | +| `evaluations:read` | Evaluierungsergebnisse auflisten, Scores im Dashboard anzeigen und Dashboard-Kennzahlen laden. | +| `evaluations:trigger` | Manuell eine Evaluierung für eine Session über `POST /sessions/:session_id/re-evaluate` oder den Neubewertungs-Button im Dashboard einreihen. | +| `dashboards:read` | Gespeicherte Dashboards anzeigen (erfordert auch `evaluations:read` zum Laden der Kennzahlen). | | `dashboards:write` | Dashboards erstellen und bearbeiten. | | `dashboards:delete` | Dashboards löschen. | @@ -251,50 +313,81 @@ Der Bootstrap-Administrator (`ADMIN_KEY`, `ADMIN_EMAIL`) erhält diese automatis ## Ergebnisse anzeigen -- **`/sessions/`**: Ereignis-Timeline + eine rechte Spalte mit den Scores der Sitzung und etwaigen Fehlern aus dem Verteilungsversuch. Wenn Ihr Schlüssel `evaluations:trigger` hat, erscheint neben der Export-Schaltfläche eine **Neubewerten**-Schaltfläche, nützlich für Sitzungen, die niemals `agent_end` ausgelöst haben, oder zum Aktualisieren von Scores nach der Bereitstellung eines neuen Evaluators. Das Dashboard fragt das neue Ergebnis ab und aktualisiert die rechte Spalte, wenn es eintrifft. -- **`/sessions`**: filterbares Sitzungsraster; die Score-Spalte zeigt den Bewertungsstatus und die Scores jeder Sitzung auf einen Blick. -- **`/dashboards`**: gespeicherte Bewertungsqualitätsansichten (siehe [Dashboards](#dashboards) unten). +- **`/sessions/`**: Event-Timeline und eine rechte Spalte mit den Scores der Session + sowie eventuellen Fehlern aus dem Dispatch-Versuch. Wenn Ihr Schlüssel + `evaluations:trigger` hat, erscheint neben dem Export-Button ein **Neubewerten**-Button, + nützlich für Sessions, die nie `agent_end` gesendet haben, oder um Scores nach dem Deployment + eines neuen Evaluators zu aktualisieren. Das Dashboard pollt das neue Ergebnis und aktualisiert die rechte Spalte, wenn es eintrifft. +- **`/sessions`**: Filterbares Session-Grid; die Score-Spalte zeigt auf einen Blick den Evaluierungsstatus und die Scores jeder Session. +- **`/dashboards`**: Gespeicherte Evaluierungs-Gesundheitsansichten (siehe [Dashboards](#dashboards) unten). -![Das Sitzungsraster mit Bewertungsstatuspillen pro Sitzung und farbcodierten Score-Abzeichen (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) +![Das Sessions-Grid mit sessionspezifischen Evaluierungsstatus-Badges und farbcodierten Score-Abzeichen (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) -*Das Sitzungsraster zeigt den Bewertungsstatus und die Scores jedes Laufs auf einen Blick; rote/gelbe/grüne Abzeichen lassen niedrige Scores sofort auffallen.* +*Das Sessions-Grid zeigt den Evaluierungsstatus und die Scores jedes Runs auf einen Blick; rote/gelbe/grüne Badges heben niedrige Scores hervor.* --- ## Dashboards -Die **Dashboards**-Seite (`/dashboards`) ermöglicht es Ihnen, eine Kombination von Bewertungsfiltern als benannte, wiederverwendbare Ansicht zu speichern und zu beobachten, wie sich dieses Segment von Bewertungen entwickelt. Dashboards werden **organisationsweit geteilt**; jeder mit `dashboards:read` sieht denselben Satz. +Die **Dashboards**-Seite (`/dashboards`) ermöglicht es Ihnen, eine Kombination aus Evaluierungsfiltern +als benannte, wiederverwendbare Ansicht zu speichern und zu beobachten, wie dieser Evaluierungsausschnitt +auf einen Blick abschneidet. Dashboards werden **innerhalb Ihrer gesamten Organisation geteilt**; +alle mit `dashboards:read` sehen denselben Satz. -Jedes Dashboard fixiert: +Jedes Dashboard speichert: -- **Filter**: dieselben Steuerelemente wie die Sitzungsseite: Umgebung, Status, Agent, ein rollierendes Zeitfenster und Score-Bereichsfilter (`key:min..max`). -- **Eine Anzeigekonfiguration**: welche Score-Schlüssel hervorgehoben werden, die grünen/gelben/roten Qualitätsschwellen, welche Panels angezeigt werden und ob auf die neueste Bewertung pro Sitzung reduziert werden soll. +- **Filter**: dieselben Steuerelemente wie die Sessions-Seite: Umgebung, Status, + Agent, ein rollierendes Zeitfenster und Score-Bereich-Filter (`key:min..max`). +- **Eine Anzeigekonfiguration**: welche Score-Schlüssel hervorgehoben werden, die grünen/gelben/roten + Schwellenwerte für den Gesundheitsstatus, welche Panels angezeigt werden und ob auf die aktuellste + Evaluierung pro Session reduziert werden soll. -Jede Karte zeigt die Anzahl übereinstimmender Sitzungen, eine done/error/timeout-Aufschlüsselung, den Durchschnitt jedes hervorgehobenen Scores und eine kleine Trend-Sparkline. Das Öffnen eines Dashboards zeigt die vollständigen Panels; **„In Sitzungen öffnen"** führt Sie zur Sitzungsseite, die genau auf dieses Segment vorge filtert ist. Metriken werden serverseitig über den gesamten übereinstimmenden Datensatz berechnet (über `GET /evaluations/aggregate`), sodass die Zahlen exakt und nicht gesampelt sind. +Jede Karte zeigt die Anzahl übereinstimmender Sessions, eine Aufschlüsselung nach done/error/timeout, +den Durchschnitt jedes hervorgehobenen Scores und einen kleinen Trend-Sparkline. Das Öffnen eines +Dashboards zeigt die Panels in voller Größe; **„in Sessions öffnen"** wechselt zur +Sessions-Seite mit genau diesem Filter vorausgewählt. Metriken werden serverseitig über die gesamte +übereinstimmende Menge berechnet (über `GET /evaluations/aggregate`), sodass die Zahlen exakt und nicht gesampelt sind. -![Ein Bewertungsqualitäts-Dashboard mit durchschnittlichen Score-Balken pro Evaluatordimension, einer Tool-ok-vs-error-Aufschlüsselung, Top-Tools und einem Ereignisse-pro-Stunde-Trend](/agenteye/images/dashboard-quality.png) +![Ein Evaluierungs-Gesundheits-Dashboard mit durchschnittlichen Score-Balken pro Evaluator-Dimension, einer Tool-ok-vs-Fehler-Aufschlüsselung, Top-Tools und einem Events-pro-Stunde-Trend](/agenteye/images/dashboard-quality.png) -**Berechtigungen:** Anzeigen erfordert sowohl `dashboards:read` als auch `evaluations:read`; Erstellen und Bearbeiten erfordert `dashboards:write`; Löschen erfordert `dashboards:delete`. Der Bootstrap-Administrator erhält all diese automatisch. +**Berechtigungen:** Anzeigen erfordert sowohl `dashboards:read` als auch `evaluations:read`; +Erstellen und Bearbeiten erfordert `dashboards:write`; Löschen erfordert `dashboards:delete`. +Der Bootstrap-Administrator erhält alle diese automatisch. --- ## Fehlerbehebung -**Sitzungen sind vorhanden, aber es werden keine Bewertungen erstellt.** Bestätigen Sie, dass `EVALUATOR_ENDPOINT` auf dem Serverprozess gesetzt ist, dass Server und Evaluator denselben `EVALUATOR_TOKEN`-Wert verwenden, und dass der `/health`-Endpunkt des Evaluators vom Server aus erreichbar ist. Ohne gesetztes `EVALUATOR_ENDPOINT` ist die Pipeline inaktiv. +**Sessions vorhanden, aber keine Evaluierungen werden erstellt.** Stellen Sie sicher, dass `EVALUATOR_ENDPOINT` +im Server-Prozess gesetzt ist, dass Server und Evaluator denselben `EVALUATOR_TOKEN`-Wert verwenden, +und dass der `/health`-Endpunkt des Evaluators vom Server erreichbar ist. Wenn `EVALUATOR_ENDPOINT` nicht gesetzt ist, ist die Pipeline inaktiv. -**Laufende Bewertungen stauen sich auf.** Fragen Sie `GET /evaluation-jobs` ab, um die laufende Warteschlange zu sehen. Überprüfen Sie `attempt_count`, `next_attempt_at` und `last_error` in jeder Zeile. Häufige Ursachen: Evaluator-Dienst nicht erreichbar oder gibt 5xx zurück (wird mit Backoff wiederholt), falsches `EVALUATOR_TOKEN` (401 ist endgültig), oder ein asynchroner Evaluator, der dauerhaft `pending` zurückgibt (siehe unten). +**Laufende Evaluierungen häufen sich an.** Fragen Sie `GET /evaluation-jobs` ab, um die +laufende Warteschlange einzusehen. Prüfen Sie `attempt_count`, `next_attempt_at` und `last_error` +für jede Zeile. Häufige Ursachen: Evaluator-Service nicht erreichbar oder gibt 5xx zurück +(wird mit Backoff wiederholt), falsches `EVALUATOR_TOKEN` (401 ist abschließend), oder ein +asynchroner Evaluator, der dauerhaft `pending` zurückgibt (siehe unten). -**Sitzungen abgeschlossen, aber keine endgültige Bewertung.** Fragen Sie `GET /evaluation-jobs?status=polling` ab; das Ergebnis kann noch in Bearbeitung sein. Wenn ein Job in `pending` feststeckt, hat der Server Probleme, den Evaluator zu erreichen; prüfen Sie, ob der Evaluator läuft und ob `EVALUATOR_TOKEN` übereinstimmt. +**Sessions abgeschlossen, aber keine abschließende Evaluierung.** Fragen Sie +`GET /evaluation-jobs?status=polling` ab; das Ergebnis könnte noch in Bearbeitung sein. +Wenn ein Job in `pending` feststeckt, hat der Server Probleme, den Evaluator zu erreichen; +prüfen Sie, ob der Evaluator läuft und ob `EVALUATOR_TOKEN` übereinstimmt. -**`HTTP 401 from evaluator: invalid bearer token`.** Das `EVALUATOR_TOKEN` auf dem Server stimmt nicht mit dem Wert überein, mit dem der Evaluator-Dienst konfiguriert ist. Sie müssen identisch sein. +**`HTTP 401 from evaluator: invalid bearer token`.** Das `EVALUATOR_TOKEN` +auf dem Server stimmt nicht mit dem Wert überein, mit dem der Evaluator-Service konfiguriert ist. +Sie müssen identisch sein. -**Asynchroner Evaluator gibt dauerhaft `pending` zurück.** Der Server fragt `GET /evaluate/{job_id}` ab, bis der Evaluator `done` oder `error` zurückgibt, oder bis `EVALUATOR_MAX_POLL_DURATION_SECS` (Standard: 1 h) abläuft. Nach Erreichen der Obergrenze wird die Bewertung als `timeout` aufgezeichnet und aus der laufenden Warteschlange entfernt. Erhöhen Sie `EVALUATOR_MAX_POLL_DURATION_SECS`, wenn Ihr Evaluator legitimerweise länger als den Standard benötigt. +**Asynchroner Evaluator gibt dauerhaft `pending` zurück.** Der Server pollt +`GET /evaluate/{job_id}`, bis der Evaluator `done` oder `error` zurückgibt, oder bis +`EVALUATOR_MAX_POLL_DURATION_SECS` (Standard: 1 h) abläuft. Nach Erreichen der Grenze +wird die Evaluierung als `timeout` aufgezeichnet und aus der laufenden Warteschlange entfernt. +Erhöhen Sie `EVALUATOR_MAX_POLL_DURATION_SECS`, wenn Ihr Evaluator legitim länger als den Standardwert benötigt. --- ## Nächste Schritte -- [Evaluator-Agenten-Skill](/de/agenteye/evaluator-skill): Lassen Sie einen Coding-Agenten Ihre Dimensionen anhand echter Sitzungen entwerfen und diesen Dienst für Sie erstellen. -- [Python SDK](/de/agenteye/python-sdk): Die `agent_end`-Ereignisse auslösen, die das Scoring anstoßen. +- [Evaluator-Agent-Skill](/de/agenteye/evaluator-skill): Lassen Sie einen Coding-Agenten Ihre Dimensionen anhand echter Sessions gestalten und diesen Service für Sie erstellen. +- [Python SDK](/de/agenteye/python-sdk): Die `agent_end`-Events ausgeben, die das Scoring auslösen. - [API-Schlüssel](/de/agenteye/api-keys): Die Berechtigungen `evaluations:read` und `evaluations:trigger`. -- [Audits](/de/agenteye/audits): Die andere automatisierte Qualitätsfunktion von Observability für richtlinienbasierte Überprüfungen. \ No newline at end of file +- [Audits](/de/agenteye/audits): Das andere automatisierte Qualitätsmerkmal von Observability für richtlinienbasierte Überprüfungen. \ No newline at end of file diff --git a/docs/de/agenteye/evaluations.mdx b/docs/de/agenteye/evaluations.mdx index c1b3e732..b8d0daca 100644 --- a/docs/de/agenteye/evaluations.mdx +++ b/docs/de/agenteye/evaluations.mdx @@ -1,50 +1,50 @@ --- -title: "Evaluations" -description: "Qualitätsprobleme finden Sie jetzt von selbst, anstatt erst durch eine Nutzerbeschwerde davon zu erfahren." +title: "Evaluierungen" +description: "Qualitätsprobleme fallen dir jetzt selbst auf – statt dass du erst durch eine Nutzerbeschwerde davon erfährst." --- -Qualitätsprobleme finden Sie jetzt von selbst, anstatt erst durch eine Nutzerbeschwerde davon zu erfahren. Verbinden Sie Ihren eigenen Scoring-Dienst einmalig, und Failproof AI Observability bewertet jeden abgeschlossenen Lauf automatisch – sodass ein Rückgang der Hilfsbereitschaft oder eine Häufung von Halluzinationen sichtbar wird, bevor ein Kunde es überhaupt merkt. +Qualitätsprobleme fallen dir jetzt selbst auf – statt dass du erst durch eine Nutzerbeschwerde davon erfährst. Verbinde deinen eigenen Scoring-Service einmalig, und Failproof AI Observability bewertet jeden abgeschlossenen Run automatisch. Ein Rückgang bei der Hilfsbereitschaft oder eine Häufung von Halluzinationen zeigt sich von selbst, bevor ein Kunde es spürt. -![Das Sessions-Raster mit einer Score-Spalte: Jeder Lauf trägt eine Auswertungs-Statusanzeige sowie farbcodierte Badges für Hilfsbereitschaft, Faktentreue und Tool-Effizienz](/agenteye/images/sessions-list.png) +![Das Sessions-Raster mit einer Score-Spalte: Jeder Run trägt eine Evaluierungsstatus-Pille und farblich kodierte Badges für Hilfsbereitschaft, Faktentreue und Tool-Effizienz](/agenteye/images/sessions-list.png) -*Jeder Lauf im Sessions-Raster trägt seine Bewertungen; rote, gelbe und grüne Badges machen schwache Läufe sofort erkennbar, ohne dass Sie ein einziges Transkript öffnen müssen.* +*Jeder Run im Sessions-Raster trägt seine Bewertungen; rote, gelbe und grüne Badges lassen schwache Runs sofort hervorstechen, ohne dass du auch nur ein einzelnes Transkript öffnen musst.* ## Schluss mit manuellen Stichproben -Früher haben Sie eine Handvoll Läufe stichprobenartig geprüft und gehofft, der Rest sei in Ordnung. Jetzt wird jede abgeschlossene Session in dem Moment bewertet, in dem sie endet – anhand der Dimensionen, die Ihnen wichtig sind: Hilfsbereitschaft, Tool-Effizienz, Faktentreue, Sicherheit oder was auch immer Ihr Qualitätsmaßstab ist. Sie legen die Score-Schlüssel fest; Failproof AI Observability speichert, verfolgt und zeigt alles an, was Ihr Evaluator zurücksendet. Kein Lauf bleibt unbewertet, und Sie erfahren von einem Regressionsfall nicht mehr erst über ein Support-Ticket. +Früher hast du eine Handvoll Runs stichprobenartig geprüft und gehofft, dass der Rest in Ordnung ist. Jetzt wird jede abgeschlossene Session in dem Moment bewertet, in dem sie endet – auf den Dimensionen, die dir wichtig sind: Hilfsbereitschaft, Tool-Effizienz, Faktentreue, Sicherheit – was auch immer deinen Qualitätsmaßstab ausmacht. Du definierst die Score-Schlüssel; Failproof AI Observability speichert, verfolgt und zeigt an, was dein Evaluator zurücksendet. Kein Run bleibt unbewertet, und du erfährst von einem Regressionsfall nicht mehr erst durch ein Support-Ticket. -Die Bewertungen erscheinen direkt im Sessions-Raster unter **`//sessions`** (Seitenleiste → *observe* → *sessions*), ein Badge-Cluster pro Zeile. Möchten Sie nur die Läufe sehen, die nicht die Erwartungen erfüllt haben? Filtern Sie das Raster nach Score-Bereich – etwa Hilfsbereitschaft unter 0,5 – und rufen Sie genau die Läufe auf, die es wert sind, gelesen zu werden. Zum Anzeigen von Bewertungen wird die Berechtigung `evaluations:read` benötigt. +Die Scores erscheinen im Sessions-Raster unter **`//sessions`** (Seitenleiste → *observe* → *sessions*), als Badge-Cluster pro Zeile. Willst du nur die Runs sehen, die nicht bestanden haben? Filtere das Raster nach Score-Bereich – z. B. Hilfsbereitschaft unter 0,5 – und rufe genau die Runs auf, die es wert sind, gelesen zu werden. Zum Anzeigen von Scores wird die Berechtigung `evaluations:read` benötigt. -## Verstehen, warum ein Lauf niedrig bewertet wurde +## Verstehen, warum ein Run schlecht bewertet wurde -Eine Zahl sagt Ihnen, dass ein Lauf schwach war; die Session-Seite erklärt Ihnen, warum. Öffnen Sie einen beliebigen Lauf, und die rechte Leiste beginnt mit der übergeordneten Zusammenfassung, gefolgt von einem Balken pro Dimension – jeweils mit der Begründung Ihres Evaluators darunter. So gelangen Sie in Sekunden von „factuality-Score 0,4" zu der genauen Aussage, die falsch war. +Eine Zahl sagt dir, dass ein Run schwach war; die Session-Seite erklärt dir, warum. Öffne einen beliebigen Run: Die rechte Leiste beginnt mit der zusammenfassenden Übersicht und zeigt dann pro Dimension einen Balken mit der Begründung deines Evaluators darunter. So gelangst du in Sekunden von „diese Session hat 0,4 für Faktentreue" zur genauen Aussage, die falsch war. -![Die rechte Leiste einer Session: oben die Auswertungszusammenfassung, darunter Score-Balken pro Dimension mit je einer Begründungszeile, neben der vollständigen Event-Timeline](/agenteye/images/session-detail.png) +![Die rechte Leiste einer Session: die Evaluierungszusammenfassung oben, dann Score-Balken pro Dimension mit je einer Begründungszeile, neben der vollständigen Ereignis-Timeline](/agenteye/images/session-detail.png) -*Die Session-Detailansicht: Zusammenfassung, Score-Balken pro Dimension und die Begründung hinter jedem Score – direkt neben der Event-Timeline des Laufs.* +*Die Session-Detailansicht: Zusammenfassung, Score-Balken pro Dimension und die Begründung hinter jedem Score – direkt neben der Ereignis-Timeline des Runs.* -Haben Sie einen präziseren Evaluator bereitgestellt oder schauen Sie sich einen Lauf an, der vor der Bewertung abgestürzt ist? Eine **Re-evaluate**-Schaltfläche (durch `evaluations:trigger` geschützt) bewertet die Session erneut und fügt das neue Ergebnis ihrer Timeline hinzu, sodass frühere Bewertungen als Verlauf sichtbar bleiben. Sie finden sie unter **`//sessions/`**. +Hast du einen schärferen Evaluator veröffentlicht oder schaust du dir einen Run an, der abgestürzt ist, bevor er bewertet werden konnte? Ein **Neu bewerten**-Button (erfordert `evaluations:trigger`) bewertet die Session direkt neu und hängt das frische Ergebnis an ihre Timeline an, sodass frühere Scores als Verlauf erhalten bleiben. Du findest ihn unter **`//sessions/`**. -## Qualitätstrends über die gesamte Flotte beobachten +## Qualitätstrend über die gesamte Flotte beobachten -Ein einzelner niedriger Score ist Rauschen; eine ganze Kohorte im Abwärtstrend ist ein Signal. Gespeicherte Dashboards wandeln Ihre Scores in einen Trend um, den Sie auf einen Blick verfolgen können: durchschnittliche Hilfsbereitschaft diese Woche im Vergleich zur letzten, pro Agent, pro Umgebung. +Ein einziger schlecht bewerteter Run ist Rauschen; ein ganzer Kohortendrift ist ein Signal. Gespeicherte Dashboards verwandeln deine Scores in einen Trend, den du auf einen Blick beobachten kannst: durchschnittliche Hilfsbereitschaft diese Woche im Vergleich zur letzten, pro Agent, pro Umgebung. -![Ein Qualitäts-Dashboard: durchschnittliche Score-Balken pro Evaluator-Dimension sowie ein zeitlicher Verlaufstrend](/agenteye/images/dashboard-quality.png) +![Ein Qualitäts-Dashboard: Durchschnittliche Score-Balken pro Evaluierungsdimension neben einem zeitlichen Trendverlauf](/agenteye/images/dashboard-quality.png) -*Ein gespeichertes Qualitäts-Dashboard zeigt die Trends der von Ihnen hervorgehobenen Score-Schlüssel – sodass eine langsame Verschlechterung lange vor einem Vorfall offensichtlich wird.* +*Ein gespeichertes Qualitäts-Dashboard zeigt den Trend der von dir hervorgehobenen Score-Schlüssel – ein schleichender Drift ist offensichtlich, lange bevor er zum Vorfall wird.* -Dashboards finden Sie unter **`//dashboards`** (Seitenleiste → *analyze* → *dashboards*), werden organisationsweit geteilt, und jede Karte fasst die zugehörigen Sessions zusammen: Anzahl, Durchschnitt jedes hervorgehobenen Scores und ein Trend-Sparkline. „Open in sessions" führt Sie direkt in die vorgefilterten Läufe hinter jeder Zahl. Zum Anzeigen werden `dashboards:read` und `evaluations:read` benötigt. +Dashboards befinden sich unter **`//dashboards`** (Seitenleiste → *analyze* → *dashboards*), sind für deine gesamte Organisation freigegeben, und jede Karte fasst die passenden Sessions zusammen: Anzahl, Durchschnitt jedes hervorgehobenen Scores und ein Trend-Sparkline. „In Sessions öffnen" bringt dich direkt in die vorgefilterten Runs hinter einer beliebigen Zahl. Zum Anzeigen werden `dashboards:read` und `evaluations:read` benötigt. -## Einen Evaluator einmalig verbinden +## Einmalig einen Evaluator verbinden -Die Bewertung ist optional und bleibt vollständig deaktiviert, bis Sie Failproof AI Observability auf einen Scorer verweisen. Sie richten einen kleinen HTTP-Dienst ein (Observability liefert eine funktionierende Referenzimplementierung, die Sie kopieren können), setzen zwei Werte auf Ihrem Server, und von da an wird jeder Lauf automatisch bewertet. Die vollständige Anleitung, den Scoring-Vertrag und das SDK finden Sie im ausführlichen Leitfaden. +Das Scoring ist optional und bleibt vollständig deaktiviert, bis du Failproof AI Observability auf einen Scorer verweist. Du richtest einen kleinen HTTP-Dienst ein (Observability liefert eine funktionierende Referenzimplementierung, die du kopieren kannst), setzt zwei Werte auf deinem Server, und ab dann wird jeder Run automatisch für dich bewertet. Die vollständige Anleitung, der Scoring-Vertrag und das SDK befinden sich im ausführlichen Leitfaden. -Nicht sicher, welche Dimensionen es überhaupt wert sind, bewertet zu werden? Die [Evaluator Agent Skill](/de/agenteye/evaluator-skill) lässt Ihren Coding-Agenten das anhand Ihrer eigenen Sessions herausarbeiten und den Dienst anschließend erstellen und bereitstellen. +Unsicher, welche Dimensionen überhaupt des Scorens wert sind? Der [Evaluator-Agent-Skill](/de/agenteye/evaluator-skill) lässt deinen Coding-Agent das anhand deiner eigenen Sessions herausarbeiten und dann den Service aufbauen und deployen. ## Verwandte Themen -- [Evaluation Suite](/de/agenteye/evaluation-suite): Verbinden Sie Ihren Evaluator, den Scoring-Vertrag und das SDK. -- [Evaluator Agent Skill](/de/agenteye/evaluator-skill): Lassen Sie einen Coding-Agenten Ihre Score-Dimensionen auswählen und den Evaluator erstellen. -- [Sessions](/de/agenteye/sessions): Das laufbezogene Raster, in dem Scores erscheinen. -- [Dashboards](/de/agenteye/dashboards): Qualitätstrends speichern und organisationsweit teilen. -- [Audits](/de/agenteye/audits): Das andere automatische Qualitätsmerkmal von Observability, für sessionübergreifende Untersuchungen. \ No newline at end of file +- [Evaluation Suite](/de/agenteye/evaluation-suite): Evaluator verbinden, Scoring-Vertrag und SDK. +- [Evaluator-Agent-Skill](/de/agenteye/evaluator-skill): Lass einen Coding-Agent deine Score-Dimensionen auswählen und den Evaluator erstellen. +- [Sessions](/de/agenteye/sessions): Das Run-für-Run-Raster, in dem Scores erscheinen. +- [Dashboards](/de/agenteye/dashboards): Qualitätstrends in deiner Organisation speichern und teilen. +- [Audits](/de/agenteye/audits): Das andere automatische Qualitätsmerkmal von Observability, für sitzungsübergreifende Untersuchungen. \ No newline at end of file diff --git a/docs/de/agenteye/evaluator-skill.mdx b/docs/de/agenteye/evaluator-skill.mdx index ccccd307..c3036f9d 100644 --- a/docs/de/agenteye/evaluator-skill.mdx +++ b/docs/de/agenteye/evaluator-skill.mdx @@ -1,22 +1,22 @@ --- title: "Failproof AI Observability Evaluator Agent Skill" -description: "Von »Ich glaube, unser Agent ist manchmal schlecht« zu einem produktiven Scoring-Service – während dein Coding-Agent sowohl die Konzeption als auch die Umsetzung übernimmt." +description: "Von \"Ich glaube, unser Agent ist manchmal schlecht\" zu einem bereitgestellten Scoring-Service – wobei Ihr Coding-Agent sowohl die Entscheidungen trifft als auch den Aufbau übernimmt." --- -Von *„Ich glaube, unser Agent ist manchmal schlecht"* zu einem produktiven Scoring-Service – während dein Coding-Agent sowohl die Konzeption als auch die Umsetzung übernimmt. Der **Failproof AI Observability Evaluator Skill** (`agenteye-evaluator`) ist ein *Agent Skill*: ein kleines Verzeichnis mit Anweisungen, das ein Coding-Agent wie Claude Code oder Codex bei Bedarf lädt. Er bringt dem Agenten bei, herauszufinden, welche Qualitätsdimensionen es für *deinen* Agenten zu verfolgen lohnt, und dann den [Evaluator-Service](/de/agenteye/evaluation-suite) zu schreiben, zu testen und zu deployen, der sie bewertet. +Von *„Ich glaube, unser Agent ist manchmal schlecht"* zu einem bereitgestellten Scoring-Service – wobei Ihr Coding-Agent sowohl die Entscheidungen trifft als auch den Aufbau übernimmt. Der **Failproof AI Observability Evaluator Skill** (`agenteye-evaluator`) ist ein *Agent Skill*: ein kleiner Ordner mit Anweisungen, den ein Coding-Agent wie Claude Code oder Codex bei Bedarf lädt. Er bringt dem Agenten bei, herauszufinden, welche Qualitätsdimensionen es für *Ihren* Agenten wert sind, verfolgt zu werden, und dann den [Evaluator-Service](/de/agenteye/evaluation-suite), der sie bewertet, zu schreiben, zu testen und bereitzustellen. -Es handelt sich **nicht** um einen gehosteten Scorer, eine Registry zum Hochladen oder ein Plugin-System. Dein Evaluator bleibt dein eigener HTTP-Service auf deiner eigenen Infrastruktur, genau wie im [Evaluation suite](/de/agenteye/evaluation-suite)-Leitfaden beschrieben. Der Skill lehrt deinen Agenten nur, ihn gut zu bauen – alles, was er tut, könntest du selbst tun, indem du denselben Code schreibst. +Es handelt sich **nicht** um einen gehosteten Scorer, eine Registry, in die Sie hochladen, oder ein Plugin-System. Ihr Evaluator bleibt Ihr eigener HTTP-Service auf Ihrer eigenen Infrastruktur, genau wie im Leitfaden zur [Evaluation Suite](/de/agenteye/evaluation-suite) beschrieben. Der Skill bringt Ihrem Agenten lediglich bei, ihn gut zu bauen – alles, was er tut, könnten Sie selbst tun, indem Sie denselben Code schreiben. --- ## Das Schwierige ist zu entscheiden, was bewertet werden soll -Die SDK-Oberfläche ist klein – ein Decorator und zwei Modelle – und ein Agent kann das allein aus dem [Contract](/de/agenteye/evaluation-suite#http-contract) herleiten. Daran scheitern Evaluatoren nicht. Sie scheitern daran, dass sie das Falsche bewerten, und ein Evaluator, der das Falsche bewertet, ist schlimmer als keiner: Er produziert ein Dashboard, das alle lernen zu ignorieren. +Die SDK-Oberfläche ist klein – ein Decorator und zwei Modelle – und ein Agent kann das allein aus dem [Vertrag](/de/agenteye/evaluation-suite#http-contract) herleiten. Daran scheitern Evaluatoren nicht. Sie scheitern, weil sie das Falsche bewerten, und ein Evaluator, der das Falsche bewertet, ist schlimmer als keiner: Er produziert ein Dashboard, das alle lernen zu ignorieren. -Deshalb liegt der Schwerpunkt des Skills auf dem Teil, bevor überhaupt Code entsteht. Der Agent interviewt dich (*„Beschreib einen Lauf, der gut war; jetzt einen, der schlecht war"*), zieht dann deine echten Sessions durch die [`agenteye` CLI](/de/agenteye/cli) und liest sie von Anfang bis Ende. Diese beiden Hälften widersprechen sich meistens, und genau das ist der Punkt: was du zu messen beabsichtigst versus was deine Transcripts tatsächlich hergeben. Eine Dimension überlebt nur, wenn sie aus den Events **berechenbar** und **diskriminierend** ist – wenn sie sowohl für deinen guten als auch für deinen schlechten Lauf 0,9 ergibt, lehrt sie nichts und wird gestrichen. +Der Großteil des Skills befasst sich daher mit dem Teil, bevor irgendein Code existiert. Er lässt den Agenten Sie interviewen (*„Beschreiben Sie einen Ablauf, der gut lief; jetzt einen, der schlecht lief"*), zieht dann Ihre echten Sessions über die [`agenteye`-CLI](/de/agenteye/cli) und liest sie von Anfang bis Ende. Diese beiden Hälften sind meist uneinig, und die Lücke ist der entscheidende Punkt: was Sie zu messen beabsichtigen gegenüber dem, was Ihre Transkripte tatsächlich unterstützen können. Eine Dimension überlebt nur, wenn sie aus den Ereignissen **berechenbar** und **diskriminierend** ist – wenn sie bei Ihrem guten und schlechten Ablauf jeweils 0,9 ergibt, lehrt sie nichts und wird gestrichen. -Das Ergebnis ist ein Vorschlag von 2–4 Dimensionen mit der zugehörigen Begründung, dem du zustimmen musst, bevor eine Zeile Code geschrieben wird. +Das Ergebnis ist ein Vorschlag von 2-4 Dimensionen mit der dazugehörigen Begründung, dem Sie zustimmen müssen, bevor eine einzige Zeile geschrieben wird. ```mermaid flowchart TD @@ -30,46 +30,46 @@ flowchart TD --- -## Beziehung zu den anderen Evaluation-Komponenten +## Wie es sich zu den anderen Evaluierungs-Komponenten verhält -Vier Docs behandeln das Scoring und gehen in dieser Reihenfolge ineinander über: +Vier Dokumente behandeln das Scoring und übergeben in dieser Reihenfolge aneinander: -| Seite | Was es ist | Verwende es, wenn | +| Seite | Was es ist | Verwenden Sie es, wenn | |---|---|---| -| **[Evaluations](/de/agenteye/evaluations)** | Das Feature: Scores im Sessions-Grid, Dashboards, Re-evaluate | Du wissen möchtest, was automatisches Scoring dir bringt | -| **[Evaluation suite](/de/agenteye/evaluation-suite)** | Der HTTP-Contract, das SDK, die Server-Umgebungsvariablen | Du den Evaluator selbst implementierst oder debuggst | -| **Evaluator Skill** (dieses Dokument) | Ein sprachbasierter Einstieg in das Designen *und* Bauen des Scorers | Du von „Ich will Evals" zu einem laufenden Service kommen möchtest | -| **[CLI skill](/de/agenteye/cli-skill)** | Ein sprachbasierter Einstieg in die `agenteye` CLI | Du die bereits vorhandenen Scores *lesen* möchtest | -| **[Python SDK skill](/de/agenteye/python-sdk-skill)** | Ein sprachbasierter Einstieg in die Instrumentierung deines Agenten | Dein Agent noch keine Sessions emittiert – es gibt noch nichts zu bewerten | +| **[Evaluations](/de/agenteye/evaluations)** | Das Feature: Scores im Sessions-Raster, Dashboards, erneute Auswertung | Sie wissen möchten, was automatisches Scoring Ihnen bringt | +| **[Evaluation Suite](/de/agenteye/evaluation-suite)** | Der HTTP-Vertrag, das SDK, die Server-Umgebungsvariablen | Sie den Evaluator selbst implementieren oder debuggen | +| **Evaluator Skill** (dieses Dokument) | Eine natürlichsprachige Eingangstür zum Entwerfen *und* Aufbauen des Scorers | Sie von „Ich möchte Evals" zu einem laufenden Service gelangen möchten | +| **[CLI Skill](/de/agenteye/cli-skill)** | Eine natürlichsprachige Eingangstür zur `agenteye`-CLI | Sie die bereits vorhandenen Scores *lesen* möchten | +| **[Python SDK Skill](/de/agenteye/python-sdk-skill)** | Eine natürlichsprachige Eingangstür zur Instrumentierung Ihres Agenten | Ihr Agent noch keine Sessions ausgibt – es gibt nichts zu bewerten | -### vs. CLI Skill: Bauen versus Lesen +### vs. der CLI Skill: Bauen versus Lesen -Die beiden Skills überschneiden sich bewusst nicht, und beide zu installieren ist der Normalfall – der Agent wählt je nach Anfrage zwischen ihnen: +Die beiden Skills überschneiden sich bewusst nicht, und beide zu installieren ist die übliche Konfiguration – der Agent wählt zwischen ihnen basierend darauf, was Sie fragen: -- **`agenteye-evaluator`** (dieses Dokument) baut das, was Scores *erzeugt*. Seine Aufgabe endet, wenn Scores zum ersten Mal eintreffen. +- **`agenteye-evaluator`** (dieses Dokument) baut das Ding, das Scores *produziert*. Seine Aufgabe endet, wenn Scores zum ersten Mal eintreffen. - **[`agenteye-cli`](/de/agenteye/cli-skill)** liest bereits vorhandene Scores (`agenteye evals`). *„Hat die Qualität diese Woche nachgelassen?"* ist seine Frage, nicht die dieses Skills. --- ## Voraussetzungen -1. **Die `agenteye` CLI installiert und eingeloggt** (`pipx install agenteye`, dann `agenteye login`). Der Skill nutzt sie an zwei Stellen: um die echten Sessions zu holen, gegen die er designed, und um am Ende zu bestätigen, dass deine Scores angekommen sind. Dein Login benötigt `events:read`, sowie `evaluations:read` für die abschließende Prüfung. Wie beim CLI Skill kann er das per E-Mail zugesandte Einmal-Code-Login **nicht** für dich abschließen. -2. **Einen Ort für den Evaluator.** Er wird in ein Image gebaut und als langlebiger Service betrieben, benötigt also ein echtes Repo, keine temporäre Datei. Evaluatoren leben oft in einem eigenen Repo, getrennt vom bewerteten Agenten – der Skill sucht nach einem vorhandenen und fragt, bevor er ein neues anlegt. -3. **Das `agenteye-evaluator` SDK Wheel** – lies den nächsten Abschnitt, bevor dein Agent `pip`-Befehle einzutippen beginnt. +1. Die **`agenteye`-CLI installiert und eingeloggt** (`pipx install agenteye`, dann `agenteye login`). Der Skill nutzt sie zweimal: zum Abrufen der echten Sessions, gegen die er entwirft, und zum Bestätigen, dass Ihre Scores am Ende angekommen sind. Ihr Login benötigt `events:read`, plus `evaluations:read` für diese abschließende Überprüfung. Wie beim CLI Skill kann er den per E-Mail versandten Einmalcode-Login **nicht** für Sie abschließen. +2. **Einen Ort für den Evaluator.** Er wird in ein Image gebaut und als dauerhaft laufender Service betrieben, benötigt also ein echtes Repo, keine temporäre Datei. Evaluatoren befinden sich oft in einem eigenen Repo, getrennt vom bewerteten Agenten – der Skill sucht nach einem vorhandenen und fragt, bevor er ein neues anlegt. +3. **Das `agenteye-evaluator`-SDK-Wheel** – lesen Sie den nächsten Abschnitt, bevor Ihr Agent beginnt, `pip`-Befehle einzutippen. --- -## Bezugsquelle +## Wo man es bekommt Der Skill ist in Failproof AI's öffentlicher Skills-Sammlung veröffentlicht: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -Das Repository ist öffentlich und der Skill benötigt keine eigenen Zugangsdaten – er steuert nur die `agenteye` CLI mit dem Session, mit dem *du* eingeloggt bist, und schreibt Code in *dein* Repo. Beachte, dass er als eigenes Verzeichnis ausgeliefert wird und **nicht** im `pipx install agenteye`-Paket enthalten ist – such ihn dort also nicht. +Das Repository ist öffentlich und der Skill benötigt keine eigenen Zugangsdaten – er steuert nur die `agenteye`-CLI mit der Session, mit der *Sie* eingeloggt sind, und schreibt Code in *Ihr* Repo. Beachten Sie, dass er als eigener Ordner ausgeliefert wird und **nicht** im `pipx install agenteye`-Paket enthalten ist – suchen Sie also nicht dort danach. ## Den Skill installieren -Der schnellste Weg ist die [`skills`](https://skills.sh) CLI, die das Verzeichnis abruft und dort ablegt, wo dein Agent sucht: +Der schnellste Weg ist die [`skills`](https://skills.sh)-CLI, die den Ordner abruft und ihn dort ablegt, wo Ihr Agent sucht: ```bash # Claude Code, nur dieses Projekt @@ -78,11 +78,11 @@ npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code # jedes Projekt (installiert nach ~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy -# stattdessen Codex +# Stattdessen Codex npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -Anschließend verwaltest du ihn wie jeden anderen Skill: +Dann verwalten Sie ihn wie jeden anderen Skill: ```bash npx skills list -a claude-code # was installiert ist @@ -90,28 +90,28 @@ npx skills update agenteye-evaluator # neueste Version holen npx skills remove agenteye-evaluator # entfernen ``` -Bevorzugst du manuelle Installation? Ein Agent Skill ist nur ein Verzeichnis mit einer `SKILL.md` (plus optionalen Referenzen), das Kopieren funktioniert also ebenfalls: +Lieber manuell installieren? Ein Agent Skill ist nur ein Ordner mit einer `SKILL.md` (plus optionalen Referenzen), daher funktioniert auch Kopieren: -- **Claude Code**: Lege das `agenteye-evaluator/`-Verzeichnis in `~/.claude/skills/` (jedes Projekt) oder `/.claude/skills/` (nur dieses Repo). Claude Code erkennt es automatisch – prüfe mit der `/skills`-Liste oder frage einfach nach Evals. -- **Codex (OpenAI)**: Codex liest dieselbe `SKILL.md`. Die mitgelieferte `agents/openai.yaml` setzt `allow_implicit_invocation: true`, sodass Codex den Skill automatisch auswählt, wenn eine Aufgabe passt; andernfalls rufst du ihn explizit als `$agenteye-evaluator` auf. +- **Claude Code**: Legen Sie den Ordner `agenteye-evaluator/` in `~/.claude/skills/` (jedes Projekt) oder `/.claude/skills/` (nur dieses Repo). Claude Code erkennt ihn automatisch – überprüfen Sie dies mit der `/skills`-Liste oder fragen Sie einfach nach Evals. +- **Codex (OpenAI)**: Codex liest dieselbe `SKILL.md`. Das mitgelieferte `agents/openai.yaml` setzt `allow_implicit_invocation: true`, sodass Codex den Skill automatisch auswählt, wenn eine Aufgabe passt; andernfalls rufen Sie ihn explizit als `$agenteye-evaluator` auf. --- ## Das SDK ist nicht auf dem öffentlichen PyPI -> **Warnung:** Lies dies, bevor du einen Agenten das SDK installieren lässt. +> **Warnung:** Lesen Sie dies, bevor Sie einen Agenten das SDK installieren lassen. -Der Skill ist öffentlich; das SDK, das er verwendet, ist es nicht. `agenteye-evaluator` wird nur als privates Release-Artefakt ausgeliefert, und anders als `agenteye` ist der Name auf dem öffentlichen PyPI **nicht beansprucht** – ein blankes `pip install agenteye-evaluator` könnte also das Paket eines Fremden in den Service ziehen, der deine Produktions-Transcripts liest. Das ist ein Supply-Chain-Problem, kein Tippfehler. +Der Skill ist öffentlich; das SDK, das er verwendet, ist es nicht. `agenteye-evaluator` wird nur als privates Release-Artefakt ausgeliefert, und im Gegensatz zu `agenteye` ist der Name auf dem öffentlichen PyPI **nicht beansprucht** – ein bloßes `pip install agenteye-evaluator` könnte also ein fremdes Paket in den Service ziehen, der Ihre Produktionstranskripte liest. Das ist ein Supply-Chain-Problem, kein Tippfehler. -Der Skill weiß das und arbeitet stattdessen eine Installations-Leiter ab, die beim ersten zutreffenden Schritt stoppt: die Monorepo-Quelle, wenn du im AgentEye-Repo bist, sonst das private Release-Wheel von GitHub Releases (erfordert Zugriff), und wenn keines davon erreichbar ist, **stoppt er und teilt dir mit, deinen Failproof AI-Kontakt nach dem Wheel zu fragen**, anstatt zu improvisieren. +Der Skill weiß das und arbeitet stattdessen eine Installationsleiter hinunter, wobei er bei der ersten zutreffenden Stufe stoppt: die Monorepo-Quelle, wenn Sie sich im AgentEye-Repo befinden, andernfalls das private Release-Wheel von GitHub Releases (benötigt Zugang), und wenn keines erreichbar ist, **stoppt er und fordert Sie auf, Ihren Failproof AI-Kontakt nach dem Wheel zu fragen**, anstatt zu improvisieren. -Wenn dein Agent also ein blankes `pip install agenteye-evaluator` von Public PyPI vorschlägt, ist das das Zeichen, dass der Skill nie geladen wurde. Halte dort an und prüfe, ob er installiert ist. +Wenn Ihr Agent also ein bloßes `pip install agenteye-evaluator` aus dem öffentlichen PyPI vorschlägt, ist das das Zeichen, dass der Skill nie geladen wurde. Halten Sie dort inne und prüfen Sie, ob er installiert ist. --- -## Was du ihn fragen kannst +## Was Sie fragen können -Ein echter Durchlauf beginnt mit einer vagen Anfrage und endet mit einem abgezeichneten Design, nicht mit Code: +Ein echter Durchlauf beginnt mit einer vagen Anfrage und endet mit einem abgesegneten Entwurf, nicht mit Code: ```text you ▸ I want evals for our support bot. I think it's sometimes bad. @@ -145,23 +145,23 @@ agent ▸ No evaluator in this repo. Should I scaffold one here, or do you have one elsewhere? ``` -Anschließend schreibt er die regelbasierten Dimensionen zuerst (kostenlos, sofort, deterministisch), testet sie gegen eine echte erfasste Session – einschließlich der leeren und nie abgeschlossenen Sessions, die naive Evaluatoren zum Absturz bringen – und greift nur für die subjektive Dimension auf einen LLM-Judge zurück. Er kennt die [Grenzen des Dispatchers](/de/agenteye/evaluation-suite#configuring-the-server) – ein 30-Sekunden-Request-Timeout und 8 gleichzeitige Calls deployment-weit – wenn der Judge nicht zuverlässig hineinpasst, geht er daher asynchron mit `JobPending` vor, anstatt zuzulassen, dass dein Judge fünfmal abgebrochen und mit fünffachen Kosten neu versucht wird. +Von dort schreibt er die regelbasierten Dimensionen zuerst (kostenlos, sofort, deterministisch), testet sie gegen eine echte aufgezeichnete Session – einschließlich der leeren und nie abgeschlossenen, die naive Evaluatoren zum Absturz bringen –, und greift nur bei der subjektiven Dimension auf einen LLM-Richter zurück. Er kennt die [Grenzen des Dispatchers](/de/agenteye/evaluation-suite#configuring-the-server) – ein 30-Sekunden-Request-Timeout und 8 gleichzeitige Aufrufe systemweit –, sodass er bei einem Richter, der nicht zuverlässig hineinpasst, asynchron mit `JobPending` vorgeht, anstatt zuzulassen, dass Ihr Richter fünfmal abgebrochen und fünfmal so teuer wiederholt wird. -Dann deployt er, setzt die beiden Server-Umgebungsvariablen und bestätigt mit `agenteye --json evals --session-id `, dass Scores tatsächlich angekommen sind. Das Ankommen der Scores ist der einzige Beweis. +Dann stellt er bereit, setzt die zwei Server-Umgebungsvariablen und bestätigt mit `agenteye --json evals --session-id `, dass Scores tatsächlich angekommen sind. Das Ankommen der Scores ist der einzige Beweis. --- -## Worauf du achten solltest +## Worauf Sie achten sollten -- **Dimensionsnamen sind nahezu dauerhaft.** Score-Keys sind beliebige Strings, und die Plattform verfolgt Trends für alles, was du sendest – das bedeutet, nichts downstream korrigiert eine schlechte Wahl. Benennst du sie später um, teilt sich die Historie: Alte Sessions behalten den alten Key und der Trend bricht ab. Deshalb holt sich der Skill explizite Zustimmung, bevor er Code schreibt – nimm diese Aufforderung ernst. -- **Fixtures sind echte Produktions-Transcripts.** Das Design gegen echte Sessions bedeutet, sie auf die Festplatte zu holen, und sie können Kundendaten enthalten. Der Skill fragt, bevor er sie in Git committet; im Zweifelsfall halte `fixtures/` aus dem Repo heraus und lass jeden Entwickler seine eigenen holen. -- **Der Agent schreibt und deployt einen Service, der jeden Transcript liest.** Er handelt als du, gebunden durch die Berechtigungen deines CLI-Logins, aber überprüfe den Evaluator wie jeden anderen Code, der Produktionsdaten berührt. +- **Dimensionsnamen sind nahezu dauerhaft.** Score-Keys sind beliebige Zeichenketten und die Plattform erstellt Trends aus allem, was Sie senden – das bedeutet, nichts stromabwärts korrigiert eine schlechte Wahl. Benennen Sie später um und die Geschichte teilt sich: Alte Sessions behalten den alten Key und der Trend bricht ab. Deshalb holt der Skill ausdrückliche Zustimmung ein, bevor Code geschrieben wird – nehmen Sie diese Aufforderung ernst. +- **Fixtures sind echte Produktionstranskripte.** Das Entwerfen gegen echte Sessions bedeutet, sie auf die Festplatte zu ziehen, und sie können Kundendaten enthalten. Der Skill fragt, bevor er sie in Git einschreibt; im Zweifelsfall halten Sie `fixtures/` aus dem Repo heraus und lassen Sie jeden Entwickler seine eigenen abrufen. +- **Der Agent schreibt und betreibt einen Service, der jedes Transkript liest.** Er handelt als Sie, begrenzt durch die Berechtigungen Ihres CLI-Logins, aber überprüfen Sie den Evaluator wie jeden anderen Code, der Produktionsdaten berührt. --- ## Nächste Schritte -- **[Evaluation suite](/de/agenteye/evaluation-suite)**: der HTTP-Contract, das SDK und die Server-Umgebungsvariablen, die der Skill konfiguriert. +- **[Evaluation Suite](/de/agenteye/evaluation-suite)**: der HTTP-Vertrag, das SDK und die Server-Umgebungsvariablen, die der Skill konfiguriert. - **[Evaluations](/de/agenteye/evaluations)**: wo die Scores erscheinen, sobald sie ankommen. -- **[CLI skill](/de/agenteye/cli-skill)**: der Schwester-Skill, zum Lesen von Ergebnissen statt zum Bauen des Scorers. -- **[CLI](/de/agenteye/cli)**: die Befehlsreferenz hinter den Session-Daten, gegen die der Skill designed. \ No newline at end of file +- **[CLI Skill](/de/agenteye/cli-skill)**: der Geschwister-Skill, zum Lesen von Ergebnissen statt zum Aufbauen des Scorers. +- **[CLI](/de/agenteye/cli)**: die Befehlsreferenz hinter den Session-Daten, gegen die der Skill entwirft. \ No newline at end of file diff --git a/docs/de/agenteye/event-stream.mdx b/docs/de/agenteye/event-stream.mdx index 8bf38095..f9dd9bbd 100644 --- a/docs/de/agenteye/event-stream.mdx +++ b/docs/de/agenteye/event-stream.mdx @@ -4,47 +4,47 @@ description: "In dem Moment, in dem dein Agent etwas tut, siehst du es." --- -In dem Moment, in dem dein Agent etwas tut, siehst du es. Der Event Stream ist dein Live-Puls auf jeden Agenten in der Produktion: kein Warten, kein Durchsuchen von Logs, kein Rätselraten, was gerade passiert ist. +In dem Moment, in dem dein Agent etwas tut, siehst du es. Der Event Stream ist dein Live-Puls auf jeden Agenten in der Produktion: kein Warten, kein Durchsuchen von Logs, kein Rätseln über das, was gerade passiert ist. -![Der Live-Event-Stream: farblich kodierte Event-Zeilen, die in Echtzeit eingehen, filterbar nach Umgebung, Agent, Session, Event-Typ und Freitext](/agenteye/images/events-stream.png) +![Der Live-Event-Stream: farbcodierte Event-Zeilen, die in Echtzeit eintreffen, filterbar nach Umgebung, Agent, Session, Eventtyp und Freitext](/agenteye/images/events-stream.png) -*Jedes Event von jedem Agenten in deiner Organisation, neueste zuerst, aktualisiert sich in Echtzeit.* +*Jedes Event von jedem Agenten in deiner Organisation, neueste zuerst, aktualisiert sich während es passiert.* ## Dein Live-Puls auf jeden Agenten -Wenn ein Agent einen Lauf startet, ein Modell aufruft, ein Tool auslöst, einen Hook ausführt oder auf einen Fehler stößt, erscheint die Zeile im selben Moment oben im Stream. Er verfolgt jeden Event über alle Agenten deiner Organisation hinweg, neueste zuerst – so hast du immer ein aktuelles Bild statt eines veralteten. +Wenn ein Agent einen Lauf startet, ein Modell aufruft, ein Tool ausführt, einen Hook startet oder auf einen Fehler stößt, erscheint die Zeile in dem Moment an der Spitze des Streams. Er verfolgt jedes Event über alle Agenten in deiner Organisation hinweg, neueste zuerst – damit du immer ein aktuelles Bild hast statt eines veralteten. -Das bedeutet: kein Nachlesen von Log-Dateien auf irgendeinem Server, kein Durchsuchen mehrerer Maschinen, kein mühsames Zusammensetzen von Zeitstempeln. Du öffnest eine einzige Seite und schaust bereits in die Produktion. +Das bedeutet: kein Mitverfolgen von Log-Dateien auf irgendeinem Server, kein Durchsuchen über mehrere Maschinen, kein manuelles Zusammensetzen von Zeitstempeln. Du öffnest eine Seite und beobachtest bereits die Produktion. -Zeilen sind nach Typ farblich kodiert, damit du den Stream auf einen Blick erfassen kannst, ohne jede Zeile einzeln zu lesen. Auf einen Blick zeigt dir jede Zeile: +Zeilen sind nach Typ farbcodiert, damit du den Stream auf einen Blick lesen kannst, ohne jede Zeile zu analysieren. Auf einen Blick zeigt dir jede Zeile: -- **Ihren Typ**, farblich kodiert: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` und mehr. -- **Eine einzeilige Zusammenfassung** des Geschehens, sodass du selten etwas öffnen musst, nur um den Kern zu verstehen. -- **Token-Anzahlen** für den jeweiligen Schritt. -- **Ein Context-Window-Füllstand-Badge**, wo es relevant ist, damit Prompt-Wachstum und ein sich näherndes Compaction sichtbar werden, bevor sie zum Problem werden. +- **Den Typ**, farbcodiert: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` und mehr. +- **Eine einzeilige Zusammenfassung** des Geschehens, sodass du selten etwas öffnen musst, um den Kern zu verstehen. +- **Token-Anzahlen** für den Schritt. +- **Ein Kontextfenster-Füllstandsabzeichen** wo zutreffend, damit Prompt-Wachstum und eine bevorstehende Komprimierung sichtbar sind, bevor sie zum Problem werden. -Live dabei zu sein bedeutet, dass du einen schlechten Deploy, eine unkontrollierte Schleife oder eine Fehlerhäufung in dem Moment bemerkst, in dem sie passiert – nicht erst bei der Überprüfung der Logs am nächsten Tag. +Das Live-Beobachten bedeutet, dass du ein fehlerhaftes Deployment, eine Endlosschleife oder eine Fehlerhäufung in dem Moment bemerkst, in dem es passiert – nicht bei der Log-Auswertung am nächsten Tag. ## Den einen Lauf finden, der zählt -Wenn etwas nicht stimmt, willst du keinen Datenstrom. Du willst den einen Lauf, der das Problem verursacht hat. Der Stream lässt sich schnell filtern: nach Umgebung, Agent, Session, Event-Typ oder Freitext. +Wenn etwas nicht stimmt, willst du nicht den Datenstrom ungefiltert. Du willst den einen Lauf, der fehlgeschlagen ist. Der Stream lässt sich schnell filtern: nach Umgebung, nach Agent, nach Session, nach Eventtyp oder per Freitext. -Filtere nach Session-ID oder Agenten-ID, um einen Lauf von seinem ersten bis zu seinem letzten Event zu verfolgen. Filtere nach Event-Typ, um eine einzelne Aktivitätskategorie zu isolieren – zum Beispiel alle `error`-Events in der gesamten Organisation in einer Ansicht. Kombiniere Filter, um von „alles, überall" zu „dieser Agent, in Produktion, mit Fehlern" in wenigen Klicks zu gelangen, und handle auf Basis dessen, was du findest. +Filtere nach Session-ID oder Agent-ID, um einen Lauf von seinem ersten bis zum letzten Event zu verfolgen. Filtere nach Eventtyp, um eine einzelne Aktivitätsart zu isolieren – zum Beispiel jeden `error` in der gesamten Organisation in einer Ansicht. Kombiniere Filter, um von „alles, überall" zu „dieser Agent, in Produktion, mit Fehlern" in wenigen Klicks zu gelangen, und handle dann entsprechend. -Die Freitextsuche führt dich direkt zu einer Nachricht, einem Tool-Namen oder einer ID, die du bereits zur Hand hast – so wird ein Kundenbericht in Sekunden zum exakten Lauf. +Die Freitext-Suche führt direkt zu einer Nachricht, einem Tool-Namen oder einer ID, die du bereits zur Hand hast – so wird ein Kundenbericht in Sekunden zum exakten Lauf. -## Wo du ihn findest +## Wo du es findest -Der Event Stream ist die Startseite deiner Organisation. Melde dich an, und er ist die erste Ansicht, die du siehst, unter `//` – die Triage beginnt also in dem Moment, in dem du ankommst. +Der Event Stream ist deine Organisations-Startseite. Melde dich an und es ist die erste Oberfläche, auf der du landest, unter `//` – damit beginnt die Triage in dem Moment, in dem du ankommst. -Im Hintergrund senden deine Agenten Events über das SDK, der Collector leitet sie an deinen Failproof AI Observability-Server weiter, und der Stream verfolgt sie, sobald sie in deiner kontrollierten Infrastruktur ankommen. Wenn du statt des rohen Trails die Gesamtübersicht möchtest, kollabieren die Events eines Laufs auf Sessions zu einer einzelnen Zeile – einen Klick entfernt. +Im Hintergrund senden deine Agenten Events über das SDK, der Collector leitet sie an deinen Failproof AI Observability-Server weiter, und der Stream verfolgt sie, während sie in der von dir kontrollierten Infrastruktur ankommen. Wenn du statt der rohen Spur die zusammengefasste Ansicht möchtest, werden die Events jedes Laufs auf Sessions in einer einzelnen Zeile zusammengefasst – einen Klick entfernt. -Dies ist die rohe Quelle der Wahrheit, auf der jede andere Observability-Ansicht aufbaut. Wenn eine Zahl anderswo falsch aussieht, ist der Stream der Ort, an dem du bestätigst, was tatsächlich passiert ist. +Dies ist die rohe Wahrheitsquelle, auf der jede andere Beobachtungsoberfläche aufbaut. Wenn also anderswo eine Zahl falsch aussieht, ist der Stream der Ort, an dem du bestätigst, was tatsächlich passiert ist. ## Verwandte Themen -- [Sessions](/de/agenteye/sessions): dieselben Events zusammengefasst zu einer Zeile pro Lauf, mit einem Git-artigen Ausführungsgraphen. +- [Sessions](/de/agenteye/sessions): dieselben Events zusammengefasst in einer Zeile pro Lauf, mit einem git-ähnlichen Ausführungsgraphen. - [Telemetry](/de/agenteye/telemetry): was deine Agenten senden und wie Events den Stream erreichen. -- [Error tracking](/de/agenteye/error-tracking): eine einzige Triage-Ansicht für alles, was schiefgelaufen ist. +- [Error tracking](/de/agenteye/error-tracking): eine einzige Triage-Oberfläche für alles, was schiefgelaufen ist. - [Alerts](/de/agenteye/alerts): wandle jeden Schwellenwert in eine Benachrichtigungsregel um. - [CLI and agents](/de/agenteye/cli-and-agents): derselbe Live-Trail aus deinem Terminal. \ No newline at end of file diff --git a/docs/de/agenteye/hermes-capture.mdx b/docs/de/agenteye/hermes-capture.mdx index 33d785fa..20b76d72 100644 --- a/docs/de/agenteye/hermes-capture.mdx +++ b/docs/de/agenteye/hermes-capture.mdx @@ -1,21 +1,21 @@ --- -title: "Hermes-Sitzungsaufzeichnung" -description: "Bringen Sie die Hermes-Gateway-Sitzungen Ihres Teams — Slack, Telegram, CLI und geplante Ausführungen — als gewöhnliche Sitzungen und Ereignisse in AgentEye ein." +title: "Hermes Session-Aufzeichnung" +description: "Bringen Sie die Hermes-Gateway-Sitzungen Ihres Teams – Slack, Telegram, CLI und geplante Läufe – als gewöhnliche Sitzungen und Ereignisse in AgentEye." --- -[Hermes](https://hermes-agent.nousresearch.com) beantwortet die Anfragen Ihres Teams von überall, wo es bereits arbeitet — Slack, Telegram, der CLI, geplante Ausführungen. Die Hermes-Sitzungsaufzeichnung bringt all das als gewöhnliche Sitzungen und Ereignisse in AgentEye ein, sodass der Assistent, mit dem Ihr Team täglich spricht, genauso beobachtbar ist wie die Agenten, die Sie selbst schreiben. +[Hermes](https://hermes-agent.nousresearch.com) antwortet Ihrem Team von überall, wo es bereits arbeitet – Slack, Telegram, der CLI, geplante Läufe. Die Hermes Session-Aufzeichnung bringt all das als gewöhnliche Sitzungen und Ereignisse in AgentEye, sodass der Assistent, mit dem Ihr Team täglich spricht, genauso beobachtbar ist wie die Agenten, die Sie selbst schreiben. -Ein kleiner Hintergrund-Collector liest Hermes' lokalen Sitzungsspeicher, während dieser beschrieben wird, und überträgt die Sitzungen an AgentEye. Er funktioniert genauso wie die Aufzeichnung bei [Codex](/de/agenteye/codex-capture) und [OpenClaw](/de/agenteye/openclaw-capture), und ein einzelner Collector kann mehrere davon gleichzeitig aufzeichnen. +Ein kleiner Hintergrund-Collector liest Hermes' lokalen Sitzungsspeicher, während er beschrieben wird, und sendet Sitzungen an AgentEye. Es funktioniert genauso wie die Aufzeichnung für [Codex](/de/agenteye/codex-capture) und [OpenClaw](/de/agenteye/openclaw-capture), und ein einzelner Collector kann mehrere gleichzeitig aufzeichnen. --- ## Was aufgezeichnet wird -Jede Hermes-Sitzung auf dem Rechner wird aufgezeichnet, unabhängig davon, über welchen Kanal sie zustande kam. Jede einzelne wird zu einer AgentEye-[Sitzung](/de/agenteye/sessions); ihre Benutzer- und Assistentennachrichten, Tool-Aufrufe und Tool-Ergebnisse werden zu den entsprechenden [Ereignissen](/de/agenteye/event-stream). +Jede Hermes-Sitzung auf dem Rechner wird aufgezeichnet, unabhängig davon, über welchen Kanal sie entstanden ist. Jede wird zu einer AgentEye-[Sitzung](/de/agenteye/sessions); ihre Benutzer- und Assistentennachrichten, Tool-Aufrufe und Tool-Ergebnisse werden zu den entsprechenden [Ereignissen](/de/agenteye/event-stream). -Der Kanal, über den eine Sitzung gestartet wurde — Slack, Telegram, CLI oder eine geplante Ausführung — wird in der Sitzung festgehalten, sodass Sie sie unterscheiden und nach einer bestimmten filtern können. Dazu kommen das Modell, auf dem die Sitzung lief, der Chat und die Person, von der sie gestartet wurde, sowie — wenn eine Sitzung eine weitere erzeugt hat — die Verknüpfung zurück zur übergeordneten Sitzung. +Der Kanal, über den eine Sitzung gestartet wurde – Slack, Telegram, CLI oder ein geplanter Lauf – wird in der Sitzung festgehalten, sodass Sie diese unterscheiden und nach einem einzelnen filtern können. Dazu kommen das Modell, auf dem die Sitzung lief, der Chat und die Person, von der sie gestartet wurde, sowie – wenn eine Sitzung eine weitere erzeugt hat – die Verknüpfung zurück zur übergeordneten Sitzung. -Sitzungen erscheinen, sobald Hermes sie startet, unabhängig davon, ob bereits etwas gesagt wurde. Die Antwort eines Gesprächsschritts und seine Tool-Aufrufe bleiben in der Reihenfolge, in der sie tatsächlich stattfanden. Wenn eine Sitzung endet, erfahren Sie auch, warum sie endete, was sie gekostet hat und wie viele Tokens sie verbrauchte. +Sitzungen erscheinen, sobald Hermes sie startet, unabhängig davon, ob bereits etwas gesagt wurde. Die Antwort eines Gesprächsschritts und seine Tool-Aufrufe bleiben in der Reihenfolge, in der sie tatsächlich stattgefunden haben. Wenn eine Sitzung endet, erfahren Sie auch, warum sie endete, was sie gekostet hat und wie viele Tokens verwendet wurden. --- @@ -28,26 +28,26 @@ curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main | sh -s -- --key --hermes-enabled ``` -Dadurch wird der Collector installiert, als Hintergrunddienst registriert und die Aufzeichnung gestartet. Bestätigen Sie, dass er läuft: +Damit wird der Collector installiert, als Hintergrunddienst registriert und die Aufzeichnung gestartet. Prüfen Sie, ob er läuft: ```bash agenteye-collector health ``` -Möchten Sie mehrere Agenten auf demselben Rechner aufzeichnen? Fügen Sie das Flag jedes Agenten demselben Befehl hinzu — zum Beispiel `--hermes-enabled --codex-enabled`. +Zeichnen Sie mehrere Agenten auf demselben Rechner auf? Fügen Sie das jeweilige Flag dem gleichen Befehl hinzu – zum Beispiel `--hermes-enabled --codex-enabled`. -Beim ersten Start werden Ihre vorhandenen Hermes-Sitzungen einmalig nachgefüllt, und neue Aktivitäten werden dann innerhalb von Sekunden übertragen. Die eigenen Daten von Hermes werden dabei nur gelesen — niemals verändert oder gelöscht — und jede Nachricht wird genau einmal übertragen, auch nach Neustarts. +Beim ersten Start werden Ihre vorhandenen Hermes-Sitzungen einmalig nachgefüllt, und neue Aktivitäten werden anschließend innerhalb von Sekunden gestreamt. Hermes' eigene Daten werden ausschließlich gelesen – niemals verändert oder gelöscht – und jede Nachricht wird genau einmal übermittelt, auch nach Neustarts. -`health` teilt Ihnen außerdem mit, ob alles, was der Collector aufgezeichnet hat, tatsächlich bei AgentEye angekommen ist. Wenn ein Batch nicht zugestellt werden konnte, wird er aufbewahrt und erneut versucht, anstatt verworfen zu werden. Die Prüfung meldet so lange einen ungesunden Zustand, wie noch etwas aussteht — „gesund" bedeutet also, dass Ihre Daten angekommen sind, nicht lediglich, dass der Prozess läuft. +`health` zeigt Ihnen auch, ob alles, was der Collector aufgezeichnet hat, tatsächlich in AgentEye angekommen ist. Wenn ein Batch nicht zugestellt werden konnte, wird er aufbewahrt und erneut versucht, anstatt verworfen zu werden. Der Check meldet einen ungesunden Zustand, solange noch etwas aussteht – „healthy" bedeutet also, dass Ihre Daten angekommen sind, und nicht nur, dass der Prozess läuft. --- ## Wo es erscheint -Aufgezeichnete Sitzungen erscheinen unter **Sessions** und ihre Ereignisse im **Events**-Stream, genauso wie bei jedem anderen beobachteten Agenten — sodass [Sitzungswiedergabe](/de/agenteye/sessions), [Suche](/de/agenteye/queries), [Auswertungen](/de/agenteye/evaluations) und [Benachrichtigungen](/de/agenteye/alerts) alle darauf anwendbar sind. Filtern Sie nach dem Hermes-Agenten, um nur dessen Sitzungen anzuzeigen. +Aufgezeichnete Sitzungen erscheinen unter **Sessions** und ihre Ereignisse im **Events**-Stream – genauso wie bei jedem anderen Agenten, den Sie beobachten. Damit funktionieren [Session-Replay](/de/agenteye/sessions), [Suche](/de/agenteye/queries), [Auswertungen](/de/agenteye/evaluations) und [Benachrichtigungen](/de/agenteye/alerts) vollständig. Filtern Sie nach dem Hermes-Agenten, um nur diese anzuzeigen. --- ## Datenschutz -Hermes-Sitzungen enthalten das vollständige Gesprächsprotokoll — einschließlich Befehlsausgaben, Dateiinhalten und allem, was der Agent gelesen oder geschrieben hat — und können Geheimnisse enthalten. Aufgezeichnete Sitzungen werden unverändert übertragen. Aktivieren Sie die Aufzeichnung daher nur dort, wo die Zentralisierung dieser Inhalte in AgentEye angemessen ist, und vergeben Sie dem Collector einen Schlüssel, der ausschließlich auf `events:add` beschränkt ist. Unter [Sicherheit](/de/agenteye/security) erfahren Sie, wie Ihre Daten isoliert aufbewahrt werden. \ No newline at end of file +Hermes-Sitzungen enthalten das vollständige Transkript – einschließlich Befehlsausgaben, Dateiinhalten und allem, was der Agent gelesen oder geschrieben hat – und können Geheimnisse enthalten. Aufgezeichnete Sitzungen werden unverändert übermittelt. Aktivieren Sie die Aufzeichnung daher nur dort, wo die Zentralisierung dieser Inhalte in AgentEye angemessen ist, und geben Sie dem Collector einen Schlüssel, der ausschließlich auf `events:add` beschränkt ist. Unter [Sicherheit](/de/agenteye/security) erfahren Sie, wie Ihre Daten isoliert aufbewahrt werden. \ No newline at end of file diff --git a/docs/de/agenteye/incidents.mdx b/docs/de/agenteye/incidents.mdx index 37b831b5..75c58ff3 100644 --- a/docs/de/agenteye/incidents.mdx +++ b/docs/de/agenteye/incidents.mdx @@ -1,28 +1,28 @@ --- title: "Incidents" -description: "Wenn ein Alert ausgelöst wird, sieht jeder, dass der Incident offen ist, wer ihn verantwortet und was bisher geschehen ist – in einer übersichtlichen, zugeordneten Timeline." +description: "Wenn ein Alert ausgelöst wird, können alle sehen, dass ein Incident offen ist, wer ihn besitzt und was bisher passiert ist – in einer einzigen, zugeschriebenen Timeline." --- -Wenn ein Alert ausgelöst wird, lautet die erste Frage immer: „Wer kümmert sich darum?" Incidents liefern die Antwort: Sobald eine Schwellenwertüberschreitung eintritt, sieht jeder, dass der Incident offen ist, wer ihn verantwortet und was bisher genau passiert ist – als saubere, zugeordnete Dokumentation, die sich direkt für eine Post-mortem-Analyse verwenden lässt. +Wenn ein Alert ausgelöst wird, lautet die erste Frage immer: „Wer kümmert sich darum?" Incidents beantworten sie: In dem Moment, in dem etwas eine Schwelle überschreitet, kann jeder sehen, dass der Incident offen ist, wer ihn besitzt und genau was bisher passiert ist – mit einem sauberen, zugeschriebenen Protokoll, das sich direkt an ein Post-mortem weitergeben lässt. -![Der Incidents-Posteingang: alert-verknüpfte und manuell geöffnete Incident-Karten, nach Status gruppiert, jeweils mit Schweregrad-Badge und zugewiesener Person](/agenteye/images/incidents.png) -*Der Posteingang gruppiert offene Incidents nach Status und filtert nach Schweregrad und zugewiesener Person, sodass sofort ersichtlich ist, was jetzt menschliches Eingreifen erfordert.* +![Der Incidents-Posteingang: Alert-verknüpfte und manuell geöffnete Incident-Karten, nach Status gruppiert, jede mit einem Schweregrad-Badge und einem Verantwortlichen](/agenteye/images/incidents.png) +*Der Posteingang gruppiert offene Incidents nach Status und filtert nach Schweregrad und Verantwortlichem, damit du sofort siehst, wo ein Mensch gefragt ist.* -## Auf einen Blick sehen, wer zuständig ist +## Auf einen Blick sehen, wer es übernommen hat -Kein „Schaut da gerade jemand drauf?" mehr im Chat. Eine Schwellenwertüberschreitung öffnet automatisch einen Incident und legt ihn in einen gemeinsamen Posteingang, gruppiert nach Status. Wer ihn bestätigt, erscheint namentlich darauf – das Team weiß sofort, dass es in Bearbeitung ist. Die Bestätigung ist gemeinsam nutzbar: Mehrere Operatoren können denselben Incident bestätigen, wobei jeder einzeln erfasst wird. So ist ein vollständiges War-Room-Team namentlich sichtbar, ohne dass sich Einträge überschneiden. Eine verantwortliche Person für das Triage lässt sich zuweisen; der Posteingang kann nach Schweregrad oder zugewiesener Person gefiltert werden, um nur die eigenen Incidents anzuzeigen. +Kein „Schaut sich das jemand an?" mehr in einem Chat-Thread. Ein Schwellenverstoß öffnet automatisch einen Incident und legt ihn in einen gemeinsamen Posteingang, nach Status gruppiert. Bestätige ihn, und dein Name steht drauf – so weiß das restliche Team, dass es gehandhabt wird. Die Bestätigung ist geteilt: Mehrere Operatoren können denselben Incident bestätigen, und jeder wird einzeln erfasst, sodass ein vollständiges War-Room-Team namentlich auftaucht, ohne sich gegenseitig zu überschreiben. Weise einen Verantwortlichen für das Triage zu und filtere den Posteingang nach Schweregrad oder Verantwortlichem, um ihn auf das Wesentliche zu reduzieren. -## Die vollständige Geschichte in einer Timeline +## Die ganze Geschichte in einer Timeline -Wenn der Incident abgeschlossen ist, ist das Protokoll bereits fertig. Beim Öffnen eines Incidents sind der Auslöser, eine Zusammenfassung der Überschreitung, zugewiesene Personen und Abonnenten, ein Kommentarbereich zur direkten Koordination sowie eine unveränderliche Aktivitäts-Timeline sichtbar. +Wenn der Incident vorbei ist, hast du den Bericht bereits. Öffne einen beliebigen Incident und du siehst den Schwellenverstoss als Beleg, die zugewiesenen Personen und Abonnenten, einen Kommentar-Thread zur Koordination direkt vor Ort sowie eine nur ergänzbare Aktivitäts-Timeline. -![Eine Incident-Detailansicht: der übergeordnete Alert und die Überschreitungszusammenfassung, zugewiesene Personen und Abonnenten, eine zugeordnete Aktivitäts-Timeline und ein Kommentarbereich](/agenteye/images/incident-detail.png) -*Alles, was passiert ist, in chronologischer Reihenfolge – jede Zeile mit dem Namen der verantwortlichen Person.* +![Eine Incident-Detailansicht: der übergeordnete Alert und die Breach-Zusammenfassung, Verantwortliche und Abonnenten, eine zugeschriebene Aktivitäts-Timeline und ein Kommentar-Thread](/agenteye/images/incident-detail.png) +*Alles, was passiert ist, in chronologischer Reihenfolge – jede Zeile signiert von der Person, die sie ausgeführt hat.* -Jede Aktion (geöffnet, bestätigt, gelöst usw.) wird in diese Timeline geschrieben und niemals nachträglich geändert. Jeder Eintrag ist zugeordnet: per E-Mail dem Operator, der die Aktion durchgeführt hat, oder **automated** für alles, was Failproof AI Observability selbstständig getan hat – beispielsweise das Öffnen des Incidents bei einer Schwellenwertüberschreitung. Nichts ist anonym und nichts geht verloren, sodass die Post-mortem-Analyse nahezu von selbst entsteht. +Jede Aktion (geöffnet, bestätigt, gelöst usw.) wird in diese Timeline geschrieben und nie nachträglich gelöscht. Jeder Eintrag ist zugeschrieben: dem Operator, der ihn vorgenommen hat, per E-Mail, oder **automated** für alles, was Failproof AI Observability eigenständig getan hat, etwa das Öffnen des Incidents bei einem Verstoß. Nichts ist anonym, nichts geht verloren – das Post-mortem schreibt sich dadurch fast von selbst. -## Wie sich ein Incident entwickelt +## Wie sich ein Incident bewegt ```mermaid stateDiagram-v2 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **Offen (firing):** Die Überschreitung öffnet den Incident und benachrichtigt die konfigurierten Kanäle einmalig. Wiederholte Überschreitungen werden in denselben Incident aufgenommen und aktualisieren dessen Nachweis, anstatt erneut Benachrichtigungen zu versenden. -- **Bestätigt (acknowledged):** Ein Operator übernimmt den Incident. Er bleibt offen, und spätere Überschreitungen aktualisieren den Nachweis ohne weitere Benachrichtigungen. -- **Gelöst (resolved):** Ein Operator schließt den Incident. Eine automatische Auflösung beim Wegfall der Bedingung ist geplant, aber noch nicht aktiviert – ein Incident bleibt daher offen, bis ein Mensch ihn manuell auflöst. Das sorgt für Klarheit darüber, was tatsächlich behoben ist. Für denselben Alert kann später ein neuer Incident geöffnet werden. +- **Offen (firing):** Der Verstoß öffnet den Incident und benachrichtigt deine Kanäle einmalig. Wiederholte Verstöße fließen in denselben Incident ein und aktualisieren dessen Beweise, anstatt dich immer wieder zu benachrichtigen. +- **Bestätigt (acknowledged):** Ein Operator übernimmt ihn. Er bleibt offen, und spätere Verstöße aktualisieren die Beweise stillschweigend. +- **Gelöst (resolved):** Ein Operator schließt ihn ab. Automatische Auflösung bei Wegfall der Bedingung ist geplant, aber noch nicht aktiviert – ein Incident bleibt also offen, bis ein Mensch ihn auflöst, was alle ehrlich darüber hält, was tatsächlich behoben wurde. Für denselben Alert kann später ein neuer Incident geöffnet werden. -Ein Alert kann zu einem Zeitpunkt höchstens einen offenen Incident haben, sodass eine flatternde Regel keine Duplikate erzeugen kann. Incidents lassen sich auch manuell öffnen: als eigenständiger Incident für etwas, das kein Alert erfasst hat, oder als einem bestehenden Alert zugeordneter Incident – sofern die Berechtigung `incidents:write` vorhanden ist. +Ein Alert hält zu jedem Zeitpunkt höchstens einen offenen Incident, sodass eine flappende Regel dich nicht in Duplikaten vergraben kann. Du kannst einen Incident auch manuell öffnen: einen eigenständigen für etwas, das kein Alert erfasst hat, oder einen, der an einen bestehenden Alert angehängt ist – sofern du `incidents:write` besitzt. -## Wo es zu finden ist +## Wo du es findest -Incidents befinden sich unter `//incidents`. Für die Anzeige wird **`incidents:read`** benötigt; für das manuelle Öffnen eines Incidents **`incidents:write`**; für das Bestätigen, Zuweisen, Kommentieren und Lösen **`incidents:ack`**. Ältere Schlüssel mit der zurückgezogenen Berechtigung `alerts:ack` funktionieren weiterhin, da sie als `incidents:ack` anerkannt werden – eine Neuausstellung für Bereitschaftsrotationen ist daher nicht erforderlich. +Incidents befinden sich unter `//incidents`. Zum Ansehen wird **`incidents:read`** benötigt; zum manuellen Öffnen eines Incidents **`incidents:write`**; zum Bestätigen, Zuweisen, Kommentieren und Lösen **`incidents:ack`**. Ältere Schlüssel, denen das abgekündigte `alerts:ack` gewährt wurde, funktionieren weiterhin, da es als `incidents:ack` anerkannt wird – deine Bereitschaftsrotation muss also nicht neu ausgestellt werden. -## Verwandte Themen +## Verwandt -- [Alerts](/de/agenteye/alerts): die Regeln, die Incidents öffnen, wenn ein Schwellenwert überschritten wird. -- [Error Tracking](/de/agenteye/error-tracking): alle Fehler an einem Ort einsehen und einen davon zu einem Alert heraufstufen. -- [Audits](/de/agenteye/audits): der geplante Analyst, der Fehler findet, die von keiner Regel überwacht wurden. \ No newline at end of file +- [Alerts](/de/agenteye/alerts): die Regeln, die diese Incidents öffnen, wenn ein Schwellenwert überschritten wird. +- [Error tracking](/de/agenteye/error-tracking): alle Fehler an einem Ort einsehen und einen davon zu einem Alert befördern. +- [Audits](/de/agenteye/audits): der geplante Analyst, der Fehler findet, auf die keine Regel geachtet hat. \ No newline at end of file diff --git a/docs/de/agenteye/observability.mdx b/docs/de/agenteye/observability.mdx index 60ecfd4c..b98901d9 100644 --- a/docs/de/agenteye/observability.mdx +++ b/docs/de/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- title: "Beobachten" -description: "Die Beobachtungsoberflächen zeigen Ihnen, was Ihre Agenten gerade tun, und ermöglichen den detaillierten Einblick in einzelne Ausführungen." +description: "Die Beobachtungsoberflächen zeigen dir in Echtzeit, was deine Agenten gerade tun, und ermöglichen es, jeden einzelnen Lauf im Detail zu untersuchen." --- -Die Beobachtungsoberflächen zeigen Ihnen, was Ihre Agenten gerade tun, und ermöglichen den detaillierten Einblick in einzelne Ausführungen. Alle Daten hier sind live, auf Ihre Organisation beschränkt und nach Datumsbereich, Umgebung, Agent und Sitzung filterbar – so gelangen Sie in Sekunden von „irgendetwas stimmt nicht" zum exakten Ausführungslauf. +Die Beobachtungsoberflächen zeigen dir in Echtzeit, was deine Agenten gerade tun, und ermöglichen es, jeden einzelnen Lauf im Detail zu untersuchen. Alles hier ist live, auf deine Organisation beschränkt und nach Zeitraum, Umgebung, Agent und Session filterbar – so kommst du in Sekunden von „irgendwas stimmt nicht" zum genauen Lauf. -![Der Live-Event-Stream, farbcodiert nach Typ und filterbar nach Umgebung, Agent und Sitzung](/agenteye/images/events-stream.png) +![Der Live-Event-Stream, farblich nach Typ kodiert und nach Umgebung, Agent und Session filterbar](/agenteye/images/events-stream.png) -Vier Oberflächen, jede mit einer eigenen Seite: +Vier Oberflächen, jede mit eigener Seite: -- **[Event-Stream](/de/agenteye/event-stream)**: der live, schrittweise Verlauf jeder Ausführung über alle Agenten hinweg, neueste zuerst. Die Startseite Ihrer Organisation und erste Anlaufstelle bei der Fehlersuche. -- **[Sitzungen und Ausführungsgraph](/de/agenteye/sessions)**: diese Ereignisse zu einer Zeile pro Ausführung zusammengefasst, plus eine git-artige Darstellung des Ablaufs jeder Ausführung. -- **[Performance-Metriken](/de/agenteye/telemetry)**: Latenz-Heatmaps und p50/p95/p99-Kennwerte für Ihre Modelle, Tools und Hooks, sodass ein Ausreißer am oberen Ende sofort vom Median auffällt. -- **[Fehlerverfolgung](/de/agenteye/error-tracking)**: eine einzige Triage-Oberfläche für alles, was schiefgelaufen ist – mit einem Klick von einem ausgelösten Alert zum fehlerhaften Ausführungslauf. +- **[Event-Stream](/de/agenteye/event-stream)**: die live, schrittweise Spur jedes Laufs aller Agenten, neueste zuerst. Deine Org-Startseite und erster Anlaufpunkt für die Fehlersuche. +- **[Sessions und Ausführungsgraph](/de/agenteye/sessions)**: diese Events zu je einer Zeile pro Lauf zusammengefasst, plus eine git-artige Darstellung des Ablaufs jedes Laufs. +- **[Performance-Metriken](/de/agenteye/telemetry)**: Latenz-Heatmaps und p50/p95/p99-Kennzahlen für deine Modelle, Tools und Hooks, damit ein Ausreißer am Ende der Verteilung sofort vom Median absticht. +- **[Fehlerverfolgung](/de/agenteye/error-tracking)**: eine einzige Triage-Oberfläche für alles, was schiefgelaufen ist – ein Klick von einem ausgelösten Alert zum betroffenen Lauf. -## Verwandte Themen +## Verwandtes -- [Evaluierungen](/de/agenteye/evaluations): Bewerten Sie jeden Ausführungslauf hinsichtlich der Qualität. -- [Alerts](/de/agenteye/alerts): Wandeln Sie beliebige Schwellenwerte in Benachrichtigungsregeln um. -- [Audits](/de/agenteye/audits): Lassen Sie Failproof AI Observability Fehlermuster über Sitzungen hinweg für Sie finden. -- [CLI und Agenten](/de/agenteye/cli-and-agents): dieselbe Observability direkt aus Ihrem Terminal. \ No newline at end of file +- [Evaluierungen](/de/agenteye/evaluations): jeden Lauf auf Qualität bewerten. +- [Alerts](/de/agenteye/alerts): beliebige Schwellenwerte in Benachrichtigungsregeln umwandeln. +- [Audits](/de/agenteye/audits): Failproof AI Observability Fehlermuster über Sessions hinweg für dich finden lassen. +- [CLI und Agenten](/de/agenteye/cli-and-agents): dieselbe Observability direkt aus deinem Terminal. \ No newline at end of file diff --git a/docs/de/agenteye/openclaw-capture.mdx b/docs/de/agenteye/openclaw-capture.mdx index ed337e98..8847bee4 100644 --- a/docs/de/agenteye/openclaw-capture.mdx +++ b/docs/de/agenteye/openclaw-capture.mdx @@ -1,49 +1,49 @@ --- -title: "OpenClaw Session-Aufzeichnung" -description: "Leiten Sie die lokalen OpenClaw-Sitzungen Ihres Teams als gewöhnliche Sessions und Events in AgentEye weiter — ohne Änderungen an der Art, wie OpenClaw ausgeführt wird." +title: "OpenClaw-Sitzungsaufzeichnung" +description: "Übertragen Sie die lokalen OpenClaw-Sitzungen Ihres Teams als gewöhnliche Sitzungen und Events in AgentEye — ohne Änderungen an der Art, wie OpenClaw ausgeführt wird." --- -Wenn Ihr Team [OpenClaw](https://docs.openclaw.ai) nutzt, bringt die OpenClaw-Sitzungsaufzeichnung diese Sessions als gewöhnliche Sessions und Events in AgentEye ein. So können Sie sie durchsuchen, wiedergeben und gemeinsam mit allem anderen auswerten, was Sie beobachten. Sie ergänzt das [Python SDK](/de/agenteye/python-sdk): Das SDK instrumentiert Agenten, die Sie selbst schreiben, während diese Funktion die OpenClaw-Arbeit erfasst, die Ihr Team bereits durchführt — ohne Änderungen an deren Arbeitsweise. +Wenn Ihr Team [OpenClaw](https://docs.openclaw.ai) nutzt, überträgt die OpenClaw-Sitzungsaufzeichnung diese Sitzungen als gewöhnliche Sitzungen und Events in AgentEye, sodass Sie sie neben allem anderen, was Sie beobachten, durchsuchen, wiedergeben und auswerten können. Sie ergänzt das [Python SDK](/de/agenteye/python-sdk): Das SDK instrumentiert Agents, die Sie selbst schreiben, während diese Funktion die OpenClaw-Arbeit erfasst, die Ihr Team bereits erledigt — ohne Änderungen an der Ausführung. -Ein kleiner Hintergrund-Collector liest OpenClaw's lokale Sitzungsprotokolle, während sie geschrieben werden, und übermittelt sie an AgentEye. Er funktioniert genauso wie der [Codex Capture](/de/agenteye/codex-capture), und ein einzelner Collector kann beide gleichzeitig erfassen. +Ein kleiner Hintergrundkollektor liest OpenClaw's lokale Sitzungstranskripte, während sie geschrieben werden, und sendet sie an AgentEye. Er funktioniert genauso wie die [Codex-Aufzeichnung](/de/agenteye/codex-capture), und ein einziger Kollektor kann beide gleichzeitig erfassen. --- -## Was aufgezeichnet wird +## Was erfasst wird -Jeder Agent, der im OpenClaw-Setup eines Rechners konfiguriert ist, wird vom Collector dieses Rechners erfasst — es ist keine agentenspezifische Einrichtung erforderlich. +Jeder Agent, der im OpenClaw-Setup eines Computers konfiguriert ist, wird vom Kollektor dieses Computers erfasst — es ist keine agentenbezogene Einrichtung erforderlich. -Jede OpenClaw-Sitzung wird zu einer AgentEye-[Session](/de/agenteye/sessions); ihre Benutzer- und Assistentennachrichten, Tool-Aufrufe und Tool-Ergebnisse werden zu den entsprechenden [Events](/de/agenteye/event-stream). +Jede OpenClaw-Sitzung wird zu einer AgentEye-[Sitzung](/de/agenteye/sessions); ihre Benutzer- und Assistentennachrichten, Tool-Aufrufe und Tool-Ergebnisse werden zu den entsprechenden [Events](/de/agenteye/event-stream). --- ## Aktivierung -Die Aufzeichnung ist deaktiviert, bis Sie sie einschalten. Installieren Sie den Collector mit einem API-Schlüssel, der die Berechtigung `events:add` besitzt (siehe [API-Schlüssel](/de/agenteye/api-keys)), und aktivieren Sie die OpenClaw-Aufzeichnung: +Die Aufzeichnung ist deaktiviert, bis Sie sie einschalten. Installieren Sie den Kollektor mit einem API-Schlüssel, der die Berechtigung `events:add` besitzt (siehe [API-Schlüssel](/de/agenteye/api-keys)), und aktivieren Sie die OpenClaw-Aufzeichnung: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -Dadurch wird der Collector installiert, als Hintergrunddienst registriert und die Aufzeichnung gestartet. Bestätigen Sie, dass er läuft: +Dadurch wird der Kollektor installiert, als Hintergrunddienst registriert und die Aufzeichnung gestartet. Prüfen Sie, ob er läuft: ```bash agenteye-collector health ``` -Möchten Sie mehr als einen Agenten auf demselben Rechner erfassen? Fügen Sie das Flag für jeden weiteren Agenten demselben Befehl hinzu — zum Beispiel `--openclaw-enabled --codex-enabled`. +Möchten Sie mehr als einen Agent auf demselben Computer erfassen? Fügen Sie jeweils das entsprechende Flag im selben Befehl hinzu — zum Beispiel `--openclaw-enabled --codex-enabled`. -Beim ersten Start werden Ihre vorhandenen OpenClaw-Sitzungen einmalig nachträglich importiert, danach wird neue Aktivität innerhalb von Sekunden übertragen. Die eigenen Dateien von OpenClaw werden ausschließlich gelesen — niemals verändert, verschoben oder gelöscht — und jede Sitzung wird genau einmal übermittelt, auch nach Neustarts. +Beim ersten Start werden Ihre vorhandenen OpenClaw-Sitzungen einmalig nachgefüllt, und neue Aktivitäten werden danach innerhalb von Sekunden übertragen. OpenClaw's eigene Dateien werden ausschließlich gelesen — niemals verändert, verschoben oder gelöscht — und jede Sitzung wird genau einmal übertragen, auch nach Neustarts. --- ## Wo die Daten erscheinen -Aufgezeichnete Sitzungen erscheinen unter **Sessions** und ihre Events im **Events**-Stream, genau wie bei jedem anderen beobachteten Agenten — sodass [Session-Wiedergabe](/de/agenteye/sessions), [Suche](/de/agenteye/queries), [Auswertungen](/de/agenteye/evaluations) und [Benachrichtigungen](/de/agenteye/alerts) alle darauf anwendbar sind. Filtern Sie nach dem OpenClaw-Agenten, um nur dessen Daten anzuzeigen. +Aufgezeichnete Sitzungen erscheinen unter **Sessions** und ihre Events im **Events**-Stream, genau wie bei jedem anderen Agent, den Sie beobachten — sodass [Sitzungswiedergabe](/de/agenteye/sessions), [Suche](/de/agenteye/queries), [Auswertungen](/de/agenteye/evaluations) und [Benachrichtigungen](/de/agenteye/alerts) allesamt darauf angewendet werden können. Filtern Sie nach dem OpenClaw-Agent, um nur dessen Daten anzuzeigen. --- ## Datenschutz -OpenClaw-Protokolle enthalten die vollständige Sitzung — einschließlich Befehlsausgaben, Dateiinhalte und alles, was der Agent gelesen oder geschrieben hat — und können vertrauliche Informationen enthalten. Aufgezeichnete Sitzungen werden unverändert übermittelt. Aktivieren Sie die Aufzeichnung daher nur auf Rechnern und für Teams, bei denen die Zentralisierung dieser Inhalte in AgentEye angemessen ist, und vergeben Sie dem Collector ausschließlich einen auf `events:add` beschränkten Schlüssel. Unter [Sicherheit](/de/agenteye/security) erfahren Sie, wie Ihre Daten isoliert aufbewahrt werden. \ No newline at end of file +OpenClaw-Transkripte enthalten die vollständige Sitzung — einschließlich Befehlsausgabe, Dateiinhalte und alles, was der Agent gelesen oder geschrieben hat — und können Geheimnisse enthalten. Aufgezeichnete Sitzungen werden unverändert übertragen. Aktivieren Sie die Aufzeichnung daher nur auf Computern und für Teams, bei denen die Zentralisierung dieser Inhalte in AgentEye angemessen ist, und geben Sie dem Kollektor ausschließlich einen auf `events:add` beschränkten Schlüssel. Unter [Sicherheit](/de/agenteye/security) erfahren Sie, wie Ihre Daten isoliert aufbewahrt werden. \ No newline at end of file diff --git a/docs/de/agenteye/overview.mdx b/docs/de/agenteye/overview.mdx index ee0650c8..0cf19047 100644 --- a/docs/de/agenteye/overview.mdx +++ b/docs/de/agenteye/overview.mdx @@ -1,108 +1,108 @@ --- title: "Failproof AI: Agenten auf Fehler überwachen" -description: "Failproof AI Observability ist eine selbst gehostete Plattform zur Beobachtung, Bewertung und Verbesserung Ihrer KI-Agenten in der Produktion." +description: "Failproof AI Observability ist eine selbst gehostete Plattform zum Beobachten, Bewerten und Verbessern Ihrer KI-Agenten im Produktionsbetrieb." --- -Failproof AI Observability ist eine selbst gehostete Plattform zur Beobachtung, Bewertung und Verbesserung Ihrer KI-Agenten in der Produktion. Sie zeichnet alles auf, was Ihre Agenten tun (jeden Tool-Aufruf, jede Modellanfrage, jeden Hook und jeden Fehler), bewertet die Qualität jedes Durchlaufs und zeigt Ihnen die Fehler, nach denen Sie nicht aktiv gesucht haben – alles in einem Dashboard, das Sie in Ihrer eigenen Infrastruktur betreiben. +Failproof AI Observability ist eine selbst gehostete Plattform zum Beobachten, Bewerten und Verbessern Ihrer KI-Agenten im Produktionsbetrieb. Sie zeichnet alles auf, was Ihre Agenten tun (jeden Tool-Aufruf, jede Modellanfrage, jeden Hook und jeden Fehler), bewertet die Qualität jedes Durchlaufs und zeigt Ihnen Fehler auf, nach denen Sie nicht einmal gesucht hätten – alles in einem Dashboard, das Sie in Ihrer eigenen Infrastruktur betreiben. -Wenn Sie KI-Agenten einsetzen und es leid sind zu rätseln, warum ein Durchlauf schiefgelaufen ist, sind Sie hier genau richtig. Diese Seite erklärt, was Failproof AI Observability Ihnen bietet und wie die einzelnen Teile zusammenpassen – noch bevor Sie irgendetwas installieren. +Wenn Sie KI-Agenten einsetzen und es leid sind zu rätseln, warum ein Durchlauf schiefgelaufen ist, sind Sie hier genau richtig. Diese Seite erklärt, was Failproof AI Observability Ihnen bietet und wie die einzelnen Teile zusammenspielen – bevor Sie irgendetwas installieren. -> **Failproof AI Observability ist ein Enterprise-Produkt von Failproof AI.** Sie möchten es in Aktion sehen? Fordern Sie eine Demo an: E-Mail an [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +> **Failproof AI Observability ist ein Enterprise-Produkt von Failproof AI.** Möchten Sie es in Aktion sehen? Demo anfordern: E-Mail an [nikita@befailproof.ai](mailto:nikita@befailproof.ai). -![Eine Failproof AI Observability-Sitzung als git-ähnlicher Ausführungsgraph neben der Ereigniszeitachse, mit einer Aufschlüsselung von Tools, Modellen und Hooks in der rechten Seitenleiste](/agenteye/images/session-detail.png) +![Eine Failproof AI Observability-Sitzung als Git-artiger Ausführungsgraph neben ihrer Ereignis-Zeitleiste, mit einer laufbasierten Aufschlüsselung von Tools, Modellen und Hooks in der rechten Spalte](/agenteye/images/session-detail.png) -*Jeder Agentendurchlauf wird als git-ähnlicher Ausführungsgraph (links) neben seiner Ereigniszeitachse dargestellt. Parallele Unteragenten erhalten jeweils ihre eigene Spur; die rechte Seitenleiste schlüsselt die Tools, Modelle, Hooks und den Token-Verbrauch des Durchlaufs auf.* +*Jeder Agenten-Durchlauf wird als Git-artiger Ausführungsgraph (links) neben seiner Ereignis-Zeitleiste dargestellt. Parallele Sub-Agenten erhalten jeweils eine eigene Spur; die rechte Spalte schlüsselt die Tools, Modelle, Hooks und den Token-Verbrauch des Durchlaufs auf.* --- ## In Aktion erleben -Zwei kurze Videos zeigen die zwei Dinge, die Teams zuerst nutzen: einen Durchlauf nachverfolgen und Fehler automatisch erkennen. +Zwei kurze Videos zeigen die zwei Funktionen, die Teams als erstes nutzen: einen Durchlauf verfolgen und Fehler automatisch finden.
-*Agenten-Tracing: Verfolgen Sie einen einzelnen Durchlauf Schritt für Schritt, vom Ziel über die Tools bis zur endgültigen Antwort.* +*Agent-Tracing: einen einzelnen Durchlauf Schritt für Schritt verfolgen, vom Ziel über die Tools bis zur abschließenden Antwort.*
-*Failproof Audit: Lassen Sie Failproof AI Observability Ihre Logs sitzungsübergreifend durchsuchen und erfahren Sie, was behoben werden muss.* +*Failproof Audit: Failproof AI Observability analysiert Ihre Logs sitzungsübergreifend und zeigt Ihnen, was behoben werden muss.* --- -## Warum Teams es nutzen +## Warum Teams es verwenden -- **Sehen Sie, was Ihr Agent wirklich getan hat.** Jeder Durchlauf wird zu einem lesbaren, git-ähnlichen Ausführungsgraphen: welche Tools parallel liefen, welche Unteragenten abgezweigt wurden, wo es ins Stocken geriet und was es gekostet hat. -- **Qualitätsrückgänge automatisch erkennen.** Verbinden Sie einen kleinen Scoring-Dienst, und Failproof AI Observability bewertet jeden abgeschlossenen Durchlauf – sodass ein Rückgang der Hilfsbereitschaft oder ein Anstieg von Halluzinationen von selbst sichtbar wird. -- **Fehler finden, für die Sie keine Regel geschrieben haben.** Regelmäßige Audits durchsuchen Ihre Logs sitzungsübergreifend nach Fehlerclustern, Latenz-Ausreißern, niedrigen Bewertungen und hängenden Durchläufen und liefern Ihnen priorisierte, evidenzbasierte Erkenntnisse. -- **Benachrichtigt werden, wenn es darauf ankommt.** Schwellenwertregeln reagieren auf Fehlerrate, Latenz, Kosten oder Evaluator-Scores und eröffnen Incidents, die Sie bestätigen, zuweisen und lösen können. -- **Fragen in natürlicher Sprache stellen.** Ein KI-Assistent im Dashboard beantwortet Fragen wie „Wie entwickelt sich die Qualität in der Produktion diese Woche?" – auf Basis Ihrer eigenen Daten. Jede Änderung, die er vornimmt, ist genehmigungspflichtig. -- **Ihre Daten behalten.** Failproof AI Observability ist selbst gehostet: Ereignisse, Prompts und Analysen bleiben in der von Ihnen kontrollierten Infrastruktur. +- **Sehen Sie, was Ihr Agent tatsächlich getan hat.** Jeder Durchlauf wird zu einem lesbaren, Git-artigen Ausführungsgraphen: welche Tools parallel liefen, welche Sub-Agenten abgezweigt sind, wo er ins Stocken geriet und was er verbraucht hat. +- **Qualitätsverschlechterungen automatisch erkennen.** Verbinden Sie einen kleinen Scoring-Dienst, und Failproof AI Observability bewertet jeden abgeschlossenen Durchlauf – so fällt ein Rückgang der Hilfsbereitschaft oder ein Anstieg von Halluzinationen von selbst auf. +- **Fehler finden, für die Sie keine Regel geschrieben haben.** Wiederkehrende Audits analysieren Ihre Logs sitzungsübergreifend nach Fehlerclustern, Latenz-Ausreißern, niedrigen Bewertungen und feststeckenden Durchläufen und liefern Ihnen priorisierte, beleggestützte Befunde. +- **Benachrichtigt werden, wenn es darauf ankommt.** Schwellenwertregeln lösen bei Fehlerrate, Latenz, Kosten oder Evaluator-Bewertungen aus und öffnen Vorfälle, die Sie bestätigen, zuweisen und lösen können. +- **Fragen in natürlicher Sprache stellen.** Ein KI-Assistent im Dashboard beantwortet Fragen wie „Wie entwickelt sich die Qualität diese Woche in der Produktion?" auf Basis Ihrer eigenen Daten. Jede Änderung, die er vornimmt, ist genehmigungspflichtig. +- **Behalten Sie Ihre Daten.** Failproof AI Observability ist selbst gehostet: Ereignisse, Prompts und Analysen verbleiben in der Infrastruktur, die Sie kontrollieren. --- ## Was Sie erhalten -Failproof AI Observability ist um drei Ideen herum organisiert (**Beobachten**, **Analysieren** und **Verwalten**), die in der linken Seitenleiste des Dashboards gespiegelt werden. +Failproof AI Observability ist um drei Konzepte herum organisiert (**beobachten**, **analysieren** und **verwalten**), die in der linken Seitenleiste des Dashboards widergespiegelt werden. -**Beobachten** (die unverfälschte Wahrheit dessen, was passiert ist): +**Beobachten** (die ungeschönte Wahrheit darüber, was passiert ist): -- **[Ereignis-Stream](/de/agenteye/event-stream)**: die Live-Aufzeichnung jedes einzelnen Schritts jedes Durchlaufs (Tool-Aufrufe, Modellaufrufe, Hooks, Fehler). -- **[Sitzungen](/de/agenteye/sessions)**: diese Ereignisse zusammengefasst zu einer Zeile pro Durchlauf, jeweils bereit zur Bewertung, mit einem git-ähnlichen Ausführungsgraphen. -- **[Performance-Metriken](/de/agenteye/telemetry)**: Latenz-Heatmaps pro Oberfläche und p50/p95/p99-Werte für Modelle, Tools und Hooks, damit ein Ausreißer im langen Ende sofort auffällt. -- **[Fehlerverfolgung](/de/agenteye/error-tracking)**: eine einzige Triage-Oberfläche für alles, was schiefgelaufen ist, einen Klick von einem ausgelösten Alert entfernt. +- **[Ereignisstrom](/de/agenteye/event-stream)**: die live, schrittweise Spur jedes Durchlaufs (Tool-Aufrufe, Modellaufrufe, Hooks, Fehler). +- **[Sitzungen](/de/agenteye/sessions)**: diese Ereignisse zu je einer Zeile pro Durchlauf zusammengefasst, jede bereit zur Bewertung, mit einem Git-artigen Ausführungsgraphen. +- **[Performance-Metriken](/de/agenteye/telemetry)**: oberflächenspezifische Latenz-Heatmaps und p50/p95/p99-Kennzahlen für Modelle, Tools und Hooks, damit ein Tail-Spike gegenüber dem Median auffällt. +- **[Fehlerverfolgung](/de/agenteye/error-tracking)**: eine zentrale Triage-Oberfläche für alles, was schiefgelaufen ist, einen Klick von einem ausgelösten Alert entfernt. ![Die Tools-Beobachtungsseite: eine Latenz-Heatmap, ein Perzentil-Band und ein Tool-Verteilungsbalken über 24 Zeitabschnitte](/agenteye/images/tools.png) -*Jede Beobachtungsoberfläche kombiniert eine Sparkline und p50/p95/p99-Werte mit einer Latenz-Heatmap und einem Perzentil-Band. Hier gezeigt: Tools.* +*Jede Beobachtungsoberfläche kombiniert eine Sparkline und p50/p95/p99-Kennzahlen mit einer Latenz-Heatmap und einem Perzentil-Band. Hier zu sehen: Tools.* -**Analysieren** (Aktivitäten in Erkenntnisse verwandeln): +**Analysieren** (Aktivität in Antworten verwandeln): -- **[Abfragen](/de/agenteye/queries)** und **[Dashboards](/de/agenteye/dashboards)**: gespeichertes SQL über Ihre Ereignisse und Evaluierungen, als geteilte, organisationsweite Dashboards visualisiert. -- **[Evaluierungen](/de/agenteye/evaluations)**: Qualitätsbewertungen, die von Ihrem eigenen Evaluator-Dienst erstellt werden, mit Begründung pro Bewertung. +- **[Abfragen](/de/agenteye/queries)** und **[Dashboards](/de/agenteye/dashboards)**: gespeichertes SQL über Ihre Ereignisse und Evaluierungen, in gemeinsam genutzte, organisationsweite Dashboards eingebettet. +- **[Evaluierungen](/de/agenteye/evaluations)**: Qualitätsbewertungen, die von Ihrem eigenen Evaluator-Dienst erzeugt werden, mit Begründung pro Bewertung. - **[Audits](/de/agenteye/audits)**: wiederkehrende Untersuchungen, die Fehlermuster sitzungsübergreifend aufdecken. -- **[Alerts](/de/agenteye/alerts)** und **[Incidents](/de/agenteye/incidents)**: Schwellenwertregeln, die Sie benachrichtigen, sowie ein Incident-Workflow zur Triage. +- **[Alerts](/de/agenteye/alerts)** und **[Vorfälle](/de/agenteye/incidents)**: Schwellenwertregeln, die Sie benachrichtigen, plus ein Incident-Workflow zur Triage. -**Schnittstellen** (auf Ihre Daten auf Ihre Weise zugreifen): +**Schnittstellen** (Zugriff auf Ihre Daten nach Ihren Wünschen): -- **[CLI](/de/agenteye/cli-and-agents)**: Steuern Sie Ihre gesamte Deployment vom Terminal oder einem Skript aus, und lassen Sie einen Coding-Agenten dies für Sie in natürlicher Sprache erledigen. -- **[KI-Assistent](/de/agenteye/assistant)**: Stellen Sie Fragen zu Ihren Agenten in natürlicher Sprache, direkt im Dashboard. -- **REST API**: Alles, was Dashboard und CLI tun, wird durch eine REST API unterstützt, die Sie direkt mit einem bereichsbegrenzten [API-Schlüssel](/de/agenteye/api-keys) aufrufen können – Ereignisse erfassen, Sitzungen und Evaluierungen abfragen sowie Dashboards, Alerts, Audits, Benutzer und Schlüssel verwalten, sodass Sie Failproof AI Observability in Ihr eigenes Tooling integrieren können. +- **[CLI](/de/agenteye/cli-and-agents)**: steuern Sie Ihr gesamtes Deployment vom Terminal oder einem Skript aus, und lassen Sie einen Coding-Agenten es für Sie in natürlicher Sprache erledigen. +- **[KI-Assistent](/de/agenteye/assistant)**: stellen Sie Fragen über Ihre Agenten in natürlicher Sprache, direkt im Dashboard. +- **REST API**: alles, was das Dashboard und die CLI tun, wird von einer REST API unterstützt, die Sie direkt mit einem scoped [API-Schlüssel](/de/agenteye/api-keys) aufrufen können – Ereignisse einlesen, Sitzungen und Evaluierungen abfragen sowie Dashboards, Alerts, Audits, Nutzer und Schlüssel verwalten, damit Sie Failproof AI Observability in Ihr eigenes Tooling einbinden können. -**Verwaltung** (für Ihr Team betreiben): +**Admin** (für Ihr Team betreiben): -- **[API-Schlüssel](/de/agenteye/api-keys)**: bereichsbegrenzte Token für den Collector, das Dashboard und den Assistenten. -- **Benutzer**: passwortlose, E-Mail-basierte Anmeldung mit einer Zulassungsliste. -- **Einstellungen**: organisationsweite Konfiguration, einschließlich Modell-Kontextfenster-Überschreibungen. +- **[API-Schlüssel](/de/agenteye/api-keys)**: Scoped-Tokens für den Collector, das Dashboard und den Assistenten. +- **Nutzer**: passwortlose, E-Mail-basierte Anmeldung mit einer Allowlist. +- **Einstellungen**: organisationsweite Konfiguration, einschließlich Überschreibungen des Modell-Kontextfensters. --- ## Wie die Teile zusammenpassen -Daten fließen in eine Richtung, von Ihrem Agenten-Code zum Dashboard: Ihr Agent sendet (über das Python-SDK) Ereignisse an den agenteye-collector, der sie an den Server weiterleitet, der das Dashboard bedient. Zwei optionale Dienste ergänzen das Ganze – ein Scoring-Dienst (Evaluierungen) und ein KI-Assistenten-Dienst (der In-Dashboard-Chat). +Daten fließen in eine Richtung, von Ihrem Agenten-Code zum Dashboard: Ihr Agent (über das Python-SDK) sendet Ereignisse an den agenteye-collector, der sie an den Server weiterleitet, der das Dashboard bereitstellt. Zwei optionale Dienste ergänzen das System – ein Scoring-Dienst (Evaluierungen) und ein KI-Assistenten-Dienst (der Chat im Dashboard). -- **Python SDK**: Sie fügen Ihrem Agenten einige `agenteye.event.*`-Aufrufe hinzu; Ereignisse werden lokal gepuffert. -- **agenteye-collector**: ein schlanker Daemon auf jeder Agenten-Maschine, der Ereignisse bündelt und an den Server sendet. -- **Server**: nimmt Ihre Ereignisse entgegen, verwaltet den Betriebszustand in Ihren eigenen Datenbanken und stellt die REST API bereit, die das Dashboard, die CLI und Ihre eigenen Integrationen verwenden. +- **Python-SDK**: Sie fügen Ihrem Agenten einige `agenteye.event.*`-Aufrufe hinzu; Ereignisse werden lokal gepuffert. +- **agenteye-collector**: ein leichtgewichtiger Daemon auf jeder Agenten-Maschine, der Ereignisse bündelt und an den Server sendet. +- **Server**: nimmt Ihre Ereignisse entgegen, hält den Betriebszustand in Ihren eigenen Datenbanken vor und stellt die REST API bereit, die das Dashboard, die CLI und Ihre eigenen Integrationen verwenden. - **Dashboard**: wo Sie alles erkunden. -- **Optionale Dienste**: ein Scoring-Dienst (Evaluierungen) und ein KI-Assistenten-Dienst (der In-Dashboard-Chat). +- **Optionale Dienste**: ein Scoring-Dienst (Evaluierungen) und ein KI-Assistenten-Dienst (der Chat im Dashboard). -Für das in der gesamten Dokumentation verwendete Vokabular (*Ereignis, Sitzung, Evaluierung, Audit, Befund, Incident*) siehe [Konzepte](/de/agenteye/concepts). +Das in der gesamten Dokumentation verwendete Vokabular (*Ereignis, Sitzung, Evaluierung, Audit, Befund, Vorfall*) finden Sie unter [Konzepte](/de/agenteye/concepts). --- ## Failproof AI Observability erhalten -Failproof AI Observability ist ein Enterprise-Produkt von Failproof AI und funktioniert zusammen mit Failproof AI Enforcement – dem Richtlinien- und Guardrail-Produkt – unter der Failproof AI-Marke. Es läuft vollständig in Ihrer eigenen Umgebung. Wenn Sie noch keinen Zugang zu den Paketen haben, fordern Sie eine Demo an, und wir richten alles für Sie ein: E-Mail an [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Failproof AI Observability ist ein Enterprise-Produkt von Failproof AI und funktioniert zusammen mit Failproof AI Enforcement – dem Richtlinien- und Guardrail-Produkt – unter der Marke Failproof AI. Es läuft vollständig in Ihrer eigenen Umgebung. Wenn Sie noch keinen Zugang zu den Paketen haben, fordern Sie eine Demo an und wir richten Sie ein: E-Mail an [nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- ## Nächste Schritte -- [Konzepte](/de/agenteye/concepts): das Failproof AI Observability-Vokabular an einem Ort. -- [Observability](/de/agenteye/observability): Verfolgen Sie, was Ihre Agenten tun, Durchlauf für Durchlauf. -- [Sicherheit](/de/agenteye/security): Wie Failproof AI Observability Ihre Daten isoliert und unter Ihrer Kontrolle hält. \ No newline at end of file +- [Konzepte](/de/agenteye/concepts): das Failproof AI Observability-Vokabular auf einen Blick. +- [Observability](/de/agenteye/observability): verfolgen Sie, was Ihre Agenten tun, Durchlauf für Durchlauf. +- [Sicherheit](/de/agenteye/security): wie Failproof AI Observability Ihre Daten isoliert und in Ihrer Kontrolle hält. \ No newline at end of file diff --git a/docs/de/agenteye/python-sdk-skill.mdx b/docs/de/agenteye/python-sdk-skill.mdx index 637dc1ac..ffddef7c 100644 --- a/docs/de/agenteye/python-sdk-skill.mdx +++ b/docs/de/agenteye/python-sdk-skill.mdx @@ -1,55 +1,55 @@ --- title: "Failproof AI Observability Python SDK Agent Skill" -description: "Von einem nicht instrumentierten Agenten zu sichtbaren Events – Ihr Coding-Agent findet die Instrumentierungspunkte, implementiert sie und beweist, dass sie korrekt funktionieren." +description: "Von einem nicht instrumentierten Agenten zu sichtbaren Events – Ihr Coding-Agent findet die Instrumentierungspunkte, schreibt sie und beweist, dass sie ankommen." --- -Sagen Sie Ihrem Coding-Agenten *„Füge Failproof AI Observability zu diesem Agenten hinzu"* und lassen Sie ihn Ihre Schleife lesen, die richtigen Instrumentierungspunkte ermitteln, den Code schreiben und die Events verifizieren – bevor er die Aufgabe als erledigt markiert. +Sagen Sie Ihrem Coding-Agenten *„Füge Failproof AI Observability zu diesem Agenten hinzu"* und lassen Sie ihn Ihre Schleife lesen, die richtigen Instrumentierungspunkte ermitteln, den Code schreiben und die Events verifizieren, bevor er die Aufgabe als erledigt erklärt. -Der **Python SDK Skill** (`agenteye-python-sdk`) ist ein *Agent Skill*: ein Ordner mit Anweisungen, den ein Coding-Agent wie Claude Code oder Codex bei Bedarf lädt, wenn eine Aufgabe dazu passt. Er bringt dem Agenten bei, das [Python SDK](/de/agenteye/python-sdk) zu verwenden – er ist keine Bibliothek und ändert nichts an der Funktionsweise des SDK. +Der **Python SDK Skill** (`agenteye-python-sdk`) ist ein *Agent Skill*: ein Ordner mit Anweisungen, den ein Coding-Agent wie Claude Code oder Codex bei Bedarf lädt, wenn eine Aufgabe dazu passt. Er bringt dem Agenten den Umgang mit dem [Python SDK](/de/agenteye/python-sdk) bei – er ist keine Bibliothek und ändert nichts an der Funktionsweise des SDKs. -## Instrumentierung ist leicht zu schreiben – und leicht still falsch zu machen +## Instrumentierung: leicht zu schreiben, leicht still zu verpatzen -Das SDK ist klein: dreizehn Event-Methoden, alle ausschließlich als Keyword-Argumente. Ein Coding-Agent kann die [Python SDK](/de/agenteye/python-sdk)-Referenz lesen und in einer Minute plausible Instrumentierung produzieren. +Das SDK ist klein: dreizehn Event-Methoden, alle mit ausschließlich Keyword-Argumenten. Ein Coding-Agent kann die [Python SDK](/de/agenteye/python-sdk)-Referenz lesen und in einer Minute plausibel klingende Instrumentierung produzieren. -Das Problem ist, dass dieses SDK keinen Fehler wirft, wenn etwas falsch ist – und falsche Instrumentierung sieht genauso aus wie richtige Instrumentierung, bis jemand ein Dashboard öffnet und es leer vorfindet. Die Fehler, die wirklich Zeit kosten, sind allesamt stille: +Der Haken: Dieses SDK wirft keine Ausnahme, wenn etwas falsch läuft – und falsche Instrumentierung sieht genauso aus wie richtige, bis jemand ein Dashboard öffnet und es leer vorfindet. Die Fehler, die wirklich Zeit kosten, sind allesamt stille Fehler: | Der Fehler | Was Sie sehen | |---|---| | Kein `agent_start` | Alle Events landen. Null Sessions. | -| Environment nie gesetzt | Alles funktioniert, wird unter `dev` abgelegt. | -| `outcome="failure"` | Der Lauf zeigt grün – nur `failed`, `error`, `timeout`, `rejected` zählen. | -| Tippfehler im Feldnamen | Akzeptiert und als neues Feld gespeichert. | -| Events aus einem Thread-Pool emittiert | Werden still verworfen. | +| Environment nie gesetzt | Alles funktioniert, wird aber unter `dev` abgelegt. | +| `outcome="failure"` | Der Lauf erscheint grün – nur `failed`, `error`, `timeout`, `rejected` zählen. | +| Tippfehler im Feldnamen | Wird akzeptiert und als neues Feld gespeichert. | +| Events aus einem Thread-Pool gesendet | Werden stillschweigend verworfen. | -Keiner davon wirft einen Fehler. Keiner taucht in Tests auf. Jeder einzelne ist im Skill dokumentiert – als Vertrag zusammen mit dem Check, der ihn erkennt. +Keiner davon wirft eine Ausnahme. Keiner taucht in Tests auf. Jeder einzelne ist im Skill erfasst – als Vertrag mit der Prüfung, die ihn aufdeckt. ## Was der Skill tut – der Reihe nach -Der Skill durchläuft dieselben drei Schritte, die ein sorgfältiger Entwickler gehen würde: +Der Skill führt dieselben drei Schritte aus, die ein sorgfältiger Entwickler durchführen würde: -1. **Planen.** Er liest Ihre Agenten-Schleife und stellt die zwei Fragen, die nur Sie beantworten können: Was zählt als ein Lauf (Ihre `session_id`), und wer sind die unterscheidbaren Akteure (Ihre `agent_id`)? Das wird geklärt, bevor Code geschrieben wird – denn eine spätere Änderung spaltet Ihre Historie und bricht die Trends. -2. **Schreiben.** Er bindet die Identität einmal pro Lauf statt sie durch jede Aufrufstelle durchzufädeln, und wählt eine nebenläufigkeitssichere Form – ein Detail, das wichtig ist, weil die naheliegende Abkürzung zwei überlappende Läufe stillschweigend in einer einzigen Session vermischt. -3. **Verifizieren.** Er führt Ihren Agenten aus und liest die entstandenen Event-Dateien, prüft ob `agent_start` vorhanden ist, das Environment stimmt und ein Lauf genau eine Session erzeugt hat. +1. **Planen.** Er liest Ihre Agentenschleife und stellt die zwei Fragen, die nur Sie beantworten können: Was gilt als ein Lauf (Ihre `session_id`), und wer sind die unterscheidbaren Akteure (Ihre `agent_id`)? Diese Punkte werden vor dem Schreiben von Code geklärt, denn eine spätere Umbenennung spaltet den Verlauf und zerstört die Trends. +2. **Schreiben.** Er bindet die Identität einmal pro Lauf, anstatt sie durch jede Aufrufstelle zu fädeln, und wählt eine nebenläufigkeitssichere Form – ein Detail, das wichtig ist, denn die naheliegende Abkürzung mischt zwei gleichzeitige Läufe stillschweigend in eine Session. +3. **Verifizieren.** Er startet Ihren Agenten und liest die erzeugten Event-Dateien, um zu prüfen, dass `agent_start` vorhanden ist, die Umgebung stimmt und ein Lauf genau eine Session erzeugt hat. -Dieser dritte Schritt ist der, den die meisten überspringen. Das SDK schreibt Events in lokale Dateien, sodass eine vollständige Integration auf einem Laptop bewiesen werden kann – ohne Server, ohne API-Key, ohne Netzwerk. Genau deshalb besteht der Skill darauf, diesen Schritt durchzuführen. +Dieser dritte Schritt ist der, den die meisten überspringen. Das SDK schreibt Events in lokale Dateien, sodass eine vollständige Integration auf einem Laptop ohne Server, ohne API-Key und ohne Netzwerkzugang nachgewiesen werden kann – genau deshalb besteht der Skill darauf, es zu tun. -## Verhältnis zu den anderen Skills +## Abgrenzung zu den anderen Skills Drei Skills, eine klare Aufteilung: -| Skill | Einsetzen wenn | Was er berührt | +| Skill | Greifen Sie darauf zurück, wenn | Was er anfasst | |---|---|---| -| **Python SDK Skill** (diese Seite) | Sie möchten, dass Ihr Agent Telemetrie *emittiert* – „Observability hinzufügen", „Warum erscheint mein Agent nicht?" | Schreibt Code in Ihrem Agenten-Repo. Liest nichts. | -| **[Evaluator Skill](/de/agenteye/evaluator-skill)** | Sie möchten Läufe *bewerten* – „Was sollen wir überhaupt messen?" | Schreibt Code in Ihrem Repo; liest Telemetrie | -| **[CLI Skill](/de/agenteye/cli-skill)** | Sie möchten *nachlesen*, was passiert ist, oder Ihr Deployment betreiben | Steuert die CLI als Sie, inklusive Änderungen | +| **Python SDK Skill** (diese Seite) | Sie möchten, dass Ihr Agent Telemetrie *sendet* – „Observability hinzufügen", „Warum taucht mein Agent nicht auf?" | Schreibt Code in Ihr Repo. Liest nichts. | +| **[Evaluator Skill](/de/agenteye/evaluator-skill)** | Sie möchten Läufe *bewerten* – „Was sollen wir überhaupt messen?" | Schreibt Code in Ihr Repo; liest Telemetrie. | +| **[CLI Skill](/de/agenteye/cli-skill)** | Sie möchten *nachlesen*, was passiert ist, oder Ihr Deployment steuern | Bedient die CLI in Ihrem Namen, einschließlich Änderungen. | -Die Übergabe erfolgt in dieser Reihenfolge: Dieser Skill bringt Events zum Fließen, der Evaluator bewertet sie, die CLI liest sie aus. Es gibt nichts zu bewerten und nichts zu lesen, bis Ihr Agent Sessions emittiert – wenn Sie von vorne beginnen, fangen Sie hier an. +Sie greifen in dieser Reihenfolge ineinander: Dieser Skill bringt Events zum Fließen, der Evaluator bewertet sie, die CLI liest sie zurück. Es gibt nichts zu bewerten und nichts zu lesen, solange Ihr Agent keine Sessions sendet – wenn Sie bei null anfangen, fangen Sie hier an. ## Voraussetzungen -1. **Python 3.10+** und die Agenten-Codebasis, die Sie instrumentieren möchten. -2. **Das SDK.** Es wird an Kunden als privates Wheel ausgeliefert und nicht über einen öffentlichen Index – Ihr Onboarding erklärt, wie Sie es beziehen und installieren. Der Skill kennt den Installationspfad und fragt Sie, anstatt zu raten, falls er ihn nicht finden kann. -3. **Nichts weiter.** Kein Dashboard-Login, kein API-Key, kein Netzwerk. Der Skill verifiziert anhand der Event-Dateien, die das SDK schreibt, und kann seine Arbeit offline abschließen und beweisen. +1. **Python 3.10+** und die Codebase des Agenten, den Sie instrumentieren möchten. +2. **Das SDK.** Es wird Kunden als privates Wheel-Paket und nicht über einen öffentlichen Index bereitgestellt – Ihr Onboarding erklärt, wie Sie es erhalten und installieren. Der Skill kennt den Installationspfad und fragt nach, anstatt zu raten, falls er ihn nicht findet. +3. **Sonst nichts.** Kein Dashboard-Login, kein API-Key, kein Netzwerk. Der Skill verifiziert anhand der Event-Dateien, die das SDK schreibt, und kann seine Arbeit vollständig offline abschließen und nachweisen. ## Bezugsquelle @@ -63,12 +63,12 @@ Fügen Sie `-g` hinzu, um ihn für alle Projekte statt nur das aktuelle zu insta ## Manuelle Installation -Agent Skills sind Ordner, die eine `SKILL.md` plus Referenzen enthalten. Falls Sie den Installer nicht verwenden möchten: +Agent Skills sind Ordner, die eine `SKILL.md` und Referenzen enthalten. Falls Sie den Installer nicht verwenden möchten: -- **Claude Code**: Kopieren Sie den Ordner `agenteye-python-sdk/` nach `~/.claude/skills/` (alle Projekte) oder `/.claude/skills/` (nur dieses Repo). Claude Code erkennt ihn automatisch – prüfen Sie die `/skills`-Liste oder fragen Sie einfach etwas, das dazu passt. -- **Codex**: Codex liest dieselbe `SKILL.md`. Das mitgelieferte `agents/openai.yaml` setzt `allow_implicit_invocation: true`, sodass er automatisch gewählt wird, wenn eine Aufgabe passt; andernfalls rufen Sie ihn als `$agenteye-python-sdk` auf. +- **Claude Code**: Kopieren Sie den Ordner `agenteye-python-sdk/` nach `~/.claude/skills/` (für alle Projekte) oder `/.claude/skills/` (nur für dieses Repo). Claude Code erkennt ihn automatisch – prüfen Sie die `/skills`-Liste oder fragen Sie einfach etwas, das dazu passt. +- **Codex**: Codex liest dieselbe `SKILL.md`. Die mitgelieferte `agents/openai.yaml` setzt `allow_implicit_invocation: true`, sodass er automatisch ausgewählt wird, wenn eine Aufgabe passt; andernfalls rufen Sie ihn als `$agenteye-python-sdk` auf. -Führen Sie Ihren Agenten **im Repository mit dem Code aus, den Sie instrumentieren möchten** – der Skill liest Ihre Agenten-Schleife, bevor er etwas vorschlägt. +Starten Sie Ihren Agenten **im Repository mit dem Code, den Sie instrumentieren möchten** – der Skill liest Ihre Agentenschleife, bevor er etwas vorschlägt. ## Wie eine Session aussieht @@ -103,29 +103,29 @@ agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and Want me to fix those too? ``` -Das Muster, das auffällt: Er hat den Code gelesen, bevor er etwas vorschlug, nur die Fragen gestellt, die Sie beantworten können, eine bereits vorhandene ID wiederverwendet, die nebenläufigkeitssichere Form gewählt *weil* er einen Thread-Pool sah, und **durch Lesen der tatsächlichen Events verifiziert** statt einfach Erfolg zu erklären – und dann die eine Stelle markiert, von der er wusste, dass sie still versagen würde. +Das Muster, das es zu beachten gilt: Er hat den Code gelesen, bevor er etwas vorgeschlagen hat, nur die Fragen gestellt, die Sie allein beantworten können, eine bereits vorhandene ID wiederverwendet, die nebenläufigkeitssichere Form gewählt, *weil* er den Thread-Pool gesehen hat, und **durch Lesen der tatsächlichen Events verifiziert** statt einfach Erfolg zu erklären – und dann die eine Stelle markiert, von der er wusste, dass sie still versagen würde. ## Was Sie ihn fragen können -- *„Warum erscheint mein Agent nicht im Dashboard?"* → Geht die Leiter hinab: Werden Events geschrieben, ist `agent_start` vorhanden, stimmt das Environment, liest der Collector am richtigen Ort? -- *„Alles landet unter dev."* → Das Environment wurde nie gesetzt oder durch einen späteren Aufruf zurückgesetzt. -- *„Token-Tracking hinzufügen."* → Findet Ihren LLM-Wrapper und erfasst Modell, Stop-Grund und Nutzung. -- *„Auch die Sub-Agenten instrumentieren."* → Eine Session, eindeutige Agenten-Labels, verschachtelt unter ihrem Elternteil. +- *„Warum taucht mein Agent nicht im Dashboard auf?"* → Geht die Leiter hoch: Werden Events geschrieben, ist `agent_start` vorhanden, stimmt die Umgebung, liest der Collector vom gleichen Ort? +- *„Alles landet unter dev."* → Die Umgebung wurde nie gesetzt oder durch einen späteren Aufruf zurückgesetzt. +- *„Token-Tracking hinzufügen."* → Findet Ihren LLM-Wrapper und erfasst Modell, Stop-Grund und Verwendung. +- *„Auch die Sub-Agenten instrumentieren."* → Eine Session, unterschiedliche Agent-Labels, verschachtelt unter dem übergeordneten Agenten. - *„Tests für die Instrumentierung schreiben."* → Zeigt das SDK auf ein temporäres Verzeichnis und macht Assertions auf die geschriebenen Events. ## Worauf Sie achten sollten -**Lassen Sie ihn verifizieren.** Der Schritt, der diesen Skill wertvoll macht, ist der letzte – Ihren Agenten ausführen und die Events zurücklesen. Ein Agent, der Instrumentierung schreibt und dann aufhört, hat die einfache Hälfte erledigt; die Hälfte, die still versagt, ist die andere. +**Lassen Sie ihn verifizieren.** Der Schritt, der diesen Skill wertvoll macht, ist der letzte – den Agenten starten und die Events zurücklesen. Ein Agent, der Instrumentierung schreibt und dann aufhört, hat die leichte Hälfte erledigt; die Hälfte, die still versagt, ist die andere. -**Namen vereinbaren, bevor Code geschrieben wird.** `session_id` und `agent_id` sind die Achsen, nach denen jede Oberfläche gruppiert. Sie später umzubenennen spaltet die Historie: Alte Läufe behalten die alten Labels und Ihre Trends brechen. Der Skill wird fragen; die Antwort ist eine Minute Nachdenken wert. +**Namen vor dem Code festlegen.** `session_id` und `agent_id` sind die Achsen, nach denen jede Oberfläche gruppiert. Eine spätere Umbenennung spaltet den Verlauf: Alte Läufe behalten die alten Labels und Ihre Trends brechen zusammen. Der Skill wird fragen; die Antwort ist eine Minute Nachdenken wert. -**Wenn Ihr Agent vorschlägt, das SDK von einem öffentlichen Index zu installieren, wurde der Skill nicht geladen.** Das SDK wird privat vertrieben. Dieser Vorschlag ist ein zuverlässiges Zeichen dafür, dass Ihr Coding-Agent rät statt dem Skill zu folgen – stoppen Sie ihn dort und prüfen Sie, ob der Skill installiert ist. +**Wenn Ihr Agent vorschlägt, das SDK von einem öffentlichen Index zu installieren, wurde der Skill nicht geladen.** Das SDK wird privat vertrieben. Dieser Vorschlag ist ein verlässliches Zeichen dafür, dass Ihr Coding-Agent rät, anstatt dem Skill zu folgen – stoppen Sie ihn dort und prüfen Sie, ob der Skill installiert ist. -Abgesehen davon ist der Wirkungsbereich überschaubar: Er schreibt Code in Ihrem Arbeitsverzeichnis und Event-Dateien dort, wo Sie es angeben. Er liest nichts aus Ihrem Deployment und ändert nichts daran. +Abgesehen davon ist der Wirkungsbereich überschaubar: Der Skill schreibt Code in Ihr Arbeitsverzeichnis und Event-Dateien dorthin, wo Sie es angeben. Er liest nichts von Ihrem Deployment und ändert nichts daran. ## Nächste Schritte - **[Python SDK](/de/agenteye/python-sdk)**: Die vollständige Event-Referenz – jeder Event-Typ und jedes Feld – hinter dem, was dieser Skill automatisiert. -- **[Sessions](/de/agenteye/sessions)**: Was Ihre Instrumentierung produziert, sobald Events ankommen. +- **[Sessions](/de/agenteye/sessions)**: Was Ihre Instrumentierung erzeugt, sobald Events ankommen. - **[Evaluator Agent Skill](/de/agenteye/evaluator-skill)**: Der nächste Schritt, sobald Läufe ankommen – ihre Bewertung. - **[CLI Agent Skill](/de/agenteye/cli-skill)**: Ihre Telemetrie zurücklesen. \ No newline at end of file diff --git a/docs/de/agenteye/python-sdk.mdx b/docs/de/agenteye/python-sdk.mdx index fbbcf938..3b427503 100644 --- a/docs/de/agenteye/python-sdk.mdx +++ b/docs/de/agenteye/python-sdk.mdx @@ -1,12 +1,12 @@ --- title: "Python SDK" -description: "Beobachte genau, was deine KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff." +description: "Sehen Sie genau, was Ihre KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff." --- -Beobachte genau, was deine KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff. Das Failproof AI Observability Python SDK zeichnet diesen Verlauf direkt aus deinem Agenten-Code auf, damit du debuggen, auditieren und nachvollziehen kannst, was passiert ist. Verwende es immer dann, wenn Failproof AI Observability deine Agenten beobachten soll. +Sehen Sie genau, was Ihre KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff. Das Failproof AI Observability Python SDK zeichnet diesen Verlauf direkt in Ihrem Agenten-Code auf, damit Sie debuggen, auditieren und nachvollziehen können, was passiert ist. Verwenden Sie es immer dann, wenn Failproof AI Observability Ihre Agenten beobachten soll. -Intern schreibt das SDK strukturierte Events in lokale JSONL-Dateien, und der Collector-Daemon liest diese und überträgt sie automatisch an die Plattform. Du musst diese Dateien nicht selbst verwalten. +Intern schreibt das SDK strukturierte Events in lokale JSONL-Dateien, und der Collector-Daemon liest diese ein und übermittelt sie automatisch an die Plattform. Sie müssen diese Dateien nicht selbst verwalten. > **Tipp:** Neu bei Failproof AI Observability? Diese Seite ist die vollständige SDK-Event-Referenz. @@ -18,15 +18,15 @@ Intern schreibt das SDK strukturierte Events in lokale JSONL-Dateien, und der Co ## Installation -Das SDK wird Kunden als privates Wheel und nicht über einen öffentlichen Paketindex bereitgestellt. Dein Onboarding erklärt, wie du es erhältst, installierst und versionierst — wende dich an deinen Failproof AI-Ansprechpartner, wenn du Zugang benötigst. +Das SDK wird Kunden als privates Wheel und nicht über einen öffentlichen Paketindex bereitgestellt. Ihr Onboarding erklärt, wie Sie es beziehen, installieren und pinnen – wenden Sie sich an Ihren Failproof AI-Kontakt, wenn Sie Zugang benötigen. -Sobald es installiert ist, überprüfe die Installation: +Sobald es installiert ist, bestätigen Sie die Installation: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Möchtest du die gesamte Integration von einem Coding-Agent erledigen lassen? Der [Python SDK Agent Skill](/de/agenteye/python-sdk-skill) kennt den Installationspfad, plant die Instrumentierungspunkte, schreibt sie und überprüft, ob die Events ankommen. +Möchten Sie die gesamte Integration lieber von einem Coding-Agenten erledigen lassen? Der [Python SDK Agent Skill](/de/agenteye/python-sdk-skill) kennt den Installationspfad, plant die Instrumentierungspunkte, implementiert sie und verifiziert, dass die Events ankommen. --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Einen echten Aufruf instrumentieren -In der Praxis umhüllst du deinen bestehenden Agenten-Code. Klammere einen Modellaufruf mit `model_request` davor und `model_response` danach ein, sodass die beiden Events die echte Anfrage umspannen und Failproof AI Observability sie zuordnen kann: +In der Praxis umhüllen Sie Ihren bestehenden Agenten-Code. Klammern Sie einen Modellaufruf mit `model_request` davor und `model_response` danach ein, damit die beiden Events die tatsächliche Anfrage umspannen und Failproof AI Observability sie einander zuordnen kann: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Umhülle Tool-Aufrufe auf dieselbe Weise mit `tool_use` und `tool_result`, wobei du eine `tool_call_id` für beide Events verwendest. +Umhüllen Sie Tool-Aufrufe auf dieselbe Weise mit `tool_use` und `tool_result`, und verwenden Sie eine gemeinsame `tool_call_id` für beide. -So sehen diese Events aus, sobald sie das Dashboard erreichen — farblich nach Typ kodiert und filterbar nach Umgebung, Agent und Session: +So sehen diese Events aus, sobald sie das Dashboard erreichen – farbkodiert nach Typ und filterbar nach Umgebung, Agent und Session: -![Der Live-Events-Stream, farblich nach Event-Typ kodiert und filterbar nach Umgebung, Agent und Session](/agenteye/images/events-stream.png) +![Der Live-Events-Stream, farbkodiert nach Event-Typ und filterbar nach Umgebung, Agent und Session](/agenteye/images/events-stream.png) --- @@ -113,18 +113,18 @@ agenteye.configure( ) ``` -Einmalig vor jedem `event.*`-Aufruf aufrufen. Kann weggelassen werden; die Standardwerte funktionieren sofort. Alle Argumente sind nur als Schlüsselwortargumente zulässig; übergib sie wie oben gezeigt mit Namen. +Einmalig vor dem ersten `event.*`-Aufruf aufrufen. Das Weglassen ist sicher; die Standardwerte funktionieren sofort. Alle Argumente sind nur als Schlüsselwortargumente zulässig; übergeben Sie sie wie oben gezeigt mit Namen. -Wenn `base_dir` `None` ist (Standard), liest das SDK `$AGENTEYE_HOME` falls gesetzt, -andernfalls wird auf `~/.agenteye` zurückgefallen. Dies entspricht der eigenen Auflösung des Collectors, -sodass eine einzige `AGENTEYE_HOME`-Umgebungsvariable den gemeinsamen Event-Spool für -SDK und Collector konfiguriert. +Wenn `base_dir` `None` ist (der Standard), liest das SDK `$AGENTEYE_HOME`, falls gesetzt, +und fällt andernfalls auf `~/.agenteye` zurück. Dies entspricht der eigenen Auflösung des Collectors, +sodass eine einzelne `AGENTEYE_HOME`-Umgebungsvariable den gemeinsamen Event-Spool für +das SDK und den Collector konfiguriert. --- ## Umgebung -Zeichne jedes Event mit einer Deployment-Umgebung aus (`production`, `staging`, `qa`, `canary` usw.). Einmalig setzen; das SDK hängt sie automatisch an jedes Event an. +Versehen Sie jedes Event mit einem Deployment-Environment-Label (`production`, `staging`, `qa`, `canary` usw.). Einmal festgelegt, hängt das SDK es automatisch an jedes Event an. **Option 1: über `configure()`:** @@ -132,33 +132,33 @@ Zeichne jedes Event mit einer Deployment-Umgebung aus (`production`, `staging`, agenteye.configure(environment="production") ``` -**Option 2: über eine Umgebungsvariable:** +**Option 2: über Umgebungsvariable:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**Priorität:** `configure(environment=...)` hat Vorrang vor der Umgebungsvariable. Wenn keines von beiden gesetzt ist, wird standardmäßig `"dev"` verwendet. +**Priorität:** `configure(environment=...)` hat Vorrang vor der Umgebungsvariable. Wenn keines von beidem gesetzt ist, wird `"dev"` als Standard verwendet. -Der Umgebungswert erscheint als erstklassiger Filter im Dashboard und wird serverseitig für schnelle Abfragen gespeichert. +Der Environment-Wert erscheint als erstklassiger Filter im Dashboard und wird für schnelle Abfragen auf dem Server gespeichert. -> **Warnung:** Umgebungswerte dürfen kein literales `,` Komma enthalten. Die Dashboard-Filter verwenden kommagetrennte Mehrfachauswahl in der URL (`?environment=prod,staging`), sodass eine Umgebung namens `prod,blue` in zwei Werte aufgeteilt würde. Events mit kommaenthaltenden Umgebungswerten werden beim Einlesen abgelehnt. +> **Warnung:** Environment-Werte dürfen kein literales `,`-Komma enthalten. Die Dashboard-Filter verwenden kommagetrennte Mehrfachauswahl in der URL (`?environment=prod,staging`), sodass ein Environment namens `prod,blue` in zwei Werte aufgeteilt würde. Events mit Komma enthaltenden Environments werden beim Ingest abgelehnt. --- ## Daten und Datenschutz -Das SDK zeichnet nur die Felder auf, die du explizit übergibst. Prompts, Nachrichten, Tool-Eingaben und -Ausgaben sowie Modell-Inhalte werden ausschließlich deshalb erfasst, weil du sie an einen `event.*`-Aufruf übergibst. Es werden keine Informationen aus deinem Prozess gelesen oder implizit erfasst. Jedes Feld, das du nicht setzt, wird vollständig aus dem Event weggelassen und nicht auf Festplatte geschrieben. +Das SDK zeichnet nur die Felder auf, die Sie explizit übergeben. Prompts, Nachrichten, Tool-Eingaben und -Ausgaben sowie Modell-Inhalte werden ausschließlich erfasst, weil Sie sie an einen `event.*`-Aufruf übergeben. Aus Ihrem Prozess wird nichts gelesen oder implizit erfasst. Jedes Feld, das Sie nicht setzen, wird vollständig aus dem Event weggelassen und nicht auf die Festplatte geschrieben. -Das macht die Bereinigung zu deiner Wahl und Verantwortung. Wenn ein Prompt oder ein Tool-Payload personenbezogene Daten oder Secrets enthält, die du nicht speichern möchtest, entferne oder maskiere sie, bevor du sie an die Event-Methode übergibst. +Das macht die Schwärzung zu Ihrer Entscheidung und Ihrer Verantwortung. Wenn ein Prompt oder eine Tool-Nutzlast personenbezogene Daten oder Geheimnisse enthält, die Sie nicht speichern möchten, entfernen oder maskieren Sie diese, bevor Sie sie an die Event-Methode übergeben. --- ## Event-Referenz -Die meisten Events kommen in Start-/End-Paaren, die eine Korrelations-ID teilen: `tool_use` und `tool_result` teilen eine `tool_call_id`, `hook_triggered` und `hook_completed` teilen eine `hook_id`, und `human_wait` und `human_input` teilen eine `input_id`. Sende das Start-Event, führe die Arbeit aus und sende dann das End-Event mit derselben ID. Failproof AI Observability ordnet das Paar zu und berechnet `duration_ms` für dich, sodass du `duration_ms` nie selbst übergibst. +Die meisten Events kommen in Start/Ende-Paaren, die eine Korrelations-ID teilen: `tool_use` und `tool_result` teilen eine `tool_call_id`, `hook_triggered` und `hook_completed` teilen eine `hook_id`, und `human_wait` und `human_input` teilen eine `input_id`. Senden Sie das Start-Event, führen Sie die Arbeit durch und senden Sie dann das Ende-Event mit derselben ID. Failproof AI Observability ordnet das Paar zu und berechnet `duration_ms` für Sie, sodass Sie `duration_ms` nie selbst übergeben müssen. -![Der git-artige Ausführungsgraph einer Session neben ihrer Event-Zeitleiste, aus den gepaarten Events rekonstruiert, mit dem Tool/Modell/Hook-Aufschlüsselungspanel](/agenteye/images/session-detail.png) +![Ein git-artiger Ausführungsgraph einer Session neben ihrer Event-Timeline, rekonstruiert aus den gepaarten Events, mit dem Tool/Modell/Hook-Aufschlüsselungspanel](/agenteye/images/session-detail.png) Alle Event-Methoden erfordern diese zwei Felder: @@ -173,7 +173,7 @@ Alle Methoden akzeptieren auch beliebige `**kwargs` für benutzerdefinierte Meta ### `event.agent_start()` -Wird ausgelöst, wenn ein Agent die Arbeit beginnt. +Wird ausgelöst, wenn ein Agent mit der Arbeit beginnt. ```python agenteye.event.agent_start( @@ -188,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Wird ausgelöst, wenn ein Agent die Arbeit beendet. +Wird ausgelöst, wenn ein Agent die Arbeit abschließt. ```python agenteye.event.agent_end( @@ -203,7 +203,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Wird ausgelöst, wenn ein Agent ein Tool aufruft. Wird mit `tool_result` gepaart; das SDK berechnet `duration_ms` automatisch. +Wird ausgelöst, wenn ein Agent ein Tool aufruft. Paarweise mit `tool_result` verwenden; das SDK berechnet `duration_ms` automatisch. ```python agenteye.event.tool_use( @@ -237,7 +237,7 @@ agenteye.event.tool_result( ### `event.model_request()` -Wird ausgelöst, unmittelbar bevor ein Prompt an ein LLM gesendet wird. +Wird kurz vor dem Senden eines Prompts an ein LLM ausgelöst. ```python agenteye.event.model_request( @@ -254,7 +254,7 @@ agenteye.event.model_request( ) ``` -`messages`-Einträge akzeptieren entweder einen einfachen String als `content` oder Anthropic-artige Listen von Content-Blöcken als `content`. Sampling-Parameter (`temperature`, `max_tokens` usw.) können als zusätzliche kwargs übergeben werden. +`messages`-Einträge akzeptieren entweder einen einfachen String als `content` oder Anthropic-artigen Listen-von-Blöcken-`content`. Sampling-Parameter (`temperature`, `max_tokens` usw.) können als zusätzliche kwargs übergeben werden. --- @@ -283,7 +283,7 @@ agenteye.event.model_response( ### `event.hook_triggered()` -Wird ausgelöst, wenn ein Hook feuert. Wird mit `hook_completed` gepaart; das SDK berechnet `duration_ms` automatisch. +Wird ausgelöst, wenn ein Hook feuert. Paarweise mit `hook_completed` verwenden; das SDK berechnet `duration_ms` automatisch. ```python agenteye.event.hook_triggered( @@ -335,11 +335,11 @@ agenteye.event.error( ## Human-in-the-Loop-Events -Human-in-the-Loop-Events geben dir Kontrolle über die Momente, in denen eine Person in die Ausführung des Agenten eingreift (auf Genehmigung warten, Eingaben liefern, pausieren oder den Agenten stoppen). Sie ermöglichen es dir zu messen, wie lange Menschen für eine Antwort benötigen (das SDK berechnet `duration_ms` bei gepaarten Events automatisch), zu auditieren, wer einen Agenten pausiert oder unterbrochen hat, sowie Genehmigungs- und Aufsichts-Workflows aufzubauen, die im Dashboard sichtbar sind. +Human-in-the-Loop-Events geben Ihnen Aufsicht über die Momente, in denen eine Person in die Ausführung des Agenten eingreift (warten auf Genehmigung, Eingaben bereitstellen, pausieren oder den Agenten stoppen). Sie ermöglichen es Ihnen zu messen, wie lange Menschen für eine Reaktion benötigen (das SDK berechnet `duration_ms` bei gepaarten Events automatisch), zu auditieren, wer einen Agenten pausiert oder unterbrochen hat, und Genehmigungs- und Aufsichts-Workflows zu erstellen, die im Dashboard angezeigt werden. ### `event.human_wait()` -Wird ausgelöst, wenn der Agent die Ausführung pausiert, um auf eine menschliche Eingabe zu warten. Wird mit `human_input` gepaart; das SDK berechnet `duration_ms` automatisch (wie lange der Mensch für eine Antwort brauchte). +Wird ausgelöst, wenn der Agent die Ausführung anhält, um auf eine menschliche Eingabe zu warten. Paarweise mit `human_input` verwenden; das SDK berechnet `duration_ms` automatisch (wie lange der Mensch für eine Antwort gebraucht hat). ```python agenteye.event.human_wait( @@ -354,7 +354,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Wird ausgelöst, wenn ein Mensch eine Eingabe macht und der Agent fortfährt. Korreliert mit `human_wait` über `input_id`. `duration_ms` wird automatisch berechnet und darf nicht vom Aufrufer übergeben werden. +Wird ausgelöst, wenn ein Mensch eine Eingabe macht und der Agent fortsetzt. Korreliert mit `human_wait` über `input_id`. `duration_ms` wird automatisch berechnet und darf nicht vom Aufrufer übergeben werden. ```python agenteye.event.human_input( @@ -368,7 +368,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Wird ausgelöst, wenn ein Mensch den Agenten aktiv pausiert (z. B. über eine Dashboard-Steuerung). Der Agent wird ausgesetzt, aber nicht beendet. +Wird ausgelöst, wenn ein Mensch den Agenten aktiv pausiert (z. B. über ein Dashboard-Steuerelement). Der Agent wird angehalten, aber nicht beendet. ```python agenteye.event.human_pause( @@ -381,7 +381,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -Wird ausgelöst, wenn ein Mensch den Agenten mitten in der Ausführung aktiv stoppt. Im Gegensatz zu `human_pause` wird die Arbeit des Agenten beendet und nicht nur ausgesetzt. +Wird ausgelöst, wenn ein Mensch den Agenten mitten in der Ausführung aktiv stoppt. Im Gegensatz zu `human_pause` wird die Arbeit des Agenten beendet und nicht nur angehalten. ```python agenteye.event.human_interrupt( @@ -410,27 +410,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` und `environment` sind reserviert und lösen einen `ValueError` aus (`Reserved field names cannot be used as custom fields: [...]`), wenn sie als benutzerdefinierte Felder übergeben werden. `session_id` und `agent_id` sind erforderliche Parameter bei jeder Event-Methode und können nicht ein zweites Mal übergeben werden; Python löst einen `TypeError` aus, wenn du es versuchst. Setze die Umgebung mit `configure(environment=...)` (oder der `AGENTEYE_ENVIRONMENT`-Variable). +`timestamp`, `type` und `environment` sind reserviert und lösen einen `ValueError` aus (`Reserved field names cannot be used as custom fields: [...]`), wenn sie als benutzerdefinierte Felder übergeben werden. `session_id` und `agent_id` sind Pflichtparameter bei jeder Event-Methode und können nicht ein zweites Mal übergeben werden; Python löst einen `TypeError` aus, wenn Sie dies versuchen. Legen Sie die Umgebung stattdessen mit `configure(environment=...)` (oder der `AGENTEYE_ENVIRONMENT`-Variable) fest. -Halte Payloads als strukturiertes JSON, wenn du ihre Felder abfragen möchtest. Werte, die JSON nicht nativ unterstützt — wie Datetimes, UUIDs, Dezimalzahlen, Sets, Bytes oder Modell-Objekte — werden in Strings umgewandelt, damit die Aufzeichnung sicher fortgesetzt werden kann. +Verwenden Sie für Nutzdaten strukturiertes JSON, wenn Sie deren Felder abfragen möchten. Werte, die JSON nicht nativ unterstützt – wie Datetimes, UUIDs, Dezimalzahlen, Sets, Bytes oder Modellobjekte – werden in Strings konvertiert, damit die Aufzeichnung sicher fortgesetzt werden kann. --- -## Wie Events geschrieben werden +## So werden Events geschrieben -Events werden im Prozess gepuffert und alle `flush_interval` Sekunden auf Festplatte geschrieben (Standard: 500 ms). Jeder Flush schreibt eine JSONL-Datei: +Events werden prozessintern gepuffert und alle `flush_interval` Sekunden auf die Festplatte geschrieben (Standard: 500 ms). Jeder Flush schreibt eine JSONL-Datei: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Der Collector überwacht dieses Verzeichnis und lädt Dateien automatisch hoch. Du musst diese Dateien nicht direkt verwalten. +Der Collector überwacht dieses Verzeichnis und lädt Dateien automatisch hoch. Sie müssen diese Dateien nicht direkt verwalten. -Jede Datei wird atomar geschrieben: Das SDK schreibt zunächst in eine temporäre Datei und benennt sie dann an ihren Zielort um, sodass der Collector niemals eine halb geschriebene Datei sieht. Ein abschließender Flush wird auch beim Beenden deines Prozesses ausgeführt, sodass Events, die im letzten Intervall gepuffert wurden, nicht verloren gehen. Wenn der Collector offline ist, sammeln sich Events einfach als Dateien auf der Festplatte an und werden übertragen, sobald er wieder verfügbar ist. +Jede Datei wird atomar geschrieben: Das SDK schreibt in eine temporäre Datei und benennt sie dann um, sodass der Collector niemals eine halb geschriebene Datei sieht. Ein abschließender Flush läuft auch beim Beenden Ihres Prozesses, sodass im letzten Intervall gepufferte Events nicht verloren gehen. Wenn der Collector offline ist, akkumulieren sich Events einfach als Dateien auf der Festplatte und werden versendet, sobald er wieder online kommt. --- ## Nächste Schritte -- [Event-Stream](/de/agenteye/event-stream): Beobachte, wie diese Events live ankommen, farblich kodiert und filterbar nach Umgebung, Agent und Session. -- [Sessions](/de/agenteye/sessions): Sieh, wie die gepaarten Events jeden Agentenlauf als Ausführungsgraph und Zeitleiste rekonstruieren. \ No newline at end of file +- [Event-Stream](/de/agenteye/event-stream): Sehen Sie zu, wie diese Events live ankommen – farbkodiert und filterbar nach Umgebung, Agent und Session. +- [Sessions](/de/agenteye/sessions): Sehen Sie, wie die gepaarten Events jeden Agentenlauf als Ausführungsgraph und Timeline rekonstruieren. \ No newline at end of file diff --git a/docs/de/agenteye/queries.mdx b/docs/de/agenteye/queries.mdx index 6ea854c5..751c945e 100644 --- a/docs/de/agenteye/queries.mdx +++ b/docs/de/agenteye/queries.mdx @@ -4,53 +4,53 @@ description: "Stellen Sie Ihren Agentendaten beliebige Fragen und erhalten Sie i --- -Stellen Sie Ihren Agentendaten beliebige Fragen und erhalten Sie in Sekunden eine Antwort. Failproof AI Observability bietet Ihnen eine Bibliothek gespeicherter, sofort ausführbarer Abfragen über Ihre Events und Auswertungen – damit starten Sie mit einem funktionierenden Beispiel statt vor einem leeren SQL-Editor. +Stellen Sie Ihren Agentendaten beliebige Fragen und erhalten Sie in Sekunden eine Antwort. Die Observability-Funktion von Failproof AI bietet Ihnen eine Bibliothek gespeicherter, sofort ausführbarer Abfragen über Ihre Events und Auswertungen – so starten Sie mit einem funktionierenden Beispiel statt vor einem leeren SQL-Editor. -![Die Bibliothek gespeicherter Abfragen: ein Raster wiederverwendbarer Abfragen, sowohl eingebaute Vorlagen als auch eigene](/agenteye/images/queries.png) +![Die Bibliothek gespeicherter Abfragen: ein Raster wiederverwendbarer Abfragen, sowohl integrierte Voreinstellungen als auch benutzerdefinierte](/agenteye/images/queries.png) -*Ihre Bibliothek gespeicherter Abfragen unter `//queries`: eingebaute Vorlagen neben den Abfragen, die Ihr Team gespeichert hat.* +*Ihre Bibliothek gespeicherter Abfragen unter `//queries`: integrierte Voreinstellungen neben den Abfragen, die Ihr Team gespeichert hat.* -## Mit einer Vorlage starten, nicht auf einer leeren Seite +## Mit einer Vorlage starten, nicht mit einer leeren Seite -Sie müssen sich keine Tabellennamen merken oder SQL von Grund auf schreiben. Die Bibliothek öffnet sich mit eingebauten Vorlagen für die Fragen, die Teams am häufigsten stellen – direkt neben den Abfragen, die Ihr Team selbst gespeichert und benannt hat. Wählen Sie eine aus, die Ihrem Bedarf nahekommt, und Sie sind der Antwort schon einen großen Schritt näher. +Sie müssen sich keine Tabellennamen merken oder SQL von Grund auf schreiben. Die Bibliothek öffnet sich mit integrierten Voreinstellungen für die Fragen, die Teams am häufigsten stellen – direkt neben den Abfragen, die Ihr eigenes Team gespeichert und benannt hat. Wählen Sie eine aus, die Ihrem Ziel nahekommt, und Sie sind dem Ergebnis bereits sehr nah. -Jede gespeicherte Abfrage ist organisationsweit gültig und geteilt, sodass nützliche Abfragen Ihrer Teammitglieder auch Ihnen zur Verfügung stehen. Geben Sie einer Abfrage einmalig einen Namen und eine Beschreibung, und jede Person in Ihrer Organisation kann sie finden, ausführen oder ihre Ergebnisse später in ein Dashboard einbinden. +Jede gespeicherte Abfrage ist organisations-weit gültig und geteilt, sodass nützliche Abfragen Ihrer Teammitglieder auch Ihnen zur Verfügung stehen. Benennen Sie eine Abfrage einmal und versehen Sie sie mit einer Beschreibung – dann kann jeder in Ihrer Organisation sie finden, ausführen oder ihre Ergebnisse später auf einem Dashboard anheften. -Sie finden die Bibliothek unter `//queries`. +Sie finden sie unter `//queries`. ## Im SQL-Composer anpassen und ausführen -Öffnen Sie eine beliebige Abfrage, und sie wird im SQL-Composer angezeigt, wo Sie sie anpassen und die Antwort sofort sehen können – kein Export, kein Umweg, kein Warten auf jemand anderen. +Öffnen Sie eine beliebige Abfrage, und sie landet im SQL-Composer, wo Sie sie anpassen und die Antwort sofort sehen können – kein Export, kein Umweg, kein Warten auf jemand anderen. ![Der SQL-Abfrage-Composer mit einer gespeicherten Abfrage, einer Schema-Seitenleiste und einem Live-Ergebnisraster](/agenteye/images/query-lab.png) -*Der SQL-Composer: Ihre Abfrage auf der linken Seite, eine Schema-Seitenleiste damit Sie nie einen Spaltennamen erraten müssen, und ein Live-Ergebnisraster darunter.* +*Der SQL-Composer: Ihre Abfrage auf der linken Seite, eine Schema-Seitenleiste damit Sie nie nach einem Spaltennamen suchen müssen, und ein Live-Ergebnisraster darunter.* -- **Eine Schema-Seitenleiste** zeigt die Analysetabellen und ihre Spalten übersichtlich an, sodass Sie eine Abfrage formulieren können, ohne nach Feldnamen suchen zu müssen. -- **Ein Live-Ergebnisraster** liefert Zeilen sofort nach der Ausführung, sodass Sie in Sekunden iterieren können, anstatt zu raten und erneut zu raten. -- **Nur-Lese-Design.** Abfragen werden gegen Ihren Event-Store ausgeführt und serverseitig validiert: Nur `SELECT`- und `WITH`-Anweisungen sind erlaubt, mit einem Anweisungs-Timeout und einer Zeilenbegrenzung. Eine explorative Abfrage kann Ihre Daten niemals verändern, und eine unkontrolliert laufende wird automatisch gestoppt. +- **Eine Schema-Seitenleiste** zeigt die Analysetabellen und ihre Spalten an, sodass Sie eine Abfrage formulieren können, ohne nach Feldnamen suchen zu müssen. +- **Ein Live-Ergebnisraster** gibt Zeilen zurück, sobald Sie die Abfrage ausführen, damit Sie in Sekunden iterieren können statt immer wieder zu raten. +- **Konstruktionsbedingt schreibgeschützt.** Abfragen laufen gegen Ihren Event-Store und werden serverseitig validiert: Nur `SELECT`- und `WITH`-Anweisungen sind erlaubt, mit einem Anweisungs-Timeout und einer Zeilenobergrenze. Eine explorative Abfrage kann Ihre Daten niemals verändern, und eine außer Kontrolle geratene wird automatisch gestoppt. -Zufrieden mit dem Ergebnis? Speichern Sie es in der Bibliothek, damit das gesamte Team davon profitiert, oder binden Sie die Ausgabe als Linien-, Balken-, Flächen- oder Kreisdiagramm-Kachel in ein Dashboard ein. +Mit dem Ergebnis zufrieden? Speichern Sie es in der Bibliothek, damit das gesamte Team davon profitiert, oder heften Sie die Ausgabe als Linien-, Balken-, Flächen- oder Kreisdiagramm-Kachel auf ein Dashboard. ## Über das Terminal ausführen oder vom Assistenten schreiben lassen -Dieselben gespeicherten Abfragen folgen Ihnen überall hin: +Dieselben gespeicherten Abfragen begleiten Sie überall: -- **Über das Terminal.** Die `agenteye`-CLI listet, führt aus und speichert dieselben Abfragen, sodass Sie ein Ergebnis in ein Skript einfügen, in CI einbinden oder an einen Coding-Agenten weitergeben können. +- **Vom Terminal aus.** Das `agenteye` CLI listet, führt aus und speichert dieselben Abfragen, sodass Sie ein Ergebnis in ein Skript einbinden, in CI integrieren oder an einen Coding-Agenten übergeben können. ```bash -agenteye query list # die gleichen gespeicherten Abfragen, aus Ihrem Terminal -agenteye query run errs --arg prod # eine ausführen und die Zeilen ausgeben (--json zum Weiterleiten hinzufügen) +agenteye query list # the same saved queries, from your terminal +agenteye query run errs --arg prod # run one and print the rows (add --json to pipe it) ``` - Siehe [CLI und Agenten](/de/agenteye/cli-and-agents) für den vollständigen Befehlssatz. + Die vollständige Befehlsübersicht finden Sie unter [CLI und Agenten](/de/agenteye/cli-and-agents). -- **Über den KI-Assistenten.** Sie sind unsicher, wie Sie das SQL formulieren sollen? Fragen Sie den [KI-Assistenten](/de/agenteye/assistant) im Dashboard auf normalem Deutsch, und er wird die Abfrage entwerfen und für Sie in Ihrer Bibliothek speichern. +- **Über den KI-Assistenten.** Nicht sicher, wie Sie das SQL formulieren sollen? Fragen Sie den [KI-Assistenten](/de/agenteye/assistant) im Dashboard auf Deutsch und er entwirft die Abfrage und speichert sie für Sie in Ihrer Bibliothek. -Das Ausführen einer gespeicherten Abfrage ist durch die Berechtigung `queries:run` geschützt, die getrennt von den Berechtigungen zum Erstellen oder Löschen von Abfragen verwaltet wird. So können Sie Lesezugriff erteilen, ohne allen zu erlauben, die Bibliothek umzuschreiben. +Das Ausführen einer gespeicherten Abfrage erfordert die Berechtigung `queries:run`, die von den Berechtigungen zum Erstellen oder Löschen von Abfragen getrennt ist – so können Sie Lesezugriff gewähren, ohne allen das Umschreiben der Bibliothek zu erlauben. ## Verwandte Themen -- [Dashboards](/de/agenteye/dashboards): Abfrageergebnisse in geteilte, organisationsweite Diagramme einbinden. -- [KI-Assistent](/de/agenteye/assistant): Fragen auf normalem Deutsch stellen und eine fertige Abfrage erhalten. -- [CLI und Agenten](/de/agenteye/cli-and-agents): Dieselben Abfragen über das Terminal ausführen und speichern. \ No newline at end of file +- [Dashboards](/de/agenteye/dashboards): Abfrageergebnisse in organisations-weite, geteilte Diagramme einbinden. +- [KI-Assistent](/de/agenteye/assistant): Fragen in natürlicher Sprache stellen und eine Abfrage zurückerhalten. +- [CLI und Agenten](/de/agenteye/cli-and-agents): Dieselben Abfragen vom Terminal aus ausführen und speichern. \ No newline at end of file diff --git a/docs/de/agenteye/security.mdx b/docs/de/agenteye/security.mdx index 9756abac..74451335 100644 --- a/docs/de/agenteye/security.mdx +++ b/docs/de/agenteye/security.mdx @@ -1,68 +1,68 @@ --- title: "Sicherheit" -description: "Failproof AI Observability ist darauf ausgelegt, nah an Ihren Produktions-Agents zu laufen – das bedeutet, es sieht Ihre Prompts, Tool-Eingaben und Ausgaben." +description: "Failproof AI Observability ist darauf ausgelegt, nah an Ihren Produktions-Agenten zu arbeiten – und sieht daher Ihre Prompts, Tool-Eingaben und Ausgaben." --- -Failproof AI Observability ist darauf ausgelegt, nah an Ihren Produktions-Agents zu laufen – das bedeutet, es sieht Ihre Prompts, Tool-Eingaben und Ausgaben. Diese Seite erklärt, wie die Daten isoliert, kontrolliert und in Ihren Händen bleiben. Wenn Sie Failproof AI Observability im Rahmen einer Sicherheitsprüfung evaluieren, beginnen Sie hier. +Failproof AI Observability ist darauf ausgelegt, nah an Ihren Produktions-Agenten zu arbeiten – und sieht daher Ihre Prompts, Tool-Eingaben und Ausgaben. Diese Seite erklärt, wie Ihre Daten isoliert, kontrolliert und in Ihren Händen bleiben. Wenn Sie Failproof AI Observability für ein Sicherheits-Review evaluieren, beginnen Sie hier. --- -## Ihre Daten bleiben in Ihrer Umgebung +## Ihre Daten verbleiben in Ihrer Umgebung -Failproof AI Observability wird selbst gehostet. Events, Prompts, Modellantworten und Analysen werden in Ihren eigenen Datenbanken, in Ihrer eigenen Umgebung gespeichert. Es werden keine Daten zur Speicherung an einen Drittanbieter-SaaS übermittelt – Ihre Daten verbleiben in Ihrem eigenen Cloud-Account. +Failproof AI Observability ist self-hosted. Ereignisse, Prompts, Modellantworten und Analysen werden in Ihren eigenen Datenbanken, in Ihrer eigenen Umgebung gespeichert. Es werden keine Daten zur Speicherung an einen Drittanbieter-SaaS übertragen, und Ihre Daten verbleiben in Ihrem eigenen Cloud-Konto. --- -## Mandantenisolierung +## Mandantenisolation -Eine Failproof AI Observability-Instanz kann viele Organisationen beherbergen, und jede ist auf Speicherebene isoliert – durchgesetzt von der Datenbank, nicht nur von der Benutzeroberfläche: +Eine Failproof AI Observability-Instanz kann viele Organisationen hosten, wobei jede auf der Speicherschicht isoliert ist – durchgesetzt von der Datenbank selbst, nicht nur von der Benutzeroberfläche: - Die operativen Daten einer Organisation (Benutzer, Schlüssel, Dashboards, gespeicherte Abfragen) sind auf diese Organisation beschränkt, und organisationsübergreifende Lesezugriffe werden von der Datenbank selbst blockiert. -- Jedes aufgenommene Event wird mit der zugehörigen Organisation gestempelt, sodass die Events einer Organisation niemals von einer anderen gelesen werden können. +- Jedes erfasste Ereignis wird mit der zugehörigen Organisation gestempelt, sodass die Ereignisse einer Organisation niemals von einer anderen gelesen werden können. -Jede Dashboard-Route ist unter einem Org-Slug (`//…`) eingeschränkt. +Jede Dashboard-Route ist unter einem Org-Slug (`//…`) abgegrenzt. --- ## Anmeldung -Failproof AI Observability verwendet passwortlose, E-Mail-basierte Anmeldung. Es gibt kein Passwort, das abgephisht oder geleakt werden könnte. Ein Benutzer fordert einen Einmalcode (oder einen Magic Link zum einmaligen Klicken) an, der per E-Mail zugestellt wird und schnell abläuft. Die Anmeldung ist durch eine **Allowlist** gesichert: Nur E-Mail-Adressen (oder Domains), die Sie freigeben, können sich authentifizieren. +Failproof AI Observability verwendet passwortlose, e-mailbasierte Anmeldung. Es gibt kein Passwort, das abgephisht oder geleakt werden könnte. Ein Benutzer fordert einen Einmalcode (oder einen Magic-Link per Klick) an, der ihm per E-Mail zugeschickt wird und schnell abläuft. Die Anmeldung wird durch eine **Allowlist** gesteuert: Nur E-Mail-Adressen (oder Domains), die Sie freigeben, können sich authentifizieren. -![Der Anmeldebildschirm von Failproof AI Observability, der einen Einmalcode an Ihre E-Mail-Adresse sendet](/agenteye/images/login.png) +![Der Failproof AI Observability-Anmeldebildschirm, der einen Einmalcode an Ihre E-Mail sendet](/agenteye/images/login.png) --- -## Eingeschränkter Zugriff mit API-Schlüsseln +## Abgegrenzter Zugriff mit API-Schlüsseln -Jeder Client authentifiziert sich mit einem API-Schlüssel, der granulare, minimal privilegierte Berechtigungen trägt. Ein Collector benötigt lediglich `events:add`; ein Dashboard- oder Assistenten-Schlüssel kann schreibgeschützt sein; destruktive Aktionen (Löschen, Neugenerieren) sind separate Berechtigungen, die Sie gezielt vergeben. +Jeder Client authentifiziert sich mit einem API-Schlüssel, der granulare Least-Privilege-Berechtigungen trägt. Ein Collector benötigt nur `events:add`; ein Dashboard- oder Assistenten-Schlüssel kann schreibgeschützt sein; destruktive Aktionen (Löschen, Neugenerieren) sind separate Berechtigungen, die Sie gezielt vergeben. -![Die API-Schlüssel-Seite: Berechtigungen jedes Schlüssels, farblich nach Lese-, Schreib- und destruktivem Umfang kodiert](/agenteye/images/api-keys.png) +![Die API-Schlüssel-Seite: die Berechtigungen jedes Schlüssels, farblich nach Lese-, Schreib- und destruktivem Umfang codiert](/agenteye/images/api-keys.png) -Behalten Sie den Admin-Bootstrap-Schlüssel für die Einrichtung, und vergeben Sie eingeschränkte Schlüssel für alles andere. Siehe [API-Schlüssel](/de/agenteye/api-keys). +Behalten Sie den Admin-Bootstrap-Schlüssel für die Einrichtung und vergeben Sie enge Schlüssel für alles andere. Siehe [API-Schlüssel](/de/agenteye/api-keys). --- ## Ein schreibgeschützter, genehmigungspflichtiger Assistent -Der [KI-Assistent](/de/agenteye/assistant) im Dashboard beantwortet Fragen über Ihre Daten, ist aber bewusst eingeschränkt: +Der [KI-Assistent](/de/agenteye/assistant) im Dashboard beantwortet Fragen zu Ihren Daten, ist aber konzeptionell eingeschränkt: -- Er ist **standardmäßig schreibgeschützt**: Sein SQL wird durch einen Guard geleitet, der nur `SELECT`/`WITH`-Abfragen, einzelne Anweisungen und eine Zeilenbegrenzung erlaubt. -- Alles, was er erstellt (eine gespeicherte Abfrage, ein Dashboard), ist **genehmigungspflichtig**: Sie prüfen und genehmigen jeden Schreibvorgang, bevor er ausgeführt wird. +- Er ist **standardmäßig schreibgeschützt**: Sein SQL läuft durch eine Absicherung, die nur `SELECT`/`WITH`-Abfragen zulässt – einzelne Anweisungen, mit einer Zeilenbegrenzung. +- Alles, was er erstellt (eine gespeicherte Abfrage, ein Dashboard), unterliegt einer **Genehmigungspflicht**: Sie prüfen und genehmigen jeden Schreibvorgang, bevor er ausgeführt wird. - Er **kann niemals löschen**. -So kann ein Teammitglied fragen „Welche Agents haben diese Woche am häufigsten Fehler gemeldet?" und auf die Antwort reagieren – ohne dass der Assistent Ihre Daten eigenständig ändern oder entfernen kann. +So kann ein Teammitglied fragen „Welche Agenten hatten diese Woche am meisten Fehler?" und auf die Antwort reagieren, ohne dass der Assistent Ihre Daten eigenständig ändern oder entfernen kann. --- -## Daten in Übertragung +## Übertragungssicherheit -Der gesamte Datenverkehr läuft über HTTPS. Sie terminieren TLS mit Ihren eigenen Zertifikaten, sodass der Datenverkehr zwischen Collector und Server sowie zwischen Browser und Server verschlüsselt übertragen wird. +Der gesamte Datenverkehr läuft über HTTPS. Sie beenden TLS mit Ihren eigenen Zertifikaten, sodass der Datenverkehr zwischen Collector und Server sowie zwischen Browser und Server verschlüsselt übertragen wird. --- ## Nächste Schritte -- [Übersicht](/de/agenteye/overview): Wie Failproof AI Observability zusammenarbeitet. -- [API-Schlüssel](/de/agenteye/api-keys): Zugriff für Collector, Dashboard und Assistent einschränken. -- [Observability](/de/agenteye/observability): Was Failproof AI Observability von Ihren Agents erfasst. \ No newline at end of file +- [Übersicht](/de/agenteye/overview): Wie Failproof AI Observability zusammenspielt. +- [API-Schlüssel](/de/agenteye/api-keys): Zugriffsrechte für Collector, Dashboard und Assistent abgrenzen. +- [Observability](/de/agenteye/observability): Was Failproof AI Observability von Ihren Agenten erfasst. \ No newline at end of file diff --git a/docs/de/agenteye/sessions.mdx b/docs/de/agenteye/sessions.mdx index 547a8800..396336bb 100644 --- a/docs/de/agenteye/sessions.mdx +++ b/docs/de/agenteye/sessions.mdx @@ -1,57 +1,56 @@ --- title: "Sessions & Ausführungsgraph" -description: "Alle Ereignisse eines Runs in einer übersichtlichen Zeile zusammengefasst und als Git-ähnlicher Ausführungsgraph dargestellt, den du in Sekunden erfassen kannst." +description: "Alle Ereignisse eines Durchlaufs in einer lesbaren Zeile zusammengefasst und als Git-ähnlicher Ausführungsgraph dargestellt, den Sie in Sekunden erfassen können." --- +Hören Sie auf zu rätseln, warum ein Durchlauf fehlgeschlagen ist. Failproof AI Observability fasst alle Ereignisse eines Durchlaufs in einer lesbaren Zeile zusammen und zeichnet den gesamten Ablauf als Git-ähnliches Diagramm, das Sie in Sekunden erfassen können – so sehen Sie Schritt für Schritt genau, was Ihr Agent getan hat. -Schluss mit dem Rätseln, warum ein Run fehlgeschlagen ist. Failproof AI Observability fasst alle Ereignisse eines Runs in einer lesbaren Zeile zusammen und zeichnet den gesamten Run als Git-ähnliches Diagramm, das du in Sekunden erfassen kannst – so siehst du genau, was dein Agent Schritt für Schritt getan hat. +![Die Sessions-Liste: eine Zeile pro Durchlauf, über Umgebungen und Agenten hinweg, mit Status-Badges und Bewertungs-Badges](/agenteye/images/sessions-list.png) -![Die Sessions-Liste: eine Zeile pro Run, über Umgebungen und Agents hinweg, mit Status-Pills und Bewertungsbadges](/agenteye/images/sessions-list.png) - -*Eine Zeile pro Run: der Status-Pill zeigt auf einen Blick, wie der Run geendet hat, und ein Score-Badge erscheint, sobald ein Evaluator verbunden ist.* +*Eine Zeile pro Durchlauf: Das Status-Badge zeigt auf einen Blick, wie der Durchlauf endete, und ein Bewertungs-Badge erscheint, sobald ein Evaluator verbunden ist.*
-*Agent-Tracing: einem einzelnen Run Schritt für Schritt folgen, vom Ziel über die Tools bis zur finalen Antwort.* +*Agent-Tracing: Verfolgen Sie einen einzelnen Durchlauf Schritt für Schritt, vom Ziel über die Tools bis zur abschließenden Antwort.* --- -## Alle Runs auf einen Blick +## Jeden Durchlauf auf einen Blick erfassen -Der rohe Ereignisverlauf ist die Wahrheit hinter jedem Schritt – aber wenn du Tausende von Schritten über Dutzende von Runs hinweg hast, brauchst du den Run, nicht den einzelnen Schritt. Die Sessions-Seite fasst alle Ereignisse eines Runs in einer Zeile zusammen, sodass ein ganzer Tag an Aktivität zu einer übersichtlichen Liste wird, anstatt einem Datenstrom, der kaum zu verfolgen ist. +Das rohe Ereignisprotokoll ist die Wahrheit über jeden einzelnen Schritt – aber wenn Sie Tausende von Schritten über Dutzende von Durchläufen haben, brauchen Sie den Überblick, nicht den einzelnen Schritt. Die Sessions-Seite fasst alle Ereignisse eines Durchlaufs in einer Zeile zusammen, sodass aus einem Tag voller Aktivität eine übersichtliche Liste statt eines endlosen Datenstroms wird. -Jede Zeile trägt einen Status-Pill, sodass ein fehlgeschlagener Run sofort ins Auge fällt, bevor du überhaupt klickst. Filtere nach Datumsbereich, Umgebung, Agent oder Session, um mit wenigen Klicks von „alles" zu „genau der Run, der mich interessiert" zu gelangen. +Jede Zeile trägt ein Status-Badge, sodass ein fehlgeschlagener Durchlauf sofort auffällt, noch bevor Sie irgendwo klicken. Filtern Sie nach Datumsbereich, Umgebung, Agent oder Session, um in wenigen Klicks von „alles" zu „genau der Durchlauf, der mich interessiert" zu gelangen. -Sobald du einen Evaluator verbindest, wird jeder abgeschlossene Run automatisch bewertet und sein aktueller Score erscheint als Badge in der Zeile. Du kannst nach jedem Score-Bereich filtern – „zeig mir alle niedrig bewerteten Prod-Runs dieser Woche" ist ein Filter, kein manueller Review-Prozess. Solange du noch keinen Evaluator eingerichtet hast, erfassen Sessions trotzdem den vollständigen Run, sie tragen nur noch keinen Score. +Sobald Sie einen Evaluator verbinden, wird jeder abgeschlossene Durchlauf automatisch bewertet und die aktuellste Bewertung erscheint als Badge in der Zeile. Sie können nach beliebigen Bewertungsbereichen filtern – „zeig mir alle schlecht bewerteten Produktionsdurchläufe dieser Woche" ist damit ein Filter, keine manuelle Prüfung. Bis Sie einen Evaluator einrichten, erfassen Sessions dennoch den vollständigen Durchlauf – sie tragen nur noch keine Bewertung. --- -## Den gesamten Run als Diagramm lesen +## Den gesamten Durchlauf als Diagramm lesen -![Der Git-ähnliche Ausführungsgraph einer Session neben ihrer Ereigniszeitleiste, mit dem Panel für Tool-, Modell- und Hook-Aufschlüsselung](/agenteye/images/session-detail.png) +![Der Git-ähnliche Ausführungsgraph einer Session neben ihrer Ereignis-Zeitleiste, mit dem Aufschlüsselungs-Panel für Tools, Modelle und Hooks](/agenteye/images/session-detail.png) -*Der Ausführungsgraph (links) liegt neben der Ereigniszeitleiste; die rechte Leiste schlüsselt Tools, Modelle, Hooks und Token-Verbrauch des Runs auf.* +*Der Ausführungsgraph (links) befindet sich neben der Ereignis-Zeitleiste; die rechte Leiste schlüsselt die Tools, Modelle, Hooks und den Token-Verbrauch des Durchlaufs auf.* -Klicke auf eine beliebige Session, um ihren Ausführungsgraph zu öffnen: eine Git-ähnliche Ansicht, die zeigt, wie Agents, Tools, Hooks und Modellaufrufe sich im Zeitverlauf entfaltet haben. Parallele Sub-Agents verzweigen sich jeweils auf ihre eigene Spur, sodass du siehst, welche Arbeit parallel lief, welcher Sub-Agent ins Stocken geraten ist und wo der Run vom Kurs abgekommen ist – ohne ihn gedanklich aus einem Wust von Logs rekonstruieren zu müssen. +Klicken Sie auf eine beliebige Session, um deren Ausführungsgraph zu öffnen: eine Git-ähnliche Ansicht, die zeigt, wie Agenten, Tools, Hooks und Modellaufrufe sich über die Zeit entfaltet haben. Parallele Sub-Agenten verzweigen sich jeweils in ihre eigene Spur, sodass Sie sehen können, welche Arbeiten parallel liefen, welcher Sub-Agent ins Stocken geriet und wo der Durchlauf vom Kurs abwich – ohne ihn in Gedanken aus einem Meer von Logs rekonstruieren zu müssen. -Die rechte Leiste liefert dir die Run-spezifische Aufschlüsselung: welche Tools und Modelle liefen, welche Hooks gefeuert haben und was der Run an Tokens gekostet hat. Das ist die Antwort auf „Warum hat dieser Run so viel gekostet?" oder „Welches Tool ist das langsame?" – direkt neben dem Graphen, der dazu geführt hat. +Die rechte Leiste liefert die Aufschlüsselung pro Durchlauf: welche Tools und Modelle ausgeführt wurden, welche Hooks ausgelöst wurden und wie viele Tokens der Durchlauf verbraucht hat. Das ist die Antwort auf „Warum hat dieser Durchlauf so viel gekostet?" oder „Welches Tool ist das langsame?" – direkt neben dem Graphen, der dazu geführt hat. -Einzelne Ereignisse sind adressierbar, sodass du jemandem einen Link zu einem bestimmten Moment schicken kannst, anstatt „die Session, ungefähr zwei Drittel runter". Kopiere den Link aus einem beliebigen Ereignis, oder folge einem Link aus einem [Audit](/de/agenteye/audits)-Fund oder einem Fehler – die Session öffnet sich dann mit dem ausgewählten und angezeigten Ereignis. Das gilt auch für sehr lange Runs: Die Zeitleiste lädt aus Rücksicht auf deinen Browser ein begrenztes Fenster, und ein Link, der über dieses Fenster hinausweist, findet sein Ereignis trotzdem, anstatt dich am Anfang abzusetzen. Wenn das Ereignis aus deinem Aufbewahrungsfenster herausgefallen ist, teilt dir die Seite das mit, anstatt stillschweigend nichts auszuwählen. +Einzelne Ereignisse sind adressierbar, sodass Sie jemandem einen Link zu einem bestimmten Moment schicken können, anstatt zu sagen „die Session, ungefähr bei zwei Dritteln". Kopieren Sie den Link aus einem beliebigen Ereignis, oder folgen Sie einem aus einem [Audit](/de/agenteye/audits)-Befund oder einem Fehler – die Session öffnet sich dann mit dem ausgewählten und angesteuerten Ereignis. Das gilt auch für sehr lange Durchläufe: Die Zeitleiste lädt aus Rücksicht auf Ihren Browser ein begrenztes Fenster, und ein Link, der über dieses Fenster hinauszeigt, findet dennoch sein Ereignis, anstatt Sie einfach am Anfang zu landen. Sollte das Ereignis Ihr Aufbewahrungsfenster überschritten haben, teilt die Seite Ihnen das mit, anstatt stillschweigend nichts auszuwählen. --- -## Wo du es findest +## Wo Sie es finden -Jede Dashboard-Seite ist auf deine Org beschränkt (`//…`). Sessions findest du unter **Observe** in der linken Seitenleiste, neben Events, mit den Filtern für Datumsbereich, Umgebung, Agent und Session am oberen Rand der Liste. Jede Zeile ist einen Klick von ihrem vollständigen Ausführungsgraph entfernt. +Jede Dashboard-Seite ist auf Ihre Organisation beschränkt (`//…`). Sessions befindet sich unter **Observe** in der linken Seitenleiste, neben Events, mit den Filtern für Datumsbereich, Umgebung, Agent und Session am oberen Rand der Liste. Jede Zeile führt mit einem Klick zum vollständigen Ausführungsgraph. -Um die Score-Badges und die Score-Bereich-Filterung zu aktivieren, verbinde einen Evaluator: siehe [Evaluations](/de/agenteye/evaluations). +Um die Bewertungs-Badges und die Filterung nach Bewertungsbereichen zu aktivieren, verbinden Sie einen Evaluator: siehe [Evaluations](/de/agenteye/evaluations). --- ## Verwandte Themen -- [Event stream](/de/agenteye/event-stream): der rohe, schrittweise Verlauf, aus dem jede Session zusammengesetzt wird. -- [Evaluations](/de/agenteye/evaluations): verbinde einen Evaluator, damit jeder Run einen Score-Badge erhält, nach dem du filtern kannst. -- [Telemetry](/de/agenteye/telemetry): wie Runs von deinem Agent in diese Sessions gelangen. \ No newline at end of file +- [Event stream](/de/agenteye/event-stream): Das rohe, schrittweise Protokoll, aus dem jede Session zusammengesetzt wird. +- [Evaluations](/de/agenteye/evaluations): Verbinden Sie einen Evaluator, damit jeder Durchlauf ein Bewertungs-Badge erhält, nach dem Sie filtern können. +- [Telemetry](/de/agenteye/telemetry): Wie Durchläufe von Ihrem Agenten in diese Sessions gelangen. \ No newline at end of file diff --git a/docs/de/agenteye/telemetry.mdx b/docs/de/agenteye/telemetry.mdx index 0a731789..cd0fa29f 100644 --- a/docs/de/agenteye/telemetry.mdx +++ b/docs/de/agenteye/telemetry.mdx @@ -4,49 +4,49 @@ description: "Erkenne sofort, wenn deine Modelle, Tools oder Hooks langsamer wer --- -Erkenne sofort, wenn deine Modelle, Tools oder Hooks langsamer werden oder Kosten verursachen, und fange Tail-Latency-Spitzen ab, bevor deine Nutzer sie überhaupt bemerken. Drei dedizierte Seiten verwandeln rohe Laufzeiten in p50, p95 und p99, die du auf einen Blick ablesen kannst. +Erkenne sofort, wenn deine Modelle, Tools oder Hooks langsamer werden oder Kosten verursachen, und fange Tail-Latency-Spitzen ab, bevor deine Nutzer sie überhaupt bemerken. Drei dedizierte Seiten verwandeln rohe Zeitwerte in p50, p95 und p99, die du auf einen Blick ablesen kannst. -![Die Models-Seite mit einer Latency-Heatmap, einem Percentile-Band und modellspezifischen Token-, Kosten- und Kontextfenster-Werten](/agenteye/images/models.png) -*Die Models-Seite: eine Latency-Heatmap, ein Percentile-Band sowie modellspezifische Token-Zahlen, geschätzte Kosten und die Kontextfenster-Auslastung.* +![Die Models-Seite mit einer Latenz-Heatmap, einem Perzentilband sowie modellspezifischen Token-, Kosten- und Kontextfenster-Angaben](/agenteye/images/models.png) +*Die Models-Seite: eine Latenz-Heatmap, ein Perzentilband sowie modellspezifische Token-Anzahl, geschätzte Kosten und Kontextfenster-Auslastung.* ## Lass Durchschnittswerte nicht mehr deine schlechtesten Läufe verbergen -Eine durchschnittliche Latenzangabe klingt beruhigend – und ist gleichzeitig nutzlos: Sie glättet genau jenen einen Aufruf unter fünfzig, der ins Stocken gerät und deinen Bereitschaftsdienst um 2 Uhr nachts weckt. Die Seiten Models, Tools und Hooks machen das nicht mit. Alle drei haben denselben Aufbau, den du nur einmal lernen musst: +Ein durchschnittlicher Latenzwert ist beruhigend und nutzlos zugleich: Er glättet genau den einen Aufruf von fünfzig, der ins Stocken gerät und deinen Bereitschaftsdienst um 2 Uhr nachts weckt. Die Seiten Models, Tools und Hooks tun das nicht. Jede folgt demselben Aufbau, den du einmal lernst und überall wiederfindest: - Ein **24-Bin-Sparkline** für den Trend auf einen Blick: Wird es schlechter? -- Ein **Vitals-Streifen** mit p50, p95 und p99 Latenz, damit der typische Lauf und der Ausreißer nebeneinander stehen. -- Eine **Latency-Heatmap** – 24 Zeitabschnitte gegen Latenz-Buckets –, die zeigt, *wann* sich die langsamen Aufrufe gehäuft haben. -- Ein **Percentile-Band**: eine p50-Linie mit schraffierten Bändern für p25–p75 und p10–p90 sowie p99-Punkte, sodass die Streuung sichtbar bleibt, anstatt weggemittelt zu werden. +- Ein **Vitals-Streifen** mit p50, p95 und p99 Latenz, sodass typischer Lauf und Tail nebeneinander sichtbar sind. +- Eine **Latenz-Heatmap** mit 24 Zeitbins und Latenz-Buckets, die zeigt, *wann* sich die langsamen Aufrufe häuften. +- Ein **Perzentilband**: eine p50-Linie mit schraffierten Bändern für p25 bis p75 sowie p10 bis p90 und p99-Punkten, sodass die Streuung sichtbar bleibt statt weggemittelt zu werden. -Ein gemeinsames Hover-Fadenkreuz verknüpft Heatmap und Band zeitlich miteinander, sodass ein Tail-Spike in beiden Ansichten an derselben Stelle erscheint, statt hinter einer einzigen Mittellinie zu verschwinden. Alle drei Seiten findest du im Bereich **observe** deines Dashboards – gefiltert nach Organisation und einschränkbar nach Datumsbereich, Umgebung, Agent und Session. +Ein gemeinsamer Hover-Crosshair verbindet Heatmap und Band, sodass eine Tail-Spitze zeitlich in beiden Ansichten übereinstimmt, anstatt hinter einer einzigen Mittellinie zu verschwinden. Alle drei Seiten befinden sich im Bereich **observe** deines Dashboards und können nach Datumsbereich, Umgebung, Agent und Session gefiltert werden. -## Models: sieh genau, was jedes Modell dich kostet +## Models: Sieh genau, was jedes Modell kostet -Die Models-Seite (oben abgebildet) beantwortet die zwei Fragen, die eine Rechnung immer aufwirft: Welches Modell, und wie viel? Zusätzlich zur gemeinsamen Latenzansicht zeigt sie **modellspezifischen Token-Verbrauch**, **geschätzte Kosten** und die **Kontextfenster-Auslastung** – damit unkontrolliertes Prompt-Wachstum und eine bevorstehende Kompaktierung sichtbar werden, bevor sie dich überraschen. +Die Models-Seite (oben abgebildet) beantwortet die zwei Fragen, die eine Rechnung immer aufwirft: Welches Modell, und wie viel? Zusätzlich zur gemeinsamen Latenzansicht zeigt sie **modellspezifischen Token-Verbrauch**, **geschätzte Kosten** und **Kontextfenster-Auslastung**, sodass unkontrolliertes Prompt-Wachstum und eine bevorstehende Kompaktierung sichtbar werden, bevor sie dich überraschen. -Failproof AI Observability erkennt gängige Modell-IDs automatisch. Falls ein Fenster falsch aussieht oder du ein eigenes privates Modell betreibst, korrigiere es oder füge eines unter **Settings** bei **model context windows** hinzu – die Auslastungsanzeigen passen sich entsprechend an. +Failproof AI Observability erkennt gängige Modell-IDs automatisch. Sollte ein Fenster falsch aussehen oder du ein eigenes privates Modell betreiben, korrigiere es oder füge eines unter **Settings** im Bereich **model context windows** hinzu – die Auslastungsanzeigen passen sich entsprechend an. -## Tools: unterscheide langsam von defekt +## Tools: Trenne Langsamkeit von Fehlern -Ein Tool-Aufruf kann langsam sein oder stillschweigend fehlschlagen – und du möchtest das in Sekunden wissen, nicht erst nach stundenlangem Log-Wühlen. +Ein Tool-Aufruf kann langsam sein oder still versagen – und du möchtest binnen Sekunden wissen, was zutrifft, statt erst durch Logs wühlen zu müssen. -![Die Tools-Seite mit der gemeinsamen Latency-Heatmap und dem Percentile-Band neben einer Erfolgs- und Fehleraufschlüsselung sowie einem Tool-Verteilungsbalken](/agenteye/images/tools.png) -*Die Tools-Seite: dieselbe Heatmap und dasselbe Percentile-Band, ergänzt um eine Erfolgs- und Fehleraufschlüsselung sowie einen Tool-Verteilungsbalken.* +![Die Tools-Seite mit der gemeinsamen Latenz-Heatmap und dem Perzentilband neben einer Aufschlüsselung nach Erfolg und Fehler sowie einem Tool-Verteilungsbalken](/agenteye/images/tools.png) +*Die Tools-Seite: dieselbe Heatmap und dasselbe Perzentilband, ergänzt durch eine Aufschlüsselung nach Erfolg und Fehler sowie einen Tool-Verteilungsbalken.* -Neben der gemeinsamen Latenzansicht fügt die Tools-Seite eine **Erfolgs- und Fehleraufschlüsselung** sowie einen **Tool-Verteilungsbalken** hinzu, sodass du auf einen Blick siehst, welche Tools du am häufigsten verwendest und welche dein Fehlerbudget auffressen. +Neben der gemeinsamen Latenzansicht fügt die Tools-Seite eine **Aufschlüsselung nach Erfolg und Fehler** sowie einen **Tool-Verteilungsbalken** hinzu, sodass du auf einen Blick siehst, welche Tools du am häufigsten nutzt und welche dein Fehlerbudget aufbrauchen. -## Hooks: den genauen Hook und Trigger ermitteln +## Hooks: Den genauen Hook und Trigger identifizieren -Wenn ein Lifecycle-Hook einen Lauf verlangsamt, kannst du mit der Aussage „Hooks sind langsam" nichts anfangen. Die Hooks-Seite führt dich direkt zu dem einen, der das Problem verursacht. +Wenn ein Lifecycle-Hook einen Lauf verlangsamt, ist „Hooks sind langsam" keine handlungsfähige Information. Die Hooks-Seite führt dich direkt zum entscheidenden Hook. -![Die Hooks-Seite mit nach Hook-Name und Trigger-Event aufgeschlüsselter Latenz über der gemeinsamen Heatmap und dem Percentile-Band](/agenteye/images/hooks.png) +![Die Hooks-Seite mit nach Hook-Name und Trigger-Event aufgeschlüsselter Latenz über der gemeinsamen Heatmap und dem Perzentilband](/agenteye/images/hooks.png) *Die Hooks-Seite: Latenz aufgeschlüsselt nach Hook-Name und Trigger-Event.* -Über derselben Latency-Heatmap und demselben Percentile-Band schlüsselt die Hooks-Seite die Aktivität nach **Hook-Name** und **Trigger-Event** auf, sodass du direkt bei dem einen Hook und dem einen Event landest, der Aufmerksamkeit erfordert. +Über derselben Latenz-Heatmap und demselben Perzentilband schlüsselt die Hooks-Seite die Aktivität nach **Hook-Name** und **Trigger-Event** auf, sodass du direkt zu dem einen Hook und dem einen Event gelangst, die Aufmerksamkeit erfordern. -## Verwandte Seiten +## Verwandte Themen -- [Event-Stream](/de/agenteye/event-stream): der Live-Feed aller Events, farblich kodiert. -- [Sessions](/de/agenteye/sessions): Events zu einer Zeile pro Lauf zusammenfassen und den Ausführungsgraphen öffnen. -- [Fehlerverfolgung](/de/agenteye/error-tracking): eine zentrale Triage-Oberfläche für alles, was das Dashboard rot einfärbt. -- [Dashboards](/de/agenteye/dashboards): Übersichtsansichten über deine gesamte Flotte. \ No newline at end of file +- [Event stream](/de/agenteye/event-stream): der Live-Verlauf jedes Events in Farbe. +- [Sessions](/de/agenteye/sessions): Events zu einer Zeile pro Lauf zusammenfassen und den Ausführungsgraph öffnen. +- [Error tracking](/de/agenteye/error-tracking): eine zentrale Triage-Oberfläche für alles, was das Dashboard rot markiert. +- [Dashboards](/de/agenteye/dashboards): übergreifende Übersichten für deine gesamte Flotte. \ No newline at end of file diff --git a/docs/de/architecture.mdx b/docs/de/architecture.mdx index b796c5ba..aaaa67b5 100644 --- a/docs/de/architecture.mdx +++ b/docs/de/architecture.mdx @@ -4,16 +4,16 @@ description: "Wie der Hook-Handler, das Laden der Konfiguration und die Policy-A icon: sitemap --- -Dieses Dokument erläutert, wie failproofai intern funktioniert: wie das Hook-System Agent-Tool-Aufrufe abfängt, wie die Konfiguration geladen und zusammengeführt wird, wie Policies ausgewertet werden und wie das Dashboard die Aktivitäten des Agenten überwacht. +Dieses Dokument erläutert, wie failproofai intern funktioniert: wie das Hook-System Agenten-Tool-Aufrufe abfängt, wie Konfigurationen geladen und zusammengeführt werden, wie Policies ausgewertet werden und wie das Dashboard die Agentenaktivität überwacht. --- -## Überblick +## Übersicht failproofai besteht aus zwei unabhängigen Subsystemen: -1. **Hook-Handler** – Ein schneller CLI-Subprozess, den Claude Code bei jedem Agent-Tool-Aufruf aufruft. Er wertet Policies aus und gibt eine Entscheidung zurück. -2. **Agent Monitor (Dashboard)** – Eine Next.js-Webanwendung zur Überwachung von Agent-Sitzungen und Verwaltung von Policies. +1. **Hook-Handler** – Ein schneller CLI-Subprozess, den Claude Code bei jedem Agenten-Tool-Aufruf aufruft. Wertet Policies aus und liefert eine Entscheidung zurück. +2. **Agent-Monitor (Dashboard)** – Eine Next.js-Webanwendung zur Überwachung von Agentensitzungen und zur Verwaltung von Policies. Beide Subsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im `.failproofai/`-Verzeichnis des Projekts, laufen jedoch als separate Prozesse und kommunizieren ausschließlich über das Dateisystem. @@ -23,7 +23,7 @@ Beide Subsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im ` ### Integration mit Claude Code -Wenn Sie `failproofai policies --install` ausführen, werden folgende Einträge in `~/.claude/settings.json` geschrieben: +Wenn Sie `failproofai policies --install` ausführen, schreibt failproofai folgende Einträge in `~/.claude/settings.json`: ```json { @@ -44,7 +44,7 @@ Wenn Sie `failproofai policies --install` ausführen, werden folgende Einträge } ``` -Claude Code ruft `failproofai --hook PreToolUse` dann vor jedem Tool-Aufruf als Subprozess auf und übergibt dabei einen JSON-Payload über stdin. +Claude Code ruft daraufhin `failproofai --hook PreToolUse` als Subprozess vor jedem Tool-Aufruf auf und übergibt eine JSON-Nutzlast über stdin. ### Payload-Format @@ -62,7 +62,7 @@ Claude Code ruft `failproofai --hook PreToolUse` dann vor jedem Tool-Aufruf als Bei `PostToolUse`-Ereignissen enthält der Payload zusätzlich `tool_result` mit der Ausgabe des Tools. -Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit überschreiten, werden verworfen, und alle Policies erlauben implizit. +Der Handler erzwingt ein Limit von 1 MB für stdin. Payloads, die dieses Limit überschreiten, werden verworfen und alle Policies erlauben implizit. ### Antwortformat @@ -85,7 +85,7 @@ Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit übers } ``` -**Anweisen (beliebiges Ereignis außer Stop):** +**Anweisung (beliebiges Ereignis außer Stop):** ```json { "hookSpecificOutput": { @@ -94,17 +94,17 @@ Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit übers } ``` -**Stop-Ereignis anweisen:** +**Stop-Ereignis mit Anweisung:** - Exit-Code: `2` -- Grund wird in stderr geschrieben (nicht stdout) +- Begründung wird in stderr geschrieben (nicht stdout) **Erlauben:** - Exit-Code: `0` -- Leerer stdout +- Leere stdout **Erlauben mit Nachricht:** -`allow(message)` ermöglicht es einer Policy, informativen Kontext an Claude zurückzusenden, auch wenn der Vorgang erlaubt ist. Der Hook-Handler schreibt folgenden JSON-Code nach **stdout** (keine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie die Ablehnen- und Anweisen-Antworten oben): +`allow(message)` ermöglicht es einer Policy, informativen Kontext an Claude zurückzusenden, auch wenn die Operation erlaubt ist. Der Hook-Handler schreibt folgendes JSON auf **stdout** (keine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie Ablehnen- und Anweisungsantworten oben): ```json // Written to stdout by the hook handler process @@ -114,9 +114,9 @@ Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit übers } } ``` -- Exit-Code: `0` (Vorgang ist erlaubt) -- Wenn mehrere Policies `allow` mit einer Nachricht zurückgeben, werden ihre Nachrichten mit Zeilenumbrüchen zu einem einzelnen `additionalContext`-String zusammengeführt -- Wenn keine Policy eine Nachricht liefert, ist stdout leer (wie zuvor) +- Exit-Code: `0` (Operation ist erlaubt) +- Wenn mehrere Policies `allow` mit einer Nachricht zurückgeben, werden ihre Nachrichten mit Zeilenumbrüchen zu einem einzelnen `additionalContext`-String zusammengefügt +- Falls keine Policy eine Nachricht liefert, ist stdout leer (wie bisher) ### Verarbeitungspipeline @@ -126,16 +126,16 @@ Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit übers stdin JSON → Payload parsen (max. 1 MB) → Sitzungsmetadaten extrahieren (session_id, cwd, tool_name, tool_input, etc.) - → readMergedHooksConfig(cwd) ← Projekt-, lokale und globale Konfiguration zusammenführen - → aktivierte eingebaute Policies mit aufgelösten Parametern registrieren - → benutzerdefinierte Policies aus customPoliciesPath laden (falls angegeben) + → readMergedHooksConfig(cwd) ← Zusammenführen von Projekt-, lokaler und globaler Konfiguration + → aktivierte Built-in-Policies mit aufgelösten Parametern registrieren + → benutzerdefinierte Policies aus customPoliciesPath laden (falls gesetzt) → benutzerdefinierte Policies in die Policy-Registry registrieren - → alle Policies auswerten (zuerst eingebaute, dann benutzerdefinierte) - → erster deny-Bescheid schließt die Verarbeitung kurz + → alle Policies auswerten (Built-ins zuerst, dann benutzerdefinierte) + → erstes deny bricht sofort ab → instruct-Entscheidungen werden gesammelt → allow-Nachrichten werden gesammelt - → JSON-Entscheidung nach stdout schreiben - → Ereignis nach ~/.failproofai/hook-activity/current.jsonl persistieren + → JSON-Entscheidung auf stdout schreiben + → Ereignis in ~/.failproofai/hook-activity/current.jsonl persistieren → beenden ``` @@ -143,9 +143,9 @@ Der gesamte Prozess läuft bei typischen Payloads ohne LLM-Aufrufe in unter 100 --- -## Konfigurationsladung +## Laden der Konfiguration -`src/hooks/hooks-config.ts` implementiert das Laden von Konfigurationen mit drei Geltungsbereichen. +`src/hooks/hooks-config.ts` implementiert das Laden der Konfiguration mit drei Geltungsbereichen. ```text [1] {cwd}/.failproofai/policies-config.json ← Projekt (höchste Priorität) @@ -154,10 +154,10 @@ Der gesamte Prozess läuft bei typischen Payloads ohne LLM-Aufrufe in unter 100 ``` Zusammenführungslogik: -- `enabledPolicies` – deduplizierte Vereinigung aus allen drei Dateien +- `enabledPolicies` – deduplizierte Vereinigung aller drei Dateien - `policyParams` – pro Policy-Schlüssel gewinnt die erste Datei, die ihn definiert, vollständig -- `customPoliciesPath` – die erste Datei, die ihn definiert, gewinnt -- `llm` – die erste Datei, die ihn definiert, gewinnt +- `customPoliciesPath` – die erste Datei, die es definiert, gewinnt +- `llm` – die erste Datei, die es definiert, gewinnt Das Web-Dashboard verwendet `readHooksConfig()` (nur global) zum Lesen und Schreiben, da es nicht mit einem Projekt-cwd aufgerufen wird. @@ -171,22 +171,22 @@ Für jede Policy: 1. Das `params`-Schema der Policy nachschlagen (falls vorhanden). 2. `policyParams[policy.name]` aus der zusammengeführten Konfiguration lesen. -3. Vom Benutzer bereitgestellte Werte über die Schema-Standardwerte zusammenführen, um `ctx.params` zu erzeugen. +3. Vom Benutzer angegebene Werte mit den Schema-Standardwerten zusammenführen, um `ctx.params` zu erzeugen. 4. `policy.fn(ctx)` mit dem aufgelösten Kontext aufrufen. -5. Ist das Ergebnis `deny`, sofort stoppen und diese Entscheidung zurückgeben. +5. Ist das Ergebnis `deny`, sofort abbrechen und diese Entscheidung zurückgeben. 6. Ist das Ergebnis `instruct`, die Nachricht sammeln und fortfahren. -7. Ist das Ergebnis `allow`, mit der nächsten Policy fortfahren. +7. Ist das Ergebnis `allow`, zur nächsten Policy weitergehen. Nachdem alle Policies ausgeführt wurden: -- Falls ein `deny` zurückgegeben wurde, die Ablehnen-Antwort ausgeben. -- Falls `instruct`-Rückgaben gesammelt wurden, eine einzelne Anweisen-Antwort mit allen zusammengeführten Nachrichten ausgeben. -- Andernfalls eine Erlauben-Antwort ausgeben (leerer stdout, Exit 0). +- Falls ein `deny` zurückgegeben wurde, die Ablehnungsantwort ausgeben. +- Falls `instruct`-Rückgaben gesammelt wurden, eine einzelne Anweisungsantwort mit allen zusammengefügten Nachrichten ausgeben. +- Andernfalls eine Allow-Antwort ausgeben (leere stdout, Exit 0). --- -## Eingebaute Policies +## Built-in-Policies -`src/hooks/builtin-policies.ts` definiert alle 39 eingebauten Policies als `BuiltinPolicyDefinition`-Objekte: +`src/hooks/builtin-policies.ts` definiert alle 39 integrierten Policies als `BuiltinPolicyDefinition`-Objekte: ```typescript interface BuiltinPolicyDefinition { @@ -206,7 +206,7 @@ interface BuiltinPolicyDefinition { Policies, die `params` akzeptieren, deklarieren ein `PolicyParamsSchema` mit Typen und Standardwerten für jeden Parameter. Der Policy-Evaluator injiziert aufgelöste Werte in `ctx.params`, bevor `fn` aufgerufen wird. Policy-Funktionen lesen `ctx.params` ohne Null-Prüfung, da Standardwerte immer zuerst angewendet werden. -Das Pattern-Matching innerhalb von Policies verwendet geparste Befehlstoken (argv) und kein einfaches String-Matching. Dies verhindert Umgehungsversuche durch Shell-Operator-Injektion (z. B. kann ein Pattern für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden). +Der Musterabgleich innerhalb von Policies verwendet geparste Befehls-Token (argv) statt einfachem String-Abgleich. Dies verhindert eine Umgehung durch Shell-Operator-Injection (z. B. kann ein Muster für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden). --- @@ -229,21 +229,21 @@ export function clearCustomHooks(): void { ... } // used in tests 1. `customPoliciesPath` aus der Konfiguration lesen; überspringen, falls nicht vorhanden. 2. Zu absolutem Pfad auflösen; prüfen, ob die Datei existiert. -3. Alle `from "failproofai"`-Importe zum tatsächlichen dist-Pfad umschreiben, damit `customPolicies` auf dieselbe `globalThis`-Registry verweist. -4. Transitive lokale Importe rekursiv umschreiben, um ESM-Kompatibilität sicherzustellen. +3. Alle `from "failproofai"`-Importe zum tatsächlichen dist-Pfad umschreiben, damit `customPolicies` zur selben `globalThis`-Registry aufgelöst wird. +4. Transitive lokale Importe rekursiv umschreiben, um ESM-Kompatibilität zu gewährleisten. 5. Temporäre `.mjs`-Dateien schreiben und die Einstiegsdatei per `import()` laden. 6. `getCustomHooks()` aufrufen, um registrierte Hooks abzurufen. -7. Alle temporären Dateien in einem `finally`-Block bereinigen. +7. Alle temporären Dateien in einem `finally`-Block aufräumen. -Bei einem Fehler (Datei nicht gefunden, Syntaxfehler, Import-Fehler) wird der Fehler in `~/.failproofai/hook.log` protokolliert, und der Loader gibt ein leeres Array zurück. Eingebaute Policies sind davon nicht betroffen. +Bei jedem Fehler (Datei nicht gefunden, Syntaxfehler, Importfehler) wird der Fehler in `~/.failproofai/hook.log` protokolliert und der Loader gibt ein leeres Array zurück. Built-in-Policies sind davon nicht betroffen. -Benutzerdefinierte Policies werden nach allen eingebauten Policies ausgewertet. Ein `deny` einer benutzerdefinierten Policy schließt weitere benutzerdefinierte Policies ebenfalls kurz (alle eingebauten Policies wurden zu diesem Zeitpunkt jedoch bereits ausgeführt). +Benutzerdefinierte Policies werden nach allen Built-in-Policies ausgewertet. Ein `deny` einer benutzerdefinierten Policy unterbricht trotzdem weitere benutzerdefinierte Policies (alle Built-ins wurden zu diesem Zeitpunkt jedoch bereits ausgeführt). --- ## Aktivitätsprotokollierung -Nach jedem Hook-Ereignis hängt der Handler eine JSONL-Zeile an `~/.failproofai/hook-activity/current.jsonl` an, die in `page--.jsonl` rotiert wird, sobald eine Seite erreicht ist: +Nach jedem Hook-Ereignis hängt der Handler eine JSONL-Zeile an `~/.failproofai/hook-activity/current.jsonl` an, die in `page--.jsonl` rotiert, sobald sie eine Seite erreicht: ```json { @@ -258,7 +258,7 @@ Nach jedem Hook-Ereignis hängt der Handler eine JSONL-Zeile an `~/.failproofai/ } ``` -Eine Zeile pro Policy, die eine Nicht-Erlauben-Entscheidung getroffen hat. Erlauben-Entscheidungen werden nicht protokolliert (um die Datei klein zu halten). +Eine Zeile pro Policy, die eine Nicht-Allow-Entscheidung getroffen hat. Allow-Entscheidungen werden nicht protokolliert (um die Datei klein zu halten). --- @@ -269,16 +269,16 @@ Das Dashboard ist eine **Next.js 16**-Anwendung, die den App Router mit React Se ```text app/ layout.tsx ← Root-Layout (Theme, Telemetrie, Navigation) - projects/page.tsx ← Server Component: alle Claude-Projekte auflisten - project/[name]/page.tsx ← Server Component: Sitzungen in einem Projekt auflisten + projects/page.tsx ← Server-Komponente: alle Claude-Projekte auflisten + project/[name]/page.tsx ← Server-Komponente: Sitzungen in einem Projekt auflisten project/[name]/session/ - [sessionId]/page.tsx ← Server Component: Sitzungs-Viewer rendern - policies/page.tsx ← Client Component: Policy-Verwaltung + Aktivitätslog + [sessionId]/page.tsx ← Server-Komponente: Sitzungsansicht rendern + policies/page.tsx ← Client-Komponente: Policy-Verwaltung + Aktivitätsprotokoll actions/ get-hooks-config.ts ← Konfiguration + Policy-Liste lesen update-hooks-config.ts ← Policy ein-/ausschalten update-policy-params.ts ← Policy-Parameter aktualisieren - get-hook-activity.ts ← Aktivitätslog paginieren/durchsuchen + get-hook-activity.ts ← Aktivitätsprotokoll paginieren/durchsuchen install-hooks-web.ts ← Hooks über den Browser installieren/entfernen api/ download/[project]/[session]/route.ts ← Export einzelner CLI-Sitzungen (JSONL oder JSON) @@ -294,35 +294,35 @@ app/ - Keine Datenbank – alle persistenten Zustände liegen in einfachen Dateien (`~/.failproofai/`, `~/.claude/projects/`). - Server Actions für Mutationen – keine REST-API für CRUD-Operationen erforderlich. -- React Server Components für Leseseiten – schnelleres initiales Laden, kein Client-Bundle für das Abrufen von Daten. -- Client Components nur dort, wo Interaktivität erforderlich ist (Policy-Umschalter, Aktivitätssuche, Log-Viewer). +- React Server Components für Leseseiten – schnelleres erstes Laden, kein Client-Bundle für das Abrufen von Daten. +- Client-Komponenten nur dort, wo Interaktivität benötigt wird (Policy-Umschalter, Aktivitätssuche, Log-Viewer). --- -## Dateistruktur +## Dateilayout ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI-Router (hook / dashboard / install / etc.) +│ └── failproofai.mjs # CLI-Router (Hook / Dashboard / Install / etc.) ├── src/hooks/ │ ├── handler.ts # Hook-Ereignis-Pipeline │ ├── builtin-policies.ts # 39 Policy-Definitionen -│ ├── policy-evaluator.ts # Policy-Ausführungs-Engine +│ ├── policy-evaluator.ts # Policy-Ausführungsmaschine │ ├── policy-registry.ts # Policy-Registrierung und -Suche │ ├── policy-types.ts # TypeScript-Interfaces │ ├── hooks-config.ts # Konfigurationsladung mit mehreren Geltungsbereichen │ ├── custom-hooks-registry.ts # globalThis-basierte Hook-Registry │ ├── custom-hooks-loader.ts # ESM-Loader für benutzerdefinierte JS-Hooks -│ ├── manager.ts # Installieren / Entfernen / Auflisten von Operationen -│ ├── install-prompt.ts # Interaktive Policy-Auswahlmaske +│ ├── manager.ts # Installieren / Entfernen / Auflisten +│ ├── install-prompt.ts # Interaktive Policy-Auswahlabfrage │ ├── hook-logger.ts # Protokollierung in hook.log │ ├── hook-activity-store.ts # Aktivität in hook-activity/ persistieren │ └── llm-client.ts # LLM-API-Client (für KI-gestützte Policies) ├── app/ # Next.js-Dashboard (Seiten + Server Actions) ├── lib/ # Gemeinsam genutzte Hilfsprogramme -│ ├── projects.ts # Claude-Projekte aus dem Dateisystem auflisten -│ ├── log-entries.ts # JSONL-Transkriptformat von Claude parsen +│ ├── projects.ts # Claude-Projekte aus dem Dateisystem aufzählen +│ ├── log-entries.ts # Claude-Transkript-JSONL-Format parsen │ ├── paths.ts # Systempfade auflösen │ └── ... ├── components/ # Gemeinsam genutzte React-UI-Komponenten diff --git a/docs/de/built-in-policies.mdx b/docs/de/built-in-policies.mdx index 86bebdb6..309c26fc 100644 --- a/docs/de/built-in-policies.mdx +++ b/docs/de/built-in-policies.mdx @@ -1,10 +1,10 @@ --- -title: Integrierte Richtlinien -description: "Alle 39 integrierten Richtlinien, die häufige Agent-Fehlertypen abfangen" +title: Eingebaute Richtlinien +description: "Alle 39 eingebauten Richtlinien, die häufige Fehlerszenarien von Agenten abfangen" icon: shield --- -failproofai wird mit 39 integrierten Richtlinien ausgeliefert, die häufige Agent-Fehlertypen abfangen. Jede Richtlinie wird bei einem bestimmten Hook-Ereignistyp und Toolnamen ausgelöst. Neunzehn Richtlinien akzeptieren Parameter, mit denen Sie ihr Verhalten anpassen können, ohne Code zu schreiben. Fünf Workflow-Richtlinien erzwingen eine Commit → Push → PR → CI-Pipeline, bevor Claude stoppt. +failproofai wird mit 39 eingebauten Richtlinien geliefert, die häufige Fehlerszenarien von Agenten abfangen. Jede Richtlinie wird bei einem bestimmten Hook-Ereignistyp und Werkzeugnamen ausgelöst. Neunzehn Richtlinien akzeptieren Parameter, mit denen Sie ihr Verhalten anpassen können, ohne Code schreiben zu müssen. Fünf Workflow-Richtlinien erzwingen eine Commit → Push → PR → CI-Pipeline, bevor Claude stoppt. --- @@ -15,7 +15,7 @@ Richtlinien sind in Kategorien gruppiert: | Kategorie | Richtlinien | Hook-Typ | |----------|----------|-----------| | [Gefährliche Befehle](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | -| [Infra-Befehle](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [Infrastrukturbefehle](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | | [Secrets (Sanitizer)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [Umgebung](#environment) | block-env-files, protect-env-vars | PreToolUse | | [Dateizugriff](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | @@ -27,17 +27,17 @@ Richtlinien sind in Kategorien gruppiert: - **`block-`** — verhindert, dass der Agent fortfährt. - **`warn-`** — gibt dem Agenten zusätzlichen Kontext, damit er sich selbst korrigieren kann. -- **`sanitize-`** — bereinigt sensible Daten aus der Tool-Ausgabe, bevor der Agent sie sieht. +- **`sanitize-`** — bereinigt sensible Daten aus der Werkzeugausgabe, bevor der Agent sie sieht. ### Namespaces -Jede Richtlinie befindet sich in einem `/`-Slot. Integrierte Richtlinien gehören zum +Jede Richtlinie befindet sich in einem `/`-Slot. Eingebaute Richtlinien gehören zum **`failproofai/`**-Namespace — zum Beispiel `failproofai/sanitize-jwt`. Der Namespace verhindert Kollisionen, wenn Sie auch benutzerdefinierte oder Drittanbieter-Richtlinien mit ähnlichen Kurznamen laden. -In Ihrer Konfiguration können Sie eine integrierte Richtlinie entweder über ihren Kurznamen oder ihren -vollständigen Namen referenzieren; beide Formen zeigen auf dieselbe Richtlinie: +In Ihrer Konfiguration können Sie auf eine eingebaute Richtlinie entweder über ihren Kurznamen oder ihren +qualifizierten Namen verweisen; beide Formen werden zur selben Richtlinie aufgelöst: ```json { @@ -49,14 +49,14 @@ vollständigen Namen referenzieren; beide Formen zeigen auf dieselbe Richtlinie: ``` Wenn ein Name kein `/` enthält, behandelt failproofai ihn als zum Standard-Namespace -`failproofai` gehörend. Namen, die bereits ein `/` enthalten (z. B. `myorg/foo`, +`failproofai` gehörend. Namen, die bereits ein `/` enthalten (z.B. `myorg/foo`, `custom/my-hook`), werden unverändert übernommen. - **`require-`** — blockiert das Stop-Ereignis, bis die Bedingungen erfüllt sind. --- -Jede Richtlinie unterstützt ein optionales `hint`-Feld in `policyParams`. Der Hinweis wird an die deny- oder instruct-Nachricht angehängt, die Claude sieht, und gibt umsetzbare Anweisungen, ohne den Richtliniencode zu ändern. Funktioniert mit integrierten, benutzerdefinierten und konventionsbasierten Richtlinien. Siehe [Konfiguration → hint](/de/configuration#hint-cross-cutting) für Details. +Jede Richtlinie unterstützt ein optionales `hint`-Feld in `policyParams`. Der Hinweis wird an die deny- oder instruct-Nachricht angehängt, die Claude sieht, und bietet umsetzbare Orientierung, ohne den Richtliniencode zu ändern. Funktioniert mit eingebauten, benutzerdefinierten und konventionsbasierten Richtlinien. Weitere Details unter [Konfiguration → hint](/de/configuration#hint-cross-cutting). --- @@ -70,12 +70,12 @@ Verhindert, dass Agenten Operationen ausführen, die schwer rückgängig zu mach **Ereignis:** PreToolUse (Bash) **Standard:** Verweigert jeden `sudo`- oder `doas`-Befehl. -Blockiert einen Befehl, der ein Elevation-Binary **in Befehlsposition** ausführt. Die Erkennung erfolgt strukturell statt textuell: Der Befehl wird in Segmente aufgeteilt, wie es eine Shell tun würde, Präfix-Zuweisungen (`FOO=bar`), Umleitungen und Runner mit ihren Flags (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) werden abgetrennt, und das resultierende Binary wird anhand seines **Basisnamens** verglichen. So werden `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` und `bash -c "sudo …"` alle verweigert, und `doas` wird als dieselbe Fähigkeit unter einem anderen Namen behandelt. +Blockiert einen Befehl, der ein Rechteerweiterungsprogramm **an der Befehlsposition** ausführt. Das Matching ist strukturell statt textuell: Der Befehl wird so in Segmente aufgeteilt, wie es eine Shell tun würde; Präfix-Zuweisungen (`FOO=bar`), Umleitungen und Runner mit ihren Flags (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) werden entfernt, und das resultierende Programm wird nach **Basename** verglichen. Daher werden `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` und `bash -c "sudo …"` alle verweigert, und `doas` wird als dieselbe Fähigkeit unter einem anderen Namen behandelt. -Da die Prüfung auf die Befehlsposition verankert ist und nicht auf das Vorhandensein des Wortes irgendwo, wird sie **nicht** ausgelöst bei Befehlen, die es lediglich erwähnen — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"` oder eine `grep`-Alternation, die das Wort enthält, laufen normal durch. +Da die Prüfung auf die Befehlsposition ausgerichtet ist und nicht auf das bloße Vorkommen des Wortes, wird sie **nicht** bei Befehlen ausgelöst, die das Wort lediglich erwähnen — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"` oder ein `grep`-Ausdruck mit dem Wort laufen normal durch. -Dies stoppt den offensichtlichen Versuch; es schließt jedoch nicht die gesamte Klasse. Ein Agent, der beliebige Shell-Befehle ausführen kann, kann Elevation dennoch indirekt erreichen — über eine Variable (`S=sudo; $S …`), eine base64-dekodierte Pipe oder ein Wrapper-Skript auf der Festplatte — da keine Inspektion eines einzelnen Befehls-Strings diesen folgen kann. Betrachten Sie dies als Schutzmaßnahme gegen Fehler und versehentliche Eskalation, nicht als Sicherheitsgrenze gegen einen entschlossenen Agenten. Eine echte Grenze muss unterhalb der Shell durchgesetzt werden. +Dies stoppt den offensichtlichen Versuch; es schließt jedoch nicht die gesamte Angriffsfläche. Ein Agent, der beliebige Shell-Befehle ausführen kann, kann dennoch indirekt Rechte erlangen — durch eine Variable (`S=sudo; $S …`), eine base64-dekodierte Pipe oder ein Wrapper-Skript auf der Festplatte — da keine Inspektion eines einzelnen Befehlsstrings diese Wege verfolgen kann. Betrachten Sie dies als Schutzmaßnahme gegen Fehler und beiläufige Rechteausweitung, nicht als Sicherheitsgrenze gegen einen entschlossenen Agenten. Eine echte Grenze muss unterhalb der Shell durchgesetzt werden. **Parameter:** @@ -99,7 +99,7 @@ Dies stoppt den offensichtlichen Versuch; es schließt jedoch nicht die gesamte Mit dieser Konfiguration ist `sudo systemctl status nginx` erlaubt, aber `sudo rm /etc/hosts` wird verweigert. -Muster werden gegen geparste Token geprüft, nicht gegen den rohen Befehls-String. Dies verhindert Umgehung über angehängte Shell-Operatoren (z. B. entspricht `sudo systemctl status x; rm -rf /` nicht dem Muster `sudo systemctl status *`). +Muster werden gegen geparste Token geprüft, nicht gegen den rohen Befehlsstring. Dies verhindert Umgehungen durch angehängte Shell-Operatoren (z.B. entspricht `sudo systemctl status x; rm -rf /` nicht dem Muster `sudo systemctl status *`). --- @@ -113,7 +113,7 @@ Muster werden gegen geparste Token geprüft, nicht gegen den rohen Befehls-Strin | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Pfade, die sicher rekursiv gelöscht werden dürfen (z. B. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Pfade, die sicher rekursiv gelöscht werden dürfen (z.B. `/tmp`). | **Beispiel:** @@ -141,7 +141,7 @@ Keine Parameter. ### `block-failproofai-commands` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert Befehle, die failproofai selbst deinstallieren oder deaktivieren würden (z. B. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Standard:** Verweigert Befehle, die failproofai selbst deinstallieren oder deaktivieren würden (z.B. `npm uninstall failproofai`, `failproofai policies --uninstall`). Keine Parameter. @@ -150,21 +150,21 @@ Keine Parameter. ### `block-self-pause` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert `failproofai config --pause`, das die Durchsetzung für eine Sitzung aussetzt. Das Pausieren ist eine menschliche Entscheidung — ein Agent, der dies ausführen kann, könnte mit einem einzigen Befehl alle anderen Richtlinien deaktivieren. +**Standard:** Verweigert `failproofai config --pause`, das die Durchsetzung für eine Sitzung aussetzt. Das Pausieren ist eine menschliche Entscheidung — ein Agent, der es ausführen kann, könnte alle anderen Richtlinien mit einem einzigen Befehl abschalten. -Bewusst enger gefasst als [`block-failproofai-commands`](#block-failproofai-commands) und nicht davon abgedeckt: Diese Richtlinie verankert sich an einer Befehlsgrenze, sodass `npx -y failproofai config --pause` nicht darauf passt; und da sie breit gefasst ist, wird sie oft deaktiviert, damit Agenten `failproofai audit` ausführen können. `--resume` und `--status` sind erlaubt — keines davon entfernt die Durchsetzung. +Absichtlich enger als [`block-failproofai-commands`](#block-failproofai-commands) und nicht davon abgedeckt: Diese Richtlinie greift an einer Befehlsgrenze, sodass `npx -y failproofai config --pause` nicht damit übereinstimmt; da sie breiter ist, wird sie oft deaktiviert, damit Agenten `failproofai audit` ausführen können. `--resume` und `--status` sind erlaubt — keines davon hebt die Durchsetzung auf. -Dies stoppt den direkten Versuch, nicht die gesamte Klasse: Ein Agent kann denselben Zustand dennoch über einen Alias oder ein Wrapper-Skript erreichen. Um dies vollständig zu verhindern, muss die Pause-Funktion für Tool-Aufrufe gänzlich unerreichbar sein. +Dies stoppt den direkten Versuch, nicht die gesamte Angriffsfläche: Ein Agent kann denselben Zustand noch über einen Alias oder ein Wrapper-Skript erreichen. Die vollständige Absicherung erfordert, dass die Pause-Funktion für einen Tool-Aufruf überhaupt nicht erreichbar ist. Keine Parameter. --- -## Infra-Befehle +## Infrastrukturbefehle -Verhindert, dass Coding-Agenten Infrastruktur-CLIs ausführen oder CI/CD-Pipelines auslösen. Alle Richtlinien in dieser Kategorie sind **opt-in** (`defaultEnabled: false`) — Agenten, die `kubectl`, `terraform` usw. legitim aufrufen müssen, werden nicht gestört, es sei denn, Sie aktivieren die Richtlinie. Wenn aktiviert, wird jeder Aufruf des entsprechenden CLI verweigert, sofern der Befehl nicht einem Eintrag in `allowPatterns` entspricht. +Verhindert, dass Coding-Agenten Infrastruktur-CLIs ausführen oder CI/CD-Pipelines auslösen. Alle Richtlinien in dieser Kategorie sind **opt-in** (`defaultEnabled: false`) — Agenten, die `kubectl`, `terraform` usw. legitim aufrufen müssen, werden nicht gestört, es sei denn, Sie aktivieren die Richtlinie. Wenn aktiviert, wird jeder Aufruf der entsprechenden CLI verweigert, es sei denn, der Befehl stimmt mit einem Eintrag in `allowPatterns` überein. -Die Mustergrammatik ist dieselbe wie bei [`block-sudo`](#block-sudo): Token werden gegen geparste argv geprüft, `*` ist ein Platzhalter für ein Token, und jeder Befehl mit einem eigenständigen Shell-Operator (`&&`, `||`, `|`, `;`) oder einem Token mit eingebetteten Shell-Metazeichen wird vor dem Allowlist-Abgleich abgelehnt, um Injection-Bypässe zu verhindern. +Die Mustersyntax ist dieselbe wie bei [`block-sudo`](#block-sudo): Token werden gegen geparste argv geprüft, `*` ist ein Platzhalter für ein Token, und jeder Befehl mit einem eigenständigen Shell-Operator (`&&`, `||`, `|`, `;`) oder einem Token mit eingebetteten Shell-Metazeichen wird vor dem Allowlist-Matching abgewiesen, um Injection-Umgehungen zu verhindern. ### `block-kubectl` @@ -321,7 +321,7 @@ Mit dieser Konfiguration ist `kubectl get pods` erlaubt, aber `kubectl apply -f ### `block-gh-pipeline` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert die folgenden `gh`-CLI-Unterbefehle, die Zustand mutieren oder Pipelines auslösen: +**Standard:** Verweigert die folgenden `gh`-CLI-Unterbefehle, die Zustand verändern oder Pipelines auslösen: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -336,7 +336,7 @@ Schreibgeschützte `gh`-Unterbefehle wie `gh pr view`, `gh pr list`, `gh run lis | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Spezifische geskriptete Aufrufe, die erlaubt werden sollen, obwohl sie sonst verweigert würden. | +| `allowPatterns` | `string[]` | `[]` | Bestimmte skriptierte Aufrufe, die erlaubt werden sollen, obwohl sie andernfalls verweigert würden. | **Beispiel:** @@ -354,11 +354,11 @@ Schreibgeschützte `gh`-Unterbefehle wie `gh pr view`, `gh pr list`, `gh run lis ## Secrets (Sanitizer) -Verhindert, dass Agenten Zugangsdaten in ihren Kontext oder ihre Ausgabe einschleusen. Sanitizer-Richtlinien werden bei **PostToolUse**-Ereignissen ausgelöst. Wenn Claude einen Bash-Befehl ausführt, eine Datei liest oder ein Tool aufruft, überprüfen diese Richtlinien die Ausgabe, bevor sie an Claude zurückgegeben wird. Wenn ein Secret-Muster erkannt wird, gibt die Richtlinie eine deny-Entscheidung zurück, die verhindert, dass die Ausgabe weitergeleitet wird. +Verhindert, dass Agenten Anmeldeinformationen in ihren Kontext oder ihre Ausgabe einschleusen. Sanitizer-Richtlinien werden bei **PostToolUse**-Ereignissen ausgelöst. Wenn Claude einen Bash-Befehl ausführt, eine Datei liest oder ein beliebiges Werkzeug aufruft, überprüfen diese Richtlinien die Ausgabe, bevor sie an Claude zurückgegeben wird. Wird ein Secret-Muster erkannt, gibt die Richtlinie eine deny-Entscheidung zurück, die verhindert, dass die Ausgabe weitergeleitet wird. ### `sanitize-jwt` -**Ereignis:** PostToolUse (alle Tools) +**Ereignis:** PostToolUse (alle Werkzeuge) **Standard:** Schwärzt JWT-Token (drei base64url-Segmente, getrennt durch `.`). Keine Parameter. @@ -367,8 +367,8 @@ Keine Parameter. ### `sanitize-api-keys` -**Ereignis:** PostToolUse (alle Tools) -**Standard:** Schwärzt gängige API-Schlüsselformate: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS-Zugriffsschlüssel (`AKIA`), Stripe-Schlüssel (`sk_live_`, `sk_test_`) und Google-API-Schlüssel (`AIza`). +**Ereignis:** PostToolUse (alle Werkzeuge) +**Standard:** Schwärzt gängige API-Key-Formate: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS-Zugriffsschlüssel (`AKIA`), Stripe-Schlüssel (`sk_live_`, `sk_test_`) und Google-API-Schlüssel (`AIza`). **Parameter:** @@ -395,8 +395,8 @@ Keine Parameter. ### `sanitize-connection-strings` -**Ereignis:** PostToolUse (alle Tools) -**Standard:** Schwärzt Datenbankverbindungszeichenketten mit eingebetteten Zugangsdaten (z. B. `postgresql://user:password@host/db`). +**Ereignis:** PostToolUse (alle Werkzeuge) +**Standard:** Schwärzt Datenbankverbindungsstrings mit eingebetteten Anmeldeinformationen (z.B. `postgresql://user:password@host/db`). Keine Parameter. @@ -404,7 +404,7 @@ Keine Parameter. ### `sanitize-private-key-content` -**Ereignis:** PostToolUse (alle Tools) +**Ereignis:** PostToolUse (alle Werkzeuge) **Standard:** Schwärzt PEM-Blöcke (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` usw.). Keine Parameter. @@ -413,7 +413,7 @@ Keine Parameter. ### `sanitize-bearer-tokens` -**Ereignis:** PostToolUse (alle Tools) +**Ereignis:** PostToolUse (alle Werkzeuge) **Standard:** Schwärzt `Authorization: Bearer `-Header, bei denen das Token 20 oder mehr Zeichen lang ist. Keine Parameter. @@ -422,14 +422,14 @@ Keine Parameter. ## Umgebung -Schützt sensible Umgebungskonfigurationen davor, von Agenten gelesen oder offengelegt zu werden. +Schützt sensible Umgebungskonfiguration vor dem Lesen oder Offenlegen durch Agenten. ### `block-env-files` **Ereignis:** PreToolUse (Bash, Read) -**Standard:** Verweigert das Lesen von `.env`-Dateien über `cat .env`, Read-Tool-Aufrufe mit `.env` als Dateipfad usw. +**Standard:** Verweigert das Lesen von `.env`-Dateien über `cat .env`, `Read`-Werkzeugaufrufe mit `.env` als Dateipfad usw. -Blockiert nicht `.envrc` oder andere umgebungsnahe Dateien — nur Dateien, die exakt `.env` heißen. +Blockiert nicht `.envrc` oder andere umgebungsähnliche Dateien — nur Dateien mit dem exakten Namen `.env`. Keine Parameter. @@ -446,12 +446,12 @@ Keine Parameter. ## Dateizugriff -Hält Agenten innerhalb der Projektgrenzen und fernab von sensiblen Dateien. +Hält Agenten innerhalb der Projektgrenzen und von sensiblen Dateien fern. ### `block-read-outside-cwd` **Ereignis:** PreToolUse (Read, Bash) -**Standard:** Verweigert das Lesen von Dateien außerhalb des Projektstamms. Die Grenze ist `CLAUDE_PROJECT_DIR` (einmal pro Sitzung von Claude Code gesetzt), mit einem Fallback auf das aktuelle Arbeitsverzeichnis der Sitzung, wenn diese Variable nicht gesetzt ist. Die Verwendung des Projektstamms statt des aktuellen `cwd` sorgt dafür, dass die Grenze stabil bleibt, auch wenn Claude per `cd` in ein Unterverzeichnis wechselt. +**Standard:** Verweigert das Lesen von Dateien außerhalb des Projektstamms. Die Grenze ist `CLAUDE_PROJECT_DIR` (einmalig pro Sitzung von Claude Code gesetzt), mit einem Fallback auf das aktuelle Arbeitsverzeichnis der Sitzung, wenn diese Variable nicht gesetzt ist. Die Verwendung des Projektstamms statt des aktuellen `cwd` bedeutet, dass die Grenze stabil bleibt, auch wenn Claude in ein Unterverzeichnis wechselt. **Parameter:** @@ -476,7 +476,7 @@ Hält Agenten innerhalb der Projektgrenzen und fernab von sensiblen Dateien. ### `block-secrets-write` **Ereignis:** PreToolUse (Write, Edit) -**Standard:** Verweigert Schreibvorgänge in Dateien, die häufig für private Schlüssel und Zertifikate verwendet werden: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Standard:** Verweigert Schreibzugriffe auf Dateien, die häufig für private Schlüssel und Zertifikate verwendet werden: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parameter:** @@ -534,7 +534,7 @@ Um das Pushen auf alle Branches zu erlauben (was diese Richtlinie effektiv deakt ### `block-work-on-main` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert `git commit`, `git merge`, `git rebase` und `git cherry-pick`, wenn sich der Working Tree auf `main` oder `master` befindet. Branch-Erstellung und -Wechsel (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) sind nicht betroffen. +**Standard:** Verweigert `git commit`, `git merge`, `git rebase` und `git cherry-pick`, wenn sich der Arbeitsbaum auf `main` oder `master` befindet. Branch-Erstellung und -Wechsel (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) sind nicht betroffen. **Parameter:** @@ -566,7 +566,7 @@ Keine richtlinienspezifischen Parameter. Verwenden Sie das übergreifende [`hint ### `warn-git-amend` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, beim Ausführen von `git commit --amend` vorsichtig vorzugehen. Blockiert den Befehl nicht. +**Standard:** Weist Claude an, vorsichtig vorzugehen, wenn `git commit --amend` ausgeführt wird. Blockiert den Befehl nicht. Keine Parameter. @@ -575,7 +575,7 @@ Keine Parameter. ### `warn-git-stash-drop` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, vor dem Ausführen von `git stash drop` eine Bestätigung einzuholen. Blockiert den Befehl nicht. +**Standard:** Weist Claude an, vor der Ausführung von `git stash drop` zu bestätigen. Blockiert den Befehl nicht. Keine Parameter. @@ -584,7 +584,7 @@ Keine Parameter. ### `warn-all-files-staged` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, zu überprüfen, was es staged, wenn es `git add -A` oder `git add .` ausführt. Blockiert den Befehl nicht. +**Standard:** Weist Claude an, zu überprüfen, was es stagt, wenn `git add -A` oder `git add .` ausgeführt wird. Blockiert den Befehl nicht. Keine Parameter. @@ -597,7 +597,7 @@ Fängt destruktive SQL-Operationen ab, bevor sie gegen Ihre Datenbank ausgeführ ### `warn-destructive-sql` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, eine Bestätigung einzuholen, bevor SQL mit `DROP TABLE`, `DROP DATABASE` oder `DELETE` ohne `WHERE`-Klausel ausgeführt wird. +**Standard:** Weist Claude an, zu bestätigen, bevor SQL mit `DROP TABLE`, `DROP DATABASE` oder `DELETE` ohne `WHERE`-Klausel ausgeführt wird. Keine Parameter. @@ -606,7 +606,7 @@ Keine Parameter. ### `warn-schema-alteration` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, eine Bestätigung einzuholen, bevor `ALTER TABLE`-Anweisungen ausgeführt werden. +**Standard:** Weist Claude an, zu bestätigen, bevor `ALTER TABLE`-Anweisungen ausgeführt werden. Keine Parameter. @@ -619,13 +619,13 @@ Gibt Agenten zusätzlichen Kontext vor potenziell riskanten, aber nicht destrukt ### `warn-large-file-write` **Ereignis:** PreToolUse (Write) -**Standard:** Weist Claude an, eine Bestätigung einzuholen, bevor Dateien mit mehr als 1024 KB geschrieben werden. +**Standard:** Weist Claude an, zu bestätigen, bevor Dateien größer als 1024 KB geschrieben werden. **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Dateigrößenschwellenwert in Kilobyte, ab dem eine Warnung ausgegeben wird. | +| `thresholdKb` | `number` | `1024` | Dateigrößenschwelle in Kilobyte, ab der eine Warnung ausgegeben wird. | **Beispiel:** @@ -640,7 +640,7 @@ Gibt Agenten zusätzlichen Kontext vor potenziell riskanten, aber nicht destrukt ``` -Der Hook-Handler erzwingt ein stdin-Limit von 1 MB für Payloads. Um diese Richtlinie mit kleinen Inhalten zu testen, setzen Sie `thresholdKb` auf einen Wert deutlich unter 1024. +Der Hook-Handler erzwingt ein 1-MB-stdin-Limit für Payloads. Um diese Richtlinie mit kleinen Inhalten zu testen, setzen Sie `thresholdKb` auf einen Wert deutlich unterhalb von 1024. --- @@ -648,7 +648,7 @@ Der Hook-Handler erzwingt ein stdin-Limit von 1 MB für Payloads. Um diese Richt ### `warn-package-publish` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, eine Bestätigung einzuholen, bevor `npm publish` ausgeführt wird. +**Standard:** Weist Claude an, zu bestätigen, bevor `npm publish` ausgeführt wird. Keine Parameter. @@ -657,7 +657,7 @@ Keine Parameter. ### `warn-background-process` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, beim Starten von Hintergrundprozessen über `nohup`, `&`, `disown` oder `screen` vorsichtig zu sein. +**Standard:** Weist Claude an, vorsichtig zu sein, wenn Hintergrundprozesse über `nohup`, `&`, `disown` oder `screen` gestartet werden. Keine Parameter. @@ -666,7 +666,7 @@ Keine Parameter. ### `warn-global-package-install` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, eine Bestätigung einzuholen, bevor `npm install -g`, `yarn global add` oder `pip install` ohne virtuelle Umgebung ausgeführt wird. +**Standard:** Weist Claude an, zu bestätigen, bevor `npm install -g`, `yarn global add` oder `pip install` ohne virtuelle Umgebung ausgeführt wird. Keine Parameter. @@ -686,9 +686,9 @@ Erkennt: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, po | Parameter | Typ | Standard | Beschreibung | |-----------|------|---------|-------------| | `allowed` | string[] | `[]` | Erlaubte Paketmanager-Namen. Jeder erkannte Manager, der nicht in dieser Liste steht, wird blockiert. Wenn leer, ist die Richtlinie wirkungslos. | -| `blocked` | string[] | `[]` | Zusätzliche Manager-Namen, die über die integrierte Liste hinaus blockiert werden sollen (z. B. `['pdm', 'pipx']`). | +| `blocked` | string[] | `[]` | Zusätzliche Manager-Namen, die über die eingebaute Liste hinaus blockiert werden sollen (z.B. `['pdm', 'pipx']`). | -Die integrierte Blockliste umfasst: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Verwenden Sie `blocked`, um Manager hinzuzufügen, die nicht in dieser Liste enthalten sind. +Die eingebaute Blockliste umfasst: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Verwenden Sie `blocked`, um Manager hinzuzufügen, die nicht in dieser Liste stehen. **Beispielkonfiguration:** @@ -704,7 +704,7 @@ Die integrierte Blockliste umfasst: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, } ``` -Mit dieser Konfiguration werden `pip install flask` und `pdm install flask` beide verweigert, mit einer Meldung, die Claude auffordert, stattdessen `uv` oder `bun` zu verwenden. Befehle wie `uv pip install flask` sind erlaubt, da `uv` in der Allowlist steht und zuerst geprüft wird. +Mit dieser Konfiguration werden `pip install flask` und `pdm install flask` beide verweigert, und Claude wird angewiesen, stattdessen `uv` oder `bun` zu verwenden. Befehle wie `uv pip install flask` sind erlaubt, da `uv` in der Allowlist steht und zuerst geprüft wird. --- @@ -714,8 +714,8 @@ Erkennt, wenn Agenten feststecken oder sich unerwartet verhalten. ### `warn-repeated-tool-calls` -**Ereignis:** PreToolUse (alle Tools) -**Standard:** Weist Claude an, seine Vorgehensweise zu überdenken, wenn dasselbe Tool 3 oder mehr Mal mit identischen Parametern aufgerufen wird — ein häufiges Zeichen dafür, dass der Agent in einer Schleife feststeckt. +**Ereignis:** PreToolUse (alle Werkzeuge) +**Standard:** Weist Claude an, zu überdenken, wenn dasselbe Werkzeug 3 oder mehr Mal mit identischen Parametern aufgerufen wird — ein häufiges Zeichen dafür, dass der Agent in einer Schleife feststeckt. Keine Parameter. @@ -723,39 +723,39 @@ Keine Parameter. ## Workflow -Erzwingt einen disziplinierten End-of-Session-Workflow. Diese Richtlinien werden beim **Stop**-Ereignis ausgelöst und verhindern, dass der Agent stoppt, bis jede Bedingung erfüllt ist. Sie folgen einer natürlichen Abhängigkeitskette: Commit → Push → PR → CI. Wenn eine Richtlinie verweigert, werden spätere Richtlinien in der Kette übersprungen (Deny ist Kurzschluss). +Erzwingt einen disziplinierten End-of-Session-Workflow. Diese Richtlinien werden beim **Stop**-Ereignis ausgelöst und verhindern, dass der Agent stoppt, bis jede Bedingung erfüllt ist. Sie folgen einer natürlichen Abhängigkeitskette: Commit → Push → PR → CI. Wenn eine Richtlinie verweigert, werden spätere Richtlinien in der Kette übersprungen (deny schließt kurz). -Alle Workflow-Richtlinien sind **fail-open**: Wenn das erforderliche Tool nicht verfügbar ist (z. B. `gh` nicht installiert, kein Git-Remote), erlaubt die Richtlinie mit einer informativen Meldung, die erklärt, warum die Prüfung übersprungen wurde. +Alle Workflow-Richtlinien sind **fail-open**: Wenn das erforderliche Werkzeug nicht verfügbar ist (z.B. `gh` nicht installiert, kein Git-Remote), erlaubt die Richtlinie mit einer informativen Nachricht, die erklärt, warum die Prüfung übersprungen wurde. ### Stop-Semantik pro CLI -Die Stop-Durchsetzung sieht bei den sechs unterstützten CLIs leicht unterschiedlich aus, da jede einen anderen Vertrag für den „Agent fertig"-Hook exponiert. Das **Ergebnis** ist dasselbe — der Agent kann nicht stoppen, während ein Workflow-Gate fehlschlägt — aber die **Mechanik** unterscheidet sich. Die folgende Tabelle fasst dies zusammen; nur Pi hat eine für den Benutzer sichtbare Eigenheit, die es wert ist, sie zu verstehen, bevor Sie eine `require-*-before-stop`-Richtlinie aktivieren. +Die Stop-Durchsetzung sieht bei den sechs unterstützten CLIs etwas unterschiedlich aus, da jede eine andere Vertragssemantik für den „Agent fertig"-Hook bietet. Das **Ergebnis** ist dasselbe — der Agent kommt nicht damit durch, zu stoppen, während ein Workflow-Gate fehlschlägt — aber die **Mechanismen** unterscheiden sich. Die folgende Tabelle fasst dies zusammen; nur Pi hat eine für den Benutzer sichtbare Eigenheit, die Sie verstehen sollten, bevor Sie eine `require-*-before-stop`-Richtlinie aktivieren. | CLI | Wann das Gate ausgelöst wird | Was Sie sehen | |---|---|---| -| Claude Code | Gleiche Agent-Schleife, sofort | Claude arbeitet weiter — behebt das Problem und versucht dann erneut zu beenden. Für Sie keine sichtbare Unterbrechung. | -| Codex | Gleiche Agent-Schleife, sofort | Wie Claude. | -| GitHub Copilot CLI | Gleiche Agent-Schleife, sofort | Wie Claude (verwendet Copilots `{decision:"block", reason}`-Retry-Kanal — empirisch gegen Copilot CLI 1.0.41 verifiziert). | -| Cursor Agent | Gleiche Agent-Schleife, sofort | Wie Claude (verwendet Cursors `{followup_message}`-Kanal — begrenzt auf `loop_limit`, standardmäßig 5 Wiederholungen). | -| OpenCode | Gleiche Agent-Schleife, sofort | Wie Claude (verwendet OpenCodes `client.session.prompt(...)`-SDK-Aufruf, der über `hookSpecificOutput.additionalContext` weitergeleitet wird). | -| **Pi (pi-coding-agent)** | **Nächster Benutzerturn** | **Pi stoppt sichtbar**, wenn das Gate ausgelöst wird — seine Agent-Schleife beendet sich und Sie kehren zur Eingabeaufforderung zurück. Das Gate wird beim nächsten eingereichten Prompt ausgelöst: failproofai stellt eine `MANDATORY ACTION REQUIRED`-Direktive dem System-Prompt dieses Turns voran und weist das LLM an, den Workflow-Schritt (Commit, Push usw.) abzuschließen, bevor es das Angeforderte tut. | +| Claude Code | Gleiche Agentenschleife, sofort | Claude arbeitet weiter — behebt das Problem und versucht dann erneut zu beenden. Für Sie keine sichtbare Unterbrechung. | +| Codex | Gleiche Agentenschleife, sofort | Wie Claude. | +| GitHub Copilot CLI | Gleiche Agentenschleife, sofort | Wie Claude (verwendet Copilots `{decision:"block", reason}`-Retry-Kanal — empirisch gegen Copilot CLI 1.0.41 verifiziert). | +| Cursor Agent | Gleiche Agentenschleife, sofort | Wie Claude (verwendet Cursors `{followup_message}`-Kanal — begrenzt auf `loop_limit`, standardmäßig 5 Wiederholungen). | +| OpenCode | Gleiche Agentenschleife, sofort | Wie Claude (verwendet OpenCodes `client.session.prompt(...)`-SDK-Aufruf, der über `hookSpecificOutput.additionalContext` geleitet wird). | +| **Pi (pi-coding-agent)** | **Nächste Benutzerrunde** | **Pi stoppt sichtbar**, wenn das Gate ausgelöst wird — seine Agentenschleife beendet sich und Sie kehren zur Eingabeaufforderung zurück. Das Gate löst dann beim nächsten Einreichen einer Eingabe aus: failproofai stellt eine `MANDATORY ACTION REQUIRED`-Direktive an den System-Prompt dieser Runde voran und weist das LLM an, den Workflow-Schritt (Commit, Push usw.) abzuschließen, bevor es Ihre Anfrage bearbeitet. | -**Pi-Einschränkung.** Pis `AgentEndEvent` (das Upstream-Äquivalent von Claudes Stop-Hook) hat keinen Result-Typ — wenn es ausgelöst wird, hat Pis Agent-Schleife bereits beendet. Pi kann nicht gezwungen werden, dieselbe Schleife zu wiederholen wie Claude / Copilot / Cursor / OpenCode. failproofai verschiebt das Gate auf Pis `before_agent_start`-Ereignis (das nach dem nächsten Benutzer-Prompt ausgelöst wird), sodass die Workflow-Prüfung noch durchgesetzt wird, nur beim nächsten Turn statt beim aktuellen. +**Pi-Einschränkung.** Pi's `AgentEndEvent` (das Upstream-Äquivalent von Claudes `Stop`-Hook) hat keinen Result-Typ — wenn er ausgelöst wird, hat Pi's Agentenschleife bereits beendet. Pi kann nicht gezwungen werden, dieselbe Schleife wie Claude / Copilot / Cursor / OpenCode zu wiederholen. failproofai verlagert das Gate auf Pi's `before_agent_start`-Ereignis (das nach dem nächsten Benutzer-Prompt ausgelöst wird), sodass die Workflow-Prüfung noch durchgesetzt wird, nur in der nächsten Runde statt der aktuellen. **Was das in der Praxis bedeutet:** -- Nachdem Pi stoppt, wird der deny-Grund im Speicher gespeichert, indexiert nach Pi-Session-ID. Der allernächste Prompt, den Sie im selben Pi-Prozess einreichen, leert ihn: Das LLM sieht die `MANDATORY ACTION REQUIRED`-Direktive am Anfang seines System-Prompts, committet (oder pusht / öffnet den PR / wartet auf CI) und fährt erst dann mit Ihrer Anfrage fort. Der gespeicherte deny-Grund ist einmalig — nach dem Leeren ist das Gate frei. -- Das Gate ist an die Prozesslebensdauer von Pi gebunden. Wenn Sie Pi mit `Ctrl+C` beenden oder zwischen den Turns verlassen, wird der In-Memory-Eintrag zusammen mit dem Prozess verworfen und das Gate wird verpasst. Claude, Copilot, Cursor und OpenCode haben dieselbe Bindung (Agent töten und das Gate wird verpasst) — Pi macht es nur sichtbarer, da der Agent sichtbar beendet wird, bevor das Gate ausgelöst wird. -- Ein ausstehender deny wird auch bei `session_shutdown` aus beliebigem Grund (`new` / `resume` / `fork` / `quit`) gelöscht, sodass ein veraltetes Gate einer vorherigen Sitzung nicht in eine neue Sitzung im selben Pi-Prozess überlaufen kann. +- Nachdem Pi stoppt, wird der deny-Grund im Speicher nach Pi-Sitzungs-ID gespeichert. Der nächste Prompt, den Sie im selben Pi-Prozess einreichen, leert ihn: Das LLM sieht die `MANDATORY ACTION REQUIRED`-Direktive am Anfang seines System-Prompts, führt Commit (oder Push / öffnet den PR / wartet auf CI) durch und fährt dann erst mit Ihrer Anfrage fort. Der gespeicherte deny-Grund ist einmalig — einmal geleert, ist das Gate frei. +- Das Gate ist an die Prozesslebensdauer von Pi gebunden. Wenn Sie Pi zwischen den Runden mit `Ctrl+C` beenden oder schließen, wird der In-Memory-Eintrag zusammen mit dem Prozess verworfen und das Gate wird verpasst. Claude, Copilot, Cursor und OpenCode haben dieselbe Bindung (Agent beenden und das Gate wird verpasst) — Pi macht es nur sichtbarer, da der Agent sichtbar beendet wird, bevor das Gate auslöst. +- Ein ausstehender deny wird auch bei `session_shutdown` aus beliebigem Grund (`new` / `resume` / `fork` / `quit`) gelöscht, sodass ein veraltetes Gate aus einer früheren Sitzung nicht in eine neue Sitzung im selben Pi-Prozess übergeht. -Wenn Sie den gleich-Schleife-Retry im Claude-Stil benötigen, führen Sie Ihre Stop-Richtlinien unter einem der anderen fünf unterstützten CLIs aus. Wir verfolgen Pi Upstream auf einen zukünftigen Result-Typ bei `AgentEndEvent`, der es uns ermöglichen würde, diese Lücke zu schließen. +Wenn Sie Claude-ähnliche Same-Loop-Wiederholung benötigen, führen Sie Ihre `Stop`-Richtlinien unter einer der anderen fünf unterstützten CLIs aus. Wir beobachten Pi upstream auf einen zukünftigen Result-Typ bei `AgentEndEvent`, der es uns ermöglichen würde, diese Lücke zu schließen. ### `require-commit-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn uncommittete Änderungen vorhanden sind (geänderte, gestagete oder untracked Dateien). Gibt eine informative Meldung zurück, wenn das Arbeitsverzeichnis sauber ist. +**Standard:** Verweigert das Stoppen, wenn nicht committete Änderungen vorhanden sind (geänderte, gestagte oder nicht verfolgte Dateien). Gibt eine informative Nachricht zurück, wenn das Arbeitsverzeichnis sauber ist. Keine Parameter. @@ -764,13 +764,13 @@ Keine Parameter. ### `require-push-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn es ungepushte Commits gibt oder wenn der aktuelle Branch keinen Remote-Tracking-Branch hat. Schlägt `git push -u` vor, um bei Bedarf einen Tracking-Branch zu erstellen. Fail-open, wenn kein Remote konfiguriert ist. +**Standard:** Verweigert das Stoppen, wenn nicht gepushte Commits vorhanden sind oder wenn der aktuelle Branch keinen Remote-Tracking-Branch hat. Schlägt `git push -u` vor, um einen Tracking-Branch zu erstellen, falls nötig. Schlägt offen fehl, wenn kein Remote konfiguriert ist. **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Remote-Name, auf den gepusht werden soll. | +| `remote` | `string` | `"origin"` | Remote-Name, zu dem gepusht werden soll. | **Beispiel:** @@ -789,14 +789,14 @@ Keine Parameter. ### `require-pr-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn kein Pull Request für den aktuellen Branch existiert oder wenn der vorhandene PR ohne Merge geschlossen wurde. Weist Claude an, einen PR mit `gh pr create` zu erstellen. Wenn der PR **gemergt** wurde, erlaubt die Richtlinie (die Arbeit ist ausgeliefert) und die Meldung weist darauf hin, vom Branch zu wechseln (`git checkout main && git pull`). +**Standard:** Verweigert das Stoppen, wenn kein Pull Request für den aktuellen Branch existiert oder wenn der vorhandene PR ohne Merge geschlossen wurde. Weist Claude an, einen PR mit `gh pr create` zu erstellen. Wenn der PR **gemergt** wurde, erlaubt die Richtlinie (die Arbeit ist veröffentlicht) und die Nachricht gibt den Hinweis, den Branch zu wechseln (`git checkout main && git pull`). Keine Parameter. Diese Richtlinie erfordert, dass [GitHub CLI](https://cli.github.com/) (`gh`) installiert und authentifiziert ist. Führen Sie `gh auth login` mit einem Personal Access Token aus, das `repo`-Scope für Lesezugriff auf -Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, ist die Richtlinie fail-open und berichtet den Grund an Claude. +Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, schlägt die Richtlinie offen fehl und meldet den Grund an Claude. --- @@ -804,12 +804,12 @@ Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, i ### `require-no-conflicts-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn der aktuelle Branch nicht sauber in den Basis-Branch gemergt werden kann. Die Richtlinie bestätigt zunächst, dass ein `OPEN`-PR auf GitHub für den Branch vorhanden ist — ohne einen gibt es kein Merge-Ziel zum Durchsetzen, sodass die gesamte Richtlinie mit allow kurzschließt. Sobald ein `OPEN`-PR bestätigt ist, laufen zwei unabhängige Prüfungen: +**Standard:** Verweigert das Stoppen, wenn der aktuelle Branch nicht sauber in den Basis-Branch gemergt werden kann. Die Richtlinie bestätigt zunächst, dass ein `OPEN` PR auf GitHub für den Branch existiert — ohne einen solchen gibt es kein Merge-Ziel zum Durchsetzen, sodass die gesamte Richtlinie zu allow kurz schließt. Sobald ein `OPEN` PR bestätigt ist, laufen zwei unabhängige Prüfungen: -1. **Lokal** — `git merge-tree --write-tree --name-only origin/ HEAD`. Bei einem Konflikt nennt die deny-Meldung die konfliktierenden Dateien, damit Claude genau weiß, was zu lösen ist. -2. **GitHub** — verwendet das bereits bei der Vorabprüfung abgerufene `gh pr view --json mergeable,state`-Ergebnis. Fängt Konflikte ab, die ein veraltetes lokales `origin/` verpassen würde (z. B. wenn jemand seit dem letzten Fetch einen konfliktierenden PR auf `main` gemergt hat). Ein `CONFLICTING`-Ergebnis verweigert. Ein `UNKNOWN`-Ergebnis verweigert ebenfalls und weist Claude an, etwa 10 Sekunden zu warten und erneut zu prüfen, bevor ein erneuter Stoppversuch unternommen wird — dies verhindert falsch-negative Ergebnisse, während GitHub neu berechnet. +1. **Lokal** — `git merge-tree --write-tree --name-only origin/ HEAD`. Bei einem Konflikt nennt die deny-Nachricht die konfliktbehafteten Dateien, damit Claude genau weiß, was zu lösen ist. +2. **GitHub** — verwendet das bereits beim Vorab-Check abgerufene `gh pr view --json mergeable,state`-Ergebnis. Fängt Konflikte ab, die ein veraltetes lokales `origin/` übersehen würde (z.B. wenn jemand seit dem letzten Fetch einen konfliktbehafteten PR auf `main` gemergt hat). Ein `CONFLICTING`-Ergebnis verweigert. Ein `UNKNOWN`-Ergebnis verweigert ebenfalls und weist Claude an, ca. 10 Sekunden zu warten und erneut zu prüfen, bevor versucht wird, erneut zu stoppen — dies verhindert falsche Negative, während GitHub neu berechnet. -Überspringt komplett (erlaubt), wenn: `gh` nicht installiert ist, kein PR für den Branch existiert, der PR-Status nicht `OPEN` ist (z. B. `MERGED`, `CLOSED`), oder `gh pr view` nicht parsbare Ausgabe zurückgibt. Fail-open auch, wenn `origin/` lokal fehlt oder wenn keine Commits vor der Basis vorhanden sind — diese Layer-1-Fallbacks konsultieren die gecachte PR-Mergbarkeit noch, bevor sie erlauben. +Überspringt vollständig (erlaubt), wenn: `gh` nicht installiert ist, kein PR für den Branch existiert, der PR-Status nicht `OPEN` ist (z.B. `MERGED`, `CLOSED`) oder `gh pr view` nicht parsbare Ausgabe zurückgibt. Schlägt auch offen fehl, wenn `origin/` lokal fehlt oder wenn keine Commits vor dem Basis-Commit liegen — diese Layer-1-Fallbacks konsultieren dennoch die zwischengespeicherte PR-Merge-Fähigkeit, bevor sie erlauben. **Parameter:** @@ -819,8 +819,8 @@ Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, i GitHub CLI (`gh`) ist für diese Richtlinie erforderlich. Die Richtlinie verwendet `gh pr view`, um zu bestätigen, -dass ein `OPEN`-PR vorhanden ist, bevor eine Konfliktprüfung durchgeführt wird — ohne `gh` schließt die Richtlinie -mit allow kurz. Führen Sie `gh auth login` mit einem Personal Access Token aus, das +dass ein `OPEN` PR existiert, bevor eine Konfliktprüfung ausgeführt wird — ohne `gh` schließt die Richtlinie +zu allow kurz. Führen Sie `gh auth login` mit einem Personal Access Token aus, das `repo`-Scope für Lesezugriff auf Pull Requests hat. @@ -829,14 +829,14 @@ mit allow kurz. Führen Sie `gh auth login` mit einem Personal Access Token aus, ### `require-ci-green-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn CI-Prüfungen fehlschlagen oder noch auf dem aktuellen Branch laufen. Prüft sowohl GitHub Actions-Workflow-Runs als auch Drittanbieter-Bot-Prüfungen (z. B. CodeRabbit, SonarCloud, Codecov). Behandelt `skipped`, `cancelled` und `neutral`-Ergebnisse als nicht-fehlschlagend (letzteres deckt z. B. Socket Security-Benachrichtigungen bei PRs externer Mitwirkender ab, bei denen die App absichtlich neutral statt success/failure meldet). Gibt eine informative Meldung zurück, wenn alle Prüfungen bestehen. +**Standard:** Verweigert das Stoppen, wenn CI-Prüfungen fehlschlagen oder auf dem aktuellen Branch noch laufen. Prüft sowohl GitHub Actions-Workflow-Runs als auch Drittanbieter-Bot-Prüfungen (z.B. CodeRabbit, SonarCloud, Codecov). Behandelt `skipped`, `cancelled` und `neutral`-Schlussfolgerungen als nicht fehlschlagend (letzteres deckt z.B. Socket Security-Warnungen bei PRs externer Mitwirkender ab, wo die App absichtlich neutral statt Erfolg/Misserfolg meldet). Gibt eine informative Nachricht zurück, wenn alle Prüfungen bestehen. Keine Parameter. Diese Richtlinie erfordert, dass [GitHub CLI](https://cli.github.com/) (`gh`) installiert und authentifiziert ist. Führen Sie `gh auth login` mit einem Personal Access Token aus, das `repo`-Scope für Lesezugriff auf -Actions-Workflow-Runs und die Checks-API hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, ist die Richtlinie fail-open und berichtet den Grund an Claude. +Actions-Workflow-Runs und die Checks-API hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, schlägt die Richtlinie offen fehl und meldet den Grund an Claude. --- @@ -845,7 +845,7 @@ Actions-Workflow-Runs und die Checks-API hat. Wenn `gh` nicht installiert oder n ## Einzelne Richtlinien deaktivieren -Entfernen Sie eine bestimmte Richtlinie aus `enabledPolicies` in Ihrer Konfiguration oder deaktivieren Sie sie im Policies-Tab des Dashboards. +Entfernen Sie eine bestimmte Richtlinie aus `enabledPolicies` in Ihrer Konfiguration oder deaktivieren Sie sie im Dashboard-Tab „Policies". ```json { diff --git a/docs/de/cli/audit.mdx b/docs/de/cli/audit.mdx index 5e8476f0..b4593bc4 100644 --- a/docs/de/cli/audit.mdx +++ b/docs/de/cli/audit.mdx @@ -1,18 +1,19 @@ --- title: Vergangene Sitzungen prüfen (Beta) -description: "Zählt, wie oft der Agent in vergangenen Transkripten verschwenderische oder riskante Aktionen durchgeführt hat" +description: "Zählt, wie oft der Agent in vergangenen Transkripten unnötige oder riskante Aktionen durchgeführt hat" --- - **Beta-Funktion.** Die Audit-Funktion wird als Beta veröffentlicht, während wir erstes Feedback sammeln. - Der Detektor-Katalog und das Berichtsformat können sich vor dem nächsten stabilen - Release ändern. Bitte eröffne ein Issue, falls etwas nicht stimmt. + **Beta-Funktion.** Das Audit wird als Beta ausgeliefert, während wir erstes + Feedback sammeln. Der Detektor-Katalog und das Berichtsformat können sich vor + dem nächsten stabilen Release ändern. Bitte eröffne ein Issue, wenn etwas + nicht stimmt. -Das Audit spielt vergangene Agent-CLI-Transkripte durch failproofais Policy-Engine -und zeigt einen teilbaren, visuellen Bericht auf der **`/audit`-Dashboard-Seite** an — -den Archetypen deines Agenten, einen Score von 0–100 und genau welche Policies -was erkannt hätten. +Das Audit spielt deine vergangenen Agent-CLI-Transkripte durch failproofais +Policy-Engine ab und erstellt einen teilbaren, visuellen Bericht auf der +**`/audit`-Dashboard-Seite** — den Archetyp deines Agenten, einen Score von +0–100 und genau welche Policies was abgefangen hätten. ## Ausführen @@ -35,97 +36,133 @@ failproofai - - `npx -y failproofai audit` lädt failproofai herunter, führt den Scan durch und öffnet das - Dashboard für dich — ohne vorherige Installation. + + `npx -y failproofai audit` lädt failproofai herunter, führt den Scan durch + und öffnet das Dashboard für dich — nichts muss vorher installiert werden. - `failproofai audit` führt den Scan im Terminal aus und öffnet - `localhost:8020/audit` automatisch nach Abschluss. + `failproofai audit` führt den Scan im Terminal aus und öffnet anschließend + automatisch `localhost:8020/audit`. - Starte `failproofai` und klicke in der Navigationsleiste auf **Audit** (zwischen Policies und - Projects), oder öffne `/audit` direkt. + Starte `failproofai` und klicke in der Navigationsleiste auf **Audit** + (zwischen Policies und Projects), oder öffne `/audit` direkt. - Führe `failproofai audit -h` (oder `--help`) aus, um die Nutzungshinweise anzuzeigen. Das Audit läuft **vollständig - offline** — kein Konto oder Netzwerk erforderlich — und das Dashboard bleibt aktiv, - bis du es mit `Ctrl+C` beendest. + Führe `failproofai audit -h` (oder `--help`) aus, um die Verwendung + anzuzeigen. Das Audit läuft **vollständig offline** — kein Konto oder + Netzwerk erforderlich — und das Dashboard bleibt aktiv, bis du es mit + `Ctrl+C` stoppst. -Das Dashboard scannt vergangene Agent-CLI-Transkripte auf diesem Rechner (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) und zeigt an, wie oft der Agent Dinge getan hat, die failproofai verhindern soll — Umgebungsvariablen-Prüfungen, Force-Pushes, redundante `cd `-Präfixe, Sleep-Polling-Schleifen, erneutes Lesen gerade bearbeiteter Dateien und mehr. +Das Dashboard scannt vergangene Agent-CLI-Transkripte auf diesem Rechner (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) und zeigt an, wie oft der Agent Dinge getan hat, die failproofai verhindern soll — Umgebungsvariablen-Checks, Force-Pushes, redundante `cd `-Präfixe, Sleep-Polling-Schleifen, erneutes Lesen gerade bearbeiteter Dateien und mehr. -Für jedes Transkript wird jedes Tool-Use-Ereignis durch die 39 integrierten Policies **und** durch 8 audit-exklusive Detektoren wiedergegeben, die Muster erkennen, die noch nicht durch Laufzeit-Policies abgedeckt sind. Die Zählungen werden pro Policy/Detektor über alle Sitzungen hinweg aggregiert. +Für jedes Transkript wird jedes Tool-Use-Ereignis durch die 39 eingebauten Policies **und** durch 8 audit-exklusive Detektoren abgespielt, die Muster erkennen, die von den Laufzeit-Policies noch nicht abgedeckt werden. Die Häufigkeiten werden pro Policy/Detektor über alle Sitzungen aggregiert. ## Was du erhältst -Die `/audit`-Seite ist ein einseitiges, teilbares **Poster** gefolgt von vier weiteren Abschnitten unterhalb des sichtbaren Bereichs: +Die `/audit`-Seite ist ein einzeiliges, teilbares **Poster** gefolgt von vier +Abschnitten unterhalb: -1. **Poster** — die Identität deines Agenten auf einen Blick: sein **Archetyp** (einer von 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), seine Persona-Schlagwörter, wie selten dieser Archetyp ist, und ein **Score von 0–100** mit einer Tier-Einstufung (`S` bis `bottom tier`). Zum Teilen gedacht — poste es auf X oder LinkedIn, oder lade es als PNG herunter. -2. **`// strengths`** — was dein Agent bereits gut macht, als echte Zahlen aus dem Scan (z. B. Clean-Tool-Call-%, `0` Push-to-Main-Versuche), nur angezeigt, wo die betreffende Policy eine saubere Bilanz hat. -3. **`// quirks`** — was durchgerutscht ist: eine priorisierte Tabelle mit Verhaltensweisen, die failproofai abgefangen hätte — *wann* es zuletzt passiert ist, *was durchgerutscht ist* (und das integrierte Policy, das es blockiert hätte), der *Schweregrad* und wie oft es *aufgetreten* ist (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — die empfohlene Behebungsliste: eine Zeile pro Policy mit einem kopierbaren `failproofai policy add `, plus einem **Install all**-Button, der alle Empfehlungen auf einmal aktiviert und deinen **voraussichtlichen Score** anzeigt. -5. **`// come back better`** — baue eine Gewohnheit auf: setze eine E-Mail-**Erinnerung** für das nächste Audit (`3d` / `7d` / `14d` / `30d`) oder starte jetzt ein erneutes Audit, und **lade einen Freund** ein, sein eigenes Audit durchzuführen (gesendet von failproof.ai, Cc an dich). Erinnerungen und Einladungen erfordern eine Anmeldung. +1. **Poster** — die Identität deines Agenten auf einen Blick: sein **Archetyp** (einer von 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), seine Persona-Schlüsselwörter, wie selten dieser Archetyp ist, und ein **Score von 0–100** mit einer Tier-Einstufung (`S` bis `bottom tier`). Zum Teilen gedacht — poste ihn auf X oder LinkedIn oder lade ihn als PNG herunter. +2. **`// strengths`** — was dein Agent bereits gut macht, als echte Zahlen aus dem Scan (z. B. Anteil sauberer Tool-Aufrufe, `0` Push-to-main-Versuche), nur angezeigt, wenn die betreffende Policy eine saubere Bilanz hat. +3. **`// quirks`** — was durchgerutscht ist: eine sortierte Tabelle der Verhaltensweisen, die failproofai abgefangen hätte — *wann* es zuletzt passiert ist, *was durchgerutscht ist* (und das eingebaute Policy, das es blockiert hätte), die *Schwere* und wie oft es *vorkam* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — die empfohlene Korrekturnliste: eine Zeile pro Policy mit einem kopierbaren `failproofai policy add `, plus einem **alle installieren**-Button, der alle Empfehlungen auf einmal aktiviert und deinen **projizierten Score** anzeigt. +5. **`// come back better`** — entwickle die Gewohnheit: lege eine E-Mail-**Erinnerung** für ein Re-Audit fest (`3d` / `7d` / `14d` / `30d`) oder führe jetzt ein Re-Audit durch, und **lade einen Freund** ein, sein eigenes Audit durchzuführen (gesendet von failproof.ai, mit dir in Cc). Erinnerungen und Einladungen erfordern eine Anmeldung. ## Geplante Audits Wenn du den **failproofaid-Daemon** ausführst (siehe [`failproofai config`](/de/cli/install-policies)), -kann er das Audit nach einem Zeitplan für dich wiederholen und den `/audit`-Bericht im -Hintergrund aktualisieren. Er ist **standardmäßig deaktiviert**, da der Scan den *Inhalt* -jedes Agent-Sitzungstranskripts auf diesem Rechner liest — nichts scannt nach einem Timer, -bis du es anforderst. - -Aktiviere es in `~/.failproofai/config.toml`: - -```toml -[audit] -auto = true -interval_days = 7 +kann er das Audit planmäßig für dich erneut ausführen und den `/audit`-Bericht +im Hintergrund aktualisieren. Er ist **standardmäßig deaktiviert**, da der Scan +den *Inhalt* jedes Agent-Sitzungstranskripts auf diesem Rechner liest — nichts +wird auf einem Timer gescannt, bis du es anforderst. + +Aktiviere es in `~/.failproofai/config.json` — füge den `audit`-Schlüssel +neben allem anderen hinzu, was die Datei bereits enthält: + +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | Schlüssel | Bedeutung | |---|---| -| `auto` | `true` aktiviert den geplanten Scan. Alles andere — nicht vorhanden, `false`, `"yes"` — ist deaktiviert. | -| `interval_days` | Tage zwischen Scans. Begrenzt auf 1–90; `0`, ein negativer Wert oder ein Nicht-Zahl-Wert fällt auf `7` zurück. | - -- Der Zeitplan basiert auf der **Echtzeit**, übersteht also Suspend und Neustarts: Ein Laptop, - der seinen fälligen Zeitpunkt im Schlafmodus verpasst hat, läuft **einmal** beim Aufwachen — ohne Rückstand. -- Jeder Durchlauf ist ein separater Prozess mit niedriger Priorität (`nice 19`) — nie der Hook-Pfad des Daemons, - der frei bleibt, um Tool-Aufrufe zu beantworten. -- Ein Scan wird übersprungen, wenn `failproofai audit` oder der erneute Durchlauf des Dashboards bereits läuft; er wird kurz danach wiederholt, anstatt als Fehler behandelt zu werden. -- Der Fortschritt wird in `~/.failproofai/state/audit-schedule.json` gespeichert (letzter Durchlauf, - nächste Fälligkeit). Der Daemon besitzt diese Datei — ändere den Rhythmus in `config.toml`. +| `auto` | `true` aktiviert den geplanten Scan. Alles andere — nicht vorhanden, `false`, `"yes"` — bedeutet deaktiviert. | +| `interval_days` | Tage zwischen den Scans. Begrenzt auf 1–90; `0`, ein negativer Wert oder kein numerischer Wert fällt auf `7` zurück. | + +- Der Zeitplan ist **wanduhrenbasiert**, übersteht also Suspend und Neustarts: + Ein Laptop, der während seiner Fälligkeit im Schlafmodus war, läuft beim + Aufwachen **einmal**, nie mit einem Rückstand. +- Jeder Lauf ist ein separater, niedrig priorisierter (`nice 19`) Prozess — + nie der Hook-Pfad des Daemons, der frei bleibt, um Tool-Aufrufe zu + beantworten. +- Ein Scan wird übersprungen, wenn `failproofai audit` oder das Re-Ausführen + des Dashboards bereits läuft; er wird kurz danach erneut versucht, anstatt + als Fehler behandelt zu werden. +- Der Fortschritt wird in `~/.failproofai/state/audit-schedule.json` + gespeichert (letzter Lauf, nächste Fälligkeit). Der Daemon besitzt diese + Datei — ändere den Rhythmus in `config.json`. -Wenn du dies auf einem Rechner aktiviert hast, der mit einer älteren Version von failproofai eingerichtet wurde, führe -einmalig `failproofai config` aus. Die Service-Definition des Daemons benötigt einen zusätzlichen -Eintrag, bevor die CLI gestartet werden kann, und die Aktualisierung ist Teil dieses Befehls. +Wenn du dies auf einem Rechner aktiviert hast, der mit einem älteren +failproofai eingerichtet wurde, führe einmal `failproofai config` aus. Die +Service-Definition des Daemons benötigt einen zusätzlichen Eintrag, bevor er +die CLI starten kann, und die Aktualisierung ist Teil dieses Befehls. ## Audit-exklusive Detektoren -Diese erkennen Muster für „dummes Verhalten", die (noch) nicht in Echtzeit erzwungen werden. Sie laufen nur während des Audits und blockieren niemals einen Live-Tool-Aufruf. +Diese erkennen Muster für „unsinniges Verhalten", die (noch) nicht in Echtzeit +durchgesetzt werden. Sie laufen nur während des Audits und blockieren nie einen +Live-Tool-Aufruf. | Detektor | Was gezählt wird | |---|---| -| `redundant-cd-cwd` | Bash-Befehle, die mit `cd && …` beginnen, obwohl Befehle bereits im `cwd` ausgeführt werden. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` auf einer einzelnen Quelldatei — nutze stattdessen das `Read`-Tool. | -| `prefer-edit-over-sed-awk` | In-Place-Bearbeitungen mit `sed -i` / `awk … > file` — nutze stattdessen das `Edit`-Tool. | -| `prefer-write-over-heredoc` | Heredoc / mehrzeiliges `echo > file` zum Schreiben von Dateien — nutze stattdessen das `Write`-Tool. | -| `sleep-polling-loop` | Langes `sleep N` (≥ 30s) oder `while …; sleep …; done`-Polling-Schleifen. | -| `find-from-root` | `find /`, `find /home`, `find /usr` usw. — schränke auf `cwd` ein. | +| `redundant-cd-cwd` | Bash-Befehle, die mit `cd && …` beginnen, obwohl Befehle bereits in `cwd` ausgeführt werden. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` auf einer einzelnen Quelldatei — verwende stattdessen das `Read`-Tool. | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` In-Place-Bearbeitungen — verwende stattdessen das `Edit`-Tool. | +| `prefer-write-over-heredoc` | Heredoc / mehrzeiliges `echo > file` zum Schreiben von Dateien — verwende stattdessen das `Write`-Tool. | +| `sleep-polling-loop` | Lange `sleep N`-Wartezeiten (≥ 30s) oder `while …; sleep …; done`-Polling-Schleifen. | +| `find-from-root` | `find /`, `find /home`, `find /usr` usw. — beschränke den Bereich auf `cwd`. | | `git-commit-no-verify` | `git commit … --no-verify` / `-n`, überspringt Hooks. | -| `reread-after-edit` | `Read` einer Datei, die gerade in derselben Sitzung mit `Edit`/`Write` bearbeitet wurde. | +| `reread-after-edit` | `Read` einer Datei, die in derselben Sitzung gerade per `Edit`/`Write` bearbeitet wurde. | ## Caches -- **Transkript-spezifischer Cache** unter `~/.failproofai/cache/audit/.json`, nach `(mtime, size, engineVersion, detectorVersion)` geordnet — wird automatisch ungültig, wenn das Transkript oder der Policy-/Detektor-Code sich ändert. Jeder Eintrag enthält auch einen `cachedAt`-Zeitstempel als **TTL-Metadaten** (nicht Teil des Cache-Schlüssels); Einträge, die älter als **7 Tage** sind, werden beim Lesen abgelehnt, damit langlebige Ergebnisse nicht eine sich weiterentwickelnde Detektor-Absicht überleben. -- **Gesamtergebnis-Cache** unter `~/.failproofai/audit-dashboard.json` (Modus 0600). Ermöglicht dem Dashboard eine sofortige Darstellung beim Navigieren ohne erneuten Scan. Wird beim Lesen nach der **7-Tage-TTL** ebenfalls abgelehnt — `/audit` fällt dann in seinen leeren Zustand zurück und fordert einen neuen Durchlauf an. Klicke unten im Bericht auf `[ re-audit now ]`, um zu aktualisieren — ein erneutes Audit sendet `noCache: true`, umgeht damit den transkript-spezifischen Cache und scannt alle Transkripte neu, anstatt das gecachte Ergebnis zurückzugeben; der Durchlauf streamt den Fortschritt über einen fixierten Top-Streifen und tauscht das Ergebnis bei Erfolg direkt aus (kein Seitenneuladn; ein fehlgeschlagenes erneutes Audit behält den vorherigen Bericht). +- **Transkript-bezogener Cache** unter `~/.failproofai/cache/audit/.json`, + indiziert nach `(mtime, size, engineVersion, detectorVersion)` — wird + automatisch ungültig, wenn sich das Transkript oder der Policy-/Detektor-Code + ändert. Jeder Eintrag speichert auch einen `cachedAt`-Zeitstempel als + **TTL-Metadaten** (kein Teil des Cache-Schlüssels); Einträge, die älter als + **7 Tage** sind, werden beim Lesen abgelehnt, damit langlebige Ergebnisse + nicht die Weiterentwicklung der Detektoren überdauern. +- **Gesamtergebnis-Cache** unter `~/.failproofai/audit-dashboard.json` + (Modus 0600). Ermöglicht dem Dashboard, beim Navigieren sofort zu rendern, + ohne erneut ausgeführt zu werden. Wird beim Lesen nach der **7-Tage-TTL** + ebenfalls abgelehnt — `/audit` fällt dann in seinen leeren Zustand zurück + und fordert einen neuen Lauf an. Klicke unten im Bericht auf + `[ re-audit now ]`, um zu aktualisieren — ein Re-Audit sendet `noCache: true`, + umgeht also den Transkript-Cache und scannt jedes Transkript erneut, anstatt + das gecachte Ergebnis zurückzugeben; der Lauf streamt den Fortschritt über + einen fixierten Streifen oben und tauscht das Ergebnis bei Erfolg direkt aus + (kein Seiten-Reload; ein fehlgeschlagenes Re-Audit behält den vorherigen + Bericht). ## Hinweise -- **Keine Änderungen.** Das Audit läuft im Nur-Lesen-Modus. `warn-repeated-tool-calls` wird übersprungen, da sonst der sitzungsspezifische Begleiter geändert würde. -- **Workflow-Policies übersprungen.** `require-*-before-stop`-Policies werden nur bei `Stop`-Ereignissen ausgelöst und führen `execSync` gegen den Live-Git-Zustand aus — sie haben keine sinnvolle „Was wäre 2025 passiert"-Interpretation und erscheinen daher nicht in den Audit-Zählungen. -- **Benutzerdefinierte Policies übersprungen.** Vom Benutzer bereitgestellte benutzerdefinierte Hooks werden nicht wiedergegeben (sie können sich seit der ursprünglichen Sitzung geändert haben). \ No newline at end of file +- **Keine Mutation.** Das Audit läuft im Nur-Lese-Modus. `warn-repeated-tool-calls` + wird übersprungen, da sein Sitzungs-Sidecar sonst geändert würde. +- **Workflow-Policies übersprungen.** `require-*-before-stop`-Policies werden + nur bei `Stop`-Ereignissen ausgelöst und führen `execSync` gegen den aktuellen + Git-Zustand aus — sie haben keine sinnvolle Interpretation im Sinne von + „was wäre 2025 passiert", daher erscheinen sie nicht in den Audit-Zählungen. +- **Benutzerdefinierte Policies übersprungen.** Vom Nutzer bereitgestellte + benutzerdefinierte Hooks werden nicht erneut abgespielt (sie können sich seit + der ursprünglichen Sitzung geändert haben). \ No newline at end of file diff --git a/docs/de/cli/dashboard.mdx b/docs/de/cli/dashboard.mdx index 5f52b60b..fd05d33b 100644 --- a/docs/de/cli/dashboard.mdx +++ b/docs/de/cli/dashboard.mdx @@ -13,10 +13,10 @@ Startet das Web-Dashboard unter `http://localhost:8020`. | Flag | Beschreibung | |------|--------------| -| `--port ` | Port, auf dem gehört wird (Standard: `8020`) | +| `--port ` | Port, auf dem gelistet wird (Standard: `8020`) | | `--allowed-origins ` | Kommagetrennte Hosts/IPs, die auf Entwicklungsressourcen zugreifen dürfen | -Um das Dashboard auf einen nicht standardmäßigen Claude-Projektordner zu verweisen, setzen Sie beim Starten die Umgebungsvariable `CLAUDE_PROJECTS_PATH`. +Um das Dashboard auf einen nicht standardmäßigen Claude-Projektordner zu verweisen, setzen Sie beim Start die Umgebungsvariable `CLAUDE_PROJECTS_PATH`. ## Beispiele diff --git a/docs/de/cli/environment-variables.mdx b/docs/de/cli/environment-variables.mdx index 176df212..93947d27 100644 --- a/docs/de/cli/environment-variables.mdx +++ b/docs/de/cli/environment-variables.mdx @@ -1,6 +1,6 @@ --- title: Umgebungsvariablen -description: "Verhalten von failproofai mit Umgebungsvariablen konfigurieren" +description: "Konfiguriere das Verhalten von failproofai mit Umgebungsvariablen" --- ## Dashboard @@ -8,65 +8,68 @@ description: "Verhalten von failproofai mit Umgebungsvariablen konfigurieren" | Variable | Beschreibung | |----------|-------------| | `PORT` | Dashboard-Port (Standard: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Überschreibt den Speicherort der Claude Code-Projektordner | +| `CLAUDE_PROJECTS_PATH` | Überschreibt den Pfad, unter dem Claude Code Projektordner gesucht werden | | `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Kommagetrennte Liste von Dashboard-Seiten, die ausgeblendet werden sollen | | `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs, die auf Entwicklungsressourcen zugreifen dürfen. Entspricht `--allowed-origins`. | -## Protokollierung +## Logging | Variable | Beschreibung | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Server-Protokollierungsstufe (Standard: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Benutzerdefinierter Pfad zur Hook-Protokolldatei oder `true` für den Standardpfad (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Server-Log-Level (Standard: `warn`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Benutzerdefinierter Pfad zur Hook-Log-Datei oder `true` für den Standardpfad (`~/.failproofai/logs/hooks.log`) | ## Telemetrie -failproofai übermittelt standardmäßig anonyme Nutzungstelemetrie. Es gibt zwei Möglichkeiten, -diese zu deaktivieren. Es gilt immer die restriktivere Einstellung – eine Umgebungsvariable -kann niemals etwas wieder aktivieren, das in der Konfigurationsdatei deaktiviert wurde. +failproofai sendet standardmäßig anonyme Nutzungstelemetrie. Es gibt zwei Möglichkeiten, +diese zu deaktivieren. Es gilt stets die restriktivere Einstellung — eine Umgebungsvariable +kann niemals etwas reaktivieren, was die Konfigurationsdatei deaktiviert hat. | Variable | Beschreibung | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Anonyme Nutzungstelemetrie für diesen Prozess deaktivieren | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Deaktiviert anonyme Nutzungstelemetrie für diesen Prozess | -Um die Telemetrie dauerhaft für das gesamte System zu deaktivieren, fügen Sie Folgendes zu `~/.failproofai/config.toml` hinzu: +Um die Telemetrie dauerhaft für das gesamte System zu deaktivieren, füge Folgendes zur `~/.failproofai/config.json` hinzu: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -Die Konfigurationsdatei ist die richtige Option, wenn Sie den **failproofaid-Daemon** betreiben. -Der Daemon ist ein systemweiter Dienst, dessen Umgebung keine aus Ihrer Shell exportierten -Variablen enthält – `FAILPROOFAI_TELEMETRY_DISABLED` kann ihn daher nicht erreichen. -`[telemetry] enabled = false` wird sowohl von der CLI als auch vom Daemon gelesen. +Die Konfigurationsdatei ist die empfohlene Option, wenn du den **failproofaid-Daemon** betreibst. +Der Daemon ist ein systemweiter Dienst, dessen Umgebung keine Variablen enthält, die aus deiner +Shell exportiert wurden — `FAILPROOFAI_TELEMETRY_DISABLED` erreicht ihn daher nicht. +`[telemetry] enabled = false` wird sowohl vom CLI als auch vom Daemon ausgewertet. -Der Daemon meldet ausschließlich seinen eigenen **Lebenszyklus**: ob er gestartet wurde (und ob der -vorherige Lauf sauber beendet wurde), ob er gestoppt wurde, wann sein Auswertungs-Worker gestartet -oder neu gestartet wurde, wann eine Collector-Aufgabe fehlgeschlagen ist sowie das Ergebnis eines -Cloud-Policy-Abrufs. Diese Ereignisse enthalten nur wenige kategorische Werte und Zählerstände – -niemals einen Dateipfad, einen Befehl, eine Richtlinie, einen Prompt oder andere Inhalte aus einem -Transkript. Es gibt kein Ereignis pro Tool-Aufruf. +Der Daemon meldet ausschließlich seinen eigenen **Lebenszyklus**: dass er gestartet wurde (und ob der +vorherige Lauf sauber beendet wurde), dass er gestoppt wurde, wann sein Auswertungs-Worker erzeugt +oder neu gestartet wurde, wann eine Collector-Aufgabe fehlgeschlagen ist, und das Ergebnis eines +Cloud-Policy-Abrufs. Diese Ereignisse enthalten nur Werte mit geringer Kardinalität und Zähler — +niemals einen Dateipfad, einen Befehl, eine Policy, einen Prompt oder irgendetwas, das aus einem +Transkript stammt. Es gibt kein Ereignis pro Tool-Aufruf. ## Authentifizierung | Variable | Beschreibung | |----------|-------------| -| `FAILPROOF_API_URL` | Überschreibt die vom Dashboard-Authentifizierungsdialog verwendete API-Server-Basis-URL. Standardmäßig `https://api.befailproof.ai`; auf `http://localhost:8080` (oder einen anderen Wert) setzen, wenn ein lokaler API-Server verwendet wird. | -| `FAILPROOFAI_AUTH_DIR` | Überschreibt den Speicherort von `auth.json` (Standard: `~/.failproofai`). Hauptsächlich für isolierte Tests nützlich. | +| `FAILPROOF_API_URL` | Überschreibt die API-Server-Basis-URL, die im Dashboard-Authentifizierungsdialog verwendet wird. Standard ist `https://api.befailproof.ai`; setze den Wert auf `http://localhost:8080` (oder einen anderen Pfad), wenn du einen lokalen API-Server betreibst. | +| `FAILPROOFAI_AUTH_DIR` | Überschreibt den Speicherort von `auth.json` (Standard: `~/.failproofai`). Hauptsächlich nützlich für isolierte Tests. | ## Erster-Start-Hinweis | Variable | Beschreibung | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Überspringt die Aufforderung zur Installation von Richtlinien beim ersten einfachen Aufruf von `failproofai` | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Überspringt den Hinweis, der beim ersten einfachen `failproofai`-Aufruf angeboten wird, Policies zu installieren | -## LLM (für die Richtlinienauswertung) +## LLM (für die Policy-Auswertung) | Variable | Beschreibung | |----------|-------------| | `FAILPROOFAI_LLM_BASE_URL` | LLM-API-Endpunkt (Standard: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | API-Schlüssel für LLM-gestützte Richtlinien | +| `FAILPROOFAI_LLM_API_KEY` | API-Schlüssel für LLM-gestützte Policies | | `FAILPROOFAI_LLM_MODEL` | Modellname (Standard: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/de/cli/hook.mdx b/docs/de/cli/hook.mdx index fc297aaf..1fb6b053 100644 --- a/docs/de/cli/hook.mdx +++ b/docs/de/cli/hook.mdx @@ -7,15 +7,15 @@ description: "Der Subprozess, den Claude Code bei jedem Tool-Ereignis aufruft" failproofai --hook ``` -Dies ist der Befehl, der in Claude Codes `settings.json` durch `failproofai policies --install` registriert wird. Normalerweise wird er nicht direkt aufgerufen. +Dies ist der Befehl, der in der `settings.json` von Claude Code durch `failproofai policies --install` registriert wird. Normalerweise wird er nicht direkt aufgerufen. -Liest eine JSON-Nutzlast von stdin, wertet alle aktivierten Richtlinien aus und beendet sich mit einem Code, der die Entscheidung angibt: +Liest eine JSON-Payload von stdin, wertet alle aktivierten Richtlinien aus und beendet sich mit einem Code, der die Entscheidung anzeigt: | Exit-Code | Entscheidung | Auswirkung | |-----------|--------------|------------| | `0` | `allow` | Aktion erlauben | -| `1` | `deny` | Aktion blockieren – Claude sieht den Ablehnungsgrund | -| `2` | `instruct` | Anleitung in Claudes Kontext einschleusen | +| `1` | `deny` | Aktion blockieren – Claude erhält den Ablehnungsgrund | +| `2` | `instruct` | Hinweise in Claudes Kontext einfügen | ### Unterstützte Ereignistypen diff --git a/docs/de/cli/install-policies.mdx b/docs/de/cli/install-policies.mdx index ff1546f3..eadb9e4b 100644 --- a/docs/de/cli/install-policies.mdx +++ b/docs/de/cli/install-policies.mdx @@ -7,18 +7,18 @@ description: "Richtlinien aktivieren, damit sie bei jedem Agenten-Tool-Aufruf au failproofai policies --install [policy-names...] [options] ``` -Schreibt Hook-Einträge in die Einstellungsdatei der installierten Agenten-CLI (Claude Code, OpenAI Codex oder GitHub Copilot CLI _(Beta)_), damit failproofai Tool-Aufrufe abfängt. +Schreibt Hook-Einträge in die Einstellungsdatei der installierten Agenten-CLI (Claude Code, OpenAI Codex oder GitHub Copilot CLI _(Beta)_), sodass failproofai Tool-Aufrufe abfängt. Aliase: `failproofai p -i` ## Optionen | Flag | Beschreibung | -|------|--------------| -| `--cli claude\|codex\|copilot` | Agenten-CLI(s), für die installiert werden soll; durch Leerzeichen getrennt (z. B. `--cli claude codex copilot`) oder wiederholt angegeben. Weglassen, um installierte CLIs zu erkennen und eine Auswahl anzuzeigen. | -| `--scope user` | Installiert in die benutzerweite Einstellungsdatei (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Standard. | -| `--scope project` | Installiert in die projektweite Einstellungsdatei (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Nur Claude — installiert in `/.claude/settings.local.json`. Codex und Copilot verfügen nicht über einen `local`-Bereich. | +|------|-------------| +| `--cli claude\|codex\|copilot` | Agenten-CLI(s), für die installiert werden soll; durch Leerzeichen getrennt (z. B. `--cli claude codex copilot`) oder mehrfach angegeben. Weglassen, um installierte CLIs automatisch zu erkennen und eine Auswahl anzuzeigen. | +| `--scope user` | In die benutzerweite Einstellungsdatei installieren (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Standard. | +| `--scope project` | In die projektweite Einstellungsdatei installieren (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Nur Claude — installiert in `/.claude/settings.local.json`. Codex und Copilot unterstützen keinen `local`-Scope. | | `--custom ` / `-c` | Pfad zu einer JS-Datei mit benutzerdefinierten Hook-Richtlinien | ## Verhalten @@ -44,7 +44,7 @@ failproofai policies --install all # Mit einer benutzerdefinierten Richtliniendatei installieren failproofai policies --install --custom ./my-policies.js -# Für OpenAI Codex installieren (Projektbereich) +# Für OpenAI Codex installieren (Projekt-Scope) failproofai policies --install --cli codex --scope project # Für GitHub Copilot CLI (Beta) für das aktuelle Projekt installieren @@ -54,4 +54,4 @@ failproofai policies --install --cli copilot --scope project failproofai policies --install --cli claude codex copilot ``` -Wenn `--custom ` angegeben wird, wird die Datei sofort validiert – sie muss `customPolicies.add()` mindestens einmal aufrufen. Der aufgelöste Pfad wird als `customPoliciesPath` in `policies-config.json` gespeichert. \ No newline at end of file +Wenn `--custom ` angegeben wird, wird die Datei sofort validiert – sie muss mindestens einmal `customPolicies.add()` aufrufen. Der aufgelöste Pfad wird als `customPoliciesPath` in `policies-config.json` gespeichert. \ No newline at end of file diff --git a/docs/de/cli/list-policies.mdx b/docs/de/cli/list-policies.mdx index 67f7721b..6d683864 100644 --- a/docs/de/cli/list-policies.mdx +++ b/docs/de/cli/list-policies.mdx @@ -1,6 +1,6 @@ --- title: Richtlinien auflisten -description: "Zeigt, welche Richtlinien aktiviert sind, ihre Parameter und benutzerdefinierte Richtlinien" +description: "Zeigt an, welche Richtlinien aktiviert sind, ihre Parameter und benutzerdefinierte Richtlinien" --- ```bash @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Unbekannte Schlüssel in `policyParams` werden hier markiert, damit Sie Tippfehler frühzeitig erkennen können. \ No newline at end of file +Unbekannte Schlüssel in `policyParams` werden hier hervorgehoben, damit Sie Tippfehler frühzeitig erkennen können. \ No newline at end of file diff --git a/docs/de/cli/migrate.mdx b/docs/de/cli/migrate.mdx new file mode 100644 index 00000000..a02be7c1 --- /dev/null +++ b/docs/de/cli/migrate.mdx @@ -0,0 +1,124 @@ +--- +title: Home-Verzeichnis migrieren +description: "~/.failproofai auf das Layout dieser Version bringen und vorher sehen, was passieren würde" +--- + +```bash +failproofai migrate --dry-run # Plan ausgeben, nichts ändern +failproofai migrate # ausführen +``` + +Die meisten Leute geben diesen Befehl nie ein. Er läuft beim ersten Befehl nach +einem Upgrade automatisch ab, und [`failproofai update`](/de/cli/update) schließt +ihn mit ein. Greife direkt darauf zurück, wenn du den Plan vor der Ausführung +sehen möchtest oder die Migration separat ausführen willst. + +## Auf das Layout abgestimmt, nicht auf die Version + +`~/.failproofai/VERSION` speichert eine **Layout**-Nummer — die Struktur des +Verzeichnisses, nicht das Release, das sie geschrieben hat. Migrationen sind auf +diese Nummer abgestimmt, was größere Lücken günstig macht: + +- npm-Versionen ändern sich bei jedem Release, Dutzende davon zwischen zwei Layouts. +- Eine Maschine, die dreißig Releases **ohne Layout-Änderung** überspringt, führt + **null** Migrationen durch — keine dreißig Leerlauf-Schritte. +- Eine Maschine, die mehrere Layouts auf einmal überspringt, führt jeden Schritt + der Reihe nach aus, wobei jeder Schritt nur seine eigenen zwei Enden kennt. + +Das ist wichtig, weil npm ein installiertes Paket nicht eigenständig aktualisieren +kann. Eine Maschine, die monatelang auf einer Version verbleibt und dann mehrere +Layouts auf einmal überspringt, ist der Normalfall — nicht die Ausnahme. + +## Der Trockenlauf + +`--dry-run` gibt die genaue Kette und die Dateien aus, die zuvor gespeichert +würden, und ändert überhaupt nichts — keine Migration, kein Backup, kein +Ledger-Eintrag: + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## Was übertragen und was neu erstellt wird + +Jeder Pfad im Home-Verzeichnis deklariert, welche Art von Daten er enthält, und +das entscheidet, ob eine Migration ihn verwerfen darf. Die Regel: **Abgeleitetes +und Wiederabrufbares darf verworfen werden; alles, was du eingegeben hast, alles +noch nicht Übermittelte und alles, was die Maschine identifiziert, wird +übertragen.** + +| Übertragen | Neu erstellt oder erneut abgerufen | +|---|---| +| `config.json` — Einstellungen, `daemon.configured`, zusätzliche Erfassungspfade | Der Audit-Cache | +| `credentials.json` — deine Cloud-Registrierung | Cloud-verwaltete Deployments (beim nächsten Poll erneut abgerufen und per Digest verifiziert) | +| `policies-config.json` — deine Policy-Auswahl und Parameter | Daemon-Scratch-Zustand | +| `policies/` — deine eigenen Policy-Dateien und die darin importierten Hilfsdateien | | +| `hook-activity/` — das Entscheidungsprotokoll, das das Dashboard liest | | +| Noch nicht übermittelte Ereignisse in der Upload-Warteschlange | | +| `cursors/` — Collector-Wasserzeichen | | +| Das Daemon-Binary in `bin/` | | + + + Noch nicht übermittelte Ereignisse werden übertragen statt verworfen, weil der + Verlust dauerhaft wäre, nicht nur vorübergehend: Das Wasserzeichen des Collectors + ist bereits über alles hinausgegangen, was im Spool liegt, sodass dieser + Bereich eines Transkripts nie wieder gelesen würde. Die Migration fordert den + Daemon außerdem auf, das Gespoolte unmittelbar nach Abschluss zu übermitteln — + das übliche Ergebnis ist daher, dass nichts mehr zu übertragen bleibt. + + +Schlüssel, die eine *neuere* Version in `config.json`, `credentials.json` oder +`policies-config.json` geschrieben hat, werden ebenfalls erhalten — statt von +einem älteren Reader verworfen zu werden. + +## Das hinterlassene Protokoll + +``` +~/.failproofai/migrations/ + applied.json ein Eintrag pro Schritt: Layout, CLI, Zeitstempel, Dauer, Ergebnis + backup-layout/ Kopien der unersetzlichen Dateien, vor dem ersten Schritt erstellt +``` + +`applied.json` beantwortet die Frage „Was hat diese Maschine tatsächlich +durchlaufen" — die erste Frage, die sich lohnt zu stellen, wenn nach einem Upgrade +etwas falsch aussieht. Füge sie einem Bug-Report bei. + +Das Backup ist bewusst klein gehalten und keine Kopie des gesamten Verzeichnisses: +Die Migration löscht durch Design nichts Unersetzliches mehr, weshalb es sich +lohnt, gegen einen *Fehler in einem Schritt* abzusichern — und diese wenigen +Dateien sind die Stellen, an denen ein solcher Fehler schaden würde. + +## Wenn ein Schritt fehlschlägt + +Die Kette stoppt dort. `VERSION` wird nur von einem erfolgreich abgeschlossenen +Schritt gestempelt, sodass das Home mit seinem alten Layout markiert bleibt und +der nächste Befehl es erneut versucht — ein Home wird nie auf Basis einer +unvollständigen Migration als aktuell markiert. Der Schritt wird in `applied.json` +mit `"ok": false` aufgezeichnet, und das Backup befindet sich dort, wo es erstellt +wurde. + +## Ein neueres Home wird abgelehnt, nicht migriert + +Wenn `~/.failproofai/` von einem **neueren** failproofai geschrieben wurde als dem, +das du gerade ausführst, stoppt der Befehl und fordert dich auf, stattdessen ein +Upgrade durchzuführen. Diese Daten sind in Ordnung und eine neuere CLI liest sie; +eine „Vorwärtsmigration" existiert nicht, und ein Zurücksetzen würde etwas +Wiederherstellbares zerstören. + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +Der Daemon wendet dieselbe Regel an: `failproofaid` verweigert den Start gegen ein +Layout, das er nicht versteht, anstatt Pfade zu lesen und zu schreiben, die +verschoben wurden. \ No newline at end of file diff --git a/docs/de/cli/remove-policies.mdx b/docs/de/cli/remove-policies.mdx index 722c67fc..79dad696 100644 --- a/docs/de/cli/remove-policies.mdx +++ b/docs/de/cli/remove-policies.mdx @@ -1,30 +1,30 @@ --- title: Richtlinien deinstallieren -description: "Hook-Einträge aus den Einstellungen von Claude Code entfernen" +description: "Hook-Einträge aus den Claude Code-Einstellungen entfernen" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -Entfernt failproofai Hook-Einträge aus der `settings.json` von Claude Code. +Entfernt failproofai-Hook-Einträge aus der `settings.json` von Claude Code. -Aliasse: `failproofai p -u` +Aliases: `failproofai p -u` ## Optionen | Flag | Beschreibung | |------|-------------| -| `--scope user` | Aus globalen Einstellungen entfernen (Standard) | -| `--scope project` | Aus Projekteinstellungen entfernen | -| `--scope local` | Aus lokalen Einstellungen entfernen | +| `--scope user` | Aus den globalen Einstellungen entfernen (Standard) | +| `--scope project` | Aus den Projekteinstellungen entfernen | +| `--scope local` | Aus den lokalen Einstellungen entfernen | | `--scope all` | Aus allen Geltungsbereichen gleichzeitig entfernen | | `--custom` / `-c` | Den `customPoliciesPath` aus der Konfiguration löschen | ## Verhalten -- **Keine Richtliniennamen** – entfernt alle failproofai Hook-Einträge aus der Einstellungsdatei -- **Bestimmte Namen** – deaktiviert diese Richtlinien, behält aber die installierten Hooks bei +- **Keine Richtliniennamen** – entfernt alle failproofai-Hook-Einträge aus der Einstellungsdatei +- **Bestimmte Namen** – deaktiviert die angegebenen Richtlinien, lässt die Hooks aber installiert ## Beispiele diff --git a/docs/de/cli/update.mdx b/docs/de/cli/update.mdx new file mode 100644 index 00000000..0bdf74be --- /dev/null +++ b/docs/de/cli/update.mdx @@ -0,0 +1,65 @@ +--- +title: Nach einem Upgrade aktualisieren +description: "Die Hälfte eines Upgrades erledigen, die npm nicht kann: Home migrieren und Daemon abgleichen" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +Das ist das vollständige Upgrade. `npm` ersetzt das CLI; `failproofai update` erledigt den Rest. + +## Warum ein zweiter Befehl nötig ist + +`npm install -g` ersetzt genau eine Sache – das CLI. Zwei weitere Bestandteile einer failproofai-Installation befinden sich bewusst außerhalb des Pakets und werden von npm nicht verschoben: + +- **`~/.failproofai/`** – Einstellungen, Cloud-Registrierung, Richtlinienauswahl und Verlauf. Eine neue Version kann diese Dateien anders organisieren, und die Reorganisation muss von Code durchgeführt werden, der beide Strukturen kennt. +- **Das `failproofaid`-Daemon-Binary** unter `~/.failproofai/bin/failproofaid-`. Es liegt bewusst *nicht* in `node_modules`: Ein Upgrade, das die Datei unter einem laufenden Dienst austauscht, würde einen aktiven Daemon auf ein Binary umleiten, das aus einem anderen Quellcode gebaut wurde – und das Entfernen des Pakets würde es aus einem Dienst löschen, der dann bei jedem Start in einer Absturzschleife landet. + +Nach einem `npm install -g` allein ist also das CLI aktuell, der Daemon jedoch nicht. `failproofaid` verweigert den Start gegen ein Home-Layout, das er nicht kennt – als laute Fehlermeldung statt als stille Fehlfunktion – daher müssen beide Hälften zusammengebracht werden. `failproofai update` erledigt genau diesen Schritt. + +## Was der Befehl tut + + + + Liest das in `~/.failproofai/VERSION` gespeicherte Layout und führt die Schritte aus, die es auf das Layout dieser Version bringen. Meistens sind keine nötig – siehe + [`failproofai migrate`](/de/cli/migrate). + + + Aus dem Plattformpaket, das npm bereits heruntergeladen hat, wenn möglich (kein Netzwerk erforderlich), andernfalls aus dem Release-Asset für diese exakte Version – SHA-256-verifiziert, bevor es verwendet wird. + + + Durch aktive Überprüfung statt Annahme – ein Dienst-Manager meldet einen Prozess als aktiv, sobald er ihn geforkt hat, was nicht dasselbe ist wie ein funktionierender Prozess. + + + +## Optionen + +| Flag | Wirkung | +|------|---------| +| `--no-daemon` | Nur das Home migrieren, den Daemon auf seiner aktuellen Version belassen. | + + + `--no-daemon` lässt einen versionsabweichenden Daemon im Betrieb. Auf einem Rechner, der den Daemon erfordert, **schlägt jedes Hook-Ereignis geschlossen fehl**, wenn der Daemon nicht antwortet – und ein Daemon, der den Start gegen ein migriertes Home verweigert, kann nicht antworten. Es empfiehlt sich, die Daemon-Hälfte mitlaufen zu lassen. + + +## Bei Fehlern + +Der Befehl beendet sich mit einem Nicht-Null-Exit-Code und gibt an, welche Hälfte fehlgeschlagen ist. Zwei Fälle sind erwähnenswert: + +- **Ein Migrationsschritt wurde nicht abgeschlossen.** Das Home wird mit seinem *alten* Layout markiert belassen, sodass der nächste Befehl es erneut versucht – kein Home wird je auf der Grundlage einer unvollständigen Migration als aktuell markiert. Kopien der Einstellungen und Registrierung wurden vor Beginn in `~/.failproofai/migrations/backup-layout/` gesichert. +- **Der Daemon konnte ohne Passwort nicht neu gestartet werden.** `sudo -n` wird bewusst verwendet, damit nichts unter einer Fortschrittsanzeige nach einer Eingabe fragt. Der Befehl gibt die genaue Zeile aus, die manuell ausgeführt werden muss. + + + Nichts hier benötigt den interaktiven Einrichtungsassistenten. Einstellungen, Cloud-Registrierung und Richtlinienauswahl überleben ein Upgrade, sodass ein migrierter Rechner genauso durchsetzt wie zuvor – was am wichtigsten auf Rechnern ist, an denen niemand sitzt: ein CI-Runner, ein Fleet-Rechner, ein Headless-Gateway. + + +## Automatisierung + +`failproofai update` ist nicht-interaktiv und kann sicher ausgeführt werden, wenn nichts zu tun ist – es meldet „keine Migration erforderlich" und beendet sich mit 0. Es nach jedem Upgrade in einem Provisionierungsskript oder Dockerfile aufzurufen ist die vorgesehene Verwendung: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` beim Image-Build, wo es noch keinen Dienst zum Neustart gibt.) \ No newline at end of file diff --git a/docs/de/configuration.mdx b/docs/de/configuration.mdx index fbc47781..ff42680d 100644 --- a/docs/de/configuration.mdx +++ b/docs/de/configuration.mdx @@ -1,28 +1,28 @@ --- title: Konfiguration -description: "Konfigurationsdateiformat, Drei-Ebenen-System und Zusammenführungsregeln" +description: "Konfigurationsdateiformat, das Drei-Ebenen-System und Zusammenführungsregeln" icon: gear --- -failproofai verwendet JSON-Konfigurationsdateien, um zu steuern, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie sich leicht im Team teilen lässt – committen Sie sie in Ihr Repository und jeder Entwickler erhält dasselbe Sicherheitsnetz für den Agenten. +failproofai verwendet JSON-Konfigurationsdateien, um festzulegen, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie leicht mit dem Team geteilt werden kann – einfach ins Repository committen, und jeder Entwickler profitiert vom gleichen Sicherheitsnetz für den Agenten. --- -## Konfigurationsebenen +## Konfigurationsbereiche -Es gibt drei Konfigurationsebenen, die in Prioritätsreihenfolge ausgewertet werden: +Es gibt drei Konfigurationsbereiche, die in Prioritätsreihenfolge ausgewertet werden: -| Ebene | Dateipfad | Zweck | -|-------|-----------|-------| -| **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, in die Versionskontrolle eingecheckt | -| **local** | `.failproofai/policies-config.local.json` | Persönliche Überschreibungen pro Repository, per gitignore ausgeschlossen | +| Bereich | Dateipfad | Zweck | +|---------|-----------|-------| +| **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, ins Versionskontrollsystem eingecheckt | +| **local** | `.failproofai/policies-config.local.json` | Persönliche, repository-spezifische Überschreibungen, per gitignore ausgeschlossen | | **global** | `~/.failproofai/policies-config.json` | Benutzerweite Standardwerte für alle Projekte | -Wenn failproofai ein Hook-Ereignis empfängt, lädt und zusammenführt es alle drei Dateien, die für das aktuelle Arbeitsverzeichnis existieren. +Wenn failproofai ein Hook-Ereignis empfängt, lädt und führt es alle drei Dateien zusammen, die für das aktuelle Arbeitsverzeichnis vorhanden sind. ### Zusammenführungsregeln -**`enabledPolicies`** – die Vereinigung aller drei Ebenen. Eine Richtlinie, die auf einer beliebigen Ebene aktiviert ist, ist aktiv. +**`enabledPolicies`** – die Vereinigung aller drei Bereiche. Eine auf einer beliebigen Ebene aktivierte Richtlinie ist aktiv. ```text project: ["block-sudo"] @@ -32,7 +32,7 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← deduplizierte Vereinigung ``` -**`policyParams`** – die erste Ebene, die Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es findet keine tiefe Zusammenführung von Werten innerhalb der Parameter einer Richtlinie statt. +**`policyParams`** – der erste Bereich, der Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es findet keine tiefe Zusammenführung von Werten innerhalb der Parameter einer Richtlinie statt. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -49,15 +49,11 @@ global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← fällt auf global zurück ``` -**`customPoliciesPaths` / `customPoliciesPath`** – die erste Ebene, die eine der beiden Formen definiert, gewinnt. +**`customPoliciesPaths` / `customPoliciesPath`** – der erste Bereich, der eine der beiden Formen definiert, gewinnt. -**`disabledCustomPolicies`** – Vereinigung über alle Ebenen. Das Dashboard schreibt hier eine -quellenqualifizierte ID, wenn Sie eine einzelne Richtlinie aus einer expliziten oder konventionsbasierten -Richtliniendatei deaktivieren. Nicht aufgeführte Richtlinien bleiben standardmäßig aktiviert; -IDs enthalten die Quelldatei, sodass gleichnamige Richtlinien in mehreren Dateien -unabhängig voneinander gesteuert werden können. +**`disabledCustomPolicies`** – Vereinigung über alle Bereiche hinweg. Das Dashboard schreibt hier eine quellenqualifizierte ID, wenn eine einzelne Richtlinie aus einer expliziten oder konventionsbasierten Richtliniendatei deaktiviert wird. Nicht aufgeführte Richtlinien bleiben standardmäßig aktiviert; IDs enthalten die Quelldatei, sodass gleichnamige Richtlinien in mehreren Dateien unabhängig voneinander gesteuert werden können. -**`llm`** – die erste Ebene, die es definiert, gewinnt. +**`llm`** – der erste Bereich, der es definiert, gewinnt. --- @@ -108,9 +104,9 @@ unabhängig voneinander gesteuert werden können. Typ: `string[]` -Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinienkennungen übereinstimmen, die `failproofai policies` anzeigt. Die vollständige Liste finden Sie unter [Integrierte Richtlinien](/de/built-in-policies). +Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinienkennungen übereinstimmen, die `failproofai policies` anzeigt. Die vollständige Liste findet sich unter [Integrierte Richtlinien](/de/built-in-policies). -Richtlinien, die nicht in `enabledPolicies` aufgeführt sind, sind inaktiv, auch wenn sie Einträge in `policyParams` haben. +Richtlinien, die nicht in `enabledPolicies` enthalten sind, sind inaktiv, auch wenn sie Einträge in `policyParams` haben. ### `policyParams` @@ -118,17 +114,17 @@ Typ: `Record>` Parameterüberschreibungen pro Richtlinie. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies). -Wenn eine Richtlinie Parameter hat, Sie diese aber nicht angeben, werden die integrierten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` gar nicht konfigurieren, erhalten ein identisches Verhalten wie in früheren Versionen. +Wenn eine Richtlinie Parameter hat, diese aber nicht angegeben werden, werden die integrierten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` überhaupt nicht konfigurieren, erhalten identisches Verhalten wie in früheren Versionen. -Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden zur Hook-Ausführungszeit stillschweigend ignoriert, aber als Warnungen ausgegeben, wenn Sie `failproofai policies` ausführen. +Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden beim Auslösen des Hooks stillschweigend ignoriert, aber als Warnungen ausgegeben, wenn `failproofai policies` ausgeführt wird. #### `hint` (übergreifend) Typ: `string` (optional) -Eine Meldung, die an die Begründung angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Verwenden Sie dieses Feld, um Claude handlungsrelevante Hinweise zu geben, ohne die Richtlinie selbst zu ändern. +Eine Nachricht, die an die Begründung angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Damit kann Claude handlungsrelevante Hinweise gegeben werden, ohne die Richtlinie selbst zu ändern. -Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonfiguration (`.failproofai-project/`) oder Benutzerkonfiguration (`.failproofai-user/`). +Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`). ```json { @@ -147,42 +143,46 @@ Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom } ``` -Wenn `block-force-push` ablehnt, sieht Claude: *„Force-Pushing ist blockiert. Try creating a fresh branch instead."* +Wenn `block-force-push` ablehnt, sieht Claude: *„Force-pushing is blocked. Try creating a fresh branch instead."* -Nicht-String-Werte und leere Zeichenketten werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel). +Nicht-String-Werte und leere Strings werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel). ### `customPoliciesPath` Typ: `string` (absoluter Pfad) -Pfad zu einer JavaScript-Datei mit benutzerdefinierten Hook-Richtlinien. Dieser wird automatisch durch `failproofai policies --install --custom ` gesetzt (der Pfad wird vor der Speicherung in einen absoluten Pfad aufgelöst). +Pfad zu einer JavaScript-Datei mit benutzerdefinierten Hook-Richtlinien. Dieser wird automatisch von `failproofai policies --install --custom ` gesetzt (der Pfad wird vor der Speicherung in einen absoluten Pfad aufgelöst). -Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Details zur Erstellung finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). +Die Datei wird bei jedem Hook-Ereignis neu geladen – es findet kein Caching statt. Einzelheiten zur Erstellung von Richtlinien finden sich unter [Benutzerdefinierte Richtlinien](/de/custom-policies). ### Konventionsbasierte Richtlinien Zusätzlich zum expliziten `customPoliciesPath` erkennt und lädt failproofai automatisch Richtliniendateien aus `.failproofai/policies/`-Verzeichnissen: -| Ebene | Verzeichnis | Geltungsbereich | -|-------|-------------|-----------------| -| Projekt | `.failproofai/policies/` | Gemeinsam mit dem Team über die Versionskontrolle | -| Benutzer | `~/.failproofai/policies/custom-policies/` | Persönlich, gilt für alle Projekte | +| Ebene | Verzeichnis | Bereich | +|-------|-------------|---------| +| Projekt | `.failproofai/policies/` | Mit dem Team über Versionskontrolle geteilt | +| Benutzer | `~/.failproofai/policies/` | Persönlich, gilt für alle Projekte | - Das Verzeichnis auf Benutzerebene wurde im Rahmen der Umstrukturierung des - Home-Verzeichnisses eine Ebene tiefer verschoben. Dateien, die noch am alten - Speicherort `~/.failproofai/policies/` liegen, werden beim ersten Ausführen - eines `failproofai`-Befehls nach dem Upgrade automatisch in `custom-policies/` - verschoben, und der Befehl zeigt Ihnen an, welche Dateien verschoben wurden. + Richtlinien können direkt in `~/.failproofai/policies/` abgelegt werden. Der + danebenliegende Ordner `cloud-policies/` enthält Richtlinien, die die Organisation + auf diesem Rechner bereitgestellt hat – die Erkennung durchsucht keine Unterverzeichnisse, + sodass dieser Ordner nie gescannt wird und nichts in `policies/` damit kollidieren kann. + + Bei einem Upgrade von einer Version, die `~/.failproofai/policies/custom-policies/` verwendet + hat, werden alle Inhalte dieses Ordners – Richtliniendateien, etwaige `lib/`-Hilfsdateien + sowie Datendateien – beim ersten Ausführen eines `failproofai`-Befehls automatisch eine + Ebene nach oben verschoben, und der Befehl gibt an, was verschoben wurde. -**Dateiabgleich:** Es werden nur Dateien geladen, die dem Muster `*policies.{js,mjs,ts}` entsprechen (z. B. `security-policies.mjs`, `workflow-policies.js`). Andere Dateien im Verzeichnis werden ignoriert. +**Dateiabgleich:** Es werden nur Dateien geladen, die auf `*policies.{js,mjs,ts}` passen (z. B. `security-policies.mjs`, `workflow-policies.js`). Andere Dateien im Verzeichnis werden ignoriert. -**Keine Konfiguration erforderlich:** Konventionsbasierte Richtlinien benötigen keine Einträge in `policies-config.json`. Legen Sie die Dateien einfach im Verzeichnis ab und sie werden beim nächsten Hook-Ereignis aufgegriffen. +**Keine Konfiguration erforderlich:** Konventionsbasierte Richtlinien benötigen keine Einträge in `policies-config.json`. Dateien einfach in das Verzeichnis ablegen, und sie werden beim nächsten Hook-Ereignis erkannt. -**Gemeinsames Laden:** Sowohl Projekt- als auch Benutzer-Konventionsverzeichnisse werden durchsucht. Alle übereinstimmenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das die Regel „erste Ebene gewinnt" verwendet). +**Vereinigendes Laden:** Sowohl Projekt- als auch Benutzerkonventionsverzeichnisse werden durchsucht. Alle passenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das das Prinzip „erster Bereich gewinnt" verwendet). -Weitere Details und Beispiele finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). +Weitere Details und Beispiele finden sich unter [Benutzerdefinierte Richtlinien](/de/custom-policies). ### `llm` @@ -203,24 +203,24 @@ LLM-Client-Konfiguration für Richtlinien, die KI-Aufrufe durchführen. Für die ## Konfiguration über die CLI verwalten -Die Befehle `policies --install` und `policies --uninstall` schreiben in die Hook-Einstellungsdatei Ihrer Agenten-CLI (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die Sie direkt verwalten. Beides ist getrennt: +Die Befehle `policies --install` und `policies --uninstall` schreiben in die Hook-Einstellungsdatei der Agenten-CLI (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die direkt verwaltet wird. Beides ist voneinander getrennt: -- **Agenten-CLI-Einstellungen** – weist den Agenten an, bei jeder Werkzeugverwendung `failproofai --hook ` aufzurufen: +- **Agenten-CLI-Einstellungen** – weist den Agenten an, bei jeder Werkzeugnutzung `failproofai --hook ` aufzurufen: - **Claude Code**: `~/.claude/settings.json` (Benutzer), `/.claude/settings.json` (Projekt), `/.claude/settings.local.json` (lokal) - - **OpenAI Codex**: `~/.codex/hooks.json` (Benutzer), `/.codex/hooks.json` (Projekt) – Codex hat keinen `local`-Geltungsbereich - - **GitHub Copilot CLI _(Beta)_**: `~/.copilot/hooks/failproofai.json` (Benutzer), `/.github/hooks/failproofai.json` (Projekt) – Copilot hat keinen `local`-Geltungsbereich. Hook-Einträge verwenden Copilots betriebssystemspezifische `bash`/`powershell`-Befehlsfelder mit `timeoutSec`; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Die Unterstützung für Copilot CLI ist **Beta**, während wir das `events.jsonl`-Datensatzschema (das in der öffentlichen Dokumentation nicht spezifiziert ist) gegen mehr reale Sitzungen verifizieren. **VS Code Copilot Chat Agent-Modus (Vorschau)** liest Hook-Konfigurationen aus `.github/hooks/*.json`, `~/.copilot/hooks/*.json` und `~/.claude/settings.json` (gesteuert durch die Einstellung `chat.hookFilesLocations`) unter Verwendung desselben Claude-förmigen `{hookSpecificOutput:{permissionDecision:"deny",…}}`-Vertrags – genau die Pfade, in die diese `copilot`-Integration und die `claude`-Integration (`~/.claude/settings.json`) bereits schreiben, sodass `failproofai policies --install --cli copilot` (oder `--cli claude`) **bereits im VS Code Agent-Modus durchgesetzt wird**, ohne eine separate `vscode`-Integration zu benötigen (bestätigt anhand der VS Code-Erkennungsprotokolle). - - **Cursor Agent _(Beta)_**: `~/.cursor/hooks.json` (Benutzer), `/.cursor/hooks.json` (Projekt) – Cursor hat keinen `local`-Geltungsbereich. Hook-Einträge verwenden die Claude-förmige Form `{type, command, timeout}` (keine `bash`/`powershell`-Aufteilung), werden aber unter camelCase-Ereignisschlüsseln (`preToolUse`, `beforeSubmitPrompt`, …) in einem flachen Array gemäß Cursors [Hook-Schema](https://cursor.com/docs/hooks) gespeichert; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Der Handler kanonisiert camelCase → PascalCase über `CURSOR_EVENT_MAP`, sodass bestehende integrierte Richtlinien unverändert ausgelöst werden. Die Unterstützung für Cursor Agent ist **Beta**, während wir Cursors Transcript-Festplattenformat (in der öffentlichen Dokumentation nicht spezifiziert) gegen mehr reale Installationen verifizieren. - - **OpenCode _(Beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (Benutzer), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (Projekt) – OpenCode hat keinen `local`-Geltungsbereich. Im Gegensatz zu den anderen fünf CLIs verfügt OpenCode über **kein externes Befehlshook-System**: Es lädt prozessinterne JS/TS-Plugins, die explizit über das `plugin: []`-Array in `opencode.json` registriert sind (die automatische Erkennung aus `.opencode/plugins/` ist **nicht** die Art, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt einen kleinen generierten Plugin-Shim ab, der das failproofai-Binary als Unterprozess aufruft und die Claude-förmige JSON-Antwort des Binärprogramms zurück in Plugin-Semantik übersetzt: `throw new Error()` für Werkzeugereigenis-Deny (bricht den Werkzeugaufruf ab), `client.session.prompt(...)` für instruct UND für `Stop` / `SubagentStop`-Deny (sendet den Ablehnungsgrund als nächste Benutzermeldung – der einzige Force-Retry-Kanal, da `session.idle` nur für Benachrichtigungen ist und ein Throw daraus ein No-op ist), und No-op für allow. Der Shim kanonisiert sowohl Werkzeugnamen (Kleinbuchstaben → PascalCase über `OPENCODE_TOOL_MAP`) als auch Werkzeugeingabe-Argumentschlüssel (camelCase → snake_case über `OPENCODE_TOOL_INPUT_MAP` für `Read` / `Write` / `Edit`, z. B. `filePath` → `file_path`, `oldString` → `old_string`), bevor er an das Binary weiterleitet, sodass pfadprüfende integrierte Richtlinien wie `block-read-outside-cwd`, `block-env-files` und `block-secrets-write` bei OpenCode-Werkzeugaufrufen unverändert ausgelöst werden. Sitzungen leben in OpenCodes SQLite-Datenbank unter `~/.local/share/opencode/opencode.db`; der Sitzungs-Viewer des Dashboards liest sie über `opencode db --format json` und `opencode export `. Die Unterstützung für OpenCode ist **Beta**, während wir das Verhalten über Versionen hinweg und gegen mehr reale Sitzungen verifizieren. Siehe die [OpenCode-Plugins-Dokumentation](https://opencode.ai/docs/plugins/). - - **Pi _(Beta)_**: `~/.pi/agent/settings.json` (Benutzer), `/.pi/settings.json` (Projekt) – Pi hat keinen `local`-Geltungsbereich. Pi lädt TypeScript-Erweiterungspakete beim Start; die Einstellungsdatei ist ein flaches String-Array `{"packages": ["./relative/path", …]}`. failproofai schreibt einen einzelnen Packages-Array-Eintrag, der auf sein gebündeltes `pi-extension/`-Verzeichnis zeigt. Die Erweiterung abonniert intern Pis `tool_call` / `user_bash` / `input` / `session_start`-Ereignisse und ruft `failproofai --hook --cli pi` auf; der Handler kanonisiert underscore_lower_snake_case → PascalCase über `PI_EVENT_MAP`, sodass bestehende integrierte Richtlinien unverändert ausgelöst werden. Werkzeugeingabeargumente werden ebenfalls über `PI_TOOL_INPUT_MAP` kanonisiert (Pis Read / Write / Edit liefern `path` statt `file_path`; die Zuordnung des Top-Level-Schlüssels ermöglicht das Auslösen von `block-env-files` und `block-secrets-write` – `block-read-outside-cwd` hatte bereits einen `path`-Fallback). Die Unterstützung für Pi ist **Beta**, während Pis Erweiterungs-API und Sitzungsprotokoll-Layout sich stabilisieren. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**nur Benutzerebene** – Hermes hat keine Projekt-/lokale Konfiguration). Hermes ist ein Slack/Telegram-**Gateway**, sodass eine Installation Werkzeugaufrufe von jeder Plattform (Slack/Telegram/cli/cron) **und** internen Subagenten abfängt. Hook-Einträge sind ein `{command, timeout}`-Paar (Timeout in **Sekunden**) unter einer `hooks:`-Map, die durch Hermes' snake_case-Ereignisse (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) als Schlüssel indexiert ist; der Handler kanonisiert Ereignisse über `HERMES_EVENT_MAP` und Werkzeugnamen über `HERMES_TOOL_MAP`, sodass integrierte Richtlinien unverändert ausgelöst werden. Die Konfiguration wird durch einen kommentarerhaltenden YAML-`Document`-Round-Trip bearbeitet, sodass die anderen Einstellungen des Operators erhalten bleiben, und die Installation setzt `hooks_auto_accept: true`, damit das kopflose Gateway (kein TTY) die Hooks ohne Zustimmungsaufforderung ausführt. Der Evaluator gibt Hermes' `{"decision":"block","reason"}`-stdout-Vertrag aus (Hermes ignoriert Exit-Codes). **Einschränkungen:** Hermes hat kein Turn-End-`Stop`-Ereignis, sodass die `require-*-before-stop`-Integrierten nie dafür ausgelöst werden (nicht anwendbar, nicht kaputt); `instruct` degradiert zu allow-with-logged-note (kein Zusatzkontext-Kanal); und die Ausgabe-Geheimnis-Redaktion (`sanitize-*`) kann Werkzeugausgaben über den Shell-Hook-Vertrag nicht neu schreiben. Hermes ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine Gateway-Sitzungen direkt aus `~/.hermes/state.db`. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**nur Benutzerebene** – OpenClaw hat keine Projekt-/lokale Konfiguration). Wie Hermes ist OpenClaw ein selbst gehostetes Multi-Channel-**Gateway**, sodass eine Installation Werkzeugaufrufe von jedem Kanal und seinen internen Subagenten abfängt. Die Durchsetzung erfolgt über OpenClaws **prozessinterne Plugin-Hooks** (seine dateibasierten internen Hooks sind nur zur Beobachtung und können nicht blockieren), sodass – wie OpenCode/Pi – failproofai ein statisches `openclaw-plugin/`-Paket liefert, das das failproofai-Binary asynchron startet und das Urteil übersetzt. Die Installation registriert das mitgelieferte Plugin-Verzeichnis in `openclaw.json`'s `plugins.load.paths[]` und aktiviert es unter `plugins.entries.failproofai` (mit `hooks.allowConversationAccess: true`, erforderlich für die Raw-Conversation-Hooks). Der Evaluator gibt ein flaches `{permission, reason}`-Urteil aus und der Shim ordnet es der nativen Rückgabeform jedes Hooks zu: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**) und `before_agent_finalize → {action:"revise", reason}` (**Stop** – ein echter Turn-End-Gate, sodass die `require-*-before-stop`-Integrierten bei OpenClaw **durchgesetzt werden**, anders als bei Hermes). Ereignisse und Werkzeugnamen kanonisieren binärseitig über `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …), sodass integrierte Richtlinien unverändert ausgelöst werden; der Shim schlägt bei Spawn-/Parse-/Timeout-Fehlern offen fehl. OpenClaw ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine JSONL-Sitzungen unter `~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (Benutzer), `/.factory/hooks.json` (Projekt) – Factory hat keinen `local`-Geltungsbereich. droid liefert ein Claude-ähnliches externes Befehlshook-System, jedoch mit zwei live gegen droid v0.171.0 verifizierten Besonderheiten: (1) Ereignisnamen befinden sich auf der **obersten Ebene** von `hooks.json` – es gibt **keinen `"hooks"`-Wrapper** (droid lehnt einen ab); Werkzeugereignisse (`PreToolUse`/`PostToolUse`) tragen `"matcher": "*"`, Nicht-Werkzeugereignisse lassen es weg. (2) Deny wird durch **Exit-Code 2 + stderr** gesteuert, nicht durch eine JSON-Entscheidung – der `factory`-Zweig des Evaluators gibt Exit 2 für Werkzeug-/Prompt-Ereignisse zurück und `{decision:"block", reason}` nur beim Turn-End-`Stop`-Ereignis (dem einzigen Force-Retry-Kanal von droid). Ereignisse sind bereits in PascalCase (keine Ereigniszuordnung) und die Payload ist Claude snake_case; nur Werkzeugnamen werden über `FACTORY_TOOL_MAP` kanonisiert (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine JSONL-Sitzungen unter `~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (Benutzer), `/.devin/config.json` (Projekt) – Devin hat keinen `local`-Geltungsbereich. Devin ist ein **reiner Claude-Klon**, live gegen devin v3000.1.27 verifiziert: Es verwendet das Standard-Claude-`"hooks"`-Wrapper-Schema (Schreibvorgänge sind merge-erhaltend, sodass die anderen Schlüssel der Konfigurationsdatei – `org_id`, `theme_mode`, … – erhalten bleiben), bereits PascalCase-Ereignisnamen (keine Ereigniszuordnung, kein Handler-Zweig) und eine Claude-snake_case-stdin-Payload (keine Normalisierung). Der `devin`-Zweig des Evaluators lehnt bei **jedem** Ereignis mit `{"decision":"block","reason"}` JSON auf stdout bei Exit 0 ab (verifiziert – der Block überschrieb `--permission-mode dangerous`); beim Turn-End-`Stop`-Ereignis enthält der Grund den MANDATORY-ACTION-Force-Retry-Wortlaut, sodass die `require-*-before-stop`-Integrierten durchgesetzt werden. Nur Werkzeugnamen werden über `DEVIN_TOOL_MAP` kanonisiert (`exec→Bash`; `tool_input.command` ist bereits kanonisch). Devin ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine SQLite-Sitzungen unter `~/.local/share/devin/cli/sessions.db` (jede `sessions`-Zeile enthält ein echtes `working_directory`, sodass Sitzungen wie bei Claude nach Projekt-cwd gruppiert werden). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (Benutzer), `/.agents/hooks.json` (Projekt) – Antigravity hat keinen `local`-Geltungsbereich. Anders als Factory/Devin hat Antigravity seinen **eigenen** Vertrag (kein Claude-Klon), live gegen agy v1.1.2 verifiziert. `hooks.json` verwendet ein **benanntes-Hook**-Schema: Der Top-Level-Schlüssel ist ein Hook-*Name* (`"failproofai"`), dessen Wert eine Ereignis→Handler-Map ist – Werkzeugereignisse (`PreToolUse`/`PostToolUse`) wickeln Handler in `{matcher:"*", hooks:[…]}` ein, während `PreInvocation`/`Stop` **flache** Handler-Arrays sind (andere benannte Hooks bleiben erhalten). Die stdin-Payload ist **camelCase-Protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) – failproofai normalisiert sie vor der Richtlinienausführung zu snake_case und ordnet die PascalCase-Argumente von `run_command` (`CommandLine`/`Cwd`) über `ANTIGRAVITY_TOOL_INPUT_MAP` zu. Der `antigravity`-Zweig des Evaluators verwendet Antigravitys **eigene** Antwortformen: `{decision:"deny", reason}` blockiert ein Werkzeug/Prompt (Exit 0), `{decision:"continue", reason}` beim Turn-End-`Stop` betritt die Schleife erneut (sodass die `require-*-before-stop`-Integrierten durchgesetzt werden) und `{injectSteps:[{ephemeralMessage}]}` fügt eine Anweisung bei `PreInvocation` (→ `UserPromptSubmit`) ein. Werkzeugnamen kanonisieren über `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine Plain-JSONL-Transkripte unter `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (Gesprächsindex in `conversation_summaries.db`). - - **Goose (Codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (Benutzer), `/.agents/plugins/failproofai/hooks/hooks.json` (Projekt) – Goose hat keinen `local`-Geltungsbereich. Die Durchsetzung verwendet Gooses **Hooks**-System, die agentenübergreifende **Open Plugins**-Spezifikation: Der Installer legt einfach das `failproofai`-Plugin-Verzeichnis ab und Goose erkennt es beim Start automatisch (und registriert es selbst in `~/.config/goose/config.yaml`). Die `hooks.json` verwendet ein Open-Plugins-Schema **mit** einem `"hooks"`-Wrapper auf oberster Ebene, und der Matcher wird bei jedem Ereignis **weggelassen** – ein bloßes `"*"` ist ein ungültiger Regex, der nichts übereinstimmt (live gegen goose v1.43.0 verifiziert). Ereignisnamen sind bereits in PascalCase (keine Ereigniszuordnung); die stdin-Payload verwendet `event`/`working_dir`, was der Handler zu `hook_event_name`/`cwd` normalisiert. Der `goose`-Zweig des Evaluators lehnt mit `{"decision":"block","reason"}` JSON auf stdout bei Exit 0 ab, was nur beim **`PreToolUse`**-Ereignis berücksichtigt wird (ab goose ≥ v1.37.0 ausgeliefert) – das sowohl für das Shell-Tool **als auch innerhalb delegierter Subagenten** ausgelöst wird und damit der einzige ausreichende Deny-Punkt ist; jeder andere Hook-Fehler schlägt **offen** fehl. Goose hat **kein `Stop`-Ereignis**, sodass die `require-*-before-stop`-Integrierten nicht anwendbar sind (wie bei Hermes). Werkzeugnamen kanonisieren über `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) und Pfadschlüssel über `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine SQLite-Sitzungen unter `~/.local/share/goose/sessions/sessions.db` (jede `sessions`-Zeile enthält ein echtes `working_dir`, sodass Sitzungen wie bei Devin nach Projekt-cwd gruppiert werden; `--no-session`-Scratch-Runs werden herausgefiltert). -- **`policies-config.json`** – teilt failproofai mit, welche Richtlinien ausgewertet werden sollen und mit welchen Parametern (wird von allen Agenten-CLIs gemeinsam genutzt) - -Übergeben Sie `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`, um einen bestimmten Agenten anzusteuern (durch Leerzeichen getrennt oder wiederholt für eine beliebige Teilmenge): + - **OpenAI Codex**: `~/.codex/hooks.json` (Benutzer), `/.codex/hooks.json` (Projekt) – Codex hat keinen `local`-Bereich + - **GitHub Copilot CLI _(Beta)_**: `~/.copilot/hooks/failproofai.json` (Benutzer), `/.github/hooks/failproofai.json` (Projekt) – Copilot hat keinen `local`-Bereich. Hook-Einträge verwenden die betriebssystemspezifischen `bash`/`powershell`-Befehlsfelder von Copilot mit `timeoutSec`; die Datei trägt einen `version: 1`-Marker auf oberster Ebene. Die Copilot-CLI-Unterstützung ist **Beta**, während das `events.jsonl`-Eintragsschema (das in der öffentlichen Dokumentation nicht spezifiziert ist) anhand weiterer realer Sitzungen überprüft wird. **VS Code Copilot Chat-Agentenmodus (Vorschau)** liest Hook-Konfigurationen aus `.github/hooks/*.json`, `~/.copilot/hooks/*.json` und `~/.claude/settings.json` (gesteuert durch die Einstellung `chat.hookFilesLocations`) und verwendet denselben Claude-förmigen `{hookSpecificOutput:{permissionDecision:"deny",…}}`-Vertrag – genau die Pfade, in die diese `copilot`-Integration und die `claude`-Integration (`~/.claude/settings.json`) bereits schreiben, sodass `failproofai policies --install --cli copilot` (oder `--cli claude`) **bereits im VS Code-Agentenmodus durchgesetzt wird** ohne eine separate `vscode`-Integration (bestätigt anhand von VS Codes Erkennungsprotokollen). + - **Cursor Agent _(Beta)_**: `~/.cursor/hooks.json` (Benutzer), `/.cursor/hooks.json` (Projekt) – Cursor hat keinen `local`-Bereich. Hook-Einträge verwenden das Claude-förmige `{type, command, timeout}`-Format (keine `bash`/`powershell`-Aufteilung), aber gespeichert unter camelCase-Ereignisschlüsseln (`preToolUse`, `beforeSubmitPrompt`, …) in einem flachen Array gemäß Cursors [Hooks-Schema](https://cursor.com/docs/hooks); die Datei trägt einen `version: 1`-Marker auf oberster Ebene. Der Handler normalisiert camelCase → PascalCase über `CURSOR_EVENT_MAP`, sodass vorhandene integrierte Richtlinien unverändert ausgelöst werden. Die Cursor-Agent-Unterstützung ist **Beta**, während Cursors Transkript-Festplattenformat (in der öffentlichen Dokumentation nicht spezifiziert) anhand weiterer realer Installationen überprüft wird. + - **OpenCode _(Beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (Benutzer), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (Projekt) – OpenCode hat keinen `local`-Bereich. Im Gegensatz zu den anderen fünf CLIs verfügt OpenCode über **kein externes Hook-System für Befehle**: Es lädt In-Process-JS/TS-Plugins, die explizit über das `plugin: []`-Array in `opencode.json` registriert werden (die automatische Erkennung aus `.opencode/plugins/` ist **nicht** die Art, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt einen kleinen generierten Plugin-Shim ab, der die failproofai-Binärdatei als Subprozess aufruft und die Claude-förmige JSON-Antwort der Binärdatei in Plugin-Semantik zurückübersetzt: `throw new Error()` für das Ablehnen von Tool-Ereignissen (bricht den Tool-Aufruf ab), `client.session.prompt(...)` für instruct UND für `Stop`/`SubagentStop`-Ablehnungen (übermittelt den Ablehnungsgrund als nächste Benutzernachricht – der einzige Kanal für erzwungene Wiederholung, da `session.idle` nur für Benachrichtigungen ist und ein Auslösen daraus ein No-op ist), und No-op für allow. Der Shim normalisiert sowohl Tool-Namen (Kleinbuchstaben → PascalCase über `OPENCODE_TOOL_MAP`) als auch Tool-Input-Argument-Schlüssel (camelCase → snake_case über `OPENCODE_TOOL_INPUT_MAP` für `Read`/`Write`/`Edit`, z. B. `filePath` → `file_path`, `oldString` → `old_string`), bevor an die Binärdatei weitergeleitet wird, sodass pfadprüfende integrierte Richtlinien wie `block-read-outside-cwd`, `block-env-files` und `block-secrets-write` bei OpenCode-Tool-Aufrufen unverändert ausgelöst werden. Sitzungen leben in OpenCodes SQLite-Datenbank unter `~/.local/share/opencode/opencode.db`; der Sitzungs-Viewer des Dashboards liest sie über `opencode db --format json` und `opencode export `. Die OpenCode-Unterstützung ist **Beta**, während das Verhalten über verschiedene Versionen und anhand weiterer realer Sitzungen überprüft wird. Siehe die [OpenCode-Plugin-Dokumentation](https://opencode.ai/docs/plugins/). + - **Pi _(Beta)_**: `~/.pi/agent/settings.json` (Benutzer), `/.pi/settings.json` (Projekt) – Pi hat keinen `local`-Bereich. Pi lädt TypeScript-Erweiterungspakete beim Start; die Einstellungsdatei ist ein flaches String-Array `{"packages": ["./relative/path", …]}`. failproofai schreibt einen einzelnen Pakete-Array-Eintrag, der auf sein gebündeltes `pi-extension/`-Verzeichnis zeigt. Die Erweiterung abonniert intern Pis `tool_call`/`user_bash`/`input`/`session_start`-Ereignisse und ruft `failproofai --hook --cli pi` als Shell auf; der Handler normalisiert underscore_lower_snake_case → PascalCase über `PI_EVENT_MAP`, sodass vorhandene integrierte Richtlinien unverändert ausgelöst werden. Tool-Input-Argumente werden ebenfalls über `PI_TOOL_INPUT_MAP` normalisiert (Pis Read/Write/Edit liefern `path` statt `file_path`; die Zuordnung des obersten Schlüssels ermöglicht das Auslösen von `block-env-files` und `block-secrets-write` – `block-read-outside-cwd` hatte bereits ein `path`-Fallback). Die Pi-Unterstützung ist **Beta**, während Pis Erweiterungs-API und das Sitzungsprotokoll-Layout sich stabilisieren. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**nur Benutzerbereich** – Hermes hat keine Projekt-/lokale Konfiguration). Hermes ist ein Slack/Telegram-**Gateway**, sodass eine Installation Tool-Aufrufe von jeder Plattform (Slack/Telegram/CLI/Cron) **und** internen Subagenten abfängt. Hook-Einträge sind ein `{command, timeout}`-Paar (Timeout in **Sekunden**) unter einer `hooks:`-Map, die durch Hermes' snake_case-Ereignisse (`pre_tool_call`/`post_tool_call`/`on_session_start`/`on_session_end`/`subagent_stop`) geordnet ist; der Handler normalisiert Ereignisse über `HERMES_EVENT_MAP` und Tool-Namen über `HERMES_TOOL_MAP`, sodass integrierte Richtlinien unverändert ausgelöst werden. Die Konfiguration wird durch einen kommentarerhaltenden YAML-`Document`-Roundtrip bearbeitet, damit andere Einstellungen des Betreibers erhalten bleiben, und die Installation setzt `hooks_auto_accept: true`, sodass das headless Gateway (kein TTY) die Hooks ohne Zustimmungsaufforderung ausführt. Der Evaluator gibt Hermes' `{"decision":"block","reason"}`-stdout-Vertrag aus (Hermes ignoriert Exit-Codes). **Einschränkungen:** Hermes hat kein `Stop`-Ereignis am Ende einer Runde, sodass die `require-*-before-stop`-Builtins dafür nie ausgelöst werden (nicht anwendbar, nicht fehlerhaft); `instruct` degradiert zu allow-with-logged-note (kein Kanal für zusätzlichen Kontext); und die Ausgabe-Secret-Redaktion (`sanitize-*`) kann Tool-Ausgaben über den Shell-Hook-Vertrag nicht umschreiben. Hermes ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine Gateway-Sitzungen direkt aus `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**nur Benutzerbereich** – OpenClaw hat keine Projekt-/lokale Konfiguration). Wie Hermes ist OpenClaw ein selbst gehostetes Multi-Channel-**Gateway**, sodass eine Installation Tool-Aufrufe von jedem Kanal und seinen internen Subagenten abfängt. Die Durchsetzung erfolgt über OpenClaws **In-Process-Plugin-Hooks** (seine dateibasierten internen Hooks sind nur zur Beobachtung und können nicht blockieren), sodass – wie OpenCode/Pi – failproofai ein statisches `openclaw-plugin/`-Paket mitliefert, das die failproofai-Binärdatei asynchron startet und das Ergebnis übersetzt. Die Installation registriert das mitgelieferte Plugin-Verzeichnis in `openclaw.json`'s `plugins.load.paths[]` und aktiviert es unter `plugins.entries.failproofai` (mit `hooks.allowConversationAccess: true`, erforderlich für die rohen Konversations-Hooks). Der Evaluator gibt ein flaches `{permission, reason}`-Ergebnis aus, und der Shim ordnet es der nativen Rückgabeform jedes Hooks zu: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**) und `before_agent_finalize → {action:"revise", reason}` (**Stop** – ein echtes Rundenende-Gate, sodass die `require-*-before-stop`-Builtins auf OpenClaw **durchgesetzt werden**, im Gegensatz zu Hermes). Ereignisse und Tool-Namen werden binärseitig über `OPENCLAW_EVENT_MAP`/`OPENCLAW_TOOL_MAP` normalisiert (`exec→Bash`, `read→Read`, …), sodass integrierte Richtlinien unverändert ausgelöst werden; der Shim schlägt bei Spawn-/Parse-/Timeout-Fehlern offen fehl. OpenClaw ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine JSONL-Sitzungen unter `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (Benutzer), `/.factory/hooks.json` (Projekt) – Factory hat keinen `local`-Bereich. droid liefert ein Claude-ähnliches externes Hook-System für Befehle, jedoch mit zwei Besonderheiten, die live gegen droid v0.171.0 überprüft wurden: (1) Ereignisnamen befinden sich auf der **obersten Ebene** von `hooks.json` – es gibt **keinen `"hooks"`-Wrapper** (droid lehnt einen ab); Tool-Ereignisse (`PreToolUse`/`PostToolUse`) tragen `"matcher": "*"`, Nicht-Tool-Ereignisse lassen ihn weg. (2) Das Ablehnen erfolgt durch Hook-**Exit-Code 2 + stderr**, nicht durch eine JSON-Entscheidung – der `factory`-Zweig des Evaluators gibt Exit 2 für Tool-/Prompt-Ereignisse zurück und `{decision:"block", reason}` nur beim Rundenende-`Stop`-Ereignis (droid's einziger Kanal für erzwungene Wiederholung). Ereignisse sind bereits PascalCase (keine Ereigniszuordnung) und die Nutzlast ist Claude snake_case; nur Tool-Namen werden über `FACTORY_TOOL_MAP` normalisiert (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine On-Disk-JSONL-Sitzungen unter `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (Benutzer), `/.devin/config.json` (Projekt) – Devin hat keinen `local`-Bereich. Devin ist ein **reiner Claude-Klon**, live überprüft gegen devin v3000.1.27: Es verwendet das Standard-Claude-`"hooks"`-Wrapper-Schema (Schreibvorgänge sind zusammenführungserhaltend, sodass andere Schlüssel der Konfigurationsdatei – `org_id`, `theme_mode`, … – erhalten bleiben), bereits PascalCase-Ereignisnamen (keine Ereigniszuordnung, kein Handler-Zweig) und eine Claude-snake_case-stdin-Nutzlast (keine Normalisierung). Der `devin`-Zweig des Evaluators lehnt mit `{"decision":"block","reason"}`-JSON auf stdout bei Exit 0 für **jedes** Ereignis ab (verifiziert – die Blockierung überschrieb `--permission-mode dangerous`); beim Rundenende-`Stop`-Ereignis enthält der Grund die MANDATORY-ACTION-Wording für erzwungene Wiederholung, sodass die `require-*-before-stop`-Builtins durchgesetzt werden. Nur Tool-Namen werden über `DEVIN_TOOL_MAP` normalisiert (`exec→Bash`; `tool_input.command` ist bereits kanonisch). Devin ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine SQLite-Sitzungen unter `~/.local/share/devin/cli/sessions.db` (jede `sessions`-Zeile enthält ein echtes `working_directory`, sodass Sitzungen wie bei Claude nach Projekt-CWD gruppiert werden). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (Benutzer), `/.agents/hooks.json` (Projekt) – Antigravity hat keinen `local`-Bereich. Im Gegensatz zu Factory/Devin hat Antigravity seinen **eigenen** Vertrag (kein Claude-Klon), live überprüft gegen agy v1.1.2. `hooks.json` verwendet ein **named-hook**-Schema: Der oberste Schlüssel ist ein Hook-*Name* (`"failproofai"`), dessen Wert eine Ereignis→Handler-Zuordnung ist – Tool-Ereignisse (`PreToolUse`/`PostToolUse`) kapseln Handler in `{matcher:"*", hooks:[…]}`, während `PreInvocation`/`Stop` **flache** Handler-Arrays sind (andere benannte Hooks bleiben erhalten). Die stdin-Nutzlast ist **camelCase-protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) – failproofai normalisiert sie zu snake_case, bevor Richtlinien ausgeführt werden, und ordnet die PascalCase-Argumente von `run_command` (`CommandLine`/`Cwd`) über `ANTIGRAVITY_TOOL_INPUT_MAP` zu. Der `antigravity`-Zweig des Evaluators verwendet Antigravitys **eigene** Antwortformen: `{decision:"deny", reason}` blockiert ein Tool/Prompt (Exit 0), `{decision:"continue", reason}` beim Rundenende-`Stop` betritt die Schleife erneut (sodass die `require-*-before-stop`-Builtins durchgesetzt werden), und `{injectSteps:[{ephemeralMessage}]}` injiziert eine Anweisung bei `PreInvocation` (→ `UserPromptSubmit`). Tool-Namen werden über `ANTIGRAVITY_TOOL_MAP` normalisiert (`run_command→Bash`, `view_file→Read`, …). Antigravity ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine reinen JSONL-Transkripte unter `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (Konversationsindex in `conversation_summaries.db`). + - **Goose (Codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (Benutzer), `/.agents/plugins/failproofai/hooks/hooks.json` (Projekt) – Goose hat keinen `local`-Bereich. Die Durchsetzung verwendet Gooses **Hooks**-System, die agentenübergreifende **Open Plugins**-Spezifikation: Das Installationsprogramm legt einfach das `failproofai`-Plugin-Verzeichnis ab und Goose erkennt es automatisch beim Start (und registriert es selbst in `~/.config/goose/config.yaml`). Die `hooks.json` verwendet ein Open-Plugins-Schema **mit** einem `"hooks"`-Wrapper auf oberster Ebene, und der Matcher wird bei jedem Ereignis **weggelassen** – ein reines `"*"` ist ein ungültiger Regex, der nichts passt (live überprüft gegen goose v1.43.0). Ereignisnamen sind bereits PascalCase (keine Ereigniszuordnung); die stdin-Nutzlast verwendet `event`/`working_dir`, die der Handler zu `hook_event_name`/`cwd` normalisiert. Der `goose`-Zweig des Evaluators lehnt mit `{"decision":"block","reason"}`-JSON auf stdout bei Exit 0 ab, nur beim **`PreToolUse`**-Ereignis geehrt (in goose ≥ v1.37.0 enthalten) – das beim Shell-Tool **und innerhalb delegierter Subagenten** ausgelöst wird, sodass es der einzige ausreichende Ablehnungspunkt ist; jeder andere Hook-Fehler schlägt **offen** fehl. Goose hat **kein `Stop`-Ereignis**, sodass die `require-*-before-stop`-Builtins nicht gelten (wie bei Hermes). Tool-Namen werden über `GOOSE_TOOL_MAP` normalisiert (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) und Pfadschlüssel über `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine SQLite-Sitzungen unter `~/.local/share/goose/sessions/sessions.db` (jede `sessions`-Zeile enthält ein echtes `working_dir`, sodass Sitzungen wie bei Devin nach Projekt-CWD gruppiert werden; `--no-session`-Scratch-Läufe werden herausgefiltert). +- **`policies-config.json`** – teilt failproofai mit, welche Richtlinien ausgewertet werden sollen und mit welchen Parametern (geteilt über alle Agenten-CLIs) + +`--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` übergeben, um einen bestimmten Agenten anzusprechen (leerzeichen- oder wiederholungsgetrennt für eine beliebige Teilmenge): ```bash failproofai policies --install --cli codex --scope project @@ -237,20 +237,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Wenn `--cli` weggelassen wird, erkennt `failproofai` automatisch, welche Agenten-CLIs installiert sind (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +Wenn `--cli` weggelassen wird, erkennt `failproofai`, welche Agenten-CLIs installiert sind (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **Eine CLI erkannt** – wählt diese CLI automatisch aus, ohne nachzufragen. -- **Mehrere CLIs erkannt** in einem interaktiven Terminal – zeigt eine Einzelauswahl-Eingabeaufforderung mit Pfeiltastennavigation an, gegliedert in einen Abschnitt `Erkannt (N)` (mit einer aggregierten Zeile `Für alle N erkannten installieren` + jede erkannte CLI einzeln) und einen Abschnitt `Nicht installiert (M) · Hooks vorab installieren`, der jede nicht erkannte unterstützte CLI als Vorab-Installationsoption auflistet (↑↓ zum Bewegen, Eingabe zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Erkannt-Abschnitt. -- **Mehrere CLIs erkannt** in einer nicht-interaktiven Ausführung (CI, kein TTY) – installiert für alle erkannten CLIs ohne Nachfrage. -- **Keine erkannt** – fällt auf `claude` zurück, mit einer Warnung, dass kein Agenten-Binary im PATH gefunden wurde; der Hook-Befehl wird trotzdem geschrieben, sodass er aktiviert wird, sobald Sie einen installieren. +- **Eine CLI erkannt** – wählt diese CLI automatisch ohne Rückfrage aus. +- **Mehrere CLIs erkannt** in einem interaktiven Terminal – zeigt eine Pfeil-Einzelauswahlabfrage an, gruppiert in einen `Detected (N)`-Abschnitt (mit einer `Install for all N detected`-Gesamtzeile + jede erkannte CLI einzeln) und einen `Not installed (M) · install hooks ahead of time`-Abschnitt, der jede nicht erkannte unterstützte CLI als Vorab-Installationsoption auflistet (↑↓ zum Bewegen, Enter zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Detected-Abschnitt. +- **Mehrere CLIs erkannt** in einem nicht-interaktiven Lauf (CI, kein TTY) – installiert für alle erkannten CLIs ohne Rückfrage. +- **Keine erkannt** – fällt auf `claude` zurück, mit einer Warnung, dass keine Agenten-Binärdatei im PATH gefunden wurde; der Hook-Befehl wird trotzdem geschrieben, sodass er aktiviert wird, sobald eine installiert wird. -Sie können `policies-config.json` jederzeit direkt bearbeiten; Änderungen werden sofort beim nächsten Hook-Ereignis wirksam, ohne dass ein Neustart erforderlich ist. +`policies-config.json` kann jederzeit direkt bearbeitet werden; Änderungen treten sofort beim nächsten Hook-Ereignis in Kraft, ohne Neustart. + +## Upgrades behalten die Konfiguration + +Eine neue Version von failproofai kann `~/.failproofai/` anders organisieren. In diesem Fall migriert der erste Befehl nach dem Upgrade das Verzeichnis, und **die Konfiguration wird übernommen, nicht zurückgesetzt**: + +| Erhalten | Neu erstellt | +|----------|-------------| +| Richtlinienauswahl und Parameter (`policies-config.json`) | Der Audit-Cache | +| Einstellungen, einschließlich `daemon.configured` und zusätzlicher Capture-Pfade (`config.json`) | Cloud-verwaltete Richtlinien-Deployments – werden beim nächsten Poll neu abgerufen und digest-verifiziert | +| Cloud-Registrierung (`credentials.json`) | Daemon-Scratch-Zustand | +| Eigene Richtliniendateien in `policies/` und die von ihnen importierten Hilfsdateien | | +| Das Entscheidungsprotokoll, das das Dashboard liest, und noch nicht zugestellte Ereignisse | | + +Schlüssel, die von einer *neueren* failproofai-Version geschrieben wurden, werden ebenfalls beibehalten, anstatt von einem älteren Leser verworfen zu werden – sodass der Wechsel zwischen Versionen Einstellungen in keine Richtung stillschweigend verwirft. + +**Nach dem Upgrade ist kein erneutes Setup erforderlich**: Ein migrierter Rechner setzt Richtlinien genau so durch wie zuvor, was ein sicheres Upgrade auf Rechnern ohne anwesende Benutzer ermöglicht. Jede Migration wird in `~/.failproofai/migrations/applied.json` aufgezeichnet, und die unersetzlichen Dateien werden in `~/.failproofai/migrations/backup-layout/` kopiert, bevor irgendetwas ausgeführt wird. + +Siehe [`failproofai update`](/de/cli/update) für das Einzeilen-Upgrade und [`failproofai migrate`](/de/cli/migrate) – einschließlich `--dry-run` – für die Details. --- ## Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten -Committen Sie `.failproofai/policies-config.json` in Ihr Repository: +`.failproofai/policies-config.json` ins Repository committen: ```json { @@ -269,4 +287,4 @@ Committen Sie `.failproofai/policies-config.json` in Ihr Repository: } ``` -Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (per gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne die Teamkollegen zu beeinflussen. \ No newline at end of file +Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (per gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne Teammitglieder zu beeinflussen. \ No newline at end of file diff --git a/docs/de/custom-policies.mdx b/docs/de/custom-policies.mdx index d8dbdb82..036f4a15 100644 --- a/docs/de/custom-policies.mdx +++ b/docs/de/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: Benutzerdefinierte Richtlinien -description: "Schreiben Sie eigene Richtlinien in JavaScript – Konventionen durchsetzen, Drift verhindern, Fehler erkennen, externe Systeme integrieren" +description: "Schreibe eigene Richtlinien in JavaScript – Konventionen durchsetzen, Drift verhindern, Fehler erkennen und mit externen Systemen integrieren" icon: code --- -Benutzerdefinierte Richtlinien ermöglichen es Ihnen, Regeln für beliebige Agentverhalten zu schreiben: Projektkonventionen durchsetzen, Drift verhindern, destruktive Operationen absichern, feststeckende Agenten erkennen oder Integrationen mit Slack, Genehmigungsworkflows und mehr umsetzen. Sie nutzen dasselbe Hook-Event-System und dieselben `allow`-, `deny`- und `instruct`-Entscheidungen wie die integrierten Richtlinien. +Benutzerdefinierte Richtlinien ermöglichen es dir, Regeln für beliebiges Agentenverhalten zu schreiben: Projektkonventionen durchsetzen, Drift verhindern, destruktive Operationen absichern, feststeckende Agenten erkennen oder mit Slack, Genehmigungsworkflows und mehr integrieren. Sie verwenden dasselbe Hook-Event-System und dieselben `allow`-, `deny`-, `instruct`-Entscheidungen wie eingebaute Richtlinien. --- @@ -41,7 +41,7 @@ failproofai policies --install --custom ./my-policies.js ### Option 1: Konventionsbasiert (empfohlen) -Legen Sie `*policies.{js,mjs,ts}`-Dateien im Verzeichnis `.failproofai/policies/` ab – sie werden automatisch geladen, ohne Flags oder Konfigurationsänderungen. Dies funktioniert wie Git-Hooks: Datei ablegen, fertig. +Lege `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab und sie werden automatisch geladen – ohne Flags oder Konfigurationsänderungen. Das funktioniert wie Git-Hooks: Datei ablegen, fertig. ``` # Projektebene — in Git eingecheckt, mit dem Team geteilt @@ -52,24 +52,24 @@ Legen Sie `*policies.{js,mjs,ts}`-Dateien im Verzeichnis `.failproofai/policies/ ~/.failproofai/policies/my-policies.mjs ``` -**So funktioniert es:** -- Sowohl das Projekt- als auch das Benutzerverzeichnis werden durchsucht (Vereinigungsmenge – kein Erster-gewinnt-nach-Scope) -- Dateien werden alphabetisch innerhalb jedes Verzeichnisses geladen. Mit `01-`, `02-` als Präfix können Sie die Reihenfolge steuern +**Funktionsweise:** +- Sowohl Projekt- als auch Benutzerverzeichnisse werden durchsucht (Vereinigung – kein Erste-Ebene-gewinnt-Prinzip) +- Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. Mit dem Präfix `01-`, `02-` lässt sich die Reihenfolge steuern - Nur Dateien, die `*policies.{js,mjs,ts}` entsprechen, werden geladen; andere Dateien werden ignoriert -- Jede Datei wird unabhängig geladen (Fail-open pro Datei) -- Funktioniert zusammen mit explizitem `--custom` und integrierten Richtlinien +- Jede Datei wird unabhängig geladen (fail-open pro Datei) +- Funktioniert zusammen mit expliziten `--custom`- und eingebauten Richtlinien -Konventionsrichtlinien sind der einfachste Weg, einen Qualitätsstandard für Ihre Organisation aufzubauen. Checken Sie `.failproofai/policies/` in Git ein, und jedes Teammitglied erhält automatisch dieselben Regeln – kein Setup pro Entwickler erforderlich. Wenn Ihr Team neue Fehlermuster entdeckt, fügen Sie eine Richtlinie hinzu und pushen Sie. Mit der Zeit werden diese zu einem lebendigen Qualitätsstandard, der sich mit jedem Beitrag weiterentwickelt. +Konventionsrichtlinien sind die einfachste Möglichkeit, einen Qualitätsstandard für deine Organisation aufzubauen. Checke `.failproofai/policies/` in Git ein, und jedes Teammitglied erhält automatisch dieselben Regeln – kein individuelles Setup erforderlich. Wenn dein Team neue Fehlerquellen entdeckt, füge eine Richtlinie hinzu und pushe sie. Mit der Zeit werden diese zu einem lebendigen Qualitätsstandard, der sich mit jedem Beitrag weiterentwickelt. ### Option 2: Expliziter Dateipfad ```bash -# Installation mit einer benutzerdefinierten Richtliniendatei +# Mit einer benutzerdefinierten Richtliniendatei installieren failproofai policies --install --custom ./my-policies.js -# Benutzerdefinierte Richtlinienpfade ersetzen +# Die benutzerdefinierten Richtlinienpfade ersetzen failproofai policies --install --custom ./new-policies.js # Mehrere explizite Dateien konfigurieren (in Flag-Reihenfolge geladen) @@ -79,17 +79,17 @@ failproofai policies --install --custom ./security.js --custom ./workflow.js failproofai policies --uninstall --custom ``` -Aufgelöste absolute Pfade werden in `policies-config.json` als `customPoliciesPaths` gespeichert. Wiederholen Sie `--custom`, um mehrere Dateien zu konfigurieren. Bestehende Konfigurationen mit dem veralteten Feld `customPoliciesPath` funktionieren weiterhin. Dateien werden bei jedem Hook-Event neu geladen – es gibt kein Caching zwischen Events. +Aufgelöste absolute Pfade werden in `policies-config.json` als `customPoliciesPaths` gespeichert. `--custom` kann mehrfach angegeben werden, um mehrere Dateien zu konfigurieren. Bestehende Konfigurationen, die das veraltete Feld `customPoliciesPath` verwenden, funktionieren weiterhin. Dateien werden bei jedem Hook-Event neu geladen – es gibt kein Caching zwischen Events. -Jede registrierte Richtlinie erscheint mit einem eigenen Umschalter im Dashboard. Das Deaktivieren einer Richtlinie speichert ihre quellenqualifizierte ID in `disabledCustomPolicies`; die Datei und ihre anderen Richtlinien werden weiterhin geladen, während die deaktivierte Richtlinie vor dem Event-Matching ausgeschlossen wird. Richtliniennamen, die über mehrere Dateien hinweg doppelt vorkommen, haben unabhängige Umschalter. +Jede registrierte Richtlinie erscheint mit einem eigenen Schalter im Dashboard. Wird eine Richtlinie deaktiviert, wird ihre quellenqualifizierte ID in `disabledCustomPolicies` eingetragen; die Datei und ihre anderen Richtlinien werden weiterhin geladen, während die deaktivierte Richtlinie vor dem Event-Matching ausgeschlossen wird. Richtliniennamen, die über mehrere Dateien hinweg doppelt vorkommen, verfügen über unabhängige Schalter. -### Beide Methoden kombinieren +### Beide zusammen verwenden Konventionsrichtlinien und explizite `--custom`-Dateien können nebeneinander existieren. Ladereihenfolge: 1. Explizite `customPoliciesPaths`-Dateien (in konfigurierter Reihenfolge) -2. Projektkonventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch) -3. Benutzerkonventionsdateien (`~/.failproofai/policies/`, alphabetisch) +2. Projekt-Konventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch) +3. Benutzer-Konventionsdateien (`~/.failproofai/policies/`, alphabetisch) --- @@ -103,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registriert eine Richtlinie. Rufen Sie diese Methode beliebig oft auf, um mehrere Richtlinien in derselben Datei zu definieren. +Registriert eine Richtlinie. Kann für mehrere Richtlinien in derselben Datei beliebig oft aufgerufen werden. ```ts customPolicies.add({ - name: string; // erforderlich – eindeutige Kennung - description?: string; // wird in der Ausgabe von `failproofai policies` angezeigt - match?: { events?: HookEventType[] }; // nach Eventtyp filtern; weglassen, um alle zu erfassen + name: string; // erforderlich - eindeutiger Bezeichner + description?: string; // wird in der `failproofai policies`-Ausgabe angezeigt + match?: { events?: HookEventType[] }; // nach Event-Typ filtern; weglassen, um alle abzugleichen fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` ### Entscheidungs-Hilfsfunktionen -| Funktion | Wirkung | Wann verwenden | -|----------|--------|----------| +| Funktion | Wirkung | Wann einsetzen | +|----------|---------|----------------| | `allow()` | Operation stillschweigend erlauben | Die Aktion ist sicher, keine Meldung erforderlich | | `deny(message)` | Operation blockieren | Der Agent sollte diese Aktion nicht ausführen | | `instruct(message)` | Kontext hinzufügen, ohne zu blockieren | Dem Agenten zusätzlichen Kontext geben, um ihn auf Kurs zu halten | -`deny(message)` – die Nachricht erscheint für Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` bricht alle weiteren Auswertungen ab. +`deny(message)` – die Meldung erscheint bei Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` schließt alle weitere Auswertung kurz. -`instruct(message)` – die Nachricht wird dem Kontext von Claude für den aktuellen Tool-Aufruf hinzugefügt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt. +`instruct(message)` – die Meldung wird dem Kontext von Claude für den aktuellen Tool-Aufruf hinzugefügt. Alle `instruct`-Meldungen werden gesammelt und gemeinsam zugestellt. -Sie können jedem `deny`- oder `instruct`-Message zusätzliche Hinweise anfügen, indem Sie ein `hint`-Feld in `policyParams` angeben – ohne Codeänderungen. Dies funktioniert auch für benutzerdefinierte (`custom/`), Projektkonventions- (`.failproofai-project/`) und Benutzerkonventionsrichtlinien (`.failproofai-user/`). Weitere Details finden Sie unter [Konfiguration → hint](/de/configuration#hint-cross-cutting). +Du kannst jeder `deny`- oder `instruct`-Meldung zusätzliche Hinweise hinzufügen, indem du ein `hint`-Feld in `policyParams` setzt – ohne Codeänderung. Dies funktioniert auch für benutzerdefinierte (`custom/`), Projekt-Konventions- (`.failproofai-project/`) und Benutzer-Konventionsrichtlinien (`.failproofai-user/`). Siehe [Konfiguration → hint](/de/configuration#hint-cross-cutting) für Details. -### Informative Allow-Nachrichten +### Informative allow-Meldungen -`allow(message)` erlaubt die Operation **und** sendet eine informative Nachricht an Claude. Die Nachricht wird als `additionalContext` in der stdout-Antwort des Hook-Handlers übermittelt – derselbe Mechanismus wie bei `instruct`, aber semantisch anders: Es handelt sich um ein Statusupdate, nicht um eine Warnung. +`allow(message)` erlaubt die Operation **und** sendet eine informative Meldung an Claude. Die Meldung wird als `additionalContext` in der stdout-Antwort des Hook-Handlers zugestellt – derselbe Mechanismus wie bei `instruct`, aber semantisch anders: Es ist eine Statusmeldung, keine Warnung. -| Funktion | Wirkung | Wann verwenden | -|----------|--------|----------| -| `allow(message)` | Erlauben und Kontext an Claude senden | Bestätigen, dass eine Prüfung erfolgreich war, oder erklären, warum eine Prüfung übersprungen wurde | +| Funktion | Wirkung | Wann einsetzen | +|----------|---------|----------------| +| `allow(message)` | Erlauben und Kontext an Claude senden | Bestätigen, dass eine Prüfung bestanden wurde, oder erklären, warum eine Prüfung übersprungen wurde | Anwendungsfälle: - **Statusbestätigungen:** `allow("All CI checks passed.")` – teilt Claude mit, dass alles in Ordnung ist -- **Fail-open-Erklärungen:** `allow("GitHub CLI not installed, skipping CI check.")` – erklärt Claude, warum eine Prüfung übersprungen wurde, damit es den vollen Kontext hat -- **Mehrere Nachrichten werden gesammelt:** Wenn mehrere Richtlinien jeweils `allow(message)` zurückgeben, werden alle Nachrichten mit Zeilenumbrüchen verbunden und gemeinsam übermittelt +- **Fail-open-Erklärungen:** `allow("GitHub CLI not installed, skipping CI check.")` – teilt Claude mit, warum eine Prüfung übersprungen wurde, damit der Agent den vollen Kontext hat +- **Mehrere Meldungen akkumulieren:** wenn mehrere Richtlinien jeweils `allow(message)` zurückgeben, werden alle Meldungen mit Zeilenumbrüchen verbunden und gemeinsam zugestellt ```js customPolicies.add({ @@ -163,29 +163,29 @@ customPolicies.add({ ### `PolicyContext`-Felder | Feld | Typ | Beschreibung | -|-------|------|-------------| +|------|-----|--------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | Das aufgerufene Tool (z. B. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Die Eingabeparameter des Tools | -| `payload` | `Record` | Vollständige rohe Event-Nutzlast von Claude Code | -| `session` | `SessionMetadata \| undefined` | Sitzungskontext (siehe unten) | +| `payload` | `Record` | Vollständiger roher Event-Payload von Claude Code | +| `session` | `SessionMetadata \| undefined` | Session-Kontext (siehe unten) | ### `SessionMetadata`-Felder | Feld | Typ | Beschreibung | -|-------|------|-------------| -| `sessionId` | `string` | Claude Code-Sitzungskennung | -| `cwd` | `string` | Arbeitsverzeichnis der Claude Code-Sitzung | -| `transcriptPath` | `string` | Pfad zur JSONL-Transkriptdatei der Sitzung | +|------|-----|--------------| +| `sessionId` | `string` | Claude Code-Session-Bezeichner | +| `cwd` | `string` | Arbeitsverzeichnis der Claude Code-Session | +| `transcriptPath` | `string` | Pfad zur JSONL-Transkriptdatei der Session | -### Eventtypen +### Event-Typen | Event | Wann es ausgelöst wird | `toolInput`-Inhalt | -|-------|--------------|----------------------| +|-------|----------------------|--------------------| | `PreToolUse` | Bevor Claude ein Tool ausführt | Die Eingabe des Tools (z. B. `{ command: "..." }` für Bash) | -| `PostToolUse` | Nachdem ein Tool abgeschlossen wurde | Die Eingabe des Tools + `tool_result` (die Ausgabe) | +| `PostToolUse` | Nachdem ein Tool abgeschlossen ist | Die Eingabe des Tools + `tool_result` (die Ausgabe) | | `Notification` | Wenn Claude eine Benachrichtigung sendet | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` – Hooks müssen immer `allow()` zurückgeben, sie können Benachrichtigungen nicht blockieren | -| `Stop` | Wenn die Claude-Sitzung endet | Leer | +| `Stop` | Wenn die Claude-Session endet | Leer | --- @@ -193,18 +193,18 @@ customPolicies.add({ Richtlinien werden in dieser Reihenfolge ausgewertet: -1. Integrierte Richtlinien (in Definitionsreihenfolge) +1. Eingebaute Richtlinien (in Definitionsreihenfolge) 2. Explizite benutzerdefinierte Richtlinien aus `customPoliciesPath` (in `.add()`-Reihenfolge) 3. Konventionsrichtlinien aus dem Projekt `.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb) 4. Konventionsrichtlinien aus dem Benutzerverzeichnis `~/.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb) -Das erste `deny` bricht alle nachfolgenden Richtlinien ab. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt. +Das erste `deny` schließt alle nachfolgenden Richtlinien kurz. Alle `instruct`-Meldungen werden gesammelt und gemeinsam zugestellt. --- -## Transitive Imports +## Transitive Importe Benutzerdefinierte Richtliniendateien können lokale Module über relative Pfade importieren: @@ -223,46 +223,46 @@ customPolicies.add({ }); ``` -Alle relativen Imports, die von der Einstiegsdatei aus erreichbar sind, werden aufgelöst. Dies wird implementiert, indem `from "failproofai"`-Imports auf den tatsächlichen dist-Pfad umgeschrieben und temporäre `.mjs`-Dateien erstellt werden, um ESM-Kompatibilität sicherzustellen. +Alle von der Einstiegsdatei aus erreichbaren relativen Importe werden aufgelöst. Dies wird implementiert, indem `from "failproofai"`-Importe auf den tatsächlichen dist-Pfad umgeschrieben und temporäre `.mjs`-Dateien erstellt werden, um ESM-Kompatibilität sicherzustellen. --- -## Eventtyp-Filterung +## Event-Typ-Filterung -Verwenden Sie `match.events`, um einzuschränken, wann eine Richtlinie ausgelöst wird: +Verwende `match.events`, um einzuschränken, wann eine Richtlinie ausgelöst wird: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Wird nur ausgelöst, wenn die Sitzung endet - // ctx.session.transcriptPath enthält das vollständige Sitzungsprotokoll + // Wird nur ausgelöst, wenn die Session endet + // ctx.session.transcriptPath enthält das vollständige Session-Protokoll return allow(); }, }); ``` -Lassen Sie `match` vollständig weg, um bei jedem Eventtyp ausgelöst zu werden. +`match` vollständig weglassen, um bei jedem Event-Typ auszulösen. --- -## Fehlerbehandlung und Fehlermodi +## Fehlerbehandlung und Fehlerverhalten -Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals integrierte Richtlinien oder bringen den Hook-Handler zum Absturz. +Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals eingebaute Richtlinien oder bringen den Hook-Handler zum Absturz. | Fehler | Verhalten | -|---------|----------| -| `customPoliciesPath` nicht gesetzt | Keine expliziten benutzerdefinierten Richtlinien werden ausgeführt; Konventionsrichtlinien und integrierte Richtlinien laufen normal weiter | -| Datei nicht gefunden | Warnung in `~/.failproofai/hook.log` protokolliert; integrierte Richtlinien laufen weiter | -| Syntax-/Importfehler (explizit) | Fehler in `~/.failproofai/hook.log` protokolliert; explizite benutzerdefinierte Richtlinien werden übersprungen | -| Syntax-/Importfehler (Konvention) | Fehler protokolliert; diese Datei wird übersprungen, andere Konventionsdateien werden weiterhin geladen | -| `fn` wirft zur Laufzeit | Fehler protokolliert; dieser Hook wird als `allow` behandelt; andere Hooks laufen weiter | -| `fn` dauert länger als 10 Sekunden | Timeout protokolliert; wird als `allow` behandelt | +|--------|-----------| +| `customPoliciesPath` nicht gesetzt | Keine expliziten benutzerdefinierten Richtlinien werden ausgeführt; Konventionsrichtlinien und eingebaute Richtlinien laufen normal weiter | +| Datei nicht gefunden | Warnung wird in `~/.failproofai/hook.log` protokolliert; eingebaute Richtlinien laufen weiter | +| Syntax-/Importfehler (explizit) | Fehler wird in `~/.failproofai/hook.log` protokolliert; explizite benutzerdefinierte Richtlinien werden übersprungen | +| Syntax-/Importfehler (Konvention) | Fehler wird protokolliert; diese Datei wird übersprungen, andere Konventionsdateien werden weiterhin geladen | +| `fn` wirft zur Laufzeit | Fehler wird protokolliert; dieser Hook wird als `allow` behandelt; andere Hooks laufen weiter | +| `fn` dauert länger als 10 Sekunden | Timeout wird protokolliert; wird als `allow` behandelt | | Konventionsverzeichnis fehlt | Keine Konventionsrichtlinien werden ausgeführt; kein Fehler | -Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachten Sie die Logdatei: +Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachte die Protokolldatei: ```bash tail -f ~/.failproofai/hook.log @@ -271,7 +271,7 @@ tail -f ~/.failproofai/hook.log --- -## Vollständiges Beispiel: Mehrere Richtlinien +## Vollständiges Beispiel: mehrere Richtlinien ```js // my-policies.js @@ -328,14 +328,14 @@ export { customPolicies }; ## Beispiele -Das Verzeichnis `examples/` enthält sofort ausführbare Richtliniendateien: +Das Verzeichnis `examples/` enthält einsatzbereite Richtliniendateien: | Datei | Inhalt | -|------|----------| -| `examples/policies-basic.js` | Fünf Einstiegsrichtlinien für häufige Agentfehlermodi | -| `examples/policies-advanced/index.js` | Fortgeschrittene Muster: transitive Imports, asynchrone Aufrufe, Output-Bereinigung und Sitzungsende-Hooks | -| `examples/convention-policies/security-policies.mjs` | Konventionsbasierte Sicherheitsrichtlinien (Block .env-Schreibvorgänge, Git-Historienschreiben verhindern) | -| `examples/convention-policies/workflow-policies.mjs` | Konventionsbasierte Workflow-Richtlinien (Testeinstufungen, Audit-Dateischreibvorgänge) | +|-------|--------| +| `examples/policies-basic.js` | Fünf Einstiegsrichtlinien, die häufige Agenten-Fehlerquellen abdecken | +| `examples/policies-advanced/index.js` | Erweiterte Muster: transitive Importe, asynchrone Aufrufe, Ausgabe-Bereinigung und Session-End-Hooks | +| `examples/convention-policies/security-policies.mjs` | Konventionsbasierte Sicherheitsrichtlinien (blockiert .env-Schreibvorgänge, verhindert das Umschreiben der Git-Historie) | +| `examples/convention-policies/workflow-policies.mjs` | Konventionsbasierte Workflow-Richtlinien (Test-Erinnerungen, Datei-Schreibprotokolle) | ### Explizite Dateibeispiele verwenden diff --git a/docs/de/dashboard.mdx b/docs/de/dashboard.mdx index 75c76c7d..8a306e0e 100644 --- a/docs/de/dashboard.mdx +++ b/docs/de/dashboard.mdx @@ -1,10 +1,10 @@ --- title: Dashboard -description: "Agent-Sitzungen überwachen, Tool-Aufrufe prüfen und Richtlinien verwalten" +description: "Agenten-Sitzungen überwachen, Tool-Aufrufe prüfen und Richtlinien verwalten" icon: chart-line --- -Das failproofai-Dashboard ist eine lokale Webanwendung zur Überwachung Ihrer KI-Agent-Sitzungen und zur Verwaltung von Richtlinien. Sehen Sie, was Ihre Agents während Ihrer Abwesenheit getan haben. +Das failproofai-Dashboard ist eine lokale Webanwendung zur Überwachung Ihrer KI-Agenten-Sitzungen und zur Verwaltung von Richtlinien. Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. --- @@ -16,7 +16,7 @@ failproofai Öffnet sich unter `http://localhost:8020`. -Das Dashboard liest lokale Projekt-, Sitzungs- und failproofai-Konfigurationsdaten direkt aus dem Dateisystem. Optionale authentifizierte Funktionen, wie Audit-Erinnerungen und Einladungen, senden die für diese Anfragen benötigten Informationen (einschließlich E-Mail-Adressen) an Remote-APIs. +Das Dashboard liest lokale Projekt-, Sitzungs- und failproofai-Konfigurationsdaten direkt vom Dateisystem. Optionale authentifizierte Funktionen, wie Audit-Erinnerungen und Einladungen, senden die für diese Anfragen benötigten Informationen (einschließlich E-Mail-Adressen) an externe APIs. --- @@ -24,16 +24,16 @@ Das Dashboard liest lokale Projekt-, Sitzungs- und failproofai-Konfigurationsdat ### Projekte -Listet alle Claude Code-, OpenAI Codex-, GitHub Copilot CLI- _(Beta)_, Cursor Agent- _(Beta)_, OpenCode- _(Beta)_, Pi- _(Beta)_, Hermes-, OpenClaw-, Factory Droid-, Devin-, Antigravity- und Goose-Projekte auf, die auf Ihrem Computer gefunden wurden. Claude-Projekte werden aus `~/.claude/projects/` (oder dem durch `CLAUDE_PROJECTS_PATH` festgelegten Pfad) ermittelt; Codex-Projekte werden durch Scannen aller Transkripte unter `~/.codex/sessions///
/*.jsonl` und Gruppierung nach dem in jedem ersten Datensatz der Sitzung aufgezeichneten `cwd` entdeckt; Copilot CLI-Projekte werden durch Scannen jeder `~/.copilot/session-state//workspace.yaml` (konfigurierbar über `COPILOT_HOME`) und Gruppierung nach dem `cwd`-Feld entdeckt; Cursor Agent-Projekte werden durch Scannen der sitzungsspezifischen Metadaten unter `~/.cursor/agent-sessions//` (konfigurierbar über `CURSOR_HOME`, mit `conversations/` und `sessions/` als Fallback) für ein `cwd`-Skalar in `meta.json` / `session.json` / `workspace.yaml` entdeckt; OpenCode-Projekte werden durch Abfragen der SQLite-Datenbank unter `~/.local/share/opencode/opencode.db` via `opencode db --format json` entdeckt (wir lesen die Tabellen `session` und `project` und gruppieren nach `project_id`); Pi-Projekte werden durch Scannen der sitzungsspezifischen JSONL-Transkripte unter `~/.pi/agent/sessions//_.jsonl` (konfigurierbar über `PI_SESSIONS_DIR`) und Auslesen des `cwd` aus dem ersten Datensatz jeder Sitzung entdeckt; Hermes Gateway-Sitzungen werden direkt aus dem SQLite-Speicher jedes Profils gelesen — `~/.hermes/state.db` sowie `~/.hermes/profiles//state.db` (überschreibbar über `HERMES_HOME` oder `HERMES_DB_PATH` für eine einzelne Datenbank) — und in `hermes--`-Projekte nach Profil und `source` (Slack/Telegram/cli/cron – Gateway-Sitzungen haben kein cwd) gruppiert; OpenClaw Gateway-Sitzungen werden aus `~/.openclaw/agents//sessions/*.jsonl` gelesen und in `openclaw--`-Projekte nach Agent und Kanal gruppiert (ebenfalls ohne cwd); Factory Droid-Projekte werden aus den JSONL-Transkripten unter `~/.factory/sessions//*.jsonl` ermittelt und nach cwd gruppiert; Devin-Projekte aus der SQLite-Datenbank unter `~/.local/share/devin/cli/sessions.db` (gruppiert nach dem `working_directory` jeder Sitzung); Antigravity-Projekte aus den JSONL-Transkripten unter `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` und nach cwd gruppiert; und Goose-Projekte aus der SQLite-Datenbank unter `~/.local/share/goose/sessions/sessions.db` (gruppiert nach dem `working_dir` jeder Sitzung). Ein Projekt, das von mehreren CLIs verwendet wurde, wird als einzelne Zeile mit allen passenden Badges angezeigt. Verwenden Sie das **CLI**-Dropdown über der Tabelle, um nach einer bestimmten Agent-CLI zu filtern; die URL speichert Ihre Auswahl als `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Listet alle Claude Code-, OpenAI Codex-, GitHub Copilot CLI- _(Beta)_, Cursor Agent- _(Beta)_, OpenCode- _(Beta)_, Pi- _(Beta)_, Hermes-, OpenClaw-, Factory Droid-, Devin-, Antigravity- und Goose-Projekte auf, die auf Ihrem Rechner gefunden wurden. Claude-Projekte werden aus `~/.claude/projects/` (oder dem durch `CLAUDE_PROJECTS_PATH` festgelegten Pfad) erkannt; Codex-Projekte werden durch das Scannen aller Transkripte unter `~/.codex/sessions///
/*.jsonl` und Gruppierung nach dem in jedem ersten Datensatz einer Sitzung gespeicherten `cwd` ermittelt; Copilot-CLI-Projekte werden durch das Scannen von `~/.copilot/session-state//workspace.yaml` (konfigurierbar über `COPILOT_HOME`) und Gruppierung nach dem `cwd`-Feld erkannt; Cursor-Agent-Projekte werden durch das Scannen von sitzungsbezogenen Metadaten unter `~/.cursor/agent-sessions//` (konfigurierbar über `CURSOR_HOME`, mit `conversations/` und `sessions/` als Fallbacks) nach einem `cwd`-Skalar in `meta.json` / `session.json` / `workspace.yaml` erkannt; OpenCode-Projekte werden durch Abfragen der SQLite-Datenbank unter `~/.local/share/opencode/opencode.db` via `opencode db --format json` ermittelt (wir lesen die Tabellen `session` und `project` und gruppieren nach `project_id`); Pi-Projekte werden durch das Scannen sitzungsbezogener JSONL-Transkripte unter `~/.pi/agent/sessions//_.jsonl` (konfigurierbar über `PI_SESSIONS_DIR`) und Auslesen des `cwd` aus dem ersten Datensatz jeder Sitzung erkannt; Hermes-Gateway-Sitzungen werden direkt aus dem SQLite-Speicher jedes Profils gelesen — `~/.hermes/state.db` sowie `~/.hermes/profiles//state.db` (überschreibbar via `HERMES_HOME` oder `HERMES_DB_PATH` für eine einzelne Datenbank) — und nach Profil und `source` (Slack/Telegram/cli/cron — Gateway-Sitzungen haben kein cwd) in `hermes--`-Projekte gruppiert; OpenClaw-Gateway-Sitzungen werden aus `~/.openclaw/agents//sessions/*.jsonl` gelesen und nach Agent und Kanal in `openclaw--`-Projekte gruppiert (ebenfalls ohne cwd); Factory-Droid-Projekte werden aus den JSONL-Transkripten unter `~/.factory/sessions//*.jsonl` erkannt und nach cwd gruppiert; Devin-Projekte aus der SQLite-Datenbank unter `~/.local/share/devin/cli/sessions.db` (gruppiert nach dem `working_directory` jeder Sitzung); Antigravity-Projekte aus den JSONL-Transkripten unter `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` und nach cwd gruppiert; und Goose-Projekte aus der SQLite-Datenbank unter `~/.local/share/goose/sessions/sessions.db` (gruppiert nach dem `working_dir` jeder Sitzung). Ein Projekt, das von mehreren CLIs verwendet wurde, wird als einzelne Zeile mit allen passenden Badges angezeigt. Verwenden Sie das **CLI**-Dropdown über der Tabelle, um nach einer bestimmten Agenten-CLI zu filtern; die URL speichert Ihre Auswahl als `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -Hermes und OpenClaw sind benutzerbezogen und haben kein Arbeitsverzeichnis zur Gruppierung, daher werden sie als **ausklappbarer Ordnerbaum** dargestellt — Profil (oder Agent) auf der obersten Ebene, darunter die Kanäle — während alle cwd-basierten CLIs als flache Zeile verbleiben. Ordnerzeilen fassen die Sitzungsanzahl und die jüngste Aktivität aller untergeordneten Elemente zusammen, eingeklappte Ordner werden zwischen Besuchen gespeichert, und eine Schlüsselwortsuche klappt gefundene Treffer auf. +Hermes und OpenClaw sind benutzergebunden und haben kein Arbeitsverzeichnis zur Gruppierung, daher werden sie als **ausklappbarer Ordnerbaum** dargestellt — Profil (oder Agent) auf der obersten Ebene, darunter die jeweiligen Kanäle — während jede cwd-basierte CLI als flache Zeile bleibt. Ordnerzeilen fassen die Sitzungsanzahl und die jüngste Aktivität aller untergeordneten Einträge zusammen, eingeklappte Ordner werden zwischen Besuchen gespeichert, und eine Schlüsselwortsuche klappt passende Treffer auf. Jedes Projekt zeigt: - Projektname (abgeleitet vom Ordnerpfad) -- Ein CLI-Badge — `Claude Code` (orange), `OpenAI Codex` (lila), `GitHub Copilot` (blau), `Cursor Agent` (smaragd), `OpenCode` (bernstein), `Pi` (pink) und/oder `Hermes` (indigo) +- Ein CLI-Badge — `Claude Code` (orange), `OpenAI Codex` (lila), `GitHub Copilot` (blau), `Cursor Agent` (smaragdgrün), `OpenCode` (bernstein), `Pi` (rosa) und/oder `Hermes` (indigo) - Datum der letzten Sitzungsaktivität -Klicken Sie auf ein Projekt, um seine Sitzungen anzuzeigen. +Klicken Sie auf ein Projekt, um dessen Sitzungen anzuzeigen. ### Sitzungen @@ -41,52 +41,52 @@ Listet alle Sitzungen innerhalb eines Projekts auf. Jede Sitzung zeigt: - Sitzungs-ID - Start- und Endzeitstempel - Anzahl der Tool-Aufrufe -- Anzahl der Hook-Aktivitäten (ausgelöste Richtlinien) +- Hook-Aktivitätszähler (ausgelöste Richtlinien) -Verwenden Sie den Datumsbereichsfilter und die Sitzungs-ID-Suche, um die Liste einzugrenzen. Sitzungen sind paginiert. +Verwenden Sie den Datumsbereichsfilter und die Sitzungs-ID-Suche, um die Liste einzugrenzen. Sitzungen werden seitenweise angezeigt. -Klicken Sie auf eine Sitzung, um den Sitzungsbetrachter zu öffnen. +Klicken Sie auf eine Sitzung, um den Sitzungs-Viewer zu öffnen. -### Sitzungsbetrachter +### Sitzungs-Viewer -Der Sitzungsbetrachter beantwortet die zentrale Frage bei autonomen Agents: Was hat der Agent getan, und ist er auf Kurs geblieben? Ein CLI-Badge neben dem Header zeigt an, ob es sich um ein Claude Code-, OpenAI Codex-, GitHub Copilot CLI-, Cursor Agent-, OpenCode-, Pi-, Hermes-, OpenClaw-, Factory Droid-, Devin-, Antigravity- oder Goose-Transkript handelt. Er zeigt einen Zeitstrahl aller Ereignisse in einer Sitzung: +Der Sitzungs-Viewer beantwortet die entscheidende Frage bei autonomen Agenten: Was hat der Agent getan, und ist er auf Kurs geblieben? Ein CLI-Badge neben der Kopfzeile zeigt an, ob es sich bei der Sitzung um ein Claude Code-, OpenAI Codex-, GitHub Copilot CLI-, Cursor Agent-, OpenCode-, Pi-, Hermes-, OpenClaw-, Factory Droid-, Devin-, Antigravity- oder Goose-Transkript handelt. Er zeigt einen Zeitstrahl aller Ereignisse in einer Sitzung: -- **Nachrichten** – Claudes Textantworten und Benutzeraufforderungen -- **Tool-Aufrufe** – Jedes Tool, das Claude aufgerufen hat, mit Ein- und Ausgabe -- **Richtlinienaktivität** – Für jeden Tool-Aufruf: welche Richtlinien ausgelöst wurden und welche Entscheidung sie zurückgegeben haben +- **Nachrichten** — Claudes Textantworten und Benutzeranfragen +- **Tool-Aufrufe** — Jedes Tool, das Claude aufgerufen hat, mit Ein- und Ausgabe +- **Richtlinienaktivität** — Für jeden Tool-Aufruf, welche Richtlinien ausgelöst wurden und welche Entscheidung sie zurückgaben -Die Statistikleiste oben zeigt Sitzungsdauer, Gesamtzahl der Tool-Aufrufe und eine Zusammenfassung der Hook-Entscheidungen (allow / deny / instruct-Anzahl). +Die Statusleiste oben zeigt Sitzungsdauer, Gesamtzahl der Tool-Aufrufe und eine Zusammenfassung der Hook-Entscheidungen (allow / deny / instruct-Zählungen). -Klicken Sie auf die Schaltfläche **Logs herunterladen**, um die Sitzung zu exportieren. Für Claude Code-, Codex-, Copilot-, Cursor- und Pi-Sitzungen erhalten Sie das originale JSONL-Transkript vom Datenträger byte-für-byte; für OpenCode (dessen Sitzungen in SQLite und nicht auf der Festplatte gespeichert sind) erhalten Sie ein JSON-Dokument, das die zugrunde liegenden Tabellen `session` / `messages` / `parts` widerspiegelt. +Klicken Sie auf die Schaltfläche **Protokolle herunterladen**, um die Sitzung zu exportieren. Bei Claude Code-, Codex-, Copilot-, Cursor- und Pi-Sitzungen erhalten Sie das ursprüngliche JSONL-Transkript vom Datenträger Byte für Byte; bei OpenCode (dessen Sitzungen in SQLite statt auf der Festplatte gespeichert sind) erhalten Sie ein JSON-Dokument, das die zugrunde liegenden Tabellen `session` / `messages` / `parts` widerspiegelt. ### Audit -Ein charaktergetriebener Bericht darüber, wie sich Ihr Agent tatsächlich in vergangenen Sitzungen verhalten hat. Führt denselben Scan wie die `failproofai audit`-CLI durch, stellt ihn jedoch als einseitiges, teilbares Poster + vier Abschnitte unterhalb des sichtbaren Bereichs dar: +Ein charakterorientierter Bericht darüber, wie sich Ihr Agent tatsächlich über vergangene Sitzungen hinweg verhalten hat. Führt denselben Scan wie die `failproofai audit`-CLI durch, stellt ihn aber als einseitiges, teilbares Poster dar, ergänzt durch vier unterhalb des sichtbaren Bereichs liegende Abschnitte: -1. **Poster** — füllt den ersten Viewport. Eigenständiger PNG-Erfassungsbereich mit dem failproof_ai-Wortmarke + Audit-Label · Archetyp-Index (`№ NN of 08`) + Audit-Datum · numerische Punktzahl (0–100) + Perzentil-Pille (`top 15%`) · der Archetyp-Name (einer von `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + 3-Keyword-Streifen · `// only N% of agents are this archetype`-Seltenheitszeile · 8×8-Pixel-Sigillen-Kachel · `audit yours → failproof.ai`-Fußzeile. Drei Teilen-Schaltflächen befinden sich knapp außerhalb des Erfassungsbereichs: `post your archetype` (X Intent), `share on linkedin`, `download poster`. Die Erfassung erfolgt über `html-to-image`, sodass das PNG pixelgenau mit der Bildschirmdarstellung übereinstimmt (gestrichelte Rahmen, SVG-Logo-Maske, Farbverläufe, Schriftmetriken — alles erhalten). -2. **Stärken** — ruhige ✓-Zeilenliste von Verhaltensweisen, die Ihr Agent bereits richtig macht, abgeleitet aus den Live-Audit-Daten (saubere Tool-Aufruf-Rate, keine direkten Pushes zu main, null Credential-Lecks, null Wiederholungsstürme) — jeweils nur angezeigt, wenn die entsprechende Richtlinie im Audit-Zeitraum eine saubere Bilanz hat. -3. **Eigenheiten** — Tabelle der Dinge, die durchgerutscht sind, nach Schweregrad sortiert: `Zeitpunkt · Was durchgerutscht ist + die Richtlinie, die es hätte abfangen sollen · Schweregradpille · gesehen`, wobei das Vorkommen `new` (einmal), `N× seen` (2–9 Mal) oder `recurring` (10+) lautet. -4. **So verbessern Sie sich** — ruhige Zeilenliste, eine pro empfohlener Richtlinie: Richtlinienname in Weiß, einzeilige Beschreibung, Installationsbefehl + Kopierschaltfläche auf der rechten Seite. Die Abschnittsüberschrift lautet `enable all N → projected · ` (die Punktzahl, die Sie mit allen angewendeten Korrekturen erreichen würden), und die Schaltfläche `[install all]` kopiert den kombinierten `failproofai policy add a b c …`-Befehl für jede empfohlene Richtlinie. -5. **Komm besser zurück** — zwei nebeneinander liegende Karten. Links: Erinnerung setzen (`3d` / `7d` / `14d` / `30d` Kadenz-Auswahl; wird nach Authentifizierung über `/api/auth/reminder` gespeichert). Rechts: failproof-Vorteile freischalten — `invite a friend` öffnet ein Modal, das eine komma-/leerzeichen-/zeilenumbruchgetrennte Liste von Freundes-E-Mails akzeptiert (max. 10 pro Sendung), POSTet diese an `/api/audit/invite`, das sie an den API-Server unter `POST /v0/invite` weiterleitet. Der API-Server sendet eine E-Mail pro Empfänger von `invite@failproof.ai` mit dem Absender im Cc und gesetztem `Reply-To`, sodass der Empfänger sieht, wer ihn eingeladen hat, und der Absender eine Kopie in seinem Posteingang erhält. Anonyme Benutzer werden zuerst durch den `AuthDialog` geleitet, damit die E-Mail des Absenders bekannt ist, bevor Einladungen verschickt werden. Ansprüche/Vorteilserfüllung folgt. +1. **Poster** — füllt den ersten Anzeigebereich. Eigenständiger PNG-Erfassungsbereich mit failproof_ai-Wortmarke + Audit-Label · Archetyp-Index (`№ NN von 08`) + Audit-Datum · numerischer Score (0–100) + Perzentil-Rang-Pille (`top 15%`) · der Archetyp-Name (einer von `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + 3-Schlagwort-Streifen · `// only N% of agents are this archetype`-Seltenheitszeile · 8×8-Pixel-Sigillen-Kachel · `audit yours → failproof.ai`-Fußzeile. Drei Teilen-Schaltflächen befinden sich knapp außerhalb des Erfassungsbereichs: `post your archetype` (X intent), `share on linkedin`, `download poster`. Die Erfassung erfolgt über `html-to-image`, sodass das PNG pixelgenau dem Bildschirm-Rendering entspricht (gestrichelte Rahmen, SVG-Logo-Maske, Verläufe, Schriftmetriken — alles erhalten). +2. **Stärken** — ruhige ✓-Zeilenliste von Verhaltensweisen, die Ihr Agent bereits richtig macht, abgeleitet aus den Live-Audit-Daten (saubere Tool-Aufruf-Rate, keine direkten Pushes zu main, null Anmeldedatenlecks, null Wiederholungsstürme) — jede nur angezeigt, wenn die relevante Richtlinie über das Audit-Fenster hinweg eine saubere Bilanz hat. +3. **Eigenheiten** — Tabelle der Fehler, nach Schweregrad sortiert: `wann · was durchgerutscht ist + die Richtlinie, die es erkannt hätte · Schweregrad-Pille · gesehen`, wobei die Wiederholungsrate `new` (einmal), `N× seen` (2–9 Mal) oder `recurring` (10+) anzeigt. +4. **Wie Sie sich verbessern können** — ruhige Zeilenliste, eine pro empfohlener Richtlinie: Richtlinienname in Weiß, einzeilige Beschreibung, Installationsbefehl + Kopier-Schaltfläche auf der rechten Seite. Die Abschnittsüberschrift lautet `enable all N → projected · ` (der Score, den Sie mit allen angewendeten Korrekturen erreichen würden), und die Schaltfläche `[install all]` kopiert den kombinierten `failproofai policy add a b c …`-Befehl für jede empfohlene Richtlinie. +5. **Kommen Sie besser zurück** — zwei nebeneinander angeordnete Karten. Links: Erinnerung setzen (`3d` / `7d` / `14d` / `30d`-Taktgeber; wird nach Authentifizierung über `/api/auth/reminder` gespeichert). Rechts: failproof-Vergünstigungen freischalten — `invite a friend` öffnet ein Modal, das eine durch Komma/Leerzeichen/Zeilenumbruch getrennte Liste von Freundes-E-Mail-Adressen entgegennimmt (max. 10 pro Sendung), diese per POST an `/api/audit/invite` sendet, das sie an den `POST /v0/invite`-Endpunkt des API-Servers weiterleitet. Der API-Server sendet pro Empfänger eine E-Mail von `invite@failproof.ai` mit dem Absender in CC und gesetztem `Reply-To`, sodass der Empfänger sieht, wer ihn eingeladen hat, und der Absender eine Kopie in seinem Posteingang erhält. Anonyme Benutzer werden zuerst durch den `AuthDialog` geleitet, damit die E-Mail-Adresse des Absenders bekannt ist, bevor Einladungen versandt werden. Berechtigungen und Vergünstigungen folgen in einem nächsten Schritt. -Angetrieben von der `failproofai audit`-Laufzeit — siehe [Audit CLI](/de/cli/audit) für die zugrunde liegende Scan-Engine, unterstützte Flags und sitzungsspezifische Cache-Invarianten. Das Dashboard speichert das neueste Ergebnis unter `~/.failproofai/audit-dashboard.json` (Modus `0600`, einzelner Slot, neue Läufe überschreiben), sodass erneute Besuche sofort laden; **sowohl der transkriptspezifische als auch der gesamtergebnisbezogene Cache werden beim Lesen abgelehnt, sobald sie älter als 7 Tage sind**, damit das Dashboard kein einwöchiges Ergebnis stillschweigend ausliefert — nach Ablauf der TTL fällt `/audit` in seinen Leerzustand und fordert einen neuen Lauf an. Ein Klick auf `[ re-audit now ]` nahe am Ende des Berichts sendet einen POST an `/api/audit/run` mit `noCache: true` — ein Re-Audit umgeht den transkriptspezifischen Cache und scannt jedes Transkript von Grund auf neu, anstatt stillschweigend das zwischengespeicherte Ergebnis zurückzugeben — und das Dashboard fragt `/api/audit/status` mit 1 Hz ab, bis der Lauf abgeschlossen ist; ein pinker Fortschrittsbalken wird während des Laufs mit einem Zeitmesser oben im Viewport fixiert, und das frische Ergebnis wird bei Erfolg an Ort und Stelle ausgetauscht (kein vollständiges Neuladen der Seite; ein fehlgeschlagener Re-Audit lässt den vorherigen Bericht intakt). Bei einem Fehler wird der Balken rot mit einer auf den `RerunError.kind` abgestimmten Meldung (`timeout` / `network` / `post_failed`). Leerzustand (kein Cache oder abgelaufen) und Null-Sitzungen-Zustand (Cache vorhanden, aber der Scan hat keine Transkripte gefunden) werden separat angezeigt. +Angetrieben von der `failproofai audit`-Laufzeitumgebung — siehe [Audit-CLI](/de/cli/audit) für die zugrunde liegende Scan-Engine, unterstützte Flags und Cache-Invarianten pro Transkript. Das Dashboard speichert das aktuellste Ergebnis unter `~/.failproofai/audit-dashboard.json` (Modus `0600`, einzelner Slot, neue Durchläufe überschreiben), sodass erneute Besuche sofort laden; **sowohl der Cache pro Transkript als auch der Gesamtergebnis-Cache werden beim Lesen abgelehnt, sobald sie älter als 7 Tage sind**, damit das Dashboard nie stillschweigend ein einwöchiges Ergebnis ausliefert — nach Ablauf der TTL fällt `/audit` in seinen leeren Zustand und fordert einen neuen Durchlauf auf. Ein Klick auf `[ re-audit now ]` am unteren Rand des Berichts sendet einen POST an `/api/audit/run` mit `noCache: true` — ein erneuter Audit umgeht den Cache pro Transkript und scannt jedes Transkript von Grund auf neu, anstatt stillschweigend das gecachte Ergebnis zurückzugeben — und das Dashboard fragt `/api/audit/status` mit 1 Hz ab, bis der Durchlauf abgeschlossen ist; ein auffälliger rosa Fortschrittsstreifen wird während des Durchlaufs mit einem Laufzeitzähler oben im Anzeigebereich angeheftet, und das neue Ergebnis wird bei Erfolg an Ort und Stelle eingetauscht (kein vollständiges Neuladen der Seite; ein fehlgeschlagener erneuter Audit lässt den vorherigen Bericht unberührt). Bei einem Fehler wird der Streifen rot mit einem Text, der auf den `RerunError.kind` abgestimmt ist (`timeout` / `network` / `post_failed`). Leerer Zustand (kein Cache oder abgelaufen) und Zustand ohne Sitzungen (Cache vorhanden, aber der Scan fand keine Transkripte) werden separat angezeigt. ### Richtlinien -Eine zweiseitige Seite zur Verwaltung von Richtlinien und zur Überprüfung von Aktivitäten. +Eine zweistufige Seite zur Verwaltung von Richtlinien und zur Überprüfung von Aktivitäten. - - Wählen Sie per Mehrfachauswahl aus, welche Agent-CLIs failproofai schützt — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi und Hermes haben jeweils eine Zeile mit Installationsstatus (`Active` / `Detected` / `Inactive`), dem benutzerspezifischen Einstellungspfad und einem markenspezifischen Akzent. Aktivieren oder deaktivieren Sie die gewünschten CLIs und klicken Sie auf `Apply changes`, um die Änderungen in einem Schritt zu installieren/deinstallieren. CLIs, deren Binary im PATH erkannt wird, sind vorausgewählt. - - Schalten Sie einzelne Richtlinien mit einem Klick ein oder aus (schreibt in `~/.failproofai/policies-config.json` — gemeinsam von allen installierten CLIs genutzt) - - Erweitern Sie eine Richtlinie, um ihre Parameter zu konfigurieren (für Richtlinien, die `policyParams` unterstützen) - - Legen Sie einen benutzerdefinierten Pfad für die Richtliniendatei fest + - Wählen Sie in einem einzigen Panel aus, welche Agenten-CLIs failproofai schützen soll — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi und Hermes haben jeweils eine Zeile mit Installationsstatus (`Active` / `Detected` / `Inactive`), dem benutzerbezogenen Einstellungspfad und einem markenspezifischen Akzent. Aktivieren oder deaktivieren Sie die gewünschten CLIs und klicken Sie auf `Apply changes`, um die Änderungen in einem Schritt zu installieren/deinstallieren. CLIs, deren Binärdatei im PATH erkannt wird, sind vorab aktiviert. + - Einzelne Richtlinien per Klick aktivieren oder deaktivieren (schreibt in `~/.failproofai/policies-config.json` — wird von allen installierten CLIs geteilt) + - Eine Richtlinie erweitern, um ihre Parameter zu konfigurieren (für Richtlinien, die `policyParams` unterstützen) + - Einen benutzerdefinierten Richtliniendateipfad festlegen - - Vollständiger paginierter Verlauf aller Hook-Ereignisse, die in allen Sitzungen ausgelöst wurden + - Vollständige, seitenweise aufgelistete Historie aller Hook-Ereignisse, die über alle Sitzungen hinweg ausgelöst wurden - Filtern nach Entscheidung, Ereignistyp, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(Beta)_ / Cursor Agent _(Beta)_ / OpenCode _(Beta)_ / Pi _(Beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), Richtlinienname oder Sitzungs-ID - - Jede Zeile zeigt: Zeitstempel, Richtlinienname, Entscheidung, CLI-Badge (orange = Claude Code, lila = OpenAI Codex, blau = GitHub Copilot, smaragd = Cursor Agent, bernstein = OpenCode, pink = Pi, indigo = Hermes, blaugrün = OpenClaw, rose = Factory Droid, violett = Devin, cyan = Antigravity, limette = Goose), Tool-Name, Sitzungs-ID und den Grund für deny/instruct-Entscheidungen - - Klicken Sie auf eine Sitzungs-ID, um ihr Transkript zu öffnen — der Betrachter erkennt automatisch, welche CLI den Hook ausgelöst hat (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) und zeigt das passende CLI-Badge im Header an + - Jede Zeile zeigt: Zeitstempel, Richtlinienname, Entscheidung, CLI-Badge (orange = Claude Code, lila = OpenAI Codex, blau = GitHub Copilot, smaragdgrün = Cursor Agent, bernstein = OpenCode, rosa = Pi, indigo = Hermes, blaugrün = OpenClaw, rose = Factory Droid, violett = Devin, cyan = Antigravity, limette = Goose), Tool-Name, Sitzungs-ID und den Grund für deny/instruct-Entscheidungen + - Klicken Sie auf eine Sitzungs-ID, um das zugehörige Transkript zu öffnen — der Viewer erkennt automatisch, welche CLI den Hook ausgelöst hat (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) und zeigt das passende CLI-Badge in der Kopfzeile an @@ -94,7 +94,7 @@ Eine zweiseitige Seite zur Verwaltung von Richtlinien und zur Überprüfung von ## Automatische Aktualisierung -Das Dashboard verfügt über einen Umschalter für die automatische Aktualisierung in der oberen Navigation. Wenn aktiviert, wird die aktuelle Seite regelmäßig aktualisiert, um neue Sitzungen und Richtlinienaktivitäten anzuzeigen, sobald sie auftreten. Unverzichtbar für die Überwachung lang laufender autonomer Agent-Sitzungen. +Das Dashboard verfügt über einen Schalter für die automatische Aktualisierung in der oberen Navigation. Wenn aktiviert, wird die aktuelle Seite regelmäßig aktualisiert, um neue Sitzungen und Richtlinienaktivitäten anzuzeigen, sobald sie erscheinen. Unverzichtbar für die Überwachung langläufiger autonomer Agenten-Sitzungen. --- @@ -112,7 +112,7 @@ Gültige Werte: `policies`, `projects`, `audit`. ## Projektpfad konfigurieren -Standardmäßig liest das Dashboard aus dem Standardverzeichnis für Claude Code-Projekte. Überschreiben Sie es für benutzerdefinierte Setups: +Standardmäßig liest das Dashboard aus dem Standard-Claude Code-Projektverzeichnis. Überschreiben Sie dies für benutzerdefinierte Setups: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -122,13 +122,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Zugriff von einem Nicht-localhost-Host -Wenn Sie das Dashboard im **Entwicklungsmodus** (`npm run dev`) ausführen und von einem anderen Hostnamen als `localhost` darauf zugreifen — zum Beispiel einer benutzerdefinierten Domain, einer Remote-IP oder einer getunnelten URL — erscheint möglicherweise eine Warnung wie: +Wenn Sie das Dashboard im **Entwicklungsmodus** (`npm run dev`) ausführen und von einem anderen Hostnamen als `localhost` darauf zugreifen — zum Beispiel einer benutzerdefinierten Domain, einer Remote-IP oder einer getunnelten URL — sehen Sie möglicherweise eine Warnung wie: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Dies ist Next.js, das den ursprungsübergreifenden Zugriff auf seinen HMR-WebSocket (Hot Module Reload) blockiert, welcher eine ausschließlich entwicklungsspezifische Funktion ist. Um Ihren Host zuzulassen, verwenden Sie das Flag `--allowed-origins`: +Hierbei blockiert Next.js den ursprungsübergreifenden Zugriff auf seinen HMR-Websocket (Hot Module Reload), der eine ausschließlich entwicklungsbezogene Funktion ist. Um Ihren Host zuzulassen, verwenden Sie das `--allowed-origins`-Flag: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -147,5 +147,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Dies gilt nur für den Entwicklungsmodus. Beim Ausführen von `failproofai` (Produktionsmodus) gibt es keinen HMR-WebSocket und kein ursprungsübergreifendes Entwicklungsressourcenproblem. +Dies gilt nur für den Entwicklungsmodus. Beim Ausführen von `failproofai` (Produktionsmodus) gibt es keinen HMR-Websocket und kein ursprungsübergreifendes Entwicklungsressourcenproblem. \ No newline at end of file diff --git a/docs/de/examples.mdx b/docs/de/examples.mdx index 9b02a644..11cdb0d9 100644 --- a/docs/de/examples.mdx +++ b/docs/de/examples.mdx @@ -4,13 +4,13 @@ description: "So richtest du Hooks für Claude Code und das Agents SDK ein" icon: book-open --- -Sofort einsatzbereite Beispiele für häufige Anwendungsfälle. Jedes zeigt, wie man es installiert und was zu erwarten ist. +Sofort einsatzbereite Beispiele für häufige Szenarien. Jedes zeigt, wie die Installation aussieht und was du erwarten kannst. --- ## Hooks für Claude Code einrichten -Failproof AI integriert sich mit Claude Code über dessen [Hooks-System](https://docs.anthropic.com/en/docs/claude-code/hooks). Wenn du `failproofai policies --install` ausführst, werden Hook-Befehle in der `settings.json` von Claude Code registriert, die bei jedem Tool-Aufruf ausgelöst werden. +Failproof AI integriert sich mit Claude Code über sein [Hooks-System](https://docs.anthropic.com/en/docs/claude-code/hooks). Wenn du `failproofai policies --install` ausführst, werden Hook-Befehle in der `settings.json` von Claude Code registriert, die bei jedem Tool-Aufruf ausgelöst werden. @@ -18,7 +18,7 @@ Failproof AI integriert sich mit Claude Code über dessen [Hooks-System](https:/ npm install -g failproofai ``` - + ```bash failproofai policies --install ``` @@ -28,14 +28,14 @@ Failproof AI integriert sich mit Claude Code über dessen [Hooks-System](https:/ cat ~/.claude/settings.json | grep failproofai ``` - Es sollten Hook-Einträge für `PreToolUse`-, `PostToolUse`-, `Notification`- und `Stop`-Ereignisse erscheinen. + Du solltest Hook-Einträge für `PreToolUse`, `PostToolUse`, `Notification` und `Stop`-Ereignisse sehen. ```bash claude ``` - Richtlinien laufen jetzt automatisch bei jedem Tool-Aufruf. Versuche, Claude zur Ausführung von `sudo rm -rf /` aufzufordern – der Befehl wird blockiert. + Policies werden jetzt bei jedem Tool-Aufruf automatisch ausgeführt. Bitte Claude, `sudo rm -rf /` auszuführen – der Befehl wird blockiert. @@ -43,23 +43,23 @@ Failproof AI integriert sich mit Claude Code über dessen [Hooks-System](https:/ ## Hooks für das Agents SDK einrichten -Wenn du mit dem [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) entwickelst, kannst du dasselbe Hook-System programmatisch verwenden. +Wenn du mit dem [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) entwickelst, kannst du dasselbe Hook-System programmatisch nutzen. - + ```bash npm install failproofai ``` - - Übergib Hook-Befehle beim Erstellen deines Agentenprozesses. Die Hooks werden genau wie in Claude Code ausgelöst – über stdin/stdout JSON: + + Übergib Hook-Befehle beim Erstellen deines Agenten-Prozesses. Die Hooks werden genauso wie in Claude Code ausgelöst – über stdin/stdout JSON: ```bash failproofai --hook PreToolUse # wird vor jedem Tool aufgerufen failproofai --hook PostToolUse # wird nach jedem Tool aufgerufen ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -77,7 +77,7 @@ Wenn du mit dem [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) entw }); ``` - + ```bash failproofai policies --install --custom ./my-agent-policies.js ``` @@ -88,7 +88,7 @@ Wenn du mit dem [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) entw ## Destruktive Befehle blockieren -Das häufigste Setup – verhindert, dass Agenten irreversiblen Schaden anrichten. +Das häufigste Setup – verhindert, dass Agenten irreversible Schäden anrichten. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -96,13 +96,13 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur Was das bewirkt: - `block-sudo` – blockiert alle `sudo`-Befehle -- `block-rm-rf` – blockiert das rekursive Löschen von Dateien +- `block-rm-rf` – blockiert rekursives Löschen von Dateien - `block-force-push` – blockiert `git push --force` -- `block-curl-pipe-sh` – blockiert das Weiterleiten von Remote-Skripten an die Shell +- `block-curl-pipe-sh` – blockiert das Pipen von Remote-Skripten in die Shell --- -## Geheimnisse vor Weitergabe schützen +## Geheimnis-Lecks verhindern Verhindert, dass Agenten Zugangsdaten in der Tool-Ausgabe sehen oder weitergeben. @@ -110,13 +110,13 @@ Verhindert, dass Agenten Zugangsdaten in der Tool-Ausgabe sehen oder weitergeben failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Diese Richtlinien werden bei `PostToolUse` ausgelöst – nachdem ein Tool ausgeführt wurde, bereinigen sie die Ausgabe, bevor der Agent sie sieht. +Diese werden bei `PostToolUse` ausgelöst – nachdem ein Tool ausgeführt wurde, bereinigen sie die Ausgabe, bevor der Agent sie sieht. --- ## Slack-Benachrichtigungen erhalten, wenn Agenten Aufmerksamkeit brauchen -Verwende den Notification-Hook, um Leerlauf-Benachrichtigungen an Slack weiterzuleiten. +Verwende den Notification-Hook, um Idle-Benachrichtigungen an Slack weiterzuleiten. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -142,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // den Agenten niemals blockieren, wenn Slack nicht erreichbar ist + // Agenten niemals blockieren, wenn Slack nicht erreichbar ist } return allow(); @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -Installieren: +Installation: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -160,7 +160,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## Agenten auf einem Branch halten -Verhindert, dass Agenten Branches wechseln oder in geschützte Branches pushen. +Verhindert, dass Agenten Branches wechseln oder auf geschützte Branches pushen. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +184,7 @@ customPolicies.add({ ## Tests vor Commits vorschreiben -Erinnere Agenten daran, Tests vor dem Committen auszuführen. +Erinnert Agenten daran, vor dem Committen Tests auszuführen. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -208,7 +208,7 @@ customPolicies.add({ ## Ein Produktions-Repository absichern -Lege eine projektweite Konfiguration fest, damit alle Entwickler in deinem Team dieselben Richtlinien erhalten. +Committe eine projektweite Konfiguration, damit alle Entwickler in deinem Team dieselben Policies erhalten. Erstelle `.failproofai/policies-config.json` in deinem Repository: @@ -231,23 +231,23 @@ Erstelle `.failproofai/policies-config.json` in deinem Repository: } ``` -Dann einchecken: +Dann committen: ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -Alle Teammitglieder, die failproofai installiert haben, übernehmen diese Regeln automatisch. +Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Regeln automatisch. --- -## Organisationsweite Qualitätsstandards mit Convention-Richtlinien etablieren +## Einen organisationsweiten Qualitätsstandard mit Convention-Policies aufbauen -Das wirkungsvollste Setup: Lege `.failproofai/policies/` mit auf dein Projekt zugeschnittenen Richtlinien in dein Repository. Alle Teammitglieder erhalten sie automatisch – ohne Installationsbefehle, ohne Konfigurationsänderungen. +Das wirkungsvollste Setup: Committe `.failproofai/policies/` in dein Repository mit Policies, die auf dein Projekt zugeschnitten sind. Jedes Teammitglied erhält sie automatisch – keine Installationsbefehle, keine Konfigurationsänderungen. - + ```bash mkdir -p .failproofai/policies ``` @@ -256,8 +256,8 @@ Das wirkungsvollste Setup: Lege `.failproofai/policies/` mit auf dein Projekt zu // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Enforce your team's preferred package manager - // (or enable the built-in prefer-package-manager policy instead) + // Bevorzugten Paketmanager deines Teams durchsetzen + // (oder stattdessen die integrierte prefer-package-manager Policy aktivieren) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, @@ -269,7 +269,7 @@ Das wirkungsvollste Setup: Lege `.failproofai/policies/` mit auf dein Projekt zu }, }); - // Remind the agent to run tests before committing + // Agenten daran erinnern, vor dem Committen Tests auszuführen customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, @@ -283,14 +283,14 @@ Das wirkungsvollste Setup: Lege `.failproofai/policies/` mit auf dein Projekt zu }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Wenn das Team auf neue Fehlerquellen stößt, füge Richtlinien hinzu und pushe sie. Alle erhalten das Update beim nächsten `git pull`. Diese Richtlinien werden zu einem lebendigen Qualitätsstandard, der mit deinem Team wächst. + Wenn dein Team auf neue Fehlerszenarien stößt, füge Policies hinzu und pushe sie. Alle erhalten das Update beim nächsten `git pull`. Diese Policies werden zu einem lebendigen Qualitätsstandard, der mit deinem Team wächst. @@ -302,6 +302,6 @@ Das Verzeichnis [`examples/`](https://github.com/failproofai/failproofai/tree/ma | Datei | Inhalt | |------|---------------| -| `policies-basic.js` | Einstiegsrichtlinien – Schreibzugriffe auf Produktion, Force-Push und weitergeleitete Skripte blockieren | -| `policies-notification.js` | Slack-Benachrichtigungen bei Leerlauf-Meldungen und Sitzungsende | -| `policies-advanced/index.js` | Transitive Imports, asynchrone Hooks, PostToolUse-Ausgabebereinigung, Stop-Ereignisbehandlung | \ No newline at end of file +| `policies-basic.js` | Grundlegende Policies – Produktions-Schreibzugriffe blockieren, Force-Push, gepipte Skripte | +| `policies-notification.js` | Slack-Benachrichtigungen bei Idle-Notifications und Sitzungsende | +| `policies-advanced/index.js` | Transitive Imports, asynchrone Hooks, PostToolUse-Ausgabe-Bereinigung, Stop-Event-Behandlung | \ No newline at end of file diff --git a/docs/de/for-agents.mdx b/docs/de/for-agents.mdx index 61d51cde..3c50140f 100644 --- a/docs/de/for-agents.mdx +++ b/docs/de/for-agents.mdx @@ -1,31 +1,31 @@ --- -title: "Für Agenten" -description: "Failproof AI-Wissen in einem Befehl zu deinem Coding-Agenten hinzufügen. Funktioniert mit Claude Code, Cursor, Windsurf und mehr." +title: "Für Agents" +description: "Füge Failproof AI-Wissen in einem Befehl zu deinem Coding-Agent hinzu. Funktioniert mit Claude Code, Cursor, Windsurf und mehr." --- -Füge die vollständige Failproof AI-Referenz in einem Befehl zu deinem Coding-Agenten hinzu. Funktioniert mit Claude Code, Cursor, Windsurf und jedem anderen Agenten, der Skills unterstützt. +Füge die vollständige Failproof AI-Referenz in einem Befehl zu deinem Coding-Agent hinzu. Funktioniert mit Claude Code, Cursor, Windsurf und jedem anderen Agent, der Skills unterstützt. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` erkennt automatisch, welche Agenten du installiert hast, und fügt den Skill im jeweils passenden Format hinzu. +`npx skills` erkennt automatisch, welche Agents du installiert hast, und fügt den Skill im jeweils passenden Format hinzu. ## Was der Skill abdeckt -| Bereich | Inhalt | -|---------|--------| +| Bereich | Inhalte | +|---------|---------| | Policies | Integrierte Policy-Namen, Event-Typen, Parameter, aktivieren/deaktivieren | | Custom policies | `customPolicies.add()`, Match-Filter, `allow`/`deny`/`instruct`-API | | Context-Objekt | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Konfiguration | `policies-config.json`-Struktur, Scope-Zusammenführung, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, Scopes | | Dashboard | Session-Viewer, Policy-Aktivität, Umgebungsvariablen | -| Architektur | Hook-Handler-Flow, Exit-Codes, stdin/stdout-Vertrag | +| Architektur | Hook-Handler-Ablauf, Exit-Codes, stdin/stdout-Vertrag | ## Ist der Skill vollständig? -Mintlify generiert `llms.txt` aus allen Seiten der Navigation. Die Failproof AI-Dokumentation deckt die vollständige API ab – jede Policy, Option und jedes Beispiel ist enthalten. Falls dir etwas fehlt, findest du die Quelle unter `https://docs.befailproof.ai/llms-full.txt`. +Mintlify generiert `llms.txt` aus allen Seiten der Navigation. Die Failproof AI-Dokumentation deckt die vollständige API ab – jede Policy, jede Option und jedes Beispiel ist enthalten. Falls du etwas vermisst, findest du die Quelle unter `https://docs.befailproof.ai/llms-full.txt`. Für gezielten Kontext kannst du direkt auf eine bestimmte Seite verlinken: diff --git a/docs/de/getting-started.mdx b/docs/de/getting-started.mdx index 24f8993e..f26a5881 100644 --- a/docs/de/getting-started.mdx +++ b/docs/de/getting-started.mdx @@ -1,6 +1,6 @@ --- title: Erste Schritte -description: "Installiere failproofai, aktiviere Richtlinien und lass deine Agenten zuverlässig laufen" +description: "failproofai installieren, Richtlinien aktivieren und Agenten zuverlässig betreiben" icon: rocket --- @@ -31,15 +31,15 @@ bun add -g failproofai - Richtlinien sind Regeln, die vor und nach jedem Tool-Aufruf eines Agenten ausgeführt werden. Sie erkennen destruktive Befehle, das Durchsickern von Geheimnissen und andere Fehlerquellen, bevor sie Schaden anrichten. + Richtlinien sind Regeln, die vor und nach jedem Tool-Aufruf eines Agenten ausgeführt werden. Sie erkennen destruktive Befehle, den Abfluss von Geheimnissen und andere Fehlerszenarien, bevor Schaden entsteht. ```bash failproofai policies --install ``` - Dies schreibt Hook-Einträge in die installierten Agenten-CLIs (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 generiertes Plugin-Shim unter `~/.config/opencode/plugins/failproofai.mjs` plus einen Registrierungseintrag im `plugin`-Array von `~/.config/opencode/opencode.json`, 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` oder Goose's automatisch erkanntes Plugin-Verzeichnis unter `~/.agents/plugins/failproofai/hooks/hooks.json`). Wenn mehr als eine CLI vorhanden ist, wird eine Abfrage angezeigt; übergib `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (beliebige Teilmenge), um die Abfrage zu überspringen. + Dabei werden Hook-Einträge in die installierten Agent-CLIs geschrieben (Claude Codes `~/.claude/settings.json`, OpenAI Codex' `~/.codex/hooks.json`, GitHub Copilot CLIs `~/.copilot/hooks/failproofai.json`, Cursor Agents `~/.cursor/hooks.json`, OpenCodes generierter Plugin-Shim unter `~/.config/opencode/plugins/failproofai.mjs` sowie ein Registrierungseintrag im `plugin`-Array von `~/.config/opencode/opencode.json`, Pis `~/.pi/agent/settings.json`, Hermes' `~/.hermes/config.yaml`, OpenClaws `~/.openclaw/openclaw.json`, Factory Droids `~/.factory/hooks.json`, Devin CLIs `~/.config/devin/config.json`, Antigravity CLIs `~/.gemini/config/hooks.json` oder Gooses automatisch erkanntem Plugin-Verzeichnis unter `~/.agents/plugins/failproofai/hooks/hooks.json`). Sind mehrere vorhanden, wird eine Auswahl angezeigt; mit `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (beliebige Teilmenge) kann die Abfrage übersprungen werden. - GitHub Copilot CLI, Cursor Agent, OpenCode und Pi-Unterstützung sind **Beta** – installiere mit `--cli copilot`, `--cli cursor`, `--cli opencode` oder `--cli pi`. Hermes (hermes-agent, ein Slack/Telegram-Gateway) wird im User-Scope mit `--cli hermes` installiert und ist **außerdem** eine Offline-Audit-Quelle. OpenClaw (openclaw-Gateway, ein selbst gehosteter Multi-Channel-Assistent) wird im User-Scope mit `--cli openclaw` installiert – die Durchsetzung erfolgt über seine In-Process-Plugin-Hooks (`before_agent_finalize` ist ein echter Turn-End-Gate, sodass die eingebauten `require-*-before-stop`-Richtlinien greifen) – und ist **außerdem** eine Offline-Audit-Quelle. Factory Droid (`droid`) wird mit `--cli factory` (User- und Projekt-Scope) installiert und ist **außerdem** eine Offline-Audit-Quelle. Devin CLI (`devin`, Cognition) wird mit `--cli devin` (User- und Projekt-Scope) installiert und ist **außerdem** eine Offline-Audit-Quelle. Antigravity CLI (`agy`) wird mit `--cli antigravity` (User- und Projekt-Scope) installiert und ist **außerdem** eine Offline-Audit-Quelle. Goose (Codename goose, Block) wird mit `--cli goose` (User- und Projekt-Scope) installiert – der Installer legt ein Plugin-Verzeichnis unter `~/.agents/plugins/failproofai/` an, das Goose automatisch erkennt, und ist **außerdem** eine Offline-Audit-Quelle. + GitHub Copilot CLI, Cursor Agent, OpenCode und Pi sind **Beta** – Installation mit `--cli copilot`, `--cli cursor`, `--cli opencode` oder `--cli pi`. Hermes (hermes-agent, ein Slack/Telegram-Gateway) wird im Benutzerbereich mit `--cli hermes` installiert und ist **außerdem** eine Offline-Audit-Quelle. OpenClaw (openclaw gateway, ein selbst gehosteter Multi-Channel-Assistent) wird im Benutzerbereich mit `--cli openclaw` installiert – die Durchsetzung erfolgt über seine In-Process-Plugin-Hooks (`before_agent_finalize` ist ein echtes Turn-End-Gate, sodass die eingebauten `require-*-before-stop`-Regeln greifen) – und ist **außerdem** eine Offline-Audit-Quelle. Factory Droid (`droid`) wird mit `--cli factory` (Benutzer- und Projektbereich) installiert und ist **außerdem** eine Offline-Audit-Quelle. Devin CLI (`devin`, Cognition) wird mit `--cli devin` (Benutzer- und Projektbereich) installiert und ist **außerdem** eine Offline-Audit-Quelle. Antigravity CLI (`agy`) wird mit `--cli antigravity` (Benutzer- und Projektbereich) installiert und ist **außerdem** eine Offline-Audit-Quelle. Goose (Codename goose, Block) wird mit `--cli goose` (Benutzer- und Projektbereich) installiert – das Installationsprogramm legt lediglich ein Plugin-Verzeichnis unter `~/.agents/plugins/failproofai/` an, das Goose automatisch erkennt – und ist **außerdem** eine Offline-Audit-Quelle. ```bash failproofai policies --install --scope project @@ -62,17 +62,17 @@ bun add -g failproofai failproofai policies ``` - Zeigt jede Richtlinie an, ob sie aktiviert ist und welche Parameter konfiguriert sind. + Zeigt alle Richtlinien an – ob sie aktiv sind und welche Parameter konfiguriert wurden. ```bash failproofai ``` - Öffnet ein lokales Dashboard unter `http://localhost:8020`, in dem du Sitzungen durchsuchen, Tool-Aufrufe untersuchen und Richtlinien verwalten kannst. + Öffnet ein lokales Dashboard unter `http://localhost:8020`, in dem Sitzungen durchsucht, Tool-Aufrufe inspiziert und Richtlinien verwaltet werden können. - Starte Claude Code wie gewohnt. Wenn der Agent etwas Riskantes versucht, greift failproofai automatisch ein. Lass ihn unbeaufsichtigt laufen und überprüfe im Dashboard, was passiert ist. + Starte Claude Code wie gewohnt. Versucht der Agent etwas Riskantes, greift failproofai automatisch ein. Lass ihn unbeaufsichtigt laufen und überprüfe anschließend im Dashboard, was passiert ist. @@ -80,7 +80,7 @@ bun add -g failproofai ## Wie Richtlinien funktionieren -Jedes Mal, wenn ein Agent ein Tool ausführt, ruft Claude Code failproofai als Unterprozess auf: +Jedes Mal, wenn ein Agent ein Tool ausführt, ruft Claude Code failproofai als Subprocess auf: ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -91,18 +91,18 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON Jede Richtlinie gibt eine von drei Entscheidungen zurück: - **allow** – der Agent fährt normal fort -- **deny** – die Aktion wird blockiert und der Agent wird über den Grund informiert +- **deny** – die Aktion wird blockiert, der Agent erfährt den Grund - **instruct** – dem Prompt des Agenten wird zusätzlicher Kontext hinzugefügt -Richtlinien werden in deinem lokalen Prozess ausgeführt. Es werden keine Daten an einen Remote-Dienst gesendet. +Richtlinien werden im lokalen Prozess ausgeführt. Es werden keine Daten an einen externen Dienst gesendet. --- ## Team-Richtlinien mit konventionsbasierten Richtlinien einrichten -Der schnellste Weg, Qualitätsstandards im gesamten Team zu etablieren, ist die `.failproofai/policies/`-Konvention. Lege Richtliniendateien in dieses Verzeichnis und sie werden automatisch geladen – keine Flags, keine Konfigurationsänderungen, keine Install-Befehle. +Der schnellste Weg, Qualitätsstandards im Team durchzusetzen, ist die `.failproofai/policies/`-Konvention. Lege Richtliniendateien in dieses Verzeichnis und sie werden automatisch geladen – ohne Flags, Konfigurationsänderungen oder Installationsbefehle. @@ -111,13 +111,13 @@ Der schnellste Weg, Qualitätsstandards im gesamten Team zu etablieren, ist die ``` - Kopiere die Startbeispiele oder schreibe eigene: + Kopiere die mitgelieferten Beispiele oder schreibe eigene: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - Oder erstelle eine neue: + Oder erstelle eine neue Datei: ```js // .failproofai/policies/team-policies.mjs @@ -142,12 +142,12 @@ Der schnellste Weg, Qualitätsstandards im gesamten Team zu etablieren, ist die git commit -m "Add team quality policies" ``` - Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Richtlinien automatisch. Kein Setup pro Entwickler erforderlich. + Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Richtlinien automatisch. Kein individuelles Setup erforderlich. -Checke `.failproofai/policies/` in dein Repository ein, damit das gesamte Team dieselben Standards teilt. Wenn dein Team neue Fehlerquellen entdeckt, füge Richtlinien hinzu und pushe – alle erhalten das Update beim nächsten `git pull`. Mit der Zeit werden diese Richtlinien zu einem lebendigen Qualitätsstandard, der sich kontinuierlich verbessert. +Checke `.failproofai/policies/` in dein Repository ein, damit das gesamte Team dieselben Standards teilt. Wenn das Team neue Fehlerszenarien entdeckt, füge Richtlinien hinzu und pushe – alle erhalten die Aktualisierung beim nächsten `git pull`. Mit der Zeit werden diese Richtlinien zu einem lebendigen Qualitätsstandard, der sich kontinuierlich verbessert. --- @@ -156,13 +156,15 @@ Checke `.failproofai/policies/` in dein Repository ein, damit das gesamte Team d Alle Konfigurationen und Protokolle verbleiben auf deinem Rechner: -| Pfad | Was gespeichert wird | -|------|----------------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | Globale Richtlinienkonfiguration | -| `~/.failproofai/hook-activity/` | Hook-Ausführungsverlauf (seitenweise JSONL) | +| Pfad | Inhalt | +|------|--------| +| `~/.failproofai/policies-config.json` | Globale Richtlinienkonfiguration | +| `~/.failproofai/policies/` | Eigene Richtlinien – `*-policies.mjs` ablegen, keine Konfiguration nötig | +| `~/.failproofai/policies/cloud-policies/` | Von deiner Organisation auf diesem Rechner bereitgestellte Richtlinien | +| `~/.failproofai/hook-activity/` | Hook-Ausführungsverlauf (paginiertes JSONL) | | `~/.failproofai/logs/` | Debug-Protokolle für benutzerdefinierte Hook-Fehler | -| `.failproofai/policies-config.json` | Projektbezogene Konfiguration (eingecheckt) | -| `.failproofai/policies-config.local.json` | Persönliche Überschreibungen (gitignored) | +| `.failproofai/policies-config.json` | Projektspezifische Konfiguration (eingecheckt) | +| `.failproofai/policies-config.local.json` | Persönliche Überschreibungen (per gitignore ausgeschlossen) | --- @@ -181,7 +183,7 @@ Entfernt Hook-Einträge aus `~/.claude/settings.json`. Konfigurationsdateien in - Scopes und Konfigurationsdateiformat + Bereiche und Konfigurationsdateiformat @@ -189,11 +191,11 @@ Entfernt Hook-Einträge aus `~/.claude/settings.json`. Konfigurationsdateien in - Schreibe eigene Richtlinien in JavaScript + Eigene Richtlinien in JavaScript schreiben - - Sitzungen überwachen und Richtlinienaktivitäten überprüfen + + Sitzungen überwachen und Richtlinienaktivität überprüfen \ No newline at end of file diff --git a/docs/de/introduction.mdx b/docs/de/introduction.mdx index 1ff567ef..c8bd790d 100644 --- a/docs/de/introduction.mdx +++ b/docs/de/introduction.mdx @@ -1,36 +1,36 @@ --- title: "Failproof AI" -description: "FailproofAI gibt KI-Agenten 39 integrierte Fehlerrichtlinien, die Schleifen, Secret-Leaks, destruktive Tool-Aufrufe und mehr mit einer einzigen Installation abfangen." +description: "FailproofAI gibt KI-Agenten 39 integrierte Fehler-Policies, die Schleifen, geheime Datenlecks, destruktive Tool-Aufrufe und mehr mit einer einzigen Installation abfangen." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hooks und Richtlinien für **KI-Fehlerbehandlung**, **Fehlerwiederherstellung** und **LLM-Zuverlässigkeit**. Halten Sie Ihre KI-Agenten zuverlässig und autonom am Laufen – für **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** und das **Agents SDK**. +Hooks und Policies für **KI-Fehlerbehandlung**, **Fehlerwiederherstellung** und **LLM-Zuverlässigkeit**. Halten Sie Ihre KI-Agenten zuverlässig und autonom am Laufen – mit **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** und dem **Agents SDK**. -KI-Agenten scheitern auf vorhersehbare Weise. Sie führen destruktive Befehle aus, leaken Secrets, driften vom Kurs ab, stecken in Schleifen fest oder pushen direkt auf main. Werden diese Fehler nicht abgefangen, können kleine Probleme zu Ausfällen, geleakten Zugangsdaten und verlorener Arbeit eskalieren. +KI-Agenten scheitern auf vorhersehbare Weise. Sie führen destruktive Befehle aus, geben Geheimnisse preis, driften von der Aufgabe ab, geraten in Schleifen oder pushen direkt in den Main-Branch. Unbeaufsichtigt können kleine Fehler zu Ausfällen, durchgesickerten Zugangsdaten und verlorenem Work eskalieren. -FailproofAI löst das mit **Richtlinien**. Diese Regeln greifen in jeden Agent-Tool-Aufruf ein, um **Fehler zu erkennen**, **sie zu beheben** (blockieren, anweisen, bereinigen) und **Sie zu benachrichtigen**, wenn etwas Aufmerksamkeit erfordert. Ein lokales Dashboard ermöglicht es Ihnen, anschließend jeden Tool-Aufruf, jeden Agentenfehler und jede Wiederherstellungsaktion nachzuvollziehen. +FailproofAI löst dieses Problem mit **Policies**. Diese Regeln greifen bei jedem Tool-Aufruf eines Agenten ein, um **Fehler zu erkennen**, **sie zu beheben** (blockieren, anweisen, bereinigen) und **Sie zu benachrichtigen**, wenn etwas Aufmerksamkeit erfordert. Ein lokales Dashboard ermöglicht es Ihnen, jeden Tool-Aufruf, jeden Agentenfehler und jede Wiederherstellungsmaßnahme im Nachhinein zu überprüfen. -Transkripte und Richtlinienauswertungen verbleiben auf Ihrem Rechner. Daten werden nur übertragen, wenn Sie explizit eine Online-Funktion nutzen, z. B. authentifizierte Audit-Erinnerungen oder Einladungen. +Transkripte und Policy-Auswertungen bleiben auf Ihrem Gerät. Daten werden nur dann übertragen, wenn Sie ausdrücklich eine Online-Funktion nutzen, etwa authentifizierte Audit-Erinnerungen oder Einladungen. ## Erste Schritte - - Destruktive Befehle blockieren, Secret-Leaks verhindern, Agenten innerhalb der Projektgrenzen halten und vieles mehr. Alles sofort einsatzbereit. + + Destruktive Befehle blockieren, geheime Datenlecks verhindern, Agenten innerhalb von Projektgrenzen halten und vieles mehr – alles direkt einsatzbereit. - - Schreiben Sie eigene Regeln in JavaScript mit einer einfachen allow / deny / instruct API. + + Schreiben Sie Ihre eigenen Regeln in JavaScript mit einer einfachen allow / deny / instruct API. - - Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. Sitzungen durchsuchen, Tool-Aufrufe prüfen, nachverfolgen, wo Richtlinien ausgelöst wurden. + + Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. Sitzungen durchsuchen, Tool-Aufrufe inspizieren, nachverfolgen, wo Policies ausgelöst wurden. - Jede Richtlinie ohne Code anpassen. Allowlists, geschützte Branches oder Schwellenwerte pro Projekt oder global festlegen. + Jede Policy ohne Code anpassen. Allowlists, geschützte Branches oder Schwellenwerte pro Projekt oder global festlegen. @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -Die vollständige Anleitung finden Sie im [Erste-Schritte-Leitfaden](/de/getting-started). \ No newline at end of file +Eine vollständige Anleitung finden Sie im [Erste-Schritte-Leitfaden](/de/getting-started). \ No newline at end of file diff --git a/docs/de/package-aliases.mdx b/docs/de/package-aliases.mdx index fc747956..07533934 100644 --- a/docs/de/package-aliases.mdx +++ b/docs/de/package-aliases.mdx @@ -18,9 +18,9 @@ bun add -g failproofai ## Warum wir die Aliasnamen besitzen -Typosquatting ist ein verbreiteter Supply-Chain-Angriff, bei dem ein böswilliger Akteur einen Paketnamen registriert, der sich nur um einen Tastendruck vom Namen eines verbreiteten Pakets unterscheidet. Ahnungslose Nutzer, die den Installationsbefehl vertippen, führen dadurch angreifer-kontrollierten Code mit vollem Systemzugriff aus – genau die Art von Bedrohung, gegen die Failproof AI schützen soll. +Typosquatting ist ein verbreiteter Supply-Chain-Angriff, bei dem ein böswilliger Akteur einen Paketnamen registriert, der sich nur um einen Tastendruck vom Namen eines populären Pakets unterscheidet. Ahnungslose Nutzer, die beim Installationsbefehl einen Tippfehler machen, führen dadurch Code unter der Kontrolle des Angreifers mit vollem Systemzugriff aus – genau die Art von Bedrohung, gegen die Failproof AI entwickelt wurde. -Um diese Angriffsfläche zu eliminieren, **registrieren wir vorbeugend alle gängigen Schreibfehler und Formatierungsvarianten** von `failproofai` auf npm. Keiner dieser Namen kann von Dritten registriert werden. Jeder ist ein schlanker Proxy, der das echte `failproofai`-Paket installiert und an dieses delegiert. +Um diese Angriffsfläche zu eliminieren, **besitzen wir präventiv alle gängigen Schreibfehler und Formatierungsvarianten** von `failproofai` auf npm. Keiner dieser Namen kann von Dritten registriert werden. Jeder ist ein schlanker Proxy, der das echte `failproofai`-Paket installiert und an dieses delegiert. --- @@ -37,7 +37,7 @@ Um diese Angriffsfläche zu eliminieren, **registrieren wir vorbeugend alle gän | `fail_proof_ai` | ⏳ Ausstehend (npm-Freigabe) | | `fail-proofai` | ⏳ Ausstehend (npm-Freigabe) | -**`failprof*`-Tippfehler** – fehlendes „o" in „proof": +**`failprof*`-Tippfehler** – fehlendes `o` in „proof": | Paket | Status | |-------|--------| @@ -47,7 +47,7 @@ Um diese Angriffsfläche zu eliminieren, **registrieren wir vorbeugend alle gän | `fail-prof-ai` | ⏳ Ausstehend (npm-Freigabe) | | `failprof_ai` | ⏳ Ausstehend (npm-Freigabe) | -**`faliproof*`-Tippfehler** – vertauschtes „a" und „i": +**`faliproof*`-Tippfehler** – vertauschte Buchstaben `a` und `i`: | Paket | Status | |-------|--------| @@ -55,9 +55,9 @@ Um diese Angriffsfläche zu eliminieren, **registrieren wir vorbeugend alle gän | `faliproof-ai` | ✅ Veröffentlicht | | `faliproofai` | ⏳ Ausstehend (npm-Freigabe) | -> **Warum ausstehend?** Die Spam-Prävention von npm blockiert Namen, die nach dem Entfernen von Satzzeichen und dem Ausführen von Ähnlichkeitsprüfungen auf denselben String wie ein bestehendes Paket normalisiert werden. Wir haben den npm-Support kontaktiert, um diese Namen für Anti-Squatting-Zwecke zu reservieren. Sie werden nach der Genehmigung aktiviert. +> **Warum ausstehend?** Die Spam-Schutzrichtlinie von npm blockiert Namen, die nach dem Entfernen von Satzzeichen und dem Durchführen von Ähnlichkeitsprüfungen auf denselben String wie ein bestehendes Paket normalisiert werden. Wir haben den npm-Support kontaktiert, um diese Namen für Anti-Squatting-Zwecke zu reservieren. Sie werden nach Genehmigung freigeschaltet. -Sie können prüfen, ob ein veröffentlichter Alias uns gehört: +Sie können überprüfen, ob ein veröffentlichter Alias uns gehört: ```bash npm info failproof @@ -70,13 +70,13 @@ npm info failproof Jedes Alias-Paket: -1. Listet `failproofai` als Abhängigkeit auf – damit wird das eigentliche Paket installiert und sein Binary verfügbar -2. Stellt ein Binary bereit, das dem eigenen Namen entspricht (z. B. `failprof-ai`) und alle Argumente an das `failproofai`-Binary weiterleitet +1. Listet `failproofai` als Abhängigkeit auf – dadurch wird das echte Paket installiert und seine Binary verfügbar +2. Stellt eine Binary bereit, die dem eigenen Namen entspricht (z. B. `failprof-ai`) und alle Argumente an die `failproofai`-Binary weiterleitet Der Proxy ist ein zweizeiliges Node-Skript; es enthält keine Logik, keine Netzwerkaufrufe und keine Datenerfassung über das hinaus, was `failproofai` selbst tut. --- -## Falls Sie einen fehlenden Namen entdecken +## Wenn Sie einen Namen finden, den wir übersehen haben -Erstellen Sie ein Issue unter [failproofai/failproofai](https://github.com/failproofai/failproofai/issues), und wir werden ihn registrieren. \ No newline at end of file +Öffnen Sie ein Issue unter [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) und wir werden ihn registrieren. \ No newline at end of file diff --git a/docs/de/testing.mdx b/docs/de/testing.mdx index 4fd99576..6c1a9982 100644 --- a/docs/de/testing.mdx +++ b/docs/de/testing.mdx @@ -1,10 +1,10 @@ --- -title: Testing -description: "Unit-Tests, E2E-Tests und Test-Hilfsfunktionen" +title: Testen +description: "Unit-Tests, E2E-Tests und Test-Hilfsprogramme" icon: flask-vial --- -failproofai verfügt über zwei Test-Suiten: **Unit-Tests** (schnell, mit Mocks) und **End-to-End-Tests** (echte Subprocess-Aufrufe). +failproofai verfügt über zwei Test-Suiten: **Unit-Tests** (schnell, gemockt) und **End-to-End-Tests** (echte Subprocess-Aufrufe). --- @@ -17,7 +17,7 @@ bun run test:run # Unit-Tests im Watch-Modus ausführen bun run test -# E2E-Tests ausführen (erfordert Setup – siehe unten) +# E2E-Tests ausführen (erfordert Einrichtung – siehe unten) bun run test:e2e # Typprüfung ohne Build @@ -38,13 +38,13 @@ __tests__/ hooks/ builtin-policies.test.ts # Policy-Logik für jede eingebaute Policy hooks-config.test.ts # Konfigurationsladen und Scope-Zusammenführung - policy-evaluator.test.ts # Param-Injektion und Auswertungsreihenfolge - custom-hooks-registry.test.ts # globalThis-Registry add/get/clear - custom-hooks-loader.test.ts # ESM-Loader, transitive Imports, Fehlerbehandlung + policy-evaluator.test.ts # Parameter-Injection und Auswertungsreihenfolge + custom-hooks-registry.test.ts # globalThis-Registry: add/get/clear + custom-hooks-loader.test.ts # ESM-Loader, transitive Importe, Fehlerbehandlung manager.test.ts # install/remove/list-Operationen components/ - sessions-list.test.tsx # Session-Listen-Komponente - project-list.test.tsx # Projektlisten-Komponente + sessions-list.test.tsx # Session-Listenkomponente + project-list.test.tsx # Projektlistenkomponente ... lib/ logger.test.ts @@ -110,11 +110,11 @@ describe("block-sudo", () => { ## End-to-End-Tests -E2E-Tests rufen das echte `failproofai`-Binary als Subprocess auf, leiten eine JSON-Payload an stdin weiter und prüfen die stdout-Ausgabe sowie den Exit-Code. Damit wird der vollständige Integrationspfad getestet, den Claude Code verwendet. +E2E-Tests rufen das echte `failproofai`-Binary als Subprocess auf, leiten eine JSON-Nutzlast an stdin weiter und prüfen die stdout-Ausgabe sowie den Exit-Code. Damit wird der vollständige Integrationspfad getestet, den Claude Code verwendet. -### Setup +### Einrichtung -E2E-Tests führen das Binary direkt aus dem Repo-Quellcode aus. Vor dem ersten Durchlauf muss das CJS-Bundle gebaut werden, das Custom-Hook-Dateien beim Import von `'failproofai'` verwenden: +E2E-Tests führen das Binary direkt aus dem Repository-Quellcode aus. Erstelle vor dem ersten Durchlauf das CJS-Bundle, das benutzerdefinierte Hook-Dateien verwenden, wenn sie aus `'failproofai'` importieren: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,33 +126,33 @@ Anschließend die Tests ausführen: bun run test:e2e ``` -`dist/` muss neu gebaut werden, wenn die öffentliche Hook-API geändert wird (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` oder `src/hooks/policy-types.ts`). +Erstelle `dist/` neu, wenn du die öffentliche Hook-API änderst (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` oder `src/hooks/policy-types.ts`). ### E2E-Teststruktur ```text __tests__/e2e/ helpers/ - hook-runner.ts # Binary starten, Payload-JSON weiterleiten, Exit-Code + stdout + stderr erfassen - fixture-env.ts # Pro Test isolierte temporäre Verzeichnisse mit Konfigurationsdateien - payloads.ts # Claude-konforme Payload-Factories für jeden Event-Typ + hook-runner.ts # Binary starten, Nutzlast-JSON pipen, Exit-Code + stdout + stderr erfassen + fixture-env.ts # Isolierte Temp-Verzeichnisse pro Test mit Konfigurationsdateien + payloads.ts # Claude-konforme Nutzlast-Factories für jeden Event-Typ hooks/ builtin-policies.e2e.test.ts # Jede eingebaute Policy mit echtem Subprocess - custom-hooks.e2e.test.ts # Laden und Auswerten von Custom Hooks - config-scopes.e2e.test.ts # Konfigurationszusammenführung über project/local/global - policy-params.e2e.test.ts # Parameter-Injektion für jede parametrisierte Policy + custom-hooks.e2e.test.ts # Laden und Auswertung benutzerdefinierter Hooks + config-scopes.e2e.test.ts # Konfigurationszusammenführung über Projekt/Lokal/Global + policy-params.e2e.test.ts # Parameter-Injection für jede parametrisierte Policy ``` -### Die E2E-Hilfsfunktionen verwenden +### Die E2E-Hilfsprogramme verwenden -**`FixtureEnv`** – isolierte Umgebung pro Test: +**`FixtureEnv`** – isolierte Testumgebung pro Test: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - temporäres Verzeichnis; als payload.cwd übergeben, um .failproofai/policies-config.json einzulesen -// env.home - isoliertes Home-Verzeichnis; kein echtes ~/.failproofai wird eingelesen +// env.cwd - Temp-Verzeichnis; als payload.cwd übergeben, um .failproofai/policies-config.json zu laden +// env.home - isoliertes Home-Verzeichnis; kein echtes ~/.failproofai tritt durch env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,7 +162,7 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` registriert `afterEach`-Cleanup automatisch. +`createFixtureEnv()` registriert die `afterEach`-Bereinigung automatisch. **`runHook`** – das Binary aufrufen: @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** – fertige Payload-Factories: +**`Payloads`** – vorgefertigte Nutzlast-Factories: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -238,7 +238,7 @@ describe("block-rm-rf (E2E)", () => { | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct (kein Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | leerer stdout; Grund in stderr | +| Stop instruct | `2` | leerer stdout; Begründung in stderr | | Allow | `0` | leerer String | ### Vitest-Konfiguration @@ -246,15 +246,15 @@ describe("block-rm-rf (E2E)", () => { E2E-Tests verwenden `vitest.config.e2e.mts` mit: - `environment: "node"` – keine Browser-Globals erforderlich -- `pool: "forks"` – echte Prozessisolierung (Tests starten Subprozesse) +- `pool: "forks"` – echte Prozessisolierung (Tests starten Subprocesse) - `testTimeout: 20_000` – 20 Sekunden pro Test (Binary-Start + Hook-Auswertung) -Der `forks`-Pool ist wichtig: Thread-basierte Worker teilen `globalThis`, was Subprozess-startende Tests beeinträchtigen kann. Prozessbasierte Forks vermeiden dieses Problem. +Der `forks`-Pool ist wichtig: Thread-basierte Worker teilen sich `globalThis`, was Subprocess-startende Tests stören kann. Prozessbasierte Forks vermeiden dies. --- ## CI -Der vollständige CI-Durchlauf (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) muss erfolgreich sein, bevor ein Merge durchgeführt werden kann. Die E2E-Suite wird als separater CI-Job parallel ausgeführt. +Der vollständige CI-Durchlauf (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) muss erfolgreich sein, bevor ein Merge durchgeführt werden kann. Die E2E-Suite läuft als separater CI-Job parallel dazu. -Die vollständige Checkliste vor dem Merge ist unter [Contributing](../CONTRIBUTING.md) zu finden. \ No newline at end of file +Siehe [Contributing](../CONTRIBUTING.md) für die vollständige Checkliste vor dem Merge. \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index 744a6e59..c5822a49 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -223,6 +223,8 @@ "zh/cli/list-policies", "zh/cli/hook", "zh/cli/audit", + "zh/cli/update", + "zh/cli/migrate", "zh/cli/version", "zh/cli/environment-variables" ] @@ -334,6 +336,8 @@ "ja/cli/list-policies", "ja/cli/hook", "ja/cli/audit", + "ja/cli/update", + "ja/cli/migrate", "ja/cli/version", "ja/cli/environment-variables" ] @@ -445,6 +449,8 @@ "ko/cli/list-policies", "ko/cli/hook", "ko/cli/audit", + "ko/cli/update", + "ko/cli/migrate", "ko/cli/version", "ko/cli/environment-variables" ] @@ -556,6 +562,8 @@ "es/cli/list-policies", "es/cli/hook", "es/cli/audit", + "es/cli/update", + "es/cli/migrate", "es/cli/version", "es/cli/environment-variables" ] @@ -667,6 +675,8 @@ "pt-br/cli/list-policies", "pt-br/cli/hook", "pt-br/cli/audit", + "pt-br/cli/update", + "pt-br/cli/migrate", "pt-br/cli/version", "pt-br/cli/environment-variables" ] @@ -778,6 +788,8 @@ "de/cli/list-policies", "de/cli/hook", "de/cli/audit", + "de/cli/update", + "de/cli/migrate", "de/cli/version", "de/cli/environment-variables" ] @@ -889,6 +901,8 @@ "fr/cli/list-policies", "fr/cli/hook", "fr/cli/audit", + "fr/cli/update", + "fr/cli/migrate", "fr/cli/version", "fr/cli/environment-variables" ] @@ -1000,6 +1014,8 @@ "ru/cli/list-policies", "ru/cli/hook", "ru/cli/audit", + "ru/cli/update", + "ru/cli/migrate", "ru/cli/version", "ru/cli/environment-variables" ] @@ -1111,6 +1127,8 @@ "hi/cli/list-policies", "hi/cli/hook", "hi/cli/audit", + "hi/cli/update", + "hi/cli/migrate", "hi/cli/version", "hi/cli/environment-variables" ] @@ -1222,6 +1240,8 @@ "tr/cli/list-policies", "tr/cli/hook", "tr/cli/audit", + "tr/cli/update", + "tr/cli/migrate", "tr/cli/version", "tr/cli/environment-variables" ] @@ -1333,6 +1353,8 @@ "vi/cli/list-policies", "vi/cli/hook", "vi/cli/audit", + "vi/cli/update", + "vi/cli/migrate", "vi/cli/version", "vi/cli/environment-variables" ] @@ -1444,6 +1466,8 @@ "it/cli/list-policies", "it/cli/hook", "it/cli/audit", + "it/cli/update", + "it/cli/migrate", "it/cli/version", "it/cli/environment-variables" ] @@ -1555,6 +1579,8 @@ "ar/cli/list-policies", "ar/cli/hook", "ar/cli/audit", + "ar/cli/update", + "ar/cli/migrate", "ar/cli/version", "ar/cli/environment-variables" ] @@ -1666,6 +1692,8 @@ "he/cli/list-policies", "he/cli/hook", "he/cli/audit", + "he/cli/update", + "he/cli/migrate", "he/cli/version", "he/cli/environment-variables" ] diff --git a/docs/es/agenteye/alerts.mdx b/docs/es/agenteye/alerts.mdx index 82beeb55..c5a0a631 100644 --- a/docs/es/agenteye/alerts.mdx +++ b/docs/es/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "Alertas" -description: "Entérate en el momento en que algo cruza tu línea, en el canal que tu equipo ya monitorea, en lugar de que te lo diga un cliente." +description: "Entérate en el momento en que algo supere tus límites, en el canal que tu equipo ya utiliza, en lugar de saberlo por un cliente." --- -Entérate en el momento en que algo cruza tu línea, en el canal que tu equipo ya monitorea, en lugar de que te lo diga un cliente. Define una regla una vez y Failproof AI Observability la evalúa según un calendario, notificándote por email, Slack, webhook o directamente en el dashboard. +Entérate en el momento en que algo supere tus límites, en el canal que tu equipo ya utiliza, en lugar de saberlo por un cliente. Define una regla una vez y Failproof AI Observability la comprueba de forma programada, y te notifica por correo electrónico, Slack, webhook o directamente en el dashboard. -![La página de Alertas: una cuadrícula de tarjetas de reglas de alerta, cada una con su disparador, ventana de evaluación, canales y una insignia de severidad informativa, de advertencia o crítica](/agenteye/images/alerts.png) -*Todas las reglas de alerta de un vistazo: qué monitorea, con qué frecuencia, dónde notifica y qué tan urgente es.* +![La página de Alertas: una cuadrícula de tarjetas de reglas de alerta, cada una mostrando su disparador, ventana de evaluación, canales y un distintivo de severidad informativa, de advertencia o crítica](/agenteye/images/alerts.png) +*Todas las reglas de alerta de un vistazo: qué supervisa, con qué frecuencia, dónde notifica y qué tan urgente es.* ## Entérate de los problemas antes que tus usuarios -Deja de actualizar un dashboard esperando detectar una regresión. Configura una alerta cada vez que haya una señal que quieras conocer incluso cuando nadie esté mirando, y recíbela donde ya estás: +Deja de actualizar un dashboard con la esperanza de detectar una regresión. Configura una alerta siempre que haya una señal sobre la que quieras saber incluso cuando nadie está mirando, y recíbela donde ya estás: -- **Email**, para quienes deban saberlo. +- **Correo electrónico**, para quien deba saberlo. - **Slack**, un mensaje enriquecido con un botón que lleva directamente al incidente. -- **Webhook**, un POST JSON para PagerDuty, Opsgenie o tu propio endpoint, con una firma opcional para que el receptor pueda verificar su origen. -- **En el dashboard**, silencioso por diseño, para cuando estés ajustando una regla y aún no quieras notificar a nadie. +- **Webhook**, un POST JSON para PagerDuty, Opsgenie o tu propio endpoint, con una firma opcional para que el receptor pueda verificarlo. +- **En el dashboard**, discreto por diseño, para cuando estás ajustando una regla y aún no quieres notificar a nadie. -Combina cualquier cantidad de canales en una sola regla, y su severidad (informativa, de advertencia o crítica) viaja junto con ella para que las urgentes luzcan urgentes. +Vincula cualquier combinación a una sola regla, y su severidad (informativa, de advertencia o crítica) se incluye para que las urgentes parezcan urgentes. ## Crea la regla en un formulario, no en JSON -Describes lo que significa "roto" en un formulario y Failproof AI Observability escribe la regla subyacente por ti. La especificación JSON es simplemente lo que produce ese formulario internamente, así que puedes leerla para entender una regla, pero rara vez necesitarás escribirla. +Describes qué significa "roto" en un formulario, y Failproof AI Observability escribe la regla subyacente por ti. La especificación JSON es simplemente lo que ese formulario produce internamente, por lo que puedes leerla para entender una regla, pero rara vez necesitas escribirla manualmente. -![El formulario de nueva alerta: nombre y descripción, un interruptor de activación y un selector de disparador que ofrece umbral de métrica, SQL personalizado, puntuación de evaluación, evaluación compuesta y condiciones por evento](/agenteye/images/alert-new.png) -*Elige un disparador y el formulario muestra los campos correctos; Guardar escribe la regla.* +![El formulario de nueva alerta: nombre y descripción, un interruptor de activación y un selector de disparador que ofrece umbral de métrica, SQL personalizado, puntuación de evaluación, eval compuesto y condiciones por evento](/agenteye/images/alert-new.png) +*Selecciona un disparador y el formulario muestra los campos correctos; Guardar escribe la regla.* -El flujo principal es rápido: nómbrala, elige un **disparador** (qué monitorear), define el **umbral y la ventana** (qué tan grave, durante cuánto tiempo), adjunta al menos un **canal**, luego **Guarda** y haz clic en **Probar** para enviar una notificación sintética y confirmar que todos los destinos están correctamente configurados. Internamente, eso produce una pequeña especificación como esta: +El flujo habitual es rápido: ponle nombre, elige un **disparador** (qué supervisar), establece el **umbral y la ventana** (qué tan grave, durante cuánto tiempo), vincula al menos un **canal**, luego **Guarda** y pulsa **Probar** para lanzar una notificación sintética y confirmar que cada destino está conectado correctamente. Internamente esto produce una pequeña especificación como: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -No estás limitado a un solo tipo de señal. Elige el disparador que se adapte a cómo piensas sobre el fallo: +No estás limitado a un solo tipo de señal. Elige el disparador que se ajuste a cómo piensas sobre el fallo: | Disparador | Se activa cuando | |---|---| -| **Umbral de métrica** | una métrica predefinida (tasa de errores, latencia p95 o p99, conteos de eventos o errores, gasto en tokens) cruza tu línea durante una ventana de tiempo | -| **SQL personalizado** | tu propia consulta de solo lectura devuelve una fila, o un valor calculado cruza un umbral | -| **Puntuación de evaluación** | el promedio de la puntuación de un evaluador (por ejemplo, alucinaciones) cruza un umbral | -| **Evaluación compuesta** | varias verificaciones de puntuación se combinan con lógica any, all o al-menos-N para detectar una regresión que solo se manifiesta entre múltiples puntuaciones | -| **Por evento** | llega un único evento coincidente: un agente específico, un tipo de error específico o una subcadena de mensaje | +| **Umbral de métrica** | una métrica predefinida (tasa de errores, latencia p95 o p99, conteo de eventos o errores, gasto en tokens) supera tu límite durante una ventana | +| **SQL personalizado** | tu propia consulta de solo lectura devuelve una fila, o un valor que calcula supera un umbral | +| **Puntuación de evaluación** | el promedio de puntuación de un evaluador (por ejemplo, alucinaciones) supera un umbral | +| **Eval compuesto** | varias comprobaciones de puntuación se combinan con lógica any, all o al-menos-N, para detectar una regresión que solo se manifiesta en múltiples puntuaciones | +| **Por evento** | llega un único evento coincidente: un agente específico, un tipo de error específico o una subcadena de un mensaje | -¿Ya estás mirando un fallo en la [página de Errores](/es/agenteye/error-tracking)? Cada fila tiene un botón **+ alerta** que abre este mismo formulario prellenado para detectar exactamente ese fallo en el futuro, de modo que el incidente que acabas de atender sea el que te notifique la próxima vez. +¿Ya estás viendo un fallo en la [página de Errores](/es/agenteye/error-tracking)? Cada fila tiene un botón **+ alerta** que abre este mismo formulario precompletado para detectar exactamente ese fallo en el futuro, de modo que el incidente que acabas de clasificar sea el que te notifique la próxima vez. -**Dónde encontrarlo:** Las Alertas están en `//alerts`. Para crear, editar, eliminar y probar reglas se necesita **`alerts:write`**; con `alerts:read` es suficiente para consultar. El selector de destinatarios lista a los miembros de tu organización por nombre, así que puedes notificar a una persona sin salir del formulario. +**Dónde encontrarlo:** Las alertas se encuentran en `//alerts`. Crear, editar, eliminar y probar reglas requiere **`alerts:write`**; con `alerts:read` es suficiente para consultar. El selector de destinatarios lista a los miembros de tu organización por nombre, por lo que puedes notificar a una persona sin salir del formulario. ## Notifícame solo cuando sea real -Una medición errónea no debería despertarte. El filtro de ruido **M de N** controla cuántas de las últimas verificaciones deben fallar antes de que la alerta te notifique realmente. Configúralo en **3 de 5** y la regla se activa solo después de que haya superado el umbral en tres de sus últimas cinco verificaciones, de modo que una señal inestable deje de dar falsas alarmas; déjalo en el valor predeterminado **1 de 1** para que se active en la primera infracción. También eliges con qué frecuencia se ejecuta la regla, a partir de intervalos predefinidos de 1m, 5m, 15m y 1h, ajustados a la velocidad real con que se mueve la señal. +Una medición errónea no debería despertarte. El filtro de ruido **M de N** controla cuántas de las últimas comprobaciones deben fallar antes de que la alerta te notifique realmente. Configúralo en **3 de 5** y la regla se activa solo después de superar el umbral en tres de sus últimas cinco comprobaciones, evitando que una señal inestable genere falsas alarmas; déjalo en el valor predeterminado **1 de 1** para que se active en la primera infracción. También puedes elegir con qué frecuencia se ejecuta la regla, con presets de 1m, 5m, 15m y 1h, adaptados a la velocidad real con que se mueve la señal. ## Qué ocurre cuando se activa una alerta -Una infracción abre un **incidente** y notifica a tus canales una sola vez. A partir de ahí, tu equipo lo reconoce, asigna un responsable, lo discute y lo resuelve, todo con un registro limpio y atribuido. Ese flujo de trabajo de triaje tiene su propio espacio: consulta [Incidentes](/es/agenteye/incidents). +Una infracción abre un **incidente** y notifica tus canales una vez. A partir de ahí, tu equipo lo reconoce, asigna un responsable, lo discute y lo resuelve, todo con un registro limpio y atribuido. Ese flujo de clasificación tiene su propio espacio: consulta [Incidentes](/es/agenteye/incidents). ## Relacionado - [Incidentes](/es/agenteye/incidents): sigue una alerta activa desde abierta hasta reconocida y resuelta. -- [Seguimiento de errores](/es/agenteye/error-tracking): agrupa fallos de agentes y conviértelos en una alerta con un clic. -- [Dashboards](/es/agenteye/dashboards): monitorea los paneles compartidos de los que provienen los umbrales que alertas. -- [CLI y agentes](/es/agenteye/cli-and-agents): crea alertas y confirma incidentes desde tu terminal, o incorpóralos a scripts de CI. \ No newline at end of file +- [Seguimiento de errores](/es/agenteye/error-tracking): agrupa los fallos del agente y promueve uno a alerta con un clic. +- [Dashboards](/es/agenteye/dashboards): supervisa los tableros compartidos de donde provienen los umbrales sobre los que alertas. +- [CLI y agentes](/es/agenteye/cli-and-agents): crea alertas y reconoce incidentes desde tu terminal, o incorpóralos en scripts de CI. \ No newline at end of file diff --git a/docs/es/agenteye/api-keys.mdx b/docs/es/agenteye/api-keys.mdx index ce8b5c45..7453bc97 100644 --- a/docs/es/agenteye/api-keys.mdx +++ b/docs/es/agenteye/api-keys.mdx @@ -1,97 +1,97 @@ --- title: "API Keys" -description: "Las API keys controlan quién y qué puede acceder a tu servidor de Observabilidad de Failproof AI, de modo que un collector pueda enviar eventos sin obtener permisos de lectura ni de administración." +description: "Las API keys controlan quién y qué puede acceder a tu servidor de Observabilidad de Failproof AI, de modo que un colector pueda enviar eventos sin obtener nunca permisos de lectura ni de administrador." --- -Las API keys controlan quién y qué puede acceder a tu servidor de Observabilidad de Failproof AI, de modo que un collector pueda enviar eventos sin obtener permisos de lectura ni de administración. Cada clave lleva uno o más permisos, y cada permiso protege rutas específicas del servidor; solo otorgas los que un trabajo necesita. La mayoría de los despliegues crean únicamente tres tipos de clave. +Las API keys controlan quién y qué puede acceder a tu servidor de Observabilidad de Failproof AI, de modo que un colector pueda enviar eventos sin obtener nunca permisos de lectura ni de administrador. Cada key tiene uno o más permisos, y cada permiso controla el acceso a rutas específicas del servidor; así concedes únicamente los permisos que necesita cada tarea. La mayoría de los despliegues crean solo tres tipos de key. -## Las 3 claves que necesitan la mayoría de los despliegues +## Los 3 tipos de key que necesita la mayoría de los despliegues -| Clave | Permisos | Quién la usa | +| Key | Permisos | Quién la usa | |---|---|---| -| Clave de collector | `events:add` | El `agenteye-collector` en cada máquina agente, para enviar eventos. | -| Clave de lectura del dashboard | `events:read`, `keys:read` | Un operador o integración de solo lectura que consulta datos sin modificarlos. | -| Clave admin de bootstrap | todos los permisos | El operador que levanta la instancia por primera vez (junto con el dashboard). Se inicializa desde la variable de entorno `ADMIN_KEY`. Ver [Clave admin de bootstrap](#bootstrap-admin-key). | +| Collector key | `events:add` | El `agenteye-collector` en cada máquina agente, para enviar eventos. | +| Dashboard read key | `events:read`, `keys:read` | Un operador de solo lectura o una integración que consulta datos sin modificarlos. | +| Bootstrap admin key | todos los permisos | El operador que pone en marcha la instancia por primera vez (y el dashboard). Se inicializa desde la variable de entorno `ADMIN_KEY`. Ver [Bootstrap admin key](#bootstrap-admin-key). | -Empieza aquí. Consulta el catálogo completo de permisos a continuación solo cuando necesites una clave con un ámbito más estrecho y personalizado. Ver también [Distribución recomendada de claves](#recommended-key-layout) y [Crear claves](#creating-keys). +Comienza aquí. Consulta el catálogo completo de permisos más abajo solo cuando necesites una key con un alcance más restringido y personalizado. Ver también [Layout de keys recomendado](#recommended-key-layout) y [Crear keys](#creating-keys). --- ## Permisos -El servidor aplica un catálogo fijo de permisos; cada uno protege rutas HTTP específicas. Una **clave admin** los tiene todos; una clave con ámbito tiene el subconjunto que otorgues al crearla. Las cadenas de permisos desconocidas son rechazadas al crear una clave. +El servidor aplica un catálogo fijo de permisos; cada uno controla el acceso a rutas HTTP específicas. Una **admin key** los tiene todos; una key con alcance limitado tiene solo el subconjunto que concedes al crearla. Los strings de permisos desconocidos se rechazan al crear una key. -> **Nota:** Dos permisos válidos son exclusivos para humanos/dashboard y no pueden asignarse a una API key: `orgs:admin` (administración de la instancia, exclusiva para operadores) y `keys:update`. Una solicitud a `POST /keys` o `PATCH /keys/:id` que intente otorgar cualquiera de los dos es rechazada con HTTP 422. Consulta la fila `keys:update` a continuación para entender por qué una clave bearer puede crear claves pero nunca editarlas. +> **Nota:** Dos permisos válidos son exclusivos para humanos/dashboard y no se pueden conceder a una API key: `orgs:admin` (administración de la instancia, solo para operadores) y `keys:update`. Una solicitud a `POST /keys` o `PATCH /keys/:id` que intente conceder cualquiera de ellos se rechaza con HTTP 422. Ver la fila de `keys:update` más abajo para entender por qué una bearer key puede crear keys pero nunca editarlas. -### Ingesta y consulta de eventos +### Ingestión y consulta de eventos | Permiso | Rutas HTTP | Qué permite | |---|---|---| -| `events:add` | `POST /events` | Ingestar lotes de eventos desde un collector. Es el único permiso que necesita un collector. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Consultar eventos, listar los entornos conocidos, listar los identificadores de modelos encontrados en los datos (usados por la vista de Modelos y los filtros de modelos), calcular el agregado de latencia que alimenta el mapa de calor / banda de percentiles, y exportar una sesión como JSONL. Los endpoints de facetas de la barra de filtros compartida `GET /events/environments` y `GET /events/agent_ids` son accesibles con **`events:read`** **o** `evaluations:read`, de modo que la página de sesiones (protegida por `evaluations:read`) reutiliza la misma faceta por organización. `GET /events/models` no es uno de ellos: requiere `events:read`, por lo que un principal que solo tenga `evaluations:read` recibirá un 403. | +| `events:add` | `POST /events` | Ingerir lotes de eventos desde un colector. Es el único permiso que necesita un colector. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Consultar eventos, listar los entornos conocidos, listar los identificadores de modelos observados en los datos (usado por la vista de Modelos y los filtros de modelos), calcular el agregado de latencia que alimenta el mapa de calor / banda de percentiles, y exportar una sesión como JSONL. Los endpoints de facetas de la barra de filtros compartida `GET /events/environments` y `GET /events/agent_ids` son accesibles con **`events:read`** o **`evaluations:read`**, por lo que la página de sesiones (controlada por `evaluations:read`) reutiliza la misma faceta por organización. `GET /events/models` no es uno de ellos: requiere `events:read`, por lo que un principal que solo tenga `evaluations:read` recibirá un 403. | ### Sesiones y evaluaciones | Permiso | Rutas HTTP | Qué permite | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Listar sesiones, leer resultados de evaluaciones, el estado de salud resumido de evaluaciones usado por los dashboards, y el estado de la cola de trabajos de evaluación. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Encolar manualmente una reevaluación para una sesión finalizada. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Listar sesiones, leer resultados de evaluaciones, el estado consolidado de salud de evaluaciones usado por los dashboards, y el estado de la cola de trabajos de evaluación. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Encolar manualmente una re-evaluación para una sesión finalizada. | ### Dashboards | Permiso | Rutas HTTP | Qué permite | |---|---|---| | `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Listar dashboards, cargar uno y leer sus tiles. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Crear y editar dashboards, agregar / editar / eliminar tiles, y reorganizar la cuadrícula de tiles. | -| `dashboards:delete` | `DELETE /dashboards/:id` | Eliminar un dashboard completo (la eliminación a nivel de tile corresponde a `dashboards:write`). | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Crear y editar dashboards, añadir / editar / eliminar tiles, y reorganizar la cuadrícula de tiles. | +| `dashboards:delete` | `DELETE /dashboards/:id` | Eliminar un dashboard completo (la eliminación a nivel de tile está bajo `dashboards:write`). | ### Consultas guardadas (compositor SQL) | Permiso | Rutas HTTP | Qué permite | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Listar consultas guardadas, cargar una e inspeccionar el esquema de solo lectura al que apunta el compositor. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | Crear y editar consultas guardadas. El SQL se enruta a través del mismo rol de solo lectura y las mismas verificaciones de SQL protegido que una llamada `queries:run`. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Listar consultas guardadas, cargar una, e inspeccionar el esquema de solo lectura al que apunta el compositor. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | Crear y editar consultas guardadas. El SQL sigue enrutándose a través del mismo rol de solo lectura y las mismas comprobaciones SQL que una llamada a `queries:run`. | | `queries:delete` | `DELETE /queries/:id` | Eliminar una consulta guardada. | -| `queries:run` | `POST /queries/run` | Ejecutar SQL guardado o ad-hoc contra el rol de solo lectura utilizado por el compositor. | +| `queries:run` | `POST /queries/run` | Ejecutar SQL guardado o ad-hoc contra el rol de solo lectura que usa el compositor. | ### Asistente de IA | Permiso | Rutas HTTP | Qué permite | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Interactuar con el asistente de IA y gestionar tus propias conversaciones (privadas). Requerido en el **usuario** para ver el panel del asistente; la clave propia del asistente es `dashboard-assistant` y se inicializa por separado (ver más abajo). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Hablar con el asistente de IA y gestionar tus propias conversaciones (privadas). Requerido en el **usuario** para ver el panel del asistente; la propia key del asistente es `dashboard-assistant` y se inicializa por separado (ver más abajo). | ### API keys | Permiso | Rutas HTTP | Qué permite | |---|---|---| -| `keys:create` | `POST /keys` | Crear una nueva API key con ámbito. **No** otorga la capacidad de editar los permisos de una clave existente (eso es `keys:update`). | -| `keys:read` | `GET /keys` | Listar las claves existentes. Los secretos nunca son devueltos por este endpoint. | -| `keys:update` | `PATCH /keys/:id` | Editar los permisos de una clave existente. Permiso **exclusivo para humanos/dashboard**; no puede asignarse a una API key (una clave bearer puede crear claves pero nunca editarlas). | -| `keys:disable` | `POST /keys/:id/disable` | Revocar una clave. Las claves protegidas (`admin`, `dashboard-assistant`) no pueden deshabilitarse; rótalas mediante la variable de entorno y un reinicio. | -| `keys:regenerate` | `POST /keys/:id/regenerate` | Rotar el secreto de una clave. Las claves protegidas no pueden regenerarse mediante esta ruta. | +| `keys:create` | `POST /keys` | Crear una nueva API key con alcance limitado. **No** concede editar los permisos de una key existente (eso es `keys:update`). | +| `keys:read` | `GET /keys` | Listar las keys existentes. Los secretos nunca se devuelven en este endpoint. | +| `keys:update` | `PATCH /keys/:id` | Editar los permisos de una key existente. Permiso **exclusivo para humanos/dashboard**; no se puede asignar a una API key (una bearer key puede crear keys pero nunca editarlas). | +| `keys:disable` | `POST /keys/:id/disable` | Revocar una key. Las keys protegidas (`admin`, `dashboard-assistant`) no se pueden deshabilitar; rótalas mediante variable de entorno + reinicio. | +| `keys:regenerate` | `POST /keys/:id/regenerate` | Rotar el secreto de una key. Las keys protegidas no se pueden regenerar a través de esta ruta. | ### Usuarios del dashboard | Permiso | Rutas HTTP | Qué permite | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | Invitar a un nuevo usuario del dashboard (emite un correo electrónico + inicio de sesión con código de un solo uso (OTP)) y leer el conjunto de permisos predeterminado configurado en el dashboard utilizado para prellenar el formulario de invitación. | -| `users:read` | `GET /users`, `GET /users/:id` | Listar usuarios y cargar el registro de un usuario individual. | -| `users:update` | `PUT /users/:id` | Editar los permisos de un usuario. Las actualizaciones envían un correo de cambio de permisos al usuario afectado y surten efecto en su siguiente solicitud; no requieren volver a iniciar sesión. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Deshabilitar un usuario (revoca sus sesiones de inmediato) y rehabilitar a un usuario previamente deshabilitado. | +| `users:create` | `POST /users`, `GET /users/defaults` | Invitar a un nuevo usuario del dashboard (genera un email + inicio de sesión con código de un solo uso (OTP)) y leer el conjunto de permisos por defecto configurado en el dashboard que se usa para preinicializar el formulario de invitación. | +| `users:read` | `GET /users`, `GET /users/:id` | Listar usuarios y cargar el registro de un único usuario. | +| `users:update` | `PUT /users/:id` | Editar los permisos de un usuario. Las actualizaciones envían un email de cambio de permisos al usuario afectado y surten efecto en su siguiente solicitud; no es necesario volver a iniciar sesión. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Deshabilitar a un usuario (revoca sus sesiones inmediatamente) y volver a habilitar a un usuario previamente deshabilitado. | -Estos permisos respaldan la página **Users** del dashboard, donde los ámbitos otorgados a cada miembro se muestran como chips: +Estos permisos respaldan la página **Users** del dashboard, donde los permisos concedidos a cada miembro se muestran como etiquetas: -![La página Users: una tarjeta por usuario del dashboard con su email, permisos otorgados y controles de edición/deshabilitación](/agenteye/images/users.png) +![La página Users: una tarjeta por usuario del dashboard con su email, permisos concedidos y controles de edición/deshabilitación](/agenteye/images/users.png) ### Configuración operacional | Permiso | Rutas HTTP | Qué permite | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Ver la configuración operacional gestionada por el dashboard y sus metadatos; listar las anulaciones de ventana de contexto por modelo; y resolver la ventana efectiva para un modelo. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Editar la configuración operacional y agregar, cambiar o eliminar anulaciones de ventana de contexto por modelo. Los cambios afectan a los nuevos eventos sin necesidad de reiniciar el servidor. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Ver la configuración operacional gestionada desde el dashboard y sus metadatos; listar las sobreescrituras de ventana de contexto por modelo; y resolver la ventana efectiva para un modelo. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Editar la configuración operacional y añadir, cambiar o eliminar sobreescrituras de ventana de contexto por modelo. Los cambios afectan a los eventos nuevos sin necesidad de reiniciar el servidor. | -![La página Settings: configuración operacional gestionada por el dashboard, como los inicios de sesión permitidos y los tiempos de vida de sesión/OTP, editable sin reiniciar](/agenteye/images/settings.png) +![La página Settings: configuración operacional gestionada desde el dashboard, como inicios de sesión permitidos y duraciones de sesión/OTP, editable sin reiniciar](/agenteye/images/settings.png) ### Alertas e incidentes @@ -100,74 +100,74 @@ Estos permisos respaldan la página **Users** del dashboard, donde los ámbitos | `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Ver las definiciones de alertas configuradas. | | `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Crear, editar, eliminar y disparar alertas de prueba. | | `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Ver incidentes y su historial de triaje. | -| `incidents:write` | `POST /alerts/:id/incidents` | Abrir un incidente manualmente contra una alerta existente. | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Reconocer, asignar, resolver y comentar incidentes. | +| `incidents:write` | `POST /alerts/:id/incidents` | Abrir un incidente manualmente asociado a una alerta existente. | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Confirmar, asignar, resolver y comentar incidentes. | ### Auditorías | Permiso | Rutas HTTP | Qué permite | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Ver definiciones de auditorías, historial de ejecuciones y hallazgos. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Crear, editar, eliminar y ejecutar auditorías; triar hallazgos (reconocer / silenciar / descartar / resolver / reabrir / asignar). | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Ver definiciones de auditoría, historial de ejecuciones y hallazgos. | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Crear, editar, eliminar y ejecutar auditorías; gestionar hallazgos (confirmar / silenciar / descartar / resolver / reabrir / asignar). | -> **Nota:** Para dar a una clave acceso a la superficie de auditorías, otórgale `audits:*` explícitamente. Ver [Notas de actualización y compatibilidad con versiones anteriores](#upgrade-and-backward-compatibility-notes) para saber cómo se migraron los titulares existentes cuando se lanzó Audits. +> **Nota:** Para dar a una key acceso a la superficie de auditorías, concédele `audits:*` explícitamente. Ver [Notas de actualización y compatibilidad](#upgrade-and-backward-compatibility-notes) para saber cómo se migraron los beneficiarios existentes cuando se lanzaron las Auditorías. -> El endpoint del selector de destinatarios `GET /alerts/recipients` (que lista los emails de los miembros a los que puede notificar un editor de alertas) es accesible por un titular de **`alerts:read`** **o** `alerts:write`, de modo que los editores de alertas pueden llenar el selector sin necesitar `users:read`. +> El endpoint selector de destinatarios `GET /alerts/recipients` (que lista los emails de los miembros a los que puede notificar un editor de alertas) es accesible para un titular de **`alerts:read`** o **`alerts:write`**, de modo que los editores de alertas pueden rellenar el selector sin necesitar `users:read`. -> Un visualizador de dashboards necesita **tanto** `dashboards:read` (para cargar las vistas guardadas) como `evaluations:read` (las métricas de salud se calculan a partir de datos de evaluaciones). Otorga `dashboards:write` para que un usuario pueda crear o editar dashboards, y `dashboards:delete` para eliminarlos. +> Un visualizador de dashboards necesita **tanto** `dashboards:read` (para cargar las vistas guardadas) como `evaluations:read` (las métricas de salud se calculan a partir de datos de evaluación). Concede `dashboards:write` para permitir a un usuario crear o editar dashboards, y `dashboards:delete` para eliminarlos. -> `/health` y `/auth/*` (solicitud OTP, verificación OTP, comprobación de sesión, cierre de sesión) no requieren autenticación por diseño; forman el flujo de inicio de sesión y la sonda de disponibilidad. `GET /access-granters` requiere una clave válida pero ningún permiso específico, por lo que cualquier usuario conectado puede ver qué administradores contactar sobre cambios de acceso. +> `/health` y `/auth/*` (solicitud OTP, verificación OTP, comprobación de sesión, cierre de sesión) son intencionalmente sin autenticación; son el flujo de inicio de sesión y la sonda de actividad. `GET /access-granters` requiere una key válida pero ningún permiso específico, por lo que cualquier usuario autenticado puede ver qué administradores contactar sobre cambios de acceso. --- ## Conjuntos de permisos -Los conjuntos de permisos te permiten aplicar un rol con nombre en lugar de seleccionar tokens individuales cada vez. En vez de elegir una docena de permisos uno por uno para cada nuevo usuario del dashboard o API key, eliges un conjunto, y todos los asignados a él llevan un otorgamiento consistente y revisable. Editar un conjunto personalizado vuelve a aplicar el nuevo otorgamiento a todos los usuarios ya asignados a él, de modo que un cambio de rol es una sola edición en lugar de recorrer cada miembro. +Los conjuntos de permisos te permiten aplicar un rol con nombre en lugar de seleccionar tokens individuales cada vez. En lugar de elegir una docena de permisos uno a uno para cada nuevo usuario del dashboard o API key, eliges un conjunto, y todos los asignados a él tienen una concesión consistente y revisable. Editar un conjunto personalizado vuelve a aplicar la nueva concesión a todos los usuarios ya asignados, por lo que un cambio de rol es una sola edición en lugar de recorrer cada miembro. -Cada organización se inicializa con tres conjuntos integrados: +Cada organización se inicializa con tres conjuntos predefinidos: | Conjunto | Permisos | Para quién | |---|---|---| -| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Acceso de solo lectura en toda la superficie operacional. | -| `standard` | todo lo de `read-only`, más `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Solo lectura más las acciones cotidianas del operador de guardia: ejecutar consultas, reevaluar sesiones, reconocer incidentes y usar el asistente de IA. | +| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Acceso de solo visualización en todas las superficies operacionales. | +| `standard` | todo lo de `read-only`, más `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Solo lectura más las acciones cotidianas del operador de guardia: ejecutar consultas, re-evaluar sesiones, confirmar incidentes y usar el asistente de IA. | | `admin` | todos los permisos asignables | Control total de la organización. | -Los tres conjuntos integrados son **inmutables**; sus nombres siempre significan lo mismo, por lo que `read-only`, `standard` y `admin` son seguros para referenciar en políticas e incorporaciones. Un operador puede crear **conjuntos personalizados** adicionales para modelar roles específicos de su organización (por ejemplo, un rol de "autor de dashboard" o un rol de "solo collector"). +Los tres conjuntos predefinidos son **inmutables**; sus nombres siempre significan lo mismo, por lo que `read-only`, `standard` y `admin` son seguros de referenciar en políticas y durante la incorporación. Un operador puede crear **conjuntos personalizados** adicionales para modelar roles específicos de tu organización (por ejemplo, un rol de "autor de dashboards" o un rol de "solo colector"). -Los conjuntos están disponibles en el dashboard y se gestionan a través de la API en `GET /permission-sets` (listar, protegido por `users:read`) y `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (crear, editar, eliminar un conjunto personalizado, protegido por `settings:write`). Eliminar o editar un conjunto integrado está prohibido. +Los conjuntos están disponibles en el dashboard y se gestionan a través de la API en `GET /permission-sets` (listar, controlado por `users:read`) y `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (crear, editar, eliminar un conjunto personalizado, controlado por `settings:write`). No se permite eliminar ni editar un conjunto predefinido. -La pertenencia a conjuntos respalda otras dos funcionalidades: +La membresía en conjuntos respalda otras dos funcionalidades: -- **`DEFAULT_USER_PERMISSIONS`** (el otorgamiento preseleccionado cuando un admin abre **+ nuevo usuario**) usa como valor predeterminado el conjunto `standard`. -- **El flag `--set`** en `agenteye-orgctl` (gestión de miembros por el operador) inicia un miembro desde un conjunto con nombre, que luego puedes ajustar con `--add` / `--remove`. +- **`DEFAULT_USER_PERMISSIONS`** (la concesión preseleccionada cuando un administrador abre **+ nuevo usuario**) toma por defecto el conjunto `standard`. +- **El flag `--set`** en `agenteye-orgctl` (gestión de miembros por el operador) inicializa a un miembro desde un conjunto con nombre, que luego puedes ajustar con `--add` / `--remove`. -> **Nota:** Cuando un conjunto incluye un permiso que no se puede asignar a claves (por ejemplo, un conjunto personalizado que lleva `keys:update`), inicializar una clave desde ese conjunto descarta los tokens no asignables; de lo contrario el servidor rechazaría la clave con HTTP 422. Los usuarios del dashboard no están sujetos a esa restricción. +> **Nota:** Cuando un conjunto incluye un permiso no asignable a keys (por ejemplo, un conjunto personalizado que lleva `keys:update`), al inicializar una key desde ese conjunto se descartan los tokens no asignables; de lo contrario el servidor rechazaría la key con HTTP 422. Los usuarios del dashboard no están sujetos a esa restricción. --- -## Clave Admin de Bootstrap +## Bootstrap Admin Key -La clave admin es la credencial raíz única que permite a un operador poner en marcha el acceso desde cero: con ella puedes crear todas las demás claves con ámbito, invitar a los primeros usuarios del dashboard y configurar la instancia antes de que exista cualquier otra clave. Es la única clave que no se crea a través de la API de claves; se provisiona desde el entorno para que el servidor sea accesible en el primer arranque. +La admin key es la credencial raíz única que permite a un operador poner en marcha el acceso desde cero: con ella puedes crear todas las demás keys con alcance limitado, invitar a los primeros usuarios del dashboard y configurar la instancia antes de que exista cualquier otra key. Es la única key que no se crea a través de la keys API; se provisiona desde el entorno para que el servidor sea accesible en el primer arranque. -Establece la variable de entorno `ADMIN_KEY` en el servidor. En cada inicio, el servidor hace un upsert de este valor como clave admin con todos los permisos. +Establece la variable de entorno `ADMIN_KEY` en el servidor. En cada arranque, el servidor actualiza o inserta este valor como una admin key con todos los permisos. -Para rotarla: cambia `ADMIN_KEY` por un nuevo secreto y reinicia el servidor. +Para rotar: cambia `ADMIN_KEY` a un nuevo secreto y reinicia el servidor. --- -## Ámbito de organización +## Alcance por organización -**Las organizaciones se crean y gestionan fuera de banda por un operador, no a través de esta API de claves.** El ciclo de vida de orgs y miembros (crear / renombrar / eliminar / purgar una org; agregar / actualizar / eliminar un miembro) se realiza con la CLI **`agenteye-orgctl`**; no existe una API HTTP ni un botón en el dashboard para ello. Lo que *sí* permanece igual: **las API keys por organización se siguen creando en el dashboard (o mediante esta API de claves)** por los miembros de la org. +**Las organizaciones en sí se crean y gestionan fuera de banda por un operador, no a través de esta keys API.** El ciclo de vida de las organizaciones y los miembros (crear / renombrar / eliminar / purgar una organización; añadir / actualizar / eliminar un miembro) se realiza con el CLI **`agenteye-orgctl`**; no hay una API HTTP ni un botón en el dashboard para ello. Lo que *no cambia*: **las API keys por organización siguen creándose en el dashboard (o a través de esta keys API)** por los miembros de la organización. -En un despliegue multi-org, cada clave que crea un miembro de una org (a través de esta API de claves o la página **Keys** del dashboard) pertenece a **una organización** y solo puede leer o escribir los datos de esa org; la org queda estampada en la clave al crearla y se aplica en cada solicitud. Las dos claves de bootstrap son la única excepción: la clave `admin` (inicializada desde `ADMIN_KEY`) y la clave `dashboard-assistant` (inicializada desde `AGENT_API_KEY`) tienen **ámbito de instancia** (no llevan org). El dashboard se autentica con la clave `admin` para poder proxiar solicitudes por organización en nombre de los miembros conectados. Los despliegues de un solo tenant no necesitan preocuparse por esto; todas las claves pertenecen a la org `default` integrada. +En un despliegue multi-organización, cada key que crea un miembro de una organización (a través de esta keys API o la página **Keys** del dashboard) pertenece a **una sola organización** y solo puede leer o escribir los datos de esa organización; la organización queda registrada en la key al crearla y se verifica en cada solicitud. Las dos keys de bootstrap son la única excepción: la key `admin` (inicializada desde `ADMIN_KEY`) y la key `dashboard-assistant` (inicializada desde `AGENT_API_KEY`) tienen **alcance de instancia** (no llevan organización). El dashboard se autentica con la key `admin` para poder actuar como proxy de solicitudes por organización en nombre de los miembros autenticados. Los despliegues de un solo tenant no necesitan pensar en esto; todas las keys pertenecen a la organización `default` predefinida. --- -## Crear claves +## Crear keys -Usa la clave admin (o cualquier clave con permiso `keys:create`) para crear claves adicionales con ámbito. +Usa la admin key (o cualquier key con permiso `keys:create`) para crear keys adicionales con alcance limitado. -### Clave de collector (solo ingesta) +### Collector key (solo ingestión) ```bash curl -s -X POST http://your-server/keys \ @@ -180,7 +180,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### Clave de dashboard (solo lectura) +### Dashboard key (solo lectura) ```bash curl -s -X POST http://your-server/keys \ @@ -193,7 +193,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -Cuando creas una clave a través de la API HTTP, tú mismo proporcionas el valor de `key`; elige un secreto robusto y guárdalo de forma segura. (El dashboard funciona al revés: genera un secreto robusto por ti y lo muestra una sola vez al crearlo; ver [Gestión de claves en el dashboard](#key-management-in-the-dashboard).) La respuesta confirma que la clave fue creada: +Cuando creas una key a través de la API HTTP, tú mismo proporcionas el valor de `key`; elige un secreto robusto y guárdalo de forma segura. (El dashboard funciona al revés: genera un secreto robusto por ti y lo muestra una sola vez al crearlo; ver [Gestión de keys en el dashboard](#key-management-in-the-dashboard).) La respuesta confirma que la key fue creada: ```json { @@ -206,20 +206,20 @@ Cuando creas una clave a través de la API HTTP, tú mismo proporcionas el valor --- -## Listar claves +## Listar keys ```bash curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -Los secretos de las claves no se devuelven en las respuestas de listado; solo los IDs, nombres y permisos. +Los secretos de las keys no se devuelven en las respuestas de listado; solo se devuelven IDs, nombres y permisos. --- -## Deshabilitar una clave +## Deshabilitar una key -Deshabilitar revoca el acceso de inmediato sin eliminar el registro de la clave. +Deshabilitar revoca el acceso inmediatamente sin eliminar el registro de la key. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -228,53 +228,53 @@ curl -s -X POST http://your-server/keys//disable \ --- -## Regenerar una clave +## Regenerar una key -Genera un nuevo secreto para una clave existente. El secreto anterior se invalida de inmediato. +Genera un nuevo secreto para una key existente. El secreto antiguo se invalida inmediatamente. ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -La respuesta incluye el nuevo secreto en texto plano, **mostrado solo una vez**. +La respuesta incluye el nuevo secreto en texto plano, **mostrado una sola vez**. --- -## Gestión de claves en el dashboard +## Gestión de keys en el dashboard -La página **Keys** del dashboard proporciona una interfaz de usuario para todas las operaciones anteriores. Necesitas una clave con permiso `keys:read` para ver el listado, y `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` para las acciones de crear / editar / deshabilitar / regenerar respectivamente. Editar los permisos de una clave (`keys:update`) es independiente de crearla (`keys:create`), por lo que puedes otorgar a un operador la capacidad de crear claves sin la capacidad de cambiar el ámbito de las existentes, o viceversa. La clave admin cubre todas estas acciones. +La página **Keys** del dashboard ofrece una interfaz para todas las operaciones anteriores. Necesitas una key con permiso `keys:read` para ver el listado, y `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` para las acciones de crear / editar / deshabilitar / regenerar, respectivamente. Editar los permisos de una key (`keys:update`) es independiente de crearla (`keys:create`), por lo que puedes conceder a un operador la capacidad de crear keys sin la capacidad de modificar el alcance de las existentes, o viceversa. La admin key cubre todas estas acciones. -Cuando creas una clave desde el dashboard no proporcionas el secreto; el dashboard genera un secreto robusto por ti y lo muestra **una sola vez** al crearlo. Cópialo de inmediato y guárdalo de forma segura; nunca se vuelve a mostrar, exactamente igual que con una regeneración. Puedes seguir seleccionando los permisos de la clave directamente, o inicializarlos desde un conjunto de permisos (ver más abajo). +Cuando creas una key desde el dashboard no suministras el secreto; el dashboard genera un secreto robusto por ti y lo muestra **una sola vez** al crearlo. Cópialo inmediatamente y guárdalo de forma segura; no se vuelve a mostrar nunca, exactamente igual que al regenerar. Aun así puedes elegir los permisos de la key directamente, o inicializarlos desde un conjunto de permisos (ver más abajo). -![La página API Keys: una tarjeta por clave con su nombre, permisos otorgados y fecha de creación, con acciones de regenerar y deshabilitar; las claves protegidas como `admin` están marcadas](/agenteye/images/api-keys.png) +![La página API Keys: una tarjeta por key mostrando su nombre, permisos concedidos y fecha de creación, con acciones de regeneración y deshabilitación; las keys protegidas como `admin` están marcadas](/agenteye/images/api-keys.png) --- -## Distribución recomendada de claves +## Layout de keys recomendado -| Clave | Permisos | Usada por | +| Key | Permisos | Usada por | |---|---|---| -| `admin` (bootstrap mediante la variable de entorno `ADMIN_KEY`) | todos | Operaciones/configuración, y el dashboard (se autentica con `ADMIN_KEY`, proxia solicitudes de usuarios con verificaciones de permisos) | -| Clave de collector por host | `events:add` | Collector en cada máquina agente | -| `dashboard-assistant` (bootstrap mediante la variable de entorno `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Asistente de IA, inicializado automáticamente, **protegido**; no puede editarse a través de la API | -| Clave de telemetría del asistente (opcional) | `events:add` | Auto-instrumentación del asistente de IA, si está habilitada | +| `admin` (bootstrap mediante la variable de entorno `ADMIN_KEY`) | todos | Operaciones/configuración, y el dashboard (se autentica con `ADMIN_KEY`, actúa como proxy de solicitudes de usuario con comprobaciones de permisos) | +| Collector key por host | `events:add` | Colector en cada máquina agente | +| `dashboard-assistant` (bootstrap mediante la variable de entorno `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Asistente de IA, inicializado automáticamente, **protegida**; no se puede editar a través de la API | +| Telemetría del asistente (opcional) | `events:add` | Auto-instrumentación del asistente de IA, si está habilitada | -> **Nota:** La clave del asistente se **inicializa automáticamente** por el servidor desde la variable de entorno `AGENT_API_KEY` (el mismo secreto que el agente presenta como `AGENTEYE_API_KEY`); no hay un paso manual de creación de clave ni se involucra la clave admin. Sus permisos están fijos en el código fuente para que el ámbito no pueda ampliarse por una mala configuración: lectura sobre eventos / evaluaciones / dashboards, más escritura de dashboards y lectura / escritura / ejecución de consultas para el flujo de autoría "Pídele a la IA que escriba una consulta". Todo el SQL sigue pasando por el mismo rol de solo lectura y la misma ruta de SQL protegido que una consulta escrita por un usuario, por lo que esto amplía la *superficie de autoría*, no la superficie de datos; las operaciones destructivas (`queries:delete`, `dashboards:delete`) se excluyen deliberadamente de la clave del asistente. Al igual que la clave `admin`, está **protegida**: no puede deshabilitarse ni regenerarse a través de la API de claves, solo rotarse cambiando `AGENT_API_KEY` y reiniciando. Los *usuarios* del dashboard también necesitan el permiso `agent:use` para ver y usar el asistente. Si habilitas la auto-instrumentación, dale al asistente una clave separada con solo `events:add`. +> **Nota:** La key del asistente es **inicializada automáticamente** por el servidor desde la variable de entorno `AGENT_API_KEY` (el mismo secreto que el agente presenta como `AGENTEYE_API_KEY`); no hay ningún paso de creación manual de key ni se involucra la admin key. Sus permisos están fijados en el código fuente para que el alcance no pueda ampliarse por error de configuración: lectura de eventos / evaluaciones / dashboards, más escritura de dashboards y lectura / escritura / ejecución de consultas para el flujo de autoría de "Pide a la IA que escriba una consulta". Todo el SQL sigue pasando por el mismo rol de solo lectura y la misma ruta SQL protegida que una consulta escrita por el usuario, por lo que esto amplía la *superficie de autoría*, no la superficie de datos; las operaciones destructivas (`queries:delete`, `dashboards:delete`) se mantienen deliberadamente fuera de la key del asistente. Al igual que la key `admin`, está **protegida**: no se puede deshabilitar ni regenerar a través de la keys API, solo rotarla cambiando `AGENT_API_KEY` y reiniciando. Los *usuarios* del dashboard además necesitan el permiso `agent:use` para ver y usar el asistente. Si habilitas la auto-instrumentación, dale al asistente una key separada solo con `events:add`. --- -## Notas de actualización y compatibilidad con versiones anteriores +## Notas de actualización y compatibilidad -Solo necesitas estas notas si estás actualizando una instancia existente; los nuevos despliegues pueden omitirlas. +Solo necesitas esto si estás actualizando una instancia existente; los nuevos despliegues pueden omitirlo. -> Cuando se lanzó Audits, los titulares existentes fueron ampliados siguiendo las mismas formas de rol que las alertas: cada usuario y conjunto de permisos que tenía `alerts:read` obtuvo `audits:read`, y cada titular de `alerts:write` obtuvo `audits:write`. Las API keys existentes **no** fueron ampliadas. Otorga `audits:*` a una clave explícitamente si necesita acceso a la superficie de auditorías. +> Cuando se lanzaron las Auditorías, los beneficiarios existentes se ampliaron siguiendo los mismos perfiles de rol que las alertas: cada usuario y conjunto de permisos que tenía `alerts:read` obtuvo `audits:read`, y cada titular de `alerts:write` obtuvo `audits:write`. Las API keys existentes **no** se ampliaron. Concede `audits:*` a una key explícitamente si necesita acceso a la superficie de auditorías. -> Los otorgamientos almacenados del token heredado `alerts:ack` se interpretan como `incidents:ack` para que los operadores de guardia conserven el acceso sin necesidad de regenerar claves. El token ya no se puede asignar desde el editor de usuarios del dashboard; la matriz ofrece `incidents:ack` en su lugar. +> Las concesiones almacenadas del token heredado `alerts:ack` se interpretan como `incidents:ack` para que los operadores de guardia conserven el acceso sin necesidad de regenerar keys. El token ya no es asignable desde el editor de usuarios del dashboard; la matriz ofrece `incidents:ack` en su lugar. --- ## Próximos pasos -- [SDK de Python](/es/agenteye/python-sdk): cómo se autentica el código de tu agente al enviar eventos. -- [Seguridad](/es/agenteye/security): cómo funcionan el inicio de sesión, el control de acceso y el aislamiento de datos por organización. \ No newline at end of file +- [Python SDK](/es/agenteye/python-sdk): cómo se autentica el código de tu agente al enviar eventos. +- [Security](/es/agenteye/security): cómo funcionan el inicio de sesión, el control de acceso y el aislamiento de datos por organización. \ No newline at end of file diff --git a/docs/es/agenteye/assistant.mdx b/docs/es/agenteye/assistant.mdx index c66f3058..2933c96f 100644 --- a/docs/es/agenteye/assistant.mdx +++ b/docs/es/agenteye/assistant.mdx @@ -1,13 +1,13 @@ --- title: "Asistente de IA" -description: "Haz una pregunta en lenguaje natural sobre los datos de tu agente y obtén una respuesta vinculada directamente a la evidencia." +description: "Hazle una pregunta a tus datos de agente en lenguaje natural y obtén una respuesta vinculada directamente a la evidencia." --- -Haz una pregunta en lenguaje natural sobre los datos de tu agente y obtén una respuesta vinculada directamente a la evidencia. Sin SQL que escribir, sin dashboards que explorar — el asistente de **Failproof AI Observability** es la forma más rápida para que cualquier miembro de tu equipo obtenga respuestas sobre sus agentes. +Hazle una pregunta a tus datos de agente en lenguaje natural y obtén una respuesta vinculada directamente a la evidencia. Sin SQL que escribir ni dashboards que explorar — el asistente de **Failproof AI Observability** es la forma más rápida para cualquier miembro de tu equipo de obtener respuestas sobre sus agentes. -![El asistente de Failproof AI Observability respondiendo una pregunta en lenguaje natural dentro del dashboard, mostrando una tabla de actividad de agentes en vivo, un desglose de uso de modelos por agente y conclusiones escritas, con las consultas ejecutadas mostradas inline](/agenteye/images/assistant.png) -*Pregunta en lenguaje natural y obtén una respuesta construida a partir de tus propios datos. Aquí desglosa qué agentes están más activos y qué modelos usan, y muestra las consultas que ejecutó para que puedas verificar cada número.* +![El asistente de Failproof AI Observability respondiendo una pregunta en lenguaje natural dentro del dashboard, mostrando una tabla de actividad de agentes en vivo, un desglose del uso de modelos por agente y conclusiones escritas, con las consultas ejecutadas mostradas de forma inline](/agenteye/images/assistant.png) +*Pregunta en lenguaje natural y obtén una respuesta construida a partir de tus propios datos. Aquí desglosa qué agentes están más ocupados y qué modelos utilizan, y muestra las consultas que ejecutó para que puedas verificar cada número.* No hay nada que aprender. Abre el chat, escribe lo que quieres saber y sigue los enlaces que te devuelve: @@ -24,40 +24,40 @@ AI: This run took 12 steps across 3 tools and failed near the end when a Links: the session, the failing event, and that evaluation. ``` -## Solo pregunta y ve directo a la prueba +## Solo pregunta y salta directamente a la prueba -Dejas de adivinar y de escribir consultas. Pregunta "¿cómo está evolucionando la calidad en producción esta semana?", "¿qué sesiones dieron error hoy?" o "resume esta sesión", y obtienes una respuesta directa en segundos, en lugar de construir una consulta y leerla tú mismo. +Dejas de adivinar y de escribir consultas. Pregunta "¿cómo está evolucionando la calidad en producción esta semana?", "¿qué sesiones tuvieron errores hoy?" o "resume esta sesión", y obtienes una respuesta directa en segundos en lugar de construir una consulta y leerla tú mismo. -Cada respuesta viene con sus justificantes. El asistente enlaza las sesiones exactas, las consultas guardadas y los dashboards que utilizó para llegar a la respuesta, para que puedas hacer clic y confirmar en lugar de tomar su palabra como válida. También es **consciente del contexto de la página**: pregunta sobre "esta sesión" mientras la estás viendo y ya sabe a qué ejecución te refieres. Vuelve a abrir cualquier conversación anterior desde el selector de historial y retoma donde lo dejaste. +Cada respuesta viene con sus comprobantes. El asistente enlaza las sesiones exactas, las consultas guardadas y los dashboards que utilizó para llegar a la respuesta, de modo que puedas hacer clic y confirmar en lugar de fiarte de su palabra. Además, es **consciente del contexto de página**: pregunta sobre "esta sesión" mientras la estás viendo y ya sabe a qué ejecución te refieres. Reabre cualquier conversación anterior más tarde desde el selector de historial y retoma donde lo dejaste. ## Convierte una buena respuesta en una consulta guardada o un dashboard -Cuando una respuesta vale la pena conservar, pídele al asistente que la guarde. Redacta el SQL para una consulta guardada, o ensambla un dashboard a partir de esas consultas, y luego te muestra una tarjeta de **Aprobar / Rechazar**. Nada se escribe hasta que hagas clic en Aprobar, por lo que obtienes la velocidad de "solo pregunta" con la última decisión siempre en tus manos. +Cuando una respuesta vale la pena conservar, pídele al asistente que la guarde. Redacta el SQL para una consulta guardada o ensambla un dashboard a partir de esas consultas, y luego te muestra una tarjeta de **Aprobar / Rechazar**. No se escribe nada hasta que hagas clic en Aprobar, así que obtienes la velocidad del "solo pregunta" con la última palabra siempre en tus manos. -En la página de **Queries** va un paso más allá y se convierte en autor de SQL: describe la consulta que quieres ("muestra la tasa de errores por agente durante los últimos 7 días") y transmite SQL directamente al editor, abriendo una vista de diferencias para que puedas **Aceptar** o **Rechazar** el cambio antes de que se aplique. +En la página de **Queries** va un paso más allá y se convierte en autor de SQL: describe la consulta que quieres ("mostrar la tasa de errores por agente en los últimos 7 días") y transmite SQL directamente al editor, abriendo una vista de diferencias para que puedas **Aceptar** o **Rechazar** el cambio antes de que se aplique. -![La página Queries de Observability y su editor SQL](/agenteye/images/query-lab.png) +![La página de Queries de Observability y su editor de SQL](/agenteye/images/query-lab.png) *La página Queries: este editor es donde el asistente transmite un borrador de consulta de solo lectura para que lo aceptes o rechaces.* -Crear SQL mediante preguntas aquí usa el permiso `queries:run`, el mismo que hay detrás del botón **Run** del editor. El chat en cualquier otro lugar necesita `agent:use`. +Redactar SQL preguntando aquí utiliza el permiso `queries:run`, el mismo que está detrás del botón **Run** del editor. El chat en cualquier otro lugar requiere `agent:use`. -## Seguro para todo el equipo +## Seguro para toda la organización -Puedes abrir el asistente a todos sin preocuparte por lo que podría tocar: +Puedes abrirle el asistente a todos sin preocuparte por lo que podría tocar: - **Solo lee lo que tú ya puedes ver.** Las respuestas están limitadas a tus propios permisos de lectura, por lo que nunca amplía tu superficie de datos. -- **Cada escritura espera tu confirmación.** Las consultas guardadas y los dashboards solo se crean tras tu clic explícito en Aprobar, y no existe ninguna configuración que desactive esa barrera. -- **Nunca puede eliminar nada.** No hay ninguna herramienta de eliminación expuesta y el asistente no tiene permiso de eliminación. Las eliminaciones permanecen en tus manos, en el dashboard. -- **Se mantiene dentro de tu organización.** El asistente solo ve la organización que estás visualizando en ese momento. -- **Tus preguntas son tuyas.** Los prompts y las respuestas viven en tu propia base de datos de Observability; los análisis del producto registran solo metadatos de uso, nunca el texto de tus prompts. +- **Cada escritura te espera a ti.** Las consultas guardadas y los dashboards se crean únicamente después de que hagas clic explícitamente en Aprobar, y no hay ninguna configuración que desactive esa barrera. +- **Nunca puede eliminar nada.** No hay ninguna herramienta de eliminación expuesta y el asistente no tiene permiso de eliminación. Las eliminaciones quedan en tus manos, en el dashboard. +- **Se mantiene dentro de tu organización.** El asistente solo ve en todo momento la organización que estás visualizando actualmente. +- **Tus preguntas son tuyas.** Los prompts y las respuestas viven en tu propia base de datos de Observability; el análisis de producto registra solo metadatos de uso, nunca el texto de tus prompts. ## Dónde encontrarlo -El asistente aparece en el borde derecho de cada página bajo tu organización (`//...`). Haz clic en el rail, o pulsa `⌘J` / `Ctrl+J`, para expandirlo al panel de chat completo, y arrastra su borde para redimensionarlo; tu anchura se recuerda entre recargas. Necesitas el permiso **`agent:use`** para usarlo; de lo contrario, el rail aparece en gris. Si todavía no se ha activado para tu despliegue (requiere una conexión LLM), verás un rail atenuado en lugar de un chat funcional. +El asistente aparece en el borde derecho de cada página bajo tu organización (`//...`). Haz clic en el carril o pulsa `⌘J` / `Ctrl+J` para expandirlo al panel de chat completo, y arrastra su borde para redimensionarlo; tu anchura se recuerda entre recargas. Necesitas el permiso **`agent:use`** para usarlo; de lo contrario, el carril aparecerá en gris. Si aún no está activado para tu despliegue (requiere una conexión LLM), verás un carril apagado en lugar de un chat funcional. ## Relacionado -- [CLI y agentes](/es/agenteye/cli-and-agents) +- [CLI and agents](/es/agenteye/cli-and-agents) - [Queries](/es/agenteye/queries) - [Dashboards](/es/agenteye/dashboards) -- [Suite de evaluación](/es/agenteye/evaluation-suite) \ No newline at end of file +- [Evaluation suite](/es/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/es/agenteye/audits.mdx b/docs/es/agenteye/audits.mdx index c7072e4f..3b6a0ad4 100644 --- a/docs/es/agenteye/audits.mdx +++ b/docs/es/agenteye/audits.mdx @@ -4,7 +4,7 @@ description: "Failproof AI Observability busca los fallos para los que nunca esc --- -Failproof AI Observability busca los fallos para los que nunca escribiste una regla y te entrega una lista priorizada de exactamente qué corregir, respaldada por evidencias. Es como tener un analista que revisa tus logs cada noche y te deja la lista corta sobre el escritorio antes de que empiece el día. +Failproof AI Observability busca los fallos para los que nunca escribiste una regla y te entrega una lista priorizada de exactamente qué corregir, respaldada por evidencias. Es como tener un analista que revisa tus logs cada noche y deja el resumen sobre tu escritorio por la mañana.
@@ -12,43 +12,43 @@ Failproof AI Observability busca los fallos para los que nunca escribiste una re *Un recorrido de dos minutos: desde una ejecución programada hasta una corrección sobre la que puedes actuar.* -![La página de Auditorías: trabajos recurrentes que analizan tus sesiones en busca de patrones de fallo, cada uno con una programación y sensibilidad](/agenteye/images/audits.png) -*Cada auditoría es un trabajo recurrente que examina tus sesiones y elabora recomendaciones priorizadas respaldadas por evidencias.* +![La página de Auditorías: tareas recurrentes que analizan tus sesiones en busca de patrones de fallo, cada una con un horario y una sensibilidad](/agenteye/images/audits.png) +*Cada auditoría es una tarea recurrente que analiza tus sesiones y elabora recomendaciones priorizadas y respaldadas por evidencias.* ## Deja de adivinar qué corregir a continuación -Las alertas detectan los problemas que ya sabías que debías vigilar. Las auditorías detectan los que no sabías. Según una cadencia que tú defines, una auditoría lee todas tus sesiones de agente y busca los patrones que vale la pena corregir, para que dediques tu tiempo a actuar sobre los hallazgos en lugar de desplazarte por los logs esperando detectarlos tú mismo. +Las alertas detectan los problemas que ya sabes que debes vigilar. Las auditorías detectan los que no. Con la cadencia que tú definas, una auditoría analiza todas tus sesiones de agente y busca los patrones que vale la pena corregir, para que dediques tu tiempo a actuar sobre los hallazgos en lugar de desplazarte por los logs con la esperanza de encontrarlos por tu cuenta. -Una sola ejecución ataca los modos de fallo que realmente rompen agentes en producción: +Una sola ejecución va tras los modos de fallo que realmente rompen los agentes en producción: -- **Clusters de errores**: el mismo fallo repitiéndose bajo una causa raíz común. -- **Deriva respecto a una línea base**: comportamiento que se aleja silenciosamente de una ventana conocida como buena. -- **Fallo de objetivo en transcripciones**: ejecuciones que técnicamente terminaron pero nunca cumplieron el objetivo. +- **Clústeres de errores**: el mismo fallo repitiéndose bajo una causa raíz común. +- **Deriva respecto a una línea base**: un comportamiento que se aleja silenciosamente de una ventana conocida y estable. +- **Fallo de objetivo en transcripciones**: ejecuciones que técnicamente terminaron pero nunca realizaron el trabajo. - **Uso incorrecto de herramientas**: la herramienta equivocada, argumentos incorrectos o bucles que consumen llamadas. -- **Equilibrio entre calidad y coste**: dónde estás pagando de más por una salida que podrías obtener más barato. -- **Brechas de cobertura**: comportamiento que ninguna evaluación ni alerta está vigilando. +- **Compensaciones entre calidad y coste**: dónde estás pagando de más por una salida que podrías obtener más barato. +- **Brechas de cobertura**: comportamientos que ninguna evaluación ni alerta está vigilando. -Tú decides con qué intensidad busca mediante un único ajuste de **sensibilidad** (baja, media o alta), para que tanto un agente de staging ruidoso como uno de producción bien controlado puedan sintonizarse a la señal que deseas. +Tú decides con qué profundidad analiza mediante un único ajuste de **sensibilidad** (baja, media o alta), para que tanto un agente de staging ruidoso como uno de producción bien controlado puedan ajustarse a la señal que deseas. -## Cada recomendación viene con pruebas +## Cada recomendación viene con sus pruebas -Nunca tendrás que aceptar un hallazgo por fe. Cada recomendación cita las sesiones exactas de las que proviene y el SQL que la descubrió, para que puedas abrir la evidencia y confirmar el problema con un clic en lugar de tener que reconstruir una afirmación. +Nunca tienes que aceptar un hallazgo por fe. Cada recomendación cita las sesiones exactas de las que proviene y el SQL que lo reveló, de modo que puedes abrir la evidencia y confirmar el problema con un clic en lugar de tener que desmenuzar una afirmación. -Cuando un hallazgo trata sobre una credencial filtrada, va un paso más allá y vincula los eventos individuales que coincidieron. Haz clic en uno y llegas a ese momento exacto en la sesión, ya seleccionado — no al inicio de una larga transcripción que desplazar. El enlace nombra el evento; nunca copia el secreto detectado en el hallazgo, de modo que leer un hallazgo no sea un segundo lugar donde tu credencial queda escrita. Si un evento ya no existe porque la sesión ha superado tu ventana de retención, la página lo indica claramente en lugar de dejarte preguntándote si hiciste clic en lo incorrecto. +Cuando un hallazgo trata sobre una credencial filtrada, va un paso más allá y enlaza los eventos individuales que coincidieron. Haz clic en uno y llegas a ese momento exacto en la sesión, ya seleccionado, no al comienzo de una larga transcripción por la que desplazarte. El enlace identifica el evento; nunca copia el secreto detectado en el hallazgo, así que leer un hallazgo no es otro lugar donde tu credencial queda registrada. Si un evento ya no existe porque la sesión ha superado tu ventana de retención, la página lo indica claramente en lugar de dejarte preguntándote si hiciste clic en algo incorrecto. -Eso es también lo que mantiene las auditorías honestas. El servidor verifica que cada sesión citada realmente existe y **descarta cualquier recomendación cuya evidencia no se sostenga**, de modo que la auditoría investiga pero nunca inventa. Lo que llega a tu lista es real, reproducible y está ordenado por impacto, con las ganancias más grandes al principio. +Esto es también lo que mantiene las auditorías honestas. El servidor verifica que cada sesión citada realmente existe y **descarta cualquier recomendación cuya evidencia no se sostenga**, de modo que la auditoría investiga pero nunca inventa. Lo que aparece en tu lista es real, reproducible y está priorizado por su importancia, con las mejoras más significativas al principio. ## Convierte una corrección en una salvaguarda -Corregir un problema es solo la mitad de la victoria. La otra mitad es asegurarse de que no pueda volver silenciosamente. Cada hallazgo incluye un **acceso directo con un clic que crea una alerta de recurrencia**, prellenada con un activador inicial sensato que puedes ajustar. Cierra el hallazgo, activa la alerta y la próxima vez que ese patrón reaparezca recibirás una notificación en lugar de redescubrirlo en una auditoría futura. +Corregir un problema es solo la mitad del trabajo. La otra mitad es asegurarse de que no pueda regresar silenciosamente. Cada hallazgo incluye un **acceso directo de un clic que crea un borrador de alerta de recurrencia**, prellenado con un disparador de inicio razonable que puedes ajustar. Cierra el hallazgo, activa la alerta, y la próxima vez que ese patrón reaparezca recibirás una notificación en lugar de redescubrirlo en una futura auditoría. ## Dónde encontrarlo -Las auditorías se encuentran en el panel de control en **`//audits`** (barra lateral en *analyze* → *audits*). Ver ejecuciones y hallazgos requiere **`audits:read`**; crear, editar y gestionar auditorías requiere **`audits:write`**. Define el alcance y la cadencia de una auditoría y pulsa **Run now** cuando quieras resultados inmediatos en lugar de esperar al siguiente ciclo programado. +Las auditorías se encuentran en el panel de control en **`//audits`** (barra lateral → *analyze* → *audits*). Ver ejecuciones y hallazgos requiere **`audits:read`**; crear, editar y clasificar auditorías requiere **`audits:write`**. Configura el alcance y la cadencia de una auditoría y, a continuación, pulsa **Run now** cuando quieras resultados de inmediato en lugar de esperar al siguiente pase programado. ## Relacionado - [Alertas](/es/agenteye/alerts): recibe una notificación en el momento en que se supera un umbral que ya conoces. -- [Evaluaciones](/es/agenteye/evaluations): puntúa cada ejecución para que las regresiones de calidad se detecten por sí solas. +- [Evaluaciones](/es/agenteye/evaluations): puntúa cada ejecución para que las regresiones de calidad salgan a la superficie por sí solas. - [Seguimiento de errores](/es/agenteye/error-tracking): agrupa y sigue los errores que lanzan tus agentes. -- [Incidentes](/es/agenteye/incidents): rastrea un problema que detecta una auditoría hasta su corrección. \ No newline at end of file +- [Incidentes](/es/agenteye/incidents): realiza el seguimiento de un problema que una auditoría descubre hasta su corrección. \ No newline at end of file diff --git a/docs/es/agenteye/cli-and-agents.mdx b/docs/es/agenteye/cli-and-agents.mdx index 8c9aba70..380d69fd 100644 --- a/docs/es/agenteye/cli-and-agents.mdx +++ b/docs/es/agenteye/cli-and-agents.mdx @@ -1,80 +1,80 @@ --- title: "CLI" -description: "Todo tu despliegue de Failproof AI Observability, a un comando de distancia." +description: "Todo tu despliegue de Failproof AI Observability, a un solo comando de distancia." --- -Todo tu despliegue de Failproof AI Observability, a un comando de distancia. Revisa producción, genera una clave de API o reconoce un incidente sin salir de tu terminal, luego automatiza cualquiera de estas acciones en CI, o deja que un agente de código lo haga por ti en lenguaje natural. +Todo tu despliegue de Failproof AI Observability, a un solo comando de distancia. Verifica producción, genera una clave de API o reconoce un incidente sin salir de tu terminal, luego automatiza cualquiera de estas acciones en CI, o deja que un agente de codificación lo haga por ti en lenguaje natural. ```bash pipx install agenteye -agenteye login --email you@example.com # a 6-digit code lands in your inbox -agenteye --json sessions --since 24h # every agent run from the last day, newest first +agenteye login --email tu@ejemplo.com # un código de 6 dígitos llega a tu bandeja de entrada +agenteye --json sessions --since 24h # cada ejecución de agente del último día, más reciente primero ``` -*El CLI `agenteye` se comunica con tu dashboard. Es una herramienta distinta al colector, que envía eventos al servidor.* +*El CLI `agenteye` se comunica con tu panel de control. Es una herramienta distinta del colector, que envía eventos al servidor.* -## Todo tu despliegue, a un comando de distancia +## Todo tu despliegue, a un solo comando de distancia -Deja de cambiar de pestaña para responder una pregunta rápida. El CLI `agenteye` lee tus datos y administra tu organización desde un único binario, de modo que una verificación que antes requería navegar por el dashboard se convierte en una línea que puedes volver a ejecutar, crear un alias o pegar en un runbook. Dispones de cuatro áreas: +Deja de saltar entre pestañas para responder una pregunta rápida. El CLI `agenteye` lee tus datos y administra tu organización desde un único binario, de modo que una verificación que antes requería navegar por el panel de control se convierte en una sola línea que puedes volver a ejecutar, crear como alias o pegar en un runbook. Tienes cuatro áreas de acción: - **Lee tus datos:** `sessions`, `events`, `evals` y `errors`, filtrados por tiempo, agente y entorno. - **Administra tu organización:** `keys`, `users`, `settings`, `alerts` e `incidents`. -- **Ejecuta análisis:** SQL guardado y un ejecutor `query` ad hoc sobre tus datos de eventos. -- **Consulta al asistente:** `agent ask` accede al mismo analista de solo lectura con el que conversas en el dashboard. +- **Ejecuta análisis:** SQL guardado más un ejecutor `query` ad-hoc sobre tus datos de eventos. +- **Consulta al asistente:** `agent ask` accede al mismo analista de solo lectura con el que chateas en el panel de control. -Instálalo una vez con `pipx`, inicia sesión con un código de 6 dígitos enviado por correo, y ya estás listo. La sesión dura aproximadamente un día; vuelve a ejecutar `agenteye login` cuando expire. Úsalo para revisar producción a fondo, aprovisionar una clave o clasificar un incidente activo, todo sin abrir un navegador: +Instálalo una vez con `pipx`, inicia sesión con un código de 6 dígitos enviado por correo electrónico y ya estás listo. La sesión dura aproximadamente un día; vuelve a ejecutar `agenteye login` cuando expire. Úsalo para verificar producción, aprovisionar una clave o clasificar un incidente activo, todo sin abrir un navegador: ```bash -agenteye errors --since 24h --aggregate # what is breaking, grouped by error type -agenteye incidents list --state firing # what is on fire right now -agenteye keys create ci --add events:add # a key that can only push events, secret shown once +agenteye errors --since 24h --aggregate # qué está fallando, agrupado por tipo de error +agenteye incidents list --state firing # qué está en llamas ahora mismo +agenteye keys create ci --add events:add # una clave que solo puede enviar eventos, el secreto se muestra una vez ``` -Un hábito importante: las opciones globales como `--json` van antes del comando. `agenteye --json sessions` es correcto; `agenteye sessions --json`, no. +Un hábito importante a recordar: las opciones globales como `--json` van antes del comando. `agenteye --json sessions` es correcto; `agenteye sessions --json` no lo es. -## Automatízalo, intégralo en CI +## Automatízalo e intégralo en CI -Cada comando acepta `--json`, y eso lo cambia todo. El JSON limpio va a stdout mientras los mensajes de estado y advertencias van a stderr, por lo que una captura con `--json` se puede pasar directamente a `jq` sin necesidad de limpiar líneas adicionales. Esto hace que el CLI sea igual de útil tanto para ti en la terminal como para un agente de código que procesa la salida: +Cada comando acepta `--json`, y eso lo cambia todo. El JSON limpio va a stdout mientras los mensajes de estado y advertencias para humanos van a stderr, por lo que una captura con `--json` se canaliza directamente a `jq` sin ninguna línea adicional que eliminar. Eso es lo que hace que el CLI sea igual de útil para ti en un terminal y para un agente de codificación que analiza la salida: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -Está diseñado para ejecutarse de forma desatendida. Las confirmaciones se omiten automáticamente cuando no hay terminal conectada, así que nada queda bloqueado en un pipeline, y cada comando devuelve un código de salida significativo: `0` éxito, `4` no autenticado, `5` permiso faltante (el mensaje lo indica, por ejemplo `alerts:write`), `3` dashboard inaccesible. Un script puede bifurcarse en un `4` para reautenticarse o en un `5` para saber exactamente qué solicitar a un administrador, en lugar de fallar sin información. +Está diseñado para ejecutarse de forma desatendida. Los prompts de confirmación se omiten automáticamente cuando no hay una terminal conectada, por lo que nada se bloquea en un pipeline, y cada comando devuelve un código de salida significativo: `0` éxito, `4` no has iniciado sesión, `5` falta un permiso (el mensaje lo indica, por ejemplo `alerts:write`), `3` panel de control inalcanzable. Un script puede ramificarse ante un `4` para reautenticarse o ante un `5` para indicarte exactamente qué solicitar a un administrador, en lugar de fallar sin información. -## Deja que un agente de código lo maneje en lenguaje natural +## Deja que un agente de codificación lo controle en lenguaje natural -Mejor aún, no deberías tener que recordar ninguna de estas opciones. El **CLI skill** es una pequeña carpeta de Agent Skill llamada `agenteye-cli` que enseña a un agente de código como Claude Code o Codex a manejar el CLI mediante solicitudes en lenguaje natural. Pregunta "¿hay algo roto hoy?" y el agente selecciona el comando, lo ejecuta como tú y responde en prosa. +Mejor aún, no deberías tener que recordar ninguno de estos parámetros. El **CLI skill** es una pequeña carpeta de Agent Skill llamada `agenteye-cli` que enseña a un agente de codificación como Claude Code o Codex a controlar el CLI a partir de solicitudes en lenguaje natural. Pregunta "¿hay algo roto hoy?" y el agente elige el comando, lo ejecuta como tú y responde en prosa. -Para Claude Code, coloca la carpeta `agenteye-cli` en `~/.claude/skills/` y se descubre automáticamente. Failproof AI Observability proporciona la carpeta; no hay nada extra que instalar, ya que solo controla el CLI que ya tienes instalado. Inicia sesión tú mismo primero: el skill no puede completar el inicio de sesión con código enviado por correo en tu lugar. +Para Claude Code, coloca la carpeta `agenteye-cli` en `~/.claude/skills/` y se detecta automáticamente. Failproof AI Observability proporciona la carpeta; no hay nada adicional que instalar, ya que solo controla el CLI que ya instalaste. Inicia sesión tú mismo primero: el skill no puede completar el inicio de sesión con el código enviado por correo electrónico por ti. -Como el agente ejecuta el CLI como tú, puede hacer todo lo que tu sesión permite, tanto lecturas como escrituras: crear claves, cambiar configuraciones, resolver incidentes. La confirmación interactiva del CLI no se activa para un agente, por lo que el skill está diseñado para indicar el comando exacto y esperar tu aprobación antes de cualquier cambio. Tú eres el paso de confirmación. +Como el agente ejecuta el CLI como tú, puede hacer todo lo que tu inicio de sesión permita, tanto lecturas como escrituras: crear claves, cambiar configuraciones, resolver incidentes. El prompt de confirmación del CLI no se activa para un agente, por lo que el skill está diseñado para indicar el comando exacto y esperar tu aprobación antes de cualquier cambio. Tú eres el paso de confirmación. ```text -you Why did session run-001 fail? +tú ¿Por qué falló la sesión run-001? -agent Running: agenteye --json events --session-id run-001 --all - The checkout-agent hit a TimeoutError on its third tool call. +agente Ejecutando: agenteye --json events --session-id run-001 --all + El checkout-agent encontró un TimeoutError en su tercera llamada de herramienta. ``` -Las lecturas son inmediatas, y cada escritura se pausa esperando tu confirmación: +Las lecturas son instantáneas, y cada escritura hace una pausa para ti: ```text -you Give CI a key that can only push events. +tú Dale a CI una clave que solo pueda enviar eventos. -agent This creates an API key. I'll run: +agente Esto crea una clave de API. Ejecutaré: agenteye keys create ci --add events:add - OK to proceed? + ¿Procedo? -you yes +tú sí -agent Done. Key "ci" created with events:add only. The secret is shown once, so store it now. +agente Listo. Clave "ci" creada solo con events:add. El secreto se muestra una vez, así que guárdalo ahora. ``` ## Relacionado -- [Referencia del CLI](/es/agenteye/cli): cada comando, opción y estructura JSON. -- [Recetas del CLI para agentes](/es/agenteye/cli-recipes): patrones `jq` listos para usar y manejo de códigos de salida. -- [CLI agent skill](/es/agenteye/cli-skill): instala y ejecuta el skill `agenteye-cli`. -- [Asistente de IA](/es/agenteye/assistant): el analista integrado en el dashboard con el que `agent ask` se comunica. \ No newline at end of file +- [Referencia del CLI](/es/agenteye/cli): cada comando, parámetro y estructura JSON. +- [Recetas de CLI para agentes](/es/agenteye/cli-recipes): patrones `jq` listos para copiar y manejo de códigos de salida. +- [Skill del agente CLI](/es/agenteye/cli-skill): instala y ejecuta el skill `agenteye-cli`. +- [Asistente de IA](/es/agenteye/assistant): el analista integrado en el panel de control con el que `agent ask` se comunica. \ No newline at end of file diff --git a/docs/es/agenteye/cli-recipes.mdx b/docs/es/agenteye/cli-recipes.mdx index 4f1d8e35..9d25c698 100644 --- a/docs/es/agenteye/cli-recipes.mdx +++ b/docs/es/agenteye/cli-recipes.mdx @@ -1,76 +1,77 @@ --- title: "Recetas de CLI para agentes" -description: "Patrones de consulta y recetas de jq listos para copiar y pegar que convierten datos de sesiones, eventos y evaluaciones en algo que un script o agente de código puede automatizar." +description: "Patrones de consulta listos para copiar y pegar, y recetas de jq que convierten los datos de sesiones, eventos y evaluaciones en algo que un script o agente de código puede automatizar." --- -Extrae datos de sesiones, eventos y evaluaciones (y dispara reevaluaciones) directamente desde un script o agente de código, con JSON limpio en stdout que se puede redirigir a `jq`. Estas recetas convierten los datos de Failproof AI Observability en algo que un usuario de terminal o un agente de código de IA (Claude Code, Cursor) puede consultar y automatizar, sin necesidad de navegar por el panel. -Los patrones que se muestran a continuación están listos para copiar y pegar en la CLI de Failproof AI Observability (`agenteye`). Para la instalación, autenticación y la lista completa de opciones, consulta [CLI](/es/agenteye/cli); ejecuta `agenteye -h` o `agenteye -h` para ver la ayuda integrada. +Extrae datos de sesiones, eventos y evaluaciones (y activa reevaluaciones) directamente desde un script o agente de código, con JSON limpio en stdout que se puede canalizar directamente a `jq`. Estas recetas convierten los datos de Failproof AI Observability en algo que un usuario de terminal o un agente de código con IA (Claude Code, Cursor) puede consultar y automatizar, sin necesidad de navegar por el dashboard. + +Los patrones siguientes están listos para copiar y pegar en la CLI de Failproof AI Observability (`agenteye`). Para la instalación, la autenticación y la lista completa de opciones, consulta [CLI](/es/agenteye/cli); ejecuta `agenteye -h` o `agenteye -h` para ver la ayuda integrada. ## Reglas de oro -1. **Las opciones globales van *antes* del comando.** `agenteye --json sessions` es correcto; `agenteye sessions --json` no lo es. Las opciones globales son `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Usa `--json` siempre que vayas a parsear la salida.** Los datos van a **stdout** como JSON; los mensajes de estado e errores van a **stderr**, por lo que stdout permanece limpio para redirigir a `jq`. -3. **Ramifica según el código de salida**, no según el texto de stderr: `0` correcto · `1` error inesperado · `2` argumentos incorrectos · `3` no se puede conectar al panel · `4` no autenticado o sesión expirada · `5` permiso insuficiente · `6` recurso no encontrado. +1. **Las opciones globales van *antes* del comando.** `agenteye --json sessions` es correcto; `agenteye sessions --json` no lo es. Las globales son `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Pasa `--json` siempre que analices la salida.** Los datos van a **stdout** como JSON; los mensajes de estado e errores van a **stderr**, por lo que stdout permanece limpio para canalizar a `jq`. +3. **Ramifica según el código de salida**, no según el texto de stderr: `0` correcto · `1` error inesperado · `2` argumentos incorrectos · `3` no se puede alcanzar el dashboard · `4` no autenticado o sesión expirada · `5` permiso insuficiente · `6` recurso no encontrado. 4. **Explora con `-h`.** Cada comando documenta sus filtros, formatos de valores y estructura JSON. ## Configuración inicial ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # para no repetir --base-url -agenteye login --email you@example.com # pega el código recibido por email; válido ~24h +agenteye login --email you@example.com # pega el código enviado por email; válido ~24h ``` ## Verifica la autenticación antes de trabajar -`whoami` nunca falla por una sesión ausente o expirada; en su lugar reporta `logged_in:false`, por lo que un agente puede verificar el estado de autenticación de forma segura. (Puede seguir saliendo con código distinto de cero si no hay URL base configurada o el panel no está accesible.) +`whoami` nunca falla por una sesión ausente o expirada; en su lugar, reporta `logged_in:false`, por lo que un agente puede comprobar el estado de autenticación de forma segura. (Aún puede salir con código distinto de cero si no se ha configurado una URL base o el dashboard no es accesible.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then - echo "Not authenticated. Run: agenteye login" >&2; exit 1 + echo "No autenticado. Ejecuta: agenteye login" >&2; exit 1 fi ``` -## Busca sesiones fallidas o con puntuación baja +## Encuentra sesiones fallidas o con puntuación baja ```bash -# sesiones de las últimas 24h cuya evaluación tuvo error +# sesiones en las últimas 24h cuya evaluación tuvo error agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# evaluaciones con puntuación <= 0.5 en helpfulness, para un agente concreto +# evaluaciones con puntuación <= 0.5 en helpfulness, para un agente agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` El filtrado por puntuación está en **`evals`**, no en `sessions`. `--score KEY:MIN..MAX` es repetible y se combina con AND; cualquiera de los límites es opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puedes pasar hasta 20 filtros de puntuación por solicitud; más devuelve HTTP 400. `sessions` comparte los filtros `--env`, `--status`, `--agent-id`, `--session-id` y de rango temporal con `evals`, pero no tiene `--score`. -## Lee una sesión completa de principio a fin +## Lee una sesión de principio a fin -No existe un único comando `session show`. Combina el registro de eventos con la evaluación de la sesión: +No existe un único comando `session show`. Combina el historial de eventos con la evaluación de la sesión: ```bash # la evaluación más reciente de la sesión (estado + puntuaciones) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# todos los eventos de la ejecución (aumenta --limit para un barrido completo) +# todos los eventos de la ejecución (aumenta --limit para un recorrido completo) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# solo las llamadas a herramientas de una sesión (--full es necesario para obtener el payload bruto) +# solo las llamadas a herramientas en una sesión (--full es necesario para obtener el payload en bruto) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **Nota:** Por defecto, `events` lee un feed rápido sin payload. Cada evento incluye un `summary` de una línea calculado por el servidor, además de flags como `is_error` y contadores de tokens, pero `payload` se devuelve como `{}`. Para obtener el payload bruto, añade `--full` (o `--fields payload`). El feed completo es más lento a escala, así que mantenlo acotado: combina `--full` con un único `--session-id`. +> **Nota:** Por defecto, `events` lee un feed rápido sin payload. Cada evento incluye un `summary` de una línea calculado por el servidor, más indicadores como `is_error` y conteos de tokens, pero `payload` se devuelve como `{}`. Para obtener el payload en bruto, añade `--full` (o `--fields payload`). El feed completo es más lento a escala, así que mantenlo acotado: combina `--full` con un único `--session-id`. -## Obtén todos los datos (paginación) +## Obtén todo (paginación) -Los resultados se ordenan del más reciente al más antiguo y se pagina con cursor. +Los resultados están ordenados del más reciente al más antiguo y se paginan con cursor. ```bash -# de una vez: obtiene hasta 500 filas en páginas de 200 +# una sola solicitud: obtén hasta 500 filas en páginas de 200 agenteye --json events --session-id run-001 --limit 500 --all > events.json -# paginación manual: realimenta next_cursor +# paginación manual: reutiliza next_cursor page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -78,26 +79,26 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## Reduce la salida con --fields -Restringe las claves (tanto en la tabla como con `--json`) para reducir lo que un agente debe leer. +Restringe las claves (tanto en la tabla como en `--json`) para reducir lo que un agente debe leer. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Los nombres de campo desconocidos se rechazan (salida `2`) con la lista de campos válidos, una forma sencilla de descubrir los nombres disponibles. +Los nombres de campo desconocidos se rechazan (salida `2`) con la lista válida, una forma rápida de descubrir nombres de campo. ## Descubre los valores válidos de los filtros ```bash agenteye --json list envs | jq -r '.values[]' # valores para --env agenteye --json list tools | jq -r '.values[]' # nombres de herramientas; también agents, models, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # KEY válido para --score KEY:MIN..MAX +agenteye --json list score_filters | jq -r '.values[]' # KEY válida para --score KEY:MIN..MAX ``` -## Elige tu organización (multi-tenant) +## Selecciona tu organización (multi-tenant) -Si perteneces a más de una organización, selecciona el tenant activo al iniciar sesión (se guarda): +Si perteneces a más de una organización, elige el tenant activo al iniciar sesión (se guarda): ```bash agenteye login --org acme --email you@corp.com # establece el tenant en el mismo paso que el login @@ -105,14 +106,14 @@ agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # anula para un solo comando ``` -Un inicio de sesión multi-organización sin `--org` termina con código distinto de cero e imprime las organizaciones disponibles para elegir. +Un login multi-organización sin `--org` termina con código distinto de cero y muestra las organizaciones disponibles para elegir. ## Provisiona una clave API para el SDK/collector ```bash # el secreto se imprime UNA SOLA VEZ; con --json está en el campo .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # rotación; agenteye keys disable ci-bot --yes para revocar +agenteye keys regenerate ci-bot --yes # rota la clave; agenteye keys disable ci-bot --yes para revocarla ``` ## Ejecuta una consulta guardada o ad-hoc @@ -131,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **Nota:** Las mutaciones omiten automáticamente la confirmación cuando se usa `--json` o cuando stdin no es un TTY, por lo que los agentes nunca quedan bloqueados; usa `--yes`/`-y` para omitirla explícitamente en otros contextos. +> **Nota:** Las mutaciones omiten automáticamente su confirmación cuando se usa `--json` o cuando stdin no es un TTY, por lo que los agentes nunca se quedan bloqueados; pasa `--yes`/`-y` para omitirla explícitamente en otros contextos. ## Manejo de códigos de salida en un script @@ -139,25 +140,25 @@ agenteye incidents resolve "$id" --yes out=$(agenteye --json sessions --since 1h) || code=$? case "${code:-0}" in 0) echo "$out" | jq '.sessions | length' ;; - 4) echo "Session expired - run 'agenteye login'." >&2 ;; - 5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;; - 3) echo "Dashboard unreachable - check the URL." >&2 ;; - *) echo "Unexpected error (exit ${code})." >&2 ;; + 4) echo "Sesión expirada - ejecuta 'agenteye login'." >&2 ;; + 5) echo "Permiso insuficiente (pide al administrador el permiso evaluations:read)." >&2 ;; + 3) echo "Dashboard inaccesible - verifica la URL." >&2 ;; + *) echo "Error inesperado (salida ${code})." >&2 ;; esac ``` -## Estructuras de la salida JSON +## Estructuras de salida JSON | Comando | JSON en stdout (con `--json`) | |---|---| | `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` o `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | -| `events` | `{"events": [...], "next_cursor": }` | -| `evals` | `{"evaluations": [...], "next_cursor": }` | -| `sessions` | `{"sessions": [...], "next_cursor": }` | -| `errors` | `{"errors": [...], "next_cursor": }` | +| `events` | `{"events": [...], "next_cursor": }` | +| `evals` | `{"evaluations": [...], "next_cursor": }` | +| `sessions` | `{"sessions": [...], "next_cursor": }` | +| `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` se muestra una sola vez) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` se muestra solo una vez) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | @@ -168,11 +169,11 @@ esac - Cada elemento de **evaluación** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Cada elemento de **sesión** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -El argumento `--fields` de cada comando acepta exactamente los nombres de campo de su propio elemento. El conjunto varía entre `sessions` y `evals`, por lo que un nombre válido para uno puede ser rechazado por el otro. +El `--fields` de cada comando acepta exactamente los nombres de campo de su propio elemento. El conjunto difiere entre `sessions` y `evals`, por lo que un nombre válido para uno puede ser rechazado por el otro. ## Próximos pasos -- [CLI](/es/agenteye/cli): instalación, autenticación y la referencia completa de opciones para cada comando. -- [Skill de agente CLI](/es/agenteye/cli-skill): empaqueta estas recetas como una skill que tu agente de código pueda cargar. +- [CLI](/es/agenteye/cli): instalación, autenticación y referencia completa de opciones para cada comando. +- [Habilidad de agente CLI](/es/agenteye/cli-skill): empaqueta estas recetas como una habilidad que tu agente de código puede cargar. - [Claves API](/es/agenteye/api-keys): crea y limita el alcance de las claves con las que se autentican la CLI, el SDK y el collector. - [Python SDK](/es/agenteye/python-sdk): envía eventos a Failproof AI Observability para que haya datos que estas recetas puedan consultar. \ No newline at end of file diff --git a/docs/es/agenteye/cli-skill.mdx b/docs/es/agenteye/cli-skill.mdx index e0920f32..cc9f18d1 100644 --- a/docs/es/agenteye/cli-skill.mdx +++ b/docs/es/agenteye/cli-skill.mdx @@ -1,51 +1,51 @@ --- -title: "Habilidad de CLI para Observabilidad de Failproof AI" -description: "Pregúntale a tu agente de codificación «¿hay algo roto hoy?» y deja que responda con tus datos en vivo de Observabilidad de Failproof AI, sin comandos que memorizar." +title: "Habilidad de Agente CLI de Observabilidad de Failproof AI" +description: "Pregúntale a tu agente de programación «¿hay algo roto hoy?» y deja que responda con tus datos en vivo de Observabilidad de Failproof AI, sin comandos que memorizar." --- -Pregúntale a tu agente de codificación *«¿hay algo roto hoy?»* y deja que responda con tus datos en vivo de Observabilidad de Failproof AI, sin comandos que memorizar. La **habilidad de CLI de Observabilidad de Failproof AI** (`agenteye-cli`) es una *Agent Skill*: una pequeña carpeta de instrucciones que un agente de codificación como Claude Code o Codex carga bajo demanda. Le enseña al agente a operar tu despliegue de Observabilidad a través de la [`agenteye` CLI](/es/agenteye/cli) mediante solicitudes en lenguaje natural como *«dale a CI una clave que solo pueda enviar eventos»* o *«acepta el incidente activo y asígnamelo»*. +Pregúntale a tu agente de programación *«¿hay algo roto hoy?»* y deja que responda con tus datos en vivo de Observabilidad de Failproof AI, sin comandos que memorizar. La **habilidad CLI de Observabilidad de Failproof AI** (`agenteye-cli`) es una *Agent Skill*: una pequeña carpeta de instrucciones que un agente de programación como Claude Code o Codex carga bajo demanda. Le enseña al agente a operar tu despliegue de Observabilidad a través de la [`agenteye` CLI](/es/agenteye/cli) mediante solicitudes en lenguaje natural como *«dale a CI una clave que solo pueda enviar eventos»* o *«confirma el incidente activo y asígnamelo».* -**No** es un servicio ni un binario independiente; no hay nada que desplegar. Se apoya en la CLI que ya tienes instalada: el agente invoca `agenteye --json …`, analiza el JSON limpio resultante y te responde en prosa. Todo lo que puede hacer, tú también podrías hacerlo escribiendo los mismos comandos. +**No** es un servicio ni un binario separado; no hay nada que desplegar. Se apoya en la CLI que ya tienes instalada: el agente ejecuta `agenteye --json …`, analiza el JSON limpio y te responde en prosa. Todo lo que puede hacer, podrías hacerlo tú mismo escribiendo los mismos comandos. --- -## Relación con las demás interfaces de Observabilidad de Failproof AI +## Relación con las otras interfaces de Observabilidad de Failproof AI -Failproof AI Observability te ofrece cuatro formas de acceder a los mismos datos y controles. Se complementan entre sí: +Failproof AI Observabilidad te ofrece cuatro formas de acceder a los mismos datos y controles. Se complementan entre sí: | Interfaz | Qué es | Dónde se ejecuta | Úsala cuando | |---|---|---|---| | **[CLI](/es/agenteye/cli)** | La referencia de comandos y opciones de `agenteye` | Tu terminal | Quieres ejecutar o automatizar un comando específico | -| **[Recetas de CLI](/es/agenteye/cli-recipes)** | Patrones de `jq`/pipeline listos para copiar y pegar | Tu terminal / scripts | Estás integrando la CLI en automatizaciones | -| **Habilidad de CLI** (este doc) | Una puerta de entrada en lenguaje natural a la CLI | Tu agente de codificación, en tu estación de trabajo | Quieres *simplemente preguntar* y dejar que el agente elija el comando | -| **[Habilidad de evaluador](/es/agenteye/evaluator-skill)** | Una habilidad hermana que diseña y construye tu servicio de puntuación | Tu agente de codificación, en tu estación de trabajo | Quieres *producir* puntuaciones de evaluación en lugar de leerlas | -| **[Habilidad del SDK de Python](/es/agenteye/python-sdk-skill)** | Una habilidad hermana que instrumenta tu agente para que emita telemetría | Tu agente de codificación, en tu estación de trabajo | Quieres que tu agente *produzca* los eventos que esta habilidad lee | -| **[Asistente de IA en el dashboard](/es/agenteye/assistant)** | Un chat integrado en el dashboard | Del lado del servidor (en el dashboard) | Quieres hacer preguntas sobre tus datos dentro del dashboard | +| **[Recetas CLI](/es/agenteye/cli-recipes)** | Patrones `jq`/pipeline para copiar y pegar | Tu terminal / scripts | Estás integrando la CLI en automatizaciones | +| **Habilidad CLI** (este documento) | Una puerta de entrada en lenguaje natural a la CLI | Tu agente de programación, en tu estación de trabajo | Quieres *simplemente preguntar* y dejar que el agente elija el comando | +| **[Habilidad Evaluador](/es/agenteye/evaluator-skill)** | Una habilidad hermana que diseña y construye tu servicio de puntuación | Tu agente de programación, en tu estación de trabajo | Quieres *producir* puntuaciones de evaluación en lugar de leerlas | +| **[Habilidad Python SDK](/es/agenteye/python-sdk-skill)** | Una habilidad hermana que instrumenta tu agente para que emita telemetría | Tu agente de programación, en tu estación de trabajo | Quieres que tu agente *produzca* los eventos que esta habilidad lee | +| **[Asistente IA integrado en el dashboard](/es/agenteye/assistant)** | Un chat integrado en el dashboard | Del lado del servidor (en el dashboard) | Quieres preguntas y respuestas sobre tus datos dentro del dashboard | -La habilidad en sí no tiene privilegios propios; simplemente convierte tus palabras en llamadas a la CLI que se ejecutan como tú: +La habilidad en sí no tiene privilegios propios; simplemente transforma tus palabras en llamadas CLI que se ejecutan como tú: ```mermaid flowchart TD - YOU["tú: 'acepta el incidente activo'"] --> AGENT["agente de codificación (Claude Code / Codex)
carga la habilidad agenteye-cli"] + YOU["tú: 'confirma el incidente activo'"] --> AGENT["agente de programación (Claude Code / Codex)
carga la habilidad agenteye-cli"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|tu sesión autenticada de CLI| API["API del dashboard de Observabilidad"] + CLI -->|tu sesión CLI autenticada| API["API del dashboard de Observabilidad"] ``` -### vs. el asistente de IA en el dashboard: una distinción importante +### vs. el asistente IA integrado en el dashboard: una distinción importante -Son dos herramientas distintas con radios de acción muy diferentes: +Son dos herramientas distintas con alcances de impacto muy diferentes: -- El **asistente de IA en el dashboard** ([asistente de IA](/es/agenteye/assistant)) es un chat integrado en el dashboard, respaldado por el servicio de agente. Es **de solo lectura más autoría con aprobación**: puede redactar consultas guardadas y dashboards, pero cada escritura se pausa para esperar tu aprobación explícita con un clic, y nunca elimina nada. Requiere el permiso `agent:use` y solo accede a los datos de la organización que estás viendo. -- La **habilidad de CLI** se ejecuta en *tu* estación de trabajo dentro de *tu* agente de codificación y maneja la `agenteye` CLI **como tú**. Puede realizar la **superficie completa de la CLI, incluidas las mutaciones** (crear/rotar/deshabilitar claves API, cambiar configuraciones de la organización, resolver incidentes, eliminar consultas guardadas), limitada únicamente por los permisos de tu sesión de CLI. Trátala con exactamente el mismo cuidado con el que tratarías ejecutar esos comandos tú mismo. +- El **asistente IA integrado en el dashboard** ([Asistente IA](/es/agenteye/assistant)) es un chat integrado en el dashboard, respaldado por el servicio de agente. Es **de solo lectura más autoría con aprobación**: puede crear consultas guardadas y dashboards, pero cada escritura se detiene esperando tu aprobación explícita, y nunca elimina. Requiere el permiso `agent:use` y solo ve los datos de la organización que estás visualizando. +- La **habilidad CLI** se ejecuta en *tu* estación de trabajo dentro de *tu* agente de programación y maneja la `agenteye` CLI **como tú**. Puede realizar **todas las operaciones de la CLI, incluidas las mutaciones** (crear/rotar/deshabilitar claves de API, cambiar configuraciones de la organización, resolver incidentes, eliminar consultas guardadas), limitadas solo por los permisos de tu sesión CLI. Trátala con exactamente el mismo cuidado con el que tratarías ejecutar esos comandos tú mismo. --- ## Requisitos previos -1. La **CLI `agenteye` instalada** y disponible en el `PATH` (consulta la referencia de [CLI](/es/agenteye/cli): `pipx install agenteye`). +1. La **CLI `agenteye` instalada** y en el `PATH` (consulta la referencia de la [CLI](/es/agenteye/cli): `pipx install agenteye`). 2. Tu **URL del dashboard** configurada (`AGENTEYE_DASHBOARD_URL`, o el agente pasa `--base-url`). -3. Una **sesión activa**: ejecuta `agenteye login` tú mismo primero. La habilidad **no puede** completar el proceso de inicio de sesión con código de un solo uso enviado por correo; te indicará que ejecutes `agenteye login` si la sesión falta o ha expirado (código de salida `4` de la CLI). +3. Una **sesión iniciada**: ejecuta `agenteye login` tú mismo primero. La habilidad **no puede** completar el proceso de inicio de sesión con código de un solo uso enviado por correo; te indicará que ejecutes `agenteye login` si la sesión falta o ha expirado (código de salida de CLI `4`). --- @@ -55,13 +55,13 @@ La habilidad está publicada en la colección pública de habilidades de Failpro **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -No hay ninguna restricción de acceso: el repositorio es público y la habilidad no necesita credenciales propias, ya que solo maneja la `agenteye` CLI **pública** contra *tu* dashboard, usando la sesión con la que *tú* iniciaste sesión. No necesitas pedírsela a nadie. +No hay ninguna restricción de acceso: el repositorio es público y la habilidad no necesita credencial propia, ya que solo maneja la CLI **pública** de `agenteye` contra *tu* dashboard, usando la sesión con la que *tú* iniciaste sesión. No necesitas pedírsela a nadie. -Ten en cuenta que se distribuye como su propia carpeta y **no** está incluida en el paquete `pipx install agenteye`, así que no la busques allí. +Ten en cuenta que se distribuye como su propia carpeta y **no** está incluida dentro del paquete `pipx install agenteye`, así que no la busques allí. ## Instalación de la habilidad -La forma más rápida es usando la CLI [`skills`](https://skills.sh), que descarga la carpeta y la coloca donde tu agente la busca: +La forma más rápida es la CLI [`skills`](https://skills.sh), que descarga la carpeta y la coloca donde tu agente la busca: ```bash # Claude Code, solo este proyecto @@ -82,10 +82,10 @@ npx skills update agenteye-cli # obtener la última versión npx skills remove agenteye-cli # eliminarla ``` -¿Prefieres instalarla manualmente? Una Agent Skill es simplemente una carpeta que contiene un `SKILL.md` (más referencias opcionales), así que copiarla también funciona: +¿Prefieres instalarla manualmente? Una Agent Skill es simplemente una carpeta que contiene un `SKILL.md` (más referencias opcionales), por lo que copiarla también funciona: -- **Claude Code**: coloca la carpeta `agenteye-cli/` en `~/.claude/skills/` (todos los proyectos) o `/.claude/skills/` (solo ese repositorio). Claude Code la descubre automáticamente — verifica con la lista `/skills`, o simplemente haz una pregunta que coincida con su descripción. -- **Codex (OpenAI)**: Codex lee el mismo `SKILL.md`. El archivo `agents/openai.yaml` incluido configura `allow_implicit_invocation: true`, por lo que Codex selecciona automáticamente la habilidad cuando una tarea coincide; de lo contrario, invócala explícitamente como `$agenteye-cli`. +- **Claude Code**: coloca la carpeta `agenteye-cli/` en `~/.claude/skills/` (todos los proyectos) o `/.claude/skills/` (solo ese repositorio). Claude Code la descubre automáticamente — verifícalo con la lista `/skills`, o simplemente haz una pregunta que coincida con su descripción. +- **Codex (OpenAI)**: Codex lee el mismo `SKILL.md`. El archivo `agents/openai.yaml` incluido establece `allow_implicit_invocation: true`, por lo que Codex selecciona la habilidad automáticamente cuando una tarea coincide; de lo contrario, invócala explícitamente como `$agenteye-cli`. --- @@ -93,9 +93,9 @@ npx skills remove agenteye-cli # eliminarla > **Advertencia:** Lee esto antes de permitir que un agente realice cambios. -La `agenteye` CLI normalmente pregunta *«¿estás seguro?»* antes de una acción destructiva. **Omite automáticamente esa confirmación cuando no está conectada a un terminal (que es exactamente cómo la ejecuta un agente de codificación), y `--json` también la omite.** Por lo tanto, el aviso de seguridad **no** se activará para el agente. +La CLI `agenteye` normalmente pregunta *«¿estás seguro?»* antes de una acción destructiva. **Omite automáticamente esa confirmación cuando no está conectada a una terminal (que es exactamente como la ejecuta un agente de programación), y `--json` también la omite.** Por lo tanto, el aviso de seguridad **no** se activará para el agente. -La habilidad está diseñada para compensar esto: está instruida para indicar el comando exacto que ejecutará y obtener tu **aprobación explícita antes de cualquier cambio de estado**. Mantén esa disciplina. Cuando manejas Failproof AI Observability a través de un agente, *tú* eres el paso de confirmación. Los comandos que cambian estado a los que debes prestar atención: +La habilidad está diseñada para compensarlo: se le instruye a indicar el comando exacto que ejecutará y obtener tu **aprobación explícita antes de cualquier cambio de estado**. Mantén esa disciplina. Cuando operas Failproof AI Observabilidad a través de un agente, *tú* eres el paso de confirmación. Los comandos que cambian el estado y que debes vigilar son: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` @@ -106,54 +106,54 @@ La habilidad está diseñada para compensar esto: está instruida para indicar e - `agent rename` / `delete` - `orgs switch` -Todo lo que está bajo **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) es de solo lectura y no cambia nada. +Todo lo que corresponde a **Observar** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) es de solo lectura y no modifica nada. -Dado que el agente actúa **como tú**, solo puede hacer lo que tu sesión tiene permiso para hacer; los permisos se resuelven **por organización** (consulta [API keys](/es/agenteye/api-keys)). Un comando para el que no tienes permiso devuelve el código de salida `5` con el nombre exacto del permiso requerido, por lo que el agente puede decirte exactamente qué pedirle a un administrador en lugar de fallar de forma opaca. +Como el agente actúa **como tú**, solo puede hacer lo que tu sesión tiene permiso de hacer; los permisos se resuelven **por organización** (ver [claves de API](/es/agenteye/api-keys)). Un comando para el que no tienes permiso devuelve el código de salida `5` con el nombre exacto del permiso, por lo que el agente puede decirte exactamente qué pedirle a un administrador en lugar de fallar de forma opaca. --- ## Qué puedes pedirle -Aquí tienes un ejemplo de una interacción real completa: primero una lectura, luego un cambio que espera tu aprobación: +Así es como se ve un ciclo completo real: primero una lectura, luego un cambio que espera tu aprobación: ```text tú ▸ ¿Hay algo roto en el último día? agente▸ Ejecutando: agenteye --json errors --since 24h --aggregate - 3 tipos de error en las últimas 24h. El más frecuente es TimeoutError + 3 tipos de error en las últimas 24h. El mayor es TimeoutError (18 ocurrencias, todas en checkout-agent), luego RateLimited (5). - ¿Quieres ver las sesiones fallidas de TimeoutError? + ¿Quieres las sesiones fallidas de TimeoutError? tú ▸ Dale a CI una clave que solo pueda enviar eventos. -agente▸ Esto crea una clave API. Ejecutaré: +agente▸ Esto crea una clave de API. Ejecutaré: agenteye keys create ci --add events:add ¿Procedo? tú ▸ sí -agente▸ Listo. Clave "ci" creada con solo events:add. - El secreto se muestra una sola vez, así que guárdalo ahora. No puedo volver a mostrarlo. +agente▸ Listo. Clave "ci" creada solo con events:add. + El secreto se muestra una sola vez, así que guárdalo ahora. No puedo mostrarlo de nuevo. ``` La habilidad mapea cada intención en lenguaje natural al comando `agenteye` correcto, descubriendo primero los valores válidos (`list `, `whoami`) para no adivinar, e indicando el comando exacto antes de cualquier cambio. Más ejemplos: -- *«¿Hay algo roto o fallando en las últimas 24 horas?»* → `errors --since 24h --aggregate`, luego un desglose. +- *«¿Hay algo roto / fallando en las últimas 24 horas?»* → `errors --since 24h --aggregate`, luego un desglose. - *«¿Por qué falló la sesión `run-001`?»* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *«¿Cómo está evolucionando la calidad esta semana?»* → `evals --aggregate --since 7d`, luego profundizar en las ejecuciones con puntuación baja. -- *«Dale a CI una clave que solo pueda enviar eventos.»* → `keys create ci --add events:add` (indica el comando, luego lo crea y captura el secreto de un solo uso). -- *«¿Quién tiene acceso? Dale a Dana permisos de solo lectura.»* → `users list` → `users update dana@… --permission-set read-only` (después de confirmar contigo). -- *«Acepta el incidente activo y asígnamelo.»* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. +- *«¿Cómo está evolucionando la calidad esta semana?»* → `evals --aggregate --since 7d`, luego profundiza en las ejecuciones con puntuación baja. +- *«Dale a CI una clave que solo pueda enviar eventos.»* → `keys create ci --add events:add` (indica el comando, luego lo crea y captura el secreto de uso único). +- *«¿Quién tiene acceso? Deja a Dana con solo lectura.»* → `users list` → `users update dana@… --permission-set read-only` (previa confirmación contigo). +- *«Confirma el incidente activo y asígnamelo.»* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. -Para los comandos exactos, opciones y formatos JSON detrás de estos, consulta la referencia de [CLI](/es/agenteye/cli) y las [recetas de CLI para agentes](/es/agenteye/cli-recipes). +Para conocer los comandos exactos, las opciones y las estructuras JSON detrás de estos, consulta la referencia de la [CLI](/es/agenteye/cli) y las [recetas CLI para agentes](/es/agenteye/cli-recipes). --- ## Próximos pasos - **[CLI](/es/agenteye/cli)**: referencia completa de comandos y opciones de `agenteye`. -- **[Recetas de CLI para agentes](/es/agenteye/cli-recipes)**: patrones de `jq` listos para copiar y pegar, y manejo de códigos de salida. -- **[Habilidad del agente evaluador](/es/agenteye/evaluator-skill)**: la habilidad hermana, para construir el evaluador cuyas puntuaciones lee `agenteye evals`. -- **[Habilidad del agente SDK de Python](/es/agenteye/python-sdk-skill)**: la habilidad hermana, para instrumentar un agente y que emita la telemetría que lee `agenteye`. -- **[Asistente de IA](/es/agenteye/assistant)**: el asistente integrado en el dashboard (no confundir con esta habilidad de terminal). -- **[API keys](/es/agenteye/api-keys)**: el modelo de permisos por organización que limita lo que la habilidad puede hacer. \ No newline at end of file +- **[Recetas CLI para agentes](/es/agenteye/cli-recipes)**: patrones `jq` para copiar y pegar y manejo de códigos de salida. +- **[Habilidad de agente Evaluador](/es/agenteye/evaluator-skill)**: la habilidad hermana, para construir el evaluador cuyas puntuaciones lee `agenteye evals`. +- **[Habilidad de agente Python SDK](/es/agenteye/python-sdk-skill)**: la habilidad hermana, para instrumentar un agente de modo que emita la telemetría que lee `agenteye`. +- **[Asistente IA](/es/agenteye/assistant)**: el asistente integrado en el dashboard (no confundir con esta habilidad de terminal). +- **[Claves de API](/es/agenteye/api-keys)**: el modelo de permisos por organización que delimita lo que puede hacer la habilidad. \ No newline at end of file diff --git a/docs/es/agenteye/cli.mdx b/docs/es/agenteye/cli.mdx index b424c7d7..6552136a 100644 --- a/docs/es/agenteye/cli.mdx +++ b/docs/es/agenteye/cli.mdx @@ -1,34 +1,34 @@ --- title: "CLI" -description: "Controla toda la observabilidad de Failproof AI desde la terminal o un script: sin idas y vueltas al dashboard." +description: "Gestiona toda la observabilidad de Failproof AI desde la terminal o un script: sin viajes al dashboard." --- -Controla toda la observabilidad de Failproof AI desde la terminal o un script: sin idas y vueltas al dashboard. El CLI `agenteye` consulta tus datos (sesiones, registros de eventos, evaluaciones) y administra tu organización (claves de API, usuarios, configuraciones, alertas, incidentes, consultas guardadas), así que úsalo cuando quieras automatizar una verificación, integrar Observabilidad en CI, o permitir que un agente de código inspeccione producción. Todos los comandos admiten el flag `--json`, por lo que funciona igual de bien para ti en un prompt o para un agente de código (Claude Code, Cursor) que ejecuta el comando y parsea el resultado. +Gestiona toda la observabilidad de Failproof AI desde la terminal o un script: sin viajes al dashboard. El CLI `agenteye` consulta tus datos (sesiones, registros de eventos, evaluaciones) y administra tu organización (claves API, usuarios, configuración, alertas, incidentes, consultas guardadas), por lo que es ideal cuando quieres automatizar una verificación, integrar la observabilidad en CI, o permitir que un agente de código inspeccione producción. Todos los comandos admiten el flag `--json`, por lo que funciona igual de bien para ti en un prompt o para un agente de código (Claude Code, Cursor) que ejecuta el CLI y analiza el resultado. Con un solo binario puedes: - **Leer tus datos**: `sessions`, `events`, `evals`, `errors` (filtra por tiempo, agente, entorno, puntuación). -- **Administrar tu organización**: `keys`, `users`, `settings`, `alerts`, `incidents`. +- **Gestionar tu organización**: `keys`, `users`, `settings`, `alerts`, `incidents`. - **Ejecutar análisis**: SQL guardado y un ejecutor de consultas ad-hoc (`query`). - **Consultar al asistente de IA**: el mismo analista de solo lectura con el que chateas en el dashboard (`agent`). -> **Nota:** Este es el CLI `agenteye`, una herramienta distinta del daemon recolector (`agenteye-collector`). El CLI se comunica con tu dashboard; el recolector envía eventos al servidor. +> **Nota:** Este es el CLI `agenteye`, una herramienta diferente al daemon recolector (`agenteye-collector`). El CLI se comunica con tu dashboard; el recolector envía eventos al servidor. --- ## Inicio rápido -De cero a tu primer resultado en cuatro líneas. Apunta el CLI a tu dashboard, inicia sesión, confirma quién eres y luego extrae el último día de ejecuciones: +De cero a tu primer resultado en cuatro líneas. Apunta el CLI a tu dashboard, inicia sesión, confirma quién eres y luego obtén el último día de ejecuciones: ```bash pipx install agenteye agenteye --base-url https://agenteye.example.com login --email you@example.com # código de 6 dígitos enviado por email -agenteye whoami # confirma usuario + org activa -agenteye --json sessions --since 24h # una fila por ejecución de agente, últimas 24h +agenteye whoami # confirmar usuario + organización activa +agenteye --json sessions --since 24h # una fila por ejecución del agente, últimas 24h ``` -Ese último comando imprime un objeto JSON con las sesiones más recientes (más nuevas primero, limitado a 50 por defecto). Pásalo por `jq` para filtrarlo, o quita `--json` para obtener una tabla enmarcada y con colores. Cada fila contiene el estado de la ejecución y, si un evaluador la puntuó, sus métricas (abreviadas aquí): +El último comando imprime un objeto JSON con las sesiones más recientes (de más nueva a más antigua, limitado a 50 por defecto). Pásalo a `jq` para filtrarlo, o elimina `--json` para obtener una tabla con bordes y colores. Cada fila incluye el estado de la ejecución y, si un evaluador la puntuó, sus métricas (abreviadas aquí): ```json { @@ -69,7 +69,7 @@ agenteye --version agenteye --help ``` -> **Nota:** El SDK de Python de Observabilidad de Failproof AI también usa el nombre de distribución `agenteye`. Instalar el CLI con `pipx` o `uv tool` (en lugar de `pip install` en un virtualenv compartido) evita conflictos entre ambos. Un simple `pip install agenteye` solo es seguro si el SDK no está instalado en el mismo entorno. +> **Nota:** El SDK de Python de Failproof AI Observability también usa el nombre de distribución `agenteye`. Instalar el CLI con `pipx` o `uv tool` (en lugar de `pip install` en un virtualenv compartido) evita conflictos entre ambos. Un simple `pip install agenteye` solo es seguro si el SDK no está instalado en el mismo entorno. --- @@ -79,19 +79,19 @@ El CLI se autentica en el **dashboard** con un código de un solo uso enviado po ```bash agenteye login --email you@example.com -# Se te envía un código de 6 dígitos por email; pégalo en el prompt. +# Se envía un código de 6 dígitos a tu correo; pégalo cuando se te solicite. ``` -El token de sesión se almacena en `~/.agenteye/cli.json` (legible solo por ti, modo `0600`) y es válido por 24 horas por defecto. Cuando expire, ejecuta `agenteye login` de nuevo. +El token de sesión se almacena en `~/.agenteye/cli.json` (legible solo por ti, modo `0600`) y es válido por 24 horas de forma predeterminada. Cuando expire, ejecuta `agenteye login` de nuevo. ```bash -agenteye whoami # muestra el usuario actual, la org activa y los permisos +agenteye whoami # muestra el usuario actual, la organización activa y los permisos agenteye logout # revoca la sesión y elimina el token almacenado ``` -`whoami` nunca falla por una sesión ausente o expirada; en su lugar reporta `logged_in: false`, por lo que un script o agente puede verificar el estado de autenticación de forma segura (igual puede salir con código distinto de cero si no hay URL base configurada o el dashboard no está disponible). +`whoami` nunca falla por una sesión ausente o expirada; en su lugar reporta `logged_in: false`, por lo que un script o agente puede comprobar el estado de autenticación de forma segura (aunque puede salir con código distinto de cero si no hay URL base configurada o el dashboard no es accesible). -**Requisitos:** tu email debe tener permiso para iniciar sesión en el dashboard (consulta a tu administrador de Observabilidad de Failproof AI), y el dashboard debe ser accesible en su URL base (ver [Configuración](#configuration)). Si solicitas un código y no llega, probablemente tu email todavía no tiene acceso habilitado al dashboard. +**Requisitos:** tu email debe tener permiso para iniciar sesión en el dashboard (consulta a tu administrador de Failproof AI Observability), y el dashboard debe ser accesible en su URL base (ver [Configuración](#configuration)). Si solicitas un código y no llega, es probable que tu email aún no esté habilitado para acceder al dashboard. --- @@ -100,73 +100,73 @@ agenteye logout # revoca la sesión y elimina el token almacenado Si tu cuenta pertenece a más de una organización, elige la activa **al iniciar sesión**; se guarda y se usa en todos los comandos posteriores: ```bash -agenteye login --org acme # autentícate y establece el tenant activo en un solo paso -agenteye orgs list # las orgs a las que tienes acceso (la activa aparece marcada) -agenteye orgs switch globex # cambia el valor predeterminado guardado -agenteye --org globex sessions # anula la org solo para un comando +agenteye login --org acme # autenticarse y establecer el tenant activo en un solo paso +agenteye orgs list # las organizaciones a las que tienes acceso (la activa está marcada) +agenteye orgs switch globex # cambiar la organización predeterminada guardada +agenteye --org globex sessions # anular para un solo comando ``` -Si perteneces a exactamente una org, se selecciona automáticamente y puedes ignorar `--org` por completo. Si perteneces a varias y no eliges una, el CLI las lista y te pide que vuelvas a ejecutar con `--org `. La org activa se envía al dashboard en cada solicitud, y tus permisos se resuelven **por org**; `agenteye whoami` muestra la org activa, tus permisos en ella y todas tus membresías. +Si perteneces a exactamente una organización, se selecciona automáticamente y puedes ignorar `--org` por completo. Si perteneces a varias y no eliges una, el CLI las lista y te pide que vuelvas a ejecutar con `--org `. La organización activa se envía al dashboard en cada solicitud y tus permisos se resuelven **por organización**; `agenteye whoami` muestra la organización activa, tus permisos en ella y todas tus membresías. --- ## Configuración -| Parámetro | Flag | Variable de entorno | Por defecto | +| Parámetro | Flag | Variable de entorno | Valor predeterminado | |---|---|---|---| -| URL base del dashboard | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **requerida** (sin valor predeterminado) | -| Org/tenant activo | `--org` | `AGENTEYE_ORG` | elegida al iniciar sesión; guardada en `~/.agenteye/cli.json` | +| URL base del dashboard | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **obligatorio** (sin valor predeterminado) | +| Organización/tenant activa | `--org` | `AGENTEYE_ORG` | se elige al iniciar sesión; se guarda en `~/.agenteye/cli.json` | | Token de sesión | `--token` | `AGENTEYE_CLI_TOKEN` | desde `~/.agenteye/cli.json` | | Salida JSON | `--json` | `AGENTEYE_CLI_JSON` | desactivado | | Omitir verificación TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | desactivado (guardado al iniciar sesión) | -| Tiempo de espera de solicitud (segundos) | `--timeout` | _(ninguna)_ | 30 | -| Deshabilitar telemetría de uso | _(ninguna)_ | `AGENTEYE_ANALYTICS_DISABLED` (o `DO_NOT_TRACK`) | la telemetría está actualmente deshabilitada; no se envía nada | +| Tiempo de espera de solicitud (segundos) | `--timeout` | _(ninguno)_ | 30 | +| Desactivar telemetría de uso | _(ninguno)_ | `AGENTEYE_ANALYTICS_DISABLED` (o `DO_NOT_TRACK`) | la telemetría está actualmente desactivada; no se envía nada | -El orden de resolución es **flag → variable de entorno → archivo de configuración**. No hay valor por defecto; debes apuntar el CLI a tu dashboard, ya sea por comando (`--base-url https://agenteye.example.com`) o una vez mediante la variable de entorno (también se guarda tras tu primer `login`): +El orden de resolución es **flag → variable de entorno → archivo de configuración**. No hay valor predeterminado; debes apuntar el CLI a tu dashboard, ya sea por comando (`--base-url https://agenteye.example.com`) o una vez mediante la variable de entorno (también se guarda tras tu primer `login`): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -El directorio de configuración respeta `AGENTEYE_HOME` (la misma convención que usan el SDK y el recolector); si está definido, `cli.json` se ubica en `$AGENTEYE_HOME/cli.json`. +El directorio de configuración respeta `AGENTEYE_HOME` (la misma convención que usan el SDK y el recolector); si está definido, `cli.json` reside en `$AGENTEYE_HOME/cli.json`. ### TLS autofirmado o interno -Si tu dashboard se sirve sobre HTTPS con un certificado autofirmado o interno (por ejemplo, el nombre de host de un balanceador de carga), la verificación TLS lo rechazará con un error `CERTIFICATE_VERIFY_FAILED`. Usa `--insecure` para omitir la verificación de certificados: +Si tu dashboard usa HTTPS con un certificado autofirmado o interno (por ejemplo, el hostname de un balanceador de carga sin procesar), la verificación TLS lo rechazará con un error `CERTIFICATE_VERIFY_FAILED`. Usa `--insecure` para omitir la verificación del certificado: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` se **guarda en `cli.json` al iniciar sesión**, por lo que los comandos posteriores omiten la verificación automáticamente; no necesitas repetir el flag. Usa `--secure` para una llamada verificada puntual, o para volver a habilitar la verificación en tu próximo inicio de sesión. El CLI muestra una advertencia en stderr antes de cualquier comando que contacte el dashboard con la verificación deshabilitada. Omitir la verificación elimina la protección contra ataques de intermediario (man-in-the-middle); asegúrate de confiar en la ruta de red a tu dashboard (VPN, subred privada, etc.) antes de depender de esta opción. +`--insecure` **se guarda en `cli.json` cuando inicias sesión**, por lo que los comandos posteriores omiten la verificación automáticamente; no necesitas repetir el flag. Usa `--secure` para una llamada verificada puntual, o para volver a activar la verificación en tu próximo inicio de sesión. El CLI imprime una advertencia en stderr antes de cualquier comando que contacte al dashboard mientras la verificación está desactivada. Omitir la verificación elimina la protección contra ataques de intermediario; asegúrate de confiar en la ruta de red hacia tu dashboard (VPN, subred privada, etc.) antes de usarla. --- ## Telemetría y privacidad -> **Nota:** El CLI incluido **no envía telemetría de uso hoy en día.** Hay un interruptor maestro activado, por lo que no se transmite nada independientemente de tu entorno. La sección a continuación describe la capacidad de exclusión voluntaria para el caso de que la telemetría alguna vez se habilite. +> **Nota:** El CLI distribuido **no envía telemetría de uso actualmente.** Hay un interruptor maestro activado, por lo que no se transmite nada independientemente de tu entorno. La sección a continuación describe la capacidad de exclusión voluntaria para el caso en que la telemetría se habilite en el futuro. -Incluso cuando esté habilitada, la telemetría sería **únicamente análisis de uso anónimos**, nunca datos de tu agente, sesión o eventos: +Incluso si se habilitara, la telemetría sería **solo análisis de uso anónimo**, nunca tus datos de agentes, sesiones o eventos: -- **Ningún dato de agente, sesión o evento sale jamás de tu infraestructura.** Solo se reportaría el uso del CLI: el nombre del comando y subcomando (p. ej., `keys create`), los **nombres** de los flags que usaste (nunca sus valores), estado de éxito/salida, y duración, más un evento por acción para mutaciones (p. ej., `api_key_created`, `query_run`) que solo lleva nombres/enums estáticos y conteos aproximados. Tu URL de dashboard, token de sesión, email, slug de org, IDs de recursos, SQL, secretos de claves y filtros de consulta **nunca se enviarían**. Los operadores se identificarían únicamente por un ID interno opaco, nunca por email. -- **Excluirte con antelación** establece `AGENTEYE_ANALYTICS_DISABLED=1` en el entorno del CLI (el CLI también respeta la convención multiplataforma `DO_NOT_TRACK=1`). Esto tiene efecto en el momento en que la telemetría se active, por lo que un entorno con conciencia de privacidad puede permanecer excluido permanentemente. -- Si la telemetría estuviera habilitada, el CLI enviaría directamente a PostHog (`https://us.i.posthog.com`); una máquina con ese host bloqueado simplemente no enviaría nada y el CLI no se vería afectado. +- **Ningún dato de agente, sesión o evento sale jamás de tu infraestructura.** Solo se reportaría el uso del CLI: el nombre del comando y subcomando (por ejemplo, `keys create`), los **nombres** de los flags que usaste (nunca sus valores), el estado de éxito/salida y la duración, además de un evento por acción para mutaciones (por ejemplo, `api_key_created`, `query_run`) que solo lleva nombres o enumeraciones estáticas y conteos aproximados. La URL de tu dashboard, el token de sesión, el email, el slug de la organización, los IDs de recursos, el SQL, los secretos de claves y los filtros de consultas **nunca** se enviarían. Los operadores se identificarían únicamente por un ID interno opaco, nunca por email. +- **Excluirte con antelación** es tan simple como establecer `AGENTEYE_ANALYTICS_DISABLED=1` en el entorno del CLI (el CLI también respeta la convención `DO_NOT_TRACK=1` de otras herramientas). Esto surte efecto en el momento en que se active la telemetría, por lo que un entorno sensible a la privacidad puede mantenerse excluido de forma permanente. +- Si se habilitara la telemetría, el CLI enviaría directamente a PostHog (`https://us.i.posthog.com`); una máquina con ese host bloqueado simplemente no enviaría nada y el CLI no se vería afectado. --- ## Opciones globales y convenciones -Lee esto una vez; aplica a todos los comandos. +Lee esto una vez; se aplica a todos los comandos. -- **Las opciones globales van ANTES del comando.** `agenteye --json sessions` es correcto; `agenteye sessions --json` es un error de uso. Las globales son `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` y `--no-color`. -- **`--json` imprime JSON puro en stdout, y nada más.** Las líneas de estado para humanos, advertencias y errores van a **stderr**, por lo que una captura de stdout con `--json` se mantiene limpia para pasar a `jq` incluso cuando se muestra una línea de estado. Sin `--json` obtienes una vista enmarcada y con colores para lectura humana. -- **Explora con `--help`.** Cada comando y subcomando tiene `--help` (y el alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. La ayuda de nivel superior también lista los códigos de salida y las opciones globales. No hay un volcado de superficie legible por máquina a nivel global; usa `--help` por comando, más los específicos de dominio `agenteye query schema` y `agenteye settings schema` para esos dos registros. -- **Las confirmaciones se omiten automáticamente en scripts y agentes.** Los comandos de creación/actualización/eliminación muestran el mensaje "¿estás seguro?" en una terminal interactiva, pero **omiten ese prompt automáticamente con `--json` o cuando stdin no es un TTY** (un TTY es una sesión de terminal interactiva; una tubería o un runner de CI no lo es), por lo que los scripts y agentes nunca quedan bloqueados. Usa `--yes`/`-y` para omitirlo explícitamente. Como el prompt no se mostrará para un agente, este debería confirmar las acciones destructivas con el humano primero. -- **Paginación:** los resultados están ordenados de más nuevo a más antiguo y paginados por cursor (cada página devuelve un token que usas para obtener la siguiente). `--limit N` (alias `-n`) limita las filas y **por defecto es 50**; `--all` pagina automáticamente (en bloques de 200 filas) **hasta `--limit`**, por lo que un `--all` sin más aún se detiene en 50. Para un barrido completo, pasa un límite explícito alto: `--all --limit 1000`. `--page-size N` controla el bloque por solicitud (máximo 200); `--cursor ` reanuda desde el `next_cursor` de una página anterior. -- **Filtros de tiempo:** `--since` acepta una ventana relativa: `15m`, `1h`, `6h`, `24h`, `7d`, o `all` (los presets del dashboard). Para un rango más largo o personalizado (digamos los últimos 30 días), usa `--from`/`--to`: timestamps UTC explícitos en ISO-8601 **con `T` y zona horaria** (p. ej., `2026-06-01T00:00:00Z`) que sobreescriben `--since`. Un valor separado por espacios o sin zona horaria es un error de uso. -- **`--fields a,b,c`** (en `events`, `sessions`, `evals`, `errors`) restringe la salida a esas claves, tanto en la tabla como en `--json`. Los nombres desconocidos se rechazan con la lista válida, una forma rápida de descubrir los nombres de campos. -- **`--file payload.json`** (o `--file -` para leer stdin) proporciona un cuerpo de solicitud JSON completo donde un recurso tiene una forma compleja (en `alerts create/update`, `settings set` y `users create/update`). El SQL de consultas guardadas usa `--sql @file.sql` en su lugar. -- **Los filtros de múltiples valores** son separados por comas → se comparan como un conjunto (unión dentro de un filtro, AND entre filtros): `--event-type tool_use,tool_result`. Las opciones de Click no son variádicas, así que `--add a b` no funciona. Usa `--add a,b`, repite el flag (`--add a --add b`), o entrecomíllalo (`--add "a b"`). +- **Las opciones globales van ANTES del comando.** `agenteye --json sessions` es correcto; `agenteye sessions --json` es un error de uso. Las opciones globales son `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` y `--no-color`. +- **`--json` imprime JSON puro en stdout, y nada más.** Las líneas de estado, advertencias y errores van a **stderr**, por lo que la captura de stdout con `--json` se mantiene limpia para pasar a `jq` incluso cuando se muestra una línea de estado. Sin `--json` obtienes una vista con bordes y colores para uso humano. +- **Descubre con `--help`.** Cada comando y subcomando tiene `--help` (y el alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. La ayuda de nivel superior también lista los códigos de salida y las opciones globales. No hay un volcado global legible por máquinas; usa `--help` por comando, más los específicos de dominio `agenteye query schema` y `agenteye settings schema` para esos dos registros. +- **Las confirmaciones se omiten automáticamente en scripts y agentes.** Los comandos de creación/actualización/eliminación solicitan confirmación en una terminal interactiva, pero **omiten ese prompt automáticamente con `--json` o cuando stdin no es una TTY** (una TTY es una sesión de terminal interactiva; una tubería o un runner de CI no lo es), por lo que los scripts y agentes nunca quedan bloqueados. Usa `--yes`/`-y` para omitirla explícitamente. Como el prompt no se activará para un agente, este debería confirmar las acciones destructivas con el usuario antes de ejecutarlas. +- **Paginación:** los resultados están ordenados de más nuevo a más antiguo y se paginan con cursor (cada página devuelve un token que se usa para obtener la siguiente). `--limit N` (alias `-n`) limita las filas y **tiene como valor predeterminado 50**; `--all` pagina automáticamente (en bloques de 200 filas) **hasta `--limit`**, por lo que un simple `--all` sigue deteniéndose en 50. Para un recorrido completo, pasa un límite alto explícito: `--all --limit 1000`. `--page-size N` controla el bloque por solicitud (máx. 200); `--cursor ` reanuda desde el `next_cursor` de una página anterior. +- **Filtros de tiempo:** `--since` acepta una ventana relativa: `15m`, `1h`, `6h`, `24h`, `7d` o `all` (los preajustes del dashboard). Para un rango más largo o personalizado (por ejemplo, los últimos 30 días), usa `--from`/`--to`: marcas de tiempo UTC explícitas en formato ISO-8601 **con `T` y zona horaria** (por ejemplo, `2026-06-01T00:00:00Z`) que anulan `--since`. Un valor separado por espacios o sin zona horaria es un error de uso. +- **`--fields a,b,c`** (en `events`, `sessions`, `evals`, `errors`) restringe la salida a esas claves, tanto en la tabla como en `--json`. Los nombres desconocidos se rechazan con la lista de valores válidos, una forma económica de descubrir nombres de campos. +- **`--file payload.json`** (o `--file -` para leer desde stdin) proporciona un cuerpo de solicitud JSON completo cuando un recurso tiene una forma compleja (en `alerts create/update`, `settings set` y `users create/update`). El SQL de consultas guardadas usa `--sql @file.sql` en su lugar. +- **Los filtros de múltiples valores** son separados por comas → se comparan como un conjunto (unión dentro de un filtro, AND entre filtros): `--event-type tool_use,tool_result`. Las opciones de Click no son variádicas, por lo que `--add a b` falla. Usa `--add a,b`, repite el flag (`--add a --add b`) o pon comillas (`--add "a b"`). --- @@ -174,37 +174,37 @@ Lee esto una vez; aplica a todos los comandos. ### Los 5 comandos que más usarás -La mayor parte del trabajo diario se realiza con un puñado de comandos de lectura. Empieza aquí y recurre a la superficie completa cuando lo necesites: +La mayor parte del trabajo diario se realiza con unos pocos comandos de lectura. Empieza aquí y luego recurre a la superficie completa cuando lo necesites: | Comando | Qué hace | Pruébalo | |---|---|---| -| `sessions` | Una fila por ejecución de agente: tiempo, entorno, agente, estado, última puntuación. | `agenteye --json sessions --since 24h --status error` | -| `events` | El rastro sin procesar de cada paso dentro de una ejecución (añade `--full` para los payloads). | `agenteye --json events --session-id run-001 --all` | -| `evals` | Resultados de evaluación y puntuaciones; `--aggregate` los agrupa. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `sessions` | Una fila por ejecución del agente: tiempo, entorno, agente, estado, puntuación más reciente. | `agenteye --json sessions --since 24h --status error` | +| `events` | El rastro detallado por paso dentro de una ejecución (añade `--full` para los payloads). | `agenteye --json events --session-id run-001 --all` | +| `evals` | Resultados y puntuaciones de evaluación; `--aggregate` los agrupa. | `agenteye --json evals --aggregate --since 7d --env prod` | | `errors` | Solo los eventos con error; `--aggregate` para conteos por tipo. | `agenteye --json errors --since 24h --aggregate` | | `list` | Descubre los valores de filtro válidos (agentes, entornos, modelos, …). | `agenteye list agents` | ### Todo lo que puede hacer el CLI -La superficie completa aparece a continuación. El CLI tiene **18 comandos de nivel superior**. Todos los comandos de lectura aceptan `--json` y las opciones globales anteriores; ejecuta `agenteye -h` (o ` -h`) para la lista exhaustiva de flags y la forma JSON de cualquiera. +La superficie completa sigue a continuación. El CLI tiene **18 comandos de nivel superior**. Todos los comandos de lectura admiten `--json` y las opciones globales anteriores; ejecuta `agenteye -h` (o ` -h`) para la lista exhaustiva de flags y la forma JSON de cualquiera de ellos. ### Identidad: `login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash agenteye login --email you@example.com [--org acme] # código de un solo uso por email; guarda la sesión -agenteye logout # limpia la sesión guardada en esta máquina -agenteye whoami # usuario actual, org activa, permisos -agenteye version # muestra la versión del CLI (igual que --version) +agenteye logout # eliminar la sesión guardada en esta máquina +agenteye whoami # usuario actual, organización activa, permisos +agenteye version # imprimir la versión del CLI (igual que --version) agenteye help # ayuda de nivel superior (igual que --help) ``` `orgs` inspecciona y cambia el tenant activo: ```bash -agenteye orgs list # tus orgs + tu rol en cada una (la activa aparece marcada) -agenteye orgs switch acme # cambia la org activa guardada (omite el slug para elegir de una lista en TTY) -agenteye orgs current # tarjeta de identidad de la org activa -agenteye orgs perms # tus permisos en la org activa, agrupados por recurso +agenteye orgs list # tus organizaciones + tu rol en cada una (la activa está marcada) +agenteye orgs switch acme # cambiar la organización activa guardada (omite el slug para elegir de una lista en una TTY) +agenteye orgs current # tarjeta de identidad de la organización activa +agenteye orgs perms # tus permisos en la organización activa, agrupados por recurso ``` ### Observar (solo lectura): `events` · `sessions` · `evals` · `errors` · `list` @@ -212,80 +212,80 @@ agenteye orgs perms # tus permisos en la org activa, agrupados por recurso Ninguno de estos requiere confirmación. Filtros compartidos: `--session-id`, `--agent-id`, `--env` (**no** `--environment`), y el rango de tiempo (`--since` / `--from` / `--to`). ```bash -# events (alias: el rastro sin procesar por paso), más nuevos primero +# events (alias: el rastro detallado por paso), de más nuevo a más antiguo agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' -# sessions: una fila por ejecución de agente (tiempo/entorno/agente/sesión/estado; sin filtrado por puntuación) +# sessions: una fila por ejecución del agente (tiempo/entorno/agente/sesión/estado; sin filtrado por puntuación) agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 # evals: resultados de evaluación + puntuaciones; --score filtra por métrica, --aggregate agrupa agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 -agenteye --json evals --aggregate --since 7d --env prod # mezcla de estados + estadísticas de puntuación por clave +agenteye --json evals --aggregate --since 7d --env prod # distribución de estados + estadísticas de puntuación por clave # errors: eventos con error; --aggregate para conteos/sesiones/agentes/última aparición agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 -# list: descubre los valores de filtro válidos antes de filtrar +# list: descubrir valores de filtro válidos antes de filtrar agenteye list envs # también: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (en **`evals`**, no en `sessions`) es repetible y se combina con AND; cualquiera de los límites es opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Hasta 20 filtros de puntuación por solicitud. `evals --scores-full` es un flag de visualización **solo para la tabla humana**; muestra todos los pares de puntuación en lugar de los primeros más un conteo `+N`. No tiene efecto con `--json`, que siempre devuelve el objeto de puntuación completo. Para leer **una sesión de principio a fin**, combina el rastro de eventos con su evaluación: +`--score KEY:MIN..MAX` (en **`evals`**, no en `sessions`) es repetible y se combina con AND; cualquiera de los límites es opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Hasta 20 filtros de puntuación por solicitud. `evals --scores-full` es un flag de visualización **solo para la tabla humana**; muestra cada par de puntuaciones en lugar de los primeros más un contador `+N`. No tiene efecto con `--json`, que siempre devuelve el objeto de puntuación completo. Para leer **una sesión de principio a fin**, combina el rastro de eventos con su evaluación: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' agenteye --json evals --session-id run-001 # sus puntuaciones + estado ``` -### Administrar (con permisos requeridos): `keys` · `users` · `settings` · `alerts` · `incidents` +### Gestionar (con permisos): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: claves de API. El secreto se genera localmente, se envía al servidor (que solo almacena un hash), y se **muestra una única vez** al crear/regenerar; captúralo en ese momento. Con `--json` aparece solo en el campo `key`. Se referencian por **nombre**. +**`keys`**: claves API. El secreto se genera localmente, se envía al servidor (que solo almacena un hash) y **se muestra una única vez** al crear/regenerar; captúralo en ese momento. Con `--json` aparece solo en el campo `key`. Se referencian por **nombre**. ```bash agenteye keys list # claves activas primero, luego revocadas agenteye keys show ci-bot -agenteye keys create ci-bot --add events:read.add # limita al alcance necesario; imprime el secreto UNA VEZ -agenteye keys create ops --permission-set standard --remove queries:run # comienza con un preset y recorta +agenteye keys create ci-bot --add events:read.add # limitar al ámbito necesario; imprime el secreto UNA VEZ +agenteye keys create ops --permission-set standard --remove queries:run # partir de un preset y luego recortar agenteye keys update ci-bot --add evaluations:read --yes -agenteye keys regenerate ci-bot --yes # rota el secreto (el anterior deja de funcionar) -agenteye keys disable ci-bot --yes # revoca +agenteye keys regenerate ci-bot --yes # rotar el secreto (el anterior deja de funcionar) +agenteye keys disable ci-bot --yes # revocar ``` -Los permisos funcionan como `(permission-set ∪ --add) − --remove`. Los tokens son `slug:acción` (p. ej., `events:read`) o `slug:acción.acción` para expandir varios en un recurso (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. Los permisos exclusivos de humanos (`keys:update`) no pueden concederse a una clave. +Los permisos funcionan como `(permission-set ∪ --add) − --remove`. Los tokens son `slug:action` (por ejemplo, `events:read`) o `slug:action.action` para expandir varios en un recurso (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. Los permisos exclusivos para humanos (`keys:update`) no se pueden conceder a una clave. -**`users`**: miembros de la org, referenciados por **email** (también se acepta un UUID id). +**`users`**: miembros de la organización, referenciados por **email** (también se acepta un UUID). ```bash agenteye users list [--active-only] agenteye users show dev@corp.com agenteye users create dev@corp.com --permission-set standard agenteye users update dev@corp.com --add alerts:write --remove queries:delete # predice + confirma -agenteye users disable dev@corp.com --yes # tiene protecciones de usuarios protegidos/propios +agenteye users disable dev@corp.com --yes # tiene protecciones para usuarios protegidos/propios agenteye users enable dev@corp.com ``` -**`settings`**: un registro fijo (lees y cambias claves existentes; no puedes crear nuevas). +**`settings`**: un registro fijo (lees y modificas claves existentes; no puedes crear nuevas). ```bash agenteye settings list # clave · valor · tipo · actualizado (secretos enmascarados) -agenteye settings schema # lo que acepta cada clave (tipo · rango · descripción) +agenteye settings schema # qué acepta cada clave (tipo · rango · descripción) agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: definiciones de alertas, referenciadas por **nombre**. `create` toma un NAME posicional más flags o un cuerpo JSON completo vía `--file`. +**`alerts`**: definiciones de alertas, referenciadas por **nombre**. `create` acepta un NAME posicional más flags o un cuerpo JSON completo mediante `--file`. ```bash agenteye alerts list agenteye alerts show high-errors -agenteye alerts create high-errors --file alert.json # NAME es requerido (posicional) +agenteye alerts create high-errors --file alert.json # NAME es obligatorio (posicional) agenteye alerts update high-errors --severity critical --yes -agenteye alerts test high-errors --yes # dispara una notificación de prueba +agenteye alerts test high-errors --yes # disparar una notificación de prueba agenteye alerts delete high-errors --yes ``` -**`incidents`**: incidentes de alertas, referenciados por ID (se aceptan IDs cortos). `show` imprime el registro de actividad completo; léelo antes de actuar. +**`incidents`**: incidentes de alertas, referenciados por ID (se aceptan IDs cortos). `show` imprime el registro completo de actividad; léelo antes de actuar. ```bash agenteye incidents list --state firing # también: acknowledged, resolved @@ -294,7 +294,7 @@ agenteye incidents show agenteye incidents ack agenteye incidents assign you@corp.com # el asignado debe ser un operador agenteye incidents resolve --yes -agenteye incidents open --alert-id --severity critical # abre uno manualmente contra una alerta +agenteye incidents open --alert-id --severity critical # abrir uno manualmente contra una alerta agenteye incidents comment-add "root cause: upstream 5xx" agenteye incidents comment-list ; agenteye incidents comment-delete agenteye incidents subscribe ; agenteye incidents unsubscribe ; agenteye incidents subscribers @@ -302,12 +302,12 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### Análisis y asistente: `query` · `agent` -**`query`**: SQL guardado contra tu almacén de análisis más un ejecutor ad-hoc. Las consultas guardadas se referencian por **nombre**; el SQL se valida en el servidor (solo SELECT/WITH, timeout de declaración, límite de filas). +**`query`**: SQL guardado contra tu almacén de análisis más un ejecutor ad-hoc. Las consultas guardadas se referencian por **nombre**; el SQL se valida en el servidor (solo SELECT/WITH, tiempo de espera de instrucción, límite de filas). ```bash agenteye query schema [TABLE] # estructura de columnas de las vistas de análisis agenteye query run --sql "select count(*) from analytics.events" -agenteye query run errs --arg prod --limit 100 # ejecuta una consulta guardada + un $1 posicional +agenteye query run errs --arg prod --limit 100 # ejecutar una consulta guardada + un $1 posicional agenteye query list ; agenteye query show errs agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes @@ -316,10 +316,10 @@ agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs -- **`agent`**: habla con el **asistente de IA** integrado (el mismo analista de solo lectura con el que puedes chatear en el dashboard). Los chats se referencian por un chat-id corto (resuelto por prefijo). ```bash -agenteye agent health # si el asistente de IA está configurado/accesible -agenteye agent models # modelos que puedes pasar a --model (el predeterminado aparece marcado) +agenteye agent health # si el asistente de IA está configurado y accesible +agenteye agent models # modelos que puedes pasar a --model (el predeterminado está marcado) agenteye agent ask "which agents errored most in the last day?" # inicia un chat; imprime su ID corto -agenteye agent ask --chat "and which tools did they call?" # continúa ese chat +agenteye agent ask --chat "and which tools did they call?" # continuar ese chat agenteye agent chats ; agenteye agent show agenteye agent rename --title "error triage" ; agenteye agent delete ``` @@ -331,20 +331,20 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | Código | Significado | |---|---| | 0 | Éxito | -| 1 | Error inesperado (p. ej., el dashboard devolvió un 5xx) | +| 1 | Error inesperado (por ejemplo, el dashboard devolvió un 5xx) | | 2 | Error de uso (argumentos inválidos, comando/flag desconocido, colisión de nombres) | | 3 | No se puede alcanzar el dashboard | -| 4 | No has iniciado sesión o la sesión expiró; ejecuta `agenteye login` | -| 5 | Autenticado, pero tu cuenta no tiene el permiso requerido (el mensaje lo nombra) | -| 6 | El recurso solicitado no se encontró (p. ej., sesión o ID de incidente desconocido) | +| 4 | No autenticado o sesión expirada; ejecuta `agenteye login` | +| 5 | Autenticado, pero tu cuenta carece del permiso requerido (el mensaje lo indica) | +| 6 | El recurso solicitado no se encontró (por ejemplo, ID de sesión o incidente desconocido) | -Esto hace que el CLI sea seguro para usar en scripts: un agente de código puede ramificar en un `4` para pedirte que te vuelvas a autenticar, o en un `5` para mostrar el permiso faltante. Consulta [recetas de CLI para agentes](/es/agenteye/cli-recipes) para patrones de manejo de códigos de salida y formas de salida JSON. +Estos hacen que el CLI sea seguro para scripting: un agente de código puede ramificarse en un `4` para pedirte que te vuelvas a autenticar, o en un `5` para mostrar el permiso que falta. Consulta [recetas de CLI para agentes](/es/agenteye/cli-recipes) para ver patrones de manejo de códigos de salida y formas de salida JSON. --- ## Próximos pasos -- **[Recetas de CLI para agentes](/es/agenteye/cli-recipes)**: patrones de consulta listos para copiar, one-liners de `jq`, proyecciones con `--fields`, manejo de códigos de salida y formas de salida JSON, escritos para agentes de código que controlan el CLI. -- **[Habilidad de CLI para agentes](/es/agenteye/cli-skill)**: empaqueta este CLI como una *skill* instalable de Claude Code / Codex para que un agente de código controle la Observabilidad de Failproof AI desde solicitudes en lenguaje natural. -- **[Claves de API](/es/agenteye/api-keys)**: el modelo de permisos detrás de `keys create --add …`. +- **[Recetas de CLI para agentes](/es/agenteye/cli-recipes)**: patrones de consulta para copiar y pegar, comandos de una línea con `jq`, proyecciones con `--fields`, manejo de códigos de salida y formas de salida JSON, escritos para agentes de código que manejan el CLI. +- **[Skill de CLI para agentes](/es/agenteye/cli-skill)**: empaqueta este CLI como un *skill* instalable de Claude Code / Codex para que un agente de código gestione Failproof AI Observability mediante solicitudes en lenguaje natural. +- **[Claves API](/es/agenteye/api-keys)**: el modelo de permisos detrás de `keys create --add …`. - **[Asistente de IA](/es/agenteye/assistant)**: cómo habilitar el asistente con el que habla `agent ask`. \ No newline at end of file diff --git a/docs/es/agenteye/codex-capture.mdx b/docs/es/agenteye/codex-capture.mdx index ec3ae5e8..7b6bab09 100644 --- a/docs/es/agenteye/codex-capture.mdx +++ b/docs/es/agenteye/codex-capture.mdx @@ -1,55 +1,55 @@ --- title: "Captura de sesiones de Codex" -description: "Lleva las sesiones locales de OpenAI Codex de tu equipo a AgentEye como sesiones y eventos ordinarios, sin modificar la forma en que los ejecutan." +description: "Vuelca las sesiones locales de OpenAI Codex de tu equipo en AgentEye como sesiones y eventos ordinarios, sin cambiar nada en la forma en que lo ejecutan." --- -Tus ingenieros ya usan OpenAI Codex a diario. La captura de sesiones de Codex trae esas sesiones de trabajo a AgentEye como sesiones y eventos ordinarios, para que puedas buscarlas, reproducirlas y evaluarlas junto con todo lo demás que observas. Complementa el [SDK de Python](/es/agenteye/python-sdk): el SDK instrumenta los agentes que tú escribes, mientras que esto captura el trabajo en Codex que tu equipo ya realiza, sin cambiar nada en su flujo habitual. +Tus ingenieros ya ejecutan OpenAI Codex a diario. La captura de sesiones de Codex lleva esas sesiones de trabajo al entorno de AgentEye como sesiones y eventos ordinarios, de modo que puedas buscarlas, reproducirlas y evaluarlas junto con todo lo demás que observas. Complementa el [SDK de Python](/es/agenteye/python-sdk): el SDK instrumenta los agentes que tú escribes, mientras que esto captura el trabajo que tu equipo ya realiza con Codex, sin cambiar nada en la forma en que lo ejecutan. -Un pequeño recolector en segundo plano lee las transcripciones de sesiones locales de Codex a medida que se van escribiendo y las envía a AgentEye. Un único recolector por máquina captura todas las superficies locales de Codex a la vez — no es necesario configurar nada por cada superficie. +Un pequeño recolector en segundo plano lee los registros de sesión locales de Codex a medida que se escriben y los envía a AgentEye. Un único recolector por máquina captura todas las superficies locales de Codex a la vez: no hay configuración por superficie. -El mismo recolector también captura otros agentes — consulta [OpenClaw](/es/agenteye/openclaw-capture) y [Hermes](/es/agenteye/hermes-capture). Activa los que uses; un solo recolector puede capturar varios a la vez. +El mismo recolector también captura otros agentes; consulta [OpenClaw](/es/agenteye/openclaw-capture) y [Hermes](/es/agenteye/hermes-capture). Activa cada uno que utilices; un único recolector puede capturar varios al mismo tiempo. --- ## Qué captura -Todas las superficies de Codex que se ejecutan **localmente** producen las mismas transcripciones de sesión en disco, y el recolector las recoge todas: +Cada superficie de Codex que se ejecuta **localmente** produce los mismos registros de sesión en disco, y el recolector los recoge todos: - la **CLI** de Codex y `codex exec` -- la **extensión de VS Code / IDE** +- la **extensión para VS Code / IDE** - la **aplicación de escritorio**, cuando ejecuta una sesión de forma local -Cada sesión de Codex se convierte en una [sesión](/es/agenteye/sessions) de AgentEye; sus mensajes de usuario y asistente, razonamiento, llamadas a herramientas, resultados de herramientas y uso de tokens se convierten en los [eventos](/es/agenteye/event-stream) correspondientes. La superficie de la que proviene cada sesión (CLI, IDE o escritorio) queda registrada para que puedas distinguirlas. +Cada sesión de Codex se convierte en una [sesión](/es/agenteye/sessions) de AgentEye; sus mensajes de usuario y asistente, el razonamiento, las llamadas a herramientas, los resultados de herramientas y el uso de tokens pasan a ser los [eventos](/es/agenteye/event-stream) correspondientes. La superficie de origen de cada sesión (CLI, IDE o escritorio) queda registrada para que puedas distinguirlas. -> **Las sesiones en la nube no se capturan.** La aplicación de escritorio ejecuta cada vez más sesiones en la nube de Codex y solo guarda sus metadatos en la máquina local — no hay transcripción local que leer. Solo se capturan las sesiones ejecutadas localmente. +> **Las sesiones en la nube no se capturan.** La aplicación de escritorio ejecuta cada vez más sesiones en la nube de Codex y solo conserva sus metadatos en la máquina; no hay ningún registro local que leer. Solo se capturan las sesiones ejecutadas de forma local. --- -## Cómo activarlo +## Cómo activarla -La captura está desactivada hasta que la habilites. Instala el recolector con una clave de API que tenga el permiso `events:add` (consulta [Claves de API](/es/agenteye/api-keys)) y activa la captura de Codex: +La captura está desactivada hasta que la habilites. Instala el recolector con una clave API que tenga el permiso `events:add` (consulta [Claves API](/es/agenteye/api-keys)) y activa la captura de Codex: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -Esto instala el recolector, lo registra como servicio en segundo plano y comienza la captura. Confirma que está en ejecución: +Esto instala el recolector, lo registra como servicio en segundo plano y comienza la captura. Para confirmar que está en ejecución: ```bash agenteye-collector health ``` -En el primer arranque, las sesiones de Codex existentes se importan de una sola vez y la actividad nueva fluye en cuestión de segundos. Los archivos propios de Codex solo se leen — nunca se modifican, mueven ni eliminan — y cada sesión se envía exactamente una vez, incluso tras reinicios. +En el primer arranque, las sesiones de Codex existentes se importan una sola vez de forma retroactiva; la actividad nueva empieza a transmitirse en cuestión de segundos. Los archivos propios de Codex solo se leen: nunca se modifican, mueven ni eliminan, y cada sesión se envía exactamente una vez, incluso entre reinicios. --- ## Dónde aparece -Las sesiones capturadas aparecen en **Sessions**, y sus eventos en el flujo de **Events**, igual que cualquier otro agente que observes — así que la [reproducción de sesiones](/es/agenteye/sessions), la [búsqueda](/es/agenteye/queries), las [evaluaciones](/es/agenteye/evaluations) y las [alertas](/es/agenteye/alerts) funcionan con ellas. Filtra por el agente de Codex para verlas por separado. +Las sesiones capturadas aparecen en **Sesiones**, y sus eventos en el flujo de **Eventos**, igual que cualquier otro agente que observes; así, la [reproducción de sesiones](/es/agenteye/sessions), la [búsqueda](/es/agenteye/queries), las [evaluaciones](/es/agenteye/evaluations) y las [alertas](/es/agenteye/alerts) funcionan sobre ellas. Filtra por el agente de Codex para verlas por separado. --- ## Privacidad -Las transcripciones de Codex contienen la sesión completa — incluyendo la salida de comandos, el contenido de archivos y todo lo que Codex leyó o escribió — y pueden contener secretos. Las sesiones capturadas se envían tal cual, así que activa la captura únicamente en las máquinas y para los equipos en los que centralizar ese contenido en AgentEye sea apropiado, y proporciona al recolector una clave con alcance exclusivo a `events:add`. Consulta [Seguridad](/es/agenteye/security) para saber cómo se mantienen aislados tus datos. \ No newline at end of file +Los registros de Codex contienen la sesión completa, incluyendo la salida de comandos, el contenido de archivos y todo lo que Codex leyó o escribió, y pueden incluir secretos. Las sesiones capturadas se envían tal cual, por lo que activa la captura solo en las máquinas y para los equipos en los que centralizar ese contenido en AgentEye sea apropiado, y proporciona al recolector una clave con alcance únicamente para `events:add`. Consulta [Seguridad](/es/agenteye/security) para conocer cómo se mantienen aislados tus datos. \ No newline at end of file diff --git a/docs/es/agenteye/concepts.mdx b/docs/es/agenteye/concepts.mdx index 5a7b57e2..6d0af373 100644 --- a/docs/es/agenteye/concepts.mdx +++ b/docs/es/agenteye/concepts.mdx @@ -4,33 +4,33 @@ description: "El vocabulario de Failproof AI Observability — eventos, sesiones --- -Esta página define el vocabulario que utiliza Failproof AI Observability. Si algún término en otra guía te resulta desconocido, aquí encontrarás su definición. No es necesario leerla de principio a fin: puedes hojearla o volver cuando encuentres una palabra que quieras aclarar. +Esta página define el vocabulario que utiliza Failproof AI Observability. Si algún término en otra guía te resulta desconocido, aquí encontrarás su definición. No es necesario leerla de principio a fin: recórrela por encima o vuelve a ella cuando necesites aclarar algún concepto. --- ## El modelo de datos **Evento** -La unidad mínima de datos. Un evento registra un único paso que realizó tu agente: un `tool_use`, un `model_request`, un `hook_completed`, un `error`, entre otros. Tu agente emite eventos a través del [Python SDK](/es/agenteye/python-sdk); aparecen en tiempo real en la página de **Events**. +La unidad mínima de datos. Un evento registra un único paso que realizó tu agente: un `tool_use`, un `model_request`, un `hook_completed`, un `error`, etc. Tu agente emite eventos a través del [SDK de Python](/es/agenteye/python-sdk); aparecen en tiempo real en la página de **Eventos**. **Sesión** -Una ejecución del agente, identificada por un `session_id`. Una sesión agrupa todos los eventos que comparten ese identificador, se muestra como una fila en la página de **Sessions** y se representa como un grafo de ejecución en su página de detalle. Por lo general, una sesión comienza con `agent_start` y termina con `agent_end`. +Una ejecución del agente, identificada por un `session_id`. Una sesión agrupa todos los eventos que comparten ese identificador, consolidados en una única fila en la página de **Sesiones** y representados como un grafo de ejecución en su página de detalle. Normalmente comienza con `agent_start` y termina con `agent_end`. **Agente** -Un actor con nombre dentro de una ejecución, identificado por un `agent_id`. Una ejecución puede involucrar varios agentes: por ejemplo, un planificador que genera un sub-agente de resumen. Los sub-agentes llevan un `parent_id`, que es lo que permite a Failproof AI Observability representarlos en sus propios carriles dentro del grafo de ejecución. +Un actor con nombre dentro de una ejecución, identificado por un `agent_id`. Una ejecución puede involucrar varios agentes: por ejemplo, un planificador que lanza un subagente de resumen. Los subagentes llevan un `parent_id`, que es lo que permite a Failproof AI Observability representarlos en sus propias pistas dentro del grafo de ejecución. **Entorno** -Una etiqueta que indica dónde ocurrió la ejecución: `production`, `staging`, `dev`. Se configura una sola vez al configurar el SDK. Casi todas las páginas del panel permiten filtrar por entorno. +Una etiqueta que indica dónde ocurrió la ejecución: `production`, `staging`, `dev`. Se configura una sola vez al ajustar el SDK. Casi todas las páginas del panel permiten filtrar por entorno. -**Llenado de la ventana de contexto** -El porcentaje de la ventana de contexto de un modelo que consumió una respuesta. Failproof AI Observability lo registra en los eventos `model_response` para los modelos que reconoce, de modo que el crecimiento del prompt y la compactación inminente sean visibles directamente en el flujo de eventos. +**Ocupación de la ventana de contexto** +El porcentaje de la ventana de contexto de un modelo que consumió una respuesta. Failproof AI Observability lo registra en los eventos `model_response` para los modelos que reconoce, de modo que el crecimiento del prompt y la compactación inminente son visibles directamente en el flujo de eventos. --- ## Calidad **Evaluación** -Una puntuación de calidad para una sesión finalizada, generada por un servicio de puntuación que tú ejecutas. Las evaluaciones son opcionales: hasta que conectes un evaluador, las sesiones se registran pero no se puntúan. Cada evaluación puede incluir varias puntuaciones con nombre (por ejemplo, `helpfulness`, `factuality`, `tool_efficiency`), cada una con una breve nota de razonamiento. Consulta [Evaluation suite](/es/agenteye/evaluation-suite). +Una puntuación de calidad para una sesión finalizada, producida por un servicio de puntuación que tú ejecutas. Las evaluaciones son opcionales: hasta que conectes un evaluador, las sesiones se registran pero no se puntúan. Cada evaluación puede incluir varias puntuaciones con nombre (por ejemplo, `helpfulness`, `factuality`, `tool_efficiency`), cada una con una breve nota explicativa. Consulta [Suite de evaluación](/es/agenteye/evaluation-suite). **Clave de puntuación** El nombre de una dimensión que reporta un evaluador, como `helpfulness`. Las alertas y auditorías pueden monitorear una clave de puntuación específica a lo largo del tiempo. @@ -43,45 +43,45 @@ Tu servicio de puntuación. Failproof AI Observability envía mediante POST la t ## Detección y corrección de fallos **Hook** -Una barrera de protección o efecto secundario que el framework de tu agente ejecuta alrededor de un paso: una verificación de seguridad de contenido, la eliminación de PII, un control de presupuesto. Los hooks emiten eventos `hook_triggered` / `hook_completed` con un `outcome` (allow, deny, modify), y tienen su propia página de observabilidad. +Una salvaguarda o efecto secundario que tu framework de agentes ejecuta alrededor de un paso: una verificación de seguridad de contenido, redacción de PII, un límite de presupuesto. Los hooks emiten eventos `hook_triggered` / `hook_completed` con un `outcome` (allow, deny, modify) y tienen su propia página de observación. **Regla de alerta** -Una regla que se activa cuando una métrica supera un umbral que tú defines: tasa de errores, latencia p95, costo en tokens o una puntuación del evaluador. Cuando se activa una regla, abre un incidente y notifica a los canales que hayas configurado (correo electrónico, Slack, webhook, panel de control). Consulta [Alerts](/es/agenteye/alerts). +Una regla que se activa cuando una métrica supera el umbral que hayas configurado: tasa de errores, latencia p95, coste en tokens o una puntuación del evaluador. Cuando una regla se activa, abre un incidente y notifica a los canales que hayas elegido (correo electrónico, Slack, webhook, panel). Consulta [Alertas](/es/agenteye/alerts). **Incidente** Un problema abierto que se crea cuando se activa una regla de alerta. Los incidentes tienen un ciclo de vida (reconocer, asignar, resolver) y una línea de tiempo de actividad que registra cada acción. También puedes abrir uno manualmente. **Auditoría** -Una investigación recurrente (de cada hora a semanal) que analiza tus registros *entre* sesiones en busca de patrones de fallo para los que aún no has escrito una regla: clústeres de errores, puntuaciones bajas, valores atípicos de latencia, bucles de llamadas a herramientas y ejecuciones que nunca terminaron. Mientras que una alerta monitorea una métrica que ya conoces, una auditoría te indica qué deberías revisar a continuación. Consulta [Audits](/es/agenteye/audits). +Una investigación recurrente (desde cada hora hasta semanalmente) que examina tus logs *entre* sesiones en busca de patrones de fallo para los que aún no has escrito una regla: clústeres de errores, puntuaciones bajas, valores atípicos de latencia, bucles de llamadas a herramientas y ejecuciones que nunca terminaron. Mientras que una alerta monitorea una métrica que ya conoces, una auditoría te indica qué deberías analizar a continuación. Consulta [Auditorías](/es/agenteye/audits). **Hallazgo** -Un resultado priorizado y respaldado por evidencia de una ejecución de auditoría. Un hallazgo identifica un patrón, enlaza con las sesiones exactas que lo respaldan y tiene un ciclo de vida de triaje (reconocer, resolver, silenciar, descartar). Failproof AI Observability deduplica los hallazgos entre ejecuciones, de modo que un patrón conocido se actualiza en lugar de acumularse. +Un resultado priorizado y respaldado por evidencia de una ejecución de auditoría. Un hallazgo nombra un patrón, enlaza a las sesiones exactas que lo originan y tiene un ciclo de vida de triaje (reconocer, resolver, silenciar, descartar). Failproof AI Observability elimina duplicados de hallazgos entre ejecuciones, de modo que un patrón conocido se actualiza en lugar de acumularse. **El asistente de IA** -El chat integrado en el panel que responde preguntas sobre tus agentes en lenguaje natural, utilizando tus propios datos. Es de solo lectura por defecto; todo lo que crea (una consulta guardada, un panel de control) requiere aprobación, y nunca puede eliminar datos. Consulta [AI assistant](/es/agenteye/assistant). +El chat integrado en el panel que responde preguntas sobre tus agentes en lenguaje natural, sobre tus propios datos. Es de solo lectura por defecto; cualquier elemento que cree (una consulta guardada, un panel) requiere aprobación, y nunca puede eliminar nada. Consulta [Asistente de IA](/es/agenteye/assistant). --- -## Ejecución +## Funcionamiento **Organización (tenant)** -Un espacio de trabajo aislado. Una instancia de Failproof AI Observability puede albergar muchas organizaciones, cada una con sus propios usuarios, claves y datos. Cada URL del panel está delimitada por el slug de tu organización (`//…`). +Un espacio de trabajo aislado. Una instancia de Failproof AI Observability puede alojar múltiples organizaciones, cada una con sus propios usuarios, claves y datos. Cada URL del panel está delimitada por el slug de tu organización (`//…`). -**Recolector** -`agenteye-collector`, el daemon ligero que se ejecuta en cada máquina de agente, agrupa los eventos que el SDK escribe en disco y los envía al servidor. +**Collector** +`agenteye-collector`, el daemon ligero que se ejecuta en cada máquina del agente, agrupa los eventos que el SDK escribe en disco y los envía al servidor. **Clave de API** -Un token con permisos acotados que autentica a un cliente frente al servidor. Las claves tienen permisos granulares (por ejemplo, `events:add` para el recolector, permisos de solo lectura para una clave de panel). Consulta [API keys](/es/agenteye/api-keys). +Un token con ámbito definido que autentica a un cliente frente al servidor. Las claves llevan permisos detallados (por ejemplo, `events:add` para el collector, ámbitos de solo lectura para una clave de panel). Consulta [Claves de API](/es/agenteye/api-keys). **Servidor** -El servicio de ingesta y API. Recibe eventos, almacena el estado operativo en tus bases de datos y sirve el panel de control y la CLI. +El servicio de ingesta y API. Recibe los eventos, almacena el estado operativo en tus bases de datos y sirve el panel y la CLI. -**Panel de control** -La interfaz web. Cada página está delimitada a una organización y accede a los datos a través de la API del servidor. +**Panel** +La interfaz web. Cada página está delimitada por una organización y se comunica a través de la API del servidor. --- ## Próximos pasos -- [Overview](/es/agenteye/overview): cómo encajan todas estas piezas. -- [Observability](/es/agenteye/observability): las superficies de observabilidad (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file +- [Visión general](/es/agenteye/overview): cómo encajan estas piezas. +- [Observabilidad](/es/agenteye/observability): las superficies de observación (Eventos, Sesiones, Modelos, Herramientas, Hooks, Errores). \ No newline at end of file diff --git a/docs/es/agenteye/dashboards.mdx b/docs/es/agenteye/dashboards.mdx index 5521f920..a554879b 100644 --- a/docs/es/agenteye/dashboards.mdx +++ b/docs/es/agenteye/dashboards.mdx @@ -4,43 +4,43 @@ description: "Convierte los datos en vivo de tus agentes en una vista compartida --- -Convierte los datos en vivo de tus agentes en una vista compartida que todo tu equipo puede consultar. Fija las consultas más importantes como gráficos, y todos verán los mismos números de un vistazo, sin necesidad de volver a ejecutar ni una sola consulta. +Convierte los datos en vivo de tus agentes en una vista compartida que todo tu equipo puede consultar. Ancla las consultas importantes como gráficos y todo el mundo verá los mismos números de un vistazo, sin tener que volver a ejecutar ninguna consulta. -![Un dashboard construido a partir de consultas guardadas: una línea de eventos por hora, una barra de errores por tipo, un gráfico de área de latencia y tokens por modelo](/agenteye/images/dashboard-fleet.png) +![Un dashboard construido con consultas guardadas: una línea de eventos por hora, una barra de errores por tipo, un gráfico de área de latencia y tokens por modelo](/agenteye/images/dashboard-fleet.png) -*Un tablero, cuatro consultas guardadas: eventos por hora, errores por tipo, latencia y tokens por modelo.* +*Un panel, cuatro consultas guardadas: eventos por hora, errores por tipo, latencia y tokens por modelo.* ## Todos ven la misma realidad -Deja de pegar capturas de pantalla en el chat y de volver a ejecutar la misma consulta cinco veces al día. Un dashboard es un tablero compartido a nivel de organización que cualquier miembro de tu equipo puede abrir para ver exactamente la misma información. Cuando los datos subyacentes cambian, los gráficos cambian con ellos, por lo que el tablero siempre está actualizado y nadie discute sobre números desactualizados. +Deja de pegar capturas de pantalla en el chat y de repetir la misma consulta cinco veces al día. Un dashboard es un panel compartido a nivel de organización que cualquier miembro de tu equipo puede abrir para ver exactamente la misma vista. Cuando los datos subyacentes cambian, los gráficos se actualizan con ellos, por lo que el panel siempre está al día y nadie discute sobre cifras desactualizadas. -El dashboard de flota de arriba es un buen punto de partida para las operaciones del día a día: +El dashboard de flota anterior es un buen punto de partida para las operaciones del día a día: -- una línea de **eventos por hora**, para monitorear el rendimiento y detectar caídas repentinas -- una barra de **errores por tipo**, para identificar de inmediato las categorías de fallos más frecuentes -- un gráfico de área de **latencia**, para detectar ralentizaciones antes de que los usuarios se quejen -- un desglose de **tokens por modelo**, para mantener los costos bajo control +- una línea de **eventos por hora**, para monitorizar el rendimiento y detectar caídas repentinas +- una barra de **errores por tipo**, para que las categorías de fallos más frecuentes destaquen a simple vista +- un gráfico de área de **latencia**, para identificar ralentizaciones antes de que los usuarios se quejen +- un desglose de **tokens por modelo**, para mantener los costes bajo control -Encontrarás tus tableros en `//dashboards`. +Encontrarás tus paneles en `//dashboards`. -## Fija las consultas que ya tienes guardadas +## Ancla las consultas que ya tienes guardadas -Cada mosaico comienza como una consulta guardada. Crea y guarda la consulta que necesitas en la biblioteca de [Consultas](/es/agenteye/queries) (presets integrados más los tuyos propios, sobre tus eventos y evaluaciones), y luego fíjala en un dashboard como el gráfico que mejor se adapte a los datos: una **línea** para tendencias en el tiempo, una **barra** para comparar categorías, un **área** para volumen, o un **pastel** para mostrar proporciones. +Cada tile comienza como una consulta guardada. Crea y guarda la consulta que te interese en la biblioteca de [Queries](/es/agenteye/queries) (con presets integrados y los tuyos propios, sobre tus eventos y evaluaciones) y luego ancla el gráfico que mejor se adapte a los datos: una **línea** para tendencias a lo largo del tiempo, una **barra** para comparar categorías, un **área** para volumen o un **pie** para distribuciones porcentuales. -Como un mosaico no es más que tu consulta guardada representada como gráfico, no hay nada que mantener sincronizado manualmente. Actualiza la consulta una vez y todos los dashboards que la usan se actualizan también. +Como un tile es simplemente tu consulta guardada renderizada como gráfico, no hay nada que mantener sincronizado manualmente. Actualiza la consulta una vez y todos los dashboards que la usen se actualizarán también. -## Monitorea la calidad, no solo el volumen +## Monitoriza la calidad, no solo el volumen -El volumen te dice que los agentes están ocupados. La calidad te dice que realmente están haciendo bien su trabajo. Apunta un dashboard a tus [puntuaciones de evaluación](/es/agenteye/evaluations) y obtendrás un tablero que rastrea el rendimiento de las ejecuciones a lo largo del tiempo, de modo que una regresión de calidad aparece como una caída en el gráfico en lugar de como una sorpresa de un cliente. +El volumen te dice que los agentes están ocupados. La calidad te dice si realmente están haciendo bien su trabajo. Apunta un dashboard a tus [puntuaciones de evaluación](/es/agenteye/evaluations) y obtendrás un panel que rastrea el rendimiento de las ejecuciones a lo largo del tiempo, de modo que una regresión de calidad aparece como una caída en un gráfico en lugar de ser una sorpresa que llega de un cliente. -![Un dashboard enfocado en calidad, construido a partir de consultas de evaluación guardadas](/agenteye/images/dashboard-quality.png) +![Un dashboard centrado en calidad construido con consultas de evaluación guardadas](/agenteye/images/dashboard-quality.png) -*Un tablero de calidad mantiene tus puntuaciones de evaluación en primer plano, justo junto a los números operativos.* +*Un panel de calidad mantiene tus puntuaciones de evaluación en primer plano, junto a los números operacionales.* -Mantén un tablero de operaciones y un tablero de calidad lado a lado, y tu equipo tendrá un único lugar para responder tanto "¿está funcionando?" como "¿lo está haciendo bien?", sin que nadie tenga que volver a ejecutar una consulta. +Mantén un panel de operaciones y un panel de calidad lado a lado y tu equipo tendrá un único lugar donde responder tanto a "¿está funcionando?" como a "¿está funcionando bien?", sin que nadie tenga que volver a ejecutar una consulta. -## Relacionados +## Relacionado -- [Consultas](/es/agenteye/queries): crea y guarda las consultas que se convertirán en tus mosaicos. -- [Evaluaciones](/es/agenteye/evaluations): puntúa tus ejecuciones para poder graficar la calidad a lo largo del tiempo. -- [Alertas](/es/agenteye/alerts): convierte un umbral en cualquiera de estas métricas en una notificación. \ No newline at end of file +- [Queries](/es/agenteye/queries): crea y guarda las consultas que se convertirán en tus tiles. +- [Evaluations](/es/agenteye/evaluations): puntúa tus ejecuciones para poder graficar la calidad a lo largo del tiempo. +- [Alerts](/es/agenteye/alerts): convierte un umbral sobre cualquiera de estas métricas en una notificación. \ No newline at end of file diff --git a/docs/es/agenteye/error-tracking.mdx b/docs/es/agenteye/error-tracking.mdx index 536c3e81..b6354690 100644 --- a/docs/es/agenteye/error-tracking.mdx +++ b/docs/es/agenteye/error-tracking.mdx @@ -1,37 +1,37 @@ --- title: "Seguimiento de Errores" -description: "Ve todos los fallos que producen tus agentes en un solo lugar, agrupados para que una ráfaga ruidosa se lea como un único problema." +description: "Consulta todos los fallos de tus agentes en un solo lugar, agrupados para que una ráfaga de errores se lea como un único problema." --- -Ve todos los fallos que producen tus agentes en un solo lugar, agrupados para que una ráfaga ruidosa se lea como un único problema. Tienes un camino de un solo clic desde "algo está en rojo" hasta la ejecución exacta que falló, sin tener que desplazarte por un feed en vivo para encontrarlo. +Consulta todos los fallos de tus agentes en un solo lugar, agrupados para que una ráfaga de errores se lea como un único problema. Tienes un acceso directo desde «algo está en rojo» hasta la ejecución exacta que falló, sin necesidad de desplazarte por un feed en vivo para encontrarlo. -![La página de Errores: un histograma de fallos a lo largo del tiempo encima de filas de errores en rojo agrupados, cada una con un botón "+ alert" de un solo clic](/agenteye/images/errors.png) -*La página de Errores: un histograma de fallos a lo largo del tiempo, con los fallos repetidos colapsados en una sola fila por incidente.* +![La página de Errores: un histograma de fallos a lo largo del tiempo sobre filas de errores en rojo agrupadas, cada una con un botón «+ alert» con un solo clic](/agenteye/images/errors.png) +*La página de Errores: un histograma de fallos a lo largo del tiempo, con los fallos repetidos agrupados en una sola fila por incidente.* ## Todos los fallos, ya recopilados por ti -Cuando un agente falla, no deberías tener que desplazarte por un stream de eventos en vivo esperando capturar las filas en rojo antes de que desaparezcan. La página **Errors** se encarga de la recopilación por ti. Reúne todo lo que el panel pintaría de rojo en una única superficie de triaje, para que lo primero que veas sea qué está fallando, no dónde tienes que ir a buscarlo. +Cuando un agente falla, no deberías tener que desplazarte por un flujo de eventos en vivo esperando capturar las filas rojas antes de que desaparezcan. La página **Errors** se encarga de recopilarlos por ti. Reúne todo lo que el panel marcaría en rojo en una única superficie de triaje, así que lo primero que ves es qué está fallando, no dónde buscarlo. -Y detecta más que los fallos obvios. Además de los eventos explícitos de tipo `error`, Failproof AI Observability también muestra los fallos silenciosos: cualquier `tool_result`, `hook_completed` o `agent_end` cuyo payload contenga un fallo aparece aquí. Una herramienta que devolvió un error, o un hook que terminó mal, ya no pasa desapercibido simplemente porque nada lanzó una excepción sonora. +Y detecta más que los fallos evidentes. Además de los eventos `error` explícitos, Failproof AI Observability también muestra los fallos silenciosos: cualquier `tool_result`, `hook_completed` o `agent_end` cuyo payload indique un fallo aparecerá aquí. Una herramienta que devolvió un error, o un hook que terminó de forma incorrecta, ya no pasa desapercibida simplemente porque no se lanzó una excepción ruidosa. -En la parte superior, un histograma muestra los errores a lo largo del tiempo. Un vistazo te dice si se trata de un goteo de fondo constante o de un pico que empezó hace unos minutos, para que sepas de inmediato si debes dejar lo que estás haciendo. +En la parte superior, un histograma muestra los errores a lo largo del tiempo. Un vistazo te indica si se trata de un goteo constante en segundo plano o de un pico que comenzó hace unos minutos, así que sabes de inmediato si debes dejarlo todo. -Como cualquier superficie de observabilidad, la página de Errores está delimitada por tu organización y se filtra por rango de fechas, entorno, agente y sesión. Eso significa que puedes partir de una lista de toda la flota y reducirla al agente o al entorno que realmente te interesa. +Como todas las superficies de observación, la página de Errores está delimitada por tu organización y permite filtrar por rango de fechas, entorno, agente y sesión. Esto significa que puedes partir de una lista de toda la flota y reducirla al agente o al entorno que realmente te importa. ## Un incidente, no cien filas idénticas -Una sola dependencia rota puede disparar el mismo error cientos de veces por minuto. Tal cual, eso es una pared de líneas casi idénticas que entierra lo único que realmente necesitas ver. +Una sola dependencia rota puede generar el mismo error cientos de veces por minuto. Sin procesar, eso se convierte en una pared de líneas casi idénticas que entierra lo único que realmente necesitas ver. -Failproof AI Observability colapsa los fallos repetidos que comparten la misma sesión y tipo de error en una sola fila. Una ráfaga se lee como un único incidente. Acabas contando problemas, no líneas de log, y la señal que importa se mantiene en primer plano en lugar de ahogarse en su propio volumen. +Failproof AI Observability agrupa los fallos repetidos que comparten la misma sesión y tipo de error en una única fila. Una ráfaga se lee como un solo incidente. Acabas contando problemas, no líneas de log, y la señal que importa permanece visible en lugar de quedar ahogada por su propio volumen. -## De "algo está en rojo" al evento exacto +## De «algo está en rojo» al evento exacto -Haz clic en cualquier fila para ir directamente al interior de la sesión de esa ejecución, posicionado en el evento exacto que falló. Sin copiar IDs de sesión, sin desplazarte buscando el momento en que algo salió mal: llegas justo ahí, con el grafo de ejecución completo a un vistazo para que puedas ver qué hizo el agente en los momentos previos al fallo. +Haz clic en cualquier fila para ir directamente a la sesión de esa ejecución, posicionado en el evento exacto que falló. Sin copiar IDs de sesión, sin desplazarte para buscar el momento en que algo salió mal: llegas justo ahí, con el gráfico de ejecución completo a un vistazo para que puedas ver qué hizo el agente momentos antes de fallar. -Si tienes `alerts:write`, cada fila también incluye un botón **+ alert**. Haz clic en él y Observability abre una nueva regla de alerta ya configurada para detectar ese mismo fallo de nuevo. El incidente que acabas de triar se convierte en el que te avisará la próxima vez, en lugar de sorprenderte dos veces. +Si tienes `alerts:write`, cada fila también incluye un botón **+ alert**. Haz clic en él y Observability abre una nueva regla de alerta ya rellenada para detectar ese mismo fallo en el futuro. El incidente que acabas de triagear se convierte en el que te notificará la próxima vez, en lugar de sorprenderte dos veces. -**Dónde encontrarlo:** la página **Errors** se encuentra en la sección de observabilidad del panel, en `//errors`. +**Dónde encontrarlo:** la página **Errors** se encuentra en la sección de observación del panel, en `//errors`. ## Relacionado diff --git a/docs/es/agenteye/evaluation-suite.mdx b/docs/es/agenteye/evaluation-suite.mdx index 202347ab..30c362fc 100644 --- a/docs/es/agenteye/evaluation-suite.mdx +++ b/docs/es/agenteye/evaluation-suite.mdx @@ -1,22 +1,22 @@ --- -title: "Suite de Evaluación" -description: "Failproof AI Observability puede puntuar automáticamente cada ejecución de agente finalizada: tú proporcionas un pequeño servicio de puntuación y Observability se encarga del resto." +title: "Suite de evaluación" +description: "Failproof AI Observability puede puntuar automáticamente cada ejecución de agente finalizada según su calidad: tú proporcionas un pequeño servicio de puntuación y Observability se encarga del resto." --- -Failproof AI Observability puede puntuar automáticamente cada ejecución de agente finalizada para medir su calidad: tú proporcionas un pequeño servicio de puntuación y Observability se encarga del resto. Úsalo para rastrear las dimensiones que te importan (utilidad, eficiencia de herramientas, factualidad, seguridad; tú decides), detectar regresiones a tiempo y comparar agentes o entornos de un vistazo. La puntuación es opcional: el pipeline no hace nada hasta que configures `EVALUATOR_ENDPOINT` en el servidor. +Failproof AI Observability puede puntuar automáticamente cada ejecución de agente finalizada según su calidad: tú proporcionas un pequeño servicio de puntuación y Observability se encarga del resto. Úsalo para rastrear las dimensiones que te importan (utilidad, eficiencia de herramientas, veracidad, seguridad; tú eliges), detectar regresiones a tiempo y comparar agentes o entornos de un vistazo. La puntuación es opcional: el pipeline no hace nada hasta que configures `EVALUATOR_ENDPOINT` en el servidor. -> **Nota:** Tú defines las dimensiones de puntuación. Tu evaluador puede devolver las claves numéricas que quiera; Observability almacena, analiza tendencias y muestra todo lo que le envíes. +> **Nota:** Tú defines las dimensiones de puntuación. Tu evaluador puede devolver las claves numéricas que quiera; Observability almacena, analiza tendencias y muestra todo lo que envíes. -## Resumen rápido +## Resumen -1. **Escribe un evaluador.** Levanta un pequeño servicio HTTP que lea la transcripción de una sesión y devuelva puntuaciones. Observability incluye una referencia funcional que puedes copiar. Consulta [Escribir un evaluador con el SDK](#writing-an-evaluator-with-the-sdk). -2. **Apunta Observability hacia él.** Configura `EVALUATOR_ENDPOINT` (y un `EVALUATOR_TOKEN` compartido) en el proceso del servidor. +1. **Escribe un puntuador.** Levanta un pequeño servicio HTTP que lea la transcripción de una sesión y devuelva puntuaciones. Observability incluye una referencia funcional que puedes copiar. Consulta [Escribir un evaluador con el SDK](#writing-an-evaluator-with-the-sdk). +2. **Apunta Observability hacia él.** Establece `EVALUATOR_ENDPOINT` (y un `EVALUATOR_TOKEN` compartido) en el proceso del servidor. 3. **Observa cómo llegan las puntuaciones.** Cada sesión completada se puntúa automáticamente; los resultados aparecen en la página de detalle de sesión, la cuadrícula de sesiones y los dashboards guardados. -![Vista de detalle de sesión con el resumen de evaluación, barras de puntuación por dimensión y texto de razonamiento en el panel lateral derecho](/agenteye/images/session-detail.png) +![Vista de detalle de una sesión con el resumen de evaluación, barras de puntuación por dimensión y texto de razonamiento en el panel derecho](/agenteye/images/session-detail.png) -*Una vez configurado un evaluador, cada ejecución completada recibe una puntuación y los resultados aparecen en el panel lateral derecho de la sesión: el resumen en la parte superior, seguido de barras de puntuación por dimensión con su razonamiento.* +*Una vez configurado un evaluador, cada ejecución completada se puntúa y los resultados aparecen en el panel derecho de la sesión: el resumen en la parte superior, seguido de las barras de puntuación por dimensión con el razonamiento correspondiente.* --- @@ -32,42 +32,42 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Cuando el SDK de Observability emite un evento `agent_end` para una sesión, el servidor programa una evaluación. Luego envía mediante POST la transcripción completa de eventos a tu servicio evaluador, que puede: +Cuando el SDK de Observability emite un evento `agent_end` para una sesión, el servidor programa una evaluación. A continuación, envía mediante POST la transcripción completa de eventos a tu servicio evaluador, que puede: -- **Devolver el resultado de forma inmediata** con `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. El resultado se añade a la línea temporal de evaluaciones de la sesión. `reasoning` y `summary` son opcionales. -- **Diferir la respuesta** con `{"status":"pending", "job_id":"abc-123"}`. Observability entonces llama a `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` hasta que tu evaluador devuelva `{"status":"done", ...}` o `{"status":"error", "error":"..."}`. +- **Devolver el resultado de forma inmediata** con `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. El resultado se añade a la línea de tiempo de evaluación de la sesión. `reasoning` y `summary` son opcionales. +- **Diferir** con `{"status":"pending", "job_id":"abc-123"}`. Observability entonces llama a `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` hasta que tu evaluador devuelve `{"status":"done", ...}` o `{"status":"error", "error":"..."}`. - La cadencia de sondeo es por trabajo: una respuesta `pending` puede incluir `next_poll_secs` para sobreescribirla; de lo contrario, Observability usa el valor `default_poll_interval_secs` de `GET /config`; si tampoco está definido, el servidor recurre a `EVALUATOR_POLLING_INTERVAL_SECS` (10s por defecto). Todos los valores se limitan al rango [1s, 1h]. + La cadencia de sondeo es por trabajo: una respuesta `pending` puede incluir `next_poll_secs` para sobreescribirla; de lo contrario, Observability usa el valor `default_poll_interval_secs` de `GET /config`; si tampoco está disponible, el servidor recurre a `EVALUATOR_POLLING_INTERVAL_SECS` (por defecto 10s). Todos los valores se limitan al rango [1s, 1h]. -Las sesiones que nunca emiten `agent_end` (por ejemplo, un proceso de agente que se ha bloqueado) también pueden procesarse: el `GET /config` del evaluador puede devolver `{"inactivity_timeout_secs": 1800}`, y Observability evaluará cualquier sesión que haya estado inactiva durante ese tiempo. Establece el campo en `null` u omítelo para desactivar este comportamiento alternativo. +Las sesiones que nunca emiten `agent_end` (por ejemplo, un proceso de agente que se ha bloqueado) también pueden procesarse: el `GET /config` del evaluador puede devolver `{"inactivity_timeout_secs": 1800}`, y Observability evaluará cualquier sesión que haya permanecido inactiva durante ese tiempo. Establece el campo como `null` u omítelo para deshabilitar esta alternativa. El pipeline es completamente inactivo cuando `EVALUATOR_ENDPOINT` no está configurado. -Una sesión puede acumular **múltiples evaluaciones terminales a lo largo del tiempo**: cada evento `agent_end` (y cada re-evaluación manual desde el dashboard) añade una nueva fila de evaluación. Esta es la forma admitida de evaluar una conversación reanudada: un usuario termina un agente, vuelve más tarde, envía más eventos, vuelve a terminar el agente y se ejecuta una segunda evaluación sobre la transcripción completa actualizada. El dashboard muestra la evaluación más reciente como titular y las evaluaciones anteriores como una línea temporal plegable. Mientras se ejecuta una evaluación para una sesión, los eventos `agent_end` adicionales para esa sesión se ignoran; el siguiente que llegue después de que la evaluación en curso complete pondrá en cola una nueva evaluación como de costumbre. +Una sesión puede acumular **múltiples evaluaciones terminales a lo largo del tiempo**: cada evento `agent_end` (y cada re-evaluación manual desde el dashboard) añade una nueva fila de evaluación. Esta es la forma recomendada de evaluar una conversación reanudada: un usuario termina un agente, vuelve más tarde, envía más eventos, termina el agente de nuevo, y se ejecuta una segunda evaluación contra la transcripción completa actualizada. El dashboard muestra la evaluación más reciente como titular y las evaluaciones anteriores como una línea de tiempo plegable. Mientras se ejecuta una evaluación para una sesión, los eventos `agent_end` adicionales para esa sesión se ignoran; el siguiente después de que termine la evaluación en curso pondrá en cola una nueva evaluación como de costumbre. -La recuperación por inactividad también se activa en sesiones reanudadas: si llegan nuevos eventos después de una evaluación terminal anterior y la sesión vuelve a quedar inactiva pasando el umbral de `inactivity_timeout_secs`, se pone en cola una nueva evaluación. +La alternativa por inactividad también se reactiva en sesiones reanudadas: si llegan nuevos eventos después de una evaluación terminal previa y la sesión luego queda inactiva más allá de `inactivity_timeout_secs`, se pone en cola una nueva evaluación. -Los fallos transitorios (5xx, 429, timeouts, errores de red) se reintentan con retroceso exponencial hasta `EVALUATOR_MAX_ATTEMPTS`; las respuestas 4xx son terminales. Observability es seguro de ejecutar con múltiples instancias de servidor escaladas horizontalmente; el trabajo se distribuye de forma que la misma sesión nunca se despacha dos veces de forma concurrente. +Los fallos transitorios (5xx, 429, timeouts, errores de red) se reintentan con retroceso exponencial hasta `EVALUATOR_MAX_ATTEMPTS`; las respuestas 4xx son terminales. Observability puede ejecutarse de forma segura con múltiples instancias de servidor escaladas horizontalmente; el trabajo se particiona para que la misma sesión nunca se despache dos veces de forma concurrente. --- ## Contrato HTTP -Todas las rutas autenticadas usan **autenticación mediante token bearer**. El mismo valor debe configurarse en ambos lados: +Todas las rutas autenticadas usan **autenticación con token de portador (bearer)**. El mismo valor debe configurarse en ambos lados: - Servidor de Observability: variable de entorno `EVALUATOR_TOKEN` - Servicio evaluador: configurado de la misma forma (el SDK `agenteye-evaluator` lee `EVALUATOR_TOKEN` por convención) -Si `EVALUATOR_TOKEN` no está configurado, el servidor no envía cabecera `Authorization`; el evaluador puede entonces aceptar solicitudes anónimas, lo cual es aceptable en una red exclusivamente interna pero no recomendado en internet público. +Si `EVALUATOR_TOKEN` no está configurado, el servidor no envía ningún encabezado `Authorization`; el evaluador puede entonces aceptar solicitudes anónimas, lo cual está bien para una red interna, pero no se recomienda en internet público. -### Rutas que el evaluador debe servir +### Rutas que debe servir el evaluador | Ruta | Cuerpo / parámetros | Respuesta | |---|---|---| -| `GET /health` | ninguno | `{"status":"ok"}` (abierta, sin autenticación) | +| `GET /health` | ninguno | `{"status":"ok"}` (abierta, sin auth) | | `GET /config` | ninguno | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | | `POST /evaluate` | JSON `EvalRequest` | `{"status":"done", ...}` o `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | ninguno | mismo formato de respuesta que `/evaluate` | +| `GET /evaluate/{id}` | ninguno | misma forma de respuesta que `/evaluate` | ### Cuerpo `EvalRequest` enviado por el servidor @@ -86,9 +86,9 @@ Si `EVALUATOR_TOKEN` no está configurado, el servidor no envía cabecera `Autho } ``` -### Formatos de respuesta +### Formas de respuesta -**Síncrono (done):** +**Síncrona (done):** ```json { @@ -102,9 +102,9 @@ Si `EVALUATOR_TOKEN` no está configurado, el servidor no envía cabecera `Autho } ``` -`reasoning` (un mapa de justificación por puntuación) y `summary` (una narrativa general de un párrafo) son ambos opcionales. Las claves de `reasoning` deben coincidir con las claves de `scores`; el dashboard renderiza cada entrada bajo su barra de puntuación. Los evaluadores más antiguos que solo devuelven `scores` siguen funcionando sin cambios; `reasoning` y `summary` simplemente se leen como null y los elementos de UI correspondientes se omiten. +`reasoning` (un mapa de justificación por puntuación) y `summary` (una narrativa general de un párrafo) son ambos opcionales. Las claves en `reasoning` deben reflejar las claves en `scores`; el dashboard muestra cada entrada bajo su barra de puntuación. Los evaluadores más antiguos que devuelven solo `scores` siguen funcionando sin cambios; `reasoning` y `summary` simplemente se leen como nulos y se omiten los elementos correspondientes de la interfaz. -**Asíncrono (diferido):** +**Asíncrona (diferida):** ```json { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } @@ -112,7 +112,7 @@ Si `EVALUATOR_TOKEN` no está configurado, el servidor no envía cabecera `Autho `next_poll_secs` es opcional; si se omite, el servidor recurre al `default_poll_interval_secs` del evaluador desde `/config`, y luego a su propia variable de entorno `EVALUATOR_POLLING_INTERVAL_SECS`. -**Error terminal en el lado del evaluador:** +**Error terminal del lado del evaluador:** ```json { "status": "error", "error": "model service unavailable" } @@ -124,9 +124,9 @@ El servidor trata cualquier otro cuerpo 2xx como un error de protocolo y registr ## Escribir un evaluador con el SDK -No tienes que implementar el contrato HTTP a mano. El paquete Python `agenteye-evaluator` te proporciona un wrapper tipado de FastAPI que gestiona la autenticación, el enrutamiento y los formatos de solicitud/respuesta por ti. +No es necesario implementar el contrato HTTP manualmente. El paquete Python `agenteye-evaluator` te proporciona un wrapper FastAPI tipado que gestiona la autenticación, el enrutamiento y las formas de solicitud/respuesta por ti. -Failproof AI Observability también incluye un **evaluador de referencia funcional** que puntúa `helpfulness`, `tool_efficiency` y `factuality` a partir de la estructura de la transcripción. Cópialo como punto de partida y sustituye la lógica por la tuya: un juez LLM, un motor de reglas, lo que mejor se adapte a tu criterio de calidad. +Failproof AI Observability también incluye un **evaluador de referencia funcional** que puntúa `helpfulness`, `tool_efficiency` y `factuality` a partir de la forma de la transcripción. Cópialo como punto de partida y sustitúyelo con tu propia lógica: un juez LLM, un motor de reglas, o lo que mejor se adapte a tus criterios de calidad. Evaluador mínimo viable: @@ -149,7 +149,7 @@ def run(req: EvalRequest) -> EvalResponse: La instancia `app` se ejecuta bajo cualquier servidor ASGI, por lo que `uvicorn module:app` la pone en marcha. -Para evaluadores que necesitan diferir trabajo costoso, devuelve `JobPending` en su lugar y registra un handler `@app.job_lookup`; el servidor de Observability sondea `GET /evaluate/{job_id}` hasta que devuelves un estado terminal o se agota el límite de `EVALUATOR_MAX_POLL_DURATION_SECS` (1 h por defecto). +Para los evaluadores que necesitan diferir trabajo costoso, devuelve `JobPending` en su lugar y registra un manejador `@app.job_lookup`; el servidor de Observability sondea `GET /evaluate/{job_id}` hasta que devuelves un estado terminal o se agota el límite `EVALUATOR_MAX_POLL_DURATION_SECS` (por defecto 1 h). La referencia completa de la API, el patrón asíncrono y el esquema de eventos están documentados en el README del SDK `agenteye-evaluator`. @@ -157,9 +157,9 @@ La referencia completa de la API, el patrón asíncrono y el esquema de eventos ## Ejecutar tu evaluador -El evaluador es **tu servicio** — Failproof AI Observability no incluye un evaluador por defecto, así que lo construyes y ejecutas donde ejecutas tus propios servicios. Se ejecuta bajo cualquier servidor ASGI (por ejemplo `uvicorn my_evaluator:app`); sirve las rutas `/health`, `/config` y `/evaluate` del [contrato HTTP](#http-contract) y luego apunta el servidor hacia él (consulta [Configurar el servidor](#configuring-the-server)). +El evaluador es **tu servicio** — Failproof AI Observability no incluye un evaluador predeterminado, por lo que tú lo construyes y ejecutas donde ejecutas tus propios servicios. Se ejecuta bajo cualquier servidor ASGI (por ejemplo `uvicorn my_evaluator:app`); sirve las rutas `/health`, `/config` y `/evaluate` del [contrato HTTP](#http-contract), y luego apunta el servidor hacia él (consulta [Configurar el servidor](#configuring-the-server)). -Una vez que el evaluador sea accesible, `GET /health` devuelve `{"status":"ok"}`. Después de que un agente se ejecute de principio a fin, `GET /evaluations` en el servidor devuelve una fila con `status: "done"` y las puntuaciones que produjo tu evaluador. +Una vez que el evaluador sea accesible, `GET /health` devuelve `{"status":"ok"}`. Después de que un agente se ejecute de extremo a extremo, `GET /evaluations` en el servidor devuelve una fila con `status: "done"` y las puntuaciones que produjo tu evaluador. --- @@ -169,38 +169,38 @@ Establece en el proceso del servidor: | Variable de entorno | Significado | |---|---| -| `EVALUATOR_ENDPOINT` | URL base de tu evaluador (`http://evaluator:9000`). Sin definir = pipeline desactivado. | -| `EVALUATOR_TOKEN` | Token bearer. Debe coincidir con el valor configurado en el servicio evaluador. | +| `EVALUATOR_ENDPOINT` | URL base de tu evaluador (`http://evaluator:9000`). Si no está configurada, el pipeline queda deshabilitado. | +| `EVALUATOR_TOKEN` | Token de portador (bearer). Debe coincidir con el valor configurado en el servicio evaluador. | | `EVALUATOR_WORKERS` | Tareas de worker por instancia de servidor (por defecto 2). | -| `EVALUATOR_CLAIM_BATCH` | Filas reclamadas por tick de worker (por defecto 4). Los lotes se procesan **de forma concurrente**; la concurrencia efectiva en tu endpoint del evaluador es `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Tiempo que un worker duerme entre intentos de despacho cuando no hay ninguna evaluación pendiente (por defecto 2s). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Reserva final para la cadencia de `GET /evaluate/{id}` cuando no se ha definido ni el `next_poll_secs` por respuesta ni el `default_poll_interval_secs` del evaluador (por defecto 10s). | +| `EVALUATOR_CLAIM_BATCH` | Filas reclamadas por ciclo de worker (por defecto 4). Los lotes se procesan de forma **concurrente**; la concurrencia efectiva en tu endpoint evaluador es `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Tiempo que un worker duerme entre intentos de despacho cuando no hay evaluación pendiente (por defecto 2s). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Alternativa final para la cadencia de `GET /evaluate/{id}` cuando ni `next_poll_secs` por respuesta ni `default_poll_interval_secs` del evaluador están configurados (por defecto 10s). | | `EVALUATOR_REQUEST_TIMEOUT_MS` | Timeout por solicitud (por defecto 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | Tras este número de fallos transitorios, el resultado se registra como `error` terminal (por defecto 5). | +| `EVALUATOR_MAX_ATTEMPTS` | Después de este número de fallos transitorios, el resultado se registra como `error` terminal (por defecto 5). | | `EVALUATOR_CONFIG_REFRESH_SECS` | Cadencia de `GET /config` (por defecto 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Tiempo máximo en tiempo real que una sesión puede permanecer en la cola de sondeo antes de terminar como `timeout` (por defecto 3600s). Protege contra un evaluador que sigue devolviendo `pending` indefinidamente. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Tiempo máximo en tiempo real que una sesión puede permanecer en la cola de sondeo antes de ser terminada como `timeout` (por defecto 3600s). Protege contra un evaluador que sigue devolviendo `pending` indefinidamente. | -Para activar la puntuación automática, define tanto `EVALUATOR_ENDPOINT` como `EVALUATOR_TOKEN` en el servidor y reinícialo para que tome los cambios. Con `EVALUATOR_ENDPOINT` sin definir, el pipeline permanece inactivo. +Para activar la puntuación automática, establece tanto `EVALUATOR_ENDPOINT` como `EVALUATOR_TOKEN` en el servidor y reinícialo para aplicar el cambio. Con `EVALUATOR_ENDPOINT` sin configurar, el pipeline permanece inactivo. -Los parámetros de ajuste anteriores son opcionales; configura las variables de entorno correspondientes en el servidor solo si necesitas sobreescribir los valores por defecto. +Las variables de ajuste anteriores son opcionales; establece las variables de entorno correspondientes en el servidor solo si necesitas sobreescribir los valores predeterminados. --- -## Referencia de la API +## Referencia de API | Método | Ruta | Permiso requerido | Propósito | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Consultar resultados terminales. Admite `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` tiene por defecto 50 y un máximo de 200 (a diferencia de `/events`, que tiene un máximo de 1000). `environment` acepta una lista separada por comas (p. ej. `environment=prod,staging`); los valores individuales siguen funcionando. Con `latest_per_session=true`, la respuesta contiene como máximo una fila por `session_id` (la más reciente por `completed_at`), utilizada por la página de lista de sesiones para colapsar la línea temporal de evaluaciones de una sesión a su titular actual. Por defecto es false (devuelve el historial completo). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | Métricas resumidas de salud de evaluación para un subconjunto filtrado: total, desglose por done/error/timeout, estadísticas por clave de puntuación (count/avg/min/max/p50 sobre las claves arbitrarias de `scores`), y una línea temporal por intervalos de tiempo. Acepta los **mismos parámetros de filtro que `/evaluations`** más `featured_keys` (CSV de claves de puntuación para mostrar en tendencias) y `latest_per_session`. Da soporte a la función de Dashboards; las métricas son exactas sobre todo el conjunto coincidente, no muestreadas. | -| `GET` | `/evaluations/environments` | `evaluations:read` | Valores de entorno distintos de la tabla `evaluations`. Se usa para poblar los desplegables de filtro con datos de evaluación. | -| `GET` | `/evaluation-jobs` | `evaluations:read` | Visibilidad de las evaluaciones en curso. Filtra por `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | Transmitir los eventos brutos de una sesión. Admite `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` y `order`. `order` es `desc` (los más recientes primero, por defecto) o `asc` (los más antiguos primero); un valor no reconocido vuelve a `desc`. Pagina mediante el `next_cursor` de la respuesta (un id de evento): pásalo de nuevo como `cursor` para obtener la siguiente página; con `asc` la siguiente página contiene los eventos después de ese id, con `desc` los eventos anteriores. `limit` tiene por defecto 50 y un máximo de 1000. | -| `GET` | `/sessions/:session_id/export` | `events:read` | Devuelve exactamente el cuerpo JSON que recibiría el evaluador para esta sesión, servido como archivo adjunto descargable llamado `session-.json`. Útil para reproducir sesiones de producción a través de `agenteye-evaluator` para pruebas sin conexión. Los bytes son idénticos byte a byte a lo que envía el pipeline del evaluador. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Encola una nueva evaluación para una sesión; se ejecuta independientemente de si existe una evaluación previa. El nuevo resultado se **añade** a la línea temporal de evaluaciones de la sesión en lugar de sobreescribir la anterior, por lo que las puntuaciones previas permanecen visibles como historial. Devuelve `202` al encolar, `404` para una sesión desconocida, `409` si ya hay una evaluación en curso. Úsalo tras desplegar un nuevo evaluador, o para sesiones que nunca emitieron `agent_end`. | +| `GET` | `/evaluations` | `evaluations:read` | Consultar resultados terminales. Admite `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` tiene por defecto 50 y se limita a 200 (nota: esto difiere de `/events`, que se limita a 1000). `environment` acepta una lista separada por comas (p. ej. `environment=prod,staging`); los valores individuales también funcionan. Con `latest_per_session=true`, la respuesta contiene como máximo una fila por `session_id` (la más reciente según `completed_at`), utilizada por la página de lista de sesiones para colapsar la línea de tiempo de evaluación de una sesión a su titular actual. Por defecto es false (devuelve el historial completo). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | Resumen de salud de evaluación para un subconjunto filtrado: recuento total, desglose done/error/timeout, estadísticas por clave de puntuación (count/avg/min/max/p50 sobre las claves arbitrarias de `scores`) y una línea de tiempo agrupada por tiempo. Acepta los **mismos parámetros de filtro que `/evaluations`** más `featured_keys` (CSV de claves de puntuación para tendencias) y `latest_per_session`. Alimenta la función de Dashboards; las métricas son exactas sobre todo el conjunto coincidente, no muestras. | +| `GET` | `/evaluations/environments` | `evaluations:read` | Valores de entorno distintos de la tabla `evaluations`. Se usa para poblar los menús desplegables de filtro limitados a datos legibles de evaluación. | +| `GET` | `/evaluation-jobs` | `evaluations:read` | Visibilidad sobre las evaluaciones en curso. Filtra por `status` (`pending`/`polling`). | +| `GET` | `/events` | `events:read` | Transmite los eventos sin procesar de una sesión. Admite `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` y `order`. `order` puede ser `desc` (más reciente primero, por defecto) o `asc` (más antiguo primero); un valor no reconocido vuelve a `desc`. Pagina mediante cursores usando el `next_cursor` de la respuesta (un id de evento): pásalo de vuelta como `cursor` para obtener la siguiente página; con `asc` la siguiente página son los eventos posteriores a ese id, con `desc` los anteriores. `limit` tiene por defecto 50 y se limita a 1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | Devuelve el cuerpo JSON exacto que el evaluador recibiría para esta sesión, servido como archivo adjunto descargable con el nombre `session-.json`. Útil para reproducir sesiones de producción con `agenteye-evaluator` para pruebas sin conexión. Los bytes son idénticos a los que envía el pipeline del evaluador. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Pone en cola una nueva evaluación para una sesión; se ejecuta tanto si existe una evaluación previa como si no. El nuevo resultado se **añade** a la línea de tiempo de evaluación de la sesión en lugar de sobreescribir el anterior, por lo que las puntuaciones previas permanecen visibles como historial. Devuelve `202` al poner en cola, `404` para una sesión desconocida, `409` si ya hay una evaluación en curso. Útil después de desplegar un nuevo evaluador, o para sesiones que nunca emitieron `agent_end`. | ### Filtrar por rango de puntuación: `score_filters` -`GET /evaluations` acepta un parámetro opcional `score_filters` que reduce los resultados por valores numéricos dentro del objeto `scores`. El parámetro es una lista separada por comas de entradas `key:min..max`; cualquiera de los límites puede omitirse. Múltiples entradas se combinan con AND lógico. Las filas donde la clave nombrada está ausente o no es numérica quedan excluidas. Una solicitud puede tener como máximo 20 entradas de filtro; superarlo devuelve HTTP 400. +`GET /evaluations` acepta un parámetro opcional `score_filters` que acota los resultados por valores numéricos dentro del objeto `scores`. El parámetro es una lista separada por comas de entradas `key:min..max`; cualquiera de los límites puede omitirse. Múltiples entradas se combinan con AND lógico. Las filas donde la clave nombrada está ausente o no es numérica quedan excluidas. Una solicitud puede contener como máximo 20 entradas de filtro; superarlo devuelve HTTP 400. Ejemplos: ```text @@ -210,7 +210,7 @@ GET /evaluations?score_filters=helpfulness:0.5..0.8 # tool_efficiency como máximo 0.3 (sin límite inferior) GET /evaluations?score_filters=tool_efficiency:..0.3 -# helpfulness >= 0.5 AND factuality >= 0.9 +# helpfulness >= 0.5 Y factuality >= 0.9 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` @@ -220,81 +220,81 @@ Cada objeto de respuesta de `/evaluations` tiene estos campos: |---|---|---| | `evaluation_id` | string (UUID) | El identificador canónico de esta evaluación terminal. Cada evaluación terminal recibe un nuevo UUID; una sola sesión puede tener múltiples. | | `id` | string (UUID) | Alias de compatibilidad hacia atrás que lleva el mismo valor que `evaluation_id`. | -| `session_id` | string | La sesión sobre la que se ejecutó esta evaluación. Una sesión puede tener múltiples evaluaciones en la línea temporal. | -| `agent_id` | string | Identifica al agente que produjo la sesión. | +| `session_id` | string | La sesión contra la que se ejecutó esta evaluación. Una sesión puede tener múltiples evaluaciones en la línea de tiempo. | +| `agent_id` | string | Identifica el agente que produjo la sesión. | | `environment` | string | Etiqueta de entorno copiada de la sesión. | | `status` | enum | Uno de `"done"`, `"error"`, `"timeout"`. | | `scores` | object \| null | Puntuaciones devueltas por tu evaluador. | -| `reasoning` | object \| null | Mapa opcional de justificación por puntuación devuelto por tu evaluador. Las claves suelen coincidir con las de `scores`. El dashboard renderiza cada entrada bajo su barra de puntuación. | -| `summary` | string \| null | Narrativa general opcional de un párrafo devuelta por tu evaluador. El dashboard la muestra sobre el desglose por puntuación como titular de la evaluación. | -| `error` | string \| null | Solo se rellena en `"error"` / `"timeout"`. | +| `reasoning` | object \| null | Mapa de justificación opcional por puntuación devuelto por tu evaluador. Las claves generalmente reflejan las de `scores`. El dashboard muestra cada entrada bajo su barra de puntuación. | +| `summary` | string \| null | Narrativa general opcional de un párrafo devuelta por tu evaluador. El dashboard la muestra sobre el desglose por puntuación como el titular de la evaluación. | +| `error` | string \| null | Poblado solo en `"error"` / `"timeout"`. | | `attempt_count` | integer | Número de intentos de despacho (≥ 1). | | `duration_ms` | integer \| null | Duración del último intento. | -| `completed_at` | string (ISO 8601 UTC) | Momento en que se registró el resultado terminal. Los resultados se ordenan por `completed_at` (los más recientes primero). | -| `created_at` | string (ISO 8601 UTC) | Lleva la misma marca de tiempo que `completed_at` (semántica de escritura única). | +| `completed_at` | string (ISO 8601 UTC) | Momento en que se registró el resultado terminal. Los resultados se ordenan por `completed_at` (más reciente primero). | +| `created_at` | string (ISO 8601 UTC) | Lleva el mismo timestamp que `completed_at` (semántica de escritura única). | --- ## Permisos -| Permiso | Concede | +| Permiso | Otorga | |---|---| | `evaluations:read` | Listar resultados de evaluación, ver puntuaciones en el dashboard y cargar métricas de salud del dashboard. | -| `evaluations:trigger` | Encolar manualmente una evaluación para una sesión mediante `POST /sessions/:session_id/re-evaluate` o el botón de re-evaluación del dashboard. | -| `dashboards:read` | Ver dashboards guardados (también requiere `evaluations:read` para cargar sus métricas). | +| `evaluations:trigger` | Poner en cola manualmente una evaluación para una sesión mediante `POST /sessions/:session_id/re-evaluate` o el botón de re-evaluación del dashboard. | +| `dashboards:read` | Ver dashboards guardados (también necesita `evaluations:read` para cargar sus métricas). | | `dashboards:write` | Crear y editar dashboards. | | `dashboards:delete` | Eliminar dashboards. | -El administrador bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) recibe estos permisos automáticamente. +El administrador inicial (`ADMIN_KEY`, `ADMIN_EMAIL`) recibe estos permisos automáticamente. --- ## Ver resultados -- **`/sessions/`**: línea temporal de eventos + un panel lateral derecho que muestra las puntuaciones de la sesión y cualquier error del intento de despacho. Si tu clave tiene `evaluations:trigger`, aparece un botón de **re-evaluate** junto al botón de exportación, útil para sesiones que nunca emitieron `agent_end` o para actualizar puntuaciones tras desplegar un nuevo evaluador. El dashboard sondea el nuevo resultado y actualiza el panel lateral cuando llega. +- **`/sessions/`**: línea de tiempo de eventos + un panel derecho que muestra las puntuaciones de la sesión y cualquier error del intento de despacho. Si tu clave tiene `evaluations:trigger`, aparece un botón de **re-evaluar** junto al botón de exportar, útil para sesiones que nunca emitieron `agent_end`, o para actualizar puntuaciones después de desplegar un nuevo evaluador. El dashboard sondea el nuevo resultado y actualiza el panel derecho cuando llega. - **`/sessions`**: cuadrícula de sesiones filtrable; la columna de puntuación muestra el estado de evaluación y las puntuaciones de cada sesión de un vistazo. -- **`/dashboards`**: vistas guardadas de salud de evaluación (consulta [Dashboards](#dashboards) más abajo). +- **`/dashboards`**: vistas de salud de evaluación guardadas (consulta [Dashboards](#dashboards) a continuación). -![La cuadrícula de sesiones con indicadores de estado de evaluación por sesión e insignias de puntuación con código de colores (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) +![La cuadrícula de sesiones con pastillas de estado de evaluación por sesión e insignias de puntuación codificadas por color (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) -*La cuadrícula de sesiones muestra el estado de evaluación y las puntuaciones de cada ejecución de un vistazo; las insignias en rojo/ámbar/verde hacen que las puntuaciones bajas destaquen.* +*La cuadrícula de sesiones muestra el estado de evaluación y las puntuaciones de cada ejecución de un vistazo; las insignias en rojo/ámbar/verde hacen que las puntuaciones bajas resalten inmediatamente.* --- ## Dashboards -La página de **Dashboards** (`/dashboards`) te permite guardar una combinación de filtros de evaluación como una vista con nombre y reutilizable, y observar cómo evoluciona ese subconjunto de evaluaciones de un vistazo. Los dashboards son **compartidos en toda tu organización**; todos los que tengan `dashboards:read` ven el mismo conjunto. +La página de **Dashboards** (`/dashboards`) te permite guardar una combinación de filtros de evaluación como una vista con nombre y reutilizable, y observar cómo evoluciona ese subconjunto de evaluaciones de un vistazo. Los dashboards se **comparten en toda tu organización**; todos los que tienen `dashboards:read` ven el mismo conjunto. Cada dashboard fija: - **Filtros**: los mismos controles que la página de sesiones: entorno, estado, agente, una ventana de tiempo deslizante y filtros de rango de puntuación (`key:min..max`). -- **Una configuración de visualización**: qué claves de puntuación destacar, los umbrales de salud verde/ámbar/rojo, qué paneles mostrar y si colapsar a la última evaluación por sesión. +- **Una configuración de visualización**: qué claves de puntuación destacar, los umbrales de salud verde/ámbar/rojo, qué paneles mostrar y si colapsar a la evaluación más reciente por sesión. -Cada tarjeta muestra el número de sesiones coincidentes, un desglose done/error/timeout, el promedio de cada puntuación destacada y una pequeña línea de tendencia. Abrir un dashboard muestra los paneles a tamaño completo; **"open in sessions"** te lleva a la página de sesiones prefiltrada exactamente a ese subconjunto. Las métricas se calculan en el servidor sobre todo el conjunto coincidente (mediante `GET /evaluations/aggregate`), por lo que los números son exactos y no muestreados. +Cada tarjeta muestra el número de sesiones coincidentes, un desglose done/error/timeout, el promedio de cada puntuación destacada y una pequeña línea de tendencia sparkline. Abrir un dashboard muestra los paneles a tamaño completo; **"abrir en sesiones"** te lleva a la página de sesiones pre-filtrada exactamente a ese subconjunto. Las métricas se calculan en el servidor sobre todo el conjunto coincidente (mediante `GET /evaluations/aggregate`), por lo que los números son exactos en lugar de muestras. -![Un dashboard de salud de evaluación con barras de puntuación media por dimensión del evaluador, un desglose ok-vs-error de herramientas, las principales herramientas y una tendencia de eventos por hora](/agenteye/images/dashboard-quality.png) +![Un dashboard de salud de evaluación con barras de puntuación promedio por dimensión del evaluador, un desglose ok-vs-error de herramientas, las herramientas principales y una tendencia de eventos por hora](/agenteye/images/dashboard-quality.png) -**Permisos:** para ver se necesita tanto `dashboards:read` como `evaluations:read`; para crear y editar se necesita `dashboards:write`; para eliminar se necesita `dashboards:delete`. El administrador bootstrap recibe todos estos permisos automáticamente. +**Permisos:** para ver se necesitan tanto `dashboards:read` como `evaluations:read`; para crear y editar se necesita `dashboards:write`; para eliminar se necesita `dashboards:delete`. El administrador inicial los recibe todos automáticamente. --- -## Resolución de problemas +## Solución de problemas -**Las sesiones existen pero no se crean evaluaciones.** Confirma que `EVALUATOR_ENDPOINT` está configurado en el proceso del servidor, que el servidor y el evaluador comparten el mismo valor de `EVALUATOR_TOKEN`, y que el endpoint `/health` del evaluador es accesible desde el servidor. Con `EVALUATOR_ENDPOINT` sin definir, el pipeline es inactivo. +**Las sesiones existen pero no se crean evaluaciones.** Confirma que `EVALUATOR_ENDPOINT` está configurado en el proceso del servidor, que el servidor y el evaluador comparten el mismo valor de `EVALUATOR_TOKEN`, y que el endpoint `/health` del evaluador es accesible desde el servidor. Con `EVALUATOR_ENDPOINT` sin configurar, el pipeline es inactivo. -**Las evaluaciones en curso se acumulan.** Consulta `GET /evaluation-jobs` para ver la cola en curso. Inspecciona `attempt_count`, `next_attempt_at` y `last_error` en cada fila. Causas comunes: el servicio evaluador no es accesible o devuelve 5xx (se reintenta con retroceso), `EVALUATOR_TOKEN` incorrecto (401 es terminal), o un evaluador asíncrono que devuelve `pending` indefinidamente (ver más abajo). +**Las evaluaciones en curso se acumulan.** Consulta `GET /evaluation-jobs` para ver la cola en curso. Inspecciona `attempt_count`, `next_attempt_at` y `last_error` en cada fila. Causas comunes: servicio evaluador inaccesible o devolviendo 5xx (reintentado con retroceso), `EVALUATOR_TOKEN` incorrecto (401 es terminal), o un evaluador asíncrono que devuelve `pending` indefinidamente (ver más abajo). -**Las sesiones se completaron pero no hay evaluación terminal.** Consulta `GET /evaluation-jobs?status=polling`; el resultado puede seguir en curso. Si un trabajo está atascado en `pending`, el servidor tiene problemas para contactar con el evaluador; comprueba que el evaluador está activo y que `EVALUATOR_TOKEN` coincide. +**Las sesiones se completaron pero no hay evaluación terminal.** Consulta `GET /evaluation-jobs?status=polling`; el resultado puede seguir en curso. Si un trabajo está bloqueado en `pending`, el servidor tiene dificultades para alcanzar el evaluador; comprueba que el evaluador esté activo y que `EVALUATOR_TOKEN` coincida. -**`HTTP 401 from evaluator: invalid bearer token`.** El `EVALUATOR_TOKEN` del servidor no coincide con el valor configurado en el servicio evaluador. Deben ser idénticos. +**`HTTP 401 from evaluator: invalid bearer token`.** El `EVALUATOR_TOKEN` en el servidor no coincide con el valor configurado en el servicio evaluador. Deben ser idénticos. -**El evaluador asíncrono devuelve `pending` indefinidamente.** El servidor sondea `GET /evaluate/{job_id}` hasta que el evaluador devuelve `done` o `error`, o hasta que se agota `EVALUATOR_MAX_POLL_DURATION_SECS` (1 h por defecto). Tras el límite, la evaluación se registra como `timeout` y se elimina de la cola en curso. Aumenta `EVALUATOR_MAX_POLL_DURATION_SECS` si tu evaluador legítimamente necesita más tiempo del predeterminado. +**El evaluador asíncrono devuelve `pending` indefinidamente.** El servidor sondea `GET /evaluate/{job_id}` hasta que el evaluador devuelve `done` o `error`, o hasta que se agota `EVALUATOR_MAX_POLL_DURATION_SECS` (por defecto 1 h). Tras ese límite, la evaluación se registra como `timeout` y se elimina de la cola en curso. Aumenta `EVALUATOR_MAX_POLL_DURATION_SECS` si tu evaluador legítimamente necesita más tiempo que el predeterminado. --- ## Próximos pasos -- [Habilidad de agente evaluador](/es/agenteye/evaluator-skill): haz que un agente de programación diseñe tus dimensiones a partir de sesiones reales y construya este servicio por ti. -- [Python SDK](/es/agenteye/python-sdk): emite los eventos `agent_end` que desencadenan la puntuación. +- [Habilidad de agente evaluador](/es/agenteye/evaluator-skill): haz que un agente de codificación diseñe tus dimensiones a partir de sesiones reales y construya este servicio por ti. +- [SDK de Python](/es/agenteye/python-sdk): emite los eventos `agent_end` que desencadenan la puntuación. - [Claves de API](/es/agenteye/api-keys): los permisos `evaluations:read` y `evaluations:trigger`. - [Auditorías](/es/agenteye/audits): la otra función de calidad automatizada de Observability, para revisión basada en políticas. \ No newline at end of file diff --git a/docs/es/agenteye/evaluations.mdx b/docs/es/agenteye/evaluations.mdx index af799316..58472a2c 100644 --- a/docs/es/agenteye/evaluations.mdx +++ b/docs/es/agenteye/evaluations.mdx @@ -3,48 +3,49 @@ title: "Evaluaciones" description: "Los problemas de calidad te encuentran a ti, en lugar de que te enteres por una queja de un usuario." --- -Los problemas de calidad te encuentran a ti, en lugar de que te enteres por una queja de un usuario. Conecta tu propio servicio de puntuación una sola vez y Failproof AI Observability califica automáticamente cada ejecución completada, de modo que una caída en la utilidad o un aumento en las alucinaciones aparece por sí solo, antes de que el cliente lo sienta. -![La cuadrícula de sesiones con una columna de puntuación: cada ejecución lleva una etiqueta de estado de evaluación y distintivos codificados por color de utilidad, factualidad y eficiencia de herramientas](/agenteye/images/sessions-list.png) +Los problemas de calidad te encuentran a ti, en lugar de que te enteres por una queja de un usuario. Conecta tu propio servicio de puntuación una sola vez y Failproof AI Observability evalúa automáticamente cada ejecución completada, de modo que una caída en la utilidad o un aumento en las alucinaciones aparece por sí solo, antes de que un cliente lo sienta. -*Cada ejecución en la cuadrícula de sesiones lleva sus puntuaciones; los distintivos rojos, ámbar y verdes hacen que las ejecuciones débiles resalten sin necesidad de abrir ni una sola transcripción.* +![La cuadrícula de sesiones con una columna de puntuación: cada ejecución muestra una etiqueta de estado de evaluación y distintivos con código de colores para utilidad, factualidad y eficiencia de herramientas](/agenteye/images/sessions-list.png) + +*Cada ejecución en la cuadrícula de sesiones lleva sus puntuaciones; los distintivos en rojo, ámbar y verde hacen que las ejecuciones débiles destaquen sin que tengas que abrir ni una sola transcripción.* ## Deja de revisar ejecuciones manualmente -Antes tenías que verificar un puñado de ejecuciones y esperar que el resto estuviera bien. Ahora cada sesión completada se puntúa en el momento en que termina, en las dimensiones que te importan: utilidad, eficiencia de herramientas, factualidad, seguridad, lo que sea que defina tu estándar de calidad. Tú defines las claves de puntuación; Failproof AI Observability almacena, sigue las tendencias y muestra lo que tu evaluador devuelva. Ninguna ejecución queda sin puntuar, y dejas de enterarte de una regresión a través de un ticket de soporte. +Antes revisabas a mano un puñado de ejecuciones y esperabas que el resto estuvieran bien. Ahora cada sesión completada se puntúa en el momento en que termina, en las dimensiones que te importan: utilidad, eficiencia de herramientas, factualidad, seguridad, lo que sea que defina tu estándar de calidad. Tú defines las claves de puntuación; Failproof AI Observability almacena, analiza tendencias y muestra todo lo que tu evaluador devuelva. Ninguna ejecución queda sin puntuar, y dejas de enterarte de una regresión a través de un ticket de soporte. -Las puntuaciones aparecen en la cuadrícula de sesiones en **`//sessions`** (barra lateral → *observe* → *sessions*), con un grupo de distintivos por fila. ¿Quieres solo las ejecuciones que no alcanzaron el nivel? Filtra la cuadrícula por rango de puntuación, por ejemplo utilidad por debajo de 0,5, y obtén exactamente las ejecuciones que vale la pena revisar. Ver las puntuaciones requiere el permiso `evaluations:read`. +Las puntuaciones aparecen en la cuadrícula de sesiones en **`//sessions`** (barra lateral → *observe* → *sessions*), con un grupo de distintivos por fila. ¿Quieres ver solo las ejecuciones que no alcanzaron el nivel? Filtra la cuadrícula por rango de puntuación —por ejemplo, utilidad por debajo de 0.5— y accede exactamente a las ejecuciones que vale la pena revisar. Para ver las puntuaciones se necesita el permiso `evaluations:read`. ## Descubre por qué una ejecución obtuvo una puntuación baja -Un número te dice que una ejecución fue débil; la página de sesión te dice por qué. Abre cualquier ejecución y el panel lateral derecho muestra primero el resumen general, seguido de una barra por dimensión con el razonamiento propio de tu evaluador debajo de cada una, de modo que pasas de "esto obtuvo 0,4 en factualidad" a la afirmación exacta que falló en cuestión de segundos. +Un número te dice que una ejecución fue débil; la página de sesión te dice por qué. Abre cualquier ejecución y el panel lateral derecho comienza con el resumen general, seguido de una barra por dimensión con el razonamiento propio de tu evaluador debajo de cada una, de modo que puedes pasar de "esto obtuvo 0.4 en factualidad" a la afirmación exacta que falló en cuestión de segundos. -![El panel lateral derecho de una sesión: el resumen de evaluación arriba, luego barras de puntuación por dimensión con una línea de razonamiento en cada una, junto a la línea de tiempo completa de eventos](/agenteye/images/session-detail.png) +![El panel lateral derecho de una sesión: el resumen de evaluación arriba, luego barras de puntuación por dimensión cada una con una línea de razonamiento, junto a la línea de tiempo completa de eventos](/agenteye/images/session-detail.png) *La vista de detalle de sesión: resumen, barras de puntuación por dimensión y el razonamiento detrás de cada puntuación, justo al lado de la línea de tiempo de eventos de la ejecución.* -¿Implementaste un evaluador más preciso o estás revisando una ejecución que falló antes de poder ser puntuada? Un botón de **re-evaluate** (restringido por `evaluations:trigger`) vuelve a puntuar la sesión en el lugar y añade el nuevo resultado a su línea de tiempo, de modo que las puntuaciones anteriores permanecen visibles como historial. Lo encontrarás en **`//sessions/`**. +¿Implementaste un evaluador más preciso o estás revisando una ejecución que falló antes de poder puntuarse? Un botón de **re-evaluate** (controlado por `evaluations:trigger`) vuelve a puntuar la sesión en el mismo lugar y añade el resultado nuevo a su línea de tiempo, de modo que las puntuaciones anteriores permanecen visibles como historial. Lo encontrarás en **`//sessions/`**. ## Observa la tendencia de calidad en toda la flota -Una ejecución con puntuación baja es ruido; un grupo entero descendiendo es una señal. Los dashboards guardados convierten tus puntuaciones en una tendencia que puedes monitorear de un vistazo: utilidad promedio esta semana frente a la anterior, por agente, por entorno. +Una sola ejecución con puntuación baja es ruido; una cohorte entera cayendo es una señal. Los dashboards guardados convierten tus puntuaciones en una tendencia que puedes vigilar de un vistazo: utilidad promedio esta semana frente a la anterior, por agente, por entorno. -![Un dashboard de calidad: barras de puntuación promedio por dimensión del evaluador junto a una tendencia a lo largo del tiempo](/agenteye/images/dashboard-quality.png) +![Un dashboard de calidad: barras de puntuación promedio por dimensión de evaluador junto a una tendencia en el tiempo](/agenteye/images/dashboard-quality.png) -*Un dashboard de calidad guardado sigue la tendencia de las claves de puntuación que destacas, de modo que una deriva lenta es obvia mucho antes de convertirse en un incidente.* +*Un dashboard de calidad guardado muestra la tendencia de las claves de puntuación que destacas, para que una deriva lenta sea evidente mucho antes de convertirse en un incidente.* -Los dashboards se encuentran en **`//dashboards`** (barra lateral → *analyze* → *dashboards*), se comparten en toda tu organización, y cada tarjeta agrupa las sesiones correspondientes: cuántas hay, el promedio de cada puntuación destacada y una minigráfica de tendencia. "Open in sessions" te lleva directamente a las ejecuciones prefiltradas detrás de cualquier número. Para verlos se requiere `dashboards:read` más `evaluations:read`. +Los dashboards se encuentran en **`//dashboards`** (barra lateral → *analyze* → *dashboards*), se comparten en toda tu organización y cada tarjeta agrupa las sesiones correspondientes: cuántas hay, el promedio de cada puntuación destacada y una minigráfica de tendencia. "Open in sessions" te lleva directamente a las ejecuciones prefiltradas detrás de cualquier número. Para verlos se necesitan los permisos `dashboards:read` y `evaluations:read`. ## Conecta un evaluador una sola vez -La puntuación es opcional y permanece completamente desactivada hasta que apuntes Failproof AI Observability a un puntuador. Configuras un pequeño servicio HTTP (Observability incluye una referencia funcional que puedes copiar), estableces dos valores en tu servidor, y a partir de entonces todas las ejecuciones se puntúan automáticamente. La guía completa, el contrato de puntuación y el SDK están disponibles en la guía detallada. +La puntuación es opcional y permanece completamente desactivada hasta que apuntes Failproof AI Observability a un evaluador. Levantas un pequeño servicio HTTP (Observability incluye una referencia funcional que puedes copiar), configuras dos valores en tu servidor, y a partir de entonces cada ejecución se puntúa automáticamente. La guía completa, el contrato de puntuación y el SDK están en la guía detallada. -¿No sabes qué dimensiones vale la pena puntuar en primer lugar? La [habilidad de agente evaluador](/es/agenteye/evaluator-skill) hace que tu agente de codificación lo determine en función de tus propias sesiones, y luego construye y despliega el servicio. +¿No estás seguro de qué dimensiones vale la pena puntuar? La [habilidad de agente evaluador](/es/agenteye/evaluator-skill) hace que tu agente de código lo determine a partir de tus propias sesiones, y luego construye y despliega el servicio. ## Relacionado - [Suite de evaluación](/es/agenteye/evaluation-suite): conecta tu evaluador, el contrato de puntuación y el SDK. -- [Habilidad de agente evaluador](/es/agenteye/evaluator-skill): deja que un agente de codificación elija tus dimensiones de puntuación y construya el evaluador. +- [Habilidad de agente evaluador](/es/agenteye/evaluator-skill): deja que un agente de código elija tus dimensiones de puntuación y construya el evaluador. - [Sesiones](/es/agenteye/sessions): la cuadrícula ejecución por ejecución donde aparecen las puntuaciones. - [Dashboards](/es/agenteye/dashboards): guarda y comparte tendencias de calidad en toda tu organización. - [Auditorías](/es/agenteye/audits): la otra función de calidad automática de Observability, para investigaciones entre sesiones. \ No newline at end of file diff --git a/docs/es/agenteye/evaluator-skill.mdx b/docs/es/agenteye/evaluator-skill.mdx index 8f646072..1a69f451 100644 --- a/docs/es/agenteye/evaluator-skill.mdx +++ b/docs/es/agenteye/evaluator-skill.mdx @@ -1,26 +1,26 @@ --- title: "Habilidad del Agente Evaluador de Observabilidad de Failproof AI" -description: "Pasa de «creo que nuestro agente a veces falla» a un servicio de puntuación desplegado, con tu agente de programación tomando las decisiones y construyendo la solución." +description: "Pasa de \"creo que nuestro agente a veces falla\" a un servicio de puntuación desplegado, con tu agente de codificación tomando las decisiones y construyendo el sistema." --- -Pasa de *«creo que nuestro agente a veces falla»* a un servicio de puntuación desplegado, con tu agente de programación tomando las decisiones y construyendo la solución. La **habilidad evaluadora de Observabilidad de Failproof AI** (`agenteye-evaluator`) es una *Agent Skill*: una pequeña carpeta de instrucciones que un agente de programación como Claude Code o Codex carga bajo demanda. Le enseña al agente a determinar qué dimensiones de calidad vale la pena rastrear para *tu* agente y luego escribir, probar y desplegar el [servicio evaluador](/es/agenteye/evaluation-suite) que las puntúa. +Pasa de *"creo que nuestro agente a veces falla"* a un servicio de puntuación desplegado, con tu agente de codificación tomando las decisiones y construyendo el sistema. La **habilidad de evaluador de Observabilidad de Failproof AI** (`agenteye-evaluator`) es una *Agent Skill*: una pequeña carpeta de instrucciones que un agente de codificación como Claude Code o Codex carga bajo demanda. Le enseña al agente a determinar qué dimensiones de calidad vale la pena rastrear para *tu* agente, y luego a escribir, probar y desplegar el [servicio evaluador](/es/agenteye/evaluation-suite) que las puntúa. -**No** es un puntuador alojado, un registro al que subir archivos ni un sistema de plugins. Tu evaluador permanece como tu propio servicio HTTP en tu propia infraestructura, exactamente como se describe en la guía de la [Suite de evaluación](/es/agenteye/evaluation-suite). La habilidad solo enseña a tu agente a construirlo bien, de modo que todo lo que hace, podrías hacerlo tú mismo escribiendo el mismo código. +**No** es un puntuador alojado, un registro al que subir datos ni un sistema de plugins. Tu evaluador sigue siendo tu propio servicio HTTP en tu propia infraestructura, exactamente como se describe en la guía de la [Suite de evaluación](/es/agenteye/evaluation-suite). La habilidad solo enseña a tu agente a construirlo bien, de modo que todo lo que hace, tú podrías hacerlo escribiendo el mismo código. --- ## La parte difícil es decidir qué puntuar -La superficie del SDK es pequeña — un decorador y dos modelos — y un agente puede escribirla a partir del [contrato](/es/agenteye/evaluation-suite#http-contract) por sí solo. Ahí no es donde fallan los evaluadores. Fallan porque puntúan la cosa equivocada, y un evaluador que puntúa la cosa equivocada es peor que ninguno: produce un dashboard que todos aprenden a ignorar. +La superficie del SDK es pequeña — un decorador y dos modelos — y un agente puede escribir eso a partir del [contrato](/es/agenteye/evaluation-suite#http-contract) por sí solo. Ahí no es donde fallan los evaluadores. Fallan porque puntúan lo incorrecto, y un evaluador que puntúa lo incorrecto es peor que ninguno: produce un dashboard que todo el mundo aprende a ignorar. -Por eso la mayor parte de la habilidad es la etapa previa a que exista cualquier código. Hace que el agente te entreviste (*«describe una ejecución que salió bien; ahora una que salió mal»*), luego recorre tus sesiones reales a través de la [CLI `agenteye`](/es/agenteye/cli) y las lee de principio a fin. Esas dos mitades suelen no coincidir, y la brecha es precisamente el punto: lo que pretendes medir frente a lo que tus transcripciones pueden respaldar realmente. Una dimensión solo sobrevive si es **computable** a partir de los eventos y **discriminante** — si puntúa 0,9 tanto en tu ejecución buena como en la mala, no enseña nada y se elimina. +Por eso la mayor parte de la habilidad corresponde a lo que ocurre antes de que exista cualquier código. El agente te entrevista (*"describe una ejecución que salió bien; ahora una que salió mal"*), luego extrae tus sesiones reales mediante la [CLI `agenteye`](/es/agenteye/cli) y las lee de principio a fin. Esas dos mitades suelen no coincidir, y la brecha es el punto clave: lo que pretendes medir frente a lo que tus transcripciones realmente pueden respaldar. Una dimensión solo sobrevive si es **computable** a partir de los eventos y **discriminatoria** — si puntúa 0.9 tanto en tu buena ejecución como en la mala, no enseña nada y se elimina. -Lo que se devuelve es una propuesta de 2 a 4 dimensiones con el razonamiento adjunto, para que la apruebes antes de que se escriba una sola línea. +El resultado es una propuesta de 2 a 4 dimensiones con el razonamiento adjunto, para que la apruebes antes de escribir una sola línea. ```mermaid flowchart TD - YOU["tú: 'Quiero evaluaciones para mi bot de soporte'"] --> AGENT["agente de programación (Claude Code / Codex)
carga la habilidad agenteye-evaluator"] + YOU["tú: 'quiero evals para mi bot de soporte'"] --> AGENT["agente de codificación (Claude Code / Codex)
carga la habilidad agenteye-evaluator"] AGENT -->|"entrevista: ¿cómo se ve bueno vs malo?"| YOU AGENT -->|"agenteye --json sessions / events"| DATA["tus sesiones reales
lo que realmente ocurre"] DATA --> DIMS["2-4 dimensiones, tú las apruebas"] @@ -30,46 +30,46 @@ flowchart TD --- -## Su relación con las demás piezas de evaluación +## Cómo se relaciona con las demás piezas de evaluación -Cuatro documentos cubren la puntuación, y se encadenan entre sí en orden: +Cuatro documentos cubren la puntuación, y se conectan entre sí en orden: -| Página | Qué es | Úsala cuando | +| Página | Qué es | Úsalo cuando | |---|---|---| | **[Evaluaciones](/es/agenteye/evaluations)** | La funcionalidad: puntuaciones en la cuadrícula de sesiones, dashboards, re-evaluación | Quieres saber qué te aporta la puntuación automática | | **[Suite de evaluación](/es/agenteye/evaluation-suite)** | El contrato HTTP, el SDK, las variables de entorno del servidor | Estás implementando o depurando el evaluador tú mismo | -| **Habilidad evaluadora** (este doc) | Una puerta de entrada en lenguaje natural para diseñar *y* construir el puntuador | Quieres pasar de «quiero evaluaciones» a un servicio en ejecución | -| **[Habilidad CLI](/es/agenteye/cli-skill)** | Una puerta de entrada en lenguaje natural para la CLI `agenteye` | Quieres *leer* las puntuaciones que ya tienes | -| **[Habilidad Python SDK](/es/agenteye/python-sdk-skill)** | Una puerta de entrada en lenguaje natural para instrumentar tu agente | Tu agente aún no emite sesiones — no hay nada que puntuar | +| **Habilidad del evaluador** (este documento) | Una puerta de entrada en lenguaje natural para diseñar *y* construir el puntuador | Quieres pasar de "quiero evals" a un servicio en ejecución | +| **[Habilidad de CLI](/es/agenteye/cli-skill)** | Una puerta de entrada en lenguaje natural para la CLI `agenteye` | Quieres *leer* las puntuaciones que ya tienes | +| **[Habilidad del SDK de Python](/es/agenteye/python-sdk-skill)** | Una puerta de entrada en lenguaje natural para instrumentar tu agente | Tu agente aún no emite sesiones — no hay nada que puntuar | -### vs. la habilidad CLI: construir versus leer +### vs. la habilidad de CLI: construir versus leer -Las dos habilidades están deliberadamente diseñadas para no solaparse, e instalar ambas es la configuración normal — el agente elige entre ellas según lo que le pidas: +Las dos habilidades son deliberadamente no superpuestas, e instalar ambas es la configuración habitual — el agente elige entre ellas según lo que le pidas: -- **`agenteye-evaluator`** (este doc) construye la cosa que *produce* puntuaciones. Su trabajo termina cuando las puntuaciones aparecen por primera vez. -- **[`agenteye-cli`](/es/agenteye/cli-skill)** lee las puntuaciones que ya existen (`agenteye evals`). *«¿Bajó la calidad esta semana?»* es su pregunta, no la de esta habilidad. +- **`agenteye-evaluator`** (este documento) construye lo que *produce* puntuaciones. Su trabajo termina cuando las puntuaciones llegan por primera vez. +- **[`agenteye-cli`](/es/agenteye/cli-skill)** lee puntuaciones que ya existen (`agenteye evals`). *"¿Bajó la calidad esta semana?"* es su pregunta, no la de esta habilidad. --- ## Requisitos previos -1. **La CLI `agenteye` instalada e iniciada sesión** (`pipx install agenteye`, luego `agenteye login`). La habilidad la utiliza en dos momentos: para obtener las sesiones reales con las que diseña, y para confirmar que tus puntuaciones llegaron al final. Tu sesión necesita `events:read`, más `evaluations:read` para esa verificación final. Al igual que con la habilidad CLI, **no puede** completar el inicio de sesión con código de un solo uso enviado por correo electrónico en tu lugar. -2. **Un lugar donde alojar el evaluador.** Se construye como una imagen y se ejecuta como un servicio de larga duración, por lo que necesita un repositorio real, no un archivo temporal. Los evaluadores suelen vivir en su propio repositorio, separado del agente que se está puntuando — la habilidad busca uno existente y pregunta antes de crear un andamiaje nuevo. -3. **El wheel del SDK `agenteye-evaluator`** — lee la siguiente sección antes de dejar que tu agente empiece a escribir comandos `pip`. +1. La **CLI `agenteye` instalada e iniciada sesión** (`pipx install agenteye`, luego `agenteye login`). La habilidad la utiliza en dos momentos: para extraer las sesiones reales contra las que diseña, y para confirmar al final que tus puntuaciones llegaron. Tu sesión necesita `events:read`, más `evaluations:read` para esa verificación final. Al igual que con la habilidad de CLI, **no puede** completar el inicio de sesión con código de un solo uso enviado por correo electrónico por ti. +2. **Un lugar donde vivir para el evaluador.** Se construye en una imagen y se ejecuta como un servicio de larga duración, por lo que necesita un repositorio real, no un archivo temporal. Los evaluadores suelen vivir en su propio repositorio, separado del agente que se está puntuando — la habilidad busca uno existente y pregunta antes de crear uno nuevo. +3. **El wheel del SDK `agenteye-evaluator`** — lee la siguiente sección antes de que tu agente empiece a escribir comandos `pip`. --- -## Dónde conseguirla +## Dónde obtenerlo La habilidad está publicada en la colección pública de habilidades de Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -El repositorio es público y la habilidad no necesita credenciales propias — solo maneja la CLI `agenteye` con la sesión *tuya* en la que iniciaste sesión, y escribe código en *tu* repositorio. Ten en cuenta que se distribuye como su propia carpeta y **no** está dentro del paquete `pipx install agenteye`, así que no la busques ahí. +El repositorio es público y la habilidad no necesita credenciales propias — solo utiliza la CLI `agenteye` con la sesión con la que *tú* iniciaste sesión, y escribe código en *tu* repositorio. Ten en cuenta que se distribuye como su propia carpeta y **no** está dentro del paquete `pipx install agenteye`, así que no la busques allí. ## Instalación de la habilidad -La forma más rápida es la CLI [`skills`](https://skills.sh), que descarga la carpeta y la coloca donde tu agente la busca: +La vía más rápida es la CLI [`skills`](https://skills.sh), que descarga la carpeta y la coloca donde tu agente la busca: ```bash # Claude Code, solo este proyecto @@ -90,10 +90,10 @@ npx skills update agenteye-evaluator # obtener la última versión npx skills remove agenteye-evaluator # eliminarla ``` -¿Prefieres instalar manualmente? Una Agent Skill es simplemente una carpeta que contiene un `SKILL.md` (más referencias opcionales), así que copiarla también funciona: +¿Prefieres instalarla manualmente? Una Agent Skill es simplemente una carpeta que contiene un `SKILL.md` (más referencias opcionales), por lo que copiarla también funciona: -- **Claude Code**: coloca la carpeta `agenteye-evaluator/` en `~/.claude/skills/` (todos los proyectos) o en `/.claude/skills/` (solo ese repositorio). Claude Code la descubre automáticamente — verifica con la lista `/skills`, o simplemente pide evaluaciones. -- **Codex (OpenAI)**: Codex lee el mismo `SKILL.md`. El archivo incluido `agents/openai.yaml` establece `allow_implicit_invocation: true`, por lo que Codex selecciona la habilidad automáticamente cuando una tarea coincide; de lo contrario, invócala explícitamente como `$agenteye-evaluator`. +- **Claude Code**: coloca la carpeta `agenteye-evaluator/` en `~/.claude/skills/` (todos los proyectos) o en `/.claude/skills/` (solo ese repositorio). Claude Code la descubre automáticamente — verifica con la lista `/skills`, o simplemente pide evals. +- **Codex (OpenAI)**: Codex lee el mismo `SKILL.md`. El archivo `agents/openai.yaml` incluido establece `allow_implicit_invocation: true`, por lo que Codex selecciona automáticamente la habilidad cuando una tarea coincide; de lo contrario, invócala explícitamente como `$agenteye-evaluator`. --- @@ -101,61 +101,61 @@ npx skills remove agenteye-evaluator # eliminarla > **Advertencia:** Lee esto antes de dejar que un agente instale el SDK. -La habilidad es pública; el SDK que maneja no lo es. `agenteye-evaluator` se distribuye únicamente como un artefacto de lanzamiento privado, y a diferencia de `agenteye`, el nombre está **sin reclamar en PyPI público** — así que un `pip install agenteye-evaluator` sin más podría descargar el paquete de un desconocido en el servicio que lee tus transcripciones de producción. Eso es un problema de cadena de suministro, no un error tipográfico. +La habilidad es pública; el SDK que utiliza no lo es. `agenteye-evaluator` se distribuye únicamente como un artefacto de lanzamiento privado, y a diferencia de `agenteye`, el nombre **no está registrado en PyPI público** — por lo que un simple `pip install agenteye-evaluator` podría instalar el paquete de un desconocido en el servicio que lee tus transcripciones de producción. Eso es un problema de cadena de suministro, no un error tipográfico. -La habilidad lo sabe y recorre una escalera de instalación en su lugar, deteniéndose en el primer peldaño que aplica: el código fuente del monorepo si estás dentro del repositorio de AgentEye, de lo contrario el wheel de lanzamiento privado desde GitHub Releases (requiere acceso), y si ninguno es accesible **se detiene y te dice que pidas el wheel a tu contacto de Failproof AI** en lugar de improvisar. +La habilidad lo sabe y en su lugar sigue una cadena de instalación, deteniéndose en el primer peldaño que aplica: el código fuente del monorepo si estás dentro del repositorio de AgentEye, en caso contrario el wheel de lanzamiento privado desde GitHub Releases (requiere acceso), y si ninguno es alcanzable **se detiene y te indica que pidas el wheel a tu contacto de Failproof AI** en lugar de improvisar. -Por tanto, si tu agente propone un `pip install agenteye-evaluator` simple desde PyPI público, esa es la señal de que la habilidad nunca se cargó. Detente ahí y comprueba que está instalada. +Por lo tanto, si tu agente propone un simple `pip install agenteye-evaluator` desde PyPI público, esa es la señal de que la habilidad nunca se cargó. Detente ahí y verifica que esté instalada. --- ## Qué puedes pedirle -Un ciclo completo real empieza con una petición vaga y termina con un diseño aprobado, no con código: +Un ciclo completo real comienza con una solicitud vaga y termina con un diseño aprobado, no con código: ```text -tú ▸ Quiero evaluaciones para nuestro bot de soporte. Creo que a veces falla. +tú ▸ Quiero evals para nuestro bot de soporte. Creo que a veces falla. agente▸ Antes de escribir nada: describe una ejecución que salió bien, y una que salió mal. -tú ▸ Bien: responde a partir de la documentación. Mal: se inventa cosas, +tú ▸ Bien: responde desde los documentos. Mal: se inventa cosas, o se rinde y dice "contacta con soporte". agente▸ Ejecutando: agenteye --json sessions --status error --since 7d Leyendo 5 sesiones, incluyendo dos que considerarías malas. - Tus palabras dicen veracidad y evasión. Las transcripciones - coinciden en evasión (2 de 5 terminan con una derivación a soporte, - y es evidente en model_response.content), pero la veracidad - necesita una verdad de base que tus eventos no contienen. + Tus palabras dicen factualidad y evasión. Las transcripciones + coinciden en evasión (2 de 5 terminan con un traspaso a soporte, + y es evidente en model_response.content), pero la factualidad + necesita una verdad de referencia que tus eventos no contienen. Así que puntuaría tres cosas: - deflection reglas, barato, separa tus dos ejecuciones - tool_efficiency reglas, detecta el bucle de reintentos en run-004 - groundedness juez LLM: ¿cada afirmación está en los docs que recuperó? - "factuality" necesitaría una verdad de base que no tenemos; groundedness - es lo más cercano que tus transcripciones pueden respaldar realmente. - ¿De acuerdo con esos tres nombres? Renombrar después divide el historial. + "factuality" necesitaría una verdad de referencia que no tenemos; + groundedness es lo más cercano que tus transcripciones pueden respaldar. + ¿Aceptas esos tres nombres? Renombrarlos después divide el historial. tú ▸ sí -agente▸ No hay evaluador en este repositorio. ¿Debo crear el andamiaje aquí, o +agente▸ No hay evaluador en este repositorio. ¿Debo crear uno aquí, o tienes uno en otro lugar? ``` -A partir de ahí escribe primero las dimensiones basadas en reglas (gratuitas, instantáneas, deterministas), las prueba contra una sesión capturada real incluyendo las vacías y las que nunca se completaron y que hacen fallar a los evaluadores ingenuos, y solo recurre a un juez LLM para la dimensión subjetiva. Conoce los [límites del dispatcher](/es/agenteye/evaluation-suite#configuring-the-server) — un tiempo de espera de solicitud de 30s y 8 llamadas concurrentes en todo el despliegue — así que si el juez no cabe de forma fiable, va asíncrono con `JobPending` en lugar de dejar que tu juez sea cancelado y reintentado cinco veces a cinco veces el coste. +A partir de ahí escribe primero las dimensiones basadas en reglas (gratuitas, instantáneas, deterministas), las prueba contra una sesión capturada real incluyendo las vacías y las que nunca terminaron y que hacen fallar a los evaluadores ingenuos, y solo recurre a un juez LLM en la dimensión subjetiva. Conoce los [límites del despachador](/es/agenteye/evaluation-suite#configuring-the-server) — un tiempo de espera de solicitud de 30 s y 8 llamadas concurrentes en todo el despliegue — por lo que si el juez no cabe de forma fiable, utiliza async con `JobPending` en lugar de dejar que tu juez sea cancelado y reintentado cinco veces al quíntuple del costo. -Luego lo despliega, configura las dos variables de entorno del servidor y confirma con `agenteye --json evals --session-id ` que las puntuaciones realmente llegaron. Que lleguen las puntuaciones es la única prueba. +Luego despliega, establece las dos variables de entorno del servidor, y confirma con `agenteye --json evals --session-id ` que las puntuaciones realmente llegaron. Que las puntuaciones lleguen es la única prueba. --- ## Qué tener en cuenta -- **Los nombres de las dimensiones son casi permanentes.** Las claves de puntuación son cadenas arbitrarias y la plataforma traza tendencias de lo que envíes, lo que significa que nada en el downstream corrige una mala elección. Renombrar después divide el historial: las sesiones antiguas conservan la clave antigua y la tendencia se rompe. Por eso la habilidad obtiene una aprobación explícita antes de escribir código — tómate ese aviso en serio. -- **Los fixtures son transcripciones reales de producción.** Diseñar contra sesiones reales implica descargarlas al disco, y pueden contener datos de clientes. La habilidad pregunta antes de agregarlos a git; en caso de duda, mantén `fixtures/` fuera del repositorio y pide a cada desarrollador que descargue las suyas propias. -- **El agente escribe y despliega un servicio que lee cada transcripción.** Actúa como tú, acotado por los permisos de tu sesión de CLI, pero revisa el evaluador como cualquier otro código que toque datos de producción. +- **Los nombres de las dimensiones son casi permanentes.** Las claves de puntuación son cadenas arbitrarias y la plataforma muestra tendencias de lo que envíes, lo que significa que nada en el flujo descendente corrige una mala elección. Renombra después y el historial se divide: las sesiones antiguas mantienen la clave antigua y la tendencia se rompe. Por eso la habilidad solicita aprobación explícita antes de escribir código — tómate ese momento en serio. +- **Los fixtures son transcripciones reales de producción.** Diseñar contra sesiones reales implica descargarlas al disco, y pueden contener datos de clientes. La habilidad pregunta antes de confirmarlas en git; si tienes dudas, mantén `fixtures/` fuera del repositorio y que cada desarrollador descargue las suyas. +- **El agente escribe y despliega un servicio que lee todas las transcripciones.** Actúa como tú, acotado por los permisos de tu sesión de CLI, pero revisa el evaluador como cualquier otro código que toca datos de producción. --- @@ -163,5 +163,5 @@ Luego lo despliega, configura las dos variables de entorno del servidor y confir - **[Suite de evaluación](/es/agenteye/evaluation-suite)**: el contrato HTTP, el SDK y las variables de entorno del servidor que configura la habilidad. - **[Evaluaciones](/es/agenteye/evaluations)**: dónde aparecen las puntuaciones una vez que llegan. -- **[Habilidad CLI](/es/agenteye/cli-skill)**: la habilidad hermana, para leer resultados en lugar de construir el puntuador. -- **[CLI](/es/agenteye/cli)**: la referencia de comandos detrás de los datos de sesión con los que la habilidad diseña. \ No newline at end of file +- **[Habilidad de CLI](/es/agenteye/cli-skill)**: la habilidad hermana, para leer resultados en lugar de construir el puntuador. +- **[CLI](/es/agenteye/cli)**: la referencia de comandos detrás de los datos de sesión contra los que la habilidad diseña. \ No newline at end of file diff --git a/docs/es/agenteye/event-stream.mdx b/docs/es/agenteye/event-stream.mdx index 68e102b2..84c9460c 100644 --- a/docs/es/agenteye/event-stream.mdx +++ b/docs/es/agenteye/event-stream.mdx @@ -1,50 +1,50 @@ --- -title: "Stream de Eventos" +title: "Flujo de Eventos" description: "En el momento en que tu agente hace algo, tú lo ves." --- -En el momento en que tu agente hace algo, tú lo ves. El Stream de Eventos es tu pulso en tiempo real sobre cada agente en producción: sin esperas, sin buscar entre logs, sin adivinar qué acaba de pasar. +En el momento en que tu agente hace algo, tú lo ves. El Flujo de Eventos es tu pulso en vivo sobre cada agente en producción: sin esperas, sin rastrear logs, sin adivinar qué acaba de pasar. -![El Stream de Eventos en vivo: filas de eventos con código de colores actualizándose en tiempo real, filtrables por entorno, agente, sesión, tipo de evento y texto libre](/agenteye/images/events-stream.png) +![El Flujo de Eventos en vivo: filas de eventos con código de color que se actualizan en tiempo real, filtrables por entorno, agente, sesión, tipo de evento y texto libre](/agenteye/images/events-stream.png) -*Cada evento de cada agente en tu organización, del más reciente al más antiguo, actualizándose en tiempo real.* +*Cada evento de cada agente en tu organización, el más reciente primero, actualizándose a medida que ocurre.* -## Tu pulso en tiempo real sobre cada agente +## Tu pulso en vivo sobre cada agente -Cuando un agente inicia una ejecución, llama a un modelo, dispara una herramienta, ejecuta un hook o encuentra un error, la fila aparece en la parte superior del stream en el mismo instante en que ocurre. Muestra todos los eventos de todos los agentes de tu organización, del más reciente al más antiguo, para que siempre tengas una imagen actualizada en lugar de una desactualizada. +Cuando un agente inicia una ejecución, llama a un modelo, dispara una herramienta, ejecuta un hook o encuentra un error, la fila aparece en la parte superior del flujo en el mismo momento en que ocurre. Registra todos los eventos de todos los agentes de tu organización, el más reciente primero, para que siempre tengas una imagen actualizada en lugar de una desactualizada. -Eso significa que no tienes que hacer tail de archivos de log en algún servidor, ni buscar con grep entre máquinas, ni unir timestamps manualmente. Abres una sola página y ya estás observando producción. +Esto significa que no tienes que rastrear archivos de log en algún servidor, ni hacer búsquedas entre máquinas, ni ensamblar marcas de tiempo a mano. Abres una página y ya estás observando producción. -Las filas tienen código de colores por tipo, así puedes leer el stream de un vistazo en lugar de analizar cada línea. A simple vista, cada fila te muestra: +Las filas tienen código de color por tipo, de modo que puedes leer el flujo de un vistazo en lugar de analizar cada línea. A simple vista, cada fila te muestra: -- **Su tipo**, con código de colores: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` y más. -- **Un resumen en una línea** de lo que ocurrió, para que rara vez necesites abrir algo solo para entender el contexto. -- **Conteos de tokens** del paso. -- **Un indicador de uso de ventana de contexto** donde corresponde, para que el crecimiento del prompt y una compactación inminente sean visibles antes de que causen problemas. +- **Su tipo**, con código de color: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, y más. +- **Un resumen de una línea** de lo que ocurrió, para que rara vez necesites abrir nada solo para entender la idea general. +- **Conteos de tokens** para el paso. +- **Un indicador de ocupación de la ventana de contexto** donde aplique, para que el crecimiento del prompt y una compactación inminente sean visibles antes de que se conviertan en un problema. -Observarlo en vivo significa que detectas un deploy problemático, un bucle descontrolado o una ráfaga de errores en el momento en que ocurre, no en la revisión de logs del día siguiente. +Observarlo en vivo significa que detectas un despliegue fallido, un bucle descontrolado o una ráfaga de errores en el momento en que ocurre, no en la revisión de logs del día siguiente. ## Encuentra la ejecución que importa -Cuando algo parece mal, no quieres ver todo el flujo. Quieres la única ejecución que falló. El stream se filtra rápidamente: por entorno, por agente, por sesión, por tipo de evento o por texto libre. +Cuando algo parece mal, no quieres el flujo masivo de datos. Quieres la ejecución específica que falló. El flujo se filtra rápidamente: por entorno, por agente, por sesión, por tipo de evento o por texto libre. -Filtra por ID de sesión o ID de agente para seguir una ejecución desde su primer evento hasta el último. Filtra por tipo de evento para aislar un único tipo de actividad; por ejemplo, todos los `error` de la organización en una sola vista. Apila filtros para pasar de "todo, en todas partes" a "este agente, en prod, con errores" en un par de clics, y luego actúa sobre lo que encuentres. +Filtra por id de sesión o id de agente para seguir una ejecución desde su primer evento hasta el último. Filtra por tipo de evento para aislar un único tipo de actividad, por ejemplo, todos los `error` de la organización en una sola vista. Combina filtros para pasar de "todo, en todas partes" a "este agente, en prod, con errores" en un par de clics, y luego actúa sobre lo que encuentres. -La búsqueda de texto libre va directamente a un mensaje, nombre de herramienta o ID que ya tienes a mano, para que un reporte de un cliente se convierta en la ejecución exacta en cuestión de segundos. +La búsqueda por texto libre va directo a un mensaje, un nombre de herramienta o un id que ya tienes a mano, de modo que un reporte de un cliente se convierte en la ejecución exacta en cuestión de segundos. ## Dónde encontrarlo -El Stream de Eventos es la página principal de tu organización. Inicia sesión y es la primera pantalla en la que aterrizas, en `//`, para que el triaje comience en el segundo en que llegas. +El Flujo de Eventos es la página principal de tu organización. Inicia sesión y es la primera pantalla en la que aterrizas, en `//`, para que el triaje comience en el segundo en que llegas. -Detrás de escena, tus agentes emiten eventos a través del SDK, el colector los envía a tu servidor de Observabilidad de Failproof AI, y el stream los muestra en tiempo real a medida que llegan en la infraestructura que tú controlas. Cuando quieres la vista consolidada en lugar del historial en bruto, los eventos de cada ejecución se colapsan en una sola fila en Sesiones, a un clic de distancia. +Detrás de esto, tus agentes emiten eventos a través del SDK, el colector los envía a tu servidor de Observabilidad de Failproof AI, y el flujo los registra a medida que llegan en la infraestructura que tú controlas. Cuando quieras la vista consolidada en lugar del rastro sin procesar, los eventos de cada ejecución se colapsan en una sola fila en Sesiones, a un clic de distancia. -Esta es la fuente de verdad en bruto sobre la que se construye cada otra superficie de observabilidad, así que cuando un número parece incorrecto en otro lugar, el stream es donde confirmas lo que realmente ocurrió. +Esta es la fuente de verdad sin procesar sobre la que se construyen todas las demás superficies de observación, así que cuando un número parece incorrecto en otro lugar, el flujo es donde confirmas lo que realmente ocurrió. ## Relacionado -- [Sesiones](/es/agenteye/sessions): los mismos eventos agrupados en una fila por ejecución, con un gráfico de ejecución al estilo de git. -- [Telemetría](/es/agenteye/telemetry): qué envían tus agentes y cómo llegan los eventos al stream. -- [Seguimiento de errores](/es/agenteye/error-tracking): una sola superficie de triaje para todo lo que salió mal. -- [Alertas](/es/agenteye/alerts): convierte cualquier umbral en una regla de notificación. -- [CLI y agentes](/es/agenteye/cli-and-agents): el mismo historial en tiempo real desde tu terminal. \ No newline at end of file +- [Sessions](/es/agenteye/sessions): los mismos eventos consolidados en una fila por ejecución, con un gráfico de ejecución estilo git. +- [Telemetry](/es/agenteye/telemetry): lo que envían tus agentes y cómo los eventos llegan al flujo. +- [Error tracking](/es/agenteye/error-tracking): una única superficie de triaje para todo lo que salió mal. +- [Alerts](/es/agenteye/alerts): convierte cualquier umbral en una regla de notificación. +- [CLI and agents](/es/agenteye/cli-and-agents): el mismo rastro en vivo desde tu terminal. \ No newline at end of file diff --git a/docs/es/agenteye/hermes-capture.mdx b/docs/es/agenteye/hermes-capture.mdx index 8975feab..00bce9dc 100644 --- a/docs/es/agenteye/hermes-capture.mdx +++ b/docs/es/agenteye/hermes-capture.mdx @@ -3,25 +3,25 @@ title: "Captura de sesiones de Hermes" description: "Incorpora las sesiones del gateway Hermes de tu equipo — Slack, Telegram, CLI y ejecuciones programadas — en AgentEye como sesiones y eventos ordinarios." --- -[Hermes](https://hermes-agent.nousresearch.com) responde a tu equipo desde donde ya trabajan — Slack, Telegram, la CLI, ejecuciones programadas. La captura de sesiones de Hermes lleva todo eso a AgentEye como sesiones y eventos ordinarios, de modo que el asistente con el que tu equipo habla cada día sea tan observable como los agentes que tú mismo escribes. +[Hermes](https://hermes-agent.nousresearch.com) responde a tu equipo desde donde ya trabajan — Slack, Telegram, la CLI, ejecuciones programadas. La captura de sesiones de Hermes incorpora todo eso en AgentEye como sesiones y eventos ordinarios, de modo que el asistente con el que tu equipo interactúa cada día resulta tan observable como los agentes que tú mismo escribes. -Un pequeño recolector en segundo plano lee el almacén de sesiones local de Hermes a medida que se va escribiendo y envía las sesiones a AgentEye. Funciona igual que la captura de [Codex](/es/agenteye/codex-capture) y [OpenClaw](/es/agenteye/openclaw-capture), y un único recolector puede capturar varios al mismo tiempo. +Un pequeño recolector en segundo plano lee el almacén de sesiones local de Hermes a medida que se escribe y envía las sesiones a AgentEye. Funciona de la misma forma que la captura de [Codex](/es/agenteye/codex-capture) y [OpenClaw](/es/agenteye/openclaw-capture), y un único recolector puede capturar varios al mismo tiempo. --- ## Qué captura -Se captura cada sesión de Hermes en la máquina, independientemente del canal por el que llegó. Cada una se convierte en una [sesión](/es/agenteye/sessions) de AgentEye; sus mensajes de usuario y asistente, llamadas a herramientas y resultados de herramientas se convierten en los [eventos](/es/agenteye/event-stream) correspondientes. +Se captura cada sesión de Hermes en la máquina, independientemente del canal desde el que provenga. Cada una se convierte en una [sesión](/es/agenteye/sessions) de AgentEye; sus mensajes de usuario y asistente, llamadas a herramientas y resultados de herramientas se convierten en los [eventos](/es/agenteye/event-stream) correspondientes. -El canal desde el que se inició una sesión — Slack, Telegram, CLI o una ejecución programada — queda registrado en la sesión, de modo que puedes distinguirlas y filtrar por una a la vez. Junto a esto se almacenan el modelo sobre el que se ejecutó la sesión, el chat y la persona desde la que se inició, y, cuando una sesión dio lugar a otra, el enlace de vuelta a su sesión padre. +El canal desde el que se inició una sesión — Slack, Telegram, CLI o una ejecución programada — queda registrado en la sesión, de modo que puedes distinguirlas y filtrar por una a la vez. Junto a eso se almacena el modelo con el que se ejecutó la sesión, el chat y la persona desde la que se inició y, cuando una sesión generó otra, el vínculo con su sesión padre. -Las sesiones aparecen en cuanto Hermes las inicia, independientemente de si ya se ha dicho algo, y la respuesta de un turno y sus llamadas a herramientas se mantienen en el orden en que realmente ocurrieron. Cuando una sesión finaliza, también obtienes el motivo del cierre, su coste y cuántos tokens utilizó. +Las sesiones aparecen en cuanto Hermes las inicia, haya o no mensajes todavía, y la respuesta de un turno y sus llamadas a herramientas se conservan en el orden en que realmente ocurrieron. Cuando una sesión finaliza, también obtienes el motivo del cierre, el coste y el número de tokens utilizados. --- ## Cómo activarlo -La captura está desactivada hasta que la habilites. Instala el recolector con una clave de API que tenga el permiso `events:add` (consulta [API keys](/es/agenteye/api-keys)) y activa la captura de Hermes: +La captura está desactivada hasta que la habilites. Instala el recolector con una clave de API que tenga el permiso `events:add` (consulta [Claves de API](/es/agenteye/api-keys)) y activa la captura de Hermes: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ @@ -34,20 +34,20 @@ Esto instala el recolector, lo registra como servicio en segundo plano y comienz agenteye-collector health ``` -¿Capturas más de un agente en la misma máquina? Añade el indicador de cada uno al mismo comando — por ejemplo `--hermes-enabled --codex-enabled`. +¿Vas a capturar más de un agente en la misma máquina? Añade el indicador de cada uno al mismo comando — por ejemplo, `--hermes-enabled --codex-enabled`. -En la primera ejecución, tus sesiones de Hermes existentes se importan retroactivamente una vez y la nueva actividad se transmite en segundos. Los datos propios de Hermes solo se leen — nunca se modifican ni eliminan — y cada mensaje se envía una sola vez, incluso tras reinicios. +En la primera ejecución, tus sesiones de Hermes existentes se importan una vez y la actividad nueva fluye en cuestión de segundos. Los datos propios de Hermes solo se leen — nunca se modifican ni se eliminan — y cada mensaje se envía una sola vez, incluso tras reinicios. -`health` también te indica si todo lo que capturó el recolector llegó realmente a AgentEye. Si un lote no pudo entregarse, se conserva y se reintenta en lugar de descartarse, y la comprobación reporta estado no saludable mientras haya algo pendiente — así que "saludable" significa que tus datos han llegado, no simplemente que el proceso está activo. +`health` también indica si todo lo que el recolector capturó llegó realmente a AgentEye. Si un lote no pudo entregarse, se conserva y se reintenta en lugar de descartarse, y la comprobación reporta estado no saludable mientras haya elementos pendientes — así que "saludable" significa que tus datos llegaron, no simplemente que el proceso está activo. --- ## Dónde aparece -Las sesiones capturadas aparecen en **Sessions**, y sus eventos en el flujo **Events**, igual que cualquier otro agente que observes — de modo que la [reproducción de sesiones](/es/agenteye/sessions), la [búsqueda](/es/agenteye/queries), las [evaluaciones](/es/agenteye/evaluations) y las [alertas](/es/agenteye/alerts) funcionan sobre ellas. Filtra por el agente Hermes para verlas por separado. +Las sesiones capturadas aparecen en **Sessions**, y sus eventos en el flujo de **Events**, igual que cualquier otro agente que observes — por lo que [la reproducción de sesiones](/es/agenteye/sessions), la [búsqueda](/es/agenteye/queries), las [evaluaciones](/es/agenteye/evaluations) y las [alertas](/es/agenteye/alerts) funcionan con ellas. Filtra por el agente Hermes para verlas de forma independiente. --- ## Privacidad -Las sesiones de Hermes contienen la transcripción completa — incluyendo la salida de comandos, el contenido de archivos y todo lo que el agente leyó o escribió — y pueden contener secretos. Las sesiones capturadas se envían tal cual, así que activa la captura solo donde sea apropiado centralizar ese contenido en AgentEye, y proporciona al recolector una clave con alcance limitado a `events:add`. Consulta [Security](/es/agenteye/security) para saber cómo se mantienen aislados tus datos. \ No newline at end of file +Las sesiones de Hermes contienen la transcripción completa — incluyendo la salida de comandos, el contenido de archivos y todo lo que el agente leyó o escribió — y pueden contener secretos. Las sesiones capturadas se envían tal cual, así que activa la captura solo donde centralizar ese contenido en AgentEye sea apropiado, y proporciona al recolector una clave con alcance únicamente a `events:add`. Consulta [Seguridad](/es/agenteye/security) para conocer cómo se mantienen aislados tus datos. \ No newline at end of file diff --git a/docs/es/agenteye/incidents.mdx b/docs/es/agenteye/incidents.mdx index 53dcd83a..a4a1f260 100644 --- a/docs/es/agenteye/incidents.mdx +++ b/docs/es/agenteye/incidents.mdx @@ -1,28 +1,28 @@ --- title: "Incidentes" -description: "Cuando se dispara una alerta, todos pueden ver que el incidente está abierto, quién lo gestiona y qué ha ocurrido hasta el momento — en una única línea de tiempo atribuida." +description: "Cuando se activa una alerta, todos pueden ver que el incidente está abierto, quién es el responsable y qué ha ocurrido hasta ese momento, en una única línea de tiempo atribuida." --- -Cuando se dispara una alerta, la primera pregunta siempre es "¿quién lo está atendiendo?". Los incidentes responden esa pregunta: en el momento en que algo supera un umbral, todos pueden ver que el incidente está abierto, quién lo gestiona y exactamente qué ha ocurrido hasta ahora, con un registro limpio y atribuido que puedes entregar directamente a una revisión post-mortem. +Cuando se activa una alerta, la primera pregunta siempre es «¿quién está en ello?». Los incidentes dan la respuesta: en el momento en que algo supera un umbral, todos pueden ver que el incidente está abierto, quién es el responsable y exactamente qué ha ocurrido hasta ahora, con un registro limpio y atribuido que puedes entregar directamente a una retrospectiva. -![La bandeja de incidentes: tarjetas de incidentes vinculadas a alertas y abiertas manualmente, agrupadas por estado, cada una con un indicador de severidad y un responsable asignado](/agenteye/images/incidents.png) -*La bandeja agrupa los incidentes abiertos por estado y filtra por severidad y responsable, para que veas de inmediato qué requiere atención humana.* +![La bandeja de Incidentes: tarjetas de incidentes vinculadas a alertas y abiertas manualmente, agrupadas por estado, cada una con una insignia de severidad y un responsable asignado](/agenteye/images/incidents.png) +*La bandeja agrupa los incidentes abiertos por estado y filtra por severidad y responsable, para que veas de un vistazo qué necesita atención humana ahora mismo.* ## Saber quién lo tiene, de un vistazo -No más "¿alguien está mirando esto?" en un hilo de chat. Un incumplimiento abre un incidente automáticamente y lo coloca en una bandeja compartida, agrupada por estado. Acéptalo y tu nombre queda registrado, para que el resto del equipo sepa que está atendido. La aceptación es compartida: varios operadores pueden aceptar el mismo incidente y cada uno queda registrado de forma individual, de modo que todo el equipo de guardia aparece por nombre en lugar de pisarse unos a otros. Asigna un responsable para el triaje y filtra la bandeja por severidad o responsable para quedarte solo con lo que te corresponde. +Se acabó el «¿alguien está mirando esto?» en un hilo de chat. Un umbral superado abre un incidente automáticamente y lo deposita en una bandeja compartida, agrupada por estado. Al reconocerlo, tu nombre queda registrado, de modo que el resto del equipo sabe que está atendido. El reconocimiento es compartido: varios operadores pueden confirmar el mismo incidente y cada uno queda registrado por separado, así que una sala de guerra completa aparece por nombre en lugar de pisarse unos a otros. Asigna un único responsable para el triaje y filtra la bandeja por severidad o responsable para quedarte solo con lo que es tuyo. -## Toda la historia, en una sola línea de tiempo +## Toda la historia, en una única línea de tiempo -Cuando el incidente termina, ya tienes el informe escrito. Abre cualquier incidente y verás la evidencia del incumplimiento, sus responsables y suscriptores, un hilo de comentarios para coordinar en el momento, y una línea de tiempo de actividad de solo escritura. +Cuando el incidente termina, ya tienes el informe listo. Abre cualquier incidente y encontrarás la evidencia del umbral superado, sus responsables y suscriptores, un hilo de comentarios para coordinar en el mismo lugar y una línea de tiempo de actividad de solo adición. -![Vista detallada de un incidente: la alerta padre y el resumen del incumplimiento, responsables y suscriptores, una línea de tiempo de actividad atribuida y un hilo de comentarios](/agenteye/images/incident-detail.png) +![Vista de detalle de un incidente: la alerta principal y el resumen del umbral superado, responsables y suscriptores, una línea de tiempo de actividad atribuida y un hilo de comentarios](/agenteye/images/incident-detail.png) *Todo lo que ocurrió, en orden, cada línea firmada por quien lo hizo.* -Cada acción (abierto, aceptado, resuelto, etc.) queda registrada en esa línea de tiempo y nunca se edita ni elimina. Cada entrada está atribuida: al operador que la realizó, por correo electrónico, o a **automated** para cualquier cosa que Failproof AI Observability hizo de forma autónoma, como abrir el incidente al detectar el incumplimiento. Nada es anónimo y nada se pierde, por lo que el post-mortem prácticamente se escribe solo. +Cada acción (abierto, reconocido, resuelto, etc.) se escribe en esa línea de tiempo y nunca se edita. Cada entrada está atribuida: al operador que la realizó, por correo electrónico, o a **automated** para cualquier cosa que Failproof AI Observability haya hecho por su cuenta, como abrir el incidente al detectar el umbral superado. Nada es anónimo y nada se pierde, así que la retrospectiva prácticamente se escribe sola. -## Cómo progresa un incidente +## Cómo avanza un incidente ```mermaid stateDiagram-v2 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **Abierto (firing):** el incumplimiento abre el incidente y notifica tus canales una sola vez. Los incumplimientos posteriores se agrupan en el mismo incidente y actualizan su evidencia en lugar de notificarte repetidamente. -- **Aceptado (acknowledged):** un operador lo toma. Permanece abierto, y los incumplimientos posteriores actualizan la evidencia sin generar ruido adicional. -- **Resuelto (resolved):** un operador lo cierra. La resolución automática cuando la condición se normaliza está planificada pero aún no está habilitada, por lo que un incidente permanece abierto hasta que un humano lo resuelva — lo que mantiene a todos honestos sobre qué es lo que realmente se ha resuelto. Un nuevo incidente puede abrirse sobre la misma alerta más adelante. +- **Abierto (firing):** el umbral superado abre el incidente y notifica tus canales una sola vez. Los umbrales superados repetidos se agrupan en el mismo incidente y actualizan su evidencia en lugar de notificarte una y otra vez. +- **Reconocido:** un operador lo asume. Permanece abierto y los umbrales superados posteriores actualizan la evidencia de forma silenciosa. +- **Resuelto:** un operador lo cierra. La resolución automática al despejarse la condición está planificada pero aún no está habilitada, por lo que un incidente permanece abierto hasta que un humano lo resuelve, lo que mantiene la honestidad sobre qué se ha despejado realmente. Más adelante puede abrirse un nuevo incidente sobre la misma alerta. -Una alerta puede tener como máximo un incidente abierto a la vez, por lo que una regla inestable no puede sepultarte en duplicados. También puedes abrir un incidente de forma manual: uno independiente para algo que ninguna alerta capturó, o uno vinculado a una alerta existente, si tienes el permiso `incidents:write`. +Una alerta puede tener como máximo un incidente abierto a la vez, de modo que una regla inestable no puede sepultarte en duplicados. También puedes abrir un incidente manualmente: uno independiente para algo que ninguna alerta detectó, o uno vinculado a una alerta existente, si dispones del permiso `incidents:write`. ## Dónde encontrarlo -Los incidentes se encuentran en `//incidents`. Para ver los incidentes se necesita **`incidents:read`**; para abrir un incidente manual se necesita **`incidents:write`**; aceptar, asignar, comentar y resolver requieren **`incidents:ack`**. Las claves antiguas que tenían el permiso retirado `alerts:ack` siguen funcionando, ya que se reconoce como `incidents:ack`, por lo que tu rotación de guardia no necesita ser reemitida. +Los incidentes están disponibles en `//incidents`. Para verlos se necesita **`incidents:read`**; para abrir un incidente manual se necesita **`incidents:write`**; para reconocer, asignar, comentar y resolver se necesita **`incidents:ack`**. Las claves antiguas que otorgaban el permiso retirado `alerts:ack` siguen funcionando, ya que se reconoce como `incidents:ack`, por lo que tu rotación de guardia no necesita ser reemitida. ## Relacionado - [Alertas](/es/agenteye/alerts): las reglas que abren estos incidentes cuando se supera un umbral. -- [Seguimiento de errores](/es/agenteye/error-tracking): ve todos los fallos en un solo lugar y promueve uno a alerta. -- [Auditorías](/es/agenteye/audits): el analista programado que encuentra los fallos que ninguna regla estaba supervisando. \ No newline at end of file +- [Seguimiento de errores](/es/agenteye/error-tracking): consulta todos los fallos en un único lugar y promueve uno a alerta. +- [Auditorías](/es/agenteye/audits): el analista programado que encuentra los fallos que ninguna regla estaba vigilando. \ No newline at end of file diff --git a/docs/es/agenteye/observability.mdx b/docs/es/agenteye/observability.mdx index 9e9b7552..2fcb4c8d 100644 --- a/docs/es/agenteye/observability.mdx +++ b/docs/es/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- title: "Observar" -description: "Las superficies de observación son donde vigilas lo que hacen tus agentes en tiempo real y profundizas en cualquier ejecución individual." +description: "Las superficies de observación son donde monitoreas lo que tus agentes están haciendo en este momento y profundizas en cualquier ejecución individual." --- -Las superficies de observación son donde vigilas lo que hacen tus agentes en tiempo real y profundizas en cualquier ejecución individual. Todo aquí es en vivo, limitado a tu organización y filtrable por rango de fechas, entorno, agente y sesión, para que pases de "algo no cuadra" a la ejecución exacta en segundos. +Las superficies de observación son donde monitoreas lo que tus agentes están haciendo en este momento y profundizas en cualquier ejecución individual. Todo aquí es en tiempo real, con alcance a tu organización y filtrable por rango de fechas, entorno, agente y sesión, para que pases de "algo no parece estar bien" a la ejecución exacta en segundos. -![El flujo de eventos en vivo, con código de colores por tipo y filtrable por entorno, agente y sesión](/agenteye/images/events-stream.png) +![El flujo de eventos en vivo, codificado por colores según el tipo y filtrable por entorno, agente y sesión](/agenteye/images/events-stream.png) Cuatro superficies, cada una con su propia página: -- **[Flujo de eventos](/es/agenteye/event-stream)**: el rastro en vivo, paso a paso, de cada ejecución de todos los agentes, del más reciente al más antiguo. El inicio de tu organización y el primer punto de triaje. -- **[Sesiones y grafo de ejecución](/es/agenteye/sessions)**: esos eventos agrupados en una fila por ejecución, más una imagen estilo git de cómo se desarrolló cada ejecución. -- **[Métricas de rendimiento](/es/agenteye/telemetry)**: mapas de calor de latencia y métricas p50/p95/p99 para tus modelos, herramientas y hooks, para que un pico en la cola destaque frente a la mediana. -- **[Seguimiento de errores](/es/agenteye/error-tracking)**: una superficie de triaje unificada para todo lo que salió mal, a un clic de una alerta activa a la ejecución que falló. +- **[Flujo de eventos](/es/agenteye/event-stream)**: el registro en vivo, paso a paso, de cada ejecución en todos los agentes, con las más recientes primero. La página de inicio de tu organización y el primer punto de triaje. +- **[Sesiones y gráfico de ejecución](/es/agenteye/sessions)**: esos eventos consolidados en una fila por ejecución, más una representación visual al estilo de git de cómo se desarrolló cada ejecución. +- **[Métricas de rendimiento](/es/agenteye/telemetry)**: mapas de calor de latencia y valores p50/p95/p99 para tus modelos, herramientas y hooks, para que un pico en la cola destaque frente a la mediana. +- **[Seguimiento de errores](/es/agenteye/error-tracking)**: una única superficie de triaje para todo lo que salió mal, a un clic de una alerta activa a la ejecución que falló. ## Relacionado -- [Evaluaciones](/es/agenteye/evaluations): puntúa cada ejecución en términos de calidad. +- [Evaluaciones](/es/agenteye/evaluations): puntúa cada ejecución por calidad. - [Alertas](/es/agenteye/alerts): convierte cualquier umbral en una regla de notificación. -- [Auditorías](/es/agenteye/audits): deja que Failproof AI Observability encuentre patrones de fallo en las sesiones por ti. +- [Auditorías](/es/agenteye/audits): deja que Failproof AI Observability encuentre patrones de fallos entre sesiones por ti. - [CLI y agentes](/es/agenteye/cli-and-agents): la misma observabilidad desde tu terminal. \ No newline at end of file diff --git a/docs/es/agenteye/openclaw-capture.mdx b/docs/es/agenteye/openclaw-capture.mdx index 9ac113a4..887a3a9a 100644 --- a/docs/es/agenteye/openclaw-capture.mdx +++ b/docs/es/agenteye/openclaw-capture.mdx @@ -1,17 +1,17 @@ --- title: "Captura de sesiones de OpenClaw" -description: "Transmite las sesiones locales de OpenClaw de tu equipo a AgentEye como sesiones y eventos ordinarios, sin cambiar la forma en que OpenClaw se ejecuta." +description: "Envía las sesiones locales de OpenClaw de tu equipo a AgentEye como sesiones y eventos ordinarios, sin modificar la forma en que OpenClaw funciona." --- -Si tu equipo usa [OpenClaw](https://docs.openclaw.ai), la captura de sesiones de OpenClaw incorpora esas sesiones en AgentEye como sesiones y eventos ordinarios, para que puedas buscarlas, reproducirlas y evaluarlas junto al resto de lo que observas. Complementa el [SDK de Python](/es/agenteye/python-sdk): el SDK instrumenta los agentes que tú escribes, mientras que esto captura el trabajo de OpenClaw que tu equipo ya realiza, sin ningún cambio en cómo lo ejecuta. +Si tu equipo utiliza [OpenClaw](https://docs.openclaw.ai), la captura de sesiones de OpenClaw incorpora esas sesiones en AgentEye como sesiones y eventos ordinarios, para que puedas buscarlas, reproducirlas y evaluarlas junto con todo lo demás que observas. Complementa al [SDK de Python](/es/agenteye/python-sdk): el SDK instrumenta los agentes que tú escribes, mientras que esta función captura el trabajo de OpenClaw que tu equipo ya realiza, sin cambiar en absoluto su forma de ejecutarlo. -Un pequeño recolector en segundo plano lee los transcritos de sesión locales de OpenClaw conforme se van escribiendo y los envía a AgentEye. Funciona de la misma manera que la [captura de Codex](/es/agenteye/codex-capture), y un único recolector puede capturar ambos al mismo tiempo. +Un pequeño recolector en segundo plano lee los transcriptos de sesión locales de OpenClaw a medida que se escriben y los envía a AgentEye. Funciona del mismo modo que la [captura de Codex](/es/agenteye/codex-capture), y un único recolector puede capturar ambos al mismo tiempo. --- ## Qué captura -Cada agente configurado en la instalación de OpenClaw de una máquina es capturado por el recolector de esa máquina; no se requiere configuración por agente. +Todos los agentes configurados en la instalación de OpenClaw de una máquina son capturados por el recolector de esa máquina — no se requiere configuración por agente. Cada sesión de OpenClaw se convierte en una [sesión](/es/agenteye/sessions) de AgentEye; sus mensajes de usuario y asistente, llamadas a herramientas y resultados de herramientas se convierten en los [eventos](/es/agenteye/event-stream) correspondientes. @@ -26,24 +26,24 @@ curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main | sh -s -- --key --openclaw-enabled ``` -Esto instala el recolector, lo registra como un servicio en segundo plano y comienza a capturar. Para confirmar que está en ejecución: +Esto instala el recolector, lo registra como servicio en segundo plano e inicia la captura. Confirma que está funcionando: ```bash agenteye-collector health ``` -¿Capturas más de un agente en la misma máquina? Añade el indicador de cada uno al mismo comando; por ejemplo, `--openclaw-enabled --codex-enabled`. +¿Capturas más de un agente en la misma máquina? Añade el indicador de cada uno al mismo comando — por ejemplo, `--openclaw-enabled --codex-enabled`. -En la primera ejecución, tus sesiones de OpenClaw existentes se importan de forma retroactiva una sola vez, y la nueva actividad se transmite en cuestión de segundos. Los archivos propios de OpenClaw solo se leen; nunca se modifican, mueven ni eliminan, y cada sesión se envía exactamente una vez, incluso tras reinicios. +En la primera ejecución, tus sesiones de OpenClaw existentes se importan retroactivamente una sola vez, y la actividad nueva se transmite en cuestión de segundos. Los archivos propios de OpenClaw solo se leen — nunca se modifican, mueven ni eliminan — y cada sesión se envía exactamente una vez, incluso tras reinicios. --- ## Dónde aparece -Las sesiones capturadas aparecen en **Sessions**, y sus eventos en el flujo de **Events**, igual que cualquier otro agente que observes; por lo tanto, la [reproducción de sesiones](/es/agenteye/sessions), la [búsqueda](/es/agenteye/queries), las [evaluaciones](/es/agenteye/evaluations) y las [alertas](/es/agenteye/alerts) funcionan con ellas. Filtra por el agente de OpenClaw para verlas de forma independiente. +Las sesiones capturadas aparecen en **Sesiones**, y sus eventos en el flujo de **Eventos**, igual que cualquier otro agente que observes — de modo que la [reproducción de sesiones](/es/agenteye/sessions), la [búsqueda](/es/agenteye/queries), las [evaluaciones](/es/agenteye/evaluations) y las [alertas](/es/agenteye/alerts) funcionan sobre ellas. Filtra por el agente de OpenClaw para verlas de forma independiente. --- ## Privacidad -Los transcritos de OpenClaw contienen la sesión completa, incluida la salida de comandos, el contenido de archivos y todo lo que el agente leyó o escribió, y pueden contener secretos. Las sesiones capturadas se envían tal cual, así que activa la captura únicamente en máquinas y para equipos donde centralizar ese contenido en AgentEye sea apropiado, y proporciona al recolector una clave con alcance limitado a `events:add`. Consulta [Seguridad](/es/agenteye/security) para conocer cómo se mantienen tus datos aislados. \ No newline at end of file +Los transcriptos de OpenClaw contienen la sesión completa — incluyendo la salida de comandos, el contenido de archivos y todo lo que el agente leyó o escribió — y pueden contener secretos. Las sesiones capturadas se envían tal cual, por lo que activa la captura únicamente en las máquinas y para los equipos donde centralizar ese contenido en AgentEye sea apropiado, y asigna al recolector una clave con alcance limitado a `events:add`. Consulta [Seguridad](/es/agenteye/security) para saber cómo se mantienen tus datos aislados. \ No newline at end of file diff --git a/docs/es/agenteye/overview.mdx b/docs/es/agenteye/overview.mdx index 2429a23c..6c34c635 100644 --- a/docs/es/agenteye/overview.mdx +++ b/docs/es/agenteye/overview.mdx @@ -1,83 +1,83 @@ --- -title: "Failproof AI: Observa Agentes en Busca de Fallos" +title: "Failproof AI: Observa tus Agentes para Detectar Fallos" description: "Failproof AI Observability es una plataforma autoalojada para observar, evaluar y mejorar tus agentes de IA en producción." --- -Failproof AI Observability es una plataforma autoalojada para observar, evaluar y mejorar tus agentes de IA en producción. Registra todo lo que hacen tus agentes (cada llamada a herramientas, petición al modelo, hook y error), puntúa la calidad de cada ejecución y pone de manifiesto los fallos que no sabías que debías buscar, todo ello en un panel de control que ejecutas dentro de tu propia infraestructura. +Failproof AI Observability es una plataforma autoalojada para observar, evaluar y mejorar tus agentes de IA en producción. Registra todo lo que hacen tus agentes (cada llamada a herramientas, solicitud al modelo, hook y error), puntúa la calidad de cada ejecución y saca a la luz los fallos que no sabías que debías buscar, todo en un panel de control que ejecutas dentro de tu propia infraestructura. -Si despliegas agentes de IA y estás cansado de adivinar por qué falló una ejecución, esta es la página por la que empezar. Explica qué te ofrece Failproof AI Observability y cómo encajan las piezas, antes de que instales nada. +Si desarrollas agentes de IA y estás cansado de adivinar por qué una ejecución salió mal, esta es la página por donde empezar. Explica qué te ofrece Failproof AI Observability y cómo encajan las piezas, antes de instalar nada. > **Failproof AI Observability es un producto empresarial de Failproof AI.** ¿Quieres verlo en acción? Solicita una demo: escribe a [nikita@befailproof.ai](mailto:nikita@befailproof.ai). -![Una sesión de Failproof AI Observability dibujada como un grafo de ejecución estilo git junto a su cronología de eventos, con un desglose por ejecución de herramientas, modelos y hooks en el panel derecho](/agenteye/images/session-detail.png) +![Una sesión de Failproof AI Observability representada como un grafo de ejecución al estilo git junto a su línea de tiempo de eventos, con un desglose por ejecución de herramientas, modelos y hooks en el panel derecho](/agenteye/images/session-detail.png) -*Cada ejecución del agente se representa como un grafo de ejecución estilo git (izquierda) junto a su cronología de eventos. Los subagentes paralelos tienen su propio carril; el panel derecho desglosa las herramientas, modelos, hooks y gasto en tokens de la ejecución.* +*Cada ejecución del agente se representa como un grafo de ejecución al estilo git (izquierda) junto a su línea de tiempo de eventos. Los sub-agentes paralelos tienen su propio carril; el panel derecho desglosa las herramientas, modelos, hooks y gasto en tokens de la ejecución.* --- -## Vélo en acción +## Míralo en acción -Dos vídeos cortos muestran las dos cosas a las que los equipos recurren primero: trazar una ejecución y detectar fallos automáticamente. +Dos vídeos cortos muestran las dos cosas a las que los equipos recurren primero: rastrear una ejecución y detectar fallos automáticamente.
-*Trazado de agentes: sigue una única ejecución paso a paso, desde el objetivo hasta las herramientas y la respuesta final.* +*Rastreo de agentes: sigue una única ejecución paso a paso, desde el objetivo hasta las herramientas y la respuesta final.*
-*Failproof Audit: deja que Failproof AI Observability analice tus registros entre sesiones y te indique qué debes corregir.* +*Failproof Audit: deja que Failproof AI Observability analice tus logs a lo largo de las sesiones y te diga qué corregir.* --- ## Por qué los equipos lo usan -- **Ve lo que tu agente hizo realmente.** Cada ejecución se convierte en un grafo de ejecución legible estilo git: qué herramientas se ejecutaron en paralelo, qué subagentes se ramificaron, dónde se atascó y cuánto consumió. -- **Detecta regresiones de calidad automáticamente.** Conecta un pequeño servicio de puntuación y Failproof AI Observability puntuará cada ejecución completada, de modo que una caída en utilidad o un pico en alucinaciones aparecerá por sí solo. -- **Encuentra fallos para los que no escribiste ninguna regla.** Las auditorías recurrentes analizan tus registros entre sesiones en busca de clústeres de errores, valores atípicos de latencia, puntuaciones bajas y ejecuciones bloqueadas, y te entregan hallazgos clasificados y respaldados por evidencias. -- **Recibe alertas cuando importa.** Las reglas de umbral se activan por tasa de error, latencia, coste o puntuaciones del evaluador, y abren incidentes que puedes reconocer, asignar y resolver. -- **Haz preguntas en lenguaje natural.** Un asistente de IA integrado en el panel responde preguntas como «¿cómo evoluciona la calidad en producción esta semana?» sobre tus propios datos. Cualquier cambio que realice requiere aprobación. -- **Mantén el control de tus datos.** Failproof AI Observability es autoalojada: los eventos, los prompts y los análisis permanecen en la infraestructura que tú controlas. +- **Ve lo que tu agente realmente hizo.** Cada ejecución se convierte en un grafo de ejecución legible al estilo git: qué herramientas se ejecutaron en paralelo, qué sub-agentes se ramificaron, dónde se atascó y cuánto consumió. +- **Detecta regresiones de calidad automáticamente.** Conecta un pequeño servicio de puntuación y Failproof AI Observability puntúa cada ejecución finalizada, de modo que una caída en la utilidad o un pico de alucinaciones aparecen por sí solos. +- **Encuentra fallos para los que no escribiste ninguna regla.** Las auditorías recurrentes analizan tus logs entre sesiones en busca de grupos de errores, valores atípicos de latencia, puntuaciones bajas y ejecuciones bloqueadas, y luego te presentan hallazgos priorizados y respaldados por evidencias. +- **Recibe alertas cuando importa.** Las reglas de umbral se activan por tasa de errores, latencia, coste o puntuaciones de evaluadores, y abren incidentes que puedes reconocer, asignar y resolver. +- **Haz preguntas en lenguaje natural.** Un asistente de IA integrado en el panel responde preguntas como «¿cómo evoluciona la calidad en producción esta semana?» sobre tus propios datos. Cualquier cambio que realice requiere aprobación previa. +- **Mantén el control de tus datos.** Failproof AI Observability es autoalojado: los eventos, los prompts y los análisis permanecen en la infraestructura que tú controlas. --- -## Qué obtienes +## Qué incluye -Failproof AI Observability se organiza en torno a tres conceptos (**observar**, **analizar** y **administrar**), reflejados en la barra lateral izquierda del panel de control. +Failproof AI Observability se organiza en torno a tres conceptos (**observe**, **analyze** y **admin**), reflejados en la barra lateral izquierda del panel de control. -**Observar** (la verdad bruta de lo que ocurrió): +**Observe** (la verdad en bruto de lo que ocurrió): -- **[Flujo de eventos](/es/agenteye/event-stream)**: el rastro en tiempo real, paso a paso, de cada ejecución (llamadas a herramientas, llamadas al modelo, hooks, errores). -- **[Sesiones](/es/agenteye/sessions)**: esos eventos agrupados en una fila por ejecución, cada una lista para ser puntuada, con un grafo de ejecución estilo git. -- **[Métricas de rendimiento](/es/agenteye/telemetry)**: mapas de calor de latencia por superficie y valores p50/p95/p99 para modelos, herramientas y hooks, para que un pico en la cola destaque sobre la mediana. +- **[Flujo de eventos](/es/agenteye/event-stream)**: el rastro en vivo, paso a paso, de cada ejecución (llamadas a herramientas, llamadas al modelo, hooks, errores). +- **[Sesiones](/es/agenteye/sessions)**: esos eventos agrupados en una fila por ejecución, cada una lista para puntuar, con un grafo de ejecución al estilo git. +- **[Métricas de rendimiento](/es/agenteye/telemetry)**: mapas de calor de latencia por superficie y valores p50/p95/p99 para modelos, herramientas y hooks, para que un pico en la cola destaque frente a la mediana. - **[Seguimiento de errores](/es/agenteye/error-tracking)**: una única superficie de triaje para todo lo que salió mal, a un clic de una alerta activa. -![La página de observación de Tools: un mapa de calor de latencia, una banda de percentiles y una barra de distribución de herramientas en 24 intervalos de tiempo](/agenteye/images/tools.png) +![La página de observación de herramientas: un mapa de calor de latencia, una banda de percentiles y una barra de distribución de herramientas en 24 intervalos temporales](/agenteye/images/tools.png) -*Cada superficie de observación combina un minigráfico y valores p50/p95/p99 con un mapa de calor de latencia y una banda de percentiles. Mostrado aquí: Tools.* +*Cada superficie de observación combina una minigráfica y valores p50/p95/p99 con un mapa de calor de latencia y una banda de percentiles. En la imagen: herramientas.* -**Analizar** (convertir la actividad en respuestas): +**Analyze** (convierte la actividad en respuestas): -- **[Consultas](/es/agenteye/queries)** y **[paneles](/es/agenteye/dashboards)**: SQL guardado sobre tus eventos y evaluaciones, representado en paneles compartidos con ámbito de organización. -- **[Evaluaciones](/es/agenteye/evaluations)**: puntuaciones de calidad producidas por tu propio servicio evaluador, con el razonamiento por puntuación. -- **[Auditorías](/es/agenteye/audits)**: investigaciones recurrentes que detectan patrones de fallo entre sesiones. +- **[Consultas](/es/agenteye/queries)** y **[paneles](/es/agenteye/dashboards)**: SQL guardado sobre tus eventos y evaluaciones, representado en paneles compartidos con alcance de organización. +- **[Evaluaciones](/es/agenteye/evaluations)**: puntuaciones de calidad producidas por tu propio servicio de evaluación, con razonamiento por puntuación. +- **[Auditorías](/es/agenteye/audits)**: investigaciones recurrentes que identifican patrones de fallos entre sesiones. - **[Alertas](/es/agenteye/alerts)** e **[incidentes](/es/agenteye/incidents)**: reglas de umbral que te notifican, más un flujo de trabajo de incidentes para gestionarlos. -**Interfaces** (accede a tus datos a tu manera): +**Interfaces** (accede a tus datos como prefieras): - **[CLI](/es/agenteye/cli-and-agents)**: gestiona todo tu despliegue desde el terminal o un script, y deja que un agente de codificación lo haga por ti en lenguaje natural. - **[Asistente de IA](/es/agenteye/assistant)**: haz preguntas sobre tus agentes en lenguaje natural, directamente desde el panel de control. -- **REST API**: todo lo que hacen el panel y la CLI está respaldado por una REST API que puedes llamar directamente con una [clave de API](/es/agenteye/api-keys) con ámbito definido — ingesta eventos, consulta sesiones y evaluaciones, y gestiona paneles, alertas, auditorías, usuarios y claves, para poder integrar Failproof AI Observability en tus propias herramientas. +- **REST API**: todo lo que hacen el panel y la CLI está respaldado por una REST API que puedes llamar directamente con una [clave de API](/es/agenteye/api-keys) con permisos delimitados: ingesta eventos, consulta sesiones y evaluaciones, y gestiona paneles, alertas, auditorías, usuarios y claves, para integrar Failproof AI Observability en tus propias herramientas. -**Administrar** (gestiónalo para tu equipo): +**Admin** (gestiona la plataforma para tu equipo): -- **[Claves de API](/es/agenteye/api-keys)**: tokens con ámbito para el colector, el panel y el asistente. -- **Usuarios**: inicio de sesión sin contraseña, basado en correo electrónico, con lista de permitidos. -- **Configuración**: configuración por organización, incluidas las anulaciones de ventana de contexto de los modelos. +- **[Claves de API](/es/agenteye/api-keys)**: tokens con permisos delimitados para el recolector, el panel y el asistente. +- **Usuarios**: inicio de sesión sin contraseña por correo electrónico con lista de permitidos. +- **Configuración**: configuración por organización, incluidas las anulaciones de ventana de contexto del modelo. --- @@ -85,19 +85,19 @@ Failproof AI Observability se organiza en torno a tres conceptos (**observar**, Los datos fluyen en una sola dirección, desde el código de tu agente hasta el panel de control: tu agente (a través del SDK de Python) emite eventos al agenteye-collector, que los envía al servidor, que sirve el panel de control. Dos servicios opcionales completan el sistema: un servicio de puntuación (evaluaciones) y un servicio de asistente de IA (el chat integrado en el panel). -- **SDK de Python**: añades unas pocas llamadas `agenteye.event.*` a tu agente; los eventos se almacenan en búfer localmente. -- **agenteye-collector**: un demonio ligero en cada máquina de agente que agrupa los eventos y los envía al servidor. -- **Servidor**: ingesta tus eventos, mantiene el estado operativo en tus propias bases de datos y sirve la REST API que usan el panel, la CLI y tus propias integraciones. +- **SDK de Python**: añades algunas llamadas `agenteye.event.*` a tu agente; los eventos se almacenan en búfer localmente. +- **agenteye-collector**: un daemon ligero en cada máquina de agente que agrupa eventos y los envía al servidor. +- **Servidor**: ingesta tus eventos, mantiene el estado operacional en tus propias bases de datos y sirve la REST API que utilizan el panel, la CLI y tus propias integraciones. - **Panel de control**: donde exploras todo. - **Servicios opcionales**: un servicio de puntuación (evaluaciones) y un servicio de asistente de IA (el chat integrado en el panel). -Para el vocabulario utilizado en toda la documentación (*evento, sesión, evaluación, auditoría, hallazgo, incidente*), consulta [Conceptos](/es/agenteye/concepts). +Para el vocabulario utilizado en toda la documentación (*event, session, evaluation, audit, finding, incident*), consulta [Conceptos](/es/agenteye/concepts). --- ## Cómo obtener Failproof AI Observability -Failproof AI Observability es un producto empresarial de Failproof AI, y funciona junto con Failproof AI Enforcement — el producto de políticas y barreras de seguridad — bajo la marca Failproof AI. Se ejecuta completamente en tu propio entorno. Si aún no tienes acceso a los paquetes, solicita una demo y te ayudamos a ponerte en marcha: escribe a [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Failproof AI Observability es un producto empresarial de Failproof AI, y funciona junto con Failproof AI Enforcement —el producto de políticas y barreras de protección— bajo la marca Failproof AI. Se ejecuta íntegramente en tu propio entorno. Si aún no tienes acceso a los paquetes, solicita una demo y te ayudaremos a empezar: escribe a [nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- diff --git a/docs/es/agenteye/python-sdk-skill.mdx b/docs/es/agenteye/python-sdk-skill.mdx index 4254c8b6..f0f45d22 100644 --- a/docs/es/agenteye/python-sdk-skill.mdx +++ b/docs/es/agenteye/python-sdk-skill.mdx @@ -1,57 +1,57 @@ --- -title: "Skill del Agente Python SDK de Observabilidad de Failproof AI" -description: "Pasa de un agente sin instrumentación a eventos que puedes ver, con tu agente de código encontrando los puntos de instrumentación, escribiéndolos y verificando que funcionan." +title: "Skill de Agente del SDK de Python para Observabilidad de Failproof AI" +description: "Pasa de un agente sin instrumentación a eventos visibles, con tu agente de código encontrando los puntos de instrumentación, escribiéndolos y verificando que funcionan." --- -Dile a tu agente de código *"agrega Observabilidad de Failproof AI a este agente"* y deja que lea tu bucle, determine dónde corresponde la instrumentación, la escriba y verifique los eventos antes de dar el trabajo por terminado. +Dile a tu agente de código *"agrega Observabilidad de Failproof AI a este agente"* y deja que lea tu bucle, determine dónde corresponde la instrumentación, la escriba y verifique los eventos antes de dar la tarea por terminada. -El **skill de Python SDK** (`agenteye-python-sdk`) es un *Agent Skill*: una carpeta de instrucciones que un agente de código como Claude Code o Codex carga a demanda cuando una tarea coincide con él. Le enseña al agente a usar el [Python SDK](/es/agenteye/python-sdk) — no es una librería y no cambia nada sobre cómo funciona el SDK. +El **skill del SDK de Python** (`agenteye-python-sdk`) es un *Agent Skill*: una carpeta de instrucciones que un agente de código como Claude Code o Codex carga bajo demanda cuando una tarea coincide con él. Le enseña al agente a usar el [SDK de Python](/es/agenteye/python-sdk) — no es una librería y no cambia nada en el funcionamiento del SDK. -## La instrumentación es fácil de escribir y fácil de hacer mal sin notarlo +## La instrumentación es fácil de escribir y fácil de equivocar silenciosamente -El SDK es pequeño: trece métodos de eventos, todos con argumentos nombrados. Un agente de código puede leer la referencia del [Python SDK](/es/agenteye/python-sdk) y producir instrumentación plausible en un minuto. +El SDK es pequeño: trece métodos de eventos, todos con argumentos por nombre. Un agente de código puede leer la referencia del [SDK de Python](/es/agenteye/python-sdk) y producir una instrumentación plausible en un minuto. -El problema es que este SDK no lanza errores cuando algo está mal, y la instrumentación incorrecta se ve exactamente igual a la correcta hasta que alguien abre un dashboard y lo encuentra vacío. Los errores que cuestan tiempo real son todos silencios: +El problema es que este SDK no lanza errores cuando te equivocas, y una instrumentación incorrecta se ve exactamente igual que una correcta hasta que alguien abre el dashboard y lo encuentra vacío. Los errores que cuestan tiempo real son silencios: | El error | Lo que ves | |---|---| | Sin `agent_start` | Todos los eventos llegan. Cero sesiones. | -| Entorno nunca configurado | Todo funciona, archivado bajo `dev`. | -| `outcome="failure"` | La ejecución muestra verde — solo `failed`, `error`, `timeout`, `rejected` cuentan. | -| Un nombre de campo mal escrito | Aceptado y almacenado como un nuevo campo. | +| El entorno nunca se configura | Todo funciona, archivado bajo `dev`. | +| `outcome="failure"` | La ejecución aparece en verde — solo `failed`, `error`, `timeout`, `rejected` cuentan. | +| Un nombre de campo con typo | Aceptado y almacenado como un nuevo campo. | | Eventos emitidos desde un thread pool | Descartados silenciosamente. | -Ninguno lanza errores. Ninguno aparece en las pruebas. Todos están en el skill, declarados como un contrato con la verificación que los detecta. +Ninguno lanza errores. Ninguno aparece en los tests. Cada uno está en el skill, enunciado como un contrato con la verificación que lo detecta. ## Lo que hace, en orden El skill ejecuta los mismos tres pasos que haría un ingeniero cuidadoso: -1. **Planificar.** Lee tu bucle de agente y hace las dos preguntas que solo tú puedes responder: qué cuenta como una ejecución (tu `session_id`), y quiénes son los actores distinguibles (tu `agent_id`). Las acuerda antes de escribir código, porque cambiarlas después divide tu historial y rompe las tendencias. -2. **Escribir.** Vincula la identidad una vez por ejecución en lugar de pasarla por cada punto de llamada, y elige una forma segura para concurrencia — un detalle importante, porque el atajo obvio mezcla silenciosamente dos ejecuciones superpuestas en una sola sesión. +1. **Planificar.** Lee tu bucle de agente y hace las dos preguntas que solo tú puedes responder: qué cuenta como una ejecución (tu `session_id`) y quiénes son los actores diferenciables (tu `agent_id`). Los deja acordados antes de escribir código, porque cambiarlos después divide tu historial y rompe las tendencias. +2. **Escribir.** Enlaza la identidad una vez por ejecución en lugar de pasarla por cada punto de llamada, y elige una forma segura para concurrencia — un detalle importante, porque el atajo obvio mezcla silenciosamente dos ejecuciones superpuestas en una sola sesión. 3. **Verificar.** Ejecuta tu agente y lee los archivos de eventos resultantes, comprobando que `agent_start` está presente, que el entorno es correcto y que una ejecución produjo una sesión. -Ese tercer paso es el que la gente omite. El SDK escribe eventos en archivos locales, por lo que una integración completa puede probarse en una laptop sin servidor, sin clave de API y sin red — que es exactamente por qué el skill insiste en hacerlo. +Ese tercer paso es el que la gente omite. El SDK escribe eventos en archivos locales, así que una integración completa puede probarse en una laptop sin servidor, sin API key y sin red — que es exactamente por qué el skill insiste en hacerlo. ## Cómo se relaciona con los otros skills Tres skills, una división clara: -| Skill | Úsalo cuando | Qué modifica | +| Skill | Úsalo cuando | Qué toca | |---|---|---| -| **Skill de Python SDK** (esta página) | Quieres que tu agente *emita* telemetría — "agrega observabilidad", "¿por qué no aparece mi agente?" | Escribe código en el repositorio de tu agente. No lee nada. | -| **[Skill Evaluator](/es/agenteye/evaluator-skill)** | Quieres *puntuar* ejecuciones — "¿qué deberíamos medir?" | Escribe código en tu repositorio; lee telemetría | -| **[Skill CLI](/es/agenteye/cli-skill)** | Quieres *leer* lo que ocurrió, u operar tu despliegue | Maneja la CLI en tu nombre, incluyendo cambios | +| **Skill del SDK de Python** (esta página) | Quieres que tu agente *emita* telemetría — "agrega observabilidad", "¿por qué no aparece mi agente?" | Escribe código en el repositorio de tu agente. No lee nada. | +| **[Skill de Evaluador](/es/agenteye/evaluator-skill)** | Quieres *puntuar* ejecuciones — "¿qué deberíamos medir?" | Escribe código en tu repositorio; lee telemetría | +| **[Skill de CLI](/es/agenteye/cli-skill)** | Quieres *leer* lo que ocurrió u operar tu despliegue | Maneja la CLI como tú, incluidos los cambios | -Se encadenan en ese orden: este skill hace que los eventos fluyan, el evaluador los puntúa, la CLI los lee. No hay nada que evaluar ni nada que leer hasta que tu agente emita sesiones, así que si estás empezando desde cero, comienza aquí. +Se encadenan en ese orden: este skill hace fluir los eventos, el evaluador los puntúa y la CLI los lee. No hay nada que evaluar ni nada que leer hasta que tu agente emita sesiones, así que si estás empezando desde cero, empieza aquí. ## Requisitos previos 1. **Python 3.10+** y el código base del agente que quieres instrumentar. -2. **El SDK.** Se distribuye a los clientes como un wheel privado en lugar de desde un índice público — tu proceso de incorporación explica cómo obtenerlo e instalarlo. El skill conoce la ruta de instalación y te preguntará en lugar de adivinar si no puede encontrarla. -3. **Nada más.** Sin inicio de sesión en el dashboard, sin clave de API, sin red. El skill verifica contra los archivos de eventos que escribe el SDK, por lo que puede terminar y demostrar su trabajo sin conexión. +2. **El SDK.** Se distribuye a los clientes como un wheel privado y no desde un índice público — tu proceso de incorporación cubre cómo obtenerlo e instalarlo. El skill conoce la ruta de instalación y te preguntará en vez de adivinar si no puede encontrarla. +3. **Nada más.** Sin inicio de sesión en el dashboard, sin API key, sin red. El skill verifica contra los archivos de eventos que escribe el SDK, por lo que puede terminar y probar su trabajo sin conexión. -## Dónde obtenerlo +## Dónde conseguirlo El skill vive en la colección pública [`FailproofAI/skills`](https://github.com/FailproofAI/skills): @@ -59,40 +59,39 @@ El skill vive en la colección pública [`FailproofAI/skills`](https://github.co npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -Agrega `-g` para instalarlo en todos los proyectos en lugar de solo en el actual, y `--copy` si tu entorno no sigue enlaces simbólicos. Para Codex, pasa `-a codex`. +Agrega `-g` para instalarlo en todos los proyectos en lugar de solo el actual, y `--copy` si tu entorno no sigue enlaces simbólicos. Para Codex, pasa `-a codex`. -## Instalarlo manualmente +## Instalación manual Los Agent Skills son carpetas que contienen un `SKILL.md` más referencias. Si prefieres no usar el instalador: -- **Claude Code**: copia la carpeta `agenteye-python-sdk/` en `~/.claude/skills/` (todos los proyectos) o `/.claude/skills/` (solo ese repositorio). Claude Code la descubre automáticamente — revisa la lista `/skills`, o simplemente pregunta algo que coincida con ella. +- **Claude Code**: copia la carpeta `agenteye-python-sdk/` en `~/.claude/skills/` (todos los proyectos) o `/.claude/skills/` (solo ese repositorio). Claude Code la descubre automáticamente — verifica la lista `/skills`, o simplemente pregunta algo que coincida con él. - **Codex**: Codex lee el mismo `SKILL.md`. El archivo `agents/openai.yaml` incluido establece `allow_implicit_invocation: true`, por lo que se selecciona automáticamente cuando una tarea coincide; de lo contrario, invócalo como `$agenteye-python-sdk`. -Ejecuta tu agente **en el repositorio que contiene el código que quieres instrumentar** — el skill lee tu bucle de agente antes de proponer cualquier cosa. +Ejecuta tu agente **en el repositorio que contiene el código que quieres instrumentar** — el skill lee tu bucle de agente antes de proponer nada. -## Cómo luce una sesión +## Cómo se ve una sesión ```text tú ▸ Agrega Observabilidad de Failproof AI a este agente. -agente▸ Leo tu bucle — un despachador de herramientas en tools.py, un - wrapper de Anthropic en llm.py. Dos preguntas antes de escribir - cualquier cosa. +agente▸ Leí tu bucle — un despachador de herramientas en tools.py, un + wrapper de Anthropic en llm.py. Dos preguntas antes de escribir. ¿Qué cuenta como una ejecución? Manejas solicitudes de forma concurrente, así que usaría el id de solicitud que ya tienes en - ctx.request_id — así una sesión aquí y una solicitud en tus - logs son el mismo string. + ctx.request_id — así una sesión aquí y una solicitud en tus logs + serán el mismo string. - ¿Y quiénes son los actores? Veo un camino de planificador y un - camino de investigador. ¿Los etiqueto por separado, o para ti - es un solo agente? + ¿Y quiénes son los actores? Veo un flujo de planificador y un + flujo de investigador. ¿Los etiqueto por separado, o para ti son + un solo agente? -tú ▸ El id de solicitud está bien. Son un solo agente, llámalo +tú ▸ El id de solicitud es correcto. Son un solo agente, llámalo "assistant". agente▸ Listo. Envolví el despachador y el cliente LLM; agent_start y - agent_end delimitan handle_request, incluido el camino de error. + agent_end delimitan handle_request, incluido el flujo de error. Usé un context-local para la identidad — tu despachador ejecuta herramientas en un thread pool, y el enfoque más simple habría mezclado ejecuciones concurrentes en una sola sesión sin avisar. @@ -104,32 +103,32 @@ agente▸ Listo. Envolví el despachador y el cliente LLM; agent_start y Una cosa que NO hice: tu pool de workers en batch.py envía directamente al executor, así que los eventos de ahí se - descartarían. ¿Quieres que los corrija también? + descartarían. ¿Quieres que también lo corrija? ``` -El patrón a notar: leyó el código antes de proponer, hizo solo las preguntas que tú puedes responder, reutilizó un id que ya tenías, eligió la forma segura para concurrencia *porque* vio un thread pool, y **verificó leyendo los eventos reales** en lugar de declarar éxito — luego señaló el único lugar que sabía que fallaría silenciosamente. +El patrón a notar: leyó el código antes de proponer, hizo solo las preguntas que tú puedes responder, reutilizó un id que ya tenías, eligió la forma segura para concurrencia *porque* vio un thread pool, y **verificó leyendo los eventos reales** en lugar de declarar éxito — y luego señaló el único lugar que sabía que fallaría silenciosamente. ## Qué puedes pedirle -- *"¿Por qué no aparece mi agente en el dashboard?"* → recorre la escalera: si los eventos se están escribiendo, si `agent_start` está ahí, si el entorno es correcto, si el colector está leyendo el mismo lugar. -- *"Todo está llegando bajo dev."* → el entorno nunca se configuró, o fue restablecido por una llamada posterior. -- *"Agrega seguimiento de tokens."* → encuentra tu wrapper LLM y registra modelo, razón de parada y uso. -- *"Instrumenta los sub-agentes también."* → una sesión, etiquetas de agente distintas, anidadas bajo su padre. -- *"Escribe pruebas para la instrumentación."* → apunta el SDK a un directorio temporal y hace aserciones sobre los eventos que escribió. +- *"¿Por qué no aparece mi agente en el dashboard?"* → recorre la escalera: si los eventos se están escribiendo, si `agent_start` está ahí, si el entorno es correcto, si el colector lee desde el mismo lugar. +- *"Todo está llegando bajo dev."* → el entorno nunca se configuró, o fue sobreescrito por una llamada posterior. +- *"Agrega seguimiento de tokens."* → encuentra tu wrapper de LLM y registra el modelo, el motivo de parada y el uso. +- *"Instrumenta también los sub-agentes."* → una sesión, etiquetas de agente distintas, anidados bajo su padre. +- *"Escribe tests para la instrumentación."* → apunta el SDK a un directorio temporal y verifica los eventos que escribió. ## Qué tener en cuenta -**Deja que verifique.** El paso que hace que valga la pena usar este skill es el último — ejecutar tu agente y leer los eventos de vuelta. Un agente que escribe instrumentación y se detiene ha hecho la mitad fácil, y la mitad que falla silenciosamente es la otra. +**Deja que verifique.** El paso que hace valioso este skill es el último — ejecutar tu agente y leer los eventos. Un agente que escribe la instrumentación y se detiene ha hecho la mitad fácil, y la mitad que falla silenciosamente es la otra. **Acuerda los nombres antes del código.** `session_id` y `agent_id` son los ejes por los que agrupa cada vista. Renombrarlos después divide el historial: las ejecuciones antiguas conservan las etiquetas anteriores y tus tendencias se rompen. El skill preguntará; la respuesta vale un minuto de reflexión. **Si tu agente propone instalar el SDK desde un índice público, el skill no se cargó.** El SDK se distribuye de forma privada. Esa propuesta es una señal clara de que tu agente de código está adivinando en lugar de seguir el skill — detenlo ahí y verifica que el skill esté instalado. -Más allá de eso, su radio de acción es pequeño: escribe código en tu directorio de trabajo y archivos de eventos donde tú le indiques. No lee nada de tu despliegue ni cambia nada en él. +Más allá de eso, su radio de impacto es pequeño: escribe código en tu directorio de trabajo y archivos de eventos donde tú le indiques. No lee nada de tu despliegue ni cambia nada en él. ## Próximos pasos -- **[Python SDK](/es/agenteye/python-sdk)**: la referencia completa de eventos — cada tipo de evento y campo — detrás de lo que automatiza este skill. -- **[Sessions](/es/agenteye/sessions)**: lo que produce tu instrumentación una vez que los eventos llegan. -- **[Evaluator Agent Skill](/es/agenteye/evaluator-skill)**: el siguiente paso una vez que las ejecuciones están llegando — puntuarlas. -- **[CLI Agent Skill](/es/agenteye/cli-skill)**: leer tu telemetría de vuelta. \ No newline at end of file +- **[SDK de Python](/es/agenteye/python-sdk)**: la referencia completa de eventos — cada tipo de evento y campo — detrás de lo que automatiza este skill. +- **[Sesiones](/es/agenteye/sessions)**: lo que produce tu instrumentación una vez que los eventos llegan. +- **[Skill de Agente Evaluador](/es/agenteye/evaluator-skill)**: el siguiente paso una vez que las ejecuciones están llegando — puntuarlas. +- **[Skill de Agente CLI](/es/agenteye/cli-skill)**: leer tu telemetría de vuelta. \ No newline at end of file diff --git a/docs/es/agenteye/python-sdk.mdx b/docs/es/agenteye/python-sdk.mdx index 5cf34244..87fcb45e 100644 --- a/docs/es/agenteye/python-sdk.mdx +++ b/docs/es/agenteye/python-sdk.mdx @@ -4,11 +4,11 @@ description: "Ve exactamente qué hicieron tus agentes de IA en producción: cad --- -Ve exactamente qué hicieron tus agentes de IA en producción: cada ejecución de agente, llamada a herramienta, solicitud al modelo, hook e intervención humana. El SDK de Observabilidad de Failproof AI para Python registra ese rastro desde dentro del código de tu agente para que puedas depurar, auditar y evaluar lo que ocurrió. Úsalo siempre que quieras que Failproof AI Observability observe tus agentes. +Ve exactamente qué hicieron tus agentes de IA en producción: cada ejecución de agente, llamada a herramienta, solicitud al modelo, hook e intervención humana. El SDK de Observabilidad de Failproof AI para Python registra ese rastro desde dentro del código de tu agente para que puedas depurar, auditar y evaluar lo que ocurrió. Úsalo siempre que quieras que la Observabilidad de Failproof AI monitorice tus agentes. -Internamente, el SDK escribe eventos estructurados en archivos JSONL locales, y el daemon recolector los recoge y los envía a la plataforma de forma automática. No necesitas gestionar esos archivos tú mismo. +Internamente, el SDK escribe eventos estructurados en archivos JSONL locales, y el daemon recolector los recoge y los envía automáticamente a la plataforma. No necesitas gestionar esos archivos tú mismo. -> **Sugerencia:** ¿Eres nuevo en Failproof AI Observability? Esta página es la referencia completa de eventos del SDK. +> **Consejo:** ¿Eres nuevo en la Observabilidad de Failproof AI? Esta página es la referencia completa de eventos del SDK.
@@ -18,7 +18,7 @@ Internamente, el SDK escribe eventos estructurados en archivos JSONL locales, y ## Instalación -El SDK se distribuye a los clientes como una wheel privada en lugar de desde un índice público de paquetes. Tu proceso de incorporación cubre cómo obtenerlo, instalarlo y fijarlo — habla con tu contacto de Failproof AI si necesitas acceso. +El SDK se distribuye a los clientes como un wheel privado en lugar de desde un índice de paquetes público. Tu proceso de incorporación cubre cómo obtenerlo, instalarlo y fijarlo — habla con tu contacto de Failproof AI si necesitas acceso. Una vez instalado, confirma que lo tienes: @@ -26,7 +26,7 @@ Una vez instalado, confirma que lo tienes: python -c "import agenteye; print(agenteye.__version__)" ``` -¿Prefieres dejar que un agente de programación haga toda la integración? El [Python SDK Agent Skill](/es/agenteye/python-sdk-skill) conoce la ruta de instalación, planifica los puntos de instrumentación, los escribe y verifica que los eventos lleguen correctamente. +¿Prefieres que un agente de código realice toda la integración? El [Python SDK Agent Skill](/es/agenteye/python-sdk-skill) conoce la ruta de instalación, planifica los puntos de instrumentación, los implementa y verifica que los eventos lleguen correctamente. --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Instrumentando una llamada real -En la práctica, envuelves tu código de agente existente. Enmarca una llamada al modelo con `model_request` antes y `model_response` después, de modo que los dos eventos abarquen la solicitud real y Failproof AI Observability pueda emparejarlos: +En la práctica, envuelves tu código de agente existente. Rodea una llamada al modelo con `model_request` antes y `model_response` después, de modo que los dos eventos abarquen la solicitud real y la Observabilidad de Failproof AI pueda emparejarlos: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Envuelve las llamadas a herramientas de la misma forma con `tool_use` y `tool_result`, reutilizando el mismo `tool_call_id` en ambos. +Envuelve las llamadas a herramientas de la misma manera con `tool_use` y `tool_result`, reutilizando el mismo `tool_call_id` en el par. -Así es como se ven esos eventos una vez que llegan al panel de control, con código de colores por tipo y filtrables por entorno, agente y sesión: +Así es como se ven esos eventos una vez que llegan al dashboard, codificados por color según el tipo y filtrables por entorno, agente y sesión: -![El flujo de eventos en vivo, con código de colores por tipo de evento y filtrable por entorno, agente y sesión](/agenteye/images/events-stream.png) +![El flujo de eventos en vivo, codificado por color según el tipo de evento y filtrable por entorno, agente y sesión](/agenteye/images/events-stream.png) --- @@ -113,11 +113,11 @@ agenteye.configure( ) ``` -Llama una vez antes de cualquier llamada `event.*`. Es seguro omitirlo; los valores predeterminados funcionan sin configuración adicional. Todos los argumentos son solo por nombre; pásalos por nombre como se muestra arriba. +Llama una vez antes de cualquier llamada a `event.*`. Es seguro omitirlo; los valores predeterminados funcionan sin configuración adicional. Todos los argumentos son solo de palabras clave; pásalos por nombre como se muestra arriba. Cuando `base_dir` es `None` (el valor predeterminado), el SDK lee `$AGENTEYE_HOME` si está definido, -y en caso contrario recurre a `~/.agenteye`. Esto coincide con la propia resolución del recolector, -de modo que una sola variable de entorno `AGENTEYE_HOME` configura el spool de eventos compartido tanto +de lo contrario usa `~/.agenteye` como respaldo. Esto coincide con la resolución propia del recolector, +por lo que una única variable de entorno `AGENTEYE_HOME` configura el spool de eventos compartido tanto para el SDK como para el recolector. --- @@ -138,27 +138,27 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**Prioridad:** `configure(environment=...)` tiene precedencia sobre la variable de entorno. Si no se establece ninguno, el valor predeterminado es `"dev"`. +**Prioridad:** `configure(environment=...)` tiene precedencia sobre la variable de entorno. Si ninguno está configurado, el valor predeterminado es `"dev"`. -El valor del entorno aparece como filtro de primer nivel en el panel de control y se almacena en el servidor para consultas rápidas. +El valor del entorno aparece como un filtro de primer nivel en el dashboard y se almacena en el servidor para consultas rápidas. -> **Advertencia:** Los valores de entorno no deben contener una coma literal `,`. Los filtros del panel de control utilizan selección múltiple separada por comas en la URL (`?environment=prod,staging`), por lo que un entorno llamado `prod,blue` se dividiría en dos valores. Los eventos con entornos que contienen comas son rechazados en el momento de la ingesta. +> **Advertencia:** Los valores de entorno no deben contener una coma `,` literal. Los filtros del dashboard usan selección múltiple separada por comas en la transmisión (`?environment=prod,staging`), por lo que un entorno llamado `prod,blue` se dividiría en dos valores. Los eventos con entornos que contienen comas son rechazados en el momento de la ingesta. --- ## Datos y privacidad -El SDK registra únicamente los campos que tú pasas explícitamente. Los prompts, mensajes, entradas y salidas de herramientas, y el contenido del modelo se capturan exclusivamente porque tú los proporcionas a una llamada `event.*`. Nada se lee de tu proceso ni se captura de forma implícita. Cualquier campo que dejes sin establecer se omite completamente del evento; no se escribe en disco. +El SDK registra únicamente los campos que pasas explícitamente. Los prompts, mensajes, entradas y salidas de herramientas, y el contenido del modelo se capturan exclusivamente porque tú los proporcionas en una llamada a `event.*`. Nada se lee de tu proceso ni se captura implícitamente. Cualquier campo que dejes sin definir se omite completamente del evento; no se escribe en disco. -Esto convierte la redacción en tu elección y tu responsabilidad. Si un prompt o una carga útil de herramienta contiene PII o secretos que preferirías no almacenar, elimínalos o enmascáralos antes de pasarlos al método del evento. +Esto hace que la redacción sea tu decisión y tu responsabilidad. Si un prompt o un payload de herramienta contiene información personal o secretos que prefieres no almacenar, elimínalos o enmascáralos antes de pasarlos al método de evento. --- ## Referencia de eventos -La mayoría de los eventos vienen en pares inicio/fin que comparten un ID de correlación: `tool_use` y `tool_result` comparten un `tool_call_id`, `hook_triggered` y `hook_completed` comparten un `hook_id`, y `human_wait` y `human_input` comparten un `input_id`. Emite el evento de inicio, realiza el trabajo y luego emite el evento de fin con el mismo ID. Failproof AI Observability empareja los dos y calcula `duration_ms` por ti, por lo que nunca debes pasar `duration_ms` tú mismo. +La mayoría de los eventos vienen en pares de inicio/fin que comparten un ID de correlación: `tool_use` y `tool_result` comparten un `tool_call_id`, `hook_triggered` y `hook_completed` comparten un `hook_id`, y `human_wait` y `human_input` comparten un `input_id`. Emite el evento de inicio, realiza el trabajo y luego emite el evento de fin con el mismo ID. La Observabilidad de Failproof AI empareja los eventos y calcula `duration_ms` por ti, por lo que nunca necesitas pasar `duration_ms` tú mismo. -![El grafo de ejecución estilo git de una sesión junto a su línea de tiempo de eventos, reconstruido a partir de los eventos emparejados, con el panel de desglose de herramientas/modelo/hook](/agenteye/images/session-detail.png) +![El gráfico de ejecución estilo git de una sesión junto a su línea de tiempo de eventos, reconstruido a partir de los eventos emparejados, con el panel de desglose de herramientas/modelo/hook](/agenteye/images/session-detail.png) Todos los métodos de evento requieren estos dos campos: @@ -173,7 +173,7 @@ Todos los métodos también aceptan `**kwargs` arbitrarios para metadatos person ### `event.agent_start()` -Se emite cuando un agente comienza a trabajar. +Se emite cuando un agente comienza su trabajo. ```python agenteye.event.agent_start( @@ -203,7 +203,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Se emite cuando un agente invoca una herramienta. Se empareja con `tool_result`; el SDK calcula `duration_ms` automáticamente. +Se emite cuando un agente invoca una herramienta. Empareja con `tool_result`; el SDK calcula automáticamente `duration_ms`. ```python agenteye.event.tool_use( @@ -254,7 +254,7 @@ agenteye.event.model_request( ) ``` -Las entradas de `messages` aceptan tanto un `content` de cadena simple como un `content` de lista de bloques estilo Anthropic. Los parámetros de muestreo (`temperature`, `max_tokens`, etc.) pueden pasarse como kwargs adicionales. +Las entradas de `messages` aceptan tanto un `content` de cadena simple como un `content` de lista de bloques al estilo Anthropic. Los parámetros de muestreo (`temperature`, `max_tokens`, etc.) se pueden pasar como kwargs adicionales. --- @@ -277,13 +277,13 @@ agenteye.event.model_response( ) ``` -`content` acepta tanto una cadena simple (proveedores genéricos) como una lista de bloques de contenido estilo Anthropic. Las llamadas a herramientas viven dentro de `content` como bloques `{"type": "tool_use", ...}`, sin un campo `tool_calls` separado. +`content` acepta tanto una cadena simple (proveedores genéricos) como una lista de bloques de contenido al estilo Anthropic. Las llamadas a herramientas se encuentran dentro de `content` como bloques `{"type": "tool_use", ...}`, sin un campo `tool_calls` separado. --- ### `event.hook_triggered()` -Se emite cuando se activa un hook. Se empareja con `hook_completed`; el SDK calcula `duration_ms` automáticamente. +Se emite cuando se activa un hook. Empareja con `hook_completed`; el SDK calcula automáticamente `duration_ms`. ```python agenteye.event.hook_triggered( @@ -335,11 +335,11 @@ agenteye.event.error( ## Eventos de supervisión humana -Los eventos de supervisión humana te dan visibilidad sobre los momentos en que una persona interviene en la ejecución del agente (esperando aprobación, proporcionando información, pausando o deteniendo el agente). Te permiten medir cuánto tardan los humanos en responder (el SDK calcula `duration_ms` automáticamente en los eventos emparejados), auditar quién pausó o interrumpió un agente, y construir flujos de trabajo de aprobación y supervisión que se muestran en el panel de control. +Los eventos de supervisión humana te brindan control sobre los momentos en que una persona interviene en la ejecución del agente (esperando aprobación, proporcionando información, pausando o deteniendo el agente). Te permiten medir cuánto tardan los humanos en responder (el SDK calcula automáticamente `duration_ms` en los eventos emparejados), auditar quién pausó o interrumpió un agente, y construir flujos de trabajo de aprobación y supervisión que se muestran en el dashboard. ### `event.human_wait()` -Se emite cuando el agente pausa su ejecución para esperar a que un humano proporcione información. Se empareja con `human_input`; el SDK calcula `duration_ms` automáticamente (cuánto tardó el humano en responder). +Se emite cuando el agente pausa la ejecución para esperar que un humano proporcione información. Empareja con `human_input`; el SDK calcula automáticamente `duration_ms` (cuánto tardó el humano en responder). ```python agenteye.event.human_wait( @@ -354,7 +354,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Se emite cuando un humano proporciona información y el agente se reanuda. Se correlaciona con `human_wait` mediante `input_id`. `duration_ms` se calcula automáticamente y no debe ser pasado por el llamador. +Se emite cuando un humano proporciona información y el agente se reanuda. Se correlaciona con `human_wait` mediante `input_id`. `duration_ms` se calcula automáticamente y no debe ser pasado por quien llama. ```python agenteye.event.human_input( @@ -368,7 +368,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Se emite cuando un humano pausa activamente el agente (por ejemplo, mediante un control del panel de control). El agente queda suspendido pero no terminado. +Se emite cuando un humano pausa activamente el agente (por ejemplo, mediante un control del dashboard). El agente queda suspendido pero no terminado. ```python agenteye.event.human_pause( @@ -381,7 +381,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -Se emite cuando un humano detiene activamente el agente en medio de su ejecución. A diferencia de `human_pause`, el trabajo del agente se termina en lugar de suspenderse. +Se emite cuando un humano detiene activamente el agente durante su ejecución. A diferencia de `human_pause`, el trabajo del agente se termina en lugar de suspenderse. ```python agenteye.event.human_interrupt( @@ -410,27 +410,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` y `environment` están reservados y lanzan `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) si se pasan como campos personalizados. `session_id` y `agent_id` son parámetros obligatorios en cada método de evento y no pueden suministrarse una segunda vez; Python lanza `TypeError` si lo haces. Establece el entorno con `configure(environment=...)` (o la variable `AGENTEYE_ENVIRONMENT`) en su lugar. +`timestamp`, `type` y `environment` están reservados y generan un `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) si se pasan como campos personalizados. `session_id` y `agent_id` son parámetros obligatorios en cada método de evento y no pueden proporcionarse una segunda vez; Python genera un `TypeError` si lo haces. Configura el entorno con `configure(environment=...)` (o la variable `AGENTEYE_ENVIRONMENT`) en su lugar. -Mantén las cargas útiles como JSON estructurado cuando quieras consultar sus campos. Los valores que JSON no admite de forma nativa —como datetimes, UUIDs, decimales, conjuntos, bytes u objetos de modelo— se convierten a cadenas para que el registro continúe de forma segura. +Mantén los payloads como JSON estructurado cuando quieras consultar sus campos. Los valores que JSON no admite de forma nativa —como fechas y horas, UUIDs, decimales, conjuntos, bytes u objetos de modelo— se convierten a cadenas para que el registro continúe de forma segura. --- ## Cómo se escriben los eventos -Los eventos se almacenan en búfer en el proceso y se vacían a disco cada `flush_interval` segundos (500 ms por defecto). Cada vaciado escribe un archivo JSONL: +Los eventos se almacenan en buffer en el proceso y se vacían al disco cada `flush_interval` segundos (predeterminado: 500 ms). Cada vaciado escribe un archivo JSONL: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -El recolector observa este directorio y sube los archivos automáticamente. No necesitas gestionar estos archivos directamente. +El recolector supervisa este directorio y sube los archivos automáticamente. No necesitas gestionar estos archivos directamente. -Cada archivo se escribe de forma atómica: el SDK escribe en un archivo temporal y luego lo renombra en su lugar, por lo que el recolector nunca ve un archivo a medio escribir. También se ejecuta un vaciado final cuando tu proceso termina, de modo que los eventos almacenados en el último intervalo no se pierden. Si el recolector está desconectado, los eventos simplemente se acumulan como archivos en disco y se envían una vez que vuelve a estar disponible. +Cada archivo se escribe de forma atómica: el SDK escribe en un archivo temporal y luego lo renombra a su lugar definitivo, de modo que el recolector nunca ve un archivo escrito a medias. También se ejecuta un vaciado final cuando tu proceso termina, para que los eventos almacenados en el último intervalo no se pierdan. Si el recolector está desconectado, los eventos simplemente se acumulan como archivos en disco y se envían una vez que vuelva a estar en línea. --- ## Próximos pasos -- [Flujo de eventos](/es/agenteye/event-stream): observa cómo llegan estos eventos en vivo, con código de colores y filtrables por entorno, agente y sesión. -- [Sesiones](/es/agenteye/sessions): ve cómo los eventos emparejados reconstruyen cada ejecución del agente como un grafo de ejecución y una línea de tiempo. \ No newline at end of file +- [Flujo de eventos](/es/agenteye/event-stream): observa cómo llegan estos eventos en vivo, codificados por color y filtrables por entorno, agente y sesión. +- [Sesiones](/es/agenteye/sessions): ve cómo los eventos emparejados reconstruyen cada ejecución del agente como un gráfico de ejecución y una línea de tiempo. \ No newline at end of file diff --git a/docs/es/agenteye/queries.mdx b/docs/es/agenteye/queries.mdx index 97c6f6b5..4c838342 100644 --- a/docs/es/agenteye/queries.mdx +++ b/docs/es/agenteye/queries.mdx @@ -4,53 +4,53 @@ description: "Haz cualquier pregunta sobre los datos de tu agente y obtén una r --- -Haz cualquier pregunta sobre los datos de tu agente y obtén una respuesta en segundos. La observabilidad de Failproof AI te ofrece una biblioteca de consultas guardadas y listas para ejecutar sobre tus eventos y evaluaciones, para que partas de un ejemplo funcional en lugar de un editor SQL en blanco. +Haz cualquier pregunta sobre los datos de tu agente y obtén una respuesta en segundos. La Observabilidad de Failproof AI te ofrece una biblioteca de consultas guardadas y listas para ejecutar sobre tus eventos y evaluaciones, para que puedas partir de un ejemplo funcional en lugar de un editor SQL en blanco. ![La biblioteca de consultas guardadas: una cuadrícula de consultas reutilizables, tanto presets integrados como personalizados](/agenteye/images/queries.png) *Tu biblioteca de consultas guardadas en `//queries`: presets integrados junto a las consultas que tu equipo ha guardado.* -## Empieza desde un preset, no desde una página en blanco +## Parte de un preset, no de una página en blanco -No tienes que recordar nombres de tablas ni escribir SQL desde cero. La biblioteca se abre con presets integrados para las preguntas que los equipos hacen con más frecuencia, justo al lado de las consultas que tu propio equipo ha guardado y nombrado. Elige una que se aproxime a lo que necesitas y ya estarás la mayor parte del camino hacia una respuesta. +No necesitas recordar nombres de tablas ni escribir SQL desde cero. La biblioteca se abre con presets integrados para las preguntas que los equipos hacen con más frecuencia, justo al lado de las consultas que tu propio equipo ha guardado y nombrado. Elige la que más se acerque a lo que buscas y ya tendrás gran parte de la respuesta. -Cada consulta guardada tiene alcance de organización y es compartida, así que las útiles que escriban tus compañeros también serán tuyas. Ponle nombre a una consulta y dale una descripción una sola vez, y cualquier persona de tu organización podrá encontrarla, ejecutarla o fijar sus resultados en un dashboard más adelante. +Cada consulta guardada tiene alcance de organización y es compartida, por lo que las consultas útiles que escriben tus compañeros también están disponibles para ti. Ponle nombre y descripción a una consulta una sola vez, y cualquier persona de tu organización podrá encontrarla, ejecutarla o anclar sus resultados en un dashboard más adelante. Encuéntrala en `//queries`. ## Ajústala y ejecútala en el compositor SQL -Abre cualquier consulta y aterrizará en el compositor SQL, donde puedes modificarla y ver la respuesta de inmediato: sin exportaciones, sin viajes de ida y vuelta, sin esperar a nadie. +Abre cualquier consulta y se cargará en el compositor SQL, donde puedes modificarla y ver la respuesta de inmediato: sin exportaciones, sin idas y vueltas, sin esperar a nadie. -![El compositor de consultas SQL ejecutando una consulta guardada, con una barra lateral del esquema y una cuadrícula de resultados en vivo](/agenteye/images/query-lab.png) +![El compositor de consultas SQL ejecutando una consulta guardada, con una barra lateral de esquema y una cuadrícula de resultados en tiempo real](/agenteye/images/query-lab.png) -*El compositor SQL: tu consulta a la izquierda, una barra lateral del esquema para que nunca tengas que adivinar el nombre de una columna, y una cuadrícula de resultados en vivo debajo.* +*El compositor SQL: tu consulta a la izquierda, una barra lateral de esquema para que nunca tengas que adivinar el nombre de una columna, y una cuadrícula de resultados en tiempo real debajo.* -- **Una barra lateral del esquema** muestra las tablas de análisis y sus columnas, para que puedas dar forma a una consulta sin tener que buscar los nombres de los campos. -- **Una cuadrícula de resultados en vivo** devuelve filas en el momento en que ejecutas, así iteras en segundos en lugar de adivinar una y otra vez. -- **Solo lectura por diseño.** Las consultas se ejecutan contra tu almacén de eventos y se validan en el servidor: solo se permiten instrucciones `SELECT` y `WITH`, con un tiempo de espera y un límite de filas. Una consulta exploratoria nunca puede modificar tus datos, y si una se descontrola, se detiene automáticamente. +- **Una barra lateral de esquema** muestra las tablas de analítica y sus columnas, para que puedas dar forma a una consulta sin tener que buscar nombres de campos. +- **Una cuadrícula de resultados en tiempo real** devuelve las filas en el momento en que ejecutas, para que puedas iterar en segundos en lugar de adivinar una y otra vez. +- **Solo lectura por diseño.** Las consultas se ejecutan contra tu almacén de eventos y se validan en el servidor: solo se permiten instrucciones `SELECT` y `WITH`, con un tiempo límite de ejecución y un límite de filas. Una consulta exploratoria nunca puede modificar tus datos, y si una se descontrola, se detiene automáticamente. -¿Satisfecho con el resultado? Guárdalo de vuelta en la biblioteca para que todo el equipo lo herede, o fija su salida en un dashboard como un panel de línea, barra, área o circular. +¿Satisfecho con el resultado? Guárdala en la biblioteca para que todo el equipo la herede, o ancla su salida en un dashboard como un tile de línea, barras, área o pastel. -## Ejecútalas desde la terminal, o deja que el asistente las escriba +## Ejecútalas desde la terminal o deja que el asistente las escriba -Las mismas consultas guardadas te acompañan donde quiera que trabajes: +Las mismas consultas guardadas te acompañan dondequiera que trabajes: -- **Desde la terminal.** La CLI `agenteye` lista, ejecuta y guarda exactamente las mismas consultas, para que puedas incluir un resultado en un script, integrarlo en CI o pasárselo a un agente de código. +- **Desde la terminal.** El CLI `agenteye` lista, ejecuta y guarda exactamente las mismas consultas, para que puedas incluir un resultado en un script, integrarlo en CI o pasárselo a un agente de código. ```bash -agenteye query list # las mismas consultas guardadas, desde tu terminal -agenteye query run errs --arg prod # ejecuta una e imprime las filas (añade --json para redirigirla) +agenteye query list # the same saved queries, from your terminal +agenteye query run errs --arg prod # run one and print the rows (add --json to pipe it) ``` Consulta [CLI y agentes](/es/agenteye/cli-and-agents) para ver el conjunto completo de comandos. -- **Desde el asistente de IA.** ¿No sabes cómo formular el SQL? Pregúntale al [asistente de IA](/es/agenteye/assistant) dentro del dashboard en lenguaje natural y redactará la consulta y la guardará en tu biblioteca por ti. +- **Desde el asistente de IA.** ¿No sabes cómo formular el SQL? Pregúntale al [asistente de IA](/es/agenteye/assistant) dentro del dashboard en lenguaje natural y él redactará la consulta y la guardará en tu biblioteca por ti. -Ejecutar una consulta guardada requiere el permiso `queries:run`, separado de los permisos para crear o eliminar consultas, para que puedas otorgar acceso de lectura sin permitir que todos reescriban la biblioteca. +Ejecutar una consulta guardada está controlado por el permiso `queries:run`, independiente de los permisos para crear o eliminar consultas, por lo que puedes otorgar acceso de lectura sin permitir que todos modifiquen la biblioteca. ## Relacionado -- [Dashboards](/es/agenteye/dashboards): fija los resultados de consultas en gráficos compartidos para toda la organización. +- [Dashboards](/es/agenteye/dashboards): ancla resultados de consultas en gráficos compartidos para toda la organización. - [Asistente de IA](/es/agenteye/assistant): haz preguntas en lenguaje natural y obtén una consulta como respuesta. - [CLI y agentes](/es/agenteye/cli-and-agents): ejecuta y guarda las mismas consultas desde tu terminal. \ No newline at end of file diff --git a/docs/es/agenteye/security.mdx b/docs/es/agenteye/security.mdx index 7bcada09..6aec134a 100644 --- a/docs/es/agenteye/security.mdx +++ b/docs/es/agenteye/security.mdx @@ -1,68 +1,68 @@ --- title: "Seguridad" -description: "Failproof AI Observability está diseñado para situarse cerca de tus agentes en producción, lo que significa que tiene acceso a tus prompts, entradas de herramientas y salidas." +description: "Failproof AI Observability está diseñado para operar cerca de tus agentes en producción, lo que significa que tiene acceso a tus prompts, entradas de herramientas y salidas." --- -Failproof AI Observability está diseñado para situarse cerca de tus agentes en producción, lo que significa que tiene acceso a tus prompts, entradas de herramientas y salidas. Esta página explica cómo mantiene esos datos aislados, bajo control y en tus manos. Si estás evaluando Failproof AI Observability para una revisión de seguridad, comienza aquí. +Failproof AI Observability está diseñado para operar cerca de tus agentes en producción, lo que significa que tiene acceso a tus prompts, entradas de herramientas y salidas. Esta página explica cómo mantiene esos datos aislados, controlados y en tus manos. Si estás evaluando Failproof AI Observability para una revisión de seguridad, empieza aquí. --- ## Tus datos permanecen en tu entorno -Failproof AI Observability es autoalojado. Los eventos, prompts, respuestas del modelo y las analíticas se almacenan en tus propias bases de datos, en tu propio entorno. Nada se envía a un SaaS de terceros para su almacenamiento, y tus datos permanecen en tu propia cuenta en la nube. +Failproof AI Observability es autoalojado. Los eventos, prompts, respuestas del modelo y análisis se almacenan en tus propias bases de datos, dentro de tu propio entorno. Nada se envía a un SaaS de terceros para su almacenamiento, y tus datos permanecen en tu propia cuenta en la nube. --- -## Aislamiento de inquilinos +## Aislamiento por tenant -Una sola instancia de Failproof AI Observability puede alojar muchas organizaciones, y cada una está aislada a nivel de la capa de almacenamiento — aplicado por la base de datos, no solo por la interfaz de usuario: +Una instancia de Failproof AI Observability puede alojar múltiples organizaciones, y cada una está aislada a nivel de almacenamiento — impuesto por la base de datos, no solo por la interfaz: -- Los datos operativos de una organización (usuarios, claves, paneles, consultas guardadas) están delimitados a esa organización, y las lecturas entre organizaciones están bloqueadas por la propia base de datos. -- Cada evento ingestado lleva el sello de la organización propietaria, por lo que los eventos de una organización nunca pueden ser leídos por otra. +- Los datos operativos de una organización (usuarios, claves, dashboards, consultas guardadas) están limitados a esa organización, y las lecturas entre organizaciones están bloqueadas por la propia base de datos. +- Cada evento ingestado lleva la marca de la organización propietaria, por lo que los eventos de una organización nunca pueden ser leídos por otra. -Cada ruta del panel está delimitada bajo un slug de organización (`//…`). +Cada ruta del dashboard está delimitada bajo un slug de organización (`//…`). --- ## Inicio de sesión -Failproof AI Observability utiliza inicio de sesión sin contraseña, basado en correo electrónico. No hay contraseña que pueda ser objeto de phishing o filtrarse. Un usuario solicita un código de un solo uso (o un enlace mágico de un clic), que se envía por correo electrónico y expira rápidamente. El inicio de sesión está controlado por una **lista de permitidos**: solo las direcciones de correo electrónico (o dominios) que tú autorices pueden autenticarse. +Failproof AI Observability utiliza inicio de sesión sin contraseña, basado en correo electrónico. No hay contraseña que robar ni filtrar. El usuario solicita un código de un solo uso (o un enlace mágico de un clic), que se envía por correo electrónico y expira rápidamente. El acceso está controlado por una **lista de permitidos**: solo las direcciones de correo electrónico (o dominios) que tú autorices pueden autenticarse. -![La pantalla de inicio de sesión de Failproof AI Observability, que envía un código de uso único a tu correo electrónico](/agenteye/images/login.png) +![La pantalla de inicio de sesión de Failproof AI Observability, que envía un código de un solo uso a tu correo electrónico](/agenteye/images/login.png) --- ## Acceso delimitado con claves de API -Cada cliente se autentica con una clave de API que lleva permisos granulares de mínimo privilegio. Un recopilador solo necesita `events:add`; una clave de panel o asistente puede ser de solo lectura; las acciones destructivas (eliminar, regenerar) son permisos separados que tú decides incluir. +Cada cliente se autentica con una clave de API que tiene permisos granulares y de mínimo privilegio. Un recolector solo necesita `events:add`; una clave de dashboard o de asistente puede ser de solo lectura; las acciones destructivas (eliminar, regenerar) son permisos separados que tú decides incluir. -![La página de claves de API: los permisos de cada clave, codificados por color según el alcance de lectura, escritura y destructivo](/agenteye/images/api-keys.png) +![La página de claves de API: los permisos de cada clave están codificados por color según el alcance de lectura, escritura y destructivo](/agenteye/images/api-keys.png) -Conserva la clave de arranque de administrador para la configuración, y emite claves con permisos reducidos para todo lo demás. Consulta [Claves de API](/es/agenteye/api-keys). +Conserva la clave de administración de arranque para la configuración, y emite claves con permisos reducidos para todo lo demás. Consulta [Claves de API](/es/agenteye/api-keys). --- -## Un asistente de solo lectura con aprobación previa +## Un asistente de solo lectura con aprobación obligatoria -El [asistente de IA](/es/agenteye/assistant) del panel responde preguntas sobre tus datos, pero está restringido por diseño: +El [asistente de IA](/es/agenteye/assistant) integrado en el dashboard responde preguntas sobre tus datos, pero está limitado por diseño: -- Es **de solo lectura por defecto**: su SQL se ejecuta a través de un guardián que solo permite consultas `SELECT`/`WITH`, de una sola instrucción, con un límite de filas. -- Todo lo que crea (una consulta guardada, un panel) requiere **aprobación previa**: tú revisas y apruebas cada escritura antes de que ocurra. -- **Nunca puede eliminar**. +- Es **de solo lectura por defecto**: su SQL se ejecuta a través de un filtro que solo permite consultas `SELECT`/`WITH`, de una sola instrucción y con un límite de filas. +- Todo lo que crea (una consulta guardada, un dashboard) requiere **aprobación**: tú revisas y apruebas cada escritura antes de que ocurra. +- **Nunca puede eliminar** datos. -Así, un compañero de equipo puede preguntar "¿qué agentes tuvieron más errores esta semana?" y actuar sobre la respuesta, sin que el asistente pueda modificar o eliminar tus datos por su cuenta. +Así, un compañero de equipo puede preguntar "¿qué agentes tuvieron más errores esta semana?" y actuar en consecuencia, sin que el asistente pueda modificar ni eliminar tus datos por su cuenta. --- ## En tránsito -Todo el tráfico circula a través de HTTPS. Tú terminas el TLS con tus propios certificados, por lo que el tráfico entre el recopilador y el servidor, y entre el navegador y el servidor, está cifrado en tránsito. +Todo el tráfico viaja por HTTPS. Tú terminas TLS con tus propios certificados, de modo que el tráfico del recolector al servidor y del navegador al servidor está cifrado en tránsito. --- ## Próximos pasos -- [Descripción general](/es/agenteye/overview): cómo encaja Failproof AI Observability en conjunto. -- [Claves de API](/es/agenteye/api-keys): delimita el acceso para el recopilador, el panel y el asistente. +- [Descripción general](/es/agenteye/overview): cómo encaja Failproof AI Observability. +- [Claves de API](/es/agenteye/api-keys): delimita el acceso para el recolector, el dashboard y el asistente. - [Observabilidad](/es/agenteye/observability): qué captura Failproof AI Observability de tus agentes. \ No newline at end of file diff --git a/docs/es/agenteye/sessions.mdx b/docs/es/agenteye/sessions.mdx index 430ec88e..f2fbca36 100644 --- a/docs/es/agenteye/sessions.mdx +++ b/docs/es/agenteye/sessions.mdx @@ -1,56 +1,57 @@ --- title: "Sesiones y Gráfico de Ejecución" -description: "Cada evento de una ejecución, resumido en una fila legible y representado como un gráfico de ejecución al estilo git que puedes interpretar en segundos." +description: "Todos los eventos de una ejecución, consolidados en una fila legible y representados como un gráfico de ejecución estilo git que puedes leer en segundos." --- -Deja de adivinar por qué falló una ejecución. La Observabilidad de Failproof AI consolida cada evento de una ejecución en una fila legible y luego representa la ejecución completa como un diagrama al estilo git que puedes interpretar en segundos, para que veas exactamente qué hizo tu agente, paso a paso. -![La lista de Sesiones: una fila por ejecución, a través de entornos y agentes, con indicadores de estado y etiquetas de puntuación de evaluación](/agenteye/images/sessions-list.png) +Deja de adivinar por qué falló una ejecución. La Observabilidad de Failproof AI consolida todos los eventos de una ejecución en una fila legible y luego dibuja la ejecución completa como un diagrama estilo git que puedes interpretar en segundos, para que veas exactamente qué hizo tu agente, paso a paso. -*Una fila por ejecución: el indicador de estado te dice cómo terminó la ejecución de un vistazo, y una etiqueta de puntuación aparece en cuanto conectas un evaluador.* +![La lista de Sesiones: una fila por ejecución, en todos los entornos y agentes, con indicadores de estado e insignias de puntuación de evaluación](/agenteye/images/sessions-list.png) + +*Una fila por ejecución: el indicador de estado te muestra de un vistazo cómo terminó la ejecución, y una insignia de puntuación aparece en cuanto conectas un evaluador.*
-*Trazado de agentes: sigue una sola ejecución paso a paso, desde el objetivo hasta las herramientas y la respuesta final.* +*Trazado de agentes: sigue una única ejecución paso a paso, desde el objetivo hasta las herramientas y la respuesta final.* --- ## Ve todas las ejecuciones de un vistazo -El registro de eventos en bruto es la fuente de verdad de cada paso, pero cuando tienes miles de pasos repartidos en decenas de ejecuciones, necesitas ver la ejecución, no el paso individual. La página de Sesiones consolida todos los eventos de una ejecución en una sola fila, de modo que la actividad de un día se convierte en una lista que puedes revisar de un vistazo en lugar de un flujo interminable de datos. +El rastro de eventos sin procesar es la fuente de verdad de cada paso, pero cuando tienes miles de pasos distribuidos en decenas de ejecuciones, necesitas ver la ejecución, no el paso. La página de Sesiones agrupa todos los eventos de una ejecución en una sola fila, de modo que un día de actividad se convierte en una lista escaneable en lugar de un torrente de datos. -Cada fila lleva un indicador de estado, así que una ejecución fallida resalta frente a una exitosa antes de que hagas clic en nada. Filtra por rango de fechas, entorno, agente o sesión para pasar de "todo" a "la ejecución que me interesa" en un par de clics. +Cada fila lleva un indicador de estado, así que una ejecución fallida destaca frente a una correcta antes de que hagas clic en nada. Filtra por rango de fechas, entorno, agente o sesión para pasar de «todo» a «la ejecución que me interesa» en un par de clics. -Una vez que conectas un evaluador, cada ejecución completada recibe una puntuación automáticamente y la puntuación más reciente aparece en la fila como una etiqueta. Puedes filtrar por cualquier rango de puntuación, así que "muéstrame todas las ejecuciones de producción con baja puntuación esta semana" es un filtro, no una revisión manual. Hasta que configures uno, las sesiones siguen capturando la ejecución completa; simplemente aún no llevan puntuación. +Una vez que conectas un evaluador, cada ejecución completada recibe una puntuación automáticamente y su puntuación más reciente aparece en la fila como una insignia. Puedes filtrar por cualquier rango de puntuación, de modo que «mostrarme todas las ejecuciones de producción con puntuación baja esta semana» es un filtro, no una revisión manual. Hasta que configures uno, las sesiones siguen capturando la ejecución completa; simplemente aún no llevan puntuación. --- -## Lee la ejecución completa como un diagrama +## Lee toda la ejecución como un diagrama -![El gráfico de ejecución al estilo git de una sesión junto a su cronología de eventos, con el panel de desglose de herramientas, modelos y hooks](/agenteye/images/session-detail.png) +![El gráfico de ejecución estilo git de una sesión junto a su línea de tiempo de eventos, con el panel de desglose de herramientas, modelos y hooks](/agenteye/images/session-detail.png) -*El gráfico de ejecución (izquierda) aparece junto a la cronología de eventos; el panel derecho desglosa las herramientas, modelos, hooks y el consumo de tokens de la ejecución.* +*El gráfico de ejecución (izquierda) aparece junto a la línea de tiempo de eventos; el panel derecho desglosa las herramientas, modelos, hooks y el consumo de tokens de la ejecución.* -Haz clic en cualquier sesión para abrir su gráfico de ejecución: una vista al estilo git de cómo se desarrollaron los agentes, herramientas, hooks y llamadas al modelo a lo largo del tiempo. Los subagentes paralelos se ramifican cada uno en su propio carril, de modo que puedes ver qué trabajo se ejecutó en paralelo, qué subagente se detuvo y dónde se desvió la ejecución, sin tener que reconstruirlo mentalmente a partir de una pared de registros. +Haz clic en cualquier sesión para abrir su gráfico de ejecución: una vista estilo git de cómo se desplegaron agentes, herramientas, hooks y llamadas al modelo a lo largo del tiempo. Los subagentes paralelos se ramifican en sus propios carriles, por lo que puedes ver qué trabajo se ejecutó en paralelo, qué subagente se detuvo y dónde se desvió la ejecución, sin tener que reconstruirlo mentalmente a partir de un muro de registros. -El panel derecho te ofrece el desglose por ejecución: qué herramientas y modelos se ejecutaron, qué hooks se activaron y cuántos tokens consumió la ejecución. Esa es la respuesta a "¿por qué costó tanto esta ejecución?" o "¿cuál es la herramienta más lenta?", justo al lado del gráfico que lo originó. +El panel derecho te ofrece el desglose por ejecución: qué herramientas y modelos se ejecutaron, qué hooks se dispararon y cuántos tokens consumió la ejecución. Esa es la respuesta a «¿por qué costó tanto esta ejecución?» o «¿cuál es la herramienta lenta?», justo al lado del gráfico que lo originó. -Los eventos individuales tienen su propia dirección, así que puedes pasarle a alguien un enlace a un momento concreto en lugar de "la sesión, más o menos a dos tercios". Copia el enlace desde cualquier evento, o síguelo desde un hallazgo de [auditoría](/es/agenteye/audits) o un error, y la sesión se abre con ese evento seleccionado y desplazado hasta él. Esto funciona también en ejecuciones muy largas: la cronología carga una ventana acotada por el bien de tu navegador, y un enlace que apunte más allá de esa ventana igualmente encontrará su evento en lugar de llevarte al inicio. Si el evento ha superado tu ventana de retención, la página te lo indica en lugar de seleccionar nada de forma silenciosa. +Los eventos individuales tienen su propia dirección, por lo que puedes enviarle a alguien un enlace a un momento concreto en lugar de decir «la sesión, más o menos dos tercios hacia abajo». Copia el enlace desde cualquier evento, o sigue uno desde un hallazgo de [auditoría](/es/agenteye/audits) o un error, y la sesión se abrirá con ese evento seleccionado y visible en pantalla. Esto también aplica a ejecuciones muy largas: la línea de tiempo carga una ventana acotada para no sobrecargar tu navegador, y un enlace que apunta más allá de esa ventana igualmente localiza su evento en lugar de llevarte al inicio. Si el evento ha superado tu período de retención, la página te lo indica en lugar de seleccionar nada silenciosamente. --- ## Dónde encontrarlo -Cada página del panel de control está dentro del alcance de tu organización (`//…`). Sesiones se encuentra en **Observe** en la barra lateral izquierda, junto a Eventos, con los filtros de rango de fechas, entorno, agente y sesión en la parte superior de la lista. Cada fila está a un clic de su gráfico de ejecución completo. +Cada página del panel está limitada a tu organización (`//…`). Sesiones se encuentra en **Observe** en la barra lateral izquierda, junto a Eventos, con los filtros de rango de fechas, entorno, agente y sesión en la parte superior de la lista. Cada fila está a un clic de su gráfico de ejecución completo. -Para activar las etiquetas de puntuación y el filtrado por rango de puntuación, conecta un evaluador: consulta [Evaluaciones](/es/agenteye/evaluations). +Para activar las insignias de puntuación y el filtrado por rango de puntuación, conecta un evaluador: consulta [Evaluaciones](/es/agenteye/evaluations). --- ## Relacionado -- [Flujo de eventos](/es/agenteye/event-stream): el registro en bruto por paso del que se compila cada sesión. -- [Evaluaciones](/es/agenteye/evaluations): conecta un evaluador para que cada ejecución obtenga una etiqueta de puntuación por la que puedas filtrar. -- [Telemetría](/es/agenteye/telemetry): cómo pasan las ejecuciones de tu agente a estas sesiones. \ No newline at end of file +- [Flujo de eventos](/es/agenteye/event-stream): el rastro sin procesar, paso a paso, del que se agregan todas las sesiones. +- [Evaluaciones](/es/agenteye/evaluations): conecta un evaluador para que cada ejecución reciba una insignia de puntuación por la que puedas filtrar. +- [Telemetría](/es/agenteye/telemetry): cómo llegan las ejecuciones de tu agente a estas sesiones. \ No newline at end of file diff --git a/docs/es/agenteye/telemetry.mdx b/docs/es/agenteye/telemetry.mdx index 55b69a24..4c84ec6f 100644 --- a/docs/es/agenteye/telemetry.mdx +++ b/docs/es/agenteye/telemetry.mdx @@ -1,36 +1,36 @@ --- title: "Métricas de rendimiento" -description: "Detecta al instante cuándo tus modelos, herramientas o hooks ralentizan el sistema o disparan la factura, y anticipa un pico de latencia de cola antes de que tus usuarios lo noten." +description: "Detecta al instante cuando tus modelos, herramientas o hooks se ralentizan o disparan la factura, y atrapa un pico de latencia de cola antes de que tus usuarios lo noten." --- -Detecta al instante cuándo tus modelos, herramientas o hooks ralentizan el sistema o disparan la factura, y anticipa un pico de latencia de cola antes de que tus usuarios lo noten. Tres páginas dedicadas convierten los tiempos brutos en p50, p95 y p99 que puedes leer de un vistazo. +Detecta al instante cuando tus modelos, herramientas o hooks se ralentizan o disparan la factura, y atrapa un pico de latencia de cola antes de que tus usuarios lo noten. Tres páginas dedicadas convierten tiempos en bruto en p50, p95 y p99 que puedes leer de un vistazo. -![La página de Modelos con un mapa de calor de latencia, una banda de percentiles y datos de tokens, coste y ventana de contexto por modelo](/agenteye/images/models.png) -*La página de Modelos: un mapa de calor de latencia, una banda de percentiles y, por modelo, tokens, coste estimado y ocupación de la ventana de contexto.* +![La página de Modelos mostrando un mapa de calor de latencia, una banda de percentiles y cifras de tokens, costo y ventana de contexto por modelo](/agenteye/images/models.png) +*La página de Modelos: un mapa de calor de latencia, una banda de percentiles y tokens por modelo, costo estimado y llenado de ventana de contexto.* -## Deja de permitir que los promedios oculten tus peores ejecuciones +## Deja de dejar que los promedios oculten tus peores ejecuciones -Un número de latencia promedio es tranquilizador e inútil: suaviza la llamada de cada cincuenta que se atasca y despierta a tu equipo de guardia a las 2 a.m. Las páginas de Modelos, Herramientas y Hooks se niegan a hacer eso. Todas comparten la misma estructura, así que la aprendes una sola vez: +Un número de latencia promedio resulta tranquilizador e inútil: suaviza la llamada de una entre cincuenta que se bloquea y despierta a tu guardia de turno a las 2am. Las páginas de Modelos, Herramientas y Hooks se niegan a hacer eso. Cada una comparte la misma estructura, así que la aprendes una sola vez: -- Un **sparkline de 24 intervalos** para ver la tendencia de un vistazo: ¿está empeorando? -- Una **tira de estadísticas vitales** con latencia p50, p95 y p99, de modo que la ejecución típica y la de cola se muestran una al lado de la otra. -- Un **mapa de calor de latencia**, con 24 intervalos de tiempo por rangos de latencia, que muestra *cuándo* se agruparon las llamadas lentas. -- Una **banda de percentiles**: una línea p50 con cintas sombreadas de p25 a p75 y de p10 a p90, más puntos p99, para que la dispersión sea visible en lugar de quedar diluida en un promedio. +- Una **sparkline de 24 bins** para ver la tendencia de un vistazo: ¿está empeorando? +- Una **tira de métricas vitales** con latencia p50, p95 y p99, para que la ejecución típica y la de cola queden lado a lado. +- Un **mapa de calor de latencia**, con 24 bins de tiempo por rangos de latencia, que muestra *cuándo* se agruparon las llamadas lentas. +- Una **banda de percentiles**: una línea p50 con cintas sombreadas de p25 a p75 y de p10 a p90, más puntos p99, para que la dispersión sea visible en lugar de perderse en el promedio. -Un crosshair de hover compartido vincula el mapa de calor y la banda, de modo que un pico de cola se alinea temporalmente en ambos en lugar de ocultarse detrás de una única línea media. Encontrarás las tres páginas en la sección **observe** de tu dashboard, cada una con alcance a tu organización y filtrable por rango de fechas, entorno, agente y sesión. +Un cursor cruzado compartido vincula el mapa de calor y la banda, de modo que un pico de cola queda alineado en el tiempo en ambos en lugar de esconderse detrás de una única línea de media. Encuentra las tres páginas en la sección **observe** de tu dashboard, cada una acotada a tu organización y filtrable por rango de fechas, entorno, agente y sesión. -## Modelos: ve exactamente lo que cada modelo te cuesta +## Modelos: ve exactamente lo que te cuesta cada modelo -La página de Modelos (mostrada arriba) responde las dos preguntas que siempre plantea una factura: qué modelo y cuánto. Además de la vista de latencia compartida, añade el **consumo de tokens por modelo**, el **coste estimado** y la **ocupación de la ventana de contexto**, de modo que el crecimiento desbocado de los prompts y una compactación inminente son visibles antes de que te sorprendan. +La página de Modelos (mostrada arriba) responde las dos preguntas que siempre plantea una factura: qué modelo y cuánto. Sobre la vista de latencia compartida, añade el **consumo de tokens por modelo**, el **costo estimado** y el **llenado de ventana de contexto**, para que el crecimiento descontrolado del prompt y una compactación inminente sean visibles antes de que te sorprendan. -Failproof AI Observability reconoce los IDs de modelos más comunes automáticamente. Si una ventana aparece incorrecta o ejecutas un modelo privado propio, corrígelo o añade uno en **Settings**, en **model context windows**, y las lecturas de ocupación se actualizarán en consecuencia. +Failproof AI Observability reconoce los IDs de modelos comunes automáticamente. Si una ventana parece incorrecta, o ejecutas un modelo privado propio, corrígela o añade una en **Settings**, en **model context windows**, y las lecturas de llenado se actualizarán. ## Herramientas: distingue lo lento de lo roto -Una llamada a una herramienta puede ser lenta o puede estar fallando silenciosamente, y quieres saberlo en segundos, no después de revisar logs. +Una llamada a una herramienta puede ser lenta o puede estar fallando silenciosamente, y quieres saber cuál de las dos en segundos, no después de revisar registros. -![La página de Herramientas con el mapa de calor de latencia y la banda de percentiles compartidos junto a un desglose de éxitos y fallos y una barra de distribución de herramientas](/agenteye/images/tools.png) +![La página de Herramientas mostrando el mapa de calor de latencia compartido y la banda de percentiles junto a un desglose de éxitos y fallos y una barra de distribución de herramientas](/agenteye/images/tools.png) *La página de Herramientas: el mismo mapa de calor y banda de percentiles, más un desglose de éxitos y fallos y una barra de distribución de herramientas.* Junto a la vista de latencia compartida, la página de Herramientas añade un **desglose de éxitos y fallos** y una **barra de distribución de herramientas**, para que veas de un vistazo qué herramientas usas más y cuáles están consumiendo tu presupuesto de errores. @@ -39,7 +39,7 @@ Junto a la vista de latencia compartida, la página de Herramientas añade un ** Cuando un hook de ciclo de vida ralentiza una ejecución, "los hooks son lentos" no es algo sobre lo que puedas actuar. La página de Hooks te lleva directamente al que importa. -![La página de Hooks con la latencia desglosada por nombre de hook y evento disparador sobre el mapa de calor y la banda de percentiles compartidos](/agenteye/images/hooks.png) +![La página de Hooks mostrando la latencia desglosada por nombre de hook y evento disparador sobre el mapa de calor y la banda de percentiles compartidos](/agenteye/images/hooks.png) *La página de Hooks: latencia desglosada por nombre de hook y evento disparador.* Sobre el mismo mapa de calor de latencia y banda de percentiles, la página de Hooks desglosa la actividad por **nombre de hook** y **evento disparador**, para que llegues al hook concreto y al evento concreto que necesitan atención. @@ -48,5 +48,5 @@ Sobre el mismo mapa de calor de latencia y banda de percentiles, la página de H - [Flujo de eventos](/es/agenteye/event-stream): el rastro en vivo con código de colores de cada evento. - [Sesiones](/es/agenteye/sessions): agrupa los eventos en una fila por ejecución y abre su grafo de ejecución. -- [Seguimiento de errores](/es/agenteye/error-tracking): una única superficie de triaje para todo lo que el dashboard marca en rojo. -- [Dashboards](/es/agenteye/dashboards): vistas agregadas de toda tu flota. \ No newline at end of file +- [Seguimiento de errores](/es/agenteye/error-tracking): una superficie de triaje unificada para todo lo que el dashboard marca en rojo. +- [Dashboards](/es/agenteye/dashboards): vistas consolidadas de toda tu flota. \ No newline at end of file diff --git a/docs/es/architecture.mdx b/docs/es/architecture.mdx index 9bfdb36e..a20820d7 100644 --- a/docs/es/architecture.mdx +++ b/docs/es/architecture.mdx @@ -4,16 +4,16 @@ description: "Cómo funcionan internamente el manejador de hooks, la carga de co icon: sitemap --- -Este documento explica cómo funciona failproofai internamente: cómo el sistema de hooks intercepta las llamadas a herramientas del agente, cómo se carga y combina la configuración, cómo se evalúan las políticas y cómo el panel de control monitorea la actividad del agente. +Este documento explica cómo funciona failproofai internamente: cómo el sistema de hooks intercepta las llamadas a herramientas del agente, cómo se carga y fusiona la configuración, cómo se evalúan las políticas y cómo el panel de control monitorea la actividad del agente. --- -## Descripción general +## Visión general failproofai tiene dos subsistemas independientes: 1. **Manejador de hooks** - Un subproceso CLI rápido que Claude Code invoca en cada llamada a una herramienta del agente. Evalúa las políticas y devuelve una decisión. -2. **Monitor de agentes (Panel de control)** - Una aplicación web Next.js para monitorear sesiones del agente y gestionar políticas. +2. **Monitor de agentes (Panel de control)** - Una aplicación web Next.js para monitorear sesiones de agentes y gestionar políticas. Ambos subsistemas comparten archivos de configuración en `~/.failproofai/` y en el directorio `.failproofai/` del proyecto, pero se ejecutan como procesos separados y se comunican únicamente a través del sistema de archivos. @@ -44,7 +44,7 @@ Cuando ejecutas `failproofai policies --install`, escribe entradas como esta en } ``` -Claude Code luego invoca `failproofai --hook PreToolUse` como subproceso antes de cada llamada a una herramienta, enviando un payload JSON por stdin. +Claude Code invoca entonces `failproofai --hook PreToolUse` como subproceso antes de cada llamada a una herramienta, pasando un payload JSON por stdin. ### Formato del payload @@ -62,11 +62,11 @@ Claude Code luego invoca `failproofai --hook PreToolUse` como subproceso antes d Para eventos `PostToolUse`, el payload también contiene `tool_result` con la salida de la herramienta. -El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este límite se descartan y todas las políticas permiten implícitamente. +El manejador aplica un límite de 1 MB en stdin. Los payloads que superan este límite se descartan y todas las políticas permiten implícitamente. ### Formato de respuesta -**Deny (PreToolUse):** +**Denegar (PreToolUse):** ```json { "hookSpecificOutput": { @@ -76,7 +76,7 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l } ``` -**Deny (PostToolUse):** +**Denegar (PostToolUse):** ```json { "hookSpecificOutput": { @@ -85,7 +85,7 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l } ``` -**Instruct (cualquier evento excepto Stop):** +**Instruir (cualquier evento excepto Stop):** ```json { "hookSpecificOutput": { @@ -94,17 +94,17 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l } ``` -**Instruct en evento Stop:** +**Instruir en evento Stop:** - Código de salida: `2` - El motivo se escribe en stderr (no en stdout) -**Allow:** +**Permitir:** - Código de salida: `0` - stdout vacío -**Allow con mensaje:** +**Permitir con mensaje:** -`allow(message)` permite que una política envíe contexto informativo de vuelta a Claude incluso cuando la operación está permitida. El manejador de hooks escribe el siguiente JSON en **stdout** (no en un archivo de configuración — esta es la respuesta del manejador a Claude Code, igual que las respuestas deny e instruct anteriores): +`allow(message)` permite que una política envíe contexto informativo de vuelta a Claude incluso cuando la operación está permitida. El manejador de hooks escribe el siguiente JSON en **stdout** (no en un archivo de configuración — esta es la respuesta del manejador a Claude Code, igual que las respuestas de deny e instruct anteriores): ```json // Written to stdout by the hook handler process @@ -115,7 +115,7 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l } ``` - Código de salida: `0` (la operación está permitida) -- Cuando varias políticas devuelven `allow` con mensaje, sus mensajes se unen con saltos de línea en una sola cadena `additionalContext` +- Cuando múltiples políticas devuelven `allow` con un mensaje, sus mensajes se unen con saltos de línea en un único string `additionalContext` - Si ninguna política proporciona un mensaje, stdout está vacío (igual que antes) ### Pipeline de procesamiento @@ -124,28 +124,28 @@ El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este l ```text stdin JSON - → parse payload (max 1 MB) - → extract session metadata (session_id, cwd, tool_name, tool_input, etc.) - → readMergedHooksConfig(cwd) ← merges project + local + global config - → register enabled builtin policies with resolved params - → load custom policies from customPoliciesPath (if set) - → register custom policies into policy registry - → evaluate all policies (builtins first, then custom) - → first deny short-circuits - → instruct decisions accumulate - → allow messages accumulate - → write JSON decision to stdout - → persist event to ~/.failproofai/hook-activity/current.jsonl - → exit + → parsear payload (máx. 1 MB) + → extraer metadatos de sesión (session_id, cwd, tool_name, tool_input, etc.) + → readMergedHooksConfig(cwd) ← fusiona config de proyecto + local + global + → registrar políticas builtin habilitadas con parámetros resueltos + → cargar políticas personalizadas desde customPoliciesPath (si está definido) + → registrar políticas personalizadas en el registro de políticas + → evaluar todas las políticas (builtins primero, luego personalizadas) + → el primer deny cortocircuita la evaluación + → las decisiones instruct se acumulan + → los mensajes allow se acumulan + → escribir decisión JSON en stdout + → persistir evento en ~/.failproofai/hook-activity/current.jsonl + → salir ``` -Todo el proceso se ejecuta en menos de 100ms para payloads típicos sin llamadas a LLM. +Todo el proceso se ejecuta en menos de 100 ms para payloads típicos, sin llamadas a LLM. --- ## Carga de configuración -`src/hooks/hooks-config.ts` implementa la carga de configuración en tres ámbitos. +`src/hooks/hooks-config.ts` implementa la carga de configuración con tres alcances. ```text [1] {cwd}/.failproofai/policies-config.json ← proyecto (mayor prioridad) @@ -153,9 +153,9 @@ Todo el proceso se ejecuta en menos de 100ms para payloads típicos sin llamadas [3] ~/.failproofai/policies-config.json ← global (menor prioridad) ``` -Lógica de combinación: -- `enabledPolicies` - unión deduplicada de los tres archivos -- `policyParams` - por clave de política, gana íntegramente el primer archivo que la defina +Lógica de fusión: +- `enabledPolicies` - unión deduplicada entre los tres archivos +- `policyParams` - por clave de política, gana completamente el primer archivo que la defina - `customPoliciesPath` - gana el primer archivo que lo defina - `llm` - gana el primer archivo que lo defina @@ -169,18 +169,18 @@ El panel de control web usa `readHooksConfig()` (solo global) para lectura y esc Para cada política: -1. Busca el esquema `params` de la política (si tiene uno). -2. Lee `policyParams[policy.name]` de la configuración combinada. -3. Combina los valores proporcionados por el usuario sobre los valores predeterminados del esquema para producir `ctx.params`. -4. Llama a `policy.fn(ctx)` con el contexto resuelto. -5. Si el resultado es `deny`, se detiene inmediatamente y devuelve esa decisión. -6. Si el resultado es `instruct`, acumula el mensaje y continúa. -7. Si el resultado es `allow`, continúa con la siguiente política. +1. Buscar el esquema `params` de la política (si tiene uno). +2. Leer `policyParams[policy.name]` de la configuración fusionada. +3. Fusionar los valores proporcionados por el usuario sobre los valores predeterminados del esquema para producir `ctx.params`. +4. Llamar a `policy.fn(ctx)` con el contexto resuelto. +5. Si el resultado es `deny`, detener inmediatamente y devolver esa decisión. +6. Si el resultado es `instruct`, acumular el mensaje y continuar. +7. Si el resultado es `allow`, continuar con la siguiente política. Después de que todas las políticas se ejecutan: -- Si se devolvió algún `deny`, emite la respuesta deny. -- Si se recopilaron respuestas `instruct`, emite una única respuesta instruct con todos los mensajes unidos. -- De lo contrario, emite una respuesta allow (stdout vacío, salida 0). +- Si se devolvió algún `deny`, emitir la respuesta de deny. +- Si se recopilaron devoluciones `instruct`, emitir una única respuesta instruct con todos los mensajes unidos. +- En caso contrario, emitir una respuesta allow (stdout vacío, salida 0). --- @@ -204,9 +204,9 @@ interface BuiltinPolicyDefinition { } ``` -Las políticas que aceptan `params` declaran un `PolicyParamsSchema` con tipos y valores predeterminados para cada parámetro. El evaluador de políticas inyecta los valores resueltos en `ctx.params` antes de llamar a `fn`. Las funciones de política leen `ctx.params` sin comprobaciones de nulo porque los valores predeterminados siempre se aplican primero. +Las políticas que aceptan `params` declaran un `PolicyParamsSchema` con tipos y valores predeterminados para cada parámetro. El evaluador de políticas inyecta los valores resueltos en `ctx.params` antes de llamar a `fn`. Las funciones de política leen `ctx.params` sin comprobaciones de nulidad porque los valores predeterminados siempre se aplican primero. -La coincidencia de patrones dentro de las políticas usa tokens de comando analizados (argv), no coincidencia de cadenas sin procesar. Esto evita la elusión mediante inyección de operadores de shell (por ejemplo, un patrón para `sudo systemctl status *` no puede eludirse añadiendo `; rm -rf /` al comando). +La coincidencia de patrones dentro de las políticas usa tokens de comando parseados (argv), no coincidencia de cadenas sin procesar. Esto evita la evasión mediante inyección de operadores de shell (por ejemplo, un patrón para `sudo systemctl status *` no puede eludirse añadiendo `; rm -rf /` al comando). --- @@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` carga el archivo de política del usuario: +`src/hooks/custom-hooks-loader.ts` carga el archivo de políticas del usuario: -1. Lee `customPoliciesPath` de la configuración; omite si está ausente. -2. Resuelve a ruta absoluta; verifica que el archivo exista. -3. Reescribe todas las importaciones `from "failproofai"` a la ruta dist real para que `customPolicies` resuelva al mismo registro `globalThis`. -4. Reescribe recursivamente las importaciones locales transitivas para garantizar la compatibilidad con ESM. -5. Escribe archivos `.mjs` temporales e `import()`a el archivo de entrada. -6. Llama a `getCustomHooks()` para recuperar los hooks registrados. -7. Limpia todos los archivos temporales en un bloque `finally`. +1. Leer `customPoliciesPath` de la configuración; omitir si está ausente. +2. Resolver a ruta absoluta; verificar que el archivo existe. +3. Reescribir todas las importaciones `from "failproofai"` a la ruta dist real para que `customPolicies` se resuelva al mismo registro `globalThis`. +4. Reescribir recursivamente las importaciones locales transitivas para garantizar compatibilidad con ESM. +5. Escribir archivos `.mjs` temporales e `import()` el archivo de entrada. +6. Llamar a `getCustomHooks()` para recuperar los hooks registrados. +7. Limpiar todos los archivos temporales en un bloque `finally`. Ante cualquier error (archivo no encontrado, error de sintaxis, fallo de importación), el error se registra en `~/.failproofai/hook.log` y el cargador devuelve un array vacío. Las políticas integradas no se ven afectadas. -Las políticas personalizadas se evalúan después de todas las políticas integradas. Un `deny` de una política personalizada sigue interrumpiendo el procesamiento de las políticas personalizadas restantes (pero todos los integrados ya se habrán ejecutado en ese punto). +Las políticas personalizadas se evalúan después de todas las políticas integradas. Un `deny` de una política personalizada aún cortocircuita las políticas personalizadas posteriores (pero en ese punto todas las integradas ya se han ejecutado). --- ## Registro de actividad -Después de cada evento de hook, el manejador añade una línea JSONL a `~/.failproofai/hook-activity/current.jsonl`, que rota a `page--.jsonl` una vez que alcanza el tamaño de página: +Después de cada evento de hook, el manejador añade una línea JSONL a `~/.failproofai/hook-activity/current.jsonl`, que rota a `page--.jsonl` una vez que alcanza una página: ```json { @@ -258,7 +258,7 @@ Después de cada evento de hook, el manejador añade una línea JSONL a `~/.fail } ``` -Una línea por política que tomó una decisión que no sea allow. Las decisiones allow no se registran (para mantener el archivo pequeño). +Una línea por política que tomó una decisión que no fue allow. Las decisiones allow no se registran (para mantener el archivo pequeño). --- @@ -268,11 +268,11 @@ El panel de control es una aplicación **Next.js 16** que usa el App Router con ```text app/ - layout.tsx ← Diseño raíz (tema, telemetría, navegación) - projects/page.tsx ← Componente servidor: lista todos los proyectos Claude - project/[name]/page.tsx ← Componente servidor: lista sesiones en un proyecto + layout.tsx ← Layout raíz (tema, telemetría, navegación) + projects/page.tsx ← Componente de servidor: lista todos los proyectos Claude + project/[name]/page.tsx ← Componente de servidor: lista sesiones en un proyecto project/[name]/session/ - [sessionId]/page.tsx ← Componente servidor: renderiza el visor de sesión + [sessionId]/page.tsx ← Componente de servidor: renderiza el visor de sesión policies/page.tsx ← Componente cliente: gestión de políticas + registro de actividad actions/ get-hooks-config.ts ← Leer configuración + lista de políticas @@ -286,16 +286,16 @@ app/ **Flujo de datos:** -- Los componentes de página llaman a `lib/projects.ts` y `lib/log-entries.ts` para leer datos de proyectos y sesiones directamente desde el sistema de archivos (sin capa de API para lecturas). +- Los componentes de página llaman a `lib/projects.ts` y `lib/log-entries.ts` para leer datos de proyecto/sesión directamente desde el sistema de archivos (sin capa de API para lecturas). - La página de políticas usa Server Actions para todas las mutaciones (activar/desactivar, actualizar parámetros, instalar/eliminar). -- El visor de sesión analiza el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas. +- El visor de sesiones parsea el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas. **Decisiones de diseño clave:** - Sin base de datos: todo el estado persistente está en archivos planos (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions para mutaciones: no se necesita API REST para operaciones CRUD. -- React Server Components para páginas de lectura: carga inicial más rápida, sin bundle del cliente para obtención de datos. -- Componentes cliente solo donde se necesita interactividad (activación de políticas, búsqueda de actividad, visor de registros). +- Server Actions para mutaciones: no se necesita una API REST para operaciones CRUD. +- React Server Components para páginas de lectura: carga inicial más rápida, sin bundle cliente para la obtención de datos. +- Componentes cliente solo donde se necesita interactividad (toggles de políticas, búsqueda de actividad, visor de registros). --- @@ -311,21 +311,21 @@ failproofai/ │ ├── policy-evaluator.ts # Motor de ejecución de políticas │ ├── policy-registry.ts # Registro y búsqueda de políticas │ ├── policy-types.ts # Interfaces TypeScript -│ ├── hooks-config.ts # Carga de configuración de múltiples ámbitos +│ ├── hooks-config.ts # Carga de configuración multi-alcance │ ├── custom-hooks-registry.ts # Registro de hooks respaldado por globalThis -│ ├── custom-hooks-loader.ts # Cargador ESM para hooks JS del usuario -│ ├── manager.ts # Operaciones de instalación / eliminación / listado +│ ├── custom-hooks-loader.ts # Cargador ESM para hooks JS de usuario +│ ├── manager.ts # Operaciones de instalar / eliminar / listar │ ├── install-prompt.ts # Prompt interactivo de selección de políticas │ ├── hook-logger.ts # Registro en hook.log -│ ├── hook-activity-store.ts # Persistencia de actividad en hook-activity/ +│ ├── hook-activity-store.ts # Persistir actividad en hook-activity/ │ └── llm-client.ts # Cliente de API LLM (para políticas con IA) ├── app/ # Panel de control Next.js (páginas + server actions) ├── lib/ # Utilidades compartidas │ ├── projects.ts # Enumerar proyectos Claude desde el sistema de archivos -│ ├── log-entries.ts # Analizar el formato JSONL de transcripciones Claude +│ ├── log-entries.ts # Parsear formato JSONL de transcripción Claude │ ├── paths.ts # Resolver rutas del sistema │ └── ... -├── components/ # Componentes React de UI compartidos +├── components/ # Componentes de interfaz React compartidos ├── contexts/ # Proveedores de contexto React (tema, auto-refresco, telemetría) ├── examples/ # Archivos de hooks personalizados de ejemplo └── __tests__/ # Pruebas unitarias y E2E diff --git a/docs/es/built-in-policies.mdx b/docs/es/built-in-policies.mdx index 826a734d..2e8d284f 100644 --- a/docs/es/built-in-policies.mdx +++ b/docs/es/built-in-policies.mdx @@ -1,16 +1,16 @@ --- -title: Políticas Integradas +title: Políticas integradas description: "Las 39 políticas integradas que detectan los modos de fallo más comunes de los agentes" icon: shield --- -failproofai incluye 39 políticas integradas que detectan los modos de fallo más comunes de los agentes. Cada política se activa en un tipo de evento de hook específico y un nombre de herramienta determinado. Diecinueve políticas aceptan parámetros que permiten ajustar su comportamiento sin necesidad de escribir código. Cinco políticas de flujo de trabajo imponen una secuencia commit → push → PR → CI antes de que Claude se detenga. +failproofai incluye 39 políticas integradas que detectan los modos de fallo más comunes de los agentes. Cada política se activa en un tipo de evento hook específico y para un nombre de herramienta determinado. Diecinueve políticas aceptan parámetros que permiten ajustar su comportamiento sin necesidad de escribir código. Cinco políticas de flujo de trabajo imponen un pipeline de commit → push → PR → CI antes de que Claude se detenga. --- ## Descripción general -Las políticas están agrupadas por categorías: +Las políticas están agrupadas en categorías: | Categoría | Políticas | Tipo de hook | |----------|----------|-----------| @@ -26,14 +26,14 @@ Las políticas están agrupadas por categorías: | [Flujo de trabajo](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | - **`block-`** — impide que el agente continúe. -- **`warn-`** — proporciona contexto adicional al agente para que pueda corregirse. +- **`warn-`** — proporciona al agente contexto adicional para que pueda corregirse a sí mismo. - **`sanitize-`** — elimina datos sensibles de la salida de la herramienta antes de que el agente la vea. ### Espacios de nombres -Cada política ocupa un espacio `/`. Las políticas integradas pertenecen al espacio de nombres **`failproofai/`** — por ejemplo, `failproofai/sanitize-jwt`. El espacio de nombres evita colisiones cuando también se cargan políticas personalizadas o de terceros con nombres cortos similares. +Cada política reside en un slot `/`. Las políticas integradas pertenecen al espacio de nombres **`failproofai/`** — por ejemplo, `failproofai/sanitize-jwt`. El espacio de nombres evita colisiones cuando también se cargan políticas personalizadas o de terceros con nombres cortos similares. -En tu configuración puedes hacer referencia a una política integrada tanto por su nombre corto como por su nombre completo; ambas formas se resuelven a la misma política: +En tu configuración puedes referirte a una política integrada por su nombre corto o por su nombre calificado; ambas formas apuntan a la misma política: ```json { @@ -44,39 +44,39 @@ En tu configuración puedes hacer referencia a una política integrada tanto por } ``` -Si un nombre no contiene `/`, failproofai lo trata como perteneciente al espacio de nombres predeterminado `failproofai`. Los nombres que ya contienen `/` (p. ej. `myorg/foo`, `custom/my-hook`) se mantienen tal cual. +Si un nombre no contiene `/`, failproofai lo trata como perteneciente al espacio de nombres por defecto `failproofai`. Los nombres que ya contienen un `/` (p. ej. `myorg/foo`, `custom/my-hook`) se mantienen tal cual. - **`require-`** — bloquea el evento Stop hasta que se cumplan las condiciones. --- -Toda política admite un campo opcional `hint` en `policyParams`. El hint se añade al mensaje de deny o instruct que ve Claude, proporcionando orientación accionable sin modificar el código de la política. Funciona con políticas integradas, personalizadas y de convención. Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles. +Todas las políticas admiten un campo opcional `hint` en `policyParams`. El hint se añade al mensaje de deny o instruct que ve Claude, proporcionando orientación accionable sin modificar el código de la política. Funciona con políticas integradas, personalizadas y de convención. Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles. --- ## Comandos peligrosos -Evita que los agentes ejecuten operaciones difíciles de deshacer o que podrían dañar el sistema anfitrión. +Evita que los agentes ejecuten operaciones difíciles de revertir o que puedan dañar el sistema anfitrión. ### `block-sudo` **Evento:** PreToolUse (Bash) **Por defecto:** Deniega cualquier comando `sudo` o `doas`. -Bloquea un comando que ejecuta un binario de elevación de privilegios **en posición de comando**. La coincidencia es estructural, no textual: el comando se divide en segmentos tal como lo haría un shell, se eliminan las asignaciones de prefijo (`FOO=bar`), las redirecciones y los ejecutores con sus flags (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …), y el binario resultante se compara por **nombre base**. Así, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` y `bash -c "sudo …"` son todos denegados, y `doas` se trata como la misma capacidad bajo un nombre distinto. +Bloquea un comando que ejecuta un binario de elevación de privilegios **en posición de comando**. La coincidencia es estructural, no textual: el comando se divide en segmentos tal como lo haría un shell; se descartan las asignaciones de prefijo (`FOO=bar`), las redirecciones y los ejecutores con sus flags (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …), y el binario resultante se compara por **nombre base**. Así, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` y `bash -c "sudo …"` son todos denegados, y `doas` recibe el mismo tratamiento que `sudo` bajo un nombre diferente. -Al anclar en la posición del comando en lugar de en la aparición de la palabra en cualquier parte, **no** se activa en comandos que simplemente la mencionan: `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, o una alternancia de `grep` que contiene la palabra se ejecutan normalmente. +Dado que el anclaje es en la posición del comando y no en la aparición de la palabra en cualquier lugar, **no** se activa con comandos que simplemente lo mencionan — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"` o una alternancia de `grep` que contenga la palabra se ejecutan con normalidad. -Esto detiene el intento obvio; no cierra la clase completa. Un agente capaz de ejecutar shell arbitrario puede seguir alcanzando la elevación de forma indirecta — mediante una variable (`S=sudo; $S …`), una tubería decodificada en base64, o un script envolvente en disco — porque ninguna inspección de una sola cadena de comandos puede seguir esas vías. Trátalo como una barrera contra errores y escalada casual, no como un límite de seguridad frente a un agente con intenciones deliberadas. Una barrera real debe aplicarse por debajo del shell. +Esto detiene el intento obvio, pero no cierra toda la clase. Un agente que puede ejecutar shell arbitrario aún puede alcanzar la elevación de forma indirecta — mediante una variable (`S=sudo; $S …`), una tubería con base64 decodificado o un script wrapper en disco — porque ninguna inspección de una sola cadena de comandos puede seguir esos caminos. Trátalo como una barrera contra errores y escaladas casuales, no como un límite de seguridad frente a un agente determinado. Un límite real debe aplicarse por debajo del shell. **Parámetros:** | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos exactos que están permitidos. Cada entrada se compara con los tokens argv analizados. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comando exactos que están permitidos. Cada entrada se compara con los tokens argv analizados. | **Ejemplo:** @@ -93,7 +93,7 @@ Esto detiene el intento obvio; no cierra la clase completa. Un agente capaz de e Con esta configuración, `sudo systemctl status nginx` está permitido, pero `sudo rm /etc/hosts` es denegado. -Los patrones se comparan con los tokens analizados, no con la cadena de comandos sin procesar. Esto evita la evasión mediante operadores de shell añadidos (p. ej. `sudo systemctl status x; rm -rf /` no coincide con `sudo systemctl status *`). +Los patrones se comparan con los tokens analizados, no con la cadena de comandos en bruto. Esto evita eludirlo mediante operadores de shell añadidos (p. ej. `sudo systemctl status x; rm -rf /` no coincide con `sudo systemctl status *`). --- @@ -107,7 +107,7 @@ Los patrones se comparan con los tokens analizados, no con la cadena de comandos | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Rutas donde es seguro realizar una eliminación recursiva (p. ej. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Rutas que son seguras para eliminar de forma recursiva (p. ej. `/tmp`). | **Ejemplo:** @@ -135,7 +135,7 @@ Sin parámetros. ### `block-failproofai-commands` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega comandos que desinstalarían o deshabilitarían failproofai (p. ej. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Por defecto:** Deniega comandos que desinstalarían o desactivarían failproofai (p. ej. `npm uninstall failproofai`, `failproofai policies --uninstall`). Sin parámetros. @@ -146,9 +146,9 @@ Sin parámetros. **Evento:** PreToolUse (Bash) **Por defecto:** Deniega `failproofai config --pause`, que suspende la aplicación de políticas durante una sesión. Pausar es una decisión humana — un agente capaz de ejecutarlo podría desactivar todas las demás políticas con un solo comando. -Es intencionalmente más específico que [`block-failproofai-commands`](#block-failproofai-commands) y no está cubierto por él: esa política ancla en el límite de un comando, por lo que `npx -y failproofai config --pause` no la activa; y al ser más amplia, a menudo se desactiva para que los agentes puedan ejecutar `failproofai audit`. `--resume` y `--status` están permitidos — ninguno elimina la aplicación de políticas. +Es intencionalmente más específico que [`block-failproofai-commands`](#block-failproofai-commands) y no está cubierto por él: esa política ancla en un límite de comando, por lo que `npx -y failproofai config --pause` no coincide con ella, y al ser amplia suele desactivarse para que los agentes puedan ejecutar `failproofai audit`. `--resume` y `--status` están permitidos — ninguno elimina la aplicación de políticas. -Esto detiene el intento directo, no la clase completa: un agente aún puede alcanzar el mismo estado mediante un alias o un script envolvente. Cerrar completamente esa vía requiere que la pausa sea inaccesible desde una llamada de herramienta. +Detiene el intento directo, no toda la clase: un agente aún puede alcanzar el mismo estado mediante un alias o un script wrapper. Cerrar esto completamente requiere que la pausa sea inalcanzable desde una llamada a herramienta. Sin parámetros. @@ -156,9 +156,9 @@ Sin parámetros. ## Comandos de infraestructura -Evita que los agentes de codificación ejecuten CLIs de infraestructura o activen pipelines de CI/CD. Todas las políticas de esta categoría son **opt-in** (`defaultEnabled: false`) — los agentes que legítimamente necesiten llamar a `kubectl`, `terraform`, etc. no se verán afectados a menos que habilites la política. Una vez habilitada, toda invocación del CLI correspondiente es denegada salvo que el comando coincida con una entrada en `allowPatterns`. +Evita que los agentes de codificación ejecuten CLIs de infraestructura o activen pipelines de CI/CD. Todas las políticas de esta categoría son de **opt-in** (`defaultEnabled: false`) — los agentes que legítimamente necesiten llamar a `kubectl`, `terraform`, etc. no se verán afectados a menos que habilites la política. Una vez habilitada, cada invocación del CLI correspondiente es denegada a menos que el comando coincida con una entrada en `allowPatterns`. -La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los tokens se comparan con los argv analizados, `*` actúa como comodín para un token, y cualquier comando que contenga un operador de shell independiente (`&&`, `||`, `|`, `;`) o un token con metacaracteres de shell embebidos es rechazado antes de la comprobación de la lista de permitidos, para evitar inyecciones. +La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los tokens se comparan con el argv analizado, `*` es un comodín para un token, y cualquier comando que contenga un operador de shell independiente (`&&`, `||`, `|`, `;`) o un token con metacaracteres de shell embebidos es rechazado antes de la comprobación de la lista de permitidos para evitar bypasses por inyección. ### `block-kubectl` @@ -169,7 +169,7 @@ La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los to | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos kubectl que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comando kubectl que están permitidos. | **Ejemplo:** @@ -196,7 +196,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos terraform/tofu que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comando terraform/tofu que están permitidos. | **Ejemplo:** @@ -221,7 +221,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos del CLI aws que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comando del CLI aws que están permitidos. | **Ejemplo:** @@ -246,7 +246,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos gcloud que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comando gcloud que están permitidos. | **Ejemplo:** @@ -271,7 +271,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos del CLI az que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comando del CLI az que están permitidos. | **Ejemplo:** @@ -296,7 +296,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos helm que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comando helm que están permitidos. | **Ejemplo:** @@ -324,13 +324,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply - `gh cache delete` - `gh secret set`, `gh secret delete` -Los subcomandos de `gh` de solo lectura como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` y `gh api repos/.../...` **no** son detectados por esta política — se necesitan habitualmente para comprobaciones de flujo de trabajo (incluida la propia `require-ci-green-before-stop` de failproofai). +Los subcomandos `gh` de solo lectura como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` y `gh api repos/.../...` **no** son capturados por esta política — se necesitan habitualmente para comprobaciones de flujo de trabajo (incluida la propia `require-ci-green-before-stop` de failproofai). **Parámetros:** | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocaciones específicas que se permiten aunque de otro modo serían denegadas. | +| `allowPatterns` | `string[]` | `[]` | Invocaciones específicas mediante script que se permiten aunque de otro modo serían denegadas. | **Ejemplo:** @@ -348,7 +348,7 @@ Los subcomandos de `gh` de solo lectura como `gh pr view`, `gh pr list`, `gh run ## Secretos (sanitizadores) -Evita que los agentes filtren credenciales en su contexto o salida. Las políticas de sanitización se activan en eventos **PostToolUse**. Cuando Claude ejecuta un comando Bash, lee un archivo o llama a cualquier herramienta, estas políticas inspeccionan la salida antes de que se devuelva a Claude. Si se detecta un patrón de secreto, la política devuelve una decisión de deny que impide que la salida sea devuelta. +Evita que los agentes filtren credenciales en su contexto o salida. Las políticas de sanitización se activan en eventos **PostToolUse**. Cuando Claude ejecuta un comando Bash, lee un archivo o llama a cualquier herramienta, estas políticas inspeccionan la salida antes de que sea devuelta a Claude. Si se detecta un patrón de secreto, la política devuelve una decisión de deny que impide que la salida sea enviada de vuelta. ### `sanitize-jwt` @@ -362,7 +362,7 @@ Sin parámetros. ### `sanitize-api-keys` **Evento:** PostToolUse (todas las herramientas) -**Por defecto:** Redacta formatos comunes de claves de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), PATs de GitHub (`ghp_`), claves de acceso AWS (`AKIA`), claves Stripe (`sk_live_`, `sk_test_`) y claves de API de Google (`AIza`). +**Por defecto:** Redacta formatos comunes de claves API: Anthropic (`sk-ant-`), OpenAI (`sk-`), PATs de GitHub (`ghp_`), claves de acceso AWS (`AKIA`), claves Stripe (`sk_live_`, `sk_test_`) y claves de Google API (`AIza`). **Parámetros:** @@ -390,7 +390,7 @@ Sin parámetros. ### `sanitize-connection-strings` **Evento:** PostToolUse (todas las herramientas) -**Por defecto:** Redacta cadenas de conexión a bases de datos que contengan credenciales embebidas (p. ej. `postgresql://user:password@host/db`). +**Por defecto:** Redacta cadenas de conexión a bases de datos que contienen credenciales embebidas (p. ej. `postgresql://user:password@host/db`). Sin parámetros. @@ -416,14 +416,14 @@ Sin parámetros. ## Entorno -Protege la configuración de entorno sensible para que los agentes no puedan leerla ni exponerla. +Protege la configuración sensible del entorno para que los agentes no puedan leerla ni exponerla. ### `block-env-files` **Evento:** PreToolUse (Bash, Read) **Por defecto:** Deniega la lectura de archivos `.env` mediante `cat .env`, llamadas a la herramienta `Read` con `.env` como ruta de archivo, etc. -No bloquea `.envrc` ni otros archivos relacionados con el entorno: solo archivos con el nombre exacto `.env`. +No bloquea `.envrc` ni otros archivos relacionados con el entorno — solo archivos cuyo nombre sea exactamente `.env`. Sin parámetros. @@ -440,18 +440,18 @@ Sin parámetros. ## Acceso a archivos -Mantén a los agentes trabajando dentro de los límites del proyecto y alejados de archivos sensibles. +Mantiene a los agentes trabajando dentro de los límites del proyecto y alejados de archivos sensibles. ### `block-read-outside-cwd` **Evento:** PreToolUse (Read, Bash) -**Por defecto:** Deniega la lectura de archivos fuera de la raíz del proyecto. El límite es `CLAUDE_PROJECT_DIR` (establecido una vez por sesión por Claude Code), con un fallback al directorio de trabajo actual de la sesión cuando esa variable no está definida. Al usar la raíz del proyecto en lugar del `cwd` activo, el límite se mantiene estable incluso cuando Claude hace `cd` a un subdirectorio. +**Por defecto:** Deniega la lectura de archivos fuera de la raíz del proyecto. El límite es `CLAUDE_PROJECT_DIR` (establecido una vez por sesión por Claude Code), con un fallback al directorio de trabajo actual de la sesión cuando esa variable no está definida. Usar la raíz del proyecto en lugar del `cwd` activo significa que el límite se mantiene estable incluso después de que Claude ejecute un `cd` a un subdirectorio. **Parámetros:** | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Prefijos de rutas absolutas que están permitidos aunque estén fuera de la raíz del proyecto. | +| `allowPaths` | `string[]` | `[]` | Prefijos de ruta absoluta que están permitidos aunque estén fuera de la raíz del proyecto. | **Ejemplo:** @@ -476,7 +476,7 @@ Mantén a los agentes trabajando dentro de los límites del proyecto y alejados | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Patrones de nombre de archivo adicionales (estilo glob) que se bloquean. | +| `additionalPatterns` | `string[]` | `[]` | Patrones de nombre de archivo adicionales (estilo glob) a bloquear. | **Ejemplo:** @@ -494,7 +494,7 @@ Mantén a los agentes trabajando dentro de los límites del proyecto y alejados ## Git -Evita pushes accidentales, force-pushes y errores de rama difíciles de deshacer. +Previene pushes accidentales, force-pushes y errores de rama que son difíciles de revertir. ### `block-push-master` @@ -505,7 +505,7 @@ Evita pushes accidentales, force-pushes y errores de rama difíciles de deshacer | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de ramas a las que no se puede hacer push directamente. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de rama a las que no se puede hacer push directamente. | **Ejemplo:** @@ -520,7 +520,7 @@ Evita pushes accidentales, force-pushes y errores de rama difíciles de deshacer ``` -Para permitir el push a todas las ramas (desactivando efectivamente esta política sin eliminarla de `enabledPolicies`), establece `protectedBranches: []`. +Para permitir push a todas las ramas (desactivando efectivamente esta política sin eliminarla de `enabledPolicies`), establece `protectedBranches: []`. --- @@ -528,13 +528,13 @@ Para permitir el push a todas las ramas (desactivando efectivamente esta políti ### `block-work-on-main` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega `git commit`, `git merge`, `git rebase` y `git cherry-pick` cuando el árbol de trabajo está en `main` o `master`. La creación y el cambio de ramas (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) no se ven afectados. +**Por defecto:** Deniega `git commit`, `git merge`, `git rebase` y `git cherry-pick` mientras el árbol de trabajo está en `main` o `master`. La creación y el cambio de rama (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) no se ven afectados. **Parámetros:** | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de ramas en las que se deniega commit/merge/rebase/cherry-pick. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de rama en las que se deniega commit/merge/rebase/cherry-pick. | --- @@ -543,7 +543,7 @@ Para permitir el push a todas las ramas (desactivando efectivamente esta políti **Evento:** PreToolUse (Bash) **Por defecto:** Deniega `git push --force` y `git push -f`. -Sin parámetros específicos de la política. Usa el campo transversal [`hint`](/es/configuration#hint-cross-cutting) para sugerir alternativas: +Sin parámetros específicos de política. Usa el [`hint`](/es/configuration#hint-cross-cutting) transversal para sugerir alternativas: ```json { @@ -578,7 +578,7 @@ Sin parámetros. ### `warn-all-files-staged` **Evento:** PreToolUse (Bash) -**Por defecto:** Instruye a Claude para que revise lo que está preparando cuando ejecuta `git add -A` o `git add .`. No bloquea el comando. +**Por defecto:** Instruye a Claude para que revise qué está incluyendo en el stage al ejecutar `git add -A` o `git add .`. No bloquea el comando. Sin parámetros. @@ -591,7 +591,7 @@ Detecta operaciones SQL destructivas antes de que se ejecuten contra tu base de ### `warn-destructive-sql` **Evento:** PreToolUse (Bash) -**Por defecto:** Instruye a Claude para que confirme antes de ejecutar SQL que contenga `DROP TABLE`, `DROP DATABASE`, o `DELETE` sin una cláusula `WHERE`. +**Por defecto:** Instruye a Claude para que confirme antes de ejecutar SQL que contenga `DROP TABLE`, `DROP DATABASE` o `DELETE` sin una cláusula `WHERE`. Sin parámetros. @@ -608,7 +608,7 @@ Sin parámetros. ## Advertencias -Proporciona contexto adicional a los agentes antes de operaciones potencialmente arriesgadas pero no destructivas. +Proporciona a los agentes contexto adicional antes de operaciones potencialmente arriesgadas pero no destructivas. ### `warn-large-file-write` @@ -634,7 +634,7 @@ Proporciona contexto adicional a los agentes antes de operaciones potencialmente ``` -El manejador de hooks impone un límite de 1 MB en stdin para los payloads. Para probar esta política con contenido pequeño, establece `thresholdKb` a un valor bastante inferior a 1024. +El manejador del hook aplica un límite de 1 MB en stdin para los payloads. Para probar esta política con contenido pequeño, establece `thresholdKb` a un valor muy por debajo de 1024. --- @@ -651,7 +651,7 @@ Sin parámetros. ### `warn-background-process` **Evento:** PreToolUse (Bash) -**Por defecto:** Instruye a Claude para que sea cuidadoso al lanzar procesos en segundo plano mediante `nohup`, `&`, `disown` o `screen`. +**Por defecto:** Instruye a Claude para que tenga cuidado al lanzar procesos en segundo plano mediante `nohup`, `&`, `disown` o `screen`. Sin parámetros. @@ -668,23 +668,23 @@ Sin parámetros. ## Gestores de paquetes -Define qué gestores de paquetes puede usar el agente. +Impone qué gestores de paquetes puede usar el agente. ### `prefer-package-manager` **Evento:** PreToolUse (Bash) -**Por defecto:** Deshabilitado. Cuando se habilita, bloquea cualquier comando de gestor de paquetes que no esté en la lista `allowed` e indica a Claude que reescriba el comando usando un gestor permitido. +**Por defecto:** Desactivado. Cuando está habilitado, bloquea cualquier comando de gestor de paquetes que no esté en la lista `allowed` e indica a Claude que reescriba el comando usando un gestor permitido. Detecta: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parámetro | Tipo | Por defecto | Descripción | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Nombres de gestores de paquetes permitidos. Cualquier gestor detectado que no esté en esta lista es bloqueado. Si está vacío, la política no tiene efecto. | +| `allowed` | string[] | `[]` | Nombres de gestores de paquetes permitidos. Cualquier gestor detectado que no esté en esta lista es bloqueado. Cuando está vacío, la política no hace nada. | | `blocked` | string[] | `[]` | Nombres de gestores adicionales a bloquear más allá de la lista integrada (p. ej. `['pdm', 'pipx']`). | La lista de bloqueo integrada incluye: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` para añadir gestores que no estén en esta lista. -**Ejemplo de configuración:** +**Configuración de ejemplo:** ```json { @@ -698,18 +698,18 @@ La lista de bloqueo integrada incluye: pip, pip3, npm, npx, yarn, pnpm, pnpx, bu } ``` -Con esta configuración, `pip install flask` y `pdm install flask` son denegados con un mensaje que indica a Claude que use `uv` o `bun` en su lugar. Comandos como `uv pip install flask` están permitidos porque `uv` está en la lista de permitidos y se comprueba primero. +Con esta configuración, tanto `pip install flask` como `pdm install flask` son denegados con un mensaje que indica a Claude que use `uv` o `bun` en su lugar. Comandos como `uv pip install flask` están permitidos porque `uv` está en la lista de permitidos y se comprueba primero. --- -## Comportamiento de IA +## Comportamiento de la IA -Detecta cuando los agentes se quedan atascados o se comportan de forma inesperada. +Detecta cuándo los agentes se quedan atascados o se comportan de forma inesperada. ### `warn-repeated-tool-calls` **Evento:** PreToolUse (todas las herramientas) -**Por defecto:** Instruye a Claude para que reconsidere cuando se llama a la misma herramienta 3 o más veces con parámetros idénticos — una señal habitual de que el agente está atrapado en un bucle. +**Por defecto:** Instruye a Claude para que reconsidere cuando la misma herramienta es llamada 3 o más veces con parámetros idénticos — una señal frecuente de que el agente está atrapado en un bucle. Sin parámetros. @@ -717,39 +717,39 @@ Sin parámetros. ## Flujo de trabajo -Impone un flujo de trabajo disciplinado al final de la sesión. Estas políticas se activan en el evento **Stop** y deniegan al agente la posibilidad de detenerse hasta que se cumpla cada condición. Siguen una cadena de dependencias natural: commit → push → PR → CI. Si una política deniega, las políticas posteriores de la cadena se omiten (la denegación provoca un cortocircuito). +Impone un flujo de trabajo disciplinado al final de la sesión. Estas políticas se activan en el evento **Stop** y bloquean al agente para que no se detenga hasta que cada condición se cumpla. Siguen una cadena de dependencias natural: commit → push → PR → CI. Si una política deniega, las políticas posteriores de la cadena se omiten (la denegación hace cortocircuito). -Todas las políticas de flujo de trabajo son **fail-open**: si la herramienta requerida no está disponible (p. ej. `gh` no instalado, sin remote de git), la política permite con un mensaje informativo explicando por qué se omitió la comprobación. +Todas las políticas de flujo de trabajo son **fail-open**: si la herramienta requerida no está disponible (p. ej. `gh` no instalado, sin remote de git), la política permite con un mensaje informativo que explica por qué se omitió la comprobación. ### Semántica de Stop por CLI -La aplicación de Stop se ve ligeramente diferente según cada uno de los seis CLIs compatibles, ya que cada uno expone un contrato de hook de «agente finalizado» distinto. El **resultado** es el mismo — el agente no puede detenerse mientras una compuerta de flujo de trabajo esté fallando — pero los **mecanismos** difieren. La tabla siguiente lo resume; solo Pi tiene una particularidad visible para el usuario que conviene entender antes de habilitar una política `require-*-before-stop`. +La aplicación de Stop tiene un aspecto ligeramente diferente en los seis CLIs compatibles porque cada uno expone un contrato de hook de "agente finalizado" distinto. El **resultado** es el mismo — el agente no puede detenerse mientras un gate de flujo de trabajo está fallando — pero la **mecánica** difiere. La tabla siguiente lo resume; solo Pi tiene una peculiaridad visible para el usuario que merece entenderse antes de habilitar una política `require-*-before-stop`. -| CLI | Cuándo se activa la compuerta | Qué ves | +| CLI | Cuándo se activa el gate | Qué ves | |---|---|---| -| Claude Code | En el mismo bucle del agente, inmediatamente | Claude continúa trabajando — resuelve el problema y vuelve a intentar finalizar. Sin interrupción visible para ti. | -| Codex | En el mismo bucle del agente, inmediatamente | Igual que Claude. | -| GitHub Copilot CLI | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa el canal de reintento `{decision:"block", reason}` de Copilot — verificado empíricamente contra Copilot CLI 1.0.41). | -| Cursor Agent | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa el canal `{followup_message}` de Cursor — limitado a `loop_limit`, por defecto 5 reintentos). | -| OpenCode | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa la llamada SDK `client.session.prompt(...)` de OpenCode enrutada a través de `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Siguiente turno del usuario** | **Pi se detiene visiblemente** cuando se activa la compuerta — su bucle de agente termina y se te devuelve al prompt. La compuerta se activa la próxima vez que envíes un prompt: failproofai antepone una directiva `MANDATORY ACTION REQUIRED` al prompt de sistema de ese turno, instruyendo al LLM para que complete el paso del flujo de trabajo (commit, push, etc.) antes de hacer lo que pediste. | +| Claude Code | En el mismo bucle del agente, de inmediato | Claude continúa trabajando — resuelve el problema y luego intenta terminar de nuevo. Sin interrupción visible para ti. | +| Codex | En el mismo bucle del agente, de inmediato | Igual que Claude. | +| GitHub Copilot CLI | En el mismo bucle del agente, de inmediato | Igual que Claude (usa el canal de reintento `{decision:"block", reason}` de Copilot — verificado empíricamente contra Copilot CLI 1.0.41). | +| Cursor Agent | En el mismo bucle del agente, de inmediato | Igual que Claude (usa el canal `{followup_message}` de Cursor — limitado a `loop_limit`, por defecto 5 reintentos). | +| OpenCode | En el mismo bucle del agente, de inmediato | Igual que Claude (usa la llamada SDK `client.session.prompt(...)` de OpenCode enrutada a través de `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **En el siguiente turno del usuario** | **Pi se detiene visiblemente** cuando se activa el gate — su bucle de agente finaliza y se te devuelve al prompt. El gate se activa la próxima vez que envíes un prompt: failproofai antepone una directiva `MANDATORY ACTION REQUIRED` al prompt del sistema de ese turno, instruyendo al LLM para que complete el paso del flujo de trabajo (commit, push, etc.) antes de hacer lo que pediste. | -**Limitación de Pi.** El `AgentEndEvent` de Pi (el equivalente upstream al hook `Stop` de Claude) no tiene tipo Result — cuando se activa, el bucle del agente de Pi ya ha terminado. Pi no puede ser forzado a reintentar el mismo bucle como Claude / Copilot / Cursor / OpenCode. failproofai traslada la compuerta al evento `before_agent_start` de Pi (que se activa tras el siguiente prompt del usuario) para que la comprobación del flujo de trabajo siga aplicándose, aunque en el turno siguiente en lugar del actual. +**Limitación de Pi.** El `AgentEndEvent` de Pi (el equivalente upstream del hook `Stop` de Claude) no tiene tipo Result — en el momento en que se activa, el bucle del agente de Pi ya ha finalizado. Pi no puede ser forzado a reintentar el mismo bucle como Claude / Copilot / Cursor / OpenCode. failproofai traslada el gate al evento `before_agent_start` de Pi (que se activa tras el siguiente prompt del usuario) para que la comprobación del flujo de trabajo siga aplicándose, aunque en el siguiente turno en lugar del actual. **Lo que esto significa en la práctica:** -- Cuando Pi se detiene, la razón de denegación se captura en memoria, indexada por el ID de sesión de Pi. El siguiente prompt que envíes en el mismo proceso de Pi la consume: el LLM ve la directiva `MANDATORY ACTION REQUIRED` al comienzo de su prompt de sistema, realiza el commit (o push / abre el PR / espera a CI) y solo entonces continúa con tu solicitud. La razón capturada es de un solo uso — una vez consumida, la compuerta queda libre. -- La compuerta está limitada por la vida útil del proceso de Pi. Si haces `Ctrl+C` en Pi o sales entre turnos, la entrada en memoria se descarta junto con el proceso y la compuerta se pierde. Claude, Copilot, Cursor y OpenCode tienen el mismo límite (matar el agente hace que se pierda la compuerta) — Pi simplemente lo hace más visible porque el agente termina visiblemente antes de que se active la compuerta. -- Una denegación pendiente también se borra en `session_shutdown` por cualquier razón (`new` / `resume` / `fork` / `quit`), por lo que una compuerta obsoleta de una sesión anterior no puede filtrarse en una sesión nueva iniciada en el mismo proceso de Pi. +- Después de que Pi se detenga, el motivo de denegación se captura en memoria con clave por el id de sesión de Pi. El siguiente prompt que envíes en el mismo proceso de Pi lo consume: el LLM ve la directiva `MANDATORY ACTION REQUIRED` al inicio de su prompt del sistema, hace el commit (o push / abre el PR / espera a que CI pase), y solo entonces continúa con tu solicitud. El motivo de denegación capturado es de un solo uso — una vez consumido, el gate queda despejado. +- El gate está delimitado por el tiempo de vida del proceso de Pi. Si haces `Ctrl+C` en Pi o cierras entre turnos, la entrada en memoria se descarta junto con el proceso y el gate se pierde. Claude, Copilot, Cursor y OpenCode tienen el mismo límite (matar el agente hace que se pierda el gate) — Pi simplemente lo hace más visible porque el agente sale visiblemente antes de que se active el gate. +- Una denegación pendiente también se borra en `session_shutdown` por cualquier motivo (`new` / `resume` / `fork` / `quit`), por lo que un gate obsoleto de una sesión anterior no puede filtrarse a una nueva sesión iniciada en el mismo proceso de Pi. -Si necesitas el comportamiento de reintento en el mismo bucle al estilo Claude, ejecuta tus políticas `Stop` bajo cualquiera de los otros cinco CLIs compatibles. Estamos siguiendo el upstream de Pi para un futuro tipo Result en `AgentEndEvent` que nos permitiría cerrar esta brecha. +Si necesitas el reintento en el mismo bucle al estilo de Claude, ejecuta tus políticas `Stop` bajo cualquiera de los otros cinco CLIs compatibles. Estamos siguiendo Pi upstream en busca de un futuro tipo Result en `AgentEndEvent` que nos permita cerrar esta brecha. ### `require-commit-before-stop` **Evento:** Stop -**Por defecto:** Deniega la detención cuando hay cambios sin confirmar (archivos modificados, preparados o sin seguimiento). Devuelve un mensaje informativo cuando el directorio de trabajo está limpio. +**Por defecto:** Deniega la detención cuando hay cambios sin confirmar (archivos modificados, en stage o sin seguimiento). Devuelve un mensaje informativo cuando el directorio de trabajo está limpio. Sin parámetros. @@ -758,7 +758,7 @@ Sin parámetros. ### `require-push-before-stop` **Evento:** Stop -**Por defecto:** Deniega la detención cuando hay commits sin publicar o cuando la rama actual no tiene una rama de seguimiento remota. Sugiere `git push -u` para crear una rama de seguimiento si es necesario. Fail-open si no hay ningún remote configurado. +**Por defecto:** Deniega la detención cuando hay commits sin hacer push o cuando la rama actual no tiene una rama de seguimiento remota. Sugiere `git push -u` para crear una rama de seguimiento si es necesario. Falla de forma abierta si no hay ningún remote configurado. **Parámetros:** @@ -783,14 +783,13 @@ Sin parámetros. ### `require-pr-before-stop` **Evento:** Stop -**Por defecto:** Deniega la detención cuando no existe ningún pull request para la rama actual, o cuando el PR existente está cerrado sin fusionar. Instruye a Claude para que cree un PR con `gh pr create`. Cuando el PR está **fusionado**, la política permite (el trabajo ha sido publicado) y el mensaje sugiere cambiar de rama (`git checkout main && git pull`). +**Por defecto:** Deniega la detención cuando no existe ninguna pull request para la rama actual, o cuando la PR existente está cerrada sin haberse fusionado. Instruye a Claude para que cree una PR con `gh pr create`. Cuando la PR está **fusionada**, la política permite (el trabajo se ha publicado) y el mensaje sugiere cambiar de rama (`git checkout main && git pull`). Sin parámetros. -Esta política requiere que [GitHub CLI](https://cli.github.com/) (`gh`) esté instalado y autenticado. -Ejecuta `gh auth login` con un token de acceso personal que tenga el ámbito `repo` para acceso de lectura a -pull requests. Si `gh` no está instalado o no está autenticado, la política aplica fail-open e informa a Claude del motivo. +Esta política requiere tener instalado y autenticado el [GitHub CLI](https://cli.github.com/) (`gh`). +Ejecuta `gh auth login` con un token de acceso personal que tenga el scope `repo` para acceso de lectura a pull requests. Si `gh` no está instalado o no está autenticado, la política falla de forma abierta e informa del motivo a Claude. --- @@ -798,24 +797,21 @@ pull requests. Si `gh` no está instalado o no está autenticado, la política a ### `require-no-conflicts-before-stop` **Evento:** Stop -**Por defecto:** Deniega la detención cuando la rama actual no puede fusionarse limpiamente en la rama base. La política primero confirma que existe un PR `OPEN` en GitHub para la rama — sin él, no hay destino de fusión que aplicar, por lo que toda la política aplica cortocircuito hacia allow. Una vez confirmado un PR `OPEN`, se ejecutan dos sondeos independientes: +**Por defecto:** Deniega la detención cuando la rama actual no puede fusionarse limpiamente en la rama base. La política primero confirma que existe una PR en estado `OPEN` en GitHub para la rama — sin ella, no hay objetivo de fusión que imponer, por lo que toda la política hace cortocircuito hacia allow. Una vez confirmada una PR en estado `OPEN`, se ejecutan dos sondas independientes: 1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. En caso de conflicto, el mensaje de denegación nombra los archivos en conflicto para que Claude sepa exactamente qué resolver. -2. **GitHub** — reutiliza el resultado de `gh pr view --json mergeable,state` ya obtenido en la precomprobación. Detecta conflictos que un `origin/` local desactualizado pasaría por alto (p. ej. alguien publicó un PR conflictivo en `main` desde la última sincronización). Un resultado `CONFLICTING` deniega. Un resultado `UNKNOWN` también deniega e instruye a Claude para que espere ~10 segundos y vuelva a comprobar antes de intentar detenerse de nuevo — esto evita falsos negativos mientras GitHub recalcula. +2. **GitHub** — reutiliza el resultado de `gh pr view --json mergeable,state` ya obtenido en la precomprobación. Detecta conflictos que un `origin/` local desactualizado pasaría por alto (p. ej. alguien ha fusionado una PR conflictiva en `main` desde el último fetch). Un resultado `CONFLICTING` deniega. Un resultado `UNKNOWN` también deniega e instruye a Claude para que espere ~10 segundos y vuelva a comprobar antes de intentar detenerse de nuevo — esto previene falsos negativos mientras GitHub recalcula. -Se omite completamente (allow) cuando: `gh` no está instalado, no existe ningún PR para la rama, el estado del PR no es `OPEN` (p. ej. `MERGED`, `CLOSED`), o `gh pr view` devuelve una salida no analizable. También fail-open cuando `origin/` falta localmente o cuando no hay commits por delante de la base — esos fallbacks de Capa 1 aún consultan la fusionabilidad del PR en caché antes de permitir. +Se omite completamente (permite) cuando: `gh` no está instalado, no existe ninguna PR para la rama, el estado de la PR no es `OPEN` (p. ej. `MERGED`, `CLOSED`), o `gh pr view` devuelve una salida no parseable. También falla de forma abierta cuando `origin/` no está disponible localmente o cuando no hay commits por delante de la base — esas derivaciones de Capa 1 siguen consultando la fusionabilidad de la PR en caché antes de permitir. **Parámetros:** | Parámetro | Tipo | Por defecto | Descripción | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Rama base contra la que se comprueban los conflictos. | +| `baseBranch` | `string` | `"main"` | Rama base contra la que comprobar los conflictos. | -Esta política requiere GitHub CLI (`gh`). Usa `gh pr view` para confirmar -que existe un PR `OPEN` antes de ejecutar cualquier sondeo de conflictos — sin `gh`, la política -aplica cortocircuito hacia allow. Ejecuta `gh auth login` con un token de acceso personal que tenga -el ámbito `repo` para acceso de lectura a pull requests. +El GitHub CLI (`gh`) es necesario para esta política. La política usa `gh pr view` para confirmar que existe una PR en estado `OPEN` antes de ejecutar cualquier sonda de conflicto — sin `gh`, la política hace cortocircuito hacia allow. Ejecuta `gh auth login` con un token de acceso personal que tenga el scope `repo` para acceso de lectura a pull requests. --- @@ -823,21 +819,20 @@ el ámbito `repo` para acceso de lectura a pull requests. ### `require-ci-green-before-stop` **Evento:** Stop -**Por defecto:** Deniega la detención cuando las comprobaciones de CI están fallando o aún en ejecución en la rama actual. Comprueba tanto las ejecuciones de flujo de trabajo de GitHub Actions como las comprobaciones de bots de terceros (p. ej. CodeRabbit, SonarCloud, Codecov). Trata las conclusiones `skipped`, `cancelled` y `neutral` como no fallidas (esta última cubre, por ejemplo, alertas de Socket Security en PRs de contribuidores externos, donde la aplicación intencionalmente informa neutral en lugar de éxito/fallo). Devuelve un mensaje informativo cuando todas las comprobaciones pasan. +**Por defecto:** Deniega la detención cuando las comprobaciones de CI están fallando o aún en ejecución en la rama actual. Comprueba tanto las ejecuciones de flujos de trabajo de GitHub Actions como las comprobaciones de bots de terceros (p. ej. CodeRabbit, SonarCloud, Codecov). Trata `skipped`, `cancelled` y `neutral` como conclusiones no fallidas (esta última cubre, por ejemplo, las alertas de Socket Security en PRs de colaboradores externos, donde la aplicación intencionalmente reporta neutral en lugar de éxito/fallo). Devuelve un mensaje informativo cuando todas las comprobaciones pasan. Sin parámetros. -Esta política requiere que [GitHub CLI](https://cli.github.com/) (`gh`) esté instalado y autenticado. -Ejecuta `gh auth login` con un token de acceso personal que tenga el ámbito `repo` para acceso de lectura a -ejecuciones de flujo de trabajo de Actions y a la API de Checks. Si `gh` no está instalado o no está autenticado, la política aplica fail-open e informa a Claude del motivo. +Esta política requiere tener instalado y autenticado el [GitHub CLI](https://cli.github.com/) (`gh`). +Ejecuta `gh auth login` con un token de acceso personal que tenga el scope `repo` para acceso de lectura a las ejecuciones de flujos de trabajo de Actions y la API de Checks. Si `gh` no está instalado o no está autenticado, la política falla de forma abierta e informa del motivo a Claude. --- --- -## Deshabilitar políticas individuales +## Desactivar políticas individuales Elimina una política específica de `enabledPolicies` en tu configuración, o desactívala en la pestaña Políticas del panel de control. diff --git a/docs/es/cli/audit.mdx b/docs/es/cli/audit.mdx index 6a1c25de..89ba66ca 100644 --- a/docs/es/cli/audit.mdx +++ b/docs/es/cli/audit.mdx @@ -1,23 +1,22 @@ --- title: Auditar sesiones pasadas (beta) -description: "Cuenta con qué frecuencia el agente realizó acciones innecesarias o riesgosas en transcripciones pasadas" +description: "Cuenta con qué frecuencia el agente realizó acciones innecesarias o riesgosas en transcripciones anteriores" --- - **Función beta.** La auditoría se lanza en beta mientras recopilamos - comentarios iniciales. El catálogo de detectores y el formato del informe - pueden cambiar antes de la próxima versión estable. Por favor, abre un issue - si algo parece incorrecto. + **Función en beta.** La auditoría se lanza en versión beta mientras recopilamos feedback inicial. + El catálogo de detectores y el formato del informe pueden cambiar antes del próximo + corte estable. Por favor abre un issue si algo parece incorrecto. -La auditoría reproduce las transcripciones pasadas de tu agente de CLI a través -del motor de políticas de failproofai y genera un informe visual y compartible -en la **página del panel `/audit`** — el arquetipo de tu agente, una puntuación -de 0 a 100, y exactamente qué políticas habrían detectado qué. +La auditoría reproduce tus transcripciones pasadas del agente CLI a través del motor de +políticas de failproofai y genera un informe visual y compartible en la **página del +dashboard `/audit`** — el arquetipo de tu agente, una puntuación del 0 al 100, y exactamente +qué políticas habrían detectado qué. -## Ejecutar la auditoría +## Ejecutarlo -Hay tres formas de iniciarla — todas llevan al mismo informe `/audit`. +Hay tres formas de acceder — todas llevan al mismo informe `/audit`. @@ -29,7 +28,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (panel) +```bash failproofai (dashboard) failproofai ``` @@ -37,101 +36,101 @@ failproofai - `npx -y failproofai audit` descarga failproofai, ejecuta el análisis y abre - el panel automáticamente — no necesitas instalar nada antes. + `npx -y failproofai audit` descarga failproofai, ejecuta el análisis y abre el + dashboard automáticamente — no necesitas instalar nada antes. `failproofai audit` ejecuta el análisis en tu terminal y luego abre - `localhost:8020/audit` automáticamente al terminar. + `localhost:8020/audit` automáticamente cuando termina. - - Ejecuta `failproofai` y haz clic en **Audit** en la barra de navegación - (entre Policies y Projects), o abre `/audit` directamente. + + Ejecuta `failproofai` y haz clic en **Audit** en la barra de navegación (entre Policies y + Projects), o abre `/audit` directamente. - Ejecuta `failproofai audit -h` (o `--help`) para ver el uso. La auditoría se - ejecuta **completamente sin conexión** — no requiere cuenta ni red — y el - panel sigue disponible hasta que lo detengas con `Ctrl+C`. + Ejecuta `failproofai audit -h` (o `--help`) para ver el uso. La auditoría funciona **completamente + sin conexión** — no requiere cuenta ni red — y el dashboard sigue disponible + hasta que lo detengas con `Ctrl+C`. -El panel analiza las transcripciones pasadas de la CLI del agente en esta máquina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) e informa con qué frecuencia el agente realizó acciones que failproofai está diseñado para detener — verificaciones de variables de entorno, force pushes, prefijos redundantes `cd `, bucles de polling con sleep, relectura de archivos recién editados, y más. +El dashboard analiza las transcripciones pasadas del agente CLI en esta máquina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) e informa con qué frecuencia el agente realizó acciones que failproofai está diseñado para detener — comprobaciones de variables de entorno, force pushes, prefijos redundantes `cd `, bucles de sondeo con sleep, relectura de archivos recién editados, y más. -Por cada transcripción, cada evento de uso de herramienta se reproduce a través de las 39 políticas integradas **y** a través de 8 detectores exclusivos de auditoría que capturan patrones que aún no están cubiertos por las políticas en tiempo real. Los conteos se agregan por política/detector en todas las sesiones. +Para cada transcripción, cada evento de uso de herramienta se reproduce a través de las 39 políticas integradas **y** a través de 8 detectores exclusivos de auditoría que identifican patrones que aún no están cubiertos por las políticas en tiempo real. Los recuentos se agregan por política/detector en todas las sesiones. ## Qué obtienes -La página `/audit` es un **póster** de pantalla única y compartible, seguido de cuatro secciones debajo del pliegue: +La página `/audit` es un **póster** de pantalla única y compartible seguido de cuatro secciones debajo del pliegue: -1. **Póster** — la identidad de tu agente de un vistazo: su **arquetipo** (uno de 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), sus palabras clave de personalidad, qué tan raro es ese arquetipo, y una **puntuación de 0 a 100** con una banda de nivel (`S` hasta `bottom tier`). Diseñado para compartir — publícalo en X o LinkedIn, o descárgalo como PNG. -2. **`// strengths`** — lo que tu agente ya hace bien, con números reales del análisis (p. ej., porcentaje de llamadas de herramienta limpias, `0` intentos de push-to-main), mostrado solo donde la política relevante tiene un historial limpio. -3. **`// quirks`** — lo que se escapó: una tabla ordenada de comportamientos que failproofai habría detectado — *cuándo* ocurrió por última vez, *qué se escapó* (y la política integrada que lo habría bloqueado), su *severidad*, y con qué frecuencia se *detectó* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — la lista de correcciones recomendadas: una fila por política con un `failproofai policy add ` listo para copiar y pegar, más un botón de **instalar todo** que habilita todas las recomendaciones a la vez y muestra tu **puntuación proyectada** si lo hicieras. -5. **`// come back better`** — crea el hábito: configura un **recordatorio** de reauditoría por correo electrónico (`3d` / `7d` / `14d` / `30d`) o reaudita ahora, e **invita a un amigo** a ejecutar su propia auditoría (enviado desde failproof.ai, con copia a ti). Los recordatorios e invitaciones requieren iniciar sesión. +1. **Póster** — la identidad de tu agente de un vistazo: su **arquetipo** (uno de 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), sus palabras clave de personalidad, qué tan raro es ese arquetipo, y una **puntuación del 0 al 100** con un nivel (`S` hasta `bottom tier`). Diseñado para compartir — publícalo en X o LinkedIn, o descárgalo como PNG. +2. **`// strengths`** — lo que tu agente ya hace bien, con cifras reales del análisis (por ejemplo, % de llamadas a herramientas limpias, `0` intentos de push-to-main), mostrado solo donde la política relevante tiene un historial limpio. +3. **`// quirks`** — lo que se escapó: una tabla clasificada de comportamientos que failproofai habría detectado — *cuándo* ocurrió por última vez, *qué se escapó* (y la política integrada que lo habría bloqueado), su *gravedad*, y con qué frecuencia se *observó* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — la lista de correcciones recomendadas: una fila por política con un `failproofai policy add ` listo para copiar y pegar, más un botón de **install all** que habilita todas las recomendaciones a la vez y muestra tu **puntuación proyectada** si lo hicieras. +5. **`// come back better`** — crea el hábito: configura un **recordatorio** de re-auditoría por email (`3d` / `7d` / `14d` / `30d`) o vuelve a auditar ahora, e **invita a un amigo** a ejecutar su propia auditoría (enviado desde failproof.ai, con copia a ti). Los recordatorios e invitaciones requieren iniciar sesión. ## Auditorías programadas -Si ejecutas el **daemon failproofaid** (ver [`failproofai config`](/es/cli/install-policies)), -puede volver a ejecutar la auditoría según un programa y actualizar el informe -`/audit` en segundo plano. Está **desactivado por defecto**, porque el análisis -lee el *contenido* de cada transcripción de sesión del agente en esta máquina -— nada se analiza con un temporizador hasta que lo solicites. - -Actívalo en `~/.failproofai/config.toml`: - -```toml -[audit] -auto = true -interval_days = 7 +Si ejecutas el **daemon failproofaid** (consulta [`failproofai config`](/es/cli/install-policies)), +puede volver a ejecutar la auditoría según un calendario y actualizar el informe `/audit` en +segundo plano. Está **desactivado de forma predeterminada**, porque el análisis lee el *contenido* +de cada transcripción de sesión del agente en esta máquina — nada se analiza de forma automática +hasta que lo solicites. + +Actívalo en `~/.failproofai/config.json` — agrega la clave `audit` junto con +lo que ya tenga el archivo: + +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | Clave | Significado | |---|---| -| `auto` | `true` habilita el análisis programado. Cualquier otro valor — ausente, `false`, `"yes"` — está desactivado. | +| `auto` | `true` habilita el análisis programado. Cualquier otro valor — ausente, `false`, `"yes"` — lo desactiva. | | `interval_days` | Días entre análisis. Limitado a 1–90; `0`, un valor negativo o no numérico vuelve a `7`. | -- El programa es de **reloj de pared**, por lo que sobrevive a suspensiones y - reinicios: una laptop que estaba dormida más allá de su hora programada - ejecuta el análisis **una vez** al despertar, nunca un backlog acumulado. -- Cada ejecución es un proceso separado de baja prioridad (`nice 19`) — nunca - en la ruta del hook del daemon, que permanece libre para responder llamadas - de herramientas. -- Un análisis se omite si `failproofai audit` o la re-ejecución del panel ya - están en curso; se reintenta poco después en lugar de tratarse como un error. -- El progreso se escribe en `~/.failproofai/state/audit-schedule.json` (última - ejecución, próxima fecha). El daemon gestiona ese archivo — cambia la - cadencia en `config.toml`. +- El calendario es de **reloj de pared**, por lo que sobrevive a suspensiones y reinicios: un portátil + que estaba dormido más allá de su hora programada ejecuta el análisis **una sola vez** al despertar, nunca acumula una cola. +- Cada ejecución es un proceso separado de baja prioridad (`nice 19`) — nunca en la + ruta de hooks del daemon, que permanece libre para responder a las llamadas de herramientas. +- Un análisis se omite si `failproofai audit` o la re-ejecución del dashboard ya están + en curso; se reintenta poco después en lugar de tratarse como un fallo. +- El progreso se escribe en `~/.failproofai/state/audit-schedule.json` (última ejecución, + próxima programada). El daemon es el propietario de ese archivo — cambia la cadencia en `config.json`. -Si habilitaste esto en una máquina configurada con una versión anterior de -failproofai, ejecuta `failproofai config` una vez. La definición del servicio -del daemon necesita una entrada adicional antes de poder lanzar la CLI, y la -actualización forma parte de ese comando. +Si habilitaste esto en una máquina configurada con una versión anterior de failproofai, ejecuta +`failproofai config` una vez. La definición del servicio del daemon necesita una entrada adicional +antes de poder lanzar la CLI, y la actualización forma parte de ese comando. ## Detectores exclusivos de auditoría -Estos detectan patrones de "comportamiento ineficiente" que aún no se aplican en tiempo real. Solo se ejecutan durante la auditoría y nunca bloquean una llamada de herramienta en vivo. +Estos detectan patrones de "comportamiento ineficiente" que aún no se aplican en tiempo real. Solo se ejecutan durante la auditoría y nunca bloquean una llamada a herramienta en vivo. | Detector | Qué cuenta | |---|---| -| `redundant-cd-cwd` | Comandos Bash que comienzan con `cd && …` aunque los comandos ya se ejecutan en `cwd`. | +| `redundant-cd-cwd` | Comandos Bash que comienzan con `cd && …` aunque los comandos ya se ejecuten en `cwd`. | | `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` en un único archivo fuente — usa la herramienta `Read`. | -| `prefer-edit-over-sed-awk` | Ediciones en el lugar con `sed -i` / `awk … > file` — usa la herramienta `Edit`. | +| `prefer-edit-over-sed-awk` | Ediciones en sitio con `sed -i` / `awk … > file` — usa la herramienta `Edit`. | | `prefer-write-over-heredoc` | Escritura de archivos con heredoc / `echo > file` multilínea — usa la herramienta `Write`. | -| `sleep-polling-loop` | `sleep N` largo (≥ 30s) o bucles de polling `while …; sleep …; done`. | +| `sleep-polling-loop` | `sleep N` largo (≥ 30s) o bucles de sondeo `while …; sleep …; done`. | | `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — limita el alcance a `cwd`. | | `git-commit-no-verify` | `git commit … --no-verify` / `-n`, omitiendo los hooks. | | `reread-after-edit` | `Read` de un archivo que acaba de ser modificado con `Edit`/`Write` en la misma sesión. | ## Cachés -- **Caché por transcripción** en `~/.failproofai/cache/audit/.json` con clave `(mtime, size, engineVersion, detectorVersion)` — se invalida automáticamente cuando cambia la transcripción o el código de política/detector. Cada entrada también almacena una marca de tiempo `cachedAt` como **metadatos de TTL** (no forman parte de la clave de caché); las entradas con más de **7 días** se rechazan al leer para que los resultados de larga duración no superen la intención cambiante de los detectores. -- **Caché de resultado completo** en `~/.failproofai/audit-dashboard.json` (modo 0600). Permite que el panel se renderice al instante al navegar sin necesidad de volver a ejecutar el análisis. También se rechaza al leer pasado el **TTL de 7 días** — `/audit` entonces cae a su estado vacío y solicita una nueva ejecución. Haz clic en `[ re-audit now ]` cerca de la parte inferior del informe para actualizar — la reauditoría envía `noCache: true`, por lo que omite la caché por transcripción y vuelve a analizar cada transcripción en lugar de devolver el resultado en caché; la ejecución transmite el progreso mediante una banda fija en la parte superior y reemplaza el resultado en el lugar al completarse con éxito (sin recargar la página; una reauditoría fallida conserva el informe anterior). +- **Caché por transcripción** en `~/.failproofai/cache/audit/.json` con clave por `(mtime, size, engineVersion, detectorVersion)` — se invalida automáticamente cuando cambia la transcripción o el código de políticas/detectores. Cada entrada también almacena una marca de tiempo `cachedAt` como **metadatos TTL** (no forma parte de la clave de caché); las entradas con más de **7 días** se rechazan en la lectura para que los resultados de larga duración no sobrevivan a la evolución de la intención de los detectores. +- **Caché de resultado completo** en `~/.failproofai/audit-dashboard.json` (modo 0600). Permite que el dashboard se muestre instantáneamente al navegar sin volver a ejecutar el análisis. También se rechaza en la lectura pasados los **7 días de TTL** — `/audit` entonces cae a su estado vacío y solicita una nueva ejecución. Haz clic en `[ re-audit now ]` cerca del final del informe para actualizar — la re-auditoría envía `noCache: true`, por lo que omite la caché por transcripción y vuelve a analizar cada transcripción en lugar de devolver el resultado en caché; la ejecución transmite el progreso mediante una banda superior fija y reemplaza el resultado en el lugar cuando termina correctamente (sin recarga de página; una re-auditoría fallida conserva el informe anterior). ## Notas -- **Sin mutaciones.** La auditoría se reproduce en modo de solo lectura. `warn-repeated-tool-calls` se omite porque su sidecar por sesión se modificaría de lo contrario. -- **Políticas de flujo de trabajo omitidas.** Las políticas `require-*-before-stop` solo se activan en eventos `Stop` y ejecutan `execSync` contra el estado de git en vivo — no tienen una interpretación significativa de "qué habría pasado en 2025", por lo que no aparecen en los conteos de auditoría. +- **Sin mutaciones.** La auditoría se reproduce en modo de solo lectura. `warn-repeated-tool-calls` se omite porque de lo contrario se modificaría su archivo sidecar por sesión. +- **Políticas de flujo de trabajo omitidas.** Las políticas `require-*-before-stop` solo se activan en eventos `Stop` y en `execSync` contra el estado git en vivo — no tienen una interpretación significativa de "qué habría pasado en 2025", por lo que no aparecen en los recuentos de auditoría. - **Políticas personalizadas omitidas.** Los hooks personalizados suministrados por el usuario no se reproducen (pueden haber cambiado desde la sesión original). \ No newline at end of file diff --git a/docs/es/cli/dashboard.mdx b/docs/es/cli/dashboard.mdx index f2e5b399..3900ef97 100644 --- a/docs/es/cli/dashboard.mdx +++ b/docs/es/cli/dashboard.mdx @@ -7,16 +7,16 @@ description: "Inicia el panel de control para explorar sesiones de agentes y ges failproofai ``` -Inicia el panel de control web en `http://localhost:8020`. +Inicia el panel web en `http://localhost:8020`. ## Opciones | Indicador | Descripción | |-----------|-------------| -| `--port ` | Puerto en el que escuchar (por defecto: `8020`) | -| `--allowed-origins ` | Hosts/IPs separados por comas con permiso para acceder a los recursos de desarrollo | +| `--port ` | Puerto en el que escuchar (predeterminado: `8020`) | +| `--allowed-origins ` | Hosts/IPs separados por comas con acceso permitido a recursos de desarrollo | -Para apuntar el panel de control a una carpeta de proyecto de Claude distinta a la predeterminada, establece la variable de entorno `CLAUDE_PROJECTS_PATH` al iniciarlo. +Para apuntar el panel a una carpeta de proyecto Claude distinta a la predeterminada, establece la variable de entorno `CLAUDE_PROJECTS_PATH` al iniciarlo. ## Ejemplos @@ -24,6 +24,6 @@ Para apuntar el panel de control a una carpeta de proyecto de Claude distinta a # Iniciar en un puerto diferente failproofai --port 9000 -# Usar una ruta de proyectos de Claude personalizada mediante variable de entorno +# Usar una ruta de proyectos Claude personalizada mediante variable de entorno CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/es/cli/environment-variables.mdx b/docs/es/cli/environment-variables.mdx index 3ae1a9c3..88d66b5b 100644 --- a/docs/es/cli/environment-variables.mdx +++ b/docs/es/cli/environment-variables.mdx @@ -3,13 +3,13 @@ title: Variables de entorno description: "Configura el comportamiento de failproofai con variables de entorno" --- -## Panel de control +## Dashboard | Variable | Descripción | |----------|-------------| -| `PORT` | Puerto del panel de control (por defecto: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Anula la ubicación donde se buscan las carpetas de proyectos de Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Páginas del panel separadas por comas que se ocultarán | +| `PORT` | Puerto del dashboard (por defecto: `8020`) | +| `CLAUDE_PROJECTS_PATH` | Reemplaza la ubicación donde se buscan las carpetas de proyectos de Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Páginas del dashboard a ocultar, separadas por comas | | `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs con acceso a recursos de desarrollo. Equivalente a `--allowed-origins`. | ## Registro @@ -17,56 +17,61 @@ description: "Configura el comportamiento de failproofai con variables de entorn | Variable | Descripción | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Nivel de registro del servidor (por defecto: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Ruta personalizada del archivo de registro de hooks, o `true` para usar el predeterminado (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Ruta personalizada para el archivo de log de hooks, o `true` para usar el predeterminado (`~/.failproofai/logs/hooks.log`) | ## Telemetría failproofai reporta telemetría de uso anónima por defecto. Hay dos formas de -desactivarla, y se aplica la más restrictiva de las dos — una variable de entorno -nunca puede reactivar algo que el archivo de configuración haya desactivado. +desactivarla, y se aplica la más restrictiva de las dos — una variable de +entorno nunca puede reactivar algo que el archivo de configuración haya +desactivado. | Variable | Descripción | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Desactiva la telemetría de uso anónima para este proceso | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Deshabilita la telemetría de uso anónima para este proceso | -Para desactivarla de forma permanente en la máquina, añade esto a `~/.failproofai/config.toml`: +Para desactivarla de forma permanente en la máquina, agrega esto a `~/.failproofai/config.json`: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` El archivo de configuración es la opción recomendada si ejecutas el **daemon failproofaid**. El daemon es un servicio de ámbito del sistema y su entorno no incluye las variables exportadas desde tu shell — por lo tanto, `FAILPROOFAI_TELEMETRY_DISABLED` no -puede alcanzarlo. `[telemetry] enabled = false` es leído tanto por la CLI como por el daemon. +puede llegar a él. `[telemetry] enabled = false` es leído tanto por la CLI como por el daemon. El daemon reporta únicamente su propio **ciclo de vida**: que se inició (y si la -ejecución anterior finalizó correctamente), que se detuvo, cuándo se creó o reinició -su worker de evaluación, cuándo falló una tarea del recolector y el resultado de una -sincronización de políticas en la nube. Estos eventos contienen valores de baja -cardinalidad y contadores — nunca una ruta de archivo, un comando, una política, un -prompt ni nada leído de una transcripción. No existe ningún evento por llamada a herramienta. +ejecución anterior terminó correctamente), que se detuvo, cuándo se lanzó o +reinició su worker de evaluación, cuándo falló una tarea del colector y el +resultado de una sincronización de políticas en la nube. Estos eventos incluyen +valores de baja cardinalidad y conteos — nunca una ruta de archivo, un comando, +una política, un prompt ni ningún contenido leído de una transcripción. No existe +ningún evento por llamada a herramienta. ## Autenticación | Variable | Descripción | |----------|-------------| -| `FAILPROOF_API_URL` | Anula la URL base del servidor de API utilizada por el diálogo de autenticación del panel. Por defecto es `https://api.befailproof.ai`; establécela en `http://localhost:8080` (o donde corresponda) al ejecutar un servidor de API local. | -| `FAILPROOFAI_AUTH_DIR` | Anula la ubicación donde se almacena `auth.json` (por defecto: `~/.failproofai`). Principalmente útil para pruebas aisladas. | +| `FAILPROOF_API_URL` | Reemplaza la URL base del servidor de API utilizada por el diálogo de autenticación del dashboard. Por defecto es `https://api.befailproof.ai`; establécela en `http://localhost:8080` (o donde corresponda) al ejecutar un servidor de API local. | +| `FAILPROOFAI_AUTH_DIR` | Reemplaza la ubicación donde se almacena `auth.json` (por defecto: `~/.failproofai`). Principalmente útil para pruebas aisladas. | -## Aviso de primer uso +## Prompt de primera ejecución | Variable | Descripción | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Omite el aviso que ofrece instalar políticas en la primera invocación básica de `failproofai` | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Omite el prompt que ofrece instalar políticas en la primera invocación básica de `failproofai` | ## LLM (para evaluación de políticas) | Variable | Descripción | |----------|-------------| | `FAILPROOFAI_LLM_BASE_URL` | Endpoint de la API del LLM (por defecto: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Clave de API para políticas basadas en LLM | +| `FAILPROOFAI_LLM_API_KEY` | Clave de API para políticas impulsadas por LLM | | `FAILPROOFAI_LLM_MODEL` | Nombre del modelo (por defecto: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/es/cli/hook.mdx b/docs/es/cli/hook.mdx index 5b703407..6c7b49a8 100644 --- a/docs/es/cli/hook.mdx +++ b/docs/es/cli/hook.mdx @@ -1,5 +1,5 @@ --- -title: Manejador de hooks (interno) +title: Manejador de hook (interno) description: "El subproceso que Claude Code invoca en cada evento de herramienta" --- @@ -7,17 +7,17 @@ description: "El subproceso que Claude Code invoca en cada evento de herramienta failproofai --hook ``` -Este es el comando registrado en el archivo `settings.json` de Claude Code por `failproofai policies --install`. Normalmente no se invoca directamente. +Este es el comando registrado en el `settings.json` de Claude Code por `failproofai policies --install`. Normalmente no se llama directamente. Lee un payload JSON desde stdin, evalúa todas las políticas habilitadas y termina con un código que indica la decisión: | Código de salida | Decisión | Efecto | |------------------|----------|--------| | `0` | `allow` | Permite la acción | -| `1` | `deny` | Bloquea la acción — Claude recibe el motivo del rechazo | +| `1` | `deny` | Bloquea la acción - Claude recibe el motivo del rechazo | | `2` | `instruct` | Inyecta orientación en el contexto de Claude | -### Tipos de eventos soportados +### Tipos de eventos admitidos | Categoría | Eventos | |-----------|---------| diff --git a/docs/es/cli/install-policies.mdx b/docs/es/cli/install-policies.mdx index 9ef01b7e..7e2ec74b 100644 --- a/docs/es/cli/install-policies.mdx +++ b/docs/es/cli/install-policies.mdx @@ -1,38 +1,38 @@ --- title: Instalar políticas -description: "Habilita políticas para que se ejecuten en cada llamada de herramienta del agente" +description: "Habilitar políticas para que se ejecuten en cada llamada de herramienta del agente" --- ```bash failproofai policies --install [policy-names...] [options] ``` -Escribe entradas de hook en el archivo de configuración del CLI del agente instalado (Claude Code, OpenAI Codex o GitHub Copilot CLI _(beta)_) para que failproofai intercepte las llamadas de herramientas. +Escribe entradas de hook en el archivo de configuración del CLI del agente instalado (Claude Code, OpenAI Codex o GitHub Copilot CLI _(beta)_) para que failproofai intercepte las llamadas de herramienta. Alias: `failproofai p -i` ## Opciones -| Bandera | Descripción | -|---------|-------------| -| `--cli claude\|codex\|copilot` | CLI(s) del agente en los que instalar; separados por espacios (p. ej. `--cli claude codex copilot`) o repetidos. Omite este parámetro para detectar los CLIs instalados y mostrar un menú. | -| `--scope user` | Instala en el archivo de configuración de ámbito de usuario (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Valor predeterminado. | +| Flag | Descripción | +|------|-------------| +| `--cli claude\|codex\|copilot` | CLI(s) del agente para los que instalar; separados por espacio (p. ej. `--cli claude codex copilot`) o repetidos. Omitir para detectar los CLIs instalados y mostrar un prompt. | +| `--scope user` | Instala en el archivo de configuración de ámbito de usuario (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Por defecto. | | `--scope project` | Instala en el archivo de configuración de ámbito de proyecto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Solo Claude — instala en `/.claude/settings.local.json`. Codex y Copilot no tienen un ámbito `local`. | +| `--scope local` | Solo para Claude — instala en `/.claude/settings.local.json`. Codex y Copilot no tienen ámbito `local`. | | `--custom ` / `-c` | Ruta a un archivo JS que contiene políticas de hook personalizadas | ## Comportamiento -- **Sin nombres de política** — abre un menú interactivo para seleccionar políticas -- **Nombres específicos** — habilita esas políticas (se añaden a las ya habilitadas) +- **Sin nombres de política** — abre un prompt interactivo para seleccionar políticas +- **Nombres específicos** — habilita esas políticas (se añaden a las que ya estén habilitadas) - **`all`** — habilita todas las políticas disponibles -La instalación es aditiva: volver a ejecutar `--install` agrega nuevas políticas sin eliminar las existentes. +La instalación es acumulativa: ejecutar `--install` de nuevo añade nuevas políticas sin eliminar las existentes. ## Ejemplos ```bash -# Instalar todas las políticas predeterminadas globalmente (interactivo) +# Instalar todas las políticas por defecto de forma global (interactivo) failproofai policies --install # Instalar políticas específicas para el proyecto actual @@ -47,11 +47,11 @@ failproofai policies --install --custom ./my-policies.js # Instalar para OpenAI Codex (ámbito de proyecto) failproofai policies --install --cli codex --scope project -# Instalar para GitHub Copilot CLI (beta) en el proyecto actual +# Instalar para GitHub Copilot CLI (beta) para el proyecto actual failproofai policies --install --cli copilot --scope project # Instalar para los tres CLIs a la vez failproofai policies --install --cli claude codex copilot ``` -Cuando se proporciona `--custom `, el archivo se valida de inmediato — debe llamar a `customPolicies.add()` al menos una vez. La ruta resuelta se guarda en `policies-config.json` como `customPoliciesPath`. \ No newline at end of file +Cuando se proporciona `--custom `, el archivo se valida inmediatamente — debe llamar a `customPolicies.add()` al menos una vez. La ruta resuelta se guarda en `policies-config.json` como `customPoliciesPath`. \ No newline at end of file diff --git a/docs/es/cli/list-policies.mdx b/docs/es/cli/list-policies.mdx index 9fd2ace6..df5c4ba8 100644 --- a/docs/es/cli/list-policies.mdx +++ b/docs/es/cli/list-policies.mdx @@ -1,6 +1,6 @@ --- title: Listar políticas -description: "Ver qué políticas están habilitadas, sus parámetros y las políticas personalizadas" +description: "Ver qué políticas están habilitadas, sus parámetros y políticas personalizadas" --- ```bash @@ -9,7 +9,7 @@ failproofai policies Muestra todas las políticas con su estado, parámetros configurados y políticas personalizadas. -## Salida de ejemplo +## Ejemplo de salida ```text Failproof AI Hook Policies (user) @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Las claves desconocidas en `policyParams` se marcan aquí para que puedas detectar errores tipográficos con antelación. \ No newline at end of file +Las claves desconocidas en `policyParams` se marcan aquí para que puedas detectar errores tipográficos con anticipación. \ No newline at end of file diff --git a/docs/es/cli/migrate.mdx b/docs/es/cli/migrate.mdx new file mode 100644 index 00000000..5957be87 --- /dev/null +++ b/docs/es/cli/migrate.mdx @@ -0,0 +1,86 @@ +--- +title: Migrar el directorio de inicio +description: "Actualiza ~/.failproofai al esquema que habla esta versión, y previsualiza los cambios antes de aplicarlos" +--- + +```bash +failproofai migrate --dry-run # muestra el plan sin modificar nada +failproofai migrate # ejecuta la migración +``` + +La mayoría de las personas nunca necesita escribir esto. Se ejecuta automáticamente al lanzar el primer comando tras una actualización, y [`failproofai update`](/es/cli/update) lo incluye. Úsalo directamente cuando quieras ver el plan antes de aplicarlo, o para ejecutar la migración de forma independiente. + +## Basado en el esquema, no en la versión + +`~/.failproofai/VERSION` registra un número de **esquema** — la estructura del directorio, no la versión que lo creó. Las migraciones se indexan por ese número, lo que hace que saltar muchas versiones sea económico: + +- Las versiones de npm cambian en cada lanzamiento; puede haber docenas entre dos esquemas. +- Así, una máquina que se salta treinta lanzamientos **sin cambio de esquema** ejecuta **cero** migraciones, no treinta operaciones vacías. +- Y una máquina que se salta varios esquemas a la vez ejecuta cada paso en orden, donde cada paso solo conoce sus propios dos extremos. + +Esto importa porque npm no puede actualizar un paquete instalado por sí solo. Lo habitual es que una máquina permanezca en una versión durante meses y luego salte varios esquemas de golpe — no es un caso inusual. + +## La simulación en seco + +`--dry-run` muestra la cadena exacta y los archivos que se guardarían primero, sin realizar ningún cambio — ni migración, ni copia de seguridad, ni entrada en el registro: + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## Qué se conserva y qué se reconstruye + +Cada ruta del directorio de inicio declara qué tipo de datos contiene, y eso determina si una migración puede descartarla. La regla: **lo derivado y recuperable puede eliminarse; lo que tú escribiste, lo que aún no se ha entregado y lo que identifica la máquina se conserva.** + +| Se conserva | Se reconstruye o se vuelve a obtener | +|---|---| +| `config.json` — ajustes, `daemon.configured`, rutas de captura adicionales | La caché de auditoría | +| `credentials.json` — tu inscripción en la nube | Despliegues gestionados en la nube (se vuelven a obtener y se verifica su hash en el siguiente sondeo) | +| `policies-config.json` — tu selección de políticas y parámetros | Estado temporal del daemon | +| `policies/` — tus propios archivos de políticas y los helpers que importan | | +| `hook-activity/` — el registro de decisiones que lee el panel | | +| Eventos pendientes de entrega en cola para carga | | +| `cursors/` — marcas de agua del recolector | | +| El binario del daemon en `bin/` | | + + + Los eventos pendientes de entrega se conservan en lugar de descartarse porque la pérdida sería permanente, no solo lenta: la marca de agua del recolector ya ha avanzado más allá de todo lo que haya en la cola de entrega, por lo que nada volvería a leer ese rango de una transcripción. La migración también le pide al daemon que entregue lo que está en cola en cuanto termine, así que lo habitual es que no quede nada por conservar. + + +Las claves que una versión *más reciente* escribió en `config.json`, `credentials.json` o `policies-config.json` también se preservan, en lugar de ser descartadas por un lector más antiguo. + +## El registro que deja + +``` +~/.failproofai/migrations/ + applied.json una entrada por paso: esquema, CLI, marca de tiempo, duración, resultado + backup-layout/ copias de los archivos irremplazables, tomadas antes del primer paso +``` + +`applied.json` responde a la pregunta «por qué ha pasado realmente esta máquina» — la primera pregunta que vale la pena hacer cuando algo parece incorrecto tras una actualización. Adjúntalo a un informe de error. + +La copia de seguridad es deliberadamente pequeña en lugar de ser una copia de todo el directorio: la migración ya no elimina nada irremplazable por diseño, por lo que lo que merece asegurarse es un *defecto en un paso*, y estos pocos archivos son donde tal defecto causaría daño. + +## Si un paso falla + +La cadena se detiene ahí. `VERSION` solo se actualiza cuando un paso se completa satisfactoriamente, por lo que el directorio de inicio permanece marcado con su esquema anterior y el siguiente comando lo reintenta — un directorio de inicio nunca se marca como actualizado basándose en una migración parcial. El paso se registra en `applied.json` con `"ok": false`, y la copia de seguridad permanece donde fue tomada. + +## Un directorio más nuevo se rechaza, no se migra + +Si `~/.failproofai/` fue escrito por una versión de failproofai **más reciente** que la que estás ejecutando, el comando se detiene y te indica que actualices. Esos datos están bien y una CLI más reciente los lee sin problemas; migrar «hacia adelante» desde ellos no es algo que exista, y resetearlos destruiría algo recuperable. + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +El daemon aplica la misma regla: `failproofaid` se niega a iniciarse con un esquema que no reconoce, en lugar de leer y escribir rutas que han cambiado de lugar. \ No newline at end of file diff --git a/docs/es/cli/remove-policies.mdx b/docs/es/cli/remove-policies.mdx index a220c0f6..279a5def 100644 --- a/docs/es/cli/remove-policies.mdx +++ b/docs/es/cli/remove-policies.mdx @@ -7,29 +7,29 @@ description: "Eliminar entradas de hooks de la configuración de Claude Code" failproofai policies --uninstall [policy-names...] [options] ``` -Elimina las entradas de hooks de failproofai del `settings.json` de Claude Code. +Elimina las entradas de hooks de failproofai del archivo `settings.json` de Claude Code. Alias: `failproofai p -u` ## Opciones -| Flag | Descripción | -|------|-------------| +| Indicador | Descripción | +|-----------|-------------| | `--scope user` | Eliminar de la configuración global (predeterminado) | | `--scope project` | Eliminar de la configuración del proyecto | | `--scope local` | Eliminar de la configuración local | | `--scope all` | Eliminar de todos los ámbitos a la vez | -| `--custom` / `-c` | Limpiar el `customPoliciesPath` de la configuración | +| `--custom` / `-c` | Borrar `customPoliciesPath` de la configuración | ## Comportamiento -- **Sin nombres de política** - elimina todas las entradas de hooks de failproofai del archivo de configuración -- **Nombres específicos** - deshabilita esas políticas pero mantiene los hooks instalados +- **Sin nombres de políticas** — elimina todas las entradas de hooks de failproofai del archivo de configuración +- **Nombres específicos** — deshabilita esas políticas pero mantiene los hooks instalados ## Ejemplos ```bash -# Eliminar todos los hooks globalmente +# Eliminar todos los hooks de forma global failproofai policies --uninstall # Deshabilitar una política específica (mantiene los hooks instalados) @@ -38,6 +38,6 @@ failproofai policies --uninstall block-sudo # Eliminar hooks de todos los ámbitos failproofai policies --uninstall --scope all -# Limpiar la ruta de políticas personalizadas +# Borrar la ruta de políticas personalizadas failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/es/cli/update.mdx b/docs/es/cli/update.mdx new file mode 100644 index 00000000..51b68809 --- /dev/null +++ b/docs/es/cli/update.mdx @@ -0,0 +1,102 @@ +--- +title: Actualizar tras una actualización +description: "Completa la mitad de una actualización que npm no puede hacer: migrar el directorio de inicio y sincronizar el daemon" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +Esa es la actualización completa. `npm` reemplaza la CLI; `failproofai update` hace +el resto. + +## Por qué existe un segundo comando + +`npm install -g` reemplaza una sola cosa: la CLI. Otras dos partes de una +instalación de failproofai viven fuera del paquete deliberadamente, y ninguna se +mueve cuando npm se ejecuta: + +- **`~/.failproofai/`**, tu configuración, inscripción en la nube, selección de + políticas e historial. Una nueva versión puede organizarlo de forma diferente, y + la reorganización debe realizarla código que conozca ambas estructuras. +- **El binario del daemon `failproofaid`**, en + `~/.failproofai/bin/failproofaid-`. No está dentro de `node_modules` + de forma deliberada: una actualización que intercambiara el archivo bajo un + servicio en ejecución redirigiría un daemon activo hacia un binario compilado + desde un código fuente diferente, y eliminar el paquete lo borraría de debajo de + un servicio que entonces entraría en un bucle de fallos en cada arranque. + +Así que después de ejecutar solo `npm install -g`, la CLI es nueva pero el daemon +no lo es. `failproofaid` se niega a iniciarse con una estructura de directorio de +inicio que no reconoce — la versión ruidosa de ese desajuste, no la silenciosa — +por lo que ambas mitades necesitan sincronizarse. `failproofai update` es ese paso. + +## Qué hace + + + + Lee la estructura registrada en `~/.failproofai/VERSION` y ejecuta los pasos + necesarios para actualizarla a la que esta versión reconoce. Normalmente + ninguno — consulta [`failproofai migrate`](/es/cli/migrate). + + + Desde el paquete de plataforma que npm ya descargó, cuando es posible (sin + red), o desde el recurso de la versión exacta, verificado con SHA-256 antes de + usarse. + + + Se verifica activamente en lugar de asumirse — un gestor de servicios reporta + un proceso activo en el momento en que se bifurca, lo cual no es lo mismo que + que esté funcionando. + + + +## Opciones + +| Indicador | Efecto | +|-----------|--------| +| `--no-daemon` | Migra solo el directorio de inicio, dejando el daemon en su versión actual. | + + + `--no-daemon` deja un daemon con versión desajustada en su lugar. En una máquina + configurada para requerir el daemon, cada evento de hook **falla de forma + cerrada** si el daemon no puede responder — y un daemon que se niega a iniciarse + con un directorio de inicio migrado no puede responder. Es preferible dejar que + la mitad del daemon también se ejecute. + + +## Si algo sale mal + +El comando termina con código distinto de cero e indica qué mitad falló. Dos casos +que conviene conocer: + +- **Un paso de migración no terminó.** El directorio de inicio se deja marcado con + su estructura *antigua*, de modo que el siguiente comando la reintenta — ningún + directorio se marca jamás como actual por el mérito de una migración parcial. Se + guardaron copias de tu configuración e inscripción antes de que se ejecutara + cualquier cosa, en `~/.failproofai/migrations/backup-layout/`. +- **El daemon no pudo reiniciarse sin contraseña.** `sudo -n` se usa de forma + deliberada, para que nada solicite credenciales desde debajo de un indicador de + progreso. El comando imprime la línea exacta que debes ejecutar tú mismo. + + + Nada de esto requiere el asistente de configuración interactivo. Tu + configuración, inscripción en la nube y selección de políticas sobreviven a una + actualización, por lo que una máquina migrada aplica exactamente igual que antes + — lo cual importa más en las máquinas sin nadie delante: un runner de CI, una + máquina de flota, una puerta de enlace sin interfaz gráfica. + + +## Automatizarlo + +`failproofai update` es no interactivo y seguro de ejecutar cuando no hay nada que +hacer — informa de que no se necesitaba ninguna migración y termina con código 0. +Añadirlo después de cada actualización en un script de aprovisionamiento o en un +Dockerfile es el uso previsto: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` en una compilación de imagen, donde todavía no hay ningún servicio +que reiniciar.) \ No newline at end of file diff --git a/docs/es/configuration.mdx b/docs/es/configuration.mdx index 54a2010f..c3162076 100644 --- a/docs/es/configuration.mdx +++ b/docs/es/configuration.mdx @@ -4,7 +4,7 @@ description: "Formato del archivo de configuración, sistema de tres ámbitos y icon: gear --- -failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y cada desarrollador tendrá la misma red de seguridad para el agente. +failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y cada desarrollador tendrá la misma red de seguridad del agente. --- @@ -15,10 +15,10 @@ Existen tres ámbitos de configuración, evaluados en orden de prioridad: | Ámbito | Ruta del archivo | Propósito | |--------|-----------------|-----------| | **project** | `.failproofai/policies-config.json` | Configuración por repositorio, confirmada en control de versiones | -| **local** | `.failproofai/policies-config.local.json` | Anulaciones personales por repositorio, ignoradas por git | -| **global** | `~/.failproofai/policies-config.json` | Valores predeterminados del usuario para todos los proyectos | +| **local** | `.failproofai/policies-config.local.json` | Sobreescrituras personales por repositorio, excluidas de git | +| **global** | `~/.failproofai/policies-config.json` | Valores predeterminados del usuario en todos los proyectos | -Cuando failproofai recibe un evento de hook, carga y combina los tres archivos que existen para el directorio de trabajo actual. +Cuando failproofai recibe un evento de hook, carga y combina los tres archivos que existen en el directorio de trabajo actual. ### Reglas de combinación @@ -32,13 +32,13 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unión sin duplicados ``` -**`policyParams`** — el primer ámbito que defina los parámetros para una política dada prevalece por completo. No se realiza una combinación profunda de los valores dentro de los parámetros de una política. +**`policyParams`** — el primer ámbito que define parámetros para una política determinada gana por completo. No hay combinación profunda de valores dentro de los parámetros de una política. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project prevalece, global se ignora +resolved: { allowPatterns: ["sudo apt-get update"] } ← project gana, global ignorado ``` ```text @@ -46,18 +46,18 @@ project: (sin entrada block-sudo) local: (sin entrada block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← cae al global +resolved: { allowPatterns: ["sudo systemctl status"] } ← cae hasta global ``` -**`customPoliciesPaths` / `customPoliciesPath`** — el primer ámbito que defina cualquiera de las dos formas prevalece. +**`customPoliciesPaths` / `customPoliciesPath`** — el primer ámbito que defina cualquiera de las dos formas gana. -**`disabledCustomPolicies`** — unión de todos los ámbitos. El panel escribe un -ID cualificado por fuente aquí cuando desactivas una política individual desde un -archivo de políticas explícito o de convención. Las políticas no listadas permanecen habilitadas +**`disabledCustomPolicies`** — unión entre todos los ámbitos. El panel escribe un +ID calificado por origen aquí cuando desactivas una política individual desde un +archivo de políticas explícito o de convención. Las políticas que no aparecen en la lista permanecen habilitadas de forma predeterminada; los IDs incluyen el archivo fuente para que las políticas con el mismo nombre en múltiples archivos puedan controlarse de forma independiente. -**`llm`** — el primer ámbito que lo defina prevalece. +**`llm`** — el primer ámbito que lo defina gana. --- @@ -116,11 +116,11 @@ Las políticas que no están en `enabledPolicies` están inactivas, incluso si t Tipo: `Record>` -Anulaciones de parámetros por política. La clave exterior es el nombre de la política; las claves interiores son específicas de cada política. Cada política documenta sus parámetros disponibles en [Políticas integradas](/es/built-in-policies). +Sobreescrituras de parámetros por política. La clave externa es el nombre de la política; las claves internas son específicas de cada política. Cada política documenta sus parámetros disponibles en [Políticas integradas](/es/built-in-policies). -Si una política tiene parámetros pero no los especificas, se utilizan los valores predeterminados integrados de la política. Los usuarios que no configuran `policyParams` en absoluto obtienen un comportamiento idéntico al de versiones anteriores. +Si una política tiene parámetros pero no los especificas, se utilizan los valores predeterminados integrados de la política. Los usuarios que no configuran `policyParams` en absoluto obtendrán un comportamiento idéntico al de versiones anteriores. -Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente en el momento de dispararse el hook, pero se marcan como advertencias cuando ejecutas `failproofai policies`. +Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente al momento de activarse el hook, pero se marcan como advertencias cuando ejecutas `failproofai policies`. #### `hint` (transversal) @@ -149,37 +149,43 @@ Funciona con cualquier tipo de política: integrada, personalizada (`custom/`), Cuando `block-force-push` deniega, Claude ve: *"Force-pushing is blocked. Try creating a fresh branch instead."* -Los valores que no son cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si `hint` no está definido, el comportamiento no cambia (compatible con versiones anteriores). +Los valores que no son cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si no se establece `hint`, el comportamiento no cambia (compatible con versiones anteriores). ### `customPoliciesPath` Tipo: `string` (ruta absoluta) -Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Este valor lo establece automáticamente `failproofai policies --install --custom ` (la ruta se resuelve a absoluta antes de almacenarse). +Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Esto se establece automáticamente mediante `failproofai policies --install --custom ` (la ruta se resuelve a absoluta antes de almacenarse). -El archivo se carga de nuevo en cada evento de hook; no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para más detalles sobre cómo crearlas. +El archivo se carga de nuevo en cada evento de hook; no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para obtener detalles de creación. ### Políticas basadas en convención -Además del `customPoliciesPath` explícito, failproofai descubre y carga automáticamente archivos de políticas desde los directorios `.failproofai/policies/`: +Además del `customPoliciesPath` explícito, failproofai detecta y carga automáticamente archivos de políticas desde directorios `.failproofai/policies/`: | Nivel | Directorio | Ámbito | |-------|-----------|--------| | Proyecto | `.failproofai/policies/` | Compartido con el equipo mediante control de versiones | -| Usuario | `~/.failproofai/policies/custom-policies/` | Personal, se aplica a todos los proyectos | +| Usuario | `~/.failproofai/policies/` | Personal, se aplica a todos los proyectos | - El directorio de nivel de usuario se movió un nivel más abajo en la - reorganización del directorio home. Los archivos que quedaron en la antigua ruta `~/.failproofai/policies/` se mueven - automáticamente a `custom-policies/` la primera vez que ejecutas cualquier comando `failproofai` - después de actualizar, y el comando te indica qué archivos movió. + Coloca tus políticas directamente en `~/.failproofai/policies/`. La + carpeta `cloud-policies/` junto a ellas contiene políticas que tu organización desplegó + en esta máquina; el proceso de descubrimiento no desciende a subdirectorios, por lo que + nunca se analiza y nada que pongas en `policies/` puede colisionar con ella. + + Si estás actualizando desde una versión que usaba + `~/.failproofai/policies/custom-policies/`, todo lo que haya en esa carpeta —tus + archivos de políticas, cualquier `lib/` de ayudantes que importen y cualquier archivo de datos que lean— + se mueve automáticamente hacia arriba la primera vez que ejecutas un comando `failproofai`, + y el comando te indica qué movió. -**Coincidencia de archivos:** Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}` (por ejemplo, `security-policies.mjs`, `workflow-policies.js`). Los demás archivos del directorio se ignoran. +**Coincidencia de archivos:** Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}` (p. ej., `security-policies.mjs`, `workflow-policies.js`). Los demás archivos en el directorio se ignoran. -**Sin configuración necesaria:** Las políticas de convención no requieren ninguna entrada en `policies-config.json`. Solo coloca los archivos en el directorio y se detectarán en el siguiente evento de hook. +**Sin configuración necesaria:** Las políticas de convención no requieren entradas en `policies-config.json`. Solo coloca los archivos en el directorio y se detectarán en el próximo evento de hook. -**Carga por unión:** Se analizan tanto el directorio de convención del proyecto como el del usuario. Se cargan todos los archivos coincidentes de ambos niveles (a diferencia de `customPoliciesPath`, que usa el principio de primer ámbito ganador). +**Carga por unión:** Se analizan tanto el directorio de convención del proyecto como el del usuario. Todos los archivos coincidentes de ambos niveles se cargan (a diferencia de `customPoliciesPath`, que utiliza el principio de primero-en-ganar por ámbito). Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y ejemplos. @@ -187,7 +193,7 @@ Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y e Tipo: `object` (opcional) -Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesario en la mayoría de los casos. +Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesaria para la mayoría de las configuraciones. ```json { @@ -207,19 +213,19 @@ Los comandos `policies --install` y `policies --uninstall` escriben en el archiv - **Configuración de la CLI del agente** — indica al agente que llame a `failproofai --hook ` en cada uso de herramienta: - **Claude Code**: `~/.claude/settings.json` (usuario), `/.claude/settings.json` (proyecto), `/.claude/settings.local.json` (local) - **OpenAI Codex**: `~/.codex/hooks.json` (usuario), `/.codex/hooks.json` (proyecto) — Codex no tiene ámbito `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuario), `/.github/hooks/failproofai.json` (proyecto) — Copilot no tiene ámbito `local`. Las entradas de hook usan los campos de comando `bash`/`powershell` con clave de SO de Copilot con `timeoutSec`; el archivo lleva un marcador de nivel superior `version: 1`. La compatibilidad con Copilot CLI es **beta** mientras verificamos el esquema de registros `events.jsonl` (que la documentación pública no especifica) con más sesiones del mundo real. **El modo de agente de VS Code Copilot Chat (Preview)** lee las configuraciones de hook desde `.github/hooks/*.json`, `~/.copilot/hooks/*.json` y `~/.claude/settings.json` (gobernado por la configuración `chat.hookFilesLocations`) usando el mismo contrato Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exactamente las rutas que esta integración `copilot` y la integración `claude` (`~/.claude/settings.json`) ya escriben, por lo que `failproofai policies --install --cli copilot` (o `--cli claude`) **ya aplica en el modo de agente de VS Code** sin necesidad de una integración `vscode` separada (confirmado en vivo desde los registros de descubrimiento de VS Code). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuario), `/.cursor/hooks.json` (proyecto) — Cursor no tiene ámbito `local`. Las entradas de hook usan la forma Claude `{type, command, timeout}` (sin división `bash`/`powershell`), pero almacenadas bajo claves de eventos en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) en un array plano según el [esquema de hooks de Cursor](https://cursor.com/docs/hooks); el archivo lleva un marcador de nivel superior `version: 1`. El manejador canonicaliza camelCase → PascalCase mediante `CURSOR_EVENT_MAP` para que las políticas integradas existentes se disparen sin cambios. La compatibilidad con Cursor Agent es **beta** mientras verificamos el formato de transcripción en disco de Cursor (no especificado en la documentación pública) con más instalaciones del mundo real. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuario), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proyecto) — OpenCode no tiene ámbito `local`. A diferencia de las otras cinco CLIs, OpenCode **no tiene sistema de hooks de comandos externos**: carga plugins JS/TS en proceso registrados explícitamente mediante el array `plugin: []` en `opencode.json` (la autodescubrimiento desde `.opencode/plugins/` **no** es como cargan los plugins en opencode v1.14.33). La instalación coloca un pequeño shim de plugin generado que llama al binario de failproofai como subproceso y traduce la respuesta JSON con forma Claude del binario de vuelta a semántica de plugins: `throw new Error()` para denegación de evento de herramienta (cancela la llamada a la herramienta), `client.session.prompt(...)` para instruct Y para denegación de `Stop` / `SubagentStop` (envía el motivo de denegación como el siguiente mensaje de usuario — el único canal de reintento forzado ya que `session.idle` es solo de notificación y lanzar una excepción desde él no tiene efecto), y no-op para allow. El shim canonicaliza tanto los nombres de herramientas (minúsculas → PascalCase mediante `OPENCODE_TOOL_MAP`) como las claves de argumento de entrada de herramientas (camelCase → snake_case mediante `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, por ejemplo `filePath` → `file_path`, `oldString` → `old_string`) antes de reenviar al binario, por lo que las políticas integradas de comprobación de rutas como `block-read-outside-cwd`, `block-env-files` y `block-secrets-write` se disparan sin cambios en las llamadas a herramientas de OpenCode. Las sesiones viven en la base de datos SQLite de opencode en `~/.local/share/opencode/opencode.db`; el visor de sesiones del panel las lee mediante `opencode db --format json` y `opencode export `. La compatibilidad con OpenCode es **beta** mientras verificamos el comportamiento en distintas versiones y con más sesiones del mundo real. Consulta la [documentación de plugins de OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuario), `/.pi/settings.json` (proyecto) — Pi no tiene ámbito `local`. Pi carga paquetes de extensión TypeScript al inicio; el archivo de configuración es un array plano de cadenas `{"packages": ["./relative/path", …]}`. failproofai escribe una única entrada en el array de paquetes que apunta a su directorio `pi-extension/` incluido. La extensión se suscribe internamente a los eventos `tool_call` / `user_bash` / `input` / `session_start` de Pi y llama a `failproofai --hook --cli pi`; el manejador canonicaliza underscore_lower_snake_case → PascalCase mediante `PI_EVENT_MAP` para que las políticas integradas existentes se disparen sin cambios. Los argumentos de entrada de herramientas también se canonicalizan mediante `PI_TOOL_INPUT_MAP` (los eventos Read / Write / Edit de Pi entregan `path` en lugar de `file_path`; mapear la clave de nivel superior permite que se disparen `block-env-files` y `block-secrets-write` — `block-read-outside-cwd` ya tenía un fallback para `path`). La compatibilidad con Pi es **beta** mientras la API de extensión de Pi y el esquema de registro de sesiones se estabilizan. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**solo ámbito de usuario** — Hermes no tiene configuración de proyecto/local). Hermes es una **pasarela** de Slack/Telegram, por lo que una sola instalación intercepta las llamadas a herramientas de cada plataforma (Slack/Telegram/cli/cron) **y** subagentes internos. Las entradas de hook son un par `{command, timeout}` (tiempo de espera en **segundos**) bajo un mapa `hooks:` con clave de los eventos snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); el manejador canonicaliza los eventos mediante `HERMES_EVENT_MAP` y los nombres de herramientas mediante `HERMES_TOOL_MAP` para que las políticas integradas se disparen sin cambios. La configuración se edita mediante una ida y vuelta de `Document` YAML que preserva los comentarios para que las otras configuraciones del operador sobrevivan, y la instalación establece `hooks_auto_accept: true` para que la pasarela sin cabeza (sin TTY) ejecute los hooks sin un aviso de consentimiento. El evaluador emite el contrato stdout `{"decision":"block","reason"}` de Hermes (Hermes ignora los códigos de salida). **Limitaciones:** Hermes no tiene evento `Stop` al final del turno, por lo que las políticas integradas `require-*-before-stop` nunca se disparan para él (no aplicable, no es un error); `instruct` degrada a permitir con nota registrada (sin canal de contexto adicional); y la redacción de secretos en la salida (`sanitize-*`) no puede reescribir la salida de la herramienta a través del contrato de hook de shell. Hermes es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones de pasarela directamente desde `~/.hermes/state.db`. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**solo ámbito de usuario** — OpenClaw no tiene configuración de proyecto/local). Al igual que Hermes, OpenClaw es una **pasarela** multicanal autoalojada, por lo que una sola instalación intercepta las llamadas a herramientas de cada canal y sus subagentes internos. La aplicación se ejecuta a través de los **hooks de plugin en proceso** de OpenClaw (sus hooks internos basados en archivos son solo de observación y no pueden bloquear), por lo que — al igual que OpenCode/Pi — failproofai incluye un paquete estático `openclaw-plugin/` que genera el binario de failproofai de forma asíncrona y traduce el veredicto. La instalación registra el directorio de plugin incluido en `plugins.load.paths[]` de `openclaw.json` y lo habilita bajo `plugins.entries.failproofai` (con `hooks.allowConversationAccess: true`, necesario para los hooks de conversación sin procesar). El evaluador emite un veredicto plano `{permission, reason}` y el shim lo mapea a la forma de retorno nativa de cada hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), y `before_agent_finalize → {action:"revise", reason}` (**Stop** — una compuerta real al final del turno, por lo que las políticas integradas `require-*-before-stop` **se aplican** en OpenClaw, a diferencia de Hermes). Los eventos y los nombres de herramientas se canonicalizan en el lado del binario mediante `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) para que las políticas integradas se disparen sin cambios; el shim falla de forma abierta ante cualquier error de ejecución/análisis/tiempo de espera. OpenClaw es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones JSONL en `~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (usuario), `/.factory/hooks.json` (proyecto) — Factory no tiene ámbito `local`. droid incluye un sistema de hooks de comandos externos al estilo Claude, pero con dos particularidades verificadas en vivo con droid v0.171.0: (1) los nombres de eventos se encuentran en el **nivel superior** de `hooks.json` — **no hay envoltorio `"hooks"`** (droid lo rechaza); los eventos de herramientas (`PreToolUse`/`PostToolUse`) llevan `"matcher": "*"`, los eventos que no son de herramientas lo omiten. (2) La denegación se controla por el **código de salida 2 + stderr** del hook, no por una decisión JSON — la rama `factory` del evaluador devuelve salida 2 para eventos de herramienta/prompt y `{decision:"block", reason}` solo en el evento `Stop` al final del turno (el único canal de reintento forzado de droid). Los eventos ya están en PascalCase (sin mapa de eventos) y el payload es snake_case de Claude; solo los nombres de herramientas se canonicalizan mediante `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones JSONL en disco en `~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (usuario), `/.devin/config.json` (proyecto) — Devin no tiene ámbito `local`. Devin es un **clon puro de Claude** verificado en vivo con devin v3000.1.27: usa el esquema estándar de envoltorio `"hooks"` de Claude (las escrituras preservan la combinación para que las otras claves del archivo de configuración — `org_id`, `theme_mode`, … — sobrevivan), nombres de eventos ya en PascalCase (sin mapa de eventos, sin rama del manejador) y un payload stdin en snake_case de Claude (sin normalización). La rama `devin` del evaluador deniega con JSON `{"decision":"block","reason"}` en stdout con salida 0 para **cada** evento (verificado — el bloqueo anuló `--permission-mode dangerous`); en el evento `Stop` al final del turno, el motivo lleva el texto de reintento forzado MANDATORY-ACTION para que las políticas integradas `require-*-before-stop` se apliquen. Solo los nombres de herramientas se canonicalizan mediante `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` ya es canónico). Devin es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones SQLite en `~/.local/share/devin/cli/sessions.db` (cada fila de `sessions` lleva un `working_directory` real, por lo que las sesiones se agrupan por cwd del proyecto como Claude). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (usuario), `/.agents/hooks.json` (proyecto) — Antigravity no tiene ámbito `local`. A diferencia de Factory/Devin, Antigravity tiene su **propio** contrato (no es un clon de Claude), verificado en vivo con agy v1.1.2. `hooks.json` usa un esquema de **hook con nombre**: la clave de nivel superior es un *nombre* de hook (`"failproofai"`) cuyo valor es un mapa evento→manejadores — los eventos de herramientas (`PreToolUse`/`PostToolUse`) envuelven los manejadores en `{matcher:"*", hooks:[…]}`, mientras que `PreInvocation`/`Stop` son arrays de manejadores **planos** (otros hooks con nombre se preservan). El payload stdin es **protojson en camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai lo normaliza a snake_case antes de ejecutar las políticas, y mapea los args en PascalCase de `run_command` (`CommandLine`/`Cwd`) mediante `ANTIGRAVITY_TOOL_INPUT_MAP`. La rama `antigravity` del evaluador usa las **propias** formas de respuesta de Antigravity: `{decision:"deny", reason}` bloquea una herramienta/prompt (salida 0), `{decision:"continue", reason}` en el evento `Stop` al final del turno vuelve a entrar en el bucle (por lo que las políticas integradas `require-*-before-stop` se aplican), y `{injectSteps:[{ephemeralMessage}]}` inyecta una instrucción en `PreInvocation` (→ `UserPromptSubmit`). Los nombres de herramientas se canonicalizan mediante `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity es **también** una fuente de **auditoría** sin conexión — el panel lee sus transcripciones JSONL planas en `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (índice de conversaciones en `conversation_summaries.db`). - - **Goose (nombre en clave goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (usuario), `/.agents/plugins/failproofai/hooks/hooks.json` (proyecto) — Goose no tiene ámbito `local`. La aplicación usa el sistema de **hooks** de Goose, la especificación transversal de agentes **Open Plugins**: el instalador simplemente coloca el directorio del plugin `failproofai` y Goose lo autodescubre al inicio (registrándolo automáticamente en `~/.config/goose/config.yaml`). El `hooks.json` usa un esquema de Open Plugins **con** un envoltorio `"hooks"` de nivel superior, y el matcher se **omite** en cada evento — un `"*"` simple es una expresión regular inválida que no coincide con nada (verificado en vivo con goose v1.43.0). Los nombres de eventos ya están en PascalCase (sin mapa de eventos); el payload stdin usa `event`/`working_dir`, que el manejador normaliza a `hook_event_name`/`cwd`. La rama `goose` del evaluador deniega con JSON `{"decision":"block","reason"}` en stdout con salida 0, respetado en el evento **`PreToolUse`** únicamente (incluido en goose ≥ v1.37.0) — que se dispara para la herramienta de shell **y dentro de subagentes delegados**, por lo que es el único punto de denegación suficiente; cualquier otro error de hook falla de forma **abierta**. Goose **no tiene evento `Stop`**, por lo que las políticas integradas `require-*-before-stop` no aplican (como con Hermes). Los nombres de herramientas se canonicalizan mediante `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) y las claves de ruta mediante `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones SQLite en `~/.local/share/goose/sessions/sessions.db` (cada fila de `sessions` lleva un `working_dir` real, por lo que las sesiones se agrupan por cwd del proyecto como Devin; las ejecuciones rápidas con `--no-session` se filtran). -- **`policies-config.json`** — indica a failproofai qué políticas evaluar y con qué parámetros (compartido entre todas las CLIs de agente) - -Pasa `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` para apuntar a un agente específico (separados por espacios o repetidos para cualquier subconjunto): + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuario), `/.github/hooks/failproofai.json` (proyecto) — Copilot no tiene ámbito `local`. Las entradas de hook utilizan los campos de comando `bash`/`powershell` con clave de SO de Copilot con `timeoutSec`; el archivo lleva un marcador `version: 1` en el nivel superior. El soporte de Copilot CLI está en **beta** mientras verificamos el esquema de registros de `events.jsonl` (que la documentación pública no especifica) contra más sesiones del mundo real. **El modo agente de VS Code Copilot Chat (Preview)** lee configuraciones de hook desde `.github/hooks/*.json`, `~/.copilot/hooks/*.json` y `~/.claude/settings.json` (gobernado por la configuración `chat.hookFilesLocations`) usando el mismo contrato de Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exactamente las rutas que esta integración `copilot` y la integración `claude` (`~/.claude/settings.json`) ya escriben, por lo que `failproofai policies --install --cli copilot` (o `--cli claude`) **ya aplica en el modo agente de VS Code** sin necesidad de una integración `vscode` separada (confirmado en vivo desde los registros de descubrimiento de VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuario), `/.cursor/hooks.json` (proyecto) — Cursor no tiene ámbito `local`. Las entradas de hook usan el formato de Claude `{type, command, timeout}` (sin división `bash`/`powershell`), pero se almacenan bajo claves de evento en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) en un array plano según el [esquema de hooks de Cursor](https://cursor.com/docs/hooks); el archivo lleva un marcador `version: 1` en el nivel superior. El manejador canonicaliza camelCase → PascalCase mediante `CURSOR_EVENT_MAP` para que las políticas integradas existentes se activen sin cambios. El soporte de Cursor Agent está en **beta** mientras verificamos el formato de transcripción en disco de Cursor (no especificado en la documentación pública) contra más instalaciones del mundo real. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuario), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proyecto) — OpenCode no tiene ámbito `local`. A diferencia de los otros cinco CLIs, OpenCode **no tiene un sistema de hook de comandos externos**: carga plugins JS/TS en proceso registrados explícitamente mediante el array `plugin: []` en `opencode.json` (el autodescubrimiento desde `.opencode/plugins/` **no** es como se cargan los plugins en opencode v1.14.33). La instalación coloca un pequeño shim de plugin generado que llama al binario failproofai como subproceso y traduce la respuesta JSON con forma de Claude del binario de vuelta a semántica de plugin: `throw new Error()` para denegación de eventos de herramienta (cancela la llamada a la herramienta), `client.session.prompt(...)` para instruct Y para denegación de `Stop` / `SubagentStop` (envía el motivo de denegación como el siguiente mensaje de usuario — el único canal de reintento forzado ya que `session.idle` es solo de notificación y lanzar desde él es una operación sin efecto), y sin efecto para allow. El shim canonicaliza tanto los nombres de herramientas (minúsculas → PascalCase mediante `OPENCODE_TOOL_MAP`) como las claves de argumentos de entrada de herramientas (camelCase → snake_case mediante `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, p. ej. `filePath` → `file_path`, `oldString` → `old_string`) antes de reenviarlos al binario, de modo que las políticas integradas de verificación de rutas como `block-read-outside-cwd`, `block-env-files` y `block-secrets-write` se activan sin cambios en las llamadas de herramientas de OpenCode. Las sesiones viven en la BD SQLite de opencode en `~/.local/share/opencode/opencode.db`; el visor de sesiones del panel las lee mediante `opencode db --format json` y `opencode export `. El soporte de OpenCode está en **beta** mientras verificamos el comportamiento entre versiones y contra más sesiones del mundo real. Consulta la [documentación de plugins de OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuario), `/.pi/settings.json` (proyecto) — Pi no tiene ámbito `local`. Pi carga paquetes de extensión TypeScript al inicio; el archivo de configuración es un array de cadenas plano `{"packages": ["./relative/path", …]}`. failproofai escribe una sola entrada en el array de paquetes que apunta a su directorio `pi-extension/` integrado. La extensión suscribe internamente los eventos `tool_call` / `user_bash` / `input` / `session_start` de Pi y ejecuta `failproofai --hook --cli pi`; el manejador canonicaliza underscore_lower_snake_case → PascalCase mediante `PI_EVENT_MAP` para que las políticas integradas existentes se activen sin cambios. Los argumentos de entrada de herramientas también se canonizan mediante `PI_TOOL_INPUT_MAP` (Read / Write / Edit de Pi entregan `path` en lugar de `file_path`; mapear la clave de nivel superior permite que `block-env-files` y `block-secrets-write` se activen — `block-read-outside-cwd` ya tenía un fallback para `path`). El soporte de Pi está en **beta** mientras la API de extensión de Pi y el formato del registro de sesiones se estabilizan. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**solo ámbito de usuario** — Hermes no tiene configuración de proyecto/local). Hermes es una **pasarela** de Slack/Telegram, por lo que una instalación intercepta llamadas de herramientas de cada plataforma (Slack/Telegram/cli/cron) **y** subagentes internos. Las entradas de hook son un par `{command, timeout}` (tiempo de espera en **segundos**) bajo un mapa `hooks:` con clave de los eventos snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); el manejador canonicaliza los eventos mediante `HERMES_EVENT_MAP` y los nombres de herramientas mediante `HERMES_TOOL_MAP` para que las políticas integradas se activen sin cambios. La configuración se edita mediante un `Document` YAML de ida y vuelta que preserva los comentarios para que el resto de la configuración del operador sobreviva, e install establece `hooks_auto_accept: true` para que la pasarela sin cabeza (sin TTY) ejecute los hooks sin una solicitud de consentimiento. El evaluador emite el contrato stdout `{"decision":"block","reason"}` de Hermes (Hermes ignora los códigos de salida). **Limitaciones:** Hermes no tiene un evento `Stop` de fin de turno, por lo que los integrados `require-*-before-stop` nunca se activan para él (no aplicable, no roto); `instruct` se degrada a allow-con-nota-registrada (sin canal de contexto adicional); y la redacción de secretos de salida (`sanitize-*`) no puede reescribir la salida de herramientas a través del contrato de hook de shell. Hermes es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones de pasarela directamente desde `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**solo ámbito de usuario** — OpenClaw no tiene configuración de proyecto/local). Como Hermes, OpenClaw es una **pasarela** multicanal autohospedada, por lo que una instalación intercepta llamadas de herramientas de cada canal y sus subagentes internos. La aplicación se ejecuta a través de los **hooks de plugin en proceso** de OpenClaw (sus hooks internos basados en archivos son solo de observación y no pueden bloquear), por lo que — como OpenCode/Pi — failproofai incluye un paquete estático `openclaw-plugin/` que genera de forma asíncrona el binario failproofai y traduce el veredicto. Install registra el directorio del plugin incluido en `plugins.load.paths[]` de `openclaw.json` y lo habilita bajo `plugins.entries.failproofai` (con `hooks.allowConversationAccess: true`, requerido para los hooks de conversación sin procesar). El evaluador emite un veredicto plano `{permission, reason}` y el shim lo asigna a la forma de retorno nativa de cada hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), y `before_agent_finalize → {action:"revise", reason}` (**Stop** — una compuerta real de fin de turno, por lo que los integrados `require-*-before-stop` **aplican** en OpenClaw, a diferencia de Hermes). Los eventos y nombres de herramientas se canonizan del lado del binario mediante `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) para que las políticas integradas se activen sin cambios; el shim falla de forma abierta ante cualquier error de generación/análisis/tiempo de espera. OpenClaw es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones JSONL en `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (usuario), `/.factory/hooks.json` (proyecto) — Factory no tiene ámbito `local`. droid incluye un sistema de hook de comandos externos al estilo de Claude, pero con dos peculiaridades verificadas en vivo contra droid v0.171.0: (1) los nombres de eventos viven en el **nivel superior** de `hooks.json` — **no hay un envoltorio `"hooks"`** (droid lo rechaza); los eventos de herramienta (`PreToolUse`/`PostToolUse`) llevan `"matcher": "*"`, los eventos que no son de herramienta lo omiten. (2) La denegación se controla mediante el **código de salida 2 + stderr** del hook, no por una decisión JSON — la rama `factory` del evaluador devuelve salida 2 para eventos de herramienta/prompt y `{decision:"block", reason}` solo en el evento `Stop` de fin de turno (el único canal de reintento forzado de droid). Los eventos ya están en PascalCase (sin mapa de eventos) y el payload es snake_case de Claude; solo los nombres de herramientas se canonizan mediante `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones JSONL en disco en `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (usuario), `/.devin/config.json` (proyecto) — Devin no tiene ámbito `local`. Devin es un **clon puro de Claude** verificado en vivo contra devin v3000.1.27: usa el esquema estándar de envoltorio `"hooks"` de Claude (las escrituras preservan la fusión para que las demás claves del archivo de configuración — `org_id`, `theme_mode`, … — sobrevivan), nombres de eventos ya en PascalCase (sin mapa de eventos, sin rama de manejador), y un payload stdin snake_case de Claude (sin normalización). La rama `devin` del evaluador deniega con JSON `{"decision":"block","reason"}` en stdout en salida 0 para **cada** evento (verificado — el bloque anuló `--permission-mode dangerous`); en el evento `Stop` de fin de turno, el motivo lleva el texto de reintento forzado MANDATORY-ACTION para que los integrados `require-*-before-stop` apliquen. Solo los nombres de herramientas se canonizan mediante `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` ya es canónico). Devin es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones SQLite en `~/.local/share/devin/cli/sessions.db` (cada fila de `sessions` lleva un `working_directory` real, por lo que las sesiones se agrupan por cwd de proyecto como Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (usuario), `/.agents/hooks.json` (proyecto) — Antigravity no tiene ámbito `local`. A diferencia de Factory/Devin, Antigravity tiene su **propio** contrato (no es un clon de Claude), verificado en vivo contra agy v1.1.2. `hooks.json` usa un esquema de **hook con nombre**: la clave de nivel superior es un *nombre* de hook (`"failproofai"`) cuyo valor es un mapa de evento→manejadores — los eventos de herramienta (`PreToolUse`/`PostToolUse`) envuelven los manejadores en `{matcher:"*", hooks:[…]}`, mientras que `PreInvocation`/`Stop` son arrays de manejadores **planos** (otros hooks con nombre se preservan). El payload stdin es **protojson en camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai lo normaliza a snake_case antes de que las políticas se ejecuten, y mapea los args PascalCase de `run_command` (`CommandLine`/`Cwd`) mediante `ANTIGRAVITY_TOOL_INPUT_MAP`. La rama `antigravity` del evaluador usa las **propias** formas de respuesta de Antigravity: `{decision:"deny", reason}` bloquea una herramienta/prompt (salida 0), `{decision:"continue", reason}` en el evento `Stop` de fin de turno re-entra al bucle (por lo que los integrados `require-*-before-stop` aplican), y `{injectSteps:[{ephemeralMessage}]}` inyecta una instrucción en `PreInvocation` (→ `UserPromptSubmit`). Los nombres de herramientas se canonizan mediante `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity es **también** una fuente de **auditoría** sin conexión — el panel lee sus transcripciones JSONL planas en `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (índice de conversación en `conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (usuario), `/.agents/plugins/failproofai/hooks/hooks.json` (proyecto) — Goose no tiene ámbito `local`. La aplicación usa el sistema de **hooks** de Goose, la especificación de **Open Plugins** entre agentes: el instalador simplemente coloca el directorio del plugin `failproofai` y Goose lo autodescubre al inicio (registrándolo automáticamente en `~/.config/goose/config.yaml`). El `hooks.json` usa un esquema de Open Plugins **con** un envoltorio `"hooks"` en el nivel superior, y el matcher se **omite** en cada evento — un `"*"` sin formato es una expresión regular inválida que no coincide con nada (verificado en vivo contra goose v1.43.0). Los nombres de eventos ya están en PascalCase (sin mapa de eventos); el payload stdin usa `event`/`working_dir`, que el manejador normaliza a `hook_event_name`/`cwd`. La rama `goose` del evaluador deniega con JSON `{"decision":"block","reason"}` en stdout en salida 0, respetado en el evento **`PreToolUse`** únicamente (incluido en goose ≥ v1.37.0) — que se activa tanto para la herramienta de shell **como dentro de subagentes delegados**, por lo que es el único punto de denegación suficiente; cualquier otro error de hook falla de forma **abierta**. Goose **no tiene evento `Stop`**, por lo que los integrados `require-*-before-stop` no aplican (como con Hermes). Los nombres de herramientas se canonizan mediante `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) y las claves de ruta mediante `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones SQLite en `~/.local/share/goose/sessions/sessions.db` (cada fila de `sessions` lleva un `working_dir` real, por lo que las sesiones se agrupan por cwd de proyecto como Devin; las ejecuciones temporales de `--no-session` se filtran). +- **`policies-config.json`** — indica a failproofai qué políticas evaluar y con qué parámetros (compartido entre todos los CLIs de agente) + +Pasa `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` para seleccionar un agente específico (separados por espacio o repetidos para cualquier subconjunto): ```bash failproofai policies --install --cli codex --scope project @@ -236,15 +242,33 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Cuando se omite `--cli`, `failproofai` detecta qué CLIs de agente están instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +Cuando se omite `--cli`, `failproofai` detecta qué CLIs de agente están instalados (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **Una CLI detectada** — la selecciona automáticamente sin preguntar. -- **Varias CLIs detectadas** en una terminal interactiva — muestra un prompt de selección única con teclas de flecha agrupado en una sección `Detected (N)` (con una fila agregada `Install for all N detected` + cada CLI detectada individualmente) y una sección `Not installed (M) · install hooks ahead of time` que lista cada CLI compatible no detectada como opción de instalación anticipada (↑↓ para moverse, Enter para seleccionar, ^C para salir). El flujo de desinstalación solo muestra la sección Detected. -- **Varias CLIs detectadas** en una ejecución no interactiva (CI, sin TTY) — instala para todas las CLIs detectadas sin preguntar. -- **Ninguna detectada** — recurre a `claude`, con una advertencia de que no se encontró ningún binario de agente en PATH; el comando de hook se escribe igualmente para que se active en cuanto instales uno. +- **Un CLI detectado** — lo selecciona automáticamente sin preguntar. +- **Múltiples CLIs detectados** en una terminal interactiva — muestra un prompt de selección única con teclas de flecha agrupado en una sección `Detected (N)` (con una fila agregada `Install for all N detected` + cada CLI detectado individualmente) y una sección `Not installed (M) · install hooks ahead of time` que enumera cada CLI soportado no detectado como opción de instalación anticipada (↑↓ para moverse, Enter para seleccionar, ^C para salir). El flujo de desinstalación muestra solo la sección Detected. +- **Múltiples CLIs detectados** en una ejecución no interactiva (CI, sin TTY) — instala para todos los CLIs detectados sin preguntar. +- **Ninguno detectado** — recurre a `claude`, con una advertencia de que no se encontró ningún binario de agente en PATH; el comando de hook se escribe de todas formas para que se active en cuanto instales uno. Puedes editar `policies-config.json` directamente en cualquier momento; los cambios surten efecto inmediatamente en el siguiente evento de hook sin necesidad de reiniciar. +## Las actualizaciones conservan tu configuración + +Una nueva versión de failproofai puede organizar `~/.failproofai/` de forma diferente. Cuando eso ocurre, el primer comando tras la actualización migra el directorio, y **tu configuración se traslada, no se restablece**: + +| Conservado | Reconstruido | +|---|---| +| Tu selección de políticas y parámetros (`policies-config.json`) | La caché de auditoría | +| Tu configuración, incluyendo `daemon.configured` y rutas de captura adicionales (`config.json`) | Despliegues de políticas administradas en la nube — se recuperan y verifican con firma en el próximo sondeo | +| Tu inscripción en la nube (`credentials.json`) | Estado temporal del daemon | +| Tus propios archivos de políticas en `policies/`, y los ayudantes que importan | | +| El registro de decisiones que lee el panel, y los eventos aún no entregados | | + +Las claves escritas por una versión *más reciente* de failproofai también se conservan, en lugar de ser descartadas por un lector más antiguo — por lo que moverse entre versiones no descarta silenciosamente configuraciones en ninguna dirección. + +**No** necesitas volver a ejecutar la configuración después: una máquina migrada aplica exactamente como lo hacía antes, que es lo que hace que una actualización sea segura en máquinas sin nadie delante. Cada migración se registra en `~/.failproofai/migrations/applied.json`, y los archivos irremplazables se copian en `~/.failproofai/migrations/backup-layout/` antes de que se ejecute cualquier cosa. + +Consulta [`failproofai update`](/es/cli/update) para la actualización en una sola línea, y [`failproofai migrate`](/es/cli/migrate) — incluyendo `--dry-run` — para los detalles. + --- ## Ejemplo: configuración a nivel de proyecto con valores predeterminados del equipo @@ -268,4 +292,4 @@ Confirma `.failproofai/policies-config.json` en tu repositorio: } ``` -Cada desarrollador puede entonces crear `.failproofai/policies-config.local.json` (ignorado por git) para sus anulaciones personales sin afectar a sus compañeros de equipo. \ No newline at end of file +Cada desarrollador puede entonces crear `.failproofai/policies-config.local.json` (excluido de git) para sobreescrituras personales sin afectar a sus compañeros de equipo. \ No newline at end of file diff --git a/docs/es/custom-policies.mdx b/docs/es/custom-policies.mdx index fe079c8f..2c475b0d 100644 --- a/docs/es/custom-policies.mdx +++ b/docs/es/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: Políticas Personalizadas -description: "Escribe tus propias políticas en JavaScript: aplica convenciones del proyecto, previene la deriva, detecta fallos e integra con sistemas externos" +description: "Escribe tus propias políticas en JavaScript: aplica convenciones, evita la deriva, detecta fallos e integra con sistemas externos" icon: code --- -Las políticas personalizadas te permiten escribir reglas para cualquier comportamiento del agente: aplicar convenciones del proyecto, prevenir la deriva, bloquear operaciones destructivas, detectar agentes bloqueados o integrarte con Slack, flujos de aprobación y más. Utilizan el mismo sistema de eventos de hooks y las decisiones `allow`, `deny`, `instruct` que las políticas integradas. +Las políticas personalizadas te permiten escribir reglas para cualquier comportamiento del agente: aplicar convenciones del proyecto, prevenir la deriva, controlar operaciones destructivas, detectar agentes bloqueados o integrarse con Slack, flujos de aprobación y mucho más. Utilizan el mismo sistema de eventos de hooks y las decisiones `allow`, `deny`, `instruct` que las políticas integradas. --- @@ -39,57 +39,57 @@ failproofai policies --install --custom ./my-policies.js ## Dos formas de cargar políticas personalizadas -### Opción 1: Por convención (recomendada) +### Opción 1: Basada en convención (recomendada) -Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargarán automáticamente, sin necesidad de flags ni cambios de configuración. Funciona como los git hooks: deposita el archivo y listo. +Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargarán automáticamente, sin necesidad de banderas ni cambios en la configuración. Funciona como los hooks de git: dejas el archivo ahí y listo. ``` -# A nivel de proyecto — incluido en git, compartido con el equipo +# Nivel de proyecto — confirmado en git, compartido con el equipo .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# A nivel de usuario — personal, aplica a todos los proyectos +# Nivel de usuario — personal, se aplica a todos los proyectos ~/.failproofai/policies/my-policies.mjs ``` **Cómo funciona:** -- Se analizan tanto el directorio del proyecto como el del usuario (unión; no gana el primero en el ámbito) +- Se analizan tanto el directorio del proyecto como el del usuario (unión, no el primero que gana por ámbito) - Los archivos se cargan en orden alfabético dentro de cada directorio. Usa el prefijo `01-`, `02-` para controlar el orden -- Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}`; los demás se ignoran +- Solo se cargan archivos que coincidan con `*policies.{js,mjs,ts}`; los demás se ignoran - Cada archivo se carga de forma independiente (fail-open por archivo) - Funciona junto con `--custom` explícito y las políticas integradas -Las políticas por convención son la forma más sencilla de establecer un estándar de calidad para tu organización. Incluye `.failproofai/policies/` en git y cada miembro del equipo obtendrá las mismas reglas automáticamente, sin configuración individual. A medida que el equipo descubra nuevos modos de fallo, añade una política y envíala. Con el tiempo, estas se convierten en un estándar de calidad vivo que mejora con cada contribución. +Las políticas de convención son la forma más sencilla de establecer un estándar de calidad para tu organización. Confirma `.failproofai/policies/` en git y todos los miembros del equipo recibirán las mismas reglas automáticamente, sin configuración por desarrollador. A medida que tu equipo descubre nuevos modos de fallo, añade una política y publícala. Con el tiempo, estas se convierten en un estándar de calidad vivo que mejora con cada contribución. ### Opción 2: Ruta de archivo explícita ```bash -# Instalar con un archivo de políticas personalizado +# Instalar con un archivo de políticas personalizadas failproofai policies --install --custom ./my-policies.js # Reemplazar las rutas de políticas personalizadas failproofai policies --install --custom ./new-policies.js -# Configurar múltiples archivos explícitos (cargados en el orden de los flags) +# Configurar múltiples archivos explícitos (cargados en el orden de las banderas) failproofai policies --install --custom ./security.js --custom ./workflow.js # Eliminar todas las rutas de políticas personalizadas explícitas de la configuración failproofai policies --uninstall --custom ``` -Las rutas absolutas resueltas se almacenan en `policies-config.json` como `customPoliciesPaths`. Repite `--custom` para configurar múltiples archivos. Las configuraciones existentes que usen el campo heredado `customPoliciesPath` siguen funcionando. Los archivos se cargan de nuevo en cada evento de hook; no hay caché entre eventos. +Las rutas absolutas resueltas se almacenan en `policies-config.json` como `customPoliciesPaths`. Repite `--custom` para configurar varios archivos. Las configuraciones existentes que usan el campo heredado `customPoliciesPath` siguen funcionando. Los archivos se cargan de nuevo en cada evento de hook; no hay caché entre eventos. -Cada política registrada aparece con su propio interruptor en el panel. Desactivar una política registra su ID calificado por fuente en `disabledCustomPolicies`; el archivo y sus demás políticas continúan cargándose, mientras que la política desactivada se excluye antes de la coincidencia de eventos. Los nombres de políticas duplicados entre archivos tienen interruptores independientes. +Cada política registrada aparece con su propio control en el panel. Desactivar una política registra su ID calificado por fuente en `disabledCustomPolicies`; el archivo y sus demás políticas continúan cargándose, mientras que la política desactivada se excluye antes de la coincidencia de eventos. Los nombres de política duplicados en distintos archivos tienen controles independientes. -### Usar ambas a la vez +### Usando ambas a la vez -Las políticas por convención y los archivos `--custom` explícitos pueden coexistir. Orden de carga: +Las políticas de convención y los archivos `--custom` explícitos pueden coexistir. Orden de carga: 1. Archivos `customPoliciesPaths` explícitos (en el orden configurado) -2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, orden alfabético) -3. Archivos de convención del usuario (`~/.failproofai/policies/`, orden alfabético) +2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, alfabético) +3. Archivos de convención del usuario (`~/.failproofai/policies/`, alfabético) --- @@ -109,38 +109,38 @@ Registra una política. Llámalo tantas veces como sea necesario para múltiples customPolicies.add({ name: string; // requerido - identificador único description?: string; // se muestra en la salida de `failproofai policies` - match?: { events?: HookEventType[] }; // filtrar por tipo de evento; omitir para coincidir con todos + match?: { events?: HookEventType[] }; // filtra por tipo de evento; omitir para coincidir con todos fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Helpers de decisión +### Funciones de decisión -| Función | Efecto | Úsalo cuando | +| Función | Efecto | Úsala cuando | |----------|--------|----------| -| `allow()` | Permite la operación en silencio | La acción es segura y no se necesita mensaje | -| `deny(message)` | Bloquea la operación | El agente no debería realizar esta acción | -| `instruct(message)` | Añade contexto sin bloquear | Proporciona contexto adicional al agente para que no se desvíe | +| `allow()` | Permite la operación sin mensajes | La acción es segura y no requiere mensaje | +| `deny(message)` | Bloquea la operación | El agente no debe realizar esta acción | +| `instruct(message)` | Añade contexto sin bloquear | El agente necesita contexto adicional para mantenerse en curso | -`deny(message)` — el mensaje aparece para Claude con el prefijo `"Blocked by failproofai:"`. Un único `deny` cortocircuita toda evaluación posterior. +`deny(message)`: el mensaje aparece ante Claude con el prefijo `"Blocked by failproofai:"`. Un único `deny` cortocircuita toda evaluación posterior. -`instruct(message)` — el mensaje se añade al contexto de Claude para la llamada de herramienta actual. Todos los mensajes `instruct` se acumulan y se entregan juntos. +`instruct(message)`: el mensaje se añade al contexto de Claude para la llamada de herramienta actual. Todos los mensajes `instruct` se acumulan y se entregan juntos. -Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` incluyendo un campo `hint` en `policyParams`, sin necesidad de cambiar el código. Esto funciona también para políticas personalizadas (`custom/`), de convención del proyecto (`.failproofai-project/`) y de convención del usuario (`.failproofai-user/`). Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles. +Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` agregando un campo `hint` en `policyParams`, sin necesidad de cambiar el código. Esto también funciona para políticas personalizadas (`custom/`), de convención de proyecto (`.failproofai-project/`) y de convención de usuario (`.failproofai-user/`). Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles. -### Mensajes allow informativos +### Mensajes informativos de allow -`allow(message)` permite la operación **y** envía un mensaje informativo a Claude. El mensaje se entrega como `additionalContext` en la respuesta stdout del handler del hook, el mismo mecanismo que usa `instruct`, aunque semánticamente diferente: es una actualización de estado, no una advertencia. +`allow(message)` permite la operación **y** envía un mensaje informativo de vuelta a Claude. El mensaje se entrega como `additionalContext` en la respuesta stdout del handler del hook, el mismo mecanismo que usa `instruct`, pero semánticamente diferente: es una actualización de estado, no una advertencia. -| Función | Efecto | Úsalo cuando | +| Función | Efecto | Úsala cuando | |----------|--------|----------| | `allow(message)` | Permite y envía contexto a Claude | Confirmar que una comprobación pasó o explicar por qué se omitió | Casos de uso: - **Confirmaciones de estado:** `allow("All CI checks passed.")` — indica a Claude que todo está en orden -- **Explicaciones de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — indica a Claude por qué se omitió una comprobación para que tenga contexto completo +- **Explicaciones de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — le dice a Claude por qué se omitió una comprobación para que tenga el contexto completo - **Acumulación de múltiples mensajes:** si varias políticas devuelven `allow(message)`, todos los mensajes se unen con saltos de línea y se entregan juntos ```js @@ -165,10 +165,10 @@ customPolicies.add({ | Campo | Tipo | Descripción | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | La herramienta que se está invocando (p. ej., `"Bash"`, `"Write"`, `"Read"`) | +| `toolName` | `string \| undefined` | La herramienta que se está llamando (p. ej. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Los parámetros de entrada de la herramienta | -| `payload` | `Record` | Payload completo del evento sin procesar de Claude Code | -| `session` | `SessionMetadata \| undefined` | Contexto de sesión (ver más abajo) | +| `payload` | `Record` | Carga útil del evento completa y sin procesar de Claude Code | +| `session` | `SessionMetadata \| undefined` | Contexto de la sesión (ver más abajo) | ### Campos de `SessionMetadata` @@ -180,12 +180,12 @@ customPolicies.add({ ### Tipos de eventos -| Evento | Cuándo se activa | Contenido de `toolInput` | +| Evento | Cuándo se dispara | Contenido de `toolInput` | |-------|--------------|----------------------| -| `PreToolUse` | Antes de que Claude ejecute una herramienta | La entrada de la herramienta (p. ej., `{ command: "..." }` para Bash) | -| `PostToolUse` | Tras completarse una herramienta | La entrada de la herramienta + `tool_result` (la salida) | +| `PreToolUse` | Antes de que Claude ejecute una herramienta | La entrada de la herramienta (p. ej. `{ command: "..." }` para Bash) | +| `PostToolUse` | Después de que una herramienta completa | La entrada de la herramienta + `tool_result` (la salida) | | `Notification` | Cuando Claude envía una notificación | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — los hooks siempre deben devolver `allow()`, no pueden bloquear notificaciones | -| `Stop` | Cuando finaliza la sesión de Claude | Vacío | +| `Stop` | Cuando la sesión de Claude finaliza | Vacío | --- @@ -195,18 +195,18 @@ Las políticas se evalúan en este orden: 1. Políticas integradas (en orden de definición) 2. Políticas personalizadas explícitas de `customPoliciesPath` (en orden de `.add()`) -3. Políticas de convención del proyecto en `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno) -4. Políticas de convención del usuario en `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno) +3. Políticas de convención del proyecto `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro) +4. Políticas de convención del usuario `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro) -El primer `deny` cortocircuita todas las políticas siguientes. Todos los mensajes `instruct` se acumulan y se entregan juntos. +El primer `deny` cortocircuita todas las políticas posteriores. Todos los mensajes `instruct` se acumulan y se entregan juntos. --- ## Importaciones transitivas -Los archivos de políticas personalizadas pueden importar módulos locales mediante rutas relativas: +Los archivos de políticas personalizadas pueden importar módulos locales usando rutas relativas: ```js // my-policies.js @@ -236,33 +236,33 @@ customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Solo se activa cuando finaliza la sesión + // Solo se activa cuando la sesión finaliza // ctx.session.transcriptPath contiene el registro completo de la sesión return allow(); }, }); ``` -Omite `match` por completo para activarla en todos los tipos de eventos. +Omite `match` por completo para que se active en cada tipo de evento. --- ## Manejo de errores y modos de fallo -Las políticas personalizadas son **fail-open**: los errores nunca bloquean las políticas integradas ni detienen el handler del hook. +Las políticas personalizadas son **fail-open**: los errores nunca bloquean las políticas integradas ni hacen fallar el handler del hook. | Fallo | Comportamiento | |---------|----------| -| `customPoliciesPath` no configurado | No se ejecutan políticas personalizadas explícitas; las políticas de convención y las integradas continúan con normalidad | +| `customPoliciesPath` no establecido | No se ejecutan políticas personalizadas explícitas; las políticas de convención y las integradas continúan con normalidad | | Archivo no encontrado | Se registra una advertencia en `~/.failproofai/hook.log`; las integradas continúan | | Error de sintaxis/importación (explícito) | Se registra el error en `~/.failproofai/hook.log`; se omiten las políticas personalizadas explícitas | -| Error de sintaxis/importación (por convención) | Se registra el error; ese archivo se omite, los demás archivos de convención continúan cargándose | -| `fn` lanza un error en tiempo de ejecución | Se registra el error; ese hook se trata como `allow`; los demás hooks continúan | -| `fn` tarda más de 10 s | Se registra el tiempo de espera; se trata como `allow` | -| Directorio de convención no existe | No se ejecutan políticas de convención; sin error | +| Error de sintaxis/importación (convención) | Se registra el error; ese archivo se omite, los demás archivos de convención siguen cargándose | +| `fn` lanza en tiempo de ejecución | Se registra el error; ese hook se trata como `allow`; los demás hooks continúan | +| `fn` tarda más de 10 segundos | Se registra el tiempo de espera; se trata como `allow` | +| Directorio de convención inexistente | No se ejecutan políticas de convención; sin error | -Para depurar errores en políticas personalizadas, monitorea el archivo de log: +Para depurar errores de políticas personalizadas, monitorea el archivo de log: ```bash tail -f ~/.failproofai/hook.log @@ -277,7 +277,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Evitar que el agente escriba en el directorio secrets/ +// Prevent agent from writing to secrets/ directory customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -290,7 +290,7 @@ customPolicies.add({ }, }); -// Mantener al agente en curso: verificar los tests antes de hacer commit +// 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", @@ -305,7 +305,7 @@ customPolicies.add({ }, }); -// Prevenir cambios de dependencias no planificados durante el periodo de congelamiento +// Prevent unplanned dependency changes during freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -328,31 +328,31 @@ export { customPolicies }; ## Ejemplos -El directorio `examples/` contiene archivos de políticas listos para usar: +El directorio `examples/` contiene archivos de políticas listos para ejecutar: | Archivo | Contenido | |------|----------| -| `examples/policies-basic.js` | Cinco políticas básicas que cubren los modos de fallo más comunes del agente | +| `examples/policies-basic.js` | Cinco políticas de inicio que cubren los modos de fallo más comunes de los agentes | | `examples/policies-advanced/index.js` | Patrones avanzados: importaciones transitivas, llamadas asíncronas, limpieza de salida y hooks de fin de sesión | | `examples/convention-policies/security-policies.mjs` | Políticas de seguridad basadas en convención (bloquear escrituras en .env, prevenir la reescritura del historial de git) | -| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo basadas en convención (recordatorios de tests, auditoría de escrituras de archivos) | +| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo basadas en convención (recordatorios de tests, auditoría de escrituras en archivos) | -### Usar los ejemplos de archivo explícito +### Usando los ejemplos de archivos explícitos ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### Usar los ejemplos basados en convención +### Usando los ejemplos basados en convención ```bash -# Copiar a nivel de proyecto +# Copiar al nivel del proyecto mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# O copiar a nivel de usuario +# O copiar al nivel del usuario mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -No se necesita ningún comando de instalación: los archivos se detectan automáticamente en el siguiente evento de hook. \ No newline at end of file +No se necesita ningún comando de instalación: los archivos se detectan automáticamente en el próximo evento de hook. \ No newline at end of file diff --git a/docs/es/dashboard.mdx b/docs/es/dashboard.mdx index fa9b207e..ea7a75e7 100644 --- a/docs/es/dashboard.mdx +++ b/docs/es/dashboard.mdx @@ -16,7 +16,7 @@ failproofai Se abre en `http://localhost:8020`. -El dashboard lee datos de configuración del proyecto local, sesiones y failproofai directamente desde el sistema de archivos. Las funciones autenticadas opcionales, como recordatorios de auditoría e invitaciones, envían la información necesaria para esas solicitudes (incluidas las direcciones de correo electrónico) a APIs remotas. +El dashboard lee los datos de configuración del proyecto local, la sesión y failproofai directamente desde el sistema de archivos. Las funciones opcionales autenticadas, como recordatorios de auditoría e invitaciones, envían la información necesaria para esas solicitudes (incluidas las direcciones de correo electrónico) a APIs remotas. --- @@ -24,13 +24,13 @@ El dashboard lee datos de configuración del proyecto local, sesiones y failproo ### Proyectos -Lista todos los proyectos de Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity y Goose encontrados en tu máquina. Los proyectos de Claude se descubren en `~/.claude/projects/` (o la ruta definida por `CLAUDE_PROJECTS_PATH`); los proyectos de Codex se descubren escaneando todas las transcripciones en `~/.codex/sessions///
/*.jsonl` y agrupando por el `cwd` registrado en el primer registro de cada sesión; los proyectos de Copilot CLI se descubren escaneando cada `~/.copilot/session-state//workspace.yaml` (configurable mediante `COPILOT_HOME`) y agrupando por su campo `cwd`; los proyectos de Cursor Agent se descubren escaneando los metadatos por sesión en `~/.cursor/agent-sessions//` (configurable mediante `CURSOR_HOME`, con `conversations/` y `sessions/` como rutas alternativas) para un escalar `cwd` en `meta.json` / `session.json` / `workspace.yaml`; los proyectos de OpenCode se descubren consultando su base de datos SQLite en `~/.local/share/opencode/opencode.db` mediante `opencode db --format json` (leemos las tablas `session` y `project` y agrupamos por `project_id`); los proyectos de Pi se descubren escaneando transcripciones JSONL por sesión en `~/.pi/agent/sessions//_.jsonl` (configurable mediante `PI_SESSIONS_DIR`) y extrayendo el `cwd` del primer registro de cada sesión; las sesiones del gateway de Hermes se leen directamente del almacén SQLite de cada perfil — `~/.hermes/state.db` más `~/.hermes/profiles//state.db` (reemplazable mediante `HERMES_HOME`, o `HERMES_DB_PATH` para una sola base de datos) — y se agrupan en proyectos `hermes--` por perfil y `source` (Slack/Telegram/cli/cron — las sesiones del gateway no tienen cwd); las sesiones del gateway de OpenClaw se leen desde `~/.openclaw/agents//sessions/*.jsonl` y se agrupan en proyectos `openclaw--` por agente y canal (también sin cwd); los proyectos de Factory Droid se descubren a partir de las transcripciones JSONL en `~/.factory/sessions//*.jsonl` y se agrupan por cwd; los proyectos de Devin desde su base de datos SQLite en `~/.local/share/devin/cli/sessions.db` (agrupados por el `working_directory` de cada sesión); los proyectos de Antigravity desde las transcripciones JSONL en `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` y agrupados por cwd; y los proyectos de Goose desde su base de datos SQLite en `~/.local/share/goose/sessions/sessions.db` (agrupados por el `working_dir` de cada sesión). Un proyecto que ha sido utilizado por múltiples CLIs se muestra como una sola fila con todas las insignias correspondientes. Usa el menú desplegable **CLI** sobre la tabla para filtrar por un agente CLI específico; la URL conserva tu selección como `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Lista todos los proyectos de Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity y Goose encontrados en tu máquina. Los proyectos de Claude se descubren desde `~/.claude/projects/` (o la ruta establecida por `CLAUDE_PROJECTS_PATH`); los proyectos de Codex se descubren escaneando cada transcripción en `~/.codex/sessions///
/*.jsonl` y agrupando por el `cwd` registrado en el primer registro de cada sesión; los proyectos de Copilot CLI se descubren escaneando cada `~/.copilot/session-state//workspace.yaml` (configurable mediante `COPILOT_HOME`) y agrupando por su campo `cwd`; los proyectos de Cursor Agent se descubren escaneando los metadatos por sesión en `~/.cursor/agent-sessions//` (configurable mediante `CURSOR_HOME`, con `conversations/` y `sessions/` como alternativas) buscando un escalar `cwd` en `meta.json` / `session.json` / `workspace.yaml`; los proyectos de OpenCode se descubren consultando su base de datos SQLite en `~/.local/share/opencode/opencode.db` mediante `opencode db --format json` (se leen las tablas `session` y `project` y se agrupan por `project_id`); los proyectos de Pi se descubren escaneando transcripciones JSONL por sesión en `~/.pi/agent/sessions//_.jsonl` (configurable mediante `PI_SESSIONS_DIR`) y extrayendo el `cwd` del primer registro de cada sesión; las sesiones de puerta de enlace de Hermes se leen directamente del almacén SQLite de cada perfil — `~/.hermes/state.db` más `~/.hermes/profiles//state.db` (reemplazable mediante `HERMES_HOME`, o `HERMES_DB_PATH` para una sola base de datos) — y se agrupan en proyectos `hermes--` por perfil y `source` (Slack/Telegram/cli/cron — las sesiones de puerta de enlace no tienen cwd); las sesiones de puerta de enlace de OpenClaw se leen desde `~/.openclaw/agents//sessions/*.jsonl` y se agrupan en proyectos `openclaw--` por agente y canal (también sin cwd); los proyectos de Factory Droid se descubren desde las transcripciones JSONL en `~/.factory/sessions//*.jsonl` y se agrupan por cwd; los proyectos de Devin desde su base de datos SQLite en `~/.local/share/devin/cli/sessions.db` (agrupados por el `working_directory` de cada sesión); los proyectos de Antigravity desde las transcripciones JSONL en `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` agrupados por cwd; y los proyectos de Goose desde su base de datos SQLite en `~/.local/share/goose/sessions/sessions.db` (agrupados por el `working_dir` de cada sesión). Un proyecto que haya sido usado por múltiples CLIs se muestra como una sola fila con todas las insignias correspondientes. Usa el menú desplegable **CLI** sobre la tabla para filtrar por un agente CLI específico; la URL preserva tu selección como `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -Hermes y OpenClaw son de ámbito de usuario y no tienen directorio de trabajo para agrupar, por lo que se muestran como un **árbol de carpetas plegable** — el perfil (o agente) en el nivel superior, sus canales debajo — mientras que todos los CLIs basados en cwd permanecen como filas planas. Las filas de carpetas acumulan el recuento de sesiones y la actividad más reciente de todo lo que contienen; las carpetas plegadas se recuerdan entre visitas, y una búsqueda por palabras clave expande lo que coincida. +Hermes y OpenClaw tienen alcance de usuario y no tienen directorio de trabajo para agrupar, por lo que se muestran como un **árbol de carpetas plegable** — perfil (o agente) en el nivel superior, sus canales debajo — mientras que cada CLI basado en cwd sigue siendo una fila plana. Las filas de carpeta acumulan el recuento de sesiones y la actividad más reciente de todo lo que contienen; las carpetas plegadas se recuerdan entre visitas y una búsqueda por palabra clave expande lo que coincida. Cada proyecto muestra: - Nombre del proyecto (derivado de la ruta de la carpeta) -- Una insignia de CLI — `Claude Code` (naranja), `OpenAI Codex` (morado), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (ámbar), `Pi` (rosa) y/o `Hermes` (índigo) +- Una insignia CLI — `Claude Code` (naranja), `OpenAI Codex` (morado), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (ámbar), `Pi` (rosa) y/o `Hermes` (índigo) - Fecha de la actividad de sesión más reciente Haz clic en un proyecto para ver sus sesiones. @@ -43,50 +43,50 @@ Lista todas las sesiones dentro de un proyecto. Cada sesión muestra: - Número de llamadas a herramientas - Recuento de actividad de hooks (políticas que se activaron) -Usa el filtro de rango de fechas y la búsqueda por ID de sesión para acotar la lista. Las sesiones están paginadas. +Usa el filtro de rango de fechas y la búsqueda por ID de sesión para reducir la lista. Las sesiones están paginadas. -Haz clic en una sesión para abrir el visor de sesiones. +Haz clic en una sesión para abrir el visor de sesión. -### Visor de sesiones +### Visor de sesión -El visor de sesiones responde la pregunta clave para agentes autónomos: ¿qué hizo el agente y se mantuvo en el camino correcto? Una insignia de CLI junto al encabezado indica si la sesión es una transcripción de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity o Goose. Muestra una línea de tiempo de todo lo que ocurrió en una sesión: +El visor de sesión responde la pregunta clave sobre los agentes autónomos: ¿qué hizo el agente y se mantuvo en el camino correcto? Una insignia CLI junto al encabezado indica si la sesión es una transcripción de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity o Goose. Muestra una línea de tiempo de todo lo que ocurrió en una sesión: -- **Mensajes** - Las respuestas de texto de Claude y los prompts del usuario -- **Llamadas a herramientas** - Cada herramienta que Claude invocó, con su entrada y salida -- **Actividad de políticas** - Para cada llamada a herramienta, qué políticas se activaron y qué decisión devolvieron +- **Mensajes** — Respuestas de texto de Claude y prompts del usuario +- **Llamadas a herramientas** — Cada herramienta que Claude invocó, con su entrada y salida +- **Actividad de políticas** — Para cada llamada a herramienta, qué políticas se activaron y qué decisión devolvieron -La barra de estadísticas en la parte superior muestra la duración de la sesión, el total de llamadas a herramientas y un resumen de las decisiones de los hooks (recuentos de allow / deny / instruct). +La barra de estadísticas en la parte superior muestra la duración de la sesión, el total de llamadas a herramientas y un resumen de las decisiones de hooks (recuentos de allow / deny / instruct). -Haz clic en el botón **Download Logs** para exportar la sesión. Para sesiones de Claude Code, Codex, Copilot, Cursor y Pi obtienes la transcripción JSONL original en disco byte a byte; para OpenCode (cuyas sesiones viven en SQLite, no en disco) obtienes un documento JSON que refleja las tablas subyacentes `session` / `messages` / `parts`. +Haz clic en el botón **Download Logs** para exportar la sesión. Para las sesiones de Claude Code, Codex, Copilot, Cursor y Pi obtienes la transcripción JSONL original en disco byte por byte; para OpenCode (cuyas sesiones viven en SQLite, no en disco) obtienes un documento JSON que refleja las tablas subyacentes `session` / `messages` / `parts`. -### Audit +### Auditoría -Un informe con personalidad sobre cómo se ha comportado realmente tu agente a lo largo de sesiones pasadas. Ejecuta el mismo escaneo que el CLI `failproofai audit` pero lo muestra como un póster compartible de pantalla completa + cuatro secciones adicionales: +Un informe con personalidad propia sobre cómo se ha estado comportando realmente tu agente a lo largo de sesiones pasadas. Ejecuta el mismo escaneo que el CLI `failproofai audit` pero lo muestra como un póster en pantalla única compartible + cuatro secciones debajo del pliegue: -1. **Póster** — ocupa el primer viewport. Región de captura PNG autónoma con el logotipo de failproof_ai + etiqueta de auditoría · índice de arquetipo (`№ NN of 08`) + fecha de auditoría · puntuación numérica (0–100) + píldora de rango percentil (`top 15%`) · el nombre del arquetipo (uno de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + tira de 3 palabras clave · línea de rareza `// only N% of agents are this archetype` · mosaico de símbolo de 8×8 píxeles · pie de página `audit yours → failproof.ai`. Tres botones de compartir están justo fuera del área de captura: `post your archetype` (X intent), `share on linkedin`, `download poster`. La captura se realiza mediante `html-to-image` para que el PNG coincida con el renderizado en pantalla píxel a píxel (bordes discontinuos, máscara de logo SVG, degradados, métricas de fuente — todo preservado). -2. **Fortalezas** — lista de filas con ✓ de comportamientos que tu agente ya hace bien, derivados de los datos de auditoría en vivo (tasa de llamadas a herramientas limpia, sin envíos directos a main, cero filtraciones de credenciales, cero tormentas de reintentos) — cada una aparece solo cuando la política relevante tiene un historial limpio en la ventana de auditoría. -3. **Peculiaridades** — tabla de lo que se escapó, ordenado por severidad: `when · what slipped + the policy that would've caught it · severity pill · seen`, donde la recurrencia muestra `new` (una vez), `N× seen` (2–9 veces) o `recurring` (10+). -4. **Cómo mejorar** — lista de filas, una por política prescrita: nombre de la política en blanco, descripción de una línea, comando de instalación + botón de copiar a la derecha. El encabezado de la sección muestra `enable all N → projected · ` (la puntuación que alcanzarías con todas las correcciones aplicadas), y su botón `[install all]` copia el comando combinado `failproofai policy add a b c …` para cada política prescrita. -5. **Vuelve mejor** — dos tarjetas lado a lado. Izquierda: establece un recordatorio (selector de cadencia `3d` / `7d` / `14d` / `30d`; persiste mediante `/api/auth/reminder` una vez autenticado). Derecha: desbloquea ventajas de failproof — `invite a friend` abre un modal que acepta una lista separada por comas/espacios/saltos de línea de correos electrónicos de amigos (máximo 10 por envío), los envía mediante POST a `/api/audit/invite`, que los reenvía al `POST /v0/invite` del api-server. El api-server envía un correo electrónico por destinatario desde `invite@failproof.ai` con el remitente en Cc y `Reply-To` configurado, para que el destinatario vea quién lo invitó y el remitente reciba una copia en su bandeja de entrada. Los usuarios anónimos son redirigidos primero a través del `AuthDialog` para que el correo del remitente sea conocido antes de que salgan las invitaciones. El cumplimiento de derechos/ventajas es un seguimiento pendiente. +1. **Póster** — ocupa el primer viewport. Región de captura PNG autónoma con el logotipo de failproof_ai + etiqueta de auditoría · índice de arquetipo (`№ NN de 08`) + fecha de auditoría · puntuación numérica (0–100) + píldora de rango percentil (`top 15%`) · el nombre del arquetipo (uno de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + tira de 3 palabras clave · línea de rareza `// solo el N% de los agentes son este arquetipo` · ficha de símbolo de píxeles 8×8 · pie de página `audit yours → failproof.ai`. Tres botones de compartir están justo fuera del cuadro de captura: `post your archetype` (intención X), `share on linkedin`, `download poster`. La captura se realiza a través de `html-to-image` para que el PNG coincida pixel a pixel con la representación en pantalla (bordes discontinuos, máscara de logo SVG, degradados, métricas de fuente — todo preservado). +2. **Fortalezas** — lista de filas con ✓ tranquilo sobre comportamientos que tu agente ya hace bien, derivados de los datos de auditoría en vivo (tasa de llamadas a herramientas limpias, sin pushes directos a main, cero filtraciones de credenciales, cero tormentas de reintento) — cada uno aparece solo cuando la política relevante tiene un historial limpio en la ventana de auditoría. +3. **Quirks** — tabla de lo que se escapó, ordenado por gravedad: `cuándo · qué se escapó + la política que lo habría detectado · píldora de gravedad · visto`, donde la recurrencia se lee `new` (una vez), `N× seen` (2–9 veces) o `recurring` (10+). +4. **Cómo mejorar** — lista de filas tranquila, una por política prescrita: nombre de política en blanco, descripción de una línea, comando de instalación + botón de copiar a la derecha. El encabezado de la sección dice `enable all N → projected · ` (la puntuación que alcanzarías con todas las correcciones aplicadas), y su botón `[install all]` copia el comando combinado `failproofai policy add a b c …` para cada política prescrita. +5. **Vuelve mejor** — dos tarjetas lado a lado. Izquierda: establecer un recordatorio (selector de cadencia `3d` / `7d` / `14d` / `30d`; persiste a través de `/api/auth/reminder` una vez autenticado). Derecha: desbloquear ventajas de failproof — `invite a friend` abre un modal que acepta una lista separada por comas/espacios/saltos de línea de correos electrónicos de amigos (máximo 10 por envío), los publica en `/api/audit/invite`, que los reenvía al `POST /v0/invite` del servidor de API. El servidor de API envía un correo electrónico por destinatario desde `invite@failproof.ai` con el remitente en Cc y `Reply-To` configurado, para que el destinatario vea quién los invitó y el remitente reciba una copia en su bandeja de entrada. Los usuarios anónimos son dirigidos primero a través del `AuthDialog` para que el correo electrónico del remitente sea conocido antes de enviar las invitaciones. El cumplimiento de derechos/ventajas es una tarea pendiente. -Impulsado por el runtime de `failproofai audit` — consulta [Audit CLI](/es/cli/audit) para el motor de escaneo subyacente, los flags compatibles y los invariantes de caché por transcripción. El dashboard almacena en caché el último resultado en `~/.failproofai/audit-dashboard.json` (modo `0600`, una sola ranura, las nuevas ejecuciones sobreescriben) para que las revisitas sean instantáneas; **tanto la caché por transcripción como la caché del resultado completo se rechazan al leerlas una vez que tienen más de 7 días**, por lo que el dashboard nunca sirve silenciosamente un resultado de una semana — pasado el TTL, `/audit` cae a su estado vacío y solicita una nueva ejecución. Al hacer clic en `[ re-audit now ]` cerca de la parte inferior del informe se envía un POST a `/api/audit/run` con `noCache: true` — la re-auditoría omite la caché por transcripción y vuelve a escanear cada transcripción desde cero en lugar de devolver silenciosamente el resultado en caché — y el dashboard consulta `/api/audit/status` a 1 Hz hasta que la ejecución finaliza; una barra de progreso rosa pegajosa se fija en la parte superior del viewport durante la ejecución con un temporizador transcurrido, y el nuevo resultado reemplaza al anterior en el lugar cuando tiene éxito (sin recarga de página completa; una re-auditoría fallida deja el informe anterior intacto). En caso de fallo, la barra se vuelve roja con texto basado en el `RerunError.kind` (`timeout` / `network` / `post_failed`). El estado vacío (sin caché o caducada) y el estado de cero sesiones (caché existe pero el escaneo no encontró transcripciones) se muestran por separado. +Impulsado por el runtime de `failproofai audit` — consulta [CLI de Auditoría](/es/cli/audit) para el motor de escaneo subyacente, los flags compatibles y los invariantes de caché por transcripción. El dashboard almacena en caché el último resultado en `~/.failproofai/audit-dashboard.json` (modo `0600`, ranura única, las nuevas ejecuciones sobrescriben) para que las revisitas sean instantáneas; **tanto la caché por transcripción como la de resultado completo se rechazan al leer una vez que superan los 7 días de antigüedad**, por lo que el dashboard nunca sirve silenciosamente un resultado de una semana — pasada la TTL, `/audit` cae al estado vacío y solicita una nueva ejecución. Hacer clic en `[ re-audit now ]` cerca de la parte inferior del informe publica `/api/audit/run` con `noCache: true` — la re-auditoría omite la caché por transcripción y vuelve a escanear cada transcripción desde cero en lugar de devolver silenciosamente el resultado en caché — y el dashboard sondea `/api/audit/status` a 1Hz hasta que la ejecución termina; una barra de progreso rosa fija se ancla en la parte superior del viewport durante la ejecución con un temporizador transcurrido, y el resultado actualizado reemplaza al anterior en su lugar al completarse con éxito (sin recarga de página completa; una re-auditoría fallida deja el informe anterior intacto). En caso de error, la barra se vuelve roja con texto clave basado en `RerunError.kind` (`timeout` / `network` / `post_failed`). El estado vacío (sin caché o expirado) y el estado de cero sesiones (la caché existe pero el escaneo no encontró transcripciones) se muestran por separado. ### Políticas -Una página con dos pestañas para gestionar políticas y revisar la actividad. +Una página de dos pestañas para gestionar políticas y revisar la actividad. - - - Selección múltiple de qué CLIs de agentes protege failproofai desde un solo panel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi y Hermes tienen una fila con el estado de instalación (`Active` / `Detected` / `Inactive`), la ruta de configuración de ámbito de usuario y un acento de color de marca. Marca o desmarca los CLIs que deseas y haz clic en `Apply changes` para instalar/desinstalar la diferencia en un solo paso. Los CLIs cuyo binario se detecta en PATH se marcan previamente. + + - Selección múltiple de qué CLIs de agentes protege failproofai desde un único panel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi y Hermes tienen cada uno una fila con estado de instalación (`Active` / `Detected` / `Inactive`), la ruta de configuración de alcance de usuario y un acento de color de marca. Marca o desmarca los CLIs que quieras y haz clic en `Apply changes` para instalar/desinstalar la diferencia en un solo paso. Los CLIs cuyo binario se detecta en PATH están marcados previamente. - Activa o desactiva políticas individuales con un solo clic (escribe en `~/.failproofai/policies-config.json` — compartido entre todos los CLIs instalados) - - Expande una política para configurar sus parámetros (para políticas que soportan `policyParams`) - - Establece una ruta personalizada para el archivo de políticas + - Expande una política para configurar sus parámetros (para políticas que admiten `policyParams`) + - Establece una ruta de archivo de políticas personalizadas - - - Historial paginado completo de cada evento de hook que se ha activado en todas las sesiones - - Filtra por decisión, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nombre de política o ID de sesión - - Cada fila muestra: marca de tiempo, nombre de política, decisión, insignia de CLI (naranja = Claude Code, morado = OpenAI Codex, azul = GitHub Copilot, esmeralda = Cursor Agent, ámbar = OpenCode, rosa = Pi, índigo = Hermes, verde azulado = OpenClaw, rosa intenso = Factory Droid, violeta = Devin, cian = Antigravity, lima = Goose), nombre de herramienta, ID de sesión y el motivo de las decisiones deny/instruct - - Haz clic en un ID de sesión para abrir su transcripción — el visor detecta automáticamente qué CLI activó el hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) y muestra la insignia de CLI correspondiente en el encabezado + + - Historial completo paginado de cada evento de hook que se ha activado en todas las sesiones + - Filtrar por decisión, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nombre de política o ID de sesión + - Cada fila muestra: marca de tiempo, nombre de política, decisión, insignia CLI (naranja = Claude Code, morado = OpenAI Codex, azul = GitHub Copilot, esmeralda = Cursor Agent, ámbar = OpenCode, rosa = Pi, índigo = Hermes, verde azulado = OpenClaw, rosa pálido = Factory Droid, violeta = Devin, cian = Antigravity, lima = Goose), nombre de herramienta, ID de sesión y el motivo de las decisiones deny/instruct + - Haz clic en un ID de sesión para abrir su transcripción — el visor detecta automáticamente qué CLI activó el hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) y muestra la insignia CLI correspondiente en el encabezado @@ -94,7 +94,7 @@ Una página con dos pestañas para gestionar políticas y revisar la actividad. ## Actualización automática -El dashboard tiene un interruptor de actualización automática en la navegación superior. Cuando está habilitado, la página actual se actualiza periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Es esencial para monitorear sesiones de agentes autónomos de larga duración. +El dashboard tiene un interruptor de actualización automática en la navegación superior. Cuando está activado, la página actual se actualiza periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Es esencial para monitorear sesiones de agentes autónomos de larga duración. --- @@ -112,7 +112,7 @@ Valores válidos: `policies`, `projects`, `audit`. ## Configurar la ruta de proyectos -De forma predeterminada, el dashboard lee desde el directorio estándar de proyectos de Claude Code. Reemplázalo para configuraciones personalizadas: +De forma predeterminada, el dashboard lee desde el directorio estándar de proyectos de Claude Code. Anúlalo para configuraciones personalizadas: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,15 +120,15 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Acceder desde un host que no sea localhost +## Acceso desde un host que no es localhost -Al ejecutar el dashboard en **modo dev** (`npm run dev`) y acceder a él desde un hostname distinto de `localhost` — por ejemplo, un dominio personalizado, una IP remota o una URL tunelizada — es posible que veas una advertencia como: +Cuando se ejecuta el dashboard en **modo de desarrollo** (`npm run dev`) y se accede desde un hostname que no es `localhost` — por ejemplo, un dominio personalizado, una IP remota o una URL tunelizada — es posible que veas una advertencia como: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Esto es Next.js bloqueando el acceso cross-origin a su websocket HMR (hot module reload), que es una función exclusiva del modo dev. Para permitir tu host, usa el flag `--allowed-origins`: +Esto es Next.js bloqueando el acceso de origen cruzado a su websocket HMR (recarga en caliente de módulos), que es una función exclusiva del modo de desarrollo. Para permitir tu host, usa el flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -147,5 +147,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Esto solo aplica al modo dev. Al ejecutar `failproofai` (modo producción), no hay websocket HMR ni problema de recursos dev cross-origin. +Esto solo aplica al modo de desarrollo. Cuando se ejecuta `failproofai` (modo de producción), no hay websocket HMR ni problema de recurso de desarrollo de origen cruzado. \ No newline at end of file diff --git a/docs/es/examples.mdx b/docs/es/examples.mdx index 2e2daea8..8bc01e37 100644 --- a/docs/es/examples.mdx +++ b/docs/es/examples.mdx @@ -4,7 +4,7 @@ description: "Cómo configurar hooks para Claude Code y el Agents SDK" icon: book-open --- -Ejemplos listos para usar en escenarios comunes. Cada uno muestra cómo instalar y qué esperar. +Ejemplos listos para usar en escenarios comunes. Cada uno muestra cómo instalarlo y qué esperar. --- @@ -55,8 +55,8 @@ Si estás desarrollando con el [Agents SDK](https://docs.anthropic.com/en/docs/a Pasa comandos de hook al crear el proceso de tu agente. Los hooks se activan de la misma manera que en Claude Code — mediante JSON por stdin/stdout: ```bash - failproofai --hook PreToolUse # se llama antes de cada herramienta - failproofai --hook PostToolUse # se llama después de cada herramienta + failproofai --hook PreToolUse # called before each tool + failproofai --hook PostToolUse # called after each tool ``` @@ -98,13 +98,13 @@ Qué hace esto: - `block-sudo` — bloquea todos los comandos `sudo` - `block-rm-rf` — bloquea la eliminación recursiva de archivos - `block-force-push` — bloquea `git push --force` -- `block-curl-pipe-sh` — bloquea la ejecución de scripts remotos canalizados al shell +- `block-curl-pipe-sh` — bloquea el piping de scripts remotos a la shell --- ## Prevenir la filtración de secretos -Impide que los agentes vean o filtren credenciales en la salida de las herramientas. +Evita que los agentes vean o filtren credenciales en la salida de las herramientas. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens @@ -142,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // nunca bloquear al agente si Slack no está disponible + // never block the agent if Slack is unreachable } return allow(); @@ -182,7 +182,7 @@ customPolicies.add({ --- -## Exigir pruebas antes de hacer commit +## Exigir pruebas antes de los commits Recuerda a los agentes que ejecuten las pruebas antes de hacer commit. @@ -206,9 +206,9 @@ customPolicies.add({ --- -## Proteger un repositorio de producción +## Bloquear un repositorio de producción -Guarda una configuración a nivel de proyecto para que todos los desarrolladores de tu equipo apliquen las mismas políticas. +Haz commit de una configuración a nivel de proyecto para que todos los desarrolladores de tu equipo obtengan las mismas políticas. Crea `.failproofai/policies-config.json` en tu repositorio: @@ -238,13 +238,13 @@ git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -Todos los miembros del equipo que tengan failproofai instalado aplicarán estas reglas automáticamente. +Todos los miembros del equipo que tengan failproofai instalado adoptarán estas reglas automáticamente. --- -## Construir un estándar de calidad para toda la organización con políticas de convención +## Construir un estándar de calidad organizacional con políticas de convención -La configuración más efectiva: guarda `.failproofai/policies/` en tu repositorio con políticas adaptadas a tu proyecto. Todos los miembros del equipo las obtienen automáticamente — sin comandos de instalación, sin cambios de configuración. +La configuración más impactante: haz commit de `.failproofai/policies/` en tu repositorio con políticas adaptadas a tu proyecto. Todos los miembros del equipo las obtienen automáticamente — sin comandos de instalación, sin cambios de configuración. @@ -256,8 +256,8 @@ La configuración más efectiva: guarda `.failproofai/policies/` en tu repositor // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Imponer el gestor de paquetes preferido del equipo - // (o habilitar la política integrada prefer-package-manager en su lugar) + // Enforce your team's preferred package manager + // (or enable the built-in prefer-package-manager policy instead) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, @@ -269,7 +269,7 @@ La configuración más efectiva: guarda `.failproofai/policies/` en tu repositor }, }); - // Recordar al agente que ejecute las pruebas antes de hacer commit + // Remind the agent to run tests before committing customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, @@ -283,14 +283,14 @@ La configuración más efectiva: guarda `.failproofai/policies/` en tu repositor }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - A medida que tu equipo encuentre nuevos tipos de fallos, añade políticas y publícalas. Todos reciben la actualización en su próximo `git pull`. Estas políticas se convierten en un estándar de calidad vivo que crece con tu equipo. + A medida que tu equipo encuentre nuevos tipos de fallos, añade políticas y haz push. Todos recibirán la actualización en su próximo `git pull`. Estas políticas se convierten en un estándar de calidad vivo que crece junto con tu equipo. @@ -302,6 +302,6 @@ El directorio [`examples/`](https://github.com/failproofai/failproofai/tree/main | Archivo | Qué muestra | |---------|-------------| -| `policies-basic.js` | Políticas iniciales: bloquear escrituras en producción, force-push y scripts canalizados | +| `policies-basic.js` | Políticas básicas — bloquear escrituras en producción, force-push y scripts con pipe | | `policies-notification.js` | Alertas de Slack para notificaciones de inactividad y fin de sesión | -| `policies-advanced/index.js` | Importaciones transitivas, hooks asíncronos, limpieza de salida en PostToolUse y manejo del evento Stop | \ No newline at end of file +| `policies-advanced/index.js` | Importaciones transitivas, hooks asíncronos, limpieza de salida en PostToolUse y gestión del evento Stop | \ No newline at end of file diff --git a/docs/es/for-agents.mdx b/docs/es/for-agents.mdx index 5991ff5d..4f62678c 100644 --- a/docs/es/for-agents.mdx +++ b/docs/es/for-agents.mdx @@ -9,21 +9,21 @@ Añade la referencia completa de Failproof AI a tu agente de programación con u npx skills add https://docs.befailproof.ai ``` -`npx skills` detecta qué agentes tienes instalados y añade el skill en el formato correcto para cada uno automáticamente. +`npx skills` detecta qué agentes tienes instalados y añade la skill en el formato correcto para cada uno automáticamente. -## Qué cubre el skill +## Qué cubre la skill | Área | Qué incluye | |------|-------------| -| Políticas | Nombres de políticas integradas, tipos de eventos, parámetros, habilitar/deshabilitar | +| Políticas | Nombres de políticas integradas, tipos de eventos, parámetros, activar/desactivar | | Políticas personalizadas | `customPolicies.add()`, filtros de coincidencia, API `allow`/`deny`/`instruct` | | Objeto de contexto | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configuración | Estructura de `policies-config.json`, fusión de ámbitos, `policyParams` | -| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, ámbitos | -| Panel de control | Visor de sesiones, actividad de políticas, variables de entorno | -| Arquitectura | Flujo del manejador de hooks, códigos de salida, contrato stdin/stdout | +| Configuración | Estructura de `policies-config.json`, fusión de scopes, `policyParams` | +| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes | +| Dashboard | Visor de sesiones, actividad de políticas, variables de entorno | +| Arquitectura | Flujo del hook handler, códigos de salida, contrato stdin/stdout | -## ¿Está completo el skill? +## ¿Está completa la skill? Mintlify genera `llms.txt` a partir de todas las páginas de la navegación. La documentación de Failproof AI cubre la API completa: cada política, opción y ejemplo está incluido. Si encuentras algo que falta, el origen está en `https://docs.befailproof.ai/llms-full.txt`. diff --git a/docs/es/getting-started.mdx b/docs/es/getting-started.mdx index f096c4ef..f0ba3768 100644 --- a/docs/es/getting-started.mdx +++ b/docs/es/getting-started.mdx @@ -7,7 +7,7 @@ icon: rocket ## Requisitos - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (opcional - solo necesario para compilar desde el código fuente) +- **Bun** >= 1.3.0 (opcional, solo necesario para compilar desde el código fuente) --- @@ -31,15 +31,15 @@ bun add -g failproofai - Las políticas son reglas que se ejecutan antes y después de cada llamada a una herramienta del agente. Detectan comandos destructivos, filtraciones de secretos y otros modos de fallo antes de que causen daños. + Las políticas son reglas que se ejecutan antes y después de cada llamada a una herramienta del agente. Detectan comandos destructivos, filtraciones de secretos y otros modos de fallo antes de que causen daño. ```bash failproofai policies --install ``` - Esto escribe entradas de hooks en los CLIs de agentes instalados (el `~/.claude/settings.json` de Claude Code, el `~/.codex/hooks.json` de OpenAI Codex, el `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, el `~/.cursor/hooks.json` de Cursor Agent, el shim de plugin generado por OpenCode en `~/.config/opencode/plugins/failproofai.mjs` más una entrada de registro en el array `plugin` de `~/.config/opencode/opencode.json`, el `~/.pi/agent/settings.json` de Pi, el `~/.hermes/config.yaml` de Hermes, el `~/.openclaw/openclaw.json` de OpenClaw, el `~/.factory/hooks.json` de Factory Droid, el `~/.config/devin/config.json` de Devin CLI, el `~/.gemini/config/hooks.json` de Antigravity CLI, o el directorio de plugins autodescubierto de Goose en `~/.agents/plugins/failproofai/hooks/hooks.json`). Si hay más de uno instalado se te pedirá que elijas; pasa `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (cualquier subconjunto) para omitir el aviso. + Esto escribe entradas de hook en los CLIs de agente instalados (el `~/.claude/settings.json` de Claude Code, el `~/.codex/hooks.json` de OpenAI Codex, el `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, el `~/.cursor/hooks.json` de Cursor Agent, el plugin shim generado por OpenCode en `~/.config/opencode/plugins/failproofai.mjs` junto con una entrada de registro en el array `plugin` de `~/.config/opencode/opencode.json`, el `~/.pi/agent/settings.json` de Pi, el `~/.hermes/config.yaml` de Hermes, el `~/.openclaw/openclaw.json` de OpenClaw, el `~/.factory/hooks.json` de Factory Droid, el `~/.config/devin/config.json` de Devin CLI, el `~/.gemini/config/hooks.json` de Antigravity CLI, o el directorio de plugins autodescubierto de Goose en `~/.agents/plugins/failproofai/hooks/hooks.json`). Si hay más de uno presente, se te pedirá que elijas; pasa `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (cualquier subconjunto) para omitir el aviso. - El soporte para GitHub Copilot CLI, Cursor Agent, OpenCode y Pi está en **beta** — instala con `--cli copilot`, `--cli cursor`, `--cli opencode` o `--cli pi`. Hermes (hermes-agent, una pasarela Slack/Telegram) se instala con ámbito de usuario con `--cli hermes` y es **también** una fuente de auditoría offline. OpenClaw (pasarela openclaw, un asistente multicanal autoalojado) se instala con ámbito de usuario con `--cli openclaw` — la aplicación de políticas se ejecuta a través de sus hooks de plugin en proceso (`before_agent_finalize` es una compuerta real de fin de turno, por lo que los builtins `require-*-before-stop` se aplican) — y es **también** una fuente de auditoría offline. Factory Droid (`droid`) se instala con `--cli factory` (ámbito de usuario y proyecto) y es **también** una fuente de auditoría offline. Devin CLI (`devin`, Cognition) se instala con `--cli devin` (ámbito de usuario y proyecto) y es **también** una fuente de auditoría offline. Antigravity CLI (`agy`) se instala con `--cli antigravity` (ámbito de usuario y proyecto) y es **también** una fuente de auditoría offline. Goose (nombre en clave goose, Block) se instala con `--cli goose` (ámbito de usuario y proyecto) — el instalador simplemente crea un directorio de plugin en `~/.agents/plugins/failproofai/` que Goose autodescubre, y es **también** una fuente de auditoría offline. + La compatibilidad con GitHub Copilot CLI, Cursor Agent, OpenCode y Pi está en **beta** — instala con `--cli copilot`, `--cli cursor`, `--cli opencode` o `--cli pi`. Hermes (hermes-agent, una pasarela Slack/Telegram) se instala en el ámbito de usuario con `--cli hermes` y es **también** una fuente de auditoría sin conexión. OpenClaw (pasarela openclaw, un asistente multicanal autoalojado) se instala en el ámbito de usuario con `--cli openclaw` — la aplicación de reglas funciona a través de sus hooks de plugin en proceso (`before_agent_finalize` es una puerta real de fin de turno, por lo que los builtins `require-*-before-stop` se aplican) — y es **también** una fuente de auditoría sin conexión. Factory Droid (`droid`) se instala con `--cli factory` (ámbito de usuario y proyecto) y es **también** una fuente de auditoría sin conexión. Devin CLI (`devin`, Cognition) se instala con `--cli devin` (ámbito de usuario y proyecto) y es **también** una fuente de auditoría sin conexión. Antigravity CLI (`agy`) se instala con `--cli antigravity` (ámbito de usuario y proyecto) y es **también** una fuente de auditoría sin conexión. Goose (nombre en clave goose, Block) se instala con `--cli goose` (ámbito de usuario y proyecto) — el instalador simplemente crea un directorio de plugin en `~/.agents/plugins/failproofai/` que Goose autodescubre, y es **también** una fuente de auditoría sin conexión. ```bash failproofai policies --install --scope project @@ -62,17 +62,17 @@ bun add -g failproofai failproofai policies ``` - Muestra todas las políticas, si están habilitadas y cualquier parámetro configurado. + Muestra todas las políticas, si están habilitadas y los parámetros configurados. ```bash failproofai ``` - Abre un panel de control local en `http://localhost:8020` donde puedes navegar por las sesiones, inspeccionar llamadas a herramientas y gestionar políticas. + Abre un panel de control local en `http://localhost:8020` donde puedes explorar sesiones, inspeccionar llamadas a herramientas y gestionar políticas. - Inicia Claude Code como de costumbre. Si el agente intenta algo arriesgado, failproofai lo intercepta automáticamente. Déjalo correr sin supervisión y revisa lo que ocurrió en el panel de control. + Inicia Claude Code como de costumbre. Si el agente intenta hacer algo arriesgado, failproofai lo intercepta automáticamente. Déjalo correr sin supervisión y revisa lo ocurrido en el panel de control. @@ -100,9 +100,9 @@ Las políticas se ejecutan en tu proceso local. No se envía nada a un servicio --- -## Configurar políticas de equipo con políticas basadas en convenciones +## Configura políticas de equipo con políticas basadas en convenciones -La forma más rápida de establecer estándares de calidad en todo tu equipo es la convención `.failproofai/policies/`. Coloca archivos de política en este directorio y se cargan automáticamente — sin flags, sin cambios de configuración, sin comandos de instalación. +La forma más rápida de establecer estándares de calidad en tu equipo es la convención `.failproofai/policies/`. Coloca archivos de política en este directorio y se cargan automáticamente — sin flags, sin cambios de configuración, sin comandos de instalación. @@ -136,18 +136,18 @@ La forma más rápida de establecer estándares de calidad en todo tu equipo es }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Cada miembro del equipo que tenga failproofai instalado incorporará estas políticas automáticamente. No se necesita configuración por desarrollador. + Cada miembro del equipo que tenga failproofai instalado adoptará estas políticas automáticamente. No se requiere configuración por desarrollador. -Confirma `.failproofai/policies/` en tu repositorio para que todo el equipo comparta los mismos estándares. A medida que el equipo descubra nuevos modos de fallo, añade políticas y súbelas — todos reciben la actualización en su próximo `git pull`. Con el tiempo, estas políticas se convierten en un estándar de calidad vivo que sigue mejorando. +Haz commit de `.failproofai/policies/` en tu repositorio para que todo el equipo comparta los mismos estándares. A medida que el equipo descubra nuevos modos de fallo, agrega políticas y haz push — todos recibirán la actualización en su próximo `git pull`. Con el tiempo, estas políticas se convierten en un estándar de calidad vivo que no deja de mejorar. --- @@ -158,21 +158,23 @@ Toda la configuración y los registros permanecen en tu máquina: | Ruta | Qué almacena | |------|--------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | Configuración global de políticas | +| `~/.failproofai/policies-config.json` | Configuración global de políticas | +| `~/.failproofai/policies/` | Tus propias políticas — agrega archivos `*-policies.mjs`, sin necesidad de configuración | +| `~/.failproofai/policies/cloud-policies/` | Políticas desplegadas en esta máquina por tu organización | | `~/.failproofai/hook-activity/` | Historial de ejecución de hooks (JSONL paginado) | | `~/.failproofai/logs/` | Registros de depuración para errores de hooks personalizados | -| `.failproofai/policies-config.json` | Configuración por proyecto (confirmada en git) | +| `.failproofai/policies-config.json` | Configuración por proyecto (commiteada) | | `.failproofai/policies-config.local.json` | Anulaciones personales (en gitignore) | --- -## Desinstalación +## Desinstalar ```bash failproofai policies --uninstall ``` -Elimina las entradas de hooks de `~/.claude/settings.json`. Los archivos de configuración en `~/.failproofai/` se conservan. +Elimina las entradas de hook de `~/.claude/settings.json`. Los archivos de configuración en `~/.failproofai/` se conservan. --- @@ -181,7 +183,7 @@ Elimina las entradas de hooks de `~/.claude/settings.json`. Los archivos de conf - Ámbitos y formato del archivo de configuración + Ámbitos y formato de los archivos de configuración @@ -193,7 +195,7 @@ Elimina las entradas de hooks de `~/.claude/settings.json`. Los archivos de conf - Monitorea sesiones y revisa la actividad de las políticas + Supervisa sesiones y revisa la actividad de las políticas \ No newline at end of file diff --git a/docs/es/introduction.mdx b/docs/es/introduction.mdx index aafd134f..f3664b62 100644 --- a/docs/es/introduction.mdx +++ b/docs/es/introduction.mdx @@ -1,36 +1,36 @@ --- title: "Failproof AI" -description: "FailproofAI ofrece a los agentes de IA 39 políticas de fallos integradas que detectan bucles, filtraciones de secretos, llamadas a herramientas destructivas y más, todo en una sola instalación." +description: "FailproofAI proporciona a los agentes de IA 39 políticas de fallo integradas que detectan bucles, filtraciones de secretos, llamadas destructivas a herramientas y más, con una sola instalación." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hooks y políticas para el **manejo de fallos en IA**, **recuperación ante errores** y **fiabilidad de LLM**. Mantén tus agentes de IA estables y funcionando de forma autónoma en **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** y el **Agents SDK**. +Hooks y políticas para **manejo de fallos de IA**, **recuperación de errores** y **fiabilidad de LLM**. Mantén tus agentes de IA fiables y funcionando de forma autónoma en **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** y el **Agents SDK**. -Los agentes de IA fallan de maneras predecibles: ejecutan comandos destructivos, filtran secretos, se desvían de sus tareas, quedan atrapados en bucles o hacen push directamente a main. Sin supervisión, los fallos menores se convierten en interrupciones del servicio, credenciales expuestas y trabajo perdido. +Los agentes de IA fallan de maneras predecibles. Ejecutan comandos destructivos, filtran secretos, se desvían de la tarea, se quedan atascados en bucles o hacen push directamente a main. Sin supervisión, los fallos pequeños se encadenan y provocan interrupciones del servicio, credenciales expuestas y trabajo perdido. -FailproofAI resuelve esto mediante **políticas**. Estas reglas se enganchan en cada llamada a herramientas del agente para **detectar fallos**, **mitigarlos** (bloquear, instruir, sanitizar) y **alertarte** cuando algo requiere atención. Un panel de control local te permite revisar cada llamada a herramienta, cada fallo del agente y cada acción de recuperación. +FailproofAI resuelve esto mediante **políticas**. Estas reglas se enganchan en cada llamada a herramienta del agente para **detectar fallos**, **mitigarlos** (bloquear, instruir, sanitizar) y **alertarte** cuando algo requiere atención. Un panel local te permite revisar después cada llamada a herramienta, fallo del agente y acción de recuperación. -Las transcripciones y la evaluación de políticas permanecen en tu máquina. Los datos solo se envían cuando utilizas explícitamente una función en línea, como recordatorios de auditoría autenticados o invitaciones. +Las transcripciones y la evaluación de políticas se quedan en tu máquina. Los datos solo se envían cuando utilizas explícitamente una función en línea, como recordatorios de auditoría autenticados o invitaciones. -## Primeros pasos +## Comenzar - Bloquea comandos destructivos, previene la filtración de secretos, mantiene a los agentes dentro de los límites del proyecto y mucho más. Todo listo desde el primer momento. + Bloquea comandos destructivos, previene la filtración de secretos, mantiene a los agentes dentro de los límites del proyecto y más. Todo listo para usar. - Escribe tus propias reglas en JavaScript con una API sencilla de allow / deny / instruct. + Escribe tus propias reglas en JavaScript con una sencilla API de allow / deny / instruct. - Descubre qué hicieron tus agentes mientras no estabas. Explora sesiones, inspecciona llamadas a herramientas y revisa dónde se activaron las políticas. + Descubre qué hicieron tus agentes mientras no estabas. Navega por sesiones, inspecciona llamadas a herramientas y revisa dónde se activaron las políticas. - Ajusta cualquier política sin tocar el código. Define listas de permisos, ramas protegidas o umbrales por proyecto o de forma global. + Ajusta cualquier política sin escribir código. Define listas de permitidos, ramas protegidas o umbrales por proyecto o de forma global. diff --git a/docs/es/package-aliases.mdx b/docs/es/package-aliases.mdx index cae53c1b..9547ae28 100644 --- a/docs/es/package-aliases.mdx +++ b/docs/es/package-aliases.mdx @@ -1,6 +1,6 @@ --- -title: Aliases de Paquetes -description: "Aliases registrados para prevención de typosquatting y cómo funcionan" +title: Alias de Paquetes +description: "Alias registrados para prevención de typosquatting y cómo funcionan" icon: copy --- @@ -16,46 +16,46 @@ bun add -g failproofai --- -## Por qué controlamos los nombres de alias +## Por qué somos dueños de los nombres de alias -El typosquatting es un ataque común a la cadena de suministro en el que un actor malicioso registra un nombre de paquete que difiere en una sola tecla de uno popular. Los usuarios desprevenidos que escriben mal el comando de instalación terminan ejecutando código controlado por el atacante con acceso total al sistema — exactamente el tipo de amenaza que Failproof AI está diseñado para combatir. +El typosquatting es un ataque común a la cadena de suministro donde un actor malicioso registra un nombre de paquete que difiere en una sola tecla de un paquete popular. Los usuarios que cometen un error tipográfico al ejecutar el comando de instalación terminan ejecutando código controlado por el atacante con acceso total al sistema — exactamente el tipo de amenaza que Failproof AI está diseñado para defender. -Para eliminar esta superficie de ataque, **registramos de forma preventiva todas las variantes de escritura y formato comunes** de `failproofai` en npm. Ninguno de estos nombres puede ser registrado por un tercero. Cada uno es un proxy ligero que instala y delega al paquete real `failproofai`. +Para eliminar esta superficie de ataque, **registramos de forma preventiva todas las variantes tipográficas comunes y de formato** de `failproofai` en npm. Ninguno de estos nombres puede ser registrado por terceros. Cada uno es un proxy ligero que instala y delega al paquete real `failproofai`. --- -## Aliases registrados +## Alias registrados -**Variantes de formato** — distintas formas de escribir "failproof ai": +**Variantes de formato** — diferentes formas de escribir «failproof ai»: | Paquete | Estado | |---------|--------| | `failproof` | ✅ Publicado | -| `failproof-ai` | ⏳ Pendiente de aprobación por npm | -| `fail-proof-ai` | ⏳ Pendiente de aprobación por npm | -| `failproof_ai` | ⏳ Pendiente de aprobación por npm | -| `fail_proof_ai` | ⏳ Pendiente de aprobación por npm | -| `fail-proofai` | ⏳ Pendiente de aprobación por npm | +| `failproof-ai` | ⏳ Pendiente de aprobación de npm | +| `fail-proof-ai` | ⏳ Pendiente de aprobación de npm | +| `failproof_ai` | ⏳ Pendiente de aprobación de npm | +| `fail_proof_ai` | ⏳ Pendiente de aprobación de npm | +| `fail-proofai` | ⏳ Pendiente de aprobación de npm | -**Errores tipográficos `failprof*`** — falta una `o` en "proof": +**Errores tipográficos con `failprof*`** — falta una `o` en «proof»: | Paquete | Estado | |---------|--------| | `failprof` | ✅ Publicado | | `failprof-ai` | ✅ Publicado | -| `failprofai` | ⏳ Pendiente de aprobación por npm | -| `fail-prof-ai` | ⏳ Pendiente de aprobación por npm | -| `failprof_ai` | ⏳ Pendiente de aprobación por npm | +| `failprofai` | ⏳ Pendiente de aprobación de npm | +| `fail-prof-ai` | ⏳ Pendiente de aprobación de npm | +| `failprof_ai` | ⏳ Pendiente de aprobación de npm | -**Errores tipográficos `faliproof*`** — `a` e `i` transpuestas: +**Errores tipográficos con `faliproof*`** — `a` e `i` transpuestas: | Paquete | Estado | |---------|--------| | `faliproof` | ✅ Publicado | | `faliproof-ai` | ✅ Publicado | -| `faliproofai` | ⏳ Pendiente de aprobación por npm | +| `faliproofai` | ⏳ Pendiente de aprobación de npm | -> **¿Por qué están pendientes?** La política anti-spam de npm bloquea nombres que, tras eliminar la puntuación y aplicar comprobaciones de similitud, se normalizan a la misma cadena que un paquete existente. Hemos contactado con el soporte de npm para reservar estos nombres con fines de protección contra squatting. Se activarán una vez aprobados. +> **¿Por qué están pendientes?** La política de prevención de spam de npm bloquea nombres que, tras eliminar la puntuación y aplicar comprobaciones de similitud, se normalizan a la misma cadena que un paquete existente. Hemos contactado con el soporte de npm para reservar estos nombres con fines anti-typosquatting. Se activarán una vez aprobados. Puedes verificar que cualquier alias publicado nos pertenece: @@ -66,17 +66,17 @@ npm info failproof --- -## Cómo funcionan los aliases +## Cómo funcionan los alias Cada paquete alias: -1. Incluye `failproofai` como dependencia — de modo que el paquete real se instala y su binario queda disponible -2. Expone un binario con su propio nombre (por ejemplo, `failprof-ai`) que redirige todos los argumentos al binario `failproofai` +1. Declara `failproofai` como dependencia — de modo que el paquete real se instala y su binario queda disponible +2. Expone un binario con su propio nombre (p. ej. `failprof-ai`) que redirige todos los argumentos al binario `failproofai` -El proxy es un script de Node de dos líneas; no contiene lógica adicional, ni llamadas de red, ni recopilación de datos más allá de lo que hace `failproofai` por sí mismo. +El proxy es un script de Node de dos líneas; no contiene lógica adicional, no realiza llamadas de red ni recopila datos más allá de lo que hace `failproofai` por sí mismo. --- -## Si encuentras un nombre que nos falta +## Si encuentras un nombre que nos hemos perdido Abre un issue en [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) y lo registraremos. \ No newline at end of file diff --git a/docs/es/testing.mdx b/docs/es/testing.mdx index e87bbede..e50b9911 100644 --- a/docs/es/testing.mdx +++ b/docs/es/testing.mdx @@ -1,14 +1,14 @@ --- -title: Pruebas -description: "Pruebas unitarias, pruebas E2E y utilidades de prueba" +title: Testing +description: "Pruebas unitarias, pruebas E2E y helpers de prueba" icon: flask-vial --- -failproofai cuenta con dos suites de pruebas: **pruebas unitarias** (rápidas, con mocks) y **pruebas end-to-end** (invocaciones reales de subprocesos). +failproofai tiene dos suites de pruebas: **pruebas unitarias** (rápidas, con mocks) y **pruebas end-to-end** (invocaciones reales de subprocesos). --- -## Ejecución de pruebas +## Ejecutar pruebas ```bash # Ejecutar todas las pruebas unitarias una vez @@ -23,7 +23,7 @@ bun run test:e2e # Verificar tipos sin compilar bunx tsc --noEmit -# Linting +# Lint bun run lint ``` @@ -40,7 +40,7 @@ __tests__/ hooks-config.test.ts # Carga de configuración y fusión de scopes policy-evaluator.test.ts # Inyección de parámetros y orden de evaluación custom-hooks-registry.test.ts # Registro globalThis: add/get/clear - custom-hooks-loader.test.ts # Cargador ESM, importaciones transitivas, manejo de errores + custom-hooks-loader.test.ts # Cargador ESM, imports transitivos, manejo de errores manager.test.ts # Operaciones install/remove/list components/ sessions-list.test.tsx # Componente de lista de sesiones @@ -110,7 +110,7 @@ describe("block-sudo", () => { ## Pruebas end-to-end -Las pruebas E2E invocan el binario real de `failproofai` como subproceso, envían un payload JSON por stdin y verifican la salida en stdout junto con el código de salida. Esto prueba la integración completa que utiliza Claude Code. +Las pruebas E2E invocan el binario real de `failproofai` como subproceso, envían un payload JSON por stdin y verifican la salida de stdout junto con el código de salida. Esto prueba el flujo de integración completo que utiliza Claude Code. ### Configuración @@ -126,33 +126,33 @@ Luego ejecuta las pruebas: bun run test:e2e ``` -Reconstruye `dist/` cada vez que modifiques la API pública de hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` o `src/hooks/policy-types.ts`). +Recompila `dist/` cada vez que modifiques la API pública de hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` o `src/hooks/policy-types.ts`). ### Estructura de las pruebas E2E ```text __tests__/e2e/ helpers/ - hook-runner.ts # Lanza el binario, envía el JSON del payload, captura código de salida + stdout + stderr + hook-runner.ts # Inicia el binario, envía el payload JSON, captura código de salida + stdout + stderr fixture-env.ts # Directorios temporales aislados por prueba con archivos de configuración - payloads.ts # Fábricas de payloads precisos para cada tipo de evento de Claude + payloads.ts # Fábricas de payloads precisas (según Claude) para cada tipo de evento hooks/ builtin-policies.e2e.test.ts # Cada política builtin con subproceso real custom-hooks.e2e.test.ts # Carga y evaluación de hooks personalizados - config-scopes.e2e.test.ts # Fusión de configuración entre scopes: project/local/global + config-scopes.e2e.test.ts # Fusión de configuración entre scopes project/local/global policy-params.e2e.test.ts # Inyección de parámetros para cada política parametrizada ``` ### Uso de los helpers E2E -**`FixtureEnv`** - entorno aislado por prueba: +**`FixtureEnv`** — entorno aislado por prueba: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); // env.cwd - directorio temporal; pásalo como payload.cwd para cargar .failproofai/policies-config.json -// env.home - directorio home aislado; evita que se filtre el ~/.failproofai real +// env.home - directorio home aislado; evita filtraciones de ~/.failproofai real env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -164,7 +164,7 @@ env.writeConfig({ `createFixtureEnv()` registra la limpieza con `afterEach` automáticamente. -**`runHook`** - invoca el binario: +**`runHook`** — invocar el binario: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - fábricas de payloads listas para usar: +**`Payloads`** — fábricas de payload listas para usar: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -234,10 +234,10 @@ describe("block-rm-rf (E2E)", () => { ### Formatos de respuesta E2E | Decisión | Código de salida | stdout | -|----------|-----------------|--------| +|----------|------------------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Instruct (distinto de Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Instruct (no-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | | Stop instruct | `2` | stdout vacío; motivo en stderr | | Allow | `0` | cadena vacía | @@ -245,11 +245,11 @@ describe("block-rm-rf (E2E)", () => { Las pruebas E2E usan `vitest.config.e2e.mts` con: -- `environment: "node"` - no se necesitan globales de navegador -- `pool: "forks"` - aislamiento real de procesos (las pruebas lanzan subprocesos) -- `testTimeout: 20_000` - 20s por prueba (arranque del binario + evaluación del hook) +- `environment: "node"` — no se necesitan globales del navegador +- `pool: "forks"` — aislamiento real de procesos (las pruebas lanzan subprocesos) +- `testTimeout: 20_000` — 20 s por prueba (inicio del binario + evaluación del hook) -El pool `forks` es importante: los workers basados en hilos comparten `globalThis`, lo que puede interferir con las pruebas que lanzan subprocesos. Los forks basados en procesos evitan este problema. +El pool `forks` es importante: los workers basados en hilos comparten `globalThis`, lo que puede interferir con pruebas que lanzan subprocesos. Los forks basados en procesos evitan este problema. --- @@ -257,4 +257,4 @@ El pool `forks` es importante: los workers basados en hilos comparten `globalThi La ejecución completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) debe pasar antes de hacer merge. La suite E2E se ejecuta como un job de CI independiente en paralelo. -Consulta [Contributing](../CONTRIBUTING.md) para ver el checklist completo previo al merge. \ No newline at end of file +Consulta [Contributing](../CONTRIBUTING.md) para ver la lista completa de verificaciones previas al merge. \ No newline at end of file diff --git a/docs/fr/agenteye/alerts.mdx b/docs/fr/agenteye/alerts.mdx index 0f4ffa6d..edf22ef3 100644 --- a/docs/fr/agenteye/alerts.mdx +++ b/docs/fr/agenteye/alerts.mdx @@ -1,33 +1,33 @@ --- title: "Alertes" -description: "Soyez informé dès qu'un seuil est franchi, sur le canal déjà utilisé par votre équipe, plutôt que de l'apprendre d'un client." +description: "Soyez informé dès qu'un seuil est franchi, sur le canal que votre équipe utilise déjà, plutôt que de l'apprendre d'un client." --- -Soyez informé dès qu'un seuil est franchi, sur le canal déjà utilisé par votre équipe, plutôt que de l'apprendre d'un client. Définissez une règle une fois, et l'observabilité Failproof AI la vérifie selon un planning, puis vous alerte par e-mail, Slack, webhook ou directement dans le tableau de bord. +Soyez informé dès qu'un seuil est franchi, sur le canal que votre équipe utilise déjà, plutôt que de l'apprendre d'un client. Définissez une règle une seule fois et l'observabilité Failproof AI la vérifie selon un planning, puis vous alerte par e-mail, Slack, webhook ou directement dans le tableau de bord. -![La page Alertes : une grille de cartes de règles d'alerte, chacune affichant son déclencheur, sa fenêtre d'évaluation, ses canaux et un badge de sévérité info, avertissement ou critique](/agenteye/images/alerts.png) +![La page Alertes : une grille de cartes de règles d'alerte, affichant chacune son déclencheur, sa fenêtre d'évaluation, ses canaux et un badge de sévérité info, avertissement ou critique](/agenteye/images/alerts.png) *Toutes les règles d'alerte en un coup d'œil : ce qu'elles surveillent, à quelle fréquence, où elles notifient et leur niveau d'urgence.* -## Soyez alerté des problèmes avant vos utilisateurs +## Soyez alerté avant vos utilisateurs -Arrêtez de rafraîchir un tableau de bord dans l'espoir de détecter une régression. Configurez une alerte dès qu'il y a un signal que vous voudriez connaître même quand personne ne surveille, et recevez-la là où vous êtes déjà : +Arrêtez de rafraîchir un tableau de bord en espérant détecter une régression. Configurez une alerte dès qu'il existe un signal dont vous souhaiteriez être informé même quand personne ne surveille, et faites-le arriver là où vous êtes déjà : -- **E-mail**, pour toutes les personnes concernées. +- **E-mail**, à toute personne concernée. - **Slack**, un message enrichi avec un bouton qui mène directement à l'incident. -- **Webhook**, un POST JSON pour PagerDuty, Opsgenie ou votre propre endpoint, avec une signature optionnelle pour que le récepteur puisse le valider. -- **Dans le tableau de bord**, discret par conception, pour quand vous affinez une règle et ne souhaitez pas encore envoyer de notification. +- **Webhook**, un POST JSON pour PagerDuty, Opsgenie ou votre propre endpoint, avec une signature optionnelle pour que le destinataire puisse lui faire confiance. +- **Dans le tableau de bord**, discret par conception, pour quand vous affinez une règle sans vouloir encore notifier qui que ce soit. -Combinez n'importe lesquels sur une même règle, et la sévérité (info, avertissement ou critique) est transmise avec l'alerte pour que les plus urgentes soient clairement identifiées. +Combinez plusieurs canaux sur une seule règle ; la sévérité (info, avertissement ou critique) est incluse pour que les alertes urgentes paraissent urgentes. ## Créez la règle via un formulaire, pas du JSON -Vous décrivez ce que signifie « en erreur » dans un formulaire, et l'observabilité Failproof AI génère la règle sous-jacente pour vous. La spec JSON n'est que ce que ce formulaire produit en coulisses, vous pouvez la lire pour comprendre une règle, mais vous la saisissez rarement manuellement. +Vous décrivez ce que signifie « défaillant » dans un formulaire, et l'observabilité Failproof AI génère la règle sous-jacente pour vous. La spec JSON n'est que ce que ce formulaire produit en coulisses, vous pouvez la lire pour comprendre une règle, mais vous la saisissez rarement manuellement. -![Le formulaire de nouvelle alerte : nom et description, un interrupteur d'activation et un sélecteur de déclencheur proposant seuil de métrique, SQL personnalisé, score d'évaluation, évaluation composée et conditions par événement](/agenteye/images/alert-new.png) +![Le formulaire de nouvelle alerte : nom et description, un interrupteur d'activation, et un sélecteur de déclencheur proposant seuil de métrique, SQL personnalisé, score d'évaluation, évaluation composée et conditions par événement](/agenteye/images/alert-new.png) *Choisissez un déclencheur et le formulaire affiche les bons champs ; Enregistrer écrit la règle.* -Le chemin classique est rapide : nommez-la, choisissez un **déclencheur** (ce qu'il faut surveiller), définissez le **seuil et la fenêtre** (quelle gravité, sur quelle durée), associez au moins un **canal**, puis **Enregistrez** et cliquez sur **Tester** pour déclencher une notification synthétique et vérifier que chaque destination est bien configurée. En coulisses, cela produit une petite spec comme : +Le parcours standard est rapide : nommez la règle, choisissez un **déclencheur** (ce à surveiller), définissez le **seuil et la fenêtre** (à quel point, sur quelle durée), associez au moins un **canal**, puis **Enregistrez** et cliquez sur **Tester** pour déclencher une notification synthétique et confirmer que chaque destination est bien configurée. En coulisses, cela produit une petite spec du type : ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } @@ -38,26 +38,26 @@ Vous n'êtes pas limité à un seul type de signal. Choisissez le déclencheur q | Déclencheur | Se déclenche quand | |---|---| | **Seuil de métrique** | une métrique prédéfinie (taux d'erreur, latence p95 ou p99, nombre d'événements ou d'erreurs, dépenses en tokens) franchit votre seuil sur une fenêtre | -| **SQL personnalisé** | votre propre requête en lecture seule retourne une ligne, ou une valeur calculée franchit un seuil | -| **Score d'évaluation** | la moyenne d'un score d'évaluateur (par exemple, les hallucinations) franchit un seuil | -| **Évaluation composée** | plusieurs vérifications de scores se combinent avec une logique any, all ou au-moins-N, pour détecter une régression qui n'apparaît qu'à travers plusieurs scores | -| **Par événement** | un événement correspondant survient : un agent spécifique, un type d'erreur spécifique ou une sous-chaîne de message | +| **SQL personnalisé** | votre propre requête en lecture seule renvoie une ligne, ou une valeur calculée franchit un seuil | +| **Score d'évaluation** | la moyenne du score d'un évaluateur (par exemple, hallucination) franchit un seuil | +| **Évaluation composée** | plusieurs vérifications de score se combinent avec une logique any, all ou au-moins-N, pour détecter une régression qui n'apparaît que sur plusieurs scores | +| **Par événement** | un seul événement correspondant survient : un agent spécifique, un type d'erreur spécifique ou une sous-chaîne de message | -Vous êtes déjà en train d'examiner une défaillance sur la [page Erreurs](/fr/agenteye/error-tracking) ? Chaque ligne dispose d'un bouton **+ alerte** qui ouvre ce même formulaire pré-rempli pour détecter exactement cette défaillance à l'avenir, de sorte que l'incident que vous venez de traiter devient celui qui vous alertera la prochaine fois. +Vous consultez déjà une défaillance sur la [page Erreurs](/fr/agenteye/error-tracking) ? Chaque ligne dispose d'un bouton **+ alerte** qui ouvre ce même formulaire pré-rempli pour détecter exactement cette défaillance à nouveau, afin que l'incident que vous venez de trier soit celui qui vous alertera la prochaine fois. -**Où le trouver :** Les alertes se trouvent à `//alerts`. La création, la modification, la suppression et le test des règles nécessitent **`alerts:write`** ; `alerts:read` suffit pour consulter. Le sélecteur de destinataires liste les membres de votre organisation par nom, vous pouvez donc notifier une personne sans quitter le formulaire. +**Où le trouver :** Les alertes se trouvent à `//alerts`. La création, la modification, la suppression et le test des règles nécessitent **`alerts:write`** ; `alerts:read` suffit pour la consultation. Le sélecteur de destinataires liste les membres de votre organisation par nom, vous pouvez donc notifier une personne sans quitter le formulaire. -## Ne me notifier que lorsque c'est réel +## Ne m'alertez que quand c'est réel -Une mauvaise mesure ne devrait pas vous réveiller. Le filtre anti-bruit **M sur N** contrôle combien des dernières vérifications doivent échouer avant que l'alerte vous notifie réellement. Réglez-le sur **3 sur 5** et la règle ne se déclenche qu'après avoir dépassé le seuil lors de trois des cinq dernières vérifications, évitant ainsi les fausses alarmes d'un signal instable ; laissez-le sur la valeur par défaut **1 sur 1** pour déclencher dès le premier dépassement. Vous choisissez également la fréquence d'exécution de la règle, parmi les préréglages 1m, 5m, 15m et 1h, adaptée à la rapidité réelle d'évolution du signal. +Une seule mauvaise mesure ne devrait pas vous réveiller. Le filtre anti-bruit **M sur N** contrôle combien des dernières vérifications doivent échouer avant que l'alerte vous notifie réellement. Réglez-le sur **3 sur 5** et la règle se déclenche uniquement après avoir franchi le seuil trois fois sur ses cinq dernières vérifications, afin qu'un signal instable cesse de déclencher de fausses alarmes ; laissez-le à la valeur par défaut **1 sur 1** pour se déclencher dès le premier dépassement. Vous choisissez également la fréquence d'exécution de la règle, parmi des préréglages de 1m, 5m, 15m et 1h, adaptés à la vitesse réelle d'évolution du signal. ## Ce qui se passe quand une alerte se déclenche -Un dépassement ouvre un **incident** et notifie vos canaux une fois. À partir de là, votre équipe le reconnaît, lui assigne un responsable, en discute et le résout, le tout dans un journal clair et attribué. Ce workflow de triage a son propre espace : voir [Incidents](/fr/agenteye/incidents). +Un dépassement ouvre un **incident** et notifie vos canaux une seule fois. Votre équipe peut ensuite le prendre en charge, l'assigner à un responsable, en discuter et le résoudre, le tout dans un historique clair et attribué. Ce flux de triage a son propre espace : voir [Incidents](/fr/agenteye/incidents). ## Voir aussi -- [Incidents](/fr/agenteye/incidents) : suivez une alerte déclenchée de l'ouverture à l'acquittement jusqu'à la résolution. -- [Suivi des erreurs](/fr/agenteye/error-tracking) : regroupez les défaillances des agents et transformez-en une en alerte en un clic. -- [Tableaux de bord](/fr/agenteye/dashboards) : consultez les tableaux partagés d'où proviennent les seuils que vous alertez. +- [Incidents](/fr/agenteye/incidents) : suivez une alerte déclenchée de l'ouverture à la prise en charge jusqu'à la résolution. +- [Suivi des erreurs](/fr/agenteye/error-tracking) : regroupez les défaillances des agents et promouvez-en une en alerte en un clic. +- [Tableaux de bord](/fr/agenteye/dashboards) : consultez les tableaux partagés dont proviennent les seuils sur lesquels vous alertez. - [CLI et agents](/fr/agenteye/cli-and-agents) : créez des alertes et acquittez des incidents depuis votre terminal, ou intégrez-les dans votre CI. \ No newline at end of file diff --git a/docs/fr/agenteye/api-keys.mdx b/docs/fr/agenteye/api-keys.mdx index 5fe70198..e7739f65 100644 --- a/docs/fr/agenteye/api-keys.mdx +++ b/docs/fr/agenteye/api-keys.mdx @@ -1,169 +1,169 @@ --- title: "Clés API" -description: "Les clés API contrôlent qui et ce qui peut atteindre votre serveur d'observabilité Failproof AI, afin qu'un collecteur puisse envoyer des événements sans jamais obtenir de droits de lecture ou d'administration." +description: "Les clés API contrôlent qui et quoi peut accéder à votre serveur Failproof AI Observability, afin qu'un collecteur puisse envoyer des événements sans jamais obtenir de droits de lecture ou d'administration." --- -Les clés API contrôlent qui et ce qui peut atteindre votre serveur d'observabilité Failproof AI, afin qu'un collecteur puisse envoyer des événements sans jamais obtenir de droits de lecture ou d'administration. Chaque clé porte une ou plusieurs permissions, et chaque permission conditionne l'accès à des routes spécifiques du serveur ; vous n'accordez que celles dont un service a besoin. La plupart des déploiements créent seulement trois types de clés. +Les clés API contrôlent qui et quoi peut accéder à votre serveur Failproof AI Observability, afin qu'un collecteur puisse envoyer des événements sans jamais obtenir de droits de lecture ou d'administration. Chaque clé porte une ou plusieurs permissions, et chaque permission contrôle des routes spécifiques du serveur ; vous n'accordez que celles dont un service a besoin. La plupart des déploiements créent seulement trois types de clés. ## Les 3 clés dont la plupart des déploiements ont besoin | Clé | Permissions | Utilisée par | |---|---|---| | Clé collecteur | `events:add` | L'`agenteye-collector` sur chaque machine agent, pour envoyer des événements. | -| Clé de lecture tableau de bord | `events:read`, `keys:read` | Un opérateur en lecture seule ou une intégration qui interroge les données sans les modifier. | -| Clé admin d'amorçage | toutes les permissions | L'opérateur qui démarre l'instance pour la première fois (et le tableau de bord). Initialisée depuis la variable d'environnement `ADMIN_KEY`. Voir [Clé admin d'amorçage](#bootstrap-admin-key). | +| Clé lecture tableau de bord | `events:read`, `keys:read` | Un opérateur en lecture seule ou une intégration qui interroge les données sans les modifier. | +| Clé admin bootstrap | toutes les permissions | L'opérateur qui démarre l'instance pour la première fois (et le tableau de bord). Initialisée depuis la variable d'environnement `ADMIN_KEY`. Voir [Clé admin bootstrap](#bootstrap-admin-key). | -Commencez ici. Ne consultez le catalogue complet des permissions ci-dessous que lorsque vous avez besoin d'une clé personnalisée à portée restreinte. Voir aussi [Disposition recommandée des clés](#recommended-key-layout) et [Créer des clés](#creating-keys). +Commencez par là. N'explorez le catalogue complet des permissions ci-dessous que si vous avez besoin d'une clé à portée personnalisée et plus restreinte. Voir aussi [Disposition de clés recommandée](#recommended-key-layout) et [Création de clés](#creating-keys). --- ## Permissions -Le serveur applique un catalogue fixe de permissions ; chacune conditionne l'accès à des routes HTTP spécifiques. Une **clé admin** les possède toutes ; une clé à portée restreinte possède le sous-ensemble que vous accordez à la création. Les chaînes de permission inconnues sont rejetées lors de la création d'une clé. +Le serveur applique un catalogue fixe de permissions ; chacune contrôle des routes HTTP spécifiques. Une **clé admin** les détient toutes ; une clé à portée restreinte ne détient que le sous-ensemble que vous lui accordez à la création. Les chaînes de permission inconnues sont rejetées lors de la création d'une clé. -> **Remarque :** Deux permissions valides sont réservées aux humains/tableau de bord et ne peuvent pas être accordées à une clé API : `orgs:admin` (administration de l'instance, réservée aux opérateurs) et `keys:update`. Toute requête vers `POST /keys` ou `PATCH /keys/:id` qui tente d'accorder l'une ou l'autre est rejetée avec HTTP 422. Voir la ligne `keys:update` ci-dessous pour comprendre pourquoi une clé porteuse peut créer des clés mais jamais les modifier. +> **Remarque :** Deux permissions valides sont réservées aux humains/tableaux de bord et ne peuvent pas être accordées à une clé API : `orgs:admin` (administration de l'instance, réservée aux opérateurs) et `keys:update`. Une requête vers `POST /keys` ou `PATCH /keys/:id` tentant d'accorder l'une ou l'autre est rejetée avec HTTP 422. Voir la ligne `keys:update` ci-dessous pour comprendre pourquoi une clé bearer peut créer des clés mais jamais les modifier. ### Ingestion et interrogation d'événements -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| -| `events:add` | `POST /events` | Ingérer des lots d'événements depuis un collecteur. La seule permission dont un collecteur a besoin. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Interroger les événements, lister les environnements connus, lister les identifiants de modèles présents dans les données (utilisés par la vue Modèles et les filtres de modèles), calculer l'agrégat de latence qui alimente la carte thermique / bande de percentiles, et exporter une session en JSONL. Les endpoints de facettes partagés de la barre de filtres `GET /events/environments` et `GET /events/agent_ids` sont accessibles avec **soit** `events:read` **soit** `evaluations:read`, de sorte que la page des sessions (conditionnée par `evaluations:read`) réutilise la même facette par organisation. `GET /events/models` n'en fait pas partie : elle requiert `events:read`, donc un principal ne détenant que `evaluations:read` reçoit un 403. | +| `events:add` | `POST /events` | Ingérer des lots d'événements depuis un collecteur. C'est la seule permission dont un collecteur a besoin. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Interroger les événements, lister les environnements connus, lister les identifiants de modèles observés dans les données (utilisés par la vue Modèles et les filtres de modèles), calculer l'agrégat de latence qui alimente la carte thermique/bande de percentile, et exporter une session en JSONL. Les endpoints de facettes de la barre de filtres partagée `GET /events/environments` et `GET /events/agent_ids` sont accessibles avec **soit** `events:read` **soit** `evaluations:read`, de sorte que la page des sessions (contrôlée par `evaluations:read`) réutilise la même facette par organisation. `GET /events/models` n'en fait pas partie : il requiert `events:read`, donc un principal ne détenant que `evaluations:read` reçoit une erreur 403. | ### Sessions et évaluations -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Lister les sessions, lire les résultats d'évaluation, l'état de santé agrégé des évaluations utilisé par les tableaux de bord, et l'état de la file d'attente du worker d'évaluation. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Lister les sessions, lire les résultats d'évaluation, l'état agrégé de santé des évaluations utilisé par les tableaux de bord, et l'état de la file d'attente du worker d'évaluation. | | `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Mettre manuellement en file d'attente une réévaluation pour une session terminée. | ### Tableaux de bord -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Lister les tableaux de bord, en charger un, et lire ses tuiles. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Créer et modifier des tableaux de bord, ajouter / modifier / supprimer des tuiles, et réorganiser la grille de tuiles. | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Lister les tableaux de bord, en charger un et lire ses tuiles. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Créer et modifier des tableaux de bord, ajouter/modifier/supprimer des tuiles, et réorganiser la grille de tuiles. | | `dashboards:delete` | `DELETE /dashboards/:id` | Supprimer un tableau de bord entier (la suppression au niveau des tuiles relève de `dashboards:write`). | -### Requêtes enregistrées (compositeur SQL) +### Requêtes sauvegardées (compositeur SQL) -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Lister les requêtes enregistrées, en charger une, et inspecter le schéma en lecture seule ciblé par le compositeur. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | Créer et modifier des requêtes enregistrées. Le SQL est toujours acheminé via le même rôle en lecture seule et les mêmes vérifications SQL protégées qu'un appel `queries:run`. | -| `queries:delete` | `DELETE /queries/:id` | Supprimer une requête enregistrée. | -| `queries:run` | `POST /queries/run` | Exécuter du SQL enregistré ou ad hoc contre le rôle en lecture seule utilisé par le compositeur. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Lister les requêtes sauvegardées, en charger une et inspecter le schéma en lecture seule ciblé par le compositeur. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | Créer et modifier des requêtes sauvegardées. Le SQL est toujours acheminé via le même rôle en lecture seule et les mêmes vérifications SQL surveillées qu'un appel `queries:run`. | +| `queries:delete` | `DELETE /queries/:id` | Supprimer une requête sauvegardée. | +| `queries:run` | `POST /queries/run` | Exécuter du SQL sauvegardé ou ad hoc via le rôle en lecture seule utilisé par le compositeur. | ### Assistant IA -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Interagir avec l'assistant IA et gérer ses propres conversations (privées). Requise sur l'**utilisateur** pour voir le volet assistant ; la propre clé de l'assistant est `dashboard-assistant` et est initialisée séparément (voir ci-dessous). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Discuter avec l'assistant IA et gérer vos propres conversations (privées). Requise pour l'**utilisateur** afin d'afficher le dock de l'assistant ; la clé propre à l'assistant est `dashboard-assistant` et est initialisée séparément (voir ci-dessous). | ### Clés API -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| | `keys:create` | `POST /keys` | Créer une nouvelle clé API à portée restreinte. N'accorde **pas** la modification des permissions d'une clé existante (c'est `keys:update`). | | `keys:read` | `GET /keys` | Lister les clés existantes. Les secrets ne sont jamais retournés par cet endpoint. | -| `keys:update` | `PATCH /keys/:id` | Modifier les permissions d'une clé existante. Permission **réservée aux humains/tableau de bord** ; elle ne peut pas être assignée à une clé API (une clé porteuse peut créer des clés mais jamais les modifier). | +| `keys:update` | `PATCH /keys/:id` | Modifier les permissions d'une clé existante. Permission **réservée aux humains/tableaux de bord** ; elle ne peut pas être assignée à une clé API (une clé bearer peut créer des clés mais jamais les modifier). | | `keys:disable` | `POST /keys/:id/disable` | Révoquer une clé. Les clés protégées (`admin`, `dashboard-assistant`) ne peuvent pas être désactivées ; faites-les pivoter via la variable d'environnement + redémarrage. | | `keys:regenerate` | `POST /keys/:id/regenerate` | Régénérer le secret d'une clé. Les clés protégées ne peuvent pas être régénérées via cette route. | ### Utilisateurs du tableau de bord -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | Inviter un nouvel utilisateur du tableau de bord (envoie un e-mail + connexion par mot de passe à usage unique (OTP)) et lire l'ensemble de permissions par défaut configuré dans le tableau de bord utilisé pour pré-remplir le formulaire d'invitation. | -| `users:read` | `GET /users`, `GET /users/:id` | Lister les utilisateurs et charger un enregistrement utilisateur individuel. | -| `users:update` | `PUT /users/:id` | Modifier les permissions d'un utilisateur. Les mises à jour envoient un e-mail de notification de changement de permissions à l'utilisateur concerné et prennent effet à sa prochaine requête, sans reconnexion nécessaire. | +| `users:create` | `POST /users`, `GET /users/defaults` | Inviter un nouvel utilisateur du tableau de bord (envoie un e-mail + connexion par code à usage unique (OTP)) et lire l'ensemble de permissions par défaut configuré dans le tableau de bord, utilisé pour pré-remplir le formulaire d'invitation. | +| `users:read` | `GET /users`, `GET /users/:id` | Lister les utilisateurs et charger un enregistrement d'utilisateur individuel. | +| `users:update` | `PUT /users/:id` | Modifier les permissions d'un utilisateur. Les mises à jour envoient un e-mail de notification de changement de permissions à l'utilisateur concerné et prennent effet à sa prochaine requête ; aucune reconnexion n'est requise. | | `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Désactiver un utilisateur (révoque ses sessions immédiatement) et réactiver un utilisateur précédemment désactivé. | -Ces permissions alimentent la page **Utilisateurs** du tableau de bord, où les portées accordées à chaque membre s'affichent sous forme de puces : +Ces permissions alimentent la page **Utilisateurs** du tableau de bord, où les portées accordées à chaque membre sont affichées sous forme de badges : ![La page Utilisateurs : une carte par utilisateur du tableau de bord avec son e-mail, les permissions accordées et les contrôles de modification/désactivation](/agenteye/images/users.png) ### Paramètres opérationnels -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| | `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Afficher les paramètres opérationnels gérés par le tableau de bord et leurs métadonnées ; lister les remplacements de fenêtre de contexte par modèle ; et résoudre la fenêtre effective pour un modèle. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Modifier les paramètres opérationnels et ajouter, modifier ou supprimer les remplacements de fenêtre de contexte par modèle. Les modifications s'appliquent aux nouveaux événements sans redémarrage du serveur. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Modifier les paramètres opérationnels et ajouter, modifier ou supprimer des remplacements de fenêtre de contexte par modèle. Les modifications s'appliquent aux nouveaux événements sans redémarrer le serveur. | ![La page Paramètres : paramètres opérationnels gérés par le tableau de bord tels que les connexions autorisées et les durées de vie des sessions/OTP, modifiables sans redémarrage](/agenteye/images/settings.png) ### Alertes et incidents -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| | `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Afficher les définitions d'alertes configurées. | | `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Créer, modifier, supprimer et tester des définitions d'alertes. | | `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Afficher les incidents et leur historique de triage. | -| `incidents:write` | `POST /alerts/:id/incidents` | Ouvrir manuellement un incident sur une alerte existante. | +| `incidents:write` | `POST /alerts/:id/incidents` | Ouvrir manuellement un incident contre une alerte existante. | | `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Acquitter, assigner, résoudre et commenter des incidents. | ### Audits -| Permission | Routes HTTP | Ce qu'elle autorise | +| Permission | Routes HTTP | Ce qu'elle permet | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Afficher les définitions d'audit, l'historique d'exécution et les résultats. | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Afficher les définitions d'audit, l'historique des exécutions et les résultats. | | `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Créer, modifier, supprimer et exécuter des audits ; trier les résultats (acquitter / mettre en sourdine / ignorer / résoudre / rouvrir / assigner). | -> **Remarque :** Pour donner à une clé l'accès à la surface d'audit, accordez-lui explicitement `audits:*`. Voir [Notes de mise à jour et de compatibilité ascendante](#upgrade-and-backward-compatibility-notes) pour savoir comment les bénéficiaires existants ont été migrés lors du déploiement des Audits. +> **Remarque :** Pour donner à une clé l'accès à la surface d'audit, accordez-lui `audits:*` explicitement. Voir [Notes de mise à niveau et de compatibilité ascendante](#upgrade-and-backward-compatibility-notes) pour la façon dont les bénéficiaires existants ont été migrés lors du lancement des Audits. -> L'endpoint du sélecteur de destinataires `GET /alerts/recipients` (qui liste les e-mails des membres qu'un éditeur d'alertes peut notifier) est accessible par un détenteur de **soit** `alerts:read` **soit** `alerts:write`, de sorte que les éditeurs d'alertes peuvent remplir le sélecteur sans se voir accorder `users:read`. +> L'endpoint de sélection de destinataires `GET /alerts/recipients` (qui liste les e-mails des membres qu'un éditeur d'alertes peut notifier) est accessible par un détenteur de **soit** `alerts:read` **soit** `alerts:write`, de sorte que les éditeurs d'alertes peuvent remplir le sélecteur sans se voir accorder `users:read`. -> Un lecteur de tableaux de bord a besoin des deux permissions `dashboards:read` (pour charger les vues enregistrées) et `evaluations:read` (les métriques de santé sont calculées à partir des données d'évaluation). Accordez `dashboards:write` pour permettre à un utilisateur de créer ou de modifier des tableaux de bord, et `dashboards:delete` pour les supprimer. +> Un spectateur de tableaux de bord a besoin des **deux** permissions `dashboards:read` (pour charger les vues sauvegardées) et `evaluations:read` (les métriques de santé sont calculées à partir des données d'évaluation). Accordez `dashboards:write` pour permettre à un utilisateur de créer ou modifier des tableaux de bord, et `dashboards:delete` pour les supprimer. -> `/health` et `/auth/*` (demande OTP, vérification OTP, vérification de session, déconnexion) sont non authentifiés par conception ; il s'agit du flux de connexion et de la sonde de disponibilité. `GET /access-granters` nécessite une clé valide mais aucune permission spécifique, de sorte que tout utilisateur connecté peut voir quels administrateurs contacter pour les changements d'accès. +> `/health` et `/auth/*` (demande OTP, vérification OTP, vérification de session, déconnexion) sont non authentifiés par conception ; il s'agit du flux de connexion et de la sonde de disponibilité. `GET /access-granters` requiert une clé valide mais aucune permission spécifique, de sorte que tout utilisateur connecté peut voir quels administrateurs contacter concernant les changements d'accès. --- ## Ensembles de permissions -Les ensembles de permissions vous permettent d'appliquer un rôle nommé au lieu de sélectionner manuellement des tokens individuels à chaque fois. Plutôt que de sélectionner une douzaine de permissions une par une pour chaque nouvel utilisateur du tableau de bord ou clé API, vous choisissez un ensemble, et tous ceux qui y sont assignés bénéficient d'une attribution cohérente et vérifiable. La modification d'un ensemble personnalisé réapplique le nouvel accès à chaque utilisateur qui y est déjà assigné, de sorte qu'un changement de rôle est une seule modification plutôt qu'une mise à jour de chaque membre. +Les ensembles de permissions vous permettent d'appliquer un rôle nommé plutôt que de sélectionner manuellement des tokens individuels à chaque fois. Plutôt que de choisir une douzaine de permissions une par une pour chaque nouvel utilisateur du tableau de bord ou clé API, vous sélectionnez un ensemble, et chacun qui lui est assigné dispose d'un accès cohérent et vérifiable. La modification d'un ensemble personnalisé réapplique le nouvel accès à chaque utilisateur déjà assigné, de sorte qu'un changement de rôle est une seule modification plutôt qu'un balayage de tous les membres. Chaque organisation est initialisée avec trois ensembles intégrés : | Ensemble | Permissions | Destiné à | |---|---|---| | `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Accès en lecture seule sur toutes les surfaces opérationnelles. | -| `standard` | tout ce qui est dans `read-only`, plus `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Lecture seule plus les actions quotidiennes de l'équipe de permanence : exécuter des requêtes, réévaluer des sessions, acquitter des incidents et utiliser l'assistant IA. | +| `standard` | tout ce qui est dans `read-only`, plus `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Lecture seule plus les actions quotidiennes de l'opérateur de service : exécuter des requêtes, réévaluer des sessions, acquitter des incidents et utiliser l'assistant IA. | | `admin` | toutes les permissions assignables | Contrôle total de l'organisation. | -Les trois ensembles intégrés sont **immuables** ; leurs noms ont toujours la même signification, donc `read-only`, `standard` et `admin` peuvent être référencés en toute sécurité dans les politiques et l'onboarding. Un opérateur peut créer des **ensembles personnalisés** supplémentaires pour modéliser des rôles spécifiques à votre organisation (par exemple, un rôle « auteur de tableau de bord » ou un rôle « collecteur uniquement »). +Les trois ensembles intégrés sont **immuables** ; leurs noms signifient toujours la même chose, donc `read-only`, `standard` et `admin` sont sûrs à référencer dans les politiques et l'intégration. Un opérateur peut créer des **ensembles personnalisés** supplémentaires pour modéliser des rôles spécifiques à votre organisation (par exemple, un rôle « auteur de tableau de bord » ou un rôle « collecteur uniquement »). -Les ensembles sont exposés dans le tableau de bord et gérés via l'API sur `GET /permission-sets` (liste, conditionnée par `users:read`) et `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (créer, modifier, supprimer un ensemble personnalisé, conditionné par `settings:write`). La suppression ou la modification d'un ensemble intégré est refusée. +Les ensembles sont exposés dans le tableau de bord et gérés via l'API sur `GET /permission-sets` (liste, contrôlée par `users:read`) et `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (créer, modifier, supprimer un ensemble personnalisé, contrôlés par `settings:write`). La suppression ou modification d'un ensemble intégré est refusée. -L'appartenance à un ensemble est ce qui sous-tend deux autres fonctionnalités : +L'appartenance à un ensemble sous-tend deux autres fonctionnalités : -- **`DEFAULT_USER_PERMISSIONS`** (l'accès présélectionné lorsqu'un administrateur ouvre **+ nouvel utilisateur**) correspond par défaut à l'ensemble `standard`. -- **L'indicateur `--set`** sur `agenteye-orgctl` (gestion des membres opérateurs) démarre un membre à partir d'un ensemble nommé, que vous affinez ensuite avec `--add` / `--remove`. +- **`DEFAULT_USER_PERMISSIONS`** (l'accès présélectionné lorsqu'un admin ouvre **+ nouvel utilisateur**) est défini par défaut sur l'ensemble `standard`. +- **L'indicateur `--set`** sur `agenteye-orgctl` (gestion des membres opérateurs) initialise un membre à partir d'un ensemble nommé, que vous affinez ensuite avec `--add` / `--remove`. -> **Remarque :** Lorsqu'un ensemble inclut une permission non assignable à une clé (par exemple un ensemble personnalisé portant `keys:update`), l'initialisation d'une clé à partir de cet ensemble supprime les tokens non assignables ; le serveur rejetterait sinon la clé avec HTTP 422. Les utilisateurs du tableau de bord ne sont pas soumis à cette restriction. +> **Remarque :** Lorsqu'un ensemble inclut une permission non assignable à une clé (par exemple, un ensemble personnalisé portant `keys:update`), l'initialisation d'une clé depuis cet ensemble supprime les tokens non assignables ; le serveur rejetterait sinon la clé avec HTTP 422. Les utilisateurs du tableau de bord ne sont pas soumis à cette restriction. --- -## Clé admin d'amorçage +## Clé admin bootstrap -La clé admin est l'unique identifiant racine qui permet à un opérateur de démarrer les accès depuis zéro : avec elle, vous pouvez créer toutes les autres clés à portée restreinte, inviter les premiers utilisateurs du tableau de bord et configurer l'instance avant qu'aucune autre clé n'existe. C'est la seule clé que vous ne créez pas via l'API des clés ; elle est provisionnée depuis l'environnement pour que le serveur soit accessible au premier démarrage. +La clé admin est le credential racine unique qui permet à un opérateur de mettre en place les accès depuis zéro : avec elle, vous pouvez créer toutes les autres clés à portée restreinte, inviter les premiers utilisateurs du tableau de bord et configurer l'instance avant qu'aucune autre clé n'existe. C'est la seule clé que vous ne créez pas via l'API des clés ; elle est provisionnée depuis l'environnement afin que le serveur soit accessible dès le premier démarrage. -Définissez la variable d'environnement `ADMIN_KEY` sur le serveur. À chaque démarrage, le serveur insère ou met à jour cette valeur en tant que clé admin avec toutes les permissions. +Définissez la variable d'environnement `ADMIN_KEY` sur le serveur. À chaque démarrage, le serveur upserte cette valeur en tant que clé admin avec toutes les permissions. -Pour la faire pivoter : modifiez `ADMIN_KEY` avec un nouveau secret et redémarrez le serveur. +Pour la faire pivoter : changez `ADMIN_KEY` pour un nouveau secret et redémarrez le serveur. --- -## Portée organisationnelle +## Portée par organisation -**Les organisations elles-mêmes sont créées et gérées hors bande par un opérateur, et non via cette API des clés.** Le cycle de vie des organisations et des membres (créer / renommer / supprimer / purger une organisation ; ajouter / mettre à jour / supprimer un membre) se fait avec l'interface CLI **`agenteye-orgctl`** ; il n'existe ni API HTTP ni bouton de tableau de bord pour cela. Ce qui *reste* inchangé : **les clés API par organisation sont toujours créées dans le tableau de bord (ou via cette API des clés)** par les membres de l'organisation. +**Les organisations elles-mêmes sont créées et gérées hors bande par un opérateur, pas via cette API de clés.** Le cycle de vie des organisations et des membres (créer / renommer / supprimer / purger une organisation ; ajouter / mettre à jour / supprimer un membre) s'effectue avec le CLI **`agenteye-orgctl`** ; il n'existe pas d'API HTTP ni de bouton dans le tableau de bord pour cela. Ce qui *reste* inchangé : **les clés API par organisation sont toujours créées dans le tableau de bord (ou via cette API de clés)** par les membres de l'organisation. -Dans un déploiement multi-organisations, chaque clé créée par un membre d'une organisation (via cette API des clés ou la page **Clés** du tableau de bord) appartient à **une seule organisation** et ne peut lire ou écrire que les données de cette organisation ; l'organisation est inscrite dans la clé à la création et appliquée à chaque requête. Les deux clés d'amorçage constituent la seule exception : la clé `admin` (initialisée depuis `ADMIN_KEY`) et la clé `dashboard-assistant` (initialisée depuis `AGENT_API_KEY`) ont une **portée d'instance** (elles ne portent aucune organisation). Le tableau de bord s'authentifie avec la clé `admin` afin de pouvoir traiter les requêtes par organisation au nom des membres connectés. Les déploiements mono-tenant n'ont pas à se préoccuper de cela ; toutes les clés appartiennent à l'organisation `default` intégrée. +Dans un déploiement multi-organisations, chaque clé créée par un membre d'une organisation (via cette API de clés ou la page **Clés** du tableau de bord) appartient à **une seule organisation** et ne peut lire ou écrire que les données de cette organisation ; l'organisation est horodatée sur la clé à la création et appliquée à chaque requête. Les deux clés bootstrap sont la seule exception : la clé `admin` (initialisée depuis `ADMIN_KEY`) et la clé `dashboard-assistant` (initialisée depuis `AGENT_API_KEY`) ont une **portée d'instance** (elles ne portent aucune organisation). Le tableau de bord s'authentifie avec la clé `admin` afin de pouvoir proxy les requêtes par organisation au nom des membres connectés. Les déploiements mono-tenant n'ont pas à s'en préoccuper ; toutes les clés appartiennent à l'organisation `default` intégrée. --- -## Créer des clés +## Création de clés Utilisez la clé admin (ou toute clé avec la permission `keys:create`) pour créer des clés supplémentaires à portée restreinte. @@ -193,7 +193,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -Lorsque vous créez une clé via l'API HTTP, vous fournissez vous-même la valeur `key` ; choisissez un secret fort et stockez-le de manière sécurisée. (Le tableau de bord fonctionne différemment : il génère un secret fort pour vous et le montre une seule fois à la création ; voir [Gestion des clés dans le tableau de bord](#key-management-in-the-dashboard).) La réponse confirme que la clé a été créée : +Lorsque vous créez une clé via l'API HTTP, vous fournissez vous-même la valeur `key` ; choisissez un secret robuste et stockez-le de manière sécurisée. (Le tableau de bord fonctionne différemment : il génère un secret robuste pour vous et l'affiche une seule fois à la création ; voir [Gestion des clés dans le tableau de bord](#key-management-in-the-dashboard).) La réponse confirme que la clé a été créée : ```json { @@ -206,18 +206,18 @@ Lorsque vous créez une clé via l'API HTTP, vous fournissez vous-même la valeu --- -## Lister les clés +## Listage des clés ```bash curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -Les secrets des clés ne sont pas retournés dans les réponses de liste, seulement les identifiants, noms et permissions. +Les secrets des clés ne sont pas retournés dans les réponses de liste ; seuls les identifiants, noms et permissions le sont. --- -## Désactiver une clé +## Désactivation d'une clé La désactivation révoque l'accès immédiatement sans supprimer l'enregistrement de la clé. @@ -228,7 +228,7 @@ curl -s -X POST http://your-server/keys//disable \ --- -## Régénérer une clé +## Régénération d'une clé Génère un nouveau secret pour une clé existante. L'ancien secret est invalidé immédiatement. @@ -243,38 +243,38 @@ La réponse inclut le nouveau secret en clair, **affiché une seule fois**. ## Gestion des clés dans le tableau de bord -La page **Clés** du tableau de bord fournit une interface utilisateur pour toutes les opérations ci-dessus. Vous avez besoin d'une clé avec la permission `keys:read` pour afficher la liste, et `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` pour les actions de création / modification / désactivation / régénération respectivement. La modification des permissions d'une clé (`keys:update`) est distincte de sa création (`keys:create`), ce qui vous permet d'accorder à un opérateur la possibilité de créer des clés sans pouvoir modifier la portée des clés existantes, ou inversement. La clé admin couvre tout cela. +La page **Clés** du tableau de bord fournit une interface utilisateur pour toutes les opérations ci-dessus. Vous avez besoin d'une clé avec la permission `keys:read` pour afficher la liste, et de `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` pour les actions de création / modification / désactivation / régénération respectivement. La modification des permissions d'une clé (`keys:update`) est distincte de sa création (`keys:create`), ce qui vous permet d'accorder à un opérateur la capacité de créer des clés sans lui accorder la possibilité de modifier la portée des clés existantes, ou vice versa. La clé admin couvre l'ensemble de ces actions. -Lorsque vous créez une clé depuis le tableau de bord, vous ne fournissez pas le secret ; le tableau de bord génère un secret fort pour vous et l'affiche **une seule fois** à la création. Copiez-le immédiatement et stockez-le de manière sécurisée ; il ne sera plus jamais affiché, exactement comme lors d'une régénération. Vous pouvez toujours choisir les permissions de la clé directement, ou les initialiser depuis un ensemble de permissions (voir ci-dessous). +Lorsque vous créez une clé depuis le tableau de bord, vous ne fournissez pas le secret ; le tableau de bord génère un secret robuste pour vous et l'affiche **une seule fois** à la création. Copiez-le immédiatement et stockez-le de manière sécurisée ; il ne sera jamais affiché à nouveau, exactement comme lors d'une régénération. Vous pouvez toujours choisir les permissions de la clé directement, ou les initialiser depuis un ensemble de permissions (voir ci-dessous). -![La page Clés API : une carte par clé affichant son nom, les permissions accordées et la date de création, avec les actions de régénération et de désactivation ; les clés protégées comme `admin` sont marquées](/agenteye/images/api-keys.png) +![La page Clés API : une carte par clé affichant son nom, les permissions accordées et la date de création, avec des actions de régénération et de désactivation ; les clés protégées comme `admin` sont signalées](/agenteye/images/api-keys.png) --- -## Disposition recommandée des clés +## Disposition de clés recommandée | Clé | Permissions | Utilisée par | |---|---|---| -| `admin` (amorçage via la variable d'environnement `ADMIN_KEY`) | toutes | Ops/configuration, et le tableau de bord (s'authentifie avec `ADMIN_KEY`, traite les requêtes des utilisateurs avec des vérifications de permissions) | +| `admin` (bootstrap via la variable d'env `ADMIN_KEY`) | toutes | Ops/configuration, et le tableau de bord (s'authentifie avec `ADMIN_KEY`, proxy les requêtes utilisateur avec vérification des permissions) | | Clé collecteur par hôte | `events:add` | Collecteur sur chaque machine agent | -| `dashboard-assistant` (amorçage via la variable d'environnement `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistant IA, initialisé automatiquement, **protégé** ; ne peut pas être modifié via l'API | +| `dashboard-assistant` (bootstrap via la variable d'env `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistant IA, initialisé automatiquement, **protégé** ; ne peut pas être modifié via l'API | | Clé de télémétrie de l'assistant (optionnelle) | `events:add` | Auto-instrumentation de l'assistant IA, si activée | -> **Remarque :** La clé de l'assistant est **initialisée automatiquement** par le serveur depuis la variable d'environnement `AGENT_API_KEY` (le même secret que l'agent présente comme `AGENTEYE_API_KEY`) ; il n'y a pas d'étape manuelle de création de clé ni de clé admin impliquée. Ses permissions sont figées dans le code source afin que la portée ne puisse pas être élargie par une mauvaise configuration : lecture sur les événements / évaluations / tableaux de bord, plus écriture sur les tableaux de bord et lecture / écriture / exécution des requêtes pour le flux de création « Demander à l'IA d'écrire une requête ». Tout SQL passe toujours par le même rôle en lecture seule et le même chemin SQL protégé qu'une requête écrite par un utilisateur, donc cela élargit la *surface de création*, pas la surface des données ; les opérations destructives (`queries:delete`, `dashboards:delete`) restent délibérément absentes de la clé de l'assistant. Comme la clé `admin`, elle est **protégée** : elle ne peut pas être désactivée ou régénérée via l'API des clés, seulement renouvelée en modifiant `AGENT_API_KEY` et en redémarrant. Les *utilisateurs* du tableau de bord ont en outre besoin de la permission `agent:use` pour voir et utiliser l'assistant. Si vous activez l'auto-instrumentation, donnez à l'assistant une clé séparée avec uniquement `events:add`. +> **Remarque :** La clé de l'assistant est **initialisée automatiquement** par le serveur depuis la variable d'env `AGENT_API_KEY` (le même secret que l'agent présente en tant que `AGENTEYE_API_KEY`) ; il n'y a pas d'étape manuelle de création de clé et aucune clé admin n'est impliquée. Ses permissions sont fixées dans le code source afin que la portée ne puisse pas être élargie par une mauvaise configuration : lecture sur les événements / évaluations / tableaux de bord, plus écriture sur les tableaux de bord et lecture/écriture/exécution des requêtes pour le flux de création « Demander à l'IA d'écrire une requête ». Tout le SQL passe toujours via le même rôle en lecture seule et le même chemin SQL surveillé qu'une requête écrite par un utilisateur, donc cela élargit la *surface de création*, pas la surface de données ; les opérations destructrices (`queries:delete`, `dashboards:delete`) sont délibérément absentes de la clé de l'assistant. Comme la clé `admin`, elle est **protégée** : elle ne peut pas être désactivée ou régénérée via l'API des clés, seulement pivotée en changeant `AGENT_API_KEY` et en redémarrant. Les *utilisateurs* du tableau de bord ont en outre besoin de la permission `agent:use` pour voir et utiliser l'assistant. Si vous activez l'auto-instrumentation, donnez à l'assistant une clé séparée avec uniquement `events:add`. --- -## Notes de mise à jour et de compatibilité ascendante +## Notes de mise à niveau et de compatibilité ascendante -Ces notes ne sont nécessaires que si vous mettez à niveau une instance existante ; les nouveaux déploiements peuvent les ignorer. +Ces notes ne concernent que les mises à niveau d'une instance existante ; les nouveaux déploiements peuvent les ignorer. -> Lors du déploiement des Audits, les bénéficiaires existants ont été élargis selon les mêmes formes de rôle que pour les alertes : chaque utilisateur et ensemble de permissions détenant `alerts:read` a obtenu `audits:read`, et chaque détenteur de `alerts:write` a obtenu `audits:write`. Les clés API existantes n'ont **pas** été élargies. Accordez explicitement `audits:*` à une clé si elle a besoin de la surface d'audit. +> Lors du lancement des Audits, les bénéficiaires existants ont été élargis selon les mêmes formes de rôle que les alertes : chaque utilisateur et ensemble de permissions détenant `alerts:read` a obtenu `audits:read`, et chaque détenteur de `alerts:write` a obtenu `audits:write`. Les clés API existantes n'ont **pas** été élargies. Accordez `audits:*` à une clé explicitement si elle nécessite la surface d'audit. -> Les attributions stockées du token hérité `alerts:ack` sont interprétées comme `incidents:ack` afin que les équipes de permanence conservent leur accès sans devoir recréer leurs clés. Le token n'est plus assignable depuis l'éditeur d'utilisateurs du tableau de bord ; la matrice propose désormais `incidents:ack` à la place. +> Les accords stockés du token `alerts:ack` hérité sont analysés comme `incidents:ack` afin que les opérateurs de service conservent leur accès sans avoir à recréer leurs clés. Le token n'est plus assignable depuis l'éditeur d'utilisateurs du tableau de bord ; la matrice propose `incidents:ack` à la place. --- ## Étapes suivantes -- [SDK Python](/fr/agenteye/python-sdk) : comment votre code d'agent s'authentifie lors de l'envoi d'événements. +- [SDK Python](/fr/agenteye/python-sdk) : comment votre code agent s'authentifie lors de l'envoi d'événements. - [Sécurité](/fr/agenteye/security) : comment fonctionnent la connexion, le contrôle d'accès et l'isolation des données par organisation. \ No newline at end of file diff --git a/docs/fr/agenteye/assistant.mdx b/docs/fr/agenteye/assistant.mdx index 2289c322..da19eb26 100644 --- a/docs/fr/agenteye/assistant.mdx +++ b/docs/fr/agenteye/assistant.mdx @@ -1,63 +1,63 @@ --- title: "Assistant IA" -description: "Posez une question sur vos données d'agent en langage naturel et obtenez une réponse qui renvoie directement aux preuves." +description: "Posez une question sur les données de vos agents en français naturel et obtenez une réponse qui renvoie directement aux preuves." --- -Posez une question sur vos données d'agent en langage naturel et obtenez une réponse qui renvoie directement aux preuves. Pas de SQL à écrire, pas de tableaux de bord à parcourir — l'assistant **Failproof AI Observability** est le moyen le plus rapide pour n'importe quel membre de votre équipe d'obtenir des réponses sur vos agents. +Posez une question sur les données de vos agents en langage naturel et obtenez une réponse qui renvoie directement aux preuves. Pas de SQL à écrire, pas de tableaux de bord à fouiller — l'assistant **Failproof AI Observability** est le moyen le plus rapide pour n'importe quel membre de votre équipe d'obtenir des réponses sur vos agents. ![L'assistant Failproof AI Observability répondant à une question en langage naturel dans le tableau de bord, affichant un tableau d'activité des agents en direct, une répartition de l'utilisation des modèles par agent, et des conclusions rédigées, avec les requêtes exécutées affichées en ligne](/agenteye/images/assistant.png) -*Posez votre question en langage naturel et obtenez une réponse construite à partir de vos propres données. Ici, l'assistant décompose quels agents sont les plus actifs et quels modèles ils utilisent, et affiche les requêtes exécutées pour que vous puissiez vérifier chaque chiffre.* +*Posez votre question en langage naturel et obtenez une réponse construite à partir de vos propres données. Ici, l'assistant détaille quels agents sont les plus sollicités et quels modèles ils utilisent, et affiche les requêtes exécutées pour que vous puissiez vérifier chaque chiffre.* -Rien à apprendre. Ouvrez le chat, tapez ce que vous voulez savoir et suivez les liens qu'il vous renvoie : +Rien à apprendre. Ouvrez le chat, tapez ce que vous souhaitez savoir et suivez les liens fournis : ``` -You: which sessions errored today? -AI: 5 sessions errored today, newest first. Each one is linked: - • checkout-agent 14:02 tool timeout - • billing-agent 11:47 unhandled error - • ...and 3 more - -You: summarize this session (asked while viewing a run) -AI: This run took 12 steps across 3 tools and failed near the end when a - payment tool returned an error. It scored low on your "resolved" eval. - Links: the session, the failing event, and that evaluation. +Vous : quelles sessions ont généré des erreurs aujourd'hui ? +IA : 5 sessions ont généré des erreurs aujourd'hui, de la plus récente à la plus ancienne. Chacune est liée : + • checkout-agent 14:02 timeout d'outil + • billing-agent 11:47 erreur non gérée + • ...et 3 autres + +Vous : résume cette session (demandé pendant la consultation d'une exécution) +IA : Cette exécution a compté 12 étapes sur 3 outils et a échoué vers la fin lorsqu'un + outil de paiement a renvoyé une erreur. Elle a obtenu un score faible sur votre évaluation "resolved". + Liens : la session, l'événement en échec, et cette évaluation. ``` ## Posez la question, accédez directement à la preuve -Vous arrêtez de deviner et vous arrêtez d'écrire des requêtes. Posez une question comme « comment évolue la qualité en prod cette semaine ? », « quelles sessions ont échoué aujourd'hui ? » ou « résume cette session », et vous obtenez une réponse directe en quelques secondes plutôt que de construire une requête et de la lire vous-même. +Fini les suppositions et les requêtes à écrire. Demandez « comment évolue la qualité en production cette semaine ? », « quelles sessions ont généré des erreurs aujourd'hui ? » ou « résume cette session », et vous obtenez une réponse claire en quelques secondes plutôt que de construire une requête et de l'interpréter vous-même. -Chaque réponse est accompagnée de ses justificatifs. L'assistant renvoie vers les sessions exactes, les requêtes sauvegardées et les tableaux de bord qu'il a utilisés pour formuler la réponse, afin que vous puissiez cliquer et confirmer plutôt que de le croire sur parole. Il est également **conscient du contexte de la page** : posez une question sur « cette session » pendant que vous la consultez et il sait déjà de quelle exécution vous parlez. Rouvrez une conversation antérieure depuis le sélecteur d'historique et reprenez là où vous en étiez. +Chaque réponse vient avec ses justificatifs. L'assistant lie les sessions exactes, les requêtes sauvegardées et les tableaux de bord qu'il a utilisés pour parvenir à la réponse, afin que vous puissiez vérifier par vous-même plutôt que de le croire sur parole. Il est également **conscient du contexte de la page** : demandez « cette session » pendant que vous en consultez une et il sait déjà de quelle exécution il s'agit. Rouvrez n'importe quelle conversation précédente depuis le sélecteur d'historique et reprenez là où vous en étiez. ## Transformez une bonne réponse en requête sauvegardée ou en tableau de bord -Lorsqu'une réponse mérite d'être conservée, demandez à l'assistant de la sauvegarder. Il rédige le SQL pour une requête sauvegardée, ou assemble un tableau de bord à partir de ces requêtes, puis vous présente une carte **Approuver / Rejeter**. Rien n'est écrit tant que vous ne cliquez pas sur Approuver, ce qui vous offre la rapidité du « il suffit de demander » tout en gardant le dernier mot. +Lorsqu'une réponse mérite d'être conservée, demandez à l'assistant de la sauvegarder. Il rédige le SQL pour une requête sauvegardée, ou assemble un tableau de bord à partir de ces requêtes, puis affiche une carte **Approuver / Rejeter**. Rien n'est écrit tant que vous ne cliquez pas sur Approuver, ce qui vous offre la rapidité du « posez simplement la question » tout en gardant le dernier mot. -Sur la page **Queries**, il va encore plus loin et devient un auteur SQL : décrivez la requête souhaitée (« afficher le taux d'erreur par agent sur les 7 derniers jours ») et il diffuse le SQL directement dans l'éditeur, en ouvrant une vue diff afin que vous puissiez **Accepter** ou **Rejeter** la modification avant qu'elle ne soit appliquée. +Sur la page **Queries**, il va plus loin et devient un auteur SQL : décrivez la requête souhaitée (« afficher le taux d'erreur par agent pour les 7 derniers jours ») et il diffuse le SQL directement dans l'éditeur, ouvrant une vue différentielle pour que vous puissiez **Accepter** ou **Rejeter** la modification avant qu'elle ne soit appliquée. ![La page Queries d'Observability et son éditeur SQL](/agenteye/images/query-lab.png) -*La page Queries : cet éditeur est l'endroit où l'assistant diffuse un brouillon de requête en lecture seule que vous acceptez ou rejetez.* +*La page Queries : c'est dans cet éditeur que l'assistant diffuse un brouillon de requête en lecture seule que vous pouvez accepter ou rejeter.* -La création de SQL par cette méthode utilise la permission `queries:run`, la même que celle du bouton **Run** de l'éditeur. Le chat partout ailleurs nécessite `agent:use`. +La rédaction de SQL par cette méthode utilise la permission `queries:run`, la même que celle derrière le bouton **Run** de l'éditeur. Le chat ailleurs nécessite `agent:use`. -## Accessible à toute l'équipe en toute sécurité +## Sûr à confier à toute l'équipe Vous pouvez ouvrir l'assistant à tous sans vous inquiéter de ce qu'il pourrait toucher : -- **Il ne lit que ce que vous pouvez déjà voir.** Les réponses sont limitées à vos propres permissions de lecture, donc il n'élargit jamais votre surface de données. -- **Chaque écriture attend votre confirmation.** Les requêtes sauvegardées et les tableaux de bord ne sont créés qu'après votre clic explicite sur Approuver, et aucun paramètre ne désactive cette validation. +- **Il ne lit que ce que vous pouvez déjà voir.** Les réponses sont limitées à vos propres permissions de lecture, il n'élargit donc jamais votre surface de données. +- **Chaque écriture attend votre accord.** Les requêtes sauvegardées et les tableaux de bord ne sont créés qu'après votre clic explicite sur Approuver, et aucun paramètre ne permet de désactiver cette validation. - **Il ne peut jamais rien supprimer.** Aucun outil de suppression n'est exposé et l'assistant ne détient aucune permission de suppression. Les suppressions restent entre vos mains, dans le tableau de bord. - **Il reste dans votre organisation.** L'assistant ne voit que l'organisation que vous consultez actuellement. -- **Vos questions vous appartiennent.** Les invites et les réponses sont stockées dans votre propre base de données Observability ; l'analytique produit n'enregistre que les métadonnées d'utilisation, jamais le texte de vos invites. +- **Vos questions vous appartiennent.** Les prompts et les réponses résident dans votre propre base de données Observability ; les analyses produit n'enregistrent que les métadonnées d'utilisation, jamais le texte de vos prompts. ## Où le trouver -L'assistant est présent sur le bord droit de chaque page sous votre organisation (`//...`). Cliquez sur le rail ou appuyez sur `⌘J` / `Ctrl+J` pour l'ouvrir en panneau de chat complet, et faites glisser son bord pour le redimensionner ; votre largeur est mémorisée entre les rechargements. Vous avez besoin de la permission **`agent:use`** pour l'utiliser, sinon le rail est grisé. S'il n'a pas encore été activé pour votre déploiement (une connexion LLM est requise), vous verrez un rail désactivé à la place d'un chat fonctionnel. +L'assistant est présent sur le bord droit de chaque page sous votre organisation (`//...`). Cliquez sur le rail ou appuyez sur `⌘J` / `Ctrl+J` pour le déployer en panneau de chat complet, et faites glisser son bord pour le redimensionner ; votre largeur est mémorisée entre les rechargements. Vous avez besoin de la permission **`agent:use`** pour l'utiliser, sinon le rail est grisé. S'il n'a pas encore été activé pour votre déploiement (il nécessite une connexion LLM), vous verrez un rail atténué à la place d'un chat fonctionnel. ## Voir aussi - [CLI et agents](/fr/agenteye/cli-and-agents) -- [Queries](/fr/agenteye/queries) +- [Queries](/fr/aigenteye/queries) - [Tableaux de bord](/fr/agenteye/dashboards) - [Suite d'évaluation](/fr/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/fr/agenteye/audits.mdx b/docs/fr/agenteye/audits.mdx index eb0df4e6..91dafb2e 100644 --- a/docs/fr/agenteye/audits.mdx +++ b/docs/fr/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- title: "Audits : votre analyste de fiabilité automatique" -description: "Failproof AI Observability détecte les défaillances pour lesquelles vous n'avez jamais défini de règle et vous remet une liste de priorités classées, étayées par des preuves, indiquant précisément quoi corriger." +description: "Failproof AI Observability part à la recherche des défaillances pour lesquelles vous n'avez jamais écrit de règle et vous remet une liste de tâches classées par priorité, étayées par des preuves, avec exactement ce qu'il faut corriger." --- -Failproof AI Observability détecte les défaillances pour lesquelles vous n'avez jamais défini de règle et vous remet une liste de priorités classées, étayées par des preuves, indiquant précisément quoi corriger. C'est comme avoir un analyste qui parcourt vos logs chaque nuit et vous dépose un résumé sur le bureau chaque matin. +Failproof AI Observability part à la recherche des défaillances pour lesquelles vous n'avez jamais écrit de règle et vous remet une liste de tâches classées par priorité, étayées par des preuves, avec exactement ce qu'il faut corriger. C'est comme avoir un analyste qui passe vos logs en revue chaque nuit et vous laisse la synthèse sur votre bureau au matin.
- +
-*Un tour d'horizon en deux minutes : d'une exécution planifiée à une correction sur laquelle vous pouvez agir.* +*Un tour d'horizon de deux minutes : d'une exécution planifiée à un correctif sur lequel vous pouvez agir.* ![La page Audits : des tâches récurrentes qui analysent vos sessions à la recherche de schémas d'échec, chacune avec une planification et une sensibilité](/agenteye/images/audits.png) -*Chaque audit est une tâche récurrente qui fouille vos sessions et rédige des recommandations classées et étayées par des preuves.* +*Chaque audit est une tâche récurrente qui explore vos sessions et rédige des recommandations classées par priorité, étayées par des preuves.* -## Arrêtez de deviner quoi corriger ensuite +## Arrêtez de deviner ce qu'il faut corriger en premier -Les alertes détectent les problèmes que vous savez déjà surveiller. Les audits détectent ceux que vous ne connaissez pas encore. Selon un calendrier que vous définissez, un audit parcourt l'ensemble de vos sessions d'agent pour identifier les schémas qui méritent d'être corrigés — vous passez ainsi votre temps à agir sur les résultats plutôt qu'à faire défiler des logs en espérant les repérer vous-même. +Les alertes détectent les problèmes que vous savez déjà surveiller. Les audits détectent ceux que vous ne connaissez pas encore. Selon la planification que vous définissez, un audit parcourt l'ensemble de vos sessions d'agent et traque les schémas qui méritent d'être corrigés — vous passez ainsi votre temps à agir sur les résultats plutôt qu'à faire défiler des logs en espérant les repérer vous-même. Une seule exécution s'attaque aux modes de défaillance qui brisent réellement les agents en production : -- **Clusters d'erreurs** : la même défaillance qui se répète sous une cause racine commune. -- **Dérive par rapport à une référence** : un comportement qui s'écarte discrètement d'une fenêtre connue comme saine. -- **Échec d'objectif dans les transcriptions** : des exécutions techniquement terminées mais qui n'ont jamais accompli la tâche. -- **Mauvaise utilisation des outils** : le mauvais outil, de mauvais arguments, ou des boucles qui consomment des appels inutilement. -- **Compromis qualité/coût** : là où vous surpayez pour des résultats que vous pourriez obtenir moins cher. +- **Clusters d'erreurs** : la même défaillance se répétant sous une cause racine commune. +- **Dérive par rapport à une référence** : un comportement qui s'éloigne discrètement d'une fenêtre connue comme saine. +- **Échec d'objectif dans les transcriptions** : des exécutions qui se sont techniquement terminées sans jamais accomplir la tâche. +- **Mauvaise utilisation des outils** : le mauvais outil, des arguments incorrects, ou des boucles qui consomment des appels inutilement. +- **Compromis qualité/coût** : là où vous surpayez pour un résultat que vous pourriez obtenir moins cher. - **Lacunes de couverture** : des comportements qu'aucune évaluation ni alerte ne surveille. -Vous choisissez l'intensité de l'analyse avec un simple paramètre de **sensibilité** (faible, moyenne ou élevée), de sorte qu'un agent de staging bruyant et un agent de production verrouillé peuvent chacun être calibrés sur le signal souhaité. +Vous décidez de l'intensité de la recherche avec un seul paramètre de **sensibilité** (faible, moyenne ou élevée), de sorte qu'un agent de staging bruyant et un agent de production verrouillé peuvent chacun être réglés sur le signal souhaité. -## Chaque recommandation est accompagnée de preuves +## Chaque recommandation vient avec ses preuves -Vous n'avez jamais à accepter un résultat sur parole. Chaque recommandation cite les sessions exactes dont elle provient ainsi que le SQL qui l'a fait remonter, afin que vous puissiez consulter les preuves et confirmer le problème en un clic plutôt que de reconstituer une affirmation à rebours. +Vous n'avez jamais à accepter un résultat sur parole. Chaque recommandation cite les sessions exactes dont elle est issue ainsi que la requête SQL qui l'a mise en évidence — vous pouvez ouvrir les preuves et confirmer le problème en un clic plutôt que de devoir décortiquer une affirmation. -Lorsqu'un résultat concerne un identifiant secret exposé, il va encore plus loin en reliant les événements individuels qu'il a détectés. Cliquez sur l'un d'eux et vous atterrissez sur ce moment précis dans la session, déjà sélectionné — et non en haut d'une longue transcription à faire défiler. Le lien nomme l'événement ; il ne copie jamais le secret détecté dans le résultat, de sorte que la lecture d'un résultat n'est pas un second endroit où votre identifiant est consigné. Si un événement n'est plus disponible parce que la session a dépassé votre fenêtre de rétention, la page l'indique clairement plutôt que de vous laisser vous demander si vous avez cliqué au mauvais endroit. +Lorsqu'un résultat concerne un identifiant divulgué, il va encore plus loin et renvoie vers les événements individuels correspondants. Cliquez sur l'un d'eux et vous atterrissez sur ce moment précis dans la session, déjà sélectionné — pas en haut d'une longue transcription à faire défiler. Le lien nomme l'événement ; il ne copie jamais le secret détecté dans le résultat, de sorte que la lecture d'un résultat ne constitue pas un second endroit où votre identifiant est consigné. Si un événement n'est plus disponible parce que la session a dépassé votre fenêtre de rétention, la page l'indique clairement plutôt que de vous laisser vous demander si vous avez cliqué au mauvais endroit. -C'est aussi ce qui garantit l'honnêteté des audits. Le serveur vérifie que chaque session citée existe réellement et **rejette toute recommandation dont les preuves ne tiennent pas**, de sorte que l'audit enquête sans jamais inventer. Ce qui figure sur votre liste est réel, reproductible et classé par importance, avec les gains les plus significatifs en tête. +C'est aussi ce qui garantit l'honnêteté des audits. Le serveur vérifie que chaque session citée existe réellement et **rejette toute recommandation dont les preuves ne tiennent pas**, de sorte que l'audit enquête sans jamais inventer. Ce qui figure sur votre liste est réel, reproductible et classé selon son importance, avec les gains les plus significatifs en tête. -## Transformer une correction en garde-fou +## Transformez un correctif en garde-fou -Corriger un problème ne représente que la moitié du bénéfice. L'autre moitié consiste à s'assurer qu'il ne peut pas revenir discrètement. Chaque résultat comporte **un raccourci en un clic qui crée une alerte de récurrence**, préremplie avec un déclencheur de départ raisonnable que vous pouvez ajuster. Fermez le résultat, activez l'alerte, et la prochaine fois que ce schéma réapparaît, vous êtes notifié au lieu de le redécouvrir lors d'un futur audit. +Corriger un problème ne représente que la moitié du bénéfice. L'autre moitié consiste à s'assurer qu'il ne puisse pas revenir discrètement. Chaque résultat comporte un **raccourci en un clic qui ébauche une alerte de récurrence**, préremplie avec un déclencheur de départ raisonnable que vous pouvez affiner. Fermez le résultat, activez l'alerte, et la prochaine fois que ce schéma réapparaît, vous êtes averti au lieu de le redécouvrir lors d'un futur audit. ## Où le trouver -Les audits se trouvent dans le tableau de bord à **`//audits`** (barre latérale vers *analyze* puis *audits*). La consultation des exécutions et des résultats nécessite **`audits:read`** ; la création, la modification et le triage des audits nécessitent **`audits:write`**. Définissez la portée et la cadence d'un audit, puis cliquez sur **Run now** si vous souhaitez obtenir des résultats immédiatement sans attendre le prochain passage planifié. +Les audits se trouvent dans le tableau de bord à **`//audits`** (barre latérale vers *analyze* puis *audits*). La consultation des exécutions et des résultats nécessite **`audits:read`** ; la création, la modification et le tri des audits nécessitent **`audits:write`**. Définissez la portée et la cadence d'un audit, puis cliquez sur **Run now** chaque fois que vous souhaitez obtenir des résultats immédiatement sans attendre la prochaine exécution planifiée. ## Voir aussi -- [Alerts](/fr/agenteye/alerts) : soyez notifié dès qu'un seuil que vous connaissez déjà est franchi. -- [Evaluations](/fr/agenteye/evaluations) : notez chaque exécution afin que les régressions de qualité remontent d'elles-mêmes. +- [Alerts](/fr/agenteye/alerts) : soyez averti dès qu'un seuil que vous connaissez déjà est franchi. +- [Evaluations](/fr/agenteye/evaluations) : notez chaque exécution pour que les régressions de qualité remontent d'elles-mêmes. - [Error tracking](/fr/agenteye/error-tracking) : regroupez et suivez les erreurs que vos agents génèrent. - [Incidents](/fr/agenteye/incidents) : suivez un problème détecté par un audit jusqu'à sa résolution. \ No newline at end of file diff --git a/docs/fr/agenteye/cli-and-agents.mdx b/docs/fr/agenteye/cli-and-agents.mdx index 3010ba79..caf36ca8 100644 --- a/docs/fr/agenteye/cli-and-agents.mdx +++ b/docs/fr/agenteye/cli-and-agents.mdx @@ -1,79 +1,80 @@ --- title: "CLI" -description: "Tout votre déploiement Failproof AI Observability, à portée d'une seule commande." +description: "Tout votre déploiement Failproof AI Observability, accessible en une seule commande." --- -Tout votre déploiement Failproof AI Observability, à portée d'une seule commande. Vérifiez la production, créez une clé API ou acquittez un incident sans quitter votre terminal, puis scriptez n'importe quelle opération dans votre CI, ou laissez un agent de code s'en charger en langage naturel. + +Tout votre déploiement Failproof AI Observability, accessible en une seule commande. Vérifiez la production, générez une clé API ou accusez réception d'un incident sans quitter votre terminal, puis automatisez le tout dans la CI ou laissez un agent de code le faire pour vous en langage naturel. ```bash pipx install agenteye -agenteye login --email vous@exemple.com # un code à 6 chiffres arrive dans votre boîte mail +agenteye login --email you@example.com # un code à 6 chiffres arrive dans votre boîte mail agenteye --json sessions --since 24h # toutes les exécutions d'agents des dernières 24h, les plus récentes en premier ``` *Le CLI `agenteye` communique avec votre tableau de bord. C'est un outil distinct du collecteur, qui achemine les événements vers le serveur.* -## Tout votre déploiement, une seule commande suffit +## Tout votre déploiement, en une seule commande -Fini de jongler entre les onglets pour répondre à une simple question. Le CLI `agenteye` lit vos données et administre votre organisation depuis un seul binaire : une vérification qui nécessitait auparavant de naviguer dans le tableau de bord devient une ligne que vous pouvez relancer, mettre en alias ou coller dans un runbook. Quatre surfaces sont à votre disposition : +Fini de jongler entre les onglets pour répondre à une question rapide. Le CLI `agenteye` lit vos données et administre votre organisation depuis un binaire unique : une vérification qui nécessitait auparavant de naviguer dans le tableau de bord se résume à une ligne que vous pouvez relancer, mettre en alias ou coller dans un runbook. Vous disposez de quatre surfaces : -- **Lire vos données :** `sessions`, `events`, `evals` et `errors`, filtrés par plage horaire, agent et environnement. -- **Gérer votre organisation :** `keys`, `users`, `settings`, `alerts` et `incidents`. -- **Lancer des analyses :** requêtes SQL enregistrées et un runner `query` ad hoc sur vos données d'événements. +- **Lecture de vos données :** `sessions`, `events`, `evals` et `errors`, filtrés par période, agent et environnement. +- **Gestion de votre organisation :** `keys`, `users`, `settings`, `alerts` et `incidents`. +- **Analyses :** requêtes SQL sauvegardées et un outil `query` ad hoc sur vos données d'événements. - **Interroger l'assistant :** `agent ask` accède au même analyste en lecture seule que celui disponible dans le tableau de bord. -Installez-le une fois avec `pipx`, connectez-vous via un code à 6 chiffres reçu par e-mail, et vous êtes prêt. La session dure environ une journée ; relancez `agenteye login` à son expiration. Utilisez-le pour contrôler la production, provisionner une clé ou trier un incident actif, sans jamais ouvrir un navigateur : +Installez-le une fois avec `pipx`, connectez-vous grâce à un code à 6 chiffres reçu par e-mail, et vous êtes prêt. La session dure environ une journée ; relancez `agenteye login` à son expiration. Utilisez-le pour vérifier ponctuellement la production, provisionner une clé ou trier un incident en cours, le tout sans ouvrir de navigateur : ```bash -agenteye errors --since 24h --aggregate # ce qui est en erreur, regroupé par type +agenteye errors --since 24h --aggregate # ce qui est cassé, regroupé par type d'erreur agenteye incidents list --state firing # ce qui est en feu en ce moment agenteye keys create ci --add events:add # une clé qui ne peut qu'envoyer des événements, secret affiché une seule fois ``` Un point important à retenir : les options globales comme `--json` se placent avant la commande. `agenteye --json sessions` est correct ; `agenteye sessions --json` ne l'est pas. -## Scriptez-le, intégrez-le dans votre CI +## Automatisez, intégrez à la CI -Chaque commande accepte `--json`, et cela change tout. Le JSON brut part sur stdout tandis que les messages de statut et les avertissements destinés à l'humain vont sur stderr — une capture avec `--json` s'envoie donc directement dans `jq` sans ligne parasite à éliminer. C'est ce qui rend le CLI aussi efficace pour vous à l'invite de commande que pour un agent de code qui parse les sorties : +Chaque commande accepte `--json`, ce qui change tout. Le JSON brut est envoyé vers stdout tandis que les messages de statut et les avertissements destinés à l'humain vont vers stderr — ainsi, une capture `--json` se pipe directement dans `jq` sans ligne parasite à supprimer. C'est ce qui rend le CLI aussi efficace pour vous à l'invite de commandes que pour un agent de code qui analyse la sortie : ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -Il est conçu pour fonctionner sans surveillance. Les confirmations interactives sont automatiquement ignorées lorsqu'aucun terminal n'est attaché, rien ne bloque donc dans un pipeline, et chaque commande retourne un code de sortie explicite : `0` succès, `4` non connecté, `5` permission manquante (le message la précise, par exemple `alerts:write`), `3` tableau de bord inaccessible. Un script peut brancher sur un `4` pour se réauthentifier, ou sur un `5` pour vous indiquer exactement ce qu'il faut demander à un administrateur — au lieu d'échouer silencieusement. +Il est conçu pour fonctionner sans surveillance. Les invites de confirmation sont ignorées automatiquement lorsqu'aucun terminal n'est connecté, rien ne reste bloqué dans un pipeline, et chaque commande retourne un code de sortie explicite : `0` succès, `4` non connecté, `5` permission manquante (le message la nomme, par exemple `alerts:write`), `3` tableau de bord inaccessible. Un script peut se brancher sur un `4` pour se réauthentifier ou sur un `5` pour savoir exactement quelle permission demander à un administrateur, plutôt que d'échouer sans information. -## Laissez un agent de code piloter le CLI en langage naturel +## Laissez un agent de code piloter le tout en langage naturel -Mieux encore, vous ne devriez pas avoir à retenir tous ces drapeaux. La **compétence CLI** est un petit dossier Agent Skill nommé `agenteye-cli` qui apprend à un agent de code tel que Claude Code ou Codex à piloter le CLI à partir de requêtes en langage naturel. Demandez « est-ce que quelque chose est cassé aujourd'hui ? » et l'agent choisit la commande, l'exécute en votre nom et répond en prose. +Mieux encore, vous ne devriez pas avoir à mémoriser ces options. La **compétence CLI** est un petit dossier Agent Skill nommé `agenteye-cli` qui apprend à un agent de code comme Claude Code ou Codex à piloter le CLI à partir de requêtes en langage naturel. Demandez « est-ce que quelque chose est cassé aujourd'hui ? » et l'agent choisit la commande, l'exécute en votre nom et répond en langage naturel. -Pour Claude Code, déposez le dossier `agenteye-cli` dans `~/.claude/skills/` et il est découvert automatiquement. Failproof AI Observability fournit le dossier ; il n'y a rien de supplémentaire à installer, car il se contente de piloter le CLI que vous avez déjà installé. Connectez-vous vous-même au préalable : la compétence ne peut pas effectuer à votre place la connexion par code reçu par e-mail. +Pour Claude Code, déposez le dossier `agenteye-cli` dans `~/.claude/skills/` et il sera découvert automatiquement. Failproof AI Observability fournit le dossier ; il n'y a rien de plus à installer, car il ne fait que piloter le CLI que vous avez déjà installé. Connectez-vous vous-même au préalable : la compétence ne peut pas effectuer la connexion par code e-mail à votre place. -Comme l'agent exécute le CLI en votre nom, il peut tout faire dans les limites de votre session — lectures et écritures comprises : créer des clés, modifier des paramètres, résoudre des incidents. La confirmation interactive du CLI ne se déclenche pas pour un agent, c'est pourquoi la compétence est conçue pour indiquer la commande exacte et attendre votre accord avant tout changement. Vous êtes l'étape de confirmation. +Comme l'agent exécute le CLI en votre nom, il peut tout faire dans les limites de vos droits, lectures et écritures incluses : créer des clés, modifier des paramètres, résoudre des incidents. L'invite de confirmation du CLI ne se déclenche pas pour un agent, c'est pourquoi la compétence est conçue pour indiquer la commande exacte et attendre votre accord avant tout changement. Vous êtes l'étape de confirmation. ```text -vous Pourquoi la session run-001 a-t-elle échoué ? +you Pourquoi la session run-001 a-t-elle échoué ? agent Exécution : agenteye --json events --session-id run-001 --all - Le checkout-agent a rencontré une TimeoutError lors de son troisième appel d'outil. + L'agent checkout a rencontré une TimeoutError lors de son troisième appel d'outil. ``` Les lectures restent instantanées, et chaque écriture marque une pause pour vous : ```text -vous Donne à CI une clé qui ne peut qu'envoyer des événements. +you Donne à la CI une clé qui ne peut qu'envoyer des événements. -agent Ceci va créer une clé API. Je vais exécuter : +agent Cela va créer une clé API. Je vais exécuter : agenteye keys create ci --add events:add - Confirmer ? + Voulez-vous continuer ? -vous oui +you oui -agent Fait. Clé "ci" créée avec events:add uniquement. Le secret est affiché une seule fois, enregistrez-le maintenant. +agent Terminé. La clé "ci" a été créée avec events:add uniquement. Le secret n'est affiché qu'une seule fois, conservez-le maintenant. ``` -## En relation +## Voir aussi - [Référence CLI](/fr/agenteye/cli) : toutes les commandes, options et structures JSON. - [Recettes CLI pour agents](/fr/agenteye/cli-recipes) : patterns `jq` prêts à l'emploi et gestion des codes de sortie. -- [Compétence agent CLI](/fr/agenteye/cli-skill) : installation et utilisation de la compétence `agenteye-cli`. -- [Assistant IA](/fr/agenteye/assistant) : l'analyste intégré au tableau de bord que `agent ask` interroge. \ No newline at end of file +- [Compétence CLI pour agent](/fr/agenteye/cli-skill) : installer et utiliser la compétence `agenteye-cli`. +- [Assistant IA](/fr/agenteye/assistant) : l'analyste intégré au tableau de bord auquel `agent ask` s'adresse. \ No newline at end of file diff --git a/docs/fr/agenteye/cli-recipes.mdx b/docs/fr/agenteye/cli-recipes.mdx index 34943c0d..c74830b2 100644 --- a/docs/fr/agenteye/cli-recipes.mdx +++ b/docs/fr/agenteye/cli-recipes.mdx @@ -1,41 +1,41 @@ --- -title: "Recettes CLI pour agents" -description: "Patterns de requêtes à copier-coller et recettes jq qui transforment les données de session, d'événement et d'évaluation en quelque chose qu'un script ou un agent de codage peut automatiser." +title: "Recettes CLI pour les agents" +description: "Modèles de requêtes et recettes jq à copier-coller qui transforment les données de session, d'événement et d'évaluation en quelque chose qu'un script ou un agent de code peut automatiser." --- -Récupérez les données de sessions, d'événements et d'évaluations (et déclenchez des réévaluations) directement depuis un script ou un agent de codage, avec du JSON propre sur stdout qui s'enchaîne directement dans `jq`. Ces recettes transforment les données de Failproof AI Observability en quelque chose qu'un utilisateur de terminal ou un agent de codage IA (Claude Code, Cursor) peut interroger et automatiser, sans cliquer dans le tableau de bord. +Récupérez les données de session, d'événement et d'évaluation (et déclenchez des réévaluations) directement depuis un script ou un agent de code, avec du JSON propre sur stdout qui se pipe directement dans `jq`. Ces recettes transforment les données de Failproof AI Observability en quelque chose qu'un utilisateur en ligne de commande ou un agent de code IA (Claude Code, Cursor) peut interroger et automatiser, sans passer par le tableau de bord. -Les patterns ci-dessous sont prêts à être copiés-collés pour la CLI Failproof AI Observability (`agenteye`). Pour l'installation, l'authentification et la liste complète des options, consultez [CLI](/fr/agenteye/cli) ; exécutez `agenteye -h` ou `agenteye -h` pour l'aide intégrée. +Les modèles ci-dessous sont prêts à être copiés-collés pour le CLI de Failproof AI Observability (`agenteye`). Pour l'installation, l'authentification et la liste complète des options, voir [CLI](/fr/agenteye/cli) ; exécutez `agenteye -h` ou `agenteye -h` pour l'aide intégrée. ## Règles d'or -1. **Les options globales vont *avant* la commande.** `agenteye --json sessions` est correct ; `agenteye sessions --json` ne l'est pas. Les globales sont `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Passez `--json` dès que vous analysez la sortie.** Les données vont sur **stdout** en JSON ; les statuts lisibles par l'humain et les erreurs vont sur **stderr**, donc stdout reste propre pour être transmis à `jq`. -3. **Basez-vous sur le code de sortie**, pas sur le texte de stderr : `0` ok · `1` erreur inattendue · `2` arguments invalides · `3` tableau de bord inaccessible · `4` non connecté ou session expirée · `5` permission manquante · `6` ressource introuvable. -4. **Explorez avec `-h`.** Chaque commande documente ses filtres, les formats de valeurs et la forme JSON. +1. **Les options globales vont *avant* la commande.** `agenteye --json sessions` est correct ; `agenteye sessions --json` ne l'est pas. Les options globales sont `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Passez `--json` dès que vous analysez la sortie.** Les données vont sur **stdout** en JSON ; les statuts lisibles et les erreurs vont sur **stderr**, donc stdout reste propre pour être pipé dans `jq`. +3. **Branchez-vous sur le code de sortie**, pas sur le texte de stderr : `0` ok · `1` erreur inattendue · `2` arguments invalides · `3` impossible d'atteindre le tableau de bord · `4` non connecté ou session expirée · `5` permission manquante · `6` ressource introuvable. +4. **Explorez avec `-h`.** Chaque commande documente ses filtres, les formats de valeurs et la structure JSON. ## Configuration initiale ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # pour ne pas répéter --base-url -agenteye login --email you@example.com # collez le code reçu par email ; valable ~24h +agenteye login --email you@example.com # collez le code reçu par e-mail ; valide ~24h ``` -## Vérifier l'authentification avant de travailler +## Vérifiez l'authentification avant de travailler -`whoami` ne renvoie jamais d'erreur en cas de session manquante ou expirée ; il signale `logged_in:false` à la place, ce qui permet à un agent de sonder l'état d'authentification en toute sécurité. (Il peut tout de même sortir avec un code non nul si aucune URL de base n'est définie ou si le tableau de bord est inaccessible.) +`whoami` ne renvoie jamais d'erreur pour une session manquante ou expirée ; il rapporte `logged_in:false` à la place, ce qui permet à un agent de sonder l'état d'authentification en toute sécurité. (Il peut quand même sortir avec un code non nul si aucune URL de base n'est définie ou si le tableau de bord est inaccessible.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then - echo "Not authenticated. Run: agenteye login" >&2; exit 1 + echo "Non authentifié. Exécutez : agenteye login" >&2; exit 1 fi ``` -## Trouver les sessions en échec ou avec un score bas +## Trouver les sessions en échec ou avec un score faible ```bash -# sessions des dernières 24h dont l'évaluation est en erreur +# sessions des dernières 24h dont l'évaluation a échoué agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' # évaluations avec un score helpfulness <= 0.5, pour un agent donné @@ -43,11 +43,11 @@ agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Le filtrage par score s'effectue sur **`evals`**, pas sur `sessions`. `--score KEY:MIN..MAX` est répétable et combiné par ET ; chaque borne est optionnelle (`..0.5` signifie ≤ 0.5, `0.9..` signifie ≥ 0.9). Vous pouvez passer jusqu'à 20 filtres de score par requête ; au-delà, le serveur renvoie HTTP 400. `sessions` partage les filtres `--env`, `--status`, `--agent-id`, `--session-id` et de plage temporelle avec `evals`, mais ne dispose pas de `--score`. +Le filtrage par score se fait sur **`evals`**, pas sur `sessions`. `--score KEY:MIN..MAX` est répétable et combiné en AND ; chaque borne est optionnelle (`..0.5` signifie ≤ 0.5, `0.9..` signifie ≥ 0.9). Vous pouvez passer jusqu'à 20 filtres de score par requête ; au-delà, vous obtenez une erreur HTTP 400. `sessions` partage les filtres `--env`, `--status`, `--agent-id`, `--session-id` et les plages temporelles avec `evals`, mais ne dispose pas de `--score`. ## Lire une session de bout en bout -Il n'existe pas de commande `session show` unique. Combinez la trace d'événements avec l'évaluation de la session : +Il n'existe pas de commande unique `session show`. Combinez le journal d'événements avec l'évaluation de la session : ```bash # la dernière évaluation de la session (statut + scores) @@ -56,22 +56,22 @@ agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scor # tous les événements de l'exécution (augmentez --limit pour un balayage complet) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# uniquement les appels d'outils dans une session (--full est requis pour obtenir le payload brut) +# uniquement les appels d'outils d'une session (--full est requis pour obtenir le payload brut) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **Note :** Par défaut, `events` lit un flux rapide sans payload. Chaque événement porte un résumé `summary` calculé côté serveur ainsi que des indicateurs comme `is_error` et les compteurs de tokens, mais `payload` est renvoyé sous la forme `{}`. Pour récupérer le payload brut, ajoutez `--full` (ou `--fields payload`). Le flux complet est plus lent à grande échelle, donc limitez-le : associez `--full` à un seul `--session-id`. +> **Remarque :** Par défaut, `events` lit un flux rapide sans payload. Chaque événement porte un `summary` d'une ligne calculé côté serveur ainsi que des indicateurs comme `is_error` et le nombre de tokens, mais `payload` est retourné sous la forme `{}`. Pour récupérer le payload brut, ajoutez `--full` (ou `--fields payload`). Le flux complet est plus lent à grande échelle, donc gardez-le borné : associez `--full` à un seul `--session-id`. ## Tout récupérer (pagination) Les résultats sont triés du plus récent au plus ancien et paginés par curseur. ```bash -# en une fois : récupère jusqu'à 500 lignes par pages de 200 +# en une fois : récupérer jusqu'à 500 lignes en pages de 200 lignes agenteye --json events --session-id run-001 --limit 500 --all > events.json -# pagination manuelle : réinjectez next_cursor +# pagination manuelle : réinjecter next_cursor page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -79,14 +79,14 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## Réduire la sortie avec --fields -Restreignez les clés (dans le tableau et avec `--json`) pour limiter ce qu'un agent doit lire. +Limitez les clés (dans le tableau et avec `--json`) pour réduire ce qu'un agent doit lire. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Les noms de champs inconnus sont rejetés (sortie `2`) avec la liste des valeurs valides — un moyen simple de découvrir les noms de champs. +Les noms de champs inconnus sont rejetés (code de sortie `2`) avec la liste des noms valides, ce qui est un moyen simple de les découvrir. ## Découvrir les valeurs de filtre valides @@ -101,29 +101,29 @@ agenteye --json list score_filters | jq -r '.values[]' # KEY valide pour --scor Si vous appartenez à plusieurs organisations, choisissez le tenant actif à la connexion (il est sauvegardé) : ```bash -agenteye login --org acme --email you@corp.com # définit le tenant en même temps que la connexion +agenteye login --org acme --email you@corp.com # définir le tenant en même temps que la connexion agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # remplace pour une seule commande +agenteye --org globex --json sessions --since 24h # surcharge pour une seule commande ``` -Une connexion multi-org sans `--org` se termine avec un code non nul et affiche les organisations disponibles. +Une connexion multi-org sans `--org` se termine avec un code non nul et affiche les organisations parmi lesquelles choisir. ## Créer une clé API pour le SDK/collecteur ```bash -# le secret est affiché UNE SEULE FOIS ; avec --json, c'est le champ .key +# le secret est affiché UNE SEULE FOIS ; avec --json, il correspond au champ .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # rotation ; agenteye keys disable ci-bot --yes pour révoquer ``` -## Exécuter une requête enregistrée ou ad hoc +## Exécuter une requête sauvegardée ou ad hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # une requête enregistrée + un $1 positionnel +agenteye --json query run errs --arg prod | jq '.rows' # une requête sauvegardée + un $1 positionnel ``` -## Traiter un incident de manière non interactive +## Trier un incident sans interaction ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **Note :** Les mutations ignorent automatiquement leur invite de confirmation sous `--json` ou quand stdin n'est pas un TTY, afin que les agents ne restent jamais bloqués ; passez `--yes`/`-y` pour l'ignorer explicitement ailleurs. +> **Remarque :** Les mutations ignorent automatiquement leur invite de confirmation sous `--json` ou lorsque stdin n'est pas un TTY, de sorte que les agents ne restent jamais bloqués ; passez `--yes`/`-y` pour l'ignorer explicitement ailleurs. ## Gestion des codes de sortie dans un script @@ -140,14 +140,14 @@ agenteye incidents resolve "$id" --yes out=$(agenteye --json sessions --since 1h) || code=$? case "${code:-0}" in 0) echo "$out" | jq '.sessions | length' ;; - 4) echo "Session expired - run 'agenteye login'." >&2 ;; - 5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;; - 3) echo "Dashboard unreachable - check the URL." >&2 ;; - *) echo "Unexpected error (exit ${code})." >&2 ;; + 4) echo "Session expirée - exécutez 'agenteye login'." >&2 ;; + 5) echo "Permission manquante (demandez à un administrateur evaluations:read)." >&2 ;; + 3) echo "Tableau de bord inaccessible - vérifiez l'URL." >&2 ;; + *) echo "Erreur inattendue (code de sortie ${code})." >&2 ;; esac ``` -## Formes de la sortie JSON +## Structures de sortie JSON | Commande | JSON sur stdout (avec `--json`) | |---|---| @@ -162,18 +162,18 @@ esac | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (toute commande) | l'objet ressource, ou `{"deleted": true, "id"}` pour les suppressions | -| échec (toute commande, avec `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` sur stdout | +| create/update/delete (tout) | l'objet ressource, ou `{"deleted": true, "id"}` pour les suppressions | +| échec (tout, avec `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` sur stdout | - Chaque élément **event** (`events`) : `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Notez que `payload` vaut `{}` sauf si vous demandez le flux complet avec `--full` (ou `--fields payload`). - Chaque élément **evaluation** (`evals`) : `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Chaque élément **session** (`sessions`) : `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -Le `--fields` de chaque commande accepte exactement les noms de champs de ses propres éléments. L'ensemble diffère entre `sessions` et `evals`, donc un nom valide pour l'un peut être rejeté par l'autre. +Le `--fields` de chaque commande accepte uniquement les noms de champs de ses propres éléments. L'ensemble diffère entre `sessions` et `evals`, donc un nom valide pour l'un peut être rejeté par l'autre. ## Étapes suivantes - [CLI](/fr/agenteye/cli) : installation, authentification et référence complète des options pour chaque commande. -- [Compétence CLI pour agent](/fr/agenteye/cli-skill) : regroupez ces recettes en une compétence que votre agent de codage peut charger. -- [Clés API](/fr/agenteye/api-keys) : créez et délimitez les clés avec lesquelles la CLI, le SDK et le collecteur s'authentifient. +- [Compétence CLI pour agent](/fr/agenteye/cli-skill) : packagées ces recettes comme une compétence que votre agent de code peut charger. +- [Clés API](/fr/agenteye/api-keys) : créez et délimitez les clés avec lesquelles le CLI, le SDK et le collecteur s'authentifient. - [SDK Python](/fr/agenteye/python-sdk) : envoyez des événements dans Failproof AI Observability pour que ces recettes aient des données à interroger. \ No newline at end of file diff --git a/docs/fr/agenteye/cli-skill.mdx b/docs/fr/agenteye/cli-skill.mdx index 89bb85da..8c891636 100644 --- a/docs/fr/agenteye/cli-skill.mdx +++ b/docs/fr/agenteye/cli-skill.mdx @@ -1,12 +1,12 @@ --- title: "Compétence d'agent CLI Failproof AI Observability" -description: "Demandez à votre agent de développement « est-ce que quelque chose est cassé aujourd'hui ? » et laissez-le répondre à partir de vos données Failproof AI Observability en direct, sans aucune commande à mémoriser." +description: "Demandez à votre agent de code « est-ce que quelque chose est cassé aujourd'hui ? » et laissez-le répondre à partir de vos données Failproof AI Observability en direct, sans aucune commande à mémoriser." --- -Demandez à votre agent de développement *« est-ce que quelque chose est cassé aujourd'hui ? »* et laissez-le répondre à partir de vos données Failproof AI Observability en direct, sans aucune commande à mémoriser. La **compétence CLI Failproof AI Observability** (`agenteye-cli`) est une *compétence d'agent* : un petit dossier d'instructions qu'un agent de développement comme Claude Code ou Codex charge à la demande. Elle apprend à l'agent à piloter votre déploiement Observability via le [CLI `agenteye`](/fr/agenteye/cli) à partir de requêtes en langage naturel comme *« donne à la CI une clé qui ne peut qu'envoyer des événements »* ou *« acquitte l'incident en cours et assigne-le moi »*. +Demandez à votre agent de code *« est-ce que quelque chose est cassé aujourd'hui ? »* et laissez-le répondre à partir de vos données Failproof AI Observability en direct, sans aucune commande à mémoriser. La **compétence CLI Failproof AI Observability** (`agenteye-cli`) est une *Agent Skill* : un petit dossier d'instructions qu'un agent de code tel que Claude Code ou Codex charge à la demande. Elle apprend à l'agent à piloter votre déploiement Observability via la [CLI `agenteye`](/fr/agenteye/cli) à partir de requêtes en langage naturel comme *« donne à la CI une clé qui ne peut qu'envoyer des événements »* ou *« acquitte l'incident en cours et assigne-le-moi »*. -Il **ne s'agit pas** d'un service ni d'un binaire distinct ; il n'y a rien à déployer. La compétence s'appuie sur le CLI déjà installé : l'agent exécute `agenteye --json …`, analyse le JSON propre renvoyé et vous répond en texte clair. Tout ce qu'elle peut faire, vous pourriez le faire vous-même en tapant les mêmes commandes. +Elle n'est **pas** un service ni un binaire séparé ; il n'y a rien à déployer. Elle s'appuie sur la CLI que vous avez déjà installée : l'agent exécute `agenteye --json …`, analyse le JSON propre retourné, et vous répond en prose. Tout ce qu'elle peut faire, vous pourriez le faire vous-même en tapant les mêmes commandes. --- @@ -14,38 +14,38 @@ Il **ne s'agit pas** d'un service ni d'un binaire distinct ; il n'y a rien à d Failproof AI Observability vous offre quatre façons d'accéder aux mêmes données et contrôles. Elles se complètent : -| Interface | Description | Où elle s'exécute | Utilisez-la quand | +| Interface | Ce que c'est | Où ça s'exécute | Utilisez-la quand | |---|---|---|---| -| **[CLI](/fr/agenteye/cli)** | La référence des commandes et options pour `agenteye` | Votre terminal | Vous voulez exécuter ou scripter une commande précise | -| **[Recettes CLI](/fr/agenteye/cli-recipes)** | Modèles `jq`/pipeline à copier-coller | Votre terminal / scripts | Vous intégrez le CLI dans de l'automatisation | -| **Compétence CLI** (ce document) | Une porte d'entrée en langage naturel sur le CLI | Votre agent de développement, sur votre poste | Vous voulez *poser la question* et laisser l'agent choisir la commande | -| **[Compétence Evaluator](/fr/agenteye/evaluator-skill)** | Une compétence jumelle qui conçoit et construit votre service de scoring | Votre agent de développement, sur votre poste | Vous voulez *produire* des scores d'évaluation plutôt que les lire | -| **[Compétence SDK Python](/fr/agenteye/python-sdk-skill)** | Une compétence jumelle qui instrumente votre agent pour qu'il émette de la télémétrie | Votre agent de développement, sur votre poste | Vous voulez que votre agent *produise* les événements que cette compétence lit | -| **[Assistant IA intégré au tableau de bord](/fr/agenteye/assistant)** | Un chat intégré au tableau de bord | Côté serveur (dans le tableau de bord) | Vous voulez des questions-réponses sur vos données directement dans le tableau de bord | +| **[CLI](/fr/agenteye/cli)** | La référence des commandes et options pour `agenteye` | Votre terminal | Vous souhaitez exécuter ou scripter une commande précise | +| **[Recettes CLI](/fr/agenteye/cli-recipes)** | Modèles `jq`/pipeline à copier-coller | Votre terminal / scripts | Vous intégrez la CLI dans une automatisation | +| **Compétence CLI** (ce document) | Une interface en langage naturel sur la CLI | Votre agent de code, sur votre poste de travail | Vous voulez *simplement demander* et laisser l'agent choisir la commande | +| **[Compétence Evaluator](/fr/agenteye/evaluator-skill)** | Une compétence sœur qui conçoit et construit votre service de scoring | Votre agent de code, sur votre poste de travail | Vous souhaitez *produire* des scores d'évaluation plutôt que les lire | +| **[Compétence Python SDK](/fr/agenteye/python-sdk-skill)** | Une compétence sœur qui instrumente votre agent pour qu'il émette de la télémétrie | Votre agent de code, sur votre poste de travail | Vous souhaitez que votre agent *produise* les événements que cette compétence lit | +| **[Assistant IA intégré au tableau de bord](/fr/agenteye/assistant)** | Un chat intégré dans le tableau de bord | Côté serveur (dans le tableau de bord) | Vous souhaitez poser des questions sur vos données depuis le tableau de bord | -La compétence elle-même n'a aucun privilège propre ; elle se contente de transformer vos mots en appels CLI qui s'exécutent en tant que vous : +La compétence elle-même n'a aucun privilège propre ; elle transforme simplement vos mots en appels CLI qui s'exécutent en votre nom : ```mermaid flowchart TD - YOU["vous : 'acquitte l'incident en cours'"] --> AGENT["agent de développement (Claude Code / Codex)
charge la compétence agenteye-cli"] + YOU["vous : 'acquitte l'incident en cours'"] --> AGENT["agent de code (Claude Code / Codex)
charge la compétence agenteye-cli"] AGENT --> CLI["agenteye --json incidents ack ..."] CLI -->|votre session CLI authentifiée| API["API du tableau de bord Observability"] ``` -### vs. l'assistant IA intégré au tableau de bord : une distinction importante +### Comparaison avec l'assistant IA intégré au tableau de bord : une distinction importante Ce sont deux outils différents avec des périmètres d'action très différents : -- L'**assistant IA intégré au tableau de bord** ([assistant IA](/fr/agenteye/assistant)) est un chat intégré au tableau de bord, alimenté par le service d'agent. Il est **en lecture seule avec création soumise à validation** : il peut rédiger des requêtes sauvegardées et des tableaux de bord, mais chaque écriture s'arrête pour demander votre approbation explicite, et il ne supprime jamais rien. Il est conditionné à la permission `agent:use` et ne voit jamais que les données de l'organisation que vous consultez. -- La **compétence CLI** s'exécute sur *votre* poste, dans *votre* agent de développement, et pilote le CLI `agenteye` en tant que **vous**. Elle peut utiliser **toute la surface du CLI, y compris les mutations** (créer/alterner/désactiver des clés API, modifier les paramètres d'organisation, résoudre des incidents, supprimer des requêtes sauvegardées), limitée uniquement par les permissions de votre connexion CLI. Traitez-la exactement avec la même prudence que si vous tapiez ces commandes vous-même. +- L'**assistant IA intégré au tableau de bord** ([assistant IA](/fr/agenteye/assistant)) est un chat intégré dans le tableau de bord, alimenté par le service agent. Il est **en lecture seule avec création soumise à approbation** : il peut rédiger des requêtes sauvegardées et des tableaux de bord, mais chaque écriture attend votre validation explicite par clic, et il ne supprime jamais rien. Il est conditionné par la permission `agent:use` et ne voit que les données de l'organisation que vous consultez. +- La **compétence CLI** s'exécute sur *votre* poste de travail dans *votre* agent de code et pilote la CLI `agenteye` **en tant que vous**. Elle peut effectuer l'**ensemble des opérations de la CLI, y compris les mutations** (créer/renouveler/désactiver des clés API, modifier les paramètres d'organisation, résoudre des incidents, supprimer des requêtes sauvegardées), limité uniquement par les permissions de votre session CLI. Traitez-la exactement avec la même prudence que si vous tapiez ces commandes vous-même. --- ## Prérequis -1. Le **CLI `agenteye` installé** et dans le `PATH` (voir la référence [CLI](/fr/agenteye/cli) : `pipx install agenteye`). +1. La **CLI `agenteye` installée** et dans le `PATH` (voir la référence [CLI](/fr/agenteye/cli) : `pipx install agenteye`). 2. Votre **URL de tableau de bord** configurée (`AGENTEYE_DASHBOARD_URL`, ou l'agent passe `--base-url`). -3. Une **session connectée** : exécutez `agenteye login` vous-même au préalable. La compétence **ne peut pas** effectuer la connexion par code à usage unique envoyé par e-mail à votre place ; elle vous indiquera d'exécuter `agenteye login` si la session est manquante ou expirée (code de sortie CLI `4`). +3. Une **session connectée** : exécutez `agenteye login` vous-même au préalable. La compétence **ne peut pas** effectuer la connexion par code à usage unique envoyé par e-mail à votre place ; elle vous demandera d'exécuter `agenteye login` si la session est absente ou expirée (code de sortie CLI `4`). --- @@ -55,13 +55,13 @@ La compétence est publiée dans la collection publique de compétences de Failp **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -Rien n'est restreint — le dépôt est public et la compétence n'a besoin d'aucun identifiant propre, car elle ne fait que piloter le CLI `agenteye` **public** contre *votre* tableau de bord, en utilisant la session avec laquelle *vous* vous êtes connecté. Vous n'avez besoin de la demander à personne. +Rien n'est restreint — le dépôt est public et la compétence n'a besoin d'aucun identifiant propre, car elle se contente de piloter la CLI **publique** `agenteye` sur *votre* tableau de bord, en utilisant la session avec laquelle *vous* vous êtes connecté. Vous n'avez besoin de demander l'accès à personne. -Notez qu'elle est distribuée dans son propre dossier et **n'est pas** incluse dans le paquet `pipx install agenteye`, donc ne la cherchez pas là. +Notez qu'elle est livrée dans son propre dossier et n'est **pas** incluse dans le paquet `pipx install agenteye`, donc ne la cherchez pas là. ## Installation de la compétence -Le chemin le plus rapide est le CLI [`skills`](https://skills.sh), qui récupère le dossier et le place là où votre agent le cherche : +Le chemin le plus rapide est la CLI [`skills`](https://skills.sh), qui récupère le dossier et le place là où votre agent le cherche : ```bash # Claude Code, ce projet uniquement @@ -82,20 +82,20 @@ npx skills update agenteye-cli # récupérer la dernière version npx skills remove agenteye-cli # la supprimer ``` -Vous préférez installer manuellement ? Une compétence d'agent est simplement un dossier contenant un `SKILL.md` (plus des références optionnelles), donc la copier fonctionne également : +Vous préférez installer manuellement ? Une Agent Skill n'est qu'un dossier contenant un `SKILL.md` (plus des références optionnelles), donc la copier fonctionne aussi : -- **Claude Code** : placez le dossier `agenteye-cli/` dans `~/.claude/skills/` (tous les projets) ou `/.claude/skills/` (ce dépôt uniquement). Claude Code la détecte automatiquement — vérifiez avec la liste `/skills`, ou posez simplement une question correspondant à sa description. -- **Codex (OpenAI)** : Codex lit le même `SKILL.md`. Le fichier `agents/openai.yaml` inclus définit `allow_implicit_invocation: true`, donc Codex sélectionne automatiquement la compétence quand une tâche correspond ; sinon, invoquez-la explicitement avec `$agenteye-cli`. +- **Claude Code** : placez le dossier `agenteye-cli/` dans `~/.claude/skills/` (tous les projets) ou `/.claude/skills/` (ce dépôt uniquement). Claude Code le découvre automatiquement — vérifiez avec la liste `/skills`, ou posez simplement une question correspondant à sa description. +- **Codex (OpenAI)** : Codex lit le même `SKILL.md`. Le fichier `agents/openai.yaml` inclus définit `allow_implicit_invocation: true`, ainsi Codex sélectionne automatiquement la compétence lorsqu'une tâche correspond ; sinon invoquez-la explicitement en tant que `$agenteye-cli`. --- -## Sécurité : les mutations ne demandent PAS confirmation quand un agent exécute le CLI +## Sécurité : les mutations ne demandent PAS de confirmation quand un agent exécute la CLI > **Avertissement :** Lisez ceci avant de laisser un agent effectuer des modifications. -Le CLI `agenteye` demande normalement *« êtes-vous sûr ? »* avant une action destructive. Il **saute automatiquement cette confirmation dès qu'il n'est pas attaché à un terminal (ce qui correspond exactement à la façon dont un agent de développement l'exécute), et `--json` la saute également.** Ainsi, la demande de confirmation **ne se déclenchera pas** pour l'agent. +La CLI `agenteye` demande normalement *« êtes-vous sûr ? »* avant une action destructrice. Elle **ignore automatiquement cette confirmation dès qu'elle n'est pas attachée à un terminal (ce qui est précisément la façon dont un agent de code l'exécute), et `--json` l'ignore également.** Ainsi, l'invite de confirmation **ne se déclenchera pas** pour l'agent. -La compétence est conçue pour compenser : elle est instruite d'énoncer la commande exacte qu'elle va exécuter et d'obtenir votre **accord explicite avant tout changement d'état**. Maintenez cette discipline. Lorsque vous pilotez Failproof AI Observability via un agent, *vous* êtes l'étape de confirmation. Les commandes modifiant l'état à surveiller : +La compétence est conçue pour compenser cela : elle a pour instruction d'indiquer la commande exacte qu'elle va exécuter et d'obtenir votre **accord explicite avant tout changement d'état**. Maintenez cette discipline. Lorsque vous pilotez Failproof AI Observability via un agent, *vous* êtes l'étape de confirmation. Les commandes qui modifient l'état à surveiller : - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` @@ -106,18 +106,18 @@ La compétence est conçue pour compenser : elle est instruite d'énoncer la com - `agent rename` / `delete` - `orgs switch` -Tout ce qui relève de la section **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) est en lecture seule et ne modifie rien. +Tout ce qui se trouve sous **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) est en lecture seule et ne modifie rien. -L'agent agissant en tant que **vous**, il ne peut faire que ce que votre connexion est autorisée à faire ; les permissions sont résolues **par organisation** (voir [Clés API](/fr/agenteye/api-keys)). Une commande pour laquelle vous n'avez pas la permission renvoie le code de sortie `5` avec le nom exact de la permission manquante, ce qui permet à l'agent de vous indiquer précisément ce qu'il faut demander à un administrateur plutôt que d'échouer silencieusement. +L'agent agissant **en tant que vous**, il ne peut effectuer que ce que votre session est autorisée à faire ; les permissions sont résolues **par organisation** (voir [Clés API](/fr/agenteye/api-keys)). Une commande pour laquelle vous n'avez pas la permission retourne le code de sortie `5` avec le nom exact de la permission manquante, ce qui permet à l'agent de vous indiquer précisément quoi demander à un administrateur plutôt que d'échouer sans explication. --- ## Ce que vous pouvez lui demander -Voici à quoi ressemble un vrai échange — une lecture, puis une modification qui attend votre accord : +Voici à quoi ressemble un véritable échange — une lecture, puis une modification qui attend votre accord : ```text -vous ▸ Est-ce que quelque chose est cassé ces dernières 24 heures ? +vous ▸ Est-ce que quelque chose est cassé depuis hier ? agent ▸ Exécution : agenteye --json errors --since 24h --aggregate 3 types d'erreurs dans les dernières 24h. Le plus fréquent est TimeoutError @@ -126,34 +126,34 @@ agent ▸ Exécution : agenteye --json errors --since 24h --aggregate vous ▸ Donne à la CI une clé qui ne peut qu'envoyer des événements. -agent ▸ Cela crée une clé API. Je vais exécuter : +agent ▸ Cela va créer une clé API. Je vais exécuter : agenteye keys create ci --add events:add - D'accord pour continuer ? + Confirmer ? vous ▸ oui agent ▸ Fait. Clé « ci » créée avec events:add uniquement. - Le secret n'est affiché qu'une seule fois, enregistrez-le maintenant. Je ne peux pas le réafficher. + Le secret n'est affiché qu'une seule fois, sauvegardez-le maintenant. Je ne peux pas le réafficher. ``` -La compétence associe chaque intention exprimée en langage naturel à la bonne commande `agenteye`, en découvrant d'abord les valeurs valides (`list `, `whoami`) pour ne pas deviner, et en énonçant la commande exacte avant tout changement. Quelques exemples supplémentaires : +La compétence associe chaque intention exprimée en langage naturel à la bonne commande `agenteye`, en découvrant d'abord les valeurs valides (`list `, `whoami`) pour ne pas deviner, et en indiquant la commande exacte avant tout changement. Autres exemples : -- *« Est-ce que quelque chose est cassé / en échec ces dernières 24 heures ? »* → `errors --since 24h --aggregate`, puis un récapitulatif. +- *« Est-ce que quelque chose est cassé / en échec dans les dernières 24 heures ? »* → `errors --since 24h --aggregate`, puis une ventilation détaillée. - *« Pourquoi la session `run-001` a-t-elle échoué ? »* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *« Comment évolue la qualité cette semaine ? »* → `evals --aggregate --since 7d`, puis exploration des exécutions avec les scores les plus bas. -- *« Donne à la CI une clé qui ne peut qu'envoyer des événements. »* → `keys create ci --add events:add` (elle énonce la commande, puis la crée et capture le secret à usage unique). -- *« Qui a accès ? Mets Dana en lecture seule. »* → `users list` → `users update dana@… --permission-set read-only` (après confirmation de votre part). -- *« Acquitte l'incident en cours et assigne-le moi. »* → `incidents list --state firing` → `incidents ack ` / `incidents assign vous@…`. +- *« Comment évolue la qualité cette semaine ? »* → `evals --aggregate --since 7d`, puis exploration des exécutions avec un faible score. +- *« Donne à la CI une clé qui ne peut qu'envoyer des événements. »* → `keys create ci --add events:add` (elle indique la commande, puis la crée et capture le secret à usage unique). +- *« Qui a accès ? Passe Dana en lecture seule. »* → `users list` → `users update dana@… --permission-set read-only` (après confirmation de votre part). +- *« Acquitte l'incident en cours et assigne-le-moi. »* → `incidents list --state firing` → `incidents ack ` / `incidents assign vous@…`. -Pour les commandes exactes, les options et les structures JSON correspondantes, consultez la référence [CLI](/fr/agenteye/cli) et les [recettes CLI pour agents](/fr/agenteye/cli-recipes). +Pour les commandes exactes, les options et les formats JSON correspondants, consultez la référence [CLI](/fr/agenteye/cli) et les [recettes CLI pour agents](/fr/agenteye/cli-recipes). --- -## Prochaines étapes +## Étapes suivantes - **[CLI](/fr/agenteye/cli)** : référence complète des commandes et options pour `agenteye`. - **[Recettes CLI pour agents](/fr/agenteye/cli-recipes)** : modèles `jq` à copier-coller et gestion des codes de sortie. -- **[Compétence d'agent Evaluator](/fr/agenteye/evaluator-skill)** : la compétence jumelle, pour construire l'évaluateur dont les scores sont lus par `agenteye evals`. -- **[Compétence d'agent SDK Python](/fr/agenteye/python-sdk-skill)** : la compétence jumelle, pour instrumenter un agent afin qu'il émette la télémétrie lue par `agenteye`. +- **[Compétence agent Evaluator](/fr/agenteye/evaluator-skill)** : la compétence sœur, pour construire l'évaluateur dont les scores sont lus par `agenteye evals`. +- **[Compétence agent Python SDK](/fr/agenteye/python-sdk-skill)** : la compétence sœur, pour instrumenter un agent afin qu'il émette la télémétrie lue par `agenteye`. - **[Assistant IA](/fr/agenteye/assistant)** : l'assistant intégré au tableau de bord (à ne pas confondre avec cette compétence en ligne de commande). - **[Clés API](/fr/agenteye/api-keys)** : le modèle de permissions par organisation qui délimite ce que la compétence peut faire. \ No newline at end of file diff --git a/docs/fr/agenteye/cli.mdx b/docs/fr/agenteye/cli.mdx index f9b7259a..82011661 100644 --- a/docs/fr/agenteye/cli.mdx +++ b/docs/fr/agenteye/cli.mdx @@ -1,25 +1,25 @@ --- title: "CLI" -description: "Pilotez toute l'Observabilité Failproof AI depuis le terminal ou un script : sans aller-retours vers le tableau de bord." +description: "Pilotez toute l'observabilité Failproof AI depuis le terminal ou un script, sans aller-retours vers le tableau de bord." --- -Pilotez toute l'Observabilité Failproof AI depuis le terminal ou un script : sans aller-retours vers le tableau de bord. La CLI `agenteye` interroge vos données (sessions, journaux d'événements, évaluations) et administre votre organisation (clés API, utilisateurs, paramètres, alertes, incidents, requêtes sauvegardées), afin que vous puissiez automatiser une vérification, intégrer l'Observabilité dans votre CI ou permettre à un agent de code d'inspecter la production. Chaque commande prend en charge un flag `--json`, ce qui la rend tout aussi utile à la ligne de commande ou pour un agent de code (Claude Code, Cursor) qui exécute des commandes shell et analyse les résultats. +Pilotez toute l'observabilité Failproof AI depuis le terminal ou un script, sans aller-retours vers le tableau de bord. Le CLI `agenteye` interroge vos données (sessions, journaux d'événements, évaluations) et administre votre organisation (clés API, utilisateurs, paramètres, alertes, incidents, requêtes sauvegardées), ce qui en fait l'outil idéal pour automatiser une vérification, intégrer l'observabilité dans votre CI, ou laisser un agent de code inspecter la production. Chaque commande accepte un flag `--json`, ce qui le rend aussi bien adapté à un usage interactif qu'à un agent de code (Claude Code, Cursor) qui exécute des commandes et analyse les résultats. Avec un seul binaire, vous pouvez : -- **Lire vos données** : `sessions`, `events`, `evals`, `errors` (filtrage par heure, agent, environnement, score). +- **Lire vos données** : `sessions`, `events`, `evals`, `errors` (filtrer par heure, agent, environnement, score). - **Gérer votre organisation** : `keys`, `users`, `settings`, `alerts`, `incidents`. -- **Lancer des analyses** : SQL sauvegardé et exécuteur de requêtes ad hoc (`query`). -- **Interroger l'assistant IA** : le même analyste en lecture seule que vous utilisez dans le tableau de bord (`agent`). +- **Exécuter des analyses** : SQL sauvegardé et exécuteur de requêtes ad hoc (`query`). +- **Interroger l'assistant IA** : le même analyste en lecture seule accessible depuis le tableau de bord (`agent`). -> **Remarque :** Il s'agit de la CLI `agenteye`, un outil distinct du démon collecteur (`agenteye-collector`). La CLI communique avec votre tableau de bord ; le collecteur achemine les événements vers le serveur. +> **Remarque :** Il s'agit du CLI `agenteye`, un outil distinct du démon collecteur (`agenteye-collector`). Le CLI communique avec votre tableau de bord ; le collecteur achemine les événements vers le serveur. --- ## Démarrage rapide -De zéro à votre premier résultat en quatre lignes. Pointez la CLI vers votre tableau de bord, connectez-vous, confirmez votre identité, puis récupérez les exécutions du dernier jour : +De zéro à votre premier résultat en quatre lignes. Pointez le CLI vers votre tableau de bord, connectez-vous, confirmez votre identité, puis récupérez les exécutions des dernières 24 heures : ```bash pipx install agenteye @@ -28,7 +28,7 @@ agenteye whoami agenteye --json sessions --since 24h # une ligne par exécution d'agent, dernières 24h ``` -Cette dernière commande affiche un objet JSON des sessions les plus récentes (les plus récentes en premier, limité à 50 par défaut). Canalisez-le dans `jq` pour le découper, ou supprimez `--json` pour un tableau encadré et colorisé. Chaque ligne contient le statut de l'exécution et, si un évaluateur l'a scorée, ses scores de métriques (abrégés ici) : +Cette dernière commande affiche un objet JSON des sessions les plus récentes (les plus récentes en premier, limité à 50 par défaut). Redirigez-le vers `jq` pour le filtrer, ou supprimez `--json` pour obtenir un tableau encadré et colorisé. Chaque ligne contient le statut de l'exécution et, si un évaluateur l'a noté, ses scores de métriques (abrégé ici) : ```json { @@ -48,13 +48,13 @@ Cette dernière commande affiche un objet JSON des sessions les plus récentes ( } ``` -Le reste de cette page explique chaque élément : [l'installation](#installation) en isolation, [la connexion](#authentication), [la configuration](#configuration), les [conventions globales](#global-options--conventions) partagées par toutes les commandes, et la [référence complète des commandes](#command-reference). +Le reste de cette page explique chaque aspect : [l'installation](#installation) en isolation, [la connexion](#authentication), [la configuration](#configuration), les [conventions globales](#global-options--conventions) partagées par toutes les commandes, et la [référence complète des commandes](#command-reference). --- ## Installation -La CLI est un paquet PyPI public nommé **`agenteye`**. Installez-le dans un environnement isolé afin qu'il dispose toujours de ses propres dépendances : +Le CLI est un package PyPI public nommé **`agenteye`**. Installez-le dans un environnement isolé afin qu'il dispose toujours de ses propres dépendances : ```bash pipx install agenteye @@ -69,29 +69,29 @@ agenteye --version agenteye --help ``` -> **Remarque :** Le SDK Python d'Observabilité Failproof AI utilise également le nom de distribution `agenteye`. Installer la CLI avec `pipx` ou `uv tool` (plutôt que `pip install` dans un virtualenv partagé) évite les conflits entre les deux. Un simple `pip install agenteye` convient uniquement si le SDK n'est pas installé dans le même environnement. +> **Remarque :** Le SDK Python d'observabilité Failproof AI utilise également le nom de distribution `agenteye`. Installer le CLI avec `pipx` ou `uv tool` (plutôt que `pip install` dans un virtualenv partagé) évite les conflits entre les deux. Un simple `pip install agenteye` ne pose problème que si le SDK n'est pas installé dans le même environnement. --- ## Authentification -La CLI s'authentifie auprès du **tableau de bord** avec un code à usage unique envoyé par e-mail : +Le CLI s'authentifie auprès du **tableau de bord** avec un code unique envoyé par e-mail : ```bash agenteye login --email you@example.com # Un code à 6 chiffres vous est envoyé par e-mail ; collez-le à l'invite. ``` -Le jeton de session est stocké dans `~/.agenteye/cli.json` (lisible uniquement par vous, mode `0600`) et est valide pendant 24 heures par défaut. Lorsqu'il expire, relancez `agenteye login`. +Le jeton de session est stocké dans `~/.agenteye/cli.json` (accessible uniquement par vous, mode `0600`) et est valide pendant 24 heures par défaut. À l'expiration, relancez `agenteye login`. ```bash -agenteye whoami # afficher l'utilisateur courant, l'org active et les permissions +agenteye whoami # afficher l'utilisateur actuel, l'org active et les permissions agenteye logout # révoquer la session et effacer le jeton stocké ``` -`whoami` ne génère jamais d'erreur en cas de session manquante ou expirée ; il renvoie `logged_in: false` à la place, afin qu'un script ou un agent puisse sonder l'état d'authentification en toute sécurité (il peut tout de même retourner un code non nul si aucune URL de base n'est définie ou si le tableau de bord est inaccessible). +`whoami` ne génère jamais d'erreur en cas de session absente ou expirée ; il renvoie `logged_in: false` à la place, ce qui permet à un script ou à un agent de sonder l'état d'authentification en toute sécurité (il peut quand même renvoyer un code non nul si aucune URL de base n'est définie ou si le tableau de bord est inaccessible). -**Prérequis :** votre e-mail doit être autorisé à se connecter au tableau de bord (demandez à votre administrateur d'Observabilité Failproof AI), et le tableau de bord doit être accessible à son URL de base (voir [Configuration](#configuration)). Si vous demandez un code et qu'il n'arrive pas, votre e-mail n'est probablement pas encore activé pour l'accès au tableau de bord. +**Prérequis :** votre adresse e-mail doit être autorisée à se connecter au tableau de bord (contactez votre administrateur Failproof AI Observability), et le tableau de bord doit être accessible à son URL de base (voir [Configuration](#configuration)). Si vous demandez un code et qu'aucun n'arrive, votre adresse e-mail n'est probablement pas encore activée pour l'accès au tableau de bord. --- @@ -102,55 +102,55 @@ Si votre compte appartient à plusieurs organisations, choisissez l'organisation ```bash agenteye login --org acme # s'authentifier et définir le tenant actif en une seule étape agenteye orgs list # les orgs auxquelles vous avez accès (l'active est marquée) -agenteye orgs switch globex # changer la valeur par défaut sauvegardée +agenteye orgs switch globex # changer le défaut sauvegardé agenteye --org globex sessions # remplacer pour une seule commande ``` -Si vous n'appartenez qu'à une seule organisation, elle est sélectionnée automatiquement et vous pouvez ignorer `--org` entièrement. Si vous appartenez à plusieurs et que vous n'en choisissez pas une, la CLI les liste et vous demande de relancer avec `--org `. L'org active est transmise au tableau de bord à chaque requête, et vos permissions sont résolues **par organisation** ; `agenteye whoami` affiche l'org active, vos permissions en son sein, et toutes vos appartenances. +Si vous n'appartenez qu'à une seule organisation, elle est sélectionnée automatiquement et vous pouvez ignorer `--org` entièrement. Si vous en avez plusieurs et n'en choisissez pas, le CLI les liste et vous demande de relancer avec `--org `. L'organisation active est envoyée au tableau de bord à chaque requête, et vos permissions sont résolues **par organisation** ; `agenteye whoami` affiche l'org active, vos permissions dans celle-ci, et toutes vos appartenances. --- ## Configuration -| Paramètre | Flag | Variable d'environnement | Défaut | +| Paramètre | Flag | Variable d'environnement | Valeur par défaut | |---|---|---|---| | URL de base du tableau de bord | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **obligatoire** (pas de défaut) | | Org/tenant actif | `--org` | `AGENTEYE_ORG` | choisi à la connexion ; sauvegardé dans `~/.agenteye/cli.json` | | Jeton de session | `--token` | `AGENTEYE_CLI_TOKEN` | depuis `~/.agenteye/cli.json` | | Sortie JSON | `--json` | `AGENTEYE_CLI_JSON` | désactivé | | Ignorer la vérification TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | désactivé (sauvegardé à la connexion) | -| Délai de requête (secondes) | `--timeout` | _(aucune)_ | 30 | +| Délai d'attente des requêtes (secondes) | `--timeout` | _(aucune)_ | 30 | | Désactiver la télémétrie d'utilisation | _(aucun)_ | `AGENTEYE_ANALYTICS_DISABLED` (ou `DO_NOT_TRACK`) | la télémétrie est actuellement désactivée ; rien n'est envoyé | -L'ordre de résolution est **flag → variable d'environnement → fichier de configuration**. Il n'y a pas de valeur par défaut ; vous devez pointer la CLI vers votre tableau de bord, soit par commande (`--base-url https://agenteye.example.com`), soit une fois via l'environnement (elle est également sauvegardée après votre premier `login`) : +L'ordre de résolution est **flag → variable d'environnement → fichier de configuration**. Il n'y a pas de valeur par défaut ; vous devez pointer le CLI vers votre tableau de bord, soit par commande (`--base-url https://agenteye.example.com`), soit une seule fois via l'environnement (il est également sauvegardé après votre premier `login`) : ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -Le répertoire de configuration respecte `AGENTEYE_HOME` (la même convention utilisée par le SDK et le collecteur) ; si défini, `cli.json` se trouve dans `$AGENTEYE_HOME/cli.json`. +Le répertoire de configuration respecte `AGENTEYE_HOME` (la même convention utilisée par le SDK et le collecteur) ; s'il est défini, `cli.json` se trouve dans `$AGENTEYE_HOME/cli.json`. ### TLS auto-signé ou interne -Si votre tableau de bord est servi via HTTPS avec un certificat auto-signé ou interne (par exemple, un nom d'hôte de load-balancer brut), la vérification TLS le rejettera avec une erreur `CERTIFICATE_VERIFY_FAILED`. Utilisez `--insecure` pour ignorer la vérification du certificat : +Si votre tableau de bord est servi via HTTPS avec un certificat auto-signé ou interne (par exemple, un nom d'hôte de load balancer brut), la vérification TLS le rejette avec une erreur `CERTIFICATE_VERIFY_FAILED`. Passez `--insecure` pour ignorer la vérification du certificat : ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` est **sauvegardé dans `cli.json` lors de la connexion**, de sorte que les commandes ultérieures ignorent automatiquement la vérification ; vous n'avez pas à répéter le flag. Utilisez `--secure` pour un appel vérifié ponctuel, ou pour réactiver la vérification lors de votre prochaine connexion. La CLI affiche un avertissement sur stderr avant toute commande qui contacte le tableau de bord avec la vérification désactivée. Ignorer la vérification supprime la protection contre les attaques de type man-in-the-middle ; assurez-vous de faire confiance au chemin réseau vers votre tableau de bord (VPN, sous-réseau privé, etc.) avant de vous en remettre à cette option. +`--insecure` est **sauvegardé dans `cli.json` lors de la connexion**, de sorte que les commandes ultérieures ignorent automatiquement la vérification ; vous n'avez pas à répéter le flag. Passez `--secure` pour un appel vérifié ponctuel, ou pour réactiver la vérification lors de votre prochaine connexion. Le CLI affiche un avertissement sur stderr avant toute commande qui contacte le tableau de bord alors que la vérification est désactivée. Ignorer la vérification supprime la protection contre les attaques de type man-in-the-middle ; assurez-vous de faire confiance au chemin réseau vers votre tableau de bord (VPN, sous-réseau privé, etc.) avant de vous y fier. --- ## Télémétrie et confidentialité -> **Remarque :** La CLI fournie **n'envoie aucune télémétrie d'utilisation aujourd'hui.** Un interrupteur maître est activé, de sorte que rien n'est transmis quelle que soit votre configuration. La section ci-dessous décrit la fonctionnalité de désactivation pour le cas où la télémétrie serait un jour activée. +> **Remarque :** Le CLI fourni n'envoie **aucune télémétrie d'utilisation aujourd'hui.** Un interrupteur général est activé, de sorte que rien n'est transmis quel que soit votre environnement. La section ci-dessous décrit la fonctionnalité de désinscription pour le cas où la télémétrie serait un jour activée. -Même si elle était activée, la télémétrie se limiterait à des **analyses d'utilisation anonymes**, jamais à vos données d'agent, de session ou d'événement : +Même si elle était activée, la télémétrie ne concernerait que des **analyses d'utilisation anonymes**, jamais vos données d'agent, de session ou d'événement : -- **Aucune donnée d'agent, de session ou d'événement ne quitte jamais votre infrastructure.** Seule l'utilisation de la CLI serait rapportée : le nom de la commande et de la sous-commande (ex. `keys create`), les **noms** des flags utilisés (jamais leurs valeurs), le statut de succès/sortie, et la durée, ainsi qu'un événement par action pour les mutations (ex. `api_key_created`, `query_run`) ne comportant que des noms/enums statiques et des comptages grossiers. Votre URL de tableau de bord, jeton de session, e-mail, slug d'org, identifiants de ressources, SQL, secrets de clés et filtres de requêtes ne seraient **jamais** envoyés. Les opérateurs ne seraient identifiés que par un identifiant interne opaque, jamais par e-mail. -- **Désactivez à l'avance** en définissant `AGENTEYE_ANALYTICS_DISABLED=1` dans l'environnement de la CLI (la CLI respecte également la convention inter-outils `DO_NOT_TRACK=1`). Cela prend effet dès que la télémétrie serait activée, de sorte qu'un environnement soucieux de la confidentialité peut rester désactivé en permanence. -- Si la télémétrie était activée, la CLI enverrait directement à PostHog (`https://us.i.posthog.com`) ; une machine avec cet hôte bloqué n'enverrait rien silencieusement et la CLI ne serait pas affectée. +- **Aucune donnée d'agent, de session ou d'événement ne quitte jamais votre infrastructure.** Seule l'utilisation du CLI serait reportée : le nom de la commande et de la sous-commande (p. ex. `keys create`), les **noms** des flags utilisés (jamais leurs valeurs), le statut de succès/sortie et la durée, ainsi qu'un événement par action pour les mutations (p. ex. `api_key_created`, `query_run`) ne portant que des noms/enums statiques et des comptages grossiers. Votre URL de tableau de bord, jeton de session, e-mail, slug d'org, identifiants de ressources, SQL, secrets de clés et filtres de requête ne seraient **jamais** envoyés. Les opérateurs ne seraient identifiés que par un identifiant interne opaque, jamais par e-mail. +- **Désactivez à l'avance** en définissant `AGENTEYE_ANALYTICS_DISABLED=1` dans l'environnement du CLI (le CLI respecte également la convention inter-outils `DO_NOT_TRACK=1`). Cela prend effet dès que la télémétrie est éventuellement activée, ce qui permet à un environnement soucieux de la confidentialité de rester définitivement désinscrit. +- Si la télémétrie était activée, le CLI enverrait directement à PostHog (`https://us.i.posthog.com`) ; une machine ayant cet hôte bloqué n'enverrait rien en silence et le CLI ne serait pas affecté. --- @@ -159,14 +159,14 @@ Même si elle était activée, la télémétrie se limiterait à des **analyses Lisez ceci une fois ; cela s'applique à chaque commande. - **Les options globales vont AVANT la commande.** `agenteye --json sessions` est correct ; `agenteye sessions --json` est une erreur d'utilisation. Les options globales sont `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` et `--no-color`. -- **`--json` affiche du JSON pur sur stdout, et rien d'autre.** Les lignes de statut humain, les avertissements et les erreurs vont sur **stderr**, de sorte qu'une capture stdout avec `--json` reste propre pour être canalisée dans `jq` même lorsqu'une ligne de statut est affichée. Sans `--json`, vous obtenez une vue encadrée et colorisée pour les yeux humains. -- **Explorez avec `--help`.** Chaque commande et sous-commande dispose de `--help` (et de l'alias `-h`) : `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. L'aide de niveau supérieur liste également les codes de sortie et les options globales. Il n'existe pas de surface lisible par machine globale ; utilisez `--help` par commande, ainsi que `agenteye query schema` et `agenteye settings schema` spécifiques au domaine pour ces deux registres. -- **Les confirmations sont ignorées automatiquement pour les scripts et les agents.** Les commandes de création/mise à jour/suppression demandent "êtes-vous sûr ?" dans un terminal interactif, mais **ignorent automatiquement cette invite sous `--json` ou lorsque stdin n'est pas un TTY** (un TTY est une session de terminal interactive ; un pipe ou un runner CI ne l'est pas), de sorte que les scripts et les agents ne se bloquent jamais. Utilisez `--yes`/`-y` pour l'ignorer explicitement. Comme l'invite ne se déclenchera pas pour un agent, un agent devrait confirmer les actions destructrices avec l'humain en amont. -- **Pagination :** les résultats sont classés du plus récent au plus ancien et paginés par curseur (chaque page retourne un jeton à utiliser pour récupérer la suivante). `--limit N` (alias `-n`) plafonne les lignes et **vaut 50 par défaut** ; `--all` pagine automatiquement (par blocs de 200 lignes) **jusqu'à `--limit`**, donc un simple `--all` s'arrête toujours à 50. Pour un balayage complet, passez une limite explicite élevée : `--all --limit 1000`. `--page-size N` contrôle la taille des blocs par requête (max 200) ; `--cursor ` reprend à partir du `next_cursor` d'une page précédente. -- **Filtres temporels :** `--since` accepte une fenêtre relative : `15m`, `1h`, `6h`, `24h`, `7d`, ou `all` (les présélections du tableau de bord). Pour une plage plus longue ou personnalisée (par exemple les 30 derniers jours), utilisez `--from`/`--to` : des horodatages UTC ISO-8601 explicites **avec `T` et un fuseau horaire** (ex. `2026-06-01T00:00:00Z`) qui remplacent `--since`. Une valeur séparée par des espaces ou sans fuseau horaire est une erreur d'utilisation. -- **`--fields a,b,c`** (sur `events`, `sessions`, `evals`, `errors`) restreint la sortie à ces clés, aussi bien pour le tableau que pour `--json`. Les noms inconnus sont rejetés avec la liste des noms valides, un moyen pratique de découvrir les noms de champs. -- **`--file payload.json`** (ou `--file -` pour lire depuis stdin) fournit un corps de requête JSON complet lorsqu'une ressource a une forme complexe (sur `alerts create/update`, `settings set` et `users create/update`). Le SQL de requête sauvegardée utilise `--sql @file.sql` à la place. -- **Les filtres multi-valeurs** sont séparés par des virgules → correspondance sous forme d'ensemble (union dans un filtre, ET entre filtres) : `--event-type tool_use,tool_result`. Les options Click ne sont pas variadiques, donc `--add a b` ne fonctionne pas. Utilisez `--add a,b`, répétez le flag (`--add a --add b`), ou mettez entre guillemets (`--add "a b"`). +- **`--json` affiche du JSON pur sur stdout, et rien d'autre.** Les lignes de statut humaines, les avertissements et les erreurs vont sur **stderr**, de sorte qu'une capture stdout avec `--json` reste propre pour être redirigée vers `jq` même lorsqu'une ligne de statut est affichée. Sans `--json`, vous obtenez une vue encadrée et colorisée pour les yeux humains. +- **Explorez avec `--help`.** Chaque commande et sous-commande dispose de `--help` (et de l'alias `-h`) : `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. L'aide de haut niveau liste également les codes de sortie et les options globales. Il n'y a pas de surface lisible par machine au niveau global ; utilisez `--help` par commande, ainsi que les commandes spécifiques `agenteye query schema` et `agenteye settings schema` pour ces deux registres. +- **Les confirmations sont automatiquement ignorées pour les scripts et les agents.** Les commandes de création/mise à jour/suppression affichent un message de confirmation dans un terminal interactif, mais **ignorent automatiquement cette invite sous `--json` ou chaque fois que stdin n'est pas un TTY** (un TTY est une session de terminal interactive ; un pipe ou un runner CI ne l'est pas), de sorte que les scripts et les agents ne se bloquent jamais. Passez `--yes`/`-y` pour l'ignorer explicitement. Comme l'invite ne se déclenchera pas pour un agent, un agent doit confirmer les actions destructrices avec l'humain au préalable. +- **Pagination :** les résultats sont les plus récents en premier et paginés par curseur (chaque page renvoie un jeton à utiliser pour récupérer la suivante). `--limit N` (alias `-n`) limite les lignes et **vaut 50 par défaut** ; `--all` pagine automatiquement (par blocs de 200 lignes) **jusqu'à `--limit`**, donc un simple `--all` s'arrête quand même à 50. Pour un balayage complet, passez une limite explicite élevée : `--all --limit 1000`. `--page-size N` contrôle le bloc par requête (max 200) ; `--cursor ` reprend depuis le `next_cursor` d'une page précédente. +- **Filtres temporels :** `--since` prend une fenêtre relative : `15m`, `1h`, `6h`, `24h`, `7d` ou `all` (les préréglages du tableau de bord). Pour une plage plus longue ou personnalisée (par exemple les 30 derniers jours), utilisez `--from`/`--to` : des horodatages UTC ISO-8601 explicites **avec `T` et un fuseau horaire** (p. ex. `2026-06-01T00:00:00Z`) qui remplacent `--since`. Une valeur séparée par un espace ou sans fuseau horaire est une erreur d'utilisation. +- **`--fields a,b,c`** (sur `events`, `sessions`, `evals`, `errors`) restreint la sortie à ces clés, aussi bien pour le tableau que pour `--json`. Les noms inconnus sont rejetés avec la liste valide, un moyen simple de découvrir les noms de champs. +- **`--file payload.json`** (ou `--file -` pour lire stdin) fournit un corps de requête JSON complet lorsqu'une ressource a une forme complexe (sur `alerts create/update`, `settings set` et `users create/update`). Le SQL des requêtes sauvegardées utilise `--sql @file.sql` à la place. +- **Les filtres multi-valeurs** sont séparés par des virgules → correspondant à un ensemble (union au sein d'un filtre, ET entre les filtres) : `--event-type tool_use,tool_result`. Les options Click ne sont pas variadiques, donc `--add a b` échoue. Utilisez `--add a,b`, répétez le flag (`--add a --add b`), ou mettez entre guillemets (`--add "a b"`). --- @@ -174,28 +174,28 @@ Lisez ceci une fois ; cela s'applique à chaque commande. ### Les 5 commandes que vous utiliserez le plus -La plupart du travail quotidien passe par quelques commandes de lecture. Commencez ici, puis explorez la surface complète ci-dessous si nécessaire : +La plupart des tâches quotidiennes passent par quelques commandes de lecture. Commencez ici, puis explorez la surface complète ci-dessous quand vous en avez besoin : | Commande | Ce qu'elle fait | Essayez | |---|---|---| | `sessions` | Une ligne par exécution d'agent : heure, env, agent, statut, dernier score. | `agenteye --json sessions --since 24h --status error` | | `events` | La trace brute étape par étape dans une exécution (ajoutez `--full` pour les payloads). | `agenteye --json events --session-id run-001 --all` | -| `evals` | Résultats d'évaluation et scores ; `--aggregate` les agrège. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `evals` | Résultats d'évaluation et scores ; `--aggregate` les regroupe. | `agenteye --json evals --aggregate --since 7d --env prod` | | `errors` | Uniquement les événements en erreur ; `--aggregate` pour les comptages par type. | `agenteye --json errors --since 24h --aggregate` | | `list` | Découvrir les valeurs de filtre valides (agents, envs, modèles, …). | `agenteye list agents` | -### Tout ce que la CLI peut faire +### Tout ce que le CLI peut faire -La surface complète suit. La CLI dispose de **18 commandes de premier niveau**. Toutes les commandes de lecture acceptent `--json` et les options globales ci-dessus ; exécutez `agenteye -h` (ou ` -h`) pour la liste exhaustive des flags et la structure JSON de n'importe quelle commande. +La surface complète suit. Le CLI dispose de **18 commandes de premier niveau**. Toutes les commandes de lecture acceptent `--json` et les options globales ci-dessus ; exécutez `agenteye -h` (ou ` -h`) pour la liste exhaustive des flags et la forme JSON de n'importe quelle commande. ### Identité : `login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash -agenteye login --email you@example.com [--org acme] # code à usage unique par e-mail ; sauvegarde la session +agenteye login --email you@example.com [--org acme] # code unique par e-mail ; sauvegarde la session agenteye logout # effacer la session sauvegardée sur cette machine -agenteye whoami # utilisateur courant, org active, permissions -agenteye version # afficher la version de la CLI (identique à --version) -agenteye help # aide de niveau supérieur (identique à --help) +agenteye whoami # utilisateur actuel, org active, permissions +agenteye version # afficher la version du CLI (identique à --version) +agenteye help # aide de haut niveau (identique à --help) ``` `orgs` inspecte et change le tenant actif : @@ -204,15 +204,15 @@ agenteye help # aide de niveau supérieu agenteye orgs list # vos orgs + votre rôle dans chacune (l'active est marquée) agenteye orgs switch acme # changer l'org active sauvegardée (omettez le slug pour choisir dans une liste sur un TTY) agenteye orgs current # carte d'identité de l'org active -agenteye orgs perms # vos permissions dans l'org active, groupées par ressource +agenteye orgs perms # vos permissions dans l'org active, regroupées par ressource ``` ### Observer (lecture seule) : `events` · `sessions` · `evals` · `errors` · `list` -Aucune de ces commandes n'a besoin de confirmation. Filtres partagés : `--session-id`, `--agent-id`, `--env` (**pas** `--environment`), et la plage temporelle (`--since` / `--from` / `--to`). +Aucune de ces commandes ne nécessite de confirmation. Filtres partagés : `--session-id`, `--agent-id`, `--env` (**pas** `--environment`), et la plage temporelle (`--since` / `--from` / `--to`). ```bash -# events (alias : la trace brute étape par étape), plus récents en premier +# events (alias : la trace brute étape par étape), les plus récents en premier agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' @@ -220,11 +220,11 @@ agenteye --json events --since 1h --search timeout --all | jq '.events[].payload agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 -# evals : résultats d'évaluation + scores ; --score filtre par métrique, --aggregate agrège +# evals : résultats d'évaluation + scores ; --score filtre par métrique, --aggregate regroupe agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 agenteye --json evals --aggregate --since 7d --env prod # mix de statuts + stats de score par clé -# errors : événements en erreur ; --aggregate pour comptages/sessions/agents/dernière vue +# errors : événements en erreur ; --aggregate pour les comptages/sessions/agents/dernière vue agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 @@ -232,7 +232,7 @@ agenteye --json errors --since 24h --error-type timeout --all --limit 1000 agenteye list envs # aussi : agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (sur **`evals`**, pas `sessions`) est répétable et combiné par ET ; chaque borne est optionnelle (`..0.5` signifie ≤ 0,5, `0.9..` signifie ≥ 0,9). Jusqu'à 20 filtres de score par requête. `evals --scores-full` est un flag d'affichage pour le **tableau humain uniquement** ; il affiche chaque paire de scores au lieu des premiers plus un comptage `+N`. Il n'a aucun effet sous `--json`, qui retourne toujours l'objet de score complet. Pour lire **une session de bout en bout**, combinez la trace d'événements avec son évaluation : +`--score KEY:MIN..MAX` (sur **`evals`**, pas `sessions`) est répétable et combiné avec ET ; l'une ou l'autre borne est facultative (`..0.5` signifie ≤ 0,5, `0.9..` signifie ≥ 0,9). Jusqu'à 20 filtres de score par requête. `evals --scores-full` est un flag d'affichage **pour le tableau humain uniquement** ; il affiche chaque paire de scores au lieu des premières et d'un comptage `+N`. Il n'a aucun effet sous `--json`, qui renvoie toujours l'objet score complet. Pour lire **une session de bout en bout**, combinez la trace d'événements avec son évaluation : ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' @@ -241,19 +241,19 @@ agenteye --json evals --session-id run-001 # ses scores + ### Gérer (soumis aux permissions) : `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`** : clés API. Le secret est généré localement, envoyé au serveur (qui n'en stocke qu'un hash), et **affiché une seule fois** lors de la création/regénération ; capturez-le à ce moment-là. Avec `--json`, il apparaît uniquement dans le champ `key`. Référencé par **nom**. +**`keys`** : clés API. Le secret est généré localement, envoyé au serveur (qui ne stocke qu'un hash), et **affiché une seule fois** lors de la création/régénération ; capturez-le à ce moment. Avec `--json`, il n'apparaît que dans le champ `key`. Référencé par **nom**. ```bash agenteye keys list # clés actives en premier, puis révoquées agenteye keys show ci-bot -agenteye keys create ci-bot --add events:read.add # limiter à ce dont vous avez besoin ; affiche le secret UNE FOIS -agenteye keys create ops --permission-set standard --remove queries:run # partir d'un preset, puis réduire +agenteye keys create ci-bot --add events:read.add # limitez aux permissions nécessaires ; affiche le secret UNE FOIS +agenteye keys create ops --permission-set standard --remove queries:run # initialiser un preset, puis affiner agenteye keys update ci-bot --add evaluations:read --yes -agenteye keys regenerate ci-bot --yes # effectuer une rotation du secret (l'ancien cesse de fonctionner) +agenteye keys regenerate ci-bot --yes # rotation du secret (l'ancien cesse de fonctionner) agenteye keys disable ci-bot --yes # révoquer ``` -Les permissions fonctionnent comme `(permission-set ∪ --add) − --remove`. Les jetons sont `slug:action` (ex. `events:read`) ou `slug:action.action` pour développer plusieurs actions sur une ressource (`events:read.add` → `events:read`, `events:add`). Presets : `read-only`, `standard`, `admin`. Les permissions réservées aux humains (`keys:update`) ne peuvent pas être accordées à une clé. +Les permissions fonctionnent selon `(permission-set ∪ --add) − --remove`. Les jetons sont `slug:action` (p. ex. `events:read`) ou `slug:action.action` pour développer plusieurs actions sur une ressource (`events:read.add` → `events:read`, `events:add`). Presets : `read-only`, `standard`, `admin`. Les permissions réservées aux humains (`keys:update`) ne peuvent pas être accordées à une clé. **`users`** : membres de l'organisation, référencés par **e-mail** (un id UUID est également accepté). @@ -262,7 +262,7 @@ agenteye users list [--active-only] agenteye users show dev@corp.com agenteye users create dev@corp.com --permission-set standard agenteye users update dev@corp.com --add alerts:write --remove queries:delete # prédit + confirme -agenteye users disable dev@corp.com --yes # comporte des protections contre la suppression de soi-même ou de comptes protégés +agenteye users disable dev@corp.com --yes # dispose de protections pour soi-même et les comptes protégés agenteye users enable dev@corp.com ``` @@ -274,18 +274,18 @@ agenteye settings schema # ce que chaque clé accept agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`** : définitions d'alertes, référencées par **nom**. `create` prend un NOM positionnel plus des flags ou un corps JSON complet via `--file`. +**`alerts`** : définitions d'alertes, référencées par **nom**. `create` prend un NOM positionnel et des flags ou un corps JSON complet via `--file`. ```bash agenteye alerts list agenteye alerts show high-errors -agenteye alerts create high-errors --file alert.json # NAME est obligatoire (positionnel) +agenteye alerts create high-errors --file alert.json # NOM obligatoire (positionnel) agenteye alerts update high-errors --severity critical --yes -agenteye alerts test high-errors --yes # déclencher une notification de test +agenteye alerts test high-errors --yes # envoyer une notification de test agenteye alerts delete high-errors --yes ``` -**`incidents`** : incidents d'alerte, référencés par id (ids courts acceptés). `show` affiche le journal d'activité complet ; lisez-le avant d'agir. +**`incidents`** : incidents d'alerte, référencés par id (les ids courts sont acceptés). `show` affiche le journal d'activité complet ; lisez-le avant d'agir. ```bash agenteye incidents list --state firing # aussi : acknowledged, resolved @@ -302,10 +302,10 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### Analyses et assistant : `query` · `agent` -**`query`** : SQL sauvegardé contre votre entrepôt d'analyses plus un exécuteur ad hoc. Les requêtes sauvegardées sont référencées par **nom** ; le SQL est validé côté serveur (SELECT/WITH uniquement, délai d'expiration des instructions, plafond de lignes). +**`query`** : SQL sauvegardé contre votre store d'analyse et un exécuteur ad hoc. Les requêtes sauvegardées sont référencées par **nom** ; le SQL est validé côté serveur (SELECT/WITH uniquement, délai d'attente d'instruction, limite de lignes). ```bash -agenteye query schema [TABLE] # disposition des colonnes des vues analytiques +agenteye query schema [TABLE] # structure des colonnes des vues analytiques agenteye query run --sql "select count(*) from analytics.events" agenteye query run errs --arg prod --limit 100 # exécuter une requête sauvegardée + un $1 positionnel agenteye query list ; agenteye query show errs @@ -313,11 +313,11 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`** : communique avec l'**assistant IA** intégré (le même analyste en lecture seule que vous pouvez utiliser dans le tableau de bord). Les conversations sont référencées par un chat-id court (résolution par préfixe). +**`agent`** : communique avec l'**assistant IA** intégré (le même analyste en lecture seule accessible depuis le tableau de bord). Les conversations sont référencées par un identifiant court (résolution par préfixe). ```bash agenteye agent health # l'assistant IA est-il configuré/accessible -agenteye agent models # modèles que vous pouvez passer à --model (le défaut est marqué) +agenteye agent models # modèles utilisables avec --model (le défaut est marqué) agenteye agent ask "which agents errored most in the last day?" # démarre une conversation ; affiche son id court agenteye agent ask --chat "and which tools did they call?" # continuer cette conversation agenteye agent chats ; agenteye agent show @@ -331,20 +331,20 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | Code | Signification | |---|---| | 0 | Succès | -| 1 | Erreur inattendue (ex. le tableau de bord a retourné un 5xx) | +| 1 | Erreur inattendue (p. ex. le tableau de bord a renvoyé un 5xx) | | 2 | Erreur d'utilisation (arguments invalides, commande/flag inconnu, collision de noms) | | 3 | Impossible d'atteindre le tableau de bord | | 4 | Non connecté ou session expirée ; exécutez `agenteye login` | -| 5 | Authentifié, mais votre compte ne dispose pas de la permission requise (le message la nomme) | -| 6 | La ressource demandée est introuvable (ex. session ou id d'incident inconnu) | +| 5 | Authentifié, mais votre compte n'a pas la permission requise (le message la nomme) | +| 6 | La ressource demandée est introuvable (p. ex. id de session ou d'incident inconnu) | -Ces codes rendent la CLI sûre à scripter : un agent de code peut brancher sur un `4` pour vous inviter à vous ré-authentifier, ou sur un `5` pour signaler la permission manquante. Voir [Recettes CLI pour les agents](/fr/agenteye/cli-recipes) pour les modèles de gestion des codes de sortie et les structures de sortie JSON. +Ces codes rendent le CLI sûr à scripter : un agent de code peut bifurquer sur un `4` pour vous demander de vous ré-authentifier, ou sur un `5` pour afficher la permission manquante. Consultez [Recettes CLI pour les agents](/fr/agenteye/cli-recipes) pour des modèles de gestion des codes de sortie et les formes de sortie JSON. --- -## Prochaines étapes +## Étapes suivantes -- **[Recettes CLI pour les agents](/fr/agenteye/cli-recipes)** : modèles de requêtes à copier-coller, one-liners `jq`, projections `--fields`, gestion des codes de sortie et structures de sortie JSON, écrits pour les agents de code qui pilotent la CLI. -- **[Compétence CLI pour agent](/fr/agenteye/cli-skill)** : packagée cette CLI comme une *compétence* installable Claude Code / Codex afin qu'un agent de code pilote l'Observabilité Failproof AI à partir de requêtes en langage naturel. +- **[Recettes CLI pour les agents](/fr/agenteye/cli-recipes)** : patterns de requête à copier-coller, one-liners `jq`, projections `--fields`, gestion des codes de sortie et formes de sortie JSON, écrits pour les agents de code pilotant le CLI. +- **[Compétence CLI pour agent](/fr/agenteye/cli-skill)** : packager ce CLI comme une *compétence* installable pour Claude Code / Codex afin qu'un agent de code pilote Failproof AI Observability à partir de requêtes en langage naturel. - **[Clés API](/fr/agenteye/api-keys)** : le modèle de permissions derrière `keys create --add …`. -- **[Assistant IA](/fr/agenteye/assistant)** : activation de l'assistant qu'`agent ask` utilise. \ No newline at end of file +- **[Assistant IA](/fr/agenteye/assistant)** : activer l'assistant que `agent ask` utilise. \ No newline at end of file diff --git a/docs/fr/agenteye/codex-capture.mdx b/docs/fr/agenteye/codex-capture.mdx index 22017495..8ebc01bf 100644 --- a/docs/fr/agenteye/codex-capture.mdx +++ b/docs/fr/agenteye/codex-capture.mdx @@ -1,11 +1,11 @@ --- title: "Capture de session Codex" -description: "Transmettez les sessions OpenAI Codex locales de votre équipe vers AgentEye sous forme de sessions et d'événements ordinaires — sans modifier leur façon d'utiliser Codex." +description: "Transférez les sessions OpenAI Codex locales de votre équipe vers AgentEye sous forme de sessions et d'événements ordinaires — sans modifier leur façon d'utiliser Codex." --- -Vos ingénieurs utilisent déjà OpenAI Codex au quotidien. La capture de sessions Codex importe ces sessions de codage dans AgentEye sous forme de sessions et d'événements ordinaires, afin que vous puissiez les rechercher, les rejouer et les évaluer aux côtés de tout ce que vous observez par ailleurs. Cette fonctionnalité complète le [SDK Python](/fr/agenteye/python-sdk) : le SDK instrumente les agents que vous écrivez, tandis que la capture récupère le travail Codex que votre équipe effectue déjà — sans aucune modification de leur façon de l'utiliser. +Vos ingénieurs utilisent déjà OpenAI Codex au quotidien. La capture de session Codex importe ces sessions de développement dans AgentEye sous forme de sessions et d'événements ordinaires, ce qui vous permet de les rechercher, de les rejouer et de les évaluer aux côtés de tout ce que vous observez. Elle complète le [SDK Python](/fr/agenteye/python-sdk) : le SDK instrumente les agents que vous développez, tandis que cette fonctionnalité capture le travail Codex que votre équipe effectue déjà — sans rien changer à leur façon de l'utiliser. -Un petit collecteur en arrière-plan lit les transcripts de sessions locaux de Codex au fur et à mesure de leur écriture et les envoie vers AgentEye. Un seul collecteur par machine capture simultanément toutes les surfaces Codex locales — aucune configuration par surface n'est nécessaire. +Un petit collecteur en arrière-plan lit les transcriptions de sessions locales de Codex au fur et à mesure de leur écriture et les envoie à AgentEye. Un seul collecteur par machine capture simultanément toutes les interfaces Codex locales — aucune configuration par interface n'est nécessaire. Ce même collecteur capture également d'autres agents — voir [OpenClaw](/fr/agenteye/openclaw-capture) et [Hermes](/fr/agenteye/hermes-capture). Activez chacun de ceux que vous utilisez ; un seul collecteur peut en capturer plusieurs à la fois. @@ -13,15 +13,15 @@ Ce même collecteur capture également d'autres agents — voir [OpenClaw](/fr/a ## Ce qui est capturé -Chaque surface Codex fonctionnant **localement** produit les mêmes transcripts de session sur disque, et le collecteur les récupère tous : +Chaque interface Codex fonctionnant **localement** produit les mêmes transcriptions de session sur disque, et le collecteur les récupère toutes : -- le **CLI** Codex et `codex exec` +- la **CLI** Codex et `codex exec` - l'**extension VS Code / IDE** - l'**application de bureau**, lorsqu'elle exécute une session localement -Chaque session Codex devient une [session](/fr/agenteye/sessions) AgentEye ; ses messages utilisateur et assistant, son raisonnement, ses appels d'outils, ses résultats d'outils et son utilisation des tokens deviennent les [événements](/fr/agenteye/event-stream) correspondants. La surface d'origine de chaque session (CLI, IDE ou bureau) est enregistrée, ce qui vous permet de les distinguer. +Chaque session Codex devient une [session](/fr/agenteye/sessions) AgentEye ; ses messages utilisateur et assistant, le raisonnement, les appels d'outils, les résultats d'outils et l'utilisation des tokens deviennent les [événements](/fr/agenteye/event-stream) correspondants. L'interface d'origine de chaque session (CLI, IDE ou bureau) est enregistrée, ce qui vous permet de les distinguer. -> **Les sessions cloud ne sont pas capturées.** L'application de bureau exécute de plus en plus de sessions dans le cloud Codex et ne conserve que leurs métadonnées sur la machine — il n'existe aucun transcript local à lire. Seules les sessions exécutées localement sont capturées. +> **Les sessions cloud ne sont pas capturées.** L'application de bureau exécute de plus en plus de sessions dans le cloud Codex et ne conserve que leurs métadonnées sur la machine — il n'y a pas de transcription locale à lire. Seules les sessions exécutées localement sont capturées. --- @@ -34,22 +34,22 @@ curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main | sh -s -- --key --codex-enabled ``` -Cette commande installe le collecteur, l'enregistre en tant que service en arrière-plan et démarre la capture. Vérifiez qu'il fonctionne : +Cela installe le collecteur, l'enregistre en tant que service en arrière-plan et démarre la capture. Vérifiez qu'il est bien en cours d'exécution : ```bash agenteye-collector health ``` -Au premier démarrage, vos sessions Codex existantes sont importées rétroactivement une seule fois, puis la nouvelle activité est transmise en quelques secondes. Les fichiers de Codex ne sont qu'en lecture seule — ils ne sont jamais modifiés, déplacés ni supprimés — et chaque session est envoyée exactement une fois, même en cas de redémarrage. +Au premier lancement, vos sessions Codex existantes sont importées une fois en arrière-plan, puis la nouvelle activité est transmise en quelques secondes. Les fichiers de Codex sont uniquement lus — jamais modifiés, déplacés ou supprimés — et chaque session est envoyée exactement une fois, même après des redémarrages. --- -## Où retrouver les données +## Où les retrouver -Les sessions capturées apparaissent dans **Sessions**, et leurs événements dans le flux **Events**, de la même façon que tout autre agent observé — ainsi, la [relecture de session](/fr/agenteye/sessions), la [recherche](/fr/agenteye/queries), les [évaluations](/fr/agenteye/evaluations) et les [alertes](/fr/agenteye/alerts) fonctionnent toutes avec elles. Filtrez par agent Codex pour les afficher séparément. +Les sessions capturées apparaissent dans **Sessions**, et leurs événements dans le flux **Events**, comme pour tout autre agent observé — ainsi, la [relecture de session](/fr/agenteye/sessions), la [recherche](/fr/agenteye/queries), les [évaluations](/fr/agenteye/evaluations) et les [alertes](/fr/agenteye/alerts) s'appliquent toutes à ces sessions. Filtrez par l'agent Codex pour les afficher séparément. --- ## Confidentialité -Les transcripts Codex contiennent l'intégralité de la session — y compris les sorties de commandes, le contenu des fichiers et tout ce que Codex a lu ou écrit — et peuvent contenir des secrets. Les sessions capturées sont transmises telles quelles ; n'activez donc la capture que sur les machines et pour les équipes pour lesquelles la centralisation de ce contenu dans AgentEye est appropriée, et fournissez au collecteur une clé dont la portée se limite à `events:add`. Consultez [Sécurité](/fr/agenteye/security) pour en savoir plus sur l'isolation de vos données. \ No newline at end of file +Les transcriptions Codex contiennent l'intégralité de la session — notamment les sorties de commandes, le contenu des fichiers et tout ce que Codex a lu ou écrit — et peuvent contenir des secrets. Les sessions capturées sont envoyées telles quelles ; activez donc la capture uniquement sur les machines et pour les équipes pour lesquelles la centralisation de ce contenu dans AgentEye est appropriée, et attribuez au collecteur une clé limitée à `events:add` uniquement. Consultez la section [Sécurité](/fr/agenteye/security) pour en savoir plus sur l'isolation de vos données. \ No newline at end of file diff --git a/docs/fr/agenteye/concepts.mdx b/docs/fr/agenteye/concepts.mdx index 9343dadf..13843f42 100644 --- a/docs/fr/agenteye/concepts.mdx +++ b/docs/fr/agenteye/concepts.mdx @@ -4,80 +4,80 @@ description: "Le vocabulaire de Failproof AI Observability — événements, ses --- -Cette page définit le vocabulaire utilisé par Failproof AI Observability. Si un terme vous est inconnu dans un autre guide, il est défini ici. Inutile de la lire en entier : parcourez-la en diagonale, ou revenez-y dès qu'un mot mérite d'être précisé. +Cette page définit le vocabulaire utilisé par Failproof AI Observability. Si un terme dans un autre guide vous est inconnu, vous le trouverez ici. Inutile de la lire en entier : parcourez-la, ou revenez-y lorsque vous souhaitez préciser un mot. --- ## Le modèle de données **Événement** -La plus petite unité de données. Un événement enregistre une seule étape effectuée par votre agent : un `tool_use`, un `model_request`, un `hook_completed`, une `error`, etc. Votre agent émet des événements via le [Python SDK](/fr/agenteye/python-sdk) ; ils apparaissent en temps réel sur la page **Events**. +La plus petite unité de données. Un événement enregistre une étape unique effectuée par votre agent : un `tool_use`, un `model_request`, un `hook_completed`, une `error`, etc. Votre agent émet des événements via le [SDK Python](/fr/agenteye/python-sdk) ; ils apparaissent en temps réel sur la page **Events**. **Session** -Une exécution d'agent, identifiée par un `session_id`. Une session regroupe tous les événements partageant cet identifiant, consolidés en une seule ligne sur la page **Sessions** et représentés sous forme de graphe d'exécution sur sa page de détail. Une session commence généralement par `agent_start` et se termine par `agent_end`. +Une exécution d'agent, identifiée par un `session_id`. Une session regroupe tous les événements partageant cet identifiant, agrégés en une seule ligne sur la page **Sessions** et représentés sous forme de graphe d'exécution sur sa page de détail. Une session commence généralement par `agent_start` et se termine par `agent_end`. **Agent** -Un acteur nommé au sein d'une exécution, identifié par un `agent_id`. Une exécution peut impliquer plusieurs agents : par exemple, un planificateur qui instancie un sous-agent de synthèse. Les sous-agents portent un `parent_id`, ce qui permet à Failproof AI Observability de les représenter sur leurs propres pistes dans le graphe d'exécution. +Un acteur nommé dans une exécution, identifié par un `agent_id`. Une exécution peut impliquer plusieurs agents : un planificateur qui crée un sous-agent de résumé, par exemple. Les sous-agents portent un `parent_id`, ce qui permet à Failproof AI Observability de les afficher sur leurs propres pistes dans le graphe d'exécution. **Environnement** -Un libellé indiquant où s'est déroulée l'exécution : `production`, `staging`, `dev`. Vous le définissez une seule fois lors de la configuration du SDK. Presque toutes les pages du tableau de bord permettent de filtrer par environnement. +Un libellé indiquant où l'exécution a eu lieu : `production`, `staging`, `dev`. Vous le définissez une fois lors de la configuration du SDK. Presque toutes les pages du tableau de bord peuvent être filtrées par environnement. -**Taux de remplissage de la fenêtre de contexte** -Le pourcentage de la fenêtre de contexte d'un modèle consommé par une réponse. Failproof AI Observability l'horodate sur les événements `model_response` pour les modèles qu'il reconnaît, rendant ainsi visibles la croissance des prompts et les compactions imminentes directement dans le flux d'événements. +**Remplissage de la fenêtre de contexte** +Le pourcentage de la fenêtre de contexte d'un modèle consommé par une réponse. Failproof AI Observability l'estampille sur les événements `model_response` pour les modèles qu'il reconnaît, ce qui rend visibles la croissance des prompts et la compaction imminente directement dans le flux d'événements. --- ## Qualité **Évaluation** -Un score de qualité pour une session terminée, produit par un service de notation que vous exécutez. Les évaluations sont optionnelles : tant que vous ne connectez pas d'évaluateur, les sessions sont enregistrées mais pas notées. Chaque évaluation peut comporter plusieurs scores nommés (par exemple `helpfulness`, `factuality`, `tool_efficiency`), chacun accompagné d'une courte note explicative. Voir [Evaluation suite](/fr/agenteye/evaluation-suite). +Un score de qualité pour une session terminée, produit par un service de notation que vous exécutez. Les évaluations sont optionnelles : tant que vous ne connectez pas d'évaluateur, les sessions sont enregistrées mais non notées. Chaque évaluation peut porter plusieurs scores nommés (par exemple `helpfulness`, `factuality`, `tool_efficiency`), chacun accompagné d'une courte note de raisonnement. Voir [Evaluation suite](/fr/agenteye/evaluation-suite). **Clé de score** Le nom d'une dimension rapportée par un évaluateur, comme `helpfulness`. Les alertes et les audits peuvent surveiller une clé de score spécifique dans le temps. **Évaluateur** -Votre service de notation. Failproof AI Observability lui envoie via POST la transcription d'une exécution terminée et stocke les scores renvoyés. Aucun évaluateur par défaut n'est fourni ; la logique de notation vous appartient. +Votre service de notation. Failproof AI Observability lui envoie via POST la transcription d'une exécution terminée et stocke les scores qu'il retourne. Il ne fournit pas d'évaluateur par défaut ; la logique de notation vous appartient. --- ## Identifier et corriger les défaillances **Hook** -Un garde-fou ou un effet secondaire que votre framework d'agent exécute autour d'une étape : une vérification de sécurité du contenu, une anonymisation des données personnelles, un contrôle budgétaire. Les hooks émettent des événements `hook_triggered` / `hook_completed` avec un `outcome` (allow, deny, modify) et disposent de leur propre page d'observation. +Un garde-fou ou effet secondaire que votre framework d'agent exécute autour d'une étape : une vérification de sécurité du contenu, une rédaction des données personnelles, un garde budgétaire. Les hooks émettent des événements `hook_triggered` / `hook_completed` avec un `outcome` (allow, deny, modify), et disposent de leur propre page d'observation. **Règle d'alerte** -Une règle qui se déclenche lorsqu'une métrique dépasse un seuil que vous définissez : taux d'erreur, latence p95, coût en tokens ou score d'un évaluateur. Lorsqu'une règle se déclenche, elle ouvre un incident et notifie les canaux que vous avez choisis (e-mail, Slack, webhook, tableau de bord). Voir [Alerts](/fr/agenteye/alerts). +Une règle qui se déclenche lorsqu'une métrique dépasse un seuil que vous définissez : taux d'erreur, latence p95, coût en tokens ou score d'évaluateur. Lorsqu'une règle se déclenche, elle ouvre un incident et notifie les canaux de votre choix (email, Slack, webhook, dans le tableau de bord). Voir [Alerts](/fr/agenteye/alerts). **Incident** -Un problème ouvert créé lorsqu'une règle d'alerte se déclenche. Les incidents suivent un cycle de vie (accusé de réception, assignation, résolution) et disposent d'une chronologie d'activité enregistrant chaque action. Vous pouvez également en ouvrir un manuellement. +Un problème ouvert créé lorsqu'une règle d'alerte se déclenche. Les incidents ont un cycle de vie (acquitter, assigner, résoudre) et une chronologie d'activité qui enregistre chaque action. Vous pouvez également en ouvrir un manuellement. **Audit** -Une investigation récurrente (toutes les heures à une fois par semaine) qui analyse vos journaux *à travers* les sessions pour détecter des patterns de défaillance pour lesquels vous n'avez pas encore écrit de règle : clusters d'erreurs, scores faibles, valeurs aberrantes de latence, boucles d'appels d'outils et exécutions n'ayant jamais abouti. Là où une alerte surveille une métrique que vous connaissez déjà, un audit vous indique ce sur quoi vous devriez vous pencher ensuite. Voir [Audits](/fr/agenteye/audits). +Une investigation récurrente (de toutes les heures à toutes les semaines) qui analyse vos journaux *entre* sessions à la recherche de schémas de défaillance pour lesquels vous n'avez pas encore écrit de règle : clusters d'erreurs, scores faibles, anomalies de latence, boucles d'appels d'outils et exécutions qui ne se sont jamais terminées. Là où une alerte surveille une métrique que vous connaissez déjà, un audit vous indique ce sur quoi vous devriez vous pencher ensuite. Voir [Audits](/fr/agenteye/audits). **Finding** -Un résultat classé et étayé par des preuves, issu d'une exécution d'audit. Un finding nomme un pattern, renvoie aux sessions exactes qui le sous-tendent et suit un cycle de vie de triage (accusé de réception, résolution, mise en sourdine, rejet). Failproof AI Observability déduplique les findings d'une exécution à l'autre, de sorte qu'un pattern connu est mis à jour plutôt que de s'accumuler. +Un résultat classé et étayé par des preuves, issu d'une exécution d'audit. Un finding nomme un schéma, renvoie aux sessions exactes qui l'illustrent et dispose d'un cycle de vie de triage (acquitter, résoudre, mettre en sourdine, rejeter). Failproof AI Observability déduplique les findings d'une exécution à l'autre, de sorte qu'un schéma connu est mis à jour plutôt que de s'accumuler. **L'assistant IA** -Le chat intégré au tableau de bord qui répond en langage naturel à vos questions sur vos agents, en s'appuyant sur vos propres données. Il est en lecture seule par défaut ; tout ce qu'il crée (une requête sauvegardée, un tableau de bord) nécessite une approbation, et il ne peut jamais supprimer quoi que ce soit. Voir [AI assistant](/fr/agenteye/assistant). +Le chat intégré au tableau de bord qui répond aux questions sur vos agents en langage naturel, à partir de vos propres données. Il est en lecture seule par défaut ; tout ce qu'il crée (une requête sauvegardée, un tableau de bord) est soumis à approbation, et il ne peut jamais supprimer. Voir [AI assistant](/fr/agenteye/assistant). --- -## Fonctionnement +## Exploitation **Organisation (tenant)** -Un espace de travail isolé. Une instance Failproof AI Observability peut héberger plusieurs organisations, chacune avec ses propres utilisateurs, clés et données. Chaque URL du tableau de bord est rattachée à votre slug d'organisation (`//…`). +Un espace de travail isolé. Une instance Failproof AI Observability peut héberger de nombreuses organisations, chacune avec ses propres utilisateurs, clés et données. Chaque URL du tableau de bord est délimitée par le slug de votre organisation (`//…`). -**Collector** -`agenteye-collector`, le démon léger qui s'exécute sur chaque machine agent, regroupe les événements écrits sur disque par le SDK et les envoie au serveur. +**Collecteur** +`agenteye-collector`, le daemon léger qui s'exécute sur chaque machine agent, regroupe les événements que le SDK écrit sur le disque et les envoie au serveur. **Clé API** -Un token à périmètre défini qui authentifie un client auprès du serveur. Les clés portent des permissions granulaires (par exemple `events:add` pour le collector, des périmètres en lecture seule pour une clé de tableau de bord). Voir [API keys](/fr/agenteye/api-keys). +Un jeton délimité qui authentifie un client auprès du serveur. Les clés portent des permissions granulaires (par exemple `events:add` pour le collecteur, des portées en lecture seule pour une clé de tableau de bord). Voir [API keys](/fr/agenteye/api-keys). **Serveur** -Le service d'ingestion et d'API. Il ingère les événements, stocke l'état opérationnel dans vos bases de données et sert le tableau de bord ainsi que la CLI. +Le service d'ingestion et d'API. Il ingère les événements, stocke l'état opérationnel dans vos bases de données et sert le tableau de bord et la CLI. **Tableau de bord** -L'interface web. Chaque page est rattachée à une organisation et lit les données via l'API du serveur. +L'interface web. Chaque page est délimitée par une organisation et lit via l'API du serveur. --- diff --git a/docs/fr/agenteye/dashboards.mdx b/docs/fr/agenteye/dashboards.mdx index eaf690cc..64f5299f 100644 --- a/docs/fr/agenteye/dashboards.mdx +++ b/docs/fr/agenteye/dashboards.mdx @@ -1,46 +1,46 @@ --- title: "Tableaux de bord" -description: "Transformez vos données d'agents en temps réel en une vue partagée que toute votre équipe consulte." +description: "Transformez vos données d'agents en temps réel en une vue partagée que toute votre équipe peut consulter." --- -Transformez vos données d'agents en temps réel en une vue partagée que toute votre équipe consulte. Épinglez les requêtes importantes sous forme de graphiques, et tout le monde accède instantanément aux mêmes chiffres, sans avoir à relancer une seule requête. +Transformez vos données d'agents en temps réel en une vue partagée que toute votre équipe peut consulter. Épinglez les requêtes importantes sous forme de graphiques, et tout le monde accède aux mêmes chiffres en un coup d'œil, sans avoir à relancer une seule requête. -![Un tableau de bord construit à partir de requêtes sauvegardées : une courbe d'événements par heure, un histogramme des erreurs par type, un graphique en aire de la latence, et une répartition des tokens par modèle](/agenteye/images/dashboard-fleet.png) +![Un tableau de bord construit à partir de requêtes sauvegardées : une courbe d'événements par heure, un histogramme des erreurs par type, un graphique en aires de la latence, et les tokens par modèle](/agenteye/images/dashboard-fleet.png) -*Un tableau de bord, quatre requêtes sauvegardées : événements par heure, erreurs par type, latence et tokens par modèle.* +*Un tableau, quatre requêtes sauvegardées : événements par heure, erreurs par type, latence et tokens par modèle.* ## Tout le monde voit la même réalité -Fini les captures d'écran partagées dans le chat et les mêmes requêtes relancées cinq fois par jour. Un tableau de bord est un espace partagé à l'échelle de l'organisation, que n'importe quel membre de votre équipe peut ouvrir pour consulter exactement la même vue. Quand les données sous-jacentes évoluent, les graphiques évoluent avec elles : le tableau est toujours à jour, et personne ne se dispute sur des chiffres périmés. +Arrêtez de coller des captures d'écran dans vos messages et de relancer les mêmes requêtes cinq fois par jour. Un tableau de bord est un espace partagé à l'échelle de l'organisation, que n'importe quel membre de votre équipe peut ouvrir pour voir exactement la même vue. Quand les données sous-jacentes évoluent, les graphiques évoluent avec elles — le tableau est donc toujours à jour et personne ne se dispute autour de chiffres périmés. -Le tableau de bord de flotte ci-dessus est une bonne base pour les opérations quotidiennes : +Le tableau de bord de flotte ci-dessus est un bon point de départ pour les opérations quotidiennes : - une **courbe d'événements par heure**, pour surveiller le débit et détecter une chute soudaine -- un **histogramme des erreurs par type**, pour identifier en un coup d'œil vos principales catégories de pannes -- un **graphique en aire de la latence**, pour repérer les ralentissements avant que les utilisateurs se plaignent +- un **histogramme des erreurs par type**, pour faire ressortir vos principales catégories d'échecs +- un **graphique en aires de la latence**, pour repérer les ralentissements avant que les utilisateurs ne se plaignent - une **répartition des tokens par modèle**, pour garder les coûts sous contrôle -Vous trouverez vos tableaux de bord à `//dashboards`. +Vous trouverez vos tableaux à l'adresse `//dashboards`. -## Épinglez les requêtes que vous avez déjà sauvegardées +## Épinglez les requêtes déjà sauvegardées -Chaque vignette commence par une requête sauvegardée. Créez et sauvegardez la requête qui vous intéresse dans la bibliothèque [Requêtes](/fr/agenteye/queries) (préréglages intégrés et requêtes personnalisées, sur vos événements et évaluations), puis épinglez-la sur un tableau de bord sous la forme du graphique adapté à vos données : une **courbe** pour les tendances dans le temps, un **histogramme** pour comparer des catégories, une **aire** pour les volumes, ou un **camembert** pour une répartition en parts. +Chaque tuile commence par une requête sauvegardée. Construisez et sauvegardez la requête qui vous intéresse dans la bibliothèque [Requêtes](/fr/agenteye/queries) (préréglages intégrés et vos propres requêtes, sur vos événements et évaluations), puis épinglez-la dans un tableau de bord sous la forme du graphique adapté aux données : une **courbe** pour les tendances dans le temps, un **histogramme** pour comparer des catégories, une **aire** pour les volumes, ou un **camembert** pour une répartition en parts. -Puisqu'une vignette n'est que votre requête sauvegardée affichée sous forme de graphique, rien n'est à synchroniser manuellement. Mettez à jour la requête une fois, et tous les tableaux de bord qui l'utilisent se mettent à jour automatiquement. +Comme une tuile n'est que votre requête sauvegardée affichée sous forme de graphique, il n'y a rien à synchroniser manuellement. Modifiez la requête une fois, et tous les tableaux de bord qui l'utilisent se mettent à jour automatiquement. ## Surveillez la qualité, pas seulement le volume -Le volume vous indique que les agents sont actifs. La qualité vous indique qu'ils font réellement leur travail. Orientez un tableau de bord vers vos [scores d'évaluation](/fr/agenteye/evaluations) et vous obtenez un tableau qui suit la qualité des exécutions dans le temps : une régression de qualité apparaît comme un creux sur un graphique, plutôt que comme une mauvaise surprise venue d'un client. +Le volume vous indique que les agents sont actifs. La qualité vous indique qu'ils font vraiment le travail. Orientez un tableau de bord vers vos [scores d'évaluation](/fr/agenteye/evaluations) et vous obtenez un espace qui suit la qualité des exécutions dans le temps — une régression de qualité apparaît alors comme une baisse sur un graphique plutôt que comme une mauvaise surprise venant d'un client. -![Un tableau de bord axé sur la qualité, construit à partir de requêtes d'évaluation sauvegardées](/agenteye/images/dashboard-quality.png) +![Un tableau de bord orienté qualité construit à partir de requêtes d'évaluation sauvegardées](/agenteye/images/dashboard-quality.png) -*Un tableau de bord qualité garde vos scores d'évaluation au premier plan, juste à côté des métriques opérationnelles.* +*Un tableau de bord qualité garde vos scores d'évaluation bien en vue, juste à côté des indicateurs opérationnels.* -Maintenez un tableau de bord opérationnel et un tableau de bord qualité côte à côte, et votre équipe dispose d'un seul endroit pour répondre à la fois à « est-ce que ça fonctionne ? » et « est-ce que c'est bon ? », sans que personne n'ait à relancer une requête. +Gardez un tableau opérationnel et un tableau qualité côte à côte, et votre équipe dispose d'un seul endroit pour répondre à la fois à « est-ce que ça fonctionne ? » et « est-ce que c'est bon ? », sans que personne n'ait à relancer une requête. -## Voir aussi +## Ressources associées -- [Requêtes](/fr/agenteye/queries) : créez et sauvegardez les requêtes qui deviendront vos vignettes. -- [Évaluations](/fr/agenteye/evaluations) : scorez vos exécutions pour pouvoir suivre la qualité dans le temps. -- [Alertes](/fr/agenteye/alerts) : transformez un seuil sur n'importe laquelle de ces métriques en une notification. \ No newline at end of file +- [Requêtes](/fr/agenteye/queries) : construisez et sauvegardez les requêtes qui deviendront vos tuiles. +- [Évaluations](/fr/agenteye/evaluations) : notez vos exécutions pour pouvoir suivre la qualité dans le temps. +- [Alertes](/fr/agenteye/alerts) : transformez un seuil sur l'un de ces indicateurs en notification. \ No newline at end of file diff --git a/docs/fr/agenteye/error-tracking.mdx b/docs/fr/agenteye/error-tracking.mdx index 178ca8ce..dbadbec3 100644 --- a/docs/fr/agenteye/error-tracking.mdx +++ b/docs/fr/agenteye/error-tracking.mdx @@ -1,40 +1,41 @@ --- title: "Suivi des erreurs" -description: "Visualisez en un seul endroit toutes les défaillances de vos agents, regroupées pour qu'une rafale d'erreurs apparaisse comme un problème unique." +description: "Visualisez en un seul endroit toutes les défaillances de vos agents, regroupées pour qu'une rafale de messages s'affiche comme un problème unique." --- -Visualisez en un seul endroit toutes les défaillances de vos agents, regroupées pour qu'une rafale d'erreurs apparaisse comme un problème unique. Vous disposez d'un accès en un clic entre « quelque chose est rouge » et l'exécution exacte qui a échoué, sans avoir à parcourir un flux en direct pour la retrouver. -![La page Erreurs : un histogramme des défaillances au fil du temps au-dessus de lignes d'erreurs rouges groupées, chacune avec un bouton « + alert » en un clic](/agenteye/images/errors.png) -*La page Erreurs : un histogramme des défaillances au fil du temps, avec les erreurs répétées regroupées en une seule ligne par incident.* +Visualisez en un seul endroit toutes les défaillances de vos agents, regroupées pour qu'une rafale de messages s'affiche comme un problème unique. Vous disposez d'un chemin en un clic de « quelque chose est en rouge » jusqu'à l'exécution exacte qui a échoué, sans avoir à faire défiler un flux en direct pour la retrouver. -## Toutes les défaillances, déjà collectées pour vous +![La page Erreurs : un histogramme des défaillances dans le temps au-dessus de rangées d'erreurs rouges regroupées, chacune avec un bouton « + alert » en un clic](/agenteye/images/errors.png) +*La page Erreurs : un histogramme des défaillances dans le temps, avec les défaillances répétées condensées en une seule ligne par incident.* -Quand un agent tombe en panne, vous ne devriez pas avoir à parcourir un flux d'événements en direct en espérant repérer les lignes rouges avant qu'elles disparaissent. La page **Errors** se charge de la collecte à votre place. Elle rassemble tout ce que le tableau de bord afficherait en rouge dans une interface de triage unique, de sorte que la première chose que vous voyez est ce qui échoue, et non l'endroit où chercher. +## Chaque défaillance, déjà collectée pour vous -Et elle détecte bien plus que les erreurs évidentes. En plus des événements `error` explicites, Failproof AI Observability remonte également les défaillances silencieuses : tout `tool_result`, `hook_completed` ou `agent_end` dont le contenu indique un échec apparaît ici. Un outil ayant retourné une erreur, ou un hook s'étant terminé de manière anormale, ne passe plus inaperçu simplement parce qu'aucune exception bruyante n'a été levée. +Lorsqu'un agent tombe en panne, vous ne devriez pas avoir à faire défiler un flux d'événements en direct en espérant attraper les lignes rouges avant qu'elles disparaissent. La page **Erreurs** se charge de la collecte à votre place. Elle regroupe tout ce que le tableau de bord afficherait en rouge sur une seule surface de triage, de sorte que la première chose que vous voyez est ce qui est en train d'échouer, et non où aller le chercher. -En haut de la page, un histogramme trace l'évolution des erreurs dans le temps. Un simple coup d'œil vous indique s'il s'agit d'un filet constant en arrière-plan ou d'un pic apparu il y a quelques minutes, vous permettant de décider immédiatement si vous devez tout laisser tomber. +Et elle capture bien plus que les erreurs évidentes. Au-delà des événements `error` explicites, Failproof AI Observability remonte également les défaillances silencieuses : tout `tool_result`, `hook_completed` ou `agent_end` dont le contenu indique un échec apparaît ici. Un outil qui a renvoyé une erreur, ou un hook qui s'est terminé anormalement, ne passe plus inaperçu simplement parce qu'aucune exception bruyante n'a été levée. -Comme toutes les surfaces d'observation, la page Errors est limitée à votre organisation et se filtre par plage de dates, environnement, agent et session. Vous pouvez ainsi partir d'une liste couvrant l'ensemble de votre parc et la réduire à l'agent ou à l'environnement qui vous intéresse réellement. +En haut de page, un histogramme trace les erreurs dans le temps. Un simple coup d'œil vous indique si vous êtes face à un filet de fond continu ou à un pic apparu il y a quelques minutes, ce qui vous permet de savoir immédiatement si vous devez tout lâcher pour intervenir. -## Un seul incident, pas cent lignes identiques +Comme toutes les surfaces d'observation, la page Erreurs est délimitée par votre organisation et se filtre par plage de dates, environnement, agent et session. Cela signifie que vous pouvez partir d'une liste à l'échelle de toute votre infrastructure et la restreindre à l'agent ou à l'environnement qui vous intéresse réellement. -Une dépendance défaillante peut déclencher la même erreur des centaines de fois par minute. Sans regroupement, cela donne un mur de lignes quasi identiques qui noie l'information dont vous avez vraiment besoin. +## Un incident, pas une centaine de lignes identiques -Failproof AI Observability regroupe les défaillances répétées partageant la même session et le même type d'erreur en une seule ligne. Une rafale apparaît comme un seul incident. Vous comptez des problèmes, pas des lignes de log, et le signal qui compte reste en évidence au lieu d'être noyé par son propre volume. +Une seule dépendance défaillante peut déclencher la même erreur des centaines de fois par minute. Sans traitement, c'est un mur de lignes quasi identiques qui ensevelit la seule chose que vous avez vraiment besoin de voir. -## De « quelque chose est rouge » à l'événement exact +Failproof AI Observability condense les défaillances répétées qui partagent la même session et le même type d'erreur en une seule ligne. Une rafale s'affiche comme un seul incident. Vous finissez par compter des problèmes, et non des lignes de log, et le signal qui compte reste en premier plan au lieu d'être noyé par son propre volume. -Cliquez sur n'importe quelle ligne pour accéder directement à la session de cette exécution, positionné sur l'événement exact qui a échoué. Pas besoin de copier des identifiants de session ni de faire défiler pour trouver le moment de la rupture : vous arrivez directement dessus, avec le graphe d'exécution complet à portée de regard pour voir ce que l'agent faisait dans les instants précédant la défaillance. +## De « quelque chose est en rouge » à l'événement exact -Si vous disposez de `alerts:write`, chaque ligne comporte également un bouton **+ alert**. Cliquez dessus et Observability ouvre une nouvelle règle d'alerte déjà configurée pour détecter ce même type de défaillance. L'incident que vous venez de traiter deviendra celui qui vous alerte la prochaine fois, au lieu de vous surprendre une deuxième fois. +Cliquez sur n'importe quelle ligne pour atterrir directement dans la session de cette exécution, positionné sur l'événement exact qui a échoué. Pas de copier-coller d'ID de session, pas de défilement pour retrouver le moment où ça a mal tourné : vous arrivez directement dessus, avec le graphe d'exécution complet accessible d'un regard pour voir ce que l'agent a fait dans les instants précédant la panne. -**Où le trouver :** la page **Errors** se trouve dans la section observe du tableau de bord, à l'adresse `//errors`. +Si vous disposez des droits `alerts:write`, chaque ligne comporte également un bouton **+ alert**. Cliquez dessus et Observability ouvre une nouvelle règle d'alerte déjà configurée pour détecter cette même défaillance à l'avenir. L'incident que vous venez de traiter devient celui qui vous alertera la prochaine fois, au lieu de vous surprendre une deuxième fois. -## Ressources associées +**Où le trouver :** la page **Erreurs** se trouve dans la section observe du tableau de bord, à l'adresse `//errors`. -- [Alerts](/fr/agenteye/alerts) : transformez n'importe quelle défaillance en règle d'alerte. +## Voir aussi + +- [Alertes](/fr/agenteye/alerts) : transformez n'importe quelle défaillance en règle de notification. - [Incidents](/fr/agenteye/incidents) : suivez une alerte déclenchée de son ouverture à sa résolution. - [Sessions](/fr/agenteye/sessions) : ouvrez l'exécution complète derrière n'importe quelle erreur. -- [Audits](/fr/agenteye/audits) : laissez Observability identifier les schémas de défaillance dans vos exécutions. \ No newline at end of file +- [Audits](/fr/agenteye/audits) : laissez Observability identifier automatiquement les schémas de défaillances dans vos exécutions. \ No newline at end of file diff --git a/docs/fr/agenteye/evaluation-suite.mdx b/docs/fr/agenteye/evaluation-suite.mdx index df6567ac..8eca2b60 100644 --- a/docs/fr/agenteye/evaluation-suite.mdx +++ b/docs/fr/agenteye/evaluation-suite.mdx @@ -1,22 +1,22 @@ --- title: "Suite d'évaluation" -description: "Failproof AI Observability peut noter automatiquement chaque exécution d'agent terminée pour en évaluer la qualité : vous fournissez un petit service de notation, et Observability s'occupe du reste." +description: "Failproof AI Observability peut noter automatiquement chaque exécution d'agent terminée : vous fournissez un petit service de notation, et Observability s'occupe du reste." --- -Failproof AI Observability peut noter automatiquement chaque exécution d'agent terminée pour en évaluer la qualité : vous fournissez un petit service de notation, et Observability s'occupe du reste. Utilisez-le pour suivre les dimensions qui vous importent (utilité, efficacité des outils, factualité, sécurité — vous choisissez), détecter les régressions tôt et comparer des agents ou des environnements en un coup d'œil. La notation est optionnelle : le pipeline ne fait rien tant que vous n'avez pas défini `EVALUATOR_ENDPOINT` sur le serveur. +Failproof AI Observability peut noter automatiquement chaque exécution d'agent terminée : vous fournissez un petit service de notation, et Observability s'occupe du reste. Utilisez-le pour suivre les dimensions qui vous importent (utilité, efficacité des outils, factualité, sécurité — vous choisissez), détecter les régressions tôt et comparer des agents ou des environnements en un coup d'œil. La notation est optionnelle : le pipeline ne fait rien tant que `EVALUATOR_ENDPOINT` n'est pas défini sur le serveur. -> **Remarque :** Vous définissez vous-même les dimensions de notation. Votre évaluateur peut retourner les clés numériques de son choix ; Observability stocke, suit les tendances et affiche tout ce que vous renvoyez. +> **Remarque :** Vous définissez vous-même les dimensions de notation. Votre évaluateur peut renvoyer les clés numériques qu'il souhaite ; Observability stocke, suit et affiche tout ce que vous lui envoyez. -## En bref +## Vue d'ensemble -1. **Écrivez un évaluateur.** Déployez un petit service HTTP qui lit la transcription d'une session et retourne des scores. Observability inclut une référence fonctionnelle que vous pouvez copier. Voir [Écrire un évaluateur avec le SDK](#writing-an-evaluator-with-the-sdk). +1. **Écrivez un évaluateur.** Démarrez un petit service HTTP qui lit une transcription de session et renvoie des scores. Observability inclut un exemple fonctionnel que vous pouvez copier. Voir [Écrire un évaluateur avec le SDK](#writing-an-evaluator-with-the-sdk). 2. **Pointez Observability vers ce service.** Définissez `EVALUATOR_ENDPOINT` (et un `EVALUATOR_TOKEN` partagé) sur le processus serveur. -3. **Regardez les scores arriver.** Chaque session terminée est notée automatiquement ; les résultats apparaissent sur la page de détail de la session, la grille des sessions et les tableaux de bord sauvegardés. +3. **Observez les scores arriver.** Chaque session terminée est notée automatiquement ; les résultats apparaissent sur la page de détail de la session, la grille des sessions et les tableaux de bord sauvegardés. -![Vue de détail d'une session avec le résumé de l'évaluation, les barres de score par dimension et le texte de justification dans le rail droit](/agenteye/images/session-detail.png) +![Vue détaillée d'une session avec le résumé d'évaluation, les barres de score par dimension et le texte de raisonnement dans le panneau latéral droit](/agenteye/images/session-detail.png) -*Une fois un évaluateur configuré, chaque exécution terminée est notée et les résultats apparaissent dans le rail droit de la session : le résumé en haut, puis les barres de score par dimension avec leur justification.* +*Une fois un évaluateur configuré, chaque exécution terminée est notée et les résultats apparaissent dans le panneau latéral droit de la session : le résumé en haut, puis les barres de score par dimension avec leur raisonnement.* --- @@ -32,76 +32,42 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Lorsque le SDK Observability émet un événement `agent_end` pour une session, le serveur -planifie une évaluation. Il envoie ensuite en POST la transcription complète des événements à votre -service d'évaluation, qui peut alors : - -- **Retourner le résultat immédiatement** avec `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Le - résultat est ajouté à la chronologie d'évaluation de la session. `reasoning` et - `summary` sont optionnels. -- **Différer** avec `{"status":"pending", "job_id":"abc-123"}`. Observability appelle alors - `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` jusqu'à ce que votre évaluateur - retourne `{"status":"done", ...}` ou `{"status":"error", "error":"..."}`. - - La cadence de polling est par tâche : une réponse `pending` peut inclure - `next_poll_secs` pour la surcharger ; sinon Observability utilise la valeur - `default_poll_interval_secs` issue de `GET /config` ; sinon le serveur - se rabat sur `EVALUATOR_POLLING_INTERVAL_SECS` (défaut : 10 s). Toutes les valeurs - sont limitées à [1 s, 1 h]. - -Les sessions qui n'émettent jamais `agent_end` (par exemple, un processus d'agent planté) -peuvent également être traitées : le `GET /config` de l'évaluateur peut retourner -`{"inactivity_timeout_secs": 1800}`, et Observability évaluera toute session -restée inactive pendant ce délai. Définissez le champ à `null` ou omettez-le pour -désactiver ce comportement de secours. - -Le pipeline est entièrement sans effet lorsque `EVALUATOR_ENDPOINT` n'est pas défini. - -Une session peut accumuler **plusieurs évaluations terminales dans le temps** : chaque -événement `agent_end` (et chaque réévaluation manuelle depuis le tableau de bord) ajoute -une nouvelle ligne d'évaluation. C'est la méthode recommandée pour évaluer une conversation -reprise : un utilisateur termine un agent, revient plus tard, envoie de nouveaux événements, -termine à nouveau l'agent, et une seconde évaluation s'exécute sur la transcription complète mise à jour. -Le tableau de bord affiche l'évaluation la plus récente comme titre principal et les évaluations -précédentes sous forme de chronologie rétractable. Pendant qu'une évaluation est en cours pour -une session, les événements `agent_end` supplémentaires pour cette session sont ignorés ; le -suivant, une fois l'évaluation en cours terminée, mettra en file d'attente une nouvelle évaluation -comme d'habitude. - -Le mécanisme de secours par inactivité se réengage également sur les sessions reprises : si -de nouveaux événements arrivent après une évaluation terminale précédente et que la session -reste ensuite inactive au-delà de `inactivity_timeout_secs`, une nouvelle évaluation est mise -en file d'attente. - -Les échecs transitoires (5xx, 429, délais d'expiration, erreurs réseau) font l'objet de nouvelles -tentatives avec backoff exponentiel jusqu'à `EVALUATOR_MAX_ATTEMPTS` ; les réponses 4xx sont -terminales. Observability fonctionne en toute sécurité avec plusieurs instances de serveur à -échelle horizontale ; le travail est partitionné de sorte qu'une même session ne soit jamais -traitée deux fois simultanément. +Lorsque le SDK Observability émet un événement `agent_end` pour une session, le serveur planifie une évaluation. Il envoie ensuite en POST la transcription complète des événements à votre service évaluateur, qui peut soit : + +- **Renvoyer le résultat en ligne** avec `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Le résultat est ajouté à la timeline d'évaluation de la session. `reasoning` et `summary` sont optionnels. +- **Différer** avec `{"status":"pending", "job_id":"abc-123"}`. Observability appelle alors `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` jusqu'à ce que votre évaluateur renvoie `{"status":"done", ...}` ou `{"status":"error", "error":"..."}`. + + La cadence de sondage est par tâche : une réponse `pending` peut inclure `next_poll_secs` pour la remplacer ; sinon Observability utilise la valeur `default_poll_interval_secs` de `GET /config` ; sinon le serveur se rabat sur `EVALUATOR_POLLING_INTERVAL_SECS` (10 s par défaut). Toutes les valeurs sont limitées à [1 s, 1 h]. + +Les sessions qui n'émettent jamais `agent_end` (par exemple, un processus agent planté) peuvent également être traitées : le `GET /config` de l'évaluateur peut renvoyer `{"inactivity_timeout_secs": 1800}`, et Observability évaluera toute session restée inactive aussi longtemps. Définissez le champ à `null` ou omettez-le pour désactiver ce mécanisme de secours. + +Le pipeline est entièrement inactif lorsque `EVALUATOR_ENDPOINT` n'est pas défini. + +Une session peut accumuler **plusieurs évaluations terminales au fil du temps** : chaque événement `agent_end` (et chaque réévaluation manuelle depuis le tableau de bord) ajoute une nouvelle ligne d'évaluation. C'est la méthode recommandée pour évaluer une conversation reprise : un utilisateur termine un agent, revient plus tard, envoie de nouveaux événements, termine à nouveau l'agent, et une deuxième évaluation s'exécute sur la transcription complète mise à jour. Le tableau de bord affiche l'évaluation la plus récente en titre principal et les évaluations précédentes dans une timeline repliable. Pendant qu'une évaluation est en cours pour une session, les événements `agent_end` supplémentaires pour cette session sont ignorés ; le prochain après la fin de l'évaluation en cours mettra en file d'attente une nouvelle évaluation normalement. + +Le mécanisme de secours d'inactivité se réactive également sur les sessions reprises : si de nouveaux événements arrivent après une évaluation terminale précédente et que la session passe ensuite en inactivité au-delà de `inactivity_timeout_secs`, une nouvelle évaluation est mise en file d'attente. + +Les échecs transitoires (5xx, 429, timeouts, erreurs réseau) sont relancés avec un backoff exponentiel jusqu'à `EVALUATOR_MAX_ATTEMPTS` ; les réponses 4xx sont terminales. Observability peut fonctionner en toute sécurité avec plusieurs instances serveur mises à l'échelle horizontalement ; le travail est réparti de sorte que la même session ne soit jamais envoyée deux fois simultanément. --- ## Contrat HTTP -Toutes les routes authentifiées utilisent **l'authentification par jeton bearer**. La même valeur doit être -configurée des deux côtés : +Chaque route authentifiée utilise **l'authentification par token Bearer**. La même valeur doit être configurée des deux côtés : - Serveur Observability : variable d'environnement `EVALUATOR_TOKEN` -- Service d'évaluation : configuré de la même façon (le SDK `agenteye-evaluator` lit - `EVALUATOR_TOKEN` par convention) +- Service évaluateur : configuré de la même manière (le SDK `agenteye-evaluator` lit `EVALUATOR_TOKEN` par convention) -Si `EVALUATOR_TOKEN` n'est pas défini, le serveur n'envoie pas d'en-tête `Authorization` ; l'évaluateur -peut alors accepter des requêtes anonymes, ce qui convient à un réseau purement interne -mais est déconseillé sur l'internet public. +Si `EVALUATOR_TOKEN` n'est pas défini, le serveur n'envoie pas d'en-tête `Authorization` ; l'évaluateur peut alors accepter des requêtes anonymes, ce qui convient à un réseau purement interne mais est déconseillé sur internet public. ### Routes que l'évaluateur doit exposer | Route | Corps / paramètres | Réponse | |---|---|---| -| `GET /health` | aucun | `{"status":"ok"}` (ouvert, sans authentification) | +| `GET /health` | aucun | `{"status":"ok"}` (ouverte, sans auth) | | `GET /config` | aucun | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | | `POST /evaluate` | JSON `EvalRequest` | `{"status":"done", ...}` ou `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | aucun | même format de réponse que `/evaluate` | +| `GET /evaluate/{id}` | aucun | même structure de réponse que `/evaluate` | ### Corps `EvalRequest` envoyé par le serveur @@ -120,9 +86,9 @@ mais est déconseillé sur l'internet public. } ``` -### Formats de réponse +### Structures de réponse -**Synchrone (done) :** +**Synchrone (terminé) :** ```json { @@ -136,12 +102,7 @@ mais est déconseillé sur l'internet public. } ``` -`reasoning` (une map de justification par score) et `summary` (un récit global -en un paragraphe) sont tous deux optionnels. Les clés de `reasoning` doivent -correspondre aux clés de `scores` ; le tableau de bord affiche chaque entrée en ligne sous -sa barre de score. Les anciens évaluateurs qui ne retournent que `scores` continuent de -fonctionner sans modification ; `reasoning` et `summary` sont simplement lus comme null et -les affordances d'interface correspondantes sont omises. +`reasoning` (une carte de justification par score) et `summary` (un récit global d'un paragraphe) sont tous deux optionnels. Les clés de `reasoning` doivent correspondre aux clés de `scores` ; le tableau de bord affiche chaque entrée sous sa barre de score. Les évaluateurs plus anciens qui renvoient uniquement `scores` continuent de fonctionner sans modification ; `reasoning` et `summary` sont simplement lus comme null et les affordances d'interface correspondantes sont omises. **Asynchrone (différé) :** @@ -149,9 +110,7 @@ les affordances d'interface correspondantes sont omises. { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` est optionnel ; s'il est omis, le serveur se rabat sur le -`default_poll_interval_secs` de l'évaluateur depuis `/config`, puis sur sa propre -variable d'environnement `EVALUATOR_POLLING_INTERVAL_SECS`. +`next_poll_secs` est optionnel ; s'il est omis, le serveur se rabat sur `default_poll_interval_secs` de l'évaluateur depuis `/config`, puis sur sa propre variable d'environnement `EVALUATOR_POLLING_INTERVAL_SECS`. **Erreur terminale côté évaluateur :** @@ -159,23 +118,17 @@ variable d'environnement `EVALUATOR_POLLING_INTERVAL_SECS`. { "status": "error", "error": "model service unavailable" } ``` -Le serveur traite tout autre corps 2xx comme une erreur de protocole et enregistre une -`error` terminale pour la session. +Le serveur traite tout autre corps 2xx comme une erreur de protocole et enregistre une `error` terminale pour la session. --- ## Écrire un évaluateur avec le SDK -Vous n'avez pas à implémenter le contrat HTTP manuellement. Le package Python -`agenteye-evaluator` vous fournit un wrapper FastAPI typé qui gère l'authentification, -le routage et les formats requête/réponse à votre place. +Vous n'avez pas besoin d'implémenter le contrat HTTP manuellement. Le package Python `agenteye-evaluator` vous fournit un wrapper FastAPI typé qui gère l'authentification, le routage et les structures requête/réponse à votre place. -Failproof AI Observability inclut également un **évaluateur de référence fonctionnel** qui -note `helpfulness`, `tool_efficiency` et `factuality` à partir de la forme de la transcription. -Copiez-le comme point de départ et remplacez-y votre propre logique : un juge LLM, un moteur de règles, -ou tout ce qui correspond à vos critères de qualité. +Failproof AI Observability inclut également un **évaluateur de référence fonctionnel** qui note `helpfulness`, `tool_efficiency` et `factuality` à partir de la forme de la transcription. Copiez-le comme point de départ et substituez votre propre logique : un juge LLM, un moteur de règles, tout ce qui correspond à votre critère de qualité. -Évaluateur minimal : +Évaluateur minimal viable : ```python import os @@ -196,28 +149,17 @@ def run(req: EvalRequest) -> EvalResponse: L'instance `app` s'exécute sous n'importe quel serveur ASGI, donc `uvicorn module:app` suffit à la démarrer. -Pour les évaluateurs qui ont besoin de différer un traitement coûteux, retournez `JobPending` -à la place et enregistrez un handler `@app.job_lookup` ; le serveur Observability interroge -`GET /evaluate/{job_id}` jusqu'à ce que vous retourniez un statut terminal ou que le plafond -`EVALUATOR_MAX_POLL_DURATION_SECS` (défaut : 1 h) soit atteint. +Pour les évaluateurs qui doivent différer un travail coûteux, renvoyez `JobPending` à la place et enregistrez un gestionnaire `@app.job_lookup` ; le serveur Observability sonde `GET /evaluate/{job_id}` jusqu'à ce que vous renvoyiez un statut terminal ou que le plafond `EVALUATOR_MAX_POLL_DURATION_SECS` (1 h par défaut) soit atteint. -La référence complète de l'API, le pattern asynchrone et le schéma des événements sont documentés dans -le README du SDK `agenteye-evaluator`. +La référence complète de l'API, le schéma asynchrone et le schéma des événements sont documentés dans le README du SDK `agenteye-evaluator`. --- ## Exécuter votre évaluateur -L'évaluateur est **votre service** — Failproof AI Observability ne fournit pas d'évaluateur -par défaut, vous devez donc le créer et l'exécuter là où vous déployez vos propres services. -Il s'exécute sous n'importe quel serveur ASGI (par exemple `uvicorn my_evaluator:app`) ; exposez -les routes `/health`, `/config` et `/evaluate` du -[contrat HTTP](#http-contract), puis pointez le serveur vers ce service (voir -[Configurer le serveur](#configuring-the-server)). +L'évaluateur est **votre service** — Failproof AI Observability ne fournit pas d'évaluateur par défaut, vous le construisez et l'exécutez là où vous déployez vos propres services. Il s'exécute sous n'importe quel serveur ASGI (par exemple `uvicorn my_evaluator:app`) ; exposez les routes `/health`, `/config` et `/evaluate` du [contrat HTTP](#http-contract), puis pointez le serveur vers ce service (voir [Configurer le serveur](#configuring-the-server)). -Une fois l'évaluateur accessible, `GET /health` retourne `{"status":"ok"}`. Après -l'exécution complète d'un agent, `GET /evaluations` sur le serveur retourne une ligne avec -`status: "done"` et les scores produits par votre évaluateur. +Une fois l'évaluateur accessible, `GET /health` renvoie `{"status":"ok"}`. Après l'exécution complète d'un agent, `GET /evaluations` sur le serveur renvoie une ligne avec `status: "done"` et les scores produits par votre évaluateur. --- @@ -225,55 +167,47 @@ l'exécution complète d'un agent, `GET /evaluations` sur le serveur retourne un À définir sur le processus serveur : -| Variable d'env. | Signification | +| Variable d'env | Signification | |---|---| -| `EVALUATOR_ENDPOINT` | URL de base de votre évaluateur (`http://evaluator:9000`). Non défini = pipeline désactivé. | -| `EVALUATOR_TOKEN` | Jeton bearer. Doit correspondre à la valeur configurée sur le service d'évaluation. | -| `EVALUATOR_WORKERS` | Tâches de travail par instance de serveur (défaut : 2). | -| `EVALUATOR_CLAIM_BATCH` | Lignes réclamées par tick de travail (défaut : 4). Les lots sont traités **en parallèle** ; la concurrence effective sur votre endpoint d'évaluation est `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Durée de veille d'un worker entre les tentatives de dispatch lorsqu'aucune évaluation n'est due (défaut : 2 s). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Dernier recours pour la cadence de `GET /evaluate/{id}` lorsque ni `next_poll_secs` par réponse ni `default_poll_interval_secs` de l'évaluateur ne sont définis (défaut : 10 s). | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | Délai d'expiration par requête (défaut : 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | Après ce nombre d'échecs transitoires, le résultat est enregistré comme `error` terminal (défaut : 5). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | Cadence de `GET /config` (défaut : 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Durée maximale en temps réel pendant laquelle une session peut rester dans la file de polling avant d'être terminée en `timeout` (défaut : 3600 s). Protège contre un évaluateur qui retourne indéfiniment `pending`. | - -Pour activer la notation automatique, définissez `EVALUATOR_ENDPOINT` et -`EVALUATOR_TOKEN` sur le serveur, puis redémarrez-le pour prendre en compte les modifications. Avec -`EVALUATOR_ENDPOINT` non défini, le pipeline reste sans effet. - -Les paramètres de réglage ci-dessus sont optionnels ; définissez les variables d'environnement -correspondantes sur le serveur uniquement si vous avez besoin de remplacer les valeurs par défaut. +| `EVALUATOR_ENDPOINT` | URL de base de votre évaluateur (`http://evaluator:9000`). Non définie = pipeline désactivé. | +| `EVALUATOR_TOKEN` | Token Bearer. Doit correspondre à la valeur configurée dans le service évaluateur. | +| `EVALUATOR_WORKERS` | Tâches de travail par instance serveur (2 par défaut). | +| `EVALUATOR_CLAIM_BATCH` | Lignes réclamées par tick de worker (4 par défaut). Les lots sont traités **de manière concurrente** ; la concurrence effective sur votre endpoint évaluateur est `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Durée de mise en veille d'un worker entre les tentatives de dispatch lorsqu'aucune évaluation n'est due (2 s par défaut). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Dernier recours pour la cadence de `GET /evaluate/{id}` lorsque ni `next_poll_secs` par réponse ni `default_poll_interval_secs` de l'évaluateur ne sont définis (10 s par défaut). | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Timeout par requête (30000 par défaut). | +| `EVALUATOR_MAX_ATTEMPTS` | Après ce nombre d'échecs transitoires, le résultat est enregistré comme `error` terminal (5 par défaut). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | Cadence de `GET /config` (300 par défaut). | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Durée maximale en temps réel pendant laquelle une session peut rester dans la file de sondage avant d'être terminée comme `timeout` (3600 s par défaut). Protège contre un évaluateur qui renvoie indéfiniment `pending`. | + +Pour activer la notation automatique, définissez `EVALUATOR_ENDPOINT` et `EVALUATOR_TOKEN` sur le serveur, puis redémarrez-le pour prendre en compte le changement. Avec `EVALUATOR_ENDPOINT` non défini, le pipeline reste inactif. + +Les paramètres de réglage ci-dessus sont optionnels ; définissez les variables d'environnement correspondantes sur le serveur uniquement si vous avez besoin de remplacer les valeurs par défaut. --- ## Référence API -| Méthode | Chemin | Permission requise | Objectif | +| Méthode | Chemin | Permission requise | Objet | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Interroger les résultats terminaux. Supporte `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` vaut 50 par défaut et est plafonné à 200 (contrairement à `/events`, plafonné à 1000). `environment` accepte une liste séparée par des virgules (ex. `environment=prod,staging`) ; les valeurs uniques fonctionnent toujours. Avec `latest_per_session=true`, la réponse contient au plus une ligne par `session_id` (la plus récente par `completed_at`), utilisée par la page de liste des sessions pour réduire la chronologie d'évaluation d'une session à son titre actuel. Vaut false par défaut (retourne l'historique complet). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | Bilan de santé d'évaluation agrégé pour une tranche filtrée : nombre total, répartition done/error/timeout, statistiques par clé de score (count/avg/min/max/p50 sur les clés `scores` arbitraires) et chronologie par tranches de temps. Accepte les **mêmes paramètres de filtre que `/evaluations`** plus `featured_keys` (CSV de clés de score à suivre) et `latest_per_session`. Alimente la fonctionnalité Tableaux de bord ; les métriques sont exactes sur l'ensemble correspondant, sans échantillonnage. | -| `GET` | `/evaluations/environments` | `evaluations:read` | Valeurs d'environnement distinctes de la table `evaluations`. Utilisé pour alimenter les menus déroulants de filtre limités aux données accessibles en lecture d'évaluation. | +| `GET` | `/evaluations` | `evaluations:read` | Interroger les résultats terminaux. Prend en charge `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` est 50 par défaut et plafonné à 200 (différent de `/events` qui plafonne à 1000). `environment` accepte une liste séparée par des virgules (ex. `environment=prod,staging`) ; les valeurs uniques fonctionnent toujours. Avec `latest_per_session=true`, la réponse contient au plus une ligne par `session_id` (la plus récente selon `completed_at`), utilisée par la page de liste des sessions pour réduire la timeline d'évaluation d'une session à son titre courant. Par défaut false (renvoie l'historique complet). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | Synthèse de la santé d'évaluation pour une tranche filtrée : nombre total, ventilation done/error/timeout, statistiques par clé de score (count/avg/min/max/p50 sur les clés `scores` arbitraires), et une timeline par tranche temporelle. Accepte les **mêmes paramètres de filtre que `/evaluations`** plus `featured_keys` (CSV des clés de score à suivre) et `latest_per_session`. Alimente la fonctionnalité Tableaux de bord ; les métriques sont exactes sur l'ensemble correspondant, sans échantillonnage. | +| `GET` | `/evaluations/environments` | `evaluations:read` | Valeurs d'environnement distinctes de la table `evaluations`. Utilisé pour alimenter les listes déroulantes de filtre limitées aux données lisibles par évaluation. | | `GET` | `/evaluation-jobs` | `evaluations:read` | Visibilité sur les évaluations en cours. Filtrage par `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | Diffuser les événements bruts d'une session. Supporte `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` et `order`. `order` vaut `desc` (plus récent en premier, par défaut) ou `asc` (plus ancien en premier) ; une valeur non reconnue se rabat sur `desc`. Pagination par curseur via le `next_cursor` de la réponse (un identifiant d'événement) : passez-le en tant que `cursor` pour obtenir la page suivante ; avec `asc` la page suivante correspond aux événements après cet identifiant, avec `desc` aux événements avant. `limit` vaut 50 par défaut et est plafonné à 1000. | -| `GET` | `/sessions/:session_id/export` | `events:read` | Retourne le corps JSON exact que l'évaluateur recevrait pour cette session, servi comme pièce jointe téléchargeable nommée `session-.json`. Utile pour rejouer des sessions de production via `agenteye-evaluator` pour des tests hors ligne. Les octets sont identiques à ceux envoyés par le pipeline d'évaluation. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Met en file d'attente une nouvelle évaluation pour une session ; s'exécute qu'une évaluation précédente existe ou non. Le nouveau résultat est **ajouté** à la chronologie d'évaluation de la session plutôt que d'écraser le précédent, de sorte que les scores antérieurs restent visibles en historique. Retourne `202` lors de la mise en file d'attente, `404` pour une session inconnue, `409` si une évaluation est déjà en cours. À utiliser après le déploiement d'un nouvel évaluateur, ou pour des sessions qui n'ont jamais émis `agent_end`. | +| `GET` | `/events` | `events:read` | Diffuser les événements bruts d'une session. Prend en charge `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` et `order`. `order` est `desc` (du plus récent au plus ancien, par défaut) ou `asc` (du plus ancien au plus récent) ; une valeur non reconnue se rabat sur `desc`. Paginez via le `next_cursor` de la réponse (un identifiant d'événement) : passez-le comme `cursor` pour obtenir la page suivante ; avec `asc` la page suivante contient les événements après cet identifiant, avec `desc` les événements avant. `limit` est 50 par défaut et plafonné à 1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | Renvoie le corps JSON exact que l'évaluateur recevrait pour cette session, servi comme pièce jointe téléchargeable nommée `session-.json`. Utile pour rejouer des sessions de production via `agenteye-evaluator` pour des tests hors ligne. Les octets sont identiques à ce qu'envoie le pipeline évaluateur. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Mettre en file d'attente une nouvelle évaluation pour une session ; s'exécute qu'une évaluation précédente existe ou non. Le nouveau résultat est **ajouté** à la timeline d'évaluation de la session plutôt que d'écraser le précédent, de sorte que les scores antérieurs restent visibles dans l'historique. Renvoie `202` lors de la mise en file d'attente, `404` pour une session inconnue, `409` si une évaluation est déjà en cours. À utiliser après le déploiement d'un nouvel évaluateur, ou pour les sessions qui n'ont jamais émis `agent_end`. | ### Filtrage par plage de score : `score_filters` -`GET /evaluations` accepte un paramètre optionnel `score_filters` qui -restreint les résultats par valeurs numériques dans l'objet `scores`. Le -paramètre est une liste séparée par des virgules d'entrées `key:min..max` ; chaque -borne peut être omise. Plusieurs entrées se combinent avec un ET logique. Les lignes -où la clé nommée est absente ou non numérique sont exclues. Une requête peut -contenir au maximum 20 entrées de filtre ; au-delà, HTTP 400 est retourné. +`GET /evaluations` accepte un paramètre optionnel `score_filters` qui restreint les résultats par valeurs numériques à l'intérieur de l'objet `scores`. Le paramètre est une liste séparée par des virgules d'entrées `key:min..max` ; chaque borne peut être omise. Plusieurs entrées se combinent par ET logique. Les lignes où la clé nommée est absente ou non numérique sont exclues. Une requête peut contenir au plus 20 entrées de filtre ; au-delà, HTTP 400 est renvoyé. Exemples : ```text # helpfulness dans [0.5, 0.8] GET /evaluations?score_filters=helpfulness:0.5..0.8 -# tool_efficiency au plus 0.3 (sans borne inférieure) +# tool_efficiency au plus 0.3 (pas de borne inférieure) GET /evaluations?score_filters=tool_efficiency:..0.3 # helpfulness >= 0.5 ET factuality >= 0.9 @@ -284,20 +218,20 @@ Chaque objet de réponse `/evaluations` possède ces champs : | Champ | Type | Notes | |---|---|---| -| `evaluation_id` | string (UUID) | L'identifiant canonique de cette évaluation terminale. Chaque évaluation terminale reçoit un nouvel UUID ; une seule session peut en contenir plusieurs. | -| `id` | string (UUID) | Alias de compatibilité ascendante portant la même valeur que `evaluation_id`. | -| `session_id` | string | La session contre laquelle cette évaluation a été exécutée. Une session peut avoir plusieurs évaluations dans sa chronologie. | -| `agent_id` | string | Identifie l'agent qui a produit la session. | -| `environment` | string | Libellé d'environnement copié depuis la session. | -| `status` | enum | L'une des valeurs `"done"`, `"error"`, `"timeout"`. | -| `scores` | object \| null | Scores retournés par votre évaluateur. | -| `reasoning` | object \| null | Map de justification optionnelle par score retournée par votre évaluateur. Les clés correspondent généralement à celles de `scores`. Le tableau de bord affiche chaque entrée sous sa barre de score. | -| `summary` | string \| null | Récit global optionnel en un paragraphe retourné par votre évaluateur. Le tableau de bord l'affiche au-dessus de la répartition par score comme titre de l'évaluation. | -| `error` | string \| null | Renseigné uniquement pour `"error"` / `"timeout"`. | -| `attempt_count` | integer | Nombre de tentatives de dispatch (≥ 1). | -| `duration_ms` | integer \| null | Durée de la dernière tentative. | -| `completed_at` | string (ISO 8601 UTC) | Moment où le résultat terminal a été enregistré. Les résultats sont ordonnés par `completed_at` (plus récent en premier). | -| `created_at` | string (ISO 8601 UTC) | Porte le même horodatage que `completed_at` (sémantique d'écriture unique). | +| `evaluation_id` | chaîne (UUID) | L'identifiant canonique de cette évaluation terminale. Chaque évaluation terminale reçoit un nouvel UUID ; une même session peut en avoir plusieurs. | +| `id` | chaîne (UUID) | Alias de compatibilité descendante portant la même valeur que `evaluation_id`. | +| `session_id` | chaîne | La session sur laquelle cette évaluation a été exécutée. Une session peut avoir plusieurs évaluations dans sa timeline. | +| `agent_id` | chaîne | Identifie l'agent qui a produit la session. | +| `environment` | chaîne | Label d'environnement copié depuis la session. | +| `status` | enum | L'un de `"done"`, `"error"`, `"timeout"`. | +| `scores` | objet \| null | Scores renvoyés par votre évaluateur. | +| `reasoning` | objet \| null | Carte de justification optionnelle par score renvoyée par votre évaluateur. Les clés correspondent généralement à celles de `scores`. Le tableau de bord affiche chaque entrée sous sa barre de score. | +| `summary` | chaîne \| null | Récit global optionnel d'un paragraphe renvoyé par votre évaluateur. Le tableau de bord l'affiche au-dessus de la ventilation par score comme titre de l'évaluation. | +| `error` | chaîne \| null | Renseigné uniquement pour `"error"` / `"timeout"`. | +| `attempt_count` | entier | Nombre de tentatives de dispatch (≥ 1). | +| `duration_ms` | entier \| null | Durée de la dernière tentative. | +| `completed_at` | chaîne (ISO 8601 UTC) | Moment où le résultat terminal a été enregistré. Les résultats sont ordonnés par `completed_at` (du plus récent au plus ancien). | +| `created_at` | chaîne (ISO 8601 UTC) | Porte le même horodatage que `completed_at` (sémantique en écriture unique). | --- @@ -307,7 +241,7 @@ Chaque objet de réponse `/evaluations` possède ces champs : |---|---| | `evaluations:read` | Lister les résultats d'évaluation, afficher les scores dans le tableau de bord et charger les métriques de santé du tableau de bord. | | `evaluations:trigger` | Mettre manuellement en file d'attente une évaluation pour une session via `POST /sessions/:session_id/re-evaluate` ou le bouton de réévaluation du tableau de bord. | -| `dashboards:read` | Consulter les tableaux de bord sauvegardés (nécessite également `evaluations:read` pour charger leurs métriques). | +| `dashboards:read` | Afficher les tableaux de bord sauvegardés (nécessite également `evaluations:read` pour charger leurs métriques). | | `dashboards:write` | Créer et modifier des tableaux de bord. | | `dashboards:delete` | Supprimer des tableaux de bord. | @@ -315,87 +249,52 @@ L'administrateur bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) reçoit automatiquement --- -## Consultation des résultats +## Consulter les résultats -- **`/sessions/`** : chronologie des événements + un rail droit affichant les scores de la session - et toute erreur de la tentative de dispatch. Si votre clé possède - `evaluations:trigger`, un bouton **re-evaluate** apparaît à côté du bouton d'export, - utile pour les sessions qui n'ont jamais émis `agent_end`, ou pour - actualiser les scores après le déploiement d'un nouvel évaluateur. Le tableau de bord interroge - le nouveau résultat et met à jour le rail droit à son arrivée. -- **`/sessions`** : grille de sessions filtrables ; la colonne de score montre le statut - d'évaluation et les scores de chaque session en un coup d'œil. +- **`/sessions/`** : timeline des événements + panneau latéral droit affichant les scores de la session et toute erreur de la tentative de dispatch. Si votre clé dispose de `evaluations:trigger`, un bouton **re-evaluate** apparaît à côté du bouton d'export, utile pour les sessions qui n'ont jamais émis `agent_end` ou pour actualiser les scores après le déploiement d'un nouvel évaluateur. Le tableau de bord interroge le nouveau résultat et met à jour le panneau latéral dès qu'il arrive. +- **`/sessions`** : grille de sessions filtrable ; la colonne de score affiche le statut d'évaluation et les scores de chaque session en un coup d'œil. - **`/dashboards`** : vues de santé d'évaluation sauvegardées (voir [Tableaux de bord](#dashboards) ci-dessous). -![La grille Sessions avec des pastilles de statut d'évaluation par session et des badges de score colorés (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) +![La grille des sessions avec des badges de statut d'évaluation par session et des badges de score colorés (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) -*La grille des sessions affiche le statut d'évaluation et les scores de chaque exécution en un coup d'œil ; les badges rouge/orange/vert font ressortir les scores faibles.* +*La grille des sessions affiche le statut d'évaluation et les scores de chaque exécution en un coup d'œil ; des badges rouge/orange/vert font ressortir immédiatement les scores faibles.* --- ## Tableaux de bord -La page **Tableaux de bord** (`/dashboards`) vous permet de sauvegarder une combinaison de filtres -d'évaluation sous forme de vue nommée et réutilisable, et de surveiller la santé de cette tranche -d'évaluations en un coup d'œil. Les tableaux de bord sont **partagés au sein de toute votre organisation** ; -toute personne disposant de `dashboards:read` voit le même ensemble. +La page **Tableaux de bord** (`/dashboards`) vous permet de sauvegarder une combinaison de filtres d'évaluation sous forme de vue nommée et réutilisable, et de surveiller l'état de cette tranche d'évaluations en un coup d'œil. Les tableaux de bord sont **partagés à l'échelle de toute votre organisation** ; tous ceux disposant de `dashboards:read` voient le même ensemble. -Chaque tableau de bord épingle : +Chaque tableau de bord fixe : -- **Des filtres** : les mêmes contrôles que la page des sessions : environnement, statut, - agent, une fenêtre temporelle glissante et des filtres de plage de score (`key:min..max`). -- **Une configuration d'affichage** : quelles clés de score mettre en avant, les seuils de santé - vert/orange/rouge, quels panneaux afficher et s'il faut réduire à la dernière évaluation par session. +- **Filtres** : les mêmes contrôles que la page des sessions : environnement, statut, agent, une fenêtre temporelle glissante et des filtres de plage de score (`key:min..max`). +- **Une configuration d'affichage** : quelles clés de score mettre en avant, les seuils de santé vert/orange/rouge, quels panneaux afficher et si l'on doit réduire à la dernière évaluation par session. -Chaque carte affiche le nombre de sessions correspondantes, une répartition done/error/timeout, -la moyenne de chaque score mis en avant et une petite sparkline de tendance. Ouvrir un tableau de bord -affiche les panneaux en plein écran ; **« ouvrir dans les sessions »** vous conduit vers la -page des sessions pré-filtrée sur exactement cette tranche. Les métriques sont calculées -côté serveur sur l'ensemble correspondant (via `GET /evaluations/aggregate`), les chiffres sont donc -exacts plutôt qu'échantillonnés. +Chaque carte affiche le nombre de sessions correspondantes, une ventilation done/error/timeout, la moyenne de chaque score mis en avant et un petit graphique sparkline de tendance. Ouvrir un tableau de bord affiche les panneaux en plein écran ; **« ouvrir dans les sessions »** vous redirige vers la page des sessions pré-filtrée exactement sur cette tranche. Les métriques sont calculées côté serveur sur l'ensemble correspondant (via `GET /evaluations/aggregate`), donc les chiffres sont exacts et non échantillonnés. -![Un tableau de bord de santé d'évaluation avec des barres de score moyen par dimension d'évaluateur, une répartition outil ok/erreur, les meilleurs outils et une tendance d'événements par heure](/agenteye/images/dashboard-quality.png) +![Un tableau de bord de santé d'évaluation avec des barres de score moyen par dimension d'évaluateur, une ventilation outil ok/erreur, les outils les plus utilisés et une tendance événements par heure](/agenteye/images/dashboard-quality.png) -**Permissions :** la consultation nécessite à la fois `dashboards:read` et `evaluations:read` ; -la création et la modification nécessitent `dashboards:write` ; la suppression nécessite `dashboards:delete`. -L'administrateur bootstrap reçoit toutes ces permissions automatiquement. +**Permissions :** la consultation nécessite `dashboards:read` et `evaluations:read` ; la création et la modification nécessitent `dashboards:write` ; la suppression nécessite `dashboards:delete`. L'administrateur bootstrap reçoit toutes ces permissions automatiquement. --- -## Résolution des problèmes +## Dépannage -**Des sessions existent mais aucune évaluation n'est créée.** Vérifiez que `EVALUATOR_ENDPOINT` -est défini sur le processus serveur, que le serveur et l'évaluateur partagent la même valeur -`EVALUATOR_TOKEN` et que l'endpoint `/health` de l'évaluateur est accessible depuis le serveur. -Sans `EVALUATOR_ENDPOINT` défini, le pipeline est sans effet. +**Des sessions existent mais aucune évaluation n'est créée.** Vérifiez que `EVALUATOR_ENDPOINT` est défini sur le processus serveur, que le serveur et l'évaluateur partagent la même valeur `EVALUATOR_TOKEN`, et que le endpoint `/health` de l'évaluateur est accessible depuis le serveur. Avec `EVALUATOR_ENDPOINT` non défini, le pipeline est inactif. -**Les évaluations en cours s'accumulent.** Interrogez `GET /evaluation-jobs` pour voir la file -en cours. Inspectez `attempt_count`, `next_attempt_at` et `last_error` sur chaque ligne. -Causes courantes : service d'évaluation inaccessible ou retournant des erreurs 5xx (réessayées avec backoff), -`EVALUATOR_TOKEN` incorrect (401 est terminal), ou un évaluateur asynchrone qui retourne `pending` -indéfiniment (voir ci-dessous). +**Les évaluations en cours s'accumulent.** Interrogez `GET /evaluation-jobs` pour voir la file en cours. Inspectez `attempt_count`, `next_attempt_at` et `last_error` sur chaque ligne. Causes courantes : service évaluateur inaccessible ou renvoyant des 5xx (réessayé avec backoff), mauvais `EVALUATOR_TOKEN` (401 est terminal), ou un évaluateur asynchrone qui renvoie `pending` indéfiniment (voir ci-dessous). -**Des sessions sont terminées mais sans évaluation terminale.** Interrogez -`GET /evaluation-jobs?status=polling` ; le résultat est peut-être encore en cours. -Si une tâche est bloquée en `pending`, le serveur a du mal à joindre l'évaluateur ; -vérifiez que l'évaluateur est opérationnel et que `EVALUATOR_TOKEN` correspond. +**Les sessions sont terminées mais aucune évaluation terminale.** Interrogez `GET /evaluation-jobs?status=polling` ; le résultat peut encore être en cours. Si une tâche est bloquée sur `pending`, le serveur a du mal à joindre l'évaluateur ; vérifiez que l'évaluateur est opérationnel et que `EVALUATOR_TOKEN` correspond. -**`HTTP 401 from evaluator: invalid bearer token`.** Le `EVALUATOR_TOKEN` -sur le serveur ne correspond pas à la valeur configurée sur le service d'évaluation. -Ils doivent être identiques. +**`HTTP 401 from evaluator: invalid bearer token`.** Le `EVALUATOR_TOKEN` sur le serveur ne correspond pas à la valeur configurée dans le service évaluateur. Ils doivent être identiques. -**L'évaluateur asynchrone retourne `pending` indéfiniment.** Le serveur interroge -`GET /evaluate/{job_id}` jusqu'à ce que l'évaluateur retourne `done` ou `error`, ou -jusqu'à ce que le plafond `EVALUATOR_MAX_POLL_DURATION_SECS` (défaut : 1 h) soit atteint. -Passé ce délai, l'évaluation est enregistrée comme `timeout` et retirée de la file en cours. -Augmentez `EVALUATOR_MAX_POLL_DURATION_SECS` si votre évaluateur a légitimement besoin -de plus de temps que la valeur par défaut. +**L'évaluateur asynchrone renvoie `pending` indéfiniment.** Le serveur sonde `GET /evaluate/{job_id}` jusqu'à ce que l'évaluateur renvoie `done` ou `error`, ou jusqu'à ce que le plafond `EVALUATOR_MAX_POLL_DURATION_SECS` (1 h par défaut) soit atteint. Passé ce délai, l'évaluation est enregistrée comme `timeout` et retirée de la file en cours. Augmentez `EVALUATOR_MAX_POLL_DURATION_SECS` si votre évaluateur a légitimement besoin de plus de temps que la valeur par défaut. --- ## Prochaines étapes -- [Compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) : demandez à un agent de codage de concevoir vos dimensions à partir de sessions réelles et de créer ce service pour vous. +- [Compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) : demandez à un agent de codage de concevoir vos dimensions sur des sessions réelles et de construire ce service pour vous. - [SDK Python](/fr/agenteye/python-sdk) : émettez les événements `agent_end` qui déclenchent la notation. - [Clés API](/fr/agenteye/api-keys) : les permissions `evaluations:read` et `evaluations:trigger`. -- [Audits](/fr/agenteye/audits) : l'autre fonctionnalité de contrôle qualité automatisé d'Observability, pour la revue basée sur des politiques. \ No newline at end of file +- [Audits](/fr/agenteye/audits) : l'autre fonctionnalité de qualité automatisée d'Observability, pour la revue basée sur des politiques. \ No newline at end of file diff --git a/docs/fr/agenteye/evaluations.mdx b/docs/fr/agenteye/evaluations.mdx index d442dd0f..5c83c186 100644 --- a/docs/fr/agenteye/evaluations.mdx +++ b/docs/fr/agenteye/evaluations.mdx @@ -1,50 +1,50 @@ --- title: "Évaluations" -description: "Les problèmes de qualité viennent à vous, au lieu d'en entendre parler dans une réclamation utilisateur." +description: "Les problèmes de qualité viennent à vous, au lieu de les découvrir dans une plainte utilisateur." --- -Les problèmes de qualité viennent à vous, au lieu d'en entendre parler dans une réclamation utilisateur. Connectez votre propre service de scoring une seule fois et Failproof AI Observability note chaque exécution terminée automatiquement — ainsi, une baisse d'utilité ou une hausse des hallucinations apparaît d'elle-même, avant qu'un client ne le ressente. +Les problèmes de qualité viennent à vous, au lieu de les découvrir dans une plainte utilisateur. Connectez votre propre service de scoring une fois, et Failproof AI Observability note automatiquement chaque exécution terminée — ainsi, une baisse d'utilité ou une hausse des hallucinations apparaît d'elle-même, avant qu'un client ne le ressente. -![La grille des sessions avec une colonne de scores : chaque exécution porte un badge d'état d'évaluation et des indicateurs codés par couleur pour l'utilité, la factualité et l'efficacité des outils](/agenteye/images/sessions-list.png) +![La grille Sessions avec une colonne de score : chaque exécution porte un badge de statut d'évaluation et des badges codés par couleur pour l'utilité, la factualité et l'efficacité des outils](/agenteye/images/sessions-list.png) -*Chaque exécution dans la grille des sessions affiche ses scores ; les badges rouges, ambrés et verts font ressortir les exécutions faibles sans que vous ayez à ouvrir une seule transcription.* +*Chaque exécution dans la grille des sessions affiche ses scores ; des badges rouge, orange et vert font ressortir les exécutions faibles sans que vous n'ayez à ouvrir une seule transcription.* -## Arrêtez de contrôler manuellement les exécutions +## Arrêtez de vérifier les exécutions manuellement -Vous vérifiez encore quelques exécutions au hasard en espérant que le reste est correct. Désormais, chaque session terminée est scorée au moment où elle se termine, selon les dimensions qui vous importent : utilité, efficacité des outils, factualité, sécurité, quel que soit votre seuil de qualité. Vous définissez les clés de score ; Failproof AI Observability stocke, suit les tendances et affiche tout ce que votre évaluateur renvoie. Aucune exécution ne passe sans être scorée, et vous n'apprendrez plus une régression via un ticket de support. +Auparavant, vous contrôliez quelques exécutions au hasard en espérant que les autres étaient correctes. Désormais, chaque session terminée est notée dès qu'elle se termine, selon les dimensions qui vous importent : utilité, efficacité des outils, factualité, sécurité — quel que soit votre critère de qualité. Vous définissez les clés de score ; Failproof AI Observability stocke, suit les tendances et affiche tout ce que votre évaluateur renvoie. Aucune exécution n'échappe à l'évaluation, et vous ne découvrez plus une régression via un ticket de support. -Les scores apparaissent dans la grille des sessions à **`//sessions`** (barre latérale → *observe* → *sessions*), avec un groupe de badges par ligne. Vous voulez uniquement les exécutions en dessous du seuil ? Filtrez la grille par plage de scores — par exemple, une utilité inférieure à 0,5 — pour afficher exactement les exécutions qui méritent d'être lues. La consultation des scores nécessite la permission `evaluations:read`. +Les scores s'affichent dans la grille des sessions à **`//sessions`** (barre latérale → *observer* → *sessions*), avec un groupe de badges par ligne. Vous voulez uniquement les exécutions insuffisantes ? Filtrez la grille par plage de score — par exemple utilité en dessous de 0,5 — et obtenez exactement les exécutions qui méritent d'être lues. La consultation des scores nécessite la permission `evaluations:read`. ## Comprendre pourquoi une exécution a obtenu un score faible -Un chiffre vous indique qu'une exécution était faible ; la page de session vous explique pourquoi. Ouvrez n'importe quelle exécution et le panneau de droite commence par le résumé principal, puis affiche une barre par dimension avec le raisonnement de votre évaluateur sous chacune — ainsi, vous passez de « cette exécution a obtenu 0,4 en factualité » à l'affirmation exacte qui était incorrecte en quelques secondes. +Un chiffre vous indique qu'une exécution était faible ; la page de session vous dit pourquoi. Ouvrez n'importe quelle exécution : le panneau de droite commence par le résumé général, puis affiche une barre par dimension avec le raisonnement de votre évaluateur sous chacune, vous permettant de passer de « score de 0,4 en factualité » à l'affirmation exacte qui posait problème en quelques secondes. -![Le panneau droit d'une session : le résumé de l'évaluation en haut, puis des barres de score par dimension avec une ligne de raisonnement pour chacune, à côté de la chronologie complète des événements](/agenteye/images/session-detail.png) +![Le panneau droit d'une session : le résumé d'évaluation en haut, puis des barres de score par dimension avec une ligne de raisonnement chacune, à côté de la chronologie complète des événements](/agenteye/images/session-detail.png) -*La vue détaillée d'une session : résumé, barres de score par dimension et le raisonnement derrière chaque score, juste à côté de la chronologie des événements de l'exécution.* +*La vue détail d'une session : résumé, barres de score par dimension et raisonnement derrière chaque score, directement à côté de la chronologie des événements.* -Vous avez déployé un évaluateur plus précis, ou vous regardez une exécution qui a planté avant d'être scorée ? Un bouton **re-evaluate** (conditionné par `evaluations:trigger`) rescote la session sur place et ajoute le nouveau résultat à sa chronologie, de sorte que les scores antérieurs restent visibles comme historique. Vous le trouverez à **`//sessions/`**. +Vous avez déployé un évaluateur plus précis, ou vous consultez une exécution qui a planté avant d'être notée ? Un bouton **re-evaluate** (soumis à `evaluations:trigger`) re-note la session sur place et ajoute le nouveau résultat à sa chronologie, tout en conservant les scores précédents comme historique. Vous le trouverez à **`//sessions/`**. -## Suivre l'évolution de la qualité sur l'ensemble du parc +## Suivre la tendance qualité sur l'ensemble du parc -Une exécution avec un score faible est du bruit ; toute une cohorte qui glisse est un signal. Les tableaux de bord sauvegardés transforment vos scores en une tendance que vous pouvez surveiller d'un coup d'œil : utilité moyenne cette semaine par rapport à la semaine dernière, par agent, par environnement. +Une seule exécution avec un score faible, c'est du bruit ; toute une cohorte en baisse, c'est un signal. Les tableaux de bord enregistrés transforment vos scores en une tendance observable d'un coup d'œil : utilité moyenne cette semaine par rapport à la semaine dernière, par agent, par environnement. -![Un tableau de bord qualité : barres de score moyen par dimension d'évaluation accompagnées d'une tendance dans le temps](/agenteye/images/dashboard-quality.png) +![Un tableau de bord qualité : barres de score moyen par dimension d'évaluation et tendance dans le temps](/agenteye/images/dashboard-quality.png) -*Un tableau de bord qualité sauvegardé suit les clés de score que vous mettez en avant, afin qu'une dérive progressive soit évidente bien avant de devenir un incident.* +*Un tableau de bord qualité enregistré suit les clés de score que vous mettez en avant, rendant une dérive progressive évidente bien avant qu'elle ne devienne un incident.* -Les tableaux de bord se trouvent à **`//dashboards`** (barre latérale → *analyze* → *dashboards*), sont partagés dans toute votre organisation, et chaque carte regroupe les sessions correspondantes : leur nombre, la moyenne de chaque score mis en avant et un graphique sparkline de tendance. « Open in sessions » vous amène directement aux exécutions pré-filtrées derrière n'importe quel chiffre. La consultation nécessite `dashboards:read` ainsi que `evaluations:read`. +Les tableaux de bord sont accessibles à **`//dashboards`** (barre latérale → *analyser* → *dashboards*), sont partagés dans toute votre organisation, et chaque carte agrège les sessions correspondantes : leur nombre, la moyenne de chaque score mis en avant, et une sparkline de tendance. « Ouvrir dans les sessions » vous amène directement aux exécutions pré-filtrées derrière n'importe quel chiffre. La consultation nécessite `dashboards:read` ainsi que `evaluations:read`. ## Connecter un évaluateur une seule fois -Le scoring est optionnel et reste complètement désactivé jusqu'à ce que vous pointiez Failproof AI Observability vers un scorer. Vous déployez un petit service HTTP (Observability fournit une référence fonctionnelle que vous pouvez copier), définissez deux valeurs sur votre serveur, et chaque exécution à partir de ce moment est scorée pour vous. Le guide complet, le contrat de scoring et le SDK se trouvent dans le guide approfondi. +Le scoring est optionnel et reste totalement désactivé jusqu'à ce que vous indiquiez à Failproof AI Observability où se trouve un scorer. Vous déployez un petit service HTTP (Observability fournit une référence fonctionnelle que vous pouvez copier), configurez deux valeurs sur votre serveur, et chaque exécution est ensuite notée automatiquement. Le guide complet, le contrat de scoring et le SDK se trouvent dans le guide approfondi. -Vous ne savez pas quelles dimensions valent la peine d'être scorées ? La [compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) fait travailler votre agent de code pour les déterminer à partir de vos propres sessions, puis construire et déployer le service. +Vous ne savez pas quelles dimensions valent la peine d'être évaluées en premier lieu ? La [compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) permet à votre agent de développement de les déterminer à partir de vos propres sessions, puis de construire et déployer le service. -## Liens connexes +## Voir aussi - [Suite d'évaluation](/fr/agenteye/evaluation-suite) : connecter votre évaluateur, le contrat de scoring et le SDK. -- [Compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) : laissez un agent de code choisir vos dimensions de score et construire l'évaluateur. +- [Compétence d'agent évaluateur](/fr/agenteye/evaluator-skill) : laisser un agent de développement choisir vos dimensions de score et construire l'évaluateur. - [Sessions](/fr/agenteye/sessions) : la grille exécution par exécution où les scores apparaissent. -- [Tableaux de bord](/fr/agenteye/dashboards) : sauvegardez et partagez les tendances de qualité dans votre organisation. +- [Dashboards](/fr/agenteye/dashboards) : enregistrer et partager les tendances qualité dans votre organisation. - [Audits](/fr/agenteye/audits) : l'autre fonctionnalité de qualité automatique d'Observability, pour les investigations inter-sessions. \ No newline at end of file diff --git a/docs/fr/agenteye/evaluator-skill.mdx b/docs/fr/agenteye/evaluator-skill.mdx index 0841bb94..d5364cca 100644 --- a/docs/fr/agenteye/evaluator-skill.mdx +++ b/docs/fr/agenteye/evaluator-skill.mdx @@ -1,26 +1,26 @@ --- -title: "Compétence d'agent évaluateur Failproof AI Observability" -description: "Passez de « je pense que notre agent est parfois mauvais » à un service de scoring déployé, votre agent de codage se chargeant à la fois de la conception et de la construction." +title: "Compétence d'agent évaluateur d'observabilité Failproof AI" +description: "Passez de « je pense que notre agent est parfois mauvais » à un service de scoring déployé, votre agent de code se chargeant à la fois de la conception et de la construction." --- -Passez de *« je pense que notre agent est parfois mauvais »* à un service de scoring déployé, votre agent de codage se chargeant à la fois de la conception et de la construction. La **compétence évaluateur Failproof AI Observability** (`agenteye-evaluator`) est une *Agent Skill* : un petit dossier d'instructions qu'un agent de codage tel que Claude Code ou Codex charge à la demande. Elle apprend à l'agent à déterminer quelles dimensions de qualité méritent d'être suivies pour *votre* agent, puis à écrire, tester et déployer le [service évaluateur](/fr/agenteye/evaluation-suite) qui les note. +Passez de *« je pense que notre agent est parfois mauvais »* à un service de scoring déployé, votre agent de code se chargeant à la fois de la conception et de la construction. La **compétence d'agent évaluateur d'observabilité Failproof AI** (`agenteye-evaluator`) est une *Agent Skill* : un petit dossier d'instructions qu'un agent de code tel que Claude Code ou Codex charge à la demande. Elle apprend à l'agent à déterminer quelles dimensions de qualité valent la peine d'être suivies pour *votre* agent, puis à écrire, tester et déployer le [service évaluateur](/fr/agenteye/evaluation-suite) qui les note. -Il ne s'agit **pas** d'un scoring hébergé, d'un registre vers lequel vous téléversez du contenu, ni d'un système de plugins. Votre évaluateur reste votre propre service HTTP sur votre propre infrastructure, exactement comme décrit dans le guide [Evaluation suite](/fr/agenteye/evaluation-suite). La compétence apprend simplement à votre agent à le construire correctement — tout ce qu'elle fait, vous pourriez le faire vous-même en écrivant le même code. +Il ne s'agit **pas** d'un scorer hébergé, d'un registre vers lequel vous chargez du contenu, ni d'un système de plugins. Votre évaluateur reste votre propre service HTTP sur votre propre infrastructure, exactement comme décrit dans le guide [Evaluation suite](/fr/agenteye/evaluation-suite). La compétence enseigne simplement à votre agent à le construire correctement — tout ce qu'elle fait, vous pourriez le faire vous-même en écrivant le même code. --- -## La partie difficile, c'est de décider quoi noter +## La partie difficile, c'est de décider quoi évaluer -La surface du SDK est réduite — un décorateur et deux modèles — et un agent peut l'écrire à partir du seul [contrat](/fr/agenteye/evaluation-suite#http-contract). Ce n'est pas là que les évaluateurs échouent. Ils échouent parce qu'ils mesurent la mauvaise chose, et un évaluateur qui mesure la mauvaise chose est pire qu'aucun : il produit un tableau de bord que tout le monde apprend à ignorer. +La surface du SDK est réduite — un décorateur et deux modèles — et un agent peut l'écrire à partir du seul [contrat](/fr/agenteye/evaluation-suite#http-contract). Ce n'est pas là que les évaluateurs échouent. Ils échouent parce qu'ils évaluent la mauvaise chose, et un évaluateur qui score la mauvaise chose est pire qu'aucun : il produit un tableau de bord que tout le monde finit par ignorer. -L'essentiel de la compétence concerne donc ce qui précède tout code. Elle fait interviewer l'agent (*« décrivez une exécution qui s'est bien passée ; maintenant une qui s'est mal passée »*), puis lui fait parcourir vos vraies sessions via la [CLI `agenteye`](/fr/agenteye/cli) et les lire de bout en bout. Ces deux sources divergent généralement, et l'écart est justement le point central : ce que vous avez l'intention de mesurer par rapport à ce que vos transcriptions peuvent réellement étayer. Une dimension ne survit que si elle est **calculable** à partir des événements et **discriminante** — si elle donne 0,9 à la fois sur votre bonne exécution et sur la mauvaise, elle n'enseigne rien et est supprimée. +La majeure partie de la compétence concerne donc ce qui se passe avant qu'une seule ligne de code existe. Elle fait interviewer l'agent (*« décrivez une exécution qui s'est bien passée ; maintenant une qui s'est mal passée »*), puis fait passer vos vraies sessions à travers la [`agenteye` CLI](/fr/agenteye/cli) pour les lire de bout en bout. Ces deux sources sont généralement en désaccord, et l'écart est précisément le point central : ce que vous avez l'intention de mesurer par rapport à ce que vos transcriptions peuvent réellement prendre en charge. Une dimension ne survit que si elle est **calculable** à partir des événements et **discriminante** — si elle obtient 0,9 aussi bien sur votre bonne exécution que sur votre mauvaise, elle n'enseigne rien et est éliminée. -Ce qui en ressort est une proposition de 2 à 4 dimensions avec le raisonnement associé, que vous devez valider avant qu'une seule ligne ne soit écrite. +Ce qui en résulte est une proposition de 2 à 4 dimensions avec les raisonnements associés, que vous devez valider avant qu'une ligne soit écrite. ```mermaid flowchart TD - YOU["vous : 'je veux des évals pour mon bot de support'"] --> AGENT["agent de codage (Claude Code / Codex)
charge la compétence agenteye-evaluator"] + YOU["vous : 'Je veux des évals pour mon bot de support'"] --> AGENT["agent de code (Claude Code / Codex)
charge la compétence agenteye-evaluator"] AGENT -->|"interview : à quoi ressemble le bon vs le mauvais ?"| YOU AGENT -->|"agenteye --json sessions / events"| DATA["vos vraies sessions
ce qui se passe réellement"] DATA --> DIMS["2-4 dimensions, vous validez"] @@ -30,46 +30,46 @@ flowchart TD --- -## Relation avec les autres composants d'évaluation +## Relation avec les autres éléments d'évaluation -Quatre pages couvrent le scoring, et se relaient dans l'ordre : +Quatre pages couvrent le scoring et se transmettent le relais dans l'ordre : -| Page | Ce que c'est | À utiliser quand | +| Page | Ce que c'est | Y recourir quand | |---|---|---| | **[Evaluations](/fr/agenteye/evaluations)** | La fonctionnalité : scores sur la grille de sessions, tableaux de bord, réévaluation | Vous voulez savoir ce que le scoring automatique vous apporte | -| **[Evaluation suite](/fr/agenteye/evaluation-suite)** | Le contrat HTTP, le SDK, les variables d'environnement serveur | Vous implémentez ou déboguez vous-même l'évaluateur | -| **Compétence évaluateur** (ce doc) | Une entrée en langage naturel pour concevoir *et* construire le scorer | Vous voulez passer de « je veux des évals » à un service opérationnel | -| **[CLI skill](/fr/agenteye/cli-skill)** | Une entrée en langage naturel sur la CLI `agenteye` | Vous voulez *lire* les scores que vous avez déjà | -| **[Python SDK skill](/fr/agenteye/python-sdk-skill)** | Une entrée en langage naturel pour instrumenter votre agent | Votre agent n'émet pas encore de sessions — il n'y a rien à noter | +| **[Evaluation suite](/fr/agenteye/evaluation-suite)** | Le contrat HTTP, le SDK, les variables d'environnement du serveur | Vous implémentez ou déboguez l'évaluateur vous-même | +| **Compétence évaluateur** (ce doc) | Une porte d'entrée en langage naturel pour concevoir *et* construire le scorer | Vous voulez passer de « je veux des évals » à un service fonctionnel | +| **[CLI skill](/fr/agenteye/cli-skill)** | Une porte d'entrée en langage naturel sur la CLI `agenteye` | Vous voulez *lire* les scores que vous avez déjà | +| **[Python SDK skill](/fr/agenteye/python-sdk-skill)** | Une porte d'entrée en langage naturel pour instrumenter votre agent | Votre agent n'émet pas encore de sessions — il n'y a rien à scorer | -### Par rapport à la CLI skill : construire versus lire +### vs. la compétence CLI : construire vs. lire -Les deux compétences sont délibérément sans chevauchement, et les installer toutes les deux est la configuration habituelle — l'agent choisit entre elles en fonction de ce que vous demandez : +Les deux compétences sont délibérément non redondantes, et installer les deux est la configuration normale — l'agent choisit entre elles en fonction de ce que vous demandez : -- **`agenteye-evaluator`** (ce doc) construit ce qui *produit* les scores. Sa mission se termine quand les scores arrivent pour la première fois. -- **[`agenteye-cli`](/fr/agenteye/cli-skill)** lit les scores déjà existants (`agenteye evals`). *« La qualité a-t-elle baissé cette semaine ? »* est sa question, pas celle de cette compétence. +- **`agenteye-evaluator`** (ce doc) construit ce qui *produit* les scores. Sa mission s'achève quand les scores arrivent pour la première fois. +- **[`agenteye-cli`](/fr/agenteye/cli-skill)** lit les scores qui existent déjà (`agenteye evals`). *« La qualité a-t-elle baissé cette semaine ? »* est sa question, pas celle de cette compétence. --- ## Prérequis -1. **La CLI `agenteye` installée et connectée** (`pipx install agenteye`, puis `agenteye login`). La compétence s'appuie dessus à deux reprises : pour récupérer les vraies sessions sur lesquelles elle se base lors de la conception, et pour confirmer que vos scores sont bien arrivés à la fin. Votre connexion nécessite `events:read`, plus `evaluations:read` pour cette vérification finale. Comme avec la CLI skill, elle **ne peut pas** compléter la connexion par code à usage unique envoyé par e-mail à votre place. -2. **Un endroit où héberger l'évaluateur.** Il est construit dans une image et exécuté en tant que service de longue durée, il a donc besoin d'un vrai dépôt, pas d'un fichier temporaire. Les évaluateurs vivent souvent dans leur propre dépôt, séparé de l'agent évalué — la compétence cherche un dépôt existant et demande avant d'en créer un nouveau. -3. **La roue SDK `agenteye-evaluator`** — lisez la section suivante avant que votre agent commence à taper des commandes `pip`. +1. La **CLI `agenteye` installée et connectée** (`pipx install agenteye`, puis `agenteye login`). La compétence s'appuie dessus à deux reprises : pour récupérer les vraies sessions sur lesquelles elle se base pour concevoir, et pour confirmer que vos scores ont bien atterri à la fin. Votre connexion doit disposer des droits `events:read`, ainsi que `evaluations:read` pour cette vérification finale. Comme pour la compétence CLI, elle **ne peut pas** effectuer à votre place la connexion par code à usage unique envoyé par e-mail. +2. **Un endroit où héberger l'évaluateur.** Il est intégré dans une image et exécuté en tant que service de longue durée, il lui faut donc un vrai dépôt, pas un fichier temporaire. Les évaluateurs vivent souvent dans leur propre dépôt, séparé de l'agent évalué — la compétence cherche s'il en existe un et demande avant d'en créer un nouveau. +3. **Le wheel du SDK `agenteye-evaluator`** — lisez la section suivante avant que votre agent commence à taper des commandes `pip`. --- -## Où l'obtenir +## Où le trouver -La compétence est publiée dans la collection publique de compétences de Failproof AI : +La compétence est publiée dans la collection de compétences publiques de Failproof AI : **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -Le dépôt est public et la compétence n'a pas besoin de ses propres identifiants — elle pilote uniquement la CLI `agenteye` avec la session *sur laquelle vous êtes connecté*, et écrit du code dans *votre* dépôt. Notez qu'elle est livrée dans son propre dossier et n'est **pas** incluse dans le package `pipx install agenteye`, donc ne la cherchez pas là. +Le dépôt est public et la compétence n'a besoin d'aucune credential propre — elle pilote uniquement la CLI `agenteye` avec la session *avec laquelle vous* êtes connecté, et écrit du code dans *votre* dépôt. Notez qu'elle est livrée comme son propre dossier et **n'est pas** incluse dans le package `pipx install agenteye`, donc ne la cherchez pas là. ## Installer la compétence -Le chemin le plus rapide passe par la CLI [`skills`](https://skills.sh), qui récupère le dossier et le place là où votre agent le cherche : +Le chemin le plus rapide est la CLI [`skills`](https://skills.sh), qui récupère le dossier et le dépose là où votre agent le cherche : ```bash # Claude Code, ce projet uniquement @@ -82,7 +82,7 @@ npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g - npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -Puis gérez-la comme n'importe quelle autre compétence : +Gérez-la ensuite comme n'importe quelle autre compétence : ```bash npx skills list -a claude-code # ce qui est installé @@ -90,22 +90,22 @@ npx skills update agenteye-evaluator # récupérer la dernière version npx skills remove agenteye-evaluator # la supprimer ``` -Vous préférez installer manuellement ? Une Agent Skill est juste un dossier contenant un `SKILL.md` (plus des références optionnelles), donc la copier fonctionne aussi : +Vous préférez installer manuellement ? Une Agent Skill n'est qu'un dossier contenant un `SKILL.md` (plus des références optionnelles), donc la copier fonctionne aussi : - **Claude Code** : placez le dossier `agenteye-evaluator/` dans `~/.claude/skills/` (tous les projets) ou `/.claude/skills/` (ce dépôt uniquement). Claude Code le découvre automatiquement — vérifiez avec la liste `/skills`, ou demandez simplement des évals. -- **Codex (OpenAI)** : Codex lit le même `SKILL.md`. Le fichier `agents/openai.yaml` fourni définit `allow_implicit_invocation: true`, donc Codex sélectionne automatiquement la compétence quand une tâche correspond ; sinon invoquez-la explicitement avec `$agenteye-evaluator`. +- **Codex (OpenAI)** : Codex lit le même `SKILL.md`. Le fichier `agents/openai.yaml` fourni définit `allow_implicit_invocation: true`, donc Codex sélectionne automatiquement la compétence quand une tâche correspond ; sinon, invoquez-la explicitement avec `$agenteye-evaluator`. --- ## Le SDK n'est pas sur PyPI public -> **Avertissement :** Lisez ceci avant de laisser un agent installer le SDK. +> **Attention :** Lisez ceci avant de laisser un agent installer le SDK. -La compétence est publique ; le SDK qu'elle pilote ne l'est pas. `agenteye-evaluator` est livré uniquement comme artefact de version privée, et contrairement à `agenteye`, le nom est **non revendiqué sur PyPI public** — donc un simple `pip install agenteye-evaluator` pourrait installer le package d'un inconnu dans le service qui lit vos transcriptions de production. C'est un problème de chaîne d'approvisionnement, pas une faute de frappe. +La compétence est publique ; le SDK qu'elle pilote ne l'est pas. `agenteye-evaluator` est fourni uniquement comme artefact de version privé, et contrairement à `agenteye`, le nom est **non revendiqué sur PyPI public** — ainsi un simple `pip install agenteye-evaluator` pourrait injecter le package d'un inconnu dans le service qui lit vos transcriptions de production. C'est un problème de chaîne d'approvisionnement, pas une faute de frappe. -La compétence le sait et parcourt à la place une liste d'installation par priorité, s'arrêtant à la première qui s'applique : la source du monodépôt si vous êtes dans le dépôt AgentEye, sinon la roue de version privée depuis GitHub Releases (nécessite un accès), et si aucune n'est accessible, elle **s'arrête et vous indique de demander la roue à votre contact Failproof AI** plutôt que d'improviser. +La compétence le sait et utilise à la place une échelle d'installation, s'arrêtant au premier échelon applicable : la source du monorepo si vous êtes à l'intérieur du dépôt AgentEye, sinon le wheel de version privée depuis GitHub Releases (accès requis), et si aucun n'est accessible elle **s'arrête et vous dit de demander le wheel à votre contact Failproof AI** plutôt que d'improviser. -Donc si votre agent propose un simple `pip install agenteye-evaluator` depuis PyPI public, c'est le signe que la compétence n'a jamais été chargée. Arrêtez-vous et vérifiez qu'elle est bien installée. +Donc si votre agent propose un simple `pip install agenteye-evaluator` depuis PyPI public, c'est le signe que la compétence n'a jamais été chargée. Arrêtez-vous là et vérifiez qu'elle est bien installée. --- @@ -114,54 +114,54 @@ Donc si votre agent propose un simple `pip install agenteye-evaluator` depuis Py Un vrai aller-retour commence par une demande vague et se termine par une conception validée, pas par du code : ```text -vous ▸ Je veux des évals pour notre bot de support. Je pense qu'il est parfois mauvais. +vous ▸ Je veux des évals pour notre bot de support. Je pense qu'il est parfois mauvais. -agent ▸ Avant d'écrire quoi que ce soit : décrivez une exécution qui s'est bien - passée, et une qui s'est mal passée. +agent ▸ Avant d'écrire quoi que ce soit : décrivez une exécution qui s'est bien passée, + et une qui s'est mal passée. -vous ▸ Bien : il répond à partir de la documentation. Mal : il invente des choses, - ou abandonne et dit « contactez le support ». +vous ▸ Bien : il répond à partir de la documentation. Mal : il invente des choses, + ou abandonne en disant « contactez le support ». -agent ▸ Exécution : agenteye --json sessions --status error --since 7d - Lecture de 5 sessions, dont deux que vous qualifieriez de mauvaises. +agent ▸ Exécution : agenteye --json sessions --status error --since 7d + Lecture de 5 sessions, dont deux que vous qualifieriez de mauvaises. - Vos mots évoquent la factualité et le décrochage. Les transcriptions - confirment le décrochage (2 sur 5 se terminent par un transfert au support, - clairement visible dans model_response.content), mais la factualité - nécessite une vérité terrain que vos événements ne contiennent pas. + Vos mots évoquent la factualité et la dérobade. Les transcriptions + confirment la dérobade (2 sur 5 se terminent par un transfert au support, + clairement visible dans model_response.content), mais la factualité + nécessite une vérité terrain que vos événements ne contiennent pas. - Je mesurerais donc trois choses : - - deflection règles, peu coûteux, distingue vos deux exécutions - - tool_efficiency règles, détecte la boucle de réessai dans run-004 - - groundedness juge LLM : chaque affirmation est-elle dans les docs récupérés ? + Je scorerais donc trois choses : + - deflection règles, peu coûteux, sépare vos deux exécutions + - tool_efficiency règles, détecte la boucle de réessai dans run-004 + - groundedness juge LLM : chaque affirmation est-elle dans les docs récupérés ? - « factualité » nécessiterait une vérité terrain que nous n'avons pas ; - groundedness est ce que vos transcriptions peuvent réellement étayer. - D'accord avec ces trois noms ? Les renommer plus tard divise l'historique. + « factuality » nécessiterait une vérité terrain que nous n'avons pas ; groundedness + est ce qui se rapproche le plus de ce que vos transcriptions peuvent réellement prendre en charge. + D'accord avec ces trois noms ? Les renommer plus tard divise l'historique. -vous ▸ oui +vous ▸ oui -agent ▸ Pas d'évaluateur dans ce dépôt. Dois-je en créer un ici, ou en avez-vous - un ailleurs ? +agent ▸ Pas d'évaluateur dans ce dépôt. Dois-je en créer un ici, ou en avez-vous + un ailleurs ? ``` -À partir de là, il écrit d'abord les dimensions basées sur des règles (gratuites, instantanées, déterministes), les teste contre une vraie session capturée incluant les sessions vides et inachevées qui font planter les évaluateurs naïfs, et n'utilise un juge LLM que pour la dimension subjective. Il connaît les [limites du dispatcher](/fr/agenteye/evaluation-suite#configuring-the-server) — un délai de requête de 30s et 8 appels simultanés dans tout le déploiement — donc si le juge ne s'y adapte pas de manière fiable, il passe en asynchrone avec `JobPending` plutôt que de laisser votre juge être annulé et réessayé cinq fois au quintuple du coût. +À partir de là, il écrit d'abord les dimensions basées sur des règles (gratuites, instantanées, déterministes), les teste contre une vraie session capturée — y compris les sessions vides et jamais terminées qui font planter les évaluateurs naïfs — et ne fait appel à un juge LLM que pour la dimension subjective. Il connaît les [limites du dispatcher](/fr/agenteye/evaluation-suite#configuring-the-server) — un timeout de requête de 30s et 8 appels concurrents à l'échelle du déploiement — donc si le juge ne rentre pas de façon fiable dans ce délai, il passe en asynchrone avec `JobPending` plutôt que de laisser votre juge être annulé et réessayé cinq fois pour cinq fois le coût. -Ensuite il déploie, définit les deux variables d'environnement serveur, et confirme avec `agenteye --json evals --session-id ` que les scores sont bien arrivés. L'arrivée des scores est la seule preuve. +Ensuite il déploie, configure les deux variables d'environnement du serveur, et confirme avec `agenteye --json evals --session-id ` que les scores ont bien atterri. L'arrivée des scores est la seule preuve. --- -## Ce à quoi faire attention +## Points de vigilance -- **Les noms de dimensions sont quasi permanents.** Les clés de score sont des chaînes arbitraires et la plateforme suit les tendances de tout ce que vous envoyez, ce qui signifie que rien en aval ne corrige un mauvais choix. Renommer plus tard divise l'historique : les anciennes sessions conservent l'ancienne clé et la tendance se brise. C'est pourquoi la compétence obtient une validation explicite avant d'écrire du code — prenez cette invite au sérieux. -- **Les fixtures sont de vraies transcriptions de production.** Concevoir à partir de vraies sessions signifie les télécharger sur le disque, et elles peuvent contenir des données clients. La compétence demande avant de les committer dans git ; en cas de doute, gardez `fixtures/` hors du dépôt et faites récupérer les siennes à chaque développeur. +- **Les noms de dimensions sont quasi permanents.** Les clés de score sont des chaînes arbitraires et la plateforme suit les tendances de tout ce que vous envoyez, ce qui signifie que rien en aval ne corrige un mauvais choix. Renommez plus tard et l'historique se divise : les anciennes sessions conservent l'ancienne clé et la tendance se brise. C'est pourquoi la compétence obtient une validation explicite avant d'écrire du code — prenez cette étape au sérieux. +- **Les fixtures sont de vraies transcriptions de production.** Concevoir à partir de vraies sessions implique de les télécharger sur disque, et elles peuvent contenir des données client. La compétence demande avant de les committer dans git ; en cas de doute, gardez `fixtures/` hors du dépôt et faites en sorte que chaque développeur récupère les siennes. - **L'agent écrit et déploie un service qui lit chaque transcription.** Il agit en votre nom, limité par les permissions de votre connexion CLI, mais examinez l'évaluateur comme n'importe quel autre code qui touche des données de production. --- ## Prochaines étapes -- **[Evaluation suite](/fr/agenteye/evaluation-suite)** : le contrat HTTP, le SDK et les variables d'environnement serveur que la compétence configure. -- **[Evaluations](/fr/agenteye/evaluations)** : là où les scores s'affichent une fois qu'ils arrivent. -- **[CLI skill](/fr/agenteye/cli-skill)** : la compétence jumelle, pour lire les résultats plutôt que construire le scorer. +- **[Evaluation suite](/fr/agenteye/evaluation-suite)** : le contrat HTTP, le SDK, et les variables d'environnement du serveur que la compétence configure. +- **[Evaluations](/fr/agenteye/evaluations)** : là où les scores apparaissent une fois qu'ils arrivent. +- **[CLI skill](/fr/agenteye/cli-skill)** : la compétence complémentaire, pour lire les résultats plutôt que construire le scorer. - **[CLI](/fr/agenteye/cli)** : la référence des commandes derrière les données de session sur lesquelles la compétence se base. \ No newline at end of file diff --git a/docs/fr/agenteye/event-stream.mdx b/docs/fr/agenteye/event-stream.mdx index 6cfe42ef..22eba713 100644 --- a/docs/fr/agenteye/event-stream.mdx +++ b/docs/fr/agenteye/event-stream.mdx @@ -1,45 +1,45 @@ --- title: "Flux d'événements" -description: "Au moment où votre agent agit, vous le voyez." +description: "Dès que votre agent fait quelque chose, vous le voyez." --- -Au moment où votre agent agit, vous le voyez. Le flux d'événements est votre pouls en direct sur chaque agent en production : pas d'attente, pas de recherche dans les logs, pas de devinettes sur ce qui vient de se passer. +Dès que votre agent fait quelque chose, vous le voyez. Le flux d'événements est votre pouls en temps réel sur chaque agent en production : plus d'attente, plus de grep dans les logs, plus de doutes sur ce qui vient de se passer. -![Le flux d'événements en direct : lignes d'événements colorées défilant en temps réel, filtrables par environnement, agent, session, type d'événement et texte libre](/agenteye/images/events-stream.png) +![Le flux d'événements en direct : lignes d'événements codées par couleur se défilant en temps réel, filtrables par environnement, agent, session, type d'événement et texte libre](/agenteye/images/events-stream.png) -*Chaque événement de chaque agent de votre organisation, du plus récent au plus ancien, mis à jour au fil de l'eau.* +*Chaque événement de chaque agent de votre organisation, du plus récent au plus ancien, mis à jour en temps réel.* -## Votre pouls en direct sur chaque agent +## Votre pouls en temps réel sur chaque agent -Quand un agent démarre une exécution, appelle un modèle, déclenche un outil, exécute un hook ou rencontre une erreur, la ligne apparaît en haut du flux au moment même où cela se produit. Il suit en continu tous les événements de tous vos agents, du plus récent au plus ancien, ce qui vous donne toujours une image actuelle plutôt qu'une image périmée. +Lorsqu'un agent démarre une exécution, appelle un modèle, déclenche un outil, exécute un hook ou rencontre une erreur, la ligne apparaît en haut du flux au moment même où cela se produit. Il suit en continu chaque événement de chaque agent de votre organisation, du plus récent au plus ancien, ce qui vous donne toujours une image actuelle plutôt qu'une image périmée. -Cela signifie plus besoin de surveiller des fichiers de logs sur un serveur quelque part, ni de fouiller plusieurs machines, ni d'assembler manuellement des horodatages. Vous ouvrez une seule page et vous regardez déjà la production. +Cela signifie qu'il n'est plus nécessaire de parcourir des fichiers de logs sur un serveur quelconque, de faire des grep sur plusieurs machines ou d'assembler manuellement des horodatages. Vous ouvrez une seule page et vous observez déjà la production. -Les lignes sont colorées par type, ce qui vous permet de lire le flux d'un coup d'œil plutôt que d'analyser chaque ligne. En un clin d'œil, chaque ligne vous montre : +Les lignes sont codées par couleur selon leur type, ce qui vous permet de lire le flux en un coup d'œil sans avoir à analyser chaque ligne. En un regard, chaque ligne vous indique : - **Son type**, codé par couleur : `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, et bien d'autres. -- **Un résumé en une ligne** de ce qui s'est passé, ce qui vous évite souvent d'ouvrir quoi que ce soit pour comprendre l'essentiel. -- **Le nombre de tokens** pour l'étape. -- **Un indicateur de remplissage de la fenêtre de contexte** lorsqu'il s'applique, rendant visible la croissance du prompt et l'approche d'une compaction avant qu'elles ne posent problème. +- **Un résumé en une ligne** de ce qui s'est passé, de sorte que vous avez rarement besoin d'ouvrir quoi que ce soit pour comprendre l'essentiel. +- **Le nombre de tokens** pour l'étape concernée. +- **Un indicateur de remplissage de la fenêtre de contexte** le cas échéant, afin que la croissance du prompt et l'approche d'une compaction soient visibles avant de causer des problèmes. -Surveiller le flux en direct signifie que vous détectez un mauvais déploiement, une boucle incontrôlée ou une rafale d'erreurs au moment où cela se produit, pas lors de la revue des logs du lendemain. +Observer le flux en direct vous permet de détecter un déploiement défaillant, une boucle incontrôlée ou une rafale d'erreurs au moment même où cela se produit, et non lors de la revue des logs du lendemain. -## Trouver l'unique exécution qui pose problème +## Trouver l'exécution qui pose problème -Quand quelque chose semble anormal, vous ne voulez pas le flot d'informations complet. Vous voulez l'unique exécution qui a planté. Le flux se filtre rapidement : par environnement, par agent, par session, par type d'événement ou par texte libre. +Quand quelque chose semble anormal, vous n'avez pas besoin du flux complet. Vous voulez l'exécution précise qui a échoué. Le flux se filtre rapidement : par environnement, par agent, par session, par type d'événement ou par texte libre. -Filtrez par identifiant de session ou d'agent pour suivre une exécution depuis son premier événement jusqu'au dernier. Filtrez par type d'événement pour isoler une seule catégorie d'activité, par exemple tous les `error` de l'organisation en une seule vue. Combinez des filtres pour passer de « tout, partout » à « cet agent, en prod, en erreur » en quelques clics, puis agissez sur ce que vous trouvez. +Filtrez par identifiant de session ou par identifiant d'agent pour suivre une exécution depuis son premier événement jusqu'au dernier. Filtrez par type d'événement pour isoler un seul type d'activité — par exemple, toutes les `error` de l'organisation en une seule vue. Combinez les filtres pour passer de « tout, partout » à « cet agent, en prod, avec des erreurs » en quelques clics, puis agissez sur ce que vous trouvez. -La recherche en texte libre vous amène directement à un message, un nom d'outil ou un identifiant que vous avez déjà sous la main, transformant un signalement client en exécution précise en quelques secondes. +La recherche en texte libre vous amène directement à un message, un nom d'outil ou un identifiant que vous avez déjà sous la main, transformant ainsi un signalement client en exécution exacte en quelques secondes. ## Où le trouver Le flux d'événements est la page d'accueil de votre organisation. Connectez-vous et c'est la première surface sur laquelle vous atterrissez, à `//`, de sorte que le triage commence dès votre arrivée. -En coulisse, vos agents émettent des événements via le SDK, le collecteur les achemine vers votre serveur d'observabilité Failproof AI, et le flux les suit à mesure qu'ils arrivent dans une infrastructure que vous contrôlez. Quand vous voulez la vue consolidée plutôt que la trace brute, les événements de chaque exécution se regroupent en une seule ligne dans Sessions, à un clic de là. +En coulisses, vos agents émettent des événements via le SDK, le collecteur les achemine vers votre serveur d'observabilité Failproof AI, et le flux les suit au fur et à mesure de leur arrivée dans une infrastructure que vous contrôlez. Lorsque vous souhaitez une vue agrégée plutôt que la trace brute, les événements de chaque exécution se regroupent en une seule ligne dans Sessions, accessible en un clic. -C'est la source de vérité brute sur laquelle s'appuient toutes les autres surfaces d'observation. Donc, quand un chiffre semble erroné ailleurs, le flux est l'endroit où vous confirmez ce qui s'est réellement passé. +C'est la source de vérité brute sur laquelle repose chaque autre surface d'observation. Ainsi, lorsqu'un chiffre semble incorrect ailleurs, le flux est l'endroit où vous confirmez ce qui s'est réellement passé. ## Voir aussi diff --git a/docs/fr/agenteye/hermes-capture.mdx b/docs/fr/agenteye/hermes-capture.mdx index 7a8cc9f4..f1aadaa7 100644 --- a/docs/fr/agenteye/hermes-capture.mdx +++ b/docs/fr/agenteye/hermes-capture.mdx @@ -1,34 +1,34 @@ --- title: "Capture de sessions Hermes" -description: "Intégrez les sessions de votre passerelle Hermes — Slack, Telegram, CLI et exécutions planifiées — dans AgentEye sous forme de sessions et d'événements ordinaires." +description: "Intégrez les sessions de votre passerelle Hermes — Slack, Telegram, CLI et exécutions planifiées — dans AgentEye comme des sessions et événements ordinaires." --- -[Hermes](https://hermes-agent.nousresearch.com) répond à votre équipe depuis n'importe quel outil de travail — Slack, Telegram, la CLI, des exécutions planifiées. La capture de sessions Hermes intègre l'ensemble de ces interactions dans AgentEye sous forme de sessions et d'événements ordinaires, afin que l'assistant que votre équipe utilise au quotidien soit aussi observable que les agents que vous développez vous-même. +[Hermes](https://hermes-agent.nousresearch.com) répond à votre équipe depuis n'importe quel canal qu'elle utilise déjà — Slack, Telegram, la CLI, les exécutions planifiées. La capture de sessions Hermes intègre l'ensemble dans AgentEye sous forme de sessions et d'événements ordinaires, de sorte que l'assistant que votre équipe utilise au quotidien est aussi observable que les agents que vous écrivez vous-mêmes. -Un petit collecteur en arrière-plan lit le dépôt de sessions local de Hermes au fur et à mesure de son écriture, puis transmet les sessions à AgentEye. Son fonctionnement est identique à celui des captures [Codex](/fr/agenteye/codex-capture) et [OpenClaw](/fr/agenteye/openclaw-capture), et un seul collecteur peut en capturer plusieurs simultanément. +Un petit collecteur en arrière-plan lit le magasin de sessions local de Hermes au fur et à mesure de son écriture, puis envoie les sessions vers AgentEye. Son fonctionnement est identique à celui des captures [Codex](/fr/agenteye/codex-capture) et [OpenClaw](/fr/agenteye/openclaw-capture), et un seul collecteur peut en capturer plusieurs simultanément. --- ## Ce qui est capturé -Toutes les sessions Hermes présentes sur la machine sont capturées, quel que soit le canal d'origine. Chacune devient une [session](/fr/agenteye/sessions) AgentEye ; ses messages utilisateur et assistant, ses appels d'outils et leurs résultats deviennent les [événements](/fr/agenteye/event-stream) correspondants. +Toutes les sessions Hermes présentes sur la machine sont capturées, quel que soit le canal dont elles proviennent. Chacune devient une [session](/fr/agenteye/sessions) AgentEye ; ses messages utilisateur et assistant, ses appels d'outils et leurs résultats deviennent les [événements](/fr/agenteye/event-stream) correspondants. -Le canal depuis lequel une session a démarré — Slack, Telegram, CLI ou une exécution planifiée — est enregistré sur la session, ce qui vous permet de les distinguer et de filtrer sur un seul canal à la fois. Sont également consignés : le modèle utilisé par la session, le chat et la personne à l'origine de son démarrage, ainsi que, lorsqu'une session en a engendré une autre, le lien vers sa session parente. +Le canal depuis lequel une session a démarré — Slack, Telegram, CLI ou une exécution planifiée — est enregistré sur la session, ce qui permet de les distinguer et de filtrer sur l'un d'eux à la fois. S'y ajoutent le modèle utilisé, le chat et la personne depuis lesquels la session a été lancée, et, lorsqu'une session en a engendré une autre, le lien vers sa session parente. -Les sessions apparaissent dès que Hermes les démarre, qu'un message ait été échangé ou non, et la réponse d'un tour ainsi que ses appels d'outils sont conservés dans l'ordre réel des événements. Lorsqu'une session se termine, vous obtenez également la raison de sa fin, son coût et le nombre de tokens consommés. +Les sessions apparaissent dès que Hermes les démarre, qu'il y ait eu des échanges ou non, et la réponse d'un tour ainsi que ses appels d'outils sont conservés dans l'ordre où ils se sont réellement produits. Lorsqu'une session se termine, vous obtenez également la raison de cette fin, son coût et le nombre de tokens consommés. --- ## Activation -La capture est désactivée par défaut. Installez le collecteur avec une clé API disposant de la permission `events:add` (voir [Clés API](/fr/agenteye/api-keys)), puis activez la capture Hermes : +La capture est désactivée jusqu'à ce que vous l'activiez. Installez le collecteur avec une clé API disposant de la permission `events:add` (voir [Clés API](/fr/agenteye/api-keys)), puis activez la capture Hermes : ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -Cette commande installe le collecteur, l'enregistre en tant que service en arrière-plan et lance la capture. Pour vérifier qu'il est en cours d'exécution : +Cette commande installe le collecteur, l'enregistre en tant que service en arrière-plan et démarre la capture. Pour vérifier qu'il est bien en cours d'exécution : ```bash agenteye-collector health @@ -36,18 +36,18 @@ agenteye-collector health Vous capturez plusieurs agents sur la même machine ? Ajoutez le flag de chacun à la même commande — par exemple `--hermes-enabled --codex-enabled`. -Au premier lancement, vos sessions Hermes existantes sont importées rétroactivement en une seule fois, puis la nouvelle activité est transmise en quelques secondes. Les données de Hermes sont uniquement lues — jamais modifiées ni supprimées — et chaque message est transmis une seule fois, même après des redémarrages. +Au premier lancement, vos sessions Hermes existantes sont importées rétroactivement en une seule fois, puis la nouvelle activité est transmise en quelques secondes. Les données de Hermes sont uniquement lues — jamais modifiées ni supprimées — et chaque message n'est envoyé qu'une seule fois, même après des redémarrages. -`health` vous indique également si tout ce que le collecteur a capturé a bien atteint AgentEye. Si un lot n'a pas pu être livré, il est conservé et réessayé plutôt que supprimé, et la vérification signale un état non sain tant que des données sont encore en attente — ainsi, « sain » signifie que vos données sont bien arrivées, et pas seulement que le processus est en vie. +`health` vous indique également si tout ce que le collecteur a capturé est bien parvenu à AgentEye. Si un lot n'a pas pu être transmis, il est conservé et réessayé plutôt que supprimé, et la vérification signale un état défectueux tant que des données sont en attente — ainsi, « sain » signifie que vos données sont bien arrivées, et pas seulement que le processus est actif. --- ## Où les retrouver -Les sessions capturées apparaissent dans **Sessions**, et leurs événements dans le flux **Events**, comme pour tout autre agent observé — ainsi, la [relecture de session](/fr/agenteye/sessions), la [recherche](/fr/agenteye/queries), les [évaluations](/fr/agenteye/evaluations) et les [alertes](/fr/agenteye/alerts) fonctionnent toutes sur ces données. Filtrez par l'agent Hermes pour les visualiser de manière isolée. +Les sessions capturées apparaissent dans **Sessions**, et leurs événements dans le flux **Events**, exactement comme pour tout autre agent observé — ainsi, la [relecture de session](/fr/agenteye/sessions), la [recherche](/fr/agenteye/queries), les [évaluations](/fr/agenteye/evaluations) et les [alertes](/fr/agenteye/alerts) fonctionnent toutes avec elles. Filtrez par l'agent Hermes pour les afficher séparément. --- ## Confidentialité -Les sessions Hermes contiennent la transcription complète — y compris les sorties de commandes, le contenu des fichiers et tout ce que l'agent a lu ou écrit — et peuvent contenir des secrets. Les sessions capturées sont transmises telles quelles ; n'activez donc la capture que dans les contextes où la centralisation de ce contenu dans AgentEye est appropriée, et donnez au collecteur une clé limitée à la seule permission `events:add`. Consultez [Sécurité](/fr/agenteye/security) pour en savoir plus sur l'isolation de vos données. \ No newline at end of file +Les sessions Hermes contiennent la transcription complète — notamment la sortie des commandes, le contenu des fichiers et tout ce que l'agent a lu ou écrit — et peuvent contenir des secrets. Les sessions capturées sont transmises telles quelles ; n'activez donc la capture que là où la centralisation de ce contenu dans AgentEye est appropriée, et attribuez au collecteur une clé limitée à `events:add` uniquement. Consultez [Sécurité](/fr/agenteye/security) pour en savoir plus sur l'isolation de vos données. \ No newline at end of file diff --git a/docs/fr/agenteye/incidents.mdx b/docs/fr/agenteye/incidents.mdx index e85743fa..d0c3cb69 100644 --- a/docs/fr/agenteye/incidents.mdx +++ b/docs/fr/agenteye/incidents.mdx @@ -1,26 +1,26 @@ --- title: "Incidents" -description: "Dès qu'une alerte se déclenche, chacun peut voir que l'incident est ouvert, qui en est responsable, et ce qui s'est passé jusqu'ici — sur une seule chronologie attribuée." +description: "Lorsqu'une alerte se déclenche, tout le monde peut voir que l'incident est ouvert, qui en est responsable et ce qui s'est passé jusqu'ici — sur une timeline attribuée et unifiée." --- -Dès qu'une alerte se déclenche, la première question est toujours « qui s'en occupe ? » Les incidents y répondent : à l'instant où un seuil est franchi, tout le monde peut voir que l'incident est ouvert, qui en est propriétaire, et exactement ce qui s'est passé jusqu'ici, avec un historique propre et attribué que vous pouvez transmettre directement à un post-mortem. +Lorsqu'une alerte se déclenche, la première question est toujours « qui s'en occupe ? » Les incidents y répondent : dès qu'un seuil est franchi, tout le monde peut voir que l'incident est ouvert, qui en est responsable, et exactement ce qui s'est passé jusqu'ici, avec un historique clair et attribué que vous pouvez transmettre directement à un post-mortem. -![La boîte de réception des incidents : cartes d'incidents liés à des alertes et ouverts manuellement, regroupées par état, chacune avec un badge de sévérité et un assigné](/agenteye/images/incidents.png) -*La boîte de réception regroupe les incidents ouverts par état et permet de filtrer par sévérité et par assigné, afin que vous voyiez immédiatement ce qui nécessite une intervention humaine.* +![La vue des incidents : cartes d'incidents liées à des alertes ou ouverts manuellement, regroupées par état, chacune avec un badge de sévérité et un responsable assigné](/agenteye/images/incidents.png) +*La boîte de réception regroupe les incidents ouverts par état et permet de filtrer par sévérité et par responsable, pour que vous voyiez ce qui nécessite une intervention humaine immédiatement.* -## Savoir qui s'en occupe, d'un coup d'œil +## Savoir qui s'en charge, d'un coup d'œil -Fini les « est-ce que quelqu'un regarde ça ? » dans un fil de discussion. Un dépassement ouvre automatiquement un incident et le dépose dans une boîte de réception partagée, regroupée par état. Acquittez-le et votre nom y est affiché, signalant au reste de l'équipe que c'est pris en charge. L'acquittement est partagé : plusieurs opérateurs peuvent acquitter le même incident, chacun étant enregistré séparément, de sorte qu'une salle de crise entière s'affiche par nom sans que les uns n'écrasent les autres. Assignez un seul propriétaire pour le triage, et filtrez la boîte de réception par sévérité ou par assigné pour n'afficher que ce qui vous concerne. +Fini les « est-ce que quelqu'un regarde ça ? » dans un fil de discussion. Un dépassement de seuil ouvre automatiquement un incident et le dépose dans une boîte de réception partagée, regroupée par état. Accusez-en réception et votre nom y apparaît, signalant au reste de l'équipe que c'est pris en charge. L'accusé de réception est partagé : plusieurs opérateurs peuvent acquitter le même incident, chacun étant enregistré indépendamment, ce qui permet à toute une cellule de crise d'apparaître nominativement sans se marcher dessus. Assignez un seul responsable pour le triage, et filtrez la boîte de réception par sévérité ou par assigné pour ne garder que ce qui vous appartient. -## Toute l'histoire, sur une seule chronologie +## Toute l'histoire, sur une seule timeline -Quand l'incident est terminé, le compte rendu est déjà prêt. Ouvrez n'importe quel incident et vous obtenez les preuves du dépassement, ses assignés et abonnés, un fil de commentaires pour coordonner sur place, et une chronologie d'activité en ajout seul. +Une fois l'incident terminé, votre compte-rendu est déjà prêt. Ouvrez n'importe quel incident et vous trouvez les preuves du dépassement, les assignés et abonnés, un fil de commentaires pour coordonner sur place, et une timeline d'activité en ajout seul. -![Une vue détaillée d'un incident : l'alerte parente et le résumé du dépassement, les assignés et abonnés, une chronologie d'activité attribuée, et un fil de commentaires](/agenteye/images/incident-detail.png) -*Tout ce qui s'est passé, dans l'ordre, chaque ligne signée par celui qui l'a effectuée.* +![Vue détaillée d'un incident : l'alerte parente et le résumé du dépassement, les assignés et abonnés, une timeline d'activité attribuée, et un fil de commentaires](/agenteye/images/incident-detail.png) +*Tout ce qui s'est passé, dans l'ordre, chaque ligne signée par son auteur.* -Chaque action (ouverture, acquittement, résolution, etc.) est écrite dans cette chronologie et n'est jamais modifiée. Chaque entrée est attribuée : à l'opérateur qui l'a effectuée, par e-mail, ou à **automated** pour tout ce que Failproof AI Observability a fait de manière autonome, comme l'ouverture de l'incident lors du dépassement. Rien n'est anonyme et rien n'est perdu, si bien que le post-mortem s'écrit en grande partie tout seul. +Chaque action (ouverture, accusé de réception, résolution, etc.) est écrite dans cette timeline et ne peut jamais être modifiée ou supprimée. Chaque entrée est attribuée : à l'opérateur qui l'a effectuée, par e-mail, ou à **automated** pour tout ce que Failproof AI Observability a fait automatiquement, comme l'ouverture de l'incident lors du dépassement. Rien n'est anonyme et rien n'est perdu, ce qui permet au post-mortem de pratiquement s'écrire tout seul. ## Comment un incident évolue @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **Ouvert (firing) :** le dépassement ouvre l'incident et notifie vos canaux une seule fois. Les dépassements répétés sont regroupés dans le même incident et actualisent ses preuves au lieu de vous notifier encore et encore. -- **Acquitté (acknowledged) :** un opérateur le prend en charge. Il reste ouvert, et les dépassements ultérieurs mettent à jour les preuves discrètement. -- **Résolu (resolved) :** un opérateur le clôture. La résolution automatique lorsque la condition se dissipe est prévue mais pas encore activée, donc un incident reste ouvert jusqu'à ce qu'un humain le résolve — ce qui garantit une vision honnête de ce qui a réellement été réglé. Un nouvel incident peut s'ouvrir sur la même alerte ultérieurement. +- **Ouvert (firing) :** le dépassement ouvre l'incident et notifie vos canaux une seule fois. Les dépassements successifs se fondent dans le même incident et actualisent ses preuves au lieu de vous notifier encore et encore. +- **Acquitté (acknowledged) :** un opérateur prend l'incident en charge. Il reste ouvert, et les dépassements ultérieurs mettent à jour les preuves discrètement. +- **Résolu (resolved) :** un opérateur le clôture. La résolution automatique lorsque la condition se rétablit est prévue mais pas encore activée ; un incident reste donc ouvert jusqu'à ce qu'un humain le résolve, ce qui garantit une vérité partagée sur ce qui est réellement rétabli. Un nouvel incident peut s'ouvrir sur la même alerte par la suite. -Une alerte ne peut contenir qu'un seul incident ouvert à la fois, de sorte qu'une règle instable ne peut pas vous noyer sous des doublons. Vous pouvez également ouvrir un incident manuellement : un incident autonome pour quelque chose qu'aucune alerte n'a détecté, ou un incident rattaché à une alerte existante, si vous disposez de `incidents:write`. +Une alerte ne peut détenir qu'un seul incident ouvert à la fois, de sorte qu'une règle instable ne peut pas vous noyer sous les doublons. Vous pouvez également ouvrir un incident manuellement : un incident autonome pour quelque chose qu'aucune alerte n'a détecté, ou un incident attaché à une alerte existante, si vous disposez de `incidents:write`. ## Où le trouver -Les incidents se trouvent à `//incidents`. La consultation nécessite **`incidents:read`** ; l'ouverture d'un incident manuel nécessite **`incidents:write`** ; l'acquittement, l'assignation, les commentaires et la résolution nécessitent **`incidents:ack`**. Les anciennes clés ayant accordé le droit `alerts:ack` retraité continuent de fonctionner, car il est honoré en tant que `incidents:ack`, de sorte que votre rotation d'astreinte n'a pas besoin d'être réémise. +Les incidents se trouvent à `//incidents`. La consultation nécessite **`incidents:read`** ; l'ouverture d'un incident manuel nécessite **`incidents:write`** ; l'accusé de réception, l'assignation, les commentaires et la résolution nécessitent **`incidents:ack`**. Les anciennes clés ayant accordé le rôle retraité `alerts:ack` continuent de fonctionner, car il est reconnu comme `incidents:ack`, de sorte que votre rotation d'astreinte n'a pas besoin d'être reconfigurée. ## Voir aussi - [Alertes](/fr/agenteye/alerts) : les règles qui ouvrent ces incidents lorsqu'un seuil est franchi. -- [Suivi des erreurs](/fr/agenteye/error-tracking) : consultez tous les échecs en un seul endroit et promouvez-en un en alerte. -- [Audits](/fr/agenteye/audits) : l'analyste planifié qui détecte les défaillances qu'aucune règle ne surveillait. \ No newline at end of file +- [Suivi des erreurs](/fr/agenteye/error-tracking) : visualisez tous les échecs en un seul endroit et promouvez-en un en alerte. +- [Audits](/fr/agenteye/audits) : l'analyste planifié qui détecte les échecs qu'aucune règle ne surveillait. \ No newline at end of file diff --git a/docs/fr/agenteye/observability.mdx b/docs/fr/agenteye/observability.mdx index 577af02e..bcc676d0 100644 --- a/docs/fr/agenteye/observability.mdx +++ b/docs/fr/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- title: "Observer" -description: "Les surfaces d'observation permettent de surveiller en temps réel ce que font vos agents et d'explorer chaque exécution en détail." +description: "Les surfaces d'observation permettent de surveiller ce que font vos agents en temps réel et d'explorer n'importe quelle exécution en détail." --- -Les surfaces d'observation permettent de surveiller en temps réel ce que font vos agents et d'explorer chaque exécution en détail. Tout ici est en direct, limité à votre organisation, et filtrable par plage de dates, environnement, agent et session — vous passez de « quelque chose cloche » à l'exécution exacte en quelques secondes. +Les surfaces d'observation permettent de surveiller ce que font vos agents en temps réel et d'explorer n'importe quelle exécution en détail. Tout ici est en direct, limité à votre organisation et filtrable par plage de dates, environnement, agent et session — vous passez ainsi de « quelque chose ne va pas » à l'exécution exacte en quelques secondes. ![Le flux d'événements en direct, coloré par type et filtrable par environnement, agent et session](/agenteye/images/events-stream.png) Quatre surfaces, chacune avec sa propre page : -- **[Flux d'événements](/fr/agenteye/event-stream)** : le suivi en direct, étape par étape, de chaque exécution pour tous les agents, du plus récent au plus ancien. La page d'accueil de votre organisation et premier point de triage. -- **[Sessions et graphe d'exécution](/fr/agenteye/sessions)** : ces événements regroupés en une ligne par exécution, accompagnés d'une représentation visuelle de type git montrant comment chaque exécution s'est déroulée. -- **[Métriques de performance](/fr/agenteye/telemetry)** : cartes de chaleur de latence et indicateurs p50/p95/p99 pour vos modèles, outils et hooks, afin de distinguer les pics extrêmes de la médiane. -- **[Suivi des erreurs](/fr/agenteye/error-tracking)** : une surface de triage unique pour tout ce qui a mal tourné, à un clic d'une alerte déclenchée vers l'exécution responsable. +- **[Flux d'événements](/fr/agenteye/event-stream)** : la trace en direct, étape par étape, de chaque exécution sur tous les agents, du plus récent au plus ancien. Accueil de votre organisation et premier arrêt pour le triage. +- **[Sessions et graphe d'exécution](/fr/agenteye/sessions)** : ces événements regroupés en une ligne par exécution, ainsi qu'une représentation visuelle (style git) du déroulement de chaque exécution. +- **[Métriques de performance](/fr/agenteye/telemetry)** : cartes de chaleur de latence et indicateurs p50/p95/p99 pour vos modèles, outils et hooks, afin qu'un pic de queue ressorte clairement par rapport à la médiane. +- **[Suivi des erreurs](/fr/agenteye/error-tracking)** : une surface de triage unique pour tout ce qui a mal tourné, à un clic d'une alerte déclenchée jusqu'à l'exécution fautive. -## Liens connexes +## En relation -- [Évaluations](/fr/agenteye/evaluations) : notez chaque exécution selon la qualité. -- [Alertes](/fr/agenteye/alerts) : transformez n'importe quel seuil en règle de notification. -- [Audits](/fr/agenteye/audits) : laissez Failproof AI Observability identifier automatiquement les schémas d'échec entre les sessions. +- [Évaluations](/fr/agenteye/evaluations) : noter chaque exécution selon sa qualité. +- [Alertes](/fr/agenteye/alerts) : transformer n'importe quel seuil en règle de notification. +- [Audits](/fr/agenteye/audits) : laisser Failproof AI Observability identifier les schémas d'échec entre les sessions pour vous. - [CLI et agents](/fr/agenteye/cli-and-agents) : la même observabilité depuis votre terminal. \ No newline at end of file diff --git a/docs/fr/agenteye/openclaw-capture.mdx b/docs/fr/agenteye/openclaw-capture.mdx index bf25828f..329b035d 100644 --- a/docs/fr/agenteye/openclaw-capture.mdx +++ b/docs/fr/agenteye/openclaw-capture.mdx @@ -1,11 +1,11 @@ --- -title: "Capture de session OpenClaw" -description: "Transmettez les sessions OpenClaw locales de votre équipe vers AgentEye en tant que sessions et événements ordinaires — sans aucune modification de votre façon d'utiliser OpenClaw." +title: "Capture de sessions OpenClaw" +description: "Transmettez les sessions OpenClaw locales de votre équipe vers AgentEye sous forme de sessions et d'événements ordinaires — sans modifier la façon dont OpenClaw s'exécute." --- -Si votre équipe utilise [OpenClaw](https://docs.openclaw.ai), la capture de session OpenClaw importe ces sessions dans AgentEye en tant que sessions et événements ordinaires, afin que vous puissiez les rechercher, les rejouer et les évaluer aux côtés de tout ce que vous observez. Cette fonctionnalité complète le [SDK Python](/fr/agenteye/python-sdk) : le SDK instrumente les agents que vous développez, tandis que la capture OpenClaw enregistre le travail que votre équipe réalise déjà — sans aucune modification de leur façon de l'exécuter. +Si votre équipe utilise [OpenClaw](https://docs.openclaw.ai), la capture de sessions OpenClaw intègre ces sessions dans AgentEye sous forme de sessions et d'événements ordinaires, afin que vous puissiez les rechercher, les rejouer et les évaluer aux côtés de tout ce que vous observez par ailleurs. Cette fonctionnalité complète le [SDK Python](/fr/agenteye/python-sdk) : le SDK instrumente les agents que vous développez, tandis que cette capture recueille le travail OpenClaw que votre équipe effectue déjà — sans rien changer à leur façon de l'exécuter. -Un petit collecteur en arrière-plan lit les transcripts de session locaux d'OpenClaw au fur et à mesure de leur écriture et les envoie vers AgentEye. Il fonctionne de la même manière que la [capture Codex](/fr/agenteye/codex-capture), et un seul collecteur peut capturer les deux simultanément. +Un petit collecteur en arrière-plan lit les transcripts de sessions locales d'OpenClaw au fur et à mesure de leur écriture et les envoie à AgentEye. Il fonctionne de la même manière que la [capture Codex](/fr/agenteye/codex-capture), et un seul collecteur peut capturer les deux simultanément. --- @@ -13,20 +13,20 @@ Un petit collecteur en arrière-plan lit les transcripts de session locaux d'Ope Chaque agent configuré dans l'installation OpenClaw d'une machine est capturé par le collecteur de cette machine — aucune configuration par agent n'est nécessaire. -Chaque session OpenClaw devient une [session](/fr/agenteye/sessions) AgentEye ; ses messages utilisateur et assistant, ses appels d'outils et les résultats de ces appels deviennent les [événements](/fr/agenteye/event-stream) correspondants. +Chaque session OpenClaw devient une [session](/fr/agenteye/sessions) AgentEye ; ses messages utilisateur et assistant, ses appels d'outils et ses résultats d'outils deviennent les [événements](/fr/agenteye/event-stream) correspondants. --- ## Activation -La capture est désactivée jusqu'à ce que vous l'activiez. Installez le collecteur avec une clé API disposant de la permission `events:add` (voir [Clés API](/fr/agenteye/api-keys)), puis activez la capture OpenClaw : +La capture est désactivée par défaut. Installez le collecteur avec une clé API disposant de la permission `events:add` (voir [Clés API](/fr/agenteye/api-keys)), puis activez la capture OpenClaw : ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -Cette commande installe le collecteur, l'enregistre en tant que service en arrière-plan et démarre la capture. Vérifiez qu'il est bien en cours d'exécution : +Cette commande installe le collecteur, l'enregistre en tant que service en arrière-plan et démarre la capture. Pour vérifier qu'il est bien actif : ```bash agenteye-collector health @@ -34,16 +34,16 @@ agenteye-collector health Vous capturez plusieurs agents sur la même machine ? Ajoutez le flag de chacun à la même commande — par exemple `--openclaw-enabled --codex-enabled`. -Au premier démarrage, vos sessions OpenClaw existantes sont importées une seule fois, puis la nouvelle activité est transmise en quelques secondes. Les fichiers d'OpenClaw sont uniquement lus — jamais modifiés, déplacés ou supprimés — et chaque session est envoyée exactement une fois, même lors des redémarrages. +Lors du premier lancement, vos sessions OpenClaw existantes sont importées rétroactivement en une seule fois, puis la nouvelle activité est transmise en continu en quelques secondes. Les fichiers d'OpenClaw sont uniquement lus — jamais modifiés, déplacés ou supprimés — et chaque session est envoyée exactement une fois, même en cas de redémarrage. --- -## Où retrouver les données +## Où les retrouver -Les sessions capturées apparaissent dans **Sessions**, et leurs événements dans le flux **Events**, comme pour tout autre agent que vous observez — ainsi, le [replay de session](/fr/agenteye/sessions), la [recherche](/fr/agenteye/queries), les [évaluations](/fr/agenteye/evaluations) et les [alertes](/fr/agenteye/alerts) fonctionnent tous sur ces données. Filtrez par agent OpenClaw pour les afficher séparément. +Les sessions capturées apparaissent dans **Sessions**, et leurs événements dans le flux **Events**, exactement comme n'importe quel autre agent que vous observez — ainsi, le [rejeu de session](/fr/agenteye/sessions), la [recherche](/fr/agenteye/queries), les [évaluations](/fr/agenteye/evaluations) et les [alertes](/fr/agenteye/alerts) s'appliquent toutes à ces sessions. Filtrez par agent OpenClaw pour les afficher séparément. --- ## Confidentialité -Les transcripts OpenClaw contiennent l'intégralité de la session — y compris la sortie des commandes, le contenu des fichiers, et tout ce que l'agent a lu ou écrit — et peuvent contenir des secrets. Les sessions capturées sont transmises telles quelles, donc n'activez la capture que sur les machines et pour les équipes pour lesquelles la centralisation de ces données dans AgentEye est appropriée, et accordez au collecteur une clé limitée au seul scope `events:add`. Consultez la section [Sécurité](/fr/agenteye/security) pour en savoir plus sur l'isolation de vos données. \ No newline at end of file +Les transcripts OpenClaw contiennent l'intégralité de la session — notamment la sortie des commandes, le contenu des fichiers et tout ce que l'agent a lu ou écrit — et peuvent contenir des secrets. Les sessions capturées sont transmises telles quelles ; n'activez donc la capture que sur les machines et pour les équipes pour lesquelles la centralisation de ce contenu dans AgentEye est appropriée, et donnez au collecteur une clé limitée au seul scope `events:add`. Consultez [Sécurité](/fr/agenteye/security) pour savoir comment vos données sont maintenues isolées. \ No newline at end of file diff --git a/docs/fr/agenteye/overview.mdx b/docs/fr/agenteye/overview.mdx index ae189ffd..36edd453 100644 --- a/docs/fr/agenteye/overview.mdx +++ b/docs/fr/agenteye/overview.mdx @@ -4,44 +4,44 @@ description: "Failproof AI Observability est une plateforme auto-hébergée pour --- -Failproof AI Observability est une plateforme auto-hébergée pour observer, évaluer et améliorer vos agents IA en production. Elle enregistre tout ce que font vos agents (chaque appel d'outil, requête de modèle, hook et erreur), note la qualité de chaque exécution, et met en évidence les défaillances que vous n'auriez pas su chercher — le tout dans un tableau de bord que vous faites tourner dans votre propre infrastructure. +Failproof AI Observability est une plateforme auto-hébergée pour observer, évaluer et améliorer vos agents IA en production. Elle enregistre tout ce que font vos agents (chaque appel d'outil, requête de modèle, hook et erreur), évalue la qualité de chaque exécution, et met en évidence les défaillances que vous n'auriez pas pensé à chercher — le tout dans un tableau de bord que vous hébergez dans votre propre infrastructure. -Si vous déployez des agents IA et que vous en avez assez de deviner pourquoi une exécution a mal tourné, c'est par ici qu'il faut commencer. Cette page explique ce que Failproof AI Observability vous apporte et comment les différentes pièces s'articulent, avant même que vous n'installiez quoi que ce soit. +Si vous déployez des agents IA et que vous en avez assez de deviner pourquoi une exécution a mal tourné, c'est la page par laquelle commencer. Elle explique ce que Failproof AI Observability vous apporte et comment les différentes pièces s'articulent, avant toute installation. -> **Failproof AI Observability est un produit entreprise de Failproof AI.** Vous voulez le voir en action ? Demandez une démo : écrivez à [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +> **Failproof AI Observability est un produit entreprise de Failproof AI.** Vous souhaitez le voir en action ? Demandez une démonstration : envoyez un e-mail à [nikita@befailproof.ai](mailto:nikita@befailproof.ai). -![Une session Failproof AI Observability représentée sous forme de graphe d'exécution à la git, à côté de sa chronologie d'événements, avec un détail par exécution des outils, modèles et hooks dans le panneau de droite](/agenteye/images/session-detail.png) +![Une session Failproof AI Observability représentée sous forme de graphe d'exécution en style git à côté de sa chronologie d'événements, avec une ventilation par exécution des outils, modèles et hooks dans le rail droit](/agenteye/images/session-detail.png) -*Chaque exécution d'agent est représentée sous forme de graphe d'exécution à la git (gauche), à côté de sa chronologie d'événements. Les sous-agents parallèles ont chacun leur propre couloir ; le panneau de droite détaille les outils, modèles, hooks et la consommation de tokens pour l'exécution.* +*Chaque exécution d'agent est représentée sous forme de graphe d'exécution en style git (à gauche) à côté de sa chronologie d'événements. Les sous-agents parallèles ont chacun leur propre voie ; le rail droit détaille les outils, modèles, hooks et la consommation de tokens pour l'exécution.* --- -## Voir en action +## Voyez-le en action -Deux courtes vidéos illustrent les deux choses que les équipes recherchent en premier : tracer une exécution, et détecter automatiquement les défaillances. +Deux courtes vidéos montrent les deux choses que les équipes recherchent en premier : tracer une exécution, et détecter automatiquement les défaillances.
-*Traçage d'agent : suivez une exécution pas à pas, de l'objectif aux outils jusqu'à la réponse finale.* +*Traçage d'agent : suivez une seule exécution étape par étape, de l'objectif aux outils jusqu'à la réponse finale.*
-*Failproof Audit : laissez Failproof AI Observability analyser vos logs sur l'ensemble des sessions et vous indiquer ce qu'il faut corriger.* +*Failproof Audit : laissez Failproof AI Observability analyser vos logs à travers les sessions et vous indiquer ce qu'il faut corriger.* --- ## Pourquoi les équipes l'utilisent -- **Voyez ce que votre agent a réellement fait.** Chaque exécution devient un graphe d'exécution lisible à la git : quels outils ont fonctionné en parallèle, quels sous-agents ont divergé, où l'exécution s'est bloquée, et ce qu'elle a consommé. -- **Détectez automatiquement les régressions de qualité.** Connectez un petit service de notation et Failproof AI Observability note chaque exécution terminée — une baisse d'utilité ou une hausse des hallucinations apparaît d'elle-même. -- **Trouvez les défaillances pour lesquelles vous n'avez écrit aucune règle.** Des audits récurrents analysent vos logs sur l'ensemble des sessions pour repérer des clusters d'erreurs, des valeurs aberrantes de latence, des scores faibles et des exécutions bloquées, puis vous remettent des résultats classés et étayés par des preuves. -- **Soyez alerté quand ça compte vraiment.** Des règles de seuil se déclenchent sur le taux d'erreur, la latence, le coût ou les scores d'évaluation, et ouvrent des incidents que vous pouvez prendre en charge, assigner et résoudre. -- **Posez des questions en langage naturel.** Un assistant IA intégré au tableau de bord répond à des questions comme « comment évolue la qualité en production cette semaine ? » en s'appuyant sur vos propres données. Toute modification qu'il propose est soumise à validation. -- **Gardez la maîtrise de vos données.** Failproof AI Observability est auto-hébergé : les événements, les prompts et les analyses restent dans une infrastructure que vous contrôlez. +- **Voyez ce que votre agent a réellement fait.** Chaque exécution devient un graphe d'exécution lisible en style git : quels outils ont fonctionné en parallèle, quels sous-agents ont bifurqué, où l'exécution a stagné, et ce qu'elle a coûté. +- **Détectez automatiquement les régressions de qualité.** Connectez un petit service de scoring et Failproof AI Observability évalue chaque exécution terminée, de sorte qu'une baisse d'utilité ou une hausse des hallucinations apparaît d'elle-même. +- **Trouvez les défaillances pour lesquelles vous n'avez pas écrit de règle.** Des audits récurrents analysent vos logs à travers les sessions pour y détecter des clusters d'erreurs, des valeurs aberrantes de latence, des scores faibles et des exécutions bloquées, puis vous remettent des résultats classés et étayés par des preuves. +- **Soyez alerté quand c'est important.** Des règles de seuil se déclenchent sur le taux d'erreur, la latence, le coût ou les scores d'évaluateur, et ouvrent des incidents que vous pouvez acquitter, assigner et résoudre. +- **Posez des questions en langage naturel.** Un assistant IA intégré au tableau de bord répond à des questions comme « comment la qualité évolue-t-elle en prod cette semaine ? » à partir de vos propres données. Toute modification qu'il propose est soumise à approbation. +- **Gardez vos données.** Failproof AI Observability est auto-hébergé : les événements, les prompts et les analyses restent dans une infrastructure que vous contrôlez. --- @@ -49,60 +49,60 @@ Deux courtes vidéos illustrent les deux choses que les équipes recherchent en Failproof AI Observability s'articule autour de trois idées (**observer**, **analyser** et **administrer**), reflétées dans la barre latérale gauche du tableau de bord. -**Observer** (la réalité brute de ce qui s'est passé) : +**Observer** (la vérité brute de ce qui s'est passé) : - **[Flux d'événements](/fr/agenteye/event-stream)** : la trace en direct, étape par étape, de chaque exécution (appels d'outils, appels de modèles, hooks, erreurs). -- **[Sessions](/fr/agenteye/sessions)** : ces événements regroupés en une ligne par exécution, chacune prête à être notée, avec un graphe d'exécution à la git. -- **[Métriques de performance](/fr/agenteye/telemetry)** : cartes thermiques de latence par surface et indicateurs p50/p95/p99 pour les modèles, outils et hooks, pour qu'une valeur aberrante en queue de distribution ressorte clairement par rapport à la médiane. +- **[Sessions](/fr/agenteye/sessions)** : ces événements regroupés en une ligne par exécution, chacune prête à être évaluée, avec un graphe d'exécution en style git. +- **[Métriques de performance](/fr/agenteye/telemetry)** : cartes thermiques de latence par surface et indicateurs p50/p95/p99 pour les modèles, outils et hooks, afin qu'un pic de queue se distingue clairement de la médiane. - **[Suivi des erreurs](/fr/agenteye/error-tracking)** : une surface de triage unique pour tout ce qui a dysfonctionné, à un clic d'une alerte déclenchée. -![La page d'observation des outils : une carte thermique de latence, une bande de percentiles et un graphique de distribution des outils sur 24 plages temporelles](/agenteye/images/tools.png) +![La page d'observation des outils : une carte thermique de latence, une bande de percentiles et une barre de distribution des outils sur 24 intervalles temporels](/agenteye/images/tools.png) -*Chaque surface d'observation associe une sparkline et des indicateurs p50/p95/p99 à une carte thermique de latence et une bande de percentiles. Ici : Outils.* +*Chaque surface d'observation associe un graphique sparkline et des indicateurs p50/p95/p99 à une carte thermique de latence et une bande de percentiles. Ici : Outils.* **Analyser** (transformer l'activité en réponses) : -- **[Requêtes](/fr/agenteye/queries)** et **[tableaux de bord](/fr/agenteye/dashboards)** : du SQL sauvegardé sur vos événements et évaluations, représenté sous forme de graphiques dans des tableaux de bord partagés à l'échelle de l'organisation. -- **[Évaluations](/fr/agenteye/evaluations)** : scores de qualité produits par votre propre service d'évaluation, avec le raisonnement associé à chaque score. -- **[Audits](/fr/agenteye/audits)** : investigations récurrentes qui font remonter les patterns de défaillance sur l'ensemble des sessions. -- **[Alertes](/fr/agenteye/alerts)** et **[incidents](/fr/agenteye/incidents)** : règles de seuil qui vous notifient, accompagnées d'un workflow d'incidents pour les trier. +- **[Requêtes](/fr/agenteye/queries)** et **[tableaux de bord](/fr/agenteye/dashboards)** : SQL sauvegardé sur vos événements et évaluations, représenté sous forme de graphiques dans des tableaux de bord partagés à l'échelle de l'organisation. +- **[Évaluations](/fr/agenteye/evaluations)** : scores de qualité produits par votre propre service d'évaluation, avec un raisonnement par score. +- **[Audits](/fr/agenteye/audits)** : investigations récurrentes qui font remonter les schémas de défaillance à travers les sessions. +- **[Alertes](/fr/agenteye/alerts)** et **[incidents](/fr/agenteye/incidents)** : règles de seuil qui vous notifient, plus un workflow d'incidents pour les trier. **Interfaces** (accédez à vos données à votre façon) : -- **[CLI](/fr/agenteye/cli-and-agents)** : pilotez l'ensemble de votre déploiement depuis le terminal ou un script, et laissez un agent de développement le faire pour vous en langage naturel. -- **[Assistant IA](/fr/agenteye/assistant)** : posez des questions sur vos agents en langage naturel, directement depuis le tableau de bord. -- **API REST** : tout ce que font le tableau de bord et la CLI est soutenu par une API REST que vous pouvez appeler directement avec une [clé API](/fr/agenteye/api-keys) à portée limitée — ingérer des événements, interroger des sessions et des évaluations, et gérer des tableaux de bord, alertes, audits, utilisateurs et clés, pour intégrer Failproof AI Observability dans vos propres outils. +- **[CLI](/fr/agenteye/cli-and-agents)** : pilotez l'intégralité de votre déploiement depuis le terminal ou un script, et laissez un agent de codage le faire pour vous en langage naturel. +- **[Assistant IA](/fr/agenteye/assistant)** : posez des questions sur vos agents en langage naturel, directement dans le tableau de bord. +- **API REST** : tout ce que font le tableau de bord et le CLI est soutenu par une API REST que vous pouvez appeler directement avec une [clé API](/fr/agenteye/api-keys) à portée limitée — ingérez des événements, interrogez les sessions et les évaluations, et gérez les tableaux de bord, alertes, audits, utilisateurs et clés, afin d'intégrer Failproof AI Observability dans vos propres outils. -**Administrer** (faites-le tourner pour votre équipe) : +**Administrer** (faites-le fonctionner pour votre équipe) : - **[Clés API](/fr/agenteye/api-keys)** : tokens à portée limitée pour le collecteur, le tableau de bord et l'assistant. -- **Utilisateurs** : connexion sans mot de passe, par e-mail avec liste d'autorisation. +- **Utilisateurs** : connexion sans mot de passe par e-mail avec liste d'autorisation. - **Paramètres** : configuration par organisation, y compris les surcharges de fenêtre de contexte des modèles. --- ## Comment les pièces s'articulent -Les données circulent dans un seul sens, de votre code d'agent vers le tableau de bord : votre agent (via le SDK Python) émet des événements vers l'agenteye-collector, qui les achemine vers le serveur, lequel sert le tableau de bord. Deux services optionnels complètent l'ensemble — un service de notation (évaluations) et un service d'assistant IA (le chat intégré au tableau de bord). +Les données circulent dans un seul sens, de votre code d'agent vers le tableau de bord : votre agent (via le SDK Python) émet des événements vers l'agenteye-collector, qui les envoie au serveur, lequel alimente le tableau de bord. Deux services optionnels complètent l'ensemble — un service de scoring (évaluations) et un service d'assistant IA (le chat intégré au tableau de bord). - **SDK Python** : vous ajoutez quelques appels `agenteye.event.*` à votre agent ; les événements sont mis en mémoire tampon localement. -- **agenteye-collector** : un démon léger sur chaque machine agent qui regroupe les événements en lots et les envoie au serveur. -- **Serveur** : ingère vos événements, maintient l'état opérationnel dans vos propres bases de données, et expose l'API REST utilisée par le tableau de bord, la CLI et vos propres intégrations. -- **Tableau de bord** : l'endroit où vous explorez tout. -- **Services optionnels** : un service de notation (évaluations) et un service d'assistant IA (le chat intégré au tableau de bord). +- **agenteye-collector** : un daemon léger sur chaque machine d'agent qui regroupe les événements par lots et les envoie au serveur. +- **Serveur** : ingère vos événements, maintient l'état opérationnel dans vos propres bases de données, et expose l'API REST qu'utilisent le tableau de bord, le CLI et vos propres intégrations. +- **Tableau de bord** : là où vous explorez tout. +- **Services optionnels** : un service de scoring (évaluations) et un service d'assistant IA (le chat intégré au tableau de bord). -Pour le vocabulaire utilisé tout au long de la documentation (*event, session, evaluation, audit, finding, incident*), consultez [Concepts](/fr/agenteye/concepts). +Pour le vocabulaire utilisé tout au long de la documentation (*événement, session, évaluation, audit, résultat, incident*), voir [Concepts](/fr/agenteye/concepts). --- ## Obtenir Failproof AI Observability -Failproof AI Observability est un produit entreprise de Failproof AI, et fonctionne en complément de Failproof AI Enforcement — le produit de politiques et de garde-fous — sous la marque Failproof AI. Il fonctionne entièrement dans votre propre environnement. Si vous n'avez pas encore accès aux packages, demandez une démo et nous vous aiderons à démarrer : écrivez à [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Failproof AI Observability est un produit entreprise de Failproof AI, et il fonctionne aux côtés de Failproof AI Enforcement — le produit de politique et de garde-fous — sous la marque Failproof AI. Il s'exécute entièrement dans votre propre environnement. Si vous n'avez pas encore accès aux packages, demandez une démonstration et nous vous aiderons à démarrer : envoyez un e-mail à [nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- -## Prochaines étapes +## Étapes suivantes - [Concepts](/fr/agenteye/concepts) : le vocabulaire de Failproof AI Observability en un seul endroit. -- [Observabilité](/fr/agenteye/observability) : suivez ce que font vos agents, exécution par exécution. +- [Observability](/fr/agenteye/observability) : suivez ce que font vos agents, exécution par exécution. - [Sécurité](/fr/agenteye/security) : comment Failproof AI Observability maintient vos données isolées et sous votre contrôle. \ No newline at end of file diff --git a/docs/fr/agenteye/python-sdk-skill.mdx b/docs/fr/agenteye/python-sdk-skill.mdx index 010b3a6d..e8610b79 100644 --- a/docs/fr/agenteye/python-sdk-skill.mdx +++ b/docs/fr/agenteye/python-sdk-skill.mdx @@ -1,57 +1,57 @@ --- -title: "Compétence Agent du SDK Python Failproof AI Observability" -description: "Passez d'un agent non instrumenté à des événements visibles, votre agent de codage trouvant les points d'instrumentation, les écrivant et prouvant qu'ils ont bien été intégrés." +title: "Compétence d'agent SDK Python pour l'observabilité Failproof AI" +description: "Passez d'un agent non instrumenté à des événements visibles, avec votre agent de codage qui identifie les points d'instrumentation, les écrit et confirme qu'ils fonctionnent." --- -Dites à votre agent de codage *« ajoute Failproof AI Observability à cet agent »* et laissez-le lire votre boucle, déterminer où placer l'instrumentation, l'écrire et vérifier les événements avant de considérer le travail terminé. +Dites à votre agent de codage *« ajoute l'observabilité Failproof AI à cet agent »* et laissez-le lire votre boucle, déterminer où placer l'instrumentation, l'écrire et vérifier les événements avant de déclarer la tâche terminée. -La **compétence SDK Python** (`agenteye-python-sdk`) est une *Agent Skill* : un dossier d'instructions qu'un agent de codage tel que Claude Code ou Codex charge à la demande lorsqu'une tâche lui correspond. Elle apprend à l'agent à utiliser le [SDK Python](/fr/agenteye/python-sdk) — ce n'est pas une bibliothèque, et elle ne modifie en rien le fonctionnement du SDK. +La **compétence SDK Python** (`agenteye-python-sdk`) est une *compétence d'agent* : un dossier d'instructions qu'un agent de codage tel que Claude Code ou Codex charge à la demande lorsqu'une tâche lui correspond. Elle apprend à l'agent à utiliser le [SDK Python](/fr/agenteye/python-sdk) — ce n'est pas une bibliothèque, et elle ne change rien au fonctionnement du SDK. -## L'instrumentation est facile à écrire et facile à rater silencieusement +## L'instrumentation est facile à écrire, et facile à rater silencieusement -Le SDK est minimaliste : treize méthodes d'événements, toutes avec des paramètres nommés uniquement. Un agent de codage peut lire la référence du [SDK Python](/fr/agenteye/python-sdk) et produire une instrumentation plausible en une minute. +Le SDK est minimal : treize méthodes d'événements, toutes avec des arguments nommés. Un agent de codage peut lire la référence du [SDK Python](/fr/agenteye/python-sdk) et produire une instrumentation plausible en une minute. -Le problème, c'est que ce SDK ne lève pas d'exception en cas d'erreur, et une mauvaise instrumentation ressemble exactement à une bonne instrumentation jusqu'à ce que quelqu'un ouvre un tableau de bord et le trouve vide. Les erreurs qui font perdre du temps sont toutes des silences : +Le problème, c'est que ce SDK ne lève pas d'erreur quand vous vous trompez, et une mauvaise instrumentation ressemble exactement à une bonne instrumentation — jusqu'à ce que quelqu'un ouvre le tableau de bord et le trouve vide. Les erreurs qui coûtent vraiment du temps sont toutes des silences : | L'erreur | Ce que vous voyez | |---|---| -| Pas de `agent_start` | Tous les événements arrivent. Zéro session. | +| Pas de `agent_start` | Chaque événement arrive. Zéro session. | | Environnement jamais défini | Tout fonctionne, classé sous `dev`. | -| `outcome="failure"` | L'exécution s'affiche en vert — seuls `failed`, `error`, `timeout`, `rejected` comptent. | -| Un nom de champ mal orthographié | Accepté et stocké comme nouveau champ. | -| Événements émis depuis un pool de threads | Silencieusement abandonnés. | +| `outcome="failure"` | L'exécution apparaît en vert — seuls `failed`, `error`, `timeout`, `rejected` comptent. | +| Un nom de champ mal orthographié | Accepté et stocké comme un nouveau champ. | +| Événements émis depuis un pool de threads | Silencieusement ignorés. | -Aucun de ces cas ne lève d'exception. Aucun n'apparaît dans les tests. Chacun est documenté dans la compétence, énoncé comme un contrat avec la vérification qui le détecte. +Aucun de ces cas ne lève d'erreur. Aucun n'apparaît dans les tests. Chacun est documenté dans la compétence, formulé comme un contrat avec la vérification qui le détecte. ## Ce qu'elle fait, dans l'ordre -La compétence exécute les trois mêmes étapes qu'un ingénieur rigoureux suivrait : +La compétence suit les mêmes trois étapes qu'un ingénieur rigoureux : -1. **Planifier.** Elle lit votre boucle d'agent et pose les deux questions auxquelles vous seul pouvez répondre : ce qui constitue une exécution (votre `session_id`), et qui sont les acteurs distinguables (votre `agent_id`). Elle obtient un accord sur ces points avant d'écrire du code, car les modifier plus tard divise votre historique et casse les tendances. -2. **Écrire.** Elle lie l'identité une seule fois par exécution plutôt que de la propager à travers chaque point d'appel, et elle choisit une forme sûre pour la concurrence — un détail qui compte, car le raccourci évident mélange silencieusement deux exécutions simultanées en une seule session. -3. **Vérifier.** Elle exécute votre agent et lit les fichiers d'événements résultants, en vérifiant que `agent_start` est présent, que l'environnement est correct et qu'une exécution a produit une session. +1. **Planifier.** Elle lit votre boucle d'agent et pose les deux questions auxquelles vous seul pouvez répondre : qu'est-ce qui constitue une exécution (votre `session_id`), et qui sont les acteurs distinguables (votre `agent_id`). Elle obtient ces réponses avant d'écrire du code, car les modifier plus tard fragmente votre historique et casse les tendances. +2. **Écrire.** Elle lie l'identité une seule fois par exécution plutôt que de la faire transiter par chaque point d'appel, et elle choisit une forme sûre pour la concurrence — un détail important, car le raccourci évident mélange silencieusement deux exécutions qui se chevauchent dans une seule session. +3. **Vérifier.** Elle lance votre agent et lit les fichiers d'événements produits, en vérifiant que `agent_start` est présent, que l'environnement est correct, et qu'une exécution a produit une session. -Cette troisième étape est celle que les gens ignorent. Le SDK écrit les événements dans des fichiers locaux, donc une intégration complète peut être prouvée sur un ordinateur portable sans serveur, sans clé API et sans réseau — c'est précisément pourquoi la compétence insiste pour le faire. +Cette troisième étape est celle que tout le monde saute. Le SDK écrit les événements dans des fichiers locaux, donc une intégration complète peut être prouvée sur un ordinateur portable sans serveur, sans clé API et sans réseau — c'est précisément pourquoi la compétence insiste pour le faire. -## Son rapport aux autres compétences +## Son rapport avec les autres compétences Trois compétences, une séparation nette : -| Compétence | À utiliser quand | Ce qu'elle modifie | +| Compétence | À utiliser quand | Ce qu'elle touche | |---|---|---| -| **Compétence SDK Python** (cette page) | Vous voulez que votre agent *émette* de la télémétrie — « ajoute de l'observabilité », « pourquoi mon agent n'apparaît pas ? » | Écrit du code dans le dépôt de votre agent. Ne lit rien. | -| **[Compétence Evaluator](/fr/agenteye/evaluator-skill)** | Vous voulez *noter* les exécutions — « que devrions-nous même mesurer ? » | Écrit du code dans votre dépôt ; lit la télémétrie | -| **[Compétence CLI](/fr/agenteye/cli-skill)** | Vous voulez *lire* ce qui s'est passé, ou opérer votre déploiement | Pilote la CLI en votre nom, y compris les modifications | +| **Compétence SDK Python** (cette page) | Vous voulez que votre agent *émette* de la télémétrie — « ajoute l'observabilité », « pourquoi mon agent n'apparaît-il pas ? » | Écrit du code dans le dépôt de votre agent. Ne lit rien. | +| **[Compétence Évaluateur](/fr/agenteye/evaluator-skill)** | Vous voulez *noter* les exécutions — « que devrait-on mesurer ? » | Écrit du code dans votre dépôt ; lit la télémétrie | +| **[Compétence CLI](/fr/agenteye/cli-skill)** | Vous voulez *lire* ce qui s'est passé, ou gérer votre déploiement | Pilote le CLI en votre nom, y compris les modifications | -Elles se relaient dans cet ordre : cette compétence fait circuler les événements, l'évaluateur les note, la CLI les relit. Il n'y a rien à évaluer et rien à lire tant que votre agent n'émet pas de sessions — donc si vous partez de zéro, commencez ici. +Elles se passent le relais dans cet ordre : cette compétence fait circuler les événements, l'évaluateur les note, le CLI les relit. Il n'y a rien à évaluer et rien à lire tant que votre agent n'émet pas de sessions — donc si vous partez de zéro, commencez ici. ## Prérequis -1. **Python 3.10+** et la base de code de l'agent que vous souhaitez instrumenter. -2. **Le SDK.** Il est distribué aux clients sous forme de wheel privé plutôt que depuis un index public — votre intégration couvre comment l'obtenir et l'installer. La compétence connaît le chemin d'installation et vous demandera plutôt que de deviner si elle ne le trouve pas. -3. **Rien d'autre.** Pas de connexion au tableau de bord, pas de clé API, pas de réseau. La compétence vérifie à partir des fichiers d'événements que le SDK écrit, elle peut donc terminer et prouver son travail hors ligne. +1. **Python 3.10+** et le code source de l'agent que vous souhaitez instrumenter. +2. **Le SDK.** Il est distribué aux clients sous forme de wheel privée plutôt que depuis un index public — votre onboarding explique comment l'obtenir et l'installer. La compétence connaît le chemin d'installation et vous demandera plutôt que de deviner si elle ne le trouve pas. +3. **Rien d'autre.** Pas de connexion au tableau de bord, pas de clé API, pas de réseau. La compétence vérifie en lisant les fichiers d'événements que le SDK écrit, elle peut donc terminer et prouver son travail hors ligne. -## Où l'obtenir +## Où la trouver La compétence se trouve dans la collection publique [`FailproofAI/skills`](https://github.com/FailproofAI/skills) : @@ -59,77 +59,73 @@ La compétence se trouve dans la collection publique [`FailproofAI/skills`](http npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -Ajoutez `-g` pour l'installer pour tous les projets plutôt que pour le seul projet en cours, et `--copy` si votre environnement ne suit pas les liens symboliques. Pour Codex, passez `-a codex`. +Ajoutez `-g` pour l'installer sur tous les projets plutôt que sur le seul projet en cours, et `--copy` si votre environnement ne suit pas les liens symboliques. Pour Codex, passez `-a codex`. ## Installation manuelle -Les Agent Skills sont des dossiers contenant un `SKILL.md` et des références associées. Si vous préférez ne pas utiliser l'installateur : +Les compétences d'agent sont des dossiers contenant un `SKILL.md` et des références. Si vous préférez ne pas utiliser l'installateur : -- **Claude Code** : copiez le dossier `agenteye-python-sdk/` dans `~/.claude/skills/` (tous les projets) ou `/.claude/skills/` (ce dépôt uniquement). Claude Code le découvre automatiquement — vérifiez la liste `/skills`, ou posez simplement une question qui lui correspond. -- **Codex** : Codex lit le même `SKILL.md`. Le fichier `agents/openai.yaml` inclus définit `allow_implicit_invocation: true`, il est donc auto-sélectionné quand une tâche lui correspond ; sinon invoquez-le avec `$agenteye-python-sdk`. +- **Claude Code** : copiez le dossier `agenteye-python-sdk/` dans `~/.claude/skills/` (tous les projets) ou `/.claude/skills/` (ce dépôt uniquement). Claude Code le découvre automatiquement — vérifiez la liste `/skills`, ou posez simplement une question qui y correspond. +- **Codex** : Codex lit le même `SKILL.md`. Le fichier `agents/openai.yaml` fourni définit `allow_implicit_invocation: true`, il est donc sélectionné automatiquement quand une tâche correspond ; sinon, invoquez-le avec `$agenteye-python-sdk`. -Exécutez votre agent **dans le dépôt contenant le code que vous souhaitez instrumenter** — la compétence lit votre boucle d'agent avant de proposer quoi que ce soit. +Lancez votre agent **dans le dépôt contenant le code que vous souhaitez instrumenter** — la compétence lit votre boucle d'agent avant de proposer quoi que ce soit. ## À quoi ressemble une session ```text -vous ▸ Ajoute Failproof AI Observability à cet agent. +vous ▸ Add Failproof AI Observability to this agent. -agent ▸ J'ai lu votre boucle — un dispatcheur d'outils dans tools.py, un - wrapper Anthropic dans llm.py. Deux questions avant d'écrire quoi - que ce soit. +agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic + wrapper in llm.py. Two questions before I write anything. - Qu'est-ce qui constitue une exécution ? Vous gérez les requêtes - en parallèle, donc j'utiliserais l'id de requête que vous avez - déjà dans ctx.request_id — ainsi une session ici et une requête - dans vos logs sont la même chaîne. + What counts as one run? You handle requests concurrently, so I'd + use the request id you already have in ctx.request_id — then a + session here and a request in your logs are the same string. - Et qui sont les acteurs ? Je vois un chemin planificateur et un - chemin chercheur. Les étiqueter séparément, ou c'est un seul - agent pour vous ? + And who are the actors? I see a planner path and a researcher + path. Label them separately, or is that one agent to you? -vous ▸ L'id de requête, c'est bon. C'est un seul agent, appelez-le "assistant". +vous ▸ Request id is right. They're one agent, call it "assistant". -agent ▸ Terminé. J'ai enveloppé le dispatcheur et le client LLM ; - agent_start et agent_end encadrent handle_request, y compris le - chemin d'erreur. J'ai utilisé un contexte local pour l'identité - — votre dispatcheur exécute les outils dans un pool de threads, - et l'approche plus simple aurait mélangé des exécutions - simultanées en une seule session sans se plaindre. +agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and + agent_end bracket handle_request, including the error path. Used + a context-local for identity — your dispatcher runs tools in a + thread pool, and the simpler approach would have mixed concurrent + runs into one session without complaining. - Vérifié sur une vraie exécution : 11 événements dans 4 fichiers — + Verified against a real run: 11 events across 4 files — agent_start, model_request/response, tool_use/tool_result x3, - agent_end (outcome=success). environment=production, une session - par requête, durées appariées. + agent_end (outcome=success). environment=production, one session + per request, durations paired. - Une chose que je n'ai PAS faite : votre pool de workers dans - batch.py soumet directement à l'executor, donc les événements - venant de là seraient perdus. Voulez-vous que je corrige ça aussi ? + One thing I did NOT do: your worker pool in batch.py submits + straight to the executor, so events from there would be dropped. + Want me to fix those too? ``` -Le schéma à remarquer : il a lu le code avant de proposer, n'a posé que les questions auxquelles vous seul pouvez répondre, a réutilisé un id que vous aviez déjà, a choisi la forme sûre pour la concurrence *parce qu'* il a vu un pool de threads, et **a vérifié en lisant les événements réels** plutôt qu'en déclarant le succès — puis a signalé l'endroit qu'il savait qui échouerait silencieusement. +Le schéma à retenir : il a lu le code avant de proposer quoi que ce soit, n'a posé que les questions auxquelles vous pouvez répondre, a réutilisé un identifiant que vous aviez déjà, a choisi la forme sûre pour la concurrence *parce qu'*il a vu un pool de threads, et **a vérifié en lisant les événements réels** plutôt qu'en déclarant le succès — puis a signalé l'endroit qu'il savait être susceptible d'échouer silencieusement. ## Ce que vous pouvez lui demander -- *« Pourquoi mon agent n'apparaît pas sur le tableau de bord ? »* → parcourt l'échelle : les événements sont-ils écrits, `agent_start` est-il présent, l'environnement est-il correct, le collecteur lit-il au bon endroit. -- *« Tout arrive sous dev. »* → l'environnement n'a jamais été défini, ou a été réinitialisé par un appel ultérieur. +- *« Pourquoi mon agent n'apparaît-il pas sur le tableau de bord ? »* → parcourt l'échelle : les événements sont-ils écrits, `agent_start` est-il présent, l'environnement est-il correct, le collecteur lit-il au même endroit. +- *« Tout atterrit sous dev. »* → l'environnement n'a jamais été défini, ou a été réinitialisé par un appel ultérieur. - *« Ajoute le suivi des tokens. »* → trouve votre wrapper LLM et enregistre le modèle, la raison d'arrêt et l'utilisation. -- *« Instrumente aussi les sous-agents. »* → une session, des étiquettes d'agent distinctes, imbriqués sous leur parent. -- *« Écris des tests pour l'instrumentation. »* → pointe le SDK vers un répertoire temporaire et effectue des assertions sur les événements qu'il a écrits. +- *« Instrumente aussi les sous-agents. »* → une session, des labels d'agents distincts, imbriqués sous leur parent. +- *« Écris des tests pour l'instrumentation. »* → pointe le SDK vers un répertoire temporaire et effectue des assertions sur les événements écrits. -## Points de vigilance +## Ce à quoi faire attention -**Laissez-le vérifier.** L'étape qui rend cette compétence utile est la dernière — exécuter votre agent et relire les événements. Un agent qui écrit l'instrumentation et s'arrête a fait la moitié facile, et la moitié qui échoue silencieusement, c'est l'autre. +**Laissez-la vérifier.** L'étape qui rend cette compétence utile est la dernière — lancer votre agent et relire les événements. Un agent qui écrit l'instrumentation et s'arrête là a fait la moitié facile, et la moitié qui échoue silencieusement, c'est l'autre. -**Convenez des noms avant le code.** `session_id` et `agent_id` sont les axes selon lesquels chaque surface regroupe les données. Les renommer plus tard divise l'historique : les anciennes exécutions conservent les anciennes étiquettes et vos tendances se cassent. La compétence posera la question ; la réponse mérite une minute de réflexion. +**Convenez des noms avant le code.** `session_id` et `agent_id` sont les axes selon lesquels chaque vue regroupe les données. Les renommer plus tard fragmente l'historique : les anciennes exécutions conservent leurs anciens labels et vos tendances se brisent. La compétence posera la question ; la réponse mérite une minute de réflexion. -**Si votre agent propose d'installer le SDK depuis un index public, la compétence n'a pas été chargée.** Le SDK est distribué en privé. Cette proposition est un signe révélateur que votre agent de codage improvise plutôt que de suivre la compétence — arrêtez-le là et vérifiez que la compétence est installée. +**Si votre agent propose d'installer le SDK depuis un index public, la compétence n'a pas été chargée.** Le SDK est distribué de façon privée. Cette proposition est un signe fiable que votre agent de codage improvise plutôt que de suivre la compétence — arrêtez-le là et vérifiez que la compétence est installée. -En dehors de cela, son rayon d'action est limité : elle écrit du code dans votre répertoire de travail et des fichiers d'événements là où vous lui indiquez. Elle ne lit rien de votre déploiement et n'y change rien. +Par ailleurs, son rayon d'action est limité : il écrit du code dans votre répertoire de travail et des fichiers d'événements là où vous le lui indiquez. Il ne lit rien de votre déploiement et n'y change rien. -## Étapes suivantes +## Prochaines étapes - **[SDK Python](/fr/agenteye/python-sdk)** : la référence complète des événements — chaque type d'événement et chaque champ — derrière ce que cette compétence automatise. -- **[Sessions](/fr/agenteye/sessions)** : ce que produit votre instrumentation une fois les événements reçus. -- **[Agent Skill Evaluator](/fr/agenteye/evaluator-skill)** : l'étape suivante une fois que les exécutions arrivent — les noter. -- **[Agent Skill CLI](/fr/agenteye/cli-skill)** : relire votre télémétrie. \ No newline at end of file +- **[Sessions](/fr/agenteye/sessions)** : ce que produit votre instrumentation une fois les événements arrivés. +- **[Compétence d'agent Évaluateur](/fr/agenteye/evaluator-skill)** : la prochaine étape une fois que les exécutions arrivent — les noter. +- **[Compétence d'agent CLI](/fr/agenteye/cli-skill)** : relire votre télémétrie. \ No newline at end of file diff --git a/docs/fr/agenteye/python-sdk.mdx b/docs/fr/agenteye/python-sdk.mdx index e94062ea..77d882d8 100644 --- a/docs/fr/agenteye/python-sdk.mdx +++ b/docs/fr/agenteye/python-sdk.mdx @@ -4,9 +4,9 @@ description: "Observez exactement ce que vos agents IA ont fait en production : --- -Observez exactement ce que vos agents IA ont fait en production : chaque exécution d'agent, appel d'outil, requête de modèle, hook et intervention humaine. Le SDK Python d'observabilité Failproof AI enregistre cette trace depuis l'intérieur de votre code d'agent afin que vous puissiez déboguer, auditer et évaluer ce qui s'est passé. Utilisez-le chaque fois que vous souhaitez que Failproof AI Observability observe vos agents. +Observez exactement ce que vos agents IA ont fait en production : chaque exécution d'agent, appel d'outil, requête de modèle, hook et intervention humaine. Le SDK Python d'observabilité Failproof AI enregistre cette trace depuis l'intérieur de votre code d'agent, afin que vous puissiez déboguer, auditer et évaluer ce qui s'est passé. Utilisez-le dès que vous souhaitez que Failproof AI Observability surveille vos agents. -En coulisses, le SDK écrit des événements structurés dans des fichiers JSONL locaux, et le daemon collecteur les récupère et les envoie automatiquement vers la plateforme. Vous n'avez pas à gérer ces fichiers vous-même. +En coulisses, le SDK écrit des événements structurés dans des fichiers JSONL locaux, et le démon collecteur les récupère puis les envoie automatiquement vers la plateforme. Vous n'avez pas à gérer ces fichiers vous-même. > **Conseil :** Vous découvrez Failproof AI Observability ? Cette page est la référence complète des événements du SDK. @@ -18,15 +18,15 @@ En coulisses, le SDK écrit des événements structurés dans des fichiers JSONL ## Installation -Le SDK est distribué aux clients sous forme de wheel privé plutôt que depuis un index de paquets public. Votre processus d'intégration explique comment l'obtenir, l'installer et le figer — contactez votre interlocuteur Failproof AI si vous avez besoin d'un accès. +Le SDK est distribué aux clients sous forme de wheel privé plutôt que depuis un index de paquets public. Votre processus d'intégration couvre la manière de l'obtenir, de l'installer et de le fixer à une version — contactez votre interlocuteur Failproof AI si vous avez besoin d'un accès. -Une fois installé, vérifiez qu'il est bien présent : +Une fois installé, vérifiez que vous l'avez bien : ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Vous préférez laisser un agent de codage gérer toute l'intégration ? Le [Python SDK Agent Skill](/fr/agenteye/python-sdk-skill) connaît le chemin d'installation, planifie les points d'instrumentation, les implémente et vérifie que les événements arrivent bien. +Vous préférez laisser un agent de codage gérer toute l'intégration ? Le [Python SDK Agent Skill](/fr/agenteye/python-sdk-skill) connaît le chemin d'installation, planifie les points d'instrumentation, les écrit et vérifie que les événements arrivent bien. --- @@ -58,9 +58,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### Instrumenter un appel réel +### Instrumenter un vrai appel -En pratique, vous enveloppez votre code d'agent existant. Encadrez un appel de modèle avec `model_request` avant et `model_response` après, afin que les deux événements couvrent la requête réelle et que Failproof AI Observability puisse les associer : +En pratique, vous encapsulez votre code d'agent existant. Entourez un appel de modèle avec `model_request` avant et `model_response` après, de sorte que les deux événements couvrent la requête réelle et que Failproof AI Observability puisse les associer : ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Enveloppez les appels d'outils de la même manière avec `tool_use` et `tool_result`, en réutilisant le même `tool_call_id` pour les deux. +Encapsulez les appels d'outils de la même façon avec `tool_use` et `tool_result`, en réutilisant le même `tool_call_id` pour la paire. -Voici à quoi ressemblent ces événements une fois qu'ils arrivent dans le tableau de bord, codés par couleur selon leur type et filtrables par environnement, agent et session : +Voici à quoi ressemblent ces événements une fois qu'ils atteignent le tableau de bord, avec un code couleur par type et des filtres par environnement, agent et session : -![Le flux d'événements en direct, codé par couleur selon le type d'événement et filtrable par environnement, agent et session](/agenteye/images/events-stream.png) +![Le flux d'événements en direct, avec un code couleur par type d'événement et des filtres par environnement, agent et session](/agenteye/images/events-stream.png) --- @@ -113,18 +113,18 @@ agenteye.configure( ) ``` -Appelez cette fonction une seule fois avant tout appel `event.*`. Vous pouvez l'omettre en toute sécurité ; les valeurs par défaut fonctionnent directement. Tous les arguments sont uniquement nommés ; passez-les par nom comme indiqué ci-dessus. +À appeler une seule fois avant tout appel `event.*`. Sans danger à omettre ; les valeurs par défaut fonctionnent immédiatement. Tous les arguments sont nommés uniquement (keyword-only) ; passez-les par leur nom comme indiqué ci-dessus. Lorsque `base_dir` vaut `None` (valeur par défaut), le SDK lit `$AGENTEYE_HOME` s'il est défini, -sinon il utilise `~/.agenteye`. Ce comportement correspond à la résolution propre du collecteur, -ainsi une seule variable d'environnement `AGENTEYE_HOME` configure le spool d'événements partagé pour le -SDK et le collecteur. +sinon il revient à `~/.agenteye`. Cela correspond à la résolution propre du collecteur, +de sorte qu'une seule variable d'environnement `AGENTEYE_HOME` configure la file d'attente +d'événements partagée entre le SDK et le collecteur. --- ## Environnement -Associez chaque événement à un environnement de déploiement (`production`, `staging`, `qa`, `canary`, etc.). Définissez-le une seule fois ; le SDK l'attache automatiquement à chaque événement. +Étiquetez chaque événement avec un environnement de déploiement (`production`, `staging`, `qa`, `canary`, etc.). Définissez-le une fois ; le SDK l'attache automatiquement à chaque événement. **Option 1 : via `configure()` :** @@ -142,29 +142,29 @@ export AGENTEYE_ENVIRONMENT=production La valeur d'environnement apparaît comme filtre de premier niveau dans le tableau de bord et est stockée sur le serveur pour des requêtes rapides. -> **Avertissement :** Les valeurs d'environnement ne doivent pas contenir de virgule `,` littérale. Les filtres du tableau de bord utilisent une sélection multiple séparée par des virgules sur le réseau (`?environment=prod,staging`), donc un environnement nommé `prod,blue` serait divisé en deux valeurs. Les événements dont l'environnement contient une virgule sont rejetés lors de l'ingestion. +> **Avertissement :** Les valeurs d'environnement ne doivent pas contenir de virgule `,` littérale. Les filtres du tableau de bord utilisent une sélection multiple séparée par des virgules dans l'URL (`?environment=prod,staging`), donc un environnement nommé `prod,blue` serait divisé en deux valeurs. Les événements dont l'environnement contient des virgules sont rejetés lors de l'ingestion. --- ## Données et confidentialité -Le SDK n'enregistre que les champs que vous passez explicitement. Les prompts, messages, entrées et sorties d'outils ainsi que le contenu des modèles sont capturés uniquement parce que vous les transmettez à un appel `event.*`. Rien n'est lu depuis votre processus ni capturé implicitement. Tout champ que vous ne définissez pas est omis de l'événement ; il n'est pas écrit sur le disque. +Le SDK n'enregistre que les champs que vous passez explicitement. Les prompts, messages, entrées et sorties d'outils, ainsi que le contenu des modèles, ne sont capturés que parce que vous les transmettez à un appel `event.*`. Rien n'est lu depuis votre processus ni capturé implicitement. Tout champ que vous laissez non défini est omis de l'événement ; il n'est pas écrit sur le disque. -La suppression des données sensibles est donc votre choix et votre responsabilité. Si un prompt ou une charge utile d'outil contient des données personnelles ou des secrets que vous préférez ne pas stocker, masquez-les ou supprimez-les avant de les passer à la méthode d'événement. +La rédaction est donc votre choix et votre responsabilité. Si un prompt ou une charge utile d'outil contient des données personnelles (PII) ou des secrets que vous préférez ne pas stocker, masquez-les ou supprimez-les avant de les passer à la méthode d'événement. --- ## Référence des événements -La plupart des événements viennent par paires début/fin partageant un identifiant de corrélation : `tool_use` et `tool_result` partagent un `tool_call_id`, `hook_triggered` et `hook_completed` partagent un `hook_id`, et `human_wait` et `human_input` partagent un `input_id`. Émettez l'événement de début, effectuez le travail, puis émettez l'événement de fin avec le même identifiant. Failproof AI Observability associe la paire et calcule `duration_ms` pour vous, vous n'avez donc jamais à passer `duration_ms` vous-même. +La plupart des événements viennent par paires début/fin qui partagent un identifiant de corrélation : `tool_use` et `tool_result` partagent un `tool_call_id`, `hook_triggered` et `hook_completed` partagent un `hook_id`, et `human_wait` et `human_input` partagent un `input_id`. Émettez l'événement de début, effectuez le travail, puis émettez l'événement de fin avec le même identifiant. Failproof AI Observability associe la paire et calcule automatiquement `duration_ms` pour vous, vous n'avez donc jamais à le passer vous-même. -![Le graphe d'exécution de style git d'une session à côté de sa chronologie d'événements, reconstruit à partir des événements associés, avec le panneau de répartition outil/modèle/hook](/agenteye/images/session-detail.png) +![Le graphe d'exécution d'une session de style git à côté de sa chronologie d'événements, reconstruit à partir des événements appariés, avec le panneau de répartition outil/modèle/hook](/agenteye/images/session-detail.png) Toutes les méthodes d'événement requièrent ces deux champs : | Champ | Type | Description | |---|---|---| -| `session_id` | `str` | Identifie l'exécution de l'agent de niveau supérieur | +| `session_id` | `str` | Identifie l'exécution d'agent de niveau supérieur | | `agent_id` | `str` | Identifie quel agent dans la session a émis l'événement | Toutes les méthodes acceptent également des `**kwargs` arbitraires pour des métadonnées personnalisées (voir [Champs personnalisés](#custom-fields)). @@ -173,7 +173,7 @@ Toutes les méthodes acceptent également des `**kwargs` arbitraires pour des m ### `event.agent_start()` -Émis lorsqu'un agent commence à travailler. +Émis lorsqu'un agent commence son travail. ```python agenteye.event.agent_start( @@ -219,7 +219,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -Émis lorsqu'un outil retourne un résultat. Corrélé avec `tool_use` via `tool_call_id`. +Émis lorsqu'un outil retourne un résultat. Corrèle avec `tool_use` via `tool_call_id`. ```python agenteye.event.tool_result( @@ -237,7 +237,7 @@ agenteye.event.tool_result( ### `event.model_request()` -Émis juste avant l'envoi d'un prompt à un LLM. +Émis juste avant d'envoyer un prompt à un LLM. ```python agenteye.event.model_request( @@ -254,7 +254,7 @@ agenteye.event.model_request( ) ``` -Les entrées de `messages` acceptent soit une `content` sous forme de chaîne simple, soit une `content` sous forme de liste de blocs de style Anthropic. Les paramètres d'échantillonnage (`temperature`, `max_tokens`, etc.) peuvent être passés en tant que kwargs supplémentaires. +Les entrées de `messages` acceptent soit un `content` en chaîne simple, soit un `content` sous forme de liste de blocs de style Anthropic. Les paramètres d'échantillonnage (`temperature`, `max_tokens`, etc.) peuvent être passés comme kwargs supplémentaires. --- @@ -277,7 +277,7 @@ agenteye.event.model_response( ) ``` -`content` accepte soit une chaîne simple (fournisseurs génériques) soit une liste de blocs de contenu de style Anthropic. Les appels d'outils se trouvent dans `content` sous forme de blocs `{"type": "tool_use", ...}`, sans champ `tool_calls` séparé. +`content` accepte soit une chaîne simple (fournisseurs génériques), soit une liste de blocs de contenu de style Anthropic. Les appels d'outils se trouvent dans `content` sous forme de blocs `{"type": "tool_use", ...}`, sans champ `tool_calls` séparé. --- @@ -300,7 +300,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Émis lorsqu'un hook se termine. Corrélé avec `hook_triggered` via `hook_id`. +Émis lorsqu'un hook se termine. Corrèle avec `hook_triggered` via `hook_id`. ```python agenteye.event.hook_completed( @@ -333,13 +333,13 @@ agenteye.event.error( --- -## Événements Human-in-the-Loop +## Événements humain dans la boucle -Les événements human-in-the-loop vous donnent une visibilité sur les moments où une personne intervient dans l'exécution de l'agent (attente d'approbation, saisie d'informations, mise en pause ou arrêt de l'agent). Ils vous permettent de mesurer le temps que prennent les humains pour répondre (le SDK calcule automatiquement `duration_ms` sur les événements associés), d'auditer qui a mis en pause ou interrompu un agent, et de construire des workflows d'approbation et de supervision qui apparaissent dans le tableau de bord. +Les événements humain dans la boucle vous donnent une visibilité sur les moments où une personne intervient dans l'exécution de l'agent (attente d'approbation, fourniture d'une entrée, mise en pause ou arrêt de l'agent). Ils vous permettent de mesurer le temps que les humains mettent à répondre (le SDK calcule automatiquement `duration_ms` sur les événements appariés), d'auditer qui a mis en pause ou interrompu un agent, et de construire des workflows d'approbation et de supervision qui s'affichent dans le tableau de bord. ### `event.human_wait()` -Émis lorsque l'agent suspend son exécution pour attendre qu'un humain fournisse une entrée. À associer avec `human_input` ; le SDK calcule automatiquement `duration_ms` (le temps que l'humain a mis pour répondre). +Émis lorsque l'agent met en pause son exécution pour attendre qu'un humain fournisse une entrée. À associer avec `human_input` ; le SDK calcule automatiquement `duration_ms` (le temps que l'humain a mis à répondre). ```python agenteye.event.human_wait( @@ -354,7 +354,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Émis lorsqu'un humain fournit une entrée et que l'agent reprend. Corrélé avec `human_wait` via `input_id`. `duration_ms` est calculé automatiquement et ne doit pas être passé par l'appelant. +Émis lorsqu'un humain fournit une entrée et que l'agent reprend son exécution. Corrèle avec `human_wait` via `input_id`. `duration_ms` est calculé automatiquement et ne doit pas être passé par l'appelant. ```python agenteye.event.human_input( @@ -368,7 +368,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Émis lorsqu'un humain met activement l'agent en pause (par exemple via un contrôle du tableau de bord). L'agent est suspendu mais pas terminé. +Émis lorsqu'un humain met activement l'agent en pause (par exemple via un contrôle du tableau de bord). L'agent est suspendu mais pas arrêté. ```python agenteye.event.human_pause( @@ -412,13 +412,13 @@ agenteye.event.tool_use( `timestamp`, `type` et `environment` sont réservés et lèvent une `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) s'ils sont passés comme champs personnalisés. `session_id` et `agent_id` sont des paramètres obligatoires sur chaque méthode d'événement et ne peuvent pas être fournis une seconde fois ; Python lève une `TypeError` si vous le faites. Définissez l'environnement avec `configure(environment=...)` (ou la variable `AGENTEYE_ENVIRONMENT`) à la place. -Conservez les charges utiles en JSON structuré lorsque vous souhaitez interroger leurs champs. Les valeurs que JSON ne prend pas nativement en charge — telles que les datetimes, UUIDs, décimales, ensembles, bytes ou objets de modèle — sont converties en chaînes afin que l'enregistrement se poursuive en toute sécurité. +Conservez les charges utiles en JSON structuré lorsque vous souhaitez interroger leurs champs. Les valeurs que JSON ne supporte pas nativement — telles que les datetimes, UUIDs, décimaux, ensembles, bytes ou objets modèles — sont converties en chaînes afin que l'enregistrement se poursuive en toute sécurité. --- ## Comment les événements sont écrits -Les événements sont mis en mémoire tampon dans le processus et vidés sur le disque toutes les `flush_interval` secondes (par défaut 500 ms). Chaque vidage écrit un fichier JSONL : +Les événements sont mis en mémoire tampon dans le processus et vidés sur le disque toutes les `flush_interval` secondes (500 ms par défaut). Chaque vidage écrit un fichier JSONL : ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl @@ -426,11 +426,11 @@ Les événements sont mis en mémoire tampon dans le processus et vidés sur le Le collecteur surveille ce répertoire et télécharge les fichiers automatiquement. Vous n'avez pas besoin de gérer ces fichiers directement. -Chaque fichier est écrit de manière atomique : le SDK écrit dans un fichier temporaire puis le renomme à sa place définitive, ainsi le collecteur ne voit jamais un fichier partiellement écrit. Un vidage final est également effectué à la fermeture de votre processus, afin que les événements mis en mémoire tampon lors du dernier intervalle ne soient pas perdus. Si le collecteur est hors ligne, les événements s'accumulent simplement sous forme de fichiers sur le disque et sont envoyés dès qu'il revient en ligne. +Chaque fichier est écrit de manière atomique : le SDK écrit dans un fichier temporaire puis le renomme à sa place définitive, de sorte que le collecteur ne voit jamais un fichier à moitié écrit. Un vidage final est également exécuté à la fermeture de votre processus, afin que les événements mis en mémoire tampon dans le dernier intervalle ne soient pas perdus. Si le collecteur est hors ligne, les événements s'accumulent simplement sous forme de fichiers sur le disque et sont envoyés dès qu'il revient. --- -## Étapes suivantes +## Prochaines étapes -- [Flux d'événements](/fr/agenteye/event-stream) : regardez ces événements arriver en direct, codés par couleur et filtrables par environnement, agent et session. -- [Sessions](/fr/agenteye/sessions) : découvrez comment les événements associés reconstituent chaque exécution d'agent sous forme de graphe d'exécution et de chronologie. \ No newline at end of file +- [Flux d'événements](/fr/agenteye/event-stream) : regardez ces événements arriver en direct, avec un code couleur et des filtres par environnement, agent et session. +- [Sessions](/fr/agenteye/sessions) : découvrez comment les événements appariés reconstituent chaque exécution d'agent sous forme de graphe d'exécution et de chronologie. \ No newline at end of file diff --git a/docs/fr/agenteye/queries.mdx b/docs/fr/agenteye/queries.mdx index 903c50f3..e9193102 100644 --- a/docs/fr/agenteye/queries.mdx +++ b/docs/fr/agenteye/queries.mdx @@ -1,56 +1,56 @@ --- title: "Requêtes" -description: "Posez n'importe quelle question sur les données de vos agents et obtenez une réponse en quelques secondes." +description: "Posez n'importe quelle question sur les données de votre agent et obtenez une réponse en quelques secondes." --- -Posez n'importe quelle question sur les données de vos agents et obtenez une réponse en quelques secondes. Failproof AI Observability vous propose une bibliothèque de requêtes sauvegardées, prêtes à l'emploi, sur vos événements et évaluations — vous partez ainsi d'un exemple fonctionnel plutôt que d'un éditeur SQL vide. +Posez n'importe quelle question sur les données de votre agent et obtenez une réponse en quelques secondes. Failproof AI Observability met à votre disposition une bibliothèque de requêtes enregistrées, prêtes à l'emploi, portant sur vos événements et évaluations — vous partez ainsi d'un exemple fonctionnel plutôt que d'un éditeur SQL vide. -![La bibliothèque de requêtes sauvegardées : une grille de requêtes réutilisables, qu'il s'agisse de préréglages intégrés ou de requêtes personnalisées](/agenteye/images/queries.png) +![La bibliothèque de requêtes enregistrées : une grille de requêtes réutilisables, à la fois des préréglages intégrés et des requêtes personnalisées](/agenteye/images/queries.png) -*Votre bibliothèque de requêtes sauvegardées à l'adresse `//queries` : les préréglages intégrés côtoient les requêtes enregistrées par votre équipe.* +*Votre bibliothèque de requêtes enregistrées accessible à `//queries` : des préréglages intégrés côte à côte avec les requêtes que votre équipe a sauvegardées.* -## Commencez par un préréglage, pas une page blanche +## Partez d'un préréglage, pas d'une page blanche -Inutile de vous souvenir des noms de tables ou d'écrire du SQL de zéro. La bibliothèque s'ouvre avec des préréglages intégrés répondant aux questions les plus fréquentes des équipes, directement accessibles aux côtés des requêtes que votre propre équipe a sauvegardées et nommées. Choisissez celle qui se rapproche le plus de ce que vous cherchez et vous êtes déjà à mi-chemin de la réponse. +Inutile de mémoriser les noms de tables ou d'écrire du SQL de zéro. La bibliothèque s'ouvre avec des préréglages intégrés couvrant les questions les plus fréquentes, disposés juste à côté des requêtes que votre équipe a enregistrées et nommées. Choisissez celle qui correspond le mieux à votre besoin et vous êtes déjà presque à destination. -Chaque requête sauvegardée est partagée au niveau de l'organisation, de sorte que les requêtes utiles créées par vos collègues deviennent également les vôtres. Nommez une requête et donnez-lui une description une seule fois, et n'importe quel membre de votre organisation pourra la retrouver, l'exécuter ou épingler ses résultats sur un tableau de bord ultérieurement. +Chaque requête enregistrée est partagée au niveau de l'organisation : les requêtes utiles rédigées par vos collègues deviennent automatiquement accessibles à tous. Nommez une requête, ajoutez-lui une description une seule fois, et n'importe quel membre de votre organisation pourra la retrouver, l'exécuter ou épingler ses résultats sur un tableau de bord ultérieurement. -Accédez-y à l'adresse `//queries`. +Accédez-y via `//queries`. -## Ajustez et exécutez dans le compositeur SQL +## Modifiez et exécutez dans le compositeur SQL -Ouvrez n'importe quelle requête et elle s'affiche dans le compositeur SQL, où vous pouvez la modifier et obtenir la réponse immédiatement : sans export, sans aller-retour, sans attendre quelqu'un d'autre. +Ouvrez n'importe quelle requête et elle s'affiche dans le compositeur SQL, où vous pouvez l'ajuster et consulter la réponse immédiatement : pas d'export, pas d'aller-retour, pas d'attente. -![Le compositeur de requêtes SQL exécutant une requête sauvegardée, avec un panneau latéral de schéma et une grille de résultats en direct](/agenteye/images/query-lab.png) +![Le compositeur de requêtes SQL exécutant une requête enregistrée, avec une barre latérale de schéma et une grille de résultats en direct](/agenteye/images/query-lab.png) -*Le compositeur SQL : votre requête à gauche, un panneau latéral de schéma pour ne jamais avoir à deviner un nom de colonne, et une grille de résultats en direct en dessous.* +*Le compositeur SQL : votre requête à gauche, une barre latérale de schéma pour ne jamais deviner un nom de colonne, et une grille de résultats en direct en dessous.* -- **Un panneau latéral de schéma** présente les tables d'analytique et leurs colonnes, vous permettant de construire une requête sans chercher les noms de champs. -- **Une grille de résultats en direct** retourne les lignes dès l'exécution, vous permettant d'itérer en quelques secondes plutôt que de tâtonner. -- **Conception en lecture seule.** Les requêtes s'exécutent sur votre entrepôt d'événements et sont validées côté serveur : seules les instructions `SELECT` et `WITH` sont autorisées, avec un délai d'expiration et une limite de lignes. Une requête exploratoire ne peut jamais modifier vos données, et une requête incontrôlée est automatiquement interrompue. +- **Une barre latérale de schéma** présente les tables analytiques et leurs colonnes, afin que vous puissiez construire une requête sans chercher les noms de champs. +- **Une grille de résultats en direct** affiche les lignes dès l'exécution, pour itérer en quelques secondes plutôt que de tâtonner indéfiniment. +- **Lecture seule par conception.** Les requêtes s'exécutent sur votre magasin d'événements et sont validées côté serveur : seules les instructions `SELECT` et `WITH` sont autorisées, avec un délai d'expiration et un plafond sur le nombre de lignes. Une requête exploratoire ne peut jamais modifier vos données, et une requête incontrôlée est arrêtée automatiquement. -Satisfait du résultat ? Sauvegardez-le dans la bibliothèque pour que toute l'équipe en profite, ou épinglez sa sortie sur un tableau de bord sous forme de tuile en courbe, barres, aires ou secteurs. +Satisfait du résultat ? Enregistrez-le dans la bibliothèque pour que toute l'équipe en bénéficie, ou épinglez sa sortie sur un tableau de bord sous forme de vignette en courbe, barres, aires ou camembert. -## Exécutez-les depuis le terminal ou laissez l'assistant les écrire +## Exécutez-les depuis le terminal, ou laissez l'assistant les rédiger -Les mêmes requêtes sauvegardées vous suivent où que vous travailliez : +Les mêmes requêtes enregistrées vous suivent où que vous travailliez : -- **Depuis le terminal.** La CLI `agenteye` liste, exécute et sauvegarde exactement les mêmes requêtes, vous permettant d'intégrer un résultat dans un script, de le brancher sur la CI ou de le transmettre à un agent de codage. +- **Depuis le terminal.** La CLI `agenteye` liste, exécute et enregistre exactement les mêmes requêtes, ce qui vous permet d'injecter un résultat dans un script, de l'intégrer à la CI ou de le transmettre à un agent de développement. ```bash -agenteye query list # les mêmes requêtes sauvegardées, depuis votre terminal -agenteye query run errs --arg prod # exécutez-en une et affichez les lignes (ajoutez --json pour la rediriger) +agenteye query list # the same saved queries, from your terminal +agenteye query run errs --arg prod # run one and print the rows (add --json to pipe it) ``` - Consultez [CLI and agents](/fr/agenteye/cli-and-agents) pour l'ensemble complet des commandes. + Consultez [CLI and agents](/fr/agenteye/cli-and-agents) pour la liste complète des commandes. -- **Depuis l'assistant IA.** Vous ne savez pas comment formuler le SQL ? Demandez à l'[assistant IA](/fr/agenteye/assistant) intégré au tableau de bord en langage naturel — il rédigera la requête et la sauvegardera dans votre bibliothèque. +- **Depuis l'assistant IA.** Vous ne savez pas comment formuler le SQL ? Posez la question à l'[assistant IA](/fr/agenteye/assistant) intégré au tableau de bord en français simple, et il rédigera la requête et l'enregistrera dans votre bibliothèque à votre place. -L'exécution d'une requête sauvegardée est contrôlée par la permission `queries:run`, distincte des permissions de création ou de suppression de requêtes, ce qui vous permet d'accorder un accès en lecture sans laisser tout le monde réécrire la bibliothèque. +L'exécution d'une requête enregistrée est conditionnée par la permission `queries:run`, distincte des permissions de création ou de suppression, ce qui vous permet d'accorder un accès en lecture sans autoriser tout le monde à réécrire la bibliothèque. ## Voir aussi - [Dashboards](/fr/agenteye/dashboards) : épinglez les résultats de requêtes dans des graphiques partagés à l'échelle de l'organisation. -- [AI assistant](/fr/agenteye/assistant) : posez vos questions en langage naturel et recevez une requête en retour. -- [CLI and agents](/fr/agenteye/cli-and-agents) : exécutez et sauvegardez les mêmes requêtes depuis votre terminal. \ No newline at end of file +- [AI assistant](/fr/agenteye/assistant) : posez vos questions en langage naturel et obtenez une requête en retour. +- [CLI and agents](/fr/agenteye/cli-and-agents) : exécutez et enregistrez les mêmes requêtes depuis votre terminal. \ No newline at end of file diff --git a/docs/fr/agenteye/security.mdx b/docs/fr/agenteye/security.mdx index 4b1954c1..fae31f5d 100644 --- a/docs/fr/agenteye/security.mdx +++ b/docs/fr/agenteye/security.mdx @@ -1,68 +1,68 @@ --- title: "Sécurité" -description: "Failproof AI Observability est conçu pour fonctionner au plus près de vos agents en production, ce qui signifie qu'il voit vos prompts, les entrées des outils et leurs sorties." +description: "Failproof AI Observability est conçu pour s'intégrer au plus près de vos agents en production, ce qui signifie qu'il accède à vos prompts, aux entrées des outils et à leurs sorties." --- -Failproof AI Observability est conçu pour fonctionner au plus près de vos agents en production, ce qui signifie qu'il voit vos prompts, les entrées des outils et leurs sorties. Cette page explique comment vos données restent isolées, contrôlées et entre vos mains. Si vous évaluez Failproof AI Observability dans le cadre d'une revue de sécurité, commencez ici. +Failproof AI Observability est conçu pour s'intégrer au plus près de vos agents en production, ce qui signifie qu'il accède à vos prompts, aux entrées des outils et à leurs sorties. Cette page explique comment ces données sont isolées, contrôlées et restent entre vos mains. Si vous évaluez Failproof AI Observability dans le cadre d'un audit de sécurité, commencez ici. --- ## Vos données restent dans votre environnement -Failproof AI Observability est auto-hébergé. Les événements, prompts, réponses des modèles et analyses sont stockés dans vos propres bases de données, dans votre propre environnement. Rien n'est envoyé à un service SaaS tiers pour y être stocké, et vos données demeurent dans votre propre compte cloud. +Failproof AI Observability est auto-hébergé. Les événements, prompts, réponses des modèles et analyses sont stockés dans vos propres bases de données, dans votre propre environnement. Aucune donnée n'est transmise à un service SaaS tiers pour y être stockée — tout reste dans votre compte cloud. --- ## Isolation des locataires -Une instance Failproof AI Observability peut héberger plusieurs organisations, chacune étant isolée au niveau de la couche de stockage — appliqué par la base de données elle-même, et pas seulement par l'interface : +Une instance Failproof AI Observability peut héberger plusieurs organisations, chacune étant isolée au niveau de la couche de stockage — appliqué par la base de données elle-même, et pas uniquement par l'interface : -- Les données opérationnelles d'une organisation (utilisateurs, clés, tableaux de bord, requêtes sauvegardées) sont limitées à cette organisation, et les lectures inter-organisations sont bloquées par la base de données elle-même. -- Chaque événement ingéré est marqué avec l'organisation à laquelle il appartient, de sorte qu'une organisation ne peut jamais lire les événements d'une autre. +- Les données opérationnelles d'une organisation (utilisateurs, clés, tableaux de bord, requêtes sauvegardées) sont cloisonnées à cette organisation ; les lectures inter-organisations sont bloquées directement par la base de données. +- Chaque événement ingéré est marqué avec l'organisation propriétaire, de sorte qu'une organisation ne peut jamais lire les événements d'une autre. -Chaque route de tableau de bord est délimitée sous un slug d'organisation (`//…`). +Chaque route de tableau de bord est délimitée par un slug d'organisation (`//…`). --- ## Connexion -Failproof AI Observability utilise une connexion sans mot de passe, par e-mail. Il n'y a pas de mot de passe à hameçonner ou à divulguer. Un utilisateur demande un code à usage unique (ou un lien magique en un clic), qui lui est envoyé par e-mail et expire rapidement. La connexion est contrôlée par une **liste d'autorisation** : seules les adresses e-mail (ou domaines) que vous autorisez peuvent s'authentifier. +Failproof AI Observability utilise une connexion sans mot de passe, par e-mail. Il n'y a aucun mot de passe à hameçonner ou à faire fuiter. L'utilisateur demande un code à usage unique (ou un lien magique en un clic), qui lui est envoyé par e-mail et expire rapidement. La connexion est contrôlée par une **liste d'autorisation** : seules les adresses e-mail (ou les domaines) que vous autorisez peuvent s'authentifier. ![L'écran de connexion de Failproof AI Observability, qui envoie un code à usage unique à votre adresse e-mail](/agenteye/images/login.png) --- -## Accès délimité avec des clés API +## Accès délimité avec les clés API -Chaque client s'authentifie avec une clé API dotée de permissions granulaires et à moindre privilège. Un collecteur n'a besoin que de `events:add` ; une clé de tableau de bord ou d'assistant peut être en lecture seule ; les actions destructives (suppression, regénération) sont des droits distincts que vous choisissez d'inclure. +Chaque client s'authentifie avec une clé API dotée de permissions granulaires selon le principe du moindre privilège. Un collecteur n'a besoin que de `events:add` ; une clé de tableau de bord ou d'assistant peut être en lecture seule ; les actions destructrices (suppression, régénération) sont des autorisations séparées que vous choisissez d'inclure ou non. -![La page des clés API : les permissions accordées à chaque clé, avec un code couleur par portée lecture, écriture et destructive](/agenteye/images/api-keys.png) +![La page des clés API : les permissions accordées à chaque clé sont codées par couleur selon leur portée lecture, écriture et destructrice](/agenteye/images/api-keys.png) -Conservez la clé d'amorçage administrateur pour la configuration, et créez des clés restreintes pour tout le reste. Voir [Clés API](/fr/agenteye/api-keys). +Conservez la clé d'administration initiale pour la configuration, et émettez des clés à portée restreinte pour tout le reste. Consultez [Clés API](/fr/agenteye/api-keys). --- -## Un assistant en lecture seule avec validation obligatoire +## Un assistant en lecture seule soumis à approbation L'[assistant IA](/fr/agenteye/assistant) intégré au tableau de bord répond à vos questions sur vos données, mais il est limité par conception : -- Il est **en lecture seule par défaut** : son SQL passe par un garde-fou qui n'autorise que les requêtes `SELECT`/`WITH`, à instruction unique, avec un plafond de lignes. -- Tout ce qu'il crée (une requête sauvegardée, un tableau de bord) est soumis à **validation** : vous examinez et approuvez chaque écriture avant qu'elle ne se produise. +- Il est **en lecture seule par défaut** : son SQL passe par un garde-fou qui n'autorise que les requêtes `SELECT`/`WITH`, en instruction unique, avec un plafond de lignes. +- Tout ce qu'il crée (une requête sauvegardée, un tableau de bord) est **soumis à approbation** : vous examinez et validez chaque écriture avant qu'elle ne soit effectuée. - Il **ne peut jamais supprimer**. -Ainsi, un membre de l'équipe peut demander « quels agents ont généré le plus d'erreurs cette semaine ? » et agir sur la réponse, sans que l'assistant puisse modifier ou supprimer vos données de son propre chef. +Ainsi, un membre de l'équipe peut demander « quels agents ont le plus généré d'erreurs cette semaine ? » et agir sur la réponse, sans que l'assistant puisse modifier ou supprimer vos données de son propre chef. --- ## En transit -Tout le trafic passe par HTTPS. Vous terminez le TLS avec vos propres certificats, de sorte que le trafic collecteur-vers-serveur et navigateur-vers-serveur est chiffré en transit. +Tout le trafic transite par HTTPS. Vous terminez le TLS avec vos propres certificats, de sorte que le trafic collecteur-serveur et navigateur-serveur est chiffré en transit. --- -## Étapes suivantes +## Prochaines étapes -- [Vue d'ensemble](/fr/agenteye/overview) : comment Failproof AI Observability s'articule. -- [Clés API](/fr/agenteye/api-keys) : délimitez l'accès pour le collecteur, le tableau de bord et l'assistant. +- [Vue d'ensemble](/fr/agenteye/overview) : comment s'articule Failproof AI Observability. +- [Clés API](/fr/agenteye/api-keys) : délimitez les accès pour le collecteur, le tableau de bord et l'assistant. - [Observabilité](/fr/agenteye/observability) : ce que Failproof AI Observability capture depuis vos agents. \ No newline at end of file diff --git a/docs/fr/agenteye/sessions.mdx b/docs/fr/agenteye/sessions.mdx index 918cf10c..b380a420 100644 --- a/docs/fr/agenteye/sessions.mdx +++ b/docs/fr/agenteye/sessions.mdx @@ -1,14 +1,14 @@ --- -title: "Sessions & Graphe d'Exécution" -description: "Chaque événement d'une exécution regroupé en une ligne lisible et représenté sous forme de graphe d'exécution à la git, compréhensible en quelques secondes." +title: "Sessions & Graphe d'exécution" +description: "Chaque événement d'une exécution, consolidé en une ligne lisible et représenté sous forme de graphe d'exécution à la git que vous pouvez lire en quelques secondes." --- -Fini les suppositions sur la cause d'un échec. L'observabilité Failproof AI regroupe chaque événement d'une exécution en une ligne lisible, puis représente l'ensemble sous forme d'un schéma à la git que vous pouvez déchiffrer en quelques secondes — vous voyez exactement ce que votre agent a fait, étape par étape. +Fini de chercher pourquoi une exécution a échoué. L'observabilité de Failproof AI consolide chaque événement d'une exécution en une ligne lisible, puis dessine l'ensemble de l'exécution sous forme de schéma à la git que vous pouvez parcourir en quelques secondes — vous voyez exactement ce que votre agent a fait, étape par étape. -![La liste des Sessions : une ligne par exécution, tous environnements et agents confondus, avec des pastilles de statut et des badges de score d'évaluation](/agenteye/images/sessions-list.png) +![La liste des sessions : une ligne par exécution, tous environnements et agents confondus, avec des indicateurs de statut et des badges de score d'évaluation](/agenteye/images/sessions-list.png) -*Une ligne par exécution : la pastille de statut vous indique en un coup d'œil comment s'est terminée l'exécution, et un badge de score apparaît dès qu'un évaluateur est connecté.* +*Une ligne par exécution : l'indicateur de statut vous indique en un coup d'œil comment l'exécution s'est terminée, et un badge de score apparaît dès qu'un évaluateur est connecté.*
@@ -18,40 +18,40 @@ Fini les suppositions sur la cause d'un échec. L'observabilité Failproof AI re --- -## Visualiser toutes les exécutions d'un coup d'œil +## Voir toutes les exécutions d'un coup d'œil Le journal brut des événements est la vérité de chaque étape, mais lorsque vous avez des milliers d'étapes réparties sur des dizaines d'exécutions, c'est l'exécution qui vous intéresse, pas l'étape. La page Sessions regroupe tous les événements d'une exécution en une seule ligne, transformant une journée d'activité en liste consultable plutôt qu'en flux ininterrompu. -Chaque ligne porte une pastille de statut : une exécution échouée se distingue d'une exécution réussie avant même que vous cliquiez. Filtrez par plage de dates, environnement, agent ou session pour passer de «tout» à «l'exécution qui m'intéresse» en quelques clics. +Chaque ligne porte un indicateur de statut, ce qui fait ressortir immédiatement une exécution échouée d'une exécution réussie, avant même de cliquer. Filtrez par plage de dates, environnement, agent ou session pour passer de « tout » à « l'exécution qui m'intéresse » en quelques clics. -Une fois un évaluateur connecté, chaque exécution terminée est automatiquement notée et son dernier score s'affiche sur la ligne sous forme de badge. Vous pouvez filtrer par n'importe quelle plage de scores, de sorte que «montrez-moi toutes les exécutions en production avec un faible score cette semaine» devient un simple filtre, non une revue manuelle. Tant qu'aucun évaluateur n'est configuré, les sessions capturent quand même l'intégralité de l'exécution — elles n'ont simplement pas encore de score. +Une fois un évaluateur connecté, chaque exécution terminée est scorée automatiquement et son dernier score s'affiche sur la ligne sous forme de badge. Vous pouvez filtrer par n'importe quelle plage de scores, ce qui fait de « montrez-moi toutes les exécutions de prod à faible score cette semaine » un simple filtre, et non une révision manuelle. Tant qu'aucun évaluateur n'est configuré, les sessions capturent quand même l'intégralité de l'exécution — elles ne portent simplement pas encore de score. --- -## Lire l'intégralité d'une exécution sous forme de schéma +## Lire toute l'exécution comme une image -![Le graphe d'exécution à la git d'une session à côté de sa chronologie d'événements, avec le panneau de détail des outils, modèles et hooks](/agenteye/images/session-detail.png) +![Le graphe d'exécution à la git d'une session, à côté de sa chronologie d'événements, avec le panneau de détail des outils, modèles et hooks](/agenteye/images/session-detail.png) -*Le graphe d'exécution (à gauche) se trouve à côté de la chronologie des événements ; le rail de droite détaille les outils, modèles, hooks et la consommation de tokens pour l'exécution.* +*Le graphe d'exécution (à gauche) est affiché à côté de la chronologie des événements ; le panneau de droite détaille les outils, modèles, hooks et la consommation de tokens pour l'exécution.* -Cliquez sur n'importe quelle session pour ouvrir son graphe d'exécution : une vue à la git montrant comment les agents, outils, hooks et appels de modèles se sont déroulés dans le temps. Les sous-agents parallèles s'embranchent chacun sur leur propre voie, vous permettant de voir quels travaux ont été exécutés en parallèle, quel sous-agent a bloqué et où l'exécution a déraillé — sans avoir à reconstituer mentalement un mur de logs. +Cliquez sur une session pour ouvrir son graphe d'exécution : une vue à la git montrant comment les agents, outils, hooks et appels de modèle se sont déroulés dans le temps. Chaque sous-agent parallèle se déploie sur sa propre voie, ce qui vous permet de voir quels travaux ont été exécutés en parallèle, quel sous-agent s'est bloqué, et où l'exécution a dévié — sans avoir à rejouer mentalement un mur de logs. -Le rail de droite vous offre la ventilation par exécution : quels outils et modèles ont été utilisés, quels hooks se sont déclenchés, et ce que l'exécution a consommé en tokens. C'est la réponse à «pourquoi cette exécution a-t-elle coûté si cher ?» ou «quel outil est le plus lent ?», placée juste à côté du graphe qui en est la cause. +Le panneau de droite vous donne le détail par exécution : quels outils et modèles ont été sollicités, quels hooks ont été déclenchés, et ce que l'exécution a consommé en tokens. C'est la réponse à « pourquoi cette exécution a-t-elle coûté autant ? » ou « quel est l'outil le plus lent ? », disponible directement à côté du graphe qui en est la cause. -Les événements individuels sont adressables, vous pouvez donc envoyer à quelqu'un un lien vers un moment précis plutôt que «la session, environ aux deux tiers». Copiez le lien depuis n'importe quel événement, ou suivez-en un depuis un constat d'[audit](/fr/agenteye/audits) ou une erreur, et la session s'ouvre avec cet événement sélectionné et visible à l'écran. Cela vaut aussi pour les exécutions très longues : la chronologie charge une fenêtre délimitée pour préserver les performances de votre navigateur, et un lien pointant au-delà de cette fenêtre retrouvera quand même son événement plutôt que de vous déposer au début. Si l'événement a dépassé votre fenêtre de rétention, la page vous l'indique explicitement au lieu de ne rien sélectionner silencieusement. +Les événements individuels sont adressables, ce qui vous permet de transmettre à quelqu'un un lien vers un moment précis plutôt que « la session, à peu près aux deux tiers ». Copiez le lien depuis n'importe quel événement, ou suivez-en un depuis un résultat d'[audit](/fr/agenteye/audits) ou une erreur — la session s'ouvre avec cet événement sélectionné et affiché à l'écran. Cela fonctionne même pour les exécutions très longues : la chronologie charge une fenêtre délimitée pour ménager votre navigateur, et un lien pointant au-delà de cette fenêtre retrouve quand même son événement plutôt que de vous déposer au début. Si l'événement a dépassé votre fenêtre de rétention, la page vous l'indique explicitement au lieu de ne rien sélectionner en silence. --- -## Comment y accéder +## Où le trouver -Chaque page du tableau de bord est limitée à votre organisation (`//…`). Sessions se trouve sous **Observe** dans la barre latérale gauche, à côté d'Events, avec les filtres de plage de dates, d'environnement, d'agent et de session en haut de la liste. Chaque ligne est à un clic de son graphe d'exécution complet. +Chaque page du tableau de bord est délimitée par votre organisation (`//…`). Sessions se trouve sous **Observe** dans la barre latérale gauche, à côté d'Events, avec les filtres de plage de dates, d'environnement, d'agent et de session en haut de la liste. Chaque ligne mène en un clic à son graphe d'exécution complet. Pour activer les badges de score et le filtrage par plage de scores, connectez un évaluateur : voir [Evaluations](/fr/agenteye/evaluations). --- -## En rapport +## Voir aussi -- [Event stream](/fr/agenteye/event-stream) : le journal brut, étape par étape, dont chaque session est le regroupement. +- [Flux d'événements](/fr/agenteye/event-stream) : le journal brut par étape à partir duquel chaque session est constituée. - [Evaluations](/fr/agenteye/evaluations) : connectez un évaluateur pour que chaque exécution reçoive un badge de score filtrable. -- [Telemetry](/fr/agenteye/telemetry) : comment les exécutions transitent de votre agent vers ces sessions. \ No newline at end of file +- [Telemetry](/fr/agenteye/telemetry) : comment les exécutions passent de votre agent à ces sessions. \ No newline at end of file diff --git a/docs/fr/agenteye/telemetry.mdx b/docs/fr/agenteye/telemetry.mdx index fa47768e..5b536e2e 100644 --- a/docs/fr/agenteye/telemetry.mdx +++ b/docs/fr/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- title: "Métriques de performance" -description: "Détectez à l'instant précis où vos modèles, outils ou hooks ralentissent ou font grimper la facture, et interceptez un pic de latence en queue de distribution avant que vos utilisateurs ne le ressentent." +description: "Détectez à l'instant précis où vos modèles, outils ou hooks ralentissent ou font grimper la facture, et repérez un pic de latence en queue avant que vos utilisateurs ne le ressentent." --- -Détectez à l'instant précis où vos modèles, outils ou hooks ralentissent ou font grimper la facture, et interceptez un pic de latence en queue de distribution avant que vos utilisateurs ne le ressentent. Trois pages dédiées transforment les mesures brutes en p50, p95 et p99 lisibles en un coup d'œil. +Détectez à l'instant précis où vos modèles, outils ou hooks ralentissent ou font grimper la facture, et repérez un pic de latence en queue avant que vos utilisateurs ne le ressentent. Trois pages dédiées transforment les mesures brutes en p50, p95 et p99 lisibles d'un coup d'œil. -![La page Models affichant une carte de chaleur de latence, une bande de percentiles et des chiffres de tokens, coût et fenêtre de contexte par modèle](/agenteye/images/models.png) -*La page Models : une carte de chaleur de latence, une bande de percentiles et, par modèle, le nombre de tokens, le coût estimé et le remplissage de la fenêtre de contexte.* +![La page Modèles affichant une carte thermique de latence, une bande de percentiles, et les chiffres de tokens, coût et fenêtre de contexte par modèle](/agenteye/images/models.png) +*La page Modèles : une carte thermique de latence, une bande de percentiles, et par modèle les tokens, le coût estimé et le remplissage de la fenêtre de contexte.* ## Arrêtez de laisser les moyennes masquer vos pires exécutions -Un chiffre de latence moyenne est rassurant et inutile : il lisse le seul appel sur cinquante qui bloque et réveille votre équipe d'astreinte à 2h du matin. Les pages Models, Tools et Hooks refusent de faire ça. Chacune partage la même structure, à apprendre une seule fois : +Un chiffre de latence moyenne est rassurant et inutile : il lisse le seul appel sur cinquante qui se bloque et réveille votre on-call à 2h du matin. Les pages Modèles, Outils et Hooks refusent de faire ça. Chacune partage la même structure, que vous apprenez une seule fois : -- Un **sparkline à 24 bins** pour saisir la tendance d'un coup d'œil : la situation empire-t-elle ? -- Une **bande de métriques vitales** avec les latences p50, p95 et p99, pour voir côte à côte l'exécution typique et la queue de distribution. -- Une **carte de chaleur de latence**, 24 intervalles temporels croisés avec des buckets de latence, qui indique *quand* les appels lents se sont concentrés. -- Une **bande de percentiles** : une ligne p50 avec des rubans ombrés p25–p75 et p10–p90, et des points p99, afin que l'écart reste visible plutôt que noyé dans une moyenne. +- Un **sparkline à 24 tranches** pour observer la tendance d'un coup d'œil : est-ce que ça empire ? +- Une **bande de métriques vitales** avec les latences p50, p95 et p99, afin que l'exécution typique et la queue soient côte à côte. +- Une **carte thermique de latence**, 24 tranches temporelles par plages de latence, qui montre *quand* les appels lents se sont regroupés. +- Une **bande de percentiles** : une ligne p50 avec des rubans ombrés de p25 à p75 et de p10 à p90, et des points p99, de sorte que l'étalement reste visible plutôt que lissé. -Un réticule de survol partagé relie la carte de chaleur et la bande, de sorte qu'un pic en queue de distribution s'aligne dans le temps sur les deux vues plutôt que de se cacher derrière une unique ligne de moyenne. Retrouvez ces trois pages dans la section **observe** de votre tableau de bord, chacune limitée à votre organisation et filtrable par plage de dates, environnement, agent et session. +Un réticule de survol partagé lie la carte thermique et la bande, ce qui permet à un pic en queue de s'aligner dans le temps sur les deux, au lieu de se cacher derrière une simple ligne de moyenne. Retrouvez les trois pages dans la section **observe** de votre tableau de bord, chacune limitée à votre organisation et filtrable par plage de dates, environnement, agent et session. -## Models : voyez exactement ce que chaque modèle vous coûte +## Modèles : voyez exactement ce que chaque modèle vous coûte -La page Models (illustrée ci-dessus) répond aux deux questions qu'une facture soulève invariablement : quel modèle, et combien. En plus de la vue de latence partagée, elle ajoute la **consommation de tokens par modèle**, le **coût estimé** et le **remplissage de la fenêtre de contexte**, afin que la croissance incontrôlée des prompts et une compaction imminente soient visibles avant de vous surprendre. +La page Modèles (illustrée ci-dessus) répond aux deux questions que toute facture soulève : quel modèle, et combien. En plus de la vue de latence partagée, elle ajoute la **consommation de tokens par modèle**, le **coût estimé** et le **remplissage de la fenêtre de contexte**, de sorte qu'une croissance incontrôlée du prompt et une compaction imminente soient visibles avant de vous surprendre. -Failproof AI Observability reconnaît automatiquement les identifiants de modèles courants. Si une fenêtre semble incorrecte, ou si vous utilisez un modèle privé, corrigez-la ou ajoutez-en un depuis **Settings**, dans **model context windows** — les indicateurs de remplissage se mettront à jour en conséquence. +Failproof AI Observability reconnaît automatiquement les identifiants de modèles courants. Si une fenêtre semble incorrecte, ou si vous utilisez un modèle privé, corrigez-la ou ajoutez-en un dans **Paramètres**, sous **fenêtres de contexte des modèles**, et les indicateurs de remplissage s'ajustent en conséquence. -## Tools : distinguez la lenteur de la défaillance +## Outils : distinguez les lents des défaillants -Un appel d'outil peut être lent, ou il peut échouer silencieusement — et vous voulez savoir lequel en quelques secondes, pas après avoir fouillé des logs. +Un appel d'outil peut être lent, ou il peut échouer discrètement, et vous voulez le savoir en quelques secondes, pas après avoir fouillé les logs. -![La page Tools affichant la carte de chaleur et la bande de percentiles partagées, à côté d'une répartition succès/échecs et d'une barre de distribution des outils](/agenteye/images/tools.png) -*La page Tools : la même carte de chaleur et bande de percentiles, plus une répartition succès/échecs et une barre de distribution des outils.* +![La page Outils affichant la carte thermique de latence partagée et la bande de percentiles, à côté d'une répartition succès/échecs et d'une barre de distribution des outils](/agenteye/images/tools.png) +*La page Outils : la même carte thermique et bande de percentiles, plus une répartition succès/échecs et une barre de distribution des outils.* -En complément de la vue de latence partagée, la page Tools ajoute une **répartition succès/échecs** et une **barre de distribution des outils**, afin de voir en un coup d'œil quels outils vous sollicitez le plus et lesquels grignotent votre budget d'erreurs. +En complément de la vue de latence partagée, la page Outils ajoute une **répartition succès/échecs** et une **barre de distribution des outils**, afin que vous voyiez d'un coup d'œil quels outils vous sollicitez le plus et lesquels grignotent votre budget d'erreurs. -## Hooks : identifiez le hook et le déclencheur exacts +## Hooks : identifiez précisément le hook et le déclencheur -Quand un hook de cycle de vie alourdit une exécution, constater que « les hooks sont lents » n'est pas exploitable. La page Hooks vous amène directement à celui qui pose problème. +Quand un hook de cycle de vie ralentit une exécution, « les hooks sont lents » n'est pas quelque chose sur lequel vous pouvez agir. La page Hooks vous amène directement à celui qui pose problème. -![La page Hooks affichant la latence décomposée par nom de hook et événement déclencheur, sur la carte de chaleur et la bande de percentiles partagées](/agenteye/images/hooks.png) +![La page Hooks affichant la latence décomposée par nom de hook et événement déclencheur, sur la carte thermique et la bande de percentiles partagées](/agenteye/images/hooks.png) *La page Hooks : la latence décomposée par nom de hook et événement déclencheur.* -Au-dessus de la même carte de chaleur et bande de percentiles, la page Hooks décompose l'activité par **nom de hook** et **événement déclencheur**, afin de cibler précisément le hook unique et l'événement unique qui nécessitent votre attention. +Au-dessus de la même carte thermique de latence et bande de percentiles, la page Hooks décompose l'activité par **nom de hook** et **événement déclencheur**, afin que vous arriviez directement au hook et à l'événement uniques qui nécessitent votre attention. ## Voir aussi -- [Flux d'événements](/fr/agenteye/event-stream) : la trace en direct, colorée, de chaque événement. +- [Flux d'événements](/fr/agenteye/event-stream) : la trace en direct, avec code couleur, de chaque événement. - [Sessions](/fr/agenteye/sessions) : regroupez les événements en une ligne par exécution et ouvrez son graphe d'exécution. - [Suivi des erreurs](/fr/agenteye/error-tracking) : une surface de triage unique pour tout ce que le tableau de bord affiche en rouge. -- [Tableaux de bord](/fr/agenteye/dashboards) : vues agrégées sur l'ensemble de votre flotte. \ No newline at end of file +- [Tableaux de bord](/fr/agenteye/dashboards) : vues récapitulatives sur l'ensemble de votre flotte. \ No newline at end of file diff --git a/docs/fr/architecture.mdx b/docs/fr/architecture.mdx index f1de8f93..9fd50137 100644 --- a/docs/fr/architecture.mdx +++ b/docs/fr/architecture.mdx @@ -4,7 +4,7 @@ description: "Fonctionnement interne du gestionnaire de hooks, du chargement de icon: sitemap --- -Ce document explique le fonctionnement interne de failproofai : comment le système de hooks intercepte les appels d'outils des agents, comment la configuration est chargée et fusionnée, comment les politiques sont évaluées, et comment le tableau de bord surveille l'activité des agents. +Ce document explique le fonctionnement interne de failproofai : comment le système de hooks intercepte les appels d'outils de l'agent, comment la configuration est chargée et fusionnée, comment les politiques sont évaluées, et comment le tableau de bord surveille l'activité de l'agent. --- @@ -12,10 +12,10 @@ Ce document explique le fonctionnement interne de failproofai : comment le syst failproofai comporte deux sous-systèmes indépendants : -1. **Gestionnaire de hooks** - Un sous-processus CLI rapide que Claude Code invoque à chaque appel d'outil d'un agent. Il évalue les politiques et retourne une décision. -2. **Agent Monitor (Tableau de bord)** - Une application web Next.js permettant de surveiller les sessions des agents et de gérer les politiques. +1. **Gestionnaire de hooks** - Un sous-processus CLI rapide que Claude Code invoque à chaque appel d'outil de l'agent. Il évalue les politiques et retourne une décision. +2. **Agent Monitor (Tableau de bord)** - Une application web Next.js pour surveiller les sessions d'agent et gérer les politiques. -Les deux sous-systèmes partagent des fichiers de configuration situés dans `~/.failproofai/` et dans le répertoire `.failproofai/` du projet, mais ils s'exécutent en tant que processus distincts et ne communiquent que via le système de fichiers. +Les deux sous-systèmes partagent les fichiers de configuration situés dans `~/.failproofai/` et dans le répertoire `.failproofai/` du projet, mais ils s'exécutent en tant que processus séparés et ne communiquent qu'à travers le système de fichiers. --- @@ -62,7 +62,7 @@ Claude Code invoque ensuite `failproofai --hook PreToolUse` en tant que sous-pro Pour les événements `PostToolUse`, la charge utile contient également `tool_result` avec la sortie de l'outil. -Le gestionnaire applique une limite de 1 Mo sur stdin. Les charges utiles dépassant cette taille sont ignorées et toutes les politiques autorisent implicitement. +Le gestionnaire impose une limite de 1 Mo sur stdin. Les charges utiles dépassant cette taille sont ignorées et toutes les politiques autorisent implicitement. ### Format de la réponse @@ -94,9 +94,9 @@ Le gestionnaire applique une limite de 1 Mo sur stdin. Les charges utiles dépas } ``` -**Instruction pour l'événement Stop :** +**Instruction lors d'un événement Stop :** - Code de sortie : `2` -- La raison est écrite sur stderr (et non sur stdout) +- Raison écrite sur stderr (et non sur stdout) **Autorisation :** - Code de sortie : `0` @@ -104,7 +104,7 @@ Le gestionnaire applique une limite de 1 Mo sur stdin. Les charges utiles dépas **Autorisation avec message :** -`allow(message)` permet à une politique d'envoyer du contexte informatif à Claude même lorsque l'opération est autorisée. Le gestionnaire de hooks écrit le JSON suivant sur **stdout** (et non dans un fichier de configuration — il s'agit de la réponse du gestionnaire à Claude Code, au même titre que les réponses de refus et d'instruction ci-dessus) : +`allow(message)` permet à une politique d'envoyer un contexte informatif à Claude même lorsque l'opération est autorisée. Le gestionnaire de hooks écrit le JSON suivant sur **stdout** (et non dans un fichier de configuration — il s'agit de la réponse du gestionnaire à Claude Code, tout comme les réponses de refus et d'instruction ci-dessus) : ```json // Written to stdout by the hook handler process @@ -115,12 +115,12 @@ Le gestionnaire applique une limite de 1 Mo sur stdin. Les charges utiles dépas } ``` - Code de sortie : `0` (l'opération est autorisée) -- Lorsque plusieurs politiques retournent `allow` avec un message, leurs messages sont concaténés avec des sauts de ligne dans une seule chaîne `additionalContext` +- Lorsque plusieurs politiques retournent `allow` avec un message, leurs messages sont joints par des sauts de ligne en une seule chaîne `additionalContext` - Si aucune politique ne fournit de message, stdout est vide (comportement inchangé) ### Pipeline de traitement -`src/hooks/handler.ts` implémente l'intégralité du pipeline : +`src/hooks/handler.ts` implémente le pipeline complet : ```text stdin JSON @@ -139,13 +139,13 @@ stdin JSON → exit ``` -L'ensemble du processus s'exécute en moins de 100 ms pour des charges utiles classiques, sans aucun appel à un LLM. +L'ensemble du processus s'exécute en moins de 100 ms pour des charges utiles typiques, sans aucun appel LLM. --- ## Chargement de la configuration -`src/hooks/hooks-config.ts` implémente le chargement de la configuration sur trois portées. +`src/hooks/hooks-config.ts` implémente le chargement de la configuration à trois niveaux de portée. ```text [1] {cwd}/.failproofai/policies-config.json ← projet (priorité la plus haute) @@ -154,12 +154,12 @@ L'ensemble du processus s'exécute en moins de 100 ms pour des charges utiles cl ``` Logique de fusion : -- `enabledPolicies` - union dédupliquée des trois fichiers +- `enabledPolicies` - union dédupliquée sur les trois fichiers - `policyParams` - par clé de politique, le premier fichier qui la définit l'emporte entièrement -- `customPoliciesPath` - le premier fichier qui la définit l'emporte -- `llm` - le premier fichier qui la définit l'emporte +- `customPoliciesPath` - le premier fichier qui le définit l'emporte +- `llm` - le premier fichier qui le définit l'emporte -Le tableau de bord web utilise `readHooksConfig()` (portée globale uniquement) pour la lecture et l'écriture, car il n'est pas invoqué avec un répertoire de travail de projet. +Le tableau de bord web utilise `readHooksConfig()` (niveau global uniquement) pour la lecture et l'écriture, car il n'est pas invoqué avec un répertoire de travail de projet. --- @@ -169,18 +169,18 @@ Le tableau de bord web utilise `readHooksConfig()` (portée globale uniquement) Pour chaque politique : -1. Recherche du schéma `params` de la politique (si elle en possède un). -2. Lecture de `policyParams[policy.name]` depuis la configuration fusionnée. -3. Fusion des valeurs fournies par l'utilisateur sur les valeurs par défaut du schéma pour produire `ctx.params`. -4. Appel de `policy.fn(ctx)` avec le contexte résolu. -5. Si le résultat est `deny`, arrêt immédiat et retour de cette décision. -6. Si le résultat est `instruct`, accumulation du message et poursuite. -7. Si le résultat est `allow`, passage à la politique suivante. +1. Rechercher le schéma `params` de la politique (si elle en possède un). +2. Lire `policyParams[policy.name]` depuis la configuration fusionnée. +3. Fusionner les valeurs fournies par l'utilisateur sur les valeurs par défaut du schéma pour produire `ctx.params`. +4. Appeler `policy.fn(ctx)` avec le contexte résolu. +5. Si le résultat est `deny`, s'arrêter immédiatement et retourner cette décision. +6. Si le résultat est `instruct`, accumuler le message et continuer. +7. Si le résultat est `allow`, passer à la politique suivante. -Après exécution de toutes les politiques : -- Si un `deny` a été retourné, la réponse de refus est émise. -- Si des retours `instruct` ont été collectés, une unique réponse d'instruction est émise avec tous les messages joints. -- Sinon, une réponse d'autorisation est émise (stdout vide, code de sortie 0). +Après l'exécution de toutes les politiques : +- Si un `deny` a été retourné, émettre la réponse de refus. +- Si des retours `instruct` ont été collectés, émettre une seule réponse d'instruction avec tous les messages joints. +- Sinon, émettre une réponse d'autorisation (stdout vide, code de sortie 0). --- @@ -204,9 +204,9 @@ interface BuiltinPolicyDefinition { } ``` -Les politiques acceptant des `params` déclarent un `PolicyParamsSchema` avec les types et valeurs par défaut de chaque paramètre. L'évaluateur de politiques injecte les valeurs résolues dans `ctx.params` avant d'appeler `fn`. Les fonctions de politique lisent `ctx.params` sans vérification de nullité, car les valeurs par défaut sont toujours appliquées en premier. +Les politiques qui acceptent des `params` déclarent un `PolicyParamsSchema` avec les types et valeurs par défaut de chaque paramètre. L'évaluateur de politiques injecte les valeurs résolues dans `ctx.params` avant d'appeler `fn`. Les fonctions de politique lisent `ctx.params` sans vérification de nullité car les valeurs par défaut sont toujours appliquées en premier. -La correspondance de motifs au sein des politiques utilise des tokens de commande analysés (argv), et non une correspondance de chaînes brutes. Cela empêche tout contournement par injection d'opérateurs shell (par exemple, un motif pour `sudo systemctl status *` ne peut pas être contourné en ajoutant `; rm -rf /` à la commande). +La correspondance de motifs à l'intérieur des politiques utilise des tokens de commande analysés (argv), et non une correspondance de chaîne brute. Cela empêche le contournement par injection d'opérateurs shell (par exemple, un motif pour `sudo systemctl status *` ne peut pas être contourné en ajoutant `; rm -rf /` à la commande). --- @@ -227,23 +227,23 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` charge le fichier de politique de l'utilisateur : -1. Lecture de `customPoliciesPath` depuis la configuration ; ignoré s'il est absent. -2. Résolution vers un chemin absolu ; vérification de l'existence du fichier. -3. Réécriture de toutes les importations `from "failproofai"` vers le chemin dist réel, afin que `customPolicies` se résolve vers le même registre `globalThis`. -4. Réécriture récursive des imports locaux transitifs pour garantir la compatibilité ESM. -5. Écriture de fichiers `.mjs` temporaires et `import()` du fichier d'entrée. -6. Appel de `getCustomHooks()` pour récupérer les hooks enregistrés. -7. Nettoyage de tous les fichiers temporaires dans un bloc `finally`. +1. Lire `customPoliciesPath` depuis la configuration ; ignorer si absent. +2. Résoudre vers un chemin absolu ; vérifier que le fichier existe. +3. Réécrire toutes les importations `from "failproofai"` vers le chemin dist réel afin que `customPolicies` pointe vers le même registre `globalThis`. +4. Réécrire de manière récursive les importations locales transitives pour garantir la compatibilité ESM. +5. Écrire des fichiers `.mjs` temporaires et `import()` le fichier d'entrée. +6. Appeler `getCustomHooks()` pour récupérer les hooks enregistrés. +7. Nettoyer tous les fichiers temporaires dans un bloc `finally`. En cas d'erreur (fichier introuvable, erreur de syntaxe, échec d'import), l'erreur est consignée dans `~/.failproofai/hook.log` et le chargeur retourne un tableau vide. Les politiques intégrées ne sont pas affectées. -Les politiques personnalisées sont évaluées après toutes les politiques intégrées. Un `deny` d'une politique personnalisée court-circuite quand même les politiques personnalisées suivantes (mais toutes les politiques intégrées ont déjà été exécutées à ce stade). +Les politiques personnalisées sont évaluées après toutes les politiques intégrées. Un `deny` d'une politique personnalisée court-circuite tout de même les politiques personnalisées suivantes (mais toutes les politiques intégrées ont déjà été exécutées à ce stade). --- ## Journalisation de l'activité -Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL à `~/.failproofai/hook-activity/current.jsonl`, qui est archivée dans `page--.jsonl` une fois qu'elle atteint une page : +Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL à `~/.failproofai/hook-activity/current.jsonl`, qui bascule vers `page--.jsonl` une fois qu'une page est atteinte : ```json { @@ -258,13 +258,13 @@ Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL à `~/ } ``` -Une ligne par politique ayant rendu une décision autre qu'allow. Les décisions d'autorisation ne sont pas journalisées (afin de limiter la taille du fichier). +Une ligne par politique ayant rendu une décision autre que allow. Les décisions d'autorisation ne sont pas journalisées (pour maintenir la taille du fichier réduite). --- ## Architecture du tableau de bord -Le tableau de bord est une application **Next.js 16** utilisant l'App Router avec les React Server Components et les Server Actions. +Le tableau de bord est une application **Next.js 16** utilisant l'App Router avec des React Server Components et des Server Actions. ```text app/ @@ -277,7 +277,7 @@ app/ actions/ get-hooks-config.ts ← Lecture de la configuration + liste des politiques update-hooks-config.ts ← Activation/désactivation d'une politique - update-policy-params.ts ← Mise à jour des paramètres d'une politique + update-policy-params.ts ← Mise à jour des paramètres de politique get-hook-activity.ts ← Pagination/recherche dans le journal d'activité install-hooks-web.ts ← Installation/suppression des hooks depuis le navigateur api/ @@ -286,16 +286,16 @@ app/ **Flux de données :** -- Les composants de page appellent `lib/projects.ts` et `lib/log-entries.ts` pour lire les données de projet et de session directement depuis le système de fichiers (pas de couche API pour les lectures). -- La page Policies utilise des Server Actions pour toutes les mutations (activation/désactivation, mise à jour des paramètres, installation/suppression). -- Le visualiseur de session analyse le format de transcript JSONL de Claude et affiche une chronologie des messages et des appels d'outils. +- Les composants de page appellent `lib/projects.ts` et `lib/log-entries.ts` pour lire les données de projet/session directement depuis le système de fichiers (pas de couche API pour les lectures). +- La page Policies utilise des Server Actions pour toutes les mutations (activation, mise à jour des paramètres, installation/suppression). +- Le visualiseur de session analyse le format de transcription JSONL de Claude et affiche une chronologie des messages et des appels d'outils. -**Décisions de conception clés :** +**Principales décisions de conception :** - Pas de base de données - tout l'état persistant est dans des fichiers plats (`~/.failproofai/`, `~/.claude/projects/`). - Server Actions pour les mutations - pas d'API REST nécessaire pour les opérations CRUD. - React Server Components pour les pages de lecture - chargement initial plus rapide, pas de bundle client pour la récupération de données. -- Composants client uniquement là où l'interactivité est requise (bascules de politiques, recherche dans l'activité, visualiseur de logs). +- Composants client uniquement là où l'interactivité est nécessaire (bascules de politiques, recherche d'activité, visualiseur de logs). --- @@ -309,20 +309,20 @@ failproofai/ │ ├── handler.ts # Pipeline des événements de hook │ ├── builtin-policies.ts # 39 définitions de politiques │ ├── policy-evaluator.ts # Moteur d'exécution des politiques -│ ├── policy-registry.ts # Enregistrement et recherche des politiques +│ ├── policy-registry.ts # Enregistrement et recherche de politiques │ ├── policy-types.ts # Interfaces TypeScript -│ ├── hooks-config.ts # Chargement de la configuration multi-portée +│ ├── hooks-config.ts # Chargement de configuration multi-niveaux │ ├── custom-hooks-registry.ts # Registre de hooks adossé à globalThis │ ├── custom-hooks-loader.ts # Chargeur ESM pour les hooks JS utilisateur -│ ├── manager.ts # Opérations d'installation / suppression / listage -│ ├── install-prompt.ts # Invite interactive de sélection des politiques +│ ├── manager.ts # Opérations d'installation / suppression / liste +│ ├── install-prompt.ts # Invite de sélection interactive des politiques │ ├── hook-logger.ts # Journalisation vers hook.log │ ├── hook-activity-store.ts # Persistance de l'activité dans hook-activity/ │ └── llm-client.ts # Client API LLM (pour les politiques basées sur l'IA) ├── app/ # Tableau de bord Next.js (pages + server actions) ├── lib/ # Utilitaires partagés │ ├── projects.ts # Énumération des projets Claude depuis le système de fichiers -│ ├── log-entries.ts # Analyse du format de transcript JSONL de Claude +│ ├── log-entries.ts # Analyse du format de transcription JSONL de Claude │ ├── paths.ts # Résolution des chemins système │ └── ... ├── components/ # Composants UI React partagés diff --git a/docs/fr/built-in-policies.mdx b/docs/fr/built-in-policies.mdx index 4be592bc..f4111f7e 100644 --- a/docs/fr/built-in-policies.mdx +++ b/docs/fr/built-in-policies.mdx @@ -1,10 +1,10 @@ --- title: Politiques intégrées -description: "Les 39 politiques intégrées qui détectent les modes d'échec courants des agents" +description: "Les 39 politiques intégrées qui interceptent les modes d'échec courants des agents" icon: shield --- -failproofai est livré avec 39 politiques intégrées qui détectent les modes d'échec courants des agents. Chaque politique se déclenche sur un type d'événement hook spécifique et un nom d'outil. Dix-neuf politiques acceptent des paramètres qui vous permettent d'ajuster leur comportement sans écrire de code. Cinq politiques de workflow imposent un pipeline commit → push → PR → CI avant que Claude ne s'arrête. +failproofai est livré avec 39 politiques intégrées qui interceptent les modes d'échec courants des agents. Chaque politique se déclenche sur un type d'événement hook spécifique et un nom d'outil. Dix-neuf politiques acceptent des paramètres qui vous permettent d'ajuster leur comportement sans écrire de code. Cinq politiques de workflow imposent un pipeline commit → push → PR → CI avant que Claude ne s'arrête. --- @@ -27,13 +27,13 @@ Les politiques sont regroupées par catégories : - **`block-`** — empêche l'agent de continuer. - **`warn-`** — fournit à l'agent un contexte supplémentaire pour qu'il puisse se corriger. -- **`sanitize-`** — expurge les données sensibles de la sortie d'outil avant que l'agent ne les voie. +- **`sanitize-`** — supprime les données sensibles de la sortie d'un outil avant que l'agent ne la voie. ### Espaces de noms Chaque politique occupe un emplacement `/`. Les politiques intégrées appartiennent à l'espace de noms **`failproofai/`** — par exemple, `failproofai/sanitize-jwt`. L'espace de noms évite les collisions lorsque vous chargez également des politiques personnalisées ou tierces avec des noms courts similaires. -Dans votre configuration, vous pouvez désigner une politique intégrée par son nom court ou son nom qualifié ; les deux formes résolvent vers la même politique : +Dans votre configuration, vous pouvez désigner une politique intégrée soit par son nom court, soit par son nom qualifié ; les deux formes désignent la même politique : ```json { @@ -44,13 +44,13 @@ Dans votre configuration, vous pouvez désigner une politique intégrée par son } ``` -Si un nom ne contient pas de `/`, failproofai le considère comme appartenant à l'espace de noms par défaut `failproofai`. Les noms qui contiennent déjà un `/` (p. ex. `myorg/foo`, `custom/my-hook`) sont conservés tels quels. +Si un nom ne contient pas de `/`, failproofai le considère comme appartenant à l'espace de noms par défaut `failproofai`. Les noms qui contiennent déjà un `/` (par ex. `myorg/foo`, `custom/my-hook`) sont conservés tels quels. - **`require-`** — bloque l'événement Stop jusqu'à ce que les conditions soient remplies. --- -Toutes les politiques acceptent un champ optionnel `hint` dans `policyParams`. Le hint est ajouté au message deny ou instruct que Claude reçoit, fournissant des indications concrètes sans modifier le code de la politique. Fonctionne avec les politiques intégrées, personnalisées et de convention. Voir [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails. +Chaque politique accepte un champ optionnel `hint` dans `policyParams`. Ce hint est ajouté au message deny ou instruct que Claude reçoit, offrant des conseils concrets sans modifier le code de la politique. Fonctionne avec les politiques intégrées, personnalisées et de convention. Voir [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails. --- @@ -62,21 +62,21 @@ Empêche les agents d'exécuter des opérations difficiles à annuler ou suscept ### `block-sudo` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse toute commande `sudo` ou `doas`. +**Par défaut :** Refuse toute commande `sudo` ou `doas`. -Bloque une commande qui exécute un binaire d'élévation **en position de commande**. La correspondance est structurelle plutôt que textuelle : la commande est découpée en segments comme le ferait un shell, les assignations de préfixe (`FOO=bar`), les redirections et les lanceurs avec leurs options (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) sont ignorés, et le binaire résultant est comparé par son **basename**. Ainsi, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` et `bash -c "sudo …"` sont tous refusés, et `doas` est traité comme la même capacité sous un nom différent. +Bloque une commande qui exécute un binaire d'élévation de privilèges **en position de commande**. La correspondance est structurelle plutôt que textuelle : la commande est découpée en segments comme le ferait un shell, les assignations de préfixe (`FOO=bar`), les redirections et les exécuteurs avec leurs options (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) sont ignorés, et le binaire résultant est comparé par **nom de base**. Ainsi, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` et `bash -c "sudo …"` sont tous refusés, et `doas` est traité comme la même capacité sous un nom différent. -Parce qu'elle s'ancre sur la position de commande plutôt que sur l'apparition du mot n'importe où, elle ne se déclenche **pas** sur des commandes qui le mentionnent simplement — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, ou une alternance `grep` contenant le mot s'exécutent normalement. +Parce qu'il s'ancre sur la position de commande plutôt que sur la présence du mot n'importe où, il ne se déclenche **pas** pour les commandes qui mentionnent simplement le terme — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, ou une alternance `grep` contenant le mot s'exécutent normalement. -Cela arrête la tentative évidente ; cela ne ferme pas toute la classe. Un agent capable d'exécuter un shell arbitraire peut encore atteindre l'élévation indirectement — via une variable (`S=sudo; $S …`), un pipe base64 décodé, ou un script wrapper sur le disque — car aucune inspection d'une seule chaîne de commande ne peut les suivre. Considérez ceci comme un garde-fou contre les erreurs et les escalades non intentionnelles, pas comme une frontière de sécurité contre un agent déterminé. Une vraie frontière doit être imposée en dessous du shell. +Cela bloque la tentative évidente ; cela ne ferme pas la classe entière. Un agent capable d'exécuter un shell arbitraire peut encore atteindre une élévation indirectement — via une variable (`S=sudo; $S …`), un pipe base64 décodé, ou un script wrapper sur le disque — car aucune inspection d'une seule chaîne de commande ne peut suivre ces chemins. Considérez ceci comme un garde-fou contre les erreurs et les escalades occasionnelles, non comme une frontière de sécurité contre un agent déterminé. Une vraie frontière doit être imposée en dessous du shell. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commande exacts qui sont autorisés. Chaque entrée est comparée aux tokens argv analysés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commande exacts autorisés. Chaque entrée est comparée aux tokens argv analysés. | **Exemple :** @@ -93,7 +93,7 @@ Cela arrête la tentative évidente ; cela ne ferme pas toute la classe. Un agen Avec cette configuration, `sudo systemctl status nginx` est autorisé, mais `sudo rm /etc/hosts` est refusé. -Les patterns sont comparés aux tokens analysés, pas à la chaîne de commande brute. Cela empêche les contournements via des opérateurs shell ajoutés (p. ex. `sudo systemctl status x; rm -rf /` ne correspond pas à `sudo systemctl status *`). +Les patterns sont comparés aux tokens analysés, pas à la chaîne de commande brute. Cela empêche les contournements via des opérateurs shell ajoutés (par ex. `sudo systemctl status x; rm -rf /` ne correspond pas à `sudo systemctl status *`). --- @@ -101,13 +101,13 @@ Les patterns sont comparés aux tokens analysés, pas à la chaîne de commande ### `block-rm-rf` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse `rm -rf`, `rm -fr`, et les formes similaires de suppression récursive. +**Par défaut :** Refuse `rm -rf`, `rm -fr` et les formes similaires de suppression récursive. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Chemins qu'il est sûr de supprimer récursivement (p. ex. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Chemins dont la suppression récursive est autorisée (par ex. `/tmp`). | **Exemple :** @@ -126,7 +126,7 @@ Les patterns sont comparés aux tokens analysés, pas à la chaîne de commande ### `block-curl-pipe-sh` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse `curl | bash`, `curl | sh`, `wget | bash`, et les patterns similaires. +**Par défaut :** Refuse `curl | bash`, `curl | sh`, `wget | bash` et les patterns similaires. Aucun paramètre. @@ -135,7 +135,7 @@ Aucun paramètre. ### `block-failproofai-commands` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse les commandes qui désinstalleraient ou désactiveraient failproofai lui-même (p. ex. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Par défaut :** Refuse les commandes qui désinstalleraient ou désactiveraient failproofai lui-même (par ex. `npm uninstall failproofai`, `failproofai policies --uninstall`). Aucun paramètre. @@ -144,11 +144,11 @@ Aucun paramètre. ### `block-self-pause` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse `failproofai config --pause`, qui suspend l'application des politiques pour une session. La mise en pause est une décision humaine — un agent capable de l'exécuter pourrait désactiver toutes les autres politiques avec une seule commande. +**Par défaut :** Refuse `failproofai config --pause`, qui suspend l'application des politiques pour une session. La mise en pause est une décision humaine — un agent capable de l'exécuter pourrait désactiver toutes les autres politiques avec une seule commande. -Plus ciblée que [`block-failproofai-commands`](#block-failproofai-commands) intentionnellement, et non couverte par elle : cette politique s'ancre sur une limite de commande, donc `npx -y failproofai config --pause` ne lui correspond pas, et étant large elle est souvent désactivée pour que les agents puissent exécuter `failproofai audit`. `--resume` et `--status` sont autorisés — aucun des deux ne supprime l'application. +Plus ciblée que [`block-failproofai-commands`](#block-failproofai-commands) intentionnellement, et non couverte par celle-ci : cette politique s'ancre sur une frontière de commande, donc `npx -y failproofai config --pause` ne la déclenche pas, et étant large elle est souvent désactivée pour que les agents puissent exécuter `failproofai audit`. `--resume` et `--status` sont autorisés — aucun des deux ne supprime l'application des politiques. -Cela arrête la tentative directe, pas toute la classe : un agent peut encore atteindre le même état via un alias ou un script wrapper. Pour fermer complètement cette possibilité, il faudrait que la mise en pause soit inaccessible depuis un appel d'outil. +Cela bloque la tentative directe, pas toute la classe : un agent peut toujours atteindre le même état via un alias ou un script wrapper. Fermer complètement cette possibilité nécessite que la mise en pause soit totalement inaccessible depuis un appel d'outil. Aucun paramètre. @@ -156,20 +156,20 @@ Aucun paramètre. ## Commandes infra -Empêche les agents de codage d'exécuter des CLI d'infrastructure ou de déclencher des pipelines CI/CD. Toutes les politiques de cette catégorie sont **opt-in** (`defaultEnabled: false`) — les agents qui ont légitimement besoin d'appeler `kubectl`, `terraform`, etc. ne seront pas perturbés sauf si vous activez la politique. Lorsqu'elle est activée, chaque invocation de la CLI correspondante est refusée sauf si la commande correspond à une entrée dans `allowPatterns`. +Empêche les agents de développement d'exécuter des CLI d'infrastructure ou de déclencher des pipelines CI/CD. Toutes les politiques de cette catégorie sont **opt-in** (`defaultEnabled: false`) — les agents qui ont légitimement besoin d'appeler `kubectl`, `terraform`, etc. ne seront pas perturbés sauf si vous activez la politique. Une fois activée, chaque invocation du CLI correspondant est refusée à moins que la commande ne corresponde à une entrée dans `allowPatterns`. -La grammaire des patterns est la même que pour [`block-sudo`](#block-sudo) : les tokens sont comparés aux argv analysés, `*` est un joker pour un token, et toute commande contenant un opérateur shell autonome (`&&`, `||`, `|`, `;`) ou un token avec des métacaractères shell intégrés est rejetée avant la correspondance de la liste blanche pour éviter les contournements par injection. +La grammaire des patterns est la même que pour [`block-sudo`](#block-sudo) : les tokens sont comparés aux argv analysés, `*` est un joker pour un token, et toute commande contenant un opérateur shell autonome (`&&`, `||`, `|`, `;`) ou un token avec des métacaractères shell intégrés est rejetée avant la correspondance avec la liste d'autorisation pour éviter les contournements par injection. ### `block-kubectl` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse toute invocation de `kubectl`. +**Par défaut :** Refuse toute invocation de `kubectl`. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes kubectl autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commande kubectl autorisés. | **Exemple :** @@ -190,13 +190,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-terraform` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse toute invocation de `terraform` ou `tofu` (OpenTofu). +**Par défaut :** Refuse toute invocation de `terraform` ou `tofu` (OpenTofu). **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes terraform/tofu autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commande terraform/tofu autorisés. | **Exemple :** @@ -215,13 +215,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-aws-cli` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse toute invocation de la CLI `aws`. +**Par défaut :** Refuse toute invocation du CLI `aws`. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes CLI aws autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commande CLI aws autorisés. | **Exemple :** @@ -240,13 +240,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-gcloud` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse toute invocation de la CLI `gcloud` (Google Cloud). +**Par défaut :** Refuse toute invocation du CLI `gcloud` (Google Cloud). **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes gcloud autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commande gcloud autorisés. | **Exemple :** @@ -265,13 +265,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-az-cli` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse toute invocation de la CLI `az` (Azure). +**Par défaut :** Refuse toute invocation du CLI `az` (Azure). **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes CLI az autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commande CLI az autorisés. | **Exemple :** @@ -290,13 +290,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-helm` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse toute invocation de `helm`. +**Par défaut :** Refuse toute invocation de `helm`. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes helm autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commande helm autorisés. | **Exemple :** @@ -315,7 +315,7 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-gh-pipeline` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse les sous-commandes `gh` CLI suivantes qui modifient l'état ou déclenchent des pipelines : +**Par défaut :** Refuse les sous-commandes `gh` CLI suivantes qui modifient l'état ou déclenchent des pipelines : - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -324,13 +324,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - - `gh cache delete` - `gh secret set`, `gh secret delete` -Les sous-commandes `gh` en lecture seule telles que `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, et `gh api repos/.../...` ne sont **pas** visées par cette politique — elles sont régulièrement nécessaires pour les vérifications de workflow (y compris le `require-ci-green-before-stop` de failproofai). +Les sous-commandes `gh` en lecture seule telles que `gh pr view`, `gh pr list`, `gh run list`, `gh release view` et `gh api repos/.../...` ne sont **pas** concernées par cette politique — elles sont régulièrement nécessaires pour les vérifications de workflow (y compris le propre `require-ci-green-before-stop` de failproofai). **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocations scriptées spécifiques à autoriser même si elles seraient autrement refusées. | +| `allowPatterns` | `string[]` | `[]` | Invocations scriptées spécifiques à autoriser même si elles seraient normalement refusées. | **Exemple :** @@ -348,12 +348,12 @@ Les sous-commandes `gh` en lecture seule telles que `gh pr view`, `gh pr list`, ## Secrets (sanitizers) -Empêche les agents de faire fuiter des identifiants dans leur contexte ou leur sortie. Les politiques de type sanitizer se déclenchent sur les événements **PostToolUse**. Lorsque Claude exécute une commande Bash, lit un fichier ou appelle un outil quelconque, ces politiques inspectent la sortie avant qu'elle ne soit renvoyée à Claude. Si un pattern de secret est détecté, la politique renvoie une décision deny qui empêche la sortie d'être transmise. +Empêche les agents de faire fuiter des identifiants dans leur contexte ou leur sortie. Les politiques sanitizer se déclenchent sur les événements **PostToolUse**. Lorsque Claude exécute une commande Bash, lit un fichier ou appelle un outil quelconque, ces politiques inspectent la sortie avant qu'elle ne soit retournée à Claude. Si un pattern de secret est détecté, la politique renvoie une décision de refus qui empêche la sortie d'être transmise. ### `sanitize-jwt` **Événement :** PostToolUse (tous les outils) -**Comportement par défaut :** Expurge les tokens JWT (trois segments base64url séparés par `.`). +**Par défaut :** Masque les tokens JWT (trois segments base64url séparés par `.`). Aucun paramètre. @@ -362,11 +362,11 @@ Aucun paramètre. ### `sanitize-api-keys` **Événement :** PostToolUse (tous les outils) -**Comportement par défaut :** Expurge les formats courants de clés API : Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), clés d'accès AWS (`AKIA`), clés Stripe (`sk_live_`, `sk_test_`), et clés Google API (`AIza`). +**Par défaut :** Masque les formats de clés API courants : Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), clés d'accès AWS (`AKIA`), clés Stripe (`sk_live_`, `sk_test_`), et clés Google API (`AIza`). **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| | `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Patterns regex supplémentaires à traiter comme des secrets. | @@ -390,7 +390,7 @@ Aucun paramètre. ### `sanitize-connection-strings` **Événement :** PostToolUse (tous les outils) -**Comportement par défaut :** Expurge les chaînes de connexion à des bases de données contenant des identifiants intégrés (p. ex. `postgresql://user:password@host/db`). +**Par défaut :** Masque les chaînes de connexion de base de données contenant des identifiants intégrés (par ex. `postgresql://user:password@host/db`). Aucun paramètre. @@ -399,7 +399,7 @@ Aucun paramètre. ### `sanitize-private-key-content` **Événement :** PostToolUse (tous les outils) -**Comportement par défaut :** Expurge les blocs PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.). +**Par défaut :** Masque les blocs PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.). Aucun paramètre. @@ -408,7 +408,7 @@ Aucun paramètre. ### `sanitize-bearer-tokens` **Événement :** PostToolUse (tous les outils) -**Comportement par défaut :** Expurge les en-têtes `Authorization: Bearer ` dont le token comporte 20 caractères ou plus. +**Par défaut :** Masque les en-têtes `Authorization: Bearer ` où le token fait 20 caractères ou plus. Aucun paramètre. @@ -421,7 +421,7 @@ Protège la configuration d'environnement sensible contre la lecture ou l'exposi ### `block-env-files` **Événement :** PreToolUse (Bash, Read) -**Comportement par défaut :** Refuse la lecture des fichiers `.env` via `cat .env`, les appels à l'outil `Read` avec `.env` comme chemin de fichier, etc. +**Par défaut :** Refuse la lecture des fichiers `.env` via `cat .env`, les appels à l'outil `Read` avec `.env` comme chemin de fichier, etc. Ne bloque pas `.envrc` ni d'autres fichiers liés à l'environnement — uniquement les fichiers nommés exactement `.env`. @@ -432,7 +432,7 @@ Aucun paramètre. ### `protect-env-vars` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse les commandes qui affichent les variables d'environnement : `printenv`, `env`, `echo $VAR`. +**Par défaut :** Refuse les commandes qui affichent les variables d'environnement : `printenv`, `env`, `echo $VAR`. Aucun paramètre. @@ -440,18 +440,18 @@ Aucun paramètre. ## Accès aux fichiers -Maintient les agents à l'intérieur des limites du projet et à l'écart des fichiers sensibles. +Maintient les agents dans les limites du projet et à l'écart des fichiers sensibles. ### `block-read-outside-cwd` **Événement :** PreToolUse (Read, Bash) -**Comportement par défaut :** Refuse la lecture de fichiers en dehors de la racine du projet. La limite est définie par `CLAUDE_PROJECT_DIR` (défini une fois par session par Claude Code), avec un repli sur le répertoire de travail courant de la session lorsque cette variable n'est pas définie. L'utilisation de la racine du projet plutôt que du `cwd` en direct signifie que la limite reste stable même après que Claude a effectué un `cd` dans un sous-répertoire. +**Par défaut :** Refuse la lecture de fichiers en dehors de la racine du projet. La frontière est `CLAUDE_PROJECT_DIR` (défini une fois par session par Claude Code), avec repli sur le répertoire de travail courant de la session lorsque cette variable n'est pas définie. L'utilisation de la racine du projet plutôt que du `cwd` actif garantit que la frontière reste stable même après qu'un `cd` de Claude dans un sous-répertoire. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Préfixes de chemins absolus autorisés même s'ils se trouvent en dehors de la racine du projet. | +| `allowPaths` | `string[]` | `[]` | Préfixes de chemin absolu autorisés même s'ils sont en dehors de la racine du projet. | **Exemple :** @@ -470,13 +470,13 @@ Maintient les agents à l'intérieur des limites du projet et à l'écart des fi ### `block-secrets-write` **Événement :** PreToolUse (Write, Edit) -**Comportement par défaut :** Refuse les écritures dans les fichiers couramment utilisés pour les clés privées et les certificats : `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Par défaut :** Refuse les écritures dans les fichiers couramment utilisés pour les clés privées et les certificats : `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Patterns de noms de fichiers supplémentaires (style glob) à bloquer. | +| `additionalPatterns` | `string[]` | `[]` | Patterns de nom de fichier supplémentaires (style glob) à bloquer. | **Exemple :** @@ -494,18 +494,18 @@ Maintient les agents à l'intérieur des limites du projet et à l'écart des fi ## Git -Prévient les pushs accidentels, les force-pushs et les erreurs de branche difficiles à annuler. +Empêche les pushs accidentels, les force-pushs et les erreurs de branche difficiles à annuler. ### `block-push-master` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse `git push origin main` et `git push origin master`. +**Par défaut :** Refuse `git push origin main` et `git push origin master`. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles il est interdit de pousser directement. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles le push direct est interdit. | **Exemple :** @@ -520,7 +520,7 @@ Prévient les pushs accidentels, les force-pushs et les erreurs de branche diffi ``` -Pour autoriser le push vers toutes les branches (désactivant ainsi cette politique sans la retirer de `enabledPolicies`), définissez `protectedBranches: []`. +Pour autoriser le push vers toutes les branches (en désactivant effectivement cette politique sans la retirer de `enabledPolicies`), définissez `protectedBranches: []`. --- @@ -528,11 +528,11 @@ Pour autoriser le push vers toutes les branches (désactivant ainsi cette politi ### `block-work-on-main` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse `git commit`, `git merge`, `git rebase`, et `git cherry-pick` lorsque l'arbre de travail est sur `main` ou `master`. La création et le changement de branche (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) ne sont pas affectés. +**Par défaut :** Refuse `git commit`, `git merge`, `git rebase` et `git cherry-pick` lorsque l'arbre de travail est sur `main` ou `master`. La création et le changement de branche (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) ne sont pas affectés. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles commit/merge/rebase/cherry-pick est refusé. | @@ -541,7 +541,7 @@ Pour autoriser le push vers toutes les branches (désactivant ainsi cette politi ### `block-force-push` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Refuse `git push --force` et `git push -f`. +**Par défaut :** Refuse `git push --force` et `git push -f`. Aucun paramètre spécifique à la politique. Utilisez le [`hint`](/fr/configuration#hint-cross-cutting) transversal pour suggérer des alternatives : @@ -560,7 +560,7 @@ Aucun paramètre spécifique à la politique. Utilisez le [`hint`](/fr/configura ### `warn-git-amend` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Demande à Claude de procéder avec précaution lors de l'exécution de `git commit --amend`. Ne bloque pas la commande. +**Par défaut :** Demande à Claude de procéder avec prudence lors de l'exécution de `git commit --amend`. Ne bloque pas la commande. Aucun paramètre. @@ -569,7 +569,7 @@ Aucun paramètre. ### `warn-git-stash-drop` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Demande à Claude de confirmer avant d'exécuter `git stash drop`. Ne bloque pas la commande. +**Par défaut :** Demande à Claude de confirmer avant d'exécuter `git stash drop`. Ne bloque pas la commande. Aucun paramètre. @@ -578,7 +578,7 @@ Aucun paramètre. ### `warn-all-files-staged` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Demande à Claude de vérifier ce qu'il indexe lorsqu'il exécute `git add -A` ou `git add .`. Ne bloque pas la commande. +**Par défaut :** Demande à Claude de vérifier ce qu'il met en stage lors de l'exécution de `git add -A` ou `git add .`. Ne bloque pas la commande. Aucun paramètre. @@ -586,12 +586,12 @@ Aucun paramètre. ## Base de données -Détecte les opérations SQL destructrices avant qu'elles ne s'exécutent sur votre base de données. +Intercepte les opérations SQL destructrices avant qu'elles ne s'exécutent sur votre base de données. ### `warn-destructive-sql` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Demande à Claude de confirmer avant d'exécuter du SQL contenant `DROP TABLE`, `DROP DATABASE`, ou `DELETE` sans clause `WHERE`. +**Par défaut :** Demande à Claude de confirmer avant d'exécuter du SQL contenant `DROP TABLE`, `DROP DATABASE` ou `DELETE` sans clause `WHERE`. Aucun paramètre. @@ -600,7 +600,7 @@ Aucun paramètre. ### `warn-schema-alteration` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Demande à Claude de confirmer avant d'exécuter des instructions `ALTER TABLE`. +**Par défaut :** Demande à Claude de confirmer avant d'exécuter des instructions `ALTER TABLE`. Aucun paramètre. @@ -613,13 +613,13 @@ Fournit aux agents un contexte supplémentaire avant des opérations potentielle ### `warn-large-file-write` **Événement :** PreToolUse (Write) -**Comportement par défaut :** Demande à Claude de confirmer avant d'écrire des fichiers de plus de 1024 Ko. +**Par défaut :** Demande à Claude de confirmer avant d'écrire des fichiers de plus de 1024 Ko. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Seuil de taille de fichier en kilo-octets au-delà duquel un avertissement est émis. | +| `thresholdKb` | `number` | `1024` | Seuil de taille de fichier en kilo-octets au-dessus duquel un avertissement est émis. | **Exemple :** @@ -634,7 +634,7 @@ Fournit aux agents un contexte supplémentaire avant des opérations potentielle ``` -Le gestionnaire de hook impose une limite de 1 Mo sur les payloads stdin. Pour tester cette politique avec un contenu de petite taille, définissez `thresholdKb` à une valeur bien inférieure à 1024. +Le gestionnaire de hook impose une limite de 1 Mo sur stdin pour les charges utiles. Pour tester cette politique avec un contenu de petite taille, définissez `thresholdKb` à une valeur bien inférieure à 1024. --- @@ -642,7 +642,7 @@ Le gestionnaire de hook impose une limite de 1 Mo sur les payloads stdin. Pour t ### `warn-package-publish` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Demande à Claude de confirmer avant d'exécuter `npm publish`. +**Par défaut :** Demande à Claude de confirmer avant d'exécuter `npm publish`. Aucun paramètre. @@ -651,7 +651,7 @@ Aucun paramètre. ### `warn-background-process` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Demande à Claude d'être prudent lors du lancement de processus en arrière-plan via `nohup`, `&`, `disown`, ou `screen`. +**Par défaut :** Demande à Claude d'être prudent lors du lancement de processus en arrière-plan via `nohup`, `&`, `disown` ou `screen`. Aucun paramètre. @@ -660,7 +660,7 @@ Aucun paramètre. ### `warn-global-package-install` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Demande à Claude de confirmer avant d'exécuter `npm install -g`, `yarn global add`, ou `pip install` sans environnement virtuel. +**Par défaut :** Demande à Claude de confirmer avant d'exécuter `npm install -g`, `yarn global add` ou `pip install` sans environnement virtuel. Aucun paramètre. @@ -673,14 +673,14 @@ Impose les gestionnaires de paquets que l'agent est autorisé à utiliser. ### `prefer-package-manager` **Événement :** PreToolUse (Bash) -**Comportement par défaut :** Désactivé. Lorsqu'il est activé, bloque toute commande de gestionnaire de paquets qui ne figure pas dans la liste `allowed` et demande à Claude de réécrire la commande en utilisant un gestionnaire autorisé. +**Par défaut :** Désactivé. Une fois activé, bloque toute commande de gestionnaire de paquets absent de la liste `allowed` et demande à Claude de réécrire la commande en utilisant un gestionnaire autorisé. Détecte : pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Noms des gestionnaires de paquets autorisés. Tout gestionnaire détecté qui n'est pas dans cette liste est bloqué. Lorsqu'elle est vide, la politique n'a aucun effet. | -| `blocked` | string[] | `[]` | Noms de gestionnaires supplémentaires à bloquer au-delà de la liste intégrée (p. ex. `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Noms de gestionnaires de paquets autorisés. Tout gestionnaire détecté absent de cette liste est bloqué. Quand vide, la politique est sans effet. | +| `blocked` | string[] | `[]` | Noms de gestionnaires supplémentaires à bloquer en plus de la liste intégrée (par ex. `['pdm', 'pipx']`). | La liste de blocage intégrée couvre : pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Utilisez `blocked` pour ajouter des gestionnaires absents de cette liste. @@ -698,18 +698,18 @@ La liste de blocage intégrée couvre : pip, pip3, npm, npx, yarn, pnpm, pnpx, b } ``` -Avec cette configuration, `pip install flask` et `pdm install flask` sont tous deux refusés avec un message indiquant à Claude d'utiliser `uv` ou `bun` à la place. Les commandes comme `uv pip install flask` sont autorisées car `uv` figure dans la liste blanche et est vérifié en premier. +Avec cette configuration, `pip install flask` et `pdm install flask` sont tous deux refusés avec un message demandant à Claude d'utiliser `uv` ou `bun` à la place. Les commandes comme `uv pip install flask` sont autorisées car `uv` figure dans la liste d'autorisation et est vérifié en premier. --- ## Comportement de l'IA -Détecte quand les agents sont bloqués ou se comportent de manière inattendue. +Détecte quand les agents sont bloqués ou se comportent de façon inattendue. ### `warn-repeated-tool-calls` **Événement :** PreToolUse (tous les outils) -**Comportement par défaut :** Demande à Claude de reconsidérer lorsque le même outil est appelé 3 fois ou plus avec des paramètres identiques — signe courant que l'agent est bloqué dans une boucle. +**Par défaut :** Demande à Claude de reconsidérer lorsque le même outil est appelé 3 fois ou plus avec des paramètres identiques — signe courant que l'agent est pris dans une boucle. Aucun paramètre. @@ -717,39 +717,39 @@ Aucun paramètre. ## Workflow -Impose un workflow discipliné en fin de session. Ces politiques se déclenchent sur l'événement **Stop** et empêchent l'agent de s'arrêter jusqu'à ce que chaque condition soit remplie. Elles suivent une chaîne de dépendance naturelle : commit → push → PR → CI. Si une politique refuse, les politiques suivantes dans la chaîne sont ignorées (court-circuit sur refus). +Impose un workflow de fin de session discipliné. Ces politiques se déclenchent sur l'événement **Stop** et empêchent l'agent de s'arrêter tant que chaque condition n'est pas remplie. Elles suivent une chaîne de dépendances naturelle : commit → push → PR → CI. Si une politique refuse, les politiques suivantes dans la chaîne sont ignorées (court-circuit sur refus). -Toutes les politiques de workflow sont **fail-open** : si l'outil requis n'est pas disponible (p. ex. `gh` non installé, pas de remote git), la politique autorise avec un message informatif expliquant pourquoi la vérification a été ignorée. +Toutes les politiques de workflow sont **fail-open** : si l'outil requis n'est pas disponible (par ex. `gh` non installé, pas de remote git), la politique autorise avec un message informatif expliquant pourquoi la vérification a été ignorée. ### Sémantique Stop par CLI -L'application du Stop se présente légèrement différemment selon les six CLI supportées car chacune expose un contrat de hook différent pour « l'agent a terminé ». Le **résultat** est le même — l'agent ne peut pas s'arrêter tant qu'une condition de workflow n'est pas remplie — mais les **mécanismes** diffèrent. Le tableau ci-dessous résume la situation ; seul Pi présente un comportement visible par l'utilisateur qu'il vaut la peine de comprendre avant d'activer une politique `require-*-before-stop`. +L'application du Stop se présente légèrement différemment selon les six CLI supportés, car chacun expose un contrat de hook différent pour signaler la fin de l'agent. Le **résultat** est le même — l'agent ne peut pas s'arrêter tant qu'une condition de workflow n'est pas satisfaite — mais les **mécanismes** diffèrent. Le tableau ci-dessous résume la situation ; seul Pi présente une particularité visible par l'utilisateur qu'il vaut la peine de comprendre avant d'activer une politique `require-*-before-stop`. | CLI | Quand la condition se déclenche | Ce que vous voyez | |---|---|---| -| Claude Code | Même boucle agent, immédiatement | Claude continue à travailler — résout le problème, puis tente à nouveau de terminer. Aucune interruption visible pour vous. | -| Codex | Même boucle agent, immédiatement | Identique à Claude. | -| GitHub Copilot CLI | Même boucle agent, immédiatement | Identique à Claude (utilise le canal de nouvelle tentative `{decision:"block", reason}` de Copilot — vérifié empiriquement sur Copilot CLI 1.0.41). | -| Cursor Agent | Même boucle agent, immédiatement | Identique à Claude (utilise le canal `{followup_message}` de Cursor — limité à `loop_limit`, 5 nouvelles tentatives par défaut). | -| OpenCode | Même boucle agent, immédiatement | Identique à Claude (utilise l'appel SDK `client.session.prompt(...)` d'OpenCode routé via `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Prochain tour utilisateur** | **Pi s'arrête visiblement** quand la condition se déclenche — sa boucle agent se termine et vous êtes renvoyé à l'invite. La condition se déclenche ensuite la prochaine fois que vous soumettez une invite : failproofai ajoute une directive `MANDATORY ACTION REQUIRED` au prompt système de ce tour, demandant au LLM de compléter l'étape de workflow (commit, push, etc.) avant de faire ce que vous avez demandé. | +| Claude Code | Même boucle d'agent, immédiatement | Claude continue à travailler — résout le problème, puis tente à nouveau de terminer. Aucune interruption visible pour vous. | +| Codex | Même boucle d'agent, immédiatement | Identique à Claude. | +| GitHub Copilot CLI | Même boucle d'agent, immédiatement | Identique à Claude (utilise le canal de relance `{decision:"block", reason}` de Copilot — vérifié empiriquement sur Copilot CLI 1.0.41). | +| Cursor Agent | Même boucle d'agent, immédiatement | Identique à Claude (utilise le canal `{followup_message}` de Cursor — plafonné à `loop_limit`, 5 relances par défaut). | +| OpenCode | Même boucle d'agent, immédiatement | Identique à Claude (utilise l'appel SDK `client.session.prompt(...)` d'OpenCode routé via `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Tour utilisateur suivant** | **Pi s'arrête visiblement** quand la condition se déclenche — sa boucle d'agent se termine et vous revenez au prompt. La condition se déclenche alors à la prochaine soumission d'un prompt : failproofai préfixe une directive `MANDATORY ACTION REQUIRED` au prompt système de ce tour, demandant au LLM de compléter l'étape de workflow (commit, push, etc.) avant de faire ce que vous avez demandé. | -**Limitation de Pi.** L'`AgentEndEvent` de Pi (l'équivalent upstream du hook `Stop` de Claude) n'a pas de type Result — au moment où il se déclenche, la boucle agent de Pi a déjà quitté. Pi ne peut pas être forcé à réessayer la même boucle comme Claude / Copilot / Cursor / OpenCode le peuvent. failproofai déplace la condition vers l'événement `before_agent_start` de Pi (qui se déclenche après la prochaine invite utilisateur) afin que la vérification de workflow s'applique quand même, simplement au tour suivant plutôt qu'au tour courant. +**Limitation de Pi.** L'`AgentEndEvent` de Pi (l'équivalent amont du hook `Stop` de Claude) n'a pas de type Result — au moment où il se déclenche, la boucle d'agent de Pi s'est déjà terminée. Pi ne peut pas être forcé à relancer la même boucle comme Claude / Copilot / Cursor / OpenCode. failproofai déplace la condition vers l'événement `before_agent_start` de Pi (qui se déclenche après le prochain prompt utilisateur) afin que la vérification du workflow soit toujours appliquée, simplement au tour suivant plutôt qu'au tour actuel. **Ce que cela signifie en pratique :** -- Après l'arrêt de Pi, la raison du refus est capturée en mémoire, indexée par l'id de session Pi. La toute prochaine invite que vous soumettez dans le même processus Pi la draine : le LLM voit la directive `MANDATORY ACTION REQUIRED` en haut de son prompt système, effectue le commit (ou le push / ouvre la PR / attend le CI), puis continue avec votre demande. La raison du refus capturée est à usage unique — une fois drainée, la condition est levée. -- La condition est bornée par la durée de vie du processus Pi. Si vous faites `Ctrl+C` sur Pi ou quittez entre les tours, l'entrée en mémoire est supprimée avec le processus et la condition est manquée. Claude, Copilot, Cursor et OpenCode ont la même limite (arrêter l'agent fait manquer la condition) — Pi le rend simplement plus visible car l'agent quitte visiblement avant que la condition ne se déclenche. -- Un refus en attente est également effacé lors d'un `session_shutdown` pour toute raison (`new` / `resume` / `fork` / `quit`), de sorte qu'une condition obsolète d'une session précédente ne peut pas se propager dans une nouvelle session démarrée dans le même processus Pi. +- Après l'arrêt de Pi, la raison du refus est capturée en mémoire, indexée par l'identifiant de session Pi. Le tout prochain prompt soumis dans le même processus Pi la consomme : le LLM voit la directive `MANDATORY ACTION REQUIRED` en haut de son prompt système, effectue le commit (ou le push / ouvre la PR / attend le CI), et ne continue avec votre demande qu'ensuite. La raison de refus capturée est à usage unique — une fois consommée, la condition est levée. +- La condition est limitée à la durée de vie du processus Pi. Si vous faites `Ctrl+C` sur Pi ou quittez entre deux tours, l'entrée en mémoire est supprimée avec le processus et la condition est manquée. Claude, Copilot, Cursor et OpenCode ont la même limite (tuer l'agent fait manquer la condition) — Pi le rend simplement plus visible parce que l'agent se termine visiblement avant que la condition ne se déclenche. +- Un refus en attente est également effacé à l'événement `session_shutdown` pour toute raison (`new` / `resume` / `fork` / `quit`), de sorte qu'une condition périmée d'une session précédente ne peut pas s'infiltrer dans une nouvelle session démarrée dans le même processus Pi. -Si vous avez besoin d'une nouvelle tentative dans la même boucle comme avec Claude, exécutez vos politiques `Stop` sous l'une des cinq autres CLI supportées. Nous suivons Pi en amont pour un futur type Result sur `AgentEndEvent` qui nous permettrait de combler cet écart. +Si vous avez besoin d'une relance dans la même boucle à la manière de Claude, exécutez vos politiques `Stop` sous l'un des cinq autres CLI supportés. Nous suivons l'évolution de Pi en amont pour un futur type Result sur `AgentEndEvent` qui nous permettrait de combler cet écart. ### `require-commit-before-stop` **Événement :** Stop -**Comportement par défaut :** Refuse l'arrêt lorsqu'il y a des modifications non commitées (fichiers modifiés, indexés ou non suivis). Renvoie un message informatif lorsque le répertoire de travail est propre. +**Par défaut :** Refuse l'arrêt lorsqu'il y a des modifications non committées (fichiers modifiés, en stage ou non suivis). Renvoie un message informatif quand le répertoire de travail est propre. Aucun paramètre. @@ -758,11 +758,11 @@ Aucun paramètre. ### `require-push-before-stop` **Événement :** Stop -**Comportement par défaut :** Refuse l'arrêt lorsqu'il y a des commits non poussés ou lorsque la branche courante n'a pas de branche de suivi distante. Suggère `git push -u` pour créer une branche de suivi si nécessaire. Fail-open si aucun remote n'est configuré. +**Par défaut :** Refuse l'arrêt lorsqu'il y a des commits non poussés ou lorsque la branche courante n'a pas de branche de suivi distante. Suggère `git push -u` pour créer une branche de suivi si nécessaire. Fail-open si aucun remote n'est configuré. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| | `remote` | `string` | `"origin"` | Nom du remote vers lequel pousser. | @@ -783,13 +783,13 @@ Aucun paramètre. ### `require-pr-before-stop` **Événement :** Stop -**Comportement par défaut :** Refuse l'arrêt lorsqu'aucune pull request n'existe pour la branche courante, ou lorsque la PR existante est fermée sans avoir été fusionnée. Demande à Claude de créer une PR avec `gh pr create`. Lorsque la PR est **fusionnée**, la politique autorise (le travail est livré) et le message suggère de quitter la branche (`git checkout main && git pull`). +**Par défaut :** Refuse l'arrêt lorsqu'aucune pull request n'existe pour la branche courante, ou lorsque la PR existante est fermée sans être fusionnée. Demande à Claude de créer une PR avec `gh pr create`. Quand la PR est **fusionnée**, la politique autorise (le travail a été livré) et le message suggère de revenir sur la branche principale (`git checkout main && git pull`). Aucun paramètre. Cette politique nécessite que [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. -Exécutez `gh auth login` avec un token d'accès personnel ayant la portée `repo` pour un accès en lecture aux pull requests. Si `gh` n'est pas installé ou pas authentifié, la politique est fail-open et rapporte la raison à Claude. +Exécutez `gh auth login` avec un personal access token ayant la portée `repo` pour l'accès en lecture aux pull requests. Si `gh` n'est pas installé ou pas authentifié, la politique est fail-open et en informe Claude. --- @@ -797,24 +797,21 @@ Exécutez `gh auth login` avec un token d'accès personnel ayant la portée `rep ### `require-no-conflicts-before-stop` **Événement :** Stop -**Comportement par défaut :** Refuse l'arrêt lorsque la branche courante ne peut pas fusionner proprement dans la branche de base. La politique vérifie d'abord qu'il existe une PR `OPEN` sur GitHub pour la branche — sans cela, il n'y a pas de cible de fusion à appliquer, donc toute la politique court-circuite vers allow. Une fois qu'une PR `OPEN` est confirmée, deux sondes indépendantes s'exécutent : +**Par défaut :** Refuse l'arrêt lorsque la branche courante ne peut pas être fusionnée proprement dans la branche de base. La politique confirme d'abord qu'il existe une PR `OPEN` sur GitHub pour la branche — sans cela, il n'y a pas de cible de fusion à imposer, donc toute la politique court-circuite vers l'autorisation. Une fois une PR `OPEN` confirmée, deux sondes indépendantes s'exécutent : -1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. En cas de conflit, le message de refus liste les fichiers en conflit afin que Claude sache exactement quoi résoudre. -2. **GitHub** — réutilise le résultat de `gh pr view --json mergeable,state` déjà récupéré lors de la vérification préalable. Détecte les conflits qu'un `origin/` local obsolète manquerait (p. ex. si quelqu'un a fusionné une PR conflictuelle sur `main` depuis le dernier fetch). Un résultat `CONFLICTING` refuse. Un résultat `UNKNOWN` refuse également et demande à Claude d'attendre ~10 secondes et de revérifier avant de tenter de s'arrêter à nouveau — cela évite les faux négatifs pendant que GitHub recalcule. +1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. En cas de conflit, le message de refus liste les fichiers conflictuels afin que Claude sache exactement quoi résoudre. +2. **GitHub** — réutilise le résultat de `gh pr view --json mergeable,state` déjà récupéré lors de la vérification préalable. Détecte les conflits qu'un `origin/` local périmé manquerait (par ex. si quelqu'un a fusionné une PR conflictuelle sur `main` depuis le dernier fetch). Un résultat `CONFLICTING` entraîne un refus. Un résultat `UNKNOWN` entraîne également un refus et demande à Claude d'attendre ~10 secondes et de revérifier avant de tenter à nouveau de s'arrêter — cela évite les faux négatifs pendant que GitHub recalcule. -Ignore entièrement (autorise) lorsque : `gh` n'est pas installé, aucune PR n'existe pour la branche, l'état de la PR n'est pas `OPEN` (p. ex. `MERGED`, `CLOSED`), ou `gh pr view` renvoie une sortie non analysable. Fail-open également lorsque `origin/` est absent localement ou lorsqu'aucun commit n'est en avance sur la base — ces replis de couche 1 consultent quand même la fusionnabilité de la PR mise en cache avant d'autoriser. +Ignore complètement (autorise) quand : `gh` n'est pas installé, aucune PR n'existe pour la branche, l'état de la PR n'est pas `OPEN` (par ex. `MERGED`, `CLOSED`), ou `gh pr view` renvoie une sortie non analysable. Également fail-open quand `origin/` est absent localement ou quand aucun commit n'est en avance sur la base — ces échappées de couche 1 consultent tout de même la fusionnabilité PR mise en cache avant d'autoriser. **Paramètres :** -| Paramètre | Type | Défaut | Description | +| Paramètre | Type | Par défaut | Description | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Branche de base contre laquelle vérifier les conflits. | +| `baseBranch` | `string` | `"main"` | Branche de base par rapport à laquelle vérifier les conflits. | -GitHub CLI (`gh`) est requis pour cette politique. La politique utilise `gh pr view` pour confirmer -l'existence d'une PR `OPEN` avant d'exécuter toute sonde de conflit — sans `gh`, la politique -court-circuite vers allow. Exécutez `gh auth login` avec un token d'accès personnel ayant la portée -`repo` pour un accès en lecture aux pull requests. +GitHub CLI (`gh`) est requis pour cette politique. La politique utilise `gh pr view` pour confirmer l'existence d'une PR `OPEN` avant d'exécuter toute sonde de conflit — sans `gh`, la politique court-circuite vers l'autorisation. Exécutez `gh auth login` avec un personal access token ayant la portée `repo` pour l'accès en lecture aux pull requests. --- @@ -822,13 +819,13 @@ court-circuite vers allow. Exécutez `gh auth login` avec un token d'accès pers ### `require-ci-green-before-stop` **Événement :** Stop -**Comportement par défaut :** Refuse l'arrêt lorsque les vérifications CI échouent ou sont encore en cours sur la branche courante. Vérifie à la fois les exécutions de workflow GitHub Actions et les vérifications de bots tiers (p. ex. CodeRabbit, SonarCloud, Codecov). Traite les conclusions `skipped`, `cancelled` et `neutral` comme non-échouantes (ce dernier couvre p. ex. les alertes Socket Security sur les PRs de contributeurs externes, où l'application rapporte intentionnellement neutral plutôt que success/failure). Renvoie un message informatif lorsque toutes les vérifications passent. +**Par défaut :** Refuse l'arrêt lorsque les vérifications CI échouent ou sont toujours en cours sur la branche courante. Vérifie à la fois les exécutions de workflow GitHub Actions et les vérifications de bots tiers (par ex. CodeRabbit, SonarCloud, Codecov). Traite les conclusions `skipped`, `cancelled` et `neutral` comme non-échecs (ce dernier couvre par ex. les alertes Socket Security sur les PR de contributeurs externes, où l'application signale intentionnellement neutral plutôt que success/failure). Renvoie un message informatif quand toutes les vérifications sont réussies. Aucun paramètre. Cette politique nécessite que [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. -Exécutez `gh auth login` avec un token d'accès personnel ayant la portée `repo` pour un accès en lecture aux exécutions de workflow Actions et à l'API Checks. Si `gh` n'est pas installé ou pas authentifié, la politique est fail-open et rapporte la raison à Claude. +Exécutez `gh auth login` avec un personal access token ayant la portée `repo` pour l'accès en lecture aux exécutions de workflow Actions et à l'API Checks. Si `gh` n'est pas installé ou pas authentifié, la politique est fail-open et en informe Claude. --- @@ -837,7 +834,7 @@ Exécutez `gh auth login` avec un token d'accès personnel ayant la portée `rep ## Désactiver des politiques individuelles -Retirez une politique spécifique de `enabledPolicies` dans votre configuration, ou désactivez-la dans l'onglet Politiques du tableau de bord. +Retirez une politique spécifique de `enabledPolicies` dans votre configuration, ou désactivez-la depuis l'onglet Politiques du tableau de bord. ```json { diff --git a/docs/fr/cli/audit.mdx b/docs/fr/cli/audit.mdx index bccee050..6b364397 100644 --- a/docs/fr/cli/audit.mdx +++ b/docs/fr/cli/audit.mdx @@ -1,20 +1,20 @@ --- title: Auditer les sessions passées (bêta) -description: "Comptez combien de fois l'agent a effectué des actions inutiles ou risquées dans les transcriptions passées" +description: "Comptez la fréquence des actions inutiles ou risquées de l'agent dans les transcriptions passées" --- - **Fonctionnalité bêta.** L'audit est disponible en bêta le temps de recueillir les premiers retours. - Le catalogue de détecteurs et le format du rapport peuvent évoluer avant la prochaine version stable. - N'hésitez pas à ouvrir un ticket si quelque chose vous semble incorrect. + **Fonctionnalité bêta.** L'audit est publié en version bêta pendant la collecte des premiers retours. + Le catalogue de détecteurs et le format du rapport sont susceptibles de changer avant la prochaine version stable. + N'hésitez pas à ouvrir un ticket si quelque chose semble incorrect. L'audit rejoue vos transcriptions passées de l'agent CLI à travers le moteur de politiques de failproofai -et génère un rapport visuel et partageable sur la **page du tableau de bord `/audit`** — l'archétype de votre agent, un score de 0 à 100, et précisément quelles politiques auraient détecté quoi. +et génère un rapport visuel et partageable sur la **page du tableau de bord `/audit`** — l'archétype de votre agent, un score de 0 à 100, et exactement quelles politiques auraient détecté quoi. ## Lancer l'audit -Trois façons d'accéder — toutes aboutissent au même rapport `/audit`. +Trois façons de démarrer — toutes aboutissent au même rapport `/audit`. @@ -34,93 +34,96 @@ failproofai - `npx -y failproofai audit` télécharge failproofai, lance le scan et ouvre le + `npx -y failproofai audit` télécharge failproofai, lance l'analyse et ouvre le tableau de bord automatiquement — rien à installer au préalable. - - `failproofai audit` exécute le scan dans votre terminal, puis ouvre - `localhost:8020/audit` automatiquement une fois terminé. + + `failproofai audit` lance l'analyse dans votre terminal, puis ouvre + `localhost:8020/audit` automatiquement à la fin. - Lancez `failproofai` et cliquez sur **Audit** dans la barre de navigation (entre Policies et - Projects), ou ouvrez `/audit` directement. + Exécutez `failproofai` et cliquez sur **Audit** dans la barre de navigation (entre Politiques et + Projets), ou ouvrez `/audit` directement. - Exécutez `failproofai audit -h` (ou `--help`) pour afficher l'aide. L'audit fonctionne **entièrement - hors ligne** — aucun compte ni connexion réseau requis — et le tableau de bord reste actif - jusqu'à ce que vous l'arrêtiez avec `Ctrl+C`. + Exécutez `failproofai audit -h` (ou `--help`) pour afficher l'aide. L'audit s'exécute **entièrement + hors ligne** — aucun compte ni réseau requis — et le tableau de bord reste actif jusqu'à + ce que vous l'arrêtiez avec `Ctrl+C`. -Le tableau de bord analyse les transcriptions passées de l'agent CLI sur cette machine (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) et indique la fréquence à laquelle l'agent a effectué des actions que failproofai est conçu pour bloquer — vérifications de variables d'environnement, push forcés, préfixes `cd ` redondants, boucles de polling par sleep, re-lecture de fichiers venants d'être modifiés, et bien plus. +Le tableau de bord analyse les transcriptions passées de l'agent CLI sur cette machine (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) et indique la fréquence à laquelle l'agent a accompli des actions que failproofai est conçu pour bloquer — vérifications de variables d'environnement, push forcés, préfixes `cd ` redondants, boucles de polling avec sleep, relecture de fichiers venants d'être modifiés, et bien plus. -Pour chaque transcription, chaque événement d'utilisation d'outil est rejoué à travers les 39 politiques intégrées **et** à travers 8 détecteurs propres à l'audit qui repèrent des patterns non encore couverts par les politiques en temps réel. Les comptages sont agrégés par politique / détecteur sur l'ensemble des sessions. +Pour chaque transcription, chaque événement d'utilisation d'outil est rejoué à travers les 39 politiques intégrées **et** 8 détecteurs réservés à l'audit qui repèrent des schémas non encore couverts par les politiques en temps réel. Les occurrences sont agrégées par politique / détecteur sur l'ensemble des sessions. ## Ce que vous obtenez -La page `/audit` est une **affiche** pleine page et partageable, suivie de quatre sections sous le pli : +La page `/audit` est une **affiche** en plein écran et partageable, suivie de quatre sections sous le pli : -1. **Affiche** — l'identité de votre agent en un coup d'œil : son **archétype** (l'un des 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), ses mots-clés de persona, la rareté de cet archétype, et un **score de 0 à 100** avec un niveau (`S` jusqu'à `bottom tier`). Conçue pour être partagée — postez sur X ou LinkedIn, ou téléchargez en PNG. -2. **`// strengths`** — ce que votre agent fait déjà bien, exprimé en chiffres réels issus du scan (ex. : taux de tool-call propres, `0` tentative de push vers main), affiché uniquement lorsque la politique concernée n'a aucune infraction. -3. **`// quirks`** — ce qui s'est glissé : un tableau classé des comportements que failproofai aurait interceptés — *quand* cela s'est produit pour la dernière fois, *ce qui a glissé* (et la règle intégrée qui l'aurait bloqué), sa *sévérité*, et la fréquence d'apparition (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — la liste des correctifs recommandés : une ligne par politique avec un `failproofai policy add ` à copier-coller, plus un bouton **install all** qui active toutes les recommandations d'un coup et affiche votre **score projeté** si vous le faites. -5. **`// come back better`** — adoptez la bonne habitude : configurez un **rappel** par e-mail (`3d` / `7d` / `14d` / `30d`) ou relancez l'audit maintenant, et **invitez un ami** à effectuer son propre audit (envoyé depuis failproof.ai, avec vous en Cc). Les rappels et invitations nécessitent une connexion. +1. **Affiche** — l'identité de votre agent en un coup d'œil : son **archétype** (l'un des 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), ses mots-clés de persona, la rareté de cet archétype, et un **score de 0 à 100** avec un niveau associé (`S` jusqu'à `bottom tier`). Conçue pour être partagée — publiez-la sur X ou LinkedIn, ou téléchargez-la en PNG. +2. **`// strengths`** — ce que votre agent fait déjà bien, exprimé en chiffres réels issus de l'analyse (ex. : pourcentage d'appels d'outils propres, `0` tentative de push vers main), affiché uniquement lorsque la politique concernée présente un bilan irréprochable. +3. **`// quirks`** — ce qui a glissé à travers les mailles : un tableau classé des comportements que failproofai aurait interceptés — *quand* c'est arrivé pour la dernière fois, *ce qui a échappé* (et la règle intégrée qui l'aurait bloqué), sa *gravité*, et la fréquence observée (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — la liste des correctifs prescrits : une ligne par politique avec un `failproofai policy add ` prêt à copier-coller, plus un bouton **install all** qui active toutes les recommandations en une fois et affiche votre **score projeté** si vous les appliquiez toutes. +5. **`// come back better`** — ancrez la bonne habitude : définissez un **rappel** par e-mail pour un nouvel audit (`3d` / `7d` / `14d` / `30d`) ou relancez l'audit immédiatement, et **invitez un ami** à effectuer son propre audit (envoyé depuis failproof.ai, avec copie à vous). Rappels et invitations nécessitent une connexion. ## Audits planifiés -Si vous faites tourner le **démon failproofaid** (voir [`failproofai config`](/fr/cli/install-policies)), -il peut relancer l'audit selon un calendrier et rafraîchir le rapport `/audit` en -arrière-plan. Cette option est **désactivée par défaut**, car le scan lit le *contenu* -de chaque transcription de session de l'agent sur cette machine — rien ne scanne de façon planifiée -tant que vous ne le demandez pas. - -Activez-la dans `~/.failproofai/config.toml` : - -```toml -[audit] -auto = true -interval_days = 7 +Si vous exécutez le **démon failproofaid** (voir [`failproofai config`](/fr/cli/install-policies)), +il peut relancer l'audit automatiquement selon un calendrier et actualiser le rapport `/audit` en +arrière-plan. Cette fonctionnalité est **désactivée par défaut**, car l'analyse lit le *contenu* +de chaque transcription de session d'agent sur cette machine — rien n'est analysé de façon programmée +tant que vous ne le demandez pas explicitement. + +Activez-la dans `~/.failproofai/config.json` — ajoutez la clé `audit` à côté de +ce que le fichier contient déjà : + +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | Clé | Signification | |---|---| -| `auto` | `true` active le scan planifié. Toute autre valeur — absente, `false`, `"yes"` — désactive la fonctionnalité. | -| `interval_days` | Jours entre les scans. Limité à 1–90 ; `0`, une valeur négative ou non numérique revient à `7`. | +| `auto` | `true` active l'analyse planifiée. Toute autre valeur — absente, `false`, `"yes"` — désactive la fonctionnalité. | +| `interval_days` | Nombre de jours entre les analyses. Limité à 1–90 ; `0`, une valeur négative ou non numérique revient à `7`. | -- Le calendrier est basé sur **l'horloge murale**, ce qui lui permet de survivre aux suspensions et redémarrages : un ordinateur portable qui était en veille au-delà de son heure prévue s'exécute **une seule fois** au réveil, sans rattrapage en file. -- Chaque exécution est un processus distinct à faible priorité (`nice 19`) — jamais sur le chemin des hooks du démon, qui reste libre pour répondre aux appels d'outils. -- Un scan est ignoré si `failproofai audit` ou la relance depuis le tableau de bord est déjà en cours ; il est retenté peu après plutôt que traité comme un échec. -- La progression est écrite dans `~/.failproofai/state/audit-schedule.json` (dernière exécution, prochaine échéance). Ce fichier appartient au démon — modifiez la cadence dans `config.toml`. +- Le planning est basé sur **l'horloge murale**, il survit donc aux mises en veille et aux redémarrages : un ordinateur portable qui était en veille au-delà de son heure prévue exécute l'analyse **une seule fois** au réveil, sans rattraper les passages manqués. +- Chaque exécution est un processus distinct de basse priorité (`nice 19`) — jamais sur le chemin des hooks du démon, qui reste libre de répondre aux appels d'outils. +- Une analyse est ignorée si `failproofai audit` ou le relancement depuis le tableau de bord est déjà en cours ; elle est retentée peu après plutôt que considérée comme un échec. +- La progression est écrite dans `~/.failproofai/state/audit-schedule.json` (dernière exécution, prochaine échéance). Le démon possède ce fichier — modifiez la cadence dans `config.json`. -Si vous avez activé cette option sur une machine configurée avec une ancienne version de failproofai, exécutez -`failproofai config` une fois. La définition de service du démon nécessite une entrée supplémentaire -avant de pouvoir lancer la CLI, et le rafraîchissement fait partie de cette commande. +Si vous avez activé cette fonctionnalité sur une machine configurée avec une ancienne version de failproofai, exécutez +`failproofai config` une fois. La définition de service du démon nécessite une entrée supplémentaire avant de pouvoir lancer le CLI, et cette mise à jour fait partie de cette commande. -## Détecteurs propres à l'audit +## Détecteurs réservés à l'audit -Ces détecteurs repèrent des patterns de « comportement inefficace » pas encore appliqués en temps réel. Ils ne s'exécutent que lors de l'audit et ne bloquent jamais un appel d'outil en direct. +Ces détecteurs identifient des schémas de « comportement inutile » qui ne sont pas (encore) appliqués en temps réel. Ils s'exécutent uniquement lors de l'audit et ne bloquent jamais un appel d'outil en direct. -| Détecteur | Ce qu'il compte | +| Détecteur | Ce qu'il comptabilise | |---|---| | `redundant-cd-cwd` | Commandes Bash commençant par `cd && …` alors que les commandes s'exécutent déjà dans `cwd`. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` sur un seul fichier source — utilisez l'outil `Read`. | -| `prefer-edit-over-sed-awk` | Modifications en place avec `sed -i` / `awk … > file` — utilisez l'outil `Edit`. | -| `prefer-write-over-heredoc` | Écriture de fichiers via heredoc / `echo > file` multiligne — utilisez l'outil `Write`. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` sur un fichier source unique — utilisez plutôt l'outil `Read`. | +| `prefer-edit-over-sed-awk` | Modifications en place avec `sed -i` / `awk … > file` — utilisez plutôt l'outil `Edit`. | +| `prefer-write-over-heredoc` | Écriture de fichiers via heredoc / `echo > file` multiligne — utilisez plutôt l'outil `Write`. | | `sleep-polling-loop` | Long `sleep N` (≥ 30s) ou boucles de polling `while …; sleep …; done`. | | `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — limitez la portée à `cwd`. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, en sautant les hooks. | -| `reread-after-edit` | `Read` d'un fichier qui vient d'être modifié par `Edit`/`Write` dans la même session. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, qui contourne les hooks. | +| `reread-after-edit` | Lecture (`Read`) d'un fichier qui vient d'être modifié par `Edit`/`Write` dans la même session. | ## Caches -- **Cache par transcription** dans `~/.failproofai/cache/audit/.json` indexé par `(mtime, size, engineVersion, detectorVersion)` — invalidé automatiquement lorsque la transcription ou le code de politique/détecteur change. Chaque entrée stocke également un horodatage `cachedAt` comme **métadonnées TTL** (non incluses dans la clé de cache) ; les entrées de plus de **7 jours** sont rejetées à la lecture afin que des résultats anciens ne survivent pas à l'évolution des détecteurs. -- **Cache du résultat global** dans `~/.failproofai/audit-dashboard.json` (mode 0600). Permet au tableau de bord de s'afficher instantanément lors de la navigation sans relancer le scan. Également rejeté à la lecture au-delà du **TTL de 7 jours** — `/audit` revient alors à son état vide et invite à relancer une analyse fraîche. Cliquez sur `[ re-audit now ]` en bas du rapport pour actualiser — la relance envoie `noCache: true`, ce qui contourne le cache par transcription et rescanne toutes les transcriptions au lieu de retourner le résultat mis en cache ; l'exécution diffuse sa progression via une bannière persistante en haut et remplace le résultat en place en cas de succès (sans rechargement de page ; un échec de la relance conserve le rapport précédent). +- **Cache par transcription** dans `~/.failproofai/cache/audit/.json`, indexé par `(mtime, size, engineVersion, detectorVersion)` — invalidé automatiquement lorsque la transcription ou le code des politiques/détecteurs change. Chaque entrée stocke également un horodatage `cachedAt` comme **métadonnée TTL** (non incluse dans la clé de cache) ; les entrées de plus de **7 jours** sont rejetées à la lecture pour éviter que des résultats persistants ne survivent à l'évolution de l'intention des détecteurs. +- **Cache du résultat global** dans `~/.failproofai/audit-dashboard.json` (mode 0600). Permet au tableau de bord de s'afficher instantanément à la navigation sans relancer l'analyse. Également rejeté à la lecture après une **TTL de 7 jours** — `/audit` revient alors à son état vide et invite à relancer une analyse. Cliquez sur `[ re-audit now ]` en bas du rapport pour actualiser — le nouvel audit envoie `noCache: true`, ce qui contourne le cache par transcription et réanalyse chaque transcription au lieu de retourner le résultat mis en cache ; l'exécution diffuse sa progression via un bandeau fixe en haut de page et remplace le résultat en place en cas de succès (sans rechargement de page ; un audit échoué conserve le rapport précédent). ## Remarques -- **Aucune mutation.** L'audit se rejoue en mode lecture seule. `warn-repeated-tool-calls` est ignoré car son fichier annexe par session serait sinon modifié. -- **Politiques de workflow ignorées.** Les politiques `require-*-before-stop` ne se déclenchent que sur les événements `Stop` et s'exécutent via `execSync` contre l'état git en direct — elles n'ont pas d'interprétation significative du type « qu'aurait-il pu se passer en 2025 », et n'apparaissent donc pas dans les comptages d'audit. -- **Politiques personnalisées ignorées.** Les hooks personnalisés fournis par l'utilisateur ne sont pas rejoués (ils peuvent avoir changé depuis la session d'origine). \ No newline at end of file +- **Aucune modification.** L'audit s'exécute en mode lecture seule. `warn-repeated-tool-calls` est ignoré car son fichier sidecar par session serait autrement modifié. +- **Politiques de flux de travail ignorées.** Les politiques `require-*-before-stop` se déclenchent uniquement sur les événements `Stop` et effectuent un `execSync` sur l'état git en direct — elles n'ont pas d'interprétation significative du type « que se serait-il passé en 2025 », et n'apparaissent donc pas dans les comptages de l'audit. +- **Politiques personnalisées ignorées.** Les hooks personnalisés fournis par l'utilisateur ne sont pas rejoués (ils ont pu changer depuis la session d'origine). \ No newline at end of file diff --git a/docs/fr/cli/dashboard.mdx b/docs/fr/cli/dashboard.mdx index 13b61ab2..fe6c3c20 100644 --- a/docs/fr/cli/dashboard.mdx +++ b/docs/fr/cli/dashboard.mdx @@ -7,7 +7,7 @@ description: "Lancer le tableau de bord pour parcourir les sessions d'agents et failproofai ``` -Lance le tableau de bord web sur `http://localhost:8020`. +Démarre le tableau de bord web à `http://localhost:8020`. ## Options @@ -16,7 +16,7 @@ Lance le tableau de bord web sur `http://localhost:8020`. | `--port ` | Port d'écoute (par défaut : `8020`) | | `--allowed-origins ` | Hôtes/IPs séparés par des virgules autorisés à accéder aux ressources de développement | -Pour pointer le tableau de bord vers un dossier de projet Claude non par défaut, définissez la variable d'environnement `CLAUDE_PROJECTS_PATH` au lancement. +Pour pointer le tableau de bord vers un dossier de projet Claude non-standard, définissez la variable d'environnement `CLAUDE_PROJECTS_PATH` au lancement. ## Exemples diff --git a/docs/fr/cli/environment-variables.mdx b/docs/fr/cli/environment-variables.mdx index 984a9bac..7e061602 100644 --- a/docs/fr/cli/environment-variables.mdx +++ b/docs/fr/cli/environment-variables.mdx @@ -7,64 +7,69 @@ description: "Configurer le comportement de failproofai avec des variables d'env | Variable | Description | |----------|-------------| -| `PORT` | Port du tableau de bord (défaut : `8020`) | -| `CLAUDE_PROJECTS_PATH` | Remplace l'emplacement où sont recherchés les dossiers de projets Claude Code | +| `PORT` | Port du tableau de bord (par défaut : `8020`) | +| `CLAUDE_PROJECTS_PATH` | Remplacer l'emplacement où sont trouvés les dossiers de projets Claude Code | | `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Pages du tableau de bord à masquer, séparées par des virgules | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hôtes/IPs autorisés à accéder aux ressources de développement. Équivalent à `--allowed-origins`. | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hôtes/IPs autorisés à accéder aux ressources de développement. Identique à `--allowed-origins`. | ## Journalisation | Variable | Description | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Niveau de journalisation du serveur (défaut : `warn`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Niveau de journalisation du serveur (par défaut : `warn`) | | `FAILPROOFAI_HOOK_LOG_FILE` | Chemin personnalisé du fichier de journal des hooks, ou `true` pour le chemin par défaut (`~/.failproofai/logs/hooks.log`) | ## Télémétrie -failproofai envoie par défaut des données de télémétrie d'utilisation anonymes. Il existe deux façons de -la désactiver, et c'est la plus restrictive qui s'applique — une variable d'environnement -ne peut jamais réactiver ce que le fichier de configuration a désactivé. +failproofai transmet par défaut des données de télémétrie d'utilisation anonymes. Il existe deux façons de +la désactiver, et c'est toujours la valeur la plus restrictive qui s'applique — une variable +d'environnement ne peut jamais réactiver ce que le fichier de configuration a désactivé. | Variable | Description | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Désactive la télémétrie d'utilisation anonyme pour ce processus | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Désactiver la télémétrie d'utilisation anonyme pour ce processus | -Pour la désactiver définitivement sur la machine, ajoutez ceci dans `~/.failproofai/config.toml` : +Pour la désactiver de façon permanente sur la machine, ajoutez ceci dans `~/.failproofai/config.json` : -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -Le fichier de configuration est l'option à utiliser si vous exécutez le **démon failproofaid**. -Le démon est un service à portée système, et son environnement n'inclut pas -les variables exportées depuis votre shell — `FAILPROOFAI_TELEMETRY_DISABLED` ne peut donc pas -l'atteindre. `[telemetry] enabled = false` est lu aussi bien par le CLI que par le démon. +Le fichier de configuration est l'option à utiliser si vous exécutez le **daemon failproofaid**. +Le daemon est un service à portée système, et son environnement n'inclut pas +les variables exportées depuis votre shell — `FAILPROOFAI_TELEMETRY_DISABLED` ne peut donc +pas l'atteindre. `[telemetry] enabled = false` est lu à la fois par le CLI et par le daemon. -Le démon ne rapporte que son propre **cycle de vie** : le fait qu'il a démarré (et si -l'exécution précédente s'est terminée proprement), qu'il s'est arrêté, quand son worker d'évaluation a été +Le daemon ne rapporte que son propre cycle de vie **lifecycle** : qu'il a démarré (et si le +précédent processus s'est terminé proprement), qu'il s'est arrêté, quand son worker d'évaluation a été lancé ou redémarré, quand une tâche de collecte a échoué, et le résultat d'une -récupération de politique cloud. Ces données ne contiennent que des valeurs et des compteurs à faible cardinalité — jamais un chemin de fichier, une commande, une politique, une invite ou quoi que ce soit extrait d'une transcription. Il n'y a aucun événement par appel d'outil. +récupération de politique cloud. Ces données contiennent des valeurs et des compteurs à faible cardinalité — jamais un chemin de fichier, +une commande, une politique, une invite ou quoi que ce soit lu dans une transcription. Il +n'existe aucun événement par appel d'outil. ## Authentification | Variable | Description | |----------|-------------| -| `FAILPROOF_API_URL` | Remplace l'URL de base du serveur API utilisée par la boîte de dialogue d'authentification du tableau de bord. Par défaut `https://api.befailproof.ai` ; à définir sur `http://localhost:8080` (ou autre) lors de l'exécution d'un serveur API local. | -| `FAILPROOFAI_AUTH_DIR` | Remplace l'emplacement de stockage de `auth.json` (défaut : `~/.failproofai`). Principalement utile pour des tests isolés. | +| `FAILPROOF_API_URL` | Remplacer l'URL de base du serveur API utilisée par la boîte de dialogue d'authentification du tableau de bord. Par défaut : `https://api.befailproof.ai` ; définir sur `http://localhost:8080` (ou autre) lors de l'exécution d'un serveur API local. | +| `FAILPROOFAI_AUTH_DIR` | Remplacer l'emplacement de stockage de `auth.json` (par défaut : `~/.failproofai`). Principalement utile pour les tests isolés. | -## Invite de premier démarrage +## Invite au premier lancement | Variable | Description | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignore l'invite proposant d'installer des politiques lors du premier appel nu à `failproofai` | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignorer l'invite proposant d'installer des politiques lors du premier appel à failproofai sans arguments | ## LLM (pour l'évaluation des politiques) | Variable | Description | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | Point de terminaison de l'API LLM (défaut : `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Clé API pour les politiques basées sur un LLM | -| `FAILPROOFAI_LLM_MODEL` | Nom du modèle (défaut : `gpt-4o-mini`) | \ No newline at end of file +| `FAILPROOFAI_LLM_BASE_URL` | Point de terminaison de l'API LLM (par défaut : `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | Clé API pour les politiques basées sur le LLM | +| `FAILPROOFAI_LLM_MODEL` | Nom du modèle (par défaut : `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/fr/cli/hook.mdx b/docs/fr/cli/hook.mdx index 35c7fb59..5a27f669 100644 --- a/docs/fr/cli/hook.mdx +++ b/docs/fr/cli/hook.mdx @@ -1,5 +1,5 @@ --- -title: Hook handler (interne) +title: Gestionnaire de hooks (interne) description: "Le sous-processus que Claude Code appelle à chaque événement d'outil" --- @@ -9,13 +9,13 @@ failproofai --hook Il s'agit de la commande enregistrée dans le fichier `settings.json` de Claude Code par `failproofai policies --install`. Vous n'avez normalement pas à l'appeler directement. -Lit un payload JSON depuis stdin, évalue toutes les politiques activées, et se termine avec un code indiquant la décision : +Lit un payload JSON depuis stdin, évalue toutes les politiques activées, puis se termine avec un code indiquant la décision : | Code de sortie | Décision | Effet | |----------------|----------|-------| -| `0` | `allow` | Autorise l'action | -| `1` | `deny` | Bloque l'action — Claude reçoit le motif du refus | -| `2` | `instruct` | Injecte des instructions dans le contexte de Claude | +| `0` | `allow` | Autoriser l'action | +| `1` | `deny` | Bloquer l'action — Claude reçoit le motif du refus | +| `2` | `instruct` | Injecter des instructions dans le contexte de Claude | ### Types d'événements pris en charge diff --git a/docs/fr/cli/install-policies.mdx b/docs/fr/cli/install-policies.mdx index f320be90..09b36ae1 100644 --- a/docs/fr/cli/install-policies.mdx +++ b/docs/fr/cli/install-policies.mdx @@ -1,13 +1,13 @@ --- title: Installer les politiques -description: "Activer les politiques pour qu'elles s'exécutent à chaque appel d'outil de l'agent" +description: "Activer les politiques afin qu'elles s'exécutent à chaque appel d'outil de l'agent" --- ```bash failproofai policies --install [policy-names...] [options] ``` -Écrit des entrées de hook dans le fichier de paramètres de votre CLI d'agent installé (Claude Code, OpenAI Codex ou GitHub Copilot CLI _(bêta)_) afin que failproofai intercepte les appels d'outils. +Écrit des entrées de hook dans le fichier de paramètres de l'agent CLI installé (Claude Code, OpenAI Codex ou GitHub Copilot CLI _(bêta)_) afin que failproofai intercepte les appels d'outils. Alias : `failproofai p -i` @@ -15,16 +15,16 @@ Alias : `failproofai p -i` | Indicateur | Description | |------------|-------------| -| `--cli claude\|codex\|copilot` | CLI(s) d'agent pour lesquels installer ; séparés par des espaces (ex. `--cli claude codex copilot`) ou répétés. Omettre pour détecter les CLI installés et afficher une invite. | +| `--cli claude\|codex\|copilot` | Agent(s) CLI pour lesquels installer ; séparés par des espaces (ex. `--cli claude codex copilot`) ou répétés. Omettez pour détecter les CLIs installés et être invité à choisir. | | `--scope user` | Installe dans le fichier de paramètres de portée utilisateur (Claude : `~/.claude/settings.json` ; Codex : `~/.codex/hooks.json` ; Copilot : `~/.copilot/hooks/failproofai.json`). Par défaut. | | `--scope project` | Installe dans le fichier de paramètres de portée projet (Claude : `/.claude/settings.json` ; Codex : `/.codex/hooks.json` ; Copilot : `/.github/hooks/failproofai.json`). | -| `--scope local` | Claude uniquement — installe dans `/.claude/settings.local.json`. Codex et Copilot n'ont pas de portée `local`. | +| `--scope local` | Claude uniquement — installe dans `/.claude/settings.local.json`. Codex et Copilot ne disposent pas d'une portée `local`. | | `--custom ` / `-c` | Chemin vers un fichier JS contenant des politiques de hook personnalisées | ## Comportement - **Aucun nom de politique** — ouvre une invite interactive pour sélectionner les politiques -- **Noms spécifiques** — active ces politiques (ajoutées à celles déjà activées) +- **Noms spécifiques** — active ces politiques (s'ajoute à celles déjà activées) - **`all`** — active toutes les politiques disponibles L'installation est additive : exécuter `--install` à nouveau ajoute de nouvelles politiques sans supprimer les existantes. @@ -41,7 +41,7 @@ failproofai policies --install block-sudo sanitize-api-keys --scope project # Activer toutes les politiques en une seule fois failproofai policies --install all -# Installer avec un fichier de politiques personnalisées +# Installer avec un fichier de politiques personnalisé failproofai policies --install --custom ./my-policies.js # Installer pour OpenAI Codex (portée projet) @@ -50,8 +50,8 @@ failproofai policies --install --cli codex --scope project # Installer pour GitHub Copilot CLI (bêta) pour le projet en cours failproofai policies --install --cli copilot --scope project -# Installer pour les trois CLI à la fois +# Installer pour les trois CLIs en même temps failproofai policies --install --cli claude codex copilot ``` -Lorsque `--custom ` est fourni, le fichier est validé immédiatement — il doit appeler `customPolicies.add()` au moins une fois. Le chemin résolu est enregistré dans `policies-config.json` sous la clé `customPoliciesPath`. \ No newline at end of file +Lorsque `--custom ` est fourni, le fichier est validé immédiatement — il doit appeler `customPolicies.add()` au moins une fois. Le chemin résolu est enregistré dans `policies-config.json` sous `customPoliciesPath`. \ No newline at end of file diff --git a/docs/fr/cli/list-policies.mdx b/docs/fr/cli/list-policies.mdx index 47d77ff9..db2cc1fd 100644 --- a/docs/fr/cli/list-policies.mdx +++ b/docs/fr/cli/list-policies.mdx @@ -7,7 +7,7 @@ description: "Voir quelles politiques sont activées, leurs paramètres et les p failproofai policies ``` -Affiche toutes les politiques avec leur statut, les paramètres configurés et les politiques personnalisées. +Affiche toutes les politiques avec leur état, leurs paramètres configurés et les politiques personnalisées. ## Exemple de sortie @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Les clés inconnues dans `policyParams` sont signalées ici afin que vous puissiez détecter les fautes de frappe rapidement. \ No newline at end of file +Les clés inconnues dans `policyParams` sont signalées ici pour vous permettre de détecter les fautes de frappe rapidement. \ No newline at end of file diff --git a/docs/fr/cli/migrate.mdx b/docs/fr/cli/migrate.mdx new file mode 100644 index 00000000..b93b03b1 --- /dev/null +++ b/docs/fr/cli/migrate.mdx @@ -0,0 +1,126 @@ +--- +title: Migrer le répertoire personnel +description: "Mettre ~/.failproofai à jour selon la structure attendue par cette version, et prévisualiser les changements" +--- + +```bash +failproofai migrate --dry-run # afficher le plan, sans rien modifier +failproofai migrate # exécuter la migration +``` + +La plupart des utilisateurs n'ont jamais besoin de taper cette commande. Elle +s'exécute automatiquement au premier lancement après une mise à jour, et +[`failproofai update`](/fr/cli/update) l'inclut également. Utilisez-la directement +quand vous souhaitez voir le plan avant qu'il s'exécute, ou pour lancer la +migration de manière autonome. + +## Basé sur la structure, pas sur la version + +`~/.failproofai/VERSION` enregistre un numéro de **structure** — la forme du +répertoire, et non la version qui l'a créée. Les migrations sont indexées sur ce +numéro, ce qui rend les sauts importants peu coûteux : + +- Les versions npm changent à chaque publication, parfois des dizaines entre deux + structures. +- Ainsi, une machine qui passe trente versions sans **aucun changement de + structure** exécute **zéro** migration, et non trente opérations vides. +- Et une machine qui saute plusieurs structures à la fois exécute chaque étape + dans l'ordre, chacune ne connaissant que ses deux extrémités. + +Cela a son importance car npm ne peut pas mettre à jour un package installé de +lui-même. Une machine restée sur une version pendant des mois avant de sauter +plusieurs structures est le cas courant, pas l'exception. + +## Le mode dry run + +`--dry-run` affiche la chaîne exacte et les fichiers qui seraient sauvegardés au +préalable, sans effectuer aucune modification — ni migration, ni sauvegarde, ni +entrée dans le journal : + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## Ce qui est conservé et ce qui est reconstruit + +Chaque chemin du répertoire personnel indique le type de données qu'il contient, +ce qui détermine si une migration peut le supprimer. La règle : **les données +dérivées et récupérables peuvent être supprimées ; tout ce que vous avez saisi, +tout ce qui n'a pas encore été envoyé, et tout ce qui identifie la machine est +conservé.** + +| Conservé | Reconstruit ou récupéré | +|---|---| +| `config.json` — paramètres, `daemon.configured`, chemins de capture supplémentaires | Le cache d'audit | +| `credentials.json` — votre inscription cloud | Les déploiements gérés par le cloud (récupérés et vérifiés par condensé lors du prochain sondage) | +| `policies-config.json` — votre sélection de politiques et leurs paramètres | L'état temporaire du daemon | +| `policies/` — vos propres fichiers de politiques et les modules qu'ils importent | | +| `hook-activity/` — le journal de décisions lu par le tableau de bord | | +| Les événements non envoyés encore en attente d'envoi | | +| `cursors/` — les filigranes du collecteur | | +| Le binaire du daemon dans `bin/` | | + + + Les événements non envoyés sont conservés plutôt que supprimés car la perte + serait définitive et non simplement retardée : le filigrane du collecteur a déjà + avancé au-delà de tout ce qui se trouve dans la file d'attente, si bien que rien + ne relira jamais cette plage d'une transcription. La migration demande également + au daemon d'envoyer ce qui est en attente dès qu'il a terminé, de sorte que le + résultat habituel est qu'il ne reste rien à conserver. + + +Les clés écrites par une version *plus récente* dans `config.json`, +`credentials.json` ou `policies-config.json` sont également préservées, plutôt que +supprimées par un lecteur plus ancien. + +## Le journal qu'elle laisse + +``` +~/.failproofai/migrations/ + applied.json une entrée par étape : structure, CLI, horodatage, durée, résultat + backup-layout/ copies des fichiers irremplaçables, prises avant la première étape +``` + +`applied.json` répond à la question « par quoi cette machine est-elle réellement +passée » — la première chose à vérifier quand quelque chose semble anormal après +une mise à jour. Joignez-le à un rapport de bogue. + +La sauvegarde est délibérément réduite plutôt que d'être une copie de l'ensemble +du répertoire : la migration ne supprime plus rien d'irremplaçable par conception, +donc ce contre quoi il vaut la peine de se prémunir est un *défaut dans une +étape*, et ces quelques fichiers sont ceux qu'un tel défaut pourrait endommager. + +## Si une étape échoue + +La chaîne s'arrête à cet endroit. `VERSION` n'est mis à jour que par une étape +qui s'est terminée avec succès, si bien que le répertoire reste marqué avec son +ancienne structure et que la commande suivante réessaie — un répertoire n'est +jamais marqué comme à jour sur la base d'une migration partielle. L'étape est +enregistrée dans `applied.json` avec `"ok": false`, et la sauvegarde se trouve là +où elle a été prise. + +## Un répertoire plus récent est refusé, pas migré + +Si `~/.failproofai/` a été écrit par une version de failproofai **plus récente** +que celle que vous exécutez, la commande s'arrête et vous invite à effectuer une +mise à jour. Ces données sont intactes et une CLI plus récente les lit ; les migrer +«vers l'avant» n'est pas quelque chose qui existe, et les réinitialiser détruirait +quelque chose de récupérable. + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +Le daemon applique la même règle : `failproofaid` refuse de démarrer avec une +structure qu'il ne reconnaît pas, plutôt que de lire et d'écrire des chemins qui +ont été déplacés. \ No newline at end of file diff --git a/docs/fr/cli/remove-policies.mdx b/docs/fr/cli/remove-policies.mdx index 8793d5cc..baaa4ecd 100644 --- a/docs/fr/cli/remove-policies.mdx +++ b/docs/fr/cli/remove-policies.mdx @@ -18,13 +18,13 @@ Alias : `failproofai p -u` | `--scope user` | Supprimer des paramètres globaux (par défaut) | | `--scope project` | Supprimer des paramètres du projet | | `--scope local` | Supprimer des paramètres locaux | -| `--scope all` | Supprimer de toutes les portées simultanément | +| `--scope all` | Supprimer de toutes les portées à la fois | | `--custom` / `-c` | Effacer le `customPoliciesPath` de la configuration | ## Comportement - **Aucun nom de politique** — supprime toutes les entrées de hook failproofai du fichier de paramètres -- **Noms spécifiques** — désactive ces politiques tout en conservant les hooks installés +- **Noms spécifiques** — désactive ces politiques mais conserve les hooks installés ## Exemples diff --git a/docs/fr/cli/update.mdx b/docs/fr/cli/update.mdx new file mode 100644 index 00000000..6d45fb5d --- /dev/null +++ b/docs/fr/cli/update.mdx @@ -0,0 +1,64 @@ +--- +title: Mettre à jour après une montée de version +description: "Finalisez la partie de la mise à jour que npm ne peut pas effectuer : migrer le répertoire personnel et synchroniser le daemon" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +Voilà la mise à jour complète. `npm` remplace le CLI ; `failproofai update` s'occupe du reste. + +## Pourquoi une deuxième commande est nécessaire + +`npm install -g` ne remplace qu'une seule chose — le CLI. Deux autres composants d'une installation failproofai résident volontairement en dehors du package, et aucun des deux ne bouge quand npm s'exécute : + +- **`~/.failproofai/`**, vos paramètres, l'enrôlement cloud, la sélection des politiques et l'historique. Une nouvelle version peut les organiser différemment, et cette réorganisation doit être effectuée par du code qui connaît les deux structures. +- **Le binaire du daemon `failproofaid`**, situé dans `~/.failproofai/bin/failproofaid-`. Il n'est délibérément *pas* placé dans `node_modules` : une mise à jour qui remplacerait le fichier sous un service en cours d'exécution réorienterait un daemon actif vers un binaire compilé depuis une source différente, et la suppression du package le retirerait sous un service qui entrerait alors dans une boucle de plantage à chaque démarrage. + +Ainsi, après `npm install -g` seul, le CLI est à jour mais pas le daemon. `failproofaid` refuse de démarrer avec une structure de répertoire personnel qu'il ne reconnaît pas — signalant explicitement cette incompatibilité plutôt que de l'ignorer silencieusement — et les deux parties doivent donc être synchronisées. `failproofai update` réalise cette étape. + +## Ce que la commande fait + + + + Lit la structure enregistrée dans `~/.failproofai/VERSION` et exécute les étapes nécessaires pour la porter à celle que cette version utilise. En général aucune — voir [`failproofai migrate`](/fr/cli/migrate). + + + À partir du package de plateforme déjà téléchargé par npm lorsque c'est possible (sans accès réseau), sinon depuis l'asset de release correspondant exactement à cette version, vérifié par SHA-256 avant utilisation. + + + Le service est sondé plutôt que supposé actif — un gestionnaire de services signale un processus comme actif dès son démarrage, ce qui n'est pas la même chose que son bon fonctionnement. + + + +## Options + +| Option | Effet | +|--------|-------| +| `--no-daemon` | Migre uniquement le répertoire personnel, sans toucher à la version actuelle du daemon. | + + + `--no-daemon` laisse en place un daemon dont la version est désynchronisée. Sur une machine configurée pour exiger le daemon, chaque événement de hook **échoue en mode fermé** si le daemon ne peut pas répondre — et un daemon qui refuse de démarrer avec un répertoire personnel migré ne peut pas répondre. Privilégiez l'exécution de la partie daemon. + + +## En cas de problème + +La commande se termine avec un code non nul et indique quelle partie a échoué. Deux cas à connaître : + +- **Une étape de migration n'a pas abouti.** Le répertoire personnel est laissé marqué avec son *ancienne* structure, de sorte que la commande suivante la réessaiera — aucun répertoire n'est jamais marqué comme à jour sur la base d'une migration partielle. Des copies de vos paramètres et de votre enrôlement ont été sauvegardées avant toute exécution, dans `~/.failproofai/migrations/backup-layout/`. +- **Le daemon n'a pas pu être redémarré sans mot de passe.** `sudo -n` est utilisé délibérément, afin que rien ne demande de saisie depuis un affichage de progression. La commande affiche la ligne exacte à exécuter vous-même. + + + Rien ici ne nécessite l'assistant de configuration interactif. Vos paramètres, l'enrôlement cloud et la sélection des politiques survivent à une mise à jour, de sorte qu'une machine migrée applique exactement les mêmes règles qu'avant — ce qui importe surtout sur les machines sans personne devant l'écran : un runner CI, une machine de parc, une passerelle headless. + + +## Automatisation + +`failproofai update` est non interactif et peut être exécuté sans risque lorsqu'il n'y a rien à faire — il indique qu'aucune migration n'était nécessaire et se termine avec le code 0. L'intégrer après chaque mise à jour dans un script de provisionnement ou un Dockerfile est l'usage prévu : + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` dans la construction d'une image, là où il n'y a pas encore de service à redémarrer.) \ No newline at end of file diff --git a/docs/fr/configuration.mdx b/docs/fr/configuration.mdx index e1fa4cd1..97e683c5 100644 --- a/docs/fr/configuration.mdx +++ b/docs/fr/configuration.mdx @@ -1,10 +1,10 @@ --- title: Configuration -description: "Format de fichier de configuration, système à trois niveaux et règles de fusion" +description: "Format du fichier de configuration, système à trois niveaux et règles de fusion" icon: gear --- -failproofai utilise des fichiers de configuration JSON pour contrôler quelles politiques sont actives, comment elles se comportent, et où les politiques personnalisées sont chargées. La configuration est conçue pour être facilement partageable avec votre équipe — commitez-la dans votre dépôt et chaque développeur bénéficie du même filet de sécurité pour l'agent. +failproofai utilise des fichiers de configuration JSON pour contrôler les politiques actives, leur comportement et l'emplacement des politiques personnalisées. La configuration est conçue pour être facilement partagée avec votre équipe — intégrez-la à votre dépôt et chaque développeur bénéficie du même filet de sécurité pour l'agent. --- @@ -12,13 +12,13 @@ failproofai utilise des fichiers de configuration JSON pour contrôler quelles p Il existe trois niveaux de configuration, évalués par ordre de priorité : -| Niveau | Chemin du fichier | Objectif | -|--------|-------------------|---------| -| **project** | `.failproofai/policies-config.json` | Paramètres par dépôt, commités dans le contrôle de version | +| Niveau | Chemin du fichier | Rôle | +|--------|-------------------|------| +| **project** | `.failproofai/policies-config.json` | Paramètres par dépôt, intégrés au contrôle de version | | **local** | `.failproofai/policies-config.local.json` | Remplacements personnels par dépôt, ignorés par git | -| **global** | `~/.failproofai/policies-config.json` | Valeurs par défaut au niveau utilisateur pour tous les projets | +| **global** | `~/.failproofai/policies-config.json` | Paramètres par défaut au niveau utilisateur, pour tous les projets | -Lorsque failproofai reçoit un événement de hook, il charge et fusionne les trois fichiers qui existent pour le répertoire de travail courant. +Lorsque failproofai reçoit un événement de hook, il charge et fusionne les trois fichiers existants pour le répertoire de travail courant. ### Règles de fusion @@ -29,10 +29,10 @@ project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← union dédoublonnée +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← union dédupliquée ``` -**`policyParams`** — le premier niveau qui définit des paramètres pour une politique donnée l'emporte entièrement. Il n'y a pas de fusion profonde des valeurs au sein des paramètres d'une politique. +**`policyParams`** — le premier niveau définissant les paramètres d'une politique donnée l'emporte entièrement. Il n'y a pas de fusion profonde des valeurs au sein des paramètres d'une politique. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,19 +42,19 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project l'emporte, gl ``` ```text -project: (aucune entrée block-sudo) -local: (aucune entrée block-sudo) +project: (pas d'entrée block-sudo) +local: (pas d'entrée block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← remonte jusqu'au global ``` -**`customPoliciesPaths` / `customPoliciesPath`** — le premier niveau qui définit l'une ou l'autre forme l'emporte. +**`customPoliciesPaths` / `customPoliciesPath`** — le premier niveau définissant l'une ou l'autre forme l'emporte. -**`disabledCustomPolicies`** — union entre tous les niveaux. Le tableau de bord écrit un -identifiant qualifié par la source ici lorsque vous désactivez une politique individuelle depuis -un fichier de politiques explicite ou de convention. Les politiques non listées restent activées par -défaut ; les identifiants incluent le fichier source afin que les politiques de même nom dans plusieurs fichiers +**`disabledCustomPolicies`** — union de tous les niveaux. Le tableau de bord écrit un +ID qualifié par source ici lorsque vous désactivez une politique individuelle depuis +un fichier de politique explicite ou de convention. Les politiques non listées restent activées par +défaut ; les IDs incluent le fichier source pour que des politiques portant le même nom dans plusieurs fichiers puissent être contrôlées indépendamment. **`llm`** — le premier niveau qui le définit l'emporte. @@ -108,7 +108,7 @@ puissent être contrôlées indépendamment. Type : `string[]` -Liste des noms de politiques à activer. Les noms doivent correspondre exactement aux identifiants de politique affichés par `failproofai policies`. Consultez [Politiques intégrées](/fr/built-in-policies) pour la liste complète. +Liste des noms de politiques à activer. Les noms doivent correspondre exactement aux identifiants affichés par `failproofai policies`. Consultez [Politiques intégrées](/fr/built-in-policies) pour la liste complète. Les politiques absentes de `enabledPolicies` sont inactives, même si elles ont des entrées dans `policyParams`. @@ -116,9 +116,9 @@ Les politiques absentes de `enabledPolicies` sont inactives, même si elles ont Type : `Record>` -Remplacements de paramètres par politique. La clé externe est le nom de la politique ; les clés internes sont spécifiques à chaque politique. Chaque politique documente ses paramètres disponibles dans [Politiques intégrées](/fr/built-in-policies). +Remplacements des paramètres par politique. La clé externe est le nom de la politique ; les clés internes sont spécifiques à chaque politique. Chaque politique documente ses paramètres disponibles dans [Politiques intégrées](/fr/built-in-policies). -Si une politique possède des paramètres mais que vous ne les spécifiez pas, les valeurs par défaut intégrées de la politique sont utilisées. Les utilisateurs qui ne configurent pas du tout `policyParams` obtiennent un comportement identique aux versions précédentes. +Si une politique dispose de paramètres que vous ne spécifiez pas, les valeurs par défaut intégrées de la politique sont utilisées. Les utilisateurs qui ne configurent pas du tout `policyParams` obtiennent un comportement identique aux versions précédentes. Les clés inconnues dans le bloc de paramètres d'une politique sont silencieusement ignorées au moment du déclenchement du hook, mais signalées comme avertissements lors de l'exécution de `failproofai policies`. @@ -126,9 +126,9 @@ Les clés inconnues dans le bloc de paramètres d'une politique sont silencieuse Type : `string` (optionnel) -Un message ajouté à la raison lorsqu'une politique retourne `deny` ou `instruct`. Utilisez-le pour donner à Claude des instructions exploitables sans modifier la politique elle-même. +Un message ajouté à la raison lorsqu'une politique retourne `deny` ou `instruct`. Utilisez-le pour fournir à Claude des conseils exploitables sans modifier la politique elle-même. -Fonctionne avec n'importe quel type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`) ou convention utilisateur (`.failproofai-user/`). +Fonctionne avec tout type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`) ou convention utilisateur (`.failproofai-user/`). ```json { @@ -147,7 +147,7 @@ Fonctionne avec n'importe quel type de politique — intégrée, personnalisée } ``` -Lorsque `block-force-push` refuse, Claude voit : *« Les push forcés sont bloqués. Try creating a fresh branch instead. »* +Lorsque `block-force-push` refuse, Claude voit : *« Force-pushing is blocked. Try creating a fresh branch instead. »* Les valeurs non-chaînes et les chaînes vides sont silencieusement ignorées. Si `hint` n'est pas défini, le comportement est inchangé (rétrocompatible). @@ -155,7 +155,7 @@ Les valeurs non-chaînes et les chaînes vides sont silencieusement ignorées. S Type : `string` (chemin absolu) -Chemin vers un fichier JavaScript contenant des politiques de hook personnalisées. Ce champ est défini automatiquement par `failproofai policies --install --custom ` (le chemin est résolu en chemin absolu avant d'être enregistré). +Chemin vers un fichier JavaScript contenant des politiques de hook personnalisées. Ce champ est renseigné automatiquement par `failproofai policies --install --custom ` (le chemin est résolu en absolu avant d'être stocké). Le fichier est rechargé à chaque événement de hook — il n'y a pas de mise en cache. Consultez [Politiques personnalisées](/fr/custom-policies) pour les détails de création. @@ -164,22 +164,28 @@ Le fichier est rechargé à chaque événement de hook — il n'y a pas de mise En plus du `customPoliciesPath` explicite, failproofai découvre et charge automatiquement les fichiers de politiques depuis les répertoires `.failproofai/policies/` : | Niveau | Répertoire | Portée | -|--------|------------|--------| +|--------|-----------|--------| | Projet | `.failproofai/policies/` | Partagé avec l'équipe via le contrôle de version | -| Utilisateur | `~/.failproofai/policies/custom-policies/` | Personnel, s'applique à tous les projets | +| Utilisateur | `~/.failproofai/policies/` | Personnel, s'applique à tous les projets | - Le répertoire de niveau utilisateur a été déplacé d'un niveau dans la - réorganisation du répertoire personnel. Les fichiers laissés à l'ancien emplacement `~/.failproofai/policies/` sont déplacés - automatiquement dans `custom-policies/` la première fois que vous exécutez une commande `failproofai` - après la mise à niveau, et la commande vous indique les fichiers déplacés. + Déposez vos politiques directement dans `~/.failproofai/policies/`. Le + dossier `cloud-policies/` à côté contient les politiques déployées par votre organisation + sur cette machine — la découverte ne descend pas dans les sous-répertoires, il + n'est donc jamais analysé, et rien de ce que vous placez dans `policies/` ne peut entrer en conflit avec lui. + + Si vous mettez à niveau depuis une version utilisant + `~/.failproofai/policies/custom-policies/`, tout ce qui se trouve dans ce dossier — vos + fichiers de politiques, tout `lib/` d'utilitaires qu'ils importent et tous les fichiers de données qu'ils lisent + — est automatiquement remonté d'un niveau la première fois que vous exécutez une commande `failproofai`, + qui vous indique ce qu'elle a déplacé. -**Correspondance de fichiers :** Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés (ex. : `security-policies.mjs`, `workflow-policies.js`). Les autres fichiers du répertoire sont ignorés. +**Correspondance des fichiers :** Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés (ex. `security-policies.mjs`, `workflow-policies.js`). Les autres fichiers du répertoire sont ignorés. -**Aucune configuration requise :** Les politiques de convention ne nécessitent aucune entrée dans `policies-config.json`. Déposez simplement des fichiers dans le répertoire et ils seront pris en compte au prochain événement de hook. +**Aucune configuration nécessaire :** Les politiques de convention ne nécessitent aucune entrée dans `policies-config.json`. Déposez simplement les fichiers dans le répertoire et ils seront pris en compte au prochain événement de hook. -**Chargement par union :** Les répertoires de convention du projet et de l'utilisateur sont tous deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui utilise le premier niveau gagnant). +**Chargement par union :** Les répertoires de convention du projet et de l'utilisateur sont tous deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui utilise le principe du premier niveau gagnant). Consultez [Politiques personnalisées](/fr/custom-policies) pour plus de détails et d'exemples. @@ -200,26 +206,26 @@ Configuration du client LLM pour les politiques qui effectuent des appels IA. No --- -## Gestion de la configuration depuis la CLI +## Gérer la configuration depuis la CLI -Les commandes `policies --install` et `policies --uninstall` écrivent dans le fichier de paramètres de hooks de votre CLI d'agent (les points d'entrée du hook), tandis que `policies-config.json` est le fichier que vous gérez directement. Les deux sont distincts : +Les commandes `policies --install` et `policies --uninstall` écrivent dans le fichier de paramètres de hook de votre CLI agent (les points d'entrée des hooks), tandis que `policies-config.json` est le fichier que vous gérez directement. Les deux sont distincts : -- **Paramètres de la CLI d'agent** — indique à l'agent d'appeler `failproofai --hook ` à chaque utilisation d'outil : +- **Paramètres de la CLI agent** — indique à l'agent d'appeler `failproofai --hook ` à chaque utilisation d'outil : - **Claude Code** : `~/.claude/settings.json` (utilisateur), `/.claude/settings.json` (projet), `/.claude/settings.local.json` (local) - **OpenAI Codex** : `~/.codex/hooks.json` (utilisateur), `/.codex/hooks.json` (projet) — Codex n'a pas de portée `local` - - **GitHub Copilot CLI _(bêta)_** : `~/.copilot/hooks/failproofai.json` (utilisateur), `/.github/hooks/failproofai.json` (projet) — Copilot n'a pas de portée `local`. Les entrées de hook utilisent les champs de commande `bash`/`powershell` à clé OS de Copilot avec `timeoutSec` ; le fichier porte un marqueur `version: 1` au niveau supérieur. La prise en charge de Copilot CLI est en **bêta** pendant que nous vérifions le schéma d'enregistrement `events.jsonl` (non spécifié dans la documentation publique) contre davantage de sessions réelles. **VS Code Copilot Chat en mode agent (Prévisualisation)** lit les configurations de hooks depuis `.github/hooks/*.json`, `~/.copilot/hooks/*.json` et `~/.claude/settings.json` (régi par le paramètre `chat.hookFilesLocations`) en utilisant le même contrat Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exactement les chemins que cette intégration `copilot` et l'intégration `claude` (`~/.claude/settings.json`) écrivent déjà, donc `failproofai policies --install --cli copilot` (ou `--cli claude`) **applique déjà les politiques en mode agent VS Code** sans intégration `vscode` séparée (confirmé en direct depuis les journaux de découverte VS Code). - - **Cursor Agent _(bêta)_** : `~/.cursor/hooks.json` (utilisateur), `/.cursor/hooks.json` (projet) — Cursor n'a pas de portée `local`. Les entrées de hook utilisent la forme Claude `{type, command, timeout}` (sans séparation `bash`/`powershell`), mais stockées sous des clés d'événement en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) dans un tableau plat selon le [schéma de hooks](https://cursor.com/docs/hooks) de Cursor ; le fichier porte un marqueur `version: 1` au niveau supérieur. Le gestionnaire canonicalise camelCase → PascalCase via `CURSOR_EVENT_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. La prise en charge de Cursor Agent est en **bêta** pendant que nous vérifions le format de transcription sur disque de Cursor (non spécifié dans la documentation publique) contre davantage d'installations réelles. - - **OpenCode _(bêta)_** : `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (utilisateur), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projet) — OpenCode n'a pas de portée `local`. Contrairement aux cinq autres CLIs, OpenCode **n'a pas de système de hooks par commande externe** : il charge des plugins JS/TS en cours de processus explicitement enregistrés via le tableau `plugin: []` dans `opencode.json` (la découverte automatique depuis `.opencode/plugins/` **n'est pas** la façon dont les plugins se chargent sur opencode v1.14.33). L'installation dépose un petit shim de plugin généré qui appelle le binaire failproofai en sous-processus et traduit la réponse JSON de forme Claude du binaire en sémantique de plugin : `throw new Error()` pour le refus d'événement d'outil (annule l'appel d'outil), `client.session.prompt(...)` pour instruct ET pour le refus `Stop` / `SubagentStop` (soumet la raison du refus comme prochain message utilisateur — le seul canal de forçage de relance puisque `session.idle` est en lecture seule et que lever une exception depuis celui-ci est un no-op), et no-op pour allow. Le shim canonicalise à la fois les noms d'outils (minuscules → PascalCase via `OPENCODE_TOOL_MAP`) et les clés d'arguments d'entrée d'outil (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` pour `Read` / `Write` / `Edit`, ex. `filePath` → `file_path`, `oldString` → `old_string`) avant de transmettre au binaire, afin que les politiques intégrées de vérification de chemin comme `block-read-outside-cwd`, `block-env-files` et `block-secrets-write` se déclenchent sans modification sur les appels d'outils OpenCode. Les sessions vivent dans la base de données SQLite d'opencode à `~/.local/share/opencode/opencode.db` ; le visualiseur de sessions du tableau de bord les lit via `opencode db --format json` et `opencode export `. La prise en charge d'OpenCode est en **bêta** pendant que nous vérifions le comportement entre les versions et contre davantage de sessions réelles. Consultez la [documentation des plugins OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(bêta)_** : `~/.pi/agent/settings.json` (utilisateur), `/.pi/settings.json` (projet) — Pi n'a pas de portée `local`. Pi charge des packages d'extension TypeScript au démarrage ; le fichier de paramètres est un tableau de chaînes plat `{"packages": ["./relative/path", …]}`. failproofai écrit une seule entrée dans le tableau packages pointant vers son répertoire `pi-extension/` intégré. L'extension s'abonne en interne aux événements `tool_call` / `user_bash` / `input` / `session_start` de Pi et exécute `failproofai --hook --cli pi` dans un shell ; le gestionnaire canonicalise underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. Les arguments d'entrée d'outil sont également canonicalisés via `PI_TOOL_INPUT_MAP` (les outils Read / Write / Edit de Pi fournissent `path` plutôt que `file_path` ; mapper la clé de niveau supérieur permet à `block-env-files` et `block-secrets-write` de se déclencher — `block-read-outside-cwd` avait déjà un fallback `path`). La prise en charge de Pi est en **bêta** pendant que l'API d'extension de Pi et la disposition des journaux de session se stabilisent. - - **Hermes (hermes-agent)** : `~/.hermes/config.yaml` (**portée utilisateur uniquement** — Hermes n'a pas de configuration projet/local). Hermes est une **passerelle** Slack/Telegram, donc une seule installation intercepte les appels d'outils de chaque plateforme (Slack/Telegram/cli/cron) **et** les sous-agents internes. Les entrées de hook sont une paire `{command, timeout}` (timeout en **secondes**) sous une map `hooks:` à clé par les événements snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) ; le gestionnaire canonicalise les événements via `HERMES_EVENT_MAP` et les noms d'outils via `HERMES_TOOL_MAP` afin que les politiques intégrées se déclenchent sans modification. La configuration est modifiée via un aller-retour YAML `Document` préservant les commentaires afin que les autres paramètres de l'opérateur survivent, et l'installation définit `hooks_auto_accept: true` afin que la passerelle sans tête (pas de TTY) exécute les hooks sans invite de consentement. L'évaluateur émet le contrat stdout `{"decision":"block","reason"}` de Hermes (Hermes ignore les codes de sortie). **Limitations :** Hermes n'a pas d'événement `Stop` de fin de tour, donc les politiques intégrées `require-*-before-stop` ne se déclenchent jamais pour lui (non applicable, pas cassé) ; `instruct` se dégrade en allow-avec-note-journalisée (pas de canal de contexte supplémentaire) ; et la suppression des secrets en sortie (`sanitize-*`) ne peut pas réécrire la sortie d'outil via le contrat de hook shell. Hermes est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions de passerelle directement depuis `~/.hermes/state.db`. - - **OpenClaw (passerelle openclaw)** : `~/.openclaw/openclaw.json` (**portée utilisateur uniquement** — OpenClaw n'a pas de configuration projet/local). Comme Hermes, OpenClaw est une **passerelle** multi-canal auto-hébergée, donc une seule installation intercepte les appels d'outils de chaque canal et ses sous-agents internes. L'application des politiques passe par les **hooks de plugin en cours de processus** d'OpenClaw (ses hooks internes basés sur des fichiers sont en observation uniquement et ne peuvent pas bloquer), donc — comme OpenCode/Pi — failproofai livre un package `openclaw-plugin/` statique qui lance le binaire failproofai de manière asynchrone et traduit le verdict. L'installation enregistre le répertoire du plugin livré dans `plugins.load.paths[]` de `openclaw.json` et l'active sous `plugins.entries.failproofai` (avec `hooks.allowConversationAccess: true`, requis pour les hooks de conversation brute). L'évaluateur émet un verdict plat `{permission, reason}` et le shim le mappe à la forme de retour native de chaque hook : `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), et `before_agent_finalize → {action:"revise", reason}` (**Stop** — une vraie porte de fin de tour, donc les politiques intégrées `require-*-before-stop` **s'appliquent** sur OpenClaw, contrairement à Hermes). Les événements et les noms d'outils se canonicalisent côté binaire via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) afin que les politiques intégrées se déclenchent sans modification ; le shim échoue ouvert en cas d'erreur de spawn/parse/timeout. OpenClaw est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions JSONL à `~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)** : `~/.factory/hooks.json` (utilisateur), `/.factory/hooks.json` (projet) — Factory n'a pas de portée `local`. droid livre un système de hook par commande externe de style Claude, mais avec deux particularités vérifiées en direct contre droid v0.171.0 : (1) les noms d'événements se trouvent au **niveau supérieur** de `hooks.json` — il n'y a **pas d'enveloppe `"hooks"`** (droid la rejette) ; les événements d'outil (`PreToolUse`/`PostToolUse`) portent `"matcher": "*"`, les événements non-outil l'omettent. (2) Le refus est piloté par le **code de sortie 2 + stderr** du hook, pas par une décision JSON — la branche `factory` de l'évaluateur retourne le code de sortie 2 pour les événements d'outil/prompt et `{decision:"block", reason}` uniquement sur l'événement de fin de tour `Stop` (le seul canal de forçage de relance de droid). Les événements sont déjà en PascalCase (pas de map d'événements) et le payload est en snake_case Claude ; seuls les noms d'outils sont canonicalisés via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions JSONL sur disque à `~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)** : `~/.config/devin/config.json` (utilisateur), `/.devin/config.json` (projet) — Devin n'a pas de portée `local`. Devin est un **clone pur de Claude** vérifié en direct contre devin v3000.1.27 : il utilise le schéma standard Claude avec enveloppe `"hooks"` (les écritures préservent la fusion afin que les autres clés du fichier de configuration — `org_id`, `theme_mode`, … — survivent), des noms d'événements déjà en PascalCase (pas de map d'événements, pas de branche de gestionnaire), et un payload stdin snake_case Claude (pas de normalisation). La branche `devin` de l'évaluateur refuse avec `{"decision":"block","reason"}` JSON sur stdout au code de sortie 0 pour **chaque** événement (vérifié — le bloc a surchargé `--permission-mode dangerous`) ; sur l'événement de fin de tour `Stop`, la raison porte le libellé de forçage de relance MANDATORY-ACTION afin que les politiques intégrées `require-*-before-stop` s'appliquent. Seuls les noms d'outils sont canonicalisés via `DEVIN_TOOL_MAP` (`exec→Bash` ; `tool_input.command` est déjà canonique). Devin est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions SQLite à `~/.local/share/devin/cli/sessions.db` (chaque ligne `sessions` porte un vrai `working_directory`, donc les sessions se regroupent par cwd de projet comme Claude). - - **Antigravity CLI (`agy`)** : `~/.gemini/config/hooks.json` (utilisateur), `/.agents/hooks.json` (projet) — Antigravity n'a pas de portée `local`. Contrairement à Factory/Devin, Antigravity a son **propre** contrat (pas un clone de Claude), vérifié en direct contre agy v1.1.2. `hooks.json` utilise un schéma de **hook nommé** : la clé de niveau supérieur est un *nom* de hook (`"failproofai"`) dont la valeur est une map événement→gestionnaires — les événements d'outil (`PreToolUse`/`PostToolUse`) enveloppent les gestionnaires dans `{matcher:"*", hooks:[…]}`, tandis que `PreInvocation`/`Stop` sont des **tableaux plats** de gestionnaires (les autres hooks nommés sont préservés). Le payload stdin est du **protojson en camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai le normalise en snake_case avant l'exécution des politiques, et mappe les args PascalCase de `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. La branche `antigravity` de l'évaluateur utilise les **propres** formes de réponse d'Antigravity : `{decision:"deny", reason}` bloque un outil/prompt (code de sortie 0), `{decision:"continue", reason}` sur l'événement de fin de tour `Stop` relance la boucle (donc les politiques intégrées `require-*-before-stop` s'appliquent), et `{injectSteps:[{ephemeralMessage}]}` injecte une instruction sur `PreInvocation` (→ `UserPromptSubmit`). Les noms d'outils se canonicalisent via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity est **également** une source d'**audit** hors ligne — le tableau de bord lit ses transcriptions JSONL brutes à `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (index de conversation dans `conversation_summaries.db`). - - **Goose (nom de code goose, Block)** : `~/.agents/plugins/failproofai/hooks/hooks.json` (utilisateur), `/.agents/plugins/failproofai/hooks/hooks.json` (projet) — Goose n'a pas de portée `local`. L'application des politiques utilise le système de **hooks** de Goose, la spécification **Open Plugins** multi-agents : l'installateur dépose simplement le répertoire du plugin `failproofai` et Goose le découvre automatiquement au démarrage (en l'auto-enregistrant dans `~/.config/goose/config.yaml`). Le `hooks.json` utilise un schéma Open Plugins **avec** une enveloppe `"hooks"` au niveau supérieur, et le matcher est **omis** sur chaque événement — un `"*"` nu est une regex invalide qui ne correspond à rien (vérifié en direct contre goose v1.43.0). Les noms d'événements sont déjà en PascalCase (pas de map d'événements) ; le payload stdin utilise `event`/`working_dir`, que le gestionnaire normalise en `hook_event_name`/`cwd`. La branche `goose` de l'évaluateur refuse avec `{"decision":"block","reason"}` JSON sur stdout au code de sortie 0, honoré sur l'événement **`PreToolUse`** uniquement (livré dans goose ≥ v1.37.0) — qui se déclenche pour l'outil shell **et à l'intérieur des sous-agents délégués**, en faisant le seul point de refus suffisant ; toute autre erreur de hook échoue **ouvert**. Goose **n'a pas d'événement `Stop`**, donc les politiques intégrées `require-*-before-stop` ne s'appliquent pas (comme avec Hermes). Les noms d'outils se canonicalisent via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) et les clés de chemin via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions SQLite à `~/.local/share/goose/sessions/sessions.db` (chaque ligne `sessions` porte un vrai `working_dir`, donc les sessions se regroupent par cwd de projet comme Devin ; les exécutions scratch `--no-session` sont filtrées). -- **`policies-config.json`** — indique à failproofai quelles politiques évaluer et avec quels paramètres (partagé entre toutes les CLIs d'agent) - -Passez `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` pour cibler un agent spécifique (séparé par des espaces ou répété pour tout sous-ensemble) : + - **GitHub Copilot CLI _(bêta)_** : `~/.copilot/hooks/failproofai.json` (utilisateur), `/.github/hooks/failproofai.json` (projet) — Copilot n'a pas de portée `local`. Les entrées de hook utilisent les champs de commande `bash`/`powershell` keyed par OS de Copilot avec `timeoutSec` ; le fichier porte un marqueur `version: 1` au niveau racine. La prise en charge de Copilot CLI est en **bêta** pendant que nous vérifions le schéma d'enregistrement `events.jsonl` (non spécifié dans la documentation publique) contre davantage de sessions réelles. **VS Code Copilot Chat en mode agent (Aperçu)** lit les configurations de hook depuis `.github/hooks/*.json`, `~/.copilot/hooks/*.json` et `~/.claude/settings.json` (régi par le paramètre `chat.hookFilesLocations`) en utilisant le même contrat Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exactement les chemins que cette intégration `copilot` et l'intégration `claude` (`~/.claude/settings.json`) écrivent déjà, donc `failproofai policies --install --cli copilot` (ou `--cli claude`) **applique déjà les règles en mode agent VS Code** sans intégration `vscode` séparée (confirmé en direct depuis les journaux de découverte de VS Code). + - **Cursor Agent _(bêta)_** : `~/.cursor/hooks.json` (utilisateur), `/.cursor/hooks.json` (projet) — Cursor n'a pas de portée `local`. Les entrées de hook utilisent la forme Claude `{type, command, timeout}` (sans séparation `bash`/`powershell`), mais stockées sous des clés d'événement en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) dans un tableau plat selon le [schéma de hooks](https://cursor.com/docs/hooks) de Cursor ; le fichier porte un marqueur `version: 1` au niveau racine. Le gestionnaire canonicalise le camelCase → PascalCase via `CURSOR_EVENT_MAP` pour que les politiques intégrées existantes se déclenchent sans modification. La prise en charge de Cursor Agent est en **bêta** pendant que nous vérifions le format de transcript sur disque de Cursor (non spécifié dans la documentation publique) contre davantage d'installations réelles. + - **OpenCode _(bêta)_** : `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (utilisateur), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projet) — OpenCode n'a pas de portée `local`. Contrairement aux cinq autres CLI, OpenCode **n'a pas de système de hook basé sur des commandes externes** : il charge des plugins JS/TS en cours de processus explicitement enregistrés via le tableau `plugin: []` dans `opencode.json` (l'auto-découverte depuis `.opencode/plugins/` **n'est pas** la façon dont les plugins se chargent sur opencode v1.14.33). L'installation dépose un petit shim de plugin généré qui appelle le binaire failproofai en sous-processus et traduit la réponse JSON en forme Claude du binaire en sémantique de plugin : `throw new Error()` pour refuser un événement outil (annule l'appel d'outil), `client.session.prompt(...)` pour instruct ET pour le refus de `Stop` / `SubagentStop` (soumet la raison du refus comme prochain message utilisateur — le seul canal de force-retry puisque `session.idle` est en notification seulement et qu'un throw depuis celui-ci est un no-op), et no-op pour allow. Le shim canonicalise les noms d'outils (minuscules → PascalCase via `OPENCODE_TOOL_MAP`) et les clés d'arguments d'entrée d'outil (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` pour `Read` / `Write` / `Edit`, ex. `filePath` → `file_path`, `oldString` → `old_string`) avant de transmettre au binaire, afin que les builtins vérifiant les chemins comme `block-read-outside-cwd`, `block-env-files` et `block-secrets-write` se déclenchent sans modification sur les appels d'outils OpenCode. Les sessions vivent dans la base de données SQLite d'opencode à `~/.local/share/opencode/opencode.db` ; le viewer de sessions du tableau de bord les lit via `opencode db --format json` et `opencode export `. La prise en charge d'OpenCode est en **bêta** pendant que nous vérifions le comportement sur différentes versions et contre davantage de sessions réelles. Consultez la [documentation des plugins OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(bêta)_** : `~/.pi/agent/settings.json` (utilisateur), `/.pi/settings.json` (projet) — Pi n'a pas de portée `local`. Pi charge des packages d'extension TypeScript au démarrage ; le fichier de paramètres est un tableau de chaînes plat `{"packages": ["./relative/path", …]}`. failproofai écrit une seule entrée dans le tableau packages pointant vers son répertoire `pi-extension/` inclus. L'extension s'abonne en interne aux événements `tool_call` / `user_bash` / `input` / `session_start` de Pi et exécute `failproofai --hook --cli pi` ; le gestionnaire canonicalise underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` pour que les politiques intégrées existantes se déclenchent sans modification. Les arguments d'entrée d'outil sont également canonicalisés via `PI_TOOL_INPUT_MAP` (Read / Write / Edit de Pi fournissent `path` plutôt que `file_path` ; le mappage de la clé de niveau supérieur permet à `block-env-files` et `block-secrets-write` de se déclencher — `block-read-outside-cwd` avait déjà un fallback `path`). La prise en charge de Pi est en **bêta** pendant que l'API d'extension de Pi et la disposition des journaux de session se stabilisent. + - **Hermes (hermes-agent)** : `~/.hermes/config.yaml` (**portée utilisateur uniquement** — Hermes n'a pas de configuration projet/local). Hermes est une **passerelle** Slack/Telegram, donc une seule installation intercepte les appels d'outils de chaque plateforme (Slack/Telegram/cli/cron) **et** les sous-agents internes. Les entrées de hook sont une paire `{command, timeout}` (timeout en **secondes**) sous une map `hooks:` indexée par les événements snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) ; le gestionnaire canonicalise les événements via `HERMES_EVENT_MAP` et les noms d'outils via `HERMES_TOOL_MAP` pour que les politiques intégrées se déclenchent sans modification. La configuration est éditée via un round-trip YAML `Document` préservant les commentaires pour que les autres paramètres de l'opérateur survivent, et l'installation définit `hooks_auto_accept: true` pour que la passerelle headless (sans TTY) exécute les hooks sans invite de consentement. L'évaluateur émet le contrat stdout `{"decision":"block","reason"}` de Hermes (Hermes ignore les codes de sortie). **Limitations :** Hermes n'a pas d'événement `Stop` de fin de tour, donc les builtins `require-*-before-stop` ne se déclenchent jamais pour lui (non applicable, pas cassé) ; `instruct` se dégrade en allow-avec-note-journalisée (pas de canal de contexte supplémentaire) ; et la rédaction de secrets en sortie (`sanitize-*`) ne peut pas réécrire la sortie d'outil via le contrat de hook shell. Hermes est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions de passerelle directement depuis `~/.hermes/state.db`. + - **OpenClaw (passerelle openclaw)** : `~/.openclaw/openclaw.json` (**portée utilisateur uniquement** — OpenClaw n'a pas de configuration projet/local). Comme Hermes, OpenClaw est une **passerelle** multi-canal auto-hébergée, donc une seule installation intercepte les appels d'outils de chaque canal et de ses sous-agents internes. L'application des règles passe par les **hooks de plugin en cours de processus** d'OpenClaw (ses hooks internes basés sur des fichiers sont en observation seulement et ne peuvent pas bloquer), donc — comme OpenCode/Pi — failproofai livre un package statique `openclaw-plugin/` qui génère de manière asynchrone le binaire failproofai et traduit le verdict. L'installation enregistre le répertoire de plugin livré dans `plugins.load.paths[]` de `openclaw.json` et l'active sous `plugins.entries.failproofai` (avec `hooks.allowConversationAccess: true`, requis pour les hooks de conversation brute). L'évaluateur émet un verdict plat `{permission, reason}` et le shim le mappe à la forme de retour native de chaque hook : `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), et `before_agent_finalize → {action:"revise", reason}` (**Stop** — une vraie porte de fin de tour, donc les builtins `require-*-before-stop` **s'appliquent** sur OpenClaw, contrairement à Hermes). Les événements et les noms d'outils canonicalisent côté binaire via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) pour que les politiques intégrées se déclenchent sans modification ; le shim échoue ouvert en cas d'erreur de spawn/parse/timeout. OpenClaw est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions JSONL à `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)** : `~/.factory/hooks.json` (utilisateur), `/.factory/hooks.json` (projet) — Factory n'a pas de portée `local`. droid livre un système de hook de commandes externes de style Claude, mais avec deux particularités vérifiées en direct contre droid v0.171.0 : (1) les noms d'événements sont au **niveau racine** de `hooks.json` — il **n'y a pas d'enveloppe `"hooks"`** (droid la rejette) ; les événements d'outil (`PreToolUse`/`PostToolUse`) portent `"matcher": "*"`, les événements non-outil l'omettent. (2) Le refus est piloté par le **code de sortie 2 + stderr** du hook, pas par une décision JSON — la branche `factory` de l'évaluateur retourne le code de sortie 2 pour les événements d'outil/prompt et `{decision:"block", reason}` uniquement sur l'événement `Stop` de fin de tour (le seul canal de force-retry de droid). Les événements sont déjà en PascalCase (pas de map d'événements) et le payload est en snake_case Claude ; seuls les noms d'outils sont canonicalisés via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions JSONL sur disque à `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)** : `~/.config/devin/config.json` (utilisateur), `/.devin/config.json` (projet) — Devin n'a pas de portée `local`. Devin est un **clone pur de Claude** vérifié en direct contre devin v3000.1.27 : il utilise le schéma d'enveloppe `"hooks"` standard de Claude (les écritures préservent la fusion pour que les autres clés du fichier de configuration — `org_id`, `theme_mode`, … — survivent), des noms d'événements déjà en PascalCase (pas de map d'événements, pas de branche de gestionnaire) et un payload stdin snake_case Claude (pas de normalisation). La branche `devin` de l'évaluateur refuse avec `{"decision":"block","reason"}` JSON sur stdout au code de sortie 0 pour **chaque** événement (vérifié — le bloc a surchargé `--permission-mode dangerous`) ; sur l'événement `Stop` de fin de tour, la raison porte le libellé de force-retry MANDATORY-ACTION pour que les builtins `require-*-before-stop` s'appliquent. Seuls les noms d'outils sont canonicalisés via `DEVIN_TOOL_MAP` (`exec→Bash` ; `tool_input.command` est déjà canonique). Devin est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions SQLite à `~/.local/share/devin/cli/sessions.db` (chaque ligne `sessions` porte un vrai `working_directory`, donc les sessions se regroupent par cwd de projet comme Claude). + - **Antigravity CLI (`agy`)** : `~/.gemini/config/hooks.json` (utilisateur), `/.agents/hooks.json` (projet) — Antigravity n'a pas de portée `local`. Contrairement à Factory/Devin, Antigravity a son **propre** contrat (pas un clone de Claude), vérifié en direct contre agy v1.1.2. `hooks.json` utilise un schéma de **hook nommé** : la clé de niveau racine est un *nom* de hook (`"failproofai"`) dont la valeur est une map événement→gestionnaires — les événements d'outil (`PreToolUse`/`PostToolUse`) enveloppent les gestionnaires dans `{matcher:"*", hooks:[…]}`, tandis que `PreInvocation`/`Stop` sont des tableaux de gestionnaires **plats** (les autres hooks nommés sont préservés). Le payload stdin est en **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai le normalise en snake_case avant l'exécution des politiques, et mappe les args PascalCase de `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. La branche `antigravity` de l'évaluateur utilise les **propres** formes de réponse d'Antigravity : `{decision:"deny", reason}` bloque un outil/prompt (code de sortie 0), `{decision:"continue", reason}` sur l'événement `Stop` de fin de tour re-entre dans la boucle (donc les builtins `require-*-before-stop` s'appliquent), et `{injectSteps:[{ephemeralMessage}]}` injecte une instruction sur `PreInvocation` (→ `UserPromptSubmit`). Les noms d'outils canonicalisent via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity est **également** une source d'**audit** hors ligne — le tableau de bord lit ses transcripts JSONL simples à `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (index de conversation dans `conversation_summaries.db`). + - **Goose (nom de code goose, Block)** : `~/.agents/plugins/failproofai/hooks/hooks.json` (utilisateur), `/.agents/plugins/failproofai/hooks/hooks.json` (projet) — Goose n'a pas de portée `local`. L'application des règles utilise le système de **hooks** de Goose, la spécification **Open Plugins** multi-agent : l'installateur dépose simplement le répertoire du plugin `failproofai` et Goose le découvre automatiquement au démarrage (en le s'enregistrant dans `~/.config/goose/config.yaml`). Le `hooks.json` utilise un schéma Open Plugins **avec** une enveloppe `"hooks"` au niveau racine, et le matcher est **omis** sur chaque événement — un `"*"` nu est une regex invalide qui ne correspond à rien (vérifié en direct contre goose v1.43.0). Les noms d'événements sont déjà en PascalCase (pas de map d'événements) ; le payload stdin utilise `event`/`working_dir`, que le gestionnaire normalise en `hook_event_name`/`cwd`. La branche `goose` de l'évaluateur refuse avec `{"decision":"block","reason"}` JSON sur stdout au code de sortie 0, honoré sur l'événement **`PreToolUse`** uniquement (livré dans goose ≥ v1.37.0) — qui se déclenche pour l'outil shell **et à l'intérieur des sous-agents délégués**, c'est donc le seul point de refus suffisant ; toute autre erreur de hook échoue **ouvert**. Goose **n'a pas d'événement `Stop`**, donc les builtins `require-*-before-stop` ne s'appliquent pas (comme avec Hermes). Les noms d'outils canonicalisent via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) et les clés de chemin via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions SQLite à `~/.local/share/goose/sessions/sessions.db` (chaque ligne `sessions` porte un vrai `working_dir`, donc les sessions se regroupent par cwd de projet comme Devin ; les exécutions ponctuelles `--no-session` sont filtrées). +- **`policies-config.json`** — indique à failproofai quelles politiques évaluer et avec quels paramètres (partagé entre toutes les CLI agents) + +Passez `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` pour cibler un agent spécifique (séparés par des espaces ou répétés pour tout sous-ensemble) : ```bash failproofai policies --install --cli codex --scope project @@ -236,20 +242,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Lorsque `--cli` est omis, `failproofai` détecte les CLIs d'agent installées (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`) : +Lorsque `--cli` est omis, `failproofai` détecte quelles CLI agents sont installées (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`) : -- **Une CLI détectée** — sélectionne automatiquement cette CLI sans demande de confirmation. -- **Plusieurs CLIs détectées** dans un terminal interactif — affiche une invite de sélection unique par flèches groupée en une section `Detected (N)` (avec une ligne agrégée `Install for all N detected` + chaque CLI détectée individuellement) et une section `Not installed (M) · install hooks ahead of time` listant toutes les CLIs prises en charge non détectées comme option d'installation anticipée (↑↓ pour déplacer, Entrée pour sélectionner, ^C pour quitter). Le flux de désinstallation n'affiche que la section Detected. -- **Plusieurs CLIs détectées** lors d'une exécution non interactive (CI, pas de TTY) — installe pour toutes les CLIs détectées sans demande de confirmation. -- **Aucune détectée** — revient à `claude`, avec un avertissement qu'aucun binaire d'agent n'a été trouvé dans PATH ; la commande de hook est quand même écrite afin qu'elle s'active dès que vous en installez une. +- **Une CLI détectée** — sélectionne automatiquement cette CLI sans invite. +- **Plusieurs CLI détectées** dans un terminal interactif — affiche une invite de sélection unique à touches fléchées regroupant une section `Detected (N)` (avec une ligne agrégée `Install for all N detected` + chaque CLI détectée individuellement) et une section `Not installed (M) · install hooks ahead of time` listant chaque CLI prise en charge non détectée comme option d'installation anticipée (↑↓ pour naviguer, Entrée pour sélectionner, ^C pour quitter). Le flux de désinstallation n'affiche que la section Detected. +- **Plusieurs CLI détectées** dans une exécution non interactive (CI, pas de TTY) — installe pour toutes les CLI détectées sans invite. +- **Aucune détectée** — revient à `claude`, avec un avertissement indiquant qu'aucun binaire agent n'a été trouvé dans PATH ; la commande de hook est tout de même écrite pour s'activer dès que vous en installez un. Vous pouvez modifier `policies-config.json` directement à tout moment ; les modifications prennent effet immédiatement au prochain événement de hook, sans redémarrage nécessaire. +## Les mises à niveau conservent votre configuration + +Une nouvelle version de failproofai peut réorganiser `~/.failproofai/` différemment. Le cas échéant, la première commande après la mise à niveau migre le répertoire, et **votre configuration est transférée, pas réinitialisée** : + +| Conservé | Reconstruit | +|---|---| +| Votre sélection de politiques et leurs paramètres (`policies-config.json`) | Le cache d'audit | +| Vos paramètres, y compris `daemon.configured` et les chemins de capture supplémentaires (`config.json`) | Les déploiements de politiques gérés par le cloud — récupérés et vérifiés par empreinte au prochain sondage | +| Votre enrôlement cloud (`credentials.json`) | L'état temporaire du daemon | +| Vos propres fichiers de politiques dans `policies/`, et les utilitaires qu'ils importent | | +| Le journal de décisions lu par le tableau de bord, et les événements non encore livrés | | + +Les clés écrites par une version *plus récente* de failproofai sont également préservées plutôt qu'ignorées par un lecteur plus ancien — passer d'une version à l'autre ne supprime donc silencieusement aucun paramètre dans aucun sens. + +Vous **n'avez pas** besoin de relancer la configuration après la migration : une machine migrée applique exactement les mêmes règles qu'avant, ce qui rend une mise à niveau sûre sur des machines sans personne devant l'écran. Chaque migration est enregistrée dans `~/.failproofai/migrations/applied.json`, et les fichiers irremplaçables sont copiés dans `~/.failproofai/migrations/backup-layout/` avant toute exécution. + +Consultez [`failproofai update`](/fr/cli/update) pour la mise à niveau en une ligne, et [`failproofai migrate`](/fr/cli/migrate) — y compris `--dry-run` — pour les détails. + --- ## Exemple : configuration au niveau projet avec des valeurs par défaut d'équipe -Commitez `.failproofai/policies-config.json` dans votre dépôt : +Intégrez `.failproofai/policies-config.json` à votre dépôt : ```json { @@ -268,4 +292,4 @@ Commitez `.failproofai/policies-config.json` dans votre dépôt : } ``` -Chaque développeur peut ensuite créer `.failproofai/policies-config.local.json` (ignoré par git) pour ses remplacements personnels sans affecter ses coéquipiers. \ No newline at end of file +Chaque développeur peut ensuite créer `.failproofai/policies-config.local.json` (ignoré par git) pour ses remplacements personnels sans affecter ses collègues. \ No newline at end of file diff --git a/docs/fr/custom-policies.mdx b/docs/fr/custom-policies.mdx index 3728a775..e5d76ba0 100644 --- a/docs/fr/custom-policies.mdx +++ b/docs/fr/custom-policies.mdx @@ -4,7 +4,7 @@ description: "Écrivez vos propres politiques en JavaScript - appliquez des conv icon: code --- -Les politiques personnalisées vous permettent d'écrire des règles pour n'importe quel comportement d'agent : appliquer des conventions de projet, prévenir la dérive, bloquer les opérations destructives, détecter les agents bloqués, ou intégrer Slack, des workflows d'approbation, et plus encore. Elles utilisent le même système d'événements de hook et les mêmes décisions `allow`, `deny`, `instruct` que les politiques intégrées. +Les politiques personnalisées vous permettent d'écrire des règles pour n'importe quel comportement d'agent : appliquer des conventions de projet, prévenir la dérive, contrôler les opérations destructives, détecter les agents bloqués, ou s'intégrer avec Slack, des workflows d'approbation, et plus encore. Elles utilisent le même système d'événements de hook et les mêmes décisions `allow`, `deny`, `instruct` que les politiques intégrées. --- @@ -41,7 +41,7 @@ failproofai policies --install --custom ./my-policies.js ### Option 1 : Basée sur les conventions (recommandée) -Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont automatiquement chargés — aucun indicateur ni modification de configuration nécessaire. Cela fonctionne comme les hooks git : déposez un fichier, ça marche tout de suite. +Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont automatiquement chargés — aucun indicateur ni modification de configuration n'est nécessaire. Cela fonctionne comme les hooks git : déposez un fichier, ça marche tout seul. ``` # Niveau projet — commité dans git, partagé avec l'équipe @@ -52,15 +52,15 @@ Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et i ~/.failproofai/policies/my-policies.mjs ``` -**Comment ça fonctionne :** -- Les répertoires projet et utilisateur sont tous les deux analysés (union — pas de priorité par portée) +**Fonctionnement :** +- Les répertoires projet et utilisateur sont tous deux analysés (union — pas de priorité au premier scope) - Les fichiers sont chargés par ordre alphabétique dans chaque répertoire. Préfixez avec `01-`, `02-` pour contrôler l'ordre - Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés ; les autres fichiers sont ignorés - Chaque fichier est chargé indépendamment (fail-open par fichier) -- Fonctionne avec les options explicites `--custom` et les politiques intégrées +- Fonctionne en parallèle avec les fichiers `--custom` explicites et les politiques intégrées -Les politiques basées sur les conventions sont le moyen le plus simple d'établir un standard de qualité pour votre organisation. Commitez `.failproofai/policies/` dans git et chaque membre de l'équipe obtient automatiquement les mêmes règles — aucune configuration par développeur requise. Au fil de la découverte de nouveaux modes d'échec, ajoutez une politique et poussez. Ces politiques deviennent progressivement un standard de qualité vivant qui s'améliore à chaque contribution. +Les politiques de convention sont le moyen le plus simple d'établir un standard de qualité pour votre organisation. Commitez `.failproofai/policies/` dans git et chaque membre de l'équipe obtient automatiquement les mêmes règles — aucune configuration par développeur n'est nécessaire. Au fur et à mesure que votre équipe découvre de nouveaux modes de défaillance, ajoutez une politique et poussez. Avec le temps, elles deviennent un standard de qualité vivant qui s'améliore à chaque contribution. ### Option 2 : Chemin de fichier explicite @@ -79,16 +79,16 @@ failproofai policies --install --custom ./security.js --custom ./workflow.js failproofai policies --uninstall --custom ``` -Les chemins absolus résolus sont stockés dans `policies-config.json` sous `customPoliciesPaths`. Répétez `--custom` pour configurer plusieurs fichiers. Les configurations existantes utilisant le champ hérité `customPoliciesPath` continuent de fonctionner. Les fichiers sont rechargés à chaque événement de hook - il n'y a pas de mise en cache entre les événements. +Les chemins absolus résolus sont stockés dans `policies-config.json` sous `customPoliciesPaths`. Répétez `--custom` pour configurer plusieurs fichiers. Les configurations existantes utilisant le champ hérité `customPoliciesPath` continuent de fonctionner. Les fichiers sont chargés à neuf à chaque événement de hook — il n'y a pas de mise en cache entre les événements. -Chaque politique enregistrée apparaît avec son propre bouton de bascule dans le tableau de bord. Désactiver une politique enregistre son ID qualifié par la source dans `disabledCustomPolicies` ; le fichier et ses autres politiques continuent de se charger, tandis que la politique désactivée est exclue avant la correspondance d'événement. Les noms de politiques dupliqués entre fichiers ont des boutons de bascule indépendants. +Chaque politique enregistrée apparaît avec sa propre bascule dans le tableau de bord. Désactiver une politique enregistre son identifiant qualifié par la source dans `disabledCustomPolicies` ; le fichier et ses autres politiques continuent de se charger, tandis que la politique désactivée est exclue avant la correspondance d'événements. Les noms de politiques dupliqués entre fichiers ont des bascules indépendantes. ### Utiliser les deux ensemble -Les politiques basées sur les conventions et les fichiers `--custom` explicites peuvent coexister. Ordre de chargement : +Les politiques de convention et les fichiers `--custom` explicites peuvent coexister. Ordre de chargement : 1. Fichiers `customPoliciesPaths` explicites (dans l'ordre configuré) -2. Fichiers de convention du projet (`{cwd}/.failproofai/policies/`, ordre alphabétique) +2. Fichiers de convention projet (`{cwd}/.failproofai/policies/`, ordre alphabétique) 3. Fichiers de convention utilisateur (`~/.failproofai/policies/`, ordre alphabétique) --- @@ -109,7 +109,7 @@ Enregistre une politique. Appelez cette fonction autant de fois que nécessaire customPolicies.add({ name: string; // requis - identifiant unique description?: string; // affiché dans la sortie de `failproofai policies` - match?: { events?: HookEventType[] }; // filtrer par type d'événement ; omettez pour tout correspondre + match?: { events?: HookEventType[] }; // filtrer par type d'événement ; omettre pour correspondre à tous fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` @@ -118,30 +118,30 @@ customPolicies.add({ | Fonction | Effet | Utiliser quand | |----------|--------|----------| -| `allow()` | Autorise l'opération silencieusement | L'action est sûre, aucun message nécessaire | -| `deny(message)` | Bloque l'opération | L'agent ne devrait pas effectuer cette action | -| `instruct(message)` | Ajoute du contexte sans bloquer | Donner à l'agent un contexte supplémentaire pour rester sur la bonne voie | +| `allow()` | Autoriser l'opération silencieusement | L'action est sûre, aucun message n'est nécessaire | +| `deny(message)` | Bloquer l'opération | L'agent ne devrait pas effectuer cette action | +| `instruct(message)` | Ajouter du contexte sans bloquer | Donner à l'agent du contexte supplémentaire pour rester sur la bonne voie | `deny(message)` - le message apparaît à Claude préfixé par `"Blocked by failproofai:"`. Un seul `deny` court-circuite toute évaluation ultérieure. -`instruct(message)` - le message est ajouté au contexte de Claude pour l'appel d'outil en cours. Tous les messages `instruct` sont accumulés et délivrés ensemble. +`instruct(message)` - le message est ajouté au contexte de Claude pour l'appel d'outil en cours. Tous les messages `instruct` sont accumulés et transmis ensemble. -Vous pouvez ajouter des indications supplémentaires à n'importe quel message `deny` ou `instruct` en ajoutant un champ `hint` dans `policyParams` — aucune modification de code nécessaire. Cela fonctionne également pour les politiques personnalisées (`custom/`), les conventions de projet (`.failproofai-project/`) et les conventions utilisateur (`.failproofai-user/`). Consultez [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails. +Vous pouvez ajouter des instructions supplémentaires à n'importe quel message `deny` ou `instruct` en ajoutant un champ `hint` dans `policyParams` — aucune modification de code n'est nécessaire. Cela fonctionne également pour les politiques personnalisées (`custom/`), de convention projet (`.failproofai-project/`) et de convention utilisateur (`.failproofai-user/`). Consultez [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails. -### Messages d'autorisation informatifs +### Messages allow informationnels -`allow(message)` autorise l'opération **et** envoie un message informatif à Claude. Le message est délivré sous forme de `additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme utilisé par `instruct`, mais sémantiquement différent : c'est une mise à jour de statut, pas un avertissement. +`allow(message)` autorise l'opération **et** envoie un message informationnel à Claude. Le message est transmis en tant que `additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme qu'`instruct`, mais sémantiquement différent : c'est une mise à jour de statut, pas un avertissement. | Fonction | Effet | Utiliser quand | |----------|--------|----------| -| `allow(message)` | Autorise et envoie du contexte à Claude | Confirmer qu'une vérification a réussi, ou expliquer pourquoi une vérification a été ignorée | +| `allow(message)` | Autoriser et envoyer du contexte à Claude | Confirmer qu'une vérification a réussi, ou expliquer pourquoi une vérification a été ignorée | Cas d'utilisation : - **Confirmations de statut :** `allow("All CI checks passed.")` — indique à Claude que tout est en ordre - **Explications fail-open :** `allow("GitHub CLI not installed, skipping CI check.")` — indique à Claude pourquoi une vérification a été ignorée afin qu'il dispose du contexte complet -- **Accumulation de messages :** si plusieurs politiques retournent chacune `allow(message)`, tous les messages sont joints avec des sauts de ligne et délivrés ensemble +- **Accumulation de plusieurs messages :** si plusieurs politiques retournent chacune `allow(message)`, tous les messages sont joints avec des sauts de ligne et transmis ensemble ```js customPolicies.add({ @@ -183,7 +183,7 @@ customPolicies.add({ | Événement | Quand il se déclenche | Contenu de `toolInput` | |-------|--------------|----------------------| | `PreToolUse` | Avant que Claude exécute un outil | L'entrée de l'outil (ex. `{ command: "..." }` pour Bash) | -| `PostToolUse` | Après la fin d'un outil | L'entrée de l'outil + `tool_result` (la sortie) | +| `PostToolUse` | Après la complétion d'un outil | L'entrée de l'outil + `tool_result` (la sortie) | | `Notification` | Quand Claude envoie une notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - les hooks doivent toujours retourner `allow()`, ils ne peuvent pas bloquer les notifications | | `Stop` | Quand la session Claude se termine | Vide | @@ -194,12 +194,12 @@ customPolicies.add({ Les politiques sont évaluées dans cet ordre : 1. Politiques intégrées (dans l'ordre de définition) -2. Politiques personnalisées explicites de `customPoliciesPath` (dans l'ordre `.add()`) -3. Politiques de convention du projet `.failproofai/policies/` (fichiers par ordre alphabétique, ordre `.add()` à l'intérieur) -4. Politiques de convention utilisateur `~/.failproofai/policies/` (fichiers par ordre alphabétique, ordre `.add()` à l'intérieur) +2. Politiques personnalisées explicites de `customPoliciesPath` (dans l'ordre des `.add()`) +3. Politiques de convention projet `.failproofai/policies/` (fichiers alphabétiques, ordre `.add()` à l'intérieur) +4. Politiques de convention utilisateur `~/.failproofai/policies/` (fichiers alphabétiques, ordre `.add()` à l'intérieur) -Le premier `deny` court-circuite toutes les politiques suivantes. Tous les messages `instruct` sont accumulés et délivrés ensemble. +Le premier `deny` court-circuite toutes les politiques suivantes. Tous les messages `instruct` sont accumulés et transmis ensemble. --- @@ -247,18 +247,18 @@ Omettez `match` entièrement pour se déclencher sur chaque type d'événement. --- -## Gestion des erreurs et modes d'échec +## Gestion des erreurs et modes de défaillance Les politiques personnalisées sont **fail-open** : les erreurs ne bloquent jamais les politiques intégrées ni ne font planter le gestionnaire de hook. -| Échec | Comportement | +| Défaillance | Comportement | |---------|----------| -| `customPoliciesPath` non défini | Aucune politique personnalisée explicite ne s'exécute ; les politiques de convention et les intégrées continuent normalement | -| Fichier introuvable | Avertissement journalisé dans `~/.failproofai/hook.log` ; les politiques intégrées continuent | -| Erreur de syntaxe/import (explicite) | Erreur journalisée dans `~/.failproofai/hook.log` ; politiques personnalisées explicites ignorées | -| Erreur de syntaxe/import (convention) | Erreur journalisée ; ce fichier ignoré, les autres fichiers de convention se chargent quand même | -| `fn` lève une erreur à l'exécution | Erreur journalisée ; ce hook traité comme `allow` ; les autres hooks continuent | -| `fn` prend plus de 10 secondes | Délai d'expiration journalisé ; traité comme `allow` | +| `customPoliciesPath` non défini | Aucune politique personnalisée explicite ne s'exécute ; les politiques de convention et les politiques intégrées continuent normalement | +| Fichier introuvable | Avertissement enregistré dans `~/.failproofai/hook.log` ; les politiques intégrées continuent | +| Erreur de syntaxe/import (explicite) | Erreur enregistrée dans `~/.failproofai/hook.log` ; les politiques personnalisées explicites sont ignorées | +| Erreur de syntaxe/import (convention) | Erreur enregistrée ; ce fichier est ignoré, les autres fichiers de convention se chargent quand même | +| `fn` lève une exception à l'exécution | Erreur enregistrée ; ce hook est traité comme `allow` ; les autres hooks continuent | +| `fn` prend plus de 10s | Timeout enregistré ; traité comme `allow` | | Répertoire de convention manquant | Aucune politique de convention ne s'exécute ; aucune erreur | @@ -290,7 +290,7 @@ customPolicies.add({ }, }); -// Garder l'agent sur la bonne voie : vérifier les tests avant de commiter +// Maintenir l'agent sur la bonne voie : vérifier les tests avant de commiter customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -332,10 +332,10 @@ Le répertoire `examples/` contient des fichiers de politiques prêts à l'emplo | Fichier | Contenu | |------|----------| -| `examples/policies-basic.js` | Cinq politiques de démarrage couvrant les modes d'échec d'agent courants | -| `examples/policies-advanced/index.js` | Modèles avancés : imports transitifs, appels asynchrones, nettoyage de sortie et hooks de fin de session | +| `examples/policies-basic.js` | Cinq politiques de démarrage couvrant les modes de défaillance courants des agents | +| `examples/policies-advanced/index.js` | Modèles avancés : imports transitifs, appels asynchrones, nettoyage des sorties et hooks de fin de session | | `examples/convention-policies/security-policies.mjs` | Politiques de sécurité basées sur les conventions (bloquer les écritures .env, empêcher la réécriture de l'historique git) | -| `examples/convention-policies/workflow-policies.mjs` | Politiques de workflow basées sur les conventions (rappels de tests, journalisation des écritures de fichiers) | +| `examples/convention-policies/workflow-policies.mjs` | Politiques de workflow basées sur les conventions (rappels de tests, audit des écritures de fichiers) | ### Utiliser les exemples de fichiers explicites @@ -346,7 +346,7 @@ failproofai policies --install --custom ./examples/policies-basic.js ### Utiliser les exemples basés sur les conventions ```bash -# Copier au niveau du projet +# Copier au niveau projet mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ @@ -355,4 +355,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Aucune commande d'installation requise — les fichiers sont automatiquement pris en compte lors du prochain événement de hook. \ No newline at end of file +Aucune commande d'installation n'est nécessaire — les fichiers sont automatiquement détectés au prochain événement de hook. \ No newline at end of file diff --git a/docs/fr/dashboard.mdx b/docs/fr/dashboard.mdx index 4922603d..1b17a928 100644 --- a/docs/fr/dashboard.mdx +++ b/docs/fr/dashboard.mdx @@ -1,14 +1,14 @@ --- -title: Dashboard +title: Tableau de bord description: "Surveiller les sessions d'agents, examiner les appels d'outils et gérer les politiques" icon: chart-line --- -Le dashboard failproofai est une application web locale permettant de surveiller vos sessions d'agents IA et de gérer les politiques. Voyez ce que vos agents ont fait pendant votre absence. +Le tableau de bord failproofai est une application web locale permettant de surveiller vos sessions d'agents IA et de gérer vos politiques. Consultez ce que vos agents ont fait pendant votre absence. --- -## Démarrer le dashboard +## Démarrage du tableau de bord ```bash failproofai @@ -16,7 +16,7 @@ failproofai S'ouvre à l'adresse `http://localhost:8020`. -Le dashboard lit les données de configuration locales du projet, des sessions et de failproofai directement depuis le système de fichiers. Les fonctionnalités optionnelles authentifiées, telles que les rappels d'audit et les invitations, transmettent les informations nécessaires à ces requêtes (y compris les adresses e-mail) vers des API distantes. +Le tableau de bord lit les données locales de projet, de session et de configuration failproofai directement depuis le système de fichiers. Les fonctionnalités optionnelles authentifiées, telles que les rappels d'audit et les invitations, envoient les informations nécessaires à ces requêtes (y compris les adresses e-mail) vers des API distantes. --- @@ -24,9 +24,9 @@ Le dashboard lit les données de configuration locales du projet, des sessions e ### Projets -Liste tous les projets Claude Code, OpenAI Codex, GitHub Copilot CLI _(bêta)_, Cursor Agent _(bêta)_, OpenCode _(bêta)_, Pi _(bêta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity et Goose trouvés sur votre machine. Les projets Claude sont découverts depuis `~/.claude/projects/` (ou le chemin défini par `CLAUDE_PROJECTS_PATH`) ; les projets Codex sont découverts en analysant chaque transcription sous `~/.codex/sessions///
/*.jsonl` et regroupés par le `cwd` enregistré dans le premier enregistrement de chaque session ; les projets Copilot CLI sont découverts en analysant chaque fichier `~/.copilot/session-state//workspace.yaml` (configurable via `COPILOT_HOME`) et regroupés par son champ `cwd` ; les projets Cursor Agent sont découverts en analysant les métadonnées par session sous `~/.cursor/agent-sessions//` (configurable via `CURSOR_HOME`, avec `conversations/` et `sessions/` sondés comme alternatives) pour un scalaire `cwd` dans `meta.json` / `session.json` / `workspace.yaml` ; les projets OpenCode sont découverts en interrogeant sa base de données SQLite à `~/.local/share/opencode/opencode.db` via `opencode db --format json` (nous lisons les tables `session` et `project` et regroupons par `project_id`) ; les projets Pi sont découverts en analysant les transcriptions JSONL par session sous `~/.pi/agent/sessions//_.jsonl` (configurable via `PI_SESSIONS_DIR`) et en extrayant le `cwd` du premier enregistrement de chaque session ; les sessions de passerelle Hermes sont lues directement depuis le magasin SQLite de chaque profil — `~/.hermes/state.db` plus `~/.hermes/profiles//state.db` (remplaçable via `HERMES_HOME`, ou `HERMES_DB_PATH` pour une seule base de données) — et regroupées en projets `hermes--` par profil et `source` (Slack/Telegram/cli/cron — les sessions de passerelle n'ont pas de cwd) ; les sessions de passerelle OpenClaw sont lues depuis `~/.openclaw/agents//sessions/*.jsonl` et regroupées en projets `openclaw--` par agent et canal (également sans cwd) ; les projets Factory Droid sont découverts depuis les transcriptions JSONL à `~/.factory/sessions//*.jsonl` et regroupés par cwd ; les projets Devin depuis sa base de données SQLite à `~/.local/share/devin/cli/sessions.db` (regroupés par le `working_directory` de chaque session) ; les projets Antigravity depuis les transcriptions JSONL à `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` et regroupés par cwd ; et les projets Goose depuis sa base de données SQLite à `~/.local/share/goose/sessions/sessions.db` (regroupés par le `working_dir` de chaque session). Un projet utilisé par plusieurs CLI s'affiche sur une seule ligne avec tous les badges correspondants. Utilisez le menu déroulant **CLI** au-dessus du tableau pour filtrer par un agent CLI spécifique ; l'URL conserve votre sélection sous la forme `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Répertorie tous les projets Claude Code, OpenAI Codex, GitHub Copilot CLI _(bêta)_, Cursor Agent _(bêta)_, OpenCode _(bêta)_, Pi _(bêta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity et Goose trouvés sur votre machine. Les projets Claude sont découverts depuis `~/.claude/projects/` (ou le chemin défini par `CLAUDE_PROJECTS_PATH`) ; les projets Codex sont découverts en analysant chaque transcript sous `~/.codex/sessions///
/*.jsonl` et en les regroupant par le `cwd` enregistré dans le premier enregistrement de chaque session ; les projets Copilot CLI sont découverts en analysant chaque `~/.copilot/session-state//workspace.yaml` (configurable via `COPILOT_HOME`) et en les regroupant par leur champ `cwd` ; les projets Cursor Agent sont découverts en analysant les métadonnées par session sous `~/.cursor/agent-sessions//` (configurable via `CURSOR_HOME`, avec `conversations/` et `sessions/` comme chemins de secours) à la recherche d'un scalaire `cwd` dans `meta.json` / `session.json` / `workspace.yaml` ; les projets OpenCode sont découverts en interrogeant sa base de données SQLite à `~/.local/share/opencode/opencode.db` via `opencode db --format json` (nous lisons les tables `session` et `project` et les regroupons par `project_id`) ; les projets Pi sont découverts en analysant les transcripts JSONL par session sous `~/.pi/agent/sessions//_.jsonl` (configurable via `PI_SESSIONS_DIR`) et en extrayant le `cwd` du premier enregistrement de chaque session ; les sessions de la passerelle Hermes sont lues directement depuis le store SQLite de chaque profil — `~/.hermes/state.db` ainsi que `~/.hermes/profiles//state.db` (modifiable via `HERMES_HOME`, ou `HERMES_DB_PATH` pour une base de données unique) — et regroupées en projets `hermes--` par profil et `source` (Slack/Telegram/cli/cron — les sessions de passerelle n'ont pas de cwd) ; les sessions de la passerelle OpenClaw sont lues depuis `~/.openclaw/agents//sessions/*.jsonl` et regroupées en projets `openclaw--` par agent et canal (sans cwd également) ; les projets Factory Droid sont découverts à partir des transcripts JSONL situés à `~/.factory/sessions//*.jsonl` et regroupés par cwd ; les projets Devin à partir de sa base de données SQLite à `~/.local/share/devin/cli/sessions.db` (regroupés par `working_directory` de chaque session) ; les projets Antigravity à partir des transcripts JSONL situés à `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` et regroupés par cwd ; et les projets Goose à partir de sa base de données SQLite à `~/.local/share/goose/sessions/sessions.db` (regroupés par `working_dir` de chaque session). Un projet utilisé par plusieurs CLI s'affiche comme une ligne unique avec tous les badges correspondants. Utilisez le menu déroulant **CLI** au-dessus du tableau pour filtrer par agent CLI spécifique ; l'URL conserve votre sélection sous la forme `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -Hermes et OpenClaw sont limités à l'utilisateur et n'ont pas de répertoire de travail pour le regroupement, ils s'affichent donc sous forme d'**arborescence repliable** — profil (ou agent) au premier niveau, ses canaux en dessous — tandis que chaque CLI basé sur un cwd reste une ligne plate. Les lignes de dossier cumulent le nombre de sessions et l'activité la plus récente de tout ce qu'elles contiennent, les dossiers réduits sont mémorisés entre les visites, et une recherche par mot-clé développe tout ce qui correspond. +Hermes et OpenClaw sont à portée utilisateur et n'ont pas de répertoire de travail pour le regroupement, ils s'affichent donc sous forme d'**arborescence de dossiers repliable** — le profil (ou l'agent) au niveau supérieur, ses canaux en dessous — tandis que chaque CLI basé sur un cwd reste une ligne plate. Les lignes de dossiers totalisent le nombre de sessions et l'activité la plus récente de tout ce qu'elles contiennent, les dossiers repliés sont mémorisés entre les visites, et une recherche par mot-clé développe les correspondances. Chaque projet affiche : - Le nom du projet (dérivé du chemin du dossier) @@ -37,7 +37,7 @@ Cliquez sur un projet pour voir ses sessions. ### Sessions -Liste toutes les sessions au sein d'un projet. Chaque session affiche : +Répertorie toutes les sessions d'un projet. Chaque session affiche : - L'identifiant de session - Les horodatages de début et de fin - Le nombre d'appels d'outils @@ -45,31 +45,31 @@ Liste toutes les sessions au sein d'un projet. Chaque session affiche : Utilisez le filtre de plage de dates et la recherche par identifiant de session pour affiner la liste. Les sessions sont paginées. -Cliquez sur une session pour ouvrir le visualiseur de session. +Cliquez sur une session pour ouvrir la visionneuse de session. -### Visualiseur de session +### Visionneuse de session -Le visualiseur de session répond à la question clé pour les agents autonomes : qu'a fait l'agent, et est-il resté dans les limites fixées ? Un badge CLI à côté de l'en-tête indique si la session est une transcription Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ou Goose. Il affiche une chronologie de tout ce qui s'est passé durant une session : +La visionneuse de session répond à la question clé pour les agents autonomes : qu'a fait l'agent, et est-il resté dans les rails ? Un badge CLI à côté de l'en-tête indique si la session est un transcript Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ou Goose. Elle affiche une chronologie de tout ce qui s'est passé dans une session : - **Messages** - Les réponses textuelles de Claude et les invites utilisateur -- **Appels d'outils** - Chaque outil invoqué par Claude, avec son entrée et sa sortie -- **Activité des politiques** - Pour chaque appel d'outil, quelles politiques se sont déclenchées et quelle décision elles ont rendu +- **Appels d'outils** - Chaque outil invoqué par Claude, avec ses entrées et sorties +- **Activité des politiques** - Pour chaque appel d'outil, quelles politiques ont été déclenchées et quelle décision elles ont retournée La barre de statistiques en haut affiche la durée de la session, le nombre total d'appels d'outils et un résumé des décisions de hook (comptages allow / deny / instruct). -Cliquez sur le bouton **Télécharger les journaux** pour exporter la session. Pour les sessions Claude Code, Codex, Copilot, Cursor et Pi, vous obtenez la transcription JSONL originale sur disque octet par octet ; pour OpenCode (dont les sessions résident dans SQLite et non sur disque), vous obtenez un document JSON reflétant les tables sous-jacentes `session` / `messages` / `parts`. +Cliquez sur le bouton **Download Logs** pour exporter la session. Pour les sessions Claude Code, Codex, Copilot, Cursor et Pi, vous obtenez le transcript JSONL original sur disque octet par octet ; pour OpenCode (dont les sessions résident dans SQLite, pas sur disque) vous obtenez un document JSON reflétant les tables sous-jacentes `session` / `messages` / `parts`. ### Audit -Un rapport à personnalité qui rend compte du comportement réel de votre agent sur les sessions passées. Exécute la même analyse que la CLI `failproofai audit` mais l'affiche sous forme d'une affiche partageable en plein écran + quatre sections sous le pli : +Un rapport à la personnalité marquée sur le comportement réel de votre agent à travers les sessions passées. Exécute la même analyse que la CLI `failproofai audit` mais la restitue sous forme d'une affiche partageable plein écran + quatre sections sous le pli : -1. **Affiche** — occupe le premier viewport. Zone de capture PNG autonome avec le logo failproof_ai + libellé d'audit · index d'archétype (`№ NN of 08`) + date d'audit · score numérique (0–100) + pastille de rang percentile (`top 15%`) · le nom de l'archétype (l'un parmi `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + bande de 3 mots-clés · ligne de rareté `// only N% of agents are this archetype` · tuile de sigil 8×8 pixels · pied de page `audit yours → failproof.ai`. Trois boutons de partage se trouvent juste en dehors de la zone de capture : `post your archetype` (intention X), `share on linkedin`, `download poster`. La capture s'effectue via `html-to-image` afin que le PNG corresponde pixel par pixel au rendu à l'écran (bordures en pointillés, masque de logo SVG, dégradés, métriques de police — tout est préservé). -2. **Points forts** — liste de comportements que votre agent réalise déjà correctement, dérivés des données d'audit en direct (taux d'appels d'outils propres, pas de push direct sur main, zéro fuite d'identifiants, zéro tempête de nouvelles tentatives) — chacun affiché uniquement lorsque la politique concernée présente un bilan propre sur la fenêtre d'audit. -3. **Comportements inhabituels** — tableau de ce qui est passé au travers, classé par sévérité : `quand · ce qui a passé + la politique qui l'aurait intercepté · pastille de sévérité · observé`, où la récurrence indique `new` (une fois), `N× seen` (2–9 fois) ou `recurring` (10+). -4. **Comment s'améliorer** — liste calme, une entrée par politique prescrite : nom de la politique en blanc, description en une ligne, commande d'installation + bouton de copie sur le côté droit. L'en-tête de section indique `enable all N → projected · ` (le score que vous atteindriez avec tous les correctifs appliqués), et son bouton `[install all]` copie la commande combinée `failproofai policy add a b c …` pour chaque politique prescrite. -5. **Revenez meilleur** — deux cartes côte à côte. À gauche : définir un rappel (sélecteur de cadence `3d` / `7d` / `14d` / `30d` ; persiste via `/api/auth/reminder` une fois authentifié). À droite : débloquer des avantages failproof — `invite a friend` ouvre une fenêtre modale acceptant une liste d'adresses e-mail d'amis séparées par des virgules/espaces/sauts de ligne (10 maximum par envoi), les envoie via POST à `/api/audit/invite`, qui les transmet au `POST /v0/invite` du serveur API. Le serveur API envoie un e-mail par destinataire depuis `invite@failproof.ai` avec l'expéditeur en Cc et `Reply-To` défini, de sorte que le destinataire voit qui l'a invité et l'expéditeur reçoit une copie dans sa boîte de réception. Les utilisateurs anonymes sont d'abord redirigés via `AuthDialog` afin que l'adresse e-mail de l'expéditeur soit connue avant l'envoi des invitations. La gestion des droits / avantages est prévue dans une prochaine étape. +1. **Affiche** — occupe le premier écran. Zone de capture PNG autonome avec le logotype failproof_ai + étiquette d'audit · index d'archétype (`№ NN of 08`) + date d'audit · score numérique (0–100) + pastille de rang percentile (`top 15%`) · le nom de l'archétype (l'un de : `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + bandeau de 3 mots-clés · ligne de rareté `// only N% of agents are this archetype` · tuile sigil 8×8 pixels · pied de page `audit yours → failproof.ai`. Trois boutons de partage se trouvent juste en dehors de la zone de capture : `post your archetype` (intent X), `share on linkedin`, `download poster`. La capture passe par `html-to-image`, le PNG correspondant au rendu à l'écran pixel par pixel (bordures en pointillés, masque SVG du logo, dégradés, métriques de police — tout conservé). +2. **Points forts** — liste de lignes ✓ sereine sur les comportements que votre agent fait déjà bien, dérivés des données d'audit en direct (taux d'appels d'outils propre, pas de push direct vers main, zéro fuite d'identifiants, zéro tempête de tentatives) — chacun affiché uniquement lorsque la politique concernée a un historique propre sur la fenêtre d'audit. +3. **Particularités** — tableau de ce qui a glissé entre les mailles, classé par sévérité : `when · what slipped + the policy that would've caught it · severity pill · seen`, où la récurrence s'affiche `new` (une fois), `N× seen` (2–9 fois) ou `recurring` (10+). +4. **Comment s'améliorer** — liste de lignes sereine, une par politique prescrite : nom de politique en blanc, description en une ligne, commande d'installation + bouton de copie sur la droite. L'en-tête de section indique `enable all N → projected · ` (le score que vous atteindriez avec chaque correction appliquée), et son bouton `[install all]` copie la commande combinée `failproofai policy add a b c …` pour chaque politique prescrite. +5. **Revenez mieux** — deux cartes côte à côte. Gauche : définir un rappel (sélecteur de cadence `3d` / `7d` / `14d` / `30d` ; persiste via `/api/auth/reminder` une fois authentifié). Droite : débloquer les avantages failproof — `invite a friend` ouvre une modale acceptant une liste d'adresses e-mail d'amis séparées par des virgules, espaces ou sauts de ligne (max 10 par envoi), les envoie en POST à `/api/audit/invite`, qui les transfère au serveur API via `POST /v0/invite`. Le serveur API envoie un e-mail par destinataire depuis `invite@failproof.ai` avec l'expéditeur en Cc et `Reply-To` défini, de sorte que le destinataire voit qui l'a invité et l'expéditeur reçoit une copie dans sa boîte de réception. Les utilisateurs anonymes sont d'abord redirigés vers `AuthDialog` afin que l'adresse e-mail de l'expéditeur soit connue avant l'envoi des invitations. Les droits / avantages seront traités dans une prochaine version. -Alimenté par le moteur d'exécution `failproofai audit` — voir [CLI Audit](/fr/cli/audit) pour le moteur d'analyse sous-jacent, les indicateurs pris en charge et les invariants de cache par transcription. Le dashboard met en cache le dernier résultat dans `~/.failproofai/audit-dashboard.json` (mode `0600`, emplacement unique, les nouvelles exécutions écrasent) afin que les revisites soient instantanées ; **les caches par transcription et par résultat complet sont tous deux rejetés à la lecture s'ils ont plus de 7 jours**, ainsi le dashboard ne sert jamais silencieusement un résultat vieux d'une semaine — passé la TTL, `/audit` retombe sur son état vide et invite à relancer une analyse. Cliquer sur `[ re-audit now ]` près du bas du rapport envoie un POST `/api/audit/run` avec `noCache: true` — la ré-analyse contourne le cache par transcription et réanalyse chaque transcription depuis le début plutôt que de retourner silencieusement le résultat mis en cache — et le dashboard interroge `/api/audit/status` à 1 Hz jusqu'à la fin de l'exécution ; une bande de progression rose épinglée s'affiche en haut du viewport pendant l'exécution avec un minuteur écoulé, et le nouveau résultat remplace l'ancien en place en cas de succès (sans rechargement de page ; une ré-analyse échouée laisse le rapport précédent intact). En cas d'échec, la bande devient rouge avec un message basé sur `RerunError.kind` (`timeout` / `network` / `post_failed`). L'état vide (pas de cache ou expiré) et l'état zéro session (le cache existe mais l'analyse n'a trouvé aucune transcription) sont affichés séparément. +Piloté par le runtime `failproofai audit` — consultez [Audit CLI](/fr/cli/audit) pour le moteur d'analyse sous-jacent, les options supportées et les invariants du cache par transcript. Le tableau de bord met en cache le dernier résultat à `~/.failproofai/audit-dashboard.json` (mode `0600`, emplacement unique, les nouvelles exécutions écrasent l'ancien) pour des visites instantanées ; **les deux caches (par transcript et résultat global) sont rejetés à la lecture lorsqu'ils ont plus de 7 jours**, de sorte que le tableau de bord ne serve jamais silencieusement un résultat vieux d'une semaine — passé la durée de vie, `/audit` tombe dans son état vide et invite à relancer une analyse. Cliquer sur `[ re-audit now ]` en bas du rapport envoie un POST à `/api/audit/run` avec `noCache: true` — la ré-analyse contourne le cache par transcript et réanalyse chaque transcript depuis zéro plutôt que de retourner silencieusement le résultat mis en cache — et le tableau de bord interroge `/api/audit/status` à 1 Hz jusqu'à la fin de l'exécution ; une bande de progression rose fixe s'accroche en haut de l'écran pendant l'exécution avec un minuteur écoulé, et le nouveau résultat s'affiche en place en cas de succès (pas de rechargement complet de la page ; une ré-analyse échouée laisse le rapport précédent intact). En cas d'échec, la bande devient rouge avec un message basé sur le `RerunError.kind` (`timeout` / `network` / `post_failed`). L'état vide (pas de cache ou expiré) et l'état zéro session (cache existant mais l'analyse n'a trouvé aucun transcript) sont affichés séparément. ### Politiques @@ -77,16 +77,16 @@ Une page à deux onglets pour gérer les politiques et examiner l'activité. - - Sélection multiple des CLI d'agents que failproofai protège depuis un seul panneau — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi et Hermes ont chacun une ligne avec le statut d'installation (`Active` / `Detected` / `Inactive`), le chemin des paramètres de portée utilisateur et un accent coloré à la marque. Cochez ou décochez les CLI souhaités et cliquez sur `Apply changes` pour installer/désinstaller le delta en une seule étape. Les CLI dont le binaire est détecté dans le PATH sont pré-cochés. - - Activez ou désactivez individuellement les politiques en un seul clic (écrit dans `~/.failproofai/policies-config.json` — partagé entre tous les CLI installés) - - Développez une politique pour configurer ses paramètres (pour les politiques prenant en charge `policyParams`) + - Sélection multiple des CLI d'agents que failproofai protège depuis un seul panneau — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi et Hermes ont chacun une ligne avec le statut d'installation (`Active` / `Detected` / `Inactive`), le chemin des paramètres à portée utilisateur et un accent de couleur de marque. Cochez ou décochez les CLI souhaités et cliquez sur `Apply changes` pour installer/désinstaller la différence en une seule étape. Les CLI dont le binaire est détecté dans le PATH sont pré-cochés. + - Activez ou désactivez individuellement les politiques d'un seul clic (écrit dans `~/.failproofai/policies-config.json` — partagé entre tous les CLI installés) + - Développez une politique pour configurer ses paramètres (pour les politiques qui supportent `policyParams`) - Définissez un chemin de fichier de politiques personnalisé - Historique paginé complet de chaque événement de hook déclenché dans toutes les sessions - - Filtrez par décision, type d'événement, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(bêta)_ / Cursor Agent _(bêta)_ / OpenCode _(bêta)_ / Pi _(bêta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nom de politique ou identifiant de session - - Chaque ligne affiche : horodatage, nom de la politique, décision, badge CLI (orange = Claude Code, violet = OpenAI Codex, bleu = GitHub Copilot, émeraude = Cursor Agent, ambre = OpenCode, rose = Pi, indigo = Hermes, sarcelle = OpenClaw, rose foncé = Factory Droid, violet foncé = Devin, cyan = Antigravity, lime = Goose), nom de l'outil, identifiant de session et la raison des décisions deny/instruct - - Cliquez sur un identifiant de session pour ouvrir sa transcription — le visualiseur détecte automatiquement quel CLI a déclenché le hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) et affiche le badge CLI correspondant dans l'en-tête + - Filtrage par décision, type d'événement, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(bêta)_ / Cursor Agent _(bêta)_ / OpenCode _(bêta)_ / Pi _(bêta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nom de politique ou identifiant de session + - Chaque ligne affiche : horodatage, nom de politique, décision, badge CLI (orange = Claude Code, violet = OpenAI Codex, bleu = GitHub Copilot, émeraude = Cursor Agent, ambre = OpenCode, rose = Pi, indigo = Hermes, sarcelle = OpenClaw, rose vif = Factory Droid, violet = Devin, cyan = Antigravity, vert citron = Goose), nom d'outil, identifiant de session et la raison des décisions deny/instruct + - Cliquez sur un identifiant de session pour ouvrir son transcript — la visionneuse détecte automatiquement quel CLI a déclenché le hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) et affiche le badge CLI correspondant dans l'en-tête @@ -94,13 +94,13 @@ Une page à deux onglets pour gérer les politiques et examiner l'activité. ## Actualisation automatique -Le dashboard dispose d'un bouton d'activation de l'actualisation automatique dans la navigation supérieure. Lorsqu'elle est activée, la page actuelle s'actualise périodiquement pour afficher les nouvelles sessions et l'activité des politiques au fur et à mesure. Indispensable pour surveiller les sessions d'agents autonomes de longue durée. +Le tableau de bord dispose d'un bouton d'actualisation automatique dans la navigation supérieure. Lorsqu'elle est activée, la page actuelle se rafraîchit périodiquement pour afficher les nouvelles sessions et l'activité des politiques au fur et à mesure. Indispensable pour surveiller les sessions d'agents autonomes de longue durée. --- -## Désactiver des pages +## Désactivation de pages -Si vous n'avez besoin que de certaines parties du dashboard, définissez `FAILPROOFAI_DISABLE_PAGES` avec une liste de noms de pages séparés par des virgules : +Si vous n'avez besoin que de certaines parties du tableau de bord, définissez `FAILPROOFAI_DISABLE_PAGES` avec une liste de noms de pages séparés par des virgules : ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,9 +110,9 @@ Valeurs valides : `policies`, `projects`, `audit`. --- -## Configurer le chemin des projets +## Configuration du chemin des projets -Par défaut, le dashboard lit depuis le répertoire de projets Claude Code standard. Remplacez-le pour des configurations personnalisées : +Par défaut, le tableau de bord lit depuis le répertoire de projets Claude Code standard. Modifiez-le pour des configurations personnalisées : ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,15 +120,15 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Accès depuis un hôte non-localhost +## Accès depuis un hôte autre que localhost -Lorsque vous exécutez le dashboard en **mode développement** (`npm run dev`) et y accédez depuis un nom d'hôte autre que `localhost` — par exemple, un domaine personnalisé, une IP distante ou une URL tunnelisée — vous pouvez voir un avertissement tel que : +Lors de l'exécution du tableau de bord en **mode développement** (`npm run dev`) et de l'accès depuis un nom d'hôte autre que `localhost` — par exemple, un domaine personnalisé, une IP distante ou une URL tunnelisée — vous pourriez voir un avertissement tel que : ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Il s'agit de Next.js qui bloque l'accès cross-origin à son websocket HMR (rechargement de module à chaud), une fonctionnalité exclusivement liée au mode développement. Pour autoriser votre hôte, utilisez l'indicateur `--allowed-origins` : +Il s'agit de Next.js bloquant l'accès cross-origin à son websocket HMR (rechargement à chaud des modules), qui est une fonctionnalité réservée au mode développement. Pour autoriser votre hôte, utilisez l'option `--allowed-origins` : ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -147,5 +147,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Ceci s'applique uniquement au mode développement. Lors de l'exécution de `failproofai` (mode production), il n'y a pas de websocket HMR ni de problème de ressource de développement cross-origin. +Cela s'applique uniquement au mode développement. Lors de l'exécution de `failproofai` (mode production), il n'y a pas de websocket HMR ni de problème de ressource cross-origin en développement. \ No newline at end of file diff --git a/docs/fr/examples.mdx b/docs/fr/examples.mdx index ed6cf212..b6ece4cb 100644 --- a/docs/fr/examples.mdx +++ b/docs/fr/examples.mdx @@ -1,16 +1,16 @@ --- title: Exemples -description: "Comment configurer des hooks pour Claude Code et l'Agents SDK" +description: "Comment configurer des hooks pour Claude Code et le Agents SDK" icon: book-open --- -Des exemples prêts à l'emploi pour les scénarios courants. Chacun montre comment installer et ce à quoi s'attendre. +Exemples prêts à l'emploi pour les scénarios courants. Chacun montre comment effectuer l'installation et ce à quoi vous pouvez vous attendre. --- ## Configurer des hooks pour Claude Code -Failproof AI s'intègre à Claude Code via son [système de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Lorsque vous exécutez `failproofai policies --install`, des commandes de hook sont enregistrées dans le fichier `settings.json` de Claude Code et se déclenchent à chaque appel d'outil. +Failproof AI s'intègre à Claude Code via son [système de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Lorsque vous exécutez `failproofai policies --install`, il enregistre des commandes de hook dans le fichier `settings.json` de Claude Code, qui se déclenchent à chaque appel d'outil. @@ -41,9 +41,9 @@ Failproof AI s'intègre à Claude Code via son [système de hooks](https://docs. --- -## Configurer des hooks pour l'Agents SDK +## Configurer des hooks pour le Agents SDK -Si vous développez avec l'[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), vous pouvez utiliser le même système de hooks de manière programmatique. +Si vous développez avec le [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), vous pouvez utiliser le même système de hooks de manière programmatique. @@ -52,7 +52,7 @@ Si vous développez avec l'[Agents SDK](https://docs.anthropic.com/en/docs/agent ``` - Passez des commandes de hook lors de la création de votre processus d'agent. Les hooks se déclenchent de la même façon que dans Claude Code — via stdin/stdout JSON : + Transmettez des commandes de hook lors de la création de votre processus agent. Les hooks se déclenchent de la même façon que dans Claude Code — via du JSON en stdin/stdout : ```bash failproofai --hook PreToolUse # appelé avant chaque outil @@ -86,7 +86,7 @@ Si vous développez avec l'[Agents SDK](https://docs.anthropic.com/en/docs/agent --- -## Bloquer les commandes destructives +## Bloquer les commandes destructrices La configuration la plus courante — empêcher les agents de causer des dommages irréversibles. @@ -102,21 +102,21 @@ Ce que cela fait : --- -## Prévenir les fuites de secrets +## Empêcher les fuites de secrets -Empêcher les agents de voir ou de divulguer des identifiants dans la sortie des outils. +Empêchez les agents de voir ou de divulguer des identifiants dans la sortie des outils. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Ces politiques se déclenchent sur `PostToolUse` — après l'exécution d'un outil, elles nettoient la sortie avant que l'agent ne la voie. +Ces politiques se déclenchent sur `PostToolUse` — après l'exécution d'un outil, elles purgent la sortie avant que l'agent ne la consulte. --- ## Recevoir des alertes Slack quand les agents ont besoin d'attention -Utilisez le hook de notification pour transférer les alertes d'inactivité vers Slack. +Utilisez le hook de notification pour transmettre les alertes d'inactivité à Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -160,7 +160,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## Maintenir les agents sur une branche -Empêcher les agents de changer de branche ou de pousser vers des branches protégées. +Empêchez les agents de changer de branche ou de pousser vers des branches protégées. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +184,7 @@ customPolicies.add({ ## Exiger des tests avant les commits -Rappeler aux agents d'exécuter les tests avant de faire un commit. +Rappeler aux agents d'exécuter les tests avant de committer. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -208,7 +208,7 @@ customPolicies.add({ ## Verrouiller un dépôt de production -Commitez une configuration au niveau du projet afin que tous les développeurs de votre équipe bénéficient des mêmes politiques. +Committez une configuration au niveau du projet afin que tous les développeurs de votre équipe bénéficient des mêmes politiques. Créez `.failproofai/policies-config.json` dans votre dépôt : @@ -231,20 +231,20 @@ Créez `.failproofai/policies-config.json` dans votre dépôt : } ``` -Puis commitez-le : +Puis committez-le : ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -Chaque membre de l'équipe ayant failproofai installé récupèrera automatiquement ces règles. +Chaque membre de l'équipe ayant failproofai installé appliquera automatiquement ces règles. --- -## Établir un standard de qualité à l'échelle de l'organisation avec des politiques de convention +## Établir un standard qualité à l'échelle de l'organisation avec des politiques de convention -La configuration la plus impactante : commitez `.failproofai/policies/` dans votre dépôt avec des politiques adaptées à votre projet. Chaque membre de l'équipe les obtient automatiquement — aucune commande d'installation, aucun changement de configuration. +La configuration la plus impactante : committez `.failproofai/policies/` dans votre dépôt avec des politiques adaptées à votre projet. Tous les membres de l'équipe en bénéficient automatiquement — aucune commande d'installation, aucune modification de configuration. @@ -256,8 +256,8 @@ La configuration la plus impactante : commitez `.failproofai/policies/` dans vot // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Enforce your team's preferred package manager - // (or enable the built-in prefer-package-manager policy instead) + // Imposer le gestionnaire de paquets préféré de l'équipe + // (ou activer à la place la politique intégrée prefer-package-manager) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, @@ -269,7 +269,7 @@ La configuration la plus impactante : commitez `.failproofai/policies/` dans vot }, }); - // Remind the agent to run tests before committing + // Rappeler à l'agent d'exécuter les tests avant de committer customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, @@ -283,14 +283,14 @@ La configuration la plus impactante : commitez `.failproofai/policies/` dans vot }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Au fur et à mesure que votre équipe rencontre de nouveaux modes de défaillance, ajoutez des politiques et poussez-les. Tout le monde reçoit la mise à jour au prochain `git pull`. Ces politiques deviennent un standard de qualité vivant qui évolue avec votre équipe. + Au fur et à mesure que votre équipe rencontre de nouveaux problèmes, ajoutez des politiques et poussez-les. Tout le monde reçoit la mise à jour au prochain `git pull`. Ces politiques deviennent un standard qualité vivant qui évolue avec votre équipe. @@ -301,7 +301,7 @@ La configuration la plus impactante : commitez `.failproofai/policies/` dans vot Le répertoire [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) du dépôt contient : | Fichier | Ce qu'il illustre | -|------|---------------| -| `policies-basic.js` | Politiques de base — bloquer les écritures en production, le force-push, les scripts via pipe | +|---------|-------------------| +| `policies-basic.js` | Politiques de base — bloquer les écritures en production, les force-push, les scripts pipés | | `policies-notification.js` | Alertes Slack pour les notifications d'inactivité et la fin de session | -| `policies-advanced/index.js` | Imports transitifs, hooks asynchrones, nettoyage de la sortie avec PostToolUse, gestion de l'événement Stop | \ No newline at end of file +| `policies-advanced/index.js` | Imports transitifs, hooks asynchrones, purge de sortie avec PostToolUse, gestion de l'événement Stop | \ No newline at end of file diff --git a/docs/fr/for-agents.mdx b/docs/fr/for-agents.mdx index 99c05803..b745b607 100644 --- a/docs/fr/for-agents.mdx +++ b/docs/fr/for-agents.mdx @@ -1,38 +1,38 @@ --- title: "Pour les agents" -description: "Ajoutez la documentation Failproof AI à votre agent de développement en une seule commande. Compatible avec Claude Code, Cursor, Windsurf et plus encore." +description: "Ajoutez la documentation Failproof AI à votre agent de code en une seule commande. Compatible avec Claude Code, Cursor, Windsurf et bien d'autres." --- -Ajoutez la référence complète Failproof AI à votre agent de développement en une seule commande. Compatible avec Claude Code, Cursor, Windsurf et tout autre agent prenant en charge les skills. +Ajoutez la documentation complète de Failproof AI à votre agent de code en une seule commande. Compatible avec Claude Code, Cursor, Windsurf et tout autre agent prenant en charge les skills. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` détecte les agents que vous avez installés et ajoute le skill dans le bon format pour chacun d'eux automatiquement. +`npx skills` détecte les agents installés sur votre machine et ajoute le skill dans le format approprié pour chacun d'eux, automatiquement. ## Ce que couvre le skill -| Domaine | Contenu | -|---------|---------| -| Policies | Noms des policies intégrées, types d'événements, paramètres, activation/désactivation | +| Domaine | Contenu inclus | +|---------|----------------| +| Policies | Noms des politiques intégrées, types d'événements, paramètres, activation/désactivation | | Custom policies | `customPolicies.add()`, filtres de correspondance, API `allow`/`deny`/`instruct` | -| Objet contexte | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | +| Objet de contexte | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Configuration | Structure de `policies-config.json`, fusion des scopes, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes | -| Dashboard | Visionneuse de sessions, activité des policies, variables d'environnement | -| Architecture | Flux du hook handler, codes de sortie, contrat stdin/stdout | +| Dashboard | Visionneuse de sessions, activité des politiques, variables d'environnement | +| Architecture | Flux du gestionnaire de hooks, codes de sortie, contrat stdin/stdout | ## Le skill est-il complet ? -Mintlify génère un fichier `llms.txt` à partir de toutes les pages de la navigation. La documentation Failproof AI couvre l'API complète — chaque policy, option et exemple est inclus. Si vous constatez qu'il manque quelque chose, la source est disponible à l'adresse `https://docs.befailproof.ai/llms-full.txt`. +Mintlify génère `llms.txt` à partir de toutes les pages présentes dans la navigation. La documentation Failproof AI couvre l'intégralité de l'API — chaque politique, option et exemple y est inclus. Si vous constatez qu'il manque quelque chose, la source est disponible à l'adresse `https://docs.befailproof.ai/llms-full.txt`. -Pour un contexte ciblé, pointez directement vers une page spécifique : +Pour un contexte ciblé, créez un lien directement vers une page spécifique : ```bash -# Uniquement l'API des custom policies +# Uniquement l'API custom policies npx skills add https://docs.befailproof.ai/custom-policies -# Uniquement les built-in policies +# Uniquement les politiques intégrées npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/fr/getting-started.mdx b/docs/fr/getting-started.mdx index 55052c05..b5ea5095 100644 --- a/docs/fr/getting-started.mdx +++ b/docs/fr/getting-started.mdx @@ -1,6 +1,6 @@ --- title: Démarrage rapide -description: "Installez failproofai, activez les politiques et laissez vos agents s'exécuter de manière fiable" +description: "Installez failproofai, activez les politiques et laissez vos agents s'exécuter de façon fiable" icon: rocket --- @@ -31,15 +31,15 @@ bun add -g failproofai - Les politiques sont des règles qui s'exécutent avant et après chaque appel d'outil d'un agent. Elles interceptent les commandes destructrices, les fuites de secrets et d'autres modes de défaillance avant qu'ils ne causent des dommages. + Les politiques sont des règles qui s'exécutent avant et après chaque appel d'outil de l'agent. Elles interceptent les commandes destructrices, les fuites de secrets et autres modes de défaillance avant qu'ils ne causent des dommages. ```bash failproofai policies --install ``` - Cette commande écrit des entrées de hook dans les CLIs d'agents installés (le `~/.claude/settings.json` de Claude Code, le `~/.codex/hooks.json` d'OpenAI Codex, le `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, le `~/.cursor/hooks.json` de Cursor Agent, le shim de plugin généré par OpenCode dans `~/.config/opencode/plugins/failproofai.mjs` ainsi qu'une entrée d'enregistrement dans le tableau `plugin` de `~/.config/opencode/opencode.json`, le `~/.pi/agent/settings.json` de Pi, le `~/.hermes/config.yaml` de Hermes, le `~/.openclaw/openclaw.json` d'OpenClaw, le `~/.factory/hooks.json` de Factory Droid, le `~/.config/devin/config.json` de Devin CLI, le `~/.gemini/config/hooks.json` d'Antigravity CLI, ou le répertoire de plugins auto-découvert par Goose dans `~/.agents/plugins/failproofai/hooks/hooks.json`). Si plusieurs sont présents, vous serez invité à choisir ; passez `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (n'importe quel sous-ensemble) pour ignorer cette invite. + Cette commande inscrit des entrées de hooks dans vos CLIs d'agents installés (le `~/.claude/settings.json` de Claude Code, le `~/.codex/hooks.json` d'OpenAI Codex, le `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, le `~/.cursor/hooks.json` de Cursor Agent, le shim de plugin généré par OpenCode à `~/.config/opencode/plugins/failproofai.mjs` ainsi qu'une entrée d'enregistrement dans le tableau `plugin` de `~/.config/opencode/opencode.json`, le `~/.pi/agent/settings.json` de Pi, le `~/.hermes/config.yaml` de Hermes, le `~/.openclaw/openclaw.json` d'OpenClaw, le `~/.factory/hooks.json` de Factory Droid, le `~/.config/devin/config.json` de Devin CLI, le `~/.gemini/config/hooks.json` d'Antigravity CLI, ou le répertoire de plugins auto-découvert par Goose à `~/.agents/plugins/failproofai/hooks/hooks.json`). Si plusieurs sont présents, vous serez invité à choisir ; passez `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (tout sous-ensemble) pour ignorer cette invite. - La prise en charge de GitHub Copilot CLI, Cursor Agent, OpenCode et Pi est en **bêta** — installez avec `--cli copilot`, `--cli cursor`, `--cli opencode`, ou `--cli pi`. Hermes (hermes-agent, une passerelle Slack/Telegram) s'installe en portée utilisateur avec `--cli hermes` et est **également** une source d'audit hors ligne. OpenClaw (passerelle openclaw, un assistant multi-canaux auto-hébergé) s'installe en portée utilisateur avec `--cli openclaw` — l'application des règles passe par ses hooks de plugin en cours de processus (`before_agent_finalize` est une vraie barrière de fin de tour, ainsi les fonctions intégrées `require-*-before-stop` sont appliquées) — et est **également** une source d'audit hors ligne. Factory Droid (`droid`) s'installe avec `--cli factory` (portée utilisateur + projet) et est **également** une source d'audit hors ligne. Devin CLI (`devin`, Cognition) s'installe avec `--cli devin` (portée utilisateur + projet) et est **également** une source d'audit hors ligne. Antigravity CLI (`agy`) s'installe avec `--cli antigravity` (portée utilisateur + projet) et est **également** une source d'audit hors ligne. Goose (nom de code goose, Block) s'installe avec `--cli goose` (portée utilisateur + projet) — l'installateur dépose simplement un répertoire de plugin dans `~/.agents/plugins/failproofai/` que Goose auto-découvre, et il est **également** une source d'audit hors ligne. + La prise en charge de GitHub Copilot CLI, Cursor Agent, OpenCode et Pi est en **bêta** — installez avec `--cli copilot`, `--cli cursor`, `--cli opencode` ou `--cli pi`. Hermes (hermes-agent, une passerelle Slack/Telegram) s'installe en portée utilisateur avec `--cli hermes` et est **également** une source d'audit hors ligne. OpenClaw (passerelle openclaw, un assistant multi-canal auto-hébergé) s'installe en portée utilisateur avec `--cli openclaw` — l'application des règles s'effectue via ses hooks de plugin intégrés (`before_agent_finalize` est un véritable verrou de fin de tour, donc les built-ins `require-*-before-stop` sont effectivement appliqués) — et est **également** une source d'audit hors ligne. Factory Droid (`droid`) s'installe avec `--cli factory` (portée utilisateur + projet) et est **également** une source d'audit hors ligne. Devin CLI (`devin`, Cognition) s'installe avec `--cli devin` (portée utilisateur + projet) et est **également** une source d'audit hors ligne. Antigravity CLI (`agy`) s'installe avec `--cli antigravity` (portée utilisateur + projet) et est **également** une source d'audit hors ligne. Goose (nom de code goose, Block) s'installe avec `--cli goose` (portée utilisateur + projet) — l'installateur dépose simplement un répertoire de plugin dans `~/.agents/plugins/failproofai/` que Goose découvre automatiquement, et il est **également** une source d'audit hors ligne. ```bash failproofai policies --install --scope project @@ -69,10 +69,10 @@ bun add -g failproofai failproofai ``` - Ouvre un tableau de bord local à l'adresse `http://localhost:8020` où vous pouvez parcourir les sessions, inspecter les appels d'outils et gérer les politiques. + Ouvre un tableau de bord local à `http://localhost:8020` où vous pouvez parcourir les sessions, inspecter les appels d'outils et gérer les politiques. - - Démarrez Claude Code comme d'habitude. Si l'agent tente quelque chose de risqué, failproofai l'intercepte automatiquement. Laissez-le tourner sans surveillance et consultez ce qui s'est passé dans le tableau de bord. + + Lancez Claude Code comme d'habitude. Si l'agent tente quelque chose de risqué, failproofai l'intercepte automatiquement. Laissez-le tourner sans surveillance et consultez ce qui s'est passé dans le tableau de bord. @@ -88,7 +88,7 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON writes decision to stdout ``` -Chaque politique retourne l'une des trois décisions suivantes : +Chaque politique renvoie l'une des trois décisions suivantes : - **allow** - l'agent continue normalement - **deny** - l'action est bloquée, l'agent est informé de la raison @@ -100,9 +100,9 @@ Les politiques s'exécutent dans votre processus local. Rien n'est envoyé à un --- -## Configurer des politiques d'équipe avec les politiques basées sur les conventions +## Mettre en place des politiques d'équipe avec les politiques basées sur les conventions -La façon la plus rapide d'établir des standards de qualité au sein de votre équipe est la convention `.failproofai/policies/`. Déposez des fichiers de politique dans ce répertoire et ils sont chargés automatiquement — pas d'arguments, pas de modifications de configuration, pas de commandes d'installation. +La façon la plus rapide d'établir des standards de qualité au sein de votre équipe est la convention `.failproofai/policies/`. Déposez des fichiers de politique dans ce répertoire et ils sont chargés automatiquement — pas d'options, pas de modifications de configuration, pas de commandes d'installation. @@ -142,26 +142,28 @@ La façon la plus rapide d'établir des standards de qualité au sein de votre git commit -m "Add team quality policies" ``` - Chaque membre de l'équipe qui a failproofai installé récupère ces politiques automatiquement. Aucune configuration individuelle n'est nécessaire. + Chaque membre de l'équipe qui a failproofai installé récupère automatiquement ces politiques. Aucune configuration individuelle n'est nécessaire. -Validez `.failproofai/policies/` dans votre dépôt afin que toute l'équipe partage les mêmes standards. Au fur et à mesure que votre équipe découvre de nouveaux modes de défaillance, ajoutez des politiques et poussez-les — tout le monde reçoit la mise à jour au prochain `git pull`. Avec le temps, ces politiques deviennent un standard de qualité vivant qui ne cesse de s'améliorer. +Commitez `.failproofai/policies/` dans votre dépôt afin que toute l'équipe partage les mêmes standards. Au fur et à mesure que votre équipe découvre de nouveaux modes de défaillance, ajoutez des politiques et poussez-les — tout le monde reçoit la mise à jour au prochain `git pull`. Avec le temps, ces politiques deviennent un standard de qualité vivant qui ne cesse de s'améliorer. --- ## Stockage des données -Toute la configuration et les journaux restent sur votre machine : +Toutes les configurations et les journaux restent sur votre machine : | Chemin | Contenu | |--------|---------| -| `~/.failproofai/policies/local-policies/policies-config.json` | Configuration globale des politiques | +| `~/.failproofai/policies-config.json` | Configuration globale des politiques | +| `~/.failproofai/policies/` | Vos propres politiques — déposez des fichiers `*-policies.mjs`, aucune configuration requise | +| `~/.failproofai/policies/cloud-policies/` | Politiques déployées sur cette machine par votre organisation | | `~/.failproofai/hook-activity/` | Historique d'exécution des hooks (JSONL paginé) | | `~/.failproofai/logs/` | Journaux de débogage pour les erreurs de hooks personnalisés | -| `.failproofai/policies-config.json` | Configuration par projet (validée) | +| `.failproofai/policies-config.json` | Configuration par projet (validée dans git) | | `.failproofai/policies-config.local.json` | Substitutions personnelles (ignorées par git) | --- @@ -172,11 +174,11 @@ Toute la configuration et les journaux restent sur votre machine : failproofai policies --uninstall ``` -Supprime les entrées de hook de `~/.claude/settings.json`. Les fichiers de configuration dans `~/.failproofai/` sont conservés. +Supprime les entrées de hooks de `~/.claude/settings.json`. Les fichiers de configuration dans `~/.failproofai/` sont conservés. --- -## Étapes suivantes +## Prochaines étapes @@ -192,7 +194,7 @@ Supprime les entrées de hook de `~/.claude/settings.json`. Les fichiers de conf Écrivez vos propres politiques en JavaScript - + Surveillez les sessions et examinez l'activité des politiques diff --git a/docs/fr/introduction.mdx b/docs/fr/introduction.mdx index ce69bd5d..02810af3 100644 --- a/docs/fr/introduction.mdx +++ b/docs/fr/introduction.mdx @@ -1,15 +1,15 @@ --- title: "Failproof AI" -description: "FailproofAI donne aux agents IA 39 politiques de défaillance intégrées qui détectent les boucles, les fuites de secrets, les appels d'outils destructeurs et bien plus encore, en une seule installation." +description: "FailproofAI dote les agents IA de 39 politiques de défaillance intégrées qui détectent les boucles, les fuites de secrets, les appels d'outils destructeurs, et bien plus encore — en une seule installation." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hooks et politiques pour la **gestion des défaillances IA**, la **récupération d'erreurs** et la **fiabilité des LLM**. Gardez vos agents IA fiables et en fonctionnement autonome avec **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** et le **Agents SDK**. +Hooks et politiques pour la **gestion des défaillances IA**, la **récupération d'erreurs** et la **fiabilité des LLM**. Gardez vos agents IA fiables et autonomes avec **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** et l'**Agents SDK**. -Les agents IA échouent de manière prévisible. Ils exécutent des commandes destructrices, laissent fuiter des secrets, dérivent hors de leur périmètre, se retrouvent coincés dans des boucles ou poussent directement sur la branche principale. Sans surveillance, de petites défaillances se transforment en pannes en cascade, en identifiants compromis et en travail perdu. +Les agents IA échouent de manière prévisible. Ils exécutent des commandes destructrices, fuient des secrets, dérivent hors de leur tâche, se retrouvent coincés dans des boucles ou poussent directement sur main. Sans surveillance, de petites défaillances peuvent déclencher des pannes, des identifiants compromis et du travail perdu. -FailproofAI résout ce problème grâce aux **politiques**. Ces règles s'accrochent à chaque appel d'outil de l'agent pour **détecter les défaillances**, **les atténuer** (bloquer, instruire, assainir) et **vous alerter** quand quelque chose nécessite votre attention. Un tableau de bord local vous permet de revoir chaque appel d'outil, chaque défaillance d'agent et chaque action de récupération après coup. +FailproofAI résout ce problème grâce aux **politiques**. Ces règles s'accrochent à chaque appel d'outil de l'agent pour **détecter les défaillances**, **les atténuer** (bloquer, instruire, assainir) et **vous alerter** lorsque quelque chose nécessite votre attention. Un tableau de bord local vous permet d'examiner ultérieurement chaque appel d'outil, chaque défaillance d'agent et chaque action de récupération. Les transcriptions et l'évaluation des politiques restent sur votre machine. Les données ne sont envoyées que lorsque vous utilisez explicitement une fonctionnalité en ligne, comme les rappels d'audit authentifiés ou les invitations. @@ -18,19 +18,19 @@ Les transcriptions et l'évaluation des politiques restent sur votre machine. Le - Bloquez les commandes destructrices, empêchez les fuites de secrets, maintenez les agents dans les limites du projet, et bien plus encore. Tout est disponible dès l'installation. + Bloquez les commandes destructrices, empêchez les fuites de secrets, maintenez les agents dans les limites du projet, et bien plus encore. Tout est prêt à l'emploi. - Rédigez vos propres règles en JavaScript avec une API simple allow / deny / instruct. + Écrivez vos propres règles en JavaScript avec une API simple allow / deny / instruct. - Voyez ce que vos agents ont fait pendant votre absence. Parcourez les sessions, inspectez les appels d'outils, examinez où les politiques se sont déclenchées. + Voyez ce que vos agents ont fait pendant votre absence. Parcourez les sessions, inspectez les appels d'outils, vérifiez où les politiques ont été déclenchées. - Ajustez n'importe quelle politique sans écrire de code. Définissez des listes autorisées, des branches protégées ou des seuils par projet ou globalement. + Ajustez n'importe quelle politique sans écrire de code. Définissez des listes d'autorisation, des branches protégées ou des seuils par projet ou globalement. @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -Consultez le guide [Premiers pas](/fr/getting-started) pour le parcours complet. \ No newline at end of file +Consultez le guide [Premiers pas](/fr/getting-started) pour une présentation complète. \ No newline at end of file diff --git a/docs/fr/package-aliases.mdx b/docs/fr/package-aliases.mdx index 9d142b2b..a85a6f92 100644 --- a/docs/fr/package-aliases.mdx +++ b/docs/fr/package-aliases.mdx @@ -10,32 +10,32 @@ Le package npm canonique est **`failproofai`** : ```bash npm install -g failproofai -# ou +# or bun add -g failproofai ``` --- -## Pourquoi nous détenons les noms d'alias +## Pourquoi nous détenons ces alias -Le typosquatting est une attaque courante sur la chaîne d'approvisionnement logicielle : un acteur malveillant enregistre un nom de package à une touche de distance d'un package populaire. Les utilisateurs qui font une faute de frappe lors de la commande d'installation se retrouvent à exécuter du code contrôlé par l'attaquant avec un accès total au système — précisément le type de menace que Failproof AI est conçu pour contrer. +Le typosquatting est une attaque courante sur la chaîne d'approvisionnement logicielle : un acteur malveillant enregistre un nom de package à une touche près d'un package populaire. Les utilisateurs qui font une faute de frappe lors de la commande d'installation se retrouvent à exécuter du code contrôlé par l'attaquant avec un accès total au système — exactement le type de menace que Failproof AI est conçu à contrer. -Pour éliminer cette surface d'attaque, **nous détenons de manière préventive toutes les fautes d'orthographe courantes et variantes de mise en forme** de `failproofai` sur npm. Aucun de ces noms ne peut être enregistré par un tiers. Chacun est un proxy léger qui installe et délègue au vrai package `failproofai`. +Pour éliminer cette surface d'attaque, **nous détenons de manière préventive toutes les fautes d'orthographe courantes et variantes de formatage** de `failproofai` sur npm. Aucun de ces noms ne peut être enregistré par un tiers. Chacun est un proxy léger qui installe et délègue au vrai package `failproofai`. --- ## Alias enregistrés -**Variantes de mise en forme** — différentes façons d'écrire « failproof ai » : +**Variantes de formatage** — différentes façons d'écrire « failproof ai » : | Package | Statut | |---------|--------| | `failproof` | ✅ Publié | -| `failproof-ai` | ⏳ En attente de validation npm | -| `fail-proof-ai` | ⏳ En attente de validation npm | -| `failproof_ai` | ⏳ En attente de validation npm | -| `fail_proof_ai` | ⏳ En attente de validation npm | -| `fail-proofai` | ⏳ En attente de validation npm | +| `failproof-ai` | ⏳ En attente d'approbation npm | +| `fail-proof-ai` | ⏳ En attente d'approbation npm | +| `failproof_ai` | ⏳ En attente d'approbation npm | +| `fail_proof_ai` | ⏳ En attente d'approbation npm | +| `fail-proofai` | ⏳ En attente d'approbation npm | **Fautes de frappe `failprof*`** — un `o` manquant dans « proof » : @@ -43,25 +43,25 @@ Pour éliminer cette surface d'attaque, **nous détenons de manière préventive |---------|--------| | `failprof` | ✅ Publié | | `failprof-ai` | ✅ Publié | -| `failprofai` | ⏳ En attente de validation npm | -| `fail-prof-ai` | ⏳ En attente de validation npm | -| `failprof_ai` | ⏳ En attente de validation npm | +| `failprofai` | ⏳ En attente d'approbation npm | +| `fail-prof-ai` | ⏳ En attente d'approbation npm | +| `failprof_ai` | ⏳ En attente d'approbation npm | -**Fautes de frappe `faliproof*`** — `a` et `i` inversés : +**Fautes de frappe `faliproof*`** — inversion du `a` et du `i` : | Package | Statut | |---------|--------| | `faliproof` | ✅ Publié | | `faliproof-ai` | ✅ Publié | -| `faliproofai` | ⏳ En attente de validation npm | +| `faliproofai` | ⏳ En attente d'approbation npm | -> **Pourquoi « en attente » ?** La politique anti-spam de npm bloque les noms qui, après suppression de la ponctuation et vérification de similarité, se normalisent vers la même chaîne qu'un package existant. Nous avons contacté le support npm pour réserver ces noms à des fins de protection contre le typosquatting. Ils seront activés une fois approuvés. +> **Pourquoi « en attente » ?** La politique anti-spam de npm bloque les noms qui se normalisent en la même chaîne qu'un package existant après suppression de la ponctuation et application de vérifications de similarité. Nous avons contacté le support npm pour réserver ces noms à des fins de protection contre le squatting. Ils seront activés une fois approuvés. Vous pouvez vérifier que tout alias publié nous appartient : ```bash npm info failproof -# Cherchez : "ExosphereHost Inc." dans le champ maintainers +# Look for: "ExosphereHost Inc." in the maintainers field ``` --- @@ -70,10 +70,10 @@ npm info failproof Chaque package alias : -1. Liste `failproofai` comme dépendance — ainsi le vrai package est installé et son binaire devient disponible -2. Expose un binaire portant son propre nom (ex. `failprof-ai`) qui transmet tous les arguments au binaire `failproofai` +1. Déclare `failproofai` comme dépendance — ainsi le vrai package est installé et son binaire devient disponible +2. Expose un binaire portant son propre nom (par exemple `failprof-ai`) qui transmet tous les arguments au binaire `failproofai` -Le proxy est un script Node de deux lignes ; il ne contient aucune logique, aucun appel réseau et ne collecte aucune donnée au-delà de ce que fait `failproofai` lui-même. +Le proxy est un script Node de deux lignes ; il ne contient aucune logique, n'effectue aucun appel réseau et ne collecte aucune donnée au-delà de ce que `failproofai` lui-même effectue. --- diff --git a/docs/fr/testing.mdx b/docs/fr/testing.mdx index b6d9489b..9072953b 100644 --- a/docs/fr/testing.mdx +++ b/docs/fr/testing.mdx @@ -4,11 +4,11 @@ description: "Tests unitaires, tests E2E et utilitaires de test" icon: flask-vial --- -failproofai dispose de deux suites de tests : les **tests unitaires** (rapides, avec mocks) et les **tests end-to-end** (invocations réelles de sous-processus). +failproofai dispose de deux suites de tests : les **tests unitaires** (rapides, avec mocks) et les **tests de bout en bout** (invocations réelles de sous-processus). --- -## Exécution des tests +## Exécuter les tests ```bash # Lancer tous les tests unitaires une fois @@ -17,7 +17,7 @@ bun run test:run # Lancer les tests unitaires en mode watch bun run test -# Lancer les tests E2E (nécessite une configuration préalable - voir ci-dessous) +# Lancer les tests E2E (nécessite une configuration - voir ci-dessous) bun run test:e2e # Vérification des types sans compilation @@ -37,9 +37,9 @@ Les tests unitaires se trouvent dans `__tests__/` et utilisent [Vitest](https:// __tests__/ hooks/ builtin-policies.test.ts # Logique des politiques pour chaque builtin - hooks-config.test.ts # Chargement de la config et fusion des scopes + hooks-config.test.ts # Chargement de la configuration et fusion des scopes policy-evaluator.test.ts # Injection de paramètres et ordre d'évaluation - custom-hooks-registry.test.ts # globalThis registry add/get/clear + custom-hooks-registry.test.ts # Registre globalThis : add/get/clear custom-hooks-loader.test.ts # Chargeur ESM, imports transitifs, gestion des erreurs manager.test.ts # Opérations install/remove/list components/ @@ -108,9 +108,9 @@ describe("block-sudo", () => { --- -## Tests end-to-end +## Tests de bout en bout -Les tests E2E invoquent le vrai binaire `failproofai` en tant que sous-processus, lui envoient un payload JSON via stdin et vérifient le résultat sur stdout ainsi que le code de sortie. Cela teste le chemin d'intégration complet utilisé par Claude Code. +Les tests E2E invoquent le vrai binaire `failproofai` en tant que sous-processus, lui transmettent un payload JSON via stdin et vérifient la sortie stdout ainsi que le code de sortie. Cela teste le chemin d'intégration complet utilisé par Claude Code. ### Configuration @@ -126,33 +126,33 @@ Puis lancez les tests : bun run test:e2e ``` -Recompilez `dist/` à chaque fois que vous modifiez l'API publique des hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` ou `src/hooks/policy-types.ts`). +Recompilez `dist/` à chaque modification de l'API publique des hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` ou `src/hooks/policy-types.ts`). ### Structure des tests E2E ```text __tests__/e2e/ helpers/ - hook-runner.ts # Lance le binaire, envoie le payload JSON, capture le code de sortie + stdout + stderr - fixture-env.ts # Répertoires temporaires isolés par test avec fichiers de config - payloads.ts # Factories de payloads conformes à Claude pour chaque type d'événement + hook-runner.ts # Lance le binaire, transmet le JSON du payload, capture le code de sortie + stdout + stderr + fixture-env.ts # Répertoires temporaires isolés par test avec fichiers de configuration + payloads.ts # Factories de payloads fidèles à Claude pour chaque type d'événement hooks/ builtin-policies.e2e.test.ts # Chaque politique builtin avec un vrai sous-processus custom-hooks.e2e.test.ts # Chargement et évaluation des hooks personnalisés - config-scopes.e2e.test.ts # Fusion de config entre les scopes project/local/global + config-scopes.e2e.test.ts # Fusion de configuration sur les scopes project/local/global policy-params.e2e.test.ts # Injection de paramètres pour chaque politique paramétrée ``` -### Utilisation des utilitaires E2E +### Utiliser les utilitaires E2E -**`FixtureEnv`** - environnement isolé par test : +**`FixtureEnv`** — environnement isolé par test : ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - répertoire temporaire ; à passer en payload.cwd pour charger .failproofai/policies-config.json -// env.home - home isolé ; évite toute fuite depuis le vrai ~/.failproofai +// env.cwd - répertoire temporaire ; à passer comme payload.cwd pour récupérer .failproofai/policies-config.json +// env.home - répertoire home isolé ; aucune fuite depuis le vrai ~/.failproofai env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -164,7 +164,7 @@ env.writeConfig({ `createFixtureEnv()` enregistre automatiquement le nettoyage via `afterEach`. -**`runHook`** - invoquer le binaire : +**`runHook`** — invoquer le binaire : ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - factories de payloads prêts à l'emploi : +**`Payloads`** — factories de payloads prêts à l'emploi : ```typescript Payloads.preToolUse.bash(command, cwd) @@ -245,9 +245,9 @@ describe("block-rm-rf (E2E)", () => { Les tests E2E utilisent `vitest.config.e2e.mts` avec : -- `environment: "node"` - pas de globals navigateur requis -- `pool: "forks"` - isolation réelle des processus (les tests lancent des sous-processus) -- `testTimeout: 20_000` - 20 s par test (démarrage du binaire + évaluation du hook) +- `environment: "node"` — aucune variable globale navigateur requise +- `pool: "forks"` — isolation réelle des processus (les tests lancent des sous-processus) +- `testTimeout: 20_000` — 20 s par test (démarrage du binaire + évaluation du hook) Le pool `forks` est important : les workers basés sur des threads partagent `globalThis`, ce qui peut interférer avec les tests qui lancent des sous-processus. Les forks basés sur des processus évitent ce problème. @@ -255,6 +255,6 @@ Le pool `forks` est important : les workers basés sur des threads partagent `gl ## CI -L'exécution complète de la CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) doit passer avant toute fusion. La suite E2E s'exécute en parallèle dans un job CI séparé. +L'exécution complète de la CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) doit réussir avant toute fusion. La suite E2E s'exécute en tant que job CI distinct, en parallèle. Consultez [Contributing](../CONTRIBUTING.md) pour la liste de vérification complète avant fusion. \ No newline at end of file diff --git a/docs/he/agenteye/alerts.mdx b/docs/he/agenteye/alerts.mdx index 7fa63cd2..32e7e9ed 100644 --- a/docs/he/agenteye/alerts.mdx +++ b/docs/he/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "התראות" -description: "גלה ברגע שמשהו חוצה את הגבול שלך, בערוץ שהצוות שלך כבר צופה בו, במקום לשמוע על זה מלקוח." +description: "גלו ברגע שמשהו חוצה את הגבול שלכם, בערוץ שהצוות שלכם כבר צופה בו, במקום לשמוע על זה מלקוח." --- -גלה ברגע שמשהו חוצה את הגבול שלך, בערוץ שהצוות שלך כבר צופה בו, במקום לשמוע על זה מלקוח. הגדר כלל פעם אחת ו-Failproof AI Observability בודק אותו לפי לוח זמנים, ואז שולח לך התראה בדוא"ל, Slack, webhook, או ישירות בלוח הבקרה. +גלו ברגע שמשהו חוצה את הגבול שלכם, בערוץ שהצוות שלכם כבר צופה בו, במקום לשמוע על זה מלקוח. הגדירו כלל פעם אחת וFailproof AI Observability בודקת אותו לפי לוח זמנים, ואז תשדר לכם בדוא"ל, Slack, webhook, או ישירות בדאשבורד. -![עמוד ההתראות: רשת של כרטיסי כללי התראה, כל אחד מציג את ההגדרה שלו, חלון ההערכה, ערוצים, ותג חומרה של מידע, אזהרה או קריטי](/agenteye/images/alerts.png) -*כל כלל התראה בהצצה: מה הוא מוקד, בכמה תדירות, לאן זה שולח התראות, ועד כמה זה דחוף.* +![דף התראות: רשת של כרטיסי כללי התראות, כל אחד מראה את ההדלקה שלו, חלון הערכה, ערוצים, ותג חומרה של מידע, אזהרה או קריטי](/agenteye/images/alerts.png) +*כל כלל התראה במבט ברור: מה הוא עוקב, כמה בתדירות, לאן הוא משדר, ועד כמה זה דחוף.* -## קבל ידיעה על בעיות לפני המשתמשים שלך +## שמעו על בעיות לפני שהמשתמשים שלכם יודעים על כך -הפסק להחדש את לוח הבקרה בתקווה לתפוס רגרסיה. השתמש בהתראה בכל פעם שיש אות שתרצה לשמוע עליה גם כשאף אחד לא מביט, והנח אותה במקום שבו אתה כבר נמצא: +הפסיקו רענון דאשבורד בתקווה לתפוס רגרסיה. היעזרו בהתראה בכל פעם שיש אות שתרצו לשמוע עליה גם כשאף אחד לא מסתכל, והנחו אותה להגיע לשם שבו אתם כבר נמצאים: -- **דוא"ל**, למי שצריך לדעת. -- **Slack**, הודעה עשירה עם כפתור שקופץ ישר לתקרית. -- **Webhook**, JSON POST ל-PagerDuty, Opsgenie, או לנקודת הקצה שלך, עם חתימה אופציונלית כדי שהמקבל יוכל לסמוך עליה. -- **בלוח הבקרה**, שקט בעיצוב, כשאתה מכוונן כלל ולא רוצה עדיין להתריע לאיש. +- **דוא"ל**, לכל מי שצריך לדעת. +- **Slack**, הודעה עשירה עם כפתור שקופץ ישירות לתקרית. +- **Webhook**, פוסט JSON ל-PagerDuty, Opsgenie, או לנקודת קצה משלכם, עם חתימה אופציונלית כך שהמקלט יכול להאמין לה. +- **בתוך הדאשבורד**, שקט בעיצובו, למקרים בהם אתם כוללים כלל ולא רוצים לשדר לאף אחד עדיין. -צרף כל שילוב לכלל יחיד, וחומרתו (מידע, אזהרה או קריטי) נשארת עם זה כדי שהחשוב נראה חשוב. +צרפו כל שילוב לכלל יחיד, וחומרתו (מידע, אזהרה או קריטי) מלווה אותו כך שהמסעיפים הדחופים נראים דחופים. -## בנה את הכלל בטופס, לא ב-JSON +## בנו את הכלל בטופס, לא ב-JSON -אתה מתאר מה "שבור" אומר בטופס, ו-Failproof AI Observability כותב את הכלל הבסיסי בשבילך. מפרט ה-JSON הוא רק מה שהטופס הזה מייצר בעמקי המערכת, כך שאתה יכול לקרוא אותו כדי להבין כלל אבל בדרך כלל לא תקליד אותו. +אתם מתארים מה פירושו "שבור" בטופס, וFailproof AI Observability כותבת את הכלל הבסיסי בשבילכם. מפרט ה-JSON הוא רק מה שהטופס מייצר מתחת למכסה המנוע, כך שתוכלו לקרוא אותו כדי להבין כלל אך לעתים רחוקות תקלידו אותו. -![טופס ההתראה החדשה: שם ותיאור, כפתור הפעלה, ובוררי הגדרה המציעים סף מטרי, SQL מותאם אישית, ציון הערכה, eval מורכב, ותנאים לכל אירוע](/agenteye/images/alert-new.png) -*בחר הגדרה והטופס מחליף לשדות הנכונים; שמור כותב את הכלל.* +![טופס ההתראה החדשה: שם ותיאור, מתג זמין, ובורר הדלקה המציע סף מטרי, SQL מותאם אישית, ציון הערכה, הערכה מורכבת, ותנאים לכל אירוע](/agenteye/images/alert-new.png) +*בחרו הדלקה והטופס מחליף את השדות הנכונים; שמור כותב את הכלל.* -הנתיב הטוב הוא מהיר: תן לו שם, בחר **הגדרה** (מה לצפות בו), קבע **סף וחלון** (כמה רע, על פני כמה זמן), צרף לפחות ערוץ **אחד**, ואז **שמור** ולחץ על **בדיקה** כדי לשלוח התראה סינתטית ולאשר שכל יעד חוברה. בעמקי המערכת זה יוצר spec קטן כמו: +הנתיב המאושר הוא מהיר: תנו לו שם, בחרו **הדלקה** (מה לעקוב), קבעו **סף וחלון** (כמה רע, על פני כמה זמן), צרפו לפחות ערוץ **אחד**, ואז **שמור** והקישו **בדיקה** כדי להפעיל הודעה סינתטית ולאשר שכל יעד קשור כראוי. מתחת למכסה המנוע זה מייצר ספק קטן כמו: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -אתה לא מוגבל לסוג אות אחד. בחר בהגדרה שמתאימה לאופן שבו אתה חושב על הכשל: +אתם לא מוגבלים לסוג אות אחד. בחרו בהדלקה שמתאימה לאופן שבו אתם חושבים על התקלה: -| הגדרה | משדרת כאשר | +| הדלקה | מופעלת כאשר | |---|---| -| **סף מטרי** | מטרי קבוע מראש (שיעור שגיאה, p95 או p99 latency, ספירות אירוע או שגיאה, הוצאות token) חוצה את הגבול שלך על פני חלון | -| **SQL מותאם אישית** | השאילתה קריאה בלבד שלך מחזירה שורה, או ערך שהיא מחשבת חוצה סף | -| **ציון הערכה** | ממוצע ציון מעריך (נניח, hallucination) חוצה סף | -| **Eval מורכב** | מספר בדיקות ציון משולבות עם any, all, או at-least-N logic, כדי לתפוס רגרסיה שמופיעה רק על פני ציונים | -| **לכל אירוע** | אירוע תואם יחיד נוחת: agent ספציפי, סוג שגיאה ספציפי, או substring הודעה | +| **סף מטרי** | מטרי קבוע מראש (שיעור שגיאה, p95 או p99 latency, ספירת אירוע או שגיאה, הוצאת טוקן) חוצה את הגבול שלכם על פני חלון | +| **SQL מותאם אישית** | השאילתה שלכם שרק לקריאה מחזירה שורה, או ערך שהיא מחשבת חוצה סף | +| **ציון הערכה** | ממוצע ציון מעריך (נניח, הלוצינציה) חוצה סף | +| **הערכה מורכבת** | מספר בדיקות ציון משתלבות עם כל אחת, הכל, או לפחות-N לוגיקה, כדי לתפוס רגרסיה שמופיעה רק על פני ציונים | +| **לכל אירוע** | אירוע תואם יחיד מגיע: סוכן ספציפי, סוג שגיאה ספציפי, או תת-מחרוזת הודעה | -כבר בעיניים על כשל בעמוד ה-[Errors](/he/agenteye/error-tracking)? כל שורה שם יש לה כפתור **+ alert** שפותח את אותו טופס עם מילוי מראש כדי לתפוס את הכשל המדויק הזה שוב, כך שהתקרית שזה עתה טיפלת בה הופכת לאחד שישדר לך בפעם הבאה. +כבר מסתכלים על תקלה בדף [Errors](/he/agenteye/error-tracking)? כל שורה שם יש כפתור **+ alert** שפותח את הטופס הזה עם מילוי מקדים כדי לתפוס את התקלה המדויקת הזו שוב, כך שהתקרית שזה עתה קיימתם הופכת לזו שמשדרת לכם בפעם הבאה. -**איפה למצוא אותו:** התראות נמצאות ב-`//alerts`. יצירה, עריכה, מחיקה, ובדיקת כללים דורשים **`alerts:write`**; `alerts:read` מספיק להסתכלות. בוררי הנמענה מפרטים את חברי הארגון שלך בשם, כך שתוכל להתריע לאדם מבלי להשאיר את הטופס. +**איפה למצוא אותה:** התראות חיות ב-`//alerts`. יצירה, עריכה, מחיקה, וכללי בדיקה צריכים **`alerts:write`**; `alerts:read` מספיק כדי להסתכל. בורר הנמענה מפרט את חברי הארגון שלכם לפי שם, כך שתוכלו לשדר אדם מבלי להשאיר את הטופס. -## התריע אותי רק כשזה אמיתי +## שדר אותי רק כשזה אמיתי -מדידה רעה אחת לא צריכה להעיר אותך. מסנן הרעש **M של N** שולט בכמה מהבדיקות האחרונות החייבות להיכשל לפני שההתראה בעצם משדרת אותך. קבע אותו ל-**3 מ-5** והכלל משדר רק לאחר שהוא חרג שלוש מחמש הבדיקות האחרונות שלו, כך שאות רועד מפסיק לבכות לזئב; השאר את ברירת המחדל **1 מ-1** כדי להשדר על החרגה הראשונה. אתה גם בוחר כמה לעתים קרובות הכלל פועל, מערכות הגדרות של 1m, 5m, 15m, ו-1h, תואמות לאופן שהאות באמת זז. +מדידה אחת רעה לא צריכה להעיר אתכם. **M של N** מסנן הרעש שולט כמה מהבדיקות האחרונות חייבות להיכשל לפני שההתראה בעצם משדרת לכם. הגדר זאת ל-**3 של 5** והכלל מופעל רק אחרי שהוא חרג שלוש מהבדיקות האחרונות שלו חמש, כך שאות רועד מפסיק לבכות זאב; השאר בברירת המחדל **1 של 1** כדי להפעיל על ההפרה הראשונה. אתם גם בוחרים כמה בתדירות הכלל פועל, מברירות מוגדרות מראש של 1m, 5m, 15m, ו-1h, התאם לאופן שבו האות באמת נע. -## מה קורה כשהתראה משדרת +## מה קורה כאשר התראה מופעלת -הפרה פותחת **תקרית** ומשדרת את הערוצים שלך פעם אחת. משם הצוות שלך מכיר בה, מקצה בעלים, דן בה, ופותר אותה, הכל מול רקורד נקי ומיוחסו. לזרימת העבודה של טריאז 'הזו יש בית משלו: ראה [Incidents](/he/agenteye/incidents). +הפרה פותחת **תקרית** ומשדרת את הערוצים שלכם פעם אחת. משם הצוות שלכם מאשר אותה, מקצה בעלים, מדברים זאת, ופתרים אותה, הכל מול רקע ברור ומיוחס. לזרימת העבודה הטריאז הזו יש ביתה משלה: ראה [Incidents](/he/agenteye/incidents). ## קשור -- [Incidents](/he/agenteye/incidents): עקוב אחר התראה משדרת מפתח לממומנע לנפתר. -- [Error tracking](/he/agenteye/error-tracking): קבץ כשלי agent והעלה אחד להתראה בלחיצה. -- [Dashboards](/he/agenteye/dashboards): צפה בלוחות המשותפים שהספים שאתה משדר עליהם מגיעים מהם. -- [CLI and agents](/he/agenteye/cli-and-agents): צור התראות וack תקריות מהטרמינל שלך, או script אותן ל-CI. \ No newline at end of file +- [Incidents](/he/agenteye/incidents): עקוב אחרי התראה מתפוצצת מפתוח ל-acknowledged ל-resolved. +- [Error tracking](/he/agenteye/error-tracking): קבץ כשלים של סוכן ותקדם אחד להתראה בקליק. +- [Dashboards](/he/agenteye/dashboards): צפו בלוחות המשותפים שהספים שאתם משדרים עליהם מגיעים מהם. +- [CLI and agents](/he/agenteye/cli-and-agents): צרו התראות וודא אירועים מהטרמינל שלכם, או תסקרטו אותם לתוך CI. \ No newline at end of file diff --git a/docs/he/agenteye/api-keys.mdx b/docs/he/agenteye/api-keys.mdx index 3326c725..f07727e6 100644 --- a/docs/he/agenteye/api-keys.mdx +++ b/docs/he/agenteye/api-keys.mdx @@ -1,172 +1,172 @@ --- title: "מפתחות API" -description: "מפתחות API שולטים על מי ומה יכול להגיע לשרת Failproof AI Observability שלך, כך שקולקטור יכול לשלוח אירועים מבלי להשיג אי פעם הרשאות קריאה או admin." +description: "מפתחות API שולטים בגישה לשרת Failproof AI Observability שלך, כך שקולט יכול לשלוח אירועים ללא זכויות קריאה או ניהול. כל מפתח נושא הרשאה אחת או יותר, וכל הרשאה שומרת על מסלולי שרת ספציפיים; אתה מעניק רק את מה שהעבודה צריכה." --- -מפתחות API שולטים על מי ומה יכול להגיע לשרת Failproof AI Observability שלך, כך שקולקטור יכול לשלוח אירועים מבלי להשיג אי פעם הרשאות קריאה או admin. כל מפתח נושא הרשאה אחת או יותר, וכל הרשאה שולטת במסלולי שרת ספציפיים; אתה מעניק רק את אלה שעבודה זקוקה להם. רוב ההפעלות יוצרות רק שלוש סוגי מפתחות. +מפתחות API שולטים בגישה לשרת Failproof AI Observability שלך, כך שקולט יכול לשלוח אירועים ללא זכויות קריאה או ניהול. כל מפתח נושא הרשאה אחת או יותר, וכל הרשאה שומרת על מסלולי שרת ספציפיים; אתה מעניק רק את מה שהעבודה צריכה. רוב ההפצות יוצרות שלושה סוגי מפתח בלבד. -## 3 המפתחות שרוב ההפעלות צריכות +## 3 המפתחות שרוב ההפצות צריכות | מפתח | הרשאות | מי משתמש בו | |---|---|---| -| מפתח קולקטור | `events:add` | ה-`agenteye-collector` על כל מכונת אג'נט, כדי לשלוח אירועים. | -| מפתח קריאה Dashboard | `events:read`, `keys:read` | אופרטור קריאה בלבד או אינטגרציה החוקרת נתונים מבלי לשנות אותם. | -| מפתח admin Bootstrap | כל ההרשאות | האופרטור שמעלה את ההופעה לראשונה (ו-Dashboard). זרוע מתוך משתנה הסביבה `ADMIN_KEY`. ראה [מפתח admin Bootstrap](#bootstrap-admin-key). | +| מפתח קולט | `events:add` | `agenteye-collector` על כל מכונת agent, כדי לשלוח אירועים. | +| מפתח קריאה לדוח | `events:read`, `keys:read` | אופרטור לקריאה בלבד או אינטגרציה המבצעת שאילתות נתונים ללא שינויים. | +| מפתח bootstrap ניהול | כל ההרשאות | האופרטור שמעלה את המופע לראשונה (ואת הדוח). מזורע מתוך משתנה הסביבה `ADMIN_KEY`. ראה [מפתח bootstrap ניהול](#bootstrap-admin-key). | -התחל כאן. פנה לקטלוג ההרשאה המלא למטה רק כשאתה צריך מפתח בהיקף מותאם וצר יותר. ראה גם [פריסת מפתחות מומלצת](#recommended-key-layout) ו[יצירת מפתחות](#creating-keys). +התחל כאן. פנה לקטלוג ההרשאות המלא למטה רק כשאתה צריך מפתח בהיקף צר וממותאם. ראה גם [פריסת מפתח מומלצת](#recommended-key-layout) ו[יצירת מפתחות](#creating-keys). --- ## הרשאות -השרת אוכף קטלוג קבוע של הרשאות; כל אחת שולטת במסלולי HTTP ספציפיים. **מפתח admin** מחזיק בכל אחת מהן; מפתח בהיקף מחזיק בתת-הקבוצה שאתה מעניק ביצירה. מחרוזות הרשאה לא ידועות נדחות כאשר מפתח נוצר. +השרת אוכף קטלוג קבוע של הרשאות; כל אחת שומרת על מסלולי HTTP ספציפיים. **מפתח ניהול** מחזיק בכולם; מפתח בהיקף מחזיק בתת-הקבוצה שאתה מעניק בעת היצירה. מחרוזות הרשאה לא ידועות נדחות בעת יצירת מפתח. -> **הערה:** שתי הרשאות תקפות הן dashboard-only בלבד ולא יכולות להיות ממנויות למפתח API: `orgs:admin` (ניהול instance, שהוא רק לאופרטור) ו`keys:update`. בקשה ל-`POST /keys` או `PATCH /keys/:id` שמנסה להעניק אחת מהן נדחית ב-HTTP 422. ראה את שורת `keys:update` למטה כדי להבין למה מפתח bearer עשוי ליצור מפתחות אך אף פעם לא לערוך אותם. +> **הערה:** שתי הרשאות תקפות הן לשימוש אדם/דוח בלבד ולא ניתן להעניק אותן למפתח API: `orgs:admin` (ניהול מופע, שהוא לאופרטורים בלבד) ו`keys:update`. בקשה ל`POST /keys` או `PATCH /keys/:id` שמנסה להעניק אחד מהם נדחית ב-HTTP 422. ראה את השורה `keys:update` למטה כדי להבין מדוע מפתח bearer עשוי ליצור מפתחות אך לעולם לא לערוך אותם. -### הנגשת אירועים וחקירה +### הנתעה וחקירת אירועים | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `events:add` | `POST /events` | הנגשת אצווות של אירועים מקולקטור. ההרשאה היחידה שקולקטור צריך. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | חקירת אירועים, רשימת הסביבות הידועות, רשימת מזהי המודלים שנראו בנתונים (בשימוש בתצוגת Models ובמסננים של מודלים), חישוב ההיקף latency המניע את heat-map / percentile band, וייצוא session כ-JSONL. נקודות קצה של facet של סרגל ההסנן המשותף `GET /events/environments` ו`GET /events/agent_ids` ניתנות להשגה ב-**או** `events:read` **או** `evaluations:read`, כך שעמוד ה-sessions (gated `evaluations:read`) משתמש ב-facet per-org זהה. `GET /events/models` אינו אחד מהם: הוא דורש `events:read`, כך שעקרון שמחזיק רק ב-`evaluations:read` מקבל 403 ממנו. | +| `events:add` | `POST /events` | הנתעה של אצוות אירועים מקולט. ההרשאה היחידה שקולט צריך. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | חקירה של אירועים, רשימה של הסביבות הידועות, רשימה של מזהי מודל שנראו בנתונים (בשימוש בתצוגת Models ובמסננים מודל), חישוב הצבירה של latency שמעניקה את מפת החום / רצועת percentile, וייצוא סשן כ-JSONL. נקודות קצה של facet בסרגל הסנן המשותף `GET /events/environments` ו`GET /events/agent_ids` נגישות עם **או** `events:read` **או** `evaluations:read`, כך שעמוד הסשנים (מגודר `evaluations:read`) משתמש בנקודות הקצה per-org זהות. `GET /events/models` אינה אחת מהן: זה דורש `events:read`, כך שעיקרון המחזיק רק ב`evaluations:read` מקבל 403 ממנה. | -### Sessions והערכות +### סשנים והערכות | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | רשימת sessions, קריאת תוצאות הערכה, בריאות eval מגוללת בשימוש ב-dashboards, וחווקרת ה-evaluation-job worker. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | ערוך ידנית re-evaluation לסשן שהסתיים. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | רשימה של סשנים, קריאה של תוצאות הערכה, בריאות ההערכה המצטברת בשימוש בדוחות, ומצב תור העובדים של משימות ההערכה. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | הנקה ידנית של הערכה חוזרת לסשן שהסתיים. | -### Dashboards +### דוחות | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | רשימת dashboards, טעינת אחד, וקריאת הplates שלו. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | יצירה ועריכת dashboards, הוספה / עריכה / הסרת tiles, והסדרה מחדש של grid ה-tile. | -| `dashboards:delete` | `DELETE /dashboards/:id` | מחק dashboard שלם (מחיקה ברמת tile חיה תחת `dashboards:write`). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | רשימה של דוחות, טעינה של אחד, וקריאה של הרעפים שלו. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | יצירה ועריכה של דוחות, הוספה / עריכה / הסרת רעפים, וסדור מחדש של רשת הרעפים. | +| `dashboards:delete` | `DELETE /dashboards/:id` | מחיקה של דוח שלם (מחיקה ברמת רעף נמצאת תחת `dashboards:write`). | ### שאילתות שמורות (SQL composer) | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | רשימת שאילתות שמורות, טעינת אחת, וביקורת הסכימה read-only שה-composer מכוון אליה. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | יצירה ועריכת שאילתות שמורות. SQL עדיין מנוהל דרך אותו role read-only בדיוק ובדיקות SQL שמורות כמו קריאה `queries:run`. | -| `queries:delete` | `DELETE /queries/:id` | מחק שאילתה שמורה. | -| `queries:run` | `POST /queries/run` | בצע SQL שמור או ad-hoc נגד ה-role read-only בשימוש ה-composer. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | רשימה של שאילתות שמורות, טעינה של אחת, ובדיקה של סכימת הקריאה בלבד שה-composer מכוון אליה. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | יצירה ועריכה של שאילתות שמורות. SQL עדיין מנותב דרך אותו תפקיד קריאה בלבד ובדיקות SQL מוגנות כמו בקריאת `queries:run`. | +| `queries:delete` | `DELETE /queries/:id` | מחיקה של שאילתה שמורה. | +| `queries:run` | `POST /queries/run` | ביצוע של SQL שמור או ad-hoc כנגד התפקיד קריאה בלבד בשימוש ב-composer. | -### AI assistant +### עוזר AI | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | דוברה עם ה-AI assistant וניהול שלך שלך (private) שיחות. נדרש ב-**user** כדי לראות את ה-assistant dock; המפתח שלו עצמו של ה-assistant הוא `dashboard-assistant` וזריעה נפרדת (ראה למטה). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | שיחה עם עוזר ה-AI וניהול שיחות משלך (פרטיות). נדרש ב**משתמש** כדי לראות את הנמל של העוזר; מפתח העוזר עצמו הוא `dashboard-assistant` ומזורע בנפרד (ראה למטה). | ### מפתחות API | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `keys:create` | `POST /keys` | צור מפתח API בהיקף חדש. **אינו** מעניק עריכת הרשאות של מפתח קיים (זה `keys:update`). | -| `keys:read` | `GET /keys` | רשימת מפתחות קיימים. סודות לעולם לא מוחזרים על ידי נקודת קצה זו. | -| `keys:update` | `PATCH /keys/:id` | ערוך הרשאות של מפתח קיים. הרשאה **human/dashboard-only**; היא לא יכולה להיות מוקצה למפתח API (מפתח bearer עשוי ליצור מפתחות אך אף פעם לא לערוך אותם). | -| `keys:disable` | `POST /keys/:id/disable` | שחזר מפתח. מפתחות מוגנים (`admin`, `dashboard-assistant`) לא יכולים להיות מבוטלים; סובב אותם דרך env var + restart. | -| `keys:regenerate` | `POST /keys/:id/regenerate` | סובב סוד של מפתח. מפתחות מוגנים לא יכולים להיווצר מחדש דרך מסלול זה. | +| `keys:create` | `POST /keys` | יצירה של מפתח API בהיקף חדש. **לא** מעניק עריכה של הרשאות מפתח קיים (זה `keys:update`). | +| `keys:read` | `GET /keys` | רשימה של מפתחות קיימים. סודות לעולם לא מוחזרים על ידי נקודת קצה זו. | +| `keys:update` | `PATCH /keys/:id` | עריכה של הרשאות מפתח קיים. הרשאה **לשימוש אדם/דוח בלבד**; לא ניתן להקצות אותה למפתח API (מפתח bearer עשוי ליצור מפתחות אך לעולם לא לערוך אותם). | +| `keys:disable` | `POST /keys/:id/disable` | שלילת מפתח. מפתחות מוגנים (`admin`, `dashboard-assistant`) לא יכולים להיות מושבתים; סובב אותם דרך משתנה env + הפעלה מחדש. | +| `keys:regenerate` | `POST /keys/:id/regenerate` | סיבוב הסוד של מפתח. מפתחות מוגנים לא יכולים להיות משוחזרים דרך נקודת קצה זו. | -### משתמשי Dashboard +### משתמשי דוח | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | הזמן משתמש dashboard חדש (משדרת email + one-time passcode (OTP) login) וקרא את ערכת ההרשאה default שהוגדרה ב-dashboard המשמשת seed את טופס ההזמנה. | -| `users:read` | `GET /users`, `GET /users/:id` | רשימת משתמשים וטעינת רשומת משתמש יחידה. | -| `users:update` | `PUT /users/:id` | ערוך הרשאות של משתמש. עדכונים משדרים email של שינוי הרשאות למשתמש המושפע ונכנסים לתוקף בבקשתם הבאה; לא נדרשת relоgin. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | בטל משתמש (שחזר את ה-sessions שלהם מיד) ו-re-enable משתמש שהיה מבוטל בעבר. | +| `users:create` | `POST /users`, `GET /users/defaults` | הזמנת משתמש דוח חדש (מנפיק דוא"ל + התחברות קוד חד-פעמי (OTP)) וקריאה של קבוצת ההרשאות ברירת המחדל שהוגדרה בדוח המשמשת כאריעה של טופס ההזמנה. | +| `users:read` | `GET /users`, `GET /users/:id` | רשימה של משתמשים וטעינה של רשיון משתמש יחיד. | +| `users:update` | `PUT /users/:id` | עריכה של הרשאות משתמש. עדכונים משדרים דוא"ל שינוי הרשאות למשתמש המושפע ונכנסים לתוקף בבקשה הבאה שלהם; אין צורך להתחברות מחדש. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | השבתה של משתמש (שלילה מיידית של הסשנים שלהם) והפעלה מחדש של משתמש שהושבת קודם לכן. | -הרשאות אלה תומכות בעמוד **Users** של ה-dashboard, שם ההיקפים שניתנו של כל חבר מוצגים כ-chips: +הרשאות אלו מגבירות את עמוד **משתמשים** של הדוח, כאשר ההיקפים המוענקים של כל חבר מוצגים כשבבי: -![עמוד Users: כרטיס לכל משתמש dashboard עם דוא"ל שלהם, הרשאות שניתנו, ובקרות עריכה/ביטול](/agenteye/images/users.png) +![עמוד המשתמשים: כרטיסיה לכל משתמש דוח עם הדוא"ל, ההרשאות המוענקות, וביקורות/השבתה](/agenteye/images/users.png) ### הגדרות תפעוליות | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | צפה בהגדרות תפעוליות המנוהלות ב-dashboard ובמטה-דטה שלהן; רשימת overrides context-window per-model; וסגור את החלון האפקטיבי למודל. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | ערוך הגדרות תפעוליות והוסף, שנה, או הסר per-model context-window overrides. השינויים משפיעים על אירועים חדשים ללא restart של השרת. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | צפייה בהגדרות תפעוליות המנוהלות בדוח ובמטא-נתונים שלהם; רשימה של עדכונים בחלון ההקשר לכל מודל; ותאימות של החלון האפקטיבי לדגם. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | עריכה של הגדרות תפעוליות והוספה, שינוי או הסרה של עדכונים בחלון ההקשר לכל מודל. שינויים משפיעים על אירועים חדשים ללא הפעלת השרת מחדש. | -![עמוד Settings: הגדרות תפעוליות המנוהלות ב-dashboard כגון sign-ins מורשים וחיי session/OTP, ניתנים לעריכה ללא restart](/agenteye/images/settings.png) +![עמוד ההגדרות: הגדרות תפעוליות המנוהלות בדוח כגון התחברויות מותרות וחיי סשן/OTP, שניתן לערוך ללא הפעלה מחדש](/agenteye/images/settings.png) -### alerts ו-incidents +### התראות ותקריות | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | צפה בהגדרות alert שהוגדרו. | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | יצירה, עריכה, מחיקה, ו-test-fire של הגדרות alert. | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | צפה ב-incidents וב-triage trail שלהם. | -| `incidents:write` | `POST /alerts/:id/incidents` | פתח incident ידנית נגד alert קיים. | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Acknowledge, assign, resolve, וcomment על incidents. | +| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | צפייה בהגדרות התראה מוגדרות. | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | יצירה, עריכה, מחיקה, וירי בחן של הגדרות התראה. | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | צפייה בתקריות וביום ההדרכה שלהן. | +| `incidents:write` | `POST /alerts/:id/incidents` | פתיחה ידנית של תקרית כנגד התראה קיימת. | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | הכרה, הקצאה, פתרון והוספת הערות לתקריות. | -### Audits +### ביקורות | הרשאה | מסלולי HTTP | מה זה מאפשר | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | צפה בהגדרות audit, היסטוריית run, וממצאים. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | יצירה, עריכה, מחיקה, וריצת audits; triage findings (acknowledge / mute / dismiss / resolve / reopen / assign). | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | צפייה בהגדרות ביקורת, היסטוריית ריצה ותוצאות. | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | יצירה, עריכה, מחיקה וריצה של ביקורות; טריאג תוצאות (הכרה / השתק / דחייה / פתרון / פתיחה מחדש / הקצאה). | -> **הערה:** כדי להעניק למפתח את משטח audit, הענק `audits:*` לו באופן מפורש. ראה [הערות upgrade וחוזרים לאחור](#upgrade-and-backward-compatibility-notes) לאופן כיצד grantees קיימים הומיגרו כאשר Audits הושלח. +> **הערה:** כדי לתן למפתח את משטח הביקורת, הענק `audits:*` בעדכון מפורש. ראה [הערות שדרוג וחומר תאימות אחורי](#upgrade-and-backward-compatibility-notes) להיסטוריית אופן הזדקנות של המנויים הקיימים כשהביקורות נשלחו. -> נקודת קצה של recipient-picker `GET /alerts/recipients` (המפרטת את אימיילי החברים שעורך alert יכול להודיע) ניתנת להשגה על ידי בעל **או** `alerts:read` **או** `alerts:write`, כך שעורכי alert יכולים למלא את הpicker ללא הענקת `users:read`. +> נקודת קצה של בחור הנמען `GET /alerts/recipients` (המפרטת את הודעות הדוא"ל של החברים שעורך התראה יכול להודיע) נגישה על ידי בעל **או** `alerts:read` **או** `alerts:write`, כך שעורכי התראה יכולים למלא את בחור ללא הענקת `users:read`. -> צופה dashboards צריך **גם** `dashboards:read` (כדי לטעון את התצוגות השמורות) וגם `evaluations:read` (מטריקות הבריאות מחושבות מנתוני הערכה). הענק `dashboards:write` כדי לאפשר למשתמש ליצור או לערוך dashboards, ו`dashboards:delete` כדי להסיר אותם. +> צופה דוחות צריך **כל** `dashboards:read` (כדי לטעון את התצוגות השמורות) **וגם** `evaluations:read` (מדדי הבריאות מחושבים מנתוני הערכה). תן `dashboards:write` כדי לתת למשתמש ליצור או לערוך דוחות, ו`dashboards:delete` כדי להסיר אותם. -> `/health` ו`/auth/*` (בקשת OTP, OTP verify, בדיקת session, logout) הם unauthenticated בעיצוב; הם זרימת הlogin וprobe של liveness. `GET /access-granters` דורש מפתח תקף אך ללא הרשאה ספציפית, כך שכל משתמש מחובר יכול לראות אילו admins ליצור קשר איתם לגבי שינויי גישה. +> `/health` ו`/auth/*` (בקשת OTP, אימות OTP, בדיקת סשן, התנתקות) אינם מאומתים לפי עיצוב; הם זרימת ההתחברות וחד-קו חיות. `GET /access-granters` דורש מפתח תקף אך ללא הרשאה ספציפית, כך שכל משתמש שהתחבר יכול לראות איזה מנהלים לא ליצור קשר בנוגע לשינויי גישה. --- -## ערכות הרשאות +## קבוצות הרשאות -ערכות הרשאות מאפשרות לך להחיל תפקיד בעל שם במקום לבחור ידנית tokens בודדים בכל פעם. במקום לבחור תריסר הרשאות אחת אחת עבור כל משתמש dashboard חדש או מפתח API, אתה בוחר קבוצה, וכל אחד שמוקצה לה נושא הענקה עקבית וניתנת לביקורת. עריכת קבוצה מותאמת מחדש את ההענקה החדשה לכל משתמש שכבר מוקצה לה, כך ששינוי תפקיד הוא עריכה אחת ולא סריקה דרך כל חבר. +קבוצות הרשאות מאפשרות לך להחיל תפקיד בשם במקום לבחור ידנית אסימונים בודדים בכל פעם. במקום בחירה של תריסר הרשאות אחת אחת לכל משתמש דוח חדש או מפתח API, אתה בוחר קבוצה, וכל אחד שהוקצה לה נושא הענקה עקבית וניתנת לבדיקה. עריכה של קבוצה משותפת מחדש משתמשת את ההענקה החדשה לכל משתמש שכבר הוקצה לה, כך ששינוי תפקיד הוא עריכה אחת ולא סריקה דרך כל חבר. -כל organization זורעת עם שלוש קבוצות built-in: +כל ארגון מזורע עם שלוש קבוצות מובנות: -| קבוצה | הרשאות | מיועדת עבור | +| קבוצה | הרשאות | מיועדת ל | |---|---|---| -| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | גישת view-only בכל משטח תפעולי. | -| `standard` | כל דבר ב-`read-only`, בתוספת `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | read-only בתוספת פעולות ה-on-caller היומיומיות: הריצו שאילתות, re-evaluate sessions, acknowledge incidents, והשתמש ב-AI assistant. | -| `admin` | כל הרשאה assignable | בקרה מלאה של ה-org. | +| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | גישה לצפייה בלבד על כל משטח התפעול. | +| `standard` | הכל ב`read-only`, בתוספת `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | קריאה בלבד בתוספת פעולות הקריאה היומיות: הרצת שאילתות, הערכה חוזרת של סשנים, הכרה בתקריות, והשימוש בעוזר ה-AI. | +| `admin` | כל הרשאה מוקצית | שליטה מלאה של הארגון. | -שלוש הקבוצות built-in הן **immutable**; השמות שלהם תמיד משמעות את אותו דבר, כך `read-only`, `standard`, ו`admin` בטוחים להפניה בpolicy וב-onboarding. אופרטור יכול ליצור **custom sets** נוספים כדי למודל תפקידים ספציפיים לארגון שלך (לדוגמה, תפקיד dashboard author או תפקיד collector-only). +שלוש הקבוצות המובנות הן **בלתי ניתנות לשינוי**; השמות שלהן תמיד אומרים דבר זהה, כך ש`read-only`, `standard`, ו`admin` בטוח להתייחס במדיניות ובהנעה. אופרטור יכול ליצור **קבוצות משותפות** נוספות כדי למדל תפקידים הספציפיים לארגון שלך (למשל, תפקיד דוח מחבר או תפקיד קולט בלבד). -ערכות מוצגות ב-dashboard ומנוהלות על ה-API ב-`GET /permission-sets` (רשימה, gated על ידי `users:read`) ו`POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (יצירה, עריכה, מחיקה של קבוצה מותאמת, gated על ידי `settings:write`). מחיקה או עריכה של קבוצה built-in נדחית. +קבוצות מעומיתות בדוח ומנוהלות על ה-API ב`GET /permission-sets` (רשימה, מגודרת על ידי `users:read`) ו`POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (יצירה, עריכה, מחיקה של קבוצה משותפת, מגודרת על ידי `settings:write`). דחייה או עריכה של קבוצה מובנית מוחזקת. -חברות בקבוצה היא מה שתומך שתי תכונות אחרות: +החברות בקבוצה הוא מה תומך בשתי תכונות נוספות: -- **`DEFAULT_USER_PERMISSIONS`** (ההענקה preselected כשadmin פותח **+ new user**) מוגדרת כברירת מחדל לקבוצה `standard`. -- **הדגל `--set`** ב-`agenteye-orgctl` (ניהול חברים של operator) מתחיל חבר מקבוצה בעל שם, ש-fine-tune אחר כך עם `--add` / `--remove`. +- **`DEFAULT_USER_PERMISSIONS`** (ההענקה שנבחרה מראש כאשר מנהל פותח **+ משתמש חדש**) מתחילה בערך של קבוצת `standard`. +- **הדגל `--set`** ב`agenteye-orgctl` (ניהול חבר ארגוני) מתחיל חבר מקבוצה בשם, שלאחר מכן אתה מעדן עם `--add` / `--remove`. -> **הערה:** כאשר קבוצה כוללת הרשאה שאינה key-assignable (לדוגמה קבוצה מותאמת הנושאת `keys:update`), זריעה של מפתח מקבוצה זו מפילה את ה-tokens שאינם assignable; השרת אחרת היה דוחה את המפתח ב-HTTP 422. משתמשי Dashboard אינם כפופים להגבלה זו. +> **הערה:** כאשר קבוצה כוללת הרשאה שאינה מוקצית-מפתח (למשל קבוצה משותפת לתמוך ב`keys:update`), זריעה של מפתח מהקבוצה מפיל את האסימונים שלא מוקצים; השרת אחרת דחה את המפתח עם HTTP 422. משתמשי דוח אינם כפופים להגבלה זו. --- -## מפתח Admin Bootstrap +## מפתח Bootstrap Admin -מפתח ה-admin הוא credential הroot היחיד שמאפשר לאופרטור להעלות גישה מלא: עם זה אתה יכול ליצור כל מפתח בהיקף אחר, להזמין את משתמשי dashboard הראשונים, ולהגדיר את ההופעה לפני שמפתח אחר קיים. זהו המפתח היחיד שאתה לא יוצר דרך מפתחות API; הוא מסופק מהסביבה כך השרת ניתן להשגה ב-first boot. +מפתח ניהול הוא בן הברית היחיד שמאפשר לאופרטור להעלות גישה מכלום: בעזרתו אתה יכול להכניס כל מפתח בהיקף אחר, להזמין את משתמשי הדוח הראשונים, ולהגדיר את המופע לפני שמפתח אחר קיים. זהו המפתח היחיד שאתה לא יוצר דרך ה-API של מפתחות; הוא מסופק מהסביבה כך שהשרת נגיש בהפעלה הראשונה. -הגדר את משתנה הסביבה `ADMIN_KEY` על השרת. בכל startup השרת עושה upsert של ערך זה כמפתח admin עם כל ההרשאות. +הגדר את משתנה הסביבה `ADMIN_KEY` על השרת. בכל הפעלה, השרת מחדש ערך זה כמפתח ניהול עם כל ההרשאות. -כדי לסובב: שנה את `ADMIN_KEY` לסוד חדש והפעל מחדש את השרת. +כדי לסובב: שנה `ADMIN_KEY` לסוד חדש והפעל את השרת מחדש. --- -## Organization scoping +## ארגון scoping -**Organizations עצמם יוצרים ומנוהלים out-of-band על ידי אופרטור, לא דרך keys API זה.** Org וחיי member (create / rename / delete / purge org; add / update / remove member) נעשים עם ה-**`agenteye-orgctl`** CLI; אין HTTP API או כפתור dashboard עבורו. מה *כן* בלתי שונה: **per-org API keys עדיין ממולכים ב-dashboard (או דרך keys API זה)** על ידי חברים של org. +**ארגונים עצמם נוצרים ומנוהלים מחוץ הלהקה על ידי אופרטור, לא דרך API מפתחות זה.** מחזור חיי ארגון וחברים (יצירה / שינוי שם / מחיקה / טיהור ארגון; הוספה / עדכון / הסרת חבר) נעשה עם ה**`agenteye-orgctl`** CLI; אין API HTTP או כפתור דוח לכך. מה *כן* ללא שינוי: **מפתחות API לכל ארגון עדיין מוטעמים בדוח (או דרך API מפתחות זה)** על ידי חברי ארגון. -בהפעלה multi-org, כל מפתח שחבר org יוצר (דרך keys API זה או ה-dashboard **Keys** page) שייך ל-**organization אחת** ויכול רק אי פעם לקרוא או לכתוב את הנתונים של org זה; ה-org stamped על המפתח בזמן יצירה ומאוכף בכל בקשה. שני המפתחות bootstrap הם היוצא מן הכלל היחיד: מפתח ה-`admin` (זרוע מ-`ADMIN_KEY`) ומפתח ה-`dashboard-assistant` (זרוע מ-`AGENT_API_KEY`) הם **instance-scoped** (הם לא נושאים org). ה-dashboard מטפל כעם עם מפתח `admin` כך הוא יכול proxy per-org requests בעבור חברים שחתומים. single-tenant deployments לא צריכים לחשוב על זה; כל המפתחות שייכים ל-`default` org built-in. +בהפצה ארגונית רבה, כל מפתח שחבר ארגון יוצר (דרך API מפתחות זה או עמוד **Keys** של הדוח) שייך **לארגון אחד** ויכול רק אי פעם לקרוא או לכתוב נתונים של ארגון זה; הארגון חתום על המפתח בעת יצירה ומאומת בכל בקשה. שני ה-bootstrap keys הם החריג היחיד: מפתח `admin` (מזורע מ`ADMIN_KEY`) ומפתח `dashboard-assistant` (מזורע מ`AGENT_API_KEY`) הם **טווח מופע** (הם אינם נושאים ארגון). הדוח מאומת עם מפתח `admin` כך שהוא יכול להיות proxy בקשות לכל ארגון בשם חברים שנכנסו. בהפצות דיירים יחידים אין צורך לחשוב על כך; כל מפתחות שייכים לארגון `default` המובנה. --- ## יצירת מפתחות -השתמש במפתח ה-admin (או כל מפתח עם הרשאה `keys:create`) כדי ליצור מפתחות בהיקף נוסף. +השתמש במפתח ניהול (או בכל מפתח עם הרשאת `keys:create`) ליצירת מפתחות בהיקף נוסף. -### Collector key (ingest only) +### מפתח קולט (ingest בלבד) ```bash curl -s -X POST http://your-server/keys \ @@ -179,7 +179,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### Dashboard key (read only) +### מפתח דוח (קריאה בלבד) ```bash curl -s -X POST http://your-server/keys \ @@ -192,7 +192,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -כשאתה יוצר מפתח דרך HTTP API, אתה מספק את ערך `key` בעצמך; בחר בסוד חזק ואחסן אותו בבטחה. (ה-dashboard עובד בדרך אחרת: הוא יוצר סוד חזק עבורך ומראה אותו פעם אחת ביצירה; ראה [Key Management in the Dashboard](#key-management-in-the-dashboard).) התגובה מאשרת שהמפתח נוצר: +כאשר אתה יוצר מפתח על API HTTP, אתה מספק את ערך `key` בעצמך; בחר בסוד חזק ואחסנו בבטחה. (הדוח פועל בדרך אחרת: הוא יוצר סוד חזק עבורך ומציג אותו פעם אחת בעת היצירה; ראה [ניהול מפתחות בדוח](#key-management-in-the-dashboard).) התגובה מאשרת שהמפתח נוצר: ```json { @@ -205,20 +205,20 @@ curl -s -X POST http://your-server/keys \ --- -## רישום מפתחות +## רשימת מפתחות ```bash curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -סודות מפתחות לא מוחזרים בתגובות רישום, רק IDs, שמות, והרשאות. +סודות מפתח אינם מוחזרים בתגובות רשימה, רק IDs, שמות, והרשאות. --- -## ביטול מפתח +## השבתת מפתח -ביטול שחזור גישה מיד ללא מחיקת רשומת המפתח. +השבתה שולל גישה מיד ללא מחיקת רשיון המפתח. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -227,53 +227,53 @@ curl -s -X POST http://your-server/keys//disable \ --- -## סיבוב מפתח +## ספירה מחדש של מפתח -יוצר סוד חדש למפתח קיים. הסוד הישן מבוטל מיד. +יוצר סוד חדש למפתח קיים. הסוד הישן מועמד מיד. ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -התגובה כוללת את הסוד בטקסט פשוט החדש, **מוצג רק פעם אחת**. +התגובה כוללת את הסוד בטקסט חדש, **מוצג רק פעם אחת**. --- -## ניהול מפתחות ב-Dashboard +## ניהול מפתחות בדוח -עמוד **Keys** ב-dashboard מספק UI עבור כל הפעולות לעיל. אתה צריך מפתח עם הרשאה `keys:read` כדי לצפות ברשימה, ו`keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` עבור ה-create / edit / disable / regenerate פעולות בהתאמה. עריכה של הרשאות של מפתח (`keys:update`) היא נפרדת מיצירת אחד (`keys:create`), כך שאתה יכול להעניק לאופרטור את היכולת ליצור מפתחות ללא היכולת לשנות היקף של קיימים, או להיפך. מפתח ה-admin מכסה את כל אלה. +עמוד **Keys** בדוח מספק ממשק משתמש לכל הפעולות לעיל. אתה צריך מפתח עם הרשאת `keys:read` כדי לצפות ברשימה, ו`keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` לפעולות ליצור / עריכה / השבתה / ספירה מחדש בהתאמה. עריכה של הרשאות מפתח (`keys:update`) מופרדת מיצירת אחת (`keys:create`), כך שתוכל להעניק לאופרטור את היכולת להטביע מפתחות ללא היכולת לשנות-סקופ קיימים, או להיפך. מפתח ניהול מכסה את כל אלה. -כאשר אתה יוצר מפתח מה-dashboard אתה לא מספק את הסוד; ה-dashboard יוצר סוד חזק בשבילך ומציג אותו **פעם אחת** ביצירה. העתק אותו מיד ואחסן אותו בבטחה; הוא לעולם לא מוצג שוב, בדיוק כמו עם regenerate. אתה עדיין יכול לבחור את הרשאות המפתח ישירות, או לזרוע אותם מערכת הרשאות (ראה למטה). +כאשר אתה יוצר מפתח מהדוח, אתה לא מספק את הסוד; הדוח יוצר סוד חזק עבורך ומציג אותו **פעם אחת** בעת היצירה. העתק אותו מיד ואחסנו בבטחה; הוא לעולם לא יוצג שוב, בדיוק כמו בספירה מחדש. עדיין תוכל לבחור את ההרשאות של המפתח ישירות, או לזרוע אותן מקבוצת הרשאות (ראה למטה). -![עמוד API Keys: כרטיס לכל מפתח המציג את שמו, הרשאות שניתנו, וזמן יצירה, עם regenerate ו-disable פעולות; מפתחות מוגנים כמו `admin` מסומנים](/agenteye/images/api-keys.png) +![עמוד מפתחות ה-API: כרטיסיה לכל מפתח המציגה את שמו, ההרשאות המוענקות, ועת היצירה, עם פעולות ספירה מחדש והשבתה; מפתחות מוגנים כמו `admin` מסומנים](/agenteye/images/api-keys.png) --- -## פריסת מפתחות מומלצת +## פריסת מפתח מומלצת -| מפתח | הרשאות | בשימוש על ידי | +| מפתח | הרשאות | משמש ל | |---|---|---| -| `admin` (bootstrap דרך env var `ADMIN_KEY`) | הכל | Ops/setup, ו-dashboard (אימות עם `ADMIN_KEY`, proxy בקשות משתמש עם בדיקות הרשאה) | -| מפתח קולקטור per-host | `events:add` | קולקטור על כל מכונת אג'נט | -| `dashboard-assistant` (bootstrap דרך env var `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI assistant, זרוע באופן אוטומטי, **מוגן**; לא יכול להיות edited דרך ה-API | -| מפתח telemetry של assistant (אופציונלי) | `events:add` | self-instrumentation של AI assistant, אם מופעל | +| `admin` (bootstrap דרך משתנה env `ADMIN_KEY`) | כל ההרשאות | Ops/setup, והדוח (מאומת עם `ADMIN_KEY`, proxy בקשות משתמש עם בדיקות הרשאות) | +| מפתח קולט לכל host | `events:add` | קולט על כל מכונת agent | +| `dashboard-assistant` (bootstrap דרך משתנה env `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | עוזר AI, מזורע באופן אוטומטי, **מוגן**; לא ניתן לערוך דרך ה-API | +| מפתח טלמטריה של עוזר (אופציונלי) | `events:add` | כיול עצמי של עוזר AI, אם מופעל | -> **הערה:** מפתח ה-assistant **זורע באופן אוטומטי** על ידי השרת מ-env var `AGENT_API_KEY` (אותו סוד שה-agent מציג כ-`AGENTEYE_API_KEY`); אין שלב key-minting ידני ואין מפתח admin מעורב. הרשאות שלו קבועות בקוד המקור כך ההיקף לא יכול להיות מורחב על ידי misconfiguration: קריאה על פני events / evaluations / dashboards, בתוספת dashboards-write ו-queries-read / write / run עבור זרימת authoring של Query AI Ask Write. כל ה-SQL עדיין עובר אותו role read-only בדיוק וguarded SQL path כמו query שנכתב על ידי משתמש, כך זה מרחיב את המשטח *authoring*, לא את משטח הנתונים; פעולות destructive (`queries:delete`, `dashboards:delete`) בכוונון להישאר off מפתח ה-assistant. כמו מפתח `admin`, הוא **מוגן**: הוא לא יכול להיות מבוטל או regenerated דרך keys API, רק סובב על ידי שינוי `AGENT_API_KEY` וrestart. משתמשי Dashboard בנוסף צריך את הרשאה `agent:use` כדי לראות ולהשתמש ב-assistant. אם אתה מפעיל self-instrumentation, תן ל-assistant מפתח נפרד `events:add`-only. +> **הערה:** מפתח העוזר **מזורע באופן אוטומטי** על ידי השרת מתוך משתנה env `AGENT_API_KEY` (אותו הסוד שה-agent מציג כ`AGENTEYE_API_KEY`); אין שלב יצירת מפתח ידני ואין שום מפתח ניהול מעורב. ההרשאות שלו קבועות בקוד מקור כך ש-scope לא יכול להיות מורחב על ידי הגדרה מוטעה: קרא על פני אירועים / הערכות / דוחות, בתוספת dashboards-write ו-queries-read / write / run לזרימת כתיבת שאילתה Ask AI. כל ה-SQL עדיין עובר דרך אותו תפקיד קריאה בלבד ודרך מוגנת SQL כמו שאילתה שנכתבה על ידי משתמש, כך שזה מרחיב את *משטח הכתיבה*, לא משטח נתונים; פעולות הרסניות (`queries:delete`, `dashboards:delete`) בכוונון להישאר בחוץ מפתח עוזר. כמו מפתח `admin`, הוא **מוגן**: לא ניתן להשביתו או לספרו מחדש דרך ה-API של מפתחות, רק לסובב על ידי שינוי `AGENT_API_KEY` והפעלה מחדש. *משתמשי* דוח צריכים בנוסף הרשאת `agent:use` כדי לראות ולהשתמש בעוזר. אם אתה מפעיל כיול עצמי, תן לעוזר מפתח נפרד `events:add`-בלבד. --- -## הערות upgrade וחוזר לאחור תאימות +## הערות שדרוג וחומר תאימות אחורי -אתה צריך אלה רק אם אתה משדרג instance קיים; פריסות חדשות יכולות לדלג עליהם. +אתה צריך אלה רק אם אתה מדרוג מופע קיים; הפצות חדשות יכולות לדלג עליהן. -> כאשר Audits הושלח, grantees קיימים הורחבו לאורך אותן צורות תפקיד כמו alerts: כל משתמש וערכת הרשאות שמחזיק `alerts:read` הקבל `audits:read`, וכל בעל `alerts:write` הקבל `audits:write`. API keys קיימים **לא** הורחבו. הענק `audits:*` למפתח באופן מפורש אם הוא צריך את משטח audit. +> כאשר Audits נשלחו, קודמים קיימים הורחבו לאורך אותם צורות תפקיד כמו התראות: כל משתמש וקבוצת הרשאות המחזיקה `alerts:read` קיבלה `audits:read`, וכל בעל `alerts:write` קיבל `audits:write`. מפתחות API קיימים **לא** הורחבו. הענק `audits:*` למפתח בעדכון מפורש אם הוא צריך משטח ביקורת. -> Stored grants של ה-legacy token `alerts:ack` מנותחים כ-`incidents:ack` כך on-callers שומרים גישה ללא rekeying. ה-token כבר לא assignable מ-user editor של ה-dashboard; המטריצה מציעה `incidents:ack` במקום. +> הענקות מאוחסנות של האסימון `alerts:ack` המדורג מנתחות כ`incidents:ack` כך שקראי הקריאה מחזיקים בגישה ללא מפתח חדש. האסימון כבר אינו מוקצה מעורך המשתמש של הדוח; המטריצה מציעה `incidents:ack` במקום זאת. --- -## צעדים הבאים +## שלבים הבאים -- [Python SDK](/he/agenteye/python-sdk): כיצד קוד ה-agent שלך מטפל בהנחה כאשר שולח אירועים. -- [Security](/he/agenteye/security): כיצד sign-in, access control, ו-per-organization data isolation עובדים. \ No newline at end of file +- [Python SDK](/he/agenteye/python-sdk): כיצד קוד agent שלך מאומת בעת שליחת אירועים. +- [אבטחה](/he/agenteye/security): איך התחברות, שליטה בגישה, וביידוד נתונים לכל ארגון פועלים. \ No newline at end of file diff --git a/docs/he/agenteye/assistant.mdx b/docs/he/agenteye/assistant.mdx index bf37cb18..f0317620 100644 --- a/docs/he/agenteye/assistant.mdx +++ b/docs/he/agenteye/assistant.mdx @@ -1,15 +1,16 @@ --- +--- title: "עוזר AI" -description: "שאל את נתוני הסוכן שלך שאלה באנגלית פשוטה וקבל תשובה המקושרת ישירות להוכחה." +description: "שאל שאלה לנתוני הסוכן שלך באנגלית רגילה וקבל תשובה המקושרת ישירות להוכחה." --- -שאל את נתוני הסוכן שלך שאלה באנגלית פשוטה וקבל תשובה המקושרת ישירות להוכחה. אין SQL לכתוב, אין לוחות מחוונים לדפדף דרכם — עוזר **Failproof AI Observability** הוא הדרך המהירה ביותר לכל אחד בצוות שלך לקבל תשובות על הסוכנים שלך. +שאל שאלה לנתוני הסוכן שלך באנגלית רגילה וקבל תשובה המקושרת ישירות להוכחה. אין צורך לכתוב SQL, אין צורך לחפש בדשבורדים — עוזר ה-**Failproof AI Observability** הוא הדרך המהירה ביותר לכל אחד בצוות שלך להשיג תשובות על הסוכנים שלך. -![עוזר Failproof AI Observability משיב לשאלה באנגלית פשוטה בתוך לוח המחוונים, המציג טבלת Agent Activity חיה, פירוט שימוש בדגם לכל סוכן, ותובנות כתובות, עם השאילתות שהוא הריץ המוצגות בשורה](/agenteye/images/assistant.png) -*שאל באנגלית פשוטה וקבל תשובה שנבנתה מנתונים משלך. כאן הוא מפרק אילו סוכנים עסוקים ביותר ואילו דגמים הם משתמשים בהם, ומציג את השאילתות שהוא הריץ כדי שתוכל לאמת כל מספר.* +![עוזר Failproof AI Observability עונה לשאלה באנגלית רגילה בתוך הדשבורד, מציג טבלת Agent Activity חיה, פירוט שימוש במודל לכל סוכן, ותובנות כתובות, עם השאילתות שהוא הפעיל מוצגות בשורה](/agenteye/images/assistant.png) +*שאל באנגלית רגילה וקבל תשובה שנבנתה מהנתונים שלך. כאן זה מפרק אילו סוכנים עסוקים ביותר ואילו מודלים הם משתמשים, ומציג את השאילתות שהוא הפעיל כדי שתוכל לאמת כל מספר.* -אין מה ללמוד. פתח את הצ'אט, הקלד מה שאתה רוצה לדעת, וקבע את הקישורים שהוא מחזיר: +אין כלום ללמוד. פתח את הצ'אט, הקלד מה שאתה רוצה לדעת, וגש לקישורים שהוא מחזיר: ``` You: which sessions errored today? @@ -24,36 +25,36 @@ AI: This run took 12 steps across 3 tools and failed near the end when a Links: the session, the failing event, and that evaluation. ``` -## פשוט שאל, וקפוץ ישר להוכחה +## פשוט שאל, וקפוץ ישירות להוכחה -אתה מפסיק לנחש ואתה מפסיק לכתוב שאילתות. שאל "איך איכות מתפתחת בייצור השבוע הזה?", "אילו הפעלות נכשלו היום?", או "סכם הפעלה זו," וקבל תשובה ישירה תוך שניות במקום לבנות שאילתה ולקרוא אותה בעצמך. +אתה מפסיק לנחש ומפסיק לכתוב שאילתות. שאל "איך איכות טרנדית בייצור השבוע הזה?", "אילו סשנים כשלו היום?" או "סכום את הסשן הזה," וקבל תשובה ישרה תוך שניות במקום לבנות שאילתה ולקרוא אותה בעצמך. -כל תשובה מגיעה עם הקבלות שלה. העוזר מקשר את ההפעלות המדויקות, השאילתות השמורות, ולוחות המחוונים שהוא השתמש בהם כדי להגיע לתשובה, כדי שתוכל ללחוץ וליצור קישור ולאשר בזה לקחת את דברו על זה. הוא גם **page-aware**: שאל על "הפעלה זו" בזמן שאתה צופה בהפעלה אחת והוא כבר יודע איזו הפעלה אתה מתכוון. פתח מחדש כל שיחה מוקדמת יותר מאוחר מת דורג ההיסטוריה והמשך מהמקום שבו עזבת. +כל תשובה מגיעה עם התעודות שלה. העוזר מקשר את הסשנים המדויקים, השאילתות השמורות והדשבורדים שהוא השתמש בהם כדי להגיע לתשובה, כדי שתוכל ללחוץ וקדימה ולאשר במקום קחת את זה על האמונה. זה גם **תלוי עמוד**: שאל על "הסשן הזה" בזמן שאתה צופה באחד והוא כבר יודע איזו הרצה אתה מתכוון. פתח מחדש כל שיחה קודמת מיותר מהמתג מסלול ההיסטוריה והמשך מעם עזבת. -## הפוך תשובה טובה לשאילתה שמורה או לוח מחוונים +## הפוך תשובה טובה לשאילתה שמורה או לדשבורד -כאשר תשובה שווה את ההנצחה, בקש מהעוזר לשמור אותה. הוא משרטט את SQL לשאילתה שמורה, או מרכיב לוח מחוונים מאותן שאילתות, ואז מציג לך כרטיס **Approve / Reject**. שום דבר לא נכתב עד שתלחץ על Approve, כך שתקבל את המהירות של "פשוט שאל" כשהמילה האחרונה היא תמיד שלך. +כאשר תשובה שווה לשמור, בקש מהעוזר לשמור אותה. הוא מעצב את SQL לשאילתה שמורה, או מרכיב דשבורד מהשאילתות הללו, ואז מציג לך כרטיס **אישור / דחייה**. שום דבר לא נכתב עד שתלחץ אישור, כך שתקבל את המהירות של "פשוט שאל" כשלשמה האחרון תמיד שלך. -בעמוד **Queries** הוא הולך צעד קדימה הופך ללוחור SQL: תאר את השאילתה שאתה רוצה ("הצג שיעור שגיאה לפי סוכן במשך 7 הימים האחרונים") והוא זורם SQL ישר לעורך, ופוצה תצוגת diff כדי שתוכל **Accept** או **Reject** את השינוי לפני שהוא נוחת. +בעמוד **Queries** זה הולך צעד אחד הלאה ופוך עוזר SQL: תאר את השאילתה שאתה רוצה ("הצג שיעור שגיאה לפי סוכן ב-7 הימים האחרונים") והוא משדר SQL ישירות לעורך, פתיחה תצוגת דיפ כדי שתוכל **קבל** או **דחה** את השינוי לפני שהוא יישבת. -![עמוד Observability Queries ועורך SQL שלו](/agenteye/images/query-lab.png) -*עמוד Queries: עורך זה הוא המקום שבו העוזר זורם רק לקריאה שאילתה בדעת לך לקבל או לדחות.* +![עמוד Observability Queries והעורך SQL שלו](/agenteye/images/query-lab.png) +*עמוד Queries: העורך הזה הוא המקום שבו העוזר משדר טיוטה לקריאה בלבד לשאילתה שלך להשכמות או דחייה.* -לשם SQL על ידי שאילה כאן משתמש בהרשאה `queries:run`, אותה שלידה כפתור **Run** של העורך. צ'אט בכל מקום אחר זקוק `agent:use`. +שימוש ב-SQL על ידי שאילה כאן משתמש ב-`queries:run` הרשאה, אותה אחת שמאחורי הכפתור **Run** של העורך. צ'אט בכל מקום אחר צריך `agent:use`. -## בטוח להעביר לכל הצוות +## בטוח להחזיק לכל הצוות -אתה יכול לפתוח את העוזר לכל אחד בלי לדאוג למה זה עשוי לגעת: +אתה יכול לפתוח את העוזר לכל אחד בלי לדאוג למה הוא יכול לגעת: -- **הוא קורא רק מה שאתה כבר יכול לראות.** תשובות מתוחמות להרשאות הקריאה שלך, כך שהוא לעולם לא מרחיב את פני השטח של הנתונים שלך. -- **כל כתיבה מחכה לך.** שאילתות שמורות ולוחות מחוונים נוצרים רק לאחר לחיצת Approve מפורשת, ואין הגדרה שהופכת את השער הזה. -- **זה לעולם לא יכול למחוק שום דבר.** אין כלי מחיקה חשוף ללעוזר אין הרשאת מחיקה. מחיקות נשארות בידיך, בלוח המחוונים. -- **זה נשאר בתוך הארגון שלך.** העוזר רואה רק את הארגון שאתה צופה כרגע. -- **השאלות שלך נשארות שלך.** הנושאים והתשובות חיים בנתוני Observability שלך; רק ניתוחי המוצר מתעדים מטא -דטה שימוש, לעולם לא טקסט הנושא שלך. +- **זה קורא רק את מה שאתה כבר יכול לראות.** תשובות מתוחמות להרשאות הקריאה שלך, כך שזה לעולם לא מרחיב את פני השטח של הנתונים שלך. +- **כל כתיבה מחכה לך.** שאילתות שמורות ודשבורדים נוצרים רק לאחר לחיצת אישור מפורשת שלך, ואין הגדרה שהופכת את השער הזה. +- **זה לעולם לא יכול למחוק שום דבר.** לא חשוף כלי מחיקה וה-עוזר אין הרשאת מחיקה. מחיקות נשארות בידיך, בדשבורד. +- **זה נשאר בתוך הארגון שלך.** העוזר רק אי פעם רואה את הארגון שאתה צופה כרגע. +- **השאלות שלך נשארות שלך.** Prompts והתשובות חיות בבסיס הנתונים של Observability שלך; ניתוח מוצרים מתעד רק נתוני מטא-שימוש, לא את הטקסט של ה-prompt שלך. ## איפה למצוא אותו -העוזר רוכב על הקצה הימני של כל עמוד תחת הארגון שלך (`//...`). לחץ על הרל, או לחץ על `⌘J` / `Ctrl+J`, כדי להרחיב אותו לפנל צ'אט מלא, וגרור את קצהו כדי לשנות את גודל; הרוחב שלך זכור על פני טעינות חוזרות. אתה זקוק להרשאת **`agent:use`** כדי להשתמש בו, אחרת הרל מכוסה. אם זה עדיין לא הופעל לפריסה שלך (זה צריך חיבור LLM), תראה רל מושתק במקום צ'אט עובד. +העוזר רוכב על הקצה הימני של כל עמוד תחת הארגון שלך (`//...`). לחץ על המסילה, או לחץ על `⌘J` / `Ctrl+J`, כדי להרחיב אותה לפנל הצ'אט המלא, וגרור את הקצה שלה כדי לשנות את הגודל; הרוחב שלך זכור על פני טעינות מחדש. אתה צריך את הרשאת **`agent:use`** כדי להשתמש בו, אחרת המסילה מתעמתת. אם זה עדיין לא הופעל ליישום שלך (זה צריך חיבור LLM), תראה מסילה ספומה במקום צ'אט עובד. ## קשור diff --git a/docs/he/agenteye/audits.mdx b/docs/he/agenteye/audits.mdx index b1af7a32..4fa7fc58 100644 --- a/docs/he/agenteye/audits.mdx +++ b/docs/he/agenteye/audits.mdx @@ -1,9 +1,10 @@ --- -title: "審査: מנתח אמינות אוטומטי שלך" -description: "Failproof AI Observability חוקר את הכשלים שלא כתבת עבורם כלל כלל, ומסר לך רשימת עדיפויות מדורגת ומבוססת ראיות של בדיוק מה לתקן." +title: "ביקורות: האנליטיקאי הנתינות האוטומטי שלך" +description: "Failproof AI Observability חוקר את הכשלים שלא כתבת להם כלל כלל וחוקר כך לך רשימת מדורגת ותומכת בראיות של בדיוק מה לתקן." --- -Failproof AI Observability חוקר את הכשלים שלא כתבת עבורם כלל כלל, ומסר לך רשימת עדיפויות מדורגת ומבוססת ראיות של בדיוק מה לתקן. זה כמו שיש לך אנליסט שמסרק את הלוגים שלך כל לילה, ואז משאיר את הרשימה הקצרה על השולחן שלך בבוקר. + +Failproof AI Observability חוקר את הכשלים שלא כתבת להם כלל כלל וחוקר כך לך רשימת מדורגת ותומכת בראיות של בדיוק מה לתקן. זה כמו שיש לך אנליטיקאי שמסרק את הלוגים שלך כל לילה, ואז משאיר את הרשימה הקצרה על השולחן שלך עד הבוקר.
@@ -11,43 +12,43 @@ Failproof AI Observability חוקר את הכשלים שלא כתבת עבורם *סיור של שתי דקות: מריצה מתוזמנת לתיקון שאתה יכול לפעול לפיו.* -![דף הAudits: עבודות חוזרות שסורקות את ההפעלות שלך לדפוסי כשל, כל אחת עם לוח זמנים והרגישות](/agenteye/images/audits.png) -*כל 审查 היא עבודה חוזרת שחוקרת את ההפעלות שלך וכותבת המלצות מדורגות ומבוססות ראיות.* +![עמוד הביקורות: משימות חוזרות שסורקות את הסשנים שלך לחיפוש דפוסי כשל, כל אחת עם לוח זמנים וקביעת רגישות](/agenteye/images/audits.png) +*כל ביקורת היא משימה חוזרת שחוקרת את הסשנים שלך וכותבת המלצות מדורגות ותומכות בראיות.* -## הפסק להנחש מה לתקן הבא +## הפסיקו לנחש מה לתקן הבא -התראות תופסות את הבעיות שאתה כבר יודע שצריך לעקוב אחריהן. 审查 תופסות את אלה שאתה לא. על לוח זמנים שאתה קובע, 审查 קורא על פני כל הפעלות ה-agent שלך וציד אחר דפוסים שכדאי לתקן, כדי שתוכל להקדיש את הזמן שלך לפעול על ממצאים במקום לגלול ברישומים בתקווה לזהות אותם בעצמך. +התראות תופסות את הבעיות שאתה כבר יודע לראות אותן. ביקורות תופסות את אלה שאתה לא. בלוח זמנים שאתה קובע, ביקורת קוראת על פני כל סשני האג'נט שלך וצדות דפוסים שכדאי לתקן, כך שתוציא את הזמן שלך לפעול על ממצאים במקום להתגלגל בלוגים וקווה לתפוס אותם בעצמך. -ריצה יחידה רודפת אחרי מצבי הכשל שבעצם שוברים agents בייצור: +ריצה יחידה צדה על מצבי הכשל שבאמת שוברים אג'נטים בייצור: -- **clusters שגיאה**: אותו כשל חוזר תחת סיבה ערך משותפת. -- **drift לעומת baseline**: התנהגות שקט גולשת משחלון ידוע-טוב. -- **כשל יעד בתמלילים**: ריצות שסיימו בטכנית אבל לעולם לא עשו את העבודה. -- **שימוש לא נכון בכלי**: הכלי הלא נכון, ארגומנטים גרועים, או לולאות שבוערות קריאות. -- **עסקות איכות ועלות**: איפה שאתה משלם יותר מדי עבור פלט שאתה יכול להשיג בזול יותר. -- **פערי כיסוי**: התנהגות שאף eval או התראה לא משקיפה עליה. +- **אשכולות שגיאה**: אותו כשל חוזר תחת סיבה שורש משותפת. +- **סחיפה מול בסיס**: התנהגות החלקה שבהשקט מחלון ידוע טוב. +- **כשל מטרה בתמלילים**: ריצות שהסתיימו מבחינה טכנית אבל לא עשו את העבודה. +- **שימוש לא נכון בכלים**: הכלי הלא נכון, טיעונים גרועים, או לולאות שחוזרות בשיחות. +- **פשרויות בעלות ואיכות**: כאשר אתה משלם יותר מדי לתפוקה שיכולת לקבל בעלות נמוכה יותר. +- **פערי כיסוי**: התנהגות שאף הערכה או התראה לא מעקבת אחריה. -אתה מחליט כמה קשה זה חוקר עם הגדרת **הרגישות** יחידה (נמוכה, בינונית, או גבוהה), כך ש-agent בכל שלב אחד וכזה נעול-למטה בייצור יכול כל אחד להיות כוונן לאות שאתה רוצה. +אתה מחליט כמה קשה זה מחפש עם הגדרת **רגישות** יחידה (נמוכה, בינונית, או גבוהה), כך שאג'נט סטגינג רועם ואחד מנעול בייצור יכולים כל אחד להיות מכוונים לאות שאתה רוצה. ## כל המלצה מגיעה עם קבלות -אתה לעולם לא צריך לקחת ממצא על אמונה. כל המלצה מצטטת את ההפעלות המדויקות שהיא באה מהן ו-SQL שחשפה אותה, כך שתוכל לפתוח את הראיות ולאשר את הבעיה בקליק במקום להנדס הפוך תביעה. +אתה לא צריך לקחת ממצא בהשקעה. כל המלצה מצטטת את הסשנים המדוקדקים שהיא באה מהם ו-SQL שהעלה אותה, כך שתוכל לפתוח את הראיות ולאשר את הבעיה בלחיצה במקום לתהפוך הפוך. -כאשר ממצא הוא בנושא הדמי שהיה בורח, זה הולך צעד קדימה אחד וקישורים את האירועים הבודדים שהוא התאים. לחץ על אחד ואתה נוחת על רגע מדויק בהפעלה, כבר נבחר — לא לראש תמלול ארוך כדי לגלול דרכו. הקישור שם את האירוע; זה לעולם לא מעתיק את הסוד שזוהה לתוך הממצא, כך שקריאת ממצא היא לא מקום שני הסוד שלך נכתב. אם אירוע כבר לא שם כי ההפעלה עברה את חלון ההחזקה שלך, הדף אומר זאת בבירור במקום להשאיר אותך תוהה אם לחצת על הדבר הלא נכון. +כאשר ממצא הוא על זלילת אישור, זה הולך צעד אחד קדימה וקישורים לאירועים הפרטיים שהוא תאמו. לחץ על אחד והנך נוחת ברגע המדוקדק בסשן, כבר נבחר — לא החלק העליון של תמלול ארוך להתגלגל דרכו. הקישור שם את האירוע; זה לעולם לא מעתיק את הסוד המגולה לממצא, כך שקריאה של ממצא אינה מקום שני שהאישור שלך כתוב בו. אם אירוע כבר לא קיים כי הסשן עבר על חלון ההשמירה שלך, העמוד אומר זאת בצורה מובהקת במקום להשאיר אותך תוהה אם לחצת על הדבר הלא נכון. -זה גם מה שמחזיק audits כן. השרת בודק שכל הפעלה שצוטטה באמת קיימת ו**משליך כל המלצה שהראיות שלה לא מתקיימות**, כך ש審查 חוקר אבל לעולם לא ממציא. מה שנחת ברשימה שלך הוא אמיתי, שחזור, ומדורג לפי כמה זה חשוב, עם הניצחונות הגדולים בראש. +זה גם מה שמביא ביקורות הוגנות. השרת בודק שכל סשן מצוטט בעצם קיים **משלילות כל המלצה ששלה ראיות לא עומדות**, כך שהביקורת חוקרת אבל לעולם לא משכרת. מה שנוחת על הרשימה שלך הוא אמיתי, ניתן לשחזור, ומדורג לפי כמה זה משנה, עם הנצחונות הגדולים ביותר בחלק העליון. -## הפוך תיקון לתחזוקה +## הפוך תיקון לכביש רדוד -תיקון בעיה הוא רק חצי מהנצחון. החצי השני הוא הבטחה שזה לא יכול בשקט לחזור. כל ממצא נושא **קיצור דרך בקליק יחיד שממלא אזהרת הישנות**, prefilled עם טריגר התחלה הגיוני שאתה יכול להתאים. סגור את הממצא, חמוש את ההתראה, וביצעה שהדפוס הבא מופיע שוב אתה מקבל דף במקום לגלות מחדש את זה ב審查 עתידי. +תיקון בעיה הוא רק מחצית מהנצחון. המחצית האחרת היא הבטחה שהיא לא יכולה בשקט לחזור. כל ממצא נושא **קיצור דרך של לחיצה אחת שמעצב התראת הישנות**, מראש מלא עם טריגר התחלה הגיוני שאתה יכול לכוונן. סגור את הממצא, חמוש את ההתראה, והפעם הבאה שדפוס זה יופיע אתה מקבל דף במקום לגלות אותו מחדש בביקורת עתידית. -## איפה למצוא את זה +## היכן למצוא את זה -Audits חיים בלוח הבקרה ב **`//audits`** (צד לאנליזה ל審查). צפייה בריצות וממצאים צריכה **`audits:read`**; יצירה, עריכה, וטריאג'ות של audits צריך **`audits:write`**. קבע את ההיקף וקדנציה של審查, ואז לחץ על **Run now** כל פעם שאתה רוצה תוצאות מיד במקום להמתין לעבור המתוזמן הבא. +ביקורות חיות בלוח המחוונים ב-**`//audits`** (סרגל צד ל-*analyze* ל-*audits*). הצגת ריצות וממצאים צריך **`audits:read`**; יצירה, עריכה, וטריאז' ביקורות צריך **`audits:write`**. הגדר את ההיקף של ביקורת וקצב, אחר כך לחץ **Run now** בכל פעם שאתה רוצה תוצאות מיד במקום להמתין לעבור מתוזמן הבא. -## קשורה +## קשור -- [Alerts](/he/agenteye/alerts): קבל דף בנקודה הן סף שאתה כבר יודע על חצתה. -- [Evaluations](/he/agenteye/evaluations): קלע כל ריצה כך רגרסיות איכות על פני השטח בעצמם. -- [Error tracking](/he/agenteye/error-tracking): קבוצה ועקוב אחר השגיאות agents שלך לזרוק. -- [Incidents](/he/agenteye/incidents): עקוב אחרי בעיה審查 הופכת עד לתיקון שלה. \ No newline at end of file +- [התראות](/he/agenteye/alerts): קבל עמוד ברגע שסף שאתה כבר יודע על זה נחצה. +- [הערכות](/he/agenteye/evaluations): ניקוד כל ריצה כך שרגרסיות איכות משטח בעצמן. +- [עקבוב שגיאות](/he/agenteye/error-tracking): קבוצה ועקוב את השגיאות שהאג'נטים שלך זורקים. +- [תקריות](/he/agenteye/incidents): עקוב אחרי בעיה שביקורת חוקרת דרך הצעד שלה לתיקון. \ No newline at end of file diff --git a/docs/he/agenteye/cli-and-agents.mdx b/docs/he/agenteye/cli-and-agents.mdx index 1da70ee1..7c038bee 100644 --- a/docs/he/agenteye/cli-and-agents.mdx +++ b/docs/he/agenteye/cli-and-agents.mdx @@ -1,10 +1,11 @@ --- +--- title: "CLI" -description: "כל הפריסה של Failproof AI Observability שלך, במרחק פקודה אחת." +description: "כל פריסת ה-Failproof AI Observability שלך, במרחק פקודה אחת." --- -כל הפריסה של Failproof AI Observability שלך, במרחק פקודה אחת. בדוק את הייצור, צור מפתח API, או אשר תקלה מבלי לעזוב את הטרמינל שלך, ואז כתוב סקריפט לכל זה ל-CI, או תן לסוכן קוד לעשות זאת בעברית פשוטה. +כל פריסת ה-Failproof AI Observability שלך, במרחק פקודה אחת. בדוק את ייצור, צור מפתח API, או הודע על תקלה ללא עזיבת הטרמינל שלך, ואז תסקריפט כל דבר לתוך CI, או תן לסוכן קוד לעשות זאת עבורך בשפה טבעית. ```bash pipx install agenteye @@ -12,18 +13,18 @@ agenteye login --email you@example.com # a 6-digit code lands in your inbox agenteye --json sessions --since 24h # every agent run from the last day, newest first ``` -*ה-CLI של `agenteye` מדבר עם הדשבורד שלך. זהו כלי שונה מהאספן, שמשדר אירועים לשרת.* +*ה-CLI של `agenteye` מדבר עם הדוחמ שלך. זהו כלי שונה מהקולקטור, המשדר אירועים לשרת.* ## כל הפריסה שלך, במרחק פקודה אחת -הפסק לדלג בין כרטיסיות כדי לענות על שאלה מהירה. ה-CLI של `agenteye` קורא את הנתונים שלך ומנהל את הארגון שלך מקובץ בינארי אחד, כך שבדיקה שפעם הייתה דורשת לחיצה דרך הדשבורד הופכת לשורה אחת שאתה יכול להפעיל מחדש, ליצור כינוי, או להדביק לתוך runbook. אתה מקבל ארבע ממשקים: +תעזוב את הקפיצה בין כרטיסיות כדי לענות על שאלה מהירה. ה-CLI של `agenteye` קורא את הנתונים שלך ומנהל את הארגון שלך מקובץ בינארי יחיד, כך שבדיקה שעולה הדומה ללחיצה דרך הדוח הופכת לשורה אחת שתוכל להריץ מחדש, להגדיר כשם קצר, או להדביק לתוך runbook. אתה מקבל ארבע ממשקים: -- **קרא את הנתונים שלך:** `sessions`, `events`, `evals`, ו-`errors`, מסוננים לפי זמן, סוכן וסביבה. +- **קרא את הנתונים שלך:** `sessions`, `events`, `evals`, ו-`errors`, מסוננות לפי זמן, סוכן וסביבה. - **נהל את הארגון שלך:** `keys`, `users`, `settings`, `alerts`, ו-`incidents`. -- **הרץ ניתוח:** SQL שמור בתוספת מריץ `query` אד-הוק על נתוני האירוע שלך. -- **שאל את העוזר:** `agent ask` מגיע לאותו אנליסט בקריאה בלבד שאתה משוחח איתו בדשבורד. +- **הרץ ניתוח:** SQL שמור בתוספת `query` ריצה אד-הוק על נתוני האירועים שלך. +- **שאל את העוזר:** `agent ask` מגיע לאותו אנליסט קריאה בלבד שאתה משוחח איתו בדוח. -התקן אותו פעם אחת עם `pipx`, היכנס עם קוד בן 6 ספרות שנשלח בדוא"ל, ואתה מוכן. ההפעלה נמשכת כיום; הרץ את `agenteye login` מחדש כאשר היא תפוג. השתמש בו כדי לבדוק את הייצור, לספק מפתח, או לטפל בתקלה שזורקת, הכל ללא פתיחת דפדפן: +התקן פעם אחת עם `pipx`, היכנס עם קוד 6 ספרות שהתקבל בדוא"ל, ואתה מוכן. הסדרה נמשכת בערך יום אחד; הרץ מחדש `agenteye login` כשהוא פג. הגע בו כדי לבדוק ייצור, לספק מפתח, או לפתח תקלה שנדלקת, הכל ללא פתיחת דפדפן: ```bash agenteye errors --since 24h --aggregate # what is breaking, grouped by error type @@ -31,25 +32,25 @@ agenteye incidents list --state firing # what is on fire right now agenteye keys create ci --add events:add # a key that can only push events, secret shown once ``` -הרגל אחד שכדאי לדעת: אפשרויות גלובליות כמו `--json` מופיעות לפני הפקודה. `agenteye --json sessions` נכון; `agenteye sessions --json` לא. +הרגל אחד שכדאי לדעת: אפשרויות גלובליות כמו `--json` הולכות לפני הפקודה. `agenteye --json sessions` נכון; `agenteye sessions --json` לא. -## כתוב סקריפט, חברו ל-CI +## תסקריפט זה, חוט זה לתוך CI -כל פקודה מקבלת `--json`, וזה משנה הכל. JSON נקי עובר ל-stdout בעוד מצב ואזהרות לבני אדם עוברות ל-stderr, כך שתיעוד `--json` מופעל ישר ל-`jq` ללא שורה תועה לפירוק. זה מה שהופך את ה-CLI לטוב באותה מידה עבורך בהנחיה ועבור סוכן קוד שמנתח פלט: +כל פקודה לוקחת `--json`, וזה משנה הכל. JSON נקי עובר ל-stdout בעוד מצב אנושי וקנוניות עוברות ל-stderr, כך שכיבוש `--json` מחובר ישירות ל-`jq` ללא שורה סוטה להסרה. זה מה שהופך את CLI לטוב בדיוק עבורך בשדכה ולסוכן קוד המנתח פלט: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -זה בנוי להפעלה ללא השגחה. בקשות אישור דלג אוטומטי כאשר אין טרמינל מצורף, כך שלא משהו תלוי בצינור, וכל פקודה מחזירה קוד יציאה משמעותי: `0` הצלחה, `4` לא מחובר, `5` חסר הרשאה (ההודעה שמה שם, למשל `alerts:write`), `3` דשבורד לא ניתן להשגה. סקריפט יכול להתחלק על `4` כדי לאמת מחדש או על `5` כדי לומר לך בדיוק מה לבקש ממנהל. +זה בנוי להריץ ללא השגחה. נושאי אישור דילוגים אוטומטיים כשאין טרמינל מצורף, כך שלא חוק כלום בצינור, וכל פקודה מחזירה קוד יציאה משמעותי: `0` הצלחה, `4` לא היכנס, `5` חסרה הרשאה (ההודעה שמה את שמה, לדוגמה `alerts:write`), `3` דוח לא זמין. סקריפט יכול לשנות ענף על `4` להאמתה מחדש או `5` כדי לומר לך בדיוק מה לבקש ממנהל, במקום להיכשל עיוור. -## תן לסוכן קוד להנהיג אותו בעברית פשוטה +## תן לסוכן קוד להנהיג זה בשפה טבעית -עדיף עדיין, לא צריך לזכור את דגלים אלה כלל. **ה-CLI skill** הוא תיקייה Skill סוכן קטנה בשם `agenteye-cli` שמלמדת סוכן קוד כמו Claude Code או Codex להנהיג את ה-CLI מבקשות בעברית פשוטה. שאל "יש משהו שבור היום?" והסוכן בוחר את הפקודה, מריץ אותה כמוך, וענה בפרוזה. +טוב עדיין, לא צריך לזכור כל אחד מהדגלונים הללו בכלל. **CLI skill** הוא תיקייה קטנה Agent Skill בשם `agenteye-cli` המלמדת סוכן קוד כמו Claude Code או Codex להנהיג את CLI מבקשות בשפה אנגלית. שאל "האם משהו שבור היום?" וה-agent בוחר את הפקודה, מריץ אותה כאתה, וענה בפרוזה. -עבור Claude Code, שחרר את תיקיית `agenteye-cli` ל-`~/.claude/skills/` והיא מגלה אוטומטי. Failproof AI Observability מספק את התיקייה; אין שום דבר נוסף להתקנה, מכיוון שזה רק מנהיג את ה-CLI שכבר התקנת. היכנס בעצמך תחילה: הskill לא יכול להשלים את הכניסה לקוד דוא"ל עבורך. +עבור Claude Code, הסר את תיקייה `agenteye-cli` לתוך `~/.claude/skills/` והיא מגוגלת אוטומטית. Failproof AI Observability מספק את התיקייה; אין התקנה נוספת, כי היא רק מנהיגה את CLI שכבר התקנת. היכנס בעצמך קודם: ה-skill לא יכול להשלים את ההיכנסה בקוד דוא"ל עבורך. -מכיוון שהסוכן מנהיג את ה-CLI כמוך, הוא יכול לעשות הכל שההתחברות שלך מאפשרת, קריאה וכתיבה כאחד: צור מפתחות, שנה הגדרות, פתור תקלות. בקשת "האם אתה בטוח?" ב-CLI לא מתחדשת עבור סוכן, כך שהskill כתוב כדי להצהיר על הפקודה המדויקת ולהמתין לאישור שלך לפני כל שינוי. אתה שלב האישור. +מכיוון שה-agent מריץ את CLI כאתה, הוא יכול לעשות הכל שההיכנסה שלך מרשה, קוראים וכותבים כאחד: יצור מפתחות, שנה הגדרות, פתור תקלות. ההודעה "האם אתה בטוח?" של CLI לא שורפת עבור סוכן, כך שה-skill כתוב לאמור את הפקודה המדויקת וחכה לאישור שלך לפני כל שינוי. אתה הצעד האישור. ```text you Why did session run-001 fail? @@ -58,7 +59,7 @@ agent Running: agenteye --json events --session-id run-001 --all The checkout-agent hit a TimeoutError on its third tool call. ``` -הקריאות נשארות מיידיות, וכל כתיבה עוצרת עבורך: +הקריאות נשארות מיידיות, וכל כתיבה מושהה עבורך: ```text you Give CI a key that can only push events. @@ -75,6 +76,6 @@ agent Done. Key "ci" created with events:add only. The secret is shown once, so ## קשור - [CLI reference](/he/agenteye/cli): כל פקודה, דגל וצורת JSON. -- [CLI recipes for agents](/he/agenteye/cli-recipes): עותקים והדבקות של דפוסי `jq` וטיפול קוד יציאה. -- [CLI agent skill](/he/agenteye/cli-skill): התקן והרץ את ה-`agenteye-cli` skill. -- [AI assistant](/he/agenteye/assistant): האנליסט בדשבורד שה-`agent ask` מדבר אליו. \ No newline at end of file +- [CLI recipes for agents](/he/agenteye/cli-recipes): `jq` דפוסים ו-exit-code עיבוד. +- [CLI agent skill](/he/agenteye/cli-skill): התקן והרץ את skill `agenteye-cli`. +- [AI assistant](/he/agenteye/assistant): האנליסט בדוח שה-`agent ask` מדבר אתו. \ No newline at end of file diff --git a/docs/he/agenteye/cli-recipes.mdx b/docs/he/agenteye/cli-recipes.mdx index b78709a1..03b7d4a1 100644 --- a/docs/he/agenteye/cli-recipes.mdx +++ b/docs/he/agenteye/cli-recipes.mdx @@ -1,30 +1,30 @@ --- -title: "מתכונים CLI לסוכנים" -description: "דוגמאות query וקומנדות jq שהניתנות להעתקה המשתנות נתוני session, event וערכת ערכים לאומטומציה על ידי סקריפט או סוכן קוד." +--- +title: "מתכונים CLI לאג'נטים" +description: "דוגמאות query וממשקי jq שהניתנים להעתקה המומרים נתוני סשן, אירוע והערכה לכל דבר שסקריפט או אג'נט קוד יכול להפוך לאוטומציה." --- +משוך נתוני סשן, אירוע והערכה (והפעל הערכות מחדש) ישירות מתוך סקריפט או אג'נט קוד, עם JSON נקי ב-stdout שמופעל ישירות ל-`jq`. המתכונים הללו הופכים נתוני Failproof AI Observability למשהו שמשתמש בטרמינל או אג'נט קוד AI (Claude Code, Cursor) יכול לשאול שאלות עליהם ולהפוך לאוטומציה, ללא לחיצה דרך הדאשבורד. -משוך נתוני session, event וערכת ערכים (והפעל הערכות מחדש) ישירות מסקריפט או סוכן קוד, עם JSON נקי ב-stdout שמופנה ישירות ל-`jq`. המתכונים האלה משנים נתונים של Failproof AI Observability למשהו שמשתמש בטרמינל או סוכן קוד AI (Claude Code, Cursor) יכול לשאול וליישם אוטומציה, ללא לחיצה דרך ה-dashboard. - -ההוראות למטה מוכנות להעתקה ישירה לממשק הפקודה של Failproof AI Observability (`agenteye`). להתקנה, אימות וקائמת האפשרויות המלאה ראה [CLI](/he/agenteye/cli); הרץ `agenteye -h` או `agenteye -h` לעזרה המובנית. +הדוגמאות להלן מוכנות להעתקה עבור Failproof AI Observability CLI (`agenteye`). לקבלת התקנה, אימות והרשימה המלאה של אפשרויות ראה [CLI](/he/agenteye/cli); הרץ `agenteye -h` או `agenteye -h` לעזרה מובנית. -## כללים זהב +## הכללים הזהובים -1. **אפשרויות גלובליות קודמות לפקודה.** `agenteye --json sessions` נכון; `agenteye sessions --json` אינו נכון. הגלובליים הם `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **העבור `--json` בכל פעם שאתה מנתח פלט.** נתונים עוברים ל-**stdout** כ-JSON; סטטוס אנושי וטעויות עוברות ל-**stderr**, כך ש-stdout נשאר נקי לשימוש ב-`jq`. -3. **ענף על קוד היציאה, לא על טקסט stderr**: `0` בסדר · `1` שגיאה בלתי צפויה · `2` ארגומנטים שגויים · `3` אי אפשר להגיע ל-dashboard · `4` לא מחובר או שתוקף פג · `5` הרשאה חסרה · `6` משאב לא נמצא. -4. **גלה עם `-h`.** כל פקודה מתעדת את המסננים שלה, פורמטי ערכים וצורת JSON. +1. **אפשרויות גלובליות חייבות להופיע *לפני* הפקודה.** `agenteye --json sessions` נכון; `agenteye sessions --json` אינו נכון. הגלובליות הן `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **העבר `--json` בכל פעם שאתה מפענח פלט.** נתונים עוברים ל-**stdout** כ-JSON; מצב אנושי ושגיאות עוברים ל-**stderr**, כך ש-stdout נשאר נקי לצינור ל-`jq`. +3. **הסתמך על קוד היציאה, לא על טקסט stderr**: `0` בסדר · `1` שגיאה בלתי צפויה · `2` ארגומנטים שגויים · `3` לא יכול להגיע לדאשבורד · `4` לא מחובר או פג תוקף · `5` הרשאה חסרה · `6` משאב לא נמצא. +4. **גלה עם `-h`.** כל פקודה מתעדת את המסננים שלה, פורמטי ערך וצורת JSON. -## התקנה חד פעמית +## הגדרה חד-פעמית ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # כדי שלא תחזור על --base-url -agenteye login --email you@example.com # הדבק את הקוד שנשלח בדוא"ל; תוקף ~24h +agenteye login --email you@example.com # הדבק את הקוד שהתקבל בדוא"ל; תוקף ~24 שעות ``` -## אמת אימות לפני ביצוע עבודה +## אמת את האימות לפני ביצוע עבודה -`whoami` לעולם לא משגה בהפסדה או אימות שתוקפו פג; במקום זאת הוא מדווח `logged_in:false`, כך שסוכן יכול לבדוק את מצב האימות בבטחה. (זה עדיין יכול לצאת עם קוד שאינו אפס אם לא הוגדרה כתובת בסיסית או ה-dashboard אינו נגיש.) +`whoami` לעולם לא מחזיר שגיאה בסשן חסר או פג תוקף; זה דיווח `logged_in:false` במקום זאת, כך שאג'נט יכול לבדוק את מצב האימות בבטחה. (זה עדיין יכול לצאת עם קוד שאינו אפס אם לא הוגדרה כתובת בסיס או אם הדאשבורד אינו נגיש.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,98 +32,98 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## מצא sessions שנכשלו או בעלי ניקוד נמוך +## מצא סשנים בעלי ביצועים נמוכים או סשנים שנכשלו ```bash -# sessions ב-24 שעות האחרונות שערכת הערכים שלהם היתה בשגיאה +# סשנים ב-24 השעות האחרונות שהערכתם הייתה בשגיאה agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# evaluations בניקוד <= 0.5 ב-helpfulness, לסוכן אחד +# הערכות שנותנות ניקוד <= 0.5 בעזריות, עבור אג'נט אחד agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -סינון ניקוד חי ב-**`evals`**, לא ב-`sessions`. `--score KEY:MIN..MAX` חוזר על עצמו ומשולב עם AND; כל גבול הוא אופציונלי (`..0.5` פירושו ≤ 0.5, `0.9..` פירושו ≥ 0.9). אתה יכול להעביר עד 20 מסננים ניקוד לכל בקשה; יותר מזה מחזיר HTTP 400. `sessions` חולק את המסננים `--env`, `--status`, `--agent-id`, `--session-id` וטווח הזמן עם `evals`, אך אין לו `--score`. +סינון הציון חי על **`evals`**, לא `sessions`. `--score KEY:MIN..MAX` ניתן לחזור עליו ומשולב עם AND; כל גבול הוא אופציונלי (`..0.5` פירושו ≤ 0.5, `0.9..` פירושו ≥ 0.9). אתה יכול להעביר עד 20 מסנני ציון לבקשה; יותר מחזיר HTTP 400. `sessions` משתף את `--env`, `--status`, `--agent-id`, `--session-id`, ומסנני טווח הזמן עם `evals`, אך אין `--score`. -## קרא session אחד מהסוף לסוף +## קרא סשן מתחילה לסוף -אין פקודת `session show` יחידה. שלב את עקבות ה-event עם ערכת הערכים של ה-session: +אין פקודת `session show` יחידה. שלב את שביל האירוע עם הערכת הסשן: ```bash -# ערכת הערכים האחרונה של ה-session (סטטוס + ניקוד) +# ההערכה האחרונה של הסשן (סטטוס + ניקוד) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# כל event בריצה (הגבר את --limit לסריקה מלאה) +# כל אירוע בהריצה (הגדל --limit לסריקה מלאה) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# רק הקריאות לכלים ב-session (--full נדרש כדי לקבל את ה-payload הגולמי) +# רק קריאות הכלי בסשן (--full נדרש כדי לקבל את הפיילוד הגולמי) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **הערה:** כברירת מחדל, `events` קורא feed מהיר וללא payload. כל event נושא `summary` המחושב בשרת בשורה אחת בתוספת דגלים כמו `is_error` וספירת token, אך `payload` חוזר כ-`{}`. כדי למשוך את ה-payload הגולמי, הוסף `--full` (או `--fields payload`). ה-feed המלא איטי בקנה מידה, אז שמור עליו מוגבל: זווג `--full` עם `--session-id` יחיד. +> **הערה:** כברירת מחדל, `events` קורא הזנה מהירה וללא פיילוד. כל אירוע נושא `summary` חד-שורתי שחושב בשרת בתוספת דגלים כמו `is_error` וספירת token, אך `payload` חוזר כ-`{}`. כדי למשוך את הפיילוד הגולמי, הוסף `--full` (או `--fields payload`). ההזנה המלאה איטית בקנה מידה, אז שמור עליה בגבול: צמד `--full` עם יחיד `--session-id`. -## שלוף הכל (עמודים) +## משוך הכל (עימוד) -התוצאות הן חדשה-ראשית ומעמוד-ושרשור. +התוצאות הן החדשות ביותר קודם ומעימוד סמן. ```bash -# היא אחת: משוך עד 500 שורות בעמודים של 200 שורה +# shot אחד: משוך עד 500 שורות בעמודים של 200 שורות agenteye --json events --session-id run-001 --limit 500 --all > events.json -# עמודים ידניים: הזן את next_cursor חזרה +# עימוד ידני: החזר סמן הבא page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## הצמק את הפלט עם --fields +## צמצם את הפלט עם --fields -הגבל את המפתחות (גם בטבלה וב-`--json`) כדי להפחית מה שסוכן חייב לקרוא. +הגבל את המפתחות (בטבלה וב-`--json`) כדי להפחית מה שאג'נט חייב לקרוא. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -שמות שדות לא ידוע נדחים (יציאה `2`) עם הרשימה התקפה, דרך זולה לגלות שמות שדות. +שמות שדות לא ידועים נדחים (יציאה `2`) עם הרשימה התקפה, דרך זולה לגילוי שמות שדות. ## גלה ערכי מסנן תקפים ```bash -agenteye --json list envs | jq -r '.values[]' # ערכים לעבור --env -agenteye --json list tools | jq -r '.values[]' # שמות כלים; גם agents, models, event_types, ... -agenteye --json list score_filters | jq -r '.values[]' # KEY תקף עבור --score KEY:MIN..MAX +agenteye --json list envs | jq -r '.values[]' # ערכים ל-–env +agenteye --json list tools | jq -r '.values[]' # שמות כלים; גם אג'נטים, מודלים, event_types, … +agenteye --json list score_filters | jq -r '.values[]' # KEY תקף ל-–score KEY:MIN..MAX ``` -## בחר את ה-org שלך (מרובה דיירים) +## בחר את הארגון שלך (ריבוי טנאנט) -אם אתה שייך ליותר מ-org אחד, בחר את הדייר הפעיל בעת התחברות (זה נשמר): +אם אתה שייך ליותר מארגון אחד, בחר את הטנאנט הפעיל בעת התחברות (הוא נשמר): ```bash -agenteye login --org acme --email you@corp.com # הגדר את הדייר באותו שלב כמו התחברות +agenteye login --org acme --email you@corp.com # הגדר את הטנאנט באותו שלב כמו התחברות agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # בחזוק לפקודה אחת +agenteye --org globex --json sessions --since 24h # בטל עבור פקודה אחת ``` -התחברות מרובת-org ללא `--org` יוצאת עם קוד שאינו אפס ותדפיס את ה-orgs לבחירה. +התחברות ריבוי-ארגון ללא `--org` יוצאת עם קוד שאינו אפס ומדפיסה את הארגונים לבחירה. -## הפקד מפתח API לעבור ה-SDK/collector +## תן רישיון למפתח API עבור SDK/collector ```bash -# הסוד מודפס פעם אחת, עם --json זה ה-.key field +# הסוד מודפס פעם אחת, עם –json זה השדה .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # סובב; agenteye keys disable ci-bot --yes להשבת +agenteye keys regenerate ci-bot --yes # סובב; agenteye keys disable ci-bot --yes לביטול ``` ## הרץ שאילתה שמורה או ad-hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # שאילתה שמורה + $1 מיקומי +agenteye --json query run errs --arg prod | jq '.rows' # שאילתה שמורה + $1 עמדתי ``` -## בחן תקרית ללא אינטראקציה +## בדוק אירוע חירום ללא אינטראקציה ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **הערה:** Mutations מדלגות באופן אוטומטי על ההנחיה לאישור תחת `--json` או כאשר stdin אינו TTY, כך שסוכנים לעולם לא תלויים; העבור `--yes`/`-y` כדי לדלג עליו במפורש במקום אחר. +> **הערה:** מוטציות דילוג אוטומטית של הנושא אישור שלהם תחת `--json` או כאשר stdin אינו TTY, כך שאג'נטים לעולם לא תלויים; העבר `--yes`/`-y` כדי לדלג עליו במפורש במקום אחר. ## טיפול בקוד יציאה בסקריפט @@ -162,18 +162,18 @@ esac | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (כל) | אובייקט המשאב, או `{"deleted": true, "id"}` למחיקות | +| יצירה/עדכון/מחיקה (כל) | אובייקט המשאב, או `{"deleted": true, "id"}` למחיקות | | כישלון (כל, עם `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` ב-stdout | -- כל פריט **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. שים לב ש-`payload` הוא `{}` אלא אם אתה מבקש את ה-feed המלא עם `--full` (או `--fields payload`). -- כל פריט **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- כל פריט **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- כל פריט **אירוע** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. שים לב ש-`payload` הוא `{}` אלא אם תבקש את ההזנה המלאה עם `--full` (או `--fields payload`). +- כל פריט **הערכה** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- כל פריט **סשן** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -ה-`--fields` של כל פקודה מקבל בדיוק שמות שדות של הפריט שלה. הקבוצה שונה בין `sessions` ו-`evals`, כך ששם תקף לאחד אולי יידחה על ידי השני. +`--fields` של כל פקודה מקבל בדיוק שמות שדות של הפריט שלה. הקבוצה שונה בין `sessions` ו-`evals`, כך ששם תקף לאחד עשוי להידחות על ידי השני. ## שלבים הבאים -- [CLI](/he/agenteye/cli): התקנה, אימות וההתייחסות המלאה לאפשרויות לכל פקודה. -- [CLI agent skill](/he/agenteye/cli-skill): אפס את המתכונים האלה כמו מיומנות שסוכן הקוד שלך יכול לטעון. -- [API keys](/he/agenteye/api-keys): צור ותחום את המפתחות שעם ה-CLI, SDK והאספן מתאמתים. -- [Python SDK](/he/agenteye/python-sdk): שלח events ל-Failproof AI Observability כדי שיהיו נתונים כדי שהמתכונים האלה יכלו לשאול. \ No newline at end of file +- [CLI](/he/agenteye/cli): התקנה, אימות, והפניה אפשרויות מלאה לכל פקודה. +- [CLI agent skill](/he/agenteye/cli-skill): חבור מתכונים אלה כמו מיומנות שאג'נט הקוד שלך יכול לטעון. +- [API keys](/he/agenteye/api-keys): יצור ופקד מפתחות שהCLI, SDK וcollector מאמתים עם. +- [Python SDK](/he/agenteye/python-sdk): שלח אירועים ל-Failproof AI Observability כדי שיהיו נתונים למתכונים אלה לשאול. \ No newline at end of file diff --git a/docs/he/agenteye/cli-skill.mdx b/docs/he/agenteye/cli-skill.mdx index e645f111..52a7f8cf 100644 --- a/docs/he/agenteye/cli-skill.mdx +++ b/docs/he/agenteye/cli-skill.mdx @@ -1,68 +1,66 @@ --- +title: "מיומנות Failproof AI Observability CLI Agent" +description: "שאל את סוכן הקוד שלך \"האם משהו השתבר היום?\" והנח לו לענות מנתוני Failproof AI Observability החיים שלך, ללא צורך לזכור פקודות." --- -title: "כישורון CLI Observability של Failproof AI" -description: "שאל את סוכן הקוד שלך \"האם משהו שבור היום?\" והנח לו לענות מנתוני Failproof AI Observability השידוריים שלך, ללא צורך לשנן פקודות." ---- - -שאל את סוכן הקוד שלך *"האם משהו שבור היום?"* והנח לו לענות מנתוני Failproof AI Observability השידוריים שלך, ללא צורך לשנן פקודות. **כישורון CLI Observability של Failproof AI** (`agenteye-cli`) הוא *Agent Skill*: תיקייה קטנה של הוראות שסוכן קוד כגון Claude Code או Codex טוען לפי הצורך. היא מלמדת את הסוכן להפעיל את התפוצה של Observability שלך דרך ה-[`agenteye` CLI](/he/agenteye/cli) מבקשות בעברית רגילה כמו *"תן ל-CI מפתח שיכול רק לדחוף אירועים"* או *"אשר את האירוע הפועל והקצה אותו אלי."* +שאל את סוכן הקוד שלך *"האם משהו השתבר היום?"* והנח לו לענות מנתוני Failproof AI Observability החיים שלך, ללא צורך לזכור פקודות. **מיומנות Failproof AI Observability CLI** (`agenteye-cli`) היא *Agent Skill*: תיקייה קטנה של הוראות שסוכן קוד כמו Claude Code או Codex טוען לפי הביקוש. היא מלמדת את הסוכן להפעיל את הפריסה של Observability שלך דרך [CLI של `agenteye`](/he/agenteye/cli) מבקשות באנגלית פשוטה כמו *"תן ל-CI מפתח שיכול רק לדחוף אירועים"* או *"אשר את האירוע הירי והקצה אותו אלי."* -זה **לא** שירות או בינארי נפרד; אין כלום לפרוס. זה עובד על גבי ה-CLI שכבר התקנת: הסוכן שדרג אל `agenteye --json …`, מנתח את ה-JSON הנקי, והשיב לך בטקסט. כל דבר שהוא יכול לעשות, אתה יכול לעשות בעצמך בהקלדת אותן פקודות. +זה **לא** שירות או בינארי נפרד; אין שום דבר לפרוס. הוא עובד על גבי CLI שכבר התקנת: הסוכן משדר ל-`agenteye --json …`, ניתח את ה-JSON הנקי, וענה לך בטקסט. כל מה שהוא יכול לעשות, אתה יכול לעשות בעצמך על ידי הקלדת אותן פקודות. --- -## איך זה קשור לממשקים אחרים של Failproof AI Observability +## כיצד זה קשור לממשקי Failproof AI Observability האחרים -Failproof AI Observability נותן לך ארבע דרכים להגיע לאותם נתונים ובקרות. הם משלימים זה את זה: +Failproof AI Observability נותן לך ארבע דרכים להגיע לאותם נתונים וביקורות. הם משלימים זה את זה: -| ממשק | מה זה | איפה זה רץ | הגש אליו כאשר | +| ממשק | מה זה | איפה זה עובד | בחר בו כאשר | |---|---|---|---| -| **[CLI](/he/agenteye/cli)** | ההתייחסות לפקודה/דגל עבור `agenteye` | הטרמינל שלך | אתה רוצה להריץ או לתסריט פקודה ספציפית | -| **[CLI recipes](/he/agenteye/cli-recipes)** | דוגמות `jq`/pipeline להעתקה-הדבקה | הטרמינל / סקריפטים שלך | אתה מחברת את ה-CLI לאוטומציה | -| **כישורון CLI** (מסמך זה) | דלת חזיתית בשפה טבעית ל-CLI | סוכן הקוד שלך, בתחנת העבודה שלך | אתה רוצה לשאול ולתת לסוכן לבחור את הפקודה | -| **[כישורון Evaluator](/he/agenteye/evaluator-skill)** | כישורון אחות שתכנן ובונה את שירות הניקוד שלך | סוכן הקוד שלך, בתחנת העבודה שלך | אתה רוצה **לייצר** ניקוד eval במקום לקרוא אותו | -| **[כישורון Python SDK](/he/agenteye/python-sdk-skill)** | כישורון אחות שמכשיר את הסוכן שלך כך שהוא פולט טלמטריה כלל | סוכן הקוד שלך, בתחנת העבודה שלך | אתה רוצה שהסוכן שלך **ייצור** את האירועים שכישורון זה קורא | -| **[עוזר AI בתוך הלוח](/he/agenteye/assistant)** | צ'אט משובץ בלוח המחוונים | צד שרת (בלוח המחוונים) | אתה רוצה שאלות ותשובות בתוך לוח המחוונים על הנתונים שלך | +| **[CLI](/he/agenteye/cli)** | הייחוס לפקודה/דגל עבור `agenteye` | הטרמינל שלך | אתה רוצה להפעיל או לכתוב סקריפט לפקודה ספציפית | +| **[CLI recipes](/he/agenteye/cli-recipes)** | דפוסי `jq`/צינור להעתקה-הדבקה | הטרמינל שלך / סקריפטים | אתה קושר את CLI לאוטומציה | +| **CLI skill** (מסמך זה) | דלת כניסה בשפה טבעית ל-CLI | סוכן הקוד שלך, בתחנת העבודה שלך | אתה רוצה *פשוט לשאול* והנח לסוכן לבחור בפקודה | +| **[מיומנות Evaluator](/he/agenteye/evaluator-skill)** | מיומנות אחות שמעצבת ובונה את שירות הדירוג שלך | סוכן הקוד שלך, בתחנת העבודה שלך | אתה רוצה *להפיק* ניקוד eval במקום לקרוא אותו | +| **[מיומנות Python SDK](/he/agenteye/python-sdk-skill)** | מיומנות אחות שמעצבת את הסוכן שלך כך שהוא פולט טלמטריה בכלל | סוכן הקוד שלך, בתחנת העבודה שלך | אתה רוצה שהסוכן שלך *יפיק* את האירועים שמיומנות זו קוראת | +| **[עוזר AI בדוחף](/he/agenteye/assistant)** | צ'אט משובץ בדוחף | שרת-צד (בדוחף) | אתה רוצה Q&A בדוחף על הנתונים שלך | -לכישורון עצמו אין הרשאות שלו; הוא רק הופך את המילים שלך לקריאות CLI שרצות כך: +למיומנות עצמה אין הרשאות משלה; היא פשוט הופכת את המילים שלך לקריאות CLI שפועלות כאתה: ```mermaid flowchart TD - YOU["אתה: 'אשר את האירוע הפועל'"] --> AGENT["סוכן קוד (Claude Code / Codex)
טוען את כישורון agenteye-cli"] + YOU["אתה: 'אשר את האירוע הירי'"] --> AGENT["סוכן קוד (Claude Code / Codex)
טוען את מיומנות agenteye-cli"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|הפעלת CLI המאומתת שלך| API["API לוח Observability"] + CLI -->|ההפעלה של CLI המאומתת שלך| API["API של דוחף Observability"] ``` -### לעומת עוזר ה-AI בתוך הלוח: הבחנה חשובה +### לעומת עוזר ה-AI בדוחף: הבדל חשוב -אלה שני כלים שונים עם טווחי פיצוץ שונים מאוד: +אלו שני כלים שונים עם רדיוסי התפוצה שונים מאוד: -- **עוזר ה-AI בתוך הלוח** ([AI assistant](/he/agenteye/assistant)) הוא צ'אט משובץ בלוח המחוונים, בגיבוי שירות הסוכן. זה **קריאה בלבד בתוספת כתיבה שאושרה**: הוא יכול לטיוטה שאלות שמורות ולוחות, אך כל כתיבה עוצרת לאישור ההקלקה המפורש שלך, והוא לעולם לא מוחק. זה נשער על ידי ההרשאה `agent:use` ורק אי פעם רואה נתונים עבור הארגון שאתה צופה בו. -- **כישורון CLI** רץ על *תחנת העבודה שלך* בתוך *סוכן הקוד שלך* ומנהל את `agenteye` CLI כ-**אתה**. הוא יכול לבצע את **המשטח המלא של ה-CLI, כולל מוטציות** (יצור/סיבוב/הפסקה של מפתחות API, שנה הגדרות ארגון, פתור אירועים, מחק שאלות שמורות), מוגבל רק בהרשאות ההתחברות שלך ל-CLI. התייחס אליו בדיוק כפי שהיית מתייחס להרצת אותן פקודות ביד. +- **עוזר ה-AI בדוחף** ([עוזר AI](/he/agenteye/assistant)) הוא צ'אט משובץ בדוחף, מגובה על ידי שירות הסוכן. הוא **קריאה בלבד בתוספת כתיבה כשאישור:** הוא יכול לעצב שאילתות שמורות ודוחפים, אך כל כתיבה מושהית לאישור הלחיצה המפורש שלך, וזה לעולם לא מוחק. הוא מגודר על ידי הרשאת `agent:use` ורואה רק נתונים עבור הארגון שאתה צופה. +- **מיומנות CLI** עובדת בתחנת העבודה *שלך* בתוך סוכן הקוד *שלך* ומניעה את CLI של `agenteye` כ**אתה**. היא יכולה לבצע את **משטח המלא של CLI, כולל מוטציות** (יצור/סיבוב/השבתת מפתחות API, שינוי הגדרות ארגון, פתרון אירועים, מחיקת שאילתות שמורות), מוגבלת רק על ידי הרשאות של כניסתך ל-CLI. התייחס אליה בדיוק כמו שהיית מתייחס להפעלת אותן פקודות ביד. --- -## דרישות ראשוניות +## דרישות מוקדמות -1. **ה-`agenteye` CLI מותקן** ו-`PATH` (ראה את התייחסות [CLI](/he/agenteye/cli): `pipx install agenteye`). -2. **כתובת ה-URL של לוח המחוונים שלך** מוגדרת (`AGENTEYE_DASHBOARD_URL`, או הסוכן עובר `--base-url`). -3. **הפעלה שנכנסה**: הרץ `agenteye login` בעצמך קודם לכן. הכישורון **לא יכול** להשלים את הכניסה לקוד חד-פעמי בדוא״ל עבורך; זה אמר לך להרוץ `agenteye login` אם ההפעלה חסרה או פג תוקף (קוד יציאת CLI `4`). +1. **`agenteye` CLI מותקן** וב-`PATH` (ראה ייחוס [CLI](/he/agenteye/cli): `pipx install agenteye`). +2. **כתובת ה-URL של הדוחף שלך** מוגדרת (`AGENTEYE_DASHBOARD_URL`, או הסוכן מעביר `--base-url`). +3. **הפעלה מחובר:** הרץ `agenteye login` בעצמך קודם. המיומנות **לא יכולה** להשלים את כניסת קוד חד-פעמי בדוא"ל עבורך; היא תגיד לך להריץ `agenteye login` אם ההפעלה חסרה או פגה (קוד יציאה של CLI `4`). --- ## איפה להשיג את זה -הכישורון פורסם באוסף הכישורונים הציבורי של Failproof AI: +המיומנות פורסמה באוסף המיומנויות הציבורי של Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -שום דבר בו לא משוער — המאגר ציבורי והכישורון לא זקוק לעדות משלו משום שהוא רק מנהל את `agenteye` CLI **הציבורי** מול לוח המחוונים שלך, תוך שימוש בהפעלה **שהתחברת אליה**. אתה לא צריך לשאול אף אחד על זה. +שום דבר בקשור אליו לא מגודר — המאגר ציבורי והמיומנות לא צריכה כל אישור משלה, כי היא רק מניעה את CLI `agenteye` **הציבורי** לעומת הדוחף *שלך*, באמצעות ההפעלה *שאתה* התחברת אליה. אתה לא צריך לשאול את זה מאנשים. -שימו לב שהוא משתלח כתיקייה משלו והוא **לא** בתוך חבילת `pipx install agenteye`, כך שלא תחפש אותו שם. +שימו לב שהוא משנה כתיקייה משלו והוא **לא** בתוך הארוזה `pipx install agenteye`, אז אל תחפש אותו שם. -## התקנת הכישורון +## התקנת המיומנות -הנתיב המהיר ביותר הוא CLI [`skills`](https://skills.sh), אשר אחזר את התיקייה ושוחק אותה כאשר הסוכן שלך מחפש: +הדרך המהירה ביותר היא CLI של [`skills`](https://skills.sh), שמשדר את התיקייה ומוריד אותה היכן שהסוכן שלך מחפש: ```bash # Claude Code, פרויקט זה בלבד @@ -75,55 +73,55 @@ npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -לאחר מכן נהל אותו כמו כל כישורון אחר: +ואז נהל אותה כמו כל מיומנות אחרת: ```bash -npx skills list -a claude-code # מה שהותקן +npx skills list -a claude-code # מה מותקן npx skills update agenteye-cli # משוך את הגרסה העדכנית -npx skills remove agenteye-cli # הסר אותו +npx skills remove agenteye-cli # הסר אותה ``` -מעדיף להתקין ביד? Agent Skill הוא רק תיקייה המכילה `SKILL.md` (בתוספת התייחסויות אופציונליות), כך שהעתקה פועלת גם: +מעדיף להתקין ביד? Agent Skill היא פשוט תיקייה המכילה `SKILL.md` (בתוספת התייחסויות אופציונליות), אז העתקה עובדת גם: -- **Claude Code**: שים את תיקיית `agenteye-cli/` ב-`~/.claude/skills/` (כל פרויקט) או `/.claude/skills/` (רק אותו רפו). Claude Code מגלה זאת באופן אוטומטי — אמת עם רשימת `/skills`, או פשוט שאל שאלה התואמת את התיאור שלו. -- **Codex (OpenAI)**: Codex קורא את אותה `SKILL.md`. ה-`agents/openai.yaml` המצורף קובע `allow_implicit_invocation: true`, כך ש-Codex בוחר באופן אוטומטי את הכישורון כאשר משימה תואמת; אחרת הפעל אותו באופן מפורש כ-`$agenteye-cli`. +- **Claude Code**: שים את תיקיית `agenteye-cli/` ב-`~/.claude/skills/` (כל פרויקט) או `/.claude/skills/` (רק אותו repo). Claude Code חוקר זאת באופן אוטומטי — אמת עם רשימת `/skills`, או פשוט שאל שאלה שתואמת את התיאור שלה. +- **Codex (OpenAI)**: Codex קורא את `SKILL.md` זהה. ה-`agents/openai.yaml` המצורף קובע `allow_implicit_invocation: true`, אז Codex בוחר באופן אוטומטי את המיומנות כאשר משימה תואמת; אחרת יש לזמן אותה במפורש כ-`$agenteye-cli`. --- -## בטיחות: מוטציות **לא** מבקשות כאשר סוכן מריץ את ה-CLI +## בטיחות: מוטציות לא מהן כאשר סוכן מריץ את CLI -> **אזהרה:** קרא זאת לפני שאתה נותן לסוכן לבצע שינויים. +> **אזהרה:** קרא את זה לפני שאתה נותן לסוכן לבצע שינויים. -ה-CLI `agenteye` בדרך כלל שואל *"האם אתה בטוח?"* לפני פעולה הרסנית. זה **דילוג אוטומטי על אישור זה בכל פעם שלא מוצמד לטרמינל (שהוא בדיוק איך סוכן קוד מריץ אותו), ו-`--json` דילוג עליו גם.** אז הנושא הבטיחות **לא** יופעל עבור הסוכן. +CLI של `agenteye` בדרך כלל שואל *"האם אתה בטוח?"* לפני פעולה הרסנית. הוא **דוחה באופן אוטומטי את האישור בכל פעם שהוא לא מחובר לטרמינל (שזה בדיוק איך סוכן קוד מריץ אותו), ו-`--json` דוחה אותו גם.** אז הבטחון בהודעה לא **יופעל** עבור הסוכן. -הכישורון כתוב לפיצוי: הוא מוּעד להצהיר על הפקודה המדויקת שהוא יריץ ולהשיג את ה-**אישור המפורש שלך לפני כל שינוי מצב**. השמור על המשמעת הזו. כאשר אתה מנהל את Failproof AI Observability דרך סוכן, *אתה* הצעד האישור. הפקודות המשנות מצב שצריך להיזהר מהן: +המיומנות כתובה לפיצוי: היא מונחית להצהיר על הפקודה המדויקת שהיא תריץ ותקבל את **ה-OK המפורש שלך לפני כל שינוי מצב**. שמור על הדיסציפלינה. כאשר אתה מניע את Failproof AI Observability דרך סוכן, *אתה* הצעד האישור. פקודות שינוי המצב שיש להיזהר מהן: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` - `settings set` - `alerts create` / `update` / `delete` / `test` -- תת-הפקודות הכתיבה `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` +- תת-הפקודות הכתיבה של `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` - `query create` / `update` / `delete` - `agent rename` / `delete` - `orgs switch` -הכל תחת **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) הוא קריאה בלבד ולא משנה שום דבר. +כל דבר תחת **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) קריאה בלבד ולא משנה דבר. -מכיוון שהסוכן פועל כ-**אתה**, הוא יכול לעשות רק מה שההתחברות שלך מורשת לעשות; הרשאות מתבררות **לכל ארגון** (ראה [API keys](/he/agenteye/api-keys)). פקודה שאתה חסר הרשאה עבורה מחזירה קוד יציאה `5` עם ההרשאה המדויקת שנקראה, כך שהסוכן יכול לומר לך בדיוק למה לבקש מ-admin במקום להיכשל בעלום. +מכיוון שהסוכן פועל כ**אתה**, הוא יכול רק לעשות מה שהכניסה שלך מורשית לעשות; הרשאות מחוברות **לכל ארגון** (ראה [מפתחות API](/he/agenteye/api-keys)). פקודה שאתה חסר הרשאה לה מחזירה קוד יציאה `5` עם ההרשאה המדויקת בשם, כך שהסוכן יכול לומר לך בדיוק מה לבקש מאדמין במקום להיכשל בעדינות. --- ## מה אתה יכול לשאול אותו -הנה איך נראית סיבוב בעולם האמת, קריאה ואחריה שינוי שמחכה לאישור שלך: +הנה מה שחזרת בפועל נראית, קריאה, ואחר כך שינוי שמחכה ל-OK שלך: ```text -אתה ▸ האם משהו שבור בבחינה האחרונה? +אתה ▸ האם משהו השתבר בעדי היום? -סוכן ▸ ריצה: agenteye --json errors --since 24h --aggregate - 3 סוגי שגיאה בבחינה האחרונה. הגדול ביותר הוא TimeoutError - (18 עוקבים, כולם ב-checkout-agent), ואחריו RateLimited (5). - רוצה את ההפעלות הנכשלות עבור TimeoutError? +סוכן ▸ הפעלה: agenteye --json errors --since 24h --aggregate + 3 סוגי שגיאה ביום האחרון. הגדולה ביותר היא TimeoutError + (18 הצעות, הכל בחקוי-checkout), ואחריה RateLimited (5). + רוצה את ההפעלות הכושלות עבור TimeoutError? אתה ▸ תן ל-CI מפתח שיכול רק לדחוף אירועים. @@ -133,28 +131,28 @@ npx skills remove agenteye-cli # הסר אותו אתה ▸ כן -סוכן ▸ בוצע. מפתח "ci" נוצר עם events:add בלבד. - הסוד מוצג רק פעם אחת, כך שאחסן אותו עכשיו. אני לא יכול להדפיס מחדש. +סוכן ▸ בוצע. מפתח "ci" יצור עם events:add בלבד. + הסוד מוצג רק פעם אחת, אז שמור אותו עכשיו. אני לא יכול להדפיס אותו מחדש. ``` -הכישורון ממפה כל כוונה בשפה טבעית לפקודת `agenteye` הנכונה, תוך גילוי ערכים חוקיים קודם (`list `, `whoami`) כך שהוא לא מנחש, והצהיר על הפקודה המדויקת לפני כל שינוי. עוד דוגמאות: +המיומנות ממפה כל כוונה בשפה טבעית לפקודת `agenteye` הנכונה, גילויה ערכים תקפים תחילה (`list `, `whoami`) כדי שהוא לא יחשוד, והצהיר על הפקודה המדויקת לפני כל שינוי. דוגמאות נוספות: -- *"האם משהו שבור / נכשל בבחינה האחרונה?"* → `errors --since 24h --aggregate`, ואחריו פירוט. -- *"למה הפעלה `run-001` נכשלה?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *"איך האיכות מתגברת בשבוע זה?"* → `evals --aggregate --since 7d`, ואחריו קדרילה לתוך ריצות בציון נמוך. -- *"תן ל-CI מפתח שיכול רק לדחוף אירועים."* → `keys create ci --add events:add` (זה מצהיר על הפקודה, ואחריו יוצר אותה ותופס את הסוד החד-פעמי). -- *"מי יש גישה? הפוך את Dana לקריאה בלבד."* → `users list` → `users update dana@… --permission-set read-only` (לאחר אישור איתך). -- *"אשר את האירוע הפועל והקצה אותו אלי."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. +- *"האם משהו השתבר / נכשל ביום האחרון?"* → `errors --since 24h --aggregate`, ואחר כך פירוק. +- *"למה ההפעלה `run-001` נכשלה?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. +- *"כיצד האיכות חוזרת השבוע?"* → `evals --aggregate --since 7d`, ואחר כך קדח להפעלות בדרגה נמוכה. +- *"תן ל-CI מפתח שיכול רק לדחוף אירועים."* → `keys create ci --add events:add` (זה מצהיר על הפקודה, ואחר כך יוצר אותה ותופס את הסוד חד-פעמי). +- *"למי יש גישה? עשה Dana קריאה-בלבד."* → `users list` → `users update dana@… --permission-set read-only` (אחרי שאישור איתך). +- *"אשר את האירוע הירי והקצה אותו אלי."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. -עבור הפקודות המדויקות, הדגלים, וצורות JSON שמאחוריהן, ראה את התייחסות [CLI](/he/agenteye/cli) ו-[CLI recipes for agents](/he/agenteye/cli-recipes). +עבור הפקודות המדויקות, הדגלים, וצורות JSON מאחורי אלה, ראה את הייחוס [CLI](/he/agenteye/cli) ו-[CLI recipes עבור סוכנים](/he/agenteye/cli-recipes). --- -## שלבים הבאים +## צעדים הבאים -- **[CLI](/he/agenteye/cli)**: ההתייחסות המלאה לפקודה ודגל עבור `agenteye`. -- **[CLI recipes for agents](/he/agenteye/cli-recipes)**: דוגמות `jq` להעתקה-הדבקה וטיפול בקוד יציאה. -- **[כישורון סוכן Evaluator](/he/agenteye/evaluator-skill)**: הכישורון אחות, לבניית ה-evaluator שאותו ניקוד `agenteye evals` קורא. -- **[כישורון סוכן Python SDK](/he/agenteye/python-sdk-skill)**: הכישורון אחות, להכשרת סוכן כך שהוא פולט את הטלמטריה שקוראת `agenteye`. -- **[עוזר AI](/he/agenteye/assistant)**: העוזר בתוך הלוח (לא להתבלבל עם כישורון הטרמינל הזה). -- **[API keys](/he/agenteye/api-keys)**: מודל ההרשאה לכל ארגון שמגביל מה הכישורון יכול לעשות. \ No newline at end of file +- **[CLI](/he/agenteye/cli)**: ייחוס פקודה ודגל מלא עבור `agenteye`. +- **[CLI recipes עבור סוכנים](/he/agenteye/cli-recipes)**: דפוסי `jq` להעתקה-הדבקה ו-exit-code handling. +- **[מיומנות סוכן Evaluator](/he/agenteye/evaluator-skill)**: מיומנות אחות, לבניית המעריך שניקוד שלו `agenteye evals` קורא. +- **[מיומנות סוכן Python SDK](/he/agenteye/python-sdk-skill)**: מיומנות אחות, להכשרת סוכן כך שהוא פולט את הטלמטריה `agenteye` קורא. +- **[עוזר AI](/he/agenteye/assistant)**: עוזר בדוחף (לא להתבלבל עם מיומנות טרמינל זו). +- **[מפתחות API](/he/agenteye/api-keys)**: מודל ההרשאה לכל ארגון שמוגבל מה המיומנות יכולה לעשות. \ No newline at end of file diff --git a/docs/he/agenteye/cli.mdx b/docs/he/agenteye/cli.mdx index 19a792a3..052e9b19 100644 --- a/docs/he/agenteye/cli.mdx +++ b/docs/he/agenteye/cli.mdx @@ -1,24 +1,24 @@ --- title: "CLI" -description: "נהל את כל Failproof AI Observability מהטרמינל או מסקריפט: ללא צורך בגלישה בדashboard." +description: "הנע את כל Failproof AI Observability מהטרמינל או מסקריפט: ללא ביקורים בדשבורד." --- -נהל את כל Failproof AI Observability מהטרמינל או מסקריפט: ללא צורך בגלישה בדashboard. ה-CLI של `agenteye` שואל על הנתונים שלך (sessions, event logs, evaluations) וממנהל את הארגון שלך (API keys, users, settings, alerts, incidents, saved queries), אז הפנה אליו כאשר אתה רוצה להוסיף בדיקה אוטומטית, לחבר Observability ל-CI, או להשאיר לagent לבדוק production. כל פקודה תומכת בדגל `--json`, כך שהיא עובדת באותה מידה טובה בשבילך בשורת הפקודה או לagent שמריץ ודורס את התוצאה. +הנע את כל Failproof AI Observability מהטרמינל או מסקריפט: ללא ביקורים בדשבורד. ה-CLI של `agenteye` שואל על הנתונים שלך (sessions, event logs, evaluations) ומנהל את הארגון שלך (API keys, users, settings, alerts, incidents, saved queries), לכן הפנה אליו כשאתה רוצה להפעיל בדיקה אוטומטית, לחבר Observability ל-CI, או לאפשר לסוכן קוד לבדוק את הייצור. כל פקודה תומכת בדגל `--json`, כך שהיא עובדת בדיוק כמו לך בשורת הפקודה או לסוכן קוד (Claude Code, Cursor) המבצע shell out ומנתח את התוצאה. -עם בינארי אחד אתה יכול: +עם בינרי אחד אתה יכול: -- **קרוא את הנתונים שלך**: `sessions`, `events`, `evals`, `errors` (סנן לפי זמן, agent, env, score). +- **קרא את הנתונים שלך**: `sessions`, `events`, `evals`, `errors` (סנן לפי זמן, סוכן, env, ציון). - **נהל את הארגון שלך**: `keys`, `users`, `settings`, `alerts`, `incidents`. -- **הרץ ניתוחים**: SQL שמור ומריץ query ad-hoc (`query`). -- **שאל את עוזר ה-AI**: אותו analyst read-only שאתה משוחח איתו בdashboard (`agent`). +- **הפעל analytics**: SQL שמור ו-ad-hoc query runner (`query`). +- **שאל את עוזר ה-AI**: אותו אנליסט קריאה בלבד שאתה משוחח איתו בדשבורד (`agent`). -> **הערה:** זה ה-CLI של `agenteye`, כלי שונה מה-collector daemon (`agenteye-collector`). ה-CLI מדבר עם dashboard שלך; ה-collector שולח events לשרת. +> **הערה:** זה ה-CLI של `agenteye`, כלי שונה מה-collector daemon (`agenteye-collector`). ה-CLI מדבר לדשבורד שלך; ה-collector שולח events לשרת. --- -## התחלה מהירה +## Quickstart -מלא אפס עד התוצאה הראשונה שלך בארבע שורות. אתחל את ה-CLI לdashboard שלך, התחבר, אשר מי אתה, ואז משוך את יום אחרון של runs: +מלא לא כלום לתוצאה הראשונה שלך בארבע שורות. הצבע את ה-CLI לדשבורד שלך, היכנס, אשר מי אתה, ואז משוך את היום האחרון של runs: ```bash pipx install agenteye @@ -27,7 +27,7 @@ agenteye whoami agenteye --json sessions --since 24h # one row per agent run, last 24h ``` -הפקודה האחרונה מדפיסה אובייקט JSON של ה-sessions האחרונים ביותר (החדשים ביותר קודם, מוגבלים ל-50 כברירת מחדל). Pipe את זה ל-`jq` כדי לחתוך אותו, או הסר `--json` לטבלה boxed וצבעונית. כל שורה נושאת את status של ה-run, ואם evaluator נתן ציון, את ציוני המטריקות שלו (מקוצר כאן): +הפקודה האחרונה הדפיסה אובייקט JSON של ה-sessions האחרונים ביותר (החדשים ביותר ראשונים, מוגבל ל-50 כברירת מחדל). צנור אותו ל-`jq` כדי לפרוס אותו, או זרוק `--json` לטבלה מלוטשת וצבעונית. כל שורה נושאת את הסטטוס של ה-run וההערה, אם evaluator נתן לה ציון, את ציוני המדדים שלה (מקוצרים כאן): ```json { @@ -47,13 +47,13 @@ agenteye --json sessions --since 24h } ``` -שאר הדף מסביר כל חלק: [התקנה](#installation) בבידוד, [התחברות](#authentication), [תצורה](#configuration), [הקונבנציות הגלובליות](#global-options--conventions) שכל פקודה משתפת, ו[הפניה המלאה לפקודות](#command-reference). +שאר העמוד מסביר כל חלק: [התקנה](#installation) בבידוד, [כניסה](#authentication), [תצורה](#configuration), ה-[מוסכמות גלובליות](#global-options--conventions) שכל פקודה חולקת, ו-[ההפניה המלאה של הפקודה](#command-reference). --- -## התקנה +## Installation -ה-CLI הוא חבילת PyPI ציבורית בשם **`agenteye`**. התקן אותו בסביבה מבודדת כך שיהיה לו תמיד תלויות משלו: +ה-CLI הוא חבילת PyPI ציבורית בשם **`agenteye`**. התקנה אותה בסביבה מבודדת כדי שתמיד יהיו לה תלויות משלה: ```bash pipx install agenteye @@ -68,35 +68,35 @@ agenteye --version agenteye --help ``` -> **הערה:** ה-Python SDK של Failproof AI Observability משתמש גם בשם ההפצה `agenteye`. התקנת ה-CLI עם `pipx` או `uv tool` (במקום `pip install` לתוך virtualenv משותף) מונעת התנגשות בין השניים. `pip install agenteye` פשוט בסדר רק אם ה-SDK לא מותקן באותה סביבה. +> **הערה:** ה-SDK של Failproof AI Observability Python משתמש גם בשם ההפצה `agenteye`. התקנת ה-CLI עם `pipx` או `uv tool` (במקום `pip install` ל-virtualenv משותף) מונעת מהשניים להתנגש. `pip install agenteye` פשוט בסדר רק אם ה-SDK לא מותקן באותה סביבה. --- -## התחברות +## Authentication -ה-CLI מתחבר ל-**dashboard** עם קוד חד-פעמי בדואר: +ה-CLI מאמת ל-**דשבורד** עם קוד חד-פעמי בדואר: ```bash agenteye login --email you@example.com # A 6-digit code is emailed to you; paste it at the prompt. ``` -토큰ה-session מאוחסן ב-`~/.agenteye/cli.json` (קריא רק לך, mode `0600`) והוא תקף למשך 24 שעות כברירת מחדל. כאשר הוא פג, הרץ `agenteye login` שוב. +טוקן ההפעלה מאוחסן ב-`~/.agenteye/cli.json` (קריא רק על ידיך, mode `0600`) ותקף במשך 24 שעות כברירת מחדל. כשהוא תוקף, הרץ שוב `agenteye login`. ```bash agenteye whoami # show the current user, active org, and permissions agenteye logout # revoke the session and clear the stored token ``` -`whoami` לעולם לא נכשל בsession חסר או פג; הוא מדווח על `logged_in: false` במקום זאת, כך שסקריפט או agent יכול לבדוק את מצב ה-auth בבטחה (הוא עדיין יכול להיכשל עם non-zero אם לא מוגדר base URL או ה-dashboard לא זמין). +`whoami` לא אי פעם שגיאה בהפגשה חסרה או תוקפת; זה דיווח `logged_in: false` במקום זאת, כך שסקריפט או סוכן יכול לחקור בעדינות את מצב ה-auth (זה עדיין יכול לצאת שאינו אפס אם לא מוגדרת כתובת URL בסיס או הדשבורד בלתי מסיח דעת). -**דרישות:** הדואר שלך חייב להיות מורשה להתחבר לdashboard (שאל את מנהל Failproof AI Observability שלך), וה-dashboard חייב להיות זמין ב-base URL שלו (ראה [Configuration](#configuration)). אם אתה מבקש קוד וכלום לא מגיע, הדואר שלך כנראה עדיין לא מופעל לגישה לdashboard. +**דרישות:** הדוא"ל שלך חייב להיות מורשה להיכנס לדשבורד (שאל את מנהל Failproof AI Observability), והדשבורד חייב להיות זמין בכתובת ה-URL הבסיסית שלו (ראה [תצורה](#configuration)). אם תבקש קוד ואף אחד לא מגיע, הדוא"ל שלך כנראה עדיין לא מופעל לגישה לדשבורד. --- -## בחר את ה-org שלך (multi-tenant) +## בחירת הארגון שלך (multi-tenant) -אם החשבון שלך שייך ליותר מ-org אחד, בחר את ה-active **בזמן login**; זה נשמר ומשמש לכל פקודה מאוחרת: +אם החשבון שלך שייך ליותר מארגון אחד, בחר את הפעיל **בעת הכניסה**; זה נשמר והשתמש בכל פקודה מאוחרת יותר: ```bash agenteye login --org acme # authenticate and set the active tenant in one step @@ -105,13 +105,13 @@ agenteye orgs switch globex # change the saved default agenteye --org globex sessions # override for a single command ``` -אם אתה שייך בדיוק לorg אחד הוא נבחר אוטומטית ואתה יכול להתעלם מ-`--org` לחלוטין. אם אתה שייך לכמה ולא בחרת אחד, ה-CLI מרשימה אותם ושואל אותך להריץ מחדש עם `--org `. ה-org הpublic הactive נשלח לdashboard בכל בקשה, וההרשאות שלך מסולרות **per org**; `agenteye whoami` מציגה את ה-org הactive, ההרשאות שלך בו, והחברויות שלך. +אם אתה שייך בדיוק לארגון אחד הוא נבחר באופן אוטומטי ותוכל להתעלם לחלוטין מ-`--org`. אם אתה שייך לכמה ולא בחרת באחד, ה-CLI מופעים אותם ומבקש ממך להריץ שוב עם `--org `. הארגון הפעיל נשלח לדשבורד בכל בקשה, וההרשאות שלך מחושבות **לכל ארגון**; `agenteye whoami` מציג את הארגון הפעיל, ההרשאות שלך בו, וכל החברויות שלך. --- -## תצורה +## Configuration -| הגדרה | דגל | משתנה סביבה | ברירת מחדל | +| Setting | Flag | Environment variable | Default | |---|---|---|---| | Dashboard base URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **required** (no default) | | Active org/tenant | `--org` | `AGENTEYE_ORG` | chosen at login; saved in `~/.agenteye/cli.json` | @@ -121,71 +121,71 @@ agenteye --org globex sessions # override for a single command | Request timeout (seconds) | `--timeout` | _(none)_ | 30 | | Disable usage telemetry | _(none)_ | `AGENTEYE_ANALYTICS_DISABLED` (or `DO_NOT_TRACK`) | telemetry is currently disabled; nothing is sent | -סדר ההחלטה הוא **flag → environment variable → config file**. אין ברירת מחדל; חייב לאתחל את ה-CLI לdashboard שלך, או per-command (`--base-url https://agenteye.example.com`) או פעם אחת דרך הסביבה (זה גם נשמר לאחר `login` הראשון שלך): +סדר הפתרון הוא **flag → environment variable → config file**. אין ברירת מחדל; עליך להצביע את ה-CLI לדשבורד שלך, או לפי פקודה (`--base-url https://agenteye.example.com`) או פעם אחת דרך הסביבה (זה גם נשמר לאחר ה-`login` הראשון שלך): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -ספריית התצורה מכבדת `AGENTEYE_HOME` (אותה קונבנציה המשמשת את ה-SDK וה-collector); אם מוגדר, `cli.json` חי ב-`$AGENTEYE_HOME/cli.json`. +ספריית התצורה כבדת `AGENTEYE_HOME` (אותה מוסכמה בשימוש על ידי ה-SDK וה-collector); אם מוגדר, `cli.json` חי ב-`$AGENTEYE_HOME/cli.json`. -### TLS חתום עצמי או פנימי +### Self-signed or internal TLS -אם ה-dashboard שלך מוזן דרך HTTPS עם תעודה חתומה עצמית או פנימית (לדוגמה, שם host raw load-balancer), אימות TLS דוחה אותו עם שגיאת `CERTIFICATE_VERIFY_FAILED`. עבור `--insecure` כדי לדלג על אימות תעודה: +אם הדשבורד שלך מוגש על פני HTTPS עם תעודה self-signed או פנימית (לדוגמה, שם המארח של load-balancer גולמי), אימות TLS דוחה אותו עם שגיאת `CERTIFICATE_VERIFY_FAILED`. עבור `--insecure` כדי לדלג על אימות התעודה: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` הוא **נשמר ל-`cli.json` כאשר אתה מתחבר**, כך שפקודות מאוחרות יותר דילוג אימות אוטומטי; אתה לא צריך לחזור על הדגל. עבור `--secure` לקול מאומת חד-פעמי, או כדי לשמור אימות חזרה על ב-login הבא שלך. ה-CLI מדפיס אזהרה ל-stderr לפני כל פקודה שמתקשרת לdashboard בזמן אימות מכובה. דילוג אימות מסיר הגנה נגד התקפות man-in-the-middle; ודא שאתה סומך על נתיב הרשת לdashboard (VPN, private subnet, וכו') לפני שאתה מסתמך עליו. +`--insecure` הוא **נשמר ל-`cli.json` כשאתה מכניס**, כך שפקודות מאוחרות יותר דולגות אימות באופן אוטומטי; אתה לא צריך לחזור על הדגל. עבור `--secure` לשיחה אימות חד פעמית, או כדי לשמור בחזרה אימות בעת ההכנסה הבאה שלך. ה-CLI מדפיס אזהרה ל-stderr לפני כל פקודה שמעבדת אל הדשבורד בעוד שאימות אינו מופעל. דילוג על אימות מסיר הגנה מפני התקפות middle-in-the-middle; ודא שאתה מאמין בנתיב הרשת לדשבורד שלך (VPN, private subnet, וכו ') לפני שאתה מסתמך עליו. --- ## Telemetry & privacy -> **הערה:** ה-CLI המסופק שולח **שום telemetry שימוש היום.** מתג הרג ראשי הוא פועל, כך שלום לא משודר בכל סביבה. הקטע שלהלן מתאר את יכולת ה-opt-out לאם וכאשר telemetry כשהוא מופעל אי פעם. +> **הערה:** ה-CLI המשדר שלח **לא משימוש טלמטריה כיום.** מתג kill master מופעל, כך שכלום לא מועבר ללא קשר לסביבה שלך. הסעיף להלן מתאר את יכולת ה-opt-out עבור אם ומתי טלמטריה אי פעם מופעלת. -גם כשמופעל, telemetry יהיה **analytics שימוש אנונימי בלבד**, לא מעולם ה-agent, session, או event שלך: +אפילו כשמופעל, טלמטריה תהיה **בלבד ניתוח שימוש אנונימי**, לעולם לא הסוכן, ההפעלה, או נתוני האירוע שלך: -- **לא ה-agent, session, או event שלך כשהוא משאיר את התשתית שלך.** רק שימוש CLI יהיה מדווח: הפקודה ו-subcommand name (לדוגמה `keys create`), **names** של הדגלים שהשתמשת בהם (לא פעם את הערכים שלהם), success/exit status, ודווח, בתוספת per-action event לmutations (לדוגמה `api_key_created`, `query_run`) בנשיאה שמות/enums סטטיים בלבד וספירות גס. ה-dashboard URL שלך, session token, דואר, org slug, resource ids, SQL, key secrets, וquery filters היו **never** שלח. אופרטורים היו מזוהים רק ב-opaque internal id, לא לפי דואר. -- **Opt out מראש** על ידי הגדרה `AGENTEYE_ANALYTICS_DISABLED=1` בסביבה של ה-CLI (ה-CLI גם מכבד את ה-cross-tool `DO_NOT_TRACK=1` קונבנציה). זה נכנס לתוקף ברגע telemetry הוא אי פעם הופכת, כך שסביבה privacy-conscious יכולה להישאר opted out לצמיתות. -- אם telemetry היו מופעל, ה-CLI היה שלח ישירות ל-PostHog (`https://us.i.posthog.com`); מכונה עם host זה חסום היא שקט לא שלח כלום וה-CLI היה unaffected. +- **לא סוכן, הפעלה, או נתוני אירוע אי פעם עזבו את התשתית שלך.** רק ה-CLI שימוש דווח: שם הפקודה והתת-פקודה (לדוגמה `keys create`), **השמות** של הדגלים שהשתמשת (לעולם לא את הערכים שלהם), הצלחה / exit status, ומשך, בתוספת אירוע לפעולה למוטציות (לדוגמה `api_key_created`, `query_run`) נושא שמות / enums סטטיים בלבד וספירות גסות. כתובת ה-URL של הדשבורד שלך, טוקן ההפעלה, דוא"ל, org slug, ids משאבים, SQL, סודות מפתח, וסינוני שאילתות **לעולם** לא יישלחו. מפעילים הם מזוהים רק על ידי id פנימי אטום, לעולם לא בדוא"ל. +- **הסר beforehand** על ידי הגדרה `AGENTEYE_ANALYTICS_DISABLED=1` בסביבת ה-CLI (ה-CLI גם מכבד את `DO_NOT_TRACK=1` cross-tool convention). זה נכנס לתוקף ברגע שטלמטריה היא כל פעם הדלק, כך סביבה-מודעת פרטיות יכול להישאר מחוץ לעד לנצח. +- אם טלמטריה היתה מופעלת, ה-CLI היה שולח ישירות ל-PostHog (`https://us.i.posthog.com`); מכונה עם אותו מארח חסום היה שולח בשקט כלום וה-CLI לא היה מושפע. --- ## Global options & conventions -קרא את זה פעם אחת; זה חל לכל פקודה. +קרא זה פעם אחת; זה חל על כל פקודה. -- **Global options לך לפני הפקודה.** `agenteye --json sessions` הוא נכון; `agenteye sessions --json` היא שגיאת שימוש. ה-globals הם `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, ו-`--no-color`. -- **`--json` מדפיס pure JSON ל-stdout, וכלום אחר.** Human status lines, הערות, ושגיאות לך ל-**stderr**, כך ש-`--json` stdout capture נשאר נקי ל-pipe לתוך `jq` גם כאשר status line מוצג. ללא `--json` אתה משיג boxed, צפוי בחזרה לעיני אדם. -- **גלה עם `--help`.** כל פקודה וsub-command יש `--help` (ו-`-h` alias): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. העזרה ברמה העליונה גם רשימות exit codes וגלובליות אפציות. אין global machine-readable surface dump; השתמש per-command `--help`, בתוספת domain-specific `agenteye query schema` ו-`agenteye settings schema` לשניים אלו registries. -- **Confirmations auto-skip לscrips וagents.** Create/update/delete פקודות הנושא "האם אתה בטוח?" בטרמינל interactive, אבל **auto-skip שהנושא תחת `--json` או בכל פעם stdin אינו TTY** (TTY הוא interactive terminal session; pipe או CI runner לא), כך שscrips וagents לא תלויים. עבור `--yes`/`-y` כדי לדלג עליו במפורש. מכיוון שהנושא לא יקום לagent, agent צריך לאשר משימות destructive עם אדם ראשון. -- **Pagination:** תוצאות הן newest-first וcursor-paginated (כל עמוד חוזר token אתה משתמש כדי להביא את הבא). `--limit N` (alias `-n`) caps rows ו**defaults ל-50**; `--all` auto-paginates (בחלקי 200-row) **עד `--limit`**, כך צרה `--all` עדיין עוצר ב-50. לעבור מלא עבור pass a גבוה explicit cap: `--all --limit 1000`. `--page-size N` שליטה per-request chunk (max 200); `--cursor ` resumes מא prior page's `next_cursor`. -- **Time filters:** `--since` לוקח a relative window: `15m`, `1h`, `6h`, `24h`, `7d`, או `all` (dashboard's presets). לארוך או custom range (say 30 ימים האחרונים), השתמש `--from`/`--to`: explicit ISO-8601 UTC timestamps **עם `T` וtimezone** (לדוגמה `2026-06-01T00:00:00Z`) כי override `--since`. space-separated או timezone-less value היא שגיאת שימוש. -- **`--fields a,b,c`** (על `events`, `sessions`, `evals`, `errors`) מגביל את הפלט לאלו מקשים, עבור שניהם הטבלה ו-`--json`. שמות לא ידועים דחויים עם הרשימה תקפה, דרך זול לגלות שמות שדה. -- **`--file payload.json`** (או `--file -` לקרוא stdin) מספק מלא JSON request body כאשר משאב יש צורה מורכבת (על `alerts create/update`, `settings set`, ו-`users create/update`). Saved-query SQL משתמש `--sql @file.sql` במקום. -- **Multi-value filters** הם comma-separated → matched כ-set (union בתוך filter אחד, AND throughout filters): `--event-type tool_use,tool_result`. Click אפציות אינם variadic, כך `--add a b` שבירות. השתמש `--add a,b`, חזור הדגל (`--add a --add b`), או ציטוט (`--add "a b"`). +- **אפשרויות גלובליות הולכות לפני הפקודה.** `agenteye --json sessions` נכון; `agenteye sessions --json` הוא שגיאת שימוש. הגלובאליים הם `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, ו-`--no-color`. +- **`--json` מדפיס JSON טהור ל-stdout, ותו לא.** שורות סטטוס אנושיות, אזהרות, ו-errors הולכים ל-**stderr**, כך ש-`--json` stdout capture נשאר נקי כדי להנקות ל-`jq` אפילו כששורת סטטוס מוצגת. ללא `--json` אתה מקבל תצוגה מלוטשת וצבעונית לעיניים אנושיות. +- **גלה עם `--help`.** כל פקודה ותת-פקודה יש `--help` (וה-`-h` alias): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. העזרה ברמה העליונה גם מופעת את קודי ה-exit וההאפשרויות הגלובליות. אין דומה משטח קרא כללי מכונה; להשתמש לכל פקודה `--help`, בתוספת תחום-ספציפיק `agenteye query schema` ו-`agenteye settings schema` לאלה שני registries. +- **אישורים auto-skip לסקריפטים וסוכנים.** צור / עדכן / מחק פקודות לשאול את "האם אתה בטוח?" בטרמינל אינטראקטיבי, אך **skip auto את ההנמקה תחת `--json` או בכל פעם stdin אינו TTY** (TTY הוא טרמינל אינטראקטיבי הפעלה; צינור או CI runner אינו), כך סקריפטים וסוכנים לעולם לא תלויים. עבור `--yes`/`-y` כדי לדלג עליו בבירור. כי הנתונים לא יירה סוכן, סוכן צריך לאשר פעולות הרס עם האדם ראשון. +- **עמוד**: תוצאות הן newest-first ו-cursor-paginated (כל עמוד מחזיר אסימון שבו אתה משתמש כדי להביא את הבא). `--limit N` (alias `-n`) כובע שורות ו-**defaults to 50**; `--all` auto-paginates (ב-200-row chunks) **עד `--limit`**, כך בחושך `--all` עדיין עוצר ב-50. לסחיפה מלאה עבור גדול explicit cap: `--all --limit 1000`. `--page-size N` שולטים בכל בקשה chunk (max 200); `--cursor ` resumes מ-prior page `next_cursor`. +- **מסנני זמן:** `--since` לוקח חלון יחסי: `15m`, `1h`, `6h`, `24h`, `7d`, או `all` (presets של הדשבורד). לטווח ארוך יותר או בהתאם (תגיד ב-30 ימים האחרונים), השתמש ב-`--from`/`--to`: explicit ISO-8601 UTC timestamps **עם `T` וטיימזון** (לדוגמה `2026-06-01T00:00:00Z`) זה הכול `--since`. חלל-מופרד או ערך timezone-less הוא שגיאת שימוש. +- **`--fields a,b,c`** (on `events`, `sessions`, `evals`, `errors`) מגביל את הפלט לאותם מקשים, לשניהם הטבלה ו-`--json`. שמות לא ידועים נדחים עם הרשימה התקפה, דרך זולה לגלות שמות שדה. +- **`--file payload.json`** (או `--file -` להקריא stdin) חל גוף בקשת JSON מלא כאשר למשאב יש צורה מורכבת (על `alerts create/update`, `settings set`, ו-`users create/update`). Saved-query SQL משתמש `--sql @file.sql` במקום זאת. +- **מסנני רב-ערכים** הם comma-separated → התאימו כקבוצה (union בתוך מסנן אחד, AND על פני מסנני): `--event-type tool_use,tool_result`. אפשרויות לחיצה אינן variadic, כך `--add a b` שברים. משתמש `--add a,b`, חזור על הדגל (`--add a --add b`), או ציטוט (`--add "a b"`). --- ## Command reference -### אתה תשתמש בחמשת הפקודות הללו ביותר +### אתה תשתמש בפקודות אלה 5 הכי הרבה -יום רביעי של עבודה מתבצעות דרך של קצת read commands. התחל כאן, אז הגע עבור המשטח המלא להלן כאשר אתה צריך: +רוב העבודה היומית הולכת דרך קומץ פקודות קריאה. התחל כאן, ואז הפנה עצמך לשטח הגלוי להלן כשאתה זקוק לו: -| פקודה | מה זה עושה | נסה את זה | +| Command | What it does | Try it | |---|---|---| -| `sessions` | שורה אחת לכל agent run: זמן, env, agent, status, ציון לאחרונה. | `agenteye --json sessions --since 24h --status error` | -| `events` | ה-raw per-step trail בתוך run (הוסף `--full` לtayloads). | `agenteye --json events --session-id run-001 --all` | -| `evals` | תוצאות הערכה וציונים; `--aggregate` rolls them up. | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | רק את errored events; `--aggregate` לספירה לפי סוג. | `agenteye --json errors --since 24h --aggregate` | -| `list` | גלה את ערכי ה-filter תקפה (agents, envs, models, …). | `agenteye list agents` | +| `sessions` | One row per agent run: time, env, agent, status, latest score. | `agenteye --json sessions --since 24h --status error` | +| `events` | The raw per-step trail inside a run (add `--full` for payloads). | `agenteye --json events --session-id run-001 --all` | +| `evals` | Evaluation results and scores; `--aggregate` rolls them up. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | Just the errored events; `--aggregate` for counts by type. | `agenteye --json errors --since 24h --aggregate` | +| `list` | Discover the valid filter values (agents, envs, models, …). | `agenteye list agents` | -### כל מה ש-CLI יכול לעשות +### הכל ש-CLI יכול לעשות -המשטח המלא עוקב. ל-CLI יש **18 פקודות top-level**. כל read commands קבל `--json` וגלובליות אפציות לעיל; הרץ `agenteye -h` (או ` -h`) לexhaustive flag list וJSON shape של כל אחד. +השטח המלא הבא. ל-CLI יש **18 פקודות ברמה עליונה**. כל פקודות קריאה קבל `--json` והאפשרויות הגלובליות למעלה; הרץ `agenteye -h` (או ` -h`) עבור רשימת הדגל מלאה וצורת JSON של כל אחד. ### Identity: `login` · `logout` · `whoami` · `orgs` · `version` · `help` @@ -197,7 +197,7 @@ agenteye version # print the CLI version (s agenteye help # top-level help (same as --help) ``` -`orgs` inspects וscreens ה-active tenant: +`orgs` בודקת ומחליפה את דיירך הפעיל: ```bash agenteye orgs list # your orgs + your role in each (active one marked) @@ -208,7 +208,7 @@ agenteye orgs perms # your permissions in the active org, grouped by resou ### Observe (read-only): `events` · `sessions` · `evals` · `errors` · `list` -אף אחד מאלה צרך confirmation. Shared filters: `--session-id`, `--agent-id`, `--env` (**לא** `--environment`), וה-time range (`--since` / `--from` / `--to`). +אף אחד מאלה לא צריך אישור. מסנני משותפים: `--session-id`, `--agent-id`, `--env` (**לא** `--environment`), וטווח הזמן (`--since` / `--from` / `--to`). ```bash # events (alias: the raw per-step trail), newest first @@ -231,7 +231,7 @@ agenteye --json errors --since 24h --error-type timeout --all --limit 1000 agenteye list envs # also: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (על **`evals`**, לא `sessions`) הוא repeatable וAND-combined; שניהם bound הם אופציוניים (`..0.5` אומר ≤ 0.5, `0.9..` אומר ≥ 0.9). עד 20 score filters לבקשה. `evals --scores-full` היא display flag עבור ה-**human table בלבד**; זה מראה כל score pair במקום את הראשון כמה בתוספת `+N` count. זה אין השפעה תחת `--json`, שתמיד מחזיר את object score מלא. לקרוא **one session end-to-end**, שלב את ה-event trail עם הערכתו: +`--score KEY:MIN..MAX` (על **`evals`**, לא `sessions`) חוזרת ו-AND-combined; כל קשור הוא אופציונלי (`..0.5` פירושו ≤ 0.5, `0.9..` פירושו ≥ 0.9). עד 20 מסנני ציון לבקשה. `evals --scores-full` הוא דגל תצוגה עבור **הטבלה האנושית בלבד**; הוא מציג כל זוג ציון במקום את הראשון כמה בתוספת ספירת `+N`. זה אין השפעה תחת `--json`, שתמיד מחזיר את ציון אובייקט השלם. קרא **הפעלה אחת end-to-end**, שלב את path trail עם evaluation שלה: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' @@ -240,7 +240,7 @@ agenteye --json evals --session-id run-001 # its scores + ### Manage (permission-gated): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: API keys. הסוד נוצר מקומית, שלח לשרת (אשר stores רק hash), ו-**shown פעם אחת** על create/regenerate; capture זה אז. עם `--json` זה מופיע רק בשדה `key`. Referenced by **name**. +**`keys`**: API keys. הסוד נוצר באופן מקומי, נשלח לשרת (אשר מאחסן רק hash), **הוצג פעם אחת** על יצור / regenerate; לכוד אותו אחרי כן. עם `--json` זה מופיע רק בשדה `key`. ציטוט על ידי **שם**. ```bash agenteye keys list # active keys first, then revoked @@ -252,9 +252,9 @@ agenteye keys regenerate ci-bot --yes # rotate the secret (the ol agenteye keys disable ci-bot --yes # revoke ``` -הרשאות עבודה כמו `(permission-set ∪ --add) − --remove`. Tokens הם `slug:action` (לדוגמה `events:read`) או `slug:action.action` להרחיב כמה על משאב אחד (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. Human-only הרשאות (`keys:update`) לא יכול להיות כן ל-key. +הרשאות עבודה כ-`(permission-set ∪ --add) − --remove`. טוקנים הם `slug:action` (לדוגמה `events:read`) או `slug:action.action` כדי להרחיב כמה על משאב אחד (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. הרשאות אנושיות בלבד (`keys:update`) לא יכול להיות הוענק לחיבור. -**`users`**: org members, referenced by **email** (UUID id נכנס גם accepted). +**`users`**: חברי org, ציטוט על ידי **דוא"ל** (UUID id אתה תקבל גם). ```bash agenteye users list [--active-only] @@ -265,7 +265,7 @@ agenteye users disable dev@corp.com --yes # has protected/self guards agenteye users enable dev@corp.com ``` -**`settings`**: fixed registry (אתה קורא ושנה קיים keys; אתה לא יכול ליצור חדש). +**`settings`**: registry קבוע (אתה קורא וזה שינויים קיימים מקשים; אתה לא יכול ליצור חדש). ```bash agenteye settings list # key · value · type · updated (secrets masked) @@ -273,7 +273,7 @@ agenteye settings schema # what each key accepts (ty agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: הגדרות alert, referenced by **name**. `create` לוקח positional NAME בתוספת flags או מלא JSON body דרך `--file`. +**`alerts`**: הגדרות התראה, ציטוט על ידי **שם**. `create` לוקח שם פוזיציוני בתוספת דגלים או גוף JSON מלא דרך `--file`. ```bash agenteye alerts list @@ -284,7 +284,7 @@ agenteye alerts test high-errors --yes # fire a test noti agenteye alerts delete high-errors --yes ``` -**`incidents`**: alert incidents, referenced by id (short ids accepted). `show` prints ה-full activity log; קרא את זה לפני פועל. +**`incidents`**: התראה incidents, ציטוט על ידי id (קצר ids מקובל). `show` מדפיס את יומן הפעילות המלא; קרא אותו לפני פעולה. ```bash agenteye incidents list --state firing # also: acknowledged, resolved @@ -301,7 +301,7 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### Analytics & assistant: `query` · `agent` -**`query`**: saved SQL נגד analytics store בתוספת ad-hoc runner. Saved queries הם referenced by **name**; ה-SQL הוא validated server-side (SELECT/WITH רק, statement timeout, row cap). +**`query`**: שמור SQL נגד האנליטיקה שלך store בתוספת ad-hoc runner. שאילתות שמור הם ציטוט על ידי **שם**; SQL מתוצמת server-side (SELECT/WITH בלבד, statement timeout, row cap). ```bash agenteye query schema [TABLE] # column layout of the analytics views @@ -312,7 +312,7 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: דברים ל-built-in **AI assistant** (אותו read-only analyst אתה יכול לשוחח עם בdashboard). Chats הם referenced by short chat-id (prefix-resolved). +**`agent`**: מדברת עם ה-**עוזר AI** המובנה (אותו אנליסט קריאה בלבד שאתה יכול לשוחח איתו בדשבורד). צ'טים הם ציטוט על ידי short chat-id (prefix-resolved). ```bash agenteye agent health # is the AI assistant configured/reachable @@ -327,23 +327,23 @@ agenteye agent rename --title "error triage" ; agenteye agent delete ## Exit codes -| קוד | משמעות | +| Code | Meaning | |---|---| -| 0 | הצלחה | -| 1 | שגיאה לא צפויה (לדוגמה ה-dashboard החזיר 5xx) | -| 2 | שגיאת שימוש (ארגומנטים לא תקפה, פקודה/דגל לא ידוע, שם collision) | -| 3 | לא יכול להגיע ל-dashboard | -| 4 | לא התחבר או session פג; הרץ `agenteye login` | -| 5 | Authenticated, אבל החשבון שלך חסר את ההרשאה הנדרשת (ההודעה קורא את זה) | -| 6 | משאב המבוקש לא היה found (לדוגמה session לא ידוע או incident id) | +| 0 | Success | +| 1 | Unexpected error (e.g. the dashboard returned a 5xx) | +| 2 | Usage error (invalid arguments, unknown command/flag, name collision) | +| 3 | Cannot reach the dashboard | +| 4 | Not logged in or session expired; run `agenteye login` | +| 5 | Authenticated, but your account lacks the required permission (the message names it) | +| 6 | The requested resource was not found (e.g. unknown session or incident id) | -אלה עושים את ה-CLI בטוח לsript: coding agent יכול branch על `4` להנושא אותך re-authenticate, או `5` to surface החסרה הרשאה. ראה [CLI recipes לagents](/he/agenteye/cli-recipes) עבור exit-code-handling דפוסים וJSON output צורות. +אלה עושה את ה-CLI בטוח לסקריפט: סוכן קוד יכול ענף על `4` כדי לבקש ממך להתחיל שוב, או `5` כדי משטח ההרשאה החסרה. ראה [CLI recipes for agents](/he/agenteye/cli-recipes) עבור exit-code-handling דפוסים וצורות פלט JSON. --- -## הצעדים הבאים +## Next steps -- **[CLI recipes לagents](/he/agenteye/cli-recipes)**: copy-paste query דפוסים, `jq` one-liners, `--fields` הקרנות, exit-code handling, וJSON output צורות, כתוב עבור agents coding driving ה-CLI. -- **[CLI agent skill](/he/agenteye/cli-skill)**: חבילה זה CLI כמו installable Claude Code / Codex *skill* כך agent coding drives Failproof AI Observability מ-plain-English בקשות. -- **[API keys](/he/agenteye/api-keys)**: דגם ההרשאה מאחוריי `keys create --add …`. -- **[AI assistant](/he/agenteye/assistant)**: enabling ה-assistant כי `agent ask` דברים ל. \ No newline at end of file +- **[CLI recipes for agents](/he/agenteye/cli-recipes)**: העתק-הדבק דפוסי שאילתה, `jq` one-liners, `--fields` הקרנות, exit-code handling, וצורות פלט JSON, כתוב לסוכנים קוד נהונים ה-CLI. +- **[CLI agent skill](/he/agenteye/cli-skill)**: חבילה זה ה-CLI כמו installable Claude Code / Codex *skill* כך סוכן קוד נהונים Failproof AI Observability מ-plain-English בקשות. +- **[API keys](/he/agenteye/api-keys)**: הרשאה מודל מאחורי `keys create --add …`. +- **[AI assistant](/he/agenteye/assistant)**: הפעלת העוזר זה `agent ask` מדברת עם. \ No newline at end of file diff --git a/docs/he/agenteye/codex-capture.mdx b/docs/he/agenteye/codex-capture.mdx index d4faa449..4a35c7a3 100644 --- a/docs/he/agenteye/codex-capture.mdx +++ b/docs/he/agenteye/codex-capture.mdx @@ -1,56 +1,56 @@ --- --- title: "Codex session capture" -description: "Tail your team's local OpenAI Codex sessions into AgentEye as ordinary sessions and events — with no change to how they run Codex." +description: "ספור את ההפעלות המקומיות של Codex של הצוות שלך ל-AgentEye כפי שהן הפעלות ואירועים רגילים — ללא שינוי בדרך הפעלתן של Codex." --- -המהנדסים שלך כבר משתמשים ב-OpenAI Codex כל יום. Codex session capture מביא את הסשנים של קידוד אלה לתוך AgentEye כסשנים ואירועים רגילים, כך שתוכל לחפש, להשמיע שוב ולהעריך אותם לצד כל שאר מה שאתה צופה בו. זה משלים את [Python SDK](/he/agenteye/python-sdk): ה-SDK מחוממי אגנטים שאתה כותב, בעוד שזה תופס את עבודת ה-Codex שהצוות שלך כבר עושה — ללא שום שינוי בדרך שהם משתמשים בו. +המהנדסים שלך כבר מפעילים את OpenAI Codex כל יום. Codex session capture מביא את הפעלות הקודינג הללו ל-AgentEye כפי שהן הפעלות ואירועים רגילים, כך שתוכל לחפש, להשמיע שוב ולהעריך אותן לצד הכל האחר שאתה מצפה. זה משלים את [Python SDK](/he/agenteye/python-sdk): ה-SDK מעצב Agents שאתה כותב, בעוד שהוא תופס את עבודת ה-Codex שהצוות שלך כבר עושה — ללא שינוי בדרך הפעלתה. -collector בעלי רקע קטן קורא Codex local session transcripts כשהם נכתבים ושולח אותם ל-AgentEye. collector אחד לכל מכונה תופס כל Codex surface מקומי בו זמנית — אין הגדרה לכל משטח. +קולט רקע קטן קורא את תמלילי ההפעלות המקומיות של Codex כשהם נכתבים ושולח אותם ל-AgentEye. קולט אחד לכל מכונה תופס כל משטח Codex מקומי בו זמנית — אין הגדרה לכל משטח. -אותו collector תופס אגנטים אחרים גם — ראה [OpenClaw](/he/agenteye/openclaw-capture) ו-[Hermes](/he/agenteye/hermes-capture). הפוך כל אחד שאתה מריץ; collector יחיד יכול להשתמע למספר בו זמנית. +אותו קולט תופס גם Agents אחרים — ראה [OpenClaw](/he/agenteye/openclaw-capture) ו-[Hermes](/he/agenteye/hermes-capture). הפעל כל אחד מהם שאתה משתמש בו; קולט יחיד יכול לתפוס כמה בו זמנית. --- -## מה זה תופס +## מה הוא תופס -כל Codex surface שמריץ **locally** מייצר את אותו on-disk session transcripts, ו-collector תופס את כולם: +כל משטח Codex שרץ **מקומית** מייצר את אותם תמלילי הפעלות על הדיסק, והקולט בוחר את כולם: - ה-Codex **CLI** ו-`codex exec` -- ה-**VS Code / IDE extension** -- ה-**desktop app**, כשהוא מריץ סשן locally +- **ה-VS Code / IDE extension** +- **ה-desktop app**, כשהוא מפעיל הפעלה מקומית -כל Codex session הופך ל-AgentEye [session](/he/agenteye/sessions); ההודעות של user ו-assistant שלו, reasoning, tool calls, tool results, ו-token usage הופכים ל-[events](/he/agenteye/event-stream) התואמים. ה-surface שכל סשן הגיע ממנה (CLI, IDE, או desktop) נרשם, כך שתוכל להבחין ביניהם. +כל הפעלת Codex הופכת ל-AgentEye [session](/he/agenteye/sessions); הודעות המשתמש והעוזר שלה, הנמקה, קריאות כלים, תוצאות כלים והשימוש בטוקנים הופכים לתאימים [events](/he/agenteye/event-stream). המשטח שממנו הפעלה הגיעה (CLI, IDE, או desktop) נרשם, כך שתוכל להבדיל בינם. -> **Cloud sessions לא תופסים.** ה-desktop app בהולך וגדל מריץ סשנים בענן Codex ושומר רק את metadata שלהם במכונה — אין local transcript לקרוא. רק סשנים המתורגמים locally תופסים. +> **הפעלות בענן לא תופסות.** ה-desktop app בצורה הולכת וגוברת מפעיל הפעלות בענן Codex ושומר רק על המטא-נתונים שלהם על המכונה — אין תמליל מקומי לקרוא. רק הפעלות שמבוצעות מקומית תופסות. --- -## הפוך זה פעיל +## הפעל זאת -Capture כבוי עד שתהפוך אותו פעיל. התקן את ה-collector עם API key שיש לו את הרשות `events:add` (ראה [API keys](/he/agenteye/api-keys)), והפוך את ה-Codex capture פעיל: +הקיפור כבוי עד שתפעיל אותו. התקן את הקולט עם מפתח API שיש לו את ההרשאה `events:add` (ראה [API keys](/he/agenteye/api-keys)), והפעל את Codex capture: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -זה מתקין את ה-collector, משנה אותו כ-background service, ומתחיל ללכוד. אשר שהוא פועל: +זה מתקין את הקולט, רושם אותו כשירות רקע, ומתחיל בקיפור. אשר שהוא פועל: ```bash agenteye-collector health ``` -בהפעלה הראשונה, הסשנים ה-Codex הקיימים שלך מתמלאים חזרה פעם אחת ופעילות חדשה ואז זורמת תוך שניות. הקבצים שלהם של Codex עצמם נקראים בלבד — אף פעם לא משונים, מועברים, או מחוקים — וכל סשן נשלח בדיוק פעם אחת, אפילו על פני restarts. +בהפעלה הראשונה, ההפעלות הקיימות של Codex שלך מלאות לאחור פעם אחת ופעילות חדשה אז משדרת תוך שניות. קבצים של Codex עצמו נקראים בלבד — לעולם לא משונים, מעברים או נמחקים — וכל הפעלה משודרת בדיוק פעם אחת, אפילו על פני הפעלות חוזרות. --- -## היכן זה מופיע +## איפה זה מופיע -סשנים תפוסים מופיעים ב-**Sessions**, והאירועים שלהם בזרם **Events**, כמו כל אגנט אחר שאתה צופה בו — כך שה-[session replay](/he/agenteye/sessions), [search](/he/agenteye/queries), [evaluations](/he/agenteye/evaluations), ו-[alerts](/he/agenteye/alerts) כולם עובדים עליהם. סנן לפי ה-Codex agent כדי לראות אותם בעצמם. +הפעלות שנתפסו מופיעות ב-**Sessions**, והאירועים שלהן בזרם **Events**, אותו דבר כמו כל Agent אחר שאתה מצפה — כך [session replay](/he/agenteye/sessions), [search](/he/agenteye/queries), [evaluations](/he/agenteye/evaluations), ו-[alerts](/he/agenteye/alerts) כל עבודה עליהם. סנן לפי ה-Codex agent כדי לראות אותם בעצמם. --- -## Privacy +## פרטיות -Codex transcripts מכילים את הסשן המלא — כולל command output, file contents, וכל מה ש-Codex קרא או כתב — ויכול להכיל סודות. סשנים תפוסים נשלחים כמו שהם, אז הפוך את ה-capture פעיל רק במכונות וצוותים שבהם ריכוז תוכן זה ב-AgentEye הוא מתאים, ותן ל-collector key בהיקף `events:add` בלבד. ראה [Security](/he/agenteye/security) להבנת איך הנתונים שלך מוחזקים מבודדים. \ No newline at end of file +תמלילי Codex מכילים את כל ההפעלה — כולל פלט פקודה, תוכן קבצים וכל דבר שCodex קרא או כתב — ויכולים להכיל סודות. הפעלות שנתפסו משודרות כמו שהן, אז הפעל קיפור רק על מכונות וצוותים שם ריכוז תוכן זה ב-AgentEye מתאים, ותן לקולט מפתח בהיקף `events:add` בלבד. ראה [Security](/he/agenteye/security) לגבי איך הנתונים שלך מוצאים בחיזוק. \ No newline at end of file diff --git a/docs/he/agenteye/concepts.mdx b/docs/he/agenteye/concepts.mdx index 131473d6..54f4e18c 100644 --- a/docs/he/agenteye/concepts.mdx +++ b/docs/he/agenteye/concepts.mdx @@ -1,87 +1,87 @@ --- -title: "קונספטים" -description: "אוצר המילים של Failproof AI Observability — אירועים, סשנים, הערכות, ביקורות, ממצאים, וכרונות — מוגדרים במקום אחד." +title: "מושגים" +description: "אוצר המילים של Failproof AI Observability — אירועים, הפעלות, הערכות, ביקורות, ממצאים והודעות — מוגדרים במקום אחד." --- -עמוד זה מגדיר את אוצר המילים שבו משתמשת Failproof AI Observability. אם מונח בגיד אחר לא מוכר לך, הוא מוגדר כאן. אתה לא חייב לקרוא את זה מתחילה עד סוף: התסקור, או חזור בעת שתיתקל במילה שאתה רוצה להבהיר. +דף זה מגדיר את אוצר המילים שבו משתמש Failproof AI Observability. אם מונח בהנחיה אחרת אינו מוכר לך, הוא מוגדר כאן. אתה לא צריך לקרוא את זה מהסוף להתחלה: תוכל להציץ בו, או לחזור אליו כשתיתקל במילה שאתה רוצה להבין טוב יותר. --- ## מודל הנתונים -**Event** -יחידת הנתונים הקטנה ביותר. אירוע אחד רושם צעד יחיד שהסוכן שלך ביצע: `tool_use`, `model_request`, `hook_completed`, `error`, וכדומה. הסוכן שלך פולט אירועים דרך ה-[Python SDK](/he/agenteye/python-sdk); הם מופיעים בזמן אמת בעמוד **Events**. +**Event (אירוע)** +יחידת הנתונים הקטנה ביותר. אירוע אחד מתעד שלב יחיד שהאגנט שלך בצע: `tool_use`, `model_request`, `hook_completed`, `error`, וכו'. האגנט שלך משדר אירועים דרך [Python SDK](/he/agenteye/python-sdk); הם מופיעים בזמן אמת בעמוד **Events**. -**Session** -ריצה אחת של סוכן, המזוהה על ידי `session_id`. סשן הוא כל האירועים החולקים את המזהה הזה, ממוקדים בשורה יחידה בעמוד **Sessions** וצויירו כגרף ביצוע בעמוד הפרטים שלו. סשן בדרך כלל מתחיל עם `agent_start` ומסתיים עם `agent_end`. +**Session (הפעלה)** +הפעלה אחת של אגנט, המזוהה על ידי `session_id`. הפעלה היא כל האירועים שחולקים את המזהה הזה, מרוכזים לשורה אחת בעמוד **Sessions** ומצויירים כגרף ביצוע בעמוד הפרטים שלה. בדרך כלל הפעלה מתחילה ב-`agent_start` ומסתיימת ב-`agent_end`. -**Agent** -שחקן בעל שם בתוך ריצה, המזוהה על ידי `agent_id`. ריצה יכולה לכלול כמה סוכנים: מתכננן שיוצר תת-סוכן מסכם, לדוגמה. תת-סוכנים נושאים `parent_id`, וזה מה שמאפשר ל-Failproof AI Observability לצייר אותם בנתיבים שלהם בגרף הביצוע. +**Agent (אגנט)** +שחקן בעל שם בהפעלה אחת, המזוהה על ידי `agent_id`. הפעלה יכולה להיות כרוכה בכמה אגנטים: מתכננן שיוצר אגנט תת-הסכמה, לדוגמה. תת-אגנטים נושאים `parent_id`, וזה מה שמאפשר ל-Failproof AI Observability לצייר אותם בנתיבים משלהם בגרף הביצוע. -**Environment** -תווית למקום בו התרחשה הריצה: `production`, `staging`, `dev`. אתה מגדיר את זה פעם אחת כשאתה מגדיר את ה-SDK. כמעט כל עמוד בלוח הבקרה יכול לסנן לפי סביבה. +**Environment (סביבה)** +תווית למקום שבו התרחשה ההפעלה: `production`, `staging`, `dev`. אתה קובע זאת פעם אחת כשאתה מקנפג את ה-SDK. כמעט כל עמוד בלוח המחוונים יכול לסנן לפי סביבה. -**Context-window fill** -אחוז חלון ההקשר של מודל שתגובה צרכה. Failproof AI Observability חוצצה אותו על אירועי `model_response` עבור מודלים שהוא מזהה, כך שגדילת ההנחיה והעימות קרוב יהיו גלויים ממש בזרם האירועים. +**Context-window fill (מילוי חלון הקשר)** +אחוז חלון ההקשר של מודל שתגובה צרכה. Failproof AI Observability חותם אותו על אירועי `model_response` עבור מודלים שהוא מזהה, כך שגדילת ההנחיה והדחיסה המתרחשת גלויה ממש בזרם האירועים. --- ## איכות -**Evaluation** -ציון איכות לסשן שהסתיים, שמופק על ידי שירות ניקוד שאתה מריץ. הערכות הן אופציונליות: עד שאתה מחבר מערך, סשנים מתועדים אך לא מדורגים. כל הערכה יכולה להכיל כמה ציונים בעלי שם (לדוגמה `helpfulness`, `factuality`, `tool_efficiency`), כל אחד עם הערה קצרה של הנמקה. ראה [Evaluation suite](/he/agenteye/evaluation-suite). +**Evaluation (הערכה)** +ניקוד איכות לפעלה שהסתיימה, המיוצר על ידי שירות ניקוד שאתה מפעיל. הערכות הן אופציונליות: עד שתחבר מערכת הערכה, הפעלות נרשמות אך לא מדורגות. כל הערכה יכולה לשאת כמה ניקודים בעלי שם (לדוגמה `helpfulness`, `factuality`, `tool_efficiency`), כל אחד עם הערה קצרה של נימוק. ראה [Evaluation suite](/he/agenteye/evaluation-suite). -**Score key** -שם של ממד אחד שמערך דיווח עליו, כגון `helpfulness`. התראות וביקורות יכולות להסתכל על מפתח ציון ספציפי לאורך זמן. +**Score key (מפתח ניקוד)** +שם של ממד אחד שמערכת הערכה מדווחת עליו, כגון `helpfulness`. התראות וביקורות יכולות לעקוב אחרי מפתח ניקוד ספציפי לאורך זמן. -**Evaluator** -שירות הניקוד שלך. Failproof AI Observability משדרת את התמלול של ריצה שהסתיימה אליו ושומרת את הציונים שהוא מחזיר. זה לא משדר מערך ברירת מחדל; לוגיקת הניקוד היא שלך. +**Evaluator (מערכת הערכה)** +שירות הניקוד שלך. Failproof AI Observability מעביר טרנסקריפט של הפעלה שהסתיימה אליו ושומר את הניקודים שהוא מחזיר. הוא לא משלח מערכת הערכה ברירת מחדל; לוגיקת הניקוד היא שלך. --- ## מציאה ותיקון כשלים -**Hook** -מגן או תופעת לוואי שמסגרת הסוכן שלך מריצה סביב צעד: בדיקת בטיחות תוכן, עריכת PII, שמורת תקציב. Hooks פולטות אירועי `hook_triggered` / `hook_completed` עם `outcome` (allow, deny, modify), ומקבלות את עמוד ההתבוננות שלהן. +**Hook (תפס)** +מעקב בטיחות או תופעת לוואי שמסגרת האגנט שלך מפעילה סביב שלב: בדיקת בטיחות תוכן, עיוור PII, שמירה על תקציב. תפסים משדרים אירועי `hook_triggered` / `hook_completed` עם `outcome` (allow, deny, modify), ויש להם עמוד observe משלהם. -**Alert rule** -כלל שנכנס לפעולה כאשר מטרי חוצה סף שהגדרת: שיעור שגיאות, p95 latency, עלות אסימונים, או ציון מערך. כאשר כלל נכנס לפעולה, הוא פותח כרונה ומודיע לערוצים שבחרת (דוא"ל, Slack, webhook, בתוך לוח הבקרה). ראה [Alerts](/he/agenteye/alerts). +**Alert rule (כלל התראה)** +כלל שמופעל כשמדד חוצה סף שקבעת: שיעור שגיאות, p95 latency, עלות טוקן, או ניקוד של מערכת הערכה. כשכלל מופעל, הוא פותח הודעה ומודיע לערוצים שבחרת (דוא"ל, Slack, webhook, בתוך הלוח). ראה [Alerts](/he/agenteye/alerts). -**Incident** -בעיה פתוחה שנוצרה כאשר כלל התראה נכנס לפעולה. לכרונות יש מחזור חיים (קבל, הקצה, פתור) וציר זמן פעילות שרושם כל פעולה. אתה יכול גם לפתוח אחת ידנית. +**Incident (הודעה)** +בעיה פתוחה שנוצרה כשכלל התראה מופעל. להודעות יש מחזור חיים (acknowledge, assign, resolve) וציר זמן פעילות המתעד כל פעולה. אתה יכול גם לפתוח אחת באופן ידני. -**Audit** -חקירה חוזרת (כל שעה עד שבועית) שחופרת את היומנים שלך *על פני* סשנים לחיפוש דפוסי כשל שלא כתבת כלל עבורם: אשכולות שגיאות, ציונים נמוכים, חריגות latency, לולאות קריאת כלים, וריצות שלא הסתיימו. איפה שהתראה שומרת על מטרי שאתה כבר יודע עליו, ביקורת אומרת לך למה להסתכל הבא. ראה [Audits](/he/agenteye/audits). +**Audit (ביקורת)** +חקירה חוזרת (כל שעה עד שבועי) שחופרת בלוגים שלך *על פני* הפעלות לחיפוש דפוסי כשל שלא כתבת כלל עבורם: צבירי שגיאות, ניקודים נמוכים, יוצאי דופן בעיכוב, לולאות קריאת כלים, והפעלות שלא הסתיימו. כאשר התראה משגחת על מדד שאתה כבר יודע עליו, ביקורת אומרת לך על מה לפנות בהמשך. ראה [Audits](/he/agenteye/audits). -**Finding** -תוצאה אחת דורגת וגיבוי ראיות מריצת ביקורת. מציאה מכנה דפוס, מקשרת להפעלות המדויקות מאחוריו, וממלאה מחזור חיים בדיקה (קבל, פתור, השתק, בטל). Failproof AI Observability מסלקת מציאות פעם על פעם כך שדפוס ידוע מתעדכן במקום להצטבר. +**Finding (ממצא)** +תוצאה אחת דורגת ותומכת בראיות מהפעלת ביקורת. ממצא מתאר דפוס, מקשר להפעלות המדויקות שמאחוריו, ונושא מחזור חיים מיון (acknowledge, resolve, mute, dismiss). Failproof AI Observability משכפל ממצאים מהפעלה להפעלה כדי שדפוס ידוע יעדכן במקום להצטבר. -**The AI assistant** -הצ'אט בתוך לוח הבקרה שמענה לשאלות על הסוכנים שלך באנגלית רגילה, על הנתונים שלך שלך. הוא קריאה בלבד כברירת מחדל; כל דבר שהוא יוצר (שאילתה שמורה, לוח בקרה) מאושר בשער, והוא לא יכול לעולם למחוק. ראה [AI assistant](/he/agenteye/assistant). +**The AI assistant (עוזר AI)** +הצ'אט בתוך הלוח המחוונים שעונה על שאלות לגבי האגנטים שלך בעברית רגילה, על פני הנתונים שלך. הוא קרא-בלבד כברירת מחדל; כל דבר שהוא יוצר (שאילתה שמורה, לוח מחוונים) הוא בעל שער אישור, והוא לא יכול לעולם למחוק. ראה [AI assistant](/he/agenteye/assistant). --- ## הפעלה -**Organization (tenant)** -סביבת עבודה מבודדת. מופע אחד של Failproof AI Observability יכול להנחות ארגונים רבים, כל אחד עם המשתמשים, המפתחות, וההנתונים שלו. כל URL של לוח בקרה מסודר בהיקף של ה-slug הארגוני שלך (`//…`). +**Organization (tenant) (ארגון)** +סביבת עבודה מבודדת. מופע אחד של Failproof AI Observability יכול להעביר ארגונים רבים, כל אחד עם המשתמשים, המפתחות והנתונים שלו. כל כתובת URL של לוח מחוונים חסומה תחת slug ארגונך (`//…`). -**Collector** -`agenteye-collector`, הדמון הקל שרץ בכל מכונת סוכן, מקבץ את האירועים שה-SDK כותב לדיסק, ומשדר אותם לשרת. +**Collector (אספן)** +`agenteye-collector`, תהליך שדמות קל שפועל על כל מכונת אגנט, בודד את האירועים שה-SDK כותב לדיסק, ומשדר אותם לשרת. -**API key** -אסימון בהיקף זה מאמת לקוח כנגד השרת. מפתחות נושאים הרשאות דקיקות (לדוגמה `events:add` עבור הקולט, היקפי קריאה בלבד עבור מפתח לוח בקרה). ראה [API keys](/he/agenteye/api-keys). +**API key (מפתח API)** +אסימון בהיקף שמאמת קלায נט מול השרת. מפתחות נושאים הרשאות תחום-דקיק (לדוגמה `events:add` עבור האספן, היקפים קרא-בלבד עבור מפתח לוח מחוונים). ראה [API keys](/he/agenteye/api-keys). -**Server** -שירות ההשקעה וה-API. הוא משקיע אירועים, שומר מצב תפעולי בבסיסי הנתונים שלך, ומשרת את לוח הבקרה וה-CLI. +**Server (שרת)** +שירות ספיגה וAPI. הוא ספוג אירועים, אחסן מצב תפעולי במסדי הנתונים שלך, ומגדם את הלוח המחוונים וה-CLI. -**Dashboard** -ממשק המשתמש של האינטרנט. כל עמוד מסודר לארגון ו קורא דרך API של השרת. +**Dashboard (לוח מחוונים)** +ממשק המשתמש של האינטרנט. כל עמוד חסום לארגון ופועל דרך API של השרת. --- -## צעדים הבאים +## שלבים הבאים -- [Overview](/he/agenteye/overview): איך החלקים האלה מתאימים יחד. -- [Observability](/he/agenteye/observability): משטחי ההתבוננות (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file +- [Overview](/he/agenteye/overview): כיצד חלקים אלו משתלבים יחד. +- [Observability](/he/agenteye/observability): משטחי התצפית (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file diff --git a/docs/he/agenteye/dashboards.mdx b/docs/he/agenteye/dashboards.mdx index 3870ea5b..d4b273de 100644 --- a/docs/he/agenteye/dashboards.mdx +++ b/docs/he/agenteye/dashboards.mdx @@ -1,46 +1,46 @@ --- -title: "לוחות בקרה" -description: "הפוך את נתוני הסוכן הלייב שלך לתמונה משותפת אחת שכל הצוות שלך משקיף עליה." +title: "לוחות מחוונים" +description: "הפוך את נתוני הסוכן החי שלך לתמונה משותפת אחת שכל הצוות שלך צופה בה." --- -הפוך את נתוני הסוכן הלייב שלך לתמונה משותפת אחת שכל הצוות שלך משקיף עליה. הצמד את השאילתות החשובות ביותר כגרפים, וכולם יפתחו את אותם מספרים במבט אחד, ללא הרצה חוזרת של שאילתה אחת. +הפוך את נתוני הסוכן החי שלך לתמונה משותפת אחת שכל הצוות שלך צופה בה. הצמד את השאילתות החשובות כגרפים, וכולם פותחים את אותם מספרים במבט אחד, בלי להריץ שום שאילתה מחדש. -![לוח בקרה הבנוי משאילתות שמורות: קו אירועים לשעה, עמודות שגיאות לפי סוג, גרף שטח של השהיה, ואסימונים לפי מודל](/agenteye/images/dashboard-fleet.png) +![לוח מחוונים שנבנה משאילתות שמורות: קו של אירועים לשעה, עמודה של שגיאות לפי סוג, גרף שטח של חביון, וטוקנים לפי מודל](/agenteye/images/dashboard-fleet.png) -*לוח אחד, ארבע שאילתות שמורות: אירועים לשעה, שגיאות לפי סוג, השהיה, ואסימונים לפי מודל.* +*לוח אחד, ארבע שאילתות שמורות: אירועים לשעה, שגיאות לפי סוג, חביון וטוקנים לפי מודל.* -## כולם רואים את אותה אמת +## כולם רואים את אותה האמת -הפסק להדביק צילומי מסך לצ'אט והפסק להריץ את אותה שאילתה חמש פעמים ביום. לוח בקרה הוא לוח משותף ברמת הארגון שכל חבר בצוות שלך יכול לפתוח כדי לראות את אותו הנוף בדיוק. כאשר הנתונים הבסיסיים משתנים, הגרפים משתנים איתם, כך שהלוח תמיד עדכני ואף אחד לא מתווכח על מספרים ישנים. +תפסיקו להדביק צילומי מסך לצ'אט ותפסיקו להריץ את אותה השאילתה חמש פעמים ביום. לוח מחוונים הוא לוח משותף בקנה מידה ארגוני שכל אחד בצוות שלכם יכול לפתוח ולראות אותה התצוגה בדיוק. כשהנתונים הבסיסיים משתנים, הגרפים משתנים איתם, כך שהלוח תמיד עדכני ולא אחד מתווכחים על מספרים יישנים. -לוח הצי לעיל הוא צורה טובה להתחלה לפעולות יומיומיות: +לוח הצי שלמעלה הוא צורה טובה להתחיל בה לפעילויות יומיומיות: -- שורת **אירועים-לשעה**, כך שתוכל לצפות בתפוקה ולתפוס ירידה פתאומית -- עמודות **שגיאות-לפי-סוג**, כך שקטגוריות הכשל הגדולות ביותר שלך בולטות -- גרף שטח של **השהיה**, כך שההאטות מופיעות לפני שמשתמשים מתלוננים -- פירוט **אסימונים-לפי-מודל**, כך שהעלות נשארת בשדה הראייה +- קו **אירועים-לשעה**, כדי שתוכלו לצפות בתפוקה ולתפוס ירידה פתאומית +- עמודה **שגיאות-לפי-סוג**, כך שקטגוריות הכישלון הגדולות שלכם יבלטו +- גרף שטח **חביון**, כדי שהאטות יופיעו לפני שמשתמשים יתלוננו +- פירוט **טוקנים-לפי-מודל**, כך שהעלות תישאר בתצוגה -תמצא את הלוחות שלך ב `//dashboards`. +את הלוחות שלכם תמצאו ב־`//dashboards`. -## הצמד את השאילתות שכבר שמרת +## הצמדו את השאילתות שכבר שמרתם -כל אריח מתחיל כשאילתה שמורה. בנה ושמור את השאילתה שחשובה לך בספריית [Queries](/he/agenteye/queries) (הגדרות מוגדרות מראש בנוסף לשלך, על האירועים וההערכות שלך), ואז הצמד אותה ללוח בקרה כגרף המתאים לנתונים: **שורה** לטרנדים לאורך זמן, **עמודות** להשוואת קטגוריות, **שטח** לנפח, או **עוגה** לפירוט חלקים. +כל רעפה מתחילה כשאילתה שמורה. בנו ושמרו את השאילתה החשובה לכם בספרייה [שאילתות](/he/agenteye/queries) (קביעות מובנות בתוספת שלכם, על האירועים וההערכות שלכם), ואז הצמדו אותה ללוח מחוונים כגרף המתאים לנתונים: **קו** לטרנדים לאורך זמן, **עמודה** להשוואת קטגוריות, **שטח** לנפח, או **עוגה** לפירוט שיתוף. -מכיוון שאריח הוא פשוט השאילתה השמורה שלך המוצגת כגרף, אין כלום שצריך להסנכרן ביד. עדכן את השאילתה פעם אחת וכל לוח בקרה שמשתמש בה יתעדכן גם כן. +מכיוון שרעפה היא פשוט השאילתה השמורה שלכם המוצגת כגרף, אין כלום להשמור בסינכרון ידני. עדכנו את השאילתה פעם אחת וכל לוח מחוונים שמשתמש בה מתעדכן גם כן. -## צפה באיכות, לא רק בנפח +## צפו בכמות, לא רק בנפח -נפח אומר לך שהסוכנים עסוקים. איכות אומרת לך שהם באמת עושים את העבודה. כוונן לוח בקרה ל[ניקוד ההערכות](/he/agenteye/evaluations) שלך ותקבל לוח שעוקב אחרי עד כמה טוב הרצות מתנהלות לאורך זמן, כך שרגרסיה באיכות תופיע כטבילה בגרף במקום הפתעה מלקוח. +נפח מגיד לכם שהסוכנים עסוקים. איכות מגידה לכם שהם בעצם עושים את העבודה. כווונו לוח מחוונים לעברך [ציוני ההערכה](/he/agenteye/evaluations) שלכם ותקבלו לוח המעקב אחרי עד כמה טוב הריצות הולכות לאורך זמן, כך שרגרסיה בתכונה תופיע כשקע בגרף במקום הפתעה מלקוח. -![לוח בקרה ממוקד איכות הבנוי משאילתות הערכה שמורות](/agenteye/images/dashboard-quality.png) +![לוח מחוונים ממוקד באיכות שנבנה משאילתות הערכה שמורות](/agenteye/images/dashboard-quality.png) -*לוח איכות שומר את ניקוד ההערכות שלך בחזית, ממש לצד המספרים התפעוליים.* +*לוח איכות מחזיק את ציוני ההערכה שלכם במרכז הדעת, ממש ליד המספרים התפעוליים.* -שמור לוח פעולות ולוח איכות זה לצד זה וצוות שלך יש מקום אחד לענות על שתי השאלות "האם זה עובד?" ו"האם זה טוב?", ללא שמישהו מריץ שוב שאילתה. +שמרו לוח פעילויות ולוח איכות זה לצד זה והצוות שלכם יש לו מקום אחד לענות על שתי השאלות "האם זה עובד?" ו"האם זה טוב?", בלי שאיש יריץ שאילתה מחדש. ## קשור -- [Queries](/he/agenteye/queries): בנה ושמור את השאילתות שהופכות לאריחים שלך. -- [Evaluations](/he/agenteye/evaluations): דרג את ההרצות שלך כך שתוכל לתרשים איכות לאורך זמן. -- [Alerts](/he/agenteye/alerts): הפוך סף בכל אחד מהמדדים הללו לעמוד. \ No newline at end of file +- [שאילתות](/he/agenteye/queries): בנו ושמרו את השאילתות שהופכות לרעפות שלכם. +- [הערכות](/he/agenteye/evaluations): קבעו ציון לריצות שלכם כדי שתוכלו לתרשים איכות לאורך זמן. +- [התראות](/he/agenteye/alerts): הפכו ערך סף על כל אחד מהמדדים הללו לעמוד. \ No newline at end of file diff --git a/docs/he/agenteye/error-tracking.mdx b/docs/he/agenteye/error-tracking.mdx index dd68a0fb..eaf647a7 100644 --- a/docs/he/agenteye/error-tracking.mdx +++ b/docs/he/agenteye/error-tracking.mdx @@ -1,41 +1,40 @@ --- -title: "עקיבות שגיאות" -description: "ראה כל כשל שהסוכנים שלך מייצרים במקום אחד, מקובצים כך שפיצוץ רועם נקרא כבעיה אחת." +title: "עקיבות אחר שגיאות" +description: "ראו כל כשל שהסוכנים שלכם יוצרים במקום אחד, מקובצים כך שפרץ רועם נקרא כבעיה יחידה." --- +ראו כל כשל שהסוכנים שלכם יוצרים במקום אחד, מקובצים כך שפרץ רועם נקרא כבעיה יחידה. אתם מקבלים נתיב בלחיצה אחת מ"משהו בצבע אדום" לריצה המדויקת שנשברה, בלי גלילה בזרימת ישיר כדי למצוא אותה. -ראה כל כשל שהסוכנים שלך מייצרים במקום אחד, מקובצים כך שפיצוץ רועם נקרא כבעיה אחת. אתה מקבל נתיב בלחיצה אחת מ"משהו אדום" לריצה המדויקת שהשתברה, ללא צורך בגלילה בזרם חי כדי למצוא אותה. +![עמוד השגיאות: היסטוגרמה של כשלים לאורך זמן מעל שורות שגיאה אדומות מקובצות, כל אחת עם כפתור "+ alert" בלחיצה אחת](/agenteye/images/errors.png) +*עמוד השגיאות: היסטוגרמה של כשלים לאורך זמן, עם כשלים חוזרים שקרסו לשורה אחת לכל תקרית.* -![עמוד השגיאות: היסטוגרמה של כשלים לאורך זמן מעל שורות שגיאה אדומות מקובצות, כל אחת עם כפתור "+התראה" בלחיצה אחת](/agenteye/images/errors.png) -*עמוד השגיאות: היסטוגרמה של כשלים לאורך זמן, כשכשלים חוזרים מקופלים לשורה אחת לכל תקרית.* +## כל כשל, כבר אוסף עבורכם -## כל כשל, כבר אסוף עבורך +כאשר סוכן נשבר, לא צריך לגלול בזרימת אירועים ישירה בתקווה לתפוס את השורות האדומות לפני שהן גולשות. עמוד **השגיאות** עושה את האיסוף עבורכם. הוא מרכיב הכל מה שלוח המחוונים היה צובע באדום למשטח טריאז יחיד, כך שהדבר הראשון שאתם רואים הוא מה נכשל, לא לאן ללכת לחפש אותו. -כאשר סוכן משתבר, לא צריך לגלול בזרם אירועים חי בתקווה לתפוס את השורות האדומות לפני שהן גללו. עמוד **השגיאות** עושה את האיסוף בשבילך. הוא אוסף הכל שלוח המחוונים היה צובע באדום למשטח ניתוח אחד, כך שהדבר הראשון שאתה רואה הוא מה נכשל, לא היכן ללכת לחפש אותו. +וזה תופס יותר מזה הברור. לצד אירועי `error` ברורים, Failproof AI Observability משטח גם את הכשלים השקטים: כל `tool_result`, `hook_completed`, או `agent_end` שהמטען שלהם נושא כשל מופיע כאן. כלי שהחזיר שגיאה, או hook שיצא בצורה גרועה, כבר לא משתמט מעברכם רק כי לא הוטלה יוצאת דופן קולנית. -וזה תופס יותר מהברורות. לצד אירועי `error` מפורשים, Failproof AI Observability משטח גם את הכשלים השקטים: כל `tool_result`, `hook_completed`, או `agent_end` שהמטען שלו נושא כשל מופיע כאן. כלי שהחזיר שגיאה, או hook שיצא בצורה גרועה, כבר לא מחמק אליך רק מכיוון שלא הטילו חריג חזק. +על פני החלק העליון, היסטוגרמה משרטטת שגיאות לאורך זמן. מבט אחד אומר לכם אם זה זרימה רקע יציבה או דחף שהתחיל לפני כמה דקות, כך שתדעו מיד אם להפסיק מה שאתם עושים. -על פני החלק העליון, היסטוגרמה מתווה שגיאות לאורך זמן. מבט אחד אומר לך האם זה זרימה עמוקה קבועה או דוקן שהתחיל לפני כמה דקות, כך שאתה יודע מיד האם להשליך מה שאתה עושה. - -כמו כל משטח צפייה, עמוד השגיאות מסוגנן לארגון שלך ומסננים לפי טווח תאריכים, סביבה, סוכן וסשן. זה אומר שאתה יכול לקחת רשימת קfleet רחבה ולהצמצם אותה לסוכן אחד או סביבה אחת שאכפת לך בעצם. +כמו כל משטח observe, עמוד השגיאות מוגבל לארגון שלכם ומסנן לפי טווח תאריכים, סביבה, סוכן וסשן. זה אומר שאתם יכולים לקחת רשימה בקנה מידה צי ולצמצם אותה לסוכן אחד או סביבה אחת שאתם באמת אכפת לכם. ## תקרית אחת, לא מאה שורות זהות -תלות אחת שבורה יכולה להדליק את אותה שגיאה מאות פעמים בדקה. נותרה גולמית, זו קיר של קווים כמעט זהים שקוברים את הדבר האחד שאתה בעצם צריך לראות. +תלות אחת שנשברה יכולה להירות את אותה שגיאה מאות פעמים בדקה. אם משאירים בחום, זה קיר של שורות כמעט זהות שטומן את הדבר היחיד שאתם באמת צריכים לראות. -Failproof AI Observability מקפל כשלים חוזרים השותפים לאותו סשן וסוג שגיאה לשורה אחת. פיצוץ נקרא כתקרית אחת. בסוף אתה סופר בעיות, לא שורות log, והאות שחשובה נשארת על גבי במקום להיות טבולה בנפחה שלה. +Failproof AI Observability קורס כשלים חוזרים החולקים את אותו סשן וסוג שגיאה לשורה יחידה. פרץ נקרא כתקרית אחת. בסופו של דבר אתם סופרים בעיות, לא שורות log, והאות שחשובה נשארת למעלה במקום להיות טבועה בנפחה שלה. -## מ"משהו אדום" לאירוע המדויק +## מ"משהו בצבע אדום" לאירוע המדויק -לחץ על כל שורה כדי להנחות ישר בתוך הסשן של הריצה הזו, ממוקם על האירוע המדויק שנכשל. אין העתקת מזהי סשן, אין גלילה כדי לחפש את הרגע שזה השתבר: אתה מגיע לזה, כשגרף הביצוע המלא במבט אחד כך שאתה יכול לראות מה הסוכן עשה בשניות לפני שזה השתבר. +לחצו על כל שורה כדי להנחות ישר לתוך הסשן של ההרצה, מעמדים על האירוע המדויק שנכשל. לא העתקת מזהי סשן, לא גלילה כדי לחפש את הרגע שהוא הלך לרעה: אתם מגיעים ממש אליו, עם גרף ההוצאה המלא בהצצה אחת משם כך שתוכלו לראות מה הסוכן עשה ברגעים לפני שהוא נשבר. -אם יש לך `alerts:write`, כל שורה גם נושאת כפתור **+התראה**. לחץ עליו ו-Observability פותח כלל התראה חדש כבר מלא כדי לתפוס את אותו כשל שוב. התקרית שזה עתה ערכת ניתוח הופכת לזו שמעמודה אותך בפעם הבאה, במקום להפתיע אותך פעמיים. +אם יש לכם `alerts:write`, כל שורה גם נושאת כפתור **+ alert**. לחצו עליו ו-Observability פותח כלל alert חדש כבר מלא כדי לתפוס את אותו כשל שוב. התקרית שאתם זה עתה ביצעתם triage לה הופכת לזו שתדפיק אתכם בפעם הבאה, במקום להפתיע אתכם פעמיים. -**היכן למצוא זה:** עמוד **השגיאות** חי בסעיף הצפייה של לוח המחוונים, ב `//errors`. +**איפה למצוא אותו:** עמוד **השגיאות** חי בסעיף observe של לוח המחוונים, ב-`//errors`. ## קשור -- [התראות](/he/agenteye/alerts): הפוך כל כשל לכלל עמודה. -- [תקריות](/he/agenteye/incidents): עקוב אחר התראה שנורה מפתיחה לפתרון. -- [סשנים](/he/agenteye/sessions): פתח את הריצה המלאה מאחורי כל שגיאה. -- [ביקורות](/he/agenteye/audits): תן ל-Observability למצוא דפוסי כשל על פני הריצות שלך בשבילך. \ No newline at end of file +- [Alerts](/he/agenteye/alerts): הפוך כל כשל לכלל paging. +- [Incidents](/he/agenteye/incidents): עקוב אחר alert שנורה מפתיחה לפתרון. +- [Sessions](/he/agenteye/sessions): פתח את ההרצה המלאה מאחורי כל שגיאה. +- [Audits](/he/agenteye/audits): תן ל-Observability למצוא דפוסי כשל על פני הריצות שלך עבורך. \ No newline at end of file diff --git a/docs/he/agenteye/evaluation-suite.mdx b/docs/he/agenteye/evaluation-suite.mdx index 18fe96fb..6a5b1dbf 100644 --- a/docs/he/agenteye/evaluation-suite.mdx +++ b/docs/he/agenteye/evaluation-suite.mdx @@ -1,21 +1,21 @@ --- title: "חבילת הערכה" -description: "Failproof AI Observability יכול לדרג באופן אוטומטי כל הרצה של סוכן שהסתיימה מבחינת איכות: אתה מספק שירות דירוג קטן, ו-Observability מטפל בשאר." +description: "Failproof AI Observability יכול לדרג באופן אוטומטי כל הפעלת agent שהסתיימה לפי איכות: אתה מספק שירות דירוג קטן, ו-Observability מטפל בשאר." --- -Failproof AI Observability יכול לדרג באופן אוטומטי כל הרצה של סוכן שהסתיימה מבחינת איכות: אתה מספק שירות דירוג קטן, ו-Observability מטפל בשאר. השתמש בו כדי לעקוב אחר הממדים שחשובים לך (עזרתיות, יעילות כלים, עובדתיות, בטיחות; אתה בוחר), לתפוס רגרסיות מוקדם, ולהשוות סוכנים או סביבות בהצצה. הדירוג הוא אופציונלי: הצינור לא עושה כלום עד שתגדיר את `EVALUATOR_ENDPOINT` בשרת. +Failproof AI Observability יכול לדרג באופן אוטומטי כל הפעלת agent שהסתיימה לפי איכות: אתה מספק שירות דירוג קטן, ו-Observability מטפל בשאר. השתמש בו כדי לעקוב אחרי הממדים שחשובים לך (עזרתיות, יעילות כלים, עובדתיות, בטיחות; אתה בוחר), לתפוס נסיגות מוקדם, והשוואת agents או סביבות בהצצה. הדירוג הוא התנייה: ה-pipeline לא עושה כלום עד שתקביע `EVALUATOR_ENDPOINT` בשרת. -> **הערה:** אתה מגדיר את ממדי הציון. ההערכה שלך יכולה להחזיר כל מפתחות מספריים שהיא רוצה; Observability אחסן, טרנד ומציג כל מה שאתה שולח חזרה. +> **הערה:** אתה מגדיר את ממדי הדירוג. ה-evaluator שלך יכול להחזיר כל מפתחות מספריים שהוא רוצה; Observability שומר, מנטר, ומציג כל מה שאתה שולח בחזרה. -## במבט חטוף +## בהצצה -1. **כתוב מדרג.** הקם שירות HTTP קטן שקורא תמליל של סשן ומחזיר ציונים. Observability משלח התייחסות עובדת שאתה יכול להעתיק. ראה [כתיבת מעריך עם ה-SDK](#writing-an-evaluator-with-the-sdk). -2. **הצביע ל-Observability על זה.** קבע את `EVALUATOR_ENDPOINT` (ו-`EVALUATOR_TOKEN` משותף) בתהליך השרת. -3. **צפה בציונים שנחתו.** כל סשן שהסתיים מדורג באופן אוטומטי; התוצאות מופיעות בעמוד פרטי הסשן, בגריד הסשנים ובלוחות שנשמרו. +1. **כתוב דירוג.** הצב שירות HTTP קטן שקורא תמליל של session ומחזיר ניקוד. Observability משלח הפניה עובדת שאתה יכול להעתיק. ראה [כתיבת evaluator עם ה-SDK](#writing-an-evaluator-with-the-sdk). +2. **סמן את Observability אליו.** קבע `EVALUATOR_ENDPOINT` (ו-`EVALUATOR_TOKEN` משותף) בתהליך השרת. +3. **צפה בניקוד שמגיע.** כל session שהושלם מדורג באופן אוטומטי; התוצאות מופיעות בעמוד פרטי ה-session, ברשת ה-sessions, וב-dashboards שמורים. -![תצוגת פרטי סשן עם סיכום ההערכה, סרגלי ציון לממד, וטקסט נמקות בפס ימני](/agenteye/images/session-detail.png) +![תצוגת פרטי session עם סיכום הערכה, ברים ניקוד לכל ממד, וטקסט נימוק בפס הימני](/agenteye/images/session-detail.png) -*לאחר הגדרת מעריך, כל הרצה שהושלמה מדורגת והתוצאות מופיעות בפס הימני של הסשן: הסיכום בחלק העליון, ואחריו סרגלי ציון לממד עם נמקות.* +*לאחר שמודיל evaluator מוגדר, כל הפעלה שהושלמה מדורגת והתוצאות מופיעות בפס הימני של ה-session: הסיכום בחלקו העליון, ולאחר מכן ברים ניקוד לכל ממד עם נימוק.* --- @@ -31,44 +31,44 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -כאשר Failproof AI Observability SDK פולט אירוע `agent_end` לסשן, השרת מתכנן הערכה. לאחר מכן הוא עושה POST של תמליל האירוע המלא לשירות ההערכה שלך, שיכול: +כאשר Failproof AI Observability SDK פולט אירוע `agent_end` ל-session, השרת מתעד הערכה. לאחר מכן הוא משדר את תמליל האירוע המלא לשירות ה-evaluator שלך, שיכול: -- **להחזיר את התוצאה בשורה** עם `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. התוצאה מנוספת לציר הזמן של ההערכה של הסשן. `reasoning` ו-`summary` הם אופציונליים. -- **לדחות** עם `{"status":"pending", "job_id":"abc-123"}`. Observability ואז קורא `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` עד שההערכה שלך מחזירה `{"status":"done", ...}` או `{"status":"error", "error":"..."}`. +- **להחזיר את התוצאה באופן מיידי** עם `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. התוצאה מתווספת לציר הזמן של הערכת ה-session. `reasoning` ו-`summary` הם אופציונליים. +- **לדחות** עם `{"status":"pending", "job_id":"abc-123"}`. Observability אז קורא ל-`GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` עד שה-evaluator שלך מחזיר `{"status":"done", ...}` או `{"status":"error", "error":"..."}`. - קצב הסקר הוא לכל עבודה: תגובת `pending` עשויה לכלול `next_poll_secs` כדי לדרוג; אחרת Observability משתמש בערך `default_poll_interval_secs` מ-`GET /config`; אחרת השרת חוזר אל `EVALUATOR_POLLING_INTERVAL_SECS` (ברירת מחדל 10 שניות). כל הערכים מוגבלים ל-[1 שניה, 1 שעה]. + קצב ה-polling הוא לכל job: תגובת `pending` עשויה לכלול `next_poll_secs` כדי להחריג; אחרת Observability משתמש בערך `default_poll_interval_secs` מ-`GET /config`; אחרת השרת חוזר ל-`EVALUATOR_POLLING_INTERVAL_SECS` (ברירת מחדל 10 שניות). כל הערכים מוגבלים ל-[1s, 1h]. -סשנים שלא פלטו `agent_end` (לדוגמה, תהליך סוכן שהתרסק) יכולים גם להיאסף: `GET /config` של ההערכה עשוי להחזיר `{"inactivity_timeout_secs": 1800}`, וה-Observability יעריך כל סשן שנשמר בחוסר פעילות לפי זמן זה. קבע את השדה ל-`null` או השמיט אותו כדי להשבית את הנופל החלופי. +Sessions שלעולם לא פולטים `agent_end` (לדוגמה, תהליך agent שקרס) יכול גם להיות נבחר: `GET /config` של ה-evaluator עשוי להחזיר `{"inactivity_timeout_secs": 1800}`, ו-Observability יעריך כל session שהיה inactive לפרק זמן כה ארוך. קבע את השדה ל-`null` או השמט אותו כדי להשבית את ה-fallback זה. -הצינור הוא כל ל-no-op כאשר `EVALUATOR_ENDPOINT` לא מוגדר. +ה-pipeline הוא no-op לחלוטין כאשר `EVALUATOR_ENDPOINT` לא מוגדר. -סשן יכול להצטבר **הערכות מסוף מרובות לאורך זמן**: כל אירוע `agent_end` (וכל הערכה חוזרת ידנית מלוח המחוונים) מוסיף שורת הערכה חדשה. זוהי הדרך הנתמכת להערכת שיחה שנעתקה: משתמש מסיים סוכן, חוזר מאוחר יותר, שולח עוד אירועים, מסיים את הסוכן שוב, והערכה שנייה רצה כנגד התמליל המעודכן המלא. לוח המחוונים משרטט את ההערכה העדכנית ביותר כהכותרת והערכות הקודמות כציר זמן ניתן לצמצום. בזמן שהערכה אחת פועלת לסשן, אירועי `agent_end` נוספים עבור אותו סשן מתעלמים; האחד הבא לאחר השלמת ההערכה הפועלת יתור הערכה טרייה כרגיל. +Session יכול להצטבר **מספר הערכות סיום לאורך זמן**: כל אירוע `agent_end` (וכל re-eval ידני מה-dashboard) מוסיף שורת הערכה טרייה. זו הדרך הנתמכת להערכת שיחה מחודשת: משתמש מסיים agent, חוזר מאוחר יותר, שולח עוד אירועים, מסיים את ה-agent שוב, והערכה שנייה רצה כנגד התמליל המעודכן המלא. ה-dashboard מציג את ההערכה האחרונה כמטבח וההערכות הקודמות כציר זמן שניתן לכיווץ. כאשר הערכה אחת פועלת לכל session, אירועי `agent_end` נוספים לאותו session מתעלמים; הבא לאחר סיום ההערכה הפעמונית יתערער הערכה טרייה כרגיל. -הנופל החלופי של חוסר פעילות מחדש בסשנים שנעתקו: אם אירועים חדשים מגיעים לאחר הערכה סוף קודמת וסשן ואז הולך ללא פעילות בעבר `inactivity_timeout_secs`, הערכה טרייה מתורה. +ה-fallback inactivity מתחדש גם ב-sessions המחודשים: אם אירועים חדשים מגיעים אחרי הערכה טרמינלית קודמת והתא אז הופך ל-idle בעבר `inactivity_timeout_secs`, הערכה טרייה מתערערת. -כשלים חולפים (5xx, 429, timeouts, שגיאות רשת) מנסים שוב עם backoff אקספוננציאלי עד `EVALUATOR_MAX_ATTEMPTS`; תגובות 4xx הן סופיות. Observability בטוח להריץ עם מספר מקבלות שרת במרובה; העבודה מחולקת כך שאותו סשן לעולם לא יישלח פעמיים במקביל. +כשלים שעלולים (5xx, 429, timeouts, שגיאות רשת) נסמנו בחזרה עם exponential backoff עד ל-`EVALUATOR_MAX_ATTEMPTS`; תגובות 4xx הן טרמינליות. Observability בטוח לריצה עם מספר instances של שרת בקנה מידה אופקי; העבודה מחולקת כך שאותו session לעולם לא מיוצא פעמיים בו-זמנית. --- ## חוזה HTTP -כל מסלול מאומת משתמש **ב-Bearer Token Auth**. אותו ערך חייב להיות מוגדר משני הצדדים: +כל מסלול מאומת משתמש **באימות bearer token**. אותו ערך חייב להיות מוגדר משני הצדדים: - שרת Observability: משתנה env `EVALUATOR_TOKEN` -- שירות Evaluator: מוגדר באותו אופן (ה-SDK `agenteye-evaluator` קורא `EVALUATOR_TOKEN` לפי מוסכמה) +- שירות Evaluator: מוגדר בדרך זהה (ה-SDK `agenteye-evaluator` קורא ל-`EVALUATOR_TOKEN` לפי כנס) -אם `EVALUATOR_TOKEN` לא מוגדר, השרת לא שולח כותרת `Authorization`; ההערכה עשויה לקבל בקשות אנונימיות, שזה בסדר לרשת פנימית בלבד אך מודחה באינטרנט הציבורי. +אם `EVALUATOR_TOKEN` לא מוגדר, השרת לא שולח כותרת `Authorization`; ה-evaluator עשוי להקבל בקשות אנונימיות, שזה בסדר לרשת פנימית בלבד אך לא מומלץ ב-public internet. -### נתיבים שההערכה חייבת להגיש +### מסלולים שה-evaluator חייב להגיש -| נתיב | גוף / פרמטרים | תגובה | +| מסלול | גוף / params | תגובה | |---|---|---| -| `GET /health` | ללא | `{"status":"ok"}` (פתוח, ללא auth) | -| `GET /config` | ללא | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | +| `GET /health` | אף אחד | `{"status":"ok"}` (פתוח, ללא auth) | +| `GET /config` | אף אחד | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | | `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` או `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | ללא | אותה צורת תגובה כמו `/evaluate` | +| `GET /evaluate/{id}` | אף אחד | אותה צורת תגובה כמו `/evaluate` | -### גוף `EvalRequest` שנשלח על ידי השרת +### גוף `EvalRequest` ששולח השרת ```json { @@ -87,7 +87,7 @@ flowchart LR ### צורות תגובה -**סינכרוני (בוצע):** +**Sync (done):** ```json { @@ -101,33 +101,33 @@ flowchart LR } ``` -`reasoning` (מפת הנמקה לכל ציון) ו-`summary` (נרטיב אחד-פסקה כולל) שניהם אופציונליים. מפתחות ב-`reasoning` צריכים לשקף מפתחות ב-`scores`; לוח המחוונים משרטט כל ערך בשורה מתחת לסרגל הציון שלו. הערכות ישנות יותר שמחזירות רק `scores` ממשיכות לעבוד ללא שינוי; `reasoning` ו-`summary` פשוט קוראים כ-null ויכולות ה-UI המתאימות מושמטות. +`reasoning` (מפת הצדקה לכל ניקוד) ו-`summary` (נרטיב כללי של פסקה אחת) שניהם אופציונליים. מפתחות ב-`reasoning` צריכים לשקף מפתחות ב-`scores`; ה-dashboard מעבד כל ערך בשורה מתחת לסרגל הניקוד שלו. Evaluators ישנים יותר שמחזירים רק `scores` ממשיכים לעבוד ללא שינוי; `reasoning` ו-`summary` פשוט קוראים כ-null וה-affordances ה-UI המתאימים מושמטים. -**אסינכרוני (דחוי):** +**Async (deferred):** ```json { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` הוא אופציונלי; אם מושמט השרת חוזר ל-`default_poll_interval_secs` של ההערכה מ-`/config`, ואז ל-משתנה ה-env `EVALUATOR_POLLING_INTERVAL_SECS` שלו. +`next_poll_secs` אופציונלי; אם מושמט השרת חוזר ל-`default_poll_interval_secs` של ה-evaluator מ-`/config`, ואז לשלו `EVALUATOR_POLLING_INTERVAL_SECS` env var. -**שגיאה סופית בצד המעריך:** +**שגיאת טרמינלית בצד evaluator:** ```json { "status": "error", "error": "model service unavailable" } ``` -השרת מתייחס לכל גוף 2xx אחר כשגיאת פרוטוקול ורושם `error` סופי לסשן. +השרת מעשה כל גוף 2xx אחר כשגיאת פרוטוקול ורוב טרמינלי `error` עבור ה-session. --- -## כתיבת מעריך עם ה-SDK +## כתיבת evaluator עם ה-SDK -אתה לא חייב ליישם את חוזה HTTP ביד. החבילה Python `agenteye-evaluator` נותנת לך ליפוף FastAPI מוקלד שמטפל בהתאמה, ניתוב וצורות בקשה/תגובה בשבילך. +אתה לא צריך ליישם את חוזה HTTP ביד. חבילת Python `agenteye-evaluator` נותן לך wrapper FastAPI מוקלד המטפל באימות, ניתוב, וצורות בקשה/תגובה בעבורך. -Failproof AI Observability גם משלח **מעריך התייחסות עובד** שמדרג `helpfulness`, `tool_efficiency` ו-`factuality` מצורת התמליל. העתק אותו כנקודת התחלה וחליף בלוגיקה שלך: שופט LLM, מנוע כללים, כל מה שמתאים לסטנדרט האיכות שלך. +Failproof AI Observability גם משלח **evaluator הפניה עובדת** שדורג `helpfulness`, `tool_efficiency`, ו-`factuality` מצורת התמליל. העתק אותו כנקודת התחלה וחליף בלוגיקה שלך: שופט LLM, מנוע כללים, כל מה שמתאים להגדרת הכיוונון שלך. -מעריך ברור ברירת מחדל: +Evaluator מינימלי שניתן to liveliness: ```python import os @@ -146,60 +146,60 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -מופע ה-`app` פועל תחת כל שרת ASGI, כך שתחילת `uvicorn module:app`. +מופע `app` פועל תחת כל שרת ASGI, אז `uvicorn module:app` מתחיל אותו. -עבור הערכות שצריכות לדחות עבודה יקרה, החזור ב-`JobPending` בעוד רושם `@app.job_lookup` handler; שרת Observability סוקר `GET /evaluate/{job_id}` עד שתחזיר סטטוס סופי או עד שהמכסה `EVALUATOR_MAX_POLL_DURATION_SECS` (ברירת מחדל 1 שעה) חולפת. +עבור evaluators שצריכים לדחות עבודה יקרה, החזר `JobPending` במקום ורשום `@app.job_lookup` handler; שרת Observability סקור `GET /evaluate/{job_id}` עד שאתה מחזיר סטטוס טרמינלי או ה-`EVALUATOR_MAX_POLL_DURATION_SECS` כיפה (ברירת מחדל 1 שעה) חולף. -ה-API reference המלא, דפוס אסינכרוני וסכמת אירועים תועדו ב-README של SDK ה-`agenteye-evaluator`. +העדכון API המלא, דפוס async, וסכמה אירועים מתועדים ב-README של SDK `agenteye-evaluator`. --- -## הרצת המעריך שלך +## הפעלת ה-evaluator שלך -ההערכה היא **השירות שלך** — Failproof AI Observability לא משלח מעריך ברירת מחדל, כך שאתה בונה והרץ אותו במקום שבו אתה מריץ את השירותים שלך. הוא פועל תחת כל שרת ASGI (לדוגמה `uvicorn my_evaluator:app`); הגיש את נתיבי `/health`, `/config` ו-`/evaluate` מ-[חוזה HTTP](#http-contract), ואז הצביע את השרת אליו (ראה [הגדרת השרת](#configuring-the-server)). +ה-evaluator הוא **השירות שלך** — Failproof AI Observability לא משלח evaluator ברירת מחדל, אז אתה בונה ומפעיל אותו כל היכן שאתה מפעיל את השירותים שלך. הוא פועל תחת כל שרת ASGI (לדוגמה `uvicorn my_evaluator:app`); הגש את מסלולי `/health`, `/config`, ו-`/evaluate` מ-[חוזה HTTP](#http-contract), ואז סמן את השרת אליו (ראה [קביעת השרת](#configuring-the-server)). -ברגע שההערכה ניתנת להשגה, `GET /health` מחזיר `{"status":"ok"}`. לאחר הרצה של סוכן מקצה לקצה, `GET /evaluations` בשרת מחזיר שורה עם `status: "done"` וציונים שההערכה שלך ייצרה. +לאחר שה-evaluator נגיש, `GET /health` מחזיר `{"status":"ok"}`. לאחר שagent רץ מקצה לקצה, `GET /evaluations` בשרת מחזיר שורה עם `status: "done"` והניקוד שה-evaluator שלך הפיק. --- -## הגדרת השרת +## קביעת השרת קבע בתהליך השרת: | Env var | משמעות | |---|---| -| `EVALUATOR_ENDPOINT` | URL בסיסי של ההערכה שלך (`http://evaluator:9000`). לא מוגדר = צינור מנוטרל. | -| `EVALUATOR_TOKEN` | Bearer token. חייב להיות שווה לערך שהשירות ההערכה מוגדר איתו. | -| `EVALUATOR_WORKERS` | משימות עובדים לכל מופע שרת (ברירת מחדל 2). | -| `EVALUATOR_CLAIM_BATCH` | שורות שטענו לכל תיקיית עובדים (ברירת מחדל 4). אצוות מעובדות **במקביל**; תחולה אפקטיבית בנקודת ההערכה שלך היא `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | כמה זמן עובד ישן בין ניסיונות dispatч כאשר לא מוערך (ברירת מחדל 2 שניות). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | נופל סופי ל-`GET /evaluate/{id}` קצב כאשר לא `next_poll_secs` ולא `default_poll_interval_secs` של ההערכה מוגדר (ברירת מחדל 10 שניות). | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | קצבאו לכל בקשה (ברירת מחדל 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | לאחר נסיונות חולפים רבים זה, התוצאה מוקלטת כ-`error` סופי (ברירת מחדל 5). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | קצבאו של `GET /config` (ברירת מחדל 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | זמן קיר מקסימלי שסשן עשוי להישאר בתור הסקר לפני שהוא מסתיים כ-`timeout` (ברירת מחדל 3600 שניות). משמר כנגד מעריך שמחזיר `pending` לנצח. | +| `EVALUATOR_ENDPOINT` | Base URL של ה-evaluator שלך (`http://evaluator:9000`). לא מוגדר = ה-pipeline מנוטרל. | +| `EVALUATOR_TOKEN` | Bearer token. חייב להיות שווה לערך ש-evaluator service מוגדר אתו. | +| `EVALUATOR_WORKERS` | משימות עובדים לכל instance שרת (ברירת מחדל 2). | +| `EVALUATOR_CLAIM_BATCH` | שורות שטענו לכל tick עובדים (ברירת מחדל 4). אצות מעובדות **בו-זמנית**; concurrency יעיל בנקודת הסיום של ה-evaluator שלך הוא `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | כמה זמן עובד ישן בין ניסיונות dispatch כשלא הערכה הגיעה (ברירת מחדל 2 שניות). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Final fallback עבור קצב `GET /evaluate/{id}` כשגם `next_poll_secs` לכל תגובה וגם `default_poll_interval_secs` של ה-evaluator לא מוגדר (ברירת מחדל 10 שניות). | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Per-request timeout (ברירת מחדל 30000). | +| `EVALUATOR_MAX_ATTEMPTS` | לאחר כשלים זמניים רבים זה התוצאה רשומה כ-`error` טרמינלי (ברירת מחדל 5). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` קצב (ברירת מחדל 300). | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | זמן wallclock מרבי session עשוי להישאר בתור polling לפני שהוא מסתיים כ-`timeout` (ברירת מחדל 3600 שניות). שומר כנגד evaluator שממשיך להחזיר `pending` לנצח. | -כדי להפעיל דירוג אוטומטי, קבע הן את `EVALUATOR_ENDPOINT` והן את `EVALUATOR_TOKEN` בשרת, ואז הפעל מחדש כדי להרים את השינוי. עם `EVALUATOR_ENDPOINT` לא מוגדר הצינור נשאר no-op. +כדי להפעיל ניקוד אוטומטי, קבע גם `EVALUATOR_ENDPOINT` וגם `EVALUATOR_TOKEN` בשרת, ואחר כך הפעל מחדש אותו כדי לעלות על השינוי. עם `EVALUATOR_ENDPOINT` לא מוגדר ה-pipeline נשאר no-op. -כפתורי הכיול לעיל הם אופציונליים; קבע משתנים סביבה מתאימים בשרת רק אם אתה צריך לדרוג את ברירות המחדל. +ידיות הכיול לעיל הן אופציונליות; קבע את משתני הסביבה המתאימים בשרת רק אם אתה צריך להחריג את ברירות המחדל. --- -## API reference +## הפניה API | שיטה | נתיב | הרשאה נדרשת | מטרה | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | תוצאות סופיות של שאילתה. תומך בـ `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` מכתת ל-50 וקצוב ב-200 (שימו לב זה שונה מ-`/events`, שקצוב ב-1000). `environment` מקבל רשימה המופרדת בפסיקים (למשל `environment=prod,staging`); ערכים יחידים עדיין פועלים. עם `latest_per_session=true` התגובה מכילה לכל היותר שורה אחת לכל `session_id` (ההאחרונה לפי `completed_at`) בשימוש בעמוד רשימת הסשנים כדי לצמצם ציר זמן הערכה של סשן לכותרת הנוכחית שלו. ברירת מחדל לשקר (מחזיר את ההיסטוריה המלאה). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | בריאות eval מצטברת עבור פרוסה מסוננת: ספירה כוללת, פירוט done/error/timeout, סטטיסטיקה לכל מפתח ציון (ספירה/ממוצע/דקות/מקס/p50 על פני מפתחות `scores` שרירותיים) וציר זמן מגודל זמן. מקבל **אותם פרמטרים סינון כמו `/evaluations`** בתוספת `featured_keys` (CSV של מפתחות ציון לטרנד) ו-`latest_per_session`. הנוסחאות לתכונת Dashboards; מדדים מדויקים על כל הסט התואם, לא דגום. | -| `GET` | `/evaluations/environments` | `evaluations:read` | ערכי סביבה מובחנים מטבלת ה-`evaluations`. משמש למילוי תפריטי סינון המתוגבלים לנתונים הניתנים לקריאה הערכה. | -| `GET` | `/evaluation-jobs` | `evaluations:read` | ראות להערכות בטיסה. סנן לפי `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | זרימת אירועים גולמיים של סשן. תומך ב-`session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` וכן `order`. `order` הוא `desc` (newest-first, ברירת מחדל) או `asc` (oldest-first); ערך לא מוכר חוזר אל `desc`. סמן עמוד דרך ה-`next_cursor` של התגובה (מזהה אירוע): העבור אותו חזרה כמו `cursor` כדי לקבל את העמוד הבא; עם `asc` העמוד הבא הוא האירועים לאחר מזהה זה, עם `desc` האירועים לפניו. `limit` מכתת ל-50 וקצוב ב-1000. | -| `GET` | `/sessions/:session_id/export` | `events:read` | מחזיר את גוף JSON המדוייק שההערכה תקבל לסשן זה, המוגש כקובץ הורדה בשם `session-.json`. שימושי לניגון סשנים ייצור דרך `agenteye-evaluator` לבדיקה offline. הבתים זהים בדיוק לבתים שצינור ההערכה שולח. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | תור הערכה טרייה לסשן; רץ בין אם הערכה קודמת קיימת או לא. התוצאה החדשה היא **מוספת** לציר זמן ההערכה של הסשן ולא דורסת את הקודמת, כך ציונים קודמים נשארים גלויים כהיסטוריה. מחזיר `202` על תור, `404` לסשן לא ידוע, `409` אם הערכה כבר בטיסה. השתמש בזה לאחר פריסת מעריך חדש, או לסשנים שמעולם לא פלטו `agent_end`. | +| `GET` | `/evaluations` | `evaluations:read` | תוצאות טרמינליות שאילתה. תומך ב-`session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` ברירות לערך 50 ומוגבל לערך 200 (שימו לב שזה שונה מ-`/events`, שמוגבל ל-1000). `environment` קיבל רשימה מופרדת בפסיקים (למשל `environment=prod,staging`); ערכים בודדים עדיין עובדים. עם `latest_per_session=true` התגובה מכילה לכל היותר שורה אחת לכל `session_id` (האחרון ביותר על ידי `completed_at`) בשימוש בעמוד רשימת ה-sessions כדי לכווץ ציר זמן הערכה של session להדפס הנוכחי. ברירות לערך false (מחזיר את ההיסטוריה המלאה). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | בריאות eval מגולגלת עבור ריסה מסננת: ספירה סה"כ, פירוק done/error/timeout, סטטיסטיקות לכל-score-key (count/avg/min/max/p50 על top-keyed `scores` שרירותיים), וציר זמן משוכה על ידי זמן. קיבל **אותם params filter כמו `/evaluations`** בתוספת `featured_keys` (CSV של score keys לטרנד) ו-`latest_per_session`. כוחות עמוד Dashboards; מטריקות מדויקות על כל הסט התאימות, לא דגומות. | +| `GET` | `/evaluations/environments` | `evaluations:read` | ערכי סביבה ברורים מטבלת `evaluations`. בשימוש לאוכלוסיית dropdowns filter בקנה מידה לנתונים ניתנים לקריאה-הערכה. | +| `GET` | `/evaluation-jobs` | `evaluations:read` | ראות לתוך הערכות in-flight. סינון לפי `status` (`pending`/`polling`). | +| `GET` | `/events` | `events:read` | זרום אירועים גולמיים של session. תומך ב-`session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit`, וה-`order`. `order` הוא `desc` (newest-first, ברירת המחדל) או `asc` (oldest-first); ערך שלא מוכר חוזר ל-`desc`. Cursor-paginate דרך `next_cursor` של התגובה (id אירוע): העברה חזרה כ-`cursor` כדי לקבל את העמוד הבא; עם `asc` העמוד הבא הוא האירועים אחרי id זה, עם `desc` האירועים לפניו. `limit` ברירות לערך 50 ומוגבל ל-1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | מחזיר את גוף ה-JSON המדויק שה-evaluator היה מקבל לתא זה, שימשוך כקובץ מצורף להורדה בשם `session-.json`. שימושי לעיבוד מחדש של sessions ייצור דרך `agenteye-evaluator` לבדיקה offline. הבתים הם byte-identical לאלו ש-evaluator pipeline שולח. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | כל הערכה טרייה עבור session; פעולות בין אם קיימת הערכה קודמת או לא. התוצאה החדשה היא **מתווספת** לציר זמן הערכה של ה-session במקום להחליף את הקודם, אז ניקודים קודמים נשארים גלויים כהיסטוריה. החזרות `202` בתערער, `404` עבור session לא ידוע, `409` אם הערכה כבר in-flight. השתמש בזה אחרי deployment evaluator חדש, או עבור sessions שלעולם לא פולטו `agent_end`. | -### סינון לפי טווח ציון: `score_filters` +### סינון לפי טווח ניקוד: `score_filters` -`GET /evaluations` מקבל פרמטר אופציונלי `score_filters` שמצמצם תוצאות לפי ערכים מספריים בתוך `scores` object. הפרמטר הוא רשימה המופרדת בפסיקים של ערכי `key:min..max`; כל קשר עשוי להיות מושמט. כניסות מרובות משלבות עם AND לוגי. שורות כאשר המפתח הנקוב חסר או לא מספרי מודדות. בקשה עשויה להכיל לכל היותר 20 ערכי סינון; חריגה מזה מחזיר HTTP 400. +`GET /evaluations` מקבל `score_filters` parameter אופציונלי שמצמצם תוצאות לפי ערכים מספריים בתוך אובייקט `scores`. ה-parameter הוא רשימה מופרדת בפסיקים של ערכים `key:min..max`; כל קשור עשוי להיות מושמט. ערכים מרובים משלבים עם AND לוגי. שורות כאשר המפתח הנקוב חסר או non-numeric מוחרגות. בקשה עלולה לשאת לכל היותר 20 ערכי filter; החריגה שלהם מחזירה HTTP 400. דוגמאות: ```text @@ -213,87 +213,87 @@ GET /evaluations?score_filters=tool_efficiency:..0.3 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` -לכל אובייקט תגובה `/evaluations` יש שדות אלה: +לכל אובייקט תגובה `/evaluations` יש שדות אלו: | שדה | סוג | הערות | |---|---|---| -| `evaluation_id` | string (UUID) | המזהה הקנוני להערכה סופית זו. כל הערכה סופית מקבלת UUID חדש; סשן אחד יכול להחזיק מרובות. | -| `id` | string (UUID) | כינוי backward-compatibility הנושא את אותו ערך כמו `evaluation_id`. | -| `session_id` | string | הסשן שהערכה זו רצה כנגדו. סשן יכול להיות הערכות מרובות בציר הזמן. | -| `agent_id` | string | מזהה את הסוכן שייצר את הסשן. | -| `environment` | string | תווית סביבה מעתקת מהסשן. | +| `evaluation_id` | string (UUID) | המזהה הקנוני להערכה טרמינלית זו. כל הערכה טרמינלית מקבלת UUID חדש; session יחיד יכול להחזיק רבים. | +| `id` | string (UUID) | תואם-אחורה alias הנושא את אותו ערך כמו `evaluation_id`. | +| `session_id` | string | ה-session הערכה זו רצה נגדה. session יכול להחזיק הערכות מרובות בציר זמן. | +| `agent_id` | string | מזהה את ה-agent שהפיק את ה-session. | +| `environment` | string | תווית סביבה המועתקת מ-session. | | `status` | enum | אחד מ-`"done"`, `"error"`, `"timeout"`. | -| `scores` | object \| null | ציונים שהוחזרו על ידי ההערכה שלך. | -| `reasoning` | object \| null | מפת הנמקה אופציונלית לכל ציון שהוחזרה על ידי ההערכה שלך. מפתחות בדרך כלל משקפים אלה ב-`scores`. לוח המחוונים משרטט כל ערך מתחת לסרגל הציון שלו. | -| `summary` | string \| null | נרטיב אחד-פסקה כולל אופציונלי שהוחזר על ידי ההערכה שלך. לוח המחוונים משרטט זאת למעלה פירוק הציון לכל ציון כהערכה של ההערכה. | -| `error` | string \| null | למלא ב-`"error"` / `"timeout"` בלבד. | +| `scores` | object \| null | ניקודים המוחזרים על ידי ה-evaluator שלך. | +| `reasoning` | object \| null | מפת הצדקה אופציונלית לכל-ניקוד המוחזרת על ידי ה-evaluator שלך. מפתחות בדרך כלל משקפים אלו ב-`scores`. ה-dashboard מעבד כל ערך תחת סרגל הניקוד שלו. | +| `summary` | string \| null | סיכום פסקה אחת אופציונלי כללי המוחזר על ידי ה-evaluator שלך. ה-dashboard מעבד זה מעל פירוק ה-score לכל אחד כהדפס ההערכה. | +| `error` | string \| null | אוכלוס על `"error"` / `"timeout"` רק. | | `attempt_count` | integer | מספר ניסיונות dispatch (≥ 1). | | `duration_ms` | integer \| null | משך הניסיון הסופי. | -| `completed_at` | string (ISO 8601 UTC) | מתי התוצאה הסופית נוקדה. תוצאות מסודרות לפי `completed_at` (newest first). | -| `created_at` | string (ISO 8601 UTC) | נושא את אותו חותם זמן כמו `completed_at` (semantics write-once). | +| `completed_at` | string (ISO 8601 UTC) | כאשר התוצאה הטרמינלית נרשמה. התוצאות מסודרות ב-`completed_at` (newest first). | +| `created_at` | string (ISO 8601 UTC) | נושא את אותו חותם זמן כמו `completed_at` (semantics כתיבה-פעם). | --- ## הרשאות -| הרשאה | מיוחסות | +| הרשאה | מענקים | |---|---| -| `evaluations:read` | רשימת תוצאות הערכה, צפייה בציונים בלוח המחוונים וטעינת מדדי בריאות לוח המחוונים. | -| `evaluations:trigger` | תור ידנית של הערכה לסשן דרך `POST /sessions/:session_id/re-evaluate` או כפתור re-evaluate של לוח המחוונים. | -| `dashboards:read` | צפייה בלוחות שמורים (גם צריך `evaluations:read` כדי לטעון את המדדים שלהם). | -| `dashboards:write` | יצירה ועריכת לוחות. | -| `dashboards:delete` | מחיקת לוחות. | +| `evaluations:read` | תוצאות הערכה רשימה, צפה בניקודים ב-dashboard, וטען מטריקות בריאות dashboard. | +| `evaluations:trigger` | כל הערכה ידנית עבור session דרך `POST /sessions/:session_id/re-evaluate` או כפתור re-evaluate ב-dashboard. | +| `dashboards:read` | צפה בדashboards שמורים (גם צריך `evaluations:read` כדי לטעון את המטריקות שלהם). | +| `dashboards:write` | יצור וערוך dashboards. | +| `dashboards:delete` | מחק dashboards. | -ה-bootstrap admin (`ADMIN_KEY`, `ADMIN_EMAIL`) מקבל אלה באופן אוטומטי. +bootstrap admin (`ADMIN_KEY`, `ADMIN_EMAIL`) קיבל אוטומטית את אלו. --- -## צפייה בתוצאות +## תצפיות תוצאות -- **`/sessions/`**: אירועים ציר זמן + פס ימני המציג את ציוני הסשן וכל שגיאה מניסיון ה-dispatch. אם המפתח שלך כולל `evaluations:trigger`, כפתור **re-evaluate** מופיע ליד כפתור ה-export, שימושי לסשנים שמעולם לא פלטו `agent_end`, או להרעיש ציונים לאחר פריסת מעריך חדש. לוח המחוונים סוקר את התוצאה החדשה ומעדכן את פס הימני כאשר הוא נוחת. -- **`/sessions`**: גריד סשנים ניתן לסינון; עמודת הציון מציגה את סטטוס ההערכה וציונים של כל סשן בהצצה. -- **`/dashboards`**: צפיות בריאות eval שמורה (ראה [לוחות](#dashboards) להלן). +- **`/sessions/`**: ציר זמן אירועים + פס ימני המציג ניקודי ה-session וכל שגיאה מניסיון ה-dispatch. אם המפתח שלך יש `evaluations:trigger`, כפתור **re-evaluate** מופיע לצד כפתור ה-export, שימושי עבור sessions שלעולם לא פלטו `agent_end`, או לריענון ניקודים אחרי הצבה evaluator חדש. ה-dashboard סקור את התוצאה החדשה ומעדכן את הפס הימני כאשר הוא נחות. +- **`/sessions`**: רשת session שניתן לסנן; עמודת הניקוד מציגה כל status הערכה של session ודירוגים בהצצה. +- **`/dashboards`**: תצפיות בריאות eval שמורות (ראה [Dashboards](#dashboards) להלן). -![גריד הסשנים עם כלולי סטטוס הערכה לכל סשן ובתגים מדורגים בצבע (עזרתיות, עובדתיות, tool_efficiency, בטיחות, קוהרנטיות)](/agenteye/images/sessions-list.png) +![רשת Sessions עם כל-session evaluation status pills וציבע-coded score badges (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) -*גריד הסשנים מציג את סטטוס ההערכה וציונים של כל הרצה בהצצה; תגים אדומים/כהים/ירוקים גורמים לציונים נמוכים לקפוץ החוצה.* +*רשת ה-sessions מציגה כל status הערכה של הפעלה ודירוגים בהצצה; תגים אדום/אמבר/ירוק הם ניקודים נמוכים לקפוץ בחוץ.* --- -## לוחות +## Dashboards -דף **Dashboards** (`/dashboards`) מאפשר לך שמירה של שילוב של סינני הערכה כתצוגה בשם וניתנת לשימוש חוזר וצפייה כיצד האות פרוסה של הערכות עושה בהצצה. לוחות הם **משותפים בכל הארגון שלך**; כולם עם `dashboards:read` רואים את אותה סט. +עמוד **Dashboards** (`/dashboards`) מאפשר לך לשמור שילוב של filters הערכה כתצפיות שם שניתן להשתמש בהן מחדש וצפה כיצד הפרח הזה של הערכות עושה בהצצה. Dashboards הם **משותפים על פני ארגון שלך כולו**; כל אחד עם `dashboards:read` רואה את אותה קבוצה. -כל לוח משמירה: +כל dashboard סיכה: -- **סינונים**: אותם בקרים כמו עמוד הסשנים: סביבה, סטטוס, סוכן, חלון זמן מתגלגל וסינני טווח ציון (`key:min..max`). -- **תצורת תצוגה**: איזה מפתחות ציון לתכונה, סף בריאות ירוק/כהה/אדום, איזה פנלים להציג והאם לצמצם לאחרון הערכה לכל סשן. +- **Filters**: הבקרות זהה כמו עמוד ה-sessions: סביבה, status, agent, חלון זמן מתגלגל, וfilters score-range (`key:min..max`). +- **תצורת תצוגה**: אילו score keys עד להתחייב, הירוק/אמבר/אדום health thresholds, אילו panels להציג, וכן לא להכניס להערכה האחרונה לכל session. -כל כרטיס מציג את מספר הסשנים התואמים, פירוט done/error/timeout, ממוצע של כל ציון בתכונה וטרנדלין ספארק קטן. פתיחת לוח מציגה את הפנלים במלוא הגודל; **"פתח בסשנים"** מושיב אותך לעמוד הסשנים מקדים מסונן לאותה פרוסה בדיוק. מדדים מחושבים בצד שרת על פני כל הסט התואם (דרך `GET /evaluations/aggregate`), כך המספרים מדויקים ולא דגומים. +כל כרטיס מציג את מספר sessions תואמים, פירוק done/error/timeout, את הממוצע של כל featured score, וsparkline trend קטן. פתיחה של dashboard מציגה את המלא-size panels; **open in sessions** מטיל אתך לעמוד ה-sessions pre-filtered לבדיוק אותו מחדש. מטריקות מחושבות בצד-שרת על כל הסט התאימות (דרך `GET /evaluations/aggregate`), אז המספרים דויקים למעמ דגומות. -![לוח בריאות eval עם סרגלי ציון ממוצע לממד evaluator, breakdown tool ok-vs-error, כלים למעלה וטרנד events-per-hour](/agenteye/images/dashboard-quality.png) +![eval-health dashboard עם average-score bars לכל evaluator dimension, כלי ok-vs-error פירוק, למדים כלים, וevents-per-hour trend](/agenteye/images/dashboard-quality.png) -**הרשאות:** צפייה צריכה הן `dashboards:read` והן `evaluations:read`; יצירה ועריכה צריכה `dashboards:write`; מחיקה צריכה `dashboards:delete`. ה-bootstrap admin מקבל את כל אלה באופן אוטומטי. +**הרשאות:** צפייה דורשת גם `dashboards:read` וגם `evaluations:read`; יצירה וערוך דורשים `dashboards:write`; מחיקה דורשת `dashboards:delete`. bootstrap admin קיבל אוטומטית את כל אלו. --- ## פתרון בעיות -**סשנים קיימים אך לא נוצרות הערכות.** אשר כי `EVALUATOR_ENDPOINT` מוגדר בתהליך השרת, שהשרת וההערכה משתפים אותו ערך `EVALUATOR_TOKEN` וכי נקודת הסוף `/health` של ההערכה ניתנת להשגה מהשרת. עם `EVALUATOR_ENDPOINT` לא מוגדר הצינור הוא no-op. +**Sessions קיימים אבל לא הערכות נוצרות.** אישור `EVALUATOR_ENDPOINT` מוגדר בתהליך השרת, ששרת ו-evaluator משתפים את אותו ערך `EVALUATOR_TOKEN`, וש-`/health` endpoint של ה-evaluator נגיש מ-host. עם `EVALUATOR_ENDPOINT` לא מוגדר ה-pipeline הוא no-op. -**הערכות בטיסה צוברות.** שאילתה `GET /evaluation-jobs` כדי לראות את התור בטיסה. בדוק את `attempt_count`, `next_attempt_at` ו-`last_error` על כל שורה. סיבות נפוצות: שירות ההערכה לא ניתן להשגה או מחזיר 5xx (מנסה שוב עם backoff), `EVALUATOR_TOKEN` שגוי (401 סופי) או מעריך אסינכרוני שמחזיר `pending` לנצח (ראה להלן). +**הערכות in-flight ערמון עד.** שאלה `GET /evaluation-jobs` כדי לראות את תור in-flight. בדוק `attempt_count`, `next_attempt_at`, ו-`last_error` בכל שורה. סיבות נפוצות: שירות evaluator לא נגיש או להחזיר 5xx (נסמנו בחזרה עם backoff), לא נכון `EVALUATOR_TOKEN` (401 טרמינלי), או async evaluator שמחזיר `pending` לנצח (ראה להלן). -**סשנים הושלמו אך לא הערכה סופית.** שאילתה `GET /evaluation-jobs?status=polling`; התוצאה עדיין עשויה להיות בטיסה. אם עבודה תקועה ב-`pending`, לשרת יש בעיה להשגת ההערכה; בדוק שהערכה מעלה וכי `EVALUATOR_TOKEN` משחק. +**Sessions הושלמו אבל לא הערכה טרמינלית.** שאלה `GET /evaluation-jobs?status=polling`; התוצאה עלולה להיות עדיין in-flight. אם job תקוע ב-`pending`, השרת יש בעיה להגיע ל-evaluator; בדוק כי ה-evaluator גם עד וש-`EVALUATOR_TOKEN` תואמים. -**`HTTP 401 from evaluator: invalid bearer token`.** ה-`EVALUATOR_TOKEN` בשרת לא משחק עם הערך שהשירות ההערכה מוגדר איתו. הם חייבים להיות זהים. +**`HTTP 401 from evaluator: invalid bearer token`.** ה-`EVALUATOR_TOKEN` בשרת לא תואמים את הערך ש-evaluator service מוגדר אתו. הם חייבים להיות זהים. -**מעריך אסינכרוני מחזיר `pending` לנצח.** השרת סוקר `GET /evaluate/{job_id}` עד שההערכה מחזירה `done` או `error`, או עד ש-`EVALUATOR_MAX_POLL_DURATION_SECS` (ברירת מחדל 1 שעה) חולפת. לאחר הכובע ההערכה מוקלטת כ-`timeout` והוסרת מתור הבטיסה. הרם את `EVALUATOR_MAX_POLL_DURATION_SECS` אם ההערכה שלך בחוקיות צריכה יותר מברירת המחדל. +**Async evaluator מחזיר `pending` לנצח.** השרת סקור `GET /evaluate/{job_id}` עד ש-evaluator מחזיר `done` או `error`, או עד `EVALUATOR_MAX_POLL_DURATION_SECS` (ברירת מחדל 1 שעה) עוברת. אחרי הכיפה ההערכה נרשמה כ-`timeout` והוסרה מהתור in-flight. גבה `EVALUATOR_MAX_POLL_DURATION_SECS` אם ה-evaluator שלך בהגון צורך יותר מברירת המחדל. --- -## שלבים הבאים +## השלבים הבאים -- [מיומנות סוכן Evaluator](/he/agenteye/evaluator-skill): יש לסוכן קידוד עיצוב הממדים שלך כנגד סשנים אמיתיים וביצוע שירות זה בשבילך. -- [Python SDK](/he/agenteye/python-sdk): פלטו את אירועי `agent_end` שמפעילים דירוג. -- [API keys](/he/agenteye/api-keys): הרשאות `evaluations:read` ו-`evaluations:trigger`. -- [Audits](/he/agenteye/audits): תכונת בריאות אוטומטית נוספת של Observability, לבדיקה מבוססת מדיניות. \ No newline at end of file +- [Evaluator agent skill](/he/agenteye/evaluator-skill): יש coding agent לעצב את הממדים שלך נגד sessions אמיתיים ובנה את השירות הזה בעבורך. +- [Python SDK](/he/agenteye/python-sdk): פלוט `agent_end` אירועים שטריגר דירוג. +- [API keys](/he/agenteye/api-keys): ההרשאות `evaluations:read` ו-`evaluations:trigger`. +- [Audits](/he/agenteye/audits): Observability של Failproof AI בעיה אחרת בחינה, לבדיקה מבוססת-policy. \ No newline at end of file diff --git a/docs/he/agenteye/evaluations.mdx b/docs/he/agenteye/evaluations.mdx index af3ed0b4..b44844c7 100644 --- a/docs/he/agenteye/evaluations.mdx +++ b/docs/he/agenteye/evaluations.mdx @@ -1,51 +1,51 @@ --- title: "הערכות" -description: "בעיות איכות מוצאות אותך כעת, במקום שתשמע עליהן בתלונת משתמש." +description: "בעיות איכות מוצאות אתכם עכשיו, במקום שתשמעו עליהן בתלונת משתמש." --- -בעיות איכות מוצאות אותך כעת, במקום שתשמע עליהן בתלונת משתמש. חבר את שירות ההדירוג שלך פעם אחת ו-Failproof AI Observability מדרג כל הרצה שהושלמה באופן אוטומטי, כך שירידה בעזרתיות או עלייה בהלוצינציות מופיעה מעצמה, לפני שלקוח חש בכך. +בעיות איכות מוצאות אתכם עכשיו, במקום שתשמעו עליהן בתלונת משתמש. חברו את שירות הדירוג שלכם פעם אחת וFailproof AI Observability מדרגת כל הרצה שהושלמה באופן אוטומטי, כך שירידה בשימושיות או עלייה בהזיות תופיעו מעצמם, לפני שלקוח ירגיש זאת. -![רשת ההפעלות עם עמודת ניקוד: כל הרצה נושאת תג סטטוס הערכה ותגי עזרתיות, עובדתיות וַיעילות כלים בקודים צבעים](/agenteye/images/sessions-list.png) +![רשת Sessions עם עמודת ניקוד: כל הרצה נושאת תג סטטוס הערכה ותגיות שימושיות, דיוק וכלים בקוד צבע](/agenteye/images/sessions-list.png) -*כל הרצה ברשת ההפעלות נושאת את הניקודים שלה; תגים אדומים, כתומים וירוקים הופכים את ההרצות החלשות לבולטות מבלי שתפתח אפילו תמלול אחד.* +*כל הרצה ברשת ה-sessions נושאת את הניקודים שלה; תגיות אדומות, כתומות וירוקות הופכות את ההרצות החלשות בולטות ללא צורך בפתיחת תמלול יחיד.* -## הפסק דגימה ידנית של הרצות +## הפסיקו לדגום הרצות ידנית -נהגת לבדוק כמה הרצות וקיווית שהשאר בסדר. כעת כל סשן שהושלם מקבל ניקוד ברגע שהוא מסתיים, בממדים שחשובים לך: עזרתיות, יעילות כלים, עובדתיות, בטיחות, כל מה שקובע את רמת האיכות שלך. אתה מגדיר את מפתחות הניקוד; Failproof AI Observability שומר, עוקב אחר מגמות ומציג כל מה שמעריך שלך חוזר חזור. אף הרצה לא מחליקה ללא ניקוד, והתה מפסיק ללמוד על נסיגה מכרטיס תמיכה. +בעבר בדקתם כמה הרצות בעין ותיקוו שהשאר היו בסדר. עכשיו כל הפעלה שהסתיימה מדורגת ברגע שהיא מסתיימת, על הממדים שחשובים לכם: שימושיות, יעילות כלים, דיוק, בטיחות, כל מה שקובע את רמת האיכות שלכם. אתם מגדירים את מפתחות הניקוד; Failproof AI Observability אחסן, מעקב וממוקד כל מה שהמעריך שלכם שולח בחזרה. אף הרצה לא חולפת ללא ניקוד, וביטלתם ללמוד על נסיגה מכרטיס תמיכה. -הניקודים נוסעים עם רשת ההפעלות ב-**`//sessions`** (סרגל צד → *observe* → *sessions*), אשכול תגים אחד לכל שורה. רוצה רק את ההרצות שירדו? סנן את הרשת לפי טווח ניקוד, נניח עזרתיות מתחת ל-0.5, וציין בדיוק את ההרצות שכדאי לקרוא. צפייה בניקודים דורשת את ההרשאה `evaluations:read`. +הניקודים מופיעים ברשת ה-sessions ב-**`//sessions`** (צד ימין → *observe* → *sessions*), קבוצת תגיות אחת לכל שורה. רוצים רק הרצות שהתחסרו? סננו את הרשת לפי טווח ניקוד, למשל שימושיות מתחת ל-0.5, והוציאו בדיוק את ההרצות שכדאי לקרוא. הצגת ניקודים דורשת הרשאת `evaluations:read`. -## ראה למה הרצה קיבלה ניקוד נמוך +## ראו מדוע הרצה קיבלה ניקוד נמוך -מספר אומר לך שהרצה הייתה חלשה; דף ההפעלה אומר לך למה. פתח כל הרצה והרגל הימני מתחיל עם סיכום הכותרת, ואז מציג עמודה לכל ממד עם הנימוק של המעריך שלך מתחתה, כך שתעבור מ"זה קיבל 0.4 בעובדתיות" לטעות המדויקת בשניות. +מספר אומר לכם שהרצה הייתה חלשה; דף ה-session אומר לכם למה. פתחו כל הרצה והפס הימני מתחיל בסיכום הכותרת, ואז מציג סרגל לכל ממד עם נימוקו שלו של המעריך מתחת לכל אחד, כך שתעברו מ-"זה קיבל 0.4 בדיוק" לטעות המדויקת בשניות. -![הרגל הימני של הפעלה: סיכום ההערכה בחלקו העליון, ואז עמודות ניקוד לכל ממד כל אחת עם שורת נימוק, לצד ציר הזמן המלא של האירוע](/agenteye/images/session-detail.png) +![פס ימין של session: סיכום ההערכה בחלק העליון, ואז סרגלי ניקוד לכל ממד עם כל אחד עם שורה של נימוקים, ליד ציר הזמן המלא של האירועים](/agenteye/images/session-detail.png) -*תצוגת פרטי ההפעלה: סיכום, עמודות ניקוד לכל ממד, והנימוק מאחורי כל ניקוד, ממש לצד ציר הזמן של האירוע של ההרצה.* +*תצוגת פרטי session: סיכום, סרגלי ניקוד לכל ממד, והנימוק מאחורי כל ניקוד, ממש ליד ציר הזמן של אירועי ההרצה.* -שלחת מעריך חדשותי, או מסתכל על הרצה שהתרסקה לפני שיכול היה להתדרג? כפתור **re-evaluate** (מעוגן ב-`evaluations:trigger`) משדרג את ההפעלה במקום ומוסיף את התוצאה הטרייה לציר הזמן שלה, כך שניקודים קודמים נשארים גלויים כהיסטוריה. תמצא אותו ב-**`//sessions/`**. +שלחתם מעריך חדץ יותר, או בודקים הרצה שהתרסקה לפני שיכלה להיות מדורגת? כפתור **re-evaluate** (מגובל על ידי `evaluations:trigger`) מדרגת את ה-session במקום ומוסיף את התוצאה החדשה לציר הזמן שלו, כך שניקודים קודמים נשארים גלויים כהיסטוריה. תמצאו אותו ב-**`//sessions/`**. -## צפה במגמת איכות על כל הצי +## עקבו אחר מגמת איכות בחFleet -הרצה אחת עם ניקוד נמוך היא רעש; קוהורטה שלמה שמחליקה היא סימן. לוחות בקרה שמורים הופכים את הניקודים שלך למגמה שאתה יכול לצפות בה במבט אחד: עזרתיות ממוצעת השבוע מול השבוע שעבר, לכל סוכן, לכל סביבה. +הרצה אחת שקיבלה ניקוד נמוך היא רעש; קוהורטה שלמה שקורסת היא אות. לוחות בקרה שמורים הופכים את הניקודים שלכם למגמה שתוכלו לראות במבט: ממוצע שימושיות שבועות זה לעומת שבועות שעברו, לכל סוכן, לכל סביבה. -![לוח בקרה איכות: עמודות ניקוד ממוצע לכל ממד מעריך לצד מגמה לאורך זמן](/agenteye/images/dashboard-quality.png) +![לוח בקרה איכות: סרגלי ניקוד ממוצע לכל ממד מעריך ליד מגמה לאורך זמן](/agenteye/images/dashboard-quality.png) -*לוח בקרה איכות שמור מעקב אחר מפתחות הניקוד שאתה מציג, כך שסחיפה איטית היא ברורה הרבה לפני שהוא הופך לתקרית.* +*לוח בקרה איכות שמור תופס את מפתחות הניקוד שתוכלו לכלול, כך שסחף איטי יהיה ברור הרבה לפני שהוא הופך לתקרית.* -לוחות בקרה ממוקמים ב-**`//dashboards`** (סרגל צד → *analyze* → *dashboards*), משותפים לכל הארגון שלך, וכל כרטיס מצבור את ההפעלות התואמות: כמה, הממוצע של כל ניקוד מוצג, וקו מגמה דקיק. "Open in sessions" מוריד אותך ישירות להרצות שסוננו מראש מאחורי כל מספר. צפייה דורשת `dashboards:read` בתוספת `evaluations:read`. +לוחות בקרה נמצאים ב-**`//dashboards`** (צד ימין → *analyze* → *dashboards*), משותפים בכל הארגון שלכם, וכל כרטיס מגביה את ה-sessions המתאימים: כמה, הממוצע של כל ניקוד שתכללו, וקו מגמה זעיר. "Open in sessions" מוריד אתכם ישר לתוך ההרצות שסוננו מראש מאחורי כל מספר. הצגה דורשת `dashboards:read` בתוספת `evaluations:read`. -## חבר מעריך פעם אחת +## חברו מעריך פעם אחת -ניקוד הוא בחירה וnמשמר כיבוי לחלוטין עד שאתה מצביע את Failproof AI Observability על מתדרג. אתה מקים שירות HTTP קטן אחד (Observability משלח התייחסות עובדת שתוכל להעתיק), קובע שני ערכים בשרת שלך, וכל הרצה מעתה מתדרגת בשבילך. ההדרכה המלאה, חוזה הניקוד, וה-SDK חיים בהנחיה העמוקה. +ניקוד הוא רשות ולא משהו פעיל עד שתצביעו את Failproof AI Observability למעריך. תציבו שירות HTTP קטן אחד (Observability משלח הפניה עובדת שתוכלו להעתיק), הגדרו שני ערכים בשרתכם, וכל הרצה מזה ואילך מדורגת בשבילכם. ההסבר המלא, חוזה הניקוד, וה-SDK נמצאים במדריך העמוק. -לא בטוח איזה ממדים כדאי לדרג בהתחלה? [כישורון סוכן המעריך](/he/agenteye/evaluator-skill) מאפשר לסוכן קידוד שלך לעבוד זאת כנגד ההפעלות שלך, ואז לבנות ולפרוס את השירות. +לא בטוחים אילו ממדים כדאי לנקד בהתחלה? [מיומנות סוכן המעריך](/he/agenteye/evaluator-skill) מבררת את זה עבורכם מול ה-sessions שלכם, ואז בונה ומפרסמת את השירות. ## קשור -- [חבילת הערכה](/he/agenteye/evaluation-suite): חבר את המעריך שלך, חוזה הניקוד, וה-SDK. -- [כישורון סוכן מעריך](/he/agenteye/evaluator-skill): תן לסוכן קידוד לבחור את ממדי הניקוד שלך ובנה את המעריך. -- [הפעלות](/he/agenteye/sessions): רשת ההרצה-אחר-הרצה שבה ניקודים מופיעים. -- [לוחות בקרה](/he/agenteye/dashboards): שמור וחלוק מגמות איכות על פני הארגון שלך. -- [ביקורות](/he/agenteye/audits): תכונת האיכות האוטומטית האחרת של Observability, לחקירות חוצות-הפעלה. \ No newline at end of file +- [Evaluation suite](/he/agenteye/evaluation-suite): חברו את המעריך שלכם, חוזה הניקוד, וה-SDK. +- [Evaluator agent skill](/he/agenteye/evaluator-skill): אפשרו לסוכן קוד לבחור את ממדי הניקוד שלכם ולבנות את המעריך. +- [Sessions](/he/agenteye/sessions): רשת ההרצה בכל מקום שבו מופיעים הניקודים. +- [Dashboards](/he/agenteye/dashboards): שמרו וחלקו מגמות איכות בכל הארגון שלכם. +- [Audits](/he/agenteye/audits): התכונה האוטומטית השנייה של איכות של Observability, לחקירות בחתך-session. \ No newline at end of file diff --git a/docs/he/agenteye/evaluator-skill.mdx b/docs/he/agenteye/evaluator-skill.mdx index f5902d58..a92631ea 100644 --- a/docs/he/agenteye/evaluator-skill.mdx +++ b/docs/he/agenteye/evaluator-skill.mdx @@ -1,23 +1,21 @@ --- +title: "מיומנות סוכן Failproof AI Observability Evaluator" +description: "מעבר מ\"אני חושב שהסוכן שלנו לפעמים לא טוב\" לשירות scoring שפרוס, כאשר סוכן הקוד שלך עושה גם את ההחלטה וגם את הבנייה." --- -title: "כישרון סוכן הערכה של Failproof AI Observability" -description: "עבור מ\"אני חושב שהסוכן שלנו לפעמים רע\" לשירות ניקוד פרוס, כשהסוכן הקוד שלך עושה גם את ההחלטה וגם את הבנייה." ---- - -עבור מ*\"אני חושב שהסוכן שלנו לפעמים רע\"* לשירות ניקוד פרוס, כשהסוכן הקוד שלך עושה גם את ההחלטה וגם את הבנייה. **כישרון Failproof AI Observability evaluator** (`agenteye-evaluator`) הוא *Agent Skill*: תיקייה קטנה של הוראות שסוכן קוד כמו Claude Code או Codex טוען לפי דרישה. זה מלמד את הסוכן לעבוד ולברר אילו מימדי איכות כדאי לעקוב עבור *הסוכן שלך*, ואז לכתוב, לבדוק ולפרוס את [שירות ה-evaluator](/he/agenteye/evaluation-suite) שמדרג אותם. +מעבר מ*"אני חושב שהסוכן שלנו לפעמים לא טוב"* לשירות scoring שפרוס, כאשר סוכן הקוד שלך עושה גם את ההחלטה וגם את הבנייה. **מיומנות Failproof AI Observability evaluator** (`agenteye-evaluator`) היא *Agent Skill*: תיקייה קטנה של הוראות שסוכן קוד כמו Claude Code או Codex טוען לפי דרישה. היא מלמדת את הסוכן להבין אילו ממדי איכות כדאי לעקוב אחריהם עבור *הסוכן שלך*, ואז לכתוב, לבדוק ולפרוס את [שירות ה-evaluator](/he/agenteye/evaluation-suite) שנותן ניקוד להם. -זה **לא** מדרג מתארח, רישום שאתה מעלה אליו, או מערכת תוספים. ה-evaluator שלך נשאר שירות HTTP שלך בתשתית שלך, בדיוק כما מתואר בהדרכה [Evaluation suite](/he/agenteye/evaluation-suite). הכישרון רק מלמד את הסוכן שלך לבנות זאת טוב, כך שכל מה שהוא עושה, אתה יכול לעשות בעצמך על ידי כתיבת אותו קוד. +זה **לא** scorer מתארח, רישום שאתה מעלה אליו, או מערכת פלאגינים. ה-evaluator שלך נשאר שירות HTTP משלך בתשתית שלך, בדיוק כما מתואר ב[מדריך ה-Evaluation suite](/he/agenteye/evaluation-suite). המיומנות רק מלמדת את הסוכן שלך לבנות אותו טוב, אז כל מה שהוא עושה, אתה יכול לעשות בעצמך בכתיבת אותו קוד. --- -## החלק הקשה הוא להחליט מה לדרג +## החלק הקשה הוא להחליט מה לנקד -משטח ה-SDK קטן — דקורטור ושני מודלים — וסוכן יכול לכתוב את זה מ[החוזה](/he/agenteye/evaluation-suite#http-contract) לבד. זה לא המקום שבו evaluators נכשלים. הם נכשלים כי הם דורגים את הדבר הלא נכון, וה-evaluator שדורג את הדבר הלא נכון הוא גרוע מכלום: הוא מייצר לוח מחוונים שכולם למדו להתעלם ממנו. +משטח ה-SDK קטן — דקורטור ושני מודלים — וסוכן יכול לכתוב את זה מ[החוזה](/he/agenteye/evaluation-suite#http-contract) לבדו. זה לא המקום בו evaluators נכשלים. הם נכשלים כי הם נוקדים את הדבר הלא נכון, ו-evaluator שנוקד את הדבר הלא נכון גרוע יותר מלא כלום: הוא מייצר לוח מחוונים שכולם לומדים להתעלם ממנו. -אז רוב הכישרון הוא החלק לפני שקוד כלשהו קיים. יש לסוכן לראיין אותך (*\"תאר הפעלה שהלכה טוב; עכשיו אחת שהלכה בצורה רעה\"*), ואז לשוך את הסשנים האמיתיים שלך דרך [`agenteye` CLI](/he/agenteye/cli) וקרא אותם מקצה לקצה. שתי החצאים האלה בדרך כלל לא מסכימים, והפער הוא הנקודה: מה אתה מתכוון למדוד בעבור מה שהתמלילים שלך יכולים להתמוך בו. מימד שורד רק אם הוא **ניתן לחישוב** מהאירועים ו**מבדיל** — אם הוא מדרג 0.9 גם בהפעלה הטובה שלך וגם בהרעה, הוא לא מלמד כלום ומתחלק. +אז רוב המיומנות היא החלק לפני שקוד כלשהו קיים. יש לה את הסוכן מראיין אותך (*"תאר הרצה שהלכה טוב; עכשיו אחת שהלכה בעיה"*), ואז משוך את הסשנים האמיתיים שלך דרך [CLI של `agenteye`](/he/agenteye/cli) וקרא אותם מתחילה עד סוף. שני החלקים האלה בדרך כלל לא מסכימים, והפער הוא הנקודה: מה אתה מתכוון למדוד מול מה שהתמלילים שלך יכולים בעצם לתמוך. ממד שורד רק אם הוא **computable** מהאירועים ו**discriminating** — אם הוא נוקד 0.9 הן בהרצה הטובה שלך והן בזו הרעה, הוא לא מלמד כלום וגט חתוך. -מה שחוזר הוא הצעה של 2-4 מימדים כשהנימוק מצורף, בשבילך לאשר לפני שכתוב שורה אחת. +מה שחוזר הוא הצעה של 2-4 ממדים עם הנימוק המצורף, בשבילך לאשר לפני שכתיבת שורה אחת. ```mermaid flowchart TD @@ -31,88 +29,88 @@ flowchart TD --- -## איך זה קשור לחלקי ההערכה האחרים +## איך זה קשור לחתיכות ההערכה האחרות -ארבע מסמכים מכסים ניקוד, והם מוסרים זה לזה בסדר: +ארבע דוקים כוללים scoring, והם עוברים אחד לשני בסדר: -| עמוד | מה זה | הגע אליו כאשר | +| עמוד | מה זה | הגע אליו כשל | |---|---|---| -| **[Evaluations](/he/agenteye/evaluations)** | התכונה: ניקודים בגריד הסשנים, לוחות מחוונים, הערכה מחדש | אתה רוצה לדעת מה ניקוד אוטומטי מקבל לך | -| **[Evaluation suite](/he/agenteye/evaluation-suite)** | החוזה HTTP, ה-SDK, משתני סביבת השרת | אתה מיישם או ניפוי באגים ב-evaluator בעצמך | -| **Evaluator skill** (מסמך זה) | דלת קדמית בשפה טבעית לעיצוב *וגם* בנייה של המדרג | אתה רוצה להעבור מ"אני רוצה evals" לשירות שרץ | -| **[CLI skill](/he/agenteye/cli-skill)** | דלת קדמית בשפה טבעית על ה-`agenteye` CLI | אתה רוצה *לקרוא* את הניקודים שכבר יש לך | -| **[Python SDK skill](/he/agenteye/python-sdk-skill)** | דלת קדמית בשפה טבעית על כלי הסוכן שלך | הסוכן שלך עדיין לא משדר סשנים — אין שום דבר לדרג | +| **[Evaluations](/he/agenteye/evaluations)** | התכונה: ניקוד על רשת הסשנים, לוחות מחוונים, הערכה מחדש | אתה רוצה לדעת מה scoring אוטומטי משיג | +| **[Evaluation suite](/he/agenteye/evaluation-suite)** | החוזה HTTP, ה-SDK, משתני סביבת השרת | אתה מיישם או debug את ה-evaluator בעצמך | +| **Evaluator skill** (מסמך זה) | דלת חזית בשפה טבעית לעיצוב *ובנייה* של ה-scorer | אתה רוצה ללכת מ"אני רוצה evals" לשירות פועל | +| **[CLI skill](/he/agenteye/cli-skill)** | דלת חזית בשפה טבעית ב-`agenteye` CLI | אתה רוצה *לקרוא* את הניקוד שיש לך כבר | +| **[Python SDK skill](/he/agenteye/python-sdk-skill)** | דלת חזית בשפה טבעית בהנדסת סוכן שלך | הסוכן שלך עדיין לא פולט סשנים — אין כלום לנקד | -### לעומת CLI skill: בנייה לעומת קריאה +### מול ה-CLI skill: בנייה מול קריאה -שני הכישרונות מכוונים במכוון שאינם חופפים, והתקנת שניהם היא ההגדרה הרגילה — הסוכן בוחר ביניהם על סמך מה שאתה שואל: +שתי המיומנויות הן בכוונה לא חופפות, והתקנת שתיהן היא ההתקנה הנורמלית — הסוכן בוחר בביניהן בהתאם למה שאתה שואל: -- **`agenteye-evaluator`** (מסמך זה) בונה את הדבר שמייצר ניקודים. עבודתו מסתיימת כאשר ניקודים נוחתים בפעם הראשונה. -- **[`agenteye-cli`](/he/agenteye/cli-skill)** קורא ניקודים שכבר קיימים (`agenteye evals`). *"האם איכות ירדה השבוע?"* היא השאלה שלה, לא של הכישרון הזה. +- **`agenteye-evaluator`** (מסמך זה) בונה את הדבר שמייצר scores. העבודה שלו מסתיימת כשניקוד נחת בפעם הראשונה. +- **[`agenteye-cli`](/he/agenteye/cli-skill)** קורא scores שכבר קיימים (`agenteye evals`). *"האם איכות ירדה השבוע?"* היא השאלה שלו, לא של מיומנות זו. --- -## דרישות מוקדמות +## דרישות קדם -1. **`agenteye` CLI מותקן ומחובר** (`pipx install agenteye`, ואז `agenteye login`). הכישרון מסתמך עליו פעמיים: לשוך את הסשנים האמיתיים שהוא מעצב בהם, ולאשר שהניקודים שלך נוחתו בסוף. הכניסה שלך צריכה `events:read`, בתוספת `evaluations:read` לאישור סופי זה. כמו CLI skill, היא **לא יכולה** להשלים את כניסת קוד חד-פעמית שנשלחה בדוא\"ל עבורך. -2. **מקום ל-evaluator לחיות בו.** הוא מובנה לתמונה ורץ כשירות ממושך, אז הוא צריך ריפו אמיתי, לא קובץ סקראץ'. Evaluators לעתים קרובות חיים בריפו שלהם, נפרדים מהסוכן שנדרג — הכישרון חפש אחד קיים ושואל לפני סיבוך חדש. -3. **גלגל `agenteye-evaluator` SDK** — קרא את הסעיף הבא לפני שהסוכן שלך מתחיל להקליד `pip` פקודות. +1. **`agenteye` CLI מותקן ומחובר** (`pipx install agenteye`, ואז `agenteye login`). המיומנות משענת עליה פעמיים: כדי למשוך את הסשנים האמיתיים שהוא מעצב מולם, וכדי לאשר שניקוד שלך נחת בסוף. ההתחברות שלך צריכה `events:read`, בתוספת `evaluations:read` לבדיקה הסופית הזו. כמו ב-CLI skill, היא **לא יכולה** להשלים את התחברות קוד חד פעמי בהודעת דוא״ל בשבילך. +2. **מקום כדי שה-evaluator יגור בו.** הוא בנוי לתוך תמונה ורץ כשירות ארוך טווח, אז הוא צריך repo אמיתי, לא קובץ scratch. Evaluators לרוב גרים ב-repo משלהם, נפרדים מהסוכן שנוקד — המיומנות מחפשת קיימת ושואלת לפני scaffolding אחד חדש. +3. **wheel ה-`agenteye-evaluator` SDK** — קרא את הסעיף הבא לפני שהסוכן שלך מתחיל להקליד פקודות `pip`. --- -## איפה להשיג זאת +## איפה להשיג את זה -הכישרון פורסם בקולקציית הכישרונות הציבורית של Failproof AI: +המיומנות פורסמה בקולקציית המיומנויות הציבורית של Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -המחסן ציבורי והכישרון לא זקוק לכל אישור משלו — הוא רק מנהל את `agenteye` CLI עם הסשן *שלך* התחברת אליו, וכותב קוד בריפו *שלך*. שים לב שהוא מסופק כתיקייה משלו ו**לא** בתוך חבילת `pipx install agenteye`, אז אל תחפש אותו שם. +המחסן הוא ציבורי והמיומנות לא צריכה כל זכות גישה משלה — היא רק מנהלת את CLI של `agenteye` עם הסשן *שאתה* התחברת אליו, וכותבת קוד ב*repo שלך*. שים לב שהיא משלחת כתיקייה משלה וזו **לא** בתוך חבילת `pipx install agenteye`, אז אל תחפש אותה שם. -## התקנת הכישרון +## התקנת המיומנות -הנתיב המהיר ביותר הוא [`skills`](https://skills.sh) CLI, המביא את התיקייה וזורקת אותה למקום שהסוכן שלך מחפש: +הנתיב המהיר ביותר הוא [`skills`](https://skills.sh) CLI, שמביא את התיקייה ומוריד אותה למקום שהסוכן שלך מחפש: ```bash -# Claude Code, this project only +# Claude Code, project זה בלבד npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -# every project (installs to ~/.claude/skills/) +# כל project (מתקנן ל-~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy -# Codex instead +# Codex במקום זה npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -אז נהל זאת כמו כל כישרון אחר: +אז נהל אותה כמו כל מיומנות אחרת: ```bash -npx skills list -a claude-code # what's installed -npx skills update agenteye-evaluator # pull the latest version -npx skills remove agenteye-evaluator # remove it +npx skills list -a claude-code # מה מותקן +npx skills update agenteye-evaluator # משוך את הגרסה האחרונה +npx skills remove agenteye-evaluator # הסר אותה ``` -מעדיף להתקין ביד? Agent Skill הוא רק תיקייה המכילה `SKILL.md` (בתוספת הפניות אופציונליות), אז הועתקה עובדת גם: +תעדיף להתקנן ביד? Agent Skill הוא רק תיקייה המכילה `SKILL.md` (בתוספת הפניות אופציונליות), אז העתקה עובדת גם: -- **Claude Code**: הצב את תיקייה `agenteye-evaluator/` ב-`~/.claude/skills/` (כל פרויקט) או `/.claude/skills/` (הריפו הזה בלבד). Claude Code גילוי אוטומטי שלה — אימות עם רשימה `/skills`, או פשוט שאל אותו evals. -- **Codex (OpenAI)**: Codex קורא אותו `SKILL.md`. ה-`agents/openai.yaml` המצורף מגדיר `allow_implicit_invocation: true`, אז Codex בחירה אוטומטית בכישרון כאשר משימה תואמת; אחרת הזמן זאת בפירוש כ-`$agenteye-evaluator`. +- **Claude Code**: שים את תיקיית `agenteye-evaluator/` ב-`~/.claude/skills/` (כל project) או `/.claude/skills/` (ה-repo הזה בלבד). Claude Code גילוי עצמי אותה — אמת עם הרשימה `/skills`, או פשוט שאל עבור evals. +- **Codex (OpenAI)**: Codex קורא את אותו `SKILL.md`. ה-`agents/openai.yaml` המצורף קובע `allow_implicit_invocation: true`, אז Codex בוחר את המיומנות באופן אוטומטי כשמשימה תואמת; אחרת קרא אותה מפורשות כ-`$agenteye-evaluator`. --- -## ה-SDK לא ב-PyPI הציבורי +## ה-SDK לא ברשת PyPI הציבורית -> **Warning:** קרא את זה לפני שאתה מעביר סוכן להתקין את ה-SDK. +> **Warning:** קרא את זה לפני ששאתה משאיר סוכן להתקנן את ה-SDK. -הכישרון ציבורי; ה-SDK שהוא מנהל אינו. `agenteye-evaluator` משודר רק כיצירה ריליז פרטית, ובשונה מ-`agenteye`, השם הוא **לא תבועה על PyPI ציבורי** — אז `pip install agenteye-evaluator` חשוף יכול לשוך חבילה של זר לתוך השירות שקורא את התמלילים של הייצור שלך. זה בעיה של שרשרת אספקה, לא טעות הקלדה. +המיומנות היא ציבורית; ה-SDK שהיא מנהלת לא. `agenteye-evaluator` משלחים רק כ-release artifact פרטי, ובניגוד ל-`agenteye`, השם הוא **unclaimed ברשת PyPI הציבורית** — אז `pip install agenteye-evaluator` בחוקי עלול למשוך חבילה של זר לתוך השירות שקורא תמלילים ייצורי שלך. זו בעיה של supply-chain, לא typo. -הכישרון יודע זאת ועוסק בסולם התקנה במקום, עוצר בשלב הראשון החל: ה-monorepo מקור אם אתה בתוך ריפו AgentEye, אחרת גלגל ריליז פרטי מ-GitHub Releases (צריך גישה), ואם כלום לא נגיע זה **עוצר ואומר לך לשאול את איש הקשר Failproof AI שלך לגלגל** במקום improvising. +המיומנות יודעת את זה ועובדת משדרג התקנה במקום, עוצרת בדרג ראשון שחל: מקור ה-monorepo אם אתה בתוך ה-AgentEye repo, אחרת ה-wheel של release פרטי מ-GitHub Releases (צריך גישה), ואם לא משהו מהם ניתן להגיע זה **עוצר ואומר לך לשאול את הקשר Failproof AI שלך עבור ה-wheel** במקום improvising. -אז אם הסוכן שלך מציע `pip install agenteye-evaluator` חשוף מ-PyPI ציבורי, זה הדבר שהכישרון לא היה נטען. עצור שם בדוק שהוא מותקן. +אז אם הסוכן שלך מציע `pip install agenteye-evaluator` בחוקי מרשת PyPI הציבורית, זה הסימן שהמיומנות מעולם לא נטענה. עצור שם ובדוק שהוא מותקן. --- ## מה אתה יכול לשאול אותו -סיבוב טיול אמיתי מתחיל בשאלה עמומה ומסתיים בעיצוב שחתום, לא עם קוד: +סיבוב אמיתי מעגל מתחיל בבקשה בעלמת מעלה ומסתיים בעיצוב חתום, לא בקוד: ```text you ▸ I want evals for our support bot. I think it's sometimes bad. @@ -146,23 +144,23 @@ agent ▸ No evaluator in this repo. Should I scaffold one here, or do you have one elsewhere? ``` -משם זה כותב את המימדים המבוססים על כללים קודם (חינם, מיידי, דטרמיניסטי), בודק אותם כנגד סשן שלכד אמיתי כולל הריקים והעולם לא בסוף שמתרסקים naive evaluators, ורק מגיע לשופט LLM בממד הסובייקטיבי. זה יודע את [מגבלות ה-dispatcher](/he/agenteye/evaluation-suite#configuring-the-server) — timeout בקשה 30 שניות ו-8 שיחות בו-זמנית פריסה-רחבה — אז אם השופט לא יתאים בהצלחה, זה הולך async עם `JobPending` במקום להפוך את השופט שלך לחצוי וחזור חמש פעמים בחמש פעמים העלות. +משם היא כותבת את הממדים מבוססי הכללים קודם לכן (חינם, מיידי, דטרמיניסטי), בודקת אותם מול סשן אמיתי שנתפס כולל הריקים ואלה שמעולם לא הסתיימו שמתרסקים naïve evaluators, ורק מגיעה לשופט LLM בממד סובייקטיבי. היא יודעת את [גבולות ה-dispatcher](/he/agenteye/evaluation-suite#configuring-the-server) — timeout בקשה של 30s ו-8 קריאות עוקבות deployment-wide — אז אם השופט לא יתאים בעדינות, היא הולכת async עם `JobPending` במקום להשאיר את השופט שלך לקבל ביטול וניסיון חוזר חמש פעמים בחמש פעמים הוצאה. -אז זה פורס, מגדיר את שני משתני סביבת השרת, ומאשר עם `agenteye --json evals --session-id ` ש-scores בעצם נוחתו. ניקודים נחתו הוא ההוכחה היחידה. +ואז היא פורסמת, קובעת את שני משתני סביבת השרת, ומאשרת עם `agenteye --json evals --session-id ` שניקוד באמת נחת. ניקוד נחת הוא ההוכחה היחידה. --- -## מה להשגיח על +## מה להיזהר ממנו -- **שמות מימדים קרובים לקבוע.** מפתחות ניקוד הם מחרוזות שרירותיות והפלטפורמה עולה כל דבר שאתה שולח, מה שאומר שום דבר במורד הזרם מתקן בחירה רעה. שנה קורא ובמימדים נפרדים: סשנים ישנים שמור המפתח הישן והטרנד שבר. זו הסיבה שהכישרון מקבל חתימה מוגדרת לפני קוד כתיבה — קח את ההנחיה ברצינות. -- **Fixtures הם תמלילי ייצור אמיתיים.** עיצוב כנגד סשנים אמיתיים אומר שוך אותם לדיסק, והם יכולים להכיל נתוני לקוח. הכישרון שואל לפני התחייב שלהם לגיט; אם בספק, שמור `fixtures/` מחוץ לריפו ויש כל מפתח לשוך שלהם שלהם. -- **הסוכן כותב ופורס שירות שקורא כל תמליל.** זה עובד כמוך, מחובר לפי ההרשאות של כניסת ה-CLI שלך, אבל סקור את ה-evaluator כמו כל קוד אחר שנוגע לנתוני ייצור. +- **שמות ממדים קרובים לקבוע.** מפתחות ניקוד הם מחרוזות שרירותיות והפלטפורמה טוענת כל מה שאתה שולח, כלומר שום דבר downstrem לא מתקן בחירה רעה. שנה שם מאוחר יותר והתיש מחלוקת: סשנים ישנים שומרים על המפתח הישן והמגמה שבירה. זו הסיבה שהמיומנות מקבלת חתימה מפורשת לפני כתיבת קוד — קח את ה-prompt הזה ברצינות. +- **Fixtures הם תמלילים ייצורי אמיתיים.** עיצוב מול סשנים אמיתיים פירושו משיכתם לדיסק, והם יכולים להכיל נתוני לקוח. המיומנות שואלת לפני הפעלה אותם לתוך git; אם ספק, שמור `fixtures/` מחוץ ל-repo ויש לכל developer למשוך משלהם. +- **הסוכן כותב ופורס שירות שקורא כל תמליל.** היא פועלת כמוך, bounded על ידי הרשאות ההתחברות CLI שלך, אבל בחזור על ה-evaluator כמו קוד אחר שנוגע בנתוני ייצור. --- -## הצעדים הבאים +## צעדים הבאים -- **[Evaluation suite](/he/agenteye/evaluation-suite)**: החוזה HTTP, ה-SDK, ומשתני סביבת השרת שהכישרון מגדיר. -- **[Evaluations](/he/agenteye/evaluations)**: איפה הניקודים מופיעים ברגע שהם נוחתו. -- **[CLI skill](/he/agenteye/cli-skill)**: הכישרון האחות, לקריאת תוצאות במקום בנייה של המדרג. -- **[CLI](/he/agenteye/cli)**: הנושא הפקודה מאחורי נתוני הסשן שהכישרון עיצוב כנגדו. \ No newline at end of file +- **[Evaluation suite](/he/agenteye/evaluation-suite)**: החוזה HTTP, ה-SDK, ומשתני סביבת השרת שהמיומנות קובעת. +- **[Evaluations](/he/agenteye/evaluations)**: היכן הניקוד מופיע ברגע שהוא נחת. +- **[CLI skill](/he/agenteye/cli-skill)**: המיומנות האחות, לקריאת תוצאות במקום בנייה של ה-scorer. +- **[CLI](/he/agenteye/cli)**: התייחסות הפקודה מאחורי נתוני הסשן שהמיומנות עיצוב מולם. \ No newline at end of file diff --git a/docs/he/agenteye/event-stream.mdx b/docs/he/agenteye/event-stream.mdx index 38225d18..a89546ac 100644 --- a/docs/he/agenteye/event-stream.mdx +++ b/docs/he/agenteye/event-stream.mdx @@ -1,50 +1,51 @@ --- +--- title: "Event Stream" -description: "ברגע שהエージェנט שלך עושה משהו, אתה רואה את זה." +description: "ברגע שהסוכן שלך עושה משהו, אתה רואה זאת." --- -ברגע שהエージェนט שלך עושה משהו, אתה רואה את זה. ה-Event Stream הוא הדופק החי שלך על כל agent בייצור: ללא המתנה, ללא חיפוש בלוגים, ללא ניחוש מה זה עתה קרה. +ברגע שהסוכן שלך עושה משהו, אתה רואה זאת. Event Stream הוא הדופק החי שלך על כל סוכן בייצור: ללא המתנה, ללא חיפוש בלוגים, ללא ניחושים מה זה עתה קרה. -![ה-Event Stream החי: שורות אירוע בצבעים שונים המתעדכנות בזמן אמת, ניתנות לסינון לפי סביבה, agent, session, סוג אירוע וחיפוש חופשי](/agenteye/images/events-stream.png) +![ה-Event Stream החי: שורות אירועים צבועות קוד בזמן אמת, ניתנות לסינון לפי סביבה, סוכן, סשן, סוג אירוע וטקסט חופשי](/agenteye/images/events-stream.png) -*כל אירוע מכל agent בארגון שלך, החדש ביותר קודם, מתעדכן כשזה קורה.* +*כל אירוע מכל סוכן בארגון שלך, החדשים ביותר קודם, מתעדכנים כשזה קורה.* -## הדופק החי שלך על כל agent +## הדופק החי שלך על כל סוכן -כאשר agent מתחיל run, קורא ל-model, משתמש בכלי, מריץ hook או נתקל בשגיאה, השורה מופיעה בראש הזרם ברגע שזה קורה. זה עוקב אחרי כל אירוע בכל agent בארגון שלך, החדש ביותר קודם, כך שתמיד יש לך תמונה עדכנית במקום ישנה. +כשסוכן מתחיל הרצה, קורא מודל, מפעיל כלי, מריץ hook, או נתקל בשגיאה, השורה מופיעה בחלק העליון של הזרם ברגע שזה קורה. זה עוקב אחרי כל אירוע על פני כל סוכן בארגון שלך, החדשים ביותר קודם, כך שיש לך תמיד תמונה עדכנית במקום ישנה. -זה אומר ללא ניטור קבצי לוג בשרת כלשהו, ללא חיפוש על מכונות שונות, ללא חיבור timestamps ביד. אתה פותח עמוד אחד והוא כבר שומר על הייצור. +זה אומר ללא עקיבה אחרי קבצי לוג בקופסה כמו שם, ללא חיפוש על פני מחשבים, ללא תפירת חותמות זמן ביד. אתה פותח עמוד אחד וכבר אתה צופה בייצור. -השורות בצבעיות לפי סוג, כך שתוכל לקרוא את הזרם במבט חטוף במקום לנתח כל שורה. במבט חטוף, כל שורה מראה לך: +שורות צבועות קוד לפי סוג, כך שאתה יכול לקרוא את הזרם בהצצה במקום לעבור כל שורה. בהצצה, כל שורה מראה לך: -- **את הסוג שלו**, בצבעיות: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, ועוד. -- **סיכום בשורה אחת** של מה שקרה, כך שנדיר שצריך לפתוח משהו רק כדי להבין את הרעיון הכללי. -- **ספירות tokens** עבור הצעד. -- **תג מילוי context-window** שם זה רלוונטי, כך שגדילת prompt וsquash הקרוב נראים לעין לפני שהם גורמים לבעיות. +- **הסוג שלה**, צבוע קוד: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, ועוד. +- **סיכום בשורה אחת** של מה שקרה, כך שאתה רק לעתים רחוקות צריך לפתוח משהו רק כדי להבין את הרעיון. +- **ספירות טוקנים** לשלב. +- **תג מילוי חלון הקשר** שם זה רלוונטי, כך שגדילת ההנמקה וקום דחיסה קרוב גלוי לפני שהוא נוגע. -ניטור בזמן אמת פירושו שתופס deploy גרוע, לולאה שהופכת להוראשית, או פרץ של שגיאות כשזה קורה, לא בביקורת הלוג של מחר. +צפייה בזמן אמת אומר שאתה תופס deploy גרוע, לולאה שמתנגדת, או התפרצות של שגיאות כשזה קורה, לא בביקורת הלוג של מחר. -## מצא את ה-run היחיד שחשוב +## מצא את ההרצה האחת שחשובה -כאשר משהו נראה לא בסדר, לא תרצה את כל הנתונים. אתה רוצה את ה-run היחיד שהשתבר. הזרם מסנן במהירות: לפי סביבה, לפי agent, לפי session, לפי סוג אירוע, או לפי חיפוש חופשי. +כשמשהו נראה לא בסדר, אתה לא רוצה את הכיבוי מלא. אתה רוצה את ההרצה היחידה שהשתברה. הזרם מסנן במהירות: לפי סביבה, לפי סוכן, לפי סשן, לפי סוג אירוע, או לפי טקסט חופשי. -סנן לפי session id או agent id כדי לעקוב אחרי run אחד מהאירוע הראשון שלו לאחרון. סנן לפי סוג אירוע כדי לבודד סוג אחד של פעילות, לדוגמה כל `error` בכל הארגון בתצוגה אחת. ערם מסננים כדי להצטמצם מ"הכל, בכל מקום" ל"agent זה, בייצור, עם שגיאות" בזוג קליקים, ואז פעול לפי מה שתמצא. +סנן לפי מזהה סשן או מזהה סוכן כדי לעקוב אחרי הרצה אחת מהאירוע הראשון שלה לאחרון שלה. סנן לפי סוג אירוע כדי לבודד סוג אחד של פעילות, למשל כל `error` על פני הארגון בתצוגה אחת. ערום סינונים כדי להצטמק מ-"הכל, בכל מקום" ל-"הסוכן הזה, בייצור, שגיאה" בכמה קליקים, ואז פעול על מה שאתה מוצא. -חיפוש חופשי חוצה ישירות להודעה, שם כלי, או id שכבר יש לך ביד, כך שדוח של לקוח הופך ל-run המדויק תוך שניות. +חיפוש טקסט חופשי חוצה ישר להודעה, שם כלי, או מזהה שיש לך כבר ביד, כך שדוח של לקוח הופך להרצה המדויקת בתוך שניות. -## איפה למצוא את זה +## היכן למצוא זאת -ה-Event Stream הוא בית הארגון שלך. התחברות והוא הראשון בו אתה נוחת, ב-`//`, כך שהטריאז מתחיל ברגע שאתה מגיע. +Event Stream הוא בית הארגון שלך. היכנס וזו הגדול הראשון שאתה נוחת עליו, ב-`//`, כך שהטריאז מתחיל ברגע שאתה מגיע. -מאחוריו, ה-agents שלך פולטים אירועים דרך ה-SDK, ה-collector משלח אותם לשרת Failproof AI Observability שלך, והזרם עוקב אחריהם כשהם מגיעים לתשתית שאתה שולט בה. כאשר אתה רוצה את התצוגה המצטברת במקום את השביל הגולמי, האירועים של כל run קורסים לשורה אחת ב-Sessions, קליק אחד משם. +מאחורי זה, הסוכנים שלך פולטים אירועים דרך ה-SDK, הקולט שולח אותם לשרת Failproof AI Observability שלך, והזרם עוקב אחריהם כשהם מגיעים בתשתית שאתה שולט בה. כשאתה רוצה את התצוגה המגובשת במקום השביל הגולמי, אירועי הרצה של כל הרצה קורסים לשורה יחידה ב-Sessions, קליק אחד משם. -זה האמת הגולמית שעליה כל משטח observe אחר בנוי, כך שכאשר מספר נראה לא נכון במקום אחר, הזרם הוא המקום בו אתה מאשר מה שבאמת קרה. +זה המקור הגולמי של האמת שכל גדול צפיה אחר בונה עליו, כך שכשמספר נראה לא בסדר במקום אחר, הזרם הוא היכן שאתה מאשר מה בעצם קרה. ## קשור -- [Sessions](/he/agenteye/sessions): אותם אירועים מצטברים לשורה אחת לכל run, עם גרף ביצוע בסגנון git. -- [Telemetry](/he/agenteye/telemetry): מה שה-agents שלך שולחים וכיצד אירועים מגיעים לזרם. -- [Error tracking](/he/agenteye/error-tracking): משטח טריאז אחד לכל מה שנפל. -- [Alerts](/he/agenteye/alerts): הפוך כל סף לכלל paging. -- [CLI and agents](/he/agenteye/cli-and-agents): אותו שביל חי מהטרמינל שלך. \ No newline at end of file +- [Sessions](/he/agenteye/sessions): אותם אירועים מגובשים לשורה אחת לכל הרצה, עם גרף ביצוע בסגנון git. +- [Telemetry](/he/agenteye/telemetry): מה הסוכנים שלך שולחים וכיצד אירועים מגיעים לזרם. +- [Error tracking](/he/agenteye/error-tracking): גדול טריאז אחד לכל מה שהלך לא בסדר. +- [Alerts](/he/agenteye/alerts): הפוך כל סף לכלל עמודים. +- [CLI and agents](/he/agenteye/cli-and-agents): אותו שביל חי מהסוף שלך. \ No newline at end of file diff --git a/docs/he/agenteye/hermes-capture.mdx b/docs/he/agenteye/hermes-capture.mdx index b67d0c6d..07ee4fdb 100644 --- a/docs/he/agenteye/hermes-capture.mdx +++ b/docs/he/agenteye/hermes-capture.mdx @@ -1,54 +1,54 @@ --- --- title: "Hermes session capture" -description: "הביאו את ישיבות Hermes gateway של הצוות שלכם — Slack, Telegram, CLI, והרצות מתוזמנות — ל-AgentEye כישיבות ואירועים רגילים." +description: "הביאו את sessions של Hermes gateway של הצוות שלכם — Slack, Telegram, CLI, וריצות מתוזמנות — ל-AgentEye כ-sessions ו-events רגילים." --- -[Hermes](https://hermes-agent.nousresearch.com) עונה לצוות שלכם מכל מקום שבו הם כבר עובדים — Slack, Telegram, ה-CLI, הרצות מתוזמנות. Hermes session capture מביא הכל ל-AgentEye כישיבות ואירועים רגילים, כך שהעוזר שהצוות מדבר איתו כל יום ניתן להצפה בדיוק כמו ה-agents שאתם כותבים בעצמכם. +[Hermes](https://hermes-agent.nousresearch.com) עונה לצוות שלכם מכל מקום שבו הם כבר עובדים — Slack, Telegram, CLI, ריצות מתוזמנות. Hermes session capture מביא הכל ל-AgentEye כ-sessions ו-events רגילים, כך שהassistant שהצוות שלכם מדבר איתו כל יום ניתן להצפות בדיוק כמו agents שאתם כותבים בעצמכם. -אספן רקע קטן קורא את חנות הישיבות המקומית של Hermes כשהיא נכתבת ומשדר ישיבות ל-AgentEye. זה עובד באותו אופן כמו [Codex](/he/agenteye/codex-capture) ו-[OpenClaw](/he/agenteye/openclaw-capture) capture, ואספן אחד יכול ללכוד כמה בו זמנית. +מאסף רקע קטן קורא את local session store של Hermes בזמן שהוא נכתב ומשדר sessions ל-AgentEye. זה עובד בדיוק באותו אופן כמו [Codex](/he/agenteye/codex-capture) ו-[OpenClaw](/he/agenteye/openclaw-capture) capture, ומאסף אחד יכול ללכוד מספר בו זמנית. --- -## מה זה תופס +## מה הוא לוכד -כל ישיבת Hermes במכונה תופסת, באיזה ערוץ שהיא הגיעה. כל אחת הופכת ל-[session](/he/agenteye/sessions) ב-AgentEye; הודעות המשתמש והעוזר שלה, קריאות כלים ותוצאות כלים הופכות ל-[events](/he/agenteye/event-stream) התואמים. +כל Hermes session במכונה נלכד, לא משנה באיזה channel הוא הגיע. כל אחד הופך ל-AgentEye [session](/he/agenteye/sessions); הודעות המשתמש וה-assistant שלו, tool calls, וtool results הופכים ל-matching [events](/he/agenteye/event-stream). -הערוץ שממנו התחילה ישיבה — Slack, Telegram, CLI, או הרצה מתוזמנת — מתועד בישיבה, כך שאתה יכול להבחין בהם ולסנן לאחד בכל פעם. לצידו מגיע המודל שעליו רצה הישיבה, הצ'אט והאדם שממנו הוא הוקם, ובכל פעם שישיבה יצרה שנייה, הקישור חזרה להורה שלה. +ה-channel שממנו התחיל session — Slack, Telegram, CLI, או ריצה מתוזמנת — מתורשם ב-session, כך שתוכלו להבחין ביניהם ולסנן לאחד בכל פעם. לצידו מגיע ה-model שעליו רץ ה-session, ה-chat והאדם ממנו הוא הוקם, וכשsession הוליד session אחר, הקישור בחזרה להורה שלו. -ישיבות מופיעות ברגע שב-Hermes הם מתחילים אותם, בין אם משהו נאמר או לא, וההשגה של תור וקריאות הכלים שלו נשארות בסדר שבו הן בעצם קרו. כשישיבה מסתיימת אתה גם מקבל למה היא הסתיימה, מה היא עלתה, וכמה tokenים היא השתמשה. +Sessions מופיעים ברגע שHermes מתחיל אותם, בין אם משהו נאמר או לא, ותשובה של turn וה-tool calls שלה נשמרים בסדר שבו הם בעצם התרחשו. כשsession מסתיים, אתם גם מקבלים למה הוא התחיל, מה זה עלה, וכמה tokens הוא השתמש. --- -## הפעלתו +## הפעילו אותו -ה-capture כבוי עד שאתה מפעיל אותו. התקן את האספן עם מפתח API שיש לו את ההרשאה `events:add` (ראה [API keys](/he/agenteye/api-keys)), והפעל Hermes capture: +Capture כבוי עד שתפעילו אותו. התקינו את המאסף עם API key שיש לו את ההרשאה `events:add` (ראו [API keys](/he/agenteye/api-keys)), והפעילו את Hermes capture: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -זה מתקין את האספן, רושם אותו כשירות רקע, ומתחיל ללכוד. אשר שהוא פועל: +זה מתקין את המאסף, רושם אותו כשירות רקע, ומתחיל ללכוד. אשרו שהוא פועל: ```bash agenteye-collector health ``` -תופסים יותר מ-agent אחד באותה מכונה? הוסף את הדגל של כל אחד לאותה הפקודה — למשל `--hermes-enabled --codex-enabled`. +לוכדים יותר מagent אחד באותה מכונה? הוסיפו את הflag של כל אחד לאותה פקודה — למשל `--hermes-enabled --codex-enabled`. -בהרצה הראשונה, הישיבות Hermes הקיימות שלך מלאות חזרה פעם אחת והפעילות החדשה אז נשדרת תוך שניות. נתוני Hermes שלהם נקראים בלבד — לעולם לא שונו או נמחקו — וכל הודעה משודרת פעם אחת, גם על פני הפעלות מחדש. +בריצה הראשונה, ה-Hermes sessions הקיימים שלכם מולאו אחורה פעם אחת וactivity חדש אז streaming תוך שניות. ה-data של Hermes עצמו נקרא בלבד — לא מעודכן או מחוק — וכל הודעה משודרת פעם אחת, אפילו על פני restarts. -`health` גם אומר לך אם הכל שהאספן תפס בעצם הגיע ל-AgentEye. אם קבוצה לא יכלה להיות מסופקת היא נשמרת ובוחנת שוב במקום להיהנות, והבדיקה מדווחת בריאה אם משהו עדיין בהמתנה — כך "בריא" פירושו שהנתונים שלך הגיעו, לא רק שהתהליך קיים. +`health` גם אומר לכם אם כל מה שהמאסף לכד בעצם הגיע ל-AgentEye. אם batch לא יכול היה להיות מועבר, הוא נשמר ונסיון חוזר במקום להיות מושלך, והבדיקה דיווחת unhealthy כל עוד משהו עדיין חוזר — אז "healthy" פירושו שה-data שלכם הגיע, לא רק שהתהליך חי. --- -## היכן זה מופיע +## איפה זה מופיע -ישיבות שנתפסו מופיעות ב-**Sessions**, והאירועים שלהם בזרם **Events**, בדיוק כמו כל agent אחר שאתה צופה בו — כך [session replay](/he/agenteye/sessions), [search](/he/agenteye/queries), [evaluations](/he/agenteye/evaluations), ו-[alerts](/he/agenteye/alerts) כולם עובדים עליהם. סנן לפי ה-Hermes agent כדי לראות אותם בעצמם. +Sessions שנלכדו מופיעים ב-**Sessions**, ו-events שלהם ב-stream **Events**, בדיוק כמו agent אחר שאתם צופים בו — כך ש-[session replay](/he/agenteye/sessions), [search](/he/agenteye/queries), [evaluations](/he/agenteye/evaluations), ו-[alerts](/he/agenteye/alerts) כולם עובדים עליהם. סננו לפי ה-Hermes agent כדי לראות אותם בעצמם. --- ## פרטיות -ישיבות Hermes מכילות את השיחה המלאה — כולל פלט פקודה, תכנים של קבצים, וכל דבר שהעוזר קרא או כתב — ויכולות להכיל סודות. ישיבות שנתפסו משודרות כמו שהן, כך להפעיל capture רק במקום שבו ריכוז תכנים זה AgentEye הוא מתאים, ותן לאספן מפתח מוגבל ל-`events:add` בלבד. ראה [Security](/he/agenteye/security) לאופן שבו הנתונים שלך נשמרים בידוד. \ No newline at end of file +Hermes sessions מכילים את התמלול המלא — כולל output של פקודות, תוכן קבצים, וכל דבר שה-agent קרא או כתב — ויכולים להכיל secrets. Captured sessions משודרים כפי שהם, כך שהפעילו capture רק כשמרכוז תוכן זה ב-AgentEye הוא הולם, והעניקו למאסף key בהיקף `events:add` בלבד. ראו [Security](/he/agenteye/security) לפרטים כיצד ה-data שלכם מוחזק מבודד. \ No newline at end of file diff --git a/docs/he/agenteye/incidents.mdx b/docs/he/agenteye/incidents.mdx index 6989381b..b4c1140b 100644 --- a/docs/he/agenteye/incidents.mdx +++ b/docs/he/agenteye/incidents.mdx @@ -1,28 +1,28 @@ --- -title: "תקריות" -description: "כאשר התראה משתלחת, כולם יכולים לראות שהתקרית פתוחה, מי בעלות עליה, ומה קרה עד כה — על ציר זמן אחד מיוחס." +title: "Incidents" +description: "כאשר התראה מופעלת, כל אחד יכול לראות שהתרעה פתוחה, מי בעל אחריות עליה, ומה קרה עד כה — בשורה זמן אחת מיוחסת." --- -כאשר התראה משתלחת, השאלה הראשונה היא תמיד "מי עוסק בזה?" תקריות עונות לזה: ברגע שמשהו חורץ, כולם יכולים לראות שהתקרית פתוחה, מי בעלות עליה, בדיוק מה קרה עד כה, עם רשומה נקייה ומיוחסת שאתה יכול להעביר ישירות לניתוח-פוסט-מורטם. +כאשר התראה מופעלת, השאלה הראשונה היא תמיד "מי טוען בזה?" Incidents עונה על זה: ברגע שמשהו חוצה סף, כל אחד יכול לראות שהתרעה פתוחה, מי בעל אחריות עליה, ובדיוק מה קרה עד כה, עם רשומה ברורה ומיוחסת שניתן להעביר ישירות לניתוח postmortem. -![תיבת הנכנסים של התקריות: כרטיסי תקרית המקושרים להתראה וכרטיסים שנפתחו ידנית, מקובצים לפי מצב, כל אחד עם תג חומרה ו-assignee](/agenteye/images/incidents.png) -*תיבת הנכנסים מקבצת תקריות פתוחות לפי מצב ומסננת לפי חומרה ו-assignee, כך שאתה רואה מה זקוק לתשומת לב אנושית כעת.* +![תיבת הנכנסים של Incidents: כרטיסי תרעה מקושרים ותרעות שנפתחו ידנית, מקובצים לפי מצב, כל אחד עם תג חומרה וגם מי שהוא מוקצה](/agenteye/images/incidents.png) +*תיבת הנכנסים מקבצת תרעות פתוחות לפי מצב ומסננת לפי חומרה ומקצה, כך שאתה רואה מה זקוק להתערבות אנושית כרגע.* -## דע מי בעלות, במבט אחד +## דע מי טוען בזה, במבט אחד -לא עוד "האם מישהו בודק את זה?" בשרשור צ'אט. הפרה פותחת תקרית באופן אוטומטי ותופלת אותה לתיבה משותפת, מקובצת לפי מצב. אשר עליה והשם שלך עליו, כך ששאר הצוות יודע שהיא מטופלת. אישור משותף: מספר אופרטורים יכולים לאשר אותה תקרית ואישורו של כל אחד מהם מתועד בנפרד, כך שחדר מלחמה שלם מופיע בשמות במקום להעלות אחד על השני. הקצה בעלים אחד לפחיתות, וסנן את תיבת הנכנסים לפי חומרה או assignee כדי לצמצם לזה שלך. +אין עוד "האם מישהו בודק את זה?" בשרשור צ'אט. הפרה פותחת תרעה באופן אוטומטי וזורקת אותה לתיבת נכנסים משותפת, מקובצת לפי מצב. הכר בה ושמך על הדף, כך ששאר הצוות יודע שזה מטופל. הכרה היא משותפת: מספר מפעילים יכולים להכיר בתרעה זהה וכל אחד נרשם בנפרד, כך שחדר מלחמה מלא מופיע בשם במקום לדרוך זה על זה. הקצה בעל אחריות אחד לפחיתה, וסנן את תיבת הנכנסים לפי חומרה או מקצה כדי להקטין אותה למה שלך. -## כל הסיפור, בציר זמן אחד +## הסיפור כולו, בשורה זמן אחת -כשהתקרית מסתיימת, כבר יש לך את הכתיבה. פתח כל תקרית ותקבל את ראיות ההפרה, את ה-assignees והמנויים שלה, שרשור הערות לתיאום במקום, וציר זמן פעילות יחיד-כיווני. +כאשר התרעה תמומה, כבר יש לך את הכתיבה. פתח כל תרעה ותקבל את עדות ההפרה, את המקצים והמנויים שלה, שרשור הערות לתיאום במקום, ושורה זמן פעילות נוספת בלבד. -![תצוגה פרטי תקרית: ההתראה ההורית וסיכום ההפרה, assignees ומנויים, ציר זמן פעילות מיוחס, ושרשור הערות](/agenteye/images/incident-detail.png) -*כל מה שקרה, בסדר, כל שורה חתומה על ידי מי שעשה זאת.* +![תצוגה מפורטת של תרעה: התראה האם וסיכום הפרה, מקצים ומנויים, שורה זמן פעילות מיוחסת, ושרשור הערות](/agenteye/images/incident-detail.png) +*הכל שקרה, לפי הסדר, כל שורה חתומה על ידי מי שעשה את זה.* -כל פעולה (פתוח, אושר, פתור וכו') נכתבת לציר הזמן הזה ולעולם לא עורכה. כל ערך מיוחס: לאופרטור שלקח אותו, לפי דוא"ל, או ל**automated** עבור כל מה ש-Failproof AI Observability עשה בעצמו, כמו פתיחת התקרית בהפרה. שום דבר אינו אנונימי ושום דבר לא אבד, כך שניתוח-פוסט-מורטם כתוב לעצמו בערך. +כל פעולה (פתוח, מוכר, פתור וכו') נכתבת לשורה הזו ולעולם לא נערכת. כל ערך מיוחס: למפעיל שנקט בה, לפי דוא"ל, או ל**automated** לכל דבר שObservability של Failproof AI עשה בעצמו, כמו פתיחת התרעה בהפרה. כלום אינו אנונימי וכלום לא אובד, כך שהpostmortem כמעט כותב את עצמו. -## איך תקרית זז +## כיצד תרעה נעה ```mermaid stateDiagram-v2 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **Open (firing):** ההפרה פותחת את התקרית ודפה את הערוצים שלך פעם אחת. הפרות חוזרות מתקפלות לאותה תקרית ומרעננות את הראיות שלה במקום לדפק אותך שוב ושוב. -- **Acknowledged:** אופרטור קוטף אותה. היא נשארת פתוחה, והפרות מאוחרות מרעננות את הראיות בשקט. -- **Resolved:** אופרטור סוגר אותה. רזולוציה אוטומטית כשהתנאי מתברר מתוכננת אך עדיין לא מופעלת, כך שתקרית נשארת פתוחה עד שאדם פותר אותה, מה שמשמר את כולם כנים לגבי מה באמת התברר. תקרית טרייה יכולה להיפתח באותה התראה מאוחר יותר. +- **Open (firing):** ההפרה פותחת את התרעה ודופקת בערוצים שלך פעם אחת. הפרות חוזרות מתקפלות לתוך אותה תרעה ומרעננות את העדות שלה במקום לדפוק אותך שוב ושוב. +- **Acknowledged:** מפעיל הוא אותה. זה נשאר פתוח, והפרות מאוחרות מעדכנות את העדות בשקט. +- **Resolved:** מפעיל סוגר אותה. פתרון אוטומטי כאשר התנאי מתפזר מתוכנן אך עדיין לא מופעל, כך שתרעה נשארת פתוחה עד שאדם פותר אותה, מה שמשמר את כל אחד כנה לגבי מה שבעצם מתפזר. תרעה חדשה יכולה להיפתח באותה התראה מאוחר יותר. -התראה אחת מחזיקה לכל היותר תקרית פתוחה אחת בכל פעם, כך ששלטון דש לא יכול להטביע אותך בשכפולים. אתה יכול גם לפתוח תקרית ביד: אחת סטנדאלון לעשsomething שלא התראה תפסה, או אחת המוגבלת להתראה קיימת, אם יש לך `incidents:write`. +התראה אחת מחזיקה לכל היותר תרעה פתוחה אחת בבת אחת, כך שכלל תרידה לא יכולה לקבור אותך בשכפולים. אתה יכול גם לפתוח תרעה ביד: אחת עצמאית עבור משהו שלא התראה תפסה, או אחת המצורפת להתראה קיימת, אם יש לך `incidents:write`. ## איפה למצוא את זה -תקריות חיות ב-`//incidents`. הצפייה זקוקה **`incidents:read`**; פתיחת תקרית ידנית זקוקה **`incidents:write`**; אישור, הקצאה, הערות, ופתרון זקוקים **`incidents:ack`**. מפתחות ישנים יותר שהעניקו את ה-`alerts:ack` המושכת לפנסיון ממשיכים לעבוד, מכיוון שהוא מכובד כ-`incidents:ack`, כך שסיבוב on-call שלך לא צריך הוצאה מחדש. +Incidents גרים ב`//incidents`. הצפייה דורשת **`incidents:read`**; פתיחת תרעה ידנית דורשת **`incidents:write`**; הכרה, הקצאה, הערות ופתרון דורשים **`incidents:ack`**. מפתחות ישנים יותר שהעניקו את ה`alerts:ack` המיושן מתמשכים בעבודה, מכיוון שהוא מכובד כ`incidents:ack`, כך שסיבוב ה-on-call שלך לא צריך הנפקה מחדש. ## קשור -- [Alerts](/he/agenteye/alerts): הכללים שפותחים תקריות אלה כאשר סף חורץ. -- [Error tracking](/he/agenteye/error-tracking): ראה כל כישלון במקום אחד והעלה אחד להתראה. -- [Audits](/he/agenteye/audits): האנליסט המתוכנן שמוצא את הכישלונות שלא היה שום כלל צפה בהם. \ No newline at end of file +- [Alerts](/he/agenteye/alerts): הכללים שפותחים תרעות אלה כאשר סף חוצה. +- [Error tracking](/he/agenteye/error-tracking): ראה כל כישלון במקום אחד וקדם אחד להתראה. +- [Audits](/he/agenteye/audits): האנליסט המתוכנן שמוצא את הכשלים שלא כלל כלל היה צופה. \ No newline at end of file diff --git a/docs/he/agenteye/observability.mdx b/docs/he/agenteye/observability.mdx index 74bf1c8a..1d6c174e 100644 --- a/docs/he/agenteye/observability.mdx +++ b/docs/he/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- -title: "צפייה" -description: "משטחי הצפייה הם המקום שבו אתה רואה מה האג'נטים שלך עושים כרגע וחוקר כל ריצה בודדת." +title: "Observe" +description: "משטחי ה-observe הם המקום שבו אתה צופה במה שהסוכנים שלך עושים כרגע ו-drill into כל ריצה בודדת." --- -משטחי הצפייה הם המקום שבו אתה רואה מה האג'נטים שלך עושים כרגע וחוקר כל ריצה בודדת. הכל כאן הוא בזמן אמת, מסוגנן לארגון שלך, וניתן לסינון לפי טווח תאריכים, סביבה, אג'נט וסשן, כך שאתה עובר מ"משהו לא בסדר" להריצה המדויקת תוך שניות. +משטחי ה-observe הם המקום שבו אתה צופה במה שהסוכנים שלך עושים כרגע ו-drill into כל ריצה בודדת. הכל כאן הוא live, scoped לארגון שלך, וניתן לסינון לפי טווח תאריכים, environment, סוכן, וsession, כך שאתה עובר מ"משהו נראה לא בסדר" לריצה מדויקת בשניות. -![ה-Event Stream בזמן אמת, מעוצב בצבעים לפי סוג וניתן לסינון לפי סביבה, אג'נט וסשן](/agenteye/images/events-stream.png) +![Event Stream חי, צבוע בקוד לפי סוג וניתן לסינון לפי environment, סוכן וsession](/agenteye/images/events-stream.png) -ארבעה משטחים, כל אחד עם הדף שלו: +ארבעה משטחים, לכל אחד שלו דף: -- **[זרם אירועים](/he/agenteye/event-stream)**: שביל בזמן אמת, לפי שלב, של כל ריצה בכל אג'נט, החדש ביותר ראשון. בית הארגון שלך והתחנה הראשונה לטריאז'. -- **[סשנים וגרף ביצוע](/he/agenteye/sessions)**: אירועים אלה מתוקבצים לשורה אחת לכל ריצה, בתוספת תמונה בסגנון git של איך כל ריצה התגלגלה. -- **[מטריקות ביצועים](/he/agenteye/telemetry)**: מפות חום של שהיות וקריטיקלים p50/p95/p99 עבור המודלים, הכלים והוקים שלך, כך שנקודה בחלק העליון בולטת מהחציון. -- **[עקבוי שגיאות](/he/agenteye/error-tracking)**: משטח טריאז' יחיד לכל מה שהשתבש, קליק אחד מהתראה שנשלחה לריצה שקרסה. +- **[Event stream](/he/agenteye/event-stream)**: שביל live, לכל צעד של כל ריצה על פני כל סוכן, החדש ביותר ראשון. בית הארגון שלך ותחנה ראשונה לtriage. +- **[Sessions and execution graph](/he/agenteye/sessions)**: האירועים הללו מסוכמים לשורה אחת לכל ריצה, בתוספת תמונה בסגנון git של איך כל ריצה התפתחה. +- **[Performance metrics](/he/agenteye/telemetry)**: heat-maps של latency וvitals p50/p95/p99 עבור models, tools וhooks שלך, כך שspike בזנב בולט מהmedian. +- **[Error tracking](/he/agenteye/error-tracking)**: משטח triage אחד לכל מה שהלך לא בסדר, לחיצה אחת מalert שירה לריצה ששברה. -## קשור +## Related -- [הערכות](/he/agenteye/evaluations): דרג כל ריצה על איכות. -- [התראות](/he/agenteye/alerts): הפוך כל סף לכלל דיוור. -- [ביקורות](/he/agenteye/audits): תן ל-Failproof AI Observability למצוא דפוסי כשל בסשנים בשבילך. -- [CLI ואג'נטים](/he/agenteye/cli-and-agents): אותה צפיפות מהמסוף שלך. \ No newline at end of file +- [Evaluations](/he/agenteye/evaluations): דרג כל ריצה לאיכות. +- [Alerts](/he/agenteye/alerts): הפוך כל threshold לכלל paging. +- [Audits](/he/agenteye/audits): תן ל-Failproof AI Observability למצוא דפוסי כשל על פני sessions בשבילך. +- [CLI and agents](/he/agenteye/cli-and-agents): אותה observability מהterminal שלך. \ No newline at end of file diff --git a/docs/he/agenteye/openclaw-capture.mdx b/docs/he/agenteye/openclaw-capture.mdx index 057c0616..e4f4f166 100644 --- a/docs/he/agenteye/openclaw-capture.mdx +++ b/docs/he/agenteye/openclaw-capture.mdx @@ -1,50 +1,50 @@ --- --- -title: "תיעוד הפגישות של OpenClaw" -description: "עקוב אחרי פגישות OpenClaw המקומיות של הצוות שלך ב-AgentEye כפגישות ואירועים רגילים — ללא שום שינוי בדרך שבה OpenClaw פועל." +title: "לכידת הפעלות OpenClaw" +description: "עקוב אחרי הפעלות OpenClaw המקומיות של הצוות שלך ל-AgentEye כהפעלות ואירועים רגילים — ללא שינוי בדרך ההפעלה של OpenClaw." --- -אם הצוות שלך מריץ [OpenClaw](https://docs.openclaw.ai), תיעוד הפגישות של OpenClaw מביא את הפגישות האלה ל-AgentEye כפגישות ואירועים רגילים, כך שאתה יכול לחפש, להשמיע שוב, והערכה שלהם לצד כל שאר מה שאתה צופה. זה משלים את [Python SDK](/he/agenteye/python-sdk): ה-SDK מתחקה אחרי agents שאתה כותב, בעוד שזה תוקף את עבודת OpenClaw שהצוות שלך כבר עושה — ללא שום שינוי בדרך שהם מריצים אותה. +אם הצוות שלך מפעיל [OpenClaw](https://docs.openclaw.ai), לכידת הפעלות OpenClaw מביאה הפעלות אלה ל-AgentEye כהפעלות ואירועים רגילים, כך שתוכלו לחפש, להשמיע שוב, ולהעריך אותם לצד כל שאר מה שאתם צופים. זה משלים את [Python SDK](/he/agenteye/python-sdk): ה-SDK מעצב agents שאתם כותבים, בעוד שזה לוכד את עבודת OpenClaw שהצוות שלך כבר עושה — ללא שינוי בדרך הפעלתה. -אספן רקע קטן קורא את תמלול הפגישות המקומיות של OpenClaw כשהם נכתבים ושולח אותם ל-AgentEye. זה עובד בדיוק באותו אופן כמו [Codex capture](/he/agenteye/codex-capture), ואספן אחד יכול ללכוד גם את שניהם בו-זמנית. +אספן רקע קטן קורא תעודות הפעלות מקומיות של OpenClaw כשהן נכתבות וגם משלח אותן ל-AgentEye. זה עובד באותה הדרך כמו [לכידת Codex](/he/agenteye/codex-capture), ואספן אחד יכול ללכוד את שניהם בו-זמנית. --- -## מה זה תוקף +## מה הוא לוכד -כל agent שהוגדר בהגדרת OpenClaw של מכונה מוקלט על ידי אספן המכונה של אותה מכונה — אין כל הגדרה לכל agent. +כל agent שמוגדר בהגדרת OpenClaw של מכונה נלכד על ידי אספן המכונה של אותה מכונה — אין הגדרה לכל agent. -כל פגישת OpenClaw הופכת ל-[session](/he/agenteye/sessions) של AgentEye; ההודעות שלה של המשתמש והעוזר, קריאות הכלים, ותוצאות הכלים הופכות ל-[events](/he/agenteye/event-stream) המתאימים. +כל הפעלת OpenClaw הופכת ל[הפעלה](/he/agenteye/sessions) של AgentEye; ההודעות של משתמש ועוזר שלה, קריאות כלים, תוצאות כלים הופכות ל[אירועים](/he/agenteye/event-stream) תואמים. --- -## הפעלה +## הפעל אותו -התיעוד כבוי עד שתפעיל אותו. התקן את האספן עם מפתח API שיש לו הרשאה `events:add` (ראה [API keys](/he/agenteye/api-keys)), והפעל את תיעוד OpenClaw: +הלכידה כבויה עד שתפעיל אותה. התקן את האספן עם מפתח API שיש לו הרשאה `events:add` (ראה [מפתחות API](/he/agenteye/api-keys)), והפעל את לכידת OpenClaw: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -זה מתקין את האספן, משלם אותו כשירות רקע, ומתחיל לתעד. אשר שהוא פועל: +זה מתקין את האספן, רושם אותו כשירות רקע, ומתחיל ללכוד. אשר שהוא פועל: ```bash agenteye-collector health ``` -תיעוד של יותר מ-agent אחד באותה מכונה? הוסף את הדגל של כל אחד לאותה פקודה — לדוגמה `--openclaw-enabled --codex-enabled`. +לוכד יותר מ-agent אחד באותה מכונה? הוסף את הדגל של כל אחד לאותו הפקודה — למשל `--openclaw-enabled --codex-enabled`. -בהרצה הראשונה, הפגישות הקיימות של OpenClaw שלך משמשות כמילוי פעם אחת ופעילות חדשה זורמת לאחר מכן תוך שניות. קבצים של OpenClaw קוראים בלבד — לעולם לא משונים, מועברים, או מחוקים — וכל פגישה משלוחה בדיוק פעם אחת, גם על פני הפעלות מחדש. +בהפעלה הראשונה, ההפעלות OpenClaw הקיימות שלך מתמלאות לאחור פעם אחת והפעילות החדשה אז משדרת תוך שניות. קבצי OpenClaw שלו קוראים בעצמם — לא משנים, לא מעבירים, ולא מוחקים — וכל הפעלה משודרת בדיוק פעם אחת, אפילו על פני הפעלות מחדש. --- -## היכן זה מופיע +## איפה זה מופיע -פגישות שתועדו מופיעות ב-**Sessions**, והאירועים שלהן בזרם **Events**, בדיוק כמו כל agent אחר שאתה צופה — כך [session replay](/he/agenteye/sessions), [search](/he/agenteye/queries), [evaluations](/he/agenteye/evaluations), ו-[alerts](/he/agenteye/alerts) כולם עובדים עליהם. סנן לפי ה-agent של OpenClaw כדי לראות אותם בעצמם. +הפעלות שנלכדו מופיעות ב**Sessions** והאירועים שלהן בזרם **Events**, כמו כל agent אחר שאתה צופה — כך ש[השמעה מחדש של הפעלות](/he/agenteye/sessions), [חיפוש](/he/agenteye/queries), [הערכות](/he/agenteye/evaluations), ו[התראות](/he/agenteye/alerts) כולן עובדות עליהם. סנן לפי ה-agent של OpenClaw כדי לראות אותם בעצמם. --- ## פרטיות -תמלול של OpenClaw מכיל את הפגישה המלאה — כולל פלט פקודה, תוכן קבצים, וכל דבר שה-agent קרא או כתב — ויכול להכיל סודות. פגישות שתועדו משלוחות כשהן, אז הפעל תיעוד רק על מכונות ועבור צוותים שבהם ריכוז התוכן הזה ב-AgentEye מתאים, ותן לאספן מפתח שמתוחם ל-`events:add` בלבד. ראה [Security](/he/agenteye/security) כדי להבין כיצד הנתונים שלך מובדלים. \ No newline at end of file +תמליל OpenClaw מכיל את כל ההפעלה — כולל פלט פקודה, תוכן קבצים, וכל דבר שה-agent קרא או כתב — ויכול להכיל סודות. הפעלות שנלכדו משודרות כפי שהן, אז הפעל לכידה רק על מכונות ועבור צוותים שם ריכוז תוכן זה ב-AgentEye הוא מתאים, ותן לאספן מפתח שמטווח ל-`events:add` בלבד. ראה [אבטחה](/he/agenteye/security) כדי לבחון כיצד הנתונים שלך מבודדים. \ No newline at end of file diff --git a/docs/he/agenteye/overview.mdx b/docs/he/agenteye/overview.mdx index 62b248ca..1a7bf57b 100644 --- a/docs/he/agenteye/overview.mdx +++ b/docs/he/agenteye/overview.mdx @@ -1,108 +1,108 @@ --- --- -title: "Failproof AI: צפו בסוכנים בחיפוש כשלים" -description: "Failproof AI Observability היא פלטפורמה מארוחסנת בעצמך לצפייה, הערכה וشיפור של סוכנים בבינה מלאכותית בייצור." +title: "Failproof AI: צפייה בסוכני בינה מלאכותית לזיהוי כשלים" +description: "Failproof AI Observability היא פלטפורמה בתצורה עצמית להצפייה, הערכה ושיפור סוכני ה-AI שלך בייצור." --- -Failproof AI Observability היא פלטפורמה מאורחסנת בעצמך לצפייה, הערכה ושיפור של סוכנים בבינה מלאכותית בייצור. היא משמרת הכל שהסוכנים שלכם עושים (כל קריאת כלי, בקשת מודל, hook ושגיאה), מדרגת את איכות כל הרצה, וחושפת את הכשלים שלא ידעתם שצריך לחפש, הכל בדוח בקרים שאתה מפעיל בתוך תשתית שלך. +Failproof AI Observability היא פלטפורמה בתצורה עצמית להצפייה, הערכה ושיפור סוכני ה-AI שלך בייצור. היא רושמת את כל מה שהסוכנים שלך עושים (כל קריאת כלי, בקשת מודל, hook וטעות), מדרגת את איכות כל הרצה, וחושפת את הכשלים שלא ידעת שצריך לחפש אחריהם, הכל בדשבורד שאתה מריץ בתוך התשתית שלך. -אם אתה משגר סוכנים בבינה מלאכותית ואתה עייף מ"ניחוש" למה הרצה השתבשה, זה הדף להתחיל ממנו. הוא מסביר מה Failproof AI Observability נותן לך וכיצד החלקים מתאימים יחד, לפני שתתקין כל דבר. +אם אתה משגר סוכני AI וכבר עייף מלנחש למה הרצה השתבשה, זו העמוד להתחיל. הוא מסביר מה Failproof AI Observability נותן לך וכיצד החלקים מתאימים זה לזה, לפני שתתקין דבר כלשהו. -> **Failproof AI Observability היא מוצר ארגוני מ-Failproof AI.** רוצה לראות את זה בפעולה? בקש הדגמה: שלח דוא"ל ל-[nikita@befailproof.ai](mailto:nikita@befailproof.ai). +> **Failproof AI Observability הוא מוצר enterprise מ-Failproof AI.** רוצה לראות את זה בפעולה? בקש הדגמה: שלח אימייל ל-[nikita@befailproof.ai](mailto:nikita@befailproof.ai). -![הפעלת Failproof AI Observability מצויירת כגרף ביצוע בסגנון git לצד ציר הזמן של האירועים שלה, עם פירוט לכל הרצה של כלים, מודלים וואקות בפס הימני](/agenteye/images/session-detail.png) +![הפעלת Failproof AI Observability מצוירת כגרף ביצוע בסגנון git לצד ציר הזמן של האירועים שלה, עם פירוק לכל הרצה של כלים, מודלים ו-hooks בסרגל הימני](/agenteye/images/session-detail.png) -*כל הרצה של סוכן מצויירת כגרף ביצוע בסגנון git (משמאל) לצד ציר הזמן של האירועים שלה. לכל תת-סוכן מקביל יש נתיב משלו; פס הימני מפרק את הכלים, המודלים, הקשרים וההוצאה לטוקנים עבור ההרצה.* +*כל הרצה של סוכן מצויירת כגרף ביצוע בסגנון git (משמאל) לצד ציר הזמן של האירועים שלה. לכל תת-סוכן מקביל יש נתיב משלו; הסרגל הימני מפרק את הכלים, המודלים, ה-hooks והוצאת הטוקנים עבור ההרצה.* --- ## ראה את זה בפעולה -שני סרטונים קצרים מציגים את שני הדברים שהצוותים מחפשים ראשון: עקבוב אחרי הרצה ומציאת כשלים באופן אוטומטי. +שני סרטונים קצרים מראים את שני הדברים שצוותים מגיעים אליהם ראשונים: מעקב אחר הרצה, וחיפוש כשלים אוטומטי.
-*עקבוב סוכן: עקוב אחרי הרצה אחת שלב אחר שלב, מהיעד לכלים לתשובה סופית.* +*מעקב סוכן: עקוב אחר הרצה יחידה צעד אחר צעד, מהמטרה לכלים לתשובה סופית.*
-*Failproof Audit: תן ל-Failproof AI Observability לחפור בתיעודים שלך בחסות סשנים ולהגיד לך מה לתקן.* +*Failproof Audit: אפשר ל-Failproof AI Observability לכרות את היומנים שלך על פני הפעלות ולהגיד לך מה לתקן.* --- ## למה צוותים משתמשים בזה -- **ראה מה הסוכן שלך בעצם עשה.** כל הרצה הופכת לגרף ביצוע קריא בסגנון git: איזה כלים רצו במקביל, אילו תת-סוכנים התפצלו, איפה זה קפא, והוצאות מה. -- **תפס רגרסיות איכות באופן אוטומטי.** חבר שירות דירוג קטן וה-Failproof AI Observability ידרג כל הרצה מסיימת, כך שירידה בשימושיות או עלייה בהזיות תופיע בעצמה. -- **מצא כשלים שלא כתבת כלל עבורם.** ביקורות חוזרות חופרות בתיעודים שלך בחסות סשנים לאשכולות שגיאות, חריגי זמן תגובה, ניקוד נמוך והרצות תקועות, ואז מעניקות לך ממצאים מדורגים ומבוססי ראיות. -- **קבל עמוד כשזה משנה.** כללי סף כן על שיעור שגיאה, זמן תגובה, עלות או ניקוד מעריך ופתח תקלות שאתה יכול להשתמע, להקצות ולפתור. -- **שאל שאלות באנגלית רגילה.** עוזר בינה מלאכותית בתוך הדוח משיב על האם איכות עוברת מגמה בייצור השבוע? על הנתונים שלך. כל שינוי שהיא עושה כפוף לאישור. -- **שמור על הנתונים שלך.** Failproof AI Observability מאורחסן בעצמך: אירועים, הנושאים והניתוחים נשארים בתשתית שאתה שולט בה. +- **ראה מה הסוכן שלך בעצם עשה.** כל הרצה הופכת לגרף ביצוע קריא בסגנון git: אילו כלים רצו במקביל, אילו תת-סוכנים הסתעפו, היכן הוא הציע, ומה הוא הוציא. +- **תפוס נסיגות באיכות באופן אוטומטי.** חבר שירות ניקוד קטן ו-Failproof AI Observability תדרג כל הרצה שהסתיימה, כך שירידה בעזרות או שיא בהזיות יופיע מעצמו. +- **מצא כשלים שלא כתבת עבורם כלל.** ביקורות חוזרות כורות את היומנים שלך על פני הפעלות לקבוצות שגיאה, חריגי חביון, ניקוד נמוך והרצות תקועות, ואז משימות לך ממצאים מדורגים ומגובים בראיות. +- **קבל דף כשחשוב.** כללי סף יורים על שיעור שגיאה, חביון, עלות, או ניקוד מעריך ופתחו תקריות שאתה יכול להודות, להקצות ולפתור. +- **שאל שאלות באנגלית רגילה.** עוזר AI בדשבורד עונה על "איך איכות מתחזקת בייצור השבוע הזה?" על הנתונים שלך. כל שינוי שהוא עושה מעבר דרך אישור. +- **שמור על הנתונים שלך.** Failproof AI Observability מתצורה עצמית: אירועים, הנושאים והניתוחים נשארים בתשתית שאתה שולט בה. --- ## מה אתה מקבל -Failproof AI Observability מארגנה סביב שלוש רעיונות (**צפייה**, **ניתוח** ו**ניהול**), משתקפת בסרגל הצד השמאלי של הדוח. +Failproof AI Observability מאורגנת סביב שלוש רעיונות (**observe**, **analyze**, ו-**admin**), מוקרנים בסרגל הצד השמאלי של הדשבורד. -**צפייה** (האמת הגולמית של מה שקרה): +**Observe** (האמת הגולמית של מה קרה): -- **[ספר אירועים](/he/agenteye/event-stream)**: שביל חי לכל שלב של כל הרצה (קריאות כלים, קריאות מודל, קשרים, שגיאות). -- **[סשנים](/he/agenteye/sessions)**: אירועים אלה מצטברים לשורה אחת לכל הרצה, כל אחד מוכן להיות מדורג, עם גרף ביצוע בסגנון git. -- **[מטרי ביצוע](/he/agenteye/telemetry)**: מפות חום זמן תגובה לכל משטח וחיוני p50/p95/p99 עבור מודלים, כלים וקשרים, כך שקוצץ זנב בולט מהחציון. -- **[עקבוב שגיאות](/he/agenteye/error-tracking)**: משטח טריאז אחד לכל מה שהשתבש, קליק אחד מהתראה שנורתה. +- **[Event stream](/he/agenteye/event-stream)**: שביל חי, לכל שלב של כל הרצה (קריאות כלי, קריאות מודל, hooks, שגיאות). +- **[Sessions](/he/agenteye/sessions)**: אירועים אלה גולגלו לשורה אחת לכל הרצה, כל אחד מוכן להדרגה, עם גרף ביצוע בסגנון git. +- **[Performance metrics](/he/agenteye/telemetry)**: מפות חום חביון לכל משטח ו-p50/p95/p99 חיוניות עבור מודלים, כלים וקטעים, כך ששיא זנב בולט מהחציון. +- **[Error tracking](/he/agenteye/error-tracking)**: משטח טריאז אחד לכל מה שהשתבש, קליק אחד מהתראה שנורה. -![עמוד כלים של צפייה: מפת חום זמן תגובה, פס אחוז ובר התפלגות כלים על 24 פחי זמן](/agenteye/images/tools.png) +![עמוד כלים של Failproof AI Observability: מפת חום חביון, רצועת אחוזון וסרגל חלוקת כלים על פני 24 תאים זמן](/agenteye/images/tools.png) -*כל משטח צפייה משלב קו ניצנים וחיוני p50/p95/p99 עם מפת חום זמן תגובה ופס אחוז. מוצג כאן: כלים.* +*כל משטח observe משדר קו נוזל וחיוניות p50/p95/p99 עם מפת חום חביון ורצועת אחוזון. מוצג כאן: כלים.* -**ניתוח** (הפוך פעילות לתשובות): +**Analyze** (הפוך פעילות לתשובות): -- **[שאילתות](/he/agenteye/queries)** ו**[דוחות בקרים](/he/agenteye/dashboards)**: SQL שנשמר על אירועים והערכות שלך, תורשמו לדוחות בקרים משותפים בהיקף ארגוני. -- **[הערכות](/he/agenteye/evaluations)**: ניקוד איכות שמופקים משירות המעריך שלך, עם נימוק לכל ניקוד. -- **[ביקורות](/he/agenteye/audits)**: חקירות חוזרות המפיקות דפוסי כשל בחסות סשנים. -- **[התראות](/he/agenteye/alerts)** ו**[תקלות](/he/agenteye/incidents)**: כללי סף שעמודים לך, בתוספת זרימת עבודה תקלה לטריאז שלהם. +- **[Queries](/he/agenteye/queries)** ו-**[dashboards](/he/agenteye/dashboards)**: SQL שמור על האירועים וההערכות שלך, משורטט לדשבורדים משותפים בהיקף ארגוני. +- **[Evaluations](/he/agenteye/evaluations)**: ניקוד איכות שנוצר על ידי שירות ההערכה שלך, עם נימוק לכל ניקוד. +- **[Audits](/he/agenteye/audits)**: חקירות חוזרות שחושפות דפוסי כשל על פני הפעלות. +- **[Alerts](/he/agenteye/alerts)** ו-**[incidents](/he/agenteye/incidents)**: כללי סף שמעבירים אותך, בתוספת זרימת עבודה לתקריות לטריאז בהן. -**ממשקים** (הגע לנתונים שלך בדרכך שלך): +**Interfaces** (הגע לנתונים שלך בדרכך): -- **[CLI](/he/agenteye/cli-and-agents)**: נהג בכל ההטמעה שלך מהטרמינל או סקריפט, והתן לסוכן קוד לעשות את זה עבורך באנגלית רגילה. -- **[עוזר בינה מלאכותית](/he/agenteye/assistant)**: שאל שאלות על הסוכנים שלך באנגלית רגילה, ממש בתוך הדוח. -- **REST API**: הכל שהדוח והקלי עושים מגובה על ידי REST API שאתה יכול להתקשר אליו ישירות עם [מפתח API](/he/agenteye/api-keys) בהיקף - ספוג אירועים, שאל סשנים והערכות, וניהל דוחות בקרים, התראות, ביקורות, משתמשים ומפתחות, כך שאתה יכול לחווט את Failproof AI Observability לתוך הכלים שלך. +- **[CLI](/he/agenteye/cli-and-agents)**: נהל את כל הפריסה שלך מהטרמינל או סקריפט, והנח לסוכן קידוד לעשות זאת עבורך באנגלית רגילה. +- **[AI assistant](/he/agenteye/assistant)**: שאל שאלות על הסוכנים שלך באנגלית רגילה, ממש בתוך הדשבורד. +- **REST API**: הכל שהדשבורד וה-CLI עושים מגובה על ידי REST API שאתה יכול לקרוא ישירות עם [API key](/he/agenteye/api-keys) בהיקף — ספוג אירועים, שאילתות הפעלות והערכות, וקבל דשבורדים, התראות, ביקורות, משתמשים ומפתחות, כך שתוכל לחוט את Failproof AI Observability לתוך הכלים שלך. -**ניהול** (הפעל את זה בשביל הצוות שלך): +**Admin** (הריצו אותו לצוות שלכם): -- **[מפתחות API](/he/agenteye/api-keys)**: אסימונים בהיקף עבור הלקט, הדוח והעוזר. -- **משתמשים**: כניסה ללא סיסמה מבוססת דוא"ל עם רשימת הרשאה. -- **הגדרות**: תצורה לכל ארגון, כולל דריסות חלון הקשר של מודל. +- **[API keys](/he/agenteye/api-keys)**: אסימונים בהיקף עבור מגבי, הדשבורד והעוזר. +- **Users**: כניסה ללא סיסמה מבוססת אימייל עם רשימת היתר. +- **Settings**: תצורה לכל ארגון, כולל עקיפות חלון הקשר של מודל. --- -## כיצד החלקים מתאימים +## איך החלקים מתאימים -הנתונים זורמים בכיוון אחד, מקוד הסוכן שלך לדוח: הסוכן שלך (דרך Python SDK) משדר אירועים ל-agenteye-collector, שמשלח אותם לשרת, שמגיש את הדוח. שני שירותים אופציונליים משלימים את זה — שירות דירוג (הערכות) ושירות עוזר בינה מלאכותית (הצ'אט בתוך הדוח). +הנתונים זורמים בכיוון אחד, מקוד הסוכן שלך לדשבורד: הסוכן שלך (דרך Python SDK) פולט אירועים ל-agenteye-collector, שמספק אותם לשרת, שמשרת את הדשבורד. שתי שירותים אופציונליים משלימים את זה — שירות ניקוד (הערכות) ושירות עוזר AI (הצ'אט בדשבורד). -- **Python SDK**: אתה מוסיף כמה קריאות `agenteye.event.*` לסוכן שלך; אירועים מתחזקים באופן מקומי. -- **agenteye-collector**: שדמון קל משקל בכל מכונת סוכן שאורגנה אירועים ומשלח אותם לשרת. -- **שרת**: ספוג אירועים שלך, מעכל מצב תפעולי בתוך מסדי הנתונים שלך, משגר את REST API שהדוח, ה-CLI וההטמעות שלך משתמשות בהן. -- **דוח**: איפה אתה חוקר הכל. -- **שירותים אופציונליים**: שירות דירוג (הערכות), ושירות עוזר בינה מלאכותית (הצ'אט בתוך הדוח). +- **Python SDK**: אתה מוסיף כמה קריאות `agenteye.event.*` לסוכן שלך; אירועים מוחסנים בחסינה. +- **agenteye-collector**: דיימון קל משקל על כל מכונת סוכן שמקבץ אירועים ומספק אותם לשרת. +- **Server**: ספוג אירועים שלך, שומר מצב תפעול בבסיסי הנתונים שלך, משרת את REST API שהדשבורד, CLI וההטמעות שלך משתמשות בהן. +- **Dashboard**: כאן אתה חוקר את הכל. +- **Optional services**: שירות ניקוד (הערכות), ושירות עוזר AI (הצ'אט בדשבורד). -עבור אוצר המילים בשימוש לאורך הדוקים (*אירוע, סשן, הערכה, ביקורת, ממצא, תקלה*), ראה [קונספטים](/he/agenteye/concepts). +לגבי אוצר המילים המשמש בכל התיעוד (*event, session, evaluation, audit, finding, incident*), ראה [Concepts](/he/agenteye/concepts). --- -## קבלת Failproof AI Observability +## קבל את Failproof AI Observability -Failproof AI Observability היא מוצר ארגוני מ-Failproof AI, והיא פועלת לצד Failproof AI Enforcement — המוצר של מדיניות ומגן — תחת המותג Failproof AI. היא פועלת כליל בסביבה שלך. אם אין לך גישה לחבילות עדיין, בקש הדגמה ואנחנו נקבע אותך: שלח דוא"ל ל-[nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Failproof AI Observability הוא מוצר enterprise מ-Failproof AI, והוא עובד לצד Failproof AI Enforcement — המוצר של מדיניות והגנות — תחת הברנד Failproof AI. הוא פועל לחלוטין בסביבה שלך. אם אין לך גישה לחבילות עדיין, בקש הדגמה ואנחנו נסדר אותך: שלח אימייל ל-[nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- -## הצעדים הבאים +## שלבים הבאים -- [קונספטים](/he/agenteye/concepts): Failproof AI Observability אוצר מילים במקום אחד. -- [צפייה](/he/agenteye/observability): עקוב מה הסוכנים שלך עושים, הרצה אחר הרצה. -- [אבטחה](/he/agenteye/security): כיצד Failproof AI Observability שומר על הנתונים שלך מבודדים ובשליטתך. \ No newline at end of file +- [Concepts](/he/agenteye/concepts): אוצר Failproof AI Observability במקום אחד. +- [Observability](/he/agenteye/observability): עקוב אחר מה שהסוכנים שלך עושים, הרצה אחר הרצה. +- [Security](/he/agenteye/security): איך Failproof AI Observability שומרת על הנתונים שלך מבודדים ובשליטתך. \ No newline at end of file diff --git a/docs/he/agenteye/python-sdk-skill.mdx b/docs/he/agenteye/python-sdk-skill.mdx index 52732c36..5d7235e2 100644 --- a/docs/he/agenteye/python-sdk-skill.mdx +++ b/docs/he/agenteye/python-sdk-skill.mdx @@ -1,77 +1,77 @@ --- --- title: "Failproof AI Observability Python SDK Agent Skill" -description: "מעבר מסוכן שלא מכיל instrumentationליוצרי אירועים שבהם אתה יכול לראות, כאשר סוכן הקידוד שלך מוצא את נקודות ה-instrumentation, כותב אותן, ומוכיח שהן הגיעו." +description: "מעבר מסוכן לא מחוזק לאירועים שתוכל לראות, כאשר הסוכן הקודי שלך מוצא את נקודות הקצי, כותב אותן ומוכיח שהן נחתו." --- -אמור לסוכן הקידוד שלך *"הוסף Failproof AI Observability לסוכן זה"* וברשתך לקרוא את הלולאה שלך, להבין לאן ה-instrumentation צריך להישתייך, לכתוב אותו, ולאמת את האירועים לפני שהוא משלים את העבודה. +ספר לסוכן הקודי שלך *"add Failproof AI Observability to this agent"* והניח לו לקרוא את הלולאה שלך, להבין היכן צריכה להיות הקצי, לכתוב אותה ולאמת את האירועים לפני שהוא מוגמר בעבודה. -ה-**Python SDK skill** (`agenteye-python-sdk`) הוא *Agent Skill*: תיקייה של הוראות שסוכן קידוד כמו Claude Code או Codex טוען לפי דרישה כאשר משימה תואמת אותו. הוא מלמד את הסוכן להשתמש ב-[Python SDK](/he/agenteye/python-sdk) — זה לא ספרייה, והוא לא משנה שום דבר בדרך שה-SDK פועלת. +ה**Python SDK skill** (`agenteye-python-sdk`) היא *Agent Skill*: תיקייה של הוראות שסוכן קודי כמו Claude Code או Codex טוען לפי הצורך כאשר משימה מתאימה לה. היא מלמדת את הסוכן להשתמש ב[Python SDK](/he/agenteye/python-sdk) — זה לא ספרייה, וזה לא משנה כלום באופן שה-SDK פועל. -## Instrumentation קל לכתיבה וקל להשגיאה בשקט +## קצי קל לכתיבה וקל להשיג בשקט בצורה שגויה -ה-SDK קטן: שלוש עשרה שיטות אירועים, כולן keyword-only. סוכן קידוד יכול לקרוא את ה-[Python SDK](/he/agenteye/python-sdk) reference וליצור instrumentation סביר בדקה. +ה-SDK קטן: שלוש עשרה שיטות אירוע, הכל דרך מילים-קלידו. סוכן קודי יכול לקרוא את ה[Python SDK](/he/agenteye/python-sdk) reference ולהייצר קצי סביר בדקה. -הבעיה היא שה-SDK הזה לא זורק כשאתה טועה, וinstrumentation שגוי נראה בדיוק כמו instrumentation נכון עד שמישהו פותח דאשבורד ומוצא שהוא ריק. הטעויות שעולות בזמן אמיתי הן כולן שתיקות: +הקלסה היא שה-SDK הזה לא מעלה כאשר אתה טועה, וקצי שגוי נראה בדיוק כמו קצי נכון עד שמישהו פותח דשבורד ומוצא אותו ריק. הטעויות שעולות זמן אמיתי הן כל הדממות: | הטעות | מה אתה רואה | |---|---| -| No `agent_start` | כל אירוע מגיע. אפס sessions. | -| Environment לא הוגדר | הכל עובד, מוגדר תחת `dev`. | -| `outcome="failure"` | הריצה מוצגת בירוק — רק `failed`, `error`, `timeout`, `rejected` נחשבים. | -| שם שדה עם typo | מקובל ומאוחסן כשדה חדש. | -| אירועים נפלטים מ-thread pool | מושמטים בשקט. | +| אין `agent_start` | כל אירוע נוחת. אפס הפעלות. | +| סביבה לא הוגדרה | הכל עובד, מופקד תחת `dev`. | +| `outcome="failure"` | ההרצה מופיעה ירוקה — רק `failed`, `error`, `timeout`, `rejected` נספרים. | +| שם שדה עם שגיאת הקלדה | מקובל ומאוחסן כשדה חדש. | +| אירועים שנפלטו מבריכת חוטים | שקט נשמט. | -אחד מאלה לא זורק. אחד לא מופיע בבדיקות. כל אחד בטוב בskill, המוצהר כחוזה עם הבדיקה שתופסת אותה. +אף אחד מאלה לא מעלה. אף אחד לא מופיע בבדיקות. כל אחד נמצא בכישור, מצוין כהסכם עם הבדיקה שתופסת אותו. -## מה הוא עושה, לפי הסדר +## מה זה עושה, לפי הסדר -ה-skill מריץ אותם שלושה שלבים שמהנדס זהיר היה עושה: +הכישור מריץ את אותן שלוש שלבים שמהנדס זהיר הוא: -1. **Plan.** הוא קורא את לולאת הסוכן שלך ושואל שתי שאלות שרק אתה יכול לענות: מה נחשב לריצה אחת (`session_id` שלך), ומיהם השחקנים הבחינים (`agent_id` שלך). הוא מקבל את ההסכמה לפני כתיבת קוד, כי שינוי אותם מאוחר יותר חותך את ההיסטוריה שלך ושובר את התמיהות. -2. **Write.** הוא קושר זהות פעם אחת לכל ריצה ולא מעבירה דרך כל אתר קריאה, והוא בוחר צורה בטוחה לחוזקות — פרט שחשוב, כי הדרך המקוצרת הברורה מערבבת בשקט שתי ריצות חופפות לסשן אחד. -3. **Verify.** הוא מריץ את הסוכן שלך וקורא את קבצי האירועים שנוצרו, בודק ש-`agent_start` קיים, הסביבה נכונה, וריצה אחת הפיקה סשן אחד. +1. **תוכנית.** הוא קורא את לולאת הסוכן שלך ושואל את שתי השאלות שרק אתה יכול לענות: מה נחשב להרצה אחת (שלך `session_id`), ומי השחקנים הניתנים להבחנה (שלך `agent_id`). הוא מקבל את אלה בהסכם לפני כתיבת קוד, כי שינוי שלהם מאוחר יותר מפצל את ההיסטוריה שלך ושובר את המגמות. +2. **כתוב.** הוא קושר זהות פעם אחת לכל הרצה במקום להעביר אותה דרך כל אתר קריאה, והוא בוחר בצורה בטוחה לתיאום — פרט שחשוב, כי הקיצור הברור בשקט מערבב שתי הרצות חופפות להפעלה אחת. +3. **אמת.** הוא מריץ את הסוכן שלך וקורא את קבצי האירועים שהתקבלו, בודק כי `agent_start` קיים, הסביבה נכונה, והרצה אחת ייצרה הפעלה אחת. -השלב השלישי הוא אותו שאנשים מדלגים. ה-SDK כותב אירועים לקבצים מקומיים, כך שintegration שלם יכול להיות מוכח על נייד ללא שרת, ללא API key, וללא רשת — שזה בדיוק למה ה-skill מнастаיває על עשיית זה. +השלב השלישי הוא זה שאנשים דילגים עליו. ה-SDK כותב אירועים לקבצים מקומיים, כך שאינטגרציה מלאה יכולה להיות מוכחת על נייד עם אין שרת, אין מפתח API, ואין רשת — שהוא בדיוק למה הכישור מעדיף לעשות זאת. -## איך זה קשור לטכנולוגיות האחרות +## איך זה קשור לכישורים האחרים -שלוש skills, חלוקה נקייה אחת: +שלוש כישורים, ישיבה נקייה אחת: -| Skill | הגע אליו כאשר | מה זה נוגע | +| כישור | הגע לזה כשאתה | מה זה משפיע | |---|---|---| -| **Python SDK skill** (דף זה) | אתה רוצה שהסוכן שלך *יפלוט* telemetry — "הוסף observability", "למה הסוכן שלי לא מופיע?" | כותב קוד במאגר הסוכן שלך. לא קורא שום דבר. | -| **[Evaluator skill](/he/agenteye/evaluator-skill)** | אתה רוצה *לדרוג* ריצות — "מה כבר צריך למדוד?" | כותב קוד במאגר שלך; קורא telemetry | -| **[CLI skill](/he/agenteye/cli-skill)** | אתה רוצה *לקרוא* מה קרה, או להפעיל את ה-deployment שלך | מנהל את ה-CLI כמוך, כולל שינויים | +| **Python SDK skill** (דף זה) | אתה רוצה את הסוכן שלך *לפלוט* טלמטריה — "add observability", "למה הסוכן שלי לא מופיע?" | כותב קוד במרכז של הסוכן שלך. לא קורא כלום. | +| **[Evaluator skill](/he/agenteye/evaluator-skill)** | אתה רוצה *לדירוג* הרצות — "מה אנחנו אפילו צריכים למדוד?" | כותב קוד במרכז שלך; קורא טלמטריה | +| **[CLI skill](/he/agenteye/cli-skill)** | אתה רוצה *לקרוא* מה קרה, או להפעיל את ההפצה שלך | מניע את ה-CLI בתור אתה, כולל שינויים | -הם עוברים בסדר הזה: skill זה מקבל אירועים לזרימה, המדרג מדרג אותם, ה-CLI קורא אותם חזרה. אין שום דבר להערכה ואין שום דבר לקרוא עד שהסוכן שלך פולט sessions, כך שאם אתה מתחיל מ scratch, התחל כאן. +הם הופכים לפי סדר זה: כישור זה מקבל אירועים זורמים, המעריך מדרגם, ה-CLI קורא אותם חזרה. אין כלום להעריך ואין כלום לקרוא עד שהסוכן שלך ייפלוט הפעלות, כך שאם אתה מתחיל מאפס, התחל כאן. -## דרישות מקדימות +## דרישות מוקדמות -1. **Python 3.10+** ובסיס הקוד של הסוכן שאתה רוצה לעבודת את המכשיר. -2. **ה-SDK.** הוא מופץ ללקוחות כ wheel פרטי ולא מאינדקס ציבורי — ה-onboarding שלך מכסה כיצד להשיג אותו ולהתקין אותו. ה-skill יודע את נתיב ההתקנה ויבקש ממך במקום לנחש אם הוא לא יכול למצוא אותו. -3. **כום דבר אחר.** אין כניסה לדאשבורד, אין API key, אין רשת. ה-skill מאמת לעומת קבצי האירועים שה-SDK כותב, כך שהוא יכול לסיים ולהוכיח את עבודתו offline. +1. **Python 3.10+** וקודקוד הסוכן שאתה רוצה לקדם. +2. **ה-SDK.** הוא מופץ ללקוחות כחיד פרטי ולא מאינדקס ציבורי — הקודים שלך מכסה איך להשיג זאת ולהתקין זאת. הכישור יודע את שביל ההתקנה וישאל אותך במקום להניח אם הוא לא יכול למצוא אותו. +3. **כלום אחר.** אין כניסה לדשבורד, אין מפתח API, אין רשת. הכישור מאמת כנגד קבצי האירועים ש-SDK כותב, כך שהוא יכול לסיים ולהוכיח את עבודתו במצב לא מקוון. -## איפה להשיגו +## היכן להשיג אותו -ה-skill גר בקולקציה ציבורית [`FailproofAI/skills`](https://github.com/FailproofAI/skills): +הכישור חי בקולקציית [`FailproofAI/skills`](https://github.com/FailproofAI/skills) ציבורית: ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -הוסף `-g` להתקנתו לכל פרויקט במקום רק זה הנוכחי, ו-`--copy` אם הסביבה שלך לא עוקבת אחר symlinks. עבור Codex, העבור `-a codex`. +הוסף `-g` כדי להתקין אותו לכל פרויקט במקום רק לזה הנוכחי, ו`--copy` אם הסביבה שלך לא עוקבת אחר סימלינק. עבור Codex, עבור `-a codex`. -## התקנתו ביד +## התקנה ידית -Agent Skills הן תיקיות המכילות `SKILL.md` בתוספת הפניות. אם אתה מעדיף לא להשתמש בהתקנה: +Agent Skills הן תיקיות המכילות `SKILL.md` פלוס הפניות. אם אתה מעדיף לא להשתמש בהתקנה: -- **Claude Code**: העתק את תיקיית `agenteye-python-sdk/` ל-`~/.claude/skills/` (כל פרויקט) או `/.claude/skills/` (רק המאגר הזה). Claude Code מגלה אותה באופן אוטומטי — בדוק את רשימת `/skills`, או פשוט שאל משהו שמתאים אליה. -- **Codex**: Codex קורא את אותו `SKILL.md`. ה-`agents/openai.yaml` המלווה מגדיר `allow_implicit_invocation: true`, כך שהוא נבחר אוטומטי כאשר משימה תואמת; אחרת קרא אליו כ-`$agenteye-python-sdk`. +- **Claude Code**: העתק את תיקיית `agenteye-python-sdk/` לתוך `~/.claude/skills/` (כל פרויקט) או `/.claude/skills/` (רק המרכז הזה). Claude Code מגלה זאת באופן אוטומטי — בדוק את רשימת `/skills`, או פשוט שאל משהו שמתאים לזה. +- **Codex**: Codex קורא את אותו `SKILL.md`. ה`agents/openai.yaml` המוטבע קובע `allow_implicit_invocation: true`, אז הוא נבחר באופן אוטומטי כאשר משימה מתאימה; אחרת זימן אותו כ`$agenteye-python-sdk`. -הפעל את הסוכן שלך **במאגר המחזיק את הקוד שאתה רוצה לעבודת את המכשיר** — ה-skill קורא את לולאת הסוכן שלך לפני שהוא מציע משהו. +הפעל את הסוכן שלך **במרכז המחזיק את הקוד שאתה רוצה להקדם** — הכישור קורא את לולאת הסוכן שלך לפני שהוא מציע כלום. -## איך session נראה +## איך הפעלה נראית ```text you ▸ Add Failproof AI Observability to this agent. @@ -104,29 +104,29 @@ agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and Want me to fix those too? ``` -הדפוס להבחנה: הוא קרא את הקוד לפני הצעה, שאל רק את השאלות שאתה יכול לענות, שימש שנית ID שכבר היה לך, בחר את הצורה הבטוחה לחוזקות *כי* ראה thread pool, ו**אימת על ידי קריאת האירועים בפועל** במקום הצהרה על הצלחה — ואז דגל במקום היחיד בו ידע שיכול להיכשל בשקט. +ההדפס שיש להשים לב: הוא קרא את הקוד לפני שהציע, שאל רק את השאלות שאתה יכול לענות, השתמש בתעודה שכבר היתה לך, בחר בצורה בטוחה לתיאום *כי* ראה בריכת חוטים, ו**אמת על ידי קריאת האירועים בפועל** במקום הצהרת הצלחה — ואז סימן את המקום היחיד שידע שייכשל בשקט. ## מה אתה יכול לבקש ממנו -- *"Why isn't my agent showing up on the dashboard?"* → הולך בסולם: אם אירועים נכתבים, אם `agent_start` שם, אם הסביבה נכונה, אם הקלט קורא באותו מקום. -- *"Everything's landing under dev."* → הסביבה לא הוגדרה, או אופסה על ידי קריאה מאוחרת יותר. -- *"Add token tracking."* → מוצא את עטיפת ה-LLM שלך ורושם modularizer, stop reason, ו-usage. -- *"Instrument the sub-agents too."* → סשן אחד, תוויות סוכן ברורות, קן תחת הורם. -- *"Write tests for the instrumentation."* → מפנה את ה-SDK לתיקייה זמנית וטוען על האירועים שהוא כתב. +- *"למה הסוכן שלי לא מופיע בדשבורד?"* → הולך בסולם: האם אירועים נכתבים, האם `agent_start` שם, האם הסביבה נכונה, האם הקולטף קורא לאותו מקום. +- *"הכל נוחת תחת dev."* → הסביבה לא הוגדרה זה עתה, או הוגדרה מחדש על ידי קריאה מאוחרת יותר. +- *"הוסף עקיבה אחר אסימונים."* → מוצא את עטיפת ה-LLM שלך ורושם מודל, סיבת עצירה וזימון. +- *"אגול את תת-הסוכנים גם."* → הפעלה אחת, תוויות סוכן מובחנות, מקוננות תחת ההורה שלהם. +- *"כתוב בדיקות לקצי."* → מצביע ה-SDK בתיקייה זמנית ואישר על האירועים שהוא כתב. -## מה להביט +## מה להשגיח -**תן לו לאמת.** השלב שהופך את ה-skill הזה שווה להשתמש בו הוא האחרון — הפעלת הסוכן שלך וקריאת האירועים חזרה. סוכן שכותב instrumentation ועוצר עשה את החצי הקל, וחצי זה נכשל בשקט הוא השני. +**תן לזה לאמת.** השלב שעושה את הכישור הזה שווה להשתמש בו הוא האחרון — הרצת הסוכן שלך וקריאת האירועים חזרה. סוכן שכותב קצי והופך עשה את החצי הקל, והחצי שנכשל בשקט הוא השני. -**הסכימו על השמות לפני הקוד.** `session_id` ו-`agent_id` הם הצירים שכל משטח קובץ לפי. שינוי שם להם מאוחר יותר חותך את ההיסטוריה: ריצות ישנות שמרו התוויות הישנות והתמיהות שלך שובקות. ה-skill ישאל; התשובה שווה דקה של מחשבה. +**הסכם על השמות לפני הקוד.** `session_id` ו`agent_id` הם הצירים שכל משטח קבוצות על ידי. שינוי שמות מאוחר יותר מפצל את ההיסטוריה: הרצות ישנות שמור הקודם תוויות והמגמות שלך שובר. הכישור ישאל; התשובה שווה דקה של מחשבה. -**אם הסוכן שלך מציע התקנת ה-SDK מאינדקס ציבורי, ה-skill לא טען.** ה-SDK מופץ באופן פרטי. ההצעה הזו היא סימן אמין שסוכן הקידוד שלך מנחש במקום לעקוב אחר ה-skill — עצור אותו שם ובדוק אם ה-skill מותקן. +**אם הסוכן שלך מציע התקנת ה-SDK מאינדקס ציבורי, הכישור לא טעון.** ה-SDK מופץ בפרטיות. הצעה זו היא ספר אמין שהסוכן הקודי שלך מנחש במקום לפעול לפי הכישור — עצור את זה שם ובדוק שהכישור מותקן. -מעבר לכך, רדיוס הנפץ שלו קטן: הוא כותב קוד בספריית העבודה שלך וקבצי אירועים שבהם אתה אומר לו. הוא לא קורא שום דבר מה-deployment שלך ולא משנה שום דבר בעולם. +מעבר לזה, רדיוס הפיצוץ שלו קטן: הוא כותב קוד בתיקיית העבודה שלך וקבצי אירועים איפה שאתה אומר לו. הוא לא קורא כלום מההפצה שלך ולא משנה כלום בה. -## שלבים הבאים +## צעדים הבאים -- **[Python SDK](/he/agenteye/python-sdk)**: ה-event reference השלם — כל סוג אירוע ושדה — מאחורי מה ה-skill הזה אוטומטי. -- **[Sessions](/he/agenteye/sessions)**: מה ה-instrumentation שלך מייצר כאשר אירועים מגיעים. -- **[Evaluator Agent Skill](/he/agenteye/evaluator-skill)**: השלב הבא כאשר ריצות מגיעות — ניקודן. -- **[CLI Agent Skill](/he/agenteye/cli-skill)**: קריאת ה-telemetry שלך חזרה. \ No newline at end of file +- **[Python SDK](/he/agenteye/python-sdk)**: ההפניה המלאה של האירוע — כל סוג אירוע ושדה — מאחורי מה שהכישור הזה אוטומציה. +- **[Sessions](/he/agenteye/sessions)**: מה הקצי שלך מייצר ברגע שאירועים נוחתים. +- **[Evaluator Agent Skill](/he/agenteye/evaluator-skill)**: השלב הבא ברגע שהרצות נוחתות — דירוגן. +- **[CLI Agent Skill](/he/agenteye/cli-skill)**: קריאת הטלמטריה שלך חזרה. \ No newline at end of file diff --git a/docs/he/agenteye/python-sdk.mdx b/docs/he/agenteye/python-sdk.mdx index 1ef405c8..738d5b12 100644 --- a/docs/he/agenteye/python-sdk.mdx +++ b/docs/he/agenteye/python-sdk.mdx @@ -1,14 +1,15 @@ --- +--- title: "Python SDK" -description: "ראה בדיוק מה עשו הסוכנים AI שלך בייצור: כל הרצת סוכן, קריאת כלי, בקשת מודל, hook והתערבות אנוש." +description: "ראו בדיוק מה שהסוכנים החכמים שלכם עשו בפרודקשן: כל הרצת סוכן, קריאת כלי, בקשת מודל, hook, והתערבות אנושית." --- -ראה בדיוק מה עשו הסוכנים AI שלך בייצור: כל הרצת סוכן, קריאת כלי, בקשת מודל, hook והתערבות אנוש. ה-SDK של Failproof AI Observability Python מתעד את השביל הזה מתוך קוד הסוכן שלך כדי שתוכל לתקן, לתקן באופן הולם ולהעריך מה קרה. השתמש בו בכל פעם שתרצה ש-Failproof AI Observability תצפה בסוכנים שלך. +ראו בדיוק מה שהסוכנים החכמים שלכם עשו בפרודקשן: כל הרצת סוכן, קריאת כלי, בקשת מודל, hook, והתערבות אנושית. ה-Failproof AI Observability Python SDK מתעד את השביל הזה מתוך קוד הסוכן שלכם כדי שתוכלו לבצע ניפוי באגים, בדיקת ביקורת, והערכה של מה שקרה. השתמשו בו בכל עת שתרצו ש-Failproof AI Observability יעקוב אחרי הסוכנים שלכם. -מתחת להנהלה, ה-SDK כותב אירועים מובנים לקבצי JSONL מקומיים, וה-daemon של הקלט אוסף אותם ומשלח אותם לפלטפורמה באופן אוטומטי. אתה לא מנהל את הקבצים הללו בעצמך. +בבסיס הדברים, ה-SDK כותב אירועים מובנים לקבצי JSONL מקומיים, וה-collector daemon אוסף אותם ושולח אותם לפלטפורמה באופן אוטומטי. אתם לא מנהלים את הקבצים הללו בעצמכם. -> **Tip:** חדש ל-Failproof AI Observability? דף זה הוא ההפניה המלאה של אירועי SDK. +> **טיפ:** חדשים ב-Failproof AI Observability? דף זה הוא ההפניה המלאה של אירועי ה-SDK.
@@ -18,15 +19,15 @@ description: "ראה בדיוק מה עשו הסוכנים AI שלך בייצו ## התקנה -ה-SDK מופץ ללקוחות כ-wheel פרטי ולא מאינדקס חבילה ציבורי. ה-onboarding שלך מכסה כיצד להשיג אותו, להתקין אותו ולהצמיד אותו — דבר עם אנשר הקשר שלך ב-Failproof AI אם אתה צריך גישה. +ה-SDK מופץ ללקוחות כ-wheel פרטי ולא מאינדקס חבילות ציבורי. ההטמעה שלכם מכסה כיצד להשיג אותו, להתקין אותו, וליצור גרסה קבועה — דברו עם איש הקשר של Failproof AI שלכם אם אתם צריכים גישה. -לאחר ההתקנה, אשר שיש לך אותו: +לאחר התקנתו, אשרו שיש לכם אותו: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -מעדיף להניח לסוכן קידוד לבצע את כל השילוב? [Python SDK Agent Skill](/he/agenteye/python-sdk-skill) מכיר את נתיב ההתקנה, מתכנן את נקודות הכלים, כותב אותן ומאמת שהאירועים מגיעים. +מעדיפים לתת לסוכן קידוד לבצע את כל ההטמעה? [Python SDK Agent Skill](/he/agenteye/python-sdk-skill) יודע את נתיב ההתקנה, מתכננן את נקודות ההצבת מכשול, כותב אותן, ומאמת שהאירועים מגיעים. --- @@ -58,9 +59,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### הקנת קריאה אמיתית +### הטמעה של קריאה אמיתית -בפועל אתה עוטף את קוד הסוכן הקיים שלך. קוצץ קריאת מודל עם `model_request` לפני ו-`model_response` אחרי, כך ששני האירועים משתרעים על הבקשה האמיתית ו-Failproof AI Observability יכולה לעשות זוג עם אותם: +בפועל אתם עוטפים את קוד הסוכן הקיים שלכם. שמרו קריאת מודל עם `model_request` לפני ו-`model_response` אחרי, כדי ששני האירועים יעטפו את הבקשה האמיתית וה-Failproof AI Observability יוכל להתאים אותם: ```python import anthropic @@ -95,11 +96,11 @@ agenteye.event.model_response( ) ``` -עטוף קריאות כלים באותו אופן עם `tool_use` ו-`tool_result`, בשימוש חוזר ב-`tool_call_id` אחד על פני הזוג. +עטפו קריאות כלים באותה דרך עם `tool_use` ו-`tool_result`, תוך שימוש חוזר באותו `tool_call_id` על פני הזוג. -הנה איך נראים אירועים אלה לאחר שהם מגיעים לדashboard, מיוחסים בצבעים לפי סוג וניתנים לסינון לפי סביבה, סוכן וסשן: +הנה כיצד אירועים אלו נראים לאחר שהם מגיעים לדוח הבקרה, מקודדים בצבע לפי סוג וניתן לסננן לפי סביבה, סוכן, וסשן: -![זרם האירועים החי, מקודד בצבעים לפי סוג אירוע וניתן לסינון לפי סביבה, סוכן וסשן](/agenteye/images/events-stream.png) +![זרם האירועים הלייב, מקודד בצבע לפי סוג אירוע וניתן לסננן לפי סביבה, סוכן, וסשן](/agenteye/images/events-stream.png) --- @@ -113,18 +114,18 @@ agenteye.configure( ) ``` -התקשר פעם אחת לפני כל קריאה ל-`event.*`. בטוח להשמיט; ברירות המחדל עובדות מתוך הקופסה. כל הטיעונים הם מילת-מפתח בלבד; העביר אותם לפי שם כפי שמוצג לעיל. +קראו פעם אחת לפני כל קריאה `event.*`. בטוח להשמיט; ברירות המחדל עובדות מיד. כל הארגומנטים הם מילה-מפתח בלבד; העבירו אותם לפי שם כפי שמוצג לעיל. -כאשר `base_dir` הוא `None` (ברירת המחדל), ה-SDK קורא ל-`$AGENTEYE_HOME` אם הוא מוגדר, -אחרת חוזר אל `~/.agenteye`. זה תואם את הרזולוציה שלעצמו של הקלט, -כך שמשתנה `AGENTEYE_HOME` env יחיד מגדיר את הסימון האירוע המשותף עבור שניהם -ה-SDK והקלט. +כאשר `base_dir` הוא `None` (ברירת המחדל), ה-SDK קורא את `$AGENTEYE_HOME` אם הוא מוגדר, +אחרת הוא חוזר ל-`~/.agenteye`. זה תואם את הרזולוציה של ה-collector שלו, +כך שמשתנה `AGENTEYE_HOME` סביבה יחיד מגדיר את ה-spool המשותף לאירועים עבור שניהם +ה-SDK וה-collector. --- ## סביבה -תייג כל אירוע עם סביבת פריסה (`production`, `staging`, `qa`, `canary` וכו'). הגדר אותו פעם אחת; ה-SDK מצרף אותו לכל אירוע באופן אוטומטי. +תייגו כל אירוע עם סביבת פריסה (`production`, `staging`, `qa`, `canary`, וכו'). הגדרו אותו פעם אחת; ה-SDK מצרף אותו לכל אירוע באופן אוטומטי. **אפשרות 1: דרך `configure()`:** @@ -138,42 +139,42 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**עדיפות:** `configure(environment=...)` מנצח על משתנה סביבה. אם אף אחד לא מוגדר, ברירות למחדל `"dev"`. +**עדיפות:** `configure(environment=...)` מנצח על משתנה הסביבה. אם אף אחד מהם לא מוגדר, ברירת המחדל היא `"dev"`. -ערך הסביבה מופיע כמסנן בפועל ראשון בדashboard ומאוחסן בשרת לשאילתות מהירות. +ערך הסביבה מופיע כמסנן מהשורה הראשונה בדוח הבקרה ומאוחסן בשרת לשאילתות מהירות. -> **Warning:** ערכי סביבה לא חייבים להכיל פסיק `,` מילולי. מסנני הדashboard משתמשים בבחירה מרובה המפוצלת בפסיק בחוט (`?environment=prod,staging`), כך שסביבה בשם `prod,blue` תחלק לשני ערכים. אירועים עם סביבות המכילות פסיקים דחויים בזמן הגילום. +> **אזהרה:** ערכי סביבה חייבים שלא להכיל פסיק `,` מילולי. מסננים דוח הבקרה משתמשים בבחירה מרובה מופרדת בפסיקים על החוט (`?environment=prod,staging`), כך שסביבה בשם `prod,blue` תחולק לשני ערכים. אירועים עם סביבות המכילות פסיקים נדחים בזמן ספיגה. --- -## נתונים ופרטיות +## נתונים וגופניות -ה-SDK רושם רק את השדות שאתה מעביר באופן מפורש. Prompts, הודעות, כניסות כלים ופלטים, ותוכן מודל נתפסים רק משום שאתה מעביר אותם לקריאת `event.*`. שום דבר לא נקרא מהתהליך שלך או תפוס באופן מרומז. כל שדה שאתה משאיר לא מוגדר מושמט מהאירוע כולו; זה לא כתוב לדיסק. +ה-SDK מתעד רק את השדות שאתם מעבירים במפורש. ערכי Prompts, הודעות, קלטי כלים וקלטי פלטים, ותוכן מודל נתפסים רק כי אתם מעבירים אותם לקריאת `event.*`. שום דבר לא נקרא מהתהליך שלכם או נתפס באופן מגוחך. כל שדה שאתם משאירים ללא הגדרה מושמט מהאירוע לחלוטין; הוא לא כתוב לדיסק. -זה הופך את הריגול לבחירה שלך ולאחריות שלך. אם prompt או payload כלי מכיל PII או סודות שיותר טוב לא לאחסן, היסר או החסם אותו לפני שאתה מעביר אותו לשיטת האירוע. +זה הופך את הגדלת לא-גלויה לבחירה שלכם ולאחריות שלכם. אם prompt או payload כלי מכיל PII או סודות שתעדיפו לא לאחסן, הסירו או כסו אותם לפני שאתם מעבירים אותם לשיטת האירוע. --- -## הפניה אירוע +## ההפניה לאירוע -רוב האירועים מגיעים בצמדי התחלה/סיום השותפים מזהה קורלציה: `tool_use` ו-`tool_result` חולקים `tool_call_id`, `hook_triggered` ו-`hook_completed` חולקים `hook_id`, ו-`human_wait` ו-`human_input` חולקים `input_id`. פתוח את אירוע ההתחלה, בצע את העבודה, ואז פתוח את אירוע הסיום עם אותו מזהה. Failproof AI Observability תאם את הזוג ותחשב `duration_ms` עבורך, כך שאתה לא מעביר `duration_ms` בעצמך. +רוב האירועים מגיעים בזוגות התחלה/סיום החולקים מזהה קורלציה: `tool_use` ו-`tool_result` חולקים `tool_call_id`, `hook_triggered` ו-`hook_completed` חולקים `hook_id`, ו-`human_wait` ו-`human_input` חולקים `input_id`. שלחו את אירוע ההתחלה, בצעו את העבודה, ואז שלחו את אירוע הסיום עם אותו מזהה. Failproof AI Observability מתאימה את הזוג ומחשבת את `duration_ms` בשבילכם, כך שלעולם לא תעבירו את `duration_ms` בעצמכם. -![גרף ביצוע בסגנון git של סשן לצד ציר הזמן של האירוע שלו, שנבנה מחדש מהאירועים המזוווגים, עם פירוק כלי/מודל/חטיף](/agenteye/images/session-detail.png) +![גרף הרצה בסגנון git של סשן לצד ציר הזמן של האירוע שלו, שנבנה מחדש מהאירועים המזווגים, עם פירוק הכלים/מודל/hook](/agenteye/images/session-detail.png) -כל שיטות אירוע דורשות שני שדות אלה: +כל שיטות האירוע דורשות את שני השדות הבאים: | שדה | סוג | תיאור | |---|---|---| | `session_id` | `str` | מזהה את הרצת הסוכן ברמה העליונה | -| `agent_id` | `str` | מזהה איזה סוכן בתוך הסשן פתח את האירוע | +| `agent_id` | `str` | מזהה איזה סוכן בתוך הסשן פלט את האירוע | -כל שיטה גם מקבלת `**kwargs` שרירותי עבור מטא-נתונים מותאמים אישית (ראה [שדות מותאמים אישית](#custom-fields)). +כל השיטות מקבלות גם `**kwargs` שרירותי למטא-נתונים מותאמים אישית (ראו [שדות מותאמים אישית](#custom-fields)). --- ### `event.agent_start()` -פתוח כאשר סוכן מתחיל לעבוד. +נפלט כאשר סוכן מתחיל עבודה. ```python agenteye.event.agent_start( @@ -188,7 +189,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -פתוח כאשר סוכן מסיים לעבוד. +נפלט כאשר סוכן מסיים עבודה. ```python agenteye.event.agent_end( @@ -203,7 +204,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -פתוח כאשר סוכן קורא לכלי. זוג עם `tool_result`; ה-SDK מחשב אוטומטית `duration_ms`. +נפלט כאשר סוכן קורא לכלי. התאימו עם `tool_result`; ה-SDK מחשב אוטומטית את `duration_ms`. ```python agenteye.event.tool_use( @@ -219,7 +220,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -פתוח כאשר כלי חוזר. מתעדכנות עם `tool_use` דרך `tool_call_id`. +נפלט כאשר כלי חוזר. מתואם עם `tool_use` דרך `tool_call_id`. ```python agenteye.event.tool_result( @@ -237,7 +238,7 @@ agenteye.event.tool_result( ### `event.model_request()` -פתוח רק לפני שליחת prompt ל-LLM. +נפלט רגע לפני שליחת prompt ל-LLM. ```python agenteye.event.model_request( @@ -254,13 +255,13 @@ agenteye.event.model_request( ) ``` -ערכי `messages` מקבלים או `content` מחרוזת פשוטה או ברשימה בסגנון Anthropic של בלוקים. פרמטרים דגימה (`temperature`, `max_tokens` וכו') יכולים להיות מועברים כ-kwargs נוסף. +ערכי `messages` מקבלים או `content` מחרוזת רגילה או Anthropic-style list-of-blocks `content`. ניתן להעביר פרמטרי דגימה (`temperature`, `max_tokens`, וכו') כ-kwargs נוסף. --- ### `event.model_response()` -פתוח כאשר ה-LLM חוזר תשובה. +נפלט כאשר ה-LLM מחזיר תגובה. ```python agenteye.event.model_response( @@ -277,13 +278,13 @@ agenteye.event.model_response( ) ``` -`content` מקבל או מחרוזת פשוטה (ספקי גנריים) או ברשימה של בלוקי תוכן בסגנון Anthropic. קריאות כלים חיות בתוך `content` כבלוקים `{"type": "tool_use", ...}`, ללא שדה `tool_calls` נפרד. +`content` מקבל או מחרוזת רגילה (ספקים גנריים) או רשימה של Anthropic-style content blocks. קריאות כלים חיות בתוך `content` כ-`{"type": "tool_use", ...}` blocks, ללא שדה `tool_calls` נפרד. --- ### `event.hook_triggered()` -פתוח כאשר hook יורה. זוג עם `hook_completed`; ה-SDK מחשב אוטומטית `duration_ms`. +נפלט כאשר hook שורה. התאימו עם `hook_completed`; ה-SDK מחשב אוטומטית את `duration_ms`. ```python agenteye.event.hook_triggered( @@ -300,7 +301,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -פתוח כאשר hook מסיים. מתעדכנות עם `hook_triggered` דרך `hook_id`. +נפלט כאשר hook מסיים. מתואם עם `hook_triggered` דרך `hook_id`. ```python agenteye.event.hook_completed( @@ -319,7 +320,7 @@ agenteye.event.hook_completed( ### `event.error()` -פתוח כאשר שגיאה לא מטופלת מתרחשת. +נפלט כאשר שגיאה ללא טיפול מתרחשת. ```python agenteye.event.error( @@ -333,13 +334,13 @@ agenteye.event.error( --- -## אירועי Human-in-the-Loop +## אירועי אדם בלולאה -אירועי human-in-the-loop נותנים לך פיקוח על הרגעים בהם אדם צעד לביצוע של הסוכן (המתנה לאישור, מתן קלט, השהייה או עצירת הסוכן). הם מאפשרים לך למדוד כמה זמן לוקח לבנים לענות (ה-SDK מחשב אוטומטית `duration_ms` על האירועים המזוווגים), לתקן ולראות מי השהה או הפריע לסוכן, וליצור זרימות אישור ופיקוח המופיעות בדashboard. +אירועי אדם בלולאה נותנים לכם פיקוח על הרגעים בהם אדם צועד לתוך הביצוע של הסוכן (המתנה לאישור, הספקת קלט, השהיה, או עצירת הסוכן). הם מאפשרים לכם למדוד כמה זמן לוקח לאנשים להגיב (ה-SDK מחשב אוטומטית את `duration_ms` על האירועים המזווגים), בדיקת ביקורת מי השהה או הפריע לסוכן, ובנייה של זרימות אישור ופיקוח שמופיעות בדוח הבקרה. ### `event.human_wait()` -פתוח כאשר הסוכן עוצר ביצוע להמתין לאדם לספק קלט. זוג עם `human_input`; ה-SDK מחשב אוטומטית `duration_ms` (כמה זמן לקח לאדם לענות). +נפלט כאשר סוכן מעצור הרצה כדי להמתין לאדם להספיק קלט. התאימו עם `human_input`; ה-SDK מחשב אוטומטית את `duration_ms` (כמה זמן לקח לאדם להגיב). ```python agenteye.event.human_wait( @@ -354,7 +355,7 @@ agenteye.event.human_wait( ### `event.human_input()` -פתוח כאשר אדם מספק קלט והסוכן מתחדש. מתעדכנות עם `human_wait` דרך `input_id`. `duration_ms` מחושב אוטומטית ולא חייב להיות מועבר על ידי הקורא. +נפלט כאשר אדם מספק קלט וה-סוכן חוזר. מתואם עם `human_wait` דרך `input_id`. `duration_ms` מחושב אוטומטית ולא חייב להיות מועבר על ידי הקורא. ```python agenteye.event.human_input( @@ -368,7 +369,7 @@ agenteye.event.human_input( ### `event.human_pause()` -פתוח כאשר אדם באופן פעיל משהה את הסוכן (למשל דרך בקרת דashboard). הסוכן מושהה אך לא מסיים. +נפלט כאשר אדם משהה באופן פעיל את הסוכן (למשל דרך שליטת דוח בקרה). הסוכן מושהה אך לא מסתיים. ```python agenteye.event.human_pause( @@ -381,7 +382,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -פתוח כאשר אדם באופן פעיל עוצר את הסוכן באמצע ביצוע. בניגוד ל-`human_pause`, עבודת הסוכן מסתיימת במקום להיות מושהה. +נפלט כאשר אדם עוצר באופן פעיל את הסוכן בתוך הביצוע. בניגוד ל-`human_pause`, עבודת הסוכן מסתיימת ולא משהה. ```python agenteye.event.human_interrupt( @@ -397,7 +398,7 @@ agenteye.event.human_interrupt( ## שדות מותאמים אישית -כל טיעונים מילת מפתח נוסף מצורפים לאירוע לאחר השדות הסטנדרטיים: +כל ארגומנטי מילה-מפתח נוסף מתווספים לאירוע לאחר השדות הסטנדרטיים: ```python agenteye.event.tool_use( @@ -410,27 +411,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` ו-`environment` שמורים ויוראו `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) אם מועברים כשדות מותאמים אישית. `session_id` ו-`agent_id` הם פרמטרים נדרשים בכל שיטת אירוע ולא ניתן לספק אותם בפעם השנייה; Python מעלה `TypeError` אם אתה עושה. הגדר את הסביבה עם `configure(environment=...)` (או משתנה `AGENTEYE_ENVIRONMENT`) במקום. +`timestamp`, `type`, ו-`environment` שמורים ומעלים `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) אם מועברים כשדות מותאמים אישית. `session_id` ו-`agent_id` הם פרמטרים נדרשים בכל שיטת אירוע ולא ניתן לספק אותם שנית; Python מעלה `TypeError` אם אתם עושים זאת. הגדרו את הסביבה עם `configure(environment=...)` (או המשתנה `AGENTEYE_ENVIRONMENT`) במקום. -שמור על עומסים מובנים JSON כאשר אתה רוצה להשאול את השדות שלהם. ערכים שה-JSON אינו תומך בהם ברורות — כגון datetimes, UUIDs, עשרוניות, קבוצות, בתים או אובייקטי מודל — מומרים למחרוזות כדי שההקלטה תמשיך בבטחה. +שמרו payloads כ-JSON מובנה כאשר אתם רוצים לשאול את שדותיהם. ערכים שה-JSON לא תומך בהם ללידה—כגון datetimes, UUIDs, decimals, sets, bytes, או model objects—מומרים לחוטים כדי ההקלטה תמשיך בבטחה. --- ## כיצד אירועים נכתבים -אירועים חוזרים בתוך תהליך ועטופים לדיסק כל `flush_interval` שניות (ברירת מחדל 500 מ"ש). כל ההנחה כותבת קובץ JSONL אחד: +אירועים מוגדרים כ-buffer בתוך תהליך ומשטפלים לדיסק כל `flush_interval` שניות (ברירת המחדל 500 ms). כל flush כותב קובץ JSONL אחד: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -הקלט צופה בספרייה זו ומעלה קבצים באופן אוטומטי. אתה לא צריך לנהל קבצים אלה ישירות. +ה-collector צופה בתיקייה זו ומעלה קבצים באופן אוטומטי. אתם לא צריכים לנהל את הקבצים הללו ישירות. -כל קובץ נכתב בצורה אטומית: ה-SDK כותב לקובץ זמני ואז שם אותו במקום, כך שהקלט לעולם לא רואה קובץ כתוב חצי. שטיפה סופית גם פעם כאשר התהליך שלך יוצא, כך אירועים מחוזרים במרווח האחרון אינם אבודים. אם הקלט אוff-line, אירועים פשוט נצברים כקבצים בדיסק וספינה ברגע שזה חוזר. +כל קובץ נכתב באופן אטומי: ה-SDK כותב לקובץ זמני ואז שינויו למקום, כדי שה-collector לעולם לא יראה קובץ חצי-כתוב. flush סופי גם עובר כאשר התהליך שלכם יוצא, כך שאירועים מוגדרים כ-buffer בInterval האחרון לא אבדו. אם ה-collector לא מחובר, אירועים פשוט מצטברים כקבצים בדיסק ונשלחים ברגע שהוא חוזר. --- -## שלבים הבאים +## השלבים הבאים -- [Event stream](/he/agenteye/event-stream): צפה באירועים אלה מגיעים בחיים, מיוחסים בצבעים וניתנים לסינון לפי סביבה, סוכן וסשן. -- [Sessions](/he/agenteye/sessions): ראה כיצד האירועים המזוווגים משחזרים כל הרצת סוכן כגרף ביצוע וציר זמן. \ No newline at end of file +- [אירוע stream](/he/agenteye/event-stream): צפו באירועים אלו מגיעים בחיים, מקודדים בצבע וניתן לסננן לפי סביבה, סוכן, וסשן. +- [סשנים](/he/agenteye/sessions): ראו כיצד האירועים המזווגים שנבנו מחדש כל הרצת סוכן כגרף הרצה וציר זמן. \ No newline at end of file diff --git a/docs/he/agenteye/queries.mdx b/docs/he/agenteye/queries.mdx index fd852322..bb5a6909 100644 --- a/docs/he/agenteye/queries.mdx +++ b/docs/he/agenteye/queries.mdx @@ -1,56 +1,56 @@ --- title: "שאילתות" -description: "שאל כל שאלה על נתוני הסוכן שלך וקבל תשובה תוך שניות." +description: "שאל כל שאלה על נתוני הסוכן שלך וקבל תשובה בשניות." --- -שאל כל שאלה על נתוני הסוכן שלך וקבל תשובה תוך שניות. Failproof AI Observability מספק לך ספרייה של שאילתות שמורות וגמורות לשימוש על האירועים וההערכות שלך, כך שתוכל להתחיל מדוגמה עובדת במקום מעורך SQL ריק. +שאל כל שאלה על נתוני הסוכן שלך וקבל תשובה בשניות. Failproof AI Observability נותן לך ספריית שאילתות שמורות וערוכות להפעלה מיידית על האירועים וההערכות שלך, כך שאתה מתחיל מדוגמה שעובדת במקום עורך SQL ריק. -![ספרית השאילתות השמורות: רשת של שאילתות בנות שימוש חוזר, גם הפריסטים המובנים וגם אלה שכוללים משלך](/agenteye/images/queries.png) +![ספריית השאילתות השמורות: רשת של שאילתות הניתנות לשימוש חוזר, גם קביעות מוגדרות מראש וגם אלו מותאמות אישית](/agenteye/images/queries.png) -*ספרית השאילתות השמורות שלך ב-`//queries`: פריסטים מובנים לצד השאילתות שהצוות שלך שמר ושימ.* +*ספריית השאילתות השמורות שלך ב-`//queries`: קביעות מוגדרות מראש לצד השאילתות שהצוות שלך שמר.* -## התחל מפריסט, לא מעמוד ריק +## התחל מקביעה מוגדרת מראש, לא מעמוד ריק -אתה לא צריך לזכור שמות טבלאות או לכתוב SQL מאפס. הספרייה נפתחת עם פריסטים מובנים לשאלות שהצוותים שואלים הכי הרבה, יושבים ממש לצד השאילתות שהצוות שלך שמר ושימ. בחר באחת שקרובה למה שאתה רוצה ואתה כבר בדרך לתשובה. +אתה לא צריך לזכור שמות טבלאות או לכתוב SQL מאפס. הספריה נפתחת עם קביעות מוגדרות מראש לשאלות שהצוותים שואלים הכי הרבה, יושבות ממש לצד השאילתות שהצוות שלך שמר ושיימנו. בחר אחת שקרובה למה שאתה רוצה ואתה כמעט באמצע הדרך לתשובה. -כל שאילתה שמורה היא בהיקף ארגון ומשותפת, כך שהשאילתות השימושיות שהחברים שלך כותבים הן גם שלך. תן שם לשאילתה, תן לה תיאור פעם אחת, וכל אחד בארגון שלך יכול למצוא אותה, להריץ אותה, או להצמיד את התוצאות שלה לדשבורד מאוחר יותר. +כל שאילתה שמורה היא ברמת הארגון ומשותפת, כך שהיעילות שהקולגות שלך כותבים הופכות להיות שלך גם כן. שמור שם לשאילתה וכתוב תיאור פעם אחת, וכל אחד בארגון שלך יכול למצוא אותה, להריץ אותה, או לצמד את התוצאות שלה לדשבורד מאוחר יותר. -מצא זאת ב-`//queries`. +מצא את זה ב-`//queries`. -## התאם אותה והרץ אותה בספר ההרכב SQL +## התאם אותה והרץ אותה בקומפוזר ה-SQL -פתח כל שאילתה והיא תנחת בספר ההרכב SQL, שם אתה יכול להתאים אותה ולראות את התשובה מיד: ללא ייצוא, ללא הליך הלוך וחזור, ללא המתנה למישהו אחר. +פתח כל שאילתה והיא תנחת בקומפוזר ה-SQL, שם אתה יכול להתאים אותה ולראות את התשובה מיד: ללא ייצוא, ללא טיול הלוך ושוב, ללא המתנה למישהו אחר. -![ספר ההרכב של שאילתות SQL מריץ שאילתה שמורה, עם סרגל בחצי טוב ורשת תוצאות חי](/agenteye/images/query-lab.png) +![קומפוזר שאילתות SQL המריץ שאילתה שמורה, עם סרגל סכימה וגריד תוצאות חי](/agenteye/images/query-lab.png) -*ספר ההרכב של SQL: השאילתה שלך משמאל, סרגל בחצי טוב כדי שלעולם לא תנחש שם עמודה, ורשת תוצאות חי מתחת.* +*קומפוזר ה-SQL: השאילתה שלך בצד שמאל, סרגל סכימה כדי שלא תניח בעד שם עמודה, וגריד תוצאות חי מתחת.* -- **סרגל סכמה** פורש את טבלאות האנליטיקה וההעמודות שלהן, כך שאתה יכול ליצור שאילתה ללא ציד שמות שדות. -- **רשת תוצאות חי** מחזירה שורות ברגע שאתה מריץ, כך שאתה חוזר על עצמך בשניות במקום לנחש ולנחש מחדש. -- **קריאה בלבד בעיצוב.** שאילתות פועלות כנגד חנות האירועים שלך ומאומתות בשרת: רק משפטי `SELECT` ו-`WITH` מותרים, עם timeout של הצהרה וכובלת שורות. שאילתה חקרנית לעולם לא יכולה לשנות את הנתונים שלך, ואחת שרקדה מקבלת עצירה בשבילך. +- **סרגל סכימה** מפרט את טבלאות הניתוח וההעמודות שלהן, כך שאתה יכול לעצב שאילתה ללא ציד לשמות שדות. +- **גריד תוצאות חי** מחזיר שורות ברגע שהרצת, כך שאתה חוזר על עצמך בשניות במקום להנחש ולהנחש שוב. +- **קריאה בלבד בעיצוב.** שאילתות רצות כנגד אחסן האירועים שלך ומאומתות על השרת: רק הצהרות `SELECT` ו-`WITH` מותרות, עם timeout הצהרה וגבול שורה. שאילתה חקרנית לא יכולה לעולם לשנות את הנתונים שלך, ואחת that runaway מעוצרת בשבילך. -שמח בתוצאה? שמור אותה בחזרה לספרייה כדי שכל הצוות יורש אותה, או צמיד את הפלט שלה לדשבורד כאריח קו, בר, אזור או עוגה. +מרוצה מהתוצאה? שמור אותה חזרה לספריה כך שכל הצוות תורש אותה, או צמד את התפוקה שלה לדשבורד כאריח קו, עמודה, אזור או עוגה. -## הרץ אותן מהטרמינל, או תן לעוזר לכתוב אותן +## הרץ אותן מהטרמינל, או תן לעוזר להיות זה שכותב אותן -אותן שאילתות שמורות עוקבות אחריך לכל מקום שבו אתה עובד: +השאילתות השמורות הזהות עוקבות אחריך לכל מקום שבו אתה עובד: -- **מהטרמינל.** ה-CLI של `agenteye` רוכזת, מריץ ושומרת אותן שאילתות, כך שאתה יכול להוריד תוצאה לסקריפט, לתאם אותה ל-CI, או להיפטר ממנה לסוכן קידוד. +- **מהטרמינל.** ה-CLI של `agenteye` מציע, מריץ ושומר את אותן שאילתות בדיוק, כך שאתה יכול לזרוק תוצאה לתוך סקריפט, לחוט אותה ל-CI, או למסור אותה לסוכן קוד. ```bash -agenteye query list # אותן שאילתות שמורות, מהטרמינל שלך -agenteye query run errs --arg prod # הרץ אחת והדפיס את השורות (הוסף --json כדי לצנור אותה) +agenteye query list # the same saved queries, from your terminal +agenteye query run errs --arg prod # run one and print the rows (add --json to pipe it) ``` - ראה [CLI וסוכנים](/he/agenteye/cli-and-agents) לסט הפקודה המלא. + ראה [CLI וסוכנים](/he/agenteye/cli-and-agents) לסט הפקודות המלא. -- **מהעוזר AI.** לא בטוח איך לנסח את SQL? שאל את [עוזר ה-AI](/he/agenteye/assistant) בתוך הדשבורד בעברית רגילה והוא יסיר את השאילתה וישמור אותה בספרייה שלך בשבילך. +- **מעוזר ה-AI.** לא בטוח איך לנסח את ה-SQL? שאל את [עוזר ה-AI](/he/agenteye/assistant) בתוך הדשבורד באנגלית פשוטה והוא יעצב את השאילתה ויחסוך אותה לספריה שלך בשבילך. -הרצת שאילתה שמורה מגובלת על ידי הרשאת `queries:run`, המופרדת מההרשאות ליצור או למחוק שאילתות, כך שאתה יכול להעניק גישת קריאה ללא רשות לכולם לכתוב מחדש את הספרייה. +הרצת שאילתה שמורה מוקיבה על ידי ההרשאה `queries:run`, נשמרה בנפרד מההרשאות ליצור או למחוק שאילתות, כך שאתה יכול להעניק גישת קריאה ללא לתן לכל אחד לכתוב מחדש את הספריה. ## קשור -- [Dashboards](/he/agenteye/dashboards): צמיד תוצאות שאילתה לתרשימים משותפים בהיקף ארגון. -- [עוזר AI](/he/agenteye/assistant): שאל שאלות בעברית רגילה וקבל שאילתה חזרה. +- [דשבורדים](/he/agenteye/dashboards): צמד תוצאות שאילתה לתרשימים משותפים וברמת הארגון. +- [עוזר AI](/he/agenteye/assistant): שאל שאלות באנגלית פשוטה וקבל חזרה שאילתה. - [CLI וסוכנים](/he/agenteye/cli-and-agents): הרץ ושמור את אותן שאילתות מהטרמינל שלך. \ No newline at end of file diff --git a/docs/he/agenteye/security.mdx b/docs/he/agenteye/security.mdx index dee38a73..05fbb27a 100644 --- a/docs/he/agenteye/security.mdx +++ b/docs/he/agenteye/security.mdx @@ -1,67 +1,68 @@ --- title: "אבטחה" -description: "Failproof AI Observability בנוי כך שיעמוד קרוב לאגנטים הייצור שלך, מה שאומר שהוא רואה את ההנמקות שלך, קלטי הכלים, והפלטים שלהם." +description: "Failproof AI Observability בנוי כדי להיות קרוב לאג'נטים הייצור שלך, כלומר הוא רואה את ההנמקות, קלטי הכלים, והפלטים שלך." --- -Failproof AI Observability בנוי כך שיעמוד קרוב לאגנטים הייצור שלך, מה שאומר שהוא רואה את ההנמקות שלך, קלטי הכלים, והפלטים שלהם. דף זה מסביר כיצד הוא משמר את הנתונים הללו בצורה מבודדת, מבוקרת, וברשותך. אם אתה בתהליך הערכה של Failproof AI Observability לסקירת אבטחה, התחל כאן. + +Failproof AI Observability בנוי כדי להיות קרוב לאג'נטים הייצור שלך, כלומר הוא רואה את ההנמקות, קלטי הכלים, והפלטים שלך. דף זה מסביר כיצד הוא שומר על הנתונים שלך מבודדים, מנוהלים, ובידיים שלך. אם אתה בוחן את Failproof AI Observability לביקורת אבטחה, התחל כאן. --- -## הנתונים שלך נשארים בסביבתך +## הנתונים שלך נשארים בסביבה שלך -Failproof AI Observability הוא self-hosted. אירועים, הנמקות, תגובות מודל, וניתוחים מאוחסנים בבסיסי הנתונים שלך, בסביבתך שלך. שום דבר לא נשלח ל-SaaS של צד שלישי לאחסון, והנתונים שלך נשארים בחשבון הענן שלך. +Failproof AI Observability הוא self-hosted. אירועים, הנמקות, תגובות מודל, וניתוחים מאוחסנים במסדי הנתונים שלך, בסביבה שלך. שום דבר לא נשלח ל-SaaS של צד שלישי לאחסון, והנתונים שלך נשארים בחשבון הענן שלך. --- -## בידוד דיירים +## בידול דיירים -מופע אחד של Failproof AI Observability יכול להנחות ארגונים רבים, וכל אחד מבודד בשכבת האחסון — מאופשר על ידי מסד הנתונים, לא רק על ידי ממשק המשתמש: +מופע Failproof AI Observability אחד יכול להוביל ארגונים רבים, וכל אחד מבודד ברמת האחסון — מוכפה על ידי המסד, לא רק על ידי ממשק המשתמש: -- הנתונים התפעוליים של ארגון (משתמשים, מפתחות, לוחות מחוונים, שאילתות שמורות) מוגבלים לארגון זה, וקריאות חוצות-ארגוניות חסומות על ידי מסד הנתונים עצמו. -- כל אירוע שנקלט מוקלד עם הארגון שבעליו, כך שאירועים של ארגון אחד לעולם לא יוכלו להיקרא על ידי ארגון אחר. +- הנתונים התפעוליים של ארגון (משתמשים, מפתחות, לוחות מחוונים, שאילתות שמורות) מצופים לארגון זה, וקריאות חוצות-ארגון חסומות על ידי המסד עצמו. +- כל אירוע שנקלט מסומן עם הארגון שלו, כך שאירועים של ארגון אחד לעולם לא יוכלו להיקרא על ידי ארגון אחר. -כל נתיב לוח מחוונים מוגבל תחת slug ארגוני (`//…`). +כל נתיב לוח מחוונים מצופה תחת slug ארגון (`//…`). --- -## כניסה למערכת +## כניסה -Failproof AI Observability משתמש בכניסה ללא ססמה, מבוססת דוא״ל. אין ססמה שאפשר לתפוס או לדלוף. משתמש מבקש קוד חד-פעמי (או קישור קסום של לחיצה אחת), שנשלח להם בדוא״ל ותוקפו פוקע במהירות. הכניסה מוגדרת על ידי **רשימת אישור**: רק כתובות דוא״ל (או דומיינים) שאתה מאשר יכולות להתחקות. +Failproof AI Observability משתמש בכניסה ללא סיסמה המבוססת על דוא"ל. אין סיסמה לדיוג או לדלף. משתמש מבקש קוד חד-פעמי (או קישור קסום לחיצה אחת), המשולח להם בדוא"ל וחשוב שיפוג במהירות. הכניסה מסוגרת על ידי **רשימת מותרים**: רק כתובות דוא"ל (או דומיינים) שאתה מאשר יכולים להתחייב. -![מסך הכניסה של Failproof AI Observability, המשדר קוד חד-פעמי לדוא״ל שלך](/agenteye/images/login.png) +![מסך הכניסה של Failproof AI Observability, השולח קוד בשימוש יחיד לדוא"ל שלך](/agenteye/images/login.png) --- -## גישה מוגבלת עם מפתחות API +## גישה בעלת ההיקף עם מפתחות API -כל לקוח מתחקה עם מפתח API שנושא הרשאות דקות, עם עקרון הפחות-הרשאות. קולקטור צריך רק `events:add`; מפתח לוח מחוונים או עוזר יכול להיות קריאה בלבד; פעולות הרסניות (מחיקה, יצירה מחדש) הן הנחות נפרדות שאתה בוחר להכליל. +כל לקוח משתמש בהצפנה עם מפתח API הנושא הרשאות דקות וברי-מזל. קלט צריך רק `events:add`; מפתח לוח מחוונים או עוזר יכול להיות קריאה בלבד; פעולות הרסניות (מחיקה, חידוש) הן הנחות נפרדות שאתה בוחר להכללה. -![דף מפתחות ה-API: הנחות ההרשאות של כל מפתח, בקודים צבע לפי היקף קריאה, כתיבה, והרסני](/agenteye/images/api-keys.png) +![דף מפתחות API: הנחות ההרשאה של כל מפתח, צבועות בצבע לפי טווח קריאה, כתיבה והרסני](/agenteye/images/api-keys.png) -שמור על מפתח bootstrap המנהל להגדרה, והנפק מפתחות צרים לכל השאר. ראה [מפתחות API](/he/agenteye/api-keys). +שמור את מפתח ה-bootstrap של מנהל עבור התקנה, והנפק מפתחות צרים לכל השאר. ראה [מפתחות API](/he/agenteye/api-keys). --- -## עוזר קריאה-בלבד, בשער אישור +## עוזר קריאה בלבד ומוגן בהסכמה -[העוזר בלוח המחוונים](/he/agenteye/assistant) משובץ מענה על שאלות על הנתונים שלך, אך הוא מוגבל בעיצוב: +העוזר [AI בלוח המחוונים](/he/agenteye/assistant) עונה על שאלות על הנתונים שלך, אך הוא מוגבל בעיצוב: -- הוא **קריאה-בלבד כברירת מחדל**: SQL שלו עובר דרך שומר שמותר רק `SELECT`/`WITH` שאילתות, הצהרה יחידה, עם מכסה שורות. -- כל דבר שהוא יוצר (שאילתה שמורה, לוח מחוונים) הוא **בשער אישור**: אתה סוקר ומאשר כל כתיבה לפני שזה קורה. -- הוא **לא יכול למחוק לעולם**. +- זה **קריאה בלבד כברירת מחדל**: ה-SQL שלו רץ דרך שומר המאפשר רק שאילתות `SELECT`/`WITH`, הצהרה יחידה, עם כובד שורה. +- כל מה שהוא יוצר (שאילתה שמורה, לוח מחוונים) הוא **מוגן בהסכמה**: אתה בוחן ומאשר כל כתיבה לפני שזה קורה. +- זה **לא יכול לעולם למחוק**. -אז חברה יכולה לשאול "אילו אגנטים השגיאו הכי הרבה השבוע?" ולפעול על פי התשובה, ללא שהעוזר יכול לשנות או להסיר את הנתונים שלך בעצמו. +אז חבר בצוות יכול לשאול "אילו אג'נטים שגו ביותר השבוע?" ולפעול על בסיס התשובה, בלי שהעוזר יוכל לשנות או להסיר את הנתונים שלך בעצמו. --- -## בדרך +## בתנועה -כל התעבורה עובדת על HTTPS. אתה מסיים TLS עם התעודות שלך, כך שתעבורת קולקטור-לשרת ודפדפן-לשרת מוצפנת בדרך. +כל התנועה רצה על HTTPS. אתה מסיים TLS עם הסרטיפיקטים שלך, כך שתנועה ממטבח לשרת ומדפדפן לשרת מוצפנת בתנועה. --- ## הצעדים הבאים -- [סקירה כללית](/he/agenteye/overview): כיצד Failproof AI Observability מתחברים ביחד. -- [מפתחות API](/he/agenteye/api-keys): הגבל גישה לקולקטור, לוח מחוונים, ועוזר. -- [Observability](/he/agenteye/observability): מה Failproof AI Observability לוקח מהאגנטים שלך. \ No newline at end of file +- [סקירה כללית](/he/agenteye/overview): איך Failproof AI Observability מצטרף יחד. +- [מפתחות API](/he/agenteye/api-keys): טווח גישה עבור הקלט, לוח המחוונים, והעוזר. +- [Observability](/he/agenteye/observability): מה Failproof AI Observability לוכד מהאג'נטים שלך. \ No newline at end of file diff --git a/docs/he/agenteye/sessions.mdx b/docs/he/agenteye/sessions.mdx index 086f62bc..0266efec 100644 --- a/docs/he/agenteye/sessions.mdx +++ b/docs/he/agenteye/sessions.mdx @@ -1,58 +1,57 @@ --- ---- -title: "Sessions & Execution Graph" -description: "כל event מ-run, מקופל לשורה אחת קריאה וממורה כגרף ביצוע בסגנון git שאתה יכול לקרוא בשניות." +title: "הפעלות וגרף ביצוע" +description: "כל אירוע מהרצה, מעוגל לשורה קריאה אחת ומשורטט כגרף ביצוע בסגנון git שאתה יכול לקרוא בשניות." --- -תוך כדי שאתה מנחש למה run נכשל. Failproof AI Observability מקפל כל event מ-run לשורה אחת קריאה, ואז מציירת את כל ה-run כתמונה בסגנון git שאתה יכול לקרוא בשניות, כך שאתה רואה בדיוק מה עשה ה-agent שלך, שלב אחר שלב. +הפסק לנחש למה הרצה נכשלה. Failproof AI Observability מעגל כל אירוע מהרצה לשורה קריאה אחת, ואז משרטט את כל ההרצה כתמונה בסגנון git שאתה יכול לקרוא בשניות, כדי שתראה בדיוק מה ה-agent עשה, צעד אחר צעד. -![רשימת ה-Sessions: שורה אחת לכל run, על פני environments ו-agents, עם status pills ו-evaluation score badges](/agenteye/images/sessions-list.png) +![רשימת ההפעלות: שורה אחת לכל הרצה, על פני סביבות ו-agents, עם pill-ים של סטטוס ו-badges של ניקוד הערכה](/agenteye/images/sessions-list.png) -*שורה אחת לכל run: ה-status pill אומר לך איך הסתיים ה-run במבט אחד, ותגי score רכובים לצד זה ברגע שמעריך מחובר.* +*שורה אחת לכל הרצה: ה-pill של הסטטוס אומר לך איך הרצה הסתיימה במבט חטוף, ו-badge של ניקוד מתלווה אחרי שמעריך מחובר.*
-*Agent tracing: עקוב אחרי run יחיד שלב אחר שלב, מיעד לכלים לתשובה סופית.* +*עקיבה אחר agent: עקוב אחרי הרצה יחידה צעד אחר צעד, מיעד לכלים לתשובה סופית.* --- -## ראה כל run במבט אחד +## ראה כל הרצה במבט חטוף -השביל event הגולמי הוא האמת של כל שלב, אבל כשיש לך אלפי צעדים על פני עשרות של runs, אתה צריך את ה-run, לא את השלב. דף ה-Sessions מקפל את כל ה-events של run לשורה אחת, כך שיום של פעילות הופך לרשימה סריקה במקום hosiery. +שביל האירועים הגולמי הוא האמת של כל צעד, אבל כשיש לך אלפי צעדים על פני עשרות הרצות, אתה צריך את ההרצה, לא את הצעד. עמוד ההפעלות מעגל את כל אירועי ההרצה לשורה אחת, כך שיום של פעילות הופך לרשימה סורקת במקום להצפה של מידע. -כל שורה נושאת status pill, כך ש-run כושל בולט מ-run בריא לפני שאתה לוחץ על דבר כלשהו. סנן לפי טווח תאריכים, environment, agent, או session כדי לעבור מ-"הכל" ל-"ה-run שחשוב לי" בכמה קליקים. +כל שורה נושאת pill סטטוס, כך שהרצה שנכשלה בולטת מאחת בריאה לפני שאתה לוחץ על כלום. סנן לפי טווח תאריכים, סביבה, agent, או הפעלה כדי לעבור מ"הכל" ל"ההרצה שחשובה לי" בכמה לחיצות. -ברגע שאתה מחבר מעריך, כל run שהושלם מקבל ניקוד אוטומטי והציון האחרון שלו מופיע בשורה כתג. אתה יכול לסנן לפי כל טווח ציונים, כך ש-"הצג לי כל run בעל ציון נמוך של prod השבוע הזה" הוא סנן, לא ביקורת ידנית. עד שתגדיר אחד, sessions עדיין תופס את כל ה-run; הוא פשוט לא נושא ניקוד עדיין. +לאחר חיבור מעריך, כל הרצה שהסתיימה מקבלת ניקוד אוטומטי והניקוד העדכני ביותר שלה מופיע בשורה כ-badge. אתה יכול לסנן לפי טווח ניקוד כלשהו, כך ש"הראה לי כל הרצה בציון נמוך בייצור השבוע הזה" היא סינון, לא בדיקה ידנית. עד שתקים אחד, הפעלות עדיין לוכדות את ההרצה המלאה; הן פשוט לא נושאות ניקוד עדיין. --- -## קרא את כל ה-run כתמונה +## קרא את כל ההרצה כתמונה -![גרף ביצוע בסגנון git של session לצד ציר הזמן של events שלו, עם פירוט של tool, model, ו-hook panel](/agenteye/images/session-detail.png) +![גרף ביצוע בסגנון git של הפעלה לצד ציר הזמן של האירועים שלה, עם לוח פירוט הכלים, המודל וה-hook](/agenteye/images/session-detail.png) -*גרף הביצוע (שמאל) יושב ליד ציר הזמן של events; ה-rail הימני מפרק את ה-tools, models, hooks, ו-token spend של ה-run.* +*גרף הביצוע (שמאל) ישב לצד ציר הזמן של האירועים; ה-rail הימני מפרק את הכלים, המודלים, ה-hooks וה-token spend עבור ההרצה.* -לחץ על כל session כדי לפתוח את גרף הביצוע שלו: תצוגה בסגנון git של איך agents, tools, hooks, ו-model calls התפתחו לאורך זמן. כל sub-agents במקביל מסתעפים לנתיב שלהם, כך שאתה יכול לראות איזה עבודה רצה זה לזה, איזה sub-agent עצר, ולאן ה-run הלך לא בכיוון, בלי להשמיע אותו שוב בראשך מקיר של logs. +לחץ על כל הפעלה כדי לפתוח את גרף הביצוע שלה: תצוגה בסגנון git של איך agents, כלים, hooks, וקריאות מודל התגלגלו לאורך זמן. כל sub-agent במקביל מתגדלים לנתיבה שלהם, כך שאתה יכול לראות איזה עבודה רץ זה לצד זה, איזה sub-agent עצר, ולאן ההרצה הלכה לכיוון שגוי, בלי להשמיע זאת מחדש בראשך מקיר של logs. -ה-rail הימני נותן לך את הפירוט per-run: אילו tools ו-models רצו, אילו hooks בעירו, ומה ה-run הוציא בתוקנים. זו התשובה ל-"למה ה-run הזה עלה כל כך הרבה?" או "איזה tool הוא ה-slow אחד?" יושבת ממש לצד הגרף שגרם לזה. +ה-rail הימני נותן לך את פירוט ההרצה: אילו כלים ומודלים רצו, אילו hooks נורו, ומה ההרצה הוציאה ב-tokens. זו התשובה ל"למה הרצה זו עלתה כל כך הרבה?" או "איזה כלי הוא האיטי?" יושב ממש לצד הגרף שגרם לזה. -Events בודדים ניתנים לפנייה, כך שאתה יכול לתת למישהו קישור לרגע אחד ולא "ה-session, בערך שתיים שלישים למטה". העתק את הקישור מכל event, או עקוב אחרי אחד מ-[audit](/he/agenteye/audits) finding או שגיאה, והוא session נפתח עם אותו event נבחר וגלול אליו. זה מתקיים גם עבור runs ארוך מאוד: ציר הזמן טוען חלון מוגבל למען הדפדפן שלך, וקישור שמצביע מעבר לחלון זה עדיין מוצא את ה-event שלו ולא משליך אותך לתחילה. אם ה-event התיישן מחלון ה-retention שלך, הדף אומר לך את זה במקום לבחור בשקט כלום. +אירועים בודדים ניתנים להתעדה, כך שאתה יכול להסתר למישהו קישור לרגע אחד במקום "ההפעלה, בערך שני שלישים למטה". העתק את הקישור מכל אירוע, או עקוב אחרי אחד ממציאת [ביקורת](/he/agenteye/audits) או שגיאה, וההפעלה נפתחת עם אותו אירוע שנבחר וגלול אליו. זה מחזיק להרצות ארוכות מאוד גם: ציר הזמן טוען חלון מוגבל למען הדפדפן שלך, וקישור המצביע על אותו חלון עדיין מוצא את האירוע שלו במקום להפיל אותך בהתחלה. אם האירוע התישן מחלון השמירה שלך, העמוד אומר לך את זה במקום לבחור בשקט בשום דבר. --- ## איפה למצוא את זה -כל דף dashboard מוגבל לארגון שלך (`//…`). Sessions חי תחת **Observe** בסרגל הצד השמאלי, ליד Events, עם טווח התאריכים, environment, agent, ו-session filters על פני החלק העליון של הרשימה. כל שורה היא קליק אחד מגרף הביצוע המלא שלה. +כל עמוד במDashboard מחודד לארגון שלך (`//…`). ההפעלות חיות תחת **Observe** בה-sidebar שמאלי, לצד Events, עם טווח התאריכים, הסביבה, ה-agent, וסינוני ההפעלה על פני החלק העליון של הרשימה. כל שורה היא לחיצה אחת מגרף הביצוע המלא שלה. -כדי להפעיל את תגי הציונים וסינון טווח ציונים, חבר מעריך: ראה [Evaluations](/he/agenteye/evaluations). +כדי להפעיל את ה-score badges וסינון טווח ניקוד, חבר מעריך: ראה [Evaluations](/he/agenteye/evaluations). --- ## קשור -- [Event stream](/he/agenteye/event-stream): השביל הגולמי, per-step כל session מקופל ממנו. -- [Evaluations](/he/agenteye/evaluations): חבר מעריך כך שכל run יקבל תג ציון שאתה יכול לסנן לפיו. -- [Telemetry](/he/agenteye/telemetry): איך runs מגיעים מ-agent שלך אל sessions אלה. \ No newline at end of file +- [Event stream](/he/agenteye/event-stream): שביל גולמי וחד-צעדי שכל הפעלה מעוגלת ממנו. +- [Evaluations](/he/agenteye/evaluations): חבר מעריך כך שכל הרצה תקבל badge ניקוד שאתה יכול לסנן לפיו. +- [Telemetry](/he/agenteye/telemetry): איך הרצות מקבלות מה-agent שלך לתוך הפעלות אלה. \ No newline at end of file diff --git a/docs/he/agenteye/telemetry.mdx b/docs/he/agenteye/telemetry.mdx index 071080c6..2c816711 100644 --- a/docs/he/agenteye/telemetry.mdx +++ b/docs/he/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- title: "מדדי ביצוע" -description: "ראה את הרגע בו המודלים, הכלים או ה-hooks מאטים או מרימים את החשבון, ותופסו עיכוב זנב לפני שהמשתמשים שלך ירגישו זאת." +description: "ראה את הרגע שבו המודלים, הכלים או ההוקים שלך מאטים או עולים בעלות, ותפס עלייה בזנב-זמן-תגובה לפני שהמשתמשים שלך אי פעם ירגישו בה." --- -ראה את הרגע בו המודלים, הכלים או ה-hooks מאטים או מרימים את החשבון, ותופסו עיכוב זנב לפני שהמשתמשים שלך ירגישו זאת. שלוש דפים ייעודיים הופכים תזמוני גולמיים ל-p50, p95, ו-p99 שתוכל לקרוא בחטף. +ראה את הרגע שבו המודלים, הכלים או ההוקים שלך מאטים או עולים בעלות, ותפס עלייה בזנב-זמן-תגובה לפני שהמשתמשים שלך אי פעם ירגישו בה. שלוש עמודים ייעודיים הופכים זמנים גולמיים ל-p50, p95 ו-p99 שאתה יכול לקרוא במבט אחד. -![דף Models המציג מפת חום של latency, קו אחוזון ומספרים לפי מודל של טוקנים, עלות וחלון context](/agenteye/images/models.png) -*דף Models: מפת חום של latency, קו אחוזון וטוקנים לפי מודל, עלות משוערת ומילוי חלון context.* +![עמוד Models המציג מפת חום של זמן-תגובה, רצועת אחוזונים ופרטים לכל מודל של אסימונים, עלות והקשר-חלון](/agenteye/images/models.png) +*עמוד Models: מפת חום של זמן-תגובה, רצועת אחוזונים, וספירת אסימונים לכל מודל, עלות משוערת ומילוי חלון ההקשר.* -## הפסק להתיר לממוצעים להסתיר את ההרצות הגרועות שלך +## הפסק להניח לממוצעים להסתיר את הריצות הגרועות ביותר שלך -מספר latency ממוצע הוא משכנע וחסר תועלת: הוא משטח על אותה קריאה אחת מחמישים שתלויה ומעוררת את ה-on-call שלך בשעתיים בלילה. דפי Models, Tools ו-Hooks מסרבים לעשות זאת. לכל אחד אותו צורה, כך שתלמד את זה פעם אחת: +מספר זמן-תגובה ממוצע הוא מנחם וחסר תועלת: הוא משטח על פני קריאה אחת מתוך חמישים שמתקעת וקוראת לכל-על בשעה 2 בבוקר. עמודי Models, Tools ו-Hooks מסרבים לעשות זאת. כל אחד חולק את אותה צורה, כדי שתלמד את זה פעם אחת: -- **sparkline בן 24 תאים** עבור הטרנד בחטף: האם זה הולך להחמיר? -- **פס חיויים** עם p50, p95, ו-p99 latency, כך שההרצה הטיפוסית והזנב יושבים זה ליד זה. -- **מפת חום של latency**, 24 תאי זמן לפי דלי latency, שמציגה *מתי* הקריאות האטות התקבצו. -- **קו אחוזון**: קו p50 עם סרטי צל p25 ל-p75 ו-p10 ל-p90 ונקודות p99, כך שההתפשטות נשארת גלויה במקום להיות ממוצעת. +- **ספרקליין בעל 24 תאים** לטרנד במבט אחד: האם זה הולך והופך לגרוע יותר? +- **רצועת חיוניים** עם זמן-תגובה p50, p95 ו-p99, כדי שהריצה הטיפוסית והזנב יושבו זה ליד זה. +- **מפת חום של זמן-תגובה**, 24 פחים בזמן לפי דלי זמן-תגובה, המציגה *מתי* הקריאות האיטיות התקבצו. +- **רצועת אחוזונים**: קו p50 עם סרטים מוצללים p25 עד p75 ו-p10 עד p90 ונקודות p99, כדי ששפיצות נראה במקום להיות ממוצע. -crosshair ריחוף משותף קושר את מפת החום והקו, כך שעיכוב זנב מיישר שורה בזמן על שניהם במקום להסתתר מאחורי שורת ממוצע אחת. מצא את כל שלוש הדפים בקטע **observe** של הלוח הבקרה שלך, כל אחד בהיקף הארגון שלך וניתן לסינון לפי טווח תאריכים, סביבה, agent וsession. +קו-ישר צף משותף מקשר את מפת החום ואת הרצועה, כדי שעלייה בזנב מתיישרת בזמן בשניהם במקום להסתתר מאחורי קו ממוצע יחיד. מצא את כל שלושת העמודים בחלק **observe** בדשבורד שלך, כל אחד במתחם של הארגון שלך וניתן לסינון לפי טווח תאריכים, סביבה, סוכן וסשן. ## Models: ראה בדיוק מה כל מודל עולה לך -דף Models (המוצג למעלה) עונה על שתי השאלות שכל חשבון מעלה: איזה מודל, וכמה. על גבי התצוגה latency המשותפת, הוא מוסיף **צריכת טוקנים לפי מודל**, **עלות משוערת** ו**מילוי חלון context**, כך שגדילה בלתי מבוקרת של prompt וcompaction קרוב יותר גלויים לפני שהם תופסים אותך בפתיעה. +עמוד Models (מוצג למעלה) משיב על שתי השאלות שהחשבון תמיד מעלה: איזה מודל וכמה. על גבי התצוגה משותפת של זמן-תגובה, היא מוסיפה **צריכת אסימונים לכל מודל**, **עלות משוערת** ו**מילוי חלון ההקשר**, כדי שצמיחה פרומפט בחסם וקיבוץ קרוב יהיו גלויים לפני שהם תופסים אתך בהפתעה. -Failproof AI Observability מזהה מזהי מודל נפוצים באופן אוטומטי. אם חלון נראה לא תקין, או שאתה מריץ מודל פרטי משלך, תקן אותו או הוסף אחד תחת **Settings**, ב**model context windows**, וקריאות המילוי עוקבות. +Failproof AI Observability מזהה מזהי מודל נפוצים באופן אוטומטי. אם חלון נראה לא נכון, או אתה מריץ מודל פרטי משלך, תקן אותו או הוסף אחד תחת **Settings**, ב**model context windows**, והקריאות של מילוי עוקבות. -## Tools: הבחן בין האיטי לשבור +## Tools: הבדל בין האיטי לשבור -קריאת tool יכולה להיות איטית, או שהיא יכולה להיכשל בשקט, ואתה רוצה לדעת איזה מהם בעוד שניות, לא אחרי שחפרת דרך יומנים. +קריאת כלים יכולה להיות איטית, או היא יכולה להיכשל בשקט, ואתה רוצה לדעת איזה אחד בשניות, לא אחרי שחופרת דרך יומנים. -![דף Tools המציג את מפת החום של latency המשותפת וקו האחוזון ליד פירוק הצלחה וכישלון וקו התפלגות כלי](/agenteye/images/tools.png) -*דף Tools: אותה מפת חום וקו אחוזון, בתוספת פירוק הצלחה וכישלון וקו התפלגות כלי.* +![עמוד Tools המציג את מפת החום משותף של זמן-תגובה ורצועת אחוזונים ליד פירוט הצלחה וכישלון וסרגל חלוקה כלים](/agenteye/images/tools.png) +*עמוד Tools: אותה מפת חום ורצועת אחוזונים, בתוספת פירוט הצלחה וכישלון וסרגל חלוקה כלים.* -לצד התצוגה latency המשותפת, דף Tools מוסיף **פירוק הצלחה וכישלון** ו**קו התפלגות כלי**, כך שתראה בחטף אילו כלים אתה מסתמך עליהם הכי הרבה ואילו אוכלים את תקציב השגיאות שלך. +לצד תצוגת זמן-תגובה משותפת, עמוד Tools מוסיף **פירוט הצלחה וכישלון** ו**סרגל חלוקה כלים**, כדי שתראה במבט אחד אילו כלים אתה מסתמך עליהם ביותר ואילו אוכלים את תקציב השגיאות שלך. -## Hooks: אתר את ה-hook והטריגר המדויקים +## Hooks: הצביע על ההוק המדויק והטריגר -כאשר lifecycle hook משך run, "hooks הם איטיים" אינו משהו שאתה יכול לפעול לפיו. דף Hooks מקבל אותך לזה שחשוב. +כאשר lifecycle hook משך ריצה, "hooks הם איטיים" אינו משהו שאתה יכול לפעול עליו. עמוד Hooks מביא אותך לזה שחשוב. -![דף Hooks המציג latency מפורק לפי שם hook ואירוע טריגר על מפת החום והקו האחוזון המשותפים](/agenteye/images/hooks.png) -*דף Hooks: latency מפורק לפי שם hook ואירוע טריגר.* +![עמוד Hooks המציג זמן-תגובה מפורק לפי שם הוק ואירוע טריגר על מפת החום משותף ורצועת אחוזונים](/agenteye/images/hooks.png) +*עמוד Hooks: זמן-תגובה מפורק לפי שם הוק ואירוע טריגר.* -על אותה מפת חום של latency וקו אחוזון, דף Hooks מפרק את הפעילות לפי **שם hook** ו**אירוע טריגר**, כך שתנחת על ה-hook האחד ואירוע אחד שצריכים תשומת לב. +על אותה מפת חום של זמן-תגובה ורצועת אחוזונים, עמוד Hooks משבר פעילות לפי **שם הוק** ו**אירוע טריגר**, כדי שתנחת על ההוק היחיד ועל האירוע היחיד שצריכים תשומת לב. ## קשור -- [Event stream](/he/agenteye/event-stream): השביל החי וקידוד הצבע של כל אירוע. -- [Sessions](/he/agenteye/sessions): צבור אירועים לשורה אחת לכל ריצה ופתח את גרף ההוצאה לפועל שלה. -- [Error tracking](/he/agenteye/error-tracking): משטח triage אחד לכל מה שהלוח הבקרה צובע אדום. -- [Dashboards](/he/agenteye/dashboards): צפייה rolled-up על פני הצי שלך. \ No newline at end of file +- [Event stream](/he/agenteye/event-stream): השביל חי ובעל קוד צבע של כל אירוע. +- [Sessions](/he/agenteye/sessions): גלגל אירועים לשורה אחת לכל ריצה ופתח את גרף ההעדכון שלו. +- [Error tracking](/he/agenteye/error-tracking): משטח טריאז אחד לכל מה שהדשבורד צובע באדום. +- [Dashboards](/he/agenteye/dashboards): תצוגות צבירה על פני הצי שלך. \ No newline at end of file diff --git a/docs/he/architecture.mdx b/docs/he/architecture.mdx index da6f733d..066cfbee 100644 --- a/docs/he/architecture.mdx +++ b/docs/he/architecture.mdx @@ -1,10 +1,11 @@ --- +--- title: ארכיטקטורה -description: "כיצד מטפל ה-hook, טעינת ההגדרות והערכת המדיניות פועלים באופן פנימי" +description: "כיצד מטפל ה-hook, טעינת קונפיגורציה והערכת מדיניות עובדים באופן פנימי" icon: sitemap --- -מסמך זה מסביר כיצד failproofai עובד באופן פנימי: כיצד מערכת ה-hook יוצרת intercept לקריאות כלים של Agent, כיצד הגדרות נטענות ומשולבות, כיצד מדיניות מוערכות, וכיצד ה-dashboard עוקב אחרי פעילות agent. +מסמך זה מסביר כיצד failproofai עובד באופן פנימי: כיצד מערכת ה-hook מיירטת קריאות כלי סוכן, כיצד קונפיגורציה נטענת ומוזגת, כיצד מדיניות מוערכת, וכיצד הלוח מעקב אחר פעילות הסוכן. --- @@ -12,18 +13,18 @@ icon: sitemap ל-failproofai שתי תת-מערכות עצמאיות: -1. **מטפל Hook** - תת-תהליך CLI מהיר ש-Claude Code משדר בכל קריאת כלי agent. מעריך מדיניות וחוזר החלטה. -2. **Agent Monitor (Dashboard)** - יישום אינטרנט Next.js לניטור הפעלות של agent וניהול מדיניות. +1. **Hook handler** - תהליך CLI מהיר שלא Claude Code מפעיל בכל קריאת כלי סוכן. מעריך מדיניות וחוזר עם החלטה. +2. **Agent Monitor (Dashboard)** - יישומת Next.js לניטור הפעלות סוכן וניהול מדיניות. -שתי התת-מערכות חולקות קבצי הגדרות ב-`~/.failproofai/` ובדירקטוריון `.failproofai/` של הפרויקט, אך הן פועלות כתהליכים נפרדים ותקשרות רק דרך מערכת הקבצים. +שתי תת-המערכות משתפות קבצי קונפיגורציה ב-`~/.failproofai/` וב-`.failproofai/` של הפרויקט, אך הן רצות כתהליכים נפרדים ותקשרות רק דרך מערכת הקבצים. --- -## מטפל Hook +## Hook handler ### אינטגרציה עם Claude Code -כאשר אתה מריץ `failproofai policies --install`, הוא כותב ערכים כאלה ל-`~/.claude/settings.json`: +כאשר תריץ `failproofai policies --install`, זה כותב ערכים כאלה ל-`~/.claude/settings.json`: ```json { @@ -44,9 +45,9 @@ icon: sitemap } ``` -Claude Code אז משדר את `failproofai --hook PreToolUse` כתת-תהליך לפני כל קריאת כלי, ומעביר payload JSON ב-stdin. +Claude Code לאחר מכן מפעיל `failproofai --hook PreToolUse` כתהליך משנה לפני כל קריאת כלי, ומעביר payload JSON על stdin. -### פורמט Payload +### פורמט payload ```json { @@ -62,7 +63,7 @@ Claude Code אז משדר את `failproofai --hook PreToolUse` כתת-תהליך עבור אירועי `PostToolUse`, ה-payload מכיל גם `tool_result` עם הפלט של הכלי. -המטפל אוכף מגבלת stdin של 1 MB. Payloads שחוצים זה מושלכים וכל המדיניות מאפשרת באופן משתמע. +המטפל אוכף מגבלת stdin של 1 MB. Payloads העולים על זה משלכים ובכל המדיניות מאופשרת בעיקרון. ### פורמט תגובה @@ -85,7 +86,7 @@ Claude Code אז משדר את `failproofai --hook PreToolUse` כתת-תהליך } ``` -**Instruct (כל אירוע פרט ל-Stop):** +**Instruct (כל אירוע מלבד Stop):** ```json { "hookSpecificOutput": { @@ -94,7 +95,7 @@ Claude Code אז משדר את `failproofai --hook PreToolUse` כתת-תהליך } ``` -**אירוע Stop instruct:** +**Stop event instruct:** - קוד יציאה: `2` - סיבה כתובה ל-stderr (לא stdout) @@ -104,23 +105,23 @@ Claude Code אז משדר את `failproofai --hook PreToolUse` כתת-תהליך **Allow עם הודעה:** -`allow(message)` מאפשר למדיניות לשלוח הקשר מידע חוזר ל-Claude גם כשהפעולה מותרת. מטפל ה-hook כותב את ה-JSON הבא ל-**stdout** (לא קובץ הגדרות — זו התגובה של המטפל ל-Claude Code, בדיוק כמו תגובות deny ו-instruct לעיל): +`allow(message)` מאפשר למדיניות לשלוח הקשר מידע חוזר ל-Claude גם כאשר הפעולה מורשית. מטפל ה-hook כותב את JSON הבא ל-**stdout** (לא קובץ קונפיגורציה — זו התגובה של המטפל ל-Claude Code, בדיוק כמו תגובות deny ו-instruct לעיל): ```json -// כתוב ל-stdout על ידי תהליך מטפל ה-hook +// Written to stdout by the hook handler process { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." } } ``` -- קוד יציאה: `0` (הפעולה מותרת) -- כאשר מספר מדיניות חוזרות `allow` עם הודעה, ההודעות שלהן משולבות עם newlines לתוך מחרוזת `additionalContext` יחידה -- אם אף מדיניות לא מספקת הודעה, stdout ריק (כמו קודם) +- קוד יציאה: `0` (פעולה מורשית) +- כאשר מדיניות מרובות מחזירות `allow` עם הודעה, ההודעות שלהן מחוברות בשורות חדשות ל-`additionalContext` יחיד +- אם אין למדיניות הודעה, stdout ריק (כמו בעבר) -### צינור עיבוד +### עמוד עיבוד -`src/hooks/handler.ts` מיישם את הצינור המלא: +`src/hooks/handler.ts` מיישם את כל הפייפליין: ```text stdin JSON @@ -139,13 +140,13 @@ stdin JSON → exit ``` -כל התהליך רץ תחת 100ms עבור payloads טיפוסיים ללא קריאות LLM. +כל התהליך פועל בתוך 100ms לפחות עבור payloads טיפוסיים ללא קריאות LLM. --- -## טעינת הגדרות +## טעינת קונפיגורציה -`src/hooks/hooks-config.ts` מיישם טעינת הגדרות בתלת-scope. +`src/hooks/hooks-config.ts` מיישם טעינת קונפיגורציה בתלת-scope. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -154,33 +155,33 @@ stdin JSON ``` לוגיקת merge: -- `enabledPolicies` - איחוד מבודד בכל שלושת הקבצים -- `policyParams` - לכל מדיניות, הקובץ הראשון שמגדיר אותו מנצח לחלוטין -- `customPoliciesPath` - הקובץ הראשון שמגדיר אותו מנצח -- `llm` - הקובץ הראשון שמגדיר אותו מנצח +- `enabledPolicies` - איחוד מבוטל כפילויות בכל שלושת הקבצים +- `policyParams` - לכל מדיניות, הקובץ הראשון המגדיר אותה מנצח לחלוטין +- `customPoliciesPath` - הקובץ הראשון המגדיר אותו מנצח +- `llm` - הקובץ הראשון המגדיר אותו מנצח -ה-dashboard של האינטרנט משתמש ב-`readHooksConfig()` (global only) לקריאה וכתיבה, מכיוון שהוא לא משדר עם project cwd. +לוח המחוונים של האינטרנט משתמש ב-`readHooksConfig()` (כללי בלבד) לקריאה וכתיבה, מכיוון שהוא אינו מופעל עם project cwd. --- ## הערכת מדיניות -`src/hooks/policy-evaluator.ts` מריץ מדיניות בסדר. +`src/hooks/policy-evaluator.ts` מפעיל מדיניות בסדר. -עבור כל מדיניות: +לכל מדיניות: -1. חפש את סכימת `params` של המדיניות (אם יש לה כזה). -2. קרא את `policyParams[policy.name]` מהגדרה המוזגת. -3. מזג ערכים שסופקו על ידי המשתמש על פני ברירות מחדל של סכימה כדי לייצר `ctx.params`. -4. קרא את `policy.fn(ctx)` עם ההקשר שנפתר. -5. אם התוצאה היא `deny`, עצור מיד והחזר החלטה זו. -6. אם התוצאה היא `instruct`, צבור את ההודעה והמשך. +1. חפש את סכמת `params` של המדיניות (אם יש לה). +2. קרא את `policyParams[policy.name]` מהקונפיגורציה המוזגת. +3. מזג ערכים שנספקו על ידי המשתמש על ברירות מחדל של סכמה כדי לייצר `ctx.params`. +4. קרא ל-`policy.fn(ctx)` עם הקשר שנפתר. +5. אם התוצאה היא `deny`, עצור מיד וחזור עם החלטה זו. +6. אם התוצאה היא `instruct`, הצבר את ההודעה והמשך. 7. אם התוצאה היא `allow`, המשך למדיניות הבאה. -לאחר שכל המדיניות פעלות: -- אם כל `deny` הוחזר, פלוט את תגובת ה-deny. -- אם כל `instruct` הוחזרו נאספו, פלוט תגובת instruct יחידה עם כל ההודעות משולבות. -- אחרת, פלוט תגובה allow (stdout ריק, exit 0). +לאחר שכל המדיניות רצה: +- אם הוחזר `deny`, שלח את תגובת deny. +- אם נאספו החזרות `instruct`, שלח תגובת instruct יחיד עם כל ההודעות מחוברות. +- אחרת, שלח תגובת allow (stdout ריק, יציאה 0). --- @@ -204,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -מדיניות המקבלת `params` מצהירה `PolicyParamsSchema` עם סוגים וברירות מחדל לכל פרמטר. מעריך המדיניות משדר ערכים שנפתרו ל-`ctx.params` לפני קריאה ל-`fn`. פונקציות מדיניות קוראות `ctx.params` ללא null-guarding מכיוון שברירות מחדל תמיד מוחלות קודם. +מדיניות המקבלת `params` מצהירה על `PolicyParamsSchema` עם סוגים וברירות מחדל לכל פרמטר. משערך המדיניות מזריק ערכים שנפתרו ל-`ctx.params` לפני קריאה ל-`fn`. פונקציות מדיניות קוראות `ctx.params` ללא null-guarding מכיוון שברירות מחדל תמיד מיושמות תחילה. -התאמת דפוס בתוך מדיניות משתמשת בתוקנים מפוענחי פקודה (argv), לא התאמה של מחרוזות גולמיות. זה מונע עקיפה דרך הזרקת מפעילים של shell (למשל דפוס עבור `sudo systemctl status *` לא יכול להיות מעוקף על ידי הוספת `; rm -rf /` לפקודה). +התאמת דפוסים בתוך מדיניות משתמשת בטוקנים פקודה מנוסחים (argv), לא התאמה של מחרוזת גולמית. זה מונע עקיפה דרך הזרקת מפעיל shell (לדוגמה, דפוס `sudo systemctl status *` לא ניתן לעקוף על ידי הוספת `; rm -rf /` לפקודה). --- -## מדיניות מותאמת אישית +## מדיניות מותאמת -`src/hooks/custom-hooks-registry.ts` מיישם רג'יסטרי תומך `globalThis`: +`src/hooks/custom-hooks-registry.ts` מיישם רישום מבוסס `globalThis`: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -227,23 +228,23 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` טוען את קובץ המדיניות של המשתמש: -1. קרא את `customPoliciesPath` מההגדרות; דלג אם חסר. -2. פתור לנתיב מוחלט; בדוק שהקובץ קיים. -3. כתוב מחדש את כל ה-`from "failproofai"` imports לנתיב dist בפועל כך `customPolicies` מתחזר לרג'יסטרי `globalThis` זהה. -4. כתוב מחדש transitive local imports רקורסיבי כדי להבטיח תאימות ESM. +1. קרא `customPoliciesPath` מהקונפיגורציה; דלג אם לא קיים. +2. פתור לנתיב מוחלט; בדוק אם קובץ קיים. +3. כתוב מחדש את כל ייבוא `from "failproofai"` לנתיב dist בפועל כדי ש-`customPolicies` יפתור לאותו רישום `globalThis`. +4. כתוב מחדש באופן רקורסיבי ייבוא מקומי טרנזיטיבי כדי להבטיח תאימות ESM. 5. כתוב קבצי `.mjs` זמניים ו-`import()` את קובץ הערך. -6. קרא `getCustomHooks()` כדי לאחזר hooks רשומים. -7. נקה את כל קבצים זמניים בבלוק `finally`. +6. קרא ל-`getCustomHooks()` כדי לשלוף את ה-hooks הרשומים. +7. נקה את כל הקבצים הזמניים בבלוק `finally`. -בכל שגיאה (קובץ לא נמצא, שגיאת תחביר, כשל בייבוא), השגיאה מתועדת ל-`~/.failproofai/hook.log` והמטעין מחזיר מערך ריק. מדיניות מובנית לא מושפעת. +בכל שגיאה (קובץ לא נמצא, שגיאת תחביר, כשל ייבוא), השגיאה מתועדת ל-`~/.failproofai/hook.log` והטוען מחזיר מערך ריק. מדיניות מובנית אינה מושפעת. -מדיניות מותאמת אישית מוערכת לאחר כל המדיניות המובנות. מדיניות מותאמת אישית `deny` עדיין מקצרת מדיניויות מותאמות אישיות נוספות (אך כל המובנות כבר רצו בנקודה זו). +מדיניות מותאמת מוערכת לאחר כל המדיניות המובנות. `deny` מדיניות מותאמת עדיין מקצר מדיניות מותאמת נוספת (אך כל הבנויות כבר פעלו בנקודה זו). --- -## ניתוח פעילות +## רישום פעילות -לאחר כל אירוע hook, המטפל משדר שורת JSONL ל-`~/.failproofai/hook-activity/current.jsonl`, שמסתובבת ל-`page--.jsonl` ברגע שהוא מגיע לעמוד: +לאחר כל אירוע hook, המטפל הוסף שורת JSONL ל-`~/.failproofai/hook-activity/current.jsonl`, המתחדשת ל-`page--.jsonl` לאחר שהוא מגיע לעמוד: ```json { @@ -258,13 +259,13 @@ export function clearCustomHooks(): void { ... } // used in tests } ``` -שורה אחת לכל מדיניות שהחזירה החלטה שאינה allow. החלטות Allow לא מתועדות (כדי להשאיר את הקובץ קטן). +שורה אחת לכל מדיניות שהחליטה להחלטה שאינה allow. החלטות Allow אינן מתועדות (כדי לשמור על הקובץ קטן). --- -## ארכיטקטורת Dashboard +## ארכיטקטורת לוח המחוונים -ה-dashboard הוא יישום **Next.js 16** המשתמש ב-App Router עם React Server Components ו-Server Actions. +לוח המחוונים הוא יישומת **Next.js 16** המשתמשת ב-App Router עם React Server Components ו-Server Actions. ```text app/ @@ -286,16 +287,16 @@ app/ **זרימת נתונים:** -- רכיבי עמוד קוראים `lib/projects.ts` ו-`lib/log-entries.ts` כדי לקרוא נתוני project/session ישירות ממערכת הקבצים (אין שכבת API לקריאות). -- עמוד Policies משתמש ב-Server Actions לכל המוטציות (toggle, params update, install/remove). -- מצפה ההפעלה מפענח את פורמט הטרנסקריפט JSONL של Claude ומעביר ציר הזמן של הודעות וקריאות כלים. +- רכיבי עמוד קוראים ל-`lib/projects.ts` ו-`lib/log-entries.ts` כדי לקרוא נתוני פרויקט/הפעלה ישירות מאחסן הקבצים (ללא שכבת API לקריאות). +- דף המדיניות משתמש ב-Server Actions לכל המוטציות (החלפה, עדכון פרמטרים, התקנה/הסרה). +- צופה ההפעלה מנתח את פורמט תמלול JSONL של Claude ומרנדר ציר זמן של הודעות וקריאות כלים. -**החלטות עיצוב מרכזיות:** +**החלטות עיצוב חיוני:** -- אין מסד נתונים - כל מצב קבוע הוא בקבצים רגילים (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions לתוך מוטציות - אין צורך ב-REST API עבור פעולות CRUD. -- React Server Components עבור עמודי קריאה - טעינה ראשונית מהירה יותר, אין חבילה של client עבור fetch נתונים. -- רכיבי client רק כאשר נדרשת אינטראקטיביות (toggles מדיניות, חיפוש פעילות, צופה יומן). +- ללא מסד נתונים - כל המצב הקבוע נמצא בקבצים פשוטים (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions לתרופות - אין צורך ב-REST API לפעולות CRUD. +- React Server Components עבור עמודי קריאה - טעינה ראשונית מהירה יותר, ללא חבילת לקוח להביא נתונים. +- רכיבי לקוח רק בו אינטראקטיביות נדרשת (מדיניות toggles, חיפוש פעילות, צופה יומן). --- diff --git a/docs/he/built-in-policies.mdx b/docs/he/built-in-policies.mdx index c720787d..0af6ed93 100644 --- a/docs/he/built-in-policies.mdx +++ b/docs/he/built-in-policies.mdx @@ -1,11 +1,10 @@ --- ---- title: המדיניות המובנות -description: "כל 39 המדיניות המובנות שתופסות מצבי כשל נפוצים של סוכנים" +description: "כל 39 מדיניות מובנות שתופסות מצבי כשל נפוצים של סוכנים" icon: shield --- -failproofai מגיע עם 39 מדיניות מובנות שתופסות מצבי כשל נפוצים של סוכנים. כל מדיניות מופעלת על סוג אירוע hook ספציפי ושם כלי. תשע עשרה מדיניות מקבלות פרמטרים שמאפשרים לך לכוונן את התנהגותן ללא כתיבת קוד. חמש מדיניות של זרימת עבודה אוכפות צינור commit → push → PR → CI לפני שהסוכן מפסיק. +failproofai מגיע עם 39 מדיניות מובנות שתופסות מצבי כשל נפוצים של סוכנים. כל מדיניות מופעלת על סוג אירוע hook ושם כלי ספציפיים. תשע עשרה מדיניות מקבלות פרמטרים המאפשרים לך לכייל את התנהגותן ללא כתיבת קוד. חמש מדיניות זרימת עבודה כופות צינור commit → push → PR → CI לפני שClaude עוצר. --- @@ -14,29 +13,31 @@ failproofai מגיע עם 39 מדיניות מובנות שתופסות מצבי המדיניות מחולקות לקטגוריות: | קטגוריה | מדיניות | סוג Hook | -|----------|---------|-----------| +|----------|----------|-----------| | [פקודות מסוכנות](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | -| [פקודות Infrastructure](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [סודות (sanitizers)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [פקודות תשתית](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [סודות (מטהרים)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [סביבה](#environment) | block-env-files, protect-env-vars | PreToolUse | -| [גישת קבצים](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| [גישה לקבצים](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | | [מסד נתונים](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | | [אזהרות](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | | [מנהלי חבילות](#package-managers) | prefer-package-manager | PreToolUse | | [זרימת עבודה](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — עצור את הסוכן מההמשך. -- **`warn-`** — תן לסוכן הקשר נוסף כדי שיוכל להתקן את עצמו. -- **`sanitize-`** — הסר נתונים רגישים מפלט הכלי לפני שהסוכן רואה זאת. +- **`block-`** — עצור את הסוכן מהמשך. +- **`warn-`** — תן לסוכן הקשר נוסף כדי שיוכל לתקן את עצמו. +- **`sanitize-`** — נקה נתונים רגישים מפלט כלי לפני שהסוכן רואה זאת. -### Namespaces +### מרחבי שמות -כל מדיניות נמצאת בחריץ `/`. המדיניות המובנות שייכות ל- -namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namespace -מונע התנגשויות כאשר אתה טוען גם מדיניות מותאמות או של צד שלישי עם שמות קצרים דומים. +כל מדיניות נמצאת בחריץ `/`. מדיניות מובנות שייכות ל +**`failproofai/`** namespace — לדוגמה, `failproofai/sanitize-jwt`. מרחב השמות +מונע התנגשויות כאשר אתה גם טוען מדיניות מותאמות או של צד שלישי +עם שמות קצרים דומים. -בתצורה שלך אתה יכול להתייחס למדיניות מובנית בשם קצר או בשם מוקדם; שתי הצורות מתייחסות לאותה מדיניות: +בקונפיגורציה שלך אתה יכול להתייחס למדיניות מובנית על ידי השם הקצר או +השם המתוקן שלה; שתי הצורות מתוקנות לאותה מדיניות: ```json { @@ -47,42 +48,43 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp } ``` -אם לשם אין `/`, failproofai מתייחס אליו כשייך ל-namespace ברירת המחדל `failproofai`. שמות שכבר מכילים `/` (למשל `myorg/foo`, +אם לשם אין `/`, failproofai מחשיב אותו כשייך ל namespace ברירת המחדל +`failproofai`. שמות המכילים כבר `/` (לדוגמה `myorg/foo`, `custom/my-hook`) נשמרים כמו שהם. -- **`require-`** — חסום את אירוע Stop עד שתנאים מתקיימים. +- **`require-`** — חסום את אירוע ה-Stop עד שתנאים מתקיימים. --- -כל מדיניות תומכת בשדה `hint` אופציונלי ב-`policyParams`. ה-hint מצורף להודעת ה-deny או ה-instruct שClaude רואה, מה שנותן הנחיות שימושיות ללא שינוי קוד מדיניות. עובד עם מדיניות מובנות, מותאמות, וקונווקציה. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. +כל מדיניות תומכת בשדה `hint` אופציונלי ב-`policyParams`. ה-hint מוספף להודעת deny או instruct שClaude רואה, ומספק הנחיה ממשמעותית ללא שינוי קוד המדיניות. עובד עם מדיניות מובנות, מותאמות, וקונבנציה. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. --- ## פקודות מסוכנות -מנע מסוכנים הפעלת פעולות שקשה לבטל או שיכולות לפגוע במערכת המארח. +מנע מסוכנים הפעלת פעולות שקשה לבטל או שעלולות לפגוע במערכת המתארח. ### `block-sudo` **Event:** PreToolUse (Bash) -**Default:** מחסום כל פקודת `sudo` או `doas`. +**Default:** מסרב לכל פקודת `sudo` או `doas`. -חוסם פקודה שמריצה בינארית הרמה **במצב הפקודה**. ההתאמה היא מבנית ולא טקסטואלית: הפקודה מחולקת לקטעים כמו שקליפה הייתה עושה זאת, הקצאות קידומת (`FOO=bar`), הפניות מחדש, ורייצים עם הדגלים שלהם (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) מהולכים ברחוק, והבינארי המתקבל מושווה לפי **basename**. אז `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` ו-`bash -c "sudo …"` כולם חסומים, ו-`doas` מתורגמן בתור אותו היכולת תחת שם שונה. +חוסם פקודה שמפעילה בינארי הנמקה **במצב הפקודה**. ההתאמה היא מבנית ולא טקסטואלית: הפקודה מחולקת לסגמנטים בדרך שהשל היה עושה, השמות שלפנים (`FOO=bar`), הפניות, וחוקים עם הדגלים שלהם (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, ...) הם חלפו, והבינארי המתקבל מושווה לפי **basename**. אז `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` ו-`bash -c "sudo ..."` כולם מסורבים, ו-`doas` מטופל כאותה יכולת תחת שם אחר. -כי זה מעוגן במצב פקודה ולא בהופעת המילה בכל מקום, זה **לא** מופעל על פקודות שרק מזכירות זאת — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, או ההיתוך `grep` המכיל את המילה כלם רצים בדרך כלל. +מכיוון שהוא עוגן על מצב הפקודה ולא על המילה המופיעה בכל מקום, היא **לא** מופעלת על פקודות שרק מזכירות זאת — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, או `grep` החלפה המכילה את המילה כל רץ בדרך כלל. -זה עוצר את הניסיון הברור; זה לא סוגר את הסוג. סוכן שיכול להריץ shell שרירותי יכול עדיין להגיע להרמה בעקיפין — דרך משתנה (`S=sudo; $S …`), צינור מפוענח base64, או קובץ מעטפת על דיסק — כי לא ניתן לעקוב אחר אלה מבדיקה של string פקודה בודדה. תייחס לזה כמשוער כנגד טעויות וסקאלציה מזדמנת, לא כגבול ביטחון נגד סוכן מוחלט. גבול אמיתי חייב להיות אכוף מתחת לקליפה. +זה עוצר את הנסיון הברור; זה לא סוגר את המחלקה. סוכן שיכול להפעיל של שרירותי עדיין יכול להגיע להנמקה בעקיפין — דרך משתנה (`S=sudo; $S ...`), pipe מקודד base64, או תסריט wrapper על הדיסק — כי אין בדיקה של מחרוזת פקודה אחת יכולה לעקוב אחרי אלה. התייחס לזה כ guardrail נגד טעויות וטיפול בקנה מידה קל, לא כגבול אבטחה נגד סוכן מחושב. גבול אמיתי צריך להיות מוגבל מתחת לקליפה. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה מדויקות המותרות. כל רשומה מתאימה לאסימוני argv מנתחים. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה מדוקדקות המותרות. כל ערך מתואם נגד אפילוגים argv שנותחו. | -**Example:** +**דוגמה:** ```json { @@ -94,10 +96,10 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp } ``` -עם תצורה זו, `sudo systemctl status nginx` מותרת, אך `sudo rm /etc/hosts` חסומה. +עם קונפיגורציה זו, `sudo systemctl status nginx` מותר, אך `sudo rm /etc/hosts` מסורב. -דפוסים מתאימים לאסימוני מנתחים, לא ל-raw command string. זה מונע bypass דרך אופרטורים קליפה מצורפים (למשל `sudo systemctl status x; rm -rf /` לא תואמת `sudo systemctl status *`). +דפוסים מתואמים נגד אפילוגים שנותחו, לא מחרוזת הפקודה הגולמית. זה מונע bypass דרך אופרטורים shell מצורפים (לדוגמה `sudo systemctl status x; rm -rf /` אינו תואם ל-`sudo systemctl status *`). --- @@ -105,15 +107,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-rm-rf` **Event:** PreToolUse (Bash) -**Default:** מחסום `rm -rf`, `rm -fr`, וצורות מחיקה רקורסיבית דומות. +**Default:** מסרב ל-`rm -rf`, `rm -fr`, וצורות מחיקה רקורסיבית דומות. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | נתיבים שבטוח למחוק בצורה רקורסיבית (למשל `/tmp`). | +| `allowPaths` | `string[]` | `[]` | נתיבים שבטוח למחוק באופן רקורסיבי (לדוגמה `/tmp`). | -**Example:** +**דוגמה:** ```json { @@ -130,7 +132,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-curl-pipe-sh` **Event:** PreToolUse (Bash) -**Default:** מחסום `curl | bash`, `curl | sh`, `wget | bash`, ודפוסים דומים. +**Default:** מסרב ל-`curl | bash`, `curl | sh`, `wget | bash`, ודפוסים דומים. אין פרמטרים. @@ -139,7 +141,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-failproofai-commands` **Event:** PreToolUse (Bash) -**Default:** מחסום פקודות שהיו מסירות או מנטרלות את failproofai עצמו (למשל `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Default:** מסרב לפקודות שהיו מסירות או משביתות את failproofai עצמו (לדוגמה `npm uninstall failproofai`, `failproofai policies --uninstall`). אין פרמטרים. @@ -148,34 +150,34 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-self-pause` **Event:** PreToolUse (Bash) -**Default:** מחסום `failproofai config --pause`, שמושהה את האכיפה לסשן. השהיה היא החלטה אנושית — סוכן שיכול להריץ אותה יכול לכבות כל מדיניות אחרת עם פקודה אחת. +**Default:** מסרב ל-`failproofai config --pause`, אשר משהה אכיפה לסשן. השהיה היא החלטה אנושית — סוכן שיכול להפעיל אותה יכול להשבית כל מדיניות אחרת עם פקודה אחת. -צר יותר מ-[`block-failproofai-commands`](#block-failproofai-commands) בכוונה, ולא מכוסה על ידו: מדיניות זו מעוגנת בגבול פקודה, כך `npx -y failproofai config --pause` לא תואמת אותה, ובהיותה רחבה היא לעתים קרובות כבויה כדי שסוכנים יוכלו להריץ `failproofai audit`. `--resume` ו-`--status` מותרים — אף אחד מהם לא מסיר אכיפה. +צר יותר מ-[`block-failproofai-commands`](#block-failproofai-commands) בכוונה, ולא מכוסה בו: מדיניות זו עוגן על גבול פקודה, אז `npx -y failproofai config --pause` אינו תואם אותו, ובהיותו רחב הוא לעתים קרובות כבוי כדי שסוכנים יוכלו להפעיל `failproofai audit`. `--resume` ו-`--status` מותרים — אף אחד מהם אינו מסיר אכיפה. -זה עוצר את הניסיון הישיר, לא את כל הסוג: סוכן יכול עדיין להגיע לאותו מצב דרך כינוי או קובץ מעטפת. סגירתו במלואו דורשת שההשהיה לא תהיה נגישה מקריאת כלי כלל. +זה עוצר את הנסיון הישיר, לא את כל המחלקה: סוכן יכול עדיין להגיע לאותו מצב דרך alias או תסריט wrapper. סגירת זה לחלוטין דורשת שההשהיה תהיה בלתי מסיסה מקריאת כלי בכלל. אין פרמטרים. --- -## פקודות Infrastructure +## פקודות תשתית -עצור סוכני קידוד מהפעלת CLIs infrastructure או הפעלת צינורות CI/CD. כל מדיניות בקטגוריה זו היא **opt-in** (`defaultEnabled: false`) — סוכנים שצריכים בדרך כלל לקרוא `kubectl`, `terraform`, וכו' לא יופרעו אלא אם תפעיל את המדיניות. כאשר הוא מופעל, כל הקראת ה-CLI המתאימה חסומה אלא אם הפקודה תואמת רשומה ב-`allowPatterns`. +עצור סוכנים קידוד מהפעלת CLIs תשתית או הפעלת צינורות CI/CD. כל המדיניות בקטגוריה זו הן **opt-in** (`defaultEnabled: false`) — סוכנים שצריכים בחוקיות להתקשר ל-`kubectl`, `terraform`, וכו'. לא יופרעו אלא אם אתה מאפשר את המדיניות. כאשר מופעלת, כל הפעלה של CLI תואמת מסורבת אלא אם הפקודה תואמת ערך ב-`allowPatterns`. -דקדוק דפוס זהה ל-[`block-sudo`](#block-sudo): אסימונים מתאימים לאסימוני argv מנתחים, `*` הוא כרטיס בר-תוקף לאסימון אחד, וכל פקודה המכילה אופרטור קליפה עצמאי (`&&`, `||`, `|`, `;`) או אסימון עם תווי מטא-קליפה משובצים נדחת לפני התאמת allowlist להגנה מפני התעלמות הזרקה. +דקדוק התבנית זהה ל-[`block-sudo`](#block-sudo): אפילוגים מתואמים נגד argv שנותח, `*` הוא wildcard עבור אפילוג אחד, וכל פקודה המכילה operator shell עצמאי (`&&`, `||`, `|`, `;`) או אפילוג עם תווי מטא של shell משובצים נדחית לפני התאמה allowlist כדי למנוע עקיפות הזרקה. ### `block-kubectl` **Event:** PreToolUse (Bash) -**Default:** מחסום כל הקראת `kubectl`. +**Default:** מסרב לכל הפעלה של `kubectl`. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | קידומות פקודה kubectl המותרות. | -**Example:** +**דוגמה:** ```json { @@ -187,22 +189,22 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp } ``` -עם תצורה זו, `kubectl get pods` מותרת אך `kubectl apply -f deploy.yaml` חסומה. +עם קונפיגורציה זו, `kubectl get pods` מותר אך `kubectl apply -f deploy.yaml` מסורב. --- ### `block-terraform` **Event:** PreToolUse (Bash) -**Default:** מחסום כל הקראת `terraform` או `tofu` (OpenTofu). +**Default:** מסרב לכל הפעלה של `terraform` או `tofu` (OpenTofu). -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | קידומות פקודה terraform/tofu המותרות. | -**Example:** +**דוגמה:** ```json { @@ -219,15 +221,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-aws-cli` **Event:** PreToolUse (Bash) -**Default:** מחסום כל הקראת `aws` CLI. +**Default:** מסרב לכל הפעלה של `aws` CLI. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | קידומות פקודה aws CLI המותרות. | -**Example:** +**דוגמה:** ```json { @@ -244,15 +246,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-gcloud` **Event:** PreToolUse (Bash) -**Default:** מחסום כל הקראת `gcloud` (Google Cloud) CLI. +**Default:** מסרב לכל הפעלה של `gcloud` (Google Cloud) CLI. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | קידומות פקודה gcloud המותרות. | -**Example:** +**דוגמה:** ```json { @@ -269,15 +271,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-az-cli` **Event:** PreToolUse (Bash) -**Default:** מחסום כל הקראת `az` (Azure) CLI. +**Default:** מסרב לכל הפעלה של `az` (Azure) CLI. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | קידומות פקודה az CLI המותרות. | -**Example:** +**דוגמה:** ```json { @@ -294,15 +296,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-helm` **Event:** PreToolUse (Bash) -**Default:** מחסום כל הקראת `helm`. +**Default:** מסרב לכל הפעלה של `helm`. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | קידומות פקודה helm המותרות. | -**Example:** +**דוגמה:** ```json { @@ -319,7 +321,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-gh-pipeline` **Event:** PreToolUse (Bash) -**Default:** מחסום את תת-הפקודות `gh` CLI הבאות שמתחזקות מצב או מפעילות צינורות: +**Default:** מסרב לתתפקודי `gh` CLI הבאים המטרידים מצב או מפעילים צינורות: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -328,15 +330,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp - `gh cache delete` - `gh secret set`, `gh secret delete` -תת-פקודות `gh` של קריאה בלבד כגון `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, ו-`gh api repos/.../...` הם **לא** תואמים על ידי מדיניות זו — הם נדרשים בדרך כלל לבדיקות זרימת עבודה (כולל `require-ci-green-before-stop` של failproofai עצמו). +תתפקודי `gh` לקריאה בלבד כגון `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, ו-`gh api repos/.../...` הם **לא** מתואמים על ידי מדיניות זו — הם נדרשים בדרך כלל לבדיקות זרימת עבודה (כולל `require-ci-green-before-stop` של failproofai). -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | הקראות סקריפטיות ספציפיות להרשות גם כי אחרת הן היו חסומות. | +| `allowPatterns` | `string[]` | `[]` | קריאות תסריט ספציפיות המותרות למרות שהן היו מסורבות. | -**Example:** +**דוגמה:** ```json { @@ -350,14 +352,14 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp --- -## סודות (sanitizers) +## סודות (מטהרים) -עצור סוכנים מדליפת אישורים להקשר או פלט שלהם. מדיניות sanitizer מופעלת על אירועי **PostToolUse**. כאשר Claude מריץ פקודת Bash, קורא קובץ, או קורא לכל כלי, מדיניות אלה בוחנות את הפלט לפני שהוא מוחזר ל-Claude. אם תבנית סוד מתגלתה, המדיניות מחזירה החלטת deny שמונעת להעביר את הפלט חזרה. +עצור סוכנים מהדלפת אישורים להקשר או פלט שלהם. מדיניות מטהר מופעלת על אירועי **PostToolUse**. כאשר Claude מפעיל פקודת Bash, קורא קובץ, או קורא לכל כלי, מדיניות אלה בודקות את הפלט לפני שהוא מוחזר ל-Claude. אם נמצא דפוס סוד, המדיניות מחזירה החלטת deny המונעת את הפלט מהעברה חזרה. ### `sanitize-jwt` -**Event:** PostToolUse (כל כלים) -**Default:** Redacts JWT tokens (שלוש קטעים base64url מופרדים ב-`.`). +**Event:** PostToolUse (כל הכלים) +**Default:** מסתיר אפילוגי JWT (שלוש קטעי base64url מופרדים על ידי `.`). אין פרמטרים. @@ -365,16 +367,16 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `sanitize-api-keys` -**Event:** PostToolUse (כל כלים) -**Default:** Redacts תבניות מפתח API נפוצות: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`), ומפתחות Google API (`AIza`). +**Event:** PostToolUse (כל הכלים) +**Default:** מסתיר פורמטי מפתח API נפוצים: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), מפתחות גישה AWS (`AKIA`), מפתחות Stripe (`sk_live_`, `sk_test_`), ומפתחות Google API (`AIza`). -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | דפוסי regex נוספים להתייחס כסודות. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | דפוסי regex נוסף לטיפול כסודות. | -**Example:** +**דוגמה:** ```json { @@ -393,8 +395,8 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `sanitize-connection-strings` -**Event:** PostToolUse (כל כלים) -**Default:** Redacts connection strings של מסד נתונים המכילות אישורים משובצים (למשל `postgresql://user:password@host/db`). +**Event:** PostToolUse (כל הכלים) +**Default:** מסתיר מחרוזות חיבור מסד נתונים המכילות אישורים משובצים (לדוגמה `postgresql://user:password@host/db`). אין פרמטרים. @@ -402,8 +404,8 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `sanitize-private-key-content` -**Event:** PostToolUse (כל כלים) -**Default:** Redacts PEM blocks (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, וכו'). +**Event:** PostToolUse (כל הכלים) +**Default:** מסתיר בלוקים PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, וכו'). אין פרמטרים. @@ -411,8 +413,8 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `sanitize-bearer-tokens` -**Event:** PostToolUse (כל כלים) -**Default:** Redacts headers `Authorization: Bearer ` כאשר הטוקן הוא 20 תווים או יותר. +**Event:** PostToolUse (כל הכלים) +**Default:** מסתיר `Authorization: Bearer ` headers כאשר האפילוג הוא 20 תווים או יותר. אין פרמטרים. @@ -420,14 +422,14 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ## סביבה -הגן על תצורת סביבה רגישה מלהיות קראה או חשופה על ידי סוכנים. +הגן על קונפיגורציה סביבה רגישה מלהיות קרואה או חשופה על ידי סוכנים. ### `block-env-files` **Event:** PreToolUse (Bash, Read) -**Default:** מחסום קריאה של קבצי `.env` דרך `cat .env`, קריאות כלי `Read` עם `.env` כנתיב קובץ, וכו'. +**Default:** מסרב לקריאת קבצי `.env` דרך `cat .env`, קריאות כלי `Read` עם `.env` כנתיב הקובץ, וכו'. -לא חוסם `.envrc` או קבצים סמוכים לסביבה אחרים - רק קבצים בשם בדיוק `.env`. +אינו חוסם `.envrc` או קבצים סביבה אחרים - רק קבצים שנקראו בדיוק `.env`. אין פרמטרים. @@ -436,28 +438,28 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `protect-env-vars` **Event:** PreToolUse (Bash) -**Default:** מחסום פקודות שמדפיסות משתני סביבה: `printenv`, `env`, `echo $VAR`. +**Default:** מסרב לפקודות שמדפיסות משתני סביבה: `printenv`, `env`, `echo $VAR`. אין פרמטרים. --- -## גישת קבצים +## גישה לקבצים -שמור סוכנים עובדים בתוך גבולות פרויקט ובמרחק מקבצים רגישים. +שמור על סוכנים שעובדים בתוך גבולות פרויקט וחסום מקבצים רגישים. ### `block-read-outside-cwd` **Event:** PreToolUse (Read, Bash) -**Default:** מחסום קריאה של קבצים מחוץ לשורש הפרויקט. הגבול הוא `CLAUDE_PROJECT_DIR` (מוגדר פעם אחת לסשן על ידי Claude Code), עם fallback לספריית העבודה הנוכחית של הסשן כאשר משתנה זה לא מוגדר. שימוש בשורש הפרויקט בעדיפות על פני `cwd` החיוני פירושו שהגבול נשאר יציב גם לאחר ש-Claude מבחין ל-subdirectory. +**Default:** מסרב לקריאת קבצים מחוץ לשורש הפרויקט. הגבול הוא `CLAUDE_PROJECT_DIR` (מוגדר פעם אחת ליחס על ידי Claude Code), עם fallback לספריית העבודה הנוכחית של הסשן כאשר משתנה זה לא מוגדר. שימוש בשורש הפרויקט ולא ב-`cwd` החי פירושו שהגבול נשאר יציב אפילו אחרי ש-Claude `cd` לתוך תיקייה משנית. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | קידומות נתיבים מוחלטים המותרות גם אם מחוץ לשורש הפרויקט. | +| `allowPaths` | `string[]` | `[]` | קידומות נתיב מוחלטות המותרות אפילו אם מחוץ לשורש הפרויקט. | -**Example:** +**דוגמה:** ```json { @@ -474,15 +476,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-secrets-write` **Event:** PreToolUse (Write, Edit) -**Default:** מחסום כתיבה לקבצים בשימוש נפוץ למפתחות פרטיים ותעודות: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Default:** מסרב לכתיבה לקבצים הנמצאים בשימוש נפוץ עבור מפתחות פרטיים ותעודות: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | דפוסי שם קובץ נוספים (סגנון glob) לחסום. | +| `additionalPatterns` | `string[]` | `[]` | דפוסי שם קובץ נוסף (glob-style) לחסימה. | -**Example:** +**דוגמה:** ```json { @@ -498,20 +500,20 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ## Git -מנע pushes אקראיות, force-pushes, וטעויות ענף שקשה לבטל. +מנע pushes אקראיים, force-pushes, וטעויות ענף שקשה לבטל. ### `block-push-master` **Event:** PreToolUse (Bash) -**Default:** מחסום `git push origin main` ו-`git push origin master`. +**Default:** מסרב ל-`git push origin main` ו-`git push origin master`. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | שמות ענפים שלא ניתן לדחוף אליהם ישירות. | -**Example:** +**דוגמה:** ```json { @@ -524,7 +526,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ``` -כדי לאפשר דחיפה לכל הענפים (למעשה הכבאה מדיניות זו ללא הסרתה מ-`enabledPolicies`), הגדר `protectedBranches: []`. +כדי לאפשר דחיפה לכל הענפים (למעשה השבת מדיניות זו ללא הסרה מ-`enabledPolicies`), הגדר `protectedBranches: []`. --- @@ -532,22 +534,22 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `block-work-on-main` **Event:** PreToolUse (Bash) -**Default:** מחסום `git commit`, `git merge`, `git rebase`, ו-`git cherry-pick` בזמן שעץ העבודה נמצא על `main` או `master`. יצירה וחלפה של ענפים (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) אינם מושפעים. +**Default:** מסרב ל-`git commit`, `git merge`, `git rebase`, ו-`git cherry-pick` בזמן שעץ העבודה נמצא על `main` או `master`. יצירת ענף והחלפה (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) אינן מושפעות. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | שמות ענפים שעליהם commit/merge/rebase/cherry-pick חסום. | +| `protectedBranches` | `string[]` | `["main", "master"]` | שמות ענפים שעליהם commit/merge/rebase/cherry-pick מסורב. | --- ### `block-force-push` **Event:** PreToolUse (Bash) -**Default:** מחסום `git push --force` ו-`git push -f`. +**Default:** מסרב ל-`git push --force` ו-`git push -f`. -אין פרמטרים ספציפיים למדיניות. השתמש ב-[`hint`](/he/configuration#hint-cross-cutting) חוצה-גזירה להציע חלופות: +אין פרמטרים ספציפיים למדיניות. השתמש ב-[`hint`](/he/configuration#hint-cross-cutting) חוצה-עקוב לרוחב כדי להציע חלופות: ```json { @@ -564,7 +566,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `warn-git-amend` **Event:** PreToolUse (Bash) -**Default:** משנה את Claude להמשיך בזהירות בעת הפעלת `git commit --amend`. לא חוסם את הפקודה. +**Default:** מדריך Claude לתועלת בזהירות בעת הפעלת `git commit --amend`. אינו חוסם את הפקודה. אין פרמטרים. @@ -573,7 +575,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `warn-git-stash-drop` **Event:** PreToolUse (Bash) -**Default:** משנה את Claude לאישור לפני הפעלת `git stash drop`. לא חוסם את הפקודה. +**Default:** מדריך Claude לאישור לפני הפעלת `git stash drop`. אינו חוסם את הפקודה. אין פרמטרים. @@ -582,7 +584,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `warn-all-files-staged` **Event:** PreToolUse (Bash) -**Default:** משנה את Claude לבדיקת מה שהוא מבצע staging כאשר הוא מריץ `git add -A` או `git add .`. לא חוסם את הפקודה. +**Default:** מדריך Claude לסקור מה הוא עורך לבמה כאשר הוא מפעיל `git add -A` או `git add .`. אינו חוסם את הפקודה. אין פרמטרים. @@ -590,12 +592,12 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ## מסד נתונים -תפוס פעולות SQL הרסניות לפני שהן מבוצעות כנגד מסד הנתונים שלך. +תפוס פעולות SQL הרסניות לפני שהן מופעלות נגד מסד הנתונים שלך. ### `warn-destructive-sql` **Event:** PreToolUse (Bash) -**Default:** משנה את Claude לאישור לפני הפעלת SQL המכילה `DROP TABLE`, `DROP DATABASE`, או `DELETE` ללא סעיף `WHERE`. +**Default:** מדריך Claude לאישור לפני הפעלת SQL המכיל `DROP TABLE`, `DROP DATABASE`, או `DELETE` ללא סעיף `WHERE`. אין פרמטרים. @@ -604,7 +606,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `warn-schema-alteration` **Event:** PreToolUse (Bash) -**Default:** משנה את Claude לאישור לפני הפעלת הצהרות `ALTER TABLE`. +**Default:** מדריך Claude לאישור לפני הפעלת הצהרות `ALTER TABLE`. אין פרמטרים. @@ -617,15 +619,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `warn-large-file-write` **Event:** PreToolUse (Write) -**Default:** משנה את Claude לאישור לפני כתיבת קבצים גדולים מ-1024 KB. +**Default:** מדריך Claude לאישור לפני כתיבת קבצים גדולים מ-1024 KB. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | סף גודל קובץ בקילובייטים שמעליו הוצגת אזהרה. | +| `thresholdKb` | `number` | `1024` | סף גודל קובץ בקילובייטים שמעליו מוצגת אזהרה. | -**Example:** +**דוגמה:** ```json { @@ -638,7 +640,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ``` -עורך ה-hook אוכף מגבלת stdin של 1 MB על עומסים. כדי לבדוק מדיניות זו עם תוכן קטן, הגדר `thresholdKb` לערך הרבה מתחת ל-1024. +מטפל ה-hook אוכף גבול stdin של 1 MB על עומסים. כדי לבדוק מדיניות זו עם תוכן קטן, הגדר `thresholdKb` לערך הרבה מתחת ל-1024. --- @@ -646,7 +648,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `warn-package-publish` **Event:** PreToolUse (Bash) -**Default:** משנה את Claude לאישור לפני הפעלת `npm publish`. +**Default:** מדריך Claude לאישור לפני הפעלת `npm publish`. אין פרמטרים. @@ -655,7 +657,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `warn-background-process` **Event:** PreToolUse (Bash) -**Default:** משנה את Claude להיות זהיר בעת הפעלת תהליכים בתמונה דרך `nohup`, `&`, `disown`, או `screen`. +**Default:** מדריך Claude להיות זהיר בעת השקת תהליכים ברקע דרך `nohup`, `&`, `disown`, או `screen`. אין פרמטרים. @@ -664,7 +666,7 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `warn-global-package-install` **Event:** PreToolUse (Bash) -**Default:** משנה את Claude לאישור לפני הפעלת `npm install -g`, `yarn global add`, או `pip install` ללא סביבה וירטואלית. +**Default:** מדריך Claude לאישור לפני הפעלת `npm install -g`, `yarn global add`, או `pip install` ללא סביבה וירטואלית. אין פרמטרים. @@ -672,23 +674,23 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ## מנהלי חבילות -אכוף אילו מנהלי חבילות הסוכן רשאי להשתמש. +כופה איזה מנהלי חבילות הסוכן מורשה להשתמש. ### `prefer-package-manager` **Event:** PreToolUse (Bash) -**Default:** מנוטרל. כאשר מופעל, חוסם כל פקודת מנהל חבילות שלא ברשימת ה-`allowed` ואומר ל-Claude לכתוב מחדש את הפקודה בעזרת מנהל מותר. +**Default:** מושבת. כאשר מופעלת, חוסמת כל פקודת מנהל חבילות שלא ברשימת `allowed` וממדריכה Claude לשכתב את הפקודה בעזרת מנהל מותר. -גילויים: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. +מגלה: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | שמות מנהלי חבילות מותרים. כל מנהל שנגילה שאינו ברשימה זו חסום. כאשר ריק, המדיניות היא no-op. | -| `blocked` | string[] | `[]` | שמות מנהלים נוספים לחסום מעבר לרשימה המובנית (למשל `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | שמות מנהלי חבילות מותרים. כל מנהל שנגלה שלא ברשימה זו מחוסם. כאשר ריק, המדיניות היא no-op. | +| `blocked` | string[] | `[]` | שמות מנהלי חבילות נוספים לחסימה מעבר לרשימה המובנית (לדוגמה `['pdm', 'pipx']`). | רשימת החסימה המובנית מכסה: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. השתמש ב-`blocked` כדי להוסיף מנהלים שלא ברשימה זו. -**Example configuration:** +**קונפיגורציה דוגמה:** ```json { @@ -702,18 +704,18 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp } ``` -עם תצורה זו, `pip install flask` ו-`pdm install flask` שניהם חסומים עם הודעה שאומרת ל-Claude להשתמש ב-`uv` או `bun` במקום זאת. פקודות כמו `uv pip install flask` מותרות כי `uv` ברשימת ה-allowlist ובדיקות תחילה. +עם קונפיגורציה זו, `pip install flask` ו-`pdm install flask` שניהם מסורבים עם הודעה המדריכה Claude להשתמש ב-`uv` או `bun` במקום. פקודות כגון `uv pip install flask` מותרות כי `uv` ברשימת ה-allowlist ובדוקה ראשונה. --- ## התנהגות AI -גלה כאשר סוכנים תקועים או מתנהגים בצורה בלתי צפויה. +זהה כאשר סוכנים תקועים או מתנהגים בצורה בלתי צפויה. ### `warn-repeated-tool-calls` -**Event:** PreToolUse (כל כלים) -**Default:** משנה את Claude להיעדר זימה כאשר אותו כלי נקרא 3 + פעמים עם פרמטרים זהים - סימן נפוץ שהסוכן תקוע בלופ. +**Event:** PreToolUse (כל הכלים) +**Default:** מדריך Claude להתחשב מחדש כאשר אותו כלי נקרא 3 פעמים או יותר עם פרמטרים זהים - סימן נפוץ לכך שהסוכן תקוע בלולאה. אין פרמטרים. @@ -721,39 +723,39 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ## זרימת עבודה -אכוף זרימת עבודה משומרת של סיום סשן. מדיניות אלה מופעלות על אירוע **Stop** וחוסמות את הסוכן מהפסקה עד שכל תנאי מתקיימים. הם עוקבים אחר שרשרת תלות טבעית: commit → push → PR → CI. אם מדיניות חוסמת, מדיניות מאוחרות יותר בשרשרת דלוקות (deny short-circuits). +כופה זרימת עבודה משקל בסוף הסשן. מדיניות אלה מופעלות על אירוע ה-**Stop** ומסרבות לסוכן מעצירה עד שכל תנאי מתקיימים. הם עוקבים אחרי שרשרת תלות טבעית: commit → push → PR → CI. אם מדיניות מסרבת, מדיניות מאוחרות יותר בשרשרת מדוללות (deny short-circuits). -כל מדיניות זרימת עבודה היא **fail-open**: אם הכלי הנדרש לא זמין (למשל `gh` לא מותקן, אין git remote), המדיניות מאפשרת עם הודעה מידע המסבירה מדוע הבדיקה דלוקה. +כל מדיניות זרימת עבודה היא **fail-open**: אם הכלי הנדרש אינו זמין (לדוגמה `gh` לא מותקן, אין git remote), המדיניות מתירה עם הודעה מידע המסבירה מדוע הבדיקה דווח שדלגה. -### Stop semantics לכל CLI +### סמנטיקה Stop לפי-CLI -אכיפת Stop נראית מעט שונה בין שישת CLIs הנתמכים כי לכל אחד יש חוזה hook שונה של סיום סוכן. התוצאה (**outcome**) זהה — הסוכן לא יוצא מהפסקה בזמן שדלת זרימת עבודה נכשלת — אך **המכניקה** שונה. הטבלה להלן מסכמת; רק Pi יש quirk נראה למשתמש ראוי להבנה לפני שתפעיל מדיניות `require-*-before-stop`. +אכיפת Stop נראית קצת שונה על פני ששת ה-CLIs הנתמכים כי לכל אחד חוזה hook "agent finished" שונה. **התוצאה** זהה — הסוכן לא יוכל להסתיר בעת עצירה עם שער זרימת עבודה נופל — אך ה-**מכניקה** שונה. הטבלה להלן מסכמת; רק Pi יש מוזרות גלויה למשתמש ששווה להבין לפני שתאפשר מדיניות `require-*-before-stop`. -| CLI | מתי השער מופעל | מה אתה רואה | +| CLI | כאשר השער מופעל | מה אתה רואה | |---|---|---| -| Claude Code | אותה לולאת סוכן, מיד | Claude ממשיך לעבוד — תיקונים הבעיה, ואז מנסה לסיים שוב. אין הפסקה גלויה לך. | -| Codex | אותה לולאת סוכן, מיד | זהה Claude. | -| GitHub Copilot CLI | אותה לולאת סוכן, מיד | זהה Claude (משתמש בערוץ ניסיון של Copilot `{decision:"block", reason}` — אומת אמפיראית נגד Copilot CLI 1.0.41). | -| Cursor Agent | אותה לולאת סוכן, מיד | זהה Claude (משתמש בערוץ `{followup_message}` של Cursor — מוגבל ל-`loop_limit`, ברירת מחדל 5 ניסיונות). | -| OpenCode | אותה לולאת סוכן, מיד | זהה Claude (משתמש בקריאה SDK של OpenCode `client.session.prompt(...)` מנותבת דרך `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **תור משתמש הבא** | **Pi חסום גלוי** כאשר השער מופעל — לולאת הסוכן שלו יוצאת והוחזרו ללאים. השער ואז מופעל את הפעם הבאה בה תגיש בקשה: failproofai הקדים directive `MANDATORY ACTION REQUIRED` למערכת prompt של התור ההוא, משנה את ה-LLM להשלים את שלב זרימת העבודה (commit, push, וכו') לפני לעשות מה שבקשת. | +| Claude Code | אותו לולאת סוכן, מיד | Claude ממשיך לעבוד — מתקן את הבעיה, ואז מנסה להסיים שוב. אין הפסקה גלויה לך. | +| Codex | אותו לולאת סוכן, מיד | זהה ל-Claude. | +| GitHub Copilot CLI | אותו לולאת סוכן, מיד | זהה ל-Claude (משתמש בערוץ ה-retry של Copilot `{decision:"block", reason}` — אומת באופן אמפירי נגד Copilot CLI 1.0.41). | +| Cursor Agent | אותו לולאת סוכן, מיד | זהה ל-Claude (משתמש בערוץ `{followup_message}` של Cursor — מוגבל ל-`loop_limit`, ברירת מחדל 5 retries). | +| OpenCode | אותו לולאת סוכן, מיד | זהה ל-Claude (משתמש ב-`client.session.prompt(...)` SDK call מנותב דרך `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **ההופעה הבאה של המשתמש** | **Pi עוצר בנראות** כאשר השער מופעל — לולאת הסוכן שלו יוצאת ואתה מוחזר להנחיה. השער ואז מופעל בפעם הבאה שאתה שולח הנחיה: failproofai מוקדים `MANDATORY ACTION REQUIRED` directive להנחיית המערכת של הסיבוב ההוא, מדריכה את ה-LLM להשלים את שלב זרימת העבודה (commit, push, וכו') לפני ביצוע כל מה שביקשת. | -**מגבלת Pi.** `AgentEndEvent` של Pi (המקבילה של ה-upstream של Claude's `Stop` hook) אין סוג Result — בזמן שזה מופעל, לולאת הסוכן של Pi כבר יצאה. Pi לא יכול להיאכף להקראות אותה לולאה כמו Claude / Copilot / Cursor / OpenCode יכול. failproofai משנה את השער לאירוע `before_agent_start` של Pi (שמופעל לאחר בקשת משתמש הבאה) כך בדיקת הזרימה עדיין אוכפת, רק בתור הבא במקום הנוכחי. +**Pi limitation.** Pi's `AgentEndEvent` (המקבילה של Claude `Stop` hook) אין סוג Result — בזמן שהוא מופעל, לולאת הסוכן של Pi כבר יצאה. Pi לא יכול להיכפף retry באותה לולאה בדרך ש-Claude / Copilot / Cursor / OpenCode יכול. failproofai מעביר את השער ל-`before_agent_start` event של Pi (אשר מופעל אחרי ההנחיה הבאה של המשתמש) כדי שבדיקת זרימת העבודה בעדיין אוכפת, רק בתור הבא במקום הנוכחי. -**מה זה אומר בפועל:** +**מה זה אומר בפרקטיקה:** -- לאחר Pi מפסיק, סיבת ה-deny נתפסת בזיכרון מונחה על ידי Pi session id. הבקשה הבאה בדיוק בה אתה מגיש בתור אותו Pi processes סוביה: ה-LLM רואה את directive `MANDATORY ACTION REQUIRED` בחלק העליון של system prompt שלו, commits (או pushes / פותח את PR / מחכה עבור CI), ורק אחר כך ממשיך עם הבקשה שלך. סיבת ה-deny שנתפסה היא one-shot — פעם סוביה, השער ברור. -- השער מוגבל על ידי lifetime התהליך של Pi. אם אתה `Ctrl+C` Pi או יוצא בין תורות, הרשומה בזיכרון מוטלת יחד עם התהליך והשער הוא miss. Claude, Copilot, Cursor, ו-OpenCode יש את אותו bound (להרוג את הסוכן והשער הוא miss) — Pi פשוט עושה את זה גלוי יותר כי הסוכן עוזב גלוי לפני השער. -- ה-deny תלוי גם מתוך ברור על `session_shutdown` בשום סיבה (`new` / `resume` / `fork` / `quit`), כך gate stale מתור קוד לא יכול דלוף לתור פרייש התחיל בתהליך אותו Pi. +- אחרי ש-Pi עוצר, הסיבה deny נתפסת בזיכרון המפתח לפי מזהה סשן Pi. ההנחיה ממש הבאה שאתה שולח באותו תהליך Pi מרוקן אותו: ה-LLM רואה את `MANDATORY ACTION REQUIRED` directive בחלק העליון של הנחיית המערכת שלו, commits (או pushes / פותח את ה-PR / מחכה ל-CI), ורק אחר כך ממשיך עם בקשתך. הסיבה deny שנתפסת היא one-shot — ברגע שמרוקן, השער ברור. +- השער תחום לאורך החיים של תהליך Pi. אם אתה `Ctrl+C` Pi או עוזב בין סיבובים, הכניסה בזיכרון מושלכת יחד עם התהליך והשער מחוזק. Claude, Copilot, Cursor, ו-OpenCode יש אותו קשור (הרוג את הסוכן והשער מחוזק) — Pi רק עושה אותו גלוי יותר כי הסוכן יוצא בנראות לפני שהשער מופעל. +- deny ממתין הוא גם ברור על `session_shutdown` לכל סיבה (`new` / `resume` / `fork` / `quit`), אז שער מיושן מתור ללא קודמים לא יכול לדלוף לתוך סשן טרי בתחילת אותו תהליך Pi. -אם אתה צריך Claude-סגנון אותו-לולאה ניסיון, הפעל את `Stop` מדיניות שלך תחת כל אחד מחמש CLIs נתמך. אנחנו עוקבים Pi upstream עבור עתידי Result סוג על `AgentEndEvent` שהיה לתן לנו לסגור את הפער זה. +אם אתה זקוק retry בסגנון Claude, הפעל את מדיניות ה-`Stop` שלך תחת אחד מחמשת ה-CLIs הנתמכים האחרים. אנחנו עוקבים מאחורי Pi upstream עבור סוג Result בעתיד על `AgentEndEvent` שיאפשר לנו לסגור את הפער הזה. ### `require-commit-before-stop` **Event:** Stop -**Default:** חוסם עצירה כאשר יש שינויים uncommitted (שונה, staged, או קבצים untracked). מחזיר הודעת מידע כאשר ספריית העבודה ברורה. +**Default:** מסרב עצירה כאשר יש שינויים לא committed (קבצים שונים, בבמה, או לא עוקב). מחזיר הודעת מידע כאשר ספריית העבודה נקייה. אין פרמטרים. @@ -762,15 +764,15 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `require-push-before-stop` **Event:** Stop -**Default:** חוסם עצירה כאשר יש commits unpushed או כאשר הענף הנוכחי אין remote tracking branch. מציע `git push -u` ליצור tracking branch אם נדרש. נכשל פתוח אם אין remote מוגדר. +**Default:** מסרב עצירה כאשר יש commits לא pushed או כאשר לענף הנוכחי אין ענף remote tracking. מציע `git push -u` ליצור ענף tracking במידת הצורך. נכשל פתוח אם אין remote מוגדר. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | שם remote לדחוף אליו. | +| `remote` | `string` | `"origin"` | שם remote לדחיפה אליו. | -**Example:** +**דוגמה:** ```json { @@ -787,14 +789,14 @@ namespace **`failproofai/`** — למשל, `failproofai/sanitize-jwt`. ה-namesp ### `require-pr-before-stop` **Event:** Stop -**Default:** חוסם עצירה כאשר אין pull request קיים לענף הנוכחי, או כאשר ה-PR הקיים סגור ללא merge. משנה את Claude ליצור PR עם `gh pr create`. כאשר ה-PR הוא **merged**, המדיניות מאפשרת (העבודה חיברה) והודעה רמזת להחליף ענף (`git checkout main && git pull`). +**Default:** מסרב עצירה כאשר אין pull request לענף הנוכחי, או כאשר ה-PR הקיים סגור ללא merge. מדריך Claude ליצור PR עם `gh pr create`. כאשר ה-PR **merged**, המדיניות מתירה (העבודה נישלחה) והודעה מרמזת להחליף את הענף (`git checkout main && git pull`). אין פרמטרים. -מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקן ומאומת. -הפעל `gh auth login` עם personal access token שיש לו `repo` scope לקריאה גישה ל- -pull requests. אם `gh` לא מותקן או לא מאומת, המדיניות נכשל פתוח ודיווח הסיבה ל-Claude. +מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקנת ו-authenticated. +הפעל `gh auth login` עם פולחן גישה אישי שיש לו `repo` scope לגישה קריאה ל- +pull requests. אם `gh` אינו מותקן או לא authenticated, המדיניות נכשלת פתוח ודיווח הסיבה ל-Claude. --- @@ -802,23 +804,22 @@ pull requests. אם `gh` לא מותקן או לא מאומת, המדיניות ### `require-no-conflicts-before-stop` **Event:** Stop -**Default:** חוסם עצירה כאשר הענף הנוכחי לא יכול לערבב בניקיון לענף הבסיס. המדיניות תחילה מאשרת יש `OPEN` PR ב-GitHub לענף — ללא אחד, אין merge target לאכיפה, כל המדיניות short-circuits לאפשר. פעם `OPEN` PR אושרה, שניים probes עצמאיים: +**Default:** מסרב עצירה כאשר הענף הנוכחי לא יכול להיות מוזג בנקיות לענף הבסיס. המדיניות תחילה מאשרת שיש `OPEN` PR על GitHub לענף — ללא אחד, אין merge target לאכיפה, כך הכל מדיניות short-circuits להתיר. ברגע שה-`OPEN` PR מאושר, שתי חוקרות עצמאיות: -1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. בסכסוך, ה-deny הודעה שמות הקבצים conflicted כך Claude יודע בדיוק מה לפתור. -2. **GitHub** — reuses את `gh pr view --json mergeable,state` תוצאה כבר fetched בה-precheck. תופסת סכסוכים stale המקומי `origin/` היה miss (למשל מישהו נחת conflicting PR ב-`main` מאז ה-last fetch). תוצאת `CONFLICTING` חוסמת. תוצאת `UNKNOWN` גם חוסמת משנה את Claude להמתין ~10 שניות ו-re-check לפני לנסות עצירה שוב — זה מונע false negatives בזמן GitHub recomputes. +1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. בהתנגשות, הודעת deny מתרים קבצים בהתנגשות כדי Claude יודע בדיוק מה לפתור. +2. **GitHub** — reuses ה-`gh pr view --json mergeable,state` תוצאה כבר נחפשה בתו-תק. תופסת התנגשויות שא-`origin/` מיושן מקומי היה להחמיץ (לדוגמה מישהו קמון PR בהתנגשות על `main` מאז הנחפש לאחרונה). תוצאה `CONFLICTING` מסרבת. תוצאה `UNKNOWN` גם מסרבת וממדריכה Claude להמתין ~10 שניות ובדוק מחדש לפני נסיון להפסיק שוב — זה מונע false negatives בזמן GitHub מחשבון מחדש. -דלוקות כלל בעת: `gh` לא מותקן, PR לא קיים לענף, ה-PR state לא `OPEN` (למשל `MERGED`, `CLOSED`), או `gh pr view` מחזיר unparseable פלט. גם נכשל פתוח כאשר `origin/` חסר locally או כאשר commits אין קדמה של בסיס — אלה Slayer 1 fall-throughs עדיין להתייעץ את ה-cached PR mergeability לפני יום. +דלג לחלוטין (מתיר) כאשר: `gh` אינו מותקן, אין PR לענף, מצב ה-PR אינו `OPEN` (לדוגמה `MERGED`, `CLOSED`), או `gh pr view` מחזיר פלט לא ניתן לניתוח. גם נכשל פתוח כאשר `origin/` חסר מקומי או כאשר אין commits קדמו לבסיס — אלה Fall-throughs Layer 1 עדיין יעון ל-PR mergeability cached לפני מתירה. -**Parameters:** +**פרמטרים:** | Param | Type | Default | Description | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | בסיס ענף לבדיקה סכסוכים נגד. | +| `baseBranch` | `string` | `"main"` | ענף בסיס לבדוק התנגשויות נגד. | -GitHub CLI (`gh`) נדרש למדיניות זו. המדיניות משתמשת `gh pr view` לאשר -`OPEN` PR קיים לפני הפעלת כל probe סכסוך — ללא `gh`, המדיניות -short-circuits לאפשר. הפעל `gh auth login` עם personal access token שיש לו +GitHub CLI (`gh`) נדרש למדיניות זו. המדיניות משתמשת ב-`gh pr view` לאישור PR `OPEN` קיים +לפני הפעלת כל חוקר התנגשות — ללא `gh`, המדיניות short-circuits להתיר. הפעל `gh auth login` עם פולחן גישה אישי שיש לו `repo` scope לקריאה גישה ל-pull requests. @@ -827,14 +828,14 @@ short-circuits לאפשר. הפעל `gh auth login` עם personal access token ### `require-ci-green-before-stop` **Event:** Stop -**Default:** חוסם עצירה כאשר בדיקות CI נוכשלות או עדיין רצות על הענף הנוכחי. בדוקות GitHub Actions זרימות עבודה וב-third-party bot בדיקות (למשל CodeRabbit, SonarCloud, Codecov). מתרגמות `skipped`, `cancelled`, ו-`neutral` מסקנות כ-non-failing (האחרונות מכסות למשל Socket Security alerts על ציבור חיצוני PRs, כאשר ה-app intentionally דיווחים neutral רמת success/failure). מחזירה הודעת מידע כאשר כל בדיקות לעבור. +**Default:** מסרב עצירה כאשר בדיקות CI נכשלות או עדיין פעולות בענף הנוכחי. בדוקות גם GitHub Actions זרימות עבודה וקבוצות bot צד שלישי (לדוגמה CodeRabbit, SonarCloud, Codecov). מעכל `skipped`, `cancelled`, ו-`neutral` סיכומים כלא-failing (זה האחרון מכסה לדוגמה Socket Security alerts על בחוץ תורם PRs, כאשר היישום בכוונה דיווח neutral בדל מהצלחה/כשל). מחזיר הודעת מידע כאשר כל בדיקות לעבור. אין פרמטרים. -מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקן ומאומת. -הפעל `gh auth login` עם personal access token שיש לו `repo` scope לקריאה גישה ל- -Actions זרימות עבודה רצות ו-Checks API. אם `gh` לא מותקן או לא מאומת, המדיניות נכשל פתוח ודיווח הסיבה ל-Claude. +מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקנת ו-authenticated. +הפעל `gh auth login` עם פולחן גישה אישי שיש לו `repo` scope לקריאה גישה ל- +Actions זרימות עבודה ו-Checks API. אם `gh` אינו מותקן או לא authenticated, המדיניות נכשלת פתוח ודיווח הסיבה ל-Claude. --- @@ -843,7 +844,7 @@ Actions זרימות עבודה רצות ו-Checks API. אם `gh` לא מותק ## השבתת מדיניות בודדות -הסר מדיניות ספציפית מ-`enabledPolicies` בתצורה שלך, או כבה אותה בכרטיסיית Policies של ה-dashboard. +הסר מדיניות ספציפית מ-`enabledPolicies` בקונפיגורציה שלך, או הדק אותה כבויה בלשונית Policies של לוח ההכל. ```json { @@ -854,4 +855,4 @@ Actions זרימות עבודה רצות ו-Checks API. אם `gh` לא מותק } ``` -מדיניות שלא רשומה ב-`enabledPolicies` לא רצות, גם אם ערכי `policyParams` קיימים עבורם. \ No newline at end of file +מדיניות לא רשומות ב-`enabledPolicies` לא פועלות, אפילו אם ערכי `policyParams` קיימים עבורן. \ No newline at end of file diff --git a/docs/he/cli/audit.mdx b/docs/he/cli/audit.mdx index 7ce3ef9d..40a614ca 100644 --- a/docs/he/cli/audit.mdx +++ b/docs/he/cli/audit.mdx @@ -1,23 +1,23 @@ --- ---- -title: 审计过去的会话 (beta) -description: "统计代理在过去的文字记录中执行浪费或风险操作的频率" +title: ביקורת של פגישות קודמות (בטא) +description: "ספור כמה פעמים הסוכן עשה דברים בזבזניים או מסוכנים על פני תנודות קודמות" --- - **Beta 功能。** 审计以 beta 版本发布，同时我们收集早期反馈。 - 检测器目录和报告格式在下一个稳定版本发布前可能会更改。如果您发现任何问题，请提交 issue。 + **תכונת בטא.** הביקורת משתלחת בבטא בזמן שאנו אוספים משוב מוקדם. + קטלוג הגלאי וקבוצת הדוח עשויים להשתנות לפני החתך היציב הבא. + אנא פתחו issue אם משהו נראה לא בסדר. -审计通过 failproofai 的策略引擎重放您过去的代理 CLI 文字记录，并在 **`/audit` 仪表板页面** 上呈现可共享的可视化报告 — 您的代理的原型、0–100 分数，以及具体哪些策略会捕获什么。 +הביקורת משחזרת את תנודות הסוכן-CLI הקודמות שלך דרך מנוע המדיניות של failproofai וביססת דוח חזותי וניתן לשיתוף בעמוד הדשבורד **`/audit`** — אַרכיטיפוס הסוכן שלך, ציון 0–100, והדיוק איזו מדיניות היתה לוכדת מה. -## 运行它 +## הפעל זאת -三种方式 — 都会转到同一个 `/audit` 报告。 +שלוש דרכים פנימה — כולן נוחתות באותה דוח `/audit`. -```bash npx (no install) +```bash npx (אין התקנה) npx -y failproofai audit ``` @@ -32,85 +32,96 @@ failproofai - - `npx -y failproofai audit` 获取 failproofai、运行扫描，并为您打开仪表板 — 无需事先安装任何内容。 + + `npx -y failproofai audit` משגרת את failproofai, מפעילה את הסריקה, ופותחת עבורך את הדשבורד — כלום להתקנה תחילה. - - `failproofai audit` 在终端中运行扫描，然后在完成时自动打开 `localhost:8020/audit`。 + + `failproofai audit` מפעילה את הסריקה בטרמינל שלך, ואז פותחת `localhost:8020/audit` באופן אוטומטי כאשר היא מסתיימת. - - 运行 `failproofai` 并在导航栏中点击 **Audit**（位于"策略"和"项目"之间），或直接打开 `/audit`。 + + הפעל את `failproofai` ולחץ על **Audit** בnavbar (בין Policies ו-Projects), או פתח `/audit` ישירות. - 运行 `failproofai audit -h`（或 `--help`）查看使用方法。审计 **完全离线运行** — 无需账户或网络 — 仪表板将一直提供服务，直到您用 `Ctrl+C` 停止它。 + הפעל את `failproofai audit -h` (או `--help`) כדי לראות שימוש. הביקורת מתריצה **לחלוטין במצב לא מקוון** — אין צורך בחשבון או רשת — והדשבורד ממשיך להשרת עד שתעצור זאת עם `Ctrl+C`. -仪表板扫描这台机器上的过去代理 CLI 文字记录（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi），并报告代理执行 failproofai 被构建用来阻止的操作的频率 — 环境变量检查、强制推送、冗余的 `cd ` 前缀、睡眠轮询循环、重新读取刚编辑的文件等。 +הדשבורד סורק תנודות סוכן CLI קודמות במכונה זו (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) ודיווח כמה פעמים הסוכן עשה דברים שfaiproofai בנוי כדי להפסיק — בדיקות env-var, דחיפות כפויות, `cd ` קידומות מיותרות, לולאות sleep-polling, קריאה מחודשת של קבצים שנערכו זה עתה, ועוד. -对于每个文字记录，每个工具使用事件都会通过 39 个内置策略 **以及** 8 个仅审计检测器重放，这些检测器捕获运行时策略尚未覆盖的模式。计数会跨所有会话按策略/检测器聚合。 +לכל תנודה, כל אירוע tool-use משוחזר דרך 39 מדיניות מובנות **וכן** דרך 8 גלאים שנועדו לביקורת בלבד שתופסות דפוסים שעדיין לא מכוסים על ידי מדיניות זמן ריצה. הספירות מצטברות למדיניות / גלאי על פני כל הפגישות. -## 您获得什么 +## מה אתה משיג -`/audit` 页面是一个单屏、可共享的 **海报**，后面跟着四个下方部分： +עמוד `/audit` הוא כרזה בחד-מסך וניתנת לשיתוף ואחריה ארבע סעיפים מתחת לקפל: -1. **海报** — 一览您的代理标识：其 **原型**（8 种之一 — `optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、其角色关键字、该原型的罕见程度，以及一个带等级带的 **0–100 分数**（`S` 到 `bottom tier`）。为了便于分享而构建 — 发布到 X 或 LinkedIn，或将其下载为 PNG。 -2. **`// strengths`** — 您的代理已经做得很好的地方，作为来自扫描的真实数字（例如 clean-tool-call %、`0` push-to-main 尝试），仅在相关策略有清晰记录的地方显示。 -3. **`// quirks`** — 滑过的内容：failproofai 会捕获的行为的排名表 — *最后发生的时间*、*滑过的内容*（以及会阻止它的内置程序）、其 *严重程度*，以及 *看到* 它的频率（`new` / `recurring` / `N× seen`）。 -4. **`// how to improve`** — 推荐的修复列表：每个策略一行，包含可复制粘贴的 `failproofai policy add `，加上一个 **install all** 按钮，可一次启用每项建议并显示您的 **projected score**。 -5. **`// come back better`** — 养成习惯：设置重新审计电子邮件 **提醒**（`3d` / `7d` / `14d` / `30d`）或立即重新审计，以及 **邀请朋友** 运行他们自己的审计（从 failproof.ai 发送，抄送给您）。提醒和邀请需要登录。 +1. **כרזה** — זהות הסוכן שלך במבט ראשון: שלו **אַרכיטיפוס** (אחד משמונה — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), מילות מפתח של הגוברנות שלו, כמה נדיר הוא הארכיטיפוס הזה, וציון **0–100** עם רצועת טיר (`S` עד `bottom tier`). בנוי לשיתוף — פרסום ל-X או LinkedIn, או הורדה כ-PNG. +2. **`// strengths`** — מה הסוכן שלך כבר עושה בצורה טובה, כמספרים אמיתיים מהסריקה (לדוגמה clean-tool-call %, `0` push-to-main attempts), מוצג רק כאשר למדיניות הרלוונטית יש רקורד נקי. +3. **`// quirks`** — מה התחמק: טבלה דורגת של התנהגויות שfaiproofai היתה לוכדת — *מתי* זה קרה לאחרונה, *מה התחמק* (והמובנה שהיתה חוסמת זאת), *חומרתו*, וכמה פעמים זה היה *נראה* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — רשימת התיקונים שנקבעו: שורה אחת למדיניות עם העתק-הדבק `failproofai policy add `, בתוספת כפתור **install all** המאפשר כל המלצה בבת אחת ומציג את **ציון ההשקעה** שלך אם עשית. +5. **`// come back better`** — בנה את ההרגל: הגדר **תזכורת** בדוא"ל לביקורת מחדש (`3d` / `7d` / `14d` / `30d`) או ביקורת מחדש עכשיו, והזמן **חבר** לביצוע הביקורת שלהם (שנשלחו מ-failproof.ai, Cc לך). תזכורות והזמנות דורשות כניסה. -## 计划审计 +## ביקורות מתוכננות -如果您运行 **failproofaid 守护进程**（请参阅 [`failproofai config`](/he/cli/install-policies)）， -它可以为您按计划重新运行审计，并在后台刷新 `/audit` 报告。 -它 **默认关闭**，因为扫描会读取这台机器上每个代理会话文字记录的 *内容* — 在您要求之前，没有任何内容在计时器上扫描。 +אם אתה מפעיל את **failproofaid daemon** (ראה [`failproofai config`](/he/cli/install-policies)), +הוא יכול להריץ את הביקורת עבורך בלוח זמנים ולרענן את דוח `/audit` +ברקע. זה **כבוי כברירת מחדל**, כי הסריקה קוראת את *התוכן* +של כל תנודת שיחת סוכן על מכונה זו — כלום לא סורק בטיימר +עד שתבקשו זאת. -在 `~/.failproofai/config.toml` 中将其打开： +הפעל זאת ב-`~/.failproofai/config.json` — הוסף את המפתח `audit` לצד +כל מה שהקובץ כבר מחזיק: -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` -| 键 | 含义 | +| מפתח | משמעות | |---|---| -| `auto` | `true` 启用计划扫描。任何其他内容 — 缺失、`false`、`"yes"` — 均为关闭。 | -| `interval_days` | 扫描之间的天数。限制为 1–90；`0`、负数或非数字返回默认值 `7`。 | +| `auto` | `true` מאפשר את הסריקה המתוכננת. כל דבר אחר — חסר, `false`, `"yes"` — כבוי. | +| `interval_days` | ימים בין סריקות. מהודק ל-1–90; `0`, שלילי או לא-מספר חוזרים ל-`7`. | -- 计划是 **挂钟时间**，所以它能在暂停和重启后继续：睡眠时间超过到期时间的笔记本电脑在唤醒时 **运行一次**，永远不会出现积压。 -- 每次运行都是一个独立的低优先级（`nice 19`）进程 — 永远不是守护进程的钩子路径，该路径保持空闲以响应工具调用。 -- 如果 `failproofai audit` 或仪表板的重新运行已在进行中，则会跳过扫描；此后不久会重试，而不是被视为失败。 -- 进度被写入 `~/.failproofai/state/audit-schedule.json`（上次运行、下次到期）。守护进程拥有该文件 — 在 `config.toml` 中更改节奏。 +- הלוח הזמנים הוא **wall-clock**, כך שהוא שורד השעיה והפעלה מחדש: מחשב נייד + שישן בעבר זמנו המוקצה מפעיל **פעם אחת** בעיר, אף פעם לא היסטוריית הצפייה. +- כל הפעלה היא תהליך נפרד, בעדיפות נמוכה (`nice 19`) — לעולם לא הנתיב של הhook של ה-daemon, הנשאר פנוי לתשובה לקריאות כלים. +- סריקה מדלגת אם `failproofai audit` או ה-re-run של הדשבורד כבר + בטיסה; זה נסיון שוב בקרוב במקום להתייחס כל כישלון. +- התקדמות נכתבת ל-`~/.failproofai/state/audit-schedule.json` (הפעלה אחרונה, + הבא עקב). ה-daemon שומר על הקובץ הזה — שנה את ה-cadence ב-`config.json`. -如果您在由较早版本的 failproofai 设置的机器上启用了此功能，请运行一次 `failproofai config`。守护进程的服务定义在启动 CLI 之前需要一个额外的条目，该刷新是该命令的一部分。 +אם הפעלת זאת במכונה שהוגדרה על ידי failproofai ישן יותר, הפעל +`failproofai config` פעם אחת. הגדרת השירות של ה-daemon צריכה ערך אחד נוסף +לפני שהוא יכול להשיק את ה-CLI, והרענון הוא חלק מהפקודה הזו. -## 仅审计检测器 +## גלאים שנועדו לביקורת בלבד -这些检测"愚蠢行为"模式，这些模式（尚）未在实时中执行。它们仅在审计期间运行，永远不会阻止实时工具调用。 +אלה מגלים דפוסי התנהגות "טיפשית" לא (עדיין) מחויבים בזמן אמת. הם מתריצים רק במהלך הביקורת ולעולם לא חוסמים שיחת כלי חי. -| 检测器 | 它计数的内容 | +| גלאי | מה הוא סוכם | |---|---| -| `redundant-cd-cwd` | 以 `cd && …` 开头的 Bash 命令，即使命令已在 `cwd` 中运行。 | -| `prefer-edit-over-read-cat` | 单个源文件上的 `cat`/`head`/`tail`/`less`/`more` — 使用 `Read` 工具。 | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` 就地编辑 — 使用 `Edit` 工具。 | -| `prefer-write-over-heredoc` | Heredoc / 多行 `echo > file` 写入文件 — 使用 `Write` 工具。 | -| `sleep-polling-loop` | 长 `sleep N`（≥ 30s）或 `while …; sleep …; done` 轮询循环。 | -| `find-from-root` | `find /`、`find /home`、`find /usr` 等 — 改为限制在 `cwd`。 | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`，跳过钩子。 | -| `reread-after-edit` | `Read` 在同一会话中刚刚被 `Edit`/`Write` 的文件。 | +| `redundant-cd-cwd` | פקודות Bash המתחילות ב-`cd && …` אף על פי שפקודות כבר מתריצות ב-`cwd`. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` בקובץ מקור יחיד — השתמש בכלי `Read`. | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` עריכות מקום — השתמש בכלי `Edit`. | +| `prefer-write-over-heredoc` | Heredoc / `echo > file` רב-שורה כתיבת קבצים — השתמש בכלי `Write`. | +| `sleep-polling-loop` | `sleep N` ארוך (≥ 30s) או `while …; sleep …; done` לולאות polling. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, וכו '. — היקף לתוך `cwd` במקום. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, דילוג על hooks. | +| `reread-after-edit` | `Read` של קובץ שהיה זה עתה `Edit`/`Write` באותו פגישה. | -## 缓存 +## מטמונים -- **按文字记录缓存** 位于 `~/.failproofai/cache/audit/.json`，由 `(mtime, size, engineVersion, detectorVersion)` 作为键 — 当文字记录或策略/检测器代码更改时自动失效。每个条目还存储一个 `cachedAt` 时间戳作为 **TTL 元数据**（不是缓存键的一部分）；超过 **7 天** 的条目在读取时被拒绝，以便长期结果不会超过不断演变的检测器意图。 -- **整体结果缓存** 位于 `~/.failproofai/audit-dashboard.json`（mode 0600）。让仪表板在导航时立即呈现，无需重新运行。在读取超过 **7 天 TTL** 时也会被拒绝 — `/audit` 然后下降到其空状态并提示进行新的运行。点击报告底部附近的 `[ re-audit now ]` 刷新 — 重新审计发送 `noCache: true`，因此它绕过按文字记录缓存并重新扫描每个文字记录，而不是返回缓存结果；运行通过粘性顶部条纹流式传输进度，并在成功时就地交换结果（无页面重新加载；失败的重新审计保留之前的报告）。 +- **מטמון לכל תנודה** ב-`~/.failproofai/cache/audit/.json` שנקבע על ידי `(mtime, size, engineVersion, detectorVersion)` — מבטל באופן אוטומטי כאשר תנודת או קוד מדיניות/גלאי משתנה. כל ערך מאחסן גם `cachedAt` חותמת זמן כ-**TTL metadata** (לא חלק ממפתח המטמון); ערכים ישנים יותר מ-**7 ימים** דחויים בקריאה כך שתוצאות חיות ארוכות לא עולות על כוונת גלאי מתפתחת. +- **מטמון תוצאה שלם** ב-`~/.failproofai/audit-dashboard.json` (מצב 0600). מאפשר לדשבורד לעבוד באופן מיידי בניווט ללא הפעלה מחדש. גם דחוי בקריאה בעבר **7-day TTL** — `/audit` ואז נופל ל-empty state שלו ודוחף לריצה טרייה. לחץ על `[ re-audit now ]` ליד תחתון הדוח כדי לרענן — ביקורת מחדש שולחת `noCache: true`, כךגלאה בערך ביקורת מחדש עוקפת את מטמון לכל-תנודה וסורקת כל תנודה שוב במקום להחזיר את התוצאה המטמונה; הריצה זורמת התקדמות דרך רצועת דבוקה עליונה וחילופי התוצאה במקום בהצלחה (לא טעינת עמוד; ביקורת מחדש שנכשלה שומרת על הדוח הקודם). -## 注意 +## הערות -- **无变动。** 审计以只读模式重放。`warn-repeated-tool-calls` 被跳过，因为其按会话的伴侣文件会被修改。 -- **工作流策略被跳过。** `require-*-before-stop` 策略仅在 `Stop` 事件和对实时 git 状态的 `execSync` 上触发 — 它们没有有意义的"2025 年会发生什么"解释，所以它们不会出现在审计计数中。 -- **自定义策略被跳过。** 用户提供的自定义钩子不会重放（它们自原始会话以来可能已更改）。 \ No newline at end of file +- **אין מוטציה.** הביקורת משחזרת במצב קריאה-בלבד. `warn-repeated-tool-calls` דלג כי הצד שלו לכל-פגישה יאופס אחרת. +- **מדיניות Workflow דלוגה.** מדיניות `require-*-before-stop` פעלה רק בגדולות `Stop` ו-`execSync` נגד מדינת ה-git החי — אין להם פירוש משמעותי של "מה היתה קורה בשנת 2025", כך שהם לא מופיעים בספירות הביקורת. +- **מדיניות מותאמת אישית דלוגה.** hooks מותאמים אישית שסופקו על ידי משתמש אינם משוחזרים (הם עשויים השתנו מאז הפגישה המקורית). \ No newline at end of file diff --git a/docs/he/cli/dashboard.mdx b/docs/he/cli/dashboard.mdx index d7ec97dc..bb0693f3 100644 --- a/docs/he/cli/dashboard.mdx +++ b/docs/he/cli/dashboard.mdx @@ -1,7 +1,7 @@ --- --- title: צפייה בהפעלות -description: "הפעל את לוח הבקרה לעיון בהפעלות סוכן וניהול מדיניויות" +description: "הפעל את לוח הבקרה לעיון בהפעלות של סוכנים וניהול מדיניות" --- ```bash @@ -14,15 +14,15 @@ failproofai | דגל | תיאור | |------|-------------| -| `--port ` | היציאה להאזנה (ברירת מחדל: `8020`) | -| `--allowed-origins ` | מארחים/כתובות IP מופרדות בפסיקים המורשות לגשת למשאבי פיתוח | +| `--port ` | הפורט להאזנה (ברירת מחדל: `8020`) | +| `--allowed-origins ` | כתובות/כתובות IP מופרדות בפסיקים שמורשות לגשת למשאבי פיתוח | -כדי להצביע על לוח הבקרה לתיקיית פרויקט Claude שאינה ברירת המחדל, הגדר את משתנה הסביבה `CLAUDE_PROJECTS_PATH` בעת ההפעלה. +כדי להצביע את לוח הבקרה לתיקייה פרויקט Claude שאינה ברירת המחדל, הגדר את משתנה הסביבה `CLAUDE_PROJECTS_PATH` בעת ההפעלה. ## דוגמאות ```bash -# הפעל ביציאה אחרת +# הפעל בפורט שונה failproofai --port 9000 # השתמש בנתיב פרויקטים Claude מותאם אישית דרך משתנה סביבה diff --git a/docs/he/cli/environment-variables.mdx b/docs/he/cli/environment-variables.mdx index 77ca196e..3d1b90b5 100644 --- a/docs/he/cli/environment-variables.mdx +++ b/docs/he/cli/environment-variables.mdx @@ -1,69 +1,70 @@ --- -title: משתנים סביבתיים -description: "הגדר את התנהגות failproofai באמצעות משתנים סביבתיים" +--- +title: משתנים סביבה +description: "הגדר את התנהגות failproofai באמצעות משתנים סביבה" --- -## לוח בקרה +## Dashboard -| משתנה | תיאור | +| Variable | Description | |----------|-------------| -| `PORT` | פורט לוח הבקרה (ברירת מחדל: `8020`) | -| `CLAUDE_PROJECTS_PATH` | שנה את המיקום שבו נמצאים תיקיות פרויקט Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | דפי לוח בקרה מופרדים בפסיקים להסתרה | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | hosts/IPs המורשים לגשת למשאבי פיתוח. זהה ל-`--allowed-origins`. | +| `PORT` | יציאת ה-Dashboard (ברירת מחדל: `8020`) | +| `CLAUDE_PROJECTS_PATH` | השתק את המיקום שבו נמצאים תיקיות פרויקטי Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | דפי Dashboard המופרדים בפסיקים להסתרה | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs המורשים לגישה למשאבי dev. זהה ל-`--allowed-origins`. | -## רישום ביומן +## Logging -| משתנה | תיאור | +| Variable | Description | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | רמת רישום השרת (ברירת מחדל: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | נתיב קובץ רישום hook מותאם אישית, או `true` לברירת מחדל (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | רמת יומן השרת (ברירת מחדל: `warn`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | נתיב קובץ יומן hook מותאם אישית, או `true` לברירת המחדל (`~/.failproofai/logs/hooks.log`) | -## טלמטריה +## Telemetry -failproofai מדווח על טלמטריית שימוש אנונימית כברירת מחדל. יש שתי דרכים -להשבית זאת, והן מפתרות לפי מה שהוא מגביל יותר — משתנה סביבתי לא יכול -לעולם להפעיל מחדש משהו שקובץ קונפיגורציה השבית. +failproofai משדר טלמטריה שימוש אנונימית כברירת מחדל. יש שתי דרכים כדי +לכבות זאת, והן מתפרשות לפי המגביל יותר — משתנה סביבה לא יכול לעולם להפעיל מחדש משהו שקובץ התצורה כיבה. -| משתנה | תיאור | +| Variable | Description | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | השבת טלמטריית שימוש אנונימית לתהליך זה | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | בטל טלמטריה שימוש אנונימית לתהליך זה | -כדי להשבית זאת באופן קבוע עבור המכונה, הוסף זאת ל-`~/.failproofai/config.toml`: +כדי להשבית זאת באופן קבוע עבור המכונה, הוסף זאת ל-`~/.failproofai/config.json`: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -קובץ הקונפיגורציה הוא האפשרות להשתמש אם אתה מריץ את **שרת failproofaid**. -השרת הוא שירות בסקופ מערכת, וסביבתו אינה כוללת משתנים שיוצאו מהשל שלך — אז `FAILPROOFAI_TELEMETRY_DISABLED` לא יכול -להגיע אליו. `[telemetry] enabled = false` נקרא גם על ידי CLI וגם על ידי השרת. +קובץ התצורה הוא האפשרות לשימוש אם אתה מריץ את ה-**failproofaid daemon**. +ה-daemon הוא שירות בהיקף מערכת, והסביבה שלו אינה כוללת +משתנים המיוצאים מה-shell שלך — כך ש-`FAILPROOFAI_TELEMETRY_DISABLED` לא יכול +להגיע אליו. `[telemetry] enabled = false` נקרא הן על ידי ה-CLI והן על ידי ה-daemon. -השרת מדווח על **מחזור חיים** משלו בלבד: שהוא התחיל (ואם ההפעלה הקודמת סיימה בצורה נקייה), שהוא עצר, כאשר סדן הערכה שלו -נוצר או הופעל מחדש, כאשר משימת אוסף נכשלה, ותוצאה של -משיכת מדיניות ענן. אלה נושאים ערכים בעלי קרדינליות נמוכה וספירות — לעולם לא נתיב קובץ, פקודה, מדיניות, הנמקה, או משהו -שנקרא מתוך תמלול. אין אירוע לכל קריאת כלי. +ה-daemon משדר את **lifecycle** שלו בלבד: שהוא התחיל (ואם ההרצה הקודמת יצאה בנקיון), שהוא עצר, מתי ה-evaluation worker שלו נוצר או הופעל מחדש, מתי משימת collector נכשלה, וההשלכה של pull של cloud-policy. אלה נושאים ערכים בעלי cardinality נמוך וספירות — לעולם לא נתיב קובץ, פקודה, מדיניות, prompt, או כל דבר שנקרא מתוך שנייה. אין אירוע לכל קריאת כלי. -## אימות +## Authentication -| משתנה | תיאור | +| Variable | Description | |----------|-------------| -| `FAILPROOF_API_URL` | שנה את URL הבסיס של שרת ה-API שבו משתמש דיאלוג אימות לוח הבקרה. ברירת מחדל היא `https://api.befailproof.ai`; הגדר ל-`http://localhost:8080` (או למקום אחר) בעת הפעלת שרת api מקומי. | -| `FAILPROOFAI_AUTH_DIR` | שנה היכן מאוחסן `auth.json` (ברירת מחדל: `~/.failproofai`). שימושי בעיקר לבדיקות מבודדות. | +| `FAILPROOF_API_URL` | השתק את כתובת URL הבסיס של api-server בה השתמש דיאלוג auth של ה-Dashboard. ברירת מחדל ל-`https://api.befailproof.ai`; הגדר ל-`http://localhost:8080` (או במקום אחר) בעת הרצת api-server מקומי. | +| `FAILPROOFAI_AUTH_DIR` | השתק את המיקום שבו מאוחסן `auth.json` (ברירת מחדל: `~/.failproofai`). שימושי בעיקר לבדיקות מבודדות. | -## הנמקה בהפעלה ראשונה +## First-run prompt -| משתנה | תיאור | +| Variable | Description | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | דלג על ההנמקה המציעה להתקין מדיניויות בהזעקה ראשונה של failproofai | +| `FAILPROOFAI_NO_FIRST_RUN=1` | דלג על ה-prompt המציע להתקין מדיניויות בהפעלה הראשונה של `failproofai` בלבד | -## LLM (לצורך הערכת מדיניות) +## LLM (for policy evaluation) -| משתנה | תיאור | +| Variable | Description | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | נקודת קצה API של LLM (ברירת מחדל: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | מפתח API למדיניויות מופעלות LLM | -| `FAILPROOFAI_LLM_MODEL` | שם המודל (ברירת מחדל: `gpt-4o-mini`) | \ No newline at end of file +| `FAILPROOFAI_LLM_BASE_URL` | נקודת קצה של LLM API (ברירת מחדל: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | מפתח API עבור מדיניויות מופעלות LLM | +| `FAILPROOFAI_LLM_MODEL` | שם מודל (ברירת מחדל: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/he/cli/hook.mdx b/docs/he/cli/hook.mdx index 19cb19c5..61123b71 100644 --- a/docs/he/cli/hook.mdx +++ b/docs/he/cli/hook.mdx @@ -1,30 +1,31 @@ --- -title: Hook handler (internal) -description: "תת-תהליך שClaude Code קוראה בכל אירוע כלי" +--- +title: מטפל ה-Hook (פנימי) +description: "תהליך משנה שה-Claude Code קורא בכל אירוע כלי" --- ```bash failproofai --hook ``` -זה הפקודה שנרשמת ב-`settings.json` של Claude Code על ידי `failproofai policies --install`. בדרך כלל אתה לא קורא לזה ישירות. +זהו הפקודה המרשמת ב-`settings.json` של Claude Code על ידי `failproofai policies --install`. בדרך כלל אתה לא קורא לזה ישירות. -קוראה JSON payload מ-stdin, מעריכה את כל הפוליסיות המופעלות, ויוצאת עם קוד המציין את ההחלטה: +קורא עומס JSON מ-stdin, מעריך את כל המדיניויות המאופשרות, ויוצא עם קוד המציין את ההחלטה: | קוד יציאה | החלטה | השפעה | -|-----------|--------|--------| +|-----------|---------|--------| | `0` | `allow` | אפשר את הפעולה | -| `1` | `deny` | חסום את הפעולה - Claude יראה את סיבת הדחייה | -| `2` | `instruct` | הזרק הנחיות להקשר של Claude | +| `1` | `deny` | חסום את הפעולה - Claude רואה את הסיבה לדחיה | +| `2` | `instruct` | הזן הנחיות להקשר של Claude | ### סוגי אירועים נתמכים | קטגוריה | אירועים | -|----------|--------| +|----------|---------| | **ביצוע כלים** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | -| **מחזור חיי הסשן** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | -| **אינטראקציה עם המשתמש** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **תת-אגנטים ומשימות** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **מחזור חיי ההפעלה** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | +| **אינטראקציה עם משתמש** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | +| **תת-סוכנים ומשימות** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **תצורה** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | -| **מערכת קבצים** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | +| **מערכת הקבצים** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **הקשר** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/he/cli/install-policies.mdx b/docs/he/cli/install-policies.mdx index 722e048a..8b78dc0b 100644 --- a/docs/he/cli/install-policies.mdx +++ b/docs/he/cli/install-policies.mdx @@ -1,14 +1,14 @@ --- --- -title: התקנת מדיניויות -description: "הפעל מדיניויות כך שהן יפעלו בכל קריאת כלי סוכן" +title: התקנת מדיניות +description: "הפעל מדיניות כך שתרוצנה בכל קריאת כלי של agent" --- ```bash failproofai policies --install [policy-names...] [options] ``` -כותב ערכי hook לתוך קובץ ההגדרות של ממשק ה-CLI המותקן שלך (Claude Code, OpenAI Codex, או GitHub Copilot CLI _(beta)_) כך ש-failproofai יחתוך קריאות כלים. +כותב ערכי hook לקובץ ההגדרות של ה-CLI של agent שהותקן (Claude Code, OpenAI Codex, או GitHub Copilot CLI _(beta)_) כך ש-failproofai יוכל להטות קריאות כלים. כינויים: `failproofai p -i` @@ -16,43 +16,43 @@ failproofai policies --install [policy-names...] [options] | דגל | תיאור | |------|-------------| -| `--cli claude\|codex\|copilot` | ממשקי CLI של סוכן להתקנה עבורם; מופרדים ברווח (למשל `--cli claude codex copilot`) או חוזרים על עצמם. השמט כדי לזהות ממשקי CLI מותקנים ולהנחות. | -| `--scope user` | התקן לתוך קובץ הגדרות בהיקף משתמש (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). ברירת המחדל. | -| `--scope project` | התקן לתוך קובץ הגדרות בהיקף פרויקט (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Claude בלבד — התקן לתוך `/.claude/settings.local.json`. ל-Codex ול-Copilot אין היקף `local`. | -| `--custom ` / `-c` | נתיב לקובץ JS המכיל מדיניויות hook מותאמות אישית | +| `--cli claude\|codex\|copilot` | CLI של agent להתקנה; מופרדים בתווי רווח (לדוגמה `--cli claude codex copilot`) או חוזרים. השמט כדי לחפש CLI מותקנים ודרוג. | +| `--scope user` | התקן לקובץ ההגדרות בהיקף משתמש (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). ברירת מחדל. | +| `--scope project` | התקן לקובץ ההגדרות בהיקף פרויקט (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Claude בלבד — התקן ל-`/.claude/settings.local.json`. ל-Codex ול-Copilot אין היקף `local`. | +| `--custom ` / `-c` | נתיב לקובץ JS המכיל מדיניות hook מותאמות | ## התנהגות -- **ללא שמות מדיניויות** - פותח הנחיה אינטראקטיבית לבחירת מדיניויות -- **שמות ספציפיים** - מפעיל את המדיניויות הללו (מתווסף לכל המדיניויות שכבר מופעלות) +- **ללא שמות מדיניות** - פותח דרוג אינטראקטיבי לבחירת מדיניות +- **שמות ספציפיים** - מפעיל את אותן מדיניות (מוסיף לכל כבר מופעלות) - **`all`** - מפעיל כל מדיניות זמינה -התקנה היא צבירתית: הפעלת `--install` שוב תוסיף מדיניויות חדשות ללא הסרת קיימות. +התקנה היא תוספתית: הפעלת `--install` שוב מוסיפה מדיניות חדשות ללא הסרת קיימות. ## דוגמאות ```bash -# התקן את כל המדיניויות ברירת המחדל בעולם (אינטראקטיבי) +# התקן את כל המדיניות המובנות בעולם (אינטראקטיבי) failproofai policies --install -# התקן מדיניויות ספציפיות עבור הפרויקט הנוכחי +# התקן מדיניות ספציפיות לפרויקט הנוכחי failproofai policies --install block-sudo sanitize-api-keys --scope project -# הפעל את כל המדיניויות בבת אחת +# הפעל את כל המדיניות בבת אחת failproofai policies --install all -# התקן עם קובץ מדיניויות מותאם אישית +# התקן עם קובץ מדיניות מותאם failproofai policies --install --custom ./my-policies.js # התקן עבור OpenAI Codex (היקף פרויקט) failproofai policies --install --cli codex --scope project -# התקן עבור GitHub Copilot CLI (beta) עבור הפרויקט הנוכחי +# התקן עבור GitHub Copilot CLI (beta) לפרויקט הנוכחי failproofai policies --install --cli copilot --scope project -# התקן עבור כל שלושת ממשקי ה-CLI בבת אחת +# התקן עבור שלושת ה-CLI בו זמנית failproofai policies --install --cli claude codex copilot ``` -כאשר `--custom ` מסופק, הקובץ מאומת מיד - עליו להפעיל את `customPolicies.add()` לפחות פעם אחת. הנתיב המוקל נשמר ל-`policies-config.json` כ-`customPoliciesPath`. \ No newline at end of file +כאשר `--custom ` מסופק, הקובץ מאומת מיד - עליו לקרוא ל-`customPolicies.add()` לפחות פעם אחת. הנתיב שפתרנו נשמר ל-`policies-config.json` כ-`customPoliciesPath`. \ No newline at end of file diff --git a/docs/he/cli/list-policies.mdx b/docs/he/cli/list-policies.mdx index 15909103..78e05101 100644 --- a/docs/he/cli/list-policies.mdx +++ b/docs/he/cli/list-policies.mdx @@ -1,16 +1,16 @@ --- --- title: רשימת מדיניויות -description: "ראה אילו מדיניויות מופעלות, הפרמטרים שלהן, ומדיניויות מותאמות אישית" +description: "ראה אילו מדיניויות מופעלות, הפרמטרים שלהן ומדיניויות מותאמות" --- ```bash failproofai policies ``` -מציג את כל המדיניויות עם הסטטוס שלהן, הפרמטרים המוגדרים, והמדיניויות המותאמות אישית. +מציג את כל המדיניויות עם הסטטוס שלהן, הפרמטרים המוגדרים והמדיניויות המותאמות. -## דוגמה לפלט +## דוגמה פלט ```text Failproof AI Hook Policies (user) @@ -29,4 +29,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -מפתחות לא ידועים ב־`policyParams` מסומנים כאן כדי שתוכל לתפוס שגיאות הקלדה מוקדם. \ No newline at end of file +מפתחות לא ידועים ב-`policyParams` מודגשים כאן כדי שתוכל לתפוס שגיאות הקלדה מוקדם. \ No newline at end of file diff --git a/docs/he/cli/migrate.mdx b/docs/he/cli/migrate.mdx new file mode 100644 index 00000000..0ba47548 --- /dev/null +++ b/docs/he/cli/migrate.mdx @@ -0,0 +1,86 @@ +--- +title: העברת ספריית הבית +description: "העבר את ~/.failproofai לפריסה שהגרסה הזו מדברת, וראה קודם מה היה קורה" +--- + +```bash +failproofai migrate --dry-run # print the plan, change nothing +failproofai migrate # run it +``` + +רוב האנשים לא מקלידים זאת. זה רץ בעצמו בפקודה הראשונה אחרי שדרוג, ו-[`failproofai update`](/he/cli/update) כולל אותו. השתמש בו ישירות כשאתה רוצה לראות את התכנית לפני שזה קורה, או להפעיל את ההעברה בעצמה. + +## מפתח על הפריסה, לא על הגרסה + +`~/.failproofai/VERSION` רושם מספר **פריסה** — צורת הספרייה, לא ההוצאה שכתבה אותה. העברות מפתחות על המספר הזה, וזה מה שהופך פער ארוך לזול: + +- גרסאות npm משתנות בכל הוצאה, עשרות ביניהן בין שתי פריסות. +- אז מכונה שמדלגת על שלוש עשרה הוצאות עם **ללא שינוי בפריסה** מפעילה **אפס** העברות, לא שלוש עשרה פעולות ריקות. +- ומכונה שמדלגת על מספר פריסות בבת אחת מפעילה כל צעד לפי הסדר, וכל צעד יודע רק את שני הקצוות שלו. + +זה חשוב כי npm לא יכול לעדכן חבילה מותקנת בעצמה. מכונה שישבה על גרסה אחת חודשים וגם קפצה על מספר פריסות זה המקרה הנורמלי, לא זה האקזוטי. + +## ההרצה היבשה + +`--dry-run` מדפיס את השרשרת המדויקת והקבצים שישמרו קודם לכן, ולא משנה כלום כלל — ללא העברה, ללא גיבוי, ללא ערך רישום: + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## מה נשמר ומה בנוי מחדש + +כל נתיב בבית מכריז איזה סוג נתונים הוא מחזיק, וזה מחליט אם העברה רשאית להשליך אותו. הכלל: **נגזר וקריא-להביא מחדש אולי להישמט; כל דבר שהקלדת, כל דבר שעדיין לא הועבר, וכל דבר שזיהה את המכונה נשמר.** + +| נשמר | בנוי מחדש או מובא מחדש | +|---|---| +| `config.json` — הגדרות, `daemon.configured`, נתיבי לכידה נוספים | זיכרון המטמון של הביקורת | +| `credentials.json` — הרישום בענן שלך | פריסות מנוהלות בענן (מובאות מחדש ואומתות על סכום קיבולי בסקר הבא) | +| `policies-config.json` — בחירת המדיניות שלך ופרמטרים | מצב תקליטון Daemon | +| `policies/` — קבצי המדיניות שלך והעוזרים שהם מייבאים | | +| `hook-activity/` — יומן ההחלטות שלוח המחוונים קורא | | +| אירועים שלא הועברו עדיין בתור לעלאות | | +| `cursors/` — סימני מים של אספן | | +| הקובץ הבינארי של daemon ב-`bin/` | | + + + אירועים שלא הועברו נשמרים ולא משולכים כי ההפסד יהיה קבוע, לא איטי: סימן המים של האספן כבר התקדם עבר הכל היושב בספול, אז כלום לא יקרא שוב טווח הזה של תמליל. ההעברה גם מבקשת מה-daemon להעביר את מה שנמצא בספול ברגע שהוא מסתיים, אז התוצאה הרגילה היא שאין כלום להשמר. + + +מפתחות שגרסה **חדשה יותר** כתבה ל-`config.json`, `credentials.json` או `policies-config.json` נשמרים גם כן, ולא משולכים על ידי קורא ישן יותר. + +## הרשומה שהוא משאיר + +``` +~/.failproofai/migrations/ + applied.json ערך אחד לכל צעד: פריסה, CLI, חתימת זמן, משך, תוצאה + backup-layout/ עותקים של הקבצים שלא ניתן להחליפם, שצולמו לפני הצעד הראשון +``` + +`applied.json` זה מה שענה על זה אמיתי עבר המכונה — השאלה הראשונה שכדאי לשאול כשמשהו נראה לא בסדר אחרי שדרוג. צרף אותו לדוח באג. + +הגיבוי קטן בכוונה ולא עותק של כל הספרייה: ההעברה כבר לא מוחקת כל דבר שלא ניתן להחליפו בעיצוב, אז מה שכדאי להבטיח נגדו היא **פגם בצעד**, וקבצים מעטים אלו הם המקום שבו פגם כזה יפגע. + +## אם צעד נכשל + +השרשרת עוצרת שם. `VERSION` חתום רק על ידי צעד שהושלם, אז הבית נשאר מסומן עם הפריסה הישנה שלו והפקודה הבאה חוזרת עליו — בית לא מסומן כעדכני על כוח של העברה חלקית. הצעד רשום ב-`applied.json` עם `"ok": false`, והגיבוי הוא המקום שבו הוא צולם. + +## בית חדש יותר סרוב, לא מהעבר + +אם `~/.failproofai/` נכתב על ידי **חדש יותר** failproofai מהאחד שאתה מפעיל, הפקודה עוצרת ואומרת לך לשדרג במקום. הנתונים האלו בסדר וקריא CLI חדש יותר אותם; ההעברה לפני אחורה מהם לא קיימת, ואיפוס היא הרסה משהו קריא. + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +ה-daemon מחיל את אותו הכלל: `failproofaid` סורב להתחיל נגד פריסה שהוא לא מדבר, במקום לקרוא ולכתוב נתיבים שזינחו. \ No newline at end of file diff --git a/docs/he/cli/remove-policies.mdx b/docs/he/cli/remove-policies.mdx index 7496f204..bc2c6f47 100644 --- a/docs/he/cli/remove-policies.mdx +++ b/docs/he/cli/remove-policies.mdx @@ -1,14 +1,14 @@ --- --- title: הסרת מדיניות -description: "הסר ערכי hook מהגדרות Claude Code" +description: "הסרת רשומות hook מהגדרות Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -מסיר ערכי failproofai hook מ-`settings.json` של Claude Code. +מסיר רשומות hook של failproofai מקובץ `settings.json` של Claude Code. כינויים: `failproofai p -u` @@ -19,24 +19,24 @@ failproofai policies --uninstall [policy-names...] [options] | `--scope user` | הסר מהגדרות גלובליות (ברירת מחדל) | | `--scope project` | הסר מהגדרות הפרויקט | | `--scope local` | הסר מהגדרות מקומיות | -| `--scope all` | הסר מכל ההיקפים בו-זמנית | -| `--custom` / `-c` | נקה את `customPoliciesPath` מהתצורה | +| `--scope all` | הסר מכל ההיקפים בו זמנית | +| `--custom` / `-c` | נקה את `customPoliciesPath` מתצורה | ## התנהגות -- **ללא שמות מדיניות** - מסיר את כל ערכי failproofai hook מקובץ ההגדרות -- **שמות ספציפיים** - מכבה מדיניות אלה אך משאיר hooks מותקנים +- **ללא שמות מדיניות** - מסיר את כל רשומות ה-hook של failproofai מקובץ ההגדרות +- **שמות ספציפיים** - משבית מדיניות אלה אך שומר על hook-ים מותקנים ## דוגמאות ```bash -# הסר את כל ה-hooks באופן גלובלי +# הסר את כל ה-hooks בעולמי failproofai policies --uninstall -# כבה מדיניות ספציפית (שמור hooks מותקנים) +# השבת מדיניות ספציפית (שומר hook-ים מותקנים) failproofai policies --uninstall block-sudo -# הסר hooks מכל היקף +# הסר hook-ים מכל היקף failproofai policies --uninstall --scope all # נקה את נתיב המדיניות המותאמות diff --git a/docs/he/cli/update.mdx b/docs/he/cli/update.mdx new file mode 100644 index 00000000..75525032 --- /dev/null +++ b/docs/he/cli/update.mdx @@ -0,0 +1,91 @@ +--- +title: עדכון לאחר שדרוג +description: "סיימו את החצי השני של שדרוג שה־npm לא יכול לעשות: העברו את הבית והתאימו את ה־daemon" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +זה כל השדרוג. `npm` מחליף את ה־CLI; `failproofai update` עושה +את השאר. + +## מדוע קיימת פקודה שנייה + +`npm install -g` מחליף דבר אחד — את ה־CLI. שני חלקים נוספים של התקנת failproofai +נמצאים מחוץ לחבילה בכוונה, ואף אחד מהם לא ינוע כאשר npm פועל: + +- **`~/.failproofai/`**, ההגדרות שלכם, רישום בענן, בחירת מדיניות והיסטוריה. גרסה + חדשה עשויה לארגן זאת אחרת, והארגון מחדש צריך להיעשות על ידי קוד שמכיר שני + הצורות. +- **Binary ה־daemon של `failproofaid`**, ב־ + `~/.failproofai/bin/failproofaid-`. זה בכוונה *לא* בתוך + `node_modules`: שדרוג שהחליף את הקובץ תחת שירות פעיל היה מצביע daemon חי לבינארי + שנבנה משורס שונה, והסרת החבילה הייתה מוחקת אותו מתחת לשירות שלאחר מכן מתרסק בכל + אתחול. + +אז לאחר `npm install -g` לבדו, ה־CLI חדש והדdaemon אינו. +`failproofaid` מסרב להתחיל כנגד פריסת בית שהוא לא מדבר — הגרסה הרמה של +ההתאמה הזו בניגוד לשתיקה — אז יש להביא את שני החלקים ביחד. `failproofai update` +הוא אותו שלב. + +## מה הוא עושה + + + + קורא את הפריסה המתועדת ב־`~/.failproofai/VERSION` ומריץ את השלבים שמביאים אותה לזו שגרסה זו מדברת. בדרך כלל אף אחד — ראו + [`failproofai migrate`](/he/cli/migrate). + + + מחבילת הפלטפורמה שה־npm כבר הורידה כאשר אפשר (אין רשת), + אחרת מנכס השחרור עבור גרסה זו בדיוק, מאומת SHA-256 + לפני שהוא בשימוש. + + + חקור במקום להניח — מנהל שירות דיווח על תהליך פעיל ברגע שהוא מתפצל, שזה לא + אותו דבר כמו שהוא עובד. + + + +## אפשרויות + +| דגל | אפקט | +|------|--------| +| `--no-daemon` | העברו את הבית בלבד, משאירים את ה־daemon בגרסתו הנוכחית. | + + + `--no-daemon` משאיר daemon משופע-גרסה במקום. על מכונה המוגדרת + לדרוש את ה־daemon, כל אירוע hook **נכשל סגור** אם ה־daemon לא יכול + להשיב — וdaemon שמסרב להתחיל כנגד בית שהועבר לא יכול להשיב. עדיפו + להשאיר את חצי ה־daemon לרוץ. + + +## אם משהו הולך לא כן + +הפקודה יוצאת מ־non-zero ואומרת איזה חצי כשל. שני מקרים שכדאי לדעת: + +- **שלב הגדרה לא סיים.** הבית נשאר מסומן בפריסה שלו *הישנה*, + אז הפקודה הבאה משנה ניסיון — לא בית מעולם מסומן כעדכני על כוחו של + הגדרה חלקית. עותקים של ההגדרות והרישום שלכם נשמרו + לפני שום דבר הרץ, ב־`~/.failproofai/migrations/backup-layout/`. +- **ה־daemon לא יכול היה להיות בעל הנתיבים מחדש ללא סיסמה.** `sudo -n` בשימוש + בכוונה, ולכן שום דבר אף פעם לא מעלה מתוך תצוגת התקדמות. הפקודה מדפיסה + את השורה המדויקת שתרוצו בעצמכם. + + + שום דבר כאן לא צריך את אשף ההתקנה האינטראקטיבי. ההגדרות, רישום הענן שלכם + ובחירת המדיניות שורדים שדרוג, אז מכונה שהועברה אוכפת בדיוק כמו בעבר — שחשוב הכי על המכונות עם + אף אחד לא יושב בהם: ריצת CI, קופסת צי, שער ללא ראש. + + +## אוטומציה שלו + +`failproofai update` אינו אינטראקטיבי ובטוח לריצה כאשר אין שום דבר לעשות — +זה דיווחים "לא הייתה צורך בהגדרה" ויוצא 0. הכנסת אותו אחרי כל +שדרוג בתסריט הספקה או Dockerfile הוא השימוש המיועד: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` בבנייה של תמונה, שם אין שירות להפעיל מחדש עדיין.) \ No newline at end of file diff --git a/docs/he/cli/version.mdx b/docs/he/cli/version.mdx index e862f196..803d4efd 100644 --- a/docs/he/cli/version.mdx +++ b/docs/he/cli/version.mdx @@ -1,7 +1,7 @@ --- --- -title: בדוק גרסה -description: "הדפס את גרסת failproofai המותקנת" +title: בדיקת הגרסה +description: "הדפסת גרסת failproofai המותקנת" --- ```bash @@ -10,4 +10,4 @@ failproofai --version failproofai -v ``` -הדפס את מספר הגרסה המותקנת. \ No newline at end of file +הדפסת מספר הגרסה המותקנת. \ No newline at end of file diff --git a/docs/he/configuration.mdx b/docs/he/configuration.mdx index a1efcac1..924f02c1 100644 --- a/docs/he/configuration.mdx +++ b/docs/he/configuration.mdx @@ -1,26 +1,27 @@ --- -title: הגדרות -description: "פורמט קובץ תצורה, מערכת שלוש-ההיקפים, וכללי ההיזוגה" +--- +title: תצורה +description: "פורמט קובץ התצורה, מערכת שלוש-ההיקפים, וכללי המיזוג" icon: gear --- -failproofai משתמש בקבצי תצורה JSON כדי לשלוט איזו מדיניות פעילה, כיצד היא מתנהגת, ומאיפה מדיניות מותאמת אישית נטענת. התצורה תוכננה להיות קלה לשיתוף עם הצוות שלך - בצע commit אל הריפו שלך וכל מפתח יקבל את אותה רשת ביטחון לאירוח. +failproofai משתמש בקובצי תצורה JSON כדי לשלוט אילו מדיניות פעילות, כיצד הן מתנהגות, ומהיכן מדיניות מותאמת אישית נטענת. התצורה מעוצבת להיות קלה לשיתוף עם הצוות שלך - התחיל אותה במאגר ודבר-אחד כל פיתוח מקבל את אותה רשת בטיחות עבור סוכן. --- -## היקפי התצורה +## היקפי תצורה -יש שלוש היקפי תצורה, המוערכות לפי סדר עדיפויות: +ישנם שלוש היקפי תצורה, המוערכים לפי סדר עדיפות: -| היקף | נתיב קובץ | מטרה | +| Scope | File path | Purpose | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | הגדרות לפי ריפו, committed לשליטה בגרסה | -| **local** | `.failproofai/policies-config.local.json` | דריסות אישיות לפי ריפו, gitignored | +| **project** | `.failproofai/policies-config.json` | הגדרות לכל מאגר, מחויבות לבקרת גרסה | +| **local** | `.failproofai/policies-config.local.json` | דריסות אישיות לכל מאגר, מנוכות מ-git | | **global** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת משתמש בכל הפרויקטים | -כאשר failproofai מקבל אירוע hook, הוא טוען ומזגג את כל שלושת הקבצים שקיימים עבור ספריית העבודה הנוכחית. +כאשר failproofai מקבל אירוע hook, הוא טוען ומשלב את כל שלושת הקובצים שקיימים עבור ספריית העבודה הנוכחית. -### כללי ההיזוגה +### כללי המיזוג **`enabledPolicies`** - האיחוד של כל שלושת ההיקפים. מדיניות שמופעלת בכל רמה היא פעילה. @@ -29,10 +30,10 @@ project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← איחוד עם הסרת כפילויות +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← איחוד ללא כפילויות ``` -**`policyParams`** - ההיקף הראשון המגדיר פרמטרים למדיניות מסוימת מנצח לחלוטין. אין היזוגה עמוקה של ערכים בתוך הפרמטרים של מדיניות. +**`policyParams`** - ההיקף הראשון המגדיר פרמטרים למדיניות נתונה מנצח לחלוטין. אין מיזוג עמוק של ערכים בתוך פרמטרי של מדיניות. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,18 +43,18 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project מנצח, glo ``` ```text -project: (אין ערך block-sudo) -local: (אין ערך block-sudo) +project: (no block-sudo entry) +local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← נופל דרך ל-global ``` -**`customPoliciesPaths` / `customPoliciesPath`** - ההיקף הראשון שמגדיר כל אחת מהצורות מנצח. +**`customPoliciesPaths` / `customPoliciesPath`** - ההיקף הראשון המגדיר אחת משתי הצורות מנצח. -**`disabledCustomPolicies`** - איחוד בכל ההיקפים. לוח המחוונים כותב כאן מזהה תו-מועד כאשר אתה כובה מדיניות בודדת מקובץ מדיניות מפורשי או מוסכמה. מדיניות שאינה רשומה נשארת מופעלת כברירת מחדל; המזהים כוללים את קובץ המקור כך שמדיניות בעלות אותו שם בקבצים מרובים יכולות להיות מנוהלות בהתאמה. +**`disabledCustomPolicies`** - איחוד על פני כל ההיקפים. לוח הבקרה כותב ID מותאם-למקור כאן כאשר אתה מכבה מדיניות אחת מקובץ מדיניות מפורש או קונוונציה. מדיניות שלא רשומה נשארת מופעלת כברירת מחדל; מזהים כוללים את קובץ המקור כדי שמדיניות עם שם זהה בקובצים מרובים יכולות להיות מווסתות בנפרד. -**`llm`** - ההיקף הראשון שמגדיר אותו מנצח. +**`llm`** - ההיקף הראשון המגדיר אותו מנצח. --- @@ -98,89 +99,91 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← נופל דרך ל-g --- -## הפניית שדות +## संदর्भ שדות ### `enabledPolicies` Type: `string[]` -רשימת שמות מדיניות להפעלה. השמות חייבים להתאים בדיוק לזיהויי המדיניות המוצגים על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לקבלת הרשימה המלאה. +רשימת שמות מדיניות להפעלה. שמות חייבים להתאים בדיוק למזהי מדיניות המוצגים על ידי `failproofai policies`. ראה [מדיניות מובנות](/he/built-in-policies) לרשימה המלאה. -מדיניות שאינה ב-`enabledPolicies` אינה פעילה, גם אם יש לה ערכים ב-`policyParams`. +מדיניות שלא ב-`enabledPolicies` אינן פעילות, גם אם יש להן ערכים ב-`policyParams`. ### `policyParams` Type: `Record>` -דריסות פרמטרים לכל-מדיניות. המפתח החיצוני הוא שם המדיניות; המפתחות הפנימיים הם ספציפיים למדיניות. כל מדיניות מתעדת את הפרמטרים הזמינים שלה ב-[Built-in Policies](/he/built-in-policies). +דריסות פרמטרים לכל מדיניות. המפתח החיצוני הוא שם המדיניות; המפתחות הפנימיים ספציפיים למדיניות. כל מדיניות מתעדת את הפרמטרים הזמינים שלה ב[מדיניות מובנות](/he/built-in-policies). -אם למדיניות יש פרמטרים אך אינך מציין אותם, משתמשים בברירות המחדל המובנות של המדיניות. משתמשים שאינם מגדירים `policyParams` כלל מקבלים התנהגות זהה לגרסאות קודמות. +אם למדיניות יש פרמטרים אבל לא מציינים אותם, משמשות את ברירות המחדל המובנות של המדיניות. משתמשים שלא מגדירים `policyParams` בכלל מקבלים התנהגות זהה לגרסאות קודמות. -מפתחות לא ידועים בתוך בלוק הפרמטרים של מדיניות מתעלמים בשקט בעת הנחת hook אך מסומנים כאזהרות כשאתה מריץ `failproofai policies`. +מפתחות לא ידועים בתוך בלוק פרמטרים של מדיניות מתעלמים בשקט בזמן הפעלת hook אבל מסומנים כאזהרות כאשר אתה מריץ `failproofai policies`. -#### `hint` (חוצה-חתוך) +#### `hint` (cross-cutting) Type: `string` (optional) -הודעה המצורפת לסיבה כאשר מדיניות מחזירה `deny` או `instruct`. השתמש בה כדי לתן Claude הנחיות פעולות מבלי לשנות את המדיניות עצמה. +הודעה המצורפת לסיבה כאשר מדיניות מחזירה `deny` או `instruct`. השתמש בה כדי לתן Claude הדרכה ממשית ללא שינוי של המדיניות עצמה. -פועל עם כל סוג מדיניות — מובנה, מותאמת אישית (`custom/`), מוסכמת פרויקט (`.failproofai-project/`), או מוסכמת משתמש (`.failproofai-user/`). +עובד עם כל סוג מדיניות — מובנה, מותאם אישית (`custom/`), קונוונציה פרויקט (`.failproofai-project/`), או קונוונציה משתמש (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "נסה ליצור ענף טרי במקום." + "hint": "Try creating a fresh branch instead." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "השתמש ב-apt-get ישירות בלי sudo." + "hint": "Use apt-get directly without sudo." }, "custom/my-policy": { - "hint": "בקש אישור מהמשתמש תחילה." + "hint": "Ask the user for approval first." } } } ``` -כאשר `block-force-push` דוחה, Claude רואה: *"Force-pushing חסום. נסה ליצור ענף טרי במקום."* +כאשר `block-force-push` מסירוב, Claude רואה: *"Force-pushing is blocked. Try creating a fresh branch instead."* -ערכים שאינם מחרוזות ומחרוזות ריקות מתעלמות בשקט. אם `hint` לא מוגדר, ההתנהגות נשארת ללא שינוי (תאומה לאחור). +ערכים שאינם מחרוזות ומחרוזות ריקות מתעלמות בשקט. אם `hint` לא הוגדר, ההתנהגות נשארת ללא שינוי (תאימות לאחור). ### `customPoliciesPath` Type: `string` (absolute path) -נתיב לקובץ JavaScript המכיל מדיניות hook מותאמות אישית. זה מוגדר באופן אוטומטי על ידי `failproofai policies --install --custom ` (הנתיב מעובד לערך מוחלט לפני שהוא מאוחסן). +נתיב לקובץ JavaScript המכיל מדיניות hook מותאמת אישית. זה מוגדר באופן אוטומטי על ידי `failproofai policies --install --custom ` (הנתיב מתורגם למוחלט לפני ההאחסנה). -הקובץ נטען בחדשות בכל אירוע hook - אין שימוש במטמון. ראה [Custom Policies](/he/custom-policies) לפרטי כתיבה. +הקובץ נטען מחדש בכל אירוע hook - אין קאשינג. ראה [מדיניות מותאמת](/he/custom-policies) לפרטי יצירה. -### מדיניות מבוססת מוסכמה +### מדיניות על בסיס קונוונציה -בנוסף ל-`customPoliciesPath` המפורשת, failproofai גוקם ובטוען קבצי מדיניות מספריות `.failproofai/policies/` באופן אוטומטי: +בנוסף ל-`customPoliciesPath` המפורש, failproofai גוקד ובוטל קובצי מדיניות מתיקיות `.failproofai/policies/`: -| רמה | ספרייה | היקף | +| Level | Directory | Scope | |-------|-----------|-------| -| Project | `.failproofai/policies/` | משותפת עם צוות דרך שליטה בגרסה | -| User | `~/.failproofai/policies/custom-policies/` | אישית, חלה על כל הפרויקטים | +| Project | `.failproofai/policies/` | משותף לצוות דרך בקרת גרסה | +| User | `~/.failproofai/policies/` | אישי, חל על כל הפרויקטים | - ספריית הרמה השנייה עברה ברמה לתוך ספריית הבית כחלק מיצירת ארגון מחדש של ספריית הבית. קבצים שנותרו במיקום הישן `~/.failproofai/policies/` מועברים אל `custom-policies/` באופן אוטומטי בפעם הראשונה שאתה מריץ כל פקודת `failproofai` לאחר שדרוג, והפקודה אומרת לך אילו קבצים היא העבירה. + שים את המדיניות שלך ישירות לתוך `~/.failproofai/policies/`. תיקיית `cloud-policies/` לצידם מכילה מדיניות שהארגון שלך פרס למכונה זו — הגילוי לא יורד לתת-ספריות, ולכן הוא לא נסרק, ודבר שתשים ב`policies/` לא יכול להתנגש איתה. + + אם אתה משדרג מגרסה שהשתמשה ב`~/.failproofai/policies/custom-policies/`, הכל בתיקייה זו — קובצי המדיניות שלך, כל `lib/` של עוזרים שהם יבואו, וכל קובצי נתונים שהם קוראים — מועבר חזרה למעלה באופן אוטומטי בפעם הראשונה שתריץ פקודת `failproofai`, והפקודה אומרת לך מה הוא העביר. -**התאמת קובץ:** רק קבצים המתאימים `*policies.{js,mjs,ts}` נטענים (למשל `security-policies.mjs`, `workflow-policies.js`). קבצים אחרים בספרייה מתעלמים. +**File matching:** רק קובצים התואמים ל-`*policies.{js,mjs,ts}` נטענים (לדוגמה `security-policies.mjs`, `workflow-policies.js`). קובצים אחרים בתיקייה מתעלמים. -**אין צורך בהגדרה:** מדיניות מוסכמה אינה דורשת ערכים ב-`policies-config.json`. פשוט שחרר קבצים לתוך הספרייה והם נוסקפו באירוע ה-hook הבא. +**No config needed:** מדיניות קונוונציה לא דורשות ערכים ב-`policies-config.json`. פשוט שים קובצים בתיקייה והם בוטלים באירוע ה-hook הבא. -**טעינת איחוד:** שתי ספריות מוסכמה של פרויקט ומשתמש סרוקות. כל הקבצים המתאימים משתי הרמות נטענים (בשונה מ-`customPoliciesPath` שמשתמש בה-first-scope-wins). +**Union loading:** שתי תיקיות קונוונציה של פרויקט ומשתמש נסרקות. כל הקובצים התואמים משתי הרמות נטענים (בניגוד ל-`customPoliciesPath` שמשתמש ב-first-scope-wins). -ראה [Custom Policies](/he/custom-policies) לפרטים ודוגמאות נוספים. +ראה [מדיניות מותאמת](/he/custom-policies) לפרטים נוספים ודוגמאות. ### `llm` Type: `object` (optional) -הגדרות לקוח LLM עבור מדיניות שמבצעות קריאות AI. לא נדרש עבור רוב ההגדרות. +תצורת לקוח LLM למדיניות שעורכות קריאות AI. לא נדרש לרוב הגדרות. ```json { @@ -193,26 +196,27 @@ Type: `object` (optional) --- -## ניהול התצורה מ-CLI +## ניהול תצורה מה-CLI -הפקודות `policies --install` ו-`policies --uninstall` כותבות לקובץ הגדרות ה-hook של ה-CLI של אירוח שלך (נקודות הכניסה של ה-hook), בעוד ש-`policies-config.json` הוא הקובץ שאתה מנהל ישירות. השניים נפרדים: +הפקודות `policies --install` ו-`policies --uninstall` כותבות לקובץ הגדרות hook של ה-CLI של הסוכן שלך (נקודות ה-entry של hook), בעוד `policies-config.json` הוא הקובץ שאתה מנהל ישירות. שני אלה נפרדים: -- **הגדרות Agent CLI** — אומר לאירוח להקרא `failproofai --hook ` בכל שימוש בכלי: +- **הגדרות Agent CLI** — אומר לסוכן להתקשר `failproofai --hook ` בכל שימוש בכלי: - **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) - - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex אין לו היקף `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot אין לו היקף `local`. ערכי Hook משתמשים בשדות הפקודה `bash`/`powershell` של Copilot עם `timeoutSec`; הקובץ נושא סימן `version: 1` ברמה העליונה. תמיכה ב-Copilot CLI היא **beta** בזמן שאנו מאמתים את סכמת התיעוד של `events.jsonl` (שהמסמכים הציבוריים לא מציינים) כנגד יותר מושבים בעולם האמיתי. **VS Code Copilot Chat agent mode (Preview)** קורא תצורות hook מ-`.github/hooks/*.json`, `~/.copilot/hooks/*.json`, ו-`~/.claude/settings.json` (מנוהל על ידי הגדרת `chat.hookFilesLocations`) תוך שימוש באותו חוזה בצורת Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — הנתיבים המדויקים שאליהם `failproofai policies --install --cli copilot` (או `--cli claude`) **כבר אוכפים ב-VS Code agent mode** ללא צורך באינטגרציה `vscode` נפרדת (מאומת בחי מרשמי הגילוי של VS Code). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor אין לו היקף `local`. ערכי Hook משתמשים בצורה בצורת Claude `{type, command, timeout}` (אין פיצול `bash`/`powershell`), אך מאוחסנים תחת מפתחות אירוע camelCase (`preToolUse`, `beforeSubmitPrompt`, …) במערך שטוח לפי [schemas hooks](https://cursor.com/docs/hooks) של Cursor; הקובץ נושא סימן `version: 1` ברמה העליונה. מטפל canonicalizes camelCase → PascalCase דרך `CURSOR_EVENT_MAP` כך שמדיניות מובנה קיימת ללא שינוי. תמיכה ב-Cursor Agent היא **beta** בזמן שאנו מאמתים את דיווח הטרנסקריפט של Cursor on-disk (לא מצוין במסמכים הציבוריים) כנגד יותר התקנות בעולם האמיתי. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode אין לו היקף `local`. בניגוד לחמשת ה-CLIs האחרים, OpenCode יש **אין מערכת hook בעלת פקודה חיצונית**: הוא טוען JS/TS plugins in-process שנרשמו בצורה מפורשת דרך מערך `plugin: []` ב-`opencode.json` (auto-discovery מ-`.opencode/plugins/` הוא **לא** איך plugins טוענים ב-opencode v1.14.33). Install משחרר shim plugin שנוצר קטן שמבצע subprocess-calls לבינארי failproofai ותרגום התגובה JSON בצורת Claude של הבינארי חזרה לסמנטיקה של plugin: `throw new Error()` עבור tool-event deny (מבטל את קריאת הכלי), `client.session.prompt(...)` עבור instruct וגם עבור `Stop` / `SubagentStop` deny (משחרר את סיבת ה-deny כהודעת המשתמש הבאה — ערוץ force-retry היחיד מאז `session.idle` הוא notification-only וזריקה מן זה היא no-op), ו-no-op עבור allow. Shim canonicalizes גם שמות כלי (lowercase → PascalCase דרך `OPENCODE_TOOL_MAP`) וגם tool-input arg keys (camelCase → snake_case דרך `OPENCODE_TOOL_INPUT_MAP` עבור `Read` / `Write` / `Edit`, למשל `filePath` → `file_path`, `oldString` → `old_string`) לפני שליחה לבינארי, כך שpath-checking builtins כמו `block-read-outside-cwd`, `block-env-files`, ו-`block-secrets-write` נורים ללא שינוי בקריאות כלי OpenCode. Sessions חיות בבסיס נתונים SQLite של opencode ב-`~/.local/share/opencode/opencode.db`; מצפה המושבים של לוח המחוונים קורא אותם דרך `opencode db --format json` ו-`opencode export `. תמיכה ב-OpenCode היא **beta** בזמן שאנו מאמתים התנהגות בגרסאות ובמול יותר מושבים בעולם האמיתי. ראה [OpenCode plugins docs](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi אין לו היקף `local`. Pi טוען TypeScript extension packages בעת ההפעלה; קובץ ההגדרות הוא מערך מחרוזות שטוח `{"packages": ["./relative/path", …]}`. failproofai כותב ערך packages-array יחיד המצביע על ספריית `pi-extension/` המופצצת שלו. ההרחבה פנימית מנויה לאירועי `tool_call` / `user_bash` / `input` / `session_start` של Pi ופגזי out to `failproofai --hook --cli pi`; מטפל canonicalizes underscore_lower_snake_case → PascalCase דרך `PI_EVENT_MAP` כך שמדיניות מובנה קיימת ללא שינוי. ארגומנטי tool input גם canonicalize דרך `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit deliver `path` במקום `file_path`; mapping the top-level key חושפת `block-env-files` ו-`block-secrets-write` — `block-read-outside-cwd` כבר היה בחזקת fallback `path`). תמיכה ב-Pi היא **beta** בזמן ש-API extension של Pi וסכמת session-log מתייצבות. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**user scope only** — Hermes אין לו תצורה project/local). Hermes הוא שער Slack/Telegram **gateway**, כך שהתקנה אחת מיירטת קריאות כלי מכל פלטפורמה (Slack/Telegram/cli/cron) **וגם** subagents פנימיים. ערכי Hook הם זוג `{command, timeout}` (timeout ב**שניות**) תחת מפת `hooks:` המקודדת לפי אירועי snake_case של Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); מטפל canonicalizes אירועים דרך `HERMES_EVENT_MAP` ושמות כלי דרך `HERMES_TOOL_MAP` כך שמדיניות מובנה נורות ללא שינוי. התצורה נערכת דרך יישור YAML `Document` המשמר הערות כך שהגדרות אחרות של האופרטור שורדות, והתקנה קובעת `hooks_auto_accept: true` כך שה-gateway headless (no TTY) מריץ את ה-hooks ללא בקשת הסכמה. המעריך פולט חוזה stdout של Hermes `{"decision":"block","reason"}` (Hermes מתעלם קודים יציאה). **Limitations:** Hermes אין turn-end `Stop` event, אז ה-`require-*-before-stop` builtins לא נורים עבורו (inapplicable, לא שבור); `instruct` נרדף כ-allow-with-logged-note (אין ערוץ context נוסף); וredaction סוד פלט (`sanitize-*`) לא יכול לשכתב tool output דרך חוזה shell-hook. Hermes הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי ה-gateway שלו ישירות מ-`~/.hermes/state.db`. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**user scope only** — OpenClaw אין לו תצורה project/local). כמו Hermes, OpenClaw הוא multi-channel self-hosted **gateway**, כך שהתקנה אחת מיירטת קריאות כלי מכל ערוץ ו-subagents פנימיים שלו. אוכיפה מריצה דרך **in-process plugin hooks** של OpenClaw (hook מבוססות קובץ פנימיים שלו הם תצפית בלבד ולא יכולים לחסום), כך ש — כמו OpenCode/Pi — failproofai משחרר ספרייה סטטית `openclaw-plugin/` שemulates-spawns את בינארי failproofai ותרגום הפסק. התקנה רושמת את ספרייה ה-plugin שנספקה בעמוד `plugins.load.paths[]` של `openclaw.json` וממקדת אותה תחת `plugins.entries.failproofai` (עם `hooks.allowConversationAccess: true`, נדרש עבור raw-conversation hooks). המעריך פולט פסק `{permission, reason}` שטוח וה-shim ממפה אותו לכל צורת החזרה של hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), ו-`before_agent_finalize → {action:"revise", reason}` (**Stop** — שער turn-end אמיתי, כך ש-`require-*-before-stop` builtins **אוכפים** ב-OpenClaw, בשונה מ-Hermes). אירועים ושמות כלי canonicalize binary-side דרך `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) כך שמדיניות מובנה נורות ללא שינוי; ה-shim נכשל פתוח בכל spawn/parse/timeout error. OpenClaw הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי JSONL שלו ב-`~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (user), `/.factory/hooks.json` (project) — Factory אין לו היקף `local`. droid משחרר מערכת hook בעלת פקודה חיצונית בצורת Claude, אך עם שתי דקויות מאומתות בחיים כנגד droid v0.171.0: (1) שמות אירוע חיים ברמה **העליונה** של `hooks.json` — אין **אין wrapper `"hooks"`** (droid דוחה אחד); אירועי כלי (`PreToolUse`/`PostToolUse`) נושאים `"matcher": "*"`, אירועים שאינם כלים משמיטים אותו. (2) Deny מונע על ידי **exit code 2 של hook + stderr**, לא JSON decision — ענף `factory` של המעריך חוזר exit 2 עבור tool/prompt events ו-`{decision:"block", reason}` רק באירוע turn-end `Stop` (ערוץ force-retry היחיד של droid). אירועים כבר PascalCase (אין event map) והמטען הוא Claude snake_case; רק שמות כלי canonicalize דרך `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי on-disk JSONL שלו ב-`~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (user), `/.devin/config.json` (project) — Devin אין לו היקף `local`. Devin הוא **pure Claude-clone** מאומת בחיים כנגד devin v3000.1.27: הוא משתמש בסכמת Claude `"hooks"`-wrapper סטנדרטית (כתיבה משמרות-merge כך שהמפתחות האחרים של קובץ ההגדרות — `org_id`, `theme_mode`, … — שורדות), שמות אירועים כבר-PascalCase (אין event map, אין handler branch), ופלט stdin בצורת Claude snake_case (ללא normalization). ענף `devin` של המעריך דוחה עם `{"decision":"block","reason"}` JSON ב-stdout ב-exit 0 עבור **כל** אירוע (מאומת — הבלוק דרס `--permission-mode dangerous`); באירוע turn-end `Stop` הסיבה נושאת את הניסוח force-retry של MANDATORY-ACTION כך שה-`require-*-before-stop` builtins אוכפים. רק שמות כלי canonicalize דרך `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` כבר canonical). Devin הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי SQLite שלו ב-`~/.local/share/devin/cli/sessions.db` (כל שורת `sessions` נושאת `working_directory` אמיתי, כך שמושבים מקובצים לפי cwd פרויקט כמו Claude). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (user), `/.agents/hooks.json` (project) — Antigravity אין לו היקף `local`. בשונה מ-Factory/Devin, Antigravity יש שלו **חוזה** (לא Claude-clone), מאומת בחיים כנגד agy v1.1.2. `hooks.json` משתמש בסכמה **named-hook**: המפתח ברמה העליונה הוא שם hook *name* (`"failproofai"`) שערכו הוא אירוע→handlers map — אירועי כלי (`PreToolUse`/`PostToolUse`) מטפלים עטוף בחוזה `{matcher:"*", hooks:[…]}`, בעוד `PreInvocation`/`Stop` הם **flat** arrays של מטפלים (hook שמות אחרים משומרים). המטען stdin הוא **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai ממנורמל אותו ל-snake_case לפני פעולת מדיניות, וממפה PascalCase args של `run_command` (`CommandLine`/`Cwd`) דרך `ANTIGRAVITY_TOOL_INPUT_MAP`. ענף `antigravity` של המעריך משתמש בצורות תגובה **שלו** של Antigravity: `{decision:"deny", reason}` חוסם tool/prompt (exit 0), `{decision:"continue", reason}` באירוע turn-end `Stop` enters the loop (כך ש-`require-*-before-stop` builtins אוכפים), ו-`{injectSteps:[{ephemeralMessage}]}` injects הנחיה ב-`PreInvocation` (→ `UserPromptSubmit`). שמות כלי canonicalize דרך `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את תמלילים plain-JSONL שלו ב-`~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (conversation index ב-`conversation_summaries.db`). - - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (user), `/.agents/plugins/failproofai/hooks/hooks.json` (project) — Goose אין לו היקף `local`. אוכיפה משתמשת בסביבת **hooks** של Goose, ה-cross-agent **Open Plugins** spec: המתקין פשוט שחרר את ספרייה `failproofai` plugin וGoose auto-discovers אותו בעת ההפעלה (self-registering אותו לתוך `~/.config/goose/config.yaml`). ה-`hooks.json` משתמש בסכמה Open Plugins **עם** wrapper `"hooks"` ברמה העליונה, ו-matcher הוא **omitted** בכל אירוע — `"*"` חשוף הוא regex לא תקף שתואם כלום (מאומת בחיים כנגד goose v1.43.0). שמות אירוע כבר PascalCase (אין event map); המטען stdin משתמש בـ `event`/`working_dir`, שהמטפל ממנורמל ל-`hook_event_name`/`cwd`. ענף `goose` של המעריך דוחה עם `{"decision":"block","reason"}` JSON ב-stdout ב-exit 0, מכובד ב**`PreToolUse`** אירוע בלבד (משחרר ב-goose ≥ v1.37.0) — שנורה עבור כלי ה-shell **וגם בתוך subagents משותקים**, כך שהוא נקודת deny יחידה מספיקה; כל hook אחר error נכשל **open**. Goose אין **אין `Stop` event**, כך שה-`require-*-before-stop` builtins לא חלים (כמו עם Hermes). שמות כלי canonicalize דרך `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) ופתח keys דרך `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose הוא **גם** מקור ביקורת offline — לוח המחוונים קורא את מושבי SQLite שלו ב-`~/.local/share/goose/sessions/sessions.db` (כל שורת `sessions` נושאת `working_dir` אמיתי, כך שמושבים מקובצים לפי cwd פרויקט כמו Devin; `--no-session` scratch runs מסוננים). -- **`policies-config.json`** — אומר ל-failproofai איזו מדיניות להעריך ועם מה פרמטרים (משותפת בכל אירוח CLIs) - -עבור `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` עבור יעד אירוח ספציפי (space-separated או חזר עבור כל תת-סט): + - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex אין לו `local` scope + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot אין לו `local` scope. ערכי Hook משתמשים ב`bash`/`powershell` של Copilot עם `timeoutSec`; הקובץ נושא סימן `version: 1` ברמה העליונה. תמיכת Copilot CLI היא **beta** בזמן שאנו מאמתים את סכמת ה-`events.jsonl` (שהמסמכים הציבוריים לא מציינים) כנגד עוד יותר הפעלות בעולם האמיתי. **VS Code Copilot Chat agent mode (Preview)** קורא תצורות hook מ-`.github/hooks/*.json`, `~/.copilot/hooks/*.json`, ו-`~/.claude/settings.json` (מנוהל על ידי הגדרת `chat.hookFilesLocations`) תוך שימוש באותו חוזה Claude-shaped `{hookSpecificOutput:{permissionDecision:"deny",…}}` — הנתיבים המדויקים שזה `copilot` integration וה-`claude` integration (`~/.claude/settings.json`) כבר כותבים, ולכן `failproofai policies --install --cli copilot` (או `--cli claude`) **כבר אוכף ב-VS Code agent mode** ללא צורך בintegration נפרד של `vscode` (אומת חי מיומני גילוי של VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor אין לו `local` scope. ערכי Hook משתמשים בצורה Claude-shaped `{type, command, timeout}` (ללא חלוקה `bash`/`powershell`), אבל מאוחסנים תחת מפתחות אירוע camelCase (`preToolUse`, `beforeSubmitPrompt`, …) במערך שטוח לכל [hooks schema](https://cursor.com/docs/hooks) של Cursor. הקובץ נושא סימן `version: 1` ברמה העליונה. המטפל מנרמל camelCase → PascalCase דרך `CURSOR_EVENT_MAP` כך שמדיניות מובנות קיימות ללא שינוי. תמיכת Cursor Agent היא **beta** בזמן שאנו מאמתים את הטרנסקריפט של Cursor על דיסק (לא מצוין במסמכים הציבוריים) כנגד עוד יותר התקנות בעולם האמיתי. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode אין לו `local` scope. בניגוד לחמישת CLI האחרים, OpenCode יש **אין מערכת hook חיצוני-פקודה**: הוא טוען בתוך-תהליך JS/TS פלאגינים שנרשמו במפורש דרך המערך `plugin: []` ב-`opencode.json` (גילוי אוטומטי מ-`.opencode/plugins/` **אינו** כיצד פלאגינים נטענים ב-opencode v1.14.33). install משחרר שימוש קטן שנוצר שמתקשר subprocess ל-binary failproofai ותרגום התגובה Claude-shape JSON של ה-binary חזרה לסמנטיקה פלאגין: `throw new Error()` ל-tool-event deny (מבטלת את הקריאה לכלי), `client.session.prompt(...)` לכל `instruct` ו`Stop` / `SubagentStop` deny (שולח את סיבת הדחייה כהודעה הבאה של המשתמש — התעלול היחיד כי `session.idle` הוא התראה בלבד והשלכה ממנה היא no-op), ו-no-op לאפשור. השימוש מנרמל שם כלים (קטן אותיות → PascalCase דרך `OPENCODE_TOOL_MAP`) וכלי-input arg מפתחות (camelCase → snake_case דרך `OPENCODE_TOOL_INPUT_MAP` עבור `Read` / `Write` / `Edit`, לדוגמה `filePath` → `file_path`, `oldString` → `old_string`) לפני העברה לה-binary, ולכן בדיקת נתיב builtins כגון `block-read-outside-cwd`, `block-env-files`, ו-`block-secrets-write` קיימות ללא שינוי על קריאות כלים ב-OpenCode. הפעלים מחיים בה-OpenCode SQLite DB ב-`~/.local/share/opencode/opencode.db`; לוח הבקרה session viewer קורא אותם דרך `opencode db --format json` ו-`opencode export `. תמיכת OpenCode היא **beta** בזמן שאנו מאמתים התנהגות על פני גרסאות וכנגד עוד יותר הפעלות בעולם האמיתי. ראה את [מסמכי OpenCode plugins](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi אין לו `local` scope. Pi טוען חבילות TypeScript extension בעת ההפעלה; קובץ ההגדרות הוא מערך מחרוזת שטוח `{"packages": ["./relative/path", …]}`. failproofai כותב ערך packages-array יחיד המצביע על תיקיית `pi-extension/` המצברת שלו. ההרחבה כל כך מנויה כדי אירועי Pi של `tool_call` / `user_bash` / `input` / `session_start` ופשוטות החוצה ל-`failproofai --hook --cli pi`; המטפל מנרמל snake_case underbar_lower → PascalCase דרך `PI_EVENT_MAP` כך שמדיניות מובנות קיימות ללא שינוי. tool input args מנורמל גם דרך `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit מספקים `path` ולא `file_path`; מיפוי המפתח ברמה העליונה משום `block-env-files` ו-`block-secrets-write` קיימות — `block-read-outside-cwd` כבר היה `path` fallback). תמיכת Pi היא **beta** בזמן שה-extension API של Pi וה-session-log layout מתייצבות. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**user scope בלבד** — Hermes אין לו project/local config). Hermes הוא **שער** Slack/Telegram, לכן התקנה יחידה מיירטת קריאות כלים מכל פלטפורמה (Slack/Telegram/cli/cron) **וגם** subagents פנימיים. ערכי Hook הם זוג `{command, timeout}` (timeout בשניות **) תחת מפת `hooks:` שהועברה דרך אירועי snake_case של Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); המטפל מנרמל אירועים דרך `HERMES_EVENT_MAP` ושמות כלים דרך `HERMES_TOOL_MAP` כך שמדיניות מובנות קיימות ללא שינוי. ההגדרה ערוכה דרך YAML comment-preserving `Document` round-trip כדי שהגדרות אחרות של המפעיל שרדו, ו-install כותב `hooks_auto_accept: true` כדי שהשער headless (ללא TTY) מריץ את ה-hooks ללא הנחיה לסכמה. ה-evaluator משדר חוזה stdout של Hermes `{"decision":"block","reason"}` (Hermes מתעלמת מקודי יציאה). **Limitations:** Hermes אין ל- turn-end `Stop` event, כדי `require-*-before-stop` builtins לעולם אירו עבורו (inapplicable, לא שבור); `instruct` יורדת להיתר-עם-logged-note (ללא ערוץ הוספה context); וחלמי תוצאה-סוד (`sanitize-*`) לא יכול לשכתב פלט כלים על פני חוזה shell-hook. Hermes הוא **גם** מקור ביקורת offline — לוח הבקרה קורא הפעלות שער ישירות מ-`~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**user scope בלבד** — OpenClaw אין לו project/local config). כמו Hermes, OpenClaw הוא **שער** בעלות עצמית רב-ערוץ, כדי התקנה יחידה מיירטת קריאות כלים מכל ערוץ ו-subagents פנימיים שלו. Enforcement מריץ דרך **in-process plugin hooks** של OpenClaw (ה-hooks שלו על בסיס קובץ הם observation-only ולא יכולים לחסום), ולכן — כמו OpenCode/Pi — failproofai חבילות plugin תיקיית `openclaw-plugin/` סטטית שביצוע async-spawns ה-binary failproofai ותרגום סיכום. install רושם את תיקיית plugin שנחרסה ב`openclaw.json`'s `plugins.load.paths[]` ומשך אותה תחת `plugins.entries.failproofai` (עם `hooks.allowConversationAccess: true`, נדרש לה-raw-conversation hooks). ה-evaluator משדר סיכום שטוח `{permission, reason}` והשימוש מיפה אותו לצורה הומית-כל hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), ו-`before_agent_finalize → {action:"revise", reason}` (**Stop** — real turn-end gate, ולכן ה-`require-*-before-stop` builtins **אכיפה** ב-OpenClaw, בניגוד ל-Hermes). אירועים ושמות כלים סטנדרט binary-side דרך `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) כדי מדיניות מובנות קיימות ללא שינוי; השימוש נכשל open בכל spawn/parse/timeout שגיאה. OpenClaw הוא **גם** מקור ביקורת offline — לוח הבקרה קורא הפעלות JSONL שלו ב-`~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (user), `/.factory/hooks.json` (project) — Factory אין לו `local` scope. droid חבילות Claude-style external-command hook מערכת, אבל עם שתי עקשנויות אומת חי כנגד droid v0.171.0: (1) שמות אירוע חיים ברמת **top level** של `hooks.json` — אין **ללא `"hooks"` wrapper** (droid דחה אחד); tool events (`PreToolUse`/`PostToolUse`) נוצא ביכנו `"matcher": "*"`, non-tool events השמיטו אותו. (2) Deny מונע על ידי hook **exit code 2 + stderr**, לא JSON decision — ה-evaluator's `factory` ענף חוזר יציאה 2 עבור tool/prompt events ו-`{decision:"block", reason}` רק ב-turn-end `Stop` event (droid's sole force-retry channel). אירועים כבר PascalCase (ללא event map) וה-payload הוא Claude snake_case; רק שמות כלים מנורמלים דרך `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory הוא **גם** מקור ביקורת offline — לוח הבקרה קורא הפעלות JSONL on-disk שלו ב-`~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (user), `/.devin/config.json` (project) — Devin אין לו `local` scope. Devin הוא **pure Claude-clone** אומת חי כנגד devin v3000.1.27: הוא משתמש בסכמה Claude הסטנדרטית `"hooks"`-wrapper (כתיבות הם merge-preserving כדי המפתחות האחרים של הקובץ — `org_id`, `theme_mode`, … — שרדו), כבר-PascalCase שמות אירוע (ללא event map, ללא handler branch), וה-payload stdin snake_case Claude (ללא normalization). ה-evaluator's `devin` ענף דוחה עם `{"decision":"block","reason"}` JSON ב-stdout ב-exit 0 עבור **כל אירוע** (אומת — החסימה דרכה `--permission-mode dangerous`); ב-turn-end `Stop` event הסיבה נושאת את אלץ-פעולה-חובה חזור כרח כדי `require-*-before-stop` builtins אכיפה. רק שמות כלים מנורמלים דרך `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` כבר canonical). Devin הוא **גם** מקור ביקורת offline — לוח הבקרה קורא הפעלות SQLite שלו ב-`~/.local/share/devin/cli/sessions.db` (כל `sessions` שורה נושאת real `working_directory`, ולכן הפעלות קבוצה לפי cwd פרויקט כמו Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (user), `/.agents/hooks.json` (project) — Antigravity אין לו `local` scope. בניגוד ל-Factory/Devin, Antigravity יש שלו **חוזה** (לא Claude-clone), אומת חי כנגד agy v1.1.2. `hooks.json` משתמש ב-**named-hook** סכמה: המפתח ברמת-top הוא hook *name* (`"failproofai"`) שערכו הוא אירוע→handlers מפת — tool events (`PreToolUse`/`PostToolUse`) wrap handlers ב-`{matcher:"*", hooks:[…]}`, בעוד `PreInvocation`/`Stop` הם **flat** handler arrays (named hooks אחרים שמורים). ה-stdin payload הוא **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai מנורמל אותו ל-snake_case לפני מדיניות להריץ, ומפות `run_command`'s PascalCase args (`CommandLine`/`Cwd`) דרך `ANTIGRAVITY_TOOL_INPUT_MAP`. ה-evaluator's `antigravity` ענף משתמש צורות תגובה **שלה** של Antigravity: `{decision:"deny", reason}` חוסמים כלי/prompt (exit 0), `{decision:"continue", reason}` ב-turn-end `Stop` re-enters לולאה (ולכן `require-*-before-stop` builtins אכיפה), ו-`{injectSteps:[{ephemeralMessage}]}` מזריקה הוראה על `PreInvocation` (→ `UserPromptSubmit`). שמות כלים סטנדרט דרך `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity הוא **גם** מקור ביקורת offline — לוח הבקרה קורא הטרנסקריפטים שלה plain-JSONL ב-`~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (index שיחה ב-`conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (user), `/.agents/plugins/failproofai/hooks/hooks.json` (project) — Goose אין לו `local` scope. Enforcement משתמש בה-**hooks** מערכת Goose, ה-cross-agent **Open Plugins** spec: ה-installer רק שחרר את תיקיית הפלאגין `failproofai` וה-Goose מגלה אותו באופן אוטומטי בעת ההפעלה (עצמו-רישום אותו לתוך `~/.config/goose/config.yaml`). ה-`hooks.json` משתמש ב-Open Plugins סכמה **עם ** top-level `"hooks"` wrapper, והמתאים **הוא השמיט** בכל אירוע — bare `"*"` הוא regex לא תקף כי התאמות כלום (אומת חי כנגד goose v1.43.0). שמות אירוע כבר PascalCase (ללא event map); ה-stdin payload משתמש `event`/`working_dir`, שהמטפל מנורמל ל-`hook_event_name`/`cwd`. ה-evaluator's `goose` ענף דוחה עם `{"decision":"block","reason"}` JSON ב-stdout ב-exit 0, honored ב-**`PreToolUse`** event בלבד (shipped ב-goose ≥ v1.37.0) — שקרי ל-shell tool **וב-delegated subagents**, ולכן הוא הנקודה של-deny יחיד-enough; כל אחר hook שגיאה כושל **open**. Goose יש **לא `Stop` event**, ולכן ה-`require-*-before-stop` builtins לא חלים (כמו Hermes). שמות כלים סטנדרט דרך `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) וגפי דרך `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose הוא **גם** מקור ביקורת offline — לוח הבקרה קורא הפעלות SQLite שלו ב-`~/.local/share/goose/sessions/sessions.db` (כל `sessions` שורה נושאת real `working_dir`, ולכן הפעלות קבוצה לפי cwd פרויקט כמו Devin; `--no-session` scratch runs הם סיננו). + +- **`policies-config.json`** — אומר failproofai אילו מדיניות להערכה וכן עם מה params (משותף על פני כל agent CLIs) + +מעבור `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` כדי לכוון סוכן ספציפי (רווח-separated או חוזר עבור כל תת-קבוצה): ```bash failproofai policies --install --cli codex --scope project @@ -229,20 +233,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -כאשר `--cli` משמיט, `failproofai` גוקם אי אירוח CLIs מותקנים (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +כאשר `--cli` השמיט, `failproofai` גוקד אילו agent CLIs מותקנים (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): + +- **One CLI detected** — auto-selects כי CLI ללא prompting. +- **Multiple CLIs detected** ב-interactive terminal — shows arrow-key single-select prompt קבוצה לתוך `Detected (N)` section (עם `Install for all N detected` aggregate row + כל detected CLI individually) וא-`Not installed (M) · install hooks ahead of time` section רישום כל undetected supported CLI כ-forward-install אפשרות (↑↓ לעבור, Enter לבחור, ^C ל-quit). ה-uninstall flow shows רק ה-Detected section. +- **Multiple CLIs detected** ב-non-interactive run (CI, ללא TTY) — הותקן לכל detected CLIs ללא prompting. +- **None detected** — falls back ל-`claude`, עם אזהרה כי ללא agent binary היה found ב-PATH; ה-hook פקודה עדיין כתובה ולכן הוא מעורר כ הקרוב אתה מותקן אחד. + +אתה יכול לערוך `policies-config.json` ישירות בכל עת; שינויים טוב אפקט מיד על ה-hook event הבא ללא קורה צורך. + +## Upgrades keep your configuration + +גרסה חדשה של failproofai עשוי לארגן `~/.failproofai/` בדרך אחרת. כאשר הוא עושה זאת, הפקודה הראשונה לאחר ה-upgrade מנדנה את התיקייה, וה-**תצורה שלך נישא על פני, לא reset**: + +| Kept | Rebuilt | +|---|---| +| בחירת המדיניות שלך וגמ (`policies-config.json`) | The audit cache | +| הגדרות שלך, כולל `daemon.configured` וערכי capture נוספים (`config.json`) | Cloud-managed policy deployments — re-fetched וdigest-verified בה-next poll | +| ה-cloud enrolment שלך (`credentials.json`) | Daemon scratch state | +| קובצי המדיניות שלך בתוך `policies/`, וה-helpers שהם יבואו | | +| ה-decision log שה-dashboard קורא, ואירועים עדיין לא מחקו | | + +מפתחות כתובים על ידי failproofai *חדש יותר* גם שמורים, ולא being נשמט על ידי קורא זקן — ולכן ניידות בין גרסאות עושה לא silently למחוק הגדרות משום כיוון. -- **CLI אחד גוקם** — auto-selects את ה-CLI בלי בקשה. -- **ריבויים CLIs גוקמים** בטרמינל אינטראקטיבי — מציג prompt single-select המונע על ידי arrow-key מקובץ לתוך `Detected (N)` section (עם `Install for all N detected` aggregate row + כל CLI גוקם בנפרד) ו`Not installed (M) · install hooks ahead of time` section מפרט כל CLI חסר כאפשרות forward-install (↑↓ לתנוע, Enter לבחור, ^C לסגור). זרימת ה-uninstall מציגה רק את סעיף ה-Detected. -- **ריבויים CLIs גוקמים** בריצה non-interactive (CI, no TTY) — התקנות עבור כל CLIs גוקמים בלי בקשה. -- **אף אחד לא גוקם** — נופל חזרה ל-`claude`, עם אזהרה שאין בינארי אירוח בـ PATH; פקודת ה-hook עדיין כתובה כך שהיא מופעלת ברגע שתתקין אחד. +אתה **לא** צורך ל-re-run setup אחר כך: מכונה מנדנה אכיפה בדיוק כן היה לפני, שהוא מה עושה ל-upgrade בטוח על מכונות עם אף אחד לא sitting בהם. כל ה-migration רשום ב-`~/.failproofai/migrations/applied.json`, והקובצים irreplaceable הם copied ל-`~/.failproofai/migrations/backup-layout/` לפני דבר כלשהו runs. -אתה יכול לערוך `policies-config.json` ישירות בכל עת; שינויים נכנסים לתוקף מיידית באירוע ה-hook הבא ללא צורך ב-restart. +ראה [`failproofai update`](/he/cli/update) לה-one-line upgrade, וגם [`failproofai migrate`](/he/cli/migrate) — כולל `--dry-run` — לה-details. --- -## דוגמה: תצורה ברמת פרויקט עם ברירות מחדל צוות +## Example: project-level config with team defaults -Commit `.failproofai/policies-config.json` לריפו שלך: +Commit `.failproofai/policies-config.json` ל-repo שלך: ```json { @@ -261,4 +283,4 @@ Commit `.failproofai/policies-config.json` לריפו שלך: } ``` -כל מפתח יכול לאחר מכן ליצור `.failproofai/policies-config.local.json` (gitignored) עבור דריסות אישיות ללא השפעה על חברי צוות. \ No newline at end of file +כל developer יכול אז ליצור `.failproofai/policies-config.local.json` (gitignored) לאישי overrides ללא השפעה teammates. \ No newline at end of file diff --git a/docs/he/custom-policies.mdx b/docs/he/custom-policies.mdx index bff03d9a..db752c45 100644 --- a/docs/he/custom-policies.mdx +++ b/docs/he/custom-policies.mdx @@ -1,11 +1,11 @@ --- --- title: מדיניות מותאמות אישית -description: "כתוב את הכללים שלך ב-JavaScript - אכוף כללים פרויקטיים, מנע סטיות, זהה כשלים, השתלב עם מערכות חיצוניות" +description: "כתוב את הכללים שלך ב-JavaScript - אכוף קונבנציות, מנע סטייה, זהה כשלים, השתלב עם מערכות חיצוניות" icon: code --- -מדיניות מותאמת אישית מאפשרת לך לכתוב כללים לכל התנהגות של agent: אכוף כללים פרויקטיים, מנע סטיות, חסום פעולות הרסניות, זהה agents שתקועים, או השתלב עם Slack, זרימות אישור, ועוד. הם משתמשים באותו מערכת hook של אירועים וקביעות `allow`, `deny`, `instruct` כמו מדיניות מובנית. +מדיניות מותאמות אישית מאפשרת לך לכתוב כללים עבור כל התנהגות של סוכן: אכיפת קונבנציות של פרויקט, מניעת סטייה, חסימת פעולות הרסניות, גילוי סוכנים תקועים, או השתלבות עם Slack, זרימות אישור ועוד. הם משתמשים באותו מערכת אירועי hook וביחידות `allow`, `deny`, `instruct` כמו המדיניות המובנית. --- @@ -30,7 +30,7 @@ customPolicies.add({ }); ``` -התקנה: +התקן זאת: ```bash failproofai policies --install --custom ./my-policies.js @@ -38,65 +38,65 @@ failproofai policies --install --custom ./my-policies.js --- -## שתי דרכים לטעון מדיניות מותאמת אישית +## שתי דרכים לטעינת מדיניות מותאמת אישית -### אפשרות 1: מבוססת על כללי כתיבה (מומלץ) +### אפשרות 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 ``` **איך זה עובד:** -- שתי ספריות (פרויקט ומשתמש) נסרקות (union — לא first-scope-wins) -- קבצים נטענים בסדר אלפביתי בכל ספרייה. הוסף `01-`, `02-` כדי לשלוט בסדר -- רק קבצים תואמים `*policies.{js,mjs,ts}` נטענים; קבצים אחרים מתעלמים -- כל קובץ נטען בעצמאות (fail-open לכל קובץ) -- עובד לצד `--custom` מפורש ומדיניות מובנית +- שתי תיקיות (פרויקט ומשתמש) נסרקות (איחוד — לא first-scope-wins) +- קבצים טוענים באופן אלפביתי בכל תיקייה. הוסף קידומת `01-`, `02-` לשליטה בסדר +- רק קבצים התואמים `*policies.{js,mjs,ts}` מטענו; קבצים אחרים מתעלמים +- כל קובץ טוען באופן עצמאי (fail-open לכל קובץ) +- פועל לצד `--custom` מפורש ומדיניות מובנית -מדיניות כללי כתיבה היא הדרך הקלה ביותר לבנות תקן איכות עבור הארגון שלך. קבע `.failproofai/policies/` ל-git וכל חברה בצוות מקבלת את אותם כללים באופן אוטומטי — אין צורך בהגדרה לכל מפתח. כאשר הצוות שלך מגלה מצבי כשל חדשים, הוסף מדיניות ודחוף. עם הזמן אלה הופכות לתקן איכות חי המשתפר עם כל תרומה. +מדיניות קונבנציה היא הדרך הקלה ביותר לבנות תקן איכות עבור הארגון שלך. אחזק `.failproofai/policies/` ב-git וכל חבר בצוות מקבל את אותם הכללים באופן אוטומטי — לא צריך התקנה לכל מפתח. כאשר הצוות שלך מגלה מצבי כשל חדשים, הוסף מדיניות ודחוף. לאורך זמן אלה הופכות לתקן איכות חי המשתפר עם כל תרומה. ### אפשרות 2: נתיב קובץ מפורש ```bash -# התקנה עם קובץ מדיניות מותאמת אישית +# התקן עם קובץ מדיניות מותאם אישית failproofai policies --install --custom ./my-policies.js # החלף את נתיבי המדיניות המותאמת אישית failproofai policies --install --custom ./new-policies.js -# קביעת תצורה של קבצים מפורשים מרובים (טעונים בסדר דגלים) +# תצורה של קבצים מפורשים מרובים (טוענים בסדר הדגלים) failproofai policies --install --custom ./security.js --custom ./workflow.js -# הסר את כל נתיבי המדיניות המותאמת אישית המפורשים מהתצורה +# הסר את כל נתיבי המדיניות המותאמת אישית המפורשת מהתצורה failproofai policies --uninstall --custom ``` -נתיבים מוחלטים מורכבים מאוחסנים ב-`policies-config.json` כ-`customPoliciesPaths`. חזור על `--custom` כדי לקבוע תצורה של קבצים מרובים. תצורות קיימות המשתמשות בשדה `customPoliciesPath` של העבר ממשיכות לעבוד. קבצים נטענים מחדש בכל אירוע hook - אין קאשינג בין אירועים. +נתיבים מוחלטים שנפתרו מאוחסנים ב-`policies-config.json` כ-`customPoliciesPaths`. חזור על `--custom` להגדרת קבצים מרובים. תצורות קיימות שמשתמשות בשדה `customPoliciesPath` הישן ממשיכות לעבוד. קבצים טוענים מחדש בכל אירוע hook — אין מטמון בין אירועים. -כל מדיניות רשומה מופיעה עם ההפעלה/כיבוי שלה בלוח הבקרה. החלפת מדיניות כיבה מתעדת את ה-ID המיומן בקובץ שלה ב-`disabledCustomPolicies`; הקובץ והמדיניות האחרות שלו ממשיכים להטען, בעוד המדיניות המבוטלת מחוצה לחוץ לפני תאימות אירוע. שמות מדיניות משוכפלים בקבצים שונים הם בעלי הפעלה/כיבוי בלתי תלוי. +כל מדיניות רשומה מופיעה עם toggle משלה בלוח הבקרה. כיבוי מדיניות מתעד את ה-ID המוכשר במקור שלה ב-`disabledCustomPolicies`; הקובץ והמדיניות האחרות שלו ממשיכות להטעין, בעוד המדיניות המכובה מודרת לפני התאמת אירועים. שמות מדיניות שחוזרים על עצמם בקבצים יש להם toggle עצמאיים. ### שימוש בשניהם ביחד -מדיניות כללי כתיבה וקבצי `--custom` מפורשים יכולים להתקיים. סדר טעינה: +מדיניות קונבנציה וקבצי `--custom` מפורשים יכולים להתקיים זה לצד זה. סדר טעינה: -1. קבצי `customPoliciesPaths` מפורשים (בסדר מוקביע) -2. קבצי כללי כתיבה של פרויקט (`{cwd}/.failproofai/policies/`, אלפביתי) -3. קבצי כללי כתיבה של משתמש (`~/.failproofai/policies/`, אלפביתי) +1. קבצי `customPoliciesPaths` מפורשים (בסדר מוגדר) +2. קבצי קונבנציה של פרויקט (`{cwd}/.failproofai/policies/`, אלפביתי) +3. קבצי קונבנציה של משתמש (`~/.failproofai/policies/`, אלפביתי) --- ## API -### ייבוא +### Import ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -104,7 +104,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -רושם מדיניות. קרא לזה כמה פעמים לפי הצורך עבור מדיניות מרובות באותו קובץ. +רושם מדיניות. קרא לפונקציה זו כמה פעמים שצריך עבור מדיניות מרובות באותו קובץ. ```ts customPolicies.add({ @@ -115,34 +115,34 @@ customPolicies.add({ }); ``` -### עוזרי קביעת החלטה +### עוזרי החלטות | פונקציה | השפעה | השתמש כאשר | |----------|--------|----------| -| `allow()` | אפשר את הפעולה בשתיקה | הפעולה בטוחה, לא נדרשת הודעה | -| `deny(message)` | חסום את הפעולה | ה-agent לא צריך לבצע פעולה זו | -| `instruct(message)` | הוסף הקשר ללא חסימה | תן ל-agent הקשר נוסף להישאר על המסלול | +| `allow()` | אפשר את הפעולה בשקט | הפעולה בטוחה, לא צריך הודעה | +| `deny(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` מצטברות ומסופקות ביחד. -אתה יכול להוסיף הנחיות נוספות לכל הודעת `deny` או `instruct` על ידי הוספת שדה `hint` ב-`policyParams` — אין צורך בשינוי קוד. זה עובד גם עבור מדיניות מותאמת אישית (`custom/`), כללי כתיבה של פרויקט (`.failproofai-project/`), וכללי כתיבה של משתמש (`.failproofai-user/`). ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. +אתה יכול להוסיף הדרכה נוספת לכל הודעת `deny` או `instruct` על ידי הוספת שדה `hint` ב-`policyParams` — לא צריך שינוי קוד. זה עובד עבור מדיניות מותאמת אישית (`custom/`), קונבנציה של פרויקט (`.failproofai-project/`), וקונבנציה של משתמש (`.failproofai-user/`) גם כן. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. -### הודעות allow מידע +### הודעות allow אינפורמטיביות -`allow(message)` מאפשר את הפעולה **וגם** שולח הודעה מידע חזרה ל-Claude. ההודעה מסופקת כ-`additionalContext` בתגובת stdout של מטפל hook — אותו מנגנון המשמש ל-`instruct`, אך שונה מבחינה סמנטית: זה עדכון סטטוס, לא אזהרה. +`allow(message)` מאפשר את הפעולה **וגם** שולח הודעה אינפורמטיבית חזרה ל-Claude. ההודעה מסופקת כ-`additionalContext` בתגובת stdout של ה-hook handler — אותו מנגנון המשמש ל-`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)`, כל ההודעות מצורפות עם שורות חדשות ומסופקות ביחד +- **הסברי fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — אומר ל-Claude מדוע בדיקה דוללדה כדי שיהיה לו הקשר מלא +- **הודעות מרובות צוברות:** אם מדיניות מרובות כל אחת מחזירה `allow(message)`, כל ההודעות מצטרפות עם שורות חדשות ומסופקות ביחד ```js customPolicies.add({ @@ -166,27 +166,27 @@ customPolicies.add({ | שדה | סוג | תיאור | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | הכלי שמופעל (למ"ג `"Bash"`, `"Write"`, `"Read"`) | +| `toolName` | `string \| undefined` | הכלי שמתבקש (למשל `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | פרמטרי הקלט של הכלי | -| `payload` | `Record` | עומס אירוע גולמי מלא מ-Claude Code | -| `session` | `SessionMetadata \| undefined` | הקשר מפגש (ראה למטה) | +| `payload` | `Record` | מטען אירוע גולמי מלא מ-Claude Code | +| `session` | `SessionMetadata \| undefined` | הקשר הסשן (ראה להלן) | ### שדות `SessionMetadata` | שדה | סוג | תיאור | |-------|------|-------------| -| `sessionId` | `string` | Claude Code מזהה מפגש | -| `cwd` | `string` | ספריה עובדת של מפגש Claude Code | -| `transcriptPath` | `string` | נתיב לקובץ תמליל JSONL של המפגש | +| `sessionId` | `string` | Claude Code session identifier | +| `cwd` | `string` | תיקיית עבודה של סשן Claude Code | +| `transcriptPath` | `string` | נתיב לקובץ תמלול JSONL של הסשן | -### סוגי אירוע +### סוגי אירועים -| אירוע | מתי זה מופעל | תוכן `toolInput` | +| אירוע | מתי זה יורה | תוכן `toolInput` | |-------|--------------|----------------------| -| `PreToolUse` | לפני Claude מפעיל כלי | קלט הכלי (למ"ג `{ command: "..." }` עבור Bash) | -| `PostToolUse` | אחרי שכלי משלים | קלט הכלי + `tool_result` (הפלט) | -| `Notification` | כאשר Claude שולח הודעה | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks חייבים תמיד להחזיר `allow()`, הם לא יכולים לחסום הודעות | -| `Stop` | כאשר מפגש Claude מסתיים | ריק | +| `PreToolUse` | לפני Claude מריץ כלי | קלט הכלי (למשל `{ command: "..." }` עבור Bash) | +| `PostToolUse` | אחרי שכלי מסתיים | קלט הכלי + `tool_result` (הפלט) | +| `Notification` | כאשר Claude שולח הודעה | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks חייבות תמיד להחזיר `allow()`, הם לא יכולים לחסום הודעות | +| `Stop` | כאשר סשן Claude מסתיים | ריק | --- @@ -196,8 +196,8 @@ customPolicies.add({ 1. מדיניות מובנית (בסדר הגדרה) 2. מדיניות מותאמת אישית מפורשת מ-`customPoliciesPath` (בסדר `.add()`) -3. מדיניות כללי כתיבה מפרויקט `.failproofai/policies/` (קבצים אלפביתיים, סדר `.add()` בתוך) -4. מדיניות כללי כתיבה ממשתמש `~/.failproofai/policies/` (קבצים אלפביתיים, סדר `.add()` בתוך) +3. מדיניות קונבנציה מפרויקט `.failproofai/policies/` (קבצים אלפביתי, סדר `.add()` בתוכם) +4. מדיניות קונבנציה מ-`~/.failproofai/policies/` של משתמש (קבצים אלפביתי, סדר `.add()` בתוכם) ה-`deny` הראשון מקצר את כל המדיניות הלאה. כל הודעות `instruct` מצטברות ומסופקות ביחד. @@ -205,7 +205,7 @@ customPolicies.add({ --- -## ייבוא חוזר +## ייבואים חוליים קבצי מדיניות מותאמת אישית יכולים לייבא מודולים מקומיים באמצעות נתיבים יחסיים: @@ -224,13 +224,13 @@ customPolicies.add({ }); ``` -כל הייבוא היחסי הנגיש מקובץ הכניסה מוגדר מחדש. זה מיושם על ידי כתיבת מחדש של `from "failproofai"` יבוא לנתיב dist בפועל וּיצירת קבצי `.mjs` זמניים להבטחת תאימות ESM. +כל הייבואים היחסיים הנגישים מקובץ הכניסה מוסברים. זה מיושם על ידי כתיבה מחדש של ייבואי `from "failproofai"` לנתיב dist בפועל ויצירת קבצי `.mjs` זמניים כדי להבטיח תאימות ESM. --- -## סינון סוגי אירוע +## סינון סוג אירוע -השתמש ב-`match.events` כדי להגביל מתי מדיניות מופעלת: +השתמש ב-`match.events` להגביל מתי מדיניות יורה: ```js customPolicies.add({ @@ -244,26 +244,26 @@ customPolicies.add({ }); ``` -השמט את `match` לחלוטין כדי להפעיל את כל סוגי האירוע. +השמט `match` לחלוטין כדי להיתקע על כל סוג אירוע. --- ## טיפול בשגיאות ומצבי כשל -מדיניות מותאמת אישית היא **fail-open**: שגיאות אף פעם לא חוסמות מדיניות מובנית או קורסות מטפל hook. +מדיניות מותאמת אישית היא **fail-open**: שגיאות לא חוסמות מדיניות מובנית או מתרסקות את ה-hook handler. | כשל | התנהגות | |---------|----------| -| `customPoliciesPath` לא הוגדרה | אין מדיניות מותאמת אישית מפורשת פועלת; מדיניות כללי כתיבה ומובנית ממשיכות בדרך כלל | -| קובץ לא נמצא | אזהרה נרשמת ל-`~/.failproofai/hook.log`; מובנית ממשיכה | -| שגיאת תחביר/ייבוא (מפורשת) | שגיאה נרשמת ל-`~/.failproofai/hook.log`; מדיניות מותאמת אישית מפורשת דילגה | -| שגיאת תחביר/ייבוא (כללי כתיבה) | שגיאה נרשמת; הקובץ הזה דילג, קבצי כללי כתיבה אחרים עדיין טוענים | -| `fn` זורק בזמן ריצה | שגיאה נרשמת; hook ההוא טרוט כ-`allow`; hoooks אחרים ממשיכים | -| `fn` לוקח יותר מ-10 שניות | timeout רשום; טיפול כ-`allow` | -| ספריית כללי כתיבה חסרה | אין מדיניות כללי כתיבה פועלת; אין שגיאה | +| `customPoliciesPath` לא מוגדר | לא מדיניות מותאמת אישית מפורשת פועלת; מדיניות קונבנציה ומובנית ממשיכות כרגיל | +| קובץ לא נמצא | אזהרה רשומה ל-`~/.failproofai/hook.log`; מובנים ממשיכים | +| שגיאת תחביר/ייבוא (מפורש) | שגיאה רשומה ל-`~/.failproofai/hook.log`; מדיניות מותאמת אישית מפורשת דוללדה | +| שגיאת תחביר/ייבוא (קונבנציה) | שגיאה רשומה; הקובץ ההוא דוללד, קבצי קונבנציה אחרים עדיין טוענים | +| `fn` זורק בזמן ריצה | שגיאה רשומה; ה-hook ההוא מטופל כ-`allow`; hook אחרים ממשיכים | +| `fn` לוקח יותר מ-10 שניות | timeout רשום; מטופל כ-`allow` | +| תיקיית קונבנציה חסרה | לא מדיניות קונבנציה פועלת; לא שגיאה | -כדי לנפות באגים בשגיאות מדיניות מותאמת אישית, צפה בקובץ היומן: +כדי לעתק שגיאות במדיניות מותאמת אישית, צפה בקובץ היומן: ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +272,7 @@ tail -f ~/.failproofai/hook.log --- -## דוגמה מלאה: מדיניות מרובה +## דוגמה מלאה: מדיניות מרובות ```js // my-policies.js @@ -329,14 +329,14 @@ export { customPolicies }; ## דוגמאות -ספריית `examples/` מכילה קבצי מדיניות מוכנים לריצה: +תיקיית `examples/` מכילה קבצי מדיניות מוכנים להפעלה: | קובץ | תוכן | |------|----------| -| `examples/policies-basic.js` | חמש מדיניות התחלה המכסות מצבי כשל רגילים של agent | -| `examples/policies-advanced/index.js` | דפוסים מתקדמים: ייבוא חוזר, קריאות async, שריטה פלט, ו-hooks של סוף מפגש | -| `examples/convention-policies/security-policies.mjs` | מדיניות אבטחה מבוססת כללי כתיבה (חסום כתיבות .env, מנע כתיבה מחדש של היסטוריית git) | -| `examples/convention-policies/workflow-policies.mjs` | מדיניות זרימה עבודה מבוססת כללי כתיבה (תזכוּרי בדיקה, קבצי כתיבה של ביקורת) | +| `examples/policies-basic.js` | חמש מדיניות התחלה המכסות מצבי כשל סוכן נפוצים | +| `examples/policies-advanced/index.js` | דפוסים מתקדמים: ייבואים חוליים, קריאות async, ניקוי פלט, וחוקי סוף סשן | +| `examples/convention-policies/security-policies.mjs` | מדיניות אבטחה מבוססות קונבנציה (חסום כתיבות .env, מנע כתיבה מחדש של היסטוריית git) | +| `examples/convention-policies/workflow-policies.mjs` | מדיניות זרימת עבודה מבוססות קונבנציה (תזכורות בדיקה, אודיט כתיבות קבצים) | ### שימוש בדוגמאות קובץ מפורשות @@ -344,7 +344,7 @@ export { customPolicies }; failproofai policies --install --custom ./examples/policies-basic.js ``` -### שימוש בדוגמאות מבוססות כללי כתיבה +### שימוש בדוגמאות מבוססות קונבנציה ```bash # Copy to project level @@ -356,4 +356,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -אין צורך בפקודת התקנה — הקבצים נאספים באופן אוטומטי בקריאת hook הבאה. \ No newline at end of file +לא צריך קובץ install — הקבצים נאספים באופן אוטומטי בהאירוע hook הבא. \ No newline at end of file diff --git a/docs/he/dashboard.mdx b/docs/he/dashboard.mdx index 1d962dba..45c954e0 100644 --- a/docs/he/dashboard.mdx +++ b/docs/he/dashboard.mdx @@ -1,110 +1,110 @@ --- title: לוח בקרה -description: "מעקב אחר הפעלות של agents, ביקורת קריאות כלים וניהול מדיניות" +description: "עיקוב הסעות וכלי של סוכנים, בדיקת קריאות לכלים וניהול מדיניות" icon: chart-line --- -לוח הבקרה של failproofai היא אפליקציית ווב מקומית לניטור הפעלות ה-AI agents שלך וניהול מדיניות. תראה מה עשו ה-agents שלך בזמן שהיית הרחק. +לוח הבקרה של failproofai היא יישומון ווב מקומי לעיקוב הסעות של סוכני AI שלך וניהול מדיניות. בדוק מה עשו הסוכנים שלך בזמן שלא היית שם. --- -## הפעלת לוח הבקרה +## התחלת לוח הבקרה ```bash failproofai ``` -נפתח ב-`http://localhost:8020`. +נפתח בכתובת `http://localhost:8020`. -לוח הבקרה קורא את נתוני הפרויקט, ההפעלה וקונפיגורציית failproofai המקומיים ישירות מקובץ המערכת. תכונות עם אימות אופציוני, כגון תזכורות ביקורת והזמנות, שולחות את המידע הנדרש לבקשות אלה (כולל כתובות דוא״ל) לממשקי API מרוחקים. +לוח הבקרה קורא נתוני פרויקט מקומי, הסעות וקונפיגורציה של failproofai ישירות מקובץ המערכת. תכונות מאומתות אופציונליות, כגון תזכורות ביקורת והזמנות, שולחות את המידע הנדרש לבקשות אלה (כולל כתובות דוא"ל) לממשקי API מרוחקים. --- ## דפים -### Projects +### Projects (פרויקטים) -מפרטת את כל פרויקטי Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ו-Goose שנמצאו במכונה שלך. פרויקטי Claude מגולים מ-`~/.claude/projects/` (או הנתיב שנקבע על ידי `CLAUDE_PROJECTS_PATH`); פרויקטי Codex מגולים על ידי סריקת כל תמליל תחת `~/.codex/sessions///
/*.jsonl` וקיבוץ לפי ה-`cwd` שנרשם ברשומה הראשונה של כל הפעלה; פרויקטי Copilot CLI מגולים על ידי סריקת כל `~/.copilot/session-state//workspace.yaml` (הניתן להגדרה דרך `COPILOT_HOME`) וקיבוץ לפי שדה ה-`cwd` שלו; פרויקטי Cursor Agent מגולים על ידי סריקת מטא-נתונים לכל הפעלה תחת `~/.cursor/agent-sessions//` (הניתן להגדרה דרך `CURSOR_HOME`, עם `conversations/` ו-`sessions/` כגישה לחילופין) עבור סקלר `cwd` ב-`meta.json` / `session.json` / `workspace.yaml`; פרויקטי OpenCode מגולים על ידי שאילתת ה-SQLite DB שלו ב-`~/.local/share/opencode/opencode.db` דרך `opencode db --format json` (אנו קוראים את טבלאות ה-`session` ו-`project` וקיבוץ לפי `project_id`); פרויקטי Pi מגולים על ידי סריקת תמליל JSONL לכל הפעלה תחת `~/.pi/agent/sessions//_.jsonl` (הניתן להגדרה דרך `PI_SESSIONS_DIR`) וקבלת ה-`cwd` מרשומה הראשונה של כל הפעלה; הפעלות שער של Hermes נקראות ישירות מחנות SQLite של כל פרופיל — `~/.hermes/state.db` בתוספת `~/.hermes/profiles//state.db` (ניתן להחזקה בחזרה דרך `HERMES_HOME`, או `HERMES_DB_PATH` עבור מסד נתונים יחיד) — וקיבוצות לפרויקטים `hermes--` לפי פרופיל ו-`source` (Slack/Telegram/cli/cron — להפעלות שער אין cwd); הפעלות שער של OpenClaw נקראות מ-`~/.openclaw/agents//sessions/*.jsonl` וקיבוצות לפרויקטים `openclaw--` לפי agent וערוץ (גם ללא cwd); פרויקטי Factory Droid מגולים מתמליל JSONL ב-`~/.factory/sessions//*.jsonl` וקיבוץ לפי cwd; פרויקטי Devin מה-SQLite DB שלו ב-`~/.local/share/devin/cli/sessions.db` (קיבוץ לפי `working_directory` של כל הפעלה); פרויקטי Antigravity מתמליל JSONL ב-`~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` וקיבוץ לפי cwd; ופרויקטי Goose מה-SQLite DB שלו ב-`~/.local/share/goose/sessions/sessions.db` (קיבוץ לפי `working_dir` של כל הפעלה). פרויקט שהשתמשה בו CLIs מרובות מוצג כשורה יחידה עם כל התגים התואמים. השתמש בתפריט הנפתח של **CLI** מעל הטבלה לסינון לפי agent CLI ספציפי; ה-URL שומר את הבחירה שלך כ-`?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +רשימת כל פרויקטי Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ו-Goose המצויים במחשב שלך. פרויקטי Claude מתגלים מתוך `~/.claude/projects/` (או הנתיב שנקבע על ידי `CLAUDE_PROJECTS_PATH`); פרויקטי Codex מתגלים על ידי סריקת כל תמלול תחת `~/.codex/sessions///
/*.jsonl` וקיבוץ לפי ה-`cwd` המוקלט בתיעוד הראשון של כל הסעה; פרויקטי Copilot CLI מתגלים על ידי סריקת כל `~/.copilot/session-state//workspace.yaml` (ניתן להגדרה דרך `COPILOT_HOME`) וקיבוץ לפי שדה ה-`cwd` שלהם; פרויקטי Cursor Agent מתגלים על ידי סריקת מטא-נתונים לפי הסעה תחת `~/.cursor/agent-sessions//` (ניתן להגדרה דרך `CURSOR_HOME`, כשהתיקיות `conversations/` ו-`sessions/` נבדקות כחלופות) לחיפוש אחר ערך סקלרי של `cwd` ב-`meta.json` / `session.json` / `workspace.yaml`; פרויקטי OpenCode מתגלים על ידי שאילתה של ה-SQLite DB שלהו ב-`~/.local/share/opencode/opencode.db` דרך `opencode db --format json` (אנו קוראים את טבלאות ה-`session` וה-`project` וקיבוץ לפי `project_id`); פרויקטי Pi מתגלים על ידי סריקת תמלולי JSONL לפי הסעה תחת `~/.pi/agent/sessions//_.jsonl` (ניתן להגדרה דרך `PI_SESSIONS_DIR`) וה-`cwd` נלקח מתיעוד הראשון של כל הסעה; הסעות שער של Hermes נקראות ישירות מחנות ה-SQLite של כל פרופיל — `~/.hermes/state.db` בתוספת `~/.hermes/profiles//state.db` (ניתן לעקוף דרך `HERMES_HOME`, או `HERMES_DB_PATH` עבור בסיס נתונים יחיד) — וקובצו לפרויקטים `hermes--` לפי פרופיל ו-`source` (Slack/Telegram/cli/cron — הסעות שער אין להן cwd); הסעות שער של OpenClaw נקראות מתוך `~/.openclaw/agents//sessions/*.jsonl` וקובצו לפרויקטים `openclaw--` לפי סוכן וערוץ (גם ללא cwd); פרויקטי Factory Droid מתגלים מתוך התמלולים של JSONL ב-`~/.factory/sessions//*.jsonl` וקובצו לפי cwd; פרויקטי Devin מתוך ה-SQLite DB שלו ב-`~/.local/share/devin/cli/sessions.db` (קובצו לפי `working_directory` של כל הסעה); פרויקטי Antigravity מתוך התמלולים של JSONL ב-`~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` וקובצו לפי cwd; ופרויקטי Goose מתוך ה-SQLite DB שלו ב-`~/.local/share/goose/sessions/sessions.db` (קובצו לפי `working_dir` של כל הסעה). פרויקט ששימש בו כמה ממשקי CLI מוצג כשורה יחידה עם כל התגים התואמים. השתמש בתפריט הנפתח של **CLI** מעל הטבלה כדי לסנן לפי ממשק CLI מסוים; ה-URL משמר את הבחירה שלך כ-`?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -Hermes ו-OpenClaw הם במתחם משתמש ואין להם ספריית עבודה לקיבוץ, כך שהם מוצגים כ-**עץ תיקיה שניתן להתמוטט** — פרופיל (או agent) ברמה העליונה, הערוצים שלו תחתיו — בעוד שכל CLI מבוסס-cwd נשאר שורה שטוחה. שורות תיקיה מגבשות את ספירת ההפעלה וההפעילות האחרונה ביותר של כל מה שנמצא תחתיהן, תיקיות מכווצות זוכרות בין ביקורים, וחיפוש מילות מפתח מרחיב כל מה שהוא תואם. +Hermes ו-OpenClaw הם בתחום משתמש ואין להם ספריית עבודה לקיבוץ לפיה, כך שהם מוצגים כ-**עץ תיקייה מתקפל** — פרופיל (או סוכן) ברמה הראשונה, הערוצים שלו מתחתיה — בעוד שכל ממשק CLI מבוסס-cwd נשאר שורה שטוחה. שורות תיקייה מצרפות את מספר ההסעות וההפעילות האחרונה ביותר של הכל תחתיהן, התיקיות המקופלות נזכרות בין ביקורים, וחיפוש מילות מפתח מרחיב כל מה שהוא תואם. כל פרויקט מציג: -- שם פרויקט (מתקבל מנתיב התיקיה) -- תג CLI — `Claude Code` (כתום), `OpenAI Codex` (סגול), `GitHub Copilot` (כחול), `Cursor Agent` (אזמרגד), `OpenCode` (ענבר), `Pi` (ורוד), ו/או `Hermes` (אינדיגו) -- תאריך של הפעילות ההפעלה המאוחרת ביותר +- שם הפרויקט (מקור מנתיב התיקייה) +- תג CLI — `Claude Code` (כתום), `OpenAI Codex` (סגול), `GitHub Copilot` (כחול), `Cursor Agent` (ירוק-כחול), `OpenCode` (amber), `Pi` (ורוד), ו/או `Hermes` (אינדיגו) +- תאריך של הפעילות בהסעה האחרונה ביותר -לחץ על פרויקט כדי לראות את ההפעלות שלו. +לחץ על פרויקט כדי לראות את הסעותיו. -### Sessions +### Sessions (הסעות) -מפרטת את כל ההפעלות בתוך פרויקט. כל הפעלה מציגה: -- מזהה הפעלה -- חתימות התחלה וסיום -- מספר קריאות כלים -- ספירת פעילות hook (מדיניות שירו) +רשימת כל ההסעות בתוך פרויקט. כל הסעה מציגה: +- מזהה הסעה +- חותמות זמן של התחלה וסיום +- מספר קריאות לכלים +- ספירת פעילות ווי (מדיניות שהופעלו) -השתמש בסנן טווח התאריכים וחיפוש מזהה הפעלה כדי לצמצם את הרשימה. הפעלות מדדיות. +השתמש בפילטר טווח התאריخים וחיפוש מזהה הסעה כדי לצמצם את הרשימה. ההסעות מחולקות לעמודים. -לחץ על הפעלה כדי לפתוח את כלי הצפיה של הפעלה. +לחץ על הסעה כדי לפתוח את מציין ההסעה. -### Session viewer +### מציין הסעה -כלי הצפיה של הפעלה עונה על השאלה העיקרית עבור agents עצמאיים: מה עשה ה-agent, והאם הוא נשאר על הפסים? תג CLI ליד הכותרת מציין אם ההפעלה היא תמליל Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity או Goose. הוא מציג ציר זמן של כל מה שקרה בהפעלה: +מציין ההסעה משיב על השאלה החזקה ביותר עבור סוכנים אוטונומיים: מה עשה הסוכן, והאם הוא נשאר על השביל? תג CLI ליד הכותרת מציין האם ההסעה היא תמלול של Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity או Goose. הוא מציג ציר זמן של כל מה שקרה בהסעה: -- **Messages** - תגובות טקסט של Claude והנחיות משתמש -- **Tool calls** - כל כלי שהדור Claude, עם הקלט והפלט שלו -- **Policy activity** - לכל קריאת כלי, אילו מדיניות ירו ואיזה החלטה הן החזירו +- **Messages (הודעות)** - תגובות טקסט של Claude והנושאים של משתמשים +- **Tool calls (קריאות לכלים)** - כל כלי שהחל Claude, עם הקלט והפלט שלו +- **Policy activity (פעילות מדיניות)** - עבור כל קריאה לכלי, אילו מדיניות הופעלו ואילו החלטה החזירו -פס הסטטיסטיקה בחלק העליון מציג משך הפעלה, סך הכל קריאות כלים וסיכום של החלטות hook (ספירות allow / deny / instruct). +סרגל הנתונים בחלק העליון מציג משך הסעה, סך הקריאות לכלים וסיכום ההחלטות של ווי (counts של allow / deny / instruct). -לחץ על כפתור **Download Logs** כדי לייצא את ההפעלה. עבור הפעלות Claude Code, Codex, Copilot, Cursor ו-Pi אתה מקבל את התמליל JSONL המקורי בדיסק byte-for-byte; עבור OpenCode (שההפעלות שלו חיות ב-SQLite, לא בדיסק) אתה מקבל מסמך JSON המשקף את טבלאות `session` / `messages` / `parts` הבסיסיות. +לחץ על כפתור **Download Logs** (הורדת יומנים) כדי לייצא את ההסעה. עבור הסעות Claude Code, Codex, Copilot, Cursor ו-Pi אתה מקבל את תמלול JSONL המקורי ממש כפי שהוא נשמר בדיסק; עבור OpenCode (שהסעותיו נמצאות ב-SQLite ולא על הדיסק) אתה מקבל מסמך JSON המשקף את טבלאות `session` / `messages` / `parts` הבסיסיות. -### Audit +### Audit (ביקורת) -דוח מונע אישיות כיצד ה-agent שלך התנהג בפועל על פני הפעלות קודמות. מפעיל את אותה סריקה כמו CLI `failproofai audit` אך עוצב אותה כפוסטר בעמוד יחיד ניתן לשיתוף + ארבעה חלקים מתחת לקיפול: +דוח מונע אישיות כיצד הסוכן שלך התנהג בפועל במהלך הסעות קודמות. מפעיל את אותה סריקה כמו CLI של `failproofai audit` אך מוצג אותה כפוסטר ניתן לשיתוף של מסך יחיד + ארבע חלקים מתחת לקפל: -1. **Poster** — ממלא את כלל התצוגה הראשונה. אזור capture בעצמו עם תו failproof_ai + תווית audit · אינדקס ארכיטיפ (`№ NN of 08`) + תאריך audit · ניקוד מספרי (0–100) + דירוג אחוזון דוהר (`top 15%`) · שם הארכיטיפ (אחד מ-`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + פס 3 מילות מפתח · `// only N% of agents are this archetype` קו נדירות · כרית חותמת פיקסל 8×8 · `audit yours → failproof.ai` footer. שלושה כפתורי שיתוף יושבים ממש מחוץ לתיבת ה-capture: `post your archetype` (כוונת X), `share on linkedin`, `download poster`. ה-Capture עובר דרך `html-to-image` כך ש-PNG משחקת את הרינדור על המסך pixel-for-pixel (גבולות מקופלים, מסכה לוגו SVG, שיפועים, מטרי גופן — הכל שמור). +1. **Poster (פוסטר)** — מלא את בחלון ההצגה הראשון. אזור ערימת PNG העצמאי עם סימן ה-failproof_ai + תווית ביקורת · אינדקס אבטיפוס (`№ NN of 08`) + תאריך ביקורת · ניקוד מספרי (0–100) + כדור דרגת אחוזון (`top 15%`) · שם האבטיפוס (אחד מהבאים: `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + רצועה של 3 מילות מפתח · `// only N% of agents are this archetype` שורת נדירות · רעפת סיגיל של 8×8 פיקסל · `audit yours → failproof.ai` כותרת. שלושה כפתורי שיתוף יושבים ממש מחוץ לקופסה: `post your archetype` (כוונת X), `share on linkedin`, `download poster`. הערימה פועלת דרך `html-to-image` כך שה-PNG תואם את העיבוד על המסך פיקסל לפיקסל (גבולות מקוקוקים, מסיכת לוגו SVG, gradients, מדדי גופן — הכל נשמר). -2. **Strengths** — רשימת שורה רגועה ✓ של התנהגויות שה-agent שלך כבר עושה נכון, הנגזרות מנתוני הביקורת החיים (קצב קריאה כלים נקי, ללא דחיפות ישירות לראשיים, אפס דליפות אישורים, אפס סערות ניסיון שוב) — כל אחד מופץ רק כאשר למדיניות הרלוונטית יש רקורד נקי על פני חלון הביקורת. +2. **Strengths (נקודות חוזק)** — רשימת שורות שקט ✓ התנהגויות שהסוכן שלך כבר עושה נכון, בנויות מנתוני הביקורת החי (קצב קריאות לכלים נקי, לא דחפים ישירים לראשי, דווח אפס של דלף אישורים, אין סערות ניסיון) — כל אחת מוצגת רק כאשר למדיניות הרלוונטית יש רקורד נקי על כל חלון הביקורת. -3. **Quirks** — טבלת מה חמק דרך, דורגת לפי חומרה: `when · what slipped + the policy that would've caught it · severity pill · seen`, כאשר חזרת הקורים קוראת `new` (פעם אחת), `N× seen` (2–9 פעמים), או `recurring` (10+). +3. **Quirks (מוזרויות)** — טבלה של מה שחמק, מדורג לפי חומרה: `when · what slipped + the policy that would've caught it · severity pill · seen`, שם ההישנות קורא `new` (פעם אחת), `N× seen` (2–9 פעמים), או `recurring` (10+). -4. **How to improve** — רשימת שורה רגועה, אחת לכל מדיניות מסומנת: שם מדיניות בלבן, תיאור בשורה אחת, הוראת התקנה + כפתור עותק בצד ימין. כותרת הקטע קוראת `enable all N → projected · ` (הניקוד שהיית מגיע עם כל התיקון החל), וה-`[install all]` שלה מעתיק את הפקודה המשולבת `failproofai policy add a b c …` לכל מדיניות מסומנת. +4. **How to improve (כיצד להשתפר)** — רשימת שורות שקט, אחת לכל מדיניות קבועה: שם מדיניות בלבן, תיאור בשורה אחת, פקודת התקנה + כפתור העתקה בצד ימין. כותרת החלק קורא `enable all N → projected · ` (הניקוד שהייתם מגיעים אליו עם כל התיקייה החלה), והכפתור `[install all]` שלה מעתיק את פקודת ה-`failproofai policy add a b c …` המשולבת עבור כל מדיניות קבועה. -5. **Come back better** — שתי כרטיסיות זה לצד זה. שמאל: קבע תזכורת (`3d` / `7d` / `14d` / `30d` בחיר קדנציה; נשמר דרך `/api/auth/reminder` לאחר אימות). ימין: בטל את הצפיפויות failproof — `invite a friend` פותח מודל שלוקח רשימה מופרדת בפסיקים/רווח/שורה חדשה של דוא״ל חברים (מקסימום 10 לשליחה), POSTs אותם ל-`/api/audit/invite`, אשר מעביר ל-`POST /v0/invite` של ה-api-server. ה-api-server שולח דוא״ל אחד לכל נמען מ-`invite@failproof.ai` עם Cc של השולח ו-`Reply-To` מוגדר, כך שהנמען רואה מי הזמין אותו והשולח מקבל עותק בתיבת הדואר שלו. משתמשים אנונימיים מנותבים דרך ה-`AuthDialog` תחילה כך שדוא״ל השולח ידוע לפני שהזמנות יוצאות. זכאות / מילוי הטבות הוא מעקב. +5. **Come back better (חוזרים עם תיקייה)** — שתי כרטיסיות זו לצד זו. שמאל: הגדר תזכורת (בוחר קצב `3d` / `7d` / `14d` / `30d`; נשמר דרך `/api/auth/reminder` ברגע שהאימות בוצע). ימין: בטל את תכניות failproof — `invite a friend` פותח דו-שיח שלוקח רשימה של כתובות דוא"ל של חברים בהפרדת פסיק/רווח/שורה חדשה (מקס 10 לשליחה), POST אותן ל-`/api/audit/invite`, שמעביר ל-`POST /v0/invite` של API-server. ה-API-server שולח דוא"ל אחד לכל נמען מתוך `invite@failproof.ai` עם ה-Cc של השולח וה-`Reply-To` מוגדר, כך שהנמען רואה מי הזמין אותו והשולח מקבל עותק בקופסת הדוא"ל שלו. משתמשים אנונימיים מנותבים דרך `AuthDialog` קודם לכן כדי שהדוא"ל של השולח ידוע לפני שההזמנות יוצאות. התאמה של זכויות / ביצוע הטבות היא עדכון נוסף. -מונע על ידי ריצת `failproofai audit` — ראה [Audit CLI](/he/cli/audit) לעניין סריקת המנוע הבסיסי, הדגלים הנתמכים, ואי-שונות במטמון לכל תמליל. לוח הבקרה מטמן את התוצאה האחרונה ב-`~/.failproofai/audit-dashboard.json` (מצב `0600`, משבצת יחידה, הריצות החדשות משכתבות) כך שביקורים חוזרים מיידיים; **גם המטמון לכל-תמליל וכל-תוצאה דחויים בקריאה ברגע שהם מעבר לתגובת TTL 7 ימים** כך שלוח הבקרה לעולם לא משרת בשקט תוצאה בן שבוע — עבר ה-TTL `/audit` נופל דרך למצב הריק שלו ומעודד ריצה חדשה. לחיצה על `[ re-audit now ]` ליד החלק התחתון של הדוח POSTs `/api/audit/run` עם `noCache: true` — ביקורת חוזרת עוקפת את המטמון לכל-תמליל וסורקת מחדש כל תמליל מאפס ולא משרתת בשקט את התוצאה המטומנת — ולוח הבקרה סוקר `/api/audit/status` ב-1Hz עד שהריצה מסתיימת; רצועת התקדמות ורודה ודבוקה מנעוצה בחלק העליון של התצוגה במהלך הריצה עם טיימר שחלף, והתוצאה הטרייה מחליפה במקום בהצלחה (ללא טעינה מחדש של דף מלא; אי-ביקורת כושלת משאירה את הדוח הקודם שלם). בכשל הרצועה הופכת לאדום עם עותק מפתוח מהסוג `RerunError.kind` (`timeout` / `network` / `post_failed`). מצב ריק (אין מטמון או פג) ומצב אפס-הפעלות (המטמון קיים אך הסריקה לא מצאה תמליל) משטחים בנפרד. +מונע על ידי זמן ההרצה של `failproofai audit` — ראה [Audit CLI](/he/cli/audit) לעבור הסריקה הבסיסי, דגלים נתמכים וחרוזי קאש לכל-תמלול. לוח הבקרה מטמון את התוצאה האחרונה ב-`~/.failproofai/audit-dashboard.json` (מצב `0600`, חריץ יחיד, ריצות חדשות דורסות) כך שביקורות חוזרות הן מיידיות; **גם קאש לכל-תמלול וקאש התוצאה-כל משולבים בקריאה ברגע שהם מבוגרים יותר מ-7 ימים** כדי שלוח הבקרה לעולם לא יעזור שקט תוצאה בת שבוע — עבור ה-TTL `/audit` נופל דרך מצבו הריק שלו ודוחה ריצה טרייה. לחיצה על `[ re-audit now ]` קרוב לתחתית הדוח POST `/api/audit/run` עם `noCache: true` — ריצה מחדש מחסום את קאש לכל-תמלול וסורק כל תמלול מ-0 במקום שקט להחזיר את התוצאה המוטמנת — ולוח הבקרה בודק את `/api/audit/status` ב-1Hz עד שהריצה מסתיימת; רצועת התקדמות ורודה דביקה מצודדת בחלק העליון של בחלון ההצגה במהלך הריצה עם טיימר עלוי, והתוצאה טרייה מחליפה במקומה בעת הצלחה (אין טעינה מחדש של עמוד שלם; ריצה מחדש שנכשלה משאירה את הדוח הקודם ללא נגיעה). בכשל הרצועה הופכת אדומה עם העתקה מפתחות מ-`RerunError.kind` (`timeout` / `network` / `post_failed`). מצב ריק (אין קאש או מוגבל) ומצב אפס-הסעות (קאש קיים אך הסריקה לא מצאה תמלולים) מוצגים בנפרד. -### Policies +### Policies (מדיניויות) -דף שתי-לשוניות לניהול מדיניות וביקורת פעילות. +דף בעל שתי לשוניות לניהול מדיניויות ובדיקת פעילות. - - - רב-בחר אילו agent CLIs failproofai מגנה מלוח יחיד — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi ו-Hermes כולם בעלי שורה עם מצב התקנה (`Active` / `Detected` / `Inactive`), נתיב הגדרות היקף המשתמש, ודגש צבע מותג. בדוק או בטל את בדיקת ה-CLIs שברצונך והקלק `Apply changes` כדי התקנה/הסרה של ההפרש בשלב אחד. CLIs שקובץ הבינאום שלה מוגדר בנתיב הם קבוע מראש. - - הפוך מדיניות אישית על או כבויה עם לחיצה יחידה (כתב ל-`~/.failproofai/policies-config.json` — משותף בכל CLI מותקן) - - הרחב מדיניות כדי להגדיר את הפרמטרים שלה (למדיניות התומכת בـ `policyParams`) - - קבע נתיב קובץ מדיניות מותאם + + - בחר ריבוי ממשקי CLI שה-failproofai מגן עליהם מלוח יחיד — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi ו-Hermes כולם בעלי שורה עם מצב התקנה (`Active` / `Detected` / `Inactive`), נתיב הגדרות בתחום המשתמש, ודגש בעל צבע מותג. סמן או בטל סימון של ממשקי CLI שאתה רוצה ולחץ על `Apply changes` כדי להתקין/להסיר את ההבדל בשלב אחד. ממשקי CLI שהקובץ הבינארי שלהם מתגלה ב-PATH מסומנים מראש. + - הדלק מדיניויות בודדות או כבה אותן בלחיצה יחידה (כותב ל-`~/.failproofai/policies-config.json` — משותף על פני כל ממשק CLI מותקן) + - הרחב מדיניות כדי להגדיר את הפרמטרים שלה (עבור מדיניויות התומכות ב-`policyParams`) + - הגדר נתיב קובץ מדיניויות מותאם אישית - - - היסטוריה דפדופית מלא של כל אירוע hook שירה על פני כל ההפעלות - - סנן לפי החלטה, סוג אירוע, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), שם מדיניות, או מזהה הפעלה - - כל שורה מציגה: חותמת זמן, שם מדיניות, החלטה, תג CLI (כתום = Claude Code, סגול = OpenAI Codex, כחול = GitHub Copilot, אזמרגד = Cursor Agent, ענבר = OpenCode, ורוד = Pi, אינדיגו = Hermes, טירקיז = OpenClaw, ורד = Factory Droid, סגול = Devin, ציאן = Antigravity, לימון = Goose), שם כלי, מזהה הפעלה, והסיבה להחלטות deny/instruct - - לחץ על מזהה הפעלה כדי לפתוח את התמליל שלו — כלי הצפיה מגלה אוטומטית אילו CLI ירה את ה-hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) וצג את תג ה-CLI התואם בכותרת + + - היסטוריית מלאה מחולקת לעמודים של כל אירוע ווי שהופעל על כל הסעות + - סנן לפי החלטה, סוג אירוע, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), שם מדיניות, או מזהה הסעה + - כל שורה מציגה: חותמת זמן, שם מדיניות, החלטה, תג CLI (כתום = Claude Code, סגול = OpenAI Codex, כחול = GitHub Copilot, ירוק-כחול = Cursor Agent, amber = OpenCode, ורוד = Pi, אינדיגו = Hermes, טיל = OpenClaw, ורד = Factory Droid, סגול = Devin, ציאן = Antigravity, ליים = Goose), שם כלי, מזהה הסעה, והסיבה להחלטות deny/instruct + - לחץ על מזהה הסעה כדי לפתוח את התמלול שלה — מציין הביקורת מגלה אוטומטית איזה CLI הפעיל את הווי (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) ומוצג את תג ה-CLI התואם בכותרת --- -## auto-refresh +## עדכון אוטומטי -לוח הבקרה יש קלט auto-refresh בניווט העליון. כאשר מופעל, הדף הנוכחי רענן מעת לעת כדי להציג הפעלות חדשות ופעילות מדיניות בעת שהן מופיעות. חיוני לניטור הפעלות agent עצמאיות ארוכות. +לוח הבקרה יש כפתור עדכון אוטומטי בניווט העליון. כאשר מופעל, העמוד הנוכחי מתרענן מעת לעת כדי להציג הסעות חדשות ופעילות מדיניות כשהן מופיעות. חיוני לעיקוב הסעות סוכן אוטונומיות ארוכות. --- ## השבתת דפים -אם אתה צריך רק חלקים מסוימים מלוח הבקרה, קבע `FAILPROOFAI_DISABLE_PAGES` לרשימה מופרדת בפסיקים של שמות דפים: +אם אתה זקוק רק לחלקים מסוימים של לוח הבקרה, הגדר את `FAILPROOFAI_DISABLE_PAGES` לרשימה מופרדת בפסיקים של שמות דפים: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -116,7 +116,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## הגדרת נתיב הפרויקטים -כברירת מחדל, לוח הבקרה קורא מספריית הפרויקטים הסטנדרטית של Claude Code. החזקה בחזרה עבור הגדרות מותאם אישית: +כברירת מחדל, לוח הבקרה קורא מספריית הפרויקטים של Claude Code הסטנדרטית. עקוף אותה עבור הגדרות מותאמות אישית: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -124,32 +124,32 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## גישה מאירח non-localhost +## גישה מכונסת שאינו localhost -כאשר מפעיל את לוח הבקרה ב-**dev mode** (`npm run dev`) וגישה אליו מ-hostname אחר מ-`localhost` - לדוגמה, דומיין מותאם אישית, IP מרוחק, או URL דרוך — אתה עלול לראות אזהרה כמו: +כאשר מפעילים את לוח הבקרה ב-**מצב פיתוח** (`npm run dev`) וגישה אליו מכונסת שאינו `localhost` - למשל, דומיין מותאם אישית, IP מרוחק או כתובת URL מנהרה - אולי תראה התראה כגון: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -זה Next.js חוסם גישה חוצת מוצא להתקן HMR (טעינה מחדש מודול חם) שלו, שהוא תכונה ב-dev בלבד. כדי לאפשר למארח שלך, השתמש בדגל `--allowed-origins`: +זה Next.js חוסם גישה חוצת מקור לווקסוקט HMR (hot module reload) שלו, שהוא תכונת dev-only. כדי לאפשר את ההוסט שלך, השתמש בדגל `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -עבור אירוחים או IPs מרובים, העבר רשימה מופרדת בפסיקים: +עבור מכשירים או כתובות IP מרובות, העבר רשימה מופרדת בפסיקים: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -אתה יכול גם להגדיר את משתנה הסביבה `FAILPROOFAI_ALLOWED_DEV_ORIGINS` במקום זאת: +ניתן גם להגדיר את משתנה הסביבה `FAILPROOFAI_ALLOWED_DEV_ORIGINS` במקום זאת: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -זה חל רק על dev mode. כאשר פועל `failproofai` (מצב ייצור), אין WebSocket HMR ואין בעיית משאב dev חוצת מוצא. +זה חל רק על מצב פיתוח. כאשר מפעילים `failproofai` (מצב ייצור), אין ווקסוקט HMR ואין בעיית משאב dev חוצת מקור. \ No newline at end of file diff --git a/docs/he/examples.mdx b/docs/he/examples.mdx index 26a8d062..18fcc084 100644 --- a/docs/he/examples.mdx +++ b/docs/he/examples.mdx @@ -1,17 +1,16 @@ --- ---- title: דוגמאות description: "כיצד להגדיר hooks עבור Claude Code ו-Agents SDK" icon: book-open --- -דוגמאות מוכנות לשימוש עבור תרחישים נפוצים. כל אחת מציגה כיצד להתקין ומה לצפות. +דוגמאות מוכנות לשימוש עבור תרחישים נפוצים. כל אחת מראה כיצד להתקין ומה לצפות. --- ## הגדרת hooks עבור Claude Code -Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) שלה. כשאתה מריץ `failproofai policies --install`, זה רושם פקודות hook ב-`settings.json` של Claude Code שפועלות בכל קריאת כלי. +Failproof AI משתלב עם Claude Code דרך [מערכת ה-hooks שלו](https://docs.anthropic.com/en/docs/claude-code/hooks). כשאתה מריץ `failproofai policies --install`, הוא רושם פקודות hook בקובץ `settings.json` של Claude Code שנוסעות בכל זימון כלי. @@ -19,7 +18,7 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks](https:// npm install -g failproofai ``` - + ```bash failproofai policies --install ``` @@ -29,14 +28,14 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks](https:// cat ~/.claude/settings.json | grep failproofai ``` - אתה אמור לראות ערכי hook עבור אירועי `PreToolUse`, `PostToolUse`, `Notification`, ו-`Stop`. + אתה אמור לראות ערכי hook עבור אירועי `PreToolUse`, `PostToolUse`, `Notification` ו-`Stop`. ```bash claude ``` - המדיניויות רצות כעת באופן אוטומטי בכל קריאת כלי. נסה לבקש מ-Claude להריץ `sudo rm -rf /` - זה יהיה חסום. + המדיניויות עכשיו רצות באופן אוטומטי בכל זימון כלי. נסה לבקש מ-Claude להריץ `sudo rm -rf /` - זה יחסום. @@ -44,7 +43,7 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks](https:// ## הגדרת hooks עבור Agents SDK -אם אתה בונה עם [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), אתה יכול להשתמש באותה מערכת hook בצורה תכנותית. +אם אתה בונה עם [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), אתה יכול להשתמש באותה מערכת hooks בצורה תכנותית. @@ -53,14 +52,14 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks](https:// ``` - העבר פקודות hook בעת יצירת תהליך ה-agent. ה-hooks פועלים באותו אופן כמו ב-Claude Code - דרך JSON של stdin/stdout: + העבר פקודות hook בעת יצירת תהליך ה-agent שלך. ה-hooks נוסעים באותו אופן כמו ב-Claude Code - דרך stdin/stdout JSON: ```bash failproofai --hook PreToolUse # called before each tool failproofai --hook PostToolUse # called after each tool ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -78,7 +77,7 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks](https:// }); ``` - + ```bash failproofai policies --install --custom ./my-agent-policies.js ``` @@ -89,35 +88,35 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks](https:// ## חסום פקודות הרסניות -ההגדרה הנפוצה ביותר - מנע מ-agents לגרום נזק בלתי הפיך. +ההגדרה הנפוצה ביותר - מנע מ-agents לעשות נזק בלתי הפיך. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` מה זה עושה: -- `block-sudo` - חוסם את כל פקודות `sudo` +- `block-sudo` - חוסם את כל פקודות ה-`sudo` - `block-rm-rf` - חוסם מחיקת קבצים רקורסיבית - `block-force-push` - חוסם `git push --force` -- `block-curl-pipe-sh` - חוסם הזרמת סקריפטים מרוחקים ל-shell +- `block-curl-pipe-sh` - חוסם צינור של סקריפטים מרוחוקים ל-shell --- ## מנע דליפת סודות -עצור agents מלראות או לדליף אישורים בפלט הכלי. +עצור agents מלראות או להדוף credentials בפלט כלים. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -אלה פועלות על `PostToolUse` - אחרי שכלי רץ, הם מנקים את הפלט לפני שה-agent רואה אותו. +אלה נוסעות ב-`PostToolUse` - אחרי שכלי רץ, הם מנקים את הפלט לפני שה-agent רואה אותו. --- -## קבל התראות Slack כשהעוזרים צריכים תשומת לב +## קבל התראות Slack כשיש צורך להשגיח על agents -השתמש ב-notification hook כדי להעביר התראות של inactivity ל-Slack. +השתמש ב-notification hook כדי להעביר התראות מצב המתנה ל-Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -161,7 +160,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## שמור על agents בענף -מנע מ-agents להחליף ענפים או לדחוף לענפים מוגנים. +מנע מ-agents להחליף ענפים או לדחוף לנוגות מוגנות. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -185,7 +184,7 @@ customPolicies.add({ ## דרוש בדיקות לפני commits -הזכר ל-agents להריץ בדיקות לפני commit. +הזכר ל-agents להריץ בדיקות לפני ביצוע commit. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -207,11 +206,11 @@ customPolicies.add({ --- -## נעל מאגר production +## נעל כמו חזק מאגר ייצור -Commit תצורה ברמת פרויקט כדי שכל מפתח בצוות שלך יקבל את אותן מדיניויות. +בצע commit של תצורה ברמת פרויקט כדי שכל מפתח בצוות שלך יקבל את אותן המדיניויות. -צור `.failproofai/policies-config.json` בספריית ה-repo שלך: +צור `.failproofai/policies-config.json` בכל ה-repo שלך: ```json { @@ -232,23 +231,23 @@ Commit תצורה ברמת פרויקט כדי שכל מפתח בצוות שלך } ``` -לאחר מכן commit אותו: +ואז בצע commit: ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -כל חבר בצוות שיש לו failproofai מותקן ילקוט באופן אוטומטי את הכללים הללו. +כל חבר צוות שיש לו failproofai מותקן יקבל אוטומטית את הכללים הללו. --- -## בנה תקן איכות בסקלה ארגונית עם convention policies +## בנה סטנדרט איכות ברחבי הארגון עם מדיניות קונוונציה -ההגדרה בעלת ההשפעה הרבה ביותר: commit `.failproofai/policies/` ל-repo שלך עם מדיניויות המותאמות לפרויקט שלך. כל חבר בצוות יקבל אותם באופן אוטומטי - אין פקודות התקנה, אין שינויי תצורה. +ההגדרה השפעתית ביותר: בצע commit של `.failproofai/policies/` ל-repo שלך עם מדיניויות מותאמות לפרויקט שלך. כל חבר צוות מקבל אותם אוטומטית — ללא פקודות התקנה, ללא שינויי תצורה. - + ```bash mkdir -p .failproofai/policies ``` @@ -284,25 +283,25 @@ git commit -m "Add failproofai team policies" }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - כשהצוות שלך נתקל בעוד אופני כשל, הוסף מדיניויות ודחוף. כולם יקבלו את העדכון בה-`git pull` הבא שלהם. המדיניויות הללו הופכות לתקן איכות חי המתגדל עם הצוות שלך. + כאשר הצוות שלך מתקל בקצת מצבי כישלון חדשים, הוסף מדיניויות ודחוף. כולם מקבלים את העדכון ב-`git pull` הבא שלהם. המדיניויות הללו הופכות לסטנדרט איכות חי שגדל עם הצוות שלך. --- -## עוד דוגמאות +## דוגמאות נוספות -ספריית [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) ב-repo מכילה: +תיקיית [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) ב-repo מכילה: -| קובץ | מה הוא מציג | +| קובץ | מה זה מראה | |------|---------------| -| `policies-basic.js` | מדיניויות התחלה - חסום כתיבה ל-production, force-push, סקריפטים שהוזרמו | -| `policies-notification.js` | התראות Slack עבור idle notifications וסוף session | -| `policies-advanced/index.js` | transitive imports, async hooks, PostToolUse output scrubbing, Stop event handling | \ No newline at end of file +| `policies-basic.js` | מדיניויות משכנעות - חסום כתיבה בייצור, force-push, סקריפטים מצונרים | +| `policies-notification.js` | התראות Slack לעצירות מצב המתנה וסיום של session | +| `policies-advanced/index.js` | יבוא חולף, hooks אסינכרוני, הנקיון פלט PostToolUse, טיפול בירוע Stop | \ No newline at end of file diff --git a/docs/he/for-agents.mdx b/docs/he/for-agents.mdx index 8e5a3c2e..7c2fc7a1 100644 --- a/docs/he/for-agents.mdx +++ b/docs/he/for-agents.mdx @@ -1,33 +1,33 @@ --- -title: "לסוכנים" -description: "הוסף ידע של Failproof AI לסוכן הקוד שלך בפקודה אחת. עובד עם Claude Code, Cursor, Windsurf ועוד." +title: "עבור agents" +description: "הוסף ידע Failproof AI לכל coding agent שלך בפקודה אחת. עובד עם Claude Code, Cursor, Windsurf ועוד." --- -הוסף את ההפניה המלאה של Failproof AI לסוכן הקוד שלך בפקודה אחת. עובד עם Claude Code, Cursor, Windsurf וכל סוכן אחר התומך ב-skills. +הוסף את ההתייחסות המלאה של Failproof AI ל-agent קידוד שלך בפקודה אחת. עובד עם Claude Code, Cursor, Windsurf וכל agent אחר התומך ב-skills. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` מזהה אילו סוכנים יש לך מותקנים ומוסיף את ה-skill בפורמט הנכון לכל אחד מהם באופן אוטומטי. +`npx skills` מגלה אילו agents יש לך מותקנים ומוסיף את ה-skill בפורמט הנכון לכל אחד מהם באופן אוטומטי. ## מה ה-skill מכסה -| אזור | מה כלול | +| תחום | מה כלול | |------|---------| -| Policies | שמות policy מובנים, סוגי אירועים, פרמטרים, הפעלה/השבתה | -| Custom policies | `customPolicies.add()`, match filters, `allow`/`deny`/`instruct` API | +| Policies | שמות policy מובנים, סוגי אירועים, פרמטרים, הפעלה/כיבוי | +| Custom policies | `customPolicies.add()`, match filters, API של `allow`/`deny`/`instruct` | | Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Configuration | מבנה `policies-config.json`, scope merging, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes | | Dashboard | Session viewer, policy activity, משתני סביבה | -| Architecture | Hook handler flow, exit codes, stdin/stdout contract | +| Architecture | Hook handler flow, exit codes, חוזה stdin/stdout | ## האם ה-skill שלם? -Mintlify יוצר `llms.txt` מכל הדפים בניווט. המסמכים של Failproof AI מכסים את ה-API המלא - כל policy, אפשרות וכל דוגמה כלולות. אם אתה מגלה משהו חסר, המקור נמצא ב-`https://docs.befailproof.ai/llms-full.txt`. +Mintlify יוצר `llms.txt` מכל העמודים בניווט. ה-docs של Failproof AI מכסים את כל ה-API - כל policy, אפשרות וקוד לדוגמה כלולים. אם אתה מגלה משהו חסר, המקור נמצא ב-`https://docs.befailproof.ai/llms-full.txt`. -לקונטקסט ממוקד, קישור ישירות לדף ספציפי: +לתוכן מטרה, קשר ישירות לעמוד ספציפי: ```bash # רק ה-custom policies API diff --git a/docs/he/getting-started.mdx b/docs/he/getting-started.mdx index e4716173..df4d5c2d 100644 --- a/docs/he/getting-started.mdx +++ b/docs/he/getting-started.mdx @@ -1,14 +1,14 @@ --- --- title: תחילת העבודה -description: "התקן את failproofai, הפעל מדיניויות, והנח לאגנטים שלך לפעול בנאמנות" +description: "התקן את failproofai, הפעל מדיניות והנח לסוכנים שלך לרוץ באופן אמין" icon: rocket --- ## דרישות - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (אופציונלי - נדרש רק לבנייה מקוד מקור) +- **Bun** >= 1.3.0 (אופציונלי - נדרש רק לבנייה מקוד המקור) --- @@ -31,16 +31,16 @@ bun add -g failproofai ## התחלה מהירה - - מדיניויות הן כללים שרצים לפני ואחרי כל קריאת כלי אגנט. הן תופסות פקודות הרסניות, דליפות סודות והיבטי כשל אחרים לפני שהם גורמים נזק. + + מדיניות הן כללים שפועלים לפני ואחרי כל קריאת כלי סוכן. הם תופסים פקודות הרסניות, דליפות סודות ודרכי כשל אחרים לפני שהם גורמים נזק. ```bash failproofai policies --install ``` - פעולה זו כותבת ערכי hook לתוך הקלים שהותקנו של האגנט (Claude Code של `~/.claude/settings.json`, OpenAI Codex של `~/.codex/hooks.json`, GitHub Copilot CLI של `~/.copilot/hooks/failproofai.json`, Cursor Agent של `~/.cursor/hooks.json`, shim של תוסף שנוצר ב-OpenCode ב-`~/.config/opencode/plugins/failproofai.mjs` בתוספת ערך הרשמה במערך `plugin` של `~/.config/opencode/opencode.json`, Pi של `~/.pi/agent/settings.json`, Hermes של `~/.hermes/config.yaml`, OpenClaw של `~/.openclaw/openclaw.json`, Factory Droid של `~/.factory/hooks.json`, Devin CLI של `~/.config/devin/config.json`, Antigravity CLI של `~/.gemini/config/hooks.json`, או ספריית התוסף שנגילתה אוטומטית של Goose ב-`~/.agents/plugins/failproofai/hooks/hooks.json`). כשיש יותר מאחד, תוצע לך בחירה; העבור `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (כל תת-קבוצה) כדי לדלג על ההנמקה. + זה כותב רשומות hook לכלי הסוכנים המותקנים שלך (Claude Code של `~/.claude/settings.json`, OpenAI Codex של `~/.codex/hooks.json`, GitHub Copilot CLI של `~/.copilot/hooks/failproofai.json`, Cursor Agent של `~/.cursor/hooks.json`, OpenCode של `~/.config/opencode/plugins/failproofai.mjs` בתוספת רשומת רישום ב-`~/.config/opencode/opencode.json` של `plugin` array, Pi של `~/.pi/agent/settings.json`, Hermes של `~/.hermes/config.yaml`, OpenClaw של `~/.openclaw/openclaw.json`, Factory Droid של `~/.factory/hooks.json`, Devin CLI של `~/.config/devin/config.json`, Antigravity CLI של `~/.gemini/config/hooks.json`, או Goose של הספריה המתגלה אוטומטית ב-`~/.agents/plugins/failproofai/hooks/hooks.json`). כאשר יש יותר מאחד, תתבקע; עברור `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (כל תת-קבוצה) כדי לדלג על השאלה. - GitHub Copilot CLI, Cursor Agent, OpenCode ו-Pi הם בשלב **beta** — התקן עם `--cli copilot`, `--cli cursor`, `--cli opencode`, או `--cli pi`. Hermes (hermes-agent, שער Slack/Telegram) מותקן בהיקף משתמש עם `--cli hermes` והוא **גם** מקור ביקורת לא מקוון. OpenClaw (שער openclaw, עוזר רב-ערוץ עצמי-מתארח) מותקן בהיקף משתמש עם `--cli openclaw` — אכיפה פועלת דרך hook-ים של תוסף בתוך התהליך (`before_agent_finalize` הוא שער קצה סיבוב אמיתי, ולכן הקטגוריות המובנות של `require-*-before-stop` אכופות) — והוא **גם** מקור ביקורת לא מקוון. Factory Droid (`droid`) מותקן עם `--cli factory` (היקף משתמש + פרויקט) והוא **גם** מקור ביקורת לא מקוון. Devin CLI (`devin`, Cognition) מותקן עם `--cli devin` (היקף משתמש + פרויקט) והוא **גם** מקור ביקורת לא מקוון. Antigravity CLI (`agy`) מותקן עם `--cli antigravity` (היקף משתמש + פרויקט) והוא **גם** מקור ביקורת לא מקוון. Goose (שם קוד goose, Block) מותקן עם `--cli goose` (היקף משתמש + פרויקט) — המתקין פשוט מכניס ספריית תוסף ב-`~/.agents/plugins/failproofai/` שGoose גילה אוטומטית, והוא **גם** מקור ביקורת לא מקוון. + GitHub Copilot CLI, Cursor Agent, OpenCode ו-Pi תומכים ב-**beta** — התקן עם `--cli copilot`, `--cli cursor`, `--cli opencode` או `--cli pi`. Hermes (hermes-agent, שער Slack/Telegram) מותקן בהיקף משתמש עם `--cli hermes` והוא **גם** מקור ביקורת מקוון. OpenClaw (שער openclaw, עוזר עצמי-מתארח מרובה ערוצים) מותקן בהיקף משתמש עם `--cli openclaw` — הכפייה פועלת דרך hook הפלאגין בתהליך שלו (`before_agent_finalize` הוא שער סיום תור אמיתי, כך ש-`require-*-before-stop` builtins כופים) — וגם **גם** מקור ביקורת מקוון. Factory Droid (`droid`) מותקן עם `--cli factory` (היקף משתמש + פרויקט) וגם **גם** מקור ביקורת מקוון. Devin CLI (`devin`, Cognition) מותקן עם `--cli devin` (היקף משתמש + פרויקט) וגם **גם** מקור ביקורת מקוון. Antigravity CLI (`agy`) מותקן עם `--cli antigravity` (היקף משתמש + פרויקט) וגם **גם** מקור ביקורת מקוון. Goose (codename goose, Block) מותקן עם `--cli goose` (היקף משתמש + פרויקט) — המתקין פשוט זורק ספריית פלאגין ב-`~/.agents/plugins/failproofai/` ש-Goose מגלה אוטומטית, וגם **גם** מקור ביקורת מקוון. ```bash failproofai policies --install --scope project @@ -58,67 +58,67 @@ bun add -g failproofai failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` - + ```bash failproofai policies ``` - מציג כל מדיניות, האם היא מופעלת, וכל פרמטרים שהוגדרו. + מציג כל מדיניות, האם היא מופעלת ופרמטרים מוגדרים כלשהם. - + ```bash failproofai ``` - פותח לוח בקרה מקומי ב-`http://localhost:8020` שבו תוכל לדפדף בהפעלות, בדוק קריאות כלים ונהל מדיניויות. + פותח לוח מחוונים מקומי ב-`http://localhost:8020` שבו אתה יכול לעיין בהפעלות, לבדוק קריאות כלים ולנהל מדיניות. - - התחל את Claude Code כרגיל. אם האגנט מנסה משהו מסוכן, failproofai יתקיף אותו באופן אוטומטי. השאר אותו פועל ללא השגחה ובדוק מה קרה בלוח הבקרה. + + התחל את Claude Code כרגיל. אם הסוכן מנסה משהו מסוכן, failproofai יחתוך אותו באופן אוטומטי. תן לו לרוץ ללא השגחה וסקור מה קרה בלוח המחוונים. --- -## איך מדיניויות פועלות +## כיצד עובדות מדיניות -בכל פעם שאגנט מפעיל כלי, Claude Code קורא ל-failproofai כתהליך משנה: +בכל פעם שסוכן מפעיל כלי, Claude Code קוראה ל-failproofai כתהליך משנה: ```text -Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin - מעריך מדיניויות - כותב החלטה ל-stdout +Claude Code → failproofai --hook PreToolUse → reads stdin JSON + evaluates policies + writes decision to stdout ``` כל מדיניות מחזירה אחת משלוש החלטות: -- **allow** - האגנט ממשיך כרגיל -- **deny** - הפעולה חסומה, האגנט מודיע למה -- **instruct** - הוספת הקשר נוסף להנמקה של האגנט +- **allow** - הסוכן ממשיך כרגיל +- **deny** - הפעולה חסומה, הסוכן מובא בעדיין למה +- **instruct** - הקשר נוסף מתווסף להנחיות הסוכן -מדיניויות רצות בתהליך המקומי שלך. שום דבר לא נשלח לשירות מרוחק. +מדיניות פועלת בתהליך המקומי שלך. שום דבר לא נשלח לשירות מרוחק. --- -## הגדר מדיניויות צוות עם מדיניויות מבוססות קונבנציה +## הגדר מדיניות קבוצתי עם מדיניות מבוססות קונבנציה -הדרך המהירה ביותר להקמת תקנים איכות בכל הצוות שלך היא הקונבנציה `.failproofai/policies/`. הטל קבצי מדיניות לספרייה זו והם יטענו באופן אוטומטי — ללא דגלים, ללא שינויי תצורה, ללא פקודות התקנה. +הדרך המהירה ביותר להקמת תקנים איכות בכל הצוות שלך היא הקונבנציה `.failproofai/policies/`. זרוק קבצי מדיניות לספריה זו והם טעונים באופן אוטומטי — ללא דגלים, ללא שינויי תצורה, ללא פקודות התקנה. - + ```bash mkdir -p .failproofai/policies ``` - - העתק את דוגמאות ההתחלה או כתוב שלך: + + העתק את דוגמאות ההתחלה או כתוב את שלך: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - או צור אחת חדשה: + או צור אחד חדש: ```js // .failproofai/policies/team-policies.mjs @@ -130,25 +130,25 @@ Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("הפעל בדיקות לפני ביצוע commit."); + return instruct("Run tests before committing."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "הוסף מדיניויות איכות צוות" + git commit -m "Add team quality policies" ``` - כל חברי צוות שיש להם failproofai מותקן לוקחים את המדיניויות הללו באופן אוטומטי. אין צורך בהגדרה נפרדת לכל מפתח. + כל חברי צוות שיש להם failproofai מותקן יקבלו את המדיניות האלה באופן אוטומטי. ללא הגדרה לכל מפתח. -העלה את `.failproofai/policies/` ל-repo שלך כדי שכל הצוות ישתוף את אותם תקנים. כאשר הצוות שלך גילה היבטי כשל חדשים, הוסף מדיניויות ודחוף — כולם מקבלים את העדכון בשלהם `git pull` הבא. לאורך זמן המדיניויות הללו הופכות לתקן איכות חי שממשיך להשתפר. +בצע דחיפה של `.failproofai/policies/` ל-repo שלך כדי שכל הצוות ישתף את אותם תקנים. כאשר הצוות שלך מגלה דרכי כשל חדשות, הוסף מדיניות ודחוף — כולם מקבלים את העדכון בהשלכה הבאה שלהם `git pull`. עם הזמן המדיניות הזו הופכת לתקן איכות חי שמשתפר כל הזמן. --- @@ -157,13 +157,15 @@ Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin כל התצורה והיומנים נשארים במכונה שלך: -| נתיב | מה הוא שומר | +| נתיב | מה זה אחסון | |------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | תצורת מדיניות גלובלית | -| `~/.failproofai/hook-activity/` | היסטוריה של ביצוע hook (JSONL מחולק) | -| `~/.failproofai/logs/` | יומנים ניפוי באגים לשגיאות hook מותאמות | -| `.failproofai/policies-config.json` | תצורה לכל פרויקט (committed) | -| `.failproofai/policies-config.local.json` | חידושים אישיים (gitignored) | +| `~/.failproofai/policies-config.json` | תצורת מדיניות גלובלית | +| `~/.failproofai/policies/` | המדיניות שלך — זרוק `*-policies.mjs` בתוך, ללא תצורה נדרשת | +| `~/.failproofai/policies/cloud-policies/` | מדיניות שפורסמה למכונה זו על ידי הארגון שלך | +| `~/.failproofai/hook-activity/` | היסטוריית ביצוע Hook (paged JSONL) | +| `~/.failproofai/logs/` | יומני ניפוי עבור שגיאות hook מותאם | +| `.failproofai/policies-config.json` | תצורת לכל-פרויקט (committed) | +| `.failproofai/policies-config.local.json` | התייחסויות אישיות (gitignored) | --- @@ -173,7 +175,7 @@ Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin failproofai policies --uninstall ``` -מסיר ערכי hook מ-`~/.claude/settings.json`. קבצי תצורה ב-`~/.failproofai/` משמרים. +מסיר רשומות hook מ-`~/.claude/settings.json`. קבצי תצורה ב-`~/.failproofai/` נשמרים. --- @@ -182,19 +184,19 @@ failproofai policies --uninstall - היקפים וקבוצת תצורה + היקפים וקבועי קבצי תצורה - - כל 26 המדיניויות עם פרמטרים + + כל 26 מדיניות עם פרמטרים - - כתוב את המדיניויות שלך ב-JavaScript + + כתוב את המדיניות שלך בJavaScript - - עקוב אחר הפעלות וביקורת פעילות מדיניויות + + עקוב אחר הפעלות וסקור את פעילות המדיניות \ No newline at end of file diff --git a/docs/he/introduction.mdx b/docs/he/introduction.mdx index b0239605..a98a3d0e 100644 --- a/docs/he/introduction.mdx +++ b/docs/he/introduction.mdx @@ -1,37 +1,36 @@ --- ---- title: "Failproof AI" -description: "FailproofAI מספקת לסוכני AI 39 מדיניויות כישל מובנות שתופסות לולאות, דליפות סודות, קריאות כלי הרסניות ועוד בהתקנה אחת." +description: "FailproofAI מספק לסוכנים AI 39 מדיניות כישלון מובנות המתפסות לולאות, דליפות סודות, קריאות כלי הרסניות ועוד בהתקנה יחידה." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -ווקים ומדיניויות ל**טיפול בכישלונות AI**, **התאוששות מ-שגיאות**, ו**אמינות LLM**. שמור על סוכני AI שלך אמינים וריצה אוטונומית ב**Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI**, ו**Agents SDK**. +Hooks ומדיניות עבור **טיפול בכישלונות AI**, **התאוששות משגיאות**, ו**אמינות LLM**. שמור על סוכנים AI אמינים ורצים באופן אוטונומי על פני **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI**, וה-**Agents SDK**. -סוכני AI כושלים בדרכים צפויות. הם מריצים פקודות הרסניות, מדליפים סודות, סוטים מהמשימה, נתקעים בלולאות, או דוחפים ישירות ל-main. אם משאירים זאת ללא פיקוח, כישלונות קטנים עלולים להיות לתאונות קטסטרופליות, דליפות אישורים עבודה, ואובדן עבודה. +סוכנים AI נכשלים בדרכים צפויות. הם מריצים פקודות הרסניות, דולפים סודות, סוטים מהמטלה, תקועים בלולאות, או דוחפים ישירות ל-main. אם משאירים אותם ללא פיקוח, כישלונות קטנים מתגברים להפסקות שירות, דלפות אישורים, ועבודה אבודה. -FailproofAI פותרת זאת באמצעות **מדיניויות**. כללים אלו משתלבים בכל קריאת כלי סוכן כדי **לגלות כישלונות**, **להפחית אותם** (לחסום, להנחות, לנקות), ו**להתריע עליך** כאשר משהו זקוק לתשומת לב. לוח מחוונים מקומי מאפשר לך לעיין בכל קריאת כלי, כישלון סוכן ופעולת התאוששות לאחר מכן. +FailproofAI פותר זאת עם **מדיניות**. כללים אלה מוכנסים לכל קריאת כלי סוכן כדי **לגלות כישלונות**, **להקל עליהם** (חסימה, הנחיה, sanitize), ו**להתריע אליך** כאשר משהו דורש תשומת לב. לוח מחוונים מקומי מאפשר לך לסקור כל קריאת כלי, כישלון סוכן וביצוע התאוששות לאחר מכן. -תמליל וה-evaluation של מדיניות נשארים במחשב שלך. נתונים נשלחים רק כאשר אתה משתמש באופן מפורש בתכונה מקוונת, כגון תזכורות ביקורת מאומתות או הזמנות. +עמלות והערכת מדיניות נשארות במכונה שלך. נתונים נשלחים רק כאשר אתה משתמש במפורש בתכונה מקוונת, כגון תזכורות ביקורת מאומתות או הזמנות. -## התחלה מהירה +## התחל - - חסום פקודות הרסניות, מנע דליפות סודות, שמור על סוכנים בתוך גבולות הפרויקט, ועוד. הכל מתוך הקופסה. + + חסום פקודות הרסניות, מנע דלפות סודות, שמור על סוכנים בתוך גבולות פרויקט, ועוד. הכל מהקופסה. - - כתוב כללים משלך ב-JavaScript באמצעות API פשוט של allow / deny / instruct. + + כתוב את הכללים שלך ב-JavaScript עם API פשוט של allow / deny / instruct. - - ראה מה סוכניך עשו כשלא היית שם. עיין בסשנים, בדוק קריאות כלים, סקור היכן מדיניויות הופעלו. + + ראה מה עשו הסוכנים שלך בזמן שלא היית. עיין בהפעלות, בדוק קריאות כלים, סקור היכן מדיניות הוציאה דיווחים. - - כייל כל מדיניות ללא קוד. הגדר allowlists, ענפים מוגנים, או ערכי סף לכל-פרויקט או בעולם. + + כוונן כל מדיניות ללא קוד. הגדר רשימות אישור, ענפים מוגנים, או סף לכל פרויקט או גלובלית. @@ -51,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # enable policies (or skip — `failproofai` will offer to set them up on first run) -failproofai # launch the dashboard +failproofai policies --install # הפוך מדיניות לזמינות (או דלג — `failproofai` יציע להגדיר אותן בהרצה הראשונה) +failproofai # הפעל את לוח המחוונים ``` -ראה את [Starting](/he/getting-started) guide להסבר המלא. \ No newline at end of file +ראה את מדריך [התחלה](/he/getting-started) לקבלת סיור מלא. \ No newline at end of file diff --git a/docs/he/package-aliases.mdx b/docs/he/package-aliases.mdx index 528d13d2..558b4f50 100644 --- a/docs/he/package-aliases.mdx +++ b/docs/he/package-aliases.mdx @@ -1,12 +1,13 @@ --- -title: כנויים של חבילה -description: "כנויים למניעת טעויות הקלדה רשומים וכיצד הם פועלים" +--- +title: Package Aliases +description: "Registered typosquat-prevention aliases and how they work" icon: copy --- -## החבילה הרשמית +## Official package -החבילה npm קנונית היא **`failproofai`**: +The canonical npm package is **`failproofai`**: ```bash npm install -g failproofai @@ -16,67 +17,67 @@ bun add -g failproofai --- -## למה אנחנו בעלים של שמות הכנויים +## Why we own the alias names -Typosquatting היא התקפת שרשרת אספקה נפוצה שבה שחקן זדוני רושם שם חבילה שנמצא במרחק הקשה אחת מחבילה פופולרית. משתמשים שלא מודעים שטעו בהקלדת פקודת ההתקנה בסופו של דבר מריצים קוד הנשלט על ידי התוקף עם גישה מלאה למערכת - בדיוק סוג האיום שFailproof AI תוכנן להגן עליו. +Typosquatting is a common supply-chain attack where a malicious actor registers a package name that is one keystroke away from a popular package. Unsuspecting users who mistype the install command end up running attacker-controlled code with full system access - exactly the kind of threat Failproof AI is designed to defend against. -כדי לבטל את פני השטח הזה, **אנחנו בעלים לפעוט של כל האיות השגויים והגרסאות העיצוביות הנפוצות** של `failproofai` ב-npm. שום אחד מהשמות הללו לא יכול להיות רשום על ידי צד שלישי. כל אחד מהם הוא פרוקסי דק המתקין ומוקד את החבילה האמיתית `failproofai`. +To eliminate this surface, **we pre-emptively own all common misspellings and formatting variants** of `failproofai` on npm. None of these names can be registered by a third party. Each one is a thin proxy that installs and delegates to the real `failproofai` package. --- -## כנויים רשומים +## Registered aliases -**גרסאות עיצוביות** - דרכים שונות לכתוב "failproof ai": +**Formatting variants** - different ways to write "failproof ai": -| חבילה | סטטוס | +| Package | Status | |---------|--------| -| `failproof` | ✅ פורסם | -| `failproof-ai` | ⏳ ממתין לתמיכת npm | -| `fail-proof-ai` | ⏳ ממתין לתמיכת npm | -| `failproof_ai` | ⏳ ממתין לתמיכת npm | -| `fail_proof_ai` | ⏳ ממתין לתמיכת npm | -| `fail-proofai` | ⏳ ממתין לתמיכת npm | +| `failproof` | ✅ Published | +| `failproof-ai` | ⏳ Pending npm support | +| `fail-proof-ai` | ⏳ Pending npm support | +| `failproof_ai` | ⏳ Pending npm support | +| `fail_proof_ai` | ⏳ Pending npm support | +| `fail-proofai` | ⏳ Pending npm support | -**טעויות `failprof*`** - חסר o אחד מ-"proof": +**`failprof*` typos** - missing one `o` from "proof": -| חבילה | סטטוס | +| Package | Status | |---------|--------| -| `failprof` | ✅ פורסם | -| `failprof-ai` | ✅ פורסם | -| `failprofai` | ⏳ ממתין לתמיכת npm | -| `fail-prof-ai` | ⏳ ממתין לתמיכת npm | -| `failprof_ai` | ⏳ ממתין לתמיכת npm | +| `failprof` | ✅ Published | +| `failprof-ai` | ✅ Published | +| `failprofai` | ⏳ Pending npm support | +| `fail-prof-ai` | ⏳ Pending npm support | +| `failprof_ai` | ⏳ Pending npm support | -**טעויות `faliproof*`** - a ו-i בעמדה הפוכה: +**`faliproof*` typos** - transposed `a` and `i`: -| חבילה | סטטוס | +| Package | Status | |---------|--------| -| `faliproof` | ✅ פורסם | -| `faliproof-ai` | ✅ פורסם | -| `faliproofai` | ⏳ ממתין לתמיכת npm | +| `faliproof` | ✅ Published | +| `faliproof-ai` | ✅ Published | +| `faliproofai` | ⏳ Pending npm support | -> **למה ממתין?** מדיניות מניעת הספאם של npm חוסמת שמות שמנורמלים לאותו מחרוזת כחבילה קיימת לאחר הסרת פיסוק וביצוע בדיקות דמיון. יצרנו קשר עם תמיכת npm כדי להזמין שמות אלה למטרות אנטי-טיפוס. הם יופעלו לאחר אישור. +> **Why pending?** npm's spam-prevention policy blocks names that normalize to the same string as an existing package after stripping punctuation and running similarity checks. We have contacted npm support to reserve these names for anti-squatting purposes. They will be activated once approved. -ניתן לאמת שכל כינוי שפורסם הוא בבעלותנו: +You can verify any published alias is owned by us: ```bash npm info failproof -# חפש: "ExosphereHost Inc." בשדה ה-maintainers +# Look for: "ExosphereHost Inc." in the maintainers field ``` --- -## איך הכנויים פועלים +## How the aliases work -כל חבילת כינוי: +Each alias package: -1. רשום את `failproofai` כתלות - אז החבילה האמיתית מותקנת והקובץ הבינארי שלה זמין -2. חושף קובץ בינארי התואם לשם שלו (למשל `failprof-ai`) שמעביר את כל הארגומנטים לקובץ `failproofai` הבינארי +1. Lists `failproofai` as a dependency - so the real package is installed and its binary becomes available +2. Exposes a binary matching its own name (e.g. `failprof-ai`) that proxies all arguments to the `failproofai` binary -הפרוקסי הוא סקריפט Node דו-שורתי; אין לוגיקה, אין קריאות רשת, ואין איסוף נתונים מעבר למה ש-`failproofai` עצמו עושה. +The proxy is a two-line Node script; there is no logic, no network calls, and no data collection beyond what `failproofai` itself does. --- -## אם מצאת שם שהחמצנו +## If you find a name we missed -פתח בעיה ב-[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) ואנחנו נרשום אותו. \ No newline at end of file +Open an issue at [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) and we will register it. \ No newline at end of file diff --git a/docs/he/testing.mdx b/docs/he/testing.mdx index ef14eec4..47667b05 100644 --- a/docs/he/testing.mdx +++ b/docs/he/testing.mdx @@ -1,10 +1,11 @@ --- +--- title: בדיקות -description: "בדיקות יחידה, בדיקות end-to-end וכלי עזר לבדיקות" +description: "בדיקות יחידה, בדיקות E2E ומסייעי בדיקה" icon: flask-vial --- -failproofai כולל שני חבילות בדיקות: **בדיקות יחידה** (מהירות, ממדומות) ו**בדיקות end-to-end** (הפעלות subprocess אמיתיות). +ל-failproofai יש שתי חבילות בדיקה: **בדיקות יחידה** (מהירות, מעוטרות) ו**בדיקות end-to-end** (קריאות subprocess אמיתיות). --- @@ -14,10 +15,10 @@ failproofai כולל שני חבילות בדיקות: **בדיקות יחידה # הרץ את כל בדיקות היחידה פעם אחת bun run test:run -# הרץ בדיקות יחידה במצב צפייה +# הרץ בדיקות יחידה במצב watch bun run test -# הרץ בדיקות E2E (דורש התקנה - ראה למטה) +# הרץ בדיקות E2E (דורש הגדרה - ראה להלן) bun run test:e2e # בדוק סוגים ללא בנייה @@ -36,15 +37,15 @@ bun run lint ```text __tests__/ hooks/ - builtin-policies.test.ts # Logic מדיניות לכל builtin - hooks-config.test.ts # טעינת config ומיזוג scope - policy-evaluator.test.ts # זריקת Param וסדר הערכה + builtin-policies.test.ts # ההיגיון של מדיניות לכל בנויה + hooks-config.test.ts # טעינת הגדרות ומיזוג scope + policy-evaluator.test.ts # הזרקת פרמטרים וסדר הערכה custom-hooks-registry.test.ts # globalThis registry add/get/clear - custom-hooks-loader.test.ts # ESM loader, imports transiently, handling errors + custom-hooks-loader.test.ts # ESM loader, ייבואים טרנזיטיביים, טיפול בשגיאות manager.test.ts # פעולות install/remove/list components/ - sessions-list.test.tsx # רכיב רשימת Session - project-list.test.tsx # רכיב רשימת Project + sessions-list.test.tsx # רכיב רשימת הפעלות + project-list.test.tsx # רכיב רשימת פרויקטים ... lib/ logger.test.ts @@ -61,7 +62,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### כתיבת בדיקת יחידה למדיניות +### כתיבת בדיקת יחידה של מדיניות ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -110,40 +111,40 @@ describe("block-sudo", () => { ## בדיקות end-to-end -בדיקות E2E משדרות את ה-binary של failproofai כـ subprocess אמיתי, משדרות payload JSON ל-stdin, וקובעות תשובה על פלט stdout וקוד יציאה. זה בודק את הנתיב המשולב המלא שבו Claude Code משתמש. +בדיקות E2E מפעילות את הקובץ `failproofai` האמיתי כ-subprocess, שולחות payload JSON ל-stdin וטוענות על פלט stdout וקוד היציאה. זה בודק את נתיב האינטגרציה המלא שבו Claude Code משתמש. -### התקנה +### הגדרה -בדיקות E2E מריצות את ה-binary ישירות מהמקור של המאגר. לפני ההרצה הראשונה, בנה את ה-CJS bundle שקבצי hook מותאמים משתמשים כשהם מייבאים מ-`'failproofai'`: +בדיקות E2E מריצות את הקובץ הבינארי ישירות מהמקור של הריפו. לפני ההרצה הראשונה, בנה את חבילת CJS שקבצי custom hook משתמשים בה כאשר הם מייבאים מ-`'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs ``` -אז הרץ את הבדיקות: +לאחר מכן הרץ את הבדיקות: ```bash bun run test:e2e ``` -בנה מחדש את `dist/` כל פעם שאתה משנה את ה-public hook API (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, או `src/hooks/policy-types.ts`). +בנה מחדש את `dist/` בכל פעם שתשנה את ה-API של hook הציבורי (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, או `src/hooks/policy-types.ts`). ### מבנה בדיקת E2E ```text __tests__/e2e/ helpers/ - hook-runner.ts # משדר את ה-binary, משדר payload JSON, לוקח exit code + stdout + stderr - fixture-env.ts # תיקיות זמניות מבודדות לכל בדיקה עם קבצי config - payloads.ts # מפעלות payload בעלות דיוק Claude לכל סוג event + hook-runner.ts # הפעל את הקובץ הבינארי, שלח payload JSON, תופס קוד יציאה + stdout + stderr + fixture-env.ts # ספריות temp מבודדות לכל בדיקה עם קבצי הגדרות + payloads.ts # מפעלי payload מדויקים של Claude עבור כל סוג אירוע hooks/ - builtin-policies.e2e.test.ts # כל builtin policy עם subprocess אמיתי - custom-hooks.e2e.test.ts # טעינת custom hook והערכה - config-scopes.e2e.test.ts # מיזוג config בחזה project/local/global - policy-params.e2e.test.ts # זריקת Parameter לכל מדיניות parameterized + builtin-policies.e2e.test.ts # כל מדיניות בנויה עם subprocess אמיתי + custom-hooks.e2e.test.ts # טעינה והערכה של custom hook + config-scopes.e2e.test.ts # מיזוג הגדרות על פני project/local/global + policy-params.e2e.test.ts # הזרקת פרמטרים לכל מדיניות פרמטרית ``` -### שימוש בעזרי E2E +### שימוש במסייעי E2E **`FixtureEnv`** - סביבה מבודדת לכל בדיקה: @@ -151,8 +152,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - תיקייה זמנית; תמסור כ-payload.cwd כדי לאסוף את .failproofai/policies-config.json -// env.home - isolated home dir; לא נוצרים דלפים של ~/.failproofai בפועל +// env.cwd - ספריית temp; העבר כ-payload.cwd כדי להרים את .failproofai/policies-config.json +// env.home - ספריית home מבודדת; אין דיסק של ~/.failproofai אמיתי env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +163,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` רושם `afterEach` cleanup באופן אוטומטי. +`createFixtureEnv()` רושמת ניקיון `afterEach` באופן אוטומטי. -**`runHook`** - משדר את ה-binary: +**`runHook`** - הפעל את הקובץ הבינארי: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +181,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - מפעלות payload מוכנות: +**`Payloads`** - מפעלי payload מוכנים: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -231,7 +232,7 @@ describe("block-rm-rf (E2E)", () => { }); ``` -### צורות תשובה של E2E +### צורות תגובה של E2E | החלטה | קוד יציאה | stdout | |----------|-----------|--------| @@ -241,20 +242,20 @@ describe("block-rm-rf (E2E)", () => { | Stop instruct | `2` | empty stdout; reason in stderr | | Allow | `0` | empty string | -### תצורת Vitest +### הגדרת Vitest בדיקות E2E משתמשות ב-`vitest.config.e2e.mts` עם: -- `environment: "node"` - לא דרושים browser globals -- `pool: "forks"` - process isolation אמיתי (בדיקות משדרות subprocesses) -- `testTimeout: 20_000` - 20 שניות לכל בדיקה (binary startup + hook eval) +- `environment: "node"` - אין צורך בגלובלים של דפדפן +- `pool: "forks"` - בידוד אמיתי של תהליכים (בדיקות שמפעילות subprocesses) +- `testTimeout: 20_000` - 20 שניות לכל בדיקה (הפעלת קובץ בינארי + הערכת hook) -ה-`forks` pool חשוב: עובדים המבוססים על thread משתפים `globalThis`, דבר שעלול להתערב בבדיקות המשדרות subprocess. process-based forks חוסכים זאת. +ה-`forks` pool חשוב: workers מבוססי thread חולקים `globalThis`, מה שיכול להפריע לבדיקות שמפעילות subprocesses. forks מבוססי process מונעים זאת. --- ## CI -ההרצה המלאה של CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) נדרשת כדי להצליח לפני merge. חבילת E2E חוברת כעבודת CI נפרדת במקביל. +הריצה המלאה של CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) חייבת להצליח לפני merge. חבילת E2E רצה כעבודת CI נפרדת במקביל. -ראה [Contributing](../CONTRIBUTING.md) לקבלת רשימת ה-checklist המלאה לפני merge. \ No newline at end of file +ראה [Contributing](../CONTRIBUTING.md) לרשימת ההשקה המלאה לפני merge. \ No newline at end of file diff --git a/docs/hi/agenteye/alerts.mdx b/docs/hi/agenteye/alerts.mdx index 1f5028bf..8fffc5a9 100644 --- a/docs/hi/agenteye/alerts.mdx +++ b/docs/hi/agenteye/alerts.mdx @@ -1,62 +1,63 @@ --- -title: "सतर्कताएं" -description: "उसी क्षण जानें जब कोई चीज़ आपकी सीमा को पार करे, उसी चैनल पर जो आपकी टीम पहले से देखती है, बजाय इसके कि किसी ग्राहक से सुनें।" +title: "अलर्ट्स" +description: "उसी क्षण जानें जब कुछ आपकी सीमा पार करे, उस चैनल पर जहां आपकी टीम पहले से देख रही है, बजाय किसी ग्राहक से इसके बारे में सुनने के।" --- -उसी क्षण जानें जब कोई चीज़ आपकी सीमा को पार करे, उसी चैनल पर जो आपकी टीम पहले से देखती है, बजाय इसके कि किसी ग्राहक से सुनें। एक बार नियम सेट करें और Failproof AI Observability इसे निर्धारित अनुसूची पर जांचता है, फिर ईमेल, Slack, webhook, या सीधे डैशबोर्ड में आपको सूचित करता है। -![सतर्कता पृष्ठ: सतर्कता-नियम कार्डों का एक ग्रिड, प्रत्येक अपने ट्रिगर, मूल्यांकन विंडो, चैनल, और एक सूचना, चेतावनी, या महत्वपूर्ण गंभीरता बैज दिखा रहा है](/agenteye/images/alerts.png) -*एक नज़र में हर सतर्कता नियम: यह क्या देखता है, कितनी बार, कहां सूचित करता है, और कितना जरूरी है।* +उसी क्षण जानें जब कुछ आपकी सीमा पार करे, उस चैनल पर जहां आपकी टीम पहले से देख रही है, बजाय किसी ग्राहक से इसके बारे में सुनने के। एक बार नियम सेट करें और Failproof AI Observability इसे नियमित रूप से जांचता है, फिर आपको ईमेल, Slack, webhook, या सीधे डैशबोर्ड में पेज करता है। + +![अलर्ट्स पेज: अलर्ट-नियम कार्ड्स का ग्रिड, प्रत्येक अपना ट्रिगर, मूल्यांकन विंडो, चैनल, और सूचना, चेतावनी, या महत्वपूर्ण गंभीरता बैज दिखाता है](/agenteye/images/alerts.png) +*हर अलर्ट नियम एक नज़र में: यह क्या देखता है, कितनी बार, कहां पेज करता है, और कितना जरूरी है।* ## अपने उपयोगकर्ताओं से पहले समस्याओं के बारे में जानें -डैशबोर्ड को ताज़ा करना बंद करें और प्रतिगमन पकड़ने की उम्मीद करें। जब भी कोई संकेत हो जो आप सुनना चाहते हैं तब भी जब कोई नहीं देख रहा हो, तो एक सतर्कता का उपयोग करें, और इसे उसी जगह भेजें जहां आप पहले से हैं: +यह आशा करते हुए डैशबोर्ड को रिफ्रेश करना बंद करें कि आप एक रिग्रेशन को पकड़ सकें। जब भी कोई संकेत हो जिसके बारे में आप सुनना चाहते हैं, भले ही कोई न देख रहा हो, एक अलर्ट चुनें, और इसे उसी जगह भेजें जहां आप पहले से हैं: -- **ईमेल**, जिसे यह जानना चाहिए उन लोगों को। -- **Slack**, एक समृद्ध संदेश एक बटन के साथ जो सीधे घटना पर कूदता है। -- **Webhook**, PagerDuty, Opsgenie, या आपके अपने endpoint के लिए JSON POST, एक वैकल्पिक हस्ताक्षर के साथ ताकि प्राप्तकर्ता इस पर विश्वास कर सके। -- **डैशबोर्ड में**, डिज़ाइन के अनुसार शांत, जब आप एक नियम को समायोजित कर रहे हों और अभी किसी को सूचित नहीं करना चाहते। +- **ईमेल**, जिन्हें जानना चाहिए उन लोगों को। +- **Slack**, एक समृद्ध संदेश जिसमें एक बटन हो जो सीधे घटना पर जाता है। +- **Webhook**, PagerDuty, Opsgenie, या अपने एंडपॉइंट के लिए एक JSON POST, एक वैकल्पिक हस्ताक्षर के साथ ताकि प्राप्तकर्ता इस पर विश्वास कर सके। +- **डैशबोर्ड में**, डिजाइन के अनुसार शांत, जब आप एक नियम को ट्यून कर रहे हों और अभी किसी को पेज नहीं करना चाहते हों। -किसी एक नियम के लिए कोई भी संयोजन संलग्न करें, और इसकी गंभीरता (सूचना, चेतावनी, या महत्वपूर्ण) साथ जाती है ताकि जरूरी वाले जरूरी दिखें। +किसी भी संयोजन को एक नियम से जोड़ें, और इसकी गंभीरता (सूचना, चेतावनी, या महत्वपूर्ण) साथ चलती है ताकि जरूरी वाले जरूरी लगें। ## फॉर्म में नियम बनाएं, JSON में नहीं -आप एक फॉर्म में बताते हैं कि "टूटा हुआ" का अर्थ क्या है, और Failproof AI Observability आपके लिए अंतर्निहित नियम लिखता है। JSON spec केवल वह है जो वह फॉर्म हुड के नीचे बनाता है, इसलिए आप इसे एक नियम को समझने के लिए पढ़ सकते हैं लेकिन आप शायद ही कभी इसे टाइप करते हैं। +आप एक फॉर्म में वर्णन करते हैं कि "टूटा हुआ" का मतलब क्या है, और Failproof AI Observability आपके लिए अंतर्निहित नियम लिखता है। JSON स्पेक बस वह है जो वह फॉर्म हुड के नीचे तैयार करता है, इसलिए आप इसे एक नियम को समझने के लिए पढ़ सकते हैं लेकिन आप शायद ही कभी इसे टाइप करते हैं। -![नई-सतर्कता फॉर्म: नाम और विवरण, एक सक्षम टॉगल, और एक ट्रिगर पिकर जो मेट्रिक थ्रेसहोल्ड, कस्टम SQL, मूल्यांकन स्कोर, यौगिक मूल्यांकन, और प्रति-ईवेंट शर्तें प्रदान करता है](/agenteye/images/alert-new.png) -*एक ट्रिगर चुनें और फॉर्म सही फील्ड में स्वैप करता है; सहेजें नियम लिखता है।* +![नया-अलर्ट फॉर्म: नाम और विवरण, एक सक्षम टॉगल, और एक ट्रिगर पिकर जो मेट्रिक थ्रेशहोल्ड, कस्टम SQL, मूल्यांकन स्कोर, कंपाउंड eval, और प्रति-ईवेंट शर्तें प्रदान करता है](/agenteye/images/alert-new.png) +*एक ट्रिगर चुनें और फॉर्म सही फील्ड्स में स्विच करता है; सेव नियम लिखता है।* -खुशियों की राह तेज़ है: इसका नाम दें, एक **ट्रिगर** चुनें (क्या देखना है), **थ्रेसहोल्ड और विंडो** सेट करें (कितना बुरा, कितने समय में), कम से कम एक **चैनल** संलग्न करें, फिर **सहेजें** और **परीक्षण** दबाएं एक कृत्रिम सूचना भेजने के लिए और पुष्टि करें कि हर गंतव्य सेट अप है। हुड के नीचे यह एक छोटा spec बनाता है जैसे: +खुशी का रास्ता जल्दी है: इसे नाम दें, एक **ट्रिगर** चुनें (क्या देखना है), **थ्रेशहोल्ड और विंडो** सेट करें (कितना बुरा, कितने समय में), कम से कम एक **चैनल** जोड़ें, फिर **सेव** करें और **टेस्ट** दबाएं एक सिंथेटिक नोटिफिकेशन भेजने के लिए और पुष्टि करें कि हर गंतव्य जुड़ा हुआ है। हुड के नीचे यह एक छोटा स्पेक तैयार करता है: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -आप एक प्रकार के संकेत तक सीमित नहीं हैं। ऐसे ट्रिगर को चुनें जो आपके विफलता के बारे में सोचने के तरीके से मेल खाता हो: +आप एक तरह के संकेत तक सीमित नहीं हैं। ऐसा ट्रिगर चुनें जो आपकी विफलता के बारे में सोचने के तरीके से मेल खाता हो: -| ट्रिगर | कब फायर होता है | +| ट्रिगर | कब फायर करता है | |---|---| -| **मेट्रिक थ्रेसहोल्ड** | एक पूर्वनिर्धारित मेट्रिक (त्रुटि दर, p95 या p99 विलंबता, ईवेंट या त्रुटि गणना, टोकन खर्च) एक विंडो पर आपकी सीमा को पार करता है | -| **कस्टम SQL** | आपकी स्वयं की पढ़ने-केवल क्वेरी एक पंक्ति लौटाती है, या यह एक मान की गणना करता है जो थ्रेसहोल्ड को पार करता है | -| **मूल्यांकन स्कोर** | एक मूल्यांकनकर्ता स्कोर का औसत (कहें, मतिभ्रम) एक थ्रेसहोल्ड को पार करता है | -| **यौगिक मूल्यांकन** | कई स्कोर जांचें any, all, या कम से कम-N तर्क के साथ संयोजित होते हैं, एक प्रतिगमन को पकड़ने के लिए जो केवल स्कोर में दिखाई देता है | -| **प्रति ईवेंट** | एक एकल मिलान वाली ईवेंट आती है: एक विशिष्ट agent, एक विशिष्ट त्रुटि प्रकार, या एक संदेश सबस्ट्रिंग | +| **मेट्रिक थ्रेशहोल्ड** | एक पूर्वनिर्धारित मेट्रिक (त्रुटि दर, p95 या p99 लेटेंसी, इवेंट या त्रुटि गणना, टोकन व्यय) एक विंडो में आपकी सीमा पार करता है | +| **कस्टम SQL** | आपकी अपनी रीड-ओनली क्वेरी एक पंक्ति लौटाती है, या यह जो मान गणना करता है वह एक थ्रेशहोल्ड पार करता है | +| **मूल्यांकन स्कोर** | एक मूल्यांकनकर्ता स्कोर का औसत (उदा., भ्रम) एक थ्रेशहोल्ड पार करता है | +| **कंपाउंड eval** | कई स्कोर जांच any, all, या कम से कम-N तर्क के साथ जोड़ी जाती हैं, एक रिग्रेशन को पकड़ने के लिए जो केवल स्कोर में दिखाई देता है | +| **प्रति इवेंट** | एक एकल मेल खाने वाली घटना आती है: एक विशिष्ट एजेंट, एक विशिष्ट त्रुटि प्रकार, या एक संदेश सबस्ट्रिंग | -पहले से ही [त्रुटि पृष्ठ](/hi/agenteye/error-tracking) पर एक विफलता को देख रहे हैं? वहां हर पंक्ति में एक **+ alert** बटन है जो इसी फॉर्म को खोलता है उस सटीक विफलता को पकड़ने के लिए पूर्वनिर्धारित, इसलिए घटना जिसे आपने अभी ट्रियेज किया वह वह है जो अगली बार आपको सूचित करती है। +पहले से ही [त्रुटि पृष्ठ](/hi/agenteye/error-tracking) पर एक विफलता को देख रहे हैं? वहां हर पंक्ति के पास एक **+ अलर्ट** बटन है जो इस फॉर्म को खोलता है, उस सटीक विफलता को पकड़ने के लिए पूर्वभरा होता है, इसलिए आपने जो घटना अभी-अभी ट्रिएज की है वह वह बन जाती है जो अगली बार आपको पेज करती है। -**इसे कहां खोजें:** Alerts `//alerts` पर रहते हैं। नियम बनाना, संपादन, हटाना, और परीक्षण करना **`alerts:write`** की आवश्यकता है; `alerts:read` देखने के लिए पर्याप्त है। प्राप्तकर्ता पिकर आपके org के सदस्यों को नाम के अनुसार सूचीबद्ध करता है, इसलिए आप फॉर्म छोड़े बिना एक व्यक्ति को सूचित कर सकते हैं। +**इसे कहां खोजें:** अलर्ट्स `//alerts` पर रहते हैं। नियम बनाना, संपादित करना, हटाना, और परीक्षण करना **`alerts:write`** की जरूरत है; `alerts:read` देखने के लिए काफी है। प्राप्तकर्ता पिकर आपके संगठन के सदस्यों को नाम से सूचीबद्ध करता है, इसलिए आप फॉर्म छोड़े बिना एक व्यक्ति को पेज कर सकते हैं। -## मुझे केवल तब सूचित करें जब यह वास्तविक हो +## मुझे केवल तब पेज करें जब यह वास्तविक हो -एक खराब माप आपको नहीं जगाना चाहिए। **M of N** शोर फ़िल्टर नियंत्रित करता है कि सतर्कता वास्तव में आपको सूचित करने से पहले कितनी अंतिम कुछ जांचें विफल होनी चाहिए। इसे **3 of 5** पर सेट करें और नियम केवल तभी फायर करता है जब इसने अपनी अंतिम पाँच जांचों में से तीन का उल्लंघन किया हो, इसलिए एक अस्थिर संकेत झूठी अलर्ट बंद करता है; इसे डिफ़ॉल्ट **1 of 1** पर छोड़ें पहली बार उल्लंघन पर फायर करने के लिए। आप यह भी चुनते हैं कि नियम कितनी बार चलता है, 1m, 5m, 15m, और 1h के पूर्वनिर्धारित से, संकेत कितनी तेज़ी से चलता है इसके साथ मेल खाते हुए। +एक बुरा माप आपको जगाना नहीं चाहिए। **M of N** शोर फिल्टर नियंत्रित करता है कि अलर्ट को वास्तव में पेज करने से पहले कितनी गत से हाल की जांचें विफल होनी चाहिए। इसे **3 of 5** पर सेट करें और नियम केवल तब फायर होता है जब यह अपनी आखिरी पांच जांचों में से तीन का उल्लंघन करता है, इसलिए एक अस्थिर संकेत झूठ बोलना बंद करता है; इसे डिफॉल्ट **1 of 1** पर छोड़ें पहली उल्लंघन पर फायर करने के लिए। आप यह भी चुनते हैं कि नियम कितनी बार चलता है, 1m, 5m, 15m, और 1h के प्रीसेट्स से, यह कितनी तेजी से संकेत वास्तव में चलता है इसके अनुसार। -## जब कोई सतर्कता फायर होती है तो क्या होता है +## जब एक अलर्ट फायर होता है तो क्या होता है -एक उल्लंघन एक **घटना** खोलता है और आपके चैनलों को एक बार सूचित करता है। वहां से आपकी टीम इसे स्वीकार करती है, एक मालिक निर्दिष्ट करती है, इसके माध्यम से बात करती है, और इसे हल करती है, सब कुछ एक स्वच्छ, जिम्मेदार रिकॉर्ड के विरुद्ध। वह ट्रियेज वर्कफ़्लो का अपना घर है: [घटनाएं](/hi/agenteye/incidents) देखें। +एक उल्लंघन एक **घटना** खोलता है और आपके चैनलों को एक बार पेज करता है। वहां से आपकी टीम इसे स्वीकार करती है, एक मालिक को असाइन करती है, इसके बारे में बात करती है, और इसे हल करती है, सभी एक स्वच्छ, जिम्मेदार रिकॉर्ड के खिलाफ। वह ट्रिएज वर्कफ़्लो का अपना घर है: [घटनाएं](/hi/agenteye/incidents) देखें। ## संबंधित -- [घटनाएं](/hi/agenteye/incidents): एक फायर की हुई सतर्कता को खुले से स्वीकृत से हल तक ट्रैक करें। -- [त्रुटि ट्रैकिंग](/hi/agenteye/error-tracking): agent विफलताओं को समूहीकृत करें और एक क्लिक में एक को सतर्कता में प्रचार करें। -- [डैशबोर्ड](/hi/agenteye/dashboards): साझा बोर्ड देखें जिन थ्रेसहोल्ड पर आप सतर्क होते हैं वे कहां से आते हैं। -- [CLI और agents](/hi/agenteye/cli-and-agents): अपने टर्मिनल से सतर्कता बनाएं और घटनाओं को स्वीकार करें, या उन्हें CI में स्क्रिप्ट करें। \ No newline at end of file +- [घटनाएं](/hi/agenteye/incidents): खुले से स्वीकृत से हल तक फायरिंग अलर्ट को ट्रैक करें। +- [त्रुटि ट्रैकिंग](/hi/agenteye/error-tracking): एजेंट विफलताओं को समूहीकृत करें और एक क्लिक में एक को अलर्ट में प्रचारित करें। +- [डैशबोर्ड्स](/hi/agenteye/dashboards): साझा बोर्ड्स को देखें जिन थ्रेशहोल्ड्स पर आप अलर्ट करते हैं वे कहां से आते हैं। +- [CLI और एजेंट्स](/hi/agenteye/cli-and-agents): अपने टर्मिनल से अलर्ट्स बनाएं और घटनाओं को स्वीकार करें, या उन्हें CI में स्क्रिप्ट करें। \ No newline at end of file diff --git a/docs/hi/agenteye/api-keys.mdx b/docs/hi/agenteye/api-keys.mdx index 0ff497ad..2cfc7189 100644 --- a/docs/hi/agenteye/api-keys.mdx +++ b/docs/hi/agenteye/api-keys.mdx @@ -1,172 +1,172 @@ --- title: "API कुंजियाँ" -description: "API कुंजियाँ नियंत्रित करती हैं कि कौन और क्या आपके Failproof AI Observability सर्वर तक पहुँच सकता है, जिससे एक कलेक्टर कभी भी पढ़ने या व्यवस्थापक शक्तियों को प्राप्त किए बिना ईवेंट भेज सकता है।" +description: "API कुंजियाँ नियंत्रित करती हैं कि कौन और क्या आपके Failproof AI Observability सर्वर तक पहुँच सकता है, ताकि एक कलेक्टर कभी भी रीड या एडमिन शक्तियाँ प्राप्त किए बिना इवेंट भेज सके।" --- -API कुंजियाँ नियंत्रित करती हैं कि कौन और क्या आपके Failproof AI Observability सर्वर तक पहुँच सकता है, जिससे एक कलेक्टर कभी भी पढ़ने या व्यवस्थापक शक्तियों को प्राप्त किए बिना ईवेंट भेज सकता है। प्रत्येक कुंजी एक या अधिक अनुमतियाँ रखती है, और प्रत्येक अनुमति विशिष्ट सर्वर रूट को नियंत्रित करती है; आप केवल वह अनुमतियाँ देते हैं जो एक कार्य को चाहिए। अधिकांश परिनियोजन केवल तीन प्रकार की कुंजियाँ बनाते हैं। +API कुंजियाँ नियंत्रित करती हैं कि कौन और क्या आपके Failproof AI Observability सर्वर तक पहुँच सकता है, ताकि एक कलेक्टर कभी भी रीड या एडमिन शक्तियाँ प्राप्त किए बिना इवेंट भेज सके। प्रत्येक कुंजी एक या अधिक अनुमतियाँ रखती है, और प्रत्येक अनुमति विशिष्ट सर्वर रूट्स को नियंत्रित करती है; आप केवल वह अनुमतियाँ देते हैं जो किसी कार्य को आवश्यक हैं। अधिकांश तैनातियाँ केवल तीन तरह की कुंजियाँ बनाती हैं। -## 3 कुंजियाँ जो अधिकांश परिनियोजन को चाहिए +## अधिकांश तैनातियों को आवश्यक 3 कुंजियाँ | कुंजी | अनुमतियाँ | इसका उपयोग कौन करता है | |---|---|---| -| कलेक्टर कुंजी | `events:add` | प्रत्येक एजेंट मशीन पर `agenteye-collector`, ईवेंट भेजने के लिए। | -| डैशबोर्ड पढ़ने की कुंजी | `events:read`, `keys:read` | केवल-पढ़ने वाला ऑपरेटर या एकीकरण जो डेटा को बिना बदले क्वेरी करता है। | -| बूटस्ट्रैप व्यवस्थापक कुंजी | सभी अनुमतियाँ | ऑपरेटर जो पहली बार उदाहरण को चलाता है (और डैशबोर्ड)। `ADMIN_KEY` पर्यावरण चर से बीजित। [बूटस्ट्रैप व्यवस्थापक कुंजी](#bootstrap-admin-key) देखें। | +| कलेक्टर कुंजी | `events:add` | प्रत्येक एजेंट मशीन पर `agenteye-collector`, इवेंट भेजने के लिए। | +| डैशबोर्ड रीड कुंजी | `events:read`, `keys:read` | एक रीड-ओनली ऑपरेटर या इंटीग्रेशन जो डेटा को बदले बिना क्वेरी करता है। | +| बूटस्ट्रैप एडमिन कुंजी | सभी अनुमतियाँ | ऑपरेटर जो पहली बार इंस्टेंस को चलाता है (और डैशबोर्ड)। `ADMIN_KEY` environment वेरिएबल से सीडेड। [Bootstrap admin key](#bootstrap-admin-key) देखें। | -यहाँ से शुरुआत करें। पूर्ण अनुमति सूची नीचे केवल तभी देखें जब आपको एक संकीर्ण, कस्टम-स्कोप की गई कुंजी चाहिए। [अनुशंसित कुंजी लेआउट](#recommended-key-layout) और [कुंजियाँ बनाना](#creating-keys) भी देखें। +यहाँ से शुरू करें। पूर्ण अनुमति सूची नीचे केवल तभी देखें जब आपको एक संकीर्ण, कस्टम-स्कोप की गई कुंजी की आवश्यकता हो। [Recommended key layout](#recommended-key-layout) और [Creating keys](#creating-keys) भी देखें। --- ## अनुमतियाँ -सर्वर एक निश्चित अनुमतियों की सूची को लागू करता है; प्रत्येक विशिष्ट HTTP रूट को नियंत्रित करता है। एक **व्यवस्थापक कुंजी** उन सभी को रखती है; एक स्कोप की गई कुंजी उस सबसेट को रखती है जो आप निर्माण पर देते हैं। अज्ञात अनुमति स्ट्रिंग को अस्वीकार कर दिया जाता है जब एक कुंजी बनाई जाती है। +सर्वर अनुमतियों का एक निश्चित कैटलॉग लागू करता है; प्रत्येक विशिष्ट HTTP रूट्स को नियंत्रित करता है। एक **admin key** उन सभी को रखती है; एक स्कोप्ड कुंजी वह सबसेट रखती है जो आप बनाते समय देते हैं। अज्ञात अनुमति स्ट्रिंग्स को अस्वीकार किया जाता है जब कुंजी बनाई जाती है। -> **नोट:** दो वैध अनुमतियाँ मानव/डैशबोर्ड-केवल हैं और एक API कुंजी को नहीं दी जा सकतीं: `orgs:admin` (उदाहरण प्रशासन, जो केवल ऑपरेटर के लिए है) और `keys:update`। `POST /keys` या `PATCH /keys/:id` के लिए एक अनुरोध जो इनमें से किसी एक को देने का प्रयास करता है HTTP 422 से अस्वीकार कर दिया जाता है। `keys:update` पंक्ति देखें कि क्यों एक वाहक कुंजी कुंजियाँ बना सकती है लेकिन कभी संपादित नहीं कर सकती। +> **नोट:** दो वैध अनुमतियाँ मानव/डैशबोर्ड-केवल हैं और API कुंजी को नहीं दी जा सकतीं: `orgs:admin` (इंस्टेंस प्रशासन, जो केवल ऑपरेटर के लिए है) और `keys:update`। `POST /keys` या `PATCH /keys/:id` का एक अनुरोध जो इनमें से किसी को भी देने का प्रयास करता है, HTTP 422 के साथ अस्वीकृत किया जाता है। नीचे `keys:update` पंक्ति देखें कि बेयरर कुंजी कुंजियाँ बना सकती है लेकिन कभी संपादित नहीं कर सकती क्यों। -### ईवेंट अंतर्ग्रहण और क्वेरी +### इवेंट्स इनजेस्ट और क्वेरी -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `events:add` | `POST /events` | एक कलेक्टर से ईवेंट के बैच को अंतर्ग्रहण करें। एकमात्र अनुमति जो एक कलेक्टर को चाहिए। | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | ईवेंट को क्वेरी करें, ज्ञात वातावरणों की सूची बनाएँ, डेटा में देखे गए मॉडल पहचानकर्ताओं की सूची बनाएँ (मॉडल दृश्य और मॉडल फ़िल्टर द्वारा उपयोग), अव्यवस्थित समन्वय की गणना करें जो ताप-मानचित्र / प्रतिशतक बैंड को शक्ति देता है, और एक सत्र को JSONL के रूप में निर्यात करें। साझा फ़िल्टर-बार पहलू अंतिम बिंदु `GET /events/environments` और `GET /events/agent_ids` **या तो** `events:read` **या** `evaluations:read` के साथ पहुँचने योग्य हैं, इसलिए सत्र पृष्ठ (द्वार `evaluations:read`) समान प्रति-ऑर्ग पहलू का पुन: उपयोग करता है। `GET /events/models` उनमें से एक नहीं है: इसे `events:read` की आवश्यकता है, इसलिए केवल `evaluations:read` रखने वाला एक प्रिंसिपल इससे 403 प्राप्त करता है। | +| `events:add` | `POST /events` | कलेक्टर से इवेंट्स के बैच को इनजेस्ट करें। एकमात्र अनुमति जो कलेक्टर को आवश्यक है। | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | इवेंट्स को क्वेरी करें, ज्ञात environments की सूची बनाएँ, डेटा में देखे गए मॉडल आइडेंटिफायर्स की सूची बनाएँ (Models view और मॉडल फिल्टर द्वारा उपयोग), latency aggregate की गणना करें जो heat-map / percentile band को शक्ति देता है, और एक session को JSONL के रूप में export करें। साझा फिल्टर-बार facet endpoints `GET /events/environments` और `GET /events/agent_ids` **या तो** `events:read` **या** `evaluations:read` के साथ पहुँचे जा सकते हैं, इसलिए sessions page (gated `evaluations:read`) एक ही प्रति-org facet को दोबारा उपयोग करता है। `GET /events/models` उनमें से एक नहीं है: इसे `events:read` की आवश्यकता है, इसलिए केवल `evaluations:read` रखने वाला principal इससे 403 प्राप्त करता है। | -### सत्र और मूल्यांकन +### Sessions और Evaluations -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | सत्रों की सूची बनाएँ, मूल्यांकन परिणाम पढ़ें, डैशबोर्ड द्वारा उपयोग की जाने वाली रोल-अप मूल्यांकन स्वास्थ्य, और मूल्यांकन-कार्य कार्यकर्ता कतार स्थिति। | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | एक समाप्त सत्र के लिए पुन: मूल्यांकन को मैन्युअल रूप से कतार में डालें। | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Sessions को सूचीबद्ध करें, evaluation परिणाम पढ़ें, dashboards द्वारा उपयोग किए जाने वाले rolled-up eval health, और evaluation-job worker queue state। | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | एक समाप्त session के लिए मैन्युअल रूप से re-evaluation को enqueue करें। | -### डैशबोर्ड +### डैशबोर्ड्स -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | डैशबोर्ड की सूची बनाएँ, एक को लोड करें, और इसकी टाइलें पढ़ें। | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | डैशबोर्ड बनाएँ और संपादित करें, टाइलें जोड़ें / संपादित करें / हटाएँ, और टाइल ग्रिड को पुन: क्रमबद्ध करें। | -| `dashboards:delete` | `DELETE /dashboards/:id` | एक संपूर्ण डैशबोर्ड हटाएँ (टाइल-स्तर का विलोपन `dashboards:write` के तहत रहता है)। | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Dashboards को सूचीबद्ध करें, एक को लोड करें, और इसके tiles को पढ़ें। | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Dashboards बनाएँ और संपादित करें, tiles जोड़ें / संपादित करें / हटाएँ, और tile grid को पुनः क्रमित करें। | +| `dashboards:delete` | `DELETE /dashboards/:id` | एक पूरे dashboard को हटाएँ (tile-स्तर deletion `dashboards:write` के तहत रहता है)। | -### सहेजी गई क्वेरीज़ (SQL संगीतकार) +### सहेजी गई क्वेरीज़ (SQL composer) -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | सहेजी गई क्वेरीज़ की सूची बनाएँ, एक को लोड करें, और संगीतकार लक्ष्य के केवल-पढ़ने वाले स्कीमा का निरीक्षण करें। | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | सहेजी गई क्वेरीज़ बनाएँ और संपादित करें। SQL अभी भी `queries:run` कॉल के समान केवल-पढ़ने वाली भूमिका के माध्यम से दिया जाता है और संरक्षित SQL जांच द्वारा संरक्षित है। | -| `queries:delete` | `DELETE /queries/:id` | एक सहेजी गई क्वेरी हटाएँ। | -| `queries:run` | `POST /queries/run` | संगीतकार द्वारा उपयोग की जाने वाली केवल-पढ़ने वाली भूमिका के विरुद्ध सहेजी गई या तदर्थ SQL को निष्पादित करें। | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | सहेजी गई क्वेरीज़ को सूचीबद्ध करें, एक को लोड करें, और composer द्वारा लक्षित रीड-ओनली स्कीमा की जांच करें। | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | सहेजी गई क्वेरीज़ बनाएँ और संपादित करें। SQL अभी भी `queries:run` कॉल के समान रीड-ओनली role और guarded SQL checks के माध्यम से रूट किया जाता है। | +| `queries:delete` | `DELETE /queries/:id` | सहेजी गई क्वेरी को हटाएँ। | +| `queries:run` | `POST /queries/run` | Composer द्वारा उपयोग किए जाने वाले रीड-ओनली role के विरुद्ध सहेजी गई या ad-hoc SQL को निष्पादित करें। | ### AI सहायक -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | AI सहायक से बात करें और अपनी स्वयं की (निजी) बातचीत का प्रबंधन करें। सहायक डॉक देखने के लिए **उपयोगकर्ता** पर आवश्यक; सहायक की अपनी कुंजी `dashboard-assistant` है और अलग से बीजित है (नीचे देखें)। | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | AI सहायक से बात करें और अपनी स्वयं की (निजी) बातचीत को प्रबंधित करें। सहायक dock को देखने के लिए **user** पर आवश्यक; सहायक की स्वयं की कुंजी `dashboard-assistant` है और अलग से सीडेड है (नीचे देखें)। | ### API कुंजियाँ -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `keys:create` | `POST /keys` | एक नई स्कोप की गई API कुंजी बनाएँ। मौजूदा कुंजी की अनुमतियों को संपादित करने के लिए **नहीं** देता है (वह `keys:update` है)। | -| `keys:read` | `GET /keys` | मौजूदा कुंजियों की सूची बनाएँ। गोपनीयताएँ कभी भी इस अंतिम बिंदु द्वारा नहीं दी जाती हैं। | -| `keys:update` | `PATCH /keys/:id` | मौजूदा कुंजी की अनुमतियों को संपादित करें। एक **मानव/डैशबोर्ड-केवल** अनुमति; इसे एक API कुंजी को असाइन नहीं किया जा सकता (एक वाहक कुंजी कुंजियाँ बना सकती है लेकिन उन्हें कभी संपादित नहीं कर सकती)। | -| `keys:disable` | `POST /keys/:id/disable` | एक कुंजी को रद्द करें। संरक्षित कुंजियाँ (`admin`, `dashboard-assistant`) को अक्षम नहीं किया जा सकता; env var + पुनः आरंभ के माध्यम से उन्हें घुमाएँ। | -| `keys:regenerate` | `POST /keys/:id/regenerate` | एक कुंजी की गोपनीयता को घुमाएँ। संरक्षित कुंजियों को इस रूट के माध्यम से पुन: निर्मित नहीं किया जा सकता। | +| `keys:create` | `POST /keys` | एक नई स्कोप्ड API कुंजी बनाएँ। किसी मौजूदा कुंजी की अनुमतियों को संपादित करने की अनुमति **नहीं** देता (वह `keys:update` है)। | +| `keys:read` | `GET /keys` | मौजूदा कुंजियों को सूचीबद्ध करें। Secrets इस endpoint से कभी नहीं लौटाई जाती हैं। | +| `keys:update` | `PATCH /keys/:id` | किसी मौजूदा कुंजी की अनुमतियों को संपादित करें। एक **मानव/डैशबोर्ड-केवल** अनुमति; इसे API कुंजी को असाइन नहीं किया जा सकता (एक बेयरर कुंजी कुंजियाँ बना सकती है लेकिन कभी संपादित नहीं कर सकती)। | +| `keys:disable` | `POST /keys/:id/disable` | कुंजी को रद्द करें। संरक्षित कुंजियाँ (`admin`, `dashboard-assistant`) अक्षम नहीं की जा सकतीं; env var + restart के माध्यम से इन्हें घुमाएँ। | +| `keys:regenerate` | `POST /keys/:id/regenerate` | कुंजी की secret को घुमाएँ। संरक्षित कुंजियों को इस route के माध्यम से पुनः नहीं बनाया जा सकता। | ### डैशबोर्ड उपयोगकर्ता -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | एक नए डैशबोर्ड उपयोगकर्ता को आमंत्रित करें (एक ईमेल + एकबारगी पासकोड (OTP) लॉगिन जारी करता है) और डैशबोर्ड-कॉन्फ़िगर की गई डिफ़ॉल्ट अनुमति सेट पढ़ें जो आमंत्रण फॉर्म को बीजित करने के लिए उपयोग किया जाता है। | -| `users:read` | `GET /users`, `GET /users/:id` | उपयोगकर्ताओं की सूची बनाएँ और एक एकल उपयोगकर्ता रिकॉर्ड लोड करें। | -| `users:update` | `PUT /users/:id` | एक उपयोगकर्ता की अनुमतियों को संपादित करें। अपडेट प्रभावित उपयोगकर्ता को अनुमति-परिवर्तन ईमेल भेजते हैं और उनके अगले अनुरोध पर प्रभावी होते हैं; कोई पुन: लॉगिन आवश्यक नहीं। | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | एक उपयोगकर्ता को अक्षम करें (उनके सत्र को तुरंत रद्द करता है) और पहले से अक्षम उपयोगकर्ता को पुन: सक्षम करें। | +| `users:create` | `POST /users`, `GET /users/defaults` | एक नए dashboard उपयोगकर्ता को आमंत्रित करें (ईमेल + one-time passcode (OTP) लॉगिन जारी करता है) और dashboard-कॉन्फ़िगर किए गए default permission set को पढ़ें जो invite form को सीड करता है। | +| `users:read` | `GET /users`, `GET /users/:id` | उपयोगकर्ताओं को सूचीबद्ध करें और एकल user record को लोड करें। | +| `users:update` | `PUT /users/:id` | उपयोगकर्ता की अनुमतियों को संपादित करें। Updates प्रभावित उपयोगकर्ता को permission-change ईमेल भेजते हैं और उनके अगले request पर प्रभावी होते हैं; कोई पुनः लॉगिन आवश्यक नहीं है। | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | उपयोगकर्ता को अक्षम करें (तुरंत उनके sessions को रद्द करता है) और एक पहले से अक्षम उपयोगकर्ता को दोबारा सक्षम करें। | -ये अनुमतियाँ डैशबोर्ड के **उपयोगकर्ता** पृष्ठ को समर्थन देती हैं, जहाँ प्रत्येक सदस्य के दिए गए दायरे चिप्स के रूप में दिखाए जाते हैं: +ये अनुमतियाँ dashboard के **Users** page को समर्थन देती हैं, जहाँ प्रत्येक सदस्य की दी गई scopes को chips के रूप में दिखाया जाता है: -![उपयोगकर्ता पृष्ठ: प्रत्येक डैशबोर्ड उपयोगकर्ता के लिए एक कार्ड उनके ईमेल, दी गई अनुमतियों, और संपादन/अक्षम नियंत्रण के साथ](/agenteye/images/users.png) +![Users page: dashboard उपयोगकर्ता प्रति कार्ड उनके ईमेल, दी गई अनुमतियों, और edit/disable नियंत्रण के साथ](/agenteye/images/users.png) ### परिचालन सेटिंग्स -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | डैशबोर्ड-प्रबंधित परिचालन सेटिंग्स और उनके मेटाडेटा को देखें; प्रति-मॉडल संदर्भ-विंडो ओवरराइड की सूची बनाएँ; और एक मॉडल के लिए प्रभावी विंडो को हल करें। | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | परिचालन सेटिंग्स को संपादित करें और प्रति-मॉडल संदर्भ-विंडो ओवरराइड को जोड़ें, बदलें, या हटाएँ। परिवर्तन सर्वर को पुनः आरंभ किए बिना नई ईवेंट को प्रभावित करते हैं। | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Dashboard-प्रबंधित परिचालन सेटिंग्स और उनके metadata को देखें; प्रति-मॉडल context-window overrides को सूचीबद्ध करें; और किसी मॉडल के लिए प्रभावी window को resolve करें। | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | परिचालन सेटिंग्स को संपादित करें और प्रति-मॉडल context-window overrides को जोड़ें, बदलें, या हटाएँ। नई events को बिना server को पुनः शुरू किए changes प्रभावित करते हैं। | -![सेटिंग्स पृष्ठ: डैशबोर्ड-प्रबंधित परिचालन सेटिंग्स जैसे अनुमति दी गई साइन-इन और सत्र/OTP जीवनकाल, पुनः आरंभ के बिना संपादन योग्य](/agenteye/images/settings.png) +![Settings page: dashboard-प्रबंधित परिचालन सेटिंग्स जैसे allowed sign-ins और session/OTP lifetimes, restart के बिना संपादनीय](/agenteye/images/settings.png) -### अलर्ट और घटनाएँ +### Alerts और Incidents -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | कॉन्फ़िगर किए गए अलर्ट परिभाषाओं को देखें। | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | अलर्ट परिभाषाओं को बनाएँ, संपादित करें, हटाएँ, और परीक्षण-फायर करें। | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | घटनाओं और उनके ट्रिएज ट्रेल को देखें। | -| `incidents:write` | `POST /alerts/:id/incidents` | एक मौजूदा अलर्ट के विरुद्ध मैन्युअल रूप से एक घटना खोलें। | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | घटनाओं को स्वीकार करें, असाइन करें, हल करें, और उन पर टिप्पणी करें। | +| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | कॉन्फ़िगर किए गए alert definitions को देखें। | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Alert definitions बनाएँ, संपादित करें, हटाएँ, और test-fire करें। | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Incidents और उनकी triage trail को देखें। | +| `incidents:write` | `POST /alerts/:id/incidents` | एक मौजूदा alert के विरुद्ध मैन्युअल रूप से एक incident खोलें। | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Incidents को acknowledge, assign, resolve करें, और comment करें। | -### ऑडिट +### Audits -| अनुमति | HTTP रूट | यह क्या अनुमति देता है | +| अनुमति | HTTP रूट्स | यह क्या अनुमति देता है | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | ऑडिट परिभाषाओं, चलाने का इतिहास, और निष्कर्ष देखें। | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | ऑडिट बनाएँ, संपादित करें, हटाएँ, और चलाएँ; निष्कर्षों को ट्रिएज करें (स्वीकार करें / म्यूट करें / खारिज करें / हल करें / फिर से खोलें / असाइन करें)। | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Audit definitions, run history, और findings को देखें। | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Audits बनाएँ, संपादित करें, हटाएँ, और चलाएँ; findings को triage करें (acknowledge / mute / dismiss / resolve / reopen / assign)। | -> **नोट:** एक कुंजी को ऑडिट सतह देने के लिए, इसे `audits:*` को स्पष्ट रूप से दें। [अपग्रेड और बैकवर्ड-संगतता नोट्स](#upgrade-and-backward-compatibility-notes) देखें कि जब ऑडिट आया तो मौजूदा अनुदानकर्ताओं को कैसे माइग्रेट किया गया। +> **नोट:** कुंजी को audit surface देने के लिए, स्पष्ट रूप से `audits:*` को इसे दें। [Upgrade and backward-compatibility notes](#upgrade-and-backward-compatibility-notes) देखें कि Audits shipped होने पर मौजूदा grantees को कैसे माइग्रेट किया गया। -> प्राप्तकर्ता-पिकर अंतिम बिंदु `GET /alerts/recipients` (जो सदस्य ईमेल सूचीबद्ध करता है एक अलर्ट संपादक को सूचित कर सकता है) **या तो** `alerts:read` **या** `alerts:write` के धारक द्वारा पहुँचने योग्य है, इसलिए अलर्ट संपादक बिना `users:read` को दिए गए पिकर को पॉप्युलेट कर सकते हैं। +> Recipient-picker endpoint `GET /alerts/recipients` (जो member emails की सूची बनाता है जिसे alert editor सूचित कर सकते हैं) **या तो** `alerts:read` **या** `alerts:write` के होल्डर द्वारा पहुँचा जा सकता है, ताकि alert editors को `users:read` दिए बिना picker को भर सकें। -> एक डैशबोर्ड दर्शक को **दोनों** `dashboards:read` (सहेजे गए दृश्यों को लोड करने के लिए) और `evaluations:read` (स्वास्थ्य मेट्रिक्स मूल्यांकन डेटा से गणना की जाती हैं) की आवश्यकता होती है। डैशबोर्ड बनाने या संपादित करने देने के लिए `dashboards:write` दें, और उन्हें हटाने के लिए `dashboards:delete` दें। +> एक dashboards viewer को **दोनों** `dashboards:read` (सहेजे गए views को लोड करने के लिए) और `evaluations:read` (health metrics evaluation data से compute किए जाते हैं) की आवश्यकता है। Dashboards बनाने या संपादित करने के लिए उपयोगकर्ता को `dashboards:write` दें, और उन्हें हटाने के लिए `dashboards:delete` दें। -> `/health` और `/auth/*` (OTP अनुरोध, OTP सत्यापन, सत्र जांच, लॉगआउट) डिज़ाइन द्वारा प्रमाणीकृत नहीं हैं; वे लॉगिन प्रवाह और जीविता जांच हैं। `GET /access-granters` एक वैध कुंजी की आवश्यकता है लेकिन कोई विशिष्ट अनुमति नहीं, इसलिए कोई भी लॉगिन उपयोगकर्ता देख सकता है कि किन व्यवस्थापकों से संपर्क करना है। +> `/health` और `/auth/*` (OTP request, OTP verify, session check, logout) डिज़ाइन द्वारा unauthenticated हैं; वे login flow और liveness probe हैं। `GET /access-granters` को एक वैध कुंजी की आवश्यकता है लेकिन कोई विशिष्ट अनुमति नहीं, इसलिए कोई भी लॉगिन उपयोगकर्ता देख सकता है कि access changes के बारे में किस admin से संपर्क करें। --- -## अनुमति सेट +## अनुमति सेट्स -अनुमति सेट आपको प्रत्येक बार व्यक्तिगत टोकन को चुनने के बजाय एक नामित भूमिका को लागू करने देते हैं। प्रत्येक नए डैशबोर्ड उपयोगकर्ता या API कुंजी के लिए एक दर्जन अनुमतियों को एक-एक करके चुनने के बजाय, आप एक सेट चुनते हैं, और हर कोई इसे असाइन किया गया एक सुसंगत, समीक्षक अनुदान रखता है। एक कस्टम सेट को संपादित करने से पहले से ही इसे असाइन किए गए हर उपयोगकर्ता को नई अनुदान को पुन: लागू किया जाता है, इसलिए एक भूमिका परिवर्तन एक संपादन है बजाय हर सदस्य के माध्यम से एक स्वीप। +अनुमति सेट्स आपको हर बार hand-pick किए गए individual tokens के बजाय एक नामित role लागू करने देते हैं। प्रत्येक नए dashboard user या API key के लिए दर्जन भर अनुमतियों को एक-एक करके चुनने के बजाय, आप एक set चुनते हैं, और इसे assigned सभी को एक सुसंगत, reviewable grant मिलता है। एक कस्टम set को संपादित करना इसे पहले से assigned हर उपयोगकर्ता को नई grant को फिर से लागू करता है, इसलिए एक role change हर सदस्य के माध्यम से sweep के बजाय एक edit है। -हर संगठन को तीन अंतर्निहित सेट के साथ बीजित किया जाता है: +प्रत्येक organization को तीन built-in sets के साथ सीडेड किया जाता है: -| सेट | अनुमतियाँ | के लिए इरादा | +| Set | अनुमतियाँ | के लिए अभिप्रेत | |---|---|---| -| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | हर परिचालन सतह में केवल-दृश्य पहुँच। | -| `standard` | `read-only` में सब कुछ, प्लस `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | केवल-पढ़ें प्लस रोज़मर्रा के ऑन-कॉलर कार्य: क्वेरीज़ चलाएँ, सत्रों को पुन: मूल्यांकन करें, घटनाओं को स्वीकार करें, और AI सहायक का उपयोग करें। | -| `admin` | हर असाइन करने योग्य अनुमति | ऑर्ग का पूर्ण नियंत्रण। | +| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | हर परिचालन सतह पर view-only access। | +| `standard` | `read-only` में सब कुछ, साथ ही `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | रीड-ओनली साथ ही रोज़मर्रा के on-caller actions: queries चलाएँ, sessions को re-evaluate करें, incidents को acknowledge करें, और AI सहायक का उपयोग करें। | +| `admin` | हर assignable अनुमति | org का पूर्ण नियंत्रण। | -तीन अंतर्निहित सेट **अपरिवर्तनीय** हैं; उनके नाम हमेशा समान बात का मतलब रखते हैं, इसलिए `read-only`, `standard`, और `admin` नीति और ऑनबोर्डिंग में संदर्भित करना सुरक्षित है। एक ऑपरेटर आपके संगठन के लिए विशिष्ट भूमिकाओं को मॉडल करने के लिए अतिरिक्त **कस्टम सेट** बना सकता है (उदाहरण के लिए, एक "डैशबोर्ड लेखक" भूमिका या एक "कलेक्टर-केवल" भूमिका)। +तीन built-in sets **immutable** हैं; उनके नाम हमेशा एक ही चीज़ का अर्थ रखते हैं, इसलिए `read-only`, `standard`, और `admin` policy और onboarding में reference करने के लिए safe हैं। एक ऑपरेटर आपके organization के लिए विशिष्ट roles को मॉडल करने के लिए अतिरिक्त **custom sets** बना सकता है (उदाहरण के लिए, एक "dashboard author" role या "collector-only" role)। -सेट डैशबोर्ड में सतह पर आते हैं और `GET /permission-sets` पर API के माध्यम से प्रबंधित होते हैं (सूची, `users:read` द्वारा द्वारपाल) और `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (कस्टम सेट बनाएँ, संपादित करें, हटाएँ, `settings:write` द्वारा द्वारपाल)। अंतर्निहित सेट को हटाना या संपादित करना अस्वीकार कर दिया जाता है। +Sets को dashboard में surface किया जाता है और API के माध्यम से `GET /permission-sets` (सूचीबद्ध, `users:read` द्वारा gated) और `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (कस्टम set बनाएँ, संपादित करें, हटाएँ, `settings:write` द्वारा gated) पर प्रबंधित किया जाता है। एक built-in set को हटाना या संपादित करना अस्वीकार किया जाता है। -सेट सदस्यता दो अन्य सुविधाओं को समर्थन देता है: +Set membership दो अन्य features को समर्थन देता है: -- **`DEFAULT_USER_PERMISSIONS`** (जब एक व्यवस्थापक **+ नया उपयोगकर्ता** खोलता है तो पूर्व-चयनित अनुदान) डिफ़ॉल्ट `standard` सेट के लिए। -- **`--set` फ़्लैग** `agenteye-orgctl` पर (ऑपरेटर सदस्य प्रबंधन) एक सदस्य को एक नामित सेट से शुरू करता है, जिसे आप फिर `--add` / `--remove` के साथ ठीक-ट्यून करते हैं। +- **`DEFAULT_USER_PERMISSIONS`** (जब admin **+ new user** खोलते हैं तो preselected grant) `standard` set को डिफ़ॉल्ट करता है। +- **`--set` flag** on `agenteye-orgctl` (ऑपरेटर सदस्य प्रबंधन) एक सदस्य को एक नामित set से शुरू करता है, जिसे आप फिर `--add` / `--remove` के साथ fine-tune करते हैं। -> **नोट:** जब एक सेट एक अनुमति को शामिल करता है जो कुंजी-असाइन करने योग्य नहीं है (उदाहरण के लिए `keys:update` रखने वाला कस्टम सेट), उस सेट से एक कुंजी को बीजित करने से गैर-असाइन करने योग्य टोकन को छोड़ दिया जाता है; सर्वर अन्यथा HTTP 422 से कुंजी को अस्वीकार कर देगा। डैशबोर्ड **उपयोगकर्ता** उस प्रतिबंध के अधीन नहीं हैं। +> **नोट:** जब एक set एक अनुमति को शामिल करता है जो key-assignable नहीं है (उदाहरण के लिए एक कस्टम set `keys:update` रखता है), उस set से एक key को सीड करना non-assignable tokens को ड्रॉप करता है; सर्वर अन्यथा कुंजी को HTTP 422 के साथ अस्वीकार करेगा। Dashboard users उस प्रतिबंध के अधीन नहीं हैं। --- -## बूटस्ट्रैप व्यवस्थापक कुंजी +## बूटस्ट्रैप एडमिन कुंजी -व्यवस्थापक कुंजी एकल मूल क्रेडेंशियल है जो एक ऑपरेटर को कुछ भी नहीं से एक्सेस को लाया जा सकता है: इसके साथ आप हर अन्य स्कोप की गई कुंजी को टकसाली कर सकते हैं, पहले डैशबोर्ड उपयोगकर्ताओं को आमंत्रित कर सकते हैं, और किसी भी अन्य कुंजी अस्तित्व से पहले उदाहरण को कॉन्फ़िगर कर सकते हैं। यह एकमात्र कुंजी है जो आप कुंजी API के माध्यम से नहीं बनाते हैं; इसे पर्यावरण से प्रदान किया जाता है इसलिए सर्वर पहले बूट पर पहुँचने योग्य है। +Admin key एकल root credential है जो एक ऑपरेटर को कुछ नहीं से access लाना शुरू करने देता है: इसके साथ आप हर दूसरी स्कोप्ड कुंजी mint कर सकते हैं, पहले dashboard users को आमंत्रित कर सकते हैं, और किसी अन्य कुंजी के अस्तित्व से पहले इंस्टेंस को कॉन्फ़िगर कर सकते हैं। यह वह एक कुंजी है जो आप keys API के माध्यम से बनाते नहीं हैं; इसे environment से प्रावधानित किया जाता है ताकि सर्वर पहली बूट पर पहुँचा जा सके। -सर्वर पर `ADMIN_KEY` पर्यावरण चर सेट करें। हर स्टार्टअप पर सर्वर इस मान को एक व्यवस्थापक कुंजी के रूप में सभी अनुमतियों के साथ अपसर्ट करता है। +सर्वर पर `ADMIN_KEY` environment variable सेट करें। हर startup पर सर्वर इस मान को सभी अनुमतियों के साथ एक admin key के रूप में upsert करता है। -घुमाने के लिए: `ADMIN_KEY` को एक नई गोपनीयता में बदलें और सर्वर को पुनः आरंभ करें। +घुमाने के लिए: `ADMIN_KEY` को एक नई secret में बदलें और सर्वर को पुनः शुरू करें। --- -## संगठन स्कोपिंग +## Organization scoping -**संगठन स्वयं ऑपरेटर द्वारा बैंड से बाहर बनाए और प्रबंधित किए जाते हैं, इस कुंजी API के माध्यम से नहीं।** ऑर्ग और सदस्य जीवनचक्र (एक ऑर्ग बनाएँ / नाम दें / हटाएँ / शुद्ध करें; एक सदस्य जोड़ें / अपडेट करें / हटाएँ) **`agenteye-orgctl`** CLI के साथ किया जाता है; इसके लिए कोई HTTP API या डैशबोर्ड बटन नहीं है। क्या *अपरिवर्तित है*: **प्रति-ऑर्ग API कुंजियाँ अभी भी डैशबोर्ड में टकसाली होती हैं (या इस कुंजी API के माध्यम से)** ऑर्ग सदस्यों द्वारा। +**Organizations को स्वयं को एक ऑपरेटर द्वारा out-of-band बनाया और प्रबंधित किया जाता है, इस keys API के माध्यम से नहीं।** Org और member lifecycle (एक org बनाएँ / नाम बदलें / हटाएँ / purge करें; एक सदस्य को जोड़ें / अपडेट करें / हटाएँ) **`agenteye-orgctl`** CLI के साथ किया जाता है; इसके लिए कोई HTTP API या dashboard बटन नहीं है। क्या *is* unchanged है: **प्रति-org API keys अभी भी dashboard (या इस keys API के माध्यम से) में org सदस्यों द्वारा mint किए जाते हैं**। -एक मल्टी-ऑर्ग परिनियोजन में, हर कुंजी एक ऑर्ग सदस्य बनाता है (इस कुंजी API या डैशबोर्ड **कुंजियाँ** पृष्ठ के माध्यम से) **एक संगठन** के अंतर्गत आता है और केवल कभी भी उस ऑर्ग के डेटा को पढ़ या लिख सकता है; ऑर्ग निर्माण पर कुंजी पर स्टैम्प किया जाता है और हर अनुरोध पर लागू किया जाता है। दो बूटस्ट्रैप कुंजियाँ एकमात्र अपवाद हैं: `admin` कुंजी (`ADMIN_KEY` से बीजित) और `dashboard-assistant` कुंजी (`AGENT_API_KEY` से बीजित) **उदाहरण-स्कोप किए गए** हैं (वे कोई ऑर्ग नहीं रखते हैं)। डैशबोर्ड `admin` कुंजी के साथ प्रमाणीकरण करता है इसलिए यह हस्ताक्षरित सदस्यों की ओर से प्रति-ऑर्ग अनुरोधों को प्रॉक्सी कर सकता है। एकल-किरायेदार परिनियोजन को इसके बारे में सोचना पड़ता है नहीं; सभी कुंजियाँ अंतर्निहित `default` ऑर्ग के अंतर्गत आती हैं। +एक multi-org deployment में, एक org member बनाई गई हर कुंजी (इस keys API या dashboard **Keys** page के माध्यम से) **एक organization** को belongs करती है और केवल उस org के डेटा को read या write कर सकती है; org बनाते समय कुंजी पर stamped होता है और हर request पर enforced होता है। दो bootstrap keys एकमात्र exception हैं: `admin` key (`ADMIN_KEY` से सीडेड) और `dashboard-assistant` key (`AGENT_API_KEY` से सीडेड) **instance-scoped** हैं (वे कोई org नहीं रखते)। Dashboard `admin` key के साथ authenticates करता है ताकि यह signed-in सदस्यों की ओर से per-org requests को proxy कर सके। Single-tenant deployments को इसके बारे में सोचने की ज़रूरत नहीं है; सभी कुंजियाँ built-in `default` org को belong करती हैं। --- ## कुंजियाँ बनाना -व्यवस्थापक कुंजी (या `keys:create` अनुमति रखने वाली किसी भी कुंजी) का उपयोग करके अतिरिक्त स्कोप की गई कुंजियाँ बनाएँ। +अतिरिक्त स्कोप्ड कुंजियाँ बनाने के लिए admin key (या `keys:create` अनुमति के साथ कोई भी key) का उपयोग करें। -### कलेक्टर कुंजी (केवल अंतर्ग्रहण) +### कलेक्टर कुंजी (केवल ingest) ```bash curl -s -X POST http://your-server/keys \ @@ -179,7 +179,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### डैशबोर्ड कुंजी (केवल पढ़ें) +### डैशबोर्ड कुंजी (केवल rread) ```bash curl -s -X POST http://your-server/keys \ @@ -192,7 +192,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -जब आप HTTP API पर एक कुंजी बनाते हैं, तो आप स्वयं `key` मान प्रदान करते हैं; एक मजबूत गोपनीयता चुनें और इसे सुरक्षित रूप से स्टोर करें। (डैशबोर्ड दूसरे तरीके से काम करता है: यह आपके लिए एक मजबूत गोपनीयता उत्पन्न करता है और निर्माण पर इसे एक बार दिखाता है; [डैशबोर्ड में कुंजी प्रबंधन](#key-management-in-the-dashboard) देखें।) प्रतिक्रिया की पुष्टि करती है कि कुंजी बनाई गई थी: +जब आप HTTP API के माध्यम से एक कुंजी बनाते हैं, तो आप `key` मान को स्वयं provide करते हैं; एक strong secret चुनें और इसे securely store करें। (Dashboard दूसरे तरीके से काम करता है: यह आपके लिए एक strong secret generate करता है और इसे बनाते समय एक बार दिखाता है; [Key Management in the Dashboard](#key-management-in-the-dashboard) देखें।) Response पुष्टि करता है कि कुंजी created हुई थी: ```json { @@ -205,20 +205,20 @@ curl -s -X POST http://your-server/keys \ --- -## कुंजियों की सूची बनाना +## कुंजियों को सूचीबद्ध करना ```bash curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -कुंजी गोपनीयताएँ सूची प्रतिक्रिया में नहीं लौटाई जाती हैं, केवल IDs, नाम, और अनुमतियाँ। +Key secrets को सूचीबद्ध responses में return नहीं किया जाता है, केवल IDs, names, और permissions। --- -## एक कुंजी को अक्षम करना +## कुंजी को अक्षम करना -अक्षम करना कुंजी रिकॉर्ड को हटाए बिना तुरंत एक्सेस को रद्द करता है। +अक्षम करना कुंजी record को हटाए बिना तुरंत access को रद्द करता है। ```bash curl -s -X POST http://your-server/keys//disable \ @@ -227,53 +227,53 @@ curl -s -X POST http://your-server/keys//disable \ --- -## एक कुंजी को पुन: उत्पन्न करना +## कुंजी को पुनः उत्पन्न करना -एक मौजूदा कुंजी के लिए एक नई गोपनीयता उत्पन्न करता है। पुरानी गोपनीयता तुरंत अमान्य कर दी जाती है। +मौजूदा कुंजी के लिए एक नई secret generate करता है। पुरानी secret तुरंत invalidated है। ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -प्रतिक्रिया में नई सादा पाठ गोपनीयता शामिल है, **केवल एक बार दिखाई दी**। +Response नई plaintext secret को शामिल करता है, **केवल एक बार दिखाई गई**। --- ## डैशबोर्ड में कुंजी प्रबंधन -डैशबोर्ड में **कुंजियाँ** पृष्ठ उपरोक्त सभी कार्यों के लिए एक UI प्रदान करता है। सूची को देखने के लिए आपको `keys:read` अनुमति के साथ एक कुंजी चाहिए, और क्रमशः निर्माण / संपादन / अक्षम / पुन: उत्पन्न कार्यों के लिए `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate`। एक कुंजी की अनुमतियों को संपादित करना (`keys:update`) एक बनाने (`keys:create`) से अलग है, इसलिए आप एक ऑपरेटर को कुंजियों को टकसाली करने की क्षमता दे सकते हैं बिना मौजूदा कुंजियों को पुन: स्कोप करने की क्षमता के, या इसके विपरीत। व्यवस्थापक कुंजी इन सभी को कवर करती है। +Dashboard में **Keys** page ऊपर के सभी operations के लिए एक UI प्रदान करता है। सूची को देखने के लिए आपको `keys:read` अनुमति के साथ एक कुंजी की आवश्यकता है, और create / edit / disable / regenerate actions के लिए क्रमशः `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate`। एक कुंजी की अनुमतियों को संपादित करना (`keys:update`) एक बनाने (`keys:create`) से अलग है, इसलिए आप एक ऑपरेटर को कुंजियाँ mint करने की क्षमता दे सकते हैं बिना मौजूदा कुंजियों को re-scope करने की क्षमता दिए, या इसके विपरीत। Admin key इन सभी को कवर करता है। -जब आप डैशबोर्ड से एक कुंजी बनाते हैं तो आप गोपनीयता की आपूर्ति नहीं करते हैं; डैशबोर्ड आपके लिए एक मजबूत गोपनीयता उत्पन्न करता है और इसे **एक बार** निर्माण पर प्रदर्शित करता है। इसे तुरंत कॉपी करें और सुरक्षित रूप से स्टोर करें; यह कभी फिर से दिखाया नहीं जाता है, एक पुन: उत्पन्न के समान ही। आप अभी भी कुंजी की अनुमतियों को सीधे चुन सकते हैं, या एक अनुमति सेट से उन्हें बीजित कर सकते हैं (नीचे देखें)। +जब आप dashboard से कुंजी बनाते हैं तो आप secret supply नहीं करते; dashboard आपके लिए एक strong secret generate करता है और इसे बनाते समय **एक बार** display करता है। इसे तुरंत copy करें और securely store करें; यह कभी दोबारा नहीं दिखाया जाता है, बिल्कुल एक regenerate की तरह। आप अभी भी कुंजी की अनुमतियों को सीधे चुन सकते हैं, या उन्हें एक अनुमति set से seed कर सकते हैं (नीचे देखें)। -![API कुंजियाँ पृष्ठ: प्रत्येक कुंजी के लिए एक कार्ड इसके नाम, दी गई अनुमतियों, और निर्माण समय के साथ, पुन: उत्पन्न और अक्षम कार्य; `admin` जैसी संरक्षित कुंजियाँ चिह्नित हैं](/agenteye/images/api-keys.png) +![API Keys page: कुंजी प्रति कार्ड इसके नाम, दी गई अनुमतियों, और creation time के साथ, regenerate और disable actions के साथ; `admin` जैसी protected keys marked हैं](/agenteye/images/api-keys.png) --- ## अनुशंसित कुंजी लेआउट -| कुंजी | अनुमतियाँ | का उपयोग कौन करता है | +| कुंजी | अनुमतियाँ | किसके द्वारा उपयोग किया जाता है | |---|---|---| -| `admin` (`ADMIN_KEY` env var के माध्यम से बूटस्ट्रैप) | सभी | Ops/सेटअप, और डैशबोर्ड (`ADMIN_KEY` के साथ प्रमाणीकरण, अनुमति जांच के साथ उपयोगकर्ता अनुरोधों को प्रॉक्सी) | -| प्रति-होस्ट कलेक्टर कुंजी | `events:add` | प्रत्येक एजेंट मशीन पर कलेक्टर | -| `dashboard-assistant` (`AGENT_API_KEY` env var के माध्यम से बूटस्ट्रैप) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI सहायक, स्वचालित रूप से बीजित, **संरक्षित**; API के माध्यम से संपादित नहीं किया जा सकता | -| सहायक टेलीमेट्री कुंजी (वैकल्पिक) | `events:add` | AI सहायक आत्म-प्रवृत्तिकरण, यदि सक्षम है | +| `admin` (`ADMIN_KEY` env var के माध्यम से bootstrap) | सभी | Ops/setup, और dashboard (authenticates `ADMIN_KEY` के साथ, permission checks के साथ user requests को proxy करता है) | +| प्रति-host collector key | `events:add` | प्रत्येक एजेंट मशीन पर Collector | +| `dashboard-assistant` (`AGENT_API_KEY` env var के माध्यम से bootstrap) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI सहायक, स्वचालित रूप से सीडेड, **protected**; API के माध्यम से संपादित नहीं किया जा सकता | +| Assistant telemetry key (optional) | `events:add` | AI सहायक self-instrumentation, यदि enabled हो | -> **नोट:** सहायक की कुंजी **स्वचालित रूप से बीजित** की जाती है सर्वर द्वारा `AGENT_API_KEY` env var से (वही गोपनीयता जो एजेंट `AGENTEYE_API_KEY` के रूप में प्रस्तुत करता है); कोई मैन्युअल कुंजी-मिंटिंग चरण नहीं है और कोई व्यवस्थापक कुंजी शामिल नहीं है। इसकी अनुमतियाँ स्रोत कोड में तय की जाती हैं इसलिए स्कोप को गलतफहमी से व्यापक नहीं किया जा सकता: ईवेंट / मूल्यांकन / डैशबोर्ड में पढ़ें, प्लस डैशबोर्ड-लेखन और क्वेरीज-पढ़ें / लिखें / चलाएँ AI से क्वेरी लिखने के लिए कहने के लिए। सभी SQL अभी भी उसी केवल-पढ़ने वाली भूमिका और संरक्षित SQL पथ के माध्यम से जाता है एक उपयोगकर्ता-लिखी गई क्वेरी के रूप में, इसलिए यह *लेखन सतह* को व्यापक करता है, डेटा सतह नहीं; विनाशकारी कार्य (`queries:delete`, `dashboards:delete`) जानबूझकर सहायक कुंजी से दूर रहते हैं। `admin` कुंजी की तरह, यह **संरक्षित** है: इसे कुंजी API के माध्यम से अक्षम या पुन: उत्पन्न नहीं किया जा सकता, केवल `AGENT_API_KEY` को बदलकर और पुनः आरंभ करके घुमाया जा सकता है। डैशबोर्ड **उपयोगकर्ता** अतिरिक्त रूप से सहायक को देखने और उपयोग करने के लिए `agent:use` अनुमति की आवश्यकता होती है। यदि आप आत्म-प्रवृत्तिकरण सक्षम करते हैं, तो सहायक को एक अलग `events:add`-केवल कुंजी दें। +> **नोट:** सहायक की कुंजी `AGENT_API_KEY` env var (agent `AGENTEYE_API_KEY` के रूप में प्रस्तुत करने वाली समान secret) से server द्वारा **स्वचालित रूप से सीडेड** होती है; कोई मैन्युअल key-minting step नहीं है और कोई admin key शामिल नहीं है। इसकी अनुमतियाँ source code में fixed हैं इसलिए scope को misconfiguration द्वारा नहीं चौड़ा किया जा सकता: events / evaluations / dashboards में read, साथ ही dashboards-write और queries-read / write / run the "Ask AI to write a query" authoring flow के लिए। सभी SQL अभी भी एक user-written query के समान रीड-ओनली role और guarded SQL path के माध्यम से जाता है, इसलिए यह *authoring surface* को चौड़ा करता है, data surface को नहीं; destructive operations (`queries:delete`, `dashboards:delete`) जानबूझकर assistant key से बाहर रहते हैं। `admin` key की तरह, यह **protected** है: इसे keys API के माध्यम से अक्षम या पुनः नहीं बनाया जा सकता, केवल `AGENT_API_KEY` बदलकर और पुनः शुरू करके rotated किया जा सकता है। Dashboard *users* को अतिरिक्त रूप से सहायक को देखने और उपयोग करने के लिए `agent:use` अनुमति की आवश्यकता है। यदि आप self-instrumentation को enable करते हैं, सहायक को एक अलग `events:add`-only key दें। --- -## अपग्रेड और बैकवर्ड-संगतता नोट्स +## अपग्रेड और backward-compatibility notes -आपको इन्हीं की आवश्यकता है यदि आप एक मौजूदा उदाहरण को अपग्रेड कर रहे हैं; नई परिनियोजन इन्हें छोड़ सकती है। +आपको इनकी आवश्यकता केवल तभी है यदि आप एक मौजूदा इंस्टेंस को upgrade कर रहे हैं; नई deployments इन्हें छोड़ सकती हैं। -> जब ऑडिट आया, मौजूदा अनुदानकर्ताओं को अलर्ट के समान भूमिका आकार के साथ व्यापक किया गया: हर उपयोगकर्ता और `alerts:read` रखने वाली अनुमति सेट `audits:read` प्राप्त की, और `alerts:write` के हर धारक को `audits:write` मिला। मौजूदा API कुंजियों को **नहीं** व्यापक किया गया। यदि इसे ऑडिट सतह चाहिए तो एक कुंजी को स्पष्ट रूप से `audits:*` दें। +> जब Audits shipped हुई, मौजूदा grantees को alerts के समान role shapes के साथ चौड़ा किया गया: हर user और permission set `alerts:read` रखने वाली को `audits:read` मिली, और हर `alerts:write` की holder को `audits:write` मिली। मौजूदा API keys को **नहीं** चौड़ा किया गया। यदि कुंजी को audit surface की आवश्यकता है तो स्पष्ट रूप से `audits:*` दें। -> विरासत `alerts:ack` टोकन के भंडारीकृत अनुदान `incidents:ack` के रूप में पार्स किए जाते हैं इसलिए ऑन-कॉलर पुनः कीइंग के बिना एक्सेस को बनाए रखते हैं। टोकन अब डैशबोर्ड के उपयोगकर्ता संपादक से असाइन करने योग्य नहीं है; मैट्रिक्स `incidents:ack` की पेशकश करता है। +> Legacy `alerts:ack` token की stored grants को `incidents:ack` के रूप में parsed किया जाता है इसलिए on-callers rekeying के बिना access रखते हैं। Token अब dashboard के user editor से assignable नहीं है; matrix `incidents:ack` को offer करता है। --- ## अगले कदम -- [Python SDK](/hi/agenteye/python-sdk): कैसे आपका एजेंट कोड प्रमाणीकृत होता है जब ईवेंट भेज रहा हो। -- [सुरक्षा](/hi/agenteye/security): साइन-इन, एक्सेस नियंत्रण, और प्रति-संगठन डेटा अलगाव कैसे काम करता है। \ No newline at end of file +- [Python SDK](/hi/agenteye/python-sdk): आपकी agent code कैसे authenticates करती है जब इवेंट्स भेजते हैं। +- [Security](/hi/agenteye/security): कैसे sign-in, access control, और per-organization data isolation काम करते हैं। \ No newline at end of file diff --git a/docs/hi/agenteye/assistant.mdx b/docs/hi/agenteye/assistant.mdx index 9ca76e7d..5532ccf1 100644 --- a/docs/hi/agenteye/assistant.mdx +++ b/docs/hi/agenteye/assistant.mdx @@ -1,59 +1,59 @@ --- -title: "AI सहायक" -description: "अपने एजेंट डेटा से सामान्य अंग्रेजी में प्रश्न पूछें और ऐसा उत्तर प्राप्त करें जो सीधे साक्ष्य से जुड़ा हो।" +title: "AI असिस्टेंट" +description: "अपने एजेंट डेटा से सादी अंग्रेजी में कोई सवाल पूछें और ऐसा उत्तर पाएं जो सीधे प्रमाण से जुड़ा हो।" --- -अपने एजेंट डेटा से सामान्य अंग्रेजी में प्रश्न पूछें और ऐसा उत्तर प्राप्त करें जो सीधे साक्ष्य से जुड़ा हो। कोई SQL लिखने की आवश्यकता नहीं, डैशबोर्ड को खोदने की जरूरत नहीं — **Failproof AI Observability** सहायक आपकी टीम के किसी भी सदस्य के लिए एजेंट्स के बारे में उत्तर पाने का सबसे तेज तरीका है। +अपने एजेंट डेटा से सादी अंग्रेजी में कोई सवाल पूछें और ऐसा उत्तर पाएं जो सीधे प्रमाण से जुड़ा हो। कोई SQL लिखने की जरूरत नहीं, कोई डैशबोर्ड खोदने की जरूरत नहीं — **Failproof AI Observability** असिस्टेंट आपकी टीम के किसी भी सदस्य को अपने एजेंट के बारे में उत्तर पाने का सबसे तेज तरीका है। -![Failproof AI Observability सहायक डैशबोर्ड के अंदर एक सामान्य-अंग्रेजी प्रश्न का उत्तर दे रहा है, जो एक लाइव एजेंट एक्टिविटी टेबल, प्रति-एजेंट मॉडल-उपयोग विभाजन और लिखित निष्कर्ष दिखा रहा है, जिसमें यह दिखाए गए क्वेरीज इनलाइन हैं](/agenteye/images/assistant.png) -*सामान्य अंग्रेजी में पूछें और अपने स्वयं के डेटा से बनाया गया उत्तर प्राप्त करें। यहां यह दिखाता है कि कौन से एजेंट सबसे व्यस्त हैं और वे किन मॉडल का उपयोग करते हैं, और यह दिखाता है कि यह किन क्वेरीज को चलाता है ताकि आप प्रत्येक संख्या को सत्यापित कर सकें।* +![Failproof AI Observability असिस्टेंट डैशबोर्ड के अंदर एक सादे अंग्रेजी के सवाल का जवाब दे रहा है, जिसमें लाइव एजेंट एक्टिविटी टेबल, प्रति-एजेंट मॉडल-उपयोग ब्रेकडाउन, और लिखित निष्कर्ष दिख रहे हैं, साथ ही जो क्वेरी चलाई गईं वह इनलाइन दिखाई दे रही हैं](/agenteye/images/assistant.png) +*सादी अंग्रेजी में पूछें और अपने स्वयं के डेटा से बना उत्तर पाएं। यह दिखाता है कि कौन से एजेंट सबसे ज्यादा व्यस्त हैं और वे कौन से मॉडल का उपयोग करते हैं, और जो क्वेरी चलाई गईं उन्हें दिखाता है ताकि आप हर संख्या को सत्यापित कर सकें।* -सीखने के लिए कुछ नहीं है। चैट खोलें, टाइप करें कि आप क्या जानना चाहते हैं, और इसके द्वारा दिए गए लिंक का पालन करें: +कुछ भी सीखने की जरूरत नहीं है। चैट खोलें, वह टाइप करें जो आप जानना चाहते हैं, और जो लिंक यह वापस देता है उनका अनुसरण करें: ``` -You: which sessions errored today? -AI: 5 sessions errored today, newest first. Each one is linked: - • checkout-agent 14:02 tool timeout - • billing-agent 11:47 unhandled error - • ...and 3 more - -You: summarize this session (asked while viewing a run) -AI: This run took 12 steps across 3 tools and failed near the end when a - payment tool returned an error. It scored low on your "resolved" eval. - Links: the session, the failing event, and that evaluation. +आप: आज कौन से सेशन एरर हुए? +AI: आज 5 सेशन एरर हुए, सबसे नए पहले। हर एक लिंक किया है: + • checkout-agent 14:02 tool timeout + • billing-agent 11:47 unhandled error + • ...और 3 और + +आप: इस सेशन को सारांश दें (एक रन देखते समय पूछा) +AI: यह रन 3 टूल्स के पार 12 कदम उठाया और अंत के पास विफल हुआ जब + एक पेमेंट टूल ने एक एरर रिटर्न किया। इसने आपके "resolved" eval पर + कम स्कोर किया। लिंक: सेशन, विफल इवेंट, और वह मूल्यांकन। ``` -## बस पूछें और सीधे प्रमाण पर जाएं +## बस पूछें, और सीधे प्रमाण तक जाएं -आप अनुमान लगाना बंद करते हैं और आप क्वेरीज लिखना बंद करते हैं। पूछें "इस सप्ताह प्रोड में गुणवत्ता कैसी है?", "आज कौन से सेशन एरर हुए?", या "इस सेशन को सारांशित करें", और आप सेकंड में सीधा उत्तर पाते हैं, क्वेरी बनाने और स्वयं पढ़ने के बजाय। +आप अनुमान लगाना बंद करते हैं और आप क्वेरी लिखना बंद करते हैं। "इस हफ्ते prod में क्वालिटी कैसे ट्रेंड कर रही है?", "आज कौन से सेशन एरर हुए?", या "इस सेशन को सारांश दें," पूछें, और आप कुछ सेकंड में एक सीधा उत्तर पाते हैं, एक क्वेरी बनाने और स्वयं इसे पढ़ने के बजाय। -हर उत्तर अपनी रसीद के साथ आता है। सहायक सटीक सेशन, सहेजी गई क्वेरीज, और डैशबोर्ड को जोड़ता है जिसका यह उत्तर तक पहुंचने के लिए उपयोग करता है, ताकि आप क्लिक करके पुष्टि कर सकें और इसके शब्दों पर विश्वास न करें। यह **पृष्ठ-सचेत** भी है: किसी एक को देखते समय "इस सेशन" के बारे में पूछें और यह पहले से ही जानता है कि आप कौन सा रन मतलब हैं। बाद में इतिहास स्विचर से किसी भी पहली बातचीत को फिर से खोलें और वहीं से जहां आप छोड़ गए थे, आगे बढ़ें। +हर उत्तर अपनी रसीद के साथ आता है। असिस्टेंट सटीक सेशन, सहेजी गई क्वेरी, और डैशबोर्ड को लिंक करता है जिसका उपयोग उत्तर तक पहुंचने के लिए किया था, ताकि आप क्लिक कर सकें और इसके बजाय इसके शब्द पर ले सकें। यह **पेज-जागरूक** भी है: किसी सेशन को देखते समय "इस सेशन" के बारे में पूछें और यह पहले से ही जानता है कि आप कौन सा रन मतलब है। बाद में इतिहास स्विचर से किसी भी पहले की बातचीत को फिर से खोलें और वहां से शुरू करें जहां आपने छोड़ा था। -## एक अच्छे उत्तर को सहेजी गई क्वेरी या डैशबोर्ड में परिणत करें +## एक अच्छे उत्तर को एक सहेजी गई क्वेरी या डैशबोर्ड में बदलें -जब कोई उत्तर संरक्षण योग्य हो, तो सहायक को इसे सहेजने के लिए कहें। यह एक सहेजी गई क्वेरी के लिए SQL का मसौदा तैयार करता है, या उन क्वेरीज से एक डैशबोर्ड को असेंबल करता है, फिर आपको एक **अनुमोदित करें / अस्वीकार करें** कार्ड दिखाता है। जब तक आप अनुमोदित करें पर क्लिक नहीं करते, तब तक कुछ नहीं लिखा जाता है, तो आप "बस पूछें" की गति पाते हैं और अंतिम शब्द हमेशा आपका होता है। +जब कोई उत्तर रखने लायक हो, असिस्टेंट को इसे सहेजने के लिए कहें। यह एक सहेजी गई क्वेरी के लिए SQL का मसौदा तैयार करता है, या उन क्वेरी से एक डैशबोर्ड असेंबल करता है, फिर आपको एक **Approve / Reject** कार्ड दिखाता है। जब तक आप Approve क्लिक नहीं करते तब तक कुछ नहीं लिखा जाता है, इसलिए आप "बस पूछें" की गति के साथ अंतिम शब्द हमेशा आपका होता है। -**Queries** पेज पर यह एक कदम आगे जाता है और एक SQL लेखक बन जाता है: उस क्वेरी का वर्णन करें जो आप चाहते हैं ("पिछले 7 दिनों के लिए एजेंट द्वारा त्रुटि दर दिखाएं") और यह SQL को सीधे संपादक में स्ट्रीम करता है, एक अंतर दृश्य खोलता है ताकि आप **स्वीकार करें** या **अस्वीकार करें** परिवर्तन से पहले यह चेक कर सकें। +**Queries** पेज पर यह एक कदम आगे जाता है और एक SQL लेखक बन जाता है: आप जो क्वेरी चाहते हैं उसका वर्णन करें ("पिछले 7 दिनों के लिए एजेंट द्वारा एरर रेट दिखाएं") और यह SQL को सीधे संपादक में स्ट्रीम करता है, एक डिफ दृश्य खोलता है ताकि आप इसे landing से पहले **Accept** या **Reject** कर सकें। -![Observability Queries पृष्ठ और इसका SQL संपादक](/agenteye/images/query-lab.png) -*Queries पृष्ठ: यह संपादक वह स्थान है जहां सहायक एक मसौदा, केवल-पठन योग्य क्वेरी स्ट्रीम करता है ताकि आप स्वीकार या अस्वीकार कर सकें।* +![Observability Queries पेज और इसका SQL संपादक](/agenteye/images/query-lab.png) +*Queries पेज: यह संपादक वह जगह है जहां असिस्टेंट एक ड्राफ्ट, केवल-पढ़ने योग्य क्वेरी को स्ट्रीम करता है ताकि आप स्वीकार या अस्वीकार कर सकें।* -यहां SQL लेखन करना `queries:run` अनुमति का उपयोग करता है, जो संपादक के **Run** बटन के पीछे भी है। अन्य जगह चैट करने के लिए `agent:use` की आवश्यकता है। +यहां SQL को पूछकर लिखना `queries:run` अनुमति का उपयोग करता है, जो संपादक के **Run** बटन के पीछे वही है। अन्य सभी जगहों पर चैट को `agent:use` की जरूरत है। -## पूरी टीम को सौंपने के लिए सुरक्षित +## पूरी टीम को सौंपना सुरक्षित है -आप सहायक को सभी के लिए खोल सकते हैं बिना चिंता किए कि यह क्या स्पर्श कर सकता है: +आप यह चिंता किए बिना असिस्टेंट को सभी के लिए खोल सकते हैं कि यह क्या छू सकता है: -- **यह केवल वही पढ़ता है जो आप पहले से देख सकते हैं।** उत्तर आपकी स्वयं की पढ़ने की अनुमतियों के दायरे में हैं, तो यह कभी भी आपकी डेटा सतह को नहीं बढ़ाता। -- **हर लेखन आपके लिए प्रतीक्षा करता है।** सहेजी गई क्वेरीज और डैशबोर्ड केवल आपकी स्पष्ट अनुमोदन क्लिक के बाद बनाए जाते हैं, और कोई सेटिंग नहीं है जो उस गेट को बंद करता है। -- **यह कभी भी कुछ नहीं हटा सकता।** कोई हटाने का उपकरण नहीं है और सहायक के पास कोई हटाने की अनुमति नहीं है। हटाने डैशबोर्ड में आपके हाथों में रहते हैं। -- **यह आपके संगठन के अंदर रहता है।** सहायक केवल उस संगठन को देखता है जिसे आप वर्तमान में देख रहे हैं। -- **आपके प्रश्न आपके हैं।** संकेत और उत्तर आपके स्वयं के Observability डेटाबेस में रहते हैं; उत्पाद विश्लेषण केवल उपयोग मेटाडेटा रिकॉर्ड करता है, कभी भी आपके संकेत पाठ को नहीं। +- **यह केवल वही पढ़ता है जो आप पहले से देख सकते हैं।** उत्तर आपकी स्वयं की read अनुमति के दायरे में हैं, इसलिए यह कभी भी आपकी डेटा सतह को नहीं बढ़ाता है। +- **हर लिखना आपके लिए इंतजार करता है।** सहेजी गई क्वेरी और डैशबोर्ड केवल आपके स्पष्ट Approve क्लिक के बाद बनाए जाते हैं, और कोई सेटिंग नहीं है जो उस गेट को बंद कर दे। +- **यह कभी भी कुछ नहीं हटा सकता है।** कोई delete टूल expose नहीं है और असिस्टेंट के पास कोई delete अनुमति नहीं है। Deletions आपके हाथों में रहते हैं, डैशबोर्ड में। +- **यह आपके org के अंदर रहता है।** असिस्टेंट केवल उस org को देखता है जो आप वर्तमान में देख रहे हैं। +- **आपके सवाल आपके हैं।** Prompts और उत्तर आपके अपने Observability डेटाबेस में रहते हैं; product analytics केवल उपयोग metadata रिकॉर्ड करता है, कभी आपकी prompt पाठ नहीं। ## इसे कहां खोजें -सहायक आपके संगठन के तहत हर पृष्ठ के दाईं ओर चलता है (`//...`)। रेल पर क्लिक करें, या `⌘J` / `Ctrl+J` दबाएं, इसे पूर्ण चैट पैनल में विस्तारित करने के लिए, और इसके किनारे को आकार देने के लिए खींचें; आपकी चौड़ाई पुनः लोड में याद रखी जाती है। इसका उपयोग करने के लिए आपको **`agent:use`** अनुमति की आवश्यकता है, अन्यथा रेल धूसर होता है। यदि यह अभी तक आपकी तैनाती के लिए चालू नहीं किया गया है (इसे एक LLM कनेक्शन की आवश्यकता है), तो आप एक काम करने वाली चैट के बजाय एक सुस्त रेल देखेंगे। +असिस्टेंट आपके org के तहत हर पेज (`//...`) के दाहिने किनारे पर चलता है। रेल पर क्लिक करें, या `⌘J` / `Ctrl+J` दबाएं, इसे पूर्ण चैट पैनल में विस्तारित करने के लिए, और आकार बदलने के लिए इसके किनारे को खींचें; आपकी चौड़ाई reloads के पार याद रखी जाती है। इसे उपयोग करने के लिए आपको **`agent:use`** अनुमति की जरूरत है, अन्यथा रेल ग्रे आउट है। यदि इसे अभी तक आपके deployment के लिए चालू नहीं किया गया है (इसे LLM कनेक्शन की जरूरत है), तो आप एक काम कर रहे चैट के बजाय एक म्यूट रेल देखेंगे। ## संबंधित diff --git a/docs/hi/agenteye/audits.mdx b/docs/hi/agenteye/audits.mdx index ea0b96fb..2561ccdd 100644 --- a/docs/hi/agenteye/audits.mdx +++ b/docs/hi/agenteye/audits.mdx @@ -1,53 +1,54 @@ --- -title: "ऑडिट: आपका स्वचालित विश्वसनीयता विश्लेषक" -description: "Failproof AI Observability उन विफलताओं को खोजता है जिनके लिए आपने कोई नियम नहीं लिखा था और आपको ठीक करने के लिए आवश्यक चीजों की एक रैंक की गई, साक्ष्य-समर्थित सूची देता है।" +title: "ऑडिट्स: आपका स्वचालित विश्वसनीयता विश्लेषक" +description: "Failproof AI Observability उन विफलताओं को खोजता है जिनके लिए आपने कोई नियम नहीं लिखा है और आपको एक रैंक की गई, साक्ष्य-समर्थित सूची देता है कि वास्तव में क्या ठीक करना है।" --- -Failproof AI Observability उन विफलताओं को खोजता है जिनके लिए आपने कोई नियम नहीं लिखा था और आपको ठीक करने के लिए आवश्यक चीजों की एक रैंक की गई, साक्ष्य-समर्थित सूची देता है। यह ऐसा है जैसे कोई विश्लेषक हर रात आपके लॉग को देखे, और फिर सुबह तक छोटी सूची आपकी डेस्क पर छोड़ दे। + +Failproof AI Observability उन विफलताओं को खोजता है जिनके लिए आपने कोई नियम नहीं लिखा है और आपको एक रैंक की गई, साक्ष्य-समर्थित सूची देता है कि वास्तव में क्या ठीक करना है। यह ऐसे ही है जैसे कोई विश्लेषक हर रात आपके लॉग्स को देखे, और सुबह तक छोटी सी सूची आपकी डेस्क पर छोड़ दे।
- +
-*दो मिनट का दौरा: एक निर्धारित रन से लेकर एक ऐसे फिक्स तक जिस पर आप कार्य कर सकते हैं।* +*दो मिनट की सैर: एक शेड्यूल्ड रन से लेकर एक ऐसी जानकारी तक जिस पर आप कार्रवाई कर सकते हैं।* -![ऑडिट पृष्ठ: आवर्ती कार्य जो आपके सत्रों को विफलता पैटर्न के लिए स्कैन करते हैं, प्रत्येक के साथ एक शेड्यूल और संवेदनशीलता](/agenteye/images/audits.png) -*प्रत्येक ऑडिट एक आवर्ती कार्य है जो आपके सत्रों को माइन करता है और रैंक की गई, साक्ष्य-समर्थित सिफारिशें लिखता है।* +![ऑडिट्स पेज: आवर्ती कार्य जो आपके सेशन में विफलता पैटर्न को स्कैन करते हैं, प्रत्येक के साथ एक शेड्यूल और संवेदनशीलता](/agenteye/images/audits.png) +*प्रत्येक ऑडिट एक आवर्ती कार्य है जो आपके सेशन को मानता है और रैंक की गई, साक्ष्य-समर्थित सिफारिशें देता है।* -## अनुमान लगाना बंद करें कि आगे क्या ठीक करना है +## अगला क्या ठीक करना है, यह अनुमान लगाना बंद करें -अलर्ट उन समस्याओं को पकड़ते हैं जिन्हें आप पहले से देखना जानते हैं। ऑडिट उन समस्याओं को पकड़ते हैं जिन्हें आप नहीं जानते। आपके द्वारा निर्धारित शेड्यूल पर, एक ऑडिट आपके सभी एजेंट सत्रों को पढ़ता है और ऐसे पैटर्न के लिए शिकार करता है जो ठीक करने के लायक हैं, इसलिए आप लॉग स्क्रॉल करने की बजाय निष्कर्षों पर कार्य करने में अपना समय लगाते हैं। +अलर्ट उन समस्याओं को पकड़ते हैं जिन्हें आप पहले से जानते हैं। ऑडिट्स उन लोगों को पकड़ते हैं जिन्हें आप नहीं जानते। आपके द्वारा निर्धारित शेड्यूल पर, एक ऑडिट आपके सभी एजेंट सेशन को पढ़ता है और उन पैटर्न को ढूंढता है जो ठीक करने योग्य हैं, ताकि आप लॉग स्क्रॉल करने की उम्मीद में समय बर्बाद न करें। -एक एकल रन उन विफलता मोड के बाद जाता है जो वास्तव में उत्पादन में एजेंटों को तोड़ते हैं: +एक एकल रन उन विफलता मोड के बाद जाता है जो वास्तव में उत्पादन में एजेंट को तोड़ते हैं: -- **त्रुटि क्लस्टर**: साझा मूल कारण के तहत समान विफलता दोहराई जाती है। -- **बेसलाइन के विरुद्ध बहाव**: व्यवहार शांति से ज्ञात-अच्छी खिड़की से दूर जा रहा है। -- **प्रतिलेखों में लक्ष्य विफलता**: चलता है जो तकनीकी रूप से समाप्त हुआ लेकिन कभी काम नहीं किया। -- **उपकरण का दुरुपयोग**: गलत उपकरण, खराब तर्क, या लूप जो कॉल को जला देते हैं। -- **गुणवत्ता और लागत के व्यापार**: जहां आप उस आउटपुट के लिए अधिक भुगतान कर रहे हैं जिसे आप सस्ते में प्राप्त कर सकते हैं। -- **कवरेज अंतराल**: व्यवहार जिसे कोई eval या अलर्ट नहीं देख रहा है। +- **त्रुटि क्लस्टर**: एक ही विफलता एक साझा मूल कारण के तहत दोहराई जाती है। +- **आधारभूत के विरुद्ध बहाव**: व्यवहार धीरे-धीरे एक ज्ञात-अच्छी खिड़की से दूर जा रहा है। +- **प्रतिलेखों में लक्ष्य विफलता**: ऐसे रन जो तकनीकी रूप से समाप्त हुए लेकिन कभी भी काम नहीं किया। +- **उपकरण का दुरुपयोग**: गलत उपकरण, खराब तर्क, या कॉल को जलाने वाले लूप। +- **गुणवत्ता और लागत व्यापार**: जहां आप कम कीमत पर मिल सकने वाले आउटपुट के लिए अधिक भुगतान कर रहे हैं। +- **कवरेज अंतराल**: ऐसा व्यवहार जिसे कोई eval या अलर्ट देख नहीं रहा है। -आप एक एकल **संवेदनशीलता** सेटिंग (कम, मध्यम, या उच्च) के साथ यह तय करते हैं कि यह कितना कठोर दिखता है, इसलिए एक शोरगुल वाला स्टेजिंग एजेंट और एक लॉक-डाउन उत्पादन एजेंट दोनों को आप चाहते हैं उस सिग्नल के लिए ट्यून किया जा सकता है। +आप एक एकल **संवेदनशीलता** सेटिंग (कम, मध्यम, या उच्च) के साथ यह तय करते हैं कि यह कितना कठोर दिखता है, ताकि एक शोर वाला स्टेजिंग एजेंट और एक लॉक-डाउन उत्पादन एजेंट प्रत्येक को उस सिग्नल के लिए ट्यून किया जा सके जो आप चाहते हैं। -## हर सिफारिश प्रमाण के साथ आती है +## हर सिफारिश साक्ष्य के साथ आती है -आपको कभी भी किसी निष्कर्ष पर विश्वास करने की आवश्यकता नहीं है। प्रत्येक सिफारिश उन सटीक सत्रों का हवाला देती है जहां से यह आया था और उस SQL को जो इसे सामने लाया था, इसलिए आप एक क्लिक में साक्ष्य खोल सकते हैं और समस्या की पुष्टि कर सकते हैं, न कि एक दावे को रिवर्स-इंजीनियर कर सकते हैं। +आपको कभी भी किसी खोज को विश्वास पर लेना नहीं पड़ता। प्रत्येक सिफारिश उन सटीक सेशन का हवाला देती है जहां से यह आया है और वह SQL जो इसे सामने लाया है, ताकि आप साक्ष्य खोल सकें और एक क्लिक में समस्या की पुष्टि कर सकें। -जब कोई निष्कर्ष एक लीक किए गए क्रेडेंशियल के बारे में हो, तो यह एक कदम आगे बढ़ता है और वह व्यक्तिगत इवेंट को लिंक करता है जिसे यह मेल खाता है। एक पर क्लिक करें और आप सत्र में उस सटीक क्षण पर उतरते हैं, पहले से ही चुना हुआ — एक लंबे प्रतिलेख के शीर्ष पर नहीं। लिंक इवेंट का नाम देता है; यह पाए गए रहस्य को निष्कर्ष में कभी नहीं कॉपी करता है, इसलिए एक निष्कर्ष पढ़ना आपके क्रेडेंशियल लिखे जाने का दूसरा स्थान नहीं है। यदि कोई इवेंट अब नहीं है क्योंकि सत्र आपकी प्रतिधारण विंडो पास कर गया है, तो पृष्ठ स्पष्ट रूप से कहता है कि आप गलत चीज पर क्लिक किया है या नहीं यह सोचकर छोड़ते हैं। +जब कोई खोज एक लीक किए गए क्रेडेंशियल के बारे में हो, तो यह एक कदम आगे जाता है और उन व्यक्तिगत इवेंट्स को लिंक करता है जिनसे यह मेल खाता है। एक पर क्लिक करें और आप उस सेशन में उस सटीक क्षण पर पहुंच जाते हैं, पहले से ही चुना हुआ — पूरे प्रतिलेख के शीर्ष पर नहीं जो आप स्क्रॉल कर सकते हैं। लिंक इवेंट का नाम देता है; यह कभी भी पहचाने गए सीक्रेट को खोज में कॉपी नहीं करता है, इसलिए एक खोज पढ़ना आपका क्रेडेंशियल लिखे जाने की दूसरी जगह नहीं है। यदि कोई इवेंट अब वहां नहीं है क्योंकि सेशन आपकी रिटेंशन विंडो को पास कर गया है, तो पृष्ठ स्पष्ट रूप से कहता है बजाय इसके कि आप गलत चीज पर क्लिक करने का सवाल उठाएं। -यह भी है जो ऑडिट को ईमानदार रखता है। सर्वर जांच करता है कि प्रत्येक उद्धृत सत्र वास्तव में मौजूद है और **किसी भी सिफारिश को त्याग देता है जिसका साक्ष्य धारण नहीं करता है**, इसलिए ऑडिट जांच करता है लेकिन कभी आविष्कार नहीं करता। आपकी सूची पर जो आता है वह वास्तविक, पुन: पेश करने योग्य, और इस बात से रैंक किया जाता है कि यह कितना महत्वपूर्ण है, सबसे बड़ी जीत शीर्ष पर है। +यह भी वह है जो ऑडिट्स को ईमानदार रखता है। सर्वर यह जांचता है कि हर उद्धृत सेशन वास्तव में मौजूद है और **किसी भी सिफारिश को त्यागता है जिसका साक्ष्य टिका नहीं है**, इसलिए ऑडिट जांच करता है लेकिन कभी आविष्कार नहीं करता। जो आपकी सूची पर आता है वह वास्तविक, पुनरुत्पादन योग्य है, और इससे महत्वपूर्ण है कि कितना है, सबसे बड़ी जीत शीर्ष पर है। -## एक फिक्स को एक सुरक्षा में बदलें +## एक फिक्स को एक गार्ड्रेल में बदलें -एक समस्या को ठीक करना केवल आधी जीत है। दूसरा आधा यह सुनिश्चित करना है कि यह शांति से वापस न आए। हर निष्कर्ष एक **एक-क्लिक शॉर्टकट ले जाता है जो एक आवर्ती अलर्ट का मसौदा तैयार करता है**, एक समझदारी से भरे हुए शुरुआती ट्रिगर के साथ आप ट्यून कर सकते हैं। निष्कर्ष को बंद करें, अलर्ट को सशस्त्र करें, और अगली बार जब वह पैटर्न फिर से प्रकट होता है तो आप एक भविष्य के ऑडिट में इसे फिर से खोजने के बजाय पेजिंग प्राप्त करते हैं। +किसी समस्या को ठीक करना केवल आधी जीत है। दूसरी आधी यह सुनिश्चित करना है कि यह चुप्पी से वापस न आ सके। हर खोज में एक **वन-क्लिक शॉर्टकट होता है जो एक पुनरावृत्ति अलर्ट का मसौदा तैयार करता है**, एक समझदारी के साथ पूर्व-भरा जो आप ट्यून कर सकते हैं। खोज को बंद करें, अलर्ट को सशस्त्र करें, और अगली बार जब वह पैटर्न फिर से दिखाई दे तो आपको भविष्य के ऑडिट में इसे फिर से खोजने के बजाय पेज मिलता है। -## इसे कहां खोजें +## इसे कहां ढूंढें -ऑडिट डैशबोर्ड में **`//audits`** पर रहते हैं (साइडबार से *विश्लेषण* से *audits*)। रन और निष्कर्षों को देखने के लिए **`audits:read`** की जरूरत है; ऑडिट बनाने, संपादित करने, और ट्राइज करने के लिए **`audits:write`** की जरूरत है। एक ऑडिट का दायरा और कैडेंस सेट करें, फिर जब आप अगले निर्धारित पास की प्रतीक्षा करने के बजाय तुरंत परिणाम चाहते हैं तो **अभी चलाएं** को हिट करें। +ऑडिट्स डैशबोर्ड में **`//audits`** पर रहते हैं (साइडबार से *विश्लेषण* से *ऑडिट्स*)। रन और खोज को देखने के लिए **`audits:read`** की आवश्यकता होती है; ऑडिट्स बनाने, संपादित करने और ट्रिएज करने के लिए **`audits:write`** की आवश्यकता होती है। एक ऑडिट का दायरा और लय सेट करें, फिर जब भी आप अगले निर्धारित पास के लिए प्रतीक्षा करने के बजाय तुरंत परिणाम चाहते हैं तो **अभी चलाएं** दबाएं। ## संबंधित -- [अलर्ट](/hi/agenteye/alerts): जिस पल एक थ्रेसहोल्ड को पार किया जाता है उस पल एक पेज प्राप्त करें। -- [मूल्यांकन](/hi/agenteye/evaluations): हर रन को स्कोर करें ताकि गुणवत्ता प्रतिगमन अपने आप सामने आएं। -- [त्रुटि ट्रैकिंग](/hi/agenteye/error-tracking): एजेंटों द्वारा फेंकी जाने वाली त्रुटियों को समूहित और अनुसरण करें। -- [घटनाएं](/hi/agenteye/incidents): एक ऑडिट के माध्यम से एक समस्या को ट्रैक करें जो यह इसके फिक्स के माध्यम से बदल देता है। \ No newline at end of file +- [अलर्ट्स](/hi/agenteye/alerts): उस क्षण पेज करें जब कोई थ्रेसहोल्ड जो आप पहले से जानते हैं पार हो जाता है। +- [मूल्यांकन](/hi/agenteye/evaluations): हर रन को स्कोर करें ताकि गुणवत्ता में गिरावट अपने आप ही सामने आ जाए। +- [त्रुटि ट्रैकिंग](/hi/agenteye/error-tracking): आपके एजेंट द्वारा फेंकी गई त्रुटियों को समूह और अनुसरण करें। +- [घटनाएं](/hi/agenteye/incidents): एक समस्या को ट्रैक करें जो एक ऑडिट अपनी फिक्स के माध्यम से बदल देता है। \ No newline at end of file diff --git a/docs/hi/agenteye/cli-and-agents.mdx b/docs/hi/agenteye/cli-and-agents.mdx index 9554133d..a3922444 100644 --- a/docs/hi/agenteye/cli-and-agents.mdx +++ b/docs/hi/agenteye/cli-and-agents.mdx @@ -1,10 +1,10 @@ --- title: "CLI" -description: "आपका पूरा Failproof AI Observability डिप्लॉयमेंट, एक कमांड की दूरी पर।" +description: "आपका संपूर्ण Failproof AI Observability डिप्लॉयमेंट, एक कमांड दूर है।" --- -आपका पूरा Failproof AI Observability डिप्लॉयमेंट, एक कमांड की दूरी पर। प्रोडक्शन को चेक करें, API कुंजी जारी करें, या अपने टर्मिनल से बाहर निकले बिना किसी इंसिडेंट को स्वीकार करें, फिर इसे CI में स्क्रिप्ट करें, या एक कोडिंग एजेंट को सादे अंग्रेजी में करने दें। +आपका संपूर्ण Failproof AI Observability डिप्लॉयमेंट, एक कमांड दूर है। प्रोडक्शन को चेक करें, API कुंजी बनाएँ, या इंसिडेंट को स्वीकार करें — सब कुछ अपने टर्मिनल से ही करें, फिर इसे CI में स्क्रिप्ट करें या किसी कोडिंग एजेंट को सादी अंग्रेजी में ऐसा करने दें। ```bash pipx install agenteye @@ -12,18 +12,18 @@ agenteye login --email you@example.com # a 6-digit code lands in your inbox agenteye --json sessions --since 24h # every agent run from the last day, newest first ``` -*`agenteye` CLI आपके डैशबोर्ड से बात करता है। यह कलेक्टर से एक अलग टूल है, जो सर्वर को ईवेंट भेजता है।* +*`agenteye` CLI आपके डैशबोर्ड से बात करता है। यह कलेक्टर से एक अलग टूल है, जो सर्वर को इवेंट भेजता है।* -## आपका पूरा डिप्लॉयमेंट, एक कमांड की दूरी पर +## आपका संपूर्ण डिप्लॉयमेंट, एक कमांड दूर -एक त्वरित सवाल का जवाब देने के लिए टैब-हॉपिंग बंद करें। `agenteye` CLI आपके डेटा को पढ़ता है और एक ही बाइनरी से आपके संगठन का प्रबंधन करता है, इसलिए एक चेक जो पहले डैशबोर्ड के माध्यम से क्लिक करने का मतलब था, अब एक पंक्ति बन जाता है जिसे आप दोबारा चला सकते हैं, उपनाम दे सकते हैं, या एक रनबुक में पेस्ट कर सकते हैं। आपको चार सतहें मिलती हैं: +टैब स्विच करना बंद करें और जल्दी सवाल का जवाब पाएँ। `agenteye` CLI आपका डेटा पढ़ता है और एक एकल बाइनरी से आपके संगठन को प्रबंधित करता है, इसलिए एक चेक जो पहले डैशबोर्ड के माध्यम से क्लिक करने का मतलब था, अब एक पंक्ति बन गया है जिसे आप फिर से चला सकते हैं, उपनाम दे सकते हैं या रनबुक में पेस्ट कर सकते हैं। आपको चार सतहें मिलती हैं: -- **अपना डेटा पढ़ें:** `sessions`, `events`, `evals`, और `errors`, समय, एजेंट और पर्यावरण द्वारा फ़िल्टर किए गए। -- **अपने संगठन का प्रबंधन करें:** `keys`, `users`, `settings`, `alerts`, और `incidents`। -- **विश्लेषण चलाएं:** सहेजे गए SQL के साथ-साथ आपके इवेंट डेटा पर एक ad-hoc `query` रनर। -- **असिस्टेंट से पूछें:** `agent ask` उसी read-only विश्लेषक तक पहुंचता है जिससे आप डैशबोर्ड में चैट करते हैं। +- **अपना डेटा पढ़ें:** `sessions`, `events`, `evals` और `errors`, समय, एजेंट और वातावरण द्वारा फ़िल्टर किए गए। +- **अपने संगठन को प्रबंधित करें:** `keys`, `users`, `settings`, `alerts` और `incidents`। +- **विश्लेषण चलाएँ:** सहेजे गए SQL और आपके इवेंट डेटा पर एक विज्ञापन-हॉक `query` रनर। +- **सहायक से पूछें:** `agent ask` उसी पढ़ने-योग्य विश्लेषक तक पहुँचता है जिससे आप डैशबोर्ड में चैट करते हैं। -इसे `pipx` के साथ एक बार इंस्टॉल करें, एक ईमेल की गई 6-अंकीय कोड से साइन इन करें, और आप तैयार हैं। सेशन लगभग एक दिन तक चलता है; जब यह समाप्त हो जाए तो `agenteye login` को दोबारा चलाएं। प्रोडक्शन को स्पॉट-चेक करने, एक कुंजी प्रदान करने, या एक फायरिंग इंसिडेंट को ट्रिएज करने के लिए इसका उपयोग करें, सब कुछ बिना ब्राउज़र खोले: +इसे `pipx` के साथ एक बार इंस्टॉल करें, एक ईमेल की गई 6-अंकीय कोड से साइन इन करें, और आप तैयार हैं। सत्र लगभग एक दिन तक रहता है; जब यह समाप्त हो जाए तो `agenteye login` को फिर से चलाएँ। प्रोडक्शन को स्पॉट-चेक करने, कुंजी प्रदान करने या एक लाइव इंसिडेंट को ट्राएज करने के लिए इसका उपयोग करें — सब कुछ ब्राउज़र खोले बिना: ```bash agenteye errors --since 24h --aggregate # what is breaking, grouped by error type @@ -31,25 +31,25 @@ agenteye incidents list --state firing # what is on fire right now agenteye keys create ci --add events:add # a key that can only push events, secret shown once ``` -एक आदत जानने के लिए: `--json` जैसे वैश्विक विकल्प कमांड से पहले जाते हैं। `agenteye --json sessions` सही है; `agenteye sessions --json` नहीं है। +एक आदत जानने योग्य है: वैश्विक विकल्प जैसे `--json` कमांड से पहले जाते हैं। `agenteye --json sessions` सही है; `agenteye sessions --json` नहीं है। -## इसे स्क्रिप्ट करें, इसे CI में वायर करें +## इसे स्क्रिप्ट करें, CI में वायर करें -प्रत्येक कमांड `--json` लेता है, और यह सब कुछ बदल देता है। स्वच्छ JSON stdout पर जाता है जबकि मानव स्थिति और चेतावनियां stderr पर जाती हैं, इसलिए एक `--json` कैप्चर सीधे `jq` में पाइप करता है बिना किसी भटकाऊ पंक्ति को छीने। यही वह है जो CLI को आपके लिए एक प्रॉम्प्ट पर और एक कोडिंग एजेंट के आउटपुट को पार्स करने के लिए समान रूप से अच्छा बनाता है: +हर कमांड `--json` लेता है, और यह सब कुछ बदल देता है। स्वच्छ JSON stdout पर जाता है जबकि मानवीय स्थिति और चेतावनियाँ stderr पर जाती हैं, इसलिए एक `--json` कैप्चर सीधे `jq` में पाइप होता है बिना किसी स्ट्रे लाइन को हटाए। यही वह है जो CLI को प्रॉम्प्ट पर आपके लिए और एक कोडिंग एजेंट जो आउटपुट पार्स करता है, दोनों के लिए समान रूप से अच्छा बनाता है: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -यह बिना किसी निरीक्षण के चलाने के लिए बनाया गया है। पुष्टिकरण प्रॉम्प्ट स्वतः-स्किप हो जाते हैं जब कोई टर्मिनल संलग्न नहीं होता है, इसलिए पाइपलाइन में कुछ नहीं रुकता, और प्रत्येक कमांड एक सार्थक निकास कोड लौटाता है: `0` सफलता, `4` लॉगिन नहीं किया गया, `5` एक अनुमति गायब है (संदेश इसे नाम देता है, उदाहरण के लिए `alerts:write`), `3` डैशबोर्ड अप्राप्य। एक स्क्रिप्ट एक `4` पर पुनः-प्रमाणीकृत करने के लिए या एक `5` पर आपको बताने के लिए शाखा कर सकता है कि सही से क्या माँगना है, बजाय अंधे तरीके से विफल होने के। +यह बिना निगरानी के चलने के लिए बनाया गया है। कन्फर्मेशन प्रॉम्प्ट तब ऑटो-स्किप हो जाते हैं जब कोई टर्मिनल संलग्न नहीं होता है, इसलिए कोई भी पाइपलाइन में अटका नहीं रहता है, और हर कमांड एक अर्थपूर्ण exit code देता है: `0` सफलता, `4` लॉगिन नहीं किया गया, `5` अनुमति की कमी (संदेश इसे नाम देता है, उदाहरण के लिए `alerts:write`), `3` डैशबोर्ड अनुपलब्ध। एक स्क्रिप्ट `4` पर फिर से प्रमाणित करने के लिए या `5` पर आपको बताने के लिए कि एक व्यवस्थापक से क्या माँगना है, इसके बजाय अँधे में विफल होने के लिए ब्रांच कर सकता है। -## एक कोडिंग एजेंट को सादे अंग्रेजी में इसे चलाने दें +## इसे एक कोडिंग एजेंट को सादी अंग्रेजी में चलाने दें -बेहतर अभी, आपको इन झंडों में से किसी को भी याद नहीं रखना चाहिए। **CLI कौशल** एक छोटा Agent Skill फ़ोल्डर है जिसका नाम `agenteye-cli` है जो Claude Code या Codex जैसे एक कोडिंग एजेंट को सादे-अंग्रेजी अनुरोधों से CLI चलाने के लिए सिखाता है। पूछें "क्या आज कुछ टूट गया है?" और एजेंट कमांड चुनता है, इसे आपके रूप में चलाता है, और गद्य में उत्तर देता है। +और भी अच्छा है, आपको इन फ़्लैग्स में से कोई भी याद रखने की आवश्यकता नहीं होनी चाहिए। **CLI स्किल** एक छोटा Agent Skill फ़ोल्डर है जिसका नाम `agenteye-cli` है जो Claude Code या Codex जैसे कोडिंग एजेंट को सादी-अंग्रेजी अनुरोधों से CLI चलाना सिखाता है। "क्या आज कुछ टूटा है?" पूछें और एजेंट कमांड चुनता है, इसे आप के रूप में चलाता है, और गद्य में उत्तर देता है। -Claude Code के लिए, `agenteye-cli` फ़ोल्डर को `~/.claude/skills/` में ड्रॉप करें और इसे स्वतः-खोजा जाता है। Failproof AI Observability फ़ोल्डर प्रदान करता है; इंस्टॉल करने के लिए कुछ अतिरिक्त नहीं है, क्योंकि यह केवल CLI को चलाता है जिसे आप पहले से ही इंस्टॉल कर चुके हैं। पहले स्वयं लॉगिन करें: कौशल ईमेल-कोड लॉगिन को आपके लिए पूरा नहीं कर सकता। +Claude Code के लिए, `agenteye-cli` फ़ोल्डर को `~/.claude/skills/` में रखें और यह स्वचालित रूप से खोजा जाएगा। Failproof AI Observability फ़ोल्डर प्रदान करता है; कोई अतिरिक्त इंस्टॉलेशन नहीं है, क्योंकि यह केवल आप द्वारा पहले से इंस्टॉल किए गए CLI को चलाता है। पहले स्वयं लॉगिन करें: स्किल आपके लिए ईमेल किए गए कोड लॉगिन को पूरा नहीं कर सकता। -क्योंकि एजेंट CLI को आपके रूप में चलाता है, यह सब कुछ कर सकता है जो आपकी लॉगिन अनुमति देता है, पढ़ता है और लिखता है: कुंजियां बनाएं, सेटिंग्स बदलें, इंसिडेंट्स को हल करें। CLI का "क्या आप निश्चित हैं?" प्रॉम्प्ट एजेंट के लिए फायर नहीं करता है, इसलिए कौशल को सटीक कमांड बताने और किसी भी परिवर्तन से पहले आपकी OK की प्रतीक्षा करने के लिए लिखा गया है। आप पुष्टिकरण चरण हैं। +क्योंकि एजेंट CLI को आप के रूप में चलाता है, यह वह सब कुछ कर सकता है जो आपके लॉगिन की अनुमति देता है, पढ़ने और लिखने दोनों: कुंजियाँ बनाएँ, सेटिंग्स बदलें, इंसिडेंट को हल करें। CLI का "क्या आप निश्चित हैं?" प्रॉम्प्ट एजेंट के लिए नहीं चलता है, इसलिए स्किल सटीक कमांड बताने के लिए लिखा गया है और किसी भी परिवर्तन से पहले आपके ठीक होने की प्रतीक्षा करता है। आप पुष्टिकरण चरण हैं। ```text you Why did session run-001 fail? @@ -58,7 +58,7 @@ agent Running: agenteye --json events --session-id run-001 --all The checkout-agent hit a TimeoutError on its third tool call. ``` -पढ़ता तुरंत रहता है, और हर लेखन आपके लिए रुकता है: +पढ़ना तुरंत रहता है, और हर लेखन आपके लिए रुकता है: ```text you Give CI a key that can only push events. @@ -74,7 +74,7 @@ agent Done. Key "ci" created with events:add only. The secret is shown once, so ## संबंधित -- [CLI संदर्भ](/hi/agenteye/cli): प्रत्येक कमांड, ध्वज, और JSON आकार। -- [एजेंट्स के लिए CLI व्यंजन](/hi/agenteye/cli-recipes): copy-paste `jq` पैटर्न और निकास-कोड हैंडलिंग। -- [CLI एजेंट कौशल](/hi/agenteye/cli-skill): `agenteye-cli` कौशल को इंस्टॉल और चलाएं। -- [AI सहायक](/hi/agenteye/assistant): डैशबोर्ड विश्लेषक जिससे `agent ask` बात करता है। \ No newline at end of file +- [CLI reference](/hi/agenteye/cli): हर कमांड, फ़्लैग और JSON आकार। +- [एजेंटों के लिए CLI रेसिपी](/hi/agenteye/cli-recipes): `jq` पैटर्न और exit-code हैंडलिंग को कॉपी-पेस्ट करें। +- [CLI एजेंट स्किल](/hi/agenteye/cli-skill): `agenteye-cli` स्किल को इंस्टॉल और चलाएँ। +- [AI सहायक](/hi/agenteye/assistant): डैशबोर्ड में विश्लेषक जिससे `agent ask` बात करता है। \ No newline at end of file diff --git a/docs/hi/agenteye/cli-recipes.mdx b/docs/hi/agenteye/cli-recipes.mdx index 148cbede..2aaf0850 100644 --- a/docs/hi/agenteye/cli-recipes.mdx +++ b/docs/hi/agenteye/cli-recipes.mdx @@ -1,29 +1,29 @@ --- -title: "एजेंटों के लिए CLI रेसिपीज़" -description: "कॉपी-पेस्ट क्वेरी पैटर्न और jq रेसिपीज़ जो सेशन, इवेंट और मूल्यांकन डेटा को ऐसी चीज़ में बदल देते हैं जिसे एक स्क्रिप्ट या कोडिंग एजेंट स्वचालित कर सकता है।" +title: "एजेंटों के लिए CLI रेसिपी" +description: "कॉपी-पेस्ट क्वेरी पैटर्न और jq रेसिपी जो सेशन, इवेंट, और मूल्यांकन डेटा को स्क्रिप्ट या कोडिंग एजेंट स्वचालित कर सकने वाली चीज़ में बदलते हैं।" --- -एक स्क्रिप्ट या कोडिंग एजेंट से सीधे सेशन, इवेंट और मूल्यांकन डेटा खींचें (और पुनः-मूल्यांकन ट्रिगर करें), स्टडआउट पर स्वच्छ JSON के साथ जो सीधे `jq` में पाइप होता है। ये रेसिपीज़ Failproof AI Observability के डेटा को ऐसी चीज़ में बदल देते हैं जिसे एक टर्मिनल उपयोगकर्ता या एक AI कोडिंग एजेंट (Claude Code, Cursor) क्वेरी और स्वचालित कर सकता है, डैशबोर्ड के माध्यम से क्लिक किए बिना। +सेशन, इवेंट, और मूल्यांकन डेटा (और पुनः मूल्यांकन को ट्रिगर करें) सीधे स्क्रिप्ट या कोडिंग एजेंट से खींचें, stdout पर स्वच्छ JSON के साथ जो सीधे `jq` में पाइप करता है। ये रेसिपी Failproof AI Observability के डेटा को एक टर्मिनल उपयोगकर्ता या AI कोडिंग एजेंट (Claude Code, Cursor) में बदलते हैं जो डैशबोर्ड के माध्यम से क्लिक किए बिना क्वेरी और स्वचालित कर सकते हैं। -नीचे दिए गए पैटर्न Failproof AI Observability CLI (`agenteye`) के लिए कॉपी-पेस्ट के लिए तैयार हैं। इंस्टॉलेशन, प्रमाणीकरण और पूर्ण विकल्प सूची के लिए [CLI](/hi/agenteye/cli) देखें; अंतर्निहित सहायता के लिए `agenteye -h` या `agenteye -h` चलाएं। +नीचे दिए गए पैटर्न Failproof AI Observability CLI (`agenteye`) के लिए कॉपी-पेस्ट के लिए तैयार हैं। इंस्टॉलेशन, प्रमाणीकरण, और पूर्ण विकल्प सूची के लिए [CLI](/hi/agenteye/cli) देखें; अंतर्निहित सहायता के लिए `agenteye -h` या `agenteye -h` चलाएं। -## मुख्य नियम +## सुनहरे नियम -1. **ग्लोबल विकल्प कमांड से *पहले* जाते हैं।** `agenteye --json sessions` सही है; `agenteye sessions --json` नहीं है। ग्लोबल्स हैं `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`। -2. **जब भी आप आउटपुट पार्स करते हैं तो `--json` पास करें।** डेटा **stdout** पर JSON के रूप में जाता है; मानव स्थिति और त्रुटियां **stderr** पर जाती हैं, इसलिए stdout स्वच्छ रहता है `jq` में पाइप करने के लिए। -3. **stderr टेक्स्ट पर नहीं, एक्जिट कोड पर विभाजित करें**: `0` ठीक है · `1` अप्रत्याशित त्रुटि · `2` खराब तर्क · `3` डैशबोर्ड तक नहीं पहुँच सकते · `4` लॉगिन नहीं है या समाप्त हो गया · `5` अनुमति नहीं है · `6` संसाधन नहीं मिला। -4. **`-h` के साथ खोजें।** प्रत्येक कमांड अपने फिल्टर, मान प्रारूप और JSON आकार को दस्तावेज़ित करता है। +1. **वैश्विक विकल्प कमांड से *पहले* जाते हैं।** `agenteye --json sessions` सही है; `agenteye sessions --json` नहीं है। वैश्विक विकल्प हैं `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`। +2. **जब भी आप आउटपुट पार्स करें तो `--json` पास करें।** डेटा stdout पर JSON के रूप में जाता है; मानवीय स्थिति और त्रुटियां stderr पर जाती हैं, इसलिए stdout `jq` में पाइप करने के लिए स्वच्छ रहता है। +3. **stderr टेक्स्ट पर नहीं, exit code पर शाखा लगाएं**: `0` ठीक है · `1` अप्रत्याशित त्रुटि · `2` खराब आर्गुमेंट · `3` डैशबोर्ड तक नहीं पहुंच सकते · `4` लॉगिन नहीं है या समाप्त · `5` अनुमति नहीं है · `6` संसाधन नहीं मिला। +4. **`-h` से खोजें।** प्रत्येक कमांड अपने फ़िल्टर, मान प्रारूप, और JSON आकार का दस्तावेज़ देता है। -## एक बार का सेटअप +## एकबारी सेटअप ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # ताकि आप --base-url दोहराएं नहीं -agenteye login --email you@example.com # ईमेल किया गया कोड पेस्ट करें; ~24h वैध +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # so you don't repeat --base-url +agenteye login --email you@example.com # paste the emailed code; valid ~24h ``` ## काम करने से पहले प्रमाणीकरण की पुष्टि करें -`whoami` कभी भी गायब या समाप्त सेशन पर त्रुटि नहीं देता; इसके बजाय `logged_in:false` की रिपोर्ट करता है, इसलिए एक एजेंट सुरक्षित रूप से प्रमाणीकरण स्थिति को जांच सकता है। (यदि कोई बेस URL सेट नहीं है या डैशबोर्ड तक पहुंचना संभव नहीं है तो यह अभी भी गैर-शून्य निकल सकता है।) +`whoami` एक लापता या समाप्त सेशन पर कभी त्रुटि नहीं करता; यह इसके बजाय `logged_in:false` रिपोर्ट करता है, इसलिए एजेंट सुरक्षित रूप से प्रमाणीकरण स्थिति को प्रोब कर सकता है। (यदि कोई बेस URL सेट नहीं है या डैशबोर्ड अप्राप्य है तो यह अभी भी शून्य-नहीं exit कर सकता है।) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -34,95 +34,95 @@ fi ## विफल या कम स्कोरिंग वाले सेशन खोजें ```bash -# पिछले 24h में सेशन जिनका मूल्यांकन त्रुटि था +# sessions in the last 24h whose evaluation errored agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# एक एजेंट के लिए सहायकता पर 0.5 <= स्कोर करने वाले मूल्यांकन +# evaluations scoring <= 0.5 on helpfulness, for one agent agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -स्कोर फिल्टरिंग **`evals`** पर रहती है, `sessions` पर नहीं। `--score KEY:MIN..MAX` दोहराया जा सकता है और AND-संयुक्त है; दोनों बाउंड वैकल्पिक हैं (`..0.5` मतलब ≤ 0.5, `0.9..` मतलब ≥ 0.9)। आप प्रति अनुरोध 20 स्कोर फिल्टर तक पास कर सकते हैं; अधिक HTTP 400 रिटर्न करता है। `sessions` `evals` के साथ `--env`, `--status`, `--agent-id`, `--session-id` और समय-सीमा फिल्टर साझा करता है, लेकिन `--score` नहीं है। +स्कोर फ़िल्टरिंग `evals` पर रहती है, `sessions` पर नहीं। `--score KEY:MIN..MAX` दोहराया जाने वाला है और AND-संयुक्त है; किसी भी सीमा को वैकल्पिक बनाया जा सकता है (`..0.5` का मतलब ≤ 0.5, `0.9..` का मतलब ≥ 0.9)। आप प्रति अनुरोध 20 स्कोर फ़िल्टर तक पास कर सकते हैं; अधिक HTTP 400 देता है। `sessions` `--env`, `--status`, `--agent-id`, `--session-id`, और समय-सीमा फ़िल्टर को `evals` के साथ साझा करता है, लेकिन `--score` नहीं है। -## एक सेशन को अंत तक पढ़ें +## एक सेशन अंत से अंत तक पढ़ें कोई एकल `session show` कमांड नहीं है। इवेंट ट्रेल को सेशन के मूल्यांकन के साथ मिलाएं: ```bash -# सेशन का नवीनतम मूल्यांकन (स्थिति + स्कोर) +# the session's latest evaluation (status + scores) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# रन में प्रत्येक इवेंट (पूर्ण स्वीप के लिए --limit बढ़ाएं) +# every event in the run (raise --limit for a full sweep) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# एक सेशन में केवल टूल कॉल (कच्चा पेलोड प्राप्त करने के लिए --full आवश्यक है) +# just the tool calls in a session (--full is required to get the raw payload) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **नोट:** डिफ़ॉल्ट रूप से, `events` एक तेज़, पेलोड-मुक्त फीड पढ़ता है। प्रत्येक इवेंट एक सर्वर-गणना किए गए एक-पंक्ति `summary` प्लस `is_error` और टोकन गणना जैसे फ्लैग ले जाता है, लेकिन `payload` `{}` के रूप में वापस आता है। कच्चा पेलोड खींचने के लिए, `--full` (या `--fields payload`) जोड़ें। पूर्ण फीड स्केल पर धीमी है, इसलिए इसे सीमित रखें: `--full` को एकल `--session-id` के साथ जोड़ी। +> **नोट:** डिफ़ॉल्ट रूप से, `events` एक तेज़, पेलोड-मुक्त फ़ीड पढ़ता है। प्रत्येक इवेंट एक सर्वर-गणना की गई एक-लाइन `summary` साथ ले जाता है और `is_error` जैसे फ्लैग और टोकन गिनती, लेकिन `payload` `{}` के रूप में वापस आता है। कच्चा पेलोड खींचने के लिए, `--full` (या `--fields payload`) जोड़ें। पूर्ण फ़ीड स्केल पर धीमा है, इसलिए इसे सीमित रखें: `--full` को एकल `--session-id` के साथ जोड़ी करें। ## सब कुछ प्राप्त करें (पेजिनेशन) -परिणाम नवीनतम-पहले हैं और कर्सर-पेजिनेटेड हैं। +परिणाम सबसे नए-पहले और कर्सर-पेजिनेटेड हैं। ```bash -# एक शॉट: 200-पंक्ति पृष्ठों में 500 पंक्तियों तक प्राप्त करें +# one shot: fetch up to 500 rows in 200-row pages agenteye --json events --session-id run-001 --limit 500 --all > events.json -# मैनुअल पेजिंग: अगले कर्सर को वापस खिलाएं +# manual paging: feed next_cursor back in page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## `--fields` के साथ आउटपुट को स्लिम करें +## --fields से आउटपुट को कम करें -कीज़ को (टेबल और `--json` दोनों में) प्रतिबंधित करें यह कम करने के लिए कि एक एजेंट को क्या पढ़ना होगा। +एजेंट को जो पढ़ना पड़ता है उसे कम करने के लिए कुंजी (तालिका और `--json` दोनों में) को प्रतिबंधित करें। ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -अज्ञात फील्ड नाम को खारिज कर दिया जाता है (निकास `2`) वैध सूची के साथ, फील्ड नाम खोजने का एक सस्ता तरीका। +अज्ञात फ़ील्ड नाम को अस्वीकार कर दिया जाता है (exit `2`) मान्य सूची के साथ, फ़ील्ड नामों की खोज करने का एक सस्ता तरीका। -## वैध फिल्टर मान खोजें +## वैध फ़िल्टर मान खोजें ```bash -agenteye --json list envs | jq -r '.values[]' # --env के लिए मान -agenteye --json list tools | jq -r '.values[]' # टूल नाम; साथ ही एजेंट, मॉडल, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX के लिए वैध KEY +agenteye --json list envs | jq -r '.values[]' # values for --env +agenteye --json list tools | jq -r '.values[]' # tool names; also agents, models, event_types, … +agenteye --json list score_filters | jq -r '.values[]' # valid KEY for --score KEY:MIN..MAX ``` -## अपना org चुनें (मल्टी-टेनेंट) +## अपनी संगठन चुनें (बहु-किरायेदार) -यदि आप एक से अधिक org से संबंधित हैं, तो लॉगिन पर सक्रिय टेनेंट चुनें (यह सहेजा गया है): +यदि आप एक से अधिक संगठनों से संबंधित हैं, तो लॉगिन में सक्रिय किरायेदार चुनें (यह सहेजा गया है): ```bash -agenteye login --org acme --email you@corp.com # लॉगिन के समान चरण में टेनेंट सेट करें +agenteye login --org acme --email you@corp.com # set the tenant in the same step as login agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # एक कमांड के लिए ओवरराइड करें +agenteye --org globex --json sessions --since 24h # override for one command ``` -`--org` के बिना एक मल्टी-org लॉगिन गैर-शून्य निकलता है और चुनने के लिए org प्रिंट करता है। +`--org` के बिना एक बहु-संगठन लॉगिन शून्य-नहीं exit करता है और चुनने के लिए संगठन प्रिंट करता है। -## SDK/कलेक्टर के लिए एक API कुंजी प्रदान करें +## SDK/collector के लिए API कुंजी प्रदान करें ```bash -# गुप्त ONCE प्रिंट होता है, --json के साथ यह .key फील्ड है +# the secret is printed ONCE, with --json it's the .key field key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # घुमाएं; agenteye keys disable ci-bot --yes को रद्द करने के लिए +agenteye keys regenerate ci-bot --yes # rotate; agenteye keys disable ci-bot --yes to revoke ``` -## एक सहेजी गई या ad-hoc क्वेरी चलाएं +## सहेजी गई या ad-hoc क्वेरी चलाएं ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # एक सहेजी गई क्वेरी + एक स्थितीय $1 +agenteye --json query run errs --arg prod | jq '.rows' # a saved query + a positional $1 ``` -## गैर-इंटरैक्टिवली एक घटना को छांटें +## गैर-इंटरैक्टिव रूप से घटना का निदान करें ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -131,9 +131,9 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **नोट:** म्यूटेशन `--json` के तहत या जब stdin TTY नहीं है तो अपनी पुष्टि प्रॉम्प्ट को स्वचालित रूप से छोड़ देते हैं, इसलिए एजेंट कभी हैंग नहीं होते; अन्यत्र इसे स्पष्ट रूप से छोड़ने के लिए `--yes`/`-y` पास करें। +> **नोट:** म्यूटेशन `--json` के तहत अपने कन्फर्मेशन प्रॉम्प्ट को स्वचालित रूप से छोड़ते हैं या जब stdin TTY नहीं है, इसलिए एजेंट कभी हैंग नहीं करते; अन्यत्र स्पष्ट रूप से इसे छोड़ने के लिए `--yes`/`-y` पास करें। -## एक स्क्रिप्ट में एक्जिट-कोड हैंडलिंग +## स्क्रिप्ट में Exit-code हैंडलिंग ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -157,22 +157,22 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` एक बार दिखाया गया) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` shown once) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (any) | संसाधन ऑब्जेक्ट, या डिलीट्स के लिए `{"deleted": true, "id"}` | -| failure (any, `--json` के साथ) | stdout पर `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | +| create/update/delete (any) | संसाधन ऑब्जेक्ट, या हटाने के लिए `{"deleted": true, "id"}` | +| विफलता (कोई भी, `--json` के साथ) | stdout पर `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | -- प्रत्येक **event** आइटम (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`। ध्यान दें कि `payload` तब तक `{}` है जब तक आप `--full` (या `--fields payload`) के साथ पूर्ण फीड का अनुरोध नहीं करते। -- प्रत्येक **evaluation** आइटम (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`। -- प्रत्येक **session** आइटम (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`। +- प्रत्येक **इवेंट** आइटम (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`। ध्यान दें कि `payload` `{}` है जब तक आप `--full` (या `--fields payload`) के साथ पूर्ण फ़ीड का अनुरोध नहीं करते। +- प्रत्येक **मूल्यांकन** आइटम (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`। +- प्रत्येक **सेशन** आइटम (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`। -प्रत्येक कमांड का `--fields` अपने ही आइटम के फील्ड नाम को स्वीकार करता है। सेट `sessions` और `evals` के बीच अलग है, इसलिए एक के लिए वैध नाम दूसरे द्वारा अस्वीकृत हो सकता है। +प्रत्येक कमांड का `--fields` बिल्कुल अपने स्वयं के आइटम के फ़ील्ड नामों को स्वीकार करता है। सेट `sessions` और `evals` के बीच अलग है, इसलिए एक के लिए वैध नाम दूसरे द्वारा अस्वीकार किया जा सकता है। -## अगले चरण +## अगले कदम -- [CLI](/hi/agenteye/cli): इंस्टॉलेशन, प्रमाणीकरण और प्रत्येक कमांड के लिए पूर्ण विकल्प संदर्भ। -- [CLI agent skill](/hi/agenteye/cli-skill): इन रेसिपीज़ को एक कौशल के रूप में पैकेज करें जो आपका कोडिंग एजेंट लोड कर सकता है। -- [API keys](/hi/agenteye/api-keys): कुंजीज़ बनाएं और स्कोप करें जो CLI, SDK और कलेक्टर प्रमाणीकरण करते हैं। -- [Python SDK](/hi/agenteye/python-sdk): Failproof AI Observability में इवेंट भेजें ताकि इन रेसिपीज़ के लिए क्वेरी करने के लिए डेटा हो। \ No newline at end of file +- [CLI](/hi/agenteye/cli): इंस्टॉलेशन, प्रमाणीकरण, और प्रत्येक कमांड के लिए पूर्ण विकल्प संदर्भ। +- [CLI agent skill](/hi/agenteye/cli-skill): इन रेसिपी को एक कौशल के रूप में पैकेज करें जो आपका कोडिंग एजेंट लोड कर सकता है। +- [API keys](/hi/agenteye/api-keys): CLI, SDK, और कलेक्टर को प्रमाणित करने वाली कुंजीएं बनाएं और स्कोप करें। +- [Python SDK](/hi/agenteye/python-sdk): Failproof AI Observability में इवेंट भेजें ताकि इन रेसिपी को क्वेरी करने के लिए डेटा हो। \ No newline at end of file diff --git a/docs/hi/agenteye/cli-skill.mdx b/docs/hi/agenteye/cli-skill.mdx index 0d0adf88..cb2e0282 100644 --- a/docs/hi/agenteye/cli-skill.mdx +++ b/docs/hi/agenteye/cli-skill.mdx @@ -1,159 +1,160 @@ --- +--- title: "Failproof AI Observability CLI Agent Skill" -description: "अपने कोडिंग एजेंट से पूछें \"क्या आज कुछ टूटा है?\" और इसे अपने लाइव Failproof AI Observability डेटा से जवाब दें, कोई कमांड याद रखने की जरूरत नहीं।" +description: "अपने कोडिंग एजेंट से पूछें कि \"क्या आज कुछ टूटा है?\" और इसे अपने लाइव Failproof AI Observability डेटा से जवाब देने दें, बिना किसी कमांड को याद रखने के।" --- -अपने कोडिंग एजेंट से *"क्या आज कुछ टूटा है?"* पूछें और इसे अपने लाइव Failproof AI Observability डेटा से जवाब दें, कोई कमांड याद रखने की जरूरत नहीं। **Failproof AI Observability CLI स्किल** (`agenteye-cli`) एक *Agent Skill* है: निर्देशों का एक छोटा फोल्डर जिसे Claude Code या Codex जैसा कोडिंग एजेंट मांग पर लोड करता है। यह एजेंट को [`agenteye` CLI](/hi/agenteye/cli) के माध्यम से आपके Observability डिप्लॉयमेंट को संचालित करना सिखाता है साधारण अंग्रेजी अनुरोधों से जैसे *"CI को एक कुंजी दें जो केवल इवेंट पुश कर सके"* या *"फायरिंग इंसिडेंट को स्वीकृति दें और इसे मुझे असाइन करें।"* +अपने कोडिंग एजेंट से *"क्या आज कुछ टूटा है?"* पूछें और इसे अपने लाइव Failproof AI Observability डेटा से जवाब देने दें, बिना किसी कमांड को याद रखने के। **Failproof AI Observability CLI स्किल** (`agenteye-cli`) एक *Agent Skill* है: निर्देशों का एक छोटा फोल्डर जिसे Claude Code या Codex जैसा कोडिंग एजेंट ज़रूरत पड़ने पर लोड करता है। यह एजेंट को [`agenteye` CLI](/hi/agenteye/cli) के माध्यम से आपके Observability डिप्लॉयमेंट को संचालित करना सिखाता है, साधारण अंग्रेजी अनुरोधों से जैसे *"CI को एक कुंजी दें जो केवल ईवेंट भेज सके"* या *"फायरिंग इंसिडेंट को स्वीकार करें और इसे मुझे असाइन करें।"* -यह **नहीं** एक सेवा या अलग बाइनरी है; तैनात करने के लिए कुछ भी नहीं है। यह उस CLI के ऊपर काम करता है जिसे आप पहले से इंस्टॉल कर चुके हैं: एजेंट `agenteye --json …` को शेल करता है, स्वच्छ JSON को पार्स करता है, और आपको गद्य में जवाब देता है। यह जो कुछ भी कर सकता है, आप इसे स्वयं कर सकते हैं। +यह **नहीं** एक सेवा या अलग बाइनरी है; इसे डिप्लॉय करने के लिए कुछ नहीं है। यह उस CLI के ऊपर चलता है जो आप पहले से इंस्टॉल कर चुके हैं: एजेंट `agenteye --json …` को चलाता है, साफ JSON को पार्स करता है, और आपको गद्य में जवाब देता है। यह जो कुछ भी कर सकता है, आप उन्हीं कमांड को टाइप करके खुद कर सकते हैं। --- ## यह अन्य Failproof AI Observability इंटरफेस से कैसे संबंधित है -Failproof AI Observability आपको समान डेटा और नियंत्रण तक पहुंचने के चार तरीके देता है। वे एक दूसरे की पूरक हैं: +Failproof AI Observability आपको एक ही डेटा और कंट्रोल तक पहुंचने के चार तरीके देता है। वे एक दूसरे को पूरक करते हैं: -| इंटरफेस | यह क्या है | यह कहां चलता है | इसे कब चुनें | +| इंटरफेस | यह क्या है | यह कहां चलता है | इसे तब चुनें जब | |---|---|---|---| -| **[CLI](/hi/agenteye/cli)** | `agenteye` के लिए कमांड/फ्लैग संदर्भ | आपका टर्मिनल | जब आप एक विशिष्ट कमांड चलाना या स्क्रिप्ट करना चाहते हैं | -| **[CLI recipes](/hi/agenteye/cli-recipes)** | कॉपी-पेस्ट `jq`/पाइपलाइन पैटर्न | आपका टर्मिनल / स्क्रिप्ट | जब आप CLI को ऑटोमेशन में वायर कर रहे हैं | -| **CLI स्किल** (यह दस्तावेज़) | CLI पर एक प्राकृतिक भाषा का प्रवेश द्वार | आपका कोडिंग एजेंट, आपके वर्कस्टेशन पर | जब आप बस पूछना चाहते हैं और एजेंट को कमांड चुनने दें | -| **[Evaluator स्किल](/hi/agenteye/evaluator-skill)** | एक सहायक स्किल जो आपकी स्कोरिंग सेवा डिज़ाइन और बनाती है | आपका कोडिंग एजेंट, आपके वर्कस्टेशन पर | जब आप eval स्कोर पढ़ने के बजाय *उत्पन्न* करना चाहते हैं | -| **[Python SDK स्किल](/hi/agenteye/python-sdk-skill)** | एक सहायक स्किल जो आपके एजेंट को सभी टेलीमेट्री उत्सर्जित करने के लिए सक्षम करती है | आपका कोडिंग एजेंट, आपके वर्कस्टेशन पर | जब आप अपने एजेंट को यह स्किल जो इवेंट पढ़ती है उन्हें *उत्पन्न* करना चाहते हैं | -| **[In-dashboard AI सहायक](/hi/agenteye/assistant)** | डैशबोर्ड में एम्बेड किया गया एक चैट | सर्वर-साइड (डैशबोर्ड में) | जब आप अपने डेटा पर इन-डैशबोर्ड प्रश्नोत्तर चाहते हैं | +| **[CLI](/hi/agenteye/cli)** | `agenteye` के लिए कमांड/फ्लैग संदर्भ | आपका टर्मिनल | आप कोई विशिष्ट कमांड चलाना या स्क्रिप्ट करना चाहते हैं | +| **[CLI recipes](/hi/agenteye/cli-recipes)** | कॉपी-पेस्ट `jq`/पाइपलाइन पैटर्न | आपका टर्मिनल / स्क्रिप्ट | आप CLI को ऑटोमेशन में वायर कर रहे हैं | +| **CLI स्किल** (यह दस्तावेज़) | CLI पर प्राकृतिक-भाषा फ्रंट डोर | आपका कोडिंग एजेंट, आपके वर्कस्टेशन पर | आप बस पूछना चाहते हैं और एजेंट को कमांड चुनने दें | +| **[Evaluator स्किल](/hi/agenteye/evaluator-skill)** | एक सहयोगी स्किल जो आपकी स्कोरिंग सेवा को डिजाइन और बनाता है | आपका कोडिंग एजेंट, आपके वर्कस्टेशन पर | आप eval स्कोर *बनाना* चाहते हैं बजाय उन्हें पढ़ने के | +| **[Python SDK स्किल](/hi/agenteye/python-sdk-skill)** | एक सहयोगी स्किल जो आपके एजेंट को ताकि वह सभी जगह टेलीमेट्री भेजे | आपका कोडिंग एजेंट, आपके वर्कस्टेशन पर | आप अपने एजेंट को *बनाना* चाहते हैं ईवेंट भेजने के लिए जिसे यह स्किल पढ़ता है | +| **[इन-डैशबोर्ड AI असिस्टेंट](/hi/agenteye/assistant)** | डैशबोर्ड में एम्बेडेड एक चैट | सर्वर-साइड (डैशबोर्ड में) | आप अपने डेटा पर इन-डैशबोर्ड Q&A चाहते हैं | -स्किल के अपने कोई विशेषाधिकार नहीं हैं; यह केवल आपके शब्दों को CLI कॉल में बदलता है जो आपके रूप में चलते हैं: +स्किल के पास अपनी कोई विशेषाधिकार नहीं है; यह केवल आपके शब्दों को CLI कॉल में बदलता है जो आप के रूप में चलते हैं: ```mermaid flowchart TD - YOU["आप: 'फायरिंग इंसिडेंट को स्वीकृति दें'"] --> AGENT["कोडिंग एजेंट (Claude Code / Codex)
agenteye-cli स्किल लोड करता है"] + YOU["आप: 'फायरिंग इंसिडेंट को स्वीकार करें'"] --> AGENT["कोडिंग एजेंट (Claude Code / Codex)
agenteye-cli स्किल को लोड करता है"] AGENT --> CLI["agenteye --json incidents ack ..."] CLI -->|आपका प्रमाणित CLI सेशन| API["Observability डैशबोर्ड API"] ``` -### बनाम in-dashboard AI सहायक: एक महत्वपूर्ण अंतर +### बनाम इन-डैशबोर्ड AI असिस्टेंट: एक महत्वपूर्ण अंतर -ये दो बिल्कुल अलग उपकरण हैं जिनके अलग-अलग प्रभाव हैं: +ये दो अलग-अलग उपकरण हैं जिनकी बहुत अलग-अलग सीमाएं हैं: -- **in-dashboard AI सहायक** ([AI सहायक](/hi/agenteye/assistant)) डैशबोर्ड में एम्बेड किया गया एक चैट है, जो एजेंट सेवा द्वारा समर्थित है। यह **केवल-पढ़ने योग्य और अनुमोदन-गेटेड लेखन** है: यह सहेजे गए क्वेरी और डैशबोर्ड का ड्राफ्ट कर सकता है, लेकिन प्रत्येक लिखने से आपकी स्पष्ट क्लिक-अनुमोदन के लिए रुकता है, और यह कभी हटाता नहीं है। यह `agent:use` अनुमति द्वारा गेट किया जाता है और केवल उस संगठन के लिए डेटा देखता है जिसे आप देख रहे हैं। -- **CLI स्किल** आपके वर्कस्टेशन पर आपके कोडिंग एजेंट के अंदर चलती है और `agenteye` CLI को **आपके रूप में** चलाती है। यह CLI की **पूर्ण सतह, म्यूटेशन सहित** कर सकती है (API कुंजी बनाएं/घुमाएं/अक्षम करें, संगठन सेटिंग्स बदलें, इंसिडेंट हल करें, सहेजे गए क्वेरी हटाएं), केवल आपकी CLI लॉगिन की अनुमतियों द्वारा सीमित। इसे बिल्कुल उसी तरह व्यवहार करें जैसे आप उन कमांडों को हाथ से चलाना चाहते हैं। +- **इन-डैशबोर्ड AI असिस्टेंट** ([AI असिस्टेंट](/hi/agenteye/assistant)) डैशबोर्ड में एम्बेडेड एक चैट है, एजेंट सेवा द्वारा समर्थित। यह **केवल-पढ़ना प्लस अनुमोदन-गेट ऑथरिंग** है: यह सहेजे गए प्रश्नों और डैशबोर्ड को ड्राफ्ट कर सकता है, लेकिन हर लेखन आपके स्पष्ट क्लिक-अनुमोदन के लिए रुकता है, और यह कभी नहीं हटाता है। यह `agent:use` अनुमति द्वारा गेट किया गया है और केवल उस संगठन के लिए डेटा देखता है जिसे आप देख रहे हैं। +- **CLI स्किल** आपके वर्कस्टेशन पर *आपके* कोडिंग एजेंट के अंदर चलता है और `agenteye` CLI को **आप** के रूप में चलाता है। यह CLI की **संपूर्ण सतह, म्यूटेशन सहित** कर सकता है (API कुंजियां बनाएं/रोटेट/अक्षम करें, संगठन सेटिंग्स बदलें, इंसिडेंट रिज़ॉल्व करें, सहेजे गए प्रश्नों को हटाएं), केवल आपके CLI लॉगिन की अनुमतियों द्वारा सीमित। इसे बिल्कुल उसी तरह व्यवहार करें जैसे आप उन कमांड को हाथ से चलाना चाहते हैं। --- ## आवश्यकताएं -1. **`agenteye` CLI इंस्टॉल** और `PATH` पर (देखें [CLI](/hi/agenteye/cli) संदर्भ: `pipx install agenteye`)। -2. आपका **डैशबोर्ड URL सेट** (`AGENTEYE_DASHBOARD_URL`, या एजेंट `--base-url` पास करता है)। -3. एक **लॉगिन किया गया सेशन**: पहले स्वयं `agenteye login` चलाएं। स्किल **नहीं** कर सकता ईमेल किए गए एकबारी-कोड लॉगिन को आपके लिए पूरा करना; यह आपको `agenteye login` चलाने के लिए कहेगा यदि सेशन अनुपस्थित या समाप्त है (CLI एक्सिट कोड `4`)। +1. **`agenteye` CLI इंस्टॉल किया हुआ** और `PATH` पर (देखें [CLI](/hi/agenteye/cli) संदर्भ: `pipx install agenteye`)। +2. आपका **डैशबोर्ड URL सेट किया हुआ** (`AGENTEYE_DASHBOARD_URL`, या एजेंट `--base-url` पास करता है)। +3. एक **लॉग इन सेशन**: पहले `agenteye login` को स्वयं चलाएं। स्किल **नहीं** ईमेल किए गए एकबारी-कोड लॉगिन को आपके लिए पूरा कर सकता है; यह आपको `agenteye login` चलाने के लिए कहेगा यदि सेशन गायब या समाप्त है (CLI एक्जिट कोड `4`)। --- -## इसे कहां से प्राप्त करें +## इसे कहां प्राप्त करें स्किल Failproof AI के सार्वजनिक स्किल संग्रह में प्रकाशित है: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -इसके बारे में कुछ भी गेटेड नहीं है — रिपॉजिटरी सार्वजनिक है और स्किल को अपने क्रेडेंशियल की आवश्यकता नहीं है, क्योंकि यह केवल **सार्वजनिक** `agenteye` CLI को आपके डैशबोर्ड के विरुद्ध चलाता है, सेशन का उपयोग करते हुए *आप* लॉगिन किए हैं। आपको किसी से इसके लिए पूछना नहीं है। +इसके बारे में कुछ भी गेट किया नहीं है — रिपॉजिटरी सार्वजनिक है और स्किल को अपने स्वयं के किसी क्रेडेंशियल की आवश्यकता नहीं है, क्योंकि यह केवल **सार्वजनिक** `agenteye` CLI को *आपके* डैशबोर्ड के विरुद्ध चलाता है, सेशन का उपयोग करके *आप* लॉग इन किए गए। आपको किसी से इसके लिए पूछने की आवश्यकता नहीं है। -नोट करें कि यह अपने स्वयं के फोल्डर के रूप में शिप करता है और `pipx install agenteye` पैकेज के अंदर **नहीं** है, इसलिए इसे वहां न ढूंढें। +ध्यान दें कि यह अपने स्वयं के फोल्डर के रूप में शिप करता है और `pipx install agenteye` पैकेज के अंदर **नहीं** है, तो वहां इसे न देखें। -## स्किल स्थापित करना +## स्किल को इंस्टॉल करना -सबसे तेज़ रास्ता [`skills`](https://skills.sh) CLI है, जो फोल्डर लाता है और इसे वहां डालता है जहां आपका एजेंट देखता है: +सबसे तेज़ रास्ता [`skills`](https://skills.sh) CLI है, जो फोल्डर को प्राप्त करता है और इसे वहां डालता है जहां आपका एजेंट देखता है: ```bash # Claude Code, केवल यह प्रोजेक्ट npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -# हर प्रोजेक्ट (~/.claude/skills/ में इंस्टॉल करता है) +# हर प्रोजेक्ट (इंस्टॉल करता है ~/.claude/skills/ में) npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy # इसके बजाय Codex npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -फिर इसे किसी अन्य स्किल की तरह प्रबंधित करें: +फिर इसे किसी भी अन्य स्किल की तरह प्रबंधित करें: ```bash npx skills list -a claude-code # क्या इंस्टॉल है -npx skills update agenteye-cli # नवीनतम संस्करण लाएं -npx skills remove agenteye-cli # इसे निकालें +npx skills update agenteye-cli # नवीनतम संस्करण प्राप्त करें +npx skills remove agenteye-cli # इसे हटाएं ``` -हाथ से इंस्टॉल करना पसंद करते हैं? एक Agent Skill केवल एक फोल्डर है जिसमें एक `SKILL.md` है (साथ ही वैकल्पिक संदर्भ), इसलिए इसे कॉपी करना भी काम करता है: +हाथ से इंस्टॉल करना पसंद करते हैं? एक Agent Skill केवल `SKILL.md` (साथ ही वैकल्पिक संदर्भ) युक्त एक फोल्डर है, इसलिए इसे कॉपी करना काम करता है: -- **Claude Code**: `agenteye-cli/` फोल्डर को `~/.claude/skills/` (हर प्रोजेक्ट) या `/.claude/skills/` (केवल वह रेपो) में रखें। Claude Code इसे स्वचालित रूप से खोजता है — `/skills` सूची के साथ सत्यापित करें, या बस एक प्रश्न पूछें जो इसके विवरण से मेल खाता हो। -- **Codex (OpenAI)**: Codex समान `SKILL.md` को पढ़ता है। बंडल किया गया `agents/openai.yaml` `allow_implicit_invocation: true` सेट करता है, इसलिए Codex स्वचालित रूप से कार्य से मेल खाने पर स्किल चुनता है; अन्यथा इसे `$agenteye-cli` के रूप में स्पष्ट रूप से आह्वान करें। +- **Claude Code**: `agenteye-cli/` फोल्डर को `~/.claude/skills/` में रखें (हर प्रोजेक्ट) या `/.claude/skills/` (केवल वह रिपॉजिटरी)। Claude Code स्वचालित रूप से इसे खोजता है — `/skills` सूची के साथ सत्यापित करें, या बस कोई प्रश्न पूछें जो इसके विवरण से मेल खाता हो। +- **Codex (OpenAI)**: Codex एक ही `SKILL.md` को पढ़ता है। बंडल किए गए `agents/openai.yaml` को `allow_implicit_invocation: true` सेट करता है, इसलिए Codex स्वचालित रूप से स्किल को चुनता है जब कोई कार्य मेल खाता है; अन्यथा इसे स्पष्ट रूप से `$agenteye-cli` के रूप में आह्वान करें। --- -## सुरक्षा: म्यूटेशन जब एजेंट CLI चलाता है तो प्रॉम्प्ट नहीं करता +## सुरक्षा: जब एजेंट CLI चलाता है तो म्यूटेशन संकेत नहीं देते > **चेतावनी:** एजेंट को परिवर्तन करने देने से पहले यह पढ़ें। -`agenteye` CLI आमतौर पर विनाशकारी कार्य से पहले *"क्या आप सुनिश्चित हैं?"* पूछता है। यह **स्वचालित रूप से पुष्टि को छोड़ देता है जब यह टर्मिनल से जुड़ा नहीं होता है (जो बिल्कुल वैसे ही होता है जैसे एक कोडिंग एजेंट इसे चलाता है), और `--json` भी इसे छोड़ देता है।** तो सुरक्षा प्रॉम्प्ट एजेंट के लिए **नहीं** चलेगा। +`agenteye` CLI सामान्य रूप से विनाशकारी कार्रवाई से पहले *"क्या आप सुनिश्चित हैं?"* पूछता है। यह **जब भी टर्मिनल से जुड़ा नहीं होता (जो बिल्कुल वैसे ही है कि कोडिंग एजेंट इसे चलाता है), तो स्वचालित रूप से इस पुष्टि को छोड़ देता है, और `--json` भी इसे छोड़ देता है।** तो सुरक्षा संकेत एजेंट के लिए **नहीं** होगा। -स्किल इसे मुआवजे के लिए लिखी गई है: इसे सटीक कमांड बताने के लिए निर्देश दिया जाता है जो यह चलाएगा और किसी भी स्थिति परिवर्तन से पहले आपकी स्पष्ट **OK** प्राप्त करना होगा। उस अनुशासन को रखें। जब आप Failproof AI Observability को एजेंट के माध्यम से चलाते हैं, *आप* पुष्टि चरण हैं। स्थिति-परिवर्तन कमांड देखने के लिए: +स्किल मुआवजे के लिए लिखा गया है: इसे सटीक कमांड को बताने का निर्देश दिया जाता है जो यह चलाएगा और किसी भी स्थिति परिवर्तन से पहले आपकी स्पष्ट **ठीक है** प्राप्त करें। उस अनुशासन को रखें। जब आप Failproof AI Observability को एजेंट के माध्यम से चलाते हैं, *आप* पुष्टि चरण होते हैं। स्थिति-परिवर्तन करने वाली कमांड जिन पर नज़र रखनी है: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` - `settings set` - `alerts create` / `update` / `delete` / `test` -- लिखने वाली `incidents` उप-कमांड: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` +- लेखन `incidents` सबकमांड: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` - `query create` / `update` / `delete` - `agent rename` / `delete` - `orgs switch` -**Observe** के अंतर्गत सब कुछ (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) केवल-पढ़ने योग्य है और कुछ नहीं बदलता। +**Observe** के तहत सब कुछ (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) केवल-पढ़ना है और कुछ भी नहीं बदलता है। -क्योंकि एजेंट **आपके रूप में** कार्य करता है, यह केवल वही कर सकता है जो आपकी लॉगिन को अनुमति दी गई है; अनुमतियां **प्रति संगठन** हल होती हैं (देखें [API कुंजी](/hi/agenteye/api-keys))। एक कमांड जिसके लिए आपके पास अनुमति नहीं है exit code `5` को सटीक अनुमति के साथ लौटाता है, इसलिए एजेंट आपको बता सकता है कि आप प्रशासक से क्या पूछ सकते हैं बजाय अस्पष्ट रूप से विफल होने के। +क्योंकि एजेंट **आप** के रूप में कार्य करता है, यह केवल वह कर सकता है जो आपके लॉगिन को करने की अनुमति है; अनुमतियों को **प्रति संगठन** हल किया जाता है (देखें [API कुंजियां](/hi/agenteye/api-keys))। एक कमांड जिसके लिए आपके पास अनुमति नहीं है, एक्जिट कोड `5` के साथ सटीक अनुमति नामित करके लौटता है, इसलिए एजेंट आपको बता सकता है कि आप एक प्रशासक से क्या पूछने के लिए कहें, बजाय अस्पष्ट रूप से विफल होने के। --- ## आप इससे क्या पूछ सकते हैं -यहां एक वास्तविक राउंड-ट्रिप दिखता है, एक पढ़ना, फिर एक परिवर्तन जो आपकी OK की प्रतीक्षा करता है: +यहाँ एक वास्तविक राउंड-ट्रिप कैसा दिखता है, एक पढ़ना, फिर एक परिवर्तन जो आपके ठीक होने की प्रतीक्षा करता है: ```text -आप ▸ क्या पिछले दिन में कुछ टूटा है? +आप ▸ क्या पिछले दिन में कुछ टूटा हुआ है? -एजेंट ▸ चल रहा है: agenteye --json errors --since 24h --aggregate - पिछले 24 घंटे में 3 त्रुटि प्रकार। सबसे बड़ा TimeoutError - (18 हिट, सभी checkout-agent पर), फिर RateLimited (5)। +एजेंट ▸ चला रहे हैं: agenteye --json errors --since 24h --aggregate + पिछले 24 घंटों में 3 त्रुटि प्रकार। सबसे बड़ा है TimeoutError + (18 हिट्स, सभी checkout-agent पर), फिर RateLimited (5)। क्या आप TimeoutError के लिए विफल सेशन चाहते हैं? -आप ▸ CI को एक कुंजी दें जो केवल इवेंट पुश कर सके। +आप ▸ CI को एक कुंजी दें जो केवल ईवेंट भेज सके। एजेंट ▸ यह एक API कुंजी बनाता है। मैं चलाऊंगा: agenteye keys create ci --add events:add - क्या आगे बढ़ना OK है? + आगे बढ़ने के लिए ठीक है? -आप ▸ हां +आप ▸ हाँ -एजेंट ▸ हो गया। कुंजी "ci" केवल events:add के साथ बनाई गई। - गुप्त केवल एक बार दिखाया जाता है, इसलिए इसे अभी स्टोर करें। मैं इसे फिर से प्रिंट नहीं कर सकता। +एजेंट ▸ पूरा। कुंजी "ci" केवल events:add के साथ बनाई गई। + गोपनीय केवल एक बार दिखाया जाता है, इसलिए अभी इसे स्टोर करें। मैं इसे फिर से प्रिंट नहीं कर सकता। ``` -स्किल प्रत्येक सादे अंग्रेजी इरादे को सही `agenteye` कमांड पर मैप करती है, पहले मान्य मान खोजती है (`list `, `whoami`) इसलिए यह अनुमान नहीं लगाता, और किसी भी परिवर्तन से पहले सटीक कमांड बताता है। अधिक उदाहरण: +स्किल प्रत्येक सादे-अंग्रेजी आशय को सही `agenteye` कमांड में मैप करता है, पहले वैध मान (`list `, `whoami`) की खोज करके ताकि यह अनुमान न लगाए, और किसी भी परिवर्तन से पहले सटीक कमांड को बताए। अधिक उदाहरण: -- *"क्या पिछले 24 घंटों में कुछ टूटा / विफल है?"* → `errors --since 24h --aggregate`, फिर एक विस्तृतीकरण। -- *"सेशन `run-001` क्यों विफल रहा?"* → `events --session-id run-001 --all` + `evals --session-id run-001`। -- *"इस हफ्ते गुणवत्ता कैसी है?"* → `evals --aggregate --since 7d`, फिर कम-स्कोरिंग रन में ड्रिल करें। -- *"CI को एक कुंजी दें जो केवल इवेंट पुश कर सके।"* → `keys create ci --add events:add` (यह कमांड बताता है, फिर इसे बनाता है और एकबारी गुप्त को कैप्चर करता है)। -- *"किसके पास पहुंच है? Dana को केवल-पढ़ने योग्य बनाएं।"* → `users list` → `users update dana@… --permission-set read-only` (आपकी पुष्टि के बाद)। -- *"फायरिंग इंसिडेंट को स्वीकृति दें और इसे मुझे असाइन करें।"* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`। +- *"क्या कुछ टूटा / विफल हो रहा है पिछले 24 घंटों में?"* → `errors --since 24h --aggregate`, फिर एक ब्रेकडाउन। +- *"सेशन `run-001` क्यों विफल हुआ?"* → `events --session-id run-001 --all` + `evals --session-id run-001`। +- *"गुणवत्ता इस हफ्ते कैसी प्रवृत्ति दिख रही है?"* → `evals --aggregate --since 7d`, फिर कम-स्कोरिंग रन में ड्रिल करें। +- *"CI को एक कुंजी दें जो केवल ईवेंट भेज सके।"* → `keys create ci --add events:add` (यह कमांड को बताता है, फिर इसे बनाता है और एकबारी गोपनीय को कैप्चर करता है)। +- *"किसके पास एक्सेस है? Dana को केवल-पढ़ना बनाएं।"* → `users list` → `users update dana@… --permission-set read-only` (आपके साथ पुष्टि के बाद)। +- *"फायरिंग इंसिडेंट को स्वीकार करें और इसे मुझे असाइन करें।"* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`। -सटीक कमांड, फ्लैग और JSON आकार के लिए, [CLI](/hi/agenteye/cli) संदर्भ और [एजेंट के लिए CLI recipes](/hi/agenteye/cli-recipes) देखें। +सटीक कमांड, फ्लैग, और इन के पीछे के JSON आकार के लिए, देखें [CLI](/hi/agenteye/cli) संदर्भ और [एजेंट के लिए CLI recipes](/hi/agenteye/cli-recipes)। --- ## अगले कदम -- **[CLI](/hi/agenteye/cli)**: `agenteye` के लिए पूर्ण कमांड और फ्लैग संदर्भ। -- **[एजेंट के लिए CLI recipes](/hi/agenteye/cli-recipes)**: कॉपी-पेस्ट `jq` पैटर्न और exit-code हैंडलिंग। -- **[Evaluator एजेंट स्किल](/hi/agenteye/evaluator-skill)**: सहायक स्किल, evaluator बनाने के लिए जिसके स्कोर `agenteye evals` पढ़ता है। -- **[Python SDK एजेंट स्किल](/hi/agenteye/python-sdk-skill)**: सहायक स्किल, एजेंट को सक्षम करने के लिए जो टेलीमेट्री उत्सर्जित करता है `agenteye` पढ़ता है। -- **[AI सहायक](/hi/agenteye/assistant)**: in-dashboard सहायक (इस टर्मिनल स्किल के साथ भ्रमित न करें)। -- **[API कुंजी](/hi/agenteye/api-keys)**: प्रति-संगठन अनुमति मॉडल जो स्किल को क्या कर सकता है इसे बांधता है। \ No newline at end of file +- **[CLI](/hi/agenteye/cli)**: `agenteye` के लिए संपूर्ण कमांड और फ्लैग संदर्भ। +- **[एजेंट के लिए CLI recipes](/hi/agenteye/cli-recipes)**: कॉपी-पेस्ट `jq` पैटर्न और एक्जिट-कोड हैंडलिंग। +- **[Evaluator एजेंट स्किल](/hi/agenteye/evaluator-skill)**: सहयोगी स्किल, evaluator को बनाने के लिए जिसके स्कोर `agenteye evals` पढ़ता है। +- **[Python SDK एजेंट स्किल](/hi/agenteye/python-sdk-skill)**: सहयोगी स्किल, एजेंट को ताकि वह टेलीमेट्री भेजे जिसे `agenteye` पढ़ता है। +- **[AI असिस्टेंट](/hi/agenteye/assistant)**: इन-डैशबोर्ड असिस्टेंट (इस टर्मिनल स्किल के साथ भ्रमित न करें)। +- **[API कुंजियां](/hi/agenteye/api-keys)**: प्रति-संगठन अनुमति मॉडल जो स्किल को क्या कर सकता है इसे सीमित करता है। \ No newline at end of file diff --git a/docs/hi/agenteye/cli.mdx b/docs/hi/agenteye/cli.mdx index efe81e2b..82af7388 100644 --- a/docs/hi/agenteye/cli.mdx +++ b/docs/hi/agenteye/cli.mdx @@ -4,22 +4,22 @@ description: "Failproof AI Observability को टर्मिनल या स --- -Failproof AI Observability को टर्मिनल या स्क्रिप्ट से पूरी तरह चलाएँ: कोई डैशबोर्ड राउंड-ट्रिप नहीं। `agenteye` CLI आपके डेटा (सेशन, इवेंट लॉग, मूल्यांकन) को क्वेरी करता है और आपके संगठन (API कुंजियाँ, उपयोगकर्ता, सेटिंग्स, अलर्ट, घटनाएँ, सहेजी गई क्वेरी) का प्रबंधन करता है, इसलिए जब आप किसी जाँच को स्वचालित करना चाहते हैं, CI में Observability को जोड़ना चाहते हैं, या कोई कोडिंग एजेंट प्रोडक्शन का निरीक्षण करे, तो इसका उपयोग करें। प्रत्येक कमांड `--json` फ़्लैग को सपोर्ट करता है, इसलिए यह प्रॉम्प्ट पर आपके लिए समान रूप से अच्छी तरह काम करता है या कोई कोडिंग एजेंट (Claude Code, Cursor) शेल आउट करके परिणाम पार्स कर सकता है। +Failproof AI Observability को टर्मिनल या स्क्रिप्ट से चलाएँ: कोई डैशबोर्ड राउंड-ट्रिप नहीं। `agenteye` CLI आपके डेटा (सेशन, इवेंट लॉग, इवेल्यूएशन) को क्वेरी करता है और आपके ऑर्ग को प्रबंधित करता है (API कीज, यूजर, सेटिंग्स, अलर्ट्स, इंसिडेंट्स, सहेजी गई क्वेरीज), इसलिए जब आप कोई चेक ऑटोमेट करना चाहते हैं, CI में Observability को जोड़ना चाहते हैं, या किसी कोडिंग एजेंट को प्रोडक्शन निरीक्षण करने दें तो इसे चुनें। हर कमांड `--json` फ्लैग को सपोर्ट करता है, इसलिए यह आपके लिए प्रॉम्प्ट पर या किसी कोडिंग एजेंट (Claude Code, Cursor) के लिए समान रूप से काम करता है जो शेल आउट करके परिणाम पार्स करता है। -एक ही बाइनरी के साथ आप कर सकते हैं: +एक ही बाइनरी से आप कर सकते हैं: -- **अपना डेटा पढ़ें**: `sessions`, `events`, `evals`, `errors` (समय, एजेंट, env, स्कोर के अनुसार फ़िल्टर करें)। -- **अपने संगठन को प्रबंधित करें**: `keys`, `users`, `settings`, `alerts`, `incidents`। -- **विश्लेषण चलाएँ**: सहेजी गई SQL और एडहॉक क्वेरी रनर (`query`)। -- **AI सहायक से पूछें**: वही केवल-पढ़ने वाले विश्लेषक जो आप डैशबोर्ड में चैट करते हैं (`agent`)। +- **अपना डेटा पढ़ें**: `sessions`, `events`, `evals`, `errors` (समय, एजेंट, env, स्कोर से फ़िल्टर करें)। +- **अपने ऑर्ग को प्रबंधित करें**: `keys`, `users`, `settings`, `alerts`, `incidents`। +- **एनालिटिक्स चलाएँ**: सहेजी गई SQL और एक ad-hoc क्वेरी रनर (`query`)। +- **AI असिस्टेंट से पूछें**: वही read-only एनालिस्ट जिससे आप डैशबोर्ड में चैट करते हैं (`agent`)। -> **नोट:** यह `agenteye` CLI है, कलेक्टर डेमॉन (`agenteye-collector`) से एक अलग टूल है। CLI आपके डैशबोर्ड से बात करता है; कलेक्टर घटनाओं को सर्वर में भेजता है। +> **नोट:** यह `agenteye` CLI है, कलेक्टर डेमॉन (`agenteye-collector`) से एक अलग टूल। CLI आपके डैशबोर्ड से बात करता है; कलेक्टर सर्वर को इवेंट भेजता है। --- -## त्वरित शुरुआत +## क्विकस्टार्ट -शून्य से लेकर पहला परिणाम चार पंक्तियों में। CLI को अपने डैशबोर्ड पर इंगित करें, साइन इन करें, पुष्टि करें कि आप कौन हैं, फिर पिछले दिन के रन खींचें: +कुछ भी न होने से अपने पहले परिणाम तक चार लाइनों में पहुँचें। CLI को अपने डैशबोर्ड पर इंगित करें, साइन इन करें, पुष्टि करें कि आप कौन हैं, फिर पिछले दिन के रन्स खींचें: ```bash pipx install agenteye @@ -28,7 +28,7 @@ agenteye whoami agenteye --json sessions --since 24h # one row per agent run, last 24h ``` -वह अंतिम कमांड सबसे हाल के सेशन (नवीनतम पहले, डिफ़ॉल्ट रूप से 50 पर सीमित) का JSON ऑब्जेक्ट प्रिंट करता है। इसे `jq` में पाइप करें इसे स्लाइस करने के लिए, या `--json` ड्रॉप करें एक बॉक्सवाला, रंगीन तालिका के लिए। प्रत्येक पंक्ति रन की स्थिति ले जाती है और, यदि कोई मूल्यांकनकर्ता इसे स्कोर करता है, तो इसके मीट्रिक स्कोर (यहाँ संक्षिप्त): +यह आखिरी कमांड सबसे हाल के सेशन का एक JSON ऑब्जेक्ट प्रिंट करता है (नवीनतम पहले, डिफ़ॉल्ट रूप से 50 तक सीमित)। इसे `jq` में पाइप करके स्लाइस करें, या शुद्ध टेबल के लिए `--json` छोड़ें। प्रत्येक पंक्ति रन की स्थिति और, यदि किसी इवेल्यूएटर ने इसे स्कोर किया है, तो इसके मेट्रिक स्कोर (यहाँ संक्षिप्त) ले जाती है: ```json { @@ -48,28 +48,28 @@ agenteye --json sessions --since 24h } ``` -इस पृष्ठ के बाकी हिस्से प्रत्येक टुकड़े की व्याख्या करते हैं: [अलगाव में स्थापित करना](#installation), [साइन इन करना](#authentication), [कॉन्फ़िगरेशन](#configuration), [वैश्विक कन्वेंशन](#global-options--conventions) जो प्रत्येक कमांड साझा करता है, और [पूर्ण कमांड संदर्भ](#command-reference)। +यह पृष्ठ बाकी सब कुछ समझाता है: अलग से [इंस्टॉल करना](#installation), [साइन इन करना](#authentication), [कॉन्फ़िगरेशन](#configuration), हर कमांड जो [वैश्विक सम्मेलन](#global-options--conventions) साझा करता है, और [पूर्ण कमांड संदर्भ](#command-reference)। --- -## स्थापना +## इंस्टॉलेशन -CLI एक सार्वजनिक PyPI पैकेज है जिसका नाम **`agenteye`** है। इसे एक अलग वातावरण में स्थापित करें ताकि इसके पास हमेशा अपनी खुद की निर्भरताएँ हों: +CLI एक सार्वजनिक PyPI पैकेज है जिसका नाम **`agenteye`** है। इसे एक अलग वातावरण में इंस्टॉल करें ताकि इसके पास हमेशा अपनी निर्भरताएँ हों: ```bash pipx install agenteye -# या +# or uv tool install agenteye ``` -इसके लिए Python 3.10+ की आवश्यकता है। स्थापित कमांड है **`agenteye`**: +इसे Python 3.10+ की आवश्यकता है। इंस्टॉल की गई कमांड **`agenteye`** है: ```bash agenteye --version agenteye --help ``` -> **नोट:** Failproof AI Observability Python SDK भी `agenteye` वितरण नाम का उपयोग करता है। `pipx` या `uv tool` के साथ CLI को स्थापित करना (साझा virtualenv में `pip install` के बजाय) दोनों को टकराने से रोकता है। एक सादा `pip install agenteye` तभी ठीक है यदि SDK उसी वातावरण में स्थापित नहीं है। +> **नोट:** Failproof AI Observability Python SDK भी `agenteye` वितरण नाम का उपयोग करता है। `pipx` या `uv tool` के साथ CLI इंस्टॉल करना (एक साझा virtualenv में `pip install` के बजाय) दोनों को टकराने से रखता है। एक सादा `pip install agenteye` केवल तभी ठीक है जब SDK उसी वातावरण में इंस्टॉल न हो। --- @@ -82,22 +82,22 @@ agenteye login --email you@example.com # A 6-digit code is emailed to you; paste it at the prompt. ``` -सेशन टोकन `~/.agenteye/cli.json` में संग्रहीत है (केवल आपके द्वारा पठनीय, मोड `0600`) और डिफ़ॉल्ट रूप से 24 घंटे के लिए वैध है। जब यह समाप्त हो जाए, `agenteye login` को फिर से चलाएँ। +सेशन टोकन `~/.agenteye/cli.json` में संग्रहीत है (केवल आपके द्वारा पठनीय, मोड `0600`) और डिफ़ॉल्ट रूप से 24 घंटे के लिए वैध है। जब यह समाप्त हो जाए, तो फिर से `agenteye login` चलाएँ। ```bash agenteye whoami # show the current user, active org, and permissions agenteye logout # revoke the session and clear the stored token ``` -`whoami` कभी भी लापता या समाप्त सेशन पर त्रुटि नहीं करता; बजाय इसके `logged_in: false` की रिपोर्ट करता है, इसलिए एक स्क्रिप्ट या एजेंट सुरक्षित रूप से प्रमाणन स्थिति की जाँच कर सकता है (यदि कोई आधार URL सेट नहीं है या डैशबोर्ड अप्राप्य है तो यह अभी भी गैर-शून्य बाहर निकल सकता है)। +`whoami` किसी लापता या समाप्त सेशन पर कभी त्रुटि नहीं करता; इसके बजाय `logged_in: false` रिपोर्ट करता है, इसलिए एक स्क्रिप्ट या एजेंट सुरक्षित रूप से प्रमाणन स्थिति की जाँच कर सकता है (यदि कोई base URL सेट नहीं है या डैशबोर्ड पहुँच योग्य नहीं है तो यह अभी भी शून्येतर हो सकता है)। -**आवश्यकताएँ:** आपके ईमेल को डैशबोर्ड में साइन इन करने की अनुमति दी जानी चाहिए (अपने Failproof AI Observability व्यवस्थापक से पूछें), और डैशबोर्ड को इसके आधार URL पर पहुँचने योग्य होना चाहिए (देखें [कॉन्फ़िगरेशन](#configuration))। यदि आप कोड का अनुरोध करते हैं और कोई भी नहीं आता है, तो आपका ईमेल शायद अभी तक डैशबोर्ड पहुँच के लिए सक्षम नहीं है। +**आवश्यकताएँ:** आपके ईमेल को डैशबोर्ड में साइन इन करने की अनुमति दी जानी चाहिए (अपने Failproof AI Observability प्रशासक से पूछें), और डैशबोर्ड को इसके base URL पर पहुँचने योग्य होना चाहिए (देखें [कॉन्फ़िगरेशन](#configuration))। यदि आप कोड का अनुरोध करते हैं और कोई नहीं आता है, तो आपके ईमेल को संभवतः डैशबोर्ड एक्सेस के लिए अभी तक सक्षम नहीं किया गया है। --- -## अपने संगठन को चुनना (मल्टी-टेनेंट) +## अपने ऑर्ग को चुनना (मल्टी-टेनेंट) -यदि आपका खाता एक से अधिक संगठनों से संबंधित है, तो **लॉगिन के समय** सक्रिय चुनें; यह सहेजा जाता है और हर बाद की कमांड के लिए उपयोग किया जाता है: +यदि आपका खाता एक से अधिक ऑर्ग से संबंधित है, तो **लॉगिन पर** सक्रिय को चुनें; इसे सहेजा जाता है और बाद में हर कमांड के लिए उपयोग किया जाता है: ```bash agenteye login --org acme # authenticate and set the active tenant in one step @@ -106,87 +106,87 @@ agenteye orgs switch globex # change the saved default agenteye --org globex sessions # override for a single command ``` -यदि आप ठीक एक संगठन से संबंधित हैं तो यह स्वचालित रूप से चुना जाता है और आप `--org` को पूरी तरह अनदेखा कर सकते हैं। यदि आप कई से संबंधित हैं और एक नहीं चुनते हैं, तो CLI उन्हें सूचीबद्ध करता है और आपको `--org ` के साथ फिर से चलाने के लिए कहता है। सक्रिय संगठन हर अनुरोध पर डैशबोर्ड को भेजा जाता है, और आपकी अनुमतियाँ **प्रति संगठन** हल की जाती हैं; `agenteye whoami` सक्रिय संगठन, इसमें आपकी अनुमतियाँ, और आपकी सभी सदस्यताएँ दिखाता है। +यदि आप केवल एक ऑर्ग से संबंधित हैं तो इसे स्वचालित रूप से चुना जाता है और आप `--org` को पूरी तरह अनदेखा कर सकते हैं। यदि आप कई से संबंधित हैं और एक को नहीं चुनते, तो CLI उन्हें सूचीबद्ध करता है और आपको `--org ` के साथ फिर से चलाने के लिए कहता है। सक्रिय ऑर्ग हर अनुरोध पर डैशबोर्ड को भेजा जाता है, और आपकी अनुमतियाँ **प्रति ऑर्ग** हल की जाती हैं; `agenteye whoami` सक्रिय ऑर्ग, इसमें आपकी अनुमतियाँ, और आपकी सभी सदस्यताएँ दिखाता है। --- ## कॉन्फ़िगरेशन -| सेटिंग | फ़्लैग | पर्यावरण चर | डिफ़ॉल्ट | +| सेटिंग | फ्लैग | पर्यावरण चर | डिफ़ॉल्ट | |---|---|---|---| -| डैशबोर्ड आधार URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **आवश्यक** (कोई डिफ़ॉल्ट नहीं) | -| सक्रिय संगठन/टेनेंट | `--org` | `AGENTEYE_ORG` | लॉगिन के समय चुना गया; `~/.agenteye/cli.json` में सहेजा गया | +| डैशबोर्ड base URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **आवश्यक** (कोई डिफ़ॉल्ट नहीं) | +| सक्रिय ऑर्ग/टेनेंट | `--org` | `AGENTEYE_ORG` | लॉगिन पर चुना गया; `~/.agenteye/cli.json` में सहेजा गया | | सेशन टोकन | `--token` | `AGENTEYE_CLI_TOKEN` | `~/.agenteye/cli.json` से | | JSON आउटपुट | `--json` | `AGENTEYE_CLI_JSON` | बंद | | TLS सत्यापन छोड़ें | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | बंद (लॉगिन पर सहेजा गया) | | अनुरोध टाइमआउट (सेकंड) | `--timeout` | _(कोई नहीं)_ | 30 | -| उपयोग टेलीमेट्री अक्षम करें | _(कोई नहीं)_ | `AGENTEYE_ANALYTICS_DISABLED` (या `DO_NOT_TRACK`) | टेलीमेट्री वर्तमान में अक्षम है; कुछ भी नहीं भेजा जाता है | +| उपयोग टेलीमेट्री अक्षम करें | _(कोई नहीं)_ | `AGENTEYE_ANALYTICS_DISABLED` (या `DO_NOT_TRACK`) | टेलीमेट्री वर्तमान में अक्षम है; कुछ भी नहीं भेजा गया | -संकल्प क्रम है **फ़्लैग → पर्यावरण चर → कॉन्फ़िग फ़ाइल**। कोई डिफ़ॉल्ट नहीं है; आपको CLI को अपने डैशबोर्ड पर इंगित करना चाहिए, या तो प्रति-कमांड (`--base-url https://agenteye.example.com`) या एक बार पर्यावरण के माध्यम से (यह आपके पहले `login` के बाद भी सहेजा जाता है): +रिज़ॉल्यूशन क्रम **फ्लैग → पर्यावरण चर → कॉन्फ़िग फाइल** है। कोई डिफ़ॉल्ट नहीं है; आपको CLI को अपने डैशबोर्ड पर इंगित करना होगा, या तो प्रति-कमांड (`--base-url https://agenteye.example.com`) या एक बार पर्यावरण के माध्यम से (यह आपके पहले `login` के बाद भी सहेजा जाता है): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -कॉन्फ़िगरेशन निर्देशिका `AGENTEYE_HOME` को सम्मानित करती है (SDK और कलेक्टर द्वारा उपयोग की जाने वाली एक ही परंपरा); यदि सेट है, तो `cli.json` `$AGENTEYE_HOME/cli.json` में रहता है। +कॉन्फ़िगरेशन निर्देशिका `AGENTEYE_HOME` को सम्मानित करती है (SDK और कलेक्टर द्वारा उपयोग किया गया यही सम्मेलन); यदि सेट है, `cli.json` `$AGENTEYE_HOME/cli.json` में रहता है। -### स्व-हस्ताक्षरित या आंतरिक TLS +### स्वयं-हस्ताक्षरित या आंतरिक TLS -यदि आपका डैशबोर्ड स्व-हस्ताक्षरित या आंतरिक प्रमाणपत्र के साथ HTTPS पर परोसा जाता है (उदाहरण के लिए, एक कच्चा लोड-बैलेंसर होस्टनाम), तो TLS सत्यापन `CERTIFICATE_VERIFY_FAILED` त्रुटि के साथ इसे अस्वीकार कर देता है। प्रमाणपत्र सत्यापन छोड़ने के लिए `--insecure` पास करें: +यदि आपका डैशबोर्ड एक स्वयं-हस्ताक्षरित या आंतरिक प्रमाणपत्र के साथ HTTPS पर परोसा जाता है (उदाहरण के लिए, एक कच्चा लोड-बैलेंसर होस्टनाम), TLS सत्यापन इसे `CERTIFICATE_VERIFY_FAILED` त्रुटि के साथ अस्वीकार करता है। प्रमाणपत्र सत्यापन छोड़ने के लिए `--insecure` पास करें: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` **लॉगिन के समय `cli.json` में सहेजा जाता है**, इसलिए बाद की कमांड स्वचालित रूप से सत्यापन छोड़ देते हैं; आपको फ़्लैग को दोहराना नहीं होगा। एकबारी सत्यापित कॉल के लिए, या अपने अगले लॉगिन पर सत्यापन को वापस बंद करने के लिए `--secure` पास करें। CLI जब भी कोई कमांड डैशबोर्ड से संपर्क करता है तो stderr को एक चेतावनी प्रिंट करता है जबकि सत्यापन अक्षम है। सत्यापन छोड़ना मैन-इन-द-मिडल हमलों से सुरक्षा को हटाता है; अपने डैशबोर्ड के लिए नेटवर्क पथ पर भरोसा करने से पहले सुनिश्चित करें कि आप उस पर भरोसा करते हैं (VPN, निजी सबनेट, आदि)। +`--insecure` **`cli.json` में सहेजा जाता है जब आप लॉगिन करते हैं**, इसलिए बाद की कमांड स्वचालित रूप से सत्यापन छोड़ते हैं; आपको फ्लैग को दोहराना नहीं है। एक-बार सत्यापित कॉल के लिए `--secure` पास करें, या अपने अगले लॉगिन पर सत्यापन वापस बंद करने के लिए। CLI डैशबोर्ड से संपर्क करते समय किसी भी कमांड से पहले stderr को एक चेतावनी प्रिंट करता है जबकि सत्यापन अक्षम है। सत्यापन छोड़ना man-in-the-middle हमलों से सुरक्षा को हटाता है; अपने डैशबोर्ड के नेटवर्क पथ (VPN, निजी सबनेट, आदि) पर निर्भर करने से पहले सुनिश्चित करें कि आप इस पर भरोसा करते हैं। --- ## टेलीमेट्री और गोपनीयता -> **नोट:** शिप किया गया CLI **आज कोई उपयोग टेलीमेट्री नहीं भेजता।** एक मास्टर किल स्विच चालू है, इसलिए आपके पर्यावरण के बावजूद कुछ भी प्रेषित नहीं होता है। नीचे दिया गया अनुभाग यदि और जब टेलीमेट्री कभी सक्षम हो तो ऑप्ट-आउट क्षमता का वर्णन करता है। +> **नोट:** भेजी गई CLI आज **कोई उपयोग टेलीमेट्री नहीं भेजता।** एक मास्टर किल स्विच चालू है, इसलिए आपके पर्यावरण की परवाह किए बिना कुछ भी नहीं भेजा जाता है। नीचे का अनुभाग opt-out क्षमता का वर्णन करता है यदि और जब टेलीमेट्री कभी सक्षम हो। -यहाँ तक कि सक्षम होने पर, टेलीमेट्री **केवल अनाम उपयोग विश्लेषण** होगा, कभी आपके एजेंट, सेशन, या घटना डेटा नहीं: +यहाँ तक कि जब सक्षम हो, टेलीमेट्री **केवल गुमनाम उपयोग एनालिटिक्स** होगा, कभी आपके एजेंट, सेशन, या इवेंट डेटा नहीं: -- **कोई भी एजेंट, सेशन, या घटना डेटा कभी भी आपके बुनियादी ढाँचे से बाहर नहीं जाता।** केवल CLI उपयोग की रिपोर्ट की जाएगी: कमांड और सबकमांड का नाम (जैसे `keys create`), आपके द्वारा उपयोग किए गए फ़्लैग के **नाम** (कभी उनके मान नहीं), सफलता/निकास स्थिति, और अवधि, साथ ही उत्परिवर्तन के लिए प्रति-क्रिया घटना (जैसे `api_key_created`, `query_run`) केवल स्थिर नाम/enums और मोटा गणना ले जाना। आपके डैशबोर्ड URL, सेशन टोकन, ईमेल, org slug, संसाधन ids, SQL, कुंजी रहस्य, और क्वेरी फ़िल्टर कभी **नहीं** भेजे जाएँगे। संचालकों की पहचान केवल एक अपारदर्शी आंतरिक id द्वारा की जाएगी, कभी ईमेल द्वारा नहीं। -- **`AGENTEYE_ANALYTICS_DISABLED=1` CLI के पर्यावरण में सेट करके पहले से ऑप्ट आउट करें** (CLI क्रॉस-टूल `DO_NOT_TRACK=1` परंपरा को भी सम्मानित करता है)। यह प्रभाव तब लेता है जब टेलीमेट्री कभी चालू हो जाता है, इसलिए गोपनीयता-सचेत वातावरण स्थायी रूप से ऑप्ट आउट रह सकता है। -- यदि टेलीमेट्री सक्षम थे, तो CLI सीधे PostHog (`https://us.i.posthog.com`) को भेजेगा; एक मशीन जिसमें वह होस्ट अवरुद्ध है, चुप्पी से कुछ भी नहीं भेजेगी और CLI प्रभावित नहीं होगी। +- **कोई एजेंट, सेशन, या इवेंट डेटा कभी आपके बुनियादी ढाँचे से नहीं निकलता।** केवल CLI उपयोग रिपोर्ट किया जाएगा: कमांड और सबकमांड नाम (उदा. `keys create`), आपने **नामों** का उपयोग किए गए फ्लैग्स (कभी उनके मानों नहीं), सफलता/exit स्थिति, और अवधि, साथ ही म्यूटेशन के लिए एक प्रति-कार्रवाई इवेंट (उदा. `api_key_created`, `query_run`) केवल स्थिर नामों/enums और कोर्स गणना ले जाता है। आपके डैशबोर्ड URL, सेशन टोकन, ईमेल, ऑर्ग slug, संसाधन ids, SQL, कुंजी रहस्य, और क्वेरी फ़िल्टर **कभी** नहीं भेजे जाएँगे। ऑपरेटरों को केवल एक अपारदर्शी आंतरिक id द्वारा पहचाना जाएगा, कभी ईमेल द्वारा नहीं। +- **आगे से opt out** करें `AGENTEYE_ANALYTICS_DISABLED=1` को CLI के पर्यावरण में सेट करके (CLI क्रॉस-टूल `DO_NOT_TRACK=1` सम्मेलन को भी सम्मानित करता है)। यह तब लागू होता है जब टेलीमेट्री कभी चालू होता है, इसलिए गोपनीयता-सचेत पर्यावरण स्थायी रूप से opted out रह सकता है। +- यदि टेलीमेट्री सक्षम थे, तो CLI सीधे PostHog (`https://us.i.posthog.com`) को भेजता; उस होस्ट को अवरुद्ध करने वाली एक मशीन चुप से कुछ नहीं भेजती और CLI प्रभावित नहीं होता। --- -## वैश्विक विकल्प और कन्वेंशन +## वैश्विक विकल्प और सम्मेलन -इसे एक बार पढ़ें; यह हर कमांड पर लागू होता है। +यह एक बार पढ़ें; यह हर कमांड पर लागू होता है। -- **वैश्विक विकल्प कमांड से पहले जाते हैं।** `agenteye --json sessions` सही है; `agenteye sessions --json` एक उपयोग त्रुटि है। विश्वव्यापी विकल्प `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, और `--no-color` हैं। -- **`--json` stdout को शुद्ध JSON प्रिंट करता है, और कुछ नहीं।** मानव स्थिति पंक्तियाँ, चेतावनियाँ, और त्रुटियाँ **stderr** में जाती हैं, इसलिए `--json` stdout कैप्चर तब भी स्वच्छ रहता है जब एक स्थिति पंक्ति दिखाई दे। `--json` के बिना आप मानव आँखों के लिए एक बॉक्सवाला, रंगीन दृश्य प्राप्त करते हैं। -- **`--help` के साथ खोजें।** प्रत्येक कमांड और सबकमांड में `--help` (और `-h` उपनाम) है: `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`। शीर्ष-स्तरीय सहायता निकास कोड और वैश्विक विकल्प भी सूचीबद्ध करती है। कोई वैश्विक मशीन-पठनीय सतह डंप नहीं है; प्रति-कमांड `--help` का उपयोग करें, साथ ही डोमेन-विशिष्ट `agenteye query schema` और `agenteye settings schema` उन दो रजिस्ट्रियों के लिए। -- **पुष्टियाँ स्क्रिप्ट और एजेंटों के लिए स्वचालित रूप से छोड़ दी जाती हैं।** बनाएँ/अपडेट/हटाएँ कमांड एक इंटरैक्टिव टर्मिनल में "क्या आप सुनिश्चित हैं?" प्रॉम्प्ट करते हैं, लेकिन **`--json` के तहत या जब भी stdin कोई TTY नहीं है (एक TTY एक इंटरैक्टिव टर्मिनल सत्र है; एक पाइप या CI रनर नहीं) तो स्वचालित रूप से उस प्रॉम्प्ट को छोड़ दें**, इसलिए स्क्रिप्ट और एजेंट कभी भी हैंग नहीं करते। `--yes`/`-y` पास करके इसे स्पष्ट रूप से छोड़ दें। क्योंकि एक एजेंट के लिए प्रॉम्प्ट फायर नहीं होगा, एक एजेंट को विनाशकारी कार्यों की मानव द्वारा पहले पुष्टि करनी चाहिए। -- **पृष्ठांकन:** परिणाम सबसे नए-पहले और कर्सर-पृष्ठांकित हैं (प्रत्येक पृष्ठ एक टोकन देता है जो आप अगला लाने के लिए उपयोग करते हैं)। `--limit N` (उपनाम `-n`) पंक्तियों को कैप करता है और **डिफ़ॉल्ट रूप से 50**; `--all` स्वचालित-पृष्ठांकन (200-पंक्ति चंक में) **`--limit` तक**, इसलिए एक बंधे हुए `--all` अभी भी 50 पर रुकते हैं। एक पूर्ण स्वीप के लिए एक उच्च स्पष्ट कैप पास करें: `--all --limit 1000`। `--page-size N` प्रति-अनुरोध चंक नियंत्रित करता है (अधिकतम 200); `--cursor ` पूर्व पृष्ठ के `next_cursor` से फिर से शुरू करता है। -- **समय फ़िल्टर:** `--since` एक सापेक्ष विंडो लेता है: `15m`, `1h`, `6h`, `24h`, `7d`, या `all` (डैशबोर्ड की पूर्वनिर्धारितें)। एक लंबी या कस्टम रेंज के लिए (कहें पिछले 30 दिन), `--from`/`--to` का उपयोग करें: स्पष्ट ISO-8601 UTC टाइमस्टैम्प **`T` और एक टाइमजोन के साथ** (जैसे `2026-06-01T00:00:00Z`) जो `--since` को ओवरराइड करते हैं। एक स्पेस-अलग या टाइमजोन-रहित मान एक उपयोग त्रुटि है। -- **`--fields a,b,c`** (`events`, `sessions`, `evals`, `errors` पर) आउटपुट को उन कुंजियों तक सीमित करता है, तालिका और `--json` दोनों के लिए। अज्ञात नाम मान्य सूची के साथ अस्वीकार किए जाते हैं, क्षेत्र नामों की खोज करने का एक सस्ता तरीका। -- **`--file payload.json`** (या `--file -` stdin को पढ़ने के लिए) एक पूर्ण JSON अनुरोध बॉडी प्रदान करता है जहाँ एक संसाधन में एक जटिल आकार है (`alerts create/update`, `settings set`, और `users create/update` पर)। सहेजी गई-क्वेरी SQL `--sql @file.sql` का उपयोग करता है। -- **मल्टी-मान फ़िल्टर** अल्पविराम-अलग हैं → एक सेट के रूप में मेल खाए (एक फ़िल्टर के भीतर संघ, फ़िल्टर भर में AND): `--event-type tool_use,tool_result`। क्लिक विकल्प variadic नहीं हैं, इसलिए `--add a b` टूट जाता है। `--add a,b` का उपयोग करें, फ़्लैग दोहराएँ (`--add a --add b`), या उद्धृत करें (`--add "a b"`)। +- **वैश्विक विकल्प कमांड से पहले जाते हैं।** `agenteye --json sessions` सही है; `agenteye sessions --json` एक उपयोग त्रुटि है। वैश्विक `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, और `--no-color` हैं। +- **`--json` stdout पर शुद्ध JSON प्रिंट करता है, और कुछ और नहीं।** मानव स्थिति पंक्तियाँ, चेतावनियाँ, और त्रुटियाँ **stderr** पर जाती हैं, इसलिए एक `--json` stdout कैप्चर स्वच्छ रहता है एक स्थिति पंक्ति दिखाए जाने पर भी `jq` में पाइप करने के लिए। `--json` के बिना आप मानव आँखों के लिए एक boxed, colourised दृश्य प्राप्त करते हैं। +- **`--help` के साथ खोजें।** हर कमांड और सबकमांड के पास `--help` (और `-h` उपनाम) है: `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`। top-level help भी exit codes और वैश्विक विकल्पों को सूचीबद्ध करता है। कोई वैश्विक मशीन-पठनीय सतह डंप नहीं है; प्रति-कमांड `--help` का उपयोग करें, साथ ही उन दोनों रजिस्ट्रियों के लिए डोमेन-विशिष्ट `agenteye query schema` और `agenteye settings schema`। +- **पुष्टिकरण स्वचालित रूप से स्क्रिप्ट और एजेंट के लिए छोड़ते हैं।** Create/update/delete कमांड एक इंटरैक्टिव टर्मिनल में "क्या आप सुनिश्चित हैं?" प्रदर्शित करते हैं, लेकिन **`--json` के अंतर्गत या जब भी stdin एक TTY नहीं है** (एक TTY एक इंटरैक्टिव टर्मिनल सेशन है; एक पाइप या CI रनर नहीं है) तो उस प्रॉम्प्ट को स्वचालित रूप से छोड़ते हैं, इसलिए स्क्रिप्ट और एजेंट कभी हैंग नहीं होते। इसे स्पष्ट रूप से छोड़ने के लिए `--yes`/`-y` पास करें। क्योंकि एजेंट के लिए प्रॉम्प्ट नहीं होगा, एजेंट को विनाशकारी कार्यों की पुष्टि करनी चाहिए मानव के साथ पहले। +- **पेजिनेशन:** परिणाम नवीनतम-प्रथम और cursor-paginated हैं (प्रत्येक पृष्ठ एक टोकन लौटाता है जो आप अगला प्राप्त करने के लिए उपयोग करते हैं)। `--limit N` (उपनाम `-n`) पंक्तियों को कैप करता है और **डिफ़ॉल्ट 50** है; `--all` स्वचालित-पेजिनेट करता है (200-पंक्ति चंक में) **`--limit` तक**, इसलिए एक बेयर `--all` अभी भी 50 पर रुकता है। एक पूर्ण स्वीप के लिए एक उच्च स्पष्ट कैप पास करें: `--all --limit 1000`। `--page-size N` प्रति-अनुरोध चंक को नियंत्रित करता है (अधिकतम 200); `--cursor ` एक पूर्व पृष्ठ के `next_cursor` से फिर से शुरू करता है। +- **समय फ़िल्टर:** `--since` एक सापेक्ष विंडो लेता है: `15m`, `1h`, `6h`, `24h`, `7d`, या `all` (डैशबोर्ड के प्रीसेट)। एक लंबी या कस्टम रेंज के लिए (कहें पिछले 30 दिन), `--from`/`--to` का उपयोग करें: स्पष्ट ISO-8601 UTC टाइमस्टैम्प **`T` और एक टाइमजोन** के साथ (उदा. `2026-06-01T00:00:00Z`) जो `--since` को ओवरराइड करते हैं। एक स्पेस-अलग किया गया या टाइमजोन-रहित मान एक उपयोग त्रुटि है। +- **`--fields a,b,c`** (`events`, `sessions`, `evals`, `errors` पर) आउटपुट को उन कुंजियों तक सीमित करता है, तालिका और `--json` दोनों के लिए। अज्ञात नाम वैध सूची के साथ अस्वीकार किए जाते हैं, फ़ील्ड नामों की खोज करने का एक सस्ता तरीका। +- **`--file payload.json`** (या `--file -` stdin पढ़ने के लिए) एक पूर्ण JSON अनुरोध बॉडी सরबराह करता है जहाँ एक संसाधन में एक जटिल आकार है (`alerts create/update`, `settings set`, और `users create/update` पर)। Saved-query SQL `--sql @file.sql` के बजाय उपयोग करता है। +- **बहु-मान फ़िल्टर** कॉमा-अलग किए गए हैं → एक सेट के रूप में मेल खाते हैं (एक फ़िल्टर के भीतर यूनियन, फ़िल्टर भर में AND): `--event-type tool_use,tool_result`। क्लिक विकल्प variadic नहीं हैं, इसलिए `--add a b` तोड़ता है। `--add a,b` का उपयोग करें, फ्लैग को दोहराएँ (`--add a --add b`), या उद्धृत करें (`--add "a b"`)। --- ## कमांड संदर्भ -### आप इन 5 कमांडों का सबसे अधिक उपयोग करेंगे +### आप इन 5 कमांडों का सबसे अधिक उपयोग करते हैं -अधिकांश दिन-प्रतिदिन का काम कुछ पढ़ने की कमांड के माध्यम से चलता है। यहाँ शुरू करें, फिर नीचे पूर्ण सतह तक पहुँचें जब आपको इसकी आवश्यकता हो: +अधिकांश दिन-प्रतिदिन का काम कुछ read कमांड के माध्यम से चलता है। यहाँ शुरू करें, फिर जब आपको इसकी आवश्यकता हो तो नीचे पूर्ण सतह तक पहुँचें: -| कमांड | यह क्या करता है | इसे आज़माएँ | +| कमांड | यह क्या करता है | इसे आजमाएँ | |---|---|---| -| `sessions` | एक एजेंट रन प्रति पंक्ति: समय, env, एजेंट, स्थिति, नवीनतम स्कोर। | `agenteye --json sessions --since 24h --status error` | -| `events` | एक रन (अधिक पेलोड के लिए `--full` जोड़ें) के अंदर कच्चा प्रति-कदम पथ। | `agenteye --json events --session-id run-001 --all` | -| `evals` | मूल्यांकन परिणाम और स्कोर; `--aggregate` उन्हें रोल करता है। | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | बस त्रुटि वाली घटनाएँ; `--aggregate` प्रकार के अनुसार गणना के लिए। | `agenteye --json errors --since 24h --aggregate` | -| `list` | मान्य फ़िल्टर मान (एजेंट, envs, मॉडल, ...) की खोज करें। | `agenteye list agents` | +| `sessions` | एजेंट रन प्रति एक पंक्ति: समय, env, एजेंट, स्थिति, नवीनतम स्कोर। | `agenteye --json sessions --since 24h --status error` | +| `events` | एक रन के अंदर कच्ची per-step ट्रेल (`--full` payloads के लिए जोड़ें)। | `agenteye --json events --session-id run-001 --all` | +| `evals` | मूल्यांकन परिणाम और स्कोर; `--aggregate` उन्हें roll up करता है। | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | बस errored events; `--aggregate` type द्वारा counts के लिए। | `agenteye --json errors --since 24h --aggregate` | +| `list` | वैध फ़िल्टर मान खोजें (एजेंट, envs, मॉडल, …)। | `agenteye list agents` | -### CLI जो कुछ भी कर सकता है +### सब कुछ जो CLI कर सकता है -पूरी सतह का अनुसरण करता है। CLI में **18 शीर्ष-स्तरीय कमांड** हैं। सभी पढ़ने की कमांड `--json` और ऊपर वैश्विक विकल्पों को स्वीकार करते हैं; किसी भी एक के लिए विस्तृत फ़्लैग सूची और JSON आकार के लिए `agenteye -h` (या ` -h`) चलाएँ। +पूर्ण सतह अनुसरण करती है। CLI के **18 top-level commands** हैं। सभी read कमांड `--json` और ऊपर वैश्विक विकल्प स्वीकार करते हैं; किसी को भी exhaustive flag सूची और JSON आकार के लिए `agenteye -h` (या ` -h`) चलाएँ। ### पहचान: `login` · `logout` · `whoami` · `orgs` · `version` · `help` @@ -198,7 +198,7 @@ agenteye version # print the CLI version (s agenteye help # top-level help (same as --help) ``` -`orgs` सक्रिय टेनेंट का निरीक्षण और स्विच करता है: +`orgs` सक्रिय टेनेंट को निरीक्षण और स्विच करता है: ```bash agenteye orgs list # your orgs + your role in each (active one marked) @@ -207,9 +207,9 @@ agenteye orgs current # identity card for the active org agenteye orgs perms # your permissions in the active org, grouped by resource ``` -### अवलोकन करें (केवल-पढ़ने योग्य): `events` · `sessions` · `evals` · `errors` · `list` +### अवलोकन (read-only): `events` · `sessions` · `evals` · `errors` · `list` -इनमें से कोई भी पुष्टि की आवश्यकता नहीं है। साझा फ़िल्टर: `--session-id`, `--agent-id`, `--env` (**नहीं** `--environment`), और समय रेंज (`--since` / `--from` / `--to`)। +इनमें से कोई भी पुष्टिकरण की आवश्यकता नहीं है। साझा फ़िल्टर: `--session-id`, `--agent-id`, `--env` (**not** `--environment`), और समय रेंज (`--since` / `--from` / `--to`)। ```bash # events (alias: the raw per-step trail), newest first @@ -232,16 +232,16 @@ agenteye --json errors --since 24h --error-type timeout --all --limit 1000 agenteye list envs # also: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (`evals` पर, `sessions` नहीं) दोहराया जाता है और AND-संयुक्त है; या तो बाउंड वैकल्पिक है (`..0.5` का अर्थ ≤ 0.5, `0.9..` का अर्थ ≥ 0.9)। प्रति अनुरोध 20 स्कोर फ़िल्टर तक। `evals --scores-full` **मानव तालिका केवल के लिए** एक डिस्प्ले फ़्लैग है; यह पहले कुछ के बजाय हर स्कोर जोड़ी और `+N` गणना दिखाता है। `--json` के तहत इसका कोई प्रभाव नहीं है, जो हमेशा पूर्ण स्कोर ऑब्जेक्ट लौटाता है। **एक सेशन अंत तक पढ़ने के लिए**, घटना पथ को इसके मूल्यांकन के साथ संयोजित करें: +`--score KEY:MIN..MAX` (**`evals`** पर, `sessions` नहीं) दोहराए जाने योग्य है और AND-संयुक्त है; किसी भी bound को वैकल्पिक (`..0.5` मतलब ≤ 0.5, `0.9..` मतलब ≥ 0.9)। प्रति अनुरोध 20 स्कोर फ़िल्टर तक। `evals --scores-full` एक प्रदर्शन फ्लैग है **मानव तालिका केवल के लिए**; यह पहले कुछ के बजाय हर स्कोर जोड़ी दिखाता है साथ ही एक `+N` गणना। यह `--json` के अंतर्गत कोई प्रभाव नहीं है, जो हमेशा पूर्ण स्कोर ऑब्जेक्ट लौटाता है। **एक सेशन को अंत तक** पढ़ने के लिए, इवेंट ट्रेल को इसके मूल्यांकन के साथ संयोजित करें: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' agenteye --json evals --session-id run-001 # its scores + status ``` -### प्रबंधन करें (अनुमति-गेटेड): `keys` · `users` · `settings` · `alerts` · `incidents` +### प्रबंधित (अनुमति-gated): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: API कुंजियाँ। रहस्य स्थानीय रूप से उत्पन्न होता है, सर्वर को भेजा जाता है (जो केवल एक हैश संग्रहीत करता है), और **एक बार** बनाएँ/पुनर्जन्म पर दिखाया जाता है; इसे तब कैप्चर करें। `--json` के साथ यह केवल `key` फ़ील्ड में दिखाई देता है। **नाम** द्वारा संदर्भित। +**`keys`**: API कीज। रहस्य को स्थानीय रूप से उत्पन्न किया जाता है, सर्वर को भेजा जाता है (जो केवल एक hash संग्रहीत करता है), और create/regenerate पर **एक बार दिखाया जाता है**; फिर इसे कैप्चर करें। `--json` के साथ यह केवल `key` फ़ील्ड में दिखाई देता है। **नाम** द्वारा संदर्भित। ```bash agenteye keys list # active keys first, then revoked @@ -253,9 +253,9 @@ agenteye keys regenerate ci-bot --yes # rotate the secret (the ol agenteye keys disable ci-bot --yes # revoke ``` -अनुमतियाँ `(permission-set ∪ --add) − --remove` के रूप में काम करती हैं। टोकन `slug:action` (जैसे `events:read`) या एक संसाधन पर कई को विस्तारित करने के लिए `slug:action.action` (जैसे `events:read.add` → `events:read`, `events:add`)। पूर्वनिर्धारितें: `read-only`, `standard`, `admin`। मानव-केवल अनुमतियाँ (`keys:update`) किसी कुंजी को दी नहीं जा सकतीं। +अनुमतियाँ `(permission-set ∪ --add) − --remove` के रूप में काम करती हैं। टोकन `slug:action` (उदा. `events:read`) या `slug:action.action` हैं एक संसाधन पर कई विस्तारित करने के लिए (`events:read.add` → `events:read`, `events:add`)। प्रीसेट: `read-only`, `standard`, `admin`। मानव-केवल अनुमतियाँ (`keys:update`) एक कुंजी को दी नहीं जा सकती। -**`users`**: org सदस्य, **ईमेल** द्वारा संदर्भित (एक UUID id भी स्वीकार किया जाता है)। +**`users`**: ऑर्ग सदस्य, **ईमेल** द्वारा संदर्भित (एक UUID id भी स्वीकार किया जाता है)। ```bash agenteye users list [--active-only] @@ -274,7 +274,7 @@ agenteye settings schema # what each key accepts (ty agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: अलर्ट परिभाषा, **नाम** द्वारा संदर्भित। `create` एक स्थितीय NAME साथ फ़्लैग या `--file` के माध्यम से एक पूर्ण JSON बॉडी लेता है। +**`alerts`**: अलर्ट परिभाषाएँ, **नाम** द्वारा संदर्भित। `create` एक positional NAME साथ फ्लैग्स या `--file` के माध्यम से एक पूर्ण JSON बॉडी लेता है। ```bash agenteye alerts list @@ -285,7 +285,7 @@ agenteye alerts test high-errors --yes # fire a test noti agenteye alerts delete high-errors --yes ``` -**`incidents`**: अलर्ट घटनाएँ, id द्वारा संदर्भित (संक्षिप्त ids स्वीकार किए जाते हैं)। `show` पूर्ण गतिविधि लॉग प्रिंट करता है; कार्य करने से पहले इसे पढ़ें। +**`incidents`**: अलर्ट incidents, id द्वारा संदर्भित (short ids स्वीकार किए जाते हैं)। `show` पूर्ण activity log प्रिंट करता है; कार्य करने से पहले इसे पढ़ें। ```bash agenteye incidents list --state firing # also: acknowledged, resolved @@ -300,9 +300,9 @@ agenteye incidents comment-list ; agenteye incidents comment-delete ; agenteye incidents unsubscribe ; agenteye incidents subscribers ``` -### विश्लेषण और सहायक: `query` · `agent` +### एनालिटिक्स और असिस्टेंट: `query` · `agent` -**`query`**: अपने विश्लेषण स्टोर के विरुद्ध सहेजी गई SQL साथ एडहॉक रनर। सहेजी गई क्वेरी **नाम** द्वारा संदर्भित हैं; SQL सर्वर-साइड (SELECT/WITH केवल, विवरण टाइमआउट, पंक्ति कैप) सत्यापित है। +**`query`**: आपके एनालिटिक्स स्टोर के विरुद्ध saved SQL साथ ad-hoc रनर। Saved queries **नाम** द्वारा संदर्भित; SQL को सर्वर-side सत्यापित किया जाता है (SELECT/WITH केवल, statement टाइमआउट, पंक्ति cap)। ```bash agenteye query schema [TABLE] # column layout of the analytics views @@ -313,7 +313,7 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: बिल्ट-इन **AI सहायक** से बात करता है (वही केवल-पढ़ने वाले विश्लेषक जिससे आप डैशबोर्ड में चैट कर सकते हैं)। चैट एक छोटे chat-id द्वारा संदर्भित होते हैं (उपसर्ग-हल)। +**`agent`**: built-in **AI असिस्टेंट** से बात करता है (डैशबोर्ड में चैट कर सकते हैं वही read-only एनालिस्ट)। Chats को एक short chat-id द्वारा संदर्भित (prefix-resolved)। ```bash agenteye agent health # is the AI assistant configured/reachable @@ -326,25 +326,25 @@ agenteye agent rename --title "error triage" ; agenteye agent delete --- -## निकास कोड +## Exit codes | कोड | अर्थ | |---|---| | 0 | सफलता | -| 1 | अप्रत्याशित त्रुटि (जैसे डैशबोर्ड ने 5xx लौटाया) | -| 2 | उपयोग त्रुटि (अमान्य तर्क, अज्ञात कमांड/फ़्लैग, नाम टकराव) | -| 3 | डैशबोर्ड तक नहीं पहुँच सकता | -| 4 | लॉगिन में नहीं हैं या सेशन समाप्त हुआ; `agenteye login` चलाएँ | -| 5 | प्रमाणित, लेकिन आपके खाते में आवश्यक अनुमति नहीं है (संदेश इसका नाम देता है) | -| 6 | अनुरोधित संसाधन नहीं मिला (जैसे अज्ञात सेशन या घटना id) | +| 1 | अप्रत्याशित त्रुटि (उदा. डैशबोर्ड ने 5xx लौटाया) | +| 2 | उपयोग त्रुटि (अमान्य तर्कें, अज्ञात कमांड/फ्लैग, नाम टकराव) | +| 3 | डैशबोर्ड तक नहीं पहुँच सकते | +| 4 | लॉगिन में नहीं है या सेशन समाप्त हुआ; `agenteye login` चलाएँ | +| 5 | प्रमाणित, लेकिन आपके खाते में आवश्यक अनुमति की कमी है (संदेश इसे नाम देता है) | +| 6 | अनुरोधित संसाधन नहीं मिला (उदा. अज्ञात सेशन या incident id) | -ये CLI को स्क्रिप्ट के लिए सुरक्षित बनाते हैं: एक कोडिंग एजेंट एक `4` पर शाखा बना सकता है आपको फिर से प्रमाणित करने का संकेत देने के लिए, या एक `5` लापता अनुमति की सतह के लिए। CLI रेसिपी देखें [एजेंट के लिए](/hi/agenteye/cli-recipes) निकास-कोड-संभालने के पैटर्न और JSON आउटपुट आकार के लिए। +ये CLI को स्क्रिप्ट करने के लिए सुरक्षित बनाते हैं: एक कोडिंग एजेंट एक `4` पर अपने आप को फिर से प्रमाणित करने के लिए प्रेरित करने पर शाखा कर सकता है, या एक `5` पर missing अनुमति को सतह पर ला सकता है। [एजेंट के लिए CLI व्यंजन](/hi/agenteye/cli-recipes) में exit-code-handling पैटर्न और JSON आउटपुट आकार देखें। --- ## अगले कदम -- **[एजेंट के लिए CLI रेसिपी](/hi/agenteye/cli-recipes)**: कॉपी-पेस्ट क्वेरी पैटर्न, `jq` एक-लाइनर, `--fields` प्रक्षेपण, निकास-कोड संभालना, और JSON आउटपुट आकार, कोडिंग एजेंट के लिए लिखा हुआ CLI चला रहे हैं। -- **[CLI एजेंट कौशल](/hi/agenteye/cli-skill)**: इस CLI को स्थापन योग्य Claude Code / Codex *कौशल* के रूप में पैकेज करें ताकि एक कोडिंग एजेंट सादे-अंग्रेजी अनुरोध से Failproof AI Observability चला सके। -- **[API कुंजियाँ](/hi/agenteye/api-keys)**: `keys create --add …` के पीछे अनुमति मॉडल। -- **[AI सहायक](/hi/agenteye/assistant)**: सहायक को सक्षम करना जिससे `agent ask` बात करता है। \ No newline at end of file +- **[एजेंट के लिए CLI व्यंजन](/hi/agenteye/cli-recipes)**: copy-paste क्वेरी पैटर्न, `jq` one-liners, `--fields` projections, exit-code handling, और JSON आउटपुट आकार, कोडिंग एजेंट के लिए लिखे गए CLI चलाते हैं। +- **[CLI एजेंट कौशल](/hi/agenteye/cli-skill)**: इस CLI को एक installable Claude Code / Codex *skill* के रूप में पैकेज करें ताकि एक कोडिंग एजेंट plain-English अनुरोध से Failproof AI Observability चलाए। +- **[API कीज](/hi/agenteye/api-keys)**: `keys create --add …` के पीछे अनुमति मॉडल। +- **[AI असिस्टेंट](/hi/agenteye/assistant)**: असिस्टेंट सक्षम करना जिससे `agent ask` बात करता है। \ No newline at end of file diff --git a/docs/hi/agenteye/codex-capture.mdx b/docs/hi/agenteye/codex-capture.mdx index 575b58be..0fe48955 100644 --- a/docs/hi/agenteye/codex-capture.mdx +++ b/docs/hi/agenteye/codex-capture.mdx @@ -1,56 +1,56 @@ --- --- -title: "Codex सत्र कैप्चर" -description: "अपनी टीम के स्थानीय OpenAI Codex सत्रों को AgentEye में सामान्य सत्र और ईवेंट के रूप में कैप्चर करें — Codex चलाने के तरीके में कोई बदलाव नहीं।" +title: "Codex session capture" +description: "अपनी टीम के स्थानीय OpenAI Codex सत्रों को AgentEye में सामान्य सत्र और इवेंट्स के रूप में कैप्चर करें — Codex चलाने के तरीके में कोई बदलाव किए बिना।" --- -आपके इंजीनियर पहले से ही हर दिन OpenAI Codex चलाते हैं। Codex सत्र कैप्चर उन कोडिंग सत्रों को AgentEye में सामान्य सत्र और ईवेंट के रूप में लाता है, ताकि आप उन्हें खोज सकें, दोबारा चला सकें, और आप जो अन्य सब कुछ देखते हैं उसके साथ उनका मूल्यांकन कर सकें। यह [Python SDK](/hi/agenteye/python-sdk) को पूरक करता है: SDK आपके द्वारा लिखे गए एजेंटों को प्रस्तुत करता है, जबकि यह आपकी टीम द्वारा पहले से किए जा रहे Codex कार्य को कैप्चर करता है — इसे चलाने के तरीके में कोई बदलाव नहीं। +आपके इंजीनियर पहले से ही हर दिन OpenAI Codex चलाते हैं। Codex session capture उन कोडिंग सत्रों को AgentEye में सामान्य सत्र और इवेंट्स के रूप में लाता है, इसलिए आप उन्हें खोज सकते हैं, दोबारा चला सकते हैं, और मूल्यांकन कर सकते हैं — साथ ही सब कुछ जो आप अवलोकन करते हैं। यह [Python SDK](/hi/agenteye/python-sdk) को पूरक करता है: SDK उन एजेंट्स को instrumentation करता है जो आप लिखते हैं, जबकि यह उस Codex काम को कैप्चर करता है जो आपकी टीम पहले से ही करती है — इसे चलाने के तरीके में कोई बदलाव किए बिना। -एक छोटा बैकग्राउंड कलेक्टर Codex के स्थानीय सत्र प्रतिलेखन को पढ़ता है क्योंकि वे लिखे जाते हैं और उन्हें AgentEye को भेजता है। एक मशीन प्रति कलेक्टर एक बार में हर स्थानीय Codex सतह को कैप्चर करता है — प्रति-सतह सेटअप की कोई आवश्यकता नहीं है। +एक छोटा background collector Codex के स्थानीय सत्र transcripts को पढ़ता है जैसे वे लिखे जाते हैं और उन्हें AgentEye में भेजता है। एक मशीन प्रति collector हर स्थानीय Codex सतह को एक साथ कैप्चर करता है — कोई per-surface सेटअप नहीं है। -एक ही कलेक्टर अन्य एजेंटों को भी कैप्चर करता है — [OpenClaw](/hi/agenteye/openclaw-capture) और [Hermes](/hi/agenteye/hermes-capture) देखें। आप जो भी चलाते हैं उसे सक्षम करें; एक एकल कलेक्टर एक साथ कई को कैप्चर कर सकता है। +एक ही collector अन्य एजेंट्स को भी कैप्चर करता है — [OpenClaw](/hi/agenteye/openclaw-capture) और [Hermes](/hi/agenteye/hermes-capture) देखें। जो भी चलाते हैं उसे सक्षम करें; एक single collector एक साथ कई को कैप्चर कर सकता है। --- ## यह क्या कैप्चर करता है -हर Codex सतह जो **स्थानीय रूप से** चलती है, डिस्क पर समान सत्र प्रतिलेखन तैयार करती है, और कलेक्टर उन सभी को उठाता है: +हर Codex सतह जो **स्थानीय रूप से** चलती है, एक ही on-disk सत्र transcripts बनाती है, और collector उन सभी को उठाता है: - Codex **CLI** और `codex exec` -- **VS Code / IDE एक्सटेंशन** -- **डेस्कटॉप ऐप**, जब यह स्थानीय रूप से एक सत्र चलाता है +- **VS Code / IDE extension** +- **desktop app**, जब यह स्थानीय रूप से एक सत्र चलाता है -प्रत्येक Codex सत्र AgentEye [सत्र](/hi/agenteye/sessions) बन जाता है; इसके उपयोगकर्ता और सहायक संदेश, तर्क, उपकरण कॉल, उपकरण परिणाम, और टोकन उपयोग मिलान करने वाले [ईवेंट](/hi/agenteye/event-stream) बन जाते हैं। जिस सतह से प्रत्येक सत्र आया था (CLI, IDE, या डेस्कटॉप) रिकॉर्ड किया जाता है, ताकि आप उन्हें अलग बता सकें। +प्रत्येक Codex सत्र एक AgentEye [session](/hi/agenteye/sessions) बन जाता है; इसके user और assistant संदेश, reasoning, tool calls, tool results, और token usage संबंधित [events](/hi/agenteye/event-stream) बन जाते हैं। वह सतह जहां से प्रत्येक सत्र आया है (CLI, IDE, या desktop), रिकॉर्ड किया जाता है, इसलिए आप उन्हें अलग बता सकते हैं। -> **क्लाउड सत्र कैप्चर नहीं किए जाते हैं।** डेस्कटॉप ऐप तेजी से Codex क्लाउड में सत्र चलाता है और मशीन पर केवल उनके मेटाडेटा को रखता है — पढ़ने के लिए कोई स्थानीय प्रतिलेखन नहीं है। केवल स्थानीय रूप से निष्पादित सत्र कैप्चर किए जाते हैं। +> **क्लाउड सत्र कैप्चर नहीं किए जाते।** Desktop app तेजी से Codex cloud में सत्र चलाता है और मशीन पर केवल उनके metadata रखता है — पढ़ने के लिए कोई स्थानीय transcript नहीं है। केवल स्थानीय रूप से निष्पादित सत्र कैप्चर किए जाते हैं। --- ## इसे चालू करें -कैप्चर तब तक बंद रहता है जब तक आप इसे सक्षम न करें। `events:add` अनुमति वाली API कुंजी के साथ कलेक्टर को इंस्टॉल करें ([API कुंजियां](/hi/agenteye/api-keys) देखें), और Codex कैप्चर को चालू करें: +Capture तब तक बंद रहता है जब तक आप इसे सक्षम नहीं करते। Collector को एक API key के साथ इंस्टॉल करें जिसके पास `events:add` अनुमति है ([API keys](/hi/agenteye/api-keys) देखें), और Codex capture चालू करें: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -यह कलेक्टर को इंस्टॉल करता है, इसे एक बैकग्राउंड सेवा के रूप में पंजीकृत करता है, और कैप्चर करना शुरू करता है। पुष्टि करें कि यह चल रहा है: +यह collector को इंस्टॉल करता है, इसे एक background service के रूप में पंजीकृत करता है, और कैप्चरिंग शुरू करता है। पुष्टि करें कि यह चल रहा है: ```bash agenteye-collector health ``` -पहली बार चलने पर, आपके मौजूदा Codex सत्रों को एक बार भर दिया जाता है और नई गतिविधि फिर सेकंड के भीतर स्ट्रीम होती है। Codex की अपनी फाइलें केवल पढ़ी जाती हैं — कभी भी संशोधित, स्थानांतरित, या हटाई नहीं जाती — और प्रत्येक सत्र बिल्कुल एक बार भेजा जाता है, यहां तक कि पुनरारंभ भी। +पहली बार चलाने पर, आपके मौजूदा Codex सत्र एक बार backfill किए जाते हैं और नई activity फिर कुछ सेकंड में स्ट्रीम करती है। Codex की खुद की फाइलें केवल पढ़ी जाती हैं — कभी संशोधित, स्थानांतरित, या हटाई नहीं जाती हैं — और प्रत्येक सत्र बिल्कुल एक बार भेजा जाता है, यहां तक कि restarts के पार भी। --- -## यह कहाँ दिखाई देता है +## यह कहां दिखाई देता है -कैप्चर किए गए सत्र **सत्र** में दिखाई देते हैं, और उनके ईवेंट **ईवेंट** स्ट्रीम में, किसी अन्य एजेंट की तरह ही जिसे आप देखते हैं — इसलिए [सत्र पुनरावृत्ति](/hi/agenteye/sessions), [खोज](/hi/agenteye/queries), [मूल्यांकन](/hi/agenteye/evaluations), और [सतर्कताएं](/hi/agenteye/alerts) सभी उन पर काम करती हैं। Codex एजेंट के अनुसार फ़िल्टर करें उन्हें अपने आप से देखने के लिए। +कैप्चर किए गए सत्र **Sessions** में दिखाई देते हैं, और उनके events **Events** stream में, ठीक उसी तरह जैसे कोई अन्य agent जिसे आप अवलोकन करते हैं — तो [session replay](/hi/agenteye/sessions), [search](/hi/agenteye/queries), [evaluations](/hi/agenteye/evaluations), और [alerts](/hi/agenteye/alerts) सभी इन पर काम करते हैं। Codex agent के द्वारा फ़िल्टर करें उन्हें अपने आप पर देखने के लिए। --- ## गोपनीयता -Codex प्रतिलेखन में पूरा सत्र होता है — कमांड आउटपुट, फाइल सामग्री, और कुछ भी Codex ने पढ़ा या लिखा सहित — और इसमें रहस्य हो सकते हैं। कैप्चर किए गए सत्र यथावत भेजे जाते हैं, इसलिए केवल उन मशीनों और टीमों पर कैप्चर सक्षम करें जहां उस सामग्री को AgentEye में केंद्रीकृत करना उपयुक्त है, और कलेक्टर को केवल `events:add` के लिए सीमित एक कुंजी दें। [सुरक्षा](/hi/agenteye/security) देखें कि आपके डेटा को कैसे अलग रखा जाता है। \ No newline at end of file +Codex transcripts में पूरा सत्र होता है — command output, file contents, और कुछ भी जो Codex ने पढ़ा या लिखा सहित — और secrets रख सकते हैं। कैप्चर किए गए सत्र जैसे-हैं भेजे जाते हैं, इसलिए केवल उन मशीनों और टीमों पर capture सक्षम करें जहां उस content को AgentEye में centralize करना उपयुक्त है, और collector को एक key दें जो केवल `events:add` तक scoped हो। [Security](/hi/agenteye/security) देखें कि आपके data को कैसे अलग रखा जाता है। \ No newline at end of file diff --git a/docs/hi/agenteye/concepts.mdx b/docs/hi/agenteye/concepts.mdx index 88bc9b89..a2424c2d 100644 --- a/docs/hi/agenteye/concepts.mdx +++ b/docs/hi/agenteye/concepts.mdx @@ -1,83 +1,83 @@ --- title: "अवधारणाएं" -description: "Failproof AI Observability के पीछे की शब्दावली — events, sessions, evaluations, audits, findings, और incidents — एक जगह परिभाषित।" +description: "Failproof AI Observability की शब्दावली — events, sessions, evaluations, audits, findings, और incidents — एक ही जगह परिभाषित।" --- -यह पेज Failproof AI Observability द्वारा उपयोग की जाने वाली शब्दावली को परिभाषित करता है। यदि किसी अन्य गाइड में कोई शब्द अपरिचित है, तो यह यहाँ परिभाषित है। आपको इसे अंत तक पढ़ने की आवश्यकता नहीं है: इसे स्किम करें, या जब आप कोई शब्द स्पष्ट करना चाहते हैं तो वापस जाएं। +यह पृष्ठ उन शब्दों को परिभाषित करता है जिनका उपयोग Failproof AI Observability करता है। यदि किसी अन्य गाइड में कोई शब्द अपरिचित है, तो वह यहाँ परिभाषित है। आपको इसे शुरू से अंत तक पढ़ने की आवश्यकता नहीं है: इसे स्कैन करें, या जब आप कोई ऐसा शब्द देखें जिसे आप स्पष्ट करना चाहते हैं तो वापस आएं। --- ## डेटा मॉडल **Event** -डेटा की सबसे छोटी इकाई। एक event आपके agent द्वारा उठाया गया एक एकल कदम रिकॉर्ड करता है: एक `tool_use`, एक `model_request`, एक `hook_completed`, एक `error`, और इसी तरह। आपका agent [Python SDK](/hi/agenteye/python-sdk) के माध्यम से events को emit करता है; वे **Events** पेज पर लाइव दिखाई देते हैं। +डेटा की सबसे छोटी इकाई। एक event आपके agent द्वारा उठाया गया एक एकल कदम रिकॉर्ड करता है: एक `tool_use`, एक `model_request`, एक `hook_completed`, एक `error`, आदि। आपका agent [Python SDK](/hi/agenteye/python-sdk) के माध्यम से events emit करता है; वे **Events** पृष्ठ पर लाइव दिखाई देते हैं। **Session** -एक agent run, जिसे एक `session_id` द्वारा चिन्हित किया जाता है। एक session वह सभी events हैं जो उस id को साझा करते हैं, **Sessions** पेज पर एक एकल row में rolled up हैं और इसके detail page पर एक execution graph के रूप में खींचे गए हैं। एक session आमतौर पर `agent_start` से शुरू होता है और `agent_end` के साथ समाप्त होता है। +एक agent run, जिसे `session_id` द्वारा चिन्हित किया जाता है। एक session सभी events हैं जो उस id को साझा करते हैं, **Sessions** पृष्ठ पर एक एकल पंक्ति में रोल किए गए हैं और इसके विवरण पृष्ठ पर एक execution ग्राफ के रूप में खींचे गए हैं। एक session आमतौर पर `agent_start` से शुरू होता है और `agent_end` पर समाप्त होता है। **Agent** -एक run के अंदर एक नामित actor, जिसे एक `agent_id` द्वारा चिन्हित किया जाता है। एक run में कई agents शामिल हो सकते हैं: एक planner जो एक summarizer sub-agent को spawn करता है, उदाहरण के लिए। Sub-agents एक `parent_id` रखते हैं, जो Failproof AI Observability को execution graph में उन्हें अपनी lanes पर खींचने देता है। +एक run के अंदर एक नामित अभिनेता, जिसे `agent_id` द्वारा चिन्हित किया जाता है। एक run में कई agents शामिल हो सकते हैं: उदाहरण के लिए, एक planner जो एक summarizer sub-agent को spawn करता है। Sub-agents में एक `parent_id` होता है, जो Failproof AI Observability को execution ग्राफ में उन्हें अपनी-अपनी lanes पर खींचने देता है। **Environment** -एक label जहाँ run हुआ: `production`, `staging`, `dev`। आप इसे SDK कॉन्फ़िगर करते समय एक बार सेट करते हैं। लगभग हर dashboard पेज environment के द्वारा फ़िल्टर कर सकता है। +एक label जो बताता है कि run कहाँ हुआ: `production`, `staging`, `dev`। आप इसे SDK कॉन्फ़िगर करते समय एक बार सेट करते हैं। लगभग हर dashboard पृष्ठ environment द्वारा filter कर सकते हैं। **Context-window fill** -एक model के context window का वह प्रतिशत जो एक response ने consume किया। Failproof AI Observability इसे उन models के लिए `model_response` events पर stamp करता है जिन्हें यह पहचानता है, इसलिए prompt growth और impending compaction event stream में सही दिखाई देते हैं। +एक model की context window का प्रतिशत जो एक response ने उपभोग किया। Failproof AI Observability इसे `model_response` events पर stamp करता है उन models के लिए जिन्हें यह पहचानता है, इसलिए prompt growth और आसन्न compaction event stream में सही दिखाई देते हैं। --- -## गुणवत्ता +## Quality **Evaluation** -एक finished session के लिए एक गुणवत्ता score, जो आप चलाने वाली एक scoring service द्वारा produced। Evaluations opt-in हैं: जब तक आप एक evaluator को connect नहीं करते, sessions रिकॉर्ड किए जाते हैं लेकिन scored नहीं होते। प्रत्येक evaluation कई named scores ले सकता है (उदाहरण के लिए `helpfulness`, `factuality`, `tool_efficiency`), प्रत्येक एक संक्षिप्त reasoning note के साथ। [Evaluation suite](/hi/agenteye/evaluation-suite) देखें। +एक समाप्त session के लिए quality score, जो एक scoring service द्वारा produced होता है जिसे आप चलाते हैं। Evaluations opt-in हैं: जब तक आप किसी evaluator को कनेक्ट नहीं करते, sessions recorded होते हैं लेकिन scored नहीं होते। प्रत्येक evaluation कई named scores ले सकता है (उदाहरण के लिए `helpfulness`, `factuality`, `tool_efficiency`), प्रत्येक के साथ एक संक्षिप्त reasoning note। [Evaluation suite](/hi/agenteye/evaluation-suite) देखें। **Score key** -एक dimension का नाम जो एक evaluator रिपोर्ट करता है, जैसे `helpfulness`। Alerts और audits समय के साथ एक specific score key को देख सकते हैं। +एक evaluator द्वारा reported किए गए एक dimension का नाम, जैसे `helpfulness`। Alerts और audits समय के साथ किसी विशिष्ट score key को देख सकते हैं। **Evaluator** -आपकी scoring service। Failproof AI Observability एक finished run का transcript उसे POST करता है और यह जो scores return करता है उन्हें store करता है। यह एक default evaluator ship नहीं करता है; scoring logic आपका है। +आपकी scoring service। Failproof AI Observability एक समाप्त run के transcript को इसे POST करता है और यह जो scores return करता है उन्हें store करता है। यह कोई default evaluator ship नहीं करता; scoring logic आपकी है। --- -## failures को खोजना और fix करना +## Failures को खोजना और ठीक करना **Hook** -एक guardrail या side-effect जो आपका agent framework एक step के चारों ओर चलाता है: एक content-safety check, PII redaction, एक budget guard। Hooks `hook_triggered` / `hook_completed` events को एक `outcome` (allow, deny, modify) के साथ emit करते हैं, और अपना स्वयं का observe page प्राप्त करते हैं। +एक guardrail या side-effect जो आपका agent framework एक कदम के चारों ओर चलाता है: एक content-safety check, PII redaction, एक budget guard। Hooks `hook_triggered` / `hook_completed` events emit करते हैं एक `outcome` (allow, deny, modify) के साथ, और अपना observe page प्राप्त करते हैं। **Alert rule** -एक rule जो तब fires जब एक metric आपके द्वारा सेट की गई threshold को cross करता है: error rate, p95 latency, token cost, या एक evaluator score। जब एक rule fires, यह एक incident खोलता है और आपके चुने हुए channels (email, Slack, webhook, in-dashboard) को notify करता है। [Alerts](/hi/agenteye/alerts) देखें। +एक rule जो तब fire होता है जब कोई metric threshold को cross करता है जो आप सेट करते हैं: error rate, p95 latency, token cost, या एक evaluator score। जब कोई rule fire होता है, तो यह एक incident खोलता है और आपके चुने हुए channels (email, Slack, webhook, in-dashboard) को notify करता है। [Alerts](/hi/agenteye/alerts) देखें। **Incident** -एक open issue जो तब created होता है जब एक alert rule fires। Incidents के पास एक lifecycle (acknowledge, assign, resolve) है और एक activity timeline है जो हर action को रिकॉर्ड करता है। आप एक को manually भी खोल सकते हैं। +एक open issue जो तब created होता है जब कोई alert rule fire होता है। Incidents का एक lifecycle (acknowledge, assign, resolve) है और एक activity timeline है जो हर action को record करती है। आप इसे manually भी खोल सकते हैं। **Audit** -एक recurring investigation (hourly to weekly) जो आपके logs को *across* sessions में mine करता है failure patterns के लिए जिनके लिए आपने एक rule नहीं लिखा है: error clusters, low scores, latency outliers, tool-call loops, और runs जो कभी finished नहीं हुए। जहाँ एक alert एक metric को देखता है जिसके बारे में आप पहले से जानते हैं, एक audit आपको बताता है कि आगे क्या देखना है। [Audits](/hi/agenteye/audits) देखें। +एक recurring investigation (hourly to weekly) जो आपके logs को *across* sessions में mine करता है उन failure patterns के लिए जिन्हें आपने rule नहीं लिखा है: error clusters, low scores, latency outliers, tool-call loops, और runs जो कभी finished नहीं हुए। जहाँ एक alert एक metric को देखता है जिसके बारे में आप पहले से जानते हैं, एक audit आपको बताता है कि आगे क्या देखना है। [Audits](/hi/agenteye/audits) देखें। **Finding** -एक audit run से एक ranked, evidence-backed result। एक finding एक pattern का नाम देता है, इसके पीछे के exact sessions को link करता है, और एक triage lifecycle (acknowledge, resolve, mute, dismiss) रखता है। Failproof AI Observability findings को run-over-run deduplicate करता है इसलिए एक known pattern update होता है बजाय इसके कि pile up हो। +एक audit run से एक ranked, evidence-backed result। एक finding एक pattern का नाम देता है, इसके पीछे के exact sessions को link करता है, और एक triage lifecycle (acknowledge, resolve, mute, dismiss) ले जाता है। Failproof AI Observability findings को run-over-run deduplicate करता है इसलिए एक known pattern update होता है बजाय इसके कि pile up हो। -**The AI assistant** -in-dashboard chat जो आपके agents के बारे में plain English में, आपके स्वयं के data के ऊपर सवालों के जवाब देता है। यह default रूप से read-only है; कुछ भी जो यह create करता है (एक saved query, एक dashboard) approval-gated है, और यह कभी delete नहीं कर सकता। [AI assistant](/hi/agenteye/assistant) देखें। +**AI assistant** +In-dashboard chat जो आपके agents के बारे में plain English में सवालों का जवाब देता है, आपके अपने data पर। यह default रूप से read-only है; कुछ भी जो यह create करता है (एक saved query, एक dashboard) approval-gated है, और यह कभी delete नहीं कर सकता। [AI assistant](/hi/agenteye/assistant) देखें। --- ## इसे चलाना **Organization (tenant)** -एक isolated workspace। एक Failproof AI Observability instance कई organizations को host कर सकता है, प्रत्येक के साथ अपने स्वयं के users, keys, और data। हर dashboard URL आपके org slug (`//…`) के अंतर्गत scoped है। +एक isolated workspace। एक Failproof AI Observability instance कई organizations को host कर सकता है, प्रत्येक के अपने users, keys, और data के साथ। हर dashboard URL आपके org slug (`//…`) के तहत scoped है। **Collector** -`agenteye-collector`, lightweight daemon जो प्रत्येक agent machine पर runs करता है, SDK द्वारा disk में लिखे गए events को batch करता है, और उन्हें server को ship करता है। +`agenteye-collector`, lightweight daemon जो प्रत्येक agent machine पर चलता है, events को batch करता है जो SDK disk पर लिखता है, और उन्हें server को भेजता है। **API key** -एक scoped token जो एक client को server के साथ authenticate करता है। Keys में granular permissions होते हैं (उदाहरण के लिए `events:add` collector के लिए, read-only scopes एक dashboard key के लिए)। [API keys](/hi/agenteye/api-keys) देखें। +एक scoped token जो एक client को server के विरुद्ध authenticate करता है। Keys में granular permissions होते हैं (उदाहरण के लिए collector के लिए `events:add`, dashboard key के लिए read-only scopes)। [API keys](/hi/agenteye/api-keys) देखें। **Server** -ingest और API service। यह events को ingest करता है, operational state को आपके databases में store करता है, और dashboard और CLI को serve करता है। +Ingest और API service। यह events को ingest करता है, operational state को आपके databases में store करता है, और dashboard और CLI को serve करता है। **Dashboard** -web UI। हर page एक organization के लिए scoped है और server के API के माध्यम से पढ़ता है। +Web UI। हर page एक organization के लिए scoped है और server के API के माध्यम से पढ़ता है। --- diff --git a/docs/hi/agenteye/dashboards.mdx b/docs/hi/agenteye/dashboards.mdx index b06f4446..43637bf3 100644 --- a/docs/hi/agenteye/dashboards.mdx +++ b/docs/hi/agenteye/dashboards.mdx @@ -1,47 +1,46 @@ --- ---- title: "डैशबोर्ड" description: "अपने लाइव एजेंट डेटा को एक साझा चित्र में बदलें जिसे आपकी पूरी टीम देखती है।" --- -अपने लाइव एजेंट डेटा को एक साझा चित्र में बदलें जिसे आपकी पूरी टीम देखती है। जो क्वेरीज़ महत्वपूर्ण हैं उन्हें चार्ट के रूप में पिन करें, और हर कोई एक नज़र में एक जैसे नंबर देखता है, बिना एक भी क्वेरी को फिर से चलाए। +अपने लाइव एजेंट डेटा को एक साझा चित्र में बदलें जिसे आपकी पूरी टीम देखती है। उन क्वेरीज़ को चार्ट के रूप में पिन करें जो मायने रखती हैं, और हर कोई एक ही डेटा को एक नज़र में देख सकता है, बिना कोई भी क्वेरी फिर से चलाए। -![एक डैशबोर्ड सहेजी गई क्वेरीज़ से बना है: एक घंटे में ईवेंट्स की लाइन, प्रकार के अनुसार त्रुटियों की बार, लेटेंसी एरिया चार्ट, और मॉडल के अनुसार टोकन](/agenteye/images/dashboard-fleet.png) +![सहेजी गई क्वेरीज़ से बनाया गया डैशबोर्ड: एक इवेंट्स-प्रति-घंटा लाइन, त्रुटियों-द्वारा-प्रकार बार, एक लेटेंसी एरिया चार्ट, और टोकन्स-द्वारा-मॉडल](/agenteye/images/dashboard-fleet.png) -*एक बोर्ड, चार सहेजी गई क्वेरीज़: प्रति घंटा ईवेंट्स, प्रकार के अनुसार त्रुटियां, लेटेंसी, और मॉडल के अनुसार टोकन।* +*एक बोर्ड, चार सहेजी गई क्वेरीज़: प्रति घंटा इवेंट्स, प्रकार के अनुसार त्रुटियां, लेटेंसी, और मॉडल के अनुसार टोकन्स।* -## हर कोई एक ही सच देखता है +## सभी को एक ही सच दिखता है -चैट में स्क्रीनशॉट पेस्ट करना बंद करें और एक ही क्वेरी को दिन में पांच बार चलाना बंद करें। एक डैशबोर्ड एक साझा, संगठन-व्यापी बोर्ड है जिसे आपकी टीम का कोई भी सदस्य खोलकर बिल्कुल एक जैसा दृश्य देख सकता है। जब अंतर्निहित डेटा बदलता है, चार्ट भी बदल जाते हैं, इसलिए बोर्ड हमेशा वर्तमान रहता है और कोई भी पुरानी संख्याओं पर बहस नहीं करता। +चैट में स्क्रीनशॉट पेस्ट करना बंद करें और दिन में पांच बार एक ही क्वेरी को फिर से चलाना बंद करें। एक डैशबोर्ड एक साझा, संगठन-व्यापी बोर्ड है जिसे आपकी टीम का कोई भी सदस्य बिल्कुल एक ही दृश्य के लिए खोल सकता है। जब अंतर्निहित डेटा बदलता है, तो चार्ट भी इसके साथ चलते हैं, इसलिए बोर्ड हमेशा वर्तमान रहता है और कोई भी पुरानी संख्याओं पर बहस नहीं करता। -ऊपर दिया गया फ़्लीट डैशबोर्ड दिन-प्रतिदिन के संचालन के लिए एक अच्छा शुरुआती आकार है: +ऊपर दिया गया फ्लीट डैशबोर्ड दिन-प्रतिदिन के संचालन के लिए एक अच्छा शुरुआती आकार है: -- एक **events-per-hour** लाइन, ताकि आप थ्रूपुट देख सकें और अचानक गिरावट को पकड़ सकें -- एक **errors-by-type** बार, ताकि आपकी सबसे बड़ी विफलता की श्रेणियां सामने आ जाएं -- एक **latency** एरिया चार्ट, ताकि धीमापन उपयोगकर्ताओं की शिकायत से पहले दिखाई दे -- एक **tokens-by-model** विभाजन, ताकि लागत नज़र में रहे +- एक **events-per-hour** लाइन, ताकि आप थ्रूपुट देख सकें और अचानक गिरावट पकड़ सकें +- एक **errors-by-type** बार, ताकि आपकी सबसे बड़ी विफलता श्रेणियां नज़र आएं +- एक **latency** एरिया चार्ट, ताकि धीमा होना उपयोगकर्ताओं की शिकायत से पहले दिखे +- एक **tokens-by-model** ब्रेकडाउन, ताकि लागत नज़र में रहे आप अपने बोर्ड `//dashboards` पर पाएंगे। -## उन क्वेरीज़ को पिन करें जिन्हें आपने पहले से सहेज रखा है +## वे क्वेरीज़ पिन करें जिन्हें आप पहले ही सहेज चुके हैं -प्रत्येक टाइल एक सहेजी गई क्वेरी से शुरू होता है। उस क्वेरी को बनाएं और सहेजें जिसकी आपको परवाह है [Queries](/hi/agenteye/queries) लाइब्रेरी में (निर्मित प्रीसेट्स प्लस आपकी अपनी, आपके ईवेंट्स और मूल्यांकन के ऊपर), फिर इसे डैशबोर्ड पर उस चार्ट के रूप में पिन करें जो डेटा के अनुरूप हो: एक **line** समय के साथ ट्रेंड्स के लिए, एक **bar** श्रेणियों की तुलना के लिए, एक **area** वॉल्यूम के लिए, या एक **pie** शेयर विभाजन के लिए। +हर टाइल एक सहेजी गई क्वेरी से शुरू होता है। [Queries](/hi/agenteye/queries) लाइब्रेरी में जिस क्वेरी की परवाह करते हैं उसे बनाएं और सहेजें (बिल्ट-इन प्रीसेट्स प्लस आपकी स्वयं की, आपके इवेंट्स और मूल्यांकन पर), फिर इसे एक चार्ट के रूप में डैशबोर्ड में पिन करें जो डेटा के लिए उपयुक्त हो: समय के साथ रुझानों के लिए एक **line**, श्रेणियों की तुलना के लिए एक **bar**, वॉल्यूम के लिए एक **area**, या शेयर ब्रेकडाउन के लिए एक **pie**। -क्योंकि एक टाइल केवल आपकी सहेजी गई क्वेरी है जिसे चार्ट के रूप में प्रदर्शित किया गया है, हाथ से सिंक रखने के लिए कुछ भी नहीं है। क्वेरी को एक बार अपडेट करें और हर डैशबोर्ड जो इसका उपयोग करता है वह भी अपडेट हो जाता है। +चूंकि एक टाइल सिर्फ आपकी सहेजी गई क्वेरी को एक चार्ट के रूप में प्रस्तुत किया जाता है, इसलिए हाथ से सिंक रखने के लिए कुछ भी नहीं है। क्वेरी को एक बार अपडेट करें और हर डैशबोर्ड जो इसका उपयोग करता है वह भी अपडेट हो जाता है। ## वॉल्यूम नहीं, गुणवत्ता देखें -वॉल्यूम आपको बताता है कि एजेंट व्यस्त हैं। गुणवत्ता आपको बताती है कि वे वास्तव में काम कर रहे हैं। अपने डैशबोर्ड को अपने [evaluation scores](/hi/agenteye/evaluations) की ओर इशारा करें और आपको एक बोर्ड मिलता है जो समय के साथ ट्रैक करता है कि रन कितनी अच्छी तरह चल रहे हैं, इसलिए गुणवत्ता में गिरावट एक चार्ट पर एक डिप के रूप में दिखाई देती है, न कि ग्राहक से एक आश्चर्य के रूप में। +वॉल्यूम आपको बताता है कि एजेंट्स व्यस्त हैं। गुणवत्ता आपको बताती है कि वे वास्तव में काम कर रहे हैं। अपने [evaluation scores](/hi/agenteye/evaluations) की ओर एक डैशबोर्ड इंगित करें और आप एक बोर्ड पाते हैं जो समय के साथ रन कितनी अच्छी तरह चल रहे हैं इसका ट्रैक रखता है, इसलिए गुणवत्ता में गिरावट ग्राहक की आश्चर्य के बजाय चार्ट पर एक गिरावट के रूप में दिखाई देती है। -![सहेजी गई मूल्यांकन क्वेरीज़ से बना एक गुणवत्ता-केंद्रित डैशबोर्ड](/agenteye/images/dashboard-quality.png) +![सहेजी गई मूल्यांकन क्वेरीज़ से बनाया गया गुणवत्ता-केंद्रित डैशबोर्ड](/agenteye/images/dashboard-quality.png) -*एक गुणवत्ता बोर्ड आपके मूल्यांकन स्कोर को सामने और केंद्र में रखता है, संचालन संख्याओं के ठीक बगल में।* +*एक गुणवत्ता बोर्ड आपके मूल्यांकन स्कोर को सामने और केंद्र में रखता है, बिल्कुल संचालन संख्याओं के बगल में।* -एक संचालन बोर्ड और एक गुणवत्ता बोर्ड को एक साथ रखें और आपकी टीम के पास दोनों सवालों का जवाब देने के लिए एक जगह है "क्या यह काम कर रहा है?" और "क्या यह अच्छा है?", बिना किसी के एक क्वेरी को फिर से चलाए। +एक ऑपरेशन बोर्ड और एक गुणवत्ता बोर्ड को एक साथ रखें और आपकी टीम के पास दोनों "क्या यह काम कर रहा है?" और "क्या यह अच्छा है?" का उत्तर देने के लिए एक ही जगह है, बिना किसी के क्वेरी को फिर से चलाए। ## संबंधित -- [Queries](/hi/agenteye/queries): उन क्वेरीज़ को बनाएं और सहेजें जो आपके टाइल्स बन जाती हैं। -- [Evaluations](/hi/agenteye/evaluations): अपने रन को स्कोर करें ताकि आप समय के साथ गुणवत्ता को चार्ट कर सकें। -- [Alerts](/hi/agenteye/alerts): इन मेट्रिक्स में से किसी भी थ्रेसहोल्ड को एक पेज में बदलें। \ No newline at end of file +- [Queries](/hi/agenteye/queries): वे क्वेरीज़ बनाएं और सहेजें जो आपके टाइल्स बनती हैं। +- [Evaluations](/hi/agenteye/evaluations): अपने रन को स्कोर करें ताकि आप समय के साथ गुणवत्ता चार्ट कर सकें। +- [Alerts](/hi/agenteye/alerts): इन मेट्रिक्स में से किसी पर भी एक थ्रेसहोल्ड को एक पेज में बदलें। \ No newline at end of file diff --git a/docs/hi/agenteye/error-tracking.mdx b/docs/hi/agenteye/error-tracking.mdx index 36adc98e..d99a9577 100644 --- a/docs/hi/agenteye/error-tracking.mdx +++ b/docs/hi/agenteye/error-tracking.mdx @@ -1,42 +1,41 @@ --- ---- title: "त्रुटि ट्रैकिंग" -description: "अपने एजेंटों द्वारा उत्पन्न सभी विफलताओं को एक जगह देखें, समूहित ताकि शोर भरा विस्फोट एक एकल समस्या के रूप में दिखे।" +description: "अपने एजेंटों द्वारा होने वाली प्रत्येक विफलता को एक ही जगह देखें, समूहित करें ताकि शोरगुल वाला फटना एक समस्या के रूप में दिखे।" --- -अपने एजेंटों द्वारा उत्पन्न सभी विफलताओं को एक जगह देखें, समूहित ताकि शोर भरा विस्फोट एक एकल समस्या के रूप में दिखे। आपको "कुछ लाल है" से लेकर उस सटीक रन तक एक-क्लिक पथ मिलता है जो टूटा है, लाइव फीड को स्क्रॉल किए बिना। +अपने एजेंटों द्वारा होने वाली प्रत्येक विफलता को एक ही जगह देखें, समूहित करें ताकि शोरगुल वाला फटना एक समस्या के रूप में दिखे। आपको "कुछ लाल है" से लेकर सटीक रन तक का एक-क्लिक पथ मिलता है जो टूट गया है, बिना लाइव फीड को स्क्रॉल किए। -![Errors पृष्ठ: समय के साथ विफलताओं का एक हिस्टोग्राम ऊपर समूहित लाल त्रुटि पंक्तियों के साथ, प्रत्येक में एक-क्लिक "+ alert" बटन है](/agenteye/images/errors.png) -*Errors पृष्ठ: समय के साथ विफलताओं का हिस्टोग्राम, दोहराई गई विफलताओं को प्रति घटना एक पंक्ति में संपीड़ित किया गया है।* +![त्रुटि पृष्ठ: समय के साथ विफलताओं का एक हिस्टोग्राम ऊपर समूहित लाल त्रुटि पंक्तियों के साथ, प्रत्येक में एक-क्लिक "+ सतर्कता" बटन](/agenteye/images/errors.png) +*त्रुटि पृष्ठ: समय के साथ विफलताओं का हिस्टोग्राम, दोहराई गई विफलताओं को प्रति घटना एक पंक्ति में संक्षिप्त किया गया।* -## हर विफलता, पहले से ही आपके लिए एकत्र की गई +## प्रत्येक विफलता, पहले से ही आपके लिए एकत्रित -जब कोई एजेंट विफल होता है, तो आपको यह आशा नहीं करनी चाहिए कि एक लाइव इवेंट स्ट्रीम को स्क्रॉल करें और लाल पंक्तियों को देखते रहें। **Errors** पृष्ठ आपके लिए एकत्रण करता है। यह डैशबोर्ड को लाल रंग में दिखाए जाने वाली सभी चीजों को एक ट्रिएज सतह में लाता है, ताकि आप जो पहली चीज देखें वह है क्या विफल हो रहा है, न कि इसे कहां खोजने के लिए जाएं। +जब कोई एजेंट विफल हो जाता है, तो आपको एक लाइव ईवेंट स्ट्रीम को स्क्रॉल करते हुए लाल पंक्तियों को पकड़ने की कोशिश नहीं करनी चाहिए। **त्रुटि** पृष्ठ आपके लिए संग्रह करता है। यह डैशबोर्ड को लाल दिखाई देने वाली सभी चीजों को एक ट्रिएज सतह में खींचता है, ताकि पहली चीज जो आप देखते हैं वह यह है कि क्या विफल हो रहा है, न कि कहाँ जाना है। -और यह स्पष्ट लोगों से अधिक कैच करता है। स्पष्ट `error` इवेंट्स के साथ-साथ, Failproof AI Observability शांत विफलताओं को भी सतह पर लाता है: कोई भी `tool_result`, `hook_completed`, या `agent_end` जिसका पेलोड विफलता ले जाता है वह यहां दिखाई देता है। एक उपकरण जो त्रुटि लौटाता है, या एक हुक जो बुरी तरह बाहर निकलता है, अब आपसे छिप नहीं जाता क्योंकि कुछ भी जोर से अपवाद नहीं फेंकता। +और यह स्पष्ट वाले से भी अधिक को पकड़ता है। स्पष्ट `error` ईवेंट के साथ, Failproof AI Observability शांत विफलताओं को भी सामने लाता है: कोई भी `tool_result`, `hook_completed`, या `agent_end` जिसका पेलोड एक विफलता को ले जाता है यहाँ दिखाई देता है। एक उपकरण जो एक त्रुटि लौटाता है, या एक हुक जो बुरी तरह से बंद हो जाता है, अब आपसे नहीं छिपता है बस इसलिए कि कोई जोर से अपवाद नहीं फेंका। -शीर्ष में, एक हिस्टोग्राम समय के साथ त्रुटियों को प्लॉट करता है। एक नजर आपको बताता है कि यह एक स्थिर पृष्ठभूमि ट्रिकल है या एक स्पाइक जो कुछ मिनट पहले शुरू हुई, इसलिए आप तुरंत जानते हैं कि आप क्या कर रहे हैं। +शीर्ष पर, एक हिस्टोग्राम समय के साथ त्रुटियों को प्लॉट करता है। एक नज़र बताता है कि क्या यह एक स्थिर पृष्ठभूमि रिसाव है या एक स्पाइक जो कुछ मिनट पहले शुरू हुआ था, इसलिए आप तुरंत जानते हैं कि क्या करना है। -हर अवलोकन सतह की तरह, Errors पृष्ठ आपके संगठन के लिए स्कोप किया गया है और तारीख सीमा, पर्यावरण, एजेंट और सेशन द्वारा फ़िल्टर किया गया है। इसका मतलब है कि आप एक फ्लीट-वाइड सूची ले सकते हैं और इसे उस एक एजेंट या एक पर्यावरण तक सीमित कर सकते हैं जिसकी आप वास्तव में परवाह करते हैं। +प्रत्येक अवलोकन सतह की तरह, त्रुटि पृष्ठ आपके संगठन के दायरे में है और तारीख सीमा, वातावरण, एजेंट और सत्र द्वारा फ़िल्टर करता है। इसका मतलब है कि आप एक फ्लीट-वाइड सूची ले सकते हैं और इसे उस एक एजेंट या एक वातावरण तक सीमित कर सकते हैं जो आप वास्तव में परवाह करते हैं। ## एक घटना, सौ समान पंक्तियां नहीं -एक टूटी हुई निर्भरता प्रति मिनट सैकड़ों बार एक ही त्रुटि को फायर कर सकती है। कच्चे रूप में छोड़ दिया, यह लगभग समान लाइनों की एक दीवार है जो एक चीज को दफन कर देती है जिसे आप वास्तव में देखना चाहते हैं। +एक टूटी हुई निर्भरता एक ही त्रुटि को प्रति मिनट सैकड़ों बार फायर कर सकती है। कच्चे रूप में, यह लगभग-समान लाइनों की एक दीवार है जो उस एक चीज को दफन कर देती है जिसे आप वास्तव में देखना चाहते हैं। -Failproof AI Observability एक ही सेशन और त्रुटि प्रकार साझा करने वाली विफलताओं को दोहराते हुए एक एकल पंक्ति में संपीड़ित करता है। एक विस्फोट एक घटना के रूप में पढ़ता है। आप समस्याओं को गिनते हैं, लॉग लाइनों को नहीं, और महत्वपूर्ण सिग्नल शीर्ष पर रहता है अपनी स्वयं की मात्रा में डूबने के बजाय। +Failproof AI Observability एक ही सत्र और त्रुटि प्रकार साझा करने वाली दोहराई गई विफलताओं को एक पंक्ति में संक्षिप्त करता है। एक फटना एक घटना के रूप में पढ़ता है। आप समस्याओं को गिनते हैं, लॉग लाइनों को नहीं, और महत्वपूर्ण संकेत शीर्ष पर रहता है, इसकी अपनी मात्रा से दबा नहीं जाता। -## "कुछ लाल है" से सटीक इवेंट तक +## "कुछ लाल है" से सटीक ईवेंट तक -किसी भी पंक्ति पर क्लिक करें उस रन के सेशन के अंदर सीधे उतरने के लिए, जो विफल हुए सटीक इवेंट पर स्थित है। कोई सेशन ID की नकल नहीं, इसे गलत होने के क्षण को खोजने के लिए स्क्रॉल नहीं करना: आप सीधे इस पर पहुंचते हैं, पूर्ण निष्पादन ग्राफ के साथ एक नज़र दूर ताकि आप देख सकें कि एजेंट ने उसके टूटने से पहले के क्षणों में क्या किया। +किसी भी पंक्ति पर क्लिक करें सीधे उस रन के सत्र के अंदर, सटीक ईवेंट पर स्थित जो विफल हुआ। कोई सत्र आईडी कॉपी नहीं, कोई स्क्रॉलिंग नहीं जब यह गलत हुआ तो क्षण खोजने के लिए: आप सही पर पहुंचते हैं, पूर्ण निष्पादन ग्राफ एक नज़र दूर है ताकि आप देख सकें कि एजेंट क्या किया था इससे पहले कि यह टूट गया। -यदि आपके पास `alerts:write` है, तो हर पंक्ति में एक **+ alert** बटन भी है। इस पर क्लिक करें और Observability एक नया अलर्ट नियम खोलता है जो पहले से ही उसी विफलता को पकड़ने के लिए भरा हुआ है। जिस घटना का आपने अभी ट्रिएज किया है वह अगली बार आपको पेज करने वाली होगी, इसके बजाय दूसरी बार आपको आश्चर्यचकित करने के बजाय। +यदि आपके पास `alerts:write` है, तो प्रत्येक पंक्ति में **+ सतर्कता** बटन भी होता है। इसे क्लिक करें और Observability एक नया सतर्कता नियम खोलता है जो उसी विफलता को पकड़ने के लिए पहले से ही भरा हुआ है। घटना जिसे आपने अभी ट्रिएज किया है वह बन जाती है जो अगली बार आपको पेज करती है, बजाय आपको दो बार आश्चर्यचकित करने के। -**इसे कहां खोजें:** **Errors** पृष्ठ डैशबोर्ड के अवलोकन अनुभाग में रहता है, `//errors` में। +**यहाँ खोजें:** **त्रुटि** पृष्ठ डैशबोर्ड के अवलोकन अनुभाग में है, `//errors` पर। ## संबंधित -- [Alerts](/hi/agenteye/alerts): किसी भी विफलता को एक पेजिंग नियम में बदलें। -- [Incidents](/hi/agenteye/incidents): खुले से समाधान तक एक फायरिंग अलर्ट को ट्रैक करें। -- [Sessions](/hi/agenteye/sessions): किसी भी त्रुटि के पीछे पूरा रन खोलें। -- [Audits](/hi/agenteye/audits): Observability को अपने रन के पार विफलता पैटर्न खोजने दें। \ No newline at end of file +- [सतर्कता](/hi/agenteye/alerts): किसी भी विफलता को एक पेजिंग नियम में बदलें। +- [घटनाएँ](/hi/agenteye/incidents): एक फायरिंग सतर्कता को खुले से हल किए गए तक ट्रैक करें। +- [सत्र](/hi/agenteye/sessions): किसी भी त्रुटि के पीछे का पूरा रन खोलें। +- [ऑडिट](/hi/agenteye/audits): Observability को अपने रन में विफलता पैटर्न खोजने दें। \ No newline at end of file diff --git a/docs/hi/agenteye/evaluation-suite.mdx b/docs/hi/agenteye/evaluation-suite.mdx index d839b36c..8ed57923 100644 --- a/docs/hi/agenteye/evaluation-suite.mdx +++ b/docs/hi/agenteye/evaluation-suite.mdx @@ -1,21 +1,22 @@ --- title: "मूल्यांकन सूट" -description: "Failproof AI Observability प्रत्येक पूर्ण agent run को गुणवत्ता के लिए स्वचालित रूप से स्कोर कर सकता है: आप एक छोटी स्कोरिंग सेवा प्रदान करते हैं, और Observability बाकी को संभालता है।" +description: "Failproof AI Observability हर पूर्ण एजेंट रन को गुणवत्ता के लिए स्वचालित रूप से स्कोर कर सकता है: आप एक छोटी स्कोरिंग सेवा प्रदान करते हैं, और Observability बाकी सब कुछ संभालता है।" --- -Failproof AI Observability प्रत्येक पूर्ण agent run को गुणवत्ता के लिए स्वचालित रूप से स्कोर कर सकता है: आप एक छोटी स्कोरिंग सेवा प्रदान करते हैं, और Observability बाकी को संभालता है। इसका उपयोग उन आयामों को ट्रैक करने के लिए करें जिनकी आपको परवाह है (सहायकता, tool efficiency, तथ्यात्मकता, सुरक्षा; आप चुनते हैं), regression को जल्दी पकड़ें, और agents या environments की तुलना एक नज़र में करें। स्कोरिंग opt-in है: pipeline तब तक कुछ नहीं करता जब तक आप server पर `EVALUATOR_ENDPOINT` सेट नहीं करते। -> **नोट:** आप स्कोर आयाम परिभाषित करते हैं। आपका evaluator किसी भी संख्यात्मक keys को return कर सकता है; Observability जो भी आप भेजते हैं उसे store, trend, और display करता है। +Failproof AI Observability हर पूर्ण एजेंट रन को गुणवत्ता के लिए स्वचालित रूप से स्कोर कर सकता है: आप एक छोटी स्कोरिंग सेवा प्रदान करते हैं, और Observability बाकी सब कुछ संभालता है। इसका उपयोग उन आयामों को ट्रैक करने के लिए करें जिनकी आपको परवाह है (सहायकता, टूल दक्षता, तथ्यात्मकता, सुरक्षा; आप चुनते हैं), प्रतिगमन जल्दी पकड़ें, और एजेंट या वातावरण की तुलना एक नज़र में करें। स्कोरिंग वैकल्पिक है: पाइपलाइन तब तक कुछ नहीं करती जब तक आप सर्वर पर `EVALUATOR_ENDPOINT` सेट नहीं करते। + +> **नोट:** आप स्कोर आयामों को परिभाषित करते हैं। आपका मूल्यांकनकर्ता किसी भी संख्यात्मक कुंजी को वापस कर सकता है जो वह चाहता है; Observability जो भी आप भेजते हैं उसे संग्रहीत, ट्रेंड और प्रदर्शित करता है। ## एक नज़र में -1. **एक scorer लिखें।** एक छोटी HTTP सेवा स्थापित करें जो एक session transcript पढ़ता है और scores return करता है। Observability एक कार्यशील reference ships करता है जिसे आप copy कर सकते हैं। [SDK के साथ एक evaluator लिखना](#writing-an-evaluator-with-the-sdk) देखें। -2. **Observability को इसकी ओर निर्देशित करें।** Server process पर `EVALUATOR_ENDPOINT` (और एक साझा `EVALUATOR_TOKEN`) सेट करें। -3. **Scores को उतरते देखें।** प्रत्येक पूर्ण session स्वचालित रूप से स्कोर किया जाता है; results session detail page, sessions grid, और saved dashboards पर दिखाई देते हैं। +1. **एक स्कोरर लिखें।** एक छोटी HTTP सेवा बनाएं जो एक सेशन ट्रांसक्रिप्ट पढ़ता है और स्कोर लौटाता है। Observability एक कार्यशील संदर्भ शिप करता है जिसे आप कॉपी कर सकते हैं। [SDK के साथ एक मूल्यांकनकर्ता लिखना](#writing-an-evaluator-with-the-sdk) देखें। +2. **Observability को इसकी ओर इशारा करें।** सर्वर प्रक्रिया पर `EVALUATOR_ENDPOINT` (और एक साझा `EVALUATOR_TOKEN`) सेट करें। +3. **स्कोर आते हुए देखें।** हर पूर्ण सेशन को स्वचालित रूप से स्कोर किया जाता है; परिणाम सेशन विवरण पृष्ठ, सेशन ग्रिड और सहेजे गए डैशबोर्ड पर दिखाई देते हैं। -![एक session detail view जिसमें evaluation summary, per-dimension score bars, और right rail में reasoning text है](/agenteye/images/session-detail.png) +![मूल्यांकन सारांश, प्रति-आयाम स्कोर बार और दाईं ओर के रेल में तर्क पाठ के साथ एक सेशन विवरण दृश्य](/agenteye/images/session-detail.png) -*एक बार evaluator configure हो जाने के बाद, प्रत्येक पूर्ण run को स्कोर किया जाता है और results session के right rail में दिखाई देते हैं: शीर्ष पर summary, फिर reasoning के साथ per-dimension score bars।* +*एक बार मूल्यांकनकर्ता कॉन्फ़िगर हो जाने के बाद, प्रत्येक पूर्ण रन को स्कोर किया जाता है और परिणाम सेशन की दाईं ओर दिखाई देते हैं: ऊपर सारांश, फिर तर्क के साथ प्रति-आयाम स्कोर बार।* --- @@ -31,44 +32,44 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -जब Observability SDK एक session के लिए `agent_end` event emit करता है, server एक evaluation को schedule करता है। फिर यह full event transcript को आपकी evaluator सेवा में POST करता है, जो निम्नलिखित में से कर सकता है: +जब Observability SDK किसी सेशन के लिए `agent_end` इवेंट उत्सर्जित करता है, तो सर्वर एक मूल्यांकन शेड्यूल करता है। यह फिर पूरी इवेंट ट्रांसक्रिप्ट आपकी मूल्यांकनकर्ता सेवा को POST करता है, जो या तो: -- **Inline result return करें** `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}` के साथ। Result को session के evaluation timeline में append किया जाता है। `reasoning` और `summary` optional हैं। -- **Defer करें** `{"status":"pending", "job_id":"abc-123"}` के साथ। Observability फिर `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` को तब तक call करता है जब तक आपका evaluator `{"status":"done", ...}` या `{"status":"error", "error":"..."}` return नहीं करता। +- **परिणाम को इनलाइन लौटाएं** `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}` के साथ। परिणाम सेशन की मूल्यांकन समयरेखा में जोड़ा जाता है। `reasoning` और `summary` वैकल्पिक हैं। +- **स्थगित करें** `{"status":"pending", "job_id":"abc-123"}` के साथ। Observability फिर `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` को कॉल करता है जब तक आपका मूल्यांकनकर्ता `{"status":"done", ...}` या `{"status":"error", "error":"..."}` लौटाता है। - Polling cadence per-job है: एक `pending` response में `next_poll_secs` शामिल हो सकता है को override करने के लिए; अन्यथा Observability `GET /config` से `default_poll_interval_secs` value का उपयोग करता है; अन्यथा server `EVALUATOR_POLLING_INTERVAL_SECS` (default 10s) पर fallback करता है। सभी values को [1s, 1h] में clamp किया जाता है। + पोलिंग गति प्रति-कार्य है: एक `pending` प्रतिक्रिया `next_poll_secs` को ओवरराइड करने के लिए शामिल कर सकती है; अन्यथा Observability `GET /config` से `default_poll_interval_secs` मान का उपयोग करता है; अन्यथा सर्वर `EVALUATOR_POLLING_INTERVAL_SECS` (डिफ़ॉल्ट 10s) को फॉलबैक करता है। सभी मान [1s, 1h] में क्लैम्प किए जाते हैं। -जो sessions कभी `agent_end` emit नहीं करते (उदाहरण के लिए, एक crashed agent process) को भी pick up किया जा सकता है: evaluator का `GET /config` `{"inactivity_timeout_secs": 1800}` return कर सकता है, और Observability किसी भी session को evaluate करेगा जो उतने समय के लिए idle गया हो। इस fallback को disable करने के लिए field को `null` सेट करें या इसे omit करें। +जो सेशन कभी `agent_end` उत्सर्जित नहीं करते (उदाहरण के लिए, एक क्रैश हुई एजेंट प्रक्रिया) उन्हें भी उठाया जा सकता है: मूल्यांकनकर्ता का `GET /config` `{"inactivity_timeout_secs": 1800}` लौटा सकता है, और Observability किसी भी सेशन का मूल्यांकन करेगा जो उस लंबे समय के लिए निष्क्रिय हो गया है। इस फॉलबैक को अक्षम करने के लिए फ़ील्ड को `null` पर सेट करें या इसे छोड़ दें। -`EVALUATOR_ENDPOINT` unset होने पर pipeline पूरी तरह no-op है। +जब `EVALUATOR_ENDPOINT` अनसेट होता है तो पाइपलाइन पूरी तरह से no-op होती है। -एक session समय के साथ **multiple terminal evaluations को accumulate कर सकता है**: प्रत्येक `agent_end` event (और dashboard से प्रत्येक manual re-eval) एक fresh evaluation row को append करता है। यह एक resumed conversation को evaluate करने का supported तरीका है: एक user एक agent को end करता है, बाद में वापस आता है, अधिक events भेजता है, agent को फिर से end करता है, और एक दूसरा evaluation पूरे updated transcript के विरुद्ध चलता है। Dashboard सबसे हाल के evaluation को headline के रूप में render करता है और prior evaluations को एक collapsible timeline के रूप में। जब एक session के लिए एक evaluation चल रहा होता है, उस session के लिए अतिरिक्त `agent_end` events को ignore किया जाता है; चलाए गए evaluation के complete होने के बाद अगला एक fresh evaluation को queue करेगा जैसा कि usual है। +एक सेशन समय के साथ **कई टर्मिनल मूल्यांकन जमा कर सकता है**: प्रत्येक `agent_end` इवेंट (और डैशबोर्ड से प्रत्येक मैनुअल पुनः-मूल्य) एक ताजा मूल्यांकन पंक्ति जोड़ता है। यह एक पुनः सेशन का मूल्यांकन करने का समर्थित तरीका है: एक उपयोगकर्ता एक एजेंट को समाप्त करता है, बाद में वापस आता है, अधिक इवेंट भेजता है, एजेंट को फिर से समाप्त करता है, और एक दूसरा मूल्यांकन पूरी अद्यतन ट्रांसक्रिप्ट के विरुद्ध चलता है। डैशबोर्ड सबसे हाल के मूल्यांकन को हेडलाइन के रूप में प्रस्तुत करता है और पूर्व के मूल्यांकन को एक संक्षिप्त समयरेखा के रूप में प्रस्तुत करता है। जब एक सेशन के लिए एक मूल्यांकन चल रहा हो, उस सेशन के लिए अतिरिक्त `agent_end` इवेंट को अनदेखा किया जाता है; चलने वाले मूल्यांकन के पूरा होने के बाद अगला एक सामान्य रूप से एक ताजा मूल्यांकन को कतार में डालेगा। -Inactivity fallback भी resumed sessions पर re-engages करता है: यदि नए events पहले के terminal evaluation के बाद आते हैं और session फिर `inactivity_timeout_secs` के पिछले idle जाता है, तो एक fresh evaluation को enqueue किया जाता है। +निष्क्रियता फॉलबैक पुनः सेशन पर भी पुनः संलग्न होता है: यदि पूर्व टर्मिनल मूल्यांकन के बाद नई घटनाएं आती हैं और सेशन फिर `inactivity_timeout_secs` के बाद निष्क्रिय हो जाता है, तो एक ताजा मूल्यांकन को कतारबद्ध किया जाता है। -Transient failures (5xx, 429, timeouts, network errors) को `EVALUATOR_MAX_ATTEMPTS` तक exponential backoff के साथ retry किया जाता है; 4xx responses terminal होते हैं। Observability multiple horizontally-scaled server instances के साथ चलाने के लिए safe है; work को partition किया जाता है इसलिए एक ही session को कभी concurrently दो बार dispatch नहीं किया जाता। +अस्थायी विफलताएं (5xx, 429, टाइमआउट, नेटवर्क त्रुटियां) `EVALUATOR_MAX_ATTEMPTS` तक घातीय बैकऑफ के साथ पुनः प्रयास की जाती हैं; 4xx प्रतिक्रियाएं टर्मिनल हैं। Observability कई क्षैतिज-स्केल किए गए सर्वर उदाहरणों के साथ चलाने के लिए सुरक्षित है; कार्य को विभाजित किया जाता है ताकि एक ही सेशन को कभी एक साथ दो बार भेजा न जाए। --- -## HTTP contract +## HTTP अनुबंध -प्रत्येक authenticated route **bearer token auth** का उपयोग करता है। एक ही value दोनों sides पर configure की जानी चाहिए: +हर प्रमाणित मार्ग **असहायक टोकन प्रमाणीकरण** का उपयोग करता है। समान मूल्य दोनों पक्षों पर कॉन्फ़िगर किया जाना चाहिए: -- Observability server: env var `EVALUATOR_TOKEN` -- Evaluator service: एक ही तरीके से configure किया गया (the `agenteye-evaluator` SDK convention के अनुसार `EVALUATOR_TOKEN` को read करता है) +- Observability सर्वर: env var `EVALUATOR_TOKEN` +- मूल्यांकनकर्ता सेवा: समान तरीके से कॉन्फ़िगर किया गया (the `agenteye-evaluator` SDK सम्मेलन द्वारा `EVALUATOR_TOKEN` पढ़ता है) -यदि `EVALUATOR_TOKEN` unset है, तो server कोई `Authorization` header नहीं भेजता है; evaluator फिर anonymous requests को accept कर सकता है, जो internal-only network के लिए ठीक है लेकिन public internet पर discouraged है। +यदि `EVALUATOR_TOKEN` अनसेट है, तो सर्वर कोई `Authorization` हेडर नहीं भेजता; मूल्यांकनकर्ता फिर अनाम अनुरोधों को स्वीकार कर सकता है, जो आंतरिक-केवल नेटवर्क के लिए ठीक है लेकिन सार्वजनिक इंटरनेट पर हतोत्साहित किया जाता है। -### Routes जो evaluator को serve करना चाहिए +### मूल्यांकनकर्ता को सेवा करने वाले मार्ग -| Route | Body / params | Response | +| मार्ग | बॉडी / पैरामीटर | प्रतिक्रिया | |---|---|---| -| `GET /health` | none | `{"status":"ok"}` (open, no auth) | -| `GET /config` | none | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | -| `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` or `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | none | same response shape as `/evaluate` | +| `GET /health` | कोई नहीं | `{"status":"ok"}` (खुला, कोई प्रमाणीकरण नहीं) | +| `GET /config` | कोई नहीं | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | +| `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` या `{"status":"pending", "job_id":"..."}` | +| `GET /evaluate/{id}` | कोई नहीं | `/evaluate` के समान प्रतिक्रिया आकार | -### Server द्वारा भेजा गया `EvalRequest` body +### सर्वर द्वारा भेजा गया `EvalRequest` बॉडी ```json { @@ -85,9 +86,9 @@ Transient failures (5xx, 429, timeouts, network errors) को `EVALUATOR_MAX_AT } ``` -### Response shapes +### प्रतिक्रिया आकार -**Sync (done):** +**सिंक (पूर्ण):** ```json { @@ -101,33 +102,33 @@ Transient failures (5xx, 429, timeouts, network errors) को `EVALUATOR_MAX_AT } ``` -`reasoning` (एक per-score justification map) और `summary` (एक overall one-paragraph narrative) दोनों optional हैं। `reasoning` में keys को `scores` में keys को mirror करना चाहिए; dashboard प्रत्येक entry को अपने score bar के अंतर्गत render करता है। Older evaluators जो केवल `scores` return करते हैं वह unchanged continue करते हैं; `reasoning` और `summary` बस null के रूप में read करते हैं और corresponding UI affordances को omit किया जाता है। +`reasoning` (एक प्रति-स्कोर औचित्य मानचित्र) और `summary` (एक समग्र एक-पैराग्राफ आख्यान) दोनों वैकल्पिक हैं। `reasoning` में कुंजियां `scores` में कुंजियों को प्रतिबिंबित करनी चाहिए; डैशबोर्ड प्रत्येक प्रविष्टि को इसके स्कोर बार के नीचे इनलाइन प्रस्तुत करता है। पुराने मूल्यांकनकर्ता जो केवल `scores` लौटाते हैं वे अपरिवर्तित जारी रहते हैं; `reasoning` और `summary` केवल null के रूप में पढ़ते हैं और संबंधित UI सुविधाएं हटा दी जाती हैं। -**Async (deferred):** +**अनुकूलन (स्थगित):** ```json { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` optional है; यदि omitted है तो server `/config` से evaluator के `default_poll_interval_secs` पर fallback करता है, फिर अपने `EVALUATOR_POLLING_INTERVAL_SECS` env var पर। +`next_poll_secs` वैकल्पिक है; यदि छोड़ा जाता है तो सर्वर `/config` से मूल्यांकनकर्ता के `default_poll_interval_secs` में गिरता है, फिर इसके स्वयं के `EVALUATOR_POLLING_INTERVAL_SECS` env var में। -**Terminal evaluator-side error:** +**टर्मिनल मूल्यांकनकर्ता-पक्ष त्रुटि:** ```json { "status": "error", "error": "model service unavailable" } ``` -Server किसी अन्य 2xx body को protocol error के रूप में treat करता है और session के लिए एक terminal `error` को record करता है। +सर्वर किसी अन्य 2xx बॉडी को प्रोटोकॉल त्रुटि के रूप में मानता है और सेशन के लिए एक टर्मिनल `error` रिकॉर्ड करता है। --- -## SDK के साथ एक evaluator लिखना +## SDK के साथ एक मूल्यांकनकर्ता लिखना -आपको HTTP contract को manually implement नहीं करना है। `agenteye-evaluator` Python package आपको एक typed FastAPI wrapper देता है जो auth, routing, और request/response shapes को आपके लिए handle करता है। +आपको HTTP अनुबंध को हाथ से लागू नहीं करना है। `agenteye-evaluator` Python पैकेज आपको एक टाइप्ड FastAPI रैपर देता है जो प्रमाणीकरण, रूटिंग और अनुरोध/प्रतिक्रिया आकारों को आपके लिए संभालता है। -Failproof AI Observability एक **कार्यशील reference evaluator** भी ships करता है जो transcript के shape से `helpfulness`, `tool_efficiency`, और `factuality` को score करता है। इसे starting point के रूप में copy करें और अपने स्वयं के logic को swap करें: एक LLM judge, एक rule engine, कुछ भी जो आपकी quality bar को fit करता है। +Failproof AI Observability भी एक **कार्यशील संदर्भ मूल्यांकनकर्ता** शिप करता है जो ट्रांसक्रिप्ट के आकार से `helpfulness`, `tool_efficiency` और `factuality` को स्कोर करता है। इसे एक प्रारंभिक बिंदु के रूप में कॉपी करें और अपनी स्वयं की तर्क में स्वैप करें: एक LLM न्यायाधीश, एक नियम इंजन, जो भी आपकी गुणवत्ता पट्टी को फिट करता है। -Minimum viable evaluator: +न्यूनतम व्यवहार्य मूल्यांकनकर्ता: ```python import os @@ -146,60 +147,60 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -`app` instance किसी भी ASGI server के अंतर्गत चलता है, इसलिए `uvicorn module:app` इसे start करता है। +`app` उदाहरण किसी भी ASGI सर्वर के तहत चलता है, तो `uvicorn module:app` इसे शुरू करता है। -उन evaluators के लिए जिन्हें expensive work को defer करने की आवश्यकता है, `JobPending` को instead return करें और एक `@app.job_lookup` handler को register करें; Observability server `GET /evaluate/{job_id}` को तब तक poll करता है जब तक आप एक terminal status return नहीं करते या `EVALUATOR_MAX_POLL_DURATION_SECS` cap (default 1 h) elapse न हो। +उन मूल्यांकनकर्ताओं के लिए जिन्हें महंगे कार्य को स्थगित करने की आवश्यकता है, इसके बजाय `JobPending` लौटाएं और एक `@app.job_lookup` हैंडलर पंजीकृत करें; Observability सर्वर `GET /evaluate/{job_id}` को तब तक पोल करता है जब तक आप एक टर्मिनल स्थिति लौटाते हैं या `EVALUATOR_MAX_POLL_DURATION_SECS` कैप (डिफ़ॉल्ट 1 h) बीत जाते हैं। -Full API reference, async pattern, और event schema को `agenteye-evaluator` SDK के README में document किया गया है। +संपूर्ण API संदर्भ, अनुकूलन पैटर्न और इवेंट स्कीमा `agenteye-evaluator` SDK के README में प्रलेखित हैं। --- -## अपने evaluator को चलाना +## आपके मूल्यांकनकर्ता को चलाना -Evaluator **आपकी सेवा** है — Failproof AI Observability एक default evaluator ship नहीं करता है, इसलिए आप इसे जहां अपनी सेवाओं को चलाते हैं वहां build और run करते हैं। यह किसी भी ASGI server के अंतर्गत चलता है (उदाहरण के लिए `uvicorn my_evaluator:app`); [HTTP contract](#http-contract) से `/health`, `/config`, और `/evaluate` routes को serve करें, फिर server को इसकी ओर निर्देशित करें (देखें [Server को configure करना](#configuring-the-server))। +मूल्यांकनकर्ता **आपकी सेवा** है — Failproof AI Observability एक डिफ़ॉल्ट मूल्यांकनकर्ता शिप नहीं करता, इसलिए आप इसे जहां आप अपनी स्वयं की सेवाएं चलाते हैं वहां बनाते और चलाते हैं। यह किसी भी ASGI सर्वर के तहत चलता है (उदाहरण के लिए `uvicorn my_evaluator:app`); [HTTP अनुबंध](#http-contract) से `/health`, `/config` और `/evaluate` मार्गों को सेवा दें, फिर सर्वर को इसकी ओर इशारा करें ([सर्वर कॉन्फ़िगर करना](#configuring-the-server) देखें)। -एक बार evaluator reachable हो जाने के बाद, `GET /health` `{"status":"ok"}` return करता है। एक agent को end-to-end चलाने के बाद, server पर `GET /evaluations` एक row return करता है `status: "done"` के साथ और scores जो आपका evaluator produce किया। +एक बार मूल्यांकनकर्ता पहुंचने योग्य हो, `GET /health` `{"status":"ok"}` लौटाता है। एक एजेंट अंत-से-अंत चलने के बाद, सर्वर पर `GET /evaluations` एक पंक्ति के साथ `status: "done"` और आपके मूल्यांकनकर्ता द्वारा उत्पादित स्कोर लौटाता है। --- -## Server को configure करना +## सर्वर कॉन्फ़िगर करना -Server process पर सेट करें: +सर्वर प्रक्रिया पर सेट करें: -| Env var | Meaning | +| Env var | अर्थ | |---|---| -| `EVALUATOR_ENDPOINT` | आपके evaluator का base URL (`http://evaluator:9000`)। Unset = pipeline disabled। | -| `EVALUATOR_TOKEN` | Bearer token। Evaluator सेवा को configure किए गए value के बराबर होना चाहिए। | -| `EVALUATOR_WORKERS` | Server instance per worker tasks (default 2)। | -| `EVALUATOR_CLAIM_BATCH` | Per worker tick rows claimed (default 4)। Batches को **concurrently** process किया जाता है; आपके evaluator endpoint पर effective concurrency `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` है। | -| `EVALUATOR_POLL_IDLE_SECS` | कब तक एक worker dispatch attempts के बीच sleep करता है जब कोई evaluation due नहीं होता (default 2s)। | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `GET /evaluate/{id}` cadence के लिए final fallback जब न तो per-response `next_poll_secs` न ही evaluator का `default_poll_interval_secs` set हो (default 10s)। | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | Per-request timeout (default 30000)। | -| `EVALUATOR_MAX_ATTEMPTS` | इस कई transient failures के बाद result को terminal `error` के रूप में record किया जाता है (default 5)। | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` cadence (default 300)। | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Maximum wallclock time जो एक session polling queue में रह सकता है इससे पहले कि यह `timeout` के रूप में terminated हो (default 3600s)। एक evaluator के विरुद्ध guards जो forever `pending` को return करता रहता है। | +| `EVALUATOR_ENDPOINT` | आपके मूल्यांकनकर्ता का आधार URL (`http://evaluator:9000`)। अनसेट = पाइपलाइन अक्षम। | +| `EVALUATOR_TOKEN` | असहायक टोकन। मूल्यांकनकर्ता सेवा के साथ कॉन्फ़िगर किए गए मूल्य के समान होना चाहिए। | +| `EVALUATOR_WORKERS` | सर्वर उदाहरण प्रति कार्यकर्ता कार्य (डिफ़ॉल्ट 2)। | +| `EVALUATOR_CLAIM_BATCH` | कार्यकर्ता टिक प्रति पंक्तियां दावा की गई (डिफ़ॉल्ट 4)। बैच **समवर्ती** रूप से संसाधित किए जाते हैं; आपके मूल्यांकनकर्ता एंडपॉइंट पर प्रभावी समवर्तिता `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` है। | +| `EVALUATOR_POLL_IDLE_SECS` | कार्यकर्ता कितने समय तक सोता है जब कोई मूल्यांकन निष्पादन के योग्य नहीं होता (डिफ़ॉल्ट 2s) के बीच। | +| `EVALUATOR_POLLING_INTERVAL_SECS` | `GET /evaluate/{id}` गति के लिए अंतिम फॉलबैक जब न तो प्रति-प्रतिक्रिया `next_poll_secs` और न ही मूल्यांकनकर्ता का `default_poll_interval_secs` सेट है (डिफ़ॉल्ट 10s)। | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | प्रति-अनुरोध टाइमआउट (डिफ़ॉल्ट 30000)। | +| `EVALUATOR_MAX_ATTEMPTS` | इस कई अस्थायी विफलताओं के बाद परिणाम टर्मिनल `error` के रूप में दर्ज किया जाता है (डिफ़ॉल्ट 5)। | +| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` गति (डिफ़ॉल्ट 300)। | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | अधिकतम वॉलक्लॉक समय जो कोई सेशन पोलिंग कतार में रह सकता है इससे पहले कि इसे `timeout` के रूप में समाप्त किया जाए (डिफ़ॉल्ट 3600s)। एक मूल्यांकनकर्ता के विरुद्ध गार्ड जो हमेशा `pending` लौटाता रहता है। | -Automatic scoring को turn on करने के लिए, server पर `EVALUATOR_ENDPOINT` और `EVALUATOR_TOKEN` दोनों सेट करें, फिर change को pick up करने के लिए इसे restart करें। `EVALUATOR_ENDPOINT` unset होने पर pipeline एक no-op रहता है। +स्वचालित स्कोरिंग चालू करने के लिए, सर्वर पर `EVALUATOR_ENDPOINT` और `EVALUATOR_TOKEN` दोनों को सेट करें, फिर परिवर्तन को चुनने के लिए इसे पुनः प्रारंभ करें। `EVALUATOR_ENDPOINT` के अनसेट होने पर पाइपलाइन एक no-op रहती है। -ऊपर की tuning knobs optional हैं; केवल यदि आप defaults को override करना चाहते हैं तो server पर corresponding environment variables सेट करें। +ऊपर दी गई ट्यूनिंग नॉब्स वैकल्पिक हैं; डिफ़ॉल्ट ओवरराइड करने की आवश्यकता होने पर सर्वर पर संबंधित पर्यावरण चर को केवल सेट करें। --- -## API reference +## API संदर्भ -| Method | Path | Required permission | Purpose | +| विधि | पथ | आवश्यक अनुमति | उद्देश्य | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Terminal results को query करें। `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session` को support करता है। `limit` default 50 है और 200 पर capped है (ध्यान दें कि यह `/events` से भिन्न है, जो 1000 पर caps करता है)। `environment` comma-separated list accept करता है (उदा. `environment=prod,staging`); single values अभी भी काम करते हैं। `latest_per_session=true` के साथ response में प्रति `session_id` अधिकतम एक row होता है (the most recent by `completed_at`) sessions-list page द्वारा उपयोग किया जाता है एक session के evaluation timeline को इसकी current headline में collapse करने के लिए। Default false है (पूरा history return करता है)। | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | एक filtered slice के लिए rolled-up eval health: total count, एक done/error/timeout breakdown, per-score-key stats (count/avg/min/max/p50 arbitrary `scores` keys पर), और एक time-bucketed timeline। **`/evaluations` के रूप में ही filter params accept करता है** plus `featured_keys` (trend करने के लिए score keys का CSV) और `latest_per_session`। Dashboards feature को power करता है; metrics पूरे matching set पर exact हैं, sampled नहीं। | -| `GET` | `/evaluations/environments` | `evaluations:read` | `evaluations` table से distinct environment values। Evaluation-readable data के लिए scoped filter dropdowns को populate करने के लिए उपयोग किया जाता है। | -| `GET` | `/evaluation-jobs` | `evaluations:read` | In-flight evaluations में visibility। `status` (`pending`/`polling`) के अनुसार filter करें। | -| `GET` | `/events` | `events:read` | एक session के raw events को stream करें। `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit`, और `order` को support करता है। `order` `desc` (newest-first, the default) या `asc` (oldest-first) है; एक unrecognized value `desc` पर fallback करता है। Response के `next_cursor` (एक event id) के माध्यम से cursor-paginate करें: अगला page get करने के लिए इसे `cursor` के रूप में pass करें; `asc` के साथ अगला page उस id के बाद events हैं, `desc` के साथ उससे पहले events हैं। `limit` default 50 है और 1000 पर capped है। | -| `GET` | `/sessions/:session_id/export` | `events:read` | Exact JSON body return करता है जो evaluator को इस session के लिए प्राप्त होगा, `session-.json` नामित एक downloadable attachment के रूप में served। Production sessions को offline testing के लिए `agenteye-evaluator` के माध्यम से replay करने के लिए उपयोगी। Bytes evaluator pipeline भेजता है जो byte-identical हैं। | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | एक session के लिए एक fresh evaluation को enqueue करें; चाहे prior evaluation exist करे या नहीं। नया result session के evaluation timeline में **appended** होता है rather than overwriting previous one को, इसलिए prior scores history के रूप में visible रहते हैं। Enqueue पर `202` return करता है, unknown session के लिए `404`, यदि एक evaluation पहले से in flight है तो `409`। यह एक नए evaluator को deploy करने के बाद use करें, या ऐसे sessions के लिए जिन्होंने कभी `agent_end` emit नहीं किया। | +| `GET` | `/evaluations` | `evaluations:read` | टर्मिनल परिणामों को क्वेरी करें। `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session` का समर्थन करता है। `limit` डिफ़ॉल्ट 50 है और 200 पर कैप किया जाता है (ध्यान दें यह `/events` से भिन्न है, जो 1000 पर कैप करता है)। `environment` अल्पविराम-विभाजित सूची स्वीकार करता है (उदाहरण के लिए `environment=prod,staging`); एकल मान अभी भी काम करते हैं। `latest_per_session=true` के साथ प्रतिक्रिया प्रति `session_id` (सबसे हाल के `completed_at`) अधिकतम एक पंक्ति में होती है जिसका उपयोग सेशन-सूची पृष्ठ द्वारा एक सेशन की मूल्यांकन समयरेखा को इसकी वर्तमान हेडलाइन में संक्षिप्त करने के लिए किया जाता है। डिफ़ॉल्ट false (पूरा इतिहास लौटाता है)। | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | फ़िल्टर किए गए स्लाइस के लिए रोल्ड-अप eval स्वास्थ्य: कुल गणना, एक done/error/timeout ब्रेकडाउन, प्रति-स्कोर-कुंजी सांख्यिकी (मनमाने `scores` कुंजियों पर गणना/औसत/न्यूनतम/अधिकतम/p50) और एक समय-विभाजित समयरेखा। `/evaluations` के साथ **समान फ़िल्टर पैरामीटर** साथ ही `featured_keys` (ट्रेंड करने के लिए स्कोर कुंजियों की CSV) और `latest_per_session` स्वीकार करता है। डैशबोर्ड सुविधा को शक्ति देता है; मेट्रिक्स पूरे मिलान सेट पर सटीक होते हैं, नमूना नहीं किए गए। | +| `GET` | `/evaluations/environments` | `evaluations:read` | `evaluations` तालिका से विशिष्ट environment मान। मूल्यांकन-पठनीय डेटा के दायरे में फ़िल्टर ड्रॉपडाउन को भरने के लिए उपयोग किया जाता है। | +| `GET` | `/evaluation-jobs` | `evaluations:read` | उड़ान में मूल्यांकन में दृश्यमानता। `status` (`pending`/`polling`) के अनुसार फ़िल्टर करें। | +| `GET` | `/events` | `events:read` | एक सेशन की कच्ची घटनाओं को स्ट्रीम करें। `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` और `order` का समर्थन करता है। `order` `desc` (newest-first, डिफ़ॉल्ट) या `asc` (oldest-first) है; एक अपरिचित मान `desc` में फॉलबैक होता है। कर्सर-पेजिनेट प्रतिक्रिया के `next_cursor` (एक इवेंट id) के माध्यम से: अगली पृष्ठ प्राप्त करने के लिए इसे `cursor` के रूप में वापस पास करें; `asc` के साथ अगली पृष्ठ उस id के बाद की घटनाएं हैं, `desc` के साथ इससे पहले की घटनाएं हैं। `limit` डिफ़ॉल्ट 50 है और 1000 पर कैप किया जाता है। | +| `GET` | `/sessions/:session_id/export` | `events:read` | सटीक JSON बॉडी लौटाता है कि मूल्यांकनकर्ता इस सेशन के लिए प्राप्त करेगा, डाउनलोड करने योग्य अनुलग्नक `session-.json` के रूप में सेवा की जाती है। उत्पादन सेशन को ऑफलाइन परीक्षण के लिए `agenteye-evaluator` के माध्यम से फिर से चलाने के लिए उपयोगी। बाइट्स मूल्यांकनकर्ता पाइपलाइन द्वारा भेजे गए बाइट-समान हैं। | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | एक सेशन के लिए एक ताजा मूल्यांकन को कतारबद्ध करता है; कोई भी मूल्यांकन पूर्व में मौजूद है या नहीं चलता है। नया परिणाम पूर्व को अधिलेखित करने के बजाय सेशन की मूल्यांकन समयरेखा में **जोड़ा** जाता है, इसलिए पूर्व स्कोर इतिहास के रूप में दृश्यमान रहते हैं। कतारबद्ध पर `202` लौटाता है, अज्ञात सेशन के लिए `404`, यदि कोई मूल्यांकन पहले से ही चल रहा है तो `409`। एक नया मूल्यांकनकर्ता तैनात करने के बाद, या उन सेशन के लिए जो कभी `agent_end` उत्सर्जित नहीं करते, इसका उपयोग करें। | -### Score range के अनुसार filtering: `score_filters` +### स्कोर रेंज के आधार पर फ़िल्टर करना: `score_filters` -`GET /evaluations` एक optional `score_filters` parameter accept करता है जो results को `scores` object के अंदर numeric values के अनुसार narrow करता है। Parameter एक comma-separated list है `key:min..max` entries का; किसी भी bound को omit किया जा सकता है। Multiple entries logical AND के साथ combine होते हैं। Rows जहां named key absent या non-numeric है को exclude किया जाता है। एक request में अधिकतम 20 filter entries हो सकते हैं; exceeding that HTTP 400 return करता है। +`GET /evaluations` एक वैकल्पिक `score_filters` पैरामीटर स्वीकार करता है जो `scores` ऑब्जेक्ट के अंदर संख्यात्मक मानों द्वारा परिणामों को संकीर्ण करता है। पैरामीटर `key:min..max` प्रविष्टियों की एक अल्पविराम-विभाजित सूची है; या तो बाउंड छोड़ा जा सकता है। कई प्रविष्टियां तार्किक AND के साथ संयोजित होती हैं। पंक्तियां जहां नामित कुंजी अनुपस्थित है या गैर-संख्यात्मक है वहां बाहर रखी जाती हैं। एक अनुरोध अधिकतम 20 फ़िल्टर प्रविष्टियां ले जा सकता है; उससे अधिक HTTP 400 लौटाता है। उदाहरण: ```text @@ -213,87 +214,87 @@ GET /evaluations?score_filters=tool_efficiency:..0.3 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` -प्रत्येक `/evaluations` response object के ये fields हैं: +प्रत्येक `/evaluations` प्रतिक्रिया ऑब्जेक्ट में ये फ़ील्ड हैं: -| Field | Type | Notes | +| फ़ील्ड | प्रकार | नोट्स | |---|---|---| -| `evaluation_id` | string (UUID) | इस terminal evaluation के लिए canonical identifier। प्रत्येक terminal evaluation को एक नया UUID मिलता है; एक single session में multiple हो सकते हैं। | -| `id` | string (UUID) | Backwards-compatibility alias `evaluation_id` के समान value को carry करता है। | -| `session_id` | string | Session जिसके विरुद्ध यह evaluation चलाया गया। एक session के timeline में multiple evaluations हो सकते हैं। | -| `agent_id` | string | Agent को identify करता है जो session produce किया। | -| `environment` | string | Environment label जो session से copy किया गया। | +| `evaluation_id` | string (UUID) | इस टर्मिनल मूल्यांकन के लिए कैनोनिकल पहचानकर्ता। प्रत्येक टर्मिनल मूल्यांकन को नया UUID मिलता है; एक भी सेशन कई हो सकते हैं। | +| `id` | string (UUID) | `evaluation_id` के समान मान को ले जाने वाली पश्चगामी-संगतता उपनाम। | +| `session_id` | string | वह सेशन जिसके विरुद्ध यह मूल्यांकन चला। एक सेशन में समयरेखा में कई मूल्यांकन हो सकते हैं। | +| `agent_id` | string | एजेंट को पहचानता है जिसने सेशन का उत्पादन किया। | +| `environment` | string | पर्यावरण लेबल सेशन से कॉपी किया गया। | | `status` | enum | `"done"`, `"error"`, `"timeout"` में से एक। | -| `scores` | object \| null | आपके evaluator द्वारा return किए गए Scores। | -| `reasoning` | object \| null | Optional per-score justification map आपके evaluator द्वारा return किया गया। Keys typically `scores` में उन keys को mirror करते हैं। Dashboard प्रत्येक entry को अपने score bar के अंतर्गत render करता है। | -| `summary` | string \| null | Optional one-paragraph overall narrative आपके evaluator द्वारा return किया गया। Dashboard इसे per-score breakdown के ऊपर render करता है evaluation के headline के रूप में। | -| `error` | string \| null | केवल `"error"` / `"timeout"` पर populated। | -| `attempt_count` | integer | Dispatch attempts की संख्या (≥ 1)। | -| `duration_ms` | integer \| null | Final attempt की duration। | -| `completed_at` | string (ISO 8601 UTC) | जब terminal result को record किया गया। Results को `completed_at` (newest first) के अनुसार order किया जाता है। | -| `created_at` | string (ISO 8601 UTC) | `completed_at` के समान timestamp carry करता है (write-once semantics)। | +| `scores` | object \| null | आपके मूल्यांकनकर्ता द्वारा लौटाए गए स्कोर। | +| `reasoning` | object \| null | आपके मूल्यांकनकर्ता द्वारा लौटाए गए वैकल्पिक प्रति-स्कोर औचित्य मानचित्र। कुंजियां आमतौर पर `scores` में कुंजियों को दर्पण करती हैं। डैशबोर्ड प्रत्येक प्रविष्टि को इसके स्कोर बार के नीचे प्रस्तुत करता है। | +| `summary` | string \| null | आपके मूल्यांकनकर्ता द्वारा लौटाए गए वैकल्पिक एक-पैराग्राफ समग्र आख्यान। डैशबोर्ड प्रति-स्कोर विफलता के रूप में मूल्यांकन की हेडलाइन ऊपर इसे प्रस्तुत करता है। | +| `error` | string \| null | केवल `"error"` / `"timeout"` पर भरा जाता है। | +| `attempt_count` | integer | प्रेषण प्रयासों की संख्या (≥ 1)। | +| `duration_ms` | integer \| null | अंतिम प्रयास की अवधि। | +| `completed_at` | string (ISO 8601 UTC) | जब टर्मिनल परिणाम दर्ज किया गया था। परिणाम `completed_at` (newest first) द्वारा ऑर्डर किए जाते हैं। | +| `created_at` | string (ISO 8601 UTC) | `completed_at` के समान टाइमस्टैम्प रखता है (लिखना-एक बार सिमेंटिक्स)। | --- -## Permissions +## अनुमतियां -| Permission | Grants | +| अनुमति | अनुदान | |---|---| -| `evaluations:read` | Evaluation results को list करें, dashboard में scores को view करें, और dashboard health metrics को load करें। | -| `evaluations:trigger` | Manually `POST /sessions/:session_id/re-evaluate` के माध्यम से एक session के लिए एक evaluation को enqueue करें या dashboard के re-evaluate button का। | -| `dashboards:read` | Saved dashboards को view करें (उनके metrics को load करने के लिए `evaluations:read` भी चाहिए)। | -| `dashboards:write` | Dashboards को create और edit करें। | -| `dashboards:delete` | Dashboards को delete करें। | +| `evaluations:read` | मूल्यांकन परिणाम सूचीबद्ध करें, डैशबोर्ड में स्कोर देखें, और डैशबोर्ड स्वास्थ्य मेट्रिक्स लोड करें। | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` के माध्यम से सेशन के लिए मैनुअल रूप से एक मूल्यांकन को कतारबद्ध करें या डैशबोर्ड के पुनः-मूल्यांकन बटन। | +| `dashboards:read` | सहेजे गए डैशबोर्ड देखें (उनकी मेट्रिक्स लोड करने के लिए भी `evaluations:read` चाहिए)। | +| `dashboards:write` | डैशबोर्ड बनाएं और संपादित करें। | +| `dashboards:delete` | डैशबोर्ड हटाएं। | -Bootstrap admin (`ADMIN_KEY`, `ADMIN_EMAIL`) स्वचालित रूप से ये सभी receive करता है। +बूटस्ट्रैप व्यवस्थापक (`ADMIN_KEY`, `ADMIN_EMAIL`) स्वचालित रूप से इन्हें प्राप्त करता है। --- -## Results को देखना +## परिणामों को देखना -- **`/sessions/`**: events timeline + एक right rail जो session के scores और dispatch attempt से कोई error दिखाता है। यदि आपकी key के पास `evaluations:trigger` है, तो एक **re-evaluate** button export button के आगे दिखाई देता है, उन sessions के लिए उपयोगी जिन्होंने कभी `agent_end` emit नहीं किया, या एक नए evaluator को deploy करने के बाद scores को refresh करने के लिए। Dashboard नए result के लिए polls करता है और इसे जब land करता है तो right rail को update करता है। -- **`/sessions`**: filterable session grid; score column प्रत्येक session की evaluation status और scores को एक नज़र में दिखाता है। -- **`/dashboards`**: saved eval-health views (देखें [Dashboards](#dashboards) नीचे)। +- **`/sessions/`**: इवेंट्स समयरेखा + एक सही रेल जो सेशन के स्कोर और प्रेषण प्रयास से कोई त्रुटि दिखाती है। यदि आपकी कुंजी में `evaluations:trigger` है, तो एक **पुनः-मूल्यांकन** बटन निर्यात बटन के बगल में दिखाई देता है, उन सेशन के लिए उपयोगी जो कभी `agent_end` उत्सर्जित नहीं करते हैं, या एक नया मूल्यांकनकर्ता तैनात करने के बाद स्कोर को ताज़ा करने के लिए। डैशबोर्ड नई परिणाम के लिए पोल करता है और इसके आने पर दाईं ओर को अपडेट करता है। +- **`/sessions`**: फ़िल्टर योग्य सेशन ग्रिड; स्कोर कॉलम प्रत्येक सेशन की मूल्यांकन स्थिति और स्कोर एक नज़र में दिखाता है। +- **`/dashboards`**: सहेजे गए eval-health दृश्य ([डैशबोर्ड](#dashboards) नीचे देखें)। -![Sessions grid per-session evaluation status pills और colour-coded score badges (helpfulness, factuality, tool_efficiency, safety, coherence) के साथ](/agenteye/images/sessions-list.png) +![सेशन ग्रिड प्रति-सेशन मूल्यांकन स्थिति गोलियों और रंग-कोडित स्कोर बैज (सहायकता, तथ्यात्मकता, tool_efficiency, सुरक्षा, सुसंगतता) के साथ](/agenteye/images/sessions-list.png) -*Sessions grid प्रत्येक run की evaluation status और scores को एक नज़र में दिखाता है; red/amber/green badges low scores को jump out करते हैं।* +*सेशन ग्रिड प्रत्येक रन की मूल्यांकन स्थिति और स्कोर एक नज़र में दिखाता है; लाल/एम्बर/हरी बैज कम स्कोर को कूद बाहर बनाते हैं।* --- -## Dashboards +## डैशबोर्ड -**Dashboards** page (`/dashboards`) आपको evaluation filters के एक combination को एक named, reusable view के रूप में save करने देता है और watch करता है कि evaluations का यह slice एक नज़र में कैसे कर रहा है। Dashboards **आपके पूरे organization में shared** हैं; `dashboards:read` के साथ सभी को same set दिखाई देता है। +**डैशबोर्ड** पृष्ठ (`/dashboards`) आपको मूल्यांकन फ़िल्टर के संयोजन को एक नामित, पुन: प्रयोज्य दृश्य के रूप में सहेजने और उस स्लाइस को मूल्यांकन कैसे कर रहे हैं यह एक नज़र में देखने देता है। डैशबोर्ड **आपके पूरे संगठन में साझा** किए जाते हैं; हर कोई `dashboards:read` के साथ एक ही सेट देखता है। -प्रत्येक dashboard pins करता है: +प्रत्येक डैशबोर्ड पिन: -- **Filters**: sessions page के समान controls: environment, status, agent, एक rolling time window, और score-range filters (`key:min..max`)। -- **एक display configuration**: कौन से score keys feature करें, green/amber/red health thresholds, कौन से panels दिखाएं, और latest evaluation per session को collapse करना है या नहीं। +- **फ़िल्टर**: सेशन पृष्ठ के समान नियंत्रण: पर्यावरण, स्थिति, एजेंट, एक रोलिंग समय विंडो, और स्कोर-रेंज फ़िल्टर (`key:min..max`)। +- **एक प्रदर्शन कॉन्फ़िगरेशन**: किस स्कोर कुंजी को दिखाना है, हरे/एम्बर/लाल स्वास्थ्य सीमा, कौन से पैनल दिखाएं, और क्या सेशन प्रति सबसे हाल के मूल्यांकन को संक्षिप्त करें। -प्रत्येक card matching sessions की संख्या दिखाता है, एक done/error/timeout breakdown, प्रत्येक featured score का average, और एक छोटा trend sparkline। एक dashboard को open करने से full-size panels दिखते हैं; **"open in sessions"** आपको sessions page में drop करता है उसी slice के लिए pre-filtered। Metrics को server-side पर पूरे matching set पर compute किया जाता है (`GET /evaluations/aggregate` के माध्यम से), इसलिए numbers exact हैं rather than sampled। +प्रत्येक कार्ड मिलान सेशन की संख्या, एक done/error/timeout ब्रेकडाउन, प्रत्येक विशेष स्कोर का औसत, और एक छोटी trend sparkline दिखाता है। एक डैशबोर्ड खोलने से पूर्ण आकार पैनल दिखते हैं; **"सेशन में खोलें"** आपको उस स्लाइस के लिए प्री-फ़िल्टर किए गए सेशन पृष्ठ में डालता है। मेट्रिक्स को सर्वर-पक्ष पूरे मिलान सेट पर (`GET /evaluations/aggregate` के माध्यम से) गणना की जाती है, इसलिए संख्याएं नमूना किए गए के बजाय सटीक होती हैं। -![एक eval-health dashboard जिसमें evaluator dimension per average-score bars, एक tool ok-vs-error breakdown, top tools, और एक events-per-hour trend है](/agenteye/images/dashboard-quality.png) +![औसत-स्कोर बार प्रति मूल्यांकनकर्ता आयाम, एक उपकरण ok-vs-error ब्रेकडाउन, शीर्ष उपकरण, और एक घटना-प्रति-घंटा प्रवृत्ति के साथ eval-स्वास्थ्य डैशबोर्ड](/agenteye/images/dashboard-quality.png) -**Permissions:** viewing के लिए `dashboards:read` और `evaluations:read` दोनों चाहिए; creating और editing के लिए `dashboards:write` चाहिए; deleting के लिए `dashboards:delete` चाहिए। Bootstrap admin को automatically ये सभी मिलते हैं। +**अनुमतियां:** देखना दोनों `dashboards:read` और `evaluations:read` की आवश्यकता है; बनाना और संपादित करना `dashboards:write` की आवश्यकता है; हटाना `dashboards:delete` की आवश्यकता है। बूटस्ट्रैप व्यवस्थापक स्वचालित रूप से सभी को प्राप्त करता है। --- -## Troubleshooting +## समस्या निवारण -**Sessions exist लेकिन कोई evaluations create नहीं हो रहे।** Confirm करें कि `EVALUATOR_ENDPOINT` server process पर set है, कि server और evaluator same `EVALUATOR_TOKEN` value share करते हैं, और कि evaluator का `/health` endpoint server से reachable है। `EVALUATOR_ENDPOINT` unset होने पर pipeline एक no-op है। +**सेशन मौजूद हैं लेकिन कोई मूल्यांकन नहीं बनाए जाते।** पुष्टि करें कि `EVALUATOR_ENDPOINT` सर्वर प्रक्रिया पर सेट है, कि सर्वर और मूल्यांकनकर्ता समान `EVALUATOR_TOKEN` मान साझा करते हैं, और कि मूल्यांकनकर्ता का `/health` एंडपॉइंट सर्वर से पहुंचने योग्य है। `EVALUATOR_ENDPOINT` अनसेट होने पर पाइपलाइन एक no-op है। -**In-flight evaluations pile up होते हैं।** `GET /evaluation-jobs` को query करें in-flight queue को देखने के लिए। प्रत्येक row पर `attempt_count`, `next_attempt_at`, और `last_error` को inspect करें। Common causes: evaluator सेवा unreachable या 5xx return कर रही है (backoff के साथ retry), गलत `EVALUATOR_TOKEN` (401 terminal है), या एक async evaluator जो `pending` को indefinitely return करता है (नीचे देखें)। +**उड़ान में मूल्यांकन ढेर हो जाते हैं।** `GET /evaluation-jobs` को क्वेरी करने के लिए उड़ान में कतार देखें। प्रत्येक पंक्ति पर `attempt_count`, `next_attempt_at` और `last_error` का निरीक्षण करें। सामान्य कारण: मूल्यांकनकर्ता सेवा अनुपलब्ध या 5xx लौटा रहा है (बैकऑफ के साथ पुनः प्रयास किया जाता है), गलत `EVALUATOR_TOKEN` (401 टर्मिनल है), या एक अनुकूलित मूल्यांकनकर्ता जो अनिश्चित काल के लिए `pending` लौटाता है (नीचे देखें)। -**Sessions completed लेकिन कोई terminal evaluation नहीं।** `GET /evaluation-jobs?status=polling` को query करें; result अभी भी in flight हो सकता है। यदि एक job `pending` में stuck है, तो server को evaluator तक पहुंचने में trouble है; check करें कि evaluator up है और कि `EVALUATOR_TOKEN` matches है। +**सेशन पूर्ण लेकिन कोई टर्मिनल मूल्यांकन नहीं।** `GET /evaluation-jobs?status=polling` को क्वेरी करें; परिणाम अभी भी उड़ान में हो सकता है। यदि कोई कार्य `pending` में फंसा हुआ है, तो सर्वर को मूल्यांकनकर्ता तक पहुंचने में परेशानी हो रही है; पुष्टि करें कि मूल्यांकनकर्ता ऊपर है और `EVALUATOR_TOKEN` मेल खाता है। -**`HTTP 401 from evaluator: invalid bearer token`।** Server पर `EVALUATOR_TOKEN` evaluator सेवा को configure किए गए value से match नहीं करता। उन्हें identical होना चाहिए। +**`HTTP 401 from evaluator: invalid bearer token`।** सर्वर पर `EVALUATOR_TOKEN` मूल्यांकनकर्ता सेवा के साथ कॉन्फ़िगर किए गए मान से मेल नहीं खाता। उन्हें समान होना चाहिए। -**Async evaluator `pending` को forever return करता है।** Server `GET /evaluate/{job_id}` को तब तक poll करता है जब तक evaluator `done` या `error` return नहीं करता, या जब तक `EVALUATOR_MAX_POLL_DURATION_SECS` (default 1 h) elapse नहीं हो। Cap के बाद evaluation को `timeout` के रूप में record किया जाता है और in-flight queue से remove किया जाता है। यदि आपका evaluator legitimate रूप से default से लंबे समय की आवश्यकता है तो `EVALUATOR_MAX_POLL_DURATION_SECS` को raise करें। +**अनुकूलित मूल्यांकनकर्ता अनिश्चित काल के लिए `pending` लौटाता है।** सर्वर `GET /evaluate/{job_id}` को तब तक पोल करता है जब तक मूल्यांकनकर्ता `done` या `error` लौटाता है, या जब तक `EVALUATOR_MAX_POLL_DURATION_SECS` (डिफ़ॉल्ट 1 h) समाप्त हो जाता है। कैप के बाद मूल्यांकन `timeout` के रूप में दर्ज किया जाता है और उड़ान में कतार से हटाया जाता है। यदि आपका मूल्यांकनकर्ता वास्तव में डिफ़ॉल्ट से अधिक समय की आवश्यकता है तो `EVALUATOR_MAX_POLL_DURATION_SECS` को बढ़ाएं। --- ## अगले कदम -- [Evaluator agent skill](/hi/agenteye/evaluator-skill): एक coding agent को real sessions के विरुद्ध आपके dimensions को design करने और यह सेवा build करने दें। -- [Python SDK](/hi/agenteye/python-sdk): `agent_end` events emit करें जो scoring को trigger करते हैं। -- [API keys](/hi/agenteye/api-keys): the `evaluations:read` और `evaluations:trigger` permissions। -- [Audits](/hi/agenteye/audits): Observability का अन्य automated quality feature, policy-based review के लिए। \ No newline at end of file +- [मूल्यांकनकर्ता एजेंट कौशल](/hi/agenteye/evaluator-skill): एक कोडिंग एजेंट को अपने आयामों को वास्तविक सेशन के विरुद्ध डिज़ाइन करने और यह सेवा आपके लिए बनाने दें। +- [Python SDK](/hi/agenteye/python-sdk): `agent_end` इवेंट्स उत्सर्जित करें जो स्कोरिंग को ट्रिगर करते हैं। +- [API कुंजियां](/hi/agenteye/api-keys): `evaluations:read` और `evaluations:trigger` अनुमतियां। +- [ऑडिट्स](/hi/agenteye/audits): Observability की अन्य स्वचालित गुणवत्ता सुविधा, नीति-आधारित समीक्षा के लिए। \ No newline at end of file diff --git a/docs/hi/agenteye/evaluations.mdx b/docs/hi/agenteye/evaluations.mdx index 43a02d05..302709f0 100644 --- a/docs/hi/agenteye/evaluations.mdx +++ b/docs/hi/agenteye/evaluations.mdx @@ -1,51 +1,51 @@ --- title: "मूल्यांकन" -description: "गुणवत्ता की समस्याएं अब आपको मिलती हैं, इसके बजाय कि आप किसी उपयोगकर्ता की शिकायत में इनके बारे में सुनें।" +description: "गुणवत्ता की समस्याएँ अब आपको मिलती हैं, न कि उपयोगकर्ता की शिकायत के माध्यम से।" --- -गुणवत्ता की समस्याएं अब आपको मिलती हैं, इसके बजाय कि आप किसी उपयोगकर्ता की शिकायत में इनके बारे में सुनें। अपनी स्कोरिंग सेवा को एक बार कनेक्ट करें और Failproof AI Observability हर पूरी हुई रन को स्वचालित रूप से ग्रेड करता है, इसलिए सहायकता में गिरावट या मतिभ्रम में वृद्धि अपने आप दिखाई देती है, इससे पहले कि कोई ग्राहक इसे महसूस करे। +गुणवत्ता की समस्याएँ अब आपको मिलती हैं, न कि उपयोगकर्ता की शिकायत के माध्यम से। अपनी स्कोरिंग सेवा को एक बार कनेक्ट करें और Failproof AI Observability हर पूरी दौड़ को स्वचालित रूप से ग्रेड करता है, इसलिए सहायता में गिरावट या मतिभ्रम में वृद्धि स्वयं दिखाई देती है, इससे पहले कि कोई ग्राहक इसे महसूस करे। -![सत्र ग्रिड एक स्कोर कॉलम के साथ: प्रत्येक रन एक मूल्यांकन स्थिति पिल और रंग-कोडित सहायकता, तथ्यात्मकता, और उपकरण-दक्षता बैज ले जाता है](/agenteye/images/sessions-list.png) +![सेशन ग्रिड एक स्कोर कॉलम के साथ: प्रत्येक दौड़ एक मूल्यांकन स्थिति पिल और रंग-कोडित सहायता, तथ्यात्मकता, और उपकरण-दक्षता बैज ले जाती है](/agenteye/images/sessions-list.png) -*सत्र ग्रिड पर हर रन अपने स्कोर ले जाता है; लाल, नारंगी, और हरे बैज कमजोर रनों को एक भी प्रतिलेख खोले बिना ही सामने ला देते हैं।* +*सेशन ग्रिड पर हर दौड़ अपने स्कोर के साथ आती है; लाल, एम्बर, और हरे बैज कमजोर दौड़ों को बिना एक भी ट्रांसक्रिप्ट खोले ही उभार देते हैं।* -## रनों को हाथ से नमूना लेना बंद करें +## हाथ से दौड़ों का नमूना लेना बंद करें -आप कुछ रनों को देखा-भाली के आधार पर जांचते थे और बाकी सब ठीक हों यह आशा करते थे। अब हर पूरा किया गया सत्र समाप्त होते ही स्कोर किया जाता है, उन आयामों पर जिनकी आपको परवाह है: सहायकता, उपकरण दक्षता, तथ्यात्मकता, सुरक्षा, जो कुछ भी आपकी गुणवत्ता की मानक है। आप स्कोर कुंजियों को परिभाषित करते हैं; Failproof AI Observability जो कुछ भी आपका मूल्यांकनकर्ता वापस भेजता है उसे संग्रहीत, प्रवृत्ति और प्रदर्शित करता है। कोई भी रन बिना स्कोर किए नहीं छूटता है, और आप किसी प्रतिगमन के बारे में सहायता टिकट से सीखना बंद कर देते हैं। +आप पहले कुछ दौड़ों की जांच करते थे और बाकी को ठीक होने की आशा करते थे। अब हर पूरा सेशन समाप्त होने के तुरंत बाद स्कोर किया जाता है, उन आयामों पर जिनकी आप परवाह करते हैं: सहायता, उपकरण दक्षता, तथ्यात्मकता, सुरक्षा, जो कुछ भी आपकी गुणवत्ता की पट्टी है। आप स्कोर कुंजियाँ परिभाषित करते हैं; Failproof AI Observability जो कुछ भी आपका मूल्यांकनकर्ता भेजता है उसे संग्रहीत, ट्रेंड करता है, और प्रदर्शित करता है। कोई भी दौड़ बिना स्कोर किए नहीं छूटती, और आप सहायता टिकट से प्रतिगमन के बारे में सीखना बंद करते हैं। -स्कोर सत्र ग्रिड पर **`//sessions`** (साइडबार → *observe* → *sessions*) पर सवार होते हैं, प्रति पंक्ति एक बैज क्लस्टर। केवल वे रन चाहते हैं जो कम हो गईं? स्कोर रेंज के आधार पर ग्रिड को फ़िल्टर करें, कहें 0.5 से नीचे सहायकता, और बिल्कुल पढ़ने योग्य रन निकालें। स्कोर देखने के लिए `evaluations:read` अनुमति की आवश्यकता है। +स्कोर **`//sessions`** पर सेशन ग्रिड के साथ चलते हैं (साइडबार → *observe* → *sessions*), प्रति पंक्ति एक बैज क्लस्टर। केवल जो दौड़ें कम पड़ीं? ग्रिड को स्कोर रेंज के आधार पर फ़िल्टर करें, कहते हैं 0.5 से नीचे सहायता, और बिल्कुल उन दौड़ों को खींचें जो पढ़ने लायक हैं। स्कोर देखने के लिए `evaluations:read` अनुमति की आवश्यकता है। -## देखें कि एक रन को कम स्कोर क्यों मिला +## देखें कि एक दौड़ को कम स्कोर क्यों मिला -एक संख्या आपको बताती है कि एक रन कमजोर था; सत्र पृष्ठ आपको बताता है कि क्यों। कोई भी रन खोलें और दाईं ओर की रेल सुर्खी सारांश के साथ शुरू होती है, फिर प्रत्येक आयाम के लिए एक बार दिखाती है और आपके मूल्यांकनकर्ता का अपना तर्क प्रत्येक के तहत दिखाती है, इसलिए आप "इसे तथ्यात्मकता पर 0.4 मिला" से सेकंड में उस सटीक दावे तक जाते हैं जो यह गलत हो गया। +एक संख्या बताती है कि एक दौड़ कमजोर थी; सेशन पृष्ठ बताता है कि क्यों। कोई भी दौड़ खोलें और दाहिनी रेल शीर्षक सारांश के साथ शुरू होती है, फिर प्रति आयाम एक बार दिखाती है जिसमें आपके मूल्यांकनकर्ता का अपना तर्क प्रत्येक के अंतर्गत होता है, इसलिए आप "इसे तथ्यात्मकता पर 0.4 मिला" से सेकंड में वास्तविक दावे तक पहुंचते हैं जो गलत था। -![एक सत्र की दाईं ओर की रेल: शीर्ष पर मूल्यांकन सारांश, फिर प्रति-आयाम स्कोर बार प्रत्येक के साथ तर्क की एक पंक्ति, पूरी घटना समयरेखा के बगल में](/agenteye/images/session-detail.png) +![एक सेशन की दाहिनी रेल: शीर्ष पर मूल्यांकन सारांश, फिर प्रति-आयाम स्कोर बार प्रत्येक एक पंक्ति तर्क के साथ, पूरी घटना समयरेखा के बगल में](/agenteye/images/session-detail.png) -*सत्र विस्तार दृश्य: सारांश, प्रति-आयाम स्कोर बार, और प्रत्येक स्कोर के पीछे तर्क, रन की घटना समयरेखा के बगल में।* +*सेशन विस्तार दृश्य: सारांश, प्रति-आयाम स्कोर बार, और प्रत्येक स्कोर के पीछे का तर्क, दौड़ की घटना समयरेखा के ठीक बगल में।* -एक तेज मूल्यांकनकर्ता भेजा गया, या कोई रन देख रहे हैं जो स्कोर किए जाने से पहले क्रैश हो गई? एक **re-evaluate** बटन (`evaluations:trigger` द्वारा गेटेड) सत्र को जगह में फिर से स्कोर करता है और ताजा परिणाम को इसकी समयरेखा में जोड़ता है, इसलिए पहले के स्कोर इतिहास के रूप में दिखाई देते हैं। आप इसे **`//sessions/`** पर पाएंगे। +एक तीव्र मूल्यांकनकर्ता भेजा गया, या एक ऐसी दौड़ को देख रहे हैं जो स्कोर किए जाने से पहले क्रैश हुई? एक **re-evaluate** बटन (`evaluations:trigger` द्वारा गेट किया गया) सेशन को स्थान पर फिर से स्कोर करता है और इसकी समयरेखा में ताज़ा परिणाम जोड़ता है, इसलिए पहले के स्कोर इतिहास के रूप में दृश्यमान रहते हैं। आप इसे **`//sessions/`** पर पाएंगे। ## पूरे बेड़े में गुणवत्ता प्रवृत्ति देखें -एक रन कम स्कोरिंग शोर है; पूरे समूह का स्लाइड करना एक संकेत है। सहेजे गए डैशबोर्ड आपके स्कोर को एक प्रवृत्ति में बदलते हैं जो आप एक नज़र में देख सकते हैं: इस हफ्ते की औसत सहायकता पिछले हफ्ते के विरुद्ध, प्रति एजेंट, प्रति वातावरण। +एक दौड़ कम स्कोर करना शोर है; पूरे समूह का स्लाइड करना एक संकेत है। सहेजे गए डैशबोर्ड आपके स्कोर को एक ऐसी प्रवृत्ति में बदलते हैं जिसे आप एक नज़र में देख सकते हैं: इस सप्ताह की औसत सहायता बनाम पिछली, प्रति एजेंट, प्रति पर्यावरण। -![एक गुणवत्ता डैशबोर्ड: मूल्यांकनकर्ता आयाम प्रति औसत-स्कोर बार समय के साथ एक प्रवृत्ति के साथ](/agenteye/images/dashboard-quality.png) +![एक गुणवत्ता डैशबोर्ड: मूल्यांकनकर्ता आयाम के आधार पर औसत-स्कोर बार समय के साथ एक प्रवृत्ति के साथ](/agenteye/images/dashboard-quality.png) -*एक सहेजा गया गुणवत्ता डैशबोर्ड स्कोर कुंजियों को प्रवृत्ति देता है जिन्हें आप प्रदर्शित करते हैं, इसलिए एक धीमी बहाव स्पष्ट है यह एक घटना बनने से बहुत पहले।* +*एक सहेजा गया गुणवत्ता डैशबोर्ड स्कोर कुंजियों को ट्रेंड करता है जिन्हें आप दिखाते हैं, इसलिए एक धीमी बहाव स्पष्ट है इससे बहुत पहले कि यह एक घटना बन जाए।* -डैशबोर्ड **`//dashboards`** (साइडबार → *analyze* → *dashboards*) पर रहते हैं, आपके पूरे संगठन में साझा किए जाते हैं, और प्रत्येक कार्ड मिलान वाले सत्रों को रोल अप करता है: कितने, प्रत्येक प्रदर्शित स्कोर का औसत, और एक प्रवृत्ति स्पार्कलाइन। "सत्र में खोलें" आपको सीधे किसी भी संख्या के पीछे पूर्व-फ़िल्टर की गई रनों में ले जाता है। देखने के लिए `dashboards:read` प्लस `evaluations:read` की आवश्यकता है। +डैशबोर्ड **`//dashboards`** पर रहते हैं (साइडबार → *analyze* → *dashboards*), आपके पूरे संगठन में साझा किए जाते हैं, और प्रत्येक कार्ड मेल खाने वाले सेशन को एकत्र करता है: कितने, प्रत्येक प्रदर्शित स्कोर का औसत, और एक प्रवृत्ति स्पार्कलाइन। "सेशन में खोलें" आपको बिल्कुल किसी भी संख्या के पीछे प्री-फ़िल्टर्ड दौड़ों में ले जाता है। देखने के लिए `dashboards:read` साथ ही `evaluations:read` की आवश्यकता है। -## एक बार एक मूल्यांकनकर्ता कनेक्ट करें +## एक मूल्यांकनकर्ता एक बार कनेक्ट करें -स्कोरिंग ऑप्ट-इन है और तब तक बिल्कुल बंद रहती है जब तक आप Failproof AI Observability को एक स्कोरर की ओर इंगित नहीं करते। आप एक छोटी सी HTTP सेवा खड़ी करते हैं (Observability एक कार्यशील संदर्भ भेजता है जिसे आप कॉपी कर सकते हैं), अपने सर्वर पर दो मान सेट करते हैं, और तब से हर रन आपके लिए स्कोर किया जाता है। पूरी मार्गदर्शिका, स्कोरिंग अनुबंध, और SDK गहन गाइड में रहते हैं। +स्कोरिंग ऑप्ट-इन है और जब तक आप Failproof AI Observability को एक स्कोरर की ओर संकेत नहीं करते तब तक पूरी तरह से बंद रहती है। आप एक छोटी HTTP सेवा स्थापित करते हैं (Observability एक कार्यशील संदर्भ भेजता है जिसे आप कॉपी कर सकते हैं), अपने सर्वर पर दो मान सेट करते हैं, और उस समय से हर दौड़ आपके लिए स्कोर की जाती है। पूरी चलना, स्कोरिंग अनुबंध, और SDK गहरी गाइड में रहते हैं। -यह सुनिश्चित नहीं हैं कि कौन से आयाम पहली जगह में स्कोर करने योग्य हैं? [evaluator agent skill](/hi/agenteye/evaluator-skill) में आपके कोडिंग एजेंट को अपने स्वयं के सत्रों के विरुद्ध इसे काम करना पड़ता है, फिर सेवा बनाएं और तैनात करें। +निश्चित नहीं कि पहली जगह में कौन से आयाम स्कोर करने लायक हैं? [evaluator agent skill](/hi/agenteye/evaluator-skill) के पास आपके अपने सेशन के खिलाफ वह काम करने के लिए आपके कोडिंग एजेंट है, फिर सेवा बनाएं और तैनात करें। ## संबंधित - [Evaluation suite](/hi/agenteye/evaluation-suite): अपने मूल्यांकनकर्ता को कनेक्ट करें, स्कोरिंग अनुबंध, और SDK। - [Evaluator agent skill](/hi/agenteye/evaluator-skill): एक कोडिंग एजेंट को अपने स्कोर आयाम चुनने और मूल्यांकनकर्ता बनाने दें। -- [Sessions](/hi/agenteye/sessions): रन-दर-रन ग्रिड जहां स्कोर दिखाई देते हैं। -- [Dashboards](/hi/agenteye/dashboards): अपने संगठन में गुणवत्ता प्रवृत्ति को सहेजें और साझा करें। -- [Audits](/hi/agenteye/audits): Observability की अन्य स्वचालित गुणवत्ता सुविधा, क्रॉस-सत्र जांचों के लिए। \ No newline at end of file +- [Sessions](/hi/agenteye/sessions): दौड़-दर-दौड़ ग्रिड जहां स्कोर दिखाई देते हैं। +- [Dashboards](/hi/agenteye/dashboards): अपने संगठन में गुणवत्ता प्रवृत्तियों को सहेजें और साझा करें। +- [Audits](/hi/agenteye/audits): Observability की अन्य स्वचालित गुणवत्ता विशेषता, क्रॉस-सेशन जांच के लिए। \ No newline at end of file diff --git a/docs/hi/agenteye/evaluator-skill.mdx b/docs/hi/agenteye/evaluator-skill.mdx index 8192b1d2..4d135f87 100644 --- a/docs/hi/agenteye/evaluator-skill.mdx +++ b/docs/hi/agenteye/evaluator-skill.mdx @@ -1,171 +1,166 @@ --- ---- title: "Failproof AI Observability Evaluator Agent Skill" -description: "Go from \"I think our agent is sometimes bad\" to a deployed scoring service, with your coding agent doing both the deciding and the building." +description: "\"मुझे लगता है कि हमारा agent कभी-कभी खराब है\" से लेकर एक deployed scoring service तक जाएँ, जहाँ आपका coding agent फैसला लेने और बनाने दोनों काम करता है।" --- -*"मुझे लगता है हमारा agent कभी-कभी खराब है"* से लेकर deployed scoring service तक जाएं, आपके coding agent के साथ both the deciding और building दोनों कर रहे हों। **Failproof AI Observability evaluator skill** (`agenteye-evaluator`) एक *Agent Skill* है: instructions का एक छोटा folder जो एक coding agent जैसे Claude Code या Codex on demand load करता है। यह agent को सिखाता है कि कौन से quality dimensions आपके *agent* के लिए tracking के लायक हैं, फिर [evaluator service](/hi/agenteye/evaluation-suite) को write, test, और deploy करते हैं जो उन्हें score करता है। +*"मुझे लगता है कि हमारा agent कभी-कभी खराब है"* से लेकर एक deployed scoring service तक जाएँ, जहाँ आपका coding agent फैसला लेने और बनाने दोनों काम करता है। **Failproof AI Observability evaluator skill** (`agenteye-evaluator`) एक *Agent Skill* है: निर्देशों का एक छोटा फोल्डर जिसे Claude Code या Codex जैसा coding agent आवश्यकतानुसार लोड करता है। यह agent को सिखाता है कि आपके *agent* के लिए कौन से quality dimensions ट्रैक करने लायक हैं, और फिर [evaluator service](/hi/agenteye/evaluation-suite) लिखें, परीक्षण करें और deploy करें जो उन्हें स्कोर करता है। -यह एक **hosted scorer नहीं है**, न ही एक registry जहां आप upload करते हैं, न ही एक plugin system। आपका evaluator आपका अपना HTTP service रहता है आपके अपने infrastructure पर, बिल्कुल जैसा [Evaluation suite](/hi/agenteye/evaluation-suite) guide में described है। skill केवल आपके agent को इसे अच्छे तरीके से बनाना सिखाती है, इसलिए जो कुछ भी यह करता है, आप खुद कर सकते हैं same code लिखकर। +यह एक hosted scorer, एक registry जिसमें आप अपलोड करते हों, या एक plugin system **नहीं** है। आपका evaluator आपका अपना HTTP service रहता है, आपके अपने infrastructure पर, बिल्कुल जैसा [Evaluation suite](/hi/agenteye/evaluation-suite) गाइड में वर्णित है। यह skill केवल आपके agent को इसे अच्छी तरह से बनाना सिखाता है, इसलिए जो कुछ भी यह करता है, आप खुद यही कोड लिखकर कर सकते हैं। --- -## कठिन हिस्सा है कि क्या score करें यह तय करना +## कठिन हिस्सा यह तय करना है कि क्या स्कोर करना है -SDK surface छोटा है — एक decorator और two models — और एक agent इसे [contract](/hi/agenteye/evaluation-suite#http-contract) से ही लिख सकता है। यहीं से evaluators fail नहीं होते। वे fail होते हैं क्योंकि वे गलत चीज़ को score करते हैं, और एक evaluator जो गलत चीज़ को score करता है वह कोई भी नहीं होने से बदतर है: यह एक dashboard produce करता है जिसे सब ignore करना सीख जाते हैं। +SDK surface छोटा है — एक decorator और दो models — और एक agent इसे [contract](/hi/agenteye/evaluation-suite#http-contract) से ही लिख सकता है। यहीं evaluators असफल नहीं होते। वे असफल होते हैं क्योंकि वे गलत चीज को स्कोर करते हैं, और एक evaluator जो गलत चीज स्कोर करता है वह किसी से भी बदतर है: यह एक dashboard बनाता है जिसे सब लोग अनदेखा करना सीख जाते हैं। -तो skill का ज़्यादातर हिस्सा code exist करने से पहले का है। इसमें agent आपसे interview करता है (*"एक run describe करें जो अच्छा गया; अब एक जो बुरा गया"*), फिर आपके real sessions को [`agenteye` CLI](/hi/agenteye/cli) के through pull करता है और उन्हें end to end पढ़ता है। ये दोनों halves आमतौर पर disagree करते हैं, और gap ही वह point है: जो आप measure करना चाहते हैं बनाम जो आपके transcripts actually support कर सकते हैं। एक dimension तभी survive करता है जब वह events से **computable** हो और **discriminating** हो — अगर यह आपके good run और bad run दोनों पर 0.9 score करता है, तो यह कुछ नहीं सिखाता और cut हो जाता है। +इसलिए यह skill का अधिकांश हिस्सा कोई कोड लिखने से पहले की बात है। यह agent को आपसे interview करवाता है (*"एक ऐसा run describe करें जो अच्छा हुआ; अब एक जो बुरा हुआ"*), फिर [`agenteye` CLI](/hi/agenteye/cli) के जरिए आपके असली sessions को pull करता है और उन्हें अंत तक पढ़ता है। ये दोनों हिस्से आमतौर पर असहमत होते हैं, और यह gap ही महत्वपूर्ण है: आप क्या मापना चाहते हैं बनाम आपके transcripts वास्तव में क्या समर्थन कर सकते हैं। एक dimension तभी बचता है अगर यह events से **computable** हो और **discriminating** हो — अगर यह आपके अच्छे और बुरे दोनों runs पर 0.9 स्कोर करता है, तो यह कुछ नहीं सिखाता और काटा जाता है। -जो वापस आता है वह 2-4 dimensions का एक proposal है reasoning के साथ, जिसे आप कोई भी line लिखने से पहले sign off करते हैं। +जो वापस आता है वह 2-4 dimensions का एक प्रस्ताव है, जिसमें reasoning जुड़ी हो, आपके approve करने के लिए कोई लाइन लिखने से पहले। ```mermaid flowchart TD - YOU["you: 'I want evals for my support bot'"] --> AGENT["coding agent (Claude Code / Codex)
loads the agenteye-evaluator skill"] - AGENT -->|"interview: what does good vs bad look like?"| YOU - AGENT -->|"agenteye --json sessions / events"| DATA["your real sessions
what actually happens"] - DATA --> DIMS["2-4 dimensions, you sign off"] - DIMS --> SVC["your evaluator service
agenteye-evaluator SDK"] - SVC --> SCORES["scores land in the dashboard
and agenteye evals"] + YOU["आप: 'मुझे अपने support bot के लिए evals चाहिए'"] --> AGENT["coding agent (Claude Code / Codex)
agenteye-evaluator skill लोड करता है"] + AGENT -->|"interview: अच्छा बनाम बुरा कैसा दिखता है?"| YOU + AGENT -->|"agenteye --json sessions / events"| DATA["आपके असली sessions
जो वास्तव में होता है"] + DATA --> DIMS["2-4 dimensions, आप approve करें"] + DIMS --> SVC["आपका evaluator service
agenteye-evaluator SDK"] + SVC --> SCORES["scores dashboard में
और agenteye evals में आते हैं"] ``` --- -## यह दूसरे evaluation pieces से कैसे संबंधित है +## यह अन्य evaluation pieces से कैसे संबंधित है -चार docs scoring को cover करते हैं, और वे order में एक-दूसरे को hand off करते हैं: +चार docs scoring को cover करते हैं, और वे क्रम में एक-दूसरे को सौंपते हैं: -| Page | यह क्या है | इसे तब use करें जब | +| पृष्ठ | यह क्या है | यब पहुंचें जब | |---|---|---| -| **[Evaluations](/hi/agenteye/evaluations)** | Feature: sessions grid पर scores, dashboards, re-evaluate | आप जानना चाहते हैं कि automatic scoring आपको क्या देता है | -| **[Evaluation suite](/hi/agenteye/evaluation-suite)** | HTTP contract, SDK, server env vars | आप evaluator को खुद implement या debug कर रहे हैं | -| **Evaluator skill** (यह doc) | Scorer को design *और* build करने का एक natural-language front door | आप "I want evals" से एक running service तक जाना चाहते हैं | -| **[CLI skill](/hi/agenteye/cli-skill)** | `agenteye` CLI का एक natural-language front door | आप scores को पढ़ना चाहते हैं जो आपके पास पहले से हैं | -| **[Python SDK skill](/hi/agenteye/python-sdk-skill)** | अपने agent को instrument करने का एक natural-language front door | आपका agent sessions emit नहीं कर रहा है — score करने के लिए कुछ नहीं है | +| **[Evaluations](/hi/agenteye/evaluations)** | यह feature: sessions grid पर scores, dashboards, re-evaluate | आप जानना चाहते हैं कि automatic scoring आपको क्या देता है | +| **[Evaluation suite](/hi/agenteye/evaluation-suite)** | HTTP contract, SDK, server env vars | आप स्वयं evaluator को implement या debug कर रहे हैं | +| **Evaluator skill** (यह doc) | scorer को design *और* build करने पर एक natural-language front door | आप "मुझे evals चाहिए" से एक running service तक जाना चाहते हैं | +| **[CLI skill](/hi/agenteye/cli-skill)** | `agenteye` CLI पर एक natural-language front door | आप पहले से मौजूद scores को *पढ़ना* चाहते हैं | +| **[Python SDK skill](/hi/agenteye/python-sdk-skill)** | अपने agent को instrument करने पर एक natural-language front door | आपका agent अभी sessions emit नहीं कर रहा है — स्कोर करने के लिए कुछ नहीं है | -### CLI skill के मुकाबले: build बनाम read +### CLI skill बनाम: build बनाम read -दोनों skills intentionally non-overlapping हैं, और दोनों को install करना normal setup है — agent यह तय करता है कि आप क्या पूछते हैं इसके आधार पर: +दोनों skills जानबूझकर non-overlapping हैं, और दोनों को install करना सामान्य setup है — agent आपसे जो पूछते हैं उसके आधार पर उनमें से चुनता है: -- **`agenteye-evaluator`** (यह doc) उस चीज़ को build करता है जो scores *produce* करता है। इसका job तब खत्म होता है जब scores पहली बार land करते हैं। -- **[`agenteye-cli`](/hi/agenteye/cli-skill)** scores को पढ़ता है जो पहले से exist करते हैं (`agenteye evals`)। *"क्या quality इस हफ्ते drop हुई?"* इसका सवाल है, इस skill का नहीं। +- **`agenteye-evaluator`** (यह doc) उस चीज को build करता है जो scores *produce* करता है। इसका काम तब समाप्त होता है जब scores पहली बार land हों। +- **[`agenteye-cli`](/hi/agenteye/cli-skill)** वह scores को read करता है जो पहले से मौजूद हैं (`agenteye evals`)। *"क्या इस हफ्ते quality गिरी?"* इसका सवाल है, इस skill का नहीं। --- ## Prerequisites -1. **`agenteye` CLI installed और logged in** (`pipx install agenteye`, फिर `agenteye login`)। Skill इसे दो बार use करती है: real sessions को pull करने के लिए जिसके against यह design करती है, और यह confirm करने के लिए कि आपके scores end में land हुए। आपके login को `events:read` की ज़रूरत है, प्लस उस final check के लिए `evaluations:read`। CLI skill की तरह, यह **नहीं** कर सकता emailed one-time-code login को complete करना आपके लिए। -2. **Evaluator के लिए कहीं रहने के लिए जगह।** यह एक image में build हो जाता है और एक long-running service के रूप में run होता है, तो इसे एक real repo की ज़रूरत है, scratch file नहीं। Evaluators अक्सर अपने अपने repo में रहते हैं, agent से अलग जिसे scored किया जा रहा है — skill एक existing को look करती है और नए को scaffold करने से पहले पूछती है। -3. **`agenteye-evaluator` SDK wheel** — अपने agent के `pip` commands type करना शुरू करने से पहले अगला section पढ़ें। +1. **`agenteye` CLI installed और logged in** (`pipx install agenteye`, फिर `agenteye login`)। यह skill इसे दो बार use करता है: असली sessions pull करने के लिए जिसके विरुद्ध यह design करता है, और अंत में आपके scores land करने की confirm करने के लिए। आपकी login को `events:read` चाहिए, साथ ही उस अंतिम check के लिए `evaluations:read`। CLI skill की तरह, यह emailed one-time-code login को आपके लिए complete **नहीं** कर सकता। +2. **Evaluator रहने के लिए कहीं।** यह एक image में build होता है और एक long-running service के रूप में run होता है, इसलिए इसे एक real repo की जरूरत है, scratch file नहीं। Evaluators अक्सर अपने स्वयं के repo में रहते हैं, स्कोर किए जा रहे agent से अलग — यह skill एक मौजूदा को खोजता है और नया scaffold करने से पहले पूछता है। +3. **`agenteye-evaluator` SDK wheel** — अगले section को read करें इससे पहले कि आपका agent `pip` commands टाइप करना शुरू करे। --- -## इसे कहां से प्राप्त करें +## यह कहाँ से प्राप्त करें -Skill Failproof AI के public skills collection में publish है: +यह skill Failproof AI के public skills collection में published है: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -Repository public है और skill को अपने credential की ज़रूरत नहीं है — यह केवल `agenteye` CLI को drive करता है session के साथ *जिसे* आप logged in थे, और *आपके* repo में code लिखता है। ध्यान दें कि यह अपने folder के रूप में ship होता है और `pipx install agenteye` package के inside **नहीं** है, तो इसे वहां न ढूंढें। +यह repository public है और skill को अपना कोई credential नहीं चाहिए — यह केवल `agenteye` CLI को उस session के साथ drive करता है जिसमें *आप* logged in हैं, और *आपके* repo में code लिखता है। ध्यान दें कि यह अपने folder के रूप में ships करता है और `pipx install agenteye` package के अंदर **नहीं** है, इसलिए वहाँ इसे न खोजें। ## Skill को install करना -सबसे तेज़ path [`skills`](https://skills.sh) CLI है, जो folder को fetch करता है और वहां drop करता है जहां आपका agent look करता है: +सबसे तेज़ path [`skills`](https://skills.sh) CLI है, जो folder को fetch करता है और उसे वहाँ drop करता है जहाँ आपका agent देखता है: ```bash -# Claude Code, यह project केवल +# Claude Code, केवल यह project npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code # हर project (installs to ~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy -# Codex इसकी जगह +# बजाय Codex के npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -फिर इसे किसी दूसरे skill की तरह manage करें: +फिर इसे किसी अन्य skill की तरह manage करें: ```bash -npx skills list -a claude-code # क्या installed है +npx skills list -a claude-code # क्या install है npx skills update agenteye-evaluator # latest version pull करें -npx skills remove agenteye-evaluator # इसे हटाएं +npx skills remove agenteye-evaluator # इसे remove करें ``` -हाथ से install करना पसंद हैं? एक Agent Skill सिर्फ एक folder है जिसमें `SKILL.md` है (plus optional references), तो इसे copy करना काम करता है: +हाथ से install करना पसंद करते हैं? एक Agent Skill केवल एक `SKILL.md` (साथ optional references) युक्त folder है, इसलिए इसे copy करना भी काम करता है: -- **Claude Code**: `agenteye-evaluator/` folder को `~/.claude/skills/` में रखें (हर project) या `/.claude/skills/` में (केवल वह repo)। Claude Code इसे auto-discover करता है — `/skills` list से verify करें, या बस evals के लिए पूछें। -- **Codex (OpenAI)**: Codex same `SKILL.md` को read करता है। Bundled `agents/openai.yaml` `allow_implicit_invocation: true` set करता है, तो Codex skill को auto-select करता है जब task match हो; अन्यथा इसे explicitly invoke करें `$agenteye-evaluator` के रूप में। +- **Claude Code**: `agenteye-evaluator/` folder को `~/.claude/skills/` (हर project) या `/.claude/skills/` (केवल वह repo) में रखें। Claude Code इसे auto-discover करता है — `/skills` list के साथ verify करें, या बस evals के लिए पूछें। +- **Codex (OpenAI)**: Codex वही `SKILL.md` read करता है। बंडल किया गया `agents/openai.yaml` `allow_implicit_invocation: true` set करता है, इसलिए Codex task से match होने पर skill को auto-select करता है; अन्यथा इसे explicitly as `$agenteye-evaluator` invoke करें। --- ## SDK public PyPI पर नहीं है -> **Warning:** Agent को SDK install करने देने से पहले यह पढ़ें। +> **Warning:** इसे एक agent को SDK install करने देने से पहले read करें। -Skill public है; जिस SDK को यह drive करता है वह नहीं है। `agenteye-evaluator` केवल एक private release artifact के रूप में ship होता है, और `agenteye` के विपरीत, name public PyPI पर **unclaimed** है — तो एक bare `pip install agenteye-evaluator` एक stranger के package को pull कर सकता है उस service में जो आपके production transcripts को read करता है। यह एक supply-chain problem है, typo नहीं। +यह skill public है; जो SDK यह drive करता है वह नहीं है। `agenteye-evaluator` केवल एक private release artifact के रूप में ships करता है, और `agenteye` के विपरीत, यह नाम public PyPI पर **unclaimed** है — इसलिए एक bare `pip install agenteye-evaluator` किसी अजनबी के package को उस service में pull कर सकता है जो आपके production transcripts को read करता है। यह एक typo नहीं, एक supply-chain समस्या है। -Skill यह जानता है और इसकी जगह एक install ladder down करता है, पहले rung पर रुकता है जो apply होता है: monorepo source अगर आप AgentEye repo के inside हैं, अन्यथा GitHub Releases से private release wheel (needs access), और अगर न ही कोई reachable है तो यह **रुकता है और आपको अपने Failproof AI contact से wheel पूछने के लिए बताता है** improvising करने की बजाय। +यह skill यह जानता है और एक install ladder के नीचे काम करता है, पहले rung पर रुकता है जो लागू होता है: monorepo source अगर आप AgentEye repo के अंदर हैं, अन्यथा GitHub Releases से private release wheel (access चाहिए), और अगर न कोई पहुंचा है तो यह **रुकता है और आपको अपने Failproof AI contact से wheel के लिए पूछने के लिए कहता है** बजाय improvise करने के। -तो अगर आपका agent public PyPI से bare `pip install agenteye-evaluator` propose करता है, वह flag है कि skill कभी load नहीं हुई। वहीं रुकें और check करें कि यह installed है। +तो अगर आपका agent public PyPI से bare `pip install agenteye-evaluator` propose करता है, यह बताता है कि skill कभी load नहीं हुई। वहाँ रुकें और check करें कि यह install है। --- -## आप इससे क्या पूछ सकते हैं +## आप क्या पूछ सकते हैं -एक real round-trip एक vague ask से शुरू होता है और code के साथ नहीं, signed-off design के साथ end होता है: +एक असली round-trip एक vague ask से शुरू होता है और code से नहीं, एक signed-off design के साथ समाप्त होता है: ```text -you ▸ मुझे हमारे support bot के लिए evals चाहिए। मुझे लगता है यह कभी-कभी - खराब है। +आप ▸ मुझे अपने support bot के लिए evals चाहिए। मुझे लगता है कि यह कभी-कभी खराब है। -agent ▸ कुछ लिखने से पहले: एक run describe करें जो अच्छा गया, +agent ▸ कुछ भी लिखने से पहले: एक ऐसा run describe करें जो अच्छा गया, और एक जो बुरा गया। -you ▸ अच्छा: यह docs से answer करता है। बुरा: यह stuff बनाता है, - या हार मानता है और कहता है "contact support"। +आप ▸ अच्छा: यह docs से answer देता है। बुरा: यह stuff बनाता है, + या हार मान लेता है और "contact support" कहता है। -agent ▸ Running: agenteye --json sessions --status error --since 7d - 5 sessions पढ़ रहे हैं, दो सहित जिन्हें आप bad कहेंगे। +agent ▸ चल रहा है: agenteye --json sessions --status error --since 7d + 5 sessions को read कर रहा हूँ, दो सहित जो आप बुरे कहेंगे। आपके शब्द factuality और deflection कहते हैं। Transcripts - deflection पर सहमत हैं (5 में से 2 support hand-off के साथ - end होते हैं, और यह model_response.content में plain है), - लेकिन factuality को ground truth की ज़रूरत है जो आपके - events carry नहीं करते। + deflection पर सहमत हैं (5 में से 2 एक support hand-off के साथ समाप्त होते हैं, + और यह model_response.content में स्पष्ट है), लेकिन factuality + को एक ground truth चाहिए जो आपके events carry नहीं करते हैं। - तो मैं तीन चीज़ें score करूंगा: - - deflection rules, cheap, आपके दोनों runs को अलग करता है + तो मैं तीन चीजें score करूँगा: + - deflection rules, सस्ता, आपके दोनों runs को अलग करता है - tool_efficiency rules, run-004 में retry loop को catch करता है - - groundedness LLM judge: क्या हर claim जो यह retrieved है - docs में है? + - groundedness LLM judge: क्या हर claim docs में है जो यह retrieve करता है? - "factuality" को ground truth की ज़रूरत होगी जो हमारे पास - नहीं है; groundedness सबसे करीबी चीज़ है जो आपके transcripts - actually support कर सकते हैं। ये तीनों names के साथ ठीक है? - बाद में rename करने से history split हो जाता है। + "factuality" को ground truth चाहिए जो हमारे पास नहीं है; groundedness + सबसे करीबी चीज है जो आपके transcripts वास्तव में support कर सकते हैं। + इन तीनों नामों से ठीक है? बाद में rename करने से history split होती है। -you ▸ हां +आप ▸ हाँ -agent ▸ इस repo में कोई evaluator नहीं। क्या मुझे यहां एक scaffold - करना चाहिए, या क्या आपके पास कहीं और एक है? +agent ▸ इस repo में कोई evaluator नहीं है। क्या मुझे यहाँ एक scaffold करना चाहिए, या आपके पास + कहीं और एक है? ``` -वहां से यह पहले rules-based dimensions लिखता है (free, instant, deterministic), उन्हें एक real captured session के against test करता है जिसमें empty और never-finished ones भी शामिल हैं जो naive evaluators को crash करते हैं, और केवल subjective dimension पर एक LLM judge के लिए पहुंचता है। यह [dispatcher की limits](/hi/agenteye/evaluation-suite#configuring-the-server) को जानता है — 30s request timeout और 8 concurrent calls deployment-wide — तो अगर judge reliably fit नहीं होगा, तो यह `JobPending` के साथ async जाता है न कि आपके judge को cancelled और retried होने देता है पांच बार पांच बार लागत पर। +वहाँ से यह rules-based dimensions को पहले लिखता है (मुफ़्त, तुरंत, deterministic), उन्हें एक असली captured session के विरुद्ध test करता है जिसमें empty और कभी-finished नहीं होने वाले शामिल हैं जो naive evaluators को crash करते हैं, और केवल subjective dimension पर एक LLM judge तक पहुंचता है। यह [dispatcher's limits](/hi/agenteye/evaluation-suite#configuring-the-server) जानता है — एक 30s request timeout और 8 concurrent calls deployment-wide — इसलिए अगर judge विश्वसनीय रूप से fit नहीं होगा, तो यह `JobPending` के साथ async जाता है बजाय आपके judge को cancelled और पाँच बार retry किया जाता है और पाँच गुना cost पर। -फिर यह deploy करता है, दो server env vars set करता है, और `agenteye --json evals --session-id ` से confirm करता है कि scores actually land हुए। Scores landing ही एकमात्र proof है। +फिर यह deploy करता है, दोनों server env vars set करता है, और `agenteye --json evals --session-id ` के साथ confirm करता है कि scores वास्तव में land हुए हैं। Scores landing ही एकमात्र proof है। --- -## देखने के लिए क्या है +## क्या watch करें -- **Dimension names करीब-करीब permanent हैं।** Score keys arbitrary strings हैं और platform जो कुछ भी आप send करते हैं उसे trend करता है, जिसका मतलब है कि कोई भी downstream एक bad choice को correct नहीं करता। बाद में rename करें और history split हो जाता है: old sessions old key को keep करते हैं और trend break हो जाता है। यही है कि skill को code लिखने से पहले explicit sign-off क्यों मिलता है — वह prompt को seriously लें। -- **Fixtures real production transcripts हैं।** Real sessions के against design करने का मतलब है उन्हें disk पर pull करना, और उनमें customer data हो सकता है। Skill यह commit करने से पहले पूछती है कि क्या git में करें; अगर doubt हो तो `fixtures/` को repo के बाहर रखें और हर developer को अपने अपने pull करने दें। -- **Agent एक service write और deploy करता है जो हर transcript को read करता है।** यह आपके रूप में कार्य करता है, bounded by आपके CLI login की permissions, लेकिन evaluator को review करें जैसे कोई अन्य code जो production data को touch करता है। +- **Dimension names लगभग permanent हैं।** Score keys arbitrary strings हैं और platform जो कुछ भी आप भेजते हैं उसे trend करता है, जिसका मतलब downstream कुछ भी bad choice को ठीक नहीं करता है। बाद में rename करें और history split हो जाती है: पुरानी sessions पुरानी key रखते हैं और trend टूट जाता है। यही कारण है कि skill code लिखने से पहले explicit sign-off पाता है — उस prompt को seriously लें। +- **Fixtures असली production transcripts हैं।** Real sessions के विरुद्ध design करने का मतलब है उन्हें disk में pull करना, और वे customer data contain कर सकते हैं। यह skill git में commit करने से पहले पूछता है; अगर संदेह है, तो `fixtures/` को repo के बाहर रखें और हर developer को अपना खुद का pull करने दें। +- **Agent एक service लिखता और deploy करता है जो हर transcript को read करता है।** यह आपके रूप में act करता है, आपकी CLI login की permissions से bounded, लेकिन evaluator को review करें जैसे किसी अन्य code के लिए जो production data को touch करता है। --- ## अगले कदम -- **[Evaluation suite](/hi/agenteye/evaluation-suite)**: HTTP contract, SDK, और server env vars जिन्हें skill configure करता है। -- **[Evaluations](/hi/agenteye/evaluations)**: जहां scores show up होते हैं एक बार जब वे land करते हैं। -- **[CLI skill](/hi/agenteye/cli-skill)**: sibling skill, scorer build करने की बजाय results read करने के लिए। -- **[CLI](/hi/agenteye/cli)**: command reference जिसके against skill session data design करती है। \ No newline at end of file +- **[Evaluation suite](/hi/agenteye/evaluation-suite)**: HTTP contract, SDK, और server env vars जो skill configure करता है। +- **[Evaluations](/hi/agenteye/evaluations)**: जहाँ scores दिखाई देते हैं एक बार वे land हों। +- **[CLI skill](/hi/agenteye/cli-skill)**: sibling skill, results को read करने के लिए scorer build करने के बजाय। +- **[CLI](/hi/agenteye/cli)**: command reference जो session data के पीछे है जो skill design करता है। \ No newline at end of file diff --git a/docs/hi/agenteye/event-stream.mdx b/docs/hi/agenteye/event-stream.mdx index c7748586..d5926b38 100644 --- a/docs/hi/agenteye/event-stream.mdx +++ b/docs/hi/agenteye/event-stream.mdx @@ -1,49 +1,50 @@ --- title: "Event Stream" -description: "जिस पल आपका agent कुछ करता है, आप उसे देखते हैं।" +description: "जिस क्षण आपका agent कुछ करता है, आप इसे देखते हैं।" --- -जिस पल आपका agent कुछ करता है, आप उसे देखते हैं। Event Stream production में हर agent की live pulse है: कोई इंतज़ार नहीं, logs को grep करने की ज़रूरत नहीं, कोई अनुमान नहीं कि अभी क्या हुआ। -![Live Event Stream: color-coded event rows जो real time में tail करते हैं, environment, agent, session, event type, और free text से filterable](/agenteye/images/events-stream.png) +जिस क्षण आपका agent कुछ करता है, आप इसे देखते हैं। Event Stream आपका production में हर agent पर live pulse है: कोई इंतज़ार नहीं, कोई logs grep करना नहीं, कोई अनुमान नहीं कि अभी क्या हुआ। -*आपके org के हर agent से हर event, सबसे नया पहले, जैसे-जैसे यह होता है अपडेट होता है।* +![Live Event Stream: colour-coded event rows जो real time में tail हो रहे हैं, environment, agent, session, event type, और free text के आधार पर filterable](/agenteye/images/events-stream.png) -## हर agent पर आपकी live pulse +*आपके org के हर agent से हर event, सबसे नए पहले, जैसा ही होता है update होता है।* -जब agent एक run शुरू करता है, model को call करता है, tool fire करता है, hook चलाता है, या error में फँसता है, तो row stream के top पर ठीक उसी पल दिखाई देता है। यह आपके संपूर्ण organization के हर agent से हर event को tail करता है, सबसे नया पहले, ताकि आपके पास हमेशा एक current picture हो, stale नहीं। +## हर agent पर आपका live pulse -इसका मतलब है कि कहीं log files को tail करने की ज़रूरत नहीं, machines के across grep करने की ज़रूरत नहीं, timestamps को हाथ से एक साथ जोड़ने की ज़रूरत नहीं। आप एक page खोलते हैं और आप पहले से ही production देख रहे हैं। +जब कोई agent एक run शुरू करता है, एक model को call करता है, एक tool fire करता है, एक hook run करता है, या एक error से टकराता है, तो row stream के top पर वही पल दिखाई देती है। यह आपके पूरे organization के हर agent में हर event को tail करता है, सबसे नए पहले, ताकि आपके पास हमेशा एक current picture हो, stale नहीं। -Rows को type के अनुसार color-coded किया गया है, ताकि आप stream को एक नज़र में पढ़ सकें, हर line को parse करने की बजाय। एक नज़र में, हर row आपको यह दिखाता है: +इसका मतलब है कि कहीं एक box पर log files को tail करना नहीं, machines के बीच grep करना नहीं, timestamps को हाथ से एक साथ जोड़ना नहीं। आप एक page खोलते हैं और आप पहले से ही production को देख रहे हैं। -- **इसका type**, color-coded: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, और अधिक। -- **एक-line summary** कि क्या हुआ, ताकि आपको शायद ही कभी सिर्फ gist पाने के लिए कुछ खोलने की ज़रूरत हो। +Rows को type के अनुसार colour-code किया जाता है, ताकि आप हर line को parse करने के बजाय stream को एक नज़र में पढ़ सकें। एक नज़र में, हर row आपको दिखाता है: + +- **इसका type**, colour-coded: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, और भी बहुत कुछ। +- **एक one-line summary** कि क्या हुआ, ताकि आपको शायद ही कभी किसी चीज़ को खोलने की ज़रूरत हो। - **Token counts** step के लिए। -- **Context-window fill badge** जहाँ लागू हो, ताकि prompt growth और approaching compaction visible हों, वे काटने से पहले। +- **एक context-window fill badge** जहाँ applicable है, ताकि prompt growth और एक approaching compaction visible हों। -इसे live देखने का मतलब है कि आप एक bad deploy, एक runaway loop, या errors का एक burst को तब पकड़ते हैं जब यह होता है, कल के log review में नहीं। +इसे live देखने का मतलब है कि आप एक bad deploy, एक runaway loop, या errors का burst catch करते हैं जैसा ही होता है, कल के log review में नहीं। ## वह एक run खोजें जो मायने रखता है -जब कुछ गलत दिखता है, तो आप firehose नहीं चाहते। आप वह single run चाहते हैं जो टूटा। Stream तेज़ी से filter होता है: environment द्वारा, agent द्वारा, session द्वारा, event type द्वारा, या free text द्वारा। +जब कुछ गलत दिखता है, तो आप firehose नहीं चाहते। आप वह single run चाहते हैं जो टूटा। Stream तेज़ी से filter हो जाता है: environment के अनुसार, agent के अनुसार, session के अनुसार, event type के अनुसार, या free text के अनुसार। -Session id या agent id द्वारा filter करें अपने पहले event से अपने last event तक एक run को follow करने के लिए। Event type द्वारा filter करें एक single kind of activity को isolate करने के लिए, उदाहरण के लिए पूरे org में हर `error` एक view में। Filters को stack करें "everything, everywhere" से "this agent, in prod, erroring" तक कुछ clicks में narrow करने के लिए, फिर जो आप खोजते हैं उस पर act करें। +Session id या agent id के अनुसार filter करें ताकि एक run को उसकी पहली event से लेकर आखिरी तक follow कर सकें। Event type के अनुसार filter करें एक single kind की activity को isolate करने के लिए, उदाहरण के लिए पूरे org में हर `error` एक view में। Filters को stack करें "everything, everywhere" से "this agent, in prod, erroring" तक कुछ clicks में narrow करने के लिए, फिर जो आप पाते हैं उस पर कार्य करें। -Free-text search सीधे एक message, एक tool name, या एक id की ओर जाता है जो आपके पास पहले से है, इसलिए एक customer report seconds में exact run में बदल जाता है। +Free-text search सीधे एक message, एक tool name, या एक id तक पहुँचता है जो आपके पास पहले से है, इसलिए एक customer report seconds में exact run में बदल जाता है। ## इसे कहाँ खोजें -Event Stream आपका org home है। Sign in करें और यह पहली surface है जहाँ आप land करते हैं, `//` पर, ताकि triage दूसरे पल से शुरू हो जाए जब आप पहुँचते हैं। +Event Stream आपका org home है। साइन इन करें और यह आपके landing करने वाली पहली surface है, `//` पर, इसलिए triage आपके आते ही शुरू हो जाता है। -इसके पीछे, आपके agents SDK के through events emit करते हैं, collector उन्हें आपके Failproof AI Observability server को ship करता है, और stream उन्हें tail करता है जैसे वे infrastructure में arrive करते हैं जो आप control करते हैं। जब आप raw trail की बजाय rolled-up view चाहते हैं, तो हर run के events Sessions पर एक single row में collapse हो जाते हैं, एक click दूर। +इसके पीछे, आपके agents SDK के माध्यम से events emit करते हैं, collector उन्हें आपके failproofai Observability server को भेजता है, और stream उन्हें आपके control करने वाले infrastructure में arrive करते ही tail करता है। जब आप raw trail के बजाय rolled-up view चाहते हैं, तो हर run की events एक single row में Sessions पर collapse हो जाती है, एक click दूर। -यह raw source of truth है जिस पर हर दूसरी observe surface build होती है, इसलिए जब एक number कहीं और गलत दिखता है, तो stream वह जगह है जहाँ आप confirm करते हैं कि वास्तव में क्या हुआ। +यह raw source of truth है कि हर दूसरी observe surface इस पर build करती है, इसलिए जब एक number कहीं और गलत दिखता है, तो stream वह जगह है जहाँ आप confirm करते हैं कि वास्तव में क्या हुआ। -## संबंधित +## Related -- [Sessions](/hi/agenteye/sessions): वही events हर run के लिए एक row में rolled up, एक git-style execution graph के साथ। -- [Telemetry](/hi/agenteye/telemetry): आपके agents क्या send करते हैं और कैसे events stream तक पहुँचते हैं। -- [Error tracking](/hi/agenteye/error-tracking): एक triage surface सब कुछ के लिए जो गलत हुआ। -- [Alerts](/hi/agenteye/alerts): किसी भी threshold को paging rule में बदलें। -- [CLI and agents](/hi/agenteye/cli-and-agents): आपके terminal से एक ही live trail। \ No newline at end of file +- [Sessions](/hi/agenteye/sessions): same events rolled up एक row में हर run के लिए, एक git-style execution graph के साथ। +- [Telemetry](/hi/agenteye/telemetry): आपके agents क्या भेजते हैं और कैसे events stream तक पहुँचते हैं। +- [Error tracking](/hi/agenteye/error-tracking): हर चीज़ के लिए एक triage surface जो गलत हुई। +- [Alerts](/hi/agenteye/alerts): किसी भी threshold को एक paging rule में बदलें। +- [CLI and agents](/hi/agenteye/cli-and-agents): आपके terminal से same live trail। \ No newline at end of file diff --git a/docs/hi/agenteye/hermes-capture.mdx b/docs/hi/agenteye/hermes-capture.mdx index e41c4d7f..d02143bc 100644 --- a/docs/hi/agenteye/hermes-capture.mdx +++ b/docs/hi/agenteye/hermes-capture.mdx @@ -1,27 +1,27 @@ --- title: "Hermes session capture" -description: "अपनी टीम के Hermes gateway sessions — Slack, Telegram, CLI, और scheduled runs — को AgentEye में ordinary sessions और events के रूप में लाएं।" +description: "अपनी टीम के Hermes gateway sessions — Slack, Telegram, CLI, और scheduled runs — को AgentEye में साधारण sessions और events के रूप में लाएं।" --- -[Hermes](https://hermes-agent.nousresearch.com) आपकी टीम को जहां भी वह काम करती है वहां से उत्तर देता है — Slack, Telegram, CLI, scheduled runs। Hermes session capture इन सभी को AgentEye में ordinary sessions और events के रूप में लाता है, ताकि आपकी टीम जिस assistant से हर दिन बात करती है वह उतना ही observable हो जितना कि आप जो agents लिखते हैं। +[Hermes](https://hermes-agent.nousresearch.com) आपकी टीम को जहां भी वे काम करते हैं वहां से जवाब देता है — Slack, Telegram, CLI, scheduled runs। Hermes session capture इन सभी को AgentEye में साधारण sessions और events के रूप में लाता है, ताकि आपकी टीम जिस assistant से हर दिन बात करती है वह उतना ही observable हो जितने कि आप जो agents खुद लिखते हैं। -एक छोटा सा background collector Hermes के local session store को जब भी लिखा जाता है तब पढ़ता है और sessions को AgentEye को भेजता है। यह [Codex](/hi/agenteye/codex-capture) और [OpenClaw](/hi/agenteye/openclaw-capture) capture के समान ही काम करता है, और एक collector कई को एक साथ capture कर सकता है। +एक छोटा background collector Hermes के local session store को जैसे-जैसे लिखा जाता है पढ़ता है और sessions को AgentEye को भेजता है। यह [Codex](/hi/agenteye/codex-capture) और [OpenClaw](/hi/agenteye/openclaw-capture) capture के समान ही काम करता है, और एक collector एक साथ कई को capture कर सकता है। --- ## यह क्या capture करता है -मशीन पर हर Hermes session को capture किया जाता है, चाहे वह किसी भी channel से आया हो। प्रत्येक एक AgentEye [session](/hi/agenteye/sessions) बन जाता है; इसके user और assistant messages, tool calls, और tool results matching [events](/hi/agenteye/event-stream) बन जाते हैं। +मशीन पर हर Hermes session capture किया जाता है, चाहे वह किसी भी channel से आया हो। प्रत्येक एक AgentEye [session](/hi/agenteye/sessions) बन जाता है; इसके user और assistant messages, tool calls, और tool results संबंधित [events](/hi/agenteye/event-stream) बन जाते हैं। -जिस channel से एक session शुरू हुआ — Slack, Telegram, CLI, या एक scheduled run — वह session पर रिकॉर्ड किया जाता है, ताकि आप उन्हें अलग बता सकें और एक बार में एक को filter कर सकें। इसके साथ session जिस model पर चला, जिस chat और person से शुरू किया गया, और जब एक session ने दूसरे को spawn किया, तो अपने parent की link भी आती है। +जिस channel से एक session शुरू हुआ — Slack, Telegram, CLI, या एक scheduled run — वह session पर record किया जाता है, ताकि आप उन्हें अलग बता सकें और एक बार में एक को filter कर सकें। इसके साथ वह model आता है जिस पर session चला, chat और person जिससे यह शुरू किया गया था, और जब एक session ने दूसरे को spawn किया, तो parent के लिए वापस का link। -Sessions तुरंत दिखाई देते हैं जब Hermes उन्हें शुरू करता है, चाहे कुछ भी कहा गया हो या नहीं, और एक turn का reply और उसके tool calls वास्तविक क्रम में रहते हैं। जब एक session समाप्त होता है तो आप यह भी जानते हैं कि यह क्यों समाप्त हुआ, इसकी लागत क्या थी, और इसने कितने tokens का उपयोग किया। +Sessions तुरंत दिखाई देते हैं जब Hermes उन्हें शुरू करता है, भले ही कुछ नहीं कहा गया हो, और एक turn का reply और इसके tool calls उसी क्रम में रहते हैं जिसमें वे वास्तव में हुए। जब एक session समाप्त होता है तो आप यह भी पाते हैं कि यह क्यों समाप्त हुआ, इसकी कीमत क्या थी, और इसने कितने tokens का उपयोग किया। --- ## इसे चालू करें -Capture तब तक बंद रहता है जब तक आप इसे enable न करें। एक API key के साथ collector install करें जिसके पास `events:add` permission हो (देखें [API keys](/hi/agenteye/api-keys)), और Hermes capture को चालू करें: +Capture तब तक बंद रहता है जब तक आप इसे सक्षम नहीं करते। एक API key के साथ collector install करें जिसके पास `events:add` permission हो ([API keys](/hi/agenteye/api-keys) देखें), और Hermes capture को चालू करें: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ @@ -34,20 +34,20 @@ curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main agenteye-collector health ``` -एक ही मशीन पर एक से अधिक agent को capture कर रहे हैं? एक ही command में प्रत्येक का flag जोड़ें — उदाहरण के लिए `--hermes-enabled --codex-enabled`। +एक ही मशीन पर एक से अधिक agents को capture कर रहे हैं? प्रत्येक के flag को एक ही command में जोड़ें — उदाहरण के लिए `--hermes-enabled --codex-enabled`। -पहली बार चलाने पर, आपके मौजूदा Hermes sessions को एक बार backfill किया जाता है और नई activity फिर कुछ सेकंड के भीतर stream होती है। Hermes के अपने data को केवल पढ़ा जाता है — कभी भी संशोधित या deleted नहीं किया जाता है — और प्रत्येक message एक बार भेजा जाता है, restarts के बीच भी। +पहली बार run करने पर, आपके मौजूदा Hermes sessions एक बार backfill किए जाते हैं और नई activity फिर कुछ सेकंड में stream होती है। Hermes का अपना data केवल read किया जाता है — कभी modify या delete नहीं — और प्रत्येक message एक बार shipped होता है, भले ही restarts के बीच हो। -`health` यह भी बताता है कि क्या collector ने जो कुछ भी capture किया वह वास्तव में AgentEye तक पहुंचा है। यदि कोई batch deliver नहीं किया जा सका तो उसे रखा जाता है और फिर से प्रयास किया जाता है न कि discarded किया जाता है, और check तब तक unhealthy रिपोर्ट करता है जब तक कुछ भी outstanding हो — तो "healthy" का अर्थ है आपका data पहुंचा, केवल यह नहीं कि process alive है। +`health` यह भी बताता है कि क्या collector द्वारा capture की गई हर चीज वास्तव में AgentEye तक पहुंची। यदि एक batch deliver नहीं किया जा सका तो यह kept रहता है और retry किया जाता है न कि discarded, और check तब तक unhealthy report करता है जब तक कुछ outstanding हो — इसलिए "healthy" का मतलब है आपका data आ गया, बस यह नहीं कि process जीवित है। --- ## यह कहां दिखाई देता है -Captured sessions **Sessions** में दिखाई देते हैं, और उनके events **Events** stream में, किसी भी अन्य agent के समान जिसे आप observe करते हैं — तो [session replay](/hi/agenteye/sessions), [search](/hi/agenteye/queries), [evaluations](/hi/agenteye/evaluations), और [alerts](/hi/agenteye/alerts) सभी उन पर काम करते हैं। उन्हें अपने आप पर देखने के लिए Hermes agent द्वारा filter करें। +Captured sessions **Sessions** में दिखाई देते हैं, और उनके events **Events** stream में, किसी भी अन्य agent जैसे जिसे आप observe करते हैं — इसलिए [session replay](/hi/agenteye/sessions), [search](/hi/agenteye/queries), [evaluations](/hi/agenteye/evaluations), और [alerts](/hi/agenteye/alerts) सभी उन पर काम करते हैं। Hermes agent द्वारा filter करें उन्हें अपने आप पर देखने के लिए। --- ## गोपनीयता -Hermes sessions में पूरी transcript होती है — command output, file contents, और कुछ भी जो agent ने पढ़ा या लिखा था सहित — और इसमें secrets हो सकते हैं। Captured sessions को जैसे-तैसे भेजा जाता है, तो capture को केवल वहां enable करें जहां उस content को AgentEye में centralize करना appropriate हो, और collector को एक ऐसी key दें जो केवल `events:add` तक scoped हो। देखें [Security](/hi/agenteye/security) कि आपके data को कैसे अलग रखा जाता है। \ No newline at end of file +Hermes sessions में पूरा transcript होता है — command output, file contents, और कुछ भी जो agent ने read या write किया — और secrets contain कर सकते हैं। Captured sessions जैसे-जैसे भेजे जाते हैं, इसलिए capture केवल वहां enable करें जहां AgentEye में उस content को centralize करना उपयुक्त हो, और collector को केवल `events:add` तक scoped एक key दें। [Security](/hi/agenteye/security) देखें कि आपका data कैसे isolated रखा जाता है। \ No newline at end of file diff --git a/docs/hi/agenteye/incidents.mdx b/docs/hi/agenteye/incidents.mdx index df3738c1..c66c66e6 100644 --- a/docs/hi/agenteye/incidents.mdx +++ b/docs/hi/agenteye/incidents.mdx @@ -1,28 +1,28 @@ --- -title: "घटनाएँ" -description: "जब कोई alert trigger होता है, तो सभी को दिखता है कि incident खुला है, इसका मालिक कौन है, और अब तक क्या हुआ है — एक ही attributed timeline पर।" +title: "घटनाएं" +description: "जब कोई अलर्ट फायर होता है, तो सभी को दिखता है कि घटना खुली है, उसका मालिक कौन है, और अब तक क्या हुआ है — एक ही जिम्मेदारी वाली टाइमलाइन पर।" --- -जब कोई alert trigger होता है, तो पहला सवाल हमेशा यही होता है "इस पर कौन काम कर रहा है?" Incidents इसका जवाब देते हैं: जिस पल कोई breach होता है, सभी को दिखता है कि incident खुला है, इसका मालिक कौन है, और अब तक बिल्कुल क्या हुआ है, साथ ही एक स्वच्छ, attributed record जिसे आप सीधे post-mortem को दे सकते हैं। +जब कोई अलर्ट फायर होता है, तो पहला सवाल हमेशा होता है "कौन इस पर है?" घटनाएं इसका जवाब देती हैं: जिस पल कुछ भी उल्लंघन करता है, सभी को दिखता है कि घटना खुली है, उसका मालिक कौन है, और अब तक बिल्कुल क्या हुआ है, एक स्वच्छ, जिम्मेदारी वाले रिकॉर्ड के साथ जिसे आप सीधे किसी पोस्ट-मॉर्टम को दे सकते हैं। -![The Incidents inbox: alert-linked और manually opened incident cards, state के अनुसार grouped, हर एक के साथ severity badge और assignee](/agenteye/images/incidents.png) -*The inbox open incidents को state के अनुसार grouped करता है और severity और assignee के अनुसार filter करता है, इसलिए आप वह देखते हैं जिसे अभी किसी की ज़रूरत है।* +![घटनाओं का इनबॉक्स: अलर्ट-लिंक की गई और मैन्युअली खोली गई घटना कार्ड, स्थिति के अनुसार समूहित, प्रत्येक एक गंभीरता बैज और एक असाइनी के साथ](/agenteye/images/incidents.png) +*इनबॉक्स खुली घटनाओं को स्थिति के अनुसार समूहित करता है और गंभीरता और असाइनी के अनुसार फ़िल्टर करता है, इसलिए आप देखते हैं कि मानव के हस्तक्षेप की क्या आवश्यकता है।* -## एक नज़र में जानें कि किसके पास है +## पहचानें कि किसके पास यह है, एक नज़र में -चैट thread में "क्या कोई इस पर नज़र रख रहा है?" के सवाल का कोई और ज़वाब नहीं। एक breach automatically एक incident खोलता है और इसे shared inbox में डालता है, जो state के अनुसार grouped होता है। इसे acknowledge करें और आपका नाम इस पर होगा, इसलिए बाकी टीम को पता चलेगा कि इसे संभाला जा रहा है। Acknowledgement shared है: कई operators एक ही incident को ack कर सकते हैं और हर एक को अलग से record किया जाता है, इसलिए पूरा war room नामों से दिखता है, न कि एक दूसरे के ऊपर। Triage के लिए एक मालिक assign करें, और inbox को severity या assignee के अनुसार filter करें ताकि आप सिर्फ अपना काम देखें। +चैट थ्रेड में फिर से "क्या कोई इस पर देख रहा है?" न पूछें। एक उल्लंघन स्वचालित रूप से एक घटना खोलता है और इसे एक साझा इनबॉक्स में डालता है, जो स्थिति के अनुसार समूहित होता है। इसे स्वीकार करें और आपका नाम इस पर है, इसलिए बाकी टीम को पता है कि यह संभाला गया है। स्वीकृति साझा की जाती है: कई ऑपरेटर एक ही घटना को स्वीकार कर सकते हैं और प्रत्येक को अलग से रिकॉर्ड किया जाता है, इसलिए एक पूरा वॉर रूम नाम के अनुसार दिखता है बजाय एक दूसरे को धकेलने के। ट्रिएज के लिए एक मालिक असाइन करें, और इनबॉक्स को गंभीरता या असाइनी के अनुसार फ़िल्टर करें ताकि यह आपके लिए कम हो जाए। -## पूरी कहानी, एक ही timeline में +## पूरी कहानी, एक टाइमलाइन में -जब incident ख़त्म हो जाता है, तो आपके पास पहले से ही write-up होता है। कोई भी incident खोलें और आपको breach का सबूत, इसके assignees और subscribers, coordinating के लिए एक comment thread, और एक append-only activity timeline मिलता है। +जब घटना समाप्त हो जाती है, तो आपके पास पहले से ही रिपोर्ट है। कोई भी घटना खोलें और आपको उल्लंघन का सबूत, इसके असाइनी और सदस्य, समन्वय के लिए एक टिप्पणी थ्रेड, और एक केवल-अपेंड गतिविधि टाइमलाइन मिलता है। -![An incident detail view: parent alert और breach summary, assignees और subscribers, एक attributed activity timeline, और एक comment thread](/agenteye/images/incident-detail.png) -*सब कुछ जो हुआ, क्रम में, हर पंक्ति इस पर हस्ताक्षर की गई है कि किसने इसे किया।* +![एक घटना विवरण दृश्य: मूल अलर्ट और उल्लंघन सारांश, असाइनी और सदस्य, एक जिम्मेदारी वाली गतिविधि टाइमलाइन, और एक टिप्पणी थ्रेड](/agenteye/images/incident-detail.png) +*सब कुछ जो हुआ, क्रम में, प्रत्येक पंक्ति उस व्यक्ति द्वारा हस्ताक्षरित जिसने इसे किया।* -हर action (opened, acknowledged, resolved, आदि) उस timeline पर लिखा जाता है और कभी संपादित नहीं किया जाता। हर entry को attribute किया जाता है: उस operator को जिसने इसे किया, email से, या **automated** को उन चीज़ों के लिए जो Failproof AI Observability ने अपने आप की हैं, जैसे breach पर incident को खोलना। कुछ भी anonymous नहीं है और कुछ भी नष्ट नहीं होता, इसलिए post-mortem कम या ज़्यादा अपने आप लिख जाता है। +प्रत्येक कार्रवाई (खोला गया, स्वीकृत, समाधान किया गया, आदि) उस टाइमलाइन पर लिखी जाती है और कभी संपादित नहीं की जाती है। प्रत्येक प्रविष्टि को जिम्मेदार ठहराया जाता है: उस ऑपरेटर को जिसने इसे किया, ईमेल के द्वारा, या **स्वचालित** किसी भी चीज़ के लिए जो Failproof AI ने स्वयं की, जैसे कि उल्लंघन पर घटना खोलना। कुछ भी गुमनाम नहीं है और कुछ भी खो नहीं जाता है, इसलिए पोस्ट-मॉर्टम कम या ज्यादा खुद लिख लेता है। -## एक incident कैसे आगे बढ़ता है +## एक घटना कैसे आगे बढ़ती है ```mermaid stateDiagram-v2 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **Open (firing):** breach incident को खोलता है और आपके channels को एक बार page करता है। Repeated breaches एक ही incident में fold हो जाते हैं और इसके बजाय evidence को refresh करते हैं कि बार-बार आपको page न करें। -- **Acknowledged:** एक operator इसे उठाता है। यह खुला रहता है, और बाद में breaches quietly evidence को update करते हैं। -- **Resolved:** एक operator इसे बंद करता है। जब condition clear हो जाती है तो automatic resolution की योजना है लेकिन अभी enabled नहीं है, इसलिए एक incident तब तक खुला रहता है जब तक कोई इंसान इसे resolve न करे, जो सभी को ईमानदार रखता है कि वास्तव में क्या clear हुआ है। एक नया incident बाद में एक ही alert पर खुल सकता है। +- **खुली (फायरिंग):** उल्लंघन घटना खोलता है और आपके चैनलों को एक बार पेज करता है। दोहराए गए उल्लंघन एक ही घटना में फोल्ड हो जाते हैं और इसके सबूत को रिफ्रेश करते हैं बजाय आपको बार-बार पेज करने के। +- **स्वीकृत:** एक ऑपरेटर इसे उठाता है। यह खुला रहता है, और बाद में उल्लंघन सबूत को शांति से अपडेट करते हैं। +- **समाधान किया गया:** एक ऑपरेटर इसे बंद कर देता है। स्वचालित समाधान जब स्थिति स्पष्ट होती है तो योजना बनाई जाती है लेकिन अभी तक सक्षम नहीं है, इसलिए एक घटना तब तक खुली रहती है जब तक कोई मानव इसे समाधान न कर दे, जो सभी को यह सच बताता है कि क्या वास्तव में स्पष्ट हुआ है। बाद में एक ही अलर्ट पर एक ताजी घटना खुल सकती है। -एक alert के पास एक बार में सबसे ज़्यादा एक open incident हो सकता है, इसलिए एक flapping rule आपको duplicates में दफ़न नहीं कर सकता। आप manually भी एक incident खोल सकते हैं: कोई alert न पकड़ने वाली चीज़ के लिए एक standalone, या एक existing alert के लिए एक, अगर आपके पास `incidents:write` है। +एक अलर्ट एक समय में सबसे अधिक एक खुली घटना रखता है, इसलिए एक फ्लैपिंग नियम आपको डुप्लिकेट से दबा नहीं सकता है। आप एक घटना को हाथ से भी खोल सकते हैं: कुछ ऐसी के लिए एक स्टैंडअलोन जो कोई अलर्ट नहीं पकड़ा, या किसी मौजूदा अलर्ट से जुड़ी हुई, यदि आपके पास `incidents:write` है। ## इसे कहाँ खोजें -Incidents `//incidents` पर रहते हैं। Viewing के लिए **`incidents:read`** की ज़रूरत है; manual incident खोलने के लिए **`incidents:write`** की ज़रूरत है; acknowledging, assigning, commenting, और resolving के लिए **`incidents:ack`** की ज़रूरत है। पुरानी keys जिन्होंने retired `alerts:ack` को granted किया है काम करती रहती हैं, क्योंकि इसे `incidents:ack` के रूप में honored किया जाता है, इसलिए आपके on-call rotation को re-issue करने की ज़रूरत नहीं है। +घटनाएं `//incidents` पर रहती हैं। देखने के लिए **`incidents:read`** की आवश्यकता है; एक मैन्युअली घटना खोलने के लिए **`incidents:write`** की आवश्यकता है; स्वीकार करने, असाइन करने, टिप्पणी करने, और समाधान करने के लिए **`incidents:ack`** की आवश्यकता है। पुरानी कुंजियां जिन्हें सेवानिवृत्त `alerts:ack` दी गई थी वह काम करती रहती हैं, क्योंकि इसे `incidents:ack` के रूप में सम्मानित किया जाता है, इसलिए आपके ऑन-कॉल रोटेशन को पुनः जारी करने की आवश्यकता नहीं है। ## संबंधित -- [Alerts](/hi/agenteye/alerts): वह नियम जो threshold breach होने पर ये incidents खोलते हैं। -- [Error tracking](/hi/agenteye/error-tracking): हर failure को एक जगह देखें और एक को एक alert में promote करें। -- [Audits](/hi/agenteye/audits): scheduled analyst जो उन failures को खोजता है जिन पर कोई rule नज़र नहीं रख रहा था। \ No newline at end of file +- [अलर्ट](/hi/agenteye/alerts): वह नियम जो एक थ्रेसहोल्ड उल्लंघन होने पर ये घटनाएं खोलते हैं। +- [त्रुटि ट्रैकिंग](/hi/agenteye/error-tracking): एक जगह पर हर विफलता देखें और एक को अलर्ट में प्रचारित करें। +- [ऑडिट](/hi/agenteye/audits): निर्धारित विश्लेषक जो उन विफलताओं को खोजता है जिन्हें कोई नियम नहीं देख रहा था। \ No newline at end of file diff --git a/docs/hi/agenteye/observability.mdx b/docs/hi/agenteye/observability.mdx index ba4c8bd6..f748a0db 100644 --- a/docs/hi/agenteye/observability.mdx +++ b/docs/hi/agenteye/observability.mdx @@ -1,23 +1,22 @@ --- title: "Observe" -description: "Observe सर्फेस वह जगह हैं जहां आप अपने एजेंटों को अभी क्या कर रहे हैं यह देख सकते हैं और किसी भी एक रन में ड्रिल डाउन कर सकते हैं।" +description: "Observe सतहें वह स्थान हैं जहाँ आप देख सकते हैं कि आपके agents अभी क्या कर रहे हैं और किसी भी एकल run में गहराई से जा सकते हैं।" --- +Observe सतहें वह स्थान हैं जहाँ आप देख सकते हैं कि आपके agents अभी क्या कर रहे हैं और किसी भी एकल run में गहराई से जा सकते हैं। यहाँ सबकुछ live है, आपके संगठन के लिए limited है, और तारीख की रेंज, environment, agent, और session के आधार पर filterable है, इसलिए आप "कुछ गलत लग रहा है" से लेकर सटीक run तक कुछ ही सेकंड में पहुँच सकते हैं। -Observe सर्फेस वह जगह हैं जहां आप अपने एजेंटों को अभी क्या कर रहे हैं यह देख सकते हैं और किसी भी एक रन में ड्रिल डाउन कर सकते हैं। यहां सब कुछ लाइव है, आपके संगठन के स्कोप में है, और तारीख की रेंज, वातावरण, एजेंट, और सेशन के आधार पर फ़िल्टर किया जा सकता है, ताकि आप "कुछ गलत महसूस हो रहा है" से सटीक रन तक सेकंडों में पहुंच सकें। +![Live Event Stream, प्रकार के अनुसार रंग-कोडित और environment, agent, और session के अनुसार filterable](/agenteye/images/events-stream.png) -![लाइव इवेंट स्ट्रीम, प्रकार के अनुसार रंग-कोडित और वातावरण, एजेंट, और सेशन के आधार पर फ़िल्टर किया जा सकता है](/agenteye/images/events-stream.png) +चार सतहें, प्रत्येक के अपने पृष्ठ के साथ: -चार सर्फेस, प्रत्येक के साथ अपना-अपना पेज: - -- **[Event stream](/hi/agenteye/event-stream)**: हर एजेंट भर में हर रन की लाइव, प्रति-चरण ट्रेल, सबसे नया पहले। आपका संगठन होम और ट्राइएज के लिए पहला स्टॉप। -- **[Sessions and execution graph](/hi/agenteye/sessions)**: वे इवेंट प्रति रन एक पंक्ति में रोल अप किए गए, साथ ही एक git-शैली की तस्वीर कि हर रन कैसे सामने आया। -- **[Performance metrics](/hi/agenteye/telemetry)**: विलंबता हीट-मैप और आपके मॉडल, टूल्स, और हुक के लिए p50/p95/p99 महत्वपूर्ण संकेत, ताकि एक टेल स्पाइक माध्यिका से अलग दिखाई दे। -- **[Error tracking](/hi/agenteye/error-tracking)**: सब कुछ के लिए एक ट्राइएज सर्फेस जो गलत हुआ, एक फायरिंग अलर्ट से रन तक एक क्लिक दूर जो टूट गया। +- **[Event stream](/hi/agenteye/event-stream)**: हर agent के पार हर run का live, प्रत्येक-चरण का ट्रेल, सबसे नया पहले। आपका संगठन home और triage के लिए पहला पड़ाव। +- **[Sessions और execution graph](/hi/agenteye/sessions)**: वे events एक run में एक पंक्ति में rolled up, साथ ही एक git-style चित्र कि कैसे हर run unfold हुआ। +- **[Performance metrics](/hi/agenteye/telemetry)**: latency heat-maps और p50/p95/p99 vitals आपके models, tools, और hooks के लिए, इसलिए एक tail spike median से अलग दिखता है। +- **[Error tracking](/hi/agenteye/error-tracking)**: सबकुछ जो गलत हुआ उसके लिए एक triage सतह, एक firing alert से broken run तक एक click की दूरी पर। ## संबंधित -- [Evaluations](/hi/agenteye/evaluations): हर रन को गुणवत्ता के लिए स्कोर करें। -- [Alerts](/hi/agenteye/alerts): किसी भी थ्रेशहोल्ड को एक पेजिंग नियम में बदलें। -- [Audits](/hi/agenteye/audits): Failproof AI Observability को सेशन भर में विफलता पैटर्न खोजने दें। -- [CLI and agents](/hi/agenteye/cli-and-agents): आपके टर्मिनल से समान अवलोकनशीलता। \ No newline at end of file +- [Evaluations](/hi/agenteye/evaluations): हर run को quality के लिए score करें। +- [Alerts](/hi/agenteye/alerts): किसी भी threshold को एक paging rule में बदलें। +- [Audits](/hi/agenteye/audits): Failproof AI Observability को sessions में failure patterns खोजने दें। +- [CLI और agents](/hi/agenteye/cli-and-agents): आपके terminal से समान observability। \ No newline at end of file diff --git a/docs/hi/agenteye/openclaw-capture.mdx b/docs/hi/agenteye/openclaw-capture.mdx index d65632cb..e5fd4ffe 100644 --- a/docs/hi/agenteye/openclaw-capture.mdx +++ b/docs/hi/agenteye/openclaw-capture.mdx @@ -1,50 +1,50 @@ --- --- -title: "OpenClaw सत्र कैप्चर" -description: "अपनी टीम के स्थानीय OpenClaw सत्रों को AgentEye में साधारण सत्रों और घटनाओं के रूप में प्राप्त करें — OpenClaw चलाने के तरीके में कोई परिवर्तन नहीं।" +title: "OpenClaw सेशन कैप्चर" +description: "अपनी टीम के स्थानीय OpenClaw सेशन को AgentEye में सामान्य सेशन और घटनाओं के रूप में कैप्चर करें — OpenClaw के चलने के तरीके में कोई बदलाव किए बिना।" --- -यदि आपकी टीम [OpenClaw](https://docs.openclaw.ai) चलाती है, तो OpenClaw सत्र कैप्चर उन सत्रों को AgentEye में साधारण सत्रों और घटनाओं के रूप में लाता है, ताकि आप उन्हें खोज सकें, पुनः चला सकें और उन्हें आपके द्वारा देखी गई किसी भी अन्य चीज़ के साथ-साथ मूल्यांकन कर सकें। यह [Python SDK](/hi/agenteye/python-sdk) की पूरक है: SDK आपके द्वारा लिखे गए एजेंटों को साधन देता है, जबकि यह आपकी टीम द्वारा पहले से किए जा रहे OpenClaw कार्य को कैप्चर करता है — इसे चलाने के तरीके में कोई परिवर्तन नहीं। +यदि आपकी टीम [OpenClaw](https://docs.openclaw.ai) चलाती है, तो OpenClaw सेशन कैप्चर उन सेशन को AgentEye में सामान्य सेशन और घटनाओं के रूप में लाता है, ताकि आप उन्हें खोज सकें, दोबारा चला सकें, और अन्य सभी चीज़ों के साथ मूल्यांकन कर सकें। यह [Python SDK](/hi/agenteye/python-sdk) को पूरक है: SDK आपके द्वारा लिखे गए एजेंट को उपकरणीकृत करता है, जबकि यह आपकी टीम जो OpenClaw का काम पहले से कर रही है उसे कैप्चर करता है — इसे चलाने के तरीके में कोई बदलाव किए बिना। -एक छोटा पृष्ठभूमि कलेक्टर OpenClaw के स्थानीय सत्र प्रतिलेखों को पढ़ता है क्योंकि वे लिखे जाते हैं और उन्हें AgentEye को भेजता है। यह [Codex कैप्चर](/hi/agenteye/codex-capture) के समान तरीके से काम करता है, और एक कलेक्टर एक साथ दोनों को कैप्चर कर सकता है। +एक छोटा बैकग्राउंड कलेक्टर OpenClaw के स्थानीय सेशन ट्रांसक्रिप्ट को पढ़ता है जैसे वे लिखे जाते हैं और उन्हें AgentEye में भेजता है। यह [Codex कैप्चर](/hi/agenteye/codex-capture) के समान तरीके से काम करता है, और एक कलेक्टर दोनों को एक साथ कैप्चर कर सकता है। --- ## यह क्या कैप्चर करता है -किसी मशीन के OpenClaw सेटअप में कॉन्फ़िगर किया गया प्रत्येक एजेंट उस मशीन के कलेक्टर द्वारा कैप्चर किया जाता है — कोई प्रति-एजेंट सेटअप नहीं है। +एक मशीन के OpenClaw सेटअप में कॉन्फ़िगर किया गया प्रत्येक एजेंट उस मशीन के कलेक्टर द्वारा कैप्चर किया जाता है — कोई प्रति-एजेंट सेटअप नहीं है। -प्रत्येक OpenClaw सत्र एक AgentEye [सत्र](/hi/agenteye/sessions) बन जाता है; इसके उपयोगकर्ता और सहायक संदेश, उपकरण कॉल और उपकरण परिणाम मिलान वाली [घटनाओं](/hi/agenteye/event-stream) बन जाते हैं। +प्रत्येक OpenClaw सेशन एक AgentEye [सेशन](/hi/agenteye/sessions) बन जाता है; इसके उपयोगकर्ता और सहायक संदेश, टूल कॉल, और टूल परिणाम मिलान वाली [घटनाओं](/hi/agenteye/event-stream) बन जाते हैं। --- ## इसे चालू करें -कैप्चर तब तक बंद है जब तक आप इसे सक्षम नहीं करते। `events:add` अनुमति वाली API कुंजी के साथ कलेक्टर को इंस्टॉल करें (देखें [API कुंजियाँ](/hi/agenteye/api-keys)), और OpenClaw कैप्चर चालू करें: +कैप्चर तब तक बंद रहता है जब तक आप इसे सक्षम नहीं करते। कलेक्टर को एक API कुंजी के साथ स्थापित करें जिसके पास `events:add` अनुमति है (देखें [API कुंजियां](/hi/agenteye/api-keys)), और OpenClaw कैप्चर चालू करें: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -यह कलेक्टर को इंस्टॉल करता है, इसे एक पृष्ठभूमि सेवा के रूप में पंजीकृत करता है, और कैप्चरिंग शुरू करता है। पुष्टि करें कि यह चल रहा है: +यह कलेक्टर को स्थापित करता है, इसे एक बैकग्राउंड सेवा के रूप में पंजीकृत करता है, और कैप्चरिंग शुरू करता है। पुष्टि करें कि यह चल रहा है: ```bash agenteye-collector health ``` -एक ही मशीन पर एक से अधिक एजेंटों को कैप्चर कर रहे हैं? प्रत्येक का ध्वज एक ही कमांड में जोड़ें — उदाहरण के लिए `--openclaw-enabled --codex-enabled`। +एक ही मशीन पर एक से अधिक एजेंट कैप्चर कर रहे हैं? प्रत्येक का फ्लैग एक ही कमांड में जोड़ें — उदाहरण के लिए `--openclaw-enabled --codex-enabled`। -पहली बार चलने पर, आपके मौजूदा OpenClaw सत्रों को एक बार बैकफिल किया जाता है और नई गतिविधि फिर कुछ सेकंड के भीतर स्ट्रीम होती है। OpenClaw की अपनी फाइलें केवल पढ़ी जाती हैं — कभी भी संशोधित, स्थानांतरित या हटाई नहीं जाती हैं — और प्रत्येक सत्र पुनः प्रारंभ के भीतर भी बिल्कुल एक बार भेजा जाता है। +पहली बार चलाने पर, आपके मौजूदा OpenClaw सेशन एक बार बैकफिल किए जाते हैं और नई गतिविधि फिर सेकंड के भीतर स्ट्रीम होती है। OpenClaw की अपनी फाइलें केवल पढ़ी जाती हैं — कभी भी संशोधित, स्थानांतरित, या हटाई नहीं जाती — और प्रत्येक सेशन को बिल्कुल एक बार भेजा जाता है, यहां तक कि पुनः शुरुआत के दौरान भी। --- -## यह कहाँ दिखाई देता है +## यह कहां दिखाई देता है -कैप्चर किए गए सत्र **Sessions** में दिखाई देते हैं, और उनकी घटनाएं **Events** स्ट्रीम में, किसी भी अन्य एजेंट के समान जिसे आप देखते हैं — इसलिए [सत्र पुनः चलाना](/hi/agenteye/sessions), [खोज](/hi/agenteye/queries), [मूल्यांकन](/hi/agenteye/evaluations), और [अलर्ट](/hi/agenteye/alerts) सभी उन पर काम करते हैं। उन्हें अपने आप से देखने के लिए OpenClaw एजेंट द्वारा फ़िल्टर करें। +कैप्चर किए गए सेशन **सेशन** में दिखाई देते हैं, और उनकी घटनाएं **घटनाओं** की स्ट्रीम में, किसी भी अन्य एजेंट की तरह जिसे आप देखते हैं — इसलिए [सेशन रीप्ले](/hi/agenteye/sessions), [खोज](/hi/agenteye/queries), [मूल्यांकन](/hi/agenteye/evaluations), और [अलर्ट](/hi/agenteye/alerts) सभी उन पर काम करते हैं। OpenClaw एजेंट द्वारा फ़िल्टर करें उन्हें अलग से देखने के लिए। --- ## गोपनीयता -OpenClaw प्रतिलेख में पूर्ण सत्र होता है — जिसमें कमांड आउटपुट, फाइल सामग्री और कुछ भी शामिल है जो एजेंट ने पढ़ा या लिखा — और इसमें गोपनीय जानकारी हो सकती है। कैप्चर किए गए सत्रों को जैसा है वैसा भेजा जाता है, इसलिए केवल उन मशीनों और टीमों के लिए कैप्चर सक्षम करें जहाँ उस सामग्री को AgentEye में केंद्रीकृत करना उपयुक्त है, और कलेक्टर को केवल `events:add` के लिए निर्धारित कुंजी दें। [सुरक्षा](/hi/agenteye/security) के लिए देखें कि आपका डेटा कैसे अलग रखा जाता है। \ No newline at end of file +OpenClaw ट्रांसक्रिप्ट में पूरा सेशन होता है — कमांड आउटपुट, फाइल सामग्री, और कुछ भी जो एजेंट ने पढ़ा या लिखा था सहित — और इसमें गुप्त जानकारी हो सकती है। कैप्चर किए गए सेशन जैसे-तैसे भेजे जाते हैं, इसलिए कैप्चर केवल उन मशीनों और टीमों पर सक्षम करें जहां उस सामग्री को AgentEye में केंद्रीकृत करना उपयुक्त है, और कलेक्टर को केवल `events:add` तक सीमित एक कुंजी दें। देखें [सुरक्षा](/hi/agenteye/security) यह जानने के लिए कि आपका डेटा कैसे अलग रखा जाता है। \ No newline at end of file diff --git a/docs/hi/agenteye/overview.mdx b/docs/hi/agenteye/overview.mdx index 4ea47378..c081e8f5 100644 --- a/docs/hi/agenteye/overview.mdx +++ b/docs/hi/agenteye/overview.mdx @@ -1,107 +1,108 @@ --- -title: "Failproof AI: एजेंट्स की विफलताओं का अवलोकन" -description: "Failproof AI Observability एक स्व-होस्टेड प्लेटफॉर्म है जो आपके AI एजेंट्स को प्रोडक्शन में देखने, मूल्यांकन करने और सुधारने के लिए है।" +title: "Failproof AI: एजेंट की विफलताओं का अवलोकन करें" +description: "Failproof AI Observability एक स्व-होस्ट किया गया प्लेटफ़ॉर्म है जो आपके AI एजेंट्स को प्रोडक्शन में देखने, मूल्यांकन करने और सुधारने के लिए है।" --- -Failproof AI Observability एक स्व-होस्टेड प्लेटफॉर्म है जो आपके AI एजेंट्स को प्रोडक्शन में देखने, मूल्यांकन करने और सुधारने के लिए है। यह आपके एजेंट्स द्वारा किए गए सभी काम को रिकॉर्ड करता है (प्रत्येक टूल कॉल, मॉडल अनुरोध, हुक और त्रुटि), प्रत्येक रन की गुणवत्ता को स्कोर करता है, और उन विफलताओं को सामने लाता है जिन्हें आप खोजने के लिए नहीं जानते थे, सभी एक डैशबोर्ड में जो आप अपने बुनियादी ढांचे के अंदर चलाते हैं। -यदि आप AI एजेंट्स शिप करते हैं और यह अनुमान लगाने से थक गए हैं कि एक रन गलत क्यों हुआ, तो यह शुरू करने के लिए सही पृष्ठ है। यह समझाता है कि Failproof AI Observability आपको क्या देता है और कैसे चीजें एक साथ फिट होती हैं, इससे पहले कि आप कुछ भी इंस्टॉल करें। +Failproof AI Observability एक स्व-होस्ट किया गया प्लेटफ़ॉर्म है जो आपके AI एजेंट्स को प्रोडक्शन में देखने, मूल्यांकन करने और सुधारने के लिए है। यह आपके एजेंट्स द्वारा की गई हर चीज़ को रिकॉर्ड करता है (हर टूल कॉल, मॉडल रिक्वेस्ट, हुक और एरर), प्रत्येक रन की गुणवत्ता को स्कोर करता है, और उन विफलताओं को सामने लाता है जिन्हें आप ढूंढ नहीं सकते थे — सब कुछ एक डैशबोर्ड में जो आप अपने बुनियादी ढांचे के अंदर चलाते हैं। -> **Failproof AI Observability एक enterprise उत्पाद है Failproof AI से।** इसे कार्य में देखना चाहते हैं? एक डेमो का अनुरोध करें: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) को ईमेल करें। +यदि आप AI एजेंट्स भेजते हैं और अनुमान लगाने से थक गए हैं कि कोई रन गलत क्यों गया, तो यह शुरू करने का पृष्ठ है। यह समझाता है कि Failproof AI Observability आपको क्या देता है और कैसे सभी टुकड़े एक साथ काम करते हैं, इससे पहले कि आप कुछ भी स्थापित करें। -![एक Failproof AI Observability सेशन को git-शैली के execution ग्राफ़ के रूप में खींचा गया है, जिसके साथ इसकी event timeline है, जिसमें दाईं ओर प्रति-रन tools, मॉडल्स और hooks का विवरण है](/agenteye/images/session-detail.png) +> **Failproof AI Observability, Failproof AI का एक एंटरप्राइज़ प्रोडक्ट है।** इसे क्रिया में देखना चाहते हैं? डेमो के लिए अनुरोध करें: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) को ईमेल करें। -*हर एजेंट रन को git-शैली के execution ग्राफ़ (बाएं) के रूप में खींचा जाता है, इसके event timeline के बगल में। समानांतर sub-agents को प्रत्येक को अपनी लेन मिलती है; दाईं ओर की पट्टी रन के लिए tools, मॉडल्स, hooks और token spend को विभाजित करती है।* +![Failproof AI Observability सेशन को git-शैली के एक्सीक्यूशन ग्राफ़ के रूप में खींचा गया है जो इसकी इवेंट टाइमलाइन के बगल में है, दाहिनी ओर प्रति-रन टूल, मॉडल और हुक का विवरण है](/agenteye/images/session-detail.png) + +*प्रत्येक एजेंट रन को git-शैली के एक्सीक्यूशन ग्राफ़ (बाएं) के रूप में खींचा जाता है जो इसकी इवेंट टाइमलाइन के बगल में है। समानांतर उप-एजेंट्स को प्रत्येक को अपनी लेन मिलती है; दाहिनी ओर रन के लिए टूल, मॉडल, हुक और टोकन खर्च का विवरण दिया गया है।* --- -## कार्य में देखें +## इसे क्रिया में देखें -दो छोटे वीडियो उन दो चीजों को दिखाते हैं जिन्हें टीमें सबसे पहले प्राप्त करती हैं: एक रन को ट्रेस करना और विफलताओं को स्वचालित रूप से खोजना। +दो छोटे वीडियो वह दो चीजें दिखाते हैं जो टीमें सबसे पहले खोजती हैं: एक रन को ट्रेस करना, और विफलताओं को स्वचालित रूप से खोजना।
-*एजेंट ट्रेसिंग: लक्ष्य से लेकर tools से अंतिम उत्तर तक, एक रन को चरण दर चरण फॉलो करें।* +*एजेंट ट्रेसिंग: एक एकल रन को चरण दर चरण लक्ष्य से टूल से अंतिम उत्तर तक देखें।*
-*Failproof Audit: Failproof AI Observability को अपने लॉग्स को सेशन्स के पार खोदने और आपको बताने दें कि क्या ठीक करना है।* +*Failproof Audit: Failproof AI Observability को अपने लॉग को सेशन के बीच माइन करने दें और आपको बताएं कि क्या ठीक करना है।* --- ## टीमें इसका उपयोग क्यों करती हैं -- **देखें कि आपका एजेंट वास्तव में क्या करता है।** हर रन एक पठनीय, git-शैली के execution ग्राफ़ में बदल जाता है: कौन से tools समानांतर में चले, कौन से sub-agents शाखा बंद हो गए, यह कहां रुका और इसने क्या खर्च किया। -- **गुणवत्ता रिग्रेशन को स्वचालित रूप से पकड़ें।** एक छोटी स्कोरिंग सेवा को कनेक्ट करें और Failproof AI Observability हर समाप्त रन को स्कोर करता है, इसलिए सहायकता में गिरावट या hallucinations में स्पाइक अपने आप दिखाई देता है। -- **उन विफलताओं को खोजें जिनके लिए आपने कोई नियम नहीं लिखा है।** पुनरावर्ती audits आपके लॉग्स को सेशन्स के पार खोदते हैं और त्रुटि क्लस्टर, latency आउटलायर्स, कम स्कोर और फंसे हुए runs को खोजते हैं, फिर आपको ranked, evidence-backed खोजें देते हैं। -- **जब यह महत्वपूर्ण हो तो पेज प्राप्त करें।** Threshold नियम त्रुटि दर, latency, cost या evaluator स्कोर पर फायर करते हैं और incidents खोलते हैं जिन्हें आप स्वीकार कर सकते हैं, assign कर सकते हैं और resolve कर सकते हैं। -- **सादे अंग्रेजी में सवाल पूछें।** एक in-dashboard AI सहायक आपके अपने डेटा पर यह जवाब देता है कि इस सप्ताह prod में गुणवत्ता कैसी चल रही है। यह जो भी परिवर्तन करता है वह approval-gated है। -- **अपना डेटा रखें।** Failproof AI Observability स्व-होस्टेड है: events, prompts और analytics उस बुनियादी ढांचे में रहते हैं जिसे आप नियंत्रित करते हैं। +- **देखें कि आपके एजेंट ने वास्तव में क्या किया।** प्रत्येक रन एक पठनीय, git-शैली के एक्सीक्यूशन ग्राफ़ में बदल जाता है: कौन से टूल समानांतर में चले, कौन से उप-एजेंट्स शाखाबद्ध हुए, यह कहां रुका और यह क्या खर्च करता है। +- **गुणवत्ता में गिरावट को स्वचालित रूप से पकड़ें।** एक छोटी स्कोरिंग सेवा को कनेक्ट करें और Failproof AI Observability प्रत्येक पूर्ण रन को स्कोर करता है, इसलिए सहायता में गिरावट या मतिभ्रम में वृद्धि अपने आप सामने आ जाती है। +- **ऐसी विफलताएं खोजें जिनके लिए आपने नियम नहीं लिखा।** आवर्ती ऑडिट आपके लॉग को सेशन के बीच माइन करते हैं और त्रुटि क्लस्टर, विलंबता आउटलायर, कम स्कोर और स्टक रन को खोजते हैं, फिर आपको रैंक किए गए, साक्ष्य-समर्थित निष्कर्ष देते हैं। +- **जब यह मायने रखता है तो पृष्ठ प्राप्त करें।** थ्रेसहोल्ड नियम त्रुटि दर, विलंबता, लागत या मूल्यांकनकर्ता स्कोर पर फायर करते हैं और घटनाएं खोलते हैं जिन्हें आप स्वीकार, असाइन और समाधान कर सकते हैं। +- **सादे अंग्रेजी में सवाल पूछें।** डैशबोर्ड में एक AI सहायक आपके अपने डेटा पर "इस हफ्ते प्रोड में गुणवत्ता कैसी है?" का जवाब देता है। यह जो भी परिवर्तन करता है वह अनुमोदन-गेट होता है। +- **अपना डेटा रखें।** Failproof AI Observability स्व-होस्ट किया गया है: इवेंट, प्रॉम्प्ट और विश्लेषण उस बुनियादी ढांचे में रहते हैं जिसे आप नियंत्रित करते हैं। --- -## आप क्या प्राप्त करते हैं +## आपको क्या मिलता है -Failproof AI Observability तीन विचारों के चारों ओर संगठित है (**observe**, **analyze**, और **admin**), जो डैशबोर्ड के बाएं sidebar में प्रतिबिंबित हैं। +Failproof AI Observability तीन विचारों के आसपास संगठित है (**देखें**, **विश्लेषण करें** और **प्रशासन**), जो डैशबोर्ड की बाईं साइडबार में दर्शाए गए हैं। -**Observe** (जो हुआ उसकी कच्ची सच्चाई): +**देखें** (क्या हुआ का कच्चा सच): -- **[Event stream](/hi/agenteye/event-stream)**: हर रन की live, per-step trail (tool calls, model calls, hooks, errors)। -- **[Sessions](/hi/agenteye/sessions)**: वे events रन के प्रति एक पंक्ति में रोल अप किए गए, प्रत्येक को स्कोर करने के लिए तैयार, एक git-शैली के execution ग्राफ़ के साथ। -- **[Performance metrics](/hi/agenteye/telemetry)**: per-surface latency heat-maps और p50/p95/p99 vitals models, tools और hooks के लिए, इसलिए एक tail spike माध्य से अलग होकर दिखता है। -- **[Error tracking](/hi/agenteye/error-tracking)**: सभी गलत चीजों के लिए एक triage surface, एक firing alert से एक क्लिक दूर। +- **[ईवेंट स्ट्रीम](/hi/agenteye/event-stream)**: प्रत्येक रन की लाइव, प्रति-चरण ट्रेल (टूल कॉल, मॉडल कॉल, हुक, त्रुटि)। +- **[सेशन](/hi/agenteye/sessions)**: उन इवेंट्स को प्रति रन एक पंक्ति में रोल अप किया गया है, प्रत्येक स्कोर होने के लिए तैयार है, एक git-शैली के एक्सीक्यूशन ग्राफ़ के साथ। +- **[प्रदर्शन मेट्रिक्स](/hi/agenteye/telemetry)**: मॉडल, टूल और हुक के लिए प्रति-सतह विलंबता हीट-मैप्स और p50/p95/p99 महत्वपूर्ण आंकड़े, इसलिए एक टेल स्पाइक माध्यिका से अलग दिखाई देता है। +- **[त्रुटि ट्रैकिंग](/hi/agenteye/error-tracking)**: हर चीज़ के लिए एक ट्रिएज सतह जो गलत गई, एक क्लिक एक फायर अलर्ट से दूर है। -![Tools observe पृष्ठ: एक latency heat-map, एक percentile band और 24 समय bins पर एक tool-distribution bar](/agenteye/images/tools.png) +![Tools observe page: एक विलंबता हीट-मैप, एक प्रतिशत बैंड, और 24 समय बिन पर एक टूल-वितरण बार](/agenteye/images/tools.png) -*प्रत्येक observe surface एक sparkline और p50/p95/p99 vitals को एक latency heat-map और एक percentile band के साथ जोड़ता है। यहां दिखाया गया है: Tools।* +*प्रत्येक observe सतह एक स्पार्कलाइन और p50/p95/p99 महत्वपूर्ण आंकड़ों को एक विलंबता हीट-मैप और एक प्रतिशत बैंड के साथ जोड़ी गई है। यहां दिखाया गया है: Tools।* -**Analyze** (activity को जवाबों में बदलें): +**विश्लेषण करें** (गतिविधि को उत्तरों में बदलें): -- **[Queries](/hi/agenteye/queries)** और **[dashboards](/hi/agenteye/dashboards)**: आपकी events और evaluations पर saved SQL, साझा, org-scoped dashboards में चार्ट किए गए। -- **[Evaluations](/hi/agenteye/evaluations)**: आपकी अपनी evaluator सेवा द्वारा उत्पादित गुणवत्ता स्कोर, per-score reasoning के साथ। -- **[Audits](/hi/agenteye/audits)**: पुनरावर्ती investigations जो sessions के पार विफलता पैटर्न को सामने लाते हैं। -- **[Alerts](/hi/agenteye/alerts)** और **[incidents](/hi/agenteye/incidents)**: threshold नियम जो आपको पेज करते हैं, साथ ही एक incident workflow उन्हें triage करने के लिए। +- **[क्वेरी](/hi/agenteye/queries)** और **[डैशबोर्ड](/hi/agenteye/dashboards)**: आपके इवेंट्स और मूल्यांकन पर बचाई गई SQL, साझा, org-स्कोप डैशबोर्ड में चार्ट किए गए। +- **[मूल्यांकन](/hi/agenteye/evaluations)**: आपकी अपनी मूल्यांकनकर्ता सेवा द्वारा उत्पादित गुणवत्ता स्कोर, प्रति-स्कोर तर्क के साथ। +- **[ऑडिट](/hi/agenteye/audits)**: आवर्ती जांचें जो सेशन के बीच विफलता पैटर्न को सामने लाती हैं। +- **[अलर्ट](/hi/agenteye/alerts)** और **[घटना](/hi/agenteye/incidents)**: थ्रेसहोल्ड नियम जो आपको पृष्ठ देते हैं, प्लस घटना वर्कफ़्लो उन्हें ट्रिएज करने के लिए। -**Interfaces** (अपने डेटा तक अपने तरीके से पहुंचें): +**इंटरफ़ेस** (अपने डेटा तक अपने तरीके से पहुंचें): -- **[CLI](/hi/agenteye/cli-and-agents)**: terminal या script से अपनी पूरी deployment चलाएं, और एक coding agent को इसे सादे अंग्रेजी में करने दें। -- **[AI assistant](/hi/agenteye/assistant)**: डैशबोर्ड के अंदर सादे अंग्रेजी में अपने एजेंट्स के बारे में सवाल पूछें। -- **REST API**: डैशबोर्ड और CLI जो करते हैं सब कुछ एक REST API द्वारा समर्थित है जिसे आप सीधे एक scoped [API key](/hi/agenteye/api-keys) के साथ कॉल कर सकते हैं — events ingest करें, sessions और evaluations query करें, और dashboards, alerts, audits, users और keys को manage करें, इसलिए आप Failproof AI Observability को अपने स्वयं के tooling में wire कर सकते हैं। +- **[CLI](/hi/agenteye/cli-and-agents)**: टर्मिनल या स्क्रिप्ट से अपनी पूरी डिप्लॉयमेंट चलाएं, और एक कोडिंग एजेंट को सादे अंग्रेजी में ऐसा करने दें। +- **[AI सहायक](/hi/agenteye/assistant)**: डैशबोर्ड के अंदर सीधे सादे अंग्रेजी में अपने एजेंट्स के बारे में सवाल पूछें। +- **REST API**: डैशबोर्ड और CLI जो कुछ भी करते हैं वह एक REST API द्वारा समर्थित है जिसे आप सीधे स्कोप किए गए [API कुंजी](/hi/agenteye/api-keys) के साथ कॉल कर सकते हैं — इवेंट्स अंतर्ग्रहण करें, सेशन और मूल्यांकन क्वेरी करें, और डैशबोर्ड, अलर्ट, ऑडिट, उपयोगकर्ता और कुंजियां प्रबंधित करें, इसलिए आप Failproof AI Observability को अपने स्वयं के उपकरण में वायर कर सकते हैं। -**Admin** (अपनी टीम के लिए इसे चलाएं): +**प्रशासन** (अपनी टीम के लिए इसे चलाएं): -- **[API keys](/hi/agenteye/api-keys)**: collector, dashboard और assistant के लिए scoped tokens। -- **Users**: passwordless, email-based sign-in एक allowlist के साथ। -- **Settings**: per-org configuration, including model context-window overrides के साथ। +- **[API कुंजियां](/hi/agenteye/api-keys)**: संग्राहक, डैशबोर्ड और सहायक के लिए स्कोप किए गए टोकन। +- **उपयोगकर्ता**: पासवर्डलेस, एक अनुमति सूची के साथ ईमेल-आधारित साइन-इन। +- **सेटिंग्स**: प्रति-org कॉन्फ़िगरेशन, जिसमें मॉडल संदर्भ-विंडो ओवरराइड शामिल हैं। --- -## चीजें कैसे फिट होती हैं +## कैसे टुकड़े एक साथ फिट होते हैं -डेटा एक दिशा में बहता है, आपके एजेंट कोड से डैशबोर्ड तक: आपका एजेंट (Python SDK के via) events को agenteye-collector को emit करता है, जो उन्हें सर्वर को भेजता है, जो डैशबोर्ड को serve करता है। दो optional सेवाएं इसे पूरा करती हैं — एक स्कोरिंग सेवा (evaluations) और एक AI assistant सेवा (in-dashboard chat)। +डेटा एक दिशा में बहता है, आपके एजेंट कोड से डैशबोर्ड तक: आपका एजेंट (Python SDK के माध्यम से) agenteye-collector को इवेंट्स उत्सर्जित करता है, जो उन्हें सर्वर को भेजता है, जो डैशबोर्ड को परोसता है। दो वैकल्पिक सेवाएं इसे पूरा करती हैं — एक स्कोरिंग सेवा (मूल्यांकन) और एक AI सहायक सेवा (डैशबोर्ड में चैट)। -- **Python SDK**: आप अपने एजेंट में कुछ `agenteye.event.*` कॉल्स जोड़ते हैं; events को locally buffer किया जाता है। -- **agenteye-collector**: हर एजेंट मशीन पर एक lightweight daemon जो events को batch करता है और सर्वर को भेजता है। -- **Server**: आपके events को ingest करता है, आपके अपने databases में operational state रखता है, और REST API को serve करता है जिसे डैशबोर्ड, CLI और आपके स्वयं के integrations सभी use करते हैं। -- **Dashboard**: जहां आप सबकुछ explore करते हैं। -- **Optional services**: एक स्कोरिंग सेवा (evaluations), और एक AI assistant सेवा (in-dashboard chat)। +- **Python SDK**: आप अपने एजेंट में कुछ `agenteye.event.*` कॉल जोड़ते हैं; इवेंट्स स्थानीय रूप से बफर किए जाते हैं। +- **agenteye-collector**: प्रत्येक एजेंट मशीन पर एक हल्का डेमॉन जो इवेंट्स को बैच करता है और सर्वर को भेजता है। +- **सर्वर**: आपके इवेंट्स को अंतर्ग्रहण करता है, अपने स्वयं के डेटाबेस में परिचालन स्थिति रखता है, और REST API को परोसता है जो डैशबोर्ड, CLI और आपके अपने एकीकरण सभी उपयोग करते हैं। +- **डैशबोर्ड**: जहां आप सब कुछ एक्सप्लोर करते हैं। +- **वैकल्पिक सेवाएं**: एक स्कोरिंग सेवा (मूल्यांकन), और एक AI सहायक सेवा (डैशबोर्ड में चैट)। -docs में उपयोग की गई vocabulary के लिए (*event, session, evaluation, audit, finding, incident*), [Concepts](/hi/agenteye/concepts) देखें। +दस्तावेज़ों में उपयोग की जाने वाली शब्दावली के लिए (*event, session, evaluation, audit, finding, incident*), [अवधारणाएं](/hi/agenteye/concepts) देखें। --- ## Failproof AI Observability प्राप्त करना -Failproof AI Observability एक enterprise उत्पाद है Failproof AI से, और यह Failproof AI Enforcement — policy और guardrail उत्पाद — के साथ काम करता है, Failproof AI ब्रांड के तहत। यह पूरी तरह से अपने स्वयं के environment में चलता है। यदि आपको packages तक access नहीं है अभी भी, एक डेमो का अनुरोध करें और हम आपको set up करेंगे: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) को ईमेल करें। +Failproof AI Observability, Failproof AI का एक एंटरप्राइज़ प्रोडक्ट है, और यह Failproof AI Enforcement — नीति और गार्डरेल प्रोडक्ट — के साथ Failproof AI ब्रांड के तहत काम करता है। यह पूरी तरह से आपके अपने वातावरण में चलता है। यदि आपके पास पैकेज तक पहुंच नहीं है, तो डेमो के लिए अनुरोध करें और हम आपको सेट अप कर देंगे: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) को ईमेल करें। --- ## अगले कदम -- [Concepts](/hi/agenteye/concepts): Failproof AI Observability vocabulary एक जगह पर। -- [Observability](/hi/agenteye/observability): अपने एजेंट्स को जो करते हैं उसे follow करें, रन दर रन। -- [Security](/hi/agenteye/security): कैसे Failproof AI Observability आपके डेटा को isolated रखता है और आपके नियंत्रण में। \ No newline at end of file +- [अवधारणाएं](/hi/agenteye/concepts): Failproof AI Observability शब्दावली एक जगह में। +- [Observability](/hi/agenteye/observability): अपने एजेंट्स को देखें कि वे क्या करते हैं, रन दर रन। +- [सुरक्षा](/hi/agenteye/security): कैसे Failproof AI Observability आपके डेटा को अलग और नियंत्रण में रखता है। \ No newline at end of file diff --git a/docs/hi/agenteye/python-sdk-skill.mdx b/docs/hi/agenteye/python-sdk-skill.mdx index e877d8a5..de8da42b 100644 --- a/docs/hi/agenteye/python-sdk-skill.mdx +++ b/docs/hi/agenteye/python-sdk-skill.mdx @@ -1,133 +1,133 @@ --- title: "Failproof AI Observability Python SDK Agent Skill" -description: "बिना instrumented agent से शुरू करके ऐसे events तक पहुंचें जिन्हें आप देख सकें, आपके coding agent के साथ instrumentation points खोजते हुए, उन्हें लिखते हुए, और यह साबित करते हुए कि वे काम कर रहे हैं।" +description: "Go from an uninstrumented agent to events you can see, with your coding agent finding the instrumentation points, writing them, and proving they landed." --- -अपने coding agent को बताएं *"इस agent में Failproof AI Observability जोड़ें"* और इसे अपना loop पढ़ने दें, काम करें कि instrumentation कहां जाना चाहिए, इसे लिखें, और events को verify करें इससे पहले कि वह काम पूरा करे। +अपने कोडिंग एजेंट को बताएँ *"इस एजेंट में Failproof AI Observability जोड़ें"* और इसे अपने लूप को पढ़ने दें, इन्स्ट्रूमेंटेशन पॉइंट्स का पता लगाने दें, उन्हें लिखने दें, और काम पूरा करने से पहले इवेंट्स को वेरिफाई करने दें। -**Python SDK skill** (`agenteye-python-sdk`) एक *Agent Skill* है: निर्देशों का एक folder जिसे coding agent जैसे Claude Code या Codex demand पर load करता है जब कोई task उससे match करे। यह agent को [Python SDK](/hi/agenteye/python-sdk) का उपयोग करना सिखाता है — यह एक library नहीं है, और यह SDK के काम करने के तरीके में कुछ नहीं बदलता। +**Python SDK स्किल** (`agenteye-python-sdk`) एक *Agent Skill* है: निर्देशों का एक फोल्डर जिसे Claude Code या Codex जैसा कोडिंग एजेंट आवश्यकतानुसार लोड करता है जब कोई कार्य इससे मेल खाता है। यह एजेंट को [Python SDK](/hi/agenteye/python-sdk) का उपयोग करना सिखाता है — यह एक लाइब्रेरी नहीं है, और यह SDK के काम करने के तरीके में कुछ नहीं बदलता। -## Instrumentation लिखना आसान है और आसानी से गलत हो सकता है +## इन्स्ट्रूमेंटेशन लिखना आसान है और चुप-चाप गलत होना भी आसान है -SDK छोटा है: तेरह event methods, सभी keyword-only। एक coding agent [Python SDK](/hi/agenteye/python-sdk) reference को पढ़ सकता है और एक मिनट में plausible instrumentation बना सकता है। +SDK छोटा है: तेरह इवेंट मेथड, सभी कीवर्ड-ओनली। एक कोडिंग एजेंट [Python SDK](/hi/agenteye/python-sdk) रेफरेंस पढ़ सकता है और एक मिनट में प्रशंसनीय इन्स्ट्रूमेंटेशन तैयार कर सकता है। -समस्या यह है कि यह SDK गलत होने पर raise नहीं करता, और गलत instrumentation बिल्कुल सही instrumentation जैसी दिखती है जब तक कोई dashboard नहीं खोलता और इसे खाली नहीं पाता। असली समय खर्च करने वाली गलतियां सभी silence हैं: +समस्या यह है कि यह SDK गलत होने पर चेतावनी नहीं देता, और गलत इन्स्ट्रूमेंटेशन सही होने तक बिल्कुल वैसा ही दिखता है जब तक कोई डैशबोर्ड नहीं खोलता और उसे खाली नहीं पाता। ज्यादा समय खर्च करने वाली गलतियाँ सभी चुप्पियाँ हैं: | गलती | आप क्या देखते हैं | |---|---| -| No `agent_start` | हर event land होता है। Zero sessions। | -| Environment कभी set नहीं होता | सब कुछ काम करता है, `dev` के तहत filed। | -| `outcome="failure"` | Run green दिखता है — केवल `failed`, `error`, `timeout`, `rejected` count होते हैं। | -| Typo'd field name | Accepted होता है और एक नए field के रूप में stored। | -| Thread pool से emitted events | Silently dropped। | +| कोई `agent_start` नहीं | हर इवेंट लैंड करता है। शून्य सेशन। | +| वातावरण कभी सेट नहीं हुआ | सब कुछ काम करता है, `dev` के तहत फाइल किया गया। | +| `outcome="failure"` | रन हरा दिखता है — सिर्फ `failed`, `error`, `timeout`, `rejected` गिने जाते हैं। | +| एक टाइपो किया गया फील्ड नाम | नए फील्ड के रूप में स्वीकार और संग्रहीत। | +| थ्रेड पूल से उत्सर्जित इवेंट्स | चुप-चाप छोड़े जाते हैं। | -इनमें से कोई भी raise नहीं करता। कोई भी tests में दिखाई नहीं देता। हर एक skill में है, एक contract के रूप में stated जिसमें check है जो इसे catch करता है। +इनमें से कोई भी चेतावनी नहीं देता। ये परीक्षणों में नहीं दिखते। प्रत्येक स्किल में है, एक अनुबंध के रूप में कथित, जिस जाँच के साथ इसे पकड़ा जा सकता है। -## यह क्या करता है, क्रम में +## यह क्या करता है, क्रमानुसार -Skill उन्हीं तीन steps को चलाता है जो एक सावधान engineer करेगा: +स्किल एक सावधान इंजीनियर के समान तीन कदम चलाती है: -1. **Plan.** यह आपके agent loop को पढ़ता है और दो सवाल पूछता है जिनका जवाब केवल आप दे सकते हैं: क्या एक run के लिए गिना जाए (`session_id`), और अलग-अलग actors कौन हैं (`agent_id`)। यह code लिखने से पहले उन पर सहमति प्राप्त करता है, क्योंकि बाद में उन्हें बदलने से आपका history split होता है और trends टूट जाते हैं। -2. **Write.** यह identity को एक बार per run bind करता है बजाय हर call site के माध्यम से thread करने के, और एक concurrency-safe shape चुनता है — एक विवरण जो मायने रखता है, क्योंकि स्पष्ट shortcut silently दो overlapping runs को एक session में mix कर सकता है। -3. **Verify.** यह आपके agent को चलाता है और resulting event files को पढ़ता है, यह check करते हुए कि `agent_start` present है, environment सही है, और एक run ने एक session बनाया है। +1. **योजना।** यह आपके एजेंट लूप को पढ़ता है और दो प्रश्न पूछता है जिनका उत्तर केवल आप दे सकते हैं: एक रन क्या माना जाता है (आपका `session_id`), और विशिष्ट अभिनेता कौन हैं (आपका `agent_id`)। यह कोड लिखने से पहले सहमति प्राप्त करता है, क्योंकि बाद में उन्हें बदलने से आपका इतिहास विभाजित हो जाता है और ट्रेंड टूट जाते हैं। +2. **लिखना।** यह प्रति रन एक बार पहचान को बाँधता है बजाय हर कॉल साइट के माध्यम से इसे थ्रेड करने के, और यह एक समवर्ती-सुरक्षित आकार चुनता है — एक विवरण जो मायने रखता है, क्योंकि स्पष्ट शॉर्टकट चुप-चाप दो अतिव्यापी रन को एक सेशन में मिलाता है। +3. **सत्यापन।** यह आपके एजेंट को चलाता है और परिणामी इवेंट फाइलों को पढ़ता है, जाँचता है कि `agent_start` मौजूद है, वातावरण सही है, और एक रन ने एक सेशन बनाया है। -वह तीसरा step है जिसे लोग skip करते हैं। SDK events को local files में लिखता है, तो एक complete integration को एक laptop पर server, API key, या network के बिना proved किया जा सकता है — जो बिल्कुल वही कारण है कि skill इसे करने पर настаивает। +तीसरा कदम वह है जिसे लोग छोड़ देते हैं। SDK इवेंट्स को स्थानीय फाइलों में लिखता है, इसलिए एक पूर्ण एकीकरण को लैपटॉप पर कोई सर्वर, कोई API कुंजी, और कोई नेटवर्क के बिना साबित किया जा सकता है — जो बिल्कुल कारण है कि स्किल इसे करने पर जोर देती है। -## यह अन्य skills से कैसे संबंधित है +## यह अन्य कौशलों से कैसे संबंधित है -तीन skills, एक स्पष्ट split: +तीन कौशल, एक स्वच्छ विभाजन: -| Skill | इसे तब प्राप्त करें जब | यह क्या छूता है | +| कौशल | इसके लिए पहुँचें जब | यह क्या छूता है | |---|---|---| -| **Python SDK skill** (यह पृष्ठ) | आप चाहते हैं कि आपका agent *emit* करे telemetry — "observability जोड़ें", "मेरा agent क्यों दिखाई नहीं दे रहा?" | आपके agent के repo में code लिखता है। कुछ नहीं पढ़ता। | -| **[Evaluator skill](/hi/agenteye/evaluator-skill)** | आप *score* करना चाहते हैं runs — "हमें क्या मापना चाहिए?" | आपके repo में code लिखता है; telemetry पढ़ता है | -| **[CLI skill](/hi/agenteye/cli-skill)** | आप *read* करना चाहते हैं कि क्या हुआ, या अपनी deployment operate करना चाहते हैं | CLI को as you drive करता है, changes सहित | +| **Python SDK स्किल** (यह पृष्ठ) | आप चाहते हैं कि आपका एजेंट *टेलीमेट्री उत्सर्जित करे* — "अवलोकनीयता जोड़ें", "मेरा एजेंट दिख क्यों नहीं रहा?" | आपके एजेंट की रेपो में कोड लिखता है। कुछ नहीं पढ़ता। | +| **[मूल्यांकनकर्ता स्किल](/hi/agenteye/evaluator-skill)** | आप रन को *स्कोर* करना चाहते हैं — "हमें वास्तव में क्या मापना चाहिए?" | आपकी रेपो में कोड लिखता है; टेलीमेट्री पढ़ता है | +| **[CLI स्किल](/hi/agenteye/cli-skill)** | आप *पढ़ना* चाहते हैं कि क्या हुआ, या अपने डिप्लॉयमेंट को संचालित करना चाहते हैं | CLI को आप के रूप में ड्राइव करता है, परिवर्तन सहित | -वे उसी order में hand off करते हैं: यह skill events को flowing करता है, evaluator उन्हें score करता है, CLI उन्हें वापस पढ़ता है। जब तक आपका agent sessions emit नहीं करता तब तक evaluate करने के लिए कुछ नहीं है और read करने के लिए कुछ नहीं है, तो यदि आप scratch से शुरू कर रहे हैं, तो यहां से शुरू करें। +ये उसी क्रम में हस्तांतरित होते हैं: यह स्किल इवेंट्स को प्रवाहित करता है, मूल्यांकनकर्ता उन्हें स्कोर करता है, CLI उन्हें वापस पढ़ता है। जब तक आपका एजेंट सेशन उत्सर्जित नहीं करता, तब तक मूल्यांकन करने के लिए कुछ नहीं है और पढ़ने के लिए कुछ नहीं है, इसलिए यदि आप शुरुआत से शुरू कर रहे हैं, यहीं से शुरू करें। -## Prerequisites +## आवश्यकताएँ -1. **Python 3.10+** और agent codebase जिसे आप instrument करना चाहते हैं। -2. **The SDK.** यह customers को एक private wheel के रूप में distributed किया जाता है एक public index से नहीं — आपके onboarding में यह शामिल है कि इसे कैसे प्राप्त करें और install करें। Skill install path को जानता है और यदि इसे नहीं मिल सकता तो आपसे पूछेगा बजाय अनुमान लगाने के। -3. **कुछ नहीं।** कोई dashboard login नहीं, कोई API key नहीं, कोई network नहीं। Skill SDK द्वारा लिखी जाने वाली event files के विरुद्ध verify करता है, तो यह offline काम पूरा कर सकता है और साबित कर सकता है। +1. **Python 3.10+** और वह एजेंट कोडबेस जिसे आप इंस्ट्रूमेंट करना चाहते हैं। +2. **SDK।** यह ग्राहकों को निजी व्हील के रूप में वितरित किया जाता है न कि सार्वजनिक इंडेक्स से — आपके ऑनबोर्डिंग में यह कवर किया जाता है कि इसे कैसे प्राप्त करें और स्थापित करें। स्किल इंस्टॉल पथ को जानता है और यदि इसे नहीं मिल सकता तो अनुमान लगाने के बजाय आपसे पूछेगा। +3. **कुछ नहीं।** कोई डैशबोर्ड लॉगिन नहीं, कोई API कुंजी नहीं, कोई नेटवर्क नहीं। स्किल उन इवेंट फाइलों के विरुद्ध सत्यापित करता है जो SDK लिखता है, इसलिए यह ऑफलाइन अपना काम पूरा कर सकता है और साबित कर सकता है। -## इसे कहां प्राप्त करें +## इसे कहाँ से प्राप्त करें -Skill public [`FailproofAI/skills`](https://github.com/FailproofAI/skills) collection में रहता है: +स्किल सार्वजनिक [`FailproofAI/skills`](https://github.com/FailproofAI/skills) संग्रह में रहता है: ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -हर project के लिए install करने के लिए `-g` जोड़ें बजाय सिर्फ current के, और `--copy` जोड़ें यदि आपका environment symlinks को follow नहीं करता है। Codex के लिए, `-a codex` pass करें। +`-g` जोड़ें इसे हर प्रोजेक्ट के लिए स्थापित करने के लिए सिर्फ वर्तमान को छोड़कर, और `--copy` यदि आपका पर्यावरण सिम्लिंक्स का पालन नहीं करता। Codex के लिए, `-a codex` पास करें। -## इसे manually install करना +## इसे हाथ से स्थापित करना -Agent Skills `SKILL.md` और references वाले folders हैं। यदि आप installer का उपयोग नहीं करना चाहते: +Agent Skills ऐसे फोल्डर हैं जिनमें `SKILL.md` और संदर्भ होते हैं। यदि आप इंस्टॉलर का उपयोग नहीं करना पसंद करते हैं: -- **Claude Code**: `agenteye-python-sdk/` folder को `~/.claude/skills/` (हर project) या `/.claude/skills/` (सिर्फ वह repo) में copy करें। Claude Code इसे automatically discover करता है — `/skills` list check करें, या बस कुछ ऐसा पूछें जो इससे match करे। -- **Codex**: Codex एक ही `SKILL.md` पढ़ता है। Bundled `agents/openai.yaml` `allow_implicit_invocation: true` set करता है, तो यह auto-selected होता है जब कोई task match करे; अन्यथा इसे `$agenteye-python-sdk` के रूप में invoke करें। +- **Claude Code**: `agenteye-python-sdk/` फोल्डर को `~/.claude/skills/` (हर प्रोजेक्ट) या `/.claude/skills/` (सिर्फ वह रेपो) में कॉपी करें। Claude Code स्वचालित रूप से इसे खोजता है — `/skills` सूची जाँचें, या बस कुछ ऐसा पूछें जो इससे मेल खाता हो। +- **Codex**: Codex वही `SKILL.md` पढ़ता है। बंडल किया गया `agents/openai.yaml` `allow_implicit_invocation: true` सेट करता है, इसलिए यह स्वचालित रूप से चुना जाता है जब कोई कार्य मेल खाता है; अन्यथा इसे `$agenteye-python-sdk` के रूप में आमंत्रित करें। -अपने agent को **उस repository में** run करें जिसमें आप instrumented करना चाहते हैं — skill code लिखने से पहले आपके agent loop को पढ़ता है। +**उस रेपोजिटरी में अपना एजेंट चलाएँ जिसमें वह कोड है जिसे आप इंस्ट्रूमेंट करना चाहते हैं** — स्किल कुछ भी प्रस्तावित करने से पहले आपके एजेंट लूप को पढ़ता है। -## एक session कैसा दिखता है +## एक सेशन कैसा दिखता है ```text -आप ▸ इस agent में Failproof AI Observability जोड़ें। +आप ▸ इस एजेंट में Failproof AI Observability जोड़ें। -agent ▸ आपके loop को read करें — tools.py में एक tool dispatcher, llm.py - में एक Anthropic wrapper। कुछ भी लिखने से पहले दो सवाल। +एजेंट ▸ आपका लूप पढ़ें — tools.py में एक टूल डिस्पैचर, llm.py में एक + Anthropic रैपर। कोड लिखने से पहले दो प्रश्न। - क्या एक run के लिए गिना जाए? आप requests को concurrently - handle करते हैं, तो मैं ctx.request_id में request id का उपयोग - करूंगा — तब यहां एक session और आपके logs में एक request - एक ही string हैं। + एक रन क्या माना जाता है? आप अनुरोधों को समवर्ती रूप से + संभालते हैं, इसलिए मैं ctx.request_id में आपके पास पहले से + मौजूद अनुरोध आईडी का उपयोग करूँ — तब यहाँ एक सेशन और + आपके लॉग में एक अनुरोध समान स्ट्रिंग है। - और actors कौन हैं? मैं एक planner path और एक researcher path - देखता हूं। उन्हें अलग से label करें, या यह आपके लिए एक agent है? + और अभिनेता कौन हैं? मैं एक योजनाकार पथ और एक शोधकर्ता + पथ देखता हूँ। उन्हें अलग से लेबल करें, या यह आपके लिए + एक एजेंट है? -आप ▸ Request id सही है। वे एक agent हैं, इसे "assistant" कहें। +आप ▸ अनुरोध आईडी सही है। वे एक एजेंट हैं, इसे "सहायक" कहें। -agent ▸ पूरा हुआ। Dispatcher और LLM client को wrap किया; - agent_start और agent_end handle_request को bracket करते हैं, - error path सहित। Identity के लिए एक context-local का उपयोग - किया — आपका dispatcher tools को एक thread pool में चलाता है, - और सरल approach concurrent runs को एक session में mix कर - सकता था बिना complain किए। +एजेंट ▸ हो गया। डिस्पैचर और LLM क्लाइंट को लपेटा; agent_start और + agent_end, त्रुटि पथ सहित handle_request को कोष्ठक करते हैं। + पहचान के लिए संदर्भ-स्थानीय का उपयोग किया — आपका + डिस्पैचर थ्रेड पूल में उपकरण चलाता है, और सरल दृष्टिकोण + समवर्ती रन को बिना शिकायत के एक सेशन में मिलाता। - एक real run के विरुद्ध verify किया: 4 files में 11 events — + वास्तविक रन के विरुद्ध सत्यापित: 4 फाइलों में 11 इवेंट्स — agent_start, model_request/response, tool_use/tool_result x3, - agent_end (outcome=success)। environment=production, हर request - के लिए एक session, durations paired। + agent_end (outcome=success)। environment=production, प्रति अनुरोध + एक सेशन, जोड़े गए अवधि। - एक चीज जो मैंने नहीं की: आपके batch.py में worker pool - सीधे executor में submit करता है, तो वहां से events - drop होते। क्या आप चाहते हैं कि मैं उन्हें भी fix करूं? + एक बात जो मैंने नहीं की: आपका worker pool batch.py में + सीधे executor को सबमिट करता है, इसलिए वहाँ से इवेंट्स + छोड़े जाएँगे। क्या आप चाहते हैं कि मैं वे भी ठीक करूँ? ``` -ध्यान देने योग्य pattern: यह code लिखने से पहले code को पढ़ा, केवल वे सवाल पूछे जिनका जवाब आप दे सकते हैं, एक id को reuse किया जो आप पहले से had करते हैं, concurrency-safe shape को चुना *क्योंकि* इसने एक thread pool देखा, और **actual events को पढ़कर verify किया** बजाय सफलता की घोषणा करने के — फिर उस एक जगह को flag किया जहां यह जानता था कि silently fail होगा। +ध्यान देने योग्य पैटर्न: यह प्रस्ताव देने से पहले कोड पढ़ता है, केवल उन प्रश्नों को पूछता है जिनका आप उत्तर दे सकते हैं, एक आईडी को पुनः उपयोग करता है जो आप पहले से रखते हैं, समवर्ती-सुरक्षित आकार चुनता है *क्योंकि* यह थ्रेड पूल देखता है, और **सफलता घोषित करने के बजाय वास्तविक इवेंट्स पढ़कर सत्यापित करता है** — फिर वह एक जगह को चिन्हित करता है जहाँ यह जानता है कि चुप-चाप विफल होगा। ## आप इससे क्या पूछ सकते हैं -- *"मेरा agent dashboard पर क्यों नहीं दिख रहा है?"* → ladder को walk करता है: क्या events write हो रहे हैं, क्या `agent_start` है, क्या environment सही है, क्या collector एक ही जगह से read कर रहा है। -- *"सब कुछ dev के तहत land हो रहा है।"* → environment कभी set नहीं हुआ, या एक later call द्वारा reset हुआ। -- *"Token tracking जोड़ें।"* → आपके LLM wrapper को खोजता है और model, stop reason, और usage record करता है। -- *"Sub-agents को भी instrument करें।"* → एक session, distinct agent labels, अपने parent के तहत nested। -- *"Instrumentation के लिए tests लिखें।"* → SDK को एक temporary directory की ओर point करता है और इसके द्वारा लिखी गई events पर assert करता है। +- *"मेरा एजेंट डैशबोर्ड पर क्यों नहीं दिख रहा है?"* → सीढ़ी चढ़ता है: क्या इवेंट्स लिखे जा रहे हैं, क्या `agent_start` है, क्या वातावरण सही है, क्या कलेक्टर समान जगह पढ़ रहा है। +- *"सब कुछ dev के तहत लैंड हो रहा है।"* → वातावरण कभी सेट नहीं किया गया, या बाद की कॉल द्वारा रीसेट किया गया। +- *"टोकन ट्रैकिंग जोड़ें।"* → आपके LLM रैपर को ढूँढता है और मॉडल, रोक कारण, और उपयोग रिकॉर्ड करता है। +- *"सब-एजेंट्स को भी इंस्ट्रूमेंट करें।"* → एक सेशन, विशिष्ट एजेंट लेबल, अपने माता-पिता के तहत नेस्टेड। +- *"इन्स्ट्रूमेंटेशन के लिए परीक्षण लिखें।"* → SDK को एक अस्थायी निर्देशिका की ओर इशारा करता है और इवेंट्स पर assert करता है जो यह लिखता है। -## इस पर ध्यान दें +## क्या देखने के लिए है -**इसे verify करने दें।** वह step जो इस skill को उपयोग करने के लायक बनाता है वह आखिरी है — आपके agent को चलाना और events को वापस पढ़ना। एक agent जो instrumentation लिखता है और रुकता है आसान आधा किया है, और आधा जो silently fail होता है वह दूसरा है। +**इसे सत्यापित करने दें।** वह कदम जो इस स्किल को उपयोग के लायक बनाता है, अंतिम है — आपके एजेंट को चलाना और इवेंट्स को वापस पढ़ना। एक एजेंट जो इन्स्ट्रूमेंटेशन लिखता है और रुकता है, आसान आधा किया है, और आधा जो चुप-चाप विफल होता है, दूसरा है। -**Names पर code से पहले सहमति प्राप्त करें।** `session_id` और `agent_id` वह axes हैं जिन पर हर surface group करता है। उन्हें बाद में rename करने से history split होता है: पुरानी runs पुरानी labels रखती हैं और आपके trends टूट जाते हैं। Skill पूछेगा; answer एक मिनट के विचार के लायक है। +**कोड से पहले नाम सहमत करें।** `session_id` और `agent_id` वे अक्ष हैं जिन्हें हर सतह द्वारा समूहीकृत किया जाता है। बाद में उन्हें नाम देना इतिहास को विभाजित करता है: पुराने रन पुराने लेबल रखते हैं और आपके ट्रेंड टूट जाते हैं। स्किल पूछेगा; उत्तर एक मिनट के विचार के लायक है। -**यदि आपका agent SDK को एक public index से install करने का प्रस्ताव देता है, तो skill load नहीं हुई।** SDK privately distributed है। वह प्रस्ताव एक reliable tell है कि आपका coding agent skill को follow करने के बजाय अनुमान लगा रहा है — इसे वहीं रोकें और check करें कि skill install है। +**यदि आपका एजेंट सार्वजनिक इंडेक्स से SDK स्थापित करने का प्रस्ताव देता है, तो स्किल लोड नहीं हुई।** SDK को निजी तरीके से वितरित किया जाता है। यह प्रस्ताव एक विश्वसनीय संकेत है कि आपका कोडिंग एजेंट स्किल का पालन करने के बजाय अनुमान लगा रहा है — वहाँ इसे रोकें और स्किल की स्थापना जाँचें। -इसके आगे इसका blast radius छोटा है: यह आपकी working directory में code लिखता है और event files जहां आप कहते हैं। यह अपनी deployment से कुछ नहीं पढ़ता और इसके बारे में कुछ नहीं बदलता। +इसके अलावा, इसकी विस्फोट त्रिज्या छोटी है: यह आपकी कार्य निर्देशिका में कोड और उन इवेंट फाइलों को लिखता है जहाँ आप बताते हैं। यह आपके डिप्लॉयमेंट से कुछ नहीं पढ़ता और उसमें कुछ नहीं बदलता। ## अगले कदम -- **[Python SDK](/hi/agenteye/python-sdk)**: complete event reference — हर event type और field — जो यह skill automate करता है। -- **[Sessions](/hi/agenteye/sessions)**: आपका instrumentation क्या produce करता है एक बार events land हो जाएं। -- **[Evaluator Agent Skill](/hi/agenteye/evaluator-skill)**: अगला step एक बार runs land होने लगें — उन्हें score करना। -- **[CLI Agent Skill](/hi/agenteye/cli-skill)**: आपकी telemetry को वापस read करना। \ No newline at end of file +- **[Python SDK](/hi/agenteye/python-sdk)**: संपूर्ण इवेंट संदर्भ — हर इवेंट प्रकार और फील्ड — इस स्किल के पीछे जो स्वचालित करता है। +- **[सेशन](/hi/agenteye/sessions)**: आपका इन्स्ट्रूमेंटेशन एक बार इवेंट्स लैंड करने के बाद क्या उत्पादित करता है। +- **[मूल्यांकनकर्ता Agent Skill](/hi/agenteye/evaluator-skill)**: अगला कदम एक बार रन लैंड करने के बाद — उन्हें स्कोर करना। +- **[CLI Agent Skill](/hi/agenteye/cli-skill)**: आपकी टेलीमेट्री को वापस पढ़ना। \ No newline at end of file diff --git a/docs/hi/agenteye/python-sdk.mdx b/docs/hi/agenteye/python-sdk.mdx index bb8a4269..de82afbd 100644 --- a/docs/hi/agenteye/python-sdk.mdx +++ b/docs/hi/agenteye/python-sdk.mdx @@ -1,13 +1,14 @@ --- title: "Python SDK" -description: "अपने AI एजेंट्स को प्रोडक्शन में बिल्कुल देखें: हर एजेंट रन, टूल कॉल, मॉडल रिक्वेस्ट, हुक, और मानव हस्तक्षेप।" +description: "अपने AI एजेंटों ने प्रोडक्शन में क्या किया यह बिल्कुल देखें: हर एजेंट रन, टूल कॉल, मॉडल रिक्वेस्ट, हुक, और मानव हस्तक्षेप।" --- -अपने AI एजेंट्स को प्रोडक्शन में बिल्कुल देखें: हर एजेंट रन, टूल कॉल, मॉडल रिक्वेस्ट, हुक, और मानव हस्तक्षेप। Failproof AI Observability Python SDK आपके एजेंट कोड के अंदर से उस ट्रेल को रिकॉर्ड करता है ताकि आप डीबग, ऑडिट, और मूल्यांकन कर सकें कि क्या हुआ। जब भी आप Failproof AI Observability को अपने एजेंट्स को देखना चाहते हैं, तब इसका उपयोग करें। -हुड के नीचे, SDK स्ट्रक्चर्ड ईवेंट्स को लोकल JSONL फाइलों में लिखता है, और कलेक्टर डेमन उन्हें चुनता है और स्वचालित रूप से प्लेटफॉर्म को भेज देता है। आप इन फाइलों को स्वयं प्रबंधित नहीं करते हैं। +अपने AI एजेंटों ने प्रोडक्शन में क्या किया यह बिल्कुल देखें: हर एजेंट रन, टूल कॉल, मॉडल रिक्वेस्ट, हुक, और मानव हस्तक्षेप। Failproof AI Observability Python SDK आपके एजेंट कोड के अंदर से उस ट्रेल को रिकॉर्ड करता है ताकि आप डीबग कर सकें, ऑडिट कर सकें, और मूल्यांकन कर सकें कि क्या हुआ। जब भी आप चाहें Failproof AI Observability को अपने एजेंटों को ऑब्जर्व करने के लिए इसका उपयोग करें। -> **सुझाव:** Failproof AI Observability के लिए नए हैं? यह पृष्ठ संपूर्ण SDK ईवेंट संदर्भ है। +हुड के तहत, SDK संरचित इवेंट्स को लोकल JSONL फ़ाइलों में लिखता है, और कलेक्टर डेमन उन्हें उठाता है और स्वचालित रूप से प्लेटफॉर्म को भेजता है। आप इन फ़ाइलों को स्वयं प्रबंधित नहीं करते हैं। + +> **सुझाव:** Failproof AI Observability में नए हैं? यह पृष्ठ पूर्ण SDK इवेंट संदर्भ है।
@@ -17,15 +18,15 @@ description: "अपने AI एजेंट्स को प्रोडक् ## इंस्टॉलेशन -SDK को ग्राहकों को एक प्राइवेट व्हील के रूप में वितरित किया जाता है, न कि किसी सार्वजनिक पैकेज इंडेक्स से। आपके ऑनबोर्डिंग में इसे कैसे प्राप्त करें, इंस्टॉल करें, और पिन करें, यह दिया गया है — यदि आपको एक्सेस की आवश्यकता है तो अपने Failproof AI संपर्क से बात करें। +SDK को ग्राहकों को सार्वजनिक पैकेज इंडेक्स से नहीं बल्कि निजी व्हील के रूप में वितरित किया जाता है। आपका ऑनबोर्डिंग कवर करता है कि इसे कैसे प्राप्त करें, इंस्टॉल करें, और इसे कैसे पिन करें — अगर आपको एक्सेस की आवश्यकता है तो अपने Failproof AI संपर्क से बात करें। -एक बार यह इंस्टॉल हो जाए, तो पुष्टि करें कि आपके पास यह है: +एक बार इंस्टॉल होने के बाद, पुष्टि करें कि आपके पास यह है: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -क्या कोडिंग एजेंट को पूरा इंटीग्रेशन करने देना पसंद करते हैं? [Python SDK Agent Skill](/hi/agenteye/python-sdk-skill) इंस्टॉल पाथ को जानता है, इंस्ट्रूमेंटेशन पॉइंट्स की योजना बनाता है, उन्हें लिखता है, और ईवेंट्स के आने की पुष्टि करता है। +क्या आप एक कोडिंग एजेंट को पूरा एकीकरण करने देना पसंद करते हैं? [Python SDK Agent Skill](/hi/agenteye/python-sdk-skill) इंस्टॉल पाथ जानता है, इंस्ट्रूमेंटेशन पॉइंट्स की योजना बनाता है, उन्हें लिखता है, और इवेंट्स लैंड होने की पुष्टि करता है। --- @@ -57,9 +58,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### असली कॉल को इंस्ट्रूमेंट करना +### वास्तविक कॉल को इंस्ट्रूमेंट करना -व्यवहार में आप अपने मौजूदा एजेंट कोड को लपेटते हैं। एक मॉडल कॉल को `model_request` से पहले और `model_response` के बाद ब्रैकेट करें, ताकि दोनों ईवेंट्स असली रिक्वेस्ट को स्पैन करें और Failproof AI Observability उन्हें जोड़ सकें: +व्यावहारिक रूप से आप अपने मौजूदा एजेंट कोड को लपेटते हैं। मॉडल कॉल को `model_request` से पहले और `model_response` के बाद ब्रैकेट करें, ताकि दोनों इवेंट्स वास्तविक रिक्वेस्ट को स्पैन करें और Failproof AI Observability उन्हें जोड़ी सके: ```python import anthropic @@ -94,11 +95,11 @@ agenteye.event.model_response( ) ``` -टूल कॉल्स को `tool_use` और `tool_result` के साथ समान तरीके से लपेटें, जोड़ी में एक ही `tool_call_id` का पुन: उपयोग करें। +टूल कॉल्स को उसी तरह से `tool_use` और `tool_result` के साथ लपेटें, जोड़ी में एक ही `tool_call_id` का पुनः उपयोग करें। -यहाँ देखें कि वे ईवेंट्स डैशबोर्ड पर कैसे दिखते हैं, प्रकार के अनुसार रंग-कोडित और पर्यावरण, एजेंट, और सेशन के अनुसार फ़िल्टर योग्य: +यहाँ वह है कि एक बार वे डैशबोर्ड में पहुँचने के बाद ये इवेंट्स कैसे दिखते हैं, टाइप के आधार पर रंग-कोडित और पर्यावरण, एजेंट, और सेशन द्वारा फ़िल्टर योग्य: -![लाइव ईवेंट्स स्ट्रीम, ईवेंट प्रकार के अनुसार रंग-कोडित और पर्यावरण, एजेंट, और सेशन के अनुसार फ़िल्टर योग्य](/agenteye/images/events-stream.png) +![लाइव इवेंट्स स्ट्रीम, इवेंट टाइप के आधार पर रंग-कोडित और पर्यावरण, एजेंट, और सेशन द्वारा फ़िल्टर योग्य](/agenteye/images/events-stream.png) --- @@ -106,23 +107,23 @@ agenteye.event.model_response( ```python agenteye.configure( - base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye - flush_interval=0.5, # float, seconds between flush cycles - environment=None, # str | None. Deployment environment label + base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME या ~/.agenteye + flush_interval=0.5, # float, फ्लश साइकल के बीच सेकंड + environment=None, # str | None. तैनाती पर्यावरण लेबल ) ``` -किसी भी `event.*` कॉल से पहले एक बार कॉल करें। लोप करना सुरक्षित है; डिफ़ॉल्ट्स बॉक्स से बाहर काम करते हैं। सभी तर्क कीवर्ड-केवल हैं; उन्हें ऊपर दिखाए गए के अनुसार नाम से पास करें। +किसी भी `event.*` कॉल से पहले एक बार कॉल करें। छोड़ना सुरक्षित है; डिफ़ॉल्ट बाहर काम करते हैं। सभी आर्गुमेंट्स केवल कीवर्ड हैं; उन्हें ऊपर दिखाए गए नाम से पास करें। जब `base_dir` `None` है (डिफ़ॉल्ट), SDK `$AGENTEYE_HOME` को पढ़ता है यदि सेट है, -अन्यथा `~/.agenteye` पर फॉल बैक करता है। यह कलेक्टर के अपने रेज़ोल्यूशन से मेल खाता है, -इसलिए एक एकल `AGENTEYE_HOME` env var SDK और कलेक्टर दोनों के लिए साझा ईवेंट स्पूल को कॉन्फ़िगर करता है। +अन्यथा `~/.agenteye` पर वापस आता है। यह कलेक्टर के अपने रिजोल्यूशन से मेल खाता है, +इसलिए एक एकल `AGENTEYE_HOME` env var SDK और कलेक्टर दोनों के लिए साझा इवेंट स्पूल को कॉन्फ़िगर करता है। --- ## पर्यावरण -हर ईवेंट को एक डिप्लॉयमेंट पर्यावरण के साथ लेबल करें (`production`, `staging`, `qa`, `canary`, आदि)। इसे एक बार सेट करें; SDK इसे हर ईवेंट में स्वचालित रूप से संलग्न करता है। +हर इवेंट को तैनाती पर्यावरण (`production`, `staging`, `qa`, `canary`, आदि) के साथ लेबल करें। इसे एक बार सेट करें; SDK इसे हर इवेंट में स्वचालित रूप से संलग्न करता है। **विकल्प 1: `configure()` के माध्यम से:** @@ -136,49 +137,49 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**प्राथमिकता:** `configure(environment=...)` पर्यावरण चर पर जीत जाता है। यदि कोई भी सेट नहीं है, तो `"dev"` पर डिफॉल्ट करता है। +**प्राथमिकता:** `configure(environment=...)` पर्यावरण चर पर जीतता है। अगर कोई भी सेट नहीं है, तो डिफ़ॉल्ट `"dev"` है। -पर्यावरण मान डैशबोर्ड में एक प्रथम-श्रेणी फ़िल्टर के रूप में दिखाई देता है और तेज़ क्वेरीज़ के लिए सर्वर पर संग्रहीत होता है। +पर्यावरण मान डैशबोर्ड में प्रथम-श्रेणी फ़िल्टर के रूप में दिखाई देता है और तेजी से क्वेरीज़ के लिए सर्वर पर संग्रहीत है। -> **चेतावनी:** पर्यावरण मानों में एक शाब्दिक `,` कोमा नहीं होना चाहिए। डैशबोर्ड फ़िल्टर्स वायर पर अल्पविराम-सीमांकित मल्टी-सिलेक्ट का उपयोग करते हैं (`?environment=prod,staging`), इसलिए `prod,blue` नामित एक पर्यावरण दो मानों में विभाजित हो जाएगा। कोमा-युक्त वातावरण वाली ईवेंट्स इनजेस्ट समय पर खारिज कर दी जाती हैं। +> **चेतावनी:** पर्यावरण मानों में शाब्दिक `,` अल्पविराम नहीं हो सकता। डैशबोर्ड फ़िल्टर तार पर अल्पविराम-सीमांकित बहु-चयन का उपयोग करते हैं (`?environment=prod,staging`), इसलिए `prod,blue` नाम का एक पर्यावरण दो मानों में विभाजित हो जाएगा। अल्पविराम-युक्त पर्यावरण वाले इवेंट्स इनजेस्ट समय पर अस्वीकृत हैं। --- ## डेटा और गोपनीयता -SDK केवल उन फील्ड्स को रिकॉर्ड करता है जो आप स्पष्ट रूप से पास करते हैं। प्रॉम्प्ट्स, मैसेज, टूल इनपुट और आउटपुट्स, और मॉडल कंटेंट केवल इसलिए कैप्चर किए जाते हैं क्योंकि आप उन्हें एक `event.*` कॉल में सौंपते हैं। कुछ भी आपकी प्रक्रिया से नहीं पढ़ा जाता है या निहित रूप से कैप्चर नहीं किया जाता है। कोई भी फील्ड जो आप अनसेट छोड़ते हैं वह ईवेंट से पूरी तरह से छोड़ दिया जाता है; यह डिस्क पर लिखा नहीं जाता है। +SDK केवल उन फ़ील्ड्स को रिकॉर्ड करता है जो आप स्पष्ट रूप से पास करते हैं। प्रॉम्प्ट्स, संदेश, टूल इनपुट और आउटपुट, और मॉडल कंटेंट केवल इसलिए कैप्चर किए जाते हैं क्योंकि आप उन्हें `event.*` कॉल पर पास करते हैं। कुछ भी आपकी प्रक्रिया से नहीं पढ़ा जाता है या निहित रूप से कैप्चर नहीं किया जाता है। कोई भी फ़ील्ड जो आप अनसेट छोड़ते हैं वह पूरी तरह से इवेंट से हटा दिया जाता है; इसे डिस्क पर नहीं लिखा जाता है। -जो रिडेक्शन को आपकी पसंद और आपकी जिम्मेदारी बनाता है। यदि कोई प्रॉम्प्ट या टूल पेलोड में PII या सीक्रेट्स हैं जिन्हें आप स्टोर नहीं करना चाहते हैं, तो आप उन्हें ईवेंट मेथड में पास करने से पहले स्ट्रिप या मास्क करें। +यह रिडैक्शन को आपकी पसंद और आपकी जिम्मेदारी बनाता है। अगर कोई प्रॉम्प्ट या टूल पेलोड में PII या सीक्रेट्स हैं जिन्हें आप स्टोर नहीं करना चाहते हैं, तो इवेंट मेथड को पास करने से पहले उन्हें स्ट्रिप या मास्क करें। --- -## ईवेंट संदर्भ +## इवेंट संदर्भ -अधिकांश ईवेंट्स स्टार्ट/एंड पेयर्स में आते हैं जो एक कोरिलेशन ID साझा करते हैं: `tool_use` और `tool_result` एक `tool_call_id` साझा करते हैं, `hook_triggered` और `hook_completed` एक `hook_id` साझा करते हैं, और `human_wait` और `human_input` एक `input_id` साझा करते हैं। स्टार्ट ईवेंट उत्सर्जित करें, काम करें, फिर एंड ईवेंट को समान ID के साथ उत्सर्जित करें। Failproof AI Observability पेयर को मेल करता है और आपके लिए `duration_ms` की गणना करता है, इसलिए आप कभी `duration_ms` स्वयं पास नहीं करते हैं। +अधिकांश इवेंट्स स्टार्ट/एंड जोड़ियों में आते हैं जो एक सहसंबंध ID साझा करते हैं: `tool_use` और `tool_result` एक `tool_call_id` साझा करते हैं, `hook_triggered` और `hook_completed` एक `hook_id` साझा करते हैं, और `human_wait` और `human_input` एक `input_id` साझा करते हैं। स्टार्ट इवेंट उत्सर्जित करें, काम करें, फिर एंड इवेंट को उसी ID के साथ उत्सर्जित करें। Failproof AI Observability जोड़ी को मैच करता है और आपके लिए `duration_ms` की गणना करता है, इसलिए आप कभी भी `duration_ms` को स्वयं पास नहीं करते हैं। -![एक सेशन का git-शैली एक्सीक्यूशन ग्राफ इसकी ईवेंट टाइमलाइन के साथ, पेयर्ड ईवेंट्स से पुनर्निर्मित, टूल/मॉडल/हुक ब्रेकडाउन पैनल के साथ](/agenteye/images/session-detail.png) +![एक सेशन का गिट-स्टाइल एक्सीक्यूशन ग्राफ इसकी इवेंट टाइमलाइन के बगल में, जोड़ी इवेंट्स से पुनर्निर्मित, टूल/मॉडल/हुक ब्रेकडाउन पैनल के साथ](/agenteye/images/session-detail.png) -सभी ईवेंट मेथड्स को ये दो फील्ड्स आवश्यक हैं: +सभी इवेंट मेथड्स को ये दो फ़ील्ड्स आवश्यक हैं: -| फील्ड | प्रकार | विवरण | +| फ़ील्ड | टाइप | विवरण | |---|---|---| -| `session_id` | `str` | टॉप-लेवल एजेंट रन को पहचानता है | -| `agent_id` | `str` | पहचानता है कि सेशन के भीतर कौन-सा एजेंट ईवेंट उत्सर्जित किया | +| `session_id` | `str` | शीर्ष-स्तरीय एजेंट रन को पहचानता है | +| `agent_id` | `str` | पहचानता है कि सेशन के भीतर कौन सा एजेंट इवेंट उत्सर्जित किया | -सभी मेथड्स कस्टम मेटाडेटा के लिए मनमाना `**kwargs` भी स्वीकार करते हैं ([कस्टम फील्ड्स](#custom-fields) देखें)। +सभी मेथड्स कस्टम मेटाडेटा के लिए मनमानी `**kwargs` भी स्वीकार करते हैं (देखें [कस्टम फ़ील्ड्स](#custom-fields))। --- ### `event.agent_start()` -जब कोई एजेंट काम शुरू करता है तो उत्सर्जित होता है। +जब कोई एजेंट काम शुरू करता है तो उत्सर्जित। ```python agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - nested agents के लिए parent agent_id + parent_id=None, # str | None - नेस्टेड एजेंट्स के लिए पैरेंट agent_id ) ``` @@ -186,7 +187,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -जब कोई एजेंट काम पूरा करता है तो उत्सर्जित होता है। +जब कोई एजेंट काम समाप्त करता है तो उत्सर्जित। ```python agenteye.event.agent_end( @@ -201,14 +202,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -जब कोई एजेंट एक टूल को लागू करता है तो उत्सर्जित होता है। `tool_result` के साथ पेयर करें; SDK स्वचालित रूप से `duration_ms` की गणना करता है। +जब कोई एजेंट एक टूल को इनवोक करता है तो उत्सर्जित। `tool_result` के साथ जोड़ी बनाएं; SDK स्वचालित रूप से `duration_ms` की गणना करता है। ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", - tool_name="web_search", # str, required - tool_call_id="toolu_01", # str, required - matching tool_result के लिए कोरिलेशन की + tool_name="web_search", # str, आवश्यक + tool_call_id="toolu_01", # str, आवश्यक - मिलान करने वाले tool_result के लिए सहसंबंध कुंजी input={"query": "..."}, # dict | None ) ``` @@ -217,16 +218,16 @@ agenteye.event.tool_use( ### `event.tool_result()` -जब कोई टूल वापस आता है तो उत्सर्जित होता है। `tool_call_id` के माध्यम से `tool_use` के साथ कोरिलेट होता है। +जब कोई टूल रिटर्न करता है तो उत्सर्जित। `tool_call_id` के माध्यम से `tool_use` से सहसंबंधित है। ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # prior tool_use से मेल खाना चाहिए + tool_call_id="toolu_01", # पूर्व tool_use से मेल खाना चाहिए output={"results": ["..."]}, # Any | None - error=None, # str | None - यदि टूल ने raise किया तो सेट करें + error=None, # str | None - सेट करें यदि टूल ने उठाया # duration_ms स्वचालित रूप से गणना की जाती है - इसे पास न करें ) ``` @@ -235,60 +236,60 @@ agenteye.event.tool_result( ### `event.model_request()` -LLM को एक प्रॉम्प्ट भेजने से पहले उत्सर्जित होता है। +LLM को प्रॉम्प्ट भेजने से ठीक पहले उत्सर्जित। ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - कोई भी provider/model स्ट्रिंग; सत्यापित नहीं है - messages=[ # list[dict] | None - कनवर्सेशन टर्न्स + model="claude-sonnet-4-6", # str | None - कोई भी प्रदाता/मॉडल स्ट्रिंग; सत्यापित नहीं है + messages=[ # list[dict] | None - बातचीत के मोड़ {"role": "user", "content": "..."}, ], - system="You are helpful.", # Any | None - str या content blocks की list - tools=[ # list[dict] | None - मॉडल को दी गई tool schemas + system="You are helpful.", # Any | None - str या कंटेंट ब्लॉक्स की सूची + tools=[ # list[dict] | None - मॉडल को पेश किए गए टूल स्कीमा {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -`messages` एंट्रीज़ या तो एक सादे स्ट्रिंग `content` या Anthropic-शैली list-of-blocks `content` स्वीकार करते हैं। सैम्पलिंग पैरामीटर्स (`temperature`, `max_tokens`, आदि) अतिरिक्त kwargs के रूप में पास किए जा सकते हैं। +`messages` एंट्रीज सादे स्ट्रिंग `content` या Anthropic-स्टाइल ब्लॉक्स-की-सूची `content` स्वीकार करती हैं। सैंपलिंग पैरामीटर्स (`temperature`, `max_tokens`, आदि) अतिरिक्त kwargs के रूप में पास किए जा सकते हैं। --- ### `event.model_response()` -जब LLM एक response वापस करता है तो उत्सर्जित होता है। +जब LLM एक प्रतिक्रिया रिटर्न करता है तो उत्सर्जित। ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - कोई भी provider/model स्ट्रिंग; सत्यापित नहीं है + model="claude-sonnet-4-6", # str | None - कोई भी प्रदाता/मॉडल स्ट्रिंग; सत्यापित नहीं है stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None - content=[ # Any | None - str, या Anthropic-शैली content blocks की list + content=[ # Any | None - str, या कंटेंट ब्लॉक्स की सूची {"type": "text", "text": "..."}, ], role="assistant", # str | None ) ``` -`content` या तो एक सादे स्ट्रिंग (सामान्य providers) या Anthropic-शैली content blocks की एक list स्वीकार करता है। टूल कॉल्स `content` के अंदर `{"type": "tool_use", ...}` ब्लॉक्स के रूप में रहते हैं, कोई अलग `tool_calls` फील्ड नहीं। +`content` सादे स्ट्रिंग (सामान्य प्रदाता) या Anthropic-स्टाइल कंटेंट ब्लॉक्स की सूची स्वीकार करता है। टूल कॉल्स `content` के अंदर `{"type": "tool_use", ...}` ब्लॉक्स के रूप में रहते हैं, कोई अलग `tool_calls` फ़ील्ड नहीं। --- ### `event.hook_triggered()` -जब कोई हुक फायर होता है तो उत्सर्जित होता है। `hook_completed` के साथ पेयर करें; SDK स्वचालित रूप से `duration_ms` की गणना करता है। +जब कोई हुक फायर करता है तो उत्सर्जित। `hook_completed` के साथ जोड़ी बनाएं; SDK स्वचालित रूप से `duration_ms` की गणना करता है। ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", - hook_name="pre_tool_use", # str, required - hook_id="hook-abc", # str, required - कोरिलेशन की + hook_name="pre_tool_use", # str, आवश्यक + hook_id="hook-abc", # str, आवश्यक - सहसंबंध कुंजी trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -298,14 +299,14 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -जब कोई हुक खत्म हो जाता है तो उत्सर्जित होता है। `hook_id` के माध्यम से `hook_triggered` के साथ कोरिलेट होता है। +जब कोई हुक समाप्त होता है तो उत्सर्जित। `hook_id` के माध्यम से `hook_triggered` से सहसंबंधित है। ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # prior hook_triggered से मेल खाना चाहिए + hook_id="hook-abc", # पूर्व hook_triggered से मेल खाना चाहिए outcome="allow", # str | None output=None, # Any | None error=None, # str | None @@ -317,56 +318,56 @@ agenteye.event.hook_completed( ### `event.error()` -जब एक अनहैंडल किया गया एरर होता है तो उत्सर्जित होता है। +जब कोई अनहैंडल्ड एरर होता है तो उत्सर्जित। ```python agenteye.event.error( session_id="run-001", agent_id="planner", - error_type="TimeoutError", # str, required - message="timed out", # str, required + error_type="TimeoutError", # str, आवश्यक + message="timed out", # str, आवश्यक traceback="Traceback...", # str | None ) ``` --- -## मानव-इन-द-लूप ईवेंट्स +## मानव-इन-द-लूप इवेंट्स -मानव-इन-द-लूप ईवेंट्स आपको उन क्षणों पर निरीक्षण देते हैं जहाँ कोई व्यक्ति एजेंट के एक्सीक्यूशन में कदम रखता है (अनुमोदन की प्रतीक्षा करना, इनपुट प्रदान करना, रोकना, या एजेंट को बंद करना)। वे आपको मापने देते हैं कि मनुष्य प्रतिक्रिया देने में कितना समय लेते हैं (SDK पेयर्ड ईवेंट्स पर `duration_ms` स्वचालित रूप से गणना करता है), ऑडिट करता है कि किसने एजेंट को रोका या बाधित किया, और अनुमोदन और निरीक्षण वर्कफ़्लो बनाता है जो डैशबोर्ड में सतह पर आते हैं। +मानव-इन-द-लूप इवेंट्स आपको उन क्षणों पर नज़र रखता है जहाँ एक व्यक्ति एजेंट के एक्सीक्यूशन में कदम रखता है (स्वीकृति के लिए प्रतीक्षा, इनपुट प्रदान, रोक, या एजेंट को रोकना)। ये आपको मानव प्रतिक्रिया समय (SDK स्वचालित रूप से जोड़ी इवेंट्स पर `duration_ms` की गणना करता है) को मापने, ऑडिट करने देते हैं कि किसने एजेंट को रोका या बाधित किया, और अनुमोदन और निरीक्षण वर्कफ़्लो बनाते हैं जो डैशबोर्ड में सतह आते हैं। ### `event.human_wait()` -जब एजेंट एक मानव को इनपुट प्रदान करने की प्रतीक्षा करने के लिए एक्सीक्यूशन को रोकता है तो उत्सर्जित होता है। `human_input` के साथ पेयर करें; SDK स्वचालित रूप से `duration_ms` (मानव को प्रतिक्रिया देने में कितना समय लगा) की गणना करता है। +जब एजेंट एक्सीक्यूशन को रोकता है ताकि मानव इनपुट प्रदान करने के लिए प्रतीक्षा करे तो उत्सर्जित। `human_input` के साथ जोड़ी बनाएं; SDK स्वचालित रूप से `duration_ms` की गणना करता है (मानव को प्रतिक्रिया देने में कितना समय लगा)। ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - matching human_input के लिए कोरिलेशन की + input_id="inp-abc", # str, आवश्यक - मेल खाने वाले human_input के लिए सहसंबंध कुंजी prompt="Do you approve this action?", # str | None - मानव को दिखाया गया प्रश्न - options=["approve", "reject", "defer"], # list[str] | None - मानव को प्रस्तुत किए गए विकल्प + options=["approve", "reject", "defer"], # list[str] | None - मानव को प्रस्तुत विकल्प reason="approval_required", # str | None - एजेंट क्यों प्रतीक्षा कर रहा है ) ``` ### `event.human_input()` -जब कोई मानव इनपुट प्रदान करता है और एजेंट फिर से शुरू होता है तो उत्सर्जित होता है। `input_id` के माध्यम से `human_wait` के साथ कोरिलेट होता है। `duration_ms` स्वचालित रूप से गणना की जाती है और कॉलर द्वारा पास नहीं की जानी चाहिए। +जब कोई मानव इनपुट प्रदान करता है और एजेंट फिर से शुरू होता है तो उत्सर्जित। `input_id` के माध्यम से `human_wait` से सहसंबंधित है। `duration_ms` स्वचालित रूप से गणना की जाती है और कॉलर द्वारा पास नहीं की जानी चाहिए। ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - prior human_wait से मेल खाना चाहिए - response="approve", # str | None - मानव का जवाब (मुक्त पाठ या चयनित विकल्प) + input_id="inp-abc", # str, आवश्यक - पूर्व human_wait से मेल खाना चाहिए + response="approve", # str | None - मानव का उत्तर (मुक्त पाठ या चयनित विकल्प) # duration_ms स्वचालित रूप से गणना की जाती है - इसे पास न करें ) ``` ### `event.human_pause()` -जब कोई मानव सक्रिय रूप से एजेंट को रोकता है (उदा. डैशबोर्ड नियंत्रण के माध्यम से) तो उत्सर्जित होता है। एजेंट को निलंबित किया जाता है लेकिन समाप्त नहीं किया जाता है। +जब कोई मानव सक्रिय रूप से एजेंट को रोकता है (उदाहरण के लिए डैशबोर्ड नियंत्रण के माध्यम से) तो उत्सर्जित। एजेंट को निलंबित कर दिया जाता है लेकिन समाप्त नहीं किया जाता है। ```python agenteye.event.human_pause( @@ -379,7 +380,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -जब कोई मानव एक्सीक्यूशन के बीच सक्रिय रूप से एजेंट को बंद करता है तो उत्सर्जित होता है। `human_pause` के विपरीत, एजेंट का काम निलंबित नहीं बल्कि समाप्त हो जाता है। +जब कोई मानव सक्रिय रूप से एजेंट को एक्सीक्यूशन के बीच में रोकता है तो उत्सर्जित। `human_pause` के विपरीत, एजेंट का काम निलंबित होने के बजाय समाप्त हो जाता है। ```python agenteye.event.human_interrupt( @@ -387,15 +388,15 @@ agenteye.event.human_interrupt( agent_id="planner", reason="output_incorrect", # str | None user_id="usr_42", # str | None - किसने एजेंट को बाधित किया - at_step="tool_use:web_search", # str | None - एजेंट को बंद करते समय क्या कर रहा था + at_step="tool_use:web_search", # str | None - एजेंट क्या कर रहा था जब रोका गया ) ``` --- -## कस्टम फील्ड्स +## कस्टम फ़ील्ड्स -कोई भी अतिरिक्त कीवर्ड आर्गुमेंट्स मानक फील्ड्स के बाद ईवेंट में जोड़े जाते हैं: +कोई भी अतिरिक्त कीवर्ड आर्गुमेंट्स मानक फ़ील्ड्स के बाद इवेंट में जोड़ी जाते हैं: ```python agenteye.event.tool_use( @@ -403,32 +404,32 @@ agenteye.event.tool_use( agent_id="planner", tool_name="db_query", tool_call_id="toolu_02", - tenant_id="acme", # कस्टम फील्ड - region="us-east-1", # कस्टम फील्ड + tenant_id="acme", # कस्टम फ़ील्ड + region="us-east-1", # कस्टम फ़ील्ड ) ``` -`timestamp`, `type`, और `environment` आरक्षित हैं और `ValueError` उठाते हैं (`Reserved field names cannot be used as custom fields: [...]`) यदि कस्टम फील्ड्स के रूप में पास किए जाते हैं। `session_id` और `agent_id` हर ईवेंट मेथड पर आवश्यक पैरामीटर हैं और दूसरी बार आपूर्ति नहीं किए जा सकते; यदि आप ऐसा करते हैं तो Python `TypeError` उठाता है। इसके बजाय `configure(environment=...)` (या `AGENTEYE_ENVIRONMENT` चर) के साथ पर्यावरण सेट करें। +`timestamp`, `type`, और `environment` आरक्षित हैं और यदि कस्टम फ़ील्ड्स के रूप में पास किए जाएं तो `ValueError` उठाते हैं (`Reserved field names cannot be used as custom fields: [...]`)। `session_id` और `agent_id` हर इवेंट मेथड पर आवश्यक पैरामीटर हैं और दूसरी बार आपूर्ति नहीं किए जा सकते; यदि आप ऐसा करते हैं तो Python `TypeError` उठाता है। इसके बजाय `configure(environment=...)` (या `AGENTEYE_ENVIRONMENT` चर) के साथ पर्यावरण सेट करें। -जब आप उनकी फील्ड्स को क्वेरी करना चाहते हैं तो पेलोड्स को स्ट्रक्चर्ड JSON के रूप में रखें। वे मान जो JSON स्वाभाविक रूप से समर्थन नहीं करते—जैसे datetimes, UUIDs, decimals, sets, bytes, या model objects—सेट रिकॉर्डिंग को सुरक्षित रूप से जारी रखने के लिए स्ट्रिंग में परिवर्तित होते हैं। +जब आप उनकी फ़ील्ड्स को क्वेरी करना चाहते हैं तो पेलोड को संरचित JSON के रूप में रखें। JSON मूल रूप से समर्थन नहीं करने वाले मान—जैसे डेटाटाइम्स, UUIDs, दशमलव, सेट्स, बाइट्स, या मॉडल ऑब्जेक्ट्स—को स्ट्रिंग में परिवर्तित किया जाता है ताकि रिकॉर्डिंग सुरक्षित रूप से जारी रहे। --- -## ईवेंट्स कैसे लिखी जाती हैं +## इवेंट्स कैसे लिखे जाते हैं -ईवेंट्स इन-प्रोसेस में बफर होते हैं और हर `flush_interval` सेकंड (डिफॉल्ट 500 ms) में डिस्क पर फ्लश होते हैं। प्रत्येक फ्लश एक JSONL फाइल लिखता है: +इवेंट्स प्रक्रिया में बफर किए जाते हैं और हर `flush_interval` सेकंड (डिफ़ॉल्ट 500 ms) में डिस्क पर फ्लश किए जाते हैं। प्रत्येक फ्लश एक JSONL फ़ाइल लिखता है: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -कलेक्टर इस डायरेक्टरी को देखता है और फाइलों को स्वचालित रूप से अपलोड करता है। आपको इन फाइलों को सीधे प्रबंधित करने की आवश्यकता नहीं है। +कलेक्टर इस निर्देशिका को देखता है और फ़ाइलों को स्वचालित रूप से अपलोड करता है। आपको इन फ़ाइलों को सीधे प्रबंधित करने की आवश्यकता नहीं है। -प्रत्येक फाइल को atomically लिखा जाता है: SDK एक अस्थायी फाइल में लिखता है और फिर इसे जगह में पुनर्नाम करता है, इसलिए कलेक्टर कभी भी आधी-लिखी फाइल नहीं देखता है। अंतिम फ्लश आपकी प्रक्रिया के exit होने पर भी चलता है, इसलिए अंतिम अंतराल में बफर की गई ईवेंट्स खो नहीं जाती हैं। यदि कलेक्टर ऑफलाइन है, तो ईवेंट्स डिस्क पर फाइलों के रूप में जमा हो जाती हैं और एक बार यह वापस आ जाए तो भेज दी जाती हैं। +प्रत्येक फ़ाइल परमाणु रूप से लिखी जाती है: SDK एक अस्थायी फ़ाइल में लिखता है और फिर इसे जगह में तोड़ता है, इसलिए कलेक्टर कभी आधी-लिखी हुई फ़ाइल नहीं देखता है। एक अंतिम फ्लश भी तब चलता है जब आपकी प्रक्रिया बाहर निकलती है, इसलिए अंतिम अंतराल में बफर किए गए इवेंट्स खो नहीं जाते हैं। यदि कलेक्टर ऑफ़लाइन है, तो इवेंट्स डिस्क पर फ़ाइलों के रूप में जमा होते हैं और एक बार वापस आने पर भेज दिए जाते हैं। --- ## अगले कदम -- [ईवेंट स्ट्रीम](/hi/agenteye/event-stream): ये ईवेंट्स लाइव में आने देखें, रंग-कोडित और पर्यावरण, एजेंट, और सेशन के अनुसार फ़िल्टर योग्य। -- [सेशन्स](/hi/agenteye/sessions): देखें कि पेयर्ड ईवेंट्स प्रत्येक एजेंट रन को एक्सीक्यूशन ग्राफ और टाइमलाइन के रूप में कैसे पुनर्निर्मित करते हैं। \ No newline at end of file +- [इवेंट स्ट्रीम](/hi/agenteye/event-stream): ये इवेंट्स लाइव पहुँचते देखें, रंग-कोडित और पर्यावरण, एजेंट, और सेशन द्वारा फ़िल्टर योग्य। +- [सेशन्स](/hi/agenteye/sessions): देखें कि कैसे जोड़ी इवेंट्स प्रत्येक एजेंट रन को एक्सीक्यूशन ग्राफ और टाइमलाइन के रूप में पुनर्निर्मित करते हैं। \ No newline at end of file diff --git a/docs/hi/agenteye/queries.mdx b/docs/hi/agenteye/queries.mdx index 526f8748..4e987f81 100644 --- a/docs/hi/agenteye/queries.mdx +++ b/docs/hi/agenteye/queries.mdx @@ -1,57 +1,56 @@ --- ---- -title: "Queries" +title: "क्वेरीज़" description: "अपने एजेंट डेटा से कोई भी सवाल पूछें और सेकंड में जवाब पाएं।" --- -अपने एजेंट डेटा से कोई भी सवाल पूछें और सेकंड में जवाब पाएं। Failproof AI Observability आपको आपकी इवेंट्स और evaluations पर सहेजे गए, चलने के लिए तैयार queries की एक लाइब्रेरी देता है, ताकि आप खाली SQL एडिटर के बजाय एक काम करने वाले उदाहरण से शुरुआत कर सकें। +अपने एजेंट डेटा से कोई भी सवाल पूछें और सेकंड में जवाब पाएं। Failproof AI Observability आपको आपकी इवेंट्स और इवेल्यूएशन्स पर सेव किए गए, रन के लिए तैयार क्वेरीज़ की एक लाइब्रेरी देता है, ताकि आप खाली SQL एडिटर की जगह एक काम करने वाले उदाहरण से शुरुआत कर सकें। -![सहेजे गए-queries की लाइब्रेरी: पुनः उपयोग योग्य queries का एक ग्रिड, दोनों built-in presets और कस्टम](/agenteye/images/queries.png) +![सेव किए गए क्वेरीज़ की लाइब्रेरी: दोबारा इस्तेमाल की जा सकने वाली क्वेरीज़ का ग्रिड, बिल्ट-इन प्रीसेट्स और कस्टम वाली दोनों](/agenteye/images/queries.png) -*आपकी सहेजी गई-queries लाइब्रेरी `//queries` पर: built-in presets आपकी टीम द्वारा सहेजे गए queries के साथ बैठे हुए।* +*आपकी सेव किए गए क्वेरीज़ की लाइब्रेरी `//queries` पर: बिल्ट-इन प्रीसेट्स आपकी टीम द्वारा सेव की गई क्वेरीज़ के साथ।* -## एक blank page से नहीं, एक preset से शुरुआत करें +## प्रीसेट से शुरुआत करें, खाली पेज से नहीं -आपको टेबल के नाम याद रखने या SQL को शुरुआत से लिखना नहीं है। लाइब्रेरी built-in presets के साथ खुलती है जो टीमें सबसे ज्यादा पूछती हैं, ठीक उसके आगे आपकी अपनी टीम द्वारा सहेजे गए और नामित queries बैठे हुए हैं। एक ऐसा चुनें जो आप जो चाहते हैं उसके करीब हो और आप लगभग आधे रास्ते पर एक जवाब पर पहुंच गए होंगे। +आपको टेबल के नाम याद रखने या SQL को शुरुआत से लिखने की जरूरत नहीं है। लाइब्रेरी बिल्ट-इन प्रीसेट्स के साथ खुलती है जो टीमें सबसे ज्यादा पूछती हैं, आपकी अपनी टीम द्वारा सेव की गई और नाम दी गई क्वेरीज़ के ठीक बगल में। ऐसा कोई चुनें जो आप जो चाहते हैं उसके करीब हो और आप जवाब तक पहुंचने का अधिकांश रास्ता तय कर चुके होंगे। -हर सहेजा गया query org-scoped और साझा किया गया है, इसलिए उपयोगी queries जो आपके टीम के सदस्य लिखते हैं वह आपके भी बन जाती हैं। एक बार query का नाम दें और एक विवरण दें, और आपके org में कोई भी इसे खोज सकता है, इसे चला सकता है, या बाद में इसके परिणामों को एक डैशबोर्ड पर pin कर सकता है। +हर सेव की गई क्वेरी org-स्कोप्ड और शेयर्ड है, इसलिए आपके टीम के सदस्यों द्वारा लिखी गई उपयोगी क्वेरीज़ आपकी भी बन जाती हैं। एक बार क्वेरी को नाम दें और विवरण दें, और आपके org में कोई भी इसे खोज सकता है, चला सकता है, या बाद में इसके नतीजों को डैशबोर्ड पर पिन कर सकता है। -`//queries` पर इसे खोजें। +इसे `//queries` पर खोजें। -## इसे SQL composer में tweaks करें और चलाएं +## इसे SQL कंपोजर में ट्वीक करें और रन करें -कोई भी query खोलें और यह SQL composer में उतरता है, जहां आप इसे समायोजित कर सकते हैं और तुरंत जवाब देख सकते हैं: कोई export नहीं, कोई round-trip नहीं, किसी और के इंतजार में नहीं। +किसी भी क्वेरी को खोलें और यह SQL कंपोजर में आता है, जहां आप इसे एडजस्ट कर सकते हैं और तुरंत जवाब देख सकते हैं: कोई एक्सपोर्ट नहीं, कोई राउंड-ट्रिप नहीं, किसी और का इंतजार नहीं। -![SQL query composer एक सहेजे गए query को चला रहा है, एक schema sidebar और एक live result grid के साथ](/agenteye/images/query-lab.png) +![SQL क्वेरी कंपोजर एक सेव की गई क्वेरी को चला रहा है, स्कीमा साइडबार और लाइव रिजल्ट ग्रिड के साथ](/agenteye/images/query-lab.png) -*SQL composer: आपका query बाईं ओर, एक schema sidebar ताकि आप कभी column name का अनुमान न लगाएं, और नीचे एक live result grid।* +*SQL कंपोजर: आपकी क्वेरी बाईं ओर, एक स्कीमा साइडबार ताकि आप कभी कॉलम नाम का अनुमान न लगाएं, और नीचे एक लाइव रिजल्ट ग्रिड।* -- **एक schema sidebar** analytics tables और उनके columns को स्पष्ट करता है, ताकि आप field names की खोज किए बिना एक query आकार दे सकें। -- **एक live result grid** वह पल में rows return करता है जब आप run करते हैं, ताकि आप अनुमान लगाने और फिर से अनुमान लगाने के बजाय सेकंड में iterate कर सकें। -- **डिज़ाइन द्वारा read-only।** Queries आपकी event store के खिलाफ चलती हैं और सर्वर पर validate की जाती हैं: केवल `SELECT` और `WITH` statements की अनुमति है, एक statement timeout और एक row cap के साथ। एक exploratory query कभी आपके डेटा को modify नहीं कर सकता, और एक runaway को आपके लिए रोक दिया जाता है। +- **एक स्कीमा साइडबार** एनालिटिक्स टेबल्स और उनके कॉलम्स को लेआउट करता है, ताकि आप फील्ड नाम ढूंढे बिना क्वेरी तैयार कर सकें। +- **एक लाइव रिजल्ट ग्रिड** रन करने के समय ही पंक्तियां रिटर्न करता है, इसलिए आप अनुमान लगाने और फिर से अनुमान लगाने की जगह सेकंड में दोहराव कर सकते हैं। +- **डिज़ाइन के अनुसार रीड-ओनली।** क्वेरीज़ आपके इवेंट स्टोर के विरुद्ध चलती हैं और सर्वर पर मान्य की जाती हैं: केवल `SELECT` और `WITH` स्टेटमेंट्स की अनुमति है, स्टेटमेंट टाइमआउट और रो कैप के साथ। एक एक्सप्लोरेटरी क्वेरी कभी आपके डेटा को संशोधित नहीं कर सकती, और एक runaway क्वेरी आपके लिए रुक जाती है। -परिणाम से खुश हैं? इसे लाइब्रेरी में वापस सहेजें ताकि पूरी टीम इसे inherit करे, या इसके output को एक डैशबोर्ड पर एक line, bar, area, या pie tile के रूप में pin करें। +नतीजे से खुश हैं? इसे लाइब्रेरी में वापस सेव करें ताकि पूरी टीम इसे प्राप्त करे, या इसके आउटपुट को डैशबोर्ड पर लाइन, बार, एरिया, या पाई टाइल के रूप में पिन करें। -## उन्हें terminal से चलाएं, या assistant को उन्हें लिखने दें +## इन्हें टर्मिनल से रन करें, या असिस्टेंट को उन्हें लिखने दें -एक ही सहेजे गए queries आपके साथ कहीं भी चलते हैं: +एक ही सेव की गई क्वेरीज़ आपके साथ जहां कहीं भी आप काम करते हैं, साथ चलती हैं: -- **Terminal से।** `agenteye` CLI सूचीबद्ध करता है, चलाता है, और वही saved queries को सहेजता है, ताकि आप एक result को एक script में drop कर सकें, इसे CI में wire कर सकें, या इसे एक coding agent को दे सकें। +- **टर्मिनल से।** `agenteye` CLI उसी सेव की गई क्वेरीज़ को लिस्ट करता है, रन करता है, और सेव करता है, इसलिए आप परिणाम को स्क्रिप्ट में डाल सकते हैं, इसे CI में वायर कर सकते हैं, या इसे एक कोडिंग एजेंट को दे सकते हैं। ```bash -agenteye query list # वही सहेजे गए queries, आपके terminal से -agenteye query run errs --arg prod # एक को चलाएं और rows print करें (pipes के लिए --json जोड़ें) +agenteye query list # आपकी टर्मिनल से वही सेव की गई क्वेरीज़ +agenteye query run errs --arg prod # एक को रन करें और पंक्तियां प्रिंट करें (पाइप करने के लिए --json जोड़ें) ``` - पूरे command set के लिए [CLI और agents](/hi/agenteye/cli-and-agents) देखें। + पूरे कमांड सेट के लिए [CLI और एजेंट्स](/hi/agenteye/cli-and-agents) देखें। -- **AI assistant से।** निश्चित नहीं कि SQL को कैसे phrase करें? in-dashboard [AI assistant](/hi/agenteye/assistant) से plain English में पूछें और यह query को draft करेगा और इसे आपकी लाइब्रेरी में सहेज देगा। +- **AI असिस्टेंट से।** SQL को कैसे फ्रेज़ करें यह सुनिश्चित नहीं हैं? डैशबोर्ड में [AI असिस्टेंट](/hi/agenteye/assistant) से साधारण अंग्रेजी में पूछें और यह क्वेरी ड्राफ्ट करेगा और इसे आपकी लाइब्रेरी में सेव करेगा। -एक सहेजे गए query को चलाना `queries:run` permission द्वारा gated है, queries को create या delete करने की permissions से अलग रखा गया है, ताकि आप read access grant कर सकें बिना हर किसी को लाइब्रेरी को rewrite करने दिए। +एक सेव की गई क्वेरी को रन करना `queries:run` अनुमति द्वारा गेटेड है, क्वेरीज़ को बनाने या हटाने की अनुमतियों से अलग रखा गया है, इसलिए आप पढ़ने की एक्सेस दे सकते हैं बिना सभी को लाइब्रेरी को फिर से लिखने की अनुमति दिए। ## संबंधित -- [Dashboards](/hi/agenteye/dashboards): query results को shared, org-wide charts में pin करें। -- [AI assistant](/hi/agenteye/assistant): plain English में सवाल पूछें और एक query वापस पाएं। -- [CLI और agents](/hi/agenteye/cli-and-agents): आपके terminal से वही queries को चलाएं और सहेजें। \ No newline at end of file +- [डैशबोर्ड्स](/hi/agenteye/dashboards): क्वेरी रिजल्ट्स को शेयर्ड, org-व्यापी चार्ट्स में पिन करें। +- [AI असिस्टेंट](/hi/agenteye/assistant): साधारण अंग्रेजी में सवाल पूछें और एक क्वेरी वापस पाएं। +- [CLI और एजेंट्स](/hi/agenteye/cli-and-agents): आपकी टर्मिनल से वही क्वेरीज़ रन करें और सेव करें। \ No newline at end of file diff --git a/docs/hi/agenteye/security.mdx b/docs/hi/agenteye/security.mdx index d9906939..2fe46e10 100644 --- a/docs/hi/agenteye/security.mdx +++ b/docs/hi/agenteye/security.mdx @@ -1,68 +1,68 @@ --- +--- title: "सुरक्षा" -description: "Failproof AI Observability आपके उत्पादन एजेंटों के पास रखने के लिए बनाया गया है, जिसका अर्थ है कि यह आपके prompts, tool inputs, और outputs को देखता है।" +description: "Failproof AI Observability आपके प्रोडक्शन एजेंट्स के करीब काम करने के लिए बनाया गया है, जिसका मतलब है कि यह आपके प्रॉम्प्ट्स, टूल इनपुट्स और आउटपुट्स को देखता है।" --- - -Failproof AI Observability आपके उत्पादन एजेंटों के पास रखने के लिए बनाया गया है, जिसका अर्थ है कि यह आपके prompts, tool inputs, और outputs को देखता है। यह पृष्ठ बताता है कि यह उस डेटा को कैसे अलग-थलग, नियंत्रित, और आपके हाथों में रखता है। यदि आप सुरक्षा समीक्षा के लिए Failproof AI Observability का मूल्यांकन कर रहे हैं, तो यहाँ से शुरू करें। +Failproof AI Observability आपके प्रोडक्शन एजेंट्स के करीब काम करने के लिए बनाया गया है, जिसका मतलब है कि यह आपके प्रॉम्प्ट्स, टूल इनपुट्स और आउटपुट्स को देखता है। यह पृष्ठ समझाता है कि यह डेटा को कैसे अलग-थलग, नियंत्रित और आपके हाथों में रखता है। यदि आप सुरक्षा समीक्षा के लिए Failproof AI Observability का मूल्यांकन कर रहे हैं, तो यहाँ से शुरू करें। --- -## आपका डेटा आपके परिवेश में रहता है +## आपका डेटा आपके वातावरण में रहता है -Failproof AI Observability self-hosted है। Events, prompts, मॉडल responses, और analytics आपके अपने डेटाबेस में, आपके अपने परिवेश में संग्रहीत हैं। कोई भी डेटा storage के लिए किसी third-party SaaS को नहीं भेजा जाता है, और आपका डेटा आपके अपने cloud account में रहता है। +Failproof AI Observability स्व-होस्टेड है। इवेंट्स, प्रॉम्प्ट्स, मॉडल रेस्पांसेस और एनालिटिक्स आपके स्वयं के डेटाबेस में, आपके स्वयं के वातावरण में संग्रहीत होते हैं। कोई भी डेटा किसी तीसरे पक्ष के SaaS में संग्रहण के लिए नहीं भेजा जाता है, और आपका डेटा आपके स्वयं के क्लाउड खाते में रहता है। --- -## टेनेंट isolation +## टेनेंट अलगाव -एक Failproof AI Observability instance कई संगठनों को host कर सकता है, और प्रत्येक को storage layer पर अलग किया जाता है — सिर्फ UI द्वारा नहीं, बल्कि डेटाबेस द्वारा लागू किया जाता है: +एक Failproof AI Observability इंस्टेंस कई संगठनों को होस्ट कर सकता है, और प्रत्येक स्टोरेज लेयर पर अलग-थलग होता है — केवल UI द्वारा नहीं, बल्कि डेटाबेस द्वारा लागू किया जाता है: -- किसी संगठन का operational data (users, keys, dashboards, saved queries) उस org तक सीमित है, और cross-org reads को डेटाबेस द्वारा ही block किया जाता है। -- प्रत्येक ingested event को अपने owning org के साथ stamp किया जाता है, इसलिए एक संगठन की events को कभी भी दूसरे द्वारा नहीं पढ़ा जा सकता। +- किसी संगठन का ऑपरेशनल डेटा (उपयोगकर्ता, कुंजियाँ, डैशबोर्ड, सहेजी गई क्वेरीज) उस संगठन के लिए स्कोप किया जाता है, और क्रॉस-ऑर्ग रीड्स को डेटाबेस स्वयं द्वारा ब्लॉक किया जाता है। +- प्रत्येक इनजेस्ट किया गया इवेंट अपने स्वामी संगठन के साथ स्टैम्प किया जाता है, इसलिए एक संगठन के इवेंट्स कभी भी दूसरे द्वारा नहीं पढ़े जा सकते। -प्रत्येक dashboard route एक org slug (`//…`) के अंतर्गत scoped है। +हर डैशबोर्ड रूट एक ऑर्ग स्लग (`//…`) के तहत स्कोप किया जाता है। --- -## Sign-in +## साइन-इन -Failproof AI Observability passwordless, email-based sign-in का उपयोग करता है। phish या leak करने के लिए कोई password नहीं है। एक उपयोगकर्ता एक one-time code (या एक one-click magic link) का अनुरोध करता है, जो उन्हें email किया जाता है और जल्दी expire हो जाता है। Sign-in को एक **allowlist** द्वारा gate किया जाता है: केवल email addresses (या domains) जिन्हें आप permit करते हैं, authenticate कर सकते हैं। +Failproof AI Observability पासवर्ड रहित, ईमेल-आधारित साइन-इन का उपयोग करता है। फिशिंग या लीक होने के लिए कोई पासवर्ड नहीं है। एक उपयोगकर्ता एक वन-टाइम कोड (या एक वन-क्लिक मैजिक लिंक) का अनुरोध करता है, जो उन्हें ईमेल किया जाता है और जल्दी समाप्त हो जाता है। साइन-इन एक **अनुमति सूची** द्वारा गेटेड होता है: केवल ईमेल पते (या डोमेन) जिन्हें आप अनुमति देते हैं, प्रमाणित हो सकते हैं। -![Failproof AI Observability sign-in screen, जो आपके email को एक single-use code भेजता है](/agenteye/images/login.png) +![Failproof AI Observability साइन-इन स्क्रीन, जो आपके ईमेल को एक सिंगल-यूज कोड भेजता है](/agenteye/images/login.png) --- -## API keys के साथ scoped access +## API कुंजियों के साथ स्कोप्ड एक्सेस -प्रत्येक client एक API key के साथ authenticate करता है जो granular, least-privilege permissions रखता है। एक collector को केवल `events:add` की जरूरत है; एक dashboard या assistant key read-only हो सकता है; destructive actions (delete, regenerate) अलग grants हैं जिन्हें आप शामिल करना चुनते हैं। +प्रत्येक क्लाइंट एक API कुंजी के साथ प्रमाणित करता है जो सूक्ष्म, न्यूनतम-विशेषाधिकार अनुमतियाँ रखता है। एक कलेक्टर को केवल `events:add` की आवश्यकता होती है; एक डैशबोर्ड या सहायक कुंजी केवल-पढ़ने के लिए हो सकती है; विनाशकारी कार्य (डिलीट, पुनः जेनरेट) अलग अनुदान हैं जिन्हें आप शामिल करना चुनते हैं। -![API keys page: प्रत्येक key की permission grants, read, write, और destructive scope द्वारा colour-coded](/agenteye/images/api-keys.png) +![API कुंजियाँ पृष्ठ: प्रत्येक कुंजी की अनुमति अनुदान, पढ़ने, लिखने और विनाशकारी स्कोप द्वारा रंग-कोडित](/agenteye/images/api-keys.png) -Admin bootstrap key को setup के लिए रखें, और बाकी सब कुछ के लिए narrow keys जारी करें। [API keys](/hi/agenteye/api-keys) देखें। +सेटअप के लिए एडमिन बूटस्ट्रैप कुंजी रखें, और बाकी सब कुछ के लिए संकीर्ण कुंजियाँ जारी करें। [API कुंजियाँ](/hi/agenteye/api-keys) देखें। --- -## एक read-only, approval-gated assistant +## एक केवल-पढ़ने वाला, अनुमोदन-गेटेड सहायक -Dashboard में [AI assistant](/hi/agenteye/assistant) आपके डेटा पर प्रश्नों का उत्तर देता है, लेकिन यह design द्वारा constrained है: +इन-डैशबोर्ड [AI सहायक](/hi/agenteye/assistant) आपके डेटा पर सवालों के जवाब देता है, लेकिन यह डिज़ाइन द्वारा सीमित है: -- यह **डिफ़ॉल्ट रूप से read-only है**: इसका SQL एक guard के माध्यम से चलता है जो केवल `SELECT`/`WITH` queries को permit करता है, single-statement, एक row cap के साथ। -- जो कुछ भी यह creates करता है (एक saved query, एक dashboard) **approval-gated है**: आप प्रत्येक write से पहले review और approve करते हैं। -- यह **कभी delete नहीं कर सकता**। +- यह **डिफ़ॉल्ट रूप से केवल-पढ़ने के लिए** है: इसका SQL एक गार्ड के माध्यम से चलता है जो केवल `SELECT`/`WITH` क्वेरीज, सिंगल-स्टेटमेंट, एक रो कैप के साथ अनुमति देता है। +- यह जो कुछ भी बनाता है (एक सहेजी गई क्वेरी, एक डैशबोर्ड) **अनुमोदन-गेटेड** होता है: आप हर लिखने से पहले समीक्षा और अनुमोदन करते हैं। +- यह **कभी भी डिलीट नहीं कर सकता**। -इसलिए एक teammate यह पूछ सकता है "इस सप्ताह किन agents में सबसे अधिक errors थीं?" और answer पर कार्रवाई कर सकता है, बिना इसके कि assistant अपने आप पर आपके डेटा को change या remove कर सके। +इसलिए एक सहकर्मी "इस सप्ताह कौन से एजेंट्स सबसे अधिक त्रुटि करते हैं?" पूछ सकता है और उत्तर पर कार्य कर सकता है, बिना सहायक को अपने आप पर आपके डेटा को बदलने या हटाने में सक्षम होने के बिना। --- -## Transit में +## ट्रांजिट में -सभी traffic HTTPS के माध्यम से चलता है। आप अपने अपने certificates के साथ TLS को terminate करते हैं, इसलिए collector-to-server और browser-to-server traffic transit में encrypted है। +सभी ट्रैफिक HTTPS पर चलता है। आप अपनी स्वयं की प्रमाणपत्रों के साथ TLS को समाप्त करते हैं, इसलिए कलेक्टर-से-सर्वर और ब्राउज़र-से-सर्वर ट्रैफिक ट्रांजिट में एन्क्रिप्ट किया जाता है। --- ## अगले कदम -- [Overview](/hi/agenteye/overview): Failproof AI Observability कैसे एक साथ आता है। -- [API keys](/hi/agenteye/api-keys): collector, dashboard, और assistant के लिए access scope करें। -- [Observability](/hi/agenteye/observability): Failproof AI Observability आपके agents से क्या captures करता है। \ No newline at end of file +- [अवलोकन](/hi/agenteye/overview): Failproof AI Observability कैसे एक साथ फिट होता है। +- [API कुंजियाँ](/hi/agenteye/api-keys): कलेक्टर, डैशबोर्ड और सहायक के लिए एक्सेस को स्कोप करें। +- [अवलोकनीयता](/hi/agenteye/observability): Failproof AI Observability आपके एजेंट्स से क्या कैप्चर करता है। \ No newline at end of file diff --git a/docs/hi/agenteye/sessions.mdx b/docs/hi/agenteye/sessions.mdx index a0e9c55f..8916f60d 100644 --- a/docs/hi/agenteye/sessions.mdx +++ b/docs/hi/agenteye/sessions.mdx @@ -1,57 +1,57 @@ --- -title: "सेशन और एक्सीक्यूशन ग्राफ" -description: "किसी भी रन से हर ईवेंट, एक पठनीय पंक्ति में, और गिट-स्टाइल एक्सीक्यूशन ग्राफ के रूप में आरेखित, जिसे आप सेकंड में समझ सकते हैं।" +title: "सेशन और एक्सिक्यूशन ग्राफ" +description: "एक रन से हर इवेंट, एक पठनीय पंक्ति में समेकित और गिट-शैली एक्सिक्यूशन ग्राफ के रूप में खींचा गया जिसे आप सेकंड में पढ़ सकते हैं।" --- -यह अनुमान लगाना बंद करें कि कोई रन क्यों विफल हुआ। Failproof AI Observability किसी रन के हर ईवेंट को एक पठनीय पंक्ति में रखता है, फिर पूरे रन को गिट-स्टाइल चित्र के रूप में खींचता है जिसे आप सेकंड में समझ सकते हैं, इसलिए आप देखते हैं कि आपके एजेंट ने क्या किया, चरण दर चरण। +अनुमान लगाना बंद करें कि रन विफल क्यों हुआ। Failproof AI Observability रन से हर इवेंट को एक पठनीय पंक्ति में समेकित करता है, फिर पूरे रन को गिट-शैली चित्र के रूप में खींचता है जिसे आप सेकंड में पढ़ सकते हैं, ताकि आप देख सकें कि आपके एजेंट ने ठीक क्या किया, चरण दर चरण। -![सेशन की सूची: प्रति रन एक पंक्ति, सभी वातावरण और एजेंट्स के साथ, स्टेटस पिल्स और मूल्यांकन स्कोर बैजेज के साथ](/agenteye/images/sessions-list.png) +![सेशन सूची: प्रत्येक रन के लिए एक पंक्ति, पर्यावरण और एजेंट्स में, स्थिति पिल्स और मूल्यांकन स्कोर बैज के साथ](/agenteye/images/sessions-list.png) -*प्रति रन एक पंक्ति: स्टेटस पिल आपको एक नज़र में बताता है कि रन कैसे समाप्त हुआ, और एक स्कोर बैज एक बार एक मूल्यांकनकर्ता जुड़ जाता है।* +*प्रत्येक रन के लिए एक पंक्ति: स्थिति पिल एक नज़र में आपको बताता है कि रन कैसे समाप्त हुआ, और एक स्कोर बैज एक मूल्यांकनकर्ता जुड़ने के बाद सवार होता है।*
-*एजेंट ट्रेसिंग: एक ही रन को चरण दर चरण फॉलो करें, लक्ष्य से लेकर टूल्स तक अंतिम उत्तर तक।* +*एजेंट ट्रेसिंग: एक एकल रन को चरण दर चरण, लक्ष्य से टूल्स तक अंतिम उत्तर तक का पालन करें।* --- ## हर रन को एक नज़र में देखें -कच्चा ईवेंट ट्रेल हर चरण का सत्य है, लेकिन जब आपके पास दर्जनों रन्स में हज़ारों चरण हों, तो आपको चरण नहीं, रन की ज़रूरत है। सेशन पेज किसी भी रन के सभी ईवेंट्स को एक पंक्ति में रोल कर देता है, इसलिए एक दिन की गतिविधि एक स्कैन करने योग्य सूची बन जाती है, न कि सूचना की बाढ़। +कच्चा इवेंट ट्रेल हर चरण का सच है, लेकिन जब आपके पास दर्जनों रनों में हजारों चरण होते हैं, तो आपको चरण नहीं, रन चाहिए। सेशन पेज एक रन के सभी इवेंट्स को एक पंक्ति में समेकित करता है, इसलिए एक दिन की गतिविधि एक स्कैन करने योग्य सूची में बदल जाती है बजाय एक तेज़ धारा के। -हर पंक्ति में एक स्टेटस पिल होता है, इसलिए कोई विफल रन स्वस्थ रन से अलग नज़र आता है, इससे पहले कि आप कुछ भी क्लिक करें। तारीख की रेंज, वातावरण, एजेंट, या सेशन द्वारा फ़िल्टर करें, ताकि "सब कुछ" से "जिस रन की मुझे परवाह है" तक कुछ ही क्लिक में पहुंचें। +हर पंक्ति एक स्थिति पिल के साथ आती है, इसलिए एक विफल रन एक स्वस्थ से अलग दिखता है इससे पहले कि आप कुछ भी क्लिक करें। दिनांक सीमा, पर्यावरण, एजेंट, या सेशन के अनुसार फ़िल्टर करें ताकि आप कुछ क्लिक में "सब कुछ" से "जिस रन की मुझे परवाह है" तक जा सकें। -एक बार जब आप एक मूल्यांकनकर्ता को कनेक्ट कर देते हैं, तो हर पूर्ण रन को स्वचालित रूप से स्कोर किया जाता है और इसका सबसे हाल ही का स्कोर पंक्ति पर एक बैज के रूप में दिखाई देता है। आप किसी भी स्कोर रेंज द्वारा फ़िल्टर कर सकते हैं, इसलिए "इस हफ़्ते हर कम-स्कोर करने वाला प्रोड रन दिखाएं" एक फ़िल्टर है, मैनुअल समीक्षा नहीं। जब तक आप एक सेट नहीं करते, सेशन भी पूरे रन को कैप्चर करते हैं; उनके पास बस अभी तक एक स्कोर नहीं है। +एक बार जब आप एक मूल्यांकनकर्ता को जोड़ते हैं, तो हर पूर्ण रन को स्वचालित रूप से स्कोर किया जाता है और इसका नवीनतम स्कोर पंक्ति पर एक बैज के रूप में दिखाई देता है। आप किसी भी स्कोर सीमा के अनुसार फ़िल्टर कर सकते हैं, इसलिए "मुझे इस हफ्ते हर कम-स्कोरिंग प्रोड रन दिखाएं" एक फ़िल्टर है, मैनुअल समीक्षा नहीं। जब तक आप एक सेट अप नहीं करते, सेशन पूरे रन को कैप्चर करते रहते हैं; बस उनके पास अभी तक कोई स्कोर नहीं होता। --- -## पूरे रन को चित्र के रूप में पढ़ें +## पूरे रन को एक चित्र के रूप में पढ़ें -![एक सेशन के गिट-स्टाइल एक्सीक्यूशन ग्राफ के बगल में इसका ईवेंट टाइमलाइन, टूल, मॉडल, और हुक ब्रेकडाउन पैनल के साथ](/agenteye/images/session-detail.png) +![एक सेशन का गिट-शैली एक्सिक्यूशन ग्राफ इसकी इवेंट टाइमलाइन के बगल में, टूल, मॉडल, और हुक ब्रेकडाउन पैनल के साथ](/agenteye/images/session-detail.png) -*एक्सीक्यूशन ग्राफ (बाएं) ईवेंट टाइमलाइन के बगल में बैठता है; दाहिनी रेल रन के लिए टूल्स, मॉडल्स, हुक्स, और टोकन खर्च को विभाजित करता है।* +*एक्सिक्यूशन ग्राफ (बाएं) इवेंट टाइमलाइन के बगल में बैठता है; दाहिनी रेल रन के लिए टूल्स, मॉडल्स, हुक्स, और टोकन व्यय को तोड़ती है।* -किसी भी सेशन को क्लिक करें इसके एक्सीक्यूशन ग्राफ को खोलने के लिए: एजेंट्स, टूल्स, हुक्स, और मॉडल कॉल्स के समय के आधार पर कैसे सामने आए, इसका एक गिट-स्टाइल दृश्य। समानांतर उप-एजेंट अपनी-अपनी लेन पर शाखा बनाते हैं, इसलिए आप देख सकते हैं कि कौन सा काम साथ-साथ चला, कौन सा उप-एजेंट रुका, और रन कहां गलत हुआ, इसे अपने सिर में फिर से चलाए बिना लॉग्स की दीवार से। +किसी भी सेशन पर क्लिक करें इसका एक्सिक्यूशन ग्राफ खोलने के लिए: एजेंट्स, टूल्स, हुक्स, और मॉडल कॉल्स के कालक्रमानुसार कैसे विकसित हुए, इसका गिट-शैली दृश्य। समांतर सब-एजेंट्स अपनी अपनी लेन में शाखाबद्ध होते हैं, इसलिए आप देख सकते हैं कि कौन सा काम साथ-साथ चला, कौन सा सब-एजेंट स्थिर हुआ, और रन कहां ट्रैक से उतरा, इसे लॉग की दीवार से अपने दिमाग में फिर से चलाए बिना। -दाहिनी रेल आपको प्रति-रन ब्रेकडाउन देता है: कौन से टूल्स और मॉडल्स चले, कौन से हुक्स फायर हुए, और रन ने टोकन में क्या खर्च किया। यह "इस रन की लागत इतनी अधिक क्यों थी?" या "कौन सा टूल धीमा है?" का उत्तर है, ठीक इसके बगल में ग्राफ बैठा है जो इसका कारण बना। +दाहिनी रेल आपको प्रति-रन ब्रेकडाउन देती है: कौन से टूल्स और मॉडल्स चले, कौन से हुक्स फायर हुए, और रन ने टोकन में क्या व्यय किया। यह इस सवाल का जवाब है कि "इस रन की कीमत इतनी अधिक क्यों थी?" या "कौन सा टूल धीमा है?" यह ग्राफ के बगल में बैठा है जिसने इसे पैदा किया। -व्यक्तिगत ईवेंट्स एड्रेसेबल हैं, इसलिए आप किसी को "सेशन, लगभग दो तिहाई नीचे" के बजाय एक ही पल के लिए एक लिंक दे सकते हैं। किसी भी ईवेंट से लिंक कॉपी करें, या [ऑडिट](/hi/agenteye/audits) ढूंढ से या कोई त्रुटि से एक लिंक फॉलो करें, और सेशन उस ईवेंट को चुना हुआ और स्क्रॉल किए गए के साथ खुलता है। यह बहुत लंबे रन्स के लिए भी होता है: टाइमलाइन आपके ब्राउज़र की खातिर एक सीमित खिड़की लोड करता है, और एक लिंक जो उस खिड़की के बाहर इंगित करता है फिर भी अपना ईवेंट पाता है, न कि शुरुआत में आपको छोड़ देता है। अगर ईवेंट आपकी रिटेंशन विंडो से बाहर हो गया है, तो पेज आपको बताता है कि इसके बजाय शांति से कुछ नहीं चुनता। +व्यक्तिगत इवेंट्स पते योग्य हैं, इसलिए आप किसी को एक क्षण का लिंक दे सकते हैं बजाय "सेशन, लगभग दो तिहाई नीचे"। किसी भी इवेंट से लिंक कॉपी करें, या एक [ऑडिट](/hi/agenteye/audits) निष्कर्ष या त्रुटि से एक का पालन करें, और सेशन उस इवेंट के साथ चयनित और स्क्रॉल किए हुए खुलता है। यह बहुत लंबे रनों के लिए भी काम करता है: टाइमलाइन आपके ब्राउज़र के लिए एक सीमित विंडो लोड करता है, और एक लिंक जो उस विंडो से आगे इंगित करता है, फिर भी इसका इवेंट खोजता है बजाय आपको शुरुआत में छोड़ देने के। यदि इवेंट आपकी प्रतिधारण विंडो से बाहर निकल गया है, तो पेज आपको कुछ नहीं चुना जाता है के बजाय बताता है। --- -## इसे कहाँ खोजें +## इसे कहां खोजें -हर डैशबोर्ड पेज आपके संगठन (`//…`) के लिए स्कॉप किया गया है। सेशन **Observe** के अंतर्गत बाईं साइडबार में रहता है, ईवेंट्स के बगल में, सूची के शीर्ष में तारीख की रेंज, वातावरण, एजेंट, और सेशन फ़िल्टर के साथ। हर पंक्ति इसके पूर्ण एक्सीक्यूशन ग्राफ से एक क्लिक दूर है। +हर डैशबोर्ड पेज आपके संगठन (`//…`) के लिए स्कोप किया गया है। सेशन बाईं ओर की साइडबार में **Observe** के तहत रहता है, इवेंट्स के बगल में, दिनांक सीमा, पर्यावरण, एजेंट, और सेशन फ़िल्टर सूची के शीर्ष में। हर पंक्ति अपने पूर्ण एक्सिक्यूशन ग्राफ से एक क्लिक दूर है। -स्कोर बैजेज़ और स्कोर-रेंज फ़िल्टरिंग को चालू करने के लिए, एक मूल्यांकनकर्ता को कनेक्ट करें: [Evaluations](/hi/agenteye/evaluations) देखें। +स्कोर बैज चालू करने और स्कोर-सीमा फ़िल्टरिंग के लिए, एक मूल्यांकनकर्ता को जोड़ें: [मूल्यांकन](/hi/agenteye/evaluations) देखें। --- ## संबंधित -- [Event stream](/hi/agenteye/event-stream): कच्चा, प्रति-चरण ट्रेल जिससे हर सेशन रोल किया जाता है। -- [Evaluations](/hi/agenteye/evaluations): एक मूल्यांकनकर्ता को कनेक्ट करें, इसलिए हर रन को एक स्कोर बैज मिलता है जिससे आप फ़िल्टर कर सकते हैं। -- [Telemetry](/hi/agenteye/telemetry): रन्स अपने एजेंट से इन सेशन्स में कैसे जाते हैं। \ No newline at end of file +- [ईवेंट स्ट्रीम](/hi/agenteye/event-stream): कच्चा, प्रति-चरण ट्रेल जिसमें से हर सेशन समेकित होता है। +- [मूल्यांकन](/hi/agenteye/evaluations): एक मूल्यांकनकर्ता को जोड़ें ताकि हर रन को एक स्कोर बैज मिले जिसके अनुसार आप फ़िल्टर कर सकें। +- [टेलीमेट्री](/hi/agenteye/telemetry): रनों को आपके एजेंट से इन सेशन्स तक कैसे पहुंचाया जाता है। \ No newline at end of file diff --git a/docs/hi/agenteye/telemetry.mdx b/docs/hi/agenteye/telemetry.mdx index e741ba23..012e64d9 100644 --- a/docs/hi/agenteye/telemetry.mdx +++ b/docs/hi/agenteye/telemetry.mdx @@ -1,51 +1,51 @@ --- title: "प्रदर्शन मेट्रिक्स" -description: "तुरंत देखें कि आपके मॉडल, टूल या हुक कब धीमे हो रहे हैं या खर्च बढ़ रहा है, और अपने उपयोगकर्ताओं को महसूस होने से पहले टेल-लेटेंसी स्पाइक को पकड़ें।" +description: "देखें कि आपके मॉडल, टूल या हुक कब धीमे होते हैं या बिल बढ़ाते हैं, और अपने उपयोगकर्ताओं को महसूस होने से पहले टेल-लेटेंसी स्पाइक को पकड़ें।" --- -तुरंत देखें कि आपके मॉडल, टूल या हुक कब धीमे हो रहे हैं या खर्च बढ़ रहा है, और अपने उपयोगकर्ताओं को महसूस होने से पहले टेल-लेटेंसी स्पाइक को पकड़ें। तीन समर्पित पृष्ठ कच्चे समय को p50, p95, और p99 में बदलते हैं जिन्हें आप एक नज़र में पढ़ सकते हैं। +देखें कि आपके मॉडल, टूल या हुक कब धीमे होते हैं या बिल बढ़ाते हैं, और अपने उपयोगकर्ताओं को महसूस होने से पहले टेल-लेटेंसी स्पाइक को पकड़ें। तीन समर्पित पेज कच्ची समयसीमा को p50, p95, और p99 में बदलते हैं जिन्हें आप एक नज़र में पढ़ सकते हैं। -![मॉडल पृष्ठ लेटेंसी हीट-मैप, प्रतिशतक बैंड, और प्रति-मॉडल टोकन, लागत और संदर्भ-विंडो आंकड़े दिखाता है](/agenteye/images/models.png) -*मॉडल पृष्ठ: लेटेंसी हीट-मैप, प्रतिशतक बैंड, और प्रति-मॉडल टोकन, अनुमानित लागत, और संदर्भ-विंडो भरण।* +![मॉडल्स पेज जो एक लेटेंसी हीट-मैप, एक परसेंटाइल बैंड और प्रति-मॉडल टोकन, लागत और कॉन्टेक्स्ट-विंडो आंकड़े दिखाता है](/agenteye/images/models.png) +*मॉडल्स पेज: एक लेटेंसी हीट-मैप, एक परसेंटाइल बैंड, और प्रति-मॉडल टोकन, अनुमानित लागत और कॉन्टेक्स्ट-विंडो फिल।* -## औसत को अपने सबसे बुरे रन को छिपाने दें +## औसत को अपने सबसे खराब रन को छिपाने मत दें -औसत लेटेंसी संख्या सुकून देने वाली और बेकार है: यह उस एक कॉल को छिपाती है जो पचास में से एक है जो रुक जाती है और सुबह 2 बजे आपके ऑन-कॉल को पेज करती है। मॉडल, टूल और हुक पेज ऐसा करने से इनकार करते हैं। प्रत्येक समान आकार साझा करता है, इसलिए आप इसे एक बार सीखते हैं: +औसत लेटेंसी संख्या सुकून दायक और बेकार है: यह पचास में से एक कॉल को स्मूथ कर देती है जो रुक जाती है और सुबह 2 बजे आपके ऑन-कॉल को पेज करती है। मॉडल्स, टूल्स और हुक्स पेजेस ऐसा नहीं करते। प्रत्येक एक ही आकार साझा करता है, इसलिए आप इसे एक बार सीखते हैं: -- एक **24-बिन स्पार्कलाइन** एक नज़र में ट्रेंड के लिए: क्या यह बदतर हो रहा है? -- एक **वाइटल्स स्ट्रिप** p50, p95, और p99 लेटेंसी के साथ, ताकि विशिष्ट रन और टेल एक दूसरे के बगल में बैठें। -- एक **लेटेंसी हीट-मैप**, 24 समय बिन द्वारा लेटेंसी बकेट, जो दिखाता है कि *कब* धीमी कॉलें क्लस्टर हुई थीं। -- एक **प्रतिशतक बैंड**: p50 लाइन के साथ p25 से p75 और p10 से p90 छायांकित रिबन और p99 डॉट्स, इसलिए फैलाव औसत से दूर दिखाई देता रहता है। +- एक **24-बिन स्पार्कलाइन** ट्रेंड के लिए एक नज़र में: क्या यह बदतर हो रहा है? +- **महत्वपूर्ण आंकड़ों की पट्टी** p50, p95 और p99 लेटेंसी के साथ, ताकि विशिष्ट रन और टेल एक दूसरे के बगल में बैठें। +- एक **लेटेंसी हीट-मैप**, 24 टाइम बिन्स लेटेंसी बकेट्स द्वारा, जो दिखाता है कि धीमी कॉल कब क्लस्टर हुई। +- एक **परसेंटाइल बैंड**: p50 लाइन के साथ p25 से p75 और p10 से p90 छायांकित रिबन और p99 डॉट्स, ताकि फैलाव औसत होने के बजाय दिखाई दे। -एक साझा होवर क्रॉसहेयर हीट-मैप और बैंड को जोड़ता है, इसलिए एक टेल स्पाइक समय में दोनों के बीच संरेखित होती है एकल माध्य लाइन के पीछे छिपने के बजाय। अपने डैशबोर्ड के **observe** सेक्शन में सभी तीन पृष्ठ खोजें, प्रत्येक आपके संगठन के लिए स्कोप किया गया है और तारीख रेंज, पर्यावरण, एजेंट और सत्र द्वारा फ़िल्टर योग्य है। +एक साझा होवर क्रॉसहेयर हीट-मैप और बैंड को लिंक करता है, इसलिए एक टेल स्पाइक समय में दोनों में संरेखित होती है, एक ही माध्य रेखा के पीछे छिपने के बजाय। अपने डैशबोर्ड के **observe** सेक्शन में तीनों पेज खोजें, प्रत्येक आपके संगठन के दायरे में और तारीख रेंज, वातावरण, एजेंट और सेशन द्वारा फ़िल्ट्रेबल। -## मॉडल: देखें कि प्रत्येक मॉडल आपको कितना खर्च कर रहा है +## मॉडल्स: देखें कि प्रत्येक मॉडल आपको बिल्कुल क्या खर्च करता है -मॉडल पृष्ठ (ऊपर दिखाया गया है) दो सवालों का जवाब देता है जो एक बिल हमेशा उठाता है: कौन सा मॉडल, और कितना। साझा लेटेंसी दृश्य के शीर्ष पर, यह **प्रति-मॉडल टोकन खपत**, **अनुमानित लागत**, और **संदर्भ-विंडो भरण** जोड़ता है, इसलिए भागते हुए प्रॉम्प्ट वृद्धि और आसन्न संपीड़न आपको आश्चर्य करने से पहले दिखाई देते हैं। +मॉडल्स पेज (ऊपर दिखाया गया) दो सवालों का जवाब देता है जो एक बिल हमेशा उठाता है: कौन सा मॉडल, और कितना। साझा लेटेंसी दृश्य के ऊपर, यह **प्रति-मॉडल टोकन खपत**, **अनुमानित लागत** और **कॉन्टेक्स्ट-विंडो फिल** जोड़ता है, इसलिए भागती हुई प्रॉम्प्ट वृद्धि और एक आसन्न कॉम्पैक्शन आपको आश्चर्य देने से पहले दिखाई देते हैं। -Failproof AI Observability सामान्य मॉडल ID को स्वचालित रूप से पहचानता है। यदि कोई विंडो गलत दिखता है, या आप अपना निजी मॉडल चलाते हैं, तो इसे **Settings** के तहत, **model context windows** में सही करें या जोड़ें, और भरण पठन अनुसरण करते हैं। +Failproof AI Observability सामान्य मॉडल आईडी को स्वचालित रूप से पहचानता है। अगर कोई विंडो गलत लगती है, या आप अपना निजी मॉडल चलाते हैं, तो इसे **Settings** में, **model context windows** के तहत ठीक करें या जोड़ें, और फिल रीडआउट का पालन करता है। -## टूल: धीमे को टूटे हुए से अलग करें +## टूल्स: धीमे को टूटे हुए से अलग करें -एक टूल कॉल धीमा हो सकता है, या यह शांति से विफल हो सकता है, और आप इसे सेकंड में जानना चाहते हैं, लॉग के माध्यम से खोदने के बाद नहीं। +एक टूल कॉल धीमी हो सकती है, या वह चुपचाप विफल हो सकती है, और आप इसे सेकंड में जानना चाहते हैं, लॉग्स के माध्यम से खोदने के बाद नहीं। -![टूल पृष्ठ साझा लेटेंसी हीट-मैप और प्रतिशतक बैंड को सफलता और विफलता विभाजन और टूल-वितरण बार के बगल में दिखाता है](/agenteye/images/tools.png) -*टूल पृष्ठ: समान हीट-मैप और प्रतिशतक बैंड, प्लस सफलता और विफलता विभाजन और टूल-वितरण बार।* +![टूल्स पेज जो साझा लेटेंसी हीट-मैप और परसेंटाइल बैंड को सफलता और विफलता के टूटपात और टूल-डिस्ट्रिब्यूशन बार के बगल में दिखाता है](/agenteye/images/tools.png) +*टूल्स पेज: एक ही हीट-मैप और परसेंटाइल बैंड, साथ ही सफलता और विफलता का टूटपात और टूल-डिस्ट्रिब्यूशन बार।* -साझा लेटेंसी दृश्य के साथ, टूल पृष्ठ एक **सफलता और विफलता विभाजन** और एक **टूल-वितरण बार** जोड़ता है, इसलिए आप एक नज़र में देखते हैं कि आप कौन से टूल पर सबसे अधिक निर्भर हैं और कौन सी आपकी त्रुटि बजट को खा रही हैं। +साझा लेटेंसी दृश्य के साथ, टूल्स पेज एक **सफलता और विफलता का टूटपात** और एक **टूल-डिस्ट्रिब्यूशन बार** जोड़ता है, ताकि आप एक नज़र में देख सकें कि आप किन टूल्स पर सबसे ज्यादा निर्भर करते हैं और कौन से आपके त्रुटि बजट को खा रहे हैं। -## हुक: सटीक हुक और ट्रिगर को इंगित करें +## हुक्स: बिल्कुल हुक और ट्रिगर को इंगित करें -जब एक लाइफसाइकल हुक एक रन को खींचता है, तो "हुक धीमे हैं" कुछ ऐसा नहीं है जिस पर आप कार्य कर सकते हैं। हुक पृष्ठ आपको वह लाता है जो महत्वपूर्ण है। +जब एक लाइफसाइकल हुक एक रन को खींचता है, तो "हुक्स धीमे हैं" कुछ ऐसा नहीं है जिस पर आप कार्रवाई कर सकते हैं। हुक्स पेज आपको उस तक पहुंचाता है जो महत्वपूर्ण है। -![हुक पृष्ठ साझा हीट-मैप और प्रतिशतक बैंड पर हुक नाम और ट्रिगर ईवेंट द्वारा विभाजित लेटेंसी दिखाता है](/agenteye/images/hooks.png) -*हुक पृष्ठ: हुक नाम और ट्रिगर ईवेंट द्वारा विभाजित लेटेंसी।* +![हुक्स पेज जो साझा हीट-मैप और परसेंटाइल बैंड पर हुक नाम और ट्रिगर इवेंट द्वारा टूटी हुई लेटेंसी दिखाता है](/agenteye/images/hooks.png) +*हुक्स पेज: हुक नाम और ट्रिगर इवेंट द्वारा टूटी हुई लेटेंसी।* -समान लेटेंसी हीट-मैप और प्रतिशतक बैंड के ऊपर, हुक पृष्ठ गतिविधि को **हुक नाम** और **ट्रिगर ईवेंट** द्वारा विभाजित करता है, इसलिए आप एकल हुक और एकल ईवेंट पर उतरते हैं जिन्हें ध्यान देने की आवश्यकता है। +एक ही लेटेंसी हीट-मैप और परसेंटाइल बैंड पर, हुक्स पेज गतिविधि को **हुक नाम** और **ट्रिगर इवेंट** द्वारा तोड़ देता है, ताकि आप एक हुक और एक इवेंट पर उतरें जिन्हें ध्यान देने की आवश्यकता है। ## संबंधित -- [Event stream](/hi/agenteye/event-stream): हर ईवेंट का लाइव, रंग-कोडित ट्रेल। -- [Sessions](/hi/agenteye/sessions): ईवेंट को एक पंक्ति प्रति रन में रोल करें और इसके निष्पादन ग्राफ को खोलें। -- [Error tracking](/hi/agenteye/error-tracking): डैशबोर्ड को लाल रंग में पेंट करने वाली हर चीज़ के लिए एक ट्रिएज सतह। -- [Dashboards](/hi/agenteye/dashboards): अपने फ्लीट में रोल-अप दृश्य। \ No newline at end of file +- [Event stream](/hi/agenteye/event-stream): हर इवेंट का लाइव, रंग-कोडित ट्रेल। +- [Sessions](/hi/agenteye/sessions): इवेंट्स को एक रन प्रति पंक्ति में रोल करें और इसके निष्पादन ग्राफ को खोलें। +- [Error tracking](/hi/agenteye/error-tracking): सबकुछ के लिए एक ट्रिएज सतह जो डैशबोर्ड लाल में रंगता है। +- [Dashboards](/hi/agenteye/dashboards): आपके फ्लीट में रोल-अप दृश्य। \ No newline at end of file diff --git a/docs/hi/architecture.mdx b/docs/hi/architecture.mdx index f1e69272..0c3ca6dc 100644 --- a/docs/hi/architecture.mdx +++ b/docs/hi/architecture.mdx @@ -1,21 +1,22 @@ --- -title: Architecture +--- +title: आर्किटेक्चर description: "हुक हैंडलर, कॉन्फ़िग लोडिंग और पॉलिसी मूल्यांकन आंतरिक रूप से कैसे काम करते हैं" icon: sitemap --- -यह दस्तावेज़ बताता है कि failproofai आंतरिक रूप से कैसे काम करता है: हुक सिस्टम एजेंट टूल कॉल को कैसे इंटरसेप्ट करता है, कॉन्फ़िग कैसे लोड और मर्ज होता है, पॉलिसीज़ का मूल्यांकन कैसे होता है, और डैशबोर्ड एजेंट गतिविधि की निगरानी कैसे करता है। +यह दस्तावेज़ बताता है कि failproofai आंतरिक रूप से कैसे काम करता है: हुक सिस्टम एजेंट टूल कॉल को कैसे इंटरसेप्ट करता है, कॉन्फ़िग को कैसे लोड और मर्ज करता है, पॉलिसी का मूल्यांकन कैसे करता है, और डैशबोर्ड एजेंट गतिविधि को कैसे मॉनिटर करता है। --- -## Overview +## अवलोकन failproofai के दो स्वतंत्र सबसिस्टम हैं: -1. **हुक हैंडलर** - एक तेज़ CLI सबप्रोसेस जो Claude Code हर एजेंट टूल कॉल पर शुरू करता है। पॉलिसीज़ का मूल्यांकन करता है और एक निर्णय लौटाता है। -2. **एजेंट मॉनिटर (डैशबोर्ड)** - एजेंट सेशन की निगरानी और पॉलिसीज़ प्रबंधन के लिए एक Next.js वेब एप्लिकेशन। +1. **हुक हैंडलर** - एक तेज़ CLI सबप्रोसेस जिसे Claude Code हर एजेंट टूल कॉल पर आमंत्रित करता है। पॉलिसी का मूल्यांकन करता है और निर्णय देता है। +2. **एजेंट मॉनिटर (डैशबोर्ड)** - एजेंट सेशन को मॉनिटर करने और पॉलिसी प्रबंधित करने के लिए एक Next.js वेब एप्लिकेशन। -दोनों सबसिस्टम `~/.failproofai/` और प्रोजेक्ट की `.failproofai/` डायरेक्टरी में कॉन्फ़िग फाइलें साझा करते हैं, लेकिन वे अलग-अलग प्रक्रियाओं के रूप में चलते हैं और केवल फाइलसिस्टम के माध्यम से संचार करते हैं। +दोनों सबसिस्टम `~/.failproofai/` और प्रोजेक्ट की `.failproofai/` निर्देशिका में कॉन्फ़िग फ़ाइलें साझा करते हैं, लेकिन वे अलग-अलग प्रक्रियाओं के रूप में चलते हैं और केवल फ़ाइलसिस्टम के माध्यम से संचार करते हैं। --- @@ -23,7 +24,7 @@ failproofai के दो स्वतंत्र सबसिस्टम ह ### Claude Code के साथ एकीकरण -जब आप `failproofai policies --install` चलाते हैं, तो यह `~/.claude/settings.json` में इस तरह की entries लिखता है: +जब आप `failproofai policies --install` चलाते हैं, तो यह `~/.claude/settings.json` में इस तरह की प्रविष्टियां लिखता है: ```json { @@ -44,9 +45,9 @@ failproofai के दो स्वतंत्र सबसिस्टम ह } ``` -Claude Code फिर हर टूल कॉल से पहले `failproofai --hook PreToolUse` को सबप्रोसेस के रूप में शुरू करता है, stdin पर एक JSON पेलोड पास करता है। +Claude Code फिर हर टूल कॉल से पहले `failproofai --hook PreToolUse` को सबप्रोसेस के रूप में आमंत्रित करता है, stdin पर एक JSON पेलोड पास करता है। -### पेलोड फॉर्मेट +### पेलोड प्रारूप ```json { @@ -60,13 +61,13 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` -`PostToolUse` events के लिए, पेलोड में टूल के आउटपुट के साथ `tool_result` भी होता है। +`PostToolUse` इवेंट के लिए, पेलोड में टूल के आउटपुट के साथ `tool_result` भी होता है। -हैंडलर 1 MB stdin सीमा लागू करता है। इस सीमा से अधिक पेलोड को छोड़ दिया जाता है और सभी पॉलिसीज़ निहित रूप से allow करती हैं। +हैंडलर 1 MB stdin लिमिट लागू करता है। इस लिमिट को पार करने वाले पेलोड को छोड़ दिया जाता है और सभी पॉलिसी स्पष्ट रूप से अनुमति देती हैं। -### Response फॉर्मेट +### रेस्पांस प्रारूप -**Deny (PreToolUse):** +**अस्वीकार (PreToolUse):** ```json { "hookSpecificOutput": { @@ -76,7 +77,7 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` -**Deny (PostToolUse):** +**अस्वीकार (PostToolUse):** ```json { "hookSpecificOutput": { @@ -85,7 +86,7 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` -**Instruct (Stop को छोड़कर कोई भी event):** +**निर्देश (कोई भी इवेंट Stop को छोड़कर):** ```json { "hookSpecificOutput": { @@ -94,17 +95,17 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` -**Stop event instruct:** -- Exit code: `2` -- Reason stderr में लिखा जाता है (stdout में नहीं) +**निर्देश इवेंट रोकें:** +- एक्जिट कोड: `2` +- कारण stderr में लिखा गया (stdout नहीं) -**Allow:** -- Exit code: `0` +**अनुमति दें:** +- एक्जिट कोड: `0` - खाली stdout -**संदेश के साथ Allow:** +**संदेश के साथ अनुमति दें:** -`allow(message)` एक पॉलिसी को Claude को सूचनात्मक context भेजने देता है भले ही ऑपरेशन की अनुमति हो। हुक हैंडलर निम्नलिखित JSON को **stdout** में लिखता है (एक कॉन्फ़िग फाइल में नहीं — यह हैंडलर का Claude Code को response है, deny और instruct responses की तरह): +`allow(message)` एक पॉलिसी को Claude को सूचनात्मक संदर्भ भेजने देता है भले ही ऑपरेशन की अनुमति हो। हुक हैंडलर **stdout** में निम्नलिखित JSON लिखता है (कॉन्फ़िग फ़ाइल नहीं — यह हैंडलर का Claude Code को रेस्पांस है, ठीक deny और instruct रेस्पांस की तरह): ```json // हुक हैंडलर प्रक्रिया द्वारा stdout में लिखा गया @@ -114,79 +115,79 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } } ``` -- Exit code: `0` (ऑपरेशन अनुमति है) -- जब कई पॉलिसीज़ संदेश के साथ `allow` लौटाती हैं, उनके संदेश newlines के साथ एक एकल `additionalContext` string में जोड़े जाते हैं -- अगर कोई पॉलिसी संदेश प्रदान नहीं करती, तो stdout खाली है (पहले की तरह) +- एक्जिट कोड: `0` (ऑपरेशन की अनुमति है) +- जब कई पॉलिसी संदेश के साथ `allow` रिटर्न करती हैं, तो उनके संदेशों को एक एकल `additionalContext` स्ट्रिंग में नई पंक्तियों से जोड़ा जाता है +- यदि कोई पॉलिसी संदेश प्रदान नहीं करती, तो stdout खाली है (पहले की तरह) -### Processing पाइपलाइन +### प्रोसेसिंग पाइपलाइन `src/hooks/handler.ts` पूरी पाइपलाइन को लागू करता है: ```text stdin JSON - → पेलोड को parse करें (अधिकतम 1 MB) + → पेलोड पार्स करें (अधिकतम 1 MB) → सेशन मेटाडेटा निकालें (session_id, cwd, tool_name, tool_input, आदि) - → readMergedHooksConfig(cwd) ← प्रोजेक्ट + local + global कॉन्फ़िग को merge करता है - → resolved params के साथ सक्षम builtin पॉलिसीज़ को register करें - → customPoliciesPath से custom पॉलिसीज़ लोड करें (यदि सेट है) - → custom पॉलिसीज़ को policy registry में register करें - → सभी पॉलिसीज़ का मूल्यांकन करें (पहले builtins, फिर custom) - → पहला deny short-circuits करता है - → instruct decisions जमा होते हैं - → allow messages जमा होते हैं - → JSON निर्णय को stdout में लिखें - → event को ~/.failproofai/hook-activity/current.jsonl में persist करें - → exit करें + → readMergedHooksConfig(cwd) ← प्रोजेक्ट + local + global कॉन्फ़िग मर्ज करता है + → सक्षम builtin पॉलिसी को हल किए गए पैराम के साथ रजिस्टर करें + → customPoliciesPath से कस्टम पॉलिसी लोड करें (यदि सेट है) + → कस्टम पॉलिसी को पॉलिसी रजिस्ट्री में रजिस्टर करें + → सभी पॉलिसी का मूल्यांकन करें (पहले builtins, फिर कस्टम) + → पहली deny शॉर्ट-सर्किट करता है + → instruct निर्णय जमा होते हैं + → allow संदेश जमा होते हैं + → stdout में JSON निर्णय लिखें + → इवेंट को ~/.failproofai/hook-activity/current.jsonl में संरक्षित करें + → एक्जिट करें ``` -पूरी प्रक्रिया 100ms से कम में चलती है typical payloads के लिए कोई LLM कॉल के साथ। +बिना LLM कॉल के विशिष्ट पेलोड के लिए पूरी प्रक्रिया 100ms में चलती है। --- ## कॉन्फ़िग लोडिंग -`src/hooks/hooks-config.ts` तीन-scope कॉन्फ़िग लोडिंग को लागू करता है। +`src/hooks/hooks-config.ts` तीन-स्कोप कॉन्फ़िग लोडिंग लागू करता है। ```text -[1] {cwd}/.failproofai/policies-config.json ← प्रोजेक्ट (सर्वोच्च प्राथमिकता) +[1] {cwd}/.failproofai/policies-config.json ← प्रोजेक्ट (उच्चतम प्राथमिकता) [2] {cwd}/.failproofai/policies-config.local.json ← local -[3] ~/.failproofai/policies-config.json ← global (न्यूनतम प्राथमिकता) +[3] ~/.failproofai/policies-config.json ← global (निम्नतम प्राथमिकता) ``` -Merge logic: -- `enabledPolicies` - सभी तीनों फाइलों में deduplicated union -- `policyParams` - प्रति-पॉलिसी key, पहली फाइल जो इसे परिभाषित करती है पूरी तरह जीतती है -- `customPoliciesPath` - पहली फाइल जो इसे परिभाषित करती है जीतती है -- `llm` - पहली फाइल जो इसे परिभाषित करती है जीतती है +मर्ज लॉजिक: +- `enabledPolicies` - तीनों फ़ाइलों में डीडुप्लिकेटेड यूनियन +- `policyParams` - प्रति-पॉलिसी कुंजी, पहली फ़ाइल जो इसे परिभाषित करती है पूरी तरह जीतती है +- `customPoliciesPath` - पहली फ़ाइल जो इसे परिभाषित करती है जीतती है +- `llm` - पहली फ़ाइल जो इसे परिभाषित करती है जीतती है -वेब डैशबोर्ड `readHooksConfig()` (केवल global) का उपयोग पढ़ने और लिखने के लिए करता है, क्योंकि यह प्रोजेक्ट cwd के साथ शुरू नहीं होता है। +वेब डैशबोर्ड पढ़ने और लिखने के लिए `readHooksConfig()` (केवल global) का उपयोग करता है, क्योंकि इसे प्रोजेक्ट cwd के साथ आमंत्रित नहीं किया जाता है। --- ## पॉलिसी मूल्यांकन -`src/hooks/policy-evaluator.ts` क्रम में पॉलिसीज़ चलाता है। +`src/hooks/policy-evaluator.ts` क्रम में पॉलिसी चलाता है। प्रत्येक पॉलिसी के लिए: -1. पॉलिसी के `params` schema को देखें (यदि इसमें एक है)। -2. merged कॉन्फ़िग से `policyParams[policy.name]` को पढ़ें। -3. `ctx.params` देने के लिए schema defaults पर user-provided values को merge करें। -4. resolved context के साथ `policy.fn(ctx)` को कॉल करें। -5. यदि result `deny` है, तो तुरंत रुकें और वह निर्णय लौटाएं। -6. यदि result `instruct` है, तो संदेश को जमा करें और जारी रखें। -7. यदि result `allow` है, तो अगली पॉलिसी पर जाएं। +1. पॉलिसी के `params` स्कीमा को देखें (यदि इसके पास है)। +2. मर्ज किए गए कॉन्फ़िग से `policyParams[policy.name]` को पढ़ें। +3. `ctx.params` का उत्पादन करने के लिए स्कीमा डिफ़ॉल्ट के ऊपर उपयोगकर्ता-प्रदान की गई मान को मर्ज करें। +4. हल किए गए संदर्भ के साथ `policy.fn(ctx)` को कॉल करें। +5. यदि परिणाम `deny` है, तो तुरंत रुकें और वह निर्णय लौटाएं। +6. यदि परिणाम `instruct` है, तो संदेश को जमा करें और जारी रखें। +7. यदि परिणाम `allow` है, तो अगली पॉलिसी पर जाएं। -सभी पॉलिसीज़ चलने के बाद: -- यदि कोई `deny` लौटाया गया था, तो deny response emit करें। -- यदि कोई `instruct` returns collect किए गए थे, तो एक एकल instruct response emit करें सभी संदेशों के साथ joined। -- अन्यथा, एक allow response emit करें (खाली stdout, exit 0)। +सभी पॉलिसी चलने के बाद: +- यदि कोई `deny` लौटाया गया था, तो deny रेस्पांस उत्सर्जित करें। +- यदि कोई `instruct` रिटर्न एकत्र किए गए थे, तो सभी संदेशों को जोड़कर एक एकल instruct रेस्पांस उत्सर्जित करें। +- अन्यथा, allow रेस्पांस उत्सर्जित करें (खाली stdout, एक्जिट 0)। --- -## Builtin पॉलिसीज़ +## Builtin पॉलिसी -`src/hooks/builtin-policies.ts` सभी 39 built-in पॉलिसीज़ को `BuiltinPolicyDefinition` objects के रूप में परिभाषित करता है: +`src/hooks/builtin-policies.ts` सभी 39 built-in पॉलिसी को `BuiltinPolicyDefinition` ऑब्जेक्ट के रूप में परिभाषित करता है: ```typescript interface BuiltinPolicyDefinition { @@ -204,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -जो पॉलिसीज़ `params` स्वीकार करती हैं वे `PolicyParamsSchema` के साथ प्रत्येक parameter के लिए types और defaults के साथ घोषणा करती हैं। पॉलिसी evaluator resolved values को `ctx.params` में `fn` को कॉल करने से पहले inject करता है। पॉलिसी functions `ctx.params` को null-guarding के बिना पढ़ते हैं क्योंकि defaults हमेशा पहले apply होते हैं। +पॉलिसी जो `params` स्वीकार करती हैं, एक `PolicyParamsSchema` घोषित करती हैं जिसमें प्रत्येक पैरामीटर के लिए प्रकार और डिफ़ॉल्ट होते हैं। पॉलिसी मूल्यांकनकर्ता `fn` को कॉल करने से पहले हल किए गए मान को `ctx.params` में इंजेक्ट करता है। पॉलिसी फ़ंक्शन `ctx.params` को पढ़ते हैं क्योंकि डिफ़ॉल्ट हमेशा पहले लागू होते हैं। -पॉलिसीज़ के अंदर pattern matching parsed command tokens (argv) का उपयोग करता है, raw string matching नहीं। यह shell operator injection के माध्यम से bypass को रोकता है (उदाहरण के लिए `sudo systemctl status *` के लिए एक pattern को command के अंत में `; rm -rf /` append करके bypass नहीं किया जा सकता)। +पॉलिसी के अंदर पैटर्न मिलान parsed command tokens (argv) का उपयोग करता है, कच्ची स्ट्रिंग मिलान नहीं। यह shell operator injection के माध्यम से bypass को रोकता है (उदाहरण के लिए, `sudo systemctl status *` के लिए एक पैटर्न को कमांड के अंत में `; rm -rf /` जोड़कर bypass नहीं किया जा सकता)। --- -## Custom पॉलिसीज़ +## कस्टम पॉलिसी -`src/hooks/custom-hooks-registry.ts` `globalThis`-backed registry को लागू करता है: +`src/hooks/custom-hooks-registry.ts` एक `globalThis`-समर्थित रजिस्ट्री लागू करता है: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -222,28 +223,28 @@ export const customPolicies = { }; export function getCustomHooks(): CustomHook[] { ... } -export function clearCustomHooks(): void { ... } // tests में उपयोग किया जाता है +export function clearCustomHooks(): void { ... } // परीक्षण में उपयोग किया जाता है ``` -`src/hooks/custom-hooks-loader.ts` user की policy फाइल लोड करता है: +`src/hooks/custom-hooks-loader.ts` उपयोगकर्ता की पॉलिसी फ़ाइल लोड करता है: -1. कॉन्फ़िग से `customPoliciesPath` पढ़ें; यदि अनुपस्थित है तो छोड़ दें। -2. Absolute path को resolve करें; फाइल की मौजूदगी की जांच करें। -3. सभी `from "failproofai"` imports को actual dist path पर फिर से लिखें ताकि `customPolicies` same `globalThis` registry को resolve करे। -4. ESM compatibility सुनिश्चित करने के लिए transitive local imports को recursively फिर से लिखें। -5. अस्थायी `.mjs` फाइलें लिखें और entry फाइल को `import()` करें। -6. registered hooks को retrieve करने के लिए `getCustomHooks()` को कॉल करें। -7. `finally` block में सभी temp फाइलें साफ करें। +1. कॉन्फ़िग से `customPoliciesPath` पढ़ें; यदि अनुपस्थित है तो छोड़ें। +2. निरपेक्ष पथ को हल करें; फ़ाइल मौजूद है यह जांचें। +3. सभी `from "failproofai"` इंपोर्ट को वास्तविक dist पथ में फिर से लिखें ताकि `customPolicies` एक ही `globalThis` रजिस्ट्री को हल करे। +4. ESM संगतता सुनिश्चित करने के लिए transitive local इंपोर्ट को पुनरावर्ती रूप से फिर से लिखें। +5. अस्थायी `.mjs` फ़ाइलें लिखें और entry फ़ाइल को `import()` करें। +6. पंजीकृत हुक प्राप्त करने के लिए `getCustomHooks()` को कॉल करें। +7. `finally` ब्लॉक में सभी temp फ़ाइलें साफ़ करें। -किसी भी error (फाइल नहीं मिली, syntax error, import failure) पर, error को `~/.failproofai/hook.log` में log किया जाता है और loader एक खाली array लौटाता है। Built-in पॉलिसीज़ प्रभावित नहीं होती हैं। +किसी भी त्रुटि पर (फ़ाइल नहीं मिली, सिंटैक्स त्रुटि, import विफलता), त्रुटि को `~/.failproofai/hook.log` में लॉग किया जाता है और लोडर एक खाली सरणी लौटाता है। Built-in पॉलिसी प्रभावित नहीं होती हैं। -Custom पॉलिसीज़ सभी built-in पॉलिसीज़ के बाद मूल्यांकन होती हैं। एक custom policy `deny` अभी भी आगे custom पॉलिसीज़ को short-circuits करता है (लेकिन सभी built-ins उस बिंदु तक पहले ही चल चुकी होंगी)। +कस्टम पॉलिसी सभी built-in पॉलिसी के बाद मूल्यांकन की जाती हैं। एक कस्टम पॉलिसी `deny` अभी भी आगे की कस्टम पॉलिसी को शॉर्ट-सर्किट करता है (लेकिन सभी built-in पहले से ही उस बिंदु तक चल चुकी हैं)। --- -## Activity लॉगिंग +## गतिविधि लॉगिंग -हर हुक event के बाद, हैंडलर `~/.failproofai/hook-activity/current.jsonl` में एक JSONL line जोड़ता है, जो एक page तक पहुंचने पर `page--.jsonl` में rotate होता है: +हर हुक इवेंट के बाद, हैंडलर `~/.failproofai/hook-activity/current.jsonl` में एक JSONL लाइन जोड़ता है, जो एक बार पृष्ठ तक पहुंचने पर `page--.jsonl` में घूमता है: ```json { @@ -258,75 +259,75 @@ Custom पॉलिसीज़ सभी built-in पॉलिसीज़ क } ``` -एक line प्रत्येक पॉलिसी के लिए जिसने non-allow निर्णय लिया। Allow निर्णय log नहीं होते हैं (फाइल को छोटा रखने के लिए)। +गैर-allow निर्णय लेने वाली प्रत्येक पॉलिसी के लिए एक लाइन। फ़ाइल को छोटा रखने के लिए Allow निर्णय लॉग नहीं किए जाते हैं। --- -## डैशबोर्ड architecture +## डैशबोर्ड आर्किटेक्चर -डैशबोर्ड एक **Next.js 16** एप्लिकेशन है जो App Router के साथ React Server Components और Server Actions का उपयोग करती है। +डैशबोर्ड एक **Next.js 16** एप्लिकेशन है जो App Router को React Server Components और Server Actions के साथ उपयोग करता है। ```text app/ - layout.tsx ← Root layout (theme, telemetry, nav) - projects/page.tsx ← Server component: सभी Claude projects को list करें - project/[name]/page.tsx ← Server component: एक project में sessions को list करें + layout.tsx ← रूट लेआउट (थीम, टेलीमेट्री, नेव) + projects/page.tsx ← सर्वर कंपोनेंट: सभी Claude प्रोजेक्ट सूचीबद्ध करें + project/[name]/page.tsx ← सर्वर कंपोनेंट: प्रोजेक्ट में सेशन सूचीबद्ध करें project/[name]/session/ - [sessionId]/page.tsx ← Server component: session viewer को render करें - policies/page.tsx ← Client component: policy management + activity log + [sessionId]/page.tsx ← सर्वर कंपोनेंट: सेशन viewer रेंडर करें + policies/page.tsx ← क्लाइंट कंपोनेंट: पॉलिसी प्रबंधन + गतिविधि लॉग actions/ - get-hooks-config.ts ← कॉन्फ़िग + policy list पढ़ें - update-hooks-config.ts ← Policy को on/off करें - update-policy-params.ts ← Policy parameters को update करें - get-hook-activity.ts ← Activity log को paginate/search करें - install-hooks-web.ts ← Browser से hooks को install/remove करें + get-hooks-config.ts ← कॉन्फ़िग + पॉलिसी सूची पढ़ें + update-hooks-config.ts ← पॉलिसी चालू/बंद करें + update-policy-params.ts ← पॉलिसी पैरामीटर अपडेट करें + get-hook-activity.ts ← गतिविधि लॉग को पेजिनेट/सर्च करें + install-hooks-web.ts ← ब्राउज़र से हुक इंस्टॉल/निकालें api/ - download/[project]/[session]/route.ts ← Per-CLI session export (JSONL या JSON) + download/[project]/[session]/route.ts ← प्रति-CLI सेशन एक्सपोर्ट (JSONL या JSON) ``` -**डेटा flow:** +**डेटा फ्लो:** -- Page components `lib/projects.ts` और `lib/log-entries.ts` को कॉल करते हैं प्रोजेक्ट/सेशन डेटा को फाइलसिस्टम से सीधे पढ़ने के लिए (reads के लिए कोई API layer नहीं)। -- Policies page सभी mutations के लिए Server Actions का उपयोग करता है (toggle, params update, install/remove)। -- Session viewer Claude के JSONL transcript format को parse करता है और messages और tool calls की एक timeline को render करता है। +- पृष्ठ कंपोनेंट फ़ाइलसिस्टम से सीधे प्रोजेक्ट/सेशन डेटा पढ़ने के लिए `lib/projects.ts` और `lib/log-entries.ts` को कॉल करते हैं (पढ़ने के लिए कोई API परत नहीं)। +- Policies पृष्ठ सभी mutations (टॉगल, params अपडेट, इंस्टॉल/निकालें) के लिए Server Actions का उपयोग करता है। +- सेशन viewer Claude के JSONL ट्रांसक्रिप्ट प्रारूप को पार्स करता है और संदेश और टूल कॉल की एक timeline को रेंडर करता है। -**मुख्य design निर्णय:** +**मुख्य डिज़ाइन निर्णय:** -- कोई डेटाबेस नहीं - सभी persistent state plain फाइलों में है (`~/.failproofai/`, `~/.claude/projects/`)। -- Mutations के लिए Server Actions - CRUD operations के लिए कोई REST API की ज़रूरत नहीं। -- Read pages के लिए React Server Components - तेज़ initial load, data fetching के लिए कोई client bundle नहीं। -- Client components केवल जहां interactivity की ज़रूरत है (policy toggles, activity search, log viewer)। +- कोई डेटाबेस नहीं - सभी persistent state सादी फ़ाइलों में है (`~/.failproofai/`, `~/.claude/projects/`)। +- Mutations के लिए Server Actions - CRUD ऑपरेशन के लिए कोई REST API की जरूरत नहीं। +- Read पृष्ठों के लिए React Server Components - तेज़ प्रारंभिक लोड, डेटा fetching के लिए कोई क्लाइंट bundle नहीं। +- क्लाइंट कंपोनेंट केवल जहां इंटरैक्टिविटी आवश्यक है (पॉलिसी टॉगल, गतिविधि सर्च, लॉग viewer)। --- -## फाइल layout +## फ़ाइल लेआउट ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI router (hook / dashboard / install / आदि) +│ └── failproofai.mjs # CLI राउटर (hook / dashboard / install / आदि) ├── src/hooks/ -│ ├── handler.ts # Hook event pipeline -│ ├── builtin-policies.ts # 39 policy definitions -│ ├── policy-evaluator.ts # Policy execution engine -│ ├── policy-registry.ts # Policy registration और lookup +│ ├── handler.ts # हुक इवेंट पाइपलाइन +│ ├── builtin-policies.ts # 39 पॉलिसी परिभाषाएं +│ ├── policy-evaluator.ts # पॉलिसी execution engine +│ ├── policy-registry.ts # पॉलिसी registration और lookup │ ├── policy-types.ts # TypeScript interfaces -│ ├── hooks-config.ts # Multi-scope config loading -│ ├── custom-hooks-registry.ts # globalThis-backed hook registry -│ ├── custom-hooks-loader.ts # User JS hooks के लिए ESM loader -│ ├── manager.ts # install / remove / list operations -│ ├── install-prompt.ts # Interactive policy selection prompt -│ ├── hook-logger.ts # hook.log में logging -│ ├── hook-activity-store.ts # hook-activity/ में activity को persist करें -│ └── llm-client.ts # LLM API client (AI-powered policies के लिए) -├── app/ # Next.js dashboard (pages + server actions) -├── lib/ # Shared utilities -│ ├── projects.ts # फाइलसिस्टम से Claude projects को enumerate करें -│ ├── log-entries.ts # Claude transcript JSONL format को parse करें -│ ├── paths.ts # System paths को resolve करें +│ ├── hooks-config.ts # Multi-scope कॉन्फ़िग लोडिंग +│ ├── custom-hooks-registry.ts # globalThis-समर्थित हुक रजिस्ट्री +│ ├── custom-hooks-loader.ts # उपयोगकर्ता JS हुक के लिए ESM लोडर +│ ├── manager.ts # install / remove / list ऑपरेशन +│ ├── install-prompt.ts # इंटरैक्टिव पॉलिसी चयन prompt +│ ├── hook-logger.ts # hook.log में लॉगिंग +│ ├── hook-activity-store.ts # hook-activity/ में गतिविधि persist करें +│ └── llm-client.ts # LLM API क्लाइंट (AI-चालित पॉलिसी के लिए) +├── app/ # Next.js डैशबोर्ड (pages + server actions) +├── lib/ # साझा उपयोगिताएं +│ ├── projects.ts # फ़ाइलसिस्टम से Claude प्रोजेक्ट गणना करें +│ ├── log-entries.ts # Claude ट्रांसक्रिप्ट JSONL प्रारूप पार्स करें +│ ├── paths.ts # सिस्टम पथ को हल करें │ └── ... -├── components/ # Shared React UI components -├── contexts/ # React context providers (theme, auto-refresh, telemetry) -├── examples/ # Example custom hook files -└── __tests__/ # Unit और E2E tests +├── components/ # साझा React UI कंपोनेंट +├── contexts/ # React context प्रदाता (थीम, auto-refresh, टेलीमेट्री) +├── examples/ # उदाहरण कस्टम हुक फ़ाइलें +└── __tests__/ # यूनिट और E2E परीक्षण ``` \ No newline at end of file diff --git a/docs/hi/built-in-policies.mdx b/docs/hi/built-in-policies.mdx index 169410e5..1409caab 100644 --- a/docs/hi/built-in-policies.mdx +++ b/docs/hi/built-in-policies.mdx @@ -1,39 +1,39 @@ --- -title: बिल्ट-इन पॉलिसीज़ -description: "सभी 39 बिल्ट-इन पॉलिसीज़ जो एजेंट की आम विफलताओं को पकड़ते हैं" +title: अंतर्निर्मित नीतियां +description: "सभी 39 अंतर्निर्मित नीतियां जो सामान्य एजेंट विफलता मोड को पकड़ती हैं" icon: shield --- -failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ आता है जो एजेंट की आम विफलता मोड को पकड़ते हैं। प्रत्येक पॉलिसी एक विशिष्ट हुक इवेंट प्रकार और टूल नाम पर काम करती है। उन्नीस पॉलिसीज़ पैरामीटर स्वीकार करती हैं जो आपको कोड लिखे बिना उनके व्यवहार को ट्यून करने देते हैं। पाँच वर्कफ़्लो पॉलिसीज़ एक commit → push → PR → CI पाइपलाइन को लागू करती हैं जिससे पहले Claude रुक जाता है। +failproofai 39 अंतर्निर्मित नीतियों के साथ आता है जो सामान्य एजेंट विफलता मोड को पकड़ती हैं। प्रत्येक नीति एक विशिष्ट हुक ईवेंट प्रकार और टूल नाम पर काम करती है। उन्नीस नीतियां पैरामीटर स्वीकार करती हैं जो आपको कोड लिखे बिना उनके व्यवहार को ट्यून करने देती हैं। पाँच वर्कफ़्लो नीतियां Claude बंद होने से पहले एक कमिट → पुश → PR → CI पाइपलाइन को लागू करती हैं। --- ## अवलोकन -पॉलिसीज़ को श्रेणियों में बाँटा गया है: +नीतियां निम्नलिखित श्रेणियों में विभाजित हैं: -| श्रेणी | पॉलिसीज़ | हुक प्रकार | +| श्रेणी | नीतियां | हुक प्रकार | |----------|----------|-----------| -| [खतरनाक कमांड](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | -| [इन्फ्रा कमांड](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [सीक्रेट्स (सैनिटाइज़र)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | -| [पर्यावरण](#environment) | block-env-files, protect-env-vars | PreToolUse | -| [फ़ाइल एक्सेस](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| [खतरनाक कमांड](#खतरनाक-कमांड) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | +| [इन्फ्रा कमांड](#इन्फ्रा-कमांड) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [सीक्रेट (सैनिटाइज़र)](#सीक्रेट-सैनिटाइज़र) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [पर्यावरण](#पर्यावरण) | block-env-files, protect-env-vars | PreToolUse | +| [फ़ाइल एक्सेस](#फ़ाइल-एक्सेस) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | -| [डेटाबेस](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | -| [चेतावनियाँ](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [पैकेज मैनेजर](#package-managers) | prefer-package-manager | PreToolUse | -| [वर्कफ़्लो](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | +| [डेटाबेस](#डेटाबेस) | warn-destructive-sql, warn-schema-alteration | PreToolUse | +| [चेतावनियां](#चेतावनियां) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | +| [पैकेज मैनेजर](#पैकेज-मैनेजर) | prefer-package-manager | PreToolUse | +| [वर्कफ़्लो](#वर्कफ़्लो) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | - **`block-`** — एजेंट को आगे बढ़ने से रोकता है। -- **`warn-`** — एजेंट को अतिरिक्त संदर्भ देता है ताकि यह स्व-सुधार कर सके। -- **`sanitize-`** — एजेंट को देखने से पहले टूल आउटपुट से संवेदनशील डेटा हटाता है। +- **`warn-`** — एजेंट को अतिरिक्त संदर्भ देता है ताकि वह स्वयं को ठीक कर सके। +- **`sanitize-`** — एजेंट को देखने से पहले टूल आउटपुट से संवेदनशील डेटा को साफ करता है। ### नेमस्पेस -प्रत्येक पॉलिसी एक `/` स्लॉट में रहती है। बिल्ट-इन पॉलिसीज़ **`failproofai/`** नेमस्पेस से संबंधित हैं — उदाहरण के लिए, `failproofai/sanitize-jwt`। नेमस्पेस तब टकराव को रोकता है जब आप समान छोटे नाम वाली कस्टम या तीसरे पक्ष की पॉलिसीज़ भी लोड करते हैं। +हर नीति एक `/` स्लॉट में रहती है। अंतर्निर्मित नीतियां **`failproofai/`** नेमस्पेस से संबंधित हैं — उदाहरण के लिए, `failproofai/sanitize-jwt`। नेमस्पेस टकराव को रोकता है जब आप समान छोटे नाम वाली कस्टम या तीसरे पक्ष की नीतियां भी लोड करते हैं। -आपके कॉन्फ़िग में आप एक बिल्ट-इन को या तो इसके छोटे नाम या योग्य नाम से संदर्भित कर सकते हैं; दोनों रूप एक ही पॉलिसी को हल करते हैं: +आपके कॉन्फ़िग में आप एक अंतर्निर्मित को उसके छोटे नाम या योग्य नाम से संदर्भित कर सकते हैं; दोनों रूप समान नीति को हल करते हैं: ```json { @@ -44,39 +44,39 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ } ``` -यदि किसी नाम में कोई `/` नहीं है, तो failproofai इसे डिफ़ॉल्ट नेमस्पेस `failproofai` के रूप में मानता है। नाम जिनमें पहले से `/` है (जैसे `myorg/foo`, `custom/my-hook`) वैसे ही रखे जाते हैं। -- **`require-`** — Stop इवेंट को तब तक ब्लॉक करता है जब तक शर्तें पूरी न हों। +यदि किसी नाम में `/` नहीं है, तो failproofai इसे डिफ़ॉल्ट नेमस्पेस `failproofai` से संबंधित मानता है। नाम जिनमें पहले से `/` है (जैसे `myorg/foo`, `custom/my-hook`) को जैसे हैं वैसे ही रखा जाता है। +- **`require-`** — जब तक शर्तें पूरी न हों तब तक Stop ईवेंट को ब्लॉक करता है। --- -प्रत्येक पॉलिसी `policyParams` में एक वैकल्पिक `hint` फील्ड का समर्थन करती है। hint को deny या instruct संदेश में जोड़ा जाता है जो Claude देखता है, पॉलिसी कोड में संशोधन किए बिना कार्रवाई योग्य मार्गदर्शन देता है। बिल्ट-इन, कस्टम और कन्वेंशन पॉलिसीज़ के साथ काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/configuration#hint-cross-cutting) देखें। +हर नीति `policyParams` में एक वैकल्पिक `hint` फ़ील्ड का समर्थन करती है। हिंट को deny या instruct संदेश में जोड़ा जाता है जो Claude देखता है, जिससे नीति कोड को संशोधित किए बिना कार्रवाई योग्य मार्गदर्शन मिलता है। अंतर्निर्मित, कस्टम, और सम्मेलन नीतियों के साथ काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/configuration#hint-cross-cutting) देखें। --- ## खतरनाक कमांड -एजेंट को ऐसे ऑपरेशन चलाने से रोकें जो पूर्ववत करने में कठिन हों या जो होस्ट सिस्टम को नुकसान पहुँचा सकते हों। +एजेंटों को ऐसी संचालन से रोकता है जो उलटाना मुश्किल हैं या जो होस्ट सिस्टम को नुकसान पहुंचा सकते हैं। ### `block-sudo` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `sudo` या `doas` कमांड को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `sudo` या `doas` कमांड को अस्वीकार करता है। -एक कमांड को ब्लॉक करता है जो **कमांड स्थिति** में एक elevation बाइनरी चलाता है। मिलान संरचनात्मक है पाठात्मक नहीं: कमांड को उन सेगमेंट में विभाजित किया जाता है जैसे एक शेल करेगा, उपसर्ग असाइनमेंट (`FOO=bar`), रीडायरेक्शन, और रनर अपने फ़्लैग्स (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) के साथ हटा दिए जाते हैं, और परिणामी बाइनरी **basename** द्वारा तुलना की जाती है। तो `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` और `bash -c "sudo …"` सभी को नकार दिया जाता है, और `doas` को एक अलग नाम के तहत एक ही क्षमता के रूप में माना जाता है। +एक कमांड को ब्लॉक करता है जो **कमांड स्थिति** में एक एलिवेशन बाइनरी चलाता है। मिलान पाठ्य के बजाय संरचनात्मक है: कमांड को उस तरह से खंडों में विभाजित किया जाता है जिस तरह एक शेल करेगा, उपसर्ग असाइनमेंट (`FOO=bar`), पुनर्निर्देश, और रनर अपने झंडों के साथ (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) को हटा दिया जाता है, और परिणामी बाइनरी की तुलना **basename** द्वारा की जाती है। तो `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` और `bash -c "sudo …"` सभी को अस्वीकार किया जाता है, और `doas` को एक अलग नाम के तहत समान क्षमता के रूप में माना जाता है। -क्योंकि यह कमांड स्थिति पर लंगर डालता है शब्द कहीं भी दिखाई देने पर नहीं, यह **नहीं** कमांड पर काम करता है जो केवल इसका उल्लेख करते हैं — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, या `grep` वैकल्पिकता युक्त शब्द सामान्य रूप से चलते हैं। +क्योंकि यह कमांड स्थिति पर एंकर करता है किसी भी जगह शब्द दिखने के बजाय, यह कमांड पर **नहीं** चलता है जो केवल इसका उल्लेख करते हैं — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, या एक `grep` वैकल्पिक सभी सामान्य रूप से चलते हैं। -यह स्पष्ट प्रयास को रोकता है; यह श्रेणी को बंद नहीं करता। एक एजेंट जो मनमानी शेल चला सकता है अभी भी अप्रत्यक्ष रूप से elevation तक पहुँच सकता है — एक वेरिएबल (`S=sudo; $S …`), एक base64-डिकोडेड पाइप, या डिस्क पर एक रैपर स्क्रिप्ट के माध्यम से — क्योंकि एक भी कमांड स्ट्रिंग का कोई निरीक्षण उन का पालन नहीं कर सकता। इसे गलतियों और आकस्मिक स्केलिंग के विरुद्ध गार्ड के रूप में देखें, एक निर्धारित एजेंट के विरुद्ध सुरक्षा सीमा के रूप में नहीं। एक वास्तविक सीमा को शेल के नीचे लागू किया जाना चाहिए। +यह स्पष्ट प्रयास को रोकता है; यह वर्ग को बंद नहीं करता है। एक एजेंट जो मनमाना शेल चला सकता है फिर भी अप्रत्यक्ष रूप से एलिवेशन तक पहुंच सकता है — एक वेरिएबल (`S=sudo; $S …`), एक base64-डिकोडेड पाइप, या डिस्क पर एक रैपर स्क्रिप्ट के माध्यम से — क्योंकि कोई एकल कमांड स्ट्रिंग की निरीक्षा उन का पालन नहीं कर सकता है। इसे गलतियों और आकस्मिक स्केलिंग के खिलाफ गार्डरेल के रूप में मानें, एक निर्धारित एजेंट के खिलाफ सुरक्षा सीमा के रूप में नहीं। एक वास्तविक सीमा को शेल के नीचे लागू करना है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | अनुमत सटीक कमांड उपसर्ग। प्रत्येक प्रविष्टि को पार्स किए गए argv टोकन के विरुद्ध मिलाया जाता है। | +| `allowPatterns` | `string[]` | `[]` | सटीक कमांड उपसर्ग जो अनुमति दिए जाते हैं। प्रत्येक प्रविष्टि को पार्स किए गए argv टोकन के विरुद्ध मिलान किया जाता है। | **उदाहरण:** @@ -90,24 +90,24 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ } ``` -इस कॉन्फ़िग के साथ, `sudo systemctl status nginx` अनुमत है, लेकिन `sudo rm /etc/hosts` नकार दिया जाता है। +इस कॉन्फ़िग के साथ, `sudo systemctl status nginx` की अनुमति है, लेकिन `sudo rm /etc/hosts` को अस्वीकार किया जाता है। -पैटर्न को पार्स किए गए टोकन के विरुद्ध मिलाया जाता है, कच्ची कमांड स्ट्रिंग के विरुद्ध नहीं। यह अंत में जोड़े गए शेल ऑपरेटर के माध्यम से बाईपास को रोकता है (उदा. `sudo systemctl status x; rm -rf /` `sudo systemctl status *` से मेल नहीं खाता)। +पैटर्न को कच्ची कमांड स्ट्रिंग के बजाय पार्स किए गए टोकन के विरुद्ध मिलान किया जाता है। यह संलग्न शेल ऑपरेटर के माध्यम से बाईपास को रोकता है (उदाहरण के लिए `sudo systemctl status x; rm -rf /` `sudo systemctl status *` से मेल नहीं खाता)। --- ### `block-rm-rf` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `rm -rf`, `rm -fr` और समान पुनरावर्ती विलोपन रूपों को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `rm -rf`, `rm -fr`, और समान पुनरावर्ती विलोपन रूपों को अस्वीकार करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | पाथ जो पुनरावर्ती रूप से हटाने के लिए सुरक्षित हैं (उदा. `/tmp`)। | +| `allowPaths` | `string[]` | `[]` | पथ जो पुनरावर्ती रूप से हटाने के लिए सुरक्षित हैं (उदाहरण के लिए, `/tmp`)। | **उदाहरण:** @@ -125,8 +125,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-curl-pipe-sh` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `curl | bash`, `curl | sh`, `wget | bash` और समान पैटर्न को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `curl | bash`, `curl | sh`, `wget | bash`, और समान पैटर्न को अस्वीकार करता है। कोई पैरामीटर नहीं। @@ -134,8 +134,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-failproofai-commands` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** कमांड को नकारता है जो failproofai को स्वयं अनइंस्टॉल या अक्षम करेंगे (उदा. `npm uninstall failproofai`, `failproofai policies --uninstall`)। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** ऐसी कमांड को अस्वीकार करता है जो failproofai को अनइंस्टॉल या अक्षम करेंगी (उदाहरण के लिए, `npm uninstall failproofai`, `failproofai policies --uninstall`)। कोई पैरामीटर नहीं। @@ -143,12 +143,12 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-self-pause` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `failproofai config --pause` को नकारता है, जो एक सेशन के लिए enforcement को निलंबित करता है। Pause एक मानव निर्णय है — एक एजेंट जो इसे चला सकता है एक ही कमांड से हर दूसरी पॉलिसी को बंद कर सकता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `failproofai config --pause` को अस्वीकार करता है, जो एक सत्र के लिए प्रवर्तन को निलंबित करता है। पॉज़ करना एक मानव निर्णय है — एक एजेंट जो इसे चला सकता है प्रत्येक अन्य नीति को एक एकल कमांड से बंद कर सकता है। -[`block-failproofai-commands`](#block-failproofai-commands) की तुलना में संकीर्ण इरादे से, और इससे कवर नहीं है: वह पॉलिसी एक कमांड सीमा पर लंगर डालती है, तो `npx -y failproofai config --pause` इससे मेल नहीं खाता, और व्यापक होने के कारण अक्सर इसे बंद कर दिया जाता है ताकि एजेंट `failproofai audit` चला सकें। `--resume` और `--status` अनुमत हैं — न ही enforcement को हटाता है। +[`block-failproofai-commands`](#block-failproofai-commands) की तुलना में उद्देश्य पर संकीर्ण, और इसमें कवर नहीं है: वह नीति एक कमांड सीमा पर एंकर करती है, इसलिए `npx -y failproofai config --pause` इसे नहीं दिखता, और व्यापक होना अक्सर इसे बंद किया जाता है ताकि एजेंट `failproofai audit` चला सकें। `--resume` और `--status` की अनुमति है — न ही प्रवर्तन को हटाता है। -यह सीधे प्रयास को रोकता है, पूरी श्रेणी को नहीं: एक एजेंट अभी भी एक alias या रैपर स्क्रिप्ट के माध्यम से एक ही स्थिति तक पहुँच सकता है। इसे पूरी तरह बंद करने के लिए pause को एक टूल कॉल से पूरी तरह अप्राप्य होना पड़ता है। +यह सीधी कोशिश को रोकता है, पूरी कक्षा को नहीं: एक एजेंट अभी भी एक उपनाम या डिस्क पर एक रैपर स्क्रिप्ट के माध्यम से समान स्थिति तक पहुंच सकता है। इसे पूरी तरह से बंद करने के लिए पॉज़ को एक टूल कॉल से पूरी तरह से अप्राप्य होना है। कोई पैरामीटर नहीं। @@ -156,20 +156,20 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## इन्फ्रा कमांड -कोडिंग एजेंट को infrastructure CLIs चलाने या CI/CD पाइपलाइन ट्रिगर करने से रोकें। इस श्रेणी में सभी पॉलिसीज़ **opt-in** हैं (`defaultEnabled: false`) — एजेंट जिन्हें `kubectl`, `terraform`, आदि को कॉल करने की वैध आवश्यकता है व्यवधान से प्रभावित नहीं होंगे जब तक आप पॉलिसी सक्षम न करें। सक्षम होने पर, मिलान किए गए CLI की प्रत्येक invocation को नकार दिया जाता है जब तक कमांड `allowPatterns` में किसी प्रविष्टि से मेल नहीं खाता। +कोडिंग एजेंटों को बुनियादी ढांचे CLI चलाने या CI/CD पाइपलाइन को ट्रिगर करने से रोकता है। इस श्रेणी में सभी नीतियां **opt-in** हैं (`defaultEnabled: false`) — एजेंट जिन्हें वैध रूप से `kubectl`, `terraform`, आदि को कॉल करने की आवश्यकता है, यदि आप नीति को सक्षम न करें तो परेशान नहीं होंगे। जब सक्षम होता है, तो मेल किए गए CLI की हर आह्वान को अस्वीकार कर दिया जाता है जब तक कि कमांड `allowPatterns` में एक प्रविष्टि से मेल न खाए। -पैटर्न व्याकरण [`block-sudo`](#block-sudo) जैसा है: टोकन को पार्स किए गए argv के विरुद्ध मिलाया जाता है, `*` एक टोकन के लिए wildcard है, और कोई भी कमांड जिसमें standalone शेल ऑपरेटर (`&&`, `||`, `|`, `;`) या embedded शेल metacharacters वाला टोकन है injection bypasses को रोकने के लिए allowlist मिलान से पहले अस्वीकार किया जाता है। +पैटर्न व्याकरण [`block-sudo`](#block-sudo) जैसा ही है: टोकन को पार्स किए गए argv के विरुद्ध मिलान किया जाता है, `*` एक टोकन के लिए एक वाइल्डकार्ड है, और किसी भी कमांड में एक स्टैंडअलोन शेल ऑपरेटर (`&&`, `||`, `|`, `;`) या एम्बेडेड शेल मेटाकैरेक्टर वाला एक टोकन allowlist मिलान से पहले इंजेक्शन बाईपास को रोकने के लिए अस्वीकार किया जाता है। ### `block-kubectl` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `kubectl` invocation को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `kubectl` आह्वान को अस्वीकार करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | kubectl कमांड उपसर्ग जो अनुमत हैं। | +| `allowPatterns` | `string[]` | `[]` | kubectl कमांड उपसर्ग जो अनुमति दिए जाते हैं। | **उदाहरण:** @@ -183,20 +183,20 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ } ``` -इस कॉन्फ़िग के साथ, `kubectl get pods` अनुमत है लेकिन `kubectl apply -f deploy.yaml` नकार दिया जाता है। +इस कॉन्फ़िग के साथ, `kubectl get pods` की अनुमति है लेकिन `kubectl apply -f deploy.yaml` को अस्वीकार किया जाता है। --- ### `block-terraform` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `terraform` या `tofu` (OpenTofu) invocation को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `terraform` या `tofu` (OpenTofu) आह्वान को अस्वीकार करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | terraform/tofu कमांड उपसर्ग जो अनुमत हैं। | +| `allowPatterns` | `string[]` | `[]` | terraform/tofu कमांड उपसर्ग जो अनुमति दिए जाते हैं। | **उदाहरण:** @@ -214,14 +214,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-aws-cli` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `aws` CLI invocation को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `aws` CLI आह्वान को अस्वीकार करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | aws CLI कमांड उपसर्ग जो अनुमत हैं। | +| `allowPatterns` | `string[]` | `[]` | aws CLI कमांड उपसर्ग जो अनुमति दिए जाते हैं। | **उदाहरण:** @@ -239,14 +239,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-gcloud` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `gcloud` (Google Cloud) CLI invocation को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `gcloud` (Google Cloud) CLI आह्वान को अस्वीकार करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | gcloud कमांड उपसर्ग जो अनुमत हैं। | +| `allowPatterns` | `string[]` | `[]` | gcloud कमांड उपसर्ग जो अनुमति दिए जाते हैं। | **उदाहरण:** @@ -264,14 +264,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-az-cli` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `az` (Azure) CLI invocation को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `az` (Azure) CLI आह्वान को अस्वीकार करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | az CLI कमांड उपसर्ग जो अनुमत हैं। | +| `allowPatterns` | `string[]` | `[]` | az CLI कमांड उपसर्ग जो अनुमति दिए जाते हैं। | **उदाहरण:** @@ -289,14 +289,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-helm` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `helm` invocation को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `helm` आह्वान को अस्वीकार करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | helm कमांड उपसर्ग जो अनुमत हैं। | +| `allowPatterns` | `string[]` | `[]` | helm कमांड उपसर्ग जो अनुमति दिए जाते हैं। | **उदाहरण:** @@ -314,8 +314,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-gh-pipeline` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** निम्नलिखित `gh` CLI subcommands को नकारता है जो स्थिति में परिवर्तन करते हैं या पाइपलाइन ट्रिगर करते हैं: +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** निम्नलिखित `gh` CLI सबकमांड को अस्वीकार करता है जो स्थिति को बदलते हैं या पाइपलाइन को ट्रिगर करते हैं: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -324,13 +324,13 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ - `gh cache delete` - `gh secret set`, `gh secret delete` -केवल-पढ़ने के लिए `gh` subcommands जैसे `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, और `gh api repos/.../...` इस पॉलिसी से **मेल नहीं** खाते — वे वर्कफ़्लो जाँच के लिए नियमित रूप से आवश्यक हैं (failproofai के अपने `require-ci-green-before-stop` सहित)। +केवल-पढ़ने के लिए `gh` सबकमांड जैसे `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, और `gh api repos/.../...` इस नीति से मेल **नहीं** खाते हैं — वर्कफ़्लो जांचों के लिए नियमित रूप से आवश्यक हैं (failproofai के अपने `require-ci-green-before-stop` सहित)। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | विशिष्ट स्क्रिप्ट invocations अनुमत करने के लिए भले ही वे अन्यथा नकार दिए जाएंगे। | +| `allowPatterns` | `string[]` | `[]` | विशिष्ट स्क्रिप्टेड आह्वान जिन्हें अनुमति है भले ही वे अन्यथा अस्वीकार कर दिए जाते। | **उदाहरण:** @@ -346,14 +346,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ --- -## सीक्रेट्स (सैनिटाइज़र) +## सीक्रेट (सैनिटाइज़र) -एजेंट को credentials को अपने संदर्भ में या आउटपुट में लीक करने से रोकें। सैनिटाइज़र पॉलिसीज़ **PostToolUse** इवेंट पर काम करती हैं। जब Claude एक Bash कमांड चलाता है, एक फ़ाइल पढ़ता है, या कोई भी टूल कॉल करता है, ये पॉलिसीज़ आउटपुट का निरीक्षण करती हैं इससे पहले कि यह Claude को वापस किया जाए। यदि एक सीक्रेट पैटर्न पाया जाता है, पॉलिसी एक नकार निर्णय लौटाती है जो आउटपुट को पास होने से रोकती है। +एजेंटों को अपने संदर्भ या आउटपुट में क्रेडेंशियल लीक करने से रोकता है। सैनिटाइज़र नीतियां **PostToolUse** ईवेंट पर चलती हैं। जब Claude एक Bash कमांड चलाता है, एक फ़ाइल पढ़ता है, या कोई भी टूल कॉल करता है, तो ये नीतियां आउटपुट को Claude को लौटाए जाने से पहले निरीक्षण करती हैं। यदि एक सीक्रेट पैटर्न का पता चलता है, तो नीति एक अस्वीकार निर्णय लौटाती है जो आउटपुट को वापस पास किए जाने को रोकता है। ### `sanitize-jwt` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** JWT टोकन को हटाता है (तीन base64url सेगमेंट `.` द्वारा अलग)। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** JWT टोकन को हटाता है (`.` से अलग किए गए तीन base64url खंड)। कोई पैरामीटर नहीं। @@ -361,14 +361,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `sanitize-api-keys` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** सामान्य API कुंजी प्रारूपों को हटाता है: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS एक्सेस कुंजी (`AKIA`), Stripe कुंजी (`sk_live_`, `sk_test_`), और Google API कुंजी (`AIza`)। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** सामान्य API कुंजी प्रारूप को हटाता है: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), AWS एक्सेस कुंजी (`AKIA`), Stripe कुंजी (`sk_live_`, `sk_test_`), और Google API कुंजी (`AIza`)। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | सीक्रेट के रूप में मानने के लिए अतिरिक्त regex पैटर्न। | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | सीक्रेट के रूप में इलाज करने के लिए अतिरिक्त regex पैटर्न। | **उदाहरण:** @@ -389,8 +389,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `sanitize-connection-strings` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** डेटाबेस कनेक्शन स्ट्रिंग को हटाता है जिनमें embedded credentials हैं (उदा. `postgresql://user:password@host/db`)। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** डेटाबेस कनेक्शन स्ट्रिंग को हटाता है जिनमें एम्बेडेड क्रेडेंशियल हैं (उदाहरण के लिए, `postgresql://user:password@host/db`)। कोई पैरामीटर नहीं। @@ -398,7 +398,7 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `sanitize-private-key-content` -**इवेंट:** PostToolUse (सभी टूल्स) +**ईवेंट:** PostToolUse (सभी टूल) **डिफ़ॉल्ट:** PEM ब्लॉक को हटाता है (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, आदि)। कोई पैरामीटर नहीं। @@ -407,8 +407,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `sanitize-bearer-tokens` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** `Authorization: Bearer ` हेडर को हटाता है जहाँ टोकन 20 या अधिक वर्ण है। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** `Authorization: Bearer ` हेडर को हटाता है जहां टोकन 20 या अधिक वर्ण हैं। कोई पैरामीटर नहीं। @@ -416,14 +416,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## पर्यावरण -संवेदनशील पर्यावरण कॉन्फ़िगरेशन को एजेंट द्वारा पढ़े जाने या exposed होने से सुरक्षित रखें। +एजेंटों द्वारा संवेदनशील पर्यावरण कॉन्फ़िगरेशन को पढ़ने या उजागर किए जाने से रक्षा करता है। ### `block-env-files` -**इवेंट:** PreToolUse (Bash, Read) -**डिफ़ॉल्ट:** `.env` फ़ाइलें पढ़ने से इनकार करता है जैसे `cat .env`, फ़ाइल पाथ के रूप में `.env` के साथ Read टूल कॉल, आदि। +**ईवेंट:** PreToolUse (Bash, Read) +**डिफ़ॉल्ट:** `.env` फ़ाइलों को `cat .env`, Read टूल कॉल (`.env` फ़ाइल पथ के रूप में), आदि के माध्यम से पढ़ने से अस्वीकार करता है। -`.envrc` या अन्य environment-संबंधी फ़ाइलों को ब्लॉक नहीं करता — केवल बिल्कुल `.env` नाम वाली फ़ाइलें। +`.envrc` या अन्य पर्यावरण-आसन्न फ़ाइलों को ब्लॉक नहीं करता — केवल `.env` नामित फ़ाइलों को। कोई पैरामीटर नहीं। @@ -431,8 +431,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `protect-env-vars` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** कमांड को नकारता है जो environment variables प्रिंट करते हैं: `printenv`, `env`, `echo $VAR`। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** ऐसी कमांड को अस्वीकार करता है जो पर्यावरण वेरिएबल को प्रिंट करती हैं: `printenv`, `env`, `echo $VAR`। कोई पैरामीटर नहीं। @@ -440,18 +440,18 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## फ़ाइल एक्सेस -एजेंट को प्रोजेक्ट सीमाओं के अंदर काम करने और संवेदनशील फ़ाइलों से दूर रखें। +एजेंटों को प्रोजेक्ट सीमाओं के भीतर काम करने के लिए रखता है और संवेदनशील फ़ाइलों से दूर। ### `block-read-outside-cwd` -**इवेंट:** PreToolUse (Read, Bash) -**डिफ़ॉल्ट:** प्रोजेक्ट रूट के बाहर फ़ाइलें पढ़ने से इनकार करता है। सीमा `CLAUDE_PROJECT_DIR` है (Claude Code द्वारा प्रति सेशन एक बार सेट), उस वेरिएबल अनसेट होने पर सेशन की वर्तमान कार्य निर्देशिका में fallback के साथ। live `cwd` के बजाय प्रोजेक्ट रूट का उपयोग करने का मतलब है कि सीमा स्थिर रहती है भले ही Claude किसी subdirectory में `cd` करे। +**ईवेंट:** PreToolUse (Read, Bash) +**डिफ़ॉल्ट:** प्रोजेक्ट रूट के बाहर फ़ाइलों को पढ़ने से अस्वीकार करता है। सीमा `CLAUDE_PROJECT_DIR` है (सत्र के अनुसार Claude Code द्वारा सेट), उस वेरिएबल अनसेट होने पर सत्र की वर्तमान कार्य निर्देशिका में फॉलबैक के साथ। लाइव `cwd` के बजाय प्रोजेक्ट रूट का उपयोग करने का अर्थ है कि सीमा स्थिर रहती है यहां तक कि Claude एक सबडायरेक्टरी में `cd` करने के बाद। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Absolute पाथ उपसर्ग जो अनुमत हैं भले ही प्रोजेक्ट रूट के बाहर हों। | +| `allowPaths` | `string[]` | `[]` | निरपेक्ष पथ उपसर्ग जो अनुमति दिए जाते हैं यहां तक कि प्रोजेक्ट रूट के बाहर भी। | **उदाहरण:** @@ -469,8 +469,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-secrets-write` -**इवेंट:** PreToolUse (Write, Edit) -**डिफ़ॉल्ट:** प्राइवेट कुंजी और certificates के लिए आमतौर पर उपयोग की जाने वाली फ़ाइलों में लिखने से इनकार करता है: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`। +**ईवेंट:** PreToolUse (Write, Edit) +**डिफ़ॉल्ट:** फ़ाइलों में लिखने से अस्वीकार करता है जो आमतौर पर निजी कुंजी और प्रमाण पत्र के लिए उपयोग किए जाते हैं: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`। **पैरामीटर:** @@ -494,18 +494,18 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## Git -आकस्मिक pushes, force-pushes, और ब्रांच गलतियों से बचें जो पूर्ववत करने में कठिन हों। +आकस्मिक पुश, force-push, और ब्रांच गलतियों को रोकता है जो उलटाना मुश्किल है। ### `block-push-master` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `git push origin main` और `git push origin master` को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git push origin main` और `git push origin master` को अस्वीकार करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | ब्रांच नाम जो सीधे push नहीं किए जा सकते। | +| `protectedBranches` | `string[]` | `["main", "master"]` | ब्रांच के नाम जिन्हें सीधे पुश नहीं किया जा सकता। | **उदाहरण:** @@ -520,36 +520,36 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ``` -सभी ब्रांच को push करने की अनुमति देने के लिए (इसे `enabledPolicies` से हटाए बिना प्रभावी रूप से अक्षम करने के लिए), `protectedBranches: []` सेट करें। +सभी ब्रांचों में पुश करने की अनुमति देने के लिए (प्रभावी रूप से इस नीति को अक्षम करने के लिए `enabledPolicies` से हटाए बिना), `protectedBranches: []` सेट करें। --- ### `block-work-on-main` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `git commit`, `git merge`, `git rebase`, और `git cherry-pick` को तब नकारता है जब कार्य ट्री `main` या `master` पर हो। ब्रांच creation और switching (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) प्रभावित नहीं हैं। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git commit`, `git merge`, `git rebase`, और `git cherry-pick` को अस्वीकार करता है जबकि कार्यिंग ट्री `main` या `master` पर है। ब्रांच निर्माण और स्विचिंग (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) प्रभावित नहीं होते हैं। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | ब्रांच नाम जिन पर commit/merge/rebase/cherry-pick से इनकार किया जाता है। | +| `protectedBranches` | `string[]` | `["main", "master"]` | ब्रांच के नाम जिन पर commit/merge/rebase/cherry-pick अस्वीकार किया जाता है। | --- ### `block-force-push` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `git push --force` और `git push -f` को नकारता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git push --force` और `git push -f` को अस्वीकार करता है। -कोई policy-विशिष्ट पैरामीटर नहीं। विकल्प सुझाने के लिए cross-cutting [`hint`](/hi/configuration#hint-cross-cutting) का उपयोग करें: +कोई नीति-विशिष्ट पैरामीटर नहीं। विकल्प सुझाने के लिए क्रॉस-कटिंग [`hint`](/hi/configuration#hint-cross-cutting) का उपयोग करें: ```json { "policyParams": { "block-force-push": { - "hint": "अपने वर्तमान HEAD से एक नई ब्रांच बनाएँ (उदा. `git checkout -b `) और इसके बजाय उसे push करें।" + "hint": "अपने वर्तमान HEAD से एक नई ब्रांच बनाएं (उदाहरण के लिए `git checkout -b `) और इसके बजाय पुश करें।" } } } @@ -559,8 +559,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-git-amend` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `git commit --amend` चलाते समय Claude को सावधानीपूर्वक आगे बढ़ने का निर्देश देता है। कमांड को ब्लॉक नहीं करता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `git commit --amend` चलाते समय सावधानी से आगे बढ़ने का निर्देश देता है। कमांड को ब्लॉक नहीं करता। कोई पैरामीटर नहीं। @@ -568,7 +568,7 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-git-stash-drop` -**इवेंट:** PreToolUse (Bash) +**ईवेंट:** PreToolUse (Bash) **डिफ़ॉल्ट:** Claude को `git stash drop` चलाने से पहले पुष्टि करने का निर्देश देता है। कमांड को ब्लॉक नहीं करता। कोई पैरामीटर नहीं। @@ -577,8 +577,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-all-files-staged` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को समीक्षा करने का निर्देश देता है कि जब यह `git add -A` या `git add .` चलाता है तो क्या stage कर रहा है। कमांड को ब्लॉक नहीं करता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `git add -A` या `git add .` चलाते समय समीक्षा करने का निर्देश देता है कि वह क्या स्टेज कर रहा है। कमांड को ब्लॉक नहीं करता। कोई पैरामीटर नहीं। @@ -586,12 +586,12 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## डेटाबेस -destructive SQL operations को database के विरुद्ध निष्पादित होने से पहले पकड़ें। +विनाशकारी SQL संचालन को आपके डेटाबेस के विरुद्ध निष्पादन से पहले पकड़ता है। ### `warn-destructive-sql` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `DROP TABLE`, `DROP DATABASE`, या `WHERE` खंड के बिना `DELETE` युक्त SQL चलाने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `DROP TABLE`, `DROP DATABASE`, या `WHERE` क्लॉज के बिना `DELETE` वाले SQL चलाने से पहले पुष्टि करने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -599,27 +599,27 @@ destructive SQL operations को database के विरुद्ध नि ### `warn-schema-alteration` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `ALTER TABLE` statements चलाने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `ALTER TABLE` कथन चलाने से पहले पुष्टि करने का निर्देश देता है। कोई पैरामीटर नहीं। --- -## चेतावनियाँ +## चेतावनियां -एजेंट को संभावित रूप से जोखिम भरे लेकिन non-destructive operations से पहले अतिरिक्त संदर्भ दें। +एजेंटों को संभावित रूप से जोखिम भरे लेकिन गैर-विनाशकारी संचालन से पहले अतिरिक्त संदर्भ देता है। ### `warn-large-file-write` -**इवेंट:** PreToolUse (Write) -**डिफ़ॉल्ट:** Claude को 1024 KB से बड़ी फ़ाइलें लिखने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Write) +**डिफ़ॉल्ट:** Claude को 1024 KB से बड़ी फ़ाइलों को लिखने से पहले पुष्टि करने का निर्देश देता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | फ़ाइल आकार threshold (kilobytes में) जिससे ऊपर चेतावनी दी जाती है। | +| `thresholdKb` | `number` | `1024` | फ़ाइल आकार सीमा किलोबाइट में जिसके ऊपर एक चेतावनी जारी की जाती है। | **उदाहरण:** @@ -634,14 +634,14 @@ destructive SQL operations को database के विरुद्ध नि ``` -हुक हैंडलर payloads पर 1 MB stdin limit लागू करता है। इस पॉलिसी को छोटी सामग्री के साथ परीक्षण करने के लिए, `thresholdKb` को 1024 से बहुत कम value पर सेट करें। +हुक हैंडलर पेलोड पर 1 MB stdin सीमा को लागू करता है। छोटी सामग्री के साथ इस नीति का परीक्षण करने के लिए, `thresholdKb` को 1024 से बहुत नीचे एक मान पर सेट करें। --- ### `warn-package-publish` -**इवेंट:** PreToolUse (Bash) +**ईवेंट:** PreToolUse (Bash) **डिफ़ॉल्ट:** Claude को `npm publish` चलाने से पहले पुष्टि करने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -650,8 +650,8 @@ destructive SQL operations को database के विरुद्ध नि ### `warn-background-process` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `nohup`, `&`, `disown`, या `screen` के माध्यम से background processes लॉन्च करते समय सावधान रहने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `nohup`, `&`, `disown`, या `screen` के माध्यम से पृष्ठभूमि प्रक्रियाएं लॉन्च करते समय सावधान रहने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -659,8 +659,8 @@ destructive SQL operations को database के विरुद्ध नि ### `warn-global-package-install` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `npm install -g`, `yarn global add`, या virtual environment के बिना `pip install` चलाने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `npm install -g`, `yarn global add`, या वर्चुअल पर्यावरण के बिना `pip install` चलाने से पहले पुष्टि करने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -668,21 +668,21 @@ destructive SQL operations को database के विरुद्ध नि ## पैकेज मैनेजर -एजेंट को किस पैकेज मैनेजर का उपयोग करने की अनुमति है यह लागू करें। +यह लागू करता है कि एजेंट किन पैकेज मैनेजर का उपयोग करने की अनुमति है। ### `prefer-package-manager` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** अक्षम। सक्षम होने पर, किसी भी पैकेज मैनेजर कमांड को ब्लॉक करता है जो `allowed` सूची में नहीं है और Claude को अनुमत मैनेजर का उपयोग करके कमांड को फिर से लिखने के लिए कहता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** अक्षम। जब सक्षम हो, तो `allowed` सूची में न होने वाली किसी भी पैकेज मैनेजर कमांड को ब्लॉक करता है और Claude को अनुमत मैनेजर का उपयोग करके कमांड को फिर से लिखने के लिए कहता है। -पाता है: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo। +पहचान: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo। | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | अनुमत पैकेज मैनेजर नाम। इस सूची में नहीं कोई भी पाया गया मैनेजर ब्लॉक किया जाता है। जब खाली हो, पॉलिसी कोई संचालन नहीं करती। | -| `blocked` | string[] | `[]` | built-in सूची से परे ब्लॉक करने के लिए अतिरिक्त मैनेजर नाम (उदा. `['pdm', 'pipx']`)। | +| `allowed` | string[] | `[]` | अनुमत पैकेज मैनेजर के नाम। इस सूची में नहीं होने वाला कोई भी पहचाना गया मैनेजर ब्लॉक किया जाता है। जब खाली हो, तो नीति एक no-op है। | +| `blocked` | string[] | `[]` | अंतर्निर्मित सूची से परे ब्लॉक करने के लिए अतिरिक्त मैनेजर नाम (उदाहरण के लिए, `['pdm', 'pipx']`)। | -Built-in ब्लॉक सूची कवर करती है: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo। इस सूची में न पाए जाने वाले मैनेजर जोड़ने के लिए `blocked` का उपयोग करें। +अंतर्निर्मित ब्लॉक सूची शामिल है: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo। इस सूची में नहीं होने वाले मैनेजर को जोड़ने के लिए `blocked` का उपयोग करें। **उदाहरण कॉन्फ़िगरेशन:** @@ -698,18 +698,18 @@ Built-in ब्लॉक सूची कवर करती है: pip, pip3, } ``` -इस कॉन्फ़िग के साथ, `pip install flask` और `pdm install flask` दोनों नकार दिए जाते हैं Claude को बताते हुए कि `uv` या `bun` का उपयोग करें। `uv pip install flask` जैसी कमांड अनुमत हैं क्योंकि `uv` allowlist में है और पहले जाँचा जाता है। +इस कॉन्फ़िग के साथ, `pip install flask` और `pdm install flask` दोनों को Claude को `uv` या `bun` का उपयोग करने के लिए कहने वाले संदेश के साथ अस्वीकार किया जाता है। `uv pip install flask` जैसी कमांड की अनुमति है क्योंकि `uv` allowlist में है और पहले जांच की जाती है। --- ## AI व्यवहार -एजेंट को stuck होने या अप्रत्याशित व्यवहार करने के समय पहचानें। +जब एजेंट फंसते हैं या अप्रत्याशित तरीके से व्यवहार करते हैं तो पहचान करता है। ### `warn-repeated-tool-calls` -**इवेंट:** PreToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** Claude को reconsider करने का निर्देश देता है जब एक ही टूल समान parameters के साथ 3+ बार कॉल किया जाता है — एक सामान्य संकेत कि एजेंट loop में फँसा है। +**ईवेंट:** PreToolUse (सभी टूल) +**डिफ़ॉल्ट:** Claude को तब फिर से विचार करने का निर्देश देता है जब समान टूल समान पैरामीटर के साथ 3+ बार कॉल किया जाता है — एक सामान्य संकेत कि एजेंट एक लूप में फंसा हुआ है। कोई पैरामीटर नहीं। @@ -717,39 +717,39 @@ Built-in ब्लॉक सूची कवर करती है: pip, pip3, ## वर्कफ़्लो -एक अनुशासित end-of-session वर्कफ़्लो लागू करें। ये पॉलिसीज़ **Stop** इवेंट पर काम करती हैं और एजेंट को रोकते हैं जब तक प्रत्येक शर्त पूरी न हो। वे एक प्राकृतिक dependency chain का पालन करते हैं: commit → push → PR → CI। यदि कोई पॉलिसी नकार करती है, chain में बाद की पॉलिसीज़ छोड़ दी जाती हैं (deny short-circuits)। +एक अनुशासित सत्र-अंत वर्कफ़्लो को लागू करता है। ये नीतियां **Stop** ईवेंट पर चलती हैं और एजेंट को बंद होने से रोकती हैं जब तक कि प्रत्येक शर्त पूरी न हो। वे एक प्राकृतिक निर्भरता श्रृंखला का पालन करते हैं: commit → push → PR → CI। यदि एक नीति अस्वीकार करती है, तो बाद की नीतियां श्रृंखला में छोड़ दी जाती हैं (अस्वीकार short-circuit)। -सभी वर्कफ़्लो पॉलिसीज़ **fail-open** हैं: यदि आवश्यक टूल उपलब्ध नहीं है (उदा. `gh` installed नहीं, कोई git remote नहीं), पॉलिसी informational संदेश के साथ allow करती है यह समझाते हुए कि check को skip क्यों किया गया। +सभी वर्कफ़्लो नीतियां **fail-open** हैं: यदि आवश्यक टूल उपलब्ध नहीं है (`gh` इंस्टॉल नहीं है, कोई git remote नहीं), तो नीति जानकारीपूर्ण संदेश के साथ अनुमति देती है जो बताता है कि जांच को क्यों छोड़ा गया था। -### Per-CLI Stop semantics +### प्रति-CLI Stop शब्दार्थ -Stop enforcement छह समर्थित CLIs में अलग-अलग दिखता है क्योंकि प्रत्येक एक अलग "agent finished" hook contract expose करता है। **outcome** समान है — एजेंट workflow gate fail होने पर stop नहीं हो सकता — लेकिन **mechanics** अलग हैं। नीचे की तालिका सारांशित करती है; केवल Pi के पास एक उपयोगकर्ता-दृश्यमान quirk है `require-*-before-stop` पॉलिसी सक्षम करने से पहले समझने योग्य। +Stop प्रवर्तन छह समर्थित CLI में थोड़ा अलग तरीके से दिखता है क्योंकि प्रत्येक एक अलग "एजेंट समाप्त" हुक अनुबंध प्रदान करता है। **परिणाम** समान है — एजेंट एक विफल वर्कफ़्लो गेट के साथ बंद होने से दूर नहीं हो जाते — लेकिन **यांत्रिकी** भिन्न होते हैं। नीचे की तालिका सारांश देती है; केवल Pi में एक उपयोगकर्ता-दृश्यमान विशिष्टता है जिसे आप `require-*-before-stop` नीति को सक्षम करने से पहले समझना चाहते हैं। -| CLI | Gate कब fires करता है | आप क्या देखते हैं | +| CLI | गेट कब चलता है | आप क्या देखते हैं | |---|---|---| -| Claude Code | समान एजेंट loop, तुरंत | Claude काम करना जारी रखता है — समस्या को ठीक करता है, फिर फिर से समाप्त करने का प्रयास करता है। आपको कोई interruption दिखाई नहीं देता। | -| Codex | समान एजेंट loop, तुरंत | Claude की तरह ही। | -| GitHub Copilot CLI | समान एजेंट loop, तुरंत | Claude की तरह ही (Copilot के `{decision:"block", reason}` retry channel का उपयोग करता है — Copilot CLI 1.0.41 के विरुद्ध empirically verified)। | -| Cursor Agent | समान एजेंट loop, तुरंत | Claude की तरह ही (Cursor के `{followup_message}` channel का उपयोग करता है — `loop_limit` पर capped, default 5 retries)। | -| OpenCode | समान एजेंट loop, तुरंत | Claude की तरह ही (OpenCode के `client.session.prompt(...)` SDK कॉल का उपयोग करता है `hookSpecificOutput.additionalContext` के माध्यम से routed)। | -| **Pi (pi-coding-agent)** | **अगली user turn** | **Pi visibly stops** जब gate fires — इसके एजेंट loop exit करते हैं और आप prompt पर लौटते हैं। Gate फिर अगली बार काम करता है जब आप एक prompt submit करते हैं: failproofai इस turn के system prompt में `MANDATORY ACTION REQUIRED` निर्देश prepend करता है, LLM को निर्देश देता है कि workflow step (commit, push, आदि) को complete करें इससे पहले कि आप जो कुछ भी पूछें। | +| Claude Code | समान एजेंट लूप, तुरंत | Claude काम करना जारी रखता है — समस्या को ठीक करता है, फिर समाप्त करने का प्रयास करता है। आपके लिए कोई दृश्यमान रुकावट नहीं। | +| Codex | समान एजेंट लूप, तुरंत | Claude जैसा ही। | +| GitHub Copilot CLI | समान एजेंट लूप, तुरंत | Claude जैसा ही (Copilot की `{decision:"block", reason}` retry चैनल का उपयोग — Copilot CLI 1.0.41 के विरुद्ध प्रायोगिक रूप से सत्यापित)। | +| Cursor Agent | समान एजेंट लूप, तुरंत | Claude जैसा ही (Cursor की `{followup_message}` चैनल का उपयोग — `loop_limit` पर सीमित, डिफ़ॉल्ट 5 retry)। | +| OpenCode | समान एजेंट लूप, तुरंत | Claude जैसा ही (OpenCode की `client.session.prompt(...)` SDK कॉल का उपयोग `hookSpecificOutput.additionalContext` के माध्यम से रूट किया गया)। | +| **Pi (pi-coding-agent)** | **अगला उपयोगकर्ता मोड़** | **Pi दृश्यमान रूप से बंद होता है** जब गेट चलता है — इसका एजेंट लूप बाहर निकलता है और आप प्रॉम्प्ट पर वापस आ जाते हैं। गेट फिर अगली बार चलता है जब आप एक प्रॉम्प्ट सबमिट करते हैं: failproofai उस मोड़ के सिस्टम प्रॉम्प्ट में एक `MANDATORY ACTION REQUIRED` निर्देश प्रीपेंड करता है, LLM को वर्कफ़्लो चरण (कमिट, पुश, आदि) को पूरा करने का निर्देश देते हुए जो आपने पूछा। | -**Pi limitation.** Pi की `AgentEndEvent` (Claude के `Stop` हुक के upstream equivalent) का कोई Result प्रकार नहीं है — जब तक यह fires होता है, Pi का एजेंट loop पहले से ही exit हो गया है। Pi को Claude / Copilot / Cursor / OpenCode की तरह एक ही loop को retry करने के लिए बाध्य नहीं किया जा सकता। failproofai gate को Pi के `before_agent_start` इवेंट (जो अगली user prompt के बाद fires होता है) में shift करता है ताकि workflow check अभी भी लागू हो, बस वर्तमान की बजाय अगली turn पर। +**Pi सीमा।** Pi का `AgentEndEvent` (Claude के `Stop` हुक के बराबर) का कोई Result प्रकार नहीं है — जब तक यह चलता है, Pi का एजेंट लूप पहले से बाहर हो गया है। Pi को उसी तरह retry करने के लिए मजबूर नहीं किया जा सकता जैसे Claude / Copilot / Cursor / OpenCode कर सकते हैं। failproofai गेट को Pi के `before_agent_start` ईवेंट पर स्थानांतरित करता है (जो अगले उपयोगकर्ता प्रॉम्प्ट के बाद चलता है) ताकि वर्कफ़्लो जांच अभी भी लागू हो, बस वर्तमान के बजाय अगले मोड़ पर। -**इसका व्यावहारिक अर्थ क्या है:** +**व्यावहारिक रूप से इसका क्या अर्थ है:** -- Pi stop करने के बाद, deny reason को Pi session id द्वारा keyed in-memory में capture किया जाता है। आप same Pi process में जो भी अगला prompt submit करते हैं वह इसे drain करता है: LLM अपने system prompt के top पर `MANDATORY ACTION REQUIRED` निर्देश देखता है, commit करता है (या push / PR खोलता / CI के लिए waits करता है), और केवल तब आपके request के साथ continue करता है। Captured deny reason one-shot है — एक बार drain होने के बाद, gate स्पष्ट है। -- Gate Pi के process lifetime से bounded है। यदि आप turns के बीच Pi को `Ctrl+C` करते हैं या quit करते हैं, in-memory entry process के साथ dropped होती है और gate missed हो जाता है। Claude, Copilot, Cursor, और OpenCode का same bound है (agent को kill करो और gate miss हो जाता है) — Pi बस इसे अधिक दृश्यमान बनाता है क्योंकि agent visibly exit करता है gate के पहले। -- एक pending deny भी clear हो जाती है `session_shutdown` पर किसी भी कारण से (`new` / `resume` / `fork` / `quit`), तो prior session से एक stale gate same Pi process में शुरू की गई fresh session में leak नहीं कर सकता। +- Pi बंद होने के बाद, अस्वीकार कारण को Pi सत्र id द्वारा कुंजीयुक्त मेमोरी में कैप्चर किया जाता है। आप समान Pi प्रक्रिया में जो अगला प्रॉम्प्ट सबमिट करते हैं वह इसे ड्रेन करता है: LLM अपने सिस्टम प्रॉम्प्ट के शीर्ष पर `MANDATORY ACTION REQUIRED` निर्देश देखता है, कमिट (या पुश / PR खोलता है / CI प्रतीक्षा करता है), और केवल तब आपके अनुरोध के साथ जारी रखता है। कैप्चर किए गए अस्वीकार कारण एक-बार — एक बार ड्रेन किए जाने के बाद, गेट स्पष्ट है। +- गेट Pi की प्रक्रिया आजीवन से बंधा है। यदि आप Pi के बीच `Ctrl+C` करते हैं या बंद करते हैं, तो मेमोरी प्रविष्टि प्रक्रिया के साथ हटा दी जाती है और गेट मिस हो जाता है। Claude, Copilot, Cursor, और OpenCode की एक ही सीमा है (एजेंट को मारो और गेट मिस हो जाता है) — Pi इसे केवल अधिक दृश्यमान बनाता है क्योंकि एजेंट गेट चलने से पहले दृश्यमान रूप से बाहर निकलता है। +- एक लंबित अस्वीकार किसी भी कारण से `session_shutdown` पर भी साफ किया जाता है (`new` / `resume` / `fork` / `quit`), इसलिए एक पूर्व सत्र से एक बासी गेट समान Pi प्रक्रिया में शुरू किए गए एक ताजा सत्र में लीक नहीं हो सकता है। -यदि आपको Claude-शैली same-loop retry की आवश्यकता है, अन्य पाँच समर्थित CLIs में से किसी के तहत अपनी `Stop` पॉलिसीज़ चलाएँ। हम Pi को track कर रहे हैं upstream के लिए एक future Result प्रकार `AgentEndEvent` पर जो हमें इस gap को बंद करने देगा। +यदि आपको Claude-शैली same-loop retry चाहिए, तो अन्य पांच समर्थित CLI में से किसी के तहत अपनी `Stop` नीतियां चलाएं। हम `AgentEndEvent` पर एक भविष्य Result प्रकार के लिए Pi upstream को ट्रैक कर रहे हैं जो हमें इस अंतर को बंद करने दे सके। ### `require-commit-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** uncommitted changes (modified, staged, या untracked फ़ाइलें) होने पर stop को नकारता है। कार्य निर्देशिका clean होने पर informational संदेश लौटाता है। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** बंद करने से अस्वीकार करता है जब uncommitted परिवर्तन हों (संशोधित, staged, या untracked फ़ाइलें)। कार्यिंग निर्देशिका स्वच्छ होने पर एक जानकारीपूर्ण संदेश लौटाता है। कोई पैरामीटर नहीं। @@ -757,14 +757,14 @@ Stop enforcement छह समर्थित CLIs में अलग-अलग ### `require-push-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** unpushed commits होने पर या जब वर्तमान ब्रांच के पास कोई remote tracking branch न हो तो stop को नकारता है। यदि आवश्यक हो तो `git push -u` का उपयोग करके एक tracking branch बनाने का सुझाव देता है। यदि कोई remote configured न हो तो fail open होता है। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** बंद करने से अस्वीकार करता है जब unpushed commits हों या जब वर्तमान ब्रांच के पास कोई remote tracking branch नहीं हो। यदि आवश्यक हो तो tracking branch बनाने के लिए `git push -u` का सुझाव देता है। यदि कोई remote कॉन्फ़िगर नहीं है तो fail open करता है। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Push करने के लिए remote नाम। | +| `remote` | `string` | `"origin"` | Remote नाम पुश करने के लिए। | **उदाहरण:** @@ -782,59 +782,59 @@ Stop enforcement छह समर्थित CLIs में अलग-अलग ### `require-pr-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** जब वर्तमान ब्रांच के लिए कोई pull request मौजूद न हो, या जब existing PR को merge किए बिना बंद किया जाए तो stop को नकारता है। Claude को `gh pr create` के साथ एक PR बनाने का निर्देश देता है। जब PR **merged** हो, पॉलिसी allow करती है (काम ship हो गया) और संदेश ब्रांच को switch off करने का संकेत देता है (`git checkout main && git pull`)। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** बंद करने से अस्वीकार करता है जब वर्तमान ब्रांच के लिए कोई pull request मौजूद न हो, या जब मौजूदा PR merge किए बिना बंद हो। Claude को `gh pr create` के साथ एक PR बनाने का निर्देश देता है। जब PR **merge** होता है, तो नीति अनुमति देती है (काम ship हो गया) और संदेश branch को स्विच करने का संकेत देता है (`git checkout main && git pull`)। कोई पैरामीटर नहीं। -इस पॉलिसी के लिए [GitHub CLI](https://cli.github.com/) (`gh`) को install और authenticate किया जाना आवश्यक है। -`gh auth login` को एक personal access token के साथ चलाएँ जिसमें pull requests के read access के लिए `repo` scope हो। यदि `gh` install नहीं है या authenticate नहीं है, पॉलिसी fail open होती है और reason को Claude को report करती है। +इस नीति को [GitHub CLI](https://cli.github.com/) (`gh`) को इंस्टॉल और प्रमाणित करने की आवश्यकता है। +`gh auth login` को एक personal access token के साथ चलाएं जिसमें pull requests को read एक्सेस करने के लिए `repo` scope हो। यदि `gh` इंस्टॉल या प्रमाणित नहीं है, तो नीति fail open करती है और कारण Claude को रिपोर्ट करती है। --- ### `require-no-conflicts-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** जब वर्तमान ब्रांच base branch में cleanly merge नहीं हो सकता तो stop को नकारता है। पॉलिसी पहले confirm करती है कि ब्रांच के लिए GitHub पर एक `OPEN` PR मौजूद है — बिना उसके, कोई merge target नहीं है enforce करने के लिए, तो पूरी पॉलिसी short-circuit करके allow करती है। एक बार `OPEN` PR confirm होने के बाद, दो independent probes चलते हैं: +**ईवेंट:** Stop +**डिफ़ॉल्ट:** बंद करने से अस्वीकार करता है जब वर्तमान ब्रांच base branch में स्वच्छ रूप से merge नहीं हो सकता। नीति पहले पुष्टि करती है कि ब्रांच के लिए GitHub पर एक `OPEN` PR मौजूद है — बिना एक के, कोई merge target नहीं है enforce करने के लिए, इसलिए पूरी नीति short-circuit करती है। एक `OPEN` PR की पुष्टि के बाद, दो स्वतंत्र probes चलते हैं: -1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`। Conflict पर, deny संदेश conflicted फ़ाइलों को नाम देता है ताकि Claude को ठीक करने के लिए क्या है यह पता हो। -2. **GitHub** — `gh pr view --json mergeable,state` result को reuse करता है जो पहले से precheck में fetch किया गया है। Conflicts को पकड़ता है जो एक stale local `origin/` miss करेगा (उदा. कोई conflicting PR को land किया `main` पर last fetch के बाद)। `CONFLICTING` result नकार करता है। `UNKNOWN` result भी नकार करता है और Claude को ~10 सेकंड wait करने और stop से पहले re-check करने का निर्देश देता है — यह false negatives को रोकता है जबकि GitHub recompute करता है। +1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`। Conflict पर, अस्वीकार संदेश conflicted फ़ाइलों को नाम देता है ताकि Claude जानता हो कि क्या resolve करना है। +2. **GitHub** — `gh pr view --json mergeable,state` परिणाम का पुनः उपयोग करता है पहले से ही precheck में fetch किया गया। एक stale local `origin/` को मिस करने वाले conflicts को पकड़ता है (उदाहरण के लिए कोई `main` पर एक conflicting PR landed है जब से अंतिम fetch)। एक `CONFLICTING` परिणाम अस्वीकार करता है। एक `UNKNOWN` परिणाम भी अस्वीकार करता है और Claude को फिर से जांचने से पहले ~10 सेकंड प्रतीक्षा करने का निर्देश देता है — यह false negatives को रोकता है जबकि GitHub पुनः गणना करता है। -Skip करता है entirely (allow करता है) जब: `gh` install नहीं है, ब्रांच के लिए कोई PR मौजूद नहीं है, PR की state `OPEN` नहीं है (उदा. `MERGED`, `CLOSED`), या `gh pr view` unparseable आउटपुट लौटाता है। भी fail open होता है जब `origin/` locally missing है या जब कोई commits base से आगे नहीं हैं — वो Layer 1 fall-throughs अभी भी allow करने से पहले cached PR mergeability को consult करते हैं। +पूरी तरह छोड़ता है (अनुमति देता है) जब: `gh` इंस्टॉल नहीं है, कोई PR नहीं है ब्रांच के लिए, PR की state `OPEN` नहीं है (`MERGED`, `CLOSED`), या `gh pr view` unparseable आउटपुट लौटाता है। जब `origin/` locally गायब है या कोई commits base से आगे नहीं हैं तो भी fail open करता है — वे Layer 1 fall-through अभी भी allow करने से पहले कैश किए गए PR mergeability को consult करते हैं। **पैरामीटर:** | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Conflicts के लिए check करने के लिए base branch। | +| `baseBranch` | `string` | `"main"` | Conflicts के लिए जांचने के लिए base branch। | -इस पॉलिसी के लिए GitHub CLI (`gh`) required है। पॉलिसी किसी भी conflict probe चलाने से पहले confirm करने के लिए `gh pr view` का उपयोग करती है कि एक `OPEN` PR मौजूद है — बिना `gh` के, पॉलिसी short-circuit करके allow करती है। `gh auth login` को एक personal access token के साथ चलाएँ जिसमें pull requests के read access के लिए `repo` scope हो। +इस नीति के लिए GitHub CLI (`gh`) आवश्यक है। नीति कोई भी conflict probe चलाने से पहले एक `OPEN` PR की पुष्टि के लिए `gh pr view` का उपयोग करता है — `gh` के बिना, नीति short-circuit करती है। `gh auth login` को एक personal access token के साथ चलाएं जिसमें pull requests को read एक्सेस करने के लिए `repo` scope हो। --- ### `require-ci-green-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** जब वर्तमान ब्रांच पर CI checks fail या run कर रहे हों तो stop को नकारता है। GitHub Actions workflow runs और third-party bot checks दोनों को check करता है (उदा. CodeRabbit, SonarCloud, Codecov)। `skipped`, `cancelled`, और `neutral` conclusions को non-failing के रूप में मानता है (latter cover करता है उदा. Socket Security alerts on outside contributor PRs, जहाँ app intentionally neutral rather than success/failure को report करता है)। सभी checks pass होने पर informational संदेश लौटाता है। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** बंद करने से अस्वीकार करता है जब CI checks वर्तमान ब्रांच पर विफल या चल रहे हों। GitHub Actions workflow runs और third-party bot checks दोनों (उदाहरण के लिए CodeRabbit, SonarCloud, Codecov) को जांचता है। `skipped`, `cancelled`, और `neutral` conclusions को non-failing मानता है (बाद वाला उदाहरण के लिए Socket Security alerts को बाहर के contributor PRs पर कवर करता है, जहां ऐप intentionally success/failure के बजाय neutral रिपोर्ट करता है)। सभी checks pass होने पर एक जानकारीपूर्ण संदेश लौटाता है। कोई पैरामीटर नहीं। -इस पॉलिसी के लिए [GitHub CLI](https://cli.github.com/) (`gh`) को install और authenticate किया जाना आवश्यक है। -`gh auth login` को एक personal access token के साथ चलाएँ जिसमें Actions workflow runs और Checks API के read access के लिए `repo` scope हो। यदि `gh` install नहीं है या authenticate नहीं है, पॉलिसी fail open होती है और reason को report करती है। +इस नीति को [GitHub CLI](https://cli.github.com/) (`gh`) को इंस्टॉल और प्रमाणित करने की आवश्यकता है। +`gh auth login` को एक personal access token के साथ चलाएं जिसमें Actions workflow runs और Checks API को read एक्सेस करने के लिए `repo` scope हो। यदि `gh` इंस्टॉल या प्रमाणित नहीं है, तो नीति fail open करती है और कारण Claude को रिपोर्ट करती है। --- --- -## व्यक्तिगत पॉलिसीज़ को अक्षम करना +## व्यक्तिगत नीतियों को अक्षम करना -अपने कॉन्फ़िग में `enabledPolicies` से एक विशिष्ट पॉलिसी को हटाएँ, या dashboard के Policies tab में इसे toggle off करें। +अपने कॉन्फ़िग में `enabledPolicies` से एक विशिष्ट नीति को हटाएं, या डैशबोर्ड के Policies tab में इसे बंद करें। ```json { @@ -845,4 +845,4 @@ Skip करता है entirely (allow करता है) जब: `gh` insta } ``` -`enabledPolicies` में सूचीबद्ध नहीं पॉलिसीज़ run नहीं होती, भले ही `policyParams` entries उनके लिए मौजूद हों। \ No newline at end of file +`enabledPolicies` में सूचीबद्ध नहीं होने वाली नीतियां नहीं चलती हैं, भले ही `policyParams` प्रविष्टियां उनके लिए मौजूद हों। \ No newline at end of file diff --git a/docs/hi/cli/audit.mdx b/docs/hi/cli/audit.mdx index 6700dfd9..f9b7c2f6 100644 --- a/docs/hi/cli/audit.mdx +++ b/docs/hi/cli/audit.mdx @@ -1,15 +1,14 @@ --- -title: पिछले सत्रों का ऑडिट (beta) -description: "जांचें कि एजेंट ने पिछले ट्रांसक्रिप्ट में कितनी बार व्यर्थ या जोखिम भरे काम किए" +title: अतीत के सेशन की जांच करें (beta) +description: "एजेंट ने अतीत के ट्रांसक्रिप्ट में कितनी बार बेकार या जोखिम भरे काम किए, इसकी गिनती करें" --- - **बीटा फीचर।** ऑडिट बीटा के रूप में जारी है जबकि हम शुरुआती प्रतिक्रिया एकत्र करते हैं। - डिटेक्टर कैटलॉग और रिपोर्ट प्रारूप अगले स्थिर संस्करण से पहले बदल सकते हैं। - यदि कुछ गलत लगे तो कृपया एक समस्या खोलें। + **Beta फीचर।** जांच बीटा के रूप में शिप होती है जबकि हम प्रारंभिक फीडबैक एकत्र करते हैं। + डिटेक्टर कैटलॉग और रिपोर्ट फॉर्मेट अगले स्थिर रिलीज से पहले बदल सकते हैं। यदि कुछ गलत दिखे तो कृपया एक समस्या खोलें। -ऑडिट आपके पिछले एजेंट-CLI ट्रांसक्रिप्ट को failproofai की policy इंजन के माध्यम से फिर से चलाता है और **`/audit` डैशबोर्ड पृष्ठ** पर एक साझाकरण योग्य, दृश्य रिपोर्ट प्रदान करता है — आपके एजेंट का आर्कीटाइप, 0–100 स्कोर, और वास्तव में कौन सी policies क्या पकड़ सकती हैं। +जांच आपके अतीत के एजेंट-CLI ट्रांसक्रिप्ट को failproofai की नीति इंजन के माध्यम से दोबारा चलाती है और **`/audit` डैशबोर्ड पेज** पर एक साझा करने योग्य, दृश्य रिपोर्ट प्रदान करती है — आपके एजेंट का आर्कटाइप, 0–100 स्कोर, और बिल्कुल किन नीतियों ने क्या पकड़ा होता। ## इसे चलाएं @@ -33,10 +32,10 @@ failproofai - `npx -y failproofai audit` failproofai को लाता है, स्कैन चलाता है, और डैशबोर्ड खोलता है — पहले कुछ इंस्टॉल करने की आवश्यकता नहीं। + `npx -y failproofai audit` failproofai को लाता है, स्कैन चलाता है, और आपके लिए डैशबोर्ड खोलता है — पहले कुछ भी इंस्टॉल करने की जरूरत नहीं है। - `failproofai audit` आपके टर्मिनल में स्कैन चलाता है, फिर यह समाप्त होने पर `localhost:8020/audit` स्वचालित रूप से खोलता है। + `failproofai audit` आपके टर्मिनल में स्कैन चलाता है, फिर यह समाप्त होने पर `localhost:8020/audit` को स्वचालित रूप से खोलता है। `failproofai` चलाएं और नेवबार में **Audit** पर क्लिक करें (Policies और Projects के बीच), या सीधे `/audit` खोलें। @@ -44,74 +43,84 @@ failproofai - उपयोग देखने के लिए `failproofai audit -h` (या `--help`) चलाएं। ऑडिट **पूरी तरह ऑफलाइन** चलता है — कोई खाता या नेटवर्क आवश्यक नहीं — और डैशबोर्ड तब तक सेवा प्रदान करता रहता है जब तक आप इसे `Ctrl+C` से बंद न करें। + उपयोग देखने के लिए `failproofai audit -h` (या `--help`) चलाएं। जांच **पूरी तरह से ऑफलाइन** चलती है — कोई खाता या नेटवर्क आवश्यक नहीं है — और डैशबोर्ड तब तक सेवा देता रहता है जब तक आप इसे `Ctrl+C` से बंद नहीं करते। -डैशबोर्ड इस मशीन पर पिछले एजेंट CLI ट्रांसक्रिप्ट को स्कैन करता है (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) और रिपोर्ट करता है कि एजेंट ने कितनी बार वे काम किए जो failproofai रोकने के लिए बनाया गया है — env-var चेक, force pushes, redundant `cd ` prefixes, sleep-polling loops, अभी-अभी edited files को फिर से पढ़ना, और अधिक। +डैशबोर्ड इस मशीन पर अतीत के एजेंट CLI ट्रांसक्रिप्ट को स्कैन करता है (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) और रिपोर्ट करता है कि एजेंट ने कितनी बार ऐसी चीजें कीं जिन्हें failproofai रोकने के लिए बनाया गया है — env-var जांच, जबरदस्ती पुश, अनावश्यक `cd ` उपसर्ग, स्लीप-पोलिंग लूप, अभी-अभी संपादित फ़ाइलें फिर से पढ़ना, और अन्य। -प्रत्येक ट्रांसक्रिप्ट के लिए, हर tool-use इवेंट को 39 builtin policies **और** 8 audit-only detectors के माध्यम से फिर से चलाया जाता है जो उन पैटर्न को पकड़ते हैं जो अभी तक runtime policies द्वारा कवर नहीं किए गए हैं। काउंट्स सभी सत्रों में प्रति policy / detector को एकत्रित किए जाते हैं। +प्रत्येक ट्रांसक्रिप्ट के लिए, प्रत्येक टूल-यूज इवेंट 39 अंतर्निहित नीतियों के माध्यम से **और** 8 जांच-केवल डिटेक्टर के माध्यम से दोबारा चलाया जाता है जो ऐसे पैटर्न को पकड़ते हैं जो अभी तक रनटाइम नीतियों द्वारा कवर नहीं किए गए हैं। गणना सभी सेशन में प्रति नीति / डिटेक्टर एकत्र की जाती है। ## आपको क्या मिलता है -`/audit` पृष्ठ एक single-screen, साझाकरण योग्य **पोस्टर** है जिसके बाद चार अनुभाग हैं: +`/audit` पृष्ठ एक एकल-स्क्रीन, साझा करने योग्य **पोस्टर** है जिसके बाद चार गुना नीचे के अनुभाग हैं: -1. **पोस्टर** — आपके एजेंट की पहचान एक नज़र में: इसका **आर्कीटाइप** (8 में से एक — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), इसके persona कीवर्ड, वह आर्कीटाइप कितना दुर्लभ है, और एक **0–100 स्कोर** एक tier band (`S` से `bottom tier`) के साथ। साझा करने के लिए बनाया गया — X या LinkedIn पर पोस्ट करें, या इसे PNG के रूप में डाउनलोड करें। -2. **`// strengths`** — स्कैन से आपका एजेंट पहले से ही क्या अच्छा करता है, real numbers के रूप में (उदाहरण के लिए clean-tool-call %, `0` push-to-main attempts), केवल वहां दिखाया गया जहां प्रासंगिक policy का रिकॉर्ड clean है। -3. **`// quirks`** — क्या पार निकल गया: failproofai द्वारा पकड़े गए व्यवहारों की एक ranked तालिका — *कब* यह आखिरी बार हुआ, *क्या पार निकल गया* (और builtin जो इसे ब्लॉक कर सकता था), इसकी *severity*, और यह कितनी बार *देखा गया* (`new` / `recurring` / `N× seen`)। -4. **`// how to improve`** — prescribed fix list: प्रति policy एक row एक copy-paste `failproofai policy add ` के साथ, साथ ही एक **install all** बटन जो हर सिफारिश को एक साथ सक्षम करता है और आपका **projected score** दिखाता है यदि आपने ऐसा किया। -5. **`// come back better`** — आदत बनाएं: एक re-audit email **reminder** सेट करें (`3d` / `7d` / `14d` / `30d`) या अभी फिर से ऑडिट करें, और **एक दोस्त को आमंत्रित करें** अपना खुद का ऑडिट चलाने के लिए (failproof.ai से भेजा गया, आपको Cc किया गया)। Reminders और invites के लिए sign-in की आवश्यकता है। +1. **पोस्टर** — आपके एजेंट की पहचान एक नज़र में: इसका **आर्कटाइप** (8 में से एक — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), इसके व्यक्तित्व कीवर्ड, वह आर्कटाइप कितना दुर्लभ है, और एक **0–100 स्कोर** एक टियर बैंड के साथ (`S` से `bottom tier` तक)। साझा करने के लिए बनाया गया — X या LinkedIn पर पोस्ट करें, या इसे PNG के रूप में डाउनलोड करें। +2. **`// strengths`** — आपका एजेंट पहले से क्या अच्छा करता है, स्कैन से वास्तविक संख्या के रूप में (उदाहरण के लिए clean-tool-call %, `0` push-to-main प्रयास), केवल वहां दिखाया जाता है जहां प्रासंगिक नीति का एक स्वच्छ रिकॉर्ड है। +3. **`// quirks`** — जो फिसल गया: failproofai के द्वारा पकड़े जाने वाले व्यवहारों की एक स्थिति तालिका — *यह कब हुआ*, *क्या फिसल गया* (और अंतर्निहित जो इसे अवरुद्ध करता), इसकी *गंभीरता*, और यह कितनी बार *देखा गया* (`new` / `recurring` / `N× seen`)। +4. **`// how to improve`** — निर्धारित फिक्स सूची: प्रति नीति एक पंक्ति कॉपी-पेस्ट `failproofai policy add ` के साथ, साथ ही एक **install all** बटन जो हर सिफारिश को एक बार में सक्षम करता है और आपका **projected score** दिखाता है यदि आप करते। +5. **`// come back better`** — आदत बनाएं: एक पुन: जांच ईमेल **reminder** सेट करें (`3d` / `7d` / `14d` / `30d`) या अभी फिर से जांच करें, और **एक मित्र को आमंत्रित करें** अपनी स्वयं की जांच चलाने के लिए (failproof.ai से भेजा गया, आपको Cc किया गया)। Reminders और invites को साइन-इन की आवश्यकता है। -## Scheduled audits +## निर्धारित जांचें यदि आप **failproofaid daemon** चलाते हैं (देखें [`failproofai config`](/hi/cli/install-policies)), -यह आपके लिए schedule पर ऑडिट को फिर से चला सकता है और background में `/audit` रिपोर्ट को refresh कर सकता है। यह **डिफ़ॉल्ट रूप से बंद** है, क्योंकि स्कैन इस मशीन पर हर एजेंट सत्र ट्रांसक्रिप्ट की *सामग्री* को पढ़ता है — जब तक आप इसके लिए न कहें, कोई भी timer पर स्कैन नहीं करता। - -इसे `~/.failproofai/config.toml` में चालू करें: - -```toml -[audit] -auto = true -interval_days = 7 +यह आपके लिए अनुसूची पर जांच को फिर से चला सकता है और `/audit` रिपोर्ट को +पृष्ठभूमि में ताज़ा कर सकता है। यह **डिफ़ॉल्ट रूप से बंद** है, क्योंकि स्कैन *सामग्री* को पढ़ता है +इस मशीन पर प्रत्येक एजेंट सेशन ट्रांसक्रिप्ट की — कोई भी स्कैन टाइमर पर नहीं होता +जब तक आप इसके लिए न कहें। + +इसे `~/.failproofai/config.json` में चालू करें — `audit` कुंजी जोड़ें जो कुछ और फ़ाइल पहले से रखती है: + +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` -| Key | अर्थ | +| कुंजी | अर्थ | |---|---| -| `auto` | `true` scheduled स्कैन को सक्षम करता है। कुछ भी और — अनुपस्थित, `false`, `"yes"` — बंद है। | -| `interval_days` | स्कैन के बीच दिन। 1–90 के लिए क्लैम्प किया गया; `0`, नकारात्मक या non-number `7` पर वापस आता है। | - -- शेड्यूल **wall-clock** है, इसलिए यह suspend और reboots को survive करता है: एक लैपटॉप जो अपने due समय के बाद सो रहा था **एक बार** wake पर चलता है, कभी backlog नहीं। -- प्रत्येक run एक अलग, low-priority (`nice 19`) प्रक्रिया है — कभी भी daemon के hook path नहीं, जो tool calls का जवाब देने के लिए free रहता है। -- एक स्कैन को छोड़ दिया जाता है यदि `failproofai audit` या डैशबोर्ड की re-run पहले से ही flight में है; यह failure के रूप में treat किए जाने के बजाय शीघ्र ही फिर से try किया जाता है। -- Progress को `~/.failproofai/state/audit-schedule.json` में लिखा जाता है (last run, next due)। Daemon उस फ़ाइल का मालिक है — `config.toml` में cadence बदलें। +| `auto` | `true` निर्धारित स्कैन को सक्षम करता है। कुछ भी अन्य — अनुपस्थित, `false`, `"yes"` — बंद है। | +| `interval_days` | स्कैन के बीच दिन। 1–90 तक सीमित; `0`, एक नकारात्मक या एक गैर-संख्या `7` पर वापस आ जाता है। | + +- शेड्यूल **wall-clock** है, इसलिए यह निलंबन और पुनः बूट से बचता है: एक लैपटॉप + जो अपने कारणीय समय से परे सो रहा था जागने पर **एक बार** चलाता है, कभी भी बैकलॉग नहीं। +- प्रत्येक रन एक अलग, कम-प्राथमिकता (`nice 19`) प्रक्रिया है — कभी भी daemon का + हुक पथ नहीं, जो टूल कॉल का जवाब देने के लिए स्वतंत्र रहता है। +- एक स्कैन छोड़ा जाता है यदि `failproofai audit` या डैशबोर्ड का पुन: रन पहले से ही + चल रहा है; इसे विफलता के रूप में माना जाने के बजाय शीघ्र ही फिर से प्रयास किया जाता है। +- प्रगति `~/.failproofai/state/audit-schedule.json` में लिखी जाती है (अंतिम रन, + अगला कारण)। Daemon इस फ़ाइल का मालिक है — `config.json` में गति बदलें। -यदि आपने इसे एक पुराने failproofai द्वारा सेट किए गए मशीन पर सक्षम किया है, तो -`failproofai config` एक बार चलाएं। Daemon की service definition को CLI को launch करने के लिए एक अतिरिक्त -entry की आवश्यकता है, और refresh उस command का हिस्सा है। +यदि आपने इसे एक पुराने failproofai द्वारा सेट अप की गई मशीन पर सक्षम किया है, तो +`failproofai config` एक बार चलाएं। Daemon की सेवा परिभाषा को CLI को लॉन्च करने से पहले एक अतिरिक्त +प्रविष्टि की आवश्यकता है, और ताज़ा करना इस कमांड का भाग है। -## Audit-only detectors +## जांच-केवल डिटेक्टर -ये "stupid behavior" पैटर्न का पता लगाते हैं जो (अभी तक) real time में लागू नहीं किए जाते हैं। ये केवल ऑडिट के दौरान चलते हैं और कभी भी live tool call को ब्लॉक नहीं करते। +ये "मूर्खतापूर्ण व्यवहार" पैटर्न का पता लगाते हैं जो (अभी तक) वास्तविक समय में लागू नहीं होते हैं। ये केवल जांच के दौरान चलते हैं और कभी भी लाइव टूल कॉल को अवरुद्ध नहीं करते। -| Detector | यह क्या गिनता है | +| डिटेक्टर | यह क्या गिनता है | |---|---| -| `redundant-cd-cwd` | Bash commands जो `cd && …` से शुरू होते हैं भले ही commands पहले से `cwd` में चलते हैं। | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` एक एकल source file पर — `Read` tool का use करें। | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` in-place edits — `Edit` tool का use करें। | -| `prefer-write-over-heredoc` | Heredoc / multi-line `echo > file` लिखते हुए files — `Write` tool का use करें। | -| `sleep-polling-loop` | लंबे `sleep N` (≥ 30s) या `while …; sleep …; done` polling loops। | -| `find-from-root` | `find /`, `find /home`, `find /usr`, आदि — instead `cwd` को scope करें। | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, hooks को छोड़ते हुए। | -| `reread-after-edit` | एक file का `Read` जो एक ही सत्र में अभी-अभी `Edit`/`Write` था। | +| `redundant-cd-cwd` | Bash कमांड `cd && …` से शुरू होते हुए भले ही कमांड पहले से ही `cwd` में चलते हैं। | +| `prefer-edit-over-read-cat` | एकल स्रोत फ़ाइल पर `cat`/`head`/`tail`/`less`/`more` — `Read` टूल का उपयोग करें। | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` में-जगह संपादन — `Edit` टूल का उपयोग करें। | +| `prefer-write-over-heredoc` | Heredoc / बहु-पंक्ति `echo > file` लिखते हुए फ़ाइलें — `Write` टूल का उपयोग करें। | +| `sleep-polling-loop` | लंबी `sleep N` (≥ 30s) या `while …; sleep …; done` पोलिंग लूप। | +| `find-from-root` | `find /`, `find /home`, `find /usr`, आदि। — `cwd` के लिए दायरा। | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, हुक को छोड़ रहा है। | +| `reread-after-edit` | एक फ़ाइल का `Read` जो अभी-अभी एक ही सेशन में `Edit`/`Write` था। | -## Caches +## कैश -- **Per-transcript cache** `~/.failproofai/cache/audit/.json` पर `(mtime, size, engineVersion, detectorVersion)` द्वारा keyed — स्वचालित रूप से अमान्य करता है जब ट्रांसक्रिप्ट या policy/detector कोड बदलता है। प्रत्येक entry एक `cachedAt` timestamp को **TTL metadata** के रूप में भी store करता है (cache key का हिस्सा नहीं); **7 दिनों** से पुरानी entries को read पर reject किया जाता है ताकि long-lived results विकसित होते detector intent को outlive न करें। -- **Whole-result cache** `~/.failproofai/audit-dashboard.json` पर (mode 0600)। डैशबोर्ड को re-run किए बिना navigation पर instantly render करने देता है। **7-day TTL** के बाद read पर भी reject किया जाता है — `/audit` फिर अपनी empty state में falls through और एक fresh run के लिए prompt करता है। रिपोर्ट के नीचे के पास `[ re-audit now ]` पर क्लिक करें refresh करने के लिए — re-audit `noCache: true` भेजता है, इसलिए यह per-transcript cache को bypass करता है और cached result return करने के बजाय हर transcript को फिर से scan करता है; run एक sticky top strip के माध्यम से progress को stream करता है और success पर result को place में swap करता है (कोई page reload नहीं; एक failed re-audit पिछली रिपोर्ट को रखता है)। +- **प्रति-ट्रांसक्रिप्ट कैश** `~/.failproofai/cache/audit/.json` पर `(mtime, size, engineVersion, detectorVersion)` द्वारा कुंजीकृत — स्वचालित रूप से अमान्य होता है जब ट्रांसक्रिप्ट या नीति/डिटेक्टर कोड बदल जाता है। प्रत्येक प्रविष्टि एक `cachedAt` टाइमस्टैम्प भी स्टोर करती है **TTL मेटाडेटा** के रूप में (कैश कुंजी का हिस्सा नहीं); **7 दिन** से पुरानी प्रविष्टियों को पढ़ने पर अस्वीकार किया जाता है ताकि लंबे समय तक चलने वाले परिणाम विकसित डिटेक्टर इरादे से अधिक समय तक न रहें। +- **संपूर्ण-परिणाम कैश** `~/.failproofai/audit-dashboard.json` पर (मोड 0600)। डैशबोर्ड को पुन: चलाए बिना नेविगेशन पर तुरंत प्रदान करने देता है। **7-दिन TTL** से परे पढ़ने पर भी अस्वीकार किया जाता है — `/audit` तब खाली स्थिति में गिरता है और एक ताज़ा रन का संकेत देता है। रिपोर्ट के नीचे के पास `[ re-audit now ]` पर क्लिक करें ताज़ा करने के लिए — re-audit `noCache: true` भेजता है, इसलिए यह प्रति-ट्रांसक्रिप्ट कैश को दरकिनार करता है और कैश किए गए परिणाम को वापस करने के बजाय प्रत्येक ट्रांसक्रिप्ट को फिर से स्कैन करता है; रन एक स्टिकी शीर्ष पट्टी के माध्यम से प्रगति स्ट्रीम करता है और सफलता पर परिणाम को जगह में बदल देता है (कोई पृष्ठ पुनः लोड नहीं; एक विफल पुन: जांच पिछली रिपोर्ट रखता है)। -## Notes +## नोट्स -- **कोई mutation नहीं।** ऑडिट read-only mode में replays करता है। `warn-repeated-tool-calls` को छोड़ा जाता है क्योंकि इसका per-session sidecar अन्यथा modified होगा। -- **Workflow policies छोड़े गए।** `require-*-before-stop` policies केवल `Stop` events पर और live git state के विरुद्ध `execSync` पर fire करती हैं — उनके पास कोई meaningful "what would have happened in 2025" interpretation नहीं है, इसलिए वे audit counts में दिखाई नहीं देते। -- **Custom policies छोड़े गए।** User-supplied custom hooks को replay नहीं किया जाता है (वे original session के बाद से बदल सकते हैं)। \ No newline at end of file +- **कोई म्यूटेशन नहीं।** जांच केवल-पढ़ने के मोड में दोबारा चलाई जाती है। `warn-repeated-tool-calls` को छोड़ा जाता है क्योंकि इसका प्रति-सेशन साइडकार अन्यथा संशोधित होगा। +- **वर्कफ़्लो नीतियां छोड़ी जाती हैं।** `require-*-before-stop` नीतियां केवल `Stop` इवेंट और लाइव git स्थिति के खिलाफ `execSync` पर चलती हैं — उनके पास कोई अर्थपूर्ण "2025 में क्या हुआ होता" की व्याख्या नहीं है, इसलिए वे जांच गणना में दिखाई नहीं देते। +- **कस्टम नीतियां छोड़ी जाती हैं।** उपयोगकर्ता-आपूर्ति किए गए कस्टम हुक को दोबारा चलाया नहीं जाता (वे मूल सेशन के बाद से बदल सकते हैं)। \ No newline at end of file diff --git a/docs/hi/cli/dashboard.mdx b/docs/hi/cli/dashboard.mdx index 75a3298d..8585fcaf 100644 --- a/docs/hi/cli/dashboard.mdx +++ b/docs/hi/cli/dashboard.mdx @@ -1,6 +1,6 @@ --- -title: सेशन देखें -description: "एजेंट सेशन ब्राउज़ करने और नीतियों को प्रबंधित करने के लिए डैशबोर्ड लॉन्च करें" +title: सत्र देखें +description: "एजेंट सत्रों को ब्राउज़ करने और नीतियों को प्रबंधित करने के लिए डैशबोर्ड लॉन्च करें" --- ```bash @@ -11,12 +11,12 @@ failproofai ## विकल्प -| फ़्लैग | विवरण | +| फ्लैग | विवरण | |------|-------------| | `--port ` | सुनने के लिए पोर्ट (डिफ़ॉल्ट: `8020`) | -| `--allowed-origins ` | कॉमा-अलग होस्ट/IP जिन्हें dev संसाधनों तक पहुंचने की अनुमति है | +| `--allowed-origins ` | डेव संसाधनों तक पहुँच की अनुमति देने वाले अल्पविराम-अलग होस्ट/IP | -डैशबोर्ड को एक गैर-डिफ़ॉल्ट Claude प्रोजेक्ट फ़ोल्डर की ओर इंगित करने के लिए, लॉन्च करते समय `CLAUDE_PROJECTS_PATH` पर्यावरण चर सेट करें। +डैशबोर्ड को गैर-डिफ़ॉल्ट Claude प्रोजेक्ट फ़ोल्डर की ओर इंगित करने के लिए, लॉन्च करते समय `CLAUDE_PROJECTS_PATH` पर्यावरण चर सेट करें। ## उदाहरण diff --git a/docs/hi/cli/environment-variables.mdx b/docs/hi/cli/environment-variables.mdx index 3c1e96d6..cc037a3a 100644 --- a/docs/hi/cli/environment-variables.mdx +++ b/docs/hi/cli/environment-variables.mdx @@ -1,64 +1,67 @@ --- -title: Environment variables -description: "failproofai के व्यवहार को environment variables से कॉन्फ़िगर करें" +--- +title: पर्यावरण चर +description: "पर्यावरण चर के साथ failproofai व्यवहार को कॉन्फ़िगर करें" --- -## Dashboard +## डैशबोर्ड -| Variable | Description | +| चर | विवरण | |----------|-------------| -| `PORT` | Dashboard port (डिफ़ॉल्ट: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Claude Code प्रोजेक्ट फोल्डर्स को खोजने की जगह को ओवरराइड करें | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | कॉमा-अलग किए गए dashboard पेज छिपाने के लिए | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | dev संसाधनों तक पहुंचने की अनुमति वाले होस्ट/IP। `--allowed-origins` के समान। | +| `PORT` | डैशबोर्ड पोर्ट (डिफ़ॉल्ट: `8020`) | +| `CLAUDE_PROJECTS_PATH` | Claude Code प्रोजेक्ट फ़ोल्डर कहां पाए जाते हैं, इसे ओवरराइड करें | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | छिपाने के लिए कॉमा-अलग डैशबोर्ड पृष्ठ | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | डेव संसाधनों तक पहुंचने की अनुमति वाले होस्ट/IP। `--allowed-origins` के समान। | -## Logging +## लॉगिंग -| Variable | Description | +| चर | विवरण | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Server log level (डिफ़ॉल्ट: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | कस्टम hook लॉग फ़ाइल पथ, या डिफ़ॉल्ट के लिए `true` (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | सर्वर लॉग स्तर (डिफ़ॉल्ट: `warn`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | कस्टम हुक लॉग फ़ाइल पाथ, या डिफ़ॉल्ट के लिए `true` (`~/.failproofai/logs/hooks.log`) | -## Telemetry +## टेलीमेट्री -failproofai डिफ़ॉल्ट रूप से anonymous usage telemetry रिपोर्ट करता है। इसे बंद करने के दो तरीके हैं, और वे जो अधिक प्रतिबंधात्मक है उसे चुनते हैं — एक environment variable कभी भी कॉन्फ़िग फ़ाइल द्वारा बंद किए गए कुछ को फिर से सक्षम नहीं कर सकता। +failproofai डिफ़ॉल्ट रूप से गुमनाम उपयोग टेलीमेट्री रिपोर्ट करता है। इसे बंद करने के दो तरीके हैं, और वे अधिक प्रतिबंधक को हल करते हैं — एक पर्यावरण चर कभी भी कोई चीज़ फिर से सक्षम नहीं कर सकता जिसे कॉन्फ़िग फ़ाइल ने बंद कर दिया है। -| Variable | Description | +| चर | विवरण | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | इस प्रक्रिया के लिए anonymous usage telemetry को अक्षम करें | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | इस प्रक्रिया के लिए गुमनाम उपयोग टेलीमेट्री को अक्षम करें | -इसे मशीन के लिए स्थायी रूप से अक्षम करने के लिए, इसे `~/.failproofai/config.toml` में जोड़ें: +इसे मशीन के लिए स्थायी रूप से अक्षम करने के लिए, इसे `~/.failproofai/config.json` में जोड़ें: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -कॉन्फ़िग फ़ाइल यह विकल्प है यदि आप **failproofaid daemon** चलाते हैं। -daemon एक system-scope सेवा है, और इसके environment में -आपके shell से export किए गए variables शामिल नहीं होते — इसलिए `FAILPROOFAI_TELEMETRY_DISABLED` इसतक नहीं पहुंच सकता। `[telemetry] enabled = false` को CLI और daemon दोनों द्वारा पढ़ा जाता है। +कॉन्फ़िग फ़ाइल यह विकल्प है यदि आप **failproofaid डेमन** चलाते हैं। +डेमन एक सिस्टम-स्कोप सेवा है, और इसका पर्यावरण आपके शेल से निर्यात किए गए चर को शामिल नहीं करता — इसलिए `FAILPROOFAI_TELEMETRY_DISABLED` इसतक नहीं पहुंच सकता। `[telemetry] enabled = false` CLI और डेमन दोनों द्वारा पढ़ा जाता है। -daemon केवल अपना **lifecycle** रिपोर्ट करता है: कि यह शुरू हुआ (और क्या पिछला रन स्वच्छता से बंद हुआ), कि यह बंद हुआ, जब इसका evaluation worker स्पॉन या पुनः शुरू किया गया था, जब एक collector task विफल हुआ, और एक cloud-policy pull का परिणाम। ये कम-cardinality values और counts ले जाते हैं — कभी एक फ़ाइल पथ, एक कमांड, एक policy, एक prompt, या transcript से कुछ भी नहीं पढ़ा जाता। कोई per-tool-call event नहीं है। +डेमन केवल अपने **जीवनचक्र** की रिपोर्ट करता है: कि यह शुरू हुआ (और क्या पिछला रन स्वच्छता से बाहर निकला), कि यह बंद हुआ, जब इसका मूल्यांकन कर्मचारी स्पॉन किया गया था या पुनरारंभ किया गया था, जब एक कलेक्टर कार्य विफल हुआ, और क्लाउड-नीति पुल का परिणाम। ये कम-कार्डिनैलिटी मानों और गणनाओं को ले जाते हैं — कभी भी कोई फ़ाइल पाथ, कमांड, नीति, प्रॉम्प्ट, या ट्रांसक्रिप्ट से पढ़ी गई कोई चीज़ नहीं। कोई प्रति-टूल-कॉल ईवेंट नहीं है। -## Authentication +## प्रमाणीकरण -| Variable | Description | +| चर | विवरण | |----------|-------------| -| `FAILPROOF_API_URL` | dashboard auth dialog द्वारा उपयोग किए जाने वाले api-server base URL को ओवरराइड करें। डिफ़ॉल्ट `https://api.befailproof.ai`; स्थानीय api-server चलाते समय `http://localhost:8080` (या जहां भी) पर सेट करें। | -| `FAILPROOFAI_AUTH_DIR` | `auth.json` को स्टोर करने की जगह को ओवरराइड करें (डिफ़ॉल्ट: `~/.failproofai`)। अधिकतर isolated tests के लिए उपयोगी। | +| `FAILPROOF_API_URL` | डैशबोर्ड auth डायलॉग द्वारा उपयोग किए जाने वाले api-सर्वर बेस URL को ओवरराइड करें। डिफ़ॉल्ट `https://api.befailproof.ai`; स्थानीय api-सर्वर चलाते समय `http://localhost:8080` (या जहां कहीं) पर सेट करें। | +| `FAILPROOFAI_AUTH_DIR` | ओवरराइड करें कि `auth.json` कहां संग्रहीत है (डिफ़ॉल्ट: `~/.failproofai`)। ज्यादातर अलग-थलग परीक्षणों के लिए उपयोगी। | -## First-run prompt +## पहली बार चलाने पर प्रॉम्प्ट -| Variable | Description | +| चर | विवरण | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | पहली bare `failproofai` invocation पर policies को install करने का प्रस्ताव देने वाले prompt को स्किप करें | +| `FAILPROOFAI_NO_FIRST_RUN=1` | पहली बार बिना किसी `failproofai` आह्वान पर नीतियों को स्थापित करने का प्रस्ताव देने वाले प्रॉम्प्ट को छोड़ें | -## LLM (policy evaluation के लिए) +## LLM (नीति मूल्यांकन के लिए) -| Variable | Description | +| चर | विवरण | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | LLM API endpoint (डिफ़ॉल्ट: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | LLM-powered policies के लिए API key | -| `FAILPROOFAI_LLM_MODEL` | Model name (डिफ़ॉल्ट: `gpt-4o-mini`) | \ No newline at end of file +| `FAILPROOFAI_LLM_BASE_URL` | LLM API एंडपॉइंट (डिफ़ॉल्ट: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | LLM-संचालित नीतियों के लिए API कुंजी | +| `FAILPROOFAI_LLM_MODEL` | मॉडल नाम (डिफ़ॉल्ट: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/hi/cli/hook.mdx b/docs/hi/cli/hook.mdx index bfd8abe3..37f45656 100644 --- a/docs/hi/cli/hook.mdx +++ b/docs/hi/cli/hook.mdx @@ -1,30 +1,31 @@ --- -title: हुक हैंडलर (आंतरिक) -description: "जो सबप्रोसेस Claude Code प्रत्येक टूल इवेंट पर कॉल करता है" +--- +title: Hook हैंडलर (आंतरिक) +description: "प्रत्येक टूल ईवेंट पर Claude Code जो सबप्रोसेस कॉल करता है" --- ```bash failproofai --hook ``` -यह वह कमांड है जो `failproofai policies --install` द्वारा Claude Code की `settings.json` में पंजीकृत होती है। आप आमतौर पर इसे सीधे कॉल नहीं करते। +यह कमांड `failproofai policies --install` द्वारा Claude Code की `settings.json` में रजिस्टर की जाती है। आप आमतौर पर इसे सीधे कॉल नहीं करते। -stdin से JSON पेलोड पढ़ता है, सभी सक्षम नीतियों का मूल्यांकन करता है, और एक कोड के साथ बाहर निकलता है जो निर्णय को दर्शाता है: +stdin से एक JSON पेलोड पढ़ता है, सभी सक्षम नीतियों का मूल्यांकन करता है, और एक कोड के साथ बाहर निकलता है जो निर्णय को दर्शाता है: -| एक्जिट कोड | निर्णय | प्रभाव | +| Exit कोड | निर्णय | प्रभाव | |-----------|--------|--------| -| `0` | `allow` | कार्रवाई की अनुमति दें | -| `1` | `deny` | कार्रवाई को ब्लॉक करें - Claude को अस्वीकृति का कारण दिखाई देता है | -| `2` | `instruct` | Claude के संदर्भ में मार्गदर्शन इंजेक्ट करें | +| `0` | `allow` | कार्य को अनुमति दें | +| `1` | `deny` | कार्य को ब्लॉक करें - Claude को इनकार का कारण दिखाई देता है | +| `2` | `instruct` | Claude के संदर्भ में मार्गदर्शन को इंजेक्ट करें | -### समर्थित इवेंट प्रकार +### समर्थित ईवेंट प्रकार -| श्रेणी | इवेंट | +| श्रेणी | ईवेंट्स | |----------|--------| | **टूल निष्पादन** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | -| **सेशन जीवनचक्र** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | +| **सत्र जीवनचक्र** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **उपयोगकर्ता इंटरैक्शन** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **सबएजेंट और कार्य** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **सबएजेंट्स और कार्य** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **कॉन्फ़िगरेशन** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | -| **फाइल सिस्टम** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | +| **फ़ाइल सिस्टम** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **संदर्भ** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/hi/cli/install-policies.mdx b/docs/hi/cli/install-policies.mdx index 4c49c5d0..a6f329d5 100644 --- a/docs/hi/cli/install-policies.mdx +++ b/docs/hi/cli/install-policies.mdx @@ -1,57 +1,58 @@ --- -title: पॉलिसीज़ इंस्टॉल करें -description: "पॉलिसीज़ को सक्षम करें ताकि वे हर एजेंट टूल कॉल पर चलें" +--- +title: नीतियां स्थापित करें +description: "नीतियां सक्षम करें ताकि वे हर एजेंट टूल कॉल पर चलें" --- ```bash failproofai policies --install [policy-names...] [options] ``` -आपके इंस्टॉल किए गए एजेंट CLI की सेटिंग्स फाइल (Claude Code, OpenAI Codex, या GitHub Copilot CLI _(beta)_) में हुक एंट्रीज़ लिखता है ताकि failproofai टूल कॉल्स को इंटरसेप्ट कर सके। +आपके स्थापित एजेंट CLI के सेटिंग्स फ़ाइल (Claude Code, OpenAI Codex, या GitHub Copilot CLI _(beta)_) में हुक प्रविष्टियां लिखता है ताकि failproofai टूल कॉल को अवरोधित कर सके। उपनाम: `failproofai p -i` ## विकल्प -| फ्लैग | विवरण | +| फ़्लैग | विवरण | |------|-------------| -| `--cli claude\|codex\|copilot` | एजेंट CLI(s) जिसके लिए इंस्टॉल करना है; स्पेस-सेपरेटेड (जैसे `--cli claude codex copilot`) या दोहराया गया। छोड़ने पर इंस्टॉल किए गए CLIs का पता लगाएगा और प्रॉम्प्ट करेगा। | -| `--scope user` | यूजर-स्कोप सेटिंग्स फाइल में इंस्टॉल करें (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`)। डिफॉल्ट। | -| `--scope project` | प्रोजेक्ट-स्कोप सेटिंग्स फाइल में इंस्टॉल करें (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`)। | -| `--scope local` | केवल Claude — `/.claude/settings.local.json` में इंस्टॉल करता है। Codex और Copilot के पास `local` स्कोप नहीं है। | -| `--custom ` / `-c` | कस्टम हुक पॉलिसीज़ युक्त JS फाइल का पाथ | +| `--cli claude\|codex\|copilot` | एजेंट CLI(s) जिनके लिए स्थापित करना है; स्पेस-अलग (जैसे `--cli claude codex copilot`) या दोहराया गया। छोड़ने से स्थापित CLIs का पता लगेगा और संकेत मिलेगा। | +| `--scope user` | उपयोगकर्ता-स्कोप सेटिंग्स फ़ाइल में स्थापित करें (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`)। डिफ़ॉल्ट। | +| `--scope project` | प्रोजेक्ट-स्कोप सेटिंग्स फ़ाइल में स्थापित करें (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`)। | +| `--scope local` | केवल Claude — `/.claude/settings.local.json` में स्थापित करता है। Codex और Copilot के पास `local` स्कोप नहीं है। | +| `--custom ` / `-c` | कस्टम हुक नीतियों वाली JS फ़ाइल का पथ | ## व्यवहार -- **कोई पॉलिसी नाम नहीं** - पॉलिसीज़ का चयन करने के लिए इंटरैक्टिव प्रॉम्प्ट खोलता है -- **विशिष्ट नाम** - उन पॉलिसीज़ को सक्षम करता है (किसी पहले से सक्षम किए गए में जोड़ा जाता है) -- **`all`** - हर उपलब्ध पॉलिसी को सक्षम करता है +- **कोई नीति नाम नहीं** - नीतियों का चयन करने के लिए एक इंटरैक्टिव संकेत खोलता है +- **विशिष्ट नाम** - उन नीतियों को सक्षम करता है (किसी भी पहले से सक्षम के साथ जोड़ा गया) +- **`all`** - हर उपलब्ध नीति को सक्षम करता है -इंस्टॉलेशन योज्य है: `--install` को फिर से चलाने से नई पॉलिसीज़ जुड़ती हैं बिना मौजूदा को हटाए। +स्थापन योगात्मक है: `--install` को फिर से चलाने से नई नीतियां जुड़ती हैं बिना मौजूदा को हटाए। ## उदाहरण ```bash -# सभी डिफॉल्ट पॉलिसीज़ को ग्लोबली इंस्टॉल करें (इंटरैक्टिव) +# सभी डिफ़ॉल्ट नीतियां विश्व स्तर पर स्थापित करें (इंटरैक्टिव) failproofai policies --install -# वर्तमान प्रोजेक्ट के लिए विशिष्ट पॉलिसीज़ इंस्टॉल करें +# वर्तमान प्रोजेक्ट के लिए विशिष्ट नीतियां स्थापित करें failproofai policies --install block-sudo sanitize-api-keys --scope project -# एक बार में सभी पॉलिसीज़ को सक्षम करें +# एक बार में सभी नीतियां सक्षम करें failproofai policies --install all -# कस्टम पॉलिसीज़ फाइल के साथ इंस्टॉल करें +# कस्टम नीतियों फ़ाइल के साथ स्थापित करें failproofai policies --install --custom ./my-policies.js -# OpenAI Codex के लिए इंस्टॉल करें (प्रोजेक्ट स्कोप) +# OpenAI Codex के लिए स्थापित करें (प्रोजेक्ट स्कोप) failproofai policies --install --cli codex --scope project -# वर्तमान प्रोजेक्ट के लिए GitHub Copilot CLI (beta) के लिए इंस्टॉल करें +# वर्तमान प्रोजेक्ट के लिए GitHub Copilot CLI (beta) के लिए स्थापित करें failproofai policies --install --cli copilot --scope project -# एक साथ सभी तीन CLIs के लिए इंस्टॉल करें +# एक बार में सभी तीन CLIs के लिए स्थापित करें failproofai policies --install --cli claude codex copilot ``` -जब `--custom ` प्रदान किया जाता है, तो फाइल को तुरंत मान्य किया जाता है - इसे कम से कम एक बार `customPolicies.add()` को कॉल करना चाहिए। हल किया गया पाथ `policies-config.json` में `customPoliciesPath` के रूप में सहेजा जाता है। \ No newline at end of file +जब `--custom ` प्रदान किया जाता है, तो फ़ाइल को तुरंत सत्यापित किया जाता है - इसे कम से कम एक बार `customPolicies.add()` को कॉल करना चाहिए। हल किया गया पथ `policies-config.json` में `customPoliciesPath` के रूप में सहेजा जाता है। \ No newline at end of file diff --git a/docs/hi/cli/list-policies.mdx b/docs/hi/cli/list-policies.mdx index ff04340a..4fb5826b 100644 --- a/docs/hi/cli/list-policies.mdx +++ b/docs/hi/cli/list-policies.mdx @@ -1,13 +1,14 @@ --- -title: नीतियों की सूची -description: "देखें कि कौन सी नीतियां सक्षम हैं, उनके पैरामीटर, और कस्टम नीतियां" +--- +title: नीतियों की सूची देखें +description: "देखें कि कौन सी नीतियां सक्षम हैं, उनके पैरामीटर और कस्टम नीतियां" --- ```bash failproofai policies ``` -सभी नीतियों को उनकी स्थिति, कॉन्फ़िगर किए गए पैरामीटर, और कस्टम नीतियों के साथ दिखाता है। +सभी नीतियों को उनकी स्थिति, कॉन्फ़िगर किए गए पैरामीटर और कस्टम नीतियों के साथ दिखाता है। ## नमूना आउटपुट @@ -28,4 +29,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -`policyParams` में अज्ञात कुंजियों को यहां फ्लैग किया जाता है ताकि आप जल्दी टाइपो को पकड़ सकें। \ No newline at end of file +`policyParams` में अज्ञात कुंजियों को यहां चिह्नित किया जाता है ताकि आप टाइपो को जल्दी पकड़ सकें। \ No newline at end of file diff --git a/docs/hi/cli/migrate.mdx b/docs/hi/cli/migrate.mdx new file mode 100644 index 00000000..123625e8 --- /dev/null +++ b/docs/hi/cli/migrate.mdx @@ -0,0 +1,85 @@ +--- +title: होम डायरेक्टरी को माइग्रेट करें +description: "~/.failproofai को इस संस्करण के लेआउट तक लाएं, और पहले देखें कि क्या होगा" +--- + +```bash +failproofai migrate --dry-run # योजना प्रिंट करें, कुछ न बदलें +failproofai migrate # इसे चलाएं +``` + +अधिकांश लोग इसे कभी नहीं लिखते। यह अपग्रेड के बाद पहली कमांड पर स्वयं चलता है, और [`failproofai update`](/hi/cli/update) में इसे शामिल किया जाता है। इसे सीधे तब चलाएं जब आप माइग्रेशन से पहले योजना देखना चाहते हैं, या माइग्रेशन को अकेले चलाना चाहते हैं। + +## संस्करण पर नहीं, लेआउट पर कुंजी + +`~/.failproofai/VERSION` एक **लेआउट** संख्या रिकॉर्ड करता है — डायरेक्टरी की आकृति, न कि इसे लिखने वाली रिलीज़। माइग्रेशन उस संख्या पर कुंजीबद्ध हैं, जो एक लंबे अंतराल को सस्ता बनाता है: + +- npm संस्करण प्रत्येक रिलीज़ पर बदलते हैं, दो लेआउट के बीच दर्जनों। +- तो एक मशीन जो **कोई लेआउट परिवर्तन न होने के साथ** तीस रिलीज़ छोड़ती है, **शून्य** माइग्रेशन चलाती है, तीस नहीं। +- और एक मशीन जो एक बार में कई लेआउट छोड़ती है, क्रम में प्रत्येक चरण चलाती है, प्रत्येक चरण केवल अपने दोनों सिरों को जानता है। + +यह महत्वपूर्ण है क्योंकि npm स्वयं एक स्थापित पैकेज को अपडेट नहीं कर सकता। एक मशीन जो महीनों तक एक संस्करण पर बैठती है और फिर कई लेआउट में कूदती है, वह सामान्य मामला है, विदेशी नहीं। + +## ड्राई रन + +`--dry-run` सटीक श्रृंखला और वह फ़ाइलें प्रिंट करता है जिन्हें पहले सहेजा जाएगा, और बिल्कुल कुछ नहीं बदलता है — कोई माइग्रेशन नहीं, कोई बैकअप नहीं, कोई बहीखाता प्रविष्टि नहीं: + +``` +लेआउट 2 डिस्क पर; यह बिल्ड 3 बोलता है। +1 चरण चलेगा: + 2 → 3 लेआउट 2 → 3: config.toml और credentials.toml को JSON में ले जाएं, कस्टम-नीतियों को वापस नीतियों में स्थानांतरित करें, नीति कॉन्फ़िगरेशन को रूट पर नेस्ट करें + +ये पहले ~/.failproofai/migrations/backup-layout2 में कॉपी किए जाएंगे: + VERSION + config.toml + credentials.toml +``` + +## क्या ले जाया जाता है, और क्या पुनर्निर्मित किया जाता है + +होम में प्रत्येक पथ घोषणा करता है कि यह किस प्रकार का डेटा रखता है, और यह तय करता है कि माइग्रेशन इसे फेंक सकता है या नहीं। नियम: **व्युत्पन्न और पुनः प्राप्त किए जाने वाले को छोड़ा जा सकता है; जो कुछ भी आपने लिखा है, जो अभी तक डिलीवर नहीं हुआ है, और जो कुछ भी मशीन की पहचान करता है वह ले जाया जाता है।** + +| ले जाया जाता है | पुनर्निर्मित या पुनः प्राप्त किया जाता है | +|---|---| +| `config.json` — सेटिंग्स, `daemon.configured`, अतिरिक्त कैप्चर पथ | ऑडिट कैश | +| `credentials.json` — आपका क्लाउड नामांकन | क्लाउड-प्रबंधित स्थापन (अगले पोल पर पुनः प्राप्त और डाइजेस्ट-सत्यापित) | +| `policies-config.json` — आपकी नीति चयन और पैरामीटर | डेमॉन स्क्रैच स्थिति | +| `policies/` — आपकी अपनी नीति फ़ाइलें और सहायक जो वे आयात करते हैं | | +| `hook-activity/` — निर्णय लॉग डैशबोर्ड पढ़ता है | | +| अभी तक अपलोड के लिए कतारबद्ध डिलीवर न किए गए इवेंट | | +| `cursors/` — कलेक्टर जलांकन | | +| `bin/` में डेमॉन बाइनरी | | + + + डिलीवर न किए गए इवेंट को छोड़ा जाने की बजाय ले जाया जाता है क्योंकि नुकसान स्थायी होगा, धीमा नहीं: कलेक्टर का जलांकन पहले से ही स्पूल में बैठी किसी भी चीज़ के आगे बढ़ चुका है, इसलिए कुछ भी एक ट्रांसक्रिप्ट की उस श्रेणी को फिर कभी नहीं पढ़ेगा। माइग्रेशन डेमॉन को स्पूल किए गए को समाप्त होने के बाद जितनी जल्दी डिलीवर करने के लिए भी कहता है, इसलिए सामान्य परिणाम यह है कि ले जाने के लिए कुछ नहीं बचा है। + + +एक *नए* संस्करण ने `config.json`, `credentials.json` या `policies-config.json` में जो कुंजियाँ लिखीं, वे भी संरक्षित रहती हैं, न कि एक पुराने पाठक द्वारा छोड़ी जाती हैं। + +## यह जो रिकॉर्ड छोड़ता है + +``` +~/.failproofai/migrations/ + applied.json प्रत्येक चरण के लिए एक प्रविष्टि: लेआउट, CLI, टाइमस्टैम्प, अवधि, परिणाम + backup-layout/ पहले चरण से पहले लिए गए अपरिहार्य फ़ाइलों की प्रतियाँ +``` + +`applied.json` वह है जो "इस मशीन ने वास्तव में क्या अनुभव किया है" का जवाब देता है — अपग्रेड के बाद कुछ गलत दिखने पर पूछने के लायक पहला प्रश्न। इसे एक बग रिपोर्ट में संलग्न करें। + +बैकअप जानबूझकर पूरी डायरेक्टरी की प्रतिलिपि के बजाय छोटा है: माइग्रेशन अब डिज़ाइन के अनुसार कुछ भी अपरिहार्य नहीं हटाता है, इसलिए जिसे बीमित करने के लायक है वह एक *चरण में दोष* है, और ये कुछ फ़ाइलें वह हैं जहां ऐसा दोष चोट पहुँचाएगा। + +## यदि कोई चरण विफल हो जाए + +श्रृंखला वहीं रुक जाती है। `VERSION` केवल एक पूर्ण चरण द्वारा स्टैम्प किया जाता है, इसलिए होम अपने पुराने लेआउट के साथ चिह्नित रहता है और अगली कमांड इसे पुनः प्रयास करती है — एक होम को कभी आंशिक माइग्रेशन की ताकत पर वर्तमान नहीं चिह्नित किया जाता है। चरण को `applied.json` में `"ok": false` के साथ दर्ज किया जाता है, और बैकअप वह है जहां इसे लिया गया था। + +## एक नए होम को माइग्रेट नहीं किया जाता, अस्वीकार किया जाता है + +यदि `~/.failproofai/` को एक **नए** failproofai द्वारा लिखा गया था जो आप चला रहे हैं उससे, कमांड रुक जाती है और आपको बजाय माइग्रेट करने के अपग्रेड करने के लिए कहती है। वह डेटा ठीक है और एक नए CLI इसे पढ़ता है; इससे "फॉरवर्ड" माइग्रेट करना एक ऐसी चीज़ है जो अस्तित्व में नहीं है, और इसे रीसेट करना कुछ पुनः प्राप्य को नष्ट करेगा। + +``` +इस मशीन की failproofai डायरेक्टरी एक नए संस्करण द्वारा लिखी गई थी (लेआउट 4; +यह बिल्ड 3 बोलता है)। माइग्रेट करने के बजाय अपग्रेड करें: + npm install -g failproofai@latest +``` + +डेमॉन एक ही नियम लागू करता है: `failproofaid` एक लेआउट के विरुद्ध शुरू करने से इनकार करता है जिसे यह नहीं बोलता है, बजाय पथों को पढ़ने और लिखने के जो चले गए हैं। \ No newline at end of file diff --git a/docs/hi/cli/remove-policies.mdx b/docs/hi/cli/remove-policies.mdx index 3a9b9bd9..9ba5551b 100644 --- a/docs/hi/cli/remove-policies.mdx +++ b/docs/hi/cli/remove-policies.mdx @@ -1,6 +1,7 @@ --- +--- title: नीतियों को अनइंस्टॉल करें -description: "Claude Code की सेटिंग्स से हुक एंट्रीज़ हटाएं" +description: "Claude Code की सेटिंग्स से हुक एंट्रीज़ को हटाएं" --- ```bash @@ -13,31 +14,31 @@ Claude Code के `settings.json` से failproofai हुक एंट्र ## विकल्प -| फ़्लैग | विवरण | +| फ्लैग | विवरण | |------|-------------| | `--scope user` | वैश्विक सेटिंग्स से हटाएं (डिफ़ॉल्ट) | | `--scope project` | प्रोजेक्ट सेटिंग्स से हटाएं | | `--scope local` | स्थानीय सेटिंग्स से हटाएं | | `--scope all` | सभी स्कोप से एक साथ हटाएं | -| `--custom` / `-c` | कॉन्फ़िग से `customPoliciesPath` को साफ़ करें | +| `--custom` / `-c` | कॉन्फ़िगरेशन से `customPoliciesPath` को साफ़ करें | ## व्यवहार -- **कोई नीति का नाम नहीं** - सेटिंग्स फ़ाइल से सभी failproofai हुक एंट्रीज़ को हटाता है +- **कोई नीति नाम नहीं** - सेटिंग्स फ़ाइल से सभी failproofai हुक एंट्रीज़ को हटाता है - **विशिष्ट नाम** - उन नीतियों को अक्षम करता है लेकिन हुक को इंस्टॉल रखता है ## उदाहरण ```bash -# सभी हुक को वैश्विक रूप से हटाएं +# सभी हुक को विश्व स्तर पर हटाएं failproofai policies --uninstall -# किसी विशिष्ट नीति को अक्षम करें (हुक इंस्टॉल रहते हैं) +# किसी विशिष्ट नीति को अक्षम करें (हुक को इंस्टॉल रखता है) failproofai policies --uninstall block-sudo # हर स्कोप से हुक को हटाएं failproofai policies --uninstall --scope all -# कस्टम नीतियों का पाथ साफ़ करें +# कस्टम नीतियों पथ को साफ़ करें failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/hi/cli/update.mdx b/docs/hi/cli/update.mdx new file mode 100644 index 00000000..31cda433 --- /dev/null +++ b/docs/hi/cli/update.mdx @@ -0,0 +1,64 @@ +--- +title: अपग्रेड के बाद अपडेट करें +description: "अपग्रेड का दूसरा आधा पूरा करें जो npm नहीं कर सकता: होम को माइग्रेट करें और डेमन को मैच करें" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +यह पूरी अपग्रेड है। `npm` CLI को बदल देता है; `failproofai update` बाकी सब कुछ करता है। + +## दूसरी कमांड क्यों मौजूद है + +`npm install -g` सिर्फ एक चीज़ को बदलता है — CLI को। failproofai इंस्टॉल के दो अन्य हिस्से पैकेज के बाहर रहते हैं, और जब npm चलता है तो दोनों नहीं हिलते: + +- **`~/.failproofai/`**, आपकी सेटिंग्स, क्लाउड नामांकन, नीति चयन और इतिहास। एक नया संस्करण इसे अलग तरीके से व्यवस्थित कर सकता है, और पुनर्व्यवस्था को ऐसे कोड द्वारा की जानी चाहिए जो दोनों रूपों को जानता है। +- **`failproofaid` डेमन बाइनरी**, `~/.failproofai/bin/failproofaid-` पर। यह जानबूझकर `node_modules` के अंदर *नहीं* है: एक अपग्रेड जो चलती सेवा के तहत फ़ाइल को स्वैप करता, लाइव डेमन को अलग स्रोत से बनी बाइनरी की ओर इशारा करेगा, और पैकेज को हटाने से यह सेवा के तहत हटा दिया जाएगा जो तब हर बूट पर क्रैश-लूप करती है। + +तो `npm install -g` के बाद अकेले, CLI नया है और डेमन नहीं है। `failproofaid` एक होम लेआउट के विरुद्ध शुरू होने से इनकार करता है जिसे वह नहीं समझता — उस बेमेल का जोर संस्करण शांत के बजाय — तो दोनों हिस्सों को एक साथ लाना पड़ता है। `failproofai update` यही कदम है। + +## यह क्या करता है + + + + `~/.failproofai/VERSION` में दर्ज किए गए लेआउट को पढ़ता है और वे चरण चलाता है जो इसे इस संस्करण में लाते हैं। आमतौर पर कोई नहीं — [`failproofai migrate`](/hi/cli/migrate) देखें। + + + प्लेटफ़ॉर्म पैकेज से जो npm पहले से ही डाउनलोड कर चुका है जहाँ संभव हो (बिना नेटवर्क), अन्यथा इस सटीक संस्करण के लिए रिलीज़ एसेट से, SHA-256 इसके उपयोग से पहले सत्यापित। + + + अनुमान के बजाय जांचा जाता है — एक सेवा प्रबंधक एक प्रक्रिया को सक्रिय रिपोर्ट करता है जिस क्षण यह फोर्क होता है, जो यह काम करने जैसा नहीं है। + + + +## विकल्प + +| फ्लैग | प्रभाव | +|------|--------| +| `--no-daemon` | केवल होम को माइग्रेट करें, डेमन को इसके वर्तमान संस्करण पर छोड़ दें। | + + + `--no-daemon` एक संस्करण-विषम डेमन को जगह पर छोड़ देता है। एक मशीन पर जिसे डेमन की आवश्यकता होने के लिए कॉन्फ़िगर किया गया है, यदि डेमन जवाब नहीं दे सकता तो हर हुक ईवेंट **बंद हो जाता है** — और एक डेमन जो माइग्रेट किए गए होम के विरुद्ध शुरू होने से इनकार करता है जवाब नहीं दे सकता। डेमन आधे को चलाने देना बेहतर है। + + +## यदि कुछ गलत हो जाए + +कमांड गैर-शून्य से बाहर निकलता है और कहता है कि कौन सा आधा विफल हुआ। दो मामले जानने के लायक हैं: + +- **एक माइग्रेशन कदम पूरा नहीं हुआ।** होम को इसके *पुराने* लेआउट से चिह्नित छोड़ा जाता है, तो अगली कमांड इसे फिर से करने की कोशिश करती है — कोई होम कभी आंशिक माइग्रेशन की ताकत पर वर्तमान चिह्नित नहीं किया जाता। आपकी सेटिंग्स और नामांकन की प्रतियाँ कुछ भी चलाने से पहले `~/.failproofai/migrations/backup-layout/` में सहेजी गई थीं। +- **डेमन को पासवर्ड के बिना पुनः आरंभ नहीं किया जा सका।** `sudo -n` को जानबूझकर उपयोग किया जाता है, इसलिए कुछ भी कभी प्रगति प्रदर्शन के तहत से संकेत नहीं देता। कमांड चलाने के लिए सटीक पंक्ति प्रिंट करता है। + + + यहाँ कुछ भी इंटरेक्टिव सेटअप विज़ार्ड की आवश्यकता नहीं है। आपकी सेटिंग्स, क्लाउड नामांकन और नीति चयन अपग्रेड से बचे रहते हैं, इसलिए एक माइग्रेट की गई मशीन ठीक वैसे ही लागू करती है जैसे पहले थी — जो सबसे अधिक महत्वपूर्ण है उन मशीनों पर जहाँ कोई नहीं बैठता: एक CI रनर, एक फ्लीट बॉक्स, एक हेडलेस गेटवे। + + +## इसे स्वचालित करना + +`failproofai update` गैर-इंटरेक्टिव है और जब कुछ नहीं करना हो तो चलाने के लिए सुरक्षित है — यह "कोई माइग्रेशन आवश्यक नहीं था" की रिपोर्ट करता है और 0 से बाहर निकलता है। इसे प्रावधान स्क्रिप्ट या Dockerfile में हर अपग्रेड के बाद डालना अभीष्ट उपयोग है: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` एक छवि बिल्ड में, जहाँ अभी तक पुनः आरंभ करने के लिए कोई सेवा नहीं है।) \ No newline at end of file diff --git a/docs/hi/cli/version.mdx b/docs/hi/cli/version.mdx index 86501810..542cdf1a 100644 --- a/docs/hi/cli/version.mdx +++ b/docs/hi/cli/version.mdx @@ -5,7 +5,7 @@ description: "स्थापित failproofai संस्करण प्र ```bash failproofai --version -# या +# or failproofai -v ``` diff --git a/docs/hi/configuration.mdx b/docs/hi/configuration.mdx index a7f106f5..5f19fce0 100644 --- a/docs/hi/configuration.mdx +++ b/docs/hi/configuration.mdx @@ -1,38 +1,39 @@ --- +--- title: कॉन्फ़िगरेशन description: "कॉन्फ़िग फ़ाइल प्रारूप, तीन-स्कोप सिस्टम, और मर्ज नियम" icon: gear --- -failproofai JSON कॉन्फ़िगरेशन फ़ाइलों का उपयोग करके नियंत्रित करता है कि कौन सी नीतियां सक्रिय हैं, वे कैसे व्यवहार करती हैं, और कस्टम नीतियां कहां से लोड की जाती हैं। कॉन्फ़िगरेशन आपकी टीम के साथ साझा करना आसान बनाने के लिए डिज़ाइन किया गया है - इसे अपने रेपो में कमिट करें और प्रत्येक डेवलपर को एक ही एजेंट सेफ्टी नेट मिलता है। +failproofai JSON कॉन्फ़िगरेशन फ़ाइलों का उपयोग करता है यह नियंत्रित करने के लिए कि कौन सी नीतियां सक्रिय हैं, वे कैसे व्यवहार करती हैं, और कहां से कस्टम नीतियां लोड की जाती हैं। कॉन्फ़िगरेशन को आपकी टीम के साथ साझा करना आसान बनाया गया है - इसे अपने रेपो में कमिट करें और हर डेवलपर को एक ही एजेंट सेफ्टी नेट मिलता है। --- ## कॉन्फ़िगरेशन स्कोप -तीन कॉन्फ़िगरेशन स्कोप हैं, जिनका मूल्यांकन प्राथमिकता क्रम में किया जाता है: +तीन कॉन्फ़िगरेशन स्कोप हैं, प्राथमिकता क्रम में मूल्यांकित: | स्कोप | फ़ाइल पथ | उद्देश्य | |-------|-----------|---------| -| **प्रोजेक्ट** | `.failproofai/policies-config.json` | प्रति-रेपो सेटिंग्स, संस्करण नियंत्रण में कमिट की गई | -| **स्थानीय** | `.failproofai/policies-config.local.json` | व्यक्तिगत प्रति-रेपो ओवरराइड, gitignore किया गया | -| **वैश्विक** | `~/.failproofai/policies-config.json` | सभी प्रोजेक्ट्स में उपयोगकर्ता-स्तर की डिफ़ॉल्ट | +| **project** | `.failproofai/policies-config.json` | प्रति-रेपो सेटिंग्स, संस्करण नियंत्रण में कमिट की गई | +| **local** | `.failproofai/policies-config.local.json` | व्यक्तिगत प्रति-रेपो ओवरराइड, gitignored | +| **global** | `~/.failproofai/policies-config.json` | उपयोगकर्ता-स्तरीय डिफ़ॉल्ट सभी प्रोजेक्ट्स में | -जब failproofai को एक हुक इवेंट प्राप्त होता है, तो वह वर्तमान कार्यशील निर्देशिका के लिए मौजूद तीनों फ़ाइलों को लोड और मर्ज करता है। +जब failproofai को एक हुक इवेंट मिलता है, तो वह सभी तीन फ़ाइलों को लोड और मर्ज करता है जो वर्तमान कार्यशील निर्देशिका के लिए मौजूद हैं। ### मर्ज नियम -**`enabledPolicies`** - तीनों स्कोप का संघ। कोई भी स्तर पर सक्षम नीति सक्रिय होती है। +**`enabledPolicies`** - सभी तीन स्कोप का यूनियन। किसी भी स्तर पर सक्षम की गई नीति सक्रिय होती है। ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← डुप्लिकेट रहित संघ +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← डीडुप्लिकेट यूनियन ``` -**`policyParams`** - पहला स्कोप जो किसी दिए गए नीति के लिए पैरामीटर परिभाषित करता है, पूरी तरह जीत जाता है। नीति के पैरामीटर के भीतर कोई गहरी मर्जिंग नहीं है। +**`policyParams`** - दिए गए नीति के लिए पैरामीटर को परिभाषित करने वाला पहला स्कोप पूरी तरह जीतता है। किसी नीति के पैरामीटर के भीतर मूल्यों का कोई गहरा मर्ज नहीं होता। ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,18 +43,18 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project जीतत ``` ```text -project: (block-sudo प्रविष्टि नहीं) -local: (block-sudo प्रविष्टि नहीं) +project: (कोई block-sudo एंट्री नहीं) +local: (कोई block-sudo एंट्री नहीं) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← global तक गिरता है ``` -**`customPoliciesPaths` / `customPoliciesPath`** - पहला स्कोप जो किसी भी रूप को परिभाषित करता है, जीत जाता है। +**`customPoliciesPaths` / `customPoliciesPath`** - किसी भी रूप को परिभाषित करने वाला पहला स्कोप जीतता है। -**`disabledCustomPolicies`** - सभी स्कोप में संघ। डैशबोर्ड यहां एक स्रोत-योग्य ID लिखता है जब आप किसी स्पष्ट या परंपरा नीति फ़ाइल से एक व्यक्तिगत नीति को बंद करते हैं। सूचीबद्ध नहीं की गई नीतियां डिफ़ॉल्ट रूप से सक्षम रहती हैं; ID में स्रोत फ़ाइल शामिल है ताकि कई फ़ाइलों में एक ही नाम की नीतियों को स्वतंत्र रूप से नियंत्रित किया जा सके। +**`disabledCustomPolicies`** - सभी स्कोप में यूनियन। डैशबोर्ड यहां एक स्रोत-योग्य ID लिखता है जब आप किसी व्यक्तिगत नीति को किसी स्पष्ट या कन्वेंशन नीति फ़ाइल से बंद करते हैं। सूचीबद्ध नहीं की गई नीतियां डिफ़ॉल्ट रूप से सक्षम रहती हैं; ID में स्रोत फ़ाइल शामिल होती है ताकि कई फ़ाइलों में समान नाम की नीतियों को स्वतंत्र रूप से नियंत्रित किया जा सके। -**`llm`** - पहला स्कोप जो इसे परिभाषित करता है, जीत जाता है। +**`llm`** - किसी भी स्कोप को परिभाषित करने वाला पहला जीतता है। --- @@ -104,33 +105,33 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global तक गि प्रकार: `string[]` -सक्षम करने के लिए नीति नामों की सूची। नाम बिल्कुल `failproofai policies` द्वारा दिखाए गए नीति आइडेंटिफायर से मेल खाना चाहिए। पूरी सूची के लिए [Built-in Policies](/hi/built-in-policies) देखें। +सक्षम करने के लिए नीति नाम की सूची। नामों को `failproofai policies` द्वारा दिखाए गए नीति पहचानकर्ताओं से बिल्कुल मेल खाना चाहिए। पूरी सूची के लिए [Built-in Policies](/hi/built-in-policies) देखें। -`enabledPolicies` में नहीं होने वाली नीतियां निष्क्रिय हैं, भले ही उनके पास `policyParams` में प्रविष्टियां हों। +`enabledPolicies` में न होने वाली नीतियां निष्क्रिय होती हैं, भले ही `policyParams` में उनके प्रविष्टियां हों। ### `policyParams` प्रकार: `Record>` -प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; भीतरी कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति [Built-in Policies](/hi/built-in-policies) में अपने उपलब्ध पैरामीटर का दस्तावेज़ देती है। +प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; भीतरी कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति [Built-in Policies](/hi/built-in-policies) में अपने उपलब्ध पैरामीटर दस्तावेज़ करती है। -यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते हैं, तो नीति के बिल्ट-इन डिफ़ॉल्ट का उपयोग किया जाता है। जो उपयोगकर्ता `policyParams` को बिल्कुल कॉन्फ़िगर नहीं करते हैं, वे पिछले संस्करणों के समान व्यवहार प्राप्त करते हैं। +यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते हैं, तो नीति के निर्मित-में डिफ़ॉल्ट का उपयोग किया जाता है। जो उपयोगकर्ता `policyParams` को बिल्कुल कॉन्फ़िगर नहीं करते हैं वे पिछले संस्करणों के समान व्यवहार प्राप्त करते हैं। -नीति के पैरामीटर ब्लॉक के अंदर अज्ञात कुंजियां हुक-फायरिंग के समय चुप रहती हैं, लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनी के रूप में फ्लैग की जाती हैं। +किसी नीति के पैरामीटर ब्लॉक के भीतर अज्ञात कुंजियों को हुक-फायर समय में मूक रूप से अनदेखा किया जाता है लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनियों के रूप में फ्लैग किया जाता है। -#### `hint` (क्रॉस-कटिंग) +#### `hint` (cross-cutting) -प्रकार: `string` (वैकल्पिक) +प्रकार: `string` (optional) -एक संदेश जो कारण में जोड़ा जाता है जब कोई नीति `deny` या `instruct` लौटाती है। इसका उपयोग नीति को स्वयं संशोधित किए बिना Claude को कार्यकारी मार्गदर्शन देने के लिए करें। +एक संदेश जोड़ा गया कारण के लिए जब कोई नीति `deny` या `instruct` रिटर्न करती है। नीति को संशोधित किए बिना Claude को कार्रवाई योग्य मार्गदर्शन देने के लिए इसका उपयोग करें। -किसी भी नीति प्रकार के साथ काम करता है — बिल्ट-इन, कस्टम (`custom/`), प्रोजेक्ट परंपरा (`.failproofai-project/`), या उपयोगकर्ता परंपरा (`.failproofai-user/`)। +किसी भी नीति प्रकार के साथ काम करता है — निर्मित-में, कस्टम (`custom/`), प्रोजेक्ट कन्वेंशन (`.failproofai-project/`), या उपयोगकर्ता कन्वेंशन (`.failproofai-user/`)। ```json { "policyParams": { "block-force-push": { - "hint": "इसके बजाय एक नई शाखा बनाने का प्रयास करें।" + "hint": "इसके बजाय एक ताज़ी शाखा बनाने की कोशिश करें।" }, "block-sudo": { "allowPatterns": ["sudo apt-get"], @@ -143,9 +144,9 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global तक गि } ``` -जब `block-force-push` अस्वीकार करता है, तो Claude देखता है: *"Force-pushing अवरुद्ध है। इसके बजाय एक नई शाखा बनाने का प्रयास करें।"* +जब `block-force-push` अस्वीकार करता है, Claude देखता है: *"Force-pushing अवरुद्ध है। इसके बजाय एक ताज़ी शाखा बनाने की कोशिश करें।"* -गैर-स्ट्रिंग मान और खाली स्ट्रिंग्स को चुप रहे हुए अनदेखा किया जाता है। यदि `hint` सेट नहीं है, तो व्यवहार अपरिवर्तित है (पिछड़ी संगतता)। +गैर-स्ट्रिंग मान और खाली स्ट्रिंग्स को मूक रूप से अनदेखा किया जाता है। यदि `hint` सेट नहीं है, तो व्यवहार अपरिवर्तित रहता है (पिछड़े-संगत)। ### `customPoliciesPath` @@ -153,34 +154,43 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global तक गि कस्टम हुक नीतियां युक्त JavaScript फ़ाइल का पथ। यह `failproofai policies --install --custom ` द्वारा स्वचालित रूप से सेट किया जाता है (पथ को संग्रहीत करने से पहले निरपेक्ष में हल किया जाता है)। -फ़ाइल प्रत्येक हुक इवेंट पर ताज़ी लोड की जाती है - कोई कैशिंग नहीं है। विस्तार के लिए [Custom Policies](/hi/custom-policies) देखें। +फ़ाइल को हर हुक इवेंट पर ताज़ा लोड किया जाता है - कोई कैशिंग नहीं है। विस्तार के लिए [Custom Policies](/hi/custom-policies) देखें। -### परंपरा-आधारित नीतियां +### कन्वेंशन-आधारित नीतियां -स्पष्ट `customPoliciesPath` के अलावा, failproofai `.failproofai/policies/` निर्देशिकाओं से स्वचालित रूप से नीति फ़ाइलें खोजता है और लोड करता है: +स्पष्ट `customPoliciesPath` के अलावा, failproofai स्वचालित रूप से `.failproofai/policies/` निर्देशिकाओं से नीति फ़ाइलें खोजता है और लोड करता है: | स्तर | निर्देशिका | स्कोप | |-------|-----------|-------| -| प्रोजेक्ट | `.failproofai/policies/` | संस्करण नियंत्रण के माध्यम से टीम के साथ साझा किया गया | -| उपयोगकर्ता | `~/.failproofai/policies/custom-policies/` | व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू होता है | +| Project | `.failproofai/policies/` | संस्करण नियंत्रण के माध्यम से टीम के साथ साझा | +| User | `~/.failproofai/policies/` | व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू होता है | - उपयोगकर्ता-स्तर की निर्देशिका होम-निर्देशिका पुनर्गठन में एक स्तर नीचे चली गई है। पुरानी `~/.failproofai/policies/` में छोड़ी गई फ़ाइलें अपग्रेड करने के बाद पहली बार कोई भी `failproofai` कमांड चलाने पर स्वचालित रूप से `custom-policies/` में स्थानांतरित की जाती हैं, और कमांड आपको बताता है कि यह कौन सी फ़ाइलें स्थानांतरित करता है। + अपनी नीतियों को सीधे `~/.failproofai/policies/` में डालें। उनके बगल वाली + `cloud-policies/` फ़ोल्डर इस मशीन पर तैनात संगठन की नीतियों को रखती है — + खोज उप-निर्देशिकाओं में नहीं जाती है, इसलिए इसे कभी स्कैन नहीं किया जाता है, और + `policies/` में जो कुछ भी आप डालते हैं वह इससे टकरा नहीं सकता। + + यदि आप ऐसे संस्करण से अपग्रेड कर रहे हैं जो `~/.failproofai/policies/custom-policies/` + का उपयोग करता था, उस फ़ोल्डर में सब कुछ — आपकी नीति फ़ाइलें, कोई भी + `lib/` जो वे आयात करते हैं, और कोई डेटा फ़ाइलें वे पढ़ते हैं — स्वचालित रूप से + पहली बार जब आप कोई `failproofai` कमांड चलाते हैं तो पीछे स्थानांतरित की जाती है, + और कमांड आपको बताता है कि इसने क्या स्थानांतरित किया। -**फ़ाइल मिलान:** केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फ़ाइलें लोड की जाती हैं (उदाहरण के लिए `security-policies.mjs`, `workflow-policies.js`)। निर्देशिका में अन्य फ़ाइलों को अनदेखा किया जाता है। +**फ़ाइल मिलान:** केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फ़ाइलें लोड की जाती हैं (उदाहरण के लिए `security-policies.mjs`, `workflow-policies.js`)। निर्देशिका में अन्य फ़ाइलें अनदेखी की जाती हैं। -**कोई कॉन्फ़िग की आवश्यकता नहीं:** परंपरा नीतियों को `policies-config.json` में कोई प्रविष्टियां नहीं चाहिए। बस निर्देशिका में फ़ाइलें छोड़ें और वे अगली हुक इवेंट पर उठाई जाएंगी। +**कोई कॉन्फ़िगरेशन आवश्यक नहीं:** कन्वेंशन नीतियों को `policies-config.json` में कोई प्रविष्टि की आवश्यकता नहीं है। बस फ़ाइलों को निर्देशिका में डालें और वे अगले हुक इवेंट पर उठाई जाती हैं। -**यूनियन लोडिंग:** प्रोजेक्ट और उपयोगकर्ता दोनों परंपरा निर्देशिकाओं को स्कैन किया जाता है। दोनों स्तरों से सभी मेल खाने वाली फ़ाइलें लोड की जाती हैं (`customPoliciesPath` के विपरीत जो पहले-स्कोप-जीत का उपयोग करता है)। +**यूनियन लोडिंग:** प्रोजेक्ट और उपयोगकर्ता दोनों कन्वेंशन निर्देशिकाओं को स्कैन किया जाता है। दोनों स्तरों से सभी मेल खाने वाली फ़ाइलें लोड की जाती हैं (`customPoliciesPath` के विपरीत जो पहले-स्कोप-जीतता-है का उपयोग करता है)। अधिक विवरण और उदाहरणों के लिए [Custom Policies](/hi/custom-policies) देखें। ### `llm` -प्रकार: `object` (वैकल्पिक) +प्रकार: `object` (optional) -AI कॉल करने वाली नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन। अधिकांश सेटअप के लिए आवश्यक नहीं है। +नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन जो AI कॉल करती हैं। अधिकांश सेटअप के लिए आवश्यक नहीं है। ```json { @@ -193,26 +203,26 @@ AI कॉल करने वाली नीतियों के लिए LL --- -## CLI से कॉन्फ़िगरेशन प्रबंधित करना +## CLI से कॉन्फ़िगरेशन का प्रबंधन -`policies --install` और `policies --uninstall` कमांड आपके एजेंट CLI की हुक सेटिंग्स फ़ाइल (हुक एंट्री पॉइंट) में लिखते हैं, जबकि `policies-config.json` वह फ़ाइल है जिसे आप सीधे प्रबंधित करते हैं। दोनों अलग हैं: +`policies --install` और `policies --uninstall` कमांड आपके एजेंट CLI की हुक सेटिंग्स फ़ाइल (हुक प्रवेश बिंदु) में लिखते हैं, जबकि `policies-config.json` वह फ़ाइल है जिसे आप सीधे प्रबंधित करते हैं। दोनों अलग हैं: -- **एजेंट CLI सेटिंग्स** — एजेंट को प्रत्येक टूल उपयोग पर `failproofai --hook ` कॉल करने के लिए कहता है: - - **Claude Code**: `~/.claude/settings.json` (उपयोगकर्ता), `/.claude/settings.json` (प्रोजेक्ट), `/.claude/settings.local.json` (स्थानीय) - - **OpenAI Codex**: `~/.codex/hooks.json` (उपयोगकर्ता), `/.codex/hooks.json` (प्रोजेक्ट) — Codex के पास कोई `local` स्कोप नहीं है - - **GitHub Copilot CLI _(बीटा)_**: `~/.copilot/hooks/failproofai.json` (उपयोगकर्ता), `/.github/hooks/failproofai.json` (प्रोजेक्ट) — Copilot के पास कोई `local` स्कोप नहीं है। हुक प्रविष्टियां Copilot के OS-कुंजीबद्ध `bash`/`powershell` कमांड फ़ील्ड का उपयोग करती हैं जिसमें `timeoutSec` है; फ़ाइल शीर्ष-स्तर `version: 1` मार्कर रखती है। Copilot CLI समर्थन **बीटा** है क्योंकि हम `events.jsonl` रिकॉर्ड स्कीमा (जिसे सार्वजनिक दस्तावेज़ निर्दिष्ट नहीं करते हैं) को अधिक वास्तविक-दुनिया सत्रों के विरुद्ध सत्यापित करते हैं। **VS Code Copilot Chat एजेंट मोड (प्रिव्यू)** `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, और `~/.claude/settings.json` (जो `chat.hookFilesLocations` सेटिंग द्वारा नियंत्रित है) से हुक कॉन्फ़िग पढ़ता है जो समान Claude-आकार `{hookSpecificOutput:{permissionDecision:"deny",…}}` अनुबंध का उपयोग करता है — बिल्कुल वे पथ जो `copilot` इंटीग्रेशन और `claude` इंटीग्रेशन (`~/.claude/settings.json`) पहले से लिखते हैं, इसलिए `failproofai policies --install --cli copilot` (या `--cli claude`) **अलग `vscode` इंटीग्रेशन की आवश्यकता के बिना VS Code एजेंट मोड में पहले से लागू होता है** (VS Code की खोज लॉग से लाइव पुष्टि)। - - **Cursor Agent _(बीटा)_**: `~/.cursor/hooks.json` (उपयोगकर्ता), `/.cursor/hooks.json` (प्रोजेक्ट) — Cursor के पास कोई `local` स्कोप नहीं है। हुक प्रविष्टियां Claude-आकार `{type, command, timeout}` रूप का उपयोग करती हैं (`bash`/`powershell` विभाजन नहीं), लेकिन Cursor की [hooks schema](https://cursor.com/docs/hooks) के अनुसार एक समतल सरणी में camelCase इवेंट कुंजियों (`preToolUse`, `beforeSubmitPrompt`, …) के तहत संग्रहीत होती हैं; फ़ाइल शीर्ष-स्तर `version: 1` मार्कर रखती है। हैंडलर `CURSOR_EVENT_MAP` के माध्यम से camelCase → PascalCase को विहित करता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित फायरिंग करें। Cursor Agent समर्थन **बीटा** है जबकि हम Cursor के डिस्क-पर प्रतिलेख प्रारूप (सार्वजनिक दस्तावेज़ में निर्दिष्ट नहीं) को अधिक वास्तविक-दुनिया इंस्टॉल के विरुद्ध सत्यापित करते हैं। - - **OpenCode _(बीटा)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (उपयोगकर्ता), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (प्रोजेक्ट) — OpenCode के पास कोई `local` स्कोप नहीं है। अन्य पाँच CLI के विपरीत, OpenCode के पास **कोई बाहरी-कमांड हुक सिस्टम नहीं है**: यह `opencode.json` में `plugin: []` सरणी के माध्यम से स्पष्ट रूप से पंजीकृत इन-प्रोसेस JS/TS प्लगइन लोड करता है (`.opencode/plugins/` से स्वचालित-खोज यह नहीं है कि opencode v1.14.33 पर प्लगइन कैसे लोड होते हैं)। इंस्टॉल एक छोटी उत्पन्न प्लगइन शिम छोड़ता है जो failproofai बाइनरी को सबप्रोसेस-कॉल करता है और बाइनरी के Claude-shape JSON प्रतिक्रिया को प्लगइन सिमेंटिक्स में वापस अनुवाद करता है: टूल-इवेंट deny के लिए `throw new Error()` (टूल कॉल रद्द करता है), `client.session.prompt(...)` instruct और `Stop` / `SubagentStop` deny के लिए (deny कारण को अगली उपयोगकर्ता संदेश के रूप में जमा करता है — एकमात्र बल-पुनः प्रयास चैनल चूंकि `session.idle` केवल-अधिसूचना है और इससे फेंकना एक नो-ऑप है), और allow के लिए नो-ऑप। शिम `OPENCODE_TOOL_MAP` के माध्यम से दोनों टूल नामों (लोअरकेस → PascalCase) और टूल-इनपुट arg कुंजियों (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` for `Read` / `Write` / `Edit`, e.g. `filePath` → `file_path`, `oldString` → `old_string`) को बाइनरी में अग्रेषित करने से पहले विहित करता है, इसलिए पथ-जांच builtins जैसे `block-read-outside-cwd`, `block-env-files`, और `block-secrets-write` OpenCode टूल कॉल पर अपरिवर्तित फायरिंग करते हैं। सत्र `~/.local/share/opencode/opencode.db` पर opencode के SQLite DB में रहते हैं; डैशबोर्ड का सत्र व्यूअर `opencode db --format json` और `opencode export ` के माध्यम से उन्हें पढ़ता है। OpenCode समर्थन **बीटा** है जबकि हम संस्करणों के पार व्यवहार सत्यापित करते हैं और अधिक वास्तविक-दुनिया सत्रों के विरुद्ध। [OpenCode plugins docs](https://opencode.ai/docs/plugins/) देखें। - - **Pi _(बीटा)_**: `~/.pi/agent/settings.json` (उपयोगकर्ता), `/.pi/settings.json` (प्रोजेक्ट) — Pi के पास कोई `local` स्कोप नहीं है। Pi स्टार्टअप पर TypeScript एक्सटेंशन पैकेज लोड करता है; सेटिंग्स फ़ाइल एक समतल स्ट्रिंग सरणी `{"packages": ["./relative/path", …]}` है। failproofai एक एकल packages-array प्रविष्टि लिखता है जो अपनी bundled `pi-extension/` निर्देशिका की ओर इशारा करती है। एक्सटेंशन आंतरिक रूप से Pi के `tool_call` / `user_bash` / `input` / `session_start` इवेंट्स को सबस्क्राइब करता है और `failproofai --hook --cli pi` को शेल आउट करता है; हैंडलर `PI_EVENT_MAP` के माध्यम से underscore_lower_snake_case → PascalCase को विहित करता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित फायरिंग करें। टूल इनपुट args को भी `PI_TOOL_INPUT_MAP` के माध्यम से विहित किया जाता है (Pi के Read / Write / Edit `file_path` के बजाय `path` प्रदान करते हैं; शीर्ष-स्तरीय कुंजी को मैप करने देता है `block-env-files` और `block-secrets-write` आग — `block-read-outside-cwd` पहले से ही `path` fallback था)। Pi समर्थन **बीटा** है जबकि Pi का एक्सटेंशन API और सत्र-लॉग लेआउट स्थिर होता है। - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**केवल उपयोगकर्ता स्कोप** — Hermes के पास कोई project/local कॉन्फ़िग नहीं है)। Hermes एक Slack/Telegram **गेटवे** है, इसलिए एक इंस्टॉल हर प्लेटफॉर्म से टूल कॉल को रोकता है (Slack/Telegram/cli/cron) **और** आंतरिक subagents। हुक प्रविष्टियां Hermes के snake_case इवेंट्स (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) द्वारा कुंजीबद्ध `hooks:` मानचित्र के तहत एक `{command, timeout}` जोड़ी हैं; हैंडलर `HERMES_EVENT_MAP` के माध्यम से इवेंट्स को विहित करता है और `HERMES_TOOL_MAP` के माध्यम से टूल नाम करता है ताकि बिल्ट-इन नीतियां अपरिवर्तित फायरिंग करें। कॉन्फ़िग को comment-preserving YAML `Document` round-trip के माध्यम से संपादित किया जाता है ताकि ऑपरेटर की अन्य सेटिंग्स जीवित रहें, और इंस्टॉल `hooks_auto_accept: true` सेट करता है ताकि headless गेटवे (कोई TTY) सहमति संकेत के बिना हुक चलाए। evaluator Hermes के `{"decision":"block","reason"}` stdout अनुबंध का उत्सर्जन करता है (Hermes exit codes को अनदेखा करता है)। **सीमाएं:** Hermes के पास कोई turn-end `Stop` इवेंट नहीं है, इसलिए `require-*-before-stop` builtins इसके लिए कभी नहीं फायरिंग करते हैं (inapplicable, broken नहीं); `instruct` allow-with-logged-note तक degraded होता है (कोई अतिरिक्त-context चैनल नहीं); और output-secret redaction (`sanitize-*`) shell-hook अनुबंध पर टूल आउटपुट को फिर से नहीं लिख सकते। Hermes है **साथ ही** एक offline **audit** स्रोत — डैशबोर्ड `~/.hermes/state.db` से अपने गेटवे सत्र सीधे पढ़ता है। - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**केवल उपयोगकर्ता स्कोप** — OpenClaw के पास कोई project/local कॉन्फ़िग नहीं है)। Hermes की तरह, OpenClaw एक self-hosted multi-channel **गेटवे** है, इसलिए एक इंस्टॉल हर चैनल और इसके आंतरिक subagents से टूल कॉल को रोकता है। Enforcement OpenClaw के **in-process plugin hooks** के माध्यम से चलता है (इसकी file-based आंतरिक हुक केवल observation हैं और ब्लॉक नहीं कर सकते), इसलिए — OpenCode/Pi की तरह — failproofai एक स्थिर `openclaw-plugin/` पैकेज शिप करता है जो failproofai बाइनरी को async-spawn करता है और निर्णय का अनुवाद करता है। इंस्टॉल `openclaw.json` के `plugins.load.paths[]` में shipped plugin dir को रजिस्टर करता है और इसे `plugins.entries.failproofai` के तहत सक्षम करता है (`hooks.allowConversationAccess: true` के साथ, कच्चे-conversation हुक के लिए आवश्यक)। evaluator एक समतल `{permission, reason}` निर्णय का उत्सर्जन करता है और शिम इसे प्रत्येक हुक के देशी रिटर्न shape में मैप करता है: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), और `before_agent_finalize → {action:"revise", reason}` (**Stop** — एक real turn-end gate, इसलिए `require-*-before-stop` builtins **लागू** OpenClaw पर होते हैं, Hermes के विपरीत)। इवेंट्स और टूल नाम `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` के माध्यम से binary-side को विहित करते हैं (`exec→Bash`, `read→Read`, …) ताकि बिल्ट-इन नीतियां अपरिवर्तित फायरिंग करें; शिम किसी भी spawn/parse/timeout त्रुटि पर खुलकर विफल हो जाता है। OpenClaw है **साथ ही** एक offline **audit** स्रोत — डैशबोर्ड `~/.openclaw/agents//sessions/.jsonl` पर अपने JSONL सत्र पढ़ता है। - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (उपयोगकर्ता), `/.factory/hooks.json` (प्रोजेक्ट) — Factory के पास कोई `local` स्कोप नहीं है। droid एक Claude-style बाहरी-कमांड हुक सिस्टम शिप करता है, लेकिन droid v0.171.0 के विरुद्ध लाइव सत्यापित दो quirks के साथ: (1) इवेंट नाम `hooks.json` के **शीर्ष स्तर** पर रहते हैं — कोई **`"hooks"` wrapper नहीं है** (droid एक को अस्वीकार करता है); टूल इवेंट्स (`PreToolUse`/`PostToolUse`) `"matcher": "*"` ले जाते हैं, गैर-टूल इवेंट्स इसे छोड़ते हैं। (2) Deny हुक **exit code 2 + stderr** द्वारा संचालित होता है, JSON निर्णय नहीं — evaluator की `factory` branch टूल/prompt इवेंट्स के लिए exit 2 लौटाता है और turn-end `Stop` इवेंट पर केवल `{decision:"block", reason}` (droid का एकमात्र बल-पुनः प्रयास चैनल)। इवेंट्स पहले से ही PascalCase हैं (कोई इवेंट मैप नहीं) और payload Claude snake_case है; केवल टूल नाम `FACTORY_TOOL_MAP` के माध्यम से विहित होते हैं (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …)। Factory है **साथ ही** एक offline **audit** स्रोत — डैशबोर्ड `~/.factory/sessions//.jsonl` पर अपने on-disk JSONL सत्र पढ़ता है। - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (उपयोगकर्ता), `/.devin/config.json` (प्रोजेक्ट) — Devin के पास कोई `local` स्कोप नहीं है। Devin एक **pure Claude-clone** है devin v3000.1.27 के विरुद्ध लाइव सत्यापित: यह standard Claude `"hooks"`-wrapper schema का उपयोग करता है (लिखना merge-preserving है ताकि कॉन्फ़िग फ़ाइल की अन्य कुंजियां — `org_id`, `theme_mode`, … — जीवित रहें), पहले से ही-PascalCase इवेंट नाम (कोई इवेंट मैप नहीं, कोई हैंडलर शाखा नहीं), और एक Claude snake_case stdin payload (कोई normalization नहीं)। evaluator की `devin` branch **हर** इवेंट के लिए exit 0 पर `{"decision":"block","reason"}` JSON के साथ अस्वीकार करता है (सत्यापित — block ने `--permission-mode dangerous` को override किया); turn-end `Stop` इवेंट पर कारण MANDATORY-ACTION बल-पुनः प्रयास शब्दांकन रखता है ताकि `require-*-before-stop` builtins लागू करें। केवल टूल नाम `DEVIN_TOOL_MAP` के माध्यम से विहित होते हैं (`exec→Bash`; `tool_input.command` पहले से ही canonical है)। Devin है **साथ ही** एक offline **audit** स्रोत — डैशबोर्ड `~/.local/share/devin/cli/sessions.db` पर अपने SQLite सत्र पढ़ता है (प्रत्येक `sessions` row एक real `working_directory` रखता है, इसलिए सत्र प्रोजेक्ट cwd द्वारा Claude की तरह समूह करते हैं)। - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (उपयोगकर्ता), `/.agents/hooks.json` (प्रोजेक्ट) — Antigravity के पास कोई `local` स्कोप नहीं है। Factory/Devin के विपरीत, Antigravity के पास अपना **ही** अनुबंध है (Claude-clone नहीं), agy v1.1.2 के विरुद्ध लाइव सत्यापित। `hooks.json` एक **named-hook** schema का उपयोग करता है: शीर्ष-स्तरीय कुंजी एक हुक *नाम* (`"failproofai"`) है जिसका मूल्य एक इवेंट→handlers मैप है — टूल इवेंट्स (`PreToolUse`/`PostToolUse`) handlers को `{matcher:"*", hooks:[…]}` में लपेटते हैं, जबकि `PreInvocation`/`Stop` **flat** handler arrays हैं (अन्य named हुक संरक्षित हैं)। stdin payload **camelCase protojson** है (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai इसे नीतियां चलाने से पहले snake_case में normalize करता है, और `ANTIGRAVITY_TOOL_INPUT_MAP` के माध्यम से `run_command` के PascalCase args (`CommandLine`/`Cwd`) को मैप करता है। evaluator की `antigravity` branch Antigravity के **ही** प्रतिक्रिया shapes का उपयोग करता है: `{decision:"deny", reason}` एक टूल/prompt को ब्लॉक करता है (exit 0), `{decision:"continue", reason}` turn-end `Stop` पर लूप को फिर से दर्ज करता है (इसलिए `require-*-before-stop` builtins लागू), और `{injectSteps:[{ephemeralMessage}]}` `PreInvocation` पर एक निर्देश को inject करता है (→ `UserPromptSubmit`)। टूल नाम `ANTIGRAVITY_TOOL_MAP` के माध्यम से विहित करते हैं (`run_command→Bash`, `view_file→Read`, …)। Antigravity है **साथ ही** एक offline **audit** स्रोत — डैशबोर्ड `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` पर अपने plain-JSONL transcripts पढ़ता है (conversation index `conversation_summaries.db` में)। - - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (उपयोगकर्ता), `/.agents/plugins/failproofai/hooks/hooks.json` (प्रोजेक्ट) — Goose के पास कोई `local` स्कोप नहीं है। Enforcement Goose के **hooks** सिस्टम का उपयोग करता है, cross-agent **Open Plugins** spec: installer बस `failproofai` plugin dir छोड़ता है और Goose startup पर इसे auto-discover करता है (इसे `~/.config/goose/config.yaml` में self-register करता है)। `hooks.json` एक Open Plugins schema का उपयोग करता है **with** एक शीर्ष-स्तरीय `"hooks"` wrapper, और matcher हर इवेंट पर **omitted** होता है — एक bare `"*"` एक invalid regex है जो कुछ नहीं मेल खाता (goose v1.43.0 के विरुद्ध लाइव सत्यापित)। इवेंट नाम पहले से ही PascalCase हैं (कोई इवेंट मैप नहीं); stdin payload `event`/`working_dir` का उपयोग करता है, जिसे हैंडलर `hook_event_name`/`cwd` में normalize करता है। evaluator की `goose` branch exit 0 पर `{"decision":"block","reason"}` JSON के साथ अस्वीकार करता है, **`PreToolUse`** इवेंट पर honor किया जाता है केवल (goose ≥ v1.37.0 में shipped) — जो shell tool **और inside delegated subagents** के लिए fires, इसलिए यह एकल पर्याप्त अस्वीकार बिंदु है; कोई अन्य हुक त्रुटि **खुलकर** विफल हो जाता है। Goose के पास **कोई `Stop` इवेंट नहीं है**, इसलिए `require-*-before-stop` builtins apply नहीं करते हैं (Hermes की तरह)। टूल नाम `GOOSE_TOOL_MAP` के माध्यम से विहित होते हैं (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) और पथ कुंजियां `GOOSE_TOOL_INPUT_MAP` के माध्यम से (`path`/`source` → `file_path`)। Goose है **साथ ही** एक offline **audit** स्रोत — डैशबोर्ड `~/.local/share/goose/sessions/sessions.db` पर अपने SQLite सत्र पढ़ता है (प्रत्येक `sessions` row एक real `working_dir` रखता है, इसलिए सत्र प्रोजेक्ट cwd द्वारा Devin की तरह समूह करते हैं; `--no-session` scratch runs फ़िल्टर किए जाते हैं)। -- **`policies-config.json`** — failproofai को बताता है कि कौन सी नीतियों का मूल्यांकन करना है और किन params के साथ (सभी एजेंट CLI के पार साझा) +- **एजेंट CLI सेटिंग्स** — एजेंट को प्रत्येक टूल उपयोग पर `failproofai --hook ` कॉल करने के लिए बताता है: + - **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) + - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex के पास `local` स्कोप नहीं है + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot के पास `local` स्कोप नहीं है। हुक प्रविष्टियां Copilot के OS-keyed `bash`/`powershell` कमांड फ़ील्ड का उपयोग करती हैं जिसमें `timeoutSec`; फ़ाइल एक शीर्ष-स्तरीय `version: 1` मार्कर रखती है। Copilot CLI सपोर्ट **beta** है जबकि हम `events.jsonl` रिकॉर्ड स्कीमा को सत्यापित करते हैं (जिसे सार्वजनिक डॉक्स निर्दिष्ट नहीं करते) अधिक वास्तविक-दुनिया सत्रों के विरुद्ध। **VS Code Copilot Chat एजेंट मोड (Preview)** `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, और `~/.claude/settings.json` से हुक कॉन्फ़िग्स पढ़ता है (`chat.hookFilesLocations` सेटिंग द्वारा शासित) उसी Claude-shaped `{hookSpecificOutput:{permissionDecision:"deny",…}}` अनुबंध का उपयोग करते हुए — वह सटीक पथ जो `copilot` एकीकरण और `claude` एकीकरण (`~/.claude/settings.json`) पहले से लिखते हैं, तो `failproofai policies --install --cli copilot` (या `--cli claude`) **पहले से ही VS Code एजेंट मोड में लागू करता है** कोई अलग `vscode` एकीकरण की आवश्यकता नहीं के साथ (VS Code की खोज लॉग से लाइव पुष्टि की गई)। + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor के पास `local` स्कोप नहीं है। हुक प्रविष्टियां Claude-shaped `{type, command, timeout}` फॉर्म का उपयोग करती हैं (कोई `bash`/`powershell` विभाजन नहीं), लेकिन Cursor की [hooks schema](https://cursor.com/docs/hooks) के अनुसार camelCase इवेंट कुंजियों (`preToolUse`, `beforeSubmitPrompt`, …) के तहत एक फ्लैट सरणी में संग्रहीत; फ़ाइल एक शीर्ष-स्तरीय `version: 1` मार्कर रखती है। हैंडलर camelCase → PascalCase को `CURSOR_EVENT_MAP` के माध्यम से कैनोनिकलाइज़ करता है ताकि मौजूदा निर्मित-में नीतियां अपरिवर्तित रहें। Cursor Agent सपोर्ट **beta** है जबकि हम Cursor के ट्रांसक्रिप्ट ऑन-डिस्क फॉर्मेट को सत्यापित करते हैं (सार्वजनिक डॉक्स में निर्दिष्ट नहीं) अधिक वास्तविक-दुनिया इंस्टॉल के विरुद्ध। + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode के पास `local` स्कोप नहीं है। अन्य पांच CLIs के विपरीत, OpenCode के पास **कोई बाहरी-कमांड हुक सिस्टम नहीं है**: यह `opencode.json` में `plugin: []` सरणी के माध्यम से स्पष्ट रूप से पंजीकृत in-process JS/TS प्लगइन लोड करता है (`.opencode/plugins/` से auto-discovery **नहीं** है कि कैसे प्लगइन opencode v1.14.33 पर लोड होते हैं)। इंस्टॉल एक छोटा जनित प्लगइन शिम को गिराता है जो failproofai बाइनरी को subprocess-कॉल करता है और बाइनरी के Claude-shape JSON प्रतिक्रिया को प्लगइन शब्दार्थ में वापस अनुवाद करता है: tool-event deny के लिए `throw new Error()` (टूल कॉल को रद्द करता है), `instruct` AND के लिए `client.session.prompt(...)` `Stop` / `SubagentStop` deny (अगले उपयोगकर्ता संदेश के रूप में डेनी कारण को सबमिट करता है — एकमात्र force-retry चैनल क्योंकि `session.idle` केवल-सूचना है और इससे थ्रो करना एक no-op है), और allow के लिए no-op। शिम दोनों टूल नामों (lowercase → PascalCase via `OPENCODE_TOOL_MAP`) और टूल-इनपुट arg कुंजियों (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` के लिए `Read` / `Write` / `Edit`, उदा. `filePath` → `file_path`, `oldString` → `old_string`) को कैनोनिकलाइज़ करता है बाइनरी को फॉरवर्ड करने से पहले, ताकि पथ-जांच बिल्ट-इन जैसे `block-read-outside-cwd`, `block-env-files`, और `block-secrets-write` OpenCode टूल कॉल पर अपरिवर्तित रहें। सत्र `~/.local/share/opencode/opencode.db` में opencode के SQLite DB में रहते हैं; डैशबोर्ड के सत्र दर्शक उन्हें `opencode db --format json` और `opencode export ` के माध्यम से पढ़ते हैं। OpenCode सपोर्ट **beta** है जबकि हम संस्करणों में व्यवहार को सत्यापित करते हैं और अधिक वास्तविक-दुनिया सत्रों के विरुद्ध। [OpenCode plugins docs](https://opencode.ai/docs/plugins/) देखें। + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi के पास `local` स्कोप नहीं है। Pi स्टार्टअप पर TypeScript एक्सटेंशन पैकेज लोड करता है; सेटिंग्स फ़ाइल एक फ्लैट स्ट्रिंग सरणी `{"packages": ["./relative/path", …]}` है। failproofai एक एकल packages-array एंट्री लिखता है जो अपनी bundled `pi-extension/` निर्देशिका की ओर इशारा करती है। एक्सटेंशन आंतरिक रूप से Pi के `tool_call` / `user_bash` / `input` / `session_start` इवेंट्स को सबस्क्राइब करता है और `failproofai --hook --cli pi` को शेल आउट करता है; हैंडलर underscore_lower_snake_case → PascalCase को `PI_EVENT_MAP` के माध्यम से कैनोनिकलाइज़ करता है ताकि मौजूदा निर्मित-में नीतियां अपरिवर्तित रहें। टूल इनपुट args को `PI_TOOL_INPUT_MAP` के माध्यम से भी कैनोनिकलाइज़ किया जाता है (Pi का Read / Write / Edit `file_path` के बजाय `path` प्रदान करते हैं; शीर्ष-स्तरीय कुंजी को मैप करना `block-env-files` और `block-secrets-write` को फायर करने देता है — `block-read-outside-cwd` पहले से ही एक `path` fallback था)। Pi सपोर्ट **beta** है जबकि Pi का एक्सटेंशन API और सत्र-लॉग लेआउट स्थिर होते हैं। + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**केवल user scope** — Hermes के पास project/local कॉन्फ़िगरेशन नहीं है)। Hermes एक Slack/Telegram **गेटवे** है, इसलिए एक इंस्टॉल हर प्लेटफॉर्म (Slack/Telegram/cli/cron) **और** आंतरिक उप-एजेंट से टूल कॉल को इंटरसेप्ट करता है। हुक प्रविष्टियां Hermes के snake_case इवेंट्स द्वारा कुंजीबद्ध एक `hooks:` मैप के तहत एक `{command, timeout}` जोड़ी होती हैं (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); हैंडलर इवेंट्स को `HERMES_EVENT_MAP` के माध्यम से कैनोनिकलाइज़ करता है और टूल नामों को `HERMES_TOOL_MAP` के माध्यम से कैनोनिकलाइज़ करता है ताकि निर्मित-में नीतियां अपरिवर्तित रहें। कॉन्फ़िगरेशन को एक comment-preserving YAML `Document` राउंड-ट्रिप के माध्यम से संपादित किया जाता है ताकि ऑपरेटर की अन्य सेटिंग्स जीवित रहें, और इंस्टॉल `hooks_auto_accept: true` सेट करता है ताकि हेडलेस गेटवे (कोई TTY नहीं) सहमति प्रॉम्प्ट के बिना हुक चलाए। मूल्यांकनकर्ता Hermes के `{"decision":"block","reason"}` stdout अनुबंध को उत्सर्जित करता है (Hermes exit कोड को अनदेखा करता है)। **सीमाएं:** Hermes के पास कोई turn-end `Stop` इवेंट नहीं है, इसलिए `require-*-before-stop` निर्मित-में कभी इसके लिए फायर नहीं होते (अप्रयोज्य, टूटा नहीं); `instruct` allow-with-logged-note में degrade होता है (कोई अतिरिक्त-संदर्भ चैनल नहीं); और आउटपुट-सीक्रेट रीडेक्शन (`sanitize-*`) शेल-हुक अनुबंध पर टूल आउटपुट को पुनः लिखने में सक्षम नहीं है। Hermes **भी** एक ऑफलाइन **audit** स्रोत है — डैशबोर्ड सीधे `~/.hermes/state.db` से अपने गेटवे सत्र पढ़ता है। + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**केवल user scope** — OpenClaw के पास project/local कॉन्फ़िगरेशन नहीं है)। Hermes की तरह, OpenClaw एक self-hosted multi-channel **गेटवे** है, इसलिए एक इंस्टॉल हर चैनल और इसके आंतरिक उप-एजेंट से टूल कॉल को इंटरसेप्ट करता है। प्रवर्तन OpenClaw के **in-process plugin हुक्स** के माध्यम से चलता है (इसकी फ़ाइल-आधारित आंतरिक हुक्स केवल अवलोकन हैं और अवरुद्ध नहीं कर सकते), तो — OpenCode/Pi की तरह — failproofai एक स्थिर `openclaw-plugin/` पैकेज को शिप करता है जो failproofai बाइनरी को async-spawn करता है और वर्डिक्ट को अनुवाद करता है। इंस्टॉल shipped plugin dir को `openclaw.json` के `plugins.load.paths[]` में पंजीकृत करता है और इसे `plugins.entries.failproofai` के तहत सक्षम करता है (`hooks.allowConversationAccess: true` के साथ, कच्चे-संवाद हुक्स के लिए आवश्यक)। मूल्यांकनकर्ता एक फ्लैट `{permission, reason}` वर्डिक्ट उत्सर्जित करता है और शिम इसे प्रत्येक हुक के मूल रिटर्न आकार में मैप करता है: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), और `before_agent_finalize → {action:"revise", reason}` (**Stop** — एक वास्तविक turn-end गेट, इसलिए `require-*-before-stop` निर्मित-में **लागू होते हैं** OpenClaw पर, Hermes के विपरीत)। इवेंट्स और टूल नामों को `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` के माध्यम से binary-side पर कैनोनिकलाइज़ करता है (`exec→Bash`, `read→Read`, …) ताकि निर्मित-में नीतियां अपरिवर्तित रहें; शिम किसी भी spawn/parse/timeout त्रुटि पर open fail करता है। OpenClaw **भी** एक ऑफलाइन **audit** स्रोत है — डैशबोर्ड `~/.openclaw/agents//sessions/.jsonl` में इसके JSONL सत्र पढ़ता है। + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (user), `/.factory/hooks.json` (project) — Factory के पास `local` स्कोप नहीं है। droid एक Claude-style बाहरी-कमांड हुक सिस्टम को शिप करता है, लेकिन दो quirks के साथ droid v0.171.0 के विरुद्ध लाइव सत्यापित: (1) इवेंट नाम `hooks.json` के **शीर्ष स्तर** पर रहते हैं — कोई **`"hooks"` रैपर नहीं** है (droid एक को अस्वीकार करता है); टूल इवेंट्स (`PreToolUse`/`PostToolUse`) `"matcher": "*"` रखते हैं, non-tool इवेंट्स इसे छोड़ते हैं। (2) Deny हुक **exit code 2 + stderr** द्वारा चलाया जाता है, JSON निर्णय नहीं — मूल्यांकनकर्ता की `factory` शाखा टूल/प्रॉम्प्ट इवेंट्स के लिए exit 2 रिटर्न करती है और turn-end `Stop` इवेंट पर `{decision:"block", reason}` केवल (droid का एकमात्र force-retry चैनल)। इवेंट पहले से ही PascalCase हैं (कोई इवेंट मैप नहीं) और पेलोड Claude snake_case है; केवल टूल नामों को `FACTORY_TOOL_MAP` के माध्यम से कैनोनिकलाइज़ किया जाता है (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …)। Factory **भी** एक ऑफलाइन **audit** स्रोत है — डैशबोर्ड `~/.factory/sessions//.jsonl` में इसके on-disk JSONL सत्र पढ़ता है। + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (user), `/.devin/config.json` (project) — Devin के पास `local` स्कोप नहीं है। Devin एक **pure Claude-clone** है devin v3000.1.27 के विरुद्ध लाइव सत्यापित: यह मानक Claude `"hooks"` रैपर स्कीमा का उपयोग करता है (लिखना merge-preserving है ताकि कॉन्फ़िग फ़ाइल की अन्य कुंजियां — `org_id`, `theme_mode`, … — जीवित रहें), पहले से ही-PascalCase इवेंट नाम (कोई इवेंट मैप नहीं, कोई हैंडलर शाखा नहीं), और एक Claude snake_case stdin पेलोड (कोई सामान्यीकरण नहीं)। मूल्यांकनकर्ता की `devin` शाखा exit 0 पर stdout पर **हर** इवेंट के लिए `{"decision":"block","reason"}` JSON के साथ अस्वीकार करती है (**सत्यापित** — ब्लॉक ने `--permission-mode dangerous` को ओवरराइड किया); turn-end `Stop` इवेंट पर कारण MANDATORY-ACTION force-retry शब्दार्थ रखता है ताकि `require-*-before-stop` निर्मित-में लागू होते हैं। केवल टूल नामों को `DEVIN_TOOL_MAP` के माध्यम से कैनोनिकलाइज़ किया जाता है (`exec→Bash`; `tool_input.command` पहले से ही canonical है)। Devin **भी** एक ऑफलाइन **audit** स्रोत है — डैशबोर्ड `~/.local/share/devin/cli/sessions.db` में इसके SQLite सत्र पढ़ता है (प्रत्येक `sessions` पंक्ति एक वास्तविक `working_directory` रखती है, इसलिए सत्र project cwd की तरह समूह)। + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (user), `/.agents/hooks.json` (project) — Antigravity के पास `local` स्कोप नहीं है। Factory/Devin के विपरीत, Antigravity का **अपना** अनुबंध है (Claude-clone नहीं), agy v1.1.2 के विरुद्ध लाइव सत्यापित। `hooks.json` एक **named-hook** स्कीमा का उपयोग करता है: शीर्ष-स्तर की कुंजी एक हुक *नाम* है (`"failproofai"`) जिसका मान एक इवेंट→handlers मैप है — टूल इवेंट्स (`PreToolUse`/`PostToolUse`) handlers को `{matcher:"*", hooks:[…]}` में लपेटते हैं, जबकि `PreInvocation`/`Stop` **फ्लैट** handler सरणियां हैं (अन्य named हुक्स संरक्षित हैं)। stdin पेलोड **camelCase protojson** है (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai इसे snake_case में सामान्यीकृत करता है नीतियों को चलाने से पहले, और `run_command` के PascalCase args को (`CommandLine`/`Cwd`) `ANTIGRAVITY_TOOL_INPUT_MAP` के माध्यम से मैप करता है। मूल्यांकनकर्ता की `antigravity` शाखा Antigravity के **अपने** प्रतिक्रिया आकार का उपयोग करती है: `{decision:"deny", reason}` एक टूल/प्रॉम्प्ट को अवरुद्ध करता है (exit 0), `{decision:"continue", reason}` turn-end `Stop` पर लूप को पुनः प्रवेश करता है (इसलिए `require-*-before-stop` निर्मित-में लागू होते हैं), और `{injectSteps:[{ephemeralMessage}]}` `PreInvocation` पर एक निर्देश इंजेक्ट करता है (→ `UserPromptSubmit`)। टूल नामों को `ANTIGRAVITY_TOOL_MAP` के माध्यम से कैनोनिकलाइज़ किया जाता है (`run_command→Bash`, `view_file→Read`, …)। Antigravity **भी** एक ऑफलाइन **audit** स्रोत है — डैशबोर्ड `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` में इसके plain-JSONL ट्रांसक्रिप्ट पढ़ता है (conversation index `conversation_summaries.db` में)। + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (user), `/.agents/plugins/failproofai/hooks/hooks.json` (project) — Goose के पास `local` स्कोप नहीं है। प्रवर्तन Goose के **हुक्स** सिस्टम का उपयोग करता है, cross-agent **Open Plugins** spec: इंस्टॉलर केवल `failproofai` plugin dir को गिराता है और Goose स्टार्टअप पर इसे auto-discover करता है (self-registering करता है `~/.config/goose/config.yaml` में)। `hooks.json` एक Open Plugins स्कीमा का उपयोग करता है **with** एक शीर्ष-स्तर `"hooks"` रैपर, और matcher **हर इवेंट पर omitted** होता है — एक bare `"*"` एक अमान्य regex है जो कुछ भी मेल नहीं खाता (goose v1.43.0 के विरुद्ध लाइव सत्यापित)। इवेंट नाम पहले से ही PascalCase हैं (कोई इवेंट मैप नहीं); stdin पेलोड `event`/`working_dir` का उपयोग करता है, जिसे हैंडलर `hook_event_name`/`cwd` को सामान्यीकृत करता है। मूल्यांकनकर्ता की `goose` शाखा exit 0 पर stdout पर `{"decision":"block","reason"}` JSON के साथ अस्वीकार करती है, **`PreToolUse`** इवेंट पर सम्मानित होता है केवल (goose ≥ v1.37.0 में शिप किया गया) — जो शेल टूल के लिए फायर करता है **और delegated उप-एजेंट के भीतर**, इसलिए यह एकमात्र पर्याप्त अस्वीकार बिंदु है; कोई भी अन्य हुक त्रुटि **open** fail करता है। Goose के पास **कोई `Stop` इवेंट** नहीं है, इसलिए `require-*-before-stop` निर्मित-में लागू नहीं होते (Hermes की तरह)। टूल नामों को `GOOSE_TOOL_MAP` के माध्यम से कैनोनिकलाइज़ किया जाता है (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) और path कुंजियों को `GOOSE_TOOL_INPUT_MAP` के माध्यम से (`path`/`source` → `file_path`)। Goose **भी** एक ऑफलाइन **audit** स्रोत है — डैशबोर्ड `~/.local/share/goose/sessions/sessions.db` में इसके SQLite सत्र पढ़ता है (प्रत्येक `sessions` पंक्ति एक वास्तविक `working_dir` रखती है, इसलिए सत्र Devin की तरह project cwd द्वारा समूह; `--no-session` scratch runs फ़िल्टर किए जाते हैं)। +- **`policies-config.json`** — failproofai को बताता है कि कौन सी नीतियां मूल्यांकित करनी हैं और किन पैरामीटर के साथ (सभी एजेंट CLIs में साझा) -एक विशिष्ट एजेंट को लक्षित करने के लिए `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` पास करें (space-separated या किसी भी सबसेट के लिए repeated): +`--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` को pass करें किसी विशिष्ट एजेंट को लक्ष्य करने के लिए (space-separated या किसी सबसेट के लिए दोहराया गया): ```bash failproofai policies --install --cli codex --scope project @@ -229,18 +239,36 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -जब `--cli` छोड़ा जाता है, तो `failproofai` पहचानता है कि कौन से एजेंट CLI इंस्टॉल किए गए हैं (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +जब `--cli` छोड़ दिया जाता है, `failproofai` पहचानता है कि कौन से एजेंट CLIs इंस्टॉल किए गए हैं (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): + +- **एक CLI पाया गया** — प्रॉम्प्ट किए बिना उस CLI को auto-select करता है। +- **Multiple CLIs detected** एक इंटरैक्टिव टर्मिनल में — एक arrow-key single-select प्रॉम्प्ट दिखाता है एक `Detected (N)` सेक्शन में समूहित (एक `Install for all N detected` aggregate row + प्रत्येक detected CLI अलग से) और एक `Not installed (M) · install hooks ahead of time` सेक्शन हर undetected supported CLI को एक forward-install विकल्प के रूप में सूचीबद्ध करते हुए (↑↓ move के लिए, Enter select के लिए, ^C quit के लिए)। uninstall प्रवाह केवल Detected सेक्शन को दिखाता है। +- **Multiple CLIs detected** एक non-interactive run में (CI, कोई TTY नहीं) — प्रॉम्पट किए बिना सभी detected CLIs के लिए इंस्टॉल करता है। +- **कोई नहीं पाया गया** — `claude` में fallback करता है, एक चेतावनी के साथ कि PATH में कोई एजेंट बाइनरी नहीं मिला; हुक कमांड अभी भी लिखा जाता है इसलिए यह सक्रिय होता है जैसे ही आप एक इंस्टॉल करते हैं। + +आप किसी भी समय `policies-config.json` को सीधे संपादित कर सकते हैं; परिवर्तन अगले हुक इवेंट पर तुरंत प्रभाव डालते हैं कोई पुनरारंभ की आवश्यकता नहीं। + +## अपग्रेड आपकी कॉन्फ़िगरेशन को रखता है + +failproofai का एक नया संस्करण `~/.failproofai/` को अलग तरीके से आयोजित कर सकता है। जब यह होता है, तो अपग्रेड के बाद पहली कमांड निर्देशिका को माइग्रेट करती है, और **आपकी कॉन्फ़िगरेशन को ले जाया जाता है, reset नहीं किया जाता है**: + +| रखा गया | पुनर्निर्मित | +|---|---| +| आपकी नीति चयन और पैरामीटर (`policies-config.json`) | audit cache | +| आपकी सेटिंग्स, `daemon.configured` और अतिरिक्त कैप्चर पथ (`config.json`) सहित | Cloud-managed नीति तैनातियां — अगली poll पर पुनः fetched और digest-verified | +| आपका cloud enrolment (`credentials.json`) | Daemon scratch state | +| `policies/` में आपकी अपनी नीति फ़ाइलें, और helpers जो वे import करते हैं | | +| decision log जो डैशबोर्ड पढ़ता है, और events अभी तक delivered नहीं | | + +एक *नए* failproofai द्वारा लिखी गई कुंजियां भी संरक्षित की जाती हैं, बजाय एक पुरानी पाठक द्वारा dropped किए जाने के — इसलिए versions के बीच जाना दोनों दिशाओं में silently settings को discard नहीं करता। -- **एक CLI detected** — उस CLI को बिना prompt के auto-select करता है। -- **Multiple CLIs detected** एक interactive terminal में — एक arrow-key single-select prompt दिखाता है एक `Detected (N)` सेक्शन में grouped (एक `Install for all N detected` aggregate row + प्रत्येक detected CLI individually के साथ) और एक `Not installed (M) · install hooks ahead of time` सेक्शन हर undetected supported CLI को एक forward-install option के रूप में सूचीबद्ध करता है (↑↓ चलने के लिए, Enter select करने के लिए, ^C quit करने के लिए)। uninstall flow केवल Detected सेक्शन दिखाता है। -- **Multiple CLIs detected** एक non-interactive run में (CI, कोई TTY) — बिना prompt के सभी detected CLI के लिए इंस्टॉल करता है। -- **None detected** — `claude` को fallback करता है, एक warning के साथ कि कोई एजेंट बाइनरी PATH में नहीं मिला; हुक कमांड अभी भी लिखा जाता है ताकि यह सक्रिय हो जाता है जैसे ही आप एक इंस्टॉल करते हैं। +आपको बाद में सेटअप को पुनः run करने की आवश्यकता **नहीं** है: एक migrated मशीन बिल्कुल उसी तरह लागू करती है जैसे पहले, जो एक अपग्रेड को machines पर सुरक्षित बनाता है जहां कोई उनके पास बैठा नहीं है। प्रत्येक migration `~/.failproofai/migrations/applied.json` में recorded है, और अपरिहार्य फ़ाइलें कुछ भी run होने से पहले `~/.failproofai/migrations/backup-layout/` को copy की जाती हैं। -आप किसी भी समय सीधे `policies-config.json` संपादित कर सकते हैं; परिवर्तन अगली हुक इवेंट पर बिना restart की आवश्यकता के तुरंत प्रभावी होते हैं। +[`failproofai update`](/hi/cli/update) के लिए one-line अपग्रेड, और [`failproofai migrate`](/hi/cli/migrate) — `--dry-run` सहित — details के लिए देखें। --- -## उदाहरण: टीम डिफ़ॉल्ट के साथ प्रोजेक्ट-स्तर कॉन्फ़िग +## उदाहरण: टीम डिफ़ॉल्ट के साथ project-level कॉन्फ़िगरेशन `.failproofai/policies-config.json` को अपने रेपो में कमिट करें: @@ -261,4 +289,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her } ``` -प्रत्येक डेवलपर फिर व्यक्तिगत overrides के लिए `.failproofai/policies-config.local.json` (gitignored) बना सकता है बिना teammates को प्रभावित किए। \ No newline at end of file +प्रत्येक डेवलपर तब व्यक्तिगत ओवरराइड के लिए `.failproofai/policies-config.local.json` (gitignored) बना सकता है बिना teammates को प्रभावित किए। \ No newline at end of file diff --git a/docs/hi/custom-policies.mdx b/docs/hi/custom-policies.mdx index 81a5bf3d..d76e396e 100644 --- a/docs/hi/custom-policies.mdx +++ b/docs/hi/custom-policies.mdx @@ -1,11 +1,10 @@ --- ---- -title: कस्टम पॉलिसीज -description: "JavaScript में अपने नियम लिखें - प्रोजेक्ट कन्वेंशन लागू करें, ड्रिफ्ट रोकें, विफलताएं डिटेक्ट करें, बाहरी सिस्टम के साथ इंटीग्रेट करें" +title: कस्टम पॉलिसीज़ +description: "JavaScript में अपने नियम लिखें - प्रोजेक्ट सम्मेलन लागू करें, ड्रिफ्ट को रोकें, विफलताओं का पता लगाएं, बाहरी सिस्टम के साथ एकीकृत करें" icon: code --- -कस्टम पॉलिसीज आपको किसी भी एजेंट व्यवहार के लिए नियम लिखने देती हैं: प्रोजेक्ट कन्वेंशन लागू करें, ड्रिफ्ट रोकें, विनाशकारी ऑपरेशन को गेट करें, फंसे हुए एजेंट्स को डिटेक्ट करें, या Slack, अनुमोदन वर्कफ़्लो और अधिक के साथ इंटीग्रेट करें। वे एक ही हुक इवेंट सिस्टम और `allow`, `deny`, `instruct` निर्णयों का उपयोग करते हैं जैसे बिल्ट-इन पॉलिसीज। +कस्टम पॉलिसीज़ आपको किसी भी एजेंट व्यवहार के लिए नियम लिखने देती हैं: प्रोजेक्ट सम्मेलन लागू करें, ड्रिफ्ट रोकें, विनाशकारी संचालन को रोकें, फंसे हुए एजेंट्स का पता लगाएं, या Slack, अनुमोदन वर्कफ़्लो और अन्य के साथ एकीकृत करें। ये बिल्ट-इन पॉलिसीज़ के समान हुक इवेंट सिस्टम और `allow`, `deny`, `instruct` निर्णयों का उपयोग करते हैं। --- @@ -38,65 +37,65 @@ failproofai policies --install --custom ./my-policies.js --- -## कस्टम पॉलिसीज लोड करने के दो तरीके +## कस्टम पॉलिसीज़ लोड करने के दो तरीके -### विकल्प 1: कन्वेंशन-आधारित (अनुशंसित) +### विकल्प 1: सम्मेलन-आधारित (अनुशंसित) -`.failproofai/policies/` में `*policies.{js,mjs,ts}` फाइलें ड्रॉप करें और वे स्वचालित रूप से लोड हो जाती हैं — कोई फ्लैग या कॉन्फ़िग परिवर्तन की आवश्यकता नहीं। यह git हुक्स की तरह काम करता है: एक फाइल ड्रॉप करें, और यह बस काम करता है। +`.failproofai/policies/` में `*policies.{js,mjs,ts}` फाइलें ड्रॉप करें और वे स्वचालित रूप से लोड हो जाती हैं — कोई फ़्लैग या कॉन्फ़िगरेशन परिवर्तन की आवश्यकता नहीं है। यह गिट हुक्स की तरह काम करता है: फाइल ड्रॉप करें, यह काम करता है। ``` -# प्रोजेक्ट स्तर — git में प्रतिबद्ध, टीम के साथ साझा किया गया +# प्रोजेक्ट स्तर — गिट में प्रतिबद्ध, टीम के साथ साझा .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# यूजर स्तर — व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू +# यूज़र स्तर — व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू होता है ~/.failproofai/policies/my-policies.mjs ``` **यह कैसे काम करता है:** -- प्रोजेक्ट और यूजर दोनों डायरेक्टरीज को स्कैन किया जाता है (यूनियन — पहले-स्कोप-जीत नहीं) -- फाइलें प्रत्येक डायरेक्टरी में वर्णक्रम में लोड होती हैं। ऑर्डर नियंत्रित करने के लिए `01-`, `02-` से शुरू करें +- प्रोजेक्ट और यूज़र दोनों निर्देशिकाएं स्कैन की जाती हैं (यूनियन — पहले-स्कोप-जीत्स नहीं) +- फाइलें प्रत्येक निर्देशिका के भीतर वर्णानुक्रम में लोड होती हैं। क्रम नियंत्रित करने के लिए `01-`, `02-` से प्रीफ़िक्स करें - केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फाइलें लोड होती हैं; अन्य फाइलें अनदेखी की जाती हैं - प्रत्येक फाइल स्वतंत्र रूप से लोड होती है (प्रति फाइल फेल-ओपन) -- स्पष्ट `--custom` और बिल्ट-इन पॉलिसीज के साथ साथ काम करता है +- स्पष्ट `--custom` और बिल्ट-इन पॉलिसीज़ के साथ काम करता है -कन्वेंशन पॉलिसीज आपके ऑर्गेनाइजेशन के लिए गुणवत्ता मानक बनाने का सबसे आसान तरीका हैं। `.failproofai/policies/` को git में प्रतिबद्ध करें और हर टीम मेंबर को स्वचालित रूप से एक ही नियम मिलते हैं — कोई प्रति-डेवलपर सेटअप की आवश्यकता नहीं। जैसे-जैसे आपकी टीम नई विफलता के तरीके खोजती है, एक पॉलिसी जोड़ें और पुश करें। समय के साथ ये एक जीवंत गुणवत्ता मानक बन जाते हैं जो हर योगदान के साथ सुधरता रहता है। +सम्मेलन पॉलिसीज़ आपकी संगठन के लिए गुणवत्ता मानक बनाने का सबसे आसान तरीका हैं। `.failproofai/policies/` को गिट में प्रतिबद्ध करें और हर टीम सदस्य को स्वचालित रूप से एक ही नियम मिलते हैं — कोई प्रति-डेवलपर सेटअप की आवश्यकता नहीं। जैसे-जैसे आपकी टीम नई विफलता के तरीके खोजती है, एक पॉलिसी जोड़ें और पुश करें। समय के साथ ये एक जीवंत गुणवत्ता मानक बन जाते हैं जो हर योगदान के साथ सुधारते रहते हैं। -### विकल्प 2: स्पष्ट फाइल पाथ +### विकल्प 2: स्पष्ट फाइल पथ ```bash -# कस्टम पॉलिसीज फाइल के साथ इंस्टॉल करें +# कस्टम पॉलिसीज़ फाइल के साथ इंस्टॉल करें failproofai policies --install --custom ./my-policies.js -# कस्टम पॉलिसी पाथ बदलें +# कस्टम पॉलिसी पथ को बदलें failproofai policies --install --custom ./new-policies.js -# कई स्पष्ट फाइलें कॉन्फ़िगर करें (फ्लैग ऑर्डर में लोड) +# कई स्पष्ट फाइलें कॉन्फ़िगर करें (फ़्लैग क्रम में लोड) failproofai policies --install --custom ./security.js --custom ./workflow.js -# कॉन्फ़िग से सभी स्पष्ट कस्टम पॉलिसी पाथ हटाएं +# कॉन्फ़िग से सभी स्पष्ट कस्टम पॉलिसी पथ हटाएं failproofai policies --uninstall --custom ``` -रिज़ॉल्व की गई निरपेक्ष पाथें `policies-config.json` में `customPoliciesPaths` के रूप में स्टोर की जाती हैं। कई फाइलें कॉन्फ़िगर करने के लिए `--custom` दोहराएं। लीगेसी `customPoliciesPath` फील्ड का उपयोग करने वाले मौजूदा कॉन्फ़िग्स काम करना जारी रखते हैं। फाइलें हर हुक इवेंट पर ताज़ी लोड होती हैं - इवेंट्स के बीच कोई कैशिंग नहीं है। +समाधान किए गए पूर्ण पथ `policies-config.json` में `customPoliciesPaths` के रूप में संग्रहीत होते हैं। कई फाइलें कॉन्फ़िगर करने के लिए `--custom` दोहराएं। लीगेसी `customPoliciesPath` फील्ड का उपयोग करने वाली मौजूदा कॉन्फ़िगरेशन काम करती रहती है। फाइलें हर हुक इवेंट पर ताज़ा लोड होती हैं - इवेंट्स के बीच कोई कैशिंग नहीं है। -प्रत्येक पंजीकृत पॉलिसी डैशबोर्ड में अपने स्वयं के टॉगल के साथ दिखाई देती है। एक पॉलिसी को बंद करने से इसके स्रोत-योग्य ID को `disabledCustomPolicies` में रिकॉर्ड किया जाता है; फाइल और इसकी अन्य पॉलिसीज लोड होना जारी रखती हैं, जबकि अक्षम पॉलिसी इवेंट मिलान से पहले बाहर निकाली जाती है। फाइलों में डुप्लिकेट पॉलिसी नामों के स्वतंत्र टॉगल होते हैं। +प्रत्येक पंजीकृत पॉलिसी डैशबोर्ड में अपने स्वयं के टॉगल के साथ दिखाई देती है। पॉलिसी को बंद करने से इसका स्रोत-योग्य ID `disabledCustomPolicies` में रिकॉर्ड होता है; फाइल और इसकी अन्य पॉलिसीज़ लोड होती रहती हैं, जबकि अक्षम की गई पॉलिसी इवेंट मिलान से पहले बहिष्कृत की जाती है। फाइलों में डुप्लीकेट पॉलिसी नामों के स्वतंत्र टॉगल होते हैं। ### दोनों को एक साथ उपयोग करना -कन्वेंशन पॉलिसीज और स्पष्ट `--custom` फाइलें एक साथ मौजूद हो सकती हैं। लोड ऑर्डर: +सम्मेलन पॉलिसीज़ और स्पष्ट `--custom` फाइलें सह-अस्तित्व में हो सकती हैं। लोड क्रम: -1. स्पष्ट `customPoliciesPaths` फाइलें (कॉन्फ़िगर किए गए ऑर्डर में) -2. प्रोजेक्ट कन्वेंशन फाइलें (`{cwd}/.failproofai/policies/`, वर्णक्रम) -3. यूजर कन्वेंशन फाइलें (`~/.failproofai/policies/`, वर्णक्रम) +1. स्पष्ट `customPoliciesPaths` फाइलें (कॉन्फ़िगर किए गए क्रम में) +2. प्रोजेक्ट सम्मेलन फाइलें (`{cwd}/.failproofai/policies/`, वर्णानुक्रम) +3. यूज़र सम्मेलन फाइलें (`~/.failproofai/policies/`, वर्णानुक्रम) --- ## API -### इम्पोर्ट +### आयात ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -104,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -एक पॉलिसी पंजीकृत करता है। एक ही फाइल में कई पॉलिसीज के लिए आवश्यकतानुसार बार-बार कॉल करें। +एक पॉलिसी को पंजीकृत करता है। एक ही फाइल में कई पॉलिसीज़ के लिए आवश्यकतानुसार इसे कॉल करें। ```ts customPolicies.add({ name: string; // आवश्यक - अद्वितीय पहचानकर्ता description?: string; // `failproofai policies` आउटपुट में दिखाया गया - match?: { events?: HookEventType[] }; // इवेंट टाइप द्वारा फ़िल्टर करें; सभी को मिलान करने के लिए छोड़ें + match?: { events?: HookEventType[] }; // इवेंट प्रकार द्वारा फ़िल्टर करें; सभी से मेल खाने के लिए छोड़ दें fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### निर्णय हेल्पर्स +### निर्णय सहायक | फंक्शन | प्रभाव | कब उपयोग करें | |----------|--------|----------| -| `allow()` | ऑपरेशन को चुप करके अनुमति दें | कार्य सुरक्षित है, कोई संदेश की आवश्यकता नहीं | -| `deny(message)` | ऑपरेशन को ब्लॉक करें | एजेंट को यह कार्य नहीं लेना चाहिए | -| `instruct(message)` | बिना ब्लॉक किए संदर्भ जोड़ें | एजेंट को ट्रैक पर रहने के लिए अतिरिक्त संदर्भ दें | +| `allow()` | संचालन को मौन रूप से अनुमति दें | कार्रवाई सुरक्षित है, कोई संदेश आवश्यक नहीं है | +| `deny(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` संदेश जमा होते हैं और एक साथ दिए जाते हैं। -आप `policyParams` में `hint` फील्ड जोड़कर किसी भी `deny` या `instruct` संदेश में अतिरिक्त निर्देश जोड़ सकते हैं — कोई कोड परिवर्तन की आवश्यकता नहीं। यह कस्टम (`custom/`), प्रोजेक्ट कन्वेंशन (`.failproofai-project/`), और यूजर कन्वेंशन (`.failproofai-user/`) पॉलिसीज के लिए भी काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/configuration#hint-cross-cutting) देखें। +आप `policyParams` में `hint` फील्ड जोड़कर किसी भी `deny` या `instruct` संदेश में अतिरिक्त मार्गदर्शन जोड़ सकते हैं — कोई कोड परिवर्तन आवश्यक नहीं है। यह कस्टम (`custom/`), प्रोजेक्ट सम्मेलन (`.failproofai-project/`), और यूज़र सम्मेलन (`.failproofai-user/`) पॉलिसीज़ के लिए भी काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/configuration#hint-cross-cutting) देखें। -### सूचनात्मक allow संदेश +### सूचनात्मक अनुमति संदेश -`allow(message)` ऑपरेशन को अनुमति देता है **और** Claude को एक सूचनात्मक संदेश भेजता है। संदेश हुक हैंडलर के stdout प्रतिक्रिया में `additionalContext` के रूप में डिलीवर किया जाता है — `instruct` द्वारा उपयोग किया गया समान तंत्र, लेकिन अर्थपूर्ण रूप से भिन्न: यह एक चेतावनी नहीं, एक स्थिति अपडेट है। +`allow(message)` संचालन की अनुमति देता है **और** Claude को वापस एक सूचनात्मक संदेश भेजता है। संदेश हुक हैंडलर के stdout प्रतिक्रिया में `additionalContext` के रूप में दिया जाता है — वही तंत्र जो `instruct` द्वारा उपयोग किया जाता है, लेकिन अर्थ में अलग: यह एक चेतावनी नहीं, बल्कि एक स्थिति अपडेट है। | फंक्शन | प्रभाव | कब उपयोग करें | |----------|--------|----------| -| `allow(message)` | अनुमति दें और Claude को संदर्भ भेजें | एक चेक पास होने की पुष्टि करें, या समझाएं कि चेक को क्यों छोड़ा गया | +| `allow(message)` | अनुमति दें और Claude को संदर्भ भेजें | एक जांच पास होने की पुष्टि करें, या समझाएं कि एक जांच को क्यों छोड़ा गया | उपयोग के मामले: - **स्थिति पुष्टि:** `allow("All CI checks passed.")` — Claude को बताता है कि सब कुछ हरा है -- **फेल-ओपन व्याख्याएं:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude को बताता है कि चेक को क्यों छोड़ा गया ताकि इसके पास पूरा संदर्भ हो -- **कई संदेश जमा होते हैं:** यदि कई पॉलिसीज प्रत्येक `allow(message)` लौटाते हैं, तो सभी संदेश न्यूलाइन्स के साथ जुड़ते हैं और एक साथ डिलीवर किए जाते हैं +- **फेल-ओपन व्याख्या:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude को बताता है कि एक जांच को क्यों छोड़ा गया ताकि इसके पास पूर्ण संदर्भ हो +- **कई संदेश जमा होते हैं:** यदि कई पॉलिसीज़ में से प्रत्येक `allow(message)` लौटाती है, तो सभी संदेश नई पंक्तियों के साथ जुड़े होते हैं और एक साथ दिए जाते हैं ```js customPolicies.add({ @@ -152,7 +151,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... branch status जांचें ... + // ... check branch status ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -163,51 +162,51 @@ customPolicies.add({ ### `PolicyContext` फील्ड्स -| फील्ड | टाइप | विवरण | +| फील्ड | प्रकार | विवरण | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | टूल कॉल किया जा रहा है (उदाहरण के लिए `"Bash"`, `"Write"`, `"Read"`) | -| `toolInput` | `Record \| undefined` | टूल के इनपुट पैरामीटर | -| `payload` | `Record` | Claude Code से पूर्ण raw इवेंट पेलोड | +| `toolName` | `string \| undefined` | कॉल किया जा रहा टूल (जैसे `"Bash"`, `"Write"`, `"Read"`) | +| `toolInput` | `Record \| undefined` | टूल के इनपुट पैरामीटर्स | +| `payload` | `Record` | Claude Code से पूर्ण कच्चा इवेंट पेलोड | | `session` | `SessionMetadata \| undefined` | सेशन संदर्भ (नीचे देखें) | ### `SessionMetadata` फील्ड्स -| फील्ड | टाइप | विवरण | +| फील्ड | प्रकार | विवरण | |-------|------|-------------| | `sessionId` | `string` | Claude Code सेशन पहचानकर्ता | -| `cwd` | `string` | Claude Code सेशन की कार्य डायरेक्टरी | -| `transcriptPath` | `string` | सेशन की JSONL ट्रांसक्रिप्ट फाइल का पाथ | +| `cwd` | `string` | Claude Code सेशन की कार्य निर्देशिका | +| `transcriptPath` | `string` | सेशन की JSONL ट्रांसक्रिप्ट फाइल का पथ | ### इवेंट प्रकार | इवेंट | कब फायर होता है | `toolInput` सामग्री | |-------|--------------|----------------------| -| `PreToolUse` | Claude एक टूल चलाने से पहले | टूल का इनपुट (उदाहरण के लिए Bash के लिए `{ command: "..." }`) | -| `PostToolUse` | एक टूल पूरा होने के बाद | टूल का इनपुट + `tool_result` (आउटपुट) | -| `Notification` | जब Claude एक सूचना भेजता है | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - हुक्स को हमेशा `allow()` लौटना होगा, वे सूचनाओं को ब्लॉक नहीं कर सकते | +| `PreToolUse` | Claude टूल चलाने से पहले | टूल का इनपुट (जैसे Bash के लिए `{ command: "..." }`) | +| `PostToolUse` | टूल पूरा होने के बाद | टूल का इनपुट + `tool_result` (आउटपुट) | +| `Notification` | जब Claude एक सूचना भेजता है | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - हुक्स को हमेशा `allow()` लौटाना चाहिए, वे सूचनाओं को ब्लॉक नहीं कर सकते | | `Stop` | जब Claude सेशन समाप्त होता है | खाली | --- -## मूल्यांकन ऑर्डर +## मूल्यांकन क्रम -पॉलिसीज का मूल्यांकन इस ऑर्डर में किया जाता है: +पॉलिसीज़ का मूल्यांकन इस क्रम में किया जाता है: -1. बिल्ट-इन पॉलिसीज (परिभाषा ऑर्डर में) -2. `customPoliciesPath` से स्पष्ट कस्टम पॉलिसीज (`.add()` ऑर्डर में) -3. प्रोजेक्ट `.failproofai/policies/` से कन्वेंशन पॉलिसीज (फाइलें वर्णक्रम में, `.add()` ऑर्डर के भीतर) -4. यूजर `~/.failproofai/policies/` से कन्वेंशन पॉलिसीज (फाइलें वर्णक्रम में, `.add()` ऑर्डर के भीतर) +1. बिल्ट-इन पॉलिसीज़ (परिभाषा क्रम में) +2. `customPoliciesPath` से स्पष्ट कस्टम पॉलिसीज़ (`.add()` क्रम में) +3. प्रोजेक्ट `.failproofai/policies/` से सम्मेलन पॉलिसीज़ (फाइलें वर्णानुक्रम, भीतर `.add()` क्रम) +4. यूज़र `~/.failproofai/policies/` से सम्मेलन पॉलिसीज़ (फाइलें वर्णानुक्रम, भीतर `.add()` क्रम) -पहली `deny` सभी बाद की पॉलिसीज को शॉर्ट-सर्किट करती है। सभी `instruct` संदेश संचित होते हैं और एक साथ डिलीवर किए जाते हैं। +पहला `deny` सभी बाद की पॉलिसीज़ को छोटा कर देता है। सभी `instruct` संदेश जमा होते हैं और एक साथ दिए जाते हैं। --- -## ट्रांजिटिव इम्पोर्ट्स +## संक्रमणकारी आयात -कस्टम पॉलिसी फाइलें सापेक्ष पाथ का उपयोग करके स्थानीय मॉड्यूल को इम्पोर्ट कर सकती हैं: +कस्टम पॉलिसी फाइलें सापेक्ष पथ का उपयोग करके स्थानीय मॉड्यूल आयात कर सकती हैं: ```js // my-policies.js @@ -224,43 +223,43 @@ customPolicies.add({ }); ``` -एंट्री फाइल से सभी सापेक्ष इम्पोर्ट्स रिज़ॉल्व किए जाते हैं। यह `from "failproofai"` इम्पोर्ट्स को वास्तविक dist पाथ में दोबारा लिखकर और ESM संगतता सुनिश्चित करने के लिए अस्थायी `.mjs` फाइलें बनाकर लागू किया जाता है। +प्रवेश फाइल से पहुंचने योग्य सभी सापेक्ष आयात समाधान किए जाते हैं। यह `from "failproofai"` आयातों को वास्तविक dist पथ में फिर से लिखकर और ESM संगतता सुनिश्चित करने के लिए अस्थायी `.mjs` फाइलें बनाकर लागू किया जाता है। --- -## इवेंट टाइप फ़िल्टरिंग +## इवेंट प्रकार फ़िल्टरिंग -`match.events` का उपयोग करके यह सीमित करें कि एक पॉलिसी कब फायर होती है: +`match.events` का उपयोग करके यह सीमित करें कि पॉलिसी कब फायर होती है: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // केवल तभी फायर होता है जब सेशन समाप्त होता है - // ctx.session.transcriptPath में पूर्ण सेशन लॉग होता है + // केवल तब फायर होता है जब सेशन समाप्त होता है + // ctx.session.transcriptPath में पूर्ण सेशन लॉग है return allow(); }, }); ``` -हर इवेंट टाइप पर फायर करने के लिए `match` को पूरी तरह से छोड़ें। +हर इवेंट प्रकार पर फायर करने के लिए `match` को पूरी तरह छोड़ दें। --- ## त्रुटि हैंडलिंग और विफलता के तरीके -कस्टम पॉलिसीज **फेल-ओपन** हैं: त्रुटियां कभी बिल्ट-इन पॉलिसीज को ब्लॉक नहीं करती हैं या हुक हैंडलर को क्रैश नहीं करती हैं। +कस्टम पॉलिसीज़ **फेल-ओपन** हैं: त्रुटियां कभी भी बिल्ट-इन पॉलिसीज़ को ब्लॉक या हुक हैंडलर को क्रैश नहीं करती। | विफलता | व्यवहार | |---------|----------| -| `customPoliciesPath` सेट नहीं | कोई स्पष्ट कस्टम पॉलिसीज नहीं चलती; कन्वेंशन पॉलिसीज और बिल्ट-इन सामान्य रूप से जारी रहते हैं | -| फाइल नहीं मिली | `~/.failproofai/hook.log` को चेतावनी लॉग की गई; बिल्ट-इन जारी रहते हैं | -| सिंटैक्स/इम्पोर्ट त्रुटि (स्पष्ट) | `~/.failproofai/hook.log` को त्रुटि लॉग की गई; स्पष्ट कस्टम पॉलिसीज छोड़ी गई | -| सिंटैक्स/इम्पोर्ट त्रुटि (कन्वेंशन) | त्रुटि लॉग की गई; वह फाइल छोड़ी गई, अन्य कन्वेंशन फाइलें अभी भी लोड होती हैं | -| `fn` रनटाइम पर थ्रो होता है | त्रुटि लॉग की गई; वह हुक `allow` के रूप में माना जाता है; अन्य हुक्स जारी रहते हैं | -| `fn` 10 सेकंड से अधिक समय लेता है | टाइमआउट लॉग किया गया; `allow` के रूप में माना जाता है | -| कन्वेंशन डायरेक्टरी लापता | कोई कन्वेंशन पॉलिसीज नहीं चलती; कोई त्रुटि नहीं | +| `customPoliciesPath` सेट नहीं है | कोई स्पष्ट कस्टम पॉलिसीज़ नहीं चलती; सम्मेलन पॉलिसीज़ और बिल्ट-इन्स सामान्य रूप से जारी रहते हैं | +| फाइल नहीं मिली | `~/.failproofai/hook.log` में चेतावनी दर्ज की जाती है; बिल्ट-इन्स जारी रहते हैं | +| सिंटैक्स/आयात त्रुटि (स्पष्ट) | `~/.failproofai/hook.log` में त्रुटि दर्ज की जाती है; स्पष्ट कस्टम पॉलिसीज़ छोड़ दी जाती हैं | +| सिंटैक्स/आयात त्रुटि (सम्मेलन) | त्रुटि दर्ज की जाती है; वह फाइल छोड़ दी जाती है, अन्य सम्मेलन फाइलें अभी भी लोड होती हैं | +| `fn` रनटाइम पर फेंकता है | त्रुटि दर्ज की जाती है; वह हुक `allow` के रूप में माना जाता है; अन्य हुक्स जारी रहते हैं | +| `fn` 10 सेकंड से अधिक समय लेता है | टाइमआउट दर्ज किया जाता है; `allow` के रूप में माना जाता है | +| सम्मेलन निर्देशिका गायब है | कोई सम्मेलन पॉलिसीज़ नहीं चलती; कोई त्रुटि नहीं | कस्टम पॉलिसी त्रुटियों को डीबग करने के लिए, लॉग फाइल को देखें: @@ -272,13 +271,13 @@ tail -f ~/.failproofai/hook.log --- -## पूर्ण उदाहरण: कई पॉलिसीज +## पूर्ण उदाहरण: कई पॉलिसीज़ ```js // 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", @@ -291,7 +290,7 @@ customPolicies.add({ }, }); -// एजेंट को ट्रैक पर रखें: प्रतिबद्ध करने से पहले टेस्ट सत्यापित करें +// एजेंट को ट्रैक पर रखें: प्रतिबद्ध करने से पहले परीक्षण सत्यापित करें customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -306,7 +305,7 @@ customPolicies.add({ }, }); -// फ्रीज अवधि के दौरान अनियोजित डिपेंडेंसी परिवर्तन रोकें +// फ्रीज़ अवधि के दौरान अनियोजित निर्भरता परिवर्तन रोकें customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -329,31 +328,31 @@ export { customPolicies }; ## उदाहरण -`examples/` डायरेक्टरी में तैयार-से-चलाने वाली पॉलिसी फाइलें हैं: +`examples/` निर्देशिका में तुरंत उपयोग के लिए तैयार पॉलिसी फाइलें हैं: | फाइल | सामग्री | |------|----------| -| `examples/policies-basic.js` | पांच स्टार्टर पॉलिसीज जो सामान्य एजेंट विफलता के तरीकों को कवर करती हैं | -| `examples/policies-advanced/index.js` | उन्नत पैटर्न: ट्रांजिटिव इम्पोर्ट्स, async कॉल्स, आउटपुट स्क्रबिंग, और सेशन-एंड हुक्स | -| `examples/convention-policies/security-policies.mjs` | कन्वेंशन-आधारित सुरक्षा पॉलिसीज (.env लिखता है ब्लॉक करें, git इतिहास पुनः लिखने को रोकें) | -| `examples/convention-policies/workflow-policies.mjs` | कन्वेंशन-आधारित वर्कफ़्लो पॉलिसीज (टेस्ट अनुस्मारक, ऑडिट फाइल लिखता है) | +| `examples/policies-basic.js` | पाँच स्टार्टर पॉलिसीज़ जो सामान्य एजेंट विफलता के तरीकों को कवर करती हैं | +| `examples/policies-advanced/index.js` | उन्नत पैटर्न: संक्रमणकारी आयात, अतुल्यकालिक कॉल, आउटपुट स्क्रबिंग, और सेशन-एंड हुक्स | +| `examples/convention-policies/security-policies.mjs` | सम्मेलन-आधारित सुरक्षा पॉलिसीज़ (.env लिखने को ब्लॉक करें, गिट इतिहास को फिर से लिखने से रोकें) | +| `examples/convention-policies/workflow-policies.mjs` | सम्मेलन-आधारित वर्कफ़्लो पॉलिसीज़ (परीक्षण अनुस्मारक, ऑडिट फाइल लिखता है) | -### स्पष्ट फाइल उदाहरण उपयोग करना +### स्पष्ट फाइल उदाहरण का उपयोग करना ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### कन्वेंशन-आधारित उदाहरण उपयोग करना +### सम्मेलन-आधारित उदाहरणों का उपयोग करना ```bash -# प्रोजेक्ट स्तर पर कॉपी करें +# प्रोजेक्ट स्तर में कॉपी करें mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# या यूजर स्तर पर कॉपी करें +# या यूज़र स्तर में कॉपी करें mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -कोई इंस्टॉल कमांड की आवश्यकता नहीं — फाइलें अगली हुक इवेंट पर स्वचालित रूप से उठाई जाती हैं। \ No newline at end of file +कोई इंस्टॉल कमांड आवश्यक नहीं है — फाइलें अगली हुक इवेंट पर स्वचालित रूप से उठाई जाती हैं। \ No newline at end of file diff --git a/docs/hi/dashboard.mdx b/docs/hi/dashboard.mdx index 54815c48..e3488795 100644 --- a/docs/hi/dashboard.mdx +++ b/docs/hi/dashboard.mdx @@ -1,15 +1,14 @@ --- ---- -title: Dashboard -description: "Agent सेशन को मॉनिटर करें, tool कॉल की समीक्षा करें, और policies को प्रबंधित करें" +title: डैशबोर्ड +description: "एजेंट सेशन की निगरानी करें, टूल कॉल की समीक्षा करें, और नीतियों का प्रबंधन करें" icon: chart-line --- -failproofai dashboard एक स्थानीय वेब एप्लिकेशन है जो आपके AI agent सेशन को मॉनिटर करने और policies को प्रबंधित करने के लिए है। देखें कि आपके agents आपके दूर रहते हुए क्या करते रहे। +failproofai डैशबोर्ड आपके AI एजेंट सेशन की निगरानी करने और नीतियों का प्रबंधन करने के लिए एक स्थानीय वेब एप्लिकेशन है। देखें कि आपके एजेंट आपके जाने के बाद क्या करते थे। --- -## Dashboard को शुरू करना +## डैशबोर्ड शुरू करना ```bash failproofai @@ -17,103 +16,103 @@ failproofai `http://localhost:8020` पर खुलता है। -Dashboard स्थानीय project, session, और failproofai कॉन्फ़िगरेशन डेटा को सीधे फ़ाइल सिस्टम से पढ़ता है। वैकल्पिक प्रमाणित सुविधाएं, जैसे audit reminders और invitations, उन अनुरोधों के लिए आवश्यक जानकारी (ईमेल पते सहित) दूरस्थ API को भेजती हैं। +डैशबोर्ड स्थानीय प्रोजेक्ट, सेशन, और failproofai कॉन्फ़िगरेशन डेटा को सीधे फाइलसिस्टम से पढ़ता है। ऑडिट अनुस्मारक और निमंत्रण जैसी वैकल्पिक प्रमाणीकृत सुविधाएं उन अनुरोधों के लिए आवश्यक जानकारी (ईमेल पते सहित) को रिमोट API को भेजती हैं। --- ## पृष्ठ -### Projects +### प्रोजेक्ट -आपकी मशीन पर मिले सभी Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, और Goose projects की सूची। Claude projects को `~/.claude/projects/` से खोजा जाता है (या `CLAUDE_PROJECTS_PATH` द्वारा सेट किए गए पथ से); Codex projects को `~/.codex/sessions///
/*.jsonl` के तहत प्रत्येक transcript को स्कैन करके और प्रत्येक सेशन की पहली रिकॉर्ड में दर्ज `cwd` द्वारा समूहित करके खोजा जाता है; Copilot CLI projects को `~/.copilot/session-state//workspace.yaml` को स्कैन करके (`COPILOT_HOME` के माध्यम से कॉन्फ़िगर करने योग्य) और उसके `cwd` फ़ील्ड द्वारा समूहित करके खोजा जाता है; Cursor Agent projects को `~/.cursor/agent-sessions//` के तहत प्रति-सेशन मेटाडेटा को स्कैन करके (`CURSOR_HOME` के माध्यम से कॉन्फ़िगर करने योग्य, fallbacks के रूप में `conversations/` और `sessions/` की जांच की जाती है) `meta.json` / `session.json` / `workspace.yaml` में `cwd` scalar के लिए खोजा जाता है; OpenCode projects को `~/.local/share/opencode/opencode.db` पर SQLite DB को `opencode db --format json` के माध्यम से क्वेरी करके खोजा जाता है (हम `session` और `project` tables को पढ़ते हैं और `project_id` द्वारा समूहित करते हैं); Pi projects को `~/.pi/agent/sessions//_.jsonl` के तहत प्रति-सेशन JSONL transcripts को स्कैन करके (`PI_SESSIONS_DIR` के माध्यम से कॉन्फ़िगर करने योग्य) और प्रत्येक सेशन की पहली रिकॉर्ड से `cwd` को खींचकर खोजा जाता है; Hermes gateway सेशन को हर प्रोफ़ाइल के SQLite store से सीधे पढ़ा जाता है — `~/.hermes/state.db` साथ ही `~/.hermes/profiles//state.db` (`HERMES_HOME` द्वारा ओवरराइडेबल, या एकल डेटाबेस के लिए `HERMES_DB_PATH`) — और प्रोफ़ाइल और `source` (Slack/Telegram/cli/cron — gateway सेशन के पास कोई cwd नहीं) द्वारा `hermes--` projects में समूहित किए जाते हैं; OpenClaw gateway सेशन को `~/.openclaw/agents//sessions/*.jsonl` से पढ़ा जाता है और agent और channel द्वारा `openclaw--` projects में समूहित किए जाते हैं (साथ ही cwd-less); Factory Droid projects को `~/.factory/sessions//*.jsonl` पर JSONL transcripts से खोजा जाता है और cwd द्वारा समूहित किया जाता है; Devin projects इसके SQLite DB से `~/.local/share/devin/cli/sessions.db` पर (प्रत्येक सेशन के `working_directory` द्वारा समूहित); Antigravity projects `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` पर JSONL transcripts से और cwd द्वारा समूहित; और Goose projects इसके SQLite DB से `~/.local/share/goose/sessions/sessions.db` पर (प्रत्येक सेशन के `working_dir` द्वारा समूहित)। एक project जो कई CLIs द्वारा उपयोग किया गया है सभी मिलान badge के साथ एकल row के रूप में प्रदर्शित होता है। तालिका के ऊपर **CLI** ड्रॉपडाउन का उपयोग करके किसी विशिष्ट agent CLI द्वारा फ़िल्टर करें; URL आपके चयन को `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` के रूप में संरक्षित करता है। +आपकी मशीन पर मिले सभी Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, और Goose प्रोजेक्ट को सूचीबद्ध करता है। Claude प्रोजेक्ट `~/.claude/projects/` से खोजे जाते हैं (या `CLAUDE_PROJECTS_PATH` द्वारा निर्धारित पथ); Codex प्रोजेक्ट `~/.codex/sessions///
/*.jsonl` के तहत प्रत्येक प्रतिलेख को स्कैन करके और प्रत्येक सेशन के पहले रिकॉर्ड में दर्ज `cwd` के आधार पर समूहीकृत करके खोजे जाते हैं; Copilot CLI प्रोजेक्ट प्रत्येक `~/.copilot/session-state//workspace.yaml` को स्कैन करके (`COPILOT_HOME` के माध्यम से कॉन्फ़िगर करने योग्य) और इसके `cwd` फील्ड के आधार पर समूहीकृत करके खोजे जाते हैं; Cursor Agent प्रोजेक्ट `~/.cursor/agent-sessions//` के तहत प्रति-सेशन मेटाडेटा को स्कैन करके (`CURSOR_HOME` के माध्यम से कॉन्फ़िगर करने योग्य, `conversations/` और `sessions/` को फॉलबैक के रूप में जांचा जाता है) `meta.json` / `session.json` / `workspace.yaml` में `cwd` स्केलर के लिए खोजे जाते हैं; OpenCode प्रोजेक्ट `~/.local/share/opencode/opencode.db` पर इसके SQLite DB को क्वेरी करके `opencode db --format json` के माध्यम से खोजे जाते हैं (हम `session` और `project` तालिकाओं को पढ़ते हैं और `project_id` के आधार पर समूहीकृत करते हैं); Pi प्रोजेक्ट `~/.pi/agent/sessions//_.jsonl` के तहत प्रति-सेशन JSONL प्रतिलेखों को स्कैन करके (`PI_SESSIONS_DIR` के माध्यम से कॉन्फ़िगर करने योग्य) और प्रत्येक सेशन के पहले रिकॉर्ड से `cwd` को खींचकर खोजे जाते हैं; Hermes गेटवे सेशन सीधे हर प्रोफाइल के SQLite स्टोर से पढ़े जाते हैं — `~/.hermes/state.db` साथ ही `~/.hermes/profiles//state.db` (`HERMES_HOME` के माध्यम से ओवरराइड करने योग्य, या एक एकल डेटाबेस के लिए `HERMES_DB_PATH`) — और प्रोफाइल और `source` (Slack/Telegram/cli/cron — गेटवे सेशन के कोई cwd नहीं) द्वारा `hermes--` प्रोजेक्ट में समूहीकृत किए जाते हैं; OpenClaw गेटवे सेशन `~/.openclaw/agents//sessions/*.jsonl` से पढ़े जाते हैं और एजेंट और चैनल द्वारा `openclaw--` प्रोजेक्ट में समूहीकृत किए जाते हैं (cwd के बिना भी); Factory Droid प्रोजेक्ट `~/.factory/sessions//*.jsonl` पर JSONL प्रतिलेखों से खोजे जाते हैं और cwd के आधार पर समूहीकृत किए जाते हैं; Devin प्रोजेक्ट `~/.local/share/devin/cli/sessions.db` पर इसके SQLite DB से (प्रत्येक सेशन के `working_directory` के आधार पर समूहीकृत); Antigravity प्रोजेक्ट `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` पर JSONL प्रतिलेखों से और cwd के आधार पर समूहीकृत; और Goose प्रोजेक्ट `~/.local/share/goose/sessions/sessions.db` पर इसके SQLite DB से (प्रत्येक सेशन के `working_dir` के आधार पर समूहीकृत)। एक प्रोजेक्ट जो कई CLIs द्वारा उपयोग किया गया है, एक एकल पंक्ति के रूप में सभी मेल खाने वाले बैज के साथ प्रस्तुत होता है। तालिका के ऊपर **CLI** ड्रॉपडाउन का उपयोग करके किसी विशेष एजेंट CLI से फ़िल्टर करें; URL आपकी चयन को `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` के रूप में संरक्षित करता है। -Hermes और OpenClaw user-scoped हैं और समूहित करने के लिए कोई working directory नहीं है, इसलिए वे **collapsible folder tree** के रूप में प्रदर्शित होते हैं — शीर्ष स्तर पर profile (या agent), इसके नीचे channels — जबकि प्रत्येक cwd-based CLI एक flat row रहता है। Folder rows उनके अंतर्गत सभी चीजों की session count और सबसे हाल की गतिविधि को रोल अप करते हैं, collapsed folders को visits के बीच याद रखा जाता है, और एक keyword search जो कुछ भी match करता है उसे expand करता है। +Hermes और OpenClaw उपयोगकर्ता-स्कोप किए गए हैं और समूहीकृत करने के लिए कोई कार्य निर्देशिका नहीं है, इसलिए वे **संक्षेपणीय फोल्डर ट्री** के रूप में प्रस्तुत होते हैं — प्रोफाइल (या एजेंट) शीर्ष स्तर पर, इसके चैनल नीचे — जबकि हर cwd-आधारित CLI एक सपाट पंक्ति रहता है। फोल्डर पंक्तियां सेशन गणना और उनके नीचे सब कुछ की सबसे हाल की गतिविधि को जमा करती हैं, संक्षेपित फोल्डर दौरों के बीच याद किए जाते हैं, और कीवर्ड खोज जो कुछ भी मेल खाता है उसे विस्तारित करती है। -प्रत्येक project दिखाता है: -- Project name (फ़ोल्डर पथ से प्राप्त) -- एक CLI badge — `Claude Code` (orange), `OpenAI Codex` (purple), `GitHub Copilot` (blue), `Cursor Agent` (emerald), `OpenCode` (amber), `Pi` (pink), और/या `Hermes` (indigo) -- सबसे हाल की session activity की तारीख +प्रत्येक प्रोजेक्ट दिखाता है: +- प्रोजेक्ट नाम (फोल्डर पथ से प्राप्त) +- एक CLI बैज — `Claude Code` (नारंगी), `OpenAI Codex` (बैंगनी), `GitHub Copilot` (नीला), `Cursor Agent` (एमराल्ड), `OpenCode` (एम्बर), `Pi` (गुलाबी), और/या `Hermes` (इंडिगो) +- सबसे हाल की सेशन गतिविधि की तारीख -किसी project को इसके सेशन देखने के लिए क्लिक करें। +एक प्रोजेक्ट पर क्लिक करके इसके सेशन देखें। -### Sessions +### सेशन -किसी project के भीतर सभी sessions की सूची। प्रत्येक session दिखाता है: -- Session ID -- शुरुआत और समाप्ति timestamps -- Tool calls की संख्या -- Hook activity count (policies जो fired हुई) +किसी प्रोजेक्ट के भीतर सभी सेशन को सूचीबद्ध करता है। प्रत्येक सेशन दिखाता है: +- सेशन ID +- शुरुआत और समाप्ति के टाइमस्टैम्प +- टूल कॉल की संख्या +- हुक गतिविधि गणना (नीतियां जो चलीं) -सूची को सीमित करने के लिए date range filter और session ID search का उपयोग करें। Sessions paginated हैं। +सूची को सीमित करने के लिए दिनांक श्रेणी फ़िल्टर और सेशन ID खोज का उपयोग करें। सेशन को पेजीकृत किया जाता है। -किसी session को session viewer खोलने के लिए क्लिक करें। +सेशन दर्शक खोलने के लिए किसी सेशन पर क्लिक करें। -### Session viewer +### सेशन दर्शक -Session viewer स्वायत्त agents के लिए मुख्य प्रश्न का उत्तर देता है: agent ने क्या किया, और क्या यह track पर रहा? Header के पास एक CLI badge यह दर्शाता है कि session Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, या Goose transcript है। यह सेशन में घटी सभी चीजों का एक timeline दिखाता है: +सेशन दर्शक स्वायत्त एजेंट के लिए मुख्य प्रश्न का उत्तर देता है: एजेंट ने क्या किया, और क्या यह ट्रैक पर रहा? हेडर के बगल में एक CLI बैज यह दर्शाता है कि सेशन Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, या Goose प्रतिलेख है। यह एक सेशन में हुई सब कुछ की एक समयरेखा दिखाता है: -- **Messages** - Claude के text responses और user prompts -- **Tool calls** - Claude द्वारा invoke किए गए हर tool, इसके input और output के साथ -- **Policy activity** - प्रत्येक tool call के लिए, कौन सी policies fired हुई और उन्होंने क्या decision return किया +- **संदेश** - Claude के पाठ प्रतिक्रियाएं और उपयोगकर्ता संकेत +- **टूल कॉल** - हर टूल जो Claude ने आह्वान किया, इसके इनपुट और आउटपुट के साथ +- **नीति गतिविधि** - प्रत्येक टूल कॉल के लिए, कौन सी नीतियां चलीं और वे क्या निर्णय लौटीं -शीर्ष पर stats bar session duration, total tool calls, और hook decisions का एक summary दिखाता है (allow / deny / instruct counts)। +शीर्ष पर स्टैट्स बार सेशन अवधि, कुल टूल कॉल, और हुक निर्णयों का सारांश (allow / deny / instruct गणना) दिखाता है। -**Download Logs** button को क्लिक करके सेशन को export करें। Claude Code, Codex, Copilot, Cursor, और Pi sessions के लिए आपको original on-disk JSONL transcript byte-for-byte मिलता है; OpenCode (जिसके सेशन SQLite में live हैं, disk पर नहीं) के लिए आपको एक JSON document मिलता है जो अंतर्निहित `session` / `messages` / `parts` tables को mirror करता है। +सेशन को निर्यात करने के लिए **Download Logs** बटन पर क्लिक करें। Claude Code, Codex, Copilot, Cursor, और Pi सेशन के लिए आप बिल्कुल मूल डिस्क पर JSONL प्रतिलेख पाते हैं; OpenCode के लिए (जिसके सेशन SQLite में हैं, डिस्क पर नहीं) आप अंतर्निहित `session` / `messages` / `parts` तालिकाओं को प्रतिबिंबित करने वाला एक JSON दस्तावेज़ पाते हैं। -### Audit +### ऑडिट -आपके agent के वास्तविक व्यवहार का एक personality-driven report पिछले सेशन में। `failproofai audit` CLI के समान scan को चलाता है लेकिन इसे एक single-screen shareable poster + चार below-the-fold sections के रूप में प्रस्तुत करता है: +आपके एजेंट ने वास्तव में पिछले सेशन में कैसे व्यवहार किया है, इसका एक व्यक्तित्व-संचालित रिपोर्ट। `failproofai audit` CLI के समान स्कैन चलाता है लेकिन इसे एक एकल-स्क्रीन साझा करने योग्य पोस्टर + चार नीचे-द-फोल्ड अनुभागों के रूप में प्रस्तुत करता है: -1. **Poster** — पहले viewport को भरता है। Self-contained PNG-capture region failproof_ai wordmark + audit label के साथ · archetype index (`№ NN of 08`) + audit date · numeric score (0–100) + percentile rank pill (`top 15%`) · archetype name (एक `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` में से) + 3-keyword strip · `// only N% of agents are this archetype` rarity line · 8×8 pixel sigil tile · `audit yours → failproof.ai` footer। Capture box के बाहर तीन share buttons हैं: `post your archetype` (X intent), `share on linkedin`, `download poster`। Capture `html-to-image` के माध्यम से चलता है इसलिए PNG on-screen render के साथ pixel-for-pixel मेल खाता है (dashed borders, SVG logo mask, gradients, font metrics — सभी preserved)। -2. **Strengths** — calm ✓ row list आपके agent द्वारा पहले से किए जाने वाले व्यवहारों का, live audit data से प्राप्त (clean tool-call rate, main के लिए कोई direct push नहीं, zero credential leaks, zero retry storms) — प्रत्येक तब ही surfaced होता है जब संबंधित policy के पास audit window में clean record हो। -3. **Quirks** — table जो फिसल गया, severity द्वारा ranked: `when · what slipped + the policy that would've caught it · severity pill · seen`, जहां recurrence `new` (एक बार), `N× seen` (2–9 times), या `recurring` (10+) को पढ़ता है। -4. **How to improve** — calm row list, प्रत्येक prescribed policy के लिए एक: white में policy name, one-line description, install command + दाईं ओर copy button। Section header `enable all N → projected · ` को पढ़ता है (वह score जो आप हर fix को लागू करने के साथ प्राप्त करेंगे), और इसका `[install all]` button प्रत्येक prescribed policy के लिए संयुक्त `failproofai policy add a b c …` command को copy करता है। -5. **Come back better** — दो side-by-side cards। Left: एक reminder सेट करें (`3d` / `7d` / `14d` / `30d` cadence picker; authed होने के बाद `/api/auth/reminder` के माध्यम से persist); Right: failproof perks unlock करें — `invite a friend` एक modal खोलता है जो comma/space/newline-separated friend emails की एक सूची लेता है (प्रति send max 10), उन्हें `/api/audit/invite` पर POST करता है, जो api-server के `POST /v0/invite` को forward करता है। Api-server `invite@failproof.ai` से प्रत्येक recipient को एक email भेजता है sender Cc के साथ और `Reply-To` सेट, इसलिए recipient देखता है कि किसने उन्हें invite किया और sender को अपने inbox में एक copy मिलता है। Anonymous users पहले `AuthDialog` के माध्यम से routed होते हैं ताकि invites के आउट जाने से पहले sender का email जाना जाए। Entitlement / perks fulfillment एक follow-up है। +1. **पोस्टर** — पहले व्यूपोर्ट को भरता है। failproof_ai वर्डमार्क + ऑडिट लेबल के साथ स्व-निहित PNG-कैप्चर क्षेत्र · आर्केटाइप इंडेक्स (`№ NN of 08`) + ऑडिट तारीख · संख्यात्मक स्कोर (0–100) + प्रतिशत रैंक पिल (`top 15%`) · आर्केटाइप नाम (एक से `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + 3-कीवर्ड स्ट्रिप · `// only N% of agents are this archetype` दुर्लभता पंक्ति · 8×8 पिक्सेल सिजिल टाइल · `audit yours → failproof.ai` फूटर। तीन साझा करें बटन कैप्चर बॉक्स के ठीक बाहर बैठते हैं: `post your archetype` (X intent), `share on linkedin`, `download poster`। कैप्चर `html-to-image` के माध्यम से चलता है ताकि PNG ऑन-स्क्रीन रेंडर से पिक्सेल-फॉर-पिक्सेल मेल खा सकें (डैश सीमाएं, SVG लोगो मास्क, ग्रेडिएंट्स, फॉन्ट मेट्रिक्स — सभी संरक्षित)। +2. **शक्तियां** — शांत ✓ पंक्ति सूची आपके एजेंट द्वारा पहले से सही ढंग से की जाने वाली व्यवहार, लाइव ऑडिट डेटा से प्राप्त (स्वच्छ टूल-कॉल दर, मुख्य को कोई सीधा पुश नहीं, शून्य क्रेडेंशियल लीक, शून्य रिट्राई तूफान) — प्रत्येक तभी सामने आता है जब संबंधित नीति के पास ऑडिट विंडो में एक स्वच्छ रिकॉर्ड हो। +3. **विचित्रताएं** — क्या सरकते रहे की तालिका, गंभीरता के आधार पर रैंक किए गए: `when · what slipped + the policy that would've caught it · severity pill · seen`, जहां पुनरावृत्ति `new` (एक बार), `N× seen` (2–9 बार), या `recurring` (10+) को पढ़ता है। +4. **कैसे सुधारें** — शांत पंक्ति सूची, निर्धारित नीति में से एक: नीति का नाम सफेद रंग में, एक-पंक्ति विवरण, दाएं ओर स्थापना कमांड + कॉपी बटन। अनुभाग हेडर `enable all N → projected · ` को पढ़ता है (वह स्कोर जो आप हर सुधार लागू करने से पहुंचेंगे), और इसका `[install all]` बटन प्रत्येक निर्धारित नीति के लिए संयुक्त `failproofai policy add a b c …` कमांड को कॉपी करता है। +5. **बेहतर लौटें** — दो साइड-बाय-साइड कार्ड। बाएं: एक अनुस्मारक सेट करें (`3d` / `7d` / `14d` / `30d` कैडेंस पिकर; `/api/auth/reminder` के माध्यम से प्रमाणीकृत होने के बाद बना रहता है)। दाएं: failproof perks अनलॉक करें — `invite a friend` एक मोडल खोलता है जो कॉमा/स्पेस/न्यूलाइन-सेपरेटेड मित्र ईमेल की सूची लेता है (प्रति भेजने के लिए अधिकतम 10), उन्हें `/api/audit/invite` पर POST करता है, जो api-server के `POST /v0/invite` पर आगे बढ़ता है। api-server `invite@failproof.ai` से एक ईमेल प्रति प्राप्तकर्ता भेजता है जिसमें भेजने वाला Cc किया जाता है और `Reply-To` सेट किया जाता है, ताकि प्राप्तकर्ता देख सके कि किसने उन्हें आमंत्रित किया और भेजने वाला को अपने इनबॉक्स में एक कॉपी मिले। अनाम उपयोगकर्ता पहले `AuthDialog` के माध्यम से रूट किए जाते हैं ताकि भेजने वाले का ईमेल आमंत्रण भेजने से पहले जाना जा सके। अधिकार / perks पूर्ति एक अनुवर्ती है। -`failproofai audit` runtime द्वारा driven — अंतर्निहित scan engine, supported flags, और per-transcript cache invariants के लिए [Audit CLI](/hi/cli/audit) देखें। Dashboard सबसे हाल का result को `~/.failproofai/audit-dashboard.json` पर cache करता है (mode `0600`, single slot, new runs overwrite) ताकि revisits instant हों; **दोनों per-transcript और whole-result caches को read पर reject किया जाता है एक बार जब वे 7 days से पुरानी हों** ताकि dashboard कभी भी silently एक week-old result serve न करे — TTL के पास `/audit` अपनी empty state में गिरता है और एक fresh run के लिए prompt करता है। Report के निचले हिस्से के पास `[ re-audit now ]` को क्लिक करने से `/api/audit/run` पर `noCache: true` के साथ POST होता है — re-audit per-transcript cache को bypass करता है और silently cached result return करने के बजाय scratch से हर transcript को फिर से स्कैन करता है — और dashboard `/api/audit/status` को 1Hz पर poll करता है जब तक run समाप्त न हो जाए; एक sticky pink progress strip run के दौरान viewport के शीर्ष को pin करता है एक elapsed timer के साथ, और fresh result success पर जगह में swap होता है (कोई full-page reload नहीं; एक failed re-audit prior report को intact छोड़ता है)। Failure पर strip `RerunError.kind` (`timeout` / `network` / `post_failed`) से keyed copy के साथ red हो जाता है। Empty state (कोई cache नहीं या expired) और zero-sessions state (cache exists लेकिन scan को कोई transcripts नहीं मिले) को अलग से surface किया जाता है। +`failproofai audit` रनटाइम द्वारा संचालित — अंतर्निहित स्कैन इंजन, समर्थित फ्लैग, और प्रति-प्रतिलेख कैश अपरिवर्तनीयों के लिए [Audit CLI](/hi/cli/audit) देखें। डैशबोर्ड सबसे हाल का परिणाम `~/.failproofai/audit-dashboard.json` में कैश करता है (मोड `0600`, एकल स्लॉट, नया चलता है ओवरराइट करता है) ताकि दुबारा दौरे तुरंत हों; **प्रति-प्रतिलेख और संपूर्ण-परिणाम कैश दोनों को पढ़ने पर अस्वीकार किया जाता है एक बार वे 7 दिन से पुराने हों** ताकि डैशबोर्ड कभी भी एक सप्ताह पुराना परिणाम चुपचाप न भेजे — TTL के बाद `/audit` अपने खाली स्थिति में गिरता है और एक ताज़ा चलाने के लिए संकेत देता है। रिपोर्ट के नीचे के पास `[ re-audit now ]` पर क्लिक करने से `noCache: true` के साथ `/api/audit/run` को POST किया जाता है — पुनः-ऑडिट प्रति-प्रतिलेख कैश को बायपास करता है और कैश किए गए परिणाम को चुपचाप लौटाने के बजाय हर प्रतिलेख को शुरुआत से फिर से स्कैन करता है — और डैशबोर्ड 1Hz पर `/api/audit/status` को पोल करता है जब तक चलना समाप्त न हो जाए; व्यूपोर्ट के शीर्ष के पास एक स्टिकी गुलाबी प्रगति पट्टी चलाने के दौरान एक व्यतीत समय के साथ पिन करती है, और ताज़ा परिणाम सफलता पर स्थान में स्वैप होता है (कोई पूर्ण-पृष्ठ पुनः लोड नहीं; एक विफल पुनः-ऑडिट पूर्व रिपोर्ट को बरकरार रखता है)। विफलता पर पट्टी `RerunError.kind` को बंद करके कॉपी के साथ लाल हो जाती है (`timeout` / `network` / `post_failed`)। खाली स्थिति (कोई कैश या समाप्त) और शून्य-सेशन स्थिति (कैश मौजूद है लेकिन स्कैन ने कोई प्रतिलेख नहीं पाया) को अलग से सामने लाया जाता है। -### Policies +### नीतियां -नीतियों को प्रबंधित करने और गतिविधि की समीक्षा करने के लिए एक two-tab page। +नीतियों को प्रबंधित करने और गतिविधि की समीक्षा करने के लिए एक दो-टैब पृष्ठ। - - - एकल panel से multi-select करें कि failproofai कौन से agent CLIs को protect करता है — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, और Hermes के सभी के पास install status (`Active` / `Detected` / `Inactive`), user-scope settings path, और एक brand-colored accent के साथ एक row है। उन CLIs को चेक या अनचेक करें जिन्हें आप चाहते हैं और एक ही step में install/uninstall diff को apply करने के लिए `Apply changes` को क्लिक करें। CLIs जिनका binary PATH पर detected है वे pre-checked हैं। - - एकल क्लिक के साथ individual policies को on या off toggle करें (`~/.failproofai/policies-config.json` को write करता है — हर installed CLI में shared) - - एक policy को expand करें इसके parameters को configure करने के लिए (उन policies के लिए जो `policyParams` को support करते हैं) - - एक custom policies file path सेट करें + + - एक एकल पैनल से किस एजेंट CLIs failproofai को बहु-चयन करें — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, और Hermes सभी के पास स्थापना स्थिति (`Active` / `Detected` / `Inactive`), उपयोगकर्ता-स्कोप सेटिंग्स पथ, और एक ब्रांड-रंगीन उच्चारण के साथ एक पंक्ति है। आप जो CLIs चाहते हैं उन्हें चेक या अनचेक करें और एक चरण में इंस्टॉल/अनइंस्टॉल करने के लिए `Apply changes` पर क्लिक करें। जिन CLIs के बाइनरी PATH पर पाए जाते हैं, वे पूर्व-जांचे जाते हैं। + - एकल क्लिक के साथ व्यक्तिगत नीतियों को चालू या बंद करें (`~/.failproofai/policies-config.json` में लिखता है — हर स्थापित CLI में साझा) + - किसी नीति को इसके पैरामीटर को कॉन्फ़िगर करने के लिए विस्तारित करें (उन नीतियों के लिए जो `policyParams` समर्थन करते हैं) + - एक कस्टम नीतियां फाइल पथ सेट करें - - - सभी sessions में fired होने वाली हर hook event का पूरा paginated history - - Decision, event type, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), policy name, या session ID द्वारा filter करें - - प्रत्येक row दिखाता है: timestamp, policy name, decision, CLI badge (orange = Claude Code, purple = OpenAI Codex, blue = GitHub Copilot, emerald = Cursor Agent, amber = OpenCode, pink = Pi, indigo = Hermes, teal = OpenClaw, rose = Factory Droid, violet = Devin, cyan = Antigravity, lime = Goose), tool name, session ID, और deny/instruct decisions के कारण - - अपना transcript खोलने के लिए किसी session ID को क्लिक करें — viewer auto-detect करता है कि कौन सा CLI hook को fired किया (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) और header में matching CLI badge को render करता है + + - सभी सेशन में फायरिंग किए गए हर हुक इवेंट का पूर्ण पेजीकृत इतिहास + - निर्णय, इवेंट प्रकार, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), नीति नाम, या सेशन ID के आधार पर फ़िल्टर करें + - प्रत्येक पंक्ति दिखाती है: टाइमस्टैम्प, नीति नाम, निर्णय, CLI बैज (नारंगी = Claude Code, बैंगनी = OpenAI Codex, नीला = GitHub Copilot, एमराल्ड = Cursor Agent, एम्बर = OpenCode, गुलाबी = Pi, इंडिगो = Hermes, टील = OpenClaw, गुलाब = Factory Droid, बैंगनी = Devin, सियान = Antigravity, लाइम = Goose), टूल नाम, सेशन ID, और deny/instruct निर्णयों का कारण + - प्रतिलेख खोलने के लिए एक सेशन ID पर क्लिक करें — दर्शक स्वचालित रूप से पहचान लेता है कि कौन सी CLI ने हुक को फायर किया (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) और हेडर में मेल खाने वाले CLI बैज को प्रस्तुत करता है --- -## Auto-refresh +## ऑटो-रीफ्रेश -Dashboard के top navigation में एक auto-refresh toggle है। जब enabled हो, तो current page periodically refresh होता है ताकि नए sessions और policy activity को दिखाया जा सके जैसे-जैसे वे appear होते हैं। Long-running autonomous agent सेशन को मॉनिटर करने के लिए आवश्यक। +डैशबोर्ड के पास शीर्ष नेविगेशन में एक ऑटो-रीफ्रेश टॉगल है। सक्षम होने पर, वर्तमान पृष्ठ समय-समय पर नए सेशन और नीति गतिविधि को दिखाने के लिए ताज़ा करता है क्योंकि वे दिखाई देते हैं। लंबे समय तक चलने वाले स्वायत्त एजेंट सेशन की निगरानी के लिए आवश्यक। --- -## Pages को disable करना +## पृष्ठ अक्षम करना -अगर आपको केवल dashboard के कुछ हिस्से चाहिए, तो `FAILPROOFAI_DISABLE_PAGES` को page names की comma-separated सूची में सेट करें: +यदि आपको डैशबोर्ड के केवल कुछ भाग चाहिए, तो `FAILPROOFAI_DISABLE_PAGES` को पृष्ठ नामों की कॉमा-सेपरेटेड सूची में सेट करें: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -Valid values: `policies`, `projects`, `audit`। +वैध मान: `policies`, `projects`, `audit`। --- -## Projects path को कॉन्फ़िगर करना +## प्रोजेक्ट पथ कॉन्फ़िगर करना -डिफ़ॉल्ट रूप से, Dashboard standard Claude Code projects directory से पढ़ता है। Custom setups के लिए इसे override करें: +डिफ़ॉल्ट रूप से, डैशबोर्ड मानक Claude Code प्रोजेक्ट निर्देशिका से पढ़ता है। कस्टम सेटअप के लिए इसे ओवरराइड करें: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -121,32 +120,32 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Non-localhost host से access करना +## गैर-localhost होस्ट से एक्सेस करना -जब Dashboard को **dev mode** में (`npm run dev`) चला रहे हों और इसे `localhost` के अलावा किसी अन्य hostname से access कर रहे हों - उदाहरण के लिए, एक custom domain, एक remote IP, या एक tunneled URL - आप एक warning देख सकते हैं जैसे: +जब डैशबोर्ड को **dev मोड** में चलाया जा रहा है (`npm run dev`) और आप इसे `localhost` के अलावा किसी होस्टनाम से एक्सेस कर रहे हैं - उदाहरण के लिए, एक कस्टम डोमेन, एक रिमोट IP, या एक सुरंगबद्ध URL - आप इस तरह की एक चेतावनी देख सकते हैं: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -यह Next.js अपनी HMR (hot module reload) websocket के लिए cross-origin access को block कर रहा है, जो एक dev-only feature है। अपने host को allow करने के लिए, `--allowed-origins` flag का उपयोग करें: +यह Next.js अपने HMR (हॉट मॉड्यूल रीलोड) वेबसॉकेट को क्रॉस-ऑरिजिन एक्सेस को ब्लॉक कर रहा है, जो एक dev-only सुविधा है। अपने होस्ट को अनुमति देने के लिए, `--allowed-origins` फ्लैग का उपयोग करें: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -कई hosts या IPs के लिए, एक comma-separated सूची pass करें: +कई होस्ट या IPs के लिए, एक कॉमा-सेपरेटेड सूची पास करें: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -आप `FAILPROOFAI_ALLOWED_DEV_ORIGINS` environment variable को इसके बजाय सेट कर सकते हैं: +आप इसके बजाय `FAILPROOFAI_ALLOWED_DEV_ORIGINS` पर्यावरण चर भी सेट कर सकते हैं: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -यह केवल dev mode पर लागू होता है। जब `failproofai` (production mode) को चला रहे हों, तो कोई HMR websocket नहीं है और कोई cross-origin dev resource issue नहीं है। +यह केवल dev मोड पर लागू होता है। जब `failproofai` को चलाया जा रहा हो (production मोड), कोई HMR वेबसॉकेट नहीं है और कोई क्रॉस-ऑरिजिन dev संसाधन समस्या नहीं है। \ No newline at end of file diff --git a/docs/hi/examples.mdx b/docs/hi/examples.mdx index 8829043c..35667ee8 100644 --- a/docs/hi/examples.mdx +++ b/docs/hi/examples.mdx @@ -1,24 +1,24 @@ --- title: उदाहरण -description: "Claude Code और Agents SDK के लिए hooks सेट अप कैसे करें" +description: "Claude Code और Agents SDK के लिए hooks कैसे सेट अप करें" icon: book-open --- -आम परिस्थितियों के लिए तुरंत उपयोग के लिए तैयार उदाहरण। प्रत्येक दिखाता है कि कैसे इंस्टॉल करें और क्या अपेक्षा करें। +सामान्य परिदृश्यों के लिए तैयार उदाहरण। प्रत्येक यह दिखाता है कि कैसे इंस्टॉल करें और क्या उम्मीद करें। --- ## Claude Code के लिए hooks सेट अप करना -Failproof AI, Claude Code के साथ इसके [hooks सिस्टम](https://docs.anthropic.com/en/docs/claude-code/hooks) के माध्यम से एकीकृत होता है। जब आप `failproofai policies --install` चलाते हैं, तो यह Claude Code के `settings.json` में hook कमांड रजिस्टर करता है जो हर tool call पर चलते हैं। +Failproof AI Claude Code के साथ इसकी [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks) के माध्यम से एकीकृत होता है। जब आप `failproofai policies --install` चलाते हैं, तो यह Claude Code के `settings.json` में hook commands को रजिस्टर करता है जो हर tool call पर फायर होते हैं। - + ```bash npm install -g failproofai ``` - + ```bash failproofai policies --install ``` @@ -28,14 +28,14 @@ Failproof AI, Claude Code के साथ इसके [hooks सिस्ट cat ~/.claude/settings.json | grep failproofai ``` - आपको `PreToolUse`, `PostToolUse`, `Notification`, और `Stop` events के लिए hook entries दिखने चाहिए। + आपको `PreToolUse`, `PostToolUse`, `Notification` और `Stop` इवेंट्स के लिए hook entries दिखेंगी। ```bash claude ``` - Policies अब हर tool call पर स्वचालित रूप से चलते हैं। Claude को `sudo rm -rf /` चलाने के लिए कहने का प्रयास करें - यह ब्लॉक हो जाएगा। + अब policies हर tool call पर स्वचालित रूप से चलती हैं। Claude को `sudo rm -rf /` चलाने के लिए कहने का प्रयास करें - यह ब्लॉक हो जाएगा। @@ -43,7 +43,7 @@ Failproof AI, Claude Code के साथ इसके [hooks सिस्ट ## Agents SDK के लिए hooks सेट अप करना -यदि आप [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) के साथ बिल्ड कर रहे हैं, तो आप एक ही hook सिस्टम को प्रोग्रामेटिक रूप से उपयोग कर सकते हैं। +यदि आप [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) के साथ निर्माण कर रहे हैं, तो आप समान hook system को प्रोग्रामेटिकली उपयोग कर सकते हैं। @@ -52,20 +52,20 @@ Failproof AI, Claude Code के साथ इसके [hooks सिस्ट ``` - अपने agent process बनाते समय hook कमांड पास करें। Hooks उसी तरह चलते हैं जैसे Claude Code में - stdin/stdout JSON के माध्यम से: + अपना agent process बनाते समय hook commands पास करें। hooks Claude Code की तरह ही फायर होते हैं - stdin/stdout JSON के माध्यम से: ```bash failproofai --hook PreToolUse # हर tool से पहले कॉल किया जाता है failproofai --hook PostToolUse # हर tool के बाद कॉल किया जाता है ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "limit-to-project-dir", - description: "Agent को प्रोजेक्ट डायरेक्टरी के अंदर रखें", + description: "Agent को प्रोजेक्ट डायरेक्टरी में रखें", match: { events: ["PreToolUse"] }, fn: async (ctx) => { const path = String(ctx.toolInput?.file_path ?? ""); @@ -77,7 +77,7 @@ Failproof AI, Claude Code के साथ इसके [hooks सिस्ट }); ``` - + ```bash failproofai policies --install --custom ./my-agent-policies.js ``` @@ -86,35 +86,35 @@ Failproof AI, Claude Code के साथ इसके [hooks सिस्ट --- -## विनाशकारी कमांड ब्लॉक करें +## विनाशकारी commands को ब्लॉक करें -सबसे आम सेटअप - agents को अपरिवर्तनीय नुकसान करने से रोकें। +सबसे सामान्य सेटअप - agents को अपरिवर्तनीय नुकसान से रोकें। ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` यह क्या करता है: -- `block-sudo` - सभी `sudo` कमांड ब्लॉक करता है -- `block-rm-rf` - recursive file deletion ब्लॉक करता है -- `block-force-push` - `git push --force` ब्लॉक करता है -- `block-curl-pipe-sh` - रिमोट scripts को shell में पाइप करना ब्लॉक करता है +- `block-sudo` - सभी `sudo` commands को ब्लॉक करता है +- `block-rm-rf` - recursive file deletion को ब्लॉक करता है +- `block-force-push` - `git push --force` को ब्लॉक करता है +- `block-curl-pipe-sh` - remote scripts को shell में pipe करने को ब्लॉक करता है --- -## Secret leakage रोकें +## secret leakage को रोकें -Agents को tool output में credentials देखने या leak करने से रोकें। +Agents को credentials को देखने या tool output में leak करने से रोकें। ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -ये `PostToolUse` पर चलते हैं - एक tool चलने के बाद, ये agent को दिखाने से पहले output को साफ करते हैं। +ये `PostToolUse` पर फायर होती हैं - एक tool चलने के बाद, ये output को agent द्वारा देखे जाने से पहले साफ कर देती हैं। --- -## Agents को Slack alerts भेजें जब उन्हें ध्यान की जरूरत हो +## Slack alerts प्राप्त करें जब agents को ध्यान देने की आवश्यकता हो Slack को idle alerts भेजने के लिए notification hook का उपयोग करें। @@ -123,13 +123,13 @@ import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "slack-on-idle", - description: "Agent के इनपुट की प्रतीक्षा के समय Slack को alert भेजें", + description: "जब agent इनपुट की प्रतीक्षा कर रहा हो तो Slack को सतर्क करें", match: { events: ["Notification"] }, fn: async (ctx) => { const webhookUrl = process.env.SLACK_WEBHOOK_URL; if (!webhookUrl) return allow(); - const message = String(ctx.payload?.message ?? "Agent इनपुट की प्रतीक्षा कर रहा है"); + const message = String(ctx.payload?.message ?? "Agent प्रतीक्षा कर रहा है"); const project = ctx.session?.cwd ?? "अज्ञात"; try { @@ -142,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // अगर Slack तक पहुंच नहीं है तो agent को कभी ब्लॉक न करें + // अगर Slack अनुपलब्ध है तो कभी भी agent को ब्लॉक न करें } return allow(); @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -इसे इंस्टॉल करें: +इंस्टॉल करें: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -158,22 +158,22 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## Agents को एक branch पर रखें +## Agents को branch पर रखें -Agents को branches switch करने या protected ones को push करने से रोकें। +Agents को branches स्विच करने या protected branches में push करने से रोकें। ```javascript import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "stay-on-branch", - description: "Agent को दूसरी branches checkout करने से रोकें", + description: "Agent को अन्य branches को checkout करने से रोकें", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+checkout\s+(?!-b)/.test(cmd)) { - return deny("मौजूदा branch पर रहें। यदि आवश्यक हो तो -b के साथ एक नई branch बनाएं।"); + return deny("वर्तमान branch पर रहें। यदि आवश्यक हो तो -b के साथ एक नई branch बनाएं।"); } return allow(); }, @@ -182,22 +182,22 @@ customPolicies.add({ --- -## Commits से पहले tests की आवश्यकता करें +## Commits से पहले tests की आवश्यकता -Agents को committing से पहले tests चलाने के लिए याद दिलाएं। +Agents को commits से पहले tests चलाने के लिए याद दिलाएं। ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "test-before-commit", - description: "Agent को committing से पहले tests चलाने के लिए याद दिलाएं", + description: "Agents को commit करने से पहले tests चलाने के लिए याद दिलाएं", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+commit/.test(cmd)) { - return instruct("Committing से पहले tests चलाएं। पहले `npm test` या `bun test` का उपयोग करें।"); + return instruct("Commit करने से पहले tests चलाएं। पहले `npm test` या `bun test` का उपयोग करें।"); } return allow(); }, @@ -206,9 +206,9 @@ customPolicies.add({ --- -## एक production repo को lock down करें +## Production repo को lock down करें -एक project-level config commit करें ताकि आपकी टीम के हर developer को same policies मिलें। +एक project-level config को commit करें ताकि आपकी टीम के हर developer को समान policies मिलें। अपने repo में `.failproofai/policies-config.json` बनाएं: @@ -235,16 +235,16 @@ customPolicies.add({ ```bash git add .failproofai/policies-config.json -git commit -m "Add failproofai team policies" +git commit -m "failproofai team policies जोड़ें" ``` -हर team member जिसके पास failproofai installed है, ये rules स्वचालित रूप से pick up करेंगे। +हर टीम member जिसके पास failproofai इंस्टॉल है, ये नियम स्वचालित रूप से उठा लेंगे। --- ## Convention policies के साथ एक org-wide quality standard बनाएं -सबसे प्रभावी सेटअप: अपने repo में `.failproofai/policies/` commit करें जिसमें आपके प्रोजेक्ट के लिए tailored policies हों। हर team member को ये स्वचालित रूप से मिलते हैं — कोई install commands नहीं, कोई config changes नहीं। +सबसे प्रभावशाली सेटअप: अपने repo में `.failproofai/policies/` को commit करें जिसमें आपके प्रोजेक्ट के लिए तैयार policies हों। हर टीम member को वे स्वचालित रूप से मिलती हैं - कोई install commands नहीं, कोई config changes नहीं। @@ -256,41 +256,41 @@ git commit -m "Add failproofai team policies" // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // अपनी टीम के preferred package manager को लागू करें - // (या इसके बजाय built-in prefer-package-manager policy सक्षम करें) + // अपनी टीम के पसंदीदा package manager को लागू करें + // (या इसके बजाय built-in prefer-package-manager policy को सक्षम करें) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); - if (/\bnpm\b/.test(cmd)) return deny("npm की जगह bun का उपयोग करें।"); + if (/\bnpm\b/.test(cmd)) return deny("npm के बजाय bun का उपयोग करें।"); return allow(); }, }); - // Agent को committing से पहले tests चलाने के लिए याद दिलाएं + // Agent को commit करने से पहले tests चलाने के लिए याद दिलाएं 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("Committing से पहले tests चलाएं।"); + return instruct("Commit करने से पहले tests चलाएं।"); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "Add team quality policies" + git commit -m "Team quality policies जोड़ें" ``` - जैसे-जैसे आपकी टीम नई failure modes को हिट करती है, policies जोड़ें और push करें। हर कोई अपने अगले `git pull` पर update पाता है। ये policies एक living quality standard बन जाती हैं जो आपकी टीम के साथ बढ़ती हैं। + जैसे ही आपकी टीम नई failures का सामना करे, policies जोड़ें और push करें। हर कोई अपने अगले `git pull` पर update पाएगा। ये policies एक जीवंत quality standard बन जाती हैं जो आपकी टीम के साथ बढ़ती हैं। @@ -301,7 +301,7 @@ git commit -m "Add failproofai team policies" Repo में [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) डायरेक्टरी में शामिल है: | फाइल | यह क्या दिखाता है | -|------|---------------| -| `policies-basic.js` | Starter policies - production writes, force-push, piped scripts ब्लॉक करें | +|------|----------------| +| `policies-basic.js` | Starter policies - production writes को ब्लॉक करें, force-push, piped scripts | | `policies-notification.js` | Idle notifications और session end के लिए Slack alerts | | `policies-advanced/index.js` | Transitive imports, async hooks, PostToolUse output scrubbing, Stop event handling | \ No newline at end of file diff --git a/docs/hi/for-agents.mdx b/docs/hi/for-agents.mdx index 2947ae3f..37521024 100644 --- a/docs/hi/for-agents.mdx +++ b/docs/hi/for-agents.mdx @@ -1,38 +1,39 @@ --- -title: "एजेंटों के लिए" -description: "एक कमांड में अपने कोडिंग एजेंट को Failproof AI ज्ञान जोड़ें। Claude Code, Cursor, Windsurf और अधिक के साथ काम करता है।" +--- +title: "एजेंट के लिए" +description: "एक कमांड में अपने कोडिंग एजेंट को Failproof AI ज्ञान जोड़ें। Claude Code, Cursor, Windsurf और अन्य के साथ काम करता है।" --- -एक कमांड में अपने कोडिंग एजेंट को पूरा Failproof AI संदर्भ जोड़ें। Claude Code, Cursor, Windsurf और किसी भी अन्य एजेंट के साथ काम करता है जो कौशल का समर्थन करता है। +एक कमांड में अपने कोडिंग एजेंट को पूरा Failproof AI संदर्भ जोड़ें। Claude Code, Cursor, Windsurf और किसी भी अन्य एजेंट के साथ काम करता है जो स्किल्स को सपोर्ट करता है। ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` पता लगाता है कि आपके पास कौन से एजेंट स्थापित हैं और प्रत्येक के लिए कौशल को सही प्रारूप में स्वचालित रूप से जोड़ता है। +`npx skills` पहचानता है कि आपके पास कौन से एजेंट इंस्टॉल हैं और प्रत्येक के लिए सही फॉर्मेट में स्किल को स्वचालित रूप से जोड़ता है। -## कौशल क्या कवर करता है +## स्किल में क्या शामिल है | क्षेत्र | क्या शामिल है | |------|----------------| -| नीतियां | बिल्ट-इन नीति नाम, इवेंट प्रकार, पैरामीटर, सक्षम/अक्षम करें | -| कस्टम नीतियां | `customPolicies.add()`, मैच फ़िल्टर, `allow`/`deny`/`instruct` API | -| Context ऑब्जेक्ट | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| कॉन्फ़िगरेशन | `policies-config.json` संरचना, स्कोप मर्जिंग, `policyParams` | +| Policies | बिल्ट-इन पॉलिसी नाम, ईवेंट टाइप, पैरामीटर, सक्षम/अक्षम करें | +| Custom policies | `customPolicies.add()`, मैच फिल्टर, `allow`/`deny`/`instruct` API | +| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | +| Configuration | `policies-config.json` संरचना, स्कोप मर्जिंग, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, स्कोप | -| डैशबोर्ड | सेशन व्यूअर, नीति गतिविधि, पर्यावरण चर | -| आर्किटेक्चर | हुक हैंडलर प्रवाह, एक्जिट कोड, stdin/stdout अनुबंध | +| Dashboard | सेशन व्यूअर, पॉलिसी एक्टिविटी, एनवायरनमेंट वेरिएबल्स | +| Architecture | हुक हैंडलर फ्लो, एक्जिट कोड, stdin/stdout कॉन्ट्रैक्ट | -## क्या कौशल पूर्ण है? +## क्या स्किल संपूर्ण है? -Mintlify नेविगेशन के सभी पृष्ठों से `llms.txt` जेनरेट करता है। Failproof AI दस्तावेज़ पूरा API कवर करते हैं - हर नीति, विकल्प और उदाहरण शामिल है। यदि आपको कुछ गायब मिले, तो स्रोत `https://docs.befailproof.ai/llms-full.txt` पर है। +Mintlify नेविगेशन के सभी पेजों से `llms.txt` जेनरेट करता है। Failproof AI डॉक्स पूरे API को कवर करते हैं - हर पॉलिसी, विकल्प और उदाहरण शामिल है। यदि आपको कुछ गायब दिखता है, तो स्रोत `https://docs.befailproof.ai/llms-full.txt` पर है। -लक्षित संदर्भ के लिए, सीधे एक विशिष्ट पृष्ठ से लिंक करें: +लक्षित संदर्भ के लिए, किसी विशिष्ट पेज से सीधे लिंक करें: ```bash -# केवल कस्टम नीतियां API +# केवल custom policies API npx skills add https://docs.befailproof.ai/custom-policies -# केवल बिल्ट-इन नीतियां +# केवल built-in policies npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/hi/getting-started.mdx b/docs/hi/getting-started.mdx index 466fd550..07a8f7d5 100644 --- a/docs/hi/getting-started.mdx +++ b/docs/hi/getting-started.mdx @@ -1,7 +1,7 @@ --- --- -title: शुरुआत करना -description: "failproofai इंस्टॉल करें, policies को सक्षम करें, और अपने agents को विश्वसनीयता से चलाएं" +title: शुरुआत करें +description: "failproofai इंस्टॉल करें, policies सक्षम करें, और अपने agents को विश्वसनीय रूप से चलाएं" icon: rocket --- @@ -31,16 +31,16 @@ bun add -g failproofai ## त्वरित शुरुआत - - Policies ऐसे नियम हैं जो प्रत्येक agent tool call से पहले और बाद में चलते हैं। वे विनाशकारी कमांड, secret leakage, और अन्य विफलता मोड को पकड़ते हैं इससे पहले कि वे नुकसान पहुंचाएं। + + Policies ऐसे नियम हैं जो प्रत्येक agent tool कॉल से पहले और बाद में चलते हैं। वे विनाशकारी कमांड, secret leakage, और अन्य विफलता मोड को नुकसान पहुंचाने से पहले पकड़ते हैं। ```bash failproofai policies --install ``` - यह आपके इंस्टॉल किए गए agent CLIs में hook entries लिखता है (Claude Code के `~/.claude/settings.json`, OpenAI Codex के `~/.codex/hooks.json`, GitHub Copilot CLI के `~/.copilot/hooks/failproofai.json`, Cursor Agent के `~/.cursor/hooks.json`, OpenCode के generated plugin shim को `~/.config/opencode/plugins/failproofai.mjs` पर प्लस `~/.config/opencode/opencode.json` के `plugin` array में एक रजिस्ट्रेशन entry, Pi के `~/.pi/agent/settings.json`, Hermes के `~/.hermes/config.yaml`, OpenClaw के `~/.openclaw/openclaw.json`, Factory Droid के `~/.factory/hooks.json`, Devin CLI के `~/.config/devin/config.json`, Antigravity CLI के `~/.gemini/config/hooks.json`, या Goose के auto-discovered plugin dir को `~/.agents/plugins/failproofai/hooks/hooks.json` पर)। जब एक से अधिक मौजूद हों तो आपको prompt दिया जाएगा; prompt को छोड़ने के लिए `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (कोई भी subset) पास करें। + यह आपके इंस्टॉल किए गए agent CLIs में hook entries लिखता है (Claude Code के `~/.claude/settings.json`, OpenAI Codex के `~/.codex/hooks.json`, GitHub Copilot CLI के `~/.copilot/hooks/failproofai.json`, Cursor Agent के `~/.cursor/hooks.json`, OpenCode के `~/.config/opencode/plugins/failproofai.mjs` पर generated plugin shim प्लस `~/.config/opencode/opencode.json` के `plugin` array में registration entry, Pi के `~/.pi/agent/settings.json`, Hermes के `~/.hermes/config.yaml`, OpenClaw के `~/.openclaw/openclaw.json`, Factory Droid के `~/.factory/hooks.json`, Devin CLI के `~/.config/devin/config.json`, Antigravity CLI के `~/.gemini/config/hooks.json`, या Goose के auto-discovered plugin dir पर `~/.agents/plugins/failproofai/hooks/hooks.json`)। जब एक से अधिक मौजूद हों तो आपको prompt दिया जाएगा; prompt को छोड़ने के लिए `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (कोई भी subset) पास करें। - GitHub Copilot CLI, Cursor Agent, OpenCode, और Pi समर्थन **beta** में हैं — `--cli copilot`, `--cli cursor`, `--cli opencode`, या `--cli pi` के साथ इंस्टॉल करें। Hermes (hermes-agent, एक Slack/Telegram gateway) user-scope के साथ `--cli hermes` से इंस्टॉल होता है और एक **offline audit source** भी है। OpenClaw (openclaw gateway, एक self-hosted multi-channel assistant) user-scope के साथ `--cli openclaw` से इंस्टॉल होता है — enforcement इसके in-process plugin hooks के माध्यम से चलता है (`before_agent_finalize` एक real turn-end gate है, इसलिए `require-*-before-stop` builtins को enforce करते हैं) — और एक **offline audit source** भी है। Factory Droid (`droid`) `--cli factory` के साथ इंस्टॉल होता है (user + project scope) और एक **offline audit source** भी है। Devin CLI (`devin`, Cognition) `--cli devin` के साथ इंस्टॉल होता है (user + project scope) और एक **offline audit source** भी है। Antigravity CLI (`agy`) `--cli antigravity` के साथ इंस्टॉल होता है (user + project scope) और एक **offline audit source** भी है। Goose (codename goose, Block) `--cli goose` के साथ इंस्टॉल होता है (user + project scope) — installer बस एक plugin dir को `~/.agents/plugins/failproofai/` पर रखता है जो Goose auto-discovers करता है, और यह एक **offline audit source** भी है। + GitHub Copilot CLI, Cursor Agent, OpenCode, और Pi support **beta** हैं — `--cli copilot`, `--cli cursor`, `--cli opencode`, या `--cli pi` के साथ इंस्टॉल करें। Hermes (hermes-agent, एक Slack/Telegram gateway) `--cli hermes` के साथ user-scope में इंस्टॉल होता है और **यह भी** एक offline audit source है। OpenClaw (openclaw gateway, एक self-hosted multi-channel assistant) `--cli openclaw` के साथ user-scope में इंस्टॉल होता है — enforcement इसके in-process plugin hooks के माध्यम से चलता है (`before_agent_finalize` एक real turn-end gate है, इसलिए `require-*-before-stop` builtins enforce करते हैं) — और **यह भी** एक offline audit source है। Factory Droid (`droid`) `--cli factory` के साथ इंस्टॉल होता है (user + project scope) और **यह भी** एक offline audit source है। Devin CLI (`devin`, Cognition) `--cli devin` के साथ इंस्टॉल होता है (user + project scope) और **यह भी** एक offline audit source है। Antigravity CLI (`agy`) `--cli antigravity` के साथ इंस्टॉल होता है (user + project scope) और **यह भी** एक offline audit source है। Goose (codename goose, Block) `--cli goose` के साथ इंस्टॉल होता है (user + project scope) — installer बस `~/.agents/plugins/failproofai/` पर एक plugin dir डालता है जिसे Goose auto-discover करता है, और यह **भी** एक offline audit source है। ```bash failproofai policies --install --scope project @@ -58,61 +58,61 @@ bun add -g failproofai failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` - + ```bash failproofai policies ``` - हर policy दिखाता है, चाहे वह सक्षम हो, और कोई भी configured parameters। + प्रत्येक policy, चाहे वह सक्षम हो, और कोई भी configured parameters दिखाता है। ```bash failproofai ``` - `http://localhost:8020` पर एक local dashboard खोलता है जहां आप sessions browse कर सकते हैं, tool calls को inspect कर सकते हैं, और policies को manage कर सकते हैं। + `http://localhost:8020` पर एक local dashboard खोलता है जहां आप sessions browse कर सकते हैं, tool calls inspect कर सकते हैं, और policies manage कर सकते हैं। - Claude Code को सामान्य तरीके से शुरू करें। यदि agent कुछ risky करने का प्रयास करता है, तो failproofai स्वचालित रूप से इसे intercept करता है। इसे unattended चलाते हुए छोड़ें और dashboard में देखें कि क्या हुआ। + Claude Code को सामान्य रूप से शुरू करें। यदि agent कुछ जोखिम भरा करने का प्रयास करे, तो failproofai स्वचालित रूप से इसे intercept करता है। इसे unattended चलाने दें और dashboard में देखें कि क्या हुआ। --- -## Policies कैसे काम करते हैं +## Policies कैसे काम करती हैं हर बार जब एक agent एक tool चलाता है, Claude Code failproofai को एक subprocess के रूप में कॉल करता है: ```text -Claude Code → failproofai --hook PreToolUse → stdin JSON को पढ़ता है +Claude Code → failproofai --hook PreToolUse → stdin JSON पढ़ता है policies का मूल्यांकन करता है - stdout में decision लिखता है + stdout को decision लिखता है ``` -प्रत्येक policy तीन निर्णयों में से एक को return करता है: +प्रत्येक policy तीन निर्णयों में से एक देता है: - **allow** - agent सामान्य रूप से आगे बढ़ता है -- **deny** - कार्रवाई blocked है, agent को कारण बताया जाता है +- **deny** - कार्रवाई को blocked किया जाता है, agent को बताया जाता है कि क्यों - **instruct** - agent के prompt में अतिरिक्त context जोड़ा जाता है -Policies आपकी local process में चलती हैं। कुछ भी दूरस्थ सेवा को नहीं भेजा जाता। +Policies आपकी local process में चलती हैं। कुछ भी किसी remote service को नहीं भेजा जाता है। --- -## Convention-based policies के साथ team policies सेट अप करें +## Convention-based policies के साथ team policies सेट करें -अपनी team में गुणवत्ता मानकों को स्थापित करने का सबसे तेज़ तरीका `.failproofai/policies/` convention है। इस निर्देशिका में policy files रखें और वे स्वचालित रूप से लोड होते हैं — कोई flags, कोई config changes, कोई install commands नहीं। +अपनी पूरी team में quality standards स्थापित करने का सबसे तेज़ तरीका `.failproofai/policies/` convention है। इस directory में policy files डालें और वे स्वचालित रूप से loaded होती हैं — कोई flags नहीं, कोई config changes नहीं, कोई install commands नहीं। - + ```bash mkdir -p .failproofai/policies ``` - Starter examples को copy करें या अपने खुद के बनाएं: + Starter examples को कॉपी करें या अपना खुद का लिखें: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -130,38 +130,40 @@ Policies आपकी local process में चलती हैं। कु fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Commit करने से पहले tests चलाएं।"); + return instruct("Committing से पहले tests चलाएं।"); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - हर team member जिसके पास failproofai installed है, ये policies स्वचालित रूप से उठाता है। कोई per-developer setup की जरूरत नहीं। + प्रत्येक team member जिसके पास failproofai installed है, ये policies स्वचालित रूप से pick up कर सकता है। कोई per-developer setup की आवश्यकता नहीं है। -`.failproofai/policies/` को अपने repo में commit करें ताकि पूरी team एक जैसे मानकों को साझा करे। जैसे ही आपकी team नई विफलता मोड की खोज करे, policies जोड़ें और push करें — हर कोई अपने अगले `git pull` पर update प्राप्त करता है। समय के साथ ये policies एक जीवंत गुणवत्ता मानक बन जाते हैं जो लगातार सुधारते रहते हैं। +`.failproofai/policies/` को अपने repo में commit करें ताकि पूरी team समान standards share करे। जब आपकी team नई failure modes खोजे, policies जोड़ें और push करें — सभी को अपने अगले `git pull` पर update मिलेगा। समय के साथ ये policies एक living quality standard बन जाती हैं जो लगातार improve हो रही है। --- -## डेटा स्टोरेज +## डेटा storage सभी configuration और logs आपकी machine पर रहते हैं: -| Path | क्या store करता है | +| Path | यह क्या store करता है | |------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | Global policy config | +| `~/.failproofai/policies-config.json` | Global policy config | +| `~/.failproofai/policies/` | आपकी अपनी policies — `*-policies.mjs` में डालें, कोई config की जरूरत नहीं | +| `~/.failproofai/policies/cloud-policies/` | आपके organisation द्वारा इस machine पर deployed policies | | `~/.failproofai/hook-activity/` | Hook execution history (paged JSONL) | -| `~/.failproofai/logs/` | Debug logs custom hook errors के लिए | +| `~/.failproofai/logs/` | Custom hook errors के लिए debug logs | | `.failproofai/policies-config.json` | Per-project config (committed) | | `.failproofai/policies-config.local.json` | Personal overrides (gitignored) | @@ -173,7 +175,7 @@ Policies आपकी local process में चलती हैं। कु failproofai policies --uninstall ``` -`~/.claude/settings.json` से hook entries को हटाता है। `~/.failproofai/` में config files को रखा जाता है। +`~/.claude/settings.json` से hook entries हटाता है। `~/.failproofai/` में config files को रखा जाता है। --- @@ -194,7 +196,7 @@ failproofai policies --uninstall - Sessions को monitor करें और policy activity को review करें + Sessions monitor करें और policy activity review करें \ No newline at end of file diff --git a/docs/hi/introduction.mdx b/docs/hi/introduction.mdx index 2cda61ac..ef514572 100644 --- a/docs/hi/introduction.mdx +++ b/docs/hi/introduction.mdx @@ -1,42 +1,41 @@ --- ---- title: "Failproof AI" -description: "FailproofAI आपके AI agents को 39 built-in failure policies देता है जो एक ही install में loops, secret leaks, destructive tool calls और बहुत कुछ को पकड़ते हैं।" +description: "FailproofAI AI एजेंटों को 39 बिल्ट-इन फेलियर पॉलिसीज देता है जो लूप्स, सीक्रेट लीक्स, डिस्ट्रक्टिव टूल कॉल्स, और बहुत कुछ एक ही इंस्टॉल में कैच करते हैं।" --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -**AI failure handling**, **error recovery**, और **LLM reliability** के लिए Hooks और policies। अपने AI agents को **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI**, और **Agents SDK** पर विश्वसनीय और स्वायत्त रूप से चलता रहें। +**AI फेलियर हैंडलिंग**, **एरर रिकवरी**, और **LLM रिलायबिलिटी** के लिए हुक्स और पॉलिसीज। अपने AI एजेंटों को **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI**, और **Agents SDK** के across विश्वसनीय और स्वायत्त रूप से चलते रहें। -AI agents पूर्वानुमानित तरीकों से विफल होते हैं। वे विनाशकारी commands चलाते हैं, secrets लीक करते हैं, task से भटकते हैं, loops में फंस जाते हैं, या सीधे main में push करते हैं। अगर बिना निरीक्षण के छोड़ दिए जाएं, तो छोटी failures बड़े outages, लीक किए गए credentials और खोए हुए काम में बदल जाती हैं। +AI एजेंटें पूर्वानुमानित तरीकों से फेल करते हैं। वे डिस्ट्रक्टिव कमांड्स चलाते हैं, सीक्रेट्स लीक करते हैं, काम से भटकते हैं, लूप्स में फंस जाते हैं, या सीधे मेन पर पुश करते हैं। बिना निगरानी के, छोटी फेलियर्स बड़े आउटेजेस, लीक किए गए क्रेडेंशियल्स, और खोए हुए काम में बदल जाती हैं। -FailproofAI इसे **policies** के साथ हल करता है। ये rules हर agent tool call में hook करते हैं ताकि **failures को detect** करें, **उन्हें mitigate** करें (block, instruct, sanitize), और जब कुछ attention की जरूरत हो तो **आपको alert** करें। एक local dashboard आपको afterward में हर tool call, agent failure और recovery action को review करने देता है। +FailproofAI इसे **पॉलिसीज** से हल करता है। ये नियम हर एजेंट टूल कॉल में हुक करते हैं ताकि **फेलियर्स को डिटेक्ट करें**, **उन्हें कम करें** (ब्लॉक, इंस्ट्रक्ट, सैनिटाइज करें), और **आपको अलर्ट करें** जब कुछ ध्यान चाहिए। एक लोकल डैशबोर्ड आपको हर टूल कॉल, एजेंट फेलियर, और रिकवरी एक्शन की बाद में रिव्यू करने देता है। -Transcripts और policy evaluation आपकी machine पर रहते हैं। Data सिर्फ तब भेजा जाता है जब आप explicitly किसी online feature का उपयोग करते हैं, जैसे authenticated audit reminders या invitations। +ट्रांसक्रिप्ट्स और पॉलिसी इवैलुएशन आपकी मशीन पर रहते हैं। डेटा केवल तब भेजा जाता है जब आप स्पष्ट रूप से एक ऑनलाइन फीचर का उपयोग करते हैं, जैसे ऑथेंटिकेटेड ऑडिट रिमाइंडर्स या इनविटेशन्स। ## शुरुआत करें - - विनाशकारी commands को block करें, secret leakage को रोकें, agents को project boundaries के अंदर रखें, और बहुत कुछ। सब कुछ बॉक्स से बाहर। + + डिस्ट्रक्टिव कमांड्स को ब्लॉक करें, सीक्रेट लीकेज को रोकें, एजेंटों को प्रोजेक्ट बाउंड्रीज के अंदर रखें, और बहुत कुछ। सब कुछ बॉक्स से ही बाहर। - - JavaScript में अपने खुद के rules लिखें एक simple allow / deny / instruct API के साथ। + + JavaScript में अपने नियम लिखें एक सरल allow / deny / instruct API के साथ। - - देखें कि आपके agents ने आपके दूर रहने के दौरान क्या किया। Sessions browse करें, tool calls को inspect करें, उन जगहों को review करें जहां policies fired हुई। + + देखें आपके एजेंटें आपके दूर रहते हुए क्या करते थे। सेशन्स ब्राउज करें, टूल कॉल्स इंस्पेक्ट करें, रिव्यू करें जहां पॉलिसीज फायर हुईं। - - किसी भी policy को बिना code के tune करें। Per-project या globally allowlists, protected branches, या thresholds set करें। + + बिना कोड के किसी भी पॉलिसी को ट्यून करें। एलाउलिस्ट्स, प्रोटेक्टेड ब्रांचेस, या थ्रेशहोल्ड्स प्रति-प्रोजेक्ट या ग्लोबली सेट करें। -## त्वरित शुरुआत +## क्विक स्टार्ट @@ -51,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # policies enable करें (या skip करें — `failproofai` पहली run पर उन्हें set करने का offer देगा) -failproofai # dashboard launch करें +failproofai policies --install # पॉलिसीज को एनेबल करें (या स्किप करें — `failproofai` पहली रन पर सेटअप करने का ऑफर देगा) +failproofai # डैशबोर्ड लॉन्च करें ``` -पूर्ण walkthrough के लिए [Getting started](/hi/getting-started) guide देखें। \ No newline at end of file +पूरे वॉकथ्रू के लिए [Getting started](/hi/getting-started) गाइड देखें। \ No newline at end of file diff --git a/docs/hi/package-aliases.mdx b/docs/hi/package-aliases.mdx index e5fd0552..256487a5 100644 --- a/docs/hi/package-aliases.mdx +++ b/docs/hi/package-aliases.mdx @@ -1,27 +1,26 @@ --- ---- title: Package Aliases -description: "पंजीकृत typosquat-prevention aliases और वे कैसे काम करती हैं" +description: "पंजीकृत typosquat-prevention aliases और वे कैसे काम करते हैं" icon: copy --- ## Official package -Canonical npm package **`failproofai`** है: +canonical npm package है **`failproofai`**: ```bash npm install -g failproofai -# या +# or bun add -g failproofai ``` --- -## हम alias names का स्वामित्व क्यों रखते हैं +## हम alias names को क्यों own करते हैं -Typosquatting एक आम supply-chain attack है जहाँ एक malicious actor एक package name को register करता है जो एक लोकप्रिय package से एक keystroke दूर होता है। जो उपयोगकर्ता install command को गलत तरीके से type करते हैं, वे attacker-controlled code चलाते हैं जिसके पास पूर्ण system access होता है - बिल्कुल वही threat जिससे Failproof AI की रक्षा करने के लिए डिज़ाइन किया गया है। +Typosquatting एक सामान्य supply-chain attack है जहां एक malicious actor किसी लोकप्रिय package के नाम के एक keystroke दूरी पर एक package name register करता है। जो users install command में गलती से टाइप करते हैं, वे attacker-controlled code को चलाते हैं जिसके पास पूरी system access होती है - बिल्कुल वही तरह का खतरा जिसे रोकने के लिए Failproof AI डिजाइन किया गया है। -इस surface को खत्म करने के लिए, **हम `failproofai` के सभी common misspellings और formatting variants को npm पर पहले से ही अपने कब्जे में करते हैं**। इनमें से कोई भी नाम किसी third party द्वारा register नहीं किया जा सकता। प्रत्येक एक thin proxy है जो real `failproofai` package को install करता है और सौंपता है। +इस surface को समाप्त करने के लिए, **हम npm पर `failproofai` के सभी सामान्य misspellings और formatting variants को पहले ही own करते हैं**। इन नामों में से कोई भी third party द्वारा register नहीं किया जा सकता। प्रत्येक एक thin proxy है जो असली `failproofai` package को install और delegate करता है। --- @@ -32,11 +31,11 @@ Typosquatting एक आम supply-chain attack है जहाँ एक malic | Package | Status | |---------|--------| | `failproof` | ✅ Published | -| `failproof-ai` | ⏳ npm support के लिए लंबित | -| `fail-proof-ai` | ⏳ npm support के लिए लंबित | -| `failproof_ai` | ⏳ npm support के लिए लंबित | -| `fail_proof_ai` | ⏳ npm support के लिए लंबित | -| `fail-proofai` | ⏳ npm support के लिए लंबित | +| `failproof-ai` | ⏳ Pending npm support | +| `fail-proof-ai` | ⏳ Pending npm support | +| `failproof_ai` | ⏳ Pending npm support | +| `fail_proof_ai` | ⏳ Pending npm support | +| `fail-proofai` | ⏳ Pending npm support | **`failprof*` typos** - "proof" से एक `o` गायब: @@ -44,9 +43,9 @@ Typosquatting एक आम supply-chain attack है जहाँ एक malic |---------|--------| | `failprof` | ✅ Published | | `failprof-ai` | ✅ Published | -| `failprofai` | ⏳ npm support के लिए लंबित | -| `fail-prof-ai` | ⏳ npm support के लिए लंबित | -| `failprof_ai` | ⏳ npm support के लिए लंबित | +| `failprofai` | ⏳ Pending npm support | +| `fail-prof-ai` | ⏳ Pending npm support | +| `failprof_ai` | ⏳ Pending npm support | **`faliproof*` typos** - transposed `a` और `i`: @@ -54,30 +53,30 @@ Typosquatting एक आम supply-chain attack है जहाँ एक malic |---------|--------| | `faliproof` | ✅ Published | | `faliproof-ai` | ✅ Published | -| `faliproofai` | ⏳ npm support के लिए लंबित | +| `faliproofai` | ⏳ Pending npm support | -> **लंबित क्यों?** npm की spam-prevention policy उन नामों को block करती है जो punctuation को हटाने और similarity checks चलाने के बाद एक existing package के समान string में normalize होते हैं। हमने इन नामों को anti-squatting के उद्देश्यों के लिए reserve करने के लिए npm support से संपर्क किया है। ये approval के बाद activate किए जाएंगे। +> **क्यों pending है?** npm की spam-prevention policy उन नामों को block करती है जो punctuation को हटाने और similarity checks को चलाने के बाद किसी existing package के समान string में normalize होते हैं। हमने npm support से contact किया है इन नामों को anti-squatting purposes के लिए reserve करने के लिए। ये approval मिलने के बाद activate होंगे। -आप यह सत्यापित कर सकते हैं कि कोई भी published alias हमारे द्वारा owned है: +आप यह verify कर सकते हैं कि कोई भी published alias हमारे द्वारा owned है: ```bash npm info failproof -# देखें: maintainers field में "ExosphereHost Inc." +# Look for: "ExosphereHost Inc." in the maintainers field ``` --- -## Aliases कैसे काम करती हैं +## Aliases कैसे काम करते हैं प्रत्येक alias package: -1. `failproofai` को एक dependency के रूप में सूचीबद्ध करता है - तो real package install होता है और इसका binary available हो जाता है -2. अपने स्वयं के नाम के अनुरूप एक binary को expose करता है (उदाहरण के लिए `failprof-ai`) जो सभी arguments को `failproofai` binary को proxy करता है +1. `failproofai` को dependency के रूप में list करता है - इसलिए असली package install होता है और इसका binary उपलब्ध हो जाता है +2. एक binary expose करता है जो अपने नाम से match करता है (उदाहरण के लिए `failprof-ai`) जो सभी arguments को `failproofai` binary को proxy करता है -Proxy एक two-line Node script है; कोई logic नहीं है, कोई network calls नहीं हैं, और कोई data collection नहीं है जो `failproofai` स्वयं करता है उसके अलावा। +Proxy एक two-line Node script है; इसमें कोई logic, कोई network calls, और कोई data collection नहीं है जो `failproofai` स्वयं करता है उससे अतिरिक्त। --- -## यदि आपको कोई ऐसा नाम मिले जिसे हमने miss किया है +## अगर आपको कोई नाम मिला जिसे हमने छोड़ दिया [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) पर एक issue खोलें और हम इसे register करेंगे। \ No newline at end of file diff --git a/docs/hi/testing.mdx b/docs/hi/testing.mdx index 62be5cf0..9e29c609 100644 --- a/docs/hi/testing.mdx +++ b/docs/hi/testing.mdx @@ -4,7 +4,7 @@ description: "यूनिट टेस्ट, E2E टेस्ट और टे icon: flask-vial --- -failproofai के दो टेस्ट सूट हैं: **यूनिट टेस्ट** (तेज़, मॉक किए गए) और **एंड-टू-एंड टेस्ट** (वास्तविक सबप्रोसेस आह्वान)। +failproofai के दो टेस्ट सूट हैं: **यूनिट टेस्ट** (तेज़, मॉक्ड) और **एंड-टू-एंड टेस्ट** (वास्तविक subprocess आमंत्रण)। --- @@ -14,16 +14,16 @@ failproofai के दो टेस्ट सूट हैं: **यूनिट # सभी यूनिट टेस्ट एक बार चलाएं bun run test:run -# यूनिट टेस्ट को वॉच मोड में चलाएं +# यूनिट टेस्ट को watch mode में चलाएं bun run test -# E2E टेस्ट चलाएं (सेटअप की आवश्यकता है - नीचे देखें) +# E2E टेस्ट चलाएं (सेटअप आवश्यक - नीचे देखें) bun run test:e2e -# बिना बिल्ड किए टाइप-चेक करें +# बिना build किए type-check करें bunx tsc --noEmit -# लिंट करें +# Lint करें bun run lint ``` @@ -31,20 +31,20 @@ bun run lint ## यूनिट टेस्ट -यूनिट टेस्ट `__tests__/` में रहते हैं और [Vitest](https://vitest.dev) को `jsdom` के साथ उपयोग करते हैं। +यूनिट टेस्ट `__tests__/` में रहते हैं और [Vitest](https://vitest.dev) के साथ `jsdom` का उपयोग करते हैं। ```text __tests__/ hooks/ - builtin-policies.test.ts # प्रत्येक बिल्टइन के लिए नीति तर्क - hooks-config.test.ts # कॉन्फ़िग लोडिंग और स्कोप मर्जिंग - policy-evaluator.test.ts # पैरामीटर इंजेक्शन और मूल्यांकन क्रम + builtin-policies.test.ts # प्रत्येक builtin के लिए Policy logic + hooks-config.test.ts # Config लोडिंग और scope मर्जिंग + policy-evaluator.test.ts # Param इंजेक्शन और मूल्यांकन क्रम custom-hooks-registry.test.ts # globalThis रजिस्ट्री add/get/clear - custom-hooks-loader.test.ts # ESM लोडर, ट्रांजिटिव इंपोर्ट, एरर हैंडलिंग + custom-hooks-loader.test.ts # ESM लोडर, transitive imports, error handling manager.test.ts # install/remove/list ऑपरेशन components/ - sessions-list.test.tsx # सेशन सूची घटक - project-list.test.tsx # प्रोजेक्ट सूची घटक + sessions-list.test.tsx # सेशन सूची कंपोनेंट + project-list.test.tsx # प्रोजेक्ट सूची कंपोनेंट ... lib/ logger.test.ts @@ -61,7 +61,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### एक नीति यूनिट टेस्ट लिखना +### एक policy यूनिट टेस्ट लिखना ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -110,11 +110,11 @@ describe("block-sudo", () => { ## एंड-टू-एंड टेस्ट -E2E टेस्ट वास्तविक `failproofai` बाइनरी को एक सबप्रोसेस के रूप में आह्वान करते हैं, एक JSON पेलोड को stdin में पाइप करते हैं, और stdout आउटपुट और एक्जिट कोड पर आश्वास करते हैं। यह पूर्ण एकीकरण पथ का परीक्षण करता है जो Claude Code उपयोग करता है। +E2E टेस्ट वास्तविक `failproofai` बाइनरी को एक subprocess के रूप में आमंत्रित करते हैं, stdin को एक JSON पेलोड pipe करते हैं, और stdout आउटपुट और exit code पर assertion करते हैं। यह पूर्ण integration path का परीक्षण करता है जो Claude Code उपयोग करता है। ### सेटअप -E2E टेस्ट रेपो स्रोत से सीधे बाइनरी चलाते हैं। पहली बार चलाने से पहले, CJS बंडल को बनाएं जो कस्टम हुक फाइलें `'failproofai'` से इंपोर्ट करते समय उपयोग करती हैं: +E2E टेस्ट बाइनरी को सीधे repo source से चलाते हैं। पहली बार चलाने से पहले, CJS bundle बनाएं जो custom hook फ़ाइलें `'failproofai'` से import करते समय उपयोग करती हैं: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,21 +126,21 @@ bun build src/index.ts --outdir dist --target node --format cjs bun run test:e2e ``` -जब भी आप सार्वजनिक हुक API (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, या `src/hooks/policy-types.ts`) को बदलते हैं, तो `dist/` को पुनः बनाएं। +जब भी आप public hook API को बदलते हैं (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, या `src/hooks/policy-types.ts`), तो `dist/` को फिर से बनाएं। ### E2E टेस्ट संरचना ```text __tests__/e2e/ helpers/ - hook-runner.ts # बाइनरी स्पॉन करें, पेलोड JSON पाइप करें, एक्जिट कोड + stdout + stderr कैप्चर करें - fixture-env.ts # कॉन्फ़िग फाइलों के साथ प्रति-टेस्ट अलग-थलग अस्थायी निर्देशिकाएं - payloads.ts # प्रत्येक इवेंट प्रकार के लिए Claude-सटीक पेलोड फैक्टरीज़ + hook-runner.ts # बाइनरी को spawn करें, पेलोड JSON को pipe करें, exit code + stdout + stderr कैप्चर करें + fixture-env.ts # config फ़ाइलों के साथ प्रति-टेस्ट अलग-थलग अस्थायी निर्देशिकाएं + payloads.ts # प्रत्येक event type के लिए Claude-सटीक पेलोड फैक्ट्रीज़ hooks/ - builtin-policies.e2e.test.ts # वास्तविक सबप्रोसेस के साथ प्रत्येक बिल्टइन नीति - custom-hooks.e2e.test.ts # कस्टम हुक लोडिंग और मूल्यांकन - config-scopes.e2e.test.ts # प्रोजेक्ट/लोकल/ग्लोबल भर में कॉन्फ़िग मर्जिंग - policy-params.e2e.test.ts # प्रत्येक पैरामीटराइज़्ड नीति के लिए पैरामीटर इंजेक्शन + builtin-policies.e2e.test.ts # वास्तविक subprocess के साथ प्रत्येक builtin policy + custom-hooks.e2e.test.ts # कस्टम hook लोडिंग और मूल्यांकन + config-scopes.e2e.test.ts # project/local/global में Config मर्जिंग + policy-params.e2e.test.ts # प्रत्येक parameterized policy के लिए Parameter इंजेक्शन ``` ### E2E हेल्पर्स का उपयोग करना @@ -151,8 +151,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - अस्थायी डायरेक्टरी; payload.cwd के रूप में पास करें .failproofai/policies-config.json को उठाने के लिए -// env.home - अलग-थलग होम डायरेक्टरी; कोई वास्तविक ~/.failproofai लीक नहीं +// env.cwd - अस्थायी निर्देशिका; .failproofai/policies-config.json को चुनने के लिए payload.cwd के रूप में पास करें +// env.home - अलग-थलग home निर्देशिका; कोई वास्तविक ~/.failproofai लीक नहीं env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` `afterEach` क्लीनअप को स्वचालित रूप से पंजीकृत करता है। +`createFixtureEnv()` स्वचालित रूप से `afterEach` सफाई को पंजीकृत करता है। -**`runHook`** - बाइनरी को आह्वान करें: +**`runHook`** - बाइनरी को आमंत्रित करें: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - तैयार पेलोड फैक्टरीज़: +**`Payloads`** - तैयार पेलोड फैक्ट्रीज़: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -231,30 +231,30 @@ describe("block-rm-rf (E2E)", () => { }); ``` -### E2E प्रतिक्रिया आकार +### E2E response आकार -| निर्णय | एक्जिट कोड | stdout | +| निर्णय | Exit code | stdout | |----------|-----------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Instruct (गैर-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | खाली stdout; कारण stderr में | +| Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Stop instruct | `2` | खाली stdout; stderr में कारण | | Allow | `0` | खाली स्ट्रिंग | -### Vitest कॉन्फ़िग +### Vitest कॉन्फ़िगरेशन -E2E टेस्ट `vitest.config.e2e.mts` का उपयोग करते हैं: +E2E टेस्ट `vitest.config.e2e.mts` का उपयोग करते हैं जिसमें है: -- `environment: "node"` - ब्राउज़र ग्लोबल्स की आवश्यकता नहीं है -- `pool: "forks"` - सच्चा प्रक्रिया अलगाव (टेस्ट सबप्रोसेस स्पॉन करते हैं) -- `testTimeout: 20_000` - प्रति टेस्ट 20 सेकंड (बाइनरी स्टार्टअप + हुक मूल्यांकन) +- `environment: "node"` - कोई ब्राउज़र globals आवश्यक नहीं +- `pool: "forks"` - सच्चा process isolation (टेस्ट subprocesses को spawn करते हैं) +- `testTimeout: 20_000` - प्रति टेस्ट 20s (बाइनरी startup + hook eval) -`forks` पूल महत्वपूर्ण है: थ्रेड-आधारित वर्कर्स `globalThis` साझा करते हैं, जो सबप्रोसेस-स्पॉनिंग टेस्ट में हस्तक्षेप कर सकता है। प्रक्रिया-आधारित फोर्क इससे बचते हैं। +`forks` pool महत्वपूर्ण है: thread-आधारित workers `globalThis` को साझा करते हैं, जो subprocess-spawning टेस्ट में हस्तक्षेप कर सकता है। Process-आधारित forks इससे बचते हैं। --- ## CI -पूरा CI रन (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) मर्ज करने से पहले पास होना आवश्यक है। E2E सूट समानांतर में एक अलग CI कार्य के रूप में चलता है। +संपूर्ण CI चलाव (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) को merge से पहले पास करना आवश्यक है। E2E सूट एक अलग CI job के रूप में समानांतर में चलता है। -पूर्ण प्री-मर्ज चेकलिस्ट के लिए [Contributing](../CONTRIBUTING.md) देखें। \ No newline at end of file +पूर्ण pre-merge चेकलिस्ट के लिए [Contributing](../CONTRIBUTING.md) देखें। \ No newline at end of file diff --git a/docs/i18n/README.ar.md b/docs/i18n/README.ar.md index ada41254..0f89d3c8 100644 --- a/docs/i18n/README.ar.md +++ b/docs/i18n/README.ar.md @@ -19,9 +19,9 @@ **الترجمات:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**حل فشل وقت التشغيل لعملاء الترميز.** -يربط Claude Code و Codex. يمسك الحلقات والإجراءات الخطيرة وتسرب الأسرار -قبل أن تصبح حوادث. بدون تأخير. يعمل محليًا. +**حل فشل البيئة التشغيلية لوكلاء البرمجة.** +يتكامل مع Claude Code و Codex. يمسك الحلقات والإجراءات الخطرة وتسريب الأسرار +قبل أن تصبح حوادث. زمن انتظار صفري. يعمل محليًا. @@ -31,7 +31,7 @@ --- -## واجهات سطر الأوامر المدعومة للعملاء +## واجهات سطر الأوامر المدعومة للوكلاء {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -131,32 +131,32 @@ ```sh npm install -g failproofai -failproofai policies --install # أو فقط قم بتشغيل `failproofai` وقبل المطالبة الأولى +failproofai policies --install # أو فقط قم بتشغيل `failproofai` وقبل الموجه في التشغيل الأول failproofai ``` -30 سياسة مدمجة تنشط على الفور. لوحة المعلومات في `localhost:8020`. قم بتعطيل مطالبة الحالة الأولى باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. +30 سياسة مدمجة تتفعل على الفور. لوحة المعلومات في `localhost:8020`. عطّل موجه البدء الأول باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## ما الذي يوقفه +## ما الذي توقفه -| السياسة | ما يتم حظره | +| السياسة | ما الذي تحجبه | |---|---| | `block-push-master` | الدفع المباشر إلى `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | الالتزامات والدمج وإعادة الأساس على `main` / `master` | +| `block-work-on-main` | الالتزامات والدمج وإعادة تكييف على `main` / `master` | | `block-rm-rf` | حذف الملفات بشكل متكرر | -| `sanitize-api-keys` | مفاتيح API تسرب في سياق العامل | +| `sanitize-api-keys` | مفاتيح واجهة برمجية تتسرب إلى سياق الوكيل | -→ [جميع السياسات المدمجة الـ 30](https://docs.befailproof.ai/built-in-policies) +→ [جميع 30 سياسة مدمجة](https://docs.befailproof.ai/built-in-policies) --- ## سياساتك الخاصة -أسقط ملفًا في `.failproofai/policies/` - يتم تحميله تلقائيًا، لا توجد علامات مطلوبة. -قم بالالتزام بها والفريق بأكمله سيحصل عليها في السحب التالي. +ضع ملف في `.failproofai/policies/` — فهو يُحمّل تلقائيًا، لا توجد أعلام مطلوبة. +التزم به وسيحصل الفريق بالكامل عليه في السحب التالي. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -177,8 +177,8 @@ customPolicies.add({ | القرار | التأثير | |---|---| | `allow()` | السماح بالعملية | -| `deny(message)` | حظره - الرسالة تعود إلى العامل | -| `instruct(message)` | دعه يمر، لكن أضف السياق إلى السؤال التالي للعامل | +| `deny(message)` | حظره — تُرسل الرسالة إلى الوكيل | +| `instruct(message)` | دعها تمر، لكن أضف سياق إلى موجه الوكيل التالي | → [دليل السياسات المخصصة](https://docs.befailproof.ai/custom-policies) @@ -186,9 +186,9 @@ customPolicies.add({ ## رؤية الجلسة -تم تسجيل كل استدعاء أداة يقوم به العامل محليًا. تعرض لوحة المعلومات ما تم تشغيله، -ما تم حظره، وما قالته السياسة للعامل - لذا لا تخمن -عندما يحدث خطأ ما. → [دليل لوحة المعلومات](https://docs.befailproof.ai/dashboard) +كل استدعاء أداة يقوم به وكيلك مسجل محليًا. تعرض لوحة المعلومات ما تم تشغيله +وما تم حجبه وما قالته السياسة للوكيل — بحيث لا تخمن +عندما يحدث شيء خاطئ. → [دليل لوحة المعلومات](https://docs.befailproof.ai/dashboard) --- @@ -196,35 +196,34 @@ customPolicies.add({ | | | |---|---| -| [البدء](https://docs.befailproof.ai/getting-started) | التثبيت والخطوات الأولى | -| [السياسات المدمجة](https://docs.befailproof.ai/built-in-policies) | جميع السياسات الـ 30 مع المعاملات | -| [السياسات المخصصة](https://docs.befailproof.ai/custom-policies) | اكتب الخاصة بك | +| [البدء السريع](https://docs.befailproof.ai/getting-started) | التثبيت والخطوات الأولى | +| [السياسات المدمجة](https://docs.befailproof.ai/built-in-policies) | جميع 30 سياسة مع المعاملات | +| [السياسات المخصصة](https://docs.befailproof.ai/custom-policies) | اكتب خاصتك | | [الإعدادات](https://docs.befailproof.ai/configuration) | نطاقات الإعدادات وقواعد الدمج | | [لوحة المعلومات](https://docs.befailproof.ai/dashboard) | مراقب الجلسة ونشاط السياسة | -| [الهندسة المعمارية](https://docs.befailproof.ai/architecture) | كيف يعمل نظام الخطاف | +| [البنية المعمارية](https://docs.befailproof.ai/architecture) | كيف يعمل نظام الخطاف | --- ## الترخيص -MIT مع [Commons Clause](https://commonsclause.com/) - مجاني للاستخدام الداخلي والشخصي؛ إعادة بيع failproofai نفسها تجاريًا يتطلب اتفاقية منفصلة. انظر [LICENSE](../../LICENSE) للنص الكامل. +MIT مع [Commons Clause](https://commonsclause.com/) — مجاني للاستخدام الداخلي والشخصي؛ إعادة بيع failproofai نفسها تجاريًا يتطلب اتفاقية منفصلة. انظر [LICENSE](../../LICENSE) للحصول على النص الكامل. --- ## المساهمة -انظر [CONTRIBUTING.md](../../CONTRIBUTING.md). السياسات الجديدة وحالات الحافة والترجمات كلها مرحب بها. +انظر [CONTRIBUTING.md](../../CONTRIBUTING.md). السياسات الجديدة والحالات الحدية والترجمات جميعها مرحب بها. -> **بناء قبل أن تبدأ.** قم بتشغيل `bun install && bun run build` أولاً. يعمل هذا المستودع -> خطاطيف failproofai الخاصة بها على نفسها، وهي تحل استيراد `failproofai` ضد -> حزمة `dist/` المترجمة - بدون بناء ستصاب بأخطاء خطاف `Cannot find package 'failproofai'`. +> **بناء قبل أن تبدأ.** قم بتشغيل `bun install && bun run build` أولاً. يقوم هذا المستودع +> بتشغيل خطافات failproofai الخاصة على نفسه، وهي تحل استيراد `failproofai` مقابل +> حزمة `dist/` المترجمة — بدون عملية بناء ستواجه أخطاء خطاف `Cannot find package 'failproofai'`. > أعد البناء بعد تغيير `src/`. انظر -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> [بناء قبل أن تعمل خطافات dev الداخلية في المستودع](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -بني بواسطة [Nivedit Jain](https://github.com/NiveditJain) و [Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +مصنوع بـ ❤️ من قبل [befailproof.ai](https://befailproof.ai) في SF و Bengaluru. \ No newline at end of file diff --git a/docs/i18n/README.de.md b/docs/i18n/README.de.md index e99fc89a..0ac11348 100644 --- a/docs/i18n/README.de.md +++ b/docs/i18n/README.de.md @@ -17,8 +17,8 @@ **Übersetzungen:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Laufzeit-Fehlerbehebung für Coding-Agenten.** -Greift in Claude Code und Codex ein. Erkennt Schleifen, gefährliche Aktionen und geheime Datenlecks, +**Laufzeit-Fehlerauflösung für Coding-Agenten.** +Klinkt sich in Claude Code und Codex ein. Erkennt Endlosschleifen, gefährliche Aktionen und Secret-Leaks, bevor sie zu Vorfällen werden. Keine Latenz. Läuft lokal. @@ -129,11 +129,11 @@ bevor sie zu Vorfällen werden. Keine Latenz. Läuft lokal. ```sh npm install -g failproofai -failproofai policies --install # oder einfach `failproofai` ausführen und die Erststart-Eingabeaufforderung bestätigen +failproofai policies --install # oder einfach `failproofai` ausführen und die Erststart-Eingabe bestätigen failproofai ``` -30 integrierte Richtlinien werden sofort aktiviert. Dashboard unter `localhost:8020`. Die Erststart-Eingabeaufforderung lässt sich mit `FAILPROOFAI_NO_FIRST_RUN=1` deaktivieren. +30 integrierte Richtlinien werden sofort aktiviert. Dashboard unter `localhost:8020`. Die Erststart-Eingabe lässt sich mit `FAILPROOFAI_NO_FIRST_RUN=1` deaktivieren. --- @@ -145,7 +145,7 @@ failproofai | `block-force-push` | `git push --force` | | `block-work-on-main` | Commits, Merges, Rebases auf `main` / `master` | | `block-rm-rf` | Rekursives Löschen von Dateien | -| `sanitize-api-keys` | API-Schlüssel, die in den Agenten-Kontext gelangen | +| `sanitize-api-keys` | API-Keys, die in den Agenten-Kontext gelangen | → [Alle 30 integrierten Richtlinien](https://docs.befailproof.ai/built-in-policies) @@ -153,8 +153,8 @@ failproofai ## Eigene Richtlinien -Legen Sie eine Datei in `.failproofai/policies/` ab — sie wird automatisch geladen, ohne zusätzliche Flags. -Committen Sie sie, und das gesamte Team erhält sie beim nächsten Pull. +Eine Datei in `.failproofai/policies/` ablegen — sie wird automatisch geladen, ohne weitere Flags. +Einfach committen und das gesamte Team erhält sie beim nächsten Pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -172,21 +172,21 @@ customPolicies.add({ Drei Entscheidungen stehen jeder Richtlinie zur Verfügung: -| Entscheidung | Auswirkung | +| Entscheidung | Wirkung | |---|---| -| `allow()` | Operation erlauben | +| `allow()` | Operation zulassen | | `deny(message)` | Blockieren — die Nachricht wird an den Agenten zurückgegeben | | `instruct(message)` | Durchlassen, aber dem nächsten Prompt des Agenten Kontext hinzufügen | -→ [Leitfaden für eigene Richtlinien](https://docs.befailproof.ai/custom-policies) +→ [Anleitung für eigene Richtlinien](https://docs.befailproof.ai/custom-policies) --- -## Sitzungsübersicht +## Sitzungs-Transparenz -Jeder Tool-Aufruf Ihres Agenten wird lokal protokolliert. Das Dashboard zeigt, was ausgeführt wurde, -was blockiert wurde und was die Richtlinie dem Agenten mitgeteilt hat — damit Sie bei Fehlern nicht -im Dunkeln tappen. → [Dashboard-Leitfaden](https://docs.befailproof.ai/dashboard) +Jeder Tool-Aufruf des Agenten wird lokal protokolliert. Das Dashboard zeigt, was ausgeführt wurde, +was blockiert wurde und was die Richtlinie dem Agenten mitgeteilt hat — damit man nicht rätseln muss, +wenn etwas schiefläuft. → [Dashboard-Anleitung](https://docs.befailproof.ai/dashboard) --- @@ -194,18 +194,18 @@ im Dunkeln tappen. → [Dashboard-Leitfaden](https://docs.befailproof.ai/dashboa | | | |---|---| -| [Erste Schritte](https://docs.befailproof.ai/getting-started) | Installation und erste Schritte | +| [Erste Schritte](https://docs.befailproof.ai/getting-started) | Installation und Einstieg | | [Integrierte Richtlinien](https://docs.befailproof.ai/built-in-policies) | Alle 30 Richtlinien mit Parametern | | [Eigene Richtlinien](https://docs.befailproof.ai/custom-policies) | Eigene Richtlinien schreiben | -| [Konfiguration](https://docs.befailproof.ai/configuration) | Konfigurationsbereiche und Zusammenführungsregeln | +| [Konfiguration](https://docs.befailproof.ai/configuration) | Konfigurations-Scopes und Zusammenführungsregeln | | [Dashboard](https://docs.befailproof.ai/dashboard) | Sitzungsmonitor und Richtlinienaktivität | -| [Architektur](https://docs.befailproof.ai/architecture) | Funktionsweise des Hook-Systems | +| [Architektur](https://docs.befailproof.ai/architecture) | Wie das Hook-System funktioniert | --- ## Lizenz -MIT mit [Commons Clause](https://commonsclause.com/) — kostenlos für den internen und persönlichen Gebrauch; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine gesonderte Vereinbarung. Den vollständigen Text finden Sie unter [LICENSE](../../LICENSE). +MIT mit [Commons Clause](https://commonsclause.com/) — kostenlos für den internen und privaten Einsatz; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine gesonderte Vereinbarung. Den vollständigen Text findet man in [LICENSE](../../LICENSE). --- @@ -213,13 +213,12 @@ MIT mit [Commons Clause](https://commonsclause.com/) — kostenlos für den inte Siehe [CONTRIBUTING.md](../../CONTRIBUTING.md). Neue Richtlinien, Grenzfälle und Übersetzungen sind herzlich willkommen. -> **Vor dem Start bauen.** Führen Sie zuerst `bun install && bun run build` aus. Dieses Repository führt -> failproofais eigene Hooks auf sich selbst aus, und sie lösen den `failproofai`-Import gegen das -> kompilierte `dist/`-Bundle auf — ohne einen Build erhalten Sie `Cannot find package 'failproofai'`- -> Hook-Fehler. Nach Änderungen an `src/` neu bauen. Siehe +> **Vor dem Start bauen.** Zuerst `bun install && bun run build` ausführen. Dieses Repository verwendet +> failproofais eigene Hooks auf sich selbst, und diese lösen den `failproofai`-Import gegen das +> kompilierte `dist/`-Bundle auf — ohne einen Build tritt der Hook-Fehler `Cannot find package 'failproofai'` +> auf. Nach Änderungen an `src/` neu bauen. Siehe > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Entwickelt von [Nivedit Jain](https://github.com/NiveditJain) und [Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +Mit ❤️ gebaut von [befailproof.ai](https://befailproof.ai) in SF und Bengaluru. diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md index 1be89c3e..2d1a3f03 100644 --- a/docs/i18n/README.es.md +++ b/docs/i18n/README.es.md @@ -19,7 +19,7 @@ **Resolución de fallos en tiempo de ejecución para agentes de código.** Se integra con Claude Code y Codex. Detecta bucles, acciones peligrosas y fugas de secretos -antes de que se conviertan en incidentes. Latencia cero. Se ejecuta localmente. +antes de que se conviertan en incidentes. Sin latencia. Corre localmente. @@ -133,15 +133,15 @@ failproofai policies --install # o simplemente ejecuta `failproofai` y acepta failproofai ``` -30 políticas integradas se activan de inmediato. Panel de control en `localhost:8020`. Desactiva el aviso de primera ejecución con `FAILPROOFAI_NO_FIRST_RUN=1`. +30 políticas integradas se activan de inmediato. Panel en `localhost:8020`. Desactiva el aviso de primera ejecución con `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## Qué previene +## Qué detiene | Política | Qué bloquea | |---|---| -| `block-push-master` | Envíos directos a `main` / `master` | +| `block-push-master` | Pushes directos a `main` / `master` | | `block-force-push` | `git push --force` | | `block-work-on-main` | Commits, merges y rebases en `main` / `master` | | `block-rm-rf` | Eliminación recursiva de archivos | @@ -153,8 +153,8 @@ failproofai ## Tus propias políticas -Coloca un archivo en `.failproofai/policies/` — se carga automáticamente, sin necesidad de parámetros adicionales. -Confírmalo en el repositorio y todo el equipo lo obtendrá en el próximo pull. +Añade un archivo en `.failproofai/policies/` — se carga automáticamente, sin necesidad de parámetros adicionales. +Haz commit y todo el equipo las tendrá en el próximo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -176,17 +176,17 @@ Tres decisiones disponibles para cada política: |---|---| | `allow()` | Permite la operación | | `deny(message)` | La bloquea — el mensaje se devuelve al agente | -| `instruct(message)` | La permite, pero agrega contexto al próximo prompt del agente | +| `instruct(message)` | La deja pasar, pero añade contexto al próximo prompt del agente | → [Guía de políticas personalizadas](https://docs.befailproof.ai/custom-policies) --- -## Visibilidad de la sesión +## Visibilidad de sesión -Cada llamada a herramientas que realiza tu agente se registra localmente. El panel de control muestra qué se ejecutó, +Cada llamada a herramienta que realiza tu agente se registra localmente. El panel muestra qué se ejecutó, qué fue bloqueado y qué le indicó la política al agente — para que no tengas que adivinar -cuando algo falla. → [Guía del panel de control](https://docs.befailproof.ai/dashboard) +cuando algo sale mal. → [Guía del panel](https://docs.befailproof.ai/dashboard) --- @@ -194,18 +194,18 @@ cuando algo falla. → [Guía del panel de control](https://docs.befailproof.ai/ | | | |---|---| -| [Primeros pasos](https://docs.befailproof.ai/getting-started) | Instalación y primeros pasos | -| [Políticas integradas](https://docs.befailproof.ai/built-in-policies) | Las 30 políticas con parámetros | +| [Primeros pasos](https://docs.befailproof.ai/getting-started) | Instalación y pasos iniciales | +| [Políticas integradas](https://docs.befailproof.ai/built-in-policies) | Las 30 políticas con sus parámetros | | [Políticas personalizadas](https://docs.befailproof.ai/custom-policies) | Escribe las tuyas propias | -| [Configuración](https://docs.befailproof.ai/configuration) | Ámbitos de configuración y reglas de combinación | -| [Panel de control](https://docs.befailproof.ai/dashboard) | Monitor de sesión y actividad de políticas | +| [Configuración](https://docs.befailproof.ai/configuration) | Ámbitos de configuración y reglas de fusión | +| [Panel](https://docs.befailproof.ai/dashboard) | Monitor de sesión y actividad de políticas | | [Arquitectura](https://docs.befailproof.ai/architecture) | Cómo funciona el sistema de hooks | --- ## Licencia -MIT con [Commons Clause](https://commonsclause.com/) — libre para uso interno y personal; la reventa comercial de failproofai en sí requiere un acuerdo separado. Consulta [LICENSE](../../LICENSE) para el texto completo. +MIT con [Commons Clause](https://commonsclause.com/) — gratuito para uso interno y personal; la reventa comercial de failproofai en sí requiere un acuerdo separado. Consulta [LICENSE](../../LICENSE) para el texto completo. --- @@ -213,13 +213,12 @@ MIT con [Commons Clause](https://commonsclause.com/) — libre para uso interno Consulta [CONTRIBUTING.md](../../CONTRIBUTING.md). Se aceptan nuevas políticas, casos límite y traducciones. -> **Compila antes de comenzar.** Ejecuta primero `bun install && bun run build`. Este repositorio ejecuta -> sus propios hooks de failproofai sobre sí mismo, y estos resuelven la importación de `failproofai` contra el -> bundle compilado de `dist/` — sin una compilación previa obtendrás errores de hook `Cannot find package 'failproofai'`. +> **Compila antes de empezar.** Ejecuta `bun install && bun run build` primero. Este repositorio ejecuta +> los propios hooks de failproofai sobre sí mismo, y resuelven la importación de `failproofai` contra el +> bundle compilado en `dist/` — sin una compilación previa obtendrás errores de hook `Cannot find package 'failproofai'`. > Vuelve a compilar tras modificar `src/`. Consulta > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Creado por [Nivedit Jain](https://github.com/NiveditJain) y [Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +Hecho con ❤️ por [befailproof.ai](https://befailproof.ai) en SF y Bengaluru. diff --git a/docs/i18n/README.fr.md b/docs/i18n/README.fr.md index 878c37ec..64918bd9 100644 --- a/docs/i18n/README.fr.md +++ b/docs/i18n/README.fr.md @@ -17,8 +17,8 @@ **Traductions :** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Résolution des défaillances à l'exécution pour les agents de codage.** -S'intègre à Claude Code et Codex. Détecte les boucles, les actions dangereuses et les fuites de secrets +**Résolution des échecs d'exécution pour les agents de développement.** +Se connecte à Claude Code et Codex. Détecte les boucles, les actions dangereuses et les fuites de secrets avant qu'ils ne deviennent des incidents. Zéro latence. Fonctionne en local. @@ -133,19 +133,19 @@ failproofai policies --install # ou lancez simplement `failproofai` et accepte failproofai ``` -30 politiques intégrées s'activent immédiatement. Tableau de bord accessible sur `localhost:8020`. Désactivez l'invite au premier démarrage avec `FAILPROOFAI_NO_FIRST_RUN=1`. +30 politiques intégrées s'activent immédiatement. Tableau de bord disponible sur `localhost:8020`. Désactivez l'invite au premier démarrage avec `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## Ce que ça bloque +## Ce qu'il bloque -| Politique | Ce qui est bloqué | +| Politique | Ce qu'elle bloque | |---|---| -| `block-push-master` | Pushs directs vers `main` / `master` | +| `block-push-master` | Les pushs directs vers `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | Commits, merges, rebases sur `main` / `master` | -| `block-rm-rf` | Suppression récursive de fichiers | -| `sanitize-api-keys` | Fuites de clés API dans le contexte de l'agent | +| `block-work-on-main` | Les commits, merges et rebases sur `main` / `master` | +| `block-rm-rf` | La suppression récursive de fichiers | +| `sanitize-api-keys` | Les clés API qui fuient dans le contexte de l'agent | → [Les 30 politiques intégrées](https://docs.befailproof.ai/built-in-policies) @@ -153,8 +153,8 @@ failproofai ## Vos propres politiques -Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun paramètre. -Commitez-le et toute l'équipe en bénéficiera au prochain pull. +Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun drapeau. +Commitez-le et toute l'équipe le récupère au prochain pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -174,9 +174,9 @@ Trois décisions disponibles pour chaque politique : | Décision | Effet | |---|---| -| `allow()` | Autorise l'opération | -| `deny(message)` | La bloque — le message est renvoyé à l'agent | -| `instruct(message)` | La laisse passer, mais ajoute du contexte à la prochaine invite de l'agent | +| `allow()` | Autoriser l'opération | +| `deny(message)` | La bloquer — le message est renvoyé à l'agent | +| `instruct(message)` | La laisser passer, mais ajouter du contexte au prochain prompt de l'agent | → [Guide des politiques personnalisées](https://docs.befailproof.ai/custom-policies) @@ -184,9 +184,7 @@ Trois décisions disponibles pour chaque politique : ## Visibilité de session -Chaque appel d'outil effectué par votre agent est journalisé localement. Le tableau de bord affiche ce qui s'est exécuté, -ce qui a été bloqué, et ce que la politique a communiqué à l'agent — plus besoin de chercher à tâtons -en cas de problème. → [Guide du tableau de bord](https://docs.befailproof.ai/dashboard) +Chaque appel d'outil effectué par votre agent est enregistré localement. Le tableau de bord affiche ce qui s'est exécuté, ce qui a été bloqué et ce que la politique a communiqué à l'agent — plus besoin de deviner quand quelque chose tourne mal. → [Guide du tableau de bord](https://docs.befailproof.ai/dashboard) --- @@ -194,7 +192,7 @@ en cas de problème. → [Guide du tableau de bord](https://docs.befailproof.ai/ | | | |---|---| -| [Démarrage rapide](https://docs.befailproof.ai/getting-started) | Installation et premières étapes | +| [Démarrage rapide](https://docs.befailproof.ai/getting-started) | Installation et premiers pas | | [Politiques intégrées](https://docs.befailproof.ai/built-in-policies) | Les 30 politiques avec leurs paramètres | | [Politiques personnalisées](https://docs.befailproof.ai/custom-policies) | Écrivez les vôtres | | [Configuration](https://docs.befailproof.ai/configuration) | Portées de configuration et règles de fusion | @@ -205,21 +203,20 @@ en cas de problème. → [Guide du tableau de bord](https://docs.befailproof.ai/ ## Licence -MIT avec [Commons Clause](https://commonsclause.com/) — gratuit pour un usage interne et personnel ; la revente commerciale de failproofai lui-même nécessite un accord séparé. Consultez [LICENSE](../../LICENSE) pour le texte intégral. +MIT avec [Commons Clause](https://commonsclause.com/) — gratuit pour un usage interne et personnel ; la revente commerciale de failproofai lui-même nécessite un accord séparé. Voir [LICENSE](../../LICENSE) pour le texte intégral. --- ## Contribuer -Consultez [CONTRIBUTING.md](../../CONTRIBUTING.md). Les nouvelles politiques, cas limites et traductions sont les bienvenus. +Voir [CONTRIBUTING.md](../../CONTRIBUTING.md). Nouvelles politiques, cas limites et traductions sont les bienvenus. -> **Compilez avant de commencer.** Exécutez `bun install && bun run build` en premier. Ce dépôt fait tourner -> les propres hooks de failproofai sur lui-même, et ils résolvent l'import `failproofai` depuis le -> bundle `dist/` compilé — sans compilation, vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. +> **Compilez avant de commencer.** Exécutez d'abord `bun install && bun run build`. Ce dépôt fait tourner +> ses propres hooks failproofai sur lui-même, et ils résolvent l'import `failproofai` depuis le +> bundle compilé `dist/` — sans compilation vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. > Recompilez après avoir modifié `src/`. Voir > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Créé par [Nivedit Jain](https://github.com/NiveditJain) et [Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +Construit avec ❤️ par [befailproof.ai](https://befailproof.ai) à San Francisco et Bengaluru. diff --git a/docs/i18n/README.he.md b/docs/i18n/README.he.md index 400d29af..e8ad5ac5 100644 --- a/docs/i18n/README.he.md +++ b/docs/i18n/README.he.md @@ -19,9 +19,9 @@ **תרגומים:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**פתרון כישלונות בזמן ריצה עבור סוכנים קידוד.** -מתחבר לתוך Claude Code ו-Codex. תופס לולאות, פעולות מסוכנות וגדילות סודות -לפני שהם הופכים לתקלות. חביון אפס. פועל locally. +**פתרון כשלים בזמן ריצה עבור סוכני קודינג.** +משתלב עם Claude Code ו-Codex. תופס לולאות, פעולות מסוכנות, וזליגת סודות +לפני שהם הופכים לתקלות. אפס זיהוי. פועל באופן מקומי. @@ -31,7 +31,7 @@ --- -## CLIs סוכנים נתמכים +## ממשקי CLI של סוכנים נתמכים {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -131,32 +131,32 @@ ```sh npm install -g failproofai -failproofai policies --install # או פשוט הרץ `failproofai` וקבל את הבקשה בהרצה ראשונה +failproofai policies --install # או הפעל `failproofai` וקבל את הנושא בהפעלה ראשונה failproofai ``` -30 מדיניויות מובנות מופעלות מיד. לוח בקרה ב-`localhost:8020`. השבת את בקשת ההרצה הראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. +30 מדיניות מובנות מופעלות מיד. לוח בקרה ב-`localhost:8020`. בטל את הנושא בהפעלה ראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. --- ## מה זה עוצר -| מדיניות | מה זה חוסם | +| מדיניות | מה היא חוסמת | |---|---| | `block-push-master` | דחיפות ישירות ל-`main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | commits, merges, rebases על `main` / `master` | +| `block-work-on-main` | Commits, merges, rebases ב-`main` / `master` | | `block-rm-rf` | מחיקת קבצים רקורסיבית | -| `sanitize-api-keys` | מפתחות API שנדלפים לתוך תיאום הסוכן | +| `sanitize-api-keys` | מפתחות API שדולפים להקשר הסוכן | -→ [כל 30 המדיניויות המובנות](https://docs.befailproof.ai/built-in-policies) +→ [כל 30 המדיניות המובנות](https://docs.befailproof.ai/built-in-policies) --- -## המדיניויות שלך שלך +## המדיניויות שלך -הטלה קובץ ל-`.failproofai/policies/` — הוא טוען באופן אוטומטי, ללא דגלים נדרשים. -התחייב בו והצוות כולו מקבל אותו ב-pull הבא. +שחרר קובץ ל-`.failproofai/policies/` — הוא נטען באופן אוטומטי, ללא דגלים נדרשים. +בצע commit אליו וכל הצוות שלך יקבל אותו בהשלכה הבאה. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -178,17 +178,17 @@ customPolicies.add({ |---|---| | `allow()` | אפשר את הפעולה | | `deny(message)` | חסום אותה — ההודעה חוזרת לסוכן | -| `instruct(message)` | תן לזה לעבור, אך הוסף הקשר להנחיה הבאה של הסוכן | +| `instruct(message)` | תן לה לעבור, אך הוסף הקשר להנחיה הבאה של הסוכן | -→ [מדריך מדיניויות מותאמות](https://docs.befailproof.ai/custom-policies) +→ [מדריך מדיניות מותאמות](https://docs.befailproof.ai/custom-policies) --- -## ראות session +## ראות הפגישה -כל קריאת כלי שהסוכן שלך עושה היא נרשמת locally. לוח הבקרה מציג מה רץ, -מה נחסם, והודעה שהמדיניות אמרה לסוכן — כך שאתה לא מנחש -כשמשהו משתבש. → [מדריך לוח הבקרה](https://docs.befailproof.ai/dashboard) +כל קריאת כלי שהסוכן שלך עושה מתועדת באופן מקומי. לוח הבקרה מציג מה רץ, +מה נחסם, ומה המדיניות אמרה לסוכן — כך שאתה לא מנחש +כאשר משהו לא הולך כמו צפוי. → [מדריך לוח הבקרה](https://docs.befailproof.ai/dashboard) --- @@ -196,35 +196,34 @@ customPolicies.add({ | | | |---|---| -| [התחל](https://docs.befailproof.ai/getting-started) | התקנה וצעדים ראשונים | +| [התחלה מהר](https://docs.befailproof.ai/getting-started) | התקנה וצעדים ראשוניים | | [מדיניויות מובנות](https://docs.befailproof.ai/built-in-policies) | כל 30 המדיניויות עם פרמטרים | | [מדיניויות מותאמות](https://docs.befailproof.ai/custom-policies) | כתוב שלך | -| [תצורה](https://docs.befailproof.ai/configuration) | זימוני תצורה וכללי merge | -| [לוח בקרה](https://docs.befailproof.ai/dashboard) | מעקב session ופעילות מדיניות | -| [ארכיטקטורה](https://docs.befailproof.ai/architecture) | איך מערכת ה-hook עובדת | +| [תצורה](https://docs.befailproof.ai/configuration) | היקפי תצורה וכללי מיזוג | +| [לוח בקרה](https://docs.befailproof.ai/dashboard) | מוניטור הפגישה ופעילות המדיניות | +| [ארכיטקטורה](https://docs.befailproof.ai/architecture) | כיצד מערכת ה-hook עובדת | --- ## רישיון -MIT עם [Commons Clause](https://commonsclause.com/) — חינם לשימוש פנימי ואישי; מכירה מסחרית מחדש של failproofai עצמו דורשת הסכם נפרד. ראה [LICENSE](../../LICENSE) לטקסט המלא. +MIT עם [Commons Clause](https://commonsclause.com/) — חינם לשימוש פנימי ואישי; מכירה מחדש מסחרית של failproofai עצמו דורשת הסכם נפרד. ראה [LICENSE](../../LICENSE) לטקסט המלא. --- ## תרומה -ראה [CONTRIBUTING.md](../../CONTRIBUTING.md). מדיניויות חדשות, edge cases, ותרגומים כולם מוזמנים. +ראה [CONTRIBUTING.md](../../CONTRIBUTING.md). מדיניויות חדשות, מקרים קצה, ותרגומים כולם בברכה. -> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` ראשון. repo זה מריץ -> את hook ה-failproofai של עצמו, והם פותרים את יבוא ה-`failproofai` כנגד -> ה-bundle `dist/` המהודר — ללא build אתה תפגע בשגיאות hook `Cannot find package 'failproofai'`. +> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` תחילה. מאגר זה מריץ +> את ה-hooks שלו בעצמו, והם פותרים את ה-`failproofai` import כנגד +> ה-bundle `dist/` המחובר — ללא build תקבל שגיאות hook של `Cannot find package 'failproofai'`. > בנה מחדש לאחר שינוי `src/`. ראה -> [בנה לפני שה-hook פיתוח in-repo יעבדו](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -בנוי על ידי [Nivedit Jain](https://github.com/NiveditJain) ו-[Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +בנוי עם ❤️ על ידי [befailproof.ai](https://befailproof.ai) בסן פרנסיסקו וב-Bengaluru. \ No newline at end of file diff --git a/docs/i18n/README.hi.md b/docs/i18n/README.hi.md index 18a6931d..002cf693 100644 --- a/docs/i18n/README.hi.md +++ b/docs/i18n/README.hi.md @@ -17,9 +17,9 @@ **अनुवाद:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**कोडिंग एजेंट्स के लिए रनटाइम विफलता समाधान।** -Claude Code और Codex में हुक करता है। लूप्स, खतरनाक कार्यों और गोपनीय रिसाव को -घटनाओं में बदलने से पहले पकड़ता है। शून्य विलंबता। स्थानीय रूप से चलता है। +**कोडिंग एजेंटों के लिए रनटाइम विफलता समाधान।** +Claude Code और Codex में हुक करता है। लूप, खतरनाक कार्यों और गुप्त रिसाव को +उन्हें घटनाओं में बदलने से पहले पकड़ता है। शून्य विलंबता। स्थानीय रूप से चलता है। @@ -125,15 +125,15 @@ Claude Code और Codex में हुक करता है। लूप् -## स्थापना +## स्थापित करें ```sh npm install -g failproofai -failproofai policies --install # या बस `failproofai` चलाएँ और पहली बार के संकेत को स्वीकार करें +failproofai policies --install # या बस `failproofai` चलाएं और पहली बार के प्रॉम्प्ट को स्वीकार करें failproofai ``` -30 अंतर्निर्मित नीतियाँ तुरंत सक्रिय हो जाती हैं। डैशबोर्ड `localhost:8020` पर है। `FAILPROOFAI_NO_FIRST_RUN=1` के साथ पहली बार के संकेत को अक्षम करें। +30 अंतर्निहित नीतियां तुरंत सक्रिय हो जाती हैं। डैशबोर्ड `localhost:8020` पर। पहली बार के प्रॉम्प्ट को `FAILPROOFAI_NO_FIRST_RUN=1` से अक्षम करें। --- @@ -141,20 +141,20 @@ failproofai | नीति | यह क्या ब्लॉक करता है | |---|---| -| `block-push-master` | `main` / `master` के लिए प्रत्यक्ष पुश | +| `block-push-master` | `main` / `master` को सीधे पुश | | `block-force-push` | `git push --force` | -| `block-work-on-main` | `main` / `master` पर कमिट्स, मर्ज, रीबेसेस | -| `block-rm-rf` | पुनरावर्ती फ़ाइल विलोपन | -| `sanitize-api-keys` | एजेंट संदर्भ में API कुंजी रिसाव | +| `block-work-on-main` | `main` / `master` पर कमिट, मर्ज, रीबेस | +| `block-rm-rf` | पुनरावर्ती फाइल हटाना | +| `sanitize-api-keys` | API कुंजियाँ एजेंट संदर्भ में लीक होना | -→ [सभी 30 अंतर्निर्मित नीतियाँ](https://docs.befailproof.ai/built-in-policies) +→ [सभी 30 अंतर्निहित नीतियाँ](https://docs.befailproof.ai/built-in-policies) --- ## आपकी अपनी नीतियाँ -`.failproofai/policies/` में एक फ़ाइल छोड़ें — यह स्वचालित रूप से लोड होती है, कोई फ़्लैग की आवश्यकता नहीं है। -इसे कमिट करें और पूरी टीम को अगली पुल पर मिलेगी। +`.failproofai/policies/` में एक फाइल रखें — यह स्वचालित रूप से लोड होती है, किसी फ्लैग की आवश्यकता नहीं। +इसे कमिट करें और पूरी टीम को अगले पुल पर मिल जाएगा। ```js import { customPolicies, deny, allow } from "failproofai"; @@ -178,15 +178,15 @@ customPolicies.add({ | `deny(message)` | इसे ब्लॉक करें — संदेश एजेंट को वापस जाता है | | `instruct(message)` | इसे आगे बढ़ने दें, लेकिन एजेंट के अगले प्रॉम्प्ट में संदर्भ जोड़ें | -→ [कस्टम नीतियाँ गाइड](https://docs.befailproof.ai/custom-policies) +→ [कस्टम नीतियों गाइड](https://docs.befailproof.ai/custom-policies) --- -## सेशन दृश्यता +## सत्र दृश्यमानता आपका एजेंट जो भी टूल कॉल करता है वह स्थानीय रूप से लॉग किया जाता है। डैशबोर्ड दिखाता है कि क्या चला, -क्या ब्लॉक किया गया, और नीति ने एजेंट को क्या बताया — इसलिए आप अनुमान नहीं लगा रहे हैं -जब कुछ गलत हो जाता है। → [डैशबोर्ड गाइड](https://docs.befailproof.ai/dashboard) +क्या ब्लॉक किया गया, और नीति ने एजेंट को क्या बताया — इसलिए जब कुछ गलत हो तो आप अनुमान नहीं लगा रहे। +→ [डैशबोर्ड गाइड](https://docs.befailproof.ai/dashboard) --- @@ -194,29 +194,27 @@ customPolicies.add({ | | | |---|---| -| [शुरुआत करें](https://docs.befailproof.ai/getting-started) | स्थापना और पहले कदम | -| [अंतर्निर्मित नीतियाँ](https://docs.befailproof.ai/built-in-policies) | सभी 30 नीतियाँ पैरामीटर के साथ | -| [कस्टम नीतियाँ](https://docs.befailproof.ai/custom-policies) | अपने स्वयं के लिखें | +| [शुरुआत करना](https://docs.befailproof.ai/getting-started) | स्थापन और पहले कदम | +| [अंतर्निहित नीतियाँ](https://docs.befailproof.ai/built-in-policies) | सभी 30 नीतियाँ पैरामीटर के साथ | +| [कस्टम नीतियाँ](https://docs.befailproof.ai/custom-policies) | अपनी अपनी लिखें | | [कॉन्फ़िगरेशन](https://docs.befailproof.ai/configuration) | कॉन्फ़िग स्कोप और मर्ज नियम | -| [डैशबोर्ड](https://docs.befailproof.ai/dashboard) | सेशन मॉनिटर और नीति गतिविधि | +| [डैशबोर्ड](https://docs.befailproof.ai/dashboard) | सत्र मॉनिटर और नीति गतिविधि | | [आर्किटेक्चर](https://docs.befailproof.ai/architecture) | हुक सिस्टम कैसे काम करता है | --- ## लाइसेंस -MIT with [Commons Clause](https://commonsclause.com/) — आंतरिक और व्यक्तिगत उपयोग के लिए निःशुल्क; failproofai का वाणिज्यिक पुनर्विक्रय एक अलग समझौते की आवश्यकता है। पूर्ण पाठ के लिए [LICENSE](../../LICENSE) देखें। +MIT के साथ [Commons Clause](https://commonsclause.com/) — आंतरिक और व्यक्तिगत उपयोग के लिए मुफ़्त; failproofai का व्यावसायिक पुनर्विक्रय एक अलग समझौते की आवश्यकता है। पूर्ण पाठ के लिए [LICENSE](../../LICENSE) देखें। --- ## योगदान -[CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई नीतियाँ, सीमांत मामले और अनुवाद सभी स्वागत हैं। +[CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई नीतियाँ, सीमांत मामले, और अनुवाद सभी स्वागत हैं। -> **बिल्ड करने से पहले शुरुआत करें।** पहले `bun install && bun run build` चलाएँ। यह रिपो स्वयं पर failproofai के हुक चलाता है, और वे संकलित `dist/` बंडल के विरुद्ध `failproofai` आयात को हल करते हैं — बिल्ड के बिना आपको `Cannot find package 'failproofai'` हुक त्रुटियों मिलेंगी। `src/` को बदलने के बाद फिर से बिल्ड करें। देखें -> [इन-रिपो डेव हुक काम करने से पहले बिल्ड करें](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)। +> **शुरू करने से पहले बनाएं।** पहले `bun install && bun run build` चलाएं। यह रिपो failproofai की अपनी नीतियों को अपने आप पर चलाता है, और वे `failproofai` आयात को संकलित `dist/` बंडल के विरुद्ध हल करते हैं — एक बिल्ड के बिना आप `Cannot find package 'failproofai'` हुक त्रुटियों को मारेंगे। `src/` बदलने के बाद पुनः बनाएं। [हुक के काम करने से पहले बिल्ड करें](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) देखें। --- -[Nivedit Jain](https://github.com/NiveditJain) और [Nikita Agarwal](https://github.com/nk-ag) द्वारा निर्मित। -[befailproof.ai](https://befailproof.ai) +❤️ के साथ [befailproof.ai](https://befailproof.ai) द्वारा SF और बेंगलुरु में बनाया गया। diff --git a/docs/i18n/README.it.md b/docs/i18n/README.it.md index 78add06b..b1eacc74 100644 --- a/docs/i18n/README.it.md +++ b/docs/i18n/README.it.md @@ -17,8 +17,8 @@ **Traduzioni:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Risoluzione runtime degli errori per agenti di codifica.** -Si integra con Claude Code e Codex. Cattura loop, azioni pericolose e perdite di segreti +**Risoluzione dei guasti a runtime per agent di coding.** +Si integra con Claude Code e Codex. Rileva loop, azioni pericolose e fughe di segreti prima che diventino incidenti. Zero latenza. Eseguito localmente. @@ -29,7 +29,7 @@ prima che diventino incidenti. Zero latenza. Eseguito localmente. --- -## CLI agenti supportati +## CLI di agent supportati {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -125,36 +125,36 @@ prima che diventino incidenti. Zero latenza. Eseguito localmente. -## Installazione +## Installa ```sh npm install -g failproofai -failproofai policies --install # oppure esegui semplicemente `failproofai` e accetta il prompt della prima esecuzione +failproofai policies --install # o semplicemente esegui `failproofai` e accetta il prompt della prima esecuzione failproofai ``` -30 politiche integrate si attivano immediatamente. Dashboard su `localhost:8020`. Disabilita il prompt della prima esecuzione con `FAILPROOFAI_NO_FIRST_RUN=1`. +30 policy integrate si attivano immediatamente. Dashboard su `localhost:8020`. Disabilita il prompt della prima esecuzione con `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## Cosa blocca +## Quello che blocca -| Politica | Cosa blocca | +| Policy | Cosa blocca | |---|---| | `block-push-master` | Push diretti a `main` / `master` | | `block-force-push` | `git push --force` | | `block-work-on-main` | Commit, merge, rebase su `main` / `master` | -| `block-rm-rf` | Eliminazione ricorsiva di file | -| `sanitize-api-keys` | Chiavi API che fuoriescono nel contesto dell'agente | +| `block-rm-rf` | Cancellazione ricorsiva di file | +| `sanitize-api-keys` | Chiavi API che si diffondono nel contesto dell'agent | -→ [Tutte le 30 politiche integrate](https://docs.befailproof.ai/built-in-policies) +→ [Tutte le 30 policy integrate](https://docs.befailproof.ai/built-in-policies) --- -## Le tue politiche personali +## Le tue policy personalizzate -Aggiungi un file in `.failproofai/policies/` — si carica automaticamente, senza flag necessari. -Committalo e tutto il team lo avrà al prossimo pull. +Aggiungi un file in `.failproofai/policies/` — viene caricato automaticamente, nessun flag necessario. +Fai un commit e l'intero team lo riceverà al prossimo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -170,23 +170,23 @@ customPolicies.add({ }); ``` -Tre decisioni disponibili per ogni politica: +Tre decisioni disponibili per ogni policy: | Decisione | Effetto | |---|---| -| `allow()` | Permette l'operazione | -| `deny(message)` | La blocca — il messaggio torna all'agente | -| `instruct(message)` | La lascia passare, ma aggiunge contesto al prompt successivo dell'agente | +| `allow()` | Consenti l'operazione | +| `deny(message)` | Bloccala — il messaggio viene restituito all'agent | +| `instruct(message)` | Lasciarla passare, ma aggiungi il contesto al prossimo prompt dell'agent | -→ [Guida alle politiche personalizzate](https://docs.befailproof.ai/custom-policies) +→ [Guida alle policy personalizzate](https://docs.befailproof.ai/custom-policies) --- ## Visibilità della sessione -Ogni tool call che il tuo agente effettua viene registrato localmente. Il dashboard mostra cosa è stato eseguito, -cosa è stato bloccato e cosa la politica ha detto all'agente — così non stai indovinando -quando qualcosa va storto. → [Guida al Dashboard](https://docs.befailproof.ai/dashboard) +Ogni chiamata di tool che effettua l'agent viene registrata localmente. Il dashboard mostra cosa è stato eseguito, +cosa è stato bloccato e cosa la policy ha comunicato all'agent — in modo che tu non stia indovinando +quando qualcosa va male. → [Guida al dashboard](https://docs.befailproof.ai/dashboard) --- @@ -194,12 +194,12 @@ quando qualcosa va storto. → [Guida al Dashboard](https://docs.befailproof.ai/ | | | |---|---| -| [Iniziare](https://docs.befailproof.ai/getting-started) | Installazione e primi passi | -| [Politiche integrate](https://docs.befailproof.ai/built-in-policies) | Tutte le 30 politiche con parametri | -| [Politiche personalizzate](https://docs.befailproof.ai/custom-policies) | Scrivi le tue | -| [Configurazione](https://docs.befailproof.ai/configuration) | Scope di configurazione e regole di merge | -| [Dashboard](https://docs.befailproof.ai/dashboard) | Monitor di sessione e attività politica | -| [Architettura](https://docs.befailproof.ai/architecture) | Come funziona il sistema di hook | +| [Getting Started](https://docs.befailproof.ai/getting-started) | Installazione e primi passi | +| [Built-in Policies](https://docs.befailproof.ai/built-in-policies) | Tutte le 30 policy con parametri | +| [Custom Policies](https://docs.befailproof.ai/custom-policies) | Scrivi le tue | +| [Configuration](https://docs.befailproof.ai/configuration) | Ambiti di configurazione e regole di merge | +| [Dashboard](https://docs.befailproof.ai/dashboard) | Monitor di sessione e attività policy | +| [Architecture](https://docs.befailproof.ai/architecture) | Come funziona il sistema di hook | --- @@ -211,15 +211,14 @@ MIT con [Commons Clause](https://commonsclause.com/) — gratuito per uso intern ## Contribuire -Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove politiche, casi limite e traduzioni sono tutti benvenuti. +Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove policy, edge case e traduzioni sono tutti benvenuti. -> **Compila prima di iniziare.** Esegui `bun install && bun run build` prima. Questo repository esegue -> i propri hook di failproofai su se stesso, e risolvono l'import `failproofai` contro il -> bundle compilato `dist/` — senza una compilazione otterrai errori di hook `Cannot find package 'failproofai'`. -> Ricompila dopo aver modificato `src/`. Vedi +> **Compila prima di iniziare.** Esegui `bun install && bun run build` per primo. Questo repository esegue +> gli hook di failproofai su se stesso, e risolvono l'import di `failproofai` rispetto al +> bundle compilato `dist/` — senza una build otterrai errori di hook `Cannot find package 'failproofai'`. +> Ricompila dopo aver cambiato `src/`. Vedi > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Creato da [Nivedit Jain](https://github.com/NiveditJain) e [Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +Realizzato con ❤️ da [befailproof.ai](https://befailproof.ai) a SF e Bengaluru. diff --git a/docs/i18n/README.ja.md b/docs/i18n/README.ja.md index b9391df8..72a64848 100644 --- a/docs/i18n/README.ja.md +++ b/docs/i18n/README.ja.md @@ -18,8 +18,8 @@ **翻訳:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) **コーディングエージェントのランタイム障害解決ツール。** -Claude Code や Codex にフックし、ループ・危険な操作・シークレット漏洩を -インシデントになる前に検知・阻止します。レイテンシーゼロ。ローカルで動作。 +Claude Code および Codex にフックし、ループ・危険な操作・シークレットの漏洩を +インシデントになる前に検出・防止します。レイテンシーゼロ。ローカル実行。 @@ -133,7 +133,7 @@ failproofai policies --install # または `failproofai` を実行して初回 failproofai ``` -30 個の組み込みポリシーが即座に有効化されます。ダッシュボードは `localhost:8020` で確認できます。初回起動プロンプトを無効にするには `FAILPROOFAI_NO_FIRST_RUN=1` を設定してください。 +30 個の組み込みポリシーが即座に有効になります。ダッシュボードは `localhost:8020` で確認できます。初回起動プロンプトを無効にするには `FAILPROOFAI_NO_FIRST_RUN=1` を設定してください。 --- @@ -145,16 +145,16 @@ failproofai | `block-force-push` | `git push --force` | | `block-work-on-main` | `main` / `master` へのコミット・マージ・リベース | | `block-rm-rf` | 再帰的なファイル削除 | -| `sanitize-api-keys` | エージェントのコンテキストへの API キー漏洩 | +| `sanitize-api-keys` | エージェントコンテキストへの API キー漏洩 | → [組み込みポリシー全 30 件](https://docs.befailproof.ai/built-in-policies) --- -## 独自ポリシーの作成 +## カスタムポリシー -`.failproofai/policies/` にファイルを配置するだけで自動的に読み込まれます。フラグは不要です。 -コミットしておけば、次回 pull 時にチーム全員に適用されます。 +`.failproofai/policies/` にファイルを置くだけで自動的に読み込まれます。フラグは不要です。 +コミットすれば、次回プル時にチーム全員に適用されます。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -170,13 +170,13 @@ customPolicies.add({ }); ``` -すべてのポリシーで使用できる 3 つの判定: +各ポリシーで使用できる判定は 3 種類です： -| 判定 | 効果 | +| 判定 | 動作 | |---|---| | `allow()` | 操作を許可する | -| `deny(message)` | ブロックする — メッセージはエージェントに返される | -| `instruct(message)` | 操作を通過させつつ、エージェントの次のプロンプトにコンテキストを追加する | +| `deny(message)` | ブロックする — メッセージがエージェントに返される | +| `instruct(message)` | 通過させるが、エージェントの次のプロンプトにコンテキストを追加する | → [カスタムポリシーガイド](https://docs.befailproof.ai/custom-policies) @@ -184,7 +184,7 @@ customPolicies.add({ ## セッションの可視化 -エージェントが行ったすべてのツール呼び出しはローカルにログとして記録されます。ダッシュボードでは実行内容・ブロックされた操作・ポリシーがエージェントに伝えた内容を確認できるため、問題が発生しても推測で対応する必要がありません。→ [ダッシュボードガイド](https://docs.befailproof.ai/dashboard) +エージェントが行ったすべてのツール呼び出しはローカルに記録されます。ダッシュボードでは、実行された内容・ブロックされた内容・ポリシーがエージェントに伝えた内容を確認できるため、問題が発生しても推測に頼る必要がありません。→ [ダッシュボードガイド](https://docs.befailproof.ai/dashboard) --- @@ -203,17 +203,16 @@ customPolicies.add({ ## ライセンス -MIT に [Commons Clause](https://commonsclause.com/) を付加したライセンス — 社内利用および個人利用は無料。failproofai 自体の商業的な再販には別途契約が必要です。全文は [LICENSE](../../LICENSE) をご覧ください。 +[Commons Clause](https://commonsclause.com/) 付き MIT ライセンス — 社内利用・個人利用は無料。failproofai 自体の商業的な再販には別途契約が必要です。全文は [LICENSE](../../LICENSE) をご覧ください。 --- ## コントリビューション -[CONTRIBUTING.md](../../CONTRIBUTING.md) をご参照ください。新しいポリシー、エッジケースの対応、翻訳など、あらゆる貢献を歓迎します。 +[CONTRIBUTING.md](../../CONTRIBUTING.md) をご参照ください。新しいポリシー、エッジケースの対応、翻訳のいずれも歓迎しています。 -> **開始前にビルドしてください。** 最初に `bun install && bun run build` を実行してください。このリポジトリは failproofai 自身のフックを自身に適用しており、フックは `failproofai` のインポートをコンパイル済みの `dist/` バンドルに対して解決します。ビルドなしで実行すると `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [リポジトリ内の開発フックを動作させるためのビルド手順](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご参照ください。 +> **作業前にビルドを実行してください。** まず `bun install && bun run build` を実行してください。このリポジトリは failproofai 自身のフックを自身に適用しており、`failproofai` のインポートはコンパイル済みの `dist/` バンドルに対して解決されます。ビルドなしに実行すると `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご覧ください。 --- -[Nivedit Jain](https://github.com/NiveditJain) と [Nikita Agarwal](https://github.com/nk-ag) が開発。 -[befailproof.ai](https://befailproof.ai) +SF とベンガルールのチームが ❤️ を込めて開発。[befailproof.ai](https://befailproof.ai) diff --git a/docs/i18n/README.ko.md b/docs/i18n/README.ko.md index ba28a26e..82fe162d 100644 --- a/docs/i18n/README.ko.md +++ b/docs/i18n/README.ko.md @@ -18,8 +18,8 @@ **번역:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) **코딩 에이전트를 위한 런타임 장애 해결 도구.** -Claude Code 및 Codex에 연결됩니다. 루프, 위험한 동작, 시크릿 누출을 -인시던트가 되기 전에 차단합니다. 지연 시간 제로. 로컬에서 실행. +Claude Code 및 Codex에 연결됩니다. 루프, 위험한 작업, 시크릿 유출을 +인시던트가 되기 전에 차단합니다. 레이턴시 제로. 로컬에서 실행. @@ -129,32 +129,32 @@ Claude Code 및 Codex에 연결됩니다. 루프, 위험한 동작, 시크릿 ```sh npm install -g failproofai -failproofai policies --install # 또는 `failproofai`를 실행하고 최초 실행 프롬프트에서 수락 +failproofai policies --install # 또는 그냥 `failproofai`를 실행하고 첫 실행 프롬프트에서 수락 failproofai ``` -30개의 기본 제공 정책이 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인할 수 있습니다. `FAILPROOFAI_NO_FIRST_RUN=1`로 최초 실행 프롬프트를 비활성화할 수 있습니다. +30개의 내장 정책이 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인할 수 있습니다. 첫 실행 프롬프트를 비활성화하려면 `FAILPROOFAI_NO_FIRST_RUN=1`을 사용하세요. --- -## 차단 항목 +## 차단하는 항목 -| 정책 | 차단 내용 | +| 정책 | 차단 대상 | |---|---| -| `block-push-master` | `main` / `master` 브랜치에 직접 푸시 | +| `block-push-master` | `main` / `master`로의 직접 푸시 | | `block-force-push` | `git push --force` | -| `block-work-on-main` | `main` / `master` 브랜치에서의 커밋, 머지, 리베이스 | +| `block-work-on-main` | `main` / `master`에서의 커밋, 머지, 리베이스 | | `block-rm-rf` | 재귀적 파일 삭제 | -| `sanitize-api-keys` | 에이전트 컨텍스트로 누출되는 API 키 | +| `sanitize-api-keys` | 에이전트 컨텍스트로 유출되는 API 키 | -→ [30개 기본 제공 정책 전체 목록](https://docs.befailproof.ai/built-in-policies) +→ [30개 내장 정책 전체 목록](https://docs.befailproof.ai/built-in-policies) --- ## 커스텀 정책 -`.failproofai/policies/` 디렉터리에 파일을 추가하면 자동으로 로드됩니다 — 별도 플래그 불필요. -커밋하면 팀 전체가 다음 풀 때 적용됩니다. +`.failproofai/policies/` 에 파일을 추가하면 자동으로 로드됩니다 — 별도의 플래그 설정이 필요 없습니다. +커밋하면 팀 전체가 다음 풀 시점에 적용받습니다. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -175,8 +175,8 @@ customPolicies.add({ | 결정 | 효과 | |---|---| | `allow()` | 작업 허용 | -| `deny(message)` | 차단 — 메시지가 에이전트에게 반환됨 | -| `instruct(message)` | 통과 허용, 단 에이전트의 다음 프롬프트에 컨텍스트 추가 | +| `deny(message)` | 차단 — 메시지가 에이전트로 반환됨 | +| `instruct(message)` | 통과 허용하되, 에이전트의 다음 프롬프트에 컨텍스트 추가 | → [커스텀 정책 가이드](https://docs.befailproof.ai/custom-policies) @@ -184,8 +184,8 @@ customPolicies.add({ ## 세션 가시성 -에이전트가 수행하는 모든 도구 호출은 로컬에 기록됩니다. 대시보드에서 실행된 내용, -차단된 내용, 정책이 에이전트에게 전달한 내용을 확인할 수 있어 — 문제가 발생했을 때 +에이전트가 수행하는 모든 도구 호출은 로컬에 기록됩니다. 대시보드는 실행된 내용, +차단된 내용, 정책이 에이전트에 전달한 내용을 보여줍니다 — 문제가 발생했을 때 추측할 필요가 없습니다. → [대시보드 가이드](https://docs.befailproof.ai/dashboard) --- @@ -195,17 +195,17 @@ customPolicies.add({ | | | |---|---| | [시작하기](https://docs.befailproof.ai/getting-started) | 설치 및 첫 번째 단계 | -| [기본 제공 정책](https://docs.befailproof.ai/built-in-policies) | 매개변수를 포함한 30개 전체 정책 | +| [내장 정책](https://docs.befailproof.ai/built-in-policies) | 파라미터를 포함한 30개 정책 전체 | | [커스텀 정책](https://docs.befailproof.ai/custom-policies) | 직접 작성하기 | | [설정](https://docs.befailproof.ai/configuration) | 설정 범위 및 병합 규칙 | | [대시보드](https://docs.befailproof.ai/dashboard) | 세션 모니터 및 정책 활동 | -| [아키텍처](https://docs.befailproof.ai/architecture) | 훅 시스템 작동 방식 | +| [아키텍처](https://docs.befailproof.ai/architecture) | 훅 시스템의 동작 방식 | --- ## 라이선스 -[Commons Clause](https://commonsclause.com/)가 적용된 MIT 라이선스 — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매는 별도 계약이 필요합니다. 전체 내용은 [LICENSE](../../LICENSE)를 참조하세요. +[Commons Clause](https://commonsclause.com/)가 포함된 MIT 라이선스 — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매는 별도의 계약이 필요합니다. 전문은 [LICENSE](../../LICENSE)를 참조하세요. --- @@ -214,12 +214,11 @@ customPolicies.add({ [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참조하세요. 새로운 정책, 엣지 케이스, 번역 모두 환영합니다. > **시작 전에 빌드하세요.** 먼저 `bun install && bun run build`를 실행하세요. 이 저장소는 -> failproofai 자체의 훅을 자신에게 적용하며, 컴파일된 `dist/` 번들에 대해 `failproofai` 임포트를 +> failproofai 자체 훅을 자신에게 적용하며, 훅은 컴파일된 `dist/` 번들에서 `failproofai` 임포트를 > 해석합니다 — 빌드 없이는 `Cannot find package 'failproofai'` 훅 오류가 발생합니다. -> `src/`를 변경한 후에는 다시 빌드하세요. -> [저장소 내 개발 훅이 동작하기 위한 빌드 방법](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)을 참조하세요. +> `src/` 변경 후에는 재빌드하세요. 자세한 내용은 +> [저장소 내 개발 훅 사용 전 빌드 필수](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)를 참조하세요. --- -[Nivedit Jain](https://github.com/NiveditJain)과 [Nikita Agarwal](https://github.com/nk-ag)이 만들었습니다. -[befailproof.ai](https://befailproof.ai) +SF와 벵갈루루에서 ❤️ 를 담아 [befailproof.ai](https://befailproof.ai)가 만들었습니다. diff --git a/docs/i18n/README.pt-br.md b/docs/i18n/README.pt-br.md index 0776bde6..e5fc069b 100644 --- a/docs/i18n/README.pt-br.md +++ b/docs/i18n/README.pt-br.md @@ -17,7 +17,7 @@ **Traduções:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Resolução de falhas em tempo de execução para agentes de código.** +**Resolução de falhas em tempo de execução para agentes de codificação.** Integra-se ao Claude Code e ao Codex. Detecta loops, ações perigosas e vazamentos de segredos antes que se tornem incidentes. Latência zero. Executa localmente. @@ -129,15 +129,15 @@ antes que se tornem incidentes. Latência zero. Executa localmente. ```sh npm install -g failproofai -failproofai policies --install # or just run `failproofai` and accept the first-run prompt +failproofai policies --install # ou simplesmente execute `failproofai` e aceite o prompt da primeira execução failproofai ``` -30 políticas integradas são ativadas imediatamente. Dashboard em `localhost:8020`. Desative o prompt de primeira execução com `FAILPROOFAI_NO_FIRST_RUN=1`. +30 políticas integradas são ativadas imediatamente. Dashboard em `localhost:8020`. Desative o prompt da primeira execução com `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## O que é bloqueado +## O que ele bloqueia | Política | O que bloqueia | |---|---| @@ -145,7 +145,7 @@ failproofai | `block-force-push` | `git push --force` | | `block-work-on-main` | Commits, merges e rebases em `main` / `master` | | `block-rm-rf` | Exclusão recursiva de arquivos | -| `sanitize-api-keys` | Vazamento de chaves de API no contexto do agente | +| `sanitize-api-keys` | Chaves de API vazando para o contexto do agente | → [Todas as 30 políticas integradas](https://docs.befailproof.ai/built-in-policies) @@ -153,8 +153,8 @@ failproofai ## Suas próprias políticas -Coloque um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem necessidade de flags. -Faça o commit e todo o time recebe na próxima atualização. +Coloque um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem flags necessárias. +Faça o commit e toda a equipe recebe na próxima atualização. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -176,7 +176,7 @@ Três decisões disponíveis para cada política: |---|---| | `allow()` | Permite a operação | | `deny(message)` | Bloqueia — a mensagem é enviada de volta ao agente | -| `instruct(message)` | Permite a passagem, mas adiciona contexto ao próximo prompt do agente | +| `instruct(message)` | Deixa passar, mas adiciona contexto ao próximo prompt do agente | → [Guia de políticas personalizadas](https://docs.befailproof.ai/custom-policies) @@ -185,8 +185,8 @@ Três decisões disponíveis para cada política: ## Visibilidade da sessão Cada chamada de ferramenta feita pelo seu agente é registrada localmente. O dashboard mostra o que foi executado, -o que foi bloqueado e o que a política informou ao agente — sem deixar dúvidas -quando algo dá errado. → [Guia do dashboard](https://docs.befailproof.ai/dashboard) +o que foi bloqueado e o que a política comunicou ao agente — para você não precisar adivinhar +quando algo der errado. → [Guia do dashboard](https://docs.befailproof.ai/dashboard) --- @@ -205,21 +205,20 @@ quando algo dá errado. → [Guia do dashboard](https://docs.befailproof.ai/dash ## Licença -MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso interno e pessoal; a revenda comercial do próprio failproofai requer um acordo separado. Veja [LICENSE](../../LICENSE) para o texto completo. +MIT com [Commons Clause](https://commonsclause.com/) — uso interno e pessoal gratuito; a revenda comercial do failproofai em si requer um acordo separado. Veja [LICENSE](../../LICENSE) para o texto completo. --- ## Contribuindo -Consulte [CONTRIBUTING.md](../../CONTRIBUTING.md). Novas políticas, casos extremos e traduções são bem-vindos. +Veja [CONTRIBUTING.md](../../CONTRIBUTING.md). Novas políticas, casos extremos e traduções são bem-vindos. -> **Compile antes de começar.** Execute `bun install && bun run build` primeiro. Este repositório executa +> **Faça o build antes de começar.** Execute `bun install && bun run build` primeiro. Este repositório executa > os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import `failproofai` a partir do -> bundle compilado em `dist/` — sem uma compilação você terá erros de hook `Cannot find package 'failproofai'`. -> Recompile após alterar `src/`. Veja -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> bundle compilado em `dist/` — sem um build você encontrará erros de hook `Cannot find package 'failproofai'`. +> Refaça o build após alterar `src/`. Veja +> [Build antes que os hooks de desenvolvimento do repositório funcionem](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Desenvolvido por [Nivedit Jain](https://github.com/NiveditJain) e [Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +Feito com ❤️ por [befailproof.ai](https://befailproof.ai) em SF e Bengaluru. diff --git a/docs/i18n/README.ru.md b/docs/i18n/README.ru.md index d75e501c..2d02bcd1 100644 --- a/docs/i18n/README.ru.md +++ b/docs/i18n/README.ru.md @@ -18,8 +18,8 @@ **Переводы:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) **Разрешение ошибок во время выполнения для кодирующих агентов.** -Подключается к Claude Code и Codex. Перехватывает циклы, опасные действия и утечки секретов -прежде, чем они станут инцидентами. Нулевая задержка. Работает локально. +Интегрируется с Claude Code и Codex. Перехватывает циклы, опасные действия и утечки секретов +до того, как они станут инцидентами. Нулевая задержка. Работает локально. @@ -129,23 +129,23 @@ ```sh npm install -g failproofai -failproofai policies --install # или просто запустите `failproofai` и согласитесь с подсказкой при первом запуске +failproofai policies --install # или просто запустите `failproofai` и согласитесь с предложением при первом запуске failproofai ``` -30 встроенных политик активируются немедленно. Панель управления доступна по адресу `localhost:8020`. Отключите подсказку при первом запуске с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. +30 встроенных политик активируются немедленно. Панель управления на `localhost:8020`. Отключите предложение при первом запуске с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. --- ## Что это блокирует -| Политика | Что блокируется | +| Политика | Что это блокирует | |---|---| -| `block-push-master` | Прямые push'и в `main` / `master` | +| `block-push-master` | Прямые отправки в `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | Коммиты, слияния, перебазирование на `main` / `master` | +| `block-work-on-main` | Коммиты, слияния, rebase на `main` / `master` | | `block-rm-rf` | Рекурсивное удаление файлов | -| `sanitize-api-keys` | Утечки API ключей в контекст агента | +| `sanitize-api-keys` | Утечки API-ключей в контекст агента | → [Все 30 встроенных политик](https://docs.befailproof.ai/built-in-policies) @@ -153,8 +153,8 @@ failproofai ## Ваши собственные политики -Поместите файл в `.failproofai/policies/` — он загружается автоматически, никаких флагов не требуется. -Закоммитьте его, и вся команда получит его при следующем pull'е. +Поместите файл в `.failproofai/policies/` — он загружается автоматически, без флагов. +Зафиксируйте его, и вся команда получит его при следующем pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -175,8 +175,8 @@ customPolicies.add({ | Решение | Эффект | |---|---| | `allow()` | Разрешить операцию | -| `deny(message)` | Заблокировать её — сообщение вернётся агенту | -| `instruct(message)` | Пропустить, но добавить контекст в следующий prompt агента | +| `deny(message)` | Заблокировать — сообщение отправляется обратно агенту | +| `instruct(message)` | Пропустить, но добавить контекст в следующий запрос агента | → [Руководство по пользовательским политикам](https://docs.befailproof.ai/custom-policies) @@ -184,9 +184,9 @@ customPolicies.add({ ## Видимость сеанса -Каждый вызов инструмента, который делает ваш агент, логируется локально. На панели управления отображается, что было запущено, -что было заблокировано и что политика сказала агенту — так вы не будете гадать, -когда что-то пойдёт не так. → [Руководство панели управления](https://docs.befailproof.ai/dashboard) +Каждый вызов инструмента, выполняемый вашим агентом, регистрируется локально. Панель управления показывает, что было запущено, +что было заблокировано и что политика сообщила агенту — так вы не будете гадать, +когда что-то пойдет не так. → [Руководство по панели управления](https://docs.befailproof.ai/dashboard) --- @@ -196,7 +196,7 @@ customPolicies.add({ |---|---| | [Начало работы](https://docs.befailproof.ai/getting-started) | Установка и первые шаги | | [Встроенные политики](https://docs.befailproof.ai/built-in-policies) | Все 30 политик с параметрами | -| [Пользовательские политики](https://docs.befailproof.ai/custom-policies) | Напишите свои | +| [Пользовательские политики](https://docs.befailproof.ai/custom-policies) | Напишите свои собственные | | [Конфигурация](https://docs.befailproof.ai/configuration) | Области конфигурации и правила слияния | | [Панель управления](https://docs.befailproof.ai/dashboard) | Монитор сеанса и активность политик | | [Архитектура](https://docs.befailproof.ai/architecture) | Как работает система хуков | @@ -205,18 +205,20 @@ customPolicies.add({ ## Лицензия -MIT с [Commons Clause](https://commonsclause.com/) — бесплатно для внутреннего и личного использования; коммерческая перепродажа самого failproofai требует отдельного соглашения. Полный текст смотрите в [LICENSE](../../LICENSE). +MIT с [Commons Clause](https://commonsclause.com/) — бесплатно для внутреннего и личного использования; коммерческая перепродажа самого failproofai требует отдельного соглашения. См. [LICENSE](../../LICENSE) для полного текста. --- -## Участие в разработке +## Вклад -Смотрите [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы приветствуются. +См. [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы приветствуются. -> **Постройте перед началом работы.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает собственные хуки failproofai на себе, и они разрешают импорт `failproofai` против скомпилированного бандла `dist/` — без сборки вы получите ошибки хуков `Cannot find package 'failproofai'`. Пересоберите после изменения `src/`. Смотрите -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Сборка перед началом.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает +> собственные хуки failproofai на самом себе, и они разрешают импорт `failproofai` в скомпилированный +> bundle `dist/` — без сборки вы столкнетесь с ошибками хуков `Cannot find package 'failproofai'`. +> Пересобирайте после изменения `src/`. См. +> [Сборка перед тем, как внутрипроектные dev-хуки начнут работать](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Создано [Nivedit Jain](https://github.com/NiveditJain) и [Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +Создано с ❤️ командой [befailproof.ai](https://befailproof.ai) в Сан-Франциско и Бангалоре. diff --git a/docs/i18n/README.tr.md b/docs/i18n/README.tr.md index 4365c0b0..3f4e60aa 100644 --- a/docs/i18n/README.tr.md +++ b/docs/i18n/README.tr.md @@ -17,9 +17,8 @@ **Çeviriler:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Kod aracıları için çalışma zamanı hata çözümü.** -Claude Code ve Codex'e bağlanır. Döngüleri, tehlikeli işlemleri ve gizli dizi sızıntılarını -olay haline gelmeden yakalar. Sıfır gecikme. Yerel olarak çalışır. +**Kodlama aracıları için çalışma zamanı hata çözümü.** +Claude Code ve Codex ile bağlantılı olarak çalışır. Döngüleri, tehlikeli işlemleri ve gizli anahtarları sızıntıya uğramadan önce yakalar. Sıfır gecikme. Yerel olarak çalışır. @@ -29,7 +28,7 @@ olay haline gelmeden yakalar. Sıfır gecikme. Yerel olarak çalışır. --- -## Desteklenen ajan CLI'ları +## Desteklenen ajan CLI'leri {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -125,36 +124,36 @@ olay haline gelmeden yakalar. Sıfır gecikme. Yerel olarak çalışır. -## Yükleme +## Kurulum ```sh npm install -g failproofai -failproofai policies --install # ya da sadece `failproofai` çalıştırın ve ilk çalıştırma komutunu kabul edin +failproofai policies --install # veya sadece `failproofai` çalıştırın ve ilk çalıştırma uyarısını kabul edin failproofai ``` -30 yerleşik politika hemen etkinleşir. Kontrol paneli `localhost:8020` adresinde bulunur. İlk çalıştırma komutunu `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. +30 yerleşik ilke hemen etkinleşir. Pano `localhost:8020` adresinde bulunur. İlk çalıştırma uyarısını `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. --- -## Neleri durdurur +## Neyi engeller -| Politika | Neleri engeller | +| İlke | Neyi engeller | |---|---| -| `block-push-master` | `main` / `master` dalına doğrudan itme | +| `block-push-master` | `main` / `master` üzerine doğrudan push işlemleri | | `block-force-push` | `git push --force` | -| `block-work-on-main` | `main` / `master` üzerinde işlemler, birleştirmeler, yeniden tabanlama | +| `block-work-on-main` | `main` / `master` üzerinde commit, merge, rebase işlemleri | | `block-rm-rf` | Özyinelemeli dosya silme | | `sanitize-api-keys` | API anahtarlarının ajan bağlamına sızması | -→ [Tüm 30 yerleşik politika](https://docs.befailproof.ai/built-in-policies) +→ [Tüm 30 yerleşik ilke](https://docs.befailproof.ai/built-in-policies) --- -## Kendi politikalarınız +## Kendi ilkeleriniz -`.failproofai/policies/` dizinine bir dosya bırakın — otomatik yüklenir, bayrak gerekmez. -Bunu kaydedin ve ekip bir sonraki çekişte hepsini alır. +`.failproofai/policies/` klasörüne bir dosya bırakın — otomatik olarak yüklenir, bayrak gerekli değildir. +Commit edin ve tüm ekip sonraki pull işleminde bunu alır. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -164,29 +163,29 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Üretim yollarına yazma işlemleri engellenir."); + return deny("Writes to production paths are blocked."); return allow(); }, }); ``` -Her politika için üç karar mevcuttur: +Her ilke için kullanılabilir üç karar vardır: | Karar | Etki | |---|---| -| `allow()` | İşlemi izin ver | -| `deny(message)` | Engelle — ileti ajana geri gönderilir | -| `instruct(message)` | Bunu geçir, ancak ajana sonraki isteminde bağlam ekle | +| `allow()` | İşleme izin ver | +| `deny(message)` | Engelle — mesaj ajana geri gönderilir | +| `instruct(message)` | İzin ver, ancak ajanın sonraki istemine bağlam ekle | -→ [Özel politikalar rehberi](https://docs.befailproof.ai/custom-policies) +→ [Özel ilkeler rehberi](https://docs.befailproof.ai/custom-policies) --- ## Oturum görünürlüğü -Ajanınızın yaptığı her araç çağrısı yerel olarak günlüğe kaydedilir. Kontrol paneli -ne çalıştırıldığını, ne engellendi ve politikanın ajana ne söylediğini gösterir — böylece -bir şey ters gittiğinde tahmin yapmak zorunda kalmazsınız. → [Kontrol paneli rehberi](https://docs.befailproof.ai/dashboard) +Ajanın yaptığı her araç çağrısı yerel olarak kaydedilir. Pano, hangi işlemlerin çalıştığını, +hangileri engellediğini ve ilkenin ajana söylediklerini gösterir — bu sayede bir şey +yanlış gittiğinde tahmin etmeniz gerekmez. → [Pano rehberi](https://docs.befailproof.ai/dashboard) --- @@ -195,27 +194,26 @@ bir şey ters gittiğinde tahmin yapmak zorunda kalmazsınız. → [Kontrol pane | | | |---|---| | [Başlarken](https://docs.befailproof.ai/getting-started) | Kurulum ve ilk adımlar | -| [Yerleşik Politikalar](https://docs.befailproof.ai/built-in-policies) | Tüm 30 politika ile parametreleri | -| [Özel Politikalar](https://docs.befailproof.ai/custom-policies) | Kendinizinkini yazın | -| [Yapılandırma](https://docs.befailproof.ai/configuration) | Yapılandırma kapsamları ve birleştirme kuralları | -| [Kontrol Paneli](https://docs.befailproof.ai/dashboard) | Oturum monitörü ve politika etkinliği | +| [Yerleşik İlkeler](https://docs.befailproof.ai/built-in-policies) | Tüm 30 ilke ve parametreleri | +| [Özel İlkeler](https://docs.befailproof.ai/custom-policies) | Kendinizinkini yazın | +| [Konfigürasyon](https://docs.befailproof.ai/configuration) | Yapılandırma kapsamları ve birleştirme kuralları | +| [Pano](https://docs.befailproof.ai/dashboard) | Oturum izleyicisi ve ilke aktivitesi | | [Mimari](https://docs.befailproof.ai/architecture) | Hook sistemi nasıl çalışır | --- ## Lisans -[Commons Clause](https://commonsclause.com/) ile MIT — iç ve kişisel kullanım için ücretsiz; failproofai'nin kendisinin ticari yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](../../LICENSE) dosyasına bakın. +MIT with [Commons Clause](https://commonsclause.com/) — iç ve kişisel kullanım için ücretsiz; failproofai'nin ticari yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](../../LICENSE) dosyasına bakın. --- -## Katkıda Bulunmak +## Katkıda Bulunma -[CONTRIBUTING.md](../../CONTRIBUTING.md) dosyasına bakın. Yeni politikalar, sınır durumları ve çeviriler hepsi memnuniyetle karşılanır. +[CONTRIBUTING.md](../../CONTRIBUTING.md) dosyasına bakın. Yeni ilkeler, sınır durumları ve çeviriler her zaman hoş karşılanır. -> **Başlamadan önce derleyin.** Önce `bun install && bun run build` komutunu çalıştırın. Bu depo, failproofai'nin kendi hook'larını kendisinde çalıştırır ve `failproofai` ithalatını derlenmiş `dist/` paketine göre çözerler — derleme yapılmadan `Cannot find package 'failproofai'` hook hataları alırsınız. `src/` değiştirdikten sonra yeniden derleyin. Bkz. [Hook'lar çalışmadan önce derleme](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Başlamadan önce derleyin.** Önce `bun install && bun run build` çalıştırın. Bu depo failproofai'nin kendi hook'larını kendisine uygular ve `failproofai` import'unu derlenmiş `dist/` paketine karşı çözer — derleme olmadan `Cannot find package 'failproofai'` hook hataları alırsınız. `src/` değiştirdikten sonra yeniden derleyin. [Hook'ların çalışması için önce derleyin](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) bölümüne bakın. --- -[Nivedit Jain](https://github.com/NiveditJain) ve [Nikita Agarwal](https://github.com/nk-ag) tarafından oluşturulmuştur. -[befailproof.ai](https://befailproof.ai) +SF ve Bengaluru'da [befailproof.ai](https://befailproof.ai) tarafından ❤️ ile yapıldı. diff --git a/docs/i18n/README.vi.md b/docs/i18n/README.vi.md index b5c4b786..57d62a35 100644 --- a/docs/i18n/README.vi.md +++ b/docs/i18n/README.vi.md @@ -17,8 +17,8 @@ **Bản dịch:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Giải quyết lỗi thời gian chạy cho các agent lập trình.** -Tích hợp vào Claude Code và Codex. Bắt các vòng lặp, hành động nguy hiểm và rò rỉ bí mật +**Giải quyết lỗi chạy thời gian cho các agent mã hóa.** +Tích hợp với Claude Code và Codex. Phát hiện các vòng lặp, hành động nguy hiểm và rò rỉ bí mật trước khi chúng trở thành sự cố. Không độ trễ. Chạy cục bộ. @@ -129,7 +129,7 @@ trước khi chúng trở thành sự cố. Không độ trễ. Chạy cục b ```sh npm install -g failproofai -failproofai policies --install # hoặc chỉ chạy `failproofai` và chấp nhận lời nhắc lần đầu +failproofai policies --install # hoặc chỉ cần chạy `failproofai` và chấp nhận lời nhắc lần đầu failproofai ``` @@ -137,24 +137,24 @@ failproofai --- -## Những gì nó ngăn chặn +## Những gì nó chặn -| Chính sách | Những gì nó chặn | +| Chính sách | Những gì bị chặn | |---|---| -| `block-push-master` | Push trực tiếp đến `main` / `master` | +| `block-push-master` | Đẩy trực tiếp đến `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | Commits, merges, rebases trên `main` / `master` | +| `block-work-on-main` | Commit, merge, rebase trên `main` / `master` | | `block-rm-rf` | Xóa tệp đệ quy | -| `sanitize-api-keys` | API keys rò rỉ vào bối cảnh agent | +| `sanitize-api-keys` | Rò rỉ khóa API vào ngữ cảnh agent | → [Tất cả 30 chính sách tích hợp](https://docs.befailproof.ai/built-in-policies) --- -## Chính sách của riêng bạn +## Các chính sách của bạn -Thả một tệp vào `.failproofai/policies/` — nó tải tự động, không cần cờ nào. -Commit nó và toàn bộ nhóm sẽ nhận được nó trên lần pull tiếp theo. +Thả một tệp vào `.failproofai/policies/` — nó sẽ tải tự động, không cần cờ nào. +Commit nó và toàn bộ nhóm sẽ nhận được nó khi pull tiếp theo. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -164,7 +164,7 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Writes to production paths are blocked."); + return deny("Ghi vào các đường dẫn production bị chặn."); return allow(); }, }); @@ -172,21 +172,21 @@ customPolicies.add({ Ba quyết định có sẵn cho mỗi chính sách: -| Quyết định | Hiệu quả | +| Quyết định | Hiệu ứng | |---|---| | `allow()` | Cho phép hoạt động | -| `deny(message)` | Chặn nó — tin nhắn quay lại agent | -| `instruct(message)` | Cho nó đi qua, nhưng thêm bối cảnh vào lời nhắc tiếp theo của agent | +| `deny(message)` | Chặn nó — thông báo sẽ được gửi lại cho agent | +| `instruct(message)` | Cho phép nó thông qua, nhưng thêm bối cảnh vào lời nhắc tiếp theo của agent | → [Hướng dẫn chính sách tùy chỉnh](https://docs.befailproof.ai/custom-policies) --- -## Khả năng nhìn thấy phiên +## Khả năng hiển thị phiên -Mỗi lệnh gọi công cụ mà agent của bạn thực hiện đều được ghi nhật ký cục bộ. Bảng điều khiển hiển thị những gì đã chạy, -những gì đã bị chặn, và những gì chính sách đã nói với agent — vì vậy bạn không phải đoán -khi có sự cố. → [Hướng dẫn bảng điều khiển](https://docs.befailproof.ai/dashboard) +Mỗi lệnh gọi công cụ mà agent của bạn thực hiện đều được ghi lại cục bộ. Bảng điều khiển hiển thị những gì đã chạy, +những gì bị chặn và chính sách nói với agent điều gì — vì vậy bạn không phải đoán +khi có gì đó không đúng. → [Hướng dẫn bảng điều khiển](https://docs.befailproof.ai/dashboard) --- @@ -194,32 +194,31 @@ khi có sự cố. → [Hướng dẫn bảng điều khiển](https://docs.befa | | | |---|---| -| [Bắt đầu](https://docs.befailproof.ai/getting-started) | Cài đặt và các bước đầu tiên | +| [Bắt đầu](https://docs.befailproof.ai/getting-started) | Cài đặt và bước đầu tiên | | [Chính sách tích hợp](https://docs.befailproof.ai/built-in-policies) | Tất cả 30 chính sách với tham số | | [Chính sách tùy chỉnh](https://docs.befailproof.ai/custom-policies) | Viết chính sách của riêng bạn | | [Cấu hình](https://docs.befailproof.ai/configuration) | Phạm vi cấu hình và quy tắc hợp nhất | -| [Bảng điều khiển](https://docs.befailproof.ai/dashboard) | Bộ giám sát phiên và hoạt động chính sách | +| [Bảng điều khiển](https://docs.befailproof.ai/dashboard) | Màn hình theo dõi phiên và hoạt động chính sách | | [Kiến trúc](https://docs.befailproof.ai/architecture) | Cách hệ thống hook hoạt động | --- ## Giấy phép -MIT với [Commons Clause](https://commonsclause.com/) — miễn phí để sử dụng nội bộ và cá nhân; bán lại thương mại của failproofai chính nó yêu cầu thỏa thuận riêng. Xem [LICENSE](../../LICENSE) để biết toàn bộ văn bản. +MIT với [Commons Clause](https://commonsclause.com/) — miễn phí để sử dụng nội bộ và cá nhân; bán lại thương mại của chính failproofai yêu cầu một thỏa thuận riêng. Xem [LICENSE](../../LICENSE) để biết văn bản đầy đủ. --- ## Đóng góp -Xem [CONTRIBUTING.md](../../CONTRIBUTING.md). Chính sách mới, trường hợp biên và bản dịch đều được chào đón. +Xem [CONTRIBUTING.md](../../CONTRIBUTING.md). Các chính sách mới, trường hợp biên và bản dịch đều được chào đón. -> **Xây dựng trước khi bắt đầu.** Chạy `bun install && bun run build` trước. Repo này chạy -> các hook của failproofai trên chính nó, và chúng giải quyết nhập `failproofai` so với -> bộ bundle `dist/` được biên dịch — mà không cần xây dựng bạn sẽ gặp `Cannot find package 'failproofai'` -> lỗi hook. Xây dựng lại sau khi thay đổi `src/`. Xem -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Xây dựng trước khi bạn bắt đầu.** Chạy `bun install && bun run build` trước. Kho lưu trữ này chạy +> các hook của failproofai trên chính nó, và chúng phân giải import `failproofai` so với +> tệp bundle `dist/` được biên dịch — mà không có build bạn sẽ gặp phải các lỗi hook `Cannot find package 'failproofai'` +> . Xây dựng lại sau khi thay đổi `src/`. Xem +> [Build trước khi các hook dev trong kho sẽ hoạt động](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Được xây dựng bởi [Nivedit Jain](https://github.com/NiveditJain) và [Nikita Agarwal](https://github.com/nk-ag). -[befailproof.ai](https://befailproof.ai) +Được xây dựng với ❤️ bởi [befailproof.ai](https://befailproof.ai) ở SF và Bengaluru. diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md index e07fead3..0c849ab9 100644 --- a/docs/i18n/README.zh.md +++ b/docs/i18n/README.zh.md @@ -15,10 +15,10 @@ [![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://docs.befailproof.ai/introduction) [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](../../LICENSE) -**翻译：** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) +**翻译版本：** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**为编程 Agent 提供运行时故障处理能力。** -接入 Claude Code 和 Codex，在循环、危险操作和密钥泄漏演变为事故之前将其拦截。零延迟，本地运行。 +**编码智能体的运行时故障处理工具。** +深度集成 Claude Code 与 Codex。在循环、危险操作和密钥泄露酿成事故之前将其拦截。零延迟，本地运行。 @@ -28,7 +28,7 @@ --- -## 支持的 Agent CLI +## 支持的智能体 CLI {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -128,11 +128,11 @@ ```sh npm install -g failproofai -failproofai policies --install # 或直接运行 `failproofai` 并在首次运行提示时确认 +failproofai policies --install # 或直接运行 `failproofai` 并在首次运行提示中确认 failproofai ``` -30 条内置策略立即生效。控制台地址：`localhost:8020`。可通过设置 `FAILPROOFAI_NO_FIRST_RUN=1` 禁用首次运行提示。 +30 条内置策略立即生效。控制台地址：`localhost:8020`。使用 `FAILPROOFAI_NO_FIRST_RUN=1` 可禁用首次运行提示。 --- @@ -142,9 +142,9 @@ failproofai |---|---| | `block-push-master` | 直接推送到 `main` / `master` 分支 | | `block-force-push` | `git push --force` | -| `block-work-on-main` | 在 `main` / `master` 上执行提交、合并、变基 | +| `block-work-on-main` | 在 `main` / `master` 上提交、合并、变基 | | `block-rm-rf` | 递归删除文件 | -| `sanitize-api-keys` | API 密钥泄漏至 Agent 上下文 | +| `sanitize-api-keys` | API 密钥泄露到智能体上下文 | → [全部 30 条内置策略](https://docs.befailproof.ai/built-in-policies) @@ -152,8 +152,7 @@ failproofai ## 自定义策略 -将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何参数。 -提交到代码仓库后，团队成员下次拉取代码时即可生效。 +将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何额外参数。提交到版本库后，团队成员在下次拉取时即可获得。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -169,21 +168,21 @@ customPolicies.add({ }); ``` -每条策略可使用三种决策： +每条策略可使用以下三种决策： | 决策 | 效果 | |---|---| -| `allow()` | 允许该操作 | -| `deny(message)` | 拦截操作——消息将返回给 Agent | -| `instruct(message)` | 放行操作，但在 Agent 的下一条提示中附加上下文信息 | +| `allow()` | 允许操作 | +| `deny(message)` | 阻止操作——消息将返回给智能体 | +| `instruct(message)` | 放行操作，但在智能体的下一个提示中附加上下文信息 | → [自定义策略指南](https://docs.befailproof.ai/custom-policies) --- -## 会话可视化 +## 会话可见性 -Agent 发起的每次工具调用都会在本地记录日志。控制台展示已执行的操作、已拦截的操作，以及策略向 Agent 返回的内容——出现问题时无需猜测。→ [控制台指南](https://docs.befailproof.ai/dashboard) +智能体发起的每次工具调用均会在本地记录。控制台将展示执行情况、拦截详情以及策略向智能体反馈的内容——出现问题时无需盲目猜测。→ [控制台指南](https://docs.befailproof.ai/dashboard) --- @@ -191,29 +190,27 @@ Agent 发起的每次工具调用都会在本地记录日志。控制台展示 | | | |---|---| -| [快速入门](https://docs.befailproof.ai/getting-started) | 安装与初始步骤 | -| [内置策略](https://docs.befailproof.ai/built-in-policies) | 全部 30 条策略及其参数 | -| [自定义策略](https://docs.befailproof.ai/custom-policies) | 编写自己的策略 | +| [快速上手](https://docs.befailproof.ai/getting-started) | 安装与初始步骤 | +| [内置策略](https://docs.befailproof.ai/built-in-policies) | 全部 30 条策略及参数说明 | +| [自定义策略](https://docs.befailproof.ai/custom-policies) | 编写你自己的策略 | | [配置](https://docs.befailproof.ai/configuration) | 配置作用域与合并规则 | | [控制台](https://docs.befailproof.ai/dashboard) | 会话监控与策略活动 | -| [架构](https://docs.befailproof.ai/architecture) | Hook 系统的工作原理 | +| [架构](https://docs.befailproof.ai/architecture) | Hook 系统工作原理 | --- ## 许可证 -MIT 附加 [Commons Clause](https://commonsclause.com/)——可免费用于内部及个人用途；将 failproofai 本身进行商业转售须另行签订协议。完整条款见 [LICENSE](../../LICENSE)。 +MIT 附加 [Commons Clause](https://commonsclause.com/) ——个人及内部使用免费；将 failproofai 本身用于商业转售需另行签订协议。完整条款请参阅 [LICENSE](../../LICENSE)。 --- -## 贡献 +## 参与贡献 -请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。欢迎贡献新策略、边界用例及翻译。 +请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。欢迎贡献新策略、边界用例及翻译内容。 -> **开始前请先构建项目。** 首先运行 `bun install && bun run build`。本仓库会将 failproofai 自身的 Hook 应用于自身，这些 Hook 会从已编译的 `dist/` 包中解析 `failproofai` 导入——若未构建，将触发 `Cannot find package 'failproofai'` Hook 错误。修改 `src/` 后请重新构建。详见 -> [构建后才能使用仓库内的开发 Hook](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 +> **开始前请先构建项目。** 首先运行 `bun install && bun run build`。本仓库会对自身运行 failproofai 的 hooks，这些 hooks 会将 `failproofai` 的导入解析到编译后的 `dist/` 包——若未构建，将触发 `Cannot find package 'failproofai'` 错误。修改 `src/` 后请重新构建。详见 [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 --- -由 [Nivedit Jain](https://github.com/NiveditJain) 和 [Nikita Agarwal](https://github.com/nk-ag) 构建。 -[befailproof.ai](https://befailproof.ai) +由 [befailproof.ai](https://befailproof.ai) 团队用 ❤️ 构建于旧金山与班加罗尔。 diff --git a/docs/it/agenteye/alerts.mdx b/docs/it/agenteye/alerts.mdx index e82ea1e2..e3d558d2 100644 --- a/docs/it/agenteye/alerts.mdx +++ b/docs/it/agenteye/alerts.mdx @@ -1,62 +1,62 @@ --- title: "Avvisi" -description: "Scopri nel momento stesso in cui qualcosa supera i tuoi limiti, sul canale che il tuo team già monitora, invece di venire a conoscenza dal cliente." +description: "Scopri nel momento esatto in cui qualcosa supera il limite, sul canale che il tuo team già monitora, invece di sentirlo dire da un cliente." --- -Scopri nel momento stesso in cui qualcosa supera i tuoi limiti, sul canale che il tuo team già monitora, invece di venire a conoscenza dal cliente. Imposta una regola una volta e Failproof AI Observability la controlla secondo una pianificazione, poi ti avvisa via email, Slack, webhook o direttamente nella dashboard. +Scopri nel momento esatto in cui qualcosa supera il limite, sul canale che il tuo team già monitora, invece di sentirlo dire da un cliente. Imposta una regola una volta e Failproof AI Observability la verifica secondo una pianificazione, quindi ti avvisa via email, Slack, webhook, o direttamente nel dashboard. -![La pagina Avvisi: una griglia di schede di regole di avviso, ognuna che mostra il suo trigger, la finestra di valutazione, i canali e un badge di gravità info, warning o critical](/agenteye/images/alerts.png) +![La pagina degli Avvisi: una griglia di schede di regole di avviso, ciascuna che mostra il suo trigger, la finestra di valutazione, i canali e un badge di severità info, warning o critical](/agenteye/images/alerts.png) *Ogni regola di avviso a colpo d'occhio: cosa monitora, con quale frequenza, dove avvisa e quanto è urgente.* -## Vieni a conoscenza dei problemi prima dei tuoi utenti +## Ricevi notizie dei problemi prima dei tuoi utenti -Smetti di aggiornare una dashboard sperando di cogliere una regressione. Imposta un avviso ogni volta che c'è un segnale che vorresti conoscere anche quando nessuno sta guardando, e fallo arrivare dove sei già: +Smetti di aggiornare un dashboard nella speranza di cogliere una regressione. Usa un avviso ogni volta che c'è un segnale che vorresti ascoltare anche quando nessuno sta guardando, e fallo arrivare dove sei già: -- **Email**, a chiunque debba saperlo. -- **Slack**, un messaggio ricco con un pulsante che ti porta direttamente all'incidente. -- **Webhook**, un POST JSON per PagerDuty, Opsgenie o il tuo endpoint, con una firma opzionale in modo che il destinatario possa fidarsi. -- **In-dashboard**, silenzioso per design, per quando stai mettendo a punto una regola e non vuoi avvisare ancora nessuno. +- **Email**, a chi deve saperlo. +- **Slack**, un messaggio ricco con un pulsante che ti porta dritto all'incidente. +- **Webhook**, un POST JSON per PagerDuty, Opsgenie, o il tuo endpoint personale, con una firma opzionale in modo che il destinatario possa fidarsi. +- **Nel dashboard**, silenzioso per design, per quando stai mettendo a punto una regola e non vuoi ancora avvisare nessuno. -Allega qualsiasi combinazione a una singola regola, e la sua gravità (info, warning o critical) viene mantenuta in modo che gli urgenti sembrino urgenti. +Allega qualsiasi combinazione a una singola regola, e la sua severità (info, warning o critical) va insieme, così quelle urgenti sembrano urgenti. -## Costruisci la regola in un form, non in JSON +## Costruisci la regola in un modulo, non in JSON -Descrivi cosa significa "rotto" in un form, e Failproof AI Observability scrive la regola sottostante per te. La spec JSON è semplicemente ciò che quel form produce dietro le quinte, quindi puoi leggerla per capire una regola ma raramente la digiti. +Descrivi cosa significa "rotto" in un modulo, e Failproof AI Observability scrive la regola sottostante per te. La spec JSON è solo quello che il modulo produce dietro le quinte, così puoi leggerla per capire una regola ma raramente la digiti. -![Il form per il nuovo avviso: nome e descrizione, un toggle abilitato e un picker di trigger che offre soglia di metrica, SQL personalizzato, punteggio di valutazione, valutazione composta e condizioni per evento](/agenteye/images/alert-new.png) -*Scegli un trigger e il form mostra i campi giusti; Salva scrive la regola.* +![Il modulo new-alert: nome e descrizione, un toggle abilitato, e un selettore di trigger che offre metric threshold, custom SQL, evaluation score, compound eval e per-event conditions](/agenteye/images/alert-new.png) +*Scegli un trigger e il modulo cambia i campi giusti; Salva scrive la regola.* -Il percorso semplice è veloce: nominalo, scegli un **trigger** (cosa monitorare), imposta la **soglia e la finestra** (quanto grave, per quanto tempo), allega almeno un **canale**, quindi **Salva** e premi **Test** per attivare una notifica sintetica e confermare che ogni destinazione è collegata. Dietro le quinte questo produce una spec piccola come: +Il percorso facile è veloce: chiamalo, scegli un **trigger** (cosa monitorare), imposta la **soglia e la finestra** (quanto grave, in quanto tempo), allega almeno un **canale**, quindi **Salva** e fai clic su **Test** per inviare una notifica sintetica e confermare che ogni destinazione è collegata. Dietro le quinte quello produce una spec piccola come: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -Non sei limitato a un solo tipo di segnale. Scegli il trigger che corrisponde a come pensi al guasto: +Non sei limitato a un tipo di segnale. Scegli il trigger che corrisponde a come pensi al guasto: | Trigger | Si attiva quando | |---|---| -| **Soglia di metrica** | una metrica preimpostata (tasso di errore, latenza p95 o p99, conteggi di eventi o errori, spesa di token) supera il tuo limite in una finestra | -| **SQL personalizzato** | la tua query di sola lettura restituisce una riga, o un valore che calcola supera una soglia | -| **Punteggio di valutazione** | la media del punteggio di un valutatore (ad es. allucinazione) supera una soglia | -| **Valutazione composta** | diversi controlli di punteggio si combinano con logica any, all o at-least-N, per cogliere una regressione che si vede solo nei punteggi | -| **Per evento** | arriva un singolo evento corrispondente: un agente specifico, un tipo di errore specifico o una sottostringa di messaggio | +| **Metric threshold** | una metrica preimpostata (error rate, latenza p95 o p99, conteggi di eventi o errori, spesa token) supera il tuo limite in una finestra | +| **Custom SQL** | la tua query di sola lettura restituisce una riga, o un valore che calcola supera una soglia | +| **Evaluation score** | la media di un punteggio di valutazione (es. allucinazione) supera una soglia | +| **Compound eval** | vari controlli di punteggio si combinano con logica any, all, o at-least-N, per cogliere una regressione che si manifesta solo tra i punteggi | +| **Per event** | arriva un singolo evento corrispondente: un agent specifico, un tipo di errore specifico, o una sottostringaa di messaggio | -Stai già guardando un guasto sulla [pagina Errori](/it/agenteye/error-tracking)? Ogni riga lì ha un pulsante **+ avviso** che apre questo stesso form precompilato per cogliere quel guasto esatto di nuovo, così l'incidente che hai appena triato diventa quello che ti avviserà la prossima volta. +Già stai fissando un guasto nella [pagina Errori](/it/agenteye/error-tracking)? Ogni riga lì ha un pulsante **+ alert** che apre questo stesso modulo precompilato per cogliere esattamente quel guasto di nuovo, così l'incidente che hai appena esaminato diventa quello che ti avvisa la prossima volta. -**Dove trovarlo:** Gli avvisi si trovano in `//alerts`. La creazione, modifica, eliminazione e test delle regole richiede **`alerts:write`**; `alerts:read` è sufficiente per visualizzare. Il picker dei destinatari elenca i membri della tua organizzazione per nome, così puoi avvisare una persona senza lasciare il form. +**Dove trovarlo:** Gli Avvisi si trovano in `//alerts`. La creazione, modifica, eliminazione e test delle regole richiedono **`alerts:write`**; `alerts:read` è sufficiente per guardare. Il selettore del destinatario elenca i membri della tua organizzazione per nome, così puoi avvisare una persona senza lasciare il modulo. ## Avvisami solo quando è reale -Una misurazione errata non dovrebbe svegliarti. Il filtro di rumore **M di N** controlla quanti degli ultimi controlli devono fallire prima che l'avviso ti paghi effettivamente. Impostalo su **3 di 5** e la regola si attiva solo dopo che ha violato tre dei suoi ultimi cinque controlli, quindi un segnale instabile smette di dare falsi allarmi; lascialo al default **1 di 1** per attivarsi al primo sfondamento. Scegli anche con quale frequenza la regola viene eseguita, da preset di 1m, 5m, 15m e 1h, adattati a quanto veloce il segnale si muove veramente. +Una cattiva misurazione non dovrebbe svegliarti. Il filtro antirumore **M of N** controlla quanti degli ultimi controlli devono fallire prima che l'avviso ti avvisi effettivamente. Impostalo su **3 of 5** e la regola si attiva solo dopo che ha superato tre dei suoi ultimi cinque controlli, così un segnale traballante smette di suonare falsi allarmi; lascialo al valore predefinito **1 of 1** per attivarsi al primo superamento. Scegli anche con quale frequenza la regola viene eseguita, da preset di 1m, 5m, 15m e 1h, abbinati a quanto velocemente il segnale si muove veramente. -## Cosa succede quando un avviso si attiva +## Cosa accade quando un avviso si attiva -Una violazione apre un **incidente** e avvisa i tuoi canali una volta. Da lì il tuo team lo riconosce, assegna un proprietario, ne discute e lo risolve, tutto su un registro pulito e attribuito. Quel flusso di lavoro di triage ha la sua casa: vedi [Incidenti](/it/agenteye/incidents). +Una violazione apre un **incidente** e avvisa i tuoi canali una volta. Da lì il tuo team lo riconosce, assegna un proprietario, ne parla e lo risolve, tutto rispetto a un record pulito e attribuito. Quel flusso di lavoro di triage ha la sua casa: vedi [Incidenti](/it/agenteye/incidents). ## Correlati -- [Incidenti](/it/agenteye/incidents): traccia un avviso che si attiva da aperto a riconosciuto a risolto. -- [Tracciamento degli errori](/it/agenteye/error-tracking): raggruppa i guasti degli agenti e promuovi uno a avviso in un click. -- [Dashboard](/it/agenteye/dashboards): osserva le board condivise da cui provengono le soglie su cui avvisi. -- [CLI e agenti](/it/agenteye/cli-and-agents): crea avvisi e riconosci incidenti dal tuo terminale, o scrivili in CI. \ No newline at end of file +- [Incidenti](/it/agenteye/incidents): traccia un avviso attivato da aperto a riconosciuto a risolto. +- [Tracciamento errori](/it/agenteye/error-tracking): raggruppa i guasti degli agent e promuovi uno a avviso in un clic. +- [Dashboard](/it/agenteye/dashboards): monitora le schede condivise da cui provengono le soglie su cui avvisi. +- [CLI e agent](/it/agenteye/cli-and-agents): crea avvisi e riconosci incidenti dal tuo terminale, oppure inseriscili in CI. \ No newline at end of file diff --git a/docs/it/agenteye/api-keys.mdx b/docs/it/agenteye/api-keys.mdx index 64034cf5..addecf0d 100644 --- a/docs/it/agenteye/api-keys.mdx +++ b/docs/it/agenteye/api-keys.mdx @@ -1,154 +1,154 @@ --- title: "Chiavi API" -description: "Le chiavi API controllano chi e cosa può raggiungere il tuo server Failproof AI Observability, in modo che un collector possa inviare eventi senza mai acquisire permessi di lettura o amministrazione." +description: "Le chiavi API controllano chi e cosa può raggiungere il tuo server Failproof AI Observability, permettendo a un collector di inviare eventi senza mai ottenere poteri di lettura o amministrazione." --- -Le chiavi API controllano chi e cosa può raggiungere il tuo server Failproof AI Observability, in modo che un collector possa inviare eventi senza mai acquisire permessi di lettura o amministrazione. Ogni chiave porta uno o più permessi e ogni permesso controlla specifiche rotte del server; concedi solo quelli di cui un job ha bisogno. La maggior parte delle implementazioni crea solo tre tipi di chiave. +Le chiavi API controllano chi e cosa può raggiungere il tuo server Failproof AI Observability, permettendo a un collector di inviare eventi senza mai ottenere poteri di lettura o amministrazione. Ogni chiave porta uno o più permessi, e ogni permesso controlla route specifiche del server; si concedono solo quelli di cui un lavoro ha bisogno. La maggior parte dei deployment crea solo tre tipi di chiave. -## Le 3 chiavi di cui la maggior parte delle implementazioni ha bisogno +## Le 3 chiavi che la maggior parte dei deployment necessita | Chiave | Permessi | Chi la usa | |---|---|---| -| Chiave collector | `events:add` | L'`agenteye-collector` su ogni macchina agente, per inviare eventi. | -| Chiave lettura dashboard | `events:read`, `keys:read` | Un operatore di sola lettura o un'integrazione che interroga dati senza modificarli. | -| Chiave amministratore bootstrap | tutti i permessi | L'operatore che avvia l'istanza (e il dashboard). Fornita dalla variabile d'ambiente `ADMIN_KEY`. Vedi [Chiave amministratore bootstrap](#chiave-amministratore-bootstrap). | +| Chiave collector | `events:add` | Il `agenteye-collector` su ogni macchina agent, per inviare eventi. | +| Chiave lettura dashboard | `events:read`, `keys:read` | Un operatore di sola lettura o un'integrazione che interroga i dati senza modificarli. | +| Chiave admin bootstrap | tutti i permessi | L'operatore che fa partire per primo l'istanza (e il dashboard). Fornita dalla variabile di ambiente `ADMIN_KEY`. Vedi [Chiave admin bootstrap](#chiave-admin-bootstrap). | -Inizia da qui. Consulta il catalogo completo dei permessi qui sotto solo quando hai bisogno di una chiave più ristretta e personalizzata. Vedi anche [Layout di chiave consigliato](#layout-di-chiave-consigliato) e [Creazione di chiavi](#creazione-di-chiavi). +Inizia qui. Consulta l'elenco completo dei permessi qui sotto solo quando hai bisogno di una chiave personalizzata con scope più ristretto. Vedi anche [Layout chiave consigliato](#layout-chiave-consigliato) e [Creazione di chiavi](#creazione-di-chiavi). --- ## Permessi -Il server applica un catalogo fisso di permessi; ognuno controlla specifiche rotte HTTP. Una **chiave amministratore** li contiene tutti; una chiave limitata contiene il sottoinsieme che concedi al momento della creazione. Le stringhe di permesso sconosciute vengono rifiutate quando viene creata una chiave. +Il server applica un catalogo fisso di permessi; ciascuno controlla route HTTP specifiche. Una **chiave admin** li contiene tutti; una chiave scoped contiene il sottoinsieme che concedi al momento della creazione. Le stringhe di permesso sconosciute vengono rifiutate quando viene creata una chiave. -> **Nota:** Due permessi validi sono solo per umani/dashboard e non possono essere concessi a una chiave API: `orgs:admin` (amministrazione dell'istanza, solo per operatori) e `keys:update`. Una richiesta a `POST /keys` o `PATCH /keys/:id` che tenta di concedere uno di questi viene rifiutata con HTTP 422. Vedi la riga `keys:update` di seguito per capire perché una chiave bearer può creare chiavi ma mai modificarle. +> **Nota:** Due permessi validi sono solo per umani/dashboard e non possono essere concessi a una chiave API: `orgs:admin` (amministrazione dell'istanza, solo operatore) e `keys:update`. Una richiesta a `POST /keys` o `PATCH /keys/:id` che tenta di concedere uno di questi viene rifiutata con HTTP 422. Vedi la riga `keys:update` qui sotto per capire perché una chiave bearer può creare chiavi ma non modificarle. -### Ingestione e interrogazione di eventi +### Ingest e query di eventi -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `events:add` | `POST /events` | Ingestione di batch di eventi da un collector. L'unico permesso di cui un collector ha bisogno. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Interrogazione di eventi, elenco degli ambienti noti, elenco degli identificativi di modello visti nei dati (usato dalla vista Modelli e dai filtri dei modelli), calcolo dell'aggregato di latenza che alimenta la mappa di calore/banda percentile ed esportazione di una sessione come JSONL. Gli endpoint della barra di filtro condivisa `GET /events/environments` e `GET /events/agent_ids` sono raggiungibili con **uno qualsiasi** tra `events:read` **o** `evaluations:read`, in modo che la pagina sessioni (controllata da `evaluations:read`) riutilizzi lo stesso aspetto per organizzazione. `GET /events/models` non fa parte di loro: richiede `events:read`, quindi un soggetto che possiede solo `evaluations:read` riceve un 403. | +| `events:add` | `POST /events` | Ingest batch di eventi da un collector. L'unico permesso che un collector necessita. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Interrogare gli eventi, elencare gli ambienti conosciuti, elencare gli identificatori di modello visti nei dati (usato dalla vista Modelli e dai filtri dei modelli), calcolare l'aggregato di latenza che alimenta la mappa di calore / banda percentile, ed esportare una sessione come JSONL. Gli endpoint facet della barra di filtro condivisi `GET /events/environments` e `GET /events/agent_ids` sono raggiungibili con **entrambi** `events:read` **o** `evaluations:read`, quindi la pagina sessioni (controllata da `evaluations:read`) riutilizza lo stesso facet per-org. `GET /events/models` non è uno di questi: richiede `events:read`, quindi un principal che detiene solo `evaluations:read` riceve 403. | ### Sessioni e valutazioni -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Elenco delle sessioni, lettura dei risultati di valutazione, lo stato di salute della valutazione aggregato utilizzato dai dashboard e lo stato della coda di worker dei job di valutazione. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Accodamento manuale di una rivalutazione per una sessione completata. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Elencare sessioni, leggere risultati di valutazione, la salute della valutazione aggregata usata dai dashboard, e lo stato della coda di lavoro evaluation-job. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Accodare manualmente una ri-valutazione per una sessione completata. | ### Dashboard -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Elenco dei dashboard, caricamento di uno e lettura dei suoi tile. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Creazione e modifica dei dashboard, aggiunta/modifica/rimozione dei tile e riordinamento della griglia dei tile. | -| `dashboards:delete` | `DELETE /dashboards/:id` | Eliminazione di un intero dashboard (l'eliminazione a livello di tile rientra in `dashboards:write`). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Elencare dashboard, caricarne uno, e leggere i suoi tile. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Creare e modificare dashboard, aggiungere / modificare / rimuovere tile, e riordinare la griglia dei tile. | +| `dashboards:delete` | `DELETE /dashboards/:id` | Eliminare un intero dashboard (l'eliminazione a livello di tile è sotto `dashboards:write`). | -### Query salvate (compositore SQL) +### Query salvate (SQL composer) -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Elenco delle query salvate, caricamento di una e ispezione dello schema di sola lettura a cui il compositore è destinato. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | Creazione e modifica delle query salvate. SQL viene comunque instradato attraverso lo stesso ruolo di sola lettura e controlli SQL protetti come una chiamata `queries:run`. | -| `queries:delete` | `DELETE /queries/:id` | Eliminazione di una query salvata. | -| `queries:run` | `POST /queries/run` | Esecuzione di SQL salvato o ad hoc contro il ruolo di sola lettura utilizzato dal compositore. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Elencare query salvate, caricarne una, e ispezionare lo schema di sola lettura che il composer utilizza. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | Creare e modificare query salvate. SQL è ancora instradato attraverso lo stesso ruolo di sola lettura e i controlli SQL guarded come una chiamata `queries:run`. | +| `queries:delete` | `DELETE /queries/:id` | Eliminare una query salvata. | +| `queries:run` | `POST /queries/run` | Eseguire SQL salvato o ad-hoc contro il ruolo di sola lettura usato dal composer. | ### Assistente AI -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Comunicazione con l'assistente AI e gestione delle tue conversazioni personali (private). Richiesto sull'**utente** per visualizzare il dock dell'assistente; la chiave dell'assistente stesso è `dashboard-assistant` ed è fornita separatamente (vedi di seguito). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Parlare con l'assistente AI e gestire le tue conversazioni private. Richiesto sull'**utente** per vedere l'assistente dock; la propria chiave è `dashboard-assistant` ed è fornita separatamente (vedi sotto). | ### Chiavi API -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `keys:create` | `POST /keys` | Creazione di una nuova chiave API limitata. **Non** concede la modifica dei permessi di una chiave esistente (quello è `keys:update`). | -| `keys:read` | `GET /keys` | Elenco delle chiavi esistenti. I segreti non vengono mai restituiti da questo endpoint. | -| `keys:update` | `PATCH /keys/:id` | Modifica dei permessi di una chiave esistente. Un permesso **solo per umani/dashboard**; non può essere assegnato a una chiave API (una chiave bearer può creare chiavi ma mai modificarle). | -| `keys:disable` | `POST /keys/:id/disable` | Revoca di una chiave. Le chiavi protette (`admin`, `dashboard-assistant`) non possono essere disabilitate; ruotale tramite variabile di ambiente + riavvio. | -| `keys:regenerate` | `POST /keys/:id/regenerate` | Rotazione del segreto di una chiave. Le chiavi protette non possono essere rigenerate tramite questa rotta. | +| `keys:create` | `POST /keys` | Creare una nuova chiave API scoped. **Non** concede la modifica dei permessi di una chiave esistente (quello è `keys:update`). | +| `keys:read` | `GET /keys` | Elencare chiavi esistenti. I segreti non vengono mai restituiti da questo endpoint. | +| `keys:update` | `PATCH /keys/:id` | Modificare i permessi di una chiave esistente. Un permesso **solo umano/dashboard**; non può essere assegnato a una chiave API (una chiave bearer può creare chiavi ma non modificarle). | +| `keys:disable` | `POST /keys/:id/disable` | Revocare una chiave. Le chiavi protette (`admin`, `dashboard-assistant`) non possono essere disabilitate; ruotale tramite env var + restart. | +| `keys:regenerate` | `POST /keys/:id/regenerate` | Ruotare il segreto di una chiave. Le chiavi protette non possono essere rigenerate attraverso questa route. | -### Utenti del dashboard +### Utenti dashboard -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | Invito di un nuovo utente del dashboard (invia un'email + login con passcode monouso (OTP)) e lettura del set di permessi predefinito configurato nel dashboard utilizzato per inizializzare il modulo di invito. | -| `users:read` | `GET /users`, `GET /users/:id` | Elenco degli utenti e caricamento di un singolo record utente. | -| `users:update` | `PUT /users/:id` | Modifica dei permessi di un utente. Gli aggiornamenti inviano un'email di cambio permessi all'utente interessato e hanno effetto sulla sua prossima richiesta; non è richiesto il riaccesso. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Disabilitazione di un utente (revoca immediatamente le sue sessioni) e riabilitazione di un utente precedentemente disabilitato. | +| `users:create` | `POST /users`, `GET /users/defaults` | Invitare un nuovo utente dashboard (invia un email + accesso con passcode monouso (OTP)) e leggere il set di permessi predefinito configurato dal dashboard usato per seminare il modulo di invito. | +| `users:read` | `GET /users`, `GET /users/:id` | Elencare utenti e caricare un singolo record utente. | +| `users:update` | `PUT /users/:id` | Modificare i permessi di un utente. Gli aggiornamenti inviano un'email di cambio permessi all'utente interessato e hanno effetto alla prossima richiesta; nessun nuovo login richiesto. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Disabilitare un utente (revoca immediatamente le loro sessioni) e ri-abilitare un utente precedentemente disabilitato. | -Questi permessi supportano la pagina **Utenti** del dashboard, dove gli ambiti concessi di ogni membro sono mostrati come chip: +Questi permessi supportano la pagina **Utenti** del dashboard, dove gli scope concessi di ogni membro sono mostrati come chip: -![La pagina Utenti: una scheda per utente del dashboard con la sua email, permessi concessi e controlli di modifica/disabilitazione](/agenteye/images/users.png) +![La pagina Utenti: una card per utente dashboard con la loro email, permessi concessi, e controlli modifica/disabilita](/agenteye/images/users.png) ### Impostazioni operative -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Visualizzazione delle impostazioni operative gestite dal dashboard e dei loro metadati; elenco degli override della finestra di contesto per modello; e risoluzione della finestra effettiva per un modello. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Modifica delle impostazioni operative e aggiunta, modifica o rimozione degli override della finestra di contesto per modello. I cambiamenti interessano i nuovi eventi senza riavviare il server. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Visualizzare le impostazioni operative gestite dal dashboard e i loro metadati; elencare override della finestra contestuale per-modello; e risolvere la finestra effettiva per un modello. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Modificare le impostazioni operative e aggiungere, modificare o rimuovere override della finestra contestuale per-modello. I cambiamenti hanno effetto sui nuovi eventi senza riavviare il server. | -![La pagina Impostazioni: impostazioni operative gestite dal dashboard come accessi consentiti e durate di sessione/OTP, modificabili senza riavvio](/agenteye/images/settings.png) +![La pagina Impostazioni: impostazioni operative gestite dal dashboard come accessi consentiti e durate sessione/OTP, modificabili senza restart](/agenteye/images/settings.png) -### Avvisi e incidenti +### Avvisi e incident -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Visualizzazione delle definizioni di avviso configurate. | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Creazione, modifica, eliminazione e test-firing delle definizioni di avviso. | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Visualizzazione degli incidenti e della loro traccia di triage. | -| `incidents:write` | `POST /alerts/:id/incidents` | Apertura manuale di un incidente rispetto a un avviso esistente. | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Riconoscimento, assegnazione, risoluzione e commento degli incidenti. | +| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Visualizzare le definizioni di avviso configurate. | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Creare, modificare, eliminare e attivare le definizioni di avviso. | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Visualizzare gli incident e il loro percorso di triage. | +| `incidents:write` | `POST /alerts/:id/incidents` | Aprire manualmente un incident su un avviso esistente. | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Acknowledgment, assegnare, risolvere, e commentare gli incident. | ### Audit -| Permesso | Rotte HTTP | Cosa consente | +| Permesso | Route HTTP | Cosa consente | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Visualizzazione delle definizioni di audit, della cronologia di esecuzione e dei risultati. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Creazione, modifica, eliminazione ed esecuzione di audit; triage dei risultati (riconoscimento / silenziamento / dismissione / risoluzione / riapertura / assegnazione). | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Visualizzare definizioni audit, cronologia di esecuzione, e findings. | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Creare, modificare, eliminare, e eseguire audit; triage findings (acknowledge / mute / dismiss / resolve / reopen / assign). | -> **Nota:** Per concedere a una chiave la superficie di audit, assegna esplicitamente `audits:*` a essa. Vedi [Note di aggiornamento e compatibilità all'indietro](#note-di-aggiornamento-e-compatibilità-allindietro) per come i beneficiari esistenti sono stati migrati al rilascio di Audits. +> **Nota:** Per dare a una chiave la superficie audit, concedi `audits:*` esplicitamente. Vedi [Note di upgrade e retrocompatibilità](#note-di-upgrade-e-retrocompatibilità) per come i grantee esistenti sono stati migrati quando Audits è stato lanciato. -> L'endpoint del selettore dei destinatari `GET /alerts/recipients` (che elenca le email dei membri che un editor di avvisi può notificare) è raggiungibile da un titolare di **uno qualsiasi** tra `alerts:read` **o** `alerts:write`, così gli editor di avvisi possono popolare il selettore senza essere assegnati a `users:read`. +> L'endpoint recipient-picker `GET /alerts/recipients` (che elenca le email dei membri che un editor di avviso può notificare) è raggiungibile da un detentore di **entrambi** `alerts:read` **o** `alerts:write`, quindi gli editor di avviso possono popolare il picker senza essere concesso `users:read`. -> Un visualizzatore di dashboard ha bisogno di **entrambi** `dashboards:read` (per caricare le viste salvate) e `evaluations:read` (le metriche di salute vengono calcolate dai dati di valutazione). Assegna `dashboards:write` per consentire a un utente di creare o modificare dashboard e `dashboards:delete` per rimuoverli. +> Un visualizzatore di dashboard necessita **entrambi** `dashboards:read` (per caricare le visualizzazioni salvate) e `evaluations:read` (le metriche di salute sono calcolate dai dati di valutazione). Concedi `dashboards:write` per permettere a un utente di creare o modificare dashboard, e `dashboards:delete` per rimuoverli. -> `/health` e `/auth/*` (richiesta OTP, verifica OTP, controllo sessione, logout) sono senza autenticazione per progettazione; sono il flusso di accesso e la sonda di vivacità. `GET /access-granters` richiede una chiave valida ma nessun permesso specifico, in modo che qualsiasi utente registrato possa vedere quali amministratori contattare per i cambiamenti di accesso. +> `/health` e `/auth/*` (richiesta OTP, verifica OTP, controllo sessione, logout) sono non autenticati per design; sono il flusso di login e la sonda di liveness. `GET /access-granters` richiede una chiave valida ma nessun permesso specifico, quindi qualsiasi utente autenticato può vedere quali admin contattare per i cambiamenti di accesso. --- ## Set di permessi -I set di permessi ti permettono di applicare un ruolo denominato invece di selezionare manualmente i token individuali ogni volta. Invece di selezionare una dozzina di permessi uno per uno per ogni nuovo utente del dashboard o chiave API, scegli un set e tutti assegnati a esso portano una concessione coerente e verificabile. La modifica di un set personalizzato riapplica la nuova concessione a ogni utente già assegnato a esso, quindi un cambiamento di ruolo è una modifica piuttosto che un'operazione su ogni membro. +I set di permessi ti permettono di applicare un ruolo denominato invece di scegliere manualmente token individuali ogni volta. Invece di selezionare una dozzina di permessi uno per uno per ogni nuovo utente dashboard o chiave API, scegli un set, e chiunque sia assegnato ad esso porta una concessione coerente e revisionabile. Modificare un set personalizzato ri-applica la nuova concessione a ogni utente già assegnato ad esso, quindi un cambio ruolo è una modifica invece di un passaggio attraverso ogni membro. -Ogni organizzazione è inizializzata con tre set incorporati: +Ogni organizzazione è seminata con tre set built-in: | Set | Permessi | Destinato a | |---|---|---| | `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Accesso di sola visualizzazione su ogni superficie operativa. | -| `standard` | tutto in `read-only`, più `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Sola lettura più le azioni quotidiane on-caller: esecuzione di query, rivalutazione di sessioni, riconoscimento di incidenti e uso dell'assistente AI. | -| `admin` | ogni permesso assegnabile | Controllo completo dell'organizzazione. | +| `standard` | tutto in `read-only`, più `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Sola lettura più le azioni quotidiane per on-caller: eseguire query, ri-valutare sessioni, acknowledgment incident, e usare l'assistente AI. | +| `admin` | ogni permesso assegnabile | Controllo totale dell'org. | -I tre set incorporati sono **immutabili**; i loro nomi significano sempre la stessa cosa, quindi `read-only`, `standard` e `admin` sono sicuri da referenziare in policy e onboarding. Un operatore può creare **set personalizzati** aggiuntivi per modellare ruoli specifici della tua organizzazione (ad esempio, un ruolo di "autore di dashboard" o un ruolo di "solo collector"). +I tre set built-in sono **immutabili**; i loro nomi significano sempre la stessa cosa, quindi `read-only`, `standard`, e `admin` sono sicuri da referenziare in policy e onboarding. Un operatore può creare ulteriori **set personalizzati** per modellare ruoli specifici della tua organizzazione (per esempio, un ruolo di "dashboard author" o un ruolo "collector-only"). -I set sono presentati nel dashboard e gestiti tramite API su `GET /permission-sets` (elenco, controllato da `users:read`) e `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (creazione, modifica, eliminazione di un set personalizzato, controllato da `settings:write`). L'eliminazione o la modifica di un set incorporato viene rifiutata. +I set sono presentati nel dashboard e gestiti sull'API su `GET /permission-sets` (elencare, controllato da `users:read`) e `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (creare, modificare, eliminare un set personalizzato, controllato da `settings:write`). L'eliminazione o la modifica di un set built-in è rifiutata. -L'appartenenza al set è ciò che supporta due altre funzionalità: +L'appartenenza al set è ciò che supporta altre due funzionalità: -- **`DEFAULT_USER_PERMISSIONS`** (la concessione preselezionata quando un amministratore apre **+ nuovo utente**) per impostazione predefinita è il set `standard`. -- **Il flag `--set`** su `agenteye-orgctl` (gestione dei membri dell'organizzazione) avvia un membro da un set denominato, che quindi affini con `--add` / `--remove`. +- **`DEFAULT_USER_PERMISSIONS`** (la concessione preselezionata quando un admin apre **+ nuovo utente**) di default è il set `standard`. +- **Il flag `--set`** su `agenteye-orgctl` (gestione membri operatore) inizia un membro da un set denominato, che puoi poi affinare con `--add` / `--remove`. -> **Nota:** Quando un set include un permesso che non è assegnabile a una chiave (ad esempio un set personalizzato con `keys:update`), l'inizializzazione di una chiave da quel set elimina i token non assegnabili; il server altrimenti rifiuterebbe la chiave con HTTP 422. Gli utenti del dashboard non sono soggetti a quella restrizione. +> **Nota:** Quando un set include un permesso che non è assegnabile a chiave (per esempio un set personalizzato portando `keys:update`), seminare una chiave da quel set scarta i token non assegnabili; il server rifiuterebbe altrimenti la chiave con HTTP 422. Gli utenti dashboard non sono soggetti a quella restrizione. --- -## Chiave amministratore bootstrap +## Chiave admin bootstrap -La chiave amministratore è la credenziale radice singola che consente a un operatore di avviare l'accesso da zero: con essa puoi creare ogni altra chiave limitata, invitare i primi utenti del dashboard e configurare l'istanza prima che esista qualsiasi altra chiave. È l'unica chiave che non crei tramite l'API delle chiavi; è fornita dall'ambiente in modo che il server sia raggiungibile al primo avvio. +La chiave admin è la singola credenziale root che permette a un operatore di portare su l'accesso dal nulla: con essa puoi creare ogni altra chiave scoped, invitare i primi utenti dashboard, e configurare l'istanza prima che qualsiasi altra chiave esista. È l'unica chiave che non crei attraverso l'API delle chiavi; è fornita dall'ambiente così il server è raggiungibile al primo avvio. -Imposta la variabile d'ambiente `ADMIN_KEY` sul server. Ad ogni avvio il server inserisce/aggiorna questo valore come una chiave amministratore con tutti i permessi. +Imposta la variabile di ambiente `ADMIN_KEY` sul server. Ad ogni avvio il server upsert questo valore come chiave admin con tutti i permessi. Per ruotare: cambia `ADMIN_KEY` con un nuovo segreto e riavvia il server. @@ -156,17 +156,17 @@ Per ruotare: cambia `ADMIN_KEY` con un nuovo segreto e riavvia il server. ## Scoping dell'organizzazione -**Le organizzazioni stesse sono create e gestite fuori banda da un operatore, non tramite questa API di chiavi.** Il ciclo di vita dell'organizzazione e del membro (creazione/ridenominazione/eliminazione/purga di un'organizzazione; aggiunta/aggiornamento/rimozione di un membro) viene eseguito con la CLI **`agenteye-orgctl`**; non esiste un'API HTTP o pulsante del dashboard per ciò. Quello che *rimane* invariato: **le chiavi API per organizzazione vengono comunque create nel dashboard (o tramite questa API di chiavi)** dai membri dell'organizzazione. +**Le organizzazioni stesse sono create e gestite out-of-band da un operatore, non attraverso questa API delle chiavi.** Il ciclo di vita org e membro (creare / rinominare / eliminare / purge un'org; aggiungere / aggiornare / rimuovere un membro) viene fatto con il CLI **`agenteye-orgctl`**; non c'è API HTTP o pulsante dashboard per esso. Ciò che *è* immutato: **le chiavi API per-org sono ancora create nel dashboard (o via questa API delle chiavi)** dai membri org. -In un'implementazione multi-org, ogni chiave che un membro dell'organizzazione crea (tramite questa API di chiavi o la pagina **Chiavi** del dashboard) appartiene a **un'organizzazione** e può solo leggere o scrivere i dati di quell'organizzazione; l'organizzazione viene timbrata sulla chiave al momento della creazione e applicata ad ogni richiesta. Le due chiavi bootstrap sono l'unica eccezione: la chiave `admin` (fornita da `ADMIN_KEY`) e la chiave `dashboard-assistant` (fornita da `AGENT_API_KEY`) sono **con ambito istanza** (non portano alcun'organizzazione). Il dashboard si autentica con la chiave `admin` in modo da poter rappresentare le richieste per organizzazione per conto dei membri registrati. Le implementazioni single-tenant non hanno bisogno di pensare a questo; tutte le chiavi appartengono all'organizzazione `default` incorporata. +In un deployment multi-org, ogni chiave che un membro org crea (attraverso questa API delle chiavi o la pagina dashboard **Chiavi**) appartiene a **un'organizzazione** e può solo leggere o scrivere i dati di quella org; l'org è marcata sulla chiave al momento della creazione ed è applicata su ogni richiesta. Le due chiavi bootstrap sono l'unica eccezione: la chiave `admin` (seminata da `ADMIN_KEY`) e la chiave `dashboard-assistant` (seminata da `AGENT_API_KEY`) sono **scoped all'istanza** (non portano org). Il dashboard si autentica con la chiave `admin` così può proxy richieste per-org per conto dei membri autenticati. I deployment single-tenant non devono pensare a questo; tutte le chiavi appartengono all'org built-in `default`. --- ## Creazione di chiavi -Usa la chiave amministratore (o qualsiasi chiave con permesso `keys:create`) per creare ulteriori chiavi limitate. +Usa la chiave admin (o qualsiasi chiave con permesso `keys:create`) per creare ulteriori chiavi scoped. -### Chiave collector (solo ingestione) +### Chiave collector (ingest only) ```bash curl -s -X POST http://your-server/keys \ @@ -179,7 +179,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### Chiave dashboard (sola lettura) +### Chiave dashboard (read only) ```bash curl -s -X POST http://your-server/keys \ @@ -192,7 +192,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -Quando crei una chiave tramite l'API HTTP, fornisci tu stesso il valore `key`; scegli un segreto forte e conservalo in modo sicuro. (Il dashboard funziona al contrario: genera un segreto forte per te e lo mostra una sola volta al momento della creazione; vedi [Gestione delle chiavi nel dashboard](#gestione-delle-chiavi-nel-dashboard).) La risposta conferma che la chiave è stata creata: +Quando crei una chiave tramite l'API HTTP, fornisci tu stesso il valore `key`; scegli un segreto forte e conservalo in modo sicuro. (Il dashboard funziona al contrario: genera un segreto forte per te e lo mostra una sola volta al momento della creazione; vedi [Gestione chiave nel dashboard](#gestione-chiave-nel-dashboard).) La risposta conferma che la chiave è stata creata: ```json { @@ -205,20 +205,20 @@ Quando crei una chiave tramite l'API HTTP, fornisci tu stesso il valore `key`; s --- -## Elenco delle chiavi +## Elenco di chiavi ```bash curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -I segreti delle chiavi non vengono restituiti negli elenchi, solo ID, nomi e permessi. +I segreti delle chiavi non vengono restituiti nelle risposte di elenco, solo ID, nomi, e permessi. --- ## Disabilitazione di una chiave -La disabilitazione revoca l'accesso immediatamente senza eliminare il record della chiave. +Disabilitare revoca l'accesso immediatamente senza eliminare il record della chiave. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -236,44 +236,44 @@ curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -La risposta include il nuovo segreto in testo libero, **mostrato una sola volta**. +La risposta include il nuovo segreto in testo piano, **mostrato una sola volta**. --- -## Gestione delle chiavi nel dashboard +## Gestione chiave nel dashboard -La pagina **Chiavi** nel dashboard fornisce un'interfaccia utente per tutte le operazioni di cui sopra. Hai bisogno di una chiave con permesso `keys:read` per visualizzare l'elenco e `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` per le azioni di creazione/modifica/disabilitazione/rigenerazione rispettivamente. La modifica dei permessi di una chiave (`keys:update`) è separata dalla creazione di una (`keys:create`), quindi puoi concedere a un operatore la capacità di creare chiavi senza la capacità di riscrivere le esistenti, o viceversa. La chiave amministratore copre tutti questi. +La pagina **Chiavi** nel dashboard fornisce un'interfaccia per tutte le operazioni sopra. Hai bisogno di una chiave con permesso `keys:read` per visualizzare l'elenco, e `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` per le azioni creare / modificare / disabilitare / rigenerare rispettivamente. Modificare i permessi di una chiave (`keys:update`) è separato dalla creazione di una (`keys:create`), quindi puoi concedere a un operatore la capacità di creare chiavi senza la capacità di ri-scope le esistenti, o viceversa. La chiave admin copre tutte questi. -Quando crei una chiave dal dashboard non fornisci il segreto; il dashboard genera un segreto forte per te e lo visualizza **una volta** al momento della creazione. Copialo immediatamente e conservalo in modo sicuro; non viene mai più mostrato, esattamente come con una rigenerazione. Puoi comunque selezionare i permessi della chiave direttamente o inizializzarli da un set di permessi (vedi di seguito). +Quando crei una chiave dal dashboard non fornisci il segreto; il dashboard genera un segreto forte per te e lo mostra **una volta** al momento della creazione. Copialo immediatamente e conservalo in modo sicuro; non è mai mostrato di nuovo, esattamente come con una rigenerazione. Puoi ancora scegliere i permessi della chiave direttamente, o seminarli da un set di permessi (vedi sotto). -![La pagina Chiavi API: una scheda per chiave che mostra il suo nome, permessi concessi e tempo di creazione, con azioni di rigenerazione e disabilitazione; le chiavi protette come `admin` sono contrassegnate](/agenteye/images/api-keys.png) +![La pagina Chiavi API: una card per chiave mostrando il suo nome, permessi concessi, e tempo di creazione, con azioni rigenerare e disabilitare; le chiavi protette come `admin` sono marcate](/agenteye/images/api-keys.png) --- -## Layout di chiave consigliato +## Layout chiave consigliato | Chiave | Permessi | Usata da | |---|---|---| -| `admin` (bootstrap tramite variabile d'ambiente `ADMIN_KEY`) | tutti | Ops/setup e il dashboard (autentica con `ADMIN_KEY`, rappresenta le richieste dell'utente con controlli di permessi) | -| Chiave collector per host | `events:add` | Collector su ogni macchina agente | -| `dashboard-assistant` (bootstrap tramite variabile d'ambiente `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistente AI, inizializzato automaticamente, **protetto**; non può essere modificato tramite l'API | +| `admin` (bootstrap via env var `ADMIN_KEY`) | tutti | Ops/setup, e il dashboard (si autentica con `ADMIN_KEY`, proxy richieste utente con controlli permessi) | +| Chiave collector per-host | `events:add` | Collector su ogni macchina agent | +| `dashboard-assistant` (bootstrap via env var `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistente AI, seminato automaticamente, **protetto**; non può essere modificato attraverso l'API | | Chiave telemetria assistente (opzionale) | `events:add` | Auto-strumentazione assistente AI, se abilitata | -> **Nota:** La chiave dell'assistente è **inizializzata automaticamente** dal server dalla variabile d'ambiente `AGENT_API_KEY` (lo stesso segreto che l'agente presenta come `AGENTEYE_API_KEY`); non c'è un passaggio manuale di creazione della chiave e nessuna chiave amministratore coinvolta. I suoi permessi sono fissi nel codice sorgente quindi l'ambito non può essere ampliato per errore di configurazione: lettura tra eventi/valutazioni/dashboard, più dashboards-write e queries-read/write/run per il flusso di authoring di "Chiedi AI di scrivere una query". Tutto il SQL passa comunque attraverso lo stesso ruolo di sola lettura e percorso SQL protetto come una query scritta dall'utente, quindi ciò amplia la *superficie di authoring*, non la superficie dei dati; le operazioni distruttive (`queries:delete`, `dashboards:delete`) rimangono deliberatamente fuori dalla chiave dell'assistente. Come la chiave `admin`, è **protetta**: non può essere disabilitata o rigenerata tramite l'API delle chiavi, solo ruotata cambiando `AGENT_API_KEY` e riavviando. Gli *utenti* del dashboard inoltre hanno bisogno del permesso `agent:use` per vedere e usare l'assistente. Se abiliti l'auto-strumentazione, dai all'assistente una chiave separata solo per `events:add`. +> **Nota:** La chiave dell'assistente è **seminata automaticamente** dal server dalla env var `AGENT_API_KEY` (lo stesso segreto che l'agent presenta come `AGENTEYE_API_KEY`); non c'è un passo di creazione chiave manuale e nessuna chiave admin coinvolta. I suoi permessi sono fissi nel codice sorgente quindi lo scope non può essere ampliato per misconfiguration: leggere attraverso eventi / valutazioni / dashboard, più dashboards-write e queries-read / write / run per il flusso di authoring "Chiedi AI di scrivere una query". Tutto SQL va ancora attraverso lo stesso ruolo di sola lettura e percorso SQL guarded come una query scritta dall'utente, quindi questo amplia la *superficie di authoring*, non quella dei dati; le operazioni distruttive (`queries:delete`, `dashboards:delete`) deliberatamente rimangono fuori dalla chiave assistente. Come la chiave `admin`, è **protetta**: non può essere disabilitata o rigenerata attraverso l'API delle chiavi, solo ruotata cambiando `AGENT_API_KEY` e riavviando. Gli *utenti* dashboard hanno inoltre bisogno del permesso `agent:use` per vedere e usare l'assistente. Se abiliti l'auto-strumentazione, dai all'assistente una chiave separata solo `events:add`. --- -## Note di aggiornamento e compatibilità all'indietro +## Note di upgrade e retrocompatibilità -Ne hai bisogno solo se stai aggiornando un'istanza esistente; le nuove implementazioni possono saltarle. +Ne hai bisogno solo se stai aggiornando un'istanza esistente; i nuovi deployment possono saltarle. -> Al rilascio di Audits, i beneficiari esistenti sono stati ampliati lungo le stesse forme di ruolo degli avvisi: ogni utente e set di permessi che contiene `alerts:read` ha acquisito `audits:read` e ogni titolare di `alerts:write` ha acquisito `audits:write`. Le chiavi API esistenti **non** sono state ampliate. Assegna `audits:*` a una chiave esplicitamente se necessita della superficie di audit. +> Quando Audits è stato lanciato, i grantee esistenti sono stati ampliati lungo le stesse forme di ruolo degli avvisi: ogni utente e set di permessi portando `alerts:read` ha guadagnato `audits:read`, e ogni detentore di `alerts:write` ha guadagnato `audits:write`. Le chiavi API esistenti **non** sono state ampliate. Concedi `audits:*` a una chiave esplicitamente se ha bisogno della superficie audit. -> Le concessioni memorizzate del token legacy `alerts:ack` vengono analizzate come `incidents:ack` in modo che gli on-caller mantengano l'accesso senza ricreate le chiavi. Il token non è più assegnabile dall'editor utente del dashboard; la matrice offre invece `incidents:ack`. +> Le concessioni archiviate del token legacy `alerts:ack` sono analizzate come `incidents:ack` quindi gli on-caller conservano l'accesso senza ricreaazione chiave. Il token non è più assegnabile dall'editor utente del dashboard; la matrice offre `incidents:ack` al suo posto. --- ## Prossimi passi -- [Python SDK](/it/agenteye/python-sdk): come il tuo codice agente si autentica quando invia eventi. -- [Sicurezza](/it/agenteye/security): come funzionano l'accesso, il controllo degli accessi e l'isolamento dei dati per organizzazione. \ No newline at end of file +- [Python SDK](/it/agenteye/python-sdk): come il tuo codice agent si autentica quando invia eventi. +- [Security](/it/agenteye/security): come sign-in, access control, e isolamento dati per-organizzazione funzionano. \ No newline at end of file diff --git a/docs/it/agenteye/assistant.mdx b/docs/it/agenteye/assistant.mdx index f9e75433..46450587 100644 --- a/docs/it/agenteye/assistant.mdx +++ b/docs/it/agenteye/assistant.mdx @@ -1,59 +1,60 @@ --- -title: "Assistente IA" -description: "Fai una domanda sui dati del tuo agente in linguaggio naturale e ottieni una risposta collegata direttamente alle prove." +title: "Assistente AI" +description: "Poni una domanda sui dati del tuo agente in inglese semplice e ottieni una risposta con collegamenti diretti alle prove." --- -Fai una domanda sui dati del tuo agente in linguaggio naturale e ottieni una risposta collegata direttamente alle prove. Niente SQL da scrivere, niente dashboard da frugare — l'assistente **Failproof AI Observability** è il modo più veloce per chiunque nel tuo team di ottenere risposte sui tuoi agenti. +Poni una domanda sui dati del tuo agente in inglese semplice e ottieni una risposta con collegamenti diretti alle prove. Niente SQL da scrivere, niente dashboard da consultare — l'assistente **Failproof AI Observability** è il modo più veloce per chiunque nel tuo team di ottenere risposte sui tuoi agenti. -![L'assistente Failproof AI Observability che risponde a una domanda in linguaggio naturale all'interno del dashboard, mostrando una tabella di Agent Activity dal vivo, una suddivisione dell'utilizzo del modello per agente e considerazioni scritte, con le query eseguite mostrate inline](/agenteye/images/assistant.png) -*Fai una domanda in linguaggio naturale e ottieni una risposta costruita dai tuoi dati. Qui scompone quali agenti sono più occupati e quali modelli usano, e mostra le query che ha eseguito per permetterti di verificare ogni numero.* +![L'assistente Failproof AI Observability che risponde a una domanda in inglese semplice dentro il dashboard, mostrando una tabella Activity live, un breakdown dell'utilizzo dei modelli per agente e considerazioni scritte, con le query eseguite mostrate inline](/agenteye/images/assistant.png) +*Chiedi in inglese semplice e ottieni una risposta costruita dai tuoi dati. Qui scompone quali agenti sono più occupati e quali modelli utilizzano, e mostra le query eseguite così puoi verificare ogni numero.* -Non c'è niente da imparare. Apri la chat, scrivi quello che vuoi sapere e segui i link che ti restituisce: +Non c'è niente da imparare. Apri la chat, digita quello che vuoi sapere e segui i link che ti restituisce: ``` -Tu: quali sessioni hanno avuto errori oggi? -IA: 5 sessioni hanno avuto errori oggi, le più recenti per prime. Ognuna è collegata: - • checkout-agent 14:02 tool timeout - • billing-agent 11:47 unhandled error - • ...e 3 altri +Tu: quali sessioni hanno errore oggi? +AI: 5 sessioni hanno errore oggi, le più recenti per prime. Ognuna è collegata: + • checkout-agent 14:02 timeout dello strumento + • billing-agent 11:47 errore non gestito + • ...e altre 3 Tu: riassumi questa sessione (chiesto mentre visualizzi un'esecuzione) -IA: Questa esecuzione ha richiesto 12 step su 3 tool e ha fallito verso la fine quando - un tool di pagamento ha restituito un errore. Ha ottenuto un basso punteggio - nella tua valutazione "resolved". Link: la sessione, l'evento che ha fallito e quella valutazione. +AI: Questa esecuzione ha richiesto 12 step su 3 strumenti e ha fallito verso + la fine quando uno strumento di pagamento ha restituito un errore. Ha + ottenuto un punteggio basso sulla tua valutazione "resolved". + Link: la sessione, l'evento che ha causato il fallimento e quella valutazione. ``` ## Chiedi semplicemente e vai diretto alle prove -Smetti di indovinare e smetti di scrivere query. Chiedi "come sta andando la qualità in prod questa settimana?", "quali sessioni hanno avuto errori oggi?", oppure "riassumi questa sessione", e ricevi una risposta diretta in pochi secondi invece di dover costruire una query e leggerla tu stesso. +Smetti di indovinare e smetti di scrivere query. Chiedi "come sta il quality trend in prod questa settimana?", "quali sessioni hanno errore oggi?" o "riassumi questa sessione" e ottieni una risposta diretta in secondi invece di costruire una query e leggerla tu stesso. -Ogni risposta viene fornita con le sue ricevute. L'assistente collega le esatte sessioni, le query salvate e i dashboard che ha utilizzato per arrivare alla risposta, così puoi cliccare e confermare invece di prendere la sua parola. È anche **consapevole della pagina**: se chiedi informazioni su "questa sessione" mentre ne stai visualizzando una, sa già quale esecuzione intendi. Riapri qualsiasi conversazione precedente in seguito dal selettore della cronologia e continua da dove hai interrotto. +Ogni risposta viene con le sue ricevute. L'assistente collega le sessioni esatte, le query salvate e i dashboard che ha usato per arrivare alla risposta, così puoi cliccare e verificare invece di fidarti della sua parola. È anche **consapevole della pagina**: chiedi di "questa sessione" mentre ne stai visualizzando una e sa già quale esecuzione intendi. Riapri qualsiasi conversazione precedente più tardi dal selettore della cronologia e continua da dove eri rimasto. ## Trasforma una buona risposta in una query salvata o un dashboard -Quando una risposta vale la pena conservare, chiedi all'assistente di salvarla. Redige l'SQL per una query salvata, oppure assembla un dashboard da quelle query, quindi ti mostra una scheda **Approva / Rifiuta**. Niente viene scritto finché non fai clic su Approva, così ottieni la velocità di "chiedi semplicemente" con l'ultima parola sempre tua. +Quando una risposta vale la pena di conservare, chiedi all'assistente di salvarla. Crea il SQL per una query salvata o assembla un dashboard da quelle query, poi ti mostra una carta **Approva / Rifiuta**. Niente viene scritto finché non fai clic su Approva, quindi ottieni la velocità del "chiedi semplicemente" con sempre l'ultima parola nelle tue mani. -Sulla pagina **Queries** va ancora oltre e diventa un autore SQL: descrivi la query che desideri ("mostra il tasso di errore per agente negli ultimi 7 giorni") e trasmette l'SQL direttamente nell'editor, aprendo una vista di diff così puoi **Accettare** o **Rifiutare** la modifica prima che sia finalizzata. +Nella pagina **Query** va ancora oltre e diventa un autore SQL: descrivi la query che vuoi ("mostra il tasso di errore per agente degli ultimi 7 giorni") e è trasmette SQL direttamente nell'editor, aprendo una vista diff così puoi **Accettare** o **Rifiutare** la modifica prima che arrivi. -![La pagina Observability Queries e il suo editor SQL](/agenteye/images/query-lab.png) -*La pagina Queries: questo editor è dove l'assistente trasmette una draft di query, di sola lettura, per te da accettare o rifiutare.* +![La pagina Osservabilità Query e il suo editor SQL](/agenteye/images/query-lab.png) +*La pagina Query: questo editor è dove l'assistente trasmette una query draft di sola lettura per accettare o rifiutare.* -La creazione di SQL chiedendo qui usa il permesso `queries:run`, lo stesso dietro al pulsante **Run** dell'editor. La chat ovunque altro ha bisogno di `agent:use`. +Creare SQL chiedendo qui usa il permesso `queries:run`, lo stesso dietro il pulsante **Run** dell'editor. La chat ovunque sia altrimenti necessita `agent:use`. -## Sicuro da affidare a tutto il team +## Sicuro da consegnare a tutto il team Puoi aprire l'assistente a tutti senza preoccuparti di quello che potrebbe toccare: - **Legge solo quello che puoi già vedere.** Le risposte sono limitate ai tuoi permessi di lettura, quindi non amplia mai la tua superficie dati. -- **Ogni scrittura è in attesa di te.** Le query salvate e i dashboard vengono creati solo dopo il tuo clic esplicito su Approva, e non c'è alcuna impostazione che disattivi questo controllo. -- **Non può mai eliminare nulla.** Nessun tool di eliminazione è esposto e l'assistente non possiede permessi di eliminazione. Le eliminazioni rimangono nelle tue mani, nel dashboard. -- **Rimane dentro la tua organizzazione.** L'assistente vede solo l'organizzazione che stai visualizzando al momento. -- **Le tue domande rimangono tue.** I prompt e le risposte vivono nel tuo database Observability; l'analisi dei prodotti registra solo i metadati di utilizzo, mai il testo del tuo prompt. +- **Ogni scrittura ti aspetta.** Le query salvate e i dashboard vengono creati solo dopo il tuo esplicito clic Approva e non c'è nessuna impostazione che disattivi questo controllo. +- **Non può mai eliminare nulla.** Nessuno strumento di eliminazione è esposto e l'assistente non ha permessi di eliminazione. Le eliminazioni rimangono nelle tue mani, nel dashboard. +- **Rimane dentro la tua organizzazione.** L'assistente vede solo l'organizzazione che stai visualizzando attualmente. +- **Le tue domande rimangono tue.** I prompt e le risposte vivono nel tuo database Observability; l'analytics del prodotto registra solo i metadati di utilizzo, mai il testo del tuo prompt. ## Dove trovarlo -L'assistente si trova lungo il bordo destro di ogni pagina sotto la tua organizzazione (`//...`). Fai clic sulla barra laterale, oppure premi `⌘J` / `Ctrl+J`, per espanderlo nel pannello chat completo, e trascina il suo bordo per ridimensionarlo; la tua larghezza viene ricordata tra i ricaricamenti. Hai bisogno del permesso **`agent:use`** per usarlo, altrimenti la barra laterale è disabilitata. Se non è stato ancora attivato per la tua distribuzione (ha bisogno di una connessione LLM), vedrai una barra laterale muta al posto di una chat funzionante. +L'assistente si trova sul bordo destro di ogni pagina sotto la tua organizzazione (`//...`). Clicca la barra laterale o premi `⌘J` / `Ctrl+J` per espanderlo nel pannello chat completo e trascina il bordo per ridimensionare; la tua larghezza è ricordata tra i ricaricamenti. Hai bisogno del permesso **`agent:use`** per usarlo, altrimenti la barra laterale è grigia. Se non è ancora stato attivato per la tua distribuzione (ha bisogno di una connessione LLM), vedrai una barra laterale attenuata al posto di una chat funzionante. ## Correlati diff --git a/docs/it/agenteye/audits.mdx b/docs/it/agenteye/audits.mdx index ed6a5d17..8501b3af 100644 --- a/docs/it/agenteye/audits.mdx +++ b/docs/it/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- -title: "Audit: il tuo analista di affidabilità automatico" -description: "Failproof AI Observability cerca i guasti che non hai mai scritto una regola per gestire e ti consegna un elenco ordinato per priorità e basato su prove di esattamente cosa correggere." +title: "Audit: il tuo analista automatico di affidabilità" +description: "Failproof AI Observability cerca i guasti per cui non hai mai scritto una regola e ti consegna una lista ordinata di priorità con prove concrete di cosa correggere." --- -Failproof AI Observability cerca i guasti che non hai mai scritto una regola per gestire e ti consegna un elenco ordinato per priorità e basato su prove di esattamente cosa correggere. È come avere un analista che esamina i tuoi log ogni notte, lasciando sul tuo desk la lista ristretta al mattino. +Failproof AI Observability cerca i guasti per cui non hai mai scritto una regola e ti consegna una lista ordinata di priorità con prove concrete di cosa correggere. È come avere un analista che passa al pettine i tuoi log ogni notte e poi ti lascia la lista breve sulla scrivania la mattina dopo.
- +
-*Un tour di due minuti: da un'esecuzione programmata a una correzione su cui puoi agire.* +*Un tour di due minuti: da un'esecuzione pianificata a una correzione su cui puoi agire.* -![La pagina Audit: lavori ricorrenti che analizzano le tue sessioni cercando pattern di guasto, ognuno con una pianificazione e sensibilità](/agenteye/images/audits.png) -*Ogni audit è un lavoro ricorrente che analizza le tue sessioni e redige raccomandazioni ordinate per priorità e basate su prove.* +![La pagina Audit: job ricorrenti che esaminano le tue sessioni alla ricerca di pattern di guasto, ognuno con una pianificazione e una sensibilità](/agenteye/images/audits.png) +*Ogni audit è un job ricorrente che analizza le tue sessioni e redige raccomandazioni ordinate e supportate da prove concrete.* -## Smetti di indovinare cosa correggere dopo +## Smetti di indovinare cosa correggere per primo -Gli alert catturano i problemi che già sai di dover tenere d'occhio. Gli audit catturano quelli che non conosci. Su una pianificazione che imposti tu, un audit legge tutte le tue sessioni di agent e cerca i pattern che vale la pena correggere, così puoi dedicare il tuo tempo ad agire sui risultati invece di scorrere i log sperando di individuarli da solo. +Gli alert catturano i problemi che già sai di dover controllare. Gli audit catturano quelli che non conosci. Secondo una pianificazione che tu stabilisci, un audit legge tutte le tue sessioni di agente e cerca i pattern che vale la pena correggere, così dedichi il tuo tempo ad agire sui risultati invece di scorrere i log sperando di individuarli. -Una singola esecuzione va dopo i modi di guasto che in realtà rompono gli agent in produzione: +Un singolo ciclo va a caccia dei modi di fallimento che realmente rompono gli agenti in produzione: -- **Cluster di errori**: lo stesso guasto che si ripete sotto una causa radice condivisa. -- **Deriva rispetto a un baseline**: il comportamento che silenziosamente si allontana da una finestra nota e affidabile. -- **Fallimento dell'obiettivo nei transcript**: esecuzioni che tecnicamente sono terminate ma non hanno mai svolto il lavoro. -- **Uso errato dello strumento**: lo strumento sbagliato, argomenti errati, o loop che consumano chiamate. -- **Compromessi tra qualità e costo**: dove stai pagando troppo per un output che potresti ottenere a un prezzo inferiore. -- **Gap di copertura**: comportamento che nessun eval o alert sta monitorando. +- **Cluster di errori**: lo stesso guasto che si ripete per una causa radice comune. +- **Drift rispetto a una linea di base**: comportamento che scivola lentamente fuori da una finestra nota e funzionante. +- **Fallimento dell'obiettivo nei transcript**: esecuzioni che tecnicamente si sono completate ma non hanno mai svolto il compito. +- **Uso errato degli strumenti**: lo strumento sbagliato, argomenti difettosi, o loop che bruciano chiamate. +- **Compromessi tra qualità e costo**: dove stai pagando troppo per un output che potresti ottenere più economicamente. +- **Gap di copertura**: comportamento che nessun eval o alert sta controllando. -Decidi quanto approfondire con una singola impostazione di **sensibilità** (bassa, media o alta), così un agent di staging rumoroso e uno di produzione bloccato possono essere sintonizzati ognuno sul segnale che desideri. +Tu decidi quanto approfonditamente deve cercare con un'unica impostazione di **sensibilità** (bassa, media o alta), così un agente di staging rumoroso e uno di produzione blindato possono essere sintonizzati ciascuno sul segnale che desideri. -## Ogni raccomandazione viene con le prove +## Ogni raccomandazione viene con prove -Non dovrai mai prendere un risultato sulla fiducia. Ogni raccomandazione cita le esatte sessioni da cui proviene e l'SQL che l'ha riportata alla luce, così puoi aprire le prove e confermare il problema con un clic invece di fare ingegneria inversa su un'affermazione. +Non devi mai accettare un risultato in buona fede. Ogni raccomandazione cita le sessioni esatte da cui proviene e l'SQL che l'ha fatto emergere, così puoi aprire le prove e confermare il problema con un clic invece di fare ingegneria inversa di un'affermazione. -Quando un risultato riguarda una credenziale persa, fa un passo oltre e collega gli eventi individuali che ha trovato. Fai clic su uno e atterri esattamente su quel momento nella sessione, già selezionato — non all'inizio di un lungo transcript da scorrere. Il link nomina l'evento; non copia mai il segreto rilevato nel risultato, così leggere un risultato non è un secondo posto dove la tua credenziale è scritta. Se un evento non è più presente perché la sessione ha superato la tua finestra di conservazione, la pagina lo dice chiaramente invece di lasciarti chiederti se hai cliccato sul posto sbagliato. +Quando un risultato riguarda una credenziale trapelata, va un passo oltre e collega i singoli eventi che ha individuato. Clicca su uno e atterri esattamente in quel momento della sessione, già selezionato — non in cima a un lungo transcript da scorrere. Il link nomina l'evento; non copia mai il segreto rilevato nel risultato, quindi leggere un risultato non è un secondo posto dove la tua credenziale viene registrata. Se un evento non è più lì perché la sessione ha superato la tua finestra di conservazione, la pagina lo dice chiaramente piuttosto che lasciarti chiederti se hai cliccato la cosa sbagliata. -Questo è anche quello che mantiene gli audit onesti. Il server verifica che ogni sessione citata esista effettivamente e **scarta qualsiasi raccomandazione le cui prove non si mantengono**, così l'audit indaga ma mai inventa. Quello che finisce nella tua lista è reale, riproducibile e ordinato per priorità in base a quanto conta, con i vincitori più grandi in cima. +È anche quello che mantiene gli audit onesti. Il server verifica che ogni sessione citata esista effettivamente e **scarta qualsiasi raccomandazione le cui prove non reggono**, così l'audit indaga ma non inventa mai. Quello che finisce nella tua lista è reale, riproducibile, e ordinato per importanza, con i vantaggi maggiori in cima. -## Trasforma una correzione in una barriera protettiva +## Trasforma una correzione in una guardrail -Correggere un problema è solo metà della vittoria. L'altra metà è assicurarsi che non torni silenziosamente. Ogni risultato porta un **collegamento con un solo clic che redige un alert di ricorrenza**, precompilato con un trigger di partenza sensato che puoi sintonizzare. Chiudi il risultato, attiva l'alert, e la prossima volta che quel pattern riappare ricevi una notifica invece di riscoprirlo in un audit futuro. +Correggere un problema è solo metà della vittoria. L'altra metà è assicurarsi che non possa tornare di nascosto. Ogni risultato contiene un **collegamento a un clic che propone un alert di ricorrenza**, precompilato con un trigger di partenza sensato che puoi sintonizzare. Chiudi il risultato, attiva l'alert, e la prossima volta che quel pattern riappare ricevi una notifica invece di riscoprirlo in un futuro audit. ## Dove trovarlo -Gli audit si trovano nel dashboard a **`//audits`** (barra laterale su *analyze* quindi su *audits*). La visualizzazione delle esecuzioni e dei risultati richiede **`audits:read`**; la creazione, la modifica e la triaging degli audit richiedono **`audits:write`**. Imposta l'ambito e la cadenza di un audit, quindi fai clic su **Run now** ogni volta che desideri i risultati immediatamente invece di attendere il prossimo passaggio programmato. +Gli audit si trovano nel dashboard all'indirizzo **`//audits`** (barra laterale su *analyze* quindi *audits*). La visualizzazione di esecuzioni e risultati richiede **`audits:read`**; la creazione, modifica e classificazione degli audit richiede **`audits:write`**. Imposta l'ambito e la cadenza di un audit, quindi premi **Run now** quando desideri risultati immediati invece di aspettare il prossimo ciclo pianificato. ## Correlati -- [Alerts](/it/agenteye/alerts): ricevi una notifica nel momento in cui viene superata una soglia che conosci già. -- [Evaluations](/it/agenteye/evaluations): assegna un punteggio a ogni esecuzione così le regressioni di qualità emergono da sole. -- [Error tracking](/it/agenteye/error-tracking): raggruppa e segui gli errori che i tuoi agent generano. +- [Alerts](/it/agenteye/alerts): ricevi una notifica nel momento in cui una soglia che conosci viene superata. +- [Evaluations](/it/agenteye/evaluations): valuta ogni esecuzione in modo che le regressioni di qualità emergano da sole. +- [Error tracking](/it/agenteye/error-tracking): raggruppa e segui gli errori che i tuoi agenti generano. - [Incidents](/it/agenteye/incidents): traccia un problema che un audit scopre fino alla sua correzione. \ No newline at end of file diff --git a/docs/it/agenteye/cli-and-agents.mdx b/docs/it/agenteye/cli-and-agents.mdx index 61107bc5..ed35901a 100644 --- a/docs/it/agenteye/cli-and-agents.mdx +++ b/docs/it/agenteye/cli-and-agents.mdx @@ -1,10 +1,10 @@ --- title: "CLI" -description: "L'intera implementazione di Failproof AI Observability, a un solo comando di distanza." +description: "L'intera implementazione di Failproof AI Observability, a un comando di distanza." --- -L'intera implementazione di Failproof AI Observability, a un solo comando di distanza. Controlla la produzione, genera una chiave API o riconosci un incidente senza lasciare il terminale, quindi inserisci tutto in uno script per CI, o lascia che un agente di codifica lo faccia per te in inglese semplice. +L'intera implementazione di Failproof AI Observability, a un comando di distanza. Controlla la produzione, genera una chiave API, o riconosci un incidente senza lasciare il terminale, quindi script tutto in CI, oppure lascia che un agente di codifica lo faccia per te in inglese naturale. ```bash pipx install agenteye @@ -14,16 +14,16 @@ agenteye --json sessions --since 24h # every agent run from the last day *La CLI `agenteye` comunica con il tuo dashboard. È uno strumento diverso dal collector, che invia eventi al server.* -## L'intera implementazione, a un solo comando di distanza +## L'intera implementazione, a un comando di distanza -Smetti di saltare tra le schede per rispondere a una domanda veloce. La CLI `agenteye` legge i tuoi dati e amministra la tua organizzazione da un singolo binario, quindi un controllo che prima significava cliccare nel dashboard diventa una singola riga che puoi rieseguire, creare un alias, o incollare in un runbook. Hai a disposizione quattro superfici: +Smetti di saltare da una scheda all'altra per rispondere a una domanda veloce. La CLI `agenteye` legge i tuoi dati e amministra la tua organizzazione da un singolo binario, così un controllo che richiedeva di cliccare attraverso il dashboard diventa una sola riga che puoi rieseguire, creare un alias, o incollare in un runbook. Hai quattro superfici: -- **Leggi i tuoi dati:** `sessions`, `events`, `evals` e `errors`, filtrati per tempo, agente e ambiente. -- **Gestisci la tua organizzazione:** `keys`, `users`, `settings`, `alerts` e `incidents`. -- **Esegui analitiche:** SQL salvato più un runner ad hoc `query` sui tuoi dati di eventi. -- **Chiedi all'assistente:** `agent ask` raggiunge lo stesso analista di sola lettura con cui chatti nel dashboard. +- **Leggi i tuoi dati:** `sessions`, `events`, `evals`, e `errors`, filtrati per tempo, agente e ambiente. +- **Gestisci la tua organizzazione:** `keys`, `users`, `settings`, `alerts`, e `incidents`. +- **Esegui analitiche:** SQL salvato più un runner `query` ad hoc sui tuoi dati di eventi. +- **Chiedi all'assistente:** `agent ask` raggiunge lo stesso analista in sola lettura con cui chat nel dashboard. -Installalo una volta con `pipx`, accedi con un codice a 6 cifre inviato via email, e sei pronto. La sessione dura circa un giorno; riesegui `agenteye login` quando scade. Usalo per controllare la produzione, provisioning di una chiave, o triage di un incidente attivo, il tutto senza aprire un browser: +Installalo una volta con `pipx`, accedi con un codice a 6 cifre inviato per email, e sei pronto. La sessione dura circa un giorno; riesegui `agenteye login` quando scade. Usalo per verificare la produzione, fornire una chiave, o fare il triage di un incidente attivo, tutto senza aprire un browser: ```bash agenteye errors --since 24h --aggregate # what is breaking, grouped by error type @@ -31,25 +31,25 @@ agenteye incidents list --state firing # what is on fire right now agenteye keys create ci --add events:add # a key that can only push events, secret shown once ``` -Un'abitudine da conoscere: le opzioni globali come `--json` vanno prima del comando. `agenteye --json sessions` è corretto; `agenteye sessions --json` non lo è. +Un'abitudine da conoscere: le opzioni globali come `--json` vanno prima del comando. `agenteye --json sessions` è corretto; `agenteye sessions --json` no. -## Inseriscilo in uno script, integralo in CI +## Script, integralo in CI -Ogni comando accetta `--json`, e questo cambia tutto. JSON pulito va a stdout mentre lo stato umano e gli avvisi vanno a stderr, quindi un capture `--json` si collega direttamente a `jq` senza alcuna riga estranea da togliere. È questo che rende la CLI altrettanto valida per te al prompt e per un agente di codifica che analizza l'output: +Ogni comando accetta `--json`, e questo cambia tutto. JSON pulito va su stdout mentre lo stato umano e gli avvisi vanno su stderr, così una cattura `--json` si piega direttamente in `jq` senza una riga estranea da eliminare. Questo è quello che rende la CLI ugualmente buona per te al prompt e per un agente di codifica che analizza l'output: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -È costruito per essere eseguito senza supervisione. I prompt di conferma vengono automaticamente saltati quando nessun terminale è collegato, quindi nulla si blocca in una pipeline, e ogni comando restituisce un codice di uscita significativo: `0` successo, `4` non connesso, `5` autorizzazione mancante (il messaggio la nomina, per esempio `alerts:write`), `3` dashboard non raggiungibile. Uno script può diramarsi su un `4` per reauthenticarsi o su un `5` per dirti esattamente cosa chiedere a un amministratore, invece di fallire senza sapere il motivo. +È costruito per funzionare senza presidiamento. I prompt di conferma si saltano automaticamente quando nessun terminale è collegato, quindi nulla si blocca in una pipeline, e ogni comando ritorna un codice di uscita significativo: `0` successo, `4` non connesso, `5` permesso mancante (il messaggio lo nomina, ad esempio `alerts:write`), `3` dashboard irraggiungibile. Uno script può diramarsi su un `4` per autenticarsi di nuovo o su un `5` per dirti esattamente cosa chiedere a un amministratore, invece di fallire al buio. -## Lascia che un agente di codifica lo guidi in inglese semplice +## Lascia che un agente di codifica lo guidi in inglese naturale -Ancora meglio, non dovresti nemmeno dover ricordare nessuno di questi flag. La **CLI skill** è una piccola cartella di Agent Skill chiamata `agenteye-cli` che insegna a un agente di codifica come Claude Code o Codex a guidare la CLI da richieste in inglese semplice. Chiedi "c'è qualcosa di rotto oggi?" e l'agente sceglie il comando, lo esegue come te, e risponde in prosa. +Ancora meglio, non dovresti nemmeno dover ricordare nessuno di questi flag. La **CLI skill** è una piccola cartella Agent Skill denominata `agenteye-cli` che insegna a un agente di codifica come Claude Code o Codex a guidare la CLI da richieste in inglese naturale. Chiedi se qualcosa è rotto oggi? e l'agente sceglie il comando, lo esegue per te, e risponde in prosa. -Per Claude Code, rilascia la cartella `agenteye-cli` in `~/.claude/skills/` e viene scoperta automaticamente. Failproof AI Observability fornisce la cartella; non c'è nulla di extra da installare, perché guida solo la CLI che hai già installato. Accedi tu stesso prima: lo skill non può completare per te l'accesso tramite codice inviato via email. +Per Claude Code, basta mettere la cartella `agenteye-cli` in `~/.claude/skills/` e viene scoperta automaticamente. Failproof AI Observability fornisce la cartella; non c'è nulla di extra da installare, perché guida solo la CLI che hai già installato. Accedi tu stesso prima: la skill non può completare per te il login con il codice inviato per email. -Poiché l'agente esegue la CLI come te, può fare tutto ciò che la tua login consente, sia letture che scritture: creare chiavi, modificare le impostazioni, risolvere incidenti. Il prompt di conferma "sei sicuro?" della CLI non si attiva per un agente, quindi lo skill è scritto per indicare il comando esatto e attendere il tuo OK prima di qualsiasi modifica. Tu sei il passaggio di conferma. +Poiché l'agente esegue la CLI come te, può fare tutto quello che il tuo login permette, legge e scritte: creare chiavi, cambiare impostazioni, risolvere incidenti. Il prompt "sei sicuro?" della CLI non si attiva per un agente, quindi la skill è scritta per indicare il comando esatto e aspettare il tuo OK prima di qualsiasi cambiamento. Tu sei il passo di conferma. ```text you Why did session run-001 fail? @@ -58,7 +58,7 @@ agent Running: agenteye --json events --session-id run-001 --all The checkout-agent hit a TimeoutError on its third tool call. ``` -Le letture rimangono istantanee, e ogni scrittura ti attende: +Le letture rimangono istantanee, e ogni scrittura si ferma per te: ```text you Give CI a key that can only push events. @@ -74,7 +74,7 @@ agent Done. Key "ci" created with events:add only. The secret is shown once, so ## Correlati -- [Riferimento CLI](/it/agenteye/cli): ogni comando, flag e forma JSON. -- [Ricette CLI per agenti](/it/agenteye/cli-recipes): pattern `jq` copia-incolla e gestione dei codici di uscita. -- [Skill agente CLI](/it/agenteye/cli-skill): installa ed esegui lo skill `agenteye-cli`. -- [Assistente AI](/it/agenteye/assistant): l'analista nel dashboard con cui comunica `agent ask`. \ No newline at end of file +- [Riferimento CLI](/it/agenteye/cli): ogni comando, flag, e forma JSON. +- [Ricette CLI per agenti](/it/agenteye/cli-recipes): pattern `jq` copia-incolla e gestione del codice di uscita. +- [CLI agent skill](/it/agenteye/cli-skill): installa ed esegui la skill `agenteye-cli`. +- [Assistente AI](/it/agenteye/assistant): l'analista nel dashboard che `agent ask` comunica. \ No newline at end of file diff --git a/docs/it/agenteye/cli-recipes.mdx b/docs/it/agenteye/cli-recipes.mdx index 028ee135..b49e9fbd 100644 --- a/docs/it/agenteye/cli-recipes.mdx +++ b/docs/it/agenteye/cli-recipes.mdx @@ -1,30 +1,30 @@ --- -title: "Ricette CLI per gli agenti" -description: "Copia e incolla i pattern di query e le ricette jq che trasformano i dati di sessione, evento e valutazione in qualcosa che uno script o un agente di codifica può automatizzare." +title: "Ricette CLI per agenti" +description: "Copia-incolla pattern di query e ricette jq che trasformano i dati di sessione, evento e valutazione in qualcosa che uno script o un agente di codifica può automatizzare." --- -Estrai i dati di sessione, evento e valutazione (e attiva rivalutazioni) direttamente da uno script o da un agente di codifica, con JSON pulito su stdout che si collega direttamente a `jq`. Queste ricette trasformano i dati di Failproof AI Observability in qualcosa che un utente di terminale o un agente di codifica IA (Claude Code, Cursor) può interrogare e automatizzare, senza navigare nella dashboard. +Estrai i dati di sessione, evento e valutazione (e attiva ri-valutazioni) direttamente da uno script o agente di codifica, con JSON pulito su stdout che si piped direttamente in `jq`. Queste ricette trasformano i dati di Failproof AI Observability in qualcosa che un utente di terminale o un agente di codifica AI (Claude Code, Cursor) può interrogare e automatizzare, senza fare clic attraverso la dashboard. -I pattern sottostanti sono pronti per il copia-incolla per la CLI di Failproof AI Observability (`agenteye`). Per l'installazione, l'autenticazione e l'elenco completo delle opzioni, vedi [CLI](/it/agenteye/cli); esegui `agenteye -h` o `agenteye -h` per l'aiuto integrato. +I pattern sottostanti sono pronti per il copia-incolla per la CLI di Failproof AI Observability (`agenteye`). Per l'installazione, l'autenticazione e l'elenco completo delle opzioni, vedi [CLI](/it/agenteye/cli); esegui `agenteye -h` o `agenteye -h` per la guida integrata. ## Regole d'oro 1. **Le opzioni globali vanno *prima* del comando.** `agenteye --json sessions` è corretto; `agenteye sessions --json` no. Le opzioni globali sono `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Passa `--json` ogni volta che analizzi l'output.** I dati vanno su **stdout** come JSON; lo stato umano e gli errori vanno su **stderr**, così stdout rimane pulito per il collegamento a `jq`. -3. **Rama sul codice di uscita**, non sul testo di stderr: `0` ok · `1` errore inaspettato · `2` argomenti non validi · `3` impossibile raggiungere la dashboard · `4` non autenticato o scaduto · `5` permesso mancante · `6` risorsa non trovata. -4. **Scopri con `-h`.** Ogni comando documenta i suoi filtri, i formati di valore e la forma JSON. +2. **Passa `--json` ogni volta che analizzi l'output.** I dati vanno su **stdout** come JSON; lo stato umano e gli errori vanno su **stderr**, quindi stdout rimane pulito per il piping in `jq`. +3. **Rami in base al codice di uscita**, non al testo stderr: `0` ok · `1` errore inaspettato · `2` argomenti non validi · `3` impossibile raggiungere la dashboard · `4` non connesso o scaduto · `5` permesso mancante · `6` risorsa non trovata. +4. **Scopri con `-h`.** Ogni comando documenta i suoi filtri, formati di valore e forma JSON. -## Configurazione una tantum +## Setup monouso ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # così non ripeti --base-url -agenteye login --email you@example.com # incolla il codice ricevuto per email; valido ~24h +agenteye login --email you@example.com # incolla il codice via email; valido ~24h ``` -## Conferma l'autenticazione prima di fare lavoro +## Conferma auth prima di fare lavoro -`whoami` non dagli mai errori su una sessione mancante o scaduta; riporta invece `logged_in:false`, così un agente può controllare lo stato dell'autenticazione in sicurezza. (Può comunque uscire con codice non zero se nessun URL di base è impostato o la dashboard non è raggiungibile.) +`whoami` non genera mai errori su una sessione mancante o scaduta; riporta invece `logged_in:false`, quindi un agente può sondare lo stato dell'auth in sicurezza. (Può comunque uscire con non-zero se non è impostato un URL di base o la dashboard non è raggiungibile.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,10 +32,10 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Trova sessioni con errori o punteggi bassi +## Trova sessioni in errore o con punteggio basso ```bash -# sessioni nelle ultime 24h il cui stato di valutazione è errore +# sessioni nelle ultime 24h la cui valutazione ha dato errore agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' # valutazioni con punteggio <= 0.5 su utilità, per un agente @@ -43,35 +43,35 @@ agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Il filtro del punteggio vive su **`evals`**, non su `sessions`. `--score KEY:MIN..MAX` è ripetibile e combinato con AND; entrambi i limiti sono opzionali (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puoi passare fino a 20 filtri di punteggio per richiesta; di più restituisce HTTP 400. `sessions` condivide i filtri `--env`, `--status`, `--agent-id`, `--session-id` e intervallo di tempo con `evals`, ma non ha `--score`. +Il filtraggio dei punteggi si trova su **`evals`**, non su `sessions`. `--score KEY:MIN..MAX` è ripetibile e combinato con AND; ogni vincolo è opzionale (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puoi passare fino a 20 filtri di punteggio per richiesta; più di questo restituisce HTTP 400. `sessions` condivide i filtri `--env`, `--status`, `--agent-id`, `--session-id` e intervallo temporale con `evals`, ma non ha `--score`. ## Leggi una sessione da capo a fondo -Non c'è un singolo comando `session show`. Combina la traccia degli eventi con la valutazione della sessione: +Non esiste un singolo comando `session show`. Combina il trail degli eventi con la valutazione della sessione: ```bash -# l'ultima valutazione della sessione (stato + punteggi) +# la valutazione più recente della sessione (stato + punteggi) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# ogni evento nell'esecuzione (aumenta --limit per un controllo completo) +# ogni evento nell'esecuzione (aumenta --limit per una scansione completa) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# solo le chiamate di strumento in una sessione (--full è richiesto per ottenere il payload grezzo) +# solo le chiamate agli strumenti in una sessione (--full è richiesto per ottenere il payload grezzo) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **Nota:** Per impostazione predefinita, `events` legge un feed veloce senza payload. Ogni evento porta un `summary` di una riga calcolato dal server più flag come `is_error` e conteggi di token, ma `payload` ritorna come `{}`. Per estrarre il payload grezzo, aggiungi `--full` (o `--fields payload`). Il feed completo è più lento su larga scala, quindi mantienilo limitato: abbina `--full` a un singolo `--session-id`. +> **Nota:** Per impostazione predefinita, `events` legge un feed veloce senza payload. Ogni evento porta un `summary` di una riga calcolato dal server più flag come `is_error` e conteggi di token, ma `payload` torna come `{}`. Per estrarre il payload grezzo, aggiungi `--full` (o `--fields payload`). Il feed completo è più lento su scala, quindi mantienilo limitato: accoppia `--full` con un singolo `--session-id`. ## Estrai tutto (paginazione) -I risultati sono più recenti in primo piano e paginati con cursore. +I risultati sono più recenti prima e paginati con cursore. ```bash -# un colpo: estrai fino a 500 righe in pagine di 200 righe +# in un colpo: estrai fino a 500 righe in pagine di 200 righe agenteye --json events --session-id run-001 --limit 500 --all > events.json -# paginazione manuale: reinserisci next_cursor +# paginazione manuale: reinserisce il next_cursor page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -79,7 +79,7 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## Riduci l'output con --fields -Limita i tasti (sia nella tabella che in `--json`) per ridurre quello che un agente deve leggere. +Limita le chiavi (sia nella tabella che in `--json`) per ridurre cosa un agente deve leggere. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' @@ -88,12 +88,12 @@ agenteye --json events --session-id run-001 --fields ts,event_type --all I nomi di campo sconosciuti vengono rifiutati (uscita `2`) con l'elenco valido, un modo economico per scoprire i nomi dei campi. -## Scopri i valori di filtro validi +## Scopri valori di filtro validi ```bash agenteye --json list envs | jq -r '.values[]' # valori per --env -agenteye --json list tools | jq -r '.values[]' # nomi degli strumenti; anche agenti, modelli, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # KEY valida per --score KEY:MIN..MAX +agenteye --json list tools | jq -r '.values[]' # nomi di strumenti; anche agenti, modelli, event_types, … +agenteye --json list score_filters | jq -r '.values[]' # KEY valido per --score KEY:MIN..MAX ``` ## Scegli la tua org (multi-tenant) @@ -103,12 +103,12 @@ Se appartieni a più di un'org, scegli il tenant attivo al login (viene salvato) ```bash agenteye login --org acme --email you@corp.com # imposta il tenant nello stesso passaggio del login agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # sostituisci per un comando +agenteye --org globex --json sessions --since 24h # sovrascrivi per un comando ``` -Un login multi-org senza `--org` esce con codice non zero e stampa le org tra cui scegliere. +Un login multi-org senza `--org` esce con non-zero e stampa le org tra cui scegliere. -## Fornisci una chiave API per SDK/collector +## Provvedi una chiave API per l'SDK/collector ```bash # il segreto viene stampato UNA VOLTA, con --json è il campo .key @@ -116,14 +116,14 @@ key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # ruota; agenteye keys disable ci-bot --yes per revocare ``` -## Esegui una query salvata o ad hoc +## Esegui una query salvata o ad-hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' agenteye --json query run errs --arg prod | jq '.rows' # una query salvata + un $1 posizionale ``` -## Triage di un incidente in modo non interattivo +## Triage di un incidente non interattivo ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **Nota:** Le mutazioni saltano automaticamente il prompt di conferma sotto `--json` o quando stdin non è una TTY, così gli agenti non si bloccano mai; passa `--yes`/`-y` per saltarlo esplicitamente altrove. +> **Nota:** Le mutazioni saltano automaticamente il loro prompt di conferma sotto `--json` o quando stdin non è un TTY, quindi gli agenti non si bloccano mai; passa `--yes`/`-y` per saltarlo esplicitamente altrove. ## Gestione del codice di uscita in uno script @@ -149,31 +149,31 @@ esac ## Forme di output JSON -| Comando | stdout JSON (con `--json`) | +| Comando | JSON stdout (con `--json`) | |---|---| -| `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` oppure `{"logged_in": false}` | +| `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` o `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | | `events` | `{"events": [...], "next_cursor": }` | | `evals` | `{"evaluations": [...], "next_cursor": }` | | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` mostrata una volta) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` mostrato una volta) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (qualsiasi) | l'oggetto risorsa, oppure `{"deleted": true, "id"}` per i delete | -| failure (qualsiasi, con `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` su stdout | +| create/update/delete (qualsiasi) | l'oggetto risorsa, o `{"deleted": true, "id"}` per le eliminazioni | +| errore (qualsiasi, con `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` su stdout | -- Ogni elemento **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Nota che `payload` è `{}` a meno che tu non richieda il feed completo con `--full` (o `--fields payload`). +- Ogni elemento **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Nota che `payload` è `{}` a meno che non richiedi il feed completo con `--full` (o `--fields payload`). - Ogni elemento **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Ogni elemento **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -Ogni comando `--fields` accetta esattamente i nomi di campo del suo elemento. L'insieme differisce tra `sessions` e `evals`, quindi un nome valido per uno può essere rifiutato dall'altro. +`--fields` di ogni comando accetta esattamente i nomi dei campi del suo elemento. L'insieme differisce tra `sessions` e `evals`, quindi un nome valido per uno può essere rifiutato dall'altro. ## Prossimi passi - [CLI](/it/agenteye/cli): installazione, autenticazione e il riferimento completo delle opzioni per ogni comando. - [CLI agent skill](/it/agenteye/cli-skill): pacchetto queste ricette come una skill che il tuo agente di codifica può caricare. -- [API keys](/it/agenteye/api-keys): crea e delimita le chiavi con cui la CLI, SDK e collector si autenticano. -- [Python SDK](/it/agenteye/python-sdk): invia eventi in Failproof AI Observability così c'è dati per queste ricette da interrogare. \ No newline at end of file +- [Chiavi API](/it/agenteye/api-keys): crea e delimita le chiavi con cui la CLI, l'SDK e il collector si autenticano. +- [Python SDK](/it/agenteye/python-sdk): invia eventi in Failproof AI Observability in modo che ci siano dati per queste ricette da interrogare. \ No newline at end of file diff --git a/docs/it/agenteye/cli-skill.mdx b/docs/it/agenteye/cli-skill.mdx index e5de4d94..d38a52af 100644 --- a/docs/it/agenteye/cli-skill.mdx +++ b/docs/it/agenteye/cli-skill.mdx @@ -1,70 +1,70 @@ --- -title: "Competenza CLI dell'Agente di Osservabilità Failproof AI" -description: "Chiedi al tuo agente di codifica \"c'è qualcosa di rotto oggi?\" e lascia che risponda dai tuoi dati di Osservabilità Failproof AI in tempo reale, senza comandi da memorizzare." +title: "Failproof AI Observability CLI Agent Skill" +description: "Chiedi al tuo agente di codifica \"c'è qualcosa rotto oggi?\" e lascia che risponda dai tuoi dati live di Failproof AI Observability, senza comandi da memorizzare." --- -Chiedi al tuo agente di codifica *"c'è qualcosa di rotto oggi?"* e lascia che risponda dai tuoi dati di Osservabilità Failproof AI in tempo reale, senza comandi da memorizzare. La **competenza CLI di Osservabilità Failproof AI** (`agenteye-cli`) è un'*Agent Skill*: una piccola cartella di istruzioni che un agente di codifica come Claude Code o Codex carica su richiesta. Insegna all'agente a operare il tuo deployment di Osservabilità tramite la [`agenteye` CLI](/it/agenteye/cli) da richieste in linguaggio naturale come *"dai a CI una chiave che può solo inviare eventi"* o *"conferma l'incident in corso e assegnalo a me."* +Chiedi al tuo agente di codifica *"c'è qualcosa rotto oggi?"* e lascia che risponda dai tuoi dati live di Failproof AI Observability, senza comandi da memorizzare. La **Failproof AI Observability CLI skill** (`agenteye-cli`) è un *Agent Skill*: una piccola cartella di istruzioni che un agente di codifica come Claude Code o Codex carica su richiesta. Insegna all'agente a operare il tuo deployment di Observability attraverso il [`agenteye` CLI](/it/agenteye/cli) da richieste in inglese semplice come *"dai a CI una chiave che può solo spingere eventi"* o *"conferma l'incidente in corso e assegnalo a me."* -**Non** è un servizio o un binario separato; non c'è nulla da distribuire. Funziona sulla CLI che hai già installato: l'agente esegue `agenteye --json …`, analizza il JSON pulito, e ti risponde in prosa. Tutto ciò che può fare, potresti farlo tu digitando gli stessi comandi. +**Non** è un servizio o un binario separato; non c'è nulla da distribuire. Funziona sopra il CLI che hai già installato: l'agente chiama `agenteye --json …`, analizza il JSON pulito e ti risponde in prosa. Tutto ciò che può fare, potresti farlo tu stesso digitando gli stessi comandi. --- -## Come si relaziona con le altre interfacce di Osservabilità Failproof AI +## Come si relaziona alle altre interfacce di Failproof AI Observability -Osservabilità Failproof AI ti offre quattro modi per raggiungere gli stessi dati e controlli. Si completano a vicenda: +Failproof AI Observability ti dà quattro modi per raggiungere gli stessi dati e controlli. Si completano a vicenda: -| Interfaccia | Che cos'è | Dove viene eseguita | Usala quando | +| Interfaccia | Che cos'è | Dove gira | Usala quando | |---|---|---|---| -| **[CLI](/it/agenteye/cli)** | Il riferimento comando/flag per `agenteye` | Il tuo terminale | Vuoi eseguire o scrivere uno script per un comando specifico | -| **[Ricette CLI](/it/agenteye/cli-recipes)** | Pattern `jq`/pipeline da copiare e incollare | Il tuo terminale / script | Stai integrando la CLI nell'automazione | -| **Competenza CLI** (questo documento) | Una porta in linguaggio naturale sulla CLI | Il tuo agente di codifica, sulla tua workstation | Vuoi *semplicemente chiedere* e lasciare che l'agente scelga il comando | -| **[Competenza Evaluator](/it/agenteye/evaluator-skill)** | Una competenza gemella che progetta e costruisce il tuo servizio di scoring | Il tuo agente di codifica, sulla tua workstation | Vuoi *produrre* punteggi di valutazione piuttosto che leggerli | -| **[Competenza Python SDK](/it/agenteye/python-sdk-skill)** | Una competenza gemella che strumenta il tuo agente in modo che emetta telemetria | Il tuo agente di codifica, sulla tua workstation | Vuoi che il tuo agente *produca* gli eventi che questa competenza legge | -| **[Assistente AI nella dashboard](/it/agenteye/assistant)** | Una chat incorporata nella dashboard | Lato server (nella dashboard) | Vuoi domande e risposte nella dashboard sui tuoi dati | +| **[CLI](/it/agenteye/cli)** | Il riferimento comando/flag per `agenteye` | Il tuo terminale | Vuoi eseguire o scriptare un comando specifico | +| **[CLI recipes](/it/agenteye/cli-recipes)** | Pattern copia-incolla di `jq`/pipeline | Il tuo terminale / script | Stai integrando il CLI nell'automazione | +| **CLI skill** (questo doc) | Una porta naturale in linguaggio plain sul CLI | Il tuo agente di codifica, sulla tua workstation | Vuoi semplicemente chiedere e lasciare che l'agente scelga il comando | +| **[Evaluator skill](/it/agenteye/evaluator-skill)** | Una skill gemella che progetta e costruisce il tuo servizio di scoring | Il tuo agente di codifica, sulla tua workstation | Vuoi produrre punteggi eval invece di leggerli | +| **[Python SDK skill](/it/agenteye/python-sdk-skill)** | Una skill gemella che strumenta il tuo agente in modo che emetta telemetria | Il tuo agente di codifica, sulla tua workstation | Vuoi che il tuo agente produca gli eventi che questa skill legge | +| **[In-dashboard AI assistant](/it/agenteye/assistant)** | Una chat incorporata nel dashboard | Lato server (nel dashboard) | Vuoi domande e risposte nel dashboard sui tuoi dati | -La competenza stessa non ha privilegi propri; converte semplicemente le tue parole in chiamate CLI che vengono eseguite come te: +La skill stessa non ha privilegi propri; trasforma semplicemente le tue parole in chiamate CLI che girano come te: ```mermaid flowchart TD - YOU["tu: 'conferma l'incident in corso'"] --> AGENT["agente di codifica (Claude Code / Codex)
carica la competenza agenteye-cli"] + YOU["tu: 'conferma l'incidente in corso'"] --> AGENT["agente di codifica (Claude Code / Codex)
carica la skill agenteye-cli"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|la tua sessione CLI autenticata| API["API dashboard Osservabilità"] + CLI -->|la tua sessione CLI autenticata| API["API dashboard Observability"] ``` -### vs. assistente AI nella dashboard: una distinzione importante +### vs. l'assistente AI nel dashboard: una distinzione importante -Questi sono due strumenti diversi con raggi di esplosione molto diversi: +Questi sono due strumenti diversi con raggi di impatto molto diversi: -- L'**assistente AI nella dashboard** ([Assistente AI](/it/agenteye/assistant)) è una chat incorporata nella dashboard, supportata dal servizio agente. È **di sola lettura più authoring controllato dall'approvazione**: può bozze salvate query e dashboard, ma ogni scrittura si ferma per la tua approvazione esplicita cliccabile, e non cancella mai. È controllato dall'autorizzazione `agent:use` e vede solo i dati dell'organizzazione che stai visualizzando. -- La **competenza CLI** viene eseguita sulla *tua* workstation dentro *il tuo* agente di codifica e guida la CLI `agenteye` come **tu**. Può eseguire la **superficie completa, incluse le mutazioni** (create/ruota/disabilita chiavi API, cambia impostazioni org, risolvi incident, elimina query salvate), limitato solo dalle autorizzazioni del tuo accesso CLI. Trattala esattamente come faresti con l'esecuzione manuale di quei comandi. +- L'**assistente AI nel dashboard** ([AI assistant](/it/agenteye/assistant)) è una chat incorporata nel dashboard, supportata dal servizio agente. È **sola lettura più authoring con approvazione**: può abbozzare query salvate e dashboard, ma ogni scrittura si pausa per la tua approvazione esplicita, e non elimina mai. È protetto dal permesso `agent:use` e vede solo i dati per l'org che stai visualizzando. +- La **CLI skill** gira sulla *tua* workstation dentro il *tuo* agente di codifica e guida il `agenteye` CLI come **te**. Può eseguire la **superficie completa del CLI, incluse le mutazioni** (create/rotate/disable chiavi API, cambiare impostazioni org, risolvere incidenti, eliminare query salvate), limitato solo dai permessi del tuo login CLI. Trattalo esattamente come tratteresti l'esecuzione di quei comandi a mano. --- ## Prerequisiti -1. La **CLI `agenteye` installata** e su `PATH` (vedi il riferimento [CLI](/it/agenteye/cli): `pipx install agenteye`). -2. Il **tuo URL della dashboard impostato** (`AGENTEYE_DASHBOARD_URL`, o l'agente passa `--base-url`). -3. Una **sessione autenticata**: esegui prima `agenteye login` tu stesso. La competenza **non può** completare l'accesso con codice monouso inviato per email; ti dirà di eseguire `agenteye login` se la sessione manca o è scaduta (codice di uscita CLI `4`). +1. Il **`agenteye` CLI installato** e su `PATH` (vedi il riferimento [CLI](/it/agenteye/cli): `pipx install agenteye`). +2. L'**URL del tuo dashboard** impostato (`AGENTEYE_DASHBOARD_URL`, o l'agente passa `--base-url`). +3. Una **sessione connessa**: esegui `agenteye login` tu stesso per primo. La skill **non può** completare il login con codice monouso inviato per email; ti dirà di eseguire `agenteye login` se la sessione manca o è scaduta (codice di uscita CLI `4`). --- -## Dove trovarla +## Dove ottenerla -La competenza è pubblicata nella raccolta di competenze pubbliche di Failproof AI: +La skill è pubblicata nella collezione di skills pubblica di Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -Niente è controllato — il repository è pubblico e la competenza non ha bisogno di credenziali proprie, perché guida solo la CLI `agenteye` **pubblica** contro *la tua* dashboard, usando la sessione in cui *tu* hai effettuato l'accesso. Non devi chiedere a nessuno. +Nulla è protetto — il repository è pubblico e la skill non ha bisogno di credenziali proprie, perché guida solo il `agenteye` CLI **pubblico** contro il *tuo* dashboard, usando la sessione *tu* con cui hai effettuato l'accesso. Non devi chiedere a nessuno. -Nota che viene spedita come sua propria cartella e **non** si trova all'interno del pacchetto `pipx install agenteye`, quindi non cercarla lì. +Nota che viene fornita come propria cartella e **non** è dentro il pacchetto `pipx install agenteye`, quindi non cercarla lì. -## Installazione della competenza +## Installare la skill -Il percorso più veloce è la CLI [`skills`](https://skills.sh), che recupera la cartella e la mette dove il tuo agente guarda: +Il percorso più veloce è il CLI [`skills`](https://skills.sh), che recupera la cartella e la posiziona dove il tuo agente guarda: ```bash -# Claude Code, questo progetto solo +# Claude Code, solo questo progetto npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code # ogni progetto (installa in ~/.claude/skills/) @@ -74,86 +74,86 @@ npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -Quindi gestiscila come qualsiasi altra competenza: +Quindi gestiscila come qualsiasi altra skill: ```bash npx skills list -a claude-code # cosa è installato -npx skills update agenteye-cli # tira l'ultima versione +npx skills update agenteye-cli # scarica la versione più recente npx skills remove agenteye-cli # rimuovila ``` -Preferisci installare a mano? Un'Agent Skill è solo una cartella contenente un `SKILL.md` (più riferimenti opzionali), quindi copiarla funziona: +Preferisci installarla a mano? Un Agent Skill è solo una cartella contenente un `SKILL.md` (più riferimenti opzionali), quindi copiarla funziona: -- **Claude Code**: metti la cartella `agenteye-cli/` in `~/.claude/skills/` (ogni progetto) o `/.claude/skills/` (solo quel repository). Claude Code la scopre automaticamente — verifica con la lista `/skills`, o semplicemente fai una domanda che corrisponde alla sua descrizione. -- **Codex (OpenAI)**: Codex legge lo stesso `SKILL.md`. Il `agents/openai.yaml` in bundle imposta `allow_implicit_invocation: true`, quindi Codex seleziona automaticamente la competenza quando un'attività corrisponde; altrimenti invocala esplicitamente come `$agenteye-cli`. +- **Claude Code**: metti la cartella `agenteye-cli/` in `~/.claude/skills/` (ogni progetto) o `/.claude/skills/` (solo quel repo). Claude Code la scopre automaticamente — verifica con la lista `/skills`, o semplicemente fai una domanda che corrisponda alla sua descrizione. +- **Codex (OpenAI)**: Codex legge lo stesso `SKILL.md`. Il `agents/openai.yaml` fornito imposta `allow_implicit_invocation: true`, quindi Codex seleziona automaticamente la skill quando un compito corrisponde; altrimenti invocala esplicitamente come `$agenteye-cli`. --- -## Sicurezza: le mutazioni NON chiedono conferma quando un agente esegue la CLI +## Sicurezza: le mutazioni NON richiedono conferma quando un agente esegue il CLI -> **Avvertenza:** Leggi questo prima di lasciare che un agente faccia cambiamenti. +> **Avviso:** Leggi questo prima di lasciare che un agente faccia cambiamenti. -La CLI `agenteye` normalmente chiede *"sei sicuro?"* prima di un'azione distruttiva. **Salta automaticamente quella conferma ogni volta che non è collegata a un terminale (che è esattamente come un agente di codifica la esegue), e `--json` la salta anche.** Quindi il prompt di sicurezza **non** attiverà per l'agente. +Il `agenteye` CLI normalmente chiede *"sei sicuro?"* prima di un'azione distruttiva. Lo **salta automaticamente ogni volta che non è collegato a un terminale (che è esattamente come un agente di codifica lo esegue), e `--json` lo salta anche.** Quindi il prompt di sicurezza **non** si attiverà per l'agente. -La competenza è scritta per compensare: le è stato insegnato di dichiarare il comando esatto che eseguirà e ottenere il tuo **OK esplicito prima di qualsiasi cambio di stato**. Mantieni quella disciplina. Quando guidi Osservabilità Failproof AI attraverso un agente, *tu* sei il passo di conferma. I comandi che cambiano lo stato da osservare: +La skill è scritta per compensare: è istruita a enunciare il comando esatto che eseguirà e ottenere il tuo **OK esplicito prima di qualsiasi cambiamento di stato**. Mantieni questa disciplina. Quando guidi Failproof AI Observability attraverso un agente, *tu* sei il passo di conferma. I comandi che cambiano stato da tenere d'occhio: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` - `settings set` - `alerts create` / `update` / `delete` / `test` -- i sottocomandi di scrittura `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` +- i sottocomandi di scrittura di `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` - `query create` / `update` / `delete` - `agent rename` / `delete` - `orgs switch` -Tutto sotto **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) è di sola lettura e non cambia nulla. +Tutto sotto **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) è sola lettura e non cambia nulla. -Poiché l'agente agisce come **tu**, può fare solo ciò che il tuo accesso è autorizzato a fare; le autorizzazioni vengono risolte **per organizzazione** (vedi [Chiavi API](/it/agenteye/api-keys)). Un comando per il quale non hai autorizzazione restituisce il codice di uscita `5` con l'autorizzazione esatta denominata, quindi l'agente può dirti precisamente cosa chiedere a un amministratore invece di fallire oscuramente. +Poiché l'agente agisce come **te**, può fare solo ciò che il tuo login è autorizzato a fare; i permessi sono risolti **per org** (vedi [API keys](/it/agenteye/api-keys)). Un comando per il quale manca il permesso restituisce il codice di uscita `5` con il permesso esatto indicato, quindi l'agente può dirti precisamente cosa chiedere a un amministratore piuttosto che fallire in modo opaco. --- -## Cosa puoi chiederle +## Ciò che puoi chiederle -Ecco come appare un vero scambio, una lettura, quindi un cambio che attende il tuo OK: +Ecco come appare un vero andata-ritorno, una lettura, poi un cambiamento che attende il tuo OK: ```text tu ▸ C'è qualcosa di rotto nell'ultimo giorno? agente ▸ Esecuzione: agenteye --json errors --since 24h --aggregate - 3 tipi di errore nelle ultime 24h. Il più grande è TimeoutError - (18 hit, tutti su checkout-agent), poi RateLimited (5). - Vuoi le sessioni fallite per TimeoutError? + 3 tipi di errore nelle ultime 24h. Il più grande è TimeoutError + (18 colpi, tutti su checkout-agent), poi RateLimited (5). + Vuoi le sessioni fallite per TimeoutError? -tu ▸ Dai a CI una chiave che può solo inviare eventi. +tu ▸ Dai a CI una chiave che può solo spingere eventi. agente ▸ Questo crea una chiave API. Eseguirò: - agenteye keys create ci --add events:add - OK per procedere? + agenteye keys create ci --add events:add + OK per procedere? tu ▸ sì agente ▸ Fatto. Chiave "ci" creata con solo events:add. - Il segreto viene mostrato solo una volta, quindi salvalo ora. Non posso ristamparlo. + Il secret viene mostrato una sola volta, quindi archivialo ora. Non posso ristamparlo. ``` -La competenza mappa ogni intento in linguaggio naturale al giusto comando `agenteye`, scoprendo prima i valori validi (`list `, `whoami`) quindi non indovina, e dichiara il comando esatto prima di qualsiasi cambio. Altri esempi: +La skill mappa ogni intento in linguaggio semplice al comando `agenteye` giusto, scoprendo i valori validi per primo (`list `, `whoami`) in modo da non indovinare, e enunciando il comando esatto prima di qualsiasi cambiamento. Più esempi: - *"C'è qualcosa di rotto / fallito nelle ultime 24 ore?"* → `errors --since 24h --aggregate`, poi un breakdown. - *"Perché la sessione `run-001` ha fallito?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *"Come sta andando la qualità questa settimana?"* → `evals --aggregate --since 7d`, poi approfondisci nei run con punteggio basso. -- *"Dai a CI una chiave che può solo inviare eventi."* → `keys create ci --add events:add` (dichiara il comando, lo crea e cattura il segreto monouso). -- *"Chi ha accesso? Rendi Dana di sola lettura."* → `users list` → `users update dana@… --permission-set read-only` (dopo confirmare con te). -- *"Conferma l'incident in corso e assegnalo a me."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. +- *"Come tende la qualità questa settimana?"* → `evals --aggregate --since 7d`, quindi approfondisci nelle esecuzioni con punteggio basso. +- *"Dai a CI una chiave che può solo spingere eventi."* → `keys create ci --add events:add` (enuncia il comando, poi lo crea e cattura il secret monouso). +- *"Chi ha accesso? Rendi Dana sola lettura."* → `users list` → `users update dana@… --permission-set read-only` (dopo aver confermato con te). +- *"Conferma l'incidente in corso e assegnalo a me."* → `incidents list --state firing` → `incidents ack ` / `incidents assign te@…`. -Per i comandi esatti, flag e forme JSON dietro questi, vedi il riferimento [CLI](/it/agenteye/cli) e [Ricette CLI per agenti](/it/agenteye/cli-recipes). +Per i comandi esatti, i flag e le forme JSON dietro questi, vedi il riferimento [CLI](/it/agenteye/cli) e [CLI recipes per agenti](/it/agenteye/cli-recipes). --- ## Prossimi passi - **[CLI](/it/agenteye/cli)**: riferimento completo di comando e flag per `agenteye`. -- **[Ricette CLI per agenti](/it/agenteye/cli-recipes)**: pattern `jq` da copiare e incollare e gestione del codice di uscita. -- **[Competenza agente Evaluator](/it/agenteye/evaluator-skill)**: la competenza gemella, per costruire l'evaluator i cui punteggi `agenteye evals` legge. -- **[Competenza agente Python SDK](/it/agenteye/python-sdk-skill)**: la competenza gemella, per strumentare un agente in modo che emetta la telemetria che `agenteye` legge. -- **[Assistente AI](/it/agenteye/assistant)**: l'assistente nella dashboard (da non confondere con questa competenza di terminale). -- **[Chiavi API](/it/agenteye/api-keys)**: il modello di autorizzazione per organizzazione che limita quello che la competenza può fare. \ No newline at end of file +- **[CLI recipes per agenti](/it/agenteye/cli-recipes)**: pattern `jq` copia-incolla e gestione dei codici di uscita. +- **[Evaluator agent skill](/it/agenteye/evaluator-skill)**: la skill gemella, per costruire l'evaluator i cui punteggi `agenteye evals` legge. +- **[Python SDK agent skill](/it/agenteye/python-sdk-skill)**: la skill gemella, per strumentare un agente in modo che emetta la telemetria `agenteye` legge. +- **[AI assistant](/it/agenteye/assistant)**: l'assistente nel dashboard (da non confondere con questa skill di terminale). +- **[API keys](/it/agenteye/api-keys)**: il modello di permesso per org che limita ciò che la skill può fare. \ No newline at end of file diff --git a/docs/it/agenteye/cli.mdx b/docs/it/agenteye/cli.mdx index 3661b257..5b543c1f 100644 --- a/docs/it/agenteye/cli.mdx +++ b/docs/it/agenteye/cli.mdx @@ -1,33 +1,34 @@ --- title: "CLI" -description: "Gestisci tutta l'osservabilità di Failproof AI dal terminale o da uno script: nessun accesso necessario alla dashboard." +description: "Guida tutta l'Osservabilità di Failproof AI dal terminale o da uno script: nessun viaggio verso il dashboard." --- -Gestisci tutta l'osservabilità di Failproof AI dal terminale o da uno script: nessun accesso necessario alla dashboard. Il CLI `agenteye` interroga i tuoi dati (sessioni, registri di eventi, valutazioni) e amministra la tua organizzazione (chiavi API, utenti, impostazioni, avvisi, incidenti, query salvate), quindi usalo quando desideri automatizzare un controllo, integrare l'osservabilità in CI, o permettere a un agente di codifica di ispezionare la produzione. Ogni comando supporta un flag `--json`, quindi funziona ugualmente bene per te al prompt o per un agente di codifica (Claude Code, Cursor) che esegue e analizza il risultato. + +Guida tutta l'Osservabilità di Failproof AI dal terminale o da uno script: nessun viaggio verso il dashboard. La CLI `agenteye` interroga i tuoi dati (sessioni, log degli eventi, valutazioni) e amministra la tua organizzazione (chiavi API, utenti, impostazioni, avvisi, incidenti, query salvate), quindi usala quando vuoi automatizzare un controllo, integrare l'Osservabilità nella CI, o permettere a un agente di codifica di ispezionare la produzione. Ogni comando supporta il flag `--json`, quindi funziona altrettanto bene per te al prompt o per un agente di codifica (Claude Code, Cursor) che esegue il comando e analizza il risultato. Con un solo binario puoi: -- **Leggere i tuoi dati**: `sessions`, `events`, `evals`, `errors` (filtra per ora, agente, ambiente, punteggio). +- **Leggere i tuoi dati**: `sessions`, `events`, `evals`, `errors` (filtra per tempo, agente, ambiente, punteggio). - **Gestire la tua organizzazione**: `keys`, `users`, `settings`, `alerts`, `incidents`. -- **Eseguire analitiche**: SQL salvate e un motore di query ad hoc (`query`). -- **Chiedere all'assistente AI**: lo stesso analista di sola lettura con cui chatti nella dashboard (`agent`). +- **Eseguire analitiche**: SQL salvato e un runner di query ad-hoc (`query`). +- **Chiedere all'assistente AI**: lo stesso analista di sola lettura con cui chatti nel dashboard (`agent`). -> **Nota:** Questo è il CLI `agenteye`, uno strumento diverso dal daemon del collettore (`agenteye-collector`). Il CLI comunica con la tua dashboard; il collettore invia gli eventi al server. +> **Nota:** Questa è la CLI `agenteye`, uno strumento diverso dal daemon del collector (`agenteye-collector`). La CLI comunica con il tuo dashboard; il collector invia gli eventi al server. --- -## Avvio rapido +## Guida rapida -Dai nulla al tuo primo risultato in quattro righe. Punta il CLI sulla tua dashboard, accedi, conferma chi sei, quindi estrai l'ultimo giorno di esecuzioni: +Da zero al tuo primo risultato in quattro righe. Punta la CLI al tuo dashboard, accedi, conferma chi sei, quindi estrai l'ultimo giorno di esecuzioni: ```bash pipx install agenteye agenteye --base-url https://agenteye.example.com login --email you@example.com # codice a 6 cifre inviato per email agenteye whoami # conferma utente + organizzazione attiva -agenteye --json sessions --since 24h # una riga per esecuzione agente, ultimi 24h +agenteye --json sessions --since 24h # una riga per ogni esecuzione dell'agente, ultime 24h ``` -Questo ultimo comando stampa un oggetto JSON delle sessioni più recenti (dal più recente al meno recente, limitato a 50 per impostazione predefinita). Indirizzalo in `jq` per affettarlo, o elimina `--json` per una tabella colorata e riquadrata. Ogni riga riporta lo stato dell'esecuzione e, se un valutatore l'ha valutata, i punteggi delle sue metriche (abbreviati qui): +Questo ultimo comando stampa un oggetto JSON delle sessioni più recenti (più nuove per prime, limitate a 50 per impostazione predefinita). Inseriscilo in `jq` per dividerlo, o ometti `--json` per una tabella con bordo e colori. Ogni riga riporta lo stato dell'esecuzione e, se un valutatore l'ha segnata, i suoi punteggi di metrica (abbreviati qui): ```json { @@ -47,17 +48,17 @@ Questo ultimo comando stampa un oggetto JSON delle sessioni più recenti (dal pi } ``` -Il resto di questa pagina spiega ogni aspetto: [installazione](#installation) in isolamento, [accesso](#authentication), [configurazione](#configuration), le [convenzioni globali](#global-options--conventions) che ogni comando condivide, e il [riferimento completo dei comandi](#command-reference). +Il resto di questa pagina spiega ogni parte: [installazione](#installation) in isolamento, [accesso](#authentication), [configurazione](#configuration), le [convenzioni globali](#global-options--conventions) che ogni comando condivide, e il [riferimento completo dei comandi](#command-reference). --- ## Installazione -Il CLI è un pacchetto PyPI pubblico denominato **`agenteye`**. Installalo in un ambiente isolato in modo che abbia sempre le sue dipendenze: +La CLI è un pacchetto pubblico di PyPI denominato **`agenteye`**. Installalo in un ambiente isolato in modo che abbia sempre le sue stesse dipendenze: ```bash pipx install agenteye -# o +# oppure uv tool install agenteye ``` @@ -68,88 +69,88 @@ agenteye --version agenteye --help ``` -> **Nota:** L'SDK Python di Failproof AI Observability utilizza anche il nome di distribuzione `agenteye`. L'installazione del CLI con `pipx` o `uv tool` (piuttosto che `pip install` in un virtualenv condiviso) impedisce conflitti tra i due. Un semplice `pip install agenteye` va bene solo se l'SDK non è installato nello stesso ambiente. +> **Nota:** L'SDK Python dell'Osservabilità Failproof AI utilizza anch'esso il nome di distribuzione `agenteye`. Installare la CLI con `pipx` o `uv tool` (anziché `pip install` in un virtualenv condiviso) evita collisioni tra i due. Un semplice `pip install agenteye` va bene solo se l'SDK non è installato nello stesso ambiente. --- ## Autenticazione -Il CLI si autentica alla **dashboard** con un codice monouso inviato per email: +La CLI si autentica al **dashboard** con un codice monouso inviato per email: ```bash agenteye login --email you@example.com # Un codice a 6 cifre ti viene inviato per email; incollalo al prompt. ``` -Il token di sessione viene archiviato in `~/.agenteye/cli.json` (leggibile solo da te, modalità `0600`) ed è valido per 24 ore per impostazione predefinita. Quando scade, esegui di nuovo `agenteye login`. +Il token di sessione è memorizzato in `~/.agenteye/cli.json` (leggibile solo da te, modo `0600`) ed è valido per 24 ore per impostazione predefinita. Quando scade, esegui di nuovo `agenteye login`. ```bash -agenteye whoami # mostra l'utente corrente, l'organizzazione attiva e i permessi -agenteye logout # revoca la sessione e cancella il token archiviato +agenteye whoami # mostra l'utente attuale, l'organizzazione attiva e i permessi +agenteye logout # revoca la sessione e cancella il token memorizzato ``` -`whoami` non genera mai errori per una sessione mancante o scaduta; invece riporta `logged_in: false`, quindi uno script o agente può controllare lo stato di autenticazione in sicurezza (può comunque uscire con codice diverso da zero se nessuna URL di base è impostata o la dashboard non è raggiungibile). +`whoami` non genera mai errori su una sessione mancante o scaduta; invece riporta `logged_in: false`, quindi uno script o un agente può sondare lo stato di autenticazione in modo sicuro (può comunque uscire con non-zero se non è impostato alcun URL di base o il dashboard non è raggiungibile). -**Requisiti:** la tua email deve essere autorizzata ad accedere alla dashboard (chiedi all'amministratore di Failproof AI Observability), e la dashboard deve essere raggiungibile al suo URL di base (vedi [Configurazione](#configuration)). Se richiedi un codice e nessuno arriva, probabilmente la tua email non è ancora abilitata per l'accesso alla dashboard. +**Requisiti:** la tua email deve essere abilitata per l'accesso al dashboard (chiedi all'amministratore dell'Osservabilità Failproof AI), e il dashboard deve essere raggiungibile al suo URL di base (vedi [Configurazione](#configuration)). Se richiedi un codice e non ne arriva nessuno, la tua email probabilmente non è ancora abilitata per l'accesso al dashboard. --- -## Scelta della tua organizzazione (multi-tenant) +## Scegliere la tua organizzazione (multi-tenant) -Se il tuo account appartiene a più di un'organizzazione, scegli quello attivo **al login**; viene salvato e utilizzato per ogni comando successivo: +Se il tuo account appartiene a più di un'organizzazione, scegli quella attiva **all'accesso**; viene salvata e utilizzata per ogni comando successivo: ```bash -agenteye login --org acme # autentica e imposta il tenant attivo in un passaggio +agenteye login --org acme # autentica e imposta il tenant attivo in un unico passaggio agenteye orgs list # le organizzazioni a cui puoi accedere (quella attiva è contrassegnata) agenteye orgs switch globex # cambia il valore predefinito salvato agenteye --org globex sessions # ignora per un singolo comando ``` -Se appartieni a esattamente un'organizzazione viene selezionata automaticamente e puoi ignorare completamente `--org`. Se appartieni a più organizzazioni e non ne scegli una, il CLI le elenca e ti chiede di eseguire di nuovo con `--org `. L'organizzazione attiva viene inviata alla dashboard ad ogni richiesta, e i tuoi permessi vengono risolti **per organizzazione**; `agenteye whoami` mostra l'organizzazione attiva, i tuoi permessi in essa, e tutti i tuoi memberships. +Se appartieni a esattamente un'organizzazione, viene selezionata automaticamente e puoi ignorare completamente `--org`. Se appartieni a più di una e non ne scegli una, la CLI le elenca e ti chiede di rieseguire con `--org `. L'organizzazione attiva viene inviata al dashboard ad ogni richiesta e i tuoi permessi vengono risolti **per organizzazione**; `agenteye whoami` mostra l'organizzazione attiva, i tuoi permessi in essa e tutte le tue appartenenze. --- ## Configurazione -| Impostazione | Flag | Variabile di ambiente | Valore predefinito | +| Impostazione | Flag | Variabile d'ambiente | Predefinito | |---|---|---|---| -| URL di base della dashboard | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **obbligatorio** (nessun valore predefinito) | -| Organizzazione/tenant attivo | `--org` | `AGENTEYE_ORG` | scelto al login; salvato in `~/.agenteye/cli.json` | +| URL di base del dashboard | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **obbligatorio** (nessun valore predefinito) | +| Organizzazione/tenant attiva | `--org` | `AGENTEYE_ORG` | scelto all'accesso; salvato in `~/.agenteye/cli.json` | | Token di sessione | `--token` | `AGENTEYE_CLI_TOKEN` | da `~/.agenteye/cli.json` | | Output JSON | `--json` | `AGENTEYE_CLI_JSON` | disattivato | -| Salta verifica TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | disattivato (salvato al login) | -| Timeout richieste (secondi) | `--timeout` | _(nessuno)_ | 30 | +| Ignora verifica TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | disattivato (salvato all'accesso) | +| Timeout della richiesta (secondi) | `--timeout` | _(nessuno)_ | 30 | | Disabilita telemetria di utilizzo | _(nessuno)_ | `AGENTEYE_ANALYTICS_DISABLED` (o `DO_NOT_TRACK`) | la telemetria è attualmente disabilitata; nulla viene inviato | -L'ordine di risoluzione è **flag → variabile di ambiente → file di configurazione**. Non c'è valore predefinito; devi puntare il CLI sulla tua dashboard, sia per comando (`--base-url https://agenteye.example.com`) che una volta tramite l'ambiente (viene anche salvato dopo il tuo primo `login`): +L'ordine di risoluzione è **flag → variabile d'ambiente → file di configurazione**. Non c'è un valore predefinito; devi puntare la CLI al tuo dashboard, sia per comando (`--base-url https://agenteye.example.com`) che una volta tramite l'ambiente (viene salvato anche dopo il tuo primo `login`): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -La directory di configurazione rispetta `AGENTEYE_HOME` (la stessa convenzione utilizzata dall'SDK e dal collettore); se impostato, `cli.json` si trova in `$AGENTEYE_HOME/cli.json`. +La directory di configurazione rispetta `AGENTEYE_HOME` (la stessa convenzione utilizzata dall'SDK e dal collector); se impostato, `cli.json` si trova in `$AGENTEYE_HOME/cli.json`. ### TLS autofirmato o interno -Se la tua dashboard è servita su HTTPS con un certificato autofirmato o interno (ad esempio, un nome host di bilanciamento del carico non elaborato), la verifica TLS lo rifiuta con un errore `CERTIFICATE_VERIFY_FAILED`. Passa `--insecure` per saltare la verifica del certificato: +Se il tuo dashboard è servito su HTTPS con un certificato autofirmato o interno (ad esempio, un nome host del load-balancer grezzo), la verifica TLS lo rifiuta con un errore `CERTIFICATE_VERIFY_FAILED`. Passa `--insecure` per saltare la verifica del certificato: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` è **salvato in `cli.json` quando accedi**, quindi i comandi successivi saltano la verifica automaticamente; non devi ripetere il flag. Passa `--secure` per una singola chiamata verificata, o per salvare la verifica di nuovo al tuo prossimo login. Il CLI stampa un avviso a stderr prima di qualsiasi comando che contatta la dashboard mentre la verifica è disabilitata. Saltare la verifica rimuove la protezione contro gli attacchi man-in-the-middle; assicurati di fidarti del percorso di rete verso la tua dashboard (VPN, subnet privata, ecc.) prima di affidarti ad essa. +`--insecure` è **salvato in `cli.json` quando accedi**, quindi i comandi successivi saltano la verifica automaticamente; non devi ripetere il flag. Passa `--secure` per una chiamata verificata una tantum, o per salvare nuovamente la verifica al tuo prossimo accesso. La CLI stampa un avviso su stderr prima di ogni comando che contatta il dashboard con la verifica disabilitata. Saltare la verifica rimuove la protezione contro gli attacchi man-in-the-middle; assicurati di fidarti del percorso di rete verso il tuo dashboard (VPN, subnet privata, ecc.) prima di fare affidamento su di esso. --- ## Telemetria e privacy -> **Nota:** Il CLI spedito **non invia alcuna telemetria di utilizzo oggi.** Un interruttore di disabilitazione principale è attivato, quindi nulla viene trasmesso indipendentemente dal tuo ambiente. La sezione sottostante descrive la capacità di esclusione per se e quando la telemetria fosse mai abilitata. +> **Nota:** La CLI fornita **non invia alcuna telemetria di utilizzo oggi.** Un interruttore di arresto generale è attivato, quindi nulla viene trasmesso indipendentemente dal tuo ambiente. La sezione seguente descrive la capacità di opt-out per se e quando la telemetria fosse mai abilitata. Anche se abilitata, la telemetria sarebbe **solo analitiche di utilizzo anonime**, mai i tuoi dati di agente, sessione o evento: -- **Nessun dato di agente, sessione o evento lascia mai la tua infrastruttura.** Solo l'utilizzo del CLI verrebbe segnalato: il nome del comando e sottocomando (ad esempio `keys create`), i **nomi** dei flag che hai usato (mai i loro valori), stato di successo/uscita e durata, più un evento per-azione per le mutazioni (ad esempio `api_key_created`, `query_run`) contenente solo nomi/enum statici e conteggi grossolani. L'URL della tua dashboard, il token di sessione, l'email, lo slug dell'organizzazione, gli id delle risorse, SQL, i segreti delle chiavi e i filtri delle query non verrebbero **mai** inviati. Gli operatori sarebbero identificati solo da un id interno opaco, mai per email. -- **Escludi in anticipo** impostando `AGENTEYE_ANALYTICS_DISABLED=1` nell'ambiente del CLI (il CLI rispetta anche la convenzione cross-tool `DO_NOT_TRACK=1`). Questo entra in vigore nel momento in cui la telemetria viene mai attivata, quindi un ambiente consapevole della privacy può rimanere escluso in modo permanente. -- Se la telemetria fosse abilitata, il CLI invierebbe direttamente a PostHog (`https://us.i.posthog.com`); una macchina con quell'host bloccato non invierebbe silenziosamente nulla e il CLI ne sarebbe illeso. +- **Nessun dato di agente, sessione o evento lascia mai la tua infrastruttura.** Verrebbe segnalato solo l'utilizzo della CLI: il nome del comando e del sottocomando (ad es. `keys create`), i **nomi** dei flag che hai utilizzato (mai i loro valori), stato di successo/uscita e durata, più un evento per azione per le mutazioni (ad es. `api_key_created`, `query_run`) portando solo nomi/enum statici e conteggi approssimativi. L'URL del tuo dashboard, il token di sessione, l'email, lo slug dell'organizzazione, gli id delle risorse, SQL, i segreti delle chiavi e i filtri delle query **non** verrebbero mai inviati. Gli operatori verrebbero identificati solo da un id interno opaco, mai per email. +- **Rifiuta in anticipo** impostando `AGENTEYE_ANALYTICS_DISABLED=1` nell'ambiente della CLI (la CLI rispetta anche la convenzione cross-tool `DO_NOT_TRACK=1`). Questo entra in vigore nel momento in cui la telemetria fosse mai attivata, quindi un ambiente attento alla privacy può rimanere rifiutato in modo permanente. +- Se la telemetria fosse abilitata, la CLI invierebbe direttamente a PostHog (`https://us.i.posthog.com`); una macchina con quell'host bloccato invierebbe silenziosamente nulla e la CLI non ne sarebbe influenzata. --- @@ -157,115 +158,115 @@ Anche se abilitata, la telemetria sarebbe **solo analitiche di utilizzo anonime* Leggi questa sezione una volta; si applica a ogni comando. -- **Le opzioni globali vanno PRIMA del comando.** `agenteye --json sessions` è corretto; `agenteye sessions --json` è un errore di utilizzo. I globali sono `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, e `--no-color`. -- **`--json` stampa pure JSON su stdout, e nulla di più.** Le righe di stato umano, gli avvisi e gli errori vanno su **stderr**, quindi un'acquisizione di stdout `--json` rimane pulita da indirizzare in `jq` anche quando viene mostrata una riga di stato. Senza `--json` ottieni una visualizzazione riquadrata e colorata per gli occhi umani. -- **Scopri con `--help`.** Ogni comando e sottocomando ha `--help` (e l'alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. L'aiuto di primo livello elenca anche i codici di uscita e le opzioni globali. Non c'è dump di superficie leggibile da macchina globale; usa per-comando `--help`, più il dominio-specifico `agenteye query schema` e `agenteye settings schema` per quei due registri. -- **Le conferme auto-saltano per script e agenti.** I comandi create/update/delete chiedono "sei sicuro?" in un terminale interattivo, ma **auto-saltano quel prompt sotto `--json` o quando stdin non è un TTY** (un TTY è una sessione di terminale interattiva; una pipe o un runner CI non lo è), quindi script e agenti non rimangono mai bloccati. Passa `--yes`/`-y` per saltarlo esplicitamente. Poiché il prompt non si attiva per un agente, un agente dovrebbe confermare le azioni distruttive con l'umano per primo. -- **Paginazione:** i risultati sono dal più recente al meno recente e paginati per cursore (ogni pagina restituisce un token che usi per recuperare il prossimo). `--limit N` (alias `-n`) limita le righe e **preimposta a 50**; `--all` auto-pagina (in chunk di 200 righe) **fino a `--limit`**, quindi un bare `--all` si ferma ancora a 50. Per un sweep completo passa un limite esplicito alto: `--all --limit 1000`. `--page-size N` controlla il chunk per-richiesta (max 200); `--cursor ` riprende dal `next_cursor` di una pagina precedente. -- **Filtri di tempo:** `--since` accetta una finestra relativa: `15m`, `1h`, `6h`, `24h`, `7d`, o `all` (i preset della dashboard). Per un intervallo più lungo o personalizzato (diciamo gli ultimi 30 giorni), usa `--from`/`--to`: timestamp UTC ISO-8601 espliciti **con `T` e un fuso orario** (ad esempio `2026-06-01T00:00:00Z`) che ignorano `--since`. Un valore separato da spazi o senza fuso orario è un errore di utilizzo. +- **Le opzioni globali vanno PRIMA del comando.** `agenteye --json sessions` è corretto; `agenteye sessions --json` è un errore di utilizzo. I globali sono `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` e `--no-color`. +- **`--json` stampa JSON puro su stdout, e nient'altro.** Le righe di stato umane, gli avvisi e gli errori vanno su **stderr**, quindi un'acquisizione di stdout `--json` rimane pulita per inserire in `jq` anche quando viene mostrata una riga di stato. Senza `--json` ottieni una visualizzazione con bordo e a colori per occhi umani. +- **Scopri con `--help`.** Ogni comando e sottocomando ha `--help` (e l'alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. L'aiuto di livello superiore elenca anche i codici di uscita e le opzioni globali. Non esiste un dump di superficie machine-readable globale; usa `--help` per comando, più i `agenteye query schema` e `agenteye settings schema` specifici del dominio per questi due registri. +- **Le conferme auto-skip per script e agenti.** I comandi crea/aggiorna/cancella chiedono "sei sicuro?" in un terminale interattivo, ma **auto-skip quel prompt sotto `--json` o ogni volta che stdin non è un TTY** (un TTY è una sessione di terminale interattiva; una pipe o un runner CI non lo è), quindi script e agenti non si bloccano mai. Passa `--yes`/`-y` per saltarlo esplicitamente. Poiché il prompt non si attiva per un agente, un agente dovrebbe confermare le azioni distruttive con l'umano prima. +- **Paginazione:** i risultati sono più recenti per primi e pagini tramite cursore (ogni pagina restituisce un token che usi per recuperare la successiva). `--limit N` (alias `-n`) limita le righe e **predefinito a 50**; `--all` auto-paginazione (in blocchi di 200 righe) **fino a `--limit`**, quindi un semplice `--all` si ferma comunque a 50. Per uno sweep completo passa un limite esplicito alto: `--all --limit 1000`. `--page-size N` controlla il blocco per richiesta (max 200); `--cursor ` riprende da `next_cursor` di una pagina precedente. +- **Filtri temporali:** `--since` accetta una finestra relativa: `15m`, `1h`, `6h`, `24h`, `7d`, o `all` (i preset del dashboard). Per un intervallo più lungo o personalizzato (diciamo gli ultimi 30 giorni), usa `--from`/`--to`: timestamp UTC espliciti ISO-8601 **con `T` e un fuso orario** (ad es. `2026-06-01T00:00:00Z`) che ignorano `--since`. Un valore separato da spazio o senza fuso orario è un errore di utilizzo. - **`--fields a,b,c`** (su `events`, `sessions`, `evals`, `errors`) limita l'output a quelle chiavi, sia per la tabella che per `--json`. I nomi sconosciuti vengono rifiutati con l'elenco valido, un modo economico per scoprire i nomi dei campi. -- **`--file payload.json`** (o `--file -` per leggere stdin) fornisce un corpo di richiesta JSON completo dove una risorsa ha una forma complessa (su `alerts create/update`, `settings set`, e `users create/update`). SQL di query salvate usa `--sql @file.sql` invece. -- **I filtri multi-valore** sono comma-separated → abbinati come un insieme (unione all'interno di un filtro, AND tra i filtri): `--event-type tool_use,tool_result`. Le opzioni click non sono variadiche, quindi `--add a b` si rompe. Usa `--add a,b`, ripeti il flag (`--add a --add b`), o circonda con virgolette (`--add "a b"`). +- **`--file payload.json`** (o `--file -` per leggere stdin) fornisce un corpo di richiesta JSON completo dove una risorsa ha una forma complessa (su `alerts create/update`, `settings set` e `users create/update`). Il SQL della query salvata usa `--sql @file.sql` invece. +- **I filtri multi-valore** sono separati da virgola → corrisposti come un set (unione all'interno di un filtro, AND attraverso i filtri): `--event-type tool_use,tool_result`. Le opzioni di clic non sono variadiche, quindi `--add a b` si rompe. Usa `--add a,b`, ripeti il flag (`--add a --add b`), o virgolette (`--add "a b"`). --- ## Riferimento dei comandi -### Userai questi 5 comandi più spesso +### Utilizzerai questi 5 comandi principalmente -La maggior parte del lavoro quotidiano viene eseguita attraverso una manciata di comandi di lettura. Inizia qui, quindi raggiungi la superficie completa sottostante quando ne hai bisogno: +La maggior parte del lavoro quotidiano viene eseguita attraverso una manciata di comandi di lettura. Inizia qui, quindi ricorri alla superficie completa sottostante quando ne hai bisogno: -| Comando | Cosa fa | Provalo | +| Comando | Cosa fa | Prova | |---|---|---| -| `sessions` | Una riga per esecuzione agente: ora, ambiente, agente, stato, punteggio più recente. | `agenteye --json sessions --since 24h --status error` | -| `events` | La traccia grezza per step dentro un'esecuzione (aggiungi `--full` per i payload). | `agenteye --json events --session-id run-001 --all` | +| `sessions` | Una riga per esecuzione dell'agente: ora, ambiente, agente, stato, punteggio più recente. | `agenteye --json sessions --since 24h --status error` | +| `events` | La scia grezza per passaggio all'interno di un'esecuzione (aggiungi `--full` per i payload). | `agenteye --json events --session-id run-001 --all` | | `evals` | Risultati di valutazione e punteggi; `--aggregate` li raggruppa. | `agenteye --json evals --aggregate --since 7d --env prod` | | `errors` | Solo gli eventi con errore; `--aggregate` per conteggi per tipo. | `agenteye --json errors --since 24h --aggregate` | | `list` | Scopri i valori di filtro validi (agenti, ambienti, modelli, …). | `agenteye list agents` | -### Tutto quello che il CLI può fare +### Tutto ciò che la CLI può fare -La superficie completa segue. Il CLI ha **18 comandi di primo livello**. Tutti i comandi di lettura accettano `--json` e le opzioni globali sopra; esegui `agenteye -h` (o ` -h`) per l'elenco di flag esaustivo e la forma JSON di uno qualsiasi. +Segue la superficie completa. La CLI ha **18 comandi di livello superiore**. Tutti i comandi di lettura accettano `--json` e le opzioni globali sopra; esegui `agenteye -h` (o ` -h`) per l'elenco di flag esaustivo e la forma JSON di uno qualsiasi. ### Identità: `login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash agenteye login --email you@example.com [--org acme] # codice monouso inviato per email; salva la sessione agenteye logout # cancella la sessione salvata su questa macchina -agenteye whoami # utente corrente, organizzazione attiva, permessi -agenteye version # stampa la versione del CLI (come --version) -agenteye help # aiuto di primo livello (come --help) +agenteye whoami # utente attuale, organizzazione attiva, permessi +agenteye version # stampa la versione della CLI (come --version) +agenteye help # aiuto di livello superiore (come --help) ``` -`orgs` ispeziona e cambia il tenant attivo: +`orgs` ispeziona e commuta il tenant attivo: ```bash -agenteye orgs list # le tue organizzazioni + il tuo ruolo in ciascuna (quella attiva è contrassegnata) -agenteye orgs switch acme # cambia l'organizzazione attiva salvata (ometti lo slug per scegliere da un elenco su un TTY) -agenteye orgs current # carta di identità per l'organizzazione attiva +agenteye orgs list # le tue organizzazioni + il tuo ruolo in ognuna (quella attiva contrassegnata) +agenteye orgs switch acme # cambia l'organizzazione attiva salvata (ometti lo slug per scegliere da un elenco su TTY) +agenteye orgs current # carta d'identità per l'organizzazione attiva agenteye orgs perms # i tuoi permessi nell'organizzazione attiva, raggruppati per risorsa ``` -### Osserva (sola lettura): `events` · `sessions` · `evals` · `errors` · `list` +### Osserva (di sola lettura): `events` · `sessions` · `evals` · `errors` · `list` -Nessuno di questi ha bisogno di una conferma. Filtri condivisi: `--session-id`, `--agent-id`, `--env` (**non** `--environment`), e l'intervallo di tempo (`--since` / `--from` / `--to`). +Nessuno di questi richiede una conferma. Filtri condivisi: `--session-id`, `--agent-id`, `--env` (**non** `--environment`), e l'intervallo temporale (`--since` / `--from` / `--to`). ```bash -# events (alias: la traccia grezza per step), dal più recente al meno recente +# events (alias: la scia grezza per passaggio), più recenti per prime agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' -# sessions: una riga per esecuzione agente (ora/ambiente/agente/sessione/stato; nessun filtro di punteggio) +# sessions: una riga per esecuzione dell'agente (ora/ambiente/agente/sessione/stato; nessun filtro punteggio) agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 # evals: risultati di valutazione + punteggi; --score filtra per metrica, --aggregate raggruppa agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 -agenteye --json evals --aggregate --since 7d --env prod # mix di stato + stats di punteggio per chiave +agenteye --json evals --aggregate --since 7d --env prod # mix di stato + statistiche di punteggio per chiave -# errors: eventi con errore; --aggregate per conteggi/sessioni/agenti/ultimo-visto +# errors: eventi con errore; --aggregate per conteggi/sessioni/agenti/ultima visualizzazione agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 # list: scopri i valori di filtro validi prima di filtrare -agenteye list envs # inoltre: agents event_types score_filters models hooks tools error_types +agenteye list envs # anche: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (su **`evals`**, non `sessions`) è ripetibile e AND-combinato; entrambi i limiti sono opzionali (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Fino a 20 filtri di punteggio per richiesta. `evals --scores-full` è un flag di visualizzazione per la **tabella umana solamente**; mostra ogni coppia di punteggio invece dei primi pochi più un conteggio `+N`. Non ha effetto sotto `--json`, che restituisce sempre l'oggetto di punteggio completo. Per leggere **una sessione end-to-end**, combina la traccia di evento con la sua valutazione: +`--score KEY:MIN..MAX` (su **`evals`**, non `sessions`) è ripetibile e AND-combinato; uno qualsiasi dei limiti è opzionale (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Fino a 20 filtri di punteggio per richiesta. `evals --scores-full` è un flag di visualizzazione solo per la **tabella umana**; mostra ogni coppia di punteggio invece dei primi pochi più un conteggio `+N`. Non ha effetto sotto `--json`, che restituisce sempre l'oggetto di punteggio completo. Per leggere **una sessione end-to-end**, combina la scia di evento con la sua valutazione: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' agenteye --json evals --session-id run-001 # i suoi punteggi + stato ``` -### Gestisci (gated da permessi): `keys` · `users` · `settings` · `alerts` · `incidents` +### Gestisci (gated di permesso): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: chiavi API. Il segreto viene generato localmente, inviato al server (che memorizza solo un hash), e **mostrato una volta** su create/regenerate; catturalo allora. Con `--json` appare solo nel campo `key`. Referenziato per **nome**. +**`keys`**: Chiavi API. Il segreto viene generato localmente, inviato al server (che memorizza solo un hash) e **mostrato una volta** su crea/rigenera; acquisiscilo allora. Con `--json` appare solo nel campo `key`. Riferito per **nome**. ```bash agenteye keys list # chiavi attive per prime, poi revocate agenteye keys show ci-bot -agenteye keys create ci-bot --add events:read.add # circoscrivi a quello di cui hai bisogno; stampa il segreto UNA VOLTA -agenteye keys create ops --permission-set standard --remove queries:run # semina un preset, poi taglia +agenteye keys create ci-bot --add events:read.add # ambito a ciò di cui hai bisogno; stampa il segreto UNA VOLTA +agenteye keys create ops --permission-set standard --remove queries:run # inizia un preset, poi ritaglia agenteye keys update ci-bot --add evaluations:read --yes agenteye keys regenerate ci-bot --yes # ruota il segreto (quello vecchio smette di funzionare) agenteye keys disable ci-bot --yes # revoca ``` -I permessi funzionano come `(permission-set ∪ --add) − --remove`. I token sono `slug:action` (ad esempio `events:read`) o `slug:action.action` per espandere diversi su una risorsa (`events:read.add` → `events:read`, `events:add`). Preset: `read-only`, `standard`, `admin`. I permessi solo per umani (`keys:update`) non possono essere concessi a una chiave. +I permessi funzionano come `(permission-set ∪ --add) − --remove`. I token sono `slug:action` (ad es. `events:read`) o `slug:action.action` per espanderne diversi su una risorsa (`events:read.add` → `events:read`, `events:add`). Preset: `read-only`, `standard`, `admin`. I permessi solo umani (`keys:update`) non possono essere concessi a una chiave. -**`users`**: membri dell'organizzazione, referenziati per **email** (è anche accettato un id UUID). +**`users`**: membri dell'organizzazione, riferiti per **email** (è accettato anche un id UUID). ```bash agenteye users list [--active-only] agenteye users show dev@corp.com agenteye users create dev@corp.com --permission-set standard agenteye users update dev@corp.com --add alerts:write --remove queries:delete # predice + conferma -agenteye users disable dev@corp.com --yes # ha protezioni/guardie di se stesso +agenteye users disable dev@corp.com --yes # ha protezioni/guardie personali agenteye users enable dev@corp.com ``` -**`settings`**: un registro fisso (leggi e cambia le chiavi esistenti; non puoi crearne di nuove). +**`settings`**: un registro fisso (leggi e modifica le chiavi esistenti; non puoi crearne di nuove). ```bash agenteye settings list # chiave · valore · tipo · aggiornato (segreti mascherati) @@ -273,7 +274,7 @@ agenteye settings schema # cosa accetta ogni chiave agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: definizioni di avviso, referenziate per **nome**. `create` accetta un NAME posizionale più flag o un corpo JSON completo via `--file`. +**`alerts`**: definizioni di avviso, riferite per **nome**. `create` accetta un NAME posizionale più flag o un corpo JSON completo tramite `--file`. ```bash agenteye alerts list @@ -284,16 +285,16 @@ agenteye alerts test high-errors --yes # attiva una notif agenteye alerts delete high-errors --yes ``` -**`incidents`**: incidenti di avviso, referenziati per id (id brevi accettati). `show` stampa il registro completo di attività; leggi prima di agire. +**`incidents`**: incidenti di avviso, riferiti per id (accettati gli id brevi). `show` stampa il log di attività completo; leggilo prima di agire. ```bash -agenteye incidents list --state firing # inoltre: acknowledged, resolved +agenteye incidents list --state firing # anche: acknowledged, resolved agenteye incidents count agenteye incidents show agenteye incidents ack agenteye incidents assign you@corp.com # l'assegnatario deve essere un operatore agenteye incidents resolve --yes -agenteye incidents open --alert-id --severity critical # aprine uno manualmente contro un avviso +agenteye incidents open --alert-id --severity critical # apri uno manualmente contro un avviso agenteye incidents comment-add "root cause: upstream 5xx" agenteye incidents comment-list ; agenteye incidents comment-delete agenteye incidents subscribe ; agenteye incidents unsubscribe ; agenteye incidents subscribers @@ -301,23 +302,23 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### Analitiche e assistente: `query` · `agent` -**`query`**: SQL salvato contro il tuo store di analitiche più un runner ad hoc. Le query salvate sono referenziate per **nome**; l'SQL viene validato lato server (solo SELECT/WITH, timeout di statement, cap di riga). +**`query`**: SQL salvato contro il tuo archivio di analitiche più un runner ad-hoc. Le query salvate sono riferite per **nome**; l'SQL viene convalidato lato server (solo SELECT/WITH, timeout dell'istruzione, limite di riga). ```bash -agenteye query schema [TABLE] # layout di colonna delle viste analitiche +agenteye query schema [TABLE] # layout delle colonne delle viste analitiche agenteye query run --sql "select count(*) from analytics.events" -agenteye query run errs --arg prod --limit 100 # esegui una query salvata + un positivo $1 +agenteye query run errs --arg prod --limit 100 # esegui una query salvata + un $1 posizionale agenteye query list ; agenteye query show errs agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: parla con l'**assistente AI** incorporato (lo stesso analista di sola lettura con cui puoi chattare nella dashboard). Le chat sono referenziate da uno short chat-id (risoluzione dei prefissi). +**`agent`**: parla all'**assistente AI** incorporato (lo stesso analista di sola lettura con cui puoi chattare nel dashboard). Le chat sono riferite da un id-chat breve (risoluzione del prefisso). ```bash agenteye agent health # l'assistente AI è configurato/raggiungibile agenteye agent models # modelli che puoi passare a --model (predefinito contrassegnato) -agenteye agent ask "which agents errored most in the last day?" # avvia una chat; stampa il suo short id +agenteye agent ask "which agents errored most in the last day?" # avvia una chat; stampa il suo id breve agenteye agent ask --chat "and which tools did they call?" # continua quella chat agenteye agent chats ; agenteye agent show agenteye agent rename --title "error triage" ; agenteye agent delete @@ -330,20 +331,20 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | Codice | Significato | |---|---| | 0 | Successo | -| 1 | Errore inaspettato (ad esempio la dashboard ha restituito un 5xx) | +| 1 | Errore inaspettato (ad es. il dashboard ha restituito un 5xx) | | 2 | Errore di utilizzo (argomenti non validi, comando/flag sconosciuto, collisione di nome) | -| 3 | Non è possibile raggiungere la dashboard | -| 4 | Non hai effettuato l'accesso o la sessione è scaduta; esegui `agenteye login` | +| 3 | Impossibile raggiungere il dashboard | +| 4 | Non connesso o sessione scaduta; esegui `agenteye login` | | 5 | Autenticato, ma il tuo account manca del permesso richiesto (il messaggio lo nomina) | -| 6 | La risorsa richiesta non è stata trovata (ad esempio id di sessione o incidente sconosciuto) | +| 6 | La risorsa richiesta non è stata trovata (ad es. id di sessione o incidente sconosciuto) | -Questi rendono il CLI sicuro per scripting: un agente di codifica può dirammarsi su un `4` per chiederti di ri-autenticarti, o un `5` per visualizzare il permesso mancante. Vedi [Ricette CLI per agenti](/it/agenteye/cli-recipes) per gestione dei codici di uscita e forme di output JSON. +Questi rendono la CLI sicura da scriptare: un agente di codifica può ramificare su un `4` per chiederti di riauthenticarti, o su un `5` per esporre il permesso mancante. Vedi [Ricette CLI per agenti](/it/agenteye/cli-recipes) per schemi di gestione dei codici di uscita e forme di output JSON. --- -## Prossimi passaggi +## Prossimi passi -- **[Ricette CLI per agenti](/it/agenteye/cli-recipes)**: pattern di query copia-incolla, one-liner `jq`, proiezioni `--fields`, gestione dei codici di uscita, e forme di output JSON, scritti per agenti di codifica che guidano il CLI. -- **[Skill agent CLI](/it/agenteye/cli-skill)**: compacchia questo CLI come una *skill* installabile di Claude Code / Codex in modo che un agente di codifica guidi l'osservabilità di Failproof AI da richieste in linguaggio naturale. -- **[Chiavi API](/it/agenteye/api-keys)**: il modello di permessi dietro `keys create --add …`. -- **[Assistente AI](/it/agenteye/assistant)**: abilitazione dell'assistente con cui `agent ask` parla. \ No newline at end of file +- **[Ricette CLI per agenti](/it/agenteye/cli-recipes)**: pattern di query copia-incolla, one-liner `jq`, proiezioni `--fields`, gestione dei codici di uscita e forme di output JSON, scritte per agenti di codifica che guidano la CLI. +- **[Abilità agente CLI](/it/agenteye/cli-skill)**: pacchetto questa CLI come una *abilità* installabile di Claude Code / Codex in modo che un agente di codifica guidi l'Osservabilità Failproof AI da richieste in linguaggio naturale. +- **[Chiavi API](/it/agenteye/api-keys)**: il modello di permesso dietro `keys create --add …`. +- **[Assistente AI](/it/agenteye/assistant)**: abilitazione dell'assistente a cui `agent ask` parla. \ No newline at end of file diff --git a/docs/it/agenteye/codex-capture.mdx b/docs/it/agenteye/codex-capture.mdx index cddad4b1..2c5a5bed 100644 --- a/docs/it/agenteye/codex-capture.mdx +++ b/docs/it/agenteye/codex-capture.mdx @@ -1,56 +1,56 @@ --- --- -title: "Acquisizione di sessioni Codex" -description: "Integra le sessioni locali di OpenAI Codex del tuo team in AgentEye come sessioni ed eventi ordinari — senza cambiare il modo in cui eseguono Codex." +title: "Acquisizione sessioni Codex" +description: "Cattura le sessioni locali di OpenAI Codex del tuo team in AgentEye come sessioni ed eventi ordinari — senza alcun cambiamento nel modo in cui eseguono Codex." --- -I tuoi ingegneri usano già OpenAI Codex ogni giorno. L'acquisizione di sessioni Codex porta quelle sessioni di programmazione in AgentEye come sessioni ed eventi ordinari, così puoi cercarle, riprodurle e valutarle insieme a tutto il resto che osservi. Complementa l'[SDK Python](/it/agenteye/python-sdk): l'SDK strumenta gli agenti che scrivi, mentre questo cattura il lavoro Codex che il tuo team fa già — senza cambiare il modo in cui lo eseguono. +I tuoi ingegneri eseguono già OpenAI Codex ogni giorno. L'acquisizione delle sessioni Codex porta quelle sessioni di coding in AgentEye come sessioni ed eventi ordinari, permettendoti di cercarle, riprodurle e valutarle insieme a tutto il resto che osservi. Completa l'[SDK Python](/it/agenteye/python-sdk): l'SDK strumenta gli agenti che scrivi, mentre questo cattura il lavoro con Codex che il tuo team fa già — senza alcun cambiamento nel modo in cui lo esegue. -Un piccolo collettore in background legge i trascritti delle sessioni locali di Codex man mano che vengono scritti e li invia ad AgentEye. Un collettore per macchina cattura ogni superficie Codex locale contemporaneamente — non è necessaria una configurazione per ogni superficie. +Un piccolo collettore in background legge i transcript locali delle sessioni Codex mentre vengono scritti e li invia ad AgentEye. Un collettore per macchina cattura ogni superficie Codex locale contemporaneamente — non è necessaria alcuna configurazione per singola superficie. -Lo stesso collettore cattura anche altri agenti — vedi [OpenClaw](/it/agenteye/openclaw-capture) e [Hermes](/it/agenteye/hermes-capture). Abilita ciascuno che esegui; un singolo collettore può catturarne diversi contemporaneamente. +Lo stesso collettore cattura anche altri agenti — vedi [OpenClaw](/it/agenteye/openclaw-capture) e [Hermes](/it/agenteye/hermes-capture). Abilita ognuno che esegui; un singolo collettore può catturarne diversi contemporaneamente. --- ## Cosa cattura -Ogni superficie Codex che viene eseguita **localmente** produce gli stessi trascritti di sessione su disco, e il collettore li cattura tutti: +Ogni superficie Codex eseguita **localmente** produce gli stessi transcript di sessione su disco, e il collettore li raccoglie tutti: -- il **CLI** di Codex e `codex exec` +- la **CLI** di Codex e `codex exec` - l'**estensione VS Code / IDE** - l'**app desktop**, quando esegue una sessione localmente -Ogni sessione Codex diventa una [sessione](/it/agenteye/sessions) di AgentEye; i suoi messaggi utente e assistente, il ragionamento, le chiamate agli strumenti, i risultati degli strumenti e l'utilizzo dei token diventano gli [eventi](/it/agenteye/event-stream) corrispondenti. La superficie da cui proviene ogni sessione (CLI, IDE o desktop) viene registrata, così puoi distinguerle. +Ogni sessione Codex diventa una [sessione](/it/agenteye/sessions) di AgentEye; i suoi messaggi utente e assistente, il ragionamento, le chiamate ai tool, i risultati dei tool e l'utilizzo dei token diventano gli [eventi](/it/agenteye/event-stream) corrispondenti. La superficie da cui proviene ogni sessione (CLI, IDE o desktop) viene registrata, così puoi distinguerle. -> **Le sessioni cloud non vengono catturate.** L'app desktop esegue sempre più spesso le sessioni nel cloud Codex e mantiene solo i loro metadati sulla macchina — non c'è un trascritto locale da leggere. Solo le sessioni eseguite localmente vengono catturate. +> **Le sessioni cloud non vengono catturate.** L'app desktop esegue sempre più spesso sessioni nel cloud Codex e mantiene solo i loro metadati sulla macchina — non c'è alcun transcript locale da leggere. Solo le sessioni eseguite localmente vengono catturate. --- ## Attivalo -L'acquisizione è disabilitata finché non la abiliti. Installa il collettore con una chiave API che dispone del permesso `events:add` (vedi [Chiavi API](/it/agenteye/api-keys)), e attiva l'acquisizione di Codex: +L'acquisizione è disabilitata finché non la abiliti. Installa il collettore con una chiave API che ha il permesso `events:add` (vedi [Chiavi API](/it/agenteye/api-keys)), e attiva l'acquisizione Codex: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -Questo installa il collettore, lo registra come servizio in background e avvia l'acquisizione. Verifica che sia in esecuzione: +Questo installa il collettore, lo registra come servizio in background e inizia l'acquisizione. Conferma che è in esecuzione: ```bash agenteye-collector health ``` -Al primo avvio, le tue sessioni Codex esistenti vengono riprese una volta e la nuova attività quindi viene trasmessa in streaming in pochi secondi. I file di Codex vengono letti solo — mai modificati, spostati o eliminati — e ogni sessione viene inviata esattamente una volta, anche tra i riavvii. +Alla prima esecuzione, le tue sessioni Codex esistenti vengono ripopolate una volta e la nuova attività quindi viene trasmessa entro pochi secondi. I file di Codex stesso vengono letti solo — mai modificati, spostati o eliminati — e ogni sessione viene inviata esattamente una volta, anche attraverso i riavvii. --- -## Dove viene visualizzato +## Dove appare -Le sessioni catturate appaiono in **Sessions** e i loro eventi nel flusso **Events**, come per qualsiasi altro agente che osservi — quindi la [riproduzione delle sessioni](/it/agenteye/sessions), la [ricerca](/it/agenteye/queries), le [valutazioni](/it/agenteye/evaluations) e gli [avvisi](/it/agenteye/alerts) funzionano tutti su di esse. Filtra per l'agente Codex per vederle da sole. +Le sessioni catturate appaiono in **Sessions** e i loro eventi nel flusso **Events**, esattamente come qualsiasi altro agente che osservi — quindi [riproduzione sessione](/it/agenteye/sessions), [ricerca](/it/agenteye/queries), [valutazioni](/it/agenteye/evaluations) e [avvisi](/it/agenteye/alerts) funzionano tutti su di esse. Filtra per l'agente Codex per vederle da sole. --- ## Privacy -I trascritti di Codex contengono la sessione completa — incluso l'output dei comandi, i contenuti dei file e tutto ciò che Codex ha letto o scritto — e possono contenere segreti. Le sessioni catturate vengono inviate così come sono, quindi abilita l'acquisizione solo su macchine e per team dove centralizzare quel contenuto in AgentEye è appropriato, e dai al collettore una chiave ristretta a `events:add` solo. Vedi [Security](/it/agenteye/security) per vedere come i tuoi dati vengono mantenuti isolati. \ No newline at end of file +I transcript Codex contengono la sessione completa — incluso l'output del comando, i contenuti dei file e qualsiasi cosa Codex abbia letto o scritto — e possono contenere segreti. Le sessioni catturate vengono inviate così come sono, quindi abilita l'acquisizione solo su macchine e per team dove centralizzare quel contenuto in AgentEye è appropriato, e fornisci al collettore una chiave limitata a `events:add` soltanto. Vedi [Security](/it/agenteye/security) per come i tuoi dati vengono mantenuti isolati. \ No newline at end of file diff --git a/docs/it/agenteye/concepts.mdx b/docs/it/agenteye/concepts.mdx index 3517b456..2288dd02 100644 --- a/docs/it/agenteye/concepts.mdx +++ b/docs/it/agenteye/concepts.mdx @@ -4,84 +4,84 @@ description: "Il vocabolario dietro Failproof AI Observability — eventi, sessi --- -Questa pagina definisce il vocabolario usato da Failproof AI Observability. Se un termine in un'altra guida ti risulta sconosciuto, la sua definizione si trova qui. Non è necessario leggerla da cima a fondo: puoi scorrerla o tornare quando incontri una parola di cui vuoi precisare il significato. +Questa pagina definisce il vocabolario utilizzato da Failproof AI Observability. Se un termine in un'altra guida non ti è familiare, è definito qui. Non è necessario leggerla da capo a fondo: scorri velocemente o torna indietro quando incontri una parola che vuoi approfondire. --- -## Il modello dei dati +## Il modello di dati **Event** -L'unità più piccola di dati. Un event registra un singolo step che il tuo agente ha eseguito: un `tool_use`, una `model_request`, un `hook_completed`, un `error`, e così via. Il tuo agente emette event attraverso [Python SDK](/it/agenteye/python-sdk); vengono visualizzati in tempo reale nella pagina **Events**. +L'unità più piccola di dati. Un event registra un singolo passo che il tuo agent ha intrapreso: un `tool_use`, una `model_request`, un `hook_completed`, un `error`, e così via. Il tuo agent emette eventi attraverso l'[Python SDK](/it/agenteye/python-sdk); vengono visualizzati in tempo reale nella pagina **Events**. **Session** -Un'esecuzione dell'agente, identificata da un `session_id`. Una session è l'insieme di tutti gli event che condividono quell'id, riepilogati in una singola riga nella pagina **Sessions** e disegnati come grafo di esecuzione nella sua pagina di dettaglio. Una session solitamente inizia con `agent_start` e termina con `agent_end`. +Un'esecuzione di agent, identificata da un `session_id`. Una session è l'insieme di tutti gli eventi che condividono quell'id, riepilogati in un'unica riga nella pagina **Sessions** e disegnati come un grafo di esecuzione nella pagina dei dettagli. Una session di solito inizia con `agent_start` e termina con `agent_end`. **Agent** -Un attore nominato all'interno di un'esecuzione, identificato da un `agent_id`. Un'esecuzione può coinvolgere diversi agenti: ad esempio un planner che genera un sub-agente summarizer. I sub-agenti contengono un `parent_id`, che consente a Failproof AI Observability di disegnarli su corsie separate nel grafo di esecuzione. +Un attore denominato all'interno di un'esecuzione, identificato da un `agent_id`. Un'esecuzione può coinvolgere più agent: ad esempio un planner che genera un sub-agent di riepilogo. I sub-agent portano un `parent_id`, che è quello che consente a Failproof AI Observability di disegnarli su corsie separate nel grafo di esecuzione. **Environment** -Un'etichetta per il luogo dove l'esecuzione è avvenuta: `production`, `staging`, `dev`. La configuri una sola volta quando imposti l'SDK. Quasi tutte le pagine del dashboard possono filtrare per environment. +Un'etichetta per il luogo in cui è avvenuta l'esecuzione: `production`, `staging`, `dev`. La imposti una sola volta quando configuri l'SDK. Quasi tutte le pagine del dashboard possono filtrare per environment. **Context-window fill** -La percentuale della finestra di contesto di un modello che una risposta ha consumato. Failproof AI Observability la registra negli event `model_response` per i modelli che riconosce, in modo che la crescita del prompt e la imminente compattazione siano visibili direttamente nel flusso degli event. +La percentuale della finestra di contesto di un modello consumata da una risposta. Failproof AI Observability la registra negli event `model_response` per i modelli che riconosce, così la crescita del prompt e la compattazione imminente sono visibili direttamente nel flusso di eventi. --- ## Qualità **Evaluation** -Un punteggio di qualità per una session completata, prodotto da un servizio di scoring che gestisci. Le evaluation sono opzionali: finché non colleghi un evaluator, le session vengono registrate ma non valutate. Ogni evaluation può contenere diversi punteggi denominati (ad esempio `helpfulness`, `factuality`, `tool_efficiency`), ognuno con una breve nota di motivazione. Vedi [Evaluation suite](/it/agenteye/evaluation-suite). +Un punteggio di qualità per una session completata, prodotto da un servizio di scoring che gestisci. Le valutazioni sono facoltative: fino a quando non colleghi un valutatore, le session vengono registrate ma non valutate. Ogni evaluation può portare più punteggi nominati (ad esempio `helpfulness`, `factuality`, `tool_efficiency`), ciascuno con una breve nota di motivazione. Consulta [Evaluation suite](/it/agenteye/evaluation-suite). **Score key** -Il nome di una dimensione che un evaluator riporta, come `helpfulness`. Gli alert e gli audit possono monitorare uno score key specifico nel tempo. +Il nome di una dimensione che un valutatore segnala, come `helpfulness`. Gli alert e gli audit possono monitorare una score key specifica nel tempo. **Evaluator** -Il tuo servizio di scoring. Failproof AI Observability effettua un POST della trascrizione di un'esecuzione completata e memorizza i punteggi che restituisce. Non fornisce un evaluator predefinito; la logica di scoring è tua. +Il tuo servizio di scoring. Failproof AI Observability POST il trascritto di un'esecuzione completata e memorizza i punteggi che restituisce. Non dispone di un valutatore predefinito; la logica di scoring è tua. --- -## Trovare e risolvere i guasti +## Trovare e correggere gli errori **Hook** -Un guardrail o effetto collaterale che il tuo framework di agenti esegue attorno a uno step: un controllo di sicurezza dei contenuti, redazione della PII, un budget guard. Gli hook emettono event `hook_triggered` / `hook_completed` con un `outcome` (allow, deny, modify), e hanno una propria pagina di observe. +Una guardrail o un effetto collaterale che il tuo framework di agent esegue attorno a un passo: un controllo di sicurezza dei contenuti, una redazione PII, una guardia di budget. Gli hook emettono event `hook_triggered` / `hook_completed` con un `outcome` (allow, deny, modify) e hanno una propria pagina di observe. **Alert rule** -Una regola che si attiva quando una metrica supera una soglia che hai impostato: error rate, p95 latency, costo in token, o un punteggio di un evaluator. Quando una regola si attiva, apre un incident e notifica i tuoi canali scelti (email, Slack, webhook, in-dashboard). Vedi [Alerts](/it/agenteye/alerts). +Una regola che si attiva quando una metrica supera una soglia che imposti: tasso di errore, latenza p95, costo dei token, o un punteggio di valutatore. Quando una regola si attiva, apre un incidente e notifica i tuoi canali scelti (email, Slack, webhook, in-dashboard). Consulta [Alerts](/it/agenteye/alerts). **Incident** -Una questione aperta creata quando un'alert rule si attiva. Gli incident hanno un ciclo di vita (acknowledge, assign, resolve) e una timeline di attività che registra ogni azione. Puoi anche aprirne uno manualmente. +Un problema aperto creato quando una regola di alert si attiva. Gli incident hanno un ciclo di vita (acknowledge, assign, resolve) e una cronologia di attività che registra ogni azione. Puoi anche aprirne uno manualmente. **Audit** -Un'indagine ricorrente (oraria fino settimanale) che estrae dai tuoi log *tra* le session i pattern di guasto che non hai scritto una regola per: cluster di errori, punteggi bassi, outlier di latenza, loop di chiamate tool, ed esecuzioni che non sono mai terminate. Dove un alert monitora una metrica che già conosci, un audit ti dice cosa guardare dopo. Vedi [Audits](/it/agenteye/audits). +Un'indagine ricorrente (oraria o settimanale) che esamina i tuoi log *tra* session per cercare modelli di errore per i quali non hai scritto una regola: cluster di errori, punteggi bassi, outlier di latenza, loop di tool-call ed esecuzioni mai terminate. Mentre un alert monitora una metrica che conosci già, un audit ti dice cosa guardare dopo. Consulta [Audits](/it/agenteye/audits). **Finding** -Un risultato classificato e supportato da prove ottenuto da un'esecuzione di audit. Un finding nomina un pattern, si collega alle exact session dietro di esso, e ha un ciclo di vita di triage (acknowledge, resolve, mute, dismiss). Failproof AI Observability deduplica i finding di esecuzione in esecuzione così un pattern noto si aggiorna invece di accumularsi. +Un risultato classificato e supportato da prove da un'esecuzione di audit. Un finding nomina un modello, si collega alle sessioni esatte dietro, e ha un ciclo di vita di triage (acknowledge, resolve, mute, dismiss). Failproof AI Observability deduplica i finding da un'esecuzione all'altra in modo che un modello noto si aggiorni invece di accumularsi. -**The AI assistant** -La chat in-dashboard che risponde a domande sui tuoi agenti in linguaggio naturale, sui tuoi dati. È read-only per impostazione predefinita; qualsiasi cosa creer (una query salvata, un dashboard) è soggetta a approvazione, e non potrà mai eliminare. Vedi [AI assistant](/it/agenteye/assistant). +**L'assistente AI** +La chat nel dashboard che risponde a domande sui tuoi agent in linguaggio naturale, sui tuoi dati. È di sola lettura per impostazione predefinita; qualsiasi cosa crei (una query salvata, un dashboard) è controllata mediante approvazione, e non può mai eliminare. Consulta [AI assistant](/it/agenteye/assistant). --- ## Eseguirlo **Organization (tenant)** -Uno spazio di lavoro isolato. Un'istanza di Failproof AI Observability può ospitare molte organizzazioni, ognuna con i propri utenti, chiavi e dati. Ogni URL del dashboard è scoped sotto il tuo slugname dell'org (`//…`). +Uno spazio di lavoro isolato. Un'istanza di Failproof AI Observability può ospitare molte organizzazioni, ciascuna con i propri utenti, chiavi e dati. Ogni URL del dashboard è scoped sotto il tuo slug di organizzazione (`//…`). **Collector** -`agenteye-collector`, il daemon leggero che gira su ogni macchina con agenti, raggruppa gli event che l'SDK scrive su disco, e li spedisce al server. +`agenteye-collector`, il daemon leggero che viene eseguito su ogni macchina di agent, raggruppa gli eventi che l'SDK scrive su disco e li invia al server. **API key** -Un token scoped che autentica un client rispetto al server. Le chiavi portano permessi granulari (ad esempio `events:add` per il collector, scope read-only per una dashboard key). Vedi [API keys](/it/agenteye/api-keys). +Un token scoped che autentica un client rispetto al server. Le chiavi portano permessi granulari (ad esempio `events:add` per il collector, scope di sola lettura per una chiave dashboard). Consulta [API keys](/it/agenteye/api-keys). **Server** -Il servizio di ingest e API. Ingerisce gli event, memorizza lo stato operativo nei tuoi database, e serve il dashboard e la CLI. +Il servizio di ingest e API. Acquisisce gli eventi, memorizza lo stato operativo nei tuoi database e serve il dashboard e la CLI. **Dashboard** L'interfaccia web. Ogni pagina è scoped a un'organizzazione e legge attraverso l'API del server. --- -## Prossimi step +## Prossimi passi -- [Overview](/it/agenteye/overview): come questi pezzi si incastrano insieme. +- [Overview](/it/agenteye/overview): come questi componenti si incastrano insieme. - [Observability](/it/agenteye/observability): le superfici di observe (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file diff --git a/docs/it/agenteye/dashboards.mdx b/docs/it/agenteye/dashboards.mdx index 3bcac2a0..a6262803 100644 --- a/docs/it/agenteye/dashboards.mdx +++ b/docs/it/agenteye/dashboards.mdx @@ -1,46 +1,45 @@ --- title: "Dashboard" -description: "Trasforma i tuoi dati live degli agent in un'unica vista condivisa che tutto il team monitora." +description: "Trasforma i dati live dei tuoi agenti in un'unica visione condivisa che tutto il team monitora." --- +Trasforma i dati live dei tuoi agenti in un'unica visione condivisa che tutto il team monitora. Fissa le query che contano come grafici, e tutti vedono gli stessi numeri a colpo d'occhio, senza rieseguire nemmeno una query. -Trasforma i tuoi dati live degli agent in un'unica vista condivisa che tutto il team monitora. Fissa le query che contano come grafici, e tutti vedono gli stessi numeri a colpo d'occhio, senza rieseguire una singola query. +![Un dashboard costruito da query salvate: una linea eventi-per-ora, un istogramma errori-per-tipo, un grafico ad area latenza e token-per-modello](/agenteye/images/dashboard-fleet.png) -![Un dashboard creato da query salvate: una linea eventi-per-ora, un grafico a barre errori-per-tipo, un grafico ad area di latenza e token-per-modello](/agenteye/images/dashboard-fleet.png) +*Un dashboard, quattro query salvate: eventi per ora, errori per tipo, latenza e token per modello.* -*Una sola board, quattro query salvate: eventi per ora, errori per tipo, latenza e token per modello.* +## Tutti vedono la stessa verità -## Tutti vedono la stessa realtà +Smetti di incollare screenshot in chat e di rieseguire la stessa query cinque volte al giorno. Un dashboard è una bacheca condivisa a livello aziendale che chiunque nel tuo team può aprire per vedere esattamente la stessa visione. Quando i dati sottostanti cambiano, i grafici si muovono con loro, quindi il dashboard è sempre aggiornato e nessuno discute su numeri obsoleti. -Smetti di incollare screenshot in chat e smetti di rieseguire la stessa query cinque volte al giorno. Un dashboard è una board condivisa a livello organizzativo che chiunque nel tuo team può aprire per vedere esattamente la stessa vista. Quando i dati sottostanti cambiano, i grafici si muovono con loro, quindi la board è sempre aggiornata e nessuno discute su numeri obsoleti. +Il dashboard della flotta qui sopra è una buona base per le operazioni quotidiane: -Il fleet dashboard qui sopra è una buona forma iniziale per le operazioni quotidiane: - -- una linea **eventi-per-ora**, così puoi monitorare il throughput e catturare un calo improvviso -- un grafico a barre **errori-per-tipo**, così le tue maggiori categorie di fallimento spicchiano -- un grafico ad area **latenza**, così i rallentamenti emergono prima che gli utenti se ne lamentino -- una scomposizione **token-per-modello**, così i costi rimangono visibili +- una linea **eventi-per-ora**, così puoi monitorare il throughput e rilevare un calo improvviso +- un istogramma **errori-per-tipo**, così le tue categorie di errore più importanti risaltano subito +- un grafico ad area **latenza**, così i rallentamenti si notano prima che gli utenti si lamentino +- una ripartizione **token-per-modello**, così i costi rimangono in vista Troverai i tuoi dashboard su `//dashboards`. ## Fissa le query che hai già salvato -Ogni tile inizia come una query salvata. Costruisci e salva la query che ti interessa nella libreria [Query](/it/agenteye/queries) (preset incorporati più i tuoi, sui tuoi eventi e valutazioni), quindi fissala a un dashboard come il grafico che si adatta ai dati: una **linea** per le tendenze nel tempo, un **grafico a barre** per confrontare categorie, un **grafico ad area** per il volume, o una **torta** per una scomposizione percentuale. +Ogni tile inizia come una query salvata. Costruisci e salva la query che ti interessa nella libreria [Queries](/it/agenteye/queries) (preset incorporati più i tuoi, sui tuoi eventi e valutazioni), poi fissala a un dashboard come il grafico che si adatta ai dati: una **linea** per i trend nel tempo, un **istogramma** per confrontare categorie, un'**area** per il volume, o un **grafico a torta** per una ripartizione di quote. -Poiché una tile è solo la tua query salvata resa come grafico, non c'è nulla da sincronizzare manualmente. Aggiorna la query una volta e ogni dashboard che la utilizza si aggiorna automaticamente. +Poiché una tile è solo la tua query salvata renderizzata come grafico, non c'è nulla da mantenere sincronizzato manualmente. Aggiorna la query una volta e ogni dashboard che la usa si aggiorna automaticamente. ## Monitora la qualità, non solo il volume -Il volume ti dice che gli agent sono occupati. La qualità ti dice che stanno effettivamente svolgendo il lavoro. Punta un dashboard ai tuoi [punteggi di valutazione](/it/agenteye/evaluations) e ottieni una board che traccia quanto bene stanno andando le esecuzioni nel tempo, così una regressione di qualità appare come un calo su un grafico invece di una sorpresa da un cliente. +Il volume ti dice che gli agenti sono occupati. La qualità ti dice che stanno effettivamente svolgendo il lavoro. Punta un dashboard sui tuoi [punteggi di valutazione](/it/agenteye/evaluations) e otterrai una bacheca che traccia quanto bene procedono le esecuzioni nel tempo, così una regressione di qualità appare come un calo su un grafico invece di una sorpresa da un cliente. ![Un dashboard focalizzato sulla qualità costruito da query di valutazione salvate](/agenteye/images/dashboard-quality.png) -*Una board di qualità mantiene i tuoi punteggi di valutazione in primo piano, proprio accanto ai numeri operativi.* +*Un dashboard di qualità mantiene i tuoi punteggi di valutazione in primo piano, proprio accanto ai numeri operativi.* -Tieni una board di operazioni e una board di qualità affiancate e il tuo team ha un unico posto per rispondere sia a "sta funzionando?" che a "è buono?", senza che nessuno riesegua una query. +Tieni un dashboard di operazioni e un dashboard di qualità uno accanto all'altro e il tuo team ha un posto per rispondere sia a "funziona?" che a "è buono?", senza che nessuno riesegua una query. ## Correlati -- [Query](/it/agenteye/queries): costruisci e salva le query che diventano le tue tile. -- [Valutazioni](/it/agenteye/evaluations): valuta le tue esecuzioni così puoi tracciare la qualità nel tempo. -- [Avvisi](/it/agenteye/alerts): trasforma una soglia su una qualsiasi di queste metriche in un alert. \ No newline at end of file +- [Queries](/it/agenteye/queries): crea e salva le query che diventano le tue tile. +- [Evaluations](/it/agenteye/evaluations): valuta le tue esecuzioni così puoi tracciare la qualità nel tempo. +- [Alerts](/it/agenteye/alerts): trasforma una soglia su una qualsiasi di queste metriche in un avviso. \ No newline at end of file diff --git a/docs/it/agenteye/error-tracking.mdx b/docs/it/agenteye/error-tracking.mdx index 4fc1c271..2c11238a 100644 --- a/docs/it/agenteye/error-tracking.mdx +++ b/docs/it/agenteye/error-tracking.mdx @@ -1,41 +1,41 @@ --- title: "Tracciamento degli errori" -description: "Visualizza tutti gli errori prodotti dai tuoi agenti in un unico posto, raggruppati in modo che un picco caotico venga letto come un unico problema." +description: "Visualizza ogni errore prodotto dai tuoi agent in un unico posto, raggruppati in modo che un picco rumoroso si legga come un unico problema." --- -Visualizza tutti gli errori prodotti dai tuoi agenti in un unico posto, raggruppati in modo che un picco caotico venga letto come un unico problema. Hai un percorso con un solo clic da "qualcosa è rosso" all'esatto run che ha causato il problema, senza scorrere un feed in tempo reale per trovarlo. +Visualizza ogni errore prodotto dai tuoi agent in un unico posto, raggruppati in modo che un picco rumoroso si legga come un unico problema. Hai un percorso con un clic da "qualcosa è rosso" alla corsa esatta che si è rotta, senza dover scorrere un feed live per trovarlo. -![La pagina Errori: un istogramma degli errori nel tempo sopra righe di errore rosse raggruppate, ciascuna con un pulsante "+ alert" con un solo clic](/agenteye/images/errors.png) -*La pagina Errori: un istogramma degli errori nel tempo, con gli errori ripetuti compressi in una riga per incidente.* +![La pagina Errori: un istogramma dei guasti nel tempo sopra righe di errore rosse raggruppate, ognuna con un pulsante "+ alert" con un clic](/agenteye/images/errors.png) +*La pagina Errori: un istogramma dei guasti nel tempo, con i guasti ripetuti compressi in una riga per incidente.* ## Ogni errore, già raccolto per te -Quando un agente si interrompe, non dovresti doversi scorrere un flusso di eventi in tempo reale sperando di catturare le righe rosse prima che scompaiano. La pagina **Errors** fa la raccolta per te. Riunisce tutto ciò che il dashboard mostrebbe in rosso in un'unica superficie di triage, in modo che la prima cosa che vedi sia cosa sta fallendo, non dove cercare. +Quando un agent si interrompe, non dovresti dover scorrere un flusso di eventi live sperando di catturare le righe rosse prima che scompaiano. La pagina **Errors** fa la raccolta per te. Riunisce tutto ciò che il dashboard dipingerebbe di rosso in un'unica superficie di triage, quindi la prima cosa che vedi è ciò che non funziona, non dove andare a cercarlo. -E cattura più dei casi ovvi. Accanto agli eventi `error` espliciti, Failproof AI Observability evidenzia anche i fallimenti silenziosi: qualsiasi `tool_result`, `hook_completed` o `agent_end` il cui payload contiene un errore appare qui. Uno strumento che ha restituito un errore, o un hook che è uscito male, non sfugge più semplicemente perché nulla ha lanciato un'eccezione rumorosa. +E cattura più degli errori evidenti. Insieme agli eventi `error` espliciti, Failproof AI Observability emerge anche i guasti silenziosi: qualsiasi `tool_result`, `hook_completed`, o `agent_end` il cui payload contiene un guasto appare qui. Uno strumento che ha restituito un errore, o un hook che è uscito male, non ti sfugge più solo perché nulla ha lanciato un'eccezione rumorosa. -Nella parte superiore, un istogramma traccia gli errori nel tempo. Un'occhiata ti dice se si tratta di un flusso costante di fondo o di un picco iniziato pochi minuti fa, così sai subito se devi smettere quello che stai facendo. +In alto, un istogramma traccia gli errori nel tempo. Un'occhiata ti dice se si tratta di un gocciolamento costante di fondo o di un picco iniziato pochi minuti fa, quindi sai subito se devi smettere quello che stai facendo. -Come ogni superficie observe, la pagina Errors è limitata alla tua organizzazione e filtra per intervallo di date, ambiente, agente e sessione. Ciò significa che puoi prendere un elenco a livello di flotta e restringerlo all'agente o all'ambiente specifico di cui ti interessa. +Come ogni superficie di osservazione, la pagina Errors è definita nell'ambito della tua organizzazione e filtrata per intervallo di date, ambiente, agent e sessione. Ciò significa che puoi prendere un elenco a livello di flotta e restringerlo all'agent o all'ambiente specifico che effettivamente ti interessa. ## Un incidente, non cento righe identiche -Una singola dipendenza interrotta può attivare lo stesso errore centinaia di volte al minuto. Lasciato così com'è, è una parete di linee quasi identiche che nasconde l'unica cosa che devi effettivamente vedere. +Una singola dipendenza interrotta può innescare lo stesso errore centinaia di volte al minuto. Se lasciato così, è un muro di linee quasi identiche che seppellisce l'unica cosa che effettivamente devi vedere. -Failproof AI Observability comprime i fallimenti ripetuti che condividono la stessa sessione e tipo di errore in un'unica riga. Un picco viene letto come un incidente. Finisci per contare i problemi, non le righe di log, e il segnale che conta rimane in primo piano invece di essere annegato dal suo stesso volume. +Failproof AI Observability comprime i guasti ripetuti che condividono la stessa sessione e tipo di errore in una singola riga. Un picco si legge come un incidente. Finisci per contare i problemi, non le righe di log, e il segnale che conta rimane in primo piano invece di essere sommerso dal suo stesso volume. ## Da "qualcosa è rosso" all'evento esatto -Fai clic su qualsiasi riga per arrivare direttamente all'interno della sessione di quel run, posizionato sull'evento esatto che ha fallito. Nessuna copia di ID sessione, nessuno scorrimento per cercare il momento in cui è andato male: arrivi direttamente lì, con il grafico di esecuzione completo a un'occhiata di distanza in modo da poter vedere cosa ha fatto l'agente nei momenti prima che si interrompesse. +Fai clic su qualsiasi riga per atterrare direttamente dentro la sessione della corsa, posizionato sull'evento esatto che si è guastato. Nessuna copia di ID di sessione, nessuno scorrimento per cercare il momento in cui è andato storto: arrivi proprio lì, con il grafico di esecuzione completo a un'occhiata di distanza in modo che tu possa vedere cosa ha fatto l'agent nei momenti prima che si rompesse. -Se hai `alerts:write`, ogni riga ha anche un pulsante **+ alert**. Fai clic e Observability apre una nuova regola di avviso già compilata per catturare lo stesso errore di nuovo. L'incidente che hai appena esaminato diventa quello che ti avviserà la prossima volta, invece di sorprenderti due volte. +Se hai `alerts:write`, ogni riga ha anche un pulsante **+ alert**. Fai clic su di esso e Observability apre una nuova regola di avviso già compilata per catturare lo stesso errore di nuovo. L'incidente che hai appena triato diventa quello che ti avvisa la prossima volta, invece di sorprenderti due volte. -**Dove trovarlo:** la pagina **Errors** si trova nella sezione observe del dashboard, a `//errors`. +**Dove trovarlo:** la pagina **Errors** si trova nella sezione observe del dashboard, in `//errors`. ## Correlati -- [Alerts](/it/agenteye/alerts): trasforma qualsiasi errore in una regola di paging. -- [Incidents](/it/agenteye/incidents): monitora un avviso attivo da apertura a risoluzione. -- [Sessions](/it/agenteye/sessions): apri il run completo dietro qualsiasi errore. -- [Audits](/it/agenteye/audits): lascia che Observability trovi i pattern di errore nei tuoi run per te. \ No newline at end of file +- [Alerts](/it/agenteye/alerts): trasforma qualsiasi guasto in una regola di paging. +- [Incidents](/it/agenteye/incidents): traccia un avviso attivato dall'apertura alla risoluzione. +- [Sessions](/it/agenteye/sessions): apri la corsa completa dietro qualsiasi errore. +- [Audits](/it/agenteye/audits): lascia che Observability trovi pattern di guasto nelle tue corse per te. \ No newline at end of file diff --git a/docs/it/agenteye/evaluation-suite.mdx b/docs/it/agenteye/evaluation-suite.mdx index 2d4c900c..c027fe2b 100644 --- a/docs/it/agenteye/evaluation-suite.mdx +++ b/docs/it/agenteye/evaluation-suite.mdx @@ -1,21 +1,22 @@ --- -title: "Suite di valutazione" -description: "Failproof AI Observability può valutare automaticamente ogni esecuzione di agent completata per la qualità: tu fornisci un piccolo servizio di scoring e Observability gestisce il resto." +title: "Suite di Valutazione" +description: "Failproof AI Observability può valutare automaticamente ogni esecuzione di agente completata per la qualità: fornisci un piccolo servizio di scoring e Observability gestisce il resto." --- -Failproof AI Observability può valutare automaticamente ogni esecuzione di agent completata per la qualità: tu fornisci un piccolo servizio di scoring e Observability gestisce il resto. Usalo per tracciare le dimensioni che ti interessano (utilità, efficienza degli strumenti, fattualità, sicurezza; scegli tu), rilevare regressioni in anticipo e confrontare agent o ambienti a colpo d'occhio. Lo scoring è facoltativo: la pipeline non fa nulla finché non imposti `EVALUATOR_ENDPOINT` sul server. -> **Nota:** Tu definisci le dimensioni del punteggio. Il tuo valutatore può restituire qualsiasi chiave numerica desideri; Observability memorizza, tende alla tendenza e visualizza tutto quello che invii. +Failproof AI Observability può valutare automaticamente ogni esecuzione di agente completata per la qualità: fornisci un piccolo servizio di scoring e Observability gestisce il resto. Usalo per tracciare le dimensioni che ti interessano (helpfulness, tool efficiency, factuality, safety; scegli tu), rilevare regressioni tempestivamente e confrontare agenti o ambienti a colpo d'occhio. Lo scoring è facoltativo: la pipeline non fa nulla finché non imposti `EVALUATOR_ENDPOINT` sul server. -## In sintesi +> **Nota:** Definisci tu le dimensioni del punteggio. Il tuo evaluator può restituire qualsiasi chiave numerica desideri; Observability archivia, crea trend e visualizza tutto ciò che invii. -1. **Scrivi uno scorer.** Crea un piccolo servizio HTTP che legge una trascrizione della sessione e restituisce i punteggi. Observability fornisce un riferimento funzionante che puoi copiare. Vedi [Scrivere un valutatore con l'SDK](#writing-an-evaluator-with-the-sdk). -2. **Punta Observability su di esso.** Imposta `EVALUATOR_ENDPOINT` (e un `EVALUATOR_TOKEN` condiviso) sul processo server. +## A colpo d'occhio + +1. **Scrivi uno scorer.** Configura un piccolo servizio HTTP che legge una trascrizione della sessione e restituisce i punteggi. Observability include un riferimento funzionante che puoi copiare. Vedi [Scrittura di un evaluator con l'SDK](#writing-an-evaluator-with-the-sdk). +2. **Punta Observability a esso.** Imposta `EVALUATOR_ENDPOINT` (e un `EVALUATOR_TOKEN` condiviso) sul processo del server. 3. **Guarda i punteggi arrivare.** Ogni sessione completata viene valutata automaticamente; i risultati appaiono nella pagina dei dettagli della sessione, nella griglia delle sessioni e nei dashboard salvati. -![Una vista dettaglio della sessione con il riepilogo della valutazione, barre dei punteggi per dimensione e testo di ragionamento nella barra laterale destra](/agenteye/images/session-detail.png) +![Una vista dettagliata della sessione con il riepilogo della valutazione, barre dei punteggi per dimensione e testo di ragionamento nella barra laterale destra](/agenteye/images/session-detail.png) -*Una volta configurato un valutatore, ogni esecuzione completata viene valutata e i risultati appaiono nella barra laterale destra della sessione: il riepilogo in alto, poi barre dei punteggi per dimensione con ragionamento.* +*Una volta configurato un evaluator, ogni esecuzione completata viene valutata e i risultati appaiono nella barra laterale destra della sessione: il riepilogo in alto, quindi barre dei punteggi per dimensione con ragionamento.* --- @@ -31,39 +32,71 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Quando l'SDK di Observability emette un evento `agent_end` per una sessione, il server pianifica una valutazione. Quindi invia un POST della trascrizione completa degli eventi al tuo servizio di valutazione, che può: - -- **Restituire il risultato inline** con `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Il risultato viene aggiunto alla timeline di valutazione della sessione. `reasoning` e `summary` sono facoltativi. -- **Rimandare** con `{"status":"pending", "job_id":"abc-123"}`. Observability poi chiama `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` finché il tuo valutatore non restituisce `{"status":"done", ...}` o `{"status":"error", "error":"..."}`. - - La cadenza di polling è per job: una risposta `pending` può includere `next_poll_secs` per sovrascrivere; altrimenti Observability usa il valore `default_poll_interval_secs` da `GET /config`; altrimenti il server ricade su `EVALUATOR_POLLING_INTERVAL_SECS` (default 10s). Tutti i valori sono limitati a [1s, 1h]. - -Anche le sessioni che non emettono mai `agent_end` (ad esempio, un processo agent che si è bloccato) possono essere rilevate: il `GET /config` del valutatore può restituire `{"inactivity_timeout_secs": 1800}`, e Observability valuterà qualsiasi sessione rimasta inattiva per quel tempo. Imposta il campo a `null` oppure omettilo per disabilitare questo fallback. - -La pipeline è completamente non operativa quando `EVALUATOR_ENDPOINT` non è impostato. - -Una sessione può accumulare **più valutazioni terminali nel tempo**: ogni evento `agent_end` (e ogni rivalutazione manuale dal dashboard) aggiunge una riga di valutazione nuova. Questo è il modo supportato per valutare una conversazione ripresa: un utente termina un agent, ritorna più tardi, invia altri eventi, termina di nuovo l'agent, e viene eseguita una seconda valutazione sulla trascrizione completa aggiornata. Il dashboard rende la valutazione più recente come titolo principale e le valutazioni precedenti come timeline collapsible. Mentre una valutazione è in esecuzione per una sessione, gli ulteriori eventi `agent_end` per quella sessione vengono ignorati; il prossimo dopo il completamento della valutazione in esecuzione metterà in coda una nuova valutazione come al solito. - -Il fallback di inattività si riattiva anche nelle sessioni riprese: se arrivano nuovi eventi dopo una precedente valutazione terminale e la sessione poi rimane inattiva oltre `inactivity_timeout_secs`, una nuova valutazione viene messa in coda. - -I guasti transitori (5xx, 429, timeout, errori di rete) vengono ritentati con backoff esponenziale fino a `EVALUATOR_MAX_ATTEMPTS`; le risposte 4xx sono terminali. Observability è sicuro da eseguire con più istanze di server scalate orizzontalmente; il lavoro è partizionato in modo che la stessa sessione non venga mai inviata due volte contemporaneamente. +Quando l'SDK Failproof AI Observability emette un evento `agent_end` per una sessione, il server +pianifica una valutazione. Quindi invia in POST la trascrizione dell'evento completo al tuo +servizio evaluator, che può: + +- **Restituire il risultato inline** con `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Il + risultato viene aggiunto alla timeline di valutazione della sessione. `reasoning` e + `summary` sono opzionali. +- **Rimandare** con `{"status":"pending", "job_id":"abc-123"}`. Observability quindi + chiama `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` finché il tuo evaluator + non restituisce `{"status":"done", ...}` o `{"status":"error", "error":"..."}`. + + La cadenza di polling è per-job: una risposta `pending` può includere + `next_poll_secs` per sovrascrivere; altrimenti Observability usa il + valore `default_poll_interval_secs` da `GET /config`; altrimenti il server + ricade su `EVALUATOR_POLLING_INTERVAL_SECS` (default 10s). Tutti i valori + sono limitati a [1s, 1h]. + +Le sessioni che non emettono mai `agent_end` (ad esempio, un processo agente bloccato) +possono anche essere riprese: la `GET /config` dell'evaluator può restituire +`{"inactivity_timeout_secs": 1800}`, e Observability valuterà qualsiasi sessione +rimasta inattiva per quel tempo. Imposta il campo su `null` oppure omettilo per +disabilitare questo fallback. + +La pipeline è completamente no-op quando `EVALUATOR_ENDPOINT` non è impostato. + +Una sessione può accumulare **più valutazioni terminali nel tempo**: ogni +evento `agent_end` (e ogni re-eval manuale dal dashboard) aggiunge una +nuova riga di valutazione. Questo è il modo supportato per valutare una conversazione +ripresa: un utente termina un agente, torna più tardi, invia altri eventi, +termina di nuovo l'agente, e una seconda valutazione viene eseguita sulla trascrizione completa aggiornata. Il dashboard visualizza la valutazione più recente come +titolo e le valutazioni precedenti come una timeline comprimibile. Mentre una +valutazione è in esecuzione per una sessione, gli ulteriori eventi `agent_end` per quella +sessione vengono ignorati; il successivo dopo il completamento della valutazione in esecuzione +entra in coda per una valutazione nuova come al solito. + +Il fallback di inattività si riattiva anche su sessioni riprese: se nuovi eventi +arrivano dopo una precedente valutazione terminale e la sessione poi rimane inattiva +oltre `inactivity_timeout_secs`, una nuova valutazione viene messa in coda. + +I guasti transitori (5xx, 429, timeout, errori di rete) vengono ritentati con +backoff esponenziale fino a `EVALUATOR_MAX_ATTEMPTS`; le risposte 4xx sono +terminali. Observability è sicuro per l'esecuzione con più istanze del server ridimensionate orizzontalmente; il lavoro +viene partizionato in modo che la stessa sessione non sia mai inviata +due volte contemporaneamente. --- ## Contratto HTTP -Ogni rotta autenticata usa **autenticazione bearer token**. Lo stesso valore deve essere configurato su entrambi i lati: +Ogni rotta autenticata utilizza **autenticazione bearer token**. Lo stesso valore deve essere +configurato su entrambi i lati: - Server Observability: variabile di ambiente `EVALUATOR_TOKEN` -- Servizio di valutazione: configurato allo stesso modo (l'SDK `agenteye-evaluator` legge `EVALUATOR_TOKEN` per convenzione) +- Servizio evaluator: configurato nello stesso modo (l'SDK `agenteye-evaluator` + legge `EVALUATOR_TOKEN` per convenzione) -Se `EVALUATOR_TOKEN` non è impostato, il server non invia l'header `Authorization`; il valutatore può quindi accettare richieste anonime, il che va bene per una rete interna ma è sconsigliato su internet pubblico. +Se `EVALUATOR_TOKEN` non è impostato, il server non invia un header `Authorization`; l' +evaluator può quindi accettare richieste anonime, il che va bene per una +rete solo interna ma sconsigliato su internet pubblico. -### Rotte che il valutatore deve servire +### Rotte che l'evaluator deve servire -| Rotta | Body / params | Risposta | +| Rotta | Body / parametri | Risposta | |---|---|---| -| `GET /health` | nessuno | `{"status":"ok"}` (aperto, nessuna autenticazione) | +| `GET /health` | nessuno | `{"status":"ok"}` (aperta, nessuna autenticazione) | | `GET /config` | nessuno | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omesso}` | | `POST /evaluate` | JSON `EvalRequest` | `{"status":"done", ...}` o `{"status":"pending", "job_id":"..."}` | | `GET /evaluate/{id}` | nessuno | stessa forma di risposta di `/evaluate` | @@ -87,7 +120,7 @@ Se `EVALUATOR_TOKEN` non è impostato, il server non invia l'header `Authorizati ### Forme di risposta -**Sincrona (done):** +**Sincrono (done):** ```json { @@ -101,33 +134,46 @@ Se `EVALUATOR_TOKEN` non è impostato, il server non invia l'header `Authorizati } ``` -`reasoning` (una mappa di giustificazione per punteggio) e `summary` (una narrazione complessiva di un paragrafo) sono entrambi facoltativi. Le chiavi in `reasoning` dovrebbero specchiare le chiavi in `scores`; il dashboard rende ogni voce in linea sotto la sua barra dei punteggi. I valutatori più vecchi che restituiscono solo `scores` continuano a funzionare senza modifiche; `reasoning` e `summary` semplicemente leggono come null e le corrispondenti funzioni UI sono omesse. +`reasoning` (una mappa di giustificazione per punteggio) e `summary` (un +narrativo complessivo di un paragrafo) sono entrambi opzionali. Le chiavi in `reasoning` dovrebbero +rispecchiare le chiavi in `scores`; il dashboard visualizza ogni voce inline sotto +la sua barra di punteggio. Gli evaluator più vecchi che restituiscono solo `scores` continuano a +funzionare senza modifiche; `reasoning` e `summary` semplicemente leggono come null e +le corrispondenti affordances dell'UI vengono omesse. -**Asincrona (rimanda):** +**Asincrono (rimandato):** ```json { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` è facoltativo; se omesso il server ricade su `default_poll_interval_secs` del valutatore da `/config`, poi su la propria variabile di ambiente `EVALUATOR_POLLING_INTERVAL_SECS`. +`next_poll_secs` è opzionale; se omesso il server ricade su +`default_poll_interval_secs` dell'evaluator da `/config`, poi su +`EVALUATOR_POLLING_INTERVAL_SECS` della sua variabile di ambiente. -**Errore terminale lato valutatore:** +**Errore terminale lato evaluator:** ```json { "status": "error", "error": "model service unavailable" } ``` -Il server tratta qualsiasi altro body 2xx come un errore di protocollo e registra un `error` terminale per la sessione. +Il server tratta qualsiasi altro body 2xx come un errore di protocollo e registra un +`error` terminale per la sessione. --- -## Scrivere un valutatore con l'SDK +## Scrittura di un evaluator con l'SDK -Non devi implementare il contratto HTTP a mano. Il pacchetto Python `agenteye-evaluator` ti fornisce un wrapper FastAPI tipizzato che gestisce l'autenticazione, il routing e le forme di richiesta/risposta per te. +Non devi implementare il contratto HTTP manualmente. Il pacchetto Python `agenteye-evaluator` +ti fornisce un wrapper FastAPI tipizzato che gestisce l'autenticazione, il routing e +le forme di richiesta/risposta per te. -Failproof AI Observability fornisce anche un **valutatore di riferimento funzionante** che valuta `helpfulness`, `tool_efficiency` e `factuality` dalla forma della trascrizione. Copialo come punto di partenza e sostituisci la tua logica: un giudice LLM, un motore di regole, qualsiasi cosa si adatti al tuo standard di qualità. +Failproof AI Observability include anche un **evaluator di riferimento funzionante** che +valuta `helpfulness`, `tool_efficiency` e `factuality` dalla forma della +trascrizione. Copialo come punto di partenza e sostituisci con la tua logica: un +judge LLM, un motore di regole, quello che si adatta al tuo standard di qualità. -Valutatore minimo praticabile: +Evaluator minimo vitale: ```python import os @@ -137,7 +183,7 @@ app = Evaluator(token=os.environ["EVALUATOR_TOKEN"]) @app.evaluator def run(req: EvalRequest) -> EvalResponse: - # Inspect req.events (the full session transcript) and return scores. + # Ispeziona req.events (la trascrizione della sessione completa) e restituisci i punteggi. tool_calls = sum(1 for e in req.events if e.event_type == "tool_use") return EvalResponse( scores={"tool_calls": float(tool_calls)}, @@ -146,88 +192,107 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -L'istanza `app` gira sotto qualsiasi server ASGI, così `uvicorn module:app` lo avvia. +L'istanza `app` viene eseguita in qualsiasi server ASGI, quindi `uvicorn module:app` lo avvia. -Per i valutatori che devono rimandare lavoro costoso, restituisci `JobPending` e registra un gestore `@app.job_lookup`; il server Observability polling `GET /evaluate/{job_id}` finché non restituisci uno stato terminale o il cap `EVALUATOR_MAX_POLL_DURATION_SECS` (default 1 h) trascorre. +Per evaluator che devono rimandare lavori costosi, restituisci `JobPending` +invece e registra un handler `@app.job_lookup`; il server Observability +esegue il polling `GET /evaluate/{job_id}` finché non restituisci uno status terminale o non trascorre il +limite `EVALUATOR_MAX_POLL_DURATION_SECS` (default 1 h). -Il riferimento API completo, il modello asincrono e lo schema degli eventi sono documentati nel README dell'SDK `agenteye-evaluator`. +L'API reference completa, il pattern asincrono e lo schema degli eventi sono documentati nel +README dell'SDK `agenteye-evaluator`. --- -## Eseguire il tuo valutatore +## Esecuzione del tuo evaluator -Il valutatore è **il tuo servizio** — Failproof AI Observability non fornisce un valutatore predefinito, quindi lo crei e lo esegui dove esegui i tuoi servizi. Viene eseguito sotto qualsiasi server ASGI (ad esempio `uvicorn my_evaluator:app`); servi le rotte `/health`, `/config` e `/evaluate` dal [contratto HTTP](#http-contract), poi punta il server su di esso (vedi [Configurare il server](#configuring-the-server)). +L'evaluator è **il tuo servizio** — Failproof AI Observability non include un +evaluator predefinito, quindi lo costruisci ed esegui dove esegui i tuoi servizi. +Viene eseguito in qualsiasi server ASGI (ad esempio `uvicorn my_evaluator:app`); servi +le rotte `/health`, `/config` e `/evaluate` dal +[contratto HTTP](#http-contract), poi punta il server a esso (vedi +[Configurazione del server](#configuring-the-server)). -Una volta che il valutatore è raggiungibile, `GET /health` restituisce `{"status":"ok"}`. Dopo che un agent viene eseguito end-to-end, `GET /evaluations` sul server restituisce una riga con `status: "done"` e i punteggi prodotti dal tuo valutatore. +Una volta che l'evaluator è raggiungibile, `GET /health` restituisce `{"status":"ok"}`. Dopo +che un agente viene eseguito end-to-end, `GET /evaluations` sul server restituisce una riga con +`status: "done"` e i punteggi prodotti dal tuo evaluator. --- -## Configurare il server +## Configurazione del server -Imposta sul processo server: +Imposta sul processo del server: | Variabile di ambiente | Significato | |---|---| -| `EVALUATOR_ENDPOINT` | URL di base del tuo valutatore (`http://evaluator:9000`). Non impostato = pipeline disabilitata. | -| `EVALUATOR_TOKEN` | Bearer token. Deve essere uguale al valore con cui è configurato il servizio di valutazione. | -| `EVALUATOR_WORKERS` | Attività worker per istanza di server (default 2). | -| `EVALUATOR_CLAIM_BATCH` | Righe rivendicate per tick di worker (default 4). I batch vengono elaborati **contemporaneamente**; la concorrenza effettiva sul tuo endpoint di valutazione è `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Quanto a lungo un worker dorme tra i tentativi di invio quando nessuna valutazione è dovuta (default 2s). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Fallback finale per la cadenza `GET /evaluate/{id}` quando né il `next_poll_secs` per risposta né il `default_poll_interval_secs` del valutatore è impostato (default 10s). | +| `EVALUATOR_ENDPOINT` | URL di base del tuo evaluator (`http://evaluator:9000`). Non impostato = pipeline disabilitata. | +| `EVALUATOR_TOKEN` | Bearer token. Deve corrispondere al valore configurato nel servizio evaluator. | +| `EVALUATOR_WORKERS` | Attività worker per istanza del server (default 2). | +| `EVALUATOR_CLAIM_BATCH` | Righe rivendicate per tick worker (default 4). I batch vengono elaborati **contemporaneamente**; la concorrenza effettiva nell'endpoint evaluator è `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Quanto tempo un worker dorme tra i tentativi di dispatch quando nessuna valutazione è dovuta (default 2s). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Fallback finale per la cadenza `GET /evaluate/{id}` quando né `next_poll_secs` per risposta né `default_poll_interval_secs` dell'evaluator è impostato (default 10s). | | `EVALUATOR_REQUEST_TIMEOUT_MS` | Timeout per richiesta (default 30000). | | `EVALUATOR_MAX_ATTEMPTS` | Dopo questo numero di guasti transitori il risultato viene registrato come `error` terminale (default 5). | | `EVALUATOR_CONFIG_REFRESH_SECS` | Cadenza `GET /config` (default 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Tempo massimo da parete che una sessione può rimanere nella coda di polling prima di essere terminata come `timeout` (default 3600s). Protegge contro un valutatore che continua a restituire `pending` per sempre. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Tempo massimo di wallclock che una sessione può rimanere nella coda di polling prima di essere terminata come `timeout` (default 3600s). Protegge da un evaluator che continua a restituire `pending` per sempre. | -Per attivare lo scoring automatico, imposta sia `EVALUATOR_ENDPOINT` che `EVALUATOR_TOKEN` sul server, quindi riavvialo per applicare le modifiche. Con `EVALUATOR_ENDPOINT` non impostato la pipeline rimane non operativa. +Per attivare lo scoring automatico, imposta sia `EVALUATOR_ENDPOINT` che +`EVALUATOR_TOKEN` sul server, quindi riavvialo per applicare il cambiamento. Con +`EVALUATOR_ENDPOINT` non impostato la pipeline rimane no-op. -I pulsanti di regolazione sopra sono facoltativi; imposta le variabili di ambiente corrispondenti sul server solo se hai bisogno di sovrascrivere i default. +I knob di tuning sopra sono opzionali; imposta le corrispondenti variabili di ambiente +sul server solo se hai bisogno di sovrascrivere i default. --- -## Riferimento API +## API reference | Metodo | Percorso | Permesso richiesto | Scopo | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Interrogare i risultati terminali. Supporta `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` di default è 50 ed è limitato a 200 (nota che questo differisce da `/events`, che ha limite a 1000). `environment` accetta un elenco separato da virgole (ad es. `environment=prod,staging`); i valori singoli funzionano ancora. Con `latest_per_session=true` la risposta contiene al massimo una riga per `session_id` (la più recente per `completed_at`) usata dalla pagina dell'elenco sessioni per collassare la timeline di valutazione di una sessione al suo titolo corrente. Default false (restituisce la cronologia completa). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | Salute eval riepilogata per una sezione filtrata: conteggio totale, disaggregazione done/error/timeout, statistiche per chiave di punteggio (count/avg/min/max/p50 sulle chiavi `scores` arbitrarie), e una timeline con bucket temporale. Accetta **gli stessi parametri di filtro di `/evaluations`** più `featured_keys` (CSV di chiavi di punteggio da tracciare) e `latest_per_session`. Potenzia la funzione Dashboards; le metriche sono esatte su tutto il set di corrispondenza, non campionate. | -| `GET` | `/evaluations/environments` | `evaluations:read` | Valori di ambiente distinti dalla tabella `evaluations`. Usato per popolare i dropdown dei filtri scoped ai dati leggibili dalla valutazione. | +| `GET` | `/evaluations` | `evaluations:read` | Query dei risultati terminali. Supporta `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` ha default 50 ed è limitato a 200 (nota che differisce da `/events`, che limita a 1000). `environment` accetta una lista separata da virgole (ad es. `environment=prod,staging`); i singoli valori continuano a funzionare. Con `latest_per_session=true` la risposta contiene al massimo una riga per `session_id` (la più recente per `completed_at`) utilizzata dalla pagina della lista sessioni per comprimere la timeline di valutazione di una sessione al suo titolo corrente. Default false (restituisce la cronologia completa). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | Salute della valutazione riepilogata per una sezione filtrata: conteggio totale, ripartizione done/error/timeout, statistiche per chiave di punteggio (count/avg/min/max/p50 sulle chiavi `scores` arbitrarie), e una timeline con bucket di tempo. Accetta **gli stessi parametri di filtro di `/evaluations`** più `featured_keys` (CSV delle chiavi di punteggio da tracciare) e `latest_per_session`. Potenzia la funzionalità Dashboards; le metriche sono esatte sull'intero set corrispondente, non campionate. | +| `GET` | `/evaluations/environments` | `evaluations:read` | Valori di environment distinti dalla tabella `evaluations`. Utilizzato per popolare i dropdown di filtro limitati ai dati leggibili per valutazione. | | `GET` | `/evaluation-jobs` | `evaluations:read` | Visibilità nelle valutazioni in corso. Filtra per `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | Trasmetti gli eventi raw di una sessione. Supporta `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` e `order`. `order` è `desc` (più recente per primo, il default) o `asc` (più vecchio per primo); un valore non riconosciuto ricade a `desc`. Pagina con cursore tramite il `next_cursor` della risposta (un id evento): passalo come `cursor` per ottenere la pagina successiva; con `asc` la pagina successiva è gli eventi dopo quell'id, con `desc` gli eventi prima di esso. `limit` di default è 50 ed è limitato a 1000. | -| `GET` | `/sessions/:session_id/export` | `events:read` | Restituisce il body JSON esatto che il valutatore riceverebbe per questa sessione, servito come allegato scaricabile nominato `session-.json`. Utile per riprodurre sessioni di produzione attraverso `agenteye-evaluator` per test offline. I byte sono byte-identici a quello che la pipeline del valutatore invia. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Metti in coda una nuova valutazione per una sessione; viene eseguita indipendentemente dal fatto che una valutazione precedente esista. Il nuovo risultato è **aggiunto** alla timeline di valutazione della sessione anziché sovrascrivere quella precedente, quindi i punteggi precedenti rimangono visibili come cronologia. Restituisce `202` in coda, `404` per una sessione sconosciuta, `409` se una valutazione è già in corso. Usa questo dopo aver distribuito un nuovo valutatore, o per sessioni che non hanno mai emesso `agent_end`. | +| `GET` | `/events` | `events:read` | Trasmetti gli eventi grezzi di una sessione. Supporta `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` e `order`. `order` è `desc` (più recente per primo, il default) o `asc` (più vecchio per primo); un valore non riconosciuto ricade su `desc`. Pagina tramite cursore usando la `next_cursor` della risposta (un id evento): ritornala come `cursor` per ottenere la pagina successiva; con `asc` la pagina successiva è gli eventi dopo quell'id, con `desc` gli eventi prima di esso. `limit` ha default 50 ed è limitato a 1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | Restituisce il corpo JSON esatto che l'evaluator riceverebbe per questa sessione, servito come allegato scaricabile denominato `session-.json`. Utile per riprodurre sessioni di produzione attraverso `agenteye-evaluator` per test offline. I byte sono identici a byte a ciò che invia la pipeline dell'evaluator. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Accoda una valutazione nuova per una sessione; viene eseguita indipendentemente dal fatto che una valutazione precedente esista. Il nuovo risultato viene **aggiunto** alla timeline di valutazione della sessione piuttosto che sovrascrivere quello precedente, quindi i punteggi precedenti rimangono visibili come cronologia. Restituisce `202` in accodamento, `404` per una sessione sconosciuta, `409` se una valutazione è già in corso. Usalo dopo aver distribuito un nuovo evaluator, o per sessioni che non hanno mai emesso `agent_end`. | -### Filtrare per intervallo di punteggi: `score_filters` +### Filtro per intervallo di punteggio: `score_filters` -`GET /evaluations` accetta un parametro `score_filters` facoltativo che restringe i risultati per valori numerici dentro l'oggetto `scores`. Il parametro è un elenco separato da virgole di voci `key:min..max`; entrambi i limiti possono essere omessi. Più voci si combinano con AND logico. Le righe dove la chiave denominata è assente o non numerica sono escluse. Una richiesta può portare al massimo 20 voci di filtro; superare questo restituisce HTTP 400. +`GET /evaluations` accetta un parametro opzionale `score_filters` che +restringe i risultati in base ai valori numerici all'interno dell'oggetto `scores`. Il +parametro è una lista separata da virgole di voci `key:min..max`; uno dei due +limiti può essere omesso. Più voci si combinano con AND logico. Le righe +dove la chiave denominata è assente o non numerica vengono escluse. Una richiesta può +contenere al massimo 20 voci di filtro; superare questo restituisce HTTP 400. Esempi: ```text # helpfulness in [0.5, 0.8] GET /evaluations?score_filters=helpfulness:0.5..0.8 -# tool_efficiency at most 0.3 (no lower bound) +# tool_efficiency al massimo 0.3 (nessun limite inferiore) GET /evaluations?score_filters=tool_efficiency:..0.3 # helpfulness >= 0.5 AND factuality >= 0.9 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` -Ogni oggetto di risposta `/evaluations` ha questi campi: +Ogni oggetto risposta `/evaluations` ha questi campi: | Campo | Tipo | Note | |---|---|---| -| `evaluation_id` | string (UUID) | L'identificatore canonico per questa valutazione terminale. Ogni valutazione terminale ottiene un nuovo UUID; una singola sessione può contenerne più di uno. | -| `id` | string (UUID) | Alias di retrocompatibilità con lo stesso valore di `evaluation_id`. | -| `session_id` | string | La sessione su cui è stata eseguita questa valutazione. Una sessione può avere più valutazioni nella timeline. | -| `agent_id` | string | Identifica l'agent che ha prodotto la sessione. | -| `environment` | string | Etichetta di ambiente copiata dalla sessione. | +| `evaluation_id` | string (UUID) | L'identificatore canonico per questa valutazione terminale. Ogni valutazione terminale ottiene un nuovo UUID; una singola sessione può contenerne più. | +| `id` | string (UUID) | Alias di retrocompatibilità che porta lo stesso valore di `evaluation_id`. | +| `session_id` | string | La sessione su cui questa valutazione è stata eseguita. Una sessione può avere più valutazioni nella timeline. | +| `agent_id` | string | Identifica l'agente che ha prodotto la sessione. | +| `environment` | string | Etichetta di environment copiata dalla sessione. | | `status` | enum | Uno di `"done"`, `"error"`, `"timeout"`. | -| `scores` | object \| null | Punteggi restituiti dal tuo valutatore. | -| `reasoning` | object \| null | Mappa di giustificazione facoltativa per punteggio restituita dal tuo valutatore. Le chiavi tipicamente specchiano quelle in `scores`. Il dashboard rende ogni voce sotto la sua barra dei punteggi. | -| `summary` | string \| null | Narrazione complessiva facoltativa di un paragrafo restituita dal tuo valutatore. Il dashboard rende questo sopra la disaggregazione per punteggio come titolo della valutazione. | -| `error` | string \| null | Popolato solo su `"error"` / `"timeout"`. | -| `attempt_count` | integer | Numero di tentativi di invio (≥ 1). | +| `scores` | object \| null | Punteggi restituiti dal tuo evaluator. | +| `reasoning` | object \| null | Mappa facoltativa di giustificazione per punteggio restituita dal tuo evaluator. Le chiavi generalmente rispecchiano quelle in `scores`. Il dashboard visualizza ogni voce sotto la sua barra di punteggio. | +| `summary` | string \| null | Narrativo complessivo facoltativo di un paragrafo restituito dal tuo evaluator. Il dashboard visualizza questo sopra la ripartizione per punteggio come titolo della valutazione. | +| `error` | string \| null | Compilato solo su `"error"` / `"timeout"`. | +| `attempt_count` | integer | Numero di tentativi di dispatch (≥ 1). | | `duration_ms` | integer \| null | Durata del tentativo finale. | | `completed_at` | string (ISO 8601 UTC) | Quando il risultato terminale è stato registrato. I risultati sono ordinati per `completed_at` (più recente per primo). | | `created_at` | string (ISO 8601 UTC) | Porta lo stesso timestamp di `completed_at` (semantica write-once). | @@ -238,62 +303,97 @@ Ogni oggetto di risposta `/evaluations` ha questi campi: | Permesso | Concede | |---|---| -| `evaluations:read` | Elencare i risultati della valutazione, visualizzare i punteggi nel dashboard e caricare le metriche di salute del dashboard. | -| `evaluations:trigger` | Metti in coda manualmente una valutazione per una sessione via `POST /sessions/:session_id/re-evaluate` o dal pulsante di rivalutazione del dashboard. | -| `dashboards:read` | Visualizzare i dashboard salvati (ha anche bisogno di `evaluations:read` per caricare le loro metriche). | -| `dashboards:write` | Creare e modificare i dashboard. | -| `dashboards:delete` | Eliminare i dashboard. | +| `evaluations:read` | Elenca i risultati di valutazione, visualizza i punteggi nel dashboard e carica le metriche di salute del dashboard. | +| `evaluations:trigger` | Accoda manualmente una valutazione per una sessione tramite `POST /sessions/:session_id/re-evaluate` o il pulsante re-evaluate del dashboard. | +| `dashboards:read` | Visualizza dashboard salvati (ha bisogno anche di `evaluations:read` per caricare le loro metriche). | +| `dashboards:write` | Crea e modifica dashboard. | +| `dashboards:delete` | Elimina dashboard. | L'admin bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) riceve automaticamente questi. --- -## Visualizzare i risultati +## Visualizzazione dei risultati -- **`/sessions/`**: timeline degli eventi + una barra laterale destra che mostra i punteggi della sessione e qualsiasi errore dal tentativo di invio. Se la tua chiave ha `evaluations:trigger`, appare un pulsante **re-evaluate** accanto al pulsante di esportazione, utile per sessioni che non hanno mai emesso `agent_end`, o per aggiornare i punteggi dopo aver distribuito un nuovo valutatore. Il dashboard effettua il poll per il nuovo risultato e aggiorna la barra laterale destra quando arriva. -- **`/sessions`**: griglia di sessione filtrabile; la colonna dei punteggi mostra lo stato di valutazione e i punteggi di ogni sessione a colpo d'occhio. -- **`/dashboards`**: viste di salute eval salvate (vedi [Dashboard](#dashboards) sotto). +- **`/sessions/`**: timeline degli eventi + una barra laterale destra che mostra i punteggi della sessione + e qualsiasi errore dal tentativo di dispatch. Se la tua chiave ha + `evaluations:trigger`, appare un pulsante **re-evaluate** accanto al pulsante di export, + utile per sessioni che non hanno mai emesso `agent_end`, o per + aggiornare i punteggi dopo aver distribuito un nuovo evaluator. Il dashboard esegue il polling per + il nuovo risultato e aggiorna la barra laterale destra quando arriva. +- **`/sessions`**: griglia di sessione filtrabile; la colonna di punteggio mostra a colpo d'occhio + lo status di valutazione e i punteggi di ogni sessione. +- **`/dashboards`**: viste salvate di eval-health (vedi [Dashboards](#dashboards) sotto). -![La griglia di sessioni con pillole di stato di valutazione per sessione e badge di punteggio codificati per colore (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) +![La griglia Sessions con pillole di status di valutazione per sessione e badge di punteggio codificati a colori (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) -*La griglia di sessioni mostra lo stato di valutazione e i punteggi di ogni esecuzione a colpo d'occhio; i badge rosso/ambra/verde rendono i punteggi bassi evidenti.* +*La griglia sessioni mostra a colpo d'occhio lo status di valutazione e i punteggi di ogni esecuzione; i badge rosso/ambra/verde fanno emergere i punteggi bassi.* --- ## Dashboard -La pagina **Dashboard** (`/dashboards`) ti consente di salvare una combinazione di filtri di valutazione come una vista denominata e riutilizzabile e osservare come quella sezione di valutazioni sta andando a colpo d'occhio. I dashboard sono **condivisi in tutta la tua intera organizzazione**; chiunque abbia `dashboards:read` vede lo stesso set. +La pagina **Dashboards** (`/dashboards`) ti permette di salvare una combinazione di filtri di valutazione +come una vista denominata e riutilizzabile e osservare come quella sezione di valutazioni +sta andando a colpo d'occhio. I dashboard sono **condivisi su tutta la tua organizzazione**; +chiunque abbia `dashboards:read` vede lo stesso set. -Ogni dashboard fissa: +Ogni dashboard mette in evidenza: -- **Filtri**: gli stessi controlli della pagina delle sessioni: ambiente, stato, agent, una finestra di tempo mobile e filtri di intervallo di punteggi (`key:min..max`). -- **Una configurazione di visualizzazione**: quali chiavi di punteggio presentare, le soglie di salute rosso/ambra/verde, quali pannelli mostrare e se collassare alla valutazione più recente per sessione. +- **Filtri**: gli stessi controlli della pagina sessioni: environment, status, + agente, una finestra di tempo mobile, e filtri di intervallo di punteggio (`key:min..max`). +- **Una configurazione di visualizzazione**: quali chiavi di punteggio evidenziare, le soglie di salute + verde/ambra/rosso, quali pannelli mostrare e se comprimere alla valutazione più recente per sessione. -Ogni card mostra il numero di sessioni corrispondenti, una disaggregazione done/error/timeout, la media di ogni punteggio presentato e un piccolo sparkline di tendenza. Aprire un dashboard mostra i pannelli a dimensione intera; **open in sessions** ti porta alla pagina delle sessioni prefiltrrata esattamente a quella sezione. Le metriche sono calcolate lato server su tutto il set di corrispondenza (via `GET /evaluations/aggregate`), così i numeri sono esatti piuttosto che campionati. +Ogni scheda mostra il numero di sessioni corrispondenti, una ripartizione done/error/timeout, +la media di ogni punteggio evidenziato e una piccola sparkline di trend. Aprire un +dashboard mostra i pannelli a grandezza intera; **"apri in sessioni"** ti porta nella +pagina sessioni pre-filtrata esattamente a quella sezione. Le metriche vengono calcolate +lato server sull'intero set corrispondente (tramite `GET /evaluations/aggregate`), quindi +i numeri sono esatti piuttosto che campionati. -![Un dashboard di salute eval con barre di punteggio medio per dimensione del valutatore, una disaggregazione tool ok-vs-error, top tools e una tendenza events-per-hour](/agenteye/images/dashboard-quality.png) +![Un dashboard di eval-health con barre di punteggio medio per dimensione dell'evaluator, ripartizione tool ok-vs-error, strumenti principali e trend events-per-hour](/agenteye/images/dashboard-quality.png) -**Permessi:** visualizzare richiede sia `dashboards:read` che `evaluations:read`; creare e modificare richiede `dashboards:write`; eliminare richiede `dashboards:delete`. L'admin bootstrap riceve tutti questi automaticamente. +**Permessi:** la visualizzazione richiede sia `dashboards:read` che `evaluations:read`; +la creazione e modifica richiedono `dashboards:write`; l'eliminazione richiede `dashboards:delete`. +L'admin bootstrap riceve automaticamente tutti questi. --- ## Risoluzione dei problemi -**Le sessioni esistono ma non vengono create valutazioni.** Conferma che `EVALUATOR_ENDPOINT` è impostato sul processo server, che il server e il valutatore condividono lo stesso valore `EVALUATOR_TOKEN`, e che l'endpoint `/health` del valutatore è raggiungibile dal server. Con `EVALUATOR_ENDPOINT` non impostato la pipeline è non operativa. - -**Le valutazioni in corso si accumulano.** Interroga `GET /evaluation-jobs` per vedere la coda in corso. Ispeziona `attempt_count`, `next_attempt_at` e `last_error` su ogni riga. Cause comuni: servizio di valutazione non raggiungibile o che restituisce 5xx (ritentato con backoff), `EVALUATOR_TOKEN` errato (401 è terminale), o un valutatore asincrono che restituisce `pending` indefinitamente (vedi sotto). - -**Le sessioni completate ma nessuna valutazione terminale.** Interroga `GET /evaluation-jobs?status=polling`; il risultato potrebbe ancora essere in corso. Se un job è bloccato in `pending`, il server ha problemi a raggiungere il valutatore; controlla che il valutatore sia in esecuzione e che `EVALUATOR_TOKEN` corrisponda. - -**`HTTP 401 from evaluator: invalid bearer token`.** Il `EVALUATOR_TOKEN` sul server non corrisponde al valore con cui è configurato il servizio di valutazione. Devono essere identici. - -**Il valutatore asincrono restituisce `pending` per sempre.** Il server effettua il polling di `GET /evaluate/{job_id}` finché il valutatore non restituisce `done` o `error`, o finché il cap `EVALUATOR_MAX_POLL_DURATION_SECS` (default 1 h) non trascorre. Dopo il cap la valutazione viene registrata come `timeout` e rimossa dalla coda in corso. Alza `EVALUATOR_MAX_POLL_DURATION_SECS` se il tuo valutatore ha legittimamente bisogno di più tempo del default. +**Le sessioni esistono ma non vengono create valutazioni.** Conferma che `EVALUATOR_ENDPOINT` +è impostato sul processo del server, che il server e l'evaluator condividono lo stesso +valore `EVALUATOR_TOKEN` e che l'endpoint `/health` dell'evaluator +è raggiungibile dal server. Con `EVALUATOR_ENDPOINT` non impostato la pipeline è no-op. + +**Le valutazioni in corso si accumulano.** Interroga `GET /evaluation-jobs` per vedere la +coda in corso. Ispeziona `attempt_count`, `next_attempt_at` e `last_error` +su ogni riga. Cause comuni: servizio evaluator non raggiungibile o che restituisce 5xx +(ritentato con backoff), `EVALUATOR_TOKEN` errato (401 è terminale), o un +evaluator asincrono che restituisce `pending` indefinitamente (vedi sotto). + +**Sessioni completate ma nessuna valutazione terminale.** Interroga +`GET /evaluation-jobs?status=polling`; il risultato potrebbe ancora essere in corso. +Se un job è bloccato in `pending`, il server ha problemi nel raggiungere l'evaluator; +controlla che l'evaluator sia attivo e che `EVALUATOR_TOKEN` corrisponda. + +**`HTTP 401 from evaluator: invalid bearer token`.** Il `EVALUATOR_TOKEN` +sul server non corrisponde al valore configurato nel servizio evaluator. Devono +essere identici. + +**Evaluator asincrono restituisce `pending` per sempre.** Il server esegue il polling +`GET /evaluate/{job_id}` finché l'evaluator non restituisce `done` o `error`, o +finché non trascorra il limite `EVALUATOR_MAX_POLL_DURATION_SECS` (default 1 h). Dopo il limite +la valutazione viene registrata come `timeout` e rimossa dalla coda in corso. +Aumenta `EVALUATOR_MAX_POLL_DURATION_SECS` se il tuo evaluator ha davvero bisogno +di più del default. --- -## Prossimi passi +## Passaggi successivi -- [Skill agent valutatore](/it/agenteye/evaluator-skill): fai progettare a un agent di codifica le tue dimensioni in base a sessioni reali e costruisci questo servizio per te. +- [Evaluator agent skill](/it/agenteye/evaluator-skill): fai in modo che un agente di coding progetti le tue dimensioni rispetto alle sessioni reali e costruisca questo servizio per te. - [Python SDK](/it/agenteye/python-sdk): emetti gli eventi `agent_end` che attivano lo scoring. - [Chiavi API](/it/agenteye/api-keys): i permessi `evaluations:read` e `evaluations:trigger`. -- [Audit](/it/agenteye/audits): l'altra funzione di qualità automatizzata di Observability, per la revisione basata su policy. \ No newline at end of file +- [Audits](/it/agenteye/audits): l'altra funzione di qualità automatizzata di Observability, per la revisione basata su policy. \ No newline at end of file diff --git a/docs/it/agenteye/evaluations.mdx b/docs/it/agenteye/evaluations.mdx index 138f4607..c1494c9e 100644 --- a/docs/it/agenteye/evaluations.mdx +++ b/docs/it/agenteye/evaluations.mdx @@ -1,51 +1,52 @@ --- +--- title: "Valutazioni" -description: "I problemi di qualità ti trovano adesso, invece di scoprirli da un reclamo utente." +description: "I problemi di qualità ti raggiungono ora, invece di scoprirli da un reclamo di un utente." --- -I problemi di qualità ti trovano adesso, invece di scoprirli da un reclamo utente. Connetti il tuo servizio di scoring una volta e Failproof AI Observability valuta automaticamente ogni esecuzione completata, così un calo di utilità o un picco di allucinazioni emerge da solo, prima che un cliente lo noti. +I problemi di qualità ti raggiungono ora, invece di scoprirli da un reclamo di un utente. Colleghi il tuo servizio di scoring una volta e Failproof AI Observability valuta automaticamente ogni esecuzione completata, così una diminuzione dell'utilità o un picco di allucinazioni appare da solo, prima che un cliente lo avverta. -![La griglia Sessioni con una colonna di score: ogni esecuzione ha un badge di stato di valutazione e badge con codice colore per utilità, fattualità ed efficienza dello strumento](/agenteye/images/sessions-list.png) +![La griglia Sessions con una colonna di score: ogni esecuzione ha una pillola di stato di valutazione e badge con codifica a colori per utilità, fattualità ed efficienza dello strumento](/agenteye/images/sessions-list.png) -*Ogni esecuzione nella griglia di sessioni porta i suoi score; i badge rossi, ambra e verdi fanno risaltare le esecuzioni deboli senza dover aprire un singolo transcript.* +*Ogni esecuzione nella griglia delle sessioni riporta i suoi score; i badge rossi, ambra e verdi fanno emergere le esecuzioni deboli senza aprire nemmeno una trascrizione.* -## Smetti di campionare le esecuzioni manualmente +## Smetti di campionare manualmente le esecuzioni -Prima facevi controlli spot su una manciata di esecuzioni e speravi che il resto andasse bene. Adesso ogni sessione completata viene valutata nel momento in cui finisce, secondo le dimensioni che contano per te: utilità, efficienza dello strumento, fattualità, sicurezza, quello che è il tuo standard di qualità. Tu definisci le chiavi di score; Failproof AI Observability memorizza, registra le tendenze e visualizza tutto quello che il tuo evaluator rimanda indietro. Nessuna esecuzione sfugge senza essere valutata, e smetti di scoprire una regressione da un ticket di supporto. +Una volta controllavi a campione un pugno di esecuzioni e speravi che il resto fosse a posto. Ora ogni sessione completata viene valutata nel momento in cui termina, sulle dimensioni che ti interessano: utilità, efficienza dello strumento, fattualità, sicurezza, qualunque sia il tuo standard di qualità. Definisci le chiavi di score; Failproof AI Observability archivia, tende e visualizza tutto ciò che il tuo valutatore rimanda indietro. Nessuna esecuzione sfugge senza score, e smetti di scoprire una regressione da un ticket di supporto. -Gli score compaiono sulla griglia di sessioni su **`//sessions`** (sidebar → *observe* → *sessions*), un cluster di badge per riga. Vuoi solo le esecuzioni che non hanno raggiunto l'obiettivo? Filtra la griglia per range di score, ad esempio utilità sotto 0.5, e accedi esattamente alle esecuzioni che vale la pena leggere. La visualizzazione degli score richiede il permesso `evaluations:read`. +I score compaiono nella griglia delle sessioni a **`//sessions`** (sidebar → *observe* → *sessions*), un cluster di badge per ogni riga. Vuoi solo le esecuzioni che non hanno raggiunto la soglia? Filtra la griglia per intervallo di score, ad esempio utilità inferiore a 0.5, e visualizza esattamente le esecuzioni che vale la pena leggere. La visualizzazione dei score richiede il permesso `evaluations:read`. -## Scopri perché un'esecuzione ha ottenuto un basso score +## Scopri perché un'esecuzione ha ottenuto uno score basso -Un numero ti dice che un'esecuzione era debole; la pagina della sessione ti dice perché. Apri qualsiasi esecuzione e la barra laterale destra inizia con il riassunto principale, poi mostra una barra per ogni dimensione con il ragionamento del tuo evaluator sotto ciascuna, così passi da "questo ha ottenuto 0.4 sulla fattualità" all'affermazione esatta sbagliata in pochi secondi. +Un numero ti dice che un'esecuzione era debole; la pagina della sessione ti spiega il perché. Apri qualsiasi esecuzione e la barra laterale destra inizia con un riepilogo principale, quindi mostra una barra per dimensione con le motivazioni del tuo valutatore sotto ciascuna, così passi da "questa ha ottenuto 0.4 sulla fattualità" all'affermazione esatta sbagliata in pochi secondi. -![La barra laterale destra di una sessione: il riassunto della valutazione in alto, poi barre di score per dimensione ciascuna con una riga di ragionamento, accanto alla completa timeline degli eventi](/agenteye/images/session-detail.png) +![La barra laterale destra di una sessione: il riepilogo della valutazione in alto, quindi barre di score per dimensione ciascuna con una linea di motivazione, accanto alla cronologia completa degli eventi](/agenteye/images/session-detail.png) -*La vista dei dettagli della sessione: riassunto, barre di score per dimensione e il ragionamento dietro ogni score, proprio accanto alla timeline degli eventi dell'esecuzione.* +*La vista dei dettagli della sessione: riepilogo, barre di score per dimensione e le motivazioni dietro ogni score, proprio accanto alla cronologia degli eventi dell'esecuzione.* -Hai distribuito un evaluator più intelligente, o stai guardando un'esecuzione che si è arrestata prima di poter essere valutata? Un pulsante **re-evaluate** (protetto da `evaluations:trigger`) rivaluta la sessione in posizione e aggiunge il risultato fresco alla sua timeline, così gli score precedenti rimangono visibili come storico. Lo troverai su **`//sessions/`**. +Hai implementato un valutatore più sofisticato, o stai guardando un'esecuzione che si è interrotta prima di poter essere valutata? Un pulsante **re-evaluate** (controllato da `evaluations:trigger`) valuta di nuovo la sessione sul posto e aggiunge il risultato fresco alla sua cronologia, così gli score precedenti rimangono visibili come cronologia. Lo troverai a **`//sessions/`**. -## Osserva la tendenza di qualità su tutta la flotta +## Osserva la tendenza della qualità nell'intera flotta -Un'esecuzione con basso score è rumore; una coorte intera che scivola è un segnale. Le dashboard salvate trasformano i tuoi score in una tendenza che puoi osservare a colpo d'occhio: utilità media questa settimana rispetto alla scorsa, per agent, per ambiente. +Una singola esecuzione con score basso è rumore; un'intera coorte che scivola è un segnale. I dashboard salvati trasformano i tuoi score in una tendenza che puoi osservare a colpo d'occhio: utilità media questa settimana rispetto a quella scorsa, per agente, per ambiente. -![Una dashboard di qualità: barre di score medio per dimensione dell'evaluator accanto a una tendenza nel tempo](/agenteye/images/dashboard-quality.png) +![Un dashboard di qualità: barre di score medio per dimensione di valutatore insieme a una tendenza nel tempo](/agenteye/images/dashboard-quality.png) -*Una dashboard di qualità salvata registra le tendenze delle chiavi di score che presenti, così una deriva lenta è ovvia molto prima che diventi un incidente.* +*Un dashboard di qualità salvato tende le chiavi di score che presenti, così una lenta deriva è ovvia molto prima che diventi un incidente.* -Le dashboard si trovano su **`//dashboards`** (sidebar → *analyze* → *dashboards*), sono condivise su tutta l'organizzazione e ogni scheda raggruppa le sessioni corrispondenti: quante ce ne sono, la media di ogni score presentato e una sparkline di tendenza. "Apri nelle sessioni" ti porta direttamente alle esecuzioni pre-filtrate dietro qualsiasi numero. La visualizzazione richiede `dashboards:read` più `evaluations:read`. +I dashboard si trovano a **`//dashboards`** (sidebar → *analyze* → *dashboards*), sono condivisi in tutta la tua organizzazione, e ogni scheda raggruppa le sessioni corrispondenti: quante sono, la media di ogni score presentato e una sparkline di tendenza. "Open in sessions" ti porta direttamente alle esecuzioni pre-filtrate dietro qualsiasi numero. La visualizzazione richiede `dashboards:read` più `evaluations:read`. -## Connetti un evaluator una volta +## Colleghi un valutatore una volta -Lo scoring è opt-in e rimane completamente disattivato finché non punti Failproof AI Observability a uno scorer. Avvii un piccolo servizio HTTP (Observability fornisce un riferimento funzionante che puoi copiare), imposti due valori sul tuo server e da allora ogni esecuzione viene valutata per te. La guida completa, il contratto di scoring e l'SDK si trovano nella guida approfondita. +Lo scoring è opzionale e rimane completamente disattivato fino a quando non punti Failproof AI Observability su uno scorer. Avvii un piccolo servizio HTTP (Observability fornisce un riferimento funzionante che puoi copiare), imposti due valori sul tuo server, e da quel momento ogni esecuzione viene valutata per te. La procedura completa, il contratto di scoring e l'SDK si trovano nella guida dettagliata. -Non sei sicuro di quali dimensioni vale la pena valutare in primo luogo? L'[agent skill evaluator](/it/agenteye/evaluator-skill) fa in modo che il tuo agent di codifica lo scopra sulle tue stesse sessioni, poi costruisci e distribuisci il servizio. +Non sei sicuro di quali dimensioni valga la pena valutare in primo luogo? La [competenza dell'agente valutatore](/it/agenteye/evaluator-skill) fa in modo che il tuo agente di codifica lo scopra sulle tue stesse sessioni, quindi costruisca e distribuisca il servizio. ## Correlati -- [Evaluation suite](/it/agenteye/evaluation-suite): connetti il tuo evaluator, il contratto di scoring e l'SDK. -- [Evaluator agent skill](/it/agenteye/evaluator-skill): lascia che un agent di codifica scelga le tue dimensioni di score e costruisca l'evaluator. -- [Sessions](/it/agenteye/sessions): la griglia run-by-run dove compaiono gli score. -- [Dashboards](/it/agenteye/dashboards): salva e condividi le tendenze di qualità nella tua organizzazione. -- [Audits](/it/agenteye/audits): l'altra funzione di qualità automatica di Observability, per investigazioni tra sessioni. \ No newline at end of file +- [Suite di valutazione](/it/agenteye/evaluation-suite): colleghi il tuo valutatore, il contratto di scoring e l'SDK. +- [Competenza dell'agente valutatore](/it/agenteye/evaluator-skill): lascia che un agente di codifica scelga le tue dimensioni di score e costruisca il valutatore. +- [Sessioni](/it/agenteye/sessions): la griglia esecuzione per esecuzione dove compaiono gli score. +- [Dashboard](/it/agenteye/dashboards): salva e condividi le tendenze di qualità nella tua organizzazione. +- [Audit](/it/agenteye/audits): l'altra funzione di qualità automatica di Observability, per indagini tra sessioni. \ No newline at end of file diff --git a/docs/it/agenteye/evaluator-skill.mdx b/docs/it/agenteye/evaluator-skill.mdx index 243583e2..08c8bd52 100644 --- a/docs/it/agenteye/evaluator-skill.mdx +++ b/docs/it/agenteye/evaluator-skill.mdx @@ -1,170 +1,166 @@ --- -title: "Failproof AI Observability Evaluator Agent Skill" -description: "Da «penso che il nostro agente a volte funzioni male» a un servizio di scoring distribuito, con il tuo agente che decide e costruisce tutto." +title: "Competenza Valutatore Osservabilità Failproof AI Agent" +description: "Passa da \"penso che il nostro agent a volte funzioni male\" a un servizio di scoring distribuito, con il tuo agente di codifica che decide e costruisce tutto." --- +Passa da *"penso che il nostro agent a volte funzioni male"* a un servizio di scoring distribuito, con il tuo agente di codifica che decide e costruisce tutto. La **competenza valutatore osservabilità Failproof AI** (`agenteye-evaluator`) è un'*Agent Skill*: una piccola cartella di istruzioni che un agente di codifica come Claude Code o Codex carica su richiesta. Insegna all'agente a individuare quali dimensioni di qualità vale la pena tracciare per il *tuo* agente, quindi scrive, testa e distribuisce il [servizio valutatore](/it/agenteye/evaluation-suite) che le valuta. -Da *«penso che il nostro agente a volte funzioni male»* a un servizio di scoring distribuito, con il tuo agente che decide e costruisce tutto. La **skill di valutazione Failproof AI Observability** (`agenteye-evaluator`) è un *Agent Skill*: una piccola cartella di istruzioni che un agente di codifica come Claude Code o Codex carica su richiesta. Insegna all'agente a capire quali dimensioni di qualità vale la pena tracciare per *il tuo* agente, quindi scrivere, testare e distribuire il [servizio di valutazione](/it/agenteye/evaluation-suite) che le punteggia. - -**Non** è uno scorer ospitato, un registro su cui caricare dati, o un sistema di plugin. Il tuo valutor rimane un tuo servizio HTTP sulla tua infrastruttura, esattamente come descritto nella guida [Evaluation suite](/it/agenteye/evaluation-suite). La skill insegna semplicemente al tuo agente a costruirlo bene, così tutto ciò che fa, potresti farlo tu scrivendo lo stesso codice. +**Non** è uno scorer ospitato, un registro dove caricare, o un sistema di plugin. Il tuo valutatore rimane un tuo servizio HTTP sulla tua infrastruttura, esattamente come descritto nella guida [Evaluation suite](/it/agenteye/evaluation-suite). La skill insegna solo al tuo agente a costruirlo bene, quindi tutto ciò che fa, potresti farlo tu stesso scrivendo lo stesso codice. --- -## La parte difficile è decidere cosa punteggiare +## La parte difficile è decidere cosa valutare -La superficie dell'SDK è piccola — un decoratore e due modelli — e un agente può scriverla dal [contratto](/it/agenteye/evaluation-suite#http-contract) da solo. Non è lì che i valutor falliscono. Falliscono perché punteggiamo la cosa sbagliata, e un valutor che punteggia la cosa sbagliata è peggio di niente: produce una dashboard che tutti imparano a ignorare. +La superficie dell'SDK è piccola — un decorator e due modelli — e un agente può scrivere quello dal [contratto](/it/agenteye/evaluation-suite#http-contract) da solo. Non è lì che i valutatori falliscono. Falliscono perché valutano la cosa sbagliata, e un valutatore che valuta la cosa sbagliata è peggio di niente: produce una dashboard che tutti imparano a ignorare. -Quindi gran parte della skill è la parte prima che esista del codice. Fa sì che l'agente ti intervisti (*«descrivi un'esecuzione andata bene; ora una andata male»*), poi tiri le tue vere sessioni attraverso la [`agenteye` CLI](/it/agenteye/cli) e le legga da cima a fondo. Queste due parti di solito non concordano, e il divario è il punto: quello che intendi misurare rispetto a quello che i tuoi transcript possono effettivamente supportare. Una dimensione sopravvive solo se è **calcolabile** dagli eventi e **discriminante** — se punteggia 0.9 sia sulla tua buona esecuzione che su quella cattiva, non insegna nulla e viene tagliata. +Quindi gran parte della skill è la parte prima che esista codice. Ha l'agente che ti intervista (*"descrivi un'esecuzione che è andata bene; ora una che è andata male"*), quindi estrae le tue sessioni reali attraverso il [`agenteye` CLI](/it/agenteye/cli) e le legge da cima a fondo. Queste due metà solitamente non concordano, e il divario è il punto: quello che intendi misurare rispetto a quello che i tuoi transcript possono effettivamente supportare. Una dimensione sopravvive solo se è **calcolabile** dagli eventi e **discriminante** — se ottiene 0.9 sia nella tua esecuzione buona che in quella cattiva, non insegna nulla e viene eliminata. -Quello che torna è una proposta di 2-4 dimensioni con il ragionamento allegato, per te da approvare prima che venga scritta una riga. +Quello che torna è una proposta di 2-4 dimensioni con il ragionamento allegato, per te per darti il via libera prima che venga scritta una riga. ```mermaid flowchart TD - YOU["tu: 'voglio valutazioni per il mio bot di supporto'"] --> AGENT["agente di codifica (Claude Code / Codex)
carica la skill agenteye-evaluator"] - AGENT -->|"intervista: come appare il bene vs il male?"| YOU - AGENT -->|"agenteye --json sessions / events"| DATA["le tue vere sessioni
quello che succede davvero"] - DATA --> DIMS["2-4 dimensioni, tu approvi"] - DIMS --> SVC["il tuo servizio valutor
agenteye-evaluator SDK"] - SVC --> SCORES["i punteggi arrivano nel dashboard
e nelle valutazioni agenteye"] + YOU["tu: 'voglio evals per il mio bot di supporto'"] --> AGENT["agente di codifica (Claude Code / Codex)
carica la skill agenteye-evaluator"] + AGENT -->|"intervista: come appare bene vs male?"| YOU + AGENT -->|"agenteye --json sessions / events"| DATA["le tue sessioni reali
quello che succede davvero"] + DATA --> DIMS["2-4 dimensioni, dai il via libera"] + DIMS --> SVC["il tuo servizio valutatore
SDK agenteye-evaluator"] + SVC --> SCORES["i punteggi arrivano nella dashboard
e negli evals agenteye"] ``` --- -## Come si relaziona agli altri pezzi di valutazione +## Come si relaziona con gli altri pezzi di valutazione -Quattro documenti riguardano il scoring e si passano il testimone in ordine: +Quattro documenti coprono lo scoring e si passano il testimone in ordine: -| Pagina | Cos'è | Usalo quando | +| Pagina | Cos'è | Usala quando | |---|---|---| -| **[Evaluations](/it/agenteye/evaluations)** | La funzione: punteggi nella griglia delle sessioni, dashboard, rivalutazione | Vuoi sapere cosa ottiene il scoring automatico | -| **[Evaluation suite](/it/agenteye/evaluation-suite)** | Il contratto HTTP, l'SDK, le variabili d'ambiente del server | Stai implementando o debuggando il valutor tu stesso | -| **Evaluator skill** (questo doc) | Una porta d'ingresso in linguaggio naturale per progettare *e* costruire il valutor | Vuoi passare da «voglio valutazioni» a un servizio in esecuzione | -| **[CLI skill](/it/agenteye/cli-skill)** | Una porta d'ingresso in linguaggio naturale sulla `agenteye` CLI | Vuoi *leggere* i punteggi che hai già | -| **[Python SDK skill](/it/agenteye/python-sdk-skill)** | Una porta d'ingresso in linguaggio naturale sull'instrumentazione del tuo agente | Il tuo agente non sta ancora emettendo sessioni — non c'è nulla da punteggiare | +| **[Evaluations](/it/agenteye/evaluations)** | La funzione: punteggi sulla griglia delle sessioni, dashboard, rivaluta | Vuoi sapere cosa ottieni dal scoring automatico | +| **[Evaluation suite](/it/agenteye/evaluation-suite)** | Il contratto HTTP, l'SDK, le variabili d'ambiente del server | Stai implementando o debuggando il valutatore tu stesso | +| **Evaluator skill** (questo doc) | Una porta d'ingresso in linguaggio naturale sulla progettazione *e* costruzione dello scorer | Vuoi passare da "voglio evals" a un servizio in esecuzione | +| **[CLI skill](/it/agenteye/cli-skill)** | Una porta d'ingresso in linguaggio naturale sul CLI `agenteye` | Vuoi *leggere* i punteggi che hai già | +| **[Python SDK skill](/it/agenteye/python-sdk-skill)** | Una porta d'ingresso in linguaggio naturale sulla strumentazione del tuo agente | Il tuo agente non emette ancora sessioni — non c'è nulla da valutare | -### vs. la CLI skill: costruire rispetto a leggere +### vs. la CLI skill: costruire versus leggere Le due skill sono deliberatamente non sovrapposte, e installare entrambe è la configurazione normale — l'agente sceglie tra loro in base a quello che chiedi: - **`agenteye-evaluator`** (questo doc) costruisce la cosa che *produce* punteggi. Il suo lavoro finisce quando i punteggi arrivano per la prima volta. -- **[`agenteye-cli`](/it/agenteye/cli-skill)** legge punteggi che già esistono (`agenteye evals`). «La qualità è diminuita questa settimana?» è sua domanda, non di questa skill. +- **[`agenteye-cli`](/it/agenteye/cli-skill)** legge punteggi che già esistono (`agenteye evals`). *"La qualità è diminuita questa settimana?"* è la sua domanda, non quella di questa skill. --- ## Prerequisiti -1. La **`agenteye` CLI installata e connessa** (`pipx install agenteye`, poi `agenteye login`). La skill vi fa affidamento due volte: per tirare le vere sessioni su cui progetta, e per confermare che i tuoi punteggi sono arrivati alla fine. Il tuo login ha bisogno di `events:read`, più `evaluations:read` per quel controllo finale. Come con la CLI skill, **non può** completare per te il login con codice monouso inviato per email. -2. **Un posto dove il valutor vive.** Viene costruito in un'immagine ed eseguito come servizio a lungo termine, quindi ha bisogno di un vero repo, non di un file temporaneo. I valutor spesso vivono nel loro repo, separato dall'agente che viene punteggiato — la skill cerca uno esistente e chiede prima di scaffoldare uno nuovo. -3. **La wheel dell'SDK `agenteye-evaluator`** — leggi la prossima sezione prima che il tuo agente inizi a digitare comandi `pip`. +1. **`agenteye` CLI installato e collegato** (`pipx install agenteye`, quindi `agenteye login`). La skill lo utilizza due volte: per estrarre le sessioni reali su cui progetta, e per confermare che i tuoi punteggi siano arrivati alla fine. Il tuo login ha bisogno di `events:read`, più `evaluations:read` per quel controllo finale. Come con la CLI skill, **non** può completare per te il login con codice monouso via email. +2. **Un posto dove il valutatore possa vivere.** Viene costruito in un'immagine ed eseguito come servizio a lunga durata, quindi ha bisogno di un vero repository, non di un file temporaneo. I valutatori spesso vivono nel loro proprio repository, separati dall'agente valutato — la skill cerca uno esistente e chiede prima di costruirne uno nuovo. +3. **La wheel dell'SDK `agenteye-evaluator`** — leggi la prossima sezione prima che il tuo agente cominci a digitare comandi `pip`. --- -## Dove ottenerlo +## Dove trovarla -La skill è pubblicata nella collezione pubblica di skill di Failproof AI: +La skill è pubblicata nella collezione di skill pubblica di Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -Il repository è pubblico e la skill non ha bisogno di credenziali proprie — guida solo la `agenteye` CLI con la sessione in cui *tu* ti sei connesso, e scrive codice nel *tuo* repo. Nota che viene spedita come propria cartella e **non** è dentro il pacchetto `pipx install agenteye`, quindi non cercarla lì. +Il repository è pubblico e la skill non ha bisogno di nessuna credenziale sua — guida solo il CLI `agenteye` con la sessione con cui *tu* ti sei collegato, e scrive codice nel *tuo* repository. Nota che viene fornita come sua propria cartella e **non** è all'interno del pacchetto `pipx install agenteye`, quindi non cercarla lì. ## Installazione della skill -Il percorso più veloce è la CLI [`skills`](https://skills.sh), che scarica la cartella e la mette dove il tuo agente guarda: +Il percorso più veloce è il CLI [`skills`](https://skills.sh), che recupera la cartella e la mette dove il tuo agente guarda: ```bash -# Claude Code, questo progetto solo +# Claude Code, solo questo progetto npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -# ogni progetto (installa a ~/.claude/skills/) +# ogni progetto (installa in ~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy # Codex invece npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -Poi gestiscila come qualsiasi altra skill: +Quindi gestiscila come qualsiasi altra skill: ```bash npx skills list -a claude-code # cosa è installato -npx skills update agenteye-evaluator # tira l'ultima versione +npx skills update agenteye-evaluator # estrai l'ultima versione npx skills remove agenteye-evaluator # rimuovila ``` -Preferisci installare a mano? Un Agent Skill è solo una cartella contenente un `SKILL.md` (più riferimenti opzionali), quindi copiarlo funziona anche: +Preferisci installarla manualmente? Un'Agent Skill è solo una cartella contenente un `SKILL.md` (più riferimenti opzionali), quindi copiarla funziona anche: -- **Claude Code**: metti la cartella `agenteye-evaluator/` in `~/.claude/skills/` (ogni progetto) o `/.claude/skills/` (solo quel repo). Claude Code la scopre automaticamente — verifica con la lista `/skills`, o semplicemente chiedi valutazioni. -- **Codex (OpenAI)**: Codex legge lo stesso `SKILL.md`. Il `agents/openai.yaml` incluso imposta `allow_implicit_invocation: true`, quindi Codex auto-seleziona la skill quando un compito corrisponde; altrimenti invocare esplicitamente come `$agenteye-evaluator`. +- **Claude Code**: metti la cartella `agenteye-evaluator/` in `~/.claude/skills/` (ogni progetto) o `/.claude/skills/` (solo quel repository). Claude Code la scopre automaticamente — verifica con l'elenco `/skills`, o chiedi semplicemente gli evals. +- **Codex (OpenAI)**: Codex legge lo stesso `SKILL.md`. Il `agents/openai.yaml` incluso imposta `allow_implicit_invocation: true`, quindi Codex seleziona automaticamente la skill quando un'attività corrisponde; altrimenti invocala esplicitamente come `$agenteye-evaluator`. --- ## L'SDK non è su PyPI pubblico -> **Avviso:** Leggi questo prima di lasciare che un agente installi l'SDK. +> **Avvertenza:** Leggi questo prima di permettere a un agente di installare l'SDK. -La skill è pubblica; l'SDK che guida non lo è. `agenteye-evaluator` viene spedito solo come artefatto di rilascio privato, e a differenza di `agenteye`, il nome è **non rivendicato su PyPI pubblico** — quindi un semplice `pip install agenteye-evaluator` potrebbe tirare il pacchetto di uno straniero nel servizio che legge i tuoi transcript di produzione. Questo è un problema di supply chain, non un errore di battitura. +La skill è pubblica; l'SDK che guida non lo è. `agenteye-evaluator` viene fornito solo come artefatto di rilascio privato, e a differenza di `agenteye`, il nome è **non rivendicato su PyPI pubblico** — quindi un semplice `pip install agenteye-evaluator` potrebbe estrarre il pacchetto di uno sconosciuto nel servizio che legge i tuoi transcript di produzione. Questo è un problema della catena di approvvigionamento, non un typo. -La skill lo sa e funziona secondo una scala di installazione, fermandosi al primo gradino che si applica: il codice del monorepo se sei dentro il repo AgentEye, altrimenti la wheel di rilascio privata da GitHub Releases (serve accesso), e se nessuno dei due è raggiungibile **si ferma e ti dice di chiedere al tuo contatto Failproof AI la wheel** piuttosto che improvvisare. +La skill lo sa e funziona lungo una scala di installazione invece, fermandosi al primo gradino che si applica: la fonte del monorepo se sei dentro il repository AgentEye, altrimenti la wheel di rilascio privata da GitHub Releases (ha bisogno di accesso), e se nessuno dei due è raggiungibile si **ferma e ti dice di chiedere al tuo contatto Failproof AI la wheel** piuttosto che improvvisare. -Quindi se il tuo agente propone un semplice `pip install agenteye-evaluator` da PyPI pubblico, quello è il segnale che la skill non è mai stata caricata. Fermati lì e controlla che sia installata. +Quindi se il tuo agente propone un semplice `pip install agenteye-evaluator` da PyPI pubblico, questo è il segnale che la skill non ha mai caricato. Fermati lì e controlla che sia installata. --- -## Cosa puoi chiedergli +## Cosa puoi chiedere -Un vero percorso completo inizia con una richiesta vaga e finisce con un design approvato, non con il codice: +Un vero percorso completo inizia con una richiesta vaga e finisce con un design firmato, non con codice: ```text -tu ▸ Voglio valutazioni per il nostro bot di supporto. Penso - sia a volte cattivo. +tu ▸ Voglio evals per il nostro bot di supporto. Penso che a volte sia male. -agente ▸ Prima che scriva qualsiasi cosa: descrivi un'esecuzione - andata bene, e una andata male. +agente ▸ Prima di scrivere qualcosa: descrivi un'esecuzione che è andata bene, + e una che è andata male. -tu ▸ Bene: risponde dai documenti. Male: inventa cose, o rinuncia - e dice «contatta il supporto». +tu ▸ Buona: risponde dalla documentazione. Cattiva: inventa cose, + o si arrende e dice "contatta il supporto". -agente ▸ Esecuzione: agenteye --json sessions --status error --since 7d - Leggo 5 sessioni, incluse due che chiameresti cattive. +agente ▸ In esecuzione: agenteye --json sessions --status error --since 7d + Lettura di 5 sessioni, incluse due che chiameresti cattive. - Le tue parole dicono fattualità e defezione. I transcript - concordano sulla defezione (2 di 5 terminano con una - consegna al supporto, ed è evidente in model_response.content), - ma la fattualità ha bisogno di una ground truth che i tuoi - eventi non portano. + Le tue parole dicono fattualità e deflazione. I transcript + concordano sulla deflazione (2 su 5 finiscono con un trasferimento di supporto, + ed è chiaro in model_response.content), ma la fattualità + ha bisogno di una verità di base che i tuoi eventi non trasportano. - Quindi punteggierei tre cose: - - deflection regole, economico, separa le tue due esecuzioni - - tool_efficiency regole, cattura il loop di riprova in run-004 - - groundedness giudice LLM: ogni affermazione è nei documenti che ha recuperato? + Quindi valuterò tre cose: + - deflation regole, economico, separa i tuoi due run + - tool_efficiency regole, cattura il ciclo di ritentativi in run-004 + - groundedness giudice LLM: ogni affermazione è nella documentazione che ha recuperato? - «factuality» avrebbe bisogno di ground truth che non abbiamo; - groundedness è la cosa più vicina che i tuoi transcript possono - effettivamente supportare. OK con questi tre nomi? Rinominare - dopo spacca la cronologia. + "factuality" avrebbe bisogno di verità di base che non abbiamo; groundedness + è la cosa più vicina che i tuoi transcript possono effettivamente supportare. + Va bene con questi tre nomi? Rinominare dopo divide la cronologia. tu ▸ sì -agente ▸ Nessun valutor in questo repo. Dovrei scaffoldarne uno qui, - o ne hai uno altrove? +agente ▸ Nessun valutatore in questo repository. Devo costruirne uno qui, o + ne hai uno altrove? ``` -Da lì scrive le dimensioni basate su regole per prime (gratis, istantanee, deterministiche), le testa rispetto a una sessione catturata reale incluse quelle vuote e mai finite che fanno crashare i valutor ingenui, e raggiunge solo un giudice LLM sulla dimensione soggettiva. Conosce i [limiti del dispatcher](/it/agenteye/evaluation-suite#configuring-the-server) — un timeout di richiesta di 30 secondi e 8 chiamate concorrenti deployment-wide — quindi se il giudice non si adatterà in modo affidabile, va asincrono con `JobPending` piuttosto che lasciare che il tuo giudice sia cancellato e riprovato cinque volte cinque volte il costo. +Da lì scrive prima le dimensioni basate su regole (gratuite, istantanee, deterministiche), le testa rispetto a una sessione reale catturata incluse quelle vuote e mai terminate che bloccano i valutatori ingenui, e raggiunge un giudice LLM solo sulla dimensione soggettiva. Conosce i [limiti del dispatcher](/it/agenteye/evaluation-suite#configuring-the-server) — un timeout di 30 secondi e 8 chiamate concorrenti in tutto il deployment — quindi se il giudice non si adatterà in modo affidabile, va asincrono con `JobPending` piuttosto che lasciare che il tuo giudice venga cancellato e ritentato cinque volte a cinque volte il costo. -Poi distribuisce, imposta le due variabili d'ambiente del server, e conferma con `agenteye --json evals --session-id ` che i punteggi sono effettivamente arrivati. I punteggi che arrivano sono l'unica prova. +Quindi distribuisce, imposta le due variabili d'ambiente del server, e conferma con `agenteye --json evals --session-id ` che i punteggi siano effettivamente arrivati. I punteggi che arrivano sono l'unica prova. --- -## Cosa stare attenti +## Cosa guardare -- **I nomi delle dimensioni sono quasi permanenti.** Le chiavi di score sono stringhe arbitrarie e la piattaforma tende quello che invii, il che significa che nulla downstream corregge una scelta sbagliata. Rinominare dopo e la cronologia si spacca: le vecchie sessioni mantengono la vecchia chiave e il trend si interrompe. Per questo la skill ottiene l'approvazione esplicita prima di scrivere il codice — prendi quel prompt seriamente. -- **Le fixture sono veri transcript di produzione.** Progettare rispetto a sessioni reali significa tirarle su disco, e possono contenere dati dei clienti. La skill chiede prima di commetterli a git; se hai dubbi, mantieni `fixtures/` fuori dal repo e fai in modo che ogni sviluppatore tiri i propri. -- **L'agente scrive e distribuisce un servizio che legge ogni transcript.** Agisce come te, limitato dalle autorizzazioni del login della tua CLI, ma rivedi il valutor come qualsiasi altro codice che tocca dati di produzione. +- **I nomi delle dimensioni sono quasi permanenti.** Le chiavi di punteggio sono stringhe arbitrarie e la piattaforma tende quello che invii, il che significa che nulla a valle corregge una scelta sbagliata. Rinominare dopo e la cronologia si divide: le sessioni vecchie mantengono la chiave vecchia e il trend si interrompe. Questo è il motivo per cui la skill ottiene l'approvazione esplicita prima di scrivere codice — prendi seriamente quel prompt. +- **Gli fixture sono veri transcript di produzione.** Progettare rispetto a sessioni reali significa estrarle su disco, e possono contenere dati dei clienti. La skill chiede prima di eseguirne il commit su git; se hai dubbi, mantieni `fixtures/` fuori dal repository e fai sì che ogni sviluppatore estragga i propri. +- **L'agente scrive e distribuisce un servizio che legge ogni transcript.** Agisce come te, delimitato dalle autorizzazioni del tuo login CLI, ma rivedi il valutatore come qualsiasi altro codice che tocca dati di produzione. --- -## Prossimi passi +## Passaggi successivi -- **[Evaluation suite](/it/agenteye/evaluation-suite)**: il contratto HTTP, l'SDK, e le variabili d'ambiente del server che la skill configura. -- **[Evaluations](/it/agenteye/evaluations)**: dove i punteggi compaiono una volta che arrivano. -- **[CLI skill](/it/agenteye/cli-skill)**: la skill gemella, per leggere i risultati piuttosto che costruire il valutor. -- **[CLI](/it/agenteye/cli)**: il riferimento dei comandi dietro i dati di sessione su cui la skill progetta. \ No newline at end of file +- **[Evaluation suite](/it/agenteye/evaluation-suite)**: il contratto HTTP, l'SDK e le variabili d'ambiente del server che la skill configura. +- **[Evaluations](/it/agenteye/evaluations)**: dove appaiono i punteggi una volta che arrivano. +- **[CLI skill](/it/agenteye/cli-skill)**: la skill gemella, per leggere i risultati piuttosto che costruire lo scorer. +- **[CLI](/it/agenteye/cli)**: il riferimento di comando dietro i dati di sessione su cui la skill progetta. \ No newline at end of file diff --git a/docs/it/agenteye/event-stream.mdx b/docs/it/agenteye/event-stream.mdx index ebf3f2d6..e93a19f7 100644 --- a/docs/it/agenteye/event-stream.mdx +++ b/docs/it/agenteye/event-stream.mdx @@ -1,50 +1,51 @@ --- +--- title: "Event Stream" description: "Nel momento in cui il tuo agent fa qualcosa, lo vedi." --- -Nel momento in cui il tuo agent fa qualcosa, lo vedi. L'Event Stream è il tuo polso in tempo reale su ogni agent in produzione: niente attese, niente grep sui log, niente supposizioni su quello che è appena successo. +Nel momento in cui il tuo agent fa qualcosa, lo vedi. L'Event Stream è il tuo polso in tempo reale su ogni agent in produzione: senza attese, senza cercare nei log, senza indovinare cosa è appena successo. -![L'Event Stream dal vivo: righe di eventi codificate per colore che scorrono in tempo reale, filtrabili per ambiente, agent, sessione, tipo di evento e testo libero](/agenteye/images/events-stream.png) +![L'Event Stream dal vivo: righe di eventi con codice colore che scorrono in tempo reale, filtrabili per ambiente, agent, sessione, tipo di evento e testo libero](/agenteye/images/events-stream.png) -*Ogni evento da ogni agent della tua organizzazione, i più recenti per primi, aggiornati mentre accadono.* +*Ogni evento da ogni agent della tua organizzazione, i più recenti per primi, aggiornati man mano che accadono.* ## Il tuo polso in tempo reale su ogni agent -Quando un agent avvia un'esecuzione, chiama un modello, attiva uno strumento, esegue un hook o incontra un errore, la riga appare in cima al flusso nel momento in cui accade. Traccia ogni evento su ogni agent della tua organizzazione, i più recenti per primi, in modo che tu abbia sempre un'immagine attuale invece di una obsoleta. +Quando un agent avvia un'esecuzione, chiama un modello, attiva uno strumento, esegue un hook o si imbatte in un errore, la riga compare in cima al flusso nel momento esatto in cui accade. Traccia ogni evento attraverso ogni agent della tua organizzazione, i più recenti per primi, così hai sempre un quadro attuale invece di uno obsoleto. -Questo significa niente monitoraggio di file di log su una macchina da qualche parte, niente grep su più macchine, niente assemblaggio manuale di timestamp. Apri una pagina e stai già guardando la produzione. +Questo significa niente coda di file di log su una macchina da qualche parte, niente ricerca su più macchine, niente sincronizzazione manuale dei timestamp. Apri una pagina e stai già osservando la produzione. -Le righe sono codificate per colore in base al tipo, in modo che tu possa leggere il flusso a colpo d'occhio invece di analizzare ogni riga. A prima vista, ogni riga ti mostra: +Le righe hanno un codice colore per tipo, quindi puoi leggere il flusso a colpo d'occhio invece di analizzare ogni riga. A prima vista, ogni riga ti mostra: -- **Il suo tipo**, codificato per colore: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, e altri. -- **Un riassunto in una riga** di quello che è successo, quindi raramente devi aprire qualcosa solo per capire il concetto. -- **I conteggi dei token** per il passaggio. -- **Un badge di riempimento della finestra di contesto** dove applicabile, quindi la crescita dei prompt e un'imminente compattazione sono visibili prima che causino problemi. +- **Il suo tipo**, con codice colore: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, e altro. +- **Un riepilogo in una riga** di quello che è successo, quindi raramente hai bisogno di aprire nulla solo per capire il concetto. +- **Conteggi di token** per il passaggio. +- **Un badge di riempimento della finestra di contesto** dove applicabile, così la crescita del prompt e un compattamento imminente sono visibili prima che causino problemi. -Guardare dal vivo significa che catturi un deploy difettoso, un loop incontrollato o un'esplosione di errori mentre accade, non nella revisione dei log di domani. +Osservarlo dal vivo significa che catturi un deploy errato, un ciclo incontrollato o un'ondata di errori mentre accade, non nella revisione dei log di domani. ## Trova l'unica esecuzione che conta -Quando qualcosa non sembra a posto, non vuoi il diluvio di dati. Vuoi l'unica esecuzione che si è rotta. Il flusso si filtra velocemente: per ambiente, per agent, per sessione, per tipo di evento o per testo libero. +Quando qualcosa sembra storto, non vuoi l'intera cascata di dati. Vuoi l'unica esecuzione che si è rotta. Il flusso si filtra velocemente: per ambiente, per agent, per sessione, per tipo di evento, o per testo libero. -Filtra per ID sessione o ID agent per seguire un'esecuzione dal suo primo evento all'ultimo. Filtra per tipo di evento per isolare un singolo tipo di attività, ad esempio ogni `error` in tutta l'organizzazione in una sola vista. Accumula i filtri per restringere da "tutto, ovunque" a "questo agent, in prod, con errori" in un paio di clic, quindi agisci su quello che trovi. +Filtra per session id o agent id per seguire un'esecuzione dal suo primo evento all'ultimo. Filtra per tipo di evento per isolare un singolo tipo di attività, ad esempio ogni `error` in tutta l'organizzazione in un'unica vista. Combina i filtri per restringere da "tutto, ovunque" a "questo agent, in prod, con errori" in un paio di clic, quindi agisci su quello che trovi. -La ricerca in testo libero va dritto a un messaggio, un nome di strumento o un ID che hai già a portata di mano, quindi una segnalazione di un cliente si trasforma nell'esecuzione esatta in pochi secondi. +La ricerca di testo libero va dritto a un messaggio, un nome di strumento, o un id che hai già a portata di mano, così una segnalazione di un cliente si trasforma nell'esecuzione esatta in pochi secondi. -## Dove trovarla +## Dove trovarlo -L'Event Stream è la home della tua organizzazione. Accedi e è la prima superficie su cui atterri, su `//`, quindi il triage inizia dal momento in cui arrivi. +L'Event Stream è la home della tua organizzazione. Accedi e è la prima superficie su cui attendi, a `//`, quindi la classificazione inizia nel momento in cui arrivi. -Dietro, i tuoi agent emettono eventi tramite l'SDK, il collector li spedisce al tuo server Failproof AI Observability, e il flusso li traccia mentre arrivano nell'infrastruttura che controlli. Quando vuoi la vista aggregata invece della traccia grezza, gli eventi di ogni esecuzione si comprimono in una singola riga su Sessions, a un clic di distanza. +Dietro le quinte, i tuoi agent emettono eventi attraverso l'SDK, il collector li invia al tuo server Failproof AI Observability, e il flusso li traccia man mano che arrivano nell'infrastruttura che controlli. Quando vuoi la vista riepilogata invece della traccia grezza, gli eventi di ogni esecuzione si comprimono in una singola riga su Sessions, a un clic di distanza. -Questa è la fonte di verità grezza su cui si costruiscono tutte le altre superfici di osservazione, quindi quando un numero sembra sbagliato altrove, il flusso è dove confermi quello che è effettivamente accaduto. +Questa è la fonte di verità grezza su cui si costruiscono tutte le altre superfici di osservazione, quindi quando un numero sembra sbagliato altrove, il flusso è dove confermi cosa è realmente accaduto. -## Correlati +## Argomenti correlati -- [Sessions](/it/agenteye/sessions): gli stessi eventi aggregati in una riga per esecuzione, con un grafico di esecuzione in stile git. +- [Sessions](/it/agenteye/sessions): gli stessi eventi riepilogati in una riga per esecuzione, con un grafico di esecuzione in stile git. - [Telemetry](/it/agenteye/telemetry): quello che i tuoi agent inviano e come gli eventi raggiungono il flusso. -- [Error tracking](/it/agenteye/error-tracking): una singola superficie di triage per tutto quello che è andato male. +- [Error tracking](/it/agenteye/error-tracking): una superficie di triage unica per tutto ciò che è andato storto. - [Alerts](/it/agenteye/alerts): trasforma qualsiasi soglia in una regola di paging. - [CLI and agents](/it/agenteye/cli-and-agents): lo stesso flusso dal vivo dal tuo terminale. \ No newline at end of file diff --git a/docs/it/agenteye/hermes-capture.mdx b/docs/it/agenteye/hermes-capture.mdx index 23c48a6f..b3f12ada 100644 --- a/docs/it/agenteye/hermes-capture.mdx +++ b/docs/it/agenteye/hermes-capture.mdx @@ -1,53 +1,53 @@ --- -title: "Acquisizione della sessione Hermes" -description: "Porta le sessioni del gateway Hermes del tuo team — Slack, Telegram, CLI ed esecuzioni pianificate — in AgentEye come sessioni ed eventi ordinari." +title: "Acquisizione sessioni Hermes" +description: "Importa le sessioni del gateway Hermes del tuo team — Slack, Telegram, CLI e esecuzioni pianificate — in AgentEye come sessioni ed eventi ordinari." --- -[Hermes](https://hermes-agent.nousresearch.com) risponde al tuo team da qualsiasi luogo in cui già lavora — Slack, Telegram, CLI, esecuzioni pianificate. L'acquisizione della sessione Hermes porta tutto questo in AgentEye come sessioni ed eventi ordinari, in modo che l'assistente con cui il tuo team parla ogni giorno sia osservabile quanto gli agenti che scrivi tu stesso. +[Hermes](https://hermes-agent.nousresearch.com) risponde al tuo team da qualsiasi posto in cui già lavora — Slack, Telegram, la CLI, le esecuzioni pianificate. L'acquisizione di sessioni Hermes porta tutto questo in AgentEye come sessioni ed eventi ordinari, così l'assistente con cui il tuo team parla ogni giorno è osservabile tanto quanto gli agenti che scrivi tu stesso. -Un piccolo collector in background legge l'archivio di sessioni locale di Hermes mentre viene scritto e invia le sessioni ad AgentEye. Funziona allo stesso modo del capture di [Codex](/it/agenteye/codex-capture) e [OpenClaw](/it/agenteye/openclaw-capture), e un collector può acquisire più agenti contemporaneamente. +Un piccolo collettore in background legge l'archivio locale delle sessioni di Hermes man mano che viene scritto e invia le sessioni a AgentEye. Funziona allo stesso modo dell'acquisizione di [Codex](/it/agenteye/codex-capture) e [OpenClaw](/it/agenteye/openclaw-capture), e un collettore può acquisire più di uno contemporaneamente. --- ## Cosa acquisisce -Ogni sessione Hermes sulla macchina viene acquisita, da qualsiasi canale provenga. Ognuna diventa una [sessione](/it/agenteye/sessions) di AgentEye; i suoi messaggi di utente e assistente, le chiamate ai tool e i risultati dei tool diventano gli [eventi](/it/agenteye/event-stream) corrispondenti. +Ogni sessione Hermes sulla macchina viene acquisita, indipendentemente dal canale da cui proviene. Ognuna diventa una [sessione](/it/agenteye/sessions) di AgentEye; i suoi messaggi utente e assistente, le chiamate agli strumenti e i risultati degli strumenti diventano i corrispondenti [eventi](/it/agenteye/event-stream). -Il canale da cui è iniziata una sessione — Slack, Telegram, CLI o un'esecuzione pianificata — viene registrato sulla sessione, così puoi distinguerle e filtrare una alla volta. Insieme vengono il modello su cui è stata eseguita la sessione, la chat e la persona da cui è stata avviata, e, quando una sessione ha generato un'altra, il collegamento al suo genitore. +Il canale da cui ha avuto inizio una sessione — Slack, Telegram, CLI o un'esecuzione pianificata — viene registrato nella sessione, così puoi distinguerli e filtrare uno alla volta. Insieme a questo vengono il modello su cui è stata eseguita la sessione, la chat e la persona da cui è stata avviata, e, quando una sessione ne ha generata un'altra, il collegamento alla sua sessione genitore. -Le sessioni appaiono non appena Hermes le avvia, indipendentemente dal fatto che sia stato detto qualcosa, e la risposta di un turno e le sue chiamate ai tool mantengono l'ordine in cui effettivamente si sono verificate. Quando una sessione termina, ottieni anche il motivo della terminazione, il costo e quanti token ha utilizzato. +Le sessioni appaiono non appena Hermes le avvia, indipendentemente dal fatto che sia stato detto qualcosa o meno, e la risposta di un turno e le sue chiamate agli strumenti rimangono nell'ordine in cui si sono effettivamente verificate. Quando una sessione termina, ottieni anche il motivo della terminazione, il costo e quanti token ha utilizzato. --- -## Attivalo +## Attivarlo -L'acquisizione è disattivata finché non la abiliti. Installa il collector con una chiave API che dispone dell'autorizzazione `events:add` (vedi [Chiavi API](/it/agenteye/api-keys)) e attiva l'acquisizione di Hermes: +L'acquisizione è disattivata finché non la abiliti. Installa il collettore con una chiave API che ha il permesso `events:add` (vedi [Chiavi API](/it/agenteye/api-keys)) e attiva l'acquisizione di Hermes: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -Questo installa il collector, lo registra come servizio in background e avvia l'acquisizione. Conferma che è in esecuzione: +Questo installa il collettore, lo registra come servizio in background e avvia l'acquisizione. Conferma che è in esecuzione: ```bash agenteye-collector health ``` -Acquisendo più di un agente sulla stessa macchina? Aggiungi il flag di ognuno allo stesso comando — ad esempio `--hermes-enabled --codex-enabled`. +Acquisire più di un agente sulla stessa macchina? Aggiungi il flag di ognuno allo stesso comando — ad esempio `--hermes-enabled --codex-enabled`. -Al primo avvio, le tue sessioni Hermes esistenti vengono riportate una sola volta e la nuova attività viene trasmessa in streaming entro pochi secondi. I dati di Hermes stesso vengono solo letti — mai modificati o eliminati — e ogni messaggio viene inviato una sola volta, anche tra i riavvii. +Alla prima esecuzione, le tue sessioni Hermes esistenti vengono caricate una sola volta e la nuova attività viene trasmessa entro pochi secondi. I dati di Hermes vengono solo letti — mai modificati o eliminati — e ogni messaggio viene inviato una volta sola, anche attraverso i riavvii. -`health` ti dice anche se tutto ciò che il collector ha acquisito è effettivamente arrivato ad AgentEye. Se un batch non può essere consegnato, viene mantenuto e ritentato piuttosto che scartato, e il controllo segnala uno stato non integro mentre c'è ancora qualcosa in sospeso — quindi "integro" significa che i tuoi dati sono arrivati, non semplicemente che il processo è attivo. +`health` ti dice anche se tutto ciò che il collettore ha acquisito è effettivamente arrivato in AgentEye. Se un batch non può essere consegnato, viene mantenuto e riprovato anziché scartato, e il controllo segnala uno stato non sano finché c'è ancora qualcosa in sospeso — quindi "sano" significa che i tuoi dati sono arrivati, non solo che il processo è attivo. --- -## Dove compare +## Dove appare -Le sessioni acquisite appaiono in **Sessions**, e i loro eventi nel flusso **Events**, esattamente come qualsiasi altro agente che osservi — quindi [session replay](/it/agenteye/sessions), [ricerca](/it/agenteye/queries), [valutazioni](/it/agenteye/evaluations) e [avvisi](/it/agenteye/alerts) funzionano tutti su di esse. Filtra per l'agente Hermes per vederle da sole. +Le sessioni acquisite appaiono in **Sessions**, e i loro eventi nel flusso **Events**, come qualsiasi altro agente che osservi — quindi [session replay](/it/agenteye/sessions), [ricerca](/it/agenteye/queries), [valutazioni](/it/agenteye/evaluations) e [avvisi](/it/agenteye/alerts) funzionano tutti su di esse. Filtra per l'agente Hermes per vederle da sole. --- ## Privacy -Le sessioni di Hermes contengono la trascrizione completa — incluso l'output dei comandi, i contenuti dei file e tutto ciò che l'agente ha letto o scritto — e possono contenere segreti. Le sessioni acquisite vengono inviate così come sono, quindi abilita l'acquisizione solo dove centralizzare quel contenuto in AgentEye è appropriato, e fornisci al collector una chiave limitata a `events:add` solamente. Vedi [Security](/it/agenteye/security) per scoprire come i tuoi dati vengono mantenuti isolati. \ No newline at end of file +Le sessioni Hermes contengono la trascrizione completa — incluso l'output dei comandi, i contenuti dei file e tutto ciò che l'agente ha letto o scritto — e possono contenere segreti. Le sessioni acquisite vengono inviate così come sono, quindi abilita l'acquisizione solo dove centralizzare quel contenuto in AgentEye è appropriato, e assegna al collettore una chiave limitata a `events:add` soltanto. Vedi [Security](/it/agenteye/security) per scoprire come i tuoi dati vengono mantenuti isolati. \ No newline at end of file diff --git a/docs/it/agenteye/incidents.mdx b/docs/it/agenteye/incidents.mdx index d0cea46d..f9704d42 100644 --- a/docs/it/agenteye/incidents.mdx +++ b/docs/it/agenteye/incidents.mdx @@ -1,27 +1,27 @@ --- -title: "Incidents" -description: "Quando scatta un alert, tutti vedono che l'incident è aperto, chi lo gestisce e cosa è successo finora — in un'unica timeline attribuita." +title: "Incidenti" +description: "Quando un avviso si attiva, tutti possono vedere che l'incidente è aperto, chi ne è responsabile e cosa è accaduto finora — su una timeline unica e attribuita." --- -Quando scatta un alert, la prima domanda è sempre "chi se ne occupa?". Gli Incidents rispondono a questa domanda: nel momento in cui qualcosa viene rilevato, tutti possono vedere che l'incident è aperto, chi lo gestisce, e esattamente cosa è successo finora, con un registro pulito e attribuito che puoi usare direttamente in una post-mortem. +Quando un avviso si attiva, la prima domanda è sempre "chi se ne sta occupando?" Gli incidenti rispondono a questa domanda: nel momento in cui qualcosa viene rilevato, tutti possono vedere che l'incidente è aperto, chi ne è responsabile e esattamente cosa è accaduto finora, con un registro pulito e attribuito che puoi consegnare direttamente a un post-mortem. -![La inbox degli Incidents: card di incident collegati agli alert e aperti manualmente, raggruppati per stato, ciascuno con un badge di severità e un assegnatario](/agenteye/images/incidents.png) -*La inbox raggruppa gli incident aperti per stato e filtra per severità e assegnatario, così vedi cosa ha bisogno di un intervento umano adesso.* +![La casella di posta Incidenti: schede di incidenti collegati agli avvisi e aperti manualmente, raggruppati per stato, ciascuno con un badge di gravità e un assegnatario](/agenteye/images/incidents.png) +*La casella di posta raggruppa gli incidenti aperti per stato e filtra per gravità e assegnatario, così vedi cosa necessita l'intervento umano adesso.* -## Sapere chi se ne occupa, a colpo d'occhio +## Sapere chi se ne sta occupando, a colpo d'occhio -Niente più "qualcuno sta guardando questo?" in un thread di chat. Una rilevazione apre un incident automaticamente e lo inserisce in una inbox condivisa, raggruppato per stato. Riconoscilo e il tuo nome è su di esso, così il resto del team sa che è gestito. Il riconoscimento è condiviso: diversi operatori possono riconoscere lo stesso incident e ognuno viene registrato a parte, quindi un'intera war room appare per nome invece di calpestarvisi addosso. Assegna un proprietario per il triage, e filtra la inbox per severità o assegnatario per ridurla a quello che è tuo. +Niente più "qualcuno sta guardando questo?" in un thread di chat. Una violazione apre automaticamente un incidente e lo inserisce in una casella di posta condivisa, raggruppato per stato. Riconoscilo e il tuo nome è su di esso, così il resto del team sa che è gestito. Il riconoscimento è condiviso: più operatori possono riconoscere lo stesso incidente e ciascuno viene registrato separatamente, quindi un'intera war room appare nominativamente invece di sovrapporsi. Assegna un proprietario per il triage e filtra la casella di posta per gravità o assegnatario per ridurla a quello che è tuo. -## L'intera storia, in una sola timeline +## L'intera storia, su una timeline -Quando l'incident è finito, hai già il rapporto. Apri un incident qualsiasi e ottieni l'evidenza della rilevazione, i suoi assegnatari e sottoscrittori, un thread di commenti per coordinare sul posto, e una timeline di attività in sola aggiunta. +Quando l'incidente è finito, hai già la documentazione. Apri un qualsiasi incidente e ottieni la prova della violazione, i suoi assegnatari e sottoscrittori, un thread di commenti per coordinare sul posto, e una timeline di attività in sola aggiunta. -![Una vista dei dettagli dell'incident: l'alert principale e il riepilogo della rilevazione, assegnatari e sottoscrittori, una timeline di attività attribuita, e un thread di commenti](/agenteye/images/incident-detail.png) +![Una vista dettagliata dell'incidente: l'avviso principale e il riepilogo della violazione, assegnatari e sottoscrittori, una timeline di attività attribuita e un thread di commenti](/agenteye/images/incident-detail.png) *Tutto ciò che è accaduto, in ordine, ogni riga firmata da chi l'ha fatto.* -Ogni azione (aperto, riconosciuto, risolto, e così via) viene scritta in quella timeline e non viene mai modificata. Ogni entry è attribuita: all'operatore che l'ha eseguita, via email, o a **automated** per tutto ciò che Failproof AI Observability ha fatto da solo, come aprire l'incident sulla rilevazione. Nulla è anonimo e nulla va perso, quindi la post-mortem più o meno si scrive da sola. +Ogni azione (aperto, riconosciuto, risolto, e così via) viene scritta su quella timeline e non viene mai modificata. Ogni voce è attribuita: all'operatore che l'ha eseguita, tramite email, o ad **automated** per qualsiasi cosa abbia fatto Failproof AI Observability autonomamente, come aprire l'incidente sulla violazione. Nulla è anonimo e nulla è perso, quindi il post-mortem più o meno si scrive da solo. -## Come si muove un incident +## Come si muove un incidente ```mermaid stateDiagram-v2 @@ -32,18 +32,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **Open (firing):** la rilevazione apre l'incident e pagina i tuoi canali una volta. Rilevazioni ripetute si uniscono allo stesso incident e aggiornano l'evidenza invece di pagarti ancora e ancora. -- **Acknowledged:** un operatore se ne occupa. Rimane aperto, e successivamente le rilevazioni aggiornano l'evidenza silenziosamente. -- **Resolved:** un operatore lo chiude. La risoluzione automatica quando la condizione si cancella è pianificata ma non ancora abilitata, quindi un incident rimane aperto fino a quando un umano lo risolve, il che tiene tutti onesti riguardo a ciò che è effettivamente stato cancellato. Un incident nuovo può aprirsi sulla stessa regola in seguito. +- **Open (firing):** la violazione apre l'incidente e avvisa i tuoi canali una volta. Le violazioni ripetute si uniscono nello stesso incidente e aggiornano la sua prova invece di avvisarti ancora e ancora. +- **Acknowledged:** un operatore se ne occupa. Rimane aperto, e le violazioni successive aggiornano la prova silenziosamente. +- **Resolved:** un operatore lo chiude. La risoluzione automatica quando la condizione si cancella è pianificata ma non ancora abilitata, quindi un incidente rimane aperto finché un umano non lo risolve, il che mantiene tutti onesti su cosa sia effettivamente stato risolto. Un incidente nuovo può aprirsi sullo stesso avviso in seguito. -Un alert contiene al massimo un incident aperto alla volta, quindi una regola instabile non può sommergerti di duplicati. Puoi anche aprire un incident manualmente: uno autonomo per qualcosa che nessun alert ha catturato, oppure uno collegato a un alert esistente, se hai `incidents:write`. +Un avviso contiene al massimo un incidente aperto alla volta, quindi una regola instabile non può sommergerti di duplicati. Puoi anche aprire un incidente manualmente: uno autonomo per qualcosa che nessun avviso ha rilevato, oppure uno collegato a un avviso esistente, se hai `incidents:write`. ## Dove trovarlo -Gli Incidents si trovano a `//incidents`. La visualizzazione richiede **`incidents:read`**; aprire un incident manuale richiede **`incidents:write`**; riconoscere, assegnare, commentare e risolvere richiedono **`incidents:ack`**. Le vecchie chiavi che hanno concesso il deprecated `alerts:ack` continuano a funzionare, poiché viene onorato come `incidents:ack`, quindi la tua rotazione on-call non ha bisogno di essere re-emessa. +Gli incidenti si trovano in `//incidents`. Visualizzare richiede **`incidents:read`**; aprire un incidente manuale richiede **`incidents:write`**; riconoscere, assegnare, commentare e risolvere richiedono **`incidents:ack`**. Le chiavi precedenti che concedevano il ritirato `alerts:ack` continuano a funzionare, poiché viene riconosciuto come `incidents:ack`, quindi la tua rotazione on-call non ha bisogno di essere riemessa. ## Correlati -- [Alerts](/it/agenteye/alerts): le regole che aprono questi incident quando una soglia viene superata. -- [Error tracking](/it/agenteye/error-tracking): vedi ogni errore in un unico posto e promuovi uno a alert. -- [Audits](/it/agenteye/audits): l'analista programmato che trova i guasti che nessuna regola stava controllando. \ No newline at end of file +- [Avvisi](/it/agenteye/alerts): le regole che aprono questi incidenti quando una soglia viene superata. +- [Error tracking](/it/agenteye/error-tracking): vedi ogni errore in un posto e promuovine uno a avviso. +- [Audits](/it/agenteye/audits): l'analista pianificato che trova gli errori che nessuna regola stava controllando. \ No newline at end of file diff --git a/docs/it/agenteye/observability.mdx b/docs/it/agenteye/observability.mdx index 79a41ead..93780aa4 100644 --- a/docs/it/agenteye/observability.mdx +++ b/docs/it/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- -title: "Observe" -description: "Le superfici di observe sono il luogo dove osservare quello che i tuoi agent stanno facendo in tempo reale e analizzare nel dettaglio ogni singola esecuzione." +title: "Osserva" +description: "Le superfici di osservazione sono dove puoi vedere cosa stanno facendo i tuoi agenti in tempo reale ed esaminare nel dettaglio qualsiasi singola esecuzione." --- -Le superfici di observe sono il luogo dove osservare quello che i tuoi agent stanno facendo in tempo reale e analizzare nel dettaglio ogni singola esecuzione. Tutto qui è live, limitato alla tua organizzazione, e filtrabile per intervallo di date, environment, agent e session, così passi da "qualcosa non sembra giusto" all'esecuzione esatta in pochi secondi. +Le superfici di osservazione sono dove puoi vedere cosa stanno facendo i tuoi agenti in tempo reale ed esaminare nel dettaglio qualsiasi singola esecuzione. Tutto qui è live, limitato alla tua organizzazione, e filtrabile per intervallo di date, ambiente, agente e sessione, così passi da "qualcosa non va" all'esecuzione esatta in pochi secondi. -![Lo stream di eventi live, con codifica a colori per tipo e filtrabile per environment, agent e session](/agenteye/images/events-stream.png) +![Lo stream di eventi live, codificato per colore per tipo e filtrabile per ambiente, agente e sessione](/agenteye/images/events-stream.png) Quattro superfici, ognuna con la sua pagina: -- **[Event stream](/it/agenteye/event-stream)**: la traccia live, passo dopo passo, di ogni esecuzione su ogni agent, più recenti per primi. La home della tua organizzazione e prima tappa per il triage. -- **[Sessions e execution graph](/it/agenteye/sessions)**: quegli eventi riepilogati in una riga per esecuzione, più una rappresentazione in stile git di come si è sviluppata ogni esecuzione. -- **[Performance metrics](/it/agenteye/telemetry)**: heat-map di latenza e vitals p50/p95/p99 per i tuoi modelli, tool e hook, così uno spike anomalo emerge dalla mediana. -- **[Error tracking](/it/agenteye/error-tracking)**: una superficie di triage unica per tutto quello che è andato storto, un click da un alert attivo all'esecuzione che ha causato il problema. +- **[Flusso di eventi](/it/agenteye/event-stream)**: il percorso live, passo dopo passo, di ogni esecuzione su ogni agente, i più recenti per primi. La home della tua organizzazione e la prima tappa per il triage. +- **[Sessioni e grafo di esecuzione](/it/agenteye/sessions)**: questi eventi riepilogati in una riga per esecuzione, più un'immagine in stile git di come si è svolta ogni esecuzione. +- **[Metriche di performance](/it/agenteye/telemetry)**: heat-map di latenza e valori vitali p50/p95/p99 per i tuoi modelli, strumenti e hook, così un picco di coda si distingue dalla mediana. +- **[Tracciamento degli errori](/it/agenteye/error-tracking)**: un'unica superficie di triage per tutto quello che è andato male, a un clic da un avviso attivo fino all'esecuzione che si è rotta. -## Correlati +## Correlato -- [Evaluations](/it/agenteye/evaluations): valuta ogni esecuzione per qualità. +- [Evaluations](/it/agenteye/evaluations): valuta ogni esecuzione per la qualità. - [Alerts](/it/agenteye/alerts): trasforma qualsiasi soglia in una regola di paging. -- [Audits](/it/agenteye/audits): lascia che Failproof AI Observability trovi pattern di errori tra le session per te. -- [CLI e agents](/it/agenteye/cli-and-agents): la stessa osservabilità dal tuo terminale. \ No newline at end of file +- [Audits](/it/agenteye/audits): lascia che Failproof AI Observability trovi per te i modelli di errore tra le sessioni. +- [CLI e agenti](/it/agenteye/cli-and-agents): la stessa osservabilità dal tuo terminale. \ No newline at end of file diff --git a/docs/it/agenteye/openclaw-capture.mdx b/docs/it/agenteye/openclaw-capture.mdx index 531e7456..f1d5be4c 100644 --- a/docs/it/agenteye/openclaw-capture.mdx +++ b/docs/it/agenteye/openclaw-capture.mdx @@ -1,49 +1,50 @@ --- -title: "Acquisizione di sessioni OpenClaw" -description: "Invia le sessioni locali di OpenClaw del tuo team in AgentEye come sessioni ed eventi ordinari — senza modificare il modo in cui OpenClaw funziona." +--- +title: "Cattura di sessioni OpenClaw" +description: "Monitora le sessioni locali OpenClaw del tuo team in AgentEye come sessioni ed eventi ordinari — senza alcun cambiamento nel modo in cui OpenClaw viene eseguito." --- -Se il tuo team utilizza [OpenClaw](https://docs.openclaw.ai), l'acquisizione di sessioni OpenClaw porta quelle sessioni in AgentEye come sessioni ed eventi ordinari, così puoi cercarle, riprodurle e valutarle insieme a tutto il resto che osservi. Completa l'[SDK Python](/it/agenteye/python-sdk): l'SDK strumenta gli agenti che scrivi, mentre questo cattura il lavoro OpenClaw che il tuo team già svolge — senza alcuna modifica al modo in cui lo eseguono. +Se il tuo team utilizza [OpenClaw](https://docs.openclaw.ai), la cattura di sessioni OpenClaw porta quelle sessioni in AgentEye come sessioni ed eventi ordinari, così puoi cercarle, riprodurle e valutarle insieme a tutto il resto che osservi. Complementa l'[SDK Python](/it/agenteye/python-sdk): l'SDK strumenta gli agenti che scrivi, mentre questo cattura il lavoro OpenClaw che il tuo team già esegue — senza alcun cambiamento nel modo in cui lo esegue. -Un piccolo collector in background legge i transcript locali delle sessioni di OpenClaw man mano che vengono scritti e li invia ad AgentEye. Funziona nello stesso modo della [acquisizione Codex](/it/agenteye/codex-capture), e un collector può acquisire entrambi contemporaneamente. +Un piccolo collector in background legge le trascrizioni locali delle sessioni OpenClaw mentre vengono scritte e le invia ad AgentEye. Funziona allo stesso modo della [cattura Codex](/it/agenteye/codex-capture), e un collector può catturare entrambe contemporaneamente. --- ## Cosa cattura -Ogni agente configurato nella configurazione OpenClaw di una macchina viene catturato dal collector di quella macchina — non c'è alcuna configurazione per singolo agente. +Ogni agente configurato nella configurazione OpenClaw di una macchina viene catturato dal collector di quella macchina — non esiste una configurazione per agente. -Ogni sessione OpenClaw diventa una [sessione](/it/agenteye/sessions) di AgentEye; i suoi messaggi utente e assistente, le chiamate di strumenti e i risultati degli strumenti diventano i corrispondenti [eventi](/it/agenteye/event-stream). +Ogni sessione OpenClaw diventa una [sessione](/it/agenteye/sessions) AgentEye; i suoi messaggi di utente e assistente, le chiamate ai tool e i risultati dei tool diventano i corrispondenti [eventi](/it/agenteye/event-stream). --- -## Attivalo +## Attivala -L'acquisizione è disattivata finché non la abiliti. Installa il collector con una chiave API che dispone dell'autorizzazione `events:add` (vedi [Chiavi API](/it/agenteye/api-keys)) e attiva l'acquisizione OpenClaw: +La cattura è disattivata finché non la abiliti. Installa il collector con una chiave API che ha il permesso `events:add` (vedi [Chiavi API](/it/agenteye/api-keys)), e attiva la cattura OpenClaw: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -Questo installa il collector, lo registra come servizio in background e inizia l'acquisizione. Conferma che è in esecuzione: +Questo installa il collector, lo registra come servizio in background e avvia la cattura. Conferma che sia in esecuzione: ```bash agenteye-collector health ``` -Stai acquisendo più di un agente sulla stessa macchina? Aggiungi il flag di ciascuno allo stesso comando — ad esempio `--openclaw-enabled --codex-enabled`. +Stai catturando più di un agente sulla stessa macchina? Aggiungi il flag di ognuno allo stesso comando — per esempio `--openclaw-enabled --codex-enabled`. -Al primo avvio, le tue sessioni OpenClaw esistenti vengono riempite una volta e la nuova attività viene trasmessa entro pochi secondi. I file di OpenClaw vengono solo letti — mai modificati, spostati o eliminati — e ogni sessione viene inviata esattamente una volta, anche attraverso i riavvii. +Alla prima esecuzione, le tue sessioni OpenClaw esistenti vengono caricate una volta e la nuova attività viene trasmessa in streaming entro pochi secondi. I file di OpenClaw vengono solo letti — mai modificati, spostati o eliminati — e ogni sessione viene inviata esattamente una volta, anche tra i riavvii. --- ## Dove appare -Le sessioni acquisite appaiono in **Sessions**, e i loro eventi nel flusso **Events**, come qualsiasi altro agente che osservi — quindi la [riproduzione della sessione](/it/agenteye/sessions), la [ricerca](/it/agenteye/queries), le [valutazioni](/it/agenteye/evaluations) e gli [avvisi](/it/agenteye/alerts) funzionano tutti su di essi. Filtra per l'agente OpenClaw per vederli da soli. +Le sessioni catturate appaiono in **Sessions**, e i loro eventi nello stream **Events**, esattamente come qualsiasi altro agente che osservi — quindi [la riproduzione di sessioni](/it/agenteye/sessions), [la ricerca](/it/agenteye/queries), [le valutazioni](/it/agenteye/evaluations) e [gli avvisi](/it/agenteye/alerts) funzionano tutti su di esse. Filtra per l'agente OpenClaw per vederle da sole. --- ## Privacy -I transcript di OpenClaw contengono la sessione completa — incluso l'output dei comandi, i contenuti dei file e qualsiasi cosa l'agente abbia letto o scritto — e possono contenere segreti. Le sessioni acquisite vengono inviate così come sono, quindi abilita l'acquisizione solo su macchine e per team dove centralizzare quel contenuto in AgentEye è appropriato, e fornisci al collector una chiave limitata a `events:add` solamente. Vedi [Sicurezza](/it/agenteye/security) per come i tuoi dati rimangono isolati. \ No newline at end of file +Le trascrizioni OpenClaw contengono la sessione completa — inclusi l'output dei comandi, i contenuti dei file e tutto ciò che l'agente ha letto o scritto — e possono contenere segreti. Le sessioni catturate vengono inviate così come sono, quindi abilita la cattura solo su macchine e per team dove centralizzare quel contenuto in AgentEye è appropriato, e fornisci al collector una chiave limitata solo a `events:add`. Vedi [Security](/it/agenteye/security) per come i tuoi dati vengono mantenuti isolati. \ No newline at end of file diff --git a/docs/it/agenteye/overview.mdx b/docs/it/agenteye/overview.mdx index 7fcb341e..63f60d38 100644 --- a/docs/it/agenteye/overview.mdx +++ b/docs/it/agenteye/overview.mdx @@ -1,107 +1,107 @@ --- -title: "Failproof AI: Osserva gli Agenti per Individuare i Fallimenti" -description: "Failproof AI Observability è una piattaforma self-hosted per osservare, valutare e migliorare i tuoi agenti AI in produzione." +title: "Failproof AI: Osserva gli Agent per i Fallimenti" +description: "Failproof AI Observability è una piattaforma self-hosted per osservare, valutare e migliorare i tuoi AI agent in produzione." --- -Failproof AI Observability è una piattaforma self-hosted per osservare, valutare e migliorare i tuoi agenti AI in produzione. Registra tutto quello che fanno i tuoi agenti (ogni chiamata a strumento, richiesta ai modelli, hook e errore), assegna un punteggio alla qualità di ogni esecuzione e mette in evidenza i fallimenti che non sapevi di dovere cercare, il tutto in una dashboard che esegui direttamente nella tua infrastruttura. +Failproof AI Observability è una piattaforma self-hosted per osservare, valutare e migliorare i tuoi AI agent in produzione. Registra tutto ciò che i tuoi agent fanno (ogni chiamata a strumento, richiesta al modello, hook ed errore), assegna un punteggio alla qualità di ogni esecuzione e mette in evidenza i fallimenti che non sapevi di dover cercare, il tutto in una dashboard che esegui all'interno della tua infrastruttura. -Se distribuisci agenti AI e sei stanco di indovinare perché un'esecuzione è andata male, questa è la pagina giusta da cui iniziare. Spiega cosa Failproof AI Observability ti offre e come i vari componenti si incastrano insieme, prima di installare qualsiasi cosa. +Se distribuisci AI agent e sei stanco di indovinare perché un'esecuzione è andata male, questa è la pagina da cui iniziare. Spiega cosa ti offre Failproof AI Observability e come i vari componenti si incastrano insieme, prima che tu installi nulla. > **Failproof AI Observability è un prodotto enterprise di Failproof AI.** Vuoi vederlo in azione? Richiedi una demo: invia un'email a [nikita@befailproof.ai](mailto:nikita@befailproof.ai). -![Una sessione di Failproof AI Observability disegnata come un grafo di esecuzione in stile git accanto alla sua timeline degli eventi, con una ripartizione per esecuzione di strumenti, modelli e hook nella colonna di destra](/agenteye/images/session-detail.png) +![Una sessione di Failproof AI Observability disegnata come un grafo di esecuzione nello stile di git accanto alla sua timeline degli eventi, con una suddivisione per esecuzione di strumenti, modelli e hook nella barra laterale destra](/agenteye/images/session-detail.png) -*Ogni esecuzione dell'agente è disegnata come un grafo di esecuzione in stile git (sinistra) accanto alla sua timeline degli eventi. I sub-agenti paralleli ottengono ciascuno la loro corsia; la colonna di destra suddivide gli strumenti, i modelli, gli hook e la spesa di token per l'esecuzione.* +*Ogni esecuzione di agent è disegnata come un grafo di esecuzione nello stile di git (sinistra) accanto alla sua timeline degli eventi. Ogni sub-agent parallelo ha la sua corsia; la barra laterale destra suddivide gli strumenti, i modelli, gli hook e la spesa di token per l'esecuzione.* --- ## Vedi in azione -Due brevi video mostrano le due cose che i team cercano per primi: tracciare un'esecuzione e trovare i fallimenti automaticamente. +Due brevi video mostrano le due cose che i team cercano per prime: tracciare un'esecuzione e trovare i fallimenti automaticamente.
- +
-*Tracciamento dell'agente: segui una singola esecuzione passo dopo passo, dall'obiettivo agli strumenti alla risposta finale.* +*Tracciamento dell'agent: segui un'esecuzione singola passo dopo passo, dall'obiettivo agli strumenti alla risposta finale.*
- +
-*Failproof Audit: lascia che Failproof AI Observability esamini i tuoi log tra le sessioni e ti dica cosa sistemare.* +*Failproof Audit: lascia che Failproof AI Observability esamini i tuoi log tra le sessioni e ti dica cosa risolvere.* --- -## Perché i team lo usano +## Perché i team la usano -- **Vedi cosa ha effettivamente fatto il tuo agente.** Ogni esecuzione diventa un grafo di esecuzione leggibile in stile git: quali strumenti hanno girato in parallelo, quali sub-agenti si sono ramificati, dove si è fermato e quanto ha speso. -- **Rileva le regressioni di qualità automaticamente.** Connetti un piccolo servizio di scoring e Failproof AI Observability assegna un punteggio a ogni esecuzione completata, in modo che un calo di utilità o un picco di allucinazioni si noti da solo. -- **Trova i fallimenti per cui non hai scritto una regola.** Gli audit ricorrenti analizzano i tuoi log tra le sessioni alla ricerca di cluster di errori, outlier di latenza, punteggi bassi ed esecuzioni bloccate, quindi ti consegnano scoperte classificate e supportate da prove. -- **Ricevi notifiche quando conta davvero.** Le regole di soglia si attivano sulla base di tasso di errore, latenza, costo o punteggi degli evaluator e aprono incident che puoi riconoscere, assegnare e risolvere. -- **Fai domande in linguaggio naturale.** Un assistente AI all'interno della dashboard risponde a domande come "come sta andando la qualità in produzione questa settimana?" sui tuoi dati. Qualsiasi modifica effettuata è sottoposta ad approvazione. -- **Mantieni i tuoi dati.** Failproof AI Observability è self-hosted: gli eventi, i prompt e l'analisi rimangono nell'infrastruttura che controlli. +- **Vedi cosa ha effettivamente fatto il tuo agent.** Ogni esecuzione diventa un grafo di esecuzione leggibile nello stile di git: quali strumenti sono stati eseguiti in parallelo, quali sub-agent si sono diramati, dove si è bloccato e quanto ha speso. +- **Cattura regressioni di qualità automaticamente.** Connetti un piccolo servizio di scoring e Failproof AI Observability assegna un punteggio a ogni esecuzione completata, così una diminuzione di utilità o un picco di allucinazioni appare da solo. +- **Trova fallimenti per i quali non hai scritto una regola.** Gli audit ricorrenti esaminano i tuoi log tra le sessioni per cluster di errori, outlier di latenza, punteggi bassi e esecuzioni bloccate, quindi ti forniscono risultati classificati e supportati da prove. +- **Ricevi una notifica quando conta.** Le regole di soglia si attivano su tasso di errore, latenza, costo o punteggi di valutazione e aprono incidenti che puoi riconoscere, assegnare e risolvere. +- **Fai domande in inglese semplice.** Un assistente AI nel dashboard risponde a Come sta andando la qualità in produzione questa settimana? sui tuoi dati. Qualsiasi modifica viene sottoposta a gate di approvazione. +- **Mantieni i tuoi dati.** Failproof AI Observability è self-hosted: eventi, prompt e analytics rimangono nell'infrastruttura che controlli. --- -## Cosa ottieni +## Quello che ottieni -Failproof AI Observability è organizzato attorno a tre concetti (**osserva**, **analizza** e **amministra**), rispecchiati nella barra laterale sinistra della dashboard. +Failproof AI Observability è organizzato attorno a tre idee (**osserva**, **analizza** e **admin**), rispecchiate nella barra laterale sinistra del dashboard. -**Osserva** (la verità grezza di cosa è successo): +**Osserva** (la verità grezza di ciò che è accaduto): -- **[Flusso di eventi](/it/agenteye/event-stream)**: il trail live, passo dopo passo, di ogni esecuzione (chiamate a strumenti, chiamate ai modelli, hook, errori). -- **[Sessioni](/it/agenteye/sessions)**: quegli eventi consolidati in una riga per esecuzione, ognuno pronto per essere assegnato un punteggio, con un grafo di esecuzione in stile git. -- **[Metriche di performance](/it/agenteye/telemetry)**: heatmap di latenza per superficie e vitali p50/p95/p99 per modelli, strumenti e hook, in modo che un picco di coda risalti dalla mediana. -- **[Tracciamento degli errori](/it/agenteye/error-tracking)**: una superficie di triage unica per tutto ciò che è andato storto, a un clic da un alert che si attiva. +- **[Flusso di eventi](/it/agenteye/event-stream)**: il percorso live, passo dopo passo, di ogni esecuzione (chiamate a strumenti, chiamate a modelli, hook, errori). +- **[Sessioni](/it/agenteye/sessions)**: quegli eventi riepilogati in una riga per esecuzione, ognuno pronto per essere valutato, con un grafo di esecuzione nello stile di git. +- **[Metriche di prestazione](/it/agenteye/telemetry)**: mappe di calore di latenza per superficie e valori p50/p95/p99 per modelli, strumenti e hook, così un picco di coda emerge dalla mediana. +- **[Tracciamento degli errori](/it/agenteye/error-tracking)**: una superficie di triage per tutto ciò che è andato male, a un clic da un alert che si attiva. -![La pagina strumenti di osservazione: una heatmap di latenza, una banda percentile e una barra di distribuzione degli strumenti su 24 intervalli di tempo](/agenteye/images/tools.png) +![La pagina osserva Strumenti: una mappa di calore della latenza, una banda percentile e una barra di distribuzione dello strumento su 24 bin temporali](/agenteye/images/tools.png) -*Ogni superficie di osservazione associa una sparkline e vitali p50/p95/p99 con una heatmap di latenza e una banda percentile. Mostrato qui: Strumenti.* +*Ogni superficie osserva abbina uno sparkline e valori p50/p95/p99 con una mappa di calore della latenza e una banda percentile. Mostrato qui: Strumenti.* **Analizza** (trasforma l'attività in risposte): -- **[Query](/it/agenteye/queries)** e **[dashboard](/it/agenteye/dashboards)**: SQL salvate sui tuoi eventi e valutazioni, rappresentate graficamente in dashboard condivise scoped all'organizzazione. -- **[Valutazioni](/it/agenteye/evaluations)**: punteggi di qualità prodotti dal tuo servizio di valutazione, con motivazioni per ogni punteggio. -- **[Audit](/it/agenteye/audits)**: indagini ricorrenti che rivelano pattern di fallimento tra le sessioni. -- **[Avvisi](/it/agenteye/alerts)** e **[incident](/it/agenteye/incidents)**: regole di soglia che ti notificano, più un flusso di lavoro per gli incident per triarli. +- **[Query](/it/agenteye/queries)** e **[dashboard](/it/agenteye/dashboards)**: SQL salvato sui tuoi eventi e valutazioni, visualizzato in dashboard condivisi e con ambito organizzativo. +- **[Valutazioni](/it/agenteye/evaluations)**: punteggi di qualità prodotti dal tuo servizio di valutazione, con ragionamento per ogni punteggio. +- **[Audit](/it/agenteye/audits)**: investigazioni ricorrenti che emergono dai pattern di fallimento tra le sessioni. +- **[Alert](/it/agenteye/alerts)** e **[incidenti](/it/agenteye/incidents)**: regole di soglia che ti avvisano, più un workflow di incidente per triargerli. -**Interfacce** (accedi ai tuoi dati come preferisci): +**Interfacce** (raggiungi i tuoi dati come preferisci): -- **[CLI](/it/agenteye/cli-and-agents)**: gestisci l'intera distribuzione dal terminale o da uno script, e lascia che un agente di codifica lo faccia per te in linguaggio naturale. -- **[Assistente AI](/it/agenteye/assistant)**: fai domande sui tuoi agenti in linguaggio naturale, direttamente all'interno della dashboard. -- **API REST**: tutto quello che fa la dashboard e la CLI è supportato da un'API REST che puoi chiamare direttamente con una [chiave API](/it/agenteye/api-keys) scoped — ingesta eventi, interroga sessioni e valutazioni, e gestisci dashboard, avvisi, audit, utenti e chiavi, in modo da poter integrare Failproof AI Observability nel tuo tooling. +- **[CLI](/it/agenteye/cli-and-agents)**: guida tutta la tua distribuzione dal terminale o da uno script, e lascia che un coding agent lo faccia per te in inglese semplice. +- **[Assistente AI](/it/agenteye/assistant)**: fai domande sui tuoi agent in inglese semplice, direttamente dentro il dashboard. +- **API REST**: tutto ciò che il dashboard e la CLI fanno è supportato da un'API REST che puoi chiamare direttamente con una [chiave API](/it/agenteye/api-keys) con ambito - acquisire eventi, interrogare sessioni e valutazioni, gestire dashboard, alert, audit, utenti e chiavi, così puoi integrare Failproof AI Observability nei tuoi strumenti. -**Amministra** (gestiscilo per il tuo team): +**Admin** (gestiscilo per il tuo team): -- **[Chiavi API](/it/agenteye/api-keys)**: token scoped per il collector, la dashboard e l'assistente. -- **Utenti**: accesso passwordless basato su email con allowlist. -- **Impostazioni**: configurazione per organizzazione, inclusi override della finestra di contesto dei modelli. +- **[Chiavi API](/it/agenteye/api-keys)**: token con ambito per il collector, il dashboard e l'assistente. +- **Utenti**: accesso senza password basato su email con una lista di permessi. +- **Impostazioni**: configurazione per organizzazione, incluse override del context window del modello. --- ## Come i pezzi si incastrano -I dati fluiscono in una direzione, dal codice del tuo agente alla dashboard: il tuo agente (tramite Python SDK) emette eventi ad agenteye-collector, che li invia al server, che serve la dashboard. Due servizi opzionali la completano — un servizio di scoring (valutazioni) e un servizio assistente AI (la chat all'interno della dashboard). +I dati fluiscono in una direzione, dal tuo codice agent al dashboard: il tuo agent (tramite Python SDK) emette eventi ad agenteye-collector, che li invia al server, che serve il dashboard. Due servizi opzionali lo completano — un servizio di scoring (valutazioni) e un servizio di assistente AI (la chat nel dashboard). -- **Python SDK**: aggiungi poche chiamate `agenteye.event.*` al tuo agente; gli eventi sono memorizzati in buffer localmente. -- **agenteye-collector**: un daemon leggero su ogni macchina agente che raggruppa gli eventi e li invia al server. -- **Server**: ingesta i tuoi eventi, mantiene lo stato operativo nei tuoi database e serve l'API REST che la dashboard, la CLI e le tue integrazioni usano. +- **Python SDK**: aggiungi alcune chiamate `agenteye.event.*` al tuo agent; gli eventi vengono memorizzati nel buffer localmente. +- **agenteye-collector**: un daemon leggero su ogni macchina agent che raggruppa gli eventi e li invia al server. +- **Server**: acquisisce i tuoi eventi, mantiene lo stato operativo nei tuoi database e serve l'API REST che il dashboard, la CLI e le tue stesse integrazioni utilizzano. - **Dashboard**: dove esplori tutto. -- **Servizi opzionali**: un servizio di scoring (valutazioni) e un servizio assistente AI (la chat all'interno della dashboard). +- **Servizi opzionali**: un servizio di scoring (valutazioni) e un servizio di assistente AI (la chat nel dashboard). -Per il vocabolario utilizzato in tutta la documentazione (*event, session, evaluation, audit, finding, incident*), vedi [Concetti](/it/agenteye/concepts). +Per il vocabolario utilizzato in tutta la documentazione (*evento, sessione, valutazione, audit, risultato, incidente*), vedi [Concetti](/it/agenteye/concepts). --- ## Ottenere Failproof AI Observability -Failproof AI Observability è un prodotto enterprise di Failproof AI, e funziona insieme a Failproof AI Enforcement — il prodotto di policy e guardrail — sotto il marchio Failproof AI. Funziona interamente nel tuo ambiente. Se non hai ancora accesso ai pacchetti, richiedi una demo e ti faremo partire: invia un'email a [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Failproof AI Observability è un prodotto enterprise di Failproof AI e funziona insieme a Failproof AI Enforcement — il prodotto di policy e guardrail — sotto il marchio Failproof AI. Gira interamente nel tuo ambiente. Se non hai ancora accesso ai pacchetti, richiedi una demo e ti aiuteremo a configurare: invia un'email a [nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- -## Passaggi successivi +## Prossimi passaggi -- [Concetti](/it/agenteye/concepts): il vocabolario di Failproof AI Observability in un'unica pagina. -- [Observability](/it/agenteye/observability): segui quello che fanno i tuoi agenti, esecuzione per esecuzione. +- [Concetti](/it/agenteye/concepts): il vocabolario di Failproof AI Observability in un solo posto. +- [Observability](/it/agenteye/observability): segui cosa fanno i tuoi agent, esecuzione per esecuzione. - [Sicurezza](/it/agenteye/security): come Failproof AI Observability mantiene i tuoi dati isolati e sotto il tuo controllo. \ No newline at end of file diff --git a/docs/it/agenteye/python-sdk-skill.mdx b/docs/it/agenteye/python-sdk-skill.mdx index d46dc12e..c0415f7c 100644 --- a/docs/it/agenteye/python-sdk-skill.mdx +++ b/docs/it/agenteye/python-sdk-skill.mdx @@ -1,77 +1,77 @@ --- --- title: "Failproof AI Observability Python SDK Agent Skill" -description: "Da un agente senza strumentazione a eventi che puoi visualizzare, con il tuo agente di codifica che trova i punti di strumentazione, li scrive e verifica che siano stati implementati." +description: "Da un agente non strumentato agli eventi che puoi vedere, con il tuo agente di codifica che trova i punti di strumentazione, li scrive e verifica che siano stati implementati." --- -Dì al tuo agente di codifica *"aggiungi Failproof AI Observability a questo agente"* e lascia che legga il tuo loop, determini dove deve andare la strumentazione, la scriva e verifichi gli eventi prima di dichiarare il lavoro completato. +Dì al tuo agente di codifica *"aggiungi Failproof AI Observability a questo agente"* e lascia che legga il tuo loop, scopra dove appartiene la strumentazione, la scriva e verifichi gli eventi prima di concludere il lavoro. -La **skill Python SDK** (`agenteye-python-sdk`) è una *Agent Skill*: una cartella di istruzioni che un agente di codifica come Claude Code o Codex carica on demand quando un'attività corrisponde. Insegna all'agente come usare [Python SDK](/it/agenteye/python-sdk) — non è una libreria e non cambia nulla nel funzionamento dell'SDK. +La **skill Python SDK** (`agenteye-python-sdk`) è un *Agent Skill*: una cartella di istruzioni che un agente di codifica come Claude Code o Codex carica su richiesta quando un'attività corrisponde. Insegna all'agente come usare l'[SDK Python](/it/agenteye/python-sdk) — non è una libreria e non cambia nulla su come funziona l'SDK. ## La strumentazione è facile da scrivere e facile da sbagliare silenziosamente -L'SDK è piccolo: tredici metodi di evento, tutti solo keyword. Un agente di codifica può leggere il riferimento [Python SDK](/it/agenteye/python-sdk) e produrre una strumentazione plausibile in un minuto. +L'SDK è piccolo: tredici metodi di evento, tutti solo keyword. Un agente di codifica può leggere il riferimento dell'[SDK Python](/it/agenteye/python-sdk) e produrre una strumentazione plausibile in un minuto. -Il problema è che questo SDK non solleva eccezioni quando sbagli, e la strumentazione sbagliata assomiglia esattamente a quella giusta finché qualcuno non apre un dashboard e lo trova vuoto. Gli errori che consumano tempo sono tutti silenzi: +Il problema è che questo SDK non solleva un'eccezione quando sbagli, e una strumentazione scorretta sembra esattamente come quella corretta finché qualcuno non apre una dashboard e la trova vuota. Gli errori che costano tempo reale sono tutti silenzi: -| L'errore | Quello che vedi | +| L'errore | Cosa vedi | |---|---| | Nessun `agent_start` | Ogni evento arriva. Zero sessioni. | | Ambiente mai impostato | Tutto funziona, archiviato sotto `dev`. | | `outcome="failure"` | L'esecuzione appare verde — solo `failed`, `error`, `timeout`, `rejected` contano. | -| Un nome di campo con typo | Accettato e archiviato come nuovo campo. | +| Un nome campo con errore di digitazione | Accettato e memorizzato come nuovo campo. | | Eventi emessi da un thread pool | Silenziosamente scartati. | -Nessuno di questi solleva eccezioni. Nessuno appare nei test. Ognuno è nella skill, enunciato come contratto con il controllo che lo cattura. +Nessuno di questi solleva un'eccezione. Nessuno appare nei test. Ogni uno è nella skill, dichiarato come contratto con il controllo che lo cattura. -## Quello che fa, in ordine +## Cosa fa, in ordine La skill esegue gli stessi tre passaggi che farebbe un ingegnere attento: -1. **Pianificazione.** Legge il tuo loop di agente e pone le due domande a cui solo tu puoi rispondere: cosa conta come un'esecuzione (il tuo `session_id`) e chi sono gli attori distinguibili (il tuo `agent_id`). Raggiunge un accordo su queste questioni prima di scrivere codice, perché cambiarle in seguito dividerà la tua cronologia e romperà i trend. -2. **Scrittura.** Associa l'identità una volta per esecuzione piuttosto che trascinandola attraverso ogni sito di chiamata, e sceglie una forma thread-safe — un dettaglio importante, perché il collegamento ovvio silenziosamente mescola due esecuzioni sovrapposte in una sessione. -3. **Verifica.** Esegue il tuo agente e legge i file di evento risultanti, verificando che `agent_start` sia presente, l'ambiente sia corretto e che un'esecuzione abbia prodotto una sessione. +1. **Pianifica.** Legge il tuo agent loop e pone le due domande a cui solo tu puoi rispondere: cosa conta come un'esecuzione (il tuo `session_id`) e chi sono gli attori distinguibili (il tuo `agent_id`). Ottiene il consenso su questi prima di scrivere codice, perché cambiarli in seguito divide la tua cronologia e rompe i trend. +2. **Scrivi.** Lega l'identità una volta per esecuzione piuttosto che trasmetterla attraverso ogni sito di chiamata, e sceglie una forma sicura per la concorrenza — un dettaglio che conta, perché il collegamento ovvio silenziosamente mescola due esecuzioni sovrapposte in una sessione. +3. **Verifica.** Esegue il tuo agente e legge i file di eventi risultanti, controllando che `agent_start` sia presente, l'ambiente sia corretto e un'esecuzione abbia prodotto una sessione. -Questo terzo passaggio è quello che la gente salta. L'SDK scrive eventi in file locali, quindi un'integrazione completa può essere provata su un laptop senza server, senza chiave API e senza rete — ed è esattamente per questo che la skill insiste nel farlo. +Quel terzo passaggio è quello che le persone saltano. L'SDK scrive eventi in file locali, quindi un'integrazione completa può essere provata su un laptop senza server, senza chiave API e senza rete — che è esattamente il motivo per cui la skill insiste nel farlo. -## Come si relaziona con le altre skill +## Come si relaziona alle altre skill -Tre skill, una separazione netta: +Tre skill, una divisione pulita: -| Skill | Usala quando | Cosa modifica | +| Skill | Usala quando | Cosa tocca | |---|---|---| -| **Python SDK skill** (questa pagina) | Vuoi che il tuo agente *emetta* telemetria — "aggiungi observability", "perché il mio agente non appare?" | Scrive codice nel repo del tuo agente. Non legge nulla. | -| **[Evaluator skill](/it/agenteye/evaluator-skill)** | Vuoi *valutare* le esecuzioni — "cosa dovremmo misurare?" | Scrive codice nel tuo repo; legge telemetria | -| **[CLI skill](/it/agenteye/cli-skill)** | Vuoi *leggere* cosa è successo, o gestire il tuo deployment | Guida la CLI come te, incluse le modifiche | +| **Python SDK skill** (questa pagina) | Vuoi che il tuo agente *emetta* telemetria — "aggiungi osservabilità", "perché il mio agente non appare?" | Scrive codice nel repo del tuo agente. Non legge nulla. | +| **[Evaluator skill](/it/agenteye/evaluator-skill)** | Vuoi *valutare* le esecuzioni — "cosa dovremmo persino misurare?" | Scrive codice nel tuo repo; legge telemetria | +| **[CLI skill](/it/agenteye/cli-skill)** | Vuoi *leggere* cosa è successo, o gestire il tuo deployment | Gestisce la CLI al tuo posto, inclusi i cambiamenti | -Si passano il testimone in quest'ordine: questa skill fa fluire gli eventi, l'evaluator li valuta, la CLI li legge indietro. Non c'è nulla da valutare e nulla da leggere finché il tuo agente non emette sessioni, quindi se inizi da zero, inizia da qui. +Si passano il testimone in questo ordine: questa skill fa fluire gli eventi, l'evaluator li valuta, la CLI li legge indietro. Non c'è nulla da valutare e nulla da leggere finché il tuo agente non emette sessioni, quindi se stai iniziando da zero, inizia qui. ## Prerequisiti -1. **Python 3.10+** e la codebase dell'agente che vuoi strumentare. -2. **L'SDK.** È distribuito ai clienti come wheel privato piuttosto che da un indice pubblico — l'onboarding spiega come ottenerlo e installarlo. La skill conosce il percorso di installazione e ti chiederà piuttosto che indovinare se non lo trova. -3. **Nient'altro.** Nessun login al dashboard, nessuna chiave API, nessuna rete. La skill verifica contro i file di evento che l'SDK scrive, quindi può terminare e provare il suo lavoro offline. +1. **Python 3.10+** e la base di codice dell'agente che vuoi strumentare. +2. **L'SDK.** È distribuito ai clienti come wheel privata piuttosto che da un indice pubblico — il tuo onboarding copre come ottenerlo e installarlo. La skill conosce il percorso di installazione e ti chiederà piuttosto che indovinare se non lo trova. +3. **Nient'altro.** Nessun login alla dashboard, nessuna chiave API, nessuna rete. La skill verifica i file di evento che l'SDK scrive, quindi può finire e provare il suo lavoro offline. ## Dove ottenerla -La skill si trova nella collezione pubblica [`FailproofAI/skills`](https://github.com/FailproofAI/skills): +La skill vive nella raccolta pubblica [`FailproofAI/skills`](https://github.com/FailproofAI/skills): ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -Aggiungi `-g` per installarla per ogni progetto invece che solo per quello corrente, e `--copy` se il tuo ambiente non segue i symlink. Per Codex, passa `-a codex`. +Aggiungi `-g` per installarla per ogni progetto invece che solo per quello attuale, e `--copy` se il tuo ambiente non segue i symlink. Per Codex, passa `-a codex`. ## Installarla manualmente -Agent Skills sono cartelle contenenti un `SKILL.md` più riferimenti. Se preferisci non usare l'installer: +Le Agent Skills sono cartelle contenenti un `SKILL.md` più riferimenti. Se preferisci non usare l'installer: -- **Claude Code**: copia la cartella `agenteye-python-sdk/` in `~/.claude/skills/` (ogni progetto) o `/.claude/skills/` (solo quel repo). Claude Code la scopre automaticamente — controlla la lista `/skills`, o chiedile semplicemente qualcosa che corrisponda. -- **Codex**: Codex legge lo stesso `SKILL.md`. Il `agents/openai.yaml` incluso imposta `allow_implicit_invocation: true`, quindi è auto-selezionato quando un'attività corrisponde; altrimenti invocalo come `$agenteye-python-sdk`. +- **Claude Code**: copia la cartella `agenteye-python-sdk/` in `~/.claude/skills/` (ogni progetto) o `/.claude/skills/` (solo quel repo). Claude Code la scopre automaticamente — controlla l'elenco `/skills`, o chiedi semplicemente qualcosa che la corrispondi. +- **Codex**: Codex legge lo stesso `SKILL.md`. Il file `agents/openai.yaml` bundled imposta `allow_implicit_invocation: true`, quindi viene selezionato automaticamente quando un'attività corrisponde; altrimenti invocalo come `$agenteye-python-sdk`. -Esegui il tuo agente **nel repository contenente il codice che vuoi strumentare** — la skill legge il tuo loop di agente prima di proporre qualcosa. +Esegui il tuo agente **nel repository che contiene il codice che vuoi strumentare** — la skill legge il tuo agent loop prima di proporre qualsiasi cosa. -## Che aspetto ha una sessione +## Come appare una sessione ```text you ▸ Add Failproof AI Observability to this agent. @@ -104,29 +104,29 @@ agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and Want me to fix those too? ``` -Il pattern da notare: ha letto il codice prima di proporre, ha posto solo le domande a cui puoi rispondere, ha riutilizzato un id che avevi già, ha scelto la forma thread-safe *perché* ha visto un thread pool, e **ha verificato leggendo gli eventi effettivi** piuttosto che dichiarare il successo — quindi ha segnalato l'unico posto dove sapeva che fallirebbe silenziosamente. +Il pattern da notare: ha letto il codice prima di proporre, ha fatto solo le domande a cui tu puoi rispondere, ha riutilizzato un id che avevi già, ha scelto la forma sicura per la concorrenza *perché* ha visto un thread pool, e **ha verificato leggendo gli eventi effettivi** piuttosto che dichiarare il successo — quindi ha segnalato l'unico posto dove sapeva che fallirebbe silenziosamente. -## Quello che puoi chiederle +## Cosa puoi chiederle -- *"Perché il mio agente non appare nel dashboard?"* → percorre la scala: gli eventi vengono scritti, c'è `agent_start`, l'ambiente è giusto, il collector legge lo stesso posto. -- *"Tutto sta atterrando sotto dev."* → l'ambiente non è mai stato impostato, oppure è stato resettato da una chiamata successiva. -- *"Aggiungi token tracking."* → trova il tuo wrapper LLM e registra il modello, la ragione di stop e l'utilizzo. -- *"Strumenta anche i sub-agenti."* → una sessione, etichette di agente distinte, nidificate sotto il loro genitore. -- *"Scrivi test per la strumentazione."* → punta l'SDK a una directory temporanea e asserisce sugli eventi che ha scritto. +- *"Perché il mio agente non appare sulla dashboard?"* → percorre la scala: gli eventi vengono scritti, c'è `agent_start`, l'ambiente è giusto, il collector legge lo stesso posto. +- *"Tutto sta arrivando sotto dev."* → l'ambiente non è mai stato impostato, o è stato ripristinato da una chiamata successiva. +- *"Aggiungi tracciamento dei token."* → trova il tuo wrapper LLM e registra modello, motivo di arresto e utilizzo. +- *"Strumenta anche i sub-agenti."* → una sessione, etichette agente distinte, annidate sotto il loro genitore. +- *"Scrivi test per la strumentazione."* → punta l'SDK a una directory temporanea e afferma gli eventi che ha scritto. -## Cosa guardare +## Cosa tenere d'occhio -**Lascia che verifichi.** Il passaggio che rende questa skill utile è l'ultimo — eseguire il tuo agente e leggere gli eventi indietro. Un agente che scrive strumentazione e si ferma ha fatto la metà facile, e la metà che fallisce silenziosamente è l'altra. +**Lascia che verifichi.** Il passaggio che rende questa skill utile è l'ultimo — eseguire il tuo agente e leggere gli eventi indietro. Un agente che scrive la strumentazione e si ferma ha fatto la metà facile, e la metà che fallisce silenziosamente è l'altra. -**Accordati sui nomi prima del codice.** `session_id` e `agent_id` sono gli assi in base ai quali ogni superficie raggruppa. Rinominarli dopo divide la cronologia: le vecchie esecuzioni conservano le vecchie etichette e i tuoi trend si rompono. La skill chiederà; la risposta vale un minuto di riflessione. +**Concorda i nomi prima del codice.** `session_id` e `agent_id` sono gli assi su cui ogni superficie si raggruppa. Rinominarli in seguito divide la cronologia: le vecchie esecuzioni mantengono le vecchie etichette e i tuoi trend si rompono. La skill chiederà; la risposta vale un minuto di riflessione. **Se il tuo agente propone di installare l'SDK da un indice pubblico, la skill non è stata caricata.** L'SDK è distribuito privatamente. Quella proposta è un indicatore affidabile che il tuo agente di codifica sta indovinando piuttosto che seguire la skill — fermalo lì e controlla che la skill sia installata. -Oltre a questo, il suo raggio di esplosione è piccolo: scrive codice nella tua directory di lavoro e file di evento dove lo indichi. Non legge nulla dal tuo deployment e non cambia nulla in esso. +Oltre a ciò, il suo raggio di scoppio è piccolo: scrive codice nella tua directory di lavoro e file di evento dove te lo dici. Non legge nulla dal tuo deployment e non cambia nulla su di esso. -## Prossimi passi +## Passaggi successivi -- **[Python SDK](/it/agenteye/python-sdk)**: il riferimento completo degli eventi — ogni tipo di evento e campo — dietro ciò che questa skill automatizza. -- **[Sessions](/it/agenteye/sessions)**: quello che la tua strumentazione produce una volta che gli eventi arrivano. -- **[Evaluator Agent Skill](/it/agenteye/evaluator-skill)**: il passo successivo una volta che le esecuzioni arrivano — valutarle. +- **[SDK Python](/it/agenteye/python-sdk)**: il riferimento di evento completo — ogni tipo di evento e campo — dietro a ciò che questa skill automatizza. +- **[Sessions](/it/agenteye/sessions)**: cosa produce la tua strumentazione una volta che gli eventi arrivano. +- **[Evaluator Agent Skill](/it/agenteye/evaluator-skill)**: il passo successivo una volta che le esecuzioni stanno arrivando — valutarle. - **[CLI Agent Skill](/it/agenteye/cli-skill)**: leggere la tua telemetria indietro. \ No newline at end of file diff --git a/docs/it/agenteye/python-sdk.mdx b/docs/it/agenteye/python-sdk.mdx index c36a2466..d8e37c7a 100644 --- a/docs/it/agenteye/python-sdk.mdx +++ b/docs/it/agenteye/python-sdk.mdx @@ -1,15 +1,13 @@ --- ---- title: "Python SDK" -description: "Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell'agente, chiamata di strumento, richiesta del modello, hook e intervento umano." +description: "Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell'agente, chiamata di strumento, richiesta di modello, hook e intervento umano." --- +Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell'agente, chiamata di strumento, richiesta di modello, hook e intervento umano. Failproof AI Observability Python SDK registra quella traccia dall'interno del codice dell'agente in modo da poter eseguire il debug, controllare e valutare cosa è successo. Usalo ogni volta che desideri che Failproof AI Observability osservi i tuoi agenti. -Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell'agente, chiamata di strumento, richiesta del modello, hook e intervento umano. L'SDK Python per l'Observability di Failproof AI registra questa traccia dall'interno del codice del tuo agente, così puoi eseguire il debug, audit e valutazione di ciò che è accaduto. Usalo ogni volta che vuoi che Failproof AI Observability osservi i tuoi agenti. - -Sotto il cofano, l'SDK scrive eventi strutturati in file JSONL locali e il daemon collector li preleva e li invia automaticamente alla piattaforma. Non devi gestire tu stesso questi file. +Sotto il cofano, l'SDK scrive eventi strutturati in file JSONL locali, e il daemon del collector li raccoglie e li invia automaticamente alla piattaforma. Non gestisci questi file da solo. -> **Consiglio:** Nuovo a Failproof AI Observability? Questa pagina è il riferimento completo degli eventi SDK. +> **Suggerimento:** Nuovo a Failproof AI Observability? Questa pagina è il riferimento completo degli eventi SDK.
@@ -19,7 +17,7 @@ Sotto il cofano, l'SDK scrive eventi strutturati in file JSONL locali e il daemo ## Installazione -L'SDK viene distribuito ai clienti come wheel privato piuttosto che da un indice di pacchetti pubblico. L'onboarding copre come ottenerlo, installarlo e pinarlo — parla con il tuo contatto Failproof AI se hai bisogno di accesso. +L'SDK è distribuito ai clienti come wheel privato piuttosto che da un indice di pacchetti pubblico. Il tuo onboarding copre come ottenerlo, installarlo e fissarlo — contatta il tuo referente Failproof AI se hai bisogno di accesso. Una volta installato, confermalo: @@ -27,11 +25,11 @@ Una volta installato, confermalo: python -c "import agenteye; print(agenteye.__version__)" ``` -Preferisci lasciare che un agente di codifica gestisca l'intera integrazione? L'[Agent Skill Python SDK](/it/agenteye/python-sdk-skill) conosce il percorso di installazione, pianifica i punti di strumentazione, li scrive e verifica che gli eventi arrivino. +Preferisci far fare l'integrazione completa a un agente di codifica? [Python SDK Agent Skill](/it/agenteye/python-sdk-skill) conosce il percorso di installazione, pianifica i punti di strumentazione, li scrive e verifica che gli eventi arrivino. --- -## Quick Start +## Guida rapida ```python import agenteye @@ -61,7 +59,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Strumentazione di una chiamata reale -In pratica racchiudi il tuo codice agente esistente. Circonda una chiamata al modello con `model_request` prima e `model_response` dopo, in modo che i due eventi abbracciamo la richiesta reale e Failproof AI Observability possa abbinarli: +In pratica avvolgi il codice dell'agente esistente. Delimita una chiamata del modello con `model_request` prima e `model_response` dopo, in modo che i due eventi coprano la richiesta reale e Failproof AI Observability possa associarli: ```python import anthropic @@ -96,11 +94,11 @@ agenteye.event.model_response( ) ``` -Racchiudi le chiamate ai strumenti allo stesso modo con `tool_use` e `tool_result`, riutilizzando uno stesso `tool_call_id` per la coppia. +Avvolgi le chiamate agli strumenti allo stesso modo con `tool_use` e `tool_result`, riutilizzando un unico `tool_call_id` nella coppia. -Ecco come appaiono questi eventi una volta raggiunto il dashboard, codificati per colore per tipo e filtrabili per ambiente, agente e sessione: +Ecco come appaiono questi eventi una volta raggiunto il dashboard, codificati per tipo e filtrabili per ambiente, agente e sessione: -![Lo stream live degli Events, codificato per colore per tipo di evento e filtrabile per ambiente, agente e sessione](/agenteye/images/events-stream.png) +![Il flusso di eventi live, codificato per tipo di evento e filtrabile per ambiente, agente e sessione](/agenteye/images/events-stream.png) --- @@ -108,58 +106,58 @@ Ecco come appaiono questi eventi una volta raggiunto il dashboard, codificati pe ```python agenteye.configure( - base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye - flush_interval=0.5, # float, seconds between flush cycles - environment=None, # str | None. Deployment environment label + base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME o ~/.agenteye + flush_interval=0.5, # float, secondi tra i cicli di flush + environment=None, # str | None. Etichetta dell'ambiente di distribuzione ) ``` -Chiamalo una volta prima di qualsiasi chiamata `event.*`. Sicuro da omettere; i valori predefiniti funzionano subito. Tutti gli argomenti sono solo keyword; passali per nome come mostrato sopra. +Chiama una volta prima di qualsiasi chiamata `event.*`. È sicuro ometterlo; i valori predefiniti funzionano subito. Tutti gli argomenti sono solo per parola chiave; passali per nome come mostrato sopra. -Quando `base_dir` è `None` (il valore predefinito), l'SDK legge `$AGENTEYE_HOME` se impostato, -altrimenti ricade a `~/.agenteye`. Questo corrisponde alla risoluzione del collector stesso, -quindi una singola variabile env `AGENTEYE_HOME` configura lo spool di eventi condiviso per entrambi -l'SDK e il collector. +Quando `base_dir` è `None` (l'impostazione predefinita), l'SDK legge `$AGENTEYE_HOME` se impostato, +altrimenti torna a `~/.agenteye`. Questo corrisponde alla risoluzione del collector stesso, +quindi una singola variabile di ambiente `AGENTEYE_HOME` configura lo spool degli eventi condiviso sia per +l'SDK che per il collector. --- ## Ambiente -Etichetta ogni evento con un ambiente di deployment (`production`, `staging`, `qa`, `canary`, ecc.). Impostalo una volta; l'SDK lo allega a ogni evento automaticamente. +Etichetta ogni evento con un ambiente di distribuzione (`production`, `staging`, `qa`, `canary`, ecc.). Impostalo una volta; l'SDK lo allega a ogni evento automaticamente. -**Opzione 1: via `configure()`:** +**Opzione 1: tramite `configure()`:** ```python agenteye.configure(environment="production") ``` -**Opzione 2: via variabile d'ambiente:** +**Opzione 2: tramite variabile di ambiente:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**Priorità:** `configure(environment=...)` prevale sulla variabile d'ambiente. Se nessuno è impostato, il valore predefinito è `"dev"`. +**Priorità:** `configure(environment=...)` prevale sulla variabile di ambiente. Se nessuno dei due è impostato, predefinito a `"dev"`. -Il valore dell'ambiente appare come filtro di prima classe nel dashboard ed è memorizzato sul server per query veloci. +Il valore dell'ambiente appare come filtro di prima classe nel dashboard ed è archiviato sul server per query veloci. -> **Avvertenza:** I valori dell'ambiente non devono contenere una virgola letterale `,`. I filtri del dashboard utilizzano multi-select separato da virgole sul filo (`?environment=prod,staging`), quindi un ambiente denominato `prod,blue` verrebbe diviso in due valori. Gli eventi con ambienti contenenti virgole vengono rifiutati al momento dell'ingestione. +> **Avvertenza:** I valori dell'ambiente non devono contenere una virgola letterale `,`. I filtri del dashboard utilizzano selezione multi-selezionata separata da virgola sul filo (`?environment=prod,staging`), quindi un ambiente denominato `prod,blue` verrebbe suddiviso in due valori. Gli eventi con ambienti contenenti virgole vengono rifiutati al momento dell'acquisizione. --- ## Dati e privacy -L'SDK registra solo i campi che tu esplicitamente passi. Prompt, messaggi, input e output dei strumenti e il contenuto del modello vengono catturati solo perché li consegni a una chiamata `event.*`. Nulla viene letto dal tuo processo o catturato implicitamente. Qualsiasi campo che lasci non impostato viene omesso dall'evento interamente; non viene scritto su disco. +L'SDK registra solo i campi che trasmetti esplicitamente. I prompt, i messaggi, gli input e output degli strumenti e il contenuto del modello vengono catturati solo perché li passate a una chiamata `event.*`. Nulla viene letto dal tuo processo o acquisito implicitamente. Qualsiasi campo che lasci non impostato viene omesso completamente dall'evento; non viene scritto su disco. -Questo rende la redazione tua scelta e tua responsabilità. Se un prompt o payload dello strumento contiene PII o segreti che preferisci non memorizzare, rimuovili o mascherali prima di passarli al metodo dell'evento. +Ciò rende la redazione una tua scelta e una tua responsabilità. Se un prompt o payload dello strumento contiene PII o segreti che preferiresti non archiviare, rimuovilo o mascheralo prima di trasmetterlo al metodo dell'evento. --- ## Riferimento degli eventi -La maggior parte degli eventi viene in coppie start/end che condividono un ID di correlazione: `tool_use` e `tool_result` condividono un `tool_call_id`, `hook_triggered` e `hook_completed` condividono un `hook_id`, e `human_wait` e `human_input` condividono un `input_id`. Emetti l'evento di inizio, fai il lavoro, poi emetti l'evento di fine con lo stesso ID. Failproof AI Observability abbina la coppia e calcola `duration_ms` per te, così non passi mai `duration_ms` da solo. +La maggior parte degli eventi viene in coppie start/end che condividono un ID di correlazione: `tool_use` e `tool_result` condividono un `tool_call_id`, `hook_triggered` e `hook_completed` condividono un `hook_id`, e `human_wait` e `human_input` condividono un `input_id`. Emetti l'evento di inizio, esegui il lavoro, quindi emetti l'evento di fine con lo stesso ID. Failproof AI Observability associa la coppia e calcola `duration_ms` per te, quindi non passi mai `duration_ms` da solo. -![Un grafo di esecuzione in stile git di una sessione accanto alla sua timeline degli eventi, ricostruito da eventi appaiati, con il pannello di breakdown strumento/modello/hook](/agenteye/images/session-detail.png) +![Il grafo di esecuzione nello stile git di una sessione accanto alla sua cronologia degli eventi, ricostruito dagli eventi associati, con il pannello di suddivisione strumento/modello/hook](/agenteye/images/session-detail.png) Tutti i metodi degli eventi richiedono questi due campi: @@ -181,7 +179,7 @@ agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - parent agent_id for nested agents + parent_id=None, # str | None - agent_id genitore per agenti annidati ) ``` @@ -204,14 +202,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -Emesso quando un agente invoca uno strumento. Accoppia con `tool_result`; l'SDK calcola automaticamente `duration_ms`. +Emesso quando un agente richiama uno strumento. Associa con `tool_result`; l'SDK calcola automaticamente `duration_ms`. ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", - tool_name="web_search", # str, required - tool_call_id="toolu_01", # str, required - correlation key for the matching tool_result + tool_name="web_search", # str, obbligatorio + tool_call_id="toolu_01", # str, obbligatorio - chiave di correlazione per il tool_result corrispondente input={"query": "..."}, # dict | None ) ``` @@ -220,17 +218,17 @@ agenteye.event.tool_use( ### `event.tool_result()` -Emesso quando uno strumento ritorna. Si correla con `tool_use` via `tool_call_id`. +Emesso quando uno strumento restituisce. Correla con `tool_use` tramite `tool_call_id`. ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # must match the prior tool_use + tool_call_id="toolu_01", # deve corrispondere al tool_use precedente output={"results": ["..."]}, # Any | None - error=None, # str | None - set if the tool raised - # duration_ms is computed automatically - do not pass it + error=None, # str | None - imposta se lo strumento ha sollevato un'eccezione + # duration_ms è calcolato automaticamente - non trasmetterlo ) ``` @@ -244,54 +242,54 @@ Emesso appena prima di inviare un prompt a un LLM. agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - any provider/model string; not validated - messages=[ # list[dict] | None - conversation turns + model="claude-sonnet-4-6", # str | None - qualsiasi stringa provider/modello; non convalidata + messages=[ # list[dict] | None - turni di conversazione {"role": "user", "content": "..."}, ], - system="You are helpful.", # Any | None - str or list of content blocks - tools=[ # list[dict] | None - tool schemas offered to the model + system="You are helpful.", # Any | None - str o elenco di blocchi di contenuto + tools=[ # list[dict] | None - schemi di strumenti offerti al modello {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -Le voci `messages` accettano sia un `content` di stringa semplice che Anthropic-style list-of-blocks `content`. I parametri di campionamento (`temperature`, `max_tokens`, ecc.) possono essere passati come kwargs extra. +Le voci di `messages` accettano sia `content` in stringa semplice che `content` in elenco di blocchi nello stile Anthropic. I parametri di campionamento (`temperature`, `max_tokens`, ecc.) possono essere passati come kwargs aggiuntivi. --- ### `event.model_response()` -Emesso quando l'LLM ritorna una risposta. +Emesso quando l'LLM restituisce una risposta. ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - any provider/model string; not validated + model="claude-sonnet-4-6", # str | None - qualsiasi stringa provider/modello; non convalidata stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None - content=[ # Any | None - str, or list of content blocks + content=[ # Any | None - str, o elenco di blocchi di contenuto {"type": "text", "text": "..."}, ], role="assistant", # str | None ) ``` -`content` accetta sia una stringa semplice (provider generici) che una lista di content blocks in stile Anthropic. Le chiamate ai strumenti vivono dentro `content` come blocchi `{"type": "tool_use", ...}`, senza un campo `tool_calls` separato. +`content` accetta sia una stringa semplice (provider generici) che un elenco di blocchi di contenuto nello stile Anthropic. Le chiamate agli strumenti si trovano all'interno di `content` come blocchi `{"type": "tool_use", ...}`, senza un campo `tool_calls` separato. --- ### `event.hook_triggered()` -Emesso quando un hook si attiva. Accoppia con `hook_completed`; l'SDK calcola automaticamente `duration_ms`. +Emesso quando un hook si attiva. Associa con `hook_completed`; l'SDK calcola automaticamente `duration_ms`. ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", - hook_name="pre_tool_use", # str, required - hook_id="hook-abc", # str, required - correlation key + hook_name="pre_tool_use", # str, obbligatorio + hook_id="hook-abc", # str, obbligatorio - chiave di correlazione trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -301,18 +299,18 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Emesso quando un hook termina. Si correla con `hook_triggered` via `hook_id`. +Emesso quando un hook termina. Correla con `hook_triggered` tramite `hook_id`. ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # must match the prior hook_triggered + hook_id="hook-abc", # deve corrispondere al hook_triggered precedente outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms is computed automatically - do not pass it + # duration_ms è calcolato automaticamente - non trasmetterlo ) ``` @@ -326,77 +324,77 @@ Emesso quando si verifica un errore non gestito. agenteye.event.error( session_id="run-001", agent_id="planner", - error_type="TimeoutError", # str, required - message="timed out", # str, required + error_type="TimeoutError", # str, obbligatorio + message="timed out", # str, obbligatorio traceback="Traceback...", # str | None ) ``` --- -## Eventi Human-in-the-Loop +## Eventi con intervento umano -Gli eventi human-in-the-loop ti danno visibilità sui momenti in cui una persona entra nell'esecuzione dell'agente (in attesa di approvazione, fornitura di input, pausa o arresto dell'agente). Ti permettono di misurare quanto tempo gli umani impiegano a rispondere (l'SDK calcola automaticamente `duration_ms` sugli eventi appaiati), audit chi ha messo in pausa o interrotto un agente, e di costruire flussi di lavoro di approvazione e supervisione che emergono nel dashboard. +Gli eventi con intervento umano ti danno visibilità sui momenti in cui una persona interviene nell'esecuzione dell'agente (in attesa di approvazione, fornendo input, mettendo in pausa o fermando l'agente). Ti consentono di misurare quanto tempo ci mette un umano a rispondere (l'SDK calcola automaticamente `duration_ms` sugli eventi associati), controllare chi ha messo in pausa o interrotto un agente e costruire flussi di lavoro di approvazione e controllo che vengono visualizzati nel dashboard. ### `event.human_wait()` -Emesso quando l'agente mette in pausa l'esecuzione per attendere che un umano fornisca input. Accoppia con `human_input`; l'SDK calcola automaticamente `duration_ms` (quanto tempo l'umano ha impiegato a rispondere). +Emesso quando l'agente sospende l'esecuzione in attesa che un umano fornisca input. Associa con `human_input`; l'SDK calcola automaticamente `duration_ms` (quanto tempo l'umano ha impiegato per rispondere). ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - correlation key for the matching human_input - prompt="Do you approve this action?", # str | None - the question shown to the human - options=["approve", "reject", "defer"], # list[str] | None - choices presented to the human - reason="approval_required", # str | None - why the agent is waiting + input_id="inp-abc", # str, obbligatorio - chiave di correlazione per il human_input corrispondente + prompt="Do you approve this action?", # str | None - la domanda mostrata all'umano + options=["approve", "reject", "defer"], # list[str] | None - scelte presentate all'umano + reason="approval_required", # str | None - perché l'agente sta aspettando ) ``` ### `event.human_input()` -Emesso quando un umano fornisce input e l'agente riprende. Si correla con `human_wait` via `input_id`. `duration_ms` viene calcolato automaticamente e non deve essere passato dal chiamante. +Emesso quando un umano fornisce input e l'agente riprende. Correla con `human_wait` tramite `input_id`. `duration_ms` viene calcolato automaticamente e non deve essere passato dal chiamante. ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - must match the prior human_wait - response="approve", # str | None - the human's answer (free text or selected option) - # duration_ms is computed automatically - do not pass it + input_id="inp-abc", # str, obbligatorio - deve corrispondere al human_wait precedente + response="approve", # str | None - la risposta dell'umano (testo libero o opzione selezionata) + # duration_ms è calcolato automaticamente - non trasmetterlo ) ``` ### `event.human_pause()` -Emesso quando un umano mette attivamente in pausa l'agente (ad es. tramite un controllo del dashboard). L'agente è sospeso ma non terminato. +Emesso quando un umano mette attivamente in pausa l'agente (ad es. tramite un controllo del dashboard). L'agente viene sospeso ma non terminato. ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - who paused the agent + user_id="usr_42", # str | None - chi ha messo in pausa l'agente ) ``` ### `event.human_interrupt()` -Emesso quando un umano arresta attivamente l'agente a metà dell'esecuzione. A differenza di `human_pause`, il lavoro dell'agente viene terminato piuttosto che sospeso. +Emesso quando un umano ferma attivamente l'agente durante l'esecuzione. A differenza di `human_pause`, il lavoro dell'agente viene terminato piuttosto che sospeso. ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - who interrupted the agent - at_step="tool_use:web_search", # str | None - what the agent was doing when stopped + user_id="usr_42", # str | None - chi ha interrotto l'agente + at_step="tool_use:web_search", # str | None - cosa stava facendo l'agente quando è stato fermato ) ``` --- -## Custom Fields +## Campi personalizzati Qualsiasi argomento di parola chiave extra viene aggiunto all'evento dopo i campi standard: @@ -406,32 +404,32 @@ agenteye.event.tool_use( agent_id="planner", tool_name="db_query", tool_call_id="toolu_02", - tenant_id="acme", # custom field - region="us-east-1", # custom field + tenant_id="acme", # campo personalizzato + region="us-east-1", # campo personalizzato ) ``` -`timestamp`, `type`, e `environment` sono riservati e sollevano `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passati come custom fields. `session_id` e `agent_id` sono parametri richiesti su ogni metodo dell'evento e non possono essere forniti una seconda volta; Python solleva `TypeError` se lo fai. Imposta l'ambiente con `configure(environment=...)` (o la variabile `AGENTEYE_ENVIRONMENT`) invece. +`timestamp`, `type` e `environment` sono riservati e generano `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passati come campi personalizzati. `session_id` e `agent_id` sono parametri obbligatori su ogni metodo di evento e non possono essere forniti una seconda volta; Python genera `TypeError` se lo fai. Invece imposta l'ambiente con `configure(environment=...)` (o la variabile `AGENTEYE_ENVIRONMENT`). -Mantieni i payload come JSON strutturato quando vuoi interrogare i loro campi. I valori che JSON non supporta nativamente — come datetime, UUID, decimali, set, byte o oggetti modello — vengono convertiti in stringhe in modo che la registrazione continui in sicurezza. +Mantieni i payload come JSON strutturato quando desideri interrogare i loro campi. I valori che JSON non supporta nativamente—come datetime, UUID, decimali, set, byte o oggetti modello—vengono convertiti in stringhe in modo che la registrazione continui in sicurezza. --- ## Come vengono scritti gli eventi -Gli eventi vengono memorizzati nel buffer in-process e svuotati su disco ogni `flush_interval` secondi (default 500 ms). Ogni flush scrive un file JSONL: +Gli eventi vengono memorizzati nel buffer in-processo e svuotati su disco ogni `flush_interval` secondi (predefinito 500 ms). Ogni svuotamento scrive un file JSONL: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Il collector guarda questa directory e carica i file automaticamente. Non hai bisogno di gestire questi file direttamente. +Il collector osserva questa directory e carica i file automaticamente. Non hai bisogno di gestire questi file direttamente. -Ogni file viene scritto atomicamente: l'SDK scrive in un file temporaneo e poi lo rinomina in posizione, quindi il collector non vede mai un file a metà della scrittura. Un flush finale è anche eseguito quando il tuo processo esce, quindi gli eventi memorizzati nell'intervallo finale non vengono persi. Se il collector è offline, gli eventi semplicemente si accumulano come file su disco e vengono inviati una volta che torna online. +Ogni file viene scritto atomicamente: l'SDK scrive in un file temporaneo e poi lo rinomina in posizione, quindi il collector non vede mai un file a metà scritto. Uno svuotamento finale viene eseguito anche quando il tuo processo esce, quindi gli eventi memorizzati nel buffer nell'ultimo intervallo non vanno persi. Se il collector è offline, gli eventi semplicemente si accumulano come file su disco e vengono inviati una volta che ritorna online. --- -## Prossimi step +## Passaggi successivi -- [Event stream](/it/agenteye/event-stream): guarda questi eventi arrivare in tempo reale, codificati per colore e filtrabili per ambiente, agente e sessione. -- [Sessions](/it/agenteye/sessions): vedi come gli eventi appaiati ricostruiscono ogni esecuzione dell'agente come un grafo di esecuzione e timeline. \ No newline at end of file +- [Event stream](/it/agenteye/event-stream): osserva questi eventi arrivare live, codificati per tipo e filtrabili per ambiente, agente e sessione. +- [Sessions](/it/agenteye/sessions): vedi come gli eventi associati ricostruiscono ogni esecuzione dell'agente come grafo di esecuzione e cronologia. \ No newline at end of file diff --git a/docs/it/agenteye/queries.mdx b/docs/it/agenteye/queries.mdx index c99b38bc..5594d7b5 100644 --- a/docs/it/agenteye/queries.mdx +++ b/docs/it/agenteye/queries.mdx @@ -1,55 +1,56 @@ --- title: "Query" -description: "Poni qualsiasi domanda sui dati del tuo agente e ottieni una risposta in pochi secondi." +description: "Fai qualsiasi domanda sui dati del tuo agente e ottieni una risposta in pochi secondi." --- -Poni qualsiasi domanda sui dati del tuo agente e ottieni una risposta in pochi secondi. Failproof AI Observability ti offre una libreria di query salvate e pronte all'uso sui tuoi eventi e valutazioni, così puoi partire da un esempio funzionante invece di un editor SQL vuoto. -![La libreria delle query salvate: una griglia di query riutilizzabili, sia preset built-in che personalizzati](/agenteye/images/queries.png) +Fai qualsiasi domanda sui dati del tuo agente e ottieni una risposta in pochi secondi. Failproof AI Observability ti offre una libreria di query salvate e pronte all'uso sui tuoi eventi e valutazioni, in modo da partire da un esempio funzionante invece che da un editor SQL vuoto. -*La tua libreria di query salvate in `//queries`: i preset built-in accanto alle query che il tuo team ha salvato.* +![La libreria delle query salvate: una griglia di query riutilizzabili, sia preset predefiniti che personalizzati](/agenteye/images/queries.png) + +*La tua libreria di query salvate su `//queries`: preset predefiniti accanto alle query che il tuo team ha salvato.* ## Parti da un preset, non da una pagina bianca -Non devi ricordare i nomi delle tabelle o scrivere SQL da zero. La libreria si apre con preset built-in per le domande che i team pongono più frequentemente, accanto alle query che il tuo team ha salvato e denominato. Scegline una che si avvicina a quello che cerchi e sarai già a metà strada verso la risposta. +Non devi ricordare i nomi delle tabelle o scrivere SQL da zero. La libreria si apre con preset predefiniti per le domande più frequenti del team, proprio accanto alle query che il tuo team ha salvato e nominato. Scegline una simile a quello che cerchi e sarai già a buon punto per ottenere una risposta. -Ogni query salvata ha ambito organizzativo e è condivisa, quindi le query utili che i tuoi colleghi scrivono diventano anche tue. Denominata una query e aggiunta una descrizione una volta, chiunque nella tua organizzazione può trovarla, eseguirla o fissarne i risultati in un dashboard in seguito. +Ogni query salvata ha ambito organizzativo ed è condivisa, quindi le query utili scritte dai tuoi colleghi diventano anche tue. Dopo aver nominato una query e aggiunto una descrizione, chiunque nella tua organizzazione può trovarla, eseguirla o ancorare i suoi risultati a una dashboard in seguito. -Trovalo in `//queries`. +La trovi su `//queries`. -## Regolala ed eseguila nel compositore SQL +## Modificala ed eseguila nel composer SQL -Apri qualsiasi query e arriverà nel compositore SQL, dove puoi modificarla e vedere la risposta immediatamente: nessuna esportazione, nessun andata e ritorno, nessuna attesa di qualcun altro. +Apri una qualsiasi query e ti ritroverai nel composer SQL, dove puoi regolarla e vedere la risposta immediatamente: niente export, niente round-trip, niente attese da altri. -![Il compositore di query SQL che esegue una query salvata, con una barra laterale dello schema e una griglia di risultati live](/agenteye/images/query-lab.png) +![Il composer di query SQL che esegue una query salvata, con una barra laterale dello schema e una griglia di risultati live](/agenteye/images/query-lab.png) -*Il compositore SQL: la tua query a sinistra, una barra laterale dello schema per non dimenticare mai un nome di colonna, e una griglia di risultati live sotto.* +*Il composer SQL: la tua query a sinistra, una barra laterale dello schema per non sbagliare mai un nome di colonna, e una griglia di risultati live sotto.* -- **Una barra laterale dello schema** illustra le tabelle analitiche e le loro colonne, così puoi strutturare una query senza cercare i nomi dei campi. -- **Una griglia di risultati live** restituisce le righe nel momento in cui le esegui, così iteri in pochi secondi anziché indovinare e riindovinare. -- **Progettato per sola lettura.** Le query vengono eseguite nel tuo event store e convalidate sul server: sono consentiti solo statement `SELECT` e `WITH`, con un timeout di statement e un limite di righe. Una query esplorativa non può mai modificare i tuoi dati e una che si impalla viene fermata per te. +- **Una barra laterale dello schema** che espone le tabelle di analisi e le loro colonne, in modo da poter scrivere una query senza cercare i nomi dei campi. +- **Una griglia di risultati live** che restituisce le righe non appena esegui, così iteri in pochi secondi anziché indovinare e indovinare di nuovo. +- **Design di sola lettura.** Le query vengono eseguite sul tuo event store e validate sul server: sono consentite solo istruzioni `SELECT` e `WITH`, con un timeout dell'istruzione e un limite di righe. Una query esplorativa non può mai modificare i tuoi dati, e una che sfugge di mano viene fermata per te. -Soddisfatto del risultato? Salvalo nella libreria in modo che l'intero team lo erediti, oppure fissa il suo output in un dashboard come un tile lineare, a barre, ad area o a torta. +Soddisfatto del risultato? Salvalo di nuovo nella libreria in modo che l'intero team lo erediti, o ancora il suo output su una dashboard come tile lineare, a barre, area o torta. -## Eseguile dal terminale, o lascia che l'assistente le scriva +## Eseguili dal terminale, o lascia che l'assistente li scriva -Le stesse query salvate ti seguono ovunque lavori: +Le stesse query salvate ti seguono ovunque tu lavori: -- **Dal terminale.** La CLI `agenteye` elenca, esegue e salva le stesse identiche query, così puoi inserire un risultato in uno script, collegarlo in CI o passarlo a un agente di codifica. +- **Dal terminale.** La CLI `agenteye` elenca, esegue e salva le stesse query, in modo da poter incollare un risultato in uno script, integrarlo in CI, o passarlo a un agente di codifica. ```bash agenteye query list # le stesse query salvate, dal tuo terminale -agenteye query run errs --arg prod # eseguine una e stampa le righe (aggiungi --json per usarla in pipe) +agenteye query run errs --arg prod # esegui una e stampa le righe (aggiungi --json per pipare) ``` - Vedi [CLI e agenti](/it/agenteye/cli-and-agents) per l'insieme completo di comandi. + Vedi [CLI e agenti](/it/agenteye/cli-and-agents) per l'elenco completo dei comandi. -- **Dall'assistente AI.** Non sei sicuro di come formulare l'SQL? Chiedi all'[assistente AI](/it/agenteye/assistant) nel dashboard in inglese naturale e ti farà uno schema della query e la salverà nella tua libreria per te. +- **Dall'assistente AI.** Non sei sicuro di come formulare l'SQL? Chiedi all'[assistente AI](/it/agenteye/assistant) nella dashboard in linguaggio naturale e bozzerà la query e la salverà nella tua libreria per te. -L'esecuzione di una query salvata è controllata dal permesso `queries:run`, mantenuto separato dai permessi per creare o eliminare query, così puoi concedere accesso in lettura senza permettere a tutti di riscrivere la libreria. +L'esecuzione di una query salvata è controllata dal permesso `queries:run`, separato dai permessi per creare o eliminare query, in modo da poter concedere l'accesso in lettura senza lasciare che tutti riscritto la libreria. ## Correlati -- [Dashboard](/it/agenteye/dashboards): fissa i risultati delle query in grafici condivisi a livello organizzativo. -- [Assistente AI](/it/agenteye/assistant): poni domande in inglese naturale e ottieni una query in cambio. +- [Dashboard](/it/agenteye/dashboards): ancora i risultati delle query in grafici condivisi a livello organizzativo. +- [Assistente AI](/it/agenteye/assistant): fai domande in linguaggio naturale e ottieni una query. - [CLI e agenti](/it/agenteye/cli-and-agents): esegui e salva le stesse query dal tuo terminale. \ No newline at end of file diff --git a/docs/it/agenteye/security.mdx b/docs/it/agenteye/security.mdx index d1409f0a..28424fe1 100644 --- a/docs/it/agenteye/security.mdx +++ b/docs/it/agenteye/security.mdx @@ -1,68 +1,68 @@ --- title: "Sicurezza" -description: "Failproof AI Observability è costruito per stare vicino ai tuoi agenti in produzione, il che significa che vede i tuoi prompt, gli input degli strumenti e gli output." +description: "Failproof AI Observability è progettato per stare a stretto contatto con i tuoi agenti in produzione, il che significa che vede i tuoi prompt, gli input dei tool e gli output." --- -Failproof AI Observability è costruito per stare vicino ai tuoi agenti in produzione, il che significa che vede i tuoi prompt, gli input degli strumenti e gli output. Questa pagina spiega come mantiene questi dati isolati, controllati e nelle tue mani. Se stai valutando Failproof AI Observability per una revisione di sicurezza, inizia da qui. +Failproof AI Observability è progettato per stare a stretto contatto con i tuoi agenti in produzione, il che significa che vede i tuoi prompt, gli input dei tool e gli output. Questa pagina spiega come mantiene i dati isolati, controllati e nelle tue mani. Se stai valutando Failproof AI Observability per una revisione della sicurezza, inizia da qui. --- ## I tuoi dati rimangono nel tuo ambiente -Failproof AI Observability è self-hosted. Gli eventi, i prompt, le risposte del modello e l'analitca sono memorizzati nei tuoi database, nel tuo ambiente. Nessun dato viene inviato a un servizio SaaS di terze parti per l'archiviazione, e i tuoi dati rimangono nel tuo account cloud. +Failproof AI Observability è self-hosted. Gli eventi, i prompt, le risposte del modello e l'analittica sono archiviati nei tuoi database, nel tuo ambiente. Nulla viene inviato a un SaaS di terze parti per l'archiviazione, e i tuoi dati rimangono nel tuo account cloud. --- ## Isolamento dei tenant -Un'istanza di Failproof AI Observability può ospitare molte organizzazioni, ognuna isolata a livello di storage — applicato dal database, non solo dall'interfaccia utente: +Un'unica istanza di Failproof AI Observability può ospitare molte organizzazioni, ciascuna isolata a livello di storage — applicato dal database, non solo dall'interfaccia utente: -- I dati operativi di un'organizzazione (utenti, chiavi, dashboard, query salvate) sono vincolati a quell'organizzazione, e le letture cross-org sono bloccate dal database stesso. +- I dati operativi di un'organizzazione (utenti, chiavi, dashboard, query salvate) sono limitati a quell'organizzazione, e le letture cross-org sono bloccate dal database stesso. - Ogni evento acquisito è contrassegnato con l'organizzazione proprietaria, quindi gli eventi di un'organizzazione non possono mai essere letti da un'altra. -Ogni rotta della dashboard è vincolata sotto uno slug dell'organizzazione (`//…`). +Ogni rotta della dashboard è limitata sotto uno slug org (`//…`). --- ## Accesso -Failproof AI Observability utilizza l'accesso senza password basato su email. Non c'è alcuna password da phishare o perdere. Un utente richiede un codice monouso (o un link magic a un click), che gli viene inviato per email e scade rapidamente. L'accesso è controllato da una **lista di whitelist**: solo gli indirizzi email (o i domini) che permetti possono autenticarsi. +Failproof AI Observability utilizza un accesso senza password basato su email. Non c'è alcuna password da phishing o da divulgare. Un utente richiede un codice monouso (o un magic link con un clic), che gli viene inviato via email e scade rapidamente. L'accesso è controllato da una **lista di permessi**: solo gli indirizzi email (o domini) che permetti possono autenticarsi. ![La schermata di accesso di Failproof AI Observability, che invia un codice monouso alla tua email](/agenteye/images/login.png) --- -## Accesso con ambito limitato con chiavi API +## Accesso limitato con chiavi API -Ogni client si autentica con una chiave API che possiede permessi granulari e con il principio del minimo privilegio. Un collector ha bisogno solo di `events:add`; una chiave dashboard o assistant può essere di sola lettura; le azioni distruttive (eliminazione, rigenerazione) sono grant separati che scegli di includere. +Ogni client si autentica con una chiave API che porta permessi granulari e con privilegio minimo. Un collector ha bisogno solo di `events:add`; una chiave dashboard o assistant può essere di sola lettura; le azioni distruttive (delete, regenerate) sono grant separati che scegli di includere. -![La pagina delle chiavi API: i grant di permessi di ogni chiave, codificati per colore in base all'ambito di lettura, scrittura e distruttività](/agenteye/images/api-keys.png) +![La pagina delle chiavi API: i grant di permessi di ogni chiave, codificati per colore per scope di lettura, scrittura e distruttivo](/agenteye/images/api-keys.png) -Mantieni la chiave bootstrap dell'admin per la configurazione e emetti chiavi ristrette per tutto il resto. Vedi [Chiavi API](/it/agenteye/api-keys). +Conserva la chiave di bootstrap admin per la configurazione, e rilascia chiavi ristrette per tutto il resto. Vedi [API keys](/it/agenteye/api-keys). --- ## Un assistente di sola lettura e controllato da approvazione -L'[assistente AI](/it/agenteye/assistant) nel dashboard risponde a domande sui tuoi dati, ma è vincolato da design: +L'[assistente AI](/it/agenteye/assistant) in-dashboard risponde a domande sui tuoi dati, ma è vincolato dalla progettazione: -- È **di sola lettura per impostazione predefinita**: il suo SQL viene eseguito attraverso una guardia che consente solo query `SELECT`/`WITH`, a singola istruzione, con un limite di righe. -- Tutto quello che crea (una query salvata, una dashboard) è **controllato dall'approvazione**: esamini e approvi ogni scrittura prima che accada. +- È **di sola lettura per impostazione predefinita**: il suo SQL passa attraverso una guardia che consente solo query `SELECT`/`WITH`, single-statement, con un limite di righe. +- Qualsiasi cosa crei (una query salvata, una dashboard) è **controllata da approvazione**: rivedi e approvi ogni scrittura prima che accada. - **Non può mai eliminare**. -Quindi un collega può chiedere "quali agenti hanno avuto il maggior numero di errori questa settimana?" e agire in base alla risposta, senza che l'assistente sia in grado di modificare o rimuovere i tuoi dati da solo. +Così un collega può chiedere "quali agenti hanno avuto più errori questa settimana?" e agire sulla risposta, senza che l'assistente sia in grado di cambiare o rimuovere i tuoi dati di sua iniziativa. --- ## In transito -Tutto il traffico avviene su HTTPS. Termini TLS con i tuoi certificati, quindi il traffico da collector a server e da browser a server è crittografato in transito. +Tutto il traffico funziona su HTTPS. Termini TLS con i tuoi certificati, quindi il traffico collector-to-server e browser-to-server è crittografato in transito. --- -## Passaggi successivi +## Prossimi passi -- [Panoramica](/it/agenteye/overview): come Failproof AI Observability si collega insieme. -- [Chiavi API](/it/agenteye/api-keys): limita l'accesso per il collector, la dashboard e l'assistente. -- [Observability](/it/agenteye/observability): cosa cattura Failproof AI Observability dai tuoi agenti. \ No newline at end of file +- [Panoramica](/it/agenteye/overview): come Failproof AI Observability funziona insieme. +- [Chiavi API](/it/agenteye/api-keys): limitare l'accesso per il collector, dashboard e assistente. +- [Observability](/it/agenteye/observability): cosa Failproof AI Observability acquisisce dai tuoi agenti. \ No newline at end of file diff --git a/docs/it/agenteye/sessions.mdx b/docs/it/agenteye/sessions.mdx index ff568271..07a50aa6 100644 --- a/docs/it/agenteye/sessions.mdx +++ b/docs/it/agenteye/sessions.mdx @@ -1,57 +1,57 @@ --- -title: "Sessioni e Grafico di Esecuzione" -description: "Ogni evento da un'esecuzione, tutto in una riga leggibile e visualizzato come un grafico di esecuzione in stile git che puoi leggere in pochi secondi." +title: "Sessioni & Grafo di Esecuzione" +description: "Ogni evento di un'esecuzione, compattato in una riga leggibile e visualizzato come un grafo di esecuzione in stile git che puoi capire in secondi." --- -Smetti di indovinare perché un'esecuzione è fallita. Failproof AI Observability raggruppa ogni evento da un'esecuzione in una riga leggibile, poi disegna l'intera esecuzione come un'immagine in stile git che puoi leggere in pochi secondi, così vedi esattamente cosa ha fatto il tuo agent, passo dopo passo. +Smetti di indovinare perché un'esecuzione è fallita. Failproof AI Observability compatta ogni evento di un'esecuzione in una riga leggibile, poi disegna l'intera esecuzione come un diagramma in stile git che puoi leggere in secondi, così vedi esattamente cosa ha fatto il tuo agente, passo dopo passo. -![L'elenco delle Sessioni: una riga per esecuzione, tra ambienti e agent, con badge di stato e valutazione](/agenteye/images/sessions-list.png) +![L'elenco delle sessioni: una riga per esecuzione, tra ambienti e agenti diversi, con badge di stato e punteggi di valutazione](/agenteye/images/sessions-list.png) -*Una riga per esecuzione: il badge di stato ti dice come è terminata l'esecuzione a prima vista, e un badge di punteggio appare quando è collegato un valutatore.* +*Una riga per esecuzione: il badge di stato ti dice come è terminata l'esecuzione a prima vista, e un badge di punteggio appare una volta connesso un valutatore.*
-*Tracciamento dell'agent: segui una singola esecuzione passo dopo passo, dal goal agli strumenti alla risposta finale.* +*Tracciamento dell'agente: segui una singola esecuzione passo dopo passo, dall'obiettivo ai tool alla risposta finale.* --- -## Vedi ogni esecuzione a prima vista +## Visualizza ogni esecuzione a prima vista -Il percorso degli eventi grezzi è la verità di ogni passo, ma quando hai migliaia di passi su dozzine di esecuzioni, ti serve l'esecuzione, non il passo. La pagina Sessions raggruppa tutti gli eventi di un'esecuzione in una riga, così un giorno di attività diventa un elenco scansionabile invece di un diluvio di informazioni. +La traccia grezza degli eventi è la verità di ogni passaggio, ma quando hai migliaia di passaggi su dozzine di esecuzioni, ti serve l'esecuzione, non il singolo passaggio. La pagina delle Sessioni compatta tutti gli eventi di un'esecuzione in una riga, così un giorno di attività diventa un elenco scorrevole invece di una valanga di informazioni. -Ogni riga ha un badge di stato, quindi un'esecuzione fallita si distingue da una sana prima ancora di fare clic. Filtra per intervallo di date, ambiente, agent o sessione per passare da "tutto" a "l'esecuzione che mi interessa" in un paio di clic. +Ogni riga ha un badge di stato, così un'esecuzione fallita si distingue da una sana prima ancora di fare un click. Filtra per intervallo di date, ambiente, agente o sessione per passare da "tutto" a "l'esecuzione che mi interessa" in un paio di click. -Una volta collegato un valutatore, ogni esecuzione completata viene valutata automaticamente e il suo punteggio più recente appare sulla riga come badge. Puoi filtrare per qualsiasi intervallo di punteggio, così "mostrami ogni esecuzione prod con punteggio basso questa settimana" è un filtro, non una revisione manuale. Finché non ne configuri uno, le sessioni continuano a catturare l'esecuzione completa; semplicemente non hanno ancora un punteggio. +Una volta connesso un valutatore, ogni esecuzione completata viene valutata automaticamente e il suo punteggio più recente appare nella riga come badge. Puoi filtrare per qualsiasi intervallo di punteggio, così "mostrami ogni esecuzione in produzione con punteggio basso questa settimana" diventa un filtro, non una revisione manuale. Finché non ne configuri uno, le sessioni catturano comunque l'esecuzione completa; semplicemente non hanno ancora un punteggio. --- -## Leggi l'intera esecuzione come un'immagine +## Leggi l'intera esecuzione come un diagramma -![Un grafico di esecuzione in stile git della sessione accanto alla sua timeline di eventi, con il pannello di scomposizione di strumenti, modelli e hook](/agenteye/images/session-detail.png) +![Un grafo di esecuzione in stile git di una sessione accanto alla sua timeline degli eventi, con il pannello di breakdown di tool, modello e hook](/agenteye/images/session-detail.png) -*Il grafico di esecuzione (a sinistra) si siede accanto alla timeline degli eventi; il pannello di destra scompone gli strumenti, i modelli, gli hook e la spesa in token per l'esecuzione.* +*Il grafo di esecuzione (sinistra) si trova accanto alla timeline degli eventi; il pannello di destra suddivide i tool, i modelli, gli hook e i token spesi per l'esecuzione.* -Fai clic su qualsiasi sessione per aprire il suo grafico di esecuzione: una visualizzazione in stile git di come agent, strumenti, hook e chiamate ai modelli si sono svolti nel tempo. I sub-agent paralleli si diramano ognuno nella propria corsia, così puoi vedere quale lavoro è stato eseguito affiancato, quale sub-agent si è bloccato e dove l'esecuzione è andata fuori strada, senza riprenderla mentalmente da un muro di log. +Fai click su una qualsiasi sessione per aprire il suo grafo di esecuzione: una visualizzazione in stile git di come agenti, tool, hook e chiamate ai modelli si sono susseguiti nel tempo. Ogni sub-agente parallelo si dirama sulla propria corsia, così puoi vedere quale lavoro è stato eseguito in parallelo, quale sub-agente si è bloccato e dove l'esecuzione è andata fuori rotta, senza doverla ripetere mentalmente da una montagna di log. -Il pannello di destra ti dà la scomposizione per esecuzione: quali strumenti e modelli sono stati eseguiti, quali hook sono stati attivati e cosa l'esecuzione ha speso in token. Questa è la risposta a "perché questa esecuzione è costata così tanto?" o "quale strumento è quello lento?" seduta proprio accanto al grafico che l'ha causata. +Il pannello di destra ti dà il breakdown per-esecuzione: quali tool e modelli hanno girato, quali hook si sono attivati e quanto l'esecuzione ha speso in token. Questa è la risposta a "perché questa esecuzione è costata così tanto?" o "quale tool è quello lento?" seduta accanto al grafo che l'ha causata. -I singoli eventi sono indirizzabili, così puoi dare a qualcuno un link a un momento specifico piuttosto che "la sessione, circa due terzi più in giù". Copia il link da qualsiasi evento o segui uno da un risultato di [audit](/it/agenteye/audits) o un errore, e la sessione si apre con quell'evento selezionato e fatto scorrere in vista. Questo vale anche per esecuzioni molto lunghe: la timeline carica una finestra limitata per il bene del tuo browser, e un link che punta oltre quella finestra comunque trova il suo evento piuttosto che lasciarti all'inizio. Se l'evento è invecchiato oltre la tua finestra di conservazione, la pagina te lo dice invece di selezionare silenziosamente nulla. +I singoli eventi sono indirizzabili, così puoi passare a qualcuno un link a un momento specifico piuttosto che "la sessione, più o meno due terzi giù". Copia il link da qualsiasi evento, o segui uno da un risultato di [audit](/it/agenteye/audits) o da un errore, e la sessione si apre con quell'evento selezionato e scorso a quella posizione. Questo vale anche per le esecuzioni molto lunghe: la timeline carica una finestra limitata per il bene del tuo browser, e un link che punta oltre quella finestra trova comunque il suo evento piuttosto che lasciarti all'inizio. Se l'evento è più vecchio della tua finestra di retention, la pagina te lo comunica invece di selezionare silenziosamente nulla. --- ## Dove trovarla -Ogni pagina della dashboard è scoped alla tua org (`//…`). Sessions si trova sotto **Observe** nella barra laterale sinistra, accanto a Events, con i filtri di intervallo di date, ambiente, agent e sessione nella parte superiore dell'elenco. Ogni riga è a un clic dal suo grafico di esecuzione completo. +Ogni pagina del dashboard è limitata alla tua organizzazione (`//…`). Le Sessioni si trovano sotto **Observe** nella barra laterale sinistra, accanto agli Eventi, con i filtri di intervallo di date, ambiente, agente e sessione in cima all'elenco. Ogni riga è a un click dal suo grafo di esecuzione completo. -Per attivare i badge di punteggio e il filtraggio per intervallo di punteggio, collega un valutatore: vedi [Evaluations](/it/agenteye/evaluations). +Per attivare i badge di punteggio e il filtro per intervallo di punteggio, connetti un valutatore: vedi [Evaluations](/it/agenteye/evaluations). --- -## Correlati +## Correlato -- [Event stream](/it/agenteye/event-stream): il percorso grezzo e per-passo da cui ogni sessione è stata raggruppata. -- [Evaluations](/it/agenteye/evaluations): collega un valutatore in modo che ogni esecuzione ottenga un badge di punteggio per cui puoi filtrare. -- [Telemetry](/it/agenteye/telemetry): come le esecuzioni vanno dal tuo agent in queste sessioni. \ No newline at end of file +- [Event stream](/it/agenteye/event-stream): la traccia grezza, per-passaggio, da cui viene compattata ogni sessione. +- [Evaluations](/it/agenteye/evaluations): connetti un valutatore così ogni esecuzione ottiene un badge di punteggio che puoi filtrare. +- [Telemetry](/it/agenteye/telemetry): come le esecuzioni vanno dal tuo agente a queste sessioni. \ No newline at end of file diff --git a/docs/it/agenteye/telemetry.mdx b/docs/it/agenteye/telemetry.mdx index a55b17a5..df0b7a9c 100644 --- a/docs/it/agenteye/telemetry.mdx +++ b/docs/it/agenteye/telemetry.mdx @@ -1,52 +1,51 @@ --- -title: "Metriche di Prestazione" -description: "Vedi l'istante in cui i tuoi modelli, strumenti o hook rallentano o fanno lievitare i costi, e intercetta un picco di latenza coda prima che i tuoi utenti lo avvertano." +title: "Metriche di Performance" +description: "Vedi l'istante in cui i tuoi modelli, strumenti o hook rallentano o fanno salire i costi, e intercetta un picco di latenza in coda prima che i tuoi utenti lo sentano." --- +Vedi l'istante in cui i tuoi modelli, strumenti o hook rallentano o fanno salire i costi, e intercetta un picco di latenza in coda prima che i tuoi utenti lo sentano. Tre pagine dedicate trasformano i tempi grezzi in p50, p95 e p99 che puoi leggere a colpo d'occhio. -Vedi l'istante in cui i tuoi modelli, strumenti o hook rallentano o fanno lievitare i costi, e intercetta un picco di latenza coda prima che i tuoi utenti lo avvertano. Tre pagine dedicate trasformano i tempi grezzi in p50, p95 e p99 leggibili a colpo d'occhio. +![La pagina Models che mostra una heat-map di latenza, una banda percentile e figure di token per modello, costo stimato e riempimento della finestra di contesto](/agenteye/images/models.png) +*La pagina Models: una heat-map di latenza, una banda percentile e token per modello, costo stimato e riempimento della finestra di contesto.* -![La pagina Models che mostra una mappa di calore della latenza, una banda percentile e figure di token, costo e finestra di contesto per modello](/agenteye/images/models.png) -*La pagina Models: una mappa di calore della latenza, una banda percentile e token per modello, costo stimato e riempimento della finestra di contesto.* +## Smetti di lasciare che le medie nascondano i tuoi peggiori run -## Smetti di lasciare che le medie nascondano le tue peggiori esecuzioni - -Un numero di latenza media è rassicurante e inutile: nasconde quella chiamata su cinquanta che si blocca e ti sveglia di soppiatto alle 2 di mattina. Le pagine Models, Tools e Hooks rifiutano di farlo. Ognuna condivide la stessa struttura, così la impari una volta: +Un numero di latenza media è rassicurante e inutile: nasconde quel singolo call su cinquanta che si blocca e attiva l'on-call alle 2 del mattino. Le pagine Models, Tools e Hooks si rifiutano di farlo. Ognuna condivide la stessa struttura, così la impari una volta sola: - Una **sparkline a 24 bin** per il trend a colpo d'occhio: sta peggiorando? -- Una **striscia di vitali** con latenza p50, p95 e p99, così l'esecuzione tipica e la coda stanno fianco a fianco. -- Una **mappa di calore della latenza**, 24 bin temporali per bucket di latenza, che mostra *quando* le chiamate lente si sono raggruppate. -- Una **banda percentile**: una linea p50 con nastri ombreggiati da p25 a p75 e da p10 a p90 e punti p99, così la distribuzione rimane visibile invece di essere mediata. +- Una **striscia vitals** con latenza p50, p95 e p99, così il run tipico e la coda stanno uno accanto all'altro. +- Una **heat-map di latenza**, 24 bin temporali per bucket di latenza, che mostra *quando* i call lenti si sono raggruppati. +- Una **banda percentile**: una linea p50 con nastri ombreggiati p25 a p75 e p10 a p90 e punti p99, così la distribuzione rimane visibile invece di essere appiattita in una media. -Un mirino di hover condiviso collega la mappa di calore e la banda, così un picco di coda si allinea nel tempo su entrambe invece di nascondersi dietro una singola linea media. Trova tutte e tre le pagine nella sezione **observe** del tuo dashboard, ognuna con ambito alla tua organizzazione e filtrabile per intervallo di date, ambiente, agente e sessione. +Un reticolo di hover condiviso collega la heat-map e la banda, così un picco di coda si allinea nel tempo su entrambe invece di nascondersi dietro una singola linea media. Trova tutte e tre le pagine nella sezione **observe** del tuo dashboard, ognuna limitata alla tua organizzazione e filtrabile per intervallo di date, ambiente, agent e sessione. -## Models: vedi esattamente quanto ogni modello ti costa +## Models: vedi esattamente quanto ti costa ogni modello -La pagina Models (mostrata in alto) risponde alle due domande che una fattura pone sempre: quale modello e quanto costa. In aggiunta alla vista di latenza condivisa, aggiunge **consumo di token per modello**, **costo stimato** e **riempimento della finestra di contesto**, così la crescita della prompt incontrollata e una compattazione imminente sono visibili prima di sorprenderti. +La pagina Models (mostrata in alto) risponde alle due domande che una fattura solleva sempre: quale modello e quanto costa. Oltre alla vista di latenza condivisa, aggiunge **consumo di token per modello**, **costo stimato** e **riempimento della finestra di contesto**, così la crescita incontrollata del prompt e una compattazione imminente sono visibili prima che ti sorprendano. -Failproof AI Observability riconosce automaticamente gli ID dei modelli comuni. Se una finestra sembra scorretta o esegui un modello privato tuo, correggilo o aggiungine uno in **Settings**, in **model context windows**, e le letture del riempimento seguiranno. +Failproof AI Observability riconosce automaticamente gli ID modello comuni. Se una finestra sembra sbagliata, o esegui un modello privato tuo, correggila o aggiungine uno in **Settings**, in **model context windows**, e le letture di riempimento seguono. ## Tools: distingui il lento dal rotto -Una chiamata di strumento può essere lenta, oppure può stare fallendo in silenzio, e vuoi sapere quale sia in secondi, non dopo aver scavato nei log. +Una chiamata di tool può essere lenta, oppure può fallire silenziosamente, e vuoi saperlo in secondi, non dopo aver scavato tra i log. -![La pagina Tools che mostra la mappa di calore della latenza condivisa e la banda percentile accanto a un dettaglio di successo e fallimento e una barra di distribuzione degli strumenti](/agenteye/images/tools.png) -*La pagina Tools: la stessa mappa di calore e banda percentile, più un dettaglio di successo e fallimento e una barra di distribuzione degli strumenti.* +![La pagina Tools che mostra la heat-map di latenza condivisa e la banda percentile accanto a una suddivisione di successo e fallimento e una barra di distribuzione degli strumenti](/agenteye/images/tools.png) +*La pagina Tools: la stessa heat-map e banda percentile, più una suddivisione di successo e fallimento e una barra di distribuzione degli strumenti.* -Accanto alla vista di latenza condivisa, la pagina Tools aggiunge un **dettaglio di successo e fallimento** e una **barra di distribuzione degli strumenti**, così vedi a colpo d'occhio quali strumenti usi di più e quali stanno consumando il tuo budget di errori. +Accanto alla vista di latenza condivisa, la pagina Tools aggiunge una **suddivisione di successo e fallimento** e una **barra di distribuzione degli strumenti**, così vedi a colpo d'occhio quali strumenti usi di più e quali stanno consumando il tuo budget di errori. -## Hooks: individua esattamente l'hook e il trigger +## Hooks: individua l'esatto hook e trigger -Quando un hook del ciclo di vita fa rallentare un'esecuzione, "gli hook sono lenti" non è qualcosa su cui puoi agire. La pagina Hooks ti porta a quello che conta. +Quando un lifecycle hook rallenta un run, dire che "gli hook sono lenti" non è qualcosa su cui puoi agire. La pagina Hooks ti porta a quello che importa. -![La pagina Hooks che mostra la latenza suddivisa per nome dell'hook e evento trigger sulla mappa di calore e banda percentile condivise](/agenteye/images/hooks.png) -*La pagina Hooks: latenza suddivisa per nome dell'hook e evento trigger.* +![La pagina Hooks che mostra la latenza suddivisa per nome hook e evento trigger sulla heat-map condivisa e la banda percentile](/agenteye/images/hooks.png) +*La pagina Hooks: latenza suddivisa per nome hook e evento trigger.* -Sulla stessa mappa di calore della latenza e banda percentile, la pagina Hooks suddivide l'attività per **nome dell'hook** e **evento trigger**, così arrivi all'hook singolo e all'evento singolo che hanno bisogno di attenzione. +Sulla stessa heat-map di latenza e banda percentile, la pagina Hooks suddivide l'attività per **nome hook** e **evento trigger**, così arrivi all'unico hook e all'unico evento che necessitano attenzione. ## Correlati -- [Event stream](/it/agenteye/event-stream): il percorso codificato a colori live di ogni evento. -- [Sessions](/it/agenteye/sessions): raggruppa gli eventi in una riga per esecuzione e apri il suo grafico di esecuzione. -- [Error tracking](/it/agenteye/error-tracking): una superficie di triage per tutto quello che il dashboard dipinge di rosso. -- [Dashboards](/it/agenteye/dashboards): viste riepilogative sulla tua flotta. \ No newline at end of file +- [Event stream](/it/agenteye/event-stream): il flusso in tempo reale, codificato a colori, di ogni evento. +- [Sessions](/it/agenteye/sessions): raggruppa eventi in una riga per run e apri il suo grafo di esecuzione. +- [Error tracking](/it/agenteye/error-tracking): una superficie di triage unica per tutto ciò che il dashboard dipinge di rosso. +- [Dashboards](/it/agenteye/dashboards): viste aggregate sulla tua flotta. \ No newline at end of file diff --git a/docs/it/architecture.mdx b/docs/it/architecture.mdx index 4b650ef1..0d9ca9a0 100644 --- a/docs/it/architecture.mdx +++ b/docs/it/architecture.mdx @@ -1,7 +1,7 @@ --- --- title: Architettura -description: "Come il gestore hook, il caricamento della configurazione e la valutazione delle policy funzionano internamente" +description: "Come il gestore degli hook, il caricamento della configurazione e la valutazione delle policy funzionano internamente" icon: sitemap --- @@ -13,14 +13,14 @@ Questo documento spiega come failproofai funziona internamente: come il sistema failproofai ha due sottosistemi indipendenti: -1. **Hook handler** - Un veloce sottoprocesso CLI che Claude Code invoca ad ogni chiamata di tool dell'agente. Valuta le policy e restituisce una decisione. -2. **Agent Monitor (Dashboard)** - Un'applicazione web Next.js per monitorare le sessioni dell'agente e gestire le policy. +1. **Gestore degli hook** - Un veloce sottoproc CLI che Claude Code invoca su ogni chiamata al tool dell'agente. Valuta le policy e restituisce una decisione. +2. **Agent Monitor (Dashboard)** - Un'applicazione web Next.js per il monitoraggio delle sessioni dell'agente e la gestione delle policy. -Entrambi i sottosistemi condividono i file di configurazione in `~/.failproofai/` e nella directory `.failproofai/` del progetto, ma vengono eseguiti come processi separati e comunicano solo attraverso il filesystem. +Entrambi i sottosistemi condividono file di configurazione in `~/.failproofai/` e nella directory `.failproofai/` del progetto, ma vengono eseguiti come processi separati e comunicano solo attraverso il filesystem. --- -## Hook handler +## Gestore degli hook ### Integrazione con Claude Code @@ -45,7 +45,7 @@ Quando esegui `failproofai policies --install`, scrive voci come questa in `~/.c } ``` -Claude Code invoca quindi `failproofai --hook PreToolUse` come sottoprocesso prima di ogni chiamata di tool, passando un payload JSON su stdin. +Claude Code quindi invoca `failproofai --hook PreToolUse` come sottoproc prima di ogni chiamata al tool, passando un payload JSON su stdin. ### Formato del payload @@ -61,9 +61,9 @@ Claude Code invoca quindi `failproofai --hook PreToolUse` come sottoprocesso pri } ``` -Per gli eventi `PostToolUse`, il payload contiene anche `tool_result` con l'output del tool. +Per eventi `PostToolUse`, il payload contiene anche `tool_result` con l'output del tool. -Il gestore applica un limite di 1 MB su stdin. I payload che superano questo limite vengono scartati e tutte le policy consentono implicitamente. +Il gestore applica un limite di stdin di 1 MB. I payload che superano questo limite vengono scartati e tutte le policy consentono implicitamente. ### Formato della risposta @@ -86,7 +86,7 @@ Il gestore applica un limite di 1 MB su stdin. I payload che superano questo lim } ``` -**Instruct (qualsiasi evento tranne Stop):** +**Instruct (qualsiasi evento eccetto Stop):** ```json { "hookSpecificOutput": { @@ -101,14 +101,14 @@ Il gestore applica un limite di 1 MB su stdin. I payload che superano questo lim **Allow:** - Exit code: `0` -- stdout vuoto +- Stdout vuoto **Allow con messaggio:** -`allow(message)` consente a una policy di inviare un contesto informativo indietro a Claude anche quando l'operazione è consentita. Il gestore hook scrive il seguente JSON su **stdout** (non un file di configurazione — questa è la risposta del gestore a Claude Code, proprio come le risposte deny e instruct sopra): +`allow(message)` consente a una policy di inviare un contesto informativo di ritorno a Claude anche quando l'operazione è consentita. Il gestore degli hook scrive il seguente JSON su **stdout** (non un file di configurazione — questa è la risposta del gestore a Claude Code, proprio come le risposte deny e instruct sopra): ```json -// Scritto su stdout dal processo gestore hook +// Written to stdout by the hook handler process { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." @@ -116,7 +116,7 @@ Il gestore applica un limite di 1 MB su stdin. I payload che superano questo lim } ``` - Exit code: `0` (operazione consentita) -- Quando più policy restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con interruzioni di riga in una singola stringa `additionalContext` +- Quando più policy restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con newline in una singola stringa `additionalContext` - Se nessuna policy fornisce un messaggio, stdout è vuoto (come prima) ### Pipeline di elaborazione @@ -155,12 +155,12 @@ L'intero processo viene eseguito in meno di 100ms per i payload tipici senza chi ``` Logica di unione: -- `enabledPolicies` - unione deduplicated tra i tre file -- `policyParams` - per ogni policy, il primo file che la definisce vince interamente -- `customPoliciesPath` - il primo file che la definisce vince -- `llm` - il primo file che la definisce vince +- `enabledPolicies` - unione deduplicate in tutti e tre i file +- `policyParams` - per chiave di policy, il primo file che lo definisce vince completamente +- `customPoliciesPath` - il primo file che lo definisce vince +- `llm` - il primo file che lo definisce vince -Il dashboard web utilizza `readHooksConfig()` (solo globale) per la lettura e la scrittura, poiché non viene invocato con un cwd di progetto. +Il dashboard web utilizza `readHooksConfig()` (solo globale) per leggere e scrivere, poiché non viene invocato con un cwd di progetto. --- @@ -171,17 +171,17 @@ Il dashboard web utilizza `readHooksConfig()` (solo globale) per la lettura e la Per ogni policy: 1. Cerca lo schema `params` della policy (se ne ha uno). -2. Legge `policyParams[policy.name]` dalla configurazione unita. -3. Unisce i valori forniti dall'utente su i valori predefiniti dello schema per produrre `ctx.params`. +2. Leggi `policyParams[policy.name]` dalla configurazione unita. +3. Unisci i valori forniti dall'utente sui default dello schema per produrre `ctx.params`. 4. Chiama `policy.fn(ctx)` con il contesto risolto. -5. Se il risultato è `deny`, si ferma immediatamente e restituisce quella decisione. +5. Se il risultato è `deny`, fermati immediatamente e restituisci quella decisione. 6. Se il risultato è `instruct`, accumula il messaggio e continua. 7. Se il risultato è `allow`, continua alla policy successiva. Dopo l'esecuzione di tutte le policy: -- Se è stato restituito qualsiasi `deny`, emette la risposta deny. -- Se sono stati raccolti risultati `instruct`, emette una singola risposta instruct con tutti i messaggi uniti. -- Altrimenti, emette una risposta allow (stdout vuoto, exit 0). +- Se qualsiasi `deny` è stato restituito, emetti la risposta deny. +- Se sono stati raccolti eventuali ritorni `instruct`, emetti una singola risposta instruct con tutti i messaggi uniti. +- Altrimenti, emetti una risposta allow (stdout vuoto, exit 0). --- @@ -205,9 +205,9 @@ interface BuiltinPolicyDefinition { } ``` -Le policy che accettano `params` dichiarano uno `PolicyParamsSchema` con tipi e valori predefiniti per ogni parametro. L'evaluatore di policy inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni di policy leggono `ctx.params` senza protezione null perché i valori predefiniti vengono sempre applicati per primi. +Le policy che accettano `params` dichiarano uno `PolicyParamsSchema` con tipi e default per ogni parametro. L'evaluator della policy inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni della policy leggono `ctx.params` senza null-guarding perché i default vengono sempre applicati per primi. -Il pattern matching all'interno delle policy utilizza token di comando analizzati (argv), non corrispondenze di stringhe grezze. Questo previene i bypass tramite iniezione di operatori shell (ad es. un pattern per `sudo systemctl status *` non può essere bypassato aggiungendo `; rm -rf /` al comando). +Il pattern matching all'interno delle policy utilizza token di comando parsati (argv), non string matching grezzo. Questo previene il bypass tramite iniezione di operatore shell (ad es. un pattern per `sudo systemctl status *` non può essere bypassato aggiungendo `; rm -rf /` al comando). --- @@ -228,21 +228,21 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` carica il file di policy dell'utente: -1. Legge `customPoliciesPath` dalla configurazione; salta se assente. -2. Risolve al percorso assoluto; controlla che il file esista. -3. Riscrive tutti gli import `from "failproofai"` al percorso dist effettivo così `customPolicies` si risolve nello stesso registro `globalThis`. -4. Riscrive ricorsivamente gli import locali transitivi per garantire la compatibilità ESM. -5. Scrive file `.mjs` temporanei e `import()` il file di ingresso. -6. Chiama `getCustomHooks()` per recuperare i ganci registrati. -7. Pulisce tutti i file temporanei in un blocco `finally`. +1. Leggi `customPoliciesPath` dalla configurazione; salta se assente. +2. Risolvi al percorso assoluto; verifica che il file esista. +3. Riscrivi tutti gli import `from "failproofai"` al percorso dist effettivo così `customPolicies` si risolva nello stesso registro `globalThis`. +4. Riscrivi ricorsivamente gli import locali transitivi per garantire la compatibilità ESM. +5. Scrivi file `.mjs` temporanei e `import()` il file di entry. +6. Chiama `getCustomHooks()` per recuperare gli hook registrati. +7. Pulisci tutti i file temp in un blocco `finally`. -Su qualsiasi errore (file non trovato, errore di sintassi, fallimento dell'import), l'errore viene registrato in `~/.failproofai/hook.log` e il caricatore restituisce un array vuoto. Le policy integrate non sono interessate. +Su qualsiasi errore (file non trovato, errore di sintassi, errore di import), l'errore viene registrato in `~/.failproofai/hook.log` e il loader restituisce un array vuoto. Le policy integrate non sono influenzate. -Le policy personalizzate vengono valutate dopo tutte le policy integrate. Un `deny` di policy personalizzata ancora interrompe ulteriori policy personalizzate (ma tutte le integrate sono già state eseguite a quel punto). +Le policy personalizzate vengono valutate dopo tutte le policy integrate. Un deny di una policy personalizzata interrompe ancora ulteriori policy personalizzate (ma tutti i built-in sono già stati eseguiti a questo punto). --- -## Logging dell'attività +## Registrazione dell'attività Dopo ogni evento hook, il gestore aggiunge una riga JSONL a `~/.failproofai/hook-activity/current.jsonl`, che ruota in `page--.jsonl` una volta raggiunta una pagina: @@ -259,7 +259,7 @@ Dopo ogni evento hook, il gestore aggiunge una riga JSONL a `~/.failproofai/hook } ``` -Una riga per ogni policy che ha preso una decisione non-allow. Le decisioni allow non vengono registrate (per mantenere il file piccolo). +Una riga per ogni policy che ha preso una decisione non-allow. Le decisioni Allow non vengono registrate (per mantenere il file piccolo). --- @@ -285,18 +285,18 @@ app/ download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` -**Flusso dati:** +**Flusso dei dati:** -- I componenti pagina chiamano `lib/projects.ts` e `lib/log-entries.ts` per leggere i dati di progetto/sessione direttamente dal filesystem (nessun livello API per le letture). -- La pagina Policies utilizza Server Actions per tutte le mutazioni (attiva/disattiva, aggiornamento parametri, installa/rimuovi). -- Il visualizzatore di sessione analizza il formato di trascrizione JSONL di Claude e renderizza una timeline di messaggi e chiamate di tool. +- I componenti pagina chiamano `lib/projects.ts` e `lib/log-entries.ts` per leggere direttamente i dati del progetto/sessione dal filesystem (nessuno strato API per le letture). +- La pagina Policies utilizza Server Actions per tutte le mutazioni (toggle, aggiornamento parametri, installa/rimuovi). +- Il visualizzatore di sessione parsifica il formato di trascritto JSONL di Claude e renderizza una cronologia di messaggi e chiamate ai tool. **Decisioni di design chiave:** - Nessun database - tutto lo stato persistente è in file semplici (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions per le mutazioni - nessuna API REST necessaria per le operazioni CRUD. -- React Server Components per le pagine di lettura - caricamento iniziale più veloce, nessun bundle client per il recupero dei dati. -- Componenti client solo dove è necessaria l'interattività (attivazioni/disattivazioni policy, ricerca attività, visualizzatore log). +- Server Actions per mutazioni - nessuna API REST necessaria per le operazioni CRUD. +- React Server Components per pagine di lettura - caricamento iniziale più veloce, nessun client bundle per il fetching dei dati. +- Componenti client solo dove è necessaria l'interattività (policy toggle, ricerca attività, visualizzatore log). --- diff --git a/docs/it/built-in-policies.mdx b/docs/it/built-in-policies.mdx index fef76d8f..cf980dc7 100644 --- a/docs/it/built-in-policies.mdx +++ b/docs/it/built-in-policies.mdx @@ -1,39 +1,43 @@ --- title: Politiche integrate -description: "Tutte le 39 politiche integrate che individuano le modalità di errore comuni degli agenti" +description: "Tutte le 39 politiche integrate che rilevano i comuni difetti degli agenti" icon: shield --- -failproofai include 39 politiche integrate che individuano le modalità di errore comuni degli agenti. Ogni politica si attiva su un tipo di evento hook specifico e su un nome di strumento. Diciannove politiche accettano parametri che consentono di regolarne il comportamento senza scrivere codice. Cinque politiche di flusso di lavoro applicano un pipeline commit → push → PR → CI prima che Claude si fermi. +failproofai viene fornito con 39 politiche integrate che rilevano i comuni difetti degli agenti. Ogni politica si attiva su un tipo di evento hook specifico e un nome di strumento. Diciannove politiche accettano parametri che ti permettono di regolarne il comportamento senza scrivere codice. Cinque politiche di workflow applicano una pipeline commit → push → PR → CI prima che Claude si fermi. --- ## Panoramica -Le politiche sono raggruppate in categorie: +Le politiche sono raggruppate per categoria: | Categoria | Politiche | Tipo di hook | |----------|----------|-----------| | [Comandi pericolosi](#comandi-pericolosi) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | -| [Comandi infrastrutturali](#comandi-infrastrutturali) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Segreti (sanitizzatori)](#segreti-sanitizzatori) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Comandi infra](#comandi-infra) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [Segreti (sanitizer)](#segreti-sanitizer) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [Ambiente](#ambiente) | block-env-files, protect-env-vars | PreToolUse | | [Accesso ai file](#accesso-ai-file) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | | [Database](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | | [Avvisi](#avvisi) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [Gestori pacchetti](#gestori-pacchetti) | prefer-package-manager | PreToolUse | -| [Flusso di lavoro](#flusso-di-lavoro) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | +| [Gestori di pacchetti](#gestori-di-pacchetti) | prefer-package-manager | PreToolUse | +| [Workflow](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — interrompe l'agente dal procedere. -- **`warn-`** — fornisce all'agente contesto aggiuntivo in modo che possa correggersi autonomamente. -- **`sanitize-`** — rimuove i dati sensibili dall'output dello strumento prima che l'agente li veda. +- **`block-`** — impedisce all'agente di procedere. +- **`warn-`** — fornisce all'agente un contesto aggiuntivo affinché possa autocorreggersi. +- **`sanitize-`** — rimuove dati sensibili dall'output dello strumento prima che l'agente li veda. -### Spazi dei nomi +### Namespace -Ogni politica si trova in uno slot `/`. Le politiche integrate appartengono allo spazio dei nomi **`failproofai/`** — ad esempio, `failproofai/sanitize-jwt`. Lo spazio dei nomi previene collisioni quando carichi anche politiche personalizzate o di terze parti con nomi brevi simili. +Ogni politica si trova in uno slot `/`. Le politiche integrate appartengono allo +**namespace `failproofai/`** — ad esempio, `failproofai/sanitize-jwt`. Il +namespace previene collisioni quando carichi anche politiche personalizzate o di terze parti +con nomi brevi simili. -Nella tua configurazione puoi fare riferimento a una politica integrata utilizzando il suo nome breve o il suo nome qualificato; entrambe le forme si risolvono nella stessa politica: +Nel tuo config puoi fare riferimento a una politica integrate usando sia il nome breve che il +nome qualificato; entrambe le forme si risolvono nella stessa politica: ```json { @@ -44,39 +48,41 @@ Nella tua configurazione puoi fare riferimento a una politica integrata utilizza } ``` -Se un nome non contiene `/`, failproofai lo tratta come appartenente allo spazio dei nomi predefinito `failproofai`. I nomi che contengono già `/` (ad es. `myorg/foo`, `custom/my-hook`) vengono mantenuti così come sono. -- **`require-`** — blocca l'evento Stop fino al verificarsi delle condizioni. +Se un nome non contiene `/`, failproofai lo tratta come appartenente al namespace predefinito +`failproofai`. I nomi che contengono già un `/` (ad es. `myorg/foo`, +`custom/my-hook`) rimangono invariati. +- **`require-`** — blocca l'evento Stop finché le condizioni non sono soddisfatte. --- -Ogni politica supporta un campo `hint` facoltativo in `policyParams`. L'hint viene aggiunto al messaggio di deny o instruct che Claude vede, fornendo indicazioni pratiche senza modificare il codice della politica. Funziona con politiche integrate, personalizzate e per convenzione. Consulta [Configurazione → hint](/it/configuration#hint-cross-cutting) per i dettagli. +Ogni politica supporta un campo facoltativo `hint` in `policyParams`. L'hint viene aggiunto al messaggio deny o instruct che Claude vede, fornendo indicazioni operative senza modificare il codice della politica. Funziona con politiche integrate, personalizzate e di convention. Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per i dettagli. --- ## Comandi pericolosi -Impedisci agli agenti di eseguire operazioni difficili da annullare o che potrebbero danneggiare il sistema host. +Impedisci agli agenti di eseguire operazioni che sono difficili da annullare o che potrebbero danneggiare il sistema host. ### `block-sudo` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi comando `sudo` o `doas`. +**Impostazione predefinita:** Nega qualsiasi comando `sudo` o `doas`. -Blocca un comando che esegue un binario di elevazione **in posizione di comando**. La corrispondenza è strutturale piuttosto che testuale: il comando viene suddiviso in segmenti come farebbe una shell, gli assegnamenti di prefisso (`FOO=bar`), i reindirizzamenti e i runner con i loro flag (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) vengono rimossi, e il binario risultante viene confrontato per **basename**. Quindi `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` e `bash -c "sudo …"` sono tutti negati, e `doas` viene trattato come la stessa capacità con un nome diverso. +Blocca un comando che esegue un binario di elevazione **in posizione di comando**. La corrispondenza è strutturale anziché testuale: il comando viene suddiviso in segmenti come farebbe una shell, gli assegnamenti di prefisso (`FOO=bar`), i reindirizzamenti e i runner con i loro flag (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) vengono rimossi e il binario risultante viene confrontato per **basename**. Quindi `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` e `bash -c "sudo …"` vengono tutti negati, e `doas` è trattato come la stessa capacità con un nome diverso. -Poiché si ancora sulla posizione del comando piuttosto che sulla parola che appare da qualsiasi parte, **non** si attiva su comandi che la menzionano semplicemente — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, o un'alternazione `grep` contenente la parola vengono eseguiti normalmente. +Poiché si ancora sulla posizione del comando anziché sulla parola che appare da qualche parte, **non** si attiva su comandi che la menzionano semplicemente — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, o un'alternazione `grep` contenente la parola vengono tutti eseguiti normalmente. -Questo ferma il tentativo ovvio; non chiude la classe. Un agente che può eseguire shell arbitrarie può comunque raggiungere l'elevazione indirettamente — attraverso una variabile (`S=sudo; $S …`), una pipe decodificata base64, o uno script wrapper su disco — perché nessuna ispezione di una singola stringa di comando può seguirle. Tratta questo come una protezione contro gli errori e l'escalation casuale, non come un confine di sicurezza contro un agente determinato. Un confine reale deve essere applicato sotto la shell. +Questo blocca il tentativo ovvio; non chiude la classe. Un agente che può eseguire shell arbitraria può comunque raggiungere l'elevazione indirettamente — attraverso una variabile (`S=sudo; $S …`), una pipe decodificata in base64 o uno script wrapper su disco — perché nessuna ispezione di una singola stringa di comando può seguire quelle. Tratta questo come un guardrail contro errori e escalation casuale, non come un confine di sicurezza contro un agente determinato. Un vero confine deve essere applicato sotto la shell. **Parametri:** | Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando esatti che sono consentiti. Ogni voce viene confrontata con i token argv analizzati. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando esatti consentiti. Ogni entry viene confrontata rispetto ai token argv analizzati. | **Esempio:** @@ -90,10 +96,10 @@ Questo ferma il tentativo ovvio; non chiude la classe. Un agente che può esegui } ``` -Con questa configurazione, `sudo systemctl status nginx` è consentito, ma `sudo rm /etc/hosts` è negato. +Con questa config, `sudo systemctl status nginx` è consentito, ma `sudo rm /etc/hosts` è negato. -I pattern vengono confrontati con i token analizzati, non con la stringa di comando grezza. Questo previene il bypass tramite operatori shell aggiunti (ad es. `sudo systemctl status x; rm -rf /` non corrisponde a `sudo systemctl status *`). +I pattern vengono confrontati rispetto ai token analizzati, non alla stringa di comando raw. Questo previene il bypass tramite operatori shell aggiunti (ad es. `sudo systemctl status x; rm -rf /` non corrisponde a `sudo systemctl status *`). --- @@ -101,13 +107,13 @@ I pattern vengono confrontati con i token analizzati, non con la stringa di coma ### `block-rm-rf` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega `rm -rf`, `rm -fr` e altre forme di eliminazione ricorsiva simili. +**Impostazione predefinita:** Nega `rm -rf`, `rm -fr` e forme simili di cancellazione ricorsiva. **Parametri:** | Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Percorsi che sono sicuri da eliminare ricorsivamente (ad es. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Percorsi sicuri da eliminare ricorsivamente (ad es. `/tmp`). | **Esempio:** @@ -126,7 +132,7 @@ I pattern vengono confrontati con i token analizzati, non con la stringa di coma ### `block-curl-pipe-sh` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega `curl | bash`, `curl | sh`, `wget | bash` e pattern simili. +**Impostazione predefinita:** Nega `curl | bash`, `curl | sh`, `wget | bash` e pattern simili. Nessun parametro. @@ -135,7 +141,7 @@ Nessun parametro. ### `block-failproofai-commands` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega comandi che disinstallerebbero o disabiliterebbero failproofai stesso (ad es. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Impostazione predefinita:** Nega i comandi che disinstallerebbero o disabiliterebbero failproofai stesso (ad es. `npm uninstall failproofai`, `failproofai policies --uninstall`). Nessun parametro. @@ -144,26 +150,26 @@ Nessun parametro. ### `block-self-pause` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega `failproofai config --pause`, che sospende l'applicazione per una sessione. La pausa è una decisione umana — un agente in grado di eseguirla potrebbe disattivare tutte le altre politiche con un singolo comando. +**Impostazione predefinita:** Nega `failproofai config --pause`, che sospende l'applicazione per una sessione. La pausa è una decisione umana — un agente in grado di eseguirla potrebbe disattivare tutte le altre politiche con un singolo comando. -Più ristretto di [`block-failproofai-commands`](#block-failproofai-commands) di proposito, e non coperto da esso: quella politica si ancora su un confine di comando, quindi `npx -y failproofai config --pause` non corrisponde ad esso, ed essendo ampio è spesso disattivato in modo che gli agenti possono eseguire `failproofai audit`. `--resume` e `--status` sono consentiti — nessuno rimuove l'applicazione. +Più stretto di [`block-failproofai-commands`](#block-failproofai-commands) di proposito e non coperto da esso: quella politica si ancora su un confine di comando, quindi `npx -y failproofai config --pause` non corrisponde ad esso, ed essendo ampia viene spesso disattivata così gli agenti possono eseguire `failproofai audit`. `--resume` e `--status` sono consentiti — nessuno dei due rimuove l'applicazione. -Questo ferma il tentativo diretto, non l'intera classe: un agente può comunque raggiungere lo stesso stato attraverso un alias o uno script wrapper. Chiuderlo completamente richiede che la pausa sia irraggiungibile da una chiamata di strumento. +Questo blocca il tentativo diretto, non l'intera classe: un agente può comunque raggiungere lo stesso stato attraverso un alias o uno script wrapper. Chiuderlo completamente richiede che la pausa sia irraggiungibile da una chiamata di strumento. Nessun parametro. --- -## Comandi infrastrutturali +## Comandi infra -Ferma gli agenti di codifica dall'eseguire CLI infrastrutturali o dall'attivare pipeline CI/CD. Tutte le politiche in questa categoria sono **opt-in** (`defaultEnabled: false`) — gli agenti che hanno legittimamente bisogno di chiamare `kubectl`, `terraform`, ecc. non verranno disturbati a meno che non abiliti la politica. Se abilitata, ogni invocazione della CLI corrispondente è negata a meno che il comando corrisponda a una voce in `allowPatterns`. +Impedisci agli agenti di codifica di eseguire CLI infrastrutturali o attivare pipeline CI/CD. Tutte le politiche in questa categoria sono **opt-in** (`defaultEnabled: false`) — gli agenti che legittimamente hanno bisogno di chiamare `kubectl`, `terraform`, ecc. non verranno disturbati a meno che non abiliti la politica. Quando abilitata, ogni invocazione del CLI corrispondente viene negata a meno che il comando non corrisponda a un entry in `allowPatterns`. -La grammatica del pattern è la stessa di [`block-sudo`](#block-sudo): i token vengono confrontati con argv analizzati, `*` è un wildcard per un token, e qualsiasi comando contenente un operatore shell autonomo (`&&`, `||`, `|`, `;`) o un token con metarcatteri shell incorporati viene rifiutato prima della corrispondenza della lista di consentiti per prevenire bypass di iniezione. +La grammatica del pattern è la stessa di [`block-sudo`](#block-sudo): i token vengono confrontati rispetto a argv analizzati, `*` è un wildcard per un token, e qualsiasi comando contenente un operatore shell standalone (`&&`, `||`, `|`, `;`) o un token con metacaratteri shell incorporati viene rifiutato prima della corrispondenza della whitelist per prevenire bypass di iniezione. ### `block-kubectl` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di `kubectl`. +**Impostazione predefinita:** Nega qualsiasi invocazione di `kubectl`. **Parametri:** @@ -183,14 +189,14 @@ La grammatica del pattern è la stessa di [`block-sudo`](#block-sudo): i token v } ``` -Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f deploy.yaml` è negato. +Con questa config, `kubectl get pods` è consentito ma `kubectl apply -f deploy.yaml` è negato. --- ### `block-terraform` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di `terraform` o `tofu` (OpenTofu). +**Impostazione predefinita:** Nega qualsiasi invocazione di `terraform` o `tofu` (OpenTofu). **Parametri:** @@ -215,7 +221,7 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-aws-cli` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di CLI `aws`. +**Impostazione predefinita:** Nega qualsiasi invocazione della CLI `aws`. **Parametri:** @@ -240,7 +246,7 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-gcloud` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di CLI `gcloud` (Google Cloud). +**Impostazione predefinita:** Nega qualsiasi invocazione della CLI `gcloud` (Google Cloud). **Parametri:** @@ -265,7 +271,7 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-az-cli` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di CLI `az` (Azure). +**Impostazione predefinita:** Nega qualsiasi invocazione della CLI `az` (Azure). **Parametri:** @@ -290,7 +296,7 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-helm` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di `helm`. +**Impostazione predefinita:** Nega qualsiasi invocazione di `helm`. **Parametri:** @@ -315,7 +321,7 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-gh-pipeline` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega i seguenti sottocomandi `gh` CLI che mutano lo stato o attivano pipeline: +**Impostazione predefinita:** Nega i seguenti sottocomandi della CLI `gh` che mutano lo stato o attivano pipeline: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -324,13 +330,13 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f - `gh cache delete` - `gh secret set`, `gh secret delete` -I sottocomandi `gh` di sola lettura come `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...` **non** sono abbinati da questa politica — vengono regolarmente necessari per i controlli del flusso di lavoro (incluso il proprio `require-ci-green-before-stop` di failproofai). +I sottocomandi `gh` di sola lettura come `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...` **non** vengono confrontati da questa politica — sono regolarmente necessari per i controlli di workflow (compreso il `require-ci-green-before-stop` di failproofai). **Parametri:** | Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocazioni scriptate specifiche da consentire anche se verrebbero negate. | +| `allowPatterns` | `string[]` | `[]` | Invocazioni specifiche scripted da consentire anche se verrebbero negate. | **Esempio:** @@ -346,14 +352,14 @@ I sottocomandi `gh` di sola lettura come `gh pr view`, `gh pr list`, `gh run lis --- -## Segreti (sanitizzatori) +## Segreti (sanitizer) -Ferma gli agenti dal divulgare credenziali nel loro contesto o output. Le politiche di sanitizzazione si attivano su eventi **PostToolUse**. Quando Claude esegue un comando Bash, legge un file, o chiama qualsiasi strumento, queste politiche ispezionano l'output prima che venga restituito a Claude. Se viene rilevato un pattern di segreto, la politica restituisce una decisione di negazione che impedisce al output di essere restituito. +Impedisci agli agenti di far trapelare credenziali nel loro contesto o output. Le politiche sanitizer si attivano su eventi **PostToolUse**. Quando Claude esegue un comando Bash, legge un file o chiama qualsiasi strumento, queste politiche ispezionano l'output prima che venga restituito a Claude. Se viene rilevato un pattern di segreto, la politica restituisce una decisione di negazione che impedisce il ritorno dell'output. ### `sanitize-jwt` **Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Redige i token JWT (tre segmenti base64url separati da `.`). +**Impostazione predefinita:** Oscura i token JWT (tre segmenti base64url separati da `.`). Nessun parametro. @@ -362,7 +368,7 @@ Nessun parametro. ### `sanitize-api-keys` **Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Redige i formati di chiave API comuni: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), chiavi di accesso AWS (`AKIA`), chiavi Stripe (`sk_live_`, `sk_test_`), e chiavi API Google (`AIza`). +**Impostazione predefinita:** Oscura i formati comuni di chiavi API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chiavi di accesso AWS (`AKIA`), chiavi Stripe (`sk_live_`, `sk_test_`) e chiavi API Google (`AIza`). **Parametri:** @@ -390,7 +396,7 @@ Nessun parametro. ### `sanitize-connection-strings` **Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Redige le stringhe di connessione al database che contengono credenziali incorporate (ad es. `postgresql://user:password@host/db`). +**Impostazione predefinita:** Oscura le stringhe di connessione al database che contengono credenziali incorporate (ad es. `postgresql://user:password@host/db`). Nessun parametro. @@ -399,7 +405,7 @@ Nessun parametro. ### `sanitize-private-key-content` **Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Redige i blocchi PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, ecc.). +**Impostazione predefinita:** Oscura i blocchi PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, ecc.). Nessun parametro. @@ -408,7 +414,7 @@ Nessun parametro. ### `sanitize-bearer-tokens` **Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Redige le intestazioni `Authorization: Bearer ` dove il token è 20 o più caratteri. +**Impostazione predefinita:** Oscura gli header `Authorization: Bearer ` dove il token è di 20 o più caratteri. Nessun parametro. @@ -416,14 +422,14 @@ Nessun parametro. ## Ambiente -Proteggi la configurazione dell'ambiente sensibile dalla lettura o dall'esposizione da parte degli agenti. +Proteggi la configurazione dell'ambiente sensibile dal essere letta o esposta dagli agenti. ### `block-env-files` **Evento:** PreToolUse (Bash, Read) -**Predefinito:** Nega la lettura di file `.env` tramite `cat .env`, chiamate di strumento Read con `.env` come percorso del file, ecc. +**Impostazione predefinita:** Nega la lettura di file `.env` tramite `cat .env`, chiamate di strumento Read con `.env` come percorso di file, ecc. -Non blocca `.envrc` o altri file correlati all'ambiente — solo i file denominati esattamente `.env`. +Non blocca `.envrc` o altri file correlati all'ambiente - solo file denominati esattamente `.env`. Nessun parametro. @@ -432,7 +438,7 @@ Nessun parametro. ### `protect-env-vars` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega comandi che stampano le variabili di ambiente: `printenv`, `env`, `echo $VAR`. +**Impostazione predefinita:** Nega i comandi che stampano le variabili di ambiente: `printenv`, `env`, `echo $VAR`. Nessun parametro. @@ -440,12 +446,12 @@ Nessun parametro. ## Accesso ai file -Mantieni gli agenti che lavorano entro i confini del progetto e lontano dai file sensibili. +Mantieni gli agenti nel lavoro all'interno dei confini del progetto e lontano da file sensibili. ### `block-read-outside-cwd` **Evento:** PreToolUse (Read, Bash) -**Predefinito:** Nega la lettura di file al di fuori della radice del progetto. Il confine è `CLAUDE_PROJECT_DIR` (impostato una volta per sessione da Claude Code), con un fallback alla directory di lavoro corrente della sessione quando quella variabile non è impostata. L'utilizzo della radice del progetto anziché della `cwd` dal vivo significa che il confine rimane stabile anche dopo che Claude esegue `cd` in una sottodirectory. +**Impostazione predefinita:** Nega la lettura di file al di fuori della radice del progetto. Il confine è `CLAUDE_PROJECT_DIR` (impostato una volta per sessione da Claude Code), con un fallback alla directory di lavoro corrente della sessione quando quella variabile non è impostata. L'utilizzo della radice del progetto anziché di `cwd` live significa che il confine rimane stabile anche dopo che Claude `cd` entra in una sottodirectory. **Parametri:** @@ -470,13 +476,13 @@ Mantieni gli agenti che lavorano entro i confini del progetto e lontano dai file ### `block-secrets-write` **Evento:** PreToolUse (Write, Edit) -**Predefinito:** Nega le scritture su file comunemente usati per chiavi private e certificati: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Impostazione predefinita:** Nega le scritture su file comunemente utilizzati per chiavi private e certificati: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parametri:** | Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Pattern di nome file aggiuntivi (stile glob) da bloccare. | +| `additionalPatterns` | `string[]` | `[]` | Pattern di filename aggiuntivi (stile glob) da bloccare. | **Esempio:** @@ -494,12 +500,12 @@ Mantieni gli agenti che lavorano entro i confini del progetto e lontano dai file ## Git -Previeni push accidentali, force-push e errori di branch difficili da annullare. +Previeni i push accidentali, i force-push e gli errori di branch che sono difficili da annullare. ### `block-push-master` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega `git push origin main` e `git push origin master`. +**Impostazione predefinita:** Nega `git push origin main` e `git push origin master`. **Parametri:** @@ -520,7 +526,7 @@ Previeni push accidentali, force-push e errori di branch difficili da annullare. ``` -Per consentire il push su tutti i branch (disabilitando efficacemente questa politica senza rimuoverla da `enabledPolicies`), imposta `protectedBranches: []`. +Per consentire il push su tutti i branch (disabilitando effettivamente questa politica senza rimuoverla da `enabledPolicies`), imposta `protectedBranches: []`. --- @@ -528,28 +534,28 @@ Per consentire il push su tutti i branch (disabilitando efficacemente questa pol ### `block-work-on-main` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` mentre l'albero di lavoro è su `main` o `master`. La creazione e il cambio di branch (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) non sono interessati. +**Impostazione predefinita:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` mentre l'albero di lavoro è su `main` o `master`. La creazione di branch e il passaggio (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) non sono interessati. **Parametri:** | Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch su cui commit/merge/rebase/cherry-pick è negato. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch su cui commit/merge/rebase/cherry-pick viene negato. | --- ### `block-force-push` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega `git push --force` e `git push -f`. +**Impostazione predefinita:** Nega `git push --force` e `git push -f`. -Nessun parametro specifico della politica. Usa il [`hint`](/it/configuration#hint-cross-cutting) trasversale per suggerire alternative: +Nessun parametro specifico della politica. Usa l'[`hint`](/it/configuration#hint-cross-cutting) cross-cutting per suggerire alternative: ```json { "policyParams": { "block-force-push": { - "hint": "Crea un nuovo branch dal tuo HEAD corrente (ad es. `git checkout -b `) e pusha quello invece." + "hint": "Crea un nuovo branch dal tuo HEAD attuale (ad es. `git checkout -b `) e invece pusha quello." } } } @@ -560,7 +566,7 @@ Nessun parametro specifico della politica. Usa il [`hint`](/it/configuration#hin ### `warn-git-amend` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a procedere con cautela quando esegue `git commit --amend`. Non blocca il comando. +**Impostazione predefinita:** Istruisce Claude a procedere con cautela durante l'esecuzione di `git commit --amend`. Non blocca il comando. Nessun parametro. @@ -569,7 +575,7 @@ Nessun parametro. ### `warn-git-stash-drop` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire `git stash drop`. Non blocca il comando. +**Impostazione predefinita:** Istruisce Claude a confermare prima di eseguire `git stash drop`. Non blocca il comando. Nessun parametro. @@ -578,7 +584,7 @@ Nessun parametro. ### `warn-all-files-staged` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a rivedere ciò che sta stage quando esegue `git add -A` o `git add .`. Non blocca il comando. +**Impostazione predefinita:** Istruisce Claude a rivedere cosa sta stages quando esegue `git add -A` o `git add .`. Non blocca il comando. Nessun parametro. @@ -586,12 +592,12 @@ Nessun parametro. ## Database -Individua le operazioni SQL distruttive prima che si eseguano contro il tuo database. +Cattura le operazioni SQL distruttive prima che vengano eseguite sul tuo database. ### `warn-destructive-sql` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire SQL contenente `DROP TABLE`, `DROP DATABASE`, o `DELETE` senza una clausola `WHERE`. +**Impostazione predefinita:** Istruisce Claude a confermare prima di eseguire SQL contenente `DROP TABLE`, `DROP DATABASE` o `DELETE` senza una clausola `WHERE`. Nessun parametro. @@ -600,7 +606,7 @@ Nessun parametro. ### `warn-schema-alteration` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire le istruzioni `ALTER TABLE`. +**Impostazione predefinita:** Istruisce Claude a confermare prima di eseguire istruzioni `ALTER TABLE`. Nessun parametro. @@ -613,13 +619,13 @@ Fornisci agli agenti contesto extra prima di operazioni potenzialmente rischiose ### `warn-large-file-write` **Evento:** PreToolUse (Write) -**Predefinito:** Istruisce Claude a confermare prima di scrivere file di dimensioni superiori a 1024 KB. +**Impostazione predefinita:** Istruisce Claude a confermare prima di scrivere file più grandi di 1024 KB. **Parametri:** | Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Soglia di dimensione del file in kilobyte al di sopra della quale viene emesso un avviso. | +| `thresholdKb` | `number` | `1024` | Soglia di dimensione file in kilobyte al di sopra della quale viene emesso un avviso. | **Esempio:** @@ -634,7 +640,7 @@ Fornisci agli agenti contesto extra prima di operazioni potenzialmente rischiose ``` -Il gestore di hook applica un limite stdin di 1 MB sui payload. Per testare questa politica con contenuti piccoli, imposta `thresholdKb` a un valore ben al di sotto di 1024. +L'handler hook applica un limite stdin di 1 MB sui payload. Per testare questa politica con contenuto piccolo, imposta `thresholdKb` a un valore ben al di sotto di 1024. --- @@ -642,7 +648,7 @@ Il gestore di hook applica un limite stdin di 1 MB sui payload. Per testare ques ### `warn-package-publish` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire `npm publish`. +**Impostazione predefinita:** Istruisce Claude a confermare prima di eseguire `npm publish`. Nessun parametro. @@ -651,7 +657,7 @@ Nessun parametro. ### `warn-background-process` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a stare attento quando lancia processi in background tramite `nohup`, `&`, `disown` o `screen`. +**Impostazione predefinita:** Istruisce Claude a stare attento quando avvia processi in background tramite `nohup`, `&`, `disown` o `screen`. Nessun parametro. @@ -660,29 +666,29 @@ Nessun parametro. ### `warn-global-package-install` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire `npm install -g`, `yarn global add` o `pip install` senza un ambiente virtuale. +**Impostazione predefinita:** Istruisce Claude a confermare prima di eseguire `npm install -g`, `yarn global add` o `pip install` senza un ambiente virtuale. Nessun parametro. --- -## Gestori pacchetti +## Gestori di pacchetti -Applica quale gestore di pacchetti è consentito all'agente di utilizzare. +Applica quale gestore di pacchetti l'agente è autorizzato a utilizzare. ### `prefer-package-manager` **Evento:** PreToolUse (Bash) -**Predefinito:** Disabilitato. Se abilitato, blocca qualsiasi comando del gestore di pacchetti non nella lista `allowed` e dice a Claude di riscrivere il comando utilizzando un gestore consentito. +**Impostazione predefinita:** Disabilitato. Quando abilitato, blocca qualsiasi comando di gestore di pacchetti non nell'elenco `allowed` e istruisce Claude a riscrivere il comando utilizzando un gestore consentito. Rileva: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parametro | Tipo | Predefinito | Descrizione | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Nomi dei gestori di pacchetti consentiti. Qualsiasi gestore rilevato non in questa lista è bloccato. Se vuoto, la politica è no-op. | -| `blocked` | string[] | `[]` | Nomi di gestori aggiuntivi da bloccare oltre la lista integrata (ad es. `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Nomi di gestore di pacchetti consentiti. Qualsiasi gestore rilevato non in questo elenco viene bloccato. Quando vuoto, la politica è un no-op. | +| `blocked` | string[] | `[]` | Nomi di gestore aggiuntivi da bloccare oltre all'elenco integrate (ad es. `['pdm', 'pipx']`). | -La lista di blocco integrata include: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` per aggiungere gestori non in questa lista. +L'elenco di blocco integrate copre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` per aggiungere gestori non in questo elenco. **Configurazione di esempio:** @@ -698,58 +704,58 @@ La lista di blocco integrata include: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun } ``` -Con questa configurazione, `pip install flask` e `pdm install flask` sono entrambi negati con un messaggio che dice a Claude di utilizzare `uv` o `bun` invece. I comandi come `uv pip install flask` sono consentiti perché `uv` è nella lista di consentiti e viene verificato per primo. +Con questa config, `pip install flask` e `pdm install flask` vengono entrambi negati con un messaggio che istruisce Claude a usare invece `uv` o `bun`. I comandi come `uv pip install flask` sono consentiti perché `uv` è nell'allowlist ed è controllato per primo. --- -## Comportamento dell'IA +## Comportamento AI -Rileva quando gli agenti rimangono bloccati o si comportano inaspettatamente. +Rileva quando gli agenti rimangono bloccati o si comportano in modo inaspettato. ### `warn-repeated-tool-calls` **Evento:** PreToolUse (tutti gli strumenti) -**Predefinito:** Istruisce Claude a riconsiderare quando lo stesso strumento viene chiamato 3+ volte con parametri identici — un segno comune che l'agente è bloccato in un ciclo. +**Impostazione predefinita:** Istruisce Claude a riconsiderare quando lo stesso strumento viene chiamato 3+ volte con parametri identici - un segno comune che l'agente è bloccato in un ciclo. Nessun parametro. --- -## Flusso di lavoro +## Workflow -Applica un flusso di lavoro di fine sessione disciplinato. Queste politiche si attivano sull'evento **Stop** e negano all'agente il diritto di fermarsi fino al verificarsi di ogni condizione. Seguono una catena di dipendenza naturale: commit → push → PR → CI. Se una politica nega, le politiche successive nella catena vengono saltate (deny cortocircuita). +Applica un disciplinato workflow di fine sessione. Queste politiche si attivano sull'evento **Stop** e negano all'agente di fermarsi fino a quando ogni condizione non è soddisfatta. Seguono una catena di dipendenza naturale: commit → push → PR → CI. Se una politica nega, le politiche successive nella catena vengono saltate (deny cortocircuita). -Tutte le politiche di flusso di lavoro sono **fail-open**: se lo strumento richiesto non è disponibile (ad es. `gh` non installato, nessun git remote), la politica consente con un messaggio informativo che spiega perché il controllo è stato saltato. +Tutte le politiche di workflow sono **fail-open**: se lo strumento richiesto non è disponibile (ad es. `gh` non installato, nessun remote git), la politica consente con un messaggio informativo che spiega perché il controllo è stato saltato. -### Semantica Stop per CLI +### Semantica dello Stop per CLI -L'applicazione dello Stop sembra leggermente diversa tra i sei CLI supportati perché ognuno espone un contratto hook "agente terminato" diverso. L'**risultato** è lo stesso — l'agente non scappa fermarsi mentre un gate del flusso di lavoro sta fallendo — ma i **meccanismi** differiscono. La tabella seguente riassume; solo Pi ha una stranezza visibile all'utente che vale la pena capire prima di abilitare una politica `require-*-before-stop`. +L'applicazione dello Stop sembra leggermente diversa nei sei CLI supportati perché ognuno espone un contratto di hook "agente finito" diverso. L'**outcome** è lo stesso — l'agente non si allontana dall'arresto mentre un gate del workflow sta fallendo — ma la **meccanica** differisce. La tabella seguente riassume; solo Pi ha un'eccentricità visibile all'utente che vale la pena capire prima di abilitare una politica `require-*-before-stop`. -| CLI | Quando il gate si attiva | Cosa vedi | +| CLI | Quando si attiva il gate | Cosa vedi | |---|---|---| -| Claude Code | Stesso ciclo agente, immediatamente | Claude continua a lavorare — corregge il problema, quindi tenta di terminare di nuovo. Nessuna interruzione visibile per te. | -| Codex | Stesso ciclo agente, immediatamente | Uguale a Claude. | -| GitHub Copilot CLI | Stesso ciclo agente, immediatamente | Uguale a Claude (utilizza il canale di ripetizione `{decision:"block", reason}` di Copilot — verificato empiricamente contro Copilot CLI 1.0.41). | -| Cursor Agent | Stesso ciclo agente, immediatamente | Uguale a Claude (utilizza il canale `{followup_message}` di Cursor — limitato a `loop_limit`, predefinito 5 tentativi). | -| OpenCode | Stesso ciclo agente, immediatamente | Uguale a Claude (utilizza la chiamata SDK `client.session.prompt(...)` di OpenCode instradato attraverso `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Turno utente successivo** | **Pi si ferma visibilmente** quando il gate si attiva — il suo ciclo agente esce e vieni restituito al prompt. Il gate si attiva quindi la prossima volta che invii un prompt: failproofai antepone una direttiva `MANDATORY ACTION REQUIRED` al prompt di sistema di quel turno, istruendo l'LLM a completare il passo del flusso di lavoro (commit, push, ecc.) prima di fare quello che hai chiesto. | +| Claude Code | Stesso ciclo di agente, immediatamente | Claude continua a lavorare — risolve il problema, quindi tenta di finire di nuovo. Nessuna interruzione visibile a te. | +| Codex | Stesso ciclo di agente, immediatamente | Come Claude. | +| GitHub Copilot CLI | Stesso ciclo di agente, immediatamente | Come Claude (usa il canale di retry `{decision:"block", reason}` di Copilot — verificato empiricamente contro Copilot CLI 1.0.41). | +| Cursor Agent | Stesso ciclo di agente, immediatamente | Come Claude (usa il canale `{followup_message}` di Cursor — limitato a `loop_limit`, default 5 tentativi). | +| OpenCode | Stesso ciclo di agente, immediatamente | Come Claude (usa la chiamata SDK `client.session.prompt(...)` di OpenCode instradata attraverso `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Turno utente successivo** | **Pi si ferma visibilmente** quando si attiva il gate — il suo ciclo di agente esce e vieni riportato al prompt. Il gate si attiva quindi la prossima volta che invii un prompt: failproofai prepende una direttiva `MANDATORY ACTION REQUIRED` al prompt di sistema di quel turno, istruendo l'LLM a completare il passo di workflow (commit, push, ecc.) prima di fare quello che hai chiesto. | -**Limitazione Pi.** L'`AgentEndEvent` di Pi (l'equivalente a monte dell'hook `Stop` di Claude) non ha un tipo Result — nel momento in cui si attiva, il ciclo agente di Pi è già uscito. Pi non può essere forzato a ritentare lo stesso ciclo come Claude / Copilot / Cursor / OpenCode possono. failproofai sposta il gate all'evento `before_agent_start` di Pi (che si attiva dopo il prossimo prompt dell'utente) in modo che il controllo del flusso di lavoro si applichi ancora, solo al turno successivo anziché a quello corrente. +**Limitazione di Pi.** L'`AgentEndEvent` di Pi (l'equivalente upstream del hook `Stop` di Claude) non ha un tipo Result — nel momento in cui si attiva, il ciclo di agente di Pi è già uscito. Pi non può essere forzato a riprovare lo stesso ciclo come possono fare Claude / Copilot / Cursor / OpenCode. failproofai sposta il gate all'evento `before_agent_start` di Pi (che si attiva dopo il prompt utente successivo) così il controllo del workflow si applica comunque, solo sul turno successivo anziché su quello attuale. **Cosa significa in pratica:** -- Dopo che Pi si ferma, la ragione del deny viene acquisita in memoria con chiave dall'id della sessione Pi. Il prossimo prompt che invii nella stessa sessione Pi lo scarica: l'LLM vede la direttiva `MANDATORY ACTION REQUIRED` in cima al suo prompt di sistema, esegue il commit (o push / apre la PR / attende CI), e solo allora continua con la tua richiesta. La ragione del deny acquisita è one-shot — una volta scaricata, il gate è chiaro. -- Il gate è vincolato dalla durata del processo Pi. Se esegui `Ctrl+C` Pi o esci tra i turni, la voce in memoria viene eliminata insieme al processo e il gate viene mancato. Claude, Copilot, Cursor e OpenCode hanno lo stesso vincolo (uccidi l'agente e il gate viene mancato) — Pi lo rende solo più visibile perché l'agente esce visibilmente prima che il gate si attivi. -- Un deny in sospeso viene anche cancellato su `session_shutdown` per qualsiasi motivo (`new` / `resume` / `fork` / `quit`), quindi un gate stantio da una sessione precedente non può fuoriuscire in una nuova sessione avviata nello stesso processo Pi. +- Dopo che Pi si ferma, il motivo di negazione viene acquisito in memoria con chiave per l'id sessione Pi. Il prompt successivo che invii nella stessa sessione Pi lo scarica: l'LLM vede la direttiva `MANDATORY ACTION REQUIRED` in cima al suo prompt di sistema, fa il commit (o pusha / apre la PR / aspetta che CI sia verde) e solo dopo continua con la tua richiesta. Il motivo di negazione acquisito è one-shot — una volta scaricato, il gate è libero. +- Il gate è limitato dalla durata del processo di Pi. Se fai `Ctrl+C` su Pi o esci tra i turni, l'entry in memoria viene droppata insieme al processo e il gate viene mancato. Claude, Copilot, Cursor e OpenCode hanno lo stesso limite (uccidi l'agente e il gate viene mancato) — Pi lo rende solo più visibile perché l'agente esce visibilmente prima che il gate si attivi. +- Un'eventuale negazione viene anche cancellata su `session_shutdown` per qualsiasi motivo (`new` / `resume` / `fork` / `quit`), quindi un gate stantio da una sessione precedente non può trapelare in una sessione fresca avviata nello stesso processo di Pi. -Se hai bisogno di un retry nello stesso ciclo in stile Claude, esegui le tue politiche `Stop` sotto uno qualsiasi degli altri cinque CLI supportati. Stiamo tracciando Pi a monte per un futuro tipo Result su `AgentEndEvent` che ci permetterebbe di colmare questo gap. +Se hai bisogno di riprova dello stesso ciclo in stile Claude, esegui le tue politiche `Stop` sotto uno qualsiasi degli altri cinque CLI supportati. Stiamo seguendo Pi upstream per un futuro tipo Result su `AgentEndEvent` che ci permetterebbe di chiudere questo divario. ### `require-commit-before-stop` **Evento:** Stop -**Predefinito:** Nega la fermata quando ci sono modifiche non impegnate (file modificati, stage o non tracciati). Restituisce un messaggio informativo quando la directory di lavoro è pulita. +**Impostazione predefinita:** Nega l'arresto quando ci sono modifiche non committate (file modificati, staged o non tracciati). Restituisce un messaggio informativo quando la directory di lavoro è pulita. Nessun parametro. @@ -758,13 +764,13 @@ Nessun parametro. ### `require-push-before-stop` **Evento:** Stop -**Predefinito:** Nega la fermata quando ci sono commit non pushati o quando il branch corrente non ha un branch di tracciamento remoto. Suggerisce `git push -u` per creare un branch di tracciamento se necessario. Fallisce open se nessun remote è configurato. +**Impostazione predefinita:** Nega l'arresto quando ci sono commit non pushati o quando il branch attuale non ha un branch di tracking remoto. Suggerisce `git push -u` per creare un branch di tracking se necessario. Fallback aperto se nessun remoto è configurato. **Parametri:** | Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Nome del remote a cui pushare. | +| `remote` | `string` | `"origin"` | Nome remoto su cui pushare. | **Esempio:** @@ -783,14 +789,14 @@ Nessun parametro. ### `require-pr-before-stop` **Evento:** Stop -**Predefinito:** Nega la fermata quando non esiste una pull request per il branch corrente, o quando la PR esistente è chiusa senza essere merge. Istruisce Claude a creare una PR con `gh pr create`. Quando la PR viene **merge**, la politica consente (il lavoro è stato spedito) e il messaggio suggerisce di disattivare il branch (`git checkout main && git pull`). +**Impostazione predefinita:** Nega l'arresto quando non esiste una pull request per il branch attuale o quando la PR esistente è chiusa senza merge. Istruisce Claude a creare una PR con `gh pr create`. Quando la PR è **merged**, la politica consente (il lavoro è stato spedito) e il messaggio suggerisce di passare da un altro branch (`git checkout main && git pull`). Nessun parametro. Questa politica richiede che [GitHub CLI](https://cli.github.com/) (`gh`) sia installato e autenticato. -Esegui `gh auth login` con un token di accesso personale che ha l'ambito `repo` per l'accesso in lettura alle -pull request. Se `gh` non è installato o non autenticato, la politica fallisce open e riporta il motivo a Claude. +Esegui `gh auth login` con un personal access token che ha scope `repo` per l'accesso in lettura alle +pull request. Se `gh` non è installato o non autenticato, la politica fallback aperto e segnala il motivo a Claude. --- @@ -798,24 +804,24 @@ pull request. Se `gh` non è installato o non autenticato, la politica fallisce ### `require-no-conflicts-before-stop` **Evento:** Stop -**Predefinito:** Nega la fermata quando il branch corrente non può eseguire il merge in modo pulito nel branch di base. La politica prima conferma che c'è una PR `OPEN` su GitHub per il branch — senza una, non c'è un target di merge da applicare, quindi l'intera politica cortocircuita a consentire. Una volta che una PR `OPEN` è confermata, due sonde indipendenti vengono eseguite: +**Impostazione predefinita:** Nega l'arresto quando il branch attuale non può effettuare il merge pulito nel branch base. La politica prima conferma che esiste una PR `OPEN` su GitHub per il branch — senza una, non c'è un target di merge da applicare, quindi l'intera politica cortocircuita per consentire. Una volta confermata una PR `OPEN`, vengono eseguiti due probe indipendenti: -1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. In caso di conflitto, il messaggio di deny nomina i file in conflitto in modo che Claude sappia esattamente cosa risolvere. -2. **GitHub** — riutilizza il risultato `gh pr view --json mergeable,state` già recuperato nella verifica preliminare. Individua i conflitti che un `origin/` locale stantio avrebbe mancato (ad es. qualcuno ha fatto il land di una PR in conflitto su `main` dall'ultimo fetch). Un risultato `CONFLICTING` nega. Un risultato `UNKNOWN` nega anche e istruisce Claude ad aspettare ~10 secondi e ri-controllare prima di tentare di fermarsi di nuovo — questo previene falsi negativi mentre GitHub ricalcola. +1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. Su conflitto, il messaggio di negazione nomina i file in conflitto così Claude sa esattamente cosa risolvere. +2. **GitHub** — riusa il risultato `gh pr view --json mergeable,state` già recuperato nel precheck. Cattura i conflitti che un `origin/` locale stantio perderebbe (ad es. qualcuno ha fatto il land di una PR conflittuale su `main` dall'ultimo fetch). Un risultato `CONFLICTING` nega. Un risultato `UNKNOWN` nega anche e istruisce Claude ad aspettare ~10 secondi e ri-controllare prima di tentare di fermarsi di nuovo — questo previene falsi negativi mentre GitHub ricalcola. -Salta interamente (consente) quando: `gh` non è installato, non esiste una PR per il branch, lo stato della PR non è `OPEN` (ad es. `MERGED`, `CLOSED`), o `gh pr view` restituisce output non analizzabile. Fallisce anche open quando `origin/` è mancante localmente o quando nessun commit è in anticipo sulla base — quelle fall-through di Strato 1 consultano comunque la mergeability della PR memorizzata nella cache prima di consentire. +Salta interamente (consente) quando: `gh` non è installato, nessuna PR esiste per il branch, lo stato della PR non è `OPEN` (ad es. `MERGED`, `CLOSED`), o `gh pr view` ritorna output non parsabile. Fallback aperto anche quando `origin/` è mancante localmente o quando non ci sono commit in avanti rispetto a base — quelle fall-through di Layer 1 consultano comunque la mergeability della PR cacheata prima di consentire. **Parametri:** | Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Branch di base su cui verificare i conflitti. | +| `baseBranch` | `string` | `"main"` | Branch base da controllare per conflitti. | -GitHub CLI (`gh`) è richiesto per questa politica. La politica utilizza `gh pr view` per confermare -che esiste una PR `OPEN` prima di eseguire qualsiasi sonda di conflitto — senza `gh`, la politica -cortocircuita a consentire. Esegui `gh auth login` con un token di accesso personale che ha -l'ambito `repo` per l'accesso in lettura alle pull request. +GitHub CLI (`gh`) è richiesto per questa politica. La politica usa `gh pr view` per confermare +che esiste una PR `OPEN` prima di eseguire qualsiasi probe di conflitto — senza `gh`, la politica +cortocircuita per consentire. Esegui `gh auth login` con un personal access token che ha +scope `repo` per l'accesso in lettura alle pull request. --- @@ -823,23 +829,23 @@ l'ambito `repo` per l'accesso in lettura alle pull request. ### `require-ci-green-before-stop` **Evento:** Stop -**Predefinito:** Nega la fermata quando i controlli CI stanno fallendo o sono ancora in esecuzione sul branch corrente. Controlla sia le esecuzioni del flusso di lavoro GitHub Actions che i controlli di bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta conclusioni `skipped`, `cancelled` e `neutral` come non fallimentari (quest'ultima copre ad es. avvisi di Socket Security su PR di contributori esterni, dove l'app intenzionalmente riporta neutral anziché success/failure). Restituisce un messaggio informativo quando tutti i controlli passano. +**Impostazione predefinita:** Nega l'arresto quando i controlli CI stanno fallendo o ancora in esecuzione sul branch attuale. Controlla sia i workflow run di GitHub Actions che i controlli di bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta le conclusioni `skipped`, `cancelled` e `neutral` come non-fallimento (quest'ultima copre ad es. gli alert di Socket Security su PR di contributor esterno, dove l'app intenzionalmente segnala neutral anziché success/failure). Restituisce un messaggio informativo quando tutti i controlli passano. Nessun parametro. Questa politica richiede che [GitHub CLI](https://cli.github.com/) (`gh`) sia installato e autenticato. -Esegui `gh auth login` con un token di accesso personale che ha l'ambito `repo` per l'accesso in lettura alle -esecuzioni del flusso di lavoro Actions e all'API Checks. Se `gh` non è installato o non autenticato, la politica fallisce open e riporta il motivo a Claude. +Esegui `gh auth login` con un personal access token che ha scope `repo` per l'accesso in lettura ai +workflow run di Actions e l'API Checks. Se `gh` non è installato o non autenticato, la politica fallback aperto e segnala il motivo a Claude. --- --- -## Disabilitazione di politiche individuali +## Disabilitazione di singole politiche -Rimuovi una politica specifica da `enabledPolicies` nella tua configurazione, o disattivarla nella scheda Politiche del dashboard. +Rimuovi una politica specifica da `enabledPolicies` nel tuo config, o disattivala nella scheda Politiche della dashboard. ```json { @@ -850,4 +856,4 @@ Rimuovi una politica specifica da `enabledPolicies` nella tua configurazione, o } ``` -Le politiche non elencate in `enabledPolicies` non vengono eseguite, anche se le voci `policyParams` esistono per loro. \ No newline at end of file +Le politiche non elencate in `enabledPolicies` non vengono eseguite, anche se esistono entry `policyParams` per loro. \ No newline at end of file diff --git a/docs/it/cli/audit.mdx b/docs/it/cli/audit.mdx index 44087ef6..c81b6255 100644 --- a/docs/it/cli/audit.mdx +++ b/docs/it/cli/audit.mdx @@ -1,23 +1,23 @@ --- -title: Audit delle sessioni passate (beta) -description: "Conta quante volte l'agente ha fatto cose inutili o rischiose nei transcript passati" +title: Audit past sessions (beta) +description: "Conta quanto spesso l'agente ha fatto cose inutili o rischiose nei trascritti passati" --- - **Funzionalità beta.** L'audit viene distribuito in versione beta mentre raccogliamo i primi feedback. - Il catalogo dei rilevatori e il formato del report potrebbero cambiare prima della prossima release stabile. - Apri una segnalazione se qualcosa non ti sembra corretto. + **Funzionalità beta.** L'audit viene fornito come beta mentre raccogliamo feedback iniziali. + Il catalogo dei rilevatori e il formato del report potrebbero cambiare prima della prossima versione stabile. + Apri una issue se qualcosa non ti sembra corretto. -L'audit riproduce i tuoi transcript passati dell'agente-CLI attraverso il motore di policy di failproofai e genera un report visivo e condivisibile sulla **pagina dashboard `/audit`** — l'archetipo del tuo agente, un punteggio da 0–100, e esattamente quali policy avrebbero catturato cosa. +L'audit riproduce i tuoi trascritti agent-CLI passati attraverso il motore di policy di failproofai e visualizza un report condivisibile e visuale sulla **pagina dashboard `/audit`** — l'archetipo dell'agente, un punteggio 0–100, e esattamente quali policy avrebbero rilevato cosa. -## Eseguirlo +## Avvialo -Tre modi di accesso — tutti portano allo stesso report `/audit`. +Tre modi per iniziare — tutti portano allo stesso report `/audit`. -```bash npx (nessuna installazione) +```bash npx (no install) npx -y failproofai audit ``` @@ -32,95 +32,99 @@ failproofai - + `npx -y failproofai audit` scarica failproofai, esegue la scansione e apre il dashboard per te — niente da installare prima. - + `failproofai audit` esegue la scansione nel tuo terminale, poi apre `localhost:8020/audit` automaticamente al termine. - Esegui `failproofai` e fai clic su **Audit** nella barra di navigazione (tra Policies e + Esegui `failproofai` e clicca su **Audit** nella navbar (tra Policies e Projects), oppure apri `/audit` direttamente. - Esegui `failproofai audit -h` (o `--help`) per vedere l'utilizzo. L'audit viene eseguito **completamente offline** — non è necessario alcun account o connessione di rete — e il dashboard continua a servire finché non lo arresti con `Ctrl+C`. + Esegui `failproofai audit -h` (o `--help`) per vederne l'uso. L'audit funziona **completamente offline** — nessun account o rete richiesta — e il dashboard continua a servire finché non lo fermi con `Ctrl+C`. -Il dashboard scansiona i transcript CLI dell'agente passati su questa macchina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) e segnala con quale frequenza l'agente ha fatto cose che failproofai è costruito per fermare — controlli di variabili d'ambiente, push forzati, prefissi ridondanti `cd `, loop di sleep-polling, ri-letture di file appena modificati, e altro ancora. +Il dashboard esegue una scansione dei trascritti agent CLI passati su questa macchina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) e segnala quanto spesso l'agente ha fatto cose che failproofai è costruito per prevenire — controlli di variabili d'ambiente, force push, prefissi `cd ` ridondanti, loop di sleep-polling, ri-lettura di file appena modificati, e altro. -Per ogni transcript, ogni evento di tool-use viene riprodotto attraverso le 39 policy builtin **e** attraverso 8 rilevatori audit-only che catturano pattern non ancora coperti dalle policy di runtime. I conteggi vengono aggregati per policy / rilevatore su tutte le sessioni. +Per ogni trascritto, ogni evento tool-use viene riprodotto attraverso le 39 policy builtin **e** attraverso 8 rilevatori solo-audit che catturano pattern non ancora coperti dalle policy runtime. I conteggi sono aggregati per policy / rilevatore su tutte le sessioni. -## Cosa ottieni +## Quello che ottieni -La pagina `/audit` è un singolo **poster** su schermo seguito da quattro sezioni under-the-fold: +La pagina `/audit` è un **poster** a singolo schermo e condivisibile seguito da quattro sezioni sotto la piega: -1. **Poster** — l'identità del tuo agente a colpo d'occhio: il suo **archetipo** (uno di 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), le sue keyword di persona, quanto raro è quell'archetipo, e un **punteggio da 0–100** con una banda di livello (`S` fino a `bottom tier`). Costruito per essere condiviso — pubblica su X o LinkedIn, oppure scaricalo come PNG. -2. **`// strengths`** — quello che il tuo agente già fa bene, come numeri reali dalla scansione (es. clean-tool-call %, `0` tentativi di push-to-main), mostrato solo dove la policy rilevante ha un record pulito. -3. **`// quirks`** — quello che è passato: una tabella classificata di comportamenti che failproofai avrebbe catturato — *quando* è accaduto l'ultima volta, *cosa è passato* (e il builtin che l'avrebbe bloccato), la sua *gravità*, e quanto spesso è stato *visto* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — l'elenco delle correzioni prescritte: una riga per policy con un comando `failproofai policy add ` copia-incolla, più un pulsante **install all** che abilita ogni raccomandazione contemporaneamente e mostra il tuo **punteggio previsto** se lo facessi. -5. **`// come back better`** — costruisci l'abitudine: imposta un **reminder** di re-audit via email (`3d` / `7d` / `14d` / `30d`) o esegui il re-audit ora, e **invita un amico** a eseguire il proprio audit (inviato da failproof.ai, in copia a te). I reminder e gli inviti richiedono l'accesso. +1. **Poster** — l'identità del tuo agente a colpo d'occhio: il suo **archetipo** (uno di 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), le sue parole chiave di persona, quanto raro è quell'archetipo, e un **punteggio 0–100** con una banda di livello (`S` fino a `bottom tier`). Realizzato per essere condiviso — pubblica su X o LinkedIn, o scaricalo come PNG. +2. **`// strengths`** — quello che il tuo agente fa già bene, come numeri reali dalla scansione (es. clean-tool-call %, `0` tentativi push-to-main), mostrato solo dove la policy rilevante ha un record pulito. +3. **`// quirks`** — quello che è sfuggito: una tabella classificata di comportamenti che failproofai avrebbe rilevato — *quando* è accaduto l'ultima volta, *cosa è sfuggito* (e il builtin che l'avrebbe bloccato), la sua *severità*, e quanto spesso è stato *visto* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — la lista di correzioni prescritte: una riga per policy con un copia-incolla `failproofai policy add `, più un pulsante **install all** che abilita ogni raccomandazione contemporaneamente e mostra il tuo **punteggio previsto** se lo facessi. +5. **`// come back better`** — costruisci l'abitudine: imposta un **reminder** di re-audit per email (`3d` / `7d` / `14d` / `30d`) o esegui un re-audit adesso, e **invita un amico** a eseguire il proprio audit (inviato da failproof.ai, Cc a te). Reminder e inviti richiedono l'accesso. ## Audit programmati Se esegui il **daemon failproofaid** (vedi [`failproofai config`](/it/cli/install-policies)), -può rieseguire l'audit per te secondo una pianificazione e aggiornare il report `/audit` in -background. È **disattivato per impostazione predefinita**, perché la scansione legge il *contenuto* -di ogni transcript di sessione dell'agente su questa macchina — nulla viene scansionato su un timer +può eseguire nuovamente l'audit per te secondo una programmazione e aggiornare il report `/audit` in +background. È **disabilitato per impostazione predefinita**, perché la scansione legge il *contenuto* +di ogni trascritto di sessione agente su questa macchina — niente viene scansionato su un timer finché non lo richiedi. -Attivalo in `~/.failproofai/config.toml`: +Attivalo in `~/.failproofai/config.json` — aggiungi la chiave `audit` insieme a +tutto il resto che il file contiene già: -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | Chiave | Significato | |---|---| -| `auto` | `true` abilita la scansione programmata. Qualsiasi altra cosa — assente, `false`, `"yes"` — è disattivata. | -| `interval_days` | Giorni tra le scansioni. Limitato a 1–90; `0`, un valore negativo o un non-numero ricadono su `7`. | +| `auto` | `true` abilita la scansione programmata. Qualsiasi altra cosa — assente, `false`, `"yes"` — è disabilitato. | +| `interval_days` | Giorni tra le scansioni. Limitato a 1–90; `0`, un numero negativo o non-numero ritorna a `7`. | -- La pianificazione è **wall-clock**, quindi sopravvive alla sospensione e ai riavvii: un laptop - che era in sleep oltre il suo orario dovuto esegue **una volta** al risveglio, mai un backlog. -- Ogni esecuzione è un processo separato e a bassa priorità (`nice 19`) — mai il percorso hook del daemon, che rimane libero per rispondere alle chiamate di tool. +- La programmazione è **basata sull'orologio di parete**, quindi sopravvive a sospensioni e riavvii: un laptop + che era in sospensione oltre l'ora dovuta esegue **una volta** al risveglio, mai un backlog. +- Ogni esecuzione è un processo separato e a bassa priorità (`nice 19`) — mai il percorso hook del daemon, che rimane libero per rispondere alle tool call. - Una scansione viene saltata se `failproofai audit` o il re-run del dashboard è già - in corso; viene riprovat poco dopo invece di essere trattata come un fallimento. -- Il progresso viene scritto in `~/.failproofai/state/audit-schedule.json` (ultima esecuzione, - prossima scadenza). Il daemon possiede quel file — cambia la cadenza in `config.toml`. + in corso; viene ritentato poco dopo invece di essere trattato come un errore. +- L'avanzamento viene scritto in `~/.failproofai/state/audit-schedule.json` (ultima esecuzione, + prossima scadenza). Il daemon possiede quel file — cambia il ritmo in `config.json`. -Se hai abilitato questa funzione su una macchina configurata da un failproofai più vecchio, esegui -`failproofai config` una volta. La definizione del servizio del daemon ha bisogno di una voce -aggiuntiva prima di poter lanciare la CLI, e l'aggiornamento fa parte di quel comando. +Se hai abilitato questo su una macchina configurata da un failproofai più vecchio, esegui +`failproofai config` una volta. La definizione del servizio del daemon ha bisogno di una voce aggiuntiva +prima di poter lanciare la CLI, e l'aggiornamento fa parte di quel comando. -## Rilevatori audit-only +## Rilevatori solo-audit -Questi rilevatori catturano pattern di "comportamento stupido" non (ancora) applicati in tempo reale. Vengono eseguiti solo durante l'audit e non bloccano mai una chiamata di tool dal vivo. +Questi rilevano pattern di "comportamento stupido" non (ancora) applicati in tempo reale. Vengono eseguiti solo durante l'audit e non bloccano mai una tool call live. | Rilevatore | Cosa conta | |---|---| | `redundant-cd-cwd` | Comandi Bash che iniziano con `cd && …` anche se i comandi vengono già eseguiti in `cwd`. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` su un singolo file sorgente — usa il tool `Read`. | -| `prefer-edit-over-sed-awk` | Modifiche in-place `sed -i` / `awk … > file` — usa il tool `Edit`. | -| `prefer-write-over-heredoc` | Scrittura di file tramite heredoc / multi-line `echo > file` — usa il tool `Write`. | -| `sleep-polling-loop` | Long `sleep N` (≥ 30s) o loop di polling `while …; sleep …; done`. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, ecc. — limita a `cwd` invece. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, saltando gli hook. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` su un singolo file sorgente — usa lo strumento `Read`. | +| `prefer-edit-over-sed-awk` | Edit in-place `sed -i` / `awk … > file` — usa lo strumento `Edit`. | +| `prefer-write-over-heredoc` | Heredoc / multi-linea `echo > file` che scrivono file — usa lo strumento `Write`. | +| `sleep-polling-loop` | `sleep N` lungo (≥ 30s) o loop di polling `while …; sleep …; done`. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, ecc. — circoscrivi a `cwd` invece. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, saltando i hook. | | `reread-after-edit` | `Read` di un file che è stato appena `Edit`/`Write` nella stessa sessione. | ## Cache -- **Cache per-transcript** in `~/.failproofai/cache/audit/.json` indicizzata da `(mtime, size, engineVersion, detectorVersion)` — si invalida automaticamente quando il transcript o il codice di policy/rilevatore cambia. Ogni voce memorizza anche un timestamp `cachedAt` come **metadati TTL** (non parte della chiave di cache); le voci più vecchie di **7 giorni** vengono rifiutate in lettura in modo che i risultati di lunga durata non sopravvivono all'evoluzione dell'intento del rilevatore. -- **Cache del risultato completo** in `~/.failproofai/audit-dashboard.json` (mode 0600). Permette al dashboard di eseguire il rendering istantaneamente durante la navigazione senza rieseguire. Anche rifiutato in lettura passati i **7 giorni TTL** — `/audit` ricade quindi nel suo stato vuoto e richiede una nuova esecuzione. Fai clic su `[ re-audit now ]` vicino al fondo del report per aggiornare — il re-audit invia `noCache: true`, quindi bypass la cache per-transcript e esegue nuovamente la scansione di ogni transcript invece di restituire il risultato memorizzato; l'esecuzione trasmette il progresso tramite una striscia sticky in alto e scambia il risultato al suo posto al completamento (nessun ricaricamento della pagina; un re-audit non riuscito mantiene il report precedente). +- **Cache per-trascritto** in `~/.failproofai/cache/audit/.json` con chiave `(mtime, size, engineVersion, detectorVersion)` — si invalida automaticamente quando il trascritto o il codice della policy/rilevatore cambia. Ogni voce memorizza anche un timestamp `cachedAt` come **metadati TTL** (non parte della chiave cache); le voci più vecchie di **7 giorni** vengono rifiutate in lettura così i risultati di lunga data non sopravvivono a rilevatori in evoluzione. +- **Cache risultato intero** in `~/.failproofai/audit-dashboard.json` (modalità 0600). Consente al dashboard di visualizzarsi istantaneamente nella navigazione senza ri-eseguire. Anche rifiutato in lettura oltre il **TTL di 7 giorni** — `/audit` allora ritorna al suo stato vuoto e richiede un'esecuzione fresca. Clicca `[ re-audit now ]` vicino al fondo del report per aggiornare — re-audit invia `noCache: true`, così bypassa la cache per-trascritto e ri-esegue la scansione di ogni trascritto invece di restituire il risultato in cache; l'esecuzione trasmette il progresso tramite una striscia sticky in alto e scambia il risultato in posizione al successo (nessun ricaricamento pagina; un re-audit fallito mantiene il report precedente). ## Note -- **Nessuna mutazione.** L'audit viene riprodotto in modalità read-only. `warn-repeated-tool-calls` viene saltato perché il suo sidecar per-session verrebbe altrimenti modificato. -- **Policy del workflow saltate.** Le policy `require-*-before-stop` si attivano solo su eventi `Stop` e `execSync` contro lo stato git dal vivo — non hanno un'interpretazione significativa di "cosa sarebbe successo nel 2025", quindi non compaiono nei conteggi dell'audit. -- **Policy personalizzate saltate.** I hook personalizzati forniti dall'utente non vengono riprodotti (potrebbero essere cambiati dalla sessione originale). \ No newline at end of file +- **Nessuna mutazione.** L'audit riproduce in modalità sola lettura. `warn-repeated-tool-calls` viene saltato perché il suo sidecar per-sessione altrimenti verrebbe modificato. +- **Policy di workflow saltate.** Le policy `require-*-before-stop` si attivano solo su eventi `Stop` e `execSync` contro lo stato git live — non hanno un'interpretazione significativa di "cosa sarebbe successo nel 2025", quindi non compaiono nei conteggi audit. +- **Policy personalizzate saltate.** Gli hook personalizzati forniti dall'utente non vengono riprodotti (potrebbero essere cambiati dalla sessione originale). \ No newline at end of file diff --git a/docs/it/cli/dashboard.mdx b/docs/it/cli/dashboard.mdx index 2b2d191c..c9a9a186 100644 --- a/docs/it/cli/dashboard.mdx +++ b/docs/it/cli/dashboard.mdx @@ -1,7 +1,6 @@ --- ---- title: Visualizza sessioni -description: "Avvia la dashboard per sfogliare le sessioni degli agent e gestire le policy" +description: "Avvia la dashboard per sfogliare le sessioni degli agenti e gestire le policy" --- ```bash @@ -14,10 +13,10 @@ Avvia la dashboard web su `http://localhost:8020`. | Flag | Descrizione | |------|-------------| -| `--port ` | Porta su cui ascoltare (predefinito: `8020`) | +| `--port ` | Porta su cui ascoltare (default: `8020`) | | `--allowed-origins ` | Host/IP separati da virgola autorizzati ad accedere alle risorse di sviluppo | -Per indirizzare la dashboard verso una cartella di progetti Claude non predefinita, imposta la variabile di ambiente `CLAUDE_PROJECTS_PATH` all'avvio. +Per indirizzare la dashboard a una cartella di progetto Claude non predefinita, imposta la variabile d'ambiente `CLAUDE_PROJECTS_PATH` al momento dell'avvio. ## Esempi @@ -25,6 +24,6 @@ Per indirizzare la dashboard verso una cartella di progetti Claude non predefini # Avvia su una porta diversa failproofai --port 9000 -# Usa un percorso personalizzato per i progetti Claude tramite variabile di ambiente +# Usa un percorso personalizzato per i progetti Claude tramite variabile d'ambiente CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/it/cli/environment-variables.mdx b/docs/it/cli/environment-variables.mdx index f47ba5c0..4f4457bd 100644 --- a/docs/it/cli/environment-variables.mdx +++ b/docs/it/cli/environment-variables.mdx @@ -8,58 +8,68 @@ description: "Configura il comportamento di failproofai con variabili d'ambiente | Variabile | Descrizione | |----------|-------------| | `PORT` | Porta del dashboard (default: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Sovrascrive dove trovare le cartelle dei progetti Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Pagine del dashboard separate da virgole da nascondere | +| `CLAUDE_PROJECTS_PATH` | Sostituisce la posizione delle cartelle di progetto di Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Pagine del dashboard separate da virgola da nascondere | | `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Host/IP autorizzati ad accedere alle risorse di sviluppo. Equivalente a `--allowed-origins`. | ## Logging | Variabile | Descrizione | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Livello dei log del server (default: `warn`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Livello di log del server (default: `warn`) | | `FAILPROOFAI_HOOK_LOG_FILE` | Percorso personalizzato del file di log degli hook, oppure `true` per il default (`~/.failproofai/logs/hooks.log`) | ## Telemetria -failproofai invia telemetria di utilizzo anonima per impostazione predefinita. Esistono due modi per disattivarla, e viene applicato il più restrittivo — una variabile d'ambiente non può mai riabilitare qualcosa che il file di configurazione ha disattivato. +failproofai segnala la telemetria di utilizzo anonima per impostazione predefinita. Ci sono due modi per +disattivarla, e si applica il più restrittivo — una variabile d'ambiente non può mai riabilitare +qualcosa che il file di configurazione ha disattivato. | Variabile | Descrizione | |----------|-------------| | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Disabilita la telemetria di utilizzo anonima per questo processo | -Per disattivarla permanentemente per la macchina, aggiungi questo a `~/.failproofai/config.toml`: +Per disattivarla permanentemente sulla macchina, aggiungi questo a `~/.failproofai/config.json`: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -Il file di configurazione è l'opzione da usare se esegui il **daemon failproofaid**. -Il daemon è un servizio a livello di sistema, e il suo ambiente non include -variabili esportate dalla tua shell — quindi `FAILPROOFAI_TELEMETRY_DISABLED` non -può raggiungerlo. `[telemetry] enabled = false` viene letto sia dalla CLI che dal daemon. +Il file di configurazione è l'opzione da usare se esegui il daemon **failproofaid**. +Il daemon è un servizio a livello di sistema e il suo ambiente non include +le variabili esportate dalla tua shell — quindi `FAILPROOFAI_TELEMETRY_DISABLED` non +può raggiungerlo. `[telemetry] enabled = false` è letto sia dalla CLI che dal daemon. -Il daemon invia solo il proprio **ciclo di vita**: che sia stato avviato (e se l'esecuzione precedente è terminata correttamente), che sia stato interrotto, quando il suo worker di valutazione è stato generato o riavviato, quando un'attività di raccolta ha avuto esito negativo, e l'esito di un pull di policy cloud. Questi portano valori e conteggi a bassa cardinalità — mai un percorso di file, un comando, una policy, un prompt, o qualcosa letto da una trascrizione. Non esiste alcun evento per ogni tool call. +Il daemon segnala solo il suo **ciclo di vita**: che si è avviato (e se l'esecuzione +precedente si è chiusa correttamente), che si è fermato, quando il suo worker di valutazione +è stato generato o riavviato, quando un'attività di raccolta è fallita, e l'esito di un +pull di policy cloud. Questi portano valori a bassa cardinalità e conteggi — mai un percorso di file, +un comando, una policy, un prompt, o qualcosa letto da una trascrizione. Non c'è +un evento per singola chiamata di tool. ## Autenticazione | Variabile | Descrizione | |----------|-------------| -| `FAILPROOF_API_URL` | Sovrascrive l'URL base del server API utilizzato dalla finestra di dialogo di autenticazione del dashboard. Default: `https://api.befailproof.ai`; imposta a `http://localhost:8080` (o dove preferisci) quando esegui un api-server locale. | -| `FAILPROOFAI_AUTH_DIR` | Sovrascrive dove `auth.json` è memorizzato (default: `~/.failproofai`). Principalmente utile per test isolati. | +| `FAILPROOF_API_URL` | Sostituisce l'URL base del server API utilizzato dalla finestra di dialogo di autenticazione del dashboard. Default: `https://api.befailproof.ai`; imposta su `http://localhost:8080` (o ovunque) quando si esegue un server API locale. | +| `FAILPROOFAI_AUTH_DIR` | Sostituisce il percorso di salvataggio di `auth.json` (default: `~/.failproofai`). Utile principalmente per test isolati. | -## Prompt al primo avvio +## Prompt della prima esecuzione | Variabile | Descrizione | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Salta il prompt che offre di installare le policy al primo avvio con il comando `failproofai` nudo | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Salta il prompt che offre di installare le policy al primo comando `failproofai` senza opzioni | ## LLM (per la valutazione delle policy) | Variabile | Descrizione | |----------|-------------| | `FAILPROOFAI_LLM_BASE_URL` | Endpoint dell'API LLM (default: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Chiave API per le policy abilitate da LLM | +| `FAILPROOFAI_LLM_API_KEY` | Chiave API per le policy alimentate da LLM | | `FAILPROOFAI_LLM_MODEL` | Nome del modello (default: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/it/cli/hook.mdx b/docs/it/cli/hook.mdx index 572f185e..b8693330 100644 --- a/docs/it/cli/hook.mdx +++ b/docs/it/cli/hook.mdx @@ -1,30 +1,30 @@ --- -title: Hook handler (interno) -description: "Il sottoprocesso che Claude Code chiama su ogni evento di tool" +title: Gestore hook (interno) +description: "Il sottoprocesso che Claude Code chiama su ogni evento di strumento" --- ```bash failproofai --hook ``` -Questo è il comando registrato in `settings.json` di Claude Code da `failproofai policies --install`. Normalmente non lo chiami direttamente. +Questo è il comando registrato nel file `settings.json` di Claude Code da `failproofai policies --install`. Normalmente non lo chiami direttamente. -Legge un payload JSON da stdin, valuta tutte le policy abilitate e termina con un codice che indica la decisione: +Legge un payload JSON da stdin, valuta tutte le politiche abilitate e esce con un codice che indica la decisione: | Codice di uscita | Decisione | Effetto | |-----------|----------|--------| -| `0` | `allow` | Consenti l'azione | +| `0` | `allow` | Permetti l'azione | | `1` | `deny` | Blocca l'azione - Claude vede il motivo del rifiuto | -| `2` | `instruct` | Inietta una guida nel contesto di Claude | +| `2` | `instruct` | Inserisci indicazioni nel contesto di Claude | ### Tipi di evento supportati | Categoria | Eventi | |----------|--------| -| **Esecuzione tool** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | +| **Esecuzione di strumenti** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Ciclo di vita della sessione** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **Interazione utente** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **Subagenti e task** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **Subagentu e attività** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **Configurazione** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **File system** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **Contesto** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/it/cli/install-policies.mdx b/docs/it/cli/install-policies.mdx index 2eb2a8ea..9a218460 100644 --- a/docs/it/cli/install-policies.mdx +++ b/docs/it/cli/install-policies.mdx @@ -1,13 +1,14 @@ --- -title: Installa le policy -description: "Abilita le policy affinché vengano eseguite ad ogni chiamata di strumento dell'agent" +--- +title: Installa policy +description: "Abilita le policy in modo che vengano eseguite ad ogni chiamata di tool dell'agent" --- ```bash failproofai policies --install [policy-names...] [options] ``` -Scrive voci di hook nel file di impostazioni del CLI dell'agent installato (Claude Code, OpenAI Codex o GitHub Copilot CLI _(beta)_) affinché failproofai intercetti le chiamate di strumento. +Scrive voci di hook nel file di impostazioni della CLI dell'agent installata (Claude Code, OpenAI Codex, o GitHub Copilot CLI _(beta)_) in modo che failproofai intercetti le chiamate di tool. Alias: `failproofai p -i` @@ -15,17 +16,17 @@ Alias: `failproofai p -i` | Flag | Descrizione | |------|-------------| -| `--cli claude\|codex\|copilot` | CLI dell'agent per cui installare; separati da spazi (es. `--cli claude codex copilot`) o ripetuti. Ometti per rilevare i CLI installati e ricevere una richiesta. | -| `--scope user` | Installa nel file di impostazioni dell'ambito utente (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Predefinito. | -| `--scope project` | Installa nel file di impostazioni dell'ambito progetto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Solo Claude — installa in `/.claude/settings.local.json`. Codex e Copilot non dispongono di un ambito `local`. | -| `--custom ` / `-c` | Percorso di un file JS contenente policy di hook personalizzate | +| `--cli claude\|codex\|copilot` | CLI dell'agent per cui eseguire l'installazione; separati da spazio (ad es. `--cli claude codex copilot`) o ripetuti. Omettere per rilevare le CLI installate e ricevere una richiesta. | +| `--scope user` | Installa nel file di impostazioni con scope utente (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Impostazione predefinita. | +| `--scope project` | Installa nel file di impostazioni con scope progetto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Solo Claude — installa in `/.claude/settings.local.json`. Codex e Copilot non hanno uno scope `local`. | +| `--custom ` / `-c` | Percorso a un file JS contenente policy di hook personalizzate | ## Comportamento - **Nessun nome di policy** - apre una richiesta interattiva per selezionare le policy - **Nomi specifici** - abilita quelle policy (aggiunte a quelle già abilitate) -- **`all`** - abilita ogni policy disponibile +- **`all`** - abilita tutte le policy disponibili L'installazione è additiva: eseguire `--install` di nuovo aggiunge nuove policy senza rimuovere quelle esistenti. @@ -44,14 +45,14 @@ failproofai policies --install all # Installa con un file di policy personalizzate failproofai policies --install --custom ./my-policies.js -# Installa per OpenAI Codex (ambito progetto) +# Installa per OpenAI Codex (scope progetto) failproofai policies --install --cli codex --scope project # Installa per GitHub Copilot CLI (beta) per il progetto corrente failproofai policies --install --cli copilot --scope project -# Installa per tutti e tre i CLI contemporaneamente +# Installa per tutte e tre le CLI contemporaneamente failproofai policies --install --cli claude codex copilot ``` -Quando viene fornito `--custom `, il file viene convalidato immediatamente - deve chiamare `customPolicies.add()` almeno una volta. Il percorso risolto viene salvato in `policies-config.json` come `customPoliciesPath`. \ No newline at end of file +Quando `--custom ` viene fornito, il file viene convalidato immediatamente - deve chiamare `customPolicies.add()` almeno una volta. Il percorso risolto viene salvato in `policies-config.json` come `customPoliciesPath`. \ No newline at end of file diff --git a/docs/it/cli/list-policies.mdx b/docs/it/cli/list-policies.mdx index 5b93bc93..a43d206e 100644 --- a/docs/it/cli/list-policies.mdx +++ b/docs/it/cli/list-policies.mdx @@ -1,15 +1,15 @@ --- -title: Elencare le policy -description: "Visualizza quali policy sono abilitate, i loro parametri e le policy personalizzate" +title: Elenco dei criteri +description: "Vedi quali criteri sono abilitati, i loro parametri e i criteri personalizzati" --- ```bash failproofai policies ``` -Mostra tutte le policy con il loro stato, i parametri configurati e le policy personalizzate. +Mostra tutti i criteri con il loro stato, i parametri configurati e i criteri personalizzati. -## Output di esempio +## Esempio di output ```text Failproof AI Hook Policies (user) @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Le chiavi sconosciute in `policyParams` vengono segnalate qui in modo che tu possa individuare gli errori di battitura in anticipo. \ No newline at end of file +Le chiavi sconosciute in `policyParams` sono evidenziate qui in modo che tu possa individuare gli errori di battitura in anticipo. \ No newline at end of file diff --git a/docs/it/cli/migrate.mdx b/docs/it/cli/migrate.mdx new file mode 100644 index 00000000..e508e90a --- /dev/null +++ b/docs/it/cli/migrate.mdx @@ -0,0 +1,122 @@ +--- +title: Migrare la home directory +description: "Porta ~/.failproofai al layout di questa versione, e vedi prima cosa succederebbe" +--- + +```bash +failproofai migrate --dry-run # stampa il piano, non cambia nulla +failproofai migrate # eseguilo +``` + +La maggior parte delle persone non digita mai questo comando. Si esegue da solo al +primo comando dopo un aggiornamento, e [`failproofai update`](/it/cli/update) lo +include. Usalo direttamente quando vuoi vedere il piano prima che accada, o per +eseguire la migrazione in autonomia. + +## Basato sul layout, non sulla versione + +`~/.failproofai/VERSION` registra un numero di **layout** — la struttura della +directory, non la release che l'ha scritta. Le migrazioni si basano su quel numero, +il che rende economica una lunga pausa: + +- Le versioni npm cambiano ad ogni release, decine di esse tra due layout. +- Quindi una macchina che salta trenta release con **nessun cambio di layout** esegue + **zero** migrazioni, non trenta no-op. +- E una macchina che salta più layout contemporaneamente esegue ogni passo in ordine, + con ogni passo che conosce solo i suoi due estremi. + +Questo è importante perché npm non può aggiornare un pacchetto installato da solo. +Una macchina che rimane su una versione per mesi e poi salta più layout è il caso +normale, non uno esotico. + +## L'esecuzione in prova + +`--dry-run` stampa la catena esatta e i file che sarebbero salvati per primo, e +non cambia nulla affatto — nessuna migrazione, nessun backup, nessuna voce di +registro: + +``` +Layout 2 su disco; questa build parla 3. +1 passo/i verrebbe/ro eseguito/i: + 2 → 3 layout 2 → 3: porta config.toml e credentials.toml in JSON, sposta + custom-policies/ indietro in policies/, annida la configurazione + della policy alla radice + +Questi verrebbero copiati in ~/.failproofai/migrations/backup-layout2 per primo: + VERSION + config.toml + credentials.toml +``` + +## Cosa viene trasportato e cosa viene ricostruito + +Ogni percorso nella home dichiara che tipo di dato contiene, e ciò decide se una +migrazione può scartarlo. La regola: **ciò che è derivato e ri-recuperabile può +essere eliminato; qualsiasi cosa tu abbia digitato, qualsiasi cosa non ancora +consegnata, e qualsiasi cosa che identifichi la macchina viene trasportata.** + +| Trasportato | Ricostruito o ri-recuperato | +|---|---| +| `config.json` — impostazioni, `daemon.configured`, percorsi di acquisizione extra | La cache di audit | +| `credentials.json` — la tua iscrizione al cloud | Distribuzioni gestite dal cloud (ri-recuperate e verificate per digest al prossimo poll) | +| `policies-config.json` — la tua selezione di policy e parametri | Stato di scratch del daemon | +| `policies/` — i tuoi file di policy e gli helper che importano | | +| `hook-activity/` — il log delle decisioni che il dashboard legge | | +| Eventi non consegnati ancora in coda per l'upload | | +| `cursors/` — watermark del collector | | +| Il binario del daemon in `bin/` | | + + + Gli eventi non consegnati vengono trasportati piuttosto che scartati perché la + perdita sarebbe permanente, non lenta: il watermark del collector ha già + avanzato oltre qualsiasi cosa seduta nello spool, quindi nulla leggerebbe mai + di nuovo quell'intervallo di una trascrizione. La migrazione chiede anche al + daemon di consegnare quello che è nello spool non appena finisce, quindi il + risultato usuale è che non c'è nulla di sinistrante da trasportare. + + +Le chiavi che una versione *più nuova* ha scritto in `config.json`, +`credentials.json` o `policies-config.json` vengono preservate anche esse, piuttosto +che scartate da un lettore più vecchio. + +## Il record che lascia + +``` +~/.failproofai/migrations/ + applied.json una voce per passo: layout, CLI, timestamp, durata, risultato + backup-layout/ copie dei file insostituibili, prese prima del primo passo +``` + +`applied.json` è ciò che risponde a "cosa ha effettivamente attraversato questa +macchina" — la prima domanda che vale la pena fare quando qualcosa sembra sbagliato +dopo un aggiornamento. Allegalo a un rapporto di bug. + +Il backup è deliberatamente piccolo piuttosto che una copia di tutta la directory: +la migrazione non cancella più nulla di insostituibile per progetto, quindi ciò che +vale la pena assicurare è un *difetto in un passo*, e questi pochi file sono dove +un tale difetto farebbe male. + +## Se un passo fallisce + +La catena si ferma lì. `VERSION` viene marcato solo da un passo che ha completato, +quindi la home rimane marcata con il suo vecchio layout e il prossimo comando lo +ritenta — una home non viene mai marcata come corrente sulla base di una migrazione +parziale. Il passo viene registrato in `applied.json` con `"ok": false`, e il +backup rimane dove è stato preso. + +## Una home più nuova viene rifiutata, non migrata + +Se `~/.failproofai/` è stata scritta da un failproofai **più nuovo** di quello che +stai eseguendo, il comando si ferma e ti dice di aggiornare invece. Quei dati +vanno bene e una CLI più nuova li legge; migrare "avanti" da essi non è una cosa +che esiste, e ripristinarli distruggerebbe qualcosa di recuperabile. + +``` +La directory failproofai di questa macchina è stata scritta da una versione più +nuova (layout 4; questa build parla 3). Aggiorna piuttosto che migrare: + npm install -g failproofai@latest +``` + +Il daemon applica la stessa regola: `failproofaid` rifiuta di avviarsi contro un +layout che non conosce, piuttosto che leggere e scrivere percorsi che si sono +spostati. \ No newline at end of file diff --git a/docs/it/cli/remove-policies.mdx b/docs/it/cli/remove-policies.mdx index 9cda6430..cf5ab2d8 100644 --- a/docs/it/cli/remove-policies.mdx +++ b/docs/it/cli/remove-policies.mdx @@ -1,13 +1,13 @@ --- title: Disinstallare le policy -description: "Rimuovere le voci di hook dalle impostazioni di Claude Code" +description: "Rimuovere le voci hook dalle impostazioni di Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -Rimuove le voci di hook di failproofai dal file `settings.json` di Claude Code. +Rimuove le voci hook di failproofai da `settings.json` di Claude Code. Alias: `failproofai p -u` @@ -23,21 +23,21 @@ Alias: `failproofai p -u` ## Comportamento -- **Nessun nome di policy** - rimuove tutte le voci di hook di failproofai dal file di impostazioni +- **Nessun nome di policy** - rimuove tutte le voci hook di failproofai dal file di impostazioni - **Nomi specifici** - disabilita quelle policy ma mantiene gli hook installati ## Esempi ```bash -# Rimuove tutti gli hook globalmente +# Rimuovere tutti gli hook globalmente failproofai policies --uninstall -# Disabilita una policy specifica (mantiene gli hook installati) +# Disabilitare una policy specifica (mantiene gli hook installati) failproofai policies --uninstall block-sudo -# Rimuove gli hook da ogni ambito +# Rimuovere gli hook da ogni ambito failproofai policies --uninstall --scope all -# Cancella il percorso delle policy personalizzate +# Cancellare il percorso delle policy personalizzate failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/it/cli/update.mdx b/docs/it/cli/update.mdx new file mode 100644 index 00000000..6cb03c2d --- /dev/null +++ b/docs/it/cli/update.mdx @@ -0,0 +1,103 @@ +--- +--- +title: Aggiornamento dopo un upgrade +description: "Completare la seconda metà di un upgrade che npm non può fare: migrare la home e allineare il daemon" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +Questo è l'intero upgrade. `npm` sostituisce la CLI; `failproofai update` fa il +resto. + +## Perché esiste un secondo comando + +`npm install -g` sostituisce una sola cosa — la CLI. Due altri componenti di un +install di failproofai vivono fuori dal package di proposito, e nessuno dei due +si sposta quando npm viene eseguito: + +- **`~/.failproofai/`**, le tue impostazioni, l'iscrizione cloud, la selezione + delle policy e la cronologia. Una nuova versione potrebbe organizzarla + diversamente, e la riorganizzazione deve essere fatta da codice che conosce + entrambi i formati. +- **Il binario del daemon `failproofaid`**, in + `~/.failproofai/bin/failproofaid-`. È deliberatamente *non* dentro + `node_modules`: un upgrade che scambiasse il file sotto un servizio in + esecuzione farebbe puntare un daemon attivo a un binario costruito da source + diverso, e rimuovere il package lo eliminerebbe da sotto un servizio che poi + farebbe crash-loop a ogni boot. + +Quindi dopo solo `npm install -g`, la CLI è nuova ma il daemon non lo è. +`failproofaid` rifiuta di partire contro un layout home che non conosce — la +versione esplicita di quella incompatibilità piuttosto che quella silenziosa — +quindi le due metà devono essere allineate. `failproofai update` è quel passo. + +## Cosa fa + + + + Legge il layout registrato in `~/.failproofai/VERSION` ed esegue i passaggi + che lo portano a quello che questa versione riconosce. Di solito nessuno — + vedi [`failproofai migrate`](/it/cli/migrate). + + + Dal package della piattaforma che npm ha già scaricato dove possibile (senza + network), altrimenti dall'asset release per questa versione esatta, verificato + con SHA-256 prima di essere utilizzato. + + + Verificato piuttosto che dato per scontato — un gestore di servizi segnala un + processo attivo nel momento in cui si crea il fork, il che non è la stessa + cosa che funzionare. + + + +## Opzioni + +| Flag | Effetto | +|------|---------| +| `--no-daemon` | Migrare solo la home, lasciando il daemon alla sua versione attuale. | + + + `--no-daemon` lascia in posizione un daemon con versione non allineata. Su una + macchina configurata per richiedere il daemon, ogni hook event **fallisce in + modalità chiusa** se il daemon non può rispondere — e un daemon che rifiuta di + partire contro una home migrata non può rispondere. È preferibile lasciare che + la metà del daemon venga eseguita. + + +## Se qualcosa va male + +Il comando esce con codice diverso da zero e dice quale metà ha fallito. Due casi +che vale la pena conoscere: + +- **Un passaggio di migrazione non è terminato.** La home è lasciata contrassegnata + con il suo layout *vecchio*, quindi il comando successivo ritenta — nessuna home + è mai contrassegnata come attuale sulla base di una migrazione parziale. Copie + delle tue impostazioni e dell'iscrizione sono state salvate prima che qualcosa + venisse eseguito, in `~/.failproofai/migrations/backup-layout/`. +- **Il daemon non ha potuto essere riavviato senza una password.** `sudo -n` è + utilizzato deliberatamente, quindi niente chiede mai input sotto una visualizzazione + di progresso. Il comando stampa la linea esatta da eseguire tu stesso. + + + Niente di tutto ciò ha bisogno della procedura di configurazione interattiva. + Le tue impostazioni, l'iscrizione cloud e la selezione delle policy sopravvivono + a un upgrade, quindi una macchina migrata applica le stesse policy di prima — + il che importa più sulle macchine dove non c'è nessuno seduto davanti: un runner + CI, una box fleet, un gateway headless. + + +## Automatizzarlo + +`failproofai update` è non-interattiva ed è sicura da eseguire quando non c'è +nulla da fare — segnala non migration was needed e esce con 0. Metterlo dopo +ogni upgrade in uno script di provisioning o in un Dockerfile è l'uso previsto: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` in una build di immagine, dove non c'è ancora alcun servizio da +riavviare.) \ No newline at end of file diff --git a/docs/it/cli/version.mdx b/docs/it/cli/version.mdx index 69c07abf..a39b7c50 100644 --- a/docs/it/cli/version.mdx +++ b/docs/it/cli/version.mdx @@ -1,5 +1,6 @@ --- -title: Controlla versione +--- +title: Verifica versione description: "Stampa la versione installata di failproofai" --- @@ -9,4 +10,4 @@ failproofai --version failproofai -v ``` -Stampa il numero di versione installata. \ No newline at end of file +Stampa il numero di versione installato. \ No newline at end of file diff --git a/docs/it/configuration.mdx b/docs/it/configuration.mdx index 6393843b..411d3cfd 100644 --- a/docs/it/configuration.mdx +++ b/docs/it/configuration.mdx @@ -1,39 +1,38 @@ --- ---- title: Configurazione -description: "Formato del file di configurazione, sistema a tre scope e regole di unione" +description: "Formato del file di configurazione, sistema a tre scope e regole di merge" icon: gear --- -failproofai utilizza file di configurazione JSON per controllare quali politiche sono attive, come si comportano e da dove vengono caricate le politiche personalizzate. La configurazione è progettata per essere facile da condividere con il tuo team - commitla nel tuo repo e ogni sviluppatore ottiene la stessa rete di sicurezza per gli agent. +failproofai utilizza file di configurazione JSON per controllare quali policy sono attive, come si comportano e da dove vengono caricate le policy personalizzate. La configurazione è progettata per essere facile da condividere con il tuo team - committala nel tuo repository e ogni sviluppatore otterrà la stessa rete di sicurezza per gli agenti. --- -## Ambiti di configurazione +## Scope di configurazione -Esistono tre ambiti di configurazione, valutati in ordine di priorità: +Ci sono tre scope di configurazione, valutati in ordine di priorità: -| Ambito | Percorso file | Scopo | -|-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | Impostazioni per-repo, commitmate nel controllo versione | -| **local** | `.failproofai/policies-config.local.json` | Override personali per-repo, gitignored | +| Scope | Percorso file | Scopo | +|-------|---------------|-------| +| **project** | `.failproofai/policies-config.json` | Impostazioni per-repository, committate nel controllo versione | +| **local** | `.failproofai/policies-config.local.json` | Override personali per-repository, ignorati da git | | **global** | `~/.failproofai/policies-config.json` | Impostazioni predefinite a livello utente per tutti i progetti | -Quando failproofai riceve un evento hook, carica e unisce tutti e tre i file che esistono per la directory di lavoro corrente. +Quando failproofai riceve un evento hook, carica e fonde tutti e tre i file che esistono per la directory di lavoro corrente. -### Regole di unione +### Regole di merge -**`enabledPolicies`** - l'unione di tutti e tre gli ambiti. Una politica abilitata a qualsiasi livello è attiva. +**`enabledPolicies`** - l'unione di tutti e tre gli scope. Una policy abilitata a qualsiasi livello è attiva. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unione con deduplica +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unione deduplicate ``` -**`policyParams`** - il primo ambito che definisce i parametri per una determinata politica vince completamente. Non c'è fusione profonda dei valori all'interno dei parametri di una politica. +**`policyParams`** - il primo scope che definisce i parametri per una data policy prevale completamente. Non c'è merge profondo dei valori all'interno dei parametri di una policy. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -43,18 +42,18 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project vince, global ``` ```text -project: (nessuna voce block-sudo) -local: (nessuna voce block-sudo) +project: (no block-sudo entry) +local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade su global +resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade al global ``` -**`customPoliciesPaths` / `customPoliciesPath`** - il primo ambito che definisce una delle due forme vince. +**`customPoliciesPaths` / `customPoliciesPath`** - il primo scope che definisce una delle due forme vince. -**`disabledCustomPolicies`** - unione tra tutti gli ambiti. Il dashboard scrive un ID qualificato di origine qui quando disattivi una politica individuale da un file di politiche esplicite o per convenzione. Le politiche non elencate rimangono abilitate per impostazione predefinita; gli ID includono il file di origine in modo che politiche con lo stesso nome in più file possano essere controllate indipendentemente. +**`disabledCustomPolicies`** - unione tra tutti gli scope. Il dashboard scrive un ID qualificato dalla fonte qui quando disattivi una singola policy da un file di policy esplicito o per convenzione. Le policy non elencate rimangono abilitate per impostazione predefinita; gli ID includono il file di origine per permettere il controllo indipendente delle policy con lo stesso nome in più file. -**`llm`** - il primo ambito che lo definisce vince. +**`llm`** - il primo scope che la definisce vince. --- @@ -99,33 +98,33 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade su global --- -## Riferimento dei campi +## Riferimento campi ### `enabledPolicies` Tipo: `string[]` -Elenco dei nomi delle politiche da abilitare. I nomi devono corrispondere esattamente agli identificatori delle politiche mostrati da `failproofai policies`. Vedi [Built-in Policies](/it/built-in-policies) per l'elenco completo. +Elenco dei nomi delle policy da abilitare. I nomi devono corrispondere esattamente agli identificatori delle policy mostrati da `failproofai policies`. Consulta [Built-in Policies](/it/built-in-policies) per l'elenco completo. -Le politiche non in `enabledPolicies` sono inattive, anche se hanno voci in `policyParams`. +Le policy non in `enabledPolicies` sono inattive, anche se hanno voci in `policyParams`. ### `policyParams` Tipo: `Record>` -Override dei parametri per-politica. La chiave esterna è il nome della politica; le chiavi interne sono specifiche della politica. Ogni politica documenta i suoi parametri disponibili in [Built-in Policies](/it/built-in-policies). +Override di parametri per-policy. La chiave esterna è il nome della policy; le chiavi interne sono specifiche della policy. Ogni policy documenta i suoi parametri disponibili in [Built-in Policies](/it/built-in-policies). -Se una politica ha parametri ma non li specifichi, vengono utilizzati i valori predefiniti incorporati della politica. Gli utenti che non configurano affatto `policyParams` ottengono un comportamento identico alle versioni precedenti. +Se una policy ha parametri ma non li specifichi, vengono utilizzati i parametri predefiniti della policy. Gli utenti che non configurano `policyParams` del tutto ottengono un comportamento identico alle versioni precedenti. -Le chiavi sconosciute all'interno del blocco dei parametri di una politica vengono silenziosamente ignorate al momento dell'attivazione dell'hook, ma segnalate come avvisi quando esegui `failproofai policies`. +Le chiavi sconosciute all'interno del blocco dei parametri di una policy vengono silenziosamente ignorate quando l'hook si attiva, ma segnalate come avvertimenti quando esegui `failproofai policies`. #### `hint` (trasversale) Tipo: `string` (opzionale) -Un messaggio aggiunto al motivo quando una politica restituisce `deny` o `instruct`. Usalo per dare a Claude una guida attuabile senza modificare la politica stessa. +Un messaggio aggiunto al motivo quando una policy restituisce `deny` o `instruct`. Usalo per dare a Claude una guida praticabile senza modificare la policy stessa. -Funziona con qualsiasi tipo di politica — incorporata, personalizzata (`custom/`), convenzione di progetto (`.failproofai-project/`), o convenzione utente (`.failproofai-user/`). +Funziona con qualsiasi tipo di policy — built-in, personalizzate (`custom/`), convenzione di progetto (`.failproofai-project/`), o convenzione utente (`.failproofai-user/`). ```json { @@ -138,54 +137,60 @@ Funziona con qualsiasi tipo di politica — incorporata, personalizzata (`custom "hint": "Usa apt-get direttamente senza sudo." }, "custom/my-policy": { - "hint": "Chiedi l'approvazione dell'utente per primo." + "hint": "Chiedi prima l'approvazione all'utente." } } } ``` -Quando `block-force-push` nega, Claude vede: *"Il force-push è bloccato. Prova a creare un nuovo branch."* +Quando `block-force-push` nega, Claude vede: *"Force-pushing è bloccato. Prova a creare un nuovo branch."* -I valori non stringa e le stringhe vuote vengono silenziosamente ignorate. Se `hint` non è impostato, il comportamento è invariato (retrocompatibile). +I valori non stringa e le stringhe vuote vengono silenziosamente ignorati. Se `hint` non è impostato, il comportamento rimane invariato (compatibilità inversa). ### `customPoliciesPath` Tipo: `string` (percorso assoluto) -Percorso di un file JavaScript contenente politiche di hook personalizzate. Questo viene impostato automaticamente da `failproofai policies --install --custom ` (il percorso viene risolto in assoluto prima di essere archiviato). +Percorso di un file JavaScript contenente policy di hook personalizzate. È impostato automaticamente da `failproofai policies --install --custom ` (il percorso viene risolto in assoluto prima di essere archiviato). -Il file viene caricato di nuovo su ogni evento hook - non c'è caching. Vedi [Custom Policies](/it/custom-policies) per i dettagli di creazione. +Il file viene caricato di nuovo ad ogni evento hook - non c'è caching. Consulta [Custom Policies](/it/custom-policies) per i dettagli sulla creazione. -### Politiche basate su convenzione +### Policy basate su convenzione -Oltre a `customPoliciesPath` esplicito, failproofai scopre e carica automaticamente file di politiche dalle directory `.failproofai/policies/`: +Oltre al `customPoliciesPath` esplicito, failproofai scopre e carica automaticamente i file di policy dalle directory `.failproofai/policies/`: -| Livello | Directory | Ambito | -|-------|-----------|-------| -| Progetto | `.failproofai/policies/` | Condiviso con il team tramite controllo versione | -| Utente | `~/.failproofai/policies/custom-policies/` | Personale, si applica a tutti i progetti | +| Livello | Directory | Scope | +|---------|-----------|-------| +| Project | `.failproofai/policies/` | Condiviso con il team tramite controllo versione | +| User | `~/.failproofai/policies/` | Personale, si applica a tutti i progetti | - La directory a livello utente si è spostata di un livello nella riorganizzazione - della home-directory. I file lasciati nel vecchio percorso `~/.failproofai/policies/` - vengono spostati automaticamente in `custom-policies/` la prima volta che esegui - un comando `failproofai` dopo l'aggiornamento, e il comando ti dice quali file - sono stati spostati. + Metti le tue policy direttamente in `~/.failproofai/policies/`. La cartella + `cloud-policies/` accanto ad esse contiene policy che la tua organizzazione ha + implementato su questa macchina — la scoperta non scende nelle sottodirectory, + quindi non viene mai scansionata, e niente di quello che metti in `policies/` + può entrare in conflitto con essa. + + Se stai eseguendo l'upgrade da una versione che utilizzava + `~/.failproofai/policies/custom-policies/`, tutto in quella cartella — i tuoi + file di policy, qualsiasi `lib/` di helper che importano, e qualsiasi file di + dati che leggono — viene spostato automaticamente la prima volta che esegui un + comando `failproofai`, e il comando ti dice cosa ha spostato. -**Corrispondenza file:** Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati (ad es. `security-policies.mjs`, `workflow-policies.js`). Gli altri file nella directory vengono ignorati. +**Corrispondenza file:** Vengono caricati solo i file corrispondenti a `*policies.{js,mjs,ts}` (ad es. `security-policies.mjs`, `workflow-policies.js`). Gli altri file nella directory vengono ignorati. -**Nessuna configurazione necessaria:** Le politiche per convenzione non richiedono voci in `policies-config.json`. Basta rilasciare file nella directory e verranno ripresi sul prossimo evento hook. +**Nessuna configurazione necessaria:** Le policy per convenzione non richiedono voci in `policies-config.json`. Basta mettere i file nella directory e verranno rilevati al prossimo evento hook. -**Caricamento unione:** Entrambe le directory di convenzione di progetto e utente vengono scansionate. Tutti i file corrispondenti da entrambi i livelli vengono caricati (a differenza di `customPoliciesPath` che utilizza il primo ambito che vince). +**Caricamento unione:** Vengono scansionate sia le directory di convenzione di progetto che di utente. Tutti i file corrispondenti da entrambi i livelli vengono caricati (a differenza di `customPoliciesPath` che utilizza il primo scope vince). -Vedi [Custom Policies](/it/custom-policies) per ulteriori dettagli ed esempi. +Consulta [Custom Policies](/it/custom-policies) per ulteriori dettagli ed esempi. ### `llm` Tipo: `object` (opzionale) -Configurazione del client LLM per le politiche che effettuano chiamate AI. Non richiesto per la maggior parte delle configurazioni. +Configurazione del client LLM per le policy che effettuano chiamate AI. Non richiesto per la maggior parte dei setup. ```json { @@ -200,24 +205,24 @@ Configurazione del client LLM per le politiche che effettuano chiamate AI. Non r ## Gestione della configurazione dalla CLI -I comandi `policies --install` e `policies --uninstall` scrivono nel file delle impostazioni hook della tua CLI agent (i punti di ingresso dell'hook), mentre `policies-config.json` è il file che gestisci direttamente. I due sono separati: +I comandi `policies --install` e `policies --uninstall` scrivono nel file delle impostazioni hook della tua agent CLI (i punti di ingresso hook), mentre `policies-config.json` è il file che gestisci direttamente. I due sono separati: -- **Impostazioni CLI Agent** — dice all'agent di chiamare `failproofai --hook ` su ogni uso dello strumento: +- **Impostazioni Agent CLI** — dice all'agent di chiamare `failproofai --hook ` ad ogni utilizzo di strumento: - **Claude Code**: `~/.claude/settings.json` (utente), `/.claude/settings.json` (progetto), `/.claude/settings.local.json` (locale) - - **OpenAI Codex**: `~/.codex/hooks.json` (utente), `/.codex/hooks.json` (progetto) — Codex non ha un ambito `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (utente), `/.github/hooks/failproofai.json` (progetto) — Copilot non ha un ambito `local`. Le voci dell'hook utilizzano i campi di comando keyed da SO di Copilot `bash`/`powershell` con `timeoutSec`; il file contiene un marcatore `version: 1` di livello superiore. Il supporto di Copilot CLI è **beta** mentre verifichiamo lo schema del record `events.jsonl` (che i documenti pubblici non specificano) rispetto a più sessioni del mondo reale. **VS Code Copilot Chat agent mode (Preview)** legge le configurazioni dell'hook da `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, e `~/.claude/settings.json` (governato dall'impostazione `chat.hookFilesLocations`) utilizzando lo stesso contratto Claude-shaped `{hookSpecificOutput:{permissionDecision:"deny",…}}` — i percorsi esatti che questa integrazione `copilot` e l'integrazione `claude` (`~/.claude/settings.json`) già scrivono, quindi `failproofai policies --install --cli copilot` (o `--cli claude`) **già applica in VS Code agent mode** senza bisogno di un'integrazione `vscode` separata (confermato in diretta dai log di discovery di VS Code). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (utente), `/.cursor/hooks.json` (progetto) — Cursor non ha un ambito `local`. Le voci dell'hook utilizzano il modulo Claude-shaped `{type, command, timeout}` (nessuna divisione `bash`/`powershell`), ma archiviate sotto chiavi di evento camelCase (`preToolUse`, `beforeSubmitPrompt`, …) in un array piatto per lo schema degli hook di Cursor; il file contiene un marcatore `version: 1` di livello superiore. Il gestore canonicalizza camelCase → PascalCase tramite `CURSOR_EVENT_MAP` in modo che le politiche incorporate esistenti si attivino invariate. Il supporto di Cursor Agent è **beta** mentre verifichiamo il trascritto su disco di Cursor (non specificato nei documenti pubblici) rispetto a più installazioni del mondo reale. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (utente), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (progetto) — OpenCode non ha un ambito `local`. A differenza degli altri cinque CLI, OpenCode **non ha un sistema di hook con comando esterno**: carica plugin JS/TS in-process esplicitamente registrati tramite l'array `plugin: []` in `opencode.json` (l'auto-discovery da `.opencode/plugins/` **non** è il modo in cui i plugin si caricano su opencode v1.14.33). L'installazione rilascia un piccolo shim di plugin generato che chiama il binario failproofai in subprocess e traduce la risposta JSON di shape Claude del binario di nuovo in semantica di plugin: `throw new Error()` per la negazione di evento di strumento (annulla la chiamata dello strumento), `client.session.prompt(...)` per `instruct` E per `Stop` / `SubagentStop` negazione (invia il motivo della negazione come prossimo messaggio utente — l'unico canale di ritentatività forzata poiché `session.idle` è solo notifica e lanciare da esso è un no-op), e no-op per allow. Lo shim canonicalizza sia i nomi degli strumenti (minuscolo → PascalCase tramite `OPENCODE_TOOL_MAP`) che le chiavi degli argomenti di input dello strumento (camelCase → snake_case tramite `OPENCODE_TOOL_INPUT_MAP` per `Read` / `Write` / `Edit`, ad es. `filePath` → `file_path`, `oldString` → `old_string`) prima di inoltrarsi al binario, così i builtin di controllo del percorso come `block-read-outside-cwd`, `block-env-files`, e `block-secrets-write` si attivano invariati su chiamate di strumento OpenCode. Le sessioni vivono nel DB SQLite di opencode in `~/.local/share/opencode/opencode.db`; il visualizzatore di sessioni del dashboard le legge tramite `opencode db --format json` e `opencode export `. Il supporto di OpenCode è **beta** mentre verifichiamo il comportamento tra versioni e rispetto a più sessioni del mondo reale. Vedi la [documentazione dei plugin OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (utente), `/.pi/settings.json` (progetto) — Pi non ha un ambito `local`. Pi carica pacchetti di estensione TypeScript all'avvio; il file delle impostazioni è un array di stringhe piatto `{"packages": ["./relative/path", …]}`. failproofai scrive una singola voce di array di pacchetti che punta alla directory `pi-extension/` in bundle. L'estensione internamente si sottoscrive agli eventi `tool_call` / `user_bash` / `input` / `session_start` di Pi e chiama il shell a `failproofai --hook --cli pi`; il gestore canonicalizza underscore_lower_snake_case → PascalCase tramite `PI_EVENT_MAP` in modo che le politiche incorporate esistenti si attivino invariate. Gli argomenti di input dello strumento vengono anche canonicalizzati tramite `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit forniscono `path` piuttosto che `file_path`; mappare la chiave di livello superiore consente a `block-env-files` e `block-secrets-write` di attivarsi — `block-read-outside-cwd` già aveva un fallback `path`). Il supporto di Pi è **beta** mentre l'API di estensione di Pi e il layout del log di sessione si stabilizzano. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**solo ambito utente** — Hermes non ha configurazione di progetto/locale). Hermes è un **gateway** Slack/Telegram, quindi un'installazione intercetta le chiamate agli strumenti da ogni piattaforma (Slack/Telegram/cli/cron) **e** subagent interni. Le voci dell'hook sono una coppia `{command, timeout}` (timeout in **secondi**) sotto una mappa `hooks:` keyed da eventi snake_case di Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); il gestore canonicalizza gli eventi tramite `HERMES_EVENT_MAP` e i nomi degli strumenti tramite `HERMES_TOOL_MAP` in modo che le politiche incorporate si attivino invariate. La configurazione viene modificata tramite un roundtrip YAML `Document` che preserva i commenti in modo che le altre impostazioni dell'operatore sopravvivano, e l'installazione imposta `hooks_auto_accept: true` in modo che il gateway headless (nessun TTY) esegua gli hook senza una richiesta di consenso. L'evaluatore emette il contratto stdout di Hermes `{"decision":"block","reason"}` (Hermes ignora i codici di uscita). **Limitazioni:** Hermes non ha un evento di fine turno `Stop`, quindi i builtin `require-*-before-stop` mai si attivano per esso (inapplicabile, non rotto); `instruct` si degrada a allow-with-logged-note (nessun canale di contesto aggiuntivo); e la redazione di output-secret (`sanitize-*`) non può riscrivere l'output dello strumento sul contratto shell-hook. Hermes è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni di gateway direttamente da `~/.hermes/state.db`. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**solo ambito utente** — OpenClaw non ha configurazione di progetto/locale). Come Hermes, OpenClaw è un **gateway** multi-canale auto-hosted, quindi un'installazione intercetta le chiamate agli strumenti da ogni canale e dai suoi subagent interni. L'applicazione viene eseguita tramite gli **hook di plugin in-process** di OpenClaw (i suoi hook basati su file interni sono solo osservativi e non possono bloccare), quindi — come OpenCode/Pi — failproofai spedisce un pacchetto `openclaw-plugin/` statico che spawn async il binario failproofai e traduce il verdetto. L'installazione registra la directory del plugin fornito in `openclaw.json`'s `plugins.load.paths[]` e lo abilita sotto `plugins.entries.failproofai` (con `hooks.allowConversationAccess: true`, richiesto per gli hook di conversazione grezzi). L'evaluatore emette un verdetto piatto `{permission, reason}` e lo shim lo mappa alla forma di ritorno nativa di ogni hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), e `before_agent_finalize → {action:"revise", reason}` (**Stop** — un vero gate di fine turno, quindi i builtin `require-*-before-stop` **appliano** su OpenClaw, a differenza di Hermes). Gli eventi e i nomi degli strumenti canonicalizzano il lato binario tramite `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) in modo che le politiche incorporate si attivino invariate; lo shim fallisce open su qualsiasi errore di spawn/parse/timeout. OpenClaw è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni JSONL in `~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (utente), `/.factory/hooks.json` (progetto) — Factory non ha un ambito `local`. droid spedisce un sistema di hook con comando esterno di stile Claude, ma con due stranezze verificate in diretta rispetto a droid v0.171.0: (1) i nomi degli eventi vivono al **livello superiore** di `hooks.json` — non c'è **nessun wrapper `"hooks"`** (droid lo rifiuta); gli eventi dello strumento (`PreToolUse`/`PostToolUse`) trasportano `"matcher": "*"`, gli eventi non-strumento lo omettono. (2) Deny è guidato dal codice di uscita dell'hook **2 + stderr**, non da una decisione JSON — il ramo `factory` dell'evaluatore restituisce uscita 2 per eventi di strumento/prompt e `{decision:"block", reason}` solo sull'evento di fine turno `Stop` (l'unico canale di ritentatività forzata di droid). Gli eventi sono già PascalCase (nessuna mappa di eventi) e il payload è snake_case di Claude; solo i nomi degli strumenti vengono canonicalizzati tramite `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni JSONL su disco in `~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (utente), `/.devin/config.json` (progetto) — Devin non ha un ambito `local`. Devin è un **clone puro di Claude** verificato in diretta rispetto a devin v3000.1.27: utilizza lo schema dello schema Claude standard `"hooks"` (i write preservano la fusione in modo che le altre chiavi del file di configurazione — `org_id`, `theme_mode`, … — sopravvivano), nomi di eventi già PascalCase (nessuna mappa di eventi, nessun ramo di gestore), e un payload stdin snake_case di Claude (nessuna normalizzazione). Il ramo `devin` dell'evaluatore nega con JSON `{"decision":"block","reason"}` su stdout all'uscita 0 per **ogni** evento (verificato — il blocco ha ignorato `--permission-mode dangerous`); sull'evento di fine turno `Stop` il motivo trasporta il wording di ritentatività forzata OBBLIGATORIO in modo che i builtin `require-*-before-stop` applino. Solo i nomi degli strumenti vengono canonicalizzati tramite `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` è già canonico). Devin è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni SQLite in `~/.local/share/devin/cli/sessions.db` (ogni riga `sessions` trasporta una vera `working_directory`, quindi le sessioni si raggruppano per progetto cwd come Claude). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (utente), `/.agents/hooks.json` (progetto) — Antigravity non ha un ambito `local`. A differenza di Factory/Devin, Antigravity ha il **suo** contratto (non un clone di Claude), verificato in diretta rispetto a agy v1.1.2. `hooks.json` utilizza uno schema **named-hook**: la chiave di livello superiore è un nome di hook (*"failproofai"*) il cui valore è una mappa evento→gestori — gli eventi dello strumento (`PreToolUse`/`PostToolUse`) avvolgono i gestori in `{matcher:"*", hooks:[…]}`, mentre `PreInvocation`/`Stop` sono array di gestori **piatti** (altri hook nominati vengono preservati). Il payload stdin è **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai lo normalizza a snake_case prima che le politiche si eseguano, e mappa gli argomenti PascalCase di `run_command` (`CommandLine`/`Cwd`) tramite `ANTIGRAVITY_TOOL_INPUT_MAP`. Il ramo `antigravity` dell'evaluatore utilizza le forme di risposta **proprie** di Antigravity: `{decision:"deny", reason}` blocca uno strumento/prompt (uscita 0), `{decision:"continue", reason}` sull'evento di fine turno `Stop` rientra nel loop (quindi i builtin `require-*-before-stop` applino), e `{injectSteps:[{ephemeralMessage}]}` inietta un'istruzione su `PreInvocation` (→ `UserPromptSubmit`). I nomi degli strumenti canonicalizzano tramite `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity è **anche** una fonte di audit **offline** — il dashboard legge i suoi trascritti plain-JSONL in `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (indice di conversazione in `conversation_summaries.db`). - - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (utente), `/.agents/plugins/failproofai/hooks/hooks.json` (progetto) — Goose non ha un ambito `local`. L'applicazione utilizza il sistema **hooks** di Goose, la specifica **Open Plugins** tra agent: l'installatore basta rilascia la directory del plugin `failproofai` e Goose lo auto-scopre all'avvio (auto-registrandolo in `~/.config/goose/config.yaml`). `hooks.json` utilizza uno schema Open Plugins **con** un wrapper `"hooks"` di livello superiore, e il matcher è **omesso** su ogni evento — un `"*"` nudo è un regex non valido che non corrisponde a nulla (verificato in diretta rispetto a goose v1.43.0). I nomi degli eventi sono già PascalCase (nessuna mappa di eventi); il payload stdin utilizza `event`/`working_dir`, che il gestore normalizza in `hook_event_name`/`cwd`. Il ramo `goose` dell'evaluatore nega con JSON `{"decision":"block","reason"}` su stdout all'uscita 0, onorato sull'evento **`PreToolUse`** solo (spedito in goose ≥ v1.37.0) — che si attiva per lo strumento shell **e all'interno dei subagent delegati**, quindi è il singolo punto di negazione sufficiente; qualsiasi altro errore di hook fallisce **open**. Goose non ha un evento **`Stop`**, quindi i builtin `require-*-before-stop` non si applicano (come con Hermes). I nomi degli strumenti canonicalizzano tramite `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) e le chiavi del percorso tramite `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni SQLite in `~/.local/share/goose/sessions/sessions.db` (ogni riga `sessions` trasporta una vera `working_dir`, quindi le sessioni si raggruppano per progetto cwd come Devin; le esecuzioni `--no-session` scratch vengono filtrate). -- **`policies-config.json`** — dice a failproofai quali politiche valutare e con quali parametri (condiviso tra tutti i CLI agent) - -Passa `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` per indirizzare un agent specifico (separati da spazio o ripetuti per qualsiasi sottoinsieme): + - **OpenAI Codex**: `~/.codex/hooks.json` (utente), `/.codex/hooks.json` (progetto) — Codex non ha uno scope locale + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (utente), `/.github/hooks/failproofai.json` (progetto) — Copilot non ha uno scope locale. Le voci di hook utilizzano i campi di comando `bash`/`powershell` della chiave del sistema operativo di Copilot con `timeoutSec`; il file contiene un marcatore `version: 1` di livello superiore. Il supporto di Copilot CLI è **beta** mentre verifichiamo lo schema del record `events.jsonl` (che i documenti pubblici non specificano) rispetto a più sessioni del mondo reale. **VS Code Copilot Chat agent mode (Preview)** legge le configurazioni hook da `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, e `~/.claude/settings.json` (governate dall'impostazione `chat.hookFilesLocations`) utilizzando lo stesso contratto a forma di Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — i percorsi esatti che questa integrazione `copilot` e l'integrazione `claude` (`~/.claude/settings.json`) scrivono già, quindi `failproofai policies --install --cli copilot` (o `--cli claude`) **già applica in VS Code agent mode** senza necessità di integrazione separata `vscode` (confermato dal vivo dai log di scoperta di VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (utente), `/.cursor/hooks.json` (progetto) — Cursor non ha uno scope locale. Le voci di hook utilizzano la forma a forma di Claude `{type, command, timeout}` (nessuna divisione `bash`/`powershell`), ma memorizzate sotto chiavi di evento camelCase (`preToolUse`, `beforeSubmitPrompt`, …) in un array piatto per lo schema hook di Cursor; il file contiene un marcatore `version: 1` di livello superiore. Il gestore canonicalizza camelCase → PascalCase via `CURSOR_EVENT_MAP` quindi le policy built-in esistenti si attivano inalterate. Il supporto di Cursor Agent è **beta** mentre verifichiamo il transcript di Cursor su disco (non specificato nei documenti pubblici) rispetto a più installazioni del mondo reale. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (utente), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (progetto) — OpenCode non ha uno scope locale. A differenza degli altri cinque CLI, OpenCode **non ha un sistema hook di comando esterno**: carica plugin JS/TS in-process registrati esplicitamente tramite l'array `plugin: []` in `opencode.json` (l'auto-scoperta da `.opencode/plugins/` **non** è come i plugin si caricano su opencode v1.14.33). L'installazione rilascia un piccolo shim plugin generato che chiama il binario failproofai in subprocess e traduce la risposta JSON a forma di Claude del binario nella semantica del plugin: `throw new Error()` per il deny di evento strumento (annulla la chiamata dello strumento), `client.session.prompt(...)` per instruct E per `Stop` / `SubagentStop` deny (invia il motivo di deny come il prossimo messaggio utente — l'unico canale di forzatura ritentativo poiché `session.idle` è solo notifica e lanciare da esso è un no-op), e no-op per allow. Lo shim canonicalizza sia i nomi degli strumenti (minuscolo → PascalCase via `OPENCODE_TOOL_MAP`) che le chiavi degli argomenti di input dello strumento (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` per `Read` / `Write` / `Edit`, ad es. `filePath` → `file_path`, `oldString` → `old_string`) prima di inoltrare al binario, quindi i built-in di controllo percorso come `block-read-outside-cwd`, `block-env-files`, e `block-secrets-write` si attivano inalterate sulle chiamate dello strumento OpenCode. Le sessioni vivono nel DB SQLite di opencode a `~/.local/share/opencode/opencode.db`; il visualizzatore della sessione dashboard le legge tramite `opencode db --format json` e `opencode export `. Il supporto di OpenCode è **beta** mentre verifichiamo il comportamento tra versioni e contro più sessioni del mondo reale. Consulta la [documentazione plugin di OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (utente), `/.pi/settings.json` (progetto) — Pi non ha uno scope locale. Pi carica pacchetti di estensione TypeScript all'avvio; il file di impostazioni è un array di stringhe piatto `{"packages": ["./relative/path", …]}`. failproofai scrive una singola voce dell'array di pacchetti che punta alla sua directory `pi-extension/` bundle. L'estensione internamente si iscrive agli eventi `tool_call` / `user_bash` / `input` / `session_start` di Pi e chiama il shell `failproofai --hook --cli pi`; il gestore canonicalizza underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` quindi le policy built-in esistenti si attivano inalterate. Gli argomenti di input dello strumento vengono anche canonicalizzati tramite `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit forniscono `path` piuttosto che `file_path`; il mapping della chiave di livello superiore consente l'attivazione di `block-env-files` e `block-secrets-write` — `block-read-outside-cwd` aveva già un fallback `path`). Il supporto di Pi è **beta** mentre l'API di estensione di Pi e il layout del log della sessione si stabilizzano. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**solo scope utente** — Hermes non ha configurazione progetto/locale). Hermes è un **gateway** Slack/Telegram, quindi un'installazione intercetta le chiamate dello strumento da ogni piattaforma (Slack/Telegram/cli/cron) **e** subagenti interni. Le voci di hook sono una coppia `{command, timeout}` (timeout in **secondi**) sotto una mappa `hooks:` con chiave dello snake_case di Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); il gestore canonicalizza gli eventi via `HERMES_EVENT_MAP` e i nomi degli strumenti via `HERMES_TOOL_MAP` quindi le policy built-in si attivano inalterate. La configurazione viene modificata attraverso un round-trip `Document` YAML che preserva i commenti in modo che le altre impostazioni dell'operatore sopravvivano, e l'installazione imposta `hooks_auto_accept: true` in modo che il gateway headless (no TTY) esegua gli hook senza un prompt di consenso. L'evaluator emette il contratto stdout `{"decision":"block","reason"}` di Hermes (Hermes ignora i codici di uscita). **Limitazioni:** Hermes non ha un evento di fine turno `Stop`, quindi i built-in `require-*-before-stop` non si attivano mai per esso (inapplicabile, non rotto); `instruct` si degrada a allow-with-logged-note (nessun canale di contesto aggiuntivo); e la redazione di secret di output (`sanitize-*`) non può riscrivere l'output dello strumento sul contratto hook della shell. Hermes è **anche** una fonte **audit** offline — il dashboard legge le sessioni del gateway direttamente da `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**solo scope utente** — OpenClaw non ha configurazione progetto/locale). Come Hermes, OpenClaw è un **gateway** multi-canale self-hosted, quindi un'installazione intercetta le chiamate dello strumento da ogni canale e dai suoi subagenti interni. L'enforcement viene eseguito attraverso gli **hook di plugin in-process** di OpenClaw (i suoi hook interni basati su file sono solo osservazione e non possono bloccare), quindi — come OpenCode/Pi — failproofai fornisce un pacchetto statico `openclaw-plugin/` che spawna async il binario failproofai e traduce il verdetto. L'installer registra la directory del plugin fornita in `openclaw.json` `plugins.load.paths[]` e lo abilita sotto `plugins.entries.failproofai` (con `hooks.allowConversationAccess: true`, richiesto per i ganci di conversazione grezzi). L'evaluator emette un verdetto `{permission, reason}` piatto e lo shim lo mappa alla forma nativa di ogni hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), e `before_agent_finalize → {action:"revise", reason}` (**Stop** — un vero gate di fine turno, quindi i built-in `require-*-before-stop` **applica** su OpenClaw, a differenza di Hermes). Gli eventi e i nomi degli strumenti canonicalizzano dal lato binario via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) quindi le policy built-in si attivano inalterate; lo shim fallisce aperto su qualsiasi errore di spawn/parse/timeout. OpenClaw è **anche** una fonte **audit** offline — il dashboard legge le sue sessioni JSONL a `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (utente), `/.factory/hooks.json` (progetto) — Factory non ha uno scope locale. droid fornisce un sistema hook di comando esterno a forma di Claude, ma con due stravaganze verificate dal vivo contro droid v0.171.0: (1) i nomi degli eventi vivono al **livello superiore** di `hooks.json` — **non c'è wrapper `"hooks"`** (droid lo rifiuta); gli eventi degli strumenti (`PreToolUse`/`PostToolUse`) portano `"matcher": "*"`, gli eventi non strumento lo omettono. (2) Deny è guidato dall'hook **exit code 2 + stderr**, non dalla decisione JSON — il ramo `factory` dell'evaluator restituisce exit 2 per gli eventi strumento/prompt e `{decision:"block", reason}` solo all'evento di fine turno `Stop` (l'unico canale di forzatura ritentativo di droid). Gli eventi sono già PascalCase (nessuna mappa di evento) e il payload è Claude snake_case; solo i nomi degli strumenti vengono canonicalizzati via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory è **anche** una fonte **audit** offline — il dashboard legge le sue sessioni JSONL on-disk a `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (utente), `/.devin/config.json` (progetto) — Devin non ha uno scope locale. Devin è un **puro Claude-clone** verificato dal vivo contro devin v3000.1.27: utilizza lo schema `"hooks"`-wrapper Claude standard (le scritture preservano il merge in modo che le altre chiavi del file di configurazione — `org_id`, `theme_mode`, … — sopravvivono), nomi di evento già PascalCase (nessuna mappa di evento, nessun ramo del gestore), e un payload stdin Claude snake_case (nessuna normalizzazione). Il ramo `devin` dell'evaluator nega con JSON `{"decision":"block","reason"}` su stdout all'exit 0 per **ogni** evento (verificato — il blocco ha ignorato `--permission-mode dangerous`); all'evento di fine turno `Stop` il motivo porta la formulazione di forzatura ritentativa OBBLIGATORIA quindi i built-in `require-*-before-stop` applica. Solo i nomi degli strumenti vengono canonicalizzati via `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` è già canonico). Devin è **anche** una fonte **audit** offline — il dashboard legge le sue sessioni SQLite a `~/.local/share/devin/cli/sessions.db` (ogni riga `sessions` porta una vera `working_directory`, quindi le sessioni si raggruppano per progetto cwd come Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (utente), `/.agents/hooks.json` (progetto) — Antigravity non ha uno scope locale. A differenza di Factory/Devin, Antigravity ha il suo **proprio** contratto (non un Claude-clone), verificato dal vivo contro agy v1.1.2. `hooks.json` utilizza uno schema **named-hook**: la chiave di livello superiore è un nome di hook (*`"failproofai"`) il cui valore è una mappa evento→handler — gli eventi degli strumenti (`PreToolUse`/`PostToolUse`) avvolgono handler in `{matcher:"*", hooks:[…]}`, mentre `PreInvocation`/`Stop` sono array di handler **piatti** (altri named hook vengono preservati). Il payload stdin è **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai lo normalizza a snake_case prima dell'esecuzione delle policy, e mappa gli argomenti PascalCase di `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. Il ramo `antigravity` dell'evaluator utilizza le proprie forme di risposta di Antigravity: `{decision:"deny", reason}` blocca uno strumento/prompt (exit 0), `{decision:"continue", reason}` all'evento di fine turno `Stop` re-entra nel loop (quindi i built-in `require-*-before-stop` applica), e `{injectSteps:[{ephemeralMessage}]}` inietta un'istruzione su `PreInvocation` (→ `UserPromptSubmit`). I nomi degli strumenti canonicalizzano via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity è **anche** una fonte **audit** offline — il dashboard legge i suoi plain-JSONL transcript a `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (conversation index in `conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (utente), `/.agents/plugins/failproofai/hooks/hooks.json` (progetto) — Goose non ha uno scope locale. L'enforcement utilizza il sistema **hooks** di Goose, la spec **Open Plugins** cross-agent: l'installer basta rilascia la directory del plugin `failproofai` e Goose la auto-scopre all'avvio (auto-registrandola in `~/.config/goose/config.yaml`). Il `hooks.json` utilizza uno schema Open Plugins **con** un wrapper `"hooks"` di livello superiore, e il matcher è **omesso** su ogni evento — un bare `"*"` è una regex non valida che non corrisponde a nulla (verificato dal vivo contro goose v1.43.0). I nomi degli eventi sono già PascalCase (nessuna mappa di evento); il payload stdin utilizza `event`/`working_dir`, che il gestore normalizza a `hook_event_name`/`cwd`. Il ramo `goose` dell'evaluator nega con JSON `{"decision":"block","reason"}` su stdout all'exit 0, onorato solo all'evento **`PreToolUse`** (fornito in goose ≥ v1.37.0) — che si attiva per lo strumento della shell **e dentro i subagenti delegati**, quindi è il singolo punto di deny sufficiente; qualsiasi altro errore di hook fallisce **open**. Goose **non ha evento `Stop`**, quindi i built-in `require-*-before-stop` non si applicano (come con Hermes). I nomi degli strumenti canonicalizzano via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) e le chiavi di percorso via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose è **anche** una fonte **audit** offline — il dashboard legge le sue sessioni SQLite a `~/.local/share/goose/sessions/sessions.db` (ogni riga `sessions` porta una vera `working_dir`, quindi le sessioni si raggruppano per progetto cwd come Devin; le esecuzioni scratch `--no-session` vengono filtrate). +- **`policies-config.json`** — dice a failproofai quali policy valutare e con quali parametri (condiviso tra tutti i CLI agent) + +Passa `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` per targetare un agent specifico (spazio-separati o ripetuti per qualsiasi subset): ```bash failproofai policies --install --cli codex --scope project @@ -234,20 +239,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Quando `--cli` viene omesso, `failproofai` rileva quali CLI agent sono installati (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +Quando `--cli` è omesso, `failproofai` rileva quali CLI agent sono installati (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): - **Un CLI rilevato** — seleziona automaticamente quel CLI senza chiedere. -- **Più CLI rilevati** in un terminale interattivo — mostra un prompt di selezione singola con tasti freccia raggruppato in una sezione `Detected (N)` (con una riga aggregata `Install for all N detected` + ogni CLI rilevato individualmente) e una sezione `Not installed (M) · install hooks ahead of time` che elenca ogni CLI non rilevato supportato come opzione di installazione anticipata (↑↓ per spostare, Invio per selezionare, ^C per uscire). Il flusso di disinstallazione mostra solo la sezione Rilevato. -- **Più CLI rilevati** in un'esecuzione non interattiva (CI, nessun TTY) — installa per tutti i CLI rilevati senza chiedere. -- **Nessuno rilevato** — ricade su `claude`, con un avviso che nessun binario agent è stato trovato in PATH; il comando dell'hook viene comunque scritto in modo che si attivi non appena installi uno. +- **Più CLI rilevati** in un terminale interattivo — mostra un prompt di selezione singola con tasto freccia raggruppato in una sezione `Rilevati (N)` (con una riga aggregata `Installa per tutti i N rilevati` + ogni CLI rilevato singolarmente) e una sezione `Non installati (M) · installa gli hook in anticipo` che elenca ogni CLI non rilevato supportato come opzione di pre-installazione (↑↓ per muovere, Invio per selezionare, ^C per uscire). Il flusso di disinstallazione mostra solo la sezione Rilevati. +- **Più CLI rilevati** in un'esecuzione non interattiva (CI, no TTY) — installa per tutti i CLI rilevati senza chiedere. +- **Nessuno rilevato** — ricade a `claude`, con un avvertimento che nessun binario agent è stato trovato in PATH; il comando hook viene comunque scritto in modo che si attivi non appena ne installi uno. + +Puoi modificare `policies-config.json` direttamente in qualsiasi momento; i cambiamenti hanno effetto immediatamente al prossimo evento hook senza necessità di riavvio. + +## Gli upgrade mantengono la tua configurazione + +Una nuova versione di failproofai può organizzare `~/.failproofai/` diversamente. Quando lo fa, il primo comando dopo l'upgrade migra la directory, e **la tua configurazione viene portata avanti, non reimpostata**: + +| Conservato | Ricostruito | +|---|---| +| La tua selezione di policy e parametri (`policies-config.json`) | La cache di audit | +| Le tue impostazioni, incluso `daemon.configured` e percorsi di cattura extra (`config.json`) | Le implementazioni di policy gestite dal cloud — ri-recuperate e verificate dal digest al prossimo sondaggio | +| Il tuo iscritto cloud (`credentials.json`) | Lo stato scratch del daemon | +| I tuoi file di policy in `policies/`, e gli helper che importano | | +| Il log delle decisioni che il dashboard legge, e gli eventi non ancora consegnati | | + +Le chiavi scritte da un failproofai *più nuovo* vengono preserve anche, piuttosto che essere eliminate da un lettore più vecchio — quindi spostarsi tra versioni non scarta silenziosamente le impostazioni neanche in una direzione. + +**Non** hai bisogno di ri-eseguire setup in seguito: una macchina migrata applica esattamente come faceva prima, che è quello che rende un upgrade sicuro su macchine con nessuno seduto davanti. Ogni migrazione viene registrata in `~/.failproofai/migrations/applied.json`, e i file insostituibili vengono copiati a `~/.failproofai/migrations/backup-layout/` prima che qualsiasi cosa venga eseguita. -Puoi modificare `policies-config.json` direttamente in qualsiasi momento; le modifiche hanno effetto immediato sul prossimo evento hook senza bisogno di riavvio. +Consulta [`failproofai update`](/it/cli/update) per l'upgrade in un'unica riga, e [`failproofai migrate`](/it/cli/migrate) — incluso `--dry-run` — per i dettagli. --- -## Esempio: configurazione a livello di progetto con impostazioni predefinite del team +## Esempio: configurazione a livello di progetto con standard del team -Committa `.failproofai/policies-config.json` nel tuo repo: +Committi `.failproofai/policies-config.json` al tuo repo: ```json { @@ -266,4 +289,4 @@ Committa `.failproofai/policies-config.json` nel tuo repo: } ``` -Ogni sviluppatore può quindi creare `.failproofai/policies-config.local.json` (gitignored) per override personali senza influenzare i compagni di squadra. \ No newline at end of file +Ogni sviluppatore può quindi creare `.failproofai/policies-config.local.json` (gitignored) per override personali senza influenzare i compagni di team. \ No newline at end of file diff --git a/docs/it/custom-policies.mdx b/docs/it/custom-policies.mdx index 8e3001e5..8fbc17d9 100644 --- a/docs/it/custom-policies.mdx +++ b/docs/it/custom-policies.mdx @@ -1,11 +1,11 @@ --- --- -title: Politiche Personalizzate -description: "Scrivi le tue regole in JavaScript - applica convenzioni, previeni derive, rileva errori, integrati con sistemi esterni" +title: Politiche personalizzate +description: "Scrivi le tue politiche in JavaScript - applica convenzioni, previeni derive, rileva errori, integra con sistemi esterni" icon: code --- -Le politiche personalizzate ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applica convenzioni di progetto, previeni derive, blocca operazioni distruttive, rileva agenti bloccati, o integrati con Slack, flussi di approvazione e altro ancora. Utilizzano lo stesso sistema di hook event e le decisioni `allow`, `deny`, `instruct` delle politiche incorporate. +Le politiche personalizzate ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applicare convenzioni di progetto, prevenire derive, bloccare operazioni distruttive, rilevare agenti bloccati, o integrarsi con Slack, flussi di approvazione e altro ancora. Utilizzano lo stesso sistema di hook event e le decisioni `allow`, `deny`, `instruct` delle politiche integrate. --- @@ -30,7 +30,7 @@ customPolicies.add({ }); ``` -Installala: +Installalo: ```bash failproofai policies --install --custom ./my-policies.js @@ -38,14 +38,14 @@ failproofai policies --install --custom ./my-policies.js --- -## Due modi per caricare le politiche personalizzate +## Due modi per caricare politiche personalizzate ### Opzione 1: Basata su convenzione (consigliata) -Inserisci i file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e verranno caricati automaticamente — nessun flag o modifica di configurazione necessaria. Funziona come i git hook: inserisci un file e basta. +Inserisci file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono caricati automaticamente — nessun flag o cambio di configurazione necessario. Funziona come i git hook: inserisci un file e basta. ``` -# Livello di progetto — salvato in git, condiviso con il team +# Livello di progetto — committato su git, condiviso con il team .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -54,14 +54,14 @@ Inserisci i file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e verranno ``` **Come funziona:** -- Entrambe le directory di progetto e utente vengono scansionate (unione — non first-scope-wins) -- I file vengono caricati alfabeticamente all'interno di ogni directory. Prefissi con `01-`, `02-` per controllare l'ordine -- Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati; gli altri file vengono ignorati -- Ogni file viene caricato indipendentemente (fail-open per file) -- Funziona insieme alle politiche esplicite `--custom` e incorporate +- Entrambe le directory di progetto e utente vengono scansionate (unione — non primo-ambito-vince) +- I file vengono caricati alfabeticamente all'interno di ciascuna directory. Usa il prefisso `01-`, `02-` per controllare l'ordine +- Solo i file corrispondenti a `*policies.{js,mjs,ts}` vengono caricati; gli altri file vengono ignorati +- Ogni file viene caricato in modo indipendente (fail-open per file) +- Funziona insieme a politiche esplicite `--custom` e integrate -Le politiche di convenzione sono il modo più semplice per costruire uno standard di qualità per la tua organizzazione. Salva `.failproofai/policies/` in git e ogni membro del team ottiene automaticamente le stesse regole — nessuna configurazione per sviluppatore necessaria. Man mano che il tuo team scopre nuove modalità di errore, aggiungi una politica e fai il push. Nel tempo questi diventano uno standard di qualità dinamico che continua a migliorare con ogni contributo. +Le politiche di convenzione sono il modo più semplice per costruire uno standard di qualità per la tua organizzazione. Committi `.failproofai/policies/` su git e ogni membro del team ottiene automaticamente le stesse regole — nessuna configurazione per sviluppatore necessaria. Man mano che il tuo team scopre nuove modalità di errore, aggiungi una politica e fai push. Nel tempo queste diventano uno standard di qualità vivo che continua a migliorare con ogni contributo. ### Opzione 2: Percorso file esplicito @@ -70,27 +70,27 @@ Le politiche di convenzione sono il modo più semplice per costruire uno standar # Installa con un file di politiche personalizzate failproofai policies --install --custom ./my-policies.js -# Sostituisci i percorsi della politica personalizzata +# Sostituisci i percorsi di politiche personalizzate failproofai policies --install --custom ./new-policies.js # Configura più file espliciti (caricati nell'ordine del flag) failproofai policies --install --custom ./security.js --custom ./workflow.js -# Rimuovi tutti i percorsi della politica personalizzata esplicita dalla configurazione +# Rimuovi tutti i percorsi di politiche personalizzate esplicite dalla configurazione failproofai policies --uninstall --custom ``` -I percorsi assoluti risolti vengono archiviati in `policies-config.json` come `customPoliciesPaths`. Ripeti `--custom` per configurare più file. Le configurazioni esistenti che utilizzano il campo legacy `customPoliciesPath` continuano a funzionare. I file vengono caricati di nuovo a ogni evento hook — non c'è caching tra gli eventi. +I percorsi assoluti risolti vengono memorizzati in `policies-config.json` come `customPoliciesPaths`. Ripeti `--custom` per configurare più file. Le configurazioni esistenti che utilizzano il campo legacy `customPoliciesPath` continuano a funzionare. I file vengono caricati di nuovo ad ogni evento hook - non c'è caching tra gli eventi. -Ogni politica registrata appare con il proprio interruttore nel dashboard. Lo spegnimento di una politica registra il suo ID qualificato con la fonte in `disabledCustomPolicies`; il file e le altre sue politiche continuano a caricarsi, mentre la politica disabilitata viene esclusa prima della corrispondenza degli eventi. I nomi di politica duplicati tra i file hanno interruttori indipendenti. +Ogni politica registrata viene visualizzata con il proprio toggle nel dashboard. Disabilitando una politica viene registrato il suo ID qualificato dalla fonte in `disabledCustomPolicies`; il file e le sue altre politiche continuano a caricarsi, mentre la politica disabilitata viene esclusa prima della corrispondenza degli eventi. I nomi di politica duplicati tra i file hanno toggle indipendenti. -### Usarli insieme +### Usare entrambi insieme -Le politiche di convenzione e i file espliciti `--custom` possono coesistere. Ordine di caricamento: +Le politiche di convenzione e i file espliciti `--custom` possono coesistere. Ordine di carico: 1. File `customPoliciesPaths` espliciti (nell'ordine configurato) -2. File di convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetici) -3. File di convenzione utente (`~/.failproofai/policies/`, alfabetici) +2. File di convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetico) +3. File di convenzione utente (`~/.failproofai/policies/`, alfabetico) --- @@ -104,44 +104,44 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registra una politica. Chiama questo quanto necessario per più politiche nello stesso file. +Registra una politica. Chiamala tutte le volte necessarie per più politiche nello stesso file. ```ts customPolicies.add({ - name: string; // richiesto - identificatore univoco + name: string; // obbligatorio - identificatore unico description?: string; // mostrato nell'output di `failproofai policies` - match?: { events?: HookEventType[] }; // filtra per tipo di evento; ometti per abbinare tutti + match?: { events?: HookEventType[] }; // filtra per tipo di evento; ometti per corrispondere a tutti fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Aiutanti per le decisioni +### Aiutanti di decisione | Funzione | Effetto | Usa quando | |----------|--------|----------| | `allow()` | Consenti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario | -| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe eseguire questa azione | +| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe intraprendere questa azione | | `instruct(message)` | Aggiungi contesto senza bloccare | Dai all'agente contesto extra per rimanere in traccia | -`deny(message)` - il messaggio appare a Claude con prefisso `"Blocked by failproofai:"`. Un singolo `deny` interrompe tutta la valutazione successiva. +`deny(message)` - il messaggio appare a Claude con il prefisso `"Blocked by failproofai:"`. Un singolo `deny` short-circuit tutta la valutazione successiva. `instruct(message)` - il messaggio viene aggiunto al contesto di Claude per la chiamata dello strumento corrente. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme. -Puoi aggiungere indicazioni aggiuntive a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessuna modifica del codice necessaria. Questo funziona anche per le politiche personalizzate (`custom/`), di convenzione di progetto (`.failproofai-project/`), e di convenzione utente (`.failproofai-user/`). Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per i dettagli. +Puoi aggiungere una guida extra a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessun cambio di codice necessario. Questo funziona per le politiche personalizzate (`custom/`), di convenzione di progetto (`.failproofai-project/`), e di convenzione utente (`.failproofai-user/`) anche. Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per i dettagli. ### Messaggi allow informativi -`allow(message)` consente l'operazione **e** invia un messaggio informativo a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore hook — lo stesso meccanismo utilizzato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avvertimento. +`allow(message)` consente l'operazione **e** invia un messaggio informativo indietro a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore hook — lo stesso meccanismo usato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avvertimento. | Funzione | Effetto | Usa quando | |----------|--------|----------| | `allow(message)` | Consenti e invia contesto a Claude | Conferma che un controllo è passato, o spiega perché un controllo è stato saltato | -Casi di utilizzo: +Casi d'uso: - **Conferme di stato:** `allow("All CI checks passed.")` — dice a Claude che tutto è verde -- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — dice a Claude perché un controllo è stato saltato in modo da avere il contesto completo +- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — dice a Claude perché un controllo è stato saltato così ha il contesto completo - **Più messaggi si accumulano:** se diverse politiche restituiscono ciascuna `allow(message)`, tutti i messaggi vengono uniti con newline e consegnati insieme ```js @@ -161,27 +161,27 @@ customPolicies.add({ }); ``` -### Campi `PolicyContext` +### Campi di `PolicyContext` | Campo | Tipo | Descrizione | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | Lo strumento chiamato (ad es. `"Bash"`, `"Write"`, `"Read"`) | +| `toolName` | `string \| undefined` | Lo strumento in fase di chiamata (ad es. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | I parametri di input dello strumento | | `payload` | `Record` | Payload di evento grezzo completo da Claude Code | -| `session` | `SessionMetadata \| undefined` | Contesto di sessione (vedi sotto) | +| `session` | `SessionMetadata \| undefined` | Contesto della sessione (vedi sotto) | -### Campi `SessionMetadata` +### Campi di `SessionMetadata` | Campo | Tipo | Descrizione | |-------|------|-------------| | `sessionId` | `string` | Identificatore di sessione Claude Code | | `cwd` | `string` | Directory di lavoro della sessione Claude Code | -| `transcriptPath` | `string` | Percorso del file trascrizione JSONL della sessione | +| `transcriptPath` | `string` | Percorso al file transcript JSONL della sessione | ### Tipi di evento -| Evento | Quando si attiva | Contenuti `toolInput` | +| Evento | Quando si attiva | Contenuto di `toolInput` | |-------|--------------|----------------------| | `PreToolUse` | Prima che Claude esegua uno strumento | L'input dello strumento (ad es. `{ command: "..." }` per Bash) | | `PostToolUse` | Dopo il completamento di uno strumento | L'input dello strumento + `tool_result` (l'output) | @@ -194,20 +194,20 @@ customPolicies.add({ Le politiche vengono valutate in questo ordine: -1. Politiche incorporate (nell'ordine di definizione) -2. Politiche personalizzate esplicite da `customPoliciesPath` (nell'ordine di `.add()`) -3. Politiche di convenzione da `.failproofai/policies/` di progetto (file alfabetici, ordine di `.add()` all'interno) -4. Politiche di convenzione da `~/.failproofai/policies/` utente (file alfabetici, ordine di `.add()` all'interno) +1. Politiche integrate (in ordine di definizione) +2. Politiche personalizzate esplicite da `customPoliciesPath` (in ordine `.add()`) +3. Politiche di convenzione da `.failproofai/policies/` di progetto (file alfabetico, ordine `.add()` all'interno) +4. Politiche di convenzione da `~/.failproofai/policies/` utente (file alfabetico, ordine `.add()` all'interno) -Il primo `deny` interrompe tutte le politiche successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme. +Il primo `deny` short-circuit tutte le politiche successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme. --- ## Importazioni transitive -I file di politica personalizzata possono importare moduli locali utilizzando percorsi relativi: +I file di politiche personalizzate possono importare moduli locali usando percorsi relativi: ```js // my-policies.js @@ -224,11 +224,11 @@ customPolicies.add({ }); ``` -Tutti gli import relativi raggiungibili dal file di entry vengono risolti. Questo è implementato riscrivendo gli import `from "failproofai"` al percorso dist effettivo e creando file `.mjs` temporanei per garantire la compatibilità ESM. +Tutti gli import relativi raggiungibili dal file di entry vengono risolti. Questo viene implementato riscrivendo gli import `from "failproofai"` al percorso dist effettivo e creando file `.mjs` temporanei per garantire la compatibilità ESM. --- -## Filtraggio del tipo di evento +## Filtro del tipo di evento Usa `match.events` per limitare quando una politica si attiva: @@ -238,32 +238,32 @@ customPolicies.add({ match: { events: ["Stop"] }, fn: async (ctx) => { // Si attiva solo quando la sessione termina - // ctx.session.transcriptPath contiene il log di sessione completo + // ctx.session.transcriptPath contiene il log della sessione completa return allow(); }, }); ``` -Ometti completamente `match` per attivare su ogni tipo di evento. +Ometti `match` interamente per attivarsi su ogni tipo di evento. --- ## Gestione degli errori e modalità di errore -Le politiche personalizzate sono **fail-open**: gli errori non blocchiano mai le politiche incorporate o causano il crash del gestore hook. +Le politiche personalizzate sono **fail-open**: gli errori non bloccano mai le politiche integrate o causano l'arresto anomalo del gestore hook. | Errore | Comportamento | |---------|----------| -| `customPoliciesPath` non impostato | Nessuna politica personalizzata esplicita viene eseguita; le politiche di convenzione e incorporate continuano normalmente | -| File non trovato | Avviso registrato in `~/.failproofai/hook.log`; le incorporate continuano | -| Errore di sintassi/importazione (esplicito) | Errore registrato in `~/.failproofai/hook.log`; le politiche personalizzate esplicite saltate | -| Errore di sintassi/importazione (convenzione) | Errore registrato; quel file saltato, altri file di convenzione ancora caricati | -| `fn` butta a runtime | Errore registrato; quel hook trattato come `allow`; altri hook continuano | +| `customPoliciesPath` non impostato | Nessuna politica personalizzata esplicita viene eseguita; le politiche di convenzione e integrate continuano normalmente | +| File non trovato | Avviso registrato in `~/.failproofai/hook.log`; le politiche integrate continuano | +| Errore di sintassi/import (esplicito) | Errore registrato in `~/.failproofai/hook.log`; politiche personalizzate esplicite saltate | +| Errore di sintassi/import (convenzione) | Errore registrato; quel file saltato, altri file di convenzione caricati ancora | +| `fn` genera un'eccezione a runtime | Errore registrato; quel hook trattato come `allow`; altri hook continuano | | `fn` impiega più di 10s | Timeout registrato; trattato come `allow` | | Directory di convenzione mancante | Nessuna politica di convenzione viene eseguita; nessun errore | -Per debuggare gli errori di politica personalizzata, guarda il file di log: +Per eseguire il debug degli errori di politica personalizzata, guarda il file di log: ```bash tail -f ~/.failproofai/hook.log @@ -278,7 +278,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Impedisci all'agente di scrivere nella directory secrets/ +// Previeni all'agente di scrivere nella directory secrets/ customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -291,7 +291,7 @@ customPolicies.add({ }, }); -// Mantieni l'agente in traccia: verifica i test prima di eseguire il commit +// Mantieni l'agente in traccia: verifica i test prima di committare customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -306,7 +306,7 @@ customPolicies.add({ }, }); -// Impedisci i cambiamenti di dipendenza non pianificati durante il congelamento +// Previeni cambiamenti di dipendenza non pianificati durante il freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -329,14 +329,14 @@ export { customPolicies }; ## Esempi -La directory `examples/` contiene file di politica pronti all'uso: +La directory `examples/` contiene file di politiche pronti per l'esecuzione: -| File | Contenuti | +| File | Contenuto | |------|----------| -| `examples/policies-basic.js` | Cinque politiche iniziali che coprono modalità di errore dell'agente comuni | -| `examples/policies-advanced/index.js` | Pattern avanzati: importazioni transitive, chiamate asincrone, scrubbing dell'output, e hook di fine sessione | -| `examples/convention-policies/security-policies.mjs` | Politiche di sicurezza basate su convenzione (blocca scritture .env, previeni la riscrittura della cronologia git) | -| `examples/convention-policies/workflow-policies.mjs` | Politiche di flusso di lavoro basate su convenzione (promemoria dei test, file di audit writes) | +| `examples/policies-basic.js` | Cinque politiche di partenza che coprono modalità di errore comuni dell'agente | +| `examples/policies-advanced/index.js` | Modelli avanzati: importazioni transitive, chiamate asincrone, scrubbing dell'output, e hook di fine sessione | +| `examples/convention-policies/security-policies.mjs` | Politiche di sicurezza basate su convenzione (blocca scritture .env, previeni riscrittura della cronologia git) | +| `examples/convention-policies/workflow-policies.mjs` | Politiche di flusso di lavoro basate su convenzione (promemoria di test, file di scrittura di audit) | ### Utilizzo di esempi di file espliciti @@ -356,4 +356,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Nessun comando di installazione necessario — i file vengono raccolti automaticamente al prossimo evento hook. \ No newline at end of file +Nessun comando di installazione necessario — i file vengono prelevati automaticamente al prossimo evento hook. \ No newline at end of file diff --git a/docs/it/dashboard.mdx b/docs/it/dashboard.mdx index fd644b56..0892a555 100644 --- a/docs/it/dashboard.mdx +++ b/docs/it/dashboard.mdx @@ -1,6 +1,7 @@ --- +--- title: Dashboard -description: "Monitora le sessioni degli agenti, esamina le chiamate ai tool e gestisci le policy" +description: "Monitora le sessioni degli agenti, rivedi le chiamate ai tool e gestisci le policy" icon: chart-line --- @@ -14,19 +15,19 @@ La dashboard di failproofai è un'applicazione web locale per monitorare le sess failproofai ``` -Si apre su `http://localhost:8020`. +Si apre all'indirizzo `http://localhost:8020`. -La dashboard legge i dati locali di progetto, sessione e configurazione di failproofai direttamente dal filesystem. Le funzionalità opzionali autenticate, come i promemoria di audit e gli inviti, inviano le informazioni necessarie per tali richieste (inclusi gli indirizzi email) alle API remote. +La dashboard legge i dati locali di progetto, sessione e configurazione di failproofai direttamente dal file system. Le funzionalità opzionali autenticate, come i promemoria di audit e gli inviti, inviano le informazioni necessarie per tali richieste (inclusi gli indirizzi email) alle API remote. --- ## Pagine -### Progetti +### Projects -Elenca tutti i progetti Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity e Goose trovati sul tuo computer. I progetti Claude vengono individuati da `~/.claude/projects/` (o dal percorso impostato da `CLAUDE_PROJECTS_PATH`); i progetti Codex vengono individuati scansionando ogni transcript sotto `~/.codex/sessions///
/*.jsonl` e raggruppando per il `cwd` registrato nel primo record della sessione; i progetti Copilot CLI vengono individuati scansionando ogni `~/.copilot/session-state//workspace.yaml` (configurabile tramite `COPILOT_HOME`) e raggruppando per il suo campo `cwd`; i progetti Cursor Agent vengono individuati scansionando i metadati per sessione sotto `~/.cursor/agent-sessions//` (configurabile tramite `CURSOR_HOME`, con `conversations/` e `sessions/` sondati come fallback) per uno scalare `cwd` in `meta.json` / `session.json` / `workspace.yaml`; i progetti OpenCode vengono individuati interrogando il suo DB SQLite su `~/.local/share/opencode/opencode.db` tramite `opencode db --format json` (leggiamo le tabelle `session` e `project` e raggruppiamo per `project_id`); i progetti Pi vengono individuati scansionando i transcript JSONL per sessione sotto `~/.pi/agent/sessions//_.jsonl` (configurabile tramite `PI_SESSIONS_DIR`) e estraendo il `cwd` dal primo record di ogni sessione; le sessioni gateway Hermes vengono lette direttamente dall'archivio SQLite di ogni profilo — `~/.hermes/state.db` più `~/.hermes/profiles//state.db` (sovrapponibile tramite `HERMES_HOME`, oppure `HERMES_DB_PATH` per un singolo database) — e raggruppate in progetti `hermes--` per profilo e `source` (Slack/Telegram/cli/cron — le sessioni gateway non hanno cwd); le sessioni gateway OpenClaw vengono lette da `~/.openclaw/agents//sessions/*.jsonl` e raggruppate in progetti `openclaw--` per agente e canale (anch'esse senza cwd); i progetti Factory Droid vengono individuati dai transcript JSONL su `~/.factory/sessions//*.jsonl` e raggruppati per cwd; i progetti Devin dal suo DB SQLite su `~/.local/share/devin/cli/sessions.db` (raggruppati per il `working_directory` di ogni sessione); i progetti Antigravity dai transcript JSONL su `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` e raggruppati per cwd; e i progetti Goose dal suo DB SQLite su `~/.local/share/goose/sessions/sessions.db` (raggruppati per il `working_dir` di ogni sessione). Un progetto che è stato utilizzato da più CLI viene visualizzato come una singola riga con tutti i badge corrispondenti. Usa il menu a tendina **CLI** sopra la tabella per filtrare per uno specifico CLI agente; l'URL conserva la tua selezione come `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Elenca tutti i progetti Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity e Goose trovati sulla tua macchina. I progetti Claude vengono rilevati da `~/.claude/projects/` (o dal percorso impostato da `CLAUDE_PROJECTS_PATH`); i progetti Codex vengono rilevati scannerizzando ogni trascrizione in `~/.codex/sessions///
/*.jsonl` e raggruppando per il `cwd` registrato nel primo record di ogni sessione; i progetti Copilot CLI vengono rilevati scannerizzando ogni `~/.copilot/session-state//workspace.yaml` (configurabile tramite `COPILOT_HOME`) e raggruppando per il campo `cwd`; i progetti Cursor Agent vengono rilevati scannerizzando i metadati per sessione in `~/.cursor/agent-sessions//` (configurabile tramite `CURSOR_HOME`, con `conversations/` e `sessions/` come fallback) per uno scalare `cwd` in `meta.json` / `session.json` / `workspace.yaml`; i progetti OpenCode vengono rilevati interrogando il suo DB SQLite all'indirizzo `~/.local/share/opencode/opencode.db` tramite `opencode db --format json` (leggiamo le tabelle `session` e `project` e raggruppiamo per `project_id`); i progetti Pi vengono rilevati scannerizzando le trascrizioni JSONL per sessione in `~/.pi/agent/sessions//_.jsonl` (configurabile tramite `PI_SESSIONS_DIR`) e estraendo il `cwd` dal primo record di ogni sessione; le sessioni del gateway Hermes vengono lette direttamente dal negozio SQLite di ogni profilo — `~/.hermes/state.db` più `~/.hermes/profiles//state.db` (sovrascrivibile tramite `HERMES_HOME`, o `HERMES_DB_PATH` per un singolo database) — e raggruppate in progetti `hermes--` per profilo e `source` (Slack/Telegram/cli/cron — le sessioni gateway non hanno cwd); le sessioni del gateway OpenClaw vengono lette da `~/.openclaw/agents//sessions/*.jsonl` e raggruppate in progetti `openclaw--` per agente e canale (anch'esse senza cwd); i progetti Factory Droid vengono rilevati dalle trascrizioni JSONL all'indirizzo `~/.factory/sessions//*.jsonl` e raggruppati per cwd; i progetti Devin dal suo DB SQLite all'indirizzo `~/.local/share/devin/cli/sessions.db` (raggruppati per `working_directory` di ogni sessione); i progetti Antigravity dalle trascrizioni JSONL all'indirizzo `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` e raggruppati per cwd; e i progetti Goose dal suo DB SQLite all'indirizzo `~/.local/share/goose/sessions/sessions.db` (raggruppati per `working_dir` di ogni sessione). Un progetto che è stato utilizzato da più CLI viene visualizzato come una singola riga con tutti i badge corrispondenti. Utilizza il dropdown **CLI** sopra la tabella per filtrare per un agente CLI specifico; l'URL preserva la tua selezione come `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -Hermes e OpenClaw hanno ambito utente e nessuna directory di lavoro per raggruppare, quindi vengono visualizzati come un **albero di cartelle comprimibile** — profilo (o agente) al livello superiore, i suoi canali sotto — mentre ogni CLI basato su cwd rimane una riga piatta. Le righe della cartella accumulano il conteggio delle sessioni e l'attività più recente di tutto ciò che contengono, le cartelle compresse vengono ricordate tra le visite e una ricerca per parola chiave espande tutto ciò che corrisponde. +Hermes e OpenClaw sono limitati all'utente e non hanno una directory di lavoro per raggruppare, quindi vengono visualizzati come un **albero di cartelle espandibile** — profilo (o agente) al livello superiore, i suoi canali sottostanti — mentre ogni CLI basato su cwd rimane una riga piatta. Le righe di cartelle aggregano il conteggio della sessione e l'attività più recente di tutto ciò che contengono, le cartelle compresse vengono ricordate tra le visite e una ricerca per parola chiave espande tutto ciò che corrisponde. Ogni progetto mostra: - Nome del progetto (derivato dal percorso della cartella) @@ -35,7 +36,7 @@ Ogni progetto mostra: Fai clic su un progetto per visualizzare le sue sessioni. -### Sessioni +### Sessions Elenca tutte le sessioni all'interno di un progetto. Ogni sessione mostra: - ID sessione @@ -43,64 +44,64 @@ Elenca tutte le sessioni all'interno di un progetto. Ogni sessione mostra: - Numero di chiamate ai tool - Conteggio dell'attività hook (policy che si sono attivate) -Usa il filtro intervallo di date e la ricerca ID sessione per ridurre l'elenco. Le sessioni sono impaginate. +Utilizza il filtro intervallo di date e la ricerca ID sessione per restringere l'elenco. Le sessioni vengono impaginate. Fai clic su una sessione per aprire il visualizzatore di sessione. -### Visualizzatore di sessione +### Session viewer -Il visualizzatore di sessione risponde alla domanda chiave per gli agenti autonomi: cosa ha fatto l'agente e ha mantenuto la rotta? Un badge CLI accanto all'intestazione indica se la sessione è una trascrizione di Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity o Goose. Mostra una timeline di tutto ciò che è accaduto in una sessione: +Il visualizzatore di sessione risponde alla domanda chiave per gli agenti autonomi: cosa ha fatto l'agente e ha mantenuto la rotta? Un badge CLI accanto all'intestazione indica se la sessione è una trascrizione Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity o Goose. Mostra una cronologia di tutto ciò che è accaduto in una sessione: -- **Messaggi** - Le risposte di testo di Claude e i prompt dell'utente -- **Chiamate ai tool** - Ogni tool invocato da Claude, con il suo input e output -- **Attività delle policy** - Per ogni chiamata ai tool, quali policy si sono attivate e quale decisione hanno restituito +- **Messages** - Le risposte di testo di Claude e i prompt degli utenti +- **Tool calls** - Ogni tool che Claude ha invocato, con il suo input e output +- **Policy activity** - Per ogni chiamata al tool, quali policy si sono attivate e quale decisione hanno restituito -La barra delle statistiche in alto mostra la durata della sessione, il numero totale di chiamate ai tool e un riepilogo delle decisioni hook (conteggi allow / deny / instruct). +La barra delle statistiche nella parte superiore mostra la durata della sessione, il totale delle chiamate ai tool e un riepilogo delle decisioni hook (conteggi allow / deny / instruct). -Fai clic sul pulsante **Download Logs** per esportare la sessione. Per le sessioni Claude Code, Codex, Copilot, Cursor e Pi ottieni il transcript JSONL originale su disco byte per byte; per OpenCode (le cui sessioni si trovano in SQLite, non su disco) ottieni un documento JSON che rispecchia le tabelle sottostanti `session` / `messages` / `parts`. +Fai clic sul pulsante **Download Logs** per esportare la sessione. Per le sessioni Claude Code, Codex, Copilot, Cursor e Pi ottieni la trascrizione JSONL originale su disco byte-per-byte; per OpenCode (le cui sessioni vivono in SQLite, non su disco) ottieni un documento JSON che rispecchia le tabelle `session` / `messages` / `parts` sottostanti. ### Audit -Un rapporto guidato dalla personalità su come il tuo agente si è effettivamente comportato nelle sessioni passate. Esegue la stessa scansione del CLI `failproofai audit` ma la rende come un poster condivisibile a schermo unico + quattro sezioni sotto la piega: +Un report guidato dalla personalità di come il tuo agente si è effettivamente comportato nelle sessioni passate. Esegue la stessa scansione del CLI `failproofai audit` ma la renderizza come un poster condivisibile a schermo singolo + quattro sezioni sotto la piega: -1. **Poster** — riempie il primo viewport. Regione PNG self-contained con il wordmark failproof_ai + etichetta audit · indice archetipo (`№ NN di 08`) + data audit · punteggio numerico (0–100) + pillola di ranking percentile (`top 15%`) · il nome dell'archetipo (uno di `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + striscia da 3 parole chiave · riga di rarità `// only N% of agents are this archetype` · tile sigillo 8×8 pixel · footer `audit yours → failproof.ai`. Tre pulsanti di condivisione si trovano appena al di fuori della casella di acquisizione: `post your archetype` (intenzione X), `share on linkedin`, `download poster`. L'acquisizione funziona tramite `html-to-image` quindi il PNG corrisponde al rendering su schermo pixel per pixel (bordi tratteggiati, maschera logo SVG, gradienti, metriche dei caratteri — tutto conservato). -2. **Strengths** — elenco di righe calmo ✓ dei comportamenti che il tuo agente già fa bene, derivato dai dati di audit live (tasso di chiamata ai tool pulito, nessun push diretto a main, zero perdite di credenziali, zero tempeste di tentativi) — ognuno presentato solo quando la relativa policy ha un registro pulito nell'intervallo di audit. -3. **Quirks** — tabella di ciò che è sfuggito, classificato per gravità: `when · what slipped + the policy that would've caught it · severity pill · seen`, dove la ricorrenza legge `new` (una volta), `N× seen` (2–9 volte), o `recurring` (10+). -4. **How to improve** — elenco di righe calmo, uno per policy prescritta: nome policy in bianco, descrizione di una riga, comando di installazione + pulsante di copia sul lato destro. L'intestazione della sezione legge `enable all N → projected · ` (il punteggio che raggiungeresti con ogni correzione applicata), e il suo pulsante `[install all]` copia il comando combinato `failproofai policy add a b c …` per ogni policy prescritta. -5. **Come back better** — due carte una accanto all'altra. Sinistra: imposta un promemoria (selettore di cadenza `3d` / `7d` / `14d` / `30d`; persiste tramite `/api/auth/reminder` una volta autenticato). Destra: sblocca i vantaggi di failproof — `invite a friend` apre un modale che accetta un elenco di email di amici separati da virgola/spazio/newline (max 10 per invio), le invia tramite POST a `/api/audit/invite`, che inoltrano a `POST /v0/invite` del server api. Il server api invia un'email per destinatario da `invite@failproof.ai` con il mittente in Cc e `Reply-To` impostato, quindi il destinatario vede chi lo ha invitato e il mittente riceve una copia nella sua inbox. Gli utenti anonimi vengono instradati prima attraverso `AuthDialog` in modo che l'email del mittente sia nota prima che gli inviti vengano inviati. L'adempimento dei diritti / vantaggi è un seguito. +1. **Poster** — riempie il primo viewport. Regione di cattura PNG autonoma con il marchio failproof_ai + etichetta audit · indice archetipo (`№ NN di 08`) + data dell'audit · punteggio numerico (0–100) + pillola di ranking percentile (`top 15%`) · il nome dell'archetipo (uno tra `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + striscia a 3 parole chiave · riga di rarità `// solo il N% degli agenti ha questo archetipo` · sigillo a piastrelle di 8×8 pixel · footer `audit yours → failproof.ai`. Tre pulsanti di condivisione si trovano appena fuori dalla casella di cattura: `post your archetype` (intent X), `share on linkedin`, `download poster`. La cattura viene eseguita tramite `html-to-image` quindi il PNG corrisponde al rendering sullo schermo pixel per pixel (bordi tratteggiati, maschera logo SVG, gradienti, metriche dei caratteri — tutto preservato). +2. **Strengths** — elenco di righe calme ✓ dei comportamenti che il tuo agente già fa bene, derivati dai dati di audit dal vivo (tasso di chiamate ai tool pulito, nessun push diretto a main, zero perdite di credenziali, zero tempeste di retry) — ciascuno visualizzato solo quando la policy rilevante ha un record pulito in tutta la finestra dell'audit. +3. **Quirks** — tabella di ciò che è passato inosservato, classificata per gravità: `quando · cosa è passato + la policy che l'avrebbe catturato · pillola di gravità · visto`, dove la ricorrenza legge `new` (una volta), `N× seen` (2–9 volte), o `recurring` (10+). +4. **How to improve** — elenco di righe calme, uno per ogni policy prescritta: nome della policy in bianco, descrizione su una riga, comando di installazione + pulsante di copia sul lato destro. L'intestazione della sezione legge `enable all N → projected · ` (il punteggio che raggiungeresti con tutte le correzioni applicate), e il suo pulsante `[install all]` copia il comando combinato `failproofai policy add a b c …` per ogni policy prescritta. +5. **Come back better** — due carte affiancate. Sinistra: imposta un promemoria (selettore di cadenza `3d` / `7d` / `14d` / `30d`; si conserva tramite `/api/auth/reminder` una volta autenticato). Destra: sblocca i vantaggi failproof — `invite a friend` apre una modale che accetta un elenco separato da virgola/spazio/newline di email di amici (massimo 10 per invio), li invia tramite POST a `/api/audit/invite`, che si inoltrano all'`POST /v0/invite` del server api. Il server api invia un'email per ogni destinatario da `invite@failproof.ai` con il mittente in Cc e `Reply-To` impostato, quindi il destinatario vede chi lo ha invitato e il mittente riceve una copia nella sua inbox. Gli utenti anonimi vengono instradati prima attraverso `AuthDialog` in modo che l'email del mittente sia nota prima che gli inviti vengano inviati. La realizzazione di diritti / vantaggi è un follow-up. -Guidato dal runtime `failproofai audit` — vedi [Audit CLI](/it/cli/audit) per il motore di scansione sottostante, i flag supportati e gli invarianti di cache per transcript. La dashboard memorizza nella cache il risultato più recente su `~/.failproofai/audit-dashboard.json` (modo `0600`, slot singolo, i nuovi run sovrascrivono) quindi le revisioni sono istantanee; **sia la cache per transcript che il risultato complessivo vengono rifiutati in lettura una volta che sono più vecchi di 7 giorni** quindi la dashboard non serve mai silenziosamente un risultato di una settimana — passato il TTL `/audit` cade nel suo stato vuoto e chiede un'esecuzione nuova. Facendo clic su `[ re-audit now ]` vicino al fondo del rapporto si invia `/api/audit/run` con `noCache: true` — la riesecuzione dell'audit bypassa la cache per transcript e ripete la scansione di ogni transcript da zero invece di restituire silenziosamente il risultato memorizzato — e la dashboard esegue il polling di `/api/audit/status` a 1Hz fino al termine dell'esecuzione; una striscia di progresso rosa appiccicatizia si fissa all'inizio del viewport durante l'esecuzione con un timer di tempo trascorso, e il risultato nuovo si scambia al suo posto al successo (nessun ricaricamento della pagina intera; un riesame fallito dell'audit lascia intatto il rapporto precedente). In caso di errore la striscia diventa rossa con copia codificata da `RerunError.kind` (`timeout` / `network` / `post_failed`). Lo stato vuoto (nessuna cache o scaduta) e lo stato zero-sessioni (cache esiste ma la scansione non ha trovato alcun transcript) sono visualizzati separatamente. +Guidato dal runtime `failproofai audit` — vedi [Audit CLI](/it/cli/audit) per il motore di scansione sottostante, i flag supportati e gli invarianti della cache per trascrizione. La dashboard memorizza nella cache il risultato più recente in `~/.failproofai/audit-dashboard.json` (modalità `0600`, slot singolo, i nuovi esecuzioni sovrascrivono) quindi le rivisite sono istantanee; **sia le cache per trascrizione che il risultato complessivo vengono rifiutate in lettura una volta che hanno più di 7 giorni** quindi la dashboard non serve mai silenziosamente un risultato di una settimana fa — dopo il TTL `/audit` cade nello stato vuoto e richiede un'esecuzione fresca. Fare clic su `[ re-audit now ]` vicino al fondo del report POST `/api/audit/run` con `noCache: true` — il re-audit bypassa la cache per trascrizione e scansiona ogni trascrizione da zero piuttosto che restituire silenziosamente il risultato in cache — e la dashboard esegue il polling `/api/audit/status` a 1Hz fino al termine dell'esecuzione; una striscia di progresso rosa appiccicosa si appunta in cima al viewport durante l'esecuzione con un timer del tempo trascorso, e il risultato fresco si sostituisce al suo posto al successo (nessun ricaricamento completo della pagina; un re-audit fallito lascia il rapporto precedente intatto). In caso di errore la striscia diventa rossa con la copia basata su `RerunError.kind` (`timeout` / `network` / `post_failed`). Lo stato vuoto (nessuna cache o scaduta) e lo stato di sessioni zero (cache esiste ma la scansione non ha trovato trascrizioni) vengono visualizzati separatamente. -### Policy +### Policies -Una pagina a due schede per gestire le policy e esaminare l'attività. +Una pagina a due schede per gestire le policy e rivedere l'attività. - - - Seleziona più CLI agente che failproofai protegge da un singolo pannello — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Hermes hanno tutti una riga con stato di installazione (`Active` / `Detected` / `Inactive`), il percorso delle impostazioni con ambito utente e un accento di colore del marchio. Seleziona o deseleziona i CLI che desideri e fai clic su `Apply changes` per installare/disinstallare la differenza in un unico passaggio. I CLI il cui binario è rilevato su PATH sono pre-selezionati. - - Attiva o disattiva singole policy con un solo clic (scrive su `~/.failproofai/policies-config.json` — condiviso su ogni CLI installato) - - Espandi una policy per configurarne i parametri (per le policy che supportano `policyParams`) - - Imposta un percorso file di policy personalizzato + + - Seleziona più agent CLI di cui failproofai protegge da un singolo pannello — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Hermes hanno tutti una riga con stato di installazione (`Active` / `Detected` / `Inactive`), il percorso delle impostazioni con ambito utente e un accento brandizzato. Seleziona o deseleziona i CLI che desideri e fai clic su `Apply changes` per installare/disinstallare la differenza in un passaggio. I CLI il cui binario è rilevato su PATH sono pre-selezionati. + - Attiva o disattiva singole policy con un singolo clic (scrive su `~/.failproofai/policies-config.json` — condiviso tra ogni CLI installato) + - Espandi una policy per configurare i suoi parametri (per policy che supportano `policyParams`) + - Imposta un percorso di file di policy personalizzate - - - Cronologia impaginata completa di ogni evento hook che si è attivato in tutte le sessioni + + - Cronologia paginata completa di ogni evento hook che si è attivato in tutte le sessioni - Filtra per decisione, tipo di evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nome della policy o ID sessione - - Ogni riga mostra: timestamp, nome della policy, decisione, badge CLI (arancione = Claude Code, viola = OpenAI Codex, blu = GitHub Copilot, smeraldo = Cursor Agent, ambra = OpenCode, rosa = Pi, indaco = Hermes, azzurro = OpenClaw, rosa antico = Factory Droid, violetto = Devin, ciano = Antigravity, lime = Goose), nome del tool, ID sessione e il motivo delle decisioni deny/instruct - - Fai clic su un ID sessione per aprire il suo transcript — il visualizzatore auto-rileva quale CLI ha attivato l'hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) e visualizza il badge CLI corrispondente nell'intestazione + - Ogni riga mostra: timestamp, nome della policy, decisione, badge CLI (arancione = Claude Code, viola = OpenAI Codex, blu = GitHub Copilot, smeraldo = Cursor Agent, ambra = OpenCode, rosa = Pi, indaco = Hermes, verde teal = OpenClaw, rosa chiaro = Factory Droid, viola = Devin, ciano = Antigravity, verde limone = Goose), nome del tool, ID sessione e il motivo delle decisioni deny/instruct + - Fai clic su un ID sessione per aprire la sua trascrizione — il visualizzatore rileva automaticamente quale CLI ha attivato l'hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) e renderizza il badge CLI corrispondente nell'intestazione --- -## Aggiornamento automatico +## Auto-refresh -La dashboard dispone di un interruttore di aggiornamento automatico nella navigazione in alto. Se abilitato, la pagina corrente si aggiorna periodicamente per mostrare nuove sessioni e attività di policy man mano che appaiono. Essenziale per il monitoraggio delle sessioni di agenti autonomi a lunga esecuzione. +La dashboard ha un interruttore di auto-refresh nella navigazione in alto. Quando abilitato, la pagina corrente si aggiorna periodicamente per mostrare nuove sessioni e attività di policy man mano che appaiono. Essenziale per monitorare le sessioni di agenti autonomi di lunga durata. --- ## Disabilitazione delle pagine -Se hai bisogno solo di alcune parti della dashboard, imposta `FAILPROOFAI_DISABLE_PAGES` su un elenco separato da virgole di nomi di pagina: +Se hai bisogno solo di alcune parti della dashboard, imposta `FAILPROOFAI_DISABLE_PAGES` su un elenco separato da virgola di nomi di pagine: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -112,7 +113,7 @@ Valori validi: `policies`, `projects`, `audit`. ## Configurazione del percorso dei progetti -Per impostazione predefinita, la dashboard legge dalla directory dei progetti Claude Code standard. Sostituiscila per configurazioni personalizzate: +Per impostazione predefinita, la dashboard legge dalla directory dei progetti Claude Code standard. Sovrascrivilo per configurazioni personalizzate: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -122,19 +123,19 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Accesso da un host non-localhost -Quando esegui la dashboard in **modalità dev** (`npm run dev`) e accedi da un nome host diverso da `localhost` - ad esempio, un dominio personalizzato, un IP remoto o un URL tunnelato - potresti vedere un avviso come: +Quando esegui la dashboard in **modalità dev** (`npm run dev`) e vi accedi da un nome host diverso da `localhost` - ad esempio, un dominio personalizzato, un IP remoto o un URL con tunnel — potresti vedere un avviso come: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Si tratta di Next.js che blocca l'accesso cross-origin alla sua risorsa dev HMR (hot module reload websocket), che è una funzionalità solo per dev. Per consentire il tuo host, usa il flag `--allowed-origins`: +Questo è Next.js che blocca l'accesso cross-origin al suo websocket HMR (hot module reload), che è una funzionalità solo per dev. Per consentire il tuo host, utilizza il flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -Per più host o IP, passa un elenco separato da virgole: +Per più host o IP, passa un elenco separato da virgola: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 @@ -147,5 +148,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Questo si applica solo alla modalità dev. Quando si esegue `failproofai` (modalità produzione), non c'è websocket HMR e nessun problema di risorsa dev cross-origin. +Questo si applica solo alla modalità dev. Quando esegui `failproofai` (modalità produzione), non c'è websocket HMR e nessun problema con le risorse dev cross-origin. \ No newline at end of file diff --git a/docs/it/examples.mdx b/docs/it/examples.mdx index 40dbf6af..fc1dea25 100644 --- a/docs/it/examples.mdx +++ b/docs/it/examples.mdx @@ -1,6 +1,7 @@ --- +--- title: Esempi -description: "Come configurare gli hook per Claude Code e Agents SDK" +description: "Come configurare gli hook per Claude Code e l'Agents SDK" icon: book-open --- @@ -8,9 +9,9 @@ Esempi pronti all'uso per scenari comuni. Ognuno mostra come installare e cosa a --- -## Configurare gli hook per Claude Code +## Configurazione degli hook per Claude Code -Failproof AI si integra con Claude Code attraverso il suo [sistema di hook](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando esegui `failproofai policies --install`, registra i comandi degli hook nel file `settings.json` di Claude Code che si attivano ad ogni chiamata di strumento. +Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando esegui `failproofai policies --install`, registra i comandi degli hook nel `settings.json` di Claude Code che si attivano ad ogni chiamata di strumento. @@ -35,15 +36,15 @@ Failproof AI si integra con Claude Code attraverso il suo [sistema di hook](http claude ``` - Le policy ora vengono eseguite automaticamente ad ogni chiamata di strumento. Prova a chiedere a Claude di eseguire `sudo rm -rf /` - verrà bloccato. + Le policy ora funzionano automaticamente ad ogni chiamata di strumento. Prova a chiedere a Claude di eseguire `sudo rm -rf /` - verrà bloccato. --- -## Configurare gli hook per Agents SDK +## Configurazione degli hook per l'Agents SDK -Se stai costruendo con [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), puoi utilizzare lo stesso sistema di hook a livello di programmazione. +Se stai costruendo con l'[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), puoi usare lo stesso sistema di hook a livello di programmazione. @@ -51,15 +52,15 @@ Se stai costruendo con [Agents SDK](https://docs.anthropic.com/en/docs/agents-sd npm install failproofai ``` - - Passa i comandi degli hook quando crei il processo del tuo agente. Gli hook si attivano allo stesso modo di Claude Code - tramite JSON su stdin/stdout: + + Passa i comandi degli hook quando crei il tuo processo agent. Gli hook si attivano nello stesso modo che in Claude Code - tramite stdin/stdout JSON: ```bash failproofai --hook PreToolUse # chiamato prima di ogni strumento failproofai --hook PostToolUse # chiamato dopo ogni strumento ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -88,7 +89,7 @@ Se stai costruendo con [Agents SDK](https://docs.anthropic.com/en/docs/agents-sd ## Blocca i comandi distruttivi -La configurazione più comune - previeni che gli agenti causino danni irreversibili. +La configurazione più comune - evita che gli agent causino danni irreversibili. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -98,23 +99,23 @@ Cosa fa: - `block-sudo` - blocca tutti i comandi `sudo` - `block-rm-rf` - blocca l'eliminazione ricorsiva di file - `block-force-push` - blocca `git push --force` -- `block-curl-pipe-sh` - blocca l'invio di script remoti tramite pipe a shell +- `block-curl-pipe-sh` - blocca il piping di script remoti alla shell --- -## Previeni la fuga di segreti +## Previeni la perdita di segreti -Impedisci agli agenti di vedere o divulgare credenziali nell'output dello strumento. +Impedisci agli agent di vedere o perdere credenziali nell'output degli strumenti. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Si attivano su `PostToolUse` - dopo che uno strumento viene eseguito, puliscono l'output prima che l'agente lo veda. +Questi si attivano su `PostToolUse` - dopo che uno strumento viene eseguito, puliscono l'output prima che l'agent lo veda. --- -## Ricevi avvisi Slack quando gli agenti hanno bisogno di attenzione +## Ricevi avvisi Slack quando gli agent richiedono attenzione Usa l'hook di notifica per inoltrare gli avvisi di inattività a Slack. @@ -150,7 +151,7 @@ customPolicies.add({ }); ``` -Installalo: +Installala: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -158,9 +159,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## Mantieni gli agenti su un ramo +## Mantieni gli agent su un branch -Impedisci agli agenti di cambiare ramo o fare push verso rami protetti. +Impedisci agli agent di cambiare branch o eseguire push su quelli protetti. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +185,7 @@ customPolicies.add({ ## Richiedi test prima dei commit -Ricorda agli agenti di eseguire i test prima di fare commit. +Ricorda agli agent di eseguire i test prima di fare commit. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -206,11 +207,11 @@ customPolicies.add({ --- -## Proteggi un repo di produzione +## Blocca un repo di produzione -Effettua il commit della configurazione a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse policy. +Fai il commit di una config a livello di progetto in modo che ogni sviluppatore del tuo team riceva le stesse policy. -Crea `.failproofai/policies-config.json` nel tuo repository: +Crea `.failproofai/policies-config.json` nel tuo repo: ```json { @@ -231,7 +232,7 @@ Crea `.failproofai/policies-config.json` nel tuo repository: } ``` -Quindi effettua il commit: +Poi fai il commit: ```bash git add .failproofai/policies-config.json @@ -242,9 +243,9 @@ Ogni membro del team che ha failproofai installato raccoglierà automaticamente --- -## Crea uno standard di qualità a livello organizzativo con le policy di convenzione +## Costruisci uno standard di qualità a livello di organizzazione con le policy di convenzione -La configurazione più impattante: effettua il commit di `.failproofai/policies/` nel tuo repo con policy personalizzate per il tuo progetto. Ogni membro del team le ottiene automaticamente — nessun comando di installazione, nessun cambiamento di configurazione. +La configurazione più impactante: fai il commit di `.failproofai/policies/` nel tuo repo con policy personalizzate per il tuo progetto. Ogni membro del team le riceve automaticamente — nessun comando di installazione, nessun cambio di config. @@ -283,14 +284,14 @@ La configurazione più impattante: effettua il commit di `.failproofai/policies/ }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Man mano che il tuo team incontra nuovi modi di fallire, aggiungi policy e fai il push. Tutti ricevono l'aggiornamento al loro prossimo `git pull`. Queste policy diventano uno standard di qualità vivo che cresce con il tuo team. + Quando il tuo team scopre nuove modalità di errore, aggiungi le policy e fai il push. Tutti ricevono l'aggiornamento al prossimo `git pull`. Queste policy diventano uno standard di qualità in continua evoluzione che cresce con il tuo team. @@ -298,10 +299,10 @@ La configurazione più impattante: effettua il commit di `.failproofai/policies/ ## Altri esempi -La directory [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) nel repository contiene: +La directory [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) nel repo contiene: | File | Cosa mostra | -|------|-------------| -| `policies-basic.js` | Policy di base - blocca le scritture in produzione, force-push, script inviati tramite pipe | -| `policies-notification.js` | Avvisi Slack per notifiche di inattività e fine sessione | +|------|---------------| +| `policies-basic.js` | Policy di base - blocca le scritture di produzione, force-push, script piped | +| `policies-notification.js` | Avvisi Slack per notifiche di inattività e fine della sessione | | `policies-advanced/index.js` | Import transitivi, hook asincroni, scrubbing dell'output PostToolUse, gestione dell'evento Stop | \ No newline at end of file diff --git a/docs/it/for-agents.mdx b/docs/it/for-agents.mdx index f9216c5b..49d1af8f 100644 --- a/docs/it/for-agents.mdx +++ b/docs/it/for-agents.mdx @@ -1,6 +1,6 @@ --- title: "Per gli agenti" -description: "Aggiungi la conoscenza di Failproof AI al tuo agente di codifica in un comando. Funziona con Claude Code, Cursor, Windsurf e molti altri." +description: "Aggiungi la conoscenza di Failproof AI al tuo agente di codifica in un comando. Funziona con Claude Code, Cursor, Windsurf e altri ancora." --- Aggiungi il riferimento completo di Failproof AI al tuo agente di codifica in un comando. Funziona con Claude Code, Cursor, Windsurf e qualsiasi altro agente che supporti le skill. @@ -14,13 +14,13 @@ npx skills add https://docs.befailproof.ai ## Cosa copre la skill | Area | Cosa è incluso | -|------|----------------| -| Policies | Nomi policy built-in, tipi di evento, parametri, abilitazione/disabilitazione | -| Custom policies | `customPolicies.add()`, filtri di corrispondenza, API `allow`/`deny`/`instruct` | +|------|---| +| Policies | Nomi delle policy built-in, tipi di evento, parametri, abilitazione/disabilitazione | +| Policy personalizzate | `customPolicies.add()`, filtri di corrispondenza, API `allow`/`deny`/`instruct` | | Oggetto Context | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configurazione | Struttura `policies-config.json`, merging dei scope, `policyParams` | +| Configurazione | Struttura di `policies-config.json`, fusione degli scope, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scope | -| Dashboard | Visualizzatore di sessioni, attività delle policy, variabili d'ambiente | +| Dashboard | Visualizzatore delle sessioni, attività delle policy, variabili d'ambiente | | Architettura | Flusso del gestore hook, codici di uscita, contratto stdin/stdout | ## La skill è completa? @@ -30,7 +30,7 @@ Mintlify genera `llms.txt` da tutte le pagine nella navigazione. La documentazio Per un contesto mirato, collega direttamente a una pagina specifica: ```bash -# Solo l'API delle custom policies +# Solo l'API delle policy personalizzate npx skills add https://docs.befailproof.ai/custom-policies # Solo le policy built-in diff --git a/docs/it/getting-started.mdx b/docs/it/getting-started.mdx index b0384df1..a308afa2 100644 --- a/docs/it/getting-started.mdx +++ b/docs/it/getting-started.mdx @@ -1,13 +1,13 @@ --- title: Iniziare -description: "Installa failproofai, abilita i criteri e lascia che i tuoi agenti funzionino in modo affidabile" +description: "Installa failproofai, abilita le policy e lascia che i tuoi agent funzionino in modo affidabile" icon: rocket --- ## Requisiti - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (facoltativo - necessario solo per compilare dal codice sorgente) +- **Bun** >= 1.3.0 (opzionale - necessario solo per compilare da sorgente) --- @@ -30,16 +30,16 @@ bun add -g failproofai ## Avvio rapido - - I criteri sono regole che vengono eseguite prima e dopo ogni chiamata di strumento dell'agente. Catturano comandi distruttivi, perdite di segreti e altre modalità di errore prima che causino danni. + + Le policy sono regole che vengono eseguite prima e dopo ogni chiamata a uno strumento dell'agent. Intercettano comandi distruttivi, perdite di segreti e altri modi di fallimento prima che causino danni. ```bash failproofai policies --install ``` - Questo scrive voci di hook nelle CLI dell'agente installate (`~/.claude/settings.json` di Claude Code, `~/.codex/hooks.json` di OpenAI Codex, `~/.copilot/hooks/failproofai.json` di GitHub Copilot CLI, `~/.cursor/hooks.json` di Cursor Agent, il plugin shim generato di OpenCode in `~/.config/opencode/plugins/failproofai.mjs` più una voce di registrazione nell'array `plugin` di `~/.config/opencode/opencode.json`, `~/.pi/agent/settings.json` di Pi, `~/.hermes/config.yaml` di Hermes, `~/.openclaw/openclaw.json` di OpenClaw, `~/.factory/hooks.json` di Factory Droid, `~/.config/devin/config.json` di Devin CLI, `~/.gemini/config/hooks.json` di Antigravity CLI, o la directory plugin auto-rilevata di Goose in `~/.agents/plugins/failproofai/hooks/hooks.json`). Quando ne è presente più di uno, ti verrà chiesto; passa `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (qualsiasi sottoinsieme) per saltare il prompt. + Questo aggiunge voci di hook ai CLI degli agent installati (il file `~/.claude/settings.json` di Claude Code, il file `~/.codex/hooks.json` di OpenAI Codex, il file `~/.copilot/hooks/failproofai.json` di GitHub Copilot CLI, il file `~/.cursor/hooks.json` di Cursor Agent, il file di plugin generato di OpenCode in `~/.config/opencode/plugins/failproofai.mjs` più una voce di registrazione nell'array `plugin` di `~/.config/opencode/opencode.json`, il file `~/.pi/agent/settings.json` di Pi, il file `~/.hermes/config.yaml` di Hermes, il file `~/.openclaw/openclaw.json` di OpenClaw, il file `~/.factory/hooks.json` di Factory Droid, il file `~/.config/devin/config.json` di Devin CLI, il file `~/.gemini/config/hooks.json` di Antigravity CLI, o la directory di plugin auto-scoperta di Goose in `~/.agents/plugins/failproofai/hooks/hooks.json`). Quando è presente più di uno, ti verrà chiesto di scegliere; passa `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (qualsiasi sottoinsieme) per saltare la richiesta. - GitHub Copilot CLI, Cursor Agent, OpenCode e il supporto per Pi sono in **beta** — installa con `--cli copilot`, `--cli cursor`, `--cli opencode`, o `--cli pi`. Hermes (hermes-agent, un gateway Slack/Telegram) si installa con scope utente con `--cli hermes` ed è **anche** una fonte di controllo offline. OpenClaw (gateway openclaw, un assistente multi-canale self-hosted) si installa con scope utente con `--cli openclaw` — l'enforcement viene eseguito attraverso i suoi hook di plugin in-process (`before_agent_finalize` è un vero gate di fine turno, quindi i builtin `require-*-before-stop` enforcer) — ed è **anche** una fonte di controllo offline. Factory Droid (`droid`) si installa con `--cli factory` (scope utente + progetto) ed è **anche** una fonte di controllo offline. Devin CLI (`devin`, Cognition) si installa con `--cli devin` (scope utente + progetto) ed è **anche** una fonte di controllo offline. Antigravity CLI (`agy`) si installa con `--cli antigravity` (scope utente + progetto) ed è **anche** una fonte di controllo offline. Goose (codename goose, Block) si installa con `--cli goose` (scope utente + progetto) — l'installer rilascia semplicemente una directory di plugin in `~/.agents/plugins/failproofai/` che Goose auto-rileva, ed è **anche** una fonte di controllo offline. + Il supporto per GitHub Copilot CLI, Cursor Agent, OpenCode e Pi è in **beta** — installa con `--cli copilot`, `--cli cursor`, `--cli opencode` o `--cli pi`. Hermes (hermes-agent, un gateway Slack/Telegram) si installa con scope utente con `--cli hermes` ed è **anche** una fonte di audit offline. OpenClaw (gateway openclaw, un assistente multi-canale auto-ospitato) si installa con scope utente con `--cli openclaw` — l'enforcement viene eseguito attraverso i suoi hook di plugin in-process (`before_agent_finalize` è un vero gate di fine turno, quindi i builtin `require-*-before-stop` applicano l'enforcement) — ed è **anche** una fonte di audit offline. Factory Droid (`droid`) si installa con `--cli factory` (scope utente + progetto) ed è **anche** una fonte di audit offline. Devin CLI (`devin`, Cognition) si installa con `--cli devin` (scope utente + progetto) ed è **anche** una fonte di audit offline. Antigravity CLI (`agy`) si installa con `--cli antigravity` (scope utente + progetto) ed è **anche** una fonte di audit offline. Goose (nome in codice goose, Block) si installa con `--cli goose` (scope utente + progetto) — l'installer crea semplicemente una directory di plugin in `~/.agents/plugins/failproofai/` che Goose auto-scopre, ed è **anche** una fonte di audit offline. ```bash failproofai policies --install --scope project @@ -62,62 +62,62 @@ bun add -g failproofai failproofai policies ``` - Mostra ogni criterio, se è abilitato e eventuali parametri configurati. + Mostra tutte le policy, se sono abilitate e i parametri configurati. - + ```bash failproofai ``` - Apre una dashboard locale in `http://localhost:8020` dove puoi sfogliare le sessioni, ispezionare le chiamate di strumento e gestire i criteri. + Apre un dashboard locale su `http://localhost:8020` dove puoi consultare le sessioni, ispezionare le chiamate a strumenti e gestire le policy. - - Avvia Claude Code come al solito. Se l'agente tenta qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione incustodito e rivedi quello che è successo nella dashboard. + + Avvia Claude Code come al solito. Se l'agent tenta qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione senza presidiare e rivedi quello che è accaduto nel dashboard. --- -## Come funzionano i criteri +## Come funzionano le policy -Ogni volta che un agente esegue uno strumento, Claude Code chiama failproofai come subprocess: +Ogni volta che un agent esegue uno strumento, Claude Code chiama failproofai come sottoprocesso: ```text Claude Code → failproofai --hook PreToolUse → legge JSON da stdin - valuta i criteri - scrive la decisione su stdout + valuta le policy + scrive la decisione su stdout ``` -Ogni criterio restituisce una di tre decisioni: +Ogni policy restituisce una di tre decisioni: -- **allow** - l'agente procede normalmente -- **deny** - l'azione è bloccata, all'agente viene spiegato il motivo -- **instruct** - un contesto aggiuntivo viene aggiunto al prompt dell'agente +- **allow** - l'agent procede normalmente +- **deny** - l'azione è bloccata, all'agent viene spiegato il motivo +- **instruct** - contesto aggiuntivo viene aggiunto al prompt dell'agent -I criteri vengono eseguiti nel tuo processo locale. Nulla viene inviato a un servizio remoto. +Le policy vengono eseguite nel tuo processo locale. Nulla viene inviato a un servizio remoto. --- -## Configura i criteri del team con criteri basati sulla convenzione +## Configura policy di team con policy basate su convenzione -Il modo più veloce per stabilire standard di qualità su tutto il team è la convenzione `.failproofai/policies/`. Inserisci i file di criterio in questa directory e verranno caricati automaticamente — nessun flag, nessun cambio di configurazione, nessun comando di installazione. +Il modo più rapido per stabilire standard di qualità in tutto il team è la convenzione `.failproofai/policies/`. Inserisci i file di policy in questa directory e verranno caricati automaticamente — niente flag, niente modifiche alla configurazione, niente comandi di installazione. - + ```bash mkdir -p .failproofai/policies ``` - - Copia gli esempi di avviamento o scrivi i tuoi: + + Copia gli esempi iniziali o scrivi i tuoi: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - Oppure creane uno nuovo: + O creane uno nuovo: ```js // .failproofai/policies/team-policies.mjs @@ -129,7 +129,7 @@ Il modo più veloce per stabilire standard di qualità su tutto il team è la co fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Run tests before committing."); + return instruct("Esegui i test prima di fare commit."); } return allow(); }, @@ -142,12 +142,12 @@ Il modo più veloce per stabilire standard di qualità su tutto il team è la co git commit -m "Add team quality policies" ``` - Ogni membro del team che ha failproofai installato raccoglie automaticamente questi criteri. Non è necessaria alcuna configurazione per sviluppatore. + Ogni membro del team che ha failproofai installato raccoglie automaticamente queste policy. Nessuna configurazione per sviluppatore necessaria. -Esegui il commit di `.failproofai/policies/` nel tuo repository in modo che l'intero team condivida gli stessi standard. Man mano che il team scopre nuove modalità di errore, aggiungi criteri e spingili — tutti ricevono l'aggiornamento al prossimo `git pull`. Nel tempo questi criteri diventano uno standard di qualità vivente che continua a migliorare. +Fai il commit di `.failproofai/policies/` nel tuo repository in modo che tutto il team condivida gli stessi standard. Man mano che il tuo team scopre nuovi modi di fallimento, aggiungi policy ed esegui il push — tutti ricevono l'aggiornamento al prossimo `git pull`. Nel corso del tempo queste policy diventano uno standard di qualità vivente che continua a migliorare. --- @@ -156,13 +156,15 @@ Esegui il commit di `.failproofai/policies/` nel tuo repository in modo che l'in Tutte le configurazioni e i log rimangono sulla tua macchina: -| Percorso | Cosa contiene | +| Percorso | Cosa memorizza | |------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | Configurazione globale dei criteri | -| `~/.failproofai/hook-activity/` | Cronologia dell'esecuzione dei hook (JSONL pagginato) | +| `~/.failproofai/policies-config.json` | Config globale delle policy | +| `~/.failproofai/policies/` | Le tue policy — inserisci file `*-policies.mjs`, nessuna configurazione necessaria | +| `~/.failproofai/policies/cloud-policies/` | Policy distribuite a questa macchina dalla tua organizzazione | +| `~/.failproofai/hook-activity/` | Cronologia dell'esecuzione degli hook (JSONL impaginato) | | `~/.failproofai/logs/` | Log di debug per errori di hook personalizzati | -| `.failproofai/policies-config.json` | Configurazione per progetto (committata) | -| `.failproofai/policies-config.local.json` | Override personali (gitignored) | +| `.failproofai/policies-config.json` | Config per progetto (sottoposto a commit) | +| `.failproofai/policies-config.local.json` | Personalizzazioni personali (ignorato da git) | --- @@ -181,19 +183,19 @@ Rimuove le voci di hook da `~/.claude/settings.json`. I file di configurazione i - Scope e formato del file di configurazione + Scopes e formato del file di configurazione - - Tutti i 26 criteri con parametri + + Tutte le 26 policy con parametri - - Scrivi i tuoi criteri in JavaScript + + Scrivi le tue policy in JavaScript - - Monitora le sessioni e rivedi l'attività dei criteri + + Monitora le sessioni e rivedi l'attività delle policy \ No newline at end of file diff --git a/docs/it/introduction.mdx b/docs/it/introduction.mdx index f5c57577..e79bcd2c 100644 --- a/docs/it/introduction.mdx +++ b/docs/it/introduction.mdx @@ -1,37 +1,37 @@ --- --- title: "Failproof AI" -description: "FailproofAI fornisce agli agenti AI 39 politiche di errore integrate che catturano loop, perdite di segreti, chiamate di strumenti distruttive e altro ancora in una singola installazione." +description: "FailproofAI offre agli agenti AI 39 politiche di fallimento integrate che rilevano loop, fughe di segreti, chiamate di strumenti distruttive e altro ancora con una singola installazione." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hook e politiche per **gestione degli errori nell'AI**, **recupero dagli errori** e **affidabilità degli LLM**. Mantieni i tuoi agenti AI affidabili e in esecuzione autonoma su **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** e **Agents SDK**. +Hook e politiche per la **gestione dei fallimenti dell'IA**, il **recupero dagli errori** e l'**affidabilità degli LLM**. Mantieni i tuoi agenti AI affidabili e in esecuzione autonoma su **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** e l'**Agents SDK**. -Gli agenti AI falliscono in modi prevedibili. Eseguono comandi distruttivi, perdono segreti, si allontanano dall'obiettivo, rimangono bloccati in loop o eseguono push direttamente su main. Se lasciati incustoditi, i piccoli errori si cascano in interruzioni, credenziali compromesse e lavoro perso. +Gli agenti IA falliscono in modi prevedibili. Eseguono comandi distruttivi, rivelano segreti, si allontanano dall'obiettivo, rimangono bloccati in loop, o eseguono push direttamente sul ramo principale. Se lasciati incustoditi, i piccoli fallimenti si trasformano in disservizi, credenziali compromesse e lavoro perso. -FailproofAI risolve questo con le **politiche**. Queste regole si collegano a ogni chiamata di strumento dell'agente per **rilevare i fallimenti**, **mitigarli** (bloccare, istruire, sanificare) e **avvertirti** quando qualcosa ha bisogno di attenzione. Una dashboard locale ti consente di esaminare ogni chiamata di strumento, fallimento dell'agente e azione di recupero in seguito. +FailproofAI risolve questo con le **politiche**. Queste regole si agganciano ad ogni chiamata di strumento dell'agente per **rilevare i fallimenti**, **mitigarli** (bloccare, istruire, sanitizzare) e **avvisarti** quando qualcosa richiede attenzione. Una dashboard locale ti permette di riesaminare ogni chiamata di strumento, fallimento dell'agente e azione di recupero successivamente. -I trascritti e la valutazione delle politiche rimangono sul tuo computer. I dati vengono inviati solo quando utilizzi esplicitamente una funzione online, come promemoria di audit autenticati o inviti. +I transcript e la valutazione delle politiche rimangono sulla tua macchina. I dati vengono inviati solo quando utilizzi esplicitamente una funzionalità online, come i promemoria di audit autenticati o gli inviti. -## Inizia +## Iniziare - Blocca i comandi distruttivi, previeni la perdita di segreti, mantieni gli agenti entro i confini del progetto e altro ancora. Tutto pronto all'uso. + Blocca comandi distruttivi, previeni fughe di segreti, mantieni gli agenti all'interno dei confini del progetto e altro ancora. Il tutto pronto all'uso. - Scrivi le tue regole in JavaScript con una semplice API allow / deny / instruct. + Scrivi le tue regole in JavaScript con un semplice API allow / deny / instruct. - - Vedi cosa hanno fatto i tuoi agenti mentre eri via. Sfoglia le sessioni, ispeziona le chiamate di strumenti, rivedi dove le politiche hanno avuto effetto. + + Vedi cosa hanno fatto i tuoi agenti mentre eri via. Sfoglia le sessioni, ispeziona le chiamate di strumenti, controlla dove le politiche si sono attivate. - - Regola qualsiasi politica senza codice. Imposta allowlist, rami protetti o soglie per progetto o a livello globale. + + Regola qualsiasi politica senza scrivere codice. Imposta allowlist, rami protetti o soglie per progetto o globalmente. @@ -51,8 +51,8 @@ bun add -g failproofai ```bash -failproofai policies --install # abilita le politiche (oppure salta — `failproofai` ti offrirà di configurarle alla prima esecuzione) +failproofai policies --install # abilita le politiche (oppure salta — `failproofai` ti offrirà di configurarle al primo avvio) failproofai # avvia la dashboard ``` -Consulta la guida [Inizia](/it/getting-started) per la procedura dettagliata completa. \ No newline at end of file +Consulta la guida [Iniziare](/it/getting-started) per la procedura completa. \ No newline at end of file diff --git a/docs/it/package-aliases.mdx b/docs/it/package-aliases.mdx index 64dd3a36..f37102ec 100644 --- a/docs/it/package-aliases.mdx +++ b/docs/it/package-aliases.mdx @@ -10,7 +10,7 @@ Il package npm canonico è **`failproofai`**: ```bash npm install -g failproofai -# or +# oppure bun add -g failproofai ``` @@ -18,9 +18,9 @@ bun add -g failproofai ## Perché possediamo i nomi degli alias -Il typosquatting è un attacco comune alla supply chain in cui un attore malevolo registra un nome di package che dista un solo tasto da un package popolare. Gli utenti ignari che scrivono male il comando di installazione finiscono per eseguire codice controllato dall'attaccante con accesso completo al sistema - esattamente il tipo di minaccia che Failproof AI è progettato per difendere. +Il typosquatting è un attacco alla catena di fornitura comune in cui un malintenzionato registra un nome di package che dista un'unica pressione di tasto da un package popolare. Gli utenti ignari che commettono errori di digitazione nel comando di installazione finiscono per eseguire codice controllato dall'aggressore con accesso completo al sistema - esattamente il tipo di minaccia che Failproof AI è progettata per difendere. -Per eliminare questa superficie di attacco, **possediamo preventivamente tutte le comuni errate ortografie e varianti di formattazione** di `failproofai` su npm. Nessuno di questi nomi può essere registrato da terze parti. Ognuno di essi è un thin proxy che installa e delega al vero package `failproofai`. +Per eliminare questa superficie di attacco, **possediamo preventivamente tutte le comuni varianti di errori di digitazione e formattazione** di `failproofai` su npm. Nessuno di questi nomi può essere registrato da terzi. Ognuno è un semplice proxy che installa e delega al vero package `failproofai`. --- @@ -29,33 +29,33 @@ Per eliminare questa superficie di attacco, **possediamo preventivamente tutte l **Varianti di formattazione** - diversi modi di scrivere "failproof ai": | Package | Stato | -|---------|-------| +|---------|--------| | `failproof` | ✅ Pubblicato | -| `failproof-ai` | ⏳ In attesa di supporto npm | -| `fail-proof-ai` | ⏳ In attesa di supporto npm | -| `failproof_ai` | ⏳ In attesa di supporto npm | -| `fail_proof_ai` | ⏳ In attesa di supporto npm | -| `fail-proofai` | ⏳ In attesa di supporto npm | +| `failproof-ai` | ⏳ In attesa del supporto npm | +| `fail-proof-ai` | ⏳ In attesa del supporto npm | +| `failproof_ai` | ⏳ In attesa del supporto npm | +| `fail_proof_ai` | ⏳ In attesa del supporto npm | +| `fail-proofai` | ⏳ In attesa del supporto npm | **Errori di digitazione `failprof*`** - manca una `o` da "proof": | Package | Stato | -|---------|-------| +|---------|--------| | `failprof` | ✅ Pubblicato | | `failprof-ai` | ✅ Pubblicato | -| `failprofai` | ⏳ In attesa di supporto npm | -| `fail-prof-ai` | ⏳ In attesa di supporto npm | -| `failprof_ai` | ⏳ In attesa di supporto npm | +| `failprofai` | ⏳ In attesa del supporto npm | +| `fail-prof-ai` | ⏳ In attesa del supporto npm | +| `failprof_ai` | ⏳ In attesa del supporto npm | -**Errori di digitazione `faliproof*`** - `a` e `i` scambiate: +**Errori di digitazione `faliproof*`** - `a` e `i` invertite: | Package | Stato | -|---------|-------| +|---------|--------| | `faliproof` | ✅ Pubblicato | | `faliproof-ai` | ✅ Pubblicato | -| `faliproofai` | ⏳ In attesa di supporto npm | +| `faliproofai` | ⏳ In attesa del supporto npm | -> **Perché in attesa?** La politica di prevenzione dello spam di npm blocca i nomi che si normalizzano alla stessa stringa di un package esistente dopo aver rimosso la punteggiatura ed eseguito controlli di somiglianza. Abbiamo contattato il supporto npm per riservare questi nomi a scopo di anti-squatting. Saranno attivati una volta approvati. +> **Perché in sospeso?** La politica di prevenzione dello spam di npm blocca i nomi che si normalizzano alla stessa stringa di un package esistente dopo la rimozione della punteggiatura e i controlli di somiglianza. Abbiamo contattato il supporto npm per riservare questi nomi a scopo di anti-squatting. Verranno attivati una volta approvati. Puoi verificare che qualsiasi alias pubblicato sia di nostra proprietà: @@ -70,13 +70,13 @@ npm info failproof Ogni package alias: -1. Elenca `failproofai` come dipendenza - in modo che il package reale sia installato e il suo binary diventi disponibile -2. Espone un binary che corrisponde al proprio nome (ad es. `failprof-ai`) che reindirizzi tutti gli argomenti al binary `failproofai` +1. Elenca `failproofai` come dipendenza - quindi il vero package viene installato e il suo binario diventa disponibile +2. Espone un binario che corrisponde al proprio nome (ad es. `failprof-ai`) che proxy di tutti gli argomenti al binario `failproofai` -Il proxy è uno script Node di due righe; non c'è alcuna logica, nessuna chiamata di rete e nessuna raccolta di dati al di là di quello che fa `failproofai` stesso. +Il proxy è uno script Node di due righe; non c'è logica, nessuna chiamata di rete e nessuna raccolta di dati al di là di ciò che `failproofai` stesso fa. --- -## Se trovi un nome che abbiamo perso +## Se trovi un nome che abbiamo dimenticato -Apri un issue su [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) e lo registreremo. \ No newline at end of file +Apri una issue su [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) e la registreremo. \ No newline at end of file diff --git a/docs/it/testing.mdx b/docs/it/testing.mdx index f6c5d589..eb70820d 100644 --- a/docs/it/testing.mdx +++ b/docs/it/testing.mdx @@ -1,27 +1,26 @@ --- ---- title: Test -description: "Unit test, test end-to-end e test helper" +description: "Test unitari, test E2E e helper di test" icon: flask-vial --- -failproofai dispone di due suite di test: **unit test** (veloci, mockati) e **test end-to-end** (invocazioni reali di subprocess). +failproofai dispone di due suite di test: **test unitari** (veloci, con mock) e **test end-to-end** (invocazioni di subprocess reali). --- ## Esecuzione dei test ```bash -# Esegui tutti gli unit test una volta +# Eseguire tutti i test unitari una volta bun run test:run -# Esegui gli unit test in modalità watch +# Eseguire i test unitari in modalità watch bun run test -# Esegui i test E2E (richiede setup - vedi sotto) +# Eseguire i test E2E (richiede setup - vedi sotto) bun run test:e2e -# Verifica dei tipi senza compilazione +# Type-check senza build bunx tsc --noEmit # Lint @@ -30,22 +29,22 @@ bun run lint --- -## Unit test +## Test unitari -Gli unit test si trovano in `__tests__/` e utilizzano [Vitest](https://vitest.dev) con `jsdom`. +I test unitari si trovano in `__tests__/` e utilizzano [Vitest](https://vitest.dev) con `jsdom`. ```text __tests__/ hooks/ - builtin-policies.test.ts # Logica delle policy per ogni builtin - hooks-config.test.ts # Caricamento della config e merge dello scope - policy-evaluator.test.ts # Iniezione dei param e ordine di valutazione - custom-hooks-registry.test.ts # Aggiungi/ottieni/cancella dal registro globalThis - custom-hooks-loader.test.ts # Loader ESM, import transitivi, gestione errori + builtin-policies.test.ts # Logica di policy per ogni policy integrata + hooks-config.test.ts # Caricamento della configurazione e merge degli scope + policy-evaluator.test.ts # Iniezione di parametri e ordine di valutazione + custom-hooks-registry.test.ts # Registry di globalThis add/get/clear + custom-hooks-loader.test.ts # ESM loader, import transitivi, gestione degli errori manager.test.ts # Operazioni install/remove/list components/ - sessions-list.test.tsx # Componente lista sessioni - project-list.test.tsx # Componente lista progetti + sessions-list.test.tsx # Componente della lista di sessioni + project-list.test.tsx # Componente della lista di progetti ... lib/ logger.test.ts @@ -62,7 +61,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### Scrivere un unit test per una policy +### Scrivere un test unitario di una policy ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -111,11 +110,11 @@ describe("block-sudo", () => { ## Test end-to-end -I test E2E invocano il binario reale `failproofai` come subprocess, inviano un payload JSON a stdin e verificano l'output su stdout e il codice di uscita. Questo test l'intero percorso di integrazione che Claude Code utilizza. +I test E2E invocano il binario `failproofai` reale come subprocess, inviano un payload JSON a stdin e verificano l'output su stdout e il codice di uscita. Questo testa il percorso di integrazione completo utilizzato da Claude Code. ### Setup -I test E2E eseguono il binario direttamente dal sorgente del repository. Prima della prima esecuzione, compila il bundle CJS che i file di hook personalizzati utilizzano quando importano da `'failproofai'`: +I test E2E eseguono il binario direttamente dal codice sorgente del repository. Prima della prima esecuzione, crea il bundle CJS che i file di hook personalizzati utilizzano quando importano da `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -127,21 +126,21 @@ Quindi esegui i test: bun run test:e2e ``` -Ricompila `dist/` ogni volta che modifichi l'API hook pubblica (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, o `src/hooks/policy-types.ts`). +Ricostruisci `dist/` ogni volta che modifichi l'API pubblica dei hook (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, o `src/hooks/policy-types.ts`). -### Struttura dei test E2E +### Struttura del test E2E ```text __tests__/e2e/ helpers/ - hook-runner.ts # Spawn del binario, invio del payload JSON, cattura exit code + stdout + stderr - fixture-env.ts # Directory temporanee isolate per test con file di config - payloads.ts # Factory di payload accurati come Claude per ogni tipo di evento + hook-runner.ts # Genera il binario, invia il payload JSON, cattura il codice di uscita + stdout + stderr + fixture-env.ts # Directory temporanee isolate per test con file di configurazione + payloads.ts # Factory di payload accurati per ogni tipo di evento, come in Claude hooks/ - builtin-policies.e2e.test.ts # Ogni policy builtin con subprocess reale - custom-hooks.e2e.test.ts # Caricamento e valutazione degli hook personalizzati - config-scopes.e2e.test.ts # Merge della config tra project/local/global - policy-params.e2e.test.ts # Iniezione dei parametri per ogni policy parametrizzata + builtin-policies.e2e.test.ts # Ogni policy integrata con subprocess reale + custom-hooks.e2e.test.ts # Caricamento e valutazione di hook personalizzati + config-scopes.e2e.test.ts # Merge della configurazione tra project/local/global + policy-params.e2e.test.ts # Iniezione di parametri per ogni policy parametrizzata ``` ### Utilizzo degli helper E2E @@ -152,8 +151,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - directory temp; passalo come payload.cwd per caricare .failproofai/policies-config.json -// env.home - directory home isolata; nessuna perdita reale di ~/.failproofai +// env.cwd - directory temporanea; passa come payload.cwd per raccogliere .failproofai/policies-config.json +// env.home - home directory isolata; nessun vero ~/.failproofai trapela env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -163,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` registra automaticamente la pulizia di `afterEach`. +`createFixtureEnv()` registra la pulizia `afterEach` automaticamente. -**`runHook`** - invocare il binario: +**`runHook`** - invoca il binario: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -181,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - factory di payload pronti: +**`Payloads`** - factory di payload pronti all'uso: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -235,27 +234,27 @@ describe("block-rm-rf (E2E)", () => { ### Forme di risposta E2E | Decisione | Codice di uscita | 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 vuoto; motivo in stderr | | Allow | `0` | stringa vuota | -### Config di Vitest +### Configurazione di Vitest I test E2E utilizzano `vitest.config.e2e.mts` con: - `environment: "node"` - nessun global del browser necessario -- `pool: "forks"` - vera isolamento dei processi (i test eseguono subprocess) -- `testTimeout: 20_000` - 20s per test (avvio del binario + valutazione dell'hook) +- `pool: "forks"` - vera isolazione di processo (i test generano subprocess) +- `testTimeout: 20_000` - 20s per test (avvio del binario + valutazione del hook) -Il pool `forks` è importante: i worker basati su thread condividono `globalThis`, il che può interferire con i test che eseguono subprocess. I fork basati su processi evitano questo problema. +Il pool `forks` è importante: i worker basati su thread condividono `globalThis`, il che può interferire con i test che generano subprocess. I fork basati su processo evitano questo. --- ## CI -L'esecuzione completa di CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) deve superare i controlli prima del merge. La suite E2E viene eseguita come job CI separato in parallelo. +L'esecuzione CI completa (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) è richiesta prima della fusione. La suite E2E viene eseguita come un job CI separato in parallelo. -Vedi [Contributing](../CONTRIBUTING.md) per la checklist completa prima del merge. \ No newline at end of file +Vedi [Contributing](../CONTRIBUTING.md) per la checklist completa di pre-fusione. \ No newline at end of file diff --git a/docs/ja/agenteye/alerts.mdx b/docs/ja/agenteye/alerts.mdx index 846f2dca..9122fb8a 100644 --- a/docs/ja/agenteye/alerts.mdx +++ b/docs/ja/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "アラート" -description: "チームがすでに使っているチャンネルで、問題が閾値を超えた瞬間に通知を受け取りましょう。顧客からの報告で気づく前に。" +description: "チームがすでに使っているチャンネルに、問題が発生した瞬間に通知を届けましょう。顧客から報告される前に気づけます。" --- -チームがすでに使っているチャンネルで、問題が閾値を超えた瞬間に通知を受け取りましょう。顧客からの報告で気づく前に。ルールを一度設定するだけで、Failproof AI Observabilityがスケジュールに従ってチェックし、メール・Slack・webhook、またはダッシュボード上で通知します。 +チームがすでに使っているチャンネルに、問題が発生した瞬間に通知を届けましょう。顧客から報告される前に気づけます。ルールを一度設定するだけで、Failproof AI Observability がスケジュールに従って監視し、メール・Slack・webhook・ダッシュボード内のいずれかで通知します。 -![アラートページ：アラートルールのカードグリッド。それぞれトリガー、評価ウィンドウ、チャンネル、およびinfo・warning・criticalの重大度バッジを表示している](/agenteye/images/alerts.png) -*すべてのアラートルールを一目で確認：監視対象、確認頻度、通知先、緊急度。* +![アラートページ：アラートルールのカードグリッド。各カードにはトリガー、評価ウィンドウ、チャンネル、info・warning・critical の重大度バッジが表示されている](/agenteye/images/alerts.png) +*すべてのアラートルールを一覧で確認：監視対象、実行頻度、通知先、緊急度。* ## ユーザーより先に問題を把握する -回帰を見つけようとダッシュボードを何度もリロードするのはもうやめましょう。誰も見ていないときでも気づきたいシグナルにはアラートを設定し、普段いる場所に通知を届けましょう： +回帰を見逃さないようにダッシュボードを更新し続けるのはやめましょう。誰も見ていないときでも知りたいシグナルがあればアラートを設定し、すでに使っている場所に通知を届けましょう： -- **メール**：知らせるべき担当者へ。 -- **Slack**：インシデントに直接ジャンプするボタン付きのリッチメッセージ。 -- **Webhook**：PagerDuty・Opsgenie、または独自のエンドポイントへのJSON POSTリクエスト。受信側が信頼できるようオプションの署名付き。 -- **ダッシュボード内**：誰にも通知せずルールを調整したいときのための、静かな通知。 +- **メール**：担当者へ直接。 +- **Slack**：インシデントへ直接ジャンプできるボタン付きのリッチメッセージ。 +- **Webhook**：PagerDuty・Opsgenie・独自エンドポイント向けの JSON POST。受信側が信頼できるようオプションの署名付き。 +- **ダッシュボード内**：ルールを調整中で誰にも通知したくないときのための、控えめな通知。 -1つのルールに任意の組み合わせで通知先を設定でき、重大度（info・warning・critical）も合わせて通知されるため、緊急のものは一目でわかります。 +1 つのルールに任意の組み合わせで通知先を設定でき、重大度（info・warning・critical）も一緒に送られるため、緊急なものはそれとわかるようになります。 -## ルールはJSONでなくフォームで作る +## JSON ではなくフォームでルールを作成 -「壊れている」状態をフォームで記述すると、Failproof AI Observabilityが基盤となるルールを自動生成します。JSONの仕様はあくまでフォームが裏で生成するものなので、ルールを理解するために読むことはあっても、直接入力することはほとんどありません。 +「壊れている」とはどういう状態かをフォームで記述すると、Failproof AI Observability が内部ルールを自動生成します。JSON の仕様はフォームが裏側で生成するものなので、ルールを理解するために読むことはあっても、直接入力することはほとんどありません。 -![新規アラートフォーム：名前と説明、有効化トグル、およびmetric threshold・custom SQL・evaluation score・compound eval・per-eventの条件を選べるトリガーピッカー](/agenteye/images/alert-new.png) +![新規アラートフォーム：名前と説明、有効化トグル、メトリクスしきい値・カスタム SQL・評価スコア・複合評価・イベント単位などのトリガー選択肢](/agenteye/images/alert-new.png) *トリガーを選ぶとフォームが適切なフィールドに切り替わります。保存するとルールが書き込まれます。* -基本的な流れはシンプルです：名前を入力し、**トリガー**（監視対象）を選び、**閾値とウィンドウ**（どの程度悪化したら、どの期間で）を設定し、**チャンネル**を少なくとも1つ追加して、**保存**します。その後 **テスト** を実行して仮の通知を送信し、すべての送信先が正しく設定されていることを確認しましょう。裏ではこのような小さなスペックが生成されます： +基本的な手順はシンプルです：名前を付け、**トリガー**（監視対象）を選び、**しきい値とウィンドウ**（どの程度悪化したら、どの期間にわたって）を設定し、少なくとも 1 つの**チャンネル**を追加して**保存**します。その後**テスト**を実行して仮の通知を送信し、すべての通知先が正しく設定されているか確認しましょう。内部的には次のような小さな仕様が生成されます： ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -シグナルの種類は1つに限りません。障害をどう捉えるかに合わせてトリガーを選びましょう： +シグナルの種類は 1 つに限定されません。障害の捉え方に合ったトリガーを選んでください： | トリガー | 発火条件 | |---|---| -| **Metric threshold** | エラー率・p95/p99レイテンシ・イベント数やエラー数・トークン消費量などのプリセットメトリクスが、指定期間内に閾値を超えたとき | -| **Custom SQL** | 独自の読み取り専用クエリが行を返したとき、またはクエリで計算した値が閾値を超えたとき | -| **Evaluation score** | 評価スコア（例：ハルシネーション）の平均値が閾値を超えたとき | -| **Compound eval** | 複数のスコアチェックをany・all・at-least-Nロジックで組み合わせ、スコア全体にまたがる回帰を検出したいとき | -| **Per event** | 特定のエージェント・特定のエラー種別・メッセージの部分文字列など、条件に一致する単一イベントが発生したとき | +| **メトリクスしきい値** | エラー率・p95/p99 レイテンシ・イベント数やエラー数・トークン消費量などのプリセットメトリクスが、指定ウィンドウ内でしきい値を超えたとき | +| **カスタム SQL** | 独自の読み取り専用クエリが行を返したとき、またはクエリが計算した値がしきい値を超えたとき | +| **評価スコア** | 評価スコアの平均値（例：ハルシネーション）がしきい値を超えたとき | +| **複合評価** | 複数のスコアチェックを any・all・at-least-N のロジックで組み合わせ、複数のスコアにまたがる回帰を検出するとき | +| **イベント単位** | 特定のエージェント・エラーの種類・メッセージのサブ文字列に一致する単一のイベントが発生したとき | -[エラーページ](/ja/agenteye/error-tracking)で障害を確認している最中ですか？各行には **+ alert** ボタンがあり、クリックするとその障害を再発時にキャッチするための内容があらかじめ入力されたフォームが開きます。今トリアージしたインシデントが、次回自動で通知されるようになります。 +[エラーページ](/ja/agenteye/error-tracking)で障害を確認している最中ですか？各行には **+ アラート** ボタンがあり、その障害を次回キャッチするためのフォームが事前入力された状態で開きます。先ほどトリアージしたインシデントが、次回の通知対象になります。 -**場所：** アラートは `//alerts` にあります。ルールの作成・編集・削除・テストには **`alerts:write`** 権限が必要です。閲覧だけなら `alerts:read` で十分です。通知先ピッカーには組織のメンバーが名前で表示されるため、フォームを離れずに特定の担当者に通知できます。 +**場所：** アラートは `//alerts` にあります。ルールの作成・編集・削除・テストには **`alerts:write`** が必要です。閲覧だけなら `alerts:read` で十分です。通知先の選択肢にはメンバーが名前で表示されるため、フォームを離れずに担当者を指定できます。 -## 本当に問題なときだけ通知する +## 本当に問題のときだけ通知する -1回の悪い計測結果で起こされるのは避けたいものです。**M of N** ノイズフィルターは、アラートが実際に通知を送る前に、直近の何回のチェックのうち何回が失敗する必要があるかを制御します。**3 of 5** に設定すると、直近5回のチェックのうち3回が閾値を超えた場合にのみ発火するため、不安定なシグナルによる誤報を防げます。デフォルトの **1 of 1** のままにすれば、最初の閾値超過で即座に発火します。ルールの実行頻度も1m・5m・15m・1hのプリセットから選択でき、シグナルの変化速度に合わせて調整できます。 +1 回の異常な計測値で起こされたくはないはずです。**M of N** ノイズフィルターは、実際にアラートを発火させるために、直近のいくつかのチェックのうち何回失敗する必要があるかを制御します。**3 of 5** に設定すると、直近 5 回のチェックのうち 3 回違反した場合にのみルールが発火するため、不安定なシグナルによる誤報を防ぎます。デフォルトの **1 of 1** のままにすると、最初の違反で即座に発火します。ルールの実行頻度も 1m・5m・15m・1h のプリセットから選択でき、シグナルの変化速度に合わせて設定できます。 ## アラートが発火したときの動作 -閾値超過が発生すると**インシデント**が開かれ、チャンネルへの通知が1回送信されます。その後チームは確認・担当者のアサイン・議論・解決を行い、すべてがクリーンな記録として残ります。このトリアージワークフローには専用の場所があります：[インシデント](/ja/agenteye/incidents)をご覧ください。 +違反が発生すると**インシデント**が作成され、通知先に 1 回通知されます。その後チームは確認・担当者割り当て・議論・解決と進め、すべてクリーンで帰属情報付きの記録として残ります。このトリアージワークフローには専用のページがあります：[インシデント](/ja/agenteye/incidents)を参照してください。 ## 関連情報 - [インシデント](/ja/agenteye/incidents)：発火したアラートをオープンから確認済み・解決済みまで追跡する。 - [エラートラッキング](/ja/agenteye/error-tracking)：エージェントの障害をグループ化し、ワンクリックでアラートに昇格させる。 -- [ダッシュボード](/ja/agenteye/dashboards)：アラートの閾値の基となる共有ボードを監視する。 -- [CLIとエージェント](/ja/agenteye/cli-and-agents)：ターミナルからアラートの作成やインシデントの確認を行う、またはCIにスクリプトとして組み込む。 \ No newline at end of file +- [ダッシュボード](/ja/agenteye/dashboards)：アラートのしきい値の元となる共有ボードを確認する。 +- [CLI とエージェント](/ja/agenteye/cli-and-agents)：ターミナルからアラートを作成したりインシデントを確認したり、CI にスクリプトとして組み込む。 \ No newline at end of file diff --git a/docs/ja/agenteye/api-keys.mdx b/docs/ja/agenteye/api-keys.mdx index 5bcce8de..a1c0aa9e 100644 --- a/docs/ja/agenteye/api-keys.mdx +++ b/docs/ja/agenteye/api-keys.mdx @@ -1,165 +1,165 @@ --- title: "APIキー" -description: "APIキーはFailproof AI Observabilityサーバーへのアクセスを制御し、コレクターが読み取り権限や管理者権限を持つことなくイベントを送信できるようにします。" +description: "APIキーは、Failproof AI Observabilityサーバーへのアクセスを管理します。コレクターは読み取り権限や管理者権限を持たずにイベントを送信できます。" --- -APIキーはFailproof AI Observabilityサーバーへのアクセスを制御し、コレクターが読み取り権限や管理者権限を持つことなくイベントを送信できるようにします。各キーには1つ以上のパーミッションが付与されており、各パーミッションは特定のサーバールートへのアクセスを制限します。必要な最小限のパーミッションのみを付与してください。ほとんどのデプロイメントでは、3種類のキーを作成するだけで十分です。 +APIキーは、Failproof AI Observabilityサーバーへのアクセスを管理します。コレクターは読み取り権限や管理者権限を持たずにイベントを送信できます。各キーには1つ以上のパーミッションが付与されており、それぞれのパーミッションが特定のサーバールートへのアクセスを制御します。必要な最小限のパーミッションのみを付与してください。ほとんどのデプロイメントでは、3種類のキーを作成するだけで十分です。 ## ほとんどのデプロイメントで必要な3つのキー | キー | パーミッション | 使用者 | |---|---|---| -| コレクターキー | `events:add` | 各エージェントマシン上の`agenteye-collector`がイベントを送信するために使用。 | -| ダッシュボード読み取りキー | `events:read`、`keys:read` | データを変更せずにクエリを実行する読み取り専用のオペレーターまたは連携サービス。 | -| ブートストラップ管理者キー | すべてのパーミッション | インスタンスを最初に起動するオペレーター（およびダッシュボード）。`ADMIN_KEY`環境変数からシードされます。[ブートストラップ管理者キー](#bootstrap-admin-key)を参照してください。 | +| コレクターキー | `events:add` | 各エージェントマシン上の`agenteye-collector`（イベント送信用） | +| ダッシュボード読み取りキー | `events:read`、`keys:read` | データを変更せずにクエリを実行する読み取り専用オペレーターまたはインテグレーション | +| ブートストラップ管理者キー | すべてのパーミッション | インスタンスを初めて立ち上げるオペレーター（ダッシュボードも含む）。`ADMIN_KEY`環境変数からシードされます。[ブートストラップ管理者キー](#bootstrap-admin-key)を参照してください。 | -まずここから始めてください。より細かいカスタムスコープのキーが必要な場合のみ、以下の完全なパーミッションカタログを参照してください。[推奨キーレイアウト](#recommended-key-layout)および[キーの作成](#creating-keys)も参照してください。 +まずここから始めてください。より細かいカスタムスコープのキーが必要な場合のみ、以下のパーミッションカタログを参照してください。[推奨キー構成](#recommended-key-layout)と[キーの作成](#creating-keys)も参照してください。 --- ## パーミッション -サーバーは固定のパーミッションカタログを強制します。各パーミッションは特定のHTTPルートへのアクセスを制限します。**管理者キー**はすべてのパーミッションを持ち、スコープ付きキーは作成時に付与したサブセットのみを持ちます。不明なパーミッション文字列はキー作成時に拒否されます。 +サーバーは固定のパーミッションカタログを適用します。各パーミッションは特定のHTTPルートへのアクセスを制御します。**管理者キー**はすべてのパーミッションを持ち、スコープ付きキーは作成時に付与したサブセットのみを持ちます。不明なパーミッション文字列はキー作成時に拒否されます。 -> **注意:** 2つの有効なパーミッションは人間/ダッシュボード専用であり、APIキーには付与できません: `orgs:admin`（インスタンス管理、オペレーター専用）と`keys:update`です。どちらかを付与しようとする`POST /keys`または`PATCH /keys/:id`リクエストはHTTP 422で拒否されます。ベアラーキーがキーを作成できても編集できない理由については、以下の`keys:update`の行を参照してください。 +> **注意:** 2つの有効なパーミッションは人間/ダッシュボード専用であり、APIキーに付与できません: `orgs:admin`（インスタンス管理、オペレーター専用）と`keys:update`です。いずれかを付与しようとする`POST /keys`または`PATCH /keys/:id`へのリクエストはHTTP 422で拒否されます。Bearerキーがキーを作成できるが編集はできない理由については、`keys:update`の行を参照してください。 ### イベントの取り込みとクエリ | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `events:add` | `POST /events` | コレクターからイベントのバッチを取り込みます。コレクターに必要な唯一のパーミッションです。 | -| `events:read` | `GET /events`、`GET /events/latency_aggregate`、`GET /events/environments`、`GET /events/models`、`GET /sessions/:session_id/export` | イベントのクエリ、既知の環境の一覧表示、データに含まれるモデル識別子の一覧表示（モデルビューとモデルフィルターで使用）、ヒートマップ/パーセンタイルバンドを構成するレイテンシ集計の計算、セッションのJSONLとしてのエクスポート。共有フィルターバーファセットエンドポイント`GET /events/environments`および`GET /events/agent_ids`は`events:read`**または**`evaluations:read`のどちらでもアクセス可能であるため、セッションページ（`evaluations:read`でゲート）は同じorg別ファセットを再利用できます。`GET /events/models`はこれに含まれません: `events:read`が必要であり、`evaluations:read`のみを持つプリンシパルは403を受け取ります。 | +| `events:add` | `POST /events` | コレクターからイベントのバッチを取り込む。コレクターに必要な唯一のパーミッション。 | +| `events:read` | `GET /events`、`GET /events/latency_aggregate`、`GET /events/environments`、`GET /events/models`、`GET /sessions/:session_id/export` | イベントのクエリ、既知の環境の一覧表示、データで確認されたモデル識別子の一覧表示（モデルビューとモデルフィルターで使用）、ヒートマップ/パーセンタイルバンドを動かすレイテンシ集計の計算、セッションのJSONLエクスポート。共有フィルターバーのファセットエンドポイント`GET /events/environments`と`GET /events/agent_ids`は`events:read`**または**`evaluations:read`のいずれかで到達可能です。セッションページ（`evaluations:read`でゲート）は同じper-orgファセットを再利用します。`GET /events/models`はそれらの1つではありません: `events:read`が必要であり、`evaluations:read`のみを持つプリンシパルは403を受け取ります。 | ### セッションと評価 | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `evaluations:read` | `GET /sessions`、`GET /evaluations`、`GET /evaluations/aggregate`、`GET /evaluations/environments`、`GET /evaluation-jobs` | セッションの一覧表示、評価結果の読み取り、ダッシュボードで使用される集計済みeval健全性、評価ジョブワーカーキューの状態。 | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | 完了したセッションの再評価を手動でキューに追加します。 | +| `evaluations:read` | `GET /sessions`、`GET /evaluations`、`GET /evaluations/aggregate`、`GET /evaluations/environments`、`GET /evaluation-jobs` | セッションの一覧表示、評価結果の読み取り、ダッシュボードで使用される評価ヘルスのロールアップ、評価ジョブワーカーキューの状態確認。 | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | 完了したセッションの再評価を手動でキューに追加する。 | ### ダッシュボード | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `dashboards:read` | `GET /dashboards`、`GET /dashboards/:id`、`GET /dashboards/:id/tiles` | ダッシュボードの一覧表示、読み込み、タイルの読み取り。 | -| `dashboards:write` | `POST /dashboards`、`PUT /dashboards/:id`、`POST /dashboards/:id/tiles`、`PUT /dashboards/:id/tiles/:tile_id`、`DELETE /dashboards/:id/tiles/:tile_id`、`PUT /dashboards/:id/tiles/layout` | ダッシュボードの作成と編集、タイルの追加/編集/削除、タイルグリッドの並べ替え。 | +| `dashboards:read` | `GET /dashboards`、`GET /dashboards/:id`、`GET /dashboards/:id/tiles` | ダッシュボードの一覧表示、個別ダッシュボードの読み込み、タイルの読み取り。 | +| `dashboards:write` | `POST /dashboards`、`PUT /dashboards/:id`、`POST /dashboards/:id/tiles`、`PUT /dashboards/:id/tiles/:tile_id`、`DELETE /dashboards/:id/tiles/:tile_id`、`PUT /dashboards/:id/tiles/layout` | ダッシュボードの作成・編集、タイルの追加・編集・削除、タイルグリッドの並び替え。 | | `dashboards:delete` | `DELETE /dashboards/:id` | ダッシュボード全体の削除（タイルレベルの削除は`dashboards:write`に含まれます）。 | ### 保存済みクエリ（SQLコンポーザー） | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `queries:read` | `GET /queries`、`GET /queries/:id`、`GET /queries/schema` | 保存済みクエリの一覧表示、読み込み、コンポーザーが対象とする読み取り専用スキーマの確認。 | -| `queries:write` | `POST /queries`、`PUT /queries/:id` | 保存済みクエリの作成と編集。SQLは`queries:run`呼び出しと同様に、同じ読み取り専用ロールとガードされたSQLチェックを通じてルーティングされます。 | +| `queries:read` | `GET /queries`、`GET /queries/:id`、`GET /queries/schema` | 保存済みクエリの一覧表示、個別クエリの読み込み、コンポーザーが対象とする読み取り専用スキーマの確認。 | +| `queries:write` | `POST /queries`、`PUT /queries/:id` | 保存済みクエリの作成・編集。SQLは`queries:run`呼び出しと同じ読み取り専用ロールおよびガードされたSQLチェックを通過します。 | | `queries:delete` | `DELETE /queries/:id` | 保存済みクエリの削除。 | -| `queries:run` | `POST /queries/run` | コンポーザーが使用する読み取り専用ロールに対して、保存済みまたはアドホックSQLを実行します。 | +| `queries:run` | `POST /queries/run` | コンポーザーが使用する読み取り専用ロールに対して保存済みまたはアドホックSQLを実行する。 | ### AIアシスタント | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `agent:use` | `GET /agent/conversations`、`POST /agent/conversations`、`GET /agent/conversations/:id`、`PATCH /agent/conversations/:id`、`DELETE /agent/conversations/:id`、`PUT /agent/conversations/:id/messages` | AIアシスタントとの会話と、自分自身の（プライベートな）会話の管理。アシスタントドックを表示するには**ユーザー**に必要です。アシスタント自身のキーは`dashboard-assistant`であり、別途シードされます（以下を参照）。 | +| `agent:use` | `GET /agent/conversations`、`POST /agent/conversations`、`GET /agent/conversations/:id`、`PATCH /agent/conversations/:id`、`DELETE /agent/conversations/:id`、`PUT /agent/conversations/:id/messages` | AIアシスタントとの会話および自分の（プライベートな）会話の管理。アシスタントドックを表示するには**ユーザー**に必要です。アシスタント自身のキーは`dashboard-assistant`であり、別途シードされます（以下を参照）。 | ### APIキー | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `keys:create` | `POST /keys` | 新しいスコープ付きAPIキーを作成します。既存キーのパーミッション編集は**含まれません**（それは`keys:update`です）。 | -| `keys:read` | `GET /keys` | 既存キーの一覧表示。シークレットはこのエンドポイントでは返されません。 | -| `keys:update` | `PATCH /keys/:id` | 既存キーのパーミッションを編集します。**人間/ダッシュボード専用**のパーミッションであり、APIキーには割り当てられません（ベアラーキーはキーを作成できますが、編集はできません）。 | -| `keys:disable` | `POST /keys/:id/disable` | キーを無効化します。保護されたキー（`admin`、`dashboard-assistant`）は無効化できません。これらは環境変数の変更と再起動によってローテートしてください。 | -| `keys:regenerate` | `POST /keys/:id/regenerate` | キーのシークレットをローテートします。保護されたキーはこのルートから再生成できません。 | +| `keys:create` | `POST /keys` | 新しいスコープ付きAPIキーの作成。既存キーのパーミッション編集は**含みません**（それは`keys:update`です）。 | +| `keys:read` | `GET /keys` | 既存キーの一覧表示。このエンドポイントでシークレットは返されません。 | +| `keys:update` | `PATCH /keys/:id` | 既存キーのパーミッション編集。**人間/ダッシュボード専用**パーミッションであり、APIキーに割り当てることはできません（Bearerキーはキーを作成できますが、編集はできません）。 | +| `keys:disable` | `POST /keys/:id/disable` | キーの無効化。保護されたキー（`admin`、`dashboard-assistant`）は無効化できません。環境変数の変更と再起動でローテーションしてください。 | +| `keys:regenerate` | `POST /keys/:id/regenerate` | キーのシークレットのローテーション。保護されたキーはこのルートで再生成できません。 | ### ダッシュボードユーザー | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `users:create` | `POST /users`、`GET /users/defaults` | 新しいダッシュボードユーザーの招待（メール＋ワンタイムパスコード（OTP）ログインの発行）と、招待フォームのシードに使用するダッシュボード設定のデフォルトパーミッションセットの読み取り。 | -| `users:read` | `GET /users`、`GET /users/:id` | ユーザーの一覧表示と単一ユーザーレコードの読み込み。 | -| `users:update` | `PUT /users/:id` | ユーザーのパーミッションを編集します。更新時に対象ユーザーへパーミッション変更メールが送信され、次回リクエスト時に有効になります。再ログインは不要です。 | -| `users:delete` | `DELETE /users/:id`、`POST /users/:id/enable` | ユーザーの無効化（セッションを即時失効）と、以前に無効化されたユーザーの再有効化。 | +| `users:create` | `POST /users`、`GET /users/defaults` | 新しいダッシュボードユーザーの招待（メール＋ワンタイムパスコード（OTP）ログインを発行）と、招待フォームのシードに使用するダッシュボード設定のデフォルトパーミッションセットの読み取り。 | +| `users:read` | `GET /users`、`GET /users/:id` | ユーザーの一覧表示と個別ユーザーレコードの読み込み。 | +| `users:update` | `PUT /users/:id` | ユーザーのパーミッション編集。更新時に対象ユーザーへパーミッション変更メールが送信され、次回リクエスト時から有効になります。再ログインは不要です。 | +| `users:delete` | `DELETE /users/:id`、`POST /users/:id/enable` | ユーザーの無効化（セッションを即座に取り消す）および無効化されたユーザーの再有効化。 | -これらのパーミッションはダッシュボードの**Users**ページを支援しており、各メンバーに付与されたスコープがチップとして表示されます: +これらのパーミッションはダッシュボードの**ユーザー**ページを支えており、各メンバーに付与されたスコープがチップとして表示されます。 -![Usersページ: 各ダッシュボードユーザーのカード（メール、付与されたパーミッション、編集/無効化コントロール）](/agenteye/images/users.png) +![ユーザーページ: ダッシュボードユーザーごとのカードにメール、付与されたパーミッション、編集/無効化コントロールが表示される](/agenteye/images/users.png) ### 運用設定 | パーミッション | HTTPルート | 許可される操作 | |---|---|---| | `settings:read` | `GET /settings`、`GET /settings/schema`、`GET /settings/model-context-windows`、`GET /settings/model-context-windows/resolve` | ダッシュボード管理の運用設定とそのメタデータの表示、モデルごとのコンテキストウィンドウオーバーライドの一覧表示、モデルの有効なウィンドウの解決。 | -| `settings:write` | `PUT /settings/:key`、`PUT /settings/model-context-windows`、`DELETE /settings/model-context-windows` | 運用設定の編集と、モデルごとのコンテキストウィンドウオーバーライドの追加/変更/削除。変更はサーバーを再起動せずに新しいイベントに反映されます。 | +| `settings:write` | `PUT /settings/:key`、`PUT /settings/model-context-windows`、`DELETE /settings/model-context-windows` | 運用設定の編集、モデルごとのコンテキストウィンドウオーバーライドの追加・変更・削除。変更はサーバーを再起動せずに新しいイベントに適用されます。 | -![Settingsページ: 許可されたサインインやセッション/OTP有効期間などのダッシュボード管理の運用設定（再起動なしで編集可能）](/agenteye/images/settings.png) +![設定ページ: 許可されたサインインやセッション/OTPライフタイムなど、再起動なしで編集可能なダッシュボード管理の運用設定](/agenteye/images/settings.png) ### アラートとインシデント | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `alerts:read` | `GET /alerts`、`GET /alerts/:id` | 設定されたアラート定義の表示。 | -| `alerts:write` | `POST /alerts`、`PUT /alerts/:id`、`DELETE /alerts/:id`、`POST /alerts/:id/test` | アラート定義の作成、編集、削除、テスト発火。 | -| `incidents:read` | `GET /alerts/incidents`、`GET /alerts/incidents/:iid`、`GET /alerts/incidents/:iid/comments`、`GET /alerts/incidents/:iid/subscribers` | インシデントとトリアージ履歴の表示。 | -| `incidents:write` | `POST /alerts/:id/incidents` | 既存のアラートに対して手動でインシデントを開始します。 | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`、`POST /alerts/incidents/:iid/assign`、`POST /alerts/incidents/:iid/resolve`、`POST /alerts/incidents/:iid/comments`、`POST /alerts/incidents/:iid/subscribe`、`POST /alerts/incidents/:iid/unsubscribe` | インシデントの確認、担当割り当て、解決、コメント。 | +| `alerts:read` | `GET /alerts`、`GET /alerts/:id` | 設定済みアラート定義の表示。 | +| `alerts:write` | `POST /alerts`、`PUT /alerts/:id`、`DELETE /alerts/:id`、`POST /alerts/:id/test` | アラート定義の作成・編集・削除・テスト発火。 | +| `incidents:read` | `GET /alerts/incidents`、`GET /alerts/incidents/:iid`、`GET /alerts/incidents/:iid/comments`、`GET /alerts/incidents/:iid/subscribers` | インシデントとそのトリアージ履歴の表示。 | +| `incidents:write` | `POST /alerts/:id/incidents` | 既存のアラートに対して手動でインシデントを開く。 | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`、`POST /alerts/incidents/:iid/assign`、`POST /alerts/incidents/:iid/resolve`、`POST /alerts/incidents/:iid/comments`、`POST /alerts/incidents/:iid/subscribe`、`POST /alerts/incidents/:iid/unsubscribe` | インシデントの確認、割り当て、解決、コメント追加。 | ### 監査 | パーミッション | HTTPルート | 許可される操作 | |---|---|---| -| `audits:read` | `GET /audits`、`GET /audits/:id`、`GET /audits/:id/runs`、`GET /audits/findings`、`GET /audits/findings/:fid` | 監査定義、実行履歴、所見の表示。 | -| `audits:write` | `POST /audits`、`PUT /audits/:id`、`DELETE /audits/:id`、`POST /audits/:id/run`、`POST /audits/findings/:fid/status` | 監査の作成、編集、削除、実行、所見のトリアージ（確認/ミュート/却下/解決/再オープン/割り当て）。 | +| `audits:read` | `GET /audits`、`GET /audits/:id`、`GET /audits/:id/runs`、`GET /audits/findings`、`GET /audits/findings/:fid` | 監査定義、実行履歴、調査結果の表示。 | +| `audits:write` | `POST /audits`、`PUT /audits/:id`、`DELETE /audits/:id`、`POST /audits/:id/run`、`POST /audits/findings/:fid/status` | 監査の作成・編集・削除・実行、調査結果のトリアージ（確認/ミュート/却下/解決/再開/割り当て）。 | -> **注意:** キーに監査機能を付与するには、`audits:*`を明示的に付与してください。Auditsが追加されたときに既存の付与者がどのように移行されたかについては、[アップグレードと後方互換性に関する注記](#upgrade-and-backward-compatibility-notes)を参照してください。 +> **注意:** キーに監査サーフェスを付与するには、`audits:*`を明示的に付与してください。監査機能がリリースされた際の既存ユーザーの移行方法については、[アップグレードと後方互換性に関する注記](#upgrade-and-backward-compatibility-notes)を参照してください。 -> 受信者ピッカーエンドポイント`GET /alerts/recipients`（アラート編集者が通知できるメンバーのメール一覧を取得）は`alerts:read`**または**`alerts:write`のいずれかを持つユーザーがアクセス可能であるため、アラート編集者は`users:read`を付与されなくてもピッカーにデータを入力できます。 +> 受信者ピッカーエンドポイント`GET /alerts/recipients`（アラートエディターが通知できるメンバーメールの一覧）は`alerts:read`**または**`alerts:write`のいずれかのホルダーから到達可能です。アラートエディターは`users:read`を付与されなくてもピッカーを利用できます。 -> ダッシュボードビューワーには`dashboards:read`（保存済みビューの読み込み）と`evaluations:read`（ヘルスメトリクスは評価データから計算）の**両方**が必要です。ダッシュボードの作成や編集を許可するには`dashboards:write`を、削除を許可するには`dashboards:delete`を付与してください。 +> ダッシュボードビューアーには`dashboards:read`（保存済みビューの読み込み）と`evaluations:read`（ヘルスメトリクスは評価データから計算）の**両方**が必要です。ダッシュボードの作成・編集には`dashboards:write`を、削除には`dashboards:delete`を付与してください。 -> `/health`と`/auth/*`（OTPリクエスト、OTP検証、セッション確認、ログアウト）は設計上、認証不要です。これらはログインフローと生存確認プローブです。`GET /access-granters`は有効なキーが必要ですが、特定のパーミッションは不要であるため、ログイン済みのすべてのユーザーがアクセス変更について連絡すべき管理者を確認できます。 +> `/health`と`/auth/*`（OTPリクエスト、OTP検証、セッション確認、ログアウト）は設計上認証不要です。これらはログインフローと稼働確認プローブです。`GET /access-granters`は有効なキーが必要ですが特定のパーミッションは不要なので、ログイン済みのすべてのユーザーがアクセス変更について連絡すべき管理者を確認できます。 --- ## パーミッションセット -パーミッションセットを使用すると、毎回個別のトークンを手作業で選択する代わりに、名前付きロールを適用できます。新しいダッシュボードユーザーやAPIキーごとに十数個のパーミッションを1つずつ選択する代わりに、セットを選択することで、割り当てられた全員が一貫した、確認可能な付与を受けます。カスタムセットを編集すると、既にそれに割り当てられているすべてのユーザーに新しい付与が再適用されるため、ロール変更は1回の編集で完了し、全メンバーを個別に更新する必要がありません。 +パーミッションセットを使用すると、毎回個別のトークンを手動で選択する代わりに、名前付きロールを適用できます。新しいダッシュボードユーザーやAPIキーのために毎回十数個のパーミッションを1つずつ選択する必要はなく、セットを選択するだけで、割り当てられた全員が一貫したレビュー可能な権限を持ちます。カスタムセットを編集すると、すでに割り当てられているすべてのユーザーに新しい権限が再適用されるため、ロール変更は全メンバーを個別に変更する手間なく1回の編集で完了します。 -すべてのオーガナイゼーションには3つの組み込みセットが初期設定されています: +すべての組織には3つの組み込みセットがシードされています。 -| セット | パーミッション | 対象 | +| セット | パーミッション | 対象者 | |---|---|---| -| `read-only` | `events:read`、`keys:read`、`users:read`、`evaluations:read`、`dashboards:read`、`queries:read`、`settings:read`、`alerts:read`、`audits:read`、`incidents:read` | すべての運用機能への読み取り専用アクセス。 | -| `standard` | `read-only`のすべて、加えて`evaluations:trigger`、`queries:run`、`incidents:ack`、`agent:use` | 読み取り専用に加えて、日常的なオンコール操作: クエリの実行、セッションの再評価、インシデントの確認、AIアシスタントの使用。 | -| `admin` | 割り当て可能なすべてのパーミッション | orgの完全な制御。 | +| `read-only` | `events:read`、`keys:read`、`users:read`、`evaluations:read`、`dashboards:read`、`queries:read`、`settings:read`、`alerts:read`、`audits:read`、`incidents:read` | すべての運用サーフェスへの表示専用アクセス。 | +| `standard` | `read-only`のすべてに加えて`evaluations:trigger`、`queries:run`、`incidents:ack`、`agent:use` | 読み取り専用に加えて、オンコール担当者の日常的な操作（クエリの実行、セッションの再評価、インシデントの確認、AIアシスタントの使用）。 | +| `admin` | 割り当て可能なすべてのパーミッション | 組織の完全な管理権限。 | -3つの組み込みセットは**変更不可**です。その名前は常に同じ意味を持つため、`read-only`、`standard`、`admin`はポリシーやオンボーディングで安全に参照できます。オペレーターはオーガナイゼーション固有のロールをモデル化するために追加の**カスタムセット**を作成できます（例: 「ダッシュボード作成者」ロールや「コレクターのみ」ロール）。 +3つの組み込みセットは**変更不可**です。`read-only`、`standard`、`admin`の名前は常に同じ意味を持つため、ポリシーやオンボーディングで安全に参照できます。オペレーターは組織固有のロールをモデル化するための追加**カスタムセット**を作成できます（例: 「ダッシュボード作成者」ロールや「コレクター専用」ロール）。 -セットはダッシュボードに表示され、`GET /permission-sets`（一覧、`users:read`でゲート）および`POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name`（カスタムセットの作成、編集、削除、`settings:write`でゲート）のAPIを通じて管理されます。組み込みセットの削除や編集は拒否されます。 +セットはダッシュボードに表示され、APIを通じて管理されます: `GET /permission-sets`（一覧表示、`users:read`でゲート）、`POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name`（カスタムセットの作成・編集・削除、`settings:write`でゲート）。組み込みセットの削除または編集は拒否されます。 -セットメンバーシップは他の2つの機能を支援します: +セットのメンバーシップは他の2つの機能を支えています: -- **`DEFAULT_USER_PERMISSIONS`**（管理者が**+ new user**を開いたときに事前選択される付与）はデフォルトで`standard`セットになります。 -- **`agenteye-orgctl`の`--set`フラグ**（オペレーターメンバー管理）は名前付きセットからメンバーを開始し、その後`--add` / `--remove`で微調整します。 +- **`DEFAULT_USER_PERMISSIONS`**（管理者が**+ 新しいユーザー**を開いたときに事前選択される権限）はデフォルトで`standard`セットになります。 +- **`agenteye-orgctl`の`--set`フラグ**（オペレーターメンバー管理）は名前付きセットからメンバーを開始し、`--add` / `--remove`で細かく調整できます。 -> **注意:** セットにキーに割り当て不可能なパーミッションが含まれている場合（例: `keys:update`を含むカスタムセット）、そのセットからキーをシードすると、割り当て不可能なトークンが除外されます。除外しない場合、サーバーはHTTP 422でキーを拒否します。ダッシュボードユーザーにはこの制限は適用されません。 +> **注意:** セットにキーに割り当て不可能なパーミッション（例: `keys:update`を含むカスタムセット）が含まれている場合、そのセットからキーをシードすると、割り当て不可能なトークンは除外されます。サーバーは通常HTTP 422でキーを拒否します。ダッシュボードユーザーにはこの制限は適用されません。 --- ## ブートストラップ管理者キー -管理者キーは、オペレーターがゼロからアクセスを構築するための単一のルート認証情報です。このキーを使用して、他のすべてのスコープ付きキーを発行し、最初のダッシュボードユーザーを招待し、他のキーが存在する前にインスタンスを設定できます。これはkeys APIを通じて作成しない唯一のキーです。サーバーが最初の起動時にアクセス可能になるよう、環境からプロビジョニングされます。 +管理者キーは、オペレーターがゼロからアクセスを立ち上げるための唯一のルートクレデンシャルです。このキーを使用して、他のすべてのスコープ付きキーの発行、最初のダッシュボードユーザーの招待、他のキーが存在する前のインスタンス設定が可能です。キーAPIを通じて作成しない唯一のキーであり、サーバーが最初の起動時に到達可能になるよう環境からプロビジョニングされます。 -サーバーで`ADMIN_KEY`環境変数を設定してください。起動のたびに、サーバーはこの値をすべてのパーミッションを持つ管理者キーとしてアップサートします。 +サーバーに`ADMIN_KEY`環境変数を設定してください。起動のたびに、サーバーはこの値をすべてのパーミッションを持つ管理者キーとしてアップサートします。 -ローテートするには: `ADMIN_KEY`を新しいシークレットに変更してサーバーを再起動します。 +ローテーションするには: `ADMIN_KEY`を新しいシークレットに変更してサーバーを再起動してください。 --- -## オーガナイゼーションスコープ +## 組織スコーピング -**オーガナイゼーション自体は、このkeys APIではなく、オペレーターによってアウトオブバンドで作成・管理されます。** orgとメンバーのライフサイクル（orgの作成/名前変更/削除/パージ、メンバーの追加/更新/削除）は**`agenteye-orgctl`** CLIで行います。これに対するHTTP APIやダッシュボードのボタンはありません。**変わらないのは、org別APIキーは依然としてダッシュボード（またはこのkeys API経由）でorgメンバーによって発行される**という点です。 +**組織自体はオペレーターがアウトオブバンドで作成・管理します。このキーAPIを通じて行うものではありません。** 組織とメンバーのライフサイクル（組織の作成/名前変更/削除/パージ、メンバーの追加/更新/削除）は**`agenteye-orgctl`** CLIで行います。HTTPAPIやダッシュボードのボタンはありません。**変わらない点: per-org APIキーは引き続きダッシュボード（またはこのキーAPI経由）で組織メンバーが発行します。** -マルチorgデプロイメントでは、orgメンバーが（このkeys APIまたはダッシュボードの**Keys**ページから）作成するすべてのキーは**1つのオーガナイゼーション**に属し、そのorgのデータのみを読み書きできます。orgはキー作成時にスタンプされ、すべてのリクエストで強制されます。2つのブートストラップキーのみが例外です: `admin`キー（`ADMIN_KEY`からシード）と`dashboard-assistant`キー（`AGENT_API_KEY`からシード）は**インスタンススコープ**です（orgを持ちません）。ダッシュボードは`admin`キーで認証し、サインイン済みメンバーの代わりにorg別リクエストをプロキシします。シングルテナントデプロイメントではこれを意識する必要はありません。すべてのキーは組み込みの`default` orgに属します。 +マルチorg デプロイメントでは、組織メンバーが作成するすべてのキー（このキーAPIまたはダッシュボードの**キー**ページ経由）は**1つの組織**に属し、その組織のデータのみを読み書きできます。組織はキー作成時にスタンプされ、すべてのリクエストで適用されます。2つのブートストラップキーのみが例外です: `admin`キー（`ADMIN_KEY`からシード）と`dashboard-assistant`キー（`AGENT_API_KEY`からシード）は**インスタンススコープ**です（組織を持ちません）。ダッシュボードは`admin`キーで認証し、サインイン済みメンバーの代わりにper-orgリクエストをプロキシします。シングルテナントのデプロイメントではこれを意識する必要はありません。すべてのキーは組み込みの`default`組織に属します。 --- @@ -167,7 +167,7 @@ APIキーはFailproof AI Observabilityサーバーへのアクセスを制御し 管理者キー（または`keys:create`パーミッションを持つキー）を使用して、追加のスコープ付きキーを作成します。 -### コレクターキー（取り込みのみ） +### コレクターキー（取り込み専用） ```bash curl -s -X POST http://your-server/keys \ @@ -180,7 +180,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### ダッシュボードキー（読み取りのみ） +### ダッシュボードキー（読み取り専用） ```bash curl -s -X POST http://your-server/keys \ @@ -193,7 +193,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -HTTP APIでキーを作成する場合、`key`の値は自分で指定します。強力なシークレットを選択し、安全に保管してください。（ダッシュボードは逆の動作をします: 強力なシークレットを生成し、作成時に一度だけ表示します。[ダッシュボードでのキー管理](#key-management-in-the-dashboard)を参照してください。）レスポンスでキーが作成されたことを確認できます: +HTTP API経由でキーを作成する場合、`key`の値は自分で指定します。強力なシークレットを選択し、安全に保管してください。（ダッシュボードでは逆の動作をします: 強力なシークレットが生成され、作成時に一度だけ表示されます。[ダッシュボードでのキー管理](#key-management-in-the-dashboard)を参照してください。）レスポンスでキーが作成されたことを確認できます: ```json { @@ -213,13 +213,13 @@ curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -一覧レスポンスではキーのシークレットは返されません。ID、名前、パーミッションのみが返されます。 +キーの一覧レスポンスにシークレットは含まれません。IDと名前とパーミッションのみが返されます。 --- ## キーの無効化 -無効化するとキーレコードを削除せずに、即座にアクセスが失効します。 +無効化するとキーレコードを削除せずにアクセスを即座に取り消します。 ```bash curl -s -X POST http://your-server/keys//disable \ @@ -230,51 +230,51 @@ curl -s -X POST http://your-server/keys//disable \ ## キーの再生成 -既存キーの新しいシークレットを生成します。古いシークレットは即座に無効化されます。 +既存のキーに対して新しいシークレットを生成します。古いシークレットは即座に無効化されます。 ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -レスポンスには新しい平文シークレットが含まれており、**一度だけ表示されます**。 +レスポンスに新しい平文のシークレットが含まれます。**一度だけ表示されます。** --- ## ダッシュボードでのキー管理 -ダッシュボードの**Keys**ページでは、上記のすべての操作をUIで行えます。一覧を表示するには`keys:read`パーミッションを持つキーが必要で、作成/編集/無効化/再生成の操作にはそれぞれ`keys:create` / `keys:update` / `keys:disable` / `keys:regenerate`が必要です。キーのパーミッションの編集（`keys:update`）とキーの作成（`keys:create`）は別々になっているため、オペレーターにキーの発行権限を付与しつつ既存キーの再スコープ権限を与えない、またはその逆が可能です。管理者キーはこれらすべてをカバーします。 +ダッシュボードの**キー**ページは、上記のすべての操作のUIを提供します。一覧を表示するには`keys:read`パーミッションを持つキーが必要で、作成/編集/無効化/再生成の各操作にはそれぞれ`keys:create` / `keys:update` / `keys:disable` / `keys:regenerate`が必要です。キーのパーミッション編集（`keys:update`）と作成（`keys:create`）は別々のパーミッションなので、既存キーの再スコープ権限なしにキーの発行権限をオペレーターに付与することも、その逆も可能です。管理者キーはこれらすべてをカバーします。 -ダッシュボードからキーを作成する場合、シークレットを入力する必要はありません。ダッシュボードが強力なシークレットを生成し、作成時に**一度だけ**表示します。すぐにコピーして安全に保管してください。再生成の場合と同様、二度と表示されません。パーミッションを直接選択することも、パーミッションセットからシードすることもできます（以下を参照）。 +ダッシュボードからキーを作成する場合、シークレットを自分で指定する必要はありません。ダッシュボードが強力なシークレットを生成し、作成時に**一度だけ**表示します。すぐにコピーして安全に保管してください。再生成の場合と同様に、二度と表示されません。キーのパーミッションは直接選択するか、パーミッションセットからシードすることができます（以下を参照）。 -![APIキーページ: 各キーのカード（名前、付与されたパーミッション、作成日時）と再生成・無効化アクション。`admin`などの保護されたキーはマーク付き](/agenteye/images/api-keys.png) +![APIキーページ: キーごとのカードに名前、付与されたパーミッション、作成日時が表示され、再生成と無効化のアクション付き。`admin`などの保護されたキーはマーク済み](/agenteye/images/api-keys.png) --- -## 推奨キーレイアウト +## 推奨キー構成 | キー | パーミッション | 使用者 | |---|---|---| -| `admin`（`ADMIN_KEY`環境変数でブートストラップ） | すべて | 運用/セットアップ、およびダッシュボード（`ADMIN_KEY`で認証し、パーミッションチェック付きでユーザーリクエストをプロキシ） | +| `admin`（`ADMIN_KEY`環境変数経由でブートストラップ） | すべて | 運用/セットアップ、およびダッシュボード（`ADMIN_KEY`で認証し、パーミッションチェックを行いながらユーザーリクエストをプロキシ） | | ホストごとのコレクターキー | `events:add` | 各エージェントマシン上のコレクター | -| `dashboard-assistant`（`AGENT_API_KEY`環境変数でブートストラップ） | `events:read`、`evaluations:read`、`dashboards:read`、`dashboards:write`、`queries:read`、`queries:write`、`queries:run` | AIアシスタント、自動シード済み、**保護済み**; APIを通じて編集不可 | -| アシスタントテレメトリーキー（オプション） | `events:add` | AIアシスタントのセルフインストルメンテーション（有効な場合） | +| `dashboard-assistant`（`AGENT_API_KEY`環境変数経由でブートストラップ） | `events:read`、`evaluations:read`、`dashboards:read`、`dashboards:write`、`queries:read`、`queries:write`、`queries:run` | AIアシスタント、自動シード済み、**保護済み**; APIを通じて編集不可 | +| アシスタントテレメトリーキー（オプション） | `events:add` | AIアシスタントの自己計装（有効な場合） | -> **注意:** アシスタントのキーは`AGENT_API_KEY`環境変数（エージェントが`AGENTEYE_API_KEY`として提示するのと同じシークレット）からサーバーによって**自動的にシード**されます。手動のキー発行手順も管理者キーの関与もありません。パーミッションはソースコードに固定されているため、設定ミスによってスコープが拡大することはありません: イベント/評価/ダッシュボード全体の読み取り、加えてクエリ作成フロー「AIにクエリを書いてもらう」のためのダッシュボード書き込みとクエリ読み取り/書き込み/実行。すべてのSQLは引き続き同じ読み取り専用ロールとガードされたSQLパスを通過するため、これは*データサーフェス*ではなく*作成サーフェス*を拡大します。破壊的な操作（`queries:delete`、`dashboards:delete`）は意図的にアシスタントキーから除外されています。`admin`キーと同様に**保護されています**: keys APIを通じて無効化や再生成はできず、`AGENT_API_KEY`を変更して再起動することでのみローテートできます。ダッシュボード*ユーザー*がアシスタントを表示して使用するには、追加で`agent:use`パーミッションが必要です。セルフインストルメンテーションを有効にする場合は、アシスタントに`events:add`専用の別キーを付与してください。 +> **注意:** アシスタントのキーはサーバーが`AGENT_API_KEY`環境変数（エージェントが`AGENTEYE_API_KEY`として提示するのと同じシークレット）から**自動的にシード**します。手動のキー発行手順や管理者キーは不要です。パーミッションはソースコードに固定されているため、設定ミスによってスコープが拡大されることはありません: イベント/評価/ダッシュボードの読み取り、plus「AIにクエリを書かせる」オーサリングフロー用のdashboards-writeおよびqueries-read/write/run。すべてのSQLはユーザーが書いたクエリと同じ読み取り専用ロールとガードされたSQLパスを通過するため、これはデータサーフェスではなく*オーサリングサーフェス*を拡大します。破壊的操作（`queries:delete`、`dashboards:delete`）は意図的にアシスタントキーから除外されています。`admin`キーと同様に**保護済み**です: キーAPIを通じて無効化や再生成はできず、`AGENT_API_KEY`を変更して再起動することでのみローテーションできます。ダッシュボード*ユーザー*がアシスタントを表示・使用するには、追加で`agent:use`パーミッションが必要です。自己計装を有効にする場合は、アシスタントに`events:add`のみのキーを別途付与してください。 --- ## アップグレードと後方互換性に関する注記 -これらは既存のインスタンスをアップグレードする場合にのみ必要です。新規デプロイメントはスキップしてください。 +これらは既存のインスタンスをアップグレードする場合のみ必要です。新規デプロイメントはスキップできます。 -> Auditsが追加された際、既存の付与者はアラートと同じロール形状に沿って拡張されました: `alerts:read`を持つすべてのユーザーとパーミッションセットには`audits:read`が追加され、`alerts:write`を持つすべてのユーザーには`audits:write`が追加されました。既存のAPIキーは**拡張されませんでした**。監査機能が必要なキーには`audits:*`を明示的に付与してください。 +> 監査機能がリリースされた際、既存の付与者はアラートと同じロール形状に従って拡張されました: `alerts:read`を持つすべてのユーザーとパーミッションセットは`audits:read`を取得し、`alerts:write`を持つすべてのホルダーは`audits:write`を取得しました。既存のAPIキーは**拡張されませんでした**。キーに監査サーフェスが必要な場合は、`audits:*`を明示的に付与してください。 -> レガシーな`alerts:ack`トークンの保存済み付与は`incidents:ack`として解析されるため、オンコール担当者はキーを再発行せずにアクセスを維持できます。このトークンはダッシュボードのユーザーエディターから割り当てられなくなりました。マトリックスでは代わりに`incidents:ack`が提供されています。 +> レガシーの`alerts:ack`トークンの保存済み付与は`incidents:ack`として解析されるため、オンコール担当者はキーを再発行せずにアクセスを維持できます。このトークンはダッシュボードのユーザーエディターから割り当て不可になりました。マトリックスには代わりに`incidents:ack`が表示されます。 --- ## 次のステップ - [Python SDK](/ja/agenteye/python-sdk): エージェントコードがイベント送信時にどのように認証するか。 -- [Security](/ja/agenteye/security): サインイン、アクセス制御、オーガナイゼーションごとのデータ分離の仕組み。 \ No newline at end of file +- [セキュリティ](/ja/agenteye/security): サインイン、アクセス制御、組織ごとのデータ分離の仕組み。 \ No newline at end of file diff --git a/docs/ja/agenteye/assistant.mdx b/docs/ja/agenteye/assistant.mdx index f8baf981..b23e5344 100644 --- a/docs/ja/agenteye/assistant.mdx +++ b/docs/ja/agenteye/assistant.mdx @@ -1,61 +1,61 @@ --- title: "AIアシスタント" -description: "エージェントのデータに自然な言葉で質問すると、証拠へ直接リンクした回答が得られます。" +description: "エージェントのデータに自然な日本語で質問するだけで、根拠へのリンク付きの回答が得られます。" --- -エージェントのデータに自然な言葉で質問すると、証拠へ直接リンクした回答が得られます。SQLを書く必要も、ダッシュボードを掘り下げる必要もありません。**Failproof AI Observability**アシスタントは、チームの誰もがエージェントに関する答えをすばやく得るための最短の方法です。 +エージェントのデータに自然な言葉で質問するだけで、根拠へのリンク付きの回答が得られます。SQLを書く必要も、ダッシュボードを掘り下げる必要もありません。**Failproof AI Observability** アシスタントは、チームの誰もがエージェントに関する答えを最速で得られる手段です。 -![Failproof AI Observabilityアシスタントがダッシュボード内で自然言語の質問に回答している画面。ライブのエージェントアクティビティテーブル、エージェントごとのモデル使用状況の内訳、テキストによる要点が表示され、実行したクエリもインラインで示されている](/agenteye/images/assistant.png) -*自然な言葉で質問すると、自分のデータから構築された回答が得られます。ここでは、最もアクティブなエージェントとそれらが使用するモデルを分析し、すべての数値を確認できるよう実行したクエリも表示されます。* +![ダッシュボード内でFailproof AI Observabilityアシスタントが自然言語の質問に回答しており、ライブのエージェントアクティビティテーブル、エージェントごとのモデル使用状況の内訳、文章によるまとめが表示され、実行されたクエリがインラインで示されている](/agenteye/images/assistant.png) +*自然な言葉で質問すると、自分のデータに基づいた回答が得られます。ここでは、最も忙しいエージェントと使用しているモデルの内訳が示され、実行されたクエリも表示されているので、すべての数値を確認できます。* -学習コストはゼロです。チャットを開いて知りたいことを入力するだけで、返ってきたリンクをたどれます。 +学習することは何もありません。チャットを開いて知りたいことを入力し、返ってきたリンクを辿るだけです： ``` -You: which sessions errored today? -AI: 5 sessions errored today, newest first. Each one is linked: - • checkout-agent 14:02 tool timeout - • billing-agent 11:47 unhandled error - • ...and 3 more - -You: summarize this session (asked while viewing a run) -AI: This run took 12 steps across 3 tools and failed near the end when a - payment tool returned an error. It scored low on your "resolved" eval. - Links: the session, the failing event, and that evaluation. +あなた: 今日エラーが発生したセッションはどれ？ +AI: 今日は5件のセッションでエラーが発生しました。新しい順に表示します。各セッションにリンクが付いています： + • checkout-agent 14:02 ツールタイムアウト + • billing-agent 11:47 未処理エラー + • ...他3件 + +あなた: このセッションを要約して（実行中のセッションを表示しながら質問） +AI: この実行は3つのツールにわたって12ステップで進み、支払いツールがエラーを返した + ときに終盤で失敗しました。「resolved」評価のスコアは低くなっています。 + リンク：セッション、失敗したイベント、その評価。 ``` -## 質問するだけで、証拠へ直接ジャンプ +## 質問するだけで、すぐに証拠へジャンプ -推測やクエリ作成はもう不要です。「今週の本番環境でクオリティはどう推移している？」「今日エラーになったセッションはどれ？」「このセッションを要約して」と聞けば、クエリを構築して自分で読む代わりに、数秒で直接的な答えが返ってきます。 +推測も不要、クエリを書く必要もありません。「今週の本番環境で品質はどう推移している？」「今日エラーが出たセッションはどれ？」「このセッションを要約して」と尋ねれば、クエリを組み立てて自分で読む代わりに、数秒で明確な回答が得られます。 -すべての回答には根拠が付きます。アシスタントは回答の導出に使用した正確なセッション、保存済みクエリ、ダッシュボードへのリンクを提示するので、鵜呑みにせずクリックして確認できます。また**ページ認識機能**も備えています。セッションを閲覧中に「このセッション」について質問すると、どの実行を指しているかを自動的に把握します。履歴スイッチャーから以前の会話を再度開けば、中断したところから再開できます。 +すべての回答には根拠が付いてきます。アシスタントは回答の根拠として使用した正確なセッション、保存済みクエリ、ダッシュボードへのリンクを提示するので、言葉を信じるだけでなく、クリックして確認できます。また、**ページ認識機能**も備えています：セッションを表示しながら「このセッション」について質問すると、どの実行を指しているかをすでに把握しています。履歴スイッチャーから以前の会話を再度開けば、中断したところから再開できます。 ## 良い回答を保存済みクエリやダッシュボードに変換 -回答を保存しておきたいと思ったら、アシスタントに保存を依頼してください。保存済みクエリ用のSQLを下書きしたり、それらのクエリからダッシュボードをまとめたりして、**承認 / 却下**カードを表示します。「承認」をクリックするまで何も書き込まれないので、「聞くだけ」のスピード感を保ちながら、最終決定は常に自分の手に残ります。 +保存しておく価値のある回答が得られたら、アシスタントに保存を依頼してください。保存済みクエリ用のSQLを下書きしたり、そのクエリからダッシュボードを組み立てたりして、**承認 / 却下** カードを表示します。「承認」をクリックするまでは何も書き込まれないので、「質問するだけ」のスピード感を保ちながら、最終決定は常に自分の手に残ります。 -**クエリ**ページではさらに一歩進んで、SQLの作成者として機能します。欲しいクエリを説明すると（「過去7日間のエージェント別エラー率を表示して」）、エディタに直接SQLをストリーミングし、変更を反映する前に**承認**または**却下**できるdiffビューを開きます。 +**クエリ** ページではさらに一歩進んで、SQLの作成者としても機能します。「過去7日間のエージェント別エラー率を表示」のように欲しいクエリを説明すると、SQLがエディタに直接ストリーミングされ、変更が確定する前に**承認**または**却下**できるdiffビューが開きます。 ![ObservabilityのクエリページとそのSQLエディタ](/agenteye/images/query-lab.png) -*クエリページ：アシスタントが下書きの読み取り専用クエリをストリーミングし、承認または却下できるエディタです。* +*クエリページ：このエディタにアシスタントが下書きの読み取り専用クエリをストリーミングし、承認または却下できます。* -ここで質問してSQLを作成する際には`queries:run`権限が使用されます。これはエディタの**実行**ボタンと同じ権限です。他のすべての場所でのチャットには`agent:use`が必要です。 +ここで質問によってSQLを作成するには `queries:run` 権限が必要です。これはエディタの**実行**ボタンと同じ権限です。その他のチャット機能には `agent:use` が必要です。 -## チーム全体に安心して開放できる +## チーム全員に安心して開放できる -アシスタントが何に触れるかを心配することなく、全員に開放できます。 +アシスタントが何に触れるかを心配せずに、全員に開放できます： -- **閲覧できるデータのみを読み取ります。** 回答は自分の読み取り権限の範囲にスコープされるため、データへのアクセス範囲が拡大することはありません。 -- **書き込みはすべてあなたの確認を待ちます。** 保存済みクエリとダッシュボードは、明示的に承認をクリックした後にのみ作成され、このゲートをオフにする設定はありません。 -- **削除は一切できません。** 削除ツールは公開されておらず、アシスタントは削除権限を持ちません。削除操作はダッシュボード上であなたの手に委ねられています。 -- **組織の外には出ません。** アシスタントは現在表示中の組織のみを参照します。 -- **質問内容はあなただけのものです。** プロンプトと回答は自分のObservabilityデータベースに保存され、プロダクトアナリティクスは使用メタデータのみを記録し、プロンプトのテキストは記録しません。 +- **表示できるものしか読み取りません。** 回答は自分の読み取り権限にスコープされているため、データのアクセス範囲が広がることはありません。 +- **すべての書き込みはあなたを待ちます。** 保存済みクエリとダッシュボードは、明示的な「承認」クリック後にのみ作成され、このゲートをオフにする設定はありません。 +- **削除は一切できません。** 削除ツールは公開されておらず、アシスタントは削除権限を持ちません。削除はダッシュボード上のあなたの手に委ねられています。 +- **組織の外には出ません。** アシスタントは現在表示している組織のみを参照します。 +- **質問はあなただけのものです。** プロンプトと回答はあなた自身のObservabilityデータベースに保存されます。プロダクト分析は使用メタデータのみを記録し、プロンプトのテキストは記録しません。 ## 見つけ方 -アシスタントは組織配下のすべてのページ（`//...`）の右端に表示されています。レールをクリックするか、`⌘J` / `Ctrl+J`を押すと全画面チャットパネルに展開され、端をドラッグしてサイズを変更できます。幅はリロード後も記憶されます。使用するには**`agent:use`**権限が必要で、権限がない場合はレールがグレーアウトされます。デプロイ環境でまだ有効化されていない場合（LLM接続が必要です）、動作するチャットの代わりにミュートされたレールが表示されます。 +アシスタントは、組織配下のすべてのページ（`//...`）の右端に常駐しています。レールをクリックするか、`⌘J` / `Ctrl+J` を押すと全画面チャットパネルに展開され、端をドラッグしてリサイズできます。幅の設定はリロードをまたいで記憶されます。使用するには **`agent:use`** 権限が必要で、権限がない場合はレールがグレーアウトされます。デプロイ環境でまだ有効化されていない場合（LLM接続が必要です）、動作するチャットの代わりにミュートされたレールが表示されます。 -## 関連情報 +## 関連項目 - [CLIとエージェント](/ja/agenteye/cli-and-agents) - [クエリ](/ja/agenteye/queries) diff --git a/docs/ja/agenteye/audits.mdx b/docs/ja/agenteye/audits.mdx index 8607ec5a..98edf02a 100644 --- a/docs/ja/agenteye/audits.mdx +++ b/docs/ja/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- -title: "監査：自動信頼性アナリスト" -description: "Failproof AI Observabilityは、ルールを書いていなかった障害を自動的に発見し、優先順位付きで根拠のある「修正すべき項目リスト」を提供します。" +title: "監査：あなたの自動信頼性アナリスト" +description: "Failproof AI Observability は、あなたがルールを書いていない障害を探し出し、修正すべき事項を根拠付きでランク付けしたTo-Doリストを提供します。" --- -Failproof AI Observabilityは、ルールを書いていなかった障害を自動的に発見し、優先順位付きで根拠のある「修正すべき項目リスト」を提供します。まるで専任のアナリストが毎晩ログを精査し、翌朝には簡潔なリストをデスクに残してくれるようなものです。 +Failproof AI Observability は、あなたがルールを書いていない障害を探し出し、修正すべき事項を根拠付きでランク付けしたTo-Doリストを提供します。毎晩アナリストがログを精査し、翌朝には要点をまとめたリストが机の上に置かれているようなイメージです。
-*2分間のツアー：スケジュール実行から実際に対処できる修正案まで。* +*2分間のツアー：スケジュール実行から実際に対応できる修正案まで。* -![監査ページ：セッション内の障害パターンをスキャンする定期ジョブ。スケジュールと感度設定付き](/agenteye/images/audits.png) -*各監査は定期的に実行されるジョブで、セッションを分析して優先順位付きの根拠ある推奨事項をまとめます。* +![監査ページ：セッションの障害パターンをスキャンする定期ジョブ。各ジョブにはスケジュールと感度が設定されている](/agenteye/images/audits.png) +*各監査はセッションを分析し、根拠付きで優先度の高い推奨事項をまとめる定期ジョブです。* -## 次に何を修正すべきか、推測をやめよう +## 次に何を修正すべきか、もう推測しなくていい -アラートは既知の問題を検知します。監査は未知の問題を検知します。設定したスケジュールに従い、監査はすべてのエージェントセッションを横断的に読み取り、修正すべきパターンを探し出します。ログをひたすらスクロールして問題を見つけようとする時間ではなく、発見した内容への対処に時間を使えるようになります。 +アラートは、すでに把握している問題を検知します。監査は、まだ把握していない問題を検知します。設定したスケジュールで、監査はすべてのエージェントセッションを横断的に読み取り、修正する価値のあるパターンを探します。ログをスクロールして問題を見つけようとする時間を、発見された知見への対応に充てることができます。 1回の実行で、本番環境でエージェントを実際に壊す障害モードを調査します： -- **エラークラスター**：共通の根本原因を持つ同じ障害の繰り返し。 -- **ベースラインからのドリフト**：既知の正常ウィンドウから静かに乖離していく挙動。 -- **トランスクリプト内のゴール失敗**：技術的には完了したが、本来の目的を果たせなかった実行。 -- **ツールの誤用**：不適切なツールの選択、不正な引数、または呼び出しを無駄に消費するループ。 -- **品質とコストのトレードオフ**：より安く得られる出力に対して過剰な費用をかけている箇所。 -- **カバレッジのギャップ**：どのevalやアラートも監視していない挙動。 +- **エラークラスター**：共通の根本原因のもとで同じ障害が繰り返されているパターン。 +- **ベースラインからのドリフト**：既知の正常な状態から静かに乖離していく挙動。 +- **トランスクリプト上のゴール失敗**：技術的には完了したものの、目的を達成できなかった実行。 +- **ツールの誤使用**：誤ったツールの選択、不正な引数、または呼び出しを浪費するループ。 +- **品質とコストのトレードオフ**：より安く得られる出力に対して過払いとなっている箇所。 +- **カバレッジのギャップ**：どの評価もアラートも監視していない挙動。 -**感度**設定（低・中・高）ひとつで調査の強度を決められます。ノイズの多いステージング環境と厳格な本番環境でそれぞれ、欲しいシグナルに合わせてチューニングできます。 +**感度**設定（低・中・高）を1つ調整するだけで、どれだけ深く調査するかを制御できます。ノイズの多いステージング環境のエージェントも、厳格な本番環境のエージェントも、それぞれ必要なシグナルに合わせてチューニングできます。 -## すべての推奨事項には根拠が伴う +## すべての推奨事項は根拠とともに提示される -発見内容を盲目的に信頼する必要はありません。各推奨事項には、その根拠となった正確なセッションとそれを発見したSQLが引用されています。主張を逆算して検証する手間なく、ワンクリックで証拠を開いて問題を確認できます。 +結果を盲目的に信頼する必要はありません。各推奨事項は、その根拠となったセッションと、発見に使われたSQLを正確に示しています。クレームを逆算して検証する代わりに、クリック一つで証拠を開いて問題を確認できます。 -認証情報の漏洩に関する発見では、さらに一歩踏み込んでマッチした個別のイベントへのリンクが提供されます。クリックすると、セッション内のその正確な瞬間に直接ジャンプでき、長いトランスクリプトの先頭からスクロールする必要はありません。リンクにはイベント名が表示されますが、検出された秘密情報は発見内容に書き込まれることはないため、発見内容を読むことで認証情報が二重に記録される心配はありません。セッションが保持期間を過ぎてイベントが存在しない場合も、誤操作かと悩ませることなく、ページに明確に表示されます。 +漏洩した認証情報に関する発見については、さらに一歩踏み込み、一致した個別のイベントへのリンクが提供されます。クリックすると、そのセッションの該当する瞬間に、すでに選択された状態でジャンプします。長いトランスクリプトの先頭からスクロールする必要はありません。リンクにはイベント名が表示されますが、検出されたシークレット自体は発見事項にコピーされません。そのため、発見事項を読むことが、認証情報が書き記される別の場所にならないよう配慮されています。セッションが保持期間を過ぎてイベントが存在しなくなっている場合は、何か操作を誤ったのではと悩むことなく、ページが明確にその旨を伝えます。 -これが監査の誠実さを保つ仕組みでもあります。サーバーは引用されたすべてのセッションの実在を確認し、**根拠が成立しない推奨事項はすべて破棄します**。監査は調査するものであり、でっち上げはしません。リストに載るのは実在して再現可能な問題であり、重要度順にランク付けされ、最大の改善効果を持つものが先頭に表示されます。 +これが監査の誠実さを保つ仕組みでもあります。サーバーは、引用されたすべてのセッションが実際に存在するかを確認し、**証拠が成立しない推奨事項は破棄します**。監査は調査はしますが、捏造はしません。リストに残るものは、実在し、再現可能で、重要度によってランク付けされており、最も価値の高い改善点が先頭に来ます。 ## 修正をガードレールに変える -問題を修正することは成果の半分に過ぎません。もう半分は、同じ問題がひっそりと再発しないようにすることです。すべての発見には**再発アラートを下書きするワンクリックショートカット**が付いており、調整可能な適切な初期トリガーがあらかじめ入力されています。発見をクローズしてアラートを有効化すれば、次にそのパターンが現れたとき、将来の監査で再発見するのではなく、通知を受け取れます。 +問題を修正することは、勝利の半分に過ぎません。もう半分は、その問題が密かに再発しないようにすることです。すべての発見事項には、**再発アラートの下書きを作成するワンクリックショートカット**が付いています。合理的な初期トリガーがあらかじめ入力されており、調整可能です。発見事項を閉じてアラートを有効にすれば、次回そのパターンが再び現れたとき、次の監査で再発見するのではなく、すぐに通知を受け取れます。 -## どこで使えるか +## 使い方 -監査はダッシュボードの **`//audits`**（サイドバーから *analyze* → *audits*）にあります。実行結果と発見内容の閲覧には **`audits:read`** 権限が必要です。監査の作成・編集・トリアージには **`audits:write`** 権限が必要です。監査のスコープとケイデンスを設定し、次のスケジュール実行を待たずにすぐ結果が欲しいときは **Run now** をクリックしてください。 +監査はダッシュボードの **`//audits`** にあります（サイドバーの「分析」→「監査」）。実行結果と発見事項の閲覧には **`audits:read`** 権限が必要で、監査の作成・編集・トリアージには **`audits:write`** 権限が必要です。監査のスコープとケイデンスを設定し、次のスケジュール実行を待たずにすぐ結果が欲しい場合は **Run now** をクリックしてください。 -## 関連情報 +## 関連項目 -- [アラート](/ja/agenteye/alerts)：既知のしきい値を超えた瞬間に通知を受け取る。 -- [評価](/ja/agenteye/evaluations)：すべての実行をスコアリングして品質の低下を自動的に検出する。 -- [エラートラッキング](/ja/agenteye/error-tracking)：エージェントがスローするエラーをグループ化して追跡する。 -- [インシデント](/ja/agenteye/incidents)：監査で発見した問題を修正完了まで追跡する。 \ No newline at end of file +- [アラート](/ja/agenteye/alerts)：すでに把握しているしきい値を超えた瞬間に通知を受け取る。 +- [評価](/ja/agenteye/evaluations)：すべての実行をスコアリングして、品質の低下を自動的に検出する。 +- [エラートラッキング](/ja/agenteye/error-tracking)：エージェントが発生させるエラーをグループ化して追跡する。 +- [インシデント](/ja/agenteye/incidents)：監査で発見された問題を修正まで追跡する。 \ No newline at end of file diff --git a/docs/ja/agenteye/cli-and-agents.mdx b/docs/ja/agenteye/cli-and-agents.mdx index 738af318..bdaac558 100644 --- a/docs/ja/agenteye/cli-and-agents.mdx +++ b/docs/ja/agenteye/cli-and-agents.mdx @@ -1,80 +1,80 @@ --- title: "CLI" -description: "Failproof AI Observabilityのデプロイ全体を、コマンド一つで。" +description: "Failproof AI Observability のデプロイ全体を、たった1つのコマンドで。" --- -Failproof AI Observabilityのデプロイ全体を、コマンド一つで。ターミナルを離れずに本番環境の確認、APIキーの発行、インシデントの承認が可能。CIへのスクリプト組み込みや、コーディングエージェントへの自然言語による指示にも対応しています。 +Failproof AI Observability のデプロイ全体を、たった1つのコマンドで。ターミナルを離れずに本番環境を確認したり、APIキーを発行したり、インシデントを承認したりできます。さらに、CI にスクリプトとして組み込んだり、コーディングエージェントに自然な英語で操作させることも可能です。 ```bash pipx install agenteye -agenteye login --email you@example.com # 6桁のコードがメールで届きます -agenteye --json sessions --since 24h # 過去1日のエージェント実行一覧（新しい順） +agenteye login --email you@example.com # 6桁のコードがメールボックスに届きます +agenteye --json sessions --since 24h # 過去1日のすべてのエージェント実行（新しい順） ``` -*`agenteye` CLIはダッシュボードと通信します。これはサーバーにイベントを送信するコレクターとは別のツールです。* +*`agenteye` CLI はダッシュボードと通信します。イベントをサーバーに送信するコレクターとは別のツールです。* -## デプロイ全体を、コマンド一つで +## デプロイ全体を、たった1つのコマンドで -簡単な確認のためにタブを行き来するのはもう終わりにしましょう。`agenteye` CLIは単一のバイナリからデータの参照と組織の管理を行えるため、ダッシュボードをクリックして回っていた作業が1行のコマンドになります。再実行、エイリアス登録、ランブックへの貼り付けも自由自在です。4つの機能領域を提供します： +ちょっとした確認のためにタブを切り替えるのはもうやめましょう。`agenteye` CLI は単一のバイナリでデータの読み取りと組織の管理を行えるため、ダッシュボードをクリックして確認していた作業が1行のコマンドで済むようになります。エイリアスに登録したり、ランブックに貼り付けたりして再利用できます。4つの機能領域があります： -- **データの参照：** `sessions`、`events`、`evals`、`errors`を時間・エージェント・環境でフィルタリング。 +- **データの読み取り：** `sessions`、`events`、`evals`、`errors` を時間・エージェント・環境でフィルタリング。 - **組織の管理：** `keys`、`users`、`settings`、`alerts`、`incidents`。 -- **分析の実行：** 保存済みSQLとイベントデータに対するアドホックな `query` ランナー。 -- **アシスタントへの質問：** `agent ask` でダッシュボード上のものと同じ読み取り専用アナリストに問い合わせ。 +- **アナリティクスの実行：** 保存済みSQLとイベントデータに対するアドホックな `query` ランナー。 +- **アシスタントへの問い合わせ：** `agent ask` でダッシュボード内のチャットと同じ読み取り専用アナリストに接続。 -`pipx` で一度インストールし、メールで届く6桁のコードでサインインすれば準備完了です。セッションは約1日持続します。期限切れになったら `agenteye login` を再実行してください。ブラウザを開かずに本番環境の確認、キーの発行、発火中のインシデントのトリアージが行えます： +`pipx` で一度インストールし、メールで届く6桁のコードでサインインするだけで準備完了です。セッションは約1日間有効で、期限切れになったら `agenteye login` を再実行してください。ブラウザを開かずに本番環境のスポットチェック、キーのプロビジョニング、発生中インシデントのトリアージを行えます： ```bash -agenteye errors --since 24h --aggregate # エラータイプ別にグループ化して何が壊れているかを確認 -agenteye incidents list --state firing # 現在発火中のインシデントを確認 -agenteye keys create ci --add events:add # イベント送信専用のキーを発行（シークレットは一度だけ表示） +agenteye errors --since 24h --aggregate # エラータイプ別にグループ化した障害状況 +agenteye incidents list --state firing # 現在発生中のインシデント一覧 +agenteye keys create ci --add events:add # イベントのプッシュのみ可能なキー（シークレットは一度だけ表示） ``` -一つ覚えておくべき習慣があります：`--json` のようなグローバルオプションはコマンドの前に置きます。`agenteye --json sessions` が正しく、`agenteye sessions --json` は正しくありません。 +覚えておきたい習慣が1つあります：`--json` のようなグローバルオプションはコマンドの前に置きます。`agenteye --json sessions` は正しい書き方で、`agenteye sessions --json` は正しくありません。 -## スクリプト化してCIに組み込む +## スクリプト化して CI に組み込む -すべてのコマンドは `--json` に対応しており、それがすべてを変えます。クリーンなJSONがstdoutに出力され、人間向けのステータスや警告はstderrに出力されるため、`--json` でキャプチャした出力は余計な行を取り除く必要なくそのまま `jq` にパイプできます。これにより、CLIはプロンプトで使う場合にも、出力をパースするコーディングエージェントにとっても等しく使いやすいツールになっています： +すべてのコマンドは `--json` オプションに対応しており、これによって大きく活用の幅が広がります。クリーンな JSON は stdout に出力され、人間向けのステータスメッセージや警告は stderr に出力されるため、`--json` で取得した出力は余分な行を取り除くことなくそのまま `jq` にパイプできます。これにより、CLI はプロンプトで使う場合でも、出力をパースするコーディングエージェントにとっても同様に使いやすい設計になっています： ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -無人実行を前提に設計されています。ターミナルが接続されていない場合は確認プロンプトが自動的にスキップされるため、パイプラインで処理が止まることはありません。また、すべてのコマンドは意味のある終了コードを返します：`0` 成功、`4` 未ログイン、`5` 権限不足（メッセージに権限名が明示されます。例：`alerts:write`）、`3` ダッシュボードに接続不可。スクリプトは `4` を受け取って再認証を行ったり、`5` を受け取って管理者に何を依頼すべきかを正確に把握したりと、失敗の原因が不明なまま処理を終了せずに対処できます。 +無人実行を想定した設計です。ターミナルが接続されていない場合、確認プロンプトは自動的にスキップされるため、パイプライン中に処理が止まることはありません。また、すべてのコマンドは意味のある終了コードを返します：`0` は成功、`4` は未ログイン、`5` は権限不足（例えば `alerts:write` のように不足している権限がメッセージに明記されます）、`3` はダッシュボードに到達不能。スクリプトで `4` の場合は再認証に分岐させたり、`5` の場合は管理者に何を依頼すべきかを正確に把握できるため、原因不明のままエラーになるようなことがありません。 -## コーディングエージェントに自然言語で操作させる +## コーディングエージェントに自然な言葉で操作させる -さらに言えば、これらのフラグをすべて覚える必要はないはずです。**CLIスキル**は `agenteye-cli` という小さなAgent Skillフォルダで、Claude CodeやCodexのようなコーディングエージェントに自然言語のリクエストからCLIを操作する方法を教えます。「今日、何か壊れているものはある？」と聞けば、エージェントが適切なコマンドを選んであなたの代わりに実行し、結果を文章で答えてくれます。 +さらに言えば、これらのフラグを覚える必要すらないはずです。**CLI スキル**は `agenteye-cli` という小さなエージェントスキルフォルダで、Claude Code や Codex などのコーディングエージェントが自然な英語のリクエストから CLI を操作できるよう教えるものです。「今日何か壊れているものはある？」と尋ねるだけで、エージェントが適切なコマンドを選び、あなたの権限で実行し、結果を文章で回答します。 -Claude Codeの場合、`agenteye-cli` フォルダを `~/.claude/skills/` に置くだけで自動的に検出されます。Failproof AI Observabilityがそのフォルダを提供します。スキルはすでにインストール済みのCLIを操作するだけなので、追加でインストールするものはありません。メールコードによるログインはエージェントが代行できないため、先にご自身でログインしておいてください。 +Claude Code の場合は、`agenteye-cli` フォルダを `~/.claude/skills/` に置くだけで自動的に認識されます。Failproof AI Observability がそのフォルダを提供するため、追加でインストールするものはありません。すでにインストール済みの CLI を操作するだけだからです。ログインはあらかじめ自分で行ってください：スキルはメール認証コードによるログインを代わりに完了させることはできません。 -エージェントはあなたのログイン権限でCLIを実行するため、読み取りも書き込みも含め、あなたが許可されているすべての操作が可能です：キーの作成、設定の変更、インシデントの解決など。エージェントに対してCLIの「本当によろしいですか？」プロンプトは表示されないため、スキルは変更を行う前に正確なコマンドを提示してあなたの承認を待つよう設計されています。確認ステップはあなた自身です。 +エージェントはあなたのログイン権限で CLI を実行するため、読み取りも書き込みも含め、あなたの権限で許可されているすべての操作が可能です：キーの作成、設定の変更、インシデントの解決など。エージェントに対しては CLI の「本当によろしいですか？」プロンプトは表示されないため、スキルは変更を加える前に正確なコマンドを提示してあなたの承認を待つように設計されています。確認ステップはあなた自身が担います。 ```text -you session run-001 が失敗した原因は？ +you session run-001 はなぜ失敗したのですか？ -agent Running: agenteye --json events --session-id run-001 --all - checkout-agentが3回目のツール呼び出しでTimeoutErrorが発生しました。 +agent 実行中: agenteye --json events --session-id run-001 --all + checkout-agent は3回目のツール呼び出しで TimeoutError が発生しました。 ``` -読み取りはすぐに実行され、書き込みはすべてあなたの確認を待ちます： +読み取り操作はすぐに完了し、書き込み操作はすべてあなたの確認を待ちます： ```text -you CIにイベントの送信だけできるキーを発行して。 +you CI にイベントのプッシュだけができるキーを作成してください。 -agent APIキーを作成します。以下のコマンドを実行します： +agent APIキーを作成します。以下を実行します： agenteye keys create ci --add events:add - 続行してよいですか？ + 実行してよいですか？ -you yes +you はい -agent 完了しました。events:addのみの権限で「ci」キーを作成しました。シークレットは一度しか表示されないため、今すぐ保存してください。 +agent 完了しました。「ci」キーが events:add 権限のみで作成されました。シークレットは一度だけ表示されるので、今すぐ保存してください。 ``` ## 関連情報 -- [CLIリファレンス](/ja/agenteye/cli)：すべてのコマンド、フラグ、JSONの形式。 -- [エージェント向けCLIレシピ](/ja/agenteye/cli-recipes)：コピー＆ペーストで使える `jq` パターンと終了コードの処理方法。 -- [CLIエージェントスキル](/ja/agenteye/cli-skill)：`agenteye-cli` スキルのインストールと実行方法。 -- [AIアシスタント](/ja/agenteye/assistant)：`agent ask` が接続するダッシュボード内のアナリスト。 \ No newline at end of file +- [CLI リファレンス](/ja/agenteye/cli)：すべてのコマンド、フラグ、JSON の形式。 +- [エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)：コピー&ペーストで使える `jq` パターンと終了コードの処理。 +- [CLI エージェントスキル](/ja/agenteye/cli-skill)：`agenteye-cli` スキルのインストールと実行方法。 +- [AI アシスタント](/ja/agenteye/assistant)：`agent ask` が接続するダッシュボード内のアナリスト。 \ No newline at end of file diff --git a/docs/ja/agenteye/cli-recipes.mdx b/docs/ja/agenteye/cli-recipes.mdx index b84952aa..a33e6aa1 100644 --- a/docs/ja/agenteye/cli-recipes.mdx +++ b/docs/ja/agenteye/cli-recipes.mdx @@ -1,30 +1,30 @@ --- title: "エージェント向けCLIレシピ" -description: "セッション・イベント・評価データをスクリプトやコーディングエージェントが自動化できる形に変換する、コピペ可能なクエリパターンとjqレシピ集。" +description: "セッション、イベント、評価データをスクリプトやコーディングエージェントが自動化できる形に変換する、コピペ可能なクエリパターンとjqレシピ集。" --- -セッション・イベント・評価データをスクリプトやコーディングエージェントから直接取得（および再評価のトリガー）できます。stdout にクリーンな JSON を出力するため、そのまま `jq` にパイプ可能です。これらのレシピは、Failproof AI Observability のデータを、ダッシュボードをクリックせずにターミナルユーザーや AI コーディングエージェント（Claude Code、Cursor）がクエリ・自動化できる形に変換します。 +セッション、イベント、評価データをスクリプトやコーディングエージェントから直接取得（および再評価のトリガー）できます。stdout にクリーンな JSON が出力されるため、そのまま `jq` にパイプできます。これらのレシピは、Failproof AI Observability のデータをターミナルユーザーや AI コーディングエージェント（Claude Code、Cursor）がダッシュボードをクリックせずにクエリ・自動化できる形に変換します。 -以下のパターンは、Failproof AI Observability CLI（`agenteye`）ですぐにコピペして使えます。インストール・認証・全オプションの一覧は [CLI](/ja/agenteye/cli) を参照してください。組み込みヘルプは `agenteye -h` または `agenteye -h` で確認できます。 +以下のパターンは Failproof AI Observability CLI（`agenteye`）ですぐにコピペして使えます。インストール、認証、全オプションの一覧については [CLI](/ja/agenteye/cli) を参照してください。組み込みヘルプは `agenteye -h` または `agenteye -h` で確認できます。 ## 基本ルール -1. **グローバルオプションはコマンドの*前*に置く。** `agenteye --json sessions` が正しい。`agenteye sessions --json` は誤り。グローバルオプションは `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color` です。 -2. **出力をパースする際は必ず `--json` を渡す。** データは JSON として **stdout** に出力され、人間向けのステータスメッセージやエラーは **stderr** に出力されるため、stdout をクリーンな状態で `jq` にパイプできます。 -3. **終了コードで分岐する**（stderr のテキストではなく）: `0` 正常 · `1` 予期しないエラー · `2` 引数不正 · `3` ダッシュボードに接続できない · `4` 未ログインまたはセッション期限切れ · `5` 権限不足 · `6` リソースが見つからない。 -4. **`-h` で探索する。** 各コマンドにはフィルター・値のフォーマット・JSON の形状がドキュメント化されています。 +1. **グローバルオプションはコマンドの*前*に置く。** `agenteye --json sessions` が正しく、`agenteye sessions --json` は正しくありません。グローバルオプションは `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color` です。 +2. **出力をパースする際は必ず `--json` を付ける。** データは JSON として **stdout** に出力され、人向けのステータスやエラーは **stderr** に出力されるため、stdout を `jq` にパイプしてもクリーンな状態が保たれます。 +3. **stderr のテキストではなく終了コードで分岐する。** `0` 正常 · `1` 予期しないエラー · `2` 引数が不正 · `3` ダッシュボードに到達できない · `4` 未ログインまたはセッション期限切れ · `5` 権限不足 · `6` リソースが見つからない。 +4. **`-h` で調べる。** 各コマンドのフィルター、値のフォーマット、JSON の構造はヘルプに記載されています。 ## 初回セットアップ ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # --base-url を毎回指定しなくて済むように -agenteye login --email you@example.com # メールで届いたコードを貼り付ける（有効期限 約24時間） +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # --base-url を毎回入力しなくて済むように +agenteye login --email you@example.com # メールで届いたコードを貼り付ける（有効期限は約24時間） ``` ## 作業前に認証を確認する -`whoami` はセッションが存在しないか期限切れの場合でもエラーにならず、代わりに `logged_in:false` を返します。そのためエージェントが認証状態を安全に確認できます（ベース URL が未設定またはダッシュボードに接続できない場合は非ゼロで終了することがあります）。 +`whoami` はセッションが存在しない・期限切れでもエラーにならず、代わりに `logged_in:false` を返します。そのため、エージェントが認証状態を安全にチェックできます（ベース URL が未設定またはダッシュボードに到達できない場合は、引き続き非ゼロで終了する場合があります）。 ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,28 +32,28 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## 失敗または低スコアのセッションを探す +## 失敗またはスコアの低いセッションを見つける ```bash -# 直近24時間で評価がエラーになったセッション +# 過去24時間以内で評価がエラーになったセッション agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# 特定エージェントの helpfulness スコアが 0.5 以下の評価 +# helpfulness のスコアが 0.5 以下の評価（特定エージェント） agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -スコアのフィルタリングは `sessions` ではなく **`evals`** に対して行います。`--score KEY:MIN..MAX` は繰り返し指定可能で AND 結合されます。どちらの境界も省略可能です（`..0.5` は ≤ 0.5、`0.9..` は ≥ 0.9）。1 リクエストあたり最大 20 個のスコアフィルターを指定でき、それ以上は HTTP 400 を返します。`sessions` は `evals` と `--env`、`--status`、`--agent-id`、`--session-id`、時間範囲フィルターを共有しますが、`--score` は使えません。 +スコアのフィルタリングは `sessions` ではなく **`evals`** にあります。`--score KEY:MIN..MAX` は繰り返し指定でき、AND で結合されます。どちらの境界も省略可能です（`..0.5` は ≤ 0.5、`0.9..` は ≥ 0.9 を意味します）。1 リクエストあたり最大 20 個のスコアフィルターを指定できます。それ以上は HTTP 400 が返されます。`sessions` は `evals` と `--env`、`--status`、`--agent-id`、`--session-id`、時間範囲フィルターを共有していますが、`--score` はありません。 ## セッションを最初から最後まで読む -`session show` のような単一コマンドはありません。イベントの記録とセッションの評価を組み合わせて使います。 +単一の `session show` コマンドはありません。イベントの履歴とセッションの評価を組み合わせて使います。 ```bash -# セッションの最新評価（ステータス + スコア） +# セッションの最新の評価（ステータスとスコア） agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# 実行中の全イベント（完全な取得には --limit を増やす） +# 実行中のすべてのイベント（全件取得には --limit を大きくする） agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' # セッション内のツール呼び出しのみ（生のペイロードを取得するには --full が必要） @@ -61,14 +61,14 @@ agenteye --json events --full --session-id run-001 --event-type tool_use,tool_re | jq '.events[].payload' ``` -> **注意:** デフォルトでは、`events` はペイロードなしの高速フィードを読み取ります。各イベントはサーバーが計算した 1 行の `summary` と `is_error` やトークン数などのフラグを持ちますが、`payload` は `{}` として返されます。生のペイロードを取得するには `--full`（または `--fields payload`）を追加してください。フルフィードは大規模になると遅くなるため、`--full` と単一の `--session-id` を組み合わせて範囲を限定してください。 +> **注意:** デフォルトでは、`events` はペイロードなしの高速フィードを読み取ります。各イベントにはサーバーが計算した1行の `summary` と `is_error` やトークン数などのフラグが含まれますが、`payload` は `{}` として返されます。生のペイロードを取得するには `--full`（または `--fields payload`）を追加します。フルフィードは大規模では低速になるため、範囲を限定してください。`--full` は単一の `--session-id` と組み合わせて使用することを推奨します。 -## すべてを取得する（ページネーション） +## 全件取得（ページネーション） -結果は最新順でカーソルページネーションが使われます。 +結果は新しい順に並び、カーソルによるページネーションが行われます。 ```bash -# 一括取得: 200 行ページで最大 500 行を取得 +# 一括取得: 200行ずつのページで最大500行を取得 agenteye --json events --session-id run-001 --limit 500 --all > events.json # 手動ページング: next_cursor を次のリクエストに渡す @@ -79,41 +79,41 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## --fields で出力を絞り込む -テーブルと `--json` の両方でキーを制限し、エージェントが読む量を減らします。 +テーブルと `--json` の両方でキーを制限し、エージェントが読む必要のある情報を減らします。 ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -不明なフィールド名は有効なリストとともに（終了コード `2` で）拒否されるため、フィールド名の探索にも使えます。 +不明なフィールド名は（終了コード `2` で）有効なフィールド一覧とともに拒否されます。これはフィールド名を調べる手軽な方法です。 -## 有効なフィルター値を確認する +## 有効なフィルター値を調べる ```bash agenteye --json list envs | jq -r '.values[]' # --env に使える値 -agenteye --json list tools | jq -r '.values[]' # ツール名（agents、models、event_types なども） +agenteye --json list tools | jq -r '.values[]' # ツール名。agents、models、event_types なども同様 agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX の有効な KEY ``` ## 組織を選択する（マルチテナント） -複数の組織に所属している場合は、ログイン時にアクティブなテナントを選択します（保存されます）。 +複数の組織に所属している場合は、ログイン時にアクティブなテナントを選択します（選択内容は保存されます）。 ```bash agenteye login --org acme --email you@corp.com # ログインと同時にテナントを設定 agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # 1 コマンドだけオーバーライド +agenteye --org globex --json sessions --since 24h # 1コマンドのみ上書き ``` -`--org` なしでマルチ組織ログインを行うと非ゼロで終了し、選択肢の組織リストが表示されます。 +`--org` を指定せずに複数組織のログインを行うと、非ゼロで終了し、選択可能な組織の一覧が表示されます。 ## SDK/コレクター用の API キーを作成する ```bash -# シークレットは一度だけ表示される。--json の場合は .key フィールド +# シークレットは一度だけ表示される。--json の場合は .key フィールドに含まれる key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # ローテート。失効させるには agenteye keys disable ci-bot --yes +agenteye keys regenerate ci-bot --yes # ローテーション。無効化は agenteye keys disable ci-bot --yes ``` ## 保存済みまたはアドホッククエリを実行する @@ -123,7 +123,7 @@ agenteye --json query run --sql "select count(*) from analytics.events" | jq '.r agenteye --json query run errs --arg prod | jq '.rows' # 保存済みクエリ + 位置引数 $1 ``` -## インシデントを非インタラクティブにトリアージする +## インシデントを非対話的にトリアージする ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **注意:** ミューテーション操作は `--json` が指定されているか stdin が TTY でない場合、確認プロンプトを自動的にスキップするため、エージェントがハングすることはありません。それ以外の場所で明示的にスキップするには `--yes`/`-y` を渡してください。 +> **注意:** ミューテーション操作は `--json` 使用時または stdin が TTY でない場合に確認プロンプトを自動的にスキップするため、エージェントが途中で止まることはありません。その他の場所で明示的にスキップする場合は `--yes`/`-y` を渡します。 ## スクリプトでの終了コード処理 @@ -147,9 +147,9 @@ case "${code:-0}" in esac ``` -## JSON 出力の形状 +## JSON 出力の構造 -| コマンド | stdout JSON（`--json` 指定時） | +| コマンド | stdout JSON（`--json` 付き） | |---|---| | `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` または `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | @@ -162,18 +162,18 @@ esac | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete（任意） | リソースオブジェクト、または削除時は `{"deleted": true, "id"}` | -| 失敗時（任意、`--json` 指定時） | stdout に `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | +| create/update/delete（いずれか） | リソースオブジェクト、削除の場合は `{"deleted": true, "id"}` | +| 失敗時（いずれか、`--json` 付き） | stdout に `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | -- **event** アイテム（`events`）の各フィールド: `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`。`payload` は `--full`（または `--fields payload`）を指定しない限り `{}` です。 -- **evaluation** アイテム（`evals`）の各フィールド: `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`。 -- **session** アイテム（`sessions`）の各フィールド: `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`。 +- 各 **event** アイテム（`events`）: `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`。`payload` は `--full`（または `--fields payload`）を指定しない限り `{}` になります。 +- 各 **evaluation** アイテム（`evals`）: `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`。 +- 各 **session** アイテム（`sessions`）: `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`。 -各コマンドの `--fields` は、そのアイテムのフィールド名のみを受け付けます。`sessions` と `evals` ではフィールドセットが異なるため、一方で有効な名前が他方では拒否されることがあります。 +各コマンドの `--fields` は、そのコマンドのアイテムのフィールド名のみを受け付けます。`sessions` と `evals` でフィールドのセットが異なるため、一方で有効な名前がもう一方では拒否される場合があります。 ## 次のステップ -- [CLI](/ja/agenteye/cli): インストール・認証・全コマンドのオプションリファレンス。 +- [CLI](/ja/agenteye/cli): インストール、認証、全コマンドのオプションリファレンス。 - [CLI エージェントスキル](/ja/agenteye/cli-skill): これらのレシピをコーディングエージェントが読み込めるスキルとしてパッケージ化する方法。 -- [API キー](/ja/agenteye/api-keys): CLI・SDK・コレクターが認証に使うキーの作成とスコープ設定。 -- [Python SDK](/ja/agenteye/python-sdk): Failproof AI Observability にイベントを送信して、これらのレシピがクエリできるデータを用意する方法。 \ No newline at end of file +- [API キー](/ja/agenteye/api-keys): CLI、SDK、コレクターが認証に使用するキーの作成とスコープ設定。 +- [Python SDK](/ja/agenteye/python-sdk): Failproof AI Observability にイベントを送信して、これらのレシピがクエリできるデータを用意する。 \ No newline at end of file diff --git a/docs/ja/agenteye/cli-skill.mdx b/docs/ja/agenteye/cli-skill.mdx index 7ff1d45a..847965f7 100644 --- a/docs/ja/agenteye/cli-skill.mdx +++ b/docs/ja/agenteye/cli-skill.mdx @@ -1,70 +1,70 @@ --- title: "Failproof AI Observability CLI エージェントスキル" -description: "コーディングエージェントに「今日何か壊れてる？」と聞くだけで、ライブの Failproof AI Observability データから回答を得られます。コマンドを暗記する必要はありません。" +description: "コーディングエージェントに「今日、何か壊れていますか？」と質問するだけで、ライブの Failproof AI Observability データから回答が得られます。コマンドを覚える必要はありません。" --- -コーディングエージェントに *「今日何か壊れてる？」* と聞くだけで、ライブの Failproof AI Observability データから回答を得られます。コマンドを暗記する必要はありません。**Failproof AI Observability CLI スキル**（`agenteye-cli`）は *エージェントスキル* です。これは、Claude Code や Codex などのコーディングエージェントがオンデマンドで読み込む小さな指示フォルダです。このスキルにより、エージェントは *「CI にイベントのプッシュだけできるキーを作って」* や *「発火中のインシデントを Ack して私にアサインして」* といった平易な英語のリクエストを通じて、[`agenteye` CLI](/ja/agenteye/cli) を使って Observability のデプロイを操作できるようになります。 +コーディングエージェントに *「今日、何か壊れていますか？」* と質問するだけで、ライブの Failproof AI Observability データから回答が得られます。コマンドを覚える必要はありません。**Failproof AI Observability CLI スキル**（`agenteye-cli`）は *エージェントスキル* です。これは、Claude Code や Codex などのコーディングエージェントがオンデマンドで読み込む小さなフォルダ形式の指示セットで、*「CI にイベントのプッシュだけができるキーを作成して」* や *「発火中のインシデントを ACK して自分にアサインして」* といった平易な英語のリクエストを通じて、Observability デプロイメントを [`agenteye` CLI](/ja/agenteye/cli) で操作できるようにエージェントを訓練します。 -これは**サービスでも独立したバイナリでもありません**。デプロイするものは何もありません。すでにインストール済みの CLI の上で動作し、エージェントが `agenteye --json …` を呼び出してクリーンな JSON をパースし、散文で回答します。エージェントができることはすべて、同じコマンドを入力すれば自分でもできます。 +これはサービスでも独立したバイナリでも **ありません**。デプロイするものは何もありません。すでにインストール済みの CLI の上で動作します。エージェントは `agenteye --json …` をシェルから呼び出し、整形された JSON を解析して、散文形式で回答します。スキルにできることはすべて、同じコマンドを自分で入力することでも実現できます。 --- ## 他の Failproof AI Observability インターフェースとの関係 -Failproof AI Observability では、同じデータとコントロールに到達する方法が4つあります。それぞれ補完し合う関係です： +Failproof AI Observability は、同じデータとコントロールにアクセスする 4 つの方法を提供しています。それぞれは互いを補完します。 -| インターフェース | 内容 | 実行場所 | 使いどころ | +| インターフェース | 概要 | 実行環境 | 使い所 | |---|---|---|---| | **[CLI](/ja/agenteye/cli)** | `agenteye` のコマンド・フラグリファレンス | ターミナル | 特定のコマンドを実行またはスクリプト化したいとき | -| **[CLI レシピ](/ja/agenteye/cli-recipes)** | コピペ可能な `jq`/パイプラインパターン | ターミナル / スクリプト | CLI を自動化に組み込みたいとき | -| **CLI スキル**（このドキュメント） | CLI への自然言語フロントドア | ワークステーション上のコーディングエージェント | コマンドを選ばずに *ただ聞く* だけにしたいとき | -| **[Evaluator スキル](/ja/agenteye/evaluator-skill)** | スコアリングサービスを設計・構築するための兄弟スキル | ワークステーション上のコーディングエージェント | eval スコアを *読む* のではなく *生成* したいとき | -| **[Python SDK スキル](/ja/agenteye/python-sdk-skill)** | エージェントがテレメトリを送出できるようにする兄弟スキル | ワークステーション上のコーディングエージェント | このスキルが読み取るイベントをエージェントに *生成* させたいとき | -| **[ダッシュボード内 AI アシスタント](/ja/agenteye/assistant)** | ダッシュボードに埋め込まれたチャット | サーバーサイド（ダッシュボード内） | データに対するダッシュボード内 Q&A を使いたいとき | +| **[CLI レシピ](/ja/agenteye/cli-recipes)** | コピペ用の `jq`/パイプラインパターン | ターミナル / スクリプト | CLI を自動化に組み込むとき | +| **CLI スキル**（このドキュメント） | CLI への自然言語フロントエンド | ワークステーション上のコーディングエージェント | 質問するだけでエージェントにコマンドを選ばせたいとき | +| **[Evaluator スキル](/ja/agenteye/evaluator-skill)** | スコアリングサービスを設計・構築する兄弟スキル | ワークステーション上のコーディングエージェント | eval スコアを読むのではなく *生成* したいとき | +| **[Python SDK スキル](/ja/agenteye/python-sdk-skill)** | エージェントにテレメトリを送信させるための兄弟スキル | ワークステーション上のコーディングエージェント | このスキルが読み取るイベントをエージェントに *生成* させたいとき | +| **[ダッシュボード内 AI アシスタント](/ja/agenteye/assistant)** | ダッシュボードに組み込まれたチャット | サーバーサイド（ダッシュボード内） | ダッシュボード上でデータに対して Q&A を行いたいとき | -スキル自体は独自の権限を持ちません。あなたの言葉を CLI コールに変換し、あなたとして実行するだけです： +スキル自体には独自の権限はなく、あなたの言葉を CLI 呼び出しに変換するだけで、あなたとして実行されます。 ```mermaid flowchart TD - YOU["あなた: 「発火中のインシデントを Ack して」"] --> AGENT["コーディングエージェント (Claude Code / Codex)
agenteye-cli スキルを読み込む"] + YOU["あなた: 「発火中のインシデントを ACK して」"] --> AGENT["コーディングエージェント（Claude Code / Codex）
agenteye-cli スキルを読み込む"] AGENT --> CLI["agenteye --json incidents ack ..."] CLI -->|認証済み CLI セッション| API["Observability ダッシュボード API"] ``` ### ダッシュボード内 AI アシスタントとの違い：重要な区別 -これらは影響範囲が大きく異なる2つの別ツールです： +これらは影響範囲が大きく異なる 2 つの別々のツールです。 -- **ダッシュボード内 AI アシスタント**（[AI アシスタント](/ja/agenteye/assistant)）はダッシュボードに埋め込まれたチャットで、エージェントサービスによってバックアップされています。**読み取り専用＋承認ゲート付き作成**：保存クエリやダッシュボードの下書きを作成できますが、書き込みはすべてあなたの明示的なクリック承認を求めて停止し、削除は行いません。`agent:use` 権限でゲートされており、閲覧中の組織のデータのみを参照します。 -- **CLI スキル**は *あなたの* ワークステーション上の *あなたの* コーディングエージェント内で動作し、**あなた**として `agenteye` CLI を操作します。API キーの作成・ローテーション・無効化、組織設定の変更、インシデントの解決、保存クエリの削除など、**ミューテーションを含む CLI の全機能**を実行できます。制限はあなたの CLI ログインの権限のみです。これらのコマンドを手動で実行するのと同じくらい慎重に扱ってください。 +- **ダッシュボード内 AI アシスタント**（[AI アシスタント](/ja/agenteye/assistant)）はダッシュボードに組み込まれたチャットで、エージェントサービスが支えています。**読み取り専用 + 承認ゲート付きの編集**です。保存済みクエリやダッシュボードの下書きは作成できますが、書き込み操作はすべて明示的なクリック承認を求めて停止し、削除は行いません。`agent:use` 権限でゲートされており、閲覧中の組織のデータのみを扱います。 +- **CLI スキル**はあなたのワークステーション上のコーディングエージェント内で動作し、`agenteye` CLI を **あなた** として駆動します。CLI の **全機能（API キーの作成・ローテーション・無効化、組織設定の変更、インシデントの解決、保存済みクエリの削除などのミューテーションを含む）** を実行できます。その範囲はあなたの CLI ログインの権限によってのみ制限されます。手動でコマンドを実行するのと全く同じ慎重さで扱ってください。 --- ## 前提条件 -1. **`agenteye` CLI がインストール済み**で `PATH` に通っていること（[CLI](/ja/agenteye/cli) リファレンス参照：`pipx install agenteye`）。 +1. **`agenteye` CLI がインストール済み**で `PATH` に含まれていること（[CLI](/ja/agenteye/cli) リファレンス参照：`pipx install agenteye`）。 2. **ダッシュボード URL** が設定されていること（`AGENTEYE_DASHBOARD_URL`、またはエージェントが `--base-url` を渡す）。 -3. **ログイン済みセッション**：事前に `agenteye login` を実行しておくこと。スキルはメールで送られるワンタイムコードによるログインを**完了できません**。セッションが存在しないか期限切れの場合（CLI 終了コード `4`）、`agenteye login` を実行するよう案内します。 +3. **ログイン済みセッション**：事前に `agenteye login` を自分で実行してください。スキルはメール送信されるワンタイムコードのログインを **代行できません**。セッションが存在しないか期限切れの場合（CLI 終了コード `4`）、`agenteye login` を実行するよう案内します。 --- ## 入手方法 -このスキルは Failproof AI の公開スキルコレクションで公開されています： +スキルは Failproof AI の公開スキルコレクションで公開されています。 **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -一切ゲートはありません。リポジトリは公開されており、スキルは独自の認証情報を必要としません。**公開**の `agenteye` CLI をあなたのダッシュボードに対して、あなたがログインしたセッションを使って動かすだけだからです。誰かに許可を求める必要はありません。 +アクセス制限は一切ありません。リポジトリは公開されており、スキル自体に認証情報は不要です。スキルは **公開** `agenteye` CLI を介してあなたのダッシュボードに、あなたがログインしたセッションを使って接続するだけです。誰かに依頼する必要はありません。 -スキルは独自のフォルダとして提供されており、`pipx install agenteye` パッケージには**含まれていません**。そこを探さないようにしてください。 +なお、スキルは独自のフォルダとして提供されており、`pipx install agenteye` パッケージには **含まれていません**。そちらで探さないでください。 ## スキルのインストール -最も手軽な方法は [`skills`](https://skills.sh) CLI です。フォルダを取得し、エージェントが参照する場所に配置します： +最も手軽な方法は [`skills`](https://skills.sh) CLI を使うことです。フォルダを取得してエージェントが参照する場所に配置します。 ```bash -# Claude Code、このプロジェクトのみ +# Claude Code（このプロジェクトのみ） npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code # すべてのプロジェクト（~/.claude/skills/ にインストール） @@ -74,7 +74,7 @@ npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -インストール後は他のスキルと同様に管理できます： +その後、他のスキルと同様に管理できます。 ```bash npx skills list -a claude-code # インストール済みスキルの確認 @@ -82,20 +82,20 @@ npx skills update agenteye-cli # 最新バージョンに更新 npx skills remove agenteye-cli # 削除 ``` -手動でインストールしたい場合も可能です。エージェントスキルは `SKILL.md`（およびオプションの参照ファイル）を含むフォルダに過ぎないので、コピーするだけで機能します： +手動でインストールする場合は、エージェントスキルは `SKILL.md`（およびオプションのリファレンスファイル）を含むフォルダに過ぎないため、コピーするだけで動作します。 -- **Claude Code**：`agenteye-cli/` フォルダを `~/.claude/skills/`（すべてのプロジェクト）または `<リポジトリ>/.claude/skills/`（そのリポジトリのみ）に配置します。Claude Code が自動検出します。`/skills` リストで確認するか、スキルの説明に合致する質問をするだけで確認できます。 -- **Codex（OpenAI）**：Codex は同じ `SKILL.md` を読み込みます。バンドルされている `agents/openai.yaml` で `allow_implicit_invocation: true` が設定されているため、タスクが一致すると Codex が自動でスキルを選択します。明示的に呼び出す場合は `$agenteye-cli` を使用してください。 +- **Claude Code**：`agenteye-cli/` フォルダを `~/.claude/skills/`（全プロジェクト）または `/.claude/skills/`（そのリポジトリのみ）に配置してください。Claude Code が自動的に検出します。`/skills` リストで確認するか、スキルの説明に合致する質問をしてみてください。 +- **Codex (OpenAI)**：Codex は同じ `SKILL.md` を読み込みます。同梱の `agents/openai.yaml` に `allow_implicit_invocation: true` が設定されているため、タスクが合致するときは Codex が自動的にスキルを選択します。明示的に呼び出す場合は `$agenteye-cli` を使用してください。 --- -## 安全性：エージェントが CLI を実行するときミューテーションは確認を求めません +## 安全性：エージェントが CLI を実行する際、ミューテーションは確認を求めません -> **警告：** エージェントに変更を加えさせる前に必ずお読みください。 +> **警告：** エージェントに変更を実行させる前にお読みください。 -`agenteye` CLI は通常、破壊的な操作の前に *「本当によろしいですか？」* と尋ねます。しかし、**ターミナルに接続されていない場合（コーディングエージェントが実行する方法はまさにこれです）は確認を自動スキップし、`--json` もスキップします。** そのため、エージェントに対して安全確認プロンプトは**表示されません**。 +`agenteye` CLI は通常、破壊的な操作の前に「本当によいですか？」と確認を求めます。ただし、**ターミナルに接続されていない場合（コーディングエージェントが実行する方法がまさにこれです）および `--json` を使用する場合は、この確認を自動的にスキップします**。そのため、エージェントには安全確認のプロンプトが **表示されません**。 -スキルはこれを補うように設計されています。実行するコマンドを明示し、**状態変更の前に明示的な OK を求める**よう指示されています。この規律を守ってください。エージェントを通じて Failproof AI Observability を操作するとき、*あなた自身*が確認ステップです。注意すべき状態変更コマンドは以下のとおりです： +スキルはこれを補うよう設計されています。実行するコマンドを正確に提示し、**状態変更の前にあなたの明示的な OK を求める**よう指示されています。このルールを守ってください。エージェントを通じて Failproof AI Observability を操作する場合、**あなた** が確認ステップです。注意が必要な状態変更コマンドは以下の通りです。 - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` @@ -106,54 +106,54 @@ npx skills remove agenteye-cli # 削除 - `agent rename` / `delete` - `orgs switch` -**Observe** 系（`events`、`sessions`、`evals`、`errors`、`list`、`whoami`、`orgs list/current/perms`）はすべて読み取り専用で、何も変更しません。 +**Observe** 配下（`events`、`sessions`、`evals`、`errors`、`list`、`whoami`、`orgs list/current/perms`）はすべて読み取り専用で、何も変更しません。 -エージェントは**あなた**として動作するため、あなたのログインが許可していることしかできません。権限は**組織ごと**に解決されます（[API キー](/ja/agenteye/api-keys)を参照）。権限のないコマンドは終了コード `5` と該当する権限名を返すため、エージェントは不透明に失敗するのではなく、管理者に何を依頼すればよいかを正確に伝えられます。 +エージェントは **あなた** として動作するため、あなたのログインで許可されている操作しか実行できません。権限は **組織ごとに** 解決されます（[API キー](/ja/agenteye/api-keys)参照）。権限がないコマンドは終了コード `5` と対象の権限名を返すため、エージェントは曖昧なエラーではなく、管理者に何を依頼すべきかを正確に伝えられます。 --- -## 何を聞けるか +## 利用例 -実際のやり取りの例です。まず読み取り、次に OK を待つ変更： +実際のやりとりの例を示します。まず読み取り、次に確認を求める変更です。 ```text -you ▸ Is anything broken in the last day? +you ▸ 昨日から何か壊れていますか？ -agent ▸ Running: agenteye --json errors --since 24h --aggregate - 3 error types in the last 24h. The biggest is TimeoutError - (18 hits, all on the checkout-agent), then RateLimited (5). - Want the failing sessions for TimeoutError? +agent ▸ 実行中: agenteye --json errors --since 24h --aggregate + 過去 24 時間で 3 種類のエラーがありました。最も多いのは TimeoutError + （18 件、すべて checkout-agent）、次に RateLimited（5 件）です。 + TimeoutError の失敗セッションを確認しますか？ -you ▸ Give CI a key that can only push events. +you ▸ CI にイベントのプッシュだけができるキーを作成して。 -agent ▸ This creates an API key. I'll run: +agent ▸ API キーを作成します。以下を実行します： agenteye keys create ci --add events:add - OK to proceed? + 実行してよいですか？ -you ▸ yes +you ▸ はい -agent ▸ Done. Key "ci" created with events:add only. - The secret is shown only once, so store it now. I can't reprint it. +agent ▸ 完了しました。"ci" キーが events:add 権限のみで作成されました。 + シークレットは一度しか表示されないため、今すぐ保存してください。再表示はできません。 ``` -スキルは各平易な英語の意図を適切な `agenteye` コマンドにマッピングします。有効な値を先に確認し（`list `、`whoami`）、推測せず、変更前に正確なコマンドを提示します。その他の例： +スキルは各自然言語の意図を適切な `agenteye` コマンドにマッピングします。まず有効な値を探索し（`list `、`whoami`）、推測を行わず、変更前に正確なコマンドを提示します。その他の例： -- *「過去24時間で何か壊れている・失敗しているものはある？」* → `errors --since 24h --aggregate`、その後詳細。 -- *「セッション `run-001` はなぜ失敗した？」* → `events --session-id run-001 --all` + `evals --session-id run-001`。 -- *「今週の品質トレンドは？」* → `evals --aggregate --since 7d`、その後低スコアの実行を詳しく調査。 -- *「CI にイベントのプッシュだけできるキーを作って。」* → `keys create ci --add events:add`（コマンドを提示し、作成してワンタイムシークレットを取得）。 -- *「誰がアクセス権を持っている？Dana を読み取り専用にして。」* → `users list` → `users update dana@… --permission-set read-only`（あなたに確認後）。 -- *「発火中のインシデントを Ack して私にアサインして。」* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`。 +- *「過去 24 時間で壊れている/失敗しているものはありますか？」* → `errors --since 24h --aggregate`、その後内訳を表示。 +- *「セッション `run-001` が失敗した原因は？」* → `events --session-id run-001 --all` + `evals --session-id run-001`。 +- *「今週の品質トレンドは？」* → `evals --aggregate --since 7d`、その後スコアの低いセッションを深掘り。 +- *「CI にイベントのプッシュだけができるキーを作成して。」* → `keys create ci --add events:add`（コマンドを提示してから作成し、ワンタイムシークレットを取得）。 +- *「誰がアクセス権を持っていますか？Dana を読み取り専用にしてください。」* → `users list` → `users update dana@… --permission-set read-only`（確認後）。 +- *「発火中のインシデントを ACK して自分にアサインして。」* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`。 -これらの背後にある正確なコマンド、フラグ、JSON の形式については、[CLI](/ja/agenteye/cli) リファレンスと[エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)を参照してください。 +これらの背後にある正確なコマンド、フラグ、JSON 形式については、[CLI](/ja/agenteye/cli) リファレンスと [エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)を参照してください。 --- ## 次のステップ -- **[CLI](/ja/agenteye/cli)**：`agenteye` のコマンドとフラグの完全リファレンス。 -- **[エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)**：コピペ可能な `jq` パターンと終了コードの処理。 -- **[Evaluator エージェントスキル](/ja/agenteye/evaluator-skill)**：`agenteye evals` が読み取るスコアを生成する評価器を構築するための兄弟スキル。 -- **[Python SDK エージェントスキル](/ja/agenteye/python-sdk-skill)**：`agenteye` が読み取るテレメトリを送出するようにエージェントを計装する兄弟スキル。 +- **[CLI](/ja/agenteye/cli)**：`agenteye` の完全なコマンド・フラグリファレンス。 +- **[エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)**：コピペ用の `jq` パターンと終了コードのハンドリング。 +- **[Evaluator エージェントスキル](/ja/agenteye/evaluator-skill)**：`agenteye evals` が読み取るスコアを生成する Evaluator を構築するための兄弟スキル。 +- **[Python SDK エージェントスキル](/ja/agenteye/python-sdk-skill)**：`agenteye` が読み取るテレメトリを送信するエージェントの計装を行うための兄弟スキル。 - **[AI アシスタント](/ja/agenteye/assistant)**：ダッシュボード内アシスタント（このターミナルスキルとは別物です）。 -- **[API キー](/ja/agenteye/api-keys)**：スキルが実行できる内容を制限する組織ごとの権限モデル。 \ No newline at end of file +- **[API キー](/ja/agenteye/api-keys)**：スキルの操作範囲を制限する組織ごとの権限モデル。 \ No newline at end of file diff --git a/docs/ja/agenteye/cli.mdx b/docs/ja/agenteye/cli.mdx index 1d49be65..30d705b5 100644 --- a/docs/ja/agenteye/cli.mdx +++ b/docs/ja/agenteye/cli.mdx @@ -1,34 +1,34 @@ --- title: "CLI" -description: "ターミナルまたはスクリプトから Failproof AI Observability の全機能を操作できます。ダッシュボードへのアクセスは不要です。" +description: "ターミナルまたはスクリプトから Failproof AI Observability をすべて操作できます。ダッシュボードへの往復は不要です。" --- -ターミナルまたはスクリプトから Failproof AI Observability の全機能を操作できます。ダッシュボードへのアクセスは不要です。`agenteye` CLI はデータ（セッション、イベントログ、評価）の照会と、組織管理（API キー、ユーザー、設定、アラート、インシデント、保存済みクエリ）を行います。チェックの自動化、Observability を CI に組み込む場合、またはコーディングエージェントが本番環境を検査する場合に役立ちます。すべてのコマンドは `--json` フラグに対応しているため、プロンプトでの手動操作でも、コーディングエージェント（Claude Code、Cursor）がシェルから呼び出して結果をパースする場合でも、同様に利用できます。 +ターミナルまたはスクリプトから Failproof AI Observability をすべて操作できます。ダッシュボードへの往復は不要です。`agenteye` CLI はデータ（セッション、イベントログ、評価）のクエリと、組織の管理（APIキー、ユーザー、設定、アラート、インシデント、保存済みクエリ）を担います。チェックの自動化、ObservabilityをCIに組み込む場合、またはコーディングエージェントが本番環境を検査する際に活用してください。すべてのコマンドは `--json` フラグをサポートしており、プロンプトで手動操作する場合も、コーディングエージェント（Claude Code、Cursor）がシェルアウトして結果をパースする場合にも同様に機能します。 -1 つのバイナリで以下が可能です: +1つのバイナリで以下が可能です： -- **データの読み取り**: `sessions`、`events`、`evals`、`errors`（時間・エージェント・環境・スコアでフィルタリング）。 -- **組織の管理**: `keys`、`users`、`settings`、`alerts`、`incidents`。 -- **アナリティクスの実行**: 保存済み SQL とアドホッククエリランナー（`query`）。 -- **AI アシスタントへの問い合わせ**: ダッシュボードでチャットできる読み取り専用アナリストと同一（`agent`）。 +- **データの読み取り**: `sessions`、`events`、`evals`、`errors`（時刻、エージェント、環境、スコアでフィルタリング） +- **組織の管理**: `keys`、`users`、`settings`、`alerts`、`incidents` +- **分析の実行**: 保存済みSQLとアドホッククエリランナー（`query`） +- **AIアシスタントへの問い合わせ**: ダッシュボードでチャットできるものと同じ読み取り専用アナリスト（`agent`） -> **注意:** これは `agenteye` CLI です。コレクターデーモン（`agenteye-collector`）とは異なるツールです。CLI はダッシュボードと通信し、コレクターはイベントをサーバーに送信します。 +> **注意:** これはコレクターデーモン（`agenteye-collector`）とは異なるツールである `agenteye` CLI です。CLIはダッシュボードと通信し、コレクターはサーバーにイベントを送信します。 --- ## クイックスタート -何もない状態から最初の結果を得るまで 4 行で完了します。CLI をダッシュボードに向け、サインインし、ユーザー確認を行い、直近 1 日の実行履歴を取得します: +ゼロから最初の結果を得るまで4行で完了します。CLIをダッシュボードに向け、サインインし、自分のアイデンティティを確認してから、過去1日間の実行を取得します： ```bash pipx install agenteye agenteye --base-url https://agenteye.example.com login --email you@example.com # 6桁のコードがメールで届きます agenteye whoami # ユーザーとアクティブな組織を確認 -agenteye --json sessions --since 24h # エージェント実行1件につき1行、直近24時間分 +agenteye --json sessions --since 24h # エージェント実行1件につき1行、過去24時間分 ``` -最後のコマンドは、直近のセッションの JSON オブジェクトを出力します（最新順、デフォルトで最大 50 件）。`jq` にパイプして絞り込むか、`--json` を省略するとボックス型のカラー表示テーブルが表示されます。各行には実行のステータスと、評価器によるスコアリングが行われている場合はメトリクススコアが含まれます（以下は省略形）: +最後のコマンドは最新のセッションのJSONオブジェクトを出力します（新しい順、デフォルトで最大50件）。`jq` にパイプして絞り込むか、`--json` を省略してボックス付きのカラー表示テーブルで確認できます。各行には実行のステータスと、評価器がスコアリングした場合はそのメトリクススコアが含まれます（ここでは省略形）： ```json { @@ -48,13 +48,13 @@ agenteye --json sessions --since 24h } ``` -このページの残りでは各要素について説明します: [インストール](#installation)、[サインイン](#authentication)、[設定](#configuration)、すべてのコマンドに共通する[グローバル規約](#global-options--conventions)、[完全なコマンドリファレンス](#command-reference)。 +このページの残りでは各要素を説明します：[インストール](#installation)の独立した手順、[サインイン](#authentication)、[設定](#configuration)、すべてのコマンドが共有する[グローバル規約](#global-options--conventions)、および[完全なコマンドリファレンス](#command-reference)。 --- ## インストール -CLI は **`agenteye`** という名前の公開 PyPI パッケージです。依存関係を独立して管理できるよう、隔離された環境にインストールしてください: +CLIは **`agenteye`** という名前のパブリックなPyPIパッケージです。依存関係を独立して管理できるよう、隔離された環境にインストールしてください： ```bash pipx install agenteye @@ -62,51 +62,51 @@ pipx install agenteye uv tool install agenteye ``` -Python 3.10 以上が必要です。インストールされるコマンド名は **`agenteye`** です: +Python 3.10以上が必要です。インストールされるコマンドは **`agenteye`** です： ```bash agenteye --version agenteye --help ``` -> **注意:** Failproof AI Observability の Python SDK も `agenteye` という配布名を使用しています。`pipx` または `uv tool` でインストール（共有 virtualenv への `pip install` ではなく）することで、両者の競合を避けられます。SDK が同一環境にインストールされていない場合に限り、`pip install agenteye` のみでも問題ありません。 +> **注意:** Failproof AI Observability Python SDKも `agenteye` ディストリビューション名を使用しています。`pipx` または `uv tool`（共有の仮想環境への `pip install` ではなく）でCLIをインストールすることで、両者の競合を防げます。SDKが同じ環境にインストールされていない場合のみ、`pip install agenteye` で問題ありません。 --- ## 認証 -CLI はメールで送信されるワンタイムコードを使って**ダッシュボード**に認証します: +CLIはメールで送られる使い捨てコードを使って **ダッシュボード** に認証します： ```bash agenteye login --email you@example.com -# 6桁のコードがメールで届くので、プロンプトに貼り付けてください。 +# 6桁のコードがメールで届きます。プロンプトに貼り付けてください。 ``` -セッショントークンは `~/.agenteye/cli.json`（あなただけが読み取り可能、モード `0600`）に保存され、デフォルトで 24 時間有効です。期限切れになった場合は `agenteye login` を再度実行してください。 +セッショントークンは `~/.agenteye/cli.json`（あなただけが読めるモード `0600`）に保存され、デフォルトで24時間有効です。期限が切れたら `agenteye login` を再実行してください。 ```bash agenteye whoami # 現在のユーザー、アクティブな組織、権限を表示 -agenteye logout # セッションを無効化し、保存済みトークンを削除 +agenteye logout # セッションを失効させ、保存されたトークンを削除 ``` -`whoami` はセッションが存在しない場合や期限切れでもエラーになりません。代わりに `logged_in: false` を返すため、スクリプトやエージェントが安全に認証状態を確認できます（ベース URL が設定されていない場合やダッシュボードに到達できない場合は非ゼロで終了することがあります）。 +`whoami` はセッションが存在しないか期限切れの場合でもエラーになりません。代わりに `logged_in: false` を返すため、スクリプトやエージェントが認証状態を安全に確認できます（ベースURLが設定されていない場合やダッシュボードに到達できない場合は、ゼロ以外の終了コードを返すことがあります）。 -**要件:** ダッシュボードへのサインインが許可されたメールアドレスであること（Failproof AI Observability 管理者に確認してください）、およびダッシュボードがベース URL で到達可能であること（[設定](#configuration)を参照）。コードをリクエストしても届かない場合、そのメールアドレスはまだダッシュボードアクセスが有効になっていない可能性があります。 +**要件:** あなたのメールアドレスがダッシュボードへのサインインを許可されている必要があります（Failproof AI Observabilityの管理者に確認してください）。また、ダッシュボードがベースURLで到達可能である必要があります（[設定](#configuration)を参照）。コードをリクエストしても届かない場合、そのメールアドレスはまだダッシュボードアクセスが有効になっていない可能性があります。 --- ## 組織の選択（マルチテナント） -アカウントが複数の組織に属している場合、**ログイン時**にアクティブな組織を選択してください。選択内容は保存され、以降のすべてのコマンドで使用されます: +アカウントが複数の組織に属している場合は、**ログイン時**にアクティブな組織を選択してください。保存されてそれ以降のすべてのコマンドに使用されます： ```bash -agenteye login --org acme # 認証とアクティブテナントの設定を一度に行う -agenteye orgs list # アクセス可能な組織の一覧（アクティブな組織にマーク付き） -agenteye orgs switch globex # 保存済みデフォルトを変更 -agenteye --org globex sessions # 単一コマンドでのみ上書き +agenteye login --org acme # 認証とアクティブなテナントの設定を一度に行う +agenteye orgs list # アクセス可能な組織一覧（アクティブなものにマーク付き） +agenteye orgs switch globex # 保存されているデフォルトを変更 +agenteye --org globex sessions # 単一コマンドのみ上書き ``` -組織が 1 つだけの場合は自動的に選択されるため、`--org` は不要です。複数の組織に属していてどれも選択していない場合、CLI が一覧を表示して `--org ` を付けて再実行するよう促します。アクティブな組織はすべてのリクエストでダッシュボードに送信され、権限は**組織ごと**に解決されます。`agenteye whoami` はアクティブな組織、その組織内での権限、およびすべてのメンバーシップを表示します。 +1つの組織にのみ所属している場合は自動的に選択されるため、`--org` は不要です。複数に所属していてどれも選択していない場合、CLIが一覧を表示して `--org ` で再実行するよう求めます。アクティブな組織はすべてのリクエストでダッシュボードに送信され、権限は**組織ごとに**解決されます。`agenteye whoami` はアクティブな組織、その中での権限、およびすべてのメンバーシップを表示します。 --- @@ -114,211 +114,211 @@ agenteye --org globex sessions # 単一コマンドでのみ上書き | 設定 | フラグ | 環境変数 | デフォルト | |---|---|---|---| -| ダッシュボードベース URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **必須**（デフォルトなし） | -| アクティブな組織/テナント | `--org` | `AGENTEYE_ORG` | ログイン時に選択し `~/.agenteye/cli.json` に保存 | +| ダッシュボードベースURL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **必須**（デフォルトなし） | +| アクティブな組織/テナント | `--org` | `AGENTEYE_ORG` | ログイン時に選択済み。`~/.agenteye/cli.json` に保存 | | セッショントークン | `--token` | `AGENTEYE_CLI_TOKEN` | `~/.agenteye/cli.json` から取得 | -| JSON 出力 | `--json` | `AGENTEYE_CLI_JSON` | オフ | -| TLS 検証をスキップ | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | オフ（ログイン時に保存） | +| JSON出力 | `--json` | `AGENTEYE_CLI_JSON` | オフ | +| TLS検証をスキップ | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | オフ（ログイン時に保存） | | リクエストタイムアウト（秒） | `--timeout` | _（なし）_ | 30 | -| 利用状況テレメトリの無効化 | _（なし）_ | `AGENTEYE_ANALYTICS_DISABLED`（または `DO_NOT_TRACK`） | テレメトリは現在無効です。送信は行われません | +| 使用状況テレメトリを無効化 | _（なし）_ | `AGENTEYE_ANALYTICS_DISABLED`（または `DO_NOT_TRACK`） | テレメトリは現在無効。何も送信されません | -解決順序は**フラグ → 環境変数 → 設定ファイル**です。デフォルト値はありません。コマンドごとに（`--base-url https://agenteye.example.com`）または環境変数で一度設定する必要があります（初回 `login` 後にも保存されます）: +解決の優先順位は **フラグ → 環境変数 → 設定ファイル** です。デフォルトはありません。コマンドごと（`--base-url https://agenteye.example.com`）または環境変数で一度だけ設定してください（最初の `login` 後にも保存されます）： ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -設定ディレクトリは `AGENTEYE_HOME` を優先します（SDK とコレクターで使われているのと同じ規約）。設定されている場合、`cli.json` は `$AGENTEYE_HOME/cli.json` に置かれます。 +設定ディレクトリは `AGENTEYE_HOME`（SDKとコレクターで使用されるものと同じ規約）を優先します。設定されている場合、`cli.json` は `$AGENTEYE_HOME/cli.json` に保存されます。 -### 自己署名または内部 TLS +### 自己署名または内部TLS -ダッシュボードが自己署名または内部証明書を使用した HTTPS で提供されている場合（例: 生のロードバランサーホスト名）、TLS 検証が `CERTIFICATE_VERIFY_FAILED` エラーで失敗します。証明書検証をスキップするには `--insecure` を指定してください: +ダッシュボードが自己署名または内部証明書（例：ロードバランサーのホスト名そのまま）でHTTPSを提供している場合、TLS検証は `CERTIFICATE_VERIFY_FAILED` エラーで拒否されます。`--insecure` を渡して証明書検証をスキップしてください： ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` は**ログイン時に `cli.json` に保存される**ため、以降のコマンドは自動的に検証をスキップします。フラグを繰り返す必要はありません。一時的に検証を有効にしたい場合は `--secure` を使用します。次回ログイン時に検証を再び有効にしておくこともできます。検証を無効にしているコマンドでは、CLI が stderr に警告を表示します。検証をスキップすると中間者攻撃からの保護がなくなります。これに依存する前に、ダッシュボードへのネットワークパス（VPN、プライベートサブネットなど）を信頼できることを確認してください。 +`--insecure` は**ログイン時に `cli.json` に保存される**ため、以降のコマンドでは自動的に検証がスキップされます。フラグを繰り返す必要はありません。`--secure` で1回限りの検証付き呼び出しを行うか、次回ログイン時に検証を再度有効化して保存できます。検証が無効な状態でダッシュボードに接続するコマンドを実行する前に、CLIはstderrに警告を出力します。検証をスキップすると中間者攻撃への保護がなくなります。使用する前に、ダッシュボードへのネットワークパス（VPN、プライベートサブネットなど）を信頼できることを確認してください。 --- ## テレメトリとプライバシー -> **注意:** 現在の CLI は**利用状況テレメトリを一切送信しません。** マスターキルスイッチがオンになっているため、環境にかかわらず何も送信されません。以下のセクションでは、テレメトリが将来有効化された場合のオプトアウト機能について説明します。 +> **注意:** 現在出荷されているCLIは**使用状況テレメトリを送信していません。** マスターキルスイッチがオンになっているため、環境に関係なく何も送信されません。以下のセクションは、テレメトリが将来有効化された場合のオプトアウト機能について説明しています。 -有効化された場合でも、テレメトリは**匿名の利用状況アナリティクスのみ**であり、エージェント・セッション・イベントデータは含まれません: +有効化された場合でも、テレメトリは**匿名の使用状況分析のみ**であり、エージェント、セッション、またはイベントデータは含まれません： -- **エージェント・セッション・イベントデータがインフラ外に出ることは一切ありません。** 報告されるのは CLI の利用状況のみです: コマンドとサブコマンド名（例: `keys create`）、使用したフラグの**名前**（値は含まない）、成功/終了ステータス、実行時間、および変更操作ごとのイベント（例: `api_key_created`、`query_run`）で静的な名前/列挙値と大まかなカウントのみが含まれます。ダッシュボード URL、セッショントークン、メール、組織スラッグ、リソース ID、SQL、キーシークレット、クエリフィルターは**送信されません**。オペレーターは不透明な内部 ID によってのみ識別され、メールアドレスは使用されません。 -- CLI の環境で `AGENTEYE_ANALYTICS_DISABLED=1` を設定することで**事前にオプトアウト**できます（CLI はクロスツール規約 `DO_NOT_TRACK=1` にも対応しています）。この設定はテレメトリが有効化された瞬間から効果を発揮するため、プライバシーを重視する環境では永続的にオプトアウト状態を維持できます。 -- テレメトリが有効化された場合、CLI は PostHog（`https://us.i.posthog.com`）に直接送信します。そのホストをブロックしているマシンでは何も送信されず、CLI の動作にも影響はありません。 +- **エージェント、セッション、またはイベントデータがインフラ外に出ることは一切ありません。** 報告されるのはCLIの使用状況のみです：コマンドとサブコマンド名（例：`keys create`）、使用したフラグの**名前**（値は含まれません）、成功/終了ステータスと所要時間、および変更操作のイベント（例：`api_key_created`、`query_run`）で静的な名前/enumと大まかなカウントのみ含みます。ダッシュボードURL、セッショントークン、メールアドレス、組織スラッグ、リソースID、SQL、キーシークレット、クエリフィルターは**決して送信されません**。オペレーターは不透明な内部IDでのみ識別され、メールアドレスは使用されません。 +- CLIの環境で `AGENTEYE_ANALYTICS_DISABLED=1` を設定することで**事前にオプトアウト**できます（CLIはクロスツールの `DO_NOT_TRACK=1` 規約にも対応しています）。テレメトリが有効化された瞬間から有効になるため、プライバシーを重視する環境では永続的にオプトアウトした状態を維持できます。 +- テレメトリが有効化された場合、CLIはPostHog（`https://us.i.posthog.com`）に直接送信します。そのホストがブロックされているマシンでは、何も送信されずCLIには影響がありません。 --- ## グローバルオプションと規約 -一度読んでおいてください。すべてのコマンドに適用されます。 +一度読んでください。すべてのコマンドに適用されます。 -- **グローバルオプションはコマンドの前に置きます。** `agenteye --json sessions` が正しい形式です。`agenteye sessions --json` は使用エラーになります。グローバルオプションは `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color` です。 -- **`--json` は純粋な JSON のみを stdout に出力します。** ヒューマン向けのステータス行、警告、エラーは **stderr** に出力されるため、`--json` の stdout キャプチャはステータス行が表示される場合でも `jq` へのパイプに適したクリーンな状態を保ちます。`--json` なしではボックス型のカラー表示が人間向けに表示されます。 -- **`--help` で詳細を確認できます。** すべてのコマンドとサブコマンドに `--help`（および `-h` エイリアス）があります: `agenteye -h`、`agenteye sessions -h`、`agenteye keys create -h`。トップレベルのヘルプには終了コードとグローバルオプションの一覧も含まれます。グローバルなマシンリーダブルなサーフェスダンプはありません。コマンドごとの `--help` と、2 つのレジストリ専用の `agenteye query schema`・`agenteye settings schema` を使用してください。 -- **スクリプトとエージェントでは確認プロンプトが自動スキップされます。** 作成・更新・削除コマンドはインタラクティブなターミナルでは「本当によいですか?」と確認を求めますが、**`--json` 使用時または stdin が TTY でない場合は自動スキップされます**（TTY はインタラクティブなターミナルセッションです。パイプや CI ランナーは TTY ではありません）。スクリプトやエージェントがハングすることはありません。明示的にスキップするには `--yes`/`-y` を使用します。エージェントに対してプロンプトが表示されないため、エージェントは破壊的な操作を行う前に人間に確認を求めるべきです。 -- **ページネーション:** 結果は最新順でカーソルページネーションされます（各ページには次のページを取得するためのトークンが返されます）。`--limit N`（エイリアス `-n`）は行数を制限し、**デフォルトは 50** です。`--all` は自動ページネーション（200 行ずつ）を行いますが、**`--limit` まで**しか取得しません。そのため `--all` だけでも 50 件で停止します。完全なスキャンには大きな明示的な上限を指定してください: `--all --limit 1000`。`--page-size N` はリクエストあたりのチャンクサイズを制御します（最大 200）。`--cursor ` は前のページの `next_cursor` からの再開に使用します。 -- **時間フィルター:** `--since` は相対的なウィンドウを取ります: `15m`、`1h`、`6h`、`24h`、`7d`、または `all`（ダッシュボードのプリセット）。より長いまたはカスタムの範囲（例: 直近 30 日間）には `--from`/`--to` を使用します: **`T` とタイムゾーンを含む** ISO-8601 UTC タイムスタンプ（例: `2026-06-01T00:00:00Z`）で `--since` を上書きします。スペース区切りまたはタイムゾーンなしの値は使用エラーになります。 -- **`--fields a,b,c`**（`events`、`sessions`、`evals`、`errors` で使用可）は、テーブルと `--json` の両方で出力をそれらのキーに制限します。不明な名前は有効な一覧とともに拒否されるため、フィールド名を簡単に調べられます。 -- **`--file payload.json`**（または `--file -` で stdin を読み込む）は、リソースが複雑な形状を持つ場合に完全な JSON リクエストボディを提供します（`alerts create/update`、`settings set`、`users create/update`）。保存済みクエリの SQL には代わりに `--sql @file.sql` を使用します。 -- **複数値フィルター**はカンマ区切りでセットとしてマッチします（1 つのフィルター内では OR、フィルター間では AND）: `--event-type tool_use,tool_result`。Click のオプションは可変長ではないため、`--add a b` は機能しません。`--add a,b`、フラグの繰り返し（`--add a --add b`）、またはクォート（`--add "a b"`）を使用してください。 +- **グローバルオプションはコマンドの前に置く必要があります。** `agenteye --json sessions` は正しく、`agenteye sessions --json` は使用エラーです。グローバルオプションは `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color` です。 +- **`--json` は純粋なJSONのみをstdoutに出力します。** 人間向けのステータス行、警告、エラーは **stderr** に出力されるため、ステータス行が表示されても `--json` のstdoutキャプチャはクリーンなまま `jq` にパイプできます。`--json` なしでは、人間の目のためにボックス付きのカラー表示になります。 +- **`--help` で探索できます。** すべてのコマンドとサブコマンドは `--help`（および `-h` エイリアス）を持っています：`agenteye -h`、`agenteye sessions -h`、`agenteye keys create -h`。トップレベルのヘルプには終了コードとグローバルオプションも記載されています。グローバルなマシン読み取り可能なサーフェスダンプはありません。コマンドごとの `--help` と、2つのレジストリ向けのドメイン固有コマンド `agenteye query schema` および `agenteye settings schema` を使用してください。 +- **確認プロンプトはスクリプトとエージェントでは自動スキップされます。** 作成/更新/削除コマンドはインタラクティブなターミナルでは「本当によろしいですか？」と尋ねますが、**`--json` 使用時またはstdinがTTYでない場合は自動的にスキップされる**ため（TTYとはインタラクティブなターミナルセッションで、パイプやCIランナーはそうではありません）、スクリプトやエージェントがハングすることはありません。明示的にスキップするには `--yes`/`-y` を渡します。エージェントにはプロンプトが表示されないため、破壊的な操作の前に人間に確認を求めるべきです。 +- **ページネーション:** 結果は新しい順でカーソルページネーションされます（各ページは次のページを取得するためのトークンを返します）。`--limit N`（エイリアス `-n`）は行数を制限し、**デフォルトは50**です。`--all` は自動ページネーション（200行単位）を行いますが、**`--limit` まで**に制限されるため、`--all` のみでも50件で停止します。全件取得には上限を明示的に指定してください：`--all --limit 1000`。`--page-size N` はリクエストあたりのチャンクを制御します（最大200）。`--cursor ` は前のページの `next_cursor` から再開します。 +- **時間フィルター:** `--since` は相対的な時間範囲を取ります：`15m`、`1h`、`6h`、`24h`、`7d`、または `all`（ダッシュボードのプリセット）。より長い範囲やカスタム範囲（例：過去30日間）には `--from`/`--to` を使用します：**`T` とタイムゾーンを含む** 明示的なISO-8601 UTCタイムスタンプ（例：`2026-06-01T00:00:00Z`）で `--since` を上書きします。スペース区切りやタイムゾーンのない値は使用エラーです。 +- **`--fields a,b,c`**（`events`、`sessions`、`evals`、`errors` で使用可能）は出力をそれらのキーに限定します（テーブルと `--json` の両方）。不明な名前は有効なリストと共にエラーになるため、フィールド名を調べる簡単な方法でもあります。 +- **`--file payload.json`**（または stdin を読む `--file -`）は、リソースが複雑な形状を持つ場合に完全なJSONリクエストボディを提供します（`alerts create/update`、`settings set`、`users create/update`）。保存済みクエリのSQLは代わりに `--sql @file.sql` を使用します。 +- **複数値フィルター** はカンマ区切りでセットとしてマッチングされます（1つのフィルター内はOR、フィルター間はAND）：`--event-type tool_use,tool_result`。Clickのオプションは可変長引数ではないため、`--add a b` は機能しません。`--add a,b`、フラグの繰り返し（`--add a --add b`）、またはクォート（`--add "a b"`）を使用してください。 --- ## コマンドリファレンス -### 最もよく使う 5 つのコマンド +### 最もよく使う5つのコマンド -日常的な作業のほとんどは、少数の読み取りコマンドで完結します。まずここから始め、必要に応じて以下の全機能を参照してください: +日常的な作業のほとんどはいくつかの読み取りコマンドで完結します。まずここから始め、必要に応じて以下の完全なサーフェスを活用してください： -| コマンド | 機能 | 試してみる | +| コマンド | 動作 | 試してみる | |---|---|---| -| `sessions` | エージェント実行 1 件につき 1 行: 時刻、環境、エージェント、ステータス、最新スコア。 | `agenteye --json sessions --since 24h --status error` | -| `events` | 実行内のステップごとの生のトレイル（`--full` でペイロード付き）。 | `agenteye --json events --session-id run-001 --all` | -| `evals` | 評価結果とスコア。`--aggregate` でロールアップ。 | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | エラーになったイベントのみ。`--aggregate` でタイプ別のカウント。 | `agenteye --json errors --since 24h --aggregate` | -| `list` | 有効なフィルター値を確認（エージェント、環境、モデルなど）。 | `agenteye list agents` | +| `sessions` | エージェント実行1件につき1行：時刻、環境、エージェント、ステータス、最新スコア | `agenteye --json sessions --since 24h --status error` | +| `events` | 実行内のステップごとの生のトレイル（ペイロードは `--full` を追加） | `agenteye --json events --session-id run-001 --all` | +| `evals` | 評価結果とスコア。`--aggregate` でロールアップ | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | エラーになったイベントのみ。`--aggregate` でタイプ別カウント | `agenteye --json errors --since 24h --aggregate` | +| `list` | 有効なフィルター値を探索（エージェント、環境、モデルなど） | `agenteye list agents` | -### CLI でできるすべてのこと +### CLIで可能なすべての操作 -以下に全機能を示します。CLI には **18 のトップレベルコマンド**があります。すべての読み取りコマンドは `--json` と上記のグローバルオプションに対応しています。各コマンドの詳細なフラグ一覧と JSON の形式は `agenteye -h`（または ` -h`）で確認できます。 +完全なサーフェスを以下に示します。CLIには **18のトップレベルコマンド** があります。すべての読み取りコマンドは `--json` と上記のグローバルオプションを受け付けます。詳細なフラグリストとJSONの形状については `agenteye -h`（または ` -h`）を実行してください。 -### ID 管理: `login` · `logout` · `whoami` · `orgs` · `version` · `help` +### アイデンティティ：`login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash -agenteye login --email you@example.com [--org acme] # メールによるワンタイムコード; セッションを保存 -agenteye logout # このマシンの保存済みセッションを削除 +agenteye login --email you@example.com [--org acme] # メールで届く使い捨てコード。セッションを保存します +agenteye logout # このマシンの保存済みセッションをクリア agenteye whoami # 現在のユーザー、アクティブな組織、権限 -agenteye version # CLI バージョンを表示（--version と同じ） -agenteye help # トップレベルのヘルプ（--help と同じ） +agenteye version # CLIバージョンを表示（--version と同じ） +agenteye help # トップレベルヘルプ（--help と同じ） ``` -`orgs` はアクティブなテナントを確認・切り替えます: +`orgs` はアクティブなテナントを検査・切り替えます： ```bash -agenteye orgs list # 所属組織と各組織でのロール（アクティブな組織にマーク付き） -agenteye orgs switch acme # 保存済みアクティブ組織を変更（スラッグ省略時は TTY 上で一覧から選択） -agenteye orgs current # アクティブな組織の ID カード -agenteye orgs perms # アクティブな組織でのリソース別権限 +agenteye orgs list # 組織一覧 + 各組織での自分のロール（アクティブなものにマーク付き） +agenteye orgs switch acme # 保存されているアクティブ組織を変更（スラッグを省略するとTTYでリストから選択） +agenteye orgs current # アクティブな組織のIDカード +agenteye orgs perms # アクティブな組織でのリソース別権限一覧 ``` -### 観察（読み取り専用）: `events` · `sessions` · `evals` · `errors` · `list` +### 観察（読み取り専用）：`events` · `sessions` · `evals` · `errors` · `list` -これらのコマンドは確認を必要としません。共通フィルター: `--session-id`、`--agent-id`、`--env`（`--environment` では**ない**）、時間範囲（`--since` / `--from` / `--to`）。 +これらはいずれも確認を必要としません。共有フィルター：`--session-id`、`--agent-id`、`--env`（**`--environment` ではありません**）、および時間範囲（`--since` / `--from` / `--to`）。 ```bash -# events（エイリアス: ステップごとの生のトレイル）、最新順 +# events（エイリアス：ステップごとの生のトレイル）、新しい順 agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' -# sessions: エージェント実行 1 件につき 1 行（時刻/環境/エージェント/セッション/ステータス; スコアフィルタリングなし） +# sessions：エージェント実行1件につき1行（時刻/環境/エージェント/セッション/ステータス。スコアフィルタリングなし） agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 -# evals: 評価結果とスコア; --score はメトリクスでフィルタリング、--aggregate はロールアップ +# evals：評価結果 + スコア。--score でメトリクスによるフィルタリング。--aggregate でロールアップ agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 -agenteye --json evals --aggregate --since 7d --env prod # ステータスの内訳 + キー別スコア統計 +agenteye --json evals --aggregate --since 7d --env prod # ステータスの内訳 + キーごとのスコア統計 -# errors: エラーになったイベント; --aggregate でカウント/セッション/エージェント/最終確認時刻 +# errors：エラーになったイベント。--aggregate でカウント/セッション/エージェント/最終確認日時 agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 -# list: フィルタリング前に有効なフィルター値を確認 -agenteye list envs # 他にも: agents event_types score_filters models hooks tools error_types +# list：フィルタリング前に有効なフィルター値を探索 +agenteye list envs # 他にも：agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX`（**`evals`** で使用、`sessions` ではない）は繰り返し可能で AND 結合されます。どちらの境界値も省略可能（`..0.5` は ≤ 0.5、`0.9..` は ≥ 0.9）。リクエストあたり最大 20 個のスコアフィルター。`evals --scores-full` は**人間用テーブルのみ**の表示フラグです。`+N` カウントと最初の数件の代わりに、すべてのスコアペアを表示します。`--json` では常に完全なスコアオブジェクトが返されるため、このフラグは効果がありません。**セッション全体を端から端まで読む**には、イベントトレイルと評価を組み合わせます: +`--score KEY:MIN..MAX`（**`evals`** のみ、`sessions` では使用不可）は繰り返し可能でAND結合されます。どちらの境界も省略可能です（`..0.5` は ≤ 0.5、`0.9..` は ≥ 0.9 を意味します）。1リクエストあたり最大20のスコアフィルター。`evals --scores-full` は**人間向けテーブルのみ**の表示フラグで、最初の数個 + `+N` カウントではなくすべてのスコアペアを表示します。`--json` では効果がなく、常に完全なスコアオブジェクトが返されます。**1つのセッションを最初から最後まで読む**には、イベントトレイルと評価を組み合わせてください： ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -agenteye --json evals --session-id run-001 # スコアとステータス +agenteye --json evals --session-id run-001 # スコア + ステータス ``` -### 管理（権限が必要）: `keys` · `users` · `settings` · `alerts` · `incidents` +### 管理（権限必須）：`keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: API キー。シークレットはローカルで生成され、サーバーに送信されます（サーバーはハッシュのみ保存します）。シークレットは作成/再生成時に**一度だけ**表示されます。その場で控えてください。`--json` では `key` フィールドにのみ表示されます。**名前**で参照します。 +**`keys`**: APIキー。シークレットはローカルで生成されてサーバーに送信され（サーバーはハッシュのみを保存）、作成/再生成時に**一度だけ**表示されます。その場でキャプチャしてください。`--json` の場合は `key` フィールドにのみ表示されます。**名前**で参照されます。 ```bash -agenteye keys list # アクティブなキーを先に、次に無効化済みを表示 +agenteye keys list # アクティブなキーを先に表示し、その後に失効済みを表示 agenteye keys show ci-bot -agenteye keys create ci-bot --add events:read.add # 必要なスコープのみ指定; シークレットは1回だけ表示 -agenteye keys create ops --permission-set standard --remove queries:run # プリセットをベースにして調整 +agenteye keys create ci-bot --add events:read.add # 必要なスコープのみに限定。シークレットを一度だけ表示 +agenteye keys create ops --permission-set standard --remove queries:run # プリセットを基に不要な権限を削除 agenteye keys update ci-bot --add evaluations:read --yes -agenteye keys regenerate ci-bot --yes # シークレットをローテーション（古いものは無効になります） -agenteye keys disable ci-bot --yes # 無効化 +agenteye keys regenerate ci-bot --yes # シークレットをローテーション（古いものは無効化） +agenteye keys disable ci-bot --yes # 失効 ``` -権限は `(permission-set ∪ --add) − --remove` として機能します。トークンは `slug:action`（例: `events:read`）または `slug:action.action`（1 つのリソースで複数のアクションを展開: `events:read.add` → `events:read`、`events:add`）です。プリセット: `read-only`、`standard`、`admin`。人間専用の権限（`keys:update`）はキーに付与できません。 +権限は `(permission-set ∪ --add) − --remove` として機能します。トークンは `slug:action`（例：`events:read`）または `slug:action.action` で1つのリソースに複数の操作を展開できます（`events:read.add` → `events:read`、`events:add`）。プリセット：`read-only`、`standard`、`admin`。人間専用の権限（`keys:update`）はキーには付与できません。 -**`users`**: 組織メンバー。**メールアドレス**で参照します（UUID の id も使用可能）。 +**`users`**: 組織メンバー。**メールアドレス**で参照されます（UUID idも使用可能）。 ```bash agenteye users list [--active-only] agenteye users show dev@corp.com agenteye users create dev@corp.com --permission-set standard -agenteye users update dev@corp.com --add alerts:write --remove queries:delete # 変更内容を確認して実行 -agenteye users disable dev@corp.com --yes # 保護/セルフガード付き +agenteye users update dev@corp.com --add alerts:write --remove queries:delete # 予測して確認 +agenteye users disable dev@corp.com --yes # 保護/自己保護のガードあり agenteye users enable dev@corp.com ``` -**`settings`**: 固定レジストリ（既存のキーを読み取り・変更できます。新しいキーは作成できません）。 +**`settings`**: 固定レジストリ（既存のキーを読み取り・変更できます。新しいキーを作成することはできません）。 ```bash -agenteye settings list # キー・値・型・更新日時（シークレットはマスク表示） -agenteye settings schema # 各キーが受け付ける値（型・範囲・説明） +agenteye settings list # キー・値・タイプ・更新日時（シークレットはマスク） +agenteye settings schema # 各キーの受け付ける値（タイプ・範囲・説明） agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: アラート定義。**名前**で参照します。`create` は位置引数の NAME に加え、フラグまたは `--file` による完全な JSON ボディを受け付けます。 +**`alerts`**: アラート定義。**名前**で参照されます。`create` は位置引数のNAMEとフラグ、または `--file` で完全なJSONボディを受け付けます。 ```bash agenteye alerts list agenteye alerts show high-errors -agenteye alerts create high-errors --file alert.json # NAME は必須（位置引数） +agenteye alerts create high-errors --file alert.json # NAMEは必須（位置引数） agenteye alerts update high-errors --severity critical --yes agenteye alerts test high-errors --yes # テスト通知を送信 agenteye alerts delete high-errors --yes ``` -**`incidents`**: アラートインシデント。ID で参照します（短縮 ID も使用可能）。`show` で完全なアクティビティログを表示します。操作前に確認してください。 +**`incidents`**: アラートインシデント。IDで参照されます（短縮IDも使用可能）。`show` は完全なアクティビティログを表示します。操作前に必ず確認してください。 ```bash -agenteye incidents list --state firing # 他にも: acknowledged, resolved +agenteye incidents list --state firing # 他にも：acknowledged、resolved agenteye incidents count agenteye incidents show agenteye incidents ack agenteye incidents assign you@corp.com # 担当者はオペレーターである必要があります agenteye incidents resolve --yes -agenteye incidents open --alert-id --severity critical # アラートに対して手動で開く +agenteye incidents open --alert-id --severity critical # アラートに対して手動でオープン agenteye incidents comment-add "root cause: upstream 5xx" agenteye incidents comment-list ; agenteye incidents comment-delete agenteye incidents subscribe ; agenteye incidents unsubscribe ; agenteye incidents subscribers ``` -### アナリティクスとアシスタント: `query` · `agent` +### 分析とアシスタント：`query` · `agent` -**`query`**: アナリティクスストアに対する保存済み SQL とアドホックランナー。保存済みクエリは**名前**で参照します。SQL はサーバー側で検証されます（SELECT/WITH のみ、ステートメントタイムアウト、行数上限）。 +**`query`**: 分析ストアに対する保存済みSQLとアドホックランナー。保存済みクエリは**名前**で参照されます。SQLはサーバー側で検証されます（SELECT/WITHのみ、ステートメントタイムアウト、行数上限）。 ```bash -agenteye query schema [TABLE] # アナリティクスビューのカラム構成 +agenteye query schema [TABLE] # 分析ビューのカラム構成 agenteye query run --sql "select count(*) from analytics.events" -agenteye query run errs --arg prod --limit 100 # 保存済みクエリを位置引数 $1 付きで実行 +agenteye query run errs --arg prod --limit 100 # 保存済みクエリ + 位置引数 $1 で実行 agenteye query list ; agenteye query show errs agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: 組み込みの **AI アシスタント**と会話します（ダッシュボードでチャットできる読み取り専用アナリストと同一）。チャットは短いチャット ID で参照します（プレフィックスで解決）。 +**`agent`**: 組み込みの **AIアシスタント**（ダッシュボードでチャットできるものと同じ読み取り専用アナリスト）と対話します。チャットは短いchat-idで参照されます（プレフィックス解決あり）。 ```bash -agenteye agent health # AI アシスタントが設定済み/到達可能か確認 -agenteye agent models # --model に渡せるモデルの一覧（デフォルトにマーク付き） -agenteye agent ask "which agents errored most in the last day?" # チャットを開始し、短い ID を表示 +agenteye agent health # AIアシスタントが設定済みで到達可能か確認 +agenteye agent models # --model に渡せるモデル一覧（デフォルトにマーク付き） +agenteye agent ask "which agents errored most in the last day?" # チャットを開始。短いIDを表示 agenteye agent ask --chat "and which tools did they call?" # そのチャットを継続 agenteye agent chats ; agenteye agent show agenteye agent rename --title "error triage" ; agenteye agent delete @@ -331,20 +331,20 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | コード | 意味 | |---|---| | 0 | 成功 | -| 1 | 予期しないエラー（例: ダッシュボードが 5xx を返した） | -| 2 | 使用エラー（無効な引数、不明なコマンド/フラグ、名前の衝突） | +| 1 | 予期しないエラー（例：ダッシュボードが5xxを返した） | +| 2 | 使用エラー（無効な引数、不明なコマンド/フラグ、名前の競合） | | 3 | ダッシュボードに到達できない | | 4 | 未ログインまたはセッション期限切れ。`agenteye login` を実行してください | -| 5 | 認証済みだが必要な権限がない（メッセージに権限名が表示されます） | -| 6 | 指定されたリソースが見つからない（例: 不明なセッションまたはインシデント ID） | +| 5 | 認証済みだが、アカウントに必要な権限がない（メッセージに権限名が表示されます） | +| 6 | リクエストされたリソースが見つからない（例：不明なセッションまたはインシデントID） | -これらにより CLI を安全にスクリプト化できます: コーディングエージェントは `4` で再認証を促したり、`5` で不足している権限を通知したりできます。終了コードの処理パターンと JSON 出力の形式については、[エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)を参照してください。 +これによりCLIは安全にスクリプト化できます。コーディングエージェントは `4` で再認証を促したり、`5` で不足している権限をサーフェスしたりできます。終了コード処理のパターンとJSON出力の形状については、[エージェント向けCLIレシピ](/ja/agenteye/cli-recipes)を参照してください。 --- ## 次のステップ -- **[エージェント向け CLI レシピ](/ja/agenteye/cli-recipes)**: コピー&ペーストで使えるクエリパターン、`jq` ワンライナー、`--fields` プロジェクション、終了コードの処理、JSON 出力の形式。CLI を操作するコーディングエージェント向けに書かれています。 -- **[CLI エージェントスキル](/ja/agenteye/cli-skill)**: この CLI を Claude Code / Codex のインストール可能な*スキル*としてパッケージ化し、コーディングエージェントが平易な英語のリクエストから Failproof AI Observability を操作できるようにします。 -- **[API キー](/ja/agenteye/api-keys)**: `keys create --add …` の背後にある権限モデル。 -- **[AI アシスタント](/ja/agenteye/assistant)**: `agent ask` が利用するアシスタントの有効化。 \ No newline at end of file +- **[エージェント向けCLIレシピ](/ja/agenteye/cli-recipes)**: コーディングエージェントがCLIを操作することを念頭に書かれた、コピペ可能なクエリパターン、`jq` ワンライナー、`--fields` プロジェクション、終了コード処理、JSON出力の形状。 +- **[CLIエージェントスキル](/ja/agenteye/cli-skill)**: このCLIをインストール可能な Claude Code / Codex の*スキル*としてパッケージ化し、コーディングエージェントが平易な英語のリクエストで Failproof AI Observability を操作できるようにします。 +- **[APIキー](/ja/agenteye/api-keys)**: `keys create --add …` の背後にある権限モデル。 +- **[AIアシスタント](/ja/agenteye/assistant)**: `agent ask` が対話するアシスタントの有効化。 \ No newline at end of file diff --git a/docs/ja/agenteye/codex-capture.mdx b/docs/ja/agenteye/codex-capture.mdx index 52d7a617..1a6a1f83 100644 --- a/docs/ja/agenteye/codex-capture.mdx +++ b/docs/ja/agenteye/codex-capture.mdx @@ -1,55 +1,55 @@ --- title: "Codex セッションキャプチャ" -description: "チームのローカル OpenAI Codex セッションを通常のセッションおよびイベントとして AgentEye に取り込みます — Codex の使い方を変える必要はありません。" +description: "チームのローカル OpenAI Codex セッションを通常のセッションおよびイベントとして AgentEye に取り込みます — Codex の実行方法を変更する必要はありません。" --- -エンジニアたちはすでに毎日 OpenAI Codex を使っています。Codex セッションキャプチャは、それらのコーディングセッションを通常のセッションおよびイベントとして AgentEye に取り込むことで、他の観測対象と並べて検索・再生・評価できるようにします。これは [Python SDK](/ja/agenteye/python-sdk) を補完する機能です。SDK は自分で書いたエージェントを計装するのに対し、こちらはチームがすでに行っている Codex の作業をキャプチャします — 使い方を変える必要は一切ありません。 +エンジニアはすでに毎日 OpenAI Codex を使用しています。Codex セッションキャプチャは、それらのコーディングセッションを通常のセッションおよびイベントとして AgentEye に取り込みます。これにより、観察する他のすべてのデータと並べて、セッションの検索・再生・評価が可能になります。[Python SDK](/ja/agenteye/python-sdk) を補完する機能です。SDK はあなたが作成したエージェントを計装しますが、このキャプチャ機能はチームがすでに行っている Codex の作業を — 実行方法を変えることなく — 取り込みます。 -小さなバックグラウンドコレクターが Codex のローカルセッショントランスクリプトを書き込みと同時に読み取り、AgentEye に送信します。1 台のマシンに 1 つのコレクターを置くだけで、すべてのローカル Codex サーフェスを一括でキャプチャできます — サーフェスごとのセットアップは不要です。 +小さなバックグラウンドコレクターが、Codex のローカルセッショントランスクリプトが書き込まれる際にそれを読み取り、AgentEye に送信します。マシンごとに 1 つのコレクターを設置するだけで、すべてのローカル Codex サーフェスを一度にキャプチャできます。サーフェスごとのセットアップは不要です。 -同じコレクターで他のエージェントもキャプチャできます — [OpenClaw](/ja/agenteye/openclaw-capture) や [Hermes](/ja/agenteye/hermes-capture) をご覧ください。使用しているものをそれぞれ有効にしてください。1 つのコレクターで複数を同時にキャプチャできます。 +同じコレクターで他のエージェントもキャプチャできます — [OpenClaw](/ja/agenteye/openclaw-capture) および [Hermes](/ja/agenteye/hermes-capture) をご覧ください。使用しているものをそれぞれ有効にしてください。1 つのコレクターで複数を同時にキャプチャできます。 --- -## キャプチャされる内容 +## キャプチャ対象 -**ローカル**で動作するすべての Codex サーフェスは同じオンディスクのセッショントランスクリプトを生成し、コレクターはそれらをすべて取得します。 +**ローカル**で実行されるすべての Codex サーフェスは同じディスク上のセッショントランスクリプトを生成し、コレクターがそれらをすべて取得します。 - Codex **CLI** および `codex exec` - **VS Code / IDE 拡張機能** -- セッションをローカルで実行している場合の**デスクトップアプリ** +- セッションをローカルで実行する場合の**デスクトップアプリ** -各 Codex セッションは AgentEye の[セッション](/ja/agenteye/sessions)になり、ユーザーとアシスタントのメッセージ、推論、ツール呼び出し、ツールの結果、トークン使用量が対応する[イベント](/ja/agenteye/event-stream)になります。各セッションの発生元（CLI、IDE、またはデスクトップ）も記録されるため、区別することができます。 +各 Codex セッションは AgentEye の[セッション](/ja/agenteye/sessions)になり、ユーザーとアシスタントのメッセージ、推論、ツール呼び出し、ツールの結果、トークン使用量が対応する[イベント](/ja/agenteye/event-stream)になります。各セッションの発生元サーフェス（CLI、IDE、またはデスクトップ）も記録されるため、区別することができます。 -> **クラウドセッションはキャプチャされません。** デスクトップアプリはセッションをますます Codex クラウドで実行するようになっており、マシン上にはメタデータのみが保存されます — ローカルに読み取るトランスクリプトは存在しません。ローカルで実行されたセッションのみがキャプチャされます。 +> **クラウドセッションはキャプチャされません。** デスクトップアプリはセッションを Codex クラウドで実行することが増えており、マシン上にはメタデータのみが保存されます — ローカルのトランスクリプトは存在しないため読み取ることができません。ローカルで実行されたセッションのみキャプチャされます。 --- ## 有効にする方法 -キャプチャは有効にするまでオフになっています。`events:add` 権限を持つ API キー（[API キー](/ja/agenteye/api-keys)を参照）でコレクターをインストールし、Codex キャプチャを有効にします。 +キャプチャは有効にするまで無効です。`events:add` 権限を持つ API キー（[API キー](/ja/agenteye/api-keys)を参照）を使用してコレクターをインストールし、Codex キャプチャを有効にします。 ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -これにより、コレクターのインストール、バックグラウンドサービスとしての登録、およびキャプチャの開始が行われます。動作を確認するには次のコマンドを実行してください。 +これにより、コレクターがインストールされ、バックグラウンドサービスとして登録され、キャプチャが開始されます。動作中であることを確認するには次のコマンドを実行します。 ```bash agenteye-collector health ``` -初回実行時に既存の Codex セッションが一括でバックフィルされ、その後の新しいアクティビティは数秒以内にストリーミングされます。Codex 自身のファイルは読み取り専用です — 変更・移動・削除は一切されません。また、再起動をまたいでも各セッションは正確に 1 回だけ送信されます。 +初回実行時には、既存の Codex セッションが一度バックフィルされ、その後の新しいアクティビティは数秒以内にストリーミングされます。Codex 自身のファイルは読み取りのみで — 変更・移動・削除は一切行われません — また、再起動をまたいでも各セッションは 1 回だけ送信されます。 --- ## 表示される場所 -キャプチャされたセッションは **Sessions** に表示され、そのイベントは他の観測対象エージェントと同様に **Events** ストリームに表示されます — そのため、[セッションリプレイ](/ja/agenteye/sessions)、[検索](/ja/agenteye/queries)、[評価](/ja/agenteye/evaluations)、[アラート](/ja/agenteye/alerts)もすべて利用できます。Codex エージェントでフィルタリングすると、それだけを表示できます。 +キャプチャされたセッションは **Sessions** に表示され、そのイベントは **Events** ストリームに表示されます。観察する他のエージェントと同様に扱われるため、[セッション再生](/ja/agenteye/sessions)、[検索](/ja/agenteye/queries)、[評価](/ja/agenteye/evaluations)、[アラート](/ja/agenteye/alerts)がすべて利用できます。Codex エージェントでフィルタリングすることで、それらだけを表示できます。 --- ## プライバシー -Codex トランスクリプトにはセッション全体が含まれます — コマンド出力、ファイルの内容、Codex が読み書きしたものすべてを含み、シークレットが含まれることもあります。キャプチャされたセッションはそのまま送信されるため、AgentEye にその内容を集約することが適切なマシンおよびチームに限ってキャプチャを有効にしてください。また、コレクターには `events:add` のみにスコープされたキーを使用してください。データがどのように隔離されて保管されるかについては、[セキュリティ](/ja/agenteye/security)をご覧ください。 \ No newline at end of file +Codex のトランスクリプトには、コマンドの出力、ファイルの内容、Codex が読み書きしたすべての内容を含む完全なセッションデータが含まれており、シークレット情報が含まれる場合もあります。キャプチャされたセッションはそのまま送信されます。そのため、AgentEye にそのコンテンツを集約することが適切なマシンおよびチームに対してのみキャプチャを有効にし、コレクターには `events:add` のみにスコープされたキーを使用してください。データの分離方法については[セキュリティ](/ja/agenteye/security)をご覧ください。 \ No newline at end of file diff --git a/docs/ja/agenteye/concepts.mdx b/docs/ja/agenteye/concepts.mdx index 34635b35..e7390e45 100644 --- a/docs/ja/agenteye/concepts.mdx +++ b/docs/ja/agenteye/concepts.mdx @@ -1,87 +1,87 @@ --- -title: "概念" -description: "Failproof AI Observability の用語集 — イベント、セッション、評価、監査、ファインディング、インシデントをひとつの場所で定義します。" +title: "コンセプト" +description: "Failproof AI Observability の用語集 — イベント、セッション、評価、監査、発見、インシデントを一箇所でまとめて定義します。" --- -このページでは、Failproof AI Observability が使用する用語を定義します。他のガイドで見慣れない用語があれば、ここで確認できます。最初から通読する必要はありません。ざっと目を通すか、確認したい用語が出てきたときに参照してください。 +このページでは、Failproof AI Observability で使用される用語を定義します。他のガイドで見慣れない用語があれば、ここで定義を確認できます。最初から読み通す必要はありません。ざっと眺めるか、気になる単語が出てきたときに戻ってきてください。 --- ## データモデル **イベント** -データの最小単位です。1 つのイベントは、エージェントが実行した単一のステップを記録します。`tool_use`、`model_request`、`hook_completed`、`error` などがあります。エージェントは [Python SDK](/ja/agenteye/python-sdk) を通じてイベントを送信し、**Events** ページにリアルタイムで表示されます。 +データの最小単位です。1 つのイベントは、エージェントが行った 1 ステップ（`tool_use`、`model_request`、`hook_completed`、`error` など）を記録します。エージェントは [Python SDK](/ja/agenteye/python-sdk) を通じてイベントを送信し、**イベント**ページにリアルタイムで表示されます。 **セッション** -`session_id` によって識別される、1 回のエージェント実行です。セッションは同じ ID を持つすべてのイベントをまとめたもので、**Sessions** ページの 1 行として表示され、詳細ページでは実行グラフとして描画されます。セッションは通常 `agent_start` で始まり、`agent_end` で終わります。 +`session_id` で識別される、エージェントの 1 回の実行です。セッションは同じ ID を持つすべてのイベントをまとめたもので、**セッション**ページに 1 行として集約され、詳細ページでは実行グラフとして描画されます。通常、セッションは `agent_start` で始まり `agent_end` で終わります。 **エージェント** -`agent_id` によって識別される、実行内の名前付きアクターです。1 回の実行に複数のエージェントが関与することがあります。たとえば、サマライザーのサブエージェントを生成するプランナーなどです。サブエージェントは `parent_id` を持ち、これによって Failproof AI Observability は実行グラフ上でそれぞれ独立したレーンに描画できます。 +`agent_id` で識別される、実行内の名前付きアクターです。1 回の実行に複数のエージェントが関与することがあります（例：プランナーがサマライザーのサブエージェントを生成する場合）。サブエージェントは `parent_id` を持ち、それによって Failproof AI Observability は実行グラフの独立したレーンに描画できます。 **環境** -実行が行われた場所を示すラベルです。`production`、`staging`、`dev` などがあります。SDK の設定時に一度だけ設定します。ダッシュボードのほぼすべてのページで環境によるフィルタリングが可能です。 +実行が行われた場所を示すラベルです（`production`、`staging`、`dev`）。SDK の設定時に一度だけ設定します。ダッシュボードのほぼすべてのページで環境によるフィルタリングが可能です。 **コンテキストウィンドウ使用率** -レスポンスがモデルのコンテキストウィンドウを消費した割合です。Failproof AI Observability は認識しているモデルの `model_response` イベントにこの値を付与するため、プロンプトの増大や差し迫ったコンパクションをイベントストリーム上で直接確認できます。 +レスポンスがモデルのコンテキストウィンドウを何パーセント消費したかを示す値です。Failproof AI Observability は認識しているモデルの `model_response` イベントにこの値をスタンプするため、プロンプトの肥大化や差し迫ったコンパクション（圧縮）をイベントストリーム上で直接確認できます。 --- ## 品質 **評価（Evaluation）** -完了したセッションに対して、あなたが実行するスコアリングサービスが生成する品質スコアです。評価はオプトイン方式です。評価器を接続するまで、セッションは記録されますがスコアリングは行われません。各評価には複数の名前付きスコア（例：`helpfulness`、`factuality`、`tool_efficiency`）を含めることができ、それぞれに短い根拠メモが付きます。[Evaluation suite](/ja/agenteye/evaluation-suite) を参照してください。 +完了したセッションに対して、あなたが実行するスコアリングサービスが生成する品質スコアです。評価はオプトイン式です。評価器を接続するまで、セッションは記録されますがスコアは付きません。各評価には複数の名前付きスコア（例：`helpfulness`、`factuality`、`tool_efficiency`）を含めることができ、それぞれに短い根拠メモが付きます。[評価スイート](/ja/agenteye/evaluation-suite)を参照してください。 **スコアキー** -評価器が報告する 1 つの評価軸の名前です（例：`helpfulness`）。アラートと監査は、特定のスコアキーを時系列で監視できます。 +評価器が報告する 1 つの評価軸の名前です（例：`helpfulness`）。アラートや監査は、特定のスコアキーの推移を監視できます。 **評価器（Evaluator）** -あなたのスコアリングサービスです。Failproof AI Observability は完了した実行のトランスクリプトをこのサービスに POST し、返されたスコアを保存します。デフォルトの評価器は提供されません。スコアリングのロジックはあなた自身が実装します。 +あなたのスコアリングサービスです。Failproof AI Observability は完了した実行のトランスクリプトを評価器に POST し、返されたスコアを保存します。デフォルトの評価器は提供されません。スコアリングのロジックはあなた自身が用意します。 --- ## 障害の発見と修正 **フック（Hook）** -エージェントフレームワークがステップの前後に実行するガードレールまたは副作用です。コンテンツの安全チェック、PII のマスキング、予算ガードなどが該当します。フックは `outcome`（allow、deny、modify）を持つ `hook_triggered` / `hook_completed` イベントを送信し、専用のオブザーブページを持ちます。 +エージェントフレームワークがステップの前後に実行するガードレールまたは副作用処理です（コンテンツ安全チェック、PII のリダクション、予算ガードなど）。フックは `outcome`（allow、deny、modify）を持つ `hook_triggered` / `hook_completed` イベントを送信し、専用の観察ページが用意されています。 **アラートルール** -エラー率、p95 レイテンシ、トークンコスト、または評価器のスコアなどのメトリクスが設定したしきい値を超えたときに発火するルールです。ルールが発火すると、インシデントが作成され、設定したチャンネル（メール、Slack、webhook、ダッシュボード内）に通知が送られます。[Alerts](/ja/agenteye/alerts) を参照してください。 +設定したしきい値をメトリクスが超えたときに発火するルールです（エラーレート、p95 レイテンシ、トークンコスト、評価器スコアなど）。ルールが発火するとインシデントが作成され、設定したチャンネル（メール、Slack、Webhook、ダッシュボード内）に通知されます。[アラート](/ja/agenteye/alerts)を参照してください。 **インシデント** -アラートルールが発火したときに作成されるオープンな問題です。インシデントにはライフサイクル（承認、割り当て、解決）があり、すべての操作を記録するアクティビティタイムラインを持ちます。手動で作成することもできます。 +アラートルールが発火したときに作成されるオープンな問題です。インシデントにはライフサイクル（確認、割り当て、解決）と、すべてのアクションを記録するアクティビティタイムラインがあります。手動で作成することも可能です。 **監査（Audit）** -まだルールを定義していない障害パターンをセッション横断でログから探り出す、定期的な調査です（毎時から毎週まで設定可能）。エラーのクラスター、低スコア、レイテンシの外れ値、ツール呼び出しのループ、完了しなかった実行などを検出します。アラートがすでに把握しているメトリクスを監視するのに対し、監査は次に注目すべき点を教えてくれます。[Audits](/ja/agenteye/audits) を参照してください。 +ログをセッション横断で定期的（1 時間ごと〜週 1 回）に調査し、ルールを書いていない障害パターンを掘り起こす機能です（エラークラスター、低スコア、レイテンシの外れ値、ツール呼び出しのループ、完了しなかった実行など）。アラートが既知のメトリクスを監視するのに対し、監査は次に注目すべき問題を教えてくれます。[監査](/ja/agenteye/audits)を参照してください。 -**ファインディング（Finding）** -監査実行から得られる、優先度付きかつ証拠に基づいた結果の 1 件です。ファインディングはパターンを名付け、その背後にある正確なセッションにリンクし、トリアージのライフサイクル（承認、解決、ミュート、却下）を持ちます。Failproof AI Observability は実行をまたいでファインディングを重複排除するため、既知のパターンは積み重なるのではなく更新されます。 +**発見（Finding）** +監査実行から得られる、優先順位付きで証拠に基づいた結果の 1 件です。発見はパターンを示し、その根拠となる具体的なセッションにリンクし、トリアージのライフサイクル（確認、解決、ミュート、却下）を持ちます。Failproof AI Observability は実行をまたいで発見を重複排除するため、既知のパターンは積み重なるのではなく更新されます。 **AI アシスタント** -ダッシュボード内のチャット機能で、あなたのデータを基にエージェントに関する質問に平易な言葉で回答します。デフォルトでは読み取り専用です。アシスタントが作成するもの（保存済みクエリ、ダッシュボードなど）は承認が必要であり、削除操作は一切できません。[AI assistant](/ja/agenteye/assistant) を参照してください。 +ダッシュボード内のチャット機能で、あなたのデータを元にエージェントに関する質問に平易な日本語で答えます。デフォルトは読み取り専用で、作成するもの（保存済みクエリ、ダッシュボードなど）は承認が必要であり、削除は一切行えません。[AI アシスタント](/ja/agenteye/assistant)を参照してください。 --- ## 実行環境 **組織（テナント）** -独立したワークスペースです。1 つの Failproof AI Observability インスタンスで複数の組織をホストでき、それぞれが独自のユーザー、キー、データを持ちます。すべてのダッシュボード URL は組織のスラッグ（`//…`）にスコープされます。 +隔離されたワークスペースです。1 つの Failproof AI Observability インスタンスで複数の組織をホストでき、それぞれが独自のユーザー、キー、データを持ちます。すべてのダッシュボード URL は組織スラグ（`//…`）配下にスコープされます。 **コレクター** -`agenteye-collector` は、各エージェントマシン上で動作する軽量なデーモンです。SDK がディスクに書き込んだイベントをバッチ処理し、サーバーに送信します。 +`agenteye-collector` は、各エージェントマシン上で動作する軽量デーモンです。SDK がディスクに書き込んだイベントをバッチ処理し、サーバーに送信します。 **API キー** -クライアントをサーバーに対して認証するためのスコープ付きトークンです。キーには細かい権限が設定されます（例：コレクター用の `events:add`、ダッシュボードキー用の読み取り専用スコープ）。[API keys](/ja/agenteye/api-keys) を参照してください。 +クライアントをサーバーに対して認証するスコープ付きトークンです。キーには細かい権限が付与されます（例：コレクター用の `events:add`、ダッシュボードキー用の読み取り専用スコープなど）。[API キー](/ja/agenteye/api-keys)を参照してください。 **サーバー** -インジェストおよび API サービスです。イベントを受信し、運用状態をデータベースに保存し、ダッシュボードと CLI を提供します。 +インジェストおよび API サービスです。イベントを取り込み、データベースに運用状態を保存し、ダッシュボードと CLI を提供します。 **ダッシュボード** -Web UI です。すべてのページは組織にスコープされ、サーバーの API を通じてデータを読み取ります。 +Web UI です。すべてのページは組織にスコープされ、サーバーの API を通じて読み取りを行います。 --- ## 次のステップ -- [Overview](/ja/agenteye/overview): これらのコンポーネントがどのように組み合わさるかを説明します。 -- [Observability](/ja/agenteye/observability): オブザーブのサーフェス（Events、Sessions、Models、Tools、Hooks、Errors）について説明します。 \ No newline at end of file +- [概要](/ja/agenteye/overview): これらの要素がどのように組み合わさるかを説明します。 +- [オブザーバビリティ](/ja/agenteye/observability): 観察サーフェス（イベント、セッション、モデル、ツール、フック、エラー）について説明します。 \ No newline at end of file diff --git a/docs/ja/agenteye/dashboards.mdx b/docs/ja/agenteye/dashboards.mdx index f092069a..ebbba308 100644 --- a/docs/ja/agenteye/dashboards.mdx +++ b/docs/ja/agenteye/dashboards.mdx @@ -1,46 +1,46 @@ --- title: "ダッシュボード" -description: "ライブエージェントデータをチーム全員が確認できる共有ビューに変換します。" +description: "ライブエージェントデータをチーム全体で共有できる一枚絵に変換します。" --- -ライブエージェントデータをチーム全員が確認できる共有ビューに変換します。重要なクエリをチャートとして固定しておけば、誰でも一目で同じ数値を確認できます。クエリを再実行する必要はありません。 +ライブエージェントデータをチーム全体で共有できる一枚絵に変換します。重要なクエリをチャートとしてピン留めすれば、誰もがクエリを再実行することなく、同じ数字を一目で確認できます。 -![保存済みクエリから構築されたダッシュボード：時間あたりのイベント数の折れ線グラフ、エラータイプ別の棒グラフ、レイテンシのエリアチャート、モデル別トークン数](/agenteye/images/dashboard-fleet.png) +![保存済みクエリから構築されたダッシュボード：1時間あたりのイベント折れ線グラフ、エラー種別の棒グラフ、レイテンシの面グラフ、モデル別トークン数](/agenteye/images/dashboard-fleet.png) -*1枚のボードに4つの保存済みクエリ：時間あたりのイベント数、エラータイプ別、レイテンシ、モデル別トークン数。* +*1つのボード、4つの保存済みクエリ：1時間あたりのイベント数、エラー種別、レイテンシ、モデル別トークン数。* -## チーム全員が同じ情報を見る +## チーム全員が同じ数字を見る -チャットにスクリーンショットを貼り付けたり、1日に同じクエリを何度も再実行したりする必要はもうありません。ダッシュボードはチーム全員がまったく同じビューを開ける、組織共有のボードです。元データが更新されると、チャートもそれに合わせて更新されます。ボードは常に最新の状態を保つため、古い数字をめぐって議論になることもありません。 +チャットにスクリーンショットを貼り付けたり、同じクエリを1日に5回も再実行したりする必要はありません。ダッシュボードはチーム全員が全く同じビューで開ける、組織共有のボードです。元データが変わればチャートも連動して更新されるため、ボードは常に最新の状態を保ち、古い数字をめぐる議論も起きません。 -上記のフリートダッシュボードは、日常運用に適した構成の例です。 +上のフリートダッシュボードは、日常運用に適した典型的な構成です： -- **時間あたりのイベント数**の折れ線グラフ：スループットを監視し、急激な落ち込みを検知できます -- **エラータイプ別**の棒グラフ：主要な障害カテゴリを一目で把握できます -- **レイテンシ**のエリアチャート：ユーザーから苦情が来る前に遅延を検出できます +- **1時間あたりのイベント数**の折れ線グラフ：スループットを監視し、急激な低下を検知できます +- **エラー種別**の棒グラフ：最も多い障害カテゴリを一目で把握できます +- **レイテンシ**の面グラフ：ユーザーから苦情が来る前に遅延を検知できます - **モデル別トークン数**の内訳：コストを常に把握できます ボードは `//dashboards` で確認できます。 -## 保存済みクエリをピンする +## 保存済みクエリをピン留めする -すべてのタイルは保存済みクエリから始まります。[クエリ](/ja/agenteye/queries)ライブラリ（組み込みプリセットと独自クエリ、イベントおよび評価データに対応）で目的のクエリを作成・保存し、データに合ったチャートとしてダッシュボードにピンします。時系列のトレンドには**折れ線**、カテゴリの比較には**棒**、ボリュームには**エリア**、割合の内訳には**円**グラフを選べます。 +各タイルは保存済みクエリから始まります。[クエリ](/ja/agenteye/queries)ライブラリ（組み込みプリセットとユーザー独自のクエリ、イベントと評価に対応）でクエリを作成・保存し、データに適したチャート形式でダッシュボードにピン留めします：時系列トレンドには**折れ線グラフ**、カテゴリ比較には**棒グラフ**、ボリューム表示には**面グラフ**、構成比には**円グラフ**。 -タイルは保存済みクエリをチャートとして表示しているだけなので、手動で同期する必要はありません。クエリを一度更新すれば、それを使用するすべてのダッシュボードも自動的に更新されます。 +タイルは保存済みクエリをチャートとして描画したものに過ぎないため、手動で同期する必要はありません。クエリを一度更新すれば、それを使用するすべてのダッシュボードも自動的に更新されます。 -## 量だけでなく品質も監視する +## 量だけでなく、品質も監視する -量はエージェントが動いているかどうかを示します。品質はエージェントが実際に仕事をこなしているかどうかを示します。[評価スコア](/ja/agenteye/evaluations)をダッシュボードに表示すれば、実行の品質を時系列で追跡できます。品質の低下はチャートの落ち込みとして現れるため、ユーザーから突然クレームが来るより前に気づくことができます。 +量はエージェントが忙しく動いていることを示します。品質はエージェントが実際に仕事をこなしているかを示します。ダッシュボードを[評価スコア](/ja/agenteye/evaluations)に向けると、実行の品質が時系列でどう推移しているかを追跡できるボードが得られます。品質の低下はグラフの落ち込みとして現れるため、ユーザーからのクレームより先に気づけます。 ![保存済み評価クエリから構築された品質重視のダッシュボード](/agenteye/images/dashboard-quality.png) -*品質ボードは、オペレーションの数値と並べて評価スコアを前面に表示します。* +*品質ボードは評価スコアを運用数値と並べて常に前面に表示します。* -オペレーションボードと品質ボードを並べて配置することで、チームは「正常に動いているか？」と「十分な品質か？」の両方を1か所で確認できます。クエリを再実行する必要もありません。 +運用ボードと品質ボードを並べて置けば、「正常に動作しているか？」と「十分な品質か？」の両方に、クエリを再実行することなく一か所で答えられます。 -## 関連ページ +## 関連項目 -- [クエリ](/ja/agenteye/queries)：タイルの元となるクエリを作成・保存する。 -- [評価](/ja/agenteye/evaluations)：実行にスコアを付けて品質を時系列でチャート化する。 -- [アラート](/ja/agenteye/alerts)：これらのメトリクスのしきい値を超えたときに通知を受け取る。 \ No newline at end of file +- [クエリ](/ja/agenteye/queries)：タイルの元となるクエリを作成・保存します。 +- [評価](/ja/agenteye/evaluations)：実行をスコアリングして品質の時系列グラフを作成します。 +- [アラート](/ja/agenteye/alerts)：これらのメトリクスにしきい値を設定して通知を受け取ります。 \ No newline at end of file diff --git a/docs/ja/agenteye/error-tracking.mdx b/docs/ja/agenteye/error-tracking.mdx index 75e19839..344f2e09 100644 --- a/docs/ja/agenteye/error-tracking.mdx +++ b/docs/ja/agenteye/error-tracking.mdx @@ -1,41 +1,41 @@ --- title: "エラートラッキング" -description: "エージェントが発生させたすべての障害を一カ所で確認できます。大量のエラーが発生しても、1つの問題としてグループ化されます。" +description: "エージェントが発生させたすべての失敗を一か所で確認できます。同種のエラーは1件の問題としてまとめて表示されます。" --- -エージェントが発生させたすべての障害を一カ所で確認できます。大量のエラーが発生しても、1つの問題としてグループ化されます。「何かが赤くなっている」という状態から、問題のある実行を特定するまで、ライブフィードをスクロールすることなくワンクリックで辿り着けます。 +エージェントが発生させたすべての失敗を一か所で確認できます。同種のエラーは1件の問題としてまとめて表示されるため、大量のエラーが短時間に集中しても見通しよく把握できます。「何かが赤くなっている」から「問題が起きた正確な実行」まで、ライブフィードをスクロールして探し回ることなく、ワンクリックで到達できます。 -![Errorsページ：上部に時系列の障害ヒストグラム、下部にグループ化された赤いエラー行が並び、それぞれに「+ alert」ボタンがある](/agenteye/images/errors.png) -*Errorsページ：時系列の障害ヒストグラムと、繰り返し発生した障害を1行にまとめたインシデント一覧。* +![エラーページ：上部に時系列のエラーヒストグラム、下部にグループ化された赤いエラー行、各行には「+ alert」ボタンが表示されている](/agenteye/images/errors.png) +*エラーページ：時系列のエラーヒストグラムと、繰り返し発生した失敗を1行にまとめたインシデント一覧。* -## すべての障害を自動収集 +## すべての失敗を自動収集 -エージェントが壊れたとき、ライブイベントストリームをスクロールして赤い行を見逃さないように監視し続ける必要はありません。**Errors** ページがその収集作業を代わりに行います。ダッシュボードで赤く表示されるすべての情報を1つのトリアージ画面にまとめるため、最初に目にするのは「何が壊れているか」であり、「どこを探すべきか」ではありません。 +エージェントが壊れたとき、ライブイベントストリームをスクロールして赤い行が流れ去る前に見つけようとするのは無駄な作業です。**エラー**ページがその収集を代わりに行います。ダッシュボードが赤く表示するすべての情報を1つのトリアージ画面にまとめるため、最初に目に入るのは「何が壊れているか」であり、「どこを見に行くべきか」ではありません。 -また、明らかな障害だけでなく、静かな失敗も捕捉します。明示的な `error` イベントに加え、Failproof AI Observability は `tool_result`、`hook_completed`、`agent_end` のペイロードに失敗が含まれている場合もここに表示します。エラーを返したツールや異常終了したフックも、大きな例外がスローされなかったからといって見逃されることはありません。 +また、明白なエラーだけでなく、静かな失敗もキャッチします。明示的な `error` イベントに加えて、Failproof AI Observability は `tool_result`、`hook_completed`、`agent_end` のペイロードに失敗が含まれる場合も検出します。エラーを返したツールや、異常終了したフックも、大きな例外をスローしていなければ見落とすという事態はなくなります。 -ページ上部のヒストグラムは、エラーを時系列でプロットします。一目で、これが断続的な背景ノイズなのか、数分前から始まったスパイクなのかが分かるため、すぐに対応の優先度を判断できます。 +ページ上部のヒストグラムはエラーを時系列でプロットします。一目で、これが継続的なバックグラウンドのトリクルなのか、数分前に始まったスパイクなのかが分かり、今すぐ対応すべきかどうかを即座に判断できます。 -すべてのオブザーブ画面と同様に、Errors ページは組織にスコープされており、日付範囲・環境・エージェント・セッションでフィルタリングできます。フリート全体の一覧から、実際に関心のある1つのエージェントや環境に絞り込むことが可能です。 +他のオブザーブ画面と同様に、エラーページはOrganizationにスコープされており、日付範囲・環境・エージェント・セッションでフィルタリングできます。フリート全体のリストを表示してから、実際に気になる1つのエージェントや環境に絞り込むことが可能です。 -## 何百もの同一行ではなく、1つのインシデントとして +## 同種の失敗は1インシデントとして集約 -依存関係が1つ壊れるだけで、同じエラーが1分間に何百回も発火することがあります。そのままでは、ほぼ同一の行が壁のように並び、本当に見るべき情報が埋もれてしまいます。 +壊れた依存関係が1つあるだけで、同じエラーが1分間に何百回も発生することがあります。そのまま表示すれば、ほぼ同一の行が壁のように並び、本当に見たい情報が埋もれてしまいます。 -Failproof AI Observability は、同じセッションとエラータイプを共有する繰り返しの障害を1行に折りたたみます。大量のエラーが1件のインシデントとして表示されます。ログ行ではなく問題の数を数えられるようになり、重要なシグナルが大量のノイズに埋もれることなく上位に留まります。 +Failproof AI Observability は、同じセッションとエラータイプを共有する繰り返しの失敗を1行にまとめます。大量発生したエラーも1件のインシデントとして表示されます。ログ行数ではなく問題の数を数えられるようになり、重要なシグナルが大量のノイズに埋もれることなく上部に表示され続けます。 ## 「何かが赤い」から正確なイベントへ -任意の行をクリックすると、そのランのセッション内に直接ジャンプし、失敗した正確なイベントの位置が表示されます。セッション ID をコピーしたり、問題が起きた瞬間を探してスクロールしたりする必要はありません。エージェントが壊れる直前に何をしていたかが分かる完全な実行グラフが一目で確認できる状態で、その場所に直接到達します。 +任意の行をクリックすると、そのセッション内の失敗した正確なイベントに直接ジャンプします。セッションIDをコピーする必要も、問題が起きた瞬間を探してスクロールする必要もありません。エージェントが壊れる直前に何をしていたかを把握できる完全な実行グラフが、すぐそこにある状態で、その場に到達できます。 -`alerts:write` 権限を持っている場合、各行には **+ alert** ボタンも表示されます。クリックすると Observability が新しいアラートルールを開き、同じ障害を再度検知するための設定があらかじめ入力された状態になっています。トリアージしたばかりのインシデントが、次回は二度目のサプライズではなく、通知として届くようになります。 +`alerts:write` 権限がある場合、各行には **+ alert** ボタンも表示されます。クリックすると、Observability がその失敗を再度キャッチするためのアラートルールをあらかじめ入力した状態で新規作成画面を開きます。たった今トリアージしたインシデントが、次回同じことが起きたときに通知してくれるルールになり、二度と不意打ちを食らわなくて済みます。 -**場所：** **Errors** ページはダッシュボードのオブザーブセクションにあり、`//errors` でアクセスできます。 +**場所：** **エラー**ページはダッシュボードのオブザーブセクションにあり、`//errors` でアクセスできます。 ## 関連ページ -- [Alerts](/ja/agenteye/alerts)：任意の障害をページングルールに変換します。 -- [Incidents](/ja/agenteye/incidents)：発火したアラートをオープンからリゾルブまで追跡します。 -- [Sessions](/ja/agenteye/sessions)：エラーの背後にある完全な実行を開きます。 -- [Audits](/ja/agenteye/audits)：Observability がすべての実行にわたる障害パターンを自動検出します。 \ No newline at end of file +- [アラート](/ja/agenteye/alerts): 任意の失敗を通知ルールに変換する。 +- [インシデント](/ja/agenteye/incidents): 発火したアラートをオープンからクローズまで追跡する。 +- [セッション](/ja/agenteye/sessions): 任意のエラーの背後にある完全な実行内容を開く。 +- [監査](/ja/agenteye/audits): Observability がすべての実行にわたって失敗パターンを自動検出する。 \ No newline at end of file diff --git a/docs/ja/agenteye/evaluation-suite.mdx b/docs/ja/agenteye/evaluation-suite.mdx index 9c5e9ed2..28442aec 100644 --- a/docs/ja/agenteye/evaluation-suite.mdx +++ b/docs/ja/agenteye/evaluation-suite.mdx @@ -1,22 +1,22 @@ --- title: "評価スイート" -description: "Failproof AI Observability は、完了したすべてのエージェント実行を自動的に品質スコアリングできます。小さなスコアリングサービスを用意するだけで、あとは Observability が処理します。" +description: "Failproof AI Observability は、完了したすべてのエージェント実行を自動的に品質スコアリングできます。小さなスコアリングサービスを用意するだけで、残りは Observability が処理します。" --- -Failproof AI Observability は、完了したすべてのエージェント実行を自動的に品質スコアリングできます。小さなスコアリングサービスを用意するだけで、あとは Observability が処理します。追跡したい指標（有用性、ツール効率、事実性、安全性など、選択は自由）を管理し、品質低下を早期に検知し、エージェントや環境を一目で比較できます。スコアリングはオプトイン式です。サーバーに `EVALUATOR_ENDPOINT` を設定するまでパイプラインは何もしません。 +Failproof AI Observability は、完了したすべてのエージェント実行を自動的に品質スコアリングできます。小さなスコアリングサービスを用意するだけで、残りは Observability が処理します。追跡したい評価軸（有用性、ツール効率、事実性、安全性など、自由に定義可能）を監視し、品質低下を早期に検出し、エージェントや環境をひと目で比較できます。スコアリングはオプトイン方式で、サーバーに `EVALUATOR_ENDPOINT` を設定するまでパイプラインは何もしません。 -> **注意:** スコアの次元はご自身が定義します。評価器はお好きな数値キーを返せます。Observability は送り返された内容をそのまま保存・トレンド表示・ダッシュボード表示します。 +> **注記:** スコアの評価軸はあなたが定義します。評価器は任意の数値キーを返せます。Observability はあなたが返すデータを保存・トレンド分析・表示します。 ## 概要 -1. **スコアラーを作成する。** セッションのトランスクリプトを読み込んでスコアを返す小さな HTTP サービスを立ち上げます。Observability には動作するリファレンス実装が含まれているのでコピーして使えます。[SDK を使った評価器の作成](#writing-an-evaluator-with-the-sdk) を参照してください。 -2. **Observability にエンドポイントを設定する。** サーバープロセスに `EVALUATOR_ENDPOINT`（および共有の `EVALUATOR_TOKEN`）を設定します。 -3. **スコアを確認する。** 完了したセッションはすべて自動的にスコアリングされ、セッション詳細ページ・セッション一覧グリッド・保存済みダッシュボードに結果が表示されます。 +1. **スコアラーを作成する。** セッションのトランスクリプトを読み込んでスコアを返す小さな HTTP サービスを立ち上げます。Observability には参考になる動作済みリファレンスが同梱されています。[SDK を使った評価器の作成](#writing-an-evaluator-with-the-sdk)を参照してください。 +2. **Observability に接続先を設定する。** サーバープロセスに `EVALUATOR_ENDPOINT`（および共有 `EVALUATOR_TOKEN`）を設定します。 +3. **スコアの反映を確認する。** 完了したすべてのセッションが自動的にスコアリングされ、結果はセッション詳細ページ、セッショングリッド、保存済みダッシュボードに表示されます。 -![評価サマリー、次元別スコアバー、右ペインの推論テキストを含むセッション詳細ビュー](/agenteye/images/session-detail.png) +![評価サマリー、評価軸別スコアバー、推論テキストが右パネルに表示されたセッション詳細ビュー](/agenteye/images/session-detail.png) -*評価器を設定すると、完了した各実行がスコアリングされ、結果がセッションの右ペインに表示されます。上部にサマリー、続いて各次元のスコアバーと推論テキストが表示されます。* +*評価器を設定すると、完了した各実行がスコアリングされ、結果がセッションの右パネルに表示されます。上部にサマリー、その下に評価軸別のスコアバーと推論テキストが並びます。* --- @@ -32,39 +32,39 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Observability SDK がセッションの `agent_end` イベントを送出すると、サーバーは評価をスケジュールします。次に、完全なイベントトランスクリプトを評価器サービスに POST します。評価器は次のどちらかを行えます。 +Observability SDK がセッションの `agent_end` イベントを送信すると、サーバーは評価をスケジュールします。次に、完全なイベントトランスクリプトを評価器サービスに POST します。評価器は以下のいずれかを行います。 -- **インラインで結果を返す:** `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}` を返します。結果はセッションの評価タイムラインに追記されます。`reasoning` と `summary` はオプションです。 -- **処理を遅延させる:** `{"status":"pending", "job_id":"abc-123"}` を返します。Observability は評価器が `{"status":"done", ...}` または `{"status":"error", "error":"..."}` を返すまで `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` をポーリングします。 +- **結果をインラインで返す**: `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}` を返すと、結果がセッションの評価タイムラインに追記されます。`reasoning` と `summary` はオプションです。 +- **遅延処理する**: `{"status":"pending", "job_id":"abc-123"}` を返すと、Observability は評価器が `{"status":"done", ...}` または `{"status":"error", "error":"..."}` を返すまで `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` を呼び続けます。 - ポーリング間隔はジョブごとに設定できます。`pending` レスポンスに `next_poll_secs` を含めると間隔を上書きできます。省略した場合、Observability は `GET /config` の `default_poll_interval_secs` を使用し、それもなければ `EVALUATOR_POLLING_INTERVAL_SECS`（デフォルト 10 秒）にフォールバックします。すべての値は [1 秒、1 時間] にクランプされます。 + ポーリング間隔はジョブごとに設定できます。`pending` レスポンスに `next_poll_secs` を含めることで上書きできます。指定がない場合は `GET /config` の `default_poll_interval_secs` を使用し、それもない場合はサーバーの `EVALUATOR_POLLING_INTERVAL_SECS`（デフォルト 10 秒）にフォールバックします。すべての値は [1 秒, 1 時間] の範囲にクランプされます。 -`agent_end` を送出しないセッション（クラッシュしたエージェントプロセスなど）もピックアップできます。評価器の `GET /config` が `{"inactivity_timeout_secs": 1800}` を返すと、Observability はその時間アイドル状態になったセッションを評価します。このフォールバックを無効にするには、フィールドを `null` に設定するか省略してください。 +`agent_end` を送信しなかったセッション（例: クラッシュしたエージェントプロセス）も拾えます。評価器の `GET /config` が `{"inactivity_timeout_secs": 1800}` を返すと、Observability はその時間以上アイドル状態のセッションを評価します。このフォールバックを無効にするには、フィールドを `null` に設定するか省略してください。 -`EVALUATOR_ENDPOINT` が未設定の場合、パイプラインは完全に no-op になります。 +`EVALUATOR_ENDPOINT` が未設定の場合、パイプラインは完全に no-op です。 -セッションは時間の経過とともに**複数の終端評価を蓄積できます**。各 `agent_end` イベント（およびダッシュボードからの手動再評価）ごとに新しい評価行が追記されます。これは再開された会話を評価するサポート方式です。ユーザーがエージェントを終了し、後で戻ってさらにイベントを送信し、再度エージェントを終了すると、更新された完全なトランスクリプトに対して2回目の評価が実行されます。ダッシュボードは最新の評価をヘッドラインとして表示し、以前の評価は折りたたみ可能なタイムラインとして表示します。あるセッションに対して評価が実行中の間、そのセッションの追加 `agent_end` イベントは無視されます。実行中の評価が完了した後の次のイベントで、通常どおり新しい評価がエンキューされます。 +セッションには**複数の終了評価が時系列で蓄積**されます。`agent_end` イベントのたびに（また、ダッシュボードからの手動再評価のたびに）新しい評価行が追記されます。これは再開された会話を評価するためのサポートされた方式です。ユーザーがエージェントを終了し、後で戻り、さらにイベントを送信してエージェントを再び終了すると、更新された完全なトランスクリプトに対して 2 回目の評価が実行されます。ダッシュボードは最新の評価をヘッドラインとして表示し、それ以前の評価は折りたたみ可能なタイムラインとして表示されます。あるセッションに対して評価が実行中の間、そのセッションへの追加の `agent_end` イベントは無視されます。実行中の評価が完了した後の次の `agent_end` で、通常通り新しい評価がエンキューされます。 -アイドル状態フォールバックは再開されたセッションでも再び動作します。以前の終端評価後に新しいイベントが届き、その後セッションが `inactivity_timeout_secs` を超えてアイドル状態になった場合、新しい評価がエンキューされます。 +アイドルタイムアウトのフォールバックは再開されたセッションにも適用されます。以前の終了評価の後に新しいイベントが到着し、セッションが再び `inactivity_timeout_secs` を超えてアイドル状態になると、新しい評価がエンキューされます。 -一時的な障害（5xx、429、タイムアウト、ネットワークエラー）は `EVALUATOR_MAX_ATTEMPTS` に達するまで指数バックオフで再試行されます。4xx レスポンスは終端扱いです。Observability は水平スケールされた複数のサーバーインスタンスで安全に実行できます。同じセッションが同時に2回ディスパッチされないようにワークが分割されます。 +一時的な障害（5xx、429、タイムアウト、ネットワークエラー）は `EVALUATOR_MAX_ATTEMPTS` まで指数バックオフで再試行されます。4xx レスポンスは終了扱いです。Observability は複数の水平スケールされたサーバーインスタンスで安全に実行できます。同じセッションが同時に 2 回ディスパッチされないようにワークが分割されます。 --- ## HTTP コントラクト -認証が必要なすべてのルートは**ベアラートークン認証**を使用します。両側で同じ値を設定する必要があります。 +認証が必要なすべてのルートは**ベアラートークン認証**を使用します。同じ値を両側に設定する必要があります。 - Observability サーバー: 環境変数 `EVALUATOR_TOKEN` -- 評価器サービス: 同じ方法で設定（`agenteye-evaluator` SDK は慣例として `EVALUATOR_TOKEN` を読み込みます） +- 評価器サービス: 同様に設定（`agenteye-evaluator` SDK は慣例として `EVALUATOR_TOKEN` を読み取ります） -`EVALUATOR_TOKEN` が未設定の場合、サーバーは `Authorization` ヘッダーを送信しません。評価器は匿名リクエストを受け付けることができますが、内部ネットワーク専用であれば問題ありませんが、公開インターネット上では非推奨です。 +`EVALUATOR_TOKEN` が未設定の場合、サーバーは `Authorization` ヘッダーを送信しません。評価器は匿名リクエストを受け付けることができますが、これは内部ネットワーク専用環境では問題ありませんが、公開インターネット上では推奨されません。 -### 評価器が提供するルート +### 評価器が提供すべきルート | ルート | ボディ / パラメータ | レスポンス | |---|---|---| -| `GET /health` | なし | `{"status":"ok"}` （オープン、認証不要） | +| `GET /health` | なし | `{"status":"ok"}` （認証不要、オープン） | | `GET /config` | なし | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | | `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` または `{"status":"pending", "job_id":"..."}` | | `GET /evaluate/{id}` | なし | `/evaluate` と同じレスポンス形式 | @@ -88,7 +88,7 @@ Observability SDK がセッションの `agent_end` イベントを送出する ### レスポンス形式 -**同期（done）:** +**同期（完了）:** ```json { @@ -102,7 +102,7 @@ Observability SDK がセッションの `agent_end` イベントを送出する } ``` -`reasoning`（スコアごとの根拠マップ）と `summary`（全体の概要段落）はどちらもオプションです。`reasoning` のキーは `scores` のキーと一致させてください。ダッシュボードは各エントリをスコアバーの下にインライン表示します。`scores` のみを返す旧来の評価器もそのまま動作します。`reasoning` と `summary` は null として扱われ、対応する UI 要素は省略されます。 +`reasoning`（スコアごとの根拠マップ）と `summary`（全体的な 1 段落の説明文）はどちらもオプションです。`reasoning` のキーは `scores` のキーに対応しているべきです。ダッシュボードは各エントリをスコアバーの下にインライン表示します。`scores` のみを返す旧来の評価器はそのまま動作します。`reasoning` と `summary` は null として扱われ、対応する UI 要素は省略されます。 **非同期（遅延）:** @@ -110,25 +110,25 @@ Observability SDK がセッションの `agent_end` イベントを送出する { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` はオプションです。省略した場合、サーバーは `/config` の `default_poll_interval_secs`、次に独自の `EVALUATOR_POLLING_INTERVAL_SECS` 環境変数にフォールバックします。 +`next_poll_secs` はオプションです。省略した場合、サーバーは `/config` の評価器の `default_poll_interval_secs` にフォールバックし、それもない場合は自身の `EVALUATOR_POLLING_INTERVAL_SECS` 環境変数を使用します。 -**評価器側の終端エラー:** +**評価器側の終了エラー:** ```json { "status": "error", "error": "model service unavailable" } ``` -サーバーはその他の 2xx ボディをプロトコルエラーとして扱い、セッションに終端 `error` を記録します。 +サーバーはそれ以外の 2xx ボディをプロトコルエラーとして扱い、セッションに終了 `error` を記録します。 --- ## SDK を使った評価器の作成 -HTTP コントラクトを手動で実装する必要はありません。`agenteye-evaluator` Python パッケージは、認証・ルーティング・リクエスト/レスポンス形式を処理する型付き FastAPI ラッパーを提供します。 +HTTP コントラクトを手動で実装する必要はありません。`agenteye-evaluator` Python パッケージは、認証、ルーティング、リクエスト/レスポンス形式を処理する型付き FastAPI ラッパーを提供します。 -Failproof AI Observability には、トランスクリプトの形状から `helpfulness`、`tool_efficiency`、`factuality` をスコアリングする**動作するリファレンス評価器**も含まれています。出発点としてコピーし、独自のロジック（LLM ジャッジ、ルールエンジンなど、品質基準に合ったもの）に置き換えてください。 +Failproof AI Observability には、トランスクリプトの形式から `helpfulness`、`tool_efficiency`、`factuality` をスコアリングする**動作済みリファレンス評価器**も同梱されています。これをコピーして出発点として使い、LLM ジャッジ、ルールエンジン、品質基準に合わせた独自のロジックに置き換えてください。 -最小限の評価器: +最小限の評価器の例: ```python import os @@ -147,9 +147,9 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -`app` インスタンスはあらゆる ASGI サーバーで動作するため、`uvicorn module:app` で起動できます。 +`app` インスタンスは任意の ASGI サーバーで動作するため、`uvicorn module:app` で起動できます。 -重い処理を遅延させる必要がある評価器では、代わりに `JobPending` を返し、`@app.job_lookup` ハンドラーを登録してください。Observability サーバーは評価器が終端ステータスを返すか、`EVALUATOR_MAX_POLL_DURATION_SECS` の上限（デフォルト 1 時間）に達するまで `GET /evaluate/{job_id}` をポーリングします。 +高コストな処理を遅延させる必要がある評価器では、代わりに `JobPending` を返し、`@app.job_lookup` ハンドラーを登録してください。Observability サーバーは評価器が終了ステータスを返すか、`EVALUATOR_MAX_POLL_DURATION_SECS` の上限（デフォルト 1 時間）に達するまで `GET /evaluate/{job_id}` をポーリングします。 完全な API リファレンス、非同期パターン、イベントスキーマは `agenteye-evaluator` SDK の README に記載されています。 @@ -157,9 +157,9 @@ def run(req: EvalRequest) -> EvalResponse: ## 評価器の実行 -評価器は**ご自身のサービス**です。Failproof AI Observability はデフォルトの評価器を提供しないため、ご自身のサービスを実行している場所でビルドして実行してください。任意の ASGI サーバー（例: `uvicorn my_evaluator:app`）で動作します。[HTTP コントラクト](#http-contract) の `/health`、`/config`、`/evaluate` ルートを提供し、サーバーからアクセスできるように設定してください（[サーバーの設定](#configuring-the-server) を参照）。 +評価器は**あなた自身のサービス**です。Failproof AI Observability はデフォルトの評価器を同梱していないため、自分のサービスを実行する環境でビルドして実行します。任意の ASGI サーバー（例: `uvicorn my_evaluator:app`）で動作します。[HTTP コントラクト](#http-contract)に記載された `/health`、`/config`、`/evaluate` ルートを提供し、サーバーに接続先を設定してください（[サーバーの設定](#configuring-the-server)を参照）。 -評価器に到達できるようになると、`GET /health` が `{"status":"ok"}` を返します。エージェントがエンドツーエンドで実行された後、サーバーの `GET /evaluations` は `status: "done"` と評価器が生成したスコアを含む行を返します。 +評価器に到達可能になると、`GET /health` が `{"status":"ok"}` を返します。エージェントがエンドツーエンドで実行された後、サーバーの `GET /evaluations` は `status: "done"` と評価器が返したスコアを含む行を返します。 --- @@ -169,20 +169,20 @@ def run(req: EvalRequest) -> EvalResponse: | 環境変数 | 意味 | |---|---| -| `EVALUATOR_ENDPOINT` | 評価器のベース URL（`http://evaluator:9000`）。未設定の場合、パイプラインは無効化されます。 | +| `EVALUATOR_ENDPOINT` | 評価器のベース URL（例: `http://evaluator:9000`）。未設定の場合、パイプラインは無効になります。 | | `EVALUATOR_TOKEN` | ベアラートークン。評価器サービスに設定された値と一致する必要があります。 | | `EVALUATOR_WORKERS` | サーバーインスタンスあたりのワーカータスク数（デフォルト 2）。 | -| `EVALUATOR_CLAIM_BATCH` | ワーカーティックごとにクレームする行数（デフォルト 4）。バッチは**並行して**処理されます。評価器エンドポイントへの実効並行数は `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` になります。 | -| `EVALUATOR_POLL_IDLE_SECS` | 評価が不要なときにワーカーがディスパッチ試行の間にスリープする時間（デフォルト 2 秒）。 | -| `EVALUATOR_POLLING_INTERVAL_SECS` | レスポンスごとの `next_poll_secs` も評価器の `default_poll_interval_secs` も設定されていない場合の `GET /evaluate/{id}` ポーリング間隔の最終フォールバック（デフォルト 10 秒）。 | +| `EVALUATOR_CLAIM_BATCH` | ワーカーティックあたりの処理行数（デフォルト 4）。バッチは**並行処理**されます。評価器エンドポイントへの実効並行数は `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` です。 | +| `EVALUATOR_POLL_IDLE_SECS` | 評価が不要な場合にワーカーがディスパッチ試行の間にスリープする時間（デフォルト 2 秒）。 | +| `EVALUATOR_POLLING_INTERVAL_SECS` | レスポンスごとの `next_poll_secs` も評価器の `default_poll_interval_secs` も設定されていない場合の `GET /evaluate/{id}` のポーリング間隔の最終フォールバック（デフォルト 10 秒）。 | | `EVALUATOR_REQUEST_TIMEOUT_MS` | リクエストごとのタイムアウト（デフォルト 30000）。 | -| `EVALUATOR_MAX_ATTEMPTS` | この回数の一時的な障害後、結果が終端 `error` として記録されます（デフォルト 5）。 | +| `EVALUATOR_MAX_ATTEMPTS` | この回数だけ一時的な障害が発生すると、結果は終了 `error` として記録されます（デフォルト 5）。 | | `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` のポーリング間隔（デフォルト 300）。 | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | セッションがポーリングキューに残れる最大ウォールクロック時間。この時間を超えると `timeout` として終了されます（デフォルト 3600 秒）。永遠に `pending` を返し続ける評価器を防ぎます。 | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | セッションがポーリングキューに残れる最大ウォールクロック時間。この時間を超えると `timeout` として終了します（デフォルト 3600 秒）。`pending` を返し続ける評価器に対するガードです。 | -自動スコアリングを有効にするには、サーバーに `EVALUATOR_ENDPOINT` と `EVALUATOR_TOKEN` の両方を設定し、サーバーを再起動して変更を反映させてください。`EVALUATOR_ENDPOINT` が未設定の場合、パイプラインは no-op のままです。 +自動スコアリングを有効にするには、サーバーに `EVALUATOR_ENDPOINT` と `EVALUATOR_TOKEN` の両方を設定し、変更を反映させるためにサーバーを再起動します。`EVALUATOR_ENDPOINT` が未設定の場合、パイプラインは no-op のままです。 -上記のチューニングパラメータはオプションです。デフォルト値を変更する必要がある場合のみ、対応する環境変数をサーバーに設定してください。 +上記のチューニングパラメータはオプションです。デフォルト値を上書きする必要がある場合にのみ、対応する環境変数をサーバーに設定してください。 --- @@ -190,111 +190,111 @@ def run(req: EvalRequest) -> EvalResponse: | メソッド | パス | 必要な権限 | 目的 | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | 終端結果を照会します。`session_id`、`agent_id`、`environment`、`status`（`done`/`error`/`timeout`）、`ts_from`、`ts_to`、`cursor`、`limit`、`score_filters`、`latest_per_session` をサポートします。`limit` のデフォルトは 50 で上限は 200 です（1000 が上限の `/events` とは異なります）。`environment` はカンマ区切りリストを受け付けます（例: `environment=prod,staging`）。単一の値も引き続き使用できます。`latest_per_session=true` にすると、レスポンスには `session_id` ごとに最大 1 行（`completed_at` が最新のもの）が含まれます。セッションの評価タイムラインを現在のヘッドラインに折りたたむためにセッション一覧ページで使用されます。デフォルトは false（完全な履歴を返します）。 | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | フィルタリングされたスライスの評価ヘルスをロールアップします。総数、done/error/timeout の内訳、スコアキーごとの統計（任意の `scores` キーにわたる count/avg/min/max/p50）、時間バケット化されたタイムラインを返します。**`/evaluations` と同じフィルターパラメータ**に加えて `featured_keys`（トレンド表示するスコアキーの CSV）と `latest_per_session` を受け付けます。ダッシュボード機能を動かします。メトリクスはサンプリングではなく、マッチするセットの全体にわたって正確です。 | -| `GET` | `/evaluations/environments` | `evaluations:read` | `evaluations` テーブルから個別の環境値を返します。評価可能データにスコープされたフィルタードロップダウンの入力に使用されます。 | -| `GET` | `/evaluation-jobs` | `evaluations:read` | 処理中の評価の可視性を提供します。`status`（`pending`/`polling`）でフィルタリングできます。 | -| `GET` | `/events` | `events:read` | セッションの生イベントをストリームします。`session_id`、`agent_id`、`event_type`（CSV）、`environment`（CSV）、`ts_from`、`ts_to`、`cursor`、`limit`、`order` をサポートします。`order` は `desc`（新しい順、デフォルト）または `asc`（古い順）です。認識されない値は `desc` にフォールバックします。レスポンスの `next_cursor`（イベント ID）でカーソルページネーションします。`cursor` として渡すと次のページを取得できます。`asc` ではそのID以降のイベント、`desc` ではそのID以前のイベントが返されます。`limit` のデフォルトは 50 で上限は 1000 です。 | -| `GET` | `/sessions/:session_id/export` | `events:read` | このセッションで評価器が受け取る正確な JSON ボディを `session-.json` という名前のダウンロード可能な添付ファイルとして返します。本番セッションを `agenteye-evaluator` でオフラインテストするためのリプレイに便利です。バイトは評価器パイプラインが送信するものとバイト単位で同一です。 | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | セッションの新しい評価をエンキューします。以前の評価が存在するかどうかに関係なく実行されます。新しい結果は前の結果を上書きするのではなく、セッションの評価タイムラインに**追記**されるため、以前のスコアは履歴として残ります。エンキュー成功時は `202`、不明なセッションには `404`、評価がすでに進行中の場合は `409` を返します。新しい評価器をデプロイした後や、`agent_end` を送出しなかったセッションに使用してください。 | +| `GET` | `/evaluations` | `evaluations:read` | 終了結果のクエリ。`session_id`、`agent_id`、`environment`、`status`（`done`/`error`/`timeout`）、`ts_from`、`ts_to`、`cursor`、`limit`、`score_filters`、`latest_per_session` をサポート。`limit` のデフォルトは 50、上限は 200（1000 が上限の `/events` とは異なる点に注意）。`environment` はカンマ区切りリストを受け付けます（例: `environment=prod,staging`）。単一の値も引き続き動作します。`latest_per_session=true` の場合、レスポンスには `session_id` ごとに最大 1 行（`completed_at` が最新のもの）が含まれます。これはセッションの評価タイムラインを現在のヘッドラインに折りたたむセッションリストページで使用されます。デフォルトは false（完全な履歴を返す）。 | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | フィルタリングされたスライスの評価ヘルスのロールアップ: 総数、done/error/timeout の内訳、スコアキーごとの統計（任意の `scores` キーにわたる count/avg/min/max/p50）、時間バケット化されたタイムライン。`/evaluations` と**同じフィルターパラメータ**に加えて `featured_keys`（トレンド表示するスコアキーの CSV）と `latest_per_session` を受け付けます。ダッシュボード機能を動作させます。メトリクスは一致するセット全体に対して正確に計算され、サンプリングされません。 | +| `GET` | `/evaluations/environments` | `evaluations:read` | `evaluations` テーブルから個別の環境値を取得します。評価データにスコープされたフィルタードロップダウンの生成に使用されます。 | +| `GET` | `/evaluation-jobs` | `evaluations:read` | 実行中の評価の可視化。`status`（`pending`/`polling`）でフィルタリング可能。 | +| `GET` | `/events` | `events:read` | セッションの生イベントのストリーム取得。`session_id`、`agent_id`、`event_type`（CSV）、`environment`（CSV）、`ts_from`、`ts_to`、`cursor`、`limit`、`order` をサポート。`order` は `desc`（新しい順、デフォルト）または `asc`（古い順）。不明な値は `desc` にフォールバックします。レスポンスの `next_cursor`（イベント ID）を使用してカーソルページネーションを行います。これを `cursor` として渡すと次のページが取得できます。`asc` では次のページはその ID 以降のイベント、`desc` ではその ID 以前のイベントになります。`limit` のデフォルトは 50、上限は 1000。 | +| `GET` | `/sessions/:session_id/export` | `events:read` | このセッションに対して評価器が受信する正確な JSON ボディを、`session-.json` という名前のダウンロード可能な添付ファイルとして返します。本番セッションを `agenteye-evaluator` でオフラインテスト用に再生する際に便利です。バイトは評価器パイプラインが送信するものと完全に一致します。 | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | セッションに対して新しい評価をエンキューします。以前の評価が存在するかどうかに関わらず実行されます。新しい結果は、以前の結果を上書きするのではなく、セッションの評価タイムラインに**追記**されるため、以前のスコアは履歴として残ります。エンキュー時に `202`、不明なセッションには `404`、評価が既に実行中の場合は `409` を返します。新しい評価器をデプロイした後、または `agent_end` を送信しなかったセッションに対して使用します。 | -### スコア範囲でのフィルタリング: `score_filters` +### スコア範囲によるフィルタリング: `score_filters` -`GET /evaluations` はオプションの `score_filters` パラメータを受け付けます。これにより `scores` オブジェクト内の数値で結果を絞り込めます。パラメータは `key:min..max` エントリのカンマ区切りリストです。どちらの境界も省略できます。複数のエントリは論理 AND で結合されます。指定したキーが存在しない行や非数値の行は除外されます。リクエストには最大 20 のフィルターエントリを含められます。超過した場合は HTTP 400 が返されます。 +`GET /evaluations` はオプションの `score_filters` パラメータを受け付け、`scores` オブジェクト内の数値によって結果を絞り込みます。このパラメータは `key:min..max` エントリのカンマ区切りリストで、どちらの境界も省略できます。複数のエントリは論理 AND で結合されます。指定されたキーが存在しないか数値でない行は除外されます。1 つのリクエストに設定できるフィルターエントリは最大 20 件で、超過した場合は HTTP 400 が返されます。 例: ```text # helpfulness が [0.5, 0.8] の範囲 GET /evaluations?score_filters=helpfulness:0.5..0.8 -# tool_efficiency が最大 0.3（下限なし） +# tool_efficiency が 0.3 以下（下限なし） GET /evaluations?score_filters=tool_efficiency:..0.3 -# helpfulness >= 0.5 かつ factuality >= 0.9 +# helpfulness >= 0.5 AND factuality >= 0.9 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` -各 `/evaluations` レスポンスオブジェクトには以下のフィールドが含まれます: +各 `/evaluations` レスポンスオブジェクトのフィールド: | フィールド | 型 | 備考 | |---|---|---| -| `evaluation_id` | string (UUID) | この終端評価の標準識別子。各終端評価に新しい UUID が割り当てられます。1 つのセッションが複数持てます。 | +| `evaluation_id` | string (UUID) | この終了評価の正規識別子。各終了評価には新しい UUID が割り当てられます。1 つのセッションに複数保持できます。 | | `id` | string (UUID) | `evaluation_id` と同じ値を持つ後方互換エイリアス。 | -| `session_id` | string | この評価が実行されたセッション。セッションはタイムライン内に複数の評価を持てます。 | -| `agent_id` | string | セッションを生成したエージェントを識別します。 | +| `session_id` | string | この評価が実行されたセッション。セッションはタイムラインに複数の評価を持てます。 | +| `agent_id` | string | セッションを生成したエージェントの識別子。 | | `environment` | string | セッションからコピーされた環境ラベル。 | | `status` | enum | `"done"`、`"error"`、`"timeout"` のいずれか。 | | `scores` | object \| null | 評価器が返したスコア。 | -| `reasoning` | object \| null | 評価器が返したオプションのスコアごとの根拠マップ。キーは通常 `scores` のキーと一致します。ダッシュボードは各エントリをスコアバーの下に表示します。 | -| `summary` | string \| null | 評価器が返したオプションの全体概要段落。ダッシュボードはこれをスコア内訳の上に評価のヘッドラインとして表示します。 | -| `error` | string \| null | `"error"` / `"timeout"` 時のみ設定されます。 | +| `reasoning` | object \| null | 評価器が返したスコアごとのオプションの根拠マップ。キーは通常 `scores` のキーと対応しています。ダッシュボードは各エントリをスコアバーの下に表示します。 | +| `summary` | string \| null | 評価器が返したオプションの全体的な 1 段落の説明文。ダッシュボードはこれをスコア内訳の上に評価のヘッドラインとして表示します。 | +| `error` | string \| null | `"error"` / `"timeout"` の場合のみ入力されます。 | | `attempt_count` | integer | ディスパッチ試行回数（1 以上）。 | | `duration_ms` | integer \| null | 最終試行の所要時間。 | -| `completed_at` | string (ISO 8601 UTC) | 終端結果が記録された時刻。結果は `completed_at` の降順（新しい順）でソートされます。 | -| `created_at` | string (ISO 8601 UTC) | `completed_at` と同じタイムスタンプ（書き込み一度のセマンティクス）。 | +| `completed_at` | string (ISO 8601 UTC) | 終了結果が記録された日時。結果は `completed_at` の降順（新しい順）で並べられます。 | +| `created_at` | string (ISO 8601 UTC) | `completed_at` と同じタイムスタンプを持ちます（書き込み一回限りのセマンティクス）。 | --- ## 権限 -| 権限 | 付与される操作 | +| 権限 | 付与する操作 | |---|---| | `evaluations:read` | 評価結果の一覧表示、ダッシュボードでのスコア閲覧、ダッシュボードヘルスメトリクスの読み込み。 | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` またはダッシュボードの再評価ボタンからセッションの評価を手動でエンキュー。 | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` またはダッシュボードの再評価ボタンを使用してセッションの評価を手動でエンキューする。 | | `dashboards:read` | 保存済みダッシュボードの閲覧（メトリクスの読み込みには `evaluations:read` も必要）。 | | `dashboards:write` | ダッシュボードの作成と編集。 | | `dashboards:delete` | ダッシュボードの削除。 | -ブートストラップ管理者（`ADMIN_KEY`、`ADMIN_EMAIL`）はこれらすべてを自動的に受け取ります。 +ブートストラップ管理者（`ADMIN_KEY`、`ADMIN_EMAIL`）はこれらすべての権限を自動的に受け取ります。 --- -## 結果の閲覧 +## 結果の確認 -- **`/sessions/`**: イベントタイムラインと、セッションのスコアおよびディスパッチ試行からのエラーを表示する右ペイン。キーに `evaluations:trigger` 権限がある場合、エクスポートボタンの横に**再評価**ボタンが表示されます。`agent_end` を送出しなかったセッションや、新しい評価器をデプロイした後にスコアを更新する際に便利です。ダッシュボードは新しい結果をポーリングし、届いた時点で右ペインを更新します。 -- **`/sessions`**: フィルタリング可能なセッション一覧グリッド。スコア列で各セッションの評価ステータスとスコアを一目で確認できます。 -- **`/dashboards`**: 保存済みの評価ヘルスビュー（以下の[ダッシュボード](#dashboards)を参照）。 +- **`/sessions/`**: イベントタイムラインと、セッションのスコアおよびディスパッチ試行からのエラーを表示する右パネル。キーに `evaluations:trigger` 権限がある場合、エクスポートボタンの横に**再評価**ボタンが表示されます。これは `agent_end` を送信しなかったセッションや、新しい評価器をデプロイした後にスコアを更新する際に便利です。ダッシュボードは新しい結果をポーリングし、結果が得られたら右パネルを更新します。 +- **`/sessions`**: フィルタリング可能なセッショングリッド。スコアカラムには各セッションの評価ステータスとスコアがひと目でわかるように表示されます。 +- **`/dashboards`**: 保存済みの評価ヘルスビュー（下記の[ダッシュボード](#dashboards)を参照）。 -![セッションごとの評価ステータスバッジとカラーコードのスコアバッジ（helpfulness、factuality、tool_efficiency、safety、coherence）が表示されたセッション一覧グリッド](/agenteye/images/sessions-list.png) +![評価ステータスのピルとカラーコードされたスコアバッジ（helpfulness、factuality、tool_efficiency、safety、coherence）が表示されたセッショングリッド](/agenteye/images/sessions-list.png) -*セッション一覧グリッドでは各実行の評価ステータスとスコアを一目で確認できます。赤/黄/緑のバッジで低スコアをすぐに発見できます。* +*セッショングリッドは各実行の評価ステータスとスコアをひと目で表示します。赤/オレンジ/緑のバッジで低スコアが目立ちます。* --- ## ダッシュボード -**ダッシュボード**ページ（`/dashboards`）では、評価フィルターの組み合わせを名前付きの再利用可能なビューとして保存し、そのスライスの評価状態を一目で確認できます。ダッシュボードは**組織全体で共有されます**。`dashboards:read` 権限を持つ全員が同じセットを閲覧できます。 +**ダッシュボード**ページ（`/dashboards`）では、評価フィルターの組み合わせを名前付きの再利用可能なビューとして保存し、その評価スライスの状況をひと目で把握できます。ダッシュボードは**組織全体で共有**されます。`dashboards:read` を持つ全員が同じセットを閲覧できます。 -各ダッシュボードが保持する内容: +各ダッシュボードには以下が保存されます。 -- **フィルター**: セッションページと同じコントロール（環境、ステータス、エージェント、ローリング時間ウィンドウ、スコア範囲フィルター（`key:min..max`））。 -- **表示設定**: 表示するスコアキー、緑/黄/赤のヘルスしきい値、表示するパネル、セッションごとに最新の評価に折りたたむかどうか。 +- **フィルター**: セッションページと同じコントロール: 環境、ステータス、エージェント、ローリングタイムウィンドウ、スコア範囲フィルター（`key:min..max`）。 +- **表示設定**: フィーチャーするスコアキー、緑/オレンジ/赤のヘルス閾値、表示するパネル、セッションごとの最新評価に折りたたむかどうか。 -各カードにはマッチするセッション数、done/error/timeout の内訳、各注目スコアの平均、小さなトレンドスパークラインが表示されます。ダッシュボードを開くとフルサイズのパネルが表示されます。**セッションで開く**をクリックすると、そのスライスに絞り込まれた状態でセッションページが開きます。メトリクスはサーバーサイドでマッチするセット全体にわたって計算されます（`GET /evaluations/aggregate` 経由）。そのため数値はサンプリングではなく正確です。 +各カードには、一致するセッション数、done/error/timeout の内訳、各フィーチャードスコアの平均、小さなトレンドスパークラインが表示されます。ダッシュボードを開くとフルサイズのパネルが表示されます。**「セッションで開く」**をクリックすると、そのスライスで事前フィルタリングされたセッションページに移動します。メトリクスはサーバーサイドで一致するセット全体に対して計算されます（`GET /evaluations/aggregate` 経由）。そのため、数値はサンプリングではなく正確です。 -![評価器の次元ごとの平均スコアバー、ツールの成功/エラー内訳、上位ツール、1 時間あたりのイベント数トレンドを含む評価ヘルスダッシュボード](/agenteye/images/dashboard-quality.png) +![評価軸別の平均スコアバー、ツールの成功/エラー内訳、トップツール、時間あたりのイベント数トレンドが表示された評価ヘルスダッシュボード](/agenteye/images/dashboard-quality.png) -**権限:** 閲覧には `dashboards:read` と `evaluations:read` の両方が必要です。作成と編集には `dashboards:write`、削除には `dashboards:delete` が必要です。ブートストラップ管理者はこれらすべてを自動的に受け取ります。 +**権限:** 閲覧には `dashboards:read` と `evaluations:read` の両方が必要です。作成と編集には `dashboards:write` が必要です。削除には `dashboards:delete` が必要です。ブートストラップ管理者はこれらすべてを自動的に受け取ります。 --- ## トラブルシューティング -**セッションは存在するが評価が作成されない。** サーバープロセスに `EVALUATOR_ENDPOINT` が設定されていること、サーバーと評価器が同じ `EVALUATOR_TOKEN` の値を共有していること、評価器の `/health` エンドポイントがサーバーから到達可能であることを確認してください。`EVALUATOR_ENDPOINT` が未設定の場合、パイプラインは no-op です。 +**セッションは存在するが評価が作成されない。** サーバープロセスに `EVALUATOR_ENDPOINT` が設定されていること、サーバーと評価器が同じ `EVALUATOR_TOKEN` 値を共有していること、評価器の `/health` エンドポイントがサーバーから到達可能であることを確認してください。`EVALUATOR_ENDPOINT` が未設定の場合、パイプラインは no-op です。 -**処理中の評価が積み上がる。** `GET /evaluation-jobs` でインフライトキューを確認してください。各行の `attempt_count`、`next_attempt_at`、`last_error` を確認してください。よくある原因: 評価器サービスに到達できないか 5xx を返している（バックオフで再試行）、`EVALUATOR_TOKEN` が間違っている（401 は終端）、`pending` を無限に返す非同期評価器（以下を参照）。 +**実行中の評価が溜まっている。** `GET /evaluation-jobs` をクエリして実行中のキューを確認します。各行の `attempt_count`、`next_attempt_at`、`last_error` を調べてください。よくある原因: 評価器サービスに到達できないか 5xx を返している（バックオフで再試行）、`EVALUATOR_TOKEN` が間違っている（401 は終了扱い）、または `pending` を無期限に返す非同期評価器（下記参照）。 -**セッションが完了したが終端評価がない。** `GET /evaluation-jobs?status=polling` を照会してください。まだ処理中かもしれません。ジョブが `pending` のままスタックしている場合、サーバーが評価器に到達できていません。評価器が起動していること、`EVALUATOR_TOKEN` が一致していることを確認してください。 +**セッションが完了したが終了評価がない。** `GET /evaluation-jobs?status=polling` をクエリしてください。結果はまだ実行中かもしれません。ジョブが `pending` のまま stuck している場合は、サーバーが評価器に到達できない可能性があります。評価器が起動していること、`EVALUATOR_TOKEN` が一致していることを確認してください。 -**`評価器からの HTTP 401: 無効なベアラートークン`。** サーバーの `EVALUATOR_TOKEN` が評価器サービスに設定された値と一致していません。両方が同一である必要があります。 +**`HTTP 401 from evaluator: invalid bearer token`。** サーバーの `EVALUATOR_TOKEN` が評価器サービスに設定された値と一致していません。同一である必要があります。 -**非同期評価器が永遠に `pending` を返す。** サーバーは評価器が `done` または `error` を返すか、`EVALUATOR_MAX_POLL_DURATION_SECS`（デフォルト 1 時間）が経過するまで `GET /evaluate/{job_id}` をポーリングします。上限を超えると評価は `timeout` として記録され、インフライトキューから削除されます。評価器が正当にデフォルトより長い時間を必要とする場合は `EVALUATOR_MAX_POLL_DURATION_SECS` を増やしてください。 +**非同期評価器が `pending` を返し続ける。** サーバーは評価器が `done` または `error` を返すか、`EVALUATOR_MAX_POLL_DURATION_SECS`（デフォルト 1 時間）が経過するまで `GET /evaluate/{job_id}` をポーリングします。上限に達すると、評価は `timeout` として記録され、実行中のキューから削除されます。評価器が正当にデフォルトより長い時間を必要とする場合は、`EVALUATOR_MAX_POLL_DURATION_SECS` を増やしてください。 --- ## 次のステップ -- [評価器エージェントスキル](/ja/agenteye/evaluator-skill): コーディングエージェントに、実際のセッションに対して次元を設計し、このサービスを構築させる。 -- [Python SDK](/ja/agenteye/python-sdk): スコアリングをトリガーする `agent_end` イベントを送出する。 -- [API キー](/ja/agenteye/api-keys): `evaluations:read` と `evaluations:trigger` 権限。 -- [監査](/ja/agenteye/audits): Observability のもう一つの自動品質機能、ポリシーベースのレビュー。 \ No newline at end of file +- [評価器エージェントスキル](/ja/agenteye/evaluator-skill): コーディングエージェントに実際のセッションに基づいて評価軸を設計させ、このサービスを構築させます。 +- [Python SDK](/ja/agenteye/python-sdk): スコアリングをトリガーする `agent_end` イベントを送信します。 +- [API キー](/ja/agenteye/api-keys): `evaluations:read` と `evaluations:trigger` の権限。 +- [監査](/ja/agenteye/audits): ポリシーベースのレビューのための Observability のもう一つの自動品質機能。 \ No newline at end of file diff --git a/docs/ja/agenteye/evaluations.mdx b/docs/ja/agenteye/evaluations.mdx index cf7008e7..5a5d1b54 100644 --- a/docs/ja/agenteye/evaluations.mdx +++ b/docs/ja/agenteye/evaluations.mdx @@ -1,51 +1,50 @@ --- title: "評価" -description: "品質の問題が自然と見つかるようになります。ユーザーのクレームで初めて気づくことはなくなります。" +description: "品質の問題が自分で見つけられるようになります。ユーザーからのクレームで初めて気づく時代は終わりです。" --- +品質の問題が自分で見つけられるようになります。ユーザーからのクレームで初めて気づく時代は終わりです。スコアリングサービスを一度接続するだけで、Failproof AI Observability がすべての完了済み実行を自動的に採点します。ヘルプ品質の低下やハルシネーションの急増が、ユーザーが気づく前に自動で表面化します。 -品質の問題が自然と見つかるようになります。ユーザーのクレームで初めて気づくことはなくなります。スコアリングサービスを一度接続するだけで、Failproof AI Observability がすべての完了済み実行を自動的に採点します。応答の有用性の低下やハルシネーションの急増を、顧客が気づく前に自動で検出します。 +![スコア列を含むセッション一覧: 各実行に評価ステータスのバッジと、ヘルプ品質・正確性・ツール効率のカラーコードバッジが表示されている](/agenteye/images/sessions-list.png) -![スコア列付きのセッショングリッド: 各実行に評価ステータスのバッジと、有用性・事実性・ツール効率を色分けしたバッジが表示されている](/agenteye/images/sessions-list.png) +*セッション一覧のすべての実行にスコアが表示されます。赤・黄・緑のバッジにより、トランスクリプトを一つも開かずに問題のある実行が一目でわかります。* -*セッショングリッドのすべての実行にスコアが付いています。赤・黄・緑のバッジにより、トランスクリプトを一つも開かずに問題のある実行が一目でわかります。* +## 手動でのサンプリングをやめる -## 手作業によるサンプリングをやめる +これまでは一部の実行を抜き打ちチェックして、残りは大丈夫だろうと祈るしかありませんでした。今後はすべての完了したセッションが、終了した瞬間に自分が重視する指標でスコアリングされます。ヘルプ品質、ツール効率、正確性、安全性など、品質基準として設定したあらゆる指標が対象です。スコアのキーはユーザーが定義し、Failproof AI Observability が評価器から返ってきた内容を保存・トレンド表示します。スコアリングから漏れる実行はなく、サポートチケットで初めて品質低下を知ることもなくなります。 -これまでは一部の実行だけをスポットチェックして、残りは問題ないと祈るしかありませんでした。今後は、完了したすべてのセッションが終了した瞬間にスコアリングされます。対象ディメンションは、有用性・ツール効率・事実性・安全性など、あなたが重視する品質基準に合わせて設定できます。スコアのキーはあなたが定義し、Failproof AI Observability は評価器が返すあらゆるデータを保存・傾向分析・表示します。採点漏れは一切なく、サポートチケットで回帰を知ることもなくなります。 - -スコアは **`//sessions`**（サイドバー → *observe* → *sessions*）のセッショングリッドに表示され、各行にバッジのクラスターが付きます。スコアが低い実行だけを確認したい場合は、スコア範囲でグリッドをフィルタリングしてください。たとえば有用性が 0.5 未満のように絞り込めば、確認すべき実行だけを取り出せます。スコアの閲覧には `evaluations:read` 権限が必要です。 +スコアは **`//sessions`**（サイドバー → *observe* → *sessions*）のセッション一覧に各行のバッジクラスターとして表示されます。基準を下回った実行だけを確認したい場合は、スコアの範囲（例：ヘルプ品質が 0.5 未満）でグリッドをフィルタリングすれば、確認すべき実行のみを絞り込めます。スコアの閲覧には `evaluations:read` 権限が必要です。 ## 低スコアの原因を確認する -数値は実行の問題を示しますが、セッションページはその理由を教えてくれます。任意の実行を開くと、右パネルに概要サマリーが表示され、その下に各ディメンションのスコアバーと評価器が生成した根拠が示されます。「事実性が 0.4 だった」という状態から、どの主張が誤っていたかまで、数秒で確認できます。 +数値は実行が不十分だったことを示しますが、セッションページはその理由を教えてくれます。任意の実行を開くと、右側のパネルに概要サマリーが表示され、その下に各指標のスコアバーと評価器による根拠が表示されます。「正確性が 0.4 だった」という状態から、具体的に誤りのあった内容へ数秒でたどり着けます。 -![セッションの右パネル: 上部に評価サマリー、続いて各ディメンションのスコアバーと根拠の一行説明、隣にはイベントタイムライン全体が表示されている](/agenteye/images/session-detail.png) +![セッションの右パネル: 評価サマリーの上部、その下に根拠の説明付き各指標のスコアバー、隣にはイベントタイムライン全体が表示されている](/agenteye/images/session-detail.png) -*セッション詳細ビュー: サマリー、ディメンション別スコアバー、各スコアの根拠が実行のイベントタイムラインの隣に表示されます。* +*セッション詳細画面: サマリー、各指標のスコアバー、各スコアの根拠が実行のイベントタイムラインの隣に表示されます。* -より精度の高い評価器をリリースした場合や、スコアリング前にクラッシュした実行を確認したい場合は、**再評価**ボタン（`evaluations:trigger` で制限）を使ってその場でセッションを再採点できます。新しい結果はタイムラインに追記され、以前のスコアも履歴として残ります。このボタンは **`//sessions/`** で確認できます。 +より精度の高い評価器を導入した場合、またはスコアリング前にクラッシュした実行を確認したい場合は、**再評価**ボタン（`evaluations:trigger` が必要）でセッションを再採点できます。新しい結果がタイムラインに追記され、以前のスコアは履歴として残ります。このボタンは **`//sessions/`** にあります。 -## フリート全体の品質トレンドを監視する +## 全体の品質トレンドを監視する -1 件の低スコアはノイズに過ぎませんが、コホート全体の低下はシグナルです。保存済みダッシュボードを使えば、スコアをひと目で確認できるトレンドに変換できます。エージェント別・環境別に、今週と先週の平均有用性を比較するといった使い方も可能です。 +1 つの実行のスコアが低いのはノイズですが、コホート全体が下降しているのはシグナルです。保存済みダッシュボードにより、スコアをひと目で確認できるトレンドに変換できます。エージェントごと・環境ごとに、今週と先週の平均ヘルプ品質を比較できます。 -![品質ダッシュボード: 評価ディメンションごとの平均スコアバーと経時的なトレンド](/agenteye/images/dashboard-quality.png) +![品質ダッシュボード: 評価指標ごとの平均スコアバーと時系列トレンドが表示されている](/agenteye/images/dashboard-quality.png) -*保存済みの品質ダッシュボードは注目するスコアキーのトレンドを表示するため、インシデントになる前の緩やかな低下を早期に発見できます。* +*保存済みの品質ダッシュボードでは注目するスコアキーのトレンドが表示されるため、インシデントになる前に緩やかな低下を早期に検知できます。* -ダッシュボードは **`//dashboards`**（サイドバー → *analyze* → *dashboards*）にあり、組織全体で共有されます。各カードは対象セッションを集計し、セッション数・注目スコアの平均・トレンドのスパークラインを表示します。「Open in sessions」をクリックすると、任意の数値に対応する事前フィルタリング済みの実行に直接移動できます。閲覧には `dashboards:read` と `evaluations:read` の両方が必要です。 +ダッシュボードは **`//dashboards`**（サイドバー → *analyze* → *dashboards*）にあり、組織全体で共有されます。各カードには対象セッションの件数、注目スコアの平均値、トレンドのスパークラインが表示されます。「セッションで開く」をクリックすると、その数値の背景にある事前フィルタリング済みの実行に直接移動できます。閲覧には `dashboards:read` と `evaluations:read` の両方が必要です。 ## 評価器を一度接続する -スコアリングはオプトイン方式で、Failproof AI Observability にスコアラーを指定するまでは完全にオフになっています。小さな HTTP サービスを一つ立ち上げ（Observability にはコピーして使える実用的なリファレンス実装が付属しています）、サーバーに 2 つの値を設定するだけで、以降のすべての実行が自動的に採点されます。詳細なウォークスルー・スコアリングの仕様・SDK は詳細ガイドに記載されています。 +スコアリングはオプトイン形式で、Failproof AI Observability にスコアラーを指定するまで完全に無効のままです。小さな HTTP サービスを一つ立ち上げ（Observability にはコピーして使える動作済みのリファレンスが含まれています）、サーバーに 2 つの値を設定するだけで、それ以降のすべての実行が自動的にスコアリングされます。詳細なウォークスルー、スコアリングの仕様、SDK は詳細ガイドに記載されています。 -どのディメンションを採点すべきか迷っている場合は、[evaluator agent skill](/ja/agenteye/evaluator-skill) を使えば、コーディングエージェントが実際のセッションをもとに最適なスコアディメンションを見つけ出し、サービスを構築・デプロイしてくれます。 +どの指標をスコアリングすべきか迷っている場合は、[evaluator agent skill](/ja/agenteye/evaluator-skill) を使って、コーディングエージェントが自分のセッションを分析して指標を決定し、サービスのビルドとデプロイまで行ってくれます。 -## 関連情報 +## 関連ドキュメント -- [Evaluation suite](/ja/agenteye/evaluation-suite): 評価器の接続、スコアリングの仕様、SDK について。 -- [Evaluator agent skill](/ja/agenteye/evaluator-skill): コーディングエージェントにスコアのディメンション選定と評価器の構築を任せる。 -- [Sessions](/ja/agenteye/sessions): スコアが表示される実行単位のグリッド。 +- [Evaluation suite](/ja/agenteye/evaluation-suite): 評価器の接続方法、スコアリングの仕様、SDK。 +- [Evaluator agent skill](/ja/agenteye/evaluator-skill): コーディングエージェントにスコア指標の選定と評価器の構築を任せる。 +- [Sessions](/ja/agenteye/sessions): スコアが表示される実行ごとの一覧。 - [Dashboards](/ja/agenteye/dashboards): 組織全体の品質トレンドを保存・共有する。 -- [Audits](/ja/agenteye/audits): セッションをまたいだ調査に対応する、Observability のもう一つの自動品質機能。 \ No newline at end of file +- [Audits](/ja/agenteye/audits): セッションをまたいだ調査に対応する Observability のもう一つの自動品質機能。 \ No newline at end of file diff --git a/docs/ja/agenteye/evaluator-skill.mdx b/docs/ja/agenteye/evaluator-skill.mdx index 3466dea6..71e2e4cd 100644 --- a/docs/ja/agenteye/evaluator-skill.mdx +++ b/docs/ja/agenteye/evaluator-skill.mdx @@ -1,75 +1,75 @@ --- -title: "Failproof AI オブザーバビリティ 評価エージェントスキル" -description: "「エージェントの品質が不安定かもしれない」という状態から、コーディングエージェントが設計と実装の両方を担いながら、スコアリングサービスをデプロイするところまで到達できます。" +title: "Failproof AI オブザーバビリティ評価エージェントスキル" +description: "「エージェントの品質がときどき悪い気がする」から、スコアリングサービスのデプロイまで。設計もビルドも、コーディングエージェントにまかせましょう。" --- -「エージェントの品質が不安定かもしれない」という状態から、コーディングエージェントが設計と実装の両方を担いながら、スコアリングサービスをデプロイするところまで到達できます。**Failproof AI オブザーバビリティ 評価スキル**（`agenteye-evaluator`）は*エージェントスキル*です。Claude Code や Codex などのコーディングエージェントがオンデマンドで読み込む、小さな命令のフォルダーです。このスキルは、エージェントが*あなたの*エージェントにとって追跡すべき品質軸を判断し、それをスコアリングする[評価サービス](/ja/agenteye/evaluation-suite)を作成・テスト・デプロイする方法を教えます。 +*「エージェントの品質がときどき悪い気がする」* という状態から、デプロイ済みのスコアリングサービスまで一気に到達できます。設計もビルドも、コーディングエージェントが担います。**Failproof AI オブザーバビリティ評価スキル**（`agenteye-evaluator`）は *Agent Skill* の一種です。Claude Code や Codex などのコーディングエージェントがオンデマンドで読み込む、小さな指示フォルダです。このスキルは、*あなたの*エージェントにとって追跡する価値のある品質ディメンションを見極め、それらをスコアリングする[評価サービス](/ja/agenteye/evaluation-suite)を記述・テスト・デプロイする方法をエージェントに教えます。 -これはホスト型のスコアラーでも、アップロード先のレジストリでも、プラグインシステムでもありません。評価サービスは[Evaluation suite](/ja/agenteye/evaluation-suite)ガイドに記載のとおり、あくまでご自身のインフラ上で動作するHTTPサービスとして、あなた自身のものとして維持されます。このスキルは、エージェントがそれをうまく構築できるよう教えるだけです。スキルが行うことは、同じコードを自分で書けばすべて自分でも実現できます。 +これはホスト型スコアラーでも、アップロード先のレジストリでも、プラグインシステムでもありません。評価エージェントは[Evaluation suite](/ja/agenteye/evaluation-suite)ガイドに記載のとおり、あなた自身のインフラ上でHTTPサービスとして動作し続けます。スキルはそれをうまく構築するための指示を提供するだけであり、スキルが行うことはすべて、あなた自身が同じコードを書けば実現できます。 --- -## 難しいのは、何をスコアリングするかを決めること +## 難しいのは「何をスコアするか」の決断 -SDKのサーフェスは小さく、デコレーターとふたつのモデルだけです。エージェントは[コントラクト](/ja/agenteye/evaluation-suite#http-contract)だけからでもそれを書くことができます。評価システムが失敗するのはそこではありません。失敗の原因は、間違ったものをスコアリングすることです。そして間違ったものをスコアリングする評価システムは、ないよりも悪い結果をもたらします。誰もが無視することを覚えてしまうダッシュボードを生み出すからです。 +SDKの表面積は小さく、デコレーターとふたつのモデルのみです。エージェントは[コントラクト](/ja/agenteye/evaluation-suite#http-contract)だけからでもそれを書けます。評価エージェントが失敗するのはそこではありません。間違ったものをスコアするから失敗するのです。そして間違ったものをスコアする評価エージェントは、ないよりも悪い。誰もが無視することを学んだダッシュボードを生み出すだけです。 -だから、スキルの大部分はコードが存在する前の段階にあります。スキルはエージェントにあなたへのインタビューをさせます（「うまくいったセッションを説明してください。次に、うまくいかなかったものを」）。そして[`agenteye` CLI](/ja/agenteye/cli)を通じて実際のセッションを取得し、最初から最後まで読み込みます。この２つの側面は通常一致せず、そのギャップこそが重要です。あなたが測定したいと意図していることと、実際のトランスクリプトがサポートできることの差です。ある軸が残るのは、イベントから**算出可能**で、かつ**識別力がある**場合のみです。良いセッションでも悪いセッションでも0.9のスコアになるなら、何も教えてくれないため除外されます。 +だからこそ、スキルの大部分はコードが存在する前の段階に費やされます。スキルはエージェントにあなたへのインタビューをさせ（*「うまくいった実行を教えてください。次に、うまくいかなかった実行を」*）、[`agenteye` CLI](/ja/agenteye/cli)を通じて実際のセッションを取得し、最初から最後まで読み込ませます。ふたつの情報源はたいてい食い違います。そのギャップこそが重要です。あなたが計測しようとしていることと、トランスクリプトが実際にサポートできることの差異。ディメンションが生き残るのは、イベントから**計算可能**であり、かつ**識別力がある**場合のみです。良い実行でも悪い実行でも0.9をスコアするなら、何も教えてくれないのでカットされます。 -返ってくるのは、コードが一行も書かれる前に、あなたが承認するための理由付きの2〜4軸の提案です。 +最終的に返ってくるのは、2〜4個のディメンションと、それぞれの根拠を添えた提案です。コードが一行も書かれる前に、あなたが承認します。 ```mermaid flowchart TD - YOU["あなた: 'サポートボットの評価を作りたい'"] --> AGENT["コーディングエージェント（Claude Code / Codex）
agenteye-evaluatorスキルを読み込む"] - AGENT -->|"インタビュー: 良い状態と悪い状態とは？"| YOU + YOU["あなた：「サポートボットの評価がほしい」"] --> AGENT["コーディングエージェント（Claude Code / Codex）
agenteye-evaluatorスキルを読み込む"] + AGENT -->|"インタビュー：良い実行と悪い実行の違いは？"| YOU AGENT -->|"agenteye --json sessions / events"| DATA["実際のセッション
実際に起きていること"] - DATA --> DIMS["2〜4軸、あなたが承認"] + DATA --> DIMS["2〜4個のディメンション、あなたが承認"] DIMS --> SVC["あなたの評価サービス
agenteye-evaluator SDK"] - SVC --> SCORES["スコアがダッシュボードと
agenteye evalsに表示される"] + SVC --> SCORES["スコアがダッシュボードと
agenteye evalsに反映される"] ``` --- ## 他の評価コンポーネントとの関係 -スコアリングに関するドキュメントは4つあり、順番に引き継ぎ合います。 +スコアリングに関するドキュメントは4つあり、順番に引き継がれます： | ページ | 内容 | 参照するタイミング | |---|---|---| -| **[Evaluations](/ja/agenteye/evaluations)** | 機能：セッショングリッドのスコア、ダッシュボード、再評価 | 自動スコアリングで何が得られるか知りたいとき | -| **[Evaluation suite](/ja/agenteye/evaluation-suite)** | HTTPコントラクト、SDK、サーバー環境変数 | 評価サービスを自分で実装またはデバッグするとき | -| **評価スキル**（このドキュメント） | スコアラーの設計と構築のための自然言語インターフェース | 「evalを作りたい」から動作するサービスまで進めたいとき | -| **[CLIスキル](/ja/agenteye/cli-skill)** | `agenteye` CLIへの自然言語インターフェース | すでにあるスコアを*読み取りたい*とき | -| **[Python SDKスキル](/ja/agenteye/python-sdk-skill)** | エージェントのインストルメント化への自然言語インターフェース | エージェントがまだセッションを出力していない — スコアリング対象がない | +| **[Evaluations](/ja/agenteye/evaluations)** | 機能：セッショングリッドのスコア、ダッシュボード、再評価 | 自動スコアリングで何が得られるかを知りたいとき | +| **[Evaluation suite](/ja/agenteye/evaluation-suite)** | HTTPコントラクト、SDK、サーバー環境変数 | 評価エージェントを自分で実装またはデバッグしているとき | +| **評価エージェントスキル**（このドキュメント） | スコアラーの設計と構築への自然言語フロントエンド | 「評価がほしい」から稼働するサービスまで進みたいとき | +| **[CLIスキル](/ja/agenteye/cli-skill)** | `agenteye` CLIへの自然言語フロントエンド | すでに持っているスコアを*読みたい*とき | +| **[Python SDKスキル](/ja/agenteye/python-sdk-skill)** | エージェントのインストルメント化への自然言語フロントエンド | エージェントがまだセッションを送出していない——スコアするものが何もないとき | -### CLIスキルとの違い：構築 vs. 読み取り +### CLIスキルとの違い：構築 vs 読み取り -ふたつのスキルは意図的に重複しないよう設計されており、両方インストールするのが通常の構成です。エージェントはあなたの質問内容に応じてどちらを使うか選択します。 +ふたつのスキルは意図的に重複しないように設計されており、両方インストールするのが通常のセットアップです。エージェントはあなたの質問に基づいて使い分けます： -- **`agenteye-evaluator`**（このドキュメント）はスコアを*生成する*ものを構築します。初めてスコアが出るところでその役割を終えます。 -- **[`agenteye-cli`](/ja/agenteye/cli-skill)**はすでに存在するスコアを読み取ります（`agenteye evals`）。「今週、品質は下がったか？」がその問いであり、このスキルの問いではありません。 +- **`agenteye-evaluator`**（このドキュメント）はスコアを*生成する*ものを構築します。初めてスコアが反映された時点でその役割は終わりです。 +- **[`agenteye-cli`](/ja/agenteye/cli-skill)** はすでに存在するスコアを読み取ります（`agenteye evals`）。「今週、品質は下がったか？」がこのスキルの問いであり、このドキュメントのスキルの問いではありません。 --- ## 前提条件 -1. **`agenteye` CLIのインストールとログイン**（`pipx install agenteye`、その後`agenteye login`）。スキルはこれを2回使います。設計の元となる実際のセッションを取得するときと、最後にスコアが届いたことを確認するときです。ログインには`events:read`と、最終確認のための`evaluations:read`が必要です。CLIスキルと同様に、メールで届くワンタイムコードを使ったログインを代行することは**できません**。 -2. **評価サービスを置く場所。** サービスはイメージとしてビルドされ、常駐するサービスとして実行されます。そのため、一時的なファイルではなく、正式なリポジトリが必要です。評価サービスはスコアリング対象のエージェントとは別のリポジトリに置かれることが多く、スキルは既存のリポジトリを探し、新しくスキャフォールドする前に確認を求めます。 -3. **`agenteye-evaluator` SDKホイール** — エージェントが`pip`コマンドを打ち始める前に次のセクションを読んでください。 +1. **`agenteye` CLIのインストールとログイン**（`pipx install agenteye` の後 `agenteye login`）。スキルはこれを2回使います。設計対象となる実際のセッションの取得と、最後にスコアが反映されたことの確認です。ログインには `events:read`、最終確認には `evaluations:read` が必要です。CLIスキルと同様に、メールで送られるワンタイムコードのログインをエージェントが代わりに完了することは**できません**。 +2. **評価エージェントの置き場所。** イメージにビルドされ、長時間稼働するサービスとして実行されるため、スクラッチファイルではなく実際のリポジトリが必要です。評価エージェントは多くの場合、スコアリング対象のエージェントとは別のリポジトリに置かれます。スキルは既存のリポジトリを探し、新しくスキャフォールドする前に確認を求めます。 +3. **`agenteye-evaluator` SDKホイール** — エージェントが `pip` コマンドを打ち始める前に次のセクションを読んでください。 --- -## 入手先 +## 入手方法 -スキルはFailproof AIの公開スキルコレクションで公開されています。 +スキルはFailproof AIの公開スキルコレクションで公開されています： **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -リポジトリは公開されており、スキル自体に認証情報は不要です。ログインしたセッションで`agenteye` CLIを操作し、*あなたの*リポジトリにコードを書くだけです。スキルは独自のフォルダーとして配布されており、`pipx install agenteye`パッケージには含まれていません。そちらで探さないようにしてください。 +リポジトリは公開されており、スキル自体には独自の認証情報は不要です。ログイン済みの `agenteye` CLIを操作し、*あなたの*リポジトリにコードを書くだけです。なお、このスキルは独自のフォルダとして提供されており、`pipx install agenteye` パッケージには含まれていません。そちらを探さないようにしてください。 ## スキルのインストール -最も手軽な方法は[`skills`](https://skills.sh) CLIを使うことです。フォルダーを取得し、エージェントが参照する場所に配置します。 +最速の方法は [`skills`](https://skills.sh) CLIです。フォルダを取得し、エージェントが参照する場所に配置します： ```bash # Claude Code、このプロジェクトのみ @@ -78,90 +78,90 @@ npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code # すべてのプロジェクト（~/.claude/skills/ にインストール） npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy -# Codexの場合 +# Codex の場合 npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -インストール後は、他のスキルと同様に管理できます。 +その後は他のスキルと同様に管理できます： ```bash -npx skills list -a claude-code # インストール済みを確認 -npx skills update agenteye-evaluator # 最新版を取得 +npx skills list -a claude-code # インストール済みの確認 +npx skills update agenteye-evaluator # 最新バージョンに更新 npx skills remove agenteye-evaluator # 削除 ``` -手動でインストールする場合は、エージェントスキルは`SKILL.md`（とオプションの参照ファイル）を含むフォルダーにすぎないため、コピーするだけでも動作します。 +手動インストールを好む場合は、Agent Skillは `SKILL.md`（とオプションの参照ファイル）を含むフォルダに過ぎないため、コピーするだけでも動作します： -- **Claude Code**：`agenteye-evaluator/`フォルダーを`~/.claude/skills/`（全プロジェクト共通）または`/.claude/skills/`（そのリポジトリのみ）に置いてください。Claude Codeは自動で認識します。`/skills`リストで確認するか、evalについて質問してみてください。 -- **Codex（OpenAI）**：Codexも同じ`SKILL.md`を読み取ります。同梱の`agents/openai.yaml`に`allow_implicit_invocation: true`が設定されているため、タスクが一致するとCodexが自動でスキルを選択します。明示的に呼び出す場合は`$agenteye-evaluator`と指定してください。 +- **Claude Code**：`agenteye-evaluator/` フォルダを `~/.claude/skills/`（すべてのプロジェクト）または `/.claude/skills/`（そのリポジトリのみ）に配置します。Claude Code が自動検出します。`/skills` リストで確認するか、評価について尋ねるだけで確認できます。 +- **Codex（OpenAI）**：Codex は同じ `SKILL.md` を読み込みます。同梱の `agents/openai.yaml` に `allow_implicit_invocation: true` が設定されているため、タスクが一致するとCodexが自動的にスキルを選択します。明示的に呼び出す場合は `$agenteye-evaluator` を使用してください。 --- ## SDKは公開PyPIにありません -> **警告：** エージェントにSDKをインストールさせる前にこのセクションを読んでください。 +> **警告：** エージェントがSDKをインストールし始める前にこれを読んでください。 -スキルは公開されていますが、それが使用するSDKは公開されていません。`agenteye-evaluator`はプライベートのリリース成果物としてのみ配布されており、`agenteye`と異なり、**公開PyPIではパッケージ名が未取得**です。そのため、`pip install agenteye-evaluator`と単純に実行すると、第三者のパッケージが本番のトランスクリプトを読み取るサービスに取り込まれる可能性があります。これはタイポの問題ではなく、サプライチェーンのリスクです。 +スキルは公開されていますが、それが利用するSDKは公開されていません。`agenteye-evaluator` はプライベートリリース成果物としてのみ提供されており、`agenteye` と異なり、**公開PyPIでその名前は未登録です**。つまり、素の `pip install agenteye-evaluator` を実行すると、本番トランスクリプトを読み込むサービスに見知らぬパッケージが引き込まれる可能性があります。これはタイポの問題ではなく、サプライチェーンの問題です。 -スキルはこれを認識しており、代わりにインストールの優先順位を順番に確認します。AgentEyeのリポジトリ内であればモノレポのソース、そうでなければGitHub Releases（アクセス権が必要）からのプライベートリリースホイール、いずれも利用できない場合は、**その場での代替策をとるのではなく、Failproof AIの担当者にホイールを問い合わせるよう案内して停止します**。 +スキルはこれを認識しており、代わりにインストール手順を順番に試します。最初に該当するもので止まります。AgentEyeリポジトリ内にいる場合はモノリポのソースを使用し、そうでなければGitHub Releasesのプライベートリリースホイールを試します（アクセス権が必要）。どちらも到達できない場合は**処理を止め、Failproof AIの担当者にホイールを問い合わせるよう伝えます**。独自に解決しようとはしません。 -したがって、エージェントが公開PyPIから`pip install agenteye-evaluator`を単純に提案してきた場合、それはスキルが読み込まれていないサインです。その場で止めて、スキルが正しくインストールされているか確認してください。 +エージェントが公開PyPIからの素の `pip install agenteye-evaluator` を提案した場合、それはスキルが読み込まれていないサインです。そこで止めて、スキルがインストールされているか確認してください。 --- -## 何を依頼できるか +## 依頼できること -実際のやり取りは、漠然とした依頼から始まり、コードではなく承認済みの設計で終わります。 +実際のやり取りは漠然とした依頼から始まり、コードではなく承認済みの設計で終わります： ```text -あなた ▸ サポートボットの評価を作りたいんだけど。品質が不安定な気がする。 +あなた ▸ サポートボットの評価をしたいです。たまに品質が悪い気がします。 -エージェント ▸ 何かを書く前に：うまくいったセッションと、 - うまくいかなかったセッションをそれぞれ説明してください。 +エージェント ▸ 何かを書く前に確認します。うまくいった実行と、 + うまくいかなかった実行を教えてください。 -あなた ▸ 良い例：ドキュメントから回答できている。悪い例：でたらめなことを言う、 - または諦めて「サポートに連絡してください」と言う。 +あなた ▸ 良い場合：ドキュメントから正確に答えてくれる。 + 悪い場合：でたらめを言う、または諦めて「サポートに連絡してください」と言う。 エージェント ▸ 実行中：agenteye --json sessions --status error --since 7d - 5つのセッションを読み込み中、うち2つはあなたが問題と判断するもの。 + 5セッションを読み込み中。そのうち2つがあなたの言う悪い例です。 - あなたの言葉から「正確性」と「回避」が見えます。トランスクリプトは - 回避については同意（5件中2件がサポートへの引き継ぎで終わっており、 - model_response.contentで明確に確認できます）が、正確性については - イベントにグラウンドトゥルースが含まれていないため判定できません。 + あなたの言葉からは「正確性」と「丸投げ」が浮かび上がります。 + トランスクリプトは「丸投げ」には同意しています（5件中2件がサポートへの + 引き渡しで終わっており、model_response.content で明確に確認できます）が、 + 「正確性」にはイベントに含まれていないグラウンドトゥルースが必要です。 - そこで、次の3つをスコアリングすることを提案します： - - deflection ルールベース、コスト低、2つのセッションを識別可能 + そこで3つをスコアすることを提案します： + - deflection ルールベース、低コスト、2つの実行を明確に区別 - tool_efficiency ルールベース、run-004のリトライループを検出 - groundedness LLMジャッジ：すべての主張が取得したドキュメントにあるか？ - 「正確性」にはグラウンドトゥルースが必要ですが存在しません。 - 「groundedness」がトランスクリプトで実際にサポートできる最も近い指標です。 - この3つの名前でよいですか？後で変更すると履歴が分裂します。 + 「factuality（正確性）」にはグラウンドトゥルースが必要ですが、それがありません。 + 「groundedness」がトランスクリプトで実際にサポートできる最も近い概念です。 + この3つの名前でよいですか？後で変更するとスコア履歴が分断されます。 -あなた ▸ はい +あなた ▸ はい -エージェント ▸ このリポジトリに評価サービスが見当たりません。 - ここにスキャフォールドしますか、それとも別の場所にありますか？ +エージェント ▸ このリポジトリに評価エージェントが見当たりません。 + ここにスキャフォールドしますか？それとも別の場所にありますか？ ``` -ここからエージェントは、まずルールベースの軸を書きます（無料、即時、決定論的）。そして、単純な評価システムをクラッシュさせる空のセッションや未完了のセッションを含む、実際にキャプチャされたセッションに対してテストします。主観的な軸にのみLLMジャッジを使います。[ディスパッチャーの制限](/ja/agenteye/evaluation-suite#configuring-the-server)（リクエストタイムアウト30秒、デプロイ全体で同時8リクエスト）を把握しているため、ジャッジが確実に収まらない場合は、5倍のコストでキャンセル・リトライが繰り返されるのを避けるため、`JobPending`で非同期処理を選択します。 +その後、まずルールベースのディメンション（コスト無料・即時・決定論的）を記述し、空のセッションや未完了のセッションなど、単純な実装がクラッシュするケースを含む実際のキャプチャセッションに対してテストします。そして主観的なディメンションにのみLLMジャッジを使用します。スキルは[ディスパッチャーの制限](/ja/agenteye/evaluation-suite#configuring-the-server)（リクエストタイムアウト30秒、デプロイメント全体で同時8件）を把握しているため、ジャッジが確実に収まらない場合は `JobPending` で非同期化します。ジャッジがキャンセルされ5倍のコストで5回リトライされる事態を防ぐためです。 -そしてデプロイし、2つのサーバー環境変数を設定し、`agenteye --json evals --session-id `でスコアが実際に届いたことを確認します。スコアが届くことだけが唯一の証明です。 +その後、デプロイし、2つのサーバー環境変数を設定し、`agenteye --json evals --session-id ` でスコアが実際に反映されたことを確認します。スコアの反映が唯一の証明です。 --- -## 注意すべき点 +## 注意点 -- **軸の名前はほぼ永続的です。** スコアのキーは任意の文字列であり、プラットフォームは送信された値をそのままトレンド表示します。つまり、後から誰かが悪い選択を修正することはありません。後から名前を変更すると履歴が分裂します。古いセッションは古いキーを保持し、トレンドが壊れます。だからこそスキルはコードを書く前に明示的な承認を求めます。そのプロンプトを真剣に受け止めてください。 -- **フィクスチャーは実際の本番トランスクリプトです。** 実際のセッションを元に設計するということは、それらをディスクに取得することを意味し、顧客データが含まれている可能性があります。スキルはgitにコミットする前に確認を求めます。不安な場合は`fixtures/`をリポジトリから除外し、各開発者が自分でセッションを取得するようにしてください。 -- **エージェントはすべてのトランスクリプトを読み取るサービスを作成・デプロイします。** CLIログインの権限の範囲内であなたとして動作しますが、本番データに触れる他のコードと同様に、評価サービスをレビューしてください。 +- **ディメンション名はほぼ永続的です。** スコアキーは任意の文字列であり、プラットフォームは送信した内容をトレンドとして追跡します。つまり、下流では誤った選択が修正されません。後で名前を変更するとスコア履歴が分断されます。古いセッションは古いキーを保持し、トレンドが壊れます。だからこそスキルはコードを書く前に明示的な承認を求めます。そのプロンプトを真剣に受け止めてください。 +- **フィクスチャは実際の本番トランスクリプトです。** 実際のセッションを基に設計するということは、それらをディスクに取得することを意味し、顧客データが含まれている可能性があります。スキルはそれらをgitにコミットする前に確認を求めます。不安な場合は `fixtures/` をリポジトリの外に置き、開発者ごとに独自に取得するようにしてください。 +- **エージェントはすべてのトランスクリプトを読み込むサービスを記述してデプロイします。** CLIログインの権限内であなたの代わりに動作しますが、本番データに触れる他のコードと同様に評価エージェントをレビューしてください。 --- ## 次のステップ - **[Evaluation suite](/ja/agenteye/evaluation-suite)**：スキルが設定するHTTPコントラクト、SDK、サーバー環境変数。 -- **[Evaluations](/ja/agenteye/evaluations)**：スコアが届いた後に表示される場所。 -- **[CLIスキル](/ja/agenteye/cli-skill)**：スコアラーを構築するのではなく結果を読み取るための、姉妹スキル。 -- **[CLI](/ja/agenteye/cli)**：スキルが設計の元となるセッションデータのコマンドリファレンス。 \ No newline at end of file +- **[Evaluations](/ja/agenteye/evaluations)**：スコアが反映されると表示される場所。 +- **[CLIスキル](/ja/agenteye/cli-skill)**：スコアラーを構築するのではなく、結果を読み取るための兄弟スキル。 +- **[CLI](/ja/agenteye/cli)**：スキルが設計対象とするセッションデータの背後にあるコマンドリファレンス。 \ No newline at end of file diff --git a/docs/ja/agenteye/event-stream.mdx b/docs/ja/agenteye/event-stream.mdx index b13131c8..63de4fcb 100644 --- a/docs/ja/agenteye/event-stream.mdx +++ b/docs/ja/agenteye/event-stream.mdx @@ -1,50 +1,50 @@ --- title: "イベントストリーム" -description: "エージェントが何かをした瞬間、それがすぐに見える。" +description: "エージェントが何かをした瞬間、それが見えます。" --- -エージェントが何かをした瞬間、それがすぐに見える。イベントストリームは、本番環境で動くすべてのエージェントをリアルタイムで把握するための窓口です。待ち時間なし、ログのgrepなし、何が起きたのかを推測する必要もありません。 +エージェントが何かをした瞬間、それが見えます。イベントストリームは、本番環境のすべてのエージェントをリアルタイムで監視できる生きた情報源です。待つ必要も、ログをgrepする必要も、何が起きたか推測する必要もありません。 -![ライブのイベントストリーム：色分けされたイベント行がリアルタイムで流れ、環境・エージェント・セッション・イベントタイプ・フリーテキストでフィルタリング可能](/agenteye/images/events-stream.png) +![ライブイベントストリーム：色分けされたイベント行がリアルタイムで流れ、環境・エージェント・セッション・イベントタイプ・フリーテキストでフィルタリング可能](/agenteye/images/events-stream.png) -*組織内のすべてのエージェントからのすべてのイベントが、最新のものから順に、発生と同時に更新される。* +*組織内のすべてのエージェントからのすべてのイベントを、最新順に、発生と同時に更新。* -## すべてのエージェントをリアルタイムで把握する +## すべてのエージェントへのライブ監視 -エージェントが実行を開始したとき、モデルを呼び出したとき、ツールを起動したとき、フックを実行したとき、またはエラーが発生したとき——その瞬間にストリームの先頭に行が追加されます。組織内のすべてのエージェントのすべてのイベントを最新順で追い続けるため、古くなった情報ではなく、常に最新の状況を把握できます。 +エージェントが実行を開始したとき、モデルを呼び出したとき、ツールを実行したとき、フックを起動したとき、またはエラーが発生したとき、その行は発生した瞬間にストリームの先頭に表示されます。組織内のすべてのエージェントにわたるすべてのイベントを最新順で追跡するため、古い情報ではなく常に最新の状況を把握できます。 -つまり、どこかのサーバーでログファイルを`tail`する必要も、複数のマシン間でgrepする必要も、タイムスタンプを手動でつなぎ合わせる必要もありません。1つのページを開くだけで、すでに本番環境を監視しています。 +つまり、どこかのサーバーでログファイルをtailする必要も、複数マシンにわたってgrepする必要も、タイムスタンプを手作業でつなぎ合わせる必要もありません。1つのページを開けば、すでに本番環境を監視しています。 -行はタイプごとに色分けされているので、1行1行を解読しなくても、ストリームをざっと眺めるだけで状況がわかります。各行には以下の情報が一目でわかります： +行はタイプごとに色分けされているため、1行ずつ解析しなくても一目でストリームを読み取れます。各行では以下が一目でわかります： -- **タイプ**（色分け表示）：`agent_start`、`model_response`、`tool_use`、`hook_completed`、`error` など。 +- **タイプ**（色分け済み）：`agent_start`、`model_response`、`tool_use`、`hook_completed`、`error`、その他。 - **何が起きたかの1行サマリー**。概要を把握するだけなら、詳細を開く必要はほとんどありません。 -- **そのステップのトークン数**。 -- **コンテキストウィンドウの使用率バッジ**（該当する場合）。プロンプトの肥大化やコンパクションが近づいていることを、問題が深刻になる前に視覚的に確認できます。 +- そのステップの**トークン数**。 +- 該当する場合は**コンテキストウィンドウの使用率バッジ**。プロンプトの肥大化や圧縮が近づいていることを、問題になる前に視認できます。 -ライブで監視することで、不正なデプロイ、暴走ループ、エラーの急増を翌日のログレビューではなく、発生した瞬間に検知できます。 +ライブで監視しているということは、不正なデプロイ、暴走ループ、エラーの急増を、翌日のログレビューではなく、発生した瞬間に検知できるということです。 -## 問題のある1つの実行を特定する +## 問題のある1つの実行を見つける -何かがおかしいと感じたとき、大量のデータを流し見たいわけではありません。問題が起きた特定の実行を見つけたいのです。ストリームのフィルタリングは素早くできます：環境別、エージェント別、セッション別、イベントタイプ別、またはフリーテキストで絞り込めます。 +何かおかしいと感じたとき、大量のデータは必要ありません。壊れた特定の実行だけが必要です。ストリームは素早くフィルタリングできます：環境、エージェント、セッション、イベントタイプ、またはフリーテキストで。 -セッションIDやエージェントIDでフィルタリングすれば、最初のイベントから最後のイベントまで1つの実行を追えます。イベントタイプでフィルタリングすれば、特定の種類のアクティビティだけを表示できます——たとえば、組織全体の`error`をすべて1つのビューで確認するといった使い方ができます。フィルターを組み合わせることで、「すべての環境のすべてのエージェント」から「本番環境でエラーが出ているこのエージェント」まで、数クリックで絞り込み、そこから即座に対応できます。 +セッションIDやエージェントIDでフィルタリングすれば、最初のイベントから最後のイベントまで1つの実行を追跡できます。イベントタイプでフィルタリングすれば、特定の種類のアクティビティだけを分離できます。たとえば、組織全体のすべての`error`を1つのビューに表示できます。フィルターを重ねることで、「すべての環境・すべての場所」から「このエージェント、本番環境、エラー発生中」へと数クリックで絞り込み、見つけた内容に対処できます。 -フリーテキスト検索を使えば、すでに手元にあるメッセージ、ツール名、またはIDから直接目的の情報にたどり着けるので、顧客からの報告を受けてから該当する実行を見つけるまで数秒で完了します。 +フリーテキスト検索は、メッセージ、ツール名、または手元にあるIDに直接たどり着けるため、カスタマーレポートから該当する実行を数秒で特定できます。 -## 場所 +## 見つける場所 -イベントストリームは組織のホーム画面です。サインインすると最初に表示されるのがこの画面で、`//` でアクセスできます。到着した瞬間からトリアージを開始できます。 +イベントストリームは組織のホームです。サインインすると最初に表示される画面で、`//` にあります。到着した瞬間からトリアージを開始できます。 -その裏では、エージェントがSDKを通じてイベントを送信し、コレクターがそれをFailproof AI Observabilityサーバーに転送し、ストリームが自分たちで管理するインフラにイベントが届くたびにリアルタイムで表示します。生のトレイルではなく集計されたビューが必要な場合は、各実行のイベントがSessions上で1行にまとめられており、1クリックで確認できます。 +その背後では、エージェントがSDKを通じてイベントを送信し、コレクターがそれをFailproof AI Observabilityサーバーに転送し、ストリームはあなたが管理するインフラに届いた順にそれらを追跡します。生のトレイルではなく集約されたビューが必要な場合は、各実行のイベントがSessionsで1行にまとめられます（1クリックで移動できます）。 -これはすべての観察用サーフェスが基盤とする生の情報源です。他の場所で数値がおかしいと感じたときは、このストリームで実際に何が起きたかを確認してください。 +これは他のすべての観測サーフェスが基盤とする生の情報源です。そのため、他の場所で数値がおかしく見えるときは、ストリームで実際に何が起きたかを確認できます。 -## 関連情報 +## 関連 - [Sessions](/ja/agenteye/sessions)：同じイベントを実行ごとに1行にまとめ、gitスタイルの実行グラフで表示。 -- [Telemetry](/ja/agenteye/telemetry)：エージェントが送信する内容と、イベントがストリームに到達するまでの仕組み。 -- [Error tracking](/ja/agenteye/error-tracking)：問題が発生したすべての事象を一元管理するトリアージ画面。 -- [Alerts](/ja/agenteye/alerts)：任意のしきい値をアラートルールに変換。 -- [CLI and agents](/ja/agenteye/cli-and-agents)：ターミナルから同じライブトレイルを確認。 \ No newline at end of file +- [Telemetry](/ja/agenteye/telemetry)：エージェントが送信する内容と、イベントがストリームに届くまでの仕組み。 +- [Error tracking](/ja/agenteye/error-tracking)：問題のあった内容をすべて一元管理するトリアージサーフェス。 +- [Alerts](/ja/agenteye/alerts)：任意のしきい値をページングルールに変換。 +- [CLI and agents](/ja/agenteye/cli-and-agents)：ターミナルからの同じライブトレイル。 \ No newline at end of file diff --git a/docs/ja/agenteye/hermes-capture.mdx b/docs/ja/agenteye/hermes-capture.mdx index 1f3a8117..027faf57 100644 --- a/docs/ja/agenteye/hermes-capture.mdx +++ b/docs/ja/agenteye/hermes-capture.mdx @@ -3,51 +3,51 @@ title: "Hermesセッションキャプチャ" description: "チームのHermesゲートウェイセッション（Slack、Telegram、CLI、スケジュール実行）をAgentEyeに通常のセッションおよびイベントとして取り込みます。" --- -[Hermes](https://hermes-agent.nousresearch.com)は、チームがすでに使っている場所（Slack、Telegram、CLI、スケジュール実行）からの問い合わせに応答します。HermesセッションキャプチャはそのすべてをAgentEyeに通常のセッションおよびイベントとして取り込むため、チームが毎日対話するアシスタントも、自分たちで作成したエージェントと同様に可観測性を持てます。 +[Hermes](https://hermes-agent.nousresearch.com)は、チームがすでに使っている場所（Slack、Telegram、CLI、スケジュール実行）からの問い合わせに答えます。Hermesセッションキャプチャは、これらすべてをAgentEyeに通常のセッションおよびイベントとして取り込むため、毎日チームが対話しているアシスタントも、自分で書いたエージェントと同じように可視化できます。 -小さなバックグラウンドコレクターが、書き込まれているHermesのローカルセッションストアを読み取り、セッションをAgentEyeに送信します。[Codex](/ja/agenteye/codex-capture)や[OpenClaw](/ja/agenteye/openclaw-capture)のキャプチャと同じ仕組みで動作し、1つのコレクターで複数を同時にキャプチャできます。 +小さなバックグラウンドコレクターがHermesのローカルセッションストアを書き込みと同時に読み取り、セッションをAgentEyeに送信します。動作の仕組みは[Codex](/ja/agenteye/codex-capture)および[OpenClaw](/ja/agenteye/openclaw-capture)のキャプチャと同様で、1つのコレクターで複数を同時にキャプチャできます。 --- ## キャプチャされる内容 -マシン上のすべてのHermesセッションが、どのチャンネルから来たものであっても、キャプチャされます。各セッションはAgentEyeの[セッション](/ja/agenteye/sessions)となり、ユーザーとアシスタントのメッセージ、ツール呼び出し、ツール結果が対応する[イベント](/ja/agenteye/event-stream)になります。 +マシン上のすべてのHermesセッションがキャプチャされます。チャンネルを問わず、それぞれがAgentEyeの[セッション](/ja/agenteye/sessions)になり、ユーザーとアシスタントのメッセージ、ツール呼び出し、ツール結果が対応する[イベント](/ja/agenteye/event-stream)になります。 -セッションが開始されたチャンネル（Slack、Telegram、CLI、またはスケジュール実行）はセッションに記録されるため、区別したり特定のチャンネルでフィルタリングしたりできます。あわせて、セッションが実行されたモデル、開始元のチャットとユーザー、セッションが別のセッションを生成した場合はその親セッションへのリンクも記録されます。 +セッションが開始されたチャンネル（Slack、Telegram、CLI、またはスケジュール実行）はセッションに記録されるため、区別したり1つに絞り込んだりすることができます。それに加えて、セッションが実行されたモデル、セッションが開始されたチャットとユーザー、そしてセッションが別のセッションを生成した場合はその親セッションへのリンクも記録されます。 -セッションは、まだ何も発言されていなくても、Hermesが開始した時点で表示されます。また、あるターンの返答とそのツール呼び出しは、実際に発生した順序に保たれます。セッション終了時には、終了した理由、コスト、使用トークン数も取得できます。 +セッションは、何かが発言されたかどうかに関わらず、Hermesが開始した時点で表示されます。また、1ターンの返信とそのツール呼び出しは、実際に発生した順序で保持されます。セッションが終了すると、終了理由、コスト、使用トークン数も記録されます。 --- -## 有効にする +## 有効にする方法 -キャプチャは有効化するまでオフです。`events:add`権限を持つAPIキーを使ってコレクターをインストールし（[APIキー](/ja/agenteye/api-keys)を参照）、Hermesキャプチャをオンにします。 +キャプチャはデフォルトで無効です。`events:add`権限を持つAPIキー（[APIキー](/ja/agenteye/api-keys)参照）でコレクターをインストールし、Hermesキャプチャを有効にします。 ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -これにより、コレクターのインストール、バックグラウンドサービスへの登録、キャプチャの開始が行われます。正常に動作しているか確認するには： +これでコレクターがインストールされ、バックグラウンドサービスとして登録され、キャプチャが開始されます。実行中であることを確認するには次のコマンドを使用します。 ```bash agenteye-collector health ``` -同じマシンで複数のエージェントをキャプチャしますか？各エージェントのフラグを同じコマンドに追加してください。例：`--hermes-enabled --codex-enabled` +同じマシンで複数のエージェントをキャプチャする場合は、同じコマンドに各フラグを追加してください。例：`--hermes-enabled --codex-enabled` -初回実行時には既存のHermesセッションが一度バックフィルされ、その後の新しいアクティビティは数秒以内にストリーミングされます。Hermesのデータは読み取り専用で、変更や削除は一切行われません。また、再起動をまたいでも各メッセージは1回だけ送信されます。 +初回実行時には既存のHermesセッションが一度バックフィルされ、その後の新しいアクティビティは数秒以内にストリーミングされます。Hermesのデータは読み取られるのみで、変更や削除は一切行われません。また、各メッセージは再起動をまたいでも一度だけ送信されます。 -`health`コマンドは、コレクターがキャプチャしたすべてのデータが実際にAgentEyeに届いているかどうかも報告します。バッチを送信できなかった場合は破棄せず保持して再試行し、未送信のデータがある間はチェックが「unhealthy」と報告します。つまり「healthy」はプロセスが生きているだけでなく、データが届いていることを意味します。 +`health`コマンドは、コレクターがキャプチャしたすべての内容が実際にAgentEyeに届いたかどうかも教えてくれます。バッチが配信できなかった場合は破棄されず保持され、再試行されます。未配信のものが残っている間はチェックが「unhealthy」と報告されるため、「healthy」はプロセスが稼働しているだけでなく、データが到達したことを意味します。 --- ## 表示される場所 -キャプチャされたセッションは**Sessions**に表示され、そのイベントは**Events**ストリームに表示されます。他のエージェントと同様に扱われるため、[セッションリプレイ](/ja/agenteye/sessions)、[検索](/ja/agenteye/queries)、[評価](/ja/agenteye/evaluations)、[アラート](/ja/agenteye/alerts)がすべて利用できます。Hermesエージェントでフィルタリングすると、そのセッションのみを表示できます。 +キャプチャされたセッションは**Sessions**に、イベントは**Events**ストリームに表示されます。他のエージェントと同様に、[セッションリプレイ](/ja/agenteye/sessions)、[検索](/ja/agenteye/queries)、[評価](/ja/agenteye/evaluations)、[アラート](/ja/agenteye/alerts)がすべて利用できます。Hermesエージェントでフィルタリングすれば、そのセッションだけを確認できます。 --- ## プライバシー -Hermesセッションには、コマンド出力、ファイルの内容、エージェントが読み書きしたすべての内容を含む完全なトランスクリプトが含まれており、シークレット情報が含まれる場合があります。キャプチャされたセッションはそのまま送信されるため、AgentEyeにそのコンテンツを集約することが適切な環境でのみキャプチャを有効にしてください。また、コレクターには`events:add`のみにスコープされたキーを付与してください。データの分離方法については[セキュリティ](/ja/agenteye/security)を参照してください。 \ No newline at end of file +Hermesセッションにはコマンド出力、ファイル内容、エージェントが読み書きした内容を含む完全なトランスクリプトが含まれており、シークレット情報が含まれる場合があります。キャプチャされたセッションはそのまま送信されるため、AgentEyeへのコンテンツ集約が適切な環境でのみキャプチャを有効にしてください。また、コレクターには`events:add`のみにスコープされたキーを使用してください。データの分離方法については[Security](/ja/agenteye/security)をご参照ください。 \ No newline at end of file diff --git a/docs/ja/agenteye/incidents.mdx b/docs/ja/agenteye/incidents.mdx index 568fd552..20369db3 100644 --- a/docs/ja/agenteye/incidents.mdx +++ b/docs/ja/agenteye/incidents.mdx @@ -1,26 +1,26 @@ --- title: "インシデント" -description: "アラートが発火すると、誰もがインシデントの状態、担当者、これまでの経緯を一つの帰属タイムラインで確認できます。" +description: "アラートが発火すると、インシデントが開いていること、担当者、これまでの経緯が、属性付きの一本のタイムラインで全員に見えます。" --- -アラートが発火したとき、最初に浮かぶ疑問は常に「誰が対応しているのか?」です。インシデントはその答えを提供します。何かが閾値を超えた瞬間に、全員がインシデントの発生、担当者、そしてこれまでの経緯を正確に把握できます。また、ポストモーテムにそのまま活用できる、クリーンで帰属情報付きの記録が残ります。 +アラートが発火したとき、最初の疑問は常に「誰が対応しているのか？」です。インシデントはその答えを提供します。何かが閾値を超えた瞬間、インシデントが開いていること、誰が担当しているか、そしてこれまでに何が起きたかが、ポストモーテムにそのまま使えるクリーンな属性付き記録とともに、全員に見えるようになります。 -![インシデントの受信トレイ: アラートに紐づいたインシデントと手動で作成されたインシデントのカードが、状態ごとにグループ化され、それぞれに重大度バッジと担当者が表示されている](/agenteye/images/incidents.png) -*受信トレイはオープンなインシデントを状態別にグループ化し、重大度や担当者でフィルタリングできるため、今すぐ人が対応すべきものを一目で確認できます。* +![インシデントの受信トレイ: アラートに紐づいたものと手動で開いたインシデントカードが、それぞれ深刻度バッジと担当者を持ちながら状態ごとにグループ化されている](/agenteye/images/incidents.png) +*受信トレイでは、オープンなインシデントが状態ごとにグループ化され、深刻度と担当者でフィルタリングできるため、今すぐ人間の対応が必要なものだけが表示されます。* -## 誰が担当しているか、一目でわかる +## 担当者を一目で把握 -チャットスレッドで「誰か見ていますか?」とやり取りする必要はもうありません。閾値を超えるとインシデントが自動的に作成され、状態ごとにグループ化された共有受信トレイに表示されます。対応を宣言すると名前が表示され、チームの他のメンバーは対応中であることを把握できます。宣言はチームで共有されます。複数のオペレーターが同じインシデントを宣言でき、それぞれが個別に記録されるため、ウォールームのメンバー全員が名前で識別され、互いに情報が上書きされることはありません。トリアージ担当者を一人アサインし、重大度や担当者で受信トレイをフィルタリングして、自分が担当するものだけに絞り込めます。 +チャットスレッドで「誰か見ている？」と聞く必要はもうありません。閾値超過が起きると自動的にインシデントが開き、状態ごとにグループ化された共有受信トレイに追加されます。確認（Acknowledge）すると自分の名前が紐づくため、チームの他のメンバーは対応中であることがわかります。確認は共有されます。複数のオペレーターが同じインシデントを確認でき、それぞれが個別に記録されるため、ウォールームの全員が互いに上書きされることなく名前で表示されます。トリアージ用のオーナーを一人アサインし、受信トレイを深刻度や担当者でフィルタリングして自分に関係するものだけを絞り込めます。 -## 全経緯を、一つのタイムラインで +## 一本のタイムラインで全経緯を把握 -インシデントが解決したとき、ドキュメントはすでに出来上がっています。任意のインシデントを開くと、閾値超過の証拠、担当者とサブスクライバー、その場での連携用コメントスレッド、そして追記のみ可能なアクティビティタイムラインが表示されます。 +インシデントが終わったときには、すでに報告書が手元にあります。任意のインシデントを開くと、閾値超過の証拠、アサインされた担当者とサブスクライバー、その場でのコーディネーション用のコメントスレッド、そして追記専用のアクティビティタイムラインが確認できます。 -![インシデントの詳細ビュー: 親アラートと閾値超過のサマリー、担当者とサブスクライバー、帰属情報付きのアクティビティタイムライン、コメントスレッド](/agenteye/images/incident-detail.png) -*起きたことすべてが時系列で並び、各行には実行した担当者の名前が付いています。* +![インシデント詳細ビュー: 親アラートと閾値超過のサマリー、担当者とサブスクライバー、属性付きアクティビティタイムライン、コメントスレッド](/agenteye/images/incident-detail.png) +*起きたことすべてが、順番に、各行には誰がそれを行ったかが署名されています。* -すべてのアクション（作成、宣言、解決など）はタイムラインに書き込まれ、後から編集されることはありません。各エントリには帰属情報が付きます。アクションを実行したオペレーターのメールアドレス、または Failproof AI Observability が自律的に行った処理（閾値超過時のインシデント作成など）の場合は **automated** と表示されます。匿名のものも、失われるものも一切ありません。ポストモーテムはほぼ自動的に出来上がります。 +すべてのアクション（オープン、確認、解決など）はそのタイムラインに書き込まれ、決して編集されません。各エントリには属性が付きます。アクションを取ったオペレーターにはメールで、Failproof AI Observability が自律的に行ったこと（閾値超過時のインシデント開設など）には **automated** という属性が付きます。匿名のものはなく、失われるものもないため、ポストモーテムはほぼ自動的に書き上がります。 ## インシデントの状態遷移 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **オープン (firing):** 閾値超過によりインシデントが作成され、通知チャンネルに一度だけページングされます。繰り返し発生した閾値超過は同じインシデントにまとめられ、何度もページングされる代わりに証拠が更新されます。 -- **宣言済み (acknowledged):** オペレーターが対応を引き受けます。インシデントはオープンのまま維持され、その後の閾値超過は静かに証拠を更新します。 -- **解決済み (resolved):** オペレーターがクローズします。条件が解消されたときの自動解決は計画中ですが、まだ有効になっていません。そのため、インシデントは人間が解決するまでオープンのまま残り、実際に何が解消されたかについて全員が誠実に向き合えます。同じアラートで後から新たなインシデントが作成されることもあります。 +- **オープン（firing）:** 閾値超過によりインシデントが開き、チャンネルに一度だけ通知されます。繰り返しの閾値超過は同じインシデントにまとめられ、何度も通知されることなく証拠が更新されます。 +- **確認済み（acknowledged）:** オペレーターが対応を引き受けます。インシデントはオープンのまま維持され、その後の閾値超過は静かに証拠を更新します。 +- **解決済み（resolved）:** オペレーターがクローズします。条件が解消された際の自動解決は計画中ですがまだ有効化されていないため、インシデントは人間が解決するまでオープンのままです。これにより、実際に解消されたものについて全員が正直でいられます。同じアラートで後から新しいインシデントが開くこともあります。 -一つのアラートに対して同時にオープンできるインシデントは最大一つです。そのため、ルールがフラッピングしても重複したインシデントに埋もれることはありません。アラートが検知できなかった事象に対してスタンドアロンのインシデントを手動で作成したり、既存のアラートに紐づけたりすることも可能です（`incidents:write` 権限が必要です）。 +一つのアラートが同時に保持できるオープンなインシデントは最大一つです。そのため、フラッピングするルールによって重複インシデントに埋もれることはありません。手動でインシデントを開くこともできます。アラートが検知していないものに対するスタンドアロンのインシデント、または既存のアラートに紐づけるインシデントを、`incidents:write` 権限があれば作成できます。 -## アクセス方法 +## 場所 -インシデントは `//incidents` にあります。閲覧には **`incidents:read`**、手動インシデントの作成には **`incidents:write`**、宣言・アサイン・コメント・解決には **`incidents:ack`** が必要です。廃止された `alerts:ack` を付与された古いキーも引き続き動作します。`incidents:ack` として認識されるため、オンコールローテーションを再発行する必要はありません。 +インシデントは `//incidents` にあります。閲覧には **`incidents:read`** が必要で、手動インシデントの開設には **`incidents:write`** が、確認・アサイン・コメント・解決には **`incidents:ack`** が必要です。廃止された `alerts:ack` が付与された古いキーは引き続き動作します。`incidents:ack` として扱われるため、オンコールローテーションを再発行する必要はありません。 -## 関連項目 +## 関連 -- [アラート](/ja/agenteye/alerts): 閾値を超えたときにインシデントを作成するルール。 +- [アラート](/ja/agenteye/alerts): 閾値超過時にインシデントを開くルール。 - [エラートラッキング](/ja/agenteye/error-tracking): すべての障害を一か所で確認し、アラートに昇格させる。 -- [監査](/ja/agenteye/audits): どのルールも監視していなかった障害を発見する、スケジュール済みアナリスト。 \ No newline at end of file +- [監査](/ja/agenteye/audits): どのルールも監視していなかった障害を発見するスケジュール型アナリスト。 \ No newline at end of file diff --git a/docs/ja/agenteye/observability.mdx b/docs/ja/agenteye/observability.mdx index d09021ea..03dd7292 100644 --- a/docs/ja/agenteye/observability.mdx +++ b/docs/ja/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- -title: "オブザーブ" -description: "オブザーブ画面では、エージェントのリアルタイムの動作を監視し、個々の実行を詳しく調べることができます。" +title: "観察" +description: "観察画面では、エージェントのリアルタイムの動作を監視し、任意の実行の詳細を掘り下げることができます。" --- -オブザーブ画面では、エージェントのリアルタイムの動作を監視し、個々の実行を詳しく調べることができます。すべての情報はライブで表示され、組織単位にスコープされており、日付範囲・環境・エージェント・セッションでフィルタリングできます。「何かおかしい」と感じてから数秒で該当の実行を特定できます。 +観察画面では、エージェントのリアルタイムの動作を監視し、任意の実行の詳細を掘り下げることができます。すべての情報はリアルタイムで表示され、組織単位でスコープが設定されており、日付範囲・環境・エージェント・セッションでフィルタリングできます。「何かがおかしい」と感じた瞬間から、問題の実行を数秒で特定できます。 -![タイプ別に色分けされ、環境・エージェント・セッションでフィルタリング可能なライブイベントストリーム](/agenteye/images/events-stream.png) +![タイプ別に色分けされたリアルタイムのイベントストリーム。環境・エージェント・セッションでフィルタリング可能](/agenteye/images/events-stream.png) -4つの画面があり、それぞれ専用のページを持っています。 +4つの画面があり、それぞれ独自のページを持っています： -- **[イベントストリーム](/ja/agenteye/event-stream)**: すべてのエージェントにわたる全実行のステップごとのライブログで、最新のものから順に表示されます。組織のホーム画面であり、トリアージの出発点です。 -- **[セッションと実行グラフ](/ja/agenteye/sessions)**: それらのイベントを1実行1行にまとめたビューと、各実行の展開をgit風に可視化したグラフです。 -- **[パフォーマンスメトリクス](/ja/agenteye/telemetry)**: モデル・ツール・フックのレイテンシヒートマップとp50/p95/p99のバイタル。テールスパイクがメディアンから際立って見えます。 -- **[エラートラッキング](/ja/agenteye/error-tracking)**: 発生したすべての問題を一元管理するトリアージ画面。発火中のアラートから問題の実行まで1クリックで到達できます。 +- **[イベントストリーム](/ja/agenteye/event-stream)**：すべてのエージェントにわたる全実行のリアルタイムなステップごとの記録。最新のものが先頭に表示されます。組織のホーム画面であり、トリアージの起点となります。 +- **[セッションと実行グラフ](/ja/agenteye/sessions)**：イベントを実行単位の1行にまとめた一覧と、各実行の流れをgit風の図で可視化したビューです。 +- **[パフォーマンスメトリクス](/ja/agenteye/telemetry)**：モデル・ツール・フックのレイテンシヒートマップと p50/p95/p99 のバイタル指標。中央値から外れたスパイクを一目で把握できます。 +- **[エラートラッキング](/ja/agenteye/error-tracking)**：発生したすべての問題を一元的にトリアージする画面。アラートの発火から問題の実行まで、1クリックで到達できます。 ## 関連情報 -- [評価](/ja/agenteye/evaluations): すべての実行を品質スコアで評価します。 -- [アラート](/ja/agenteye/alerts): 任意のしきい値をページングルールに変換します。 -- [監査](/ja/agenteye/audits): Failproof AI Observability がセッション全体にわたる障害パターンを自動検出します。 -- [CLIとエージェント](/ja/agenteye/cli-and-agents): ターミナルから同じオブザーバビリティを利用できます。 \ No newline at end of file +- [評価](/ja/agenteye/evaluations)：すべての実行を品質スコアで採点します。 +- [アラート](/ja/agenteye/alerts)：任意のしきい値をページングルールに変換します。 +- [監査](/ja/agenteye/audits)：Failproof AI Observability がセッション全体の障害パターンを自動で検出します。 +- [CLI とエージェント](/ja/agenteye/cli-and-agents)：ターミナルから同じオブザーバビリティを利用できます。 \ No newline at end of file diff --git a/docs/ja/agenteye/openclaw-capture.mdx b/docs/ja/agenteye/openclaw-capture.mdx index 60c5b66e..f7892c52 100644 --- a/docs/ja/agenteye/openclaw-capture.mdx +++ b/docs/ja/agenteye/openclaw-capture.mdx @@ -1,49 +1,49 @@ --- title: "OpenClaw セッションキャプチャ" -description: "チームのローカル OpenClaw セッションを通常のセッションやイベントとして AgentEye に取り込めます — OpenClaw の実行方法は変更不要です。" +description: "チームのローカル OpenClaw セッションを通常のセッション・イベントとして AgentEye に取り込みます — OpenClaw の実行方法は一切変更不要です。" --- -チームが [OpenClaw](https://docs.openclaw.ai) を利用している場合、OpenClaw セッションキャプチャを使うと、それらのセッションを通常のセッションやイベントとして AgentEye に取り込めます。これにより、他のエージェントの記録と並べて検索・再生・評価が可能になります。[Python SDK](/ja/agenteye/python-sdk) との補完関係にあり、SDK が自分で書いたエージェントを計装するのに対し、こちらはチームがすでに行っている OpenClaw の作業を — 実行方法を一切変えずに — キャプチャします。 +チームが [OpenClaw](https://docs.openclaw.ai) を利用している場合、OpenClaw セッションキャプチャによってそれらのセッションが通常のセッション・イベントとして AgentEye に取り込まれます。これにより、他の観測データと並べて検索・再生・評価が可能になります。[Python SDK](/ja/agenteye/python-sdk) と補完的な関係にあります。SDK は自分で作成したエージェントを計装するのに対し、こちらはチームがすでに実施している OpenClaw の作業をキャプチャします — 実行方法の変更は不要です。 -小さなバックグラウンドコレクターが OpenClaw のローカルセッショントランスクリプトを書き込まれた順に読み取り、AgentEye に送信します。[Codex キャプチャ](/ja/agenteye/codex-capture) と同じ仕組みで動作し、1 つのコレクターで両方を同時にキャプチャできます。 +小規模なバックグラウンドコレクターが、書き込まれた OpenClaw のローカルセッショントランスクリプトを読み取り、AgentEye に送信します。動作の仕組みは [Codex キャプチャ](/ja/agenteye/codex-capture) と同じであり、1 つのコレクターで両方を同時にキャプチャできます。 --- ## キャプチャされる内容 -マシンの OpenClaw 設定に含まれるすべてのエージェントが、そのマシンのコレクターによってキャプチャされます — エージェントごとのセットアップは不要です。 +マシンの OpenClaw 設定で構成されているすべてのエージェントが、そのマシンのコレクターによってキャプチャされます — エージェントごとの設定は不要です。 -各 OpenClaw セッションは AgentEye の[セッション](/ja/agenteye/sessions)となり、ユーザー・アシスタントのメッセージ、ツール呼び出し、ツール結果が対応する[イベント](/ja/agenteye/event-stream)になります。 +各 OpenClaw セッションは AgentEye の [セッション](/ja/agenteye/sessions) になり、ユーザー・アシスタントのメッセージ、ツール呼び出し、ツール結果が対応する [イベント](/ja/agenteye/event-stream) になります。 --- -## 有効にする方法 +## 有効にする -キャプチャは有効化するまでオフのままです。`events:add` 権限を持つ API キー（[API キー](/ja/agenteye/api-keys)を参照）を使ってコレクターをインストールし、OpenClaw キャプチャを有効にします。 +キャプチャはデフォルトで無効です。`events:add` 権限を持つ API キー（[API キー](/ja/agenteye/api-keys) を参照）でコレクターをインストールし、OpenClaw キャプチャを有効にしてください： ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -これでコレクターがインストールされ、バックグラウンドサービスとして登録され、キャプチャが開始されます。動作を確認するには次のコマンドを実行します。 +これにより、コレクターがインストールされ、バックグラウンドサービスとして登録され、キャプチャが開始されます。動作を確認するには： ```bash agenteye-collector health ``` -同一マシンで複数のエージェントをキャプチャする場合は、各フラグを同じコマンドに追加してください。例: `--openclaw-enabled --codex-enabled`。 +同一マシンで複数のエージェントをキャプチャする場合は、同じコマンドに各フラグを追加してください — 例: `--openclaw-enabled --codex-enabled`。 -初回実行時、既存の OpenClaw セッションが一度バックフィルされ、その後の新しいアクティビティは数秒以内にストリーミングされます。OpenClaw 自身のファイルは読み取り専用で、変更・移動・削除は一切行われません。また、再起動をまたいでも各セッションはちょうど 1 回だけ送信されます。 +初回実行時は、既存の OpenClaw セッションが一度バックフィルされ、その後の新しいアクティビティは数秒以内にストリーミングされます。OpenClaw 自身のファイルは読み取り専用で — 変更・移動・削除は一切行われません — 再起動をまたいでも各セッションはちょうど 1 回だけ送信されます。 --- ## 表示場所 -キャプチャされたセッションは **Sessions** に表示され、そのイベントは **Events** ストリームに表示されます。他のエージェントと同様に扱われるため、[セッションリプレイ](/ja/agenteye/sessions)、[検索](/ja/agenteye/queries)、[評価](/ja/agenteye/evaluations)、[アラート](/ja/agenteye/alerts)がすべて利用できます。OpenClaw エージェントでフィルタリングすることで、そのセッションだけを表示できます。 +キャプチャされたセッションは **Sessions** に表示され、そのイベントは **Events** ストリームに表示されます。他のエージェントと同様に扱われるため、[セッション再生](/ja/agenteye/sessions)、[検索](/ja/agenteye/queries)、[評価](/ja/agenteye/evaluations)、[アラート](/ja/agenteye/alerts) がすべて利用できます。OpenClaw エージェントでフィルタリングすることで、そのデータのみを表示できます。 --- ## プライバシー -OpenClaw のトランスクリプトにはセッションの全内容が含まれます。コマンドの出力、ファイルの内容、エージェントが読み書きしたあらゆる情報が含まれ、シークレット情報が含まれる場合もあります。キャプチャされたセッションはそのまま送信されるため、AgentEye にそのコンテンツを集約することが適切なマシンおよびチームに対してのみキャプチャを有効にしてください。また、コレクターには `events:add` のみにスコープを絞ったキーを使用してください。データがどのように分離して保管されるかについては、[セキュリティ](/ja/agenteye/security)を参照してください。 \ No newline at end of file +OpenClaw のトランスクリプトにはセッション全体の内容が含まれます — コマンドの出力、ファイルの内容、エージェントが読み書きしたデータなど、機密情報が含まれる場合があります。キャプチャされたセッションはそのまま送信されるため、AgentEye へのコンテンツ集約が適切なマシンおよびチームに対してのみキャプチャを有効にし、コレクターには `events:add` のみにスコープを絞ったキーを付与してください。データの分離管理については [セキュリティ](/ja/agenteye/security) を参照してください。 \ No newline at end of file diff --git a/docs/ja/agenteye/overview.mdx b/docs/ja/agenteye/overview.mdx index dc235f77..7c08f5d6 100644 --- a/docs/ja/agenteye/overview.mdx +++ b/docs/ja/agenteye/overview.mdx @@ -1,108 +1,108 @@ --- title: "Failproof AI: エージェントの障害を観測する" -description: "Failproof AI Observability は、本番環境のAIエージェントを観測・評価・改善するためのセルフホスト型プラットフォームです。" +description: "Failproof AI Observability は、本番環境でAIエージェントを観測・評価・改善するためのセルフホスト型プラットフォームです。" --- -Failproof AI Observability は、本番環境のAIエージェントを観測・評価・改善するためのセルフホスト型プラットフォームです。エージェントのあらゆる動作（ツール呼び出し、モデルリクエスト、フック、エラー）を記録し、各実行の品質をスコアリングして、気づかなかった障害を洗い出します。これらすべてを、自社インフラ内で稼働するダッシュボードで確認できます。 +Failproof AI Observability は、本番環境でAIエージェントを観測・評価・改善するためのセルフホスト型プラットフォームです。エージェントの一切の動作（すべてのツール呼び出し、モデルリクエスト、フック、エラー）を記録し、各実行の品質をスコアリングし、見落としていた障害を洗い出します。これらすべてを、自社インフラ内で運用するダッシュボードで確認できます。 -AIエージェントをリリースしていて、実行が失敗した原因の推測に疲れているなら、まずこのページから始めてください。インストールの前に、Failproof AI Observability が提供するものと各要素の関係を説明します。 +AIエージェントをリリースしていて、なぜ実行が失敗したのか推測に頼るのに疲れているなら、まずこのページから始めてください。インストール前に、Failproof AI Observability が提供するものと各コンポーネントの関係を説明します。 -> **Failproof AI Observability は Failproof AI のエンタープライズ製品です。** 実際の動作を見たいですか？デモをリクエストしてください: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) までメールをお送りください。 +> **Failproof AI Observability は Failproof AI のエンタープライズ製品です。** 実際の動作を確認したい方はデモをリクエストしてください: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) までメールをお送りください。 -![Failproof AI Observability のセッション画面。Gitスタイルの実行グラフとイベントタイムラインを並べて表示し、右側のパネルにツール・モデル・フックの実行ごとの内訳を示している](/agenteye/images/session-detail.png) +![Failproof AI Observability のセッション画面。gitスタイルの実行グラフとイベントタイムラインが並び、右側にはツール・モデル・フックの実行ごとの内訳が表示されている](/agenteye/images/session-detail.png) -*各エージェント実行はGitスタイルの実行グラフ（左）とイベントタイムラインとして表示されます。並列サブエージェントはそれぞれ独自のレーンを持ち、右パネルには実行ごとのツール・モデル・フック・トークン消費の内訳が表示されます。* +*エージェントの実行はすべて、gitスタイルの実行グラフ（左）とイベントタイムラインが並んで表示されます。並列サブエージェントはそれぞれ独自のレーンを持ち、右側にはツール・モデル・フック・トークン消費量の内訳が表示されます。* --- ## 実際の動作を見る -2本の短い動画で、チームが最初に必要とする2つの機能を紹介します。実行のトレースと、自動的な障害検出です。 +2本の短い動画で、チームがまず求める2つの機能を紹介します: 実行のトレースと、障害の自動検出です。
-*エージェントトレーシング: 目標からツール、最終回答まで、1回の実行をステップごとに追跡します。* +*エージェントのトレース: 1回の実行をゴールからツール、最終回答まで、ステップごとに追跡します。*
-*Failproof Audit: Failproof AI Observability がセッションをまたいでログを解析し、修正すべき箇所を教えてくれます。* +*Failproof Audit: Failproof AI Observability がセッションをまたいでログを分析し、修正すべき箇所を教えてくれます。* --- -## チームが使う理由 +## チームが活用する理由 -- **エージェントが実際に何をしたかを把握できる。** すべての実行は読みやすいGitスタイルの実行グラフになります。どのツールが並列で動いたか、どのサブエージェントが分岐したか、どこで止まったか、何にコストがかかったかが一目でわかります。 -- **品質の低下を自動で検出できる。** 小規模なスコアリングサービスを接続すると、Failproof AI Observability がすべての完了済み実行をスコアリングし、有用性の低下やハルシネーションの増加を自動的に検出します。 -- **ルールを書いていない障害も発見できる。** 定期監査がセッションをまたいでログを解析し、エラーのクラスター、レイテンシの外れ値、低スコア、スタックした実行を検出して、根拠付きのランク付きファインディングを提供します。 -- **重要なときに通知を受け取れる。** エラーレート、レイテンシ、コスト、評価スコアに対してしきい値ルールを設定でき、確認・割り当て・解決ができるインシデントを発生させます。 -- **自然言語で質問できる。** ダッシュボード内のAIアシスタントに「今週の本番環境の品質トレンドは?」と自分のデータに基づいて質問できます。アシスタントが行う変更はすべて承認が必要です。 -- **データを自社で管理できる。** Failproof AI Observability はセルフホスト型のため、イベント、プロンプト、分析データはすべて自社管理のインフラ内に留まります。 +- **エージェントの実際の動作を把握できる。** すべての実行が読みやすいgitスタイルの実行グラフになります。どのツールが並列で実行されたか、どのサブエージェントが分岐したか、どこで停止したか、何を消費したかが一目でわかります。 +- **品質の低下を自動検出できる。** 小規模なスコアリングサービスを接続すると、Failproof AI Observability がすべての完了した実行をスコアリングするため、有用性の低下やハルシネーションの急増を自動的に検知できます。 +- **ルールを書いていない障害も発見できる。** 定期的な監査がセッションをまたいでログを分析し、エラーのクラスター、レイテンシの外れ値、低スコア、スタックした実行を洗い出し、証拠に基づいたランク付きの調査結果を提供します。 +- **重要な場面で通知を受け取れる。** エラーレート、レイテンシ、コスト、またはエバリュエータースコアに対してしきい値ルールが発火し、確認・割り当て・解決が可能なインシデントを生成します。 +- **自然な日本語で質問できる。** ダッシュボード内のAIアシスタントが「今週の本番環境での品質トレンドは？」といった質問に自分のデータを使って答えます。アシスタントが行う変更はすべて承認が必要です。 +- **データを手元に置ける。** Failproof AI Observability はセルフホスト型です。イベント、プロンプト、分析データはすべて自社が管理するインフラに保存されます。 --- -## 提供機能 +## 提供される機能 -Failproof AI Observability は3つのコンセプト（**observe（観測）**、**analyze（分析）**、**admin（管理）**）を中心に構成されており、ダッシュボードの左サイドバーに反映されています。 +Failproof AI Observability は3つの考え方（**観測**、**分析**、**管理**）を中心に構成されており、ダッシュボードの左サイドバーに反映されています。 -**Observe**（実際に起きたことの記録）: +**観測**（何が起きたかの生の真実）: -- **[イベントストリーム](/ja/agenteye/event-stream)**: すべての実行のステップごとのリアルタイムトレイル（ツール呼び出し、モデル呼び出し、フック、エラー）。 -- **[セッション](/ja/agenteye/sessions)**: それらのイベントを1実行1行にまとめたもの。各実行はスコアリング可能で、Gitスタイルの実行グラフが付属。 -- **[パフォーマンスメトリクス](/ja/agenteye/telemetry)**: モデル・ツール・フックのサーフェスごとのレイテンシヒートマップとp50/p95/p99バイタル。テールスパイクが中央値から際立って見えます。 -- **[エラートラッキング](/ja/agenteye/error-tracking)**: 発生したすべての問題を1つのトリアージ画面で確認でき、発火したアラートからワンクリックでアクセス可能。 +- **[イベントストリーム](/ja/agenteye/event-stream)**: すべての実行のリアルタイムなステップごとの記録（ツール呼び出し、モデル呼び出し、フック、エラー）。 +- **[セッション](/ja/agenteye/sessions)**: それらのイベントを1回の実行ごとに集約した行。各行はスコアリング可能で、gitスタイルの実行グラフを持ちます。 +- **[パフォーマンスメトリクス](/ja/agenteye/telemetry)**: モデル・ツール・フックに対するサーフェスごとのレイテンシヒートマップとp50/p95/p99のバイタル。テール急増が中央値から際立って見えます。 +- **[エラートラッキング](/ja/agenteye/error-tracking)**: 発生したすべての問題を一元的にトリアージするサーフェス。発火したアラートからワンクリックでアクセスできます。 -![Toolsの観測ページ: レイテンシヒートマップ、パーセンタイルバンド、24の時間ビンにわたるツール分布バー](/agenteye/images/tools.png) +![ツールの観測ページ: レイテンシヒートマップ、パーセンタイルバンド、24タイムビンにわたるツール分布バー](/agenteye/images/tools.png) -*各観測サーフェスにはスパークラインとp50/p95/p99バイタル、レイテンシヒートマップ、パーセンタイルバンドが表示されます。表示例: ツール。* +*各観測サーフェスには、スパークラインとp50/p95/p99のバイタル、レイテンシヒートマップ、パーセンタイルバンドが組み合わされています。表示例: ツール。* -**Analyze**（活動を洞察に変える）: +**分析**（活動を洞察に変える）: -- **[クエリ](/ja/agenteye/queries)** と **[ダッシュボード](/ja/agenteye/dashboards)**: イベントと評価に対して保存済みSQLを実行し、組織スコープの共有ダッシュボードにグラフ化。 -- **[評価](/ja/agenteye/evaluations)**: 独自の評価サービスが生成する品質スコア。スコアごとの理由付きで表示。 -- **[監査](/ja/agenteye/audits)**: セッションをまたいで障害パターンを検出する定期調査。 -- **[アラート](/ja/agenteye/alerts)** と **[インシデント](/ja/agenteye/incidents)**: 通知を発するしきい値ルールと、トリアージのためのインシデントワークフロー。 +- **[クエリ](/ja/agenteye/queries)**と**[ダッシュボード](/ja/agenteye/dashboards)**: イベントと評価に対する保存済みSQL。組織スコープの共有ダッシュボードにチャートとして表示されます。 +- **[評価](/ja/agenteye/evaluations)**: 独自のエバリュエーターサービスが生成した品質スコア。スコアごとの根拠も含まれます。 +- **[監査](/ja/agenteye/audits)**: セッションをまたいで障害パターンを洗い出す定期的な調査。 +- **[アラート](/ja/agenteye/alerts)**と**[インシデント](/ja/agenteye/incidents)**: 通知を送るしきい値ルール、およびトリアージのためのインシデントワークフロー。 -**Interfaces**（自分のやり方でデータにアクセス）: +**インターフェース**（自分のやり方でデータにアクセスする）: -- **[CLI](/ja/agenteye/cli-and-agents)**: ターミナルやスクリプトからデプロイ全体を操作でき、コーディングエージェントに自然言語で任せることも可能。 -- **[AIアシスタント](/ja/agenteye/assistant)**: ダッシュボード内から自然言語でエージェントに関する質問ができます。 -- **REST API**: ダッシュボードとCLIで行えることはすべてREST APIで実行可能です。スコープ付きの[APIキー](/ja/agenteye/api-keys)で直接呼び出せ、イベントの取り込み、セッションと評価のクエリ、ダッシュボード・アラート・監査・ユーザー・キーの管理が可能です。Failproof AI Observability を自社ツールと連携させられます。 +- **[CLI](/ja/agenteye/cli-and-agents)**: ターミナルやスクリプトからデプロイメント全体を操作でき、コーディングエージェントに自然言語で実行させることもできます。 +- **[AIアシスタント](/ja/agenteye/assistant)**: ダッシュボード内でエージェントについて自然言語で質問できます。 +- **REST API**: ダッシュボードとCLIが行うすべての操作は、スコープされた[APIキー](/ja/agenteye/api-keys)を使って直接呼び出せるREST APIによって支えられています。イベントの取り込み、セッションや評価のクエリ、ダッシュボード・アラート・監査・ユーザー・キーの管理が可能で、Failproof AI Observability を自社のツールに組み込めます。 -**Admin**（チームのための運用）: +**管理**（チームのために運用する）: -- **[APIキー](/ja/agenteye/api-keys)**: コレクター・ダッシュボード・アシスタント向けのスコープ付きトークン。 -- **ユーザー**: パスワードレスのメールベース認証と許可リスト。 -- **設定**: モデルのコンテキストウィンドウオーバーライドを含む組織ごとの設定。 +- **[APIキー](/ja/agenteye/api-keys)**: コレクター、ダッシュボード、アシスタント向けのスコープされたトークン。 +- **ユーザー**: パスワードレスのメールベース認証とアローリスト。 +- **設定**: モデルのコンテキストウィンドウのオーバーライドを含む、組織ごとの設定。 --- -## 各要素の関係 +## コンポーネントの関係 -データはエージェントコードからダッシュボードへ一方向に流れます。エージェント（Python SDK経由）がイベントをagenteye-collectorに送り、collectorがサーバーに転送し、サーバーがダッシュボードを提供します。スコアリングサービス（評価）とAIアシスタントサービス（ダッシュボード内チャット）の2つのオプションサービスがこれを補完します。 +データはエージェントコードからダッシュボードへと一方向に流れます。エージェント（Python SDK経由）がイベントをagenteye-collectorに送信し、collectorがサーバーに転送し、サーバーがダッシュボードを提供します。オプションのサービスとして、スコアリングサービス（評価）とAIアシスタントサービス（ダッシュボード内チャット）が追加できます。 -- **Python SDK**: エージェントに数行の `agenteye.event.*` 呼び出しを追加するだけで、イベントはローカルにバッファリングされます。 -- **agenteye-collector**: 各エージェントマシン上で動作する軽量デーモンで、イベントをバッチ処理してサーバーに転送します。 -- **サーバー**: イベントを取り込み、自社データベースに運用状態を保持し、ダッシュボード・CLI・独自インテグレーションが使用するREST APIを提供します。 -- **ダッシュボード**: すべてを探索できる場所。 +- **Python SDK**: エージェントにいくつかの `agenteye.event.*` 呼び出しを追加するだけです。イベントはローカルにバッファリングされます。 +- **agenteye-collector**: 各エージェントマシン上の軽量デーモン。イベントをバッチ処理してサーバーに転送します。 +- **サーバー**: イベントを取り込み、自社のデータベースで運用状態を管理し、ダッシュボード・CLI・独自インテグレーションが使用するREST APIを提供します。 +- **ダッシュボード**: すべてを探索する場所。 - **オプションサービス**: スコアリングサービス（評価）とAIアシスタントサービス（ダッシュボード内チャット）。 -ドキュメント全体で使用される用語（*event、session、evaluation、audit、finding、incident*）については、[コンセプト](/ja/agenteye/concepts)を参照してください。 +ドキュメント全体で使用される用語（*イベント、セッション、評価、監査、調査結果、インシデント*）については、[概念](/ja/agenteye/concepts)を参照してください。 --- ## Failproof AI Observability の入手方法 -Failproof AI Observability は Failproof AI のエンタープライズ製品で、ポリシーとガードレール製品であるFailproof AI Enforcementと連携して Failproof AI ブランドのもとで動作します。完全に自社環境内で稼働します。パッケージへのアクセス権をまだお持ちでない場合は、デモをリクエストしてください。セットアップをお手伝いします: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) までメールをお送りください。 +Failproof AI Observability は Failproof AI のエンタープライズ製品で、Failproof AI ブランドのもとでポリシーとガードレール製品である Failproof AI Enforcement と併用できます。完全に自社環境内で動作します。まだパッケージへのアクセス権をお持ちでない場合は、デモをリクエストしてください。セットアップをサポートします: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) までメールをお送りください。 --- ## 次のステップ -- [コンセプト](/ja/agenteye/concepts): Failproof AI Observability の用語を一か所にまとめて解説。 -- [オブザーバビリティ](/ja/agenteye/observability): エージェントの動作を実行ごとに追跡する。 -- [セキュリティ](/ja/agenteye/security): Failproof AI Observability がデータをどのように隔離し、管理下に置くか。 \ No newline at end of file +- [概念](/ja/agenteye/concepts): Failproof AI Observability の用語を一箇所にまとめたリファレンス。 +- [オブザーバビリティ](/ja/agenteye/observability): 実行ごとにエージェントの動作を追跡する。 +- [セキュリティ](/ja/agenteye/security): Failproof AI Observability がデータを分離し、管理下に置く仕組み。 \ No newline at end of file diff --git a/docs/ja/agenteye/python-sdk-skill.mdx b/docs/ja/agenteye/python-sdk-skill.mdx index 16c57094..eeadb36b 100644 --- a/docs/ja/agenteye/python-sdk-skill.mdx +++ b/docs/ja/agenteye/python-sdk-skill.mdx @@ -1,74 +1,74 @@ --- title: "Failproof AI Observability Python SDK エージェントスキル" -description: "計装されていないエージェントから可視化できるイベントへ — コーディングエージェントが計装ポイントを見つけ、実装し、正常に動作することを確認します。" +description: "計装されていないエージェントから可視化できるイベントへ。コーディングエージェントが計装ポイントを特定し、実装し、正しく機能することを証明します。" --- -コーディングエージェントに *「このエージェントに Failproof AI Observability を追加して」* と伝えるだけで、エージェントがループを読み込み、計装箇所を特定し、コードを書き、ジョブ完了と宣言する前にイベントを検証してくれます。 +コーディングエージェントに *「このエージェントに Failproof AI Observability を追加して」* と伝えるだけで、あとはエージェントがループを読み込み、計装箇所を判断し、コードを書き、ジョブ完了を宣言する前にイベントを検証します。 -**Python SDK スキル**（`agenteye-python-sdk`）は *エージェントスキル* です。Claude Code や Codex などのコーディングエージェントが、タスクに合致した際にオンデマンドで読み込む指示ファイルのフォルダです。このスキルは [Python SDK](/ja/agenteye/python-sdk) の使い方をエージェントに教えるものであり、ライブラリではなく、SDK の動作自体には何も変更を加えません。 +**Python SDK スキル** (`agenteye-python-sdk`) は *Agent Skill* です。これは、Claude Code や Codex などのコーディングエージェントがタスクに応じてオンデマンドで読み込む、指示のフォルダーです。このスキルは [Python SDK](/ja/agenteye/python-sdk) の使い方をエージェントに教えるものであり、ライブラリではなく、SDK の動作を変えるものでもありません。 -## 計装は書きやすい分、静かに間違えやすい +## 計装は書きやすいが、気づかないうちに間違えやすい -SDK はシンプルです。イベントメソッドは 13 個、すべてキーワード専用です。コーディングエージェントは [Python SDK](/ja/agenteye/python-sdk) リファレンスを読めば、もっともらしい計装を 1 分で生成できます。 +SDK は小さく、13 種類のイベントメソッドはすべてキーワード専用です。コーディングエージェントは [Python SDK](/ja/agenteye/python-sdk) リファレンスを読めば、1 分ほどでもっともらしい計装コードを生成できます。 -問題は、この SDK は間違えてもエラーを投げず、誤った計装は正しい計装とまったく同じように見えることです。ダッシュボードを開いて空っぽだと気づくまで分かりません。実際に時間を浪費させるミスはすべて「沈黙」の形をしています。 +問題は、この SDK は間違えてもエラーを投げないことです。そして、間違った計装は正しい計装とまったく同じに見えます——誰かがダッシュボードを開いて空っぽだと気づくまでは。実際に時間を浪費させる間違いはすべて「沈黙」です。 -| ミスの内容 | 見え方 | +| 間違い | 見た目 | |---|---| -| `agent_start` がない | すべてのイベントは記録される。セッションはゼロ。 | -| 環境が設定されていない | すべて正常に動作し、`dev` 環境として記録される。 | -| `outcome="failure"` | 実行結果は成功表示になる — カウントされるのは `failed`、`error`、`timeout`、`rejected` のみ。 | -| フィールド名のタイポ | 受理されて新しいフィールドとして保存される。 | -| スレッドプールからイベントを送出 | 無言でドロップされる。 | +| `agent_start` がない | すべてのイベントが着地する。セッションはゼロ。 | +| 環境が設定されていない | すべて正常に動作しているが、`dev` として記録される。 | +| `outcome="failure"` | 実行は成功に見える——実際にカウントされるのは `failed`、`error`、`timeout`、`rejected` のみ。 | +| フィールド名のタイポ | 受け入れられ、新しいフィールドとして保存される。 | +| スレッドプールからイベントを送出 | 無音でドロップされる。 | -これらはいずれもエラーを投げません。テストでも検出されません。スキルにはそれぞれのケースが、検出のためのチェックとともにコントラクトとして明記されています。 +これらはどれもエラーを投げません。テストにも現れません。それぞれがスキルの中で、それを検出するチェックとともに「契約」として明示されています。 -## スキルの動作手順 +## スキルが行うこと（順を追って） -このスキルは、注意深いエンジニアが行うのと同じ 3 ステップを実行します。 +スキルは、注意深いエンジニアが行うのと同じ 3 つのステップを実行します。 -1. **計画する。** エージェントのループを読み込み、あなたにしか答えられない 2 つの問いを立てます。「1 回の実行とは何か（`session_id`）」と「識別可能なアクターは誰か（`agent_id`）」です。コードを書く前にこれを合意します。後から変更すると履歴が分断され、トレンドが壊れるからです。 -2. **実装する。** すべての呼び出し箇所に渡すのではなく、1 回の実行につき 1 度だけアイデンティティをバインドし、並行処理に安全な設計を選択します。単純な近道では、並行する 2 つの実行が 1 つのセッションに無言で混入してしまうため、この選択が重要です。 -3. **検証する。** エージェントを実行し、生成されたイベントファイルを読み込んで、`agent_start` が存在するか、環境が正しいか、1 回の実行が 1 つのセッションを生成しているかを確認します。 +1. **計画。** エージェントループを読み込み、あなたにしか答えられない 2 つの質問をします。1 回の実行とは何か（`session_id`）、そして識別可能なアクターは誰か（`agent_id`）。コードを書く前にこれらを合意します。後から変更すると履歴が分断され、トレンドが壊れるためです。 +2. **実装。** 実行ごとに 1 度だけ ID をバインドし、すべての呼び出しサイトに引き回すのではなく、並行性に安全な形式を選択します。これは重要な詳細です。明白なショートカットを使うと、重複する 2 つの実行が無音で 1 つのセッションに混入します。 +3. **検証。** エージェントを実行し、生成されたイベントファイルを読み込んで、`agent_start` が存在すること、環境が正しいこと、1 回の実行が 1 つのセッションを生成したことを確認します。 -この 3 ステップ目こそ、みんなが省略するステップです。SDK はイベントをローカルファイルに書き込むので、サーバーも API キーもネットワークも不要で、ラップトップ上で完全な統合を証明できます。だからこそスキルはこのステップを必ず実行します。 +3 番目のステップが、人々がスキップするものです。SDK はイベントをローカルファイルに書き込むため、完全なインテグレーションをサーバーなし・API キーなし・ネットワークなしでラップトップ上で証明できます。だからこそ、スキルはこのステップを必須としています。 ## 他のスキルとの関係 -3 つのスキルが明確に役割分担しています。 +3 つのスキル、明確な役割分担： -| スキル | 使うタイミング | 対象 | +| スキル | 使う場面 | 触れる対象 | |---|---|---| -| **Python SDK スキル**（このページ） | エージェントにテレメトリを *送出* させたいとき — 「オブザーバビリティを追加して」「エージェントが表示されない」 | エージェントのリポジトリにコードを書く。何も読み込まない。 | -| **[Evaluator スキル](/ja/agenteye/evaluator-skill)** | 実行結果を *スコアリング* したいとき — 「何を計測すべきか？」 | リポジトリにコードを書く。テレメトリを読み込む。 | -| **[CLI スキル](/ja/agenteye/cli-skill)** | 何が起きたかを *読み取りたい*、またはデプロイを操作したいとき | あなたの代わりに CLI を操作する（変更を含む） | +| **Python SDK スキル**（このページ） | エージェントにテレメトリを *送出* させたいとき——「オブザーバビリティを追加」「エージェントが表示されないのはなぜ？」 | エージェントのリポジトリにコードを書く。何も読まない。 | +| **[Evaluator スキル](/ja/agenteye/evaluator-skill)** | 実行を *スコアリング* したいとき——「何を測定すべきか？」 | リポジトリにコードを書く；テレメトリを読む | +| **[CLI スキル](/ja/agenteye/cli-skill)** | 何が起きたかを *読み取りたい*、またはデプロイを操作したいとき | あなたの代わりに CLI を操作（変更を含む） | -この順番で連携します。このスキルでイベントを流し、Evaluator でスコアリングし、CLI で読み返します。エージェントがセッションを送出するまで、評価するものも読み取るものも存在しないため、ゼロから始めるならここからスタートしてください。 +この順序で連携します。このスキルでイベントを流し始め、エバリュエーターがスコアリングし、CLI で読み返す。エージェントがセッションを送出するまでは評価するものも読むものも存在しません。ゼロから始めるなら、ここから始めてください。 ## 前提条件 -1. **Python 3.10 以上** と計装したいエージェントのコードベース。 -2. **SDK。** パブリックのパッケージインデックスではなく、プライベートの wheel としてお客様に配布されます。入手方法とインストール方法はオンボーディング時にご案内します。スキルはインストールパスを把握しており、見つからない場合は推測せずに確認します。 -3. **それだけ。** ダッシュボードへのログイン、API キー、ネットワーク接続は不要です。SDK が書き込んだイベントファイルを使って検証するため、オフラインで作業を完了し、証明できます。 +1. **Python 3.10 以上** と、計装対象のエージェントコードベース。 +2. **SDK。** 公開インデックスではなく、プライベートホイールとして顧客に配布されます。入手・インストール方法はオンボーディングでカバーされています。スキルはインストールパスを把握しており、見つからない場合は推測せずに確認します。 +3. **その他は不要。** ダッシュボードへのログイン、API キー、ネットワーク接続は不要です。スキルは SDK が書き込んだイベントファイルに対して検証を行うため、オフラインでも作業を完了し、証明できます。 ## 入手方法 -スキルはパブリックの [`FailproofAI/skills`](https://github.com/FailproofAI/skills) コレクションにあります。 +スキルは公開の [`FailproofAI/skills`](https://github.com/FailproofAI/skills) コレクションにあります。 ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -`-g` を追加するとカレントプロジェクトだけでなくすべてのプロジェクトにインストールされます。シンボリックリンクを使用しない環境では `--copy` を指定してください。Codex の場合は `-a codex` を渡してください。 +`-g` を追加すると現在のプロジェクトだけでなく、すべてのプロジェクトにインストールできます。環境がシンボリックリンクに対応していない場合は `--copy` を使用してください。Codex の場合は `-a codex` を渡してください。 -## 手動インストール +## 手動でインストールする -エージェントスキルは `SKILL.md` と参照ファイルを含むフォルダです。インストーラーを使わない場合は以下の手順で設定できます。 +Agent Skills は `SKILL.md` と参照ファイルを含むフォルダーです。インストーラーを使いたくない場合： -- **Claude Code**: `agenteye-python-sdk/` フォルダを `~/.claude/skills/`（すべてのプロジェクト）または `/.claude/skills/`（そのリポジトリのみ）にコピーします。Claude Code は自動的に検出します — `/skills` リストで確認するか、それに合致する質問をしてみてください。 -- **Codex**: Codex も同じ `SKILL.md` を読み込みます。同梱の `agents/openai.yaml` に `allow_implicit_invocation: true` が設定されているため、タスクに合致すると自動選択されます。明示的に呼び出す場合は `$agenteye-python-sdk` を使用してください。 +- **Claude Code**: `agenteye-python-sdk/` フォルダーを `~/.claude/skills/`（すべてのプロジェクト）または `/.claude/skills/`（そのリポジトリのみ）にコピーします。Claude Code は自動的に検出します。`/skills` リストで確認するか、マッチするリクエストを投げてみてください。 +- **Codex**: Codex も同じ `SKILL.md` を読みます。バンドルされた `agents/openai.yaml` が `allow_implicit_invocation: true` を設定しているため、タスクがマッチした場合は自動選択されます。それ以外は `$agenteye-python-sdk` として呼び出してください。 -**計装したいコードを含むリポジトリ内** でエージェントを実行してください — スキルは何かを提案する前にエージェントのループを読み込みます。 +**計装対象のコードを含むリポジトリ** でエージェントを実行してください——スキルは何かを提案する前にエージェントループを読み込みます。 ## セッションの例 @@ -103,29 +103,29 @@ agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and Want me to fix those too? ``` -注目すべきパターン：提案する前にコードを読み込み、あなたにしか答えられない質問だけを行い、既存の ID を再利用し、スレッドプールを確認した上で並行処理に安全な設計を選択し、成功を宣言する代わりに **実際のイベントを読み込んで検証し**、静かに失敗することが分かっていた箇所をフラグとして報告しています。 +注目すべきパターン：提案する前にコードを読み、あなたにしか答えられない質問だけをし、既存の ID を再利用し、スレッドプールを見たから*こそ*並行性に安全な形式を選択し、成功を宣言するのではなく**実際のイベントを読んで検証**し、そして静かに失敗するとわかっている箇所をフラグで示しています。 -## 使えるプロンプトの例 +## できること -- *「エージェントがダッシュボードに表示されないのはなぜ？」* → 段階的に確認します。イベントが書き込まれているか、`agent_start` があるか、環境が正しいか、コレクターが同じ場所を読んでいるか。 -- *「すべてが dev 環境として記録される。」* → 環境が一度も設定されていないか、後の呼び出しでリセットされています。 -- *「トークントラッキングを追加して。」* → LLM ラッパーを見つけて、モデル、停止理由、使用量を記録します。 -- *「サブエージェントも計装して。」* → 1 つのセッション、異なるエージェントラベル、親の下にネスト。 -- *「計装のテストを書いて。」* → SDK を一時ディレクトリに向けて、書き込まれたイベントをアサートします。 +- *「なぜエージェントがダッシュボードに表示されないのか？」* → ステップを追って確認：イベントが書き込まれているか、`agent_start` はあるか、環境は正しいか、コレクターは同じ場所を読んでいるか。 +- *「すべてが dev の下に着地している。」* → 環境が設定されていないか、後の呼び出しでリセットされている。 +- *「トークントラッキングを追加して。」* → LLM ラッパーを見つけて、モデル、停止理由、使用量を記録する。 +- *「サブエージェントも計装して。」* → 1 つのセッション、識別可能なエージェントラベル、親の下にネスト。 +- *「計装のテストを書いて。」* → SDK を一時ディレクトリに向け、書き込んだイベントをアサートする。 -## 注意点 +## 注意事項 -**検証ステップを省略しないこと。** このスキルが価値を持つのは最後のステップ、つまりエージェントを実行して実際のイベントを読み返すことにあります。計装を書いて終わりにしたエージェントは、作業の簡単な半分しか終えていません。静かに失敗する半分が残っています。 +**検証させること。** このスキルを使う価値があるのは最後のステップです——エージェントを実行してイベントを読み返すことです。計装を書いて止まるエージェントは、簡単な半分しかやっていません。静かに失敗するのは残りの半分です。 -**コードの前に名前を決めること。** `session_id` と `agent_id` は、すべての画面でグルーピングの軸になります。後からリネームすると履歴が分断されます。古い実行は古いラベルのままになり、トレンドが壊れます。スキルが確認しますので、少し時間をかけて答える価値があります。 +**コードより先に名前を合意すること。** `session_id` と `agent_id` は、すべての画面がグループ化する軸です。後から名前を変えると履歴が分断されます。古い実行は古いラベルのままになり、トレンドが壊れます。スキルが確認しますが、その答えは少し考える価値があります。 -**エージェントがパブリックのインデックスから SDK をインストールしようとしている場合、スキルが読み込まれていません。** SDK はプライベートで配布されています。そのような提案は、コーディングエージェントがスキルに従わずに推測していることを示す確実なサインです。その場で止めて、スキルがインストールされているかを確認してください。 +**エージェントが公開インデックスから SDK のインストールを提案したら、スキルがロードされていません。** SDK はプライベートで配布されています。その提案は、コーディングエージェントがスキルに従わずに推測している確実なサインです——そこで止めて、スキルがインストールされているか確認してください。 -それ以外の影響範囲は小さく、ワーキングディレクトリにコードを書き込み、指定した場所にイベントファイルを書き込むだけです。デプロイから何かを読み取ることも、デプロイに変更を加えることもありません。 +それ以外の影響範囲は小さいです。作業ディレクトリにコードを書き、指定した場所にイベントファイルを書き込みます。デプロイから何も読まず、何も変更しません。 ## 次のステップ -- **[Python SDK](/ja/agenteye/python-sdk)**: このスキルが自動化する処理の背後にある完全なイベントリファレンス — すべてのイベントタイプとフィールド。 -- **[Sessions](/ja/agenteye/sessions)**: イベントが記録された後、計装によって生成されるもの。 -- **[Evaluator エージェントスキル](/ja/agenteye/evaluator-skill)**: 実行が記録されたら次のステップ — スコアリング。 -- **[CLI エージェントスキル](/ja/agenteye/cli-skill)**: テレメトリの読み返し。 \ No newline at end of file +- **[Python SDK](/ja/agenteye/python-sdk)**: このスキルが自動化する処理の背後にある完全なイベントリファレンス——すべてのイベントタイプとフィールド。 +- **[Sessions](/ja/agenteye/sessions)**: イベントが着地した後、計装が生成するもの。 +- **[Evaluator Agent Skill](/ja/agenteye/evaluator-skill)**: 実行が着地したあとの次のステップ——スコアリング。 +- **[CLI Agent Skill](/ja/agenteye/cli-skill)**: テレメトリを読み返す。 \ No newline at end of file diff --git a/docs/ja/agenteye/python-sdk.mdx b/docs/ja/agenteye/python-sdk.mdx index faf7ccd6..e28bda4d 100644 --- a/docs/ja/agenteye/python-sdk.mdx +++ b/docs/ja/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "AIエージェントが本番環境で何をしたかを正確に把握する: すべてのエージェント実行、ツール呼び出し、モデルリクエスト、フック、および人間の介入。" +description: "AIエージェントが本番環境で何をしたかを正確に把握する：すべてのエージェント実行、ツール呼び出し、モデルリクエスト、フック、人間の介入を記録します。" --- -AIエージェントが本番環境で何をしたかを正確に把握する: すべてのエージェント実行、ツール呼び出し、モデルリクエスト、フック、および人間の介入。Failproof AI Observability Python SDKは、エージェントコードの内側からその実行履歴を記録し、何が起きたかをデバッグ・監査・評価できるようにします。Failproof AI Observabilityでエージェントを観測したい場合にご利用ください。 +AIエージェントが本番環境で何をしたかを正確に把握できます：すべてのエージェント実行、ツール呼び出し、モデルリクエスト、フック、人間の介入を網羅します。Failproof AI ObservabilityのPython SDKは、エージェントコードの内側からその記録を残し、何が起きたかをデバッグ・監査・評価できるようにします。Failproof AI Observabilityでエージェントを観測したいときにご利用ください。 -内部では、SDKが構造化イベントをローカルのJSONLファイルに書き込み、コレクターデーモンがそれらを自動的に収集してプラットフォームに送信します。これらのファイルを自分で管理する必要はありません。 +SDKの内部では、構造化されたイベントをローカルのJSONLファイルに書き込み、コレクターデーモンがそれらを自動的に収集してプラットフォームへ送信します。これらのファイルをご自身で管理する必要はありません。 -> **ヒント:** Failproof AI Observabilityを初めてお使いですか？このページはSDKイベントの完全なリファレンスです。 +> **ヒント:** Failproof AI Observabilityを初めてお使いの方へ：このページはSDKイベントの完全なリファレンスです。
@@ -18,15 +18,15 @@ AIエージェントが本番環境で何をしたかを正確に把握する: ## インストール -SDKは公開パッケージインデックスではなく、プライベートホイールとしてお客様に配布されます。取得・インストール・バージョン固定の方法はオンボーディングで説明しています。アクセスが必要な場合は Failproof AI の担当者にお問い合わせください。 +SDKは、公開パッケージインデックスではなく、プライベートホイールとしてお客様に配布されます。取得方法・インストール方法・バージョン固定方法はオンボーディング時にご案内します。アクセスが必要な場合は Failproof AI の担当者にお問い合わせください。 -インストール後、以下で確認してください: +インストール後、以下のコマンドで確認してください： ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -コーディングエージェントに統合作業をすべて任せたい場合は、[Python SDK Agent Skill](/ja/agenteye/python-sdk-skill) をご利用ください。インストールパスを把握し、計装ポイントを計画・実装して、イベントが正しく届いているか検証します。 +コーディングエージェントにインテグレーション全体を任せたい場合は、[Python SDK Agent Skill](/ja/agenteye/python-sdk-skill) をご利用ください。インストールパスの把握、計装ポイントの計画・実装、イベント到達の検証まで対応します。 --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### 実際の呼び出しへの計装 -実際には、既存のエージェントコードをラップします。モデル呼び出しの前に `model_request`、後に `model_response` を配置することで、2つのイベントが実際のリクエストをまたぎ、Failproof AI Observabilityがペアとして関連付けられるようになります: +実際には、既存のエージェントコードをラップします。モデル呼び出しの前後をそれぞれ `model_request` と `model_response` で囲むことで、2つのイベントが実際のリクエストをまたぎ、Failproof AI Observability がそれらを対応付けられるようになります： ```python import anthropic @@ -97,9 +97,9 @@ agenteye.event.model_response( ツール呼び出しも同様に `tool_use` と `tool_result` でラップし、ペア間で同じ `tool_call_id` を使い回します。 -ダッシュボードに届いたイベントは、タイプ別に色分けされ、環境・エージェント・セッションでフィルタリングできます: +これらのイベントがダッシュボードに届いたときの表示例です。イベントタイプごとに色分けされ、環境・エージェント・セッションでフィルタリングできます： -![ライブイベントストリーム。イベントタイプ別に色分けされ、環境・エージェント・セッションでフィルタリング可能](/agenteye/images/events-stream.png) +![イベントタイプごとに色分けされ、環境・エージェント・セッションでフィルタリング可能なライブイベントストリーム](/agenteye/images/events-stream.png) --- @@ -108,69 +108,69 @@ agenteye.event.model_response( ```python agenteye.configure( base_dir=None, # Path | str | None. デフォルト: $AGENTEYE_HOME または ~/.agenteye - flush_interval=0.5, # float, フラッシュサイクルの間隔（秒） + flush_interval=0.5, # float、フラッシュ間隔（秒） environment=None, # str | None. デプロイ環境ラベル ) ``` -`event.*` を呼び出す前に一度だけ呼び出してください。省略しても問題ありません。デフォルト設定でそのまま動作します。すべての引数はキーワード専用です。上記のように名前で渡してください。 +`event.*` を呼び出す前に一度だけ実行してください。省略しても問題ありません。デフォルト値でそのまま動作します。すべての引数はキーワード専用です。上記のように名前を指定して渡してください。 -`base_dir` が `None`（デフォルト）の場合、SDKは `$AGENTEYE_HOME` が設定されていればそれを使用し、未設定の場合は `~/.agenteye` にフォールバックします。これはコレクター自身の解決方法と一致しているため、`AGENTEYE_ENVIRONMENT` 環境変数ひとつで SDK とコレクター両方のイベントスプールを共有設定できます。 +`base_dir` が `None`（デフォルト）の場合、`$AGENTEYE_HOME` が設定されていればそれを参照し、設定されていなければ `~/.agenteye` にフォールバックします。これはコレクター自身の解決ロジックと一致するため、`AGENTEYE_HOME` 環境変数を1つ設定するだけで、SDKとコレクター両方の共有イベントスプールを設定できます。 --- ## 環境 -すべてのイベントにデプロイ環境のラベルを付けます（`production`、`staging`、`qa`、`canary` など）。一度設定するだけで、SDKがすべてのイベントに自動的に付加します。 +すべてのイベントにデプロイ環境（`production`、`staging`、`qa`、`canary` など）のラベルを付けます。一度設定すれば、SDKがすべてのイベントに自動的に付与します。 -**オプション1: `configure()` 経由:** +**オプション1：`configure()` 経由：** ```python agenteye.configure(environment="production") ``` -**オプション2: 環境変数経由:** +**オプション2：環境変数経由：** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**優先順位:** `configure(environment=...)` が環境変数より優先されます。どちらも設定されていない場合、デフォルトは `"dev"` です。 +**優先順位：** `configure(environment=...)` が環境変数より優先されます。どちらも設定されていない場合、デフォルトは `"dev"` です。 -環境の値はダッシュボードのファーストクラスフィルターとして表示され、高速クエリのためサーバーに保存されます。 +環境の値はダッシュボードのファーストクラスフィルターとして表示され、高速クエリのためにサーバーに保存されます。 -> **警告:** 環境の値にリテラルのカンマ `,` を含めることはできません。ダッシュボードのフィルターはワイヤー上でカンマ区切りのマルチセレクトを使用するため（`?environment=prod,staging`）、`prod,blue` という名前の環境は2つの値に分割されます。カンマを含む環境名のイベントはインジェスト時に拒否されます。 +> **警告:** 環境の値にリテラルのカンマ `,` を含めてはいけません。ダッシュボードのフィルターは通信上でカンマ区切りのマルチセレクトを使用するため（`?environment=prod,staging`）、`prod,blue` という名前の環境は2つの値に分割されます。カンマを含む環境のイベントは取り込み時に拒否されます。 --- ## データとプライバシー -SDKは明示的に渡したフィールドのみを記録します。プロンプト、メッセージ、ツールの入出力、モデルのコンテンツは、`event.*` 呼び出しに渡した場合にのみキャプチャされます。プロセスからの暗黙的な読み取りやキャプチャは一切行いません。未設定のフィールドはイベントから完全に省略され、ディスクに書き込まれません。 +SDKは明示的に渡したフィールドのみを記録します。プロンプト・メッセージ・ツールの入出力・モデルコンテンツは、`event.*` 呼び出しに渡したときのみキャプチャされます。プロセスからの暗黙的な読み取りやキャプチャは一切行いません。設定しなかったフィールドはイベントから完全に省略され、ディスクに書き込まれません。 -そのため、データのマスキングはお客様の判断と責任で行ってください。プロンプトやツールのペイロードに保存したくないPIIや機密情報が含まれている場合は、イベントメソッドに渡す前にそれらを除去またはマスクしてください。 +そのため、データの秘匿化はご自身の判断と責任で行ってください。プロンプトやツールのペイロードに保存したくないPIIや機密情報が含まれている場合は、イベントメソッドに渡す前にマスクまたは除去してください。 --- ## イベントリファレンス -ほとんどのイベントは相関IDを共有する開始/終了ペアで構成されています: `tool_use` と `tool_result` は `tool_call_id` を共有し、`hook_triggered` と `hook_completed` は `hook_id` を共有し、`human_wait` と `human_input` は `input_id` を共有します。開始イベントを発行し、処理を実行してから、同じIDで終了イベントを発行してください。Failproof AI Observabilityがペアを照合し `duration_ms` を自動計算するため、`duration_ms` を自分で渡す必要はありません。 +ほとんどのイベントは、相関IDを共有する開始/終了のペアで構成されています：`tool_use` と `tool_result` は `tool_call_id` を共有し、`hook_triggered` と `hook_completed` は `hook_id` を共有し、`human_wait` と `human_input` は `input_id` を共有します。開始イベントを発行し、処理を実行してから、同じIDで終了イベントを発行してください。Failproof AI Observability がペアを照合し、`duration_ms` を自動計算します。`duration_ms` を手動で渡す必要はありません。 -![セッションのgit形式の実行グラフとイベントタイムライン。ペアイベントから再構築され、ツール・モデル・フックの内訳パネルを表示](/agenteye/images/session-detail.png) +![ペアイベントから再構築された、セッションのgitスタイルの実行グラフとイベントタイムライン。ツール/モデル/フックの内訳パネル付き](/agenteye/images/session-detail.png) -すべてのイベントメソッドに以下の2フィールドが必須です: +すべてのイベントメソッドに必須の2つのフィールドです： | フィールド | 型 | 説明 | |---|---|---| -| `session_id` | `str` | トップレベルのエージェント実行を識別する | -| `agent_id` | `str` | セッション内でイベントを発行したエージェントを識別する | +| `session_id` | `str` | トップレベルのエージェント実行を識別します | +| `agent_id` | `str` | セッション内でイベントを発行したエージェントを識別します | -すべてのメソッドはカスタムメタデータ用の任意の `**kwargs` も受け付けます（[カスタムフィールド](#custom-fields) 参照）。 +すべてのメソッドはカスタムメタデータ用の任意の `**kwargs` も受け付けます（[カスタムフィールド](#custom-fields) を参照）。 --- ### `event.agent_start()` -エージェントが作業を開始したときに発行されます。 +エージェントが処理を開始したときに発行されます。 ```python agenteye.event.agent_start( @@ -185,7 +185,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -エージェントが作業を完了したときに発行されます。 +エージェントが処理を完了したときに発行されます。 ```python agenteye.event.agent_end( @@ -206,8 +206,8 @@ agenteye.event.agent_end( agenteye.event.tool_use( session_id="run-001", agent_id="planner", - tool_name="web_search", # str, 必須 - tool_call_id="toolu_01", # str, 必須 - 対応する tool_result との相関キー + tool_name="web_search", # str、必須 + tool_call_id="toolu_01", # str、必須 - 対応する tool_result との相関キー input={"query": "..."}, # dict | None ) ``` @@ -216,17 +216,17 @@ agenteye.event.tool_use( ### `event.tool_result()` -ツールが返答したときに発行されます。`tool_call_id` を通じて `tool_use` と関連付けられます。 +ツールが結果を返したときに発行されます。`tool_call_id` を通じて `tool_use` と対応付けられます。 ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # 対応する tool_use と一致させる必要があります + tool_call_id="toolu_01", # 対応する tool_use と一致させること output={"results": ["..."]}, # Any | None error=None, # str | None - ツールが例外を発生させた場合に設定 - # duration_ms は自動計算されます - 渡さないでください + # duration_ms は自動計算されます。渡さないでください ) ``` @@ -251,7 +251,7 @@ agenteye.event.model_request( ) ``` -`messages` のエントリはプレーン文字列の `content` でも、Anthropic形式のブロックリストの `content` でも受け付けます。サンプリングパラメータ（`temperature`、`max_tokens` など）は追加のkwargsとして渡せます。 +`messages` のエントリは、プレーン文字列の `content` または Anthropic スタイルのブロックリスト形式の `content` を受け付けます。サンプリングパラメータ（`temperature`、`max_tokens` など）は追加の kwargs として渡せます。 --- @@ -274,20 +274,20 @@ agenteye.event.model_response( ) ``` -`content` はプレーン文字列（汎用プロバイダー）またはAnthropic形式のコンテンツブロックのリストを受け付けます。ツール呼び出しは `{"type": "tool_use", ...}` ブロックとして `content` 内に含まれます。別途 `tool_calls` フィールドはありません。 +`content` はプレーン文字列（汎用プロバイダー向け）または Anthropic スタイルのコンテンツブロックのリストを受け付けます。ツール呼び出しは `{"type": "tool_use", ...}` ブロックとして `content` 内に含まれます。`tool_calls` フィールドは別途存在しません。 --- ### `event.hook_triggered()` -フックが発火したときに発行されます。`hook_completed` とペアにしてください。SDKが `duration_ms` を自動計算します。 +フックが起動したときに発行されます。`hook_completed` とペアにしてください。SDKが `duration_ms` を自動計算します。 ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", - hook_name="pre_tool_use", # str, 必須 - hook_id="hook-abc", # str, 必須 - 相関キー + hook_name="pre_tool_use", # str、必須 + hook_id="hook-abc", # str、必須 - 相関キー trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -297,18 +297,18 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -フックが完了したときに発行されます。`hook_id` を通じて `hook_triggered` と関連付けられます。 +フックが完了したときに発行されます。`hook_id` を通じて `hook_triggered` と対応付けられます。 ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # 対応する hook_triggered と一致させる必要があります + hook_id="hook-abc", # 対応する hook_triggered と一致させること outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms は自動計算されます - 渡さないでください + # duration_ms は自動計算されます。渡さないでください ) ``` @@ -322,71 +322,71 @@ agenteye.event.hook_completed( agenteye.event.error( session_id="run-001", agent_id="planner", - error_type="TimeoutError", # str, 必須 - message="timed out", # str, 必須 + error_type="TimeoutError", # str、必須 + message="timed out", # str、必須 traceback="Traceback...", # str | None ) ``` --- -## ヒューマン・イン・ザ・ループ イベント +## ヒューマン・イン・ザ・ループイベント -ヒューマン・イン・ザ・ループイベントは、エージェントの実行に人間が介入する瞬間（承認待ち、入力提供、一時停止、またはエージェントの停止）を監視するためのものです。これらのイベントにより、人間が応答するまでの時間を計測し（SDKがペアイベントの `duration_ms` を自動計算します）、誰がエージェントを一時停止または中断したかを監査し、ダッシュボードに表示される承認・監視ワークフローを構築できます。 +ヒューマン・イン・ザ・ループイベントは、人間がエージェントの実行に介入する瞬間（承認待ち、入力提供、一時停止、エージェント停止）を監視するための機能です。人間の応答にかかった時間の計測（SDKがペアイベントの `duration_ms` を自動計算）、誰がエージェントを一時停止または中断したかの監査、ダッシュボードに表示される承認・監視ワークフローの構築が可能になります。 ### `event.human_wait()` -エージェントが人間からの入力を待つために実行を一時停止したときに発行されます。`human_input` とペアにしてください。SDKが `duration_ms`（人間が応答するまでの時間）を自動計算します。 +エージェントが実行を一時停止して人間からの入力を待つときに発行されます。`human_input` とペアにしてください。SDKが `duration_ms`（人間が応答するまでの時間）を自動計算します。 ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, 必須 - 対応する human_input との相関キー + input_id="inp-abc", # str、必須 - 対応する human_input との相関キー prompt="Do you approve this action?", # str | None - 人間に表示される質問 options=["approve", "reject", "defer"], # list[str] | None - 人間に提示される選択肢 - reason="approval_required", # str | None - 待機している理由 + reason="approval_required", # str | None - エージェントが待機している理由 ) ``` ### `event.human_input()` -人間が入力を提供してエージェントが再開したときに発行されます。`input_id` を通じて `human_wait` と関連付けられます。`duration_ms` は自動計算されるため、呼び出し元から渡してはいけません。 +人間が入力を提供してエージェントが再開するときに発行されます。`input_id` を通じて `human_wait` と対応付けられます。`duration_ms` は自動計算されるため、呼び出し元から渡さないでください。 ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, 必須 - 対応する human_wait と一致させる必要があります + input_id="inp-abc", # str、必須 - 対応する human_wait と一致させること response="approve", # str | None - 人間の回答（自由テキストまたは選択肢） - # duration_ms は自動計算されます - 渡さないでください + # duration_ms は自動計算されます。渡さないでください ) ``` ### `event.human_pause()` -人間がエージェントを能動的に一時停止したとき（例: ダッシュボードのコントロール経由）に発行されます。エージェントは中断されますが、終了はしません。 +人間がエージェントを能動的に一時停止したとき（ダッシュボードのコントロールなど）に発行されます。エージェントは停止ではなく中断状態になります。 ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - エージェントを一時停止した人 + user_id="usr_42", # str | None - エージェントを一時停止したユーザー ) ``` ### `event.human_interrupt()` -人間がエージェントの実行中に能動的に停止させたときに発行されます。`human_pause` とは異なり、エージェントの作業は中断ではなく終了します。 +人間がエージェントの実行中に能動的に停止したときに発行されます。`human_pause` と異なり、エージェントの処理は中断ではなく終了されます。 ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - エージェントを中断した人 - at_step="tool_use:web_search", # str | None - 停止時にエージェントが実行していた処理 + user_id="usr_42", # str | None - エージェントを中断したユーザー + at_step="tool_use:web_search", # str | None - 停止時にエージェントが行っていた処理 ) ``` @@ -394,7 +394,7 @@ agenteye.event.human_interrupt( ## カスタムフィールド -追加のキーワード引数は、標準フィールドの後にイベントへ付加されます: +追加のキーワード引数は、標準フィールドの後にイベントへ追加されます： ```python agenteye.event.tool_use( @@ -407,15 +407,15 @@ agenteye.event.tool_use( ) ``` -`timestamp`、`type`、`environment` は予約済みであり、カスタムフィールドとして渡すと `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）が発生します。`session_id` と `agent_id` はすべてのイベントメソッドの必須パラメータであり、2回渡すことはできません。その場合、Pythonは `TypeError` を発生させます。環境の設定には `configure(environment=...)` または `AGENTEYE_ENVIRONMENT` 変数を使用してください。 +`timestamp`、`type`、`environment` は予約済みです。カスタムフィールドとして渡すと `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）が発生します。`session_id` と `agent_id` はすべてのイベントメソッドで必須パラメータであり、2度渡すことはできません。渡した場合はPythonが `TypeError` を発生させます。環境の設定は `configure(environment=...)` または `AGENTEYE_ENVIRONMENT` 変数で行ってください。 -ペイロードのフィールドをクエリしたい場合は、構造化JSONで保持してください。JSON がネイティブにサポートしない値（日時、UUID、Decimal、セット、バイト、モデルオブジェクトなど）は文字列に変換されるため、記録は安全に続行されます。 +フィールドを後からクエリしたい場合は、構造化JSON形式でペイロードを保持してください。JSONがネイティブにサポートしない値（datetime、UUID、decimal、セット、bytes、モデルオブジェクトなど）は、安全に記録を継続できるよう文字列に変換されます。 --- ## イベントの書き込み方法 -イベントはプロセス内でバッファリングされ、`flush_interval` 秒ごと（デフォルト500ms）にディスクにフラッシュされます。各フラッシュは1つのJSONLファイルを書き込みます: +イベントはプロセス内にバッファリングされ、`flush_interval` 秒ごと（デフォルト500ミリ秒）にディスクへフラッシュされます。フラッシュごとに1つのJSONLファイルが書き込まれます： ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl @@ -423,11 +423,11 @@ agenteye.event.tool_use( コレクターはこのディレクトリを監視し、ファイルを自動的にアップロードします。これらのファイルを直接管理する必要はありません。 -各ファイルはアトミックに書き込まれます: SDKは一時ファイルに書き込んだ後、所定の場所にリネームするため、コレクターが書きかけのファイルを読み取ることはありません。プロセス終了時にも最終フラッシュが実行されるため、最後のインターバルでバッファリングされたイベントが失われることはありません。コレクターがオフラインの場合、イベントはディスク上にファイルとして蓄積され、コレクターが復帰次第送信されます。 +各ファイルはアトミックに書き込まれます：SDKは一時ファイルに書き込んでからリネームするため、コレクターが途中まで書き込まれたファイルを読むことはありません。プロセス終了時にも最終フラッシュが実行されるため、最後のインターバルでバッファリングされたイベントが失われることはありません。コレクターがオフラインの場合でも、イベントはディスク上にファイルとして蓄積され、コレクターが復帰次第送信されます。 --- ## 次のステップ -- [イベントストリーム](/ja/agenteye/event-stream): これらのイベントがリアルタイムで届く様子を、タイプ別の色分けと環境・エージェント・セッションによるフィルタリングで確認できます。 -- [セッション](/ja/agenteye/sessions): ペアイベントが各エージェント実行を実行グラフとタイムラインとしてどのように再構築するかを確認できます。 \ No newline at end of file +- [イベントストリーム](/ja/agenteye/event-stream)：これらのイベントがリアルタイムで届く様子を、イベントタイプごとの色分けと環境・エージェント・セッションによるフィルタリングで確認できます。 +- [セッション](/ja/agenteye/sessions)：ペアイベントから各エージェント実行が実行グラフとタイムラインとしてどのように再構築されるかを確認できます。 \ No newline at end of file diff --git a/docs/ja/agenteye/queries.mdx b/docs/ja/agenteye/queries.mdx index 37093763..43088432 100644 --- a/docs/ja/agenteye/queries.mdx +++ b/docs/ja/agenteye/queries.mdx @@ -1,56 +1,55 @@ --- title: "クエリ" -description: "エージェントデータに関するあらゆる質問を投げかけ、数秒で答えを得られます。" +description: "エージェントデータに関するあらゆる質問を投げかけ、数秒で回答を得られます。" --- +エージェントデータに関するあらゆる質問を投げかけ、数秒で回答を得られます。Failproof AI Observabilityには、イベントや評価に対してすぐに実行できる保存済みクエリのライブラリが用意されており、空白のSQLエディタからではなく、実際に動くサンプルから始められます。 -エージェントデータに関するあらゆる質問を投げかけ、数秒で答えを得られます。Failproof AI のオブザーバビリティ機能は、イベントや評価に対してすぐに実行できる保存済みクエリのライブラリを提供しているため、空のSQLエディタではなく実際に動くサンプルからスタートできます。 +![保存済みクエリのライブラリ：再利用可能なクエリのグリッド表示。組み込みプリセットとカスタムクエリの両方が含まれる](/agenteye/images/queries.png) -![保存済みクエリライブラリ: 組み込みプリセットとカスタムクエリが並んだグリッド表示](/agenteye/images/queries.png) +*`//queries` にある保存済みクエリのライブラリ：組み込みプリセットとチームが保存したクエリが並んで表示されます。* -*`//queries` の保存済みクエリライブラリ: 組み込みプリセットとチームが保存したクエリが並んで表示されます。* +## 白紙のページではなくプリセットから始める -## 白紙のページではなく、プリセットから始める +テーブル名を覚えたり、SQLをゼロから書いたりする必要はありません。ライブラリには、チームがよく尋ねる質問に対応した組み込みプリセットが最初から用意されており、チームが保存・命名したクエリと並んで表示されます。目的に近いものを選べば、答えまでの道のりの大半はすでに完了しています。 -テーブル名を覚えたり、SQLをゼロから書いたりする必要はありません。ライブラリを開くと、よく聞かれる質問に対応した組み込みプリセットが、チームが保存・命名したクエリの隣にすぐ表示されます。目的に近いものを選べば、答えまでの道のりの大半はすでに終わっています。 - -保存済みクエリはすべてorg単位でスコープされ共有されるため、チームメンバーが書いた便利なクエリはそのままあなたのものにもなります。クエリに名前と説明を一度付けておけば、組織内の誰でも検索・実行でき、後からダッシュボードに結果をピン留めすることもできます。 +保存済みクエリはすべて組織スコープで共有されるため、チームメンバーが作成した便利なクエリはあなたのものにもなります。クエリに名前と説明を一度付けるだけで、組織内の誰でも見つけて実行でき、後でダッシュボードに結果をピン留めすることもできます。 `//queries` からアクセスできます。 ## SQLコンポーザーで調整して実行する -クエリを開くとSQLコンポーザーに読み込まれ、その場で調整して即座に結果を確認できます。エクスポートも往復も、他の誰かを待つ必要もありません。 +クエリを開くとSQLコンポーザーに展開され、そこで調整してすぐに答えを確認できます。エクスポート不要、往復ゼロ、他の誰かを待つ必要もありません。 ![保存済みクエリを実行中のSQLクエリコンポーザー。スキーマサイドバーとライブ結果グリッドが表示されている](/agenteye/images/query-lab.png) -*SQLコンポーザー: 左側にクエリ、列名を調べる手間を省くスキーマサイドバー、そして下部にライブ結果グリッド。* +*SQLコンポーザー：左にクエリ、カラム名を推測しなくて済むスキーマサイドバー、そして下にライブ結果グリッド。* -- **スキーマサイドバー**にはアナリティクステーブルとその列が一覧表示されるため、フィールド名を探し回ることなくクエリを組み立てられます。 -- **ライブ結果グリッド**は実行した瞬間に行を返すため、試行錯誤を繰り返すのではなく数秒で改善できます。 -- **設計上の読み取り専用。** クエリはイベントストアに対して実行され、サーバー側で検証されます。`SELECT` と `WITH` 文のみが許可されており、ステートメントタイムアウトと行数上限が設けられています。探索的なクエリがデータを変更することは一切なく、暴走したクエリは自動的に停止されます。 +- **スキーマサイドバー**にはアナリティクステーブルとそのカラムが一覧表示されるため、フィールド名を探し回ることなくクエリを作成できます。 +- **ライブ結果グリッド**は実行した瞬間に行を返すため、何度も推測し直すのではなく、数秒で反復作業を進められます。 +- **設計上読み取り専用。** クエリはイベントストアに対して実行され、サーバー側で検証されます。`SELECT` と `WITH` ステートメントのみ許可されており、ステートメントタイムアウトと行数上限が設けられています。探索的なクエリがデータを変更することは絶対になく、暴走したクエリは自動的に停止されます。 -結果に満足したら、チーム全体が使えるようにライブラリへ保存するか、出力をダッシュボードにライン・棒グラフ・エリア・円グラフのタイルとしてピン留めしましょう。 +結果に満足したら、チーム全体が使えるようにライブラリに保存するか、出力をダッシュボードに折れ線・棒・面積・円グラフのタイルとしてピン留めできます。 ## ターミナルから実行する、またはアシスタントに書いてもらう -保存済みクエリはどこで作業していても同じものを利用できます: +保存済みクエリは作業場所を問わず利用できます。 -- **ターミナルから。** `agenteye` CLIを使えば、同じ保存済みクエリの一覧表示・実行・保存が可能なため、結果をスクリプトに組み込んだり、CIに連携したり、コーディングエージェントに渡したりできます。 +- **ターミナルから。** `agenteye` CLIで同じ保存済みクエリのリスト表示・実行・保存が可能なため、結果をスクリプトに取り込んだり、CIに組み込んだり、コーディングエージェントに渡したりできます。 ```bash agenteye query list # the same saved queries, from your terminal agenteye query run errs --arg prod # run one and print the rows (add --json to pipe it) ``` - フルコマンドセットは [CLI and agents](/ja/agenteye/cli-and-agents) を参照してください。 + 完全なコマンド一覧については [CLI and agents](/ja/agenteye/cli-and-agents) を参照してください。 -- **AIアシスタントから。** SQLの書き方が分からない場合は、ダッシュボード内の [AIアシスタント](/ja/agenteye/assistant) に平易な言葉で質問するだけで、クエリを下書きしてライブラリに保存してくれます。 +- **AIアシスタントから。** SQLの書き方がわからない場合は、ダッシュボード内の [AIアシスタント](/ja/agenteye/assistant) に平易な言葉で質問するだけで、クエリを作成してライブラリに保存してくれます。 -保存済みクエリの実行は `queries:run` 権限によって管理されており、クエリの作成・削除に必要な権限とは分離されています。そのため、ライブラリの書き換えを許可することなく読み取りアクセスのみを付与できます。 +保存済みクエリの実行は `queries:run` 権限によって制御されており、クエリの作成・削除権限とは分離されています。そのため、ライブラリの書き換えを許可せずに読み取りアクセスだけを付与することができます。 -## 関連情報 +## 関連ページ -- [ダッシュボード](/ja/agenteye/dashboards): クエリ結果をorg全体で共有するグラフにピン留めする。 -- [AIアシスタント](/ja/agenteye/assistant): 平易な言葉で質問し、クエリを取得する。 -- [CLI and agents](/ja/agenteye/cli-and-agents): ターミナルから同じクエリを実行・保存する。 \ No newline at end of file +- [ダッシュボード](/ja/agenteye/dashboards)：クエリ結果を組織全体で共有するチャートにピン留めする。 +- [AIアシスタント](/ja/agenteye/assistant)：平易な言葉で質問してクエリを返してもらう。 +- [CLI and agents](/ja/agenteye/cli-and-agents)：ターミナルから同じクエリを実行・保存する。 \ No newline at end of file diff --git a/docs/ja/agenteye/security.mdx b/docs/ja/agenteye/security.mdx index 3d9eb465..8d3091c5 100644 --- a/docs/ja/agenteye/security.mdx +++ b/docs/ja/agenteye/security.mdx @@ -1,68 +1,68 @@ --- title: "セキュリティ" -description: "Failproof AI Observabilityはプロダクション環境のエージェントの近くに配置されるため、プロンプト、ツールの入力、出力を参照します。" +description: "Failproof AI Observability はプロダクション環境のエージェントのそばに配置されるため、プロンプト、ツールの入力、出力を参照します。" --- -Failproof AI Observabilityはプロダクション環境のエージェントの近くに配置されるため、プロンプト、ツールの入力、出力を参照します。このページでは、データの隔離・制御・管理方法について説明します。セキュリティレビューのためにFailproof AI Observabilityを評価している場合は、まずここをお読みください。 +Failproof AI Observability はプロダクション環境のエージェントのそばに配置されるため、プロンプト、ツールの入力、出力を参照します。このページでは、そのデータがどのように分離・制御され、あなたの手元に留まるかを説明します。セキュリティレビューの目的で Failproof AI Observability を評価している場合は、まずここからお読みください。 --- ## データはあなたの環境に留まる -Failproof AI Observabilityはセルフホスト型です。イベント、プロンプト、モデルのレスポンス、アナリティクスはすべて、あなた自身のデータベースおよび環境に保存されます。サードパーティのSaaSにデータが送信されることはなく、データは常にあなた自身のクラウドアカウント内に留まります。 +Failproof AI Observability はセルフホスト型です。イベント、プロンプト、モデルのレスポンス、アナリティクスはすべて、あなた自身のデータベース・環境に保存されます。サードパーティの SaaS にデータが送信されることはなく、あなた自身のクラウドアカウント内に留まります。 --- ## テナント分離 -1つのFailproof AI Observabilityインスタンスで複数の組織をホストできます。各組織はストレージ層で分離されており、UIではなくデータベース自体によって強制されます。 +1つの Failproof AI Observability インスタンスで複数の組織をホストできますが、各組織はストレージ層で分離されており、UI だけでなくデータベースによって強制されます。 -- 組織の運用データ（ユーザー、APIキー、ダッシュボード、保存済みクエリ）はその組織にスコープされており、組織をまたいだ読み取りはデータベース自体によってブロックされます。 +- 組織の運用データ（ユーザー、キー、ダッシュボード、保存済みクエリ）は該当組織にスコープされており、組織をまたいだ読み取りはデータベース自体によってブロックされます。 - 取り込まれたすべてのイベントには所有組織のスタンプが押されるため、ある組織のイベントを別の組織が読み取ることはできません。 -すべてのダッシュボードルートは組織スラグ（`//…`）の配下にスコープされています。 +すべてのダッシュボードルートは組織スラッグ（`//…`）配下にスコープされています。 --- ## サインイン -Failproof AI Observabilityはパスワードレスのメールベースサインインを採用しています。フィッシングやリークの対象となるパスワードは存在しません。ユーザーがワンタイムコード（またはワンクリックマジックリンク）をリクエストすると、それがメールで送信され、短時間で失効します。サインインは**許可リスト**によって制御されており、あなたが許可したメールアドレス（またはドメイン）のみが認証できます。 +Failproof AI Observability はパスワードレスのメールベース認証を採用しています。フィッシングやリークの対象となるパスワードは存在しません。ユーザーがワンタイムコード（またはワンクリックのマジックリンク）をリクエストすると、メールで送信され、すぐに期限切れになります。サインインは**許可リスト**によってゲートされており、あなたが許可したメールアドレス（またはドメイン）のみが認証できます。 -![Failproof AI Observabilityのサインイン画面。メールアドレスに使い捨てコードを送信します](/agenteye/images/login.png) +![Failproof AI Observability のサインイン画面。メールアドレスに使い切りコードを送信します](/agenteye/images/login.png) --- -## APIキーによるスコープ付きアクセス +## API キーによるスコープ付きアクセス -すべてのクライアントは、きめ細かな最小権限を持つAPIキーで認証します。コレクターには`events:add`のみが必要です。ダッシュボードやアシスタント用のキーは読み取り専用にできます。破壊的な操作（削除、再生成）は、明示的に付与を選択する別個の権限です。 +すべてのクライアントは、きめ細かな最小権限パーミッションを持つ API キーで認証されます。コレクターには `events:add` のみが必要です。ダッシュボードやアシスタント用のキーは読み取り専用にできます。破壊的な操作（削除、再生成）は個別の権限として、必要に応じて付与します。 -![APIキーページ：各キーの権限付与が読み取り・書き込み・破壊的スコープごとに色分けされています](/agenteye/images/api-keys.png) +![API キーページ：各キーのパーミッション付与が、読み取り・書き込み・破壊的スコープごとに色分けされています](/agenteye/images/api-keys.png) -管理者のブートストラップキーはセットアップ用に保持し、その他の用途には権限を絞ったキーを発行してください。詳しくは[APIキー](/ja/agenteye/api-keys)をご覧ください。 +管理者用ブートストラップキーはセットアップ用に保管し、その他の用途には最小限のキーを発行してください。詳細は [API keys](/ja/agenteye/api-keys) を参照してください。 --- ## 読み取り専用・承認ゲート付きアシスタント -ダッシュボード内の[AIアシスタント](/ja/agenteye/assistant)はデータに関する質問に回答しますが、設計上の制約があります。 +ダッシュボード内の [AI アシスタント](/ja/agenteye/assistant) はあなたのデータに対して質問に答えますが、設計上以下の制約があります。 -- **デフォルトで読み取り専用**：実行されるSQLはガードを通過し、`SELECT`/`WITH`クエリのみ、単一ステートメント、行数上限付きで許可されます。 -- アシスタントが作成するもの（保存済みクエリ、ダッシュボードなど）はすべて**承認ゲート付き**：書き込みが行われる前に、あなたがすべての内容を確認・承認します。 +- **デフォルトで読み取り専用**：実行する SQL は `SELECT`/`WITH` クエリのみ許可するガードを通過し、単一ステートメント・行数上限が設定されています。 +- アシスタントが作成するもの（保存済みクエリ、ダッシュボードなど）はすべて**承認ゲート付き**：書き込みが発生する前に、あなたが内容を確認・承認します。 - アシスタントは**削除を行うことができません**。 -そのため、チームメンバーが「今週最もエラーが多かったエージェントはどれか？」と質問して結果を活用できる一方、アシスタントが自律的にデータを変更・削除することはありません。 +チームメンバーが「今週エラーが最も多かったエージェントはどれか？」と質問して結果に基づいて行動できる一方、アシスタントが独自にデータを変更・削除することはありません。 --- -## 転送中のセキュリティ +## 転送中のデータ -すべてのトラフィックはHTTPSで通信されます。TLSはあなた自身の証明書で終端するため、コレクターからサーバーへの通信、およびブラウザからサーバーへの通信は転送中に暗号化されます。 +すべてのトラフィックは HTTPS で通信されます。TLS はあなた自身の証明書で終端するため、コレクターとサーバー間、ブラウザとサーバー間のトラフィックは転送中に暗号化されます。 --- ## 次のステップ -- [概要](/ja/agenteye/overview)：Failproof AI Observabilityの全体像 -- [APIキー](/ja/agenteye/api-keys)：コレクター、ダッシュボード、アシスタントへのアクセスのスコープ設定 -- [オブザーバビリティ](/ja/agenteye/observability)：Failproof AI Observabilityがエージェントから収集する情報 \ No newline at end of file +- [Overview](/ja/agenteye/overview)：Failproof AI Observability の全体像 +- [API keys](/ja/agenteye/api-keys)：コレクター、ダッシュボード、アシスタントのアクセスをスコープする +- [Observability](/ja/agenteye/observability)：Failproof AI Observability がエージェントから収集する情報 \ No newline at end of file diff --git a/docs/ja/agenteye/sessions.mdx b/docs/ja/agenteye/sessions.mdx index 1a9ac69f..d050c549 100644 --- a/docs/ja/agenteye/sessions.mdx +++ b/docs/ja/agenteye/sessions.mdx @@ -1,57 +1,57 @@ --- title: "セッションと実行グラフ" -description: "1回の実行で発生したすべてのイベントを1行にまとめ、git スタイルの実行グラフとして数秒で把握できるように可視化します。" +description: "1回の実行で発生したすべてのイベントを1行にまとめ、git スタイルの実行グラフとして数秒で把握できるよう可視化します。" --- -実行が失敗した原因を推測するのはもう終わりです。Failproof AI Observability は、1回の実行で発生したすべてのイベントを読みやすい1行にまとめ、実行全体を git スタイルの図として数秒で把握できるように描画します。エージェントが何をどの順番で行ったか、ステップごとに正確に確認できます。 +実行が失敗した原因を推測するのはもう終わりです。Failproof AI Observability は、1回の実行で発生したすべてのイベントを読みやすい1行にまとめ、実行全体を git スタイルの図として数秒で把握できるように描画します。エージェントが何をしたのか、ステップごとに正確に確認できます。 -![セッション一覧：環境やエージェントをまたいで1実行1行で表示され、ステータスのバッジと評価スコアのバッジが付く](/agenteye/images/sessions-list.png) +![セッション一覧：環境・エージェントをまたいで実行ごとに1行表示され、ステータスのピルと評価スコアのバッジが付いている](/agenteye/images/sessions-list.png) -*1実行1行：ステータスのバッジで実行の結果が一目でわかり、評価器を接続するとスコアバッジも表示されます。* +*実行ごとに1行：ステータスのピルで実行結果が一目でわかり、評価器を接続するとスコアバッジも表示されます。*
-*エージェントのトレーシング：ゴールからツール、最終的な回答まで、1回の実行をステップごとに追跡します。* +*エージェントトレーシング：ゴールからツール、最終的な回答まで、1回の実行をステップごとに追跡します。* --- ## すべての実行を一目で把握する -生のイベント履歴はすべてのステップの真実を記録していますが、数十の実行にわたって何千ものステップがある場合は、個々のステップではなく実行単位での把握が必要です。セッションページは、1回の実行のすべてのイベントを1行にまとめます。これにより、1日分のアクティビティが大量のログではなくスキャンしやすいリストとして表示されます。 +生のイベントトレイルはすべてのステップの真実を記録していますが、数十回の実行にまたがる何千ものステップがある場合、必要なのはステップではなく実行全体です。セッションページは、1回の実行のすべてのイベントを1行にまとめます。これにより、1日分のアクティビティが大量のデータではなく、スキャンしやすいリストになります。 -各行にはステータスのバッジが付いており、クリックする前から失敗した実行と正常な実行を区別できます。日付範囲・環境・エージェント・セッションでフィルタリングすることで、「すべての実行」から「確認したい実行」へ数クリックで絞り込めます。 +各行にはステータスのピルが表示されるため、クリックする前に失敗した実行と正常な実行を区別できます。日付範囲、環境、エージェント、またはセッションでフィルタリングすることで、「すべての実行」から「確認したい実行」へ数クリックで絞り込めます。 -評価器を接続すると、完了したすべての実行が自動的にスコアリングされ、最新のスコアがバッジとして行に表示されます。スコアの範囲でフィルタリングできるため、「今週の本番環境で低スコアのすべての実行を表示」はフィルター操作で完結し、手動レビューは不要です。評価器を設定する前でも、セッションは実行の完全な記録を保持します。スコアバッジが付かないだけです。 +評価器を接続すると、完了した実行は自動的にスコア付けされ、最新のスコアがバッジとして行に表示されます。任意のスコア範囲でフィルタリングできるため、「今週の低スコアの本番実行をすべて表示する」はフィルター操作で済み、手動でのレビューは不要です。評価器を設定するまでは、セッションには完全な実行内容が記録されますが、スコアは付きません。 --- ## 実行全体を図として読む -![セッションの git スタイルの実行グラフとイベントタイムラインが並び、右側にはツール・モデル・フックの内訳パネルが表示される](/agenteye/images/session-detail.png) +![セッションの git スタイル実行グラフとイベントタイムラインが並び、右側にツール・モデル・フックの内訳パネルが表示されている](/agenteye/images/session-detail.png) -*実行グラフ（左）はイベントタイムラインの隣に表示され、右側のパネルには実行で使用されたツール・モデル・フックおよびトークン消費量の内訳が表示されます。* +*実行グラフ（左）がイベントタイムラインの隣に表示され、右のレールには実行ごとのツール、モデル、フック、トークン消費の内訳が表示されます。* -セッションをクリックすると実行グラフが開きます。エージェント・ツール・フック・モデル呼び出しが時系列でどのように展開されたかを git スタイルで可視化したものです。並列サブエージェントはそれぞれ独自のレーンに分岐するため、どの処理が並行して実行されたか、どのサブエージェントが停止したか、実行がどこで問題に陥ったかを、大量のログを頭の中で追うことなく把握できます。 +任意のセッションをクリックすると実行グラフが開きます。これは、エージェント、ツール、フック、モデル呼び出しが時系列でどのように展開されたかを示す git スタイルのビューです。並列サブエージェントはそれぞれ独自のレーンに分岐して表示されるため、どの処理が並行して実行されたか、どのサブエージェントが停滞したか、実行がどこで意図から外れたかを、大量のログを頭の中で再現することなく把握できます。 -右側のパネルでは実行単位の内訳を確認できます。使用されたツールとモデル、発火したフック、トークン消費量が表示されます。「この実行のコストはなぜこんなに高いのか」「遅いツールはどれか」という疑問への答えが、その原因となったグラフのすぐ隣に置かれています。 +右のレールには実行ごとの内訳が表示されます：実行されたツールとモデル、起動したフック、実行に消費したトークン数。これにより「なぜこの実行はコストがかかったのか」や「どのツールが遅いのか」という疑問に、原因となったグラフのすぐ隣で答えが得られます。 -個々のイベントはアドレス指定が可能なため、「セッションの3分の2くらいのところ」という曖昧な説明ではなく、特定の瞬間へのリンクを共有できます。任意のイベントからリンクをコピーするか、[監査](/ja/agenteye/audits)の検出結果やエラーのリンクをたどると、そのイベントが選択・スクロールされた状態でセッションが開きます。非常に長い実行でも同様に機能します。タイムラインはブラウザへの負荷を考慮して一定範囲のウィンドウを読み込みますが、そのウィンドウ外を指すリンクでも、先頭に戻されることなく対象のイベントを見つけます。イベントが保持期間を過ぎている場合は、何も選択されないまま終わるのではなく、その旨がページに表示されます。 +個々のイベントはアドレス指定可能なので、「セッションの下から3分の2あたり」といった曖昧な説明ではなく、特定の瞬間へのリンクを共有できます。任意のイベントからリンクをコピーするか、[監査](/ja/agenteye/audits)の検出結果やエラーからリンクをたどると、そのイベントが選択されスクロールされた状態でセッションが開きます。非常に長い実行でも同様です：タイムラインはブラウザの負荷を考慮して一定範囲のウィンドウを読み込みますが、そのウィンドウの外を指すリンクでも、先頭に戻されることなく対象のイベントを見つけます。イベントが保持期間を過ぎていた場合は、何も選択されないまま静かに終わるのではなく、その旨がページに表示されます。 --- -## 見つけ方 +## 場所の確認 -すべてのダッシュボードページは組織単位 (`//…`) でスコープされています。セッションは左サイドバーの **Observe** にあり、Events の隣に配置されています。リストの上部には日付範囲・環境・エージェント・セッションのフィルターが並んでいます。各行を1クリックで完全な実行グラフにアクセスできます。 +すべてのダッシュボードページは組織にスコープされています（`//…`）。セッションは左サイドバーの **Observe** の下、イベントの隣にあります。リスト上部には日付範囲、環境、エージェント、セッションのフィルターが並んでいます。各行から1クリックで完全な実行グラフに移動できます。 -スコアバッジとスコア範囲によるフィルタリングを有効にするには、評価器を接続してください。詳細は [評価](/ja/agenteye/evaluations) を参照してください。 +スコアバッジとスコア範囲フィルタリングを有効にするには、評価器を接続してください：[評価](/ja/agenteye/evaluations)を参照。 --- -## 関連情報 +## 関連ページ -- [イベントストリーム](/ja/agenteye/event-stream)：各セッションの元となる、ステップごとの生の履歴。 +- [イベントストリーム](/ja/agenteye/event-stream)：各セッションのもととなる、ステップごとの生のトレイル。 - [評価](/ja/agenteye/evaluations)：評価器を接続して、各実行にフィルタリング可能なスコアバッジを付与する。 -- [テレメトリ](/ja/agenteye/telemetry)：エージェントの実行がこれらのセッションに取り込まれるまでの仕組み。 \ No newline at end of file +- [テレメトリ](/ja/agenteye/telemetry)：エージェントからこれらのセッションに実行データが送られる仕組み。 \ No newline at end of file diff --git a/docs/ja/agenteye/telemetry.mdx b/docs/ja/agenteye/telemetry.mdx index 20ac7d29..55f252f4 100644 --- a/docs/ja/agenteye/telemetry.mdx +++ b/docs/ja/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- title: "パフォーマンス指標" -description: "モデル、ツール、またはhookが遅くなったりコストが膨らんだ瞬間を即座に把握し、ユーザーが気づく前にテールレイテンシのスパイクを検出できます。" +description: "モデル、ツール、またはフックが遅延したりコストが跳ね上がった瞬間を即座に把握し、ユーザーが気づく前にテールレイテンシのスパイクを検知します。" --- -モデル、ツール、またはhookが遅くなったりコストが膨らんだ瞬間を即座に把握し、ユーザーが気づく前にテールレイテンシのスパイクを検出できます。3つの専用ページが生のタイミングデータをp50、p95、p99に変換し、一目で読み取ることができます。 +モデル、ツール、またはフックが遅延したりコストが跳ね上がった瞬間を即座に把握し、ユーザーが気づく前にテールレイテンシのスパイクを検知します。3つの専用ページが生の計測値をp50、p95、p99に変換し、一目で読み取れるようにします。 -![レイテンシヒートマップ、パーセンタイルバンド、モデルごとのトークン数・コスト・コンテキストウィンドウ使用率を表示するModelsページ](/agenteye/images/models.png) -*Modelsページ：レイテンシヒートマップ、パーセンタイルバンド、モデルごとのトークン数・推定コスト・コンテキストウィンドウ使用率。* +![Models ページにレイテンシヒートマップ、パーセンタイルバンド、モデルごとのトークン数・コスト・コンテキストウィンドウの使用率が表示されている](/agenteye/images/models.png) +*Models ページ：レイテンシヒートマップ、パーセンタイルバンド、モデルごとのトークン数、推定コスト、コンテキストウィンドウの充填率。* -## 平均値に最悪の実行を隠させない +## 平均値が最悪の結果を隠すのを防ぐ -平均レイテンシという数値は安心感を与えますが、実際には役に立ちません。50回に1回起きる、深夜2時にオンコール担当を呼び出すような停滞した呼び出しを、平均値は丸めて隠してしまうからです。Models、Tools、Hooksの各ページはそれをしません。どのページも同じ構成を持つので、一度覚えればすべてに応用できます。 +平均レイテンシという数値は安心感を与えますが、実際には役に立ちません。50回に1回の割合で発生し、深夜2時にオンコール担当者を叩き起こすようなストール呼び出しを、平均値は綺麗に覆い隠してしまうからです。Models、Tools、Hooks の各ページはそれを許しません。すべて同じ構造を持っているので、一度覚えれば使いこなせます。 -- **24ビンのスパークライン**でトレンドを一目確認：状況は悪化しているか？ -- p50、p95、p99レイテンシを並べた**バイタルストリップ**で、典型的な実行とテールを並べて比較。 -- 横軸に24タイムビン、縦軸にレイテンシバケットを取った**レイテンシヒートマップ**で、遅い呼び出しが*いつ*集中したかを可視化。 -- p50ラインにp25〜p75とp10〜p90のシェーディングリボン、p99ドットを重ねた**パーセンタイルバンド**で、ばらつきを平均化せず見え続けるように表示。 +- **24ビンのスパークライン**でトレンドを一目把握：状況は悪化しているか？ +- p50、p95、p99のレイテンシを示す**バイタルストリップ**で、典型的な実行結果とテールが並んで表示される。 +- **レイテンシヒートマップ**（24の時間ビン × レイテンシバケット）で、遅い呼び出しが*いつ*集中したかを可視化。 +- **パーセンタイルバンド**：p50のラインにp25〜p75とp10〜p90のシェーディングリボン、そしてp99のドットが重なり、ばらつきが平均化されずに見えるようになっている。 -共有ホバークロスヘアがヒートマップとバンドを連動させるため、テールスパイクが一本の平均線の陰に隠れることなく、両方で同じ時刻に揃って表示されます。3つのページはすべてダッシュボードの **observe** セクションにあり、組織スコープで日付範囲・環境・エージェント・セッションによるフィルタリングが可能です。 +ヒートマップとバンドは共有ホバークロスヘアで連動しているため、テールスパイクが1本の平均線の陰に隠れることなく、両方で時間軸上の同じ位置に表示されます。3つのページはすべてダッシュボードの **observe** セクションにあり、組織ごとにスコープが設定されており、日付範囲、環境、エージェント、セッションでフィルタリングできます。 ## Models：各モデルのコストを正確に把握する -Modelsページ（上図）は、請求書が常に提起する2つの問いに答えます：どのモデルで、いくらか。共有レイテンシビューに加えて、**モデルごとのトークン消費量**、**推定コスト**、**コンテキストウィンドウ使用率**が追加されるため、プロンプトの急激な肥大化や差し迫ったコンパクションを驚かされる前に把握できます。 +Models ページ（上記参照）は、請求書を見たときに必ず生じる2つの疑問に答えます。どのモデルが、どれだけのコストを生んでいるか。共有レイテンシビューに加え、**モデルごとのトークン消費量**、**推定コスト**、**コンテキストウィンドウの充填率**が表示されるため、プロンプトの肥大化や差し迫ったコンパクションが、驚かされる前に可視化されます。 -Failproof AI Observabilityは一般的なモデルIDを自動的に認識します。ウィンドウサイズが正しくない場合や独自のプライベートモデルを使用している場合は、**Settings** の **model context windows** で修正または追加してください。使用率の表示もそれに従って更新されます。 +Failproof AI Observability は一般的なモデルIDを自動的に認識します。ウィンドウサイズが正しくない場合や、独自のプライベートモデルを使用している場合は、**Settings** の **model context windows** で修正または追加してください。充填率の表示もそれに追随します。 ## Tools：遅いものと壊れているものを見分ける -ツール呼び出しは遅いこともあれば、静かに失敗していることもあります。どちらなのかを、ログを掘り返してからではなく、数秒で知る必要があります。 +ツール呼び出しは単に遅い場合もあれば、気づかないうちに失敗し続けている場合もあります。どちらなのかを、ログを掘り返すことなく数秒で判断できることが重要です。 -![共有レイテンシヒートマップとパーセンタイルバンドの横に成功・失敗の内訳とツール分布バーを表示するToolsページ](/agenteye/images/tools.png) -*Toolsページ：同じヒートマップとパーセンタイルバンド、さらに成功・失敗の内訳とツール分布バー。* +![Tools ページに共有のレイテンシヒートマップとパーセンタイルバンド、成功・失敗の内訳、ツール分布バーが表示されている](/agenteye/images/tools.png) +*Tools ページ：同じヒートマップとパーセンタイルバンドに加え、成功・失敗の内訳とツール分布バー。* -共有レイテンシビューに加えて、Toolsページには**成功・失敗の内訳**と**ツール分布バー**が追加されます。これにより、最も頻繁に使われているツールと、エラーバジェットを消費しているツールが一目でわかります。 +共有レイテンシビューに加え、Tools ページには**成功・失敗の内訳**と**ツール分布バー**が追加されており、どのツールを最も多く利用しているか、そしてどのツールがエラーバジェットを消耗しているかが一目でわかります。 -## Hooks：問題のあるhookとトリガーをピンポイントで特定する +## Hooks：問題のあるフックとトリガーをピンポイントで特定する -ライフサイクルhookが実行を遅らせているとき、「hookが遅い」というだけでは対処できません。Hooksページは問題のある一つにたどり着く手助けをします。 +ライフサイクルフックが実行を遅らせているとき、「フックが遅い」という情報だけでは対処できません。Hooks ページは問題の原因となっているフックを一つに絞り込みます。 -![共有ヒートマップとパーセンタイルバンドの上にhook名とトリガーイベントごとにレイテンシを分解表示するHooksページ](/agenteye/images/hooks.png) -*Hooksページ：hook名とトリガーイベントごとに分解されたレイテンシ。* +![Hooks ページに共有のヒートマップとパーセンタイルバンドの上にフック名とトリガーイベント別のレイテンシが表示されている](/agenteye/images/hooks.png) +*Hooks ページ：フック名とトリガーイベント別に分類されたレイテンシ。* -同じレイテンシヒートマップとパーセンタイルバンドの上で、Hooksページは**hook名**と**トリガーイベント**ごとにアクティビティを分解します。これにより、注意が必要な単一のhookと単一のイベントに直接たどり着けます。 +同じレイテンシヒートマップとパーセンタイルバンドの上に、Hooks ページはアクティビティを**フック名**と**トリガーイベント**別に分解して表示するため、注意が必要な単一のフックと単一のイベントにすぐたどり着けます。 ## 関連項目 -- [イベントストリーム](/ja/agenteye/event-stream)：すべてのイベントのリアルタイム・カラーコード付きトレイル。 +- [イベントストリーム](/ja/agenteye/event-stream)：すべてのイベントのライブカラーコードトレイル。 - [セッション](/ja/agenteye/sessions)：イベントを実行ごとに1行にまとめ、実行グラフを開く。 -- [エラートラッキング](/ja/agenteye/error-tracking)：ダッシュボードが赤く表示するすべての問題を一元的にトリアージするサーフェス。 +- [エラートラッキング](/ja/agenteye/error-tracking)：ダッシュボードが赤く表示するすべての問題に対応するトリアージサーフェス。 - [ダッシュボード](/ja/agenteye/dashboards)：フリート全体のロールアップビュー。 \ No newline at end of file diff --git a/docs/ja/architecture.mdx b/docs/ja/architecture.mdx index c7ff79df..6297d6c8 100644 --- a/docs/ja/architecture.mdx +++ b/docs/ja/architecture.mdx @@ -1,27 +1,27 @@ --- title: アーキテクチャ -description: "フックハンドラー、設定読み込み、ポリシー評価の内部動作" +description: "フックハンドラー、設定の読み込み、ポリシー評価の内部動作について" icon: sitemap --- -このドキュメントでは、failproofai の内部動作について説明します。フックシステムがエージェントのツール呼び出しをどのようにインターセプトするか、設定がどのように読み込まれマージされるか、ポリシーがどのように評価されるか、そしてダッシュボードがエージェントのアクティビティをどのように監視するかについて解説します。 +このドキュメントでは、failproofai の内部動作を説明します。フックシステムがエージェントのツール呼び出しをどのようにインターセプトするか、設定がどのように読み込まれてマージされるか、ポリシーがどのように評価されるか、そしてダッシュボードがエージェントのアクティビティをどのように監視するかについて解説します。 --- ## 概要 -failproofai は独立した 2 つのサブシステムで構成されています。 +failproofai には独立した2つのサブシステムがあります。 -1. **フックハンドラー** - Claude Code がすべてのエージェントツール呼び出しに対して起動する高速な CLI サブプロセスです。ポリシーを評価して判定結果を返します。 -2. **エージェントモニター（ダッシュボード）** - エージェントセッションの監視とポリシー管理のための Next.js Web アプリケーションです。 +1. **フックハンドラー** — Claude Code がエージェントのツール呼び出しごとに起動する高速な CLI サブプロセス。ポリシーを評価して決定を返します。 +2. **エージェントモニター（ダッシュボード）** — エージェントセッションの監視とポリシー管理のための Next.js ウェブアプリケーション。 -両サブシステムは `~/.failproofai/` およびプロジェクトの `.failproofai/` ディレクトリにある設定ファイルを共有しますが、それぞれ別プロセスとして動作し、ファイルシステムを通じてのみ通信します。 +両方のサブシステムは `~/.failproofai/` およびプロジェクトの `.failproofai/` ディレクトリにある設定ファイルを共有していますが、別々のプロセスとして実行され、ファイルシステムを通じてのみ通信します。 --- ## フックハンドラー -### Claude Code との連携 +### Claude Code との統合 `failproofai policies --install` を実行すると、`~/.claude/settings.json` に次のようなエントリが書き込まれます。 @@ -44,9 +44,9 @@ failproofai は独立した 2 つのサブシステムで構成されていま } ``` -Claude Code は各ツール呼び出しの前に `failproofai --hook PreToolUse` をサブプロセスとして起動し、JSON ペイロードを stdin 経由で渡します。 +Claude Code は各ツール呼び出しの前に `failproofai --hook PreToolUse` をサブプロセスとして起動し、stdin に JSON ペイロードを渡します。 -### ペイロード形式 +### ペイロードの形式 ```json { @@ -62,9 +62,9 @@ Claude Code は各ツール呼び出しの前に `failproofai --hook PreToolUse` `PostToolUse` イベントの場合、ペイロードにはツールの出力を含む `tool_result` も含まれます。 -ハンドラーは stdin の上限を 1 MB に制限しています。この上限を超えるペイロードは破棄され、すべてのポリシーは暗黙的に allow となります。 +ハンドラーは stdin の上限を 1 MB に制限しています。この制限を超えるペイロードは破棄され、すべてのポリシーが暗黙的に allow となります。 -### レスポンス形式 +### レスポンスの形式 **Deny（PreToolUse）:** ```json @@ -104,19 +104,19 @@ Claude Code は各ツール呼び出しの前に `failproofai --hook PreToolUse` **メッセージ付き Allow:** -`allow(message)` を使うと、操作が許可された場合でもポリシーから Claude に情報コンテキストを送り返せます。フックハンドラーは次の JSON を **stdout** に書き込みます（設定ファイルではなく、上記の deny・instruct レスポンスと同様に、Claude Code へのハンドラーのレスポンスです）。 +`allow(message)` を使用すると、操作が許可されている場合でも、ポリシーが情報コンテキストを Claude に送り返すことができます。フックハンドラーは以下の JSON を **stdout** に書き込みます（設定ファイルではありません — これは上記の deny や instruct レスポンスと同様に、フックハンドラープロセスが Claude Code に返すレスポンスです）。 ```json -// フックハンドラープロセスが stdout に書き込む内容 +// フックハンドラープロセスによって stdout に書き込まれます { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." } } ``` -- 終了コード: `0`（操作は許可される） +- 終了コード: `0`（操作は許可されます） - 複数のポリシーがメッセージ付きの `allow` を返した場合、それらのメッセージは改行で結合されて単一の `additionalContext` 文字列になります -- ポリシーがメッセージを返さない場合、stdout は空になります（従来と同様） +- どのポリシーもメッセージを提供しない場合、stdout は空になります（従来と同じ） ### 処理パイプライン @@ -126,26 +126,26 @@ Claude Code は各ツール呼び出しの前に `failproofai --hook PreToolUse` stdin JSON → ペイロードのパース（最大 1 MB） → セッションメタデータの抽出（session_id、cwd、tool_name、tool_input など） - → readMergedHooksConfig(cwd) ← プロジェクト・ローカル・グローバル設定をマージ - → 有効な組み込みポリシーを解決済みパラメーターで登録 + → readMergedHooksConfig(cwd) ← プロジェクト + ローカル + グローバル設定をマージ + → 解決済みパラメーターで有効な組み込みポリシーを登録 → customPoliciesPath からカスタムポリシーを読み込み（設定されている場合） → カスタムポリシーをポリシーレジストリに登録 - → すべてのポリシーを評価（組み込みが先、次にカスタム） - → 最初の deny で短絡評価 - → instruct の判定を蓄積 - → allow のメッセージを蓄積 - → JSON 判定結果を stdout に書き込み - → イベントを ~/.failproofai/hook-activity/current.jsonl に永続化 + → すべてのポリシーを評価（組み込みを先に、次にカスタム） + → 最初の deny で即時短絡 + → instruct の決定は蓄積 + → allow メッセージは蓄積 + → JSON の決定を stdout に書き込み + → イベントを ~/.failproofai/hook-activity/current.jsonl に保存 → 終了 ``` -LLM 呼び出しなしで、一般的なペイロードに対して全体が 100ms 未満で完了します。 +プロセス全体は、LLM 呼び出しなしで一般的なペイロードに対して 100ms 以内で完了します。 --- ## 設定の読み込み -`src/hooks/hooks-config.ts` が 3 スコープの設定読み込みを実装しています。 +`src/hooks/hooks-config.ts` が3スコープの設定読み込みを実装しています。 ```text [1] {cwd}/.failproofai/policies-config.json ← プロジェクト（最高優先度） @@ -153,13 +153,13 @@ LLM 呼び出しなしで、一般的なペイロードに対して全体が 100 [3] ~/.failproofai/policies-config.json ← グローバル（最低優先度） ``` -マージのロジック: -- `enabledPolicies` - 3 つのファイルにわたって重複排除したユニオン -- `policyParams` - ポリシーごとのキーで、最初に定義したファイルが全体として優先 -- `customPoliciesPath` - 最初に定義したファイルが優先 -- `llm` - 最初に定義したファイルが優先 +マージロジック: +- `enabledPolicies` — 3つのファイル全体で重複を除いた和集合 +- `policyParams` — ポリシーごとのキーで、最初に定義したファイルが全体に優先 +- `customPoliciesPath` — 最初に定義したファイルが優先 +- `llm` — 最初に定義したファイルが優先 -Web ダッシュボードはプロジェクトの cwd なしで起動されるため、読み書きに `readHooksConfig()`（グローバルのみ）を使用します。 +ウェブダッシュボードはプロジェクトの cwd を指定して呼び出されないため、読み取りと書き込みに `readHooksConfig()`（グローバルのみ）を使用します。 --- @@ -169,24 +169,24 @@ Web ダッシュボードはプロジェクトの cwd なしで起動される 各ポリシーに対して: -1. ポリシーの `params` スキーマを参照します（存在する場合）。 -2. マージ済み設定から `policyParams[policy.name]` を読み取ります。 -3. ユーザー指定の値をスキーマのデフォルト値に上書きして `ctx.params` を生成します。 -4. 解決済みコンテキストで `policy.fn(ctx)` を呼び出します。 -5. 結果が `deny` の場合、即座に停止してその判定を返します。 -6. 結果が `instruct` の場合、メッセージを蓄積して処理を継続します。 -7. 結果が `allow` の場合、次のポリシーに進みます。 +1. ポリシーの `params` スキーマを検索します（存在する場合）。 +2. マージされた設定から `policyParams[policy.name]` を読み取ります。 +3. ユーザー指定の値をスキーマのデフォルト値にマージして `ctx.params` を生成します。 +4. 解決されたコンテキストで `policy.fn(ctx)` を呼び出します。 +5. 結果が `deny` であれば即座に停止し、その決定を返します。 +6. 結果が `instruct` であれば、メッセージを蓄積して続行します。 +7. 結果が `allow` であれば、次のポリシーに進みます。 すべてのポリシーが実行された後: -- `deny` が返された場合、deny レスポンスを出力します。 -- `instruct` の結果が収集された場合、すべてのメッセージを結合した単一の instruct レスポンスを出力します。 -- それ以外の場合、allow レスポンスを出力します（stdout は空、終了コードは 0）。 +- `deny` が返された場合は deny レスポンスを出力します。 +- `instruct` の返答が収集された場合は、すべてのメッセージを結合した単一の instruct レスポンスを出力します。 +- それ以外の場合は allow レスポンスを出力します（stdout は空、終了コード 0）。 --- ## 組み込みポリシー -`src/hooks/builtin-policies.ts` は 39 個の組み込みポリシーを `BuiltinPolicyDefinition` オブジェクトとして定義しています。 +`src/hooks/builtin-policies.ts` が39個の組み込みポリシーを `BuiltinPolicyDefinition` オブジェクトとして定義しています。 ```typescript interface BuiltinPolicyDefinition { @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -`params` を受け取るポリシーは、各パラメーターの型とデフォルト値を持つ `PolicyParamsSchema` を宣言します。ポリシーエバリュエーターは `fn` を呼び出す前に解決済みの値を `ctx.params` に注入します。デフォルト値は常に先に適用されるため、ポリシー関数は null チェックなしで `ctx.params` を読み取れます。 +`params` を受け付けるポリシーは、各パラメーターの型とデフォルト値を含む `PolicyParamsSchema` を宣言します。ポリシーエバリュエーターは `fn` を呼び出す前に、解決済みの値を `ctx.params` に注入します。デフォルト値は常に最初に適用されるため、ポリシー関数は null チェックなしで `ctx.params` を読み取ることができます。 -ポリシー内のパターンマッチングは、生の文字列マッチングではなくパース済みのコマンドトークン（argv）を使用します。これにより、シェル演算子のインジェクションによるバイパスを防ぎます（例: `sudo systemctl status *` というパターンは、コマンドに `; rm -rf /` を追記しても回避できません）。 +ポリシー内部のパターンマッチングは、生の文字列マッチングではなく、パースされたコマンドトークン（argv）を使用します。これにより、シェル演算子インジェクションによるバイパスを防止します（例：`sudo systemctl status *` のパターンは、コマンドに `; rm -rf /` を追加してもバイパスできません）。 --- ## カスタムポリシー -`src/hooks/custom-hooks-registry.ts` は `globalThis` ベースのレジストリを実装しています。 +`src/hooks/custom-hooks-registry.ts` が `globalThis` ベースのレジストリを実装しています。 ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // テストで使用 ``` -`src/hooks/custom-hooks-loader.ts` はユーザーのポリシーファイルを読み込みます。 +`src/hooks/custom-hooks-loader.ts` がユーザーのポリシーファイルを読み込みます。 -1. 設定から `customPoliciesPath` を読み取り、存在しない場合はスキップします。 -2. 絶対パスに解決してファイルの存在を確認します。 -3. `from "failproofai"` のすべてのインポートを実際の dist パスに書き換え、`customPolicies` が同じ `globalThis` レジストリを参照するようにします。 -4. ESM 互換性を確保するため、推移的なローカルインポートを再帰的に書き換えます。 -5. 一時的な `.mjs` ファイルを書き出し、エントリファイルを `import()` します。 +1. 設定から `customPoliciesPath` を読み取ります。存在しない場合はスキップします。 +2. 絶対パスに解決し、ファイルの存在を確認します。 +3. `from "failproofai"` のすべてのインポートを実際の dist パスに書き換え、`customPolicies` が同じ `globalThis` レジストリに解決されるようにします。 +4. ESM との互換性を確保するため、推移的なローカルインポートを再帰的に書き換えます。 +5. 一時的な `.mjs` ファイルを書き込み、エントリファイルを `import()` します。 6. `getCustomHooks()` を呼び出して登録済みフックを取得します。 -7. `finally` ブロックですべての一時ファイルを削除します。 +7. `finally` ブロックですべての一時ファイルをクリーンアップします。 -エラー（ファイルが見つからない、構文エラー、インポート失敗）が発生した場合、エラーは `~/.failproofai/hook.log` に記録され、ローダーは空の配列を返します。組み込みポリシーへの影響はありません。 +エラーが発生した場合（ファイルが見つからない、構文エラー、インポート失敗）、エラーは `~/.failproofai/hook.log` に記録され、ローダーは空の配列を返します。組み込みポリシーは影響を受けません。 -カスタムポリシーはすべての組み込みポリシーの後に評価されます。カスタムポリシーが `deny` を返した場合、以降のカスタムポリシーの評価は短絡されますが、その時点ですべての組み込みポリシーはすでに実行済みです。 +カスタムポリシーはすべての組み込みポリシーの後に評価されます。カスタムポリシーの `deny` は後続のカスタムポリシーを短絡しますが（その時点ですべての組み込みポリシーはすでに実行済みです）。 --- ## アクティビティログ -各フックイベントの後、ハンドラーは JSONL の 1 行を `~/.failproofai/hook-activity/current.jsonl` に追記します。このファイルはページサイズに達すると `page--.jsonl` にローテーションされます。 +各フックイベントの後、ハンドラーは `~/.failproofai/hook-activity/current.jsonl` に JSONL の1行を追記します。このファイルはページサイズに達すると `page--.jsonl` にローテーションされます。 ```json { @@ -258,70 +258,70 @@ export function clearCustomHooks(): void { ... } // テストで使用 } ``` -allow 以外の判定をしたポリシーごとに 1 行記録されます。allow の判定はファイルサイズを小さく保つためにログに記録されません。 +非 allow の決定を下したポリシーごとに1行記録されます。ファイルサイズを小さく保つため、allow の決定はログに記録されません。 --- ## ダッシュボードのアーキテクチャ -ダッシュボードは App Router を使用した **Next.js 16** アプリケーションで、React Server Components と Server Actions を活用しています。 +ダッシュボードは、React Server Components と Server Actions を使用したApp Routerを採用した **Next.js 16** アプリケーションです。 ```text app/ layout.tsx ← ルートレイアウト（テーマ、テレメトリー、ナビゲーション） - projects/page.tsx ← サーバーコンポーネント: すべての Claude プロジェクトを一覧表示 - project/[name]/page.tsx ← サーバーコンポーネント: プロジェクト内のセッションを一覧表示 + projects/page.tsx ← サーバーコンポーネント: すべての Claude プロジェクトの一覧 + project/[name]/page.tsx ← サーバーコンポーネント: プロジェクト内のセッション一覧 project/[name]/session/ - [sessionId]/page.tsx ← サーバーコンポーネント: セッションビューアーのレンダリング + [sessionId]/page.tsx ← サーバーコンポーネント: セッションビューアーの表示 policies/page.tsx ← クライアントコンポーネント: ポリシー管理 + アクティビティログ actions/ - get-hooks-config.ts ← 設定 + ポリシーリストの読み取り - update-hooks-config.ts ← ポリシーの有効/無効の切り替え + get-hooks-config.ts ← 設定 + ポリシー一覧の読み取り + update-hooks-config.ts ← ポリシーのオン/オフ切り替え update-policy-params.ts ← ポリシーパラメーターの更新 get-hook-activity.ts ← アクティビティログのページネーション/検索 install-hooks-web.ts ← ブラウザからのフックのインストール/削除 api/ - download/[project]/[session]/route.ts ← CLI セッションごとのエクスポート（JSONL または JSON） + download/[project]/[session]/route.ts ← CLIセッションごとのエクスポート（JSONL または JSON） ``` **データフロー:** - ページコンポーネントは `lib/projects.ts` と `lib/log-entries.ts` を呼び出し、ファイルシステムから直接プロジェクト/セッションデータを読み取ります（読み取りに API レイヤーは不要）。 -- Policies ページはすべての変更操作（切り替え、パラメーター更新、インストール/削除）に Server Actions を使用します。 +- ポリシーページはすべての変更操作（切り替え、パラメーター更新、インストール/削除）に Server Actions を使用します。 - セッションビューアーは Claude の JSONL トランスクリプト形式をパースし、メッセージとツール呼び出しのタイムラインをレンダリングします。 -**主要な設計判断:** +**主要な設計上の決定事項:** -- データベースなし - すべての永続的な状態はプレーンファイル（`~/.failproofai/`、`~/.claude/projects/`）に保存します。 -- 変更操作には Server Actions を使用 - CRUD 操作に REST API は不要です。 -- 読み取りページには React Server Components を使用 - 初期ロードが高速で、データフェッチのクライアントバンドルが不要です。 -- クライアントコンポーネントはインタラクティブ性が必要な場合のみ使用します（ポリシーの切り替え、アクティビティ検索、ログビューアー）。 +- データベースなし — すべての永続的な状態はプレーンファイル（`~/.failproofai/`、`~/.claude/projects/`）に保存されます。 +- 変更操作には Server Actions を使用 — CRUD 操作に REST API は不要。 +- 読み取りページには React Server Components を使用 — 初期読み込みが速く、データフェッチのクライアントバンドルが不要。 +- クライアントコンポーネントはインタラクティビティが必要な箇所のみ（ポリシーの切り替え、アクティビティ検索、ログビューアー）。 --- -## ファイル構成 +## ファイルレイアウト ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI ルーター（hook / dashboard / install など） +│ └── failproofai.mjs # CLI ルーター（フック / ダッシュボード / インストール など） ├── src/hooks/ │ ├── handler.ts # フックイベントパイプライン -│ ├── builtin-policies.ts # 39 個のポリシー定義 +│ ├── builtin-policies.ts # 39個のポリシー定義 │ ├── policy-evaluator.ts # ポリシー実行エンジン -│ ├── policy-registry.ts # ポリシーの登録と参照 +│ ├── policy-registry.ts # ポリシーの登録と検索 │ ├── policy-types.ts # TypeScript インターフェース -│ ├── hooks-config.ts # マルチスコープ設定読み込み +│ ├── hooks-config.ts # マルチスコープ設定の読み込み │ ├── custom-hooks-registry.ts # globalThis ベースのフックレジストリ │ ├── custom-hooks-loader.ts # ユーザー JS フック用の ESM ローダー -│ ├── manager.ts # インストール/削除/一覧操作 +│ ├── manager.ts # インストール / 削除 / 一覧表示の操作 │ ├── install-prompt.ts # インタラクティブなポリシー選択プロンプト │ ├── hook-logger.ts # hook.log へのログ記録 -│ ├── hook-activity-store.ts # hook-activity/ へのアクティビティ永続化 +│ ├── hook-activity-store.ts # hook-activity/ へのアクティビティ保存 │ └── llm-client.ts # LLM API クライアント（AI 駆動ポリシー用） ├── app/ # Next.js ダッシュボード（ページ + サーバーアクション） ├── lib/ # 共有ユーティリティ -│ ├── projects.ts # ファイルシステムから Claude プロジェクトを列挙 +│ ├── projects.ts # ファイルシステムからの Claude プロジェクトの列挙 │ ├── log-entries.ts # Claude トランスクリプト JSONL 形式のパース │ ├── paths.ts # システムパスの解決 │ └── ... diff --git a/docs/ja/built-in-policies.mdx b/docs/ja/built-in-policies.mdx index 6f9ed9b0..5426c1e1 100644 --- a/docs/ja/built-in-policies.mdx +++ b/docs/ja/built-in-policies.mdx @@ -1,18 +1,18 @@ --- title: 組み込みポリシー -description: "エージェントの一般的な障害モードを検出する39の組み込みポリシー" +description: "よくあるエージェントの失敗パターンを検出する39個の組み込みポリシー" icon: shield --- -failproofai には、エージェントの一般的な障害モードを検出する39の組み込みポリシーが含まれています。各ポリシーは特定のフックイベントタイプとツール名に基づいて動作します。19のポリシーはコードを書かずに動作を調整できるパラメーターを受け付けます。5つのワークフローポリシーは、Claude が停止する前にコミット → プッシュ → PR → CI のパイプラインを強制します。 +failproofai には、よくあるエージェントの失敗パターンを検出する39個の組み込みポリシーが含まれています。各ポリシーは特定のフックイベントタイプとツール名に対して発動します。19個のポリシーはコードを書かずに動作を調整できるパラメーターを受け付けます。5つのワークフローポリシーは、Claude が停止する前にコミット → プッシュ → PR → CI というパイプラインを強制します。 --- ## 概要 -ポリシーはカテゴリ別にグループ化されています： +ポリシーはカテゴリーごとにグループ化されています： -| カテゴリ | ポリシー | フックタイプ | +| カテゴリー | ポリシー | フックタイプ | |----------|----------|-----------| | [危険なコマンド](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | | [インフラコマンド](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | @@ -25,15 +25,15 @@ failproofai には、エージェントの一般的な障害モードを検出 | [パッケージマネージャー](#package-managers) | prefer-package-manager | PreToolUse | | [ワークフロー](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — エージェントの処理を停止します。 -- **`warn-`** — エージェントが自己修正できるよう追加のコンテキストを提供します。 -- **`sanitize-`** — エージェントが確認する前にツール出力から機密データを除去します。 +- **`block-`** — エージェントの処理を停止する。 +- **`warn-`** — エージェントが自己修正できるよう追加のコンテキストを提供する。 +- **`sanitize-`** — エージェントが参照する前にツールの出力から機密データを除去する。 ### 名前空間 -すべてのポリシーは `/` スロットに存在します。組み込みポリシーは **`failproofai/`** 名前空間に属します（例：`failproofai/sanitize-jwt`）。名前空間は、似た短い名前を持つカスタムまたはサードパーティポリシーを読み込む際の衝突を防ぎます。 +すべてのポリシーは `/` のスロットに存在します。組み込みポリシーは **`failproofai/`** 名前空間に属します（例：`failproofai/sanitize-jwt`）。この名前空間により、似たような短い名前を持つカスタムまたはサードパーティのポリシーを同時に読み込む際の衝突を防ぎます。 -設定では、組み込みポリシーを短い名前または完全修飾名のどちらでも参照できます。どちらの形式も同じポリシーに解決されます： +設定ファイルでは、組み込みポリシーを短い名前または完全修飾名のどちらで参照しても同じポリシーに解決されます： ```json { @@ -44,32 +44,32 @@ failproofai には、エージェントの一般的な障害モードを検出 } ``` -名前に `/` が含まれない場合、failproofai はそれをデフォルト名前空間 `failproofai` に属するものとして扱います。すでに `/` を含む名前（例：`myorg/foo`、`custom/my-hook`）はそのまま保持されます。 -- **`require-`** — 条件が満たされるまで Stop イベントをブロックします。 +名前に `/` が含まれない場合、failproofai はデフォルトの名前空間 `failproofai` に属するものとして扱います。すでに `/` を含む名前（例：`myorg/foo`、`custom/my-hook`）はそのまま使用されます。 +- **`require-`** — 条件が満たされるまで Stop イベントをブロックする。 --- -すべてのポリシーは `policyParams` でオプションの `hint` フィールドをサポートしています。ヒントは Claude が受け取る deny または instruct メッセージに追記され、ポリシーコードを変更せずに実行可能なガイダンスを提供します。組み込み、カスタム、コンベンションポリシーで動作します。詳細は [設定 → hint](/ja/configuration#hint-cross-cutting) を参照してください。 +すべてのポリシーは `policyParams` 内でオプションの `hint` フィールドをサポートします。hint は Claude が受け取る deny または instruct メッセージに追記され、ポリシーコードを変更せずに実行可能なガイダンスを提供します。組み込み、カスタム、規約ポリシーすべてに対応しています。詳細は[設定 → hint](/ja/configuration#hint-cross-cutting)を参照してください。 --- ## 危険なコマンド -取り消しが困難な操作や、ホストシステムに損害を与える可能性のある操作をエージェントが実行しないようにします。 +元に戻すのが困難な操作や、ホストシステムに損害を与える可能性のある操作をエージェントが実行するのを防ぎます。 ### `block-sudo` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `sudo` または `doas` コマンドを拒否します。 -**コマンドポジション**にある昇格バイナリを実行するコマンドをブロックします。マッチングはテキストではなく構造的に行われます：コマンドはシェルと同様の方法でセグメントに分割され、プレフィックスの代入（`FOO=bar`）、リダイレクト、フラグ付きランナー（`env`、`nohup`、`timeout`、`xargs`、`sh -c` など）が取り除かれ、結果として得られるバイナリが**ベース名**で比較されます。そのため、`/usr/bin/sudo`、`env sudo`、`timeout 5 sudo`、`"sudo"`、`\sudo`、`bash -c "sudo …"` はすべて拒否され、`doas` も同じ機能を持つ別名として扱われます。 +コマンド位置で権限昇格バイナリを実行するコマンドをブロックします。マッチングはテキスト的ではなく構造的に行われます：コマンドはシェルが行うようにセグメントに分割され、プレフィックスの代入（`FOO=bar`）、リダイレクト、フラグ付きのランナー（`env`、`nohup`、`timeout`、`xargs`、`sh -c` など）が除去され、残ったバイナリが**バセネーム**で比較されます。そのため `/usr/bin/sudo`、`env sudo`、`timeout 5 sudo`、`"sudo"`、`\sudo`、`bash -c "sudo …"` はすべて拒否され、`doas` も同等の権限昇格として扱われます。 -コマンドポジションにアンカーしているため、単に言及されているだけのコマンドには反応しません。`grep -r sudo /etc`、`cat /etc/sudoers`、`git commit -m "fix sudo handling"`、または単語を含む `grep` の代替はすべて正常に実行されます。 +コマンド位置に基づいてチェックするため、単にその単語が含まれるだけのコマンド（`grep -r sudo /etc`、`cat /etc/sudoers`、`git commit -m "fix sudo handling"`、単語を含む `grep` の選択肢など）は通常通り実行されます。 -これは明白な試みを止めますが、そのクラス全体を網羅するわけではありません。任意のシェルを実行できるエージェントは、変数（`S=sudo; $S …`）、base64デコードされたパイプ、またはディスク上のラッパースクリプトを通じて間接的に昇格に到達できます。単一のコマンド文字列の検査ではそれらを追跡できないためです。これはミスや軽率なエスカレーションに対するガードレールとして扱ってください。意図的なエージェントに対するセキュリティ境界としては機能しません。本物の境界はシェルの下のレイヤーで強制する必要があります。 +これは明示的な試みを防ぐものですが、すべてのケースを網羅するわけではありません。任意のシェルを実行できるエージェントは、変数（`S=sudo; $S …`）、base64デコードされたパイプ、またはディスク上のラッパースクリプトを通じて間接的に権限昇格に達することができます。単一のコマンド文字列の検査ではそれらを追跡できないためです。これはミスや意図的でない権限昇格に対するガードレールとして扱ってください。本当のセキュリティ境界はシェルの下のレイヤーで強制する必要があります。 **パラメーター:** @@ -93,21 +93,21 @@ failproofai には、エージェントの一般的な障害モードを検出 この設定では、`sudo systemctl status nginx` は許可されますが、`sudo rm /etc/hosts` は拒否されます。 -パターンは生のコマンド文字列ではなく、解析されたトークンに対してマッチングされます。これにより、追加のシェル演算子（例：`sudo systemctl status x; rm -rf /` は `sudo systemctl status *` にマッチしない）によるバイパスを防ぎます。 +パターンは生のコマンド文字列ではなく、解析されたトークンに対してマッチングされます。これにより、シェル演算子を付加することによるバイパスを防ぎます（例：`sudo systemctl status x; rm -rf /` は `sudo systemctl status *` にマッチしません）。 --- ### `block-rm-rf` -**イベント:** PreToolUse (Bash) -**デフォルト:** `rm -rf`、`rm -fr`、および類似の再帰的削除形式を拒否します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** `rm -rf`、`rm -fr`、および同様の再帰的削除パターンを拒否します。 **パラメーター:** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | 再帰的に削除しても安全なパス（例：`/tmp`）。 | +| `allowPaths` | `string[]` | `[]` | 再帰的削除が安全なパス（例：`/tmp`）。 | **例:** @@ -125,8 +125,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-curl-pipe-sh` -**イベント:** PreToolUse (Bash) -**デフォルト:** `curl | bash`、`curl | sh`、`wget | bash` および類似のパターンを拒否します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** `curl | bash`、`curl | sh`、`wget | bash`、および同様のパターンを拒否します。 パラメーターなし。 @@ -134,8 +134,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-failproofai-commands` -**イベント:** PreToolUse (Bash) -**デフォルト:** failproofai 自体をアンインストールまたは無効化するコマンドを拒否します（例：`npm uninstall failproofai`、`failproofai policies --uninstall`）。 +**イベント:** PreToolUse (Bash) +**デフォルト:** failproofai 自体をアンインストールまたは無効化するコマンド（例：`npm uninstall failproofai`、`failproofai policies --uninstall`）を拒否します。 パラメーターなし。 @@ -143,12 +143,12 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-self-pause` -**イベント:** PreToolUse (Bash) -**デフォルト:** セッションの強制を一時停止する `failproofai config --pause` を拒否します。一時停止は人間が決定すべきことです。エージェントがこれを実行できると、単一のコマンドで他のすべてのポリシーをオフにできてしまいます。 +**イベント:** PreToolUse (Bash) +**デフォルト:** セッションの強制を一時停止する `failproofai config --pause` を拒否します。一時停止は人間が行う判断であり、エージェントがこれを実行できると、1つのコマンドで他のすべてのポリシーを無効化できてしまいます。 -意図的に [`block-failproofai-commands`](#block-failproofai-commands) より範囲が狭く、そのポリシーにはカバーされていません。そのポリシーはコマンド境界にアンカーしているため、`npx -y failproofai config --pause` はマッチせず、また広範であるためエージェントが `failproofai audit` を実行できるよう無効にされることが多いです。`--resume` と `--status` は許可されています。どちらも強制を削除しません。 +[`block-failproofai-commands`](#block-failproofai-commands) よりも意図的に狭いスコープであり、そのポリシーでカバーされていません：そのポリシーはコマンド境界に基づくため `npx -y failproofai config --pause` はマッチせず、また範囲が広いため `failproofai audit` を実行するエージェントのためにオフにされることが多いです。`--resume` と `--status` は許可されます（どちらも強制を削除しません）。 -これは直接的な試みを止めますが、クラス全体ではありません。エージェントはエイリアスやラッパースクリプトを通じて同じ状態に到達できます。完全に閉じるには、ツール呼び出しからそもそも一時停止にアクセスできないようにする必要があります。 +これは直接的な試みを防ぐものであり、すべてのケースを網羅するわけではありません：エージェントはエイリアスやラッパースクリプトを通じて同じ状態に達することができます。完全にブロックするには、ツールコールからそもそも一時停止が到達不能である必要があります。 パラメーターなし。 @@ -156,14 +156,14 @@ failproofai には、エージェントの一般的な障害モードを検出 ## インフラコマンド -コーディングエージェントがインフラ CLI を実行したり、CI/CD パイプラインをトリガーしたりしないようにします。このカテゴリのすべてのポリシーは**オプトイン**（`defaultEnabled: false`）です。正当に `kubectl`、`terraform` などを呼び出す必要があるエージェントは、ポリシーを有効にしない限り影響を受けません。有効にすると、マッチした CLI のすべての呼び出しは、コマンドが `allowPatterns` のエントリに一致しない限り拒否されます。 +コーディングエージェントがインフラ CLI を実行したり、CI/CD パイプラインをトリガーするのを防ぎます。このカテゴリーのすべてのポリシーは**オプトイン**（`defaultEnabled: false`）です。`kubectl`、`terraform` などを正当に呼び出す必要があるエージェントは、ポリシーを有効にしない限り影響を受けません。有効にすると、マッチした CLI のすべての呼び出しは、コマンドが `allowPatterns` のエントリにマッチしない限り拒否されます。 -パターンの文法は [`block-sudo`](#block-sudo) と同じです：トークンは解析された argv に対してマッチングされ、`*` は1つのトークンのワイルドカードです。また、スタンドアロンのシェル演算子（`&&`、`||`、`|`、`;`）または埋め込みシェルメタキャラクターを含むトークンを含むコマンドは、インジェクションバイパスを防ぐためにアローリストマッチングの前に拒否されます。 +パターン文法は [`block-sudo`](#block-sudo) と同じです：トークンは解析された argv に対してマッチングされ、`*` は1トークンのワイルドカードで、スタンドアロンのシェル演算子（`&&`、`||`、`|`、`;`）またはシェルメタキャラクターが埋め込まれたトークンを含むコマンドは、インジェクションバイパスを防ぐためにアローリストマッチング前に拒否されます。 ### `block-kubectl` -**イベント:** PreToolUse (Bash) -**デフォルト:** `kubectl` の呼び出しを拒否します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** すべての `kubectl` 呼び出しを拒否します。 **パラメーター:** @@ -189,8 +189,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-terraform` -**イベント:** PreToolUse (Bash) -**デフォルト:** `terraform` または `tofu`（OpenTofu）の呼び出しを拒否します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** すべての `terraform` または `tofu`（OpenTofu）呼び出しを拒否します。 **パラメーター:** @@ -214,8 +214,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-aws-cli` -**イベント:** PreToolUse (Bash) -**デフォルト:** `aws` CLI の呼び出しを拒否します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** すべての `aws` CLI 呼び出しを拒否します。 **パラメーター:** @@ -239,8 +239,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-gcloud` -**イベント:** PreToolUse (Bash) -**デフォルト:** `gcloud`（Google Cloud）CLI の呼び出しを拒否します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** すべての `gcloud`（Google Cloud）CLI 呼び出しを拒否します。 **パラメーター:** @@ -264,8 +264,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-az-cli` -**イベント:** PreToolUse (Bash) -**デフォルト:** `az`（Azure）CLI の呼び出しを拒否します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** すべての `az`（Azure）CLI 呼び出しを拒否します。 **パラメーター:** @@ -289,8 +289,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-helm` -**イベント:** PreToolUse (Bash) -**デフォルト:** `helm` の呼び出しを拒否します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** すべての `helm` 呼び出しを拒否します。 **パラメーター:** @@ -314,8 +314,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-gh-pipeline` -**イベント:** PreToolUse (Bash) -**デフォルト:** 状態を変更したりパイプラインをトリガーしたりする以下の `gh` CLI サブコマンドを拒否します： +**イベント:** PreToolUse (Bash) +**デフォルト:** 状態を変更したりパイプラインをトリガーする以下の `gh` CLI サブコマンドを拒否します： - `gh workflow run`、`gh workflow enable`、`gh workflow disable` - `gh run rerun`、`gh run cancel` @@ -324,13 +324,13 @@ failproofai には、エージェントの一般的な障害モードを検出 - `gh cache delete` - `gh secret set`、`gh secret delete` -`gh pr view`、`gh pr list`、`gh run list`、`gh release view`、`gh api repos/.../...` などの読み取り専用 `gh` サブコマンドはこのポリシーにマッチしません。これらはワークフローチェック（failproofai 自身の `require-ci-green-before-stop` を含む）で日常的に必要とされます。 +`gh pr view`、`gh pr list`、`gh run list`、`gh release view`、`gh api repos/.../...` などの読み取り専用の `gh` サブコマンドはこのポリシーにマッチしません。これらはワークフローチェック（failproofai 独自の `require-ci-green-before-stop` を含む）に日常的に必要です。 **パラメーター:** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 通常は拒否されるにもかかわらず許可する特定のスクリプト呼び出し。 | +| `allowPatterns` | `string[]` | `[]` | 通常は拒否される特定のスクリプト化された呼び出しを許可します。 | **例:** @@ -348,11 +348,11 @@ failproofai には、エージェントの一般的な障害モードを検出 ## シークレット（サニタイザー） -エージェントがコンテキストや出力に認証情報を漏洩しないようにします。サニタイザーポリシーは **PostToolUse** イベントで動作します。Claude が Bash コマンドを実行したり、ファイルを読み取ったり、ツールを呼び出したりすると、これらのポリシーは出力が Claude に返される前に検査します。シークレットパターンが検出された場合、ポリシーは出力が返されないよう deny 決定を返します。 +エージェントがコンテキストや出力に認証情報を漏洩するのを防ぎます。サニタイザーポリシーは **PostToolUse** イベントで発動します。Claude が Bash コマンドを実行したり、ファイルを読み込んだり、ツールを呼び出したりすると、これらのポリシーは Claude に返される前に出力を検査します。シークレットパターンが検出された場合、ポリシーは出力が返されないように deny 決定を返します。 ### `sanitize-jwt` -**イベント:** PostToolUse（すべてのツール） +**イベント:** PostToolUse（すべてのツール） **デフォルト:** JWT トークン（`.` で区切られた3つの base64url セグメント）を削除します。 パラメーターなし。 @@ -361,8 +361,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `sanitize-api-keys` -**イベント:** PostToolUse（すべてのツール） -**デフォルト:** 一般的な API キー形式を削除します：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS アクセスキー（`AKIA`）、Stripe キー（`sk_live_`、`sk_test_`）、Google API キー（`AIza`）。 +**イベント:** PostToolUse（すべてのツール） +**デフォルト:** よく知られた API キーフォーマットを削除します：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS アクセスキー（`AKIA`）、Stripe キー（`sk_live_`、`sk_test_`）、Google API キー（`AIza`）。 **パラメーター:** @@ -389,8 +389,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `sanitize-connection-strings` -**イベント:** PostToolUse（すべてのツール） -**デフォルト:** 埋め込まれた認証情報を含むデータベース接続文字列（例：`postgresql://user:password@host/db`）を削除します。 +**イベント:** PostToolUse（すべてのツール） +**デフォルト:** 認証情報が埋め込まれたデータベース接続文字列（例：`postgresql://user:password@host/db`）を削除します。 パラメーターなし。 @@ -398,7 +398,7 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `sanitize-private-key-content` -**イベント:** PostToolUse（すべてのツール） +**イベント:** PostToolUse（すべてのツール） **デフォルト:** PEM ブロック（`-----BEGIN PRIVATE KEY-----`、`-----BEGIN RSA PRIVATE KEY-----` など）を削除します。 パラメーターなし。 @@ -407,7 +407,7 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `sanitize-bearer-tokens` -**イベント:** PostToolUse（すべてのツール） +**イベント:** PostToolUse（すべてのツール） **デフォルト:** トークンが20文字以上の `Authorization: Bearer ` ヘッダーを削除します。 パラメーターなし。 @@ -420,10 +420,10 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-env-files` -**イベント:** PreToolUse (Bash, Read) -**デフォルト:** `cat .env`、`.env` をファイルパスとした `Read` ツール呼び出しなどによる `.env` ファイルの読み取りを拒否します。 +**イベント:** PreToolUse (Bash, Read) +**デフォルト:** `cat .env`、ファイルパスとして `.env` を指定した `Read` ツール呼び出しなどによる `.env` ファイルの読み取りを拒否します。 -`.envrc` や他の環境関連ファイルはブロックしません。`.env` という名前のファイルのみをブロックします。 +`.envrc` や他の環境関連ファイルはブロックしません。`.env` という名前のファイルのみが対象です。 パラメーターなし。 @@ -431,8 +431,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `protect-env-vars` -**イベント:** PreToolUse (Bash) -**デフォルト:** 環境変数を表示するコマンドを拒否します：`printenv`、`env`、`echo $VAR`。 +**イベント:** PreToolUse (Bash) +**デフォルト:** 環境変数を表示するコマンド（`printenv`、`env`、`echo $VAR`）を拒否します。 パラメーターなし。 @@ -440,18 +440,18 @@ failproofai には、エージェントの一般的な障害モードを検出 ## ファイルアクセス -エージェントをプロジェクト境界内に留め、機密ファイルから遠ざけます。 +エージェントをプロジェクトの境界内に留め、機密ファイルへのアクセスを防ぎます。 ### `block-read-outside-cwd` -**イベント:** PreToolUse (Read, Bash) -**デフォルト:** プロジェクトルート外のファイルの読み取りを拒否します。境界は `CLAUDE_PROJECT_DIR`（Claude Code がセッションごとに一度設定する）で、この変数が設定されていない場合はセッションのカレントワーキングディレクトリにフォールバックします。ライブの `cwd` ではなくプロジェクトルートを使用することで、Claude がサブディレクトリに `cd` した後も境界が安定して保たれます。 +**イベント:** PreToolUse (Read, Bash) +**デフォルト:** プロジェクトルート外のファイルの読み取りを拒否します。境界は `CLAUDE_PROJECT_DIR`（Claude Code によってセッションごとに1回設定される）で、その変数が未設定の場合はセッションの現在の作業ディレクトリにフォールバックします。ライブの `cwd` ではなくプロジェクトルートを使用するため、Claude がサブディレクトリに `cd` した後でも境界は安定しています。 **パラメーター:** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | プロジェクトルート外であっても許可する絶対パスプレフィックス。 | +| `allowPaths` | `string[]` | `[]` | プロジェクトルート外であっても許可される絶対パスプレフィックス。 | **例:** @@ -469,14 +469,14 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-secrets-write` -**イベント:** PreToolUse (Write, Edit) -**デフォルト:** 秘密鍵と証明書によく使用されるファイルへの書き込みを拒否します：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。 +**イベント:** PreToolUse (Write, Edit) +**デフォルト:** 秘密鍵と証明書に一般的に使用されるファイルへの書き込みを拒否します：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。 **パラメーター:** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | ブロックする追加のファイル名パターン（グロブ形式）。 | +| `additionalPatterns` | `string[]` | `[]` | ブロックする追加のファイル名パターン（glob スタイル）。 | **例:** @@ -494,11 +494,11 @@ failproofai には、エージェントの一般的な障害モードを検出 ## Git -取り消しが困難な誤ったプッシュ、フォースプッシュ、ブランチの誤操作を防ぎます。 +間違ったプッシュ、フォースプッシュ、元に戻しにくいブランチの操作ミスを防ぎます。 ### `block-push-master` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `git push origin main` および `git push origin master` を拒否します。 **パラメーター:** @@ -527,8 +527,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-work-on-main` -**イベント:** PreToolUse (Bash) -**デフォルト:** ワーキングツリーが `main` または `master` にある間は `git commit`、`git merge`、`git rebase`、`git cherry-pick` を拒否します。ブランチの作成と切り替え（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）は影響を受けません。 +**イベント:** PreToolUse (Bash) +**デフォルト:** 作業ツリーが `main` または `master` にある間、`git commit`、`git merge`、`git rebase`、`git cherry-pick` を拒否します。ブランチの作成と切り替え（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）は影響を受けません。 **パラメーター:** @@ -540,10 +540,10 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `block-force-push` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `git push --force` および `git push -f` を拒否します。 -ポリシー固有のパラメーターはありません。代替手段を提案するにはクロスカッティングの [`hint`](/ja/configuration#hint-cross-cutting) を使用します： +ポリシー固有のパラメーターはありません。クロスカッティングの [`hint`](/ja/configuration#hint-cross-cutting) を使用して代替案を提案できます： ```json { @@ -559,7 +559,7 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `warn-git-amend` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `git commit --amend` を実行する際に慎重に進むよう Claude に指示します。コマンドはブロックしません。 パラメーターなし。 @@ -568,7 +568,7 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `warn-git-stash-drop` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `git stash drop` を実行する前に確認するよう Claude に指示します。コマンドはブロックしません。 パラメーターなし。 @@ -577,8 +577,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `warn-all-files-staged` -**イベント:** PreToolUse (Bash) -**デフォルト:** `git add -A` または `git add .` を実行する際にステージングする内容を確認するよう Claude に指示します。コマンドはブロックしません。 +**イベント:** PreToolUse (Bash) +**デフォルト:** `git add -A` または `git add .` を実行する際にステージングされる内容を確認するよう Claude に指示します。コマンドはブロックしません。 パラメーターなし。 @@ -586,11 +586,11 @@ failproofai には、エージェントの一般的な障害モードを検出 ## データベース -データベースに対して実行される前に破壊的な SQL 操作を検出します。 +データベースに対して実行される前に、破壊的な SQL 操作を検出します。 ### `warn-destructive-sql` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `DROP TABLE`、`DROP DATABASE`、または `WHERE` 句のない `DELETE` を含む SQL を実行する前に確認するよう Claude に指示します。 パラメーターなし。 @@ -599,7 +599,7 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `warn-schema-alteration` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `ALTER TABLE` ステートメントを実行する前に確認するよう Claude に指示します。 パラメーターなし。 @@ -608,18 +608,18 @@ failproofai には、エージェントの一般的な障害モードを検出 ## 警告 -破壊的ではないが潜在的にリスクのある操作の前にエージェントに追加のコンテキストを提供します。 +破壊的ではないものの潜在的にリスクのある操作の前に、エージェントに追加のコンテキストを提供します。 ### `warn-large-file-write` -**イベント:** PreToolUse (Write) +**イベント:** PreToolUse (Write) **デフォルト:** 1024 KB を超えるファイルを書き込む前に確認するよう Claude に指示します。 **パラメーター:** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | 警告が発せられるファイルサイズのしきい値（キロバイト）。 | +| `thresholdKb` | `number` | `1024` | 警告が発行されるファイルサイズのしきい値（キロバイト）。 | **例:** @@ -634,14 +634,14 @@ failproofai には、エージェントの一般的な障害モードを検出 ``` -フックハンドラーはペイロードに対して 1 MB の stdin 制限を適用します。小さいコンテンツでこのポリシーをテストするには、`thresholdKb` を 1024 をかなり下回る値に設定してください。 +フックハンドラーはペイロードに対して 1 MB の stdin 制限を強制します。小さなコンテンツでこのポリシーをテストするには、`thresholdKb` を 1024 より十分に低い値に設定してください。 --- ### `warn-package-publish` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `npm publish` を実行する前に確認するよう Claude に指示します。 パラメーターなし。 @@ -650,8 +650,8 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `warn-background-process` -**イベント:** PreToolUse (Bash) -**デフォルト:** `nohup`、`&`、`disown`、または `screen` でバックグラウンドプロセスを起動する際に注意するよう Claude に指示します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** `nohup`、`&`、`disown`、または `screen` を使用してバックグラウンドプロセスを起動する際に注意するよう Claude に指示します。 パラメーターなし。 @@ -659,7 +659,7 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `warn-global-package-install` -**イベント:** PreToolUse (Bash) +**イベント:** PreToolUse (Bash) **デフォルト:** `npm install -g`、`yarn global add`、または仮想環境なしの `pip install` を実行する前に確認するよう Claude に指示します。 パラメーターなし。 @@ -672,17 +672,17 @@ failproofai には、エージェントの一般的な障害モードを検出 ### `prefer-package-manager` -**イベント:** PreToolUse (Bash) -**デフォルト:** 無効。有効にすると、`allowed` リストにないパッケージマネージャーコマンドをブロックし、許可されているマネージャーを使用してコマンドを書き直すよう Claude に指示します。 +**イベント:** PreToolUse (Bash) +**デフォルト:** 無効。有効にすると、`allowed` リストにないパッケージマネージャーコマンドをブロックし、許可されたマネージャーを使用してコマンドを書き直すよう Claude に指示します。 検出対象：pip、pip3、python -m pip、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。 | パラメーター | 型 | デフォルト | 説明 | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | 許可されるパッケージマネージャー名。このリストにない検出されたマネージャーはブロックされます。空の場合、ポリシーは何もしません。 | -| `blocked` | string[] | `[]` | 組み込みリスト以外にブロックする追加のマネージャー名（例：`['pdm', 'pipx']`）。 | +| `allowed` | string[] | `[]` | 許可されるパッケージマネージャー名。このリストにない検出済みマネージャーはブロックされます。空の場合、ポリシーは何もしません。 | +| `blocked` | string[] | `[]` | 組み込みリストに加えてブロックする追加のマネージャー名（例：`['pdm', 'pipx']`）。 | -組み込みブロックリストには pip、pip3、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo が含まれます。このリストにないマネージャーを追加するには `blocked` を使用します。 +組み込みのブロックリスト：pip、pip3、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。このリストにないマネージャーを追加するには `blocked` を使用します。 **設定例:** @@ -698,18 +698,18 @@ failproofai には、エージェントの一般的な障害モードを検出 } ``` -この設定では、`pip install flask` と `pdm install flask` は両方とも、`uv` または `bun` を使用するよう Claude に伝えるメッセージとともに拒否されます。`uv pip install flask` のようなコマンドは `uv` がアローリストにあり最初にチェックされるため許可されます。 +この設定では、`pip install flask` と `pdm install flask` はどちらも拒否され、`uv` または `bun` を使用するよう Claude に伝えるメッセージが表示されます。`uv pip install flask` のようなコマンドは `uv` がアローリストにあり最初にチェックされるため許可されます。 --- ## AI の動作 -エージェントが行き詰まったり予期しない動作をしたりする場合に検出します。 +エージェントが行き詰まったり予期しない動作をしたりしていることを検出します。 ### `warn-repeated-tool-calls` -**イベント:** PreToolUse（すべてのツール） -**デフォルト:** 同じツールが同じパラメーターで3回以上呼び出された場合、再考するよう Claude に指示します。これはエージェントがループにはまっているよくあるサインです。 +**イベント:** PreToolUse（すべてのツール） +**デフォルト:** 同じツールが同一のパラメーターで3回以上呼び出された場合（エージェントがループにはまっている一般的なサイン）、再考するよう Claude に指示します。 パラメーターなし。 @@ -717,39 +717,39 @@ failproofai には、エージェントの一般的な障害モードを検出 ## ワークフロー -セッション終了時の規律あるワークフローを強制します。これらのポリシーは **Stop** イベントで動作し、各条件が満たされるまでエージェントの停止を拒否します。自然な依存チェーン（コミット → プッシュ → PR → CI）に従います。ポリシーが拒否すると、チェーン内の後続ポリシーはスキップされます（deny がショートサーキットします）。 +セッション終了時の規律あるワークフローを強制します。これらのポリシーは **Stop** イベントで発動し、各条件が満たされるまでエージェントの停止を拒否します。コミット → プッシュ → PR → CI という自然な依存チェーンに従います。ポリシーが拒否した場合、チェーン内の後続のポリシーはスキップされます（deny はショートサーキットします）。 すべてのワークフローポリシーは**フェールオープン**です：必要なツールが利用できない場合（例：`gh` がインストールされていない、git リモートがない）、ポリシーはチェックがスキップされた理由を説明する情報メッセージとともに許可します。 ### CLI ごとの Stop セマンティクス -Stop の強制は、サポートされている6つの CLI によって多少異なります。それぞれが異なる「エージェント完了」フックコントラクトを公開しているためです。**結果**は同じです（ワークフローゲートが失敗している間はエージェントが停止できない）が、**仕組み**は異なります。以下の表に要約します。`require-*-before-stop` ポリシーを有効にする前に理解しておく価値のあるユーザーに見えるような特異点は Pi のみです。 +Stop の強制は、サポートされている6つの CLI によって若干異なります。各 CLI が異なる「エージェント完了」フックコントラクトを公開しているためです。**結果**は同じです（ワークフローゲートが失敗している間、エージェントは停止できません）が、**仕組み**は異なります。以下の表にまとめます。`require-*-before-stop` ポリシーを有効にする前に理解する価値のある、ユーザーが目にする注意点があるのは Pi のみです。 -| CLI | ゲートが発動するタイミング | 表示内容 | +| CLI | ゲートが発動するタイミング | 表示される内容 | |---|---|---| -| Claude Code | 同じエージェントループ、即座 | Claude は作業を続けます。問題を修正してから再度終了を試みます。あなたには中断は見えません。 | -| Codex | 同じエージェントループ、即座 | Claude と同じ。 | -| GitHub Copilot CLI | 同じエージェントループ、即座 | Claude と同じ（Copilot の `{decision:"block", reason}` リトライチャネルを使用。Copilot CLI 1.0.41 に対して実験的に検証済み）。 | -| Cursor Agent | 同じエージェントループ、即座 | Claude と同じ（Cursor の `{followup_message}` チャネルを使用。`loop_limit` でキャップ、デフォルト5回リトライ）。 | -| OpenCode | 同じエージェントループ、即座 | Claude と同じ（OpenCode の `client.session.prompt(...)` SDK 呼び出しが `hookSpecificOutput.additionalContext` を通じてルーティングされます）。 | -| **Pi (pi-coding-agent)** | **次のユーザーターン** | **Pi はゲートが発動するとき visibly に停止します**。エージェントループが終了し、プロンプトに戻されます。ゲートは次にプロンプトを送信するときに発動します。failproofai はそのターンのシステムプロンプトの先頭に `MANDATORY ACTION REQUIRED` ディレクティブを追加し、LLM にリクエストを実行する前にワークフローステップ（コミット、プッシュなど）を完了するよう指示します。 | +| Claude Code | 同じエージェントループ、即時 | Claude は作業を続行します（問題を修正し、再度終了を試みます）。ユーザーには中断は見えません。 | +| Codex | 同じエージェントループ、即時 | Claude と同様です。 | +| GitHub Copilot CLI | 同じエージェントループ、即時 | Claude と同様です（Copilot の `{decision:"block", reason}` リトライチャンネルを使用 — Copilot CLI 1.0.41 に対して実証的に確認済み）。 | +| Cursor Agent | 同じエージェントループ、即時 | Claude と同様です（Cursor の `{followup_message}` チャンネルを使用 — `loop_limit` で上限あり、デフォルト5回のリトライ）。 | +| OpenCode | 同じエージェントループ、即時 | Claude と同様です（OpenCode の `client.session.prompt(...)` SDK 呼び出しを `hookSpecificOutput.additionalContext` 経由でルーティング）。 | +| **Pi (pi-coding-agent)** | **次のユーザーターン** | **Pi はゲートが発動するときに目に見えて停止します** — エージェントループが終了し、プロンプトに戻ります。次にプロンプトを送信したとき、ゲートが発動します：failproofai はそのターンのシステムプロンプトの先頭に `MANDATORY ACTION REQUIRED` ディレクティブを追加し、LLM に要求された操作を行う前にワークフローステップ（コミット、プッシュなど）を完了するよう指示します。 | -**Pi の制限。** Pi の `AgentEndEvent`（Claude の `Stop` フックに相当するアップストリームイベント）には Result タイプがありません。発動する時点で Pi のエージェントループはすでに終了しています。Pi は Claude / Copilot / Cursor / OpenCode のように同じループをリトライすることを強制できません。failproofai はゲートを Pi の `before_agent_start` イベント（次のユーザープロンプトの後に発動）に移すことで、ワークフローチェックが現在のターンではなく次のターンで強制されるようにします。 +**Pi の制限事項。** Pi の `AgentEndEvent`（Claude の `Stop` フックに相当するアップストリーム）には Result 型がありません。発動する時点で Pi のエージェントループはすでに終了しています。Pi は Claude / Copilot / Cursor / OpenCode のように同じループをリトライするよう強制できません。failproofai はゲートを Pi の `before_agent_start` イベント（次のユーザープロンプトの後に発動）にシフトすることで、ワークフローチェックを現在のターンではなく次のターンに強制します。 -**実際にどういう意味か：** +**実際の意味：** -- Pi が停止した後、deny の理由は Pi セッション ID をキーとしてメモリ内にキャプチャされます。同じ Pi プロセスで次に送信するプロンプトがそれを取り出します。LLM はシステムプロンプトの先頭に `MANDATORY ACTION REQUIRED` ディレクティブを見て、コミット（またはプッシュ / PR オープン / CI 待機）を行い、その後リクエストを続行します。キャプチャされた deny の理由はワンショットです。一度取り出されるとゲートはクリアされます。 -- ゲートは Pi のプロセスライフタイムに依存します。ターン間に Pi を `Ctrl+C` するか終了すると、インメモリエントリはプロセスとともにドロップされ、ゲートはミスされます。Claude、Copilot、Cursor、OpenCode も同じ制約があります（エージェントを強制終了するとゲートはミスされます）。Pi はエージェントがゲートが発動する前に visibly に終了するため、より目立つだけです。 -- 保留中の deny は、任意の理由（`new` / `resume` / `fork` / `quit`）による `session_shutdown` でもクリアされます。そのため、以前のセッションからの古いゲートが同じ Pi プロセスで開始された新しいセッションに漏れることはありません。 +- Pi が停止した後、deny の理由は Pi のセッション ID をキーとしてメモリに保存されます。同じ Pi プロセスで次に送信するプロンプトがそれを消費します：LLM はシステムプロンプトの先頭に `MANDATORY ACTION REQUIRED` ディレクティブを見て、コミット（またはプッシュ / PR 作成 / CI 待機）を行ってからリクエストを続行します。保存された deny の理由はワンショットです（一度消費されるとゲートはクリアされます）。 +- ゲートは Pi のプロセスのライフタイムに拘束されます。ターン間で `Ctrl+C` した場合や Pi を終了した場合、メモリエントリはプロセスとともに削除され、ゲートは無効になります。Claude、Copilot、Cursor、OpenCode も同様の制限があります（エージェントを強制終了するとゲートは無効になります）。Pi の場合はエージェントループが終了する前に目に見えて終了するため、より明確です。 +- 保留中の deny は、理由に関わらず `session_shutdown`（`new` / `resume` / `fork` / `quit`）時にもクリアされるため、前のセッションの古いゲートが同じ Pi プロセスで開始された新しいセッションに漏れることはありません。 -Claude スタイルの同一ループリトライが必要な場合は、他の5つのサポートされている CLI のいずれかで `Stop` ポリシーを実行してください。`AgentEndEvent` に将来の Result タイプが追加されてこのギャップを埋められるよう、Pi のアップストリームを追跡しています。 +Claude スタイルの同一ループリトライが必要な場合は、他の5つのサポートされている CLI のいずれかで `Stop` ポリシーを実行してください。`AgentEndEvent` に Result 型が追加され、このギャップを埋められるよう Pi アップストリームを追跡しています。 ### `require-commit-before-stop` -**イベント:** Stop -**デフォルト:** コミットされていない変更（変更済み、ステージ済み、または未追跡ファイル）がある場合に停止を拒否します。ワーキングディレクトリがクリーンな場合は情報メッセージを返します。 +**イベント:** Stop +**デフォルト:** コミットされていない変更（変更済み、ステージング済み、または未追跡のファイル）がある場合、停止を拒否します。作業ディレクトリがクリーンな場合は情報メッセージを返します。 パラメーターなし。 @@ -757,8 +757,8 @@ Claude スタイルの同一ループリトライが必要な場合は、他の5 ### `require-push-before-stop` -**イベント:** Stop -**デフォルト:** プッシュされていないコミットがある場合、または現在のブランチにリモートトラッキングブランチがない場合に停止を拒否します。必要に応じてトラッキングブランチを作成するために `git push -u` を提案します。リモートが設定されていない場合はフェールオープンします。 +**イベント:** Stop +**デフォルト:** プッシュされていないコミットがある場合、または現在のブランチにリモートトラッキングブランチがない場合、停止を拒否します。必要に応じてトラッキングブランチを作成するために `git push -u` を提案します。リモートが設定されていない場合はフェールオープンします。 **パラメーター:** @@ -782,27 +782,26 @@ Claude スタイルの同一ループリトライが必要な場合は、他の5 ### `require-pr-before-stop` -**イベント:** Stop -**デフォルト:** 現在のブランチにプルリクエストが存在しない場合、またはマージされずにクローズされた既存の PR がある場合に停止を拒否します。`gh pr create` で PR を作成するよう Claude に指示します。PR が**マージ**されると、ポリシーは許可します（作業がリリースされた）。そしてブランチから切り替えるヒントを提供します（`git checkout main && git pull`）。 +**イベント:** Stop +**デフォルト:** 現在のブランチにプルリクエストが存在しない場合、または既存の PR がマージされずにクローズされている場合、停止を拒否します。`gh pr create` で PR を作成するよう Claude に指示します。PR が**マージされた**場合、ポリシーは許可します（作業がリリースされた状態）。そしてブランチを切り替えるよう（`git checkout main && git pull`）ヒントを提供します。 パラメーターなし。 -このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）のインストールと認証が必要です。 -プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェールオープンし、その理由を Claude に報告します。 +このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ認証されている必要があります。プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェールオープンし、その理由を Claude に報告します。 --- ### `require-no-conflicts-before-stop` -**イベント:** Stop -**デフォルト:** 現在のブランチがベースブランチにクリーンにマージできない場合に停止を拒否します。ポリシーはまずブランチに GitHub 上の `OPEN` PR があることを確認します。PR がない場合は強制するマージターゲットがないため、ポリシー全体がショートサーキットして許可します。`OPEN` PR が確認されると、2つの独立したプローブが実行されます： +**イベント:** Stop +**デフォルト:** 現在のブランチがベースブランチにクリーンにマージできない場合、停止を拒否します。このポリシーはまず GitHub 上でブランチに `OPEN` な PR があることを確認します。PR がない場合、強制すべきマージターゲットがないため、ポリシー全体がショートサーキットして許可します。`OPEN` な PR が確認されると、2つの独立したプローブが実行されます： -1. **ローカル** — `git merge-tree --write-tree --name-only origin/ HEAD`。コンフリクトが発生した場合、deny メッセージには Claude が正確に何を解決すべきかがわかるよう、コンフリクトしたファイル名が記載されます。 -2. **GitHub** — プレチェックですでに取得した `gh pr view --json mergeable,state` の結果を再利用します。古いローカルの `origin/` が見逃すコンフリクト（例：最後のフェッチ以降に誰かが `main` にコンフリクトする PR をマージした場合）を検出します。`CONFLICTING` の結果は拒否します。`UNKNOWN` の結果も拒否し、GitHub が再計算する間に約10秒待ってから再度停止を試みる前に再チェックするよう Claude に指示します。これにより GitHub が再計算する間の偽陰性を防ぎます。 +1. **ローカル** — `git merge-tree --write-tree --name-only origin/ HEAD`。コンフリクト時、deny メッセージにコンフリクトしたファイルが明記されるため、Claude は何を解決すべきかを正確に把握できます。 +2. **GitHub** — プレチェックですでに取得した `gh pr view --json mergeable,state` の結果を再利用します。古いローカルの `origin/` が見逃すコンフリクトを検出します（例：最後のフェッチ以降に誰かが `main` にコンフリクトする PR をマージした場合）。`CONFLICTING` の結果は拒否します。`UNKNOWN` の結果も拒否し、再度停止を試みる前に約10秒待って再チェックするよう Claude に指示します。これにより GitHub が再計算している間の偽陰性を防ぎます。 -以下の場合は完全にスキップします（許可）：`gh` がインストールされていない、ブランチに PR が存在しない、PR の状態が `OPEN` でない（例：`MERGED`、`CLOSED`）、または `gh pr view` が解析不能な出力を返した場合。`origin/` がローカルに存在しない場合や、ベースより ahead のコミットがない場合もフェールオープンします。これらの Layer 1 のフォールスルーは、許可する前にキャッシュされた PR のマージ可能性を引き続き参照します。 +以下の場合は完全にスキップ（許可）します：`gh` がインストールされていない、ブランチに PR が存在しない、PR の状態が `OPEN` でない（例：`MERGED`、`CLOSED`）、または `gh pr view` が解析不能な出力を返す。`origin/` がローカルに存在しない場合や、ベースより前にコミットがない場合もフェールオープンします（これらのレイヤー1フォールスルーはキャッシュされた PR のマージ可能性を確認してから許可します）。 **パラメーター:** @@ -811,30 +810,29 @@ Claude スタイルの同一ループリトライが必要な場合は、他の5 | `baseBranch` | `string` | `"main"` | コンフリクトをチェックするベースブランチ。 | -このポリシーには GitHub CLI（`gh`）が必要です。ポリシーはコンフリクトプローブを実行する前に `gh pr view` を使用して `OPEN` PR が存在することを確認します。`gh` がない場合、ポリシーはショートサーキットして許可します。プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。 +このポリシーには GitHub CLI（`gh`）が必要です。このポリシーはコンフリクトプローブを実行する前に `gh pr view` を使用して `OPEN` な PR の存在を確認します。`gh` がない場合、ポリシーはショートサーキットして許可します。プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。 --- ### `require-ci-green-before-stop` -**イベント:** Stop -**デフォルト:** 現在のブランチで CI チェックが失敗しているか実行中の場合に停止を拒否します。GitHub Actions ワークフロー実行とサードパーティボットチェック（例：CodeRabbit、SonarCloud、Codecov）の両方をチェックします。`skipped`、`cancelled`、`neutral` の結論は失敗としません（後者は例えば、アプリが意図的に success/failure ではなく neutral を報告する外部コントリビューターの PR に対する Socket Security アラートをカバーします）。すべてのチェックが通過した場合は情報メッセージを返します。 +**イベント:** Stop +**デフォルト:** 現在のブランチで CI チェックが失敗しているか実行中の場合、停止を拒否します。GitHub Actions のワークフロー実行とサードパーティのボットチェック（例：CodeRabbit、SonarCloud、Codecov）の両方を確認します。`skipped`、`cancelled`、`neutral` の結論は失敗として扱いません（後者は例えば Socket Security の外部コントリビューターの PR に対するアラートをカバーします。アプリが success/failure ではなく intentionally neutral を報告する場合）。すべてのチェックが通過した場合は情報メッセージを返します。 パラメーターなし。 -このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）のインストールと認証が必要です。 -Actions ワークフロー実行および Checks API への読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェールオープンし、その理由を Claude に報告します。 +このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ認証されている必要があります。Actions のワークフロー実行と Checks API への読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェールオープンし、その理由を Claude に報告します。 --- --- -## 個々のポリシーの無効化 +## 個別ポリシーの無効化 -設定の `enabledPolicies` から特定のポリシーを削除するか、ダッシュボードの Policies タブでオフに切り替えます。 +設定ファイルの `enabledPolicies` から特定のポリシーを削除するか、ダッシュボードの「Policies」タブでオフにします。 ```json { @@ -845,4 +843,4 @@ Actions ワークフロー実行および Checks API への読み取りアクセ } ``` -`enabledPolicies` にリストされていないポリシーは、`policyParams` にエントリが存在しても実行されません。 \ No newline at end of file +`enabledPolicies` にリストされていないポリシーは、`policyParams` にエントリが存在していても実行されません。 \ No newline at end of file diff --git a/docs/ja/cli/audit.mdx b/docs/ja/cli/audit.mdx index ecfaa2f4..65fa4f2f 100644 --- a/docs/ja/cli/audit.mdx +++ b/docs/ja/cli/audit.mdx @@ -1,19 +1,19 @@ --- title: 過去のセッションを監査する（ベータ版） -description: "過去のトランスクリプトから、エージェントが無駄または危険な操作を行った頻度を集計する" +description: "過去のトランスクリプトを対象に、エージェントが無駄・危険な操作をどれだけ行ったかを集計する" --- - **ベータ機能。** 初期フィードバックを収集しながら提供しています。 - 検出器のカタログおよびレポートの形式は、次の安定版リリース前に変更される可能性があります。 - 問題があればIssueを作成してください。 + **ベータ機能。** 本機能は初期フィードバック収集のためベータとして提供しています。 + 次の安定版リリース前に、検出器のカタログやレポート形式が変更される可能性があります。 + 不具合を見つけた場合は Issue を開いてください。 -この監査機能は、過去のエージェントCLIトランスクリプトを failproofai のポリシーエンジンに通して再生し、**`/audit` ダッシュボードページ**に共有可能なビジュアルレポートを表示します。レポートにはエージェントのアーキタイプ、0〜100のスコア、そしてどのポリシーが何を検出できたかが詳しく示されます。 +監査機能は、過去のエージェント CLI トランスクリプトを failproofai のポリシーエンジンで再実行し、共有可能なビジュアルレポートを **`/audit` ダッシュボードページ** に表示します。表示内容はエージェントのアーキタイプ、0〜100 のスコア、そして各ポリシーが何を検出したかの詳細です。 ## 実行方法 -3通りの起動方法があり、いずれも同じ `/audit` レポートに到達します。 +3 つの起動方法があります。どれも同じ `/audit` レポートに到達します。 @@ -33,84 +33,86 @@ failproofai - `npx -y failproofai audit` は failproofai を取得してスキャンを実行し、ダッシュボードを自動的に開きます。事前インストールは不要です。 + `npx -y failproofai audit` は failproofai を取得し、スキャンを実行して、ダッシュボードを自動で開きます。事前インストールは不要です。 - - `failproofai audit` はターミナルでスキャンを実行し、完了後に - `localhost:8020/audit` を自動的に開きます。 + + `failproofai audit` はターミナルでスキャンを実行し、完了すると自動的に + `localhost:8020/audit` を開きます。 - `failproofai` を実行してナビゲーションバーの **Audit**（PoliciesとProjectsの間）をクリックするか、`/audit` を直接開いてください。 + `failproofai` を実行してナビバーの **Audit**（Policies と Projects の間）をクリックするか、`/audit` を直接開いてください。 - `failproofai audit -h`（または `--help`）を実行すると使い方が確認できます。監査は**完全オフライン**で動作し、アカウントもネットワーク接続も不要です。`Ctrl+C` で停止するまでダッシュボードは提供され続けます。 + `failproofai audit -h`（または `--help`）を実行すると使い方が確認できます。監査は **完全オフライン** で動作し、アカウントやネットワーク接続は不要です。`Ctrl+C` で停止するまでダッシュボードは起動し続けます。 -ダッシュボードはこのマシン上の過去のエージェントCLIトランスクリプト（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi）をスキャンし、failproofai が防ぐように設計した操作（環境変数チェック、フォースプッシュ、冗長な `cd ` プレフィックス、スリープポーリングループ、直前に編集したファイルの再読み込みなど）をエージェントがどのくらいの頻度で行っているかを報告します。 +ダッシュボードはこのマシン上の過去のエージェント CLI トランスクリプト（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi）をスキャンし、failproofai が防止するよう設計された操作（環境変数チェック、強制プッシュ、不要な `cd ` プレフィックス、スリープポーリングループ、編集直後のファイルの再読み込みなど）がどれだけ発生していたかをレポートします。 -各トランスクリプトについて、すべてのツール使用イベントが39個の組み込みポリシー**および**ランタイムポリシーではまだカバーされていないパターンを検出する8個の監査専用検出器を通じて再生されます。カウントはすべてのセッションを通じてポリシー／検出器ごとに集計されます。 +トランスクリプトごとに、すべてのツール使用イベントが 39 個の組み込みポリシー **および** ランタイムポリシーではまだカバーされていないパターンを検出する 8 個の監査専用検出器で再実行されます。ポリシー・検出器ごとのカウントはすべてのセッションにわたって集計されます。 -## 取得できる情報 +## 得られる情報 -`/audit` ページは1画面で共有可能な**ポスター**と、その下に4つのセクションで構成されています。 +`/audit` ページは 1 画面の共有可能な **ポスター** と、折り畳まれた 4 つのセクションで構成されます。 -1. **ポスター** — エージェントのアイデンティティを一目で把握できます。**アーキタイプ**（8種類のうちの1つ：`optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、ペルソナキーワード、そのアーキタイプの希少性、および階層バンド付きの**0〜100スコア**（`S`〜`bottom tier`）が表示されます。XやLinkedInに投稿したり、PNGとしてダウンロードして共有できます。 -2. **`// strengths`** — エージェントがすでに上手くできていること。スキャンの実際の数値（例：クリーンなツールコール率、`0`回のmainへのプッシュ試行）として表示され、関連するポリシーのレコードがクリーンな場合のみ表示されます。 -3. **`// quirks`** — 見逃したもの：failproofai が検出したはずの動作をランキング形式の表で表示します。*いつ*最後に発生したか、*何が見逃された*か（および本来ブロックしたはずの組み込みポリシー）、その*重大度*、および*発生頻度*（`new` / `recurring` / `N× seen`）が確認できます。 -4. **`// how to improve`** — 推奨される修正リスト：コピー＆ペーストで使える `failproofai policy add ` が各ポリシーに1行ずつ表示され、すべての推奨事項を一括で有効にする **install all** ボタンと、適用した場合の**予測スコア**も確認できます。 -5. **`// come back better`** — 習慣化のサポート：再監査のメール**リマインダー**（`3d` / `7d` / `14d` / `30d`）の設定または今すぐ再監査の実行、および**友人への招待**（failproof.ai から送信され、あなたにCcされます）ができます。リマインダーと招待にはサインインが必要です。 +1. **ポスター** — エージェントの概要：**アーキタイプ**（8 種類のうちいずれか — `optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、ペルソナキーワード、そのアーキタイプの希少度、**0〜100 スコア**とティアバンド（`S` から `bottom tier` まで）。X や LinkedIn への投稿、PNG ダウンロードに対応した共有用デザインです。 +2. **`// strengths`** — スキャンの実際の数値に基づいた、エージェントがすでに優れている点（例：クリーンなツール呼び出し率、`0` 回の main へのプッシュ試行）。関連ポリシーのレコードがクリーンな場合にのみ表示されます。 +3. **`// quirks`** — 見落とされていた点：failproofai が検出できたはずの動作のランキングテーブル。*最後に発生した日時*、*何が漏れたか*（および検出・ブロックしたはずの組み込み機能）、*重大度*、*発生頻度*（`new` / `recurring` / `N× seen`）を表示します。 +4. **`// how to improve`** — 推奨される修正リスト：コピー貼り付け可能な `failproofai policy add ` を含むポリシーごとの行、すべての推奨事項を一括で有効化する **install all** ボタン、および適用した場合の **予測スコア**。 +5. **`// come back better`** — 習慣化のために：再監査の **リマインダー**（`3d` / `7d` / `14d` / `30d`）の設定または今すぐ再監査の実行、**友人への招待**（failproof.ai から送信、Cc はあなた宛）。リマインダーと招待にはサインインが必要です。 ## スケジュール監査 -**failproofaid デーモン**を実行している場合（[`failproofai config`](/ja/cli/install-policies) を参照）、スケジュールに従って自動的に監査を再実行し、バックグラウンドで `/audit` レポートを更新できます。スキャンはこのマシン上のすべてのエージェントセッショントランスクリプトの*内容*を読み込むため、**デフォルトでは無効**になっています。明示的に要求するまでタイマーでスキャンは実行されません。 +**failproofaid デーモン**を実行している場合（[`failproofai config`](/ja/cli/install-policies) 参照）、スケジュールに従って監査を自動で再実行し、バックグラウンドで `/audit` レポートを更新できます。このマシン上のすべてのエージェントセッショントランスクリプトの *内容* を読み取るため、デフォルトでは **オフ** になっています。リクエストするまでタイマーでスキャンが実行されることはありません。 -`~/.failproofai/config.toml` で有効にします： +`~/.failproofai/config.json` で有効化できます。ファイルにすでに含まれている設定の隣に `audit` キーを追加してください。 -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | キー | 意味 | |---|---| -| `auto` | `true` でスケジュールスキャンが有効になります。未設定、`false`、`"yes"` などはすべて無効です。 | -| `interval_days` | スキャンの間隔（日数）。1〜90の範囲に制限され、`0`、負の値、または数値以外の値は `7` にフォールバックします。 | +| `auto` | `true` でスケジュールスキャンを有効化。それ以外（未設定、`false`、`"yes"` など）はオフ。 | +| `interval_days` | スキャン間隔の日数。1〜90 の範囲にクランプされ、`0`・負の値・数値以外は `7` にフォールバック。 | -- スケジュールは**ウォールクロック**ベースのため、サスペンドや再起動後も維持されます。期限を過ぎてスリープしていたラップトップは起動時に**1回**だけ実行され、積み残しは発生しません。 -- 各実行は独立した低優先度（`nice 19`）プロセスです。ツールコールへの応答を維持するため、デーモンのフックパスは常に解放されています。 -- `failproofai audit` またはダッシュボードの再実行がすでに進行中の場合、スキャンはスキップされ、失敗ではなく後で再試行されます。 -- 進捗は `~/.failproofai/state/audit-schedule.json`（最終実行日時、次回予定日時）に書き込まれます。このファイルはデーモンが管理しています。スケジュールの変更は `config.toml` で行ってください。 +- スケジュールは **実時間（wall-clock）ベース** のため、サスペンドや再起動後も維持されます。予定時刻を過ぎてスリープ状態だったノート PC は、起動時に **1 回** だけ実行します（バックログの蓄積なし）。 +- 各実行は独立した低優先度プロセス（`nice 19`）です。デーモンのフックパスには影響せず、ツール呼び出しへの応答は常に確保されます。 +- `failproofai audit` またはダッシュボードの再実行がすでに進行中の場合、スキャンはスキップされます。失敗として扱われるのではなく、しばらく後に再試行されます。 +- 進捗は `~/.failproofai/state/audit-schedule.json`（最終実行日時・次回予定日時）に書き込まれます。このファイルはデーモンが管理します。ペースの変更は `config.json` で行ってください。 -古いバージョンの failproofai でセットアップしたマシンでこれを有効にした場合は、 -`failproofai config` を一度実行してください。デーモンのサービス定義にCLIを起動するための追加エントリが必要であり、このコマンドの実行によって更新されます。 +古いバージョンの failproofai でセットアップしたマシンでこれを有効化した場合は、一度 `failproofai config` を実行してください。デーモンのサービス定義に CLI を起動するためのエントリが 1 つ追加で必要であり、そのリフレッシュはこのコマンドの一部として行われます。 ## 監査専用検出器 -これらはリアルタイムではまだ適用されていない「非効率な動作」パターンを検出します。監査中にのみ実行され、ライブのツールコールをブロックすることはありません。 +リアルタイムでは（まだ）強制されていない「非効率な動作」パターンを検出します。監査中のみ実行され、ライブのツール呼び出しをブロックすることはありません。 | 検出器 | カウント対象 | |---|---| -| `redundant-cd-cwd` | コマンドがすでに `cwd` で実行されているにもかかわらず `cd && …` で始まるBashコマンド。 | -| `prefer-edit-over-read-cat` | 単一のソースファイルに対する `cat` / `head` / `tail` / `less` / `more` — `Read` ツールを使用すべきケース。 | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` によるインプレース編集 — `Edit` ツールを使用すべきケース。 | -| `prefer-write-over-heredoc` | ヒアドキュメントや複数行の `echo > file` によるファイル書き込み — `Write` ツールを使用すべきケース。 | -| `sleep-polling-loop` | 長時間の `sleep N`（30秒以上）や `while …; sleep …; done` によるポーリングループ。 | -| `find-from-root` | `find /`、`find /home`、`find /usr` など — `cwd` を起点にスコープを絞るべきケース。 | -| `git-commit-no-verify` | フックをスキップする `git commit … --no-verify` / `-n`。 | -| `reread-after-edit` | 同一セッション内で直前に `Edit` / `Write` したファイルへの `Read`。 | +| `redundant-cd-cwd` | すでに `cwd` でコマンドが実行されているにもかかわらず `cd && …` から始まる Bash コマンド。 | +| `prefer-edit-over-read-cat` | 単一のソースファイルへの `cat`/`head`/`tail`/`less`/`more` — `Read` ツールを使用すること。 | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` によるインプレース編集 — `Edit` ツールを使用すること。 | +| `prefer-write-over-heredoc` | ヒアドキュメント / 複数行 `echo > file` によるファイル書き込み — `Write` ツールを使用すること。 | +| `sleep-polling-loop` | 長い `sleep N`（30 秒以上）または `while …; sleep …; done` のポーリングループ。 | +| `find-from-root` | `find /`、`find /home`、`find /usr` など — `cwd` を起点としてスコープを絞ること。 | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n` によるフックのスキップ。 | +| `reread-after-edit` | 同一セッション内で直前に `Edit`/`Write` したファイルへの `Read`。 | ## キャッシュ -- **トランスクリプトごとのキャッシュ**は `~/.failproofai/cache/audit/.json` に保存され、`(mtime, size, engineVersion, detectorVersion)` をキーとします。トランスクリプトまたはポリシー／検出器のコードが変更されると自動的に無効化されます。各エントリには `cachedAt` タイムスタンプが**TTLメタデータ**として保存されます（キャッシュキーには含まれません）。**7日**を超えたエントリは読み取り時に拒否されるため、古い結果が進化する検出器の意図を超えて存続することはありません。 -- **全体結果のキャッシュ**は `~/.failproofai/audit-dashboard.json`（モード0600）に保存されます。ページに遷移したときに再実行なしでダッシュボードを即座に表示できます。こちらも**7日のTTL**を超えると読み取り時に拒否され、`/audit` は空の状態にフォールバックして新規実行を促します。レポート下部の `[ re-audit now ]` をクリックして更新してください。再監査は `noCache: true` で送信されるため、トランスクリプトごとのキャッシュを迂回してすべてのトランスクリプトを再スキャンします（キャッシュ結果を返すのではなく）。実行中は上部の固定ストリップで進捗がストリーミング表示され、成功時は結果がその場で入れ替わります（ページリロードなし。再監査が失敗した場合は以前のレポートが保持されます）。 +- **トランスクリプトごとのキャッシュ** は `~/.failproofai/cache/audit/.json` にあり、`(mtime, size, engineVersion, detectorVersion)` をキーとします。トランスクリプトまたはポリシー・検出器のコードが変更されると自動的に無効化されます。各エントリには `cachedAt` タイムスタンプが **TTL メタデータ**（キャッシュキーの一部ではない）として保存されており、**7 日**より古いエントリは読み込み時に拒否されます。これにより、古い結果が進化した検出器の意図を超えて長く残ることを防ぎます。 +- **全体結果キャッシュ** は `~/.failproofai/audit-dashboard.json`（モード 0600）にあります。ナビゲーション時に再実行なしでダッシュボードを即座にレンダリングできます。こちらも **7 日 TTL** を超えると読み込み拒否されます。その場合 `/audit` は空の状態にフォールバックし、新しい実行を促します。レポート下部の `[ re-audit now ]` をクリックして更新してください。再監査は `noCache: true` を送信するため、トランスクリプトごとのキャッシュをバイパスし、キャッシュ結果を返すのではなくすべてのトランスクリプトを再スキャンします。実行中は上部のスティッキーストリップに進捗が表示され、成功時はページをリロードせずに結果がその場で入れ替わります（再監査に失敗した場合は前のレポートが維持されます）。 ## 注意事項 -- **変更なし。** 監査は読み取り専用モードで再生されます。`warn-repeated-tool-calls` はセッションごとのサイドカーが変更されてしまうためスキップされます。 -- **ワークフローポリシーはスキップされます。** `require-*-before-stop` ポリシーは `Stop` イベントと `execSync` によるライブのgit状態に対してのみ動作します。「2025年の時点で何が起きていたか」を意味のある形で解釈できないため、監査カウントには含まれません。 -- **カスタムポリシーはスキップされます。** ユーザーが設定したカスタムフックは再生されません（元のセッション以降に変更されている可能性があるため）。 \ No newline at end of file +- **変更なし。** 監査は読み取り専用モードで再実行されます。`warn-repeated-tool-calls` はスキップされます。これを実行するとセッションごとのサイドカーが変更されてしまうためです。 +- **ワークフローポリシーはスキップ。** `require-*-before-stop` ポリシーは `Stop` イベントと `execSync` を組み合わせてライブの git 状態に対して発火するため、「2025 年に何が起きていたか」という意味のある解釈ができません。そのため監査カウントには表示されません。 +- **カスタムポリシーはスキップ。** ユーザー定義のカスタムフックは再実行されません（元のセッション以降に変更されている可能性があるため）。 \ No newline at end of file diff --git a/docs/ja/cli/dashboard.mdx b/docs/ja/cli/dashboard.mdx index 92941ae2..95221c14 100644 --- a/docs/ja/cli/dashboard.mdx +++ b/docs/ja/cli/dashboard.mdx @@ -1,6 +1,6 @@ --- -title: セッションの表示 -description: "ダッシュボードを起動してエージェントセッションの確認とポリシーの管理を行う" +title: セッションを表示する +description: "ダッシュボードを起動してエージェントセッションを閲覧し、ポリシーを管理する" --- ```bash @@ -16,7 +16,7 @@ failproofai | `--port ` | リッスンするポート番号（デフォルト: `8020`） | | `--allowed-origins ` | 開発リソースへのアクセスを許可するホスト/IPのカンマ区切りリスト | -デフォルト以外の Claude プロジェクトフォルダをダッシュボードに指定する場合は、起動時に `CLAUDE_PROJECTS_PATH` 環境変数を設定してください。 +デフォルト以外の Claude プロジェクトフォルダをダッシュボードに指定するには、起動時に `CLAUDE_PROJECTS_PATH` 環境変数を設定してください。 ## 使用例 @@ -24,6 +24,6 @@ failproofai # 別のポートで起動する failproofai --port 9000 -# 環境変数でカスタムの Claude プロジェクトパスを指定する +# 環境変数でカスタムの Claude プロジェクトパスを使用する CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/ja/cli/environment-variables.mdx b/docs/ja/cli/environment-variables.mdx index 14c7b049..f9117f93 100644 --- a/docs/ja/cli/environment-variables.mdx +++ b/docs/ja/cli/environment-variables.mdx @@ -1,63 +1,66 @@ --- title: 環境変数 -description: "環境変数を使用して failproofai の動作を設定する" +description: "環境変数を使って failproofai の動作を設定する" --- ## ダッシュボード | 変数 | 説明 | |----------|-------------| -| `PORT` | ダッシュボードのポート（デフォルト: `8020`） | +| `PORT` | ダッシュボードのポート番号（デフォルト: `8020`） | | `CLAUDE_PROJECTS_PATH` | Claude Code のプロジェクトフォルダの検索場所を上書きする | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 非表示にするダッシュボードページをカンマ区切りで指定 | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | 開発リソースへのアクセスを許可するホスト/IP。`--allowed-origins` と同等。 | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 非表示にするダッシュボードページをカンマ区切りで指定する | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | 開発リソースへのアクセスを許可するホスト/IP。`--allowed-origins` と同じ。 | ## ログ | 変数 | 説明 | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | サーバーのログレベル（デフォルト: `warn`） | -| `FAILPROOFAI_HOOK_LOG_FILE` | カスタムフックログファイルのパス。`true` を指定するとデフォルトのパス（`~/.failproofai/logs/hooks.log`）が使用される | +| `FAILPROOFAI_HOOK_LOG_FILE` | フックログファイルのカスタムパス。`true` を指定するとデフォルトパス（`~/.failproofai/logs/hooks.log`）を使用する | -## テレメトリ +## テレメトリー -failproofai はデフォルトで匿名の使用状況テレメトリを報告します。無効にする方法は2つあり、より制限の厳しい設定が優先されます。つまり、環境変数によって設定ファイルで無効化された機能を再有効化することはできません。 +failproofai はデフォルトで匿名の利用状況テレメトリーを報告します。無効にする方法は2つあり、より制限が厳しい設定が優先されます。つまり、環境変数によって設定ファイルで無効化した機能を再有効化することはできません。 | 変数 | 説明 | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 現在のプロセスにおける匿名使用状況テレメトリを無効化する | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | このプロセスの匿名利用状況テレメトリーを無効にする | -マシン全体で恒久的に無効化するには、`~/.failproofai/config.toml` に以下を追加してください: +マシン全体で永続的に無効にするには、`~/.failproofai/config.json` に以下を追加してください： -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -**failproofaid デーモン**を実行している場合は、設定ファイルを使用してください。 -デーモンはシステムスコープのサービスであり、そのプロセス環境にはシェルからエクスポートされた変数が含まれません。そのため `FAILPROOFAI_TELEMETRY_DISABLED` はデーモンには届きません。`[telemetry] enabled = false` はCLIとデーモンの両方で読み込まれます。 +**failproofaid デーモン**を実行している場合は、設定ファイルの方法を使用してください。 +デーモンはシステムスコープのサービスであり、シェルからエクスポートされた環境変数は含まれません。そのため、`FAILPROOFAI_TELEMETRY_DISABLED` はデーモンに届きません。`[telemetry] enabled = false` はCLIとデーモンの両方で読み取られます。 -デーモンが報告するのは、自身の**ライフサイクル**に関する情報のみです。具体的には、起動時（および前回の実行が正常終了したかどうか）、停止時、評価ワーカーの起動または再起動時、コレクタータスクの失敗時、クラウドポリシーの取得結果などです。これらには低カーディナリティの値とカウントのみが含まれ、ファイルパス、コマンド、ポリシー、プロンプト、トランスクリプトから読み取られた情報は一切含まれません。ツール呼び出しごとのイベントも存在しません。 +デーモンが報告するのは、固有の**ライフサイクル**イベントのみです。具体的には、起動時（および前回の実行が正常終了したかどうか）、停止時、評価ワーカーの起動または再起動時、コレクタータスクの失敗時、クラウドポリシーの取得結果などです。これらは低カーディナリティの値とカウントのみを含み、ファイルパス・コマンド・ポリシー・プロンプト・トランスクリプトから読み取られた内容は一切含まれません。ツール呼び出し単位のイベントもありません。 ## 認証 | 変数 | 説明 | |----------|-------------| -| `FAILPROOF_API_URL` | ダッシュボードの認証ダイアログで使用するAPIサーバーのベースURLを上書きする。デフォルトは `https://api.befailproof.ai`。ローカルのAPIサーバーを使用する場合は `http://localhost:8080`（または該当するアドレス）に設定する。 | +| `FAILPROOF_API_URL` | ダッシュボードの認証ダイアログで使用するAPIサーバーのベースURLを上書きする。デフォルトは `https://api.befailproof.ai`。ローカルのAPIサーバーを使用する場合は `http://localhost:8080`（または該当するアドレス）を設定する。 | | `FAILPROOFAI_AUTH_DIR` | `auth.json` の保存場所を上書きする（デフォルト: `~/.failproofai`）。主に独立したテスト環境で使用する。 | ## 初回起動時のプロンプト | 変数 | 説明 | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | `failproofai` を初めて単独で実行した際に表示されるポリシーのインストールを提案するプロンプトをスキップする | +| `FAILPROOFAI_NO_FIRST_RUN=1` | `failproofai` を初めて単体で実行した際に表示されるポリシーインストールの案内をスキップする | ## LLM（ポリシー評価用） | 変数 | 説明 | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | LLM APIエンドポイント（デフォルト: `https://api.openai.com/v1`） | -| `FAILPROOFAI_LLM_API_KEY` | LLMを使用したポリシー向けのAPIキー | +| `FAILPROOFAI_LLM_BASE_URL` | LLM APIのエンドポイント（デフォルト: `https://api.openai.com/v1`） | +| `FAILPROOFAI_LLM_API_KEY` | LLMを活用したポリシー用のAPIキー | | `FAILPROOFAI_LLM_MODEL` | モデル名（デフォルト: `gpt-4o-mini`） | \ No newline at end of file diff --git a/docs/ja/cli/hook.mdx b/docs/ja/cli/hook.mdx index 5b66ee72..f877c048 100644 --- a/docs/ja/cli/hook.mdx +++ b/docs/ja/cli/hook.mdx @@ -1,5 +1,5 @@ --- -title: フックハンドラー（内部） +title: フックハンドラ（内部） description: "各ツールイベントで Claude Code が呼び出すサブプロセス" --- @@ -7,24 +7,24 @@ description: "各ツールイベントで Claude Code が呼び出すサブプ failproofai --hook ``` -これは `failproofai policies --install` によって Claude Code の `settings.json` に登録されるコマンドです。通常、直接呼び出す必要はありません。 +これは `failproofai policies --install` によって Claude Code の `settings.json` に登録されるコマンドです。通常、直接呼び出すことはありません。 -stdin から JSON ペイロードを読み込み、有効なすべてのポリシーを評価し、判定結果を示す終了コードで終了します： +stdin から JSON ペイロードを読み込み、有効なすべてのポリシーを評価し、判定結果を示す終了コードで終了します。 -| 終了コード | 判定 | 効果 | -|-----------|----------|--------| +| 終了コード | 判定 | 動作 | +|-----------|------|------| | `0` | `allow` | アクションを許可する | -| `1` | `deny` | アクションをブロックする — Claude は拒否理由を受け取る | +| `1` | `deny` | アクションをブロックする — Claude には拒否理由が通知される | | `2` | `instruct` | Claude のコンテキストにガイダンスを注入する | ### サポートされているイベントタイプ | カテゴリ | イベント | -|----------|--------| +|----------|---------| | **ツール実行** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **セッションライフサイクル** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **ユーザーインタラクション** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **サブエージェント & タスク** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **サブエージェントとタスク** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **設定** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **ファイルシステム** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **コンテキスト** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/ja/cli/install-policies.mdx b/docs/ja/cli/install-policies.mdx index 272152ad..46f17f3b 100644 --- a/docs/ja/cli/install-policies.mdx +++ b/docs/ja/cli/install-policies.mdx @@ -18,16 +18,16 @@ failproofai policies --install [policy-names...] [options] | `--cli claude\|codex\|copilot` | インストール対象のエージェント CLI。スペース区切りで複数指定可能（例: `--cli claude codex copilot`）または繰り返し指定。省略するとインストール済み CLI を自動検出してプロンプトを表示。 | | `--scope user` | ユーザースコープの設定ファイルにインストール（Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`）。デフォルト。 | | `--scope project` | プロジェクトスコープの設定ファイルにインストール（Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`）。 | -| `--scope local` | Claude のみ — `/.claude/settings.local.json` にインストール。Codex および Copilot には `local` スコープがありません。 | +| `--scope local` | Claude のみ — `/.claude/settings.local.json` にインストール。Codex と Copilot には `local` スコープは存在しません。 | | `--custom ` / `-c` | カスタムフックポリシーを含む JS ファイルへのパス | ## 動作 -- **ポリシー名の未指定** — ポリシーを選択するインタラクティブなプロンプトを表示 -- **特定の名前を指定** — 指定したポリシーを有効化（既に有効なポリシーに追加） -- **`all`** — 利用可能なすべてのポリシーを有効化 +- **ポリシー名を指定しない場合** — インタラクティブなプロンプトが表示され、ポリシーを選択できます +- **特定の名前を指定した場合** — 指定したポリシーを有効化します（既に有効なポリシーに追加されます） +- **`all`** — 利用可能なすべてのポリシーを有効化します -インストールは追記型です。`--install` を再度実行しても既存のポリシーは削除されず、新しいポリシーが追加されます。 +インストールは追加式です。`--install` を再度実行すると、既存のポリシーを削除せずに新しいポリシーが追加されます。 ## 使用例 @@ -41,17 +41,17 @@ failproofai policies --install block-sudo sanitize-api-keys --scope project # すべてのポリシーを一括で有効化 failproofai policies --install all -# カスタムポリシーファイルを使用してインストール +# カスタムポリシーファイルと共にインストール failproofai policies --install --custom ./my-policies.js -# OpenAI Codex 向けにインストール（プロジェクトスコープ） +# OpenAI Codex 用にインストール（プロジェクトスコープ） failproofai policies --install --cli codex --scope project -# GitHub Copilot CLI（ベータ）向けに現在のプロジェクトへインストール +# 現在のプロジェクト向けに GitHub Copilot CLI（ベータ）用にインストール failproofai policies --install --cli copilot --scope project -# 3 つの CLI すべてに一括でインストール +# 3つの CLI すべてに一括でインストール failproofai policies --install --cli claude codex copilot ``` -`--custom ` を指定した場合、ファイルは即座に検証されます。少なくとも 1 回 `customPolicies.add()` を呼び出している必要があります。解決されたパスは `customPoliciesPath` として `policies-config.json` に保存されます。 \ No newline at end of file +`--custom ` を指定した場合、ファイルはその場で検証されます。少なくとも1回 `customPolicies.add()` を呼び出している必要があります。解決されたパスは `policies-config.json` に `customPoliciesPath` として保存されます。 \ No newline at end of file diff --git a/docs/ja/cli/list-policies.mdx b/docs/ja/cli/list-policies.mdx index 4b03b5e6..8f0534c4 100644 --- a/docs/ja/cli/list-policies.mdx +++ b/docs/ja/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- -title: ポリシー一覧 -description: "有効なポリシー、そのパラメータ、カスタムポリシーを確認する" +title: ポリシー一覧の表示 +description: "有効なポリシー、そのパラメーター、およびカスタムポリシーを確認する" --- ```bash failproofai policies ``` -すべてのポリシーとそのステータス、設定済みパラメータ、カスタムポリシーを表示します。 +すべてのポリシーをステータス、設定済みパラメーター、カスタムポリシーとともに表示します。 ## 出力例 @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -`policyParams` 内の未知のキーはここでフラグが立てられるため、タイポを早期に発見できます。 \ No newline at end of file +`policyParams` に未知のキーが含まれている場合はここに表示されるため、タイポを早期に発見できます。 \ No newline at end of file diff --git a/docs/ja/cli/migrate.mdx b/docs/ja/cli/migrate.mdx new file mode 100644 index 00000000..d5352077 --- /dev/null +++ b/docs/ja/cli/migrate.mdx @@ -0,0 +1,86 @@ +--- +title: ホームディレクトリのマイグレーション +description: "~/.failproofai を現在のバージョンが対応するレイアウトに更新する。実行前に変更内容を確認することも可能" +--- + +```bash +failproofai migrate --dry-run # 実行計画を表示するだけで何も変更しない +failproofai migrate # 実際に実行する +``` + +このコマンドを直接入力する必要があるケースはほとんどありません。アップグレード後の最初のコマンド実行時に自動で動作し、[`failproofai update`](/ja/cli/update) にも含まれています。直接使う場面があるとすれば、実行前に計画を確認したいときや、マイグレーションを単独で実行したいときです。 + +## バージョンではなくレイアウトを基準にする + +`~/.failproofai/VERSION` には**レイアウト**番号が記録されています。これはリリースバージョンではなく、ディレクトリの構造を表す番号です。マイグレーションはこの番号を基準にしているため、大きなバージョンの飛び越えでも効率よく処理できます。 + +- npm のバージョンはリリースのたびに変わり、2 つのレイアウト間に数十のバージョンが存在することもあります。 +- そのため、**レイアウトの変更がなく** 30 リリース分スキップしたマシンは、マイグレーションを **1 回も** 実行しません（30 回の無操作も不要です）。 +- 複数のレイアウトを一度にスキップした場合は、各ステップが順番に実行されます。各ステップは自分の前後のレイアウトだけを把握していれば十分です。 + +これが重要な理由は、npm がインストール済みパッケージを自動で更新できないためです。あるバージョンに何ヶ月も留まったあと、複数のレイアウトを一気に飛び越えるというのは、例外的なケースではなく通常のケースです。 + +## ドライラン + +`--dry-run` を指定すると、実行される予定のステップチェーンと事前にバックアップされるファイルが表示されます。マイグレーション、バックアップ、記録のいずれも一切行われません。 + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## 引き継がれるものと再構築されるもの + +ホームディレクトリ内の各パスは保持するデータの種類を宣言しており、それによってマイグレーション時に削除可能かどうかが決まります。ルールは次のとおりです。**派生データや再取得可能なデータは削除してよい。ユーザーが入力したもの、未送信のもの、マシンを識別するものは引き継ぐ。** + +| 引き継がれるもの | 再構築または再取得されるもの | +|---|---| +| `config.json` — 設定、`daemon.configured`、追加のキャプチャパス | 監査キャッシュ | +| `credentials.json` — クラウド登録情報 | クラウド管理のデプロイメント（次回のポーリング時に再取得してダイジェスト検証される） | +| `policies-config.json` — ポリシーの選択とパラメータ | デーモンの一時状態 | +| `policies/` — ユーザー独自のポリシーファイルとそれがインポートするヘルパー | | +| `hook-activity/` — ダッシュボードが参照する判定ログ | | +| アップロードキューに残っている未送信イベント | | +| `cursors/` — コレクターのウォーターマーク | | +| `bin/` 内のデーモンバイナリ | | + + + 未送信イベントは削除せずに引き継ぎます。失われると取り返しがつかないからです。コレクターのウォーターマークはすでにスプール内のデータを過ぎた位置にあるため、そのトランスクリプトの範囲を再度読み取ることはできません。マイグレーションはデーモンに対して、完了後すぐにスプール内のデータを送信するよう要求するため、通常は引き継ぐものが残っていない状態になります。 + + +`config.json`、`credentials.json`、`policies-config.json` に**新しい**バージョンが書き込んだキーは、古いバージョンで読み込んでも削除されずに保持されます。 + +## マイグレーションが残す記録 + +``` +~/.failproofai/migrations/ + applied.json ステップごとのエントリ: レイアウト、CLI、タイムスタンプ、所要時間、結果 + backup-layout/ 最初のステップ実行前に取得した、置き換え不可能なファイルのコピー +``` + +`applied.json` は「このマシンで実際に何が行われたか」という疑問に答えるためのものです。アップグレード後に何か問題が起きたとき、最初に確認すべきファイルです。バグレポートには必ず添付してください。 + +バックアップはディレクトリ全体のコピーではなく、意図的に小さく保たれています。設計上、マイグレーションは置き換え不可能なものを削除しません。そのため、保険をかける価値があるのは**ステップの不具合**であり、その不具合が影響するのはこの少数のファイルに限られます。 + +## ステップが失敗した場合 + +そこでチェーンは停止します。`VERSION` が更新されるのは、ステップが正常に完了した場合のみです。ホームは古いレイアウトのまま残り、次のコマンド実行時にリトライされます。部分的なマイグレーションで最新とマークされることはありません。失敗したステップは `"ok": false` として `applied.json` に記録され、バックアップは取得された場所にそのまま残ります。 + +## 新しいホームは拒否され、マイグレートされない + +`~/.failproofai/` が現在実行している failproofai より**新しい**バージョンによって書き込まれていた場合、コマンドは停止し、アップグレードを促すメッセージを表示します。そのデータは問題なく、新しい CLI で読み取ることができます。「前のバージョンへの適用」というものは存在せず、リセットすると復元可能なデータが失われます。 + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +デーモンも同じルールを適用します。`failproofaid` は対応していないレイアウトに対しては起動を拒否します。移動されたパスへの読み書きを試みる代わりに、起動しないという選択をします。 \ No newline at end of file diff --git a/docs/ja/cli/remove-policies.mdx b/docs/ja/cli/remove-policies.mdx index 86c8d113..17e2293d 100644 --- a/docs/ja/cli/remove-policies.mdx +++ b/docs/ja/cli/remove-policies.mdx @@ -1,6 +1,6 @@ --- title: ポリシーのアンインストール -description: "Claude Code の settings.json からフックエントリを削除する" +description: "Claude Code の設定からフックエントリを削除する" --- ```bash @@ -23,21 +23,21 @@ Claude Code の `settings.json` から failproofai フックエントリを削 ## 動作 -- **ポリシー名を指定しない場合** — 設定ファイルからすべての failproofai フックエントリを削除します -- **特定の名前を指定した場合** — 該当ポリシーを無効化しますが、フックはインストールされたままにします +- **ポリシー名なし** - 設定ファイルからすべての failproofai フックエントリを削除 +- **特定の名前を指定** - 該当ポリシーを無効化しつつ、フックはインストール済みの状態を維持 ## 使用例 ```bash -# すべてのフックをグローバルから削除 +# グローバルからすべてのフックを削除 failproofai policies --uninstall -# 特定のポリシーを無効化（フックはインストールされたまま） +# 特定のポリシーを無効化（フックはインストール済みを維持） failproofai policies --uninstall block-sudo # すべてのスコープからフックを削除 failproofai policies --uninstall --scope all -# カスタムポリシーのパスをクリア +# カスタムポリシーパスをクリア failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/ja/cli/update.mdx b/docs/ja/cli/update.mdx new file mode 100644 index 00000000..6e39d05c --- /dev/null +++ b/docs/ja/cli/update.mdx @@ -0,0 +1,64 @@ +--- +title: アップグレード後の更新 +description: "npm では対応できないアップグレードの後半部分を完了する: ホームの移行とデーモンの同期" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +アップグレードはこれだけです。`npm` が CLI を置き換え、`failproofai update` が残りの処理を行います。 + +## 2つ目のコマンドが必要な理由 + +`npm install -g` が置き換えるのは CLI だけです。failproofai のインストールには、意図的にパッケージの外に置かれた2つの構成要素があり、npm を実行しても移行されません。 + +- **`~/.failproofai/`** — 設定、クラウド登録、ポリシー選択、履歴が含まれます。新しいバージョンでは構成が変わっている場合があり、その再編成は新旧両方の構造を把握しているコードで行う必要があります。 +- **`failproofaid` デーモンバイナリ** (`~/.failproofai/bin/failproofaid-`) — これは意図的に `node_modules` の外に配置されています。実行中のサービスのファイルをアップグレードで差し替えると、異なるソースからビルドされたバイナリにライブデーモンが向き直され、パッケージを削除した際にサービスが起動のたびにクラッシュループに陥るためです。 + +そのため、`npm install -g` だけを実行した状態では、CLI は新しくデーモンは古いままです。`failproofaid` は、自身が対応していないホームレイアウトに対しては起動を拒否します。これはミスマッチを黙って見過ごすのではなく、明示的にエラーを出す設計です。この2つの部分を合わせる処理が `failproofai update` です。 + +## 実行内容 + + + + `~/.failproofai/VERSION` に記録されたレイアウトを読み込み、現在のバージョンが対応する状態に引き上げるステップを実行します。通常は何も実行されません。詳細は [`failproofai migrate`](/ja/cli/migrate) を参照してください。 + + + 可能であれば npm がすでにダウンロードしたプラットフォームパッケージから取得します（ネットワーク不要）。それ以外の場合は、このバージョンのリリースアセットから取得し、使用前に SHA-256 で検証します。 + + + 稼働状態を仮定するのではなく、実際に確認します。サービスマネージャーは、プロセスをフォークした瞬間にアクティブと報告しますが、それは正常動作を意味するわけではありません。 + + + +## オプション + +| フラグ | 効果 | +|------|--------| +| `--no-daemon` | ホームの移行のみを行い、デーモンは現在のバージョンのままにします。 | + + + `--no-daemon` を使用すると、バージョンがずれたデーモンが残ります。デーモンを必須とするマシンでは、デーモンが応答できない場合にすべてのフックイベントが **フェイルクローズ** になります。移行済みのホームに対して起動を拒否したデーモンは応答できません。デーモンの更新処理も実行することを推奨します。 + + +## 問題が発生した場合 + +コマンドはゼロ以外の終了コードで終了し、どちらの処理が失敗したかを出力します。特に把握しておくべき2つのケースを紹介します。 + +- **移行ステップが完了しなかった場合。** ホームは*旧*レイアウトとしてマークされたまま残るため、次のコマンド実行時に再試行されます。部分的な移行が完了したとして現在のレイアウトとマークされることはありません。処理開始前に設定と登録のコピーが `~/.failproofai/migrations/backup-layout/` に保存されます。 +- **パスワードなしでデーモンを再起動できなかった場合。** `sudo -n` を意図的に使用しているため、進行状況の表示中にプロンプトが表示されることはありません。コマンドは自分で実行すべき正確なコマンドラインを出力します。 + + + これらの処理には対話的なセットアップウィザードは不要です。設定、クラウド登録、ポリシー選択はアップグレードを経ても保持されるため、移行済みのマシンはアップグレード前とまったく同じように動作します。これは、CI ランナー、フリートマシン、ヘッドレスゲートウェイなど、誰も直接操作しないマシンで特に重要です。 + + +## 自動化する + +`failproofai update` は非対話型であり、何も行う必要がない場合でも安全に実行できます。その場合は「移行は不要でした」と報告して終了コード 0 で終了します。プロビジョニングスクリプトや Dockerfile でアップグレードのたびに実行する使い方が想定されています。 + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +（イメージのビルド時は `--no-daemon` を使用します。この段階では再起動するサービスがまだ存在しないためです。） \ No newline at end of file diff --git a/docs/ja/cli/version.mdx b/docs/ja/cli/version.mdx index 4fe5371c..86bdc4ee 100644 --- a/docs/ja/cli/version.mdx +++ b/docs/ja/cli/version.mdx @@ -1,6 +1,6 @@ --- -title: バージョン確認 -description: "インストール済みの failproofai バージョンを表示する" +title: バージョンを確認する +description: "インストールされている failproofai のバージョンを表示する" --- ```bash @@ -9,4 +9,4 @@ failproofai --version failproofai -v ``` -インストール済みのバージョン番号を表示します。 \ No newline at end of file +インストールされているバージョン番号を表示します。 \ No newline at end of file diff --git a/docs/ja/configuration.mdx b/docs/ja/configuration.mdx index fdf5a14f..37974c53 100644 --- a/docs/ja/configuration.mdx +++ b/docs/ja/configuration.mdx @@ -1,38 +1,38 @@ --- title: 設定 -description: "設定ファイルの形式、3段階スコープシステム、マージルール" +description: "設定ファイルのフォーマット、3スコープシステム、マージルール" icon: gear --- -failproofai はJSON設定ファイルを使用して、どのポリシーを有効にするか、その動作方法、カスタムポリシーの読み込み元を制御します。設定はチームと共有しやすい設計になっています。リポジトリにコミットすれば、全開発者が同じエージェント安全ネットを利用できます。 +failproofai は JSON 設定ファイルを使って、どのポリシーを有効にするか、それらの動作、およびカスタムポリシーの読み込み元を制御します。設定はチームと共有しやすいように設計されています。リポジトリにコミットすれば、すべての開発者が同じエージェントセーフティネットを利用できます。 --- ## 設定スコープ -優先順位の高い順に評価される3つの設定スコープがあります。 +3つの設定スコープがあり、優先順位の高い順に評価されます。 -| スコープ | ファイルパス | 目的 | +| スコープ | ファイルパス | 用途 | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | リポジトリ単位の設定。バージョン管理にコミット | -| **local** | `.failproofai/policies-config.local.json` | 個人用リポジトリ単位のオーバーライド。gitignore対象 | -| **global** | `~/.failproofai/policies-config.json` | 全プロジェクト共通のユーザーレベルデフォルト | +| **project** | `.failproofai/policies-config.json` | リポジトリごとの設定。バージョン管理にコミット | +| **local** | `.failproofai/policies-config.local.json` | 個人用のリポジトリごとの上書き設定。gitignore 対象 | +| **global** | `~/.failproofai/policies-config.json` | すべてのプロジェクトに適用されるユーザーレベルのデフォルト | failproofai がフックイベントを受け取ると、現在の作業ディレクトリに存在する3つのファイルをすべて読み込んでマージします。 ### マージルール -**`enabledPolicies`** — 3つのスコープの和集合。いずれかのレベルで有効になっているポリシーはアクティブになります。 +**`enabledPolicies`** — 3つのスコープの和集合。いずれかのレベルで有効化されたポリシーはアクティブになります。 ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← 重複除去された和集合 +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← 重複排除した和集合 ``` -**`policyParams`** — 特定のポリシーのパラメータを最初に定義したスコープが完全に優先されます。ポリシーのパラメータ内の値はディープマージされません。 +**`policyParams`** — あるポリシーのパラメータを定義した最初のスコープが優先されます。ポリシーのパラメータ内での深いマージは行われません。 ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,22 +42,22 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project が優先、g ``` ```text -project: (block-sudo のエントリなし) -local: (block-sudo のエントリなし) +project: (block-sudo エントリなし) +local: (block-sudo エントリなし) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← global にフォールスルー ``` -**`customPoliciesPaths` / `customPoliciesPath`** — いずれかの形式を最初に定義したスコープが優先されます。 +**`customPoliciesPaths` / `customPoliciesPath`** — いずれかの形式を定義した最初のスコープが優先されます。 -**`disabledCustomPolicies`** — 全スコープの和集合。ダッシュボードが個別ポリシーをオフにすると、ソース修飾IDがここに書き込まれます（明示的なポリシーファイルまたは規約ポリシーファイルから）。未記載のポリシーはデフォルトで有効のままです。IDにはソースファイルが含まれるため、複数ファイルに同名のポリシーが存在する場合でも個別に制御できます。 +**`disabledCustomPolicies`** — すべてのスコープにわたる和集合。ダッシュボードで明示的またはコンベンションポリシーファイルの個別ポリシーをオフにすると、ソース修飾 ID がここに書き込まれます。リストにないポリシーはデフォルトで有効のままです。ID にはソースファイルが含まれるため、複数のファイルで同名のポリシーがある場合も個別に制御できます。 -**`llm`** — 最初に定義したスコープが優先されます。 +**`llm`** — 定義した最初のスコープが優先されます。 --- -## 設定ファイルの形式 +## 設定ファイルのフォーマット ```json { @@ -104,27 +104,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global にフォー 型: `string[]` -有効にするポリシー名のリスト。名前は `failproofai policies` で表示されるポリシー識別子と完全に一致している必要があります。全リストは[組み込みポリシー](/ja/built-in-policies)を参照してください。 +有効にするポリシー名のリスト。名前は `failproofai policies` で表示されるポリシー識別子と完全に一致する必要があります。全リストは [組み込みポリシー](/ja/built-in-policies) を参照してください。 -`enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても無効になります。 +`enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても無効です。 ### `policyParams` 型: `Record>` -ポリシーごとのパラメータオーバーライド。外側のキーがポリシー名、内側のキーはポリシー固有のものです。各ポリシーで使用可能なパラメータは[組み込みポリシー](/ja/built-in-policies)に記載されています。 +ポリシーごとのパラメータ上書き設定。外側のキーはポリシー名、内側のキーはポリシー固有のものです。各ポリシーで利用可能なパラメータは [組み込みポリシー](/ja/built-in-policies) に記載されています。 -パラメータを持つポリシーで指定がない場合、ポリシーの組み込みデフォルト値が使用されます。`policyParams` を設定しないユーザーは以前のバージョンと同じ動作になります。 +ポリシーにパラメータがあっても指定しない場合、そのポリシーの組み込みデフォルトが使用されます。`policyParams` をまったく設定しないユーザーは、以前のバージョンと同じ動作になります。 -ポリシーのパラメータブロック内の未知のキーは、フック発火時には静かに無視されますが、`failproofai policies` 実行時に警告として表示されます。 +ポリシーの params ブロック内の未知のキーは、フック実行時には無視されますが、`failproofai policies` を実行したときに警告として表示されます。 -#### `hint`（共通オプション） +#### `hint`（クロスカッティング） -型: `string`（任意） +型: `string`（省略可能） -ポリシーが `deny` または `instruct` を返したときに、理由に付加されるメッセージです。ポリシー自体を変更せずに Claude に具体的なガイダンスを提供するために使用します。 +ポリシーが `deny` または `instruct` を返したときに reason に追記されるメッセージ。ポリシー自体を変更することなく、Claude に実行可能なガイダンスを提供するために使用します。 -組み込み、カスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）など、あらゆるポリシータイプで動作します。 +組み込み、カスタム（`custom/`）、プロジェクトコンベンション（`.failproofai-project/`）、ユーザーコンベンション（`.failproofai-user/`）など、あらゆるポリシータイプで機能します。 ```json { @@ -145,42 +145,45 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global にフォー `block-force-push` が拒否すると、Claude には次のように表示されます: *「Force-pushing is blocked. Try creating a fresh branch instead.」* -文字列以外の値や空文字列は静かに無視されます。`hint` が設定されていない場合は動作が変わらず（後方互換性あり）。 +文字列以外の値や空の文字列は無視されます。`hint` が設定されていない場合、動作は変わりません（後方互換）。 ### `customPoliciesPath` 型: `string`（絶対パス） -カスタムフックポリシーを含むJavaScriptファイルへのパス。`failproofai policies --install --custom ` により自動設定されます（パスは格納前に絶対パスに解決されます）。 +カスタムフックポリシーを含む JavaScript ファイルへのパス。`failproofai policies --install --custom ` によって自動的に設定されます（パスは保存前に絶対パスに解決されます）。 -ファイルはフックイベントのたびに新たに読み込まれます。キャッシュはありません。作成方法の詳細は[カスタムポリシー](/ja/custom-policies)を参照してください。 +ファイルはフックイベントのたびに新しく読み込まれます。キャッシュはありません。作成の詳細は [カスタムポリシー](/ja/custom-policies) を参照してください。 -### 規約ベースのポリシー +### コンベンションベースのポリシー -明示的な `customPoliciesPath` に加えて、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動検出して読み込みます。 +明示的な `customPoliciesPath` に加えて、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動的に検出して読み込みます。 | レベル | ディレクトリ | スコープ | |-------|-----------|-------| | プロジェクト | `.failproofai/policies/` | バージョン管理でチームと共有 | -| ユーザー | `~/.failproofai/policies/custom-policies/` | 個人用。全プロジェクトに適用 | +| ユーザー | `~/.failproofai/policies/` | 個人用。すべてのプロジェクトに適用 | - ユーザーレベルのディレクトリは、ホームディレクトリの再編成により1階層下に移動しました。古い `~/.failproofai/policies/` に残っているファイルは、アップグレード後に初めて `failproofai` コマンドを実行すると `custom-policies/` に自動移動され、移動されたファイルがコマンド出力に表示されます。 + ポリシーファイルは `~/.failproofai/policies/` に直接置いてください。隣の + `cloud-policies/` フォルダには組織がこのマシンにデプロイしたポリシーが入っています。ディスカバリーはサブディレクトリを掘り下げないため、このフォルダはスキャンされず、`policies/` に置いたファイルとの衝突も起きません。 + + `~/.failproofai/policies/custom-policies/` を使っていた旧バージョンからアップグレードする場合、そのフォルダ内のすべて（ポリシーファイル、インポートするヘルパーの `lib/`、読み込むデータファイルを含む）は、`failproofai` コマンドを初めて実行したときに自動的に上の階層へ移動され、移動した内容がコマンドに表示されます。 -**ファイルのマッチング:** `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれます（例: `security-policies.mjs`、`workflow-policies.js`）。ディレクトリ内のその他のファイルは無視されます。 +**ファイルのマッチング:** `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれます（例: `security-policies.mjs`、`workflow-policies.js`）。ディレクトリ内の他のファイルは無視されます。 -**設定不要:** 規約ポリシーは `policies-config.json` へのエントリが不要です。ディレクトリにファイルを置くだけで、次のフックイベント時に自動的に読み込まれます。 +**設定不要:** コンベンションポリシーは `policies-config.json` へのエントリが不要です。ディレクトリにファイルを置くだけで、次のフックイベント時に自動的に読み込まれます。 -**ユニオン読み込み:** プロジェクトとユーザーの両方の規約ディレクトリがスキャンされます。両レベルのマッチするファイルがすべて読み込まれます（`customPoliciesPath` の先着スコープ優先とは異なります）。 +**ユニオン読み込み:** プロジェクトとユーザー両方のコンベンションディレクトリがスキャンされます。両方のレベルからマッチするすべてのファイルが読み込まれます（最初のスコープが優先される `customPoliciesPath` とは異なります）。 -詳細と例については[カスタムポリシー](/ja/custom-policies)を参照してください。 +詳細と例は [カスタムポリシー](/ja/custom-policies) を参照してください。 ### `llm` -型: `object`（任意） +型: `object`（省略可能） -AI呼び出しを行うポリシー向けのLLMクライアント設定。多くのセットアップでは不要です。 +AI 呼び出しを行うポリシー向けの LLM クライアント設定。ほとんどの環境では不要です。 ```json { @@ -193,26 +196,26 @@ AI呼び出しを行うポリシー向けのLLMクライアント設定。多く --- -## CLIからの設定管理 +## CLI からの設定管理 -`policies --install` および `policies --uninstall` コマンドはエージェントCLIのフック設定ファイル（フックエントリポイント）に書き込みますが、`policies-config.json` は直接管理するファイルです。この2つは別物です: +`policies --install` および `policies --uninstall` コマンドはエージェント CLI のフック設定ファイル（フックエントリポイント）に書き込みますが、`policies-config.json` は直接管理するファイルです。この2つは別物です。 -- **エージェントCLI設定** — ツール使用のたびにエージェントが `failproofai --hook ` を呼び出すように指示します: +- **エージェント CLI の設定** — ツール使用のたびにエージェントが `failproofai --hook ` を呼び出すよう指示します: - **Claude Code**: `~/.claude/settings.json`（ユーザー）、`/.claude/settings.json`（プロジェクト）、`/.claude/settings.local.json`（ローカル） - - **OpenAI Codex**: `~/.codex/hooks.json`（ユーザー）、`/.codex/hooks.json`（プロジェクト）— Codex には `local` スコープがありません - - **GitHub Copilot CLI _(ベータ版)_**: `~/.copilot/hooks/failproofai.json`（ユーザー）、`/.github/hooks/failproofai.json`（プロジェクト）— Copilot には `local` スコープがありません。フックエントリはCopilotのOS別 `bash`/`powershell` コマンドフィールドと `timeoutSec` を使用し、ファイルはトップレベルに `version: 1` マーカーを持ちます。Copilot CLIのサポートは**ベータ版**です。公開ドキュメントに記載のない `events.jsonl` レコードスキーマを実際のセッションで検証中です。**VS Code Copilot Chat エージェントモード（Preview）** は、`.github/hooks/*.json`、`~/.copilot/hooks/*.json`、`~/.claude/settings.json`（`chat.hookFilesLocations` 設定で制御）からフック設定を読み込み、`{hookSpecificOutput:{permissionDecision:"deny",…}}` の同じClaude形式コントラクトを使用します。`failproofai policies --install --cli copilot`（または `--cli claude`）が書き込む正確なパスと一致するため、**VS Codeエージェントモードでも別途 `vscode` インテグレーションは不要**です（VS Codeのディスカバリーログで確認済み）。 - - **Cursor Agent _(ベータ版)_**: `~/.cursor/hooks.json`（ユーザー）、`/.cursor/hooks.json`（プロジェクト）— Cursor には `local` スコープがありません。フックエントリはClaude形式の `{type, command, timeout}` を使用しますが（`bash`/`powershell` の分割なし）、Cursorの[フックスキーマ](https://cursor.com/docs/hooks)に従いキャメルケースのイベントキー（`preToolUse`、`beforeSubmitPrompt` など）の下にフラット配列として格納されます。ファイルはトップレベルに `version: 1` マーカーを持ちます。ハンドラーは `CURSOR_EVENT_MAP` でキャメルケース → パスカルケースに正規化するため、既存の組み込みポリシーはそのまま動作します。Cursor Agentのサポートは**ベータ版**です。公開ドキュメントに記載のないCursorのトランスクリプトのオンディスク形式を実際のインストールで検証中です。 - - **OpenCode _(ベータ版)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（ユーザー）、`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（プロジェクト）— OpenCode には `local` スコープがありません。他の5つのCLIとは異なり、OpenCode には**外部コマンドフックシステムがありません**。`opencode.json` の `plugin: []` 配列に明示的に登録されたインプロセスJS/TSプラグインを読み込みます（`.opencode/plugins/` からの自動検出は opencode v1.14.33 でのプラグイン読み込み方式では**ありません**）。インストール時に小さな生成済みプラグインシムが配置され、failproofaiバイナリをサブプロセスで呼び出し、バイナリのClaude形式JSONレスポンスをプラグインセマンティクスに変換します: ツールイベント拒否に `throw new Error()`（ツール呼び出しをキャンセル）、instruct および `Stop` / `SubagentStop` 拒否に `client.session.prompt(...)`（拒否理由を次のユーザーメッセージとして送信 — `session.idle` は通知のみでスローしても無効なため、唯一の強制再試行チャンネル）、allow には何もしない。シムはツール名（小文字 → `OPENCODE_TOOL_MAP` でパスカルケース）とツール入力の引数キー（`OPENCODE_TOOL_INPUT_MAP` で `Read` / `Write` / `Edit` のキャメルケース → スネークケース、例: `filePath` → `file_path`、`oldString` → `old_string`）をバイナリに転送前に正規化するため、`block-read-outside-cwd`、`block-env-files`、`block-secrets-write` などのパスチェック組み込みポリシーはOpenCodeのツール呼び出しでもそのまま動作します。セッションは `~/.local/share/opencode/opencode.db` のOpenCodeのSQLiteデータベースに保存されます。ダッシュボードのセッションビューアーは `opencode db --format json` と `opencode export ` を通じて読み込みます。OpenCodeのサポートは**ベータ版**です。複数バージョンおよび実際のセッションでの動作を検証中です。[OpenCode pluginsドキュメント](https://opencode.ai/docs/plugins/)を参照してください。 - - **Pi _(ベータ版)_**: `~/.pi/agent/settings.json`（ユーザー）、`/.pi/settings.json`（プロジェクト）— Pi には `local` スコープがありません。Piは起動時にTypeScript拡張パッケージを読み込みます。設定ファイルはフラットな文字列配列 `{"packages": ["./relative/path", …]}` です。failproofai はバンドルされた `pi-extension/` ディレクトリを指すパッケージ配列エントリを1つ書き込みます。拡張機能はPiの `tool_call` / `user_bash` / `input` / `session_start` イベントを内部でサブスクライブし、`failproofai --hook --cli pi` をシェルアウトで呼び出します。ハンドラーは `PI_EVENT_MAP` でアンダースコア小文字スネークケース → パスカルケースに正規化するため、既存の組み込みポリシーはそのまま動作します。ツール入力引数も `PI_TOOL_INPUT_MAP` で正規化されます（PiのRead / Write / Edit は `file_path` ではなく `path` を使用。トップレベルキーをマッピングすることで `block-env-files` と `block-secrets-write` が動作し、`block-read-outside-cwd` はすでに `path` フォールバックを持っていました）。PiのサポートはPiの拡張APIとセッションログレイアウトが安定するまで**ベータ版**です。 - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml`（**ユーザースコープのみ** — Hermesにはプロジェクト/ローカル設定がありません）。HermesはSlack/Telegramの**ゲートウェイ**であるため、1回のインストールで全プラットフォーム（Slack/Telegram/cli/cron）**および**内部サブエージェントからのツール呼び出しを傍受します。フックエントリはHermesのスネークケースイベント（`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`）をキーとする `hooks:` マップの下に `{command, timeout}` ペア（タイムアウトは**秒**）として記載されます。ハンドラーは `HERMES_EVENT_MAP` でイベントを、`HERMES_TOOL_MAP` でツール名を正規化するため、組み込みポリシーはそのまま動作します。設定はコメント保持のYAML `Document` ラウンドトリップで編集されるため、オペレーターの他の設定が保持されます。インストール時に `hooks_auto_accept: true` が設定されるため、ヘッドレスゲートウェイ（TTYなし）は同意プロンプトなしでフックを実行します。評価器はHermesの `{"decision":"block","reason"}` stdout コントラクトを出力します（Hermesは終了コードを無視します）。**制限事項:** Hermesにはターン終了の `Stop` イベントがないため、`require-*-before-stop` 組み込みポリシーは動作しません（適用外。故障ではありません）。`instruct` はallow（ログ記録あり）に降格されます（追加コンテキストチャンネルなし）。出力シークレットの編集（`sanitize-*`）はシェルフックコントラクト上でツール出力を書き換えることができません。Hermesは**オフライン監査**ソースでもあります — ダッシュボードは `~/.hermes/state.db` からゲートウェイセッションを直接読み込みます。 - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json`（**ユーザースコープのみ** — OpenClawにはプロジェクト/ローカル設定がありません）。Hermesと同様に、OpenClawはセルフホスト型マルチチャンネル**ゲートウェイ**であるため、1回のインストールで全チャンネルと内部サブエージェントからのツール呼び出しを傍受します。エンフォースメントはOpenClawの**インプロセスプラグインフック**を通じて実行されます（ファイルベースの内部フックは観察のみで、ブロックできません）。そのためOpenCode/Piと同様に、failproofaiは静的な `openclaw-plugin/` パッケージを提供し、failproofaiバイナリを非同期でスポーンして判定を変換します。インストール時に `openclaw.json` の `plugins.load.paths[]` にプラグインディレクトリが登録され、`plugins.entries.failproofai`（`hooks.allowConversationAccess: true`、生のConversationフックに必要）で有効化されます。評価器はフラットな `{permission, reason}` 判定を出力し、シムはそれを各フックのネイティブ返却形式にマッピングします: `before_tool_call → {block:true, blockReason}`（**PreToolUse**）、`before_agent_run → {outcome:"block", reason}`（**UserPromptSubmit**）、`before_agent_finalize → {action:"revise", reason}`（**Stop** — 実際のターン終了ゲートであるため、Hermesとは異なり `require-*-before-stop` 組み込みポリシーが**有効**です）。イベントとツール名はバイナリ側で `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`（`exec→Bash`、`read→Read` など）を通じて正規化されるため、組み込みポリシーはそのまま動作します。シムはスポーン/パース/タイムアウトエラーが発生した場合はフェイルオープンします。OpenClawは**オフライン監査**ソースでもあります — ダッシュボードは `~/.openclaw/agents//sessions/.jsonl` のJSONLセッションを読み込みます。 - - **Factory Droid (`droid`)**: `~/.factory/hooks.json`（ユーザー）、`/.factory/hooks.json`（プロジェクト）— Factory には `local` スコープがありません。droid は Claude スタイルの外部コマンドフックシステムを搭載していますが、droid v0.171.0 で実際に確認された2つの固有の仕様があります: (1) イベント名は `hooks.json` の**トップレベル**に存在します — **`"hooks"` ラッパーはありません**（droid はラッパーがあると拒否します）。ツールイベント（`PreToolUse`/`PostToolUse`）は `"matcher": "*"` を持ち、非ツールイベントはそれを省略します。(2) 拒否はフック**終了コード2 + stderr**で駆動されます（JSONの決定ではありません）。評価器の `factory` ブランチはツール/プロンプトイベントに終了コード2を返し、ターン終了の `Stop` イベント（droidの唯一の強制再試行チャンネル）のみ `{decision:"block", reason}` を返します。イベントはすでにパスカルケースです（イベントマップなし）。ペイロードはClaude スネークケースです。ツール名のみ `FACTORY_TOOL_MAP`（`Execute→Bash`、`Create→Write`、`FetchUrl→WebFetch` など）で正規化されます。Factory は**オフライン監査**ソースでもあります — ダッシュボードは `~/.factory/sessions//.jsonl` のオンディスクJSONLセッションを読み込みます。 - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json`（ユーザー）、`/.devin/config.json`（プロジェクト）— Devin には `local` スコープがありません。Devin は devin v3000.1.27 で実際に確認された**純粋なClaude クローン**です: 標準のClaude `"hooks"` ラッパースキーマ（書き込みはマージ保持方式のため、設定ファイルの他のキー — `org_id`、`theme_mode` など — が保持されます）、すでにパスカルケースのイベント名（イベントマップなし、ハンドラーブランチなし）、Claude スネークケースの stdin ペイロード（正規化なし）を使用します。評価器の `devin` ブランチは**全**イベントに対して終了コード0で `{"decision":"block","reason"}` JSONを stdout に出力して拒否します（確認済み — ブロックは `--permission-mode dangerous` をオーバーライドしました）。ターン終了の `Stop` イベントでは、`require-*-before-stop` 組み込みポリシーが有効になるよう理由に MANDATORY-ACTION 強制再試行の文言が含まれます。ツール名のみ `DEVIN_TOOL_MAP`（`exec→Bash`; `tool_input.command` はすでに標準形式）で正規化されます。Devin は**オフライン監査**ソースでもあります — ダッシュボードは `~/.local/share/devin/cli/sessions.db` のSQLiteセッションを読み込みます（各 `sessions` 行には実際の `working_directory` が含まれるため、セッションはClaude と同様にプロジェクトの作業ディレクトリでグループ化されます）。 - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json`（ユーザー）、`/.agents/hooks.json`（プロジェクト）— Antigravity には `local` スコープがありません。Factory/Devin とは異なり、Antigravity は agy v1.1.2 で実際に確認された**独自のコントラクト**（Claude クローンではない）を持ちます。`hooks.json` は**名前付きフック**スキーマを使用します: トップレベルキーはフック*名*（`"failproofai"`）で、その値はイベント→ハンドラーマップです — ツールイベント（`PreToolUse`/`PostToolUse`）はハンドラーを `{matcher:"*", hooks:[…]}` にラップし、`PreInvocation`/`Stop` は**フラット**なハンドラー配列です（他の名前付きフックは保持されます）。stdin ペイロードは**キャメルケース protojson**（`toolCall:{name,args}`、`conversationId`、`workspacePaths`、`transcriptPath`）です — failproofai はポリシー実行前にスネークケースに正規化し、`run_command` のパスカルケース引数（`CommandLine`/`Cwd`）を `ANTIGRAVITY_TOOL_INPUT_MAP` でマッピングします。評価器の `antigravity` ブランチはAntigravity**独自**のレスポンス形式を使用します: `{decision:"deny", reason}` でツール/プロンプトをブロック（終了コード0）、`{decision:"continue", reason}` でターン終了の `Stop` にループを再開（そのため `require-*-before-stop` 組み込みポリシーが有効）、`{injectSteps:[{ephemeralMessage}]}` で `PreInvocation`（→ `UserPromptSubmit`）に命令を注入。ツール名は `ANTIGRAVITY_TOOL_MAP`（`run_command→Bash`、`view_file→Read` など）で正規化されます。Antigravity は**オフライン監査**ソースでもあります — ダッシュボードは `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` のプレーンJSONLトランスクリプトを読み込みます（会話インデックスは `conversation_summaries.db` に格納）。 - - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json`（ユーザー）、`/.agents/plugins/failproofai/hooks/hooks.json`（プロジェクト）— Goose には `local` スコープがありません。エンフォースメントはGooseの**フック**システム（クロスエージェントの**Open Plugins**仕様）を使用します: インストーラーは `failproofai` プラグインディレクトリを配置するだけで、Gooseは起動時に自動検出します（`~/.config/goose/config.yaml` に自己登録）。`hooks.json` はトップレベルに `"hooks"` ラッパーを持つOpen Pluginsスキーマを使用し、マッチャーは全イベントで**省略**されています — 裸の `"*"` は何にもマッチしない無効な正規表現です（goose v1.43.0 で実際に確認）。イベント名はすでにパスカルケースです（イベントマップなし）。stdin ペイロードは `event`/`working_dir` を使用し、ハンドラーが `hook_event_name`/`cwd` に正規化します。評価器の `goose` ブランチは終了コード0で `{"decision":"block","reason"}` JSONを stdout に出力して拒否し、**`PreToolUse`** イベントのみで有効です（goose ≥ v1.37.0 で搭載）— シェルツール**および委任されたサブエージェント内**で発火するため、単一の十分な拒否ポイントです。その他のフックエラーはフェイルオープンします。Gooseには**`Stop` イベントがない**ため、`require-*-before-stop` 組み込みポリシーは適用されません（Hermesと同様）。ツール名は `GOOSE_TOOL_MAP`（`shell→Bash`、`write→Write`、`todo__todo_write→TodoWrite` など）で、パスキーは `GOOSE_TOOL_INPUT_MAP`（`path`/`source` → `file_path`）で正規化されます。Goose は**オフライン監査**ソースでもあります — ダッシュボードは `~/.local/share/goose/sessions/sessions.db` のSQLiteセッションを読み込みます（各 `sessions` 行には実際の `working_dir` が含まれるため、セッションはDevin と同様にプロジェクトの作業ディレクトリでグループ化されます。`--no-session` のスクラッチ実行はフィルタリングされます）。 -- **`policies-config.json`** — どのポリシーを評価するか、どのパラメータで評価するかをfailproofaiに指示します（全エージェントCLI共通） - -特定のエージェントを指定するには `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` を渡します（スペース区切りまたは繰り返しで任意のサブセットを指定可能）: + - **OpenAI Codex**: `~/.codex/hooks.json`（ユーザー）、`/.codex/hooks.json`（プロジェクト） — Codex に `local` スコープはありません + - **GitHub Copilot CLI _(ベータ)_**: `~/.copilot/hooks/failproofai.json`（ユーザー）、`/.github/hooks/failproofai.json`（プロジェクト） — Copilot に `local` スコープはありません。フックエントリは Copilot の OS キー付き `bash`/`powershell` コマンドフィールドと `timeoutSec` を使用し、ファイルのトップレベルに `version: 1` マーカーを持ちます。Copilot CLI のサポートは **ベータ** です。公開ドキュメントに仕様が記載されていない `events.jsonl` レコードスキーマを、より多くの実際のセッションで検証中です。**VS Code Copilot Chat エージェントモード（プレビュー）** は `.github/hooks/*.json`、`~/.copilot/hooks/*.json`、`~/.claude/settings.json` からフック設定を読み込み（`chat.hookFilesLocations` 設定で管理）、Claude 形式の `{hookSpecificOutput:{permissionDecision:"deny",…}}` コントラクトを使用します。これはこの `copilot` インテグレーションと `claude` インテグレーション（`~/.claude/settings.json`）がすでに書き込むパスであるため、`failproofai policies --install --cli copilot`（または `--cli claude`）を実行するだけで **VS Code エージェントモードでも適用され**、別途 `vscode` インテグレーションは不要です（VS Code のディスカバリーログから確認済み）。 + - **Cursor Agent _(ベータ)_**: `~/.cursor/hooks.json`（ユーザー）、`/.cursor/hooks.json`（プロジェクト） — Cursor に `local` スコープはありません。フックエントリは Claude 形式の `{type, command, timeout}` を使用しますが（`bash`/`powershell` の分割なし）、Cursor の [フックスキーマ](https://cursor.com/docs/hooks) に従ってキャメルケースのイベントキー（`preToolUse`、`beforeSubmitPrompt` など）のフラット配列として保存されます。ファイルのトップレベルに `version: 1` マーカーを持ちます。ハンドラーは `CURSOR_EVENT_MAP` を通じてキャメルケースをパスカルケースに正規化するため、既存の組み込みポリシーはそのまま動作します。Cursor Agent のサポートは **ベータ** です。公開ドキュメントに仕様が記載されていない Cursor のトランスクリプトのディスク上フォーマットを、より多くの実際のインストールで検証中です。 + - **OpenCode _(ベータ)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（ユーザー）、`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（プロジェクト） — OpenCode に `local` スコープはありません。他の5つの CLI とは異なり、OpenCode には **外部コマンドフックシステムがありません**。`opencode.json` の `plugin: []` 配列に明示的に登録されたインプロセス JS/TS プラグインを読み込みます（`.opencode/plugins/` からの自動検出は opencode v1.14.33 でのプラグイン読み込み方法では **ありません**）。インストールは小さな生成プラグインシムを配置し、failproofai バイナリをサブプロセスとして呼び出し、バイナリの Claude 形式の JSON レスポンスをプラグインセマンティクスに変換します。ツールイベントの deny には `throw new Error()`（ツール呼び出しをキャンセル）、instruct および `Stop` / `SubagentStop` の deny には `client.session.prompt(...)`（deny の理由を次のユーザーメッセージとして送信 — `session.idle` は通知のみで throw しても no-op のため、唯一の強制リトライチャンネル）、allow には no-op を使用します。シムはツール名（小文字→パスカルケース、`OPENCODE_TOOL_MAP` 経由）とツール入力の引数キー（キャメルケース→スネークケース、`Read` / `Write` / `Edit` 向けの `OPENCODE_TOOL_INPUT_MAP` 経由、例: `filePath` → `file_path`、`oldString` → `old_string`）を正規化してからバイナリに転送するため、`block-read-outside-cwd`、`block-env-files`、`block-secrets-write` などのパスチェック組み込みポリシーは OpenCode のツール呼び出しでもそのまま動作します。セッションは `~/.local/share/opencode/opencode.db` の OpenCode の SQLite DB に保存されます。ダッシュボードのセッションビューアーは `opencode db --format json` と `opencode export ` でこれらを読み込みます。OpenCode のサポートは **ベータ** です。バージョン間の動作やより多くの実際のセッションで検証中です。[OpenCode プラグインドキュメント](https://opencode.ai/docs/plugins/) を参照してください。 + - **Pi _(ベータ)_**: `~/.pi/agent/settings.json`（ユーザー）、`/.pi/settings.json`（プロジェクト） — Pi に `local` スコープはありません。Pi は起動時に TypeScript 拡張パッケージを読み込みます。設定ファイルはフラットな文字列配列 `{"packages": ["./relative/path", …]}` です。failproofai はバンドルされた `pi-extension/` ディレクトリを指す単一の packages 配列エントリを書き込みます。拡張機能は内部で Pi の `tool_call` / `user_bash` / `input` / `session_start` イベントをサブスクライブし、`failproofai --hook --cli pi` をシェルアウトします。ハンドラーは `PI_EVENT_MAP` を通じてアンダースコアの小文字スネークケースをパスカルケースに正規化するため、既存の組み込みポリシーはそのまま動作します。ツール入力の引数も `PI_TOOL_INPUT_MAP` を通じて正規化されます（Pi の Read / Write / Edit は `file_path` でなく `path` を渡します。トップレベルキーをマッピングすることで `block-env-files` と `block-secrets-write` が動作します — `block-read-outside-cwd` にはすでに `path` のフォールバックがあります）。Pi のサポートは **ベータ** です。Pi の拡張 API とセッションログのレイアウトが安定するまで検証を続けます。 + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml`（**ユーザースコープのみ** — Hermes にはプロジェクト/ローカル設定がありません）。Hermes は Slack/Telegram の **ゲートウェイ** であるため、1回のインストールですべてのプラットフォーム（Slack/Telegram/cli/cron）および内部サブエージェントからのツール呼び出しをインターセプトします。フックエントリは Hermes のスネークケースイベント（`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`）をキーとする `hooks:` マップの `{command, timeout}` ペアです（タイムアウトは**秒**単位）。ハンドラーは `HERMES_EVENT_MAP` でイベントを、`HERMES_TOOL_MAP` でツール名を正規化するため、組み込みポリシーはそのまま動作します。設定はコメントを保持する YAML `Document` のラウンドトリップで編集されるため、オペレーターの他の設定が維持されます。インストール時に `hooks_auto_accept: true` が設定されるため、ヘッドレスゲートウェイ（TTY なし）でも同意プロンプトなしでフックが実行されます。エバリュエーターは Hermes の `{"decision":"block","reason"}` stdout コントラクトを出力します（Hermes は終了コードを無視します）。**制限事項:** Hermes にはターン終了の `Stop` イベントがないため、`require-*-before-stop` 組み込みポリシーは動作しません（該当しないだけで、壊れているわけではありません）。`instruct` は allow-with-logged-note に降格します（追加コンテキストチャンネルなし）。出力シークレットのリダクション（`sanitize-*`）はシェルフックコントラクト経由でツール出力を書き換えることができません。Hermes は**オフライン監査**ソースでもあり、ダッシュボードは `~/.hermes/state.db` から直接ゲートウェイセッションを読み込みます。 + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json`（**ユーザースコープのみ** — OpenClaw にはプロジェクト/ローカル設定がありません）。Hermes と同様に、OpenClaw はセルフホスト型のマルチチャンネル **ゲートウェイ** であるため、1回のインストールですべてのチャンネルおよび内部サブエージェントからのツール呼び出しをインターセプトします。適用は OpenClaw の **インプロセスプラグインフック** を通じて実行されます（ファイルベースの内部フックは観測のみで、ブロックできません）。そのため — OpenCode/Pi と同様に — failproofai は failproofai バイナリを非同期でスポーンして判定を変換する静的な `openclaw-plugin/` パッケージを同梱します。インストールは `openclaw.json` の `plugins.load.paths[]` に同梱のプラグインディレクトリを登録し、`plugins.entries.failproofai` で有効化します（生の会話フックに必要な `hooks.allowConversationAccess: true` を含む）。エバリュエーターはフラットな `{permission, reason}` 判定を出力し、シムはそれを各フックのネイティブな戻り形式にマッピングします: `before_tool_call → {block:true, blockReason}`（**PreToolUse**）、`before_agent_run → {outcome:"block", reason}`（**UserPromptSubmit**）、`before_agent_finalize → {action:"revise", reason}`（**Stop** — 実際のターン終了ゲートのため、Hermes と異なり `require-*-before-stop` 組み込みポリシーは OpenClaw で**適用されます**）。イベントとツール名はバイナリ側で `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`（`exec→Bash`、`read→Read` など）を通じて正規化されるため、組み込みポリシーはそのまま動作します。シムはスポーン/パース/タイムアウトエラーが発生した場合は open にフォールバックします。OpenClaw は**オフライン監査**ソースでもあり、ダッシュボードは `~/.openclaw/agents//sessions/.jsonl` の JSONL セッションを読み込みます。 + - **Factory Droid (`droid`)**: `~/.factory/hooks.json`（ユーザー）、`/.factory/hooks.json`（プロジェクト） — Factory に `local` スコープはありません。droid は Claude スタイルの外部コマンドフックシステムを備えていますが、droid v0.171.0 で実際に確認した2つの仕様があります: (1) イベント名は `hooks.json` の **トップレベル** に置かれます — **`"hooks"` ラッパーはありません**（droid はラッパーがあるとエラーになります）。ツールイベント（`PreToolUse`/`PostToolUse`）には `"matcher": "*"` が付き、非ツールイベントには付きません。(2) deny は JSON 判定ではなく、**終了コード 2 + stderr** で駆動されます — エバリュエーターの `factory` ブランチはツール/プロンプトイベントで終了コード 2 を返し、ターン終了の `Stop` イベント（droid 唯一の強制リトライチャンネル）のみ `{decision:"block", reason}` を返します。イベントはすでにパスカルケースです（イベントマップなし）。ペイロードは Claude スネークケースで、ツール名のみ `FACTORY_TOOL_MAP`（`Execute→Bash`、`Create→Write`、`FetchUrl→WebFetch` など）で正規化されます。Factory は**オフライン監査**ソースでもあり、ダッシュボードは `~/.factory/sessions//.jsonl` のディスク上の JSONL セッションを読み込みます。 + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json`（ユーザー）、`/.devin/config.json`（プロジェクト） — Devin に `local` スコープはありません。Devin は devin v3000.1.27 で実際に確認した **純粋な Claude クローン** です。標準の Claude `"hooks"` ラッパースキーマを使用し（書き込みはマージ保持型なので設定ファイルの他のキー — `org_id`、`theme_mode` など — が維持されます）、すでにパスカルケースのイベント名（イベントマップなし、ハンドラーブランチなし）、Claude スネークケースの stdin ペイロード（正規化なし）を使用します。エバリュエーターの `devin` ブランチは**すべての**イベントに対して終了コード 0 で stdout に `{"decision":"block","reason"}` JSON を出力して deny します（確認済み — ブロックは `--permission-mode dangerous` を上書きしました）。ターン終了の `Stop` イベントでは reason に MANDATORY-ACTION 強制リトライの文言が含まれるため、`require-*-before-stop` 組み込みポリシーが適用されます。ツール名のみ `DEVIN_TOOL_MAP`（`exec→Bash`; `tool_input.command` はすでに正規形）で正規化されます。Devin は**オフライン監査**ソースでもあり、ダッシュボードは `~/.local/share/devin/cli/sessions.db` の SQLite セッションを読み込みます（各 `sessions` 行には実際の `working_directory` があるため、Claude と同様にセッションがプロジェクト cwd でグループ化されます）。 + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json`（ユーザー）、`/.agents/hooks.json`（プロジェクト） — Antigravity に `local` スコープはありません。Factory/Devin とは異なり、Antigravity は agy v1.1.2 で実際に確認した**独自の**コントラクトを持ちます（Claude クローンではありません）。`hooks.json` は**名前付きフック**スキーマを使用します: トップレベルキーはフック*名*（`"failproofai"`）で、その値はイベント→ハンドラーのマップです — ツールイベント（`PreToolUse`/`PostToolUse`）はハンドラーを `{matcher:"*", hooks:[…]}` でラップし、`PreInvocation`/`Stop` は**フラット**なハンドラー配列です（他の名前付きフックは保持されます）。stdin ペイロードは **キャメルケースの protojson** です（`toolCall:{name,args}`、`conversationId`、`workspacePaths`、`transcriptPath`）— failproofai はポリシー実行前にスネークケースに正規化し、`run_command` のパスカルケース引数（`CommandLine`/`Cwd`）を `ANTIGRAVITY_TOOL_INPUT_MAP` でマッピングします。エバリュエーターの `antigravity` ブランチは Antigravity**独自の**レスポンス形式を使用します: `{decision:"deny", reason}` でツール/プロンプトをブロック（終了コード 0）、ターン終了の `Stop` での `{decision:"continue", reason}` でループ再入（`require-*-before-stop` 組み込みポリシーが適用されます）、`PreInvocation`（→ `UserPromptSubmit`）での `{injectSteps:[{ephemeralMessage}]}` で指示を注入します。ツール名は `ANTIGRAVITY_TOOL_MAP`（`run_command→Bash`、`view_file→Read` など）で正規化されます。Antigravity は**オフライン監査**ソースでもあり、ダッシュボードは `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` のプレーン JSONL トランスクリプトを読み込みます（`conversation_summaries.db` の会話インデックスを使用）。 + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json`（ユーザー）、`/.agents/plugins/failproofai/hooks/hooks.json`（プロジェクト） — Goose に `local` スコープはありません。適用は Goose の**フック**システム、クロスエージェント **Open Plugins** 仕様を使用します: インストーラーは `failproofai` プラグインディレクトリを配置するだけで、Goose が起動時に自動検出します（自分自身を `~/.config/goose/config.yaml` に登録します）。`hooks.json` は**すべての**イベントで matcher が**省略**された Open Plugins スキーマ（トップレベルに `"hooks"` ラッパーあり）を使用します — 裸の `"*"` は何にもマッチしない無効な正規表現です（goose v1.43.0 で実際に確認済み）。イベント名はすでにパスカルケースです（イベントマップなし）。stdin ペイロードは `event`/`working_dir` を使用し、ハンドラーはこれを `hook_event_name`/`cwd` に正規化します。エバリュエーターの `goose` ブランチは終了コード 0 で stdout に `{"decision":"block","reason"}` JSON を出力して deny し、**`PreToolUse`** イベントのみで受け付けられます（goose ≥ v1.37.0 で導入）— これはシェルツール**および委譲されたサブエージェント内部**で発火するため、単一の十分な deny ポイントです。その他のフックエラーは **open にフォールバック**します。Goose には **`Stop` イベントがない**ため、`require-*-before-stop` 組み込みポリシーは適用されません（Hermes と同様）。ツール名は `GOOSE_TOOL_MAP`（`shell→Bash`、`write→Write`、`todo__todo_write→TodoWrite` など）で、パスキーは `GOOSE_TOOL_INPUT_MAP`（`path`/`source` → `file_path`）で正規化されます。Goose は**オフライン監査**ソースでもあり、ダッシュボードは `~/.local/share/goose/sessions/sessions.db` の SQLite セッションを読み込みます（各 `sessions` 行には実際の `working_dir` があるため、Devin と同様にセッションがプロジェクト cwd でグループ化されます。`--no-session` のスクラッチ実行はフィルタリングされます）。 +- **`policies-config.json`** — どのポリシーをどのパラメータで評価するかを failproofai に伝えます（すべてのエージェント CLI で共有） + +特定のエージェントをターゲットにするには `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` を渡します（スペース区切りまたは繰り返しで任意のサブセットを指定できます）: ```bash failproofai policies --install --cli codex --scope project @@ -229,18 +232,36 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -`--cli` を省略すると、`failproofai` はインストールされているエージェントCLIを自動検出します（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`）: +`--cli` を省略した場合、`failproofai` はインストール済みのエージェント CLI を自動検出します（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`）: + +- **1つの CLI を検出** — プロンプトなしでその CLI を自動選択します。 +- **複数の CLI を検出**（インタラクティブターミナル） — `検出済み (N)` セクション（`N件すべてにインストール` の集約行 + 検出済み CLI のリスト個別表示）と `未インストール (M) · 事前にフックをインストール` セクション（未検出のサポート済み CLI のリスト）にグループ化された矢印キーの単一選択プロンプトを表示します（↑↓で移動、Enter で選択、^C で終了）。アンインストールフローには検出済みセクションのみ表示されます。 +- **複数の CLI を検出**（非インタラクティブ実行、CI や TTY なし） — プロンプトなしですべての検出済み CLI にインストールします。 +- **何も検出されない** — PATH にエージェントバイナリが見つからないという警告を出しながら `claude` にフォールバックします。フックコマンドは書き込まれるため、インストール後すぐに有効になります。 + +`policies-config.json` はいつでも直接編集できます。変更は次のフックイベント時に即座に反映され、再起動は不要です。 + +## アップグレード時の設定の維持 + +新しいバージョンの failproofai は `~/.failproofai/` の構成を変更することがあります。その場合、アップグレード後の最初のコマンド実行時にディレクトリが移行され、**設定はリセットされずに引き継がれます**。 + +| 維持されるもの | 再構築されるもの | +|---|---| +| ポリシーの選択とパラメータ（`policies-config.json`） | 監査キャッシュ | +| `daemon.configured` や追加キャプチャパスを含む設定（`config.json`） | クラウド管理のポリシーデプロイメント — 次のポーリング時に再取得してダイジェスト検証 | +| クラウド登録情報（`credentials.json`） | デーモンのスクラッチ状態 | +| `policies/` 内の独自ポリシーファイルとそのインポートするヘルパー | | +| ダッシュボードが読み込む決定ログと未配信のイベント | | + +*新しい* failproofai が書き込んだキーも保持されます。古いリーダーによって削除されることはないため、バージョン間の移動でいずれの方向でも設定が無音で破棄されることはありません。 -- **1つのCLIを検出** — プロンプトなしでそのCLIを自動選択します。 -- **複数のCLIを検出**（インタラクティブターミナル） — 矢印キーで操作するシングルセレクトプロンプトを表示します。`Detected (N)` セクション（`Install for all N detected` の集約行 + 検出された各CLI）と、未検出のサポート済みCLIをすべて前倒しインストールオプションとして一覧表示する `Not installed (M) · install hooks ahead of time` セクションにグループ化されます（↑↓で移動、Enterで選択、^Cで終了）。アンインストールフローはDetectedセクションのみ表示します。 -- **複数のCLIを検出**（非インタラクティブ実行 — CI、TTYなし） — プロンプトなしで検出された全CLIにインストールします。 -- **何も検出されない** — `claude` にフォールバックし、PATHにエージェントバイナリが見つからなかった旨の警告を表示します。フックコマンドは書き込まれるため、インストール後すぐに有効になります。 +移行後のセットアップの再実行は**不要**です。移行されたマシンは移行前とまったく同じように適用されます。これにより、誰も画面の前にいないマシンでも安全にアップグレードできます。すべての移行は `~/.failproofai/migrations/applied.json` に記録され、代替不可能なファイルは実行前に `~/.failproofai/migrations/backup-layout/` にコピーされます。 -`policies-config.json` はいつでも直接編集できます。変更は次のフックイベント時に即座に反映されます（再起動不要）。 +ワンライナーアップグレードは [`failproofai update`](/ja/cli/update) を、`--dry-run` を含む詳細は [`failproofai migrate`](/ja/cli/migrate) を参照してください。 --- -## 例: チームデフォルトを含むプロジェクトレベルの設定 +## 例: チームデフォルト付きのプロジェクトレベル設定 `.failproofai/policies-config.json` をリポジトリにコミットします: @@ -261,4 +282,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her } ``` -各開発者はその後 `.failproofai/policies-config.local.json`（gitignore対象）を作成して、チームメンバーに影響を与えることなく個人用オーバーライドを設定できます。 \ No newline at end of file +各開発者は `.failproofai/policies-config.local.json`（gitignore 対象）を作成して、チームメンバーに影響を与えることなく個人用の上書き設定を持つことができます。 \ No newline at end of file diff --git a/docs/ja/custom-policies.mdx b/docs/ja/custom-policies.mdx index 16ec7823..bdb28b90 100644 --- a/docs/ja/custom-policies.mdx +++ b/docs/ja/custom-policies.mdx @@ -1,14 +1,14 @@ --- title: カスタムポリシー -description: "JavaScriptで独自のポリシーを作成する - 規約の適用、ドリフトの防止、障害の検出、外部システムとの統合" +description: "JavaScriptで独自のポリシーを記述する - 規約の適用、ドリフトの防止、障害の検出、外部システムとの連携" icon: code --- -カスタムポリシーを使用すると、任意のエージェント動作に対するルールを記述できます。プロジェクトの規約の適用、ドリフトの防止、破壊的な操作のゲート処理、スタックしたエージェントの検出、Slackや承認ワークフローとの統合などが可能です。組み込みポリシーと同じフックイベントシステムと `allow`、`deny`、`instruct` の決定機構を使用します。 +カスタムポリシーを使えば、あらゆるエージェントの挙動に対してルールを記述できます。プロジェクトの規約の適用、ドリフトの防止、破壊的な操作のゲート制御、スタックしたエージェントの検出、Slackや承認ワークフローとの連携など、さまざまな用途に対応しています。組み込みポリシーと同じフックイベントシステムと `allow`、`deny`、`instruct` の判定を使用します。 --- -## クイックサンプル +## クイック例 ```js // my-policies.js @@ -37,57 +37,57 @@ failproofai policies --install --custom ./my-policies.js --- -## カスタムポリシーの読み込み方法 +## カスタムポリシーを読み込む2つの方法 ### オプション1: 規約ベース（推奨） -`.failproofai/policies/` に `*policies.{js,mjs,ts}` ファイルを配置するだけで自動的に読み込まれます。フラグや設定変更は不要です。gitフックと同様に、ファイルを置くだけで機能します。 +`*policies.{js,mjs,ts}` ファイルを `.failproofai/policies/` に置くだけで自動的に読み込まれます。フラグや設定変更は不要です。gitフックのような仕組みで、ファイルを置けばすぐに動作します。 ``` -# プロジェクトレベル — 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}` にマッチするファイルのみ読み込まれ、その他のファイルは無視されます - 各ファイルは独立して読み込まれます（ファイル単位でフェイルオープン） -- 明示的な `--custom` および組み込みポリシーと併用できます +- 明示的な `--custom` や組み込みポリシーと共存して動作します -規約ポリシーは、組織の品質基準を構築する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、すべてのチームメンバーが同じルールを自動的に取得できます。開発者ごとのセットアップは不要です。チームが新しい障害パターンを発見したらポリシーを追加してプッシュするだけで、時間とともにこれらは貢献のたびに改善される生きた品質基準になります。 +規約ポリシーは、組織の品質基準を構築する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、全てのチームメンバーが自動的に同じルールを得られます。開発者ごとのセットアップは不要です。チームが新しい障害モードを発見するたびにポリシーを追加してプッシュすれば、コントリビューションのたびに改善され続ける、生きた品質基準になっていきます。 ### オプション2: 明示的なファイルパス ```bash -# カスタムポリシーファイルをインストール +# カスタムポリシーファイルを指定してインストール failproofai policies --install --custom ./my-policies.js -# カスタムポリシーパスを置き換える +# カスタムポリシーのパスを置き換え failproofai policies --install --custom ./new-policies.js -# 複数の明示的なファイルを設定する（フラグの順序で読み込まれる） +# 複数の明示的なファイルを設定（フラグの順に読み込み） failproofai policies --install --custom ./security.js --custom ./workflow.js -# すべての明示的なカスタムポリシーパスを設定から削除する +# 設定からすべての明示的なカスタムポリシーパスを削除 failproofai policies --uninstall --custom ``` -解決された絶対パスは `policies-config.json` に `customPoliciesPaths` として保存されます。複数のファイルを設定するには `--custom` を繰り返してください。レガシーの `customPoliciesPath` フィールドを使用した既存の設定も引き続き動作します。ファイルはフックイベントごとに新たに読み込まれ、イベント間のキャッシュはありません。 +解決された絶対パスは `policies-config.json` に `customPoliciesPaths` として保存されます。複数のファイルを設定するには `--custom` を繰り返し指定します。レガシーの `customPoliciesPath` フィールドを使用している既存の設定は引き続き動作します。ファイルはフックイベントのたびに新たに読み込まれ、イベント間でのキャッシュはありません。 -登録された各ポリシーはダッシュボードに個別のトグルとして表示されます。ポリシーをオフにすると、そのソース修飾IDが `disabledCustomPolicies` に記録されます。ファイルとその他のポリシーは引き続き読み込まれますが、無効化されたポリシーはイベントマッチング前に除外されます。ファイル間で重複するポリシー名は独立したトグルを持ちます。 +登録された各ポリシーは、ダッシュボードに独自のトグルとして表示されます。ポリシーをオフにすると、そのソース修飾IDが `disabledCustomPolicies` に記録されます。ファイルとその他のポリシーは引き続き読み込まれますが、無効化されたポリシーはイベントマッチング前に除外されます。ファイルをまたいで重複するポリシー名は、それぞれ独立したトグルを持ちます。 ### 両方を組み合わせて使用する 規約ポリシーと明示的な `--custom` ファイルは共存できます。読み込み順序: -1. 明示的な `customPoliciesPaths` ファイル（設定された順序） +1. 明示的な `customPoliciesPaths` ファイル（設定された順） 2. プロジェクト規約ファイル（`{cwd}/.failproofai/policies/`、アルファベット順） 3. ユーザー規約ファイル（`~/.failproofai/policies/`、アルファベット順） @@ -103,43 +103,43 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -ポリシーを登録します。同じファイル内で複数のポリシーを追加するために何度でも呼び出せます。 +ポリシーを登録します。同じファイル内に複数のポリシーを定義する場合は、必要な回数だけ呼び出してください。 ```ts customPolicies.add({ name: string; // 必須 - 一意の識別子 description?: string; // `failproofai policies` の出力に表示される - match?: { events?: HookEventType[] }; // イベントタイプでフィルタリング; 省略するとすべてにマッチ + match?: { events?: HookEventType[] }; // イベントタイプでフィルタ；省略するとすべてにマッチ fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### 決定ヘルパー +### 判定ヘルパー -| 関数 | 効果 | 使用場面 | +| 関数 | 効果 | 使いどころ | |----------|--------|----------| -| `allow()` | 操作を暗黙的に許可する | アクションが安全で、メッセージが不要な場合 | +| `allow()` | 操作を静かに許可する | アクションが安全でメッセージが不要な場合 | | `deny(message)` | 操作をブロックする | エージェントがこのアクションを実行すべきでない場合 | -| `instruct(message)` | ブロックせずにコンテキストを追加する | エージェントに軌道を維持するための追加コンテキストを提供する場合 | +| `instruct(message)` | ブロックせずにコンテキストを追加する | エージェントに追加コンテキストを渡して軌道修正させる場合 | -`deny(message)` — メッセージは `"Blocked by failproofai:"` というプレフィックスが付いてClaudeに表示されます。単一の `deny` により、以降のすべての評価がショートサーキットされます。 +`deny(message)` - メッセージは `"Blocked by failproofai:"` というプレフィックスを付けて Claude に表示されます。1つの `deny` がそれ以降のすべての評価をショートサーキットします。 -`instruct(message)` — メッセージは現在のツール呼び出しに対するClaudeのコンテキストに追記されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。 +`instruct(message)` - メッセージは現在のツール呼び出しに対する Claude のコンテキストに追記されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。 -`policyParams` の `hint` フィールドを追加することで、コードを変更せずに `deny` または `instruct` メッセージに追加のガイダンスを付け加えられます。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）のポリシーでも機能します。詳細は[設定 → hint](/ja/configuration#hint-cross-cutting)を参照してください。 +`policyParams` の `hint` フィールドを追加することで、コード変更なしに任意の `deny` または `instruct` メッセージに追加ガイダンスを付け加えられます。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳細は [設定 → hint](/ja/configuration#hint-cross-cutting) を参照してください。 -### 情報提供のallowメッセージ +### 情報提供用のallowメッセージ -`allow(message)` は操作を許可し**つつ**、情報提供のメッセージをClaudeに送信します。メッセージはフックハンドラーのstdoutレスポンスに `additionalContext` として配信されます。これは `instruct` と同じメカニズムを使用しますが、意味的には異なります。警告ではなく、ステータスの更新です。 +`allow(message)` は操作を許可し**つつ**、情報提供メッセージを Claude に送信します。メッセージはフックハンドラのstdoutレスポンス内の `additionalContext` として配信されます。これは `instruct` と同じ仕組みですが、意味的に異なります。警告ではなく、ステータスの更新です。 -| 関数 | 効果 | 使用場面 | +| 関数 | 効果 | 使いどころ | |----------|--------|----------| -| `allow(message)` | 許可してClaudeにコンテキストを送信する | チェックが通過したことを確認する、またはチェックがスキップされた理由を説明する場合 | +| `allow(message)` | 許可してコンテキストをClaudeに送信する | チェックが通過したことを確認する、またはチェックがスキップされた理由を説明する場合 | ユースケース: -- **ステータス確認:** `allow("All CI checks passed.")` — すべてが正常であることをClaudeに伝える +- **ステータス確認:** `allow("All CI checks passed.")` — Claudeにすべてが正常であることを伝える - **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — チェックがスキップされた理由をClaudeに伝え、完全なコンテキストを提供する - **複数メッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返した場合、すべてのメッセージが改行で結合されてまとめて配信される @@ -151,7 +151,7 @@ customPolicies.add({ 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."); } @@ -167,8 +167,8 @@ customPolicies.add({ | `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` | | `toolName` | `string \| undefined` | 呼び出されるツール（例: `"Bash"`、`"Write"`、`"Read"`） | | `toolInput` | `Record \| undefined` | ツールの入力パラメータ | -| `payload` | `Record` | Claude Code からの生のイベントペイロード全体 | -| `session` | `SessionMetadata \| undefined` | セッションコンテキスト（以下参照） | +| `payload` | `Record` | Claude Code からの完全な生イベントペイロード | +| `session` | `SessionMetadata \| undefined` | セッションコンテキスト（以下を参照） | ### `SessionMetadata` フィールド @@ -176,13 +176,13 @@ customPolicies.add({ |-------|------|-------------| | `sessionId` | `string` | Claude Code セッション識別子 | | `cwd` | `string` | Claude Code セッションの作業ディレクトリ | -| `transcriptPath` | `string` | セッションのJSONLトランスクリプトファイルへのパス | +| `transcriptPath` | `string` | セッションの JSONL トランスクリプトファイルへのパス | ### イベントタイプ | イベント | 発火タイミング | `toolInput` の内容 | |-------|--------------|----------------------| -| `PreToolUse` | Claudeがツールを実行する前 | ツールの入力（例: Bashの場合は `{ command: "..." }`） | +| `PreToolUse` | Claudeがツールを実行する前 | ツールの入力（例: Bashの場合 `{ command: "..." }`） | | `PostToolUse` | ツールが完了した後 | ツールの入力 + `tool_result`（出力） | | `Notification` | Claudeが通知を送信するとき | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - フックは常に `allow()` を返す必要があり、通知をブロックすることはできません | | `Stop` | Claudeセッションが終了するとき | 空 | @@ -191,22 +191,22 @@ customPolicies.add({ ## 評価順序 -ポリシーは次の順序で評価されます: +ポリシーは以下の順序で評価されます: 1. 組み込みポリシー（定義順） -2. `customPoliciesPath` からの明示的なカスタムポリシー（`.add()` の順序） -3. プロジェクト `.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の順序） -4. ユーザー `~/.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の順序） +2. `customPoliciesPath` からの明示的なカスタムポリシー（`.add()` の順） +3. プロジェクトの `.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、各ファイル内は `.add()` の順） +4. ユーザーの `~/.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、各ファイル内は `.add()` の順） -最初の `deny` により以降のすべてのポリシーがショートサーキットされます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。 +最初の `deny` がそれ以降のすべてのポリシーをショートサーキットします。すべての `instruct` メッセージは蓄積されてまとめて配信されます。 --- ## 推移的インポート -カスタムポリシーファイルは相対パスを使用してローカルモジュールをインポートできます: +カスタムポリシーファイルは、相対パスを使用してローカルモジュールをインポートできます: ```js // my-policies.js @@ -223,21 +223,21 @@ customPolicies.add({ }); ``` -エントリファイルから到達可能なすべての相対インポートが解決されます。これは `from "failproofai"` のインポートを実際のdistパスに書き換え、ESM互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。 +エントリファイルから到達可能なすべての相対インポートが解決されます。これは `from "failproofai"` インポートを実際のdistパスに書き換え、ESM 互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。 --- ## イベントタイプのフィルタリング -`match.events` を使用してポリシーが発火するタイミングを限定できます: +`match.events` を使用して、ポリシーが発火するタイミングを制限します: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // セッションが終了したときのみ発火する - // ctx.session.transcriptPath にはセッションの完全なログが含まれる + // セッション終了時のみ発火 + // ctx.session.transcriptPath にセッションの完全なログが含まれる return allow(); }, }); @@ -249,17 +249,17 @@ customPolicies.add({ ## エラー処理と障害モード -カスタムポリシーは**フェイルオープン**です。エラーが発生しても組み込みポリシーをブロックしたり、フックハンドラーをクラッシュさせたりすることはありません。 +カスタムポリシーは**フェイルオープン**です。エラーが発生しても、組み込みポリシーをブロックしたり、フックハンドラをクラッシュさせたりすることはありません。 | 障害 | 動作 | |---------|----------| -| `customPoliciesPath` が未設定 | 明示的なカスタムポリシーは実行されない。規約ポリシーと組み込みポリシーは通常通り継続する | -| ファイルが見つからない | `~/.failproofai/hook.log` に警告が記録される。組み込みポリシーは継続する | -| 構文/インポートエラー（明示的） | `~/.failproofai/hook.log` にエラーが記録される。明示的なカスタムポリシーはスキップされる | -| 構文/インポートエラー（規約） | エラーが記録される。そのファイルはスキップされ、他の規約ファイルは引き続き読み込まれる | -| `fn` が実行時に例外をスロー | エラーが記録される。そのフックは `allow` として処理される。他のフックは継続する | -| `fn` が10秒以上かかる | タイムアウトが記録される。`allow` として処理される | -| 規約ディレクトリが存在しない | 規約ポリシーは実行されない。エラーなし | +| `customPoliciesPath` が未設定 | 明示的なカスタムポリシーは実行されない；規約ポリシーと組み込みポリシーは正常に続行 | +| ファイルが見つからない | 警告が `~/.failproofai/hook.log` に記録される；組み込みポリシーは続行 | +| 構文/インポートエラー（明示的） | エラーが `~/.failproofai/hook.log` に記録される；明示的なカスタムポリシーはスキップ | +| 構文/インポートエラー（規約） | エラーが記録される；そのファイルはスキップされ、他の規約ファイルは引き続き読み込まれる | +| 実行時に `fn` が例外をスロー | エラーが記録される；そのフックは `allow` として扱われ、他のフックは続行 | +| `fn` が10秒以上かかる | タイムアウトが記録される；`allow` として扱われる | +| 規約ディレクトリが存在しない | 規約ポリシーは実行されない；エラーなし | カスタムポリシーのエラーをデバッグするには、ログファイルを監視してください: @@ -277,7 +277,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", @@ -290,7 +290,7 @@ customPolicies.add({ }, }); -// エージェントを軌道に乗せる: コミット前にテストを確認する +// エージェントを軌道修正: コミット前にテストを確認 customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -305,7 +305,7 @@ customPolicies.add({ }, }); -// フリーズ期間中の計画外の依存関係変更を防ぐ +// フリーズ期間中の計画外の依存関係変更を防止 customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -326,33 +326,33 @@ export { customPolicies }; --- -## サンプル +## 例 -`examples/` ディレクトリにはすぐに実行できるポリシーファイルが含まれています: +`examples/` ディレクトリには、すぐに使えるポリシーファイルが含まれています: | ファイル | 内容 | |------|----------| -| `examples/policies-basic.js` | 一般的なエージェント障害モードをカバーする5つのスターターポリシー | -| `examples/policies-advanced/index.js` | 高度なパターン: 推移的インポート、非同期呼び出し、出力スクラビング、セッション終了フック | -| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.envへの書き込みをブロック、gitヒストリーの書き換えを防止） | -| `examples/convention-policies/workflow-policies.mjs` | 規約ベースのワークフローポリシー（テストリマインダー、監査ファイル書き込み） | +| `examples/policies-basic.js` | よくあるエージェントの障害モードをカバーする5つのスターターポリシー | +| `examples/policies-advanced/index.js` | 高度なパターン: 推移的インポート、非同期呼び出し、出力のスクラビング、セッション終了フック | +| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.envファイルへの書き込みのブロック、gitヒストリーの書き換え防止） | +| `examples/convention-policies/workflow-policies.mjs` | 規約ベースのワークフローポリシー（テストリマインダー、ファイル書き込みの監査） | -### 明示的なファイルサンプルの使用方法 +### 明示的なファイルの例を使用する ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### 規約ベースのサンプルの使用方法 +### 規約ベースの例を使用する ```bash -# プロジェクトレベルにコピーする +# プロジェクトレベルにコピー mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# またはユーザーレベルにコピーする +# またはユーザーレベルにコピー mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -インストールコマンドは不要です。次のフックイベント時にファイルが自動的に検出されます。 \ No newline at end of file +インストールコマンドは不要です。次のフックイベント時に自動的にファイルが読み込まれます。 \ No newline at end of file diff --git a/docs/ja/dashboard.mdx b/docs/ja/dashboard.mdx index 6924e82c..21b1a6c9 100644 --- a/docs/ja/dashboard.mdx +++ b/docs/ja/dashboard.mdx @@ -4,7 +4,7 @@ description: "エージェントセッションの監視、ツール呼び出し icon: chart-line --- -failproofai ダッシュボードは、AIエージェントセッションの監視とポリシー管理のためのローカルWebアプリケーションです。離席中にエージェントが何をしたかを確認できます。 +failproofaiダッシュボードは、AIエージェントセッションの監視とポリシー管理を行うローカルWebアプリケーションです。離席中にエージェントが何をしていたかを確認できます。 --- @@ -16,77 +16,77 @@ failproofai `http://localhost:8020` で開きます。 -ダッシュボードはローカルのプロジェクト、セッション、failproofai 設定データをファイルシステムから直接読み取ります。監査リマインダーや招待状などの認証が必要なオプション機能は、該当リクエストに必要な情報（メールアドレスを含む）をリモートAPIに送信します。 +ダッシュボードは、ローカルのプロジェクト・セッション・failproofai設定データをファイルシステムから直接読み取ります。監査リマインダーや招待などの認証が必要なオプション機能は、そのリクエストに必要な情報（メールアドレスを含む）をリモートAPIに送信します。 --- -## ページ +## ページ一覧 ### プロジェクト -マシン上で見つかったすべての Claude Code、OpenAI Codex、GitHub Copilot CLI _(beta)_、Cursor Agent _(beta)_、OpenCode _(beta)_、Pi _(beta)_、Hermes、OpenClaw、Factory Droid、Devin、Antigravity、Goose のプロジェクトを一覧表示します。Claude プロジェクトは `~/.claude/projects/`（または `CLAUDE_PROJECTS_PATH` で設定されたパス）から検出されます。Codex プロジェクトは `~/.codex/sessions///
/*.jsonl` 配下のすべてのトランスクリプトをスキャンし、各セッションの最初のレコードに記録された `cwd` でグループ化して検出されます。Copilot CLI プロジェクトは各 `~/.copilot/session-state//workspace.yaml`（`COPILOT_HOME` で変更可能）をスキャンし、`cwd` フィールドでグループ化して検出されます。Cursor Agent プロジェクトは `~/.cursor/agent-sessions//`（`CURSOR_HOME` で変更可能。フォールバックとして `conversations/` と `sessions/` も探索）配下のセッションごとのメタデータから `meta.json` / `session.json` / `workspace.yaml` 内の `cwd` スカラーをもとに検出されます。OpenCode プロジェクトは `~/.local/share/opencode/opencode.db` にある SQLite DB を `opencode db --format json` 経由でクエリし（`session` と `project` テーブルを読み取り `project_id` でグループ化）検出されます。Pi プロジェクトは `~/.pi/agent/sessions//_.jsonl`（`PI_SESSIONS_DIR` で変更可能）配下のセッションごとの JSONL トランスクリプトをスキャンし、各セッションの最初のレコードから `cwd` を取得して検出されます。Hermes ゲートウェイセッションはすべてのプロファイルの SQLite ストア（`~/.hermes/state.db` および `~/.hermes/profiles//state.db`。`HERMES_HOME` または単一データベース用の `HERMES_DB_PATH` で上書き可能）から直接読み取られ、プロファイルと `source`（Slack/Telegram/cli/cron — ゲートウェイセッションには cwd がありません）ごとに `hermes--` プロジェクトとしてグループ化されます。OpenClaw ゲートウェイセッションは `~/.openclaw/agents//sessions/*.jsonl` から読み取られ、エージェントとチャンネルごとに `openclaw--` プロジェクトとしてグループ化されます（こちらも cwd なし）。Factory Droid プロジェクトは `~/.factory/sessions//*.jsonl` の JSONL トランスクリプトから cwd でグループ化して検出されます。Devin プロジェクトは `~/.local/share/devin/cli/sessions.db` の SQLite DB から（各セッションの `working_directory` でグループ化）検出されます。Antigravity プロジェクトは `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` の JSONL トランスクリプトから cwd でグループ化して検出されます。Goose プロジェクトは `~/.local/share/goose/sessions/sessions.db` の SQLite DB から（各セッションの `working_dir` でグループ化）検出されます。複数の CLI で使用されたプロジェクトは、一致するすべてのバッジを持つ単一の行として表示されます。テーブル上部の **CLI** ドロップダウンで特定のエージェント CLI に絞り込めます。URLには選択内容が `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` として保持されます。 +マシン上で見つかったすべての Claude Code、OpenAI Codex、GitHub Copilot CLI _(ベータ)_、Cursor Agent _(ベータ)_、OpenCode _(ベータ)_、Pi _(ベータ)_、Hermes、OpenClaw、Factory Droid、Devin、Antigravity、Gooseプロジェクトを一覧表示します。Claudeプロジェクトは `~/.claude/projects/`（または `CLAUDE_PROJECTS_PATH` で設定されたパス）から検出されます。Codexプロジェクトは `~/.codex/sessions///
/*.jsonl` 配下のすべてのトランスクリプトをスキャンし、各セッションの最初のレコードに記録された `cwd` でグループ化することで検出されます。Copilot CLIプロジェクトは各 `~/.copilot/session-state//workspace.yaml`（`COPILOT_HOME` で設定可能）をスキャンし、その `cwd` フィールドでグループ化することで検出されます。Cursor Agentプロジェクトは `~/.cursor/agent-sessions//`（`CURSOR_HOME` で設定可能、フォールバックとして `conversations/` と `sessions/` を検索）配下のセッションごとのメタデータをスキャンし、`meta.json` / `session.json` / `workspace.yaml` 内の `cwd` スカラーを取得することで検出されます。OpenCodeプロジェクトは `~/.local/share/opencode/opencode.db` にあるSQLite DBを `opencode db --format json` 経由でクエリすることで検出されます（`session` および `project` テーブルを読み取り、`project_id` でグループ化）。Piプロジェクトは `~/.pi/agent/sessions//_.jsonl`（`PI_SESSIONS_DIR` で設定可能）配下のセッションごとのJSONLトランスクリプトをスキャンし、各セッションの最初のレコードから `cwd` を取得することで検出されます。HermesゲートウェイセッションはすべてのプロファイルのSQLiteストアから直接読み取られます（`~/.hermes/state.db` と `~/.hermes/profiles//state.db`、`HERMES_HOME` または単一データベースの場合は `HERMES_DB_PATH` で上書き可能）。プロファイルと `source`（Slack/Telegram/cli/cron — ゲートウェイセッションにはcwdがありません）によって `hermes--` プロジェクトにグループ化されます。OpenClawゲートウェイセッションは `~/.openclaw/agents//sessions/*.jsonl` から読み取られ、エージェントとチャンネルによって `openclaw--` プロジェクトにグループ化されます（こちらもcwdなし）。Factory Droidプロジェクトは `~/.factory/sessions//*.jsonl` のJSONLトランスクリプトからcwdでグループ化して検出されます。DevinプロジェクトはSQLite DB `~/.local/share/devin/cli/sessions.db`（各セッションの `working_directory` でグループ化）から検出されます。AntigravityプロジェクトはJSONLトランスクリプト `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` からcwdでグループ化して検出されます。GooseプロジェクトはSQLite DB `~/.local/share/goose/sessions/sessions.db`（各セッションの `working_dir` でグループ化）から検出されます。複数のCLIで使用されているプロジェクトは、該当するすべてのバッジを持つ1行として表示されます。テーブル上部の **CLI** ドロップダウンを使用して特定のエージェントCLIでフィルタリングできます。URLには選択内容が `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` として保持されます。 -Hermes と OpenClaw はユーザースコープでグループ化に使える作業ディレクトリがないため、**折りたたみ可能なフォルダーツリー**（トップレベルにプロファイルまたはエージェント、その下にチャンネル）として表示されます。cwd ベースの CLI はすべてフラットな行のまま表示されます。フォルダー行はその配下のセッション数と最新のアクティビティをロールアップ表示し、折りたたみ状態は訪問間で記憶されます。キーワード検索は一致するものを自動的に展開します。 +HermesとOpenClawはユーザースコープでグループ化できる作業ディレクトリがないため、**折りたたみ可能なフォルダツリー**として表示されます（トップレベルにプロファイルまたはエージェント、その下にチャンネル）。一方、cwdベースのすべてのCLIはフラットな行として表示されます。フォルダ行はその配下のすべてのセッション数と最新アクティビティを集計し、折りたたまれたフォルダは訪問間で記憶され、キーワード検索では一致したものが展開されます。 -各プロジェクトの表示内容： -- プロジェクト名（フォルダーパスから派生） -- CLI バッジ — `Claude Code`（オレンジ）、`OpenAI Codex`（パープル）、`GitHub Copilot`（ブルー）、`Cursor Agent`（エメラルド）、`OpenCode`（アンバー）、`Pi`（ピンク）、`Hermes`（インディゴ） -- 最新セッションアクティビティの日付 +各プロジェクトには以下が表示されます: +- プロジェクト名（フォルダパスから導出） +- CLIバッジ — `Claude Code`（オレンジ）、`OpenAI Codex`（パープル）、`GitHub Copilot`（ブルー）、`Cursor Agent`（エメラルド）、`OpenCode`（アンバー）、`Pi`（ピンク）、および/または `Hermes`（インディゴ） +- 最終セッションアクティビティの日時 -プロジェクトをクリックするとそのセッションが表示されます。 +プロジェクトをクリックするとそのセッション一覧が表示されます。 ### セッション -プロジェクト内のすべてのセッションを一覧表示します。各セッションの表示内容： -- セッション ID +プロジェクト内のすべてのセッションを一覧表示します。各セッションには以下が表示されます: +- セッションID - 開始・終了タイムスタンプ - ツール呼び出し数 - フックアクティビティ数（発動したポリシー数） -日付範囲フィルターとセッション ID 検索で絞り込めます。セッションはページネーション表示されます。 +日付範囲フィルターとセッションID検索を使用して絞り込みができます。セッションはページネーションされます。 セッションをクリックするとセッションビューアーが開きます。 ### セッションビューアー -セッションビューアーは自律エージェントにとっての核心的な問いに答えます：エージェントは何をしたか、そして正しく動作していたか？ヘッダー横の CLI バッジは、そのセッションが Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity、Goose のどのトランスクリプトかを示します。セッション内で起きたすべての出来事のタイムラインを表示します： +セッションビューアーは自律エージェントにとって重要な問いに答えます：エージェントは何をしたのか、そして正しく動作していたのか？ヘッダーの横にあるCLIバッジは、そのセッションが Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity、またはGooseのトランスクリプトであるかを示します。セッションで発生したすべての出来事のタイムラインが表示されます: -- **メッセージ** — Claude のテキスト応答とユーザープロンプト -- **ツール呼び出し** — Claude が呼び出したすべてのツール（入力と出力を含む） -- **ポリシーアクティビティ** — 各ツール呼び出しについて、どのポリシーが発動し、どの判定が返されたか +- **メッセージ** - Claudeのテキストレスポンスとユーザープロンプト +- **ツール呼び出し** - Claudeが呼び出したすべてのツールとその入力・出力 +- **ポリシーアクティビティ** - 各ツール呼び出しに対して発動したポリシーとその判断結果 -上部のステータスバーにはセッション時間、ツール呼び出しの合計数、フック判定のサマリー（allow / deny / instruct の件数）が表示されます。 +上部のスタットバーにはセッション時間、総ツール呼び出し数、フック判断のサマリー（allow / deny / instruct の件数）が表示されます。 -**Download Logs** ボタンをクリックするとセッションをエクスポートできます。Claude Code、Codex、Copilot、Cursor、Pi のセッションはディスク上の元の JSONL トランスクリプトをバイト単位でそのまま取得できます。OpenCode（セッションがディスクではなく SQLite に保存されます）の場合は、基盤となる `session` / `messages` / `parts` テーブルを反映した JSON ドキュメントを取得できます。 +**ログをダウンロード**ボタンをクリックしてセッションをエクスポートできます。Claude Code、Codex、Copilot、Cursor、Piセッションの場合はディスク上の元のJSONLトランスクリプトをバイト単位でそのまま取得できます。OpenCode（セッションがディスクではなくSQLiteに保存されている）の場合は、基となる `session` / `messages` / `parts` テーブルを反映したJSONドキュメントが得られます。 ### 監査 -過去のセッションにわたってエージェントが実際にどのように振る舞っているかをパーソナリティ主導でレポートします。`failproofai audit` CLI と同じスキャンを実行し、シングルスクリーンの共有可能なポスターとスクロール下の4つのセクションとしてレンダリングします： +過去のセッションを通じてエージェントが実際にどのように動作してきたかを、個性的なレポートとして表示します。`failproofai audit` CLIと同じスキャンを実行しますが、1画面で共有可能なポスター＋折り畳み以下の4セクションとしてレンダリングします: -1. **ポスター** — 最初のビューポートを占有します。failproof_ai ワードマーク + 監査ラベル · アーキタイプインデックス（`№ NN of 08`）+ 監査日 · 数値スコア（0～100）+ パーセンタイルランクピル（`top 15%`）· アーキタイプ名（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` のいずれか）+ 3キーワードストリップ · `// only N% of agents are this archetype` レアリティライン · 8×8 ピクセルのシジルタイル · `audit yours → failproof.ai` フッターを含む、PNG キャプチャ領域として自己完結しています。キャプチャ枠の外側に3つのシェアボタン（`post your archetype`（X インテント）、`share on linkedin`、`download poster`）があります。キャプチャは `html-to-image` を通じて実行されるため、PNG は画面上のレンダリングとピクセル単位で一致します（破線ボーダー、SVG ロゴマスク、グラデーション、フォントメトリクス — すべて保持されます）。 -2. **強み** — エージェントがすでに正しく実行している動作の落ち着いた ✓ 行リスト。ライブ監査データ（クリーンなツール呼び出し率、main への直接プッシュなし、認証情報漏洩ゼロ、リトライストームゼロ）から導出され、関連ポリシーが監査ウィンドウ全体でクリーンな記録を持つ場合にのみ表示されます。 -3. **クセ** — 見逃された問題の表。重大度順にランク付け：`発生時刻 · 何が漏れたか + それを捕捉するはずだったポリシー · 重大度ピル · 発生回数`。再発件数は `new`（1回）、`N× seen`（2～9回）、`recurring`（10回以上）と表示されます。 -4. **改善方法** — 推奨ポリシーごとの落ち着いた行リスト：白文字のポリシー名、1行の説明、右側にインストールコマンドとコピーボタン。セクションヘッダーには `enable all N → projected · `（すべての修正を適用した場合に到達するスコア）と表示され、`[install all]` ボタンは推奨されるすべてのポリシーの `failproofai policy add a b c …` コマンドをまとめてコピーします。 -5. **次回に備えて** — 横並びの2枚のカード。左：リマインダーの設定（`3d` / `7d` / `14d` / `30d` のケイデンスピッカー。認証後に `/api/auth/reminder` を通じて永続化）。右：failproof 特典のアンロック — `invite a friend` はモーダルを開き、カンマ・スペース・改行で区切られた友人のメールアドレスリスト（1回の送信で最大10件）を受け取り、`/api/audit/invite` に POST します。これが api-server の `POST /v0/invite` に転送されます。api-server は `invite@failproof.ai` から受信者1人につき1通のメールを送信し、送信者を Cc に含めて `Reply-To` を設定します。これにより受信者は誰が招待したかがわかり、送信者も自分の受信トレイにコピーを受け取ります。匿名ユーザーは招待送信前に送信者のメールアドレスを確認するため、最初に `AuthDialog` にルーティングされます。資格・特典の付与は今後の対応となります。 +1. **ポスター** — 最初のビューポートを埋めます。failproof_aiワードマーク＋監査ラベル・アーキタイプインデックス（`№ NN of 08`）＋監査日・数値スコア（0〜100）＋パーセンタイルランクピル（`top 15%`）・アーキタイプ名（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` のいずれか）＋3キーワードストリップ・`// only N% of agents are this archetype` レアリティライン・8×8ピクセルのシジルタイル・`audit yours → failproof.ai` フッターを含む自己完結型のPNGキャプチャ領域。キャプチャボックスの外側に3つのシェアボタンがあります: `post your archetype`（X intent）、`share on linkedin`、`download poster`。キャプチャは `html-to-image` を通じて実行されるため、PNGは画面上のレンダリングとピクセル単位で一致します（破線ボーダー、SVGロゴマスク、グラデーション、フォントメトリクス — すべて保持）。 +2. **強み** — エージェントがすでに正しく行っている動作を落ち着いた✓行リストで表示。ライブ監査データ（クリーンなツール呼び出し率、mainへの直接プッシュなし、認証情報漏洩ゼロ、リトライストームゼロ）から導出され、監査ウィンドウ全体で関連ポリシーのクリーンな記録がある場合にのみ表示されます。 +3. **問題点** — 漏れがあった内容を深刻度順にランク付けした表: `発生時刻 · 漏れた内容＋検出したはずのポリシー · 深刻度ピル · 発生回数`。繰り返し回数は `new`（1回）、`N× seen`（2〜9回）、または `recurring`（10回以上）と表示されます。 +4. **改善方法** — 推奨ポリシーごとの落ち着いた行リスト: ポリシー名を白で表示、1行説明、右側にインストールコマンド＋コピーボタン。セクションヘッダーには `enable all N → projected · `（すべての修正を適用した場合に到達するスコア）と表示され、`[install all]` ボタンは推奨ポリシー全てに対する `failproofai policy add a b c …` コマンドをまとめてコピーします。 +5. **より良い状態で戻ってくる** — 2つの横並びカード。左: リマインダーの設定（`3d` / `7d` / `14d` / `30d` のケイデンスピッカー。認証後に `/api/auth/reminder` を通じて保持）。右: failproofの特典をアンロック — `invite a friend` はモーダルを開き、カンマ・スペース・改行区切りの友人メールアドレスのリスト（送信ごとに最大10件）を入力できます。`/api/audit/invite` にPOSTされ、api-serverの `POST /v0/invite` に転送されます。api-serverは各受信者に `invite@failproof.ai` からメールを送信し、送信者はCcに追加され `Reply-To` が設定されるため、受信者は誰が招待したかを確認でき、送信者は受信トレイにコピーを受け取れます。匿名ユーザーは招待を送信する前に送信者のメールアドレスが確認されるよう、まず `AuthDialog` を経由するルートが設定されます。権限・特典の提供については後日対応予定です。 -`failproofai audit` ランタイムによって駆動されます — 基盤となるスキャンエンジン、サポートされるフラグ、トランスクリプトごとのキャッシュの不変条件については [Audit CLI](/ja/cli/audit) を参照してください。ダッシュボードは最新の結果を `~/.failproofai/audit-dashboard.json`（モード `0600`、シングルスロット、新しい実行で上書き）にキャッシュするため、再訪問は即座に表示されます。**トランスクリプトごとのキャッシュと全体結果のキャッシュはどちらも、7日を超えた時点で読み取り時に破棄されます**。これによりダッシュボードが1週間前の古い結果を暗黙的に提供することはありません — TTL を過ぎると `/audit` は空の状態にフォールスルーし、新しい実行を促します。レポート下部の `[ re-audit now ]` をクリックすると `noCache: true` で `/api/audit/run` に POST されます — 再監査はトランスクリプトごとのキャッシュをバイパスし、キャッシュ済み結果を暗黙的に返すのではなく、すべてのトランスクリプトをゼロから再スキャンします — ダッシュボードは実行が完了するまで 1Hz で `/api/audit/status` をポーリングします。実行中は経過タイマーとともにピンクのプログレスストリップがビューポートの上部に固定表示され、成功時には新しい結果がページの全体リロードなしにその場で差し替えられます。再監査に失敗した場合、ストリップは赤に変わり、`RerunError.kind`（`timeout` / `network` / `post_failed`）に応じたコピーが表示され、前のレポートはそのまま維持されます。空の状態（キャッシュなしまたは期限切れ）とセッションゼロの状態（キャッシュは存在するがスキャンでトランスクリプトが見つからなかった）は個別に表示されます。 +`failproofai audit` ランタイムによって動作します。基となるスキャンエンジン、サポートされているフラグ、トランスクリプトごとのキャッシュ不変条件については [Audit CLI](/ja/cli/audit) を参照してください。ダッシュボードは最新の結果を `~/.failproofai/audit-dashboard.json`（モード `0600`、シングルスロット、新しい実行で上書き）にキャッシュするため、再訪問は即座に表示されます。**トランスクリプトごとおよびリザルト全体のキャッシュは、7日以上経過すると読み込み時に拒否される**ため、ダッシュボードが1週間前の古い結果をサイレントに返すことはありません。TTLを超えると `/audit` は空の状態に移行し、新しい実行を促します。レポート下部の `[ re-audit now ]` をクリックすると `noCache: true` で `/api/audit/run` にPOSTします。再監査はトランスクリプトごとのキャッシュをバイパスし、キャッシュされた結果をサイレントに返すのではなく、すべてのトランスクリプトを最初からスキャンし直します。ダッシュボードは実行が完了するまで1Hzで `/api/audit/status` をポーリングします。実行中はビューポート上部にスティッキーなピンクのプログレスストリップが経過タイマーとともに固定表示され、成功すると新しい結果がその場で入れ替わります（フルページリロードなし）。再監査が失敗した場合は以前のレポートがそのまま表示されます。失敗時にはストリップが赤くなり、`RerunError.kind`（`timeout` / `network` / `post_failed`）に対応したコピーが表示されます。空の状態（キャッシュなしまたは期限切れ）とセッションゼロの状態（キャッシュは存在するがスキャンでトランスクリプトが見つからなかった）は別々に表示されます。 ### ポリシー -ポリシーの管理とアクティビティの確認のための2タブページです。 +ポリシーの管理とアクティビティの確認を行う2タブのページです。 - - 単一パネルから failproofai が保護するエージェント CLI を複数選択できます — Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi、Hermes のそれぞれに、インストール状態（`Active` / `Detected` / `Inactive`）、ユーザースコープの設定パス、ブランドカラーのアクセントを持つ行があります。保護したい CLI にチェックを入れ、`Apply changes` をクリックすると差分を一括でインストール/アンインストールできます。PATH 上でバイナリが検出された CLI はあらかじめチェックされています。 - - ワンクリックで個別ポリシーのオン/オフを切り替えられます（`~/.failproofai/policies-config.json` に書き込まれ、インストールされているすべての CLI 間で共有されます） - - ポリシーを展開してパラメーターを設定できます（`policyParams` をサポートするポリシーの場合） - - カスタムポリシーファイルのパスを設定できます + - 単一パネルからfailproofaiが保護するエージェントCLIを複数選択 — Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi、Hermesはそれぞれインストール状態（`Active` / `Detected` / `Inactive`）、ユーザースコープの設定パス、ブランドカラーのアクセントを持つ行として表示されます。保護したいCLIにチェックを入れ `Apply changes` をクリックすると、差分のインストール/アンインストールが1ステップで実行されます。PATHで検出されたバイナリを持つCLIは事前にチェックされます。 + - ワンクリックで個々のポリシーのオン/オフを切り替え（`~/.failproofai/policies-config.json` に書き込み — インストールされているすべてのCLIで共有） + - ポリシーを展開してパラメーターを設定（`policyParams` をサポートするポリシーの場合） + - カスタムポリシーファイルパスの設定 - - すべてのセッションにわたって発動したすべてのフックイベントの完全なページネーション付き履歴 - - 判定、イベントタイプ、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、ポリシー名、またはセッション ID でフィルタリング - - 各行の表示内容：タイムスタンプ、ポリシー名、判定、CLI バッジ（オレンジ = Claude Code、パープル = OpenAI Codex、ブルー = GitHub Copilot、エメラルド = Cursor Agent、アンバー = OpenCode、ピンク = Pi、インディゴ = Hermes、ティール = OpenClaw、ローズ = Factory Droid、バイオレット = Devin、シアン = Antigravity、ライム = Goose）、ツール名、セッション ID、deny/instruct 判定の理由 - - セッション ID をクリックするとそのトランスクリプトが開きます — ビューアーはフックを発動した CLI を自動検出し（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state//events.jsonl`、Cursor Agent `~/.cursor/agent-sessions//events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions//.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents//sessions/*.jsonl`、Factory Droid `~/.factory/sessions//.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`）、ヘッダーに一致する CLI バッジをレンダリングします + - すべてのセッションにわたって発動したすべてのフックイベントの完全なページネーション履歴 + - 判断、イベントタイプ、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(ベータ)_ / Cursor Agent _(ベータ)_ / OpenCode _(ベータ)_ / Pi _(ベータ)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、ポリシー名、またはセッションIDでフィルタリング + - 各行には: タイムスタンプ、ポリシー名、判断、CLIバッジ（オレンジ = Claude Code、パープル = OpenAI Codex、ブルー = GitHub Copilot、エメラルド = Cursor Agent、アンバー = OpenCode、ピンク = Pi、インディゴ = Hermes、ティール = OpenClaw、ローズ = Factory Droid、バイオレット = Devin、シアン = Antigravity、ライム = Goose）、ツール名、セッションID、deny/instructの判断理由が表示されます + - セッションIDをクリックするとそのトランスクリプトが開きます — ビューアーはフックを発動したCLIを自動検出し（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state//events.jsonl`、Cursor Agent `~/.cursor/agent-sessions//events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions//.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents//sessions/*.jsonl`、Factory Droid `~/.factory/sessions//.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`）、ヘッダーに対応するCLIバッジをレンダリングします @@ -94,25 +94,25 @@ Hermes と OpenClaw はユーザースコープでグループ化に使える作 ## 自動更新 -ダッシュボードには上部ナビゲーションに自動更新トグルがあります。有効にすると、現在のページが定期的に更新され、新しいセッションとポリシーアクティビティがリアルタイムで表示されます。長時間実行される自律エージェントセッションの監視に不可欠です。 +ダッシュボードのトップナビゲーションには自動更新トグルがあります。有効にすると、現在のページが定期的に更新され、新しいセッションとポリシーアクティビティが表示されます。長時間実行される自律エージェントセッションの監視に不可欠な機能です。 --- ## ページの無効化 -ダッシュボードの一部のみ必要な場合は、`FAILPROOFAI_DISABLE_PAGES` にカンマ区切りのページ名リストを設定します： +ダッシュボードの一部のみ必要な場合は、`FAILPROOFAI_DISABLE_PAGES` にカンマ区切りのページ名リストを設定してください: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -有効な値：`policies`、`projects`、`audit`。 +有効な値: `policies`、`projects`、`audit`。 --- ## プロジェクトパスの設定 -デフォルトでは、ダッシュボードは標準の Claude Code プロジェクトディレクトリから読み取ります。カスタム設定の場合は上書きできます： +デフォルトでは、ダッシュボードは標準の Claude Code プロジェクトディレクトリから読み取ります。カスタム設定の場合は上書きしてください: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,32 +120,32 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## localhost 以外のホストからのアクセス +## localhost以外のホストからのアクセス -**dev モード**（`npm run dev`）でダッシュボードを実行し、`localhost` 以外のホスト名（カスタムドメイン、リモート IP、トンネルされた URL など）からアクセスする場合、次のような警告が表示されることがあります： +**devモード**（`npm run dev`）でダッシュボードを実行し、`localhost` 以外のホスト名（カスタムドメイン、リモートIP、トンネルURLなど）からアクセスする場合、次のような警告が表示されることがあります: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -これは Next.js が HMR（ホットモジュールリロード）WebSocket へのクロスオリジンアクセスをブロックしているためです。HMR は dev モード専用の機能です。ホストを許可するには `--allowed-origins` フラグを使用します： +これはNext.jsがHMR（ホットモジュールリロード）WebSocketへのクロスオリジンアクセスをブロックしているためです。HMRはdevのみの機能です。ホストを許可するには `--allowed-origins` フラグを使用してください: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -複数のホストや IP を指定する場合は、カンマ区切りのリストを渡します： +複数のホストやIPの場合は、カンマ区切りのリストを渡します: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -環境変数 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` を使用することもできます： +代わりに `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 環境変数を設定することもできます: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -これは dev モードにのみ適用されます。`failproofai`（プロダクションモード）を実行している場合、HMR WebSocket もクロスオリジン dev リソースの問題も発生しません。 +これはdevモードにのみ適用されます。`failproofai`（本番モード）を実行する場合、HMR WebSocketもクロスオリジンのdevリソースの問題も存在しません。 \ No newline at end of file diff --git a/docs/ja/examples.mdx b/docs/ja/examples.mdx index 56089e1e..e1923968 100644 --- a/docs/ja/examples.mdx +++ b/docs/ja/examples.mdx @@ -1,16 +1,16 @@ --- title: サンプル -description: "Claude Code と Agents SDK にフックを設定する方法" +description: "Claude Code と Agents SDK 向けのフックの設定方法" icon: book-open --- -よくあるシナリオですぐに使えるサンプル集です。それぞれのインストール方法と動作結果を紹介します。 +よく使われるシナリオに対応した、すぐに使えるサンプル集です。それぞれのインストール方法と動作の確認方法を説明します。 --- -## Claude Code にフックを設定する +## Claude Code 向けのフック設定 -Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.com/en/docs/claude-code/hooks)を通じて統合されます。`failproofai policies --install` を実行すると、Claude Code の `settings.json` にフックコマンドが登録され、ツール呼び出しのたびに実行されます。 +Failproof AI は、Claude Code の[フックシステム](https://docs.anthropic.com/en/docs/claude-code/hooks)を通じて統合されます。`failproofai policies --install` を実行すると、Claude Code の `settings.json` にフックコマンドが登録され、すべてのツール呼び出しで発火するようになります。 @@ -23,7 +23,7 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` @@ -35,15 +35,15 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c claude ``` - ポリシーはツール呼び出しのたびに自動的に実行されます。Claude に `sudo rm -rf /` を実行させようとしてみてください。ブロックされます。 + これで、すべてのツール呼び出しに対してポリシーが自動的に適用されます。試しに Claude に `sudo rm -rf /` を実行するよう指示してみてください — ブロックされます。 --- -## Agents SDK にフックを設定する +## Agents SDK 向けのフック設定 -[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) を使って開発している場合、同じフックシステムをプログラムから利用できます。 +[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) を使って開発している場合も、同じフックシステムをプログラムから利用できます。 @@ -52,14 +52,14 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c ``` - エージェントプロセスの作成時にフックコマンドを渡します。フックは Claude Code と同じ方法で、stdin/stdout JSON を介して発火します。 + エージェントプロセスを作成する際にフックコマンドを渡します。フックは Claude Code と同じ方法で発火します — stdin/stdout の JSON を介して通信します： ```bash failproofai --hook PreToolUse # called before each tool failproofai --hook PostToolUse # called after each tool ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -86,35 +86,35 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c --- -## 破壊的なコマンドをブロックする +## 破壊的コマンドをブロックする -最もよくある設定 — エージェントが取り消せないダメージを与えるのを防ぎます。 +最も一般的な設定 — エージェントによる不可逆的な操作を防ぎます。 ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -この設定でできること: +この設定でできること： - `block-sudo` — すべての `sudo` コマンドをブロック - `block-rm-rf` — 再帰的なファイル削除をブロック - `block-force-push` — `git push --force` をブロック -- `block-curl-pipe-sh` — リモートスクリプトをシェルにパイプするのをブロック +- `block-curl-pipe-sh` — リモートスクリプトをシェルにパイプする操作をブロック --- ## シークレットの漏洩を防ぐ -エージェントがツール出力で認証情報を参照・漏洩しないようにします。 +ツールの出力にある認証情報をエージェントが参照・漏洩しないようにします。 ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -これらは `PostToolUse` で発火します。ツール実行後、エージェントが結果を受け取る前に出力をスクラブします。 +これらは `PostToolUse` で発火します — ツールの実行後、エージェントが出力を見る前にスクラブ処理を行います。 --- -## エージェントが応答待ちになったら Slack に通知する +## エージェントが注意を必要とするときに Slack 通知を受け取る 通知フックを使って、アイドル状態のアラートを Slack に転送します。 @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -インストール: +インストール： ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -158,9 +158,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## エージェントをブランチに固定する +## エージェントを特定のブランチに限定する -エージェントが別のブランチに切り替えたり、保護されたブランチにプッシュしたりするのを防ぎます。 +エージェントがブランチを切り替えたり、保護されたブランチにプッシュしたりするのを防ぎます。 ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +184,7 @@ customPolicies.add({ ## コミット前にテストを要求する -コミットする前にテストを実行するようエージェントに促します。 +コミットの前にテストを実行するようエージェントに促します。 ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -208,9 +208,9 @@ customPolicies.add({ ## 本番リポジトリをロックダウンする -プロジェクトレベルの設定をコミットして、チーム全員が同じポリシーを適用できるようにします。 +プロジェクトレベルの設定をコミットして、チームの全員が同じポリシーを適用できるようにします。 -リポジトリに `.failproofai/policies-config.json` を作成します: +リポジトリに `.failproofai/policies-config.json` を作成します： ```json { @@ -231,20 +231,20 @@ customPolicies.add({ } ``` -コミットします: +コミットします： ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -failproofai をインストールしているすべてのチームメンバーが、これらのルールを自動的に取得します。 +failproofai をインストールしているすべてのチームメンバーに、これらのルールが自動的に適用されます。 --- -## コンベンションポリシーで組織全体の品質基準を作る +## コンベンションポリシーで組織全体の品質基準を構築する -最も効果的な設定: プロジェクトに合わせたポリシーを含む `.failproofai/policies/` をリポジトリにコミットします。チームメンバー全員が自動的に取得できます — インストールコマンドも設定変更も不要です。 +最も効果的な設定：プロジェクトに合わせたポリシーを `.failproofai/policies/` にコミットしてリポジトリに含めます。チームの全員がインストールコマンドや設定変更なしに、自動的にポリシーを受け取れます。 @@ -290,7 +290,7 @@ failproofai をインストールしているすべてのチームメンバー ``` - チームが新たな問題に直面したら、ポリシーを追加してプッシュしましょう。次回の `git pull` で全員が更新を受け取ります。これらのポリシーは、チームとともに成長する生きた品質基準となります。 + チームが新しい問題に直面するたびにポリシーを追加してプッシュしてください。全員が次の `git pull` 時に更新を受け取ります。これらのポリシーは、チームとともに成長する生きた品質基準になります。 @@ -298,10 +298,10 @@ failproofai をインストールしているすべてのチームメンバー ## その他のサンプル -リポジトリの [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) ディレクトリには以下が含まれています: +リポジトリの [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) ディレクトリには以下が含まれています： | ファイル | 内容 | |------|---------------| -| `policies-basic.js` | スターターポリシー — 本番環境への書き込み、force-push、パイプスクリプトのブロック | +| `policies-basic.js` | 入門ポリシー — 本番環境への書き込み、force-push、パイプスクリプトのブロック | | `policies-notification.js` | アイドル通知とセッション終了時の Slack アラート | -| `policies-advanced/index.js` | 推移的インポート、非同期フック、PostToolUse 出力スクラブ、Stop イベント処理 | \ No newline at end of file +| `policies-advanced/index.js` | 推移的インポート、非同期フック、PostToolUse による出力スクラブ、Stop イベント処理 | \ No newline at end of file diff --git a/docs/ja/for-agents.mdx b/docs/ja/for-agents.mdx index 3df579d3..1abd5a07 100644 --- a/docs/ja/for-agents.mdx +++ b/docs/ja/for-agents.mdx @@ -1,9 +1,9 @@ --- title: "エージェント向け" -description: "1つのコマンドでFailproof AIの知識をコーディングエージェントに追加できます。Claude Code、Cursor、Windsurfなど様々なエージェントに対応しています。" +description: "1つのコマンドでFailproof AI のナレッジをコーディングエージェントに追加できます。Claude Code、Cursor、Windsurf などに対応しています。" --- -1つのコマンドで、Failproof AIのリファレンス全体をコーディングエージェントに追加できます。Claude Code、Cursor、Windsurf、そしてスキルをサポートするその他のエージェントでも動作します。 +1つのコマンドで Failproof AI の完全なリファレンスをコーディングエージェントに追加できます。Claude Code、Cursor、Windsurf、およびスキルをサポートする他のエージェントに対応しています。 ```bash npx skills add https://docs.befailproof.ai @@ -13,21 +13,21 @@ npx skills add https://docs.befailproof.ai ## スキルがカバーする内容 -| 分野 | 含まれる内容 | +| 領域 | 含まれる内容 | |------|-------------| -| ポリシー | 組み込みポリシー名、イベントタイプ、パラメータ、有効化/無効化 | +| ポリシー | 組み込みポリシー名、イベントタイプ、パラメーター、有効化/無効化 | | カスタムポリシー | `customPolicies.add()`、マッチフィルター、`allow`/`deny`/`instruct` API | | コンテキストオブジェクト | `ctx.eventType`、`ctx.toolName`、`ctx.toolInput`、`ctx.session` | | 設定 | `policies-config.json` の構造、スコープのマージ、`policyParams` | | CLI | `failproofai policies --install`、`--uninstall`、`--custom`、スコープ | -| ダッシュボード | セッションビューア、ポリシーアクティビティ、環境変数 | +| ダッシュボード | セッションビューアー、ポリシーアクティビティ、環境変数 | | アーキテクチャ | フックハンドラーのフロー、終了コード、stdin/stdout の仕様 | ## スキルの内容は完全ですか？ -Mintlify はナビゲーション内の全ページから `llms.txt` を生成します。Failproof AI のドキュメントは完全な API をカバーしており、すべてのポリシー、オプション、サンプルが含まれています。不足している情報があれば、ソースは `https://docs.befailproof.ai/llms-full.txt` から確認できます。 +Mintlify はナビゲーション内のすべてのページから `llms.txt` を生成します。Failproof AI のドキュメントは完全な API をカバーしており、すべてのポリシー、オプション、サンプルが含まれています。不足している内容が見つかった場合は、`https://docs.befailproof.ai/llms-full.txt` がソースです。 -特定のコンテキストだけが必要な場合は、特定のページに直接リンクすることも可能です： +特定のコンテキストだけが必要な場合は、特定のページに直接リンクできます： ```bash # カスタムポリシー API のみ diff --git a/docs/ja/getting-started.mdx b/docs/ja/getting-started.mdx index 3451c9e6..091c55ee 100644 --- a/docs/ja/getting-started.mdx +++ b/docs/ja/getting-started.mdx @@ -1,13 +1,13 @@ --- title: はじめに -description: "failproofai をインストールし、ポリシーを有効にして、エージェントを安定稼働させましょう" +description: "failproofai をインストールし、ポリシーを有効化して、エージェントを安定して動作させましょう" icon: rocket --- ## 必要要件 - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (オプション - ソースからビルドする場合のみ必要) +- **Bun** >= 1.3.0（オプション — ソースからビルドする場合のみ必要） --- @@ -30,16 +30,16 @@ bun add -g failproofai ## クイックスタート - - ポリシーとは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンド、シークレットの漏洩、その他の障害モードを、被害が発生する前に検出します。 + + ポリシーとは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンド、シークレットの漏洩、その他の障害パターンを、実害が出る前に検知します。 ```bash failproofai policies --install ``` - このコマンドは、インストール済みのエージェント CLI にフックエントリを書き込みます（Claude Code の `~/.claude/settings.json`、OpenAI Codex の `~/.codex/hooks.json`、GitHub Copilot CLI の `~/.copilot/hooks/failproofai.json`、Cursor Agent の `~/.cursor/hooks.json`、OpenCode の `~/.config/opencode/plugins/failproofai.mjs` と `~/.config/opencode/opencode.json` の `plugin` 配列へのエントリ、Pi の `~/.pi/agent/settings.json`、Hermes の `~/.hermes/config.yaml`、OpenClaw の `~/.openclaw/openclaw.json`、Factory Droid の `~/.factory/hooks.json`、Devin CLI の `~/.config/devin/config.json`、Antigravity CLI の `~/.gemini/config/hooks.json`、または Goose の自動検出プラグインディレクトリ `~/.agents/plugins/failproofai/hooks/hooks.json`）。複数がインストールされている場合は選択を促すプロンプトが表示されます。`--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose`（任意のサブセット）を指定するとプロンプトをスキップできます。 + このコマンドは、インストール済みのエージェント CLI にフックエントリを書き込みます（Claude Code の `~/.claude/settings.json`、OpenAI Codex の `~/.codex/hooks.json`、GitHub Copilot CLI の `~/.copilot/hooks/failproofai.json`、Cursor Agent の `~/.cursor/hooks.json`、OpenCode の `~/.config/opencode/plugins/failproofai.mjs` へ生成されるプラグインシムおよび `~/.config/opencode/opencode.json` の `plugin` 配列への登録エントリ、Pi の `~/.pi/agent/settings.json`、Hermes の `~/.hermes/config.yaml`、OpenClaw の `~/.openclaw/openclaw.json`、Factory Droid の `~/.factory/hooks.json`、Devin CLI の `~/.config/devin/config.json`、Antigravity CLI の `~/.gemini/config/hooks.json`、または Goose の自動検出プラグインディレクトリ `~/.agents/plugins/failproofai/hooks/hooks.json`）。複数がインストールされている場合はプロンプトが表示されます。`--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose`（任意のサブセット）を渡すとプロンプトをスキップできます。 - GitHub Copilot CLI、Cursor Agent、OpenCode、Pi のサポートは**ベータ版**です。それぞれ `--cli copilot`、`--cli cursor`、`--cli opencode`、`--cli pi` でインストールしてください。Hermes（hermes-agent、Slack/Telegram ゲートウェイ）は `--cli hermes` でユーザースコープにインストールされ、**オフライン監査ソース**としても機能します。OpenClaw（openclaw ゲートウェイ、セルフホスト型マルチチャンネルアシスタント）は `--cli openclaw` でユーザースコープにインストールされ、インプロセスのプラグインフック（`before_agent_finalize` は実際のターン終了ゲートとして機能するため、`require-*-before-stop` 組み込みポリシーが有効）を通じてポリシーが適用されます。また**オフライン監査ソース**としても機能します。Factory Droid（`droid`）は `--cli factory`（ユーザー + プロジェクトスコープ）でインストールされ、**オフライン監査ソース**としても機能します。Devin CLI（`devin`、Cognition）は `--cli devin`（ユーザー + プロジェクトスコープ）でインストールされ、**オフライン監査ソース**としても機能します。Antigravity CLI（`agy`）は `--cli antigravity`（ユーザー + プロジェクトスコープ）でインストールされ、**オフライン監査ソース**としても機能します。Goose（コードネーム goose、Block）は `--cli goose`（ユーザー + プロジェクトスコープ）でインストールされます。インストーラーは `~/.agents/plugins/failproofai/` にプラグインディレクトリを作成するだけで、Goose が自動検出します。また**オフライン監査ソース**としても機能します。 + GitHub Copilot CLI、Cursor Agent、OpenCode、Pi のサポートは **ベータ版** です — それぞれ `--cli copilot`、`--cli cursor`、`--cli opencode`、`--cli pi` を指定してインストールしてください。Hermes（hermes-agent、Slack/Telegram ゲートウェイ）は `--cli hermes` でユーザースコープにインストールされ、**オフライン監査ソースでもあります**。OpenClaw（openclaw ゲートウェイ、セルフホスト型マルチチャンネルアシスタント）は `--cli openclaw` でユーザースコープにインストールされ、インプロセスのプラグインフック（`before_agent_finalize` はターン終了の実際のゲートとして機能するため、`require-*-before-stop` の組み込みポリシーが適用されます）を通じてポリシーが実行され、**オフライン監査ソースでもあります**。Factory Droid（`droid`）は `--cli factory`（ユーザー + プロジェクトスコープ）でインストールされ、**オフライン監査ソースでもあります**。Devin CLI（`devin`、Cognition）は `--cli devin`（ユーザー + プロジェクトスコープ）でインストールされ、**オフライン監査ソースでもあります**。Antigravity CLI（`agy`）は `--cli antigravity`（ユーザー + プロジェクトスコープ）でインストールされ、**オフライン監査ソースでもあります**。Goose（コードネーム goose、Block）は `--cli goose`（ユーザー + プロジェクトスコープ）でインストールされます — インストーラーは `~/.agents/plugins/failproofai/` にプラグインディレクトリを配置するだけで Goose が自動検出します。**オフライン監査ソースでもあります**。 ```bash failproofai policies --install --scope project @@ -62,17 +62,17 @@ bun add -g failproofai failproofai policies ``` - すべてのポリシー、その有効/無効の状態、設定済みのパラメーターが一覧表示されます。 + すべてのポリシー、有効かどうか、設定済みのパラメーターが表示されます。 ```bash failproofai ``` - `http://localhost:8020` にローカルダッシュボードが開き、セッションの閲覧、ツール呼び出しの検査、ポリシーの管理ができます。 + `http://localhost:8020` にローカルダッシュボードが開き、セッションの閲覧、ツール呼び出しの確認、ポリシーの管理が行えます。 - 通常通り Claude Code を起動してください。エージェントが危険な操作を試みた場合、failproofai が自動的に介入します。エージェントを無人で動作させたまま、ダッシュボードで後から内容を確認できます。 + Claude Code を通常どおり起動してください。エージェントがリスクのある操作を試みた場合、failproofai が自動的に介入します。放置したまま実行し、あとでダッシュボードで何が起きたかを確認できます。 @@ -88,21 +88,21 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON writes decision to stdout ``` -各ポリシーは次の 3 つのいずれかの判定を返します。 +各ポリシーは次の3つの決定のいずれかを返します。 -- **allow** - エージェントは通常通り処理を続行する -- **deny** - アクションがブロックされ、エージェントに理由が通知される -- **instruct** - エージェントのプロンプトに追加のコンテキストが付加される +- **allow** — エージェントは通常どおり処理を続行する +- **deny** — アクションがブロックされ、エージェントに理由が通知される +- **instruct** — エージェントのプロンプトに追加のコンテキストが付加される -ポリシーはローカルプロセス上で実行されます。リモートサービスへのデータ送信は一切行われません。 +ポリシーはローカルプロセス内で実行されます。リモートサービスへのデータ送信は一切行われません。 --- -## コンベンションベースのポリシーでチームポリシーを設定する +## 規約ベースのポリシーでチームポリシーを設定する -チーム全体で品質基準を確立する最も手軽な方法は、`.failproofai/policies/` コンベンションを使うことです。このディレクトリにポリシーファイルを置くだけで自動的に読み込まれます。フラグや設定変更、インストールコマンドは一切不要です。 +チーム全体に品質標準を素早く展開する最善の方法は、`.failproofai/policies/` の規約です。このディレクトリにポリシーファイルを置くだけで自動的に読み込まれます — フラグも、設定変更も、インストールコマンドも不要です。 @@ -111,13 +111,13 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON ``` - スターターサンプルをコピーするか、独自のポリシーを作成してください。 + サンプルファイルをコピーするか、独自のものを作成してください。 ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - または新しいポリシーを作成します。 + または新しいファイルを作成します。 ```js // .failproofai/policies/team-policies.mjs @@ -142,23 +142,25 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON git commit -m "Add team quality policies" ``` - failproofai をインストール済みのチームメンバー全員が、これらのポリシーを自動的に受け取ります。開発者ごとのセットアップは不要です。 + failproofai をインストールしているすべてのチームメンバーがこれらのポリシーを自動的に取得します。開発者ごとのセットアップは不要です。 -`.failproofai/policies/` をリポジトリにコミットして、チーム全体で同じ基準を共有しましょう。新たな障害モードを発見したらポリシーを追加してプッシュするだけで、全員が次回の `git pull` 時にアップデートを受け取れます。こうしたポリシーは、継続的に改善されていく生きた品質基準となっていきます。 +`.failproofai/policies/` をリポジトリにコミットすることで、チーム全体が同じ標準を共有できます。新たな障害パターンが見つかったらポリシーを追加してプッシュするだけで、全員が次回の `git pull` 時にアップデートを受け取れます。ポリシーは時間とともに成長し続ける品質基準となっていきます。 --- ## データの保存場所 -すべての設定とログはお使いのマシン上に保存されます。 +すべての設定とログはマシン上に保存されます。 -| パス | 保存される内容 | +| パス | 保存内容 | |------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | グローバルポリシー設定 | +| `~/.failproofai/policies-config.json` | グローバルポリシー設定 | +| `~/.failproofai/policies/` | 独自ポリシー — `*-policies.mjs` を置くだけで設定不要 | +| `~/.failproofai/policies/cloud-policies/` | 組織からこのマシンにデプロイされたポリシー | | `~/.failproofai/hook-activity/` | フック実行履歴（ページ付き JSONL） | | `~/.failproofai/logs/` | カスタムフックエラーのデバッグログ | | `.failproofai/policies-config.json` | プロジェクト単位の設定（コミット対象） | @@ -185,15 +187,15 @@ failproofai policies --uninstall - パラメーター付き全 26 ポリシー + パラメーター付き全26ポリシー - JavaScript で独自のポリシーを作成する + JavaScript で独自のポリシーを記述する - セッションの監視とポリシー活動の確認 + セッションの監視とポリシーアクティビティの確認 \ No newline at end of file diff --git a/docs/ja/introduction.mdx b/docs/ja/introduction.mdx index 69e06712..8d2e9129 100644 --- a/docs/ja/introduction.mdx +++ b/docs/ja/introduction.mdx @@ -1,24 +1,24 @@ --- title: "Failproof AI" -description: "FailproofAI は AI エージェントに39個の組み込み障害ポリシーを提供し、ループ、シークレットの漏洩、破壊的なツール呼び出しなどを1回のインストールで検出します。" +description: "FailproofAI は AI エージェントに 39 個の組み込み失敗ポリシーを提供し、ループ・シークレット漏洩・破壊的なツール呼び出しなどを単一のインストールで検出します。" --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -**AI の障害処理**、**エラー回復**、**LLM の信頼性**のためのフックとポリシー。**Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Hermes**、**OpenClaw**、**Factory Droid**、**Devin CLI**、**Antigravity CLI**、および **Agents SDK** で AI エージェントを安定かつ自律的に稼働させ続けます。 +**AI の障害ハンドリング**、**エラーリカバリー**、**LLM の信頼性**のためのフックとポリシー。**Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Hermes**、**OpenClaw**、**Factory Droid**、**Devin CLI**、**Antigravity CLI**、そして **Agents SDK** 上で、AI エージェントを安定した自律動作に保ちます。 -AI エージェントは予測可能な形で失敗します。破壊的なコマンドを実行したり、シークレットを漏洩したり、タスクから逸脱したり、ループにはまったり、main ブランチに直接プッシュしたりします。放置すると、小さな障害が連鎖してサービス停止や認証情報の漏洩、作業の消失につながります。 +AI エージェントは予測可能なパターンで失敗します。破壊的なコマンドを実行したり、シークレットを漏洩したり、タスクから逸脱したり、ループに陥ったり、main ブランチに直接プッシュしたりします。放置すると、小さな障害が連鎖してサービス停止、認証情報の流出、作業の消失につながります。 -FailproofAI はこの問題を**ポリシー**で解決します。これらのルールはエージェントのすべてのツール呼び出しにフックし、**障害を検出**し、**対処**（ブロック、指示、サニタイズ）し、注意が必要な場合に**通知**します。ローカルダッシュボードでは、すべてのツール呼び出し、エージェントの障害、および回復アクションを後から確認できます。 +FailproofAI はこの問題を **ポリシー** で解決します。これらのルールはすべてのエージェントツール呼び出しにフックし、**障害を検出**して**緩和**（ブロック・指示・サニタイズ）し、対応が必要なときに**通知**します。ローカルダッシュボードでは、すべてのツール呼び出し・エージェント障害・リカバリーアクションを事後に確認できます。 -トランスクリプトとポリシーの評価はあなたのマシン上に保存されます。データが送信されるのは、認証済みの監査リマインダーや招待などのオンライン機能を明示的に使用した場合のみです。 +トランスクリプトとポリシー評価はすべてローカルマシン上に留まります。データが送信されるのは、認証済み監査リマインダーや招待など、オンライン機能を明示的に使用した場合のみです。 ## はじめに - - 破壊的なコマンドのブロック、シークレットの漏洩防止、エージェントをプロジェクトの境界内に収める設定など、すべてすぐに使えます。 + + 破壊的なコマンドのブロック、シークレット漏洩の防止、エージェントのプロジェクト境界内への制限など、すべてすぐに使えます。 @@ -26,11 +26,11 @@ FailproofAI はこの問題を**ポリシー**で解決します。これらの - 席を外している間にエージェントが何をしたかを確認できます。セッションの閲覧、ツール呼び出しの検査、ポリシーが発動した箇所のレビューが可能です。 + 離席中にエージェントが何をしていたかを確認できます。セッションの閲覧、ツール呼び出しの検査、ポリシーが発動した箇所のレビューが可能です。 - コードなしで任意のポリシーを調整できます。プロジェクトごと、またはグローバルにホワイトリスト、保護ブランチ、しきい値を設定できます。 + コードなしで任意のポリシーを調整できます。プロジェクト単位またはグローバルに、許可リスト・保護ブランチ・しきい値を設定できます。 @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -詳細な手順については、[はじめ方](/ja/getting-started)ガイドをご覧ください。 \ No newline at end of file +完全なウォークスルーは [Getting started](/ja/getting-started) ガイドをご覧ください。 \ No newline at end of file diff --git a/docs/ja/package-aliases.mdx b/docs/ja/package-aliases.mdx index 9235fb92..88257a05 100644 --- a/docs/ja/package-aliases.mdx +++ b/docs/ja/package-aliases.mdx @@ -1,12 +1,12 @@ --- title: パッケージエイリアス -description: "タイポスクワット防止のために登録されたエイリアスとその仕組み" +description: "登録済みタイポスクワット防止エイリアスとその仕組み" icon: copy --- ## 公式パッケージ -正式な npm パッケージは **`failproofai`** です: +正式な npm パッケージは **`failproofai`** です： ```bash npm install -g failproofai @@ -16,17 +16,17 @@ bun add -g failproofai --- -## エイリアス名を所有する理由 +## エイリアス名を保有する理由 -タイポスクワッティングは、悪意のある攻撃者が人気パッケージ名からキー入力1つ分しか違わない名前を登録するという、よくあるサプライチェーン攻撃です。インストールコマンドを誤って入力した無防備なユーザーは、フルシステムアクセス権限を持つ攻撃者制御のコードを実行することになります。これはまさに Failproof AI が防御するように設計された脅威です。 +タイポスクワッティングは、悪意のある攻撃者が人気パッケージの名前から1キー違いのパッケージ名を登録するという、一般的なサプライチェーン攻撃です。インストールコマンドを誤って入力したユーザーが、フルシステムアクセス権限を持つ攻撃者制御のコードを実行してしまいます。これはまさに Failproof AI が防御するために設計された脅威の一種です。 -この攻撃経路を排除するため、**npm 上の `failproofai` に対するよくあるスペルミスや表記バリアントをすべて先手を打って取得しています**。これらの名前はいずれも第三者に登録されることはありません。それぞれが本物の `failproofai` パッケージをインストールして委譲する薄いプロキシとなっています。 +この攻撃対象を排除するため、**npm 上の `failproofai` に関するよくある誤字・表記バリエーションをすべて先行登録しています**。これらの名前はいかなる第三者も登録できません。それぞれが本物の `failproofai` パッケージにインストールと処理を委譲するシンプルなプロキシです。 --- ## 登録済みエイリアス -**表記バリアント** - "failproof ai" のさまざまな書き方: +**表記バリエーション** - "failproof ai" のさまざまな書き方： | パッケージ | ステータス | |---------|--------| @@ -37,7 +37,7 @@ bun add -g failproofai | `fail_proof_ai` | ⏳ npm サポート対応待ち | | `fail-proofai` | ⏳ npm サポート対応待ち | -**`failprof*` タイポ** - "proof" から `o` が1つ抜けたもの: +**`failprof*` タイポ** - "proof" の `o` が1つ欠けているもの： | パッケージ | ステータス | |---------|--------| @@ -47,7 +47,7 @@ bun add -g failproofai | `fail-prof-ai` | ⏳ npm サポート対応待ち | | `failprof_ai` | ⏳ npm サポート対応待ち | -**`faliproof*` タイポ** - `a` と `i` が入れ替わったもの: +**`faliproof*` タイポ** - `a` と `i` が入れ替わっているもの： | パッケージ | ステータス | |---------|--------| @@ -55,28 +55,28 @@ bun add -g failproofai | `faliproof-ai` | ✅ 公開済み | | `faliproofai` | ⏳ npm サポート対応待ち | -> **対応待ちの理由:** npm のスパム防止ポリシーにより、記号を除去して類似性チェックを行った結果、既存パッケージと同じ文字列に正規化される名前はブロックされます。アンチスクワッティング目的でこれらの名前を予約するよう npm サポートに連絡済みです。承認され次第、有効化される予定です。 +> **対応待ちの理由について** npm のスパム防止ポリシーにより、句読点を除去して類似チェックを実施した際に既存パッケージと同じ文字列に正規化される名前はブロックされます。アンチスクワッティング目的でこれらの名前を予約するよう npm サポートに連絡済みです。承認され次第、順次有効化されます。 -公開済みのエイリアスが私たちのものであることは、以下のコマンドで確認できます: +公開済みエイリアスが当社所有であることは以下のコマンドで確認できます： ```bash npm info failproof -# maintainers フィールドに "ExosphereHost Inc." が含まれているか確認してください +# "ExosphereHost Inc." が maintainers フィールドにあることを確認してください ``` --- ## エイリアスの仕組み -各エイリアスパッケージは: +各エイリアスパッケージは： -1. `failproofai` を依存関係としてリストに含めており、これにより本物のパッケージがインストールされ、バイナリが利用可能になります -2. 自身の名前（例: `failprof-ai`）に対応するバイナリを公開し、すべての引数を `failproofai` バイナリへ転送します +1. `failproofai` を依存関係として定義しているため、本物のパッケージがインストールされ、そのバイナリが利用可能になります +2. 独自の名前（例：`failprof-ai`）に対応するバイナリを公開し、すべての引数を `failproofai` バイナリに委譲します -プロキシは2行の Node スクリプトです。ロジックもなく、ネットワーク呼び出しもなく、`failproofai` 自体が行う以上のデータ収集も一切ありません。 +プロキシは2行の Node スクリプトで構成されており、ロジック・ネットワーク呼び出し・データ収集はいずれも `failproofai` 自体が行う範囲を超えません。 --- ## 見落としている名前を発見した場合 -[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) にイシューを作成してください。登録いたします。 \ No newline at end of file +[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) にイシューを作成してください。登録対応いたします。 \ No newline at end of file diff --git a/docs/ja/testing.mdx b/docs/ja/testing.mdx index c6c79bc3..ed724fa8 100644 --- a/docs/ja/testing.mdx +++ b/docs/ja/testing.mdx @@ -4,7 +4,7 @@ description: "ユニットテスト、E2Eテスト、テストヘルパー" icon: flask-vial --- -failproofai には2つのテストスイートがあります。**ユニットテスト**（高速、モック使用）と**エンドツーエンドテスト**（実際のサブプロセス呼び出し）です。 +failproofai には **ユニットテスト**（高速・モック使用）と**エンドツーエンドテスト**（実際のサブプロセス呼び出し）の2種類のテストスイートがあります。 --- @@ -20,7 +20,7 @@ bun run test # E2Eテストを実行（事前セットアップが必要 - 下記参照） bun run test:e2e -# ビルドせずに型チェックのみ +# ビルドせずに型チェックのみ実行 bunx tsc --noEmit # リント @@ -31,20 +31,20 @@ bun run lint ## ユニットテスト -ユニットテストは `__tests__/` ディレクトリに格納されており、`jsdom` を使用した [Vitest](https://vitest.dev) で実行されます。 +ユニットテストは `__tests__/` ディレクトリに配置され、`jsdom` を使用した [Vitest](https://vitest.dev) で実行されます。 ```text __tests__/ hooks/ - builtin-policies.test.ts # 各ビルトインのポリシーロジック + builtin-policies.test.ts # 各組み込みポリシーのロジック hooks-config.test.ts # 設定の読み込みとスコープのマージ - policy-evaluator.test.ts # パラメータのインジェクションと評価順序 + policy-evaluator.test.ts # パラメータ注入と評価順序 custom-hooks-registry.test.ts # globalThis レジストリの追加/取得/クリア - custom-hooks-loader.test.ts # ESM ローダー、推移的インポート、エラー処理 - manager.test.ts # インストール/削除/一覧操作 + custom-hooks-loader.test.ts # ESM ローダー、推移的インポート、エラーハンドリング + manager.test.ts # インストール/削除/一覧表示の操作 components/ - sessions-list.test.tsx # セッション一覧コンポーネント - project-list.test.tsx # プロジェクト一覧コンポーネント + sessions-list.test.tsx # セッションリストコンポーネント + project-list.test.tsx # プロジェクトリストコンポーネント ... lib/ logger.test.ts @@ -110,48 +110,48 @@ describe("block-sudo", () => { ## エンドツーエンドテスト -E2Eテストは実際の `failproofai` バイナリをサブプロセスとして起動し、JSON ペイロードを stdin にパイプして、stdout の出力と終了コードをアサートします。これにより、Claude Code が使用する完全なインテグレーションパスをテストします。 +E2Eテストは実際の `failproofai` バイナリをサブプロセスとして呼び出し、JSON ペイロードを stdin にパイプして、stdout の出力と終了コードをアサートします。これにより、Claude Code が使用する完全なインテグレーションパスをテストします。 ### セットアップ -E2Eテストはリポジトリのソースから直接バイナリを実行します。初回実行前に、カスタムフックファイルが `'failproofai'` からインポートする際に使用する CJS バンドルをビルドしてください。 +E2Eテストはリポジトリのソースから直接バイナリを実行します。初回実行前に、カスタムフックファイルが `'failproofai'` からインポートする際に使用する CJS バンドルをビルドしてください： ```bash bun build src/index.ts --outdir dist --target node --format cjs ``` -その後、テストを実行します。 +その後、テストを実行します： ```bash bun run test:e2e ``` -公開フック API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts`、または `src/hooks/policy-types.ts`）を変更した場合は、`dist/` を再ビルドしてください。 +パブリックフック API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts`、または `src/hooks/policy-types.ts`）を変更した際は、都度 `dist/` を再ビルドしてください。 ### E2Eテストの構成 ```text __tests__/e2e/ helpers/ - hook-runner.ts # バイナリを起動し、ペイロード JSON をパイプして、終了コード・stdout・stderr をキャプチャ + hook-runner.ts # バイナリを起動し、ペイロード JSON をパイプして終了コード・stdout・stderr をキャプチャ fixture-env.ts # テストごとに分離された一時ディレクトリと設定ファイル payloads.ts # 各イベントタイプに対応した Claude 準拠のペイロードファクトリ hooks/ - builtin-policies.e2e.test.ts # 実際のサブプロセスを使った各ビルトインポリシー + builtin-policies.e2e.test.ts # 実際のサブプロセスで各組み込みポリシーをテスト custom-hooks.e2e.test.ts # カスタムフックの読み込みと評価 - config-scopes.e2e.test.ts # プロジェクト/ローカル/グローバルをまたいだ設定のマージ - policy-params.e2e.test.ts # パラメータ化された各ポリシーへのパラメータインジェクション + config-scopes.e2e.test.ts # プロジェクト/ローカル/グローバルをまたいだ設定マージ + policy-params.e2e.test.ts # パラメータ化された各ポリシーへのパラメータ注入 ``` ### E2Eヘルパーの使い方 -**`FixtureEnv`** - テストごとに分離された環境: +**`FixtureEnv`** - テストごとに分離された環境： ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - 一時ディレクトリ。payload.cwd として渡すと .failproofai/policies-config.json を読み込む +// env.cwd - 一時ディレクトリ。payload.cwd に渡すと .failproofai/policies-config.json を読み込む // env.home - 分離されたホームディレクトリ。実際の ~/.failproofai が混入しない env.writeConfig({ @@ -164,7 +164,7 @@ env.writeConfig({ `createFixtureEnv()` は `afterEach` クリーンアップを自動的に登録します。 -**`runHook`** - バイナリを呼び出す: +**`runHook`** - バイナリを呼び出す： ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - 使いやすいペイロードファクトリ: +**`Payloads`** - 用途別のペイロードファクトリ： ```typescript Payloads.preToolUse.bash(command, cwd) @@ -226,7 +226,7 @@ describe("block-rm-rf (E2E)", () => { ); expect(result.exitCode).toBe(0); - expect(result.stdout).toBe(""); // allow → 空の stdout + expect(result.stdout).toBe(""); // allow → stdout は空 }); }); ``` @@ -238,23 +238,23 @@ describe("block-rm-rf (E2E)", () => { | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct（Stop 以外） | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | stdout は空。理由は stderr に出力 | +| Stop instruct | `2` | stdout は空；理由は stderr に出力 | | Allow | `0` | 空文字列 | ### Vitest の設定 -E2Eテストは `vitest.config.e2e.mts` を使用し、以下の設定が含まれます。 +E2Eテストは `vitest.config.e2e.mts` を使用し、以下の設定が適用されます： - `environment: "node"` - ブラウザのグローバル変数は不要 - `pool: "forks"` - 真のプロセス分離（テストがサブプロセスを起動する） -- `testTimeout: 20_000` - テストごとに 20 秒（バイナリの起動 + フック評価） +- `testTimeout: 20_000` - テストごとに20秒（バイナリ起動 + フック評価） -`forks` プールは重要です。スレッドベースのワーカーは `globalThis` を共有するため、サブプロセスを起動するテストに干渉する可能性があります。プロセスベースのフォークはこの問題を回避します。 +`forks` プールが重要なのは、スレッドベースのワーカーは `globalThis` を共有するため、サブプロセスを起動するテストに干渉する可能性があるためです。プロセスベースのフォークはこの問題を回避します。 --- ## CI -マージ前に、フルの CI 実行（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）がパスする必要があります。E2Eスイートは別の CI ジョブとして並行して実行されます。 +マージ前には、完全な CI 実行（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）が通過している必要があります。E2Eスイートは並列の独立した CI ジョブとして実行されます。 -完全なマージ前チェックリストについては、[コントリビューティングガイド](../CONTRIBUTING.md)を参照してください。 \ No newline at end of file +マージ前の完全なチェックリストについては [Contributing](../CONTRIBUTING.md) を参照してください。 \ No newline at end of file diff --git a/docs/ko/agenteye/alerts.mdx b/docs/ko/agenteye/alerts.mdx index fcf7f613..c4314b78 100644 --- a/docs/ko/agenteye/alerts.mdx +++ b/docs/ko/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "알림" -description: "고객으로부터 먼저 듣는 대신, 팀이 이미 사용하는 채널에서 문제가 발생하는 즉시 알림을 받으세요." +description: "고객에게 먼저 듣기 전에, 팀이 이미 사용하는 채널에서 문제가 발생하는 즉시 알아채세요." --- -고객으로부터 먼저 듣는 대신, 팀이 이미 사용하는 채널에서 문제가 발생하는 즉시 알림을 받으세요. 규칙을 한 번 설정하면 Failproof AI Observability가 일정에 따라 확인하고, 이메일, Slack, 웹훅, 또는 대시보드에서 직접 알림을 보내드립니다. +고객에게 먼저 듣기 전에, 팀이 이미 사용하는 채널에서 문제가 발생하는 즉시 알아채세요. 규칙을 한 번 설정하면 Failproof AI Observability가 주기적으로 확인한 뒤, 이메일, Slack, 웹훅, 또는 대시보드를 통해 알림을 전송합니다. -![알림 페이지: 각 트리거, 평가 기간, 채널, 정보·경고·심각 심각도 배지를 보여주는 알림 규칙 카드 그리드](/agenteye/images/alerts.png) -*모든 알림 규칙을 한눈에: 무엇을 감시하는지, 얼마나 자주, 어디로 알리는지, 얼마나 긴급한지.* +![알림 페이지: 각 알림 규칙 카드가 트리거, 평가 윈도우, 채널, 그리고 정보/경고/심각 심각도 배지를 표시하는 그리드 레이아웃](/agenteye/images/alerts.png) +*모든 알림 규칙을 한눈에: 무엇을 모니터링하는지, 얼마나 자주, 어디로 전송하는지, 그리고 얼마나 긴급한지.* ## 사용자보다 먼저 문제를 파악하세요 -회귀를 발견하기 위해 대시보드를 새로고침하며 기다리지 마세요. 아무도 보고 있지 않을 때도 알아야 할 신호가 있다면 알림을 설정하고, 이미 사용하는 곳에서 바로 받으세요: +대시보드를 새로고침하며 회귀를 발견하길 기대하는 일은 이제 그만하세요. 아무도 보고 있지 않을 때도 알고 싶은 신호가 있다면 알림을 설정하고, 이미 사용 중인 곳에서 받아보세요: -- **이메일**: 알아야 할 담당자에게 전송. -- **Slack**: 인시던트로 바로 이동하는 버튼이 포함된 풍부한 메시지. -- **웹훅**: PagerDuty, Opsgenie 또는 자체 엔드포인트로 전달되는 JSON POST. 수신자가 신뢰할 수 있도록 선택적 서명 지원. -- **대시보드 내**: 규칙을 조정 중이고 아직 아무에게도 알리고 싶지 않을 때를 위한 조용한 옵션. +- **이메일**, 알아야 할 사람 누구에게나. +- **Slack**, 인시던트로 바로 이동하는 버튼이 포함된 풍부한 메시지. +- **웹훅**, PagerDuty, Opsgenie, 또는 자체 엔드포인트를 위한 JSON POST로, 수신자가 신뢰할 수 있도록 선택적 서명 포함. +- **대시보드 내**, 규칙을 튜닝 중이고 아직 아무에게도 알리고 싶지 않을 때를 위해, 의도적으로 조용하게. -단일 규칙에 원하는 조합을 자유롭게 연결하세요. 심각도(정보, 경고, 심각)도 함께 전달되어 긴급한 알림은 긴급하게 보입니다. +단일 규칙에 원하는 조합을 연결하고, 심각도(정보, 경고, 심각)도 함께 전달되어 긴급한 것은 긴급하게 보입니다. -## JSON이 아닌 폼으로 규칙 작성 +## JSON이 아닌 폼으로 규칙 만들기 -무엇이 "고장"인지 폼으로 설명하면 Failproof AI Observability가 내부 규칙을 대신 작성해 줍니다. JSON 사양은 그 폼이 내부적으로 생성하는 결과물이므로, 규칙을 이해하기 위해 읽을 수는 있지만 직접 타이핑할 일은 거의 없습니다. +"고장 났다"는 것이 무엇을 의미하는지 폼으로 설명하면, Failproof AI Observability가 기반 규칙을 작성합니다. JSON 사양은 폼이 내부적으로 생성하는 결과물이므로, 규칙을 이해하기 위해 읽을 수는 있지만 직접 입력할 일은 거의 없습니다. -![새 알림 폼: 이름과 설명, 활성화 토글, 메트릭 임계값·커스텀 SQL·평가 점수·복합 평가·이벤트별 조건을 제공하는 트리거 선택기](/agenteye/images/alert-new.png) -*트리거를 선택하면 폼에 해당 필드가 표시됩니다. 저장을 누르면 규칙이 작성됩니다.* +![새 알림 폼: 이름과 설명, 활성화 토글, 그리고 메트릭 임계값, 커스텀 SQL, 평가 점수, 복합 평가, 이벤트별 조건을 제공하는 트리거 선택기](/agenteye/images/alert-new.png) +*트리거를 선택하면 폼이 적절한 필드로 바뀝니다. 저장하면 규칙이 작성됩니다.* -기본 흐름은 빠릅니다: 이름을 입력하고, **트리거**(무엇을 감시할지)를 선택하고, **임계값과 기간**(얼마나 나쁜지, 얼마나 오래)을 설정하고, **채널**을 하나 이상 연결한 다음 **저장**하고 **테스트**를 눌러 가상 알림을 발송해 모든 수신처가 올바르게 연결되었는지 확인하세요. 내부적으로는 다음과 같은 작은 사양이 생성됩니다: +기본 흐름은 빠릅니다: 이름을 지정하고, **트리거**(무엇을 모니터링할지)를 선택하고, **임계값과 윈도우**(얼마나 심각한지, 얼마나 오랫동안)를 설정하고, 최소 하나의 **채널**을 연결한 다음, **저장**하고 **테스트**를 눌러 가상 알림을 발송해 모든 목적지가 올바르게 연결됐는지 확인하세요. 내부적으로는 다음과 같은 소규모 사양이 생성됩니다: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -하나의 신호 유형에만 국한되지 않습니다. 장애를 어떻게 인식하느냐에 맞는 트리거를 선택하세요: +한 가지 종류의 신호에만 국한되지 않습니다. 장애를 어떻게 생각하는지에 맞는 트리거를 선택하세요: | 트리거 | 발동 조건 | |---|---| -| **메트릭 임계값** | 미리 설정된 메트릭(오류율, p95 또는 p99 지연시간, 이벤트 또는 오류 수, 토큰 사용량)이 특정 기간 동안 설정 기준을 초과할 때 | -| **커스텀 SQL** | 사용자 정의 읽기 전용 쿼리가 행을 반환하거나, 쿼리로 계산된 값이 임계값을 초과할 때 | +| **메트릭 임계값** | 사전 설정된 메트릭(에러율, p95 또는 p99 지연 시간, 이벤트 또는 에러 횟수, 토큰 소비량)이 윈도우 동안 기준을 초과할 때 | +| **커스텀 SQL** | 직접 작성한 읽기 전용 쿼리가 행을 반환하거나, 계산된 값이 임계값을 초과할 때 | | **평가 점수** | 평가자 점수의 평균(예: 환각)이 임계값을 초과할 때 | -| **복합 평가** | 여러 점수 조건을 any, all, 또는 최소 N개 논리로 결합하여 여러 점수에 걸쳐 나타나는 회귀를 감지할 때 | -| **이벤트별** | 특정 에이전트, 특정 오류 유형, 또는 메시지 하위 문자열과 일치하는 단일 이벤트가 발생할 때 | +| **복합 평가** | 여러 점수 검사를 any, all, 또는 최소 N개 논리로 결합하여, 점수 전반에 걸쳐서만 나타나는 회귀를 포착할 때 | +| **이벤트별** | 단일 매칭 이벤트가 발생할 때: 특정 에이전트, 특정 에러 유형, 또는 메시지 부분 문자열 | -[오류 페이지](/ko/agenteye/error-tracking)에서 이미 장애를 보고 계신가요? 각 행에는 **+ alert** 버튼이 있어 동일한 폼이 해당 장애를 다시 감지하도록 미리 채워진 상태로 열립니다. 방금 분류한 인시던트가 다음번에 알림을 보내는 항목이 됩니다. +이미 [에러 페이지](/ko/agenteye/error-tracking)에서 장애를 보고 있나요? 각 행에는 **+ alert** 버튼이 있어 해당 장애를 정확히 포착하도록 미리 채워진 동일한 폼을 엽니다. 방금 분류한 인시던트가 다음에 알림을 보내는 주체가 됩니다. -**위치:** 알림은 `//alerts`에 있습니다. 규칙 생성, 편집, 삭제, 테스트에는 **`alerts:write`** 권한이 필요하며, 조회는 `alerts:read`로 충분합니다. 수신자 선택기에는 조직 구성원이 이름으로 표시되므로, 폼을 벗어나지 않고도 특정 사람에게 알림을 보낼 수 있습니다. +**찾는 방법:** 알림은 `//alerts`에 있습니다. 규칙 생성, 편집, 삭제, 테스트에는 **`alerts:write`**가 필요하며, 조회만 할 때는 `alerts:read`로 충분합니다. 수신자 선택기는 조직 구성원을 이름으로 나열하므로, 폼을 벗어나지 않고 특정 사람에게 알림을 보낼 수 있습니다. ## 실제 문제일 때만 알림 받기 -잘못된 측정 하나에 잠에서 깨어나서는 안 됩니다. **M of N** 노이즈 필터는 알림이 실제로 발동되기 전에 최근 몇 번의 확인 중 몇 번이 실패해야 하는지를 제어합니다. **3 of 5**로 설정하면 최근 다섯 번의 확인 중 세 번이 기준을 초과한 경우에만 규칙이 발동되어, 불안정한 신호가 헛된 경보를 울리지 않습니다. 첫 번째 위반 시 즉시 발동하려면 기본값 **1 of 1**로 유지하세요. 규칙 실행 빈도도 선택할 수 있으며, 신호가 실제로 변화하는 속도에 맞춰 1m, 5m, 15m, 1h 중에서 선택하세요. +잘못된 측정값 하나가 당신을 깨워선 안 됩니다. **M of N** 노이즈 필터는 알림이 실제로 전송되기 전에 최근 몇 번의 검사 중 몇 번이 실패해야 하는지 제어합니다. **3 of 5**로 설정하면 최근 다섯 번의 검사 중 세 번을 초과했을 때만 규칙이 발동되어, 불안정한 신호가 계속 거짓 경보를 내지 않게 됩니다. 첫 번째 위반 즉시 발동하려면 기본값 **1 of 1**로 유지하세요. 또한 규칙이 얼마나 자주 실행될지 선택할 수 있으며, 1분, 5분, 15분, 1시간의 사전 설정 중 신호가 실제로 변화하는 속도에 맞게 선택하세요. ## 알림이 발동되면 어떻게 되나요 -기준 위반이 발생하면 **인시던트**가 생성되고 채널에 한 번 알림이 전송됩니다. 이후 팀이 인지하고, 담당자를 지정하고, 논의하고, 해결하는 과정이 깔끔하고 명확한 기록으로 남습니다. 해당 분류 워크플로우는 별도의 페이지에 있습니다: [인시던트](/ko/agenteye/incidents)를 참조하세요. +위반이 발생하면 **인시던트**가 열리고 채널에 한 번 알림이 전송됩니다. 이후 팀이 확인하고, 담당자를 지정하고, 논의하고, 해결합니다. 모든 과정이 명확하고 귀속이 분명한 기록으로 남습니다. 해당 분류 워크플로에는 별도의 페이지가 있습니다: [인시던트](/ko/agenteye/incidents)를 참조하세요. ## 관련 항목 -- [인시던트](/ko/agenteye/incidents): 발동된 알림을 열림에서 인지됨, 해결됨까지 추적합니다. -- [오류 추적](/ko/agenteye/error-tracking): 에이전트 장애를 그룹화하고 클릭 한 번으로 알림으로 승격합니다. -- [대시보드](/ko/agenteye/dashboards): 알림 임계값의 기반이 되는 공유 보드를 확인합니다. -- [CLI 및 에이전트](/ko/agenteye/cli-and-agents): 터미널에서 알림을 생성하고 인시던트를 확인하거나, CI에 스크립트로 통합합니다. \ No newline at end of file +- [인시던트](/ko/agenteye/incidents): 발동된 알림을 열림에서 확인됨, 해결됨까지 추적합니다. +- [에러 추적](/ko/agenteye/error-tracking): 에이전트 실패를 그룹화하고 클릭 한 번으로 알림으로 승격합니다. +- [대시보드](/ko/agenteye/dashboards): 알림 임계값의 기준이 되는 공유 보드를 모니터링합니다. +- [CLI와 에이전트](/ko/agenteye/cli-and-agents): 터미널에서 알림을 생성하고 인시던트를 확인하거나, CI에 스크립트로 통합합니다. \ No newline at end of file diff --git a/docs/ko/agenteye/api-keys.mdx b/docs/ko/agenteye/api-keys.mdx index 8fe04b6a..7d70b3fc 100644 --- a/docs/ko/agenteye/api-keys.mdx +++ b/docs/ko/agenteye/api-keys.mdx @@ -1,173 +1,173 @@ --- title: "API Keys" -description: "API keys는 Failproof AI Observability 서버에 접근할 수 있는 대상을 제어하므로, 컬렉터는 읽기 또는 관리자 권한 없이도 이벤트를 전송할 수 있습니다." +description: "API 키는 Failproof AI Observability 서버에 접근할 수 있는 주체와 방식을 제어하므로, 수집기는 읽기 권한이나 관리자 권한 없이 이벤트를 전송할 수 있습니다." --- -API keys는 Failproof AI Observability 서버에 접근할 수 있는 대상을 제어하므로, 컬렉터는 읽기 또는 관리자 권한 없이도 이벤트를 전송할 수 있습니다. 각 키는 하나 이상의 권한을 가지며, 각 권한은 특정 서버 라우트를 제어합니다. 작업에 필요한 최소한의 권한만 부여하세요. 대부분의 배포 환경에서는 세 가지 종류의 키만 생성합니다. +API 키는 Failproof AI Observability 서버에 접근할 수 있는 주체와 방식을 제어하므로, 수집기는 읽기 권한이나 관리자 권한 없이 이벤트를 전송할 수 있습니다. 각 키는 하나 이상의 권한을 가지며, 각 권한은 특정 서버 라우트를 제한합니다. 필요한 최소한의 권한만 부여하세요. 대부분의 배포 환경에서는 세 가지 종류의 키만 생성합니다. ## 대부분의 배포 환경에서 필요한 3가지 키 -| 키 | 권한 | 사용자 | +| 키 | 권한 | 사용 주체 | |---|---|---| -| 컬렉터 키 | `events:add` | 각 에이전트 머신의 `agenteye-collector`로, 이벤트를 전송하는 데 사용합니다. | -| 대시보드 읽기 키 | `events:read`, `keys:read` | 데이터를 변경하지 않고 조회만 하는 읽기 전용 운영자 또는 통합 시스템. | -| 부트스트랩 관리자 키 | 모든 권한 | 인스턴스와 대시보드를 처음 구동하는 운영자. `ADMIN_KEY` 환경 변수로 시드됩니다. [부트스트랩 관리자 키](#bootstrap-admin-key)를 참조하세요. | +| 수집기 키 | `events:add` | 각 에이전트 머신의 `agenteye-collector`가 이벤트를 전송할 때 사용합니다. | +| 대시보드 읽기 키 | `events:read`, `keys:read` | 데이터를 변경하지 않고 쿼리만 하는 읽기 전용 운영자 또는 통합 서비스가 사용합니다. | +| 부트스트랩 관리자 키 | 모든 권한 | 인스턴스(및 대시보드)를 처음 시작하는 운영자가 사용합니다. `ADMIN_KEY` 환경 변수에서 초기화됩니다. [부트스트랩 관리자 키](#bootstrap-admin-key)를 참조하세요. | -여기서 시작하세요. 더 세분화된 커스텀 스코프 키가 필요한 경우에만 아래의 전체 권한 목록을 참조하세요. [권장 키 구성](#recommended-key-layout) 및 [키 생성](#creating-keys)도 참조하세요. +여기서 시작하세요. 더 세밀하게 범위를 지정한 커스텀 키가 필요할 때만 아래의 전체 권한 목록을 참조하세요. [권장 키 구성](#recommended-key-layout) 및 [키 생성](#creating-keys)도 참조하세요. --- ## 권한 -서버는 고정된 권한 목록을 적용하며, 각 권한은 특정 HTTP 라우트를 제어합니다. **관리자 키**는 모든 권한을 보유하며, 스코프 키는 생성 시 부여한 권한의 하위 집합을 보유합니다. 알 수 없는 권한 문자열은 키 생성 시 거부됩니다. +서버는 고정된 권한 목록을 적용하며, 각 권한은 특정 HTTP 라우트를 제한합니다. **관리자 키**는 모든 권한을 보유하고, 범위가 지정된 키는 생성 시 부여한 권한의 부분 집합을 보유합니다. 알 수 없는 권한 문자열은 키 생성 시 거부됩니다. -> **참고:** 사람/대시보드 전용으로 유효하여 API key에는 부여할 수 없는 권한이 두 가지 있습니다: `orgs:admin`(인스턴스 관리, 운영자 전용)과 `keys:update`. 이 두 권한 중 하나를 부여하려는 `POST /keys` 또는 `PATCH /keys/:id` 요청은 HTTP 422로 거부됩니다. bearer 키가 키를 생성할 수 있지만 편집은 불가능한 이유에 대해서는 아래 `keys:update` 항목을 참조하세요. +> **참고:** 두 가지 유효한 권한은 사람/대시보드 전용으로, API 키에 부여할 수 없습니다: `orgs:admin`(운영자 전용 인스턴스 관리)과 `keys:update`. 이 두 권한을 부여하려는 `POST /keys` 또는 `PATCH /keys/:id` 요청은 HTTP 422로 거부됩니다. 베어러 키가 키를 생성할 수 있지만 수정할 수 없는 이유는 아래 `keys:update` 항목을 참조하세요. -### 이벤트 수집 및 조회 +### 이벤트 수집 및 쿼리 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `events:add` | `POST /events` | 컬렉터로부터 이벤트 배치를 수집합니다. 컬렉터에 필요한 유일한 권한입니다. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | 이벤트 조회, 알려진 환경 목록 조회, 데이터에서 확인된 모델 식별자 목록 조회(Models 뷰 및 모델 필터에 사용), 히트맵/백분위 밴드를 지원하는 지연 시간 집계 계산, 세션을 JSONL로 내보내기. 공유 필터바 패싯 엔드포인트인 `GET /events/environments`와 `GET /events/agent_ids`는 `events:read` **또는** `evaluations:read` 중 하나로 접근 가능하므로, `evaluations:read`로 게이팅된 세션 페이지에서도 동일한 per-org 패싯을 재사용합니다. `GET /events/models`는 해당하지 않으며 `events:read`가 필요합니다. `evaluations:read`만 보유한 주체는 403을 받습니다. | +| `events:add` | `POST /events` | 수집기로부터 이벤트 배치를 수집합니다. 수집기에 필요한 유일한 권한입니다. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | 이벤트 쿼리, 알려진 환경 목록 조회, 데이터에서 확인된 모델 식별자 목록 조회(Models 뷰 및 모델 필터에 사용), 히트맵/백분위 밴드를 구동하는 레이턴시 집계 계산, 세션을 JSONL로 내보내기를 허용합니다. 공유 필터바 패싯 엔드포인트인 `GET /events/environments`와 `GET /events/agent_ids`는 `events:read` **또는** `evaluations:read` 중 하나만 있어도 접근할 수 있으므로, 세션 페이지(`evaluations:read` 필요)가 동일한 조직별 패싯을 재사용합니다. `GET /events/models`는 이에 해당하지 않으며, `events:read`가 필요하므로 `evaluations:read`만 보유한 주체는 403을 받습니다. | ### 세션 및 평가 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | 세션 목록 조회, 평가 결과 읽기, 대시보드에 사용되는 집계된 평가 상태, 평가 작업 워커 큐 상태. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | 세션 목록 조회, 평가 결과 읽기, 대시보드에 사용되는 집계된 평가 상태, 평가 작업 워커 큐 상태를 허용합니다. | | `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | 완료된 세션에 대해 재평가를 수동으로 큐에 추가합니다. | ### 대시보드 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | 대시보드 목록 조회, 개별 로드, 타일 읽기. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | 대시보드 생성 및 편집, 타일 추가/편집/삭제, 타일 그리드 순서 변경. | -| `dashboards:delete` | `DELETE /dashboards/:id` | 전체 대시보드 삭제(타일 수준 삭제는 `dashboards:write` 아래에 있음). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | 대시보드 목록 조회, 단일 대시보드 로드, 타일 읽기를 허용합니다. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | 대시보드 생성 및 편집, 타일 추가/편집/삭제, 타일 그리드 순서 변경을 허용합니다. | +| `dashboards:delete` | `DELETE /dashboards/:id` | 전체 대시보드를 삭제합니다(타일 수준 삭제는 `dashboards:write`에 속합니다). | -### 저장된 쿼리 (SQL 컴포저) +### 저장된 쿼리 (SQL 작성기) -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | 저장된 쿼리 목록 조회, 개별 로드, 컴포저가 대상으로 하는 읽기 전용 스키마 검사. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | 저장된 쿼리 생성 및 편집. SQL은 여전히 `queries:run` 호출과 동일한 읽기 전용 역할 및 보호된 SQL 검사를 통해 라우팅됩니다. | -| `queries:delete` | `DELETE /queries/:id` | 저장된 쿼리 삭제. | -| `queries:run` | `POST /queries/run` | 컴포저에서 사용하는 읽기 전용 역할에 대해 저장된 또는 임시 SQL을 실행합니다. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | 저장된 쿼리 목록 조회, 단일 쿼리 로드, 작성기가 대상으로 하는 읽기 전용 스키마 검사를 허용합니다. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | 저장된 쿼리를 생성하고 편집합니다. SQL은 `queries:run` 호출과 동일한 읽기 전용 역할 및 보호된 SQL 검사를 통해 라우팅됩니다. | +| `queries:delete` | `DELETE /queries/:id` | 저장된 쿼리를 삭제합니다. | +| `queries:run` | `POST /queries/run` | 작성기에서 사용하는 읽기 전용 역할에 대해 저장된 또는 임시 SQL을 실행합니다. | ### AI 어시스턴트 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | AI 어시스턴트와 대화하고 자신의 (비공개) 대화를 관리합니다. 어시스턴트 독을 보려면 **사용자**에게 필요합니다. 어시스턴트 자체 키는 `dashboard-assistant`이며 별도로 시드됩니다(아래 참조). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | AI 어시스턴트와 대화하고 자신의 (비공개) 대화를 관리합니다. 어시스턴트 독을 보려면 **사용자**에게 필요합니다. 어시스턴트 자체 키는 `dashboard-assistant`이며 별도로 초기화됩니다(아래 참조). | -### API Keys +### API 키 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `keys:create` | `POST /keys` | 새로운 스코프 API key를 생성합니다. 기존 키의 권한 편집은 허용하지 **않습니다**(그것은 `keys:update`). | -| `keys:read` | `GET /keys` | 기존 키 목록을 조회합니다. 시크릿은 이 엔드포인트에서 반환되지 않습니다. | -| `keys:update` | `PATCH /keys/:id` | 기존 키의 권한을 편집합니다. **사람/대시보드 전용** 권한으로 API key에 할당할 수 없습니다(bearer 키는 키를 생성할 수 있지만 편집은 불가능). | -| `keys:disable` | `POST /keys/:id/disable` | 키를 취소합니다. 보호된 키(`admin`, `dashboard-assistant`)는 비활성화할 수 없으며, 환경 변수 변경 후 재시작으로 교체하세요. | +| `keys:create` | `POST /keys` | 새 범위 지정 API 키를 생성합니다. 기존 키의 권한 편집은 **허용하지 않습니다**(그것은 `keys:update`입니다). | +| `keys:read` | `GET /keys` | 기존 키 목록을 조회합니다. 이 엔드포인트는 시크릿을 반환하지 않습니다. | +| `keys:update` | `PATCH /keys/:id` | 기존 키의 권한을 편집합니다. **사람/대시보드 전용** 권한으로 API 키에 할당할 수 없습니다(베어러 키는 키를 생성할 수 있지만 편집은 불가합니다). | +| `keys:disable` | `POST /keys/:id/disable` | 키를 폐기합니다. 보호된 키(`admin`, `dashboard-assistant`)는 비활성화할 수 없으며, 환경 변수 변경 + 재시작을 통해 교체하세요. | | `keys:regenerate` | `POST /keys/:id/regenerate` | 키의 시크릿을 교체합니다. 보호된 키는 이 라우트를 통해 재생성할 수 없습니다. | ### 대시보드 사용자 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | 새 대시보드 사용자를 초대하고(이메일 + 일회용 패스코드(OTP) 로그인 발급), 초대 양식 시드에 사용되는 대시보드 구성 기본 권한 집합을 읽습니다. | -| `users:read` | `GET /users`, `GET /users/:id` | 사용자 목록 조회 및 단일 사용자 레코드 로드. | -| `users:update` | `PUT /users/:id` | 사용자의 권한을 편집합니다. 업데이트 시 영향받는 사용자에게 권한 변경 이메일이 발송되며, 다음 요청부터 적용됩니다. 재로그인은 불필요합니다. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | 사용자를 비활성화(세션 즉시 취소)하거나 이전에 비활성화된 사용자를 재활성화합니다. | +| `users:create` | `POST /users`, `GET /users/defaults` | 새 대시보드 사용자를 초대하고(이메일 + 일회용 패스코드(OTP) 로그인 발송), 초대 양식 초기화에 사용되는 대시보드 설정 기본 권한 집합을 읽습니다. | +| `users:read` | `GET /users`, `GET /users/:id` | 사용자 목록을 조회하고 단일 사용자 레코드를 로드합니다. | +| `users:update` | `PUT /users/:id` | 사용자의 권한을 편집합니다. 업데이트 시 영향받는 사용자에게 권한 변경 이메일이 발송되며, 다음 요청 시 즉시 적용됩니다. 재로그인은 필요하지 않습니다. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | 사용자를 비활성화하고(세션 즉시 폐기), 이전에 비활성화된 사용자를 다시 활성화합니다. | -이 권한들은 대시보드의 **Users** 페이지를 지원하며, 각 멤버의 부여된 스코프가 칩으로 표시됩니다: +이 권한들은 각 멤버에게 부여된 범위가 칩으로 표시되는 대시보드의 **사용자** 페이지를 지원합니다: -![Users 페이지: 각 대시보드 사용자의 이메일, 부여된 권한, 편집/비활성화 컨트롤이 포함된 카드](/agenteye/images/users.png) +![사용자 페이지: 이메일, 부여된 권한, 편집/비활성화 컨트롤이 있는 대시보드 사용자별 카드](/agenteye/images/users.png) ### 운영 설정 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | 대시보드 관리 운영 설정 및 메타데이터 보기, per-model 컨텍스트 윈도우 오버라이드 목록 조회, 모델의 유효 윈도우 확인. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | 운영 설정 편집 및 per-model 컨텍스트 윈도우 오버라이드 추가, 변경, 삭제. 변경사항은 서버 재시작 없이 새 이벤트에 적용됩니다. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | 대시보드 관리 운영 설정과 메타데이터를 확인하고, 모델별 컨텍스트 윈도우 재정의 목록을 조회하며, 모델의 유효 윈도우를 확인합니다. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | 운영 설정을 편집하고 모델별 컨텍스트 윈도우 재정의를 추가, 변경, 삭제합니다. 변경 사항은 서버 재시작 없이 새 이벤트에 즉시 반영됩니다. | -![Settings 페이지: 허용 로그인 방법, 세션/OTP 유효기간 등 대시보드 관리 운영 설정을 재시작 없이 편집 가능](/agenteye/images/settings.png) +![설정 페이지: 허용된 로그인 방식, 세션/OTP 유효 기간 등 재시작 없이 편집 가능한 대시보드 관리 운영 설정](/agenteye/images/settings.png) ### 알림 및 인시던트 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | 구성된 알림 정의 보기. | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | 알림 정의 생성, 편집, 삭제, 테스트 발송. | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | 인시던트 및 트리아지 기록 보기. | -| `incidents:write` | `POST /alerts/:id/incidents` | 기존 알림에 대해 수동으로 인시던트를 개시합니다. | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | 인시던트 확인, 담당자 지정, 해결, 댓글 작성. | +| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | 설정된 알림 정의를 확인합니다. | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | 알림 정의를 생성, 편집, 삭제, 테스트 발송합니다. | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | 인시던트와 트리아지 기록을 확인합니다. | +| `incidents:write` | `POST /alerts/:id/incidents` | 기존 알림에 대해 수동으로 인시던트를 생성합니다. | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | 인시던트를 확인, 할당, 해결, 댓글 작성합니다. | ### 감사 -| 권한 | HTTP 라우트 | 허용 범위 | +| 권한 | HTTP 라우트 | 허용 내용 | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | 감사 정의, 실행 기록, 결과 보기. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | 감사 생성, 편집, 삭제, 실행, 결과 트리아지(확인/음소거/해제/해결/재개/담당자 지정). | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | 감사 정의, 실행 이력, 발견 항목을 확인합니다. | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | 감사를 생성, 편집, 삭제, 실행하고, 발견 항목을 트리아지합니다(확인/무시/기각/해결/재오픈/할당). | -> **참고:** 키에 감사 기능을 부여하려면 `audits:*`를 명시적으로 부여하세요. Audits 출시 시 기존 권한 보유자가 어떻게 마이그레이션되었는지는 [업그레이드 및 하위 호환성 참고사항](#upgrade-and-backward-compatibility-notes)을 참조하세요. +> **참고:** 키에 감사 기능을 부여하려면 `audits:*`를 명시적으로 부여하세요. 감사 기능이 출시되었을 때 기존 부여 대상이 어떻게 마이그레이션되었는지는 [업그레이드 및 하위 호환성 참고 사항](#upgrade-and-backward-compatibility-notes)을 참조하세요. -> 수신자 선택기 엔드포인트 `GET /alerts/recipients`(알림 편집자가 알림을 보낼 수 있는 멤버 이메일 목록)는 `alerts:read` **또는** `alerts:write` 중 하나를 보유한 사용자가 접근 가능하므로, 알림 편집자는 `users:read` 없이도 선택기를 사용할 수 있습니다. +> 수신자 선택 엔드포인트 `GET /alerts/recipients`(알림 편집자가 알림을 보낼 수 있는 멤버 이메일 목록)는 `alerts:read` **또는** `alerts:write` 중 하나만 보유해도 접근할 수 있으므로, 알림 편집자는 `users:read` 권한 없이도 선택기를 채울 수 있습니다. -> 대시보드 뷰어는 `dashboards:read`(저장된 뷰 로드)와 `evaluations:read`(상태 메트릭이 평가 데이터에서 계산됨) **둘 다** 필요합니다. 사용자가 대시보드를 생성하거나 편집하려면 `dashboards:write`를, 삭제하려면 `dashboards:delete`를 부여하세요. +> 대시보드 뷰어는 **`dashboards:read`**(저장된 뷰 로드)와 **`evaluations:read`**(평가 데이터로 계산되는 상태 지표) 두 가지 모두 필요합니다. 사용자가 대시보드를 생성하거나 편집하려면 `dashboards:write`를, 삭제하려면 `dashboards:delete`를 부여하세요. -> `/health`와 `/auth/*`(OTP 요청, OTP 검증, 세션 확인, 로그아웃)는 설계상 인증이 필요 없으며, 로그인 흐름 및 생존 확인용입니다. `GET /access-granters`는 유효한 키가 필요하지만 특정 권한은 불필요하므로, 로그인한 모든 사용자가 액세스 변경에 대해 문의할 관리자를 확인할 수 있습니다. +> `/health`와 `/auth/*`(OTP 요청, OTP 검증, 세션 확인, 로그아웃)는 의도적으로 인증이 필요 없습니다. 이것들은 로그인 플로우와 활성 상태 확인 프로브입니다. `GET /access-granters`는 유효한 키가 필요하지만 특정 권한은 필요 없으므로, 로그인한 모든 사용자가 접근 변경과 관련하여 어느 관리자에게 문의할지 확인할 수 있습니다. --- ## 권한 집합 -권한 집합을 사용하면 매번 개별 토큰을 직접 선택하는 대신 명명된 역할을 적용할 수 있습니다. 새 대시보드 사용자나 API key마다 수십 개의 권한을 일일이 선택하는 대신 집합을 선택하면, 해당 집합에 할당된 모든 사람이 일관되고 검토 가능한 권한을 보유합니다. 커스텀 집합을 편집하면 이미 할당된 모든 사용자에게 새 권한이 재적용되므로, 역할 변경이 모든 멤버를 일일이 수정하는 대신 한 번의 편집으로 완료됩니다. +권한 집합을 사용하면 매번 개별 토큰을 일일이 선택하는 대신 이름이 지정된 역할을 적용할 수 있습니다. 새 대시보드 사용자나 API 키마다 수십 개의 권한을 하나씩 선택하는 대신, 집합을 선택하면 해당 집합에 할당된 모든 사람이 일관되고 검토 가능한 권한을 갖게 됩니다. 커스텀 집합을 편집하면 이미 할당된 모든 사용자에게 새 권한이 재적용되므로, 역할 변경이 모든 멤버를 일일이 수정하는 대신 한 번의 편집으로 완료됩니다. -모든 조직에는 세 가지 기본 집합이 시드됩니다: +모든 조직에는 세 가지 기본 제공 집합이 초기화됩니다: | 집합 | 권한 | 대상 | |---|---|---| | `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | 모든 운영 영역에 대한 읽기 전용 접근. | -| `standard` | `read-only`의 모든 권한 + `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | 읽기 전용 + 일상적인 온콜 작업: 쿼리 실행, 세션 재평가, 인시던트 확인, AI 어시스턴트 사용. | -| `admin` | 모든 할당 가능한 권한 | 조직의 완전한 제어. | +| `standard` | `read-only`의 모든 권한과 `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` 추가 | 읽기 전용 권한에 더해 일상적인 온콜 작업: 쿼리 실행, 세션 재평가, 인시던트 확인, AI 어시스턴트 사용. | +| `admin` | 할당 가능한 모든 권한 | 조직의 완전한 제어. | -세 가지 기본 집합은 **변경 불가**합니다. `read-only`, `standard`, `admin`은 항상 동일한 의미를 가지므로 정책 및 온보딩에서 안전하게 참조할 수 있습니다. 운영자는 조직 특화 역할(예: "대시보드 작성자" 역할 또는 "컬렉터 전용" 역할)을 모델링하기 위해 추가적인 **커스텀 집합**을 생성할 수 있습니다. +세 가지 기본 제공 집합은 **변경 불가**합니다. 그 이름은 항상 동일한 의미를 가지므로, `read-only`, `standard`, `admin`은 정책 및 온보딩에서 안전하게 참조할 수 있습니다. 운영자는 조직 특정 역할을 모델링하기 위해 추가적인 **커스텀 집합**을 생성할 수 있습니다(예: "대시보드 작성자" 역할 또는 "수집기 전용" 역할). -집합은 대시보드에 표시되며, API에서는 `GET /permission-sets`(목록, `users:read`로 게이팅)와 `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name`(커스텀 집합 생성, 편집, 삭제, `settings:write`로 게이팅)으로 관리됩니다. 기본 집합의 삭제 또는 편집은 거부됩니다. +집합은 대시보드에 표시되며, `GET /permission-sets`(목록 조회, `users:read` 필요)와 `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name`(커스텀 집합 생성, 편집, 삭제, `settings:write` 필요)를 통해 API로 관리됩니다. 기본 제공 집합의 삭제 또는 편집은 거부됩니다. -집합 멤버십은 두 가지 다른 기능을 지원합니다: +집합 멤버십은 다른 두 기능을 지원합니다: -- **`DEFAULT_USER_PERMISSIONS`**(관리자가 **+ 새 사용자**를 열 때 미리 선택된 권한)는 기본적으로 `standard` 집합으로 설정됩니다. -- **`agenteye-orgctl`의 `--set` 플래그**(운영자 멤버 관리)는 명명된 집합에서 멤버를 시작하며, 이후 `--add` / `--remove`로 세부 조정할 수 있습니다. +- **`DEFAULT_USER_PERMISSIONS`**(관리자가 **+ 새 사용자**를 열 때 미리 선택되는 권한)는 `standard` 집합으로 기본 설정됩니다. +- **`agenteye-orgctl`의 `--set` 플래그**(운영자 멤버 관리)는 이름이 지정된 집합에서 멤버를 시작하고, 이후 `--add` / `--remove`로 세부 조정합니다. -> **참고:** 집합에 키 할당 불가능한 권한이 포함된 경우(예: `keys:update`를 포함하는 커스텀 집합), 해당 집합에서 키를 시드할 때 할당 불가능한 토큰은 제외됩니다. 그렇지 않으면 서버가 HTTP 422로 키를 거부합니다. 대시보드 사용자에게는 이 제한이 적용되지 않습니다. +> **참고:** 집합에 키 할당이 불가능한 권한이 포함된 경우(예: `keys:update`를 포함한 커스텀 집합), 해당 집합에서 키를 초기화하면 할당 불가능한 토큰은 제외됩니다. 그렇지 않으면 서버가 HTTP 422로 키를 거부합니다. 대시보드 사용자에게는 이 제한이 적용되지 않습니다. --- ## 부트스트랩 관리자 키 -관리자 키는 운영자가 아무것도 없는 상태에서 액세스를 구축할 수 있게 해주는 단일 루트 자격 증명입니다. 이를 통해 다른 모든 스코프 키를 생성하고, 첫 번째 대시보드 사용자를 초대하고, 다른 키가 존재하기 전에 인스턴스를 구성할 수 있습니다. 이 키는 keys API를 통해 생성하지 않는 유일한 키이며, 서버가 처음 부팅 시 접근 가능하도록 환경에서 프로비저닝됩니다. +관리자 키는 운영자가 아무것도 없는 상태에서 접근을 시작할 수 있게 해주는 단일 루트 자격증명입니다. 이를 통해 다른 모든 범위 지정 키를 발급하고, 첫 번째 대시보드 사용자를 초대하며, 다른 키가 존재하기 전에 인스턴스를 구성할 수 있습니다. 이 키는 키 API를 통해 생성하는 것이 아니라, 서버가 처음 부팅 시 접근 가능하도록 환경에서 프로비저닝됩니다. -서버의 `ADMIN_KEY` 환경 변수를 설정하세요. 모든 시작 시 서버는 이 값을 모든 권한을 가진 관리자 키로 upsert합니다. +서버에 `ADMIN_KEY` 환경 변수를 설정하세요. 매 시작 시 서버는 이 값을 모든 권한을 가진 관리자 키로 업서트합니다. 교체하려면: `ADMIN_KEY`를 새 시크릿으로 변경하고 서버를 재시작하세요. --- -## 조직 스코핑 +## 조직 범위 지정 -**조직 자체는 이 keys API가 아닌 운영자가 대역 외에서 생성하고 관리합니다.** 조직 및 멤버 생명주기(조직 생성/이름 변경/삭제/제거, 멤버 추가/업데이트/제거)는 **`agenteye-orgctl`** CLI로 수행하며, HTTP API나 대시보드 버튼이 없습니다. **변경되지 않는 것은: per-org API keys는 여전히 조직 멤버가 대시보드(또는 이 keys API를 통해) 발행합니다.** +**조직 자체는 이 키 API가 아닌 운영자가 대역 외에서 생성하고 관리합니다.** 조직 및 멤버 수명 주기(조직 생성/이름 변경/삭제/제거; 멤버 추가/업데이트/삭제)는 **`agenteye-orgctl`** CLI로 수행하며, HTTP API나 대시보드 버튼이 없습니다. **변경되지 않는 것은: 조직별 API 키는 여전히 조직 멤버가 대시보드(또는 이 키 API를 통해)에서 발급합니다.** -멀티 조직 배포에서 조직 멤버가 생성하는 모든 키(이 keys API 또는 대시보드 **Keys** 페이지를 통해)는 **하나의 조직**에 속하며 해당 조직의 데이터만 읽거나 쓸 수 있습니다. 조직은 키 생성 시 스탬프되어 모든 요청에서 적용됩니다. 두 가지 부트스트랩 키만 예외입니다: `admin` 키(`ADMIN_KEY`에서 시드)와 `dashboard-assistant` 키(`AGENT_API_KEY`에서 시드)는 **인스턴스 스코프**(조직 없음)입니다. 대시보드는 `admin` 키로 인증하여 로그인한 멤버를 대신해 per-org 요청을 프록시합니다. 단일 테넌트 배포는 이를 신경 쓸 필요가 없으며, 모든 키는 기본 제공 `default` 조직에 속합니다. +다중 조직 배포에서 조직 멤버가 생성하는 모든 키(이 키 API 또는 대시보드 **키** 페이지를 통해)는 **하나의 조직**에 속하며, 해당 조직의 데이터만 읽거나 쓸 수 있습니다. 조직은 키 생성 시 스탬프되어 모든 요청에서 적용됩니다. 두 부트스트랩 키만 예외입니다. `admin` 키(`ADMIN_KEY`에서 초기화)와 `dashboard-assistant` 키(`AGENT_API_KEY`에서 초기화)는 **인스턴스 범위**(조직 없음)입니다. 대시보드는 `admin` 키로 인증하여 로그인한 멤버를 대신해 조직별 요청을 프록시합니다. 단일 테넌트 배포는 이에 대해 고민할 필요가 없습니다. 모든 키는 기본 제공 `default` 조직에 속합니다. --- ## 키 생성 -관리자 키(또는 `keys:create` 권한을 가진 키)를 사용하여 추가적인 스코프 키를 생성하세요. +관리자 키(또는 `keys:create` 권한이 있는 키)를 사용하여 추가 범위 지정 키를 생성하세요. -### 컬렉터 키 (수집 전용) +### 수집기 키 (수집 전용) ```bash curl -s -X POST http://your-server/keys \ @@ -193,7 +193,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -HTTP API로 키를 생성할 때는 `key` 값을 직접 제공합니다. 강력한 시크릿을 선택하고 안전하게 보관하세요. (대시보드는 반대 방식으로 동작합니다: 강력한 시크릿을 생성하여 생성 시 한 번만 표시합니다. [대시보드의 키 관리](#key-management-in-the-dashboard)를 참조하세요.) 응답은 키가 생성되었음을 확인합니다: +HTTP API로 키를 생성할 때는 `key` 값을 직접 제공합니다. 강력한 시크릿을 선택하고 안전하게 보관하세요. (대시보드는 반대 방식으로 작동합니다. 강력한 시크릿을 자동으로 생성하여 생성 시 한 번 표시합니다. [대시보드에서의 키 관리](#key-management-in-the-dashboard)를 참조하세요.) 응답은 키가 생성되었음을 확인합니다: ```json { @@ -213,13 +213,13 @@ curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -키 시크릿은 목록 응답에서 반환되지 않으며, ID, 이름, 권한만 반환됩니다. +키 시크릿은 목록 응답에 반환되지 않으며, ID, 이름, 권한만 반환됩니다. --- ## 키 비활성화 -비활성화는 키 레코드를 삭제하지 않고 즉시 액세스를 취소합니다. +비활성화하면 키 레코드를 삭제하지 않고 즉시 접근이 폐기됩니다. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -241,40 +241,40 @@ curl -s -X POST http://your-server/keys//regenerate \ --- -## 대시보드의 키 관리 +## 대시보드에서의 키 관리 -대시보드의 **Keys** 페이지는 위의 모든 작업을 위한 UI를 제공합니다. 목록을 보려면 `keys:read` 권한이 있는 키가 필요하고, 생성/편집/비활성화/재생성 작업에는 각각 `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate`가 필요합니다. 키의 권한 편집(`keys:update`)은 키 생성(`keys:create`)과 별개이므로, 운영자에게 기존 키의 스코프 변경 없이 키 발행 권한만 부여하거나, 그 반대도 가능합니다. 관리자 키는 이 모든 것을 포함합니다. +대시보드의 **키** 페이지는 위의 모든 작업에 대한 UI를 제공합니다. 목록을 보려면 `keys:read` 권한이 있는 키가 필요하며, 생성/편집/비활성화/재생성 작업에는 각각 `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate`가 필요합니다. 키 권한 편집(`keys:update`)은 키 생성(`keys:create`)과 별개이므로, 기존 키의 범위를 변경할 수 없지만 키를 발급할 수 있는 권한을 운영자에게 부여하거나, 그 반대도 가능합니다. 관리자 키는 이 모든 권한을 포함합니다. -대시보드에서 키를 생성할 때 시크릿을 직접 입력하지 않습니다. 대시보드가 강력한 시크릿을 생성하여 생성 시 **한 번** 표시합니다. 즉시 복사하여 안전하게 보관하세요. 재생성과 마찬가지로 다시는 표시되지 않습니다. 키의 권한을 직접 선택하거나 권한 집합에서 시드할 수 있습니다(아래 참조). +대시보드에서 키를 생성할 때는 시크릿을 직접 제공하지 않습니다. 대시보드가 강력한 시크릿을 생성하여 생성 시 **한 번** 표시합니다. 즉시 복사하여 안전하게 보관하세요. 재생성과 마찬가지로 다시는 표시되지 않습니다. 키의 권한을 직접 선택하거나 권한 집합에서 초기화할 수 있습니다(아래 참조). -![API Keys 페이지: 각 키의 이름, 부여된 권한, 생성 시간이 표시된 카드, 재생성 및 비활성화 액션 포함; `admin` 같은 보호된 키는 표시됨](/agenteye/images/api-keys.png) +![API 키 페이지: 키 이름, 부여된 권한, 생성 시간을 표시하고 재생성 및 비활성화 작업이 있는 키별 카드; `admin` 같은 보호된 키는 표시됨](/agenteye/images/api-keys.png) --- ## 권장 키 구성 -| 키 | 권한 | 사용자 | +| 키 | 권한 | 사용 주체 | |---|---|---| -| `admin` (`ADMIN_KEY` 환경 변수로 부트스트랩) | 모든 권한 | 운영/설정, 및 대시보드(`ADMIN_KEY`로 인증, 권한 검사를 통해 사용자 요청 프록시) | -| 호스트별 컬렉터 키 | `events:add` | 각 에이전트 머신의 컬렉터 | -| `dashboard-assistant` (`AGENT_API_KEY` 환경 변수로 부트스트랩) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI 어시스턴트, 자동으로 시드됨, **보호됨**; API를 통해 편집 불가 | -| 어시스턴트 텔레메트리 키 (선택사항) | `events:add` | 활성화된 경우 AI 어시스턴트 자체 계측 | +| `admin` (`ADMIN_KEY` 환경 변수를 통한 부트스트랩) | 모든 권한 | 운영/설정, 그리고 대시보드(`ADMIN_KEY`로 인증하여 권한 확인과 함께 사용자 요청 프록시) | +| 호스트별 수집기 키 | `events:add` | 각 에이전트 머신의 수집기 | +| `dashboard-assistant` (`AGENT_API_KEY` 환경 변수를 통한 부트스트랩) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI 어시스턴트, 자동으로 초기화됨, **보호됨**; API를 통해 편집 불가 | +| 어시스턴트 텔레메트리 키 (선택 사항) | `events:add` | AI 어시스턴트 자체 계측(활성화된 경우) | -> **참고:** 어시스턴트 키는 서버가 `AGENT_API_KEY` 환경 변수(에이전트가 `AGENTEYE_API_KEY`로 제공하는 동일한 시크릿)에서 **자동으로 시드**합니다. 수동 키 발행 단계나 관리자 키가 필요하지 않습니다. 권한은 소스 코드에 고정되어 잘못된 구성으로 스코프가 확장되지 않습니다: 이벤트/평가/대시보드 읽기, 대시보드 쓰기, 쿼리 읽기/쓰기/실행(AI에게 쿼리 작성 요청 흐름용). 모든 SQL은 여전히 사용자 작성 쿼리와 동일한 읽기 전용 역할 및 보호된 SQL 경로를 거치므로, 이는 *데이터 표면*이 아닌 *작성 표면*을 확장합니다. 파괴적 작업(`queries:delete`, `dashboards:delete`)은 의도적으로 어시스턴트 키에서 제외됩니다. `admin` 키와 마찬가지로 **보호됨**: keys API를 통해 비활성화하거나 재생성할 수 없으며, `AGENT_API_KEY`를 변경하고 재시작해야만 교체됩니다. 대시보드 *사용자*는 어시스턴트를 보고 사용하려면 추가로 `agent:use` 권한이 필요합니다. 자체 계측을 활성화하는 경우, 어시스턴트에게 별도의 `events:add` 전용 키를 부여하세요. +> **참고:** 어시스턴트 키는 `AGENT_API_KEY` 환경 변수(에이전트가 `AGENTEYE_API_KEY`로 제공하는 동일한 시크릿)에서 서버가 **자동으로 초기화**합니다. 수동 키 발급 단계가 없으며 관리자 키도 관여하지 않습니다. 권한은 소스 코드에 고정되어 있으므로 잘못된 구성으로 범위가 확대될 수 없습니다: 이벤트/평가/대시보드에 대한 읽기 권한과 "AI에게 쿼리 작성 요청" 작성 플로우를 위한 대시보드 쓰기 및 쿼리 읽기/쓰기/실행 권한입니다. 모든 SQL은 사용자 작성 쿼리와 동일한 읽기 전용 역할 및 보호된 SQL 경로를 통해 처리되므로, 이것은 *작성 범위*를 확대하는 것이지 데이터 범위를 확대하는 것이 아닙니다. 파괴적인 작업(`queries:delete`, `dashboards:delete`)은 의도적으로 어시스턴트 키에 포함되지 않습니다. `admin` 키와 마찬가지로 **보호됨**: 키 API를 통해 비활성화하거나 재생성할 수 없으며, `AGENT_API_KEY`를 변경하고 재시작하여 교체해야 합니다. 대시보드 *사용자*는 어시스턴트를 보고 사용하려면 추가로 `agent:use` 권한이 필요합니다. 자체 계측을 활성화하는 경우 어시스턴트에 별도의 `events:add` 전용 키를 제공하세요. --- -## 업그레이드 및 하위 호환성 참고사항 +## 업그레이드 및 하위 호환성 참고 사항 -기존 인스턴스를 업그레이드하는 경우에만 필요합니다. 신규 배포는 건너뛰어도 됩니다. +기존 인스턴스를 업그레이드하는 경우에만 필요합니다. 새 배포는 건너뛸 수 있습니다. -> Audits 출시 시, 기존 권한 보유자는 알림과 동일한 역할 형태에 따라 확장되었습니다: `alerts:read`를 보유한 모든 사용자 및 권한 집합은 `audits:read`를 획득했고, `alerts:write` 보유자는 `audits:write`를 획득했습니다. 기존 API keys는 **확장되지 않았습니다**. 감사 기능이 필요한 키에는 `audits:*`를 명시적으로 부여하세요. +> 감사 기능이 출시되었을 때, 기존 부여 대상은 알림과 동일한 역할 형태로 권한이 확대되었습니다. `alerts:read`를 보유한 모든 사용자와 권한 집합은 `audits:read`를 받았고, `alerts:write`를 보유한 모든 대상은 `audits:write`를 받았습니다. 기존 API 키는 **확대되지 않았습니다**. 감사 기능이 필요한 키에는 `audits:*`를 명시적으로 부여하세요. -> 레거시 `alerts:ack` 토큰의 저장된 권한 부여는 `incidents:ack`로 파싱되어, 온콜 담당자가 키 재발행 없이 액세스를 유지합니다. 이 토큰은 더 이상 대시보드 사용자 편집기에서 할당할 수 없으며, 대신 `incidents:ack`가 제공됩니다. +> 레거시 `alerts:ack` 토큰의 저장된 권한은 `incidents:ack`로 파싱되어, 온콜 담당자가 재키 발급 없이 접근을 유지합니다. 이 토큰은 더 이상 대시보드 사용자 편집기에서 할당할 수 없으며, 매트릭스는 대신 `incidents:ack`를 제공합니다. --- ## 다음 단계 -- [Python SDK](/ko/agenteye/python-sdk): 에이전트 코드가 이벤트를 전송할 때 인증하는 방법. -- [Security](/ko/agenteye/security): 로그인, 액세스 제어, per-organization 데이터 격리 작동 방식. \ No newline at end of file +- [Python SDK](/ko/agenteye/python-sdk): 에이전트 코드가 이벤트 전송 시 인증하는 방법. +- [보안](/ko/agenteye/security): 로그인, 접근 제어, 조직별 데이터 격리 작동 방식. \ No newline at end of file diff --git a/docs/ko/agenteye/assistant.mdx b/docs/ko/agenteye/assistant.mdx index f7c0aee4..f5059d49 100644 --- a/docs/ko/agenteye/assistant.mdx +++ b/docs/ko/agenteye/assistant.mdx @@ -1,15 +1,15 @@ --- title: "AI 어시스턴트" -description: "에이전트 데이터에 대해 일반 영어로 질문하고, 근거로 바로 연결되는 답변을 받으세요." +description: "에이전트 데이터에 대해 일반 영어로 질문하면 근거와 함께 직접 연결되는 답변을 받을 수 있습니다." --- -에이전트 데이터에 대해 평문으로 질문하고, 근거로 바로 연결되는 답변을 받으세요. SQL을 작성하거나 대시보드를 뒤질 필요 없이 — **Failproof AI Observability** 어시스턴트는 팀 누구든 에이전트에 대한 답변을 가장 빠르게 얻을 수 있는 방법입니다. +에이전트 데이터에 대해 자연어로 질문하면 근거에 바로 연결되는 답변을 받을 수 있습니다. SQL을 작성하거나 대시보드를 뒤질 필요 없이 — **Failproof AI Observability** 어시스턴트는 팀 누구나 에이전트에 대한 답변을 가장 빠르게 얻을 수 있는 방법입니다. -![대시보드 내에서 평문 질문에 답하는 Failproof AI Observability 어시스턴트. 실시간 Agent Activity 테이블, 에이전트별 모델 사용 현황, 작성된 인사이트, 그리고 실행된 쿼리가 인라인으로 표시됨](/agenteye/images/assistant.png) -*평문으로 질문하면 내 데이터를 기반으로 한 답변을 받을 수 있습니다. 여기서는 어떤 에이전트가 가장 바쁘고 어떤 모델을 사용하는지 분석하며, 모든 숫자를 검증할 수 있도록 실행된 쿼리도 함께 보여줍니다.* +![대시보드 내에서 자연어 질문에 답변하는 Failproof AI Observability 어시스턴트. 실시간 에이전트 활동 테이블, 에이전트별 모델 사용 현황, 작성된 핵심 내용이 표시되며 실행된 쿼리가 인라인으로 표시됩니다.](/agenteye/images/assistant.png) +*자연어로 질문하면 자체 데이터를 기반으로 답변을 구성합니다. 여기서는 가장 활발한 에이전트와 사용 모델을 분석하며, 모든 수치를 직접 확인할 수 있도록 실행된 쿼리도 함께 보여줍니다.* -별도로 배울 것이 없습니다. 채팅을 열고, 알고 싶은 것을 입력하고, 돌아온 링크를 따라가세요: +별도로 배울 것이 없습니다. 채팅을 열고, 알고 싶은 것을 입력하고, 반환된 링크를 따라가기만 하면 됩니다: ``` You: which sessions errored today? @@ -24,40 +24,40 @@ AI: This run took 12 steps across 3 tools and failed near the end when a Links: the session, the failing event, and that evaluation. ``` -## 바로 질문하고, 증거로 바로 이동 +## 그냥 물어보고, 바로 근거로 이동 -추측을 멈추고 쿼리 작성도 멈추세요. "이번 주 프로덕션에서 품질 트렌드는 어떤가요?", "오늘 오류가 발생한 세션은 무엇인가요?", "이 세션을 요약해 주세요" 같은 질문을 하면, 쿼리를 직접 작성하고 결과를 읽는 대신 몇 초 안에 명확한 답변을 얻을 수 있습니다. +추측을 멈추고 쿼리 작성도 그만하세요. "이번 주 프로덕션 품질 추세는 어떤가요?", "오늘 오류가 발생한 세션은?", "이 세션을 요약해줘"라고 물으면, 쿼리를 직접 작성하고 읽는 것보다 몇 초 안에 명확한 답변을 받을 수 있습니다. -모든 답변에는 근거가 함께 제공됩니다. 어시스턴트는 답변 도출에 사용한 정확한 세션, 저장된 쿼리, 대시보드로의 링크를 제공하므로, 그냥 믿는 대신 직접 클릭해서 확인할 수 있습니다. 또한 **페이지 인식** 기능이 있어, 특정 세션을 보고 있는 상태에서 "이 세션"에 대해 질문하면 어떤 실행을 의미하는지 이미 알고 있습니다. 기록 전환기에서 이전 대화를 다시 열고 이어서 진행할 수도 있습니다. +모든 답변에는 근거가 함께 제공됩니다. 어시스턴트는 답변을 도출하는 데 사용한 정확한 세션, 저장된 쿼리, 대시보드를 링크로 제공하므로, 말을 그냥 믿는 것이 아니라 직접 클릭해서 확인할 수 있습니다. 또한 **페이지 인식** 기능이 있어, 특정 세션을 보는 중에 "이 세션"에 대해 물으면 어느 실행을 의미하는지 이미 알고 있습니다. 이전 대화는 기록 전환기에서 나중에 다시 열어 이어서 진행할 수 있습니다. -## 좋은 답변을 저장된 쿼리나 대시보드로 변환 +## 좋은 답변을 저장된 쿼리나 대시보드로 전환 -보관할 만한 답변이 있다면, 어시스턴트에게 저장을 요청하세요. 저장된 쿼리를 위한 SQL을 초안으로 작성하거나, 해당 쿼리들로 대시보드를 구성한 후 **승인 / 거부** 카드를 보여줍니다. 승인을 클릭하기 전까지는 아무것도 저장되지 않으므로, "그냥 물어보기"의 속도와 최종 결정권이 항상 내 손에 있는 장점을 모두 누릴 수 있습니다. +보관할 만한 답변이 있으면 어시스턴트에게 저장을 요청하세요. 저장된 쿼리를 위한 SQL 초안을 작성하거나, 해당 쿼리들로 대시보드를 구성한 다음 **승인 / 거부** 카드를 보여줍니다. 승인을 클릭하기 전까지는 아무것도 저장되지 않으므로, "그냥 물어보기"의 속도를 유지하면서 최종 결정권은 항상 여러분에게 있습니다. -**Queries** 페이지에서는 한 단계 더 나아가 SQL 작성자 역할을 합니다. 원하는 쿼리를 설명하면("지난 7일간 에이전트별 오류율 보기") SQL이 편집기에 바로 스트리밍되고, **수락** 또는 **거부**할 수 있는 diff 뷰가 열립니다. +**쿼리** 페이지에서는 한 단계 더 나아가 SQL 작성자 역할을 합니다. 원하는 쿼리를 설명("지난 7일간 에이전트별 오류율 표시")하면 편집기에 SQL을 직접 스트리밍하고, 변경 사항이 적용되기 전에 **수락** 또는 **거부**할 수 있도록 diff 뷰를 열어줍니다. -![Observability Queries 페이지와 SQL 편집기](/agenteye/images/query-lab.png) -*Queries 페이지: 어시스턴트가 초안 읽기 전용 쿼리를 스트리밍하면 수락하거나 거부할 수 있는 편집기입니다.* +![Observability 쿼리 페이지와 SQL 편집기](/agenteye/images/query-lab.png) +*쿼리 페이지: 어시스턴트가 수락 또는 거부할 수 있는 읽기 전용 초안 쿼리를 스트리밍하는 편집기입니다.* -여기서 질문을 통해 SQL을 작성하는 기능은 편집기의 **실행** 버튼과 동일한 `queries:run` 권한을 사용합니다. 다른 곳에서의 채팅에는 `agent:use` 권한이 필요합니다. +여기서 질문을 통해 SQL을 작성하면 `queries:run` 권한을 사용하며, 이는 편집기의 **실행** 버튼과 동일한 권한입니다. 다른 곳에서의 채팅에는 `agent:use` 권한이 필요합니다. -## 팀 전체에 안심하고 공개 가능 +## 전체 팀에 안심하고 공개 가능 -어시스턴트가 어떤 것을 건드릴지 걱정하지 않고 전체 팀에 공개할 수 있습니다: +어시스턴트가 무엇을 건드릴지 걱정하지 않고 모든 사람에게 열어둘 수 있습니다: -- **이미 볼 수 있는 것만 읽습니다.** 답변은 본인의 읽기 권한 범위 내로 제한되므로 데이터 접근 범위가 확장되지 않습니다. -- **모든 쓰기 작업은 승인을 기다립니다.** 저장된 쿼리와 대시보드는 명시적인 승인 클릭 이후에만 생성되며, 이 게이트를 끄는 설정은 없습니다. -- **절대 삭제할 수 없습니다.** 삭제 도구가 노출되지 않으며 어시스턴트는 삭제 권한을 가지지 않습니다. 삭제는 대시보드에서 내 손으로만 가능합니다. -- **내 조직 내에서만 작동합니다.** 어시스턴트는 현재 보고 있는 조직만 접근할 수 있습니다. -- **내 질문은 내 것입니다.** 프롬프트와 답변은 내 Observability 데이터베이스에 저장되며, 제품 분석은 사용 메타데이터만 기록하고 프롬프트 내용은 기록하지 않습니다. +- **이미 볼 수 있는 것만 읽습니다.** 답변은 자신의 읽기 권한 범위로 제한되므로 데이터 접근 범위가 확장되지 않습니다. +- **모든 쓰기 작업은 사용자 확인을 기다립니다.** 저장된 쿼리와 대시보드는 명시적인 승인 클릭 후에만 생성되며, 이 게이트를 끄는 설정은 없습니다. +- **아무것도 삭제할 수 없습니다.** 삭제 도구는 노출되지 않으며 어시스턴트는 삭제 권한을 보유하지 않습니다. 삭제는 대시보드에서 직접 수행해야 합니다. +- **조직 내에서만 동작합니다.** 어시스턴트는 현재 보고 있는 조직만 볼 수 있습니다. +- **질문 내용은 사용자 소유입니다.** 프롬프트와 답변은 자체 Observability 데이터베이스에 저장되며, 제품 분석은 사용 메타데이터만 기록하고 프롬프트 텍스트는 절대 기록하지 않습니다. ## 찾는 방법 -어시스턴트는 조직(`//...`) 하위 모든 페이지의 오른쪽 가장자리에 표시됩니다. 레일을 클릭하거나 `⌘J` / `Ctrl+J`를 눌러 전체 채팅 패널로 확장하고, 가장자리를 드래그하여 크기를 조절할 수 있으며, 설정한 너비는 새로고침 후에도 유지됩니다. 사용하려면 **`agent:use`** 권한이 필요하며, 없을 경우 레일이 비활성화됩니다. 배포 환경에서 아직 활성화되지 않은 경우(LLM 연결이 필요함), 작동하는 채팅 대신 비활성화된 레일이 표시됩니다. +어시스턴트는 조직 하위의 모든 페이지(`//...`) 오른쪽 가장자리에 위치합니다. 사이드바를 클릭하거나 `⌘J` / `Ctrl+J`를 눌러 전체 채팅 패널로 확장하고, 가장자리를 드래그하여 크기를 조정할 수 있으며 너비는 새로고침 후에도 기억됩니다. 사용하려면 **`agent:use`** 권한이 필요하며, 권한이 없으면 사이드바가 회색으로 표시됩니다. 아직 배포에서 활성화되지 않은 경우(LLM 연결이 필요함), 작동하는 채팅 대신 비활성화된 사이드바가 표시됩니다. ## 관련 항목 -- [CLI and agents](/ko/agenteye/cli-and-agents) -- [Queries](/ko/agenteye/queries) -- [Dashboards](/ko/agenteye/dashboards) -- [Evaluation suite](/ko/agenteye/evaluation-suite) \ No newline at end of file +- [CLI 및 에이전트](/ko/agenteye/cli-and-agents) +- [쿼리](/ko/agenteye/queries) +- [대시보드](/ko/agenteye/dashboards) +- [평가 스위트](/ko/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/ko/agenteye/audits.mdx b/docs/ko/agenteye/audits.mdx index 46635619..3971181a 100644 --- a/docs/ko/agenteye/audits.mdx +++ b/docs/ko/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- -title: "감사(Audits): 자동 신뢰성 분석가" -description: "Failproof AI Observability는 여러분이 규칙으로 정의하지 않은 장애를 찾아내고, 정확히 무엇을 수정해야 하는지 우선순위와 근거가 담긴 목록으로 제공합니다." +title: "감사(Audit): 자동 신뢰성 분석기" +description: "Failproof AI Observability는 규칙으로 정의하지 않은 장애까지 찾아내어, 무엇을 수정해야 하는지 근거가 뒷받침된 우선순위 목록으로 정리해 드립니다." --- -Failproof AI Observability는 여러분이 규칙으로 정의하지 않은 장애를 찾아내고, 정확히 무엇을 수정해야 하는지 우선순위와 근거가 담긴 목록으로 제공합니다. 마치 분석가가 매일 밤 로그를 살펴보고, 아침이 되면 짧은 요약 목록을 책상 위에 남겨두는 것과 같습니다. +Failproof AI Observability는 규칙으로 정의하지 않은 장애까지 찾아내어, 무엇을 수정해야 하는지 근거가 뒷받침된 우선순위 목록으로 정리해 드립니다. 마치 분석가가 매일 밤 로그를 샅샅이 훑어보고 아침이 되면 핵심 목록을 책상 위에 올려두는 것과 같습니다.
-*2분 투어: 예약 실행부터 즉시 실행할 수 있는 수정 방안까지.* +*2분 투어: 스케줄 실행부터 바로 조치할 수 있는 수정 사항까지.* -![감사(Audits) 페이지: 각 세션에서 장애 패턴을 스캔하는 반복 작업 목록으로, 일정과 민감도가 표시됩니다](/agenteye/images/audits.png) -*각 감사(audit)는 세션 데이터를 분석하여 우선순위와 근거가 담긴 권고사항을 작성하는 반복 작업입니다.* +![감사 페이지: 세션에서 장애 패턴을 스캔하는 반복 작업 목록으로, 각 항목에는 스케줄과 민감도가 표시됩니다](/agenteye/images/audits.png) +*각 감사는 세션을 분석하여 우선순위와 근거가 담긴 권고 사항을 작성하는 반복 작업입니다.* -## 다음에 무엇을 수정할지 추측하지 마세요 +## 다음에 무엇을 고쳐야 할지 더 이상 추측하지 마세요 -알림은 이미 감시하고 있다고 알고 있는 문제를 잡아냅니다. 감사(Audits)는 여러분이 미처 몰랐던 문제를 잡아냅니다. 설정한 일정에 따라 감사는 모든 에이전트 세션을 읽고 수정할 가치가 있는 패턴을 찾아내므로, 직접 로그를 스크롤하며 눈으로 발견하는 대신 결과를 바탕으로 행동하는 데 시간을 쓸 수 있습니다. +알림은 이미 알고 있는 문제를 포착하고, 감사는 아직 모르는 문제를 포착합니다. 설정한 스케줄에 따라 감사는 모든 에이전트 세션을 읽고 수정할 가치가 있는 패턴을 탐색합니다. 덕분에 로그를 직접 스크롤하며 문제를 찾아 헤매는 대신, 발견된 결과에 따라 즉시 행동하는 데 시간을 쓸 수 있습니다. -단 한 번의 실행으로 실제 프로덕션에서 에이전트를 망가뜨리는 장애 유형들을 집중적으로 검사합니다: +단 한 번의 실행으로 프로덕션 환경에서 에이전트를 실제로 망가뜨리는 장애 유형을 탐색합니다: -- **오류 클러스터**: 동일한 근본 원인 아래 반복되는 장애. -- **기준선 대비 드리프트**: 정상으로 알려진 구간에서 조용히 벗어나는 동작. -- **트랜스크립트의 목표 실패**: 기술적으로는 완료됐지만 실제 목적을 달성하지 못한 실행. -- **도구 오남용**: 잘못된 도구 선택, 잘못된 인자, 또는 API 호출을 낭비하는 루프. -- **품질 및 비용 트레이드오프**: 더 저렴하게 얻을 수 있는 결과에 과도한 비용을 지불하는 부분. -- **커버리지 공백**: 어떤 평가(eval)나 알림도 감시하지 않는 동작. +- **오류 클러스터**: 동일한 근본 원인 아래 반복되는 동일한 장애. +- **기준 대비 드리프트**: 정상 기준 윈도우에서 조용히 벗어나는 동작 변화. +- **트랜스크립트에서의 목표 미달성**: 기술적으로는 완료됐지만 실제로 작업을 수행하지 못한 실행. +- **툴 오용**: 잘못된 툴 선택, 잘못된 인수, 또는 호출을 낭비하는 루프. +- **품질과 비용의 균형**: 더 저렴하게 얻을 수 있는 출력에 과도한 비용을 지불하는 경우. +- **커버리지 공백**: 어떤 eval이나 알림도 모니터링하지 않는 동작. -**민감도** 설정 하나(낮음, 보통, 높음)로 검사 강도를 조절할 수 있어, 노이즈가 많은 스테이징 에이전트와 엄격하게 관리되는 프로덕션 에이전트 각각을 원하는 신호에 맞게 튜닝할 수 있습니다. +**민감도** 설정 하나(낮음, 보통, 높음)로 탐색 강도를 조절할 수 있어, 노이즈가 많은 스테이징 에이전트와 엄격하게 관리되는 프로덕션 에이전트 각각에 원하는 신호 수준을 맞출 수 있습니다. -## 모든 권고사항에는 근거가 따라옵니다 +## 모든 권고 사항에는 근거가 있습니다 -발견된 내용을 그냥 믿을 필요가 없습니다. 각 권고사항은 출처가 된 정확한 세션과 이를 발견한 SQL을 함께 제시하므로, 주장을 역으로 파헤칠 필요 없이 클릭 한 번으로 근거를 확인하고 문제를 검증할 수 있습니다. +발견된 내용을 그냥 믿을 필요가 없습니다. 각 권고 사항은 해당 내용의 근거가 된 정확한 세션과 이를 찾아낸 SQL을 인용하므로, 주장을 역으로 검증하는 대신 클릭 한 번으로 증거를 열어 문제를 직접 확인할 수 있습니다. -발견된 내용이 유출된 자격 증명에 관한 것이라면 한 걸음 더 나아가 일치된 개별 이벤트를 링크로 연결합니다. 하나를 클릭하면 긴 트랜스크립트의 맨 위가 아니라, 이미 선택된 상태로 해당 세션의 정확한 순간으로 이동합니다. 링크는 이벤트 이름을 표시하며, 발견된 내용에 감지된 시크릿을 절대 복사하지 않으므로 권고사항을 읽는 것이 자격 증명이 기록되는 또 다른 장소가 되지 않습니다. 세션이 보존 기간을 지나 이벤트가 더 이상 존재하지 않는 경우, 페이지는 잘못 클릭했는지 의아하게 만들지 않고 명확하게 알려줍니다. +유출된 자격 증명에 관한 발견의 경우 한 단계 더 나아가, 매칭된 개별 이벤트로 직접 연결됩니다. 클릭하면 세션 내 해당 정확한 순간으로 이동하며, 이미 선택된 상태로 표시됩니다 — 긴 트랜스크립트의 맨 위부터 스크롤할 필요가 없습니다. 링크에는 이벤트 이름이 표시되며, 감지된 시크릿은 발견 내용에 복사되지 않으므로 발견 내용을 읽는 것이 자격 증명이 기록되는 또 다른 장소가 되지 않습니다. 세션이 보존 기간을 지나 더 이상 존재하지 않는 이벤트가 있다면, 잘못 클릭한 것인지 의아해하는 일 없이 페이지에서 명확하게 알려줍니다. -이것이 바로 감사를 정직하게 유지하는 방법이기도 합니다. 서버는 인용된 모든 세션이 실제로 존재하는지 확인하고 **근거가 유효하지 않은 권고사항은 폐기**하므로, 감사는 조사하되 절대 만들어내지 않습니다. 목록에 올라오는 것은 실제로 존재하고, 재현 가능하며, 가장 중요한 것이 맨 위에 오도록 중요도에 따라 순위가 매겨져 있습니다. +이것이 감사를 정직하게 유지하는 방식이기도 합니다. 서버는 인용된 모든 세션이 실제로 존재하는지 확인하고 **근거가 유효하지 않은 권고 사항은 폐기**하므로, 감사는 조사하되 결코 만들어내지 않습니다. 목록에 올라오는 것은 실제로 존재하고, 재현 가능하며, 중요도에 따라 순위가 매겨져 있고, 가장 큰 개선 효과를 가져오는 항목이 맨 위에 위치합니다. -## 수정 사항을 가드레일로 전환하기 +## 수정 사항을 가드레일로 전환하세요 -문제를 수정하는 것은 절반의 성과일 뿐입니다. 나머지 절반은 그것이 조용히 다시 나타나지 않도록 하는 것입니다. 모든 발견 사항에는 **재발 알림을 작성하는 원클릭 단축키**가 포함되어 있으며, 조정 가능한 합리적인 시작 트리거가 미리 채워져 있습니다. 발견 사항을 닫고 알림을 활성화하면, 다음에 그 패턴이 다시 나타날 때 미래의 감사에서 재발견하는 대신 알림을 받게 됩니다. +문제를 수정하는 것은 절반의 성과에 불과합니다. 나머지 절반은 동일한 문제가 조용히 재발하지 않도록 하는 것입니다. 모든 발견 내용에는 **재발 알림을 초안으로 작성하는 원클릭 바로가기**가 제공되며, 조정 가능한 합리적인 기본 트리거가 미리 채워져 있습니다. 발견 내용을 닫고 알림을 활성화하면, 해당 패턴이 다시 나타날 때 미래의 감사에서 재발견하는 대신 즉시 알림을 받게 됩니다. -## 찾는 위치 +## 찾는 방법 -감사(Audits)는 대시보드의 **`//audits`** 에 있습니다(사이드바 → *analyze* → *audits*). 실행 결과 및 발견 사항 조회에는 **`audits:read`** 권한이 필요하고, 감사 생성·편집·분류에는 **`audits:write`** 권한이 필요합니다. 감사의 범위와 주기를 설정한 후, 다음 예약 실행을 기다리지 않고 즉시 결과를 원할 때는 **Run now**를 누르세요. +감사는 대시보드의 **`//audits`** (사이드바에서 *분석* → *감사*)에 있습니다. 실행 및 발견 내용 조회에는 **`audits:read`** 권한이 필요하고, 감사 생성, 편집 및 분류에는 **`audits:write`** 권한이 필요합니다. 감사의 범위와 주기를 설정한 후, 다음 스케줄 실행을 기다리지 않고 즉시 결과를 원할 때는 **지금 실행**을 클릭하세요. ## 관련 항목 -- [알림(Alerts)](/ko/agenteye/alerts): 이미 알고 있는 임계값이 초과되는 순간 즉시 알림을 받습니다. -- [평가(Evaluations)](/ko/agenteye/evaluations): 모든 실행에 점수를 매겨 품질 저하가 자동으로 드러나도록 합니다. -- [오류 추적(Error tracking)](/ko/agenteye/error-tracking): 에이전트가 발생시키는 오류를 그룹화하고 추적합니다. -- [인시던트(Incidents)](/ko/agenteye/incidents): 감사에서 발견된 문제를 수정 완료까지 추적합니다. \ No newline at end of file +- [알림](/ko/agenteye/alerts): 이미 알고 있는 임계값이 초과되는 순간 즉시 알림을 받으세요. +- [평가](/ko/agenteye/evaluations): 모든 실행에 점수를 매겨 품질 저하가 자동으로 드러나게 하세요. +- [오류 추적](/ko/agenteye/error-tracking): 에이전트가 발생시키는 오류를 그룹화하고 추적하세요. +- [인시던트](/ko/agenteye/incidents): 감사에서 발견된 문제를 수정 완료까지 추적하세요. \ No newline at end of file diff --git a/docs/ko/agenteye/cli-and-agents.mdx b/docs/ko/agenteye/cli-and-agents.mdx index 3a26ee42..40897d81 100644 --- a/docs/ko/agenteye/cli-and-agents.mdx +++ b/docs/ko/agenteye/cli-and-agents.mdx @@ -1,55 +1,54 @@ --- title: "CLI" -description: "Failproof AI Observability 배포 전체를 명령어 하나로 관리하세요." +description: "Failproof AI Observability 배포 전체를 단 하나의 명령으로." --- - -Failproof AI Observability 배포 전체를 명령어 하나로 관리하세요. 터미널을 벗어나지 않고 프로덕션을 점검하고, API 키를 발급하고, 인시던트를 확인할 수 있습니다. 이를 CI에 스크립트로 작성하거나, 코딩 에이전트가 일상 언어로 대신 처리하도록 할 수도 있습니다. +Failproof AI Observability 배포 전체를 단 하나의 명령으로. 터미널을 벗어나지 않고도 프로덕션 상태를 확인하고, API 키를 발급하거나 인시던트를 확인할 수 있습니다. 이 모든 작업을 CI에 스크립트로 자동화하거나, 코딩 에이전트가 자연어로 대신 처리하도록 할 수도 있습니다. ```bash pipx install agenteye -agenteye login --email you@example.com # 6자리 코드가 이메일로 전송됩니다 -agenteye --json sessions --since 24h # 최근 하루 동안의 모든 에이전트 실행, 최신순 정렬 +agenteye login --email you@example.com # 6자리 코드가 받은편지함으로 전송됩니다 +agenteye --json sessions --since 24h # 지난 하루 동안의 모든 에이전트 실행 기록, 최신순 ``` -*`agenteye` CLI는 대시보드와 통신합니다. 이벤트를 서버로 전송하는 콜렉터와는 별개의 도구입니다.* +*`agenteye` CLI는 대시보드와 통신합니다. 이벤트를 서버로 전송하는 수집기(collector)와는 별도의 도구입니다.* -## 배포 전체를 명령어 하나로 +## 배포 전체를 단 하나의 명령으로 -간단한 질문에 답하려고 탭을 여러 개 열어둘 필요가 없습니다. `agenteye` CLI는 단일 바이너리로 데이터를 읽고 조직을 관리합니다. 대시보드를 클릭해야 했던 작업이 이제 한 줄 명령어로 해결됩니다. 다시 실행하거나, 별칭으로 등록하거나, 런북에 붙여 넣을 수 있습니다. 네 가지 기능을 제공합니다: +간단한 질문 하나에 답하려고 탭을 여러 개 열어둘 필요가 없습니다. `agenteye` CLI는 단일 바이너리로 데이터를 조회하고 조직을 관리합니다. 대시보드를 클릭해 가며 확인하던 작업이 이제는 한 줄 명령으로 끝납니다. 다시 실행하거나, 별칭(alias)을 만들거나, 런북에 붙여넣을 수도 있습니다. 네 가지 기능 영역을 제공합니다: -- **데이터 조회:** `sessions`, `events`, `evals`, `errors`를 시간, 에이전트, 환경별로 필터링합니다. -- **조직 관리:** `keys`, `users`, `settings`, `alerts`, `incidents`를 관리합니다. -- **분석 실행:** 저장된 SQL과 이벤트 데이터에 대한 임시 `query` 실행기를 사용합니다. -- **어시스턴트 질의:** `agent ask`로 대시보드에서 대화하는 것과 동일한 읽기 전용 분석가에게 질문합니다. +- **데이터 조회:** 시간, 에이전트, 환경별로 필터링된 `sessions`, `events`, `evals`, `errors` +- **조직 관리:** `keys`, `users`, `settings`, `alerts`, `incidents` +- **분석 실행:** 저장된 SQL 쿼리 및 이벤트 데이터에 대한 임시 `query` 실행 +- **어시스턴트 활용:** `agent ask`로 대시보드의 읽기 전용 분석가와 동일한 기능에 접근 -`pipx`로 한 번 설치하고, 이메일로 전송된 6자리 코드로 로그인하면 준비 완료입니다. 세션은 약 하루 동안 유지되며, 만료되면 `agenteye login`을 다시 실행하세요. 브라우저를 열지 않고도 프로덕션 점검, 키 발급, 인시던트 트리아지 등을 처리할 수 있습니다: +`pipx`로 한 번 설치하고, 이메일로 전송된 6자리 코드로 로그인하면 바로 사용할 수 있습니다. 세션은 약 하루 동안 유지되며, 만료되면 `agenteye login`을 다시 실행하세요. 브라우저를 열지 않고도 프로덕션 상태 점검, 키 발급, 발생 중인 인시던트 트리아지 등을 모두 처리할 수 있습니다: ```bash agenteye errors --since 24h --aggregate # 오류 유형별로 그룹화된 장애 현황 -agenteye incidents list --state firing # 현재 발생 중인 인시던트 -agenteye keys create ci --add events:add # 이벤트 푸시만 가능한 키 (비밀값은 한 번만 표시) +agenteye incidents list --state firing # 현재 발생 중인 인시던트 목록 +agenteye keys create ci --add events:add # 이벤트 푸시만 가능한 키 생성, 시크릿은 한 번만 표시 ``` -한 가지 알아둘 사항: `--json`과 같은 전역 옵션은 명령어 앞에 위치합니다. `agenteye --json sessions`가 올바른 형식이며, `agenteye sessions --json`은 올바르지 않습니다. +한 가지 알아두어야 할 습관이 있습니다. `--json`과 같은 전역 옵션은 명령어 앞에 위치해야 합니다. `agenteye --json sessions`가 올바른 형식이며, `agenteye sessions --json`은 잘못된 형식입니다. -## 스크립트 작성 및 CI 연동 +## 스크립트로 작성하고 CI에 연결하기 -모든 명령어에 `--json`을 사용할 수 있으며, 이것이 모든 것을 바꿉니다. 정제된 JSON은 stdout으로 출력되고, 사람을 위한 상태 메시지와 경고는 stderr로 출력됩니다. 따라서 `--json`으로 캡처한 결과를 불필요한 줄 없이 바로 `jq`에 파이프할 수 있습니다. 이 덕분에 CLI는 프롬프트에서 직접 사용하는 경우와 출력을 파싱하는 코딩 에이전트 모두에게 동일하게 유용합니다: +모든 명령은 `--json` 옵션을 지원하며, 이를 통해 활용 가능성이 크게 넓어집니다. 깔끔한 JSON은 stdout으로 출력되고, 사람이 읽는 상태 메시지와 경고는 stderr로 출력됩니다. 따라서 `--json`으로 캡처한 출력을 불필요한 줄 제거 없이 바로 `jq`에 파이프할 수 있습니다. 이 덕분에 CLI는 터미널에서 직접 사용할 때뿐만 아니라 출력을 파싱하는 코딩 에이전트에게도 똑같이 유용합니다: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -무인 실행을 위해 설계되었습니다. 터미널이 연결되어 있지 않으면 확인 프롬프트가 자동으로 건너뛰어져 파이프라인이 중단되지 않습니다. 모든 명령어는 의미 있는 종료 코드를 반환합니다: `0` 성공, `4` 미로그인, `5` 권한 부족 (메시지에 해당 권한 명시, 예: `alerts:write`), `3` 대시보드 연결 불가. 스크립트에서 `4`를 감지하면 재인증을 수행하고, `5`를 감지하면 관리자에게 정확히 어떤 권한이 필요한지 알 수 있어 오류 원인을 모른 채 실패하는 상황을 방지합니다. +무인(unattended) 실행에 적합하게 설계되어 있습니다. 터미널이 연결되지 않은 경우 확인 프롬프트가 자동으로 건너뛰어지므로 파이프라인에서 중단되는 일이 없으며, 모든 명령은 의미 있는 종료 코드를 반환합니다. `0`은 성공, `4`는 미로그인, `5`는 권한 부족(메시지에 필요한 권한이 명시됨, 예: `alerts:write`), `3`은 대시보드에 연결할 수 없음을 나타냅니다. 스크립트는 `4`를 받으면 재인증하거나, `5`를 받으면 관리자에게 정확히 무엇을 요청해야 하는지 알 수 있습니다. 원인을 모른 채 실패하는 일이 없습니다. -## 코딩 에이전트가 일상 언어로 처리하도록 +## 코딩 에이전트가 자연어로 처리하도록 하기 -더 나아가, 이 플래그들을 직접 기억할 필요조차 없습니다. **CLI 스킬**은 `agenteye-cli`라는 작은 Agent Skill 폴더로, Claude Code나 Codex 같은 코딩 에이전트가 일상 언어 요청으로 CLI를 사용할 수 있도록 가르쳐 줍니다. "오늘 뭔가 문제가 있나요?"라고 물으면 에이전트가 적절한 명령어를 선택해 실행하고 결과를 설명해 줍니다. +더 나아가, 이 플래그들을 모두 기억할 필요조차 없습니다. **CLI 스킬**은 `agenteye-cli`라는 이름의 작은 Agent Skill 폴더로, Claude Code나 Codex 같은 코딩 에이전트에게 자연어 요청으로 CLI를 구동하는 방법을 가르쳐줍니다. "오늘 뭔가 문제가 있나요?"라고 물으면 에이전트가 적절한 명령을 선택해 실행하고 결과를 문장으로 답해줍니다. -Claude Code의 경우, `agenteye-cli` 폴더를 `~/.claude/skills/`에 넣으면 자동으로 인식됩니다. Failproof AI Observability가 해당 폴더를 제공하며, 이미 설치된 CLI를 활용하는 것이므로 추가 설치가 필요하지 않습니다. 단, 로그인은 직접 먼저 해야 합니다. 스킬은 이메일 코드 로그인을 대신 완료할 수 없습니다. +Claude Code의 경우, `agenteye-cli` 폴더를 `~/.claude/skills/`에 넣으면 자동으로 인식됩니다. Failproof AI Observability에서 해당 폴더를 제공하며, 이미 설치된 CLI를 구동하는 것뿐이므로 추가로 설치할 것은 없습니다. 먼저 직접 로그인해두세요. 스킬은 이메일 코드 방식의 로그인을 대신 완료할 수 없습니다. -에이전트는 사용자 권한으로 CLI를 실행하므로, 로그인이 허용하는 모든 작업(읽기와 쓰기 모두)이 가능합니다: 키 생성, 설정 변경, 인시던트 해결. CLI의 "정말 하시겠습니까?" 프롬프트는 에이전트에게는 표시되지 않으므로, 스킬은 변경 작업 전에 정확한 명령어를 명시하고 사용자의 승인을 기다리도록 작성되어 있습니다. 사용자가 직접 확인 단계가 됩니다. +에이전트는 CLI를 사용자 본인의 권한으로 실행하므로, 로그인 권한이 허용하는 모든 작업을 수행할 수 있습니다. 읽기와 쓰기 모두 가능하며, 키 생성, 설정 변경, 인시던트 해결까지 포함됩니다. 에이전트 실행 시에는 CLI의 확인 프롬프트가 표시되지 않으므로, 스킬은 변경 작업 전에 정확한 명령을 제시하고 사용자의 승인을 기다리도록 작성되어 있습니다. 확인 단계는 사용자 본인이 담당합니다. ```text you Why did session run-001 fail? @@ -58,7 +57,7 @@ agent Running: agenteye --json events --session-id run-001 --all The checkout-agent hit a TimeoutError on its third tool call. ``` -읽기 작업은 즉시 실행되고, 쓰기 작업은 매번 사용자 확인을 기다립니다: +읽기 작업은 즉시 처리되고, 모든 쓰기 작업은 사용자의 확인을 기다립니다: ```text you Give CI a key that can only push events. @@ -74,7 +73,7 @@ agent Done. Key "ci" created with events:add only. The secret is shown once, so ## 관련 문서 -- [CLI 레퍼런스](/ko/agenteye/cli): 모든 명령어, 플래그, JSON 구조. -- [에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes): 복사해서 쓸 수 있는 `jq` 패턴과 종료 코드 처리. -- [CLI 에이전트 스킬](/ko/agenteye/cli-skill): `agenteye-cli` 스킬 설치 및 실행. -- [AI 어시스턴트](/ko/agenteye/assistant): `agent ask`가 연결되는 대시보드 내 분석가. \ No newline at end of file +- [CLI 레퍼런스](/ko/agenteye/cli): 모든 명령어, 플래그, JSON 구조 +- [에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes): 복사해서 바로 쓸 수 있는 `jq` 패턴과 종료 코드 처리 +- [CLI 에이전트 스킬](/ko/agenteye/cli-skill): `agenteye-cli` 스킬 설치 및 실행 +- [AI 어시스턴트](/ko/agenteye/assistant): `agent ask`와 연결되는 대시보드 내 분석가 \ No newline at end of file diff --git a/docs/ko/agenteye/cli-recipes.mdx b/docs/ko/agenteye/cli-recipes.mdx index ddd25fc1..e0537e01 100644 --- a/docs/ko/agenteye/cli-recipes.mdx +++ b/docs/ko/agenteye/cli-recipes.mdx @@ -1,30 +1,30 @@ --- -title: "에이전트를 위한 CLI 레시피" -description: "세션, 이벤트, 평가 데이터를 스크립트나 코딩 에이전트가 자동화할 수 있는 형태로 변환하는 복사-붙여넣기 쿼리 패턴과 jq 레시피를 소개합니다." +title: "에이전트용 CLI 레시피" +description: "세션, 이벤트, 평가 데이터를 스크립트나 코딩 에이전트가 자동화할 수 있는 형태로 변환하는 복사 붙여넣기 쿼리 패턴과 jq 레시피." --- -스크립트나 코딩 에이전트에서 세션, 이벤트, 평가 데이터를 직접 가져오고(재평가 트리거 포함) `jq`로 바로 파이프할 수 있는 깔끔한 JSON을 stdout으로 출력합니다. 이 레시피들은 Failproof AI Observability의 데이터를 터미널 사용자나 AI 코딩 에이전트(Claude Code, Cursor)가 대시보드를 클릭하지 않고도 쿼리하고 자동화할 수 있도록 해줍니다. +스크립트나 코딩 에이전트에서 세션, 이벤트, 평가 데이터를 직접 조회하고 (재평가 트리거 포함), `jq`로 바로 파이프할 수 있는 깔끔한 JSON을 stdout으로 받아보세요. 이 레시피들은 Failproof AI Observability의 데이터를 터미널 사용자나 AI 코딩 에이전트(Claude Code, Cursor)가 대시보드 클릭 없이 조회하고 자동화할 수 있는 형태로 변환합니다. -아래 패턴들은 Failproof AI Observability CLI(`agenteye`)에서 바로 복사-붙여넣기하여 사용할 수 있습니다. 설치, 인증, 전체 옵션 목록은 [CLI](/ko/agenteye/cli)를 참고하세요. 내장 도움말은 `agenteye -h` 또는 `agenteye -h`로 확인할 수 있습니다. +아래 패턴들은 Failproof AI Observability CLI(`agenteye`)에서 바로 복사해서 사용할 수 있습니다. 설치, 인증, 전체 옵션 목록은 [CLI](/ko/agenteye/cli)를 참조하고, 내장 도움말은 `agenteye -h` 또는 `agenteye -h`로 확인하세요. ## 기본 원칙 -1. **전역 옵션은 명령어 *앞에* 위치합니다.** `agenteye --json sessions`는 올바르지만 `agenteye sessions --json`은 올바르지 않습니다. 전역 옵션은 `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`입니다. -2. **출력을 파싱할 때는 반드시 `--json`을 전달하세요.** 데이터는 **stdout**으로 JSON 형태로 출력되고, 사람이 읽는 상태 메시지와 오류는 **stderr**로 출력되므로 stdout을 `jq`로 깔끔하게 파이프할 수 있습니다. -3. **stderr 텍스트가 아닌 종료 코드로 분기하세요.** `0` 정상 · `1` 예기치 않은 오류 · `2` 잘못된 인수 · `3` 대시보드에 연결할 수 없음 · `4` 로그인되지 않았거나 만료됨 · `5` 권한 없음 · `6` 리소스를 찾을 수 없음. -4. **`-h`로 탐색하세요.** 모든 명령어는 필터, 값 형식, JSON 구조를 문서화하고 있습니다. +1. **글로벌 옵션은 커맨드 *앞에* 옵니다.** `agenteye --json sessions`가 올바른 형태이며, `agenteye sessions --json`은 잘못된 형태입니다. 글로벌 옵션은 `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`입니다. +2. **출력을 파싱할 때는 반드시 `--json`을 사용하세요.** 데이터는 JSON으로 **stdout**에 출력되고, 사람이 읽는 상태 정보와 오류는 **stderr**로 출력되므로 stdout을 `jq`로 깔끔하게 파이프할 수 있습니다. +3. **종료 코드를 기준으로 분기하세요.** stderr 텍스트가 아닌 종료 코드를 사용하세요: `0` 성공 · `1` 예기치 않은 오류 · `2` 잘못된 인수 · `3` 대시보드에 연결할 수 없음 · `4` 로그인하지 않았거나 만료됨 · `5` 권한 없음 · `6` 리소스를 찾을 수 없음. +4. **`-h`로 확인하세요.** 모든 커맨드에서 필터, 값 형식, JSON 구조를 문서화합니다. -## 최초 설정 +## 초기 설정 ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # --base-url을 반복 입력하지 않아도 됩니다 -agenteye login --email you@example.com # 이메일로 받은 코드를 붙여넣기; 약 24시간 유효 +agenteye login --email you@example.com # 이메일로 받은 코드를 붙여넣으세요; 약 24시간 유효 ``` ## 작업 전 인증 확인 -`whoami`는 세션이 없거나 만료된 경우에도 오류를 발생시키지 않고 `logged_in:false`를 반환하므로, 에이전트가 인증 상태를 안전하게 확인할 수 있습니다. (base URL이 설정되지 않았거나 대시보드에 연결할 수 없는 경우에는 여전히 non-zero로 종료될 수 있습니다.) +`whoami`는 세션이 없거나 만료된 경우에도 오류를 발생시키지 않고 `logged_in:false`를 반환하므로, 에이전트가 안전하게 인증 상태를 확인할 수 있습니다. (base URL이 설정되지 않았거나 대시보드에 연결할 수 없는 경우에는 여전히 비정상 종료될 수 있습니다.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,46 +32,46 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## 실패하거나 점수가 낮은 세션 찾기 +## 실패하거나 낮은 점수의 세션 찾기 ```bash -# 최근 24시간 내에 평가 오류가 발생한 세션 +# 지난 24시간 내 평가가 오류 상태인 세션 agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# 특정 에이전트에서 helpfulness 점수가 0.5 이하인 평가 +# 특정 에이전트의 helpfulness 점수가 0.5 이하인 평가 agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -점수 필터링은 `sessions`가 아닌 **`evals`**에서 수행됩니다. `--score KEY:MIN..MAX`는 반복 사용 가능하며 AND로 결합됩니다. 양쪽 경계는 선택 사항입니다(`..0.5`는 ≤ 0.5, `0.9..`는 ≥ 0.9를 의미). 요청당 최대 20개의 점수 필터를 전달할 수 있으며, 초과 시 HTTP 400을 반환합니다. `sessions`는 `evals`와 `--env`, `--status`, `--agent-id`, `--session-id`, 시간 범위 필터를 공유하지만 `--score`는 없습니다. +점수 필터링은 `sessions`가 아닌 **`evals`**에서 사용합니다. `--score KEY:MIN..MAX`는 반복 사용 가능하며 AND 조건으로 결합됩니다. 각 경계값은 선택 사항입니다(`..0.5`는 ≤ 0.5, `0.9..`는 ≥ 0.9). 요청당 최대 20개의 점수 필터를 사용할 수 있으며, 초과 시 HTTP 400이 반환됩니다. `sessions`는 `evals`와 `--env`, `--status`, `--agent-id`, `--session-id`, 시간 범위 필터를 공유하지만 `--score`는 없습니다. ## 세션 전체 읽기 -단일 `session show` 명령어는 없습니다. 이벤트 내역과 세션 평가를 조합하여 사용하세요: +단일 `session show` 커맨드는 없습니다. 이벤트 추적과 세션 평가를 함께 사용하세요: ```bash # 세션의 최신 평가 (상태 + 점수) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# 실행의 모든 이벤트 (전체 조회를 위해 --limit 값을 높이세요) +# 실행의 모든 이벤트 (전체 조회를 위해 --limit을 높이세요) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# 세션의 도구 호출만 조회 (raw 페이로드를 얻으려면 --full이 필요합니다) +# 세션 내 도구 호출만 조회 (원시 페이로드를 가져오려면 --full이 필요합니다) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **참고:** 기본적으로 `events`는 페이로드가 없는 빠른 피드를 읽습니다. 각 이벤트에는 서버에서 계산된 한 줄 `summary`와 `is_error`, 토큰 수 같은 플래그가 포함되지만 `payload`는 `{}`로 반환됩니다. raw 페이로드를 가져오려면 `--full`(또는 `--fields payload`)을 추가하세요. 전체 피드는 대규모에서 느리므로 범위를 제한하세요. `--full`과 단일 `--session-id`를 함께 사용하는 것을 권장합니다. +> **참고:** 기본적으로 `events`는 페이로드 없는 빠른 피드를 읽습니다. 각 이벤트에는 서버에서 계산한 한 줄 요약 `summary`와 `is_error`, 토큰 수 같은 플래그가 포함되지만 `payload`는 `{}`로 반환됩니다. 원시 페이로드를 가져오려면 `--full`(또는 `--fields payload`)을 추가하세요. 전체 피드는 대규모에서 느리므로 범위를 제한하세요: `--full`과 단일 `--session-id`를 함께 사용하세요. -## 전체 데이터 가져오기 (페이지네이션) +## 전체 데이터 조회 (페이지네이션) 결과는 최신순으로 정렬되며 커서 기반 페이지네이션을 사용합니다. ```bash -# 한 번에: 200행씩 페이지를 나눠 최대 500행을 가져옵니다 +# 한 번에: 200행 페이지로 최대 500행 조회 agenteye --json events --session-id run-001 --limit 500 --all > events.json -# 수동 페이징: next_cursor를 다시 전달합니다 +# 수동 페이징: next_cursor를 다시 전달 page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -79,41 +79,41 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## --fields로 출력 줄이기 -에이전트가 읽어야 하는 내용을 줄이기 위해 키를 제한합니다 (테이블과 `--json` 모두 적용). +에이전트가 읽어야 할 양을 줄이기 위해 테이블과 `--json` 모두에서 키를 제한합니다. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -알 수 없는 필드 이름은 유효한 목록과 함께 거부됩니다(종료 코드 `2`). 필드 이름을 확인하는 간편한 방법입니다. +알 수 없는 필드 이름은 유효한 목록과 함께 종료 코드 `2`로 거부되므로, 필드 이름을 확인하는 간단한 방법으로 활용할 수 있습니다. -## 유효한 필터 값 탐색 +## 유효한 필터 값 확인 ```bash -agenteye --json list envs | jq -r '.values[]' # --env에 사용할 값 -agenteye --json list tools | jq -r '.values[]' # 도구 이름; agents, models, event_types 등도 사용 가능 +agenteye --json list envs | jq -r '.values[]' # --env의 값 +agenteye --json list tools | jq -r '.values[]' # 도구 이름; agents, models, event_types 등도 가능 agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX의 유효한 KEY ``` ## 조직 선택 (멀티 테넌트) -둘 이상의 조직에 속해 있다면 로그인 시 활성 테넌트를 선택할 수 있습니다 (저장됨): +둘 이상의 조직에 속해 있는 경우, 로그인 시 활성 테넌트를 선택하세요 (저장됩니다): ```bash agenteye login --org acme --email you@corp.com # 로그인과 동시에 테넌트 설정 agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # 단일 명령어에서 재정의 +agenteye --org globex --json sessions --since 24h # 단일 커맨드에만 적용 ``` -`--org` 없이 다중 조직 로그인을 시도하면 non-zero로 종료되며 선택 가능한 조직 목록이 출력됩니다. +`--org` 없이 멀티 조직 로그인 시 비정상 종료되며 선택 가능한 조직 목록이 출력됩니다. -## SDK/컬렉터용 API 키 발급 +## SDK/콜렉터용 API 키 발급 ```bash -# 시크릿은 한 번만 출력됩니다. --json 사용 시 .key 필드에 있습니다 +# 시크릿은 한 번만 출력되며, --json 사용 시 .key 필드로 확인 key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # 교체; 폐기하려면 agenteye keys disable ci-bot --yes +agenteye keys regenerate ci-bot --yes # 교체; 취소하려면 agenteye keys disable ci-bot --yes ``` ## 저장된 쿼리 또는 임시 쿼리 실행 @@ -123,7 +123,7 @@ agenteye --json query run --sql "select count(*) from analytics.events" | jq '.r agenteye --json query run errs --arg prod | jq '.rows' # 저장된 쿼리 + 위치 인수 $1 ``` -## 인시던트 비대화형 트리아지 +## 비대화형 인시던트 트리아지 ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **참고:** 변경 작업은 `--json`이 있거나 stdin이 TTY가 아닌 경우 확인 프롬프트를 자동으로 건너뛰므로 에이전트가 중단되지 않습니다. 다른 곳에서는 `--yes`/`-y`를 명시적으로 전달하여 건너뛰세요. +> **참고:** 변경 작업은 `--json` 사용 시 또는 stdin이 TTY가 아닌 경우 확인 프롬프트를 자동으로 건너뛰므로 에이전트가 멈추지 않습니다. 다른 곳에서 명시적으로 건너뛰려면 `--yes`/`-y`를 전달하세요. ## 스크립트에서 종료 코드 처리 @@ -149,7 +149,7 @@ esac ## JSON 출력 구조 -| 명령어 | stdout JSON (`--json` 사용 시) | +| 커맨드 | stdout JSON (`--json` 사용 시) | |---|---| | `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` 또는 `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | @@ -158,22 +158,22 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key`는 한 번만 표시) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key`는 최초 1회만 표시) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (모두) | 리소스 객체, 삭제 시 `{"deleted": true, "id"}` | -| 실패 (모두, `--json` 사용 시) | stdout에 `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | +| create/update/delete (모든 경우) | 리소스 객체, 또는 삭제의 경우 `{"deleted": true, "id"}` | +| 실패 (모든 경우, `--json` 사용 시) | stdout에 `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | -- 각 **이벤트** 항목(`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. `--full`(또는 `--fields payload`)로 전체 피드를 요청하지 않으면 `payload`는 `{}`입니다. -- 각 **평가** 항목(`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- 각 **세션** 항목(`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- 각 **이벤트** 항목 (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. `payload`는 `--full`(또는 `--fields payload`)로 전체 피드를 요청하지 않으면 `{}`입니다. +- 각 **평가** 항목 (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- 각 **세션** 항목 (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -각 명령어의 `--fields`는 해당 항목의 필드 이름만 허용합니다. `sessions`와 `evals`의 필드 집합이 다르므로 한쪽에서 유효한 이름이 다른 쪽에서 거부될 수 있습니다. +각 커맨드의 `--fields`는 해당 항목의 필드 이름만 허용합니다. `sessions`와 `evals`에서 필드 집합이 다르므로 한쪽에서 유효한 이름이 다른 쪽에서는 거부될 수 있습니다. ## 다음 단계 -- [CLI](/ko/agenteye/cli): 모든 명령어의 설치, 인증, 전체 옵션 레퍼런스. +- [CLI](/ko/agenteye/cli): 설치, 인증, 모든 커맨드의 전체 옵션 레퍼런스. - [CLI 에이전트 스킬](/ko/agenteye/cli-skill): 이 레시피들을 코딩 에이전트가 로드할 수 있는 스킬로 패키징하기. -- [API 키](/ko/agenteye/api-keys): CLI, SDK, 컬렉터가 인증에 사용하는 키 생성 및 범위 설정. -- [Python SDK](/ko/agenteye/python-sdk): Failproof AI Observability로 이벤트를 전송하여 이 레시피가 쿼리할 데이터를 만들기. \ No newline at end of file +- [API 키](/ko/agenteye/api-keys): CLI, SDK, 콜렉터 인증에 사용하는 키 생성 및 범위 설정. +- [Python SDK](/ko/agenteye/python-sdk): Failproof AI Observability로 이벤트를 전송하여 이 레시피로 조회할 데이터 만들기. \ No newline at end of file diff --git a/docs/ko/agenteye/cli-skill.mdx b/docs/ko/agenteye/cli-skill.mdx index 33b87795..2d8e2e36 100644 --- a/docs/ko/agenteye/cli-skill.mdx +++ b/docs/ko/agenteye/cli-skill.mdx @@ -1,29 +1,29 @@ --- -title: "Failproof AI Observability CLI 에이전트 스킬" -description: "코딩 에이전트에게 '오늘 뭔가 고장났나요?'라고 물어보면, 명령어를 외울 필요 없이 실시간 Failproof AI Observability 데이터를 바탕으로 답을 받을 수 있습니다." +title: "Failproof AI Observability CLI Agent Skill" +description: "코딩 에이전트에게 '오늘 뭔가 문제가 있나요?'라고 물어보면, 명령어를 외울 필요 없이 실시간 Failproof AI Observability 데이터로 답변해 드립니다." --- -코딩 에이전트에게 *"오늘 뭔가 고장났나요?"* 라고 물어보면, 명령어를 외울 필요 없이 실시간 Failproof AI Observability 데이터를 바탕으로 답을 받을 수 있습니다. **Failproof AI Observability CLI 스킬** (`agenteye-cli`)은 *에이전트 스킬*입니다. Claude Code나 Codex 같은 코딩 에이전트가 필요할 때 불러오는 작은 인스트럭션 폴더로, *"CI에 이벤트만 푸시할 수 있는 키를 만들어줘"* 나 *"발생 중인 인시던트를 ack하고 나한테 할당해줘"* 같은 자연어 요청을 통해 [`agenteye` CLI](/ko/agenteye/cli)로 Observability 배포 환경을 조작하는 방법을 에이전트에게 가르쳐줍니다. +코딩 에이전트에게 *"오늘 뭔가 문제가 있나요?"*라고 물어보면, 명령어를 외울 필요 없이 실시간 Failproof AI Observability 데이터로 답변해 드립니다. **Failproof AI Observability CLI 스킬** (`agenteye-cli`)은 *Agent Skill*로, Claude Code나 Codex 같은 코딩 에이전트가 필요할 때 불러오는 소규모 지침 폴더입니다. 이 스킬은 에이전트에게 *"CI에 이벤트만 푸시할 수 있는 키를 주세요"* 또는 *"발생 중인 인시던트를 확인하고 나에게 할당해 주세요"*와 같은 자연어 요청을 통해 [`agenteye` CLI](/ko/agenteye/cli)로 Observability 배포를 운영하는 방법을 가르쳐 줍니다. -이것은 **서비스나 별도의 바이너리가 아닙니다**. 배포할 것이 없습니다. 이미 설치된 CLI 위에서 동작하며, 에이전트가 `agenteye --json …`을 실행하고 깔끔한 JSON을 파싱한 뒤 산문 형태로 답변해줍니다. 에이전트가 할 수 있는 모든 것은 여러분이 직접 같은 명령어를 입력해도 할 수 있는 것들입니다. +이것은 서비스도 아니고 별도의 바이너리도 **아닙니다**. 배포할 것이 없습니다. 이미 설치된 CLI 위에서 동작합니다. 에이전트가 `agenteye --json …`을 실행하고, 깔끔한 JSON을 파싱한 뒤, 문장으로 답변해 드립니다. 에이전트가 할 수 있는 모든 작업은 여러분이 직접 동일한 명령어를 입력해도 할 수 있습니다. --- ## 다른 Failproof AI Observability 인터페이스와의 관계 -Failproof AI Observability는 동일한 데이터와 컨트롤에 접근할 수 있는 네 가지 방법을 제공합니다. 이들은 서로 보완적입니다. +Failproof AI Observability는 동일한 데이터와 컨트롤에 접근하는 네 가지 방법을 제공합니다. 이들은 서로 보완적입니다: | 인터페이스 | 설명 | 실행 위치 | 사용 시점 | |---|---|---|---| -| **[CLI](/ko/agenteye/cli)** | `agenteye` 명령어/플래그 레퍼런스 | 터미널 | 특정 명령어를 직접 실행하거나 스크립트로 만들 때 | -| **[CLI 레시피](/ko/agenteye/cli-recipes)** | `jq`/파이프라인 패턴 복붙 모음 | 터미널 / 스크립트 | CLI를 자동화에 연결할 때 | -| **CLI 스킬** (이 문서) | CLI에 자연어로 접근하는 진입점 | 워크스테이션의 코딩 에이전트 | 그냥 물어보고 에이전트가 명령어를 선택하게 하고 싶을 때 | -| **[Evaluator 스킬](/ko/agenteye/evaluator-skill)** | 스코어링 서비스를 설계하고 구축하는 형제 스킬 | 워크스테이션의 코딩 에이전트 | eval 점수를 *읽는* 게 아니라 *생성*하고 싶을 때 | -| **[Python SDK 스킬](/ko/agenteye/python-sdk-skill)** | 에이전트가 텔레메트리를 내보내도록 계측하는 형제 스킬 | 워크스테이션의 코딩 에이전트 | 이 스킬이 읽는 이벤트를 에이전트가 *생성*하게 하고 싶을 때 | -| **[대시보드 내 AI 어시스턴트](/ko/agenteye/assistant)** | 대시보드에 내장된 채팅 | 서버 사이드 (대시보드 내) | 대시보드에서 데이터를 Q&A 방식으로 조회하고 싶을 때 | +| **[CLI](/ko/agenteye/cli)** | `agenteye`의 커맨드/플래그 레퍼런스 | 터미널 | 특정 명령어를 실행하거나 스크립트로 작성할 때 | +| **[CLI 레시피](/ko/agenteye/cli-recipes)** | 복사-붙여넣기 `jq`/파이프라인 패턴 | 터미널 / 스크립트 | CLI를 자동화에 연결할 때 | +| **CLI 스킬** (이 문서) | CLI의 자연어 프론트 엔드 | 워크스테이션의 코딩 에이전트 | 그냥 물어보고 에이전트가 명령어를 선택하게 하고 싶을 때 | +| **[Evaluator 스킬](/ko/agenteye/evaluator-skill)** | 스코어링 서비스를 설계하고 구축하는 형제 스킬 | 워크스테이션의 코딩 에이전트 | eval 점수를 읽는 것이 아니라 *생성*하고 싶을 때 | +| **[Python SDK 스킬](/ko/agenteye/python-sdk-skill)** | 에이전트가 텔레메트리를 내보내도록 계측하는 형제 스킬 | 워크스테이션의 코딩 에이전트 | 에이전트가 이 스킬이 읽는 이벤트를 *생성*하도록 하고 싶을 때 | +| **[대시보드 내 AI 어시스턴트](/ko/agenteye/assistant)** | 대시보드에 내장된 채팅 | 서버 측 (대시보드 내) | 데이터에 대해 대시보드 내 Q&A를 원할 때 | -스킬 자체에는 아무런 권한이 없습니다. 여러분의 말을 CLI 호출로 변환해줄 뿐이며, 호출은 여러분 권한으로 실행됩니다. +스킬 자체는 고유한 권한이 없습니다. 여러분의 말을 CLI 호출로 변환하여 여러분의 권한으로 실행할 뿐입니다: ```mermaid flowchart TD @@ -34,47 +34,47 @@ flowchart TD ### 대시보드 내 AI 어시스턴트와의 차이: 중요한 구분 -이 둘은 영향 범위가 매우 다른 별개의 도구입니다. +이 두 도구는 영향 범위가 매우 다릅니다: -- **대시보드 내 AI 어시스턴트** ([AI 어시스턴트](/ko/agenteye/assistant))는 에이전트 서비스를 기반으로 대시보드에 내장된 채팅입니다. **읽기 전용 + 승인 게이트 방식의 저작**: 저장된 쿼리와 대시보드를 초안으로 작성할 수 있지만, 모든 쓰기 작업은 사용자의 명시적 클릭 승인이 필요하며 절대 삭제하지 않습니다. `agent:use` 권한으로 게이트되어 있으며, 현재 보고 있는 조직의 데이터만 접근할 수 있습니다. -- **CLI 스킬**은 *여러분의* 워크스테이션에서 *여러분의* 코딩 에이전트 안에서 실행되며, `agenteye` CLI를 **여러분** 권한으로 구동합니다. API 키 생성/교체/비활성화, 조직 설정 변경, 인시던트 해결, 저장된 쿼리 삭제 등 **뮤테이션을 포함한 CLI의 전체 기능**을 수행할 수 있으며, CLI 로그인의 권한 범위 내에서만 제한됩니다. 해당 명령어를 직접 입력하는 것과 동일한 수준의 주의를 기울여 다루세요. +- **대시보드 내 AI 어시스턴트** ([AI 어시스턴트](/ko/agenteye/assistant))는 에이전트 서비스가 지원하는 대시보드 내 채팅입니다. **읽기 전용 + 승인이 필요한 작성**이 가능합니다. 저장된 쿼리와 대시보드를 초안으로 작성할 수 있지만, 모든 쓰기 작업은 명시적인 클릭 승인을 기다리며 절대 삭제하지 않습니다. `agent:use` 권한으로 게이팅되며, 현재 보고 있는 조직의 데이터만 볼 수 있습니다. +- **CLI 스킬**은 *여러분의* 워크스테이션에서 *여러분의* 코딩 에이전트 내에 실행되며, `agenteye` CLI를 **여러분의 권한**으로 구동합니다. CLI의 **전체 기능(뮤테이션 포함)**: API 키 생성/교체/비활성화, 조직 설정 변경, 인시던트 해결, 저장된 쿼리 삭제 등을 수행할 수 있으며, CLI 로그인 권한에 의해서만 제한됩니다. 이 명령어들을 직접 입력하는 것과 동일한 수준의 주의를 기울여 사용하세요. --- -## 사전 요구사항 +## 사전 요구 사항 -1. **`agenteye` CLI 설치** 및 `PATH` 등록 ([CLI](/ko/agenteye/cli) 레퍼런스 참고: `pipx install agenteye`) -2. **대시보드 URL 설정** (`AGENTEYE_DASHBOARD_URL` 환경 변수 또는 에이전트가 `--base-url` 전달) -3. **로그인된 세션**: 먼저 직접 `agenteye login`을 실행하세요. 스킬은 이메일로 전송되는 일회용 코드 로그인을 대신 완료할 수 **없습니다**. 세션이 없거나 만료된 경우 (CLI 종료 코드 `4`) `agenteye login`을 실행하라고 안내합니다. +1. **`agenteye` CLI 설치** 및 `PATH` 등록 ([CLI](/ko/agenteye/cli) 레퍼런스 참조: `pipx install agenteye`). +2. **대시보드 URL** 설정 (`AGENTEYE_DASHBOARD_URL` 환경 변수 또는 에이전트가 `--base-url` 전달). +3. **로그인된 세션**: 먼저 직접 `agenteye login`을 실행하세요. 스킬은 이메일로 전송된 일회용 코드 로그인을 완료할 수 **없습니다**. 세션이 없거나 만료된 경우(CLI 종료 코드 `4`) `agenteye login`을 실행하라고 안내합니다. --- -## 다운로드 위치 +## 스킬 위치 -스킬은 Failproof AI의 공개 스킬 컬렉션에 게시되어 있습니다. +스킬은 Failproof AI의 공개 스킬 컬렉션에 게시되어 있습니다: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -접근에 아무런 제한이 없습니다. 저장소는 공개되어 있고, 스킬은 자체 자격 증명이 필요 없습니다. *여러분이* 로그인한 세션을 사용해 **공개** `agenteye` CLI를 *여러분의* 대시보드에 연결할 뿐이기 때문입니다. 별도로 요청할 필요가 없습니다. +게이팅된 것이 없습니다. 저장소는 공개되어 있고 스킬 자체의 자격 증명이 필요 없습니다. 스킬은 *여러분이* 로그인한 세션을 사용하여 **공개** `agenteye` CLI를 *여러분의* 대시보드에 구동할 뿐입니다. 별도로 요청할 필요가 없습니다. -스킬은 별도 폴더로 제공되며, `pipx install agenteye` 패키지 **내부에 포함되어 있지 않으므로** 거기서 찾지 마세요. +스킬은 독립된 폴더로 제공되며 `pipx install agenteye` 패키지 **내부에는 포함되지 않으니** 거기서 찾지 마세요. ## 스킬 설치 -가장 빠른 방법은 [`skills`](https://skills.sh) CLI를 사용하는 것입니다. 폴더를 가져와서 에이전트가 찾는 위치에 저장해줍니다. +가장 빠른 방법은 [`skills`](https://skills.sh) CLI를 사용하는 것입니다. 폴더를 가져와 에이전트가 찾는 위치에 놓아줍니다: ```bash -# Claude Code, 현재 프로젝트에만 적용 +# Claude Code, 이 프로젝트만 npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -# 모든 프로젝트에 적용 (~/.claude/skills/에 설치) +# 모든 프로젝트 (~/.claude/skills/에 설치) npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy # Codex 사용 시 npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -이후 다른 스킬과 동일하게 관리할 수 있습니다. +다른 스킬과 동일하게 관리할 수 있습니다: ```bash npx skills list -a claude-code # 설치된 스킬 목록 @@ -82,20 +82,20 @@ npx skills update agenteye-cli # 최신 버전으로 업데이트 npx skills remove agenteye-cli # 제거 ``` -직접 설치하고 싶으신가요? 에이전트 스킬은 `SKILL.md`(와 선택적 레퍼런스 파일)가 들어 있는 폴더일 뿐이므로, 복사해서 사용해도 됩니다. +직접 설치하는 것을 선호하시나요? Agent Skill은 `SKILL.md`(및 선택적 참조 파일)를 포함하는 폴더일 뿐이므로 복사해도 됩니다: -- **Claude Code**: `agenteye-cli/` 폴더를 `~/.claude/skills/`(모든 프로젝트) 또는 `/.claude/skills/`(해당 저장소만)에 넣으세요. Claude Code가 자동으로 감지합니다. `/skills` 목록으로 확인하거나, 설명과 일치하는 질문을 직접 해보세요. -- **Codex (OpenAI)**: Codex도 동일한 `SKILL.md`를 읽습니다. 번들로 제공되는 `agents/openai.yaml`에 `allow_implicit_invocation: true`가 설정되어 있어 작업이 일치하면 Codex가 자동으로 스킬을 선택합니다. 명시적으로 호출하려면 `$agenteye-cli`를 사용하세요. +- **Claude Code**: `agenteye-cli/` 폴더를 `~/.claude/skills/`(모든 프로젝트) 또는 `/.claude/skills/`(해당 저장소만)에 넣으세요. Claude Code가 자동으로 감지합니다. `/skills` 목록으로 확인하거나, 해당 설명과 일치하는 질문을 해보세요. +- **Codex (OpenAI)**: Codex도 동일한 `SKILL.md`를 읽습니다. 번들로 제공되는 `agents/openai.yaml`에 `allow_implicit_invocation: true`가 설정되어 있어, 작업이 일치하면 Codex가 자동으로 스킬을 선택합니다. 그렇지 않으면 `$agenteye-cli`로 명시적으로 호출하세요. --- -## 안전 주의사항: 에이전트가 CLI를 실행할 때 뮤테이션은 확인 프롬프트가 나타나지 않습니다 +## 안전: 에이전트가 CLI를 실행할 때 뮤테이션은 확인을 요청하지 않습니다 -> **경고:** 에이전트가 변경 작업을 수행하도록 허용하기 전에 반드시 읽으세요. +> **경고:** 에이전트가 변경 작업을 수행하기 전에 반드시 읽으세요. -`agenteye` CLI는 일반적으로 파괴적 작업 전에 *"정말 하시겠습니까?"* 라고 물어봅니다. 그러나 **터미널에 연결되어 있지 않을 때(코딩 에이전트가 실행하는 방식이 정확히 이 경우입니다)는 해당 확인을 자동으로 건너뛰며, `--json`도 마찬가지로 건너뜁니다.** 따라서 에이전트에게는 안전 프롬프트가 **표시되지 않습니다**. +`agenteye` CLI는 일반적으로 파괴적인 작업 전에 *"정말 하시겠습니까?"*라고 묻습니다. 하지만 **터미널에 연결되지 않은 경우(코딩 에이전트가 실행하는 방식이 바로 이것입니다) 자동으로 확인을 건너뛰며, `--json`도 마찬가지입니다.** 따라서 에이전트에게는 안전 확인 메시지가 **표시되지 않습니다**. -스킬은 이를 보완하도록 작성되어 있습니다. 실행할 정확한 명령어를 명시하고, 상태를 변경하기 전에 반드시 명시적으로 **OK를 받도록** 지시받았습니다. 이 규칙을 지켜주세요. 에이전트를 통해 Failproof AI Observability를 조작할 때는, *여러분이* 확인 단계입니다. 주의해야 할 상태 변경 명령어들: +스킬은 이를 보완하도록 작성되어 있습니다. 실행할 정확한 명령어를 명시하고, 상태 변경 전에 명시적인 **승인을 받도록** 지침이 되어 있습니다. 이 규칙을 지키세요. 에이전트를 통해 Failproof AI Observability를 구동할 때 *여러분이* 확인 단계입니다. 주의해야 할 상태 변경 명령어: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` @@ -108,13 +108,13 @@ npx skills remove agenteye-cli # 제거 **Observe** 하위의 모든 것(`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`)은 읽기 전용이며 아무것도 변경하지 않습니다. -에이전트는 **여러분** 권한으로 동작하므로, 여러분의 로그인이 허용된 작업만 수행할 수 있습니다. 권한은 **조직별로** 확인됩니다 ([API 키](/ko/agenteye/api-keys) 참고). 권한이 없는 명령어는 정확한 권한 이름과 함께 종료 코드 `5`를 반환하므로, 에이전트가 불명확하게 실패하는 대신 어드민에게 무엇을 요청해야 하는지 정확히 알려줄 수 있습니다. +에이전트는 **여러분의 권한**으로 동작하므로, 여러분의 로그인이 허용하는 작업만 수행할 수 있습니다. 권한은 **조직별**로 해결됩니다([API 키](/ko/agenteye/api-keys) 참조). 권한이 없는 명령어는 정확한 권한 이름과 함께 종료 코드 `5`를 반환하므로, 에이전트가 불명확하게 실패하는 대신 관리자에게 무엇을 요청해야 하는지 정확히 알려줄 수 있습니다. --- -## 요청 예시 +## 물어볼 수 있는 것들 -실제 대화 흐름의 예시입니다. 읽기 작업과 확인을 기다리는 변경 작업이 포함되어 있습니다. +실제 대화 흐름의 예시입니다. 읽기 작업 후 승인을 기다리는 변경 작업: ```text you ▸ Is anything broken in the last day? @@ -136,24 +136,24 @@ agent ▸ Done. Key "ci" created with events:add only. The secret is shown only once, so store it now. I can't reprint it. ``` -스킬은 자연어 의도를 적절한 `agenteye` 명령어로 매핑하고, 추측하지 않기 위해 먼저 유효한 값을 조회(`list `, `whoami`)한 뒤, 변경 전에 정확한 명령어를 명시합니다. 더 많은 예시: +스킬은 각 자연어 의도를 올바른 `agenteye` 명령어로 매핑합니다. 먼저 유효한 값을 탐색하고(`list `, `whoami`), 추측하지 않으며, 변경 전에 정확한 명령어를 명시합니다. 더 많은 예시: -- *"최근 24시간 동안 고장났거나 실패한 게 있나요?"* → `errors --since 24h --aggregate` 후 세부 분석 -- *"세션 `run-001`이 왜 실패했나요?"* → `events --session-id run-001 --all` + `evals --session-id run-001` -- *"이번 주 품질 트렌드는 어떤가요?"* → `evals --aggregate --since 7d` 후 낮은 점수의 실행 드릴다운 -- *"CI에 이벤트만 푸시할 수 있는 키를 만들어줘."* → `keys create ci --add events:add` (명령어를 명시한 뒤 생성하고 일회성 시크릿 캡처) -- *"누가 접근 권한이 있나요? Dana를 읽기 전용으로 변경해줘."* → `users list` → 여러분에게 확인 후 `users update dana@… --permission-set read-only` -- *"발생 중인 인시던트를 ack하고 나한테 할당해줘."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…` +- *"지난 24시간 동안 문제가 있거나 실패한 것이 있나요?"* → `errors --since 24h --aggregate`, 이후 세부 분석. +- *"세션 `run-001`은 왜 실패했나요?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. +- *"이번 주 품질 추세는 어떻게 되나요?"* → `evals --aggregate --since 7d`, 이후 낮은 점수의 실행 드릴다운. +- *"CI에 이벤트만 푸시할 수 있는 키를 주세요."* → `keys create ci --add events:add` (명령어를 명시한 후 생성하고 일회성 시크릿 캡처). +- *"누가 접근 권한을 가지고 있나요? Dana를 읽기 전용으로 변경해 주세요."* → `users list` → `users update dana@… --permission-set read-only` (여러분의 확인 후). +- *"발생 중인 인시던트를 확인하고 나에게 할당해 주세요."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. -이 작업들 뒤에 있는 정확한 명령어, 플래그, JSON 형태는 [CLI](/ko/agenteye/cli) 레퍼런스와 [에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes)를 참고하세요. +이 작업들의 정확한 명령어, 플래그, JSON 형식은 [CLI](/ko/agenteye/cli) 레퍼런스와 [에이전트용 CLI 레시피](/ko/agenteye/cli-recipes)를 참조하세요. --- ## 다음 단계 -- **[CLI](/ko/agenteye/cli)**: `agenteye`의 전체 명령어 및 플래그 레퍼런스 -- **[에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes)**: `jq` 패턴 복붙 모음 및 종료 코드 처리 -- **[Evaluator 에이전트 스킬](/ko/agenteye/evaluator-skill)**: `agenteye evals`가 읽는 점수를 생성하는 evaluator를 구축하는 형제 스킬 -- **[Python SDK 에이전트 스킬](/ko/agenteye/python-sdk-skill)**: `agenteye`가 읽는 텔레메트리를 에이전트가 내보내도록 계측하는 형제 스킬 -- **[AI 어시스턴트](/ko/agenteye/assistant)**: 대시보드 내 어시스턴트 (이 터미널 스킬과 혼동하지 마세요) -- **[API 키](/ko/agenteye/api-keys)**: 스킬이 수행할 수 있는 작업 범위를 결정하는 조직별 권한 모델 \ No newline at end of file +- **[CLI](/ko/agenteye/cli)**: `agenteye`의 전체 커맨드 및 플래그 레퍼런스. +- **[에이전트용 CLI 레시피](/ko/agenteye/cli-recipes)**: 복사-붙여넣기 `jq` 패턴 및 종료 코드 처리. +- **[Evaluator agent 스킬](/ko/agenteye/evaluator-skill)**: `agenteye evals`가 읽는 점수를 생성하는 evaluator를 구축하기 위한 형제 스킬. +- **[Python SDK agent 스킬](/ko/agenteye/python-sdk-skill)**: 에이전트가 `agenteye`가 읽는 텔레메트리를 내보내도록 계측하는 형제 스킬. +- **[AI 어시스턴트](/ko/agenteye/assistant)**: 대시보드 내 어시스턴트 (이 터미널 스킬과 혼동하지 마세요). +- **[API 키](/ko/agenteye/api-keys)**: 스킬이 수행할 수 있는 작업의 범위를 결정하는 조직별 권한 모델. \ No newline at end of file diff --git a/docs/ko/agenteye/cli.mdx b/docs/ko/agenteye/cli.mdx index 89d06d2c..f3143ae8 100644 --- a/docs/ko/agenteye/cli.mdx +++ b/docs/ko/agenteye/cli.mdx @@ -1,34 +1,34 @@ --- title: "CLI" -description: "터미널이나 스크립트에서 Failproof AI Observability를 완전히 제어하세요: 대시보드를 오갈 필요가 없습니다." +description: "터미널이나 스크립트에서 Failproof AI Observability를 완전히 제어하세요: 대시보드를 왔다 갔다 할 필요가 없습니다." --- -터미널이나 스크립트에서 Failproof AI Observability를 완전히 제어하세요: 대시보드를 오갈 필요가 없습니다. `agenteye` CLI는 데이터(세션, 이벤트 로그, 평가)를 조회하고 조직(API 키, 사용자, 설정, 알림, 인시던트, 저장된 쿼리)을 관리합니다. 자동화된 검사를 실행하거나, Observability를 CI에 연동하거나, 코딩 에이전트가 프로덕션을 점검하도록 할 때 활용하세요. 모든 커맨드는 `--json` 플래그를 지원하므로, 터미널에서 직접 사용하거나 코딩 에이전트(Claude Code, Cursor)가 셸을 호출해 결과를 파싱할 때 모두 동일하게 작동합니다. +터미널이나 스크립트에서 Failproof AI Observability를 완전히 제어하세요: 대시보드를 왔다 갔다 할 필요가 없습니다. `agenteye` CLI는 데이터(세션, 이벤트 로그, 평가)를 조회하고 조직(API 키, 사용자, 설정, 알림, 인시던트, 저장된 쿼리)을 관리합니다. 자동화된 점검을 실행하거나, Observability를 CI에 연동하거나, 코딩 에이전트가 프로덕션을 검사하게 하고 싶을 때 활용하세요. 모든 명령어는 `--json` 플래그를 지원하므로, 프롬프트에서 직접 사용하거나 코딩 에이전트(Claude Code, Cursor)가 쉘 아웃하여 결과를 파싱할 때도 동일하게 동작합니다. -하나의 바이너리로 다음을 수행할 수 있습니다: +하나의 바이너리로 다음 모든 작업이 가능합니다: -- **데이터 조회**: `sessions`, `events`, `evals`, `errors` (시간, 에이전트, 환경, 점수로 필터링). +- **데이터 읽기**: `sessions`, `events`, `evals`, `errors` (시간, 에이전트, 환경, 점수로 필터링). - **조직 관리**: `keys`, `users`, `settings`, `alerts`, `incidents`. -- **분석 실행**: 저장된 SQL 및 임시 쿼리 실행기 (`query`). -- **AI 어시스턴트 질의**: 대시보드에서 사용하는 것과 동일한 읽기 전용 분석 도구 (`agent`). +- **분석 실행**: 저장된 SQL 및 임시 쿼리 실행기(`query`). +- **AI 어시스턴트에게 질문**: 대시보드에서 채팅할 수 있는 것과 동일한 읽기 전용 분석가(`agent`). -> **참고:** 이것은 `agenteye` CLI로, 컬렉터 데몬(`agenteye-collector`)과는 별개의 도구입니다. CLI는 대시보드와 통신하고, 컬렉터는 이벤트를 서버로 전송합니다. +> **참고:** 이것은 `agenteye` CLI로, 컬렉터 데몬(`agenteye-collector`)과는 다른 도구입니다. CLI는 대시보드와 통신하고, 컬렉터는 이벤트를 서버로 전송합니다. --- ## 빠른 시작 -처음부터 첫 번째 결과까지 네 줄이면 충분합니다. CLI가 대시보드를 가리키도록 설정하고, 로그인하고, 본인 확인 후, 최근 하루치 실행 기록을 가져옵니다: +아무것도 없는 상태에서 첫 번째 결과까지 네 줄이면 됩니다. CLI가 대시보드를 가리키도록 설정하고, 로그인하고, 본인 확인 후 지난 하루의 실행 기록을 가져옵니다: ```bash pipx install agenteye agenteye --base-url https://agenteye.example.com login --email you@example.com # 이메일로 6자리 코드 발송 -agenteye whoami # 현재 사용자 + 활성 조직 확인 -agenteye --json sessions --since 24h # 에이전트 실행 기록, 최근 24시간 +agenteye whoami # 사용자 + 활성 조직 확인 +agenteye --json sessions --since 24h # 에이전트 실행 1건당 1행, 최근 24시간 ``` -마지막 커맨드는 가장 최근 세션의 JSON 객체를 출력합니다(최신순, 기본값 최대 50개). `jq`로 파이프해서 원하는 데이터를 추출하거나, `--json`을 생략하면 박스 형태의 컬러 테이블로 볼 수 있습니다. 각 행에는 실행 상태와, 평가자가 점수를 매겼다면 해당 메트릭 점수가 포함됩니다(여기서는 일부 생략): +마지막 명령어는 가장 최근 세션의 JSON 객체를 출력합니다(최신순, 기본 최대 50개). `jq`로 파이프하여 원하는 대로 가공하거나, `--json`을 빼면 박스 형태의 컬러 테이블로 볼 수 있습니다. 각 행에는 실행 상태와, 평가자가 점수를 매겼다면 메트릭 점수가 포함됩니다(여기서는 축약됨): ```json { @@ -48,13 +48,13 @@ agenteye --json sessions --since 24h } ``` -이 페이지의 나머지 부분에서 각 구성 요소를 설명합니다: [설치](#installation), [로그인](#authentication), [설정](#configuration), 모든 커맨드에 공통으로 적용되는 [전역 규칙](#global-options--conventions), 그리고 [전체 커맨드 참조](#command-reference). +이 페이지의 나머지 부분에서는 각 항목을 설명합니다: 격리 환경에서의 [설치](#installation), [로그인](#authentication), [설정](#configuration), 모든 명령어에 공통으로 적용되는 [전역 규칙](#global-options--conventions), 그리고 [전체 명령어 참조](#command-reference). --- ## 설치 -CLI는 **`agenteye`**라는 이름의 공개 PyPI 패키지입니다. 의존성이 충돌하지 않도록 격리된 환경에 설치하세요: +CLI는 **`agenteye`**라는 이름의 공개 PyPI 패키지입니다. 항상 자체 의존성을 갖도록 격리된 환경에 설치하세요: ```bash pipx install agenteye @@ -62,51 +62,51 @@ pipx install agenteye uv tool install agenteye ``` -Python 3.10 이상이 필요합니다. 설치 후 커맨드는 **`agenteye`**입니다: +Python 3.10 이상이 필요합니다. 설치 후 실행 명령어는 **`agenteye`**입니다: ```bash agenteye --version agenteye --help ``` -> **참고:** Failproof AI Observability Python SDK도 `agenteye` 배포 이름을 사용합니다. `pipx` 또는 `uv tool`로 CLI를 설치하면(공유 가상 환경에 `pip install`하는 것과 달리) 두 패키지가 충돌하지 않습니다. 동일한 환경에 SDK가 설치되어 있지 않다면 `pip install agenteye`도 괜찮습니다. +> **참고:** Failproof AI Observability Python SDK도 `agenteye` 배포 이름을 사용합니다. `pipx` 또는 `uv tool`로 CLI를 설치하면(공유 가상 환경에 `pip install`하는 대신) 두 패키지가 충돌하지 않습니다. `pip install agenteye`는 SDK가 동일 환경에 설치되어 있지 않은 경우에만 사용하세요. --- ## 인증 -CLI는 이메일로 전송되는 일회용 코드를 사용해 **대시보드**에 인증합니다: +CLI는 이메일로 전송되는 일회용 코드로 **대시보드**에 인증합니다: ```bash agenteye login --email you@example.com -# 이메일로 6자리 코드가 전송됩니다; 프롬프트에 붙여 넣으세요. +# 6자리 코드가 이메일로 발송됩니다; 프롬프트에 붙여넣으세요. ``` -세션 토큰은 `~/.agenteye/cli.json`에 저장됩니다(본인만 읽을 수 있도록 `0600` 권한). 기본적으로 24시간 동안 유효하며, 만료되면 `agenteye login`을 다시 실행하세요. +세션 토큰은 `~/.agenteye/cli.json`에 저장됩니다(본인만 읽을 수 있도록 모드 `0600`으로 설정). 기본적으로 24시간 동안 유효하며, 만료되면 `agenteye login`을 다시 실행하세요. ```bash agenteye whoami # 현재 사용자, 활성 조직, 권한 표시 -agenteye logout # 세션을 취소하고 저장된 토큰 삭제 +agenteye logout # 세션 폐기 및 저장된 토큰 삭제 ``` -`whoami`는 세션이 없거나 만료된 경우에도 오류를 발생시키지 않으며, 대신 `logged_in: false`를 반환합니다. 스크립트나 에이전트가 인증 상태를 안전하게 확인할 수 있습니다(다만 base URL이 설정되지 않았거나 대시보드에 접근할 수 없으면 여전히 비정상 종료될 수 있습니다). +`whoami`는 세션이 없거나 만료되어도 오류를 발생시키지 않고 `logged_in: false`를 반환합니다. 스크립트나 에이전트가 안전하게 인증 상태를 확인할 수 있습니다(단, base URL이 설정되지 않았거나 대시보드에 접근할 수 없으면 비정상 종료될 수 있습니다). -**요구 사항:** 이메일이 대시보드 로그인 허용 목록에 있어야 하며(Failproof AI Observability 관리자에게 문의), 대시보드가 base URL에서 접근 가능해야 합니다([설정](#configuration) 참조). 코드를 요청했는데 도착하지 않는다면 이메일이 아직 대시보드 접근 권한이 없는 것일 수 있습니다. +**요구 사항:** 이메일이 대시보드 로그인에 허용되어 있어야 하고(Failproof AI Observability 관리자에게 문의), 대시보드가 base URL에서 접근 가능해야 합니다([설정](#configuration) 참조). 코드를 요청했는데 도착하지 않는다면 해당 이메일이 대시보드 접근 권한을 아직 부여받지 못한 것입니다. --- ## 조직 선택 (멀티 테넌트) -계정이 여러 조직에 속해 있다면 **로그인 시** 활성 조직을 선택하세요; 선택한 조직은 저장되어 이후 모든 커맨드에 사용됩니다: +계정이 둘 이상의 조직에 속해 있다면, **로그인 시** 활성 조직을 선택하세요. 이후 모든 명령어에 저장된 값이 사용됩니다: ```bash agenteye login --org acme # 인증과 활성 테넌트 설정을 한 번에 agenteye orgs list # 접근 가능한 조직 목록 (활성 조직 표시됨) agenteye orgs switch globex # 저장된 기본 조직 변경 -agenteye --org globex sessions # 단일 커맨드에서 조직 재정의 +agenteye --org globex sessions # 단일 명령어에서만 재정의 ``` -정확히 하나의 조직에만 속해 있다면 자동으로 선택되므로 `--org`를 무시해도 됩니다. 여러 조직에 속해 있는데 선택하지 않으면, CLI가 조직 목록을 보여주고 `--org `를 붙여 다시 실행하도록 요청합니다. 활성 조직은 모든 요청에 포함되며, 권한은 **조직별로** 확인됩니다; `agenteye whoami`는 활성 조직, 해당 조직에서의 권한, 모든 멤버십을 표시합니다. +조직이 하나뿐이면 자동으로 선택되며 `--org`를 신경 쓸 필요가 없습니다. 여러 조직에 속해 있는데 선택하지 않으면 CLI가 목록을 보여주고 `--org `와 함께 다시 실행하도록 안내합니다. 활성 조직은 모든 요청에 대시보드로 전달되며, 권한은 **조직별로** 적용됩니다. `agenteye whoami`는 활성 조직, 해당 조직에서의 권한, 모든 멤버십을 표시합니다. --- @@ -116,107 +116,107 @@ agenteye --org globex sessions # 단일 커맨드에서 조직 재정의 |---|---|---|---| | 대시보드 base URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **필수** (기본값 없음) | | 활성 조직/테넌트 | `--org` | `AGENTEYE_ORG` | 로그인 시 선택; `~/.agenteye/cli.json`에 저장 | -| 세션 토큰 | `--token` | `AGENTEYE_CLI_TOKEN` | `~/.agenteye/cli.json`에서 로드 | +| 세션 토큰 | `--token` | `AGENTEYE_CLI_TOKEN` | `~/.agenteye/cli.json`에서 읽음 | | JSON 출력 | `--json` | `AGENTEYE_CLI_JSON` | 꺼짐 | | TLS 검증 건너뛰기 | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | 꺼짐 (로그인 시 저장) | | 요청 타임아웃 (초) | `--timeout` | _(없음)_ | 30 | -| 사용량 텔레메트리 비활성화 | _(없음)_ | `AGENTEYE_ANALYTICS_DISABLED` (또는 `DO_NOT_TRACK`) | 텔레메트리는 현재 비활성화; 아무것도 전송되지 않음 | +| 사용 텔레메트리 비활성화 | _(없음)_ | `AGENTEYE_ANALYTICS_DISABLED` (또는 `DO_NOT_TRACK`) | 텔레메트리 현재 비활성화; 아무것도 전송되지 않음 | -우선순위는 **플래그 → 환경 변수 → 설정 파일** 순입니다. 기본값이 없으므로 CLI가 대시보드를 가리키도록 설정해야 합니다. 커맨드마다 지정하거나(`--base-url https://agenteye.example.com`), 환경 변수로 한 번만 설정하면 됩니다(첫 `login` 후에도 저장됩니다): +적용 순서는 **플래그 → 환경 변수 → 설정 파일**입니다. 기본값이 없으므로 CLI가 대시보드를 가리키도록 설정해야 합니다. 명령어마다 지정하거나(`--base-url https://agenteye.example.com`) 환경 변수로 한 번만 설정하세요(첫 `login` 이후 자동으로 저장되기도 합니다): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -설정 디렉터리는 `AGENTEYE_HOME` 환경 변수를 따릅니다(SDK 및 컬렉터와 동일한 규칙). 설정된 경우 `cli.json`은 `$AGENTEYE_HOME/cli.json`에 위치합니다. +설정 디렉터리는 `AGENTEYE_HOME`을 따릅니다(SDK 및 컬렉터에서 사용하는 것과 동일한 규칙). 설정된 경우 `cli.json`은 `$AGENTEYE_HOME/cli.json`에 위치합니다. ### 자체 서명 또는 내부 TLS -대시보드가 자체 서명 또는 내부 인증서로 HTTPS를 제공하는 경우(예: 원시 로드 밸런서 호스트명), TLS 검증이 `CERTIFICATE_VERIFY_FAILED` 오류로 실패합니다. `--insecure`를 전달해 인증서 검증을 건너뛰세요: +대시보드가 자체 서명 인증서나 내부 인증서로 HTTPS를 제공하는 경우(예: 로드 밸런서 호스트명 직접 사용), TLS 검증이 `CERTIFICATE_VERIFY_FAILED` 오류로 거부됩니다. `--insecure`를 전달하여 인증서 검증을 건너뛰세요: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure`는 **로그인 시 `cli.json`에 저장**되므로 이후 커맨드는 자동으로 검증을 건너뜁니다; 매번 플래그를 반복할 필요가 없습니다. 일회성 검증 호출에는 `--secure`를 전달하거나, 다음 로그인 시 검증을 다시 활성화할 수도 있습니다. 검증이 비활성화된 상태에서 대시보드에 접촉하는 모든 커맨드 전에 CLI가 stderr에 경고를 출력합니다. 검증을 건너뛰면 중간자 공격에 대한 보호가 제거됩니다; 이를 사용하기 전에 대시보드까지의 네트워크 경로(VPN, 프라이빗 서브넷 등)를 신뢰할 수 있는지 확인하세요. +`--insecure`는 **로그인 시 `cli.json`에 저장**되므로, 이후 명령어는 자동으로 검증을 건너뜁니다. 플래그를 반복할 필요가 없습니다. 검증이 비활성화된 상태에서 대시보드에 접속하는 명령어를 실행하면 CLI가 stderr에 경고를 출력합니다. 일회성 검증 호출을 원하거나 다음 로그인 시 검증을 다시 활성화하려면 `--secure`를 사용하세요. 검증을 건너뛰면 중간자 공격에 대한 보호가 제거됩니다. 이 설정을 사용하기 전에 대시보드까지의 네트워크 경로(VPN, 프라이빗 서브넷 등)를 신뢰할 수 있는지 확인하세요. --- ## 텔레메트리 및 개인정보 -> **참고:** 현재 배포된 CLI는 **사용량 텔레메트리를 전혀 전송하지 않습니다.** 마스터 킬 스위치가 활성화되어 있어 환경에 관계없이 아무것도 전송되지 않습니다. 아래 섹션은 텔레메트리가 향후 활성화될 경우를 대비한 옵트아웃 방법을 설명합니다. +> **참고:** 현재 배포된 CLI는 **사용 텔레메트리를 전혀 전송하지 않습니다.** 마스터 킬 스위치가 켜져 있어, 환경과 무관하게 아무것도 전송되지 않습니다. 아래 내용은 텔레메트리가 언젠가 활성화될 경우를 대비한 옵트아웃 기능 설명입니다. -활성화되더라도 텔레메트리는 **익명 사용량 분석만** 수집하며, 에이전트·세션·이벤트 데이터는 절대 포함되지 않습니다: +활성화되더라도 텔레메트리는 **익명 사용 분석 데이터에 한정**되며, 에이전트·세션·이벤트 데이터는 절대 포함되지 않습니다: -- **에이전트, 세션, 이벤트 데이터는 절대 인프라 외부로 나가지 않습니다.** CLI 사용 정보만 보고됩니다: 커맨드와 서브커맨드 이름(예: `keys create`), 사용한 플래그의 **이름**(값은 포함하지 않음), 성공/종료 상태, 실행 시간, 그리고 변경 작업에 대한 이벤트(예: `api_key_created`, `query_run`)로 정적 이름/열거형과 개략적인 카운트만 포함됩니다. 대시보드 URL, 세션 토큰, 이메일, 조직 슬러그, 리소스 ID, SQL, 키 시크릿, 쿼리 필터는 **절대 전송되지 않습니다.** 운영자는 불투명한 내부 ID로만 식별되며 이메일로는 식별되지 않습니다. -- **미리 옵트아웃**하려면 CLI 환경에서 `AGENTEYE_ANALYTICS_DISABLED=1`을 설정하세요(CLI는 범용 `DO_NOT_TRACK=1` 규칙도 지원합니다). 텔레메트리가 활성화되는 순간부터 적용되므로, 개인정보를 중시하는 환경에서 영구적으로 옵트아웃 상태를 유지할 수 있습니다. -- 텔레메트리가 활성화된다면 CLI는 PostHog(`https://us.i.posthog.com`)로 직접 전송할 것입니다; 해당 호스트가 차단된 환경에서는 아무것도 전송되지 않으며 CLI 동작에는 영향을 주지 않습니다. +- **에이전트, 세션, 이벤트 데이터는 절대로 인프라 외부로 나가지 않습니다.** CLI 사용 정보만 보고됩니다: 명령어 및 서브커맨드 이름(예: `keys create`), 사용한 플래그의 **이름**(값은 제외), 성공/종료 상태, 소요 시간. 변경 작업에는 정적 이름/열거형과 대략적인 횟수만 담긴 이벤트(예: `api_key_created`, `query_run`)가 추가됩니다. 대시보드 URL, 세션 토큰, 이메일, 조직 슬러그, 리소스 ID, SQL, 키 시크릿, 쿼리 필터는 **절대 전송되지 않습니다.** 운영자는 이메일이 아닌 불투명한 내부 ID로만 식별됩니다. +- **`AGENTEYE_ANALYTICS_DISABLED=1`**을 CLI 환경에 설정하여 미리 옵트아웃하세요(크로스 툴 규칙인 `DO_NOT_TRACK=1`도 지원합니다). 텔레메트리가 활성화되는 순간 즉시 적용되므로, 프라이버시 중심 환경에서는 영구적으로 옵트아웃 상태를 유지할 수 있습니다. +- 텔레메트리가 활성화된다면 CLI는 PostHog(`https://us.i.posthog.com`)로 직접 전송합니다. 해당 호스트가 차단된 머신에서는 아무것도 전송되지 않으며 CLI는 정상 동작합니다. --- ## 전역 옵션 및 규칙 -한 번만 읽어두세요; 모든 커맨드에 적용됩니다. +한 번만 읽어두면 모든 명령어에 적용됩니다. -- **전역 옵션은 커맨드 앞에 위치해야 합니다.** `agenteye --json sessions`는 올바르지만, `agenteye sessions --json`은 사용 오류입니다. 전역 옵션은 `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`입니다. -- **`--json`은 순수 JSON만 stdout에 출력합니다.** 사람이 읽는 상태 메시지, 경고, 오류는 **stderr**로 출력되므로, `--json` stdout 캡처는 상태 메시지가 표시되더라도 `jq`로 파이프할 수 있을 만큼 깔끔합니다. `--json` 없이는 사람이 보기 좋은 박스 형태의 컬러 뷰로 표시됩니다. -- **`--help`으로 탐색하세요.** 모든 커맨드와 서브커맨드에는 `--help`(및 `-h` 별칭)가 있습니다: `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. 최상위 도움말에는 종료 코드와 전역 옵션도 나열됩니다. 전역 머신 가독 표면 덤프는 없으며, 커맨드별 `--help`와 두 레지스트리에 특화된 `agenteye query schema`, `agenteye settings schema`를 사용하세요. -- **스크립트와 에이전트에서는 확인 프롬프트가 자동으로 건너뜁니다.** 생성/수정/삭제 커맨드는 인터랙티브 터미널에서 "정말 하시겠습니까?" 프롬프트를 표시하지만, **`--json`이거나 stdin이 TTY가 아닐 때는 자동으로 건너뜁니다**(TTY는 인터랙티브 터미널 세션; 파이프나 CI 러너는 TTY가 아님). 명시적으로 건너뛰려면 `--yes`/`-y`를 전달하세요. 에이전트에게는 프롬프트가 표시되지 않으므로, 에이전트는 파괴적인 작업을 수행하기 전에 먼저 사람에게 확인해야 합니다. -- **페이지네이션:** 결과는 최신순으로 커서 페이지네이션됩니다(각 페이지는 다음 페이지를 가져올 때 사용하는 토큰을 반환). `--limit N`(별칭 `-n`)은 행 수를 제한하며 **기본값은 50**입니다; `--all`은 자동으로 페이지네이션(200행 단위)하지만 **`--limit`까지만** 처리하므로 `--all`만 사용하면 여전히 50개에서 멈춥니다. 전체를 가져오려면 큰 상한값을 명시적으로 지정하세요: `--all --limit 1000`. `--page-size N`은 요청당 청크 크기를 제어합니다(최대 200); `--cursor `는 이전 페이지의 `next_cursor`에서 재개합니다. -- **시간 필터:** `--since`는 상대적 구간을 받습니다: `15m`, `1h`, `6h`, `24h`, `7d`, 또는 `all`(대시보드 프리셋). 더 길거나 사용자 정의 범위(예: 최근 30일)에는 `--from`/`--to`를 사용하세요: `--since`를 재정의하는 명시적 ISO-8601 UTC 타임스탬프로 **`T`와 타임존이 포함**되어야 합니다(예: `2026-06-01T00:00:00Z`). 공백으로 구분되거나 타임존이 없는 값은 사용 오류입니다. -- **`--fields a,b,c`**(`events`, `sessions`, `evals`, `errors`에서)는 테이블과 `--json` 모두에서 출력을 해당 키로 제한합니다. 알 수 없는 이름은 유효한 목록과 함께 거부되므로, 필드 이름을 확인하는 간편한 방법이기도 합니다. -- **`--file payload.json`**(또는 stdin을 읽으려면 `--file -`)은 리소스가 복잡한 형태를 가질 때 전체 JSON 요청 본문을 제공합니다(`alerts create/update`, `settings set`, `users create/update`에서). 저장된 쿼리 SQL은 대신 `--sql @file.sql`을 사용합니다. -- **다중값 필터**는 쉼표로 구분되며 집합으로 매칭됩니다(한 필터 내에서는 합집합, 필터 간에는 AND): `--event-type tool_use,tool_result`. Click 옵션은 가변 인수가 아니므로 `--add a b`는 작동하지 않습니다. `--add a,b`를 사용하거나, 플래그를 반복하거나(`--add a --add b`), 따옴표로 묶으세요(`--add "a b"`). +- **전역 옵션은 명령어 앞에 위치합니다.** `agenteye --json sessions`가 올바르고, `agenteye sessions --json`은 사용 오류입니다. 전역 옵션은 `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`입니다. +- **`--json`은 순수한 JSON만 stdout으로 출력하고 다른 것은 출력하지 않습니다.** 상태 메시지, 경고, 오류는 **stderr**로 출력되므로, `--json` stdout 캡처는 상태 메시지가 표시되더라도 `jq`로 파이프하기에 항상 깨끗합니다. `--json` 없이 실행하면 사람이 읽기 좋은 박스형 컬러 뷰로 표시됩니다. +- **`--help`으로 탐색하세요.** 모든 명령어와 서브커맨드에는 `--help`(`-h` 별칭 포함)가 있습니다: `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. 최상위 도움말에는 종료 코드와 전역 옵션도 나열됩니다. 전체 머신 리더블 서피스 덤프는 없으므로, 명령어별 `--help`와 두 레지스트리에 대한 `agenteye query schema`, `agenteye settings schema`를 활용하세요. +- **스크립트와 에이전트에서는 확인 프롬프트가 자동으로 건너뜁니다.** 생성/수정/삭제 명령어는 인터랙티브 터미널에서 "정말로 실행하시겠습니까?" 프롬프트를 표시하지만, **`--json`이 사용되거나 stdin이 TTY가 아닐 때는 자동으로 건너뜁니다**(TTY는 인터랙티브 터미널 세션이며, 파이프나 CI 러너는 해당되지 않습니다). 스크립트와 에이전트는 절대 대기하지 않습니다. `--yes`/`-y`로 명시적으로 건너뛸 수도 있습니다. 에이전트에는 프롬프트가 표시되지 않으므로, 에이전트는 파괴적인 작업을 수행하기 전에 사람에게 먼저 확인해야 합니다. +- **페이지네이션:** 결과는 최신순으로 커서 기반 페이지네이션이 적용됩니다(각 페이지는 다음 페이지 조회에 사용할 토큰을 반환합니다). `--limit N`(`-n` 별칭)은 행 수를 제한하며 **기본값은 50**입니다. `--all`은 자동 페이지네이션(200행 단위)을 실행하지만 **`--limit`까지만** 가져오므로, `--all`만 사용해도 50개에서 멈춥니다. 전체를 가져오려면 `--all --limit 1000`처럼 높은 값을 명시하세요. `--page-size N`은 요청당 청크 크기를 제어합니다(최대 200). `--cursor `는 이전 페이지의 `next_cursor`에서 이어서 조회합니다. +- **시간 필터:** `--since`는 상대적 시간 범위를 받습니다: `15m`, `1h`, `6h`, `24h`, `7d`, 또는 `all`(대시보드의 프리셋). 더 길거나 사용자 정의 범위(예: 최근 30일)는 `--from`/`--to`를 사용하세요: **`T`와 타임존이 포함된** 명시적 ISO-8601 UTC 타임스탬프(예: `2026-06-01T00:00:00Z`)로 `--since`를 재정의합니다. 공백으로 구분되거나 타임존이 없는 값은 사용 오류입니다. +- **`--fields a,b,c`**(`events`, `sessions`, `evals`, `errors`에서 사용)는 출력을 해당 키로만 제한합니다. 테이블과 `--json` 모두 적용됩니다. 알 수 없는 이름은 유효한 목록과 함께 거부되므로, 필드 이름을 탐색하는 저렴한 방법이기도 합니다. +- **`--file payload.json`**(또는 stdin을 읽으려면 `--file -`)은 리소스가 복잡한 형태를 가질 때 전체 JSON 요청 본문을 제공합니다(`alerts create/update`, `settings set`, `users create/update`에서 사용). 저장된 쿼리 SQL은 대신 `--sql @file.sql`을 사용합니다. +- **다중값 필터**는 쉼표로 구분되어 집합으로 매칭됩니다(동일 필터 내에서는 합집합, 필터 간에는 AND): `--event-type tool_use,tool_result`. Click 옵션은 가변 인자가 아니므로 `--add a b`는 오류입니다. `--add a,b`, 플래그 반복(`--add a --add b`), 또는 인용(`--add "a b"`)을 사용하세요. --- -## 커맨드 참조 +## 명령어 참조 -### 가장 자주 사용하는 5가지 커맨드 +### 가장 자주 사용하는 5가지 명령어 -대부분의 일상 작업은 몇 가지 읽기 커맨드로 해결됩니다. 여기서 시작하고, 필요할 때 아래의 전체 목록을 참조하세요: +일상적인 작업 대부분은 소수의 읽기 명령어로 처리됩니다. 여기서 시작하고, 필요할 때 아래의 전체 항목을 참조하세요: -| 커맨드 | 기능 | 예시 | +| 명령어 | 설명 | 사용 예시 | |---|---|---| -| `sessions` | 에이전트 실행 기록 한 줄씩: 시간, 환경, 에이전트, 상태, 최신 점수. | `agenteye --json sessions --since 24h --status error` | -| `events` | 실행 내 단계별 원시 추적 데이터(페이로드는 `--full` 추가). | `agenteye --json events --session-id run-001 --all` | -| `evals` | 평가 결과와 점수; `--aggregate`로 집계. | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | 오류가 발생한 이벤트만; `--aggregate`로 유형별 카운트. | `agenteye --json errors --since 24h --aggregate` | -| `list` | 유효한 필터값 탐색(에이전트, 환경, 모델 등). | `agenteye list agents` | +| `sessions` | 에이전트 실행 1건당 1행: 시간, 환경, 에이전트, 상태, 최신 점수. | `agenteye --json sessions --since 24h --status error` | +| `events` | 실행 내부의 단계별 원시 추적 데이터 (`--full`로 페이로드 포함). | `agenteye --json events --session-id run-001 --all` | +| `evals` | 평가 결과 및 점수; `--aggregate`로 집계. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | 오류가 발생한 이벤트만; `--aggregate`로 유형별 횟수. | `agenteye --json errors --since 24h --aggregate` | +| `list` | 유효한 필터 값 탐색 (에이전트, 환경, 모델 등). | `agenteye list agents` | ### CLI가 할 수 있는 모든 것 -전체 목록입니다. CLI에는 **18개의 최상위 커맨드**가 있습니다. 모든 읽기 커맨드는 `--json`과 위의 전역 옵션을 지원합니다; 특정 커맨드의 전체 플래그 목록과 JSON 형태는 `agenteye -h`(또는 ` -h`)를 실행하세요. +전체 항목은 다음과 같습니다. CLI에는 **18개의 최상위 명령어**가 있습니다. 모든 읽기 명령어는 `--json`과 위의 전역 옵션을 지원합니다. 특정 명령어의 상세 플래그 목록과 JSON 형태는 `agenteye -h`(또는 ` -h`)를 실행하세요. ### 신원: `login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash agenteye login --email you@example.com [--org acme] # 이메일 일회용 코드; 세션 저장 -agenteye logout # 이 기기의 저장된 세션 삭제 +agenteye logout # 이 머신의 저장된 세션 삭제 agenteye whoami # 현재 사용자, 활성 조직, 권한 agenteye version # CLI 버전 출력 (--version과 동일) agenteye help # 최상위 도움말 (--help와 동일) ``` -`orgs`는 활성 테넌트를 확인하고 전환합니다: +`orgs`는 활성 테넌트를 검사하고 전환합니다: ```bash -agenteye orgs list # 내 조직 + 각 역할 (활성 조직 표시됨) -agenteye orgs switch acme # 저장된 활성 조직 변경 (슬러그 생략 시 TTY에서 목록 선택) -agenteye orgs current # 활성 조직의 정보 +agenteye orgs list # 조직 목록 + 각 조직에서의 역할 (활성 조직 표시) +agenteye orgs switch acme # 저장된 활성 조직 변경 (슬러그 생략 시 TTY에서 목록 표시) +agenteye orgs current # 활성 조직의 신원 카드 agenteye orgs perms # 활성 조직에서의 권한 (리소스별 그룹화) ``` ### 관찰 (읽기 전용): `events` · `sessions` · `evals` · `errors` · `list` -이 커맨드들은 확인이 필요하지 않습니다. 공통 필터: `--session-id`, `--agent-id`, `--env`(**`--environment`가 아님**), 시간 범위(`--since` / `--from` / `--to`). +이 명령어들은 확인 프롬프트가 필요하지 않습니다. 공통 필터: `--session-id`, `--agent-id`, `--env`(**`--environment`가 아님**), 시간 범위(`--since` / `--from` / `--to`). ```bash -# events (별칭: 단계별 원시 추적 데이터), 최신순 +# events (별칭: 단계별 원시 추적), 최신순 agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' -# sessions: 에이전트 실행 기록 한 줄씩 (시간/환경/에이전트/세션/상태; 점수 필터링 없음) +# sessions: 에이전트 실행 1건당 1행 (시간/환경/에이전트/세션/상태; 점수 필터링 없음) agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 @@ -224,57 +224,57 @@ agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 agenteye --json evals --aggregate --since 7d --env prod # 상태 분포 + 키별 점수 통계 -# errors: 오류 이벤트만; --aggregate로 카운트/세션/에이전트/마지막 발생 시간 확인 +# errors: 오류 이벤트; --aggregate로 횟수/세션/에이전트/마지막 발생 시간 agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 -# list: 필터링 전에 유효한 필터값 탐색 +# list: 필터링 전에 유효한 필터 값 탐색 agenteye list envs # 또한: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX`(`sessions`이 아닌 **`evals`**에서)는 반복 가능하며 AND로 결합됩니다; 각 경계는 선택사항입니다(`..0.5`는 ≤ 0.5, `0.9..`는 ≥ 0.9). 요청당 최대 20개의 점수 필터. `evals --scores-full`은 **사람이 보는 테이블 전용** 표시 플래그로, 처음 몇 개와 `+N` 카운트 대신 모든 점수 쌍을 보여줍니다. `--json`에서는 효과가 없으며, `--json`은 항상 완전한 점수 객체를 반환합니다. **하나의 세션을 처음부터 끝까지 읽으려면** 이벤트 추적과 평가를 결합하세요: +`--score KEY:MIN..MAX`(**`sessions`가 아닌 `evals`** 전용)는 반복 가능하며 AND로 결합됩니다. 각 경계는 선택 사항입니다(`..0.5`는 ≤ 0.5, `0.9..`는 ≥ 0.9). 요청당 최대 20개의 점수 필터. `evals --scores-full`은 **사람용 테이블에서만** 적용되는 표시 플래그로, 처음 몇 개와 `+N` 카운트 대신 모든 점수 쌍을 보여줍니다. `--json`에서는 효과가 없으며, 항상 완전한 점수 객체를 반환합니다. **하나의 세션 전체를 읽으려면** 이벤트 추적과 평가를 조합하세요: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -agenteye --json evals --session-id run-001 # 해당 세션의 점수 + 상태 +agenteye --json evals --session-id run-001 # 점수 + 상태 ``` ### 관리 (권한 필요): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: API 키. 시크릿은 로컬에서 생성되어 서버로 전송되고(서버는 해시만 저장), 생성/재생성 시 **한 번만 표시**됩니다; 그 자리에서 저장하세요. `--json` 사용 시 `key` 필드에만 나타납니다. **이름**으로 참조됩니다. +**`keys`**: API 키. 시크릿은 로컬에서 생성되어 서버로 전송되며(서버는 해시만 저장), **생성/재생성 시 딱 한 번** 표시됩니다. 그때 반드시 캡처하세요. `--json`에서는 `key` 필드에만 표시됩니다. **이름**으로 참조합니다. ```bash -agenteye keys list # 활성 키 먼저, 그 다음 취소된 키 +agenteye keys list # 활성 키 먼저, 그 다음 폐기된 키 agenteye keys show ci-bot -agenteye keys create ci-bot --add events:read.add # 필요한 범위만 지정; 시크릿은 한 번만 출력 -agenteye keys create ops --permission-set standard --remove queries:run # 프리셋으로 시작 후 조정 +agenteye keys create ci-bot --add events:read.add # 필요한 범위만 부여; 시크릿 1회 출력 +agenteye keys create ops --permission-set standard --remove queries:run # 프리셋 시드 후 조정 agenteye keys update ci-bot --add evaluations:read --yes -agenteye keys regenerate ci-bot --yes # 시크릿 교체 (이전 시크릿은 즉시 무효화) -agenteye keys disable ci-bot --yes # 취소 +agenteye keys regenerate ci-bot --yes # 시크릿 교체 (이전 것 즉시 무효화) +agenteye keys disable ci-bot --yes # 폐기 ``` -권한은 `(permission-set ∪ --add) − --remove`로 계산됩니다. 토큰 형식은 `slug:action`(예: `events:read`) 또는 `slug:action.action`으로 하나의 리소스에 여러 액션을 지정합니다(`events:read.add` → `events:read`, `events:add`). 프리셋: `read-only`, `standard`, `admin`. 사람 전용 권한(`keys:update`)은 키에 부여할 수 없습니다. +권한은 `(permission-set ∪ --add) − --remove`로 계산됩니다. 토큰 형식은 `slug:action`(예: `events:read`) 또는 `slug:action.action`으로 하나의 리소스에서 여러 액션 확장(`events:read.add` → `events:read`, `events:add`). 프리셋: `read-only`, `standard`, `admin`. 사람 전용 권한(`keys:update`)은 키에 부여할 수 없습니다. -**`users`**: 조직 멤버, **이메일**로 참조됩니다(UUID id도 허용). +**`users`**: 조직 멤버. **이메일**로 참조합니다(UUID id도 허용). ```bash agenteye users list [--active-only] agenteye users show dev@corp.com agenteye users create dev@corp.com --permission-set standard agenteye users update dev@corp.com --add alerts:write --remove queries:delete # 예측 + 확인 -agenteye users disable dev@corp.com --yes # 보호된 계정/본인 계정 보호 기능 있음 +agenteye users disable dev@corp.com --yes # 보호된 계정/자기 자신 가드 적용 agenteye users enable dev@corp.com ``` -**`settings`**: 고정된 레지스트리(기존 키를 읽고 변경만 가능; 새 키는 생성 불가). +**`settings`**: 고정된 레지스트리(기존 키를 읽고 변경하는 것만 가능; 새 키 생성 불가). ```bash -agenteye settings list # 키 · 값 · 타입 · 업데이트 시간 (시크릿 마스킹) -agenteye settings schema # 각 키가 허용하는 값 (타입 · 범위 · 설명) +agenteye settings list # 키 · 값 · 유형 · 수정 시간 (시크릿 마스킹) +agenteye settings schema # 각 키가 허용하는 값 (유형 · 범위 · 설명) agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: 알림 정의, **이름**으로 참조됩니다. `create`는 위치 인수 NAME과 플래그 또는 `--file`로 전달하는 전체 JSON 본문을 받습니다. +**`alerts`**: 알림 정의. **이름**으로 참조합니다. `create`는 위치 인수로 NAME을 받으며, 플래그 또는 `--file`을 통한 전체 JSON 본문을 함께 사용합니다. ```bash agenteye alerts list @@ -285,7 +285,7 @@ agenteye alerts test high-errors --yes # 테스트 알림 agenteye alerts delete high-errors --yes ``` -**`incidents`**: 알림 인시던트, id로 참조됩니다(짧은 id 허용). `show`는 전체 활동 로그를 출력합니다; 조치 전에 읽어보세요. +**`incidents`**: 알림 인시던트. id로 참조합니다(짧은 id 허용). `show`는 전체 활동 로그를 출력합니다. 조치 전에 반드시 읽으세요. ```bash agenteye incidents list --state firing # 또한: acknowledged, resolved @@ -294,7 +294,7 @@ agenteye incidents show agenteye incidents ack agenteye incidents assign you@corp.com # 담당자는 운영자여야 함 agenteye incidents resolve --yes -agenteye incidents open --alert-id --severity critical # 알림에 대해 수동으로 생성 +agenteye incidents open --alert-id --severity critical # 알림에 대해 수동으로 인시던트 열기 agenteye incidents comment-add "root cause: upstream 5xx" agenteye incidents comment-list ; agenteye incidents comment-delete agenteye incidents subscribe ; agenteye incidents unsubscribe ; agenteye incidents subscribers @@ -302,10 +302,10 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### 분석 및 어시스턴트: `query` · `agent` -**`query`**: 분석 스토어에 대한 저장된 SQL과 임시 실행기. 저장된 쿼리는 **이름**으로 참조됩니다; SQL은 서버 측에서 검증됩니다(SELECT/WITH만 허용, 구문 타임아웃, 행 수 제한). +**`query`**: 분석 스토어에 대한 저장된 SQL과 임시 쿼리 실행기. 저장된 쿼리는 **이름**으로 참조합니다. SQL은 서버 측에서 검증됩니다(SELECT/WITH만 허용, 실행 타임아웃, 행 수 제한). ```bash -agenteye query schema [TABLE] # 분석 뷰의 컬럼 레이아웃 +agenteye query schema [TABLE] # 분석 뷰의 컬럼 구조 agenteye query run --sql "select count(*) from analytics.events" agenteye query run errs --arg prod --limit 100 # 저장된 쿼리 실행 + 위치 인수 $1 agenteye query list ; agenteye query show errs @@ -313,13 +313,13 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: 내장 **AI 어시스턴트**와 대화합니다(대시보드에서 채팅할 수 있는 것과 동일한 읽기 전용 분석 도구). 채팅은 짧은 chat-id로 참조됩니다(접두사로 확인). +**`agent`**: 내장 **AI 어시스턴트**(대시보드에서 채팅할 수 있는 것과 동일한 읽기 전용 분석가)와 통신합니다. 채팅은 짧은 chat-id로 참조합니다(접두사로 해석). ```bash agenteye agent health # AI 어시스턴트 설정/접근 가능 여부 확인 agenteye agent models # --model에 전달할 수 있는 모델 목록 (기본값 표시) agenteye agent ask "which agents errored most in the last day?" # 채팅 시작; 짧은 id 출력 -agenteye agent ask --chat "and which tools did they call?" # 이어서 대화 +agenteye agent ask --chat "and which tools did they call?" # 채팅 이어서 agenteye agent chats ; agenteye agent show agenteye agent rename --title "error triage" ; agenteye agent delete ``` @@ -331,20 +331,20 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | 코드 | 의미 | |---|---| | 0 | 성공 | -| 1 | 예기치 않은 오류 (예: 대시보드가 5xx 응답) | -| 2 | 사용 오류 (잘못된 인수, 알 수 없는 커맨드/플래그, 이름 충돌) | -| 3 | 대시보드에 접근할 수 없음 | -| 4 | 로그인하지 않았거나 세션이 만료됨; `agenteye login` 실행 필요 | -| 5 | 인증은 됐지만 계정에 필요한 권한이 없음 (메시지에 권한 이름 표시) | +| 1 | 예기치 않은 오류 (예: 대시보드가 5xx 반환) | +| 2 | 사용 오류 (잘못된 인수, 알 수 없는 명령어/플래그, 이름 충돌) | +| 3 | 대시보드에 연결할 수 없음 | +| 4 | 로그인되지 않았거나 세션 만료; `agenteye login` 실행 필요 | +| 5 | 인증은 되었지만 계정에 필요한 권한이 없음 (메시지에 권한 이름 표시) | | 6 | 요청한 리소스를 찾을 수 없음 (예: 알 수 없는 세션 또는 인시던트 id) | -종료 코드 덕분에 CLI를 안전하게 스크립트화할 수 있습니다: 코딩 에이전트는 `4`가 반환되면 재인증을 요청하거나, `5`가 반환되면 누락된 권한을 표시하도록 분기할 수 있습니다. 종료 코드 처리 패턴과 JSON 출력 형태는 [에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes)를 참조하세요. +이를 통해 CLI를 스크립트에서 안전하게 사용할 수 있습니다. 코딩 에이전트는 `4`를 받으면 재인증을 요청하거나, `5`를 받으면 부족한 권한을 표시하는 식으로 분기할 수 있습니다. 종료 코드 처리 패턴과 JSON 출력 형태는 [에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes)를 참조하세요. --- ## 다음 단계 -- **[에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes)**: 복사해서 바로 쓸 수 있는 쿼리 패턴, `jq` 원라이너, `--fields` 프로젝션, 종료 코드 처리, JSON 출력 형태 — 코딩 에이전트가 CLI를 구동하는 것을 염두에 두고 작성되었습니다. -- **[CLI 에이전트 스킬](/ko/agenteye/cli-skill)**: 이 CLI를 설치 가능한 Claude Code / Codex *스킬*로 패키징하여 코딩 에이전트가 자연어로 Failproof AI Observability를 제어할 수 있게 합니다. -- **[API 키](/ko/agenteye/api-keys)**: `keys create --add …` 뒤에 있는 권한 모델. +- **[에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes)**: 코딩 에이전트가 CLI를 구동할 때를 위해 작성된 복사-붙여넣기 쿼리 패턴, `jq` 원라이너, `--fields` 프로젝션, 종료 코드 처리, JSON 출력 형태. +- **[CLI 에이전트 스킬](/ko/agenteye/cli-skill)**: 이 CLI를 설치 가능한 Claude Code / Codex *스킬*로 패키징하여 코딩 에이전트가 자연어 요청으로 Failproof AI Observability를 구동할 수 있게 합니다. +- **[API 키](/ko/agenteye/api-keys)**: `keys create --add …` 뒤의 권한 모델. - **[AI 어시스턴트](/ko/agenteye/assistant)**: `agent ask`가 사용하는 어시스턴트 활성화 방법. \ No newline at end of file diff --git a/docs/ko/agenteye/codex-capture.mdx b/docs/ko/agenteye/codex-capture.mdx index eef114ab..ea31167b 100644 --- a/docs/ko/agenteye/codex-capture.mdx +++ b/docs/ko/agenteye/codex-capture.mdx @@ -1,55 +1,55 @@ --- title: "Codex 세션 캡처" -description: "팀의 로컬 OpenAI Codex 세션을 AgentEye에 일반 세션 및 이벤트로 수집합니다 — Codex 실행 방식을 변경할 필요가 없습니다." +description: "팀의 로컬 OpenAI Codex 세션을 AgentEye에 일반 세션 및 이벤트로 수집합니다 — Codex 사용 방식은 전혀 바꾸지 않아도 됩니다." --- -엔지니어들은 이미 매일 OpenAI Codex를 사용하고 있습니다. Codex 세션 캡처는 해당 코딩 세션을 AgentEye에 일반 세션 및 이벤트로 가져와, 다른 모든 관측 데이터와 함께 검색하고, 재생하고, 평가할 수 있게 합니다. 이 기능은 [Python SDK](/ko/agenteye/python-sdk)를 보완합니다. SDK는 직접 작성한 에이전트를 계측하는 반면, Codex 세션 캡처는 팀이 이미 사용 중인 Codex 작업을 수집합니다 — 실행 방식을 변경할 필요가 없습니다. +개발자들은 이미 매일 OpenAI Codex를 사용하고 있습니다. Codex 세션 캡처는 이러한 코딩 세션을 AgentEye에 일반 세션 및 이벤트로 가져와서, 다른 에이전트와 나란히 검색하고 재생하고 평가할 수 있게 해줍니다. 이 기능은 [Python SDK](/ko/agenteye/python-sdk)를 보완합니다. SDK는 직접 작성한 에이전트를 계측하는 반면, 이 기능은 팀이 이미 하고 있는 Codex 작업을 캡처합니다 — Codex 실행 방식은 전혀 변경할 필요가 없습니다. -소형 백그라운드 수집기가 Codex의 로컬 세션 트랜스크립트를 작성되는 즉시 읽어 AgentEye로 전송합니다. 머신당 하나의 수집기로 모든 로컬 Codex 서피스를 한 번에 캡처할 수 있으며, 서피스별 설정은 필요하지 않습니다. +소형 백그라운드 수집기가 Codex의 로컬 세션 트랜스크립트를 작성 즉시 읽어서 AgentEye로 전송합니다. 머신 한 대당 수집기 하나로 모든 로컬 Codex 인터페이스를 한 번에 캡처할 수 있어, 인터페이스별 별도 설정이 필요 없습니다. -동일한 수집기로 다른 에이전트도 캡처할 수 있습니다 — [OpenClaw](/ko/agenteye/openclaw-capture) 및 [Hermes](/ko/agenteye/hermes-capture)를 참조하세요. 사용하는 항목마다 활성화하면 단일 수집기로 여러 항목을 동시에 캡처할 수 있습니다. +동일한 수집기로 다른 에이전트도 캡처할 수 있습니다 — [OpenClaw](/ko/agenteye/openclaw-capture) 및 [Hermes](/ko/agenteye/hermes-capture)를 참조하세요. 사용하는 에이전트마다 활성화하면 수집기 하나로 여러 에이전트를 동시에 캡처할 수 있습니다. --- ## 캡처 대상 -**로컬**에서 실행되는 모든 Codex 서피스는 동일한 온디스크 세션 트랜스크립트를 생성하며, 수집기가 이를 모두 수집합니다: +**로컬**에서 실행되는 모든 Codex 인터페이스는 동일한 디스크 내 세션 트랜스크립트를 생성하며, 수집기가 이를 모두 수집합니다: - Codex **CLI** 및 `codex exec` -- **VS Code / IDE 확장 프로그램** -- **데스크톱 앱** (로컬에서 세션을 실행할 경우) +- **VS Code / IDE 확장** +- **데스크탑 앱** (로컬에서 세션을 실행할 때) -각 Codex 세션은 AgentEye [세션](/ko/agenteye/sessions)이 되고, 사용자 및 어시스턴트 메시지, 추론, 도구 호출, 도구 결과, 토큰 사용량은 해당하는 [이벤트](/ko/agenteye/event-stream)가 됩니다. 각 세션이 발생한 서피스(CLI, IDE, 데스크톱)가 기록되므로 구분이 가능합니다. +각 Codex 세션은 AgentEye [세션](/ko/agenteye/sessions)이 되며, 사용자 및 어시스턴트 메시지, 추론, 도구 호출, 도구 결과, 토큰 사용량은 해당하는 [이벤트](/ko/agenteye/event-stream)가 됩니다. 각 세션의 출처(CLI, IDE, 데스크탑)도 기록되므로 구분이 가능합니다. -> **클라우드 세션은 캡처되지 않습니다.** 데스크톱 앱은 점점 더 많은 세션을 Codex 클라우드에서 실행하며 머신에는 메타데이터만 저장합니다 — 읽을 수 있는 로컬 트랜스크립트가 없습니다. 로컬에서 실행된 세션만 캡처됩니다. +> **클라우드 세션은 캡처되지 않습니다.** 데스크탑 앱은 점점 더 많은 세션을 Codex 클라우드에서 실행하고 머신에는 메타데이터만 보관하므로, 읽어올 로컬 트랜스크립트가 존재하지 않습니다. 로컬에서 실행된 세션만 캡처됩니다. --- ## 활성화 방법 -캡처는 활성화하기 전까지 비활성 상태입니다. `events:add` 권한이 있는 API 키([API keys](/ko/agenteye/api-keys) 참조)로 수집기를 설치하고, Codex 캡처를 활성화합니다: +캡처는 기본적으로 비활성화 상태입니다. `events:add` 권한이 있는 API 키([API 키](/ko/agenteye/api-keys) 참조)로 수집기를 설치하고 Codex 캡처를 활성화하세요: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -이 명령으로 수집기가 설치되고, 백그라운드 서비스로 등록되며, 캡처가 시작됩니다. 실행 여부를 확인합니다: +이 명령은 수집기를 설치하고 백그라운드 서비스로 등록한 뒤 캡처를 시작합니다. 실행 중인지 확인하려면: ```bash agenteye-collector health ``` -최초 실행 시 기존 Codex 세션이 한 번 백필되며, 이후 새로운 활동은 몇 초 이내에 스트리밍됩니다. Codex의 파일은 읽기만 할 뿐 수정, 이동, 삭제되지 않으며, 재시작 여부와 관계없이 각 세션은 정확히 한 번만 전송됩니다. +최초 실행 시 기존 Codex 세션이 한 번 백필되며, 이후 새로운 활동은 몇 초 이내에 스트리밍됩니다. Codex 파일은 읽기만 할 뿐 수정, 이동, 삭제되지 않으며, 재시작 여부와 관계없이 각 세션은 정확히 한 번만 전송됩니다. --- ## 확인 위치 -캡처된 세션은 **Sessions**에, 이벤트는 **Events** 스트림에 표시됩니다. 다른 에이전트와 동일하게 표시되므로 [세션 재생](/ko/agenteye/sessions), [검색](/ko/agenteye/queries), [평가](/ko/agenteye/evaluations), [알림](/ko/agenteye/alerts) 모두 사용 가능합니다. Codex 에이전트로 필터링하면 해당 항목만 확인할 수 있습니다. +캡처된 세션은 **Sessions**에, 해당 이벤트는 **Events** 스트림에 표시됩니다. 다른 에이전트와 동일하게 취급되므로 [세션 재생](/ko/agenteye/sessions), [검색](/ko/agenteye/queries), [평가](/ko/agenteye/evaluations), [알림](/ko/agenteye/alerts) 기능을 모두 사용할 수 있습니다. Codex 에이전트로 필터링하면 해당 세션만 볼 수 있습니다. --- -## 개인정보 보호 +## 개인 정보 보호 -Codex 트랜스크립트에는 명령 출력, 파일 내용, Codex가 읽거나 쓴 모든 내용을 포함한 전체 세션이 담겨 있으며, 시크릿 정보가 포함될 수 있습니다. 캡처된 세션은 그대로 전송되므로, AgentEye에 해당 콘텐츠를 중앙화하는 것이 적절한 머신과 팀에 대해서만 캡처를 활성화하고, 수집기에는 `events:add`만 범위로 지정된 키를 사용하세요. 데이터 격리 방법에 대한 자세한 내용은 [Security](/ko/agenteye/security)를 참조하세요. \ No newline at end of file +Codex 트랜스크립트에는 명령 출력, 파일 내용, Codex가 읽거나 쓴 모든 내용 등 전체 세션이 포함되어 있으며, 비밀 정보가 담길 수 있습니다. 캡처된 세션은 그대로 전송되므로, AgentEye에 해당 콘텐츠를 중앙화하는 것이 적절한 머신과 팀에서만 캡처를 활성화하세요. 수집기에는 `events:add` 권한만 있는 키를 제공하는 것을 권장합니다. 데이터 격리 방식에 대한 자세한 내용은 [보안](/ko/agenteye/security)을 참조하세요. \ No newline at end of file diff --git a/docs/ko/agenteye/concepts.mdx b/docs/ko/agenteye/concepts.mdx index 088977cb..501c1e6d 100644 --- a/docs/ko/agenteye/concepts.mdx +++ b/docs/ko/agenteye/concepts.mdx @@ -1,87 +1,86 @@ --- title: "개념" -description: "Failproof AI Observability의 핵심 용어 — 이벤트, 세션, 평가, 감사, 발견 사항, 인시던트 — 를 한곳에서 정의합니다." +description: "Failproof AI Observability의 핵심 용어 — 이벤트, 세션, 평가, 감사, 발견, 인시던트 — 를 한 곳에서 정의합니다." --- - -이 페이지는 Failproof AI Observability에서 사용하는 용어를 정의합니다. 다른 가이드에서 낯선 용어를 만나면 여기에서 확인하세요. 처음부터 끝까지 읽을 필요는 없습니다. 훑어보거나, 특정 용어가 궁금할 때 다시 돌아오세요. +이 페이지는 Failproof AI Observability에서 사용하는 용어를 정의합니다. 다른 가이드에서 낯선 용어를 만났다면 이 곳에서 확인할 수 있습니다. 처음부터 끝까지 읽을 필요는 없습니다. 훑어보거나, 확인이 필요한 단어가 생겼을 때 돌아와 참고하세요. --- ## 데이터 모델 **이벤트(Event)** -데이터의 최소 단위입니다. 하나의 이벤트는 에이전트가 수행한 단일 단계를 기록합니다: `tool_use`, `model_request`, `hook_completed`, `error` 등. 에이전트는 [Python SDK](/ko/agenteye/python-sdk)를 통해 이벤트를 내보내며, **Events** 페이지에서 실시간으로 확인할 수 있습니다. +데이터의 최소 단위입니다. 하나의 이벤트는 에이전트가 수행한 단일 단계를 기록합니다: `tool_use`, `model_request`, `hook_completed`, `error` 등이 이에 해당합니다. 에이전트는 [Python SDK](/ko/agenteye/python-sdk)를 통해 이벤트를 내보내며, **Events** 페이지에서 실시간으로 확인할 수 있습니다. **세션(Session)** -`session_id`로 식별되는 하나의 에이전트 실행 단위입니다. 세션은 동일한 id를 공유하는 모든 이벤트를 묶어 **Sessions** 페이지의 단일 행으로 표시하고, 세부 페이지에서는 실행 그래프로 나타냅니다. 세션은 보통 `agent_start`로 시작하고 `agent_end`로 종료됩니다. +`session_id`로 식별되는 하나의 에이전트 실행 단위입니다. 세션은 동일한 id를 공유하는 모든 이벤트를 모아 **Sessions** 페이지의 단일 행으로 표시하고, 상세 페이지에서 실행 그래프로 시각화합니다. 세션은 보통 `agent_start`로 시작하여 `agent_end`로 끝납니다. **에이전트(Agent)** -`agent_id`로 식별되는 실행 내 행위자입니다. 하나의 실행에 여러 에이전트가 관여할 수 있습니다. 예를 들어, 요약 서브 에이전트를 생성하는 플래너 에이전트가 있을 수 있습니다. 서브 에이전트는 `parent_id`를 가지며, Failproof AI Observability는 이를 기반으로 실행 그래프에서 각각의 레인에 표시합니다. +실행 내에서 `agent_id`로 식별되는 이름 있는 행위자입니다. 하나의 실행에는 여러 에이전트가 관여할 수 있습니다. 예를 들어, 요약 서브 에이전트를 생성하는 플래너가 있을 수 있습니다. 서브 에이전트는 `parent_id`를 가지며, Failproof AI Observability가 실행 그래프에서 각 에이전트를 별도의 레인으로 표시할 수 있는 것은 이 덕분입니다. **환경(Environment)** -실행이 발생한 위치를 나타내는 레이블입니다: `production`, `staging`, `dev`. SDK를 구성할 때 한 번 설정합니다. 거의 모든 대시보드 페이지에서 환경별로 필터링할 수 있습니다. +실행이 발생한 위치를 나타내는 레이블입니다: `production`, `staging`, `dev`. SDK를 구성할 때 한 번 설정합니다. 대시보드의 거의 모든 페이지에서 환경별로 필터링할 수 있습니다. **컨텍스트 윈도우 사용률(Context-window fill)** -응답이 모델의 컨텍스트 윈도우를 얼마나 사용했는지를 나타내는 백분율입니다. Failproof AI Observability는 인식된 모델의 `model_response` 이벤트에 이 값을 기록하므로, 프롬프트 증가와 임박한 컴팩션을 이벤트 스트림에서 바로 확인할 수 있습니다. +응답이 모델의 컨텍스트 윈도우에서 차지하는 비율입니다. Failproof AI Observability는 인식하는 모델의 `model_response` 이벤트에 이 값을 기록하므로, 프롬프트 증가 추세와 임박한 컴팩션을 이벤트 스트림에서 바로 확인할 수 있습니다. --- ## 품질 **평가(Evaluation)** -완료된 세션에 대해 사용자가 운영하는 스코어링 서비스가 생성하는 품질 점수입니다. 평가는 선택 사항입니다. 평가자를 연결하기 전까지는 세션이 기록되지만 점수는 매겨지지 않습니다. 각 평가에는 여러 개의 명명된 점수(예: `helpfulness`, `factuality`, `tool_efficiency`)가 포함될 수 있으며, 각각에 간단한 이유 설명이 붙습니다. [평가 스위트](/ko/agenteye/evaluation-suite)를 참고하세요. +사용자가 실행하는 채점 서비스에 의해 완료된 세션에 부여되는 품질 점수입니다. 평가는 선택 사항입니다. 평가자를 연결하기 전까지는 세션이 기록되지만 채점되지는 않습니다. 각 평가는 여러 개의 명명된 점수(예: `helpfulness`, `factuality`, `tool_efficiency`)를 포함할 수 있으며, 각 점수에는 짧은 근거 메모가 함께 제공됩니다. [평가 스위트](/ko/agenteye/evaluation-suite)를 참고하세요. **점수 키(Score key)** -평가자가 보고하는 하나의 차원 이름으로, 예를 들어 `helpfulness`가 있습니다. 알림과 감사는 특정 점수 키를 시간에 따라 모니터링할 수 있습니다. +평가자가 보고하는 하나의 차원 이름입니다(예: `helpfulness`). 알림과 감사는 특정 점수 키를 시간 경과에 따라 모니터링할 수 있습니다. **평가자(Evaluator)** -사용자의 스코어링 서비스입니다. Failproof AI Observability는 완료된 실행의 전사 내용을 평가자에게 POST하고, 반환된 점수를 저장합니다. 기본 평가자는 제공되지 않으며, 스코어링 로직은 사용자가 직접 구현합니다. +사용자의 채점 서비스입니다. Failproof AI Observability는 완료된 실행의 트랜스크립트를 평가자에게 POST하고 반환된 점수를 저장합니다. 기본 평가자는 제공되지 않으며, 채점 로직은 사용자가 직접 작성합니다. --- -## 실패 탐지 및 수정 +## 오류 탐지 및 수정 **훅(Hook)** -에이전트 프레임워크가 단계 전후로 실행하는 가드레일 또는 부수 효과입니다: 콘텐츠 안전 검사, PII 제거, 예산 제한 등. 훅은 `outcome`(allow, deny, modify)이 포함된 `hook_triggered` / `hook_completed` 이벤트를 내보내며, 별도의 관찰 페이지를 가집니다. +에이전트 프레임워크가 단계 전후로 실행하는 가드레일 또는 부수 효과입니다: 콘텐츠 안전 검사, PII 삭제, 예산 제한 등이 있습니다. 훅은 `outcome`(allow, deny, modify)이 포함된 `hook_triggered` / `hook_completed` 이벤트를 발생시키며, 전용 관찰 페이지를 제공합니다. **알림 규칙(Alert rule)** -지정한 임계값을 지표가 초과할 때 실행되는 규칙입니다: 오류율, p95 레이턴시, 토큰 비용, 또는 평가자 점수 등. 규칙이 실행되면 인시던트가 생성되고 선택한 채널(이메일, Slack, 웹훅, 대시보드 내)로 알림이 전송됩니다. [알림](/ko/agenteye/alerts)을 참고하세요. +메트릭이 설정한 임계값을 초과할 때 발동하는 규칙입니다: 오류율, p95 지연 시간, 토큰 비용, 또는 평가자 점수가 대상입니다. 규칙이 발동하면 인시던트가 생성되고 지정한 채널(이메일, Slack, 웹훅, 대시보드 내)로 알림이 전송됩니다. [알림](/ko/agenteye/alerts)을 참고하세요. **인시던트(Incident)** -알림 규칙이 실행될 때 생성되는 오픈 이슈입니다. 인시던트는 수명 주기(확인, 할당, 해결)와 모든 작업을 기록하는 활동 타임라인을 가집니다. 수동으로 직접 열 수도 있습니다. +알림 규칙이 발동될 때 생성되는 미해결 이슈입니다. 인시던트는 수명 주기(인지, 할당, 해결)를 가지며, 모든 조치가 기록되는 활동 타임라인을 포함합니다. 수동으로 생성할 수도 있습니다. **감사(Audit)** -규칙을 별도로 정의하지 않은 실패 패턴을 찾기 위해 세션 전체에 걸쳐 로그를 주기적으로(시간별~주간) 분석하는 조사입니다: 오류 클러스터, 낮은 점수, 레이턴시 이상값, 도구 호출 루프, 완료되지 않은 실행 등. 알림이 이미 알고 있는 지표를 감시한다면, 감사는 다음에 무엇을 살펴봐야 할지 알려줍니다. [감사](/ko/agenteye/audits)를 참고하세요. +규칙을 따로 작성하지 않아도 세션 *전체*에 걸쳐 오류 패턴을 찾아내는 정기적인 조사입니다(매시간~매주). 오류 클러스터, 낮은 점수, 지연 시간 이상값, 툴 호출 루프, 완료되지 않은 실행 등을 분석합니다. 알림이 이미 알고 있는 메트릭을 모니터링한다면, 감사는 다음으로 확인해야 할 사항을 알려줍니다. [감사](/ko/agenteye/audits)를 참고하세요. -**발견 사항(Finding)** -감사 실행에서 나온 순위가 매겨진 증거 기반의 결과입니다. 발견 사항은 패턴을 명명하고, 그 배후의 정확한 세션을 링크하며, 트리아지 수명 주기(확인, 해결, 음소거, 기각)를 가집니다. Failproof AI Observability는 실행이 반복되어도 이미 알려진 패턴은 새로 쌓이지 않고 업데이트되도록 발견 사항을 중복 제거합니다. +**발견(Finding)** +감사 실행에서 나온 우선순위가 부여된 증거 기반의 결과입니다. 발견은 패턴을 명시하고, 그 근거가 되는 정확한 세션을 연결하며, 분류 수명 주기(인지, 해결, 음소거, 기각)를 포함합니다. Failproof AI Observability는 실행 간 발견을 중복 제거하여, 알려진 패턴이 반복 축적되지 않고 업데이트되도록 합니다. **AI 어시스턴트(The AI assistant)** -사용자 자신의 데이터를 기반으로 에이전트에 대한 질문에 자연어로 답하는 대시보드 내 채팅입니다. 기본적으로 읽기 전용이며, 어시스턴트가 생성하는 것(저장된 쿼리, 대시보드)은 승인 절차를 거쳐야 하고, 삭제는 절대 할 수 없습니다. [AI 어시스턴트](/ko/agenteye/assistant)를 참고하세요. +자신의 데이터를 기반으로 에이전트에 관한 질문에 자연스러운 언어로 답변하는 대시보드 내 채팅입니다. 기본적으로 읽기 전용이며, 어시스턴트가 생성하는 항목(저장된 쿼리, 대시보드)은 승인 과정을 거치고, 삭제는 절대 수행할 수 없습니다. [AI 어시스턴트](/ko/agenteye/assistant)를 참고하세요. --- -## 운영 +## 실행 환경 -**조직(Organization, 테넌트)** -격리된 워크스페이스입니다. 하나의 Failproof AI Observability 인스턴스는 각자의 사용자, 키, 데이터를 가진 여러 조직을 호스팅할 수 있습니다. 모든 대시보드 URL은 조직 슬러그(`//…`) 아래에 범위가 지정됩니다. +**조직(Organization, tenant)** +격리된 작업 공간입니다. 하나의 Failproof AI Observability 인스턴스는 여러 조직을 호스팅할 수 있으며, 각 조직은 자체 사용자, 키, 데이터를 가집니다. 모든 대시보드 URL은 조직 슬러그(`//…`) 아래에 범위가 지정됩니다. -**컬렉터(Collector)** -`agenteye-collector`는 각 에이전트 머신에서 실행되는 경량 데몬으로, SDK가 디스크에 기록하는 이벤트를 배치로 묶어 서버로 전송합니다. +**수집기(Collector)** +`agenteye-collector`는 각 에이전트 머신에서 실행되는 경량 데몬으로, SDK가 디스크에 기록한 이벤트를 일괄 처리하여 서버로 전송합니다. **API 키(API key)** -클라이언트를 서버에 인증하는 범위가 지정된 토큰입니다. 키는 세분화된 권한을 가집니다(예: 컬렉터를 위한 `events:add`, 대시보드 키를 위한 읽기 전용 범위). [API 키](/ko/agenteye/api-keys)를 참고하세요. +클라이언트가 서버에 인증하는 데 사용하는 범위 지정 토큰입니다. 키는 세밀한 권한을 부여합니다(예: 수집기용 `events:add`, 대시보드 키용 읽기 전용 범위). [API 키](/ko/agenteye/api-keys)를 참고하세요. **서버(Server)** 수집 및 API 서비스입니다. 이벤트를 수집하고, 데이터베이스에 운영 상태를 저장하며, 대시보드와 CLI를 제공합니다. **대시보드(Dashboard)** -웹 UI입니다. 모든 페이지는 조직 범위로 지정되며 서버의 API를 통해 데이터를 읽습니다. +웹 UI입니다. 모든 페이지는 조직에 범위가 지정되며 서버 API를 통해 데이터를 읽습니다. --- ## 다음 단계 -- [개요](/ko/agenteye/overview): 이 구성 요소들이 어떻게 맞물리는지 확인하세요. -- [Observability](/ko/agenteye/observability): 관찰 화면(Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file +- [개요](/ko/agenteye/overview): 각 구성 요소가 어떻게 연결되는지 확인합니다. +- [Observability](/ko/agenteye/observability): 관찰 화면 소개 (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file diff --git a/docs/ko/agenteye/dashboards.mdx b/docs/ko/agenteye/dashboards.mdx index fc446bc7..750a1ef0 100644 --- a/docs/ko/agenteye/dashboards.mdx +++ b/docs/ko/agenteye/dashboards.mdx @@ -1,46 +1,46 @@ --- title: "대시보드" -description: "실시간 에이전트 데이터를 팀 전체가 함께 보는 하나의 화면으로 만드세요." +description: "실시간 에이전트 데이터를 팀 전체가 함께 보는 하나의 공유 화면으로 만들어 보세요." --- -실시간 에이전트 데이터를 팀 전체가 함께 보는 하나의 화면으로 만드세요. 중요한 쿼리를 차트로 고정해 두면, 누구나 단 한 번의 쿼리 재실행 없이 동일한 수치를 한눈에 확인할 수 있습니다. +실시간 에이전트 데이터를 팀 전체가 함께 보는 하나의 공유 화면으로 만들어 보세요. 중요한 쿼리를 차트로 고정해 두면, 누구든 쿼리를 다시 실행할 필요 없이 동일한 수치를 한눈에 확인할 수 있습니다. -![저장된 쿼리로 구성된 대시보드: 시간당 이벤트 라인 차트, 유형별 오류 막대 차트, 지연 시간 영역 차트, 모델별 토큰 수](/agenteye/images/dashboard-fleet.png) +![저장된 쿼리로 구성된 대시보드: 시간당 이벤트 라인 차트, 유형별 오류 막대 차트, 지연 시간 영역 차트, 모델별 토큰 사용량](/agenteye/images/dashboard-fleet.png) -*하나의 보드, 네 개의 저장된 쿼리: 시간당 이벤트, 유형별 오류, 지연 시간, 모델별 토큰 수.* +*하나의 보드, 네 개의 저장 쿼리: 시간당 이벤트, 유형별 오류, 지연 시간, 모델별 토큰.* -## 모두가 같은 현실을 본다 +## 팀 전체가 같은 수치를 봅니다 -스크린샷을 채팅에 붙여넣거나 같은 쿼리를 하루에 다섯 번씩 다시 실행하는 일은 이제 그만하세요. 대시보드는 팀 내 누구나 동일한 화면을 열 수 있는 조직 공유 보드입니다. 기반 데이터가 변하면 차트도 함께 변하기 때문에 보드는 항상 최신 상태를 유지하고, 오래된 수치를 두고 다툴 일이 없습니다. +스크린샷을 채팅에 붙여넣거나 하루에 같은 쿼리를 다섯 번씩 다시 실행하는 일은 이제 그만하세요. 대시보드는 팀 내 누구든 열 수 있는 조직 전체 공유 보드로, 항상 동일한 뷰를 제공합니다. 기반 데이터가 변경되면 차트도 함께 갱신되므로 보드는 항상 최신 상태를 유지하고, 오래된 수치를 두고 다툴 일이 없습니다. -위의 플릿 대시보드는 일상적인 운영에 적합한 기본 구성입니다: +위의 플리트 대시보드는 일상적인 운영에 적합한 기본 구성입니다: -- **시간당 이벤트** 라인 차트 — 처리량을 모니터링하고 급격한 감소를 포착할 수 있습니다 -- **유형별 오류** 막대 차트 — 주요 장애 범주를 한눈에 파악할 수 있습니다 -- **지연 시간** 영역 차트 — 사용자가 불편을 느끼기 전에 속도 저하를 미리 확인할 수 있습니다 -- **모델별 토큰 수** 분석 — 비용을 항상 시야에 두고 관리할 수 있습니다 +- **시간당 이벤트** 라인 차트: 처리량을 모니터링하고 갑작스러운 감소를 빠르게 감지할 수 있습니다 +- **유형별 오류** 막대 차트: 주요 오류 카테고리를 한눈에 파악할 수 있습니다 +- **지연 시간** 영역 차트: 사용자가 불만을 제기하기 전에 속도 저하를 미리 발견할 수 있습니다 +- **모델별 토큰** 분석: 비용을 항상 확인할 수 있습니다 -보드는 `//dashboards`에서 찾을 수 있습니다. +보드는 `//dashboards`에서 확인할 수 있습니다. -## 이미 저장한 쿼리를 고정하세요 +## 저장해 둔 쿼리를 고정하세요 -모든 타일은 저장된 쿼리에서 시작합니다. [쿼리](/ko/agenteye/queries) 라이브러리(기본 제공 프리셋과 이벤트 및 평가 데이터를 기반으로 한 직접 작성 쿼리 포함)에서 원하는 쿼리를 빌드하고 저장한 다음, 데이터에 맞는 차트 형식으로 대시보드에 고정하세요. 시간에 따른 추세에는 **라인**, 카테고리 비교에는 **막대**, 볼륨에는 **영역**, 구성 비율에는 **파이** 차트가 적합합니다. +모든 타일은 저장된 쿼리에서 시작합니다. [쿼리](/ko/agenteye/queries) 라이브러리(기본 제공 프리셋과 이벤트 및 평가 데이터 기반의 사용자 정의 쿼리 포함)에서 원하는 쿼리를 빌드하고 저장한 다음, 데이터에 맞는 차트 유형으로 대시보드에 고정하세요. 시간 흐름에 따른 추이에는 **라인**, 카테고리 비교에는 **막대**, 볼륨 표현에는 **영역**, 비율 분석에는 **파이** 차트를 사용할 수 있습니다. -타일은 저장된 쿼리를 차트로 렌더링한 것에 불과하기 때문에 수동으로 동기화할 필요가 없습니다. 쿼리를 한 번 업데이트하면 해당 쿼리를 사용하는 모든 대시보드가 자동으로 업데이트됩니다. +타일은 저장된 쿼리를 차트로 렌더링한 것에 불과하므로, 수동으로 동기화할 필요가 없습니다. 쿼리를 한 번만 수정하면 해당 쿼리를 사용하는 모든 대시보드가 자동으로 업데이트됩니다. -## 단순한 양이 아닌 품질을 모니터링하세요 +## 볼륨뿐만 아니라 품질도 모니터링하세요 -양은 에이전트가 바쁘다는 것을 알려줍니다. 품질은 에이전트가 실제로 제대로 역할을 하고 있는지를 알려줍니다. [평가 점수](/ko/agenteye/evaluations)를 대시보드에 연결하면 실행 품질이 시간에 따라 어떻게 변하는지 추적할 수 있어, 품질 저하가 고객의 불만으로 이어지기 전에 차트의 하락으로 먼저 나타납니다. +볼륨은 에이전트가 바쁘게 작동하고 있다는 것을 보여줍니다. 품질은 에이전트가 실제로 제 역할을 하고 있는지를 보여줍니다. 대시보드를 [평가 점수](/ko/agenteye/evaluations)와 연결하면 실행 품질의 추이를 추적하는 보드를 만들 수 있어, 품질 저하가 발생했을 때 고객의 불만으로 놀라는 대신 차트의 하락으로 먼저 확인할 수 있습니다. ![저장된 평가 쿼리로 구성된 품질 중심 대시보드](/agenteye/images/dashboard-quality.png) -*품질 보드는 운영 지표 바로 옆에 평가 점수를 전면에 배치합니다.* +*품질 보드는 운영 수치 옆에 평가 점수를 항상 전면에 배치합니다.* -운영 보드와 품질 보드를 나란히 유지하면, 팀이 "제대로 작동하고 있는가?"와 "잘 하고 있는가?" 두 질문에 하나의 공간에서 답할 수 있습니다. 쿼리를 다시 실행할 필요도 없습니다. +운영 보드와 품질 보드를 나란히 유지하면, 팀은 "잘 작동하고 있는가?"와 "제대로 된 결과를 내고 있는가?" 두 가지 질문에 한 곳에서 답할 수 있습니다. 쿼리를 다시 실행할 필요도 없습니다. ## 관련 항목 - [쿼리](/ko/agenteye/queries): 타일의 기반이 되는 쿼리를 빌드하고 저장하세요. -- [평가](/ko/agenteye/evaluations): 실행을 채점하여 시간에 따른 품질을 차트로 확인하세요. -- [알림](/ko/agenteye/alerts): 이러한 지표의 임계값을 알림으로 전환하세요. \ No newline at end of file +- [평가](/ko/agenteye/evaluations): 실행에 점수를 매겨 시간에 따른 품질 변화를 차트로 확인하세요. +- [알림](/ko/agenteye/alerts): 모든 지표에 임계값을 설정해 알림을 받으세요. \ No newline at end of file diff --git a/docs/ko/agenteye/error-tracking.mdx b/docs/ko/agenteye/error-tracking.mdx index f15b5121..0f342398 100644 --- a/docs/ko/agenteye/error-tracking.mdx +++ b/docs/ko/agenteye/error-tracking.mdx @@ -1,40 +1,41 @@ --- title: "오류 추적" -description: "에이전트에서 발생하는 모든 실패를 한 곳에서 확인하세요. 동일한 오류가 연속으로 발생해도 하나의 문제로 묶어서 보여줍니다." +description: "에이전트가 발생시킨 모든 오류를 한 곳에서 확인하세요. 반복되는 오류 폭발도 하나의 문제로 묶어 표시됩니다." --- -에이전트에서 발생하는 모든 실패를 한 곳에서 확인하세요. 동일한 오류가 연속으로 발생해도 하나의 문제로 묶어서 보여줍니다. 라이브 피드를 스크롤하지 않아도, "뭔가 빨간색이다"에서 문제가 발생한 정확한 실행까지 클릭 한 번으로 이동할 수 있습니다. -![오류 페이지: 시간별 실패 히스토그램 아래에 빨간색 오류 행이 그룹으로 표시되며, 각 행에는 원클릭 "+ alert" 버튼이 있습니다](/agenteye/images/errors.png) -*오류 페이지: 시간별 실패 히스토그램과 반복 실패를 인시던트 단위로 하나의 행으로 묶어서 표시합니다.* +에이전트가 발생시킨 모든 오류를 한 곳에서 확인하세요. 반복되는 오류 폭발도 하나의 문제로 묶어 표시됩니다. 라이브 피드를 스크롤할 필요 없이, "뭔가 빨간색이다"에서 문제가 발생한 정확한 실행까지 원클릭으로 이동할 수 있습니다. -## 모든 실패를 자동으로 수집 +![오류 페이지: 시간 경과에 따른 오류 히스토그램 아래에 빨간색으로 그룹화된 오류 행이 표시되며, 각 행에는 원클릭 "+ alert" 버튼이 있습니다](/agenteye/images/errors.png) +*오류 페이지: 시간 경과에 따른 오류 히스토그램과 반복 오류를 인시던트별 한 행으로 축약한 목록.* -에이전트가 중단되었을 때, 빨간색 행이 사라지기 전에 잡으려고 라이브 이벤트 스트림을 스크롤할 필요가 없어야 합니다. **오류** 페이지가 대신 수집해 드립니다. 대시보드에서 빨간색으로 표시될 모든 항목을 하나의 트리아지 화면으로 모아주기 때문에, 처음 보는 화면에서 바로 무엇이 실패하고 있는지 확인할 수 있습니다. +## 모든 오류, 자동으로 수집됩니다 -또한 명확한 오류뿐만 아니라 조용한 실패도 포착합니다. 명시적인 `error` 이벤트 외에도, Failproof AI Observability는 `tool_result`, `hook_completed`, `agent_end`의 페이로드에 실패가 포함된 경우도 모두 여기에 표시합니다. 오류를 반환한 도구나 비정상 종료된 훅도, 큰 예외를 던지지 않았다는 이유만으로 그냥 지나치지 않습니다. +에이전트가 오류를 일으켰을 때 라이브 이벤트 스트림을 스크롤하며 빨간 행이 사라지기 전에 잡으려 할 필요가 없습니다. **Errors** 페이지가 대신 수집해 드립니다. 대시보드에서 빨간색으로 표시될 모든 항목을 하나의 트리아지 화면에 모아주므로, 처음 보이는 것이 "어디서 찾아야 하나"가 아니라 "무엇이 실패하고 있나"입니다. -페이지 상단에는 히스토그램이 시간에 따른 오류를 시각화합니다. 한 눈에 보면 현재 상황이 지속적인 백그라운드 오류인지, 아니면 몇 분 전에 시작된 급증인지 즉시 파악할 수 있어 지금 당장 대응해야 할지 판단할 수 있습니다. +명백한 오류만 잡는 것도 아닙니다. 명시적인 `error` 이벤트 외에도, Failproof AI Observability는 눈에 잘 띄지 않는 오류도 포착합니다. 실패 정보를 담은 `tool_result`, `hook_completed`, `agent_end` 페이로드가 있다면 여기에 표시됩니다. 오류를 반환한 도구나 비정상 종료된 훅이, 요란한 예외를 던지지 않았다는 이유만으로 그냥 지나치는 일이 없습니다. -다른 모든 관찰 화면과 마찬가지로, 오류 페이지는 조직 범위로 한정되며 날짜 범위, 환경, 에이전트, 세션별로 필터링할 수 있습니다. 전체 목록에서 실제로 관심 있는 특정 에이전트나 환경으로 좁혀볼 수 있습니다. +페이지 상단에는 시간 경과에 따른 오류를 히스토그램으로 보여줍니다. 한눈에 지속적인 배경 소음인지 몇 분 전부터 시작된 급증인지 파악할 수 있어, 지금 하던 일을 멈춰야 할지 바로 판단할 수 있습니다. -## 수백 개의 동일한 행이 아닌 하나의 인시던트 +모든 관찰 화면과 마찬가지로, Errors 페이지는 조직 단위로 범위가 지정되며 날짜 범위, 환경, 에이전트, 세션별로 필터링됩니다. 전체 목록에서 실제로 관심 있는 특정 에이전트나 환경만 좁혀볼 수 있습니다. -단일 의존성 오류 하나가 분당 수백 번 동일한 오류를 발생시킬 수 있습니다. 그대로 두면 거의 동일한 줄이 벽처럼 쌓여 실제로 확인해야 할 중요한 정보가 묻혀버립니다. +## 수백 개의 동일한 행 대신 하나의 인시던트로 -Failproof AI Observability는 동일한 세션과 오류 유형을 공유하는 반복 실패를 하나의 행으로 묶습니다. 연속 발생은 하나의 인시던트로 읽힙니다. 로그 라인이 아닌 문제 수를 세게 되고, 중요한 신호가 자체 볼륨에 묻히는 대신 상단에 유지됩니다. +하나의 의존성 오류가 1분에 수백 번씩 같은 오류를 발생시킬 수 있습니다. 날것 그대로라면 거의 동일한 행이 벽처럼 쌓여 실제로 봐야 할 것을 묻어버립니다. -## "뭔가 빨간색이다"에서 정확한 이벤트로 +Failproof AI Observability는 같은 세션과 오류 유형을 공유하는 반복 오류를 하나의 행으로 축약합니다. 오류 폭발이 하나의 인시던트로 보입니다. 로그 라인이 아닌 문제의 수를 세게 되고, 중요한 신호가 자기 자신의 볼륨에 묻히지 않고 상단에 유지됩니다. -행을 클릭하면 해당 실행의 세션으로 바로 이동하며, 실패한 정확한 이벤트에 위치가 맞춰집니다. 세션 ID를 복사하거나 문제가 발생한 순간을 찾아 스크롤할 필요가 없습니다. 에이전트가 중단되기 직전에 무엇을 했는지 한눈에 볼 수 있도록 전체 실행 그래프와 함께 바로 해당 지점에 도착합니다. +## "뭔가 빨간색이다"에서 정확한 이벤트까지 -`alerts:write` 권한이 있다면, 모든 행에 **+ alert** 버튼도 표시됩니다. 클릭하면 Observability가 동일한 실패를 다시 포착하도록 이미 설정이 채워진 새 알림 규칙을 엽니다. 방금 트리아지한 인시던트가 다음에도 예고 없이 놀라게 하는 대신, 다음 번에는 알림을 보내줍니다. +행을 클릭하면 해당 실행의 세션으로 바로 이동하며, 실패한 정확한 이벤트 위치에 위치가 잡힙니다. 세션 ID를 복사하거나 문제가 발생한 순간을 찾으려 스크롤할 필요 없이 바로 그 지점에 도착하며, 전체 실행 그래프를 한눈에 볼 수 있어 에이전트가 오류 직전에 무엇을 했는지 파악할 수 있습니다. -**찾는 방법:** **오류** 페이지는 대시보드의 관찰 섹션에 있으며, `//errors` 경로에서 확인할 수 있습니다. +`alerts:write` 권한이 있다면 모든 행에 **+ alert** 버튼도 표시됩니다. 클릭하면 Observability가 동일한 오류를 다시 감지하도록 미리 채워진 새 알림 규칙을 엽니다. 방금 트리아지한 인시던트가 다음번에도 당신을 놀라게 하는 대신 알림을 보내게 됩니다. + +**찾는 방법:** **Errors** 페이지는 대시보드의 observe 섹션에 있으며, `//errors` 경로로 접근할 수 있습니다. ## 관련 항목 -- [알림](/ko/agenteye/alerts): 모든 실패를 페이징 규칙으로 전환합니다. -- [인시던트](/ko/agenteye/incidents): 발생한 알림을 열림에서 해결까지 추적합니다. -- [세션](/ko/agenteye/sessions): 오류 뒤에 있는 전체 실행을 엽니다. -- [감사](/ko/agenteye/audits): Observability가 실행 전반에 걸친 실패 패턴을 자동으로 찾아줍니다. \ No newline at end of file +- [Alerts](/ko/agenteye/alerts): 모든 오류를 알림 규칙으로 전환합니다. +- [Incidents](/ko/agenteye/incidents): 발생한 알림을 열림에서 해결까지 추적합니다. +- [Sessions](/ko/agenteye/sessions): 오류 뒤에 있는 전체 실행을 엽니다. +- [Audits](/ko/agenteye/audits): Observability가 실행 전반에서 오류 패턴을 찾아드립니다. \ No newline at end of file diff --git a/docs/ko/agenteye/evaluation-suite.mdx b/docs/ko/agenteye/evaluation-suite.mdx index 851169cf..b425e833 100644 --- a/docs/ko/agenteye/evaluation-suite.mdx +++ b/docs/ko/agenteye/evaluation-suite.mdx @@ -1,26 +1,26 @@ --- -title: "평가 Suite" -description: "Failproof AI Observability는 완료된 모든 에이전트 실행을 자동으로 품질 점수화할 수 있습니다: 소규모 점수화 서비스를 제공하면 Observability가 나머지를 처리합니다." +title: "Evaluation Suite" +description: "Failproof AI Observability는 완료된 모든 에이전트 실행을 자동으로 품질 평가할 수 있습니다: 소규모 채점 서비스를 제공하면 Observability가 나머지를 처리합니다." --- -Failproof AI Observability는 완료된 모든 에이전트 실행을 자동으로 품질 점수화할 수 있습니다: 소규모 점수화 서비스를 제공하면 Observability가 나머지를 처리합니다. 이를 통해 관심 있는 차원(유용성, 도구 효율성, 사실성, 안전성 등 원하는 항목을 선택)을 추적하고, 회귀를 조기에 감지하며, 에이전트나 환경을 한눈에 비교할 수 있습니다. 점수화는 선택 사항입니다: 서버에 `EVALUATOR_ENDPOINT`를 설정하기 전까지는 파이프라인이 아무것도 수행하지 않습니다. +Failproof AI Observability는 완료된 모든 에이전트 실행을 자동으로 품질 평가할 수 있습니다: 소규모 채점 서비스를 제공하면 Observability가 나머지를 처리합니다. 이를 통해 원하는 평가 항목(유용성, 도구 효율성, 사실성, 안전성 등 원하는 항목을 선택)을 추적하고, 회귀를 조기에 발견하며, 에이전트나 환경을 한눈에 비교할 수 있습니다. 채점은 선택 사항입니다: 서버에 `EVALUATOR_ENDPOINT`를 설정하기 전까지는 파이프라인이 아무 작업도 하지 않습니다. -> **참고:** 점수 차원은 직접 정의합니다. 평가자는 원하는 숫자형 키를 반환할 수 있으며, Observability는 전송된 값을 저장, 추세 분석, 표시합니다. +> **참고:** 점수 항목은 직접 정의합니다. 평가자는 원하는 숫자 키를 반환할 수 있으며, Observability는 반환된 내용을 저장하고 트렌드를 추적하며 표시합니다. -## 개요 +## 한눈에 보기 -1. **점수화 서비스를 작성합니다.** 세션 트랜스크립트를 읽고 점수를 반환하는 소규모 HTTP 서비스를 구축합니다. Observability에는 복사하여 사용할 수 있는 참조 구현이 포함되어 있습니다. [SDK를 이용한 평가자 작성](#writing-an-evaluator-with-the-sdk)을 참조하세요. -2. **Observability가 해당 서비스를 가리키도록 설정합니다.** 서버 프로세스에 `EVALUATOR_ENDPOINT`(및 공유 `EVALUATOR_TOKEN`)를 설정합니다. -3. **점수가 기록되는 것을 확인합니다.** 완료된 모든 세션은 자동으로 점수화되며, 결과는 세션 상세 페이지, 세션 그리드, 저장된 대시보드에 표시됩니다. +1. **채점기를 작성합니다.** 세션 트랜스크립트를 읽고 점수를 반환하는 소규모 HTTP 서비스를 구성합니다. Observability에는 복사하여 사용할 수 있는 참조 구현이 포함되어 있습니다. [SDK로 평가자 작성하기](#writing-an-evaluator-with-the-sdk)를 참조하세요. +2. **Observability가 이를 가리키도록 설정합니다.** 서버 프로세스에 `EVALUATOR_ENDPOINT`(및 공유 `EVALUATOR_TOKEN`)를 설정합니다. +3. **점수가 반영되는 것을 확인합니다.** 완료된 모든 세션은 자동으로 채점되며, 결과는 세션 상세 페이지, 세션 그리드, 저장된 대시보드에 표시됩니다. -![평가 요약, 차원별 점수 바, 오른쪽 패널의 추론 텍스트가 포함된 세션 상세 보기](/agenteye/images/session-detail.png) +![평가 요약, 항목별 점수 바, 오른쪽 레일의 추론 텍스트가 포함된 세션 상세 보기](/agenteye/images/session-detail.png) -*평가자를 구성하면 완료된 각 실행이 점수화되고 결과가 세션의 오른쪽 패널에 표시됩니다: 상단의 요약, 그 아래 추론이 포함된 차원별 점수 바.* +*평가자가 구성되면 완료된 각 실행이 채점되고 결과가 세션의 오른쪽 레일에 표시됩니다: 상단에 요약, 이후 항목별 점수 바와 추론이 나타납니다.* --- -## 작동 방식 +## 동작 방식 ```mermaid flowchart LR @@ -32,46 +32,73 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Observability SDK가 세션에 대한 `agent_end` 이벤트를 전송하면, 서버는 +Observability SDK가 세션에 대한 `agent_end` 이벤트를 발생시키면, 서버는 평가를 예약합니다. 그런 다음 전체 이벤트 트랜스크립트를 평가자 서비스에 POST하며, -평가자 서비스는 다음 중 하나를 수행할 수 있습니다: - -- **인라인으로 결과를 반환합니다**: `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. 결과는 세션의 평가 타임라인에 추가됩니다. `reasoning`과 `summary`는 선택 사항입니다. -- **지연합니다**: `{"status":"pending", "job_id":"abc-123"}`. 그러면 Observability는 평가자가 `{"status":"done", ...}` 또는 `{"status":"error", "error":"..."}`를 반환할 때까지 `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123`을 호출합니다. - - 폴링 주기는 작업별로 설정됩니다: `pending` 응답에 `next_poll_secs`를 포함하여 재정의할 수 있으며, 그렇지 않으면 Observability는 `GET /config`의 `default_poll_interval_secs` 값을 사용하고, 그것도 없으면 서버는 `EVALUATOR_POLLING_INTERVAL_SECS`(기본값 10초)로 대체합니다. 모든 값은 [1초, 1시간] 범위로 제한됩니다. - -`agent_end`를 전송하지 않는 세션(예: 충돌한 에이전트 프로세스)도 처리할 수 있습니다: 평가자의 `GET /config`는 `{"inactivity_timeout_secs": 1800}`을 반환할 수 있으며, Observability는 해당 시간 동안 유휴 상태인 세션을 평가합니다. 이 폴백을 비활성화하려면 해당 필드를 `null`로 설정하거나 생략하세요. - -`EVALUATOR_ENDPOINT`가 설정되지 않은 경우 파이프라인은 완전히 아무런 동작도 하지 않습니다. - -세션은 **시간이 지남에 따라 여러 개의 최종 평가를 누적**할 수 있습니다: 각 `agent_end` 이벤트(및 대시보드에서의 수동 재평가)는 새로운 평가 행을 추가합니다. 이는 재개된 대화를 평가하는 공식 방법입니다: 사용자가 에이전트를 종료하고 나중에 돌아와 더 많은 이벤트를 전송하고 에이전트를 다시 종료하면, 두 번째 평가가 전체 업데이트된 트랜스크립트에 대해 실행됩니다. 대시보드는 가장 최근 평가를 헤드라인으로 렌더링하고 이전 평가는 접을 수 있는 타임라인으로 표시합니다. 세션에 대한 평가가 실행 중인 동안, 해당 세션의 추가 `agent_end` 이벤트는 무시됩니다; 실행 중인 평가가 완료된 후 다음 이벤트가 평소와 같이 새로운 평가를 큐에 추가합니다. - -비활성 폴백은 재개된 세션에도 다시 적용됩니다: 이전 최종 평가 이후 새 이벤트가 도착하고 세션이 `inactivity_timeout_secs`를 초과하여 유휴 상태가 되면 새로운 평가가 큐에 추가됩니다. - -일시적인 오류(5xx, 429, 타임아웃, 네트워크 오류)는 `EVALUATOR_MAX_ATTEMPTS`까지 지수 백오프로 재시도됩니다; 4xx 응답은 최종 오류로 처리됩니다. Observability는 여러 수평 확장된 서버 인스턴스와 함께 안전하게 실행됩니다; 작업이 분산되어 동일한 세션이 동시에 두 번 처리되지 않습니다. +평가자는 다음 중 하나를 수행할 수 있습니다: + +- **인라인으로 결과를 반환합니다:** `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. 결과는 + 세션의 평가 타임라인에 추가됩니다. `reasoning`과 + `summary`는 선택 사항입니다. +- **지연 처리합니다:** `{"status":"pending", "job_id":"abc-123"}`. 그러면 Observability가 + 평가자가 `{"status":"done", ...}` 또는 `{"status":"error", "error":"..."}`를 반환할 때까지 + `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123`을 호출합니다. + + 폴링 주기는 작업별로 설정됩니다: `pending` 응답에는 재정의를 위한 + `next_poll_secs`가 포함될 수 있습니다. 포함되지 않은 경우 Observability는 + `GET /config`의 `default_poll_interval_secs` 값을 사용하고, 그것도 없으면 + 서버가 `EVALUATOR_POLLING_INTERVAL_SECS`(기본값 10초)로 폴백합니다. + 모든 값은 [1초, 1시간] 범위로 제한됩니다. + +`agent_end`를 발생시키지 않는 세션(예: 충돌한 에이전트 프로세스)도 +처리할 수 있습니다: 평가자의 `GET /config`가 +`{"inactivity_timeout_secs": 1800}`을 반환하면, Observability는 해당 시간만큼 +유휴 상태인 세션을 평가합니다. 이 폴백을 비활성화하려면 필드를 `null`로 설정하거나 생략하세요. + +`EVALUATOR_ENDPOINT`가 설정되지 않은 경우 파이프라인은 완전히 no-op 상태입니다. + +세션은 **시간이 지남에 따라 여러 개의 최종 평가를 누적**할 수 있습니다: 각 +`agent_end` 이벤트(및 대시보드에서의 수동 재평가)는 새로운 평가 행을 추가합니다. +이는 재개된 대화를 평가하는 지원되는 방식입니다: 사용자가 에이전트를 종료하고, +나중에 돌아와 더 많은 이벤트를 보내고, 에이전트를 다시 종료하면, 업데이트된 전체 +트랜스크립트에 대해 두 번째 평가가 실행됩니다. 대시보드는 가장 최근 평가를 +헤드라인으로 렌더링하고 이전 평가는 접을 수 있는 타임라인으로 표시합니다. 한 세션에 +대해 평가가 실행 중인 동안, 해당 세션에 대한 추가 `agent_end` 이벤트는 무시됩니다; +실행 중인 평가가 완료된 후 다음 이벤트가 새로운 평가를 일반적으로 대기열에 추가합니다. + +비활성 폴백은 재개된 세션에서도 다시 작동합니다: 이전 최종 평가 이후 새 이벤트가 +도착하고 세션이 `inactivity_timeout_secs`를 초과하여 유휴 상태가 되면 새로운 평가가 +대기열에 추가됩니다. + +일시적 오류(5xx, 429, 타임아웃, 네트워크 오류)는 `EVALUATOR_MAX_ATTEMPTS`까지 +지수 백오프로 재시도됩니다; 4xx 응답은 최종 오류로 처리됩니다. Observability는 +여러 수평 확장 서버 인스턴스로 안전하게 실행할 수 있습니다; 작업이 분배되어 동일한 +세션이 동시에 두 번 디스패치되지 않습니다. --- ## HTTP 계약 -모든 인증된 라우트는 **베어러 토큰 인증**을 사용합니다. 양쪽에 동일한 값이 구성되어야 합니다: +모든 인증된 라우트는 **베어러 토큰 인증**을 사용합니다. 동일한 값이 양쪽에 +구성되어야 합니다: - Observability 서버: 환경 변수 `EVALUATOR_TOKEN` -- 평가자 서비스: 동일한 방식으로 구성 (`agenteye-evaluator` SDK는 관례에 따라 `EVALUATOR_TOKEN`을 읽음) +- 평가자 서비스: 동일한 방식으로 구성 (`agenteye-evaluator` SDK는 + 관례적으로 `EVALUATOR_TOKEN`을 읽습니다) -`EVALUATOR_TOKEN`이 설정되지 않은 경우 서버는 `Authorization` 헤더를 전송하지 않습니다; 평가자는 익명 요청을 수락할 수 있으며, 내부 전용 네트워크에서는 괜찮지만 공개 인터넷에서는 권장하지 않습니다. +`EVALUATOR_TOKEN`이 설정되지 않은 경우 서버는 `Authorization` 헤더를 전송하지 않습니다; +평가자는 익명 요청을 허용할 수 있으며, 내부 네트워크에서는 괜찮지만 공용 인터넷에서는 +권장하지 않습니다. ### 평가자가 제공해야 하는 라우트 -| 라우트 | 바디 / 파라미터 | 응답 | +| 라우트 | 본문 / 파라미터 | 응답 | |---|---|---| | `GET /health` | 없음 | `{"status":"ok"}` (공개, 인증 없음) | | `GET /config` | 없음 | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | | `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` 또는 `{"status":"pending", "job_id":"..."}` | | `GET /evaluate/{id}` | 없음 | `/evaluate`와 동일한 응답 형태 | -### 서버가 전송하는 `EvalRequest` 바디 +### 서버가 전송하는 `EvalRequest` 본문 ```json { @@ -104,7 +131,11 @@ Observability SDK가 세션에 대한 `agent_end` 이벤트를 전송하면, 서 } ``` -`reasoning`(점수별 근거 맵)과 `summary`(전체 단락 서술)는 모두 선택 사항입니다. `reasoning`의 키는 `scores`의 키와 일치해야 합니다; 대시보드는 각 항목을 해당 점수 바 아래에 인라인으로 렌더링합니다. `scores`만 반환하는 이전 평가자는 변경 없이 계속 작동합니다; `reasoning`과 `summary`는 단순히 null로 읽히고 해당 UI 요소는 생략됩니다. +`reasoning` (점수별 근거 맵)과 `summary` (전체 단락 서술)는 모두 선택 사항입니다. +`reasoning`의 키는 `scores`의 키를 반영해야 합니다; 대시보드는 각 항목을 +해당 점수 바 아래에 인라인으로 렌더링합니다. `scores`만 반환하는 이전 평가자는 +변경 없이 계속 작동합니다; `reasoning`과 `summary`는 단순히 null로 읽히고 +해당 UI 요소가 생략됩니다. **비동기 (지연):** @@ -112,7 +143,9 @@ Observability SDK가 세션에 대한 `agent_end` 이벤트를 전송하면, 서 { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs`는 선택 사항입니다; 생략하면 서버는 `/config`의 평가자 `default_poll_interval_secs`로 대체하고, 그다음에는 자체 `EVALUATOR_POLLING_INTERVAL_SECS` 환경 변수로 대체합니다. +`next_poll_secs`는 선택 사항입니다; 생략된 경우 서버는 `/config`의 +평가자 `default_poll_interval_secs`로, 그다음에는 자체 +`EVALUATOR_POLLING_INTERVAL_SECS` 환경 변수로 폴백합니다. **평가자 측 최종 오류:** @@ -120,16 +153,19 @@ Observability SDK가 세션에 대한 `agent_end` 이벤트를 전송하면, 서 { "status": "error", "error": "model service unavailable" } ``` -서버는 다른 2xx 바디를 프로토콜 오류로 처리하고 세션에 대한 최종 `error`를 기록합니다. +서버는 다른 2xx 본문을 프로토콜 오류로 처리하고 세션에 대해 +최종 `error`를 기록합니다. --- -## SDK를 이용한 평가자 작성 +## SDK로 평가자 작성하기 HTTP 계약을 직접 구현할 필요가 없습니다. `agenteye-evaluator` -Python 패키지는 인증, 라우팅, 요청/응답 형태를 자동으로 처리하는 타입이 지정된 FastAPI 래퍼를 제공합니다. +Python 패키지는 인증, 라우팅, 요청/응답 형태를 처리하는 타입이 지정된 FastAPI 래퍼를 제공합니다. -Failproof AI Observability는 트랜스크립트 형태에서 `helpfulness`, `tool_efficiency`, `factuality`를 점수화하는 **작동하는 참조 평가자**도 함께 제공합니다. 이를 시작점으로 복사하고 LLM 판단자, 규칙 엔진 등 품질 기준에 맞는 자체 로직으로 교체하세요. +Failproof AI Observability에는 트랜스크립트 형태에서 `helpfulness`, `tool_efficiency`, `factuality`를 +채점하는 **작동하는 참조 평가자**도 포함되어 있습니다. 이를 시작점으로 복사하고 +자체 로직(LLM 판정기, 규칙 엔진 등 품질 기준에 맞는 방식)으로 교체하세요. 최소 실행 가능한 평가자: @@ -150,42 +186,55 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -`app` 인스턴스는 모든 ASGI 서버에서 실행되므로 `uvicorn module:app`으로 시작할 수 있습니다. +`app` 인스턴스는 모든 ASGI 서버에서 실행되므로 `uvicorn module:app`으로 시작합니다. -비용이 많이 드는 작업을 지연해야 하는 평가자의 경우 대신 `JobPending`을 반환하고 `@app.job_lookup` 핸들러를 등록하세요; Observability 서버는 평가자가 최종 상태를 반환하거나 `EVALUATOR_MAX_POLL_DURATION_SECS` 제한(기본값 1시간)이 경과할 때까지 `GET /evaluate/{job_id}`를 폴링합니다. +비용이 많이 드는 작업을 지연해야 하는 평가자의 경우, 대신 `JobPending`을 반환하고 +`@app.job_lookup` 핸들러를 등록하세요; Observability 서버는 평가자가 최종 상태를 +반환하거나 `EVALUATOR_MAX_POLL_DURATION_SECS` 제한(기본값 1시간)이 경과할 때까지 +`GET /evaluate/{job_id}`를 폴링합니다. -전체 API 참조, 비동기 패턴, 이벤트 스키마는 `agenteye-evaluator` SDK의 README에 문서화되어 있습니다. +전체 API 참조, 비동기 패턴, 이벤트 스키마는 `agenteye-evaluator` SDK의 README에 +문서화되어 있습니다. --- -## 평가자 실행 +## 평가자 실행하기 -평가자는 **사용자의 서비스**입니다 — Failproof AI Observability는 기본 평가자를 제공하지 않으므로, 자체 서비스를 실행하는 곳에서 구축하고 실행해야 합니다. 모든 ASGI 서버에서 실행됩니다(예: `uvicorn my_evaluator:app`); [HTTP 계약](#http-contract)의 `/health`, `/config`, `/evaluate` 라우트를 제공한 다음 서버가 해당 서비스를 가리키도록 설정합니다([서버 구성](#configuring-the-server) 참조). +평가자는 **사용자의 서비스**입니다 — Failproof AI Observability는 기본 평가자를 제공하지 않으므로, +자체 서비스를 운영하는 곳에서 직접 빌드하고 실행해야 합니다. +모든 ASGI 서버에서 실행됩니다(예: `uvicorn my_evaluator:app`); +[HTTP 계약](#http-contract)에서 `/health`, `/config`, `/evaluate` 라우트를 제공한 다음 +서버가 이를 가리키도록 설정합니다([서버 구성하기](#configuring-the-server) 참조). -평가자에 접근할 수 있으면 `GET /health`는 `{"status":"ok"}`를 반환합니다. 에이전트가 엔드-투-엔드 실행을 완료한 후, 서버의 `GET /evaluations`는 `status: "done"` 및 평가자가 생성한 점수가 포함된 행을 반환합니다. +평가자에 접근할 수 있게 되면 `GET /health`가 `{"status":"ok"}`를 반환합니다. +에이전트가 엔드투엔드로 실행된 후, 서버의 `GET /evaluations`는 평가자가 생성한 +`status: "done"` 및 점수가 포함된 행을 반환합니다. --- -## 서버 구성 +## 서버 구성하기 -서버 프로세스에 설정: +서버 프로세스에 설정합니다: | 환경 변수 | 의미 | |---|---| -| `EVALUATOR_ENDPOINT` | 평가자의 기본 URL (`http://evaluator:9000`). 미설정 = 파이프라인 비활성화. | +| `EVALUATOR_ENDPOINT` | 평가자의 기본 URL(`http://evaluator:9000`). 미설정 시 파이프라인 비활성화. | | `EVALUATOR_TOKEN` | 베어러 토큰. 평가자 서비스에 구성된 값과 동일해야 합니다. | -| `EVALUATOR_WORKERS` | 서버 인스턴스당 워커 태스크 수 (기본값 2). | -| `EVALUATOR_CLAIM_BATCH` | 워커 틱당 처리되는 행 수 (기본값 4). 배치는 **동시에** 처리됩니다; 평가자 엔드포인트의 실질적인 동시성은 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`입니다. | -| `EVALUATOR_POLL_IDLE_SECS` | 평가가 예정되지 않았을 때 디스패치 시도 사이에 워커가 대기하는 시간 (기본값 2초). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | 응답별 `next_poll_secs`도, 평가자의 `default_poll_interval_secs`도 설정되지 않은 경우 `GET /evaluate/{id}` 주기의 최종 대체값 (기본값 10초). | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | 요청별 타임아웃 (기본값 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | 이 횟수만큼 일시적 오류가 발생하면 결과가 최종 `error`로 기록됩니다 (기본값 5). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` 주기 (기본값 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | 세션이 `timeout`으로 종료되기 전까지 폴링 큐에 머무를 수 있는 최대 실제 경과 시간 (기본값 3600초). 계속 `pending`을 반환하는 평가자를 방지합니다. | - -자동 점수화를 활성화하려면 서버에 `EVALUATOR_ENDPOINT`와 `EVALUATOR_TOKEN`을 모두 설정하고 서버를 재시작하여 변경 사항을 적용하세요. `EVALUATOR_ENDPOINT`가 설정되지 않으면 파이프라인은 아무런 동작도 하지 않습니다. - -위의 조정 항목은 선택 사항입니다; 기본값을 재정의해야 하는 경우에만 서버에 해당 환경 변수를 설정하세요. +| `EVALUATOR_WORKERS` | 서버 인스턴스당 워커 태스크 수(기본값 2). | +| `EVALUATOR_CLAIM_BATCH` | 워커 틱당 처리할 행 수(기본값 4). 배치는 **동시에** 처리됩니다; 평가자 엔드포인트의 실효 동시성은 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`입니다. | +| `EVALUATOR_POLL_IDLE_SECS` | 평가 대기 없을 때 워커가 디스패치 시도 사이에 대기하는 시간(기본값 2초). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | 응답별 `next_poll_secs`도, 평가자의 `default_poll_interval_secs`도 설정되지 않은 경우 `GET /evaluate/{id}` 주기의 최종 폴백(기본값 10초). | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | 요청당 타임아웃(기본값 30000). | +| `EVALUATOR_MAX_ATTEMPTS` | 이 횟수만큼 일시적 오류 발생 시 결과가 최종 `error`로 기록됩니다(기본값 5). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` 주기(기본값 300). | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | 세션이 `timeout`으로 종료되기 전까지 폴링 대기열에 남아있을 수 있는 최대 실제 시간(기본값 3600초). `pending`을 계속 반환하는 평가자에 대한 방어 수단입니다. | + +자동 채점을 활성화하려면 서버에 `EVALUATOR_ENDPOINT`와 +`EVALUATOR_TOKEN`을 모두 설정한 다음, 변경 사항을 적용하기 위해 서버를 재시작합니다. +`EVALUATOR_ENDPOINT`가 설정되지 않으면 파이프라인은 no-op 상태를 유지합니다. + +위의 조정 옵션들은 선택 사항입니다; 기본값을 재정의해야 할 때만 서버에 +해당 환경 변수를 설정하세요. --- @@ -193,17 +242,21 @@ def run(req: EvalRequest) -> EvalResponse: | 메서드 | 경로 | 필요한 권한 | 목적 | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | 최종 결과 조회. `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`을 지원합니다. `limit` 기본값은 50이며 최대 200으로 제한됩니다(최대 1000으로 제한되는 `/events`와 다름). `environment`는 쉼표로 구분된 목록을 허용합니다(예: `environment=prod,staging`); 단일 값도 여전히 작동합니다. `latest_per_session=true`를 사용하면 응답에 `session_id`당 최대 한 행(`completed_at` 기준 가장 최근)이 포함되며, 세션 목록 페이지에서 세션의 평가 타임라인을 현재 헤드라인으로 축소하는 데 사용됩니다. 기본값은 false(전체 기록 반환)입니다. | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | 필터링된 슬라이스에 대한 집계된 평가 상태: 총 개수, 완료/오류/타임아웃 분류, 점수 키별 통계(임의 `scores` 키에 대한 개수/평균/최솟값/최댓값/p50), 시간 버킷별 타임라인. `/evaluations`와 **동일한 필터 파라미터**에 `featured_keys`(추세를 볼 점수 키의 CSV)와 `latest_per_session`이 추가됩니다. 대시보드 기능을 지원합니다; 메트릭은 샘플링 없이 전체 일치 집합에 대해 정확합니다. | +| `GET` | `/evaluations` | `evaluations:read` | 최종 결과를 조회합니다. `session_id`, `agent_id`, `environment`, `status`(`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`을 지원합니다. `limit`의 기본값은 50이며 최대 200으로 제한됩니다(최대 1000인 `/events`와 다름에 유의). `environment`는 쉼표로 구분된 목록을 허용합니다(예: `environment=prod,staging`); 단일 값도 여전히 작동합니다. `latest_per_session=true`를 사용하면 응답에 `session_id`당 최대 하나의 행만 포함됩니다(`completed_at` 기준 가장 최근), 세션 목록 페이지에서 세션의 평가 타임라인을 현재 헤드라인으로 축소하는 데 사용됩니다. 기본값은 false(전체 기록 반환)입니다. | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | 필터된 슬라이스의 집계된 평가 상태: 총 개수, 완료/오류/타임아웃 분류, 점수 키별 통계(임의 `scores` 키에 대한 개수/평균/최소/최대/p50), 시간 버킷 타임라인. `/evaluations`와 **동일한 필터 파라미터**에 추가로 `featured_keys`(트렌드를 볼 점수 키의 CSV)와 `latest_per_session`을 허용합니다. 대시보드 기능을 지원합니다; 메트릭은 샘플링되지 않고 전체 일치 집합에 대해 정확하게 계산됩니다. | | `GET` | `/evaluations/environments` | `evaluations:read` | `evaluations` 테이블의 고유한 환경 값. 평가 읽기 가능 데이터로 범위가 지정된 필터 드롭다운을 채우는 데 사용됩니다. | -| `GET` | `/evaluation-jobs` | `evaluations:read` | 진행 중인 평가에 대한 가시성. `status` (`pending`/`polling`)로 필터링합니다. | -| `GET` | `/events` | `events:read` | 세션의 원시 이벤트 스트리밍. `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit`, `order`를 지원합니다. `order`는 `desc`(최신순, 기본값) 또는 `asc`(오래된 순)이며; 인식할 수 없는 값은 `desc`로 대체됩니다. 응답의 `next_cursor`(이벤트 id)를 통해 커서 페이지네이션: 다음 페이지를 가져오려면 `cursor`로 다시 전달하세요; `asc`의 경우 다음 페이지는 해당 id 이후의 이벤트이고, `desc`의 경우 그 이전의 이벤트입니다. `limit` 기본값은 50이며 최대 1000으로 제한됩니다. | -| `GET` | `/sessions/:session_id/export` | `events:read` | 이 세션에 대해 평가자가 받을 정확한 JSON 바디를 `session-.json`이라는 이름의 다운로드 가능한 첨부 파일로 반환합니다. 오프라인 테스트를 위해 프로덕션 세션을 `agenteye-evaluator`로 재현하는 데 유용합니다. 바이트는 평가자 파이프라인이 전송하는 것과 바이트 단위로 동일합니다. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | 세션에 대한 새로운 평가를 큐에 추가합니다; 이전 평가 존재 여부와 관계없이 실행됩니다. 새 결과는 이전 결과를 덮어쓰는 것이 아니라 세션의 평가 타임라인에 **추가**되므로, 이전 점수는 기록으로 계속 표시됩니다. 큐에 추가되면 `202`를 반환하고, 알 수 없는 세션이면 `404`, 평가가 이미 진행 중이면 `409`를 반환합니다. 새 평가자를 배포한 후 또는 `agent_end`를 전송하지 않은 세션에 사용합니다. | +| `GET` | `/evaluation-jobs` | `evaluations:read` | 진행 중인 평가에 대한 가시성. `status`(`pending`/`polling`)로 필터링합니다. | +| `GET` | `/events` | `events:read` | 세션의 원시 이벤트를 스트리밍합니다. `session_id`, `agent_id`, `event_type`(CSV), `environment`(CSV), `ts_from`, `ts_to`, `cursor`, `limit`, `order`를 지원합니다. `order`는 `desc`(최신 순, 기본값) 또는 `asc`(오래된 순)이며; 인식되지 않는 값은 `desc`로 폴백합니다. 응답의 `next_cursor`(이벤트 id)를 통해 커서 페이지네이션: `cursor`로 전달하면 다음 페이지를 얻습니다; `asc`의 경우 해당 id 이후의 이벤트, `desc`의 경우 그 이전의 이벤트입니다. `limit`의 기본값은 50이며 최대 1000으로 제한됩니다. | +| `GET` | `/sessions/:session_id/export` | `events:read` | 이 세션에 대해 평가자가 받을 정확한 JSON 본문을 `session-.json`이라는 이름의 다운로드 가능한 첨부 파일로 반환합니다. 오프라인 테스트를 위해 프로덕션 세션을 `agenteye-evaluator`로 재현하는 데 유용합니다. 바이트는 평가자 파이프라인이 전송하는 것과 동일합니다. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | 세션에 대한 새로운 평가를 대기열에 추가합니다; 이전 평가 존재 여부와 관계없이 실행됩니다. 새 결과는 이전 결과를 덮어쓰는 것이 아니라 세션의 평가 타임라인에 **추가**되므로 이전 점수가 기록으로 남습니다. 대기열 추가 시 `202`를 반환하고, 알 수 없는 세션의 경우 `404`, 평가가 이미 진행 중인 경우 `409`를 반환합니다. 새 평가자를 배포한 후 또는 `agent_end`를 발생시키지 않은 세션에 사용하세요. | ### 점수 범위로 필터링: `score_filters` -`GET /evaluations`는 `scores` 객체 내부의 숫자 값으로 결과를 좁히는 선택적 `score_filters` 파라미터를 허용합니다. 이 파라미터는 `key:min..max` 항목의 쉼표로 구분된 목록입니다; 어느 쪽 경계도 생략할 수 있습니다. 여러 항목은 논리 AND로 결합됩니다. 명명된 키가 없거나 숫자가 아닌 행은 제외됩니다. 요청에는 최대 20개의 필터 항목이 포함될 수 있으며, 이를 초과하면 HTTP 400이 반환됩니다. +`GET /evaluations`는 `scores` 객체 내의 숫자 값으로 결과를 좁히는 선택적 +`score_filters` 파라미터를 허용합니다. 이 파라미터는 `key:min..max` 항목의 +쉼표로 구분된 목록이며; 어느 쪽 경계도 생략할 수 있습니다. 여러 항목은 논리적 AND로 +결합됩니다. 지정된 키가 없거나 숫자가 아닌 행은 제외됩니다. 요청당 최대 20개의 +필터 항목을 포함할 수 있으며; 초과하면 HTTP 400이 반환됩니다. 예시: ```text @@ -219,32 +272,32 @@ GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. 각 `/evaluations` 응답 객체에는 다음 필드가 있습니다: -| 필드 | 타입 | 참고 | +| 필드 | 타입 | 비고 | |---|---|---| -| `evaluation_id` | string (UUID) | 이 최종 평가의 정규 식별자. 각 최종 평가는 새로운 UUID를 받으며; 단일 세션은 여러 개를 가질 수 있습니다. | +| `evaluation_id` | string (UUID) | 이 최종 평가의 표준 식별자. 각 최종 평가는 새로운 UUID를 받습니다; 단일 세션은 여러 개를 가질 수 있습니다. | | `id` | string (UUID) | `evaluation_id`와 동일한 값을 가지는 하위 호환성 별칭. | | `session_id` | string | 이 평가가 실행된 세션. 세션은 타임라인에 여러 평가를 가질 수 있습니다. | | `agent_id` | string | 세션을 생성한 에이전트를 식별합니다. | | `environment` | string | 세션에서 복사된 환경 레이블. | | `status` | enum | `"done"`, `"error"`, `"timeout"` 중 하나. | | `scores` | object \| null | 평가자가 반환한 점수. | -| `reasoning` | object \| null | 평가자가 반환한 선택적 점수별 근거 맵. 키는 일반적으로 `scores`의 키와 일치합니다. 대시보드는 각 항목을 점수 바 아래에 렌더링합니다. | +| `reasoning` | object \| null | 평가자가 반환한 선택적 점수별 근거 맵. 키는 일반적으로 `scores`의 키를 반영합니다. 대시보드는 각 항목을 해당 점수 바 아래에 렌더링합니다. | | `summary` | string \| null | 평가자가 반환한 선택적 전체 단락 서술. 대시보드는 이를 점수별 분류 위에 평가의 헤드라인으로 렌더링합니다. | -| `error` | string \| null | `"error"` / `"timeout"`일 때만 채워집니다. | -| `attempt_count` | integer | 디스패치 시도 횟수 (≥ 1). | -| `duration_ms` | integer \| null | 마지막 시도의 지속 시간. | -| `completed_at` | string (ISO 8601 UTC) | 최종 결과가 기록된 시간. 결과는 `completed_at` 기준으로 정렬됩니다(최신순). | -| `created_at` | string (ISO 8601 UTC) | `completed_at`과 동일한 타임스탬프를 가집니다(쓰기 1회 시맨틱). | +| `error` | string \| null | `"error"` / `"timeout"` 시에만 채워집니다. | +| `attempt_count` | integer | 디스패치 시도 횟수(≥ 1). | +| `duration_ms` | integer \| null | 최종 시도의 지속 시간. | +| `completed_at` | string (ISO 8601 UTC) | 최종 결과가 기록된 시간. 결과는 `completed_at` 기준으로 정렬됩니다(최신 순). | +| `created_at` | string (ISO 8601 UTC) | `completed_at`과 동일한 타임스탬프(쓰기 일회성 의미론). | --- ## 권한 -| 권한 | 부여 대상 | +| 권한 | 부여 내용 | |---|---| | `evaluations:read` | 평가 결과 목록 조회, 대시보드에서 점수 보기, 대시보드 상태 메트릭 로드. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` 또는 대시보드의 재평가 버튼을 통해 세션에 대한 평가를 수동으로 큐에 추가. | -| `dashboards:read` | 저장된 대시보드 보기 (메트릭을 로드하려면 `evaluations:read`도 필요). | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` 또는 대시보드의 재평가 버튼을 통해 세션에 대한 평가를 수동으로 대기열에 추가. | +| `dashboards:read` | 저장된 대시보드 보기(메트릭 로드를 위해 `evaluations:read`도 필요). | | `dashboards:write` | 대시보드 생성 및 편집. | | `dashboards:delete` | 대시보드 삭제. | @@ -254,50 +307,80 @@ GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ## 결과 보기 -- **`/sessions/`**: 이벤트 타임라인 + 세션의 점수와 디스패치 시도 오류를 보여주는 오른쪽 패널. 키에 `evaluations:trigger` 권한이 있으면 내보내기 버튼 옆에 **재평가** 버튼이 나타나며, `agent_end`를 전송하지 않은 세션이나 새 평가자를 배포한 후 점수를 새로 고칠 때 유용합니다. 대시보드는 새 결과를 폴링하고 결과가 도착하면 오른쪽 패널을 업데이트합니다. -- **`/sessions`**: 필터링 가능한 세션 그리드; 점수 열에는 각 세션의 평가 상태와 점수가 한눈에 표시됩니다. -- **`/dashboards`**: 저장된 평가 상태 뷰(아래 [대시보드](#dashboards) 참조). +- **`/sessions/`**: 이벤트 타임라인 + 세션의 점수와 디스패치 시도 오류를 보여주는 오른쪽 레일. 키에 + `evaluations:trigger` 권한이 있으면 내보내기 버튼 옆에 **재평가** 버튼이 나타납니다. `agent_end`를 발생시키지 않은 세션이나 + 새 평가자 배포 후 점수를 새로고침하는 데 유용합니다. 대시보드는 새 결과를 폴링하고 + 도착하면 오른쪽 레일을 업데이트합니다. +- **`/sessions`**: 필터 가능한 세션 그리드; 점수 열은 각 세션의 평가 상태와 점수를 한눈에 보여줍니다. +- **`/dashboards`**: 저장된 평가 상태 보기(아래 [대시보드](#dashboards) 참조). -![세션별 평가 상태 필과 색상으로 구분된 점수 배지(helpfulness, factuality, tool_efficiency, safety, coherence)가 있는 세션 그리드](/agenteye/images/sessions-list.png) +![세션별 평가 상태 피l과 색상 코딩된 점수 배지(helpfulness, factuality, tool_efficiency, safety, coherence)가 있는 세션 그리드](/agenteye/images/sessions-list.png) -*세션 그리드는 각 실행의 평가 상태와 점수를 한눈에 보여줍니다; 빨간색/주황색/녹색 배지로 낮은 점수가 눈에 띄게 표시됩니다.* +*세션 그리드는 각 실행의 평가 상태와 점수를 한눈에 보여줍니다; 빨간색/노란색/녹색 배지로 낮은 점수가 눈에 띕니다.* --- ## 대시보드 -**대시보드** 페이지(`/dashboards`)를 통해 평가 필터 조합을 이름이 지정된 재사용 가능한 뷰로 저장하고 해당 평가 슬라이스의 상태를 한눈에 모니터링할 수 있습니다. 대시보드는 **조직 전체에서 공유**됩니다; `dashboards:read` 권한이 있는 모든 사람이 동일한 세트를 볼 수 있습니다. +**대시보드** 페이지(`/dashboards`)에서는 평가 필터 조합을 이름이 있는 재사용 가능한 +보기로 저장하고 해당 평가 슬라이스의 상태를 한눈에 모니터링할 수 있습니다. +대시보드는 **전체 조직에서 공유됩니다**; `dashboards:read` 권한이 있는 모든 사람이 +동일한 세트를 봅니다. -각 대시보드에는 다음이 고정됩니다: +각 대시보드는 다음을 고정합니다: -- **필터**: 세션 페이지와 동일한 컨트롤: 환경, 상태, 에이전트, 롤링 시간 창, 점수 범위 필터(`key:min..max`). -- **표시 구성**: 특성화할 점수 키, 녹색/주황색/빨간색 상태 임계값, 표시할 패널, 세션별 최신 평가로 축소할지 여부. +- **필터**: 세션 페이지와 동일한 컨트롤: 환경, 상태, + 에이전트, 롤링 시간 창, 점수 범위 필터(`key:min..max`). +- **표시 구성**: 표시할 점수 키, 녹색/노란색/빨간색 상태 임계값, + 표시할 패널, 세션당 최신 평가로 축소 여부. -각 카드에는 일치하는 세션 수, 완료/오류/타임아웃 분류, 각 특성화된 점수의 평균, 소형 추세 스파크라인이 표시됩니다. 대시보드를 열면 전체 크기 패널이 표시되며; **"세션에서 열기"**를 누르면 정확히 해당 슬라이스로 미리 필터링된 세션 페이지로 이동합니다. 메트릭은 전체 일치 집합에 대해 서버 측에서 계산됩니다(`GET /evaluations/aggregate` 사용), 따라서 숫자는 샘플링이 아닌 정확한 값입니다. +각 카드는 일치하는 세션 수, 완료/오류/타임아웃 분류, +각 주요 점수의 평균, 작은 트렌드 스파크라인을 보여줍니다. 대시보드를 열면 +전체 크기 패널이 표시됩니다; **"세션에서 열기"**를 클릭하면 해당 슬라이스로 +정확히 사전 필터링된 세션 페이지로 이동합니다. 메트릭은 전체 일치 집합에 대해 +서버 측에서 계산됩니다(`GET /evaluations/aggregate`를 통해), 따라서 숫자는 +샘플링이 아닌 정확한 값입니다. -![평가자 차원별 평균 점수 바, 도구 성공/오류 분류, 상위 도구, 시간당 이벤트 추세가 있는 평가 상태 대시보드](/agenteye/images/dashboard-quality.png) +![평가자 항목별 평균 점수 바, 도구 성공/오류 분류, 상위 도구, 시간당 이벤트 트렌드가 있는 평가 상태 대시보드](/agenteye/images/dashboard-quality.png) -**권한:** 보기에는 `dashboards:read`와 `evaluations:read` 모두 필요합니다; 생성 및 편집에는 `dashboards:write`가 필요합니다; 삭제에는 `dashboards:delete`가 필요합니다. 부트스트랩 관리자는 이 모든 권한을 자동으로 받습니다. +**권한:** 보기에는 `dashboards:read`와 `evaluations:read` 모두 필요합니다; +생성 및 편집에는 `dashboards:write` 필요; 삭제에는 `dashboards:delete` 필요. +부트스트랩 관리자는 이 모두를 자동으로 받습니다. --- ## 문제 해결 -**세션은 존재하지만 평가가 생성되지 않습니다.** 서버 프로세스에 `EVALUATOR_ENDPOINT`가 설정되어 있는지, 서버와 평가자가 동일한 `EVALUATOR_TOKEN` 값을 공유하는지, 평가자의 `/health` 엔드포인트가 서버에서 접근 가능한지 확인하세요. `EVALUATOR_ENDPOINT`가 설정되지 않으면 파이프라인은 아무런 동작도 하지 않습니다. +**세션은 있지만 평가가 생성되지 않습니다.** 서버 프로세스에 `EVALUATOR_ENDPOINT`가 +설정되어 있는지, 서버와 평가자가 동일한 `EVALUATOR_TOKEN` 값을 공유하는지, +평가자의 `/health` 엔드포인트가 서버에서 접근 가능한지 확인하세요. +`EVALUATOR_ENDPOINT`가 설정되지 않으면 파이프라인은 no-op 상태입니다. -**진행 중인 평가가 쌓입니다.** `GET /evaluation-jobs`를 조회하여 진행 중인 큐를 확인하세요. 각 행의 `attempt_count`, `next_attempt_at`, `last_error`를 검사하세요. 일반적인 원인: 평가자 서비스에 접근할 수 없거나 5xx를 반환하는 경우(백오프로 재시도), 잘못된 `EVALUATOR_TOKEN`(401은 최종 오류), 또는 무기한 `pending`을 반환하는 비동기 평가자(아래 참조). +**진행 중인 평가가 쌓입니다.** `GET /evaluation-jobs`를 조회하여 진행 중인 대기열을 확인하세요. +각 행의 `attempt_count`, `next_attempt_at`, `last_error`를 검사하세요. 일반적인 +원인: 평가자 서비스에 접근할 수 없거나 5xx를 반환하는 경우(백오프로 재시도), +잘못된 `EVALUATOR_TOKEN`(401은 최종 오류), 또는 `pending`을 무한정 반환하는 +비동기 평가자(아래 참조). -**세션이 완료되었지만 최종 평가가 없습니다.** `GET /evaluation-jobs?status=polling`을 조회하세요; 결과가 아직 진행 중일 수 있습니다. 작업이 `pending` 상태에 멈춰 있으면 서버가 평가자에 접근하는 데 문제가 있는 것입니다; 평가자가 실행 중이고 `EVALUATOR_TOKEN`이 일치하는지 확인하세요. +**세션이 완료되었지만 최종 평가가 없습니다.** `GET /evaluation-jobs?status=polling`을 +조회하세요; 결과가 아직 진행 중일 수 있습니다. 작업이 `pending`에 멈춰 있다면, +서버가 평가자에 접근하는 데 문제가 있는 것입니다; 평가자가 실행 중인지, +`EVALUATOR_TOKEN`이 일치하는지 확인하세요. -**`HTTP 401 from evaluator: invalid bearer token`.** 서버의 `EVALUATOR_TOKEN`이 평가자 서비스에 구성된 값과 일치하지 않습니다. 두 값이 동일해야 합니다. +**`HTTP 401 from evaluator: invalid bearer token`.** 서버의 `EVALUATOR_TOKEN`이 +평가자 서비스에 구성된 값과 일치하지 않습니다. 두 값이 동일해야 합니다. -**비동기 평가자가 계속 `pending`을 반환합니다.** 서버는 평가자가 `done` 또는 `error`를 반환하거나 `EVALUATOR_MAX_POLL_DURATION_SECS`(기본값 1시간)가 경과할 때까지 `GET /evaluate/{job_id}`를 폴링합니다. 제한에 도달하면 평가는 `timeout`으로 기록되고 진행 중인 큐에서 제거됩니다. 평가자가 기본값보다 더 긴 시간이 실제로 필요한 경우 `EVALUATOR_MAX_POLL_DURATION_SECS`를 늘리세요. +**비동기 평가자가 계속 `pending`을 반환합니다.** 서버는 평가자가 `done` 또는 +`error`를 반환하거나 `EVALUATOR_MAX_POLL_DURATION_SECS`(기본값 1시간)가 경과할 때까지 +`GET /evaluate/{job_id}`를 폴링합니다. 제한에 도달하면 평가는 `timeout`으로 기록되고 +진행 중인 대기열에서 제거됩니다. 평가자가 합법적으로 기본값보다 더 오래 필요한 경우 +`EVALUATOR_MAX_POLL_DURATION_SECS`를 늘리세요. --- ## 다음 단계 -- [평가자 에이전트 스킬](/ko/agenteye/evaluator-skill): 코딩 에이전트가 실제 세션을 바탕으로 차원을 설계하고 이 서비스를 구축하도록 합니다. -- [Python SDK](/ko/agenteye/python-sdk): 점수화를 트리거하는 `agent_end` 이벤트를 전송합니다. -- [API 키](/ko/agenteye/api-keys): `evaluations:read` 및 `evaluations:trigger` 권한. -- [감사](/ko/agenteye/audits): 정책 기반 검토를 위한 Observability의 또 다른 자동화된 품질 기능. \ No newline at end of file +- [평가자 에이전트 스킬](/ko/agenteye/evaluator-skill): 코딩 에이전트가 실제 세션을 기반으로 평가 항목을 설계하고 이 서비스를 구축하도록 합니다. +- [Python SDK](/ko/agenteye/python-sdk): 채점을 트리거하는 `agent_end` 이벤트를 발생시킵니다. +- [API 키](/ko/agenteye/api-keys): `evaluations:read`와 `evaluations:trigger` 권한. +- [감사](/ko/agenteye/audits): 정책 기반 검토를 위한 Observability의 다른 자동화된 품질 기능. \ No newline at end of file diff --git a/docs/ko/agenteye/evaluations.mdx b/docs/ko/agenteye/evaluations.mdx index a06a2bf8..0bdc7fdf 100644 --- a/docs/ko/agenteye/evaluations.mdx +++ b/docs/ko/agenteye/evaluations.mdx @@ -1,50 +1,50 @@ --- title: "평가(Evaluations)" -description: "품질 문제가 사용자 불만으로 접수되기 전에 먼저 알 수 있습니다." +description: "품질 문제가 이제 사용자 불만으로 듣기 전에 먼저 찾아옵니다." --- -품질 문제가 사용자 불만으로 접수되기 전에 먼저 알 수 있습니다. 자체 채점 서비스를 한 번만 연결하면 Failproof AI Observability가 완료된 모든 실행을 자동으로 평가합니다. 따라서 유용성 저하나 환각 급증이 고객이 느끼기 전에 자동으로 표시됩니다. +품질 문제가 이제 사용자 불만으로 듣기 전에 먼저 찾아옵니다. 자체 채점 서비스를 한 번만 연결하면 Failproof AI Observability가 완료된 모든 실행을 자동으로 평가합니다. 이제 고객이 문제를 느끼기 전에 유용성 저하나 환각 급증이 스스로 드러납니다. -![점수 열이 있는 세션 그리드: 각 실행에 평가 상태 배지와 유용성, 사실성, 도구 효율성에 대한 색상 코딩 배지가 표시됩니다](/agenteye/images/sessions-list.png) +![점수 열이 있는 세션 그리드: 각 실행에 평가 상태 표시와 색상으로 구분된 유용성, 사실성, 도구 효율성 배지가 표시됩니다](/agenteye/images/sessions-list.png) -*세션 그리드의 모든 실행에 점수가 표시되며, 빨간색·황색·녹색 배지 덕분에 트랜스크립트를 하나도 열지 않아도 문제 있는 실행이 바로 눈에 띕니다.* +*세션 그리드의 모든 실행에 점수가 표시됩니다. 빨강, 주황, 초록 배지 덕분에 트랜스크립트를 하나도 열지 않고도 낮은 점수의 실행이 바로 눈에 띕니다.* ## 수동 샘플링 중단 -이전에는 일부 실행만 무작위로 점검하며 나머지도 괜찮을 거라 기대했을 것입니다. 이제는 완료된 모든 세션이 종료되는 즉시 원하는 기준, 즉 유용성·도구 효율성·사실성·안전성 등 여러분의 품질 기준에 따라 자동으로 채점됩니다. 점수 키는 여러분이 직접 정의하고, Failproof AI Observability는 평가기가 반환하는 모든 값을 저장·추적·표시합니다. 채점되지 않고 넘어가는 실행은 없으며, 지원 티켓을 통해 회귀를 뒤늦게 파악하는 일도 없어집니다. +예전에는 몇 개의 실행만 발췌 점검하고 나머지는 괜찮으리라 희망했습니다. 이제는 완료된 모든 세션이 끝나는 즉시, 유용성·도구 효율성·사실성·안전성 등 여러분이 중요하게 생각하는 기준으로 채점됩니다. 점수 키는 여러분이 정의하고, Failproof AI Observability는 평가기가 돌려보낸 값을 저장·추이 분석·표시합니다. 채점을 빠져나가는 실행은 없으며, 지원 티켓으로 회귀를 알게 되는 일도 사라집니다. -점수는 **`//sessions`**(사이드바 → *observe* → *sessions*)의 세션 그리드에 행마다 배지 묶음으로 표시됩니다. 기준에 미달한 실행만 보고 싶다면 점수 범위로 그리드를 필터링하세요. 예를 들어 유용성 0.5 미만으로 필터링하면 검토할 가치가 있는 실행만 정확히 불러올 수 있습니다. 점수 조회에는 `evaluations:read` 권한이 필요합니다. +점수는 **`//sessions`**(사이드바 → *observe* → *sessions*)의 세션 그리드에 함께 표시되며, 행마다 배지 묶음이 하나씩 붙습니다. 기준 미달 실행만 보고 싶다면 점수 범위로 그리드를 필터링하세요. 예를 들어 유용성이 0.5 미만인 실행만 골라 꼭 읽어야 할 실행만 확인할 수 있습니다. 점수 조회에는 `evaluations:read` 권한이 필요합니다. ## 낮은 점수의 원인 파악 -숫자는 실행이 부진했음을 알려주고, 세션 페이지는 그 이유를 알려줍니다. 실행을 열면 오른쪽 패널 상단에 핵심 요약이 나타나고, 각 항목별로 평가기가 제공한 근거와 함께 막대 그래프가 표시됩니다. 덕분에 "사실성 점수가 0.4"에서 "어떤 주장이 틀렸는지"까지 몇 초 만에 확인할 수 있습니다. +숫자는 실행이 부족했다는 사실만 알려주지만, 세션 페이지는 그 이유를 알려줍니다. 실행을 열면 오른쪽 패널 상단에 헤드라인 요약이 표시되고, 각 기준별 막대와 함께 평가기가 제공한 근거가 바로 아래에 표시됩니다. "사실성 점수가 0.4였다"는 정보에서 정확히 어떤 주장이 틀렸는지까지 몇 초 만에 파악할 수 있습니다. -![세션 오른쪽 패널: 상단에 평가 요약, 그 아래에 항목별 점수 막대와 근거 설명이 전체 이벤트 타임라인 옆에 표시됩니다](/agenteye/images/session-detail.png) +![세션의 오른쪽 패널: 상단의 평가 요약, 각 기준별 점수 막대와 근거 한 줄, 전체 이벤트 타임라인이 나란히 표시됩니다](/agenteye/images/session-detail.png) -*세션 상세 보기: 요약, 항목별 점수 막대, 각 점수의 근거가 실행 이벤트 타임라인 바로 옆에 표시됩니다.* +*세션 상세 보기: 요약, 기준별 점수 막대, 각 점수 뒤의 근거가 실행의 이벤트 타임라인 바로 옆에 표시됩니다.* -더 정밀한 평가기를 배포했거나, 채점 전에 중단된 실행을 다시 확인해야 한다면? **재평가(re-evaluate)** 버튼(`evaluations:trigger` 권한 필요)을 사용하면 세션을 즉시 재채점하고 최신 결과를 타임라인에 추가합니다. 이전 점수는 기록으로 계속 확인할 수 있습니다. **`//sessions/`**에서 찾을 수 있습니다. +더 정교한 평가기를 배포했거나, 채점 전에 중단된 실행을 확인하고 싶다면 **재평가** 버튼(`evaluations:trigger` 권한 필요)을 사용하세요. 세션을 제자리에서 다시 채점하고 최신 결과를 타임라인에 추가하므로, 이전 점수도 기록으로 계속 볼 수 있습니다. **`//sessions/`**에서 찾을 수 있습니다. -## 전체 플릿의 품질 추세 모니터링 +## 전체 품질 추이 모니터링 -실행 하나의 낮은 점수는 노이즈일 수 있지만, 전체 코호트가 하락하면 명확한 신호입니다. 저장된 대시보드는 점수를 한눈에 파악할 수 있는 추세로 변환해줍니다. 에이전트별·환경별로 이번 주와 지난주의 평균 유용성을 비교할 수 있습니다. +한 실행의 낮은 점수는 노이즈이지만, 전체 코호트의 하락은 신호입니다. 저장된 대시보드는 점수를 한눈에 볼 수 있는 추이로 변환합니다. 에이전트별·환경별로 이번 주와 지난주의 평균 유용성을 비교할 수 있습니다. -![품질 대시보드: 평가 항목별 평균 점수 막대와 시간에 따른 추세 그래프](/agenteye/images/dashboard-quality.png) +![품질 대시보드: 평가 기준별 평균 점수 막대와 시간에 따른 추이가 표시됩니다](/agenteye/images/dashboard-quality.png) -*저장된 품질 대시보드는 주요 점수 키의 추세를 보여주므로, 서서히 하락하는 추세가 장애로 번지기 훨씬 전에 명확하게 인지할 수 있습니다.* +*저장된 품질 대시보드는 주요 점수 키의 추이를 보여주므로, 인시던트가 되기 훨씬 전에 느린 드리프트를 명확히 인식할 수 있습니다.* -대시보드는 **`//dashboards`**(사이드바 → *analyze* → *dashboards*)에 위치하며 조직 전체가 공유합니다. 각 카드는 관련 세션을 집계하여 세션 수, 각 주요 점수의 평균, 추세 스파크라인을 표시합니다. "세션에서 열기"를 클릭하면 해당 숫자의 기반이 되는 사전 필터링된 실행으로 바로 이동합니다. 조회에는 `dashboards:read` 및 `evaluations:read` 권한이 필요합니다. +대시보드는 **`//dashboards`**(사이드바 → *analyze* → *dashboards*)에 있으며 조직 전체에 공유됩니다. 각 카드는 매칭되는 세션 수, 주요 점수 각각의 평균, 추이 스파크라인을 집계합니다. "Open in sessions"를 클릭하면 해당 숫자 뒤의 사전 필터링된 실행으로 바로 이동합니다. 조회에는 `dashboards:read`와 `evaluations:read`가 모두 필요합니다. ## 평가기 한 번만 연결하기 -채점은 옵트인 방식이며, Failproof AI Observability에 채점기를 연결하기 전까지는 완전히 비활성화 상태입니다. 소형 HTTP 서비스를 하나 실행하고(Observability에서 복사할 수 있는 참조 구현을 제공합니다), 서버에 두 가지 값을 설정하면 이후 모든 실행이 자동으로 채점됩니다. 전체 안내, 채점 계약, SDK는 상세 가이드에서 확인할 수 있습니다. +채점은 선택 사항이며, Failproof AI Observability에 채점기를 지정하기 전까지는 완전히 비활성 상태입니다. 소형 HTTP 서비스를 하나 구성하고(Observability가 복사할 수 있는 참조 구현을 제공합니다), 서버에 값 두 개를 설정하면 이후 모든 실행이 자동으로 채점됩니다. 전체 안내, 채점 계약, SDK는 심화 가이드에 있습니다. -어떤 항목을 채점해야 할지 모르겠다면? [평가기 에이전트 스킬](/ko/agenteye/evaluator-skill)을 사용하면 코딩 에이전트가 여러분의 세션을 분석해 점수 항목을 결정하고 서비스를 빌드·배포합니다. +어떤 기준을 채점할지 잘 모르겠다면, [evaluator agent skill](/ko/agenteye/evaluator-skill)을 활용하여 코딩 에이전트가 여러분의 세션을 기반으로 점수 기준을 결정하고 서비스를 빌드·배포하도록 할 수 있습니다. ## 관련 문서 -- [평가 suite](/ko/agenteye/evaluation-suite): 평가기 연결, 채점 계약, SDK. -- [평가기 에이전트 스킬](/ko/agenteye/evaluator-skill): 코딩 에이전트가 점수 항목을 선택하고 평가기를 빌드합니다. +- [Evaluation suite](/ko/agenteye/evaluation-suite): 평가기 연결, 채점 계약, SDK. +- [Evaluator agent skill](/ko/agenteye/evaluator-skill): 코딩 에이전트가 점수 기준을 선정하고 평가기를 빌드하도록 합니다. - [Sessions](/ko/agenteye/sessions): 점수가 표시되는 실행별 그리드. -- [Dashboards](/ko/agenteye/dashboards): 조직 전체의 품질 추세를 저장하고 공유합니다. +- [Dashboards](/ko/agenteye/dashboards): 조직 전체의 품질 추이를 저장하고 공유합니다. - [Audits](/ko/agenteye/audits): 세션 간 조사를 위한 Observability의 또 다른 자동 품질 기능. \ No newline at end of file diff --git a/docs/ko/agenteye/evaluator-skill.mdx b/docs/ko/agenteye/evaluator-skill.mdx index 859070d7..79dac557 100644 --- a/docs/ko/agenteye/evaluator-skill.mdx +++ b/docs/ko/agenteye/evaluator-skill.mdx @@ -1,78 +1,78 @@ --- title: "Failproof AI Observability 평가자 에이전트 스킬" -description: "코딩 에이전트가 설계와 구현을 모두 담당하여, '에이전트 품질이 가끔 떨어지는 것 같다'는 막연한 생각을 실제 배포된 스코어링 서비스로 만들어 드립니다." +description: "코딩 에이전트가 설계와 구현을 모두 담당하여 '에이전트가 가끔 이상한 것 같다'는 막연한 의심을 배포된 스코어링 서비스로 전환합니다." --- -코딩 에이전트가 설계와 구현을 모두 담당하여, *"에이전트 품질이 가끔 떨어지는 것 같다"* 는 막연한 생각을 실제 배포된 스코어링 서비스로 만들어 드립니다. **Failproof AI Observability 평가자 스킬** (`agenteye-evaluator`)은 *Agent Skill*입니다. Claude Code나 Codex 같은 코딩 에이전트가 필요할 때 불러오는 소규모 지침 폴더로, 에이전트에게 *여러분의* 에이전트에서 추적할 가치가 있는 품질 지표를 파악하고, 그 지표를 평가하는 [평가자 서비스](/ko/agenteye/evaluation-suite)를 작성·테스트·배포하는 방법을 가르칩니다. +코딩 에이전트가 설계와 구현을 모두 담당하여 *"에이전트가 가끔 이상한 것 같다"*는 막연한 의심을 배포된 스코어링 서비스로 전환합니다. **Failproof AI Observability 평가자 스킬** (`agenteye-evaluator`)은 *에이전트 스킬*입니다. Claude Code나 Codex 같은 코딩 에이전트가 필요할 때 불러오는 소규모 명령 폴더로, 에이전트가 *여러분의* 에이전트에서 추적할 만한 품질 기준을 스스로 파악하고, 그 기준을 점수로 매기는 [평가자 서비스](/ko/agenteye/evaluation-suite)를 작성·테스트·배포하도록 가르칩니다. -이 스킬은 호스팅된 스코어러도, 업로드 레지스트리도, 플러그인 시스템도 **아닙니다**. 여러분의 평가자는 [Evaluation suite](/ko/agenteye/evaluation-suite) 가이드에 설명된 대로, 여러분의 인프라에서 운영되는 HTTP 서비스로 완전히 여러분의 소유입니다. 이 스킬은 에이전트가 그것을 잘 만들 수 있도록 가르칠 뿐이며, 스킬이 하는 모든 작업은 여러분이 직접 동일한 코드를 작성해서도 할 수 있습니다. +이 스킬은 호스팅된 스코어러도, 업로드 레지스트리도, 플러그인 시스템도 **아닙니다**. [평가 스위트](/ko/agenteye/evaluation-suite) 가이드에서 설명하는 것처럼 평가자는 여러분 자신의 인프라에서 실행되는 HTTP 서비스로 온전히 여러분의 것입니다. 스킬은 단지 에이전트가 그것을 잘 구축하도록 가르칠 뿐이므로, 에이전트가 하는 모든 것은 여러분이 직접 같은 코드를 작성해도 할 수 있습니다. --- -## 가장 어려운 부분은 무엇을 평가할지 결정하는 것입니다 +## 가장 어려운 부분은 무엇을 점수로 매길지 결정하는 것입니다 -SDK 인터페이스는 간단합니다 — 데코레이터 하나와 모델 두 개 — 그리고 에이전트는 [계약](/ko/agenteye/evaluation-suite#http-contract)만으로도 이를 작성할 수 있습니다. 평가자가 실패하는 원인은 거기에 있지 않습니다. 실패의 원인은 잘못된 것을 측정하기 때문입니다. 잘못된 것을 측정하는 평가자는 없는 것보다 나쁩니다. 모두가 무시하게 되는 대시보드를 만들어낼 뿐입니다. +SDK 인터페이스는 작습니다 — 데코레이터 하나와 두 개의 모델 — 그리고 에이전트는 [계약](/ko/agenteye/evaluation-suite#http-contract)만으로도 이를 작성할 수 있습니다. 문제는 거기에 있지 않습니다. 평가자는 잘못된 것을 측정할 때 실패하며, 잘못된 것을 측정하는 평가자는 없는 것보다 나쁩니다. 모두가 무시하게 되는 대시보드만 만들어냅니다. -그래서 이 스킬의 대부분은 코드가 작성되기 전 단계에 할애됩니다. 스킬은 에이전트가 여러분을 인터뷰하도록 합니다(*"잘 동작한 실행을 설명해 주세요. 이제 잘못된 실행을 설명해 주세요"*). 그런 다음 [`agenteye` CLI](/ko/agenteye/cli)를 통해 실제 세션을 가져와 처음부터 끝까지 읽습니다. 이 두 가지는 대개 서로 다른 그림을 보여주는데, 그 차이가 핵심입니다: 여러분이 측정하려는 것과 실제 트랜스크립트에서 지원 가능한 것 사이의 간극입니다. 이벤트에서 **계산 가능**하고 **변별력이 있는** 경우에만 지표로 살아남습니다 — 좋은 실행과 나쁜 실행 모두에서 0.9를 기록한다면, 아무것도 알려주지 못하므로 제외됩니다. +그래서 스킬의 대부분은 코드가 작성되기 전 단계에 집중합니다. 스킬은 에이전트가 여러분을 인터뷰하도록 합니다(*"잘 된 실행을 설명해주세요; 이번엔 잘못된 것도요"*), 그런 다음 [`agenteye` CLI](/ko/agenteye/cli)를 통해 실제 세션을 가져와 처음부터 끝까지 읽습니다. 이 두 부분은 대개 일치하지 않으며, 그 간극이 핵심입니다. 즉, 여러분이 측정하려는 것과 실제 트랜스크립트가 지원할 수 있는 것 사이의 차이입니다. 이벤트에서 **계산 가능**하고 **변별력**이 있을 때만 기준이 살아남습니다 — 좋은 실행과 나쁜 실행 모두에서 0.9를 기록한다면 아무것도 알려주지 못하므로 제거됩니다. -결과물은 2~4개 지표와 그 근거가 담긴 제안서로, 코드 한 줄이 작성되기 전에 여러분의 승인을 받습니다. +결과물은 코드 한 줄 작성 전에 여러분이 승인할 수 있도록, 근거가 첨부된 2-4개 기준의 제안서입니다. ```mermaid flowchart TD - YOU["you: 'I want evals for my support bot'"] --> AGENT["coding agent (Claude Code / Codex)
loads the agenteye-evaluator skill"] - AGENT -->|"interview: what does good vs bad look like?"| YOU - AGENT -->|"agenteye --json sessions / events"| DATA["your real sessions
what actually happens"] - DATA --> DIMS["2-4 dimensions, you sign off"] - DIMS --> SVC["your evaluator service
agenteye-evaluator SDK"] - SVC --> SCORES["scores land in the dashboard
and agenteye evals"] + YOU["당신: '서포트 봇 평가를 원해'"] --> AGENT["코딩 에이전트 (Claude Code / Codex)
agenteye-evaluator 스킬 로드"] + AGENT -->|"인터뷰: 좋은 것과 나쁜 것은 어떤 모습인가?"| YOU + AGENT -->|"agenteye --json sessions / events"| DATA["실제 세션
실제로 일어난 일"] + DATA --> DIMS["2-4개 기준, 승인"] + DIMS --> SVC["평가자 서비스
agenteye-evaluator SDK"] + SVC --> SCORES["점수가 대시보드와
agenteye evals에 반영"] ``` --- ## 다른 평가 구성 요소와의 관계 -평가(scoring)를 다루는 문서는 네 가지이며, 순서대로 서로 연결됩니다: +점수화를 다루는 네 개의 문서가 있으며, 순서대로 연결됩니다: -| 페이지 | 내용 | 참조 시점 | +| 페이지 | 내용 | 참고 시점 | |---|---|---| -| **[Evaluations](/ko/agenteye/evaluations)** | 기능: 세션 그리드의 점수, 대시보드, 재평가 | 자동 평가가 무엇을 제공하는지 알고 싶을 때 | -| **[Evaluation suite](/ko/agenteye/evaluation-suite)** | HTTP 계약, SDK, 서버 환경 변수 | 직접 평가자를 구현하거나 디버깅할 때 | -| **평가자 스킬** (이 문서) | 스코어러 설계 *및* 구현을 위한 자연어 진입점 | "평가를 원한다"는 생각에서 실행 중인 서비스까지 가고 싶을 때 | -| **[CLI skill](/ko/agenteye/cli-skill)** | `agenteye` CLI를 위한 자연어 진입점 | 이미 보유한 점수를 *읽고* 싶을 때 | -| **[Python SDK skill](/ko/agenteye/python-sdk-skill)** | 에이전트 계측을 위한 자연어 진입점 | 에이전트가 아직 세션을 내보내지 않아 평가할 대상이 없을 때 | +| **[평가](/ko/agenteye/evaluations)** | 기능: 세션 그리드의 점수, 대시보드, 재평가 | 자동 점수화로 얻을 수 있는 것을 알고 싶을 때 | +| **[평가 스위트](/ko/agenteye/evaluation-suite)** | HTTP 계약, SDK, 서버 환경 변수 | 직접 평가자를 구현하거나 디버깅할 때 | +| **평가자 스킬** (이 문서) | 스코어러 설계 *및* 구축을 위한 자연어 진입점 | "평가를 원한다"에서 실행 중인 서비스까지 가고 싶을 때 | +| **[CLI 스킬](/ko/agenteye/cli-skill)** | `agenteye` CLI를 위한 자연어 진입점 | 이미 보유한 점수를 *읽고* 싶을 때 | +| **[Python SDK 스킬](/ko/agenteye/python-sdk-skill)** | 에이전트 계측을 위한 자연어 진입점 | 에이전트가 아직 세션을 내보내지 않아 점수화할 대상이 없을 때 | -### CLI 스킬 대비: 생성 vs 읽기 +### CLI 스킬과의 차이: 구축 vs 읽기 -두 스킬은 의도적으로 겹치지 않으며, 둘 다 설치하는 것이 일반적인 구성입니다 — 에이전트는 여러분의 요청에 따라 적절한 스킬을 선택합니다: +두 스킬은 의도적으로 겹치지 않으며, 둘 다 설치하는 것이 일반적인 설정입니다 — 에이전트는 요청 내용에 따라 적절한 스킬을 선택합니다: -- **`agenteye-evaluator`** (이 문서)는 점수를 *생성하는* 것을 구축합니다. 처음으로 점수가 생성되면 역할이 끝납니다. -- **[`agenteye-cli`](/ko/agenteye/cli-skill)** 는 이미 존재하는 점수를 읽습니다(`agenteye evals`). *"이번 주 품질이 떨어졌나요?"* 는 이 스킬이 답하는 질문이고, 이 문서의 스킬이 답하는 질문이 아닙니다. +- **`agenteye-evaluator`** (이 문서)는 점수를 *생성*하는 것을 구축합니다. 처음으로 점수가 반영될 때 역할이 끝납니다. +- **[`agenteye-cli`](/ko/agenteye/cli-skill)**는 이미 존재하는 점수를 읽습니다(`agenteye evals`). *"이번 주에 품질이 떨어졌나요?"*가 이 스킬의 질문이지, 이 스킬의 질문이 아닙니다. --- -## 사전 요구 사항 +## 사전 요건 -1. **`agenteye` CLI가 설치되고 로그인된 상태** (`pipx install agenteye`, 이후 `agenteye login`). 스킬은 두 가지 용도로 CLI를 사용합니다: 설계 기반이 되는 실제 세션 가져오기, 그리고 마지막에 점수가 제대로 생성됐는지 확인하기. 로그인 계정에는 `events:read` 권한이 필요하고, 최종 확인을 위해 `evaluations:read` 권한도 필요합니다. CLI 스킬과 마찬가지로, 이메일로 전송되는 일회용 코드 로그인은 **자동으로 완료할 수 없습니다**. -2. **평가자가 실행될 공간.** 평가자는 이미지로 빌드되어 장기 실행 서비스로 운영되므로, 임시 파일이 아닌 실제 저장소가 필요합니다. 평가자는 평가 대상 에이전트와 별도의 저장소에 운영되는 경우가 많습니다 — 스킬은 기존 저장소를 찾아보고, 새로 생성하기 전에 확인을 요청합니다. -3. **`agenteye-evaluator` SDK 휠** — 에이전트가 `pip` 명령을 입력하기 전에 다음 섹션을 먼저 읽으세요. +1. **`agenteye` CLI 설치 및 로그인** (`pipx install agenteye`, 그런 다음 `agenteye login`). 스킬은 두 가지 용도로 이를 활용합니다: 설계 기반이 되는 실제 세션을 가져오고, 마지막에 점수가 반영됐는지 확인합니다. 로그인에는 `events:read` 권한이 필요하며, 최종 확인을 위해 `evaluations:read`도 필요합니다. CLI 스킬과 마찬가지로, 이메일 일회용 코드 로그인은 **완료할 수 없습니다**. +2. **평가자가 실행될 공간.** 평가자는 이미지로 빌드되어 장기 실행 서비스로 실행되므로, 임시 파일이 아닌 실제 레포지토리가 필요합니다. 평가자는 채점 대상 에이전트와 별도의 레포지토리에 두는 경우가 많습니다 — 스킬은 기존 레포지토리를 찾아보고 새로 생성하기 전에 물어봅니다. +3. **`agenteye-evaluator` SDK 휠** — 에이전트가 `pip` 명령을 입력하기 전에 다음 섹션을 먼저 읽어보세요. --- -## 입수 방법 +## 스킬 가져오기 -이 스킬은 Failproof AI의 공개 스킬 컬렉션에 게시되어 있습니다: +스킬은 Failproof AI의 공개 스킬 컬렉션에 게시되어 있습니다: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -저장소는 공개되어 있으며 스킬 자체에는 별도의 인증 정보가 필요 없습니다 — 스킬은 여러분이 로그인한 세션으로 `agenteye` CLI를 구동하고 *여러분의* 저장소에 코드를 작성할 뿐입니다. 이 스킬은 별도 폴더로 제공되며 `pipx install agenteye` 패키지에는 포함되어 있지 **않으니**, 그곳에서 찾지 마세요. +레포지토리는 공개이며 스킬 자체에는 별도의 자격 증명이 필요하지 않습니다 — 여러분이 로그인한 `agenteye` CLI를 통해 세션을 가져오고, *여러분의* 레포지토리에 코드를 작성할 뿐입니다. 이 스킬은 별도 폴더로 제공되며 `pipx install agenteye` 패키지 안에 **포함되어 있지 않으니** 그곳에서 찾지 마세요. ## 스킬 설치 -가장 빠른 방법은 [`skills`](https://skills.sh) CLI를 사용하는 것입니다. 폴더를 가져와 에이전트가 찾는 위치에 배치해 줍니다: +가장 빠른 방법은 [`skills`](https://skills.sh) CLI를 사용하는 것입니다. 폴더를 가져와 에이전트가 찾는 위치에 배치해줍니다: ```bash -# Claude Code, 이 프로젝트에만 적용 +# Claude Code, 이 프로젝트에만 npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code # 모든 프로젝트 (~/.claude/skills/에 설치) @@ -82,86 +82,86 @@ npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g - npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -이후 다른 스킬과 동일하게 관리합니다: +그런 다음 다른 스킬과 동일하게 관리합니다: ```bash -npx skills list -a claude-code # 설치된 스킬 목록 +npx skills list -a claude-code # 설치된 스킬 확인 npx skills update agenteye-evaluator # 최신 버전으로 업데이트 npx skills remove agenteye-evaluator # 제거 ``` -수동으로 설치하고 싶으신가요? Agent Skill은 `SKILL.md`(및 선택적 참조 파일)가 포함된 폴더에 불과하므로, 복사해서 사용해도 됩니다: +직접 설치하는 것을 선호한다면, 에이전트 스킬은 `SKILL.md`(및 선택적 참조 파일)가 포함된 폴더일 뿐이므로 복사해도 됩니다: -- **Claude Code**: `agenteye-evaluator/` 폴더를 `~/.claude/skills/`(모든 프로젝트) 또는 `/.claude/skills/`(해당 저장소 전용)에 배치하세요. Claude Code가 자동으로 인식합니다 — `/skills` 목록으로 확인하거나, 평가를 요청해 보세요. -- **Codex (OpenAI)**: Codex도 동일한 `SKILL.md`를 읽습니다. 번들된 `agents/openai.yaml`에는 `allow_implicit_invocation: true`가 설정되어 있어, 작업 내용이 일치하면 Codex가 자동으로 스킬을 선택합니다. 명시적으로 호출하려면 `$agenteye-evaluator`를 사용하세요. +- **Claude Code**: `agenteye-evaluator/` 폴더를 `~/.claude/skills/`(모든 프로젝트) 또는 `/.claude/skills/`(해당 레포지토리만)에 넣습니다. Claude Code가 자동으로 감지합니다 — `/skills` 목록으로 확인하거나, 그냥 평가를 요청해보세요. +- **Codex (OpenAI)**: Codex는 동일한 `SKILL.md`를 읽습니다. 번들된 `agents/openai.yaml`은 `allow_implicit_invocation: true`로 설정되어 있어, 작업이 일치하면 Codex가 자동으로 스킬을 선택합니다; 그렇지 않으면 `$agenteye-evaluator`로 명시적으로 호출하세요. --- ## SDK는 공개 PyPI에 없습니다 -> **경고:** 에이전트가 SDK를 설치하기 전에 반드시 읽으세요. +> **경고:** 에이전트가 SDK를 설치하기 전에 먼저 읽어보세요. -스킬은 공개되어 있지만, 스킬이 구동하는 SDK는 그렇지 않습니다. `agenteye-evaluator`는 비공개 릴리스 아티팩트로만 제공되며, `agenteye`와 달리 공개 PyPI에서 **이름이 등록되어 있지 않습니다** — 따라서 `pip install agenteye-evaluator`를 그냥 실행하면 프로덕션 트랜스크립트를 읽는 서비스에 알 수 없는 패키지가 설치될 수 있습니다. 이는 오타의 문제가 아니라 공급망 보안 문제입니다. +스킬은 공개되어 있지만, 스킬이 구동하는 SDK는 그렇지 않습니다. `agenteye-evaluator`는 비공개 릴리스 아티팩트로만 제공되며, `agenteye`와 달리 공개 PyPI에서 이름이 **등록되지 않았습니다** — 따라서 `pip install agenteye-evaluator`를 그냥 실행하면 프로덕션 트랜스크립트를 읽는 서비스에 출처 불명의 패키지가 설치될 수 있습니다. 이것은 오타가 아니라 공급망 보안 문제입니다. -스킬은 이를 알고 있으며, 적용 가능한 첫 번째 단계부터 순서대로 설치를 시도합니다: AgentEye 저장소 내부라면 모노레포 소스, 그렇지 않으면 GitHub Releases의 비공개 릴리스 휠(접근 권한 필요), 둘 다 접근할 수 없으면 **즉흥적으로 처리하는 대신 Failproof AI 담당자에게 휠을 문의하라고 안내하고 중단합니다**. +스킬은 이를 인지하고 있으며, 대신 설치 우선순위를 단계적으로 시도합니다. 첫 번째로 적용 가능한 단계에서 멈춥니다: AgentEye 레포지토리 내부라면 모노레포 소스, 그렇지 않으면 GitHub Releases의 비공개 릴리스 휠(접근 권한 필요), 둘 다 접근할 수 없으면 즉흥적으로 처리하는 대신 **Failproof AI 담당자에게 휠을 요청하라고 알려줍니다**. -따라서 에이전트가 공개 PyPI에서 `pip install agenteye-evaluator`를 바로 제안한다면, 스킬이 로드되지 않은 것입니다. 즉시 중단하고 스킬이 설치되어 있는지 확인하세요. +따라서 에이전트가 공개 PyPI에서 `pip install agenteye-evaluator`를 제안한다면, 스킬이 로드되지 않았다는 신호입니다. 즉시 멈추고 스킬이 제대로 설치되어 있는지 확인하세요. --- -## 사용 가능한 요청 예시 +## 요청할 수 있는 것들 -실제 진행 과정은 막연한 요청으로 시작해서 코드 작성이 아닌 승인된 설계로 끝납니다: +실제 진행 과정은 막연한 요청으로 시작해 코드가 아닌 승인된 설계로 끝납니다: ```text -you ▸ I want evals for our support bot. I think it's sometimes bad. +당신 ▸ 서포트 봇 평가를 원해. 가끔 이상한 것 같아. -agent ▸ Before I write anything: describe a run that went well, - and one that went badly. +에이전트 ▸ 코드를 작성하기 전에: 잘 된 실행을 설명해주세요, + 그리고 잘못된 것도 하나요. -you ▸ Good: it answers from the docs. Bad: it makes stuff up, - or gives up and says "contact support". +당신 ▸ 좋은 것: 문서에서 답변해. 나쁜 것: 내용을 지어내거나, + 포기하고 "지원팀에 연락하세요"라고 해. -agent ▸ Running: agenteye --json sessions --status error --since 7d - Reading 5 sessions, including two you'd call bad. +에이전트 ▸ 실행 중: agenteye --json sessions --status error --since 7d + 5개 세션 읽는 중, 나쁘다고 할 두 개 포함. - Your words say factuality and deflection. The transcripts - agree on deflection (2 of 5 end with a support hand-off, - and it's plain in model_response.content), but factuality - needs a ground truth your events don't carry. + 말씀하신 내용은 사실성과 회피입니다. 트랜스크립트는 + 회피에 대해 동의하지만 (5개 중 2개가 지원 이관으로 끝나며, + model_response.content에서 명확히 확인됨), 사실성은 + 이벤트에 없는 정답 데이터가 필요합니다. - So I'd score three things: - - deflection rules, cheap, separates your two runs - - tool_efficiency rules, catches the retry loop in run-004 - - groundedness LLM judge: is every claim in the docs it retrieved? + 따라서 세 가지를 측정하겠습니다: + - deflection 규칙 기반, 저비용, 두 실행을 구분 + - tool_efficiency 규칙 기반, run-004의 재시도 루프 포착 + - groundedness LLM 판단: 검색된 문서에 모든 주장이 있는가? - "factuality" would need ground truth we don't have; groundedness - is the closest thing your transcripts can actually support. - OK with those three names? Renaming later splits the history. + "factuality"는 없는 정답 데이터가 필요하고, groundedness가 + 트랜스크립트로 실제 지원 가능한 가장 가까운 대안입니다. + 이 세 이름으로 진행해도 될까요? 나중에 이름을 바꾸면 기록이 분리됩니다. -you ▸ yes +당신 ▸ 좋아 -agent ▸ No evaluator in this repo. Should I scaffold one here, or do - you have one elsewhere? +에이전트 ▸ 이 레포지토리에 평가자가 없습니다. 여기에 만들까요, 아니면 + 다른 곳에 있나요? ``` -여기서부터 에이전트는 규칙 기반 지표를 먼저 작성합니다(비용 없음, 즉각적, 결정적). 그런 다음 빈 세션이나 중단된 세션처럼 단순한 평가자를 충돌시킬 수 있는 실제 캡처된 세션에 대해 테스트하고, 주관적인 지표에만 LLM 판정을 사용합니다. 에이전트는 [디스패처의 제한 사항](/ko/agenteye/evaluation-suite#configuring-the-server) — 30초 요청 타임아웃과 배포 전체에서 동시 8건 처리 — 을 알고 있으므로, 판정이 안정적으로 완료되기 어렵다면 비용을 5배로 늘려가며 취소와 재시도를 반복하는 대신 `JobPending`으로 비동기 처리합니다. +이후 규칙 기반 기준부터 먼저 작성합니다(무료, 즉각적, 결정론적). 그런 다음 빈 세션이나 완료되지 않은 세션처럼 단순한 평가자를 충돌시키는 케이스를 포함한 실제 캡처 세션에 대해 테스트합니다. 주관적 기준에만 LLM 판단을 사용합니다. 스킬은 [디스패처의 제한](/ko/agenteye/evaluation-suite#configuring-the-server) — 요청 타임아웃 30초, 배포 전체에서 동시 호출 8개 — 을 인지하고 있어, 판단이 안정적으로 맞지 않을 것 같으면 5배의 비용이 드는 취소·재시도 대신 `JobPending`으로 비동기 처리합니다. -이후 배포를 완료하고, 두 개의 서버 환경 변수를 설정하며, `agenteye --json evals --session-id `로 점수가 실제로 생성됐는지 확인합니다. 점수 생성이 유일한 증거입니다. +그런 다음 배포하고, 두 개의 서버 환경 변수를 설정하고, `agenteye --json evals --session-id `로 점수가 실제로 반영됐는지 확인합니다. 점수가 반영되는 것만이 유일한 증거입니다. --- -## 주의 사항 +## 주의해야 할 사항 -- **지표 이름은 사실상 영구적입니다.** 점수 키는 임의 문자열이고 플랫폼은 전송되는 모든 것의 추세를 추적하므로, 잘못된 선택을 사후에 교정할 방법이 없습니다. 나중에 이름을 바꾸면 히스토리가 분리됩니다: 이전 세션에는 이전 키가 유지되어 추세가 끊깁니다. 이것이 스킬이 코드를 작성하기 전에 명시적인 승인을 받는 이유입니다 — 그 프롬프트를 진지하게 받아들이세요. -- **픽스처는 실제 프로덕션 트랜스크립트입니다.** 실제 세션을 기반으로 설계한다는 것은 세션을 디스크로 가져온다는 의미이며, 고객 데이터가 포함될 수 있습니다. 스킬은 git에 커밋하기 전에 확인을 요청합니다. 확신이 없다면 `fixtures/`를 저장소 밖에 두고 각 개발자가 직접 가져오도록 하세요. -- **에이전트가 모든 트랜스크립트를 읽는 서비스를 작성하고 배포합니다.** CLI 로그인 권한 범위 내에서 여러분처럼 행동하지만, 프로덕션 데이터에 접근하는 다른 모든 코드와 동일하게 평가자를 검토하세요. +- **기준 이름은 거의 영구적입니다.** 점수 키는 임의의 문자열이고 플랫폼은 전송된 것을 무엇이든 트렌드로 표시합니다. 즉, 잘못된 선택을 교정해주는 하위 시스템이 없습니다. 나중에 이름을 바꾸면 기록이 분리됩니다: 이전 세션은 이전 키를 유지하고 트렌드가 끊깁니다. 이것이 스킬이 코드 작성 전에 명시적 승인을 받는 이유입니다 — 그 프롬프트를 진지하게 받아들이세요. +- **픽스처는 실제 프로덕션 트랜스크립트입니다.** 실제 세션을 기반으로 설계한다는 것은 디스크에 저장한다는 의미이며, 고객 데이터가 포함될 수 있습니다. 스킬은 git에 커밋하기 전에 확인을 요청합니다; 확신이 없다면 `fixtures/`를 레포지토리에서 제외하고 각 개발자가 직접 가져오도록 하세요. +- **에이전트는 모든 트랜스크립트를 읽는 서비스를 작성하고 배포합니다.** CLI 로그인 권한 범위 내에서 여러분을 대신해 작동하지만, 프로덕션 데이터를 다루는 다른 코드와 마찬가지로 평가자를 검토하세요. --- ## 다음 단계 -- **[Evaluation suite](/ko/agenteye/evaluation-suite)**: 스킬이 구성하는 HTTP 계약, SDK, 서버 환경 변수. -- **[Evaluations](/ko/agenteye/evaluations)**: 점수가 생성된 후 표시되는 위치. -- **[CLI skill](/ko/agenteye/cli-skill)**: 스코어러를 구축하는 대신 결과를 읽기 위한 형제 스킬. -- **[CLI](/ko/agenteye/cli)**: 스킬이 설계 기반으로 삼는 세션 데이터의 명령어 참조. \ No newline at end of file +- **[평가 스위트](/ko/agenteye/evaluation-suite)**: 스킬이 구성하는 HTTP 계약, SDK, 서버 환경 변수. +- **[평가](/ko/agenteye/evaluations)**: 점수가 반영된 후 표시되는 위치. +- **[CLI 스킬](/ko/agenteye/cli-skill)**: 스코어러를 구축하는 것이 아닌 결과를 읽기 위한 형제 스킬. +- **[CLI](/ko/agenteye/cli)**: 스킬이 기반으로 설계하는 세션 데이터의 명령어 참조. \ No newline at end of file diff --git a/docs/ko/agenteye/event-stream.mdx b/docs/ko/agenteye/event-stream.mdx index 52067e53..21b3e083 100644 --- a/docs/ko/agenteye/event-stream.mdx +++ b/docs/ko/agenteye/event-stream.mdx @@ -4,47 +4,47 @@ description: "에이전트가 무언가를 하는 순간, 바로 확인할 수 --- -에이전트가 무언가를 하는 순간, 바로 확인할 수 있습니다. 이벤트 스트림은 프로덕션의 모든 에이전트를 실시간으로 파악할 수 있는 창구입니다. 기다릴 필요도, 로그를 grep할 필요도, 방금 무슨 일이 일어났는지 추측할 필요도 없습니다. +에이전트가 무언가를 하는 순간, 바로 확인할 수 있습니다. 이벤트 스트림은 프로덕션의 모든 에이전트를 실시간으로 파악할 수 있는 창구입니다. 기다릴 필요도, 로그를 grep할 필요도, 무슨 일이 일어났는지 추측할 필요도 없습니다. ![실시간 이벤트 스트림: 색상으로 구분된 이벤트 행이 실시간으로 업데이트되며, 환경·에이전트·세션·이벤트 유형·자유 텍스트로 필터링 가능](/agenteye/images/events-stream.png) -*조직 내 모든 에이전트의 모든 이벤트가 최신순으로 표시되며, 발생하는 즉시 업데이트됩니다.* +*조직 내 모든 에이전트의 모든 이벤트를 최신순으로, 발생하는 즉시 업데이트합니다.* ## 모든 에이전트를 실시간으로 파악 -에이전트가 실행을 시작하거나, 모델을 호출하거나, 도구를 실행하거나, 훅을 실행하거나, 오류가 발생하면 해당 행이 발생하는 즉시 스트림 상단에 나타납니다. 조직 내 모든 에이전트의 모든 이벤트를 최신순으로 추적하므로, 오래된 정보가 아닌 현재 상태를 항상 파악할 수 있습니다. +에이전트가 실행을 시작하거나, 모델을 호출하거나, 툴을 실행하거나, 훅을 실행하거나, 오류가 발생하면 해당 행이 발생하는 즉시 스트림 상단에 나타납니다. 조직 내 모든 에이전트의 모든 이벤트를 최신순으로 추적하므로, 오래된 정보가 아닌 항상 최신 상태를 확인할 수 있습니다. -특정 서버에서 로그 파일을 tail하거나, 여러 머신에 걸쳐 grep하거나, 타임스탬프를 수작업으로 맞출 필요가 없습니다. 페이지 하나만 열면 이미 프로덕션을 모니터링하고 있는 것입니다. +특정 서버에서 로그 파일을 tail하거나, 여러 머신에 걸쳐 grep하거나, 타임스탬프를 수동으로 이어 맞출 필요가 없습니다. 페이지 하나만 열면 바로 프로덕션을 모니터링할 수 있습니다. -행은 유형별로 색상이 구분되어 있어, 모든 줄을 파싱하지 않아도 스트림을 한눈에 파악할 수 있습니다. 각 행에서 다음 정보를 즉시 확인할 수 있습니다: +행은 유형별로 색상이 구분되어 있어, 한 줄 한 줄 파싱하지 않아도 스트림을 한눈에 파악할 수 있습니다. 각 행에서 한눈에 확인할 수 있는 정보는 다음과 같습니다: -- **유형**: 색상으로 구분된 `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` 등. -- **한 줄 요약**: 무슨 일이 있었는지 파악하기 위해 굳이 열어볼 필요가 거의 없습니다. +- **유형** (색상 구분): `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` 등. +- **한 줄 요약**: 무슨 일이 있었는지 파악하기 위해 매번 상세 내용을 열어볼 필요가 없습니다. - **해당 단계의 토큰 수**. -- **컨텍스트 윈도우 사용률 배지**: 해당하는 경우 표시되어, 프롬프트 증가나 임박한 컴팩션을 문제가 되기 전에 미리 파악할 수 있습니다. +- **컨텍스트 윈도우 사용률 배지** (해당하는 경우): 프롬프트 증가나 컴팩션 임박 여부를 문제가 되기 전에 미리 확인할 수 있습니다. -실시간으로 모니터링하면 잘못된 배포, 무한 루프, 오류 폭발을 다음 날 로그 리뷰가 아닌 발생하는 순간에 포착할 수 있습니다. +실시간으로 모니터링하면 잘못된 배포, 무한 루프, 오류 급증 등을 다음 날 로그 리뷰가 아닌 발생하는 즉시 발견할 수 있습니다. -## 문제가 된 그 실행 찾기 +## 문제가 된 실행 찾기 -뭔가 이상해 보일 때, 엄청난 양의 데이터를 전부 뒤질 필요는 없습니다. 오류가 발생한 단 하나의 실행만 찾으면 됩니다. 스트림은 빠르게 필터링됩니다. 환경, 에이전트, 세션, 이벤트 유형, 또는 자유 텍스트로 필터링할 수 있습니다. +무언가 이상해 보일 때는 모든 데이터를 다 볼 필요가 없습니다. 문제가 된 단 하나의 실행을 찾으면 됩니다. 스트림은 빠르게 필터링됩니다: 환경별, 에이전트별, 세션별, 이벤트 유형별, 또는 자유 텍스트로 필터링할 수 있습니다. -세션 ID나 에이전트 ID로 필터링하면 첫 번째 이벤트부터 마지막 이벤트까지 하나의 실행을 추적할 수 있습니다. 이벤트 유형으로 필터링하면 특정 종류의 활동만 격리할 수 있습니다. 예를 들어 조직 전체의 모든 `error`를 한 화면에서 볼 수 있습니다. 필터를 중첩해 "모든 곳의 모든 것"에서 "프로덕션에서 오류가 나는 이 에이전트"로 몇 번의 클릭만으로 좁힌 다음, 발견한 내용에 따라 바로 조치를 취할 수 있습니다. +세션 ID나 에이전트 ID로 필터링하면 첫 번째 이벤트부터 마지막 이벤트까지 하나의 실행을 추적할 수 있습니다. 이벤트 유형으로 필터링하면 특정 종류의 활동만 격리할 수 있습니다. 예를 들어 조직 전체의 모든 `error`를 한 화면에서 볼 수 있습니다. 필터를 조합하면 "전체, 모든 곳"에서 "이 에이전트, 프로덕션, 오류 발생"으로 몇 번의 클릭만으로 범위를 좁힐 수 있으며, 발견한 내용을 바탕으로 바로 조치를 취할 수 있습니다. -자유 텍스트 검색으로 이미 알고 있는 메시지, 도구 이름, ID를 바로 찾아낼 수 있어, 고객 신고가 정확한 실행으로 이어지는 데 몇 초밖에 걸리지 않습니다. +자유 텍스트 검색은 이미 알고 있는 메시지, 툴 이름, 또는 ID로 바로 검색하므로 고객 제보가 몇 초 만에 정확한 실행으로 연결됩니다. ## 위치 -이벤트 스트림은 조직의 홈 화면입니다. 로그인하면 `//`에서 가장 먼저 보이는 화면이 바로 이벤트 스트림이므로, 도착하는 순간부터 트리아지를 시작할 수 있습니다. +이벤트 스트림은 조직의 홈 화면입니다. 로그인하면 `//`로 가장 먼저 도달하는 화면이므로, 접속하는 즉시 트리아지를 시작할 수 있습니다. -이면에서는 에이전트가 SDK를 통해 이벤트를 내보내고, 수집기가 이를 Failproof AI Observability 서버로 전송하며, 스트림이 여러분이 관리하는 인프라에 도착하는 대로 이벤트를 추적합니다. 원시 로그 대신 집계된 뷰를 원한다면, 각 실행의 이벤트가 Sessions에서 단일 행으로 접혀 표시되며 클릭 한 번으로 확인할 수 있습니다. +내부적으로 에이전트는 SDK를 통해 이벤트를 전송하고, 콜렉터가 이를 Failproof AI Observability 서버로 전달하며, 스트림은 사용자가 제어하는 인프라에 이벤트가 도착하는 대로 실시간으로 추적합니다. 원시 트레일 대신 집계된 뷰를 원할 때는 각 실행의 이벤트가 Sessions에서 한 행으로 요약되며, 클릭 한 번으로 이동할 수 있습니다. -이벤트 스트림은 다른 모든 관측 화면이 기반으로 삼는 원시 진실의 원천입니다. 다른 곳에서 숫자가 이상해 보인다면, 실제로 무슨 일이 있었는지 확인하는 곳은 바로 이 스트림입니다. +이벤트 스트림은 다른 모든 관찰 화면이 기반으로 삼는 원본 데이터 소스입니다. 따라서 다른 곳에서 수치가 이상해 보일 때, 실제로 무슨 일이 있었는지 확인하는 곳이 바로 스트림입니다. ## 관련 항목 -- [Sessions](/ko/agenteye/sessions): 동일한 이벤트를 실행 단위의 한 행으로 집계하며, git 스타일의 실행 그래프를 제공합니다. -- [Telemetry](/ko/agenteye/telemetry): 에이전트가 전송하는 내용과 이벤트가 스트림에 도달하는 방식. -- [Error tracking](/ko/agenteye/error-tracking): 모든 오류를 한 곳에서 트리아지할 수 있는 화면. +- [Sessions](/ko/agenteye/sessions): 동일한 이벤트를 실행별 한 행으로 요약하며, git 스타일의 실행 그래프 제공. +- [Telemetry](/ko/agenteye/telemetry): 에이전트가 전송하는 데이터와 이벤트가 스트림에 도달하는 방식. +- [Error tracking](/ko/agenteye/error-tracking): 발생한 모든 오류를 위한 단일 트리아지 화면. - [Alerts](/ko/agenteye/alerts): 임계값을 알림 규칙으로 전환. -- [CLI and agents](/ko/agenteye/cli-and-agents): 터미널에서 동일한 실시간 추적. \ No newline at end of file +- [CLI and agents](/ko/agenteye/cli-and-agents): 터미널에서 동일한 실시간 트레일 확인. \ No newline at end of file diff --git a/docs/ko/agenteye/hermes-capture.mdx b/docs/ko/agenteye/hermes-capture.mdx index a30bb3ce..a7051a28 100644 --- a/docs/ko/agenteye/hermes-capture.mdx +++ b/docs/ko/agenteye/hermes-capture.mdx @@ -1,53 +1,53 @@ --- title: "Hermes 세션 캡처" -description: "팀의 Hermes 게이트웨이 세션 — Slack, Telegram, CLI, 예약 실행 — 을 일반 세션 및 이벤트로 AgentEye에 가져옵니다." +description: "Slack, Telegram, CLI, 예약 실행 등 팀의 Hermes 게이트웨이 세션을 AgentEye의 일반 세션 및 이벤트로 가져옵니다." --- -[Hermes](https://hermes-agent.nousresearch.com)는 팀원들이 이미 사용하는 어떤 채널에서든 — Slack, Telegram, CLI, 예약 실행 — 응답을 제공합니다. Hermes 세션 캡처는 이 모든 것을 AgentEye에 일반 세션 및 이벤트로 가져오므로, 팀이 매일 대화하는 어시스턴트도 직접 작성한 에이전트만큼 관찰 가능해집니다. +[Hermes](https://hermes-agent.nousresearch.com)는 팀원들이 이미 사용하는 곳 어디서든 — Slack, Telegram, CLI, 예약 실행 — 질문에 답합니다. Hermes 세션 캡처는 이 모든 것을 AgentEye의 일반 세션과 이벤트로 가져오므로, 팀이 매일 대화하는 어시스턴트도 직접 작성한 에이전트만큼 투명하게 관찰할 수 있습니다. -소형 백그라운드 수집기가 Hermes의 로컬 세션 저장소를 작성 즉시 읽어 AgentEye로 전송합니다. 동작 방식은 [Codex](/ko/agenteye/codex-capture) 및 [OpenClaw](/ko/agenteye/openclaw-capture) 캡처와 동일하며, 하나의 수집기로 여러 에이전트를 동시에 캡처할 수 있습니다. +소규모 백그라운드 수집기가 Hermes의 로컬 세션 저장소를 기록되는 즉시 읽어 AgentEye로 전송합니다. [Codex](/ko/agenteye/codex-capture) 및 [OpenClaw](/ko/agenteye/openclaw-capture) 캡처와 동일한 방식으로 동작하며, 하나의 수집기로 여러 에이전트를 동시에 캡처할 수 있습니다. --- -## 캡처 항목 +## 캡처 대상 -머신의 모든 Hermes 세션은 어느 채널에서 시작되었든 캡처됩니다. 각 세션은 AgentEye [세션](/ko/agenteye/sessions)이 되고, 사용자 및 어시스턴트 메시지, 도구 호출, 도구 결과는 해당하는 [이벤트](/ko/agenteye/event-stream)가 됩니다. +채널에 관계없이 해당 머신의 모든 Hermes 세션이 캡처됩니다. 각 세션은 AgentEye [세션](/ko/agenteye/sessions)이 되며, 사용자 및 어시스턴트 메시지, 도구 호출, 도구 결과는 대응되는 [이벤트](/ko/agenteye/event-stream)가 됩니다. -세션이 시작된 채널 — Slack, Telegram, CLI, 예약 실행 — 은 세션에 기록되므로 구분하거나 하나씩 필터링할 수 있습니다. 함께 기록되는 정보로는 세션이 실행된 모델, 세션이 시작된 채팅 및 사용자, 그리고 세션이 다른 세션을 생성한 경우 부모 세션으로의 링크가 있습니다. +세션이 시작된 채널 — Slack, Telegram, CLI, 예약 실행 — 이 세션에 기록되므로 구분하거나 특정 채널만 필터링할 수 있습니다. 함께 기록되는 정보로는 세션이 실행된 모델, 세션이 시작된 채팅 및 사용자, 그리고 세션이 다른 세션을 생성한 경우 부모 세션으로의 링크가 있습니다. -세션은 Hermes가 시작하는 즉시 표시되며, 아직 아무 말도 나누지 않은 상태여도 마찬가지입니다. 한 턴의 응답과 도구 호출은 실제로 발생한 순서대로 유지됩니다. 세션이 종료되면 종료 이유, 비용, 사용된 토큰 수도 함께 확인할 수 있습니다. +세션은 Hermes가 시작하는 즉시 표시되며, 아직 아무 내용도 주고받지 않은 상태여도 마찬가지입니다. 턴의 응답과 도구 호출은 실제 발생한 순서대로 유지됩니다. 세션이 종료되면 종료 이유, 비용, 사용된 토큰 수도 함께 확인할 수 있습니다. --- ## 활성화 방법 -캡처는 활성화하기 전까지 비활성 상태입니다. `events:add` 권한이 있는 API 키([API 키](/ko/agenteye/api-keys) 참조)로 수집기를 설치하고 Hermes 캡처를 활성화합니다. +캡처는 활성화하기 전까지 비활성 상태입니다. `events:add` 권한이 있는 API 키([API 키](/ko/agenteye/api-keys) 참조)로 수집기를 설치하고 Hermes 캡처를 활성화하세요. ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -이 명령으로 수집기가 설치되고, 백그라운드 서비스로 등록되며, 캡처가 시작됩니다. 실행 여부를 확인합니다. +이 명령은 수집기를 설치하고, 백그라운드 서비스로 등록한 뒤 캡처를 시작합니다. 실행 중인지 확인하려면: ```bash agenteye-collector health ``` -동일한 머신에서 여러 에이전트를 캡처하려면? 같은 명령에 각 에이전트의 플래그를 추가하면 됩니다 — 예: `--hermes-enabled --codex-enabled`. +같은 머신에서 여러 에이전트를 캡처하고 싶으신가요? 동일한 명령에 각 에이전트의 플래그를 추가하세요 — 예: `--hermes-enabled --codex-enabled`. -첫 실행 시 기존 Hermes 세션이 한 번 백필되고, 이후 새로운 활동은 몇 초 이내에 스트리밍됩니다. Hermes의 데이터는 읽기만 할 뿐 수정하거나 삭제하지 않으며, 각 메시지는 재시작이 있더라도 한 번만 전송됩니다. +최초 실행 시 기존 Hermes 세션이 한 번 백필되며, 이후 새로운 활동은 몇 초 내로 스트리밍됩니다. Hermes의 데이터는 읽기만 할 뿐 수정하거나 삭제하지 않으며, 재시작이 이루어지더라도 각 메시지는 한 번만 전송됩니다. -`health` 명령은 수집기가 캡처한 모든 데이터가 실제로 AgentEye에 도달했는지도 알려줍니다. 배치 전송에 실패한 경우 삭제되지 않고 보존되어 재시도되며, 미전송 데이터가 남아 있는 동안은 비정상 상태로 보고됩니다 — 따라서 "정상"은 단순히 프로세스가 살아있다는 의미가 아니라 데이터가 실제로 도착했음을 의미합니다. +`health` 명령은 수집기가 캡처한 모든 데이터가 실제로 AgentEye에 도달했는지도 알려줍니다. 배치 전송에 실패한 경우 데이터는 폐기되지 않고 보관되어 재시도되며, 미전송 데이터가 남아 있는 동안은 비정상(unhealthy) 상태로 보고됩니다. 따라서 "정상(healthy)" 상태는 단순히 프로세스가 살아있다는 의미가 아니라 데이터가 실제로 도착했음을 의미합니다. --- ## 확인 위치 -캡처된 세션은 **Sessions**에, 이벤트는 **Events** 스트림에 표시되며, 다른 에이전트와 동일하게 취급됩니다 — 따라서 [세션 재생](/ko/agenteye/sessions), [검색](/ko/agenteye/queries), [평가](/ko/agenteye/evaluations), [알림](/ko/agenteye/alerts) 모두 이 세션에 적용됩니다. Hermes 에이전트로 필터링하면 해당 세션만 볼 수 있습니다. +캡처된 세션은 **Sessions**에, 이벤트는 **Events** 스트림에 표시됩니다. 다른 에이전트와 동일하게 표시되므로 [세션 재생](/ko/agenteye/sessions), [검색](/ko/agenteye/queries), [평가](/ko/agenteye/evaluations), [알림](/ko/agenteye/alerts) 기능이 모두 동작합니다. Hermes 에이전트로 필터링하면 해당 세션만 별도로 볼 수 있습니다. --- ## 개인정보 보호 -Hermes 세션에는 전체 대화 내용 — 명령 출력, 파일 내용, 에이전트가 읽거나 쓴 모든 것 — 이 포함되며, 비밀 정보가 담길 수 있습니다. 캡처된 세션은 있는 그대로 전송되므로, AgentEye에 해당 콘텐츠를 중앙화하는 것이 적절한 환경에서만 캡처를 활성화하고, 수집기에는 `events:add` 권한만 있는 키를 부여하세요. 데이터가 격리되어 보관되는 방식은 [보안](/ko/agenteye/security)을 참조하세요. \ No newline at end of file +Hermes 세션에는 명령 출력, 파일 내용, 에이전트가 읽거나 쓴 모든 내용을 포함한 전체 트랜스크립트가 담겨 있으며, 비밀 정보가 포함될 수 있습니다. 캡처된 세션은 있는 그대로 전송되므로, AgentEye에 해당 콘텐츠를 중앙화하는 것이 적절한 환경에서만 캡처를 활성화하고, 수집기에는 `events:add` 권한만 부여된 키를 사용하세요. 데이터 격리 방법에 대한 자세한 내용은 [보안](/ko/agenteye/security)을 참조하세요. \ No newline at end of file diff --git a/docs/ko/agenteye/incidents.mdx b/docs/ko/agenteye/incidents.mdx index 27f1bf45..8ebabf59 100644 --- a/docs/ko/agenteye/incidents.mdx +++ b/docs/ko/agenteye/incidents.mdx @@ -1,28 +1,28 @@ --- title: "인시던트" -description: "알림이 발생하면, 누구나 인시던트가 열려 있는지, 담당자가 누구인지, 지금까지 무슨 일이 있었는지를 하나의 귀속 타임라인에서 확인할 수 있습니다." +description: "알림이 발생하면 누구나 인시던트가 열려 있는지, 누가 담당하고 있는지, 지금까지 무슨 일이 있었는지를 하나의 귀속 타임라인에서 확인할 수 있습니다." --- -알림이 발생했을 때 가장 먼저 드는 질문은 언제나 "누가 담당하고 있나요?"입니다. 인시던트가 그 답을 제공합니다. 무언가 임계값을 초과하는 순간, 누구나 인시던트가 열려 있다는 사실, 담당자가 누구인지, 지금까지 정확히 어떤 일이 있었는지를 확인할 수 있습니다. 사후 검토(post-mortem)에 바로 활용할 수 있는 깔끔하고 귀속된 기록과 함께요. +알림이 발생했을 때 가장 먼저 드는 질문은 항상 "누가 처리하고 있나요?"입니다. 인시던트가 이 질문에 답합니다. 임계값이 초과되는 순간, 모든 팀원이 인시던트가 열려 있는지, 누가 담당하고 있는지, 지금까지 정확히 무슨 일이 있었는지를 확인할 수 있으며, 사후 검토(post-mortem)에 바로 활용할 수 있는 명확하고 귀속된 기록을 남깁니다. -![인시던트 인박스: 알림과 연결되거나 수동으로 생성된 인시던트 카드들이 상태별로 그룹화되어 있으며, 각각에는 심각도 배지와 담당자가 표시됩니다](/agenteye/images/incidents.png) -*인박스는 열린 인시던트를 상태별로 그룹화하고 심각도 및 담당자로 필터링하므로, 지금 즉시 사람이 처리해야 할 것이 무엇인지 바로 확인할 수 있습니다.* +![인시던트 인박스: 알림과 연결된 인시던트 카드와 수동으로 열린 인시던트 카드가 상태별로 그룹화되어 있으며, 각 카드에는 심각도 배지와 담당자가 표시됩니다](/agenteye/images/incidents.png) +*인박스는 열린 인시던트를 상태별로 그룹화하고 심각도와 담당자로 필터링하여, 지금 당장 사람이 처리해야 할 항목을 바로 확인할 수 있게 합니다.* -## 담당자를 한눈에 파악하세요 +## 한눈에 담당자 파악 -채팅 스레드에서 "누가 보고 있나요?"라고 묻는 일은 이제 없습니다. 임계값이 초과되면 인시던트가 자동으로 열리고 공유 인박스에 상태별로 그룹화되어 추가됩니다. 인시던트를 확인(acknowledge)하면 여러분의 이름이 붙어 나머지 팀원들이 처리되고 있다는 것을 알 수 있습니다. 확인은 공유 방식으로 이루어집니다. 여러 명의 운영자가 동일한 인시던트를 확인할 수 있으며, 각각이 개별적으로 기록되기 때문에 대규모 대응 상황에서도 서로 겹치지 않고 이름별로 표시됩니다. 트리아지(triage)를 위한 단일 담당자를 지정하고, 심각도 또는 담당자로 인박스를 필터링해서 자신이 처리해야 할 항목만 볼 수 있습니다. +채팅 스레드에서 "누가 보고 있나요?"를 물을 필요가 없습니다. 임계값 초과 시 인시던트가 자동으로 열리고 공유 인박스에 상태별로 그룹화되어 나타납니다. 인시던트를 확인(acknowledge)하면 여러분의 이름이 표시되어 나머지 팀원들이 처리 중임을 알 수 있습니다. 확인은 공유됩니다. 여러 운영자가 동일한 인시던트를 확인할 수 있으며 각각의 기록이 남기 때문에, 전체 대응 팀이 서로 겹치지 않고 이름으로 표시됩니다. 한 명의 담당자를 트리아지에 배정하고, 심각도나 담당자로 인박스를 필터링하여 자신의 항목만 볼 수 있습니다. -## 전체 경과를 하나의 타임라인으로 +## 하나의 타임라인에서 전체 경위 파악 -인시던트가 종료되면 이미 보고서가 완성되어 있습니다. 인시던트를 열면 임계값 초과 증거, 담당자 및 구독자, 현장에서 협업을 위한 댓글 스레드, 그리고 추가 전용(append-only) 활동 타임라인을 확인할 수 있습니다. +인시던트가 종료되면 이미 보고서가 작성되어 있습니다. 인시던트를 열면 임계값 초과 증거, 담당자 및 구독자, 협업을 위한 댓글 스레드, 그리고 추가만 가능한 활동 타임라인을 확인할 수 있습니다. ![인시던트 상세 보기: 상위 알림 및 임계값 초과 요약, 담당자 및 구독자, 귀속된 활동 타임라인, 댓글 스레드](/agenteye/images/incident-detail.png) -*발생한 모든 일이 순서대로 기록되며, 각 항목마다 실행한 담당자의 서명이 붙습니다.* +*발생한 모든 일이 순서대로 기록되며, 각 항목에는 누가 수행했는지가 명시됩니다.* -모든 액션(열림, 확인, 해결 등)은 해당 타임라인에 기록되며 절대 수정되거나 삭제되지 않습니다. 각 항목은 귀속됩니다. 액션을 취한 운영자의 이메일로, 또는 임계값 초과 시 인시던트를 여는 것처럼 Failproof AI Observability가 자체적으로 수행한 작업에는 **automated**로 표시됩니다. 익명 처리되거나 손실되는 것은 없으므로, 사후 검토가 거의 자동으로 완성됩니다. +모든 동작(열림, 확인, 해결 등)은 해당 타임라인에 기록되며 절대 수정되지 않습니다. 각 항목은 귀속됩니다. 작업을 수행한 운영자의 이메일로 귀속되거나, 임계값 초과 시 인시던트를 자동으로 열거나 하는 등 Failproof AI Observability가 자체적으로 수행한 작업에는 **automated**로 표시됩니다. 익명 항목도 없고 누락된 항목도 없기 때문에, 사후 검토 보고서가 거의 자동으로 작성됩니다. -## 인시던트의 상태 전환 +## 인시던트 진행 방식 ```mermaid stateDiagram-v2 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **열림(firing):** 임계값 초과 시 인시던트가 열리고 채널에 한 번 알림이 전송됩니다. 반복적인 임계값 초과는 동일한 인시던트에 통합되며, 반복 알림 대신 증거만 갱신됩니다. -- **확인됨(acknowledged):** 운영자가 인시던트를 담당합니다. 인시던트는 열린 상태를 유지하며, 이후 임계값 초과 발생 시 증거가 조용히 업데이트됩니다. -- **해결됨(resolved):** 운영자가 인시던트를 종료합니다. 조건이 해소될 때 자동으로 해결되는 기능은 계획 중이지만 아직 활성화되지 않았습니다. 따라서 인시던트는 사람이 해결할 때까지 열린 상태로 유지되어, 실제로 무엇이 해소되었는지에 대한 책임이 명확히 유지됩니다. 이후 동일한 알림에서 새로운 인시던트가 다시 열릴 수 있습니다. +- **열림 (firing):** 임계값 초과 시 인시던트가 열리고 채널에 한 번 알림을 보냅니다. 반복적인 임계값 초과는 동일한 인시던트에 통합되어 증거를 갱신하며, 반복적으로 알림을 보내지 않습니다. +- **확인됨 (acknowledged):** 운영자가 인시던트를 맡습니다. 인시던트는 열린 상태를 유지하며, 이후 임계값 초과가 발생해도 증거만 조용히 업데이트됩니다. +- **해결됨 (resolved):** 운영자가 인시던트를 종료합니다. 조건이 해소될 때 자동으로 해결되는 기능은 계획 중이나 아직 활성화되지 않았습니다. 따라서 인시던트는 사람이 직접 해결할 때까지 열린 상태로 유지되며, 이를 통해 실제로 해소된 것에 대해 투명성을 유지합니다. 나중에 동일한 알림으로 새 인시던트가 열릴 수 있습니다. -하나의 알림에는 최대 하나의 열린 인시던트만 존재할 수 있으므로, 불안정하게 반복되는 규칙으로 인해 중복 인시던트가 쌓이는 일은 없습니다. `incidents:write` 권한이 있다면 수동으로 인시던트를 열 수도 있습니다. 어떤 알림도 감지하지 못한 상황을 위한 독립 인시던트, 또는 기존 알림에 연결된 인시던트를 생성할 수 있습니다. +하나의 알림에는 동시에 열린 인시던트가 최대 하나만 존재하므로, 불안정하게 반복되는 규칙으로 인해 중복 인시던트가 쌓이지 않습니다. `incidents:write` 권한이 있다면 인시던트를 수동으로 열 수도 있습니다. 어떤 알림에도 연결되지 않은 독립 인시던트이거나, 기존 알림에 연결된 인시던트일 수 있습니다. ## 위치 -인시던트는 `//incidents`에 있습니다. 조회에는 **`incidents:read`**, 수동 인시던트 생성에는 **`incidents:write`**, 확인·담당자 지정·댓글·해결에는 **`incidents:ack`** 권한이 필요합니다. 이전에 발급된 키로 부여된 `alerts:ack` 권한은 `incidents:ack`와 동일하게 처리되므로, 온콜 로테이션을 위해 키를 재발급할 필요가 없습니다. +인시던트는 `//incidents`에 있습니다. 조회에는 **`incidents:read`** 권한이 필요하고, 수동 인시던트 열기에는 **`incidents:write`** 권한이 필요하며, 확인, 배정, 댓글 작성, 해결에는 **`incidents:ack`** 권한이 필요합니다. 이전에 폐기된 `alerts:ack` 권한을 부여받은 키는 `incidents:ack`로 인정되므로 계속 작동합니다. 따라서 온콜 로테이션을 다시 설정할 필요가 없습니다. ## 관련 항목 -- [알림](/ko/agenteye/alerts): 임계값이 초과될 때 인시던트를 여는 규칙입니다. -- [오류 추적](/ko/agenteye/error-tracking): 모든 장애를 한 곳에서 확인하고 알림으로 승격시킵니다. -- [감사](/ko/agenteye/audits): 어떤 규칙도 감지하지 못한 장애를 찾아내는 예약된 분석기입니다. \ No newline at end of file +- [알림](/ko/agenteye/alerts): 임계값 초과 시 인시던트를 여는 규칙입니다. +- [오류 추적](/ko/agenteye/error-tracking): 모든 장애를 한곳에서 확인하고 하나를 알림으로 승격합니다. +- [감사](/ko/agenteye/audits): 어떤 규칙도 감시하지 않던 장애를 찾아내는 예약된 분석기입니다. \ No newline at end of file diff --git a/docs/ko/agenteye/observability.mdx b/docs/ko/agenteye/observability.mdx index 2349fb37..9e4a5291 100644 --- a/docs/ko/agenteye/observability.mdx +++ b/docs/ko/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- title: "관찰" -description: "관찰 화면은 에이전트가 지금 무엇을 하고 있는지 실시간으로 확인하고 특정 실행을 상세히 살펴볼 수 있는 공간입니다." +description: "관찰 화면은 에이전트의 실시간 동작을 모니터링하고 개별 실행을 상세히 분석하는 곳입니다." --- -관찰 화면은 에이전트가 지금 무엇을 하고 있는지 실시간으로 확인하고 특정 실행을 상세히 살펴볼 수 있는 공간입니다. 이곳의 모든 정보는 실시간이며 조직 범위로 제공되고, 날짜 범위·환경·에이전트·세션 기준으로 필터링할 수 있어 "뭔가 이상한데"라는 느낌에서 정확한 실행 기록까지 수초 안에 도달할 수 있습니다. +관찰 화면은 에이전트의 실시간 동작을 모니터링하고 개별 실행을 상세히 분석하는 곳입니다. 여기의 모든 데이터는 실시간으로 제공되며, 조직 단위로 범위가 지정되고 날짜 범위, 환경, 에이전트, 세션별로 필터링할 수 있습니다. 덕분에 "뭔가 이상한데"라는 감이 드는 순간부터 정확한 실행 지점까지 몇 초 만에 도달할 수 있습니다. -![환경, 에이전트, 세션 기준으로 필터링 가능하고 유형별로 색상이 구분된 실시간 이벤트 스트림](/agenteye/images/events-stream.png) +![환경, 에이전트, 세션별로 필터링 가능하고 유형별로 색상이 구분된 실시간 이벤트 스트림](/agenteye/images/events-stream.png) -각각의 페이지로 구성된 네 가지 화면: +각각 별도의 페이지로 구성된 네 가지 화면: -- **[이벤트 스트림](/ko/agenteye/event-stream)**: 모든 에이전트의 모든 실행에 대한 실시간 단계별 기록으로, 최신순으로 정렬됩니다. 조직의 홈 화면이자 트리아지의 첫 번째 출발점입니다. -- **[세션 및 실행 그래프](/ko/agenteye/sessions)**: 이벤트를 실행 단위 한 행으로 집계하고, 각 실행이 어떻게 전개되었는지를 git 스타일의 그림으로 보여줍니다. -- **[성능 메트릭](/ko/agenteye/telemetry)**: 모델, 도구, 훅에 대한 지연 시간 히트맵과 p50/p95/p99 지표를 제공하여 꼬리 스파이크가 중앙값과 어떻게 다른지 한눈에 파악할 수 있습니다. -- **[오류 추적](/ko/agenteye/error-tracking)**: 문제가 발생한 모든 항목을 한 화면에서 트리아지하고, 알림 발생에서 해당 실행까지 클릭 한 번으로 이동합니다. +- **[이벤트 스트림](/ko/agenteye/event-stream)**: 모든 에이전트에 걸친 모든 실행의 실시간 단계별 기록으로, 최신 항목이 먼저 표시됩니다. 조직의 홈 화면이자 트리아지의 첫 번째 출발점입니다. +- **[세션 및 실행 그래프](/ko/agenteye/sessions)**: 이벤트를 실행 단위로 집계한 목록과 각 실행이 어떻게 전개되었는지를 보여주는 git 스타일의 시각적 그래프를 제공합니다. +- **[성능 메트릭](/ko/agenteye/telemetry)**: 모델, 도구, 훅에 대한 레이턴시 히트맵과 p50/p95/p99 지표를 제공하여 꼬리 스파이크가 중앙값과 확연히 구분되도록 합니다. +- **[오류 추적](/ko/agenteye/error-tracking)**: 발생한 모든 오류를 단일 트리아지 화면에서 확인하고, 발생한 알림에서 해당 실행까지 클릭 한 번으로 이동할 수 있습니다. ## 관련 항목 -- [평가](/ko/agenteye/evaluations): 모든 실행의 품질을 점수화합니다. -- [알림](/ko/agenteye/alerts): 임의의 임계값을 호출 규칙으로 전환합니다. -- [감사](/ko/agenteye/audits): Failproof AI Observability가 자동으로 세션 전반의 실패 패턴을 찾아드립니다. +- [평가](/ko/agenteye/evaluations): 모든 실행의 품질을 채점합니다. +- [알림](/ko/agenteye/alerts): 임의의 임계값을 페이징 규칙으로 전환합니다. +- [감사](/ko/agenteye/audits): Failproof AI Observability가 세션 전반에 걸친 장애 패턴을 자동으로 탐지합니다. - [CLI 및 에이전트](/ko/agenteye/cli-and-agents): 터미널에서도 동일한 관찰 기능을 사용할 수 있습니다. \ No newline at end of file diff --git a/docs/ko/agenteye/openclaw-capture.mdx b/docs/ko/agenteye/openclaw-capture.mdx index b5d0c156..3c7b75a7 100644 --- a/docs/ko/agenteye/openclaw-capture.mdx +++ b/docs/ko/agenteye/openclaw-capture.mdx @@ -1,49 +1,49 @@ --- title: "OpenClaw 세션 캡처" -description: "팀의 로컬 OpenClaw 세션을 AgentEye로 가져와 일반 세션 및 이벤트로 확인하세요 — OpenClaw 실행 방식은 전혀 변경할 필요가 없습니다." +description: "팀의 로컬 OpenClaw 세션을 AgentEye에 일반 세션 및 이벤트로 전송 — OpenClaw 실행 방식은 변경 없음." --- -팀이 [OpenClaw](https://docs.openclaw.ai)를 사용하고 있다면, OpenClaw 세션 캡처를 통해 해당 세션들을 AgentEye의 일반 세션 및 이벤트로 가져올 수 있습니다. 이를 통해 다른 관찰 데이터와 함께 검색, 재생, 평가가 가능합니다. 이 기능은 [Python SDK](/ko/agenteye/python-sdk)를 보완합니다. SDK는 직접 작성한 에이전트를 계측하는 반면, 이 기능은 팀이 이미 수행하는 OpenClaw 작업을 캡처합니다 — 실행 방식은 전혀 바꿀 필요가 없습니다. +팀에서 [OpenClaw](https://docs.openclaw.ai)를 사용하고 있다면, OpenClaw 세션 캡처를 통해 해당 세션을 AgentEye에 일반 세션 및 이벤트로 가져올 수 있습니다. 이를 통해 다른 관찰 대상과 함께 검색, 재생, 평가가 가능합니다. 이 기능은 [Python SDK](/ko/agenteye/python-sdk)를 보완합니다. SDK는 직접 작성한 에이전트를 계측하는 반면, 이 캡처 기능은 팀이 이미 수행 중인 OpenClaw 작업을 실행 방식 변경 없이 캡처합니다. -소규모 백그라운드 수집기가 OpenClaw의 로컬 세션 트랜스크립트를 작성 즉시 읽어 AgentEye로 전송합니다. [Codex 캡처](/ko/agenteye/codex-capture)와 동일한 방식으로 동작하며, 하나의 수집기로 두 가지를 동시에 캡처할 수 있습니다. +소형 백그라운드 수집기가 OpenClaw의 로컬 세션 트랜스크립트를 작성되는 즉시 읽어 AgentEye로 전송합니다. 동작 방식은 [Codex 캡처](/ko/agenteye/codex-capture)와 동일하며, 하나의 수집기로 두 가지를 동시에 캡처할 수 있습니다. --- -## 캡처되는 내용 +## 캡처 대상 머신의 OpenClaw 설정에 구성된 모든 에이전트는 해당 머신의 수집기에 의해 캡처됩니다 — 에이전트별 별도 설정은 필요하지 않습니다. -각 OpenClaw 세션은 AgentEye [세션](/ko/agenteye/sessions)이 되고, 사용자 및 어시스턴트 메시지, 툴 호출, 툴 결과는 대응하는 [이벤트](/ko/agenteye/event-stream)가 됩니다. +각 OpenClaw 세션은 AgentEye [세션](/ko/agenteye/sessions)이 되고, 사용자 및 어시스턴트 메시지, 도구 호출, 도구 결과는 해당하는 [이벤트](/ko/agenteye/event-stream)가 됩니다. --- ## 활성화 방법 -캡처는 기본적으로 비활성화 상태입니다. `events:add` 권한이 있는 API 키([API 키](/ko/agenteye/api-keys) 참고)로 수집기를 설치하고 OpenClaw 캡처를 활성화하세요: +캡처는 활성화하기 전까지 꺼져 있습니다. `events:add` 권한을 가진 API 키([API 키](/ko/agenteye/api-keys) 참조)로 수집기를 설치하고 OpenClaw 캡처를 활성화합니다: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -이 명령은 수집기를 설치하고, 백그라운드 서비스로 등록하며, 캡처를 시작합니다. 정상 동작 여부를 확인하려면: +이 명령은 수집기를 설치하고, 백그라운드 서비스로 등록한 뒤 캡처를 시작합니다. 실행 중인지 확인하려면: ```bash agenteye-collector health ``` -동일한 머신에서 여러 에이전트를 캡처하려면? 각 에이전트의 플래그를 동일한 명령에 추가하면 됩니다 — 예: `--openclaw-enabled --codex-enabled`. +같은 머신에서 여러 에이전트를 캡처하고 싶으신가요? 동일한 명령에 각 에이전트의 플래그를 추가하면 됩니다 — 예를 들어 `--openclaw-enabled --codex-enabled`. -최초 실행 시 기존 OpenClaw 세션이 한 번 백필되고, 이후 새 활동은 수 초 내에 스트리밍됩니다. OpenClaw의 파일은 읽기만 할 뿐 — 수정, 이동, 삭제는 절대 하지 않습니다 — 각 세션은 재시작이 있더라도 정확히 한 번만 전송됩니다. +최초 실행 시, 기존 OpenClaw 세션은 한 번 백필되며 이후 새로운 활동은 수 초 내에 스트리밍됩니다. OpenClaw의 파일은 읽기만 할 뿐 — 수정, 이동, 삭제는 절대 하지 않으며 — 재시작이 발생하더라도 각 세션은 정확히 한 번만 전송됩니다. --- -## 확인 위치 +## 표시 위치 -캡처된 세션은 **Sessions**에 표시되고, 이벤트는 **Events** 스트림에 표시됩니다 — 다른 에이전트 관찰 데이터와 동일합니다. 따라서 [세션 재생](/ko/agenteye/sessions), [검색](/ko/agenteye/queries), [평가](/ko/agenteye/evaluations), [알림](/ko/agenteye/alerts) 모두 해당 데이터에 적용됩니다. OpenClaw 에이전트로 필터링하면 해당 세션만 볼 수 있습니다. +캡처된 세션은 **Sessions**에, 해당 이벤트는 **Events** 스트림에 표시됩니다. 다른 관찰 대상 에이전트와 동일하게 [세션 재생](/ko/agenteye/sessions), [검색](/ko/agenteye/queries), [평가](/ko/agenteye/evaluations), [알림](/ko/agenteye/alerts) 기능이 모두 적용됩니다. OpenClaw 에이전트로 필터링하면 해당 세션만 볼 수 있습니다. --- -## 개인정보 보호 +## 개인 정보 보호 -OpenClaw 트랜스크립트에는 커맨드 출력, 파일 내용, 에이전트가 읽거나 쓴 모든 내용을 포함한 전체 세션이 담겨 있으며, 비밀 정보가 포함될 수 있습니다. 캡처된 세션은 있는 그대로 전송되므로, AgentEye에 해당 내용을 중앙화하는 것이 적절한 머신 및 팀에 대해서만 캡처를 활성화하고, 수집기에는 `events:add` 권한만 가진 키를 사용하세요. 데이터 격리 방식에 대해서는 [보안](/ko/agenteye/security)을 참고하세요. \ No newline at end of file +OpenClaw 트랜스크립트는 전체 세션 내용을 포함합니다 — 명령 출력, 파일 내용, 에이전트가 읽거나 쓴 모든 내용 포함 — 그리고 비밀 정보가 포함될 수 있습니다. 캡처된 세션은 있는 그대로 전송되므로, AgentEye에 해당 콘텐츠를 중앙화하는 것이 적절한 머신 및 팀에 대해서만 캡처를 활성화하고, 수집기에는 `events:add` 권한만 부여된 키를 사용하세요. 데이터 격리 방식에 대한 자세한 내용은 [보안](/ko/agenteye/security)을 참조하세요. \ No newline at end of file diff --git a/docs/ko/agenteye/overview.mdx b/docs/ko/agenteye/overview.mdx index b3c99b28..979028bd 100644 --- a/docs/ko/agenteye/overview.mdx +++ b/docs/ko/agenteye/overview.mdx @@ -4,74 +4,74 @@ description: "Failproof AI Observability는 프로덕션 환경에서 AI 에이 --- -Failproof AI Observability는 프로덕션 환경에서 AI 에이전트를 관측, 평가, 개선하기 위한 자체 호스팅 플랫폼입니다. 에이전트의 모든 동작(모든 도구 호출, 모델 요청, 훅, 오류)을 기록하고, 각 실행의 품질을 점수화하며, 미처 발견하지 못했던 장애를 찾아내 여러분의 인프라 내에서 직접 운영하는 대시보드에 표시합니다. +Failproof AI Observability는 프로덕션 환경에서 AI 에이전트를 관측, 평가, 개선하기 위한 자체 호스팅 플랫폼입니다. 에이전트의 모든 동작(툴 호출, 모델 요청, 훅, 오류)을 기록하고, 각 실행의 품질을 점수화하며, 미처 발견하지 못했던 장애를 찾아냅니다. 이 모든 것이 여러분의 인프라 내에서 직접 운영하는 대시보드를 통해 제공됩니다. -AI 에이전트를 운영 중이고 실행이 왜 잘못됐는지 계속 추측하는 데 지쳤다면, 여기서 시작하세요. 이 문서는 설치 전에 Failproof AI Observability가 제공하는 것과 각 구성 요소가 어떻게 연결되는지 설명합니다. +AI 에이전트를 배포하면서 실행이 왜 잘못됐는지 매번 추측하는 데 지치셨다면, 이 페이지가 출발점입니다. 설치 전에 Failproof AI Observability가 제공하는 것과 각 구성 요소가 어떻게 맞물리는지 설명합니다. -> **Failproof AI Observability는 Failproof AI의 엔터프라이즈 제품입니다.** 실제 동작을 보고 싶으신가요? 데모를 요청하세요: [nikita@befailproof.ai](mailto:nikita@befailproof.ai)로 이메일 보내주세요. +> **Failproof AI Observability는 Failproof AI의 엔터프라이즈 제품입니다.** 직접 확인해 보고 싶으신가요? 데모를 신청하세요: [nikita@befailproof.ai](mailto:nikita@befailproof.ai)로 이메일을 보내주세요. -![git 스타일의 실행 그래프와 이벤트 타임라인이 나란히 표시된 Failproof AI Observability 세션, 오른쪽 패널에는 도구·모델·훅의 실행별 분석 정보 표시](/agenteye/images/session-detail.png) +![git 스타일의 실행 그래프와 이벤트 타임라인이 나란히 표시된 Failproof AI Observability 세션 화면, 우측 패널에 툴·모델·훅별 실행 요약](/agenteye/images/session-detail.png) -*모든 에이전트 실행은 git 스타일의 실행 그래프(왼쪽)와 이벤트 타임라인이 나란히 표시됩니다. 병렬 서브 에이전트는 각각 별도의 레인을 가지며, 오른쪽 패널에서 해당 실행의 도구, 모델, 훅, 토큰 사용량을 상세히 확인할 수 있습니다.* +*모든 에이전트 실행은 git 스타일의 실행 그래프(왼쪽)와 이벤트 타임라인으로 시각화됩니다. 병렬 서브 에이전트는 각자의 레인을 가지며, 우측 패널에서 해당 실행의 툴, 모델, 훅, 토큰 사용량을 상세히 확인할 수 있습니다.* --- -## 실제 동작 보기 +## 실제 동작 확인 -두 편의 짧은 영상에서 팀들이 가장 먼저 찾는 두 가지 기능을 보여줍니다: 실행 추적과 자동 장애 탐지. +팀에서 가장 먼저 찾는 두 가지 기능 — 실행 추적과 자동 장애 탐지 — 을 짧은 영상 두 편으로 확인해 보세요.
-*에이전트 추적: 목표에서 도구 사용, 최종 응답까지 단일 실행을 단계별로 따라가기.* +*에이전트 추적: 목표에서 툴 호출, 최종 답변까지 단일 실행을 단계별로 따라갑니다.*
-*Failproof 감사: Failproof AI Observability가 세션 전반의 로그를 분석해 수정이 필요한 사항을 알려줍니다.* +*Failproof Audit: Failproof AI Observability가 세션 전반의 로그를 분석하여 수정해야 할 사항을 알려줍니다.* --- -## 팀이 이 도구를 사용하는 이유 +## 팀이 사용하는 이유 -- **에이전트가 실제로 무엇을 했는지 확인하세요.** 모든 실행이 읽기 쉬운 git 스타일의 실행 그래프로 변환됩니다: 어떤 도구가 병렬로 실행됐는지, 어떤 서브 에이전트가 분기했는지, 어디서 멈췄는지, 무엇을 사용했는지 한눈에 볼 수 있습니다. -- **품질 저하를 자동으로 감지하세요.** 소규모 점수화 서비스를 연결하면 Failproof AI Observability가 완료된 모든 실행을 점수화하여, 유용성 하락이나 환각 급증을 자동으로 감지합니다. -- **미리 규칙을 작성하지 않아도 장애를 찾아냅니다.** 반복 감사가 세션 전반의 로그에서 오류 클러스터, 지연 이상값, 낮은 점수, 중단된 실행을 발굴하고, 증거가 뒷받침된 우선순위 결과를 제시합니다. -- **중요한 순간에 알림을 받으세요.** 오류율, 지연 시간, 비용, 또는 평가 점수에 대한 임계값 규칙이 발동되면 인시던트가 생성되어 확인, 담당자 지정, 해결까지 처리할 수 있습니다. -- **일반 언어로 질문하세요.** 대시보드 내 AI 어시스턴트가 여러분의 데이터를 기반으로 "이번 주 프로덕션에서 품질 트렌드는 어떤가요?" 같은 질문에 답합니다. 어시스턴트가 변경하는 모든 사항은 승인이 필요합니다. -- **데이터를 직접 관리하세요.** Failproof AI Observability는 자체 호스팅 방식으로, 이벤트, 프롬프트, 분석 데이터가 여러분이 제어하는 인프라 안에 머뭅니다. +- **에이전트가 실제로 무엇을 했는지 확인합니다.** 모든 실행이 읽기 쉬운 git 스타일의 실행 그래프로 변환됩니다. 어떤 툴이 병렬로 실행됐는지, 어떤 서브 에이전트가 분기됐는지, 어디서 멈췄는지, 무엇을 소비했는지 한눈에 볼 수 있습니다. +- **품질 저하를 자동으로 감지합니다.** 소규모 채점 서비스를 연결하면 Failproof AI Observability가 완료된 모든 실행을 채점하므로, 유용성 하락이나 환각 급증이 자동으로 드러납니다. +- **규칙을 작성하지 않아도 장애를 찾아냅니다.** 정기적인 감사가 세션 전반의 로그에서 오류 클러스터, 지연 이상값, 낮은 점수, 중단된 실행을 탐지하고 증거 기반의 우선순위 결과물을 제공합니다. +- **중요한 순간에 알림을 받습니다.** 오류율, 지연 시간, 비용, 평가 점수에 대한 임계값 규칙이 인시던트를 생성하면 확인, 할당, 해결할 수 있습니다. +- **일반 언어로 질문합니다.** 대시보드 내 AI 어시스턴트가 여러분의 데이터를 기반으로 "이번 주 프로덕션의 품질 추이는 어때?"와 같은 질문에 답합니다. 어시스턴트가 변경하는 모든 사항은 승인이 필요합니다. +- **데이터를 직접 보관합니다.** Failproof AI Observability는 자체 호스팅 방식으로, 이벤트, 프롬프트, 분석 데이터가 여러분이 관리하는 인프라에 저장됩니다. --- ## 제공 기능 -Failproof AI Observability는 세 가지 개념(**관측**, **분석**, **관리**)을 중심으로 구성되며, 이는 대시보드 왼쪽 사이드바에 그대로 반영됩니다. +Failproof AI Observability는 세 가지 개념(**관측**, **분석**, **관리**)을 중심으로 구성되어 있으며, 대시보드 왼쪽 사이드바에 반영되어 있습니다. -**관측** (실제로 무슨 일이 있었는지의 원본 데이터): +**관측** (실제 발생한 일의 원시 데이터): -- **[이벤트 스트림](/ko/agenteye/event-stream)**: 모든 실행의 단계별 실시간 기록 (도구 호출, 모델 호출, 훅, 오류). -- **[세션](/ko/agenteye/sessions)**: 실행별로 집계된 이벤트로, 각 실행은 점수화 준비가 된 한 행으로 표시되며 git 스타일의 실행 그래프를 포함합니다. -- **[성능 메트릭](/ko/agenteye/telemetry)**: 표면별 지연 시간 히트맵과 모델, 도구, 훅에 대한 p50/p95/p99 지표로, 꼬리 구간의 급증을 중앙값과 비교해 식별합니다. -- **[오류 추적](/ko/agenteye/error-tracking)**: 발생한 모든 문제를 한 곳에서 트리아지하고, 발동된 알림에서 한 번의 클릭으로 접근할 수 있습니다. +- **[이벤트 스트림](/ko/agenteye/event-stream)**: 모든 실행의 실시간 단계별 기록 (툴 호출, 모델 호출, 훅, 오류). +- **[세션](/ko/agenteye/sessions)**: 이벤트를 실행 단위로 집계한 행 목록. 각 행에 채점 기능과 git 스타일 실행 그래프가 제공됩니다. +- **[성능 메트릭](/ko/agenteye/telemetry)**: 모델, 툴, 훅에 대한 서피스별 지연 시간 히트맵 및 p50/p95/p99 수치. 꼬리 급등이 중앙값과 명확히 구분됩니다. +- **[오류 추적](/ko/agenteye/error-tracking)**: 발생한 모든 오류를 하나의 트리아지 화면에서 확인하고, 알림에서 한 번의 클릭으로 이동할 수 있습니다. -![도구 관측 페이지: 24개의 시간 구간에 걸친 지연 시간 히트맵, 백분위수 밴드, 도구 분포 바](/agenteye/images/tools.png) +![툴 관측 페이지: 24개 시간 구간에 걸친 지연 시간 히트맵, 백분위 밴드, 툴 분포 막대 차트](/agenteye/images/tools.png) -*각 관측 화면은 스파크라인과 p50/p95/p99 지표를 지연 시간 히트맵 및 백분위수 밴드와 함께 표시합니다. 여기서는 도구(Tools) 화면을 보여줍니다.* +*각 관측 화면은 스파크라인과 p50/p95/p99 수치를 지연 시간 히트맵 및 백분위 밴드와 함께 표시합니다. 화면은 툴(Tools)을 보여줍니다.* **분석** (활동을 인사이트로 전환): -- **[쿼리](/ko/agenteye/queries)** 및 **[대시보드](/ko/agenteye/dashboards)**: 이벤트와 평가 데이터에 대해 저장된 SQL을 실행하고, 조직 범위의 공유 대시보드로 시각화합니다. -- **[평가](/ko/agenteye/evaluations)**: 자체 평가 서비스가 생성하는 품질 점수와 점수별 근거. -- **[감사](/ko/agenteye/audits)**: 세션 전반에서 장애 패턴을 발굴하는 반복 조사. -- **[알림](/ko/agenteye/alerts)** 및 **[인시던트](/ko/agenteye/incidents)**: 알림을 발송하는 임계값 규칙과, 이를 트리아지할 수 있는 인시던트 워크플로우. +- **[쿼리](/ko/agenteye/queries)** 및 **[대시보드](/ko/agenteye/dashboards)**: 이벤트와 평가 데이터에 대한 저장된 SQL 쿼리를 조직 범위의 공유 대시보드에 차트로 시각화합니다. +- **[평가](/ko/agenteye/evaluations)**: 자체 평가 서비스가 생성한 품질 점수와 점수별 근거. +- **[감사](/ko/agenteye/audits)**: 세션 전반에서 장애 패턴을 탐지하는 정기 조사. +- **[알림](/ko/agenteye/alerts)** 및 **[인시던트](/ko/agenteye/incidents)**: 알림을 발생시키는 임계값 규칙과 트리아지를 위한 인시던트 워크플로우. **인터페이스** (원하는 방식으로 데이터에 접근): -- **[CLI](/ko/agenteye/cli-and-agents)**: 터미널이나 스크립트에서 전체 배포를 제어하고, 코딩 에이전트가 일반 언어로 대신 처리하도록 할 수 있습니다. -- **[AI 어시스턴트](/ko/agenteye/assistant)**: 대시보드 내에서 일반 언어로 에이전트에 대해 질문하세요. -- **REST API**: 대시보드와 CLI의 모든 기능은 범위가 지정된 [API 키](/ko/agenteye/api-keys)로 직접 호출할 수 있는 REST API로 지원됩니다 — 이벤트 수집, 세션 및 평가 쿼리, 대시보드·알림·감사·사용자·키 관리까지 가능하여, Failproof AI Observability를 자체 도구와 연동할 수 있습니다. +- **[CLI](/ko/agenteye/cli-and-agents)**: 터미널이나 스크립트에서 전체 배포를 관리하고, 코딩 에이전트가 일반 언어로 대신 처리하도록 할 수 있습니다. +- **[AI 어시스턴트](/ko/agenteye/assistant)**: 대시보드 내에서 에이전트에 대한 질문을 일반 언어로 물어봅니다. +- **REST API**: 대시보드와 CLI의 모든 기능은 범위가 지정된 [API 키](/ko/agenteye/api-keys)로 직접 호출할 수 있는 REST API를 기반으로 합니다. 이벤트 수집, 세션 및 평가 조회, 대시보드·알림·감사·사용자·키 관리가 가능하므로 Failproof AI Observability를 기존 툴링에 통합할 수 있습니다. **관리** (팀을 위한 운영): @@ -83,26 +83,26 @@ Failproof AI Observability는 세 가지 개념(**관측**, **분석**, **관리 ## 구성 요소의 연결 방식 -데이터는 에이전트 코드에서 대시보드까지 단방향으로 흐릅니다: 에이전트(Python SDK를 통해)가 이벤트를 agenteye-collector로 전송하고, collector가 서버로 전달하며, 서버가 대시보드를 제공합니다. 두 개의 선택적 서비스로 구성이 완성됩니다 — 점수화 서비스(평가)와 AI 어시스턴트 서비스(대시보드 내 채팅). +데이터는 에이전트 코드에서 대시보드까지 단방향으로 흐릅니다. 에이전트(Python SDK 경유)가 agenteye-collector에 이벤트를 전송하고, collector가 서버로 전달하며, 서버가 대시보드를 제공합니다. 두 가지 선택적 서비스 — 채점 서비스(평가)와 AI 어시스턴트 서비스(대시보드 내 채팅) — 가 이를 완성합니다. -- **Python SDK**: 에이전트에 몇 가지 `agenteye.event.*` 호출을 추가하면, 이벤트가 로컬에서 버퍼링됩니다. -- **agenteye-collector**: 각 에이전트 머신에서 실행되는 경량 데몬으로, 이벤트를 일괄 처리하여 서버로 전송합니다. -- **서버**: 이벤트를 수집하고, 자체 데이터베이스에서 운영 상태를 유지하며, 대시보드·CLI·자체 통합에서 모두 사용하는 REST API를 제공합니다. -- **대시보드**: 모든 것을 탐색하는 공간. -- **선택적 서비스**: 점수화 서비스(평가)와 AI 어시스턴트 서비스(대시보드 내 채팅). +- **Python SDK**: 에이전트에 `agenteye.event.*` 호출 몇 개를 추가하면 이벤트가 로컬에 버퍼링됩니다. +- **agenteye-collector**: 각 에이전트 머신에서 실행되는 경량 데몬으로, 이벤트를 배치 처리하여 서버로 전송합니다. +- **서버**: 이벤트를 수집하고, 자체 데이터베이스에 운영 상태를 유지하며, 대시보드·CLI·기타 통합에서 사용하는 REST API를 제공합니다. +- **대시보드**: 모든 것을 탐색하는 곳입니다. +- **선택적 서비스**: 채점 서비스(평가)와 AI 어시스턴트 서비스(대시보드 내 채팅). -문서 전반에서 사용하는 용어(*이벤트, 세션, 평가, 감사, 결과, 인시던트*)에 대해서는 [개념](/ko/agenteye/concepts)을 참고하세요. +문서 전반에서 사용하는 용어(*이벤트, 세션, 평가, 감사, 결과물, 인시던트*)는 [개념 설명](/ko/agenteye/concepts)을 참고하세요. --- ## Failproof AI Observability 도입하기 -Failproof AI Observability는 Failproof AI의 엔터프라이즈 제품으로, Failproof AI 브랜드 아래 정책 및 가드레일 제품인 Failproof AI Enforcement와 함께 동작합니다. 완전히 여러분의 환경에서 실행됩니다. 아직 패키지에 대한 접근 권한이 없다면, 데모를 요청해 주세요: [nikita@befailproof.ai](mailto:nikita@befailproof.ai)로 이메일을 보내주시면 시작을 도와드리겠습니다. +Failproof AI Observability는 Failproof AI의 엔터프라이즈 제품으로, Failproof AI 브랜드 아래 정책 및 가드레일 제품인 Failproof AI Enforcement와 함께 작동합니다. 완전히 여러분의 환경 내에서 실행됩니다. 아직 패키지에 대한 접근 권한이 없다면 데모를 신청해 주세요: [nikita@befailproof.ai](mailto:nikita@befailproof.ai)로 이메일을 보내주시면 설정을 도와드립니다. --- ## 다음 단계 -- [개념](/ko/agenteye/concepts): Failproof AI Observability 용어를 한 곳에서 정리한 문서. -- [Observability](/ko/agenteye/observability): 에이전트의 동작을 실행별로 추적하기. -- [보안](/ko/agenteye/security): Failproof AI Observability가 데이터를 격리하고 여러분의 통제 하에 유지하는 방법. \ No newline at end of file +- [개념 설명](/ko/agenteye/concepts): Failproof AI Observability 용어를 한곳에서 정리합니다. +- [Observability](/ko/agenteye/observability): 에이전트의 동작을 실행 단위로 추적합니다. +- [보안](/ko/agenteye/security): Failproof AI Observability가 데이터를 격리하고 여러분이 통제할 수 있도록 유지하는 방법. \ No newline at end of file diff --git a/docs/ko/agenteye/python-sdk-skill.mdx b/docs/ko/agenteye/python-sdk-skill.mdx index cc960cb3..13fafb16 100644 --- a/docs/ko/agenteye/python-sdk-skill.mdx +++ b/docs/ko/agenteye/python-sdk-skill.mdx @@ -1,130 +1,131 @@ --- title: "Failproof AI Observability Python SDK Agent Skill" -description: "계측되지 않은 에이전트에서 가시적인 이벤트로: 코딩 에이전트가 계측 지점을 찾아내고, 작성하고, 정상적으로 반영됐음을 검증합니다." +description: "코딩 에이전트가 계측 지점을 찾고, 코드를 작성하고, 정상 동작을 검증할 때까지 — 미계측 에이전트에서 가시적인 이벤트로." --- -코딩 에이전트에게 *"이 에이전트에 Failproof AI Observability를 추가해줘"* 라고 말하면, 에이전트가 루프를 읽고, 계측 위치를 파악하고, 코드를 작성하고, 작업을 완료로 선언하기 전에 이벤트를 검증합니다. +코딩 에이전트에게 *"이 에이전트에 Failproof AI Observability를 추가해줘"* 라고 말하면, 에이전트가 루프를 읽고, 계측 위치를 파악하고, 코드를 작성한 다음, 작업 완료를 선언하기 전에 이벤트를 검증합니다. -**Python SDK 스킬** (`agenteye-python-sdk`)은 *Agent Skill*입니다. 이는 Claude Code나 Codex 같은 코딩 에이전트가 작업이 일치할 때 온디맨드로 로드하는 명령어 폴더입니다. 이 스킬은 에이전트에게 [Python SDK](/ko/agenteye/python-sdk) 사용법을 가르쳐줍니다. 라이브러리가 아니며 SDK의 작동 방식을 변경하지 않습니다. +**Python SDK 스킬** (`agenteye-python-sdk`)은 *Agent Skill*입니다. Claude Code나 Codex 같은 코딩 에이전트가 작업과 매칭될 때 로드하는 명령어 폴더로, 에이전트에게 [Python SDK](/ko/agenteye/python-sdk) 사용법을 가르칩니다. 라이브러리가 아니며 SDK 동작 방식을 전혀 변경하지 않습니다. -## 계측은 작성하기 쉽지만 조용히 잘못되기도 쉽습니다 +## 계측 코드는 작성하기 쉽지만, 모르게 틀리기도 쉽습니다 -SDK는 작습니다: 키워드 전용 인수를 사용하는 이벤트 메서드 13개가 전부입니다. 코딩 에이전트는 [Python SDK](/ko/agenteye/python-sdk) 레퍼런스를 읽고 1분 안에 그럴듯한 계측 코드를 만들어낼 수 있습니다. +SDK는 작습니다. 열세 개의 이벤트 메서드, 모두 키워드 전용입니다. 코딩 에이전트는 [Python SDK](/ko/agenteye/python-sdk) 레퍼런스를 읽고 그럴듯한 계측 코드를 1분 안에 만들어낼 수 있습니다. -문제는 이 SDK가 잘못 사용해도 오류를 발생시키지 않는다는 점이며, 잘못된 계측은 대시보드를 열었을 때 비어 있다는 걸 발견하기 전까지는 올바른 계측과 완전히 똑같아 보입니다. 실제로 시간을 낭비하게 만드는 실수들은 모두 침묵입니다: +문제는, 이 SDK는 잘못 사용해도 예외를 발생시키지 않는다는 점입니다. 잘못된 계측은 대시보드를 열어 아무것도 없다는 걸 발견하기 전까지 올바른 계측과 구분이 되지 않습니다. 실제로 시간을 잡아먹는 실수들은 전부 침묵입니다. | 실수 | 보이는 것 | |---|---| -| `agent_start` 없음 | 모든 이벤트가 기록됨. 세션은 0. | -| 환경 설정 안 됨 | 모든 것이 동작하지만 `dev`에 기록됨. | -| `outcome="failure"` | 실행이 성공으로 표시됨 — `failed`, `error`, `timeout`, `rejected`만 집계됨. | -| 오타가 있는 필드 이름 | 새 필드로 저장됨. | -| 스레드 풀에서 이벤트 발행 | 조용히 드롭됨. | +| `agent_start` 없음 | 모든 이벤트가 기록됨. 세션은 0개. | +| 환경 미설정 | 모든 것이 정상 동작하지만 `dev`로 분류됨. | +| `outcome="failure"` 사용 | 실행이 성공으로 표시됨 — `failed`, `error`, `timeout`, `rejected`만 유효함. | +| 필드명 오타 | 그대로 수락되어 새 필드로 저장됨. | +| 스레드 풀에서 이벤트 발생 | 무음으로 드롭됨. | -이 중 어떤 것도 오류를 발생시키지 않습니다. 어떤 것도 테스트에서 나타나지 않습니다. 모두 스킬에 포함되어 있으며, 이를 잡아내는 검사와 함께 명세로 기술되어 있습니다. +이 중 어느 것도 예외를 발생시키지 않습니다. 테스트에서도 잡히지 않습니다. 모든 경우가 스킬에 명시되어 있으며, 각각을 포착하는 검사와 함께 계약으로 기술되어 있습니다. -## 작동 방식, 순서대로 +## 스킬이 하는 일 (순서대로) -스킬은 신중한 엔지니어라면 수행할 세 단계를 동일하게 실행합니다: +스킬은 꼼꼼한 엔지니어라면 밟을 세 단계를 동일하게 수행합니다. -1. **계획.** 에이전트 루프를 읽고, 오직 개발자만 답할 수 있는 두 가지 질문을 합니다: 하나의 실행이 무엇인지(`session_id`), 그리고 구별 가능한 행위자가 누구인지(`agent_id`). 코드를 작성하기 전에 이 사항들을 합의합니다. 나중에 변경하면 히스토리가 분리되고 트렌드가 깨지기 때문입니다. -2. **작성.** 모든 호출 위치에 identity를 전달하는 대신 실행당 한 번만 바인딩하고, 동시성에 안전한 방식을 선택합니다. 이는 중요한 세부 사항으로, 명백해 보이는 지름길은 두 개의 겹치는 실행을 하나의 세션에 조용히 섞어버립니다. -3. **검증.** 에이전트를 실행하고 결과 이벤트 파일을 읽어 `agent_start`가 존재하는지, 환경이 올바른지, 하나의 실행이 하나의 세션을 생성했는지 확인합니다. +1. **계획.** 에이전트 루프를 읽고, 오직 당신만 답할 수 있는 두 가지 질문을 합니다. 하나의 실행 단위가 무엇인지(당신의 `session_id`), 그리고 구별 가능한 행위자가 누구인지(당신의 `agent_id`)입니다. 코드를 작성하기 전에 이 부분을 확정합니다. 나중에 변경하면 히스토리가 분리되고 트렌드가 깨집니다. +2. **작성.** 모든 호출 위치에 전달하는 대신 실행당 한 번 아이덴티티를 바인딩하고, 동시성 안전 방식을 선택합니다. 이는 중요한 세부 사항입니다. 단순한 지름길을 택하면 동시에 진행되는 두 실행이 소리 없이 하나의 세션으로 섞입니다. +3. **검증.** 에이전트를 실행하고 생성된 이벤트 파일을 읽어, `agent_start`가 존재하는지, 환경이 맞는지, 하나의 실행이 하나의 세션을 생성했는지 확인합니다. -세 번째 단계가 사람들이 건너뛰는 단계입니다. SDK는 이벤트를 로컬 파일에 기록하므로, 완전한 통합은 서버, API 키, 네트워크 없이 노트북에서 검증할 수 있습니다. 바로 이것이 스킬이 이 단계를 고집하는 이유입니다. +세 번째 단계가 사람들이 건너뛰는 부분입니다. SDK는 이벤트를 로컬 파일에 기록하므로, 서버도 API 키도 네트워크도 없는 노트북에서 완전한 통합을 증명할 수 있습니다 — 그렇기 때문에 스킬이 이 단계를 반드시 수행하는 것입니다. ## 다른 스킬들과의 관계 -세 가지 스킬, 명확한 역할 분담: +세 가지 스킬, 하나의 깔끔한 분리: -| 스킬 | 사용 시점 | 영향 범위 | +| 스킬 | 사용 시점 | 적용 대상 | |---|---|---| -| **Python SDK 스킬** (이 페이지) | 에이전트가 텔레메트리를 *발행*하게 하려고 할 때 — "observability 추가", "내 에이전트가 왜 안 보이지?" | 에이전트 레포에 코드를 작성. 아무것도 읽지 않음. | -| **[Evaluator 스킬](/ko/agenteye/evaluator-skill)** | 실행을 *평가*하려고 할 때 — "무엇을 측정해야 하지?" | 레포에 코드 작성, 텔레메트리 읽기 | -| **[CLI 스킬](/ko/agenteye/cli-skill)** | 발생한 일을 *조회*하거나 배포를 운영하려고 할 때 | 사용자 권한으로 CLI 실행, 변경 포함 | +| **Python SDK 스킬** (현재 페이지) | 에이전트가 텔레메트리를 *발신*하게 하고 싶을 때 — "observability 추가", "내 에이전트가 왜 안 보이지?" | 에이전트 레포에 코드를 작성함. 아무것도 읽지 않음. | +| **[Evaluator 스킬](/ko/agenteye/evaluator-skill)** | 실행을 *점수화*하고 싶을 때 — "무엇을 측정해야 할까?" | 레포에 코드를 작성하고 텔레메트리를 읽음 | +| **[CLI 스킬](/ko/agenteye/cli-skill)** | 발생한 일을 *읽거나* 배포를 운영하고 싶을 때 | CLI를 당신 대신 구동하며, 변경 포함 | -이 순서로 연결됩니다: 이 스킬이 이벤트를 흐르게 하고, evaluator가 점수를 매기고, CLI가 결과를 읽습니다. 에이전트가 세션을 발행하기 전까지는 평가할 것도, 읽을 것도 없습니다. 처음부터 시작한다면 여기서 시작하세요. +이 순서대로 연결됩니다. 이 스킬이 이벤트를 흐르게 하고, evaluator가 점수를 매기고, CLI가 읽어옵니다. 에이전트가 세션을 발신하기 전까지는 평가할 것도, 읽을 것도 없습니다. 처음 시작한다면 여기서 시작하세요. -## 사전 요구 사항 +## 사전 요건 1. **Python 3.10+** 및 계측하려는 에이전트 코드베이스. -2. **SDK.** 공개 패키지 인덱스가 아닌 프라이빗 wheel로 고객에게 배포됩니다. 온보딩 과정에서 SDK를 획득하고 설치하는 방법을 안내합니다. 스킬은 설치 경로를 알고 있으며, 찾을 수 없는 경우 추측 대신 직접 물어봅니다. -3. **그 외 없음.** 대시보드 로그인, API 키, 네트워크가 필요 없습니다. 스킬은 SDK가 기록하는 이벤트 파일을 기준으로 검증하므로 오프라인에서도 작업을 완료하고 증명할 수 있습니다. +2. **SDK.** 공개 인덱스가 아닌 프라이빗 wheel로 고객에게 배포됩니다 — 획득 및 설치 방법은 온보딩에서 안내됩니다. 스킬은 설치 경로를 알고 있으며, 찾지 못할 경우 추측하지 않고 질문합니다. +3. **그 외 없음.** 대시보드 로그인, API 키, 네트워크 불필요. 스킬은 SDK가 기록한 이벤트 파일로 검증하므로 오프라인에서도 작업을 완료하고 증명할 수 있습니다. -## 스킬 가져오는 방법 +## 스킬 받기 -스킬은 공개 [`FailproofAI/skills`](https://github.com/FailproofAI/skills) 컬렉션에 있습니다: +스킬은 공개 [`FailproofAI/skills`](https://github.com/FailproofAI/skills) 컬렉션에 있습니다. ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -현재 프로젝트 대신 모든 프로젝트에 설치하려면 `-g`를 추가하고, 환경이 심볼릭 링크를 지원하지 않으면 `--copy`를 사용하세요. Codex의 경우 `-a codex`를 전달하세요. +현재 프로젝트가 아닌 모든 프로젝트에 설치하려면 `-g`를 추가하고, 환경이 심볼릭 링크를 지원하지 않으면 `--copy`를 사용하세요. Codex의 경우 `-a codex`를 전달하세요. ## 수동 설치 -Agent Skills는 `SKILL.md`와 참조 파일들을 포함하는 폴더입니다. 설치 도구를 사용하지 않으려면: +Agent Skills는 `SKILL.md`와 참조 파일을 포함하는 폴더입니다. 인스톨러를 사용하지 않으려면: -- **Claude Code**: `agenteye-python-sdk/` 폴더를 `~/.claude/skills/`(모든 프로젝트) 또는 `/.claude/skills/`(해당 레포만)에 복사합니다. Claude Code가 자동으로 인식합니다 — `/skills` 목록을 확인하거나, 일치하는 내용을 질문해보세요. -- **Codex**: Codex는 동일한 `SKILL.md`를 읽습니다. 번들된 `agents/openai.yaml`이 `allow_implicit_invocation: true`로 설정되어 있어 작업이 일치하면 자동 선택됩니다. 그렇지 않으면 `$agenteye-python-sdk`로 호출하세요. +- **Claude Code**: `agenteye-python-sdk/` 폴더를 `~/.claude/skills/`(모든 프로젝트) 또는 `/.claude/skills/`(해당 레포만)에 복사하세요. Claude Code가 자동으로 감지합니다 — `/skills` 목록을 확인하거나, 매칭되는 질문을 해보세요. +- **Codex**: Codex도 동일한 `SKILL.md`를 읽습니다. 번들된 `agents/openai.yaml`이 `allow_implicit_invocation: true`로 설정되어 있어 작업이 매칭되면 자동 선택됩니다. 그렇지 않으면 `$agenteye-python-sdk`로 직접 호출하세요. -계측하려는 코드가 있는 **레포지토리에서** 에이전트를 실행하세요 — 스킬은 무엇을 제안하기 전에 에이전트 루프를 먼저 읽습니다. +계측하려는 코드가 있는 **레포지토리 내에서** 에이전트를 실행하세요 — 스킬이 무언가를 제안하기 전에 에이전트 루프를 먼저 읽습니다. -## 세션 예시 +## 세션이 어떻게 진행되는지 ```text you ▸ 이 에이전트에 Failproof AI Observability를 추가해줘. -agent ▸ 루프를 확인했습니다 — tools.py에 도구 디스패처 하나, llm.py에 - Anthropic 래퍼 하나. 코드 작성 전에 두 가지 질문이 있습니다. +agent ▸ 루프를 읽었습니다 — tools.py에 툴 디스패처 하나, + llm.py에 Anthropic 래퍼 하나. 코드 작성 전에 두 가지 질문이 있습니다. - 하나의 실행이란 무엇인가요? 요청을 동시에 처리하므로 ctx.request_id에 - 이미 있는 요청 id를 사용하는 게 좋을 것 같습니다 — 그러면 여기서의 - 세션과 로그의 요청이 동일한 문자열이 됩니다. + 하나의 실행 단위는 무엇인가요? 요청을 동시에 처리하고 있으니, + ctx.request_id에 이미 있는 요청 id를 사용하는 게 좋겠습니다 — + 그러면 여기서의 세션과 로그의 요청이 같은 문자열이 됩니다. - 그리고 행위자는 누구인가요? planner 경로와 researcher 경로가 보입니다. - 별도로 레이블링할까요, 아니면 하나의 에이전트로 볼까요? + 행위자는 누구인가요? 플래너 경로와 리서처 경로가 보입니다. + 각각 따로 레이블을 붙일까요, 아니면 하나의 에이전트로 보시나요? -you ▸ 요청 id가 맞아. 하나의 에이전트야, "assistant"로 불러. +you ▸ 요청 id가 맞아요. 하나의 에이전트로, "assistant"라고 부르세요. -agent ▸ 완료했습니다. 디스패처와 LLM 클라이언트를 래핑했고, agent_start와 - agent_end가 에러 경로를 포함해 handle_request를 감쌉니다. - Identity에는 컨텍스트 로컬을 사용했습니다 — 디스패처가 도구를 스레드 - 풀에서 실행하는데, 더 간단한 방법을 쓰면 동시 실행 결과가 하나의 세션에 - 섞여도 아무 경고가 없었을 겁니다. +agent ▸ 완료했습니다. 디스패처와 LLM 클라이언트를 래핑했습니다. + agent_start와 agent_end가 에러 경로를 포함한 handle_request를 + 괄호로 감쌉니다. 아이덴티티는 컨텍스트 로컬로 처리했습니다 — + 디스패처가 스레드 풀에서 툴을 실행하는데, 단순한 방법을 쓰면 + 동시 실행이 불평 없이 하나의 세션으로 섞였을 것입니다. - 실제 실행으로 검증했습니다: 4개 파일에 걸쳐 11개 이벤트 — + 실제 실행으로 검증했습니다: 4개 파일에 11개 이벤트 — agent_start, model_request/response, tool_use/tool_result x3, - agent_end (outcome=success). environment=production, 요청당 하나의 - 세션, 지속 시간 짝 맞춤. + agent_end (outcome=success). environment=production, 요청당 + 세션 1개, 기간 쌍 맞음. - 하지 않은 것 하나: batch.py의 워커 풀이 executor에 직접 제출하므로 - 거기서 발행된 이벤트는 드롭됩니다. 그것도 수정할까요? + 한 가지 하지 않은 것: batch.py의 워커 풀이 익스큐터에 + 직접 제출하므로, 거기서 발생하는 이벤트는 드롭됩니다. + 그것도 수정할까요? ``` -주목할 패턴: 제안하기 전에 코드를 먼저 읽었고, 개발자만 답할 수 있는 질문만 했으며, 이미 갖고 있던 id를 재사용하고, 스레드 풀을 확인했기 때문에 동시성에 안전한 방식을 선택했고, 성공을 선언하는 대신 **실제 이벤트를 읽어 검증**한 뒤 — 조용히 실패할 것을 알고 있는 곳을 표시했습니다. +주목할 패턴: 제안 전에 코드를 읽었고, 당신만 답할 수 있는 질문만 했으며, 이미 있는 id를 재사용하고, 스레드 풀을 *봤기 때문에* 동시성 안전 방식을 선택했고, 성공을 선언하는 대신 **실제 이벤트를 읽어 검증**했으며, 조용히 실패할 것으로 아는 한 곳을 명시적으로 알렸습니다. -## 질문할 수 있는 것들 +## 물어볼 수 있는 것들 -- *"내 에이전트가 왜 대시보드에 안 보이지?"* → 단계적으로 확인합니다: 이벤트가 기록되고 있는지, `agent_start`가 있는지, 환경이 올바른지, 수집기가 같은 위치를 읽고 있는지. -- *"모든 것이 dev에 기록되고 있어."* → 환경이 설정되지 않았거나, 이후 호출에서 재설정되었습니다. -- *"토큰 추적을 추가해줘."* → LLM 래퍼를 찾아 모델, 중지 이유, 사용량을 기록합니다. -- *"서브 에이전트도 계측해줘."* → 하나의 세션, 구별되는 에이전트 레이블, 부모 아래 중첩됩니다. -- *"계측 테스트를 작성해줘."* → SDK가 임시 디렉터리를 가리키게 하고 기록된 이벤트를 어서트합니다. +- *"내 에이전트가 왜 대시보드에 안 보이지?"* → 단계별로 확인: 이벤트가 기록되고 있는가, `agent_start`가 있는가, 환경이 맞는가, 컬렉터가 같은 위치를 읽고 있는가. +- *"모든 게 dev로 기록되고 있어요."* → 환경이 한 번도 설정되지 않았거나, 이후 호출에서 재설정됐습니다. +- *"토큰 추적을 추가해줘."* → LLM 래퍼를 찾아 모델, 중단 이유, 사용량을 기록합니다. +- *"서브 에이전트도 계측해줘."* → 하나의 세션, 별개의 에이전트 레이블, 부모 아래에 중첩. +- *"계측 테스트를 작성해줘."* → SDK를 임시 디렉터리로 향하게 하고 기록된 이벤트를 검증합니다. ## 주의할 점 -**검증 단계를 실행하게 하세요.** 이 스킬을 가치 있게 만드는 단계는 마지막 단계입니다 — 에이전트를 실행하고 이벤트를 다시 읽는 것. 계측을 작성하고 멈추는 에이전트는 쉬운 절반만 한 것이며, 조용히 실패하는 절반이 나머지입니다. +**검증 단계를 실행하게 하세요.** 이 스킬을 가치 있게 만드는 단계는 마지막 단계입니다 — 에이전트를 실행하고 이벤트를 읽어오는 것입니다. 계측 코드만 작성하고 멈춘 에이전트는 쉬운 절반만 한 것이며, 조용히 실패하는 절반이 바로 나머지입니다. -**코드 전에 이름을 합의하세요.** `session_id`와 `agent_id`는 모든 화면이 그룹화하는 기준 축입니다. 나중에 이름을 바꾸면 히스토리가 분리됩니다: 이전 실행은 옛 레이블을 유지하고 트렌드가 깨집니다. 스킬이 질문할 것이고, 답변은 잠깐의 생각을 충분히 투자할 가치가 있습니다. +**코드 전에 이름을 확정하세요.** `session_id`와 `agent_id`는 모든 화면이 그룹화하는 축입니다. 나중에 이름을 바꾸면 히스토리가 분리됩니다. 이전 실행은 예전 레이블을 유지하고 트렌드가 깨집니다. 스킬이 질문할 것입니다. 답은 1분만 생각해볼 가치가 있습니다. -**에이전트가 공개 인덱스에서 SDK를 설치하자고 제안한다면, 스킬이 로드되지 않은 것입니다.** SDK는 프라이빗으로 배포됩니다. 그 제안은 코딩 에이전트가 스킬을 따르지 않고 추측하고 있다는 확실한 신호입니다 — 거기서 멈추고 스킬이 설치됐는지 확인하세요. +**에이전트가 공개 인덱스에서 SDK를 설치하려고 제안한다면, 스킬이 로드되지 않은 것입니다.** SDK는 프라이빗으로 배포됩니다. 그런 제안은 코딩 에이전트가 스킬을 따르는 게 아니라 추측하고 있다는 신호입니다 — 거기서 멈추고 스킬이 설치되어 있는지 확인하세요. -그 외에는 영향 범위가 작습니다: 작업 디렉터리에 코드를 작성하고 지정한 위치에 이벤트 파일을 작성합니다. 배포에서는 아무것도 읽지 않고 변경하지도 않습니다. +그 외에 스킬의 영향 범위는 작습니다. 작업 디렉터리에 코드를 쓰고, 지정한 위치에 이벤트 파일을 씁니다. 배포에서 아무것도 읽지 않고 아무것도 변경하지 않습니다. ## 다음 단계 -- **[Python SDK](/ko/agenteye/python-sdk)**: 이 스킬이 자동화하는 것의 배경이 되는 완전한 이벤트 레퍼런스 — 모든 이벤트 타입과 필드. -- **[Sessions](/ko/agenteye/sessions)**: 이벤트가 기록된 후 계측이 생성하는 것. -- **[Evaluator Agent Skill](/ko/agenteye/evaluator-skill)**: 실행이 기록되기 시작한 후 다음 단계 — 평가. -- **[CLI Agent Skill](/ko/agenteye/cli-skill)**: 텔레메트리 결과 조회. \ No newline at end of file +- **[Python SDK](/ko/agenteye/python-sdk)**: 이 스킬이 자동화하는 것의 기반인 완전한 이벤트 레퍼런스 — 모든 이벤트 타입과 필드. +- **[Sessions](/ko/agenteye/sessions)**: 이벤트가 도달하면 계측이 만들어내는 것. +- **[Evaluator Agent Skill](/ko/agenteye/evaluator-skill)**: 실행이 기록되기 시작한 다음 단계 — 점수화. +- **[CLI Agent Skill](/ko/agenteye/cli-skill)**: 텔레메트리 읽어오기. \ No newline at end of file diff --git a/docs/ko/agenteye/python-sdk.mdx b/docs/ko/agenteye/python-sdk.mdx index 7bf29eb5..2a829f56 100644 --- a/docs/ko/agenteye/python-sdk.mdx +++ b/docs/ko/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "AI 에이전트가 프로덕션에서 수행한 모든 작업을 확인하세요: 모든 에이전트 실행, 툴 호출, 모델 요청, hook, 그리고 사람의 개입까지." +description: "AI 에이전트가 프로덕션에서 수행한 모든 작업을 확인하세요: 모든 에이전트 실행, 툴 호출, 모델 요청, 훅, 그리고 사람의 개입까지." --- -AI 에이전트가 프로덕션에서 수행한 모든 작업을 확인하세요: 모든 에이전트 실행, 툴 호출, 모델 요청, hook, 그리고 사람의 개입까지. Failproof AI Observability Python SDK는 에이전트 코드 내부에서 그 기록을 남겨 디버깅, 감사, 평가에 활용할 수 있게 해줍니다. 에이전트를 Failproof AI Observability로 관찰하고 싶을 때마다 사용하세요. +AI 에이전트가 프로덕션에서 수행한 모든 작업을 확인하세요: 모든 에이전트 실행, 툴 호출, 모델 요청, 훅, 그리고 사람의 개입까지. Failproof AI Observability Python SDK는 에이전트 코드 내부에서 해당 내역을 기록하여 디버깅, 감사, 그리고 발생한 일을 평가할 수 있게 합니다. Failproof AI Observability로 에이전트를 모니터링하고 싶을 때 사용하세요. -내부적으로 SDK는 구조화된 이벤트를 로컬 JSONL 파일에 기록하며, 콜렉터 데몬이 이를 감지해 플랫폼으로 자동 전송합니다. 파일을 직접 관리할 필요가 없습니다. +내부적으로 SDK는 구조화된 이벤트를 로컬 JSONL 파일에 기록하며, 수집기 데몬이 이를 감지하여 자동으로 플랫폼에 전송합니다. 해당 파일을 직접 관리할 필요가 없습니다. -> **팁:** Failproof AI Observability가 처음이신가요? 이 페이지는 SDK 이벤트의 완전한 레퍼런스입니다. +> **팁:** Failproof AI Observability가 처음이신가요? 이 페이지는 전체 SDK 이벤트 레퍼런스입니다.
@@ -18,15 +18,15 @@ AI 에이전트가 프로덕션에서 수행한 모든 작업을 확인하세요 ## 설치 -SDK는 공개 패키지 인덱스가 아닌 프라이빗 휠로 고객에게 배포됩니다. 온보딩 과정에서 취득, 설치, 버전 고정 방법을 안내받게 됩니다. 접근 권한이 필요하면 Failproof AI 담당자에게 문의하세요. +SDK는 공개 패키지 인덱스가 아닌 프라이빗 wheel 파일 형태로 고객에게 배포됩니다. 획득 방법, 설치 방법, 버전 고정 방법은 온보딩 과정에서 안내됩니다. 접근 권한이 필요하다면 Failproof AI 담당자에게 문의하세요. -설치 후 다음 명령으로 확인하세요: +설치 후 다음 명령으로 설치 여부를 확인하세요: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -코딩 에이전트가 전체 통합을 처리하게 하고 싶으신가요? [Python SDK Agent Skill](/ko/agenteye/python-sdk-skill)은 설치 경로를 파악하고, 계측 지점을 계획·작성하며, 이벤트가 정상적으로 수신되는지 검증합니다. +코딩 에이전트가 전체 통합 작업을 수행하도록 하고 싶으신가요? [Python SDK Agent Skill](/ko/agenteye/python-sdk-skill)은 설치 경로를 파악하고, 계측 지점을 계획하고, 직접 작성하고, 이벤트가 정상적으로 전달되는지 검증합니다. --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### 실제 호출 계측하기 -실제로는 기존 에이전트 코드를 감싸는 방식으로 사용합니다. 모델 호출 앞에 `model_request`를, 뒤에 `model_response`를 배치하면 두 이벤트가 실제 요청을 감싸게 되어 Failproof AI Observability가 두 이벤트를 서로 연결할 수 있습니다: +실제 사용 시에는 기존 에이전트 코드를 감쌉니다. 모델 호출 전에 `model_request`를, 후에 `model_response`를 배치하여 두 이벤트가 실제 요청을 감싸도록 하면 Failproof AI Observability가 두 이벤트를 쌍으로 연결할 수 있습니다: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -툴 호출도 동일한 방식으로 `tool_use`와 `tool_result`를 감싸되, 동일한 `tool_call_id`를 쌍으로 재사용하세요. +툴 호출도 같은 방식으로 `tool_use`와 `tool_result`로 감싸고, 한 쌍에 동일한 `tool_call_id`를 재사용합니다. -아래는 이벤트가 대시보드에 도달했을 때의 모습입니다. 이벤트 유형별로 색상이 구분되며 환경, 에이전트, 세션별로 필터링할 수 있습니다: +아래는 이벤트들이 대시보드에 도달했을 때의 모습으로, 유형별로 색상이 구분되며 환경, 에이전트, 세션별로 필터링할 수 있습니다: -![이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 라이브 이벤트 스트림](/agenteye/images/events-stream.png) +![이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 실시간 이벤트 스트림](/agenteye/images/events-stream.png) --- @@ -113,23 +113,23 @@ agenteye.configure( ) ``` -`event.*` 호출 전에 한 번 호출하세요. 생략해도 안전하며, 기본값만으로도 바로 사용할 수 있습니다. 모든 인수는 키워드 전용이므로 위와 같이 이름으로 전달하세요. +`event.*` 호출 이전에 한 번만 호출합니다. 생략해도 무방하며, 기본값으로도 바로 동작합니다. 모든 인자는 키워드 전용이므로 위와 같이 이름으로 전달하세요. -`base_dir`가 `None`(기본값)인 경우, SDK는 `$AGENTEYE_HOME`이 설정되어 있으면 해당 값을 사용하고, 그렇지 않으면 `~/.agenteye`로 폴백합니다. 이는 콜렉터 자체의 경로 결정 방식과 동일하므로, `AGENTEYE_HOME` 환경 변수 하나로 SDK와 콜렉터가 공유하는 이벤트 스풀을 설정할 수 있습니다. +`base_dir`가 `None`(기본값)인 경우, SDK는 `$AGENTEYE_HOME`이 설정되어 있으면 이를 사용하고, 그렇지 않으면 `~/.agenteye`로 폴백합니다. 이는 수집기 자체의 경로 해석 방식과 동일하므로, `AGENTEYE_HOME` 환경 변수 하나로 SDK와 수집기 모두의 공유 이벤트 스풀을 설정할 수 있습니다. --- -## 환경 +## 환경(Environment) -모든 이벤트에 배포 환경을 나타내는 레이블(`production`, `staging`, `qa`, `canary` 등)을 지정하세요. 한 번만 설정하면 SDK가 모든 이벤트에 자동으로 첨부합니다. +모든 이벤트에 배포 환경 레이블(`production`, `staging`, `qa`, `canary` 등)을 지정합니다. 한 번만 설정하면 SDK가 모든 이벤트에 자동으로 첨부합니다. -**방법 1: `configure()`를 통해 설정:** +**방법 1: `configure()`를 통해:** ```python agenteye.configure(environment="production") ``` -**방법 2: 환경 변수를 통해 설정:** +**방법 2: 환경 변수를 통해:** ```bash export AGENTEYE_ENVIRONMENT=production @@ -137,34 +137,34 @@ export AGENTEYE_ENVIRONMENT=production **우선순위:** `configure(environment=...)`가 환경 변수보다 우선합니다. 둘 다 설정되지 않은 경우 기본값은 `"dev"`입니다. -환경 값은 대시보드의 1급 필터로 표시되며, 빠른 쿼리를 위해 서버에 저장됩니다. +환경 값은 대시보드에서 일급 필터로 표시되며, 빠른 쿼리를 위해 서버에 저장됩니다. -> **경고:** 환경 값에는 리터럴 `,` 쉼표를 포함할 수 없습니다. 대시보드 필터는 와이어에서 쉼표로 구분된 다중 선택 방식을 사용(`?environment=prod,staging`)하므로, `prod,blue`라는 이름의 환경은 두 개의 값으로 분리됩니다. 쉼표가 포함된 환경의 이벤트는 수집 시 거부됩니다. +> **경고:** 환경 값에는 쉼표(`,`)를 직접 포함할 수 없습니다. 대시보드 필터는 와이어 상에서 쉼표로 구분된 다중 선택 방식을 사용하므로(`?environment=prod,staging`), `prod,blue`와 같이 쉼표가 포함된 환경 이름은 두 개의 값으로 분리됩니다. 쉼표가 포함된 환경의 이벤트는 수집 시 거부됩니다. --- -## 데이터 및 개인정보 보호 +## 데이터 및 프라이버시 -SDK는 명시적으로 전달한 필드만 기록합니다. 프롬프트, 메시지, 툴 입출력, 모델 콘텐츠는 `event.*` 호출에 전달할 때만 캡처됩니다. 프로세스에서 암묵적으로 읽거나 캡처하는 정보는 없습니다. 설정하지 않은 필드는 이벤트에서 완전히 제외되며 디스크에도 기록되지 않습니다. +SDK는 명시적으로 전달한 필드만 기록합니다. 프롬프트, 메시지, 툴 입출력, 모델 콘텐츠는 오직 `event.*` 호출에 직접 전달할 때만 캡처됩니다. 프로세스에서 암묵적으로 읽거나 캡처되는 것은 없습니다. 설정하지 않은 필드는 이벤트에서 완전히 생략되며 디스크에도 기록되지 않습니다. -따라서 데이터 삭제는 전적으로 여러분의 선택이자 책임입니다. 프롬프트나 툴 페이로드에 저장하고 싶지 않은 개인정보나 비밀이 포함된 경우, 이벤트 메서드에 전달하기 전에 제거하거나 마스킹하세요. +따라서 난독화(redaction)는 사용자의 선택이자 책임입니다. 프롬프트나 툴 페이로드에 저장하고 싶지 않은 개인정보(PII)나 시크릿이 포함된 경우, 이벤트 메서드에 전달하기 전에 제거하거나 마스킹하세요. --- ## 이벤트 레퍼런스 -대부분의 이벤트는 상관 ID를 공유하는 시작/종료 쌍으로 구성됩니다: `tool_use`와 `tool_result`는 `tool_call_id`를 공유하고, `hook_triggered`와 `hook_completed`는 `hook_id`를 공유하며, `human_wait`와 `human_input`은 `input_id`를 공유합니다. 시작 이벤트를 발행하고 작업을 수행한 뒤, 동일한 ID로 종료 이벤트를 발행하세요. Failproof AI Observability가 쌍을 매칭하고 `duration_ms`를 자동으로 계산하므로 직접 전달할 필요가 없습니다. +대부분의 이벤트는 상관 ID를 공유하는 시작/종료 쌍으로 이루어집니다: `tool_use`와 `tool_result`는 `tool_call_id`를 공유하고, `hook_triggered`와 `hook_completed`는 `hook_id`를 공유하며, `human_wait`와 `human_input`은 `input_id`를 공유합니다. 시작 이벤트를 발행하고, 작업을 수행한 다음, 동일한 ID로 종료 이벤트를 발행하세요. Failproof AI Observability가 쌍을 매칭하고 `duration_ms`를 자동으로 계산해주므로, `duration_ms`를 직접 전달할 필요가 없습니다. -![페어드 이벤트로 재구성된 실행 그래프 및 타임라인과 툴/모델/hook 분류 패널이 나란히 표시된 세션 상세 화면](/agenteye/images/session-detail.png) +![쌍을 이루는 이벤트로 복원된 에이전트 실행의 git 스타일 실행 그래프와 이벤트 타임라인, 그리고 툴/모델/훅 분석 패널](/agenteye/images/session-detail.png) -모든 이벤트 메서드에는 다음 두 필드가 필요합니다: +모든 이벤트 메서드에는 다음 두 필드가 필수입니다: | 필드 | 타입 | 설명 | |---|---|---| | `session_id` | `str` | 최상위 에이전트 실행을 식별합니다 | | `agent_id` | `str` | 세션 내에서 이벤트를 발행한 에이전트를 식별합니다 | -모든 메서드는 커스텀 메타데이터를 위한 임의의 `**kwargs`도 허용합니다([커스텀 필드](#custom-fields) 참고). +모든 메서드는 커스텀 메타데이터를 위한 임의의 `**kwargs`도 허용합니다([커스텀 필드](#커스텀-필드) 참조). --- @@ -200,7 +200,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -에이전트가 툴을 호출할 때 발행됩니다. `tool_result`와 쌍을 이루며 SDK가 `duration_ms`를 자동 계산합니다. +에이전트가 툴을 호출할 때 발행됩니다. `tool_result`와 쌍을 이루며, SDK가 `duration_ms`를 자동으로 계산합니다. ```python agenteye.event.tool_use( @@ -251,7 +251,7 @@ agenteye.event.model_request( ) ``` -`messages` 항목은 일반 문자열 `content` 또는 Anthropic 스타일의 블록 리스트 `content`를 모두 허용합니다. 샘플링 파라미터(`temperature`, `max_tokens` 등)는 추가 kwargs로 전달할 수 있습니다. +`messages` 항목의 `content`는 일반 문자열 또는 Anthropic 스타일의 블록 리스트 형식을 모두 허용합니다. 샘플링 파라미터(`temperature`, `max_tokens` 등)는 추가 kwargs로 전달할 수 있습니다. --- @@ -274,13 +274,13 @@ agenteye.event.model_response( ) ``` -`content`는 일반 문자열(일반 프로바이더) 또는 Anthropic 스타일의 콘텐츠 블록 리스트를 모두 허용합니다. 툴 호출은 별도의 `tool_calls` 필드 없이 `{"type": "tool_use", ...}` 블록 형태로 `content` 안에 포함됩니다. +`content`는 일반 문자열(범용 프로바이더) 또는 Anthropic 스타일의 콘텐츠 블록 리스트를 허용합니다. 툴 호출은 `content` 안에 `{"type": "tool_use", ...}` 블록으로 포함되며, 별도의 `tool_calls` 필드는 없습니다. --- ### `event.hook_triggered()` -hook이 실행될 때 발행됩니다. `hook_completed`와 쌍을 이루며 SDK가 `duration_ms`를 자동 계산합니다. +훅이 실행될 때 발행됩니다. `hook_completed`와 쌍을 이루며, SDK가 `duration_ms`를 자동으로 계산합니다. ```python agenteye.event.hook_triggered( @@ -297,7 +297,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -hook이 완료될 때 발행됩니다. `hook_id`를 통해 `hook_triggered`와 연결됩니다. +훅이 완료될 때 발행됩니다. `hook_id`를 통해 `hook_triggered`와 연결됩니다. ```python agenteye.event.hook_completed( @@ -330,13 +330,13 @@ agenteye.event.error( --- -## 사람 개입(Human-in-the-Loop) 이벤트 +## Human-in-the-Loop 이벤트 -사람 개입 이벤트는 에이전트 실행 중 사람이 개입하는 순간(승인 대기, 입력 제공, 일시 중지, 에이전트 중단)에 대한 감시를 제공합니다. 이를 통해 사람이 응답하는 데 걸리는 시간을 측정하고(SDK가 페어드 이벤트에서 `duration_ms`를 자동 계산), 에이전트를 일시 중지하거나 중단한 사람을 감사하며, 대시보드에 표시되는 승인 및 감독 워크플로를 구축할 수 있습니다. +Human-in-the-loop 이벤트는 사람이 에이전트 실행에 개입하는 순간(승인 대기, 입력 제공, 일시 중지, 에이전트 중지)에 대한 가시성을 제공합니다. 이를 통해 사람이 응답하는 데 걸리는 시간을 측정하고(SDK가 쌍을 이루는 이벤트에서 `duration_ms`를 자동으로 계산), 누가 에이전트를 일시 중지하거나 중단했는지 감사하며, 대시보드에 표시되는 승인 및 감독 워크플로우를 구축할 수 있습니다. ### `event.human_wait()` -에이전트가 사람의 입력을 기다리기 위해 실행을 일시 중지할 때 발행됩니다. `human_input`과 쌍을 이루며 SDK가 `duration_ms`(사람이 응답하는 데 걸린 시간)를 자동 계산합니다. +에이전트가 사람의 입력을 기다리며 실행을 일시 중지할 때 발행됩니다. `human_input`과 쌍을 이루며, SDK가 `duration_ms`(사람이 응답하는 데 걸린 시간)를 자동으로 계산합니다. ```python agenteye.event.human_wait( @@ -351,7 +351,7 @@ agenteye.event.human_wait( ### `event.human_input()` -사람이 입력을 제공하고 에이전트가 재개될 때 발행됩니다. `input_id`를 통해 `human_wait`와 연결됩니다. `duration_ms`는 자동으로 계산되므로 호출자가 전달해서는 안 됩니다. +사람이 입력을 제공하고 에이전트가 재개될 때 발행됩니다. `input_id`를 통해 `human_wait`와 연결됩니다. `duration_ms`는 자동으로 계산되므로 호출 측에서 전달해서는 안 됩니다. ```python agenteye.event.human_input( @@ -365,7 +365,7 @@ agenteye.event.human_input( ### `event.human_pause()` -사람이 능동적으로 에이전트를 일시 중지할 때(예: 대시보드 컨트롤을 통해) 발행됩니다. 에이전트는 종료되지 않고 일시 중단됩니다. +사람이 에이전트를 능동적으로 일시 중지할 때 발행됩니다(예: 대시보드 컨트롤을 통해). 에이전트는 종료되지 않고 일시 중단됩니다. ```python agenteye.event.human_pause( @@ -378,7 +378,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -사람이 에이전트를 실행 중에 능동적으로 중단시킬 때 발행됩니다. `human_pause`와 달리 에이전트의 작업이 일시 중단이 아닌 종료됩니다. +사람이 실행 중인 에이전트를 능동적으로 중지할 때 발행됩니다. `human_pause`와 달리, 에이전트의 작업이 일시 중단이 아닌 종료됩니다. ```python agenteye.event.human_interrupt( @@ -394,7 +394,7 @@ agenteye.event.human_interrupt( ## 커스텀 필드 -추가 키워드 인수는 표준 필드 뒤에 이벤트에 추가됩니다: +추가 키워드 인자는 표준 필드 뒤에 이벤트에 추가됩니다: ```python agenteye.event.tool_use( @@ -407,27 +407,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type`, `environment`는 예약된 이름으로, 커스텀 필드로 전달하면 `ValueError`(`Reserved field names cannot be used as custom fields: [...]`)가 발생합니다. `session_id`와 `agent_id`는 모든 이벤트 메서드의 필수 파라미터이므로 두 번 제공할 수 없으며, 그렇게 하면 Python이 `TypeError`를 발생시킵니다. 환경은 `configure(environment=...)`(또는 `AGENTEYE_ENVIRONMENT` 변수)로 설정하세요. +`timestamp`, `type`, `environment`는 예약된 필드명으로, 커스텀 필드로 전달하면 `ValueError`(`Reserved field names cannot be used as custom fields: [...]`)가 발생합니다. `session_id`와 `agent_id`는 모든 이벤트 메서드의 필수 파라미터이므로 두 번 전달할 수 없으며, 그럴 경우 Python이 `TypeError`를 발생시킵니다. 환경 설정은 `configure(environment=...)`(또는 `AGENTEYE_ENVIRONMENT` 변수)를 사용하세요. -필드를 쿼리하고 싶다면 페이로드를 구조화된 JSON으로 유지하세요. JSON이 기본적으로 지원하지 않는 값(datetime, UUID, decimal, set, bytes, 모델 객체 등)은 기록이 안전하게 계속될 수 있도록 문자열로 변환됩니다. +필드 값을 쿼리하려면 구조화된 JSON 형태로 페이로드를 유지하세요. JSON이 기본적으로 지원하지 않는 값(datetime, UUID, decimal, set, bytes, 모델 객체 등)은 문자열로 변환되어 기록이 안전하게 계속됩니다. --- ## 이벤트 기록 방식 -이벤트는 프로세스 내에 버퍼링되었다가 `flush_interval`초마다(기본값 500ms) 디스크에 플러시됩니다. 각 플러시는 하나의 JSONL 파일을 작성합니다: +이벤트는 프로세스 내에 버퍼링되었다가 `flush_interval`초(기본값 500ms)마다 디스크에 플러시됩니다. 각 플러시는 하나의 JSONL 파일을 기록합니다: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -콜렉터는 이 디렉터리를 감시하고 파일을 자동으로 업로드합니다. 파일을 직접 관리할 필요가 없습니다. +수집기가 이 디렉토리를 감시하고 파일을 자동으로 업로드합니다. 이 파일들을 직접 관리할 필요가 없습니다. -각 파일은 원자적으로 작성됩니다: SDK가 임시 파일에 쓴 다음 제자리로 이름을 변경하므로 콜렉터가 절반만 쓰인 파일을 볼 일이 없습니다. 프로세스가 종료될 때도 최종 플러시가 실행되므로 마지막 인터벌에 버퍼링된 이벤트가 유실되지 않습니다. 콜렉터가 오프라인 상태인 경우 이벤트는 디스크에 파일로 쌓여 있다가 콜렉터가 복구되면 전송됩니다. +각 파일은 원자적으로 기록됩니다: SDK가 임시 파일에 먼저 기록한 뒤 이름을 변경하는 방식으로, 수집기가 불완전하게 쓰여진 파일을 읽는 일이 없습니다. 프로세스 종료 시에도 최종 플러시가 실행되므로 마지막 인터벌에 버퍼링된 이벤트가 유실되지 않습니다. 수집기가 오프라인 상태인 경우, 이벤트는 단순히 디스크에 파일로 누적되었다가 수집기가 복구되면 전송됩니다. --- ## 다음 단계 -- [이벤트 스트림](/ko/agenteye/event-stream): 이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 라이브 이벤트 스트림을 확인하세요. -- [세션](/ko/agenteye/sessions): 페어드 이벤트가 각 에이전트 실행을 실행 그래프 및 타임라인으로 어떻게 재구성하는지 확인하세요. \ No newline at end of file +- [이벤트 스트림](/ko/agenteye/event-stream): 이벤트가 실시간으로 도착하는 것을 확인하고, 유형별로 색상이 구분되며 환경, 에이전트, 세션별로 필터링합니다. +- [세션](/ko/agenteye/sessions): 쌍을 이루는 이벤트들이 각 에이전트 실행을 실행 그래프와 타임라인으로 어떻게 복원하는지 확인합니다. \ No newline at end of file diff --git a/docs/ko/agenteye/queries.mdx b/docs/ko/agenteye/queries.mdx index a5541fd3..23655277 100644 --- a/docs/ko/agenteye/queries.mdx +++ b/docs/ko/agenteye/queries.mdx @@ -1,56 +1,56 @@ --- title: "쿼리" -description: "에이전트 데이터에 어떤 질문이든 던지고 몇 초 안에 답을 얻으세요." +description: "에이전트 데이터에 대한 질문을 하고 몇 초 안에 답을 받으세요." --- -에이전트 데이터에 어떤 질문이든 던지고 몇 초 안에 답을 얻으세요. Failproof AI Observability는 이벤트와 평가 데이터에 대한 저장된 실행 가능 쿼리 라이브러리를 제공합니다. 빈 SQL 편집기 대신 이미 동작하는 예제에서 바로 시작할 수 있습니다. +에이전트 데이터에 대한 어떤 질문이든 물어보고 몇 초 안에 답을 받으세요. Failproof AI Observability는 이벤트와 평가 데이터를 대상으로 바로 실행할 수 있는 저장된 쿼리 라이브러리를 제공하므로, 빈 SQL 편집기 대신 이미 동작하는 예제에서 시작할 수 있습니다. -![저장된 쿼리 라이브러리: 기본 제공 프리셋과 사용자 지정 쿼리가 함께 표시된 그리드](/agenteye/images/queries.png) +![저장된 쿼리 라이브러리: 기본 제공 프리셋과 사용자 정의 쿼리가 모두 표시된 그리드](/agenteye/images/queries.png) -*`//queries`에 있는 저장된 쿼리 라이브러리: 기본 제공 프리셋과 팀이 저장한 쿼리가 나란히 배치됩니다.* +*`//queries`에 있는 저장된 쿼리 라이브러리: 기본 제공 프리셋과 팀이 저장한 쿼리가 나란히 표시됩니다.* -## 빈 페이지가 아닌 프리셋에서 시작하세요 +## 빈 페이지가 아닌 프리셋에서 시작하기 -테이블 이름을 외우거나 SQL을 처음부터 작성할 필요가 없습니다. 라이브러리는 팀이 가장 자주 묻는 질문에 맞춘 기본 제공 프리셋과 함께 열리며, 팀이 저장하고 이름을 붙인 쿼리도 바로 옆에 표시됩니다. 원하는 내용에 가까운 것을 선택하면 이미 답의 절반에 도달한 셈입니다. +테이블 이름을 외우거나 SQL을 처음부터 작성할 필요가 없습니다. 라이브러리는 팀이 가장 자주 묻는 질문에 대한 기본 제공 프리셋과 함께 열리며, 팀이 저장하고 이름을 붙인 쿼리 바로 옆에 위치합니다. 원하는 것에 가까운 프리셋을 하나 선택하면 답을 얻기까지 대부분의 과정이 완료됩니다. -모든 저장된 쿼리는 조직 단위로 범위가 지정되고 공유되므로, 팀원이 작성한 유용한 쿼리가 나의 것이 되기도 합니다. 쿼리에 이름과 설명을 한 번만 붙여두면 조직 내 누구든 찾아서 실행하거나, 나중에 대시보드에 결과를 고정할 수 있습니다. +저장된 쿼리는 모두 조직 범위에서 공유되므로, 팀원이 작성한 유용한 쿼리가 자동으로 내 것이 됩니다. 쿼리에 이름과 설명을 한 번만 붙여두면, 조직 내 누구든 찾아서 실행하거나 나중에 대시보드에 결과를 고정할 수 있습니다. -`//queries`에서 찾을 수 있습니다. +`//queries`에서 확인하세요. -## SQL 작성기에서 수정하고 실행하세요 +## SQL 편집기에서 수정하고 실행하기 -쿼리를 열면 SQL 작성기로 이동하며, 여기서 바로 수정하고 즉시 결과를 확인할 수 있습니다. 내보내기도, 왕복 요청도, 다른 사람을 기다릴 필요도 없습니다. +쿼리를 열면 SQL 편집기로 이동하며, 여기서 쿼리를 수정하고 즉시 결과를 확인할 수 있습니다. 내보내기도, 왕복 과정도, 다른 사람을 기다릴 필요도 없습니다. -![저장된 쿼리를 실행 중인 SQL 작성기 — 스키마 사이드바와 실시간 결과 그리드 포함](/agenteye/images/query-lab.png) +![저장된 쿼리를 실행 중인 SQL 편집기 — 스키마 사이드바와 실시간 결과 그리드가 함께 표시됨](/agenteye/images/query-lab.png) -*SQL 작성기: 왼쪽에 쿼리, 컬럼 이름을 추측하지 않아도 되는 스키마 사이드바, 아래에 실시간 결과 그리드.* +*SQL 편집기: 왼쪽에 쿼리, 컬럼 이름을 추측하지 않아도 되는 스키마 사이드바, 아래에 실시간 결과 그리드.* -- **스키마 사이드바**는 분석 테이블과 해당 컬럼을 정리하여 보여주므로, 필드 이름을 찾아 헤매지 않고도 쿼리를 작성할 수 있습니다. -- **실시간 결과 그리드**는 실행하는 즉시 행을 반환하므로, 반복 작업을 추측 없이 몇 초 만에 처리할 수 있습니다. -- **읽기 전용 설계.** 쿼리는 이벤트 저장소에 대해 실행되며 서버에서 검증됩니다. `SELECT`와 `WITH` 구문만 허용되며, 구문 타임아웃과 행 수 제한이 적용됩니다. 탐색용 쿼리가 데이터를 수정하는 일은 절대 없으며, 과부하 쿼리는 자동으로 중단됩니다. +- **스키마 사이드바**에서 분석 테이블과 컬럼을 한눈에 확인할 수 있어, 필드 이름을 일일이 찾지 않고도 쿼리를 작성할 수 있습니다. +- **실시간 결과 그리드**는 실행 즉시 결과를 반환하므로, 반복 작업을 몇 초 안에 처리할 수 있습니다. +- **읽기 전용 설계.** 쿼리는 이벤트 저장소에 대해 실행되며 서버에서 유효성이 검사됩니다. `SELECT`와 `WITH` 구문만 허용되며, 실행 시간 제한과 행 수 제한이 적용됩니다. 탐색용 쿼리로는 데이터를 절대 수정할 수 없으며, 제어 불가능한 쿼리는 자동으로 중단됩니다. -결과가 마음에 드시나요? 팀 전체가 활용할 수 있도록 라이브러리에 저장하거나, 결과를 라인, 막대, 영역, 파이 타일 형태로 대시보드에 고정하세요. +결과가 만족스럽다면 팀 전체가 활용할 수 있도록 라이브러리에 다시 저장하거나, 결과를 라인, 바, 에어리어, 파이 차트 타일 형태로 대시보드에 고정하세요. -## 터미널에서 실행하거나 AI 어시스턴트에게 작성을 맡기세요 +## 터미널에서 실행하거나 AI 어시스턴트가 작성하도록 하기 -저장된 쿼리는 어디서 작업하든 따라옵니다. +저장된 쿼리는 어디서 작업하든 동일하게 사용할 수 있습니다. -- **터미널에서.** `agenteye` CLI로 동일한 쿼리를 목록 조회, 실행, 저장할 수 있습니다. 결과를 스크립트에 넣거나, CI에 연결하거나, 코딩 에이전트에 전달하는 것도 가능합니다. +- **터미널에서.** `agenteye` CLI를 사용하면 동일한 쿼리를 나열하고, 실행하고, 저장할 수 있어 결과를 스크립트에 바로 활용하거나 CI에 연결하거나 코딩 에이전트에 전달할 수 있습니다. ```bash agenteye query list # 터미널에서 동일한 저장된 쿼리 확인 -agenteye query run errs --arg prod # 실행하고 행 출력 (파이프 연결 시 --json 추가) +agenteye query run errs --arg prod # 쿼리를 실행하고 결과 출력 (파이프 연결 시 --json 추가) ``` - 전체 명령어 목록은 [CLI and agents](/ko/agenteye/cli-and-agents)를 참조하세요. + 전체 명령어 목록은 [CLI 및 에이전트](/ko/agenteye/cli-and-agents)를 참조하세요. -- **AI 어시스턴트에서.** SQL 표현이 어렵다면? 대시보드 내 [AI 어시스턴트](/ko/agenteye/assistant)에게 평범한 언어로 질문하면 쿼리를 작성하고 라이브러리에 저장해 드립니다. +- **AI 어시스턴트에서.** SQL 표현 방법이 불확실한가요? 대시보드 내 [AI 어시스턴트](/ko/agenteye/assistant)에 일반 영어로 질문하면 쿼리를 작성하고 라이브러리에 저장해 드립니다. -저장된 쿼리 실행은 `queries:run` 권한으로 제어되며, 쿼리 생성 및 삭제 권한과 별도로 분리되어 있습니다. 따라서 라이브러리 수정 권한 없이 읽기 전용 접근만 부여할 수 있습니다. +저장된 쿼리 실행은 `queries:run` 권한으로 제어되며, 쿼리 생성 또는 삭제 권한과 별도로 관리됩니다. 따라서 모든 사람이 라이브러리를 수정하지 않고도 읽기 권한만 부여할 수 있습니다. -## 관련 문서 +## 관련 항목 -- [Dashboards](/ko/agenteye/dashboards): 쿼리 결과를 조직 전체가 공유하는 차트에 고정합니다. -- [AI assistant](/ko/agenteye/assistant): 평범한 언어로 질문하고 쿼리를 받아보세요. -- [CLI and agents](/ko/agenteye/cli-and-agents): 터미널에서 동일한 쿼리를 실행하고 저장합니다. \ No newline at end of file +- [대시보드](/ko/agenteye/dashboards): 쿼리 결과를 조직 전체가 공유하는 차트에 고정하기. +- [AI 어시스턴트](/ko/agenteye/assistant): 일반 언어로 질문하고 쿼리 결과 받기. +- [CLI 및 에이전트](/ko/agenteye/cli-and-agents): 터미널에서 동일한 쿼리를 실행하고 저장하기. \ No newline at end of file diff --git a/docs/ko/agenteye/security.mdx b/docs/ko/agenteye/security.mdx index 76a950c7..a85b4c76 100644 --- a/docs/ko/agenteye/security.mdx +++ b/docs/ko/agenteye/security.mdx @@ -1,68 +1,68 @@ --- title: "보안" -description: "Failproof AI Observability는 프로덕션 에이전트 가까이에서 동작하도록 설계되어 있으며, 프롬프트, 도구 입력값, 출력값을 모두 처리합니다." +description: "Failproof AI Observability는 프로덕션 에이전트 가까이에서 동작하도록 설계되어, 프롬프트, 툴 입력, 출력 데이터를 모두 처리합니다." --- -Failproof AI Observability는 프로덕션 에이전트 가까이에서 동작하도록 설계되어 있으며, 프롬프트, 도구 입력값, 출력값을 모두 처리합니다. 이 페이지에서는 해당 데이터를 격리하고, 통제하며, 여러분의 손에 유지하는 방법을 설명합니다. 보안 검토를 위해 Failproof AI Observability를 평가 중이라면 여기서 시작하세요. +Failproof AI Observability는 프로덕션 에이전트 가까이에서 동작하도록 설계되어, 프롬프트, 툴 입력, 출력 데이터를 모두 처리합니다. 이 페이지에서는 해당 데이터를 어떻게 격리하고, 통제하며, 사용자의 손에 유지하는지 설명합니다. 보안 검토를 위해 Failproof AI Observability를 평가 중이라면 여기서부터 시작하세요. --- -## 데이터는 여러분의 환경에 보관됩니다 +## 데이터는 사용자 환경에 머뭅니다 -Failproof AI Observability는 자체 호스팅 방식입니다. 이벤트, 프롬프트, 모델 응답, 분석 데이터는 모두 여러분 자신의 환경에 있는 데이터베이스에 저장됩니다. 서드파티 SaaS에 데이터가 전송되거나 저장되지 않으며, 모든 데이터는 여러분의 클라우드 계정 내에 유지됩니다. +Failproof AI Observability는 자체 호스팅 방식입니다. 이벤트, 프롬프트, 모델 응답, 분석 데이터는 모두 사용자 자신의 데이터베이스, 사용자 자신의 환경에 저장됩니다. 서드파티 SaaS로 데이터가 전송되거나 저장되는 일은 없으며, 데이터는 사용자의 클라우드 계정 안에 머뭅니다. --- ## 테넌트 격리 -하나의 Failproof AI Observability 인스턴스에서 여러 조직을 호스팅할 수 있으며, 각 조직은 스토리지 계층에서 격리됩니다. 이 격리는 UI가 아닌 데이터베이스 수준에서 강제됩니다. +하나의 Failproof AI Observability 인스턴스에서 여러 조직을 호스팅할 수 있으며, 각 조직은 스토리지 계층에서 격리됩니다. 이 격리는 UI가 아닌 데이터베이스 자체에서 강제됩니다. -- 조직의 운영 데이터(사용자, 키, 대시보드, 저장된 쿼리)는 해당 조직 범위로 한정되며, 조직 간 데이터 읽기는 데이터베이스 자체에서 차단됩니다. -- 수집된 모든 이벤트에는 소유 조직 정보가 기록되므로, 한 조직의 이벤트를 다른 조직에서 절대 읽을 수 없습니다. +- 조직의 운영 데이터(사용자, 키, 대시보드, 저장된 쿼리)는 해당 조직에만 귀속되며, 조직 간 읽기는 데이터베이스 수준에서 차단됩니다. +- 수집된 모든 이벤트에는 소유 조직이 기록되므로, 한 조직의 이벤트를 다른 조직이 절대 읽을 수 없습니다. -모든 대시보드 라우트는 org 슬러그(`//…`) 하위에 범위가 지정됩니다. +모든 대시보드 라우트는 org slug(`//…`) 아래에서 범위가 지정됩니다. --- ## 로그인 -Failproof AI Observability는 비밀번호 없는 이메일 기반 로그인을 사용합니다. 피싱하거나 유출될 비밀번호 자체가 없습니다. 사용자가 일회용 코드(또는 원클릭 매직 링크)를 요청하면 이메일로 전송되며, 짧은 시간 내에 만료됩니다. 로그인은 **허용 목록**으로 제한됩니다. 여러분이 허용한 이메일 주소(또는 도메인)만 인증할 수 있습니다. +Failproof AI Observability는 비밀번호 없는 이메일 기반 로그인을 사용합니다. 피싱이나 유출의 대상이 되는 비밀번호가 존재하지 않습니다. 사용자가 일회용 코드(또는 원클릭 매직 링크)를 요청하면 이메일로 전송되며, 코드는 빠르게 만료됩니다. 로그인은 **허용 목록(allowlist)** 으로 제어되며, 사용자가 허가한 이메일 주소(또는 도메인)만 인증할 수 있습니다. -![이메일로 일회용 코드를 전송하는 Failproof AI Observability 로그인 화면](/agenteye/images/login.png) +![이메일로 일회용 코드를 발송하는 Failproof AI Observability 로그인 화면](/agenteye/images/login.png) --- -## API 키를 이용한 범위 기반 접근 제어 +## API 키를 통한 범위 지정 접근 -모든 클라이언트는 세분화된 최소 권한을 가진 API 키로 인증합니다. 수집기는 `events:add` 권한만 필요하고, 대시보드 또는 어시스턴트 키는 읽기 전용으로 설정할 수 있습니다. 삭제, 재생성과 같은 파괴적인 작업은 별도의 권한으로 관리하며, 여러분이 직접 부여 여부를 결정합니다. +모든 클라이언트는 세분화된 최소 권한을 가진 API 키로 인증합니다. 콜렉터는 `events:add`만 필요하고, 대시보드나 어시스턴트 키는 읽기 전용으로 설정할 수 있으며, 파괴적인 작업(삭제, 재생성)은 별도로 부여하는 권한입니다. -![각 키의 권한 부여 현황을 읽기, 쓰기, 파괴적 범위별로 색상 구분하여 표시하는 API 키 페이지](/agenteye/images/api-keys.png) +![API 키 페이지: 각 키의 권한이 읽기, 쓰기, 파괴적 범위별로 색상 구분되어 표시됩니다](/agenteye/images/api-keys.png) -관리자 부트스트랩 키는 설정용으로만 보관하고, 그 외 모든 용도에는 제한된 키를 발급하세요. [API 키](/ko/agenteye/api-keys) 문서를 참고하세요. +관리자 부트스트랩 키는 설정용으로만 보관하고, 나머지 용도에는 좁은 범위의 키를 발급하세요. [API 키](/ko/agenteye/api-keys)를 참고하세요. --- ## 읽기 전용, 승인 기반 어시스턴트 -대시보드 내 [AI 어시스턴트](/ko/agenteye/assistant)는 여러분의 데이터를 기반으로 질문에 답변하지만, 설계상 다음과 같은 제약이 있습니다. +대시보드 내 [AI 어시스턴트](/ko/agenteye/assistant)는 사용자 데이터를 기반으로 질문에 답하지만, 설계상 다음과 같이 제한됩니다. -- **기본적으로 읽기 전용**입니다. 어시스턴트의 SQL은 `SELECT`/`WITH` 쿼리만 허용하고, 단일 구문으로 제한되며, 행 수 상한이 적용되는 가드를 통해 실행됩니다. -- 어시스턴트가 생성하는 모든 것(저장된 쿼리, 대시보드)은 **승인 기반**으로 처리됩니다. 모든 쓰기 작업은 실행 전에 여러분이 검토하고 승인해야 합니다. +- **기본적으로 읽기 전용**입니다. 어시스턴트의 SQL은 `SELECT`/`WITH` 쿼리, 단일 구문, 행 수 제한만 허용하는 가드를 통해 실행됩니다. +- 어시스턴트가 생성하는 모든 항목(저장 쿼리, 대시보드)은 **승인 게이팅**됩니다. 쓰기 작업이 실행되기 전에 사용자가 검토하고 승인해야 합니다. - 어시스턴트는 **절대 삭제할 수 없습니다**. -따라서 팀원이 "이번 주에 가장 많이 오류가 발생한 에이전트는 무엇인가요?"라고 묻고 결과를 활용하더라도, 어시스턴트가 스스로 데이터를 변경하거나 삭제하는 것은 불가능합니다. +따라서 팀원이 "이번 주에 가장 많이 오류가 발생한 에이전트는?"이라고 물어보고 결과를 활용할 수 있지만, 어시스턴트가 스스로 데이터를 변경하거나 삭제하는 일은 불가능합니다. --- ## 전송 중 보안 -모든 트래픽은 HTTPS를 통해 전송됩니다. 여러분이 직접 인증서로 TLS를 종료하므로, 수집기-서버 간 및 브라우저-서버 간 트래픽은 전송 중 암호화됩니다. +모든 트래픽은 HTTPS를 통해 전송됩니다. TLS는 사용자 자신의 인증서로 종료되므로, 콜렉터-서버 간 및 브라우저-서버 간 트래픽은 전송 중에 암호화됩니다. --- ## 다음 단계 -- [개요](/ko/agenteye/overview): Failproof AI Observability의 전체 구조를 확인하세요. -- [API 키](/ko/agenteye/api-keys): 수집기, 대시보드, 어시스턴트에 대한 접근 범위를 설정하세요. -- [관찰 가능성](/ko/agenteye/observability): Failproof AI Observability가 에이전트에서 수집하는 정보를 확인하세요. \ No newline at end of file +- [개요](/ko/agenteye/overview): Failproof AI Observability가 어떻게 구성되는지 알아보세요. +- [API 키](/ko/agenteye/api-keys): 콜렉터, 대시보드, 어시스턴트의 접근 범위를 설정하세요. +- [Observability](/ko/agenteye/observability): Failproof AI Observability가 에이전트에서 무엇을 수집하는지 알아보세요. \ No newline at end of file diff --git a/docs/ko/agenteye/sessions.mdx b/docs/ko/agenteye/sessions.mdx index 89aedb5e..30f745d9 100644 --- a/docs/ko/agenteye/sessions.mdx +++ b/docs/ko/agenteye/sessions.mdx @@ -1,14 +1,14 @@ --- title: "세션 & 실행 그래프" -description: "한 번의 실행에서 발생한 모든 이벤트를 하나의 읽기 쉬운 행으로 정리하고, 몇 초 만에 파악할 수 있는 git 스타일의 실행 그래프로 시각화합니다." +description: "실행 중 발생한 모든 이벤트를 하나의 읽기 쉬운 행으로 통합하고, 몇 초 만에 파악할 수 있는 git 스타일 실행 그래프로 시각화합니다." --- -실행이 실패한 이유를 더 이상 추측할 필요가 없습니다. Failproof AI Observability는 한 번의 실행에서 발생한 모든 이벤트를 하나의 읽기 쉬운 행으로 정리하고, 전체 실행 흐름을 몇 초 만에 파악할 수 있는 git 스타일의 그림으로 그려냅니다. 에이전트가 단계별로 정확히 무엇을 했는지 한눈에 확인할 수 있습니다. +실행이 실패한 이유를 추측하는 데 시간을 낭비하지 마세요. Failproof AI Observability는 실행 중 발생한 모든 이벤트를 하나의 읽기 쉬운 행으로 통합하고, 전체 실행 과정을 몇 초 만에 파악할 수 있는 git 스타일 그림으로 그려줍니다. 에이전트가 각 단계에서 정확히 무엇을 했는지 한눈에 확인할 수 있습니다. -![세션 목록: 환경과 에이전트 전반에 걸쳐 실행별로 한 행씩 표시되며, 상태 뱃지와 평가 점수 뱃지가 함께 표시됩니다](/agenteye/images/sessions-list.png) +![세션 목록: 환경과 에이전트 전반에 걸쳐 실행별로 한 행씩 표시되며, 상태 뱃지와 평가 점수 뱃지가 포함됩니다](/agenteye/images/sessions-list.png) -*실행당 한 행: 상태 뱃지를 통해 실행 결과를 한눈에 파악할 수 있으며, 평가자를 연결하면 점수 뱃지도 함께 표시됩니다.* +*실행별로 하나의 행: 상태 뱃지로 실행이 어떻게 종료되었는지 한눈에 파악할 수 있으며, 평가자가 연결되면 점수 뱃지도 함께 표시됩니다.*
@@ -18,40 +18,40 @@ description: "한 번의 실행에서 발생한 모든 이벤트를 하나의 --- -## 모든 실행을 한눈에 파악하기 +## 모든 실행을 한눈에 확인 -원시 이벤트 트레일은 모든 단계의 실제 기록이지만, 수십 번의 실행에 걸쳐 수천 개의 단계가 쌓이면 개별 단계가 아닌 실행 전체를 파악해야 합니다. 세션 페이지는 한 번의 실행에서 발생한 모든 이벤트를 하나의 행으로 집약하여, 하루치 활동을 쏟아지는 로그 대신 스캔 가능한 목록으로 만들어 줍니다. +원시 이벤트 트레일은 모든 단계의 진실을 담고 있지만, 수십 번의 실행에 걸쳐 수천 개의 단계가 쌓이면 개별 단계가 아닌 실행 단위로 바라볼 필요가 있습니다. Sessions 페이지는 한 실행의 모든 이벤트를 하나의 행으로 통합하여, 하루치 활동이 끝없는 로그 스트림이 아닌 한눈에 훑어볼 수 있는 목록이 됩니다. -각 행에는 상태 뱃지가 표시되므로, 클릭하기 전에도 실패한 실행과 정상 실행을 바로 구분할 수 있습니다. 날짜 범위, 환경, 에이전트, 세션으로 필터링하면 몇 번의 클릭만으로 "전체"에서 "내가 찾는 실행"으로 범위를 좁힐 수 있습니다. +각 행에는 상태 뱃지가 표시되므로, 클릭하기 전에도 실패한 실행과 정상적인 실행을 바로 구별할 수 있습니다. 날짜 범위, 환경, 에이전트, 세션으로 필터링하면 "전체 실행" 중에서 "내가 찾는 실행"을 몇 번의 클릭만으로 찾아낼 수 있습니다. -평가자를 연결하면 완료된 모든 실행이 자동으로 점수를 받고, 최신 점수가 뱃지 형태로 해당 행에 표시됩니다. 점수 범위로 필터링할 수 있으므로 "이번 주 프로덕션에서 점수가 낮은 실행만 보기"가 수동 검토가 아닌 필터 하나로 해결됩니다. 평가자를 설정하기 전에도 세션은 전체 실행을 캡처하지만, 점수 뱃지는 아직 표시되지 않습니다. +평가자를 연결하면 완료된 모든 실행이 자동으로 점수를 받고, 최신 점수가 뱃지 형태로 행에 표시됩니다. 점수 범위로 필터링할 수 있으므로 "이번 주 프로덕션 환경에서 낮은 점수를 받은 실행 전체 보기"가 수동 검토가 아닌 단순한 필터 적용으로 해결됩니다. 평가자를 설정하기 전에도 세션은 전체 실행을 캡처하며, 단지 점수 뱃지가 아직 표시되지 않을 뿐입니다. --- -## 전체 실행을 그림으로 읽기 +## 전체 실행을 그림으로 파악 -![이벤트 타임라인 옆에 표시된 세션의 git 스타일 실행 그래프와 도구, 모델, 훅 분석 패널](/agenteye/images/session-detail.png) +![세션의 git 스타일 실행 그래프와 이벤트 타임라인이 나란히 표시되고, 오른쪽 패널에는 도구, 모델, 훅 분석 정보가 있습니다](/agenteye/images/session-detail.png) -*실행 그래프(왼쪽)가 이벤트 타임라인 옆에 표시되며, 오른쪽 패널에서는 실행에 사용된 도구, 모델, 훅, 토큰 소비량을 상세히 확인할 수 있습니다.* +*실행 그래프(왼쪽)가 이벤트 타임라인 옆에 위치하며, 오른쪽 패널에서 해당 실행의 도구, 모델, 훅, 토큰 사용량 내역을 확인할 수 있습니다.* -세션을 클릭하면 실행 그래프가 열립니다. 에이전트, 도구, 훅, 모델 호출이 시간 순서에 따라 어떻게 전개되었는지를 git 스타일로 보여줍니다. 병렬 서브 에이전트는 각각 별도의 레인으로 분기되므로, 어떤 작업이 동시에 실행되었는지, 어떤 서브 에이전트가 지연되었는지, 실행이 어디서 잘못되었는지를 로그 더미를 머릿속으로 다시 재생하지 않고도 파악할 수 있습니다. +세션을 클릭하면 실행 그래프가 열립니다. 이는 에이전트, 도구, 훅, 모델 호출이 시간에 따라 어떻게 펼쳐졌는지를 git 스타일로 보여주는 뷰입니다. 병렬로 실행된 서브 에이전트는 각각 별도의 레인으로 분기되므로, 어떤 작업이 동시에 실행되었는지, 어떤 서브 에이전트가 멈췄는지, 실행이 어디서 어긋났는지를 방대한 로그를 머릿속으로 재현하지 않고도 파악할 수 있습니다. -오른쪽 패널에서는 실행별 세부 내역을 확인할 수 있습니다. 어떤 도구와 모델이 실행되었는지, 어떤 훅이 실행되었는지, 해당 실행에서 토큰을 얼마나 소비했는지가 그래프 바로 옆에 표시됩니다. "이 실행은 왜 이렇게 비쌌지?" 또는 "느린 도구가 뭐지?"에 대한 답이 바로 거기 있습니다. +오른쪽 패널은 실행별 세부 내역을 제공합니다. 어떤 도구와 모델이 실행되었는지, 어떤 훅이 발동되었는지, 해당 실행에서 토큰을 얼마나 사용했는지를 원인이 된 그래프 바로 옆에서 확인할 수 있습니다. "이 실행 비용이 왜 이렇게 많이 나왔지?" 또는 "느린 도구가 어느 것이지?"에 대한 답이 바로 그 자리에 있습니다. -개별 이벤트에는 고유 링크가 있으므로, "세션에서 3분의 2 지점쯤"이라고 설명하는 대신 특정 순간의 링크를 바로 공유할 수 있습니다. 이벤트에서 링크를 복사하거나, [감사](/ko/agenteye/audits) 결과나 오류에서 링크를 따라가면 해당 이벤트가 선택되고 스크롤된 상태로 세션이 열립니다. 매우 긴 실행에서도 마찬가지입니다. 타임라인은 브라우저 성능을 위해 제한된 범위를 로드하지만, 해당 범위를 벗어난 이벤트를 가리키는 링크도 시작 지점으로 떨어지지 않고 해당 이벤트를 정확히 찾아줍니다. 이벤트가 보존 기간을 초과한 경우, 페이지는 아무것도 선택하지 않고 넘어가는 대신 그 사실을 명시적으로 알려줍니다. +개별 이벤트는 주소 지정이 가능하므로, "세션에서 약 3분의 2 지점쯤"이 아니라 특정 순간에 대한 링크를 공유할 수 있습니다. 이벤트에서 링크를 복사하거나, [감사](/ko/agenteye/audits) 결과나 오류에서 링크를 따라가면 해당 이벤트가 선택된 상태로 세션이 열립니다. 매우 긴 실행에서도 마찬가지입니다. 타임라인은 브라우저 성능을 위해 제한된 범위만 로드하지만, 그 범위 밖을 가리키는 링크도 처음으로 돌아가지 않고 해당 이벤트를 찾아줍니다. 이벤트가 보존 기간을 초과한 경우에는 아무 표시 없이 빈 화면이 보이는 대신 해당 사실을 페이지에서 알려줍니다. --- -## 찾는 방법 +## 위치 안내 -모든 대시보드 페이지는 조직 단위(`//…`)로 범위가 지정됩니다. 세션은 왼쪽 사이드바의 **Observe** 메뉴 아래, Events 옆에 위치하며, 목록 상단에 날짜 범위, 환경, 에이전트, 세션 필터가 제공됩니다. 모든 행에서 클릭 한 번으로 전체 실행 그래프를 확인할 수 있습니다. +모든 대시보드 페이지는 조직 범위(`//…`)로 지정됩니다. Sessions는 왼쪽 사이드바의 **Observe** 섹션 아래, Events 옆에 위치하며, 목록 상단에 날짜 범위, 환경, 에이전트, 세션 필터가 있습니다. 모든 행을 한 번 클릭하면 전체 실행 그래프로 이동합니다. -점수 뱃지와 점수 범위 필터링을 활성화하려면 평가자를 연결하세요: [평가](/ko/agenteye/evaluations)를 참고하세요. +점수 뱃지와 점수 범위 필터링을 활성화하려면 평가자를 연결하세요. 자세한 내용은 [Evaluations](/ko/agenteye/evaluations)를 참고하세요. --- ## 관련 문서 -- [이벤트 스트림](/ko/agenteye/event-stream): 각 세션이 집약되는 원시 단계별 트레일. -- [평가](/ko/agenteye/evaluations): 각 실행에 필터링 가능한 점수 뱃지를 부여하기 위한 평가자 연결 방법. -- [텔레메트리](/ko/agenteye/telemetry): 에이전트의 실행 결과가 세션으로 전달되는 방식. \ No newline at end of file +- [이벤트 스트림](/ko/agenteye/event-stream): 모든 세션의 기반이 되는 원시 단계별 트레일입니다. +- [Evaluations](/ko/agenteye/evaluations): 평가자를 연결하여 각 실행에 필터링 가능한 점수 뱃지를 부여합니다. +- [Telemetry](/ko/agenteye/telemetry): 에이전트의 실행 데이터가 세션으로 수집되는 방식입니다. \ No newline at end of file diff --git a/docs/ko/agenteye/telemetry.mdx b/docs/ko/agenteye/telemetry.mdx index f8a36493..b719bd8a 100644 --- a/docs/ko/agenteye/telemetry.mdx +++ b/docs/ko/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- -title: "성능 메트릭" -description: "모델, 도구, 훅이 느려지거나 비용이 급증하는 순간을 즉시 파악하고, 사용자가 체감하기 전에 테일 레이턴시 스파이크를 잡아내세요." +title: "성능 지표" +description: "모델, 도구, 훅이 느려지거나 비용이 급증하는 순간을 즉시 확인하고, 사용자가 체감하기 전에 꼬리 지연(tail-latency) 스파이크를 잡아내세요." --- -모델, 도구, 훅이 느려지거나 비용이 급증하는 순간을 즉시 파악하고, 사용자가 체감하기 전에 테일 레이턴시 스파이크를 잡아내세요. 세 개의 전용 페이지가 원시 타이밍 데이터를 한눈에 읽을 수 있는 p50, p95, p99 수치로 변환해 줍니다. +모델, 도구, 훅이 느려지거나 비용이 급증하는 순간을 즉시 확인하고, 사용자가 체감하기 전에 꼬리 지연(tail-latency) 스파이크를 잡아내세요. 세 개의 전용 페이지가 원시 타이밍 데이터를 한눈에 읽을 수 있는 p50, p95, p99로 변환해 줍니다. -![Models 페이지에 레이턴시 히트맵, 백분위 밴드, 모델별 토큰·비용·컨텍스트 윈도우 수치가 표시된 화면](/agenteye/images/models.png) -*Models 페이지: 레이턴시 히트맵, 백분위 밴드, 모델별 토큰 수·예상 비용·컨텍스트 윈도우 사용률.* +![지연 히트맵, 백분위수 밴드, 모델별 토큰·비용·컨텍스트 윈도우 수치를 표시하는 Models 페이지](/agenteye/images/models.png) +*Models 페이지: 지연 히트맵, 백분위수 밴드, 모델별 토큰 수, 예상 비용, 컨텍스트 윈도우 사용률.* ## 평균값이 최악의 실행을 숨기지 못하게 하세요 -평균 레이턴시 수치는 안심감을 주지만 실제로는 쓸모가 없습니다. 50번 중 한 번 멈춰서 새벽 2시에 온콜을 깨우는 그 호출을 평균이 덮어버리기 때문입니다. Models, Tools, Hooks 페이지는 그런 식으로 동작하지 않습니다. 세 페이지는 동일한 구조를 공유하므로 한 번만 익히면 됩니다. +평균 지연 수치는 안심감을 주지만 실제로는 무용지물입니다. 50번 중 한 번 발생하는 지연 호출을 매끄럽게 가려버려, 새벽 2시에 온콜 담당자를 깨우는 원인이 됩니다. Models, Tools, Hooks 페이지는 그런 방식을 거부합니다. 세 페이지 모두 동일한 구조를 공유하므로 한 번만 익히면 됩니다. -- **24구간 스파크라인**: 추세를 한눈에 파악 — 상황이 나빠지고 있는가? -- **바이탈 스트립**: p50, p95, p99 레이턴시를 나란히 표시해 일반적인 실행과 테일을 함께 확인. -- **레이턴시 히트맵**: 24개 시간 구간 × 레이턴시 버킷으로, 느린 호출이 *언제* 집중됐는지 시각화. -- **백분위 밴드**: p50 선을 중심으로 p25~p75 및 p10~p90 음영 리본과 p99 점이 표시되어, 분포가 평균으로 묻히지 않고 그대로 드러남. +- **24구간 스파크라인**: 추세를 한눈에 파악 — 상황이 나빠지고 있나요? +- **바이탈 스트립**: p50, p95, p99 지연값을 나란히 표시하여 일반적인 실행과 꼬리 구간을 함께 확인. +- **지연 히트맵**: 24개 시간 구간 × 지연 버킷으로 구성되어 느린 호출이 *언제* 집중됐는지 표시. +- **백분위수 밴드**: p50 선과 p25~p75, p10~p90 음영 리본, 그리고 p99 점으로 분포를 평균 뒤에 숨기지 않고 그대로 시각화. -히트맵과 밴드를 연결하는 공유 호버 크로스헤어가 있어, 테일 스파이크가 두 차트에서 동일한 시점으로 정렬됩니다. 단일 평균선 뒤에 숨지 않죠. 세 페이지 모두 대시보드의 **observe** 섹션에서 찾을 수 있으며, 조직 단위로 범위가 설정되고 날짜 범위·환경·에이전트·세션별로 필터링할 수 있습니다. +공유 호버 십자선이 히트맵과 밴드를 연결하므로, 꼬리 스파이크가 단일 평균선 뒤에 숨지 않고 양쪽에서 시간적으로 일치하게 표시됩니다. 세 페이지 모두 대시보드의 **observe** 섹션에서 확인할 수 있으며, 조직 단위로 범위가 지정되고 날짜 범위, 환경, 에이전트, 세션으로 필터링할 수 있습니다. -## Models: 각 모델의 정확한 비용을 파악하세요 +## Models: 각 모델의 비용을 정확히 파악하세요 -Models 페이지(위 이미지 참고)는 청구서를 받을 때 항상 드는 두 가지 질문에 답합니다. 어떤 모델인가, 그리고 얼마인가. 공유 레이턴시 뷰 위에 **모델별 토큰 소비량**, **예상 비용**, **컨텍스트 윈도우 사용률**이 추가되므로, 프롬프트가 통제 불능으로 늘어나는 상황이나 임박한 압축(compaction)을 미리 감지할 수 있습니다. +Models 페이지(상단 이미지 참조)는 청구서가 항상 제기하는 두 가지 질문에 답합니다: 어떤 모델인지, 얼마인지. 공유 지연 뷰 위에 **모델별 토큰 소비량**, **예상 비용**, **컨텍스트 윈도우 사용률**을 추가하여, 프롬프트가 걷잡을 수 없이 늘어나거나 컴팩션이 임박한 상황을 미리 파악할 수 있습니다. -Failproof AI Observability는 일반적인 모델 ID를 자동으로 인식합니다. 윈도우 크기가 잘못 표시되거나 자체 프라이빗 모델을 사용하는 경우, **Settings**의 **model context windows**에서 수정하거나 추가하면 사용률 수치에 즉시 반영됩니다. +Failproof AI Observability는 일반적인 모델 ID를 자동으로 인식합니다. 윈도우 크기가 잘못 표시되거나 자체 프라이빗 모델을 사용하는 경우, **Settings**의 **model context windows**에서 수정하거나 추가하면 사용률 수치가 즉시 반영됩니다. -## Tools: 느린 것과 고장난 것을 구분하세요 +## Tools: 느린 것과 오류 난 것을 구분하세요 -도구 호출은 느릴 수도 있고, 조용히 실패하고 있을 수도 있습니다. 로그를 뒤지는 것이 아니라 몇 초 안에 어느 쪽인지 알아야 합니다. +도구 호출은 느릴 수도 있고, 조용히 실패하고 있을 수도 있습니다. 로그를 뒤지는 대신 몇 초 안에 어느 쪽인지 파악하고 싶을 것입니다. -![Tools 페이지에 공유 레이턴시 히트맵과 백분위 밴드, 성공·실패 분류, 도구 분포 막대가 표시된 화면](/agenteye/images/tools.png) -*Tools 페이지: 동일한 히트맵과 백분위 밴드에 성공·실패 분류 및 도구 분포 막대 추가.* +![공유 지연 히트맵과 백분위수 밴드 옆에 성공/실패 분류 및 도구 분포 바를 표시하는 Tools 페이지](/agenteye/images/tools.png) +*Tools 페이지: 동일한 히트맵과 백분위수 밴드, 그리고 성공/실패 분류와 도구 분포 바.* -공유 레이턴시 뷰와 함께 Tools 페이지는 **성공·실패 분류**와 **도구 분포 막대**를 제공합니다. 어떤 도구를 가장 많이 사용하는지, 어떤 도구가 에러 버짓을 갉아먹고 있는지 한눈에 확인할 수 있습니다. +공유 지연 뷰 외에, Tools 페이지는 **성공/실패 분류**와 **도구 분포 바**를 추가하여 어떤 도구를 가장 많이 사용하는지, 어떤 도구가 에러 버짓을 소진시키는지 한눈에 파악할 수 있습니다. -## Hooks: 문제의 훅과 트리거를 정확히 찾아내세요 +## Hooks: 정확한 훅과 트리거를 찾아내세요 -라이프사이클 훅이 실행을 지연시킬 때, "훅이 느리다"는 말만으로는 조치를 취할 수 없습니다. Hooks 페이지는 문제가 되는 바로 그 훅으로 곧장 안내합니다. +라이프사이클 훅이 실행을 지연시킬 때, "훅이 느리다"는 말만으로는 조치를 취할 수 없습니다. Hooks 페이지는 문제가 되는 훅을 바로 찾아줍니다. -![Hooks 페이지에 훅 이름과 트리거 이벤트별로 분류된 레이턴시가 공유 히트맵과 백분위 밴드 위에 표시된 화면](/agenteye/images/hooks.png) -*Hooks 페이지: 훅 이름과 트리거 이벤트별로 분류된 레이턴시.* +![공유 히트맵과 백분위수 밴드 위에 훅 이름 및 트리거 이벤트별로 지연을 분류해 표시하는 Hooks 페이지](/agenteye/images/hooks.png) +*Hooks 페이지: 훅 이름과 트리거 이벤트별로 분류된 지연 정보.* -동일한 레이턴시 히트맵과 백분위 밴드 위에서, Hooks 페이지는 활동을 **훅 이름**과 **트리거 이벤트**별로 세분화합니다. 주의가 필요한 단 하나의 훅과 단 하나의 이벤트를 바로 찾아낼 수 있습니다. +동일한 지연 히트맵과 백분위수 밴드 위에서, Hooks 페이지는 활동을 **훅 이름**과 **트리거 이벤트**별로 분류하여 주의가 필요한 단일 훅과 단일 이벤트를 바로 찾을 수 있게 합니다. ## 관련 문서 -- [이벤트 스트림](/ko/agenteye/event-stream): 모든 이벤트의 실시간 컬러 코딩 추적. -- [세션](/ko/agenteye/sessions): 이벤트를 실행 단위의 단일 행으로 집계하고 실행 그래프를 열람. -- [에러 트래킹](/ko/agenteye/error-tracking): 대시보드에서 빨간색으로 표시된 모든 항목을 위한 단일 트리아지 화면. +- [이벤트 스트림](/ko/agenteye/event-stream): 모든 이벤트의 실시간 색상 코딩 트레일. +- [세션](/ko/agenteye/sessions): 이벤트를 실행 단위로 묶어 한 행으로 표시하고 실행 그래프를 열어볼 수 있습니다. +- [오류 추적](/ko/agenteye/error-tracking): 대시보드에서 빨간색으로 표시된 모든 항목을 위한 단일 트리아지 화면. - [대시보드](/ko/agenteye/dashboards): 전체 플릿에 걸친 롤업 뷰. \ No newline at end of file diff --git a/docs/ko/architecture.mdx b/docs/ko/architecture.mdx index 7e308fb2..7d4a705c 100644 --- a/docs/ko/architecture.mdx +++ b/docs/ko/architecture.mdx @@ -4,7 +4,7 @@ description: "훅 핸들러, 설정 로딩, 정책 평가의 내부 동작 방 icon: sitemap --- -이 문서는 failproofai의 내부 동작 방식을 설명합니다. 훅 시스템이 에이전트 도구 호출을 가로채는 방법, 설정이 로드되고 병합되는 방법, 정책이 평가되는 방법, 그리고 대시보드가 에이전트 활동을 모니터링하는 방법을 다룹니다. +이 문서는 failproofai의 내부 동작 방식을 설명합니다. 훅 시스템이 에이전트의 도구 호출을 가로채는 방법, 설정이 로딩 및 병합되는 방법, 정책이 평가되는 방법, 그리고 대시보드가 에이전트 활동을 모니터링하는 방법을 다룹니다. --- @@ -12,10 +12,10 @@ icon: sitemap failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: -1. **훅 핸들러** - Claude Code가 에이전트 도구 호출마다 실행하는 빠른 CLI 서브프로세스입니다. 정책을 평가하고 결정을 반환합니다. -2. **에이전트 모니터 (대시보드)** - 에이전트 세션을 모니터링하고 정책을 관리하는 Next.js 웹 애플리케이션입니다. +1. **훅 핸들러** - Claude Code가 에이전트의 모든 도구 호출 시 실행하는 빠른 CLI 서브프로세스입니다. 정책을 평가하고 결정을 반환합니다. +2. **에이전트 모니터 (대시보드)** - 에이전트 세션을 모니터링하고 정책을 관리하기 위한 Next.js 웹 애플리케이션입니다. -두 서브시스템은 모두 `~/.failproofai/`와 프로젝트의 `.failproofai/` 디렉터리에 있는 설정 파일을 공유하지만, 별도의 프로세스로 실행되며 파일시스템을 통해서만 통신합니다. +두 서브시스템은 `~/.failproofai/` 및 프로젝트의 `.failproofai/` 디렉터리에 있는 설정 파일을 공유하지만, 별도의 프로세스로 실행되며 파일 시스템을 통해서만 통신합니다. --- @@ -23,7 +23,7 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: ### Claude Code와의 통합 -`failproofai policies --install`을 실행하면 `~/.claude/settings.json`에 다음과 같은 항목이 작성됩니다: +`failproofai policies --install`을 실행하면 다음과 같은 항목이 `~/.claude/settings.json`에 기록됩니다: ```json { @@ -44,7 +44,7 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: } ``` -그러면 Claude Code는 각 도구 호출 전에 `failproofai --hook PreToolUse`를 서브프로세스로 실행하고, stdin을 통해 JSON 페이로드를 전달합니다. +이후 Claude Code는 각 도구 호출 전에 `failproofai --hook PreToolUse`를 서브프로세스로 실행하며, stdin을 통해 JSON 페이로드를 전달합니다. ### 페이로드 형식 @@ -60,9 +60,9 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: } ``` -`PostToolUse` 이벤트의 경우 페이로드에 도구의 출력 결과가 담긴 `tool_result`도 포함됩니다. +`PostToolUse` 이벤트의 페이로드에는 도구의 출력값이 담긴 `tool_result`도 포함됩니다. -핸들러는 stdin 입력을 1 MB로 제한합니다. 이를 초과하는 페이로드는 폐기되며 모든 정책이 암묵적으로 허용됩니다. +핸들러는 stdin 한도를 1 MB로 제한합니다. 이를 초과하는 페이로드는 폐기되며, 모든 정책이 암묵적으로 허용됩니다. ### 응답 형식 @@ -102,12 +102,12 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: - 종료 코드: `0` - stdout 비어 있음 -**메시지를 포함한 허용:** +**메시지와 함께 허용:** -`allow(message)`는 작업이 허용된 경우에도 정책이 Claude에게 정보성 컨텍스트를 전달할 수 있게 해줍니다. 훅 핸들러는 **stdout**에 다음 JSON을 작성합니다 (설정 파일이 아닌, 위의 거부 및 지시 응답과 마찬가지로 핸들러가 Claude Code에 보내는 응답입니다): +`allow(message)`를 사용하면 작업이 허용된 경우에도 정책이 Claude에 정보성 컨텍스트를 전달할 수 있습니다. 훅 핸들러는 다음 JSON을 **stdout**에 기록합니다 (설정 파일이 아닙니다 — 위의 deny 및 instruct 응답과 마찬가지로, 이는 Claude Code에 대한 핸들러의 응답입니다): ```json -// 훅 핸들러 프로세스가 stdout에 기록 +// Written to stdout by the hook handler process { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." @@ -115,8 +115,8 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: } ``` - 종료 코드: `0` (작업 허용) -- 여러 정책이 메시지와 함께 `allow`를 반환하면 해당 메시지들이 줄바꿈으로 연결되어 단일 `additionalContext` 문자열이 됩니다 -- 메시지를 제공하는 정책이 없으면 stdout은 비어 있습니다 (기존과 동일) +- 여러 정책이 메시지와 함께 `allow`를 반환할 경우, 메시지는 줄바꿈으로 연결되어 단일 `additionalContext` 문자열이 됩니다 +- 정책이 메시지를 제공하지 않으면 stdout은 비어 있습니다 (기존과 동일) ### 처리 파이프라인 @@ -127,60 +127,60 @@ stdin JSON → 페이로드 파싱 (최대 1 MB) → 세션 메타데이터 추출 (session_id, cwd, tool_name, tool_input 등) → readMergedHooksConfig(cwd) ← 프로젝트 + 로컬 + 전역 설정 병합 - → 활성화된 빌트인 정책을 파라미터와 함께 등록 + → 해석된 파라미터로 활성화된 빌트인 정책 등록 → customPoliciesPath에서 커스텀 정책 로드 (설정된 경우) → 커스텀 정책을 정책 레지스트리에 등록 → 모든 정책 평가 (빌트인 먼저, 이후 커스텀) - → 첫 번째 거부에서 단락 평가 - → 지시 결정은 누적 - → 허용 메시지는 누적 + → 첫 번째 deny에서 즉시 중단 + → instruct 결정은 누적 + → allow 메시지는 누적 → JSON 결정을 stdout에 기록 - → ~/.failproofai/hook-activity/current.jsonl에 이벤트 영속화 + → ~/.failproofai/hook-activity/current.jsonl에 이벤트 저장 → 종료 ``` -LLM 호출 없이 일반적인 페이로드를 100ms 이내에 처리합니다. +전체 과정은 LLM 호출 없이 일반적인 페이로드 기준 100ms 이내에 완료됩니다. --- ## 설정 로딩 -`src/hooks/hooks-config.ts`가 세 범위의 설정 로딩을 구현합니다. +`src/hooks/hooks-config.ts`는 세 가지 범위의 설정 로딩을 구현합니다. ```text -[1] {cwd}/.failproofai/policies-config.json ← 프로젝트 (최우선순위) +[1] {cwd}/.failproofai/policies-config.json ← 프로젝트 (최고 우선순위) [2] {cwd}/.failproofai/policies-config.local.json ← 로컬 -[3] ~/.failproofai/policies-config.json ← 전역 (최하위 우선순위) +[3] ~/.failproofai/policies-config.json ← 전역 (최저 우선순위) ``` -병합 로직: -- `enabledPolicies` - 세 파일 전체에서 중복 제거 후 합집합 -- `policyParams` - 정책별 키, 가장 먼저 정의한 파일이 완전히 우선됩니다 -- `customPoliciesPath` - 가장 먼저 정의한 파일이 우선됩니다 -- `llm` - 가장 먼저 정의한 파일이 우선됩니다 +병합 논리: +- `enabledPolicies` - 세 파일 전체에서 중복 제거된 합집합 +- `policyParams` - 정책별 키로, 해당 키를 정의한 첫 번째 파일이 전체적으로 우선 +- `customPoliciesPath` - 해당 값을 정의한 첫 번째 파일이 우선 +- `llm` - 해당 값을 정의한 첫 번째 파일이 우선 -웹 대시보드는 프로젝트 cwd 없이 실행되므로 읽기 및 쓰기에 `readHooksConfig()`(전역만 해당)를 사용합니다. +웹 대시보드는 프로젝트 cwd 없이 실행되므로 읽기 및 쓰기 시 `readHooksConfig()`(전역만)를 사용합니다. --- ## 정책 평가 -`src/hooks/policy-evaluator.ts`가 순서대로 정책을 실행합니다. +`src/hooks/policy-evaluator.ts`는 순서대로 정책을 실행합니다. 각 정책에 대해: 1. 정책의 `params` 스키마를 조회합니다 (있는 경우). 2. 병합된 설정에서 `policyParams[policy.name]`을 읽습니다. -3. 사용자 제공 값을 스키마 기본값 위에 병합하여 `ctx.params`를 생성합니다. -4. 해결된 컨텍스트와 함께 `policy.fn(ctx)`를 호출합니다. +3. 스키마 기본값에 사용자 제공 값을 덮어씌워 `ctx.params`를 생성합니다. +4. 해석된 컨텍스트와 함께 `policy.fn(ctx)`를 호출합니다. 5. 결과가 `deny`이면 즉시 중단하고 해당 결정을 반환합니다. 6. 결과가 `instruct`이면 메시지를 누적하고 계속합니다. 7. 결과가 `allow`이면 다음 정책으로 계속합니다. 모든 정책 실행 후: -- `deny`가 반환된 경우 거부 응답을 출력합니다. -- `instruct`가 수집된 경우 모든 메시지를 결합한 단일 지시 응답을 출력합니다. -- 그 외의 경우 허용 응답을 출력합니다 (stdout 비어 있음, 종료 코드 0). +- `deny`가 반환된 경우 deny 응답을 출력합니다. +- `instruct` 반환이 수집된 경우 모든 메시지를 합쳐 단일 instruct 응답을 출력합니다. +- 그 외의 경우 allow 응답을 출력합니다 (빈 stdout, 종료 코드 0). --- @@ -204,9 +204,9 @@ interface BuiltinPolicyDefinition { } ``` -`params`를 받는 정책은 각 파라미터의 타입과 기본값을 포함한 `PolicyParamsSchema`를 선언합니다. 정책 평가기는 `fn`을 호출하기 전에 해결된 값을 `ctx.params`에 주입합니다. 기본값이 항상 먼저 적용되므로 정책 함수는 null 검사 없이 `ctx.params`를 읽습니다. +`params`를 허용하는 정책은 각 파라미터의 타입과 기본값을 담은 `PolicyParamsSchema`를 선언합니다. 정책 평가기는 `fn`을 호출하기 전에 해석된 값을 `ctx.params`에 주입합니다. 기본값이 항상 먼저 적용되므로, 정책 함수는 null 검사 없이 `ctx.params`를 읽을 수 있습니다. -정책 내부의 패턴 매칭은 원시 문자열 매칭이 아닌 파싱된 명령어 토큰(argv)을 사용합니다. 이를 통해 셸 연산자 인젝션을 통한 우회를 방지합니다 (예: `sudo systemctl status *` 패턴은 `;rm -rf /`를 명령어에 추가해도 우회할 수 없습니다). +정책 내부의 패턴 매칭은 원시 문자열 매칭이 아닌 파싱된 명령 토큰(argv)을 사용합니다. 이를 통해 셸 연산자 삽입을 통한 우회를 방지합니다 (예: `sudo systemctl status *` 패턴은 명령 끝에 `; rm -rf /`를 추가해도 우회할 수 없습니다). --- @@ -222,28 +222,28 @@ export const customPolicies = { }; export function getCustomHooks(): CustomHook[] { ... } -export function clearCustomHooks(): void { ... } // 테스트에서 사용 +export function clearCustomHooks(): void { ... } // used in tests ``` `src/hooks/custom-hooks-loader.ts`는 사용자의 정책 파일을 로드합니다: -1. 설정에서 `customPoliciesPath`를 읽습니다. 없으면 건너뜁니다. -2. 절대 경로로 변환하고 파일 존재를 확인합니다. -3. 모든 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하여 `customPolicies`가 동일한 `globalThis` 레지스트리로 해결되도록 합니다. -4. ESM 호환성을 위해 전이적인 로컬 임포트를 재귀적으로 재작성합니다. -5. 임시 `.mjs` 파일을 작성하고 진입점 파일을 `import()`합니다. +1. 설정에서 `customPoliciesPath`를 읽고, 없으면 건너뜁니다. +2. 절대 경로로 변환하고 파일 존재 여부를 확인합니다. +3. `customPolicies`가 동일한 `globalThis` 레지스트리로 해석되도록 모든 `from "failproofai"` 임포트를 실제 dist 경로로 재작성합니다. +4. ESM 호환성을 보장하기 위해 전이적 로컬 임포트도 재귀적으로 재작성합니다. +5. 임시 `.mjs` 파일을 작성하고 엔트리 파일을 `import()`합니다. 6. `getCustomHooks()`를 호출하여 등록된 훅을 가져옵니다. 7. `finally` 블록에서 모든 임시 파일을 정리합니다. -오류 발생 시 (파일 없음, 구문 오류, 임포트 실패), 오류는 `~/.failproofai/hook.log`에 기록되고 로더는 빈 배열을 반환합니다. 빌트인 정책에는 영향이 없습니다. +오류 발생 시 (파일 없음, 문법 오류, 임포트 실패 등), 오류는 `~/.failproofai/hook.log`에 기록되고 로더는 빈 배열을 반환합니다. 빌트인 정책은 영향을 받지 않습니다. -커스텀 정책은 모든 빌트인 정책 이후에 평가됩니다. 커스텀 정책의 `deny`는 이후 커스텀 정책을 단락 평가하지만 (빌트인 정책은 이미 모두 실행된 상태입니다). +커스텀 정책은 모든 빌트인 정책 이후에 평가됩니다. 커스텀 정책의 `deny`는 이후 커스텀 정책의 실행을 즉시 중단하지만, 모든 빌트인은 이미 실행된 상태입니다. --- ## 활동 로깅 -각 훅 이벤트 후 핸들러는 `~/.failproofai/hook-activity/current.jsonl`에 JSONL 행을 추가하며, 지정된 페이지 크기에 도달하면 `page--.jsonl`로 교체됩니다: +각 훅 이벤트 이후 핸들러는 JSONL 라인을 `~/.failproofai/hook-activity/current.jsonl`에 추가하며, 페이지 크기에 도달하면 `page--.jsonl`로 교체됩니다: ```json { @@ -258,13 +258,13 @@ export function clearCustomHooks(): void { ... } // 테스트에서 사용 } ``` -허용 이외의 결정을 내린 정책당 한 줄씩 기록됩니다. 허용 결정은 파일 크기를 줄이기 위해 기록하지 않습니다. +비허용 결정을 내린 정책 하나당 한 줄이 기록됩니다. 허용 결정은 파일 크기를 줄이기 위해 기록하지 않습니다. --- ## 대시보드 아키텍처 -대시보드는 App Router, React 서버 컴포넌트, 서버 액션을 사용하는 **Next.js 16** 애플리케이션입니다. +대시보드는 App Router를 사용하는 **Next.js 16** 애플리케이션으로, React Server Components와 Server Actions를 활용합니다. ```text app/ @@ -286,16 +286,16 @@ app/ **데이터 흐름:** -- 페이지 컴포넌트는 `lib/projects.ts`와 `lib/log-entries.ts`를 호출하여 파일시스템에서 직접 프로젝트/세션 데이터를 읽습니다 (읽기에는 API 레이어 없음). -- 정책 페이지는 모든 변경 작업(토글, 파라미터 업데이트, 설치/제거)에 서버 액션을 사용합니다. -- 세션 뷰어는 Claude의 JSONL 트랜스크립트 형식을 파싱하고 메시지와 도구 호출의 타임라인을 렌더링합니다. +- 페이지 컴포넌트는 `lib/projects.ts`와 `lib/log-entries.ts`를 호출하여 파일 시스템에서 직접 프로젝트/세션 데이터를 읽습니다 (읽기에 API 레이어 없음). +- 정책 페이지는 모든 변경 작업(토글, 파라미터 업데이트, 설치/제거)에 Server Actions를 사용합니다. +- 세션 뷰어는 Claude의 JSONL 트랜스크립트 형식을 파싱하여 메시지와 도구 호출의 타임라인을 렌더링합니다. **주요 설계 결정:** -- 데이터베이스 없음 - 모든 영속적 상태는 일반 파일(`~/.failproofai/`, `~/.claude/projects/`)에 저장됩니다. -- 변경 작업에 서버 액션 사용 - CRUD 작업에 REST API가 필요 없습니다. -- 읽기 페이지에 React 서버 컴포넌트 사용 - 초기 로드 속도가 빠르고 데이터 페칭을 위한 클라이언트 번들이 필요 없습니다. -- 클라이언트 컴포넌트는 인터랙티비티가 필요한 곳에만 사용 (정책 토글, 활동 검색, 로그 뷰어). +- 데이터베이스 없음 - 모든 영구 상태는 일반 파일(`~/.failproofai/`, `~/.claude/projects/`)에 저장됩니다. +- 변경 작업에 Server Actions 사용 - CRUD 작업에 REST API가 필요하지 않습니다. +- 읽기 페이지에 React Server Components 사용 - 초기 로딩 속도 향상, 데이터 페칭을 위한 클라이언트 번들 불필요. +- 인터랙티비티가 필요한 경우에만 클라이언트 컴포넌트 사용 (정책 토글, 활동 검색, 로그 뷰어). --- @@ -304,7 +304,7 @@ app/ ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI 라우터 (hook / dashboard / install 등) +│ └── failproofai.mjs # CLI 라우터 (훅 / 대시보드 / 설치 등) ├── src/hooks/ │ ├── handler.ts # 훅 이벤트 파이프라인 │ ├── builtin-policies.ts # 39개 정책 정의 @@ -314,19 +314,19 @@ failproofai/ │ ├── hooks-config.ts # 다중 범위 설정 로딩 │ ├── custom-hooks-registry.ts # globalThis 기반 훅 레지스트리 │ ├── custom-hooks-loader.ts # 사용자 JS 훅용 ESM 로더 -│ ├── manager.ts # install / remove / list 작업 +│ ├── manager.ts # 설치 / 제거 / 목록 작업 │ ├── install-prompt.ts # 대화형 정책 선택 프롬프트 │ ├── hook-logger.ts # hook.log에 로깅 -│ ├── hook-activity-store.ts # hook-activity/에 활동 영속화 +│ ├── hook-activity-store.ts # hook-activity/에 활동 저장 │ └── llm-client.ts # LLM API 클라이언트 (AI 기반 정책용) ├── app/ # Next.js 대시보드 (페이지 + 서버 액션) ├── lib/ # 공유 유틸리티 -│ ├── projects.ts # 파일시스템에서 Claude 프로젝트 열거 +│ ├── projects.ts # 파일 시스템에서 Claude 프로젝트 열거 │ ├── log-entries.ts # Claude 트랜스크립트 JSONL 형식 파싱 -│ ├── paths.ts # 시스템 경로 해결 +│ ├── paths.ts # 시스템 경로 해석 │ └── ... ├── components/ # 공유 React UI 컴포넌트 ├── contexts/ # React 컨텍스트 프로바이더 (테마, 자동 새로고침, 텔레메트리) -├── examples/ # 커스텀 훅 예제 파일 +├── examples/ # 커스텀 훅 파일 예제 └── __tests__/ # 단위 및 E2E 테스트 ``` \ No newline at end of file diff --git a/docs/ko/built-in-policies.mdx b/docs/ko/built-in-policies.mdx index 8d04bcab..b14e04cf 100644 --- a/docs/ko/built-in-policies.mdx +++ b/docs/ko/built-in-policies.mdx @@ -1,10 +1,10 @@ --- -title: 기본 제공 정책 -description: "일반적인 에이전트 오류 패턴을 감지하는 39개의 기본 제공 정책" +title: 내장 정책 +description: "일반적인 에이전트 오류 패턴을 포착하는 39가지 내장 정책" icon: shield --- -failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개의 기본 제공 정책이 포함되어 있습니다. 각 정책은 특정 훅 이벤트 유형 및 도구 이름에 따라 작동합니다. 19개의 정책은 코드를 작성하지 않고도 동작을 조정할 수 있는 매개변수를 지원합니다. 5개의 워크플로 정책은 Claude가 중지되기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다. +failproofai는 일반적인 에이전트 오류 패턴을 포착하는 39가지 내장 정책을 제공합니다. 각 정책은 특정 훅 이벤트 유형과 도구 이름에 대해 실행됩니다. 19개의 정책은 코드 작성 없이 동작을 조정할 수 있는 매개변수를 지원합니다. 5개의 워크플로 정책은 Claude가 종료하기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제 수행합니다. --- @@ -25,19 +25,17 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 | [패키지 매니저](#package-managers) | prefer-package-manager | PreToolUse | | [워크플로](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — 에이전트의 진행을 차단합니다. +- **`block-`** — 에이전트의 진행을 중단합니다. - **`warn-`** — 에이전트가 스스로 수정할 수 있도록 추가 컨텍스트를 제공합니다. - **`sanitize-`** — 에이전트가 보기 전에 도구 출력에서 민감한 데이터를 제거합니다. ### 네임스페이스 -모든 정책은 `/` 슬롯에 위치합니다. 기본 제공 정책은 -**`failproofai/`** 네임스페이스에 속합니다 — 예를 들어 `failproofai/sanitize-jwt`. 이 -네임스페이스는 유사한 짧은 이름을 가진 커스텀 또는 서드파티 정책을 함께 로드할 때 -충돌을 방지합니다. +모든 정책은 `/` 슬롯에 위치합니다. 내장 정책은 +**`failproofai/`** 네임스페이스에 속합니다 — 예: `failproofai/sanitize-jwt`. 이 +네임스페이스는 유사한 짧은 이름을 가진 커스텀 또는 서드파티 정책을 함께 로드할 때 충돌을 방지합니다. -설정에서 기본 제공 정책은 짧은 이름 또는 전체 한정 이름으로 참조할 수 있으며, -두 형식 모두 동일한 정책으로 해석됩니다: +설정에서 내장 정책을 짧은 이름이나 정규화된 이름으로 참조할 수 있으며, 두 형식 모두 동일한 정책으로 해석됩니다: ```json { @@ -48,41 +46,41 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 } ``` -이름에 `/`가 없으면 failproofai는 기본 네임스페이스인 `failproofai`에 속하는 -것으로 처리합니다. 이미 `/`를 포함하는 이름(예: `myorg/foo`, +이름에 `/`가 없으면, failproofai는 해당 이름이 기본 네임스페이스인 +`failproofai`에 속하는 것으로 처리합니다. 이미 `/`를 포함하는 이름(예: `myorg/foo`, `custom/my-hook`)은 그대로 유지됩니다. - **`require-`** — 조건이 충족될 때까지 Stop 이벤트를 차단합니다. --- -모든 정책은 `policyParams`에서 선택적 `hint` 필드를 지원합니다. hint는 Claude가 받는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 기본 제공, 커스텀, 컨벤션 정책 모두에서 동작합니다. 자세한 내용은 [구성 → hint](/ko/configuration#hint-cross-cutting)를 참조하세요. +모든 정책은 `policyParams`에서 선택적 `hint` 필드를 지원합니다. hint는 Claude가 보는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 내장, 커스텀, 컨벤션 정책 모두에서 동작합니다. 자세한 내용은 [설정 → hint](/ko/configuration#hint-cross-cutting)를 참고하세요. --- ## 위험한 명령어 -에이전트가 되돌리기 어렵거나 호스트 시스템을 손상시킬 수 있는 작업을 실행하지 못하도록 방지합니다. +에이전트가 되돌리기 어렵거나 호스트 시스템에 손상을 줄 수 있는 작업을 실행하지 못하도록 방지합니다. ### `block-sudo` **이벤트:** PreToolUse (Bash) **기본값:** `sudo` 또는 `doas` 명령어를 거부합니다. -**명령 위치**에서 권한 상승 바이너리를 실행하는 명령어를 차단합니다. 매칭은 텍스트 기반이 아닌 구조적 방식으로 이루어집니다: 명령어는 쉘이 처리하는 방식으로 세그먼트로 분리되고, 접두사 할당(`FOO=bar`), 리다이렉션, 플래그가 포함된 실행기(`env`, `nohup`, `timeout`, `xargs`, `sh -c` 등)가 제거된 후 결과 바이너리를 **basename** 기준으로 비교합니다. 따라서 `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo`, `bash -c "sudo …"` 모두 거부되며, `doas`도 다른 이름의 동일한 권한으로 처리됩니다. +**커맨드 위치**에서 권한 상승 바이너리를 실행하는 명령을 차단합니다. 매칭은 텍스트가 아닌 구조적으로 이루어집니다: 명령어를 셸이 처리하는 방식으로 세그먼트로 분리하고, 접두 할당(`FOO=bar`), 리다이렉션, 플래그가 있는 실행기(`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …)를 걷어낸 후, 결과 바이너리를 **basename**으로 비교합니다. 따라서 `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo`, `bash -c "sudo …"` 모두 거부되며, `doas`도 다른 이름의 동일한 권한으로 처리됩니다. -명령어 위치를 기준으로 하므로, 단순히 해당 단어가 포함된 명령어에는 **작동하지 않습니다** — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, 또는 해당 단어를 포함한 `grep` 교차 표현은 정상적으로 실행됩니다. +커맨드 위치를 기준으로 하기 때문에, 단순히 해당 단어가 언급되는 명령어에는 적용되지 않습니다 — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, 또는 해당 단어를 포함하는 `grep` 패턴은 모두 정상적으로 실행됩니다. -이 정책은 명백한 시도를 차단하지만 모든 경우를 막지는 않습니다. 임의의 쉘 명령을 실행할 수 있는 에이전트는 변수(`S=sudo; $S …`), base64 디코딩 파이프, 또는 디스크의 래퍼 스크립트를 통해 간접적으로 권한 상승에 도달할 수 있습니다 — 단일 명령 문자열 검사로는 이러한 경로를 추적할 수 없기 때문입니다. 이 정책은 실수와 우발적인 권한 상승에 대한 가드레일로 취급하세요. 결정적인 에이전트에 대한 보안 경계로는 적합하지 않습니다. 실제 경계는 쉘 아래 레벨에서 강제되어야 합니다. +이 정책은 명백한 시도를 차단하지만, 모든 경우를 막지는 않습니다. 임의의 셸 명령을 실행할 수 있는 에이전트는 변수(`S=sudo; $S …`), base64 디코딩 파이프, 디스크의 래퍼 스크립트 등을 통해 간접적으로 권한 상승에 도달할 수 있습니다 — 단일 명령 문자열 검사로는 이를 추적할 수 없기 때문입니다. 이 정책은 실수와 우발적 권한 상승에 대한 가드레일로 취급하되, 의도적인 에이전트에 대한 보안 경계로 취급하지 마세요. 실제 경계는 셸 아래 계층에서 강제해야 합니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용되는 정확한 명령어 접두사. 각 항목은 파싱된 argv 토큰과 대조됩니다. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 정확한 명령 접두사. 각 항목은 파싱된 argv 토큰에 대해 매칭됩니다. | **예시:** @@ -96,10 +94,10 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 } ``` -이 설정에서 `sudo systemctl status nginx`는 허용되지만 `sudo rm /etc/hosts`는 거부됩니다. +이 설정에서 `sudo systemctl status nginx`는 허용되지만, `sudo rm /etc/hosts`는 거부됩니다. -패턴은 원시 명령 문자열이 아닌 파싱된 토큰과 대조됩니다. 이를 통해 추가된 쉘 연산자를 통한 우회를 방지합니다 (예: `sudo systemctl status x; rm -rf /`는 `sudo systemctl status *`와 매칭되지 않습니다). +패턴은 원시 명령 문자열이 아닌 파싱된 토큰에 대해 매칭됩니다. 이를 통해 셸 연산자를 추가한 우회 시도를 방지합니다(예: `sudo systemctl status x; rm -rf /`는 `sudo systemctl status *`와 매칭되지 않음). --- @@ -111,9 +109,9 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | 재귀 삭제가 허용되는 경로 (예: `/tmp`). | +| `allowPaths` | `string[]` | `[]` | 재귀 삭제가 허용되는 안전한 경로(예: `/tmp`). | **예시:** @@ -141,7 +139,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `block-failproofai-commands` **이벤트:** PreToolUse (Bash) -**기본값:** failproofai 자체를 제거하거나 비활성화하는 명령어를 거부합니다 (예: `npm uninstall failproofai`, `failproofai policies --uninstall`). +**기본값:** failproofai 자체를 제거하거나 비활성화하는 명령을 거부합니다(예: `npm uninstall failproofai`, `failproofai policies --uninstall`). 매개변수 없음. @@ -150,11 +148,11 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `block-self-pause` **이벤트:** PreToolUse (Bash) -**기본값:** 세션의 적용을 일시 중단하는 `failproofai config --pause`를 거부합니다. 일시 중지는 사람이 결정해야 할 사항으로, 에이전트가 이를 실행할 수 있다면 단 하나의 명령으로 다른 모든 정책을 비활성화할 수 있습니다. +**기본값:** 세션의 정책 적용을 일시 중단하는 `failproofai config --pause`를 거부합니다. 일시 중단은 사람이 결정해야 할 사항입니다 — 에이전트가 이를 실행할 수 있다면 단 하나의 명령으로 다른 모든 정책을 끌 수 있기 때문입니다. -[`block-failproofai-commands`](#block-failproofai-commands)보다 의도적으로 범위가 좁으며, 해당 정책에 포함되지 않습니다: 그 정책은 명령 경계를 기준으로 하므로 `npx -y failproofai config --pause`와 매칭되지 않고, 범위가 넓어 에이전트가 `failproofai audit`을 실행할 수 있도록 종종 비활성화됩니다. `--resume`과 `--status`는 허용됩니다 — 둘 다 적용을 제거하지 않습니다. +의도적으로 [`block-failproofai-commands`](#block-failproofai-commands)보다 범위가 좁으며, 해당 정책으로 커버되지 않습니다: 그 정책은 명령 경계에 고정되므로 `npx -y failproofai config --pause`는 매칭되지 않고, 범위가 넓은 관계로 에이전트가 `failproofai audit`을 실행할 수 있도록 해당 정책을 꺼두는 경우가 많습니다. `--resume`과 `--status`는 허용됩니다 — 두 명령 모두 정책 적용을 제거하지 않습니다. -이 정책은 직접적인 시도를 차단하지만 전체 경우를 막지는 않습니다: 에이전트는 여전히 별칭이나 래퍼 스크립트를 통해 동일한 상태에 도달할 수 있습니다. 완전히 차단하려면 도구 호출에서 일시 중지 기능 자체에 접근할 수 없어야 합니다. +이 정책은 직접적인 시도를 차단하지만, 모든 경우를 막지는 않습니다: 에이전트는 별칭이나 래퍼 스크립트를 통해 동일한 상태에 도달할 수 있습니다. 완전히 차단하려면 도구 호출에서 일시 중단 자체에 접근할 수 없도록 해야 합니다. 매개변수 없음. @@ -162,9 +160,9 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ## 인프라 명령어 -코딩 에이전트가 인프라 CLI를 실행하거나 CI/CD 파이프라인을 트리거하지 못하도록 방지합니다. 이 카테고리의 모든 정책은 **옵트인** (`defaultEnabled: false`) 방식입니다 — `kubectl`, `terraform` 등을 합법적으로 호출해야 하는 에이전트는 정책을 활성화하지 않는 한 영향을 받지 않습니다. 활성화되면 명령이 `allowPatterns`의 항목과 일치하지 않는 한 매칭된 CLI의 모든 호출이 거부됩니다. +코딩 에이전트가 인프라 CLI를 실행하거나 CI/CD 파이프라인을 트리거하지 못하도록 막습니다. 이 카테고리의 모든 정책은 **옵트인**(`defaultEnabled: false`)입니다 — `kubectl`, `terraform` 등을 합법적으로 호출해야 하는 에이전트는 정책을 활성화하지 않는 한 영향을 받지 않습니다. 활성화된 경우, 명령이 `allowPatterns`의 항목과 일치하지 않으면 매칭된 CLI의 모든 호출이 거부됩니다. -패턴 문법은 [`block-sudo`](#block-sudo)와 동일합니다: 토큰은 파싱된 argv와 대조되고, `*`는 단일 토큰에 대한 와일드카드이며, 독립적인 쉘 연산자(`&&`, `||`, `|`, `;`)를 포함하거나 내장된 쉘 메타문자를 포함하는 토큰이 있는 명령어는 인젝션 우회를 방지하기 위해 허용 목록 매칭 전에 거부됩니다. +패턴 문법은 [`block-sudo`](#block-sudo)와 동일합니다: 토큰은 파싱된 argv에 대해 매칭되고, `*`는 단일 토큰의 와일드카드이며, 독립적인 셸 연산자(`&&`, `||`, `|`, `;`) 또는 내장 셸 메타문자가 있는 토큰을 포함하는 명령은 인젝션 우회를 방지하기 위해 허용 목록 매칭 전에 거부됩니다. ### `block-kubectl` @@ -173,9 +171,9 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용되는 kubectl 명령어 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 kubectl 명령 접두사. | **예시:** @@ -196,13 +194,13 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `block-terraform` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `terraform` 또는 `tofu` (OpenTofu) 호출을 거부합니다. +**기본값:** 모든 `terraform` 또는 `tofu`(OpenTofu) 호출을 거부합니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용되는 terraform/tofu 명령어 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 terraform/tofu 명령 접두사. | **예시:** @@ -225,9 +223,9 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용되는 aws CLI 명령어 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 aws CLI 명령 접두사. | **예시:** @@ -246,13 +244,13 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `block-gcloud` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `gcloud` (Google Cloud) CLI 호출을 거부합니다. +**기본값:** 모든 `gcloud`(Google Cloud) CLI 호출을 거부합니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용되는 gcloud 명령어 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 gcloud 명령 접두사. | **예시:** @@ -271,13 +269,13 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `block-az-cli` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `az` (Azure) CLI 호출을 거부합니다. +**기본값:** 모든 `az`(Azure) CLI 호출을 거부합니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용되는 az CLI 명령어 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 az CLI 명령 접두사. | **예시:** @@ -300,9 +298,9 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용되는 helm 명령어 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 helm 명령 접두사. | **예시:** @@ -330,13 +328,13 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 - `gh cache delete` - `gh secret set`, `gh secret delete` -`gh pr view`, `gh pr list`, `gh run list`, `gh release view`, `gh api repos/.../...`와 같은 읽기 전용 `gh` 서브커맨드는 이 정책에서 **매칭되지 않습니다** — 이러한 명령은 워크플로 확인(failproofai의 `require-ci-green-before-stop` 포함)에 일상적으로 필요합니다. +`gh pr view`, `gh pr list`, `gh run list`, `gh release view`, `gh api repos/.../...` 같은 읽기 전용 `gh` 서브커맨드는 이 정책에 해당하지 않습니다 — 워크플로 확인(failproofai의 `require-ci-green-before-stop` 포함)에 일상적으로 필요하기 때문입니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 일반적으로 거부되더라도 허용할 특정 스크립트 호출. | +| `allowPatterns` | `string[]` | `[]` | 원래는 거부되더라도 허용할 특정 스크립트 호출. | **예시:** @@ -354,7 +352,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ## 시크릿 (새니타이저) -에이전트가 자격 증명을 컨텍스트나 출력에 노출하지 못하도록 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에서 작동합니다. Claude가 Bash 명령을 실행하거나, 파일을 읽거나, 도구를 호출하면 이 정책들이 출력이 Claude에게 반환되기 전에 검사합니다. 시크릿 패턴이 감지되면 출력이 전달되는 것을 방지하는 deny 결정을 반환합니다. +에이전트가 자격 증명을 컨텍스트나 출력에 노출하지 못하도록 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에서 실행됩니다. Claude가 Bash 명령을 실행하거나, 파일을 읽거나, 도구를 호출하면 이 정책들이 Claude에게 반환되기 전에 출력을 검사합니다. 시크릿 패턴이 감지되면, 정책은 출력이 전달되지 않도록 거부 결정을 반환합니다. ### `sanitize-jwt` @@ -368,11 +366,11 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `sanitize-api-keys` **이벤트:** PostToolUse (모든 도구) -**기본값:** 일반적인 API 키 형식을 삭제합니다: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), AWS 액세스 키 (`AKIA`), Stripe 키 (`sk_live_`, `sk_test_`), Google API 키 (`AIza`). +**기본값:** 일반적인 API 키 형식을 삭제합니다: Anthropic(`sk-ant-`), OpenAI(`sk-`), GitHub PAT(`ghp_`), AWS 액세스 키(`AKIA`), Stripe 키(`sk_live_`, `sk_test_`), Google API 키(`AIza`). **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| | `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | 시크릿으로 처리할 추가 정규식 패턴. | @@ -396,7 +394,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `sanitize-connection-strings` **이벤트:** PostToolUse (모든 도구) -**기본값:** 자격 증명이 내장된 데이터베이스 연결 문자열을 삭제합니다 (예: `postgresql://user:password@host/db`). +**기본값:** 자격 증명이 내장된 데이터베이스 연결 문자열을 삭제합니다(예: `postgresql://user:password@host/db`). 매개변수 없음. @@ -427,9 +425,9 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `block-env-files` **이벤트:** PreToolUse (Bash, Read) -**기본값:** `cat .env`, `.env`를 파일 경로로 하는 `Read` 도구 호출 등을 통해 `.env` 파일을 읽는 것을 거부합니다. +**기본값:** `cat .env`나 `.env`를 파일 경로로 사용하는 `Read` 도구 호출 등을 통해 `.env` 파일을 읽는 것을 거부합니다. -`.envrc` 또는 다른 환경 관련 파일은 차단하지 않습니다 - 정확히 `.env`라는 이름의 파일만 차단합니다. +`.envrc` 또는 다른 환경 관련 파일은 차단하지 않습니다 — 정확히 `.env`라는 이름의 파일만 차단합니다. 매개변수 없음. @@ -438,7 +436,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `protect-env-vars` **이벤트:** PreToolUse (Bash) -**기본값:** 환경 변수를 출력하는 명령어를 거부합니다: `printenv`, `env`, `echo $VAR`. +**기본값:** 환경 변수를 출력하는 명령을 거부합니다: `printenv`, `env`, `echo $VAR`. 매개변수 없음. @@ -446,18 +444,18 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ## 파일 접근 -에이전트가 프로젝트 경계 내에서 작업하고 민감한 파일에 접근하지 못하도록 합니다. +에이전트가 프로젝트 경계 내에서만 작업하고 민감한 파일에 접근하지 못하도록 합니다. ### `block-read-outside-cwd` **이벤트:** PreToolUse (Read, Bash) -**기본값:** 프로젝트 루트 외부의 파일 읽기를 거부합니다. 경계는 `CLAUDE_PROJECT_DIR` (Claude Code에 의해 세션당 한 번 설정됨)이며, 해당 변수가 설정되지 않은 경우 세션의 현재 작업 디렉토리로 대체됩니다. 현재 `cwd` 대신 프로젝트 루트를 사용하므로 Claude가 하위 디렉토리로 `cd`하더라도 경계가 안정적으로 유지됩니다. +**기본값:** 프로젝트 루트 외부의 파일 읽기를 거부합니다. 경계는 `CLAUDE_PROJECT_DIR`(Claude Code가 세션마다 한 번 설정)이며, 해당 변수가 설정되지 않은 경우 세션의 현재 작업 디렉터리로 대체됩니다. 실시간 `cwd` 대신 프로젝트 루트를 사용함으로써 Claude가 하위 디렉터리로 `cd`한 후에도 경계가 안정적으로 유지됩니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | 프로젝트 루트 외부에 있더라도 허용되는 절대 경로 접두사. | +| `allowPaths` | `string[]` | `[]` | 프로젝트 루트 외부여도 허용되는 절대 경로 접두사. | **예시:** @@ -480,9 +478,9 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | 차단할 추가 파일명 패턴 (글로브 스타일). | +| `additionalPatterns` | `string[]` | `[]` | 차단할 추가 파일명 패턴(글로브 형식). | **예시:** @@ -509,7 +507,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | 직접 푸시할 수 없는 브랜치 이름. | @@ -526,7 +524,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ``` -모든 브랜치로의 푸시를 허용하려면 (실질적으로 `enabledPolicies`에서 제거하지 않고 이 정책을 비활성화), `protectedBranches: []`로 설정하세요. +모든 브랜치에 푸시를 허용하려면(사실상 `enabledPolicies`에서 제거하지 않고 정책을 비활성화), `protectedBranches: []`로 설정하세요. --- @@ -534,13 +532,13 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `block-work-on-main` **이벤트:** PreToolUse (Bash) -**기본값:** 작업 트리가 `main` 또는 `master`에 있는 동안 `git commit`, `git merge`, `git rebase`, `git cherry-pick`을 거부합니다. 브랜치 생성 및 전환(`git checkout`, `git checkout -b`, `git switch`, `git switch -c`)은 영향을 받지 않습니다. +**기본값:** 작업 트리가 `main` 또는 `master`에 있을 때 `git commit`, `git merge`, `git rebase`, `git cherry-pick`을 거부합니다. 브랜치 생성 및 전환(`git checkout`, `git checkout -b`, `git switch`, `git switch -c`)은 영향을 받지 않습니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | 커밋/머지/리베이스/체리픽이 거부되는 브랜치 이름. | +| `protectedBranches` | `string[]` | `["main", "master"]` | commit/merge/rebase/cherry-pick이 거부되는 브랜치 이름. | --- @@ -549,7 +547,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 **이벤트:** PreToolUse (Bash) **기본값:** `git push --force` 및 `git push -f`를 거부합니다. -정책 전용 매개변수 없음. 대안을 제안하려면 범용 [`hint`](/ko/configuration#hint-cross-cutting)를 사용하세요: +정책별 매개변수는 없습니다. 크로스커팅 [`hint`](/ko/configuration#hint-cross-cutting)를 사용해 대안을 제안할 수 있습니다: ```json { @@ -566,7 +564,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `warn-git-amend` **이벤트:** PreToolUse (Bash) -**기본값:** `git commit --amend` 실행 시 Claude에게 신중하게 진행하도록 안내합니다. 명령을 차단하지는 않습니다. +**기본값:** `git commit --amend`를 실행할 때 Claude에게 신중하게 진행하도록 지시합니다. 명령을 차단하지는 않습니다. 매개변수 없음. @@ -575,7 +573,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `warn-git-stash-drop` **이벤트:** PreToolUse (Bash) -**기본값:** `git stash drop` 실행 전 Claude에게 확인하도록 안내합니다. 명령을 차단하지는 않습니다. +**기본값:** `git stash drop`을 실행하기 전에 확인하도록 Claude에게 지시합니다. 명령을 차단하지는 않습니다. 매개변수 없음. @@ -584,7 +582,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `warn-all-files-staged` **이벤트:** PreToolUse (Bash) -**기본값:** `git add -A` 또는 `git add .` 실행 시 스테이징할 내용을 검토하도록 Claude에게 안내합니다. 명령을 차단하지는 않습니다. +**기본값:** `git add -A` 또는 `git add .`를 실행할 때 스테이징 중인 내용을 검토하도록 Claude에게 지시합니다. 명령을 차단하지는 않습니다. 매개변수 없음. @@ -592,12 +590,12 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ## 데이터베이스 -데이터베이스에 실행되기 전에 파괴적인 SQL 작업을 감지합니다. +데이터베이스에서 실행되기 전에 파괴적인 SQL 작업을 포착합니다. ### `warn-destructive-sql` **이벤트:** PreToolUse (Bash) -**기본값:** `WHERE` 절 없이 `DROP TABLE`, `DROP DATABASE`, 또는 `DELETE`가 포함된 SQL 실행 전 Claude에게 확인하도록 안내합니다. +**기본값:** `WHERE` 절 없이 `DROP TABLE`, `DROP DATABASE`, 또는 `DELETE`를 포함하는 SQL을 실행하기 전에 확인하도록 Claude에게 지시합니다. 매개변수 없음. @@ -606,7 +604,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `warn-schema-alteration` **이벤트:** PreToolUse (Bash) -**기본값:** `ALTER TABLE` 구문 실행 전 Claude에게 확인하도록 안내합니다. +**기본값:** `ALTER TABLE` 구문을 실행하기 전에 확인하도록 Claude에게 지시합니다. 매개변수 없음. @@ -614,16 +612,16 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ## 경고 -잠재적으로 위험하지만 파괴적이지 않은 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다. +파괴적이지는 않지만 잠재적으로 위험한 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다. ### `warn-large-file-write` **이벤트:** PreToolUse (Write) -**기본값:** 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 안내합니다. +**기본값:** 1024 KB보다 큰 파일을 쓰기 전에 확인하도록 Claude에게 지시합니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| | `thresholdKb` | `number` | `1024` | 경고가 발생하는 파일 크기 임계값(킬로바이트). | @@ -640,7 +638,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ``` -훅 핸들러는 페이로드에 1 MB stdin 제한을 적용합니다. 작은 내용으로 이 정책을 테스트하려면 `thresholdKb`를 1024보다 훨씬 작은 값으로 설정하세요. +훅 핸들러는 페이로드에 1 MB stdin 제한을 적용합니다. 작은 콘텐츠로 이 정책을 테스트하려면 `thresholdKb`를 1024보다 훨씬 낮은 값으로 설정하세요. --- @@ -648,7 +646,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `warn-package-publish` **이벤트:** PreToolUse (Bash) -**기본값:** `npm publish` 실행 전 Claude에게 확인하도록 안내합니다. +**기본값:** `npm publish`를 실행하기 전에 확인하도록 Claude에게 지시합니다. 매개변수 없음. @@ -657,7 +655,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `warn-background-process` **이벤트:** PreToolUse (Bash) -**기본값:** `nohup`, `&`, `disown`, 또는 `screen`을 통해 백그라운드 프로세스를 시작할 때 Claude에게 주의하도록 안내합니다. +**기본값:** `nohup`, `&`, `disown`, 또는 `screen`을 통해 백그라운드 프로세스를 시작할 때 주의하도록 Claude에게 지시합니다. 매개변수 없음. @@ -666,7 +664,7 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ### `warn-global-package-install` **이벤트:** PreToolUse (Bash) -**기본값:** 가상 환경 없이 `npm install -g`, `yarn global add`, 또는 `pip install` 실행 전 Claude에게 확인하도록 안내합니다. +**기본값:** 가상 환경 없이 `npm install -g`, `yarn global add`, 또는 `pip install`을 실행하기 전에 확인하도록 Claude에게 지시합니다. 매개변수 없음. @@ -674,21 +672,21 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ## 패키지 매니저 -에이전트가 사용할 수 있는 패키지 매니저를 강제합니다. +에이전트가 사용할 수 있는 패키지 매니저를 제한합니다. ### `prefer-package-manager` **이벤트:** PreToolUse (Bash) -**기본값:** 비활성화됨. 활성화되면 `allowed` 목록에 없는 패키지 매니저 명령어를 차단하고 Claude에게 허용된 매니저를 사용하도록 명령어를 재작성하도록 안내합니다. +**기본값:** 비활성화됨. 활성화되면, `allowed` 목록에 없는 모든 패키지 매니저 명령을 차단하고 허용된 매니저를 사용하여 명령을 다시 작성하도록 Claude에게 지시합니다. 감지 대상: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | 허용되는 패키지 매니저 이름. 이 목록에 없는 감지된 매니저는 차단됩니다. 비어 있으면 정책이 아무 동작도 하지 않습니다. | -| `blocked` | string[] | `[]` | 기본 목록 외에 추가로 차단할 매니저 이름 (예: `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | 허용되는 패키지 매니저 이름. 이 목록에 없는 감지된 매니저는 차단됩니다. 비어 있으면 정책이 아무런 동작도 하지 않습니다. | +| `blocked` | string[] | `[]` | 내장 목록 외에 추가로 차단할 매니저 이름(예: `['pdm', 'pipx']`). | -기본 차단 목록은 다음을 포함합니다: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. 이 목록에 없는 매니저를 추가하려면 `blocked`를 사용하세요. +내장 차단 목록: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. 이 목록에 없는 매니저를 추가하려면 `blocked`를 사용하세요. **설정 예시:** @@ -704,18 +702,18 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 } ``` -이 설정에서 `pip install flask`와 `pdm install flask`는 모두 거부되며 Claude에게 `uv` 또는 bun을 사용하라는 메시지가 표시됩니다. `uv pip install flask`와 같은 명령은 `uv`가 허용 목록에 있고 먼저 확인되므로 허용됩니다. +이 설정에서 `pip install flask`와 `pdm install flask`는 모두 거부되며, `uv` 또는 `bun`을 사용하도록 안내합니다. `uv pip install flask`는 `uv`가 허용 목록에 있고 먼저 확인되기 때문에 허용됩니다. --- ## AI 동작 -에이전트가 막히거나 예상치 못한 동작을 보이는 경우를 감지합니다. +에이전트가 막히거나 예기치 않게 동작하는 경우를 감지합니다. ### `warn-repeated-tool-calls` **이벤트:** PreToolUse (모든 도구) -**기본값:** 동일한 도구가 동일한 매개변수로 3회 이상 호출될 때 Claude에게 재고하도록 안내합니다 — 에이전트가 루프에 갇혔다는 일반적인 신호입니다. +**기본값:** 동일한 도구가 동일한 매개변수로 3번 이상 호출될 때 재고하도록 Claude에게 지시합니다 — 에이전트가 루프에 갇혀 있다는 일반적인 신호입니다. 매개변수 없음. @@ -723,39 +721,39 @@ failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개 ## 워크플로 -세션 종료 시 규율 있는 워크플로를 강제합니다. 이 정책들은 **Stop** 이벤트에서 작동하며 각 조건이 충족될 때까지 에이전트가 중지하지 못하도록 거부합니다. 자연적인 의존성 체인을 따릅니다: 커밋 → 푸시 → PR → CI. 정책이 거부하면 체인의 이후 정책은 건너뜁니다 (deny 단락). +세션 종료 시 체계적인 워크플로를 강제합니다. 이 정책들은 **Stop** 이벤트에서 실행되며 각 조건이 충족될 때까지 에이전트가 종료하지 못하도록 차단합니다. 자연스러운 의존성 체인을 따릅니다: 커밋 → 푸시 → PR → CI. 정책이 거부하면 체인의 이후 정책은 건너뜁니다(거부 시 단락). -모든 워크플로 정책은 **fail-open** 방식입니다: 필요한 도구를 사용할 수 없는 경우 (예: `gh` 미설치, git 리모트 없음), 정책은 확인이 건너뛰어진 이유를 설명하는 정보 메시지와 함께 허용합니다. +모든 워크플로 정책은 **fail-open** 방식으로 동작합니다: 필요한 도구를 사용할 수 없는 경우(예: `gh` 미설치, git 리모트 없음), 정책은 검사가 건너뛰어진 이유를 설명하는 정보 메시지와 함께 허용합니다. -### CLI별 Stop 동작 +### CLI별 Stop 동작 방식 -Stop 적용은 6개 지원 CLI에서 각각 다른 "에이전트 완료" 훅 계약을 노출하기 때문에 약간 다르게 보입니다. **결과**는 동일합니다 — 에이전트는 워크플로 게이트가 실패하는 동안 중지할 수 없습니다 — 하지만 **메커니즘**은 다릅니다. 아래 표는 요약을 제공합니다. Pi만 `require-*-before-stop` 정책을 활성화하기 전에 이해해야 할 사용자에게 보이는 동작 특이사항이 있습니다. +Stop 정책 적용 방식은 지원되는 6개의 CLI마다 약간씩 다릅니다. 각 CLI마다 "에이전트 완료" 훅 계약이 다르게 노출되기 때문입니다. **결과**는 동일합니다 — 워크플로 게이트가 실패하는 동안 에이전트가 종료하지 못합니다 — 하지만 **메커니즘**이 다릅니다. 아래 표에 요약되어 있으며, `require-*-before-stop` 정책을 활성화하기 전에 이해할 가치가 있는 사용자 가시적 특이점이 Pi에만 있습니다. -| CLI | 게이트 작동 시점 | 표시 내용 | +| CLI | 게이트 실행 시점 | 표시되는 내용 | |---|---|---| -| Claude Code | 동일한 에이전트 루프, 즉시 | Claude가 계속 작업합니다 — 문제를 해결한 후 다시 완료를 시도합니다. 사용자에게 중단이 표시되지 않습니다. | -| Codex | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다. | -| GitHub Copilot CLI | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다 (Copilot의 `{decision:"block", reason}` 재시도 채널 사용 — Copilot CLI 1.0.41에서 실험적으로 검증됨). | -| Cursor Agent | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다 (Cursor의 `{followup_message}` 채널 사용 — `loop_limit`에 제한, 기본 5회 재시도). | -| OpenCode | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다 (OpenCode의 `client.session.prompt(...)` SDK 호출이 `hookSpecificOutput.additionalContext`를 통해 라우팅됨). | -| **Pi (pi-coding-agent)** | **다음 사용자 턴** | **Pi는 게이트가 작동할 때 눈에 띄게 중지됩니다** — 에이전트 루프가 종료되고 프롬프트로 돌아갑니다. 그런 다음 다음 프롬프트를 제출할 때 게이트가 작동합니다: failproofai가 해당 턴의 시스템 프롬프트에 `MANDATORY ACTION REQUIRED` 지시문을 앞에 추가하여 LLM이 요청한 작업을 수행하기 전에 워크플로 단계(커밋, 푸시 등)를 완료하도록 지시합니다. | +| Claude Code | 동일 에이전트 루프, 즉시 | Claude가 계속 작업합니다 — 문제를 수정한 후 다시 완료를 시도합니다. 사용자에게는 중단이 보이지 않습니다. | +| Codex | 동일 에이전트 루프, 즉시 | Claude와 동일합니다. | +| GitHub Copilot CLI | 동일 에이전트 루프, 즉시 | Claude와 동일합니다(Copilot의 `{decision:"block", reason}` 재시도 채널 사용 — Copilot CLI 1.0.41에 대해 실증적으로 검증됨). | +| Cursor Agent | 동일 에이전트 루프, 즉시 | Claude와 동일합니다(Cursor의 `{followup_message}` 채널 사용 — `loop_limit`에 의해 제한, 기본값 5회 재시도). | +| OpenCode | 동일 에이전트 루프, 즉시 | Claude와 동일합니다(OpenCode의 `client.session.prompt(...)` SDK 호출이 `hookSpecificOutput.additionalContext`를 통해 라우팅됨). | +| **Pi (pi-coding-agent)** | **다음 사용자 턴** | **Pi는 게이트가 실행될 때 눈에 띄게 종료됩니다** — 에이전트 루프가 종료되고 프롬프트로 돌아갑니다. 그런 다음 다음 프롬프트를 제출할 때 게이트가 실행됩니다: failproofai가 해당 턴의 시스템 프롬프트에 `MANDATORY ACTION REQUIRED` 지시문을 앞에 추가하여, 요청한 작업을 수행하기 전에 워크플로 단계(커밋, 푸시 등)를 완료하도록 LLM에게 지시합니다. | -**Pi 제한사항.** Pi의 `AgentEndEvent` (Claude의 `Stop` 훅에 해당하는 업스트림 이벤트)는 Result 타입이 없습니다 — 작동 시점에 Pi의 에이전트 루프가 이미 종료되어 있습니다. Pi는 Claude / Copilot / Cursor / OpenCode처럼 동일한 루프를 강제로 재시도할 수 없습니다. failproofai는 게이트를 Pi의 `before_agent_start` 이벤트(다음 사용자 프롬프트 후 작동)로 이동하여 워크플로 확인이 현재 턴이 아닌 다음 턴에서 강제되도록 합니다. +**Pi 제한 사항.** Pi의 `AgentEndEvent`(Claude의 `Stop` 훅에 해당하는 업스트림)에는 Result 타입이 없습니다 — 이벤트가 실행될 때 Pi의 에이전트 루프는 이미 종료된 상태입니다. Pi는 Claude / Copilot / Cursor / OpenCode처럼 동일한 루프를 강제로 재시도할 수 없습니다. failproofai는 게이트를 Pi의 `before_agent_start` 이벤트(다음 사용자 프롬프트 이후 실행)로 이동시켜 워크플로 검사가 여전히 적용되도록 합니다. 다만 현재 턴이 아닌 다음 턴에서 적용됩니다. -**실제적 의미:** +**실제로 의미하는 바:** -- Pi가 중지된 후, deny 이유는 Pi 세션 id로 키가 지정된 메모리에 캡처됩니다. 동일한 Pi 프로세스에서 제출하는 바로 다음 프롬프트가 이를 처리합니다: LLM은 시스템 프롬프트 상단에 `MANDATORY ACTION REQUIRED` 지시문을 보고, 커밋(또는 푸시 / PR 열기 / CI 대기)을 수행한 후 요청을 계속합니다. 캡처된 deny 이유는 한 번만 처리됩니다 — 처리되면 게이트가 해제됩니다. -- 게이트는 Pi의 프로세스 수명에 의해 경계가 정해집니다. 턴 사이에 Pi를 `Ctrl+C`하거나 종료하면 메모리 항목이 프로세스와 함께 삭제되어 게이트가 누락됩니다. Claude, Copilot, Cursor, OpenCode도 동일한 경계를 가집니다 (에이전트를 종료하면 게이트가 누락됨) — Pi는 에이전트가 게이트가 작동하기 전에 눈에 띄게 종료되므로 더 명확하게 보입니다. -- 보류 중인 deny는 어떤 이유로든 (`new` / `resume` / `fork` / `quit`) `session_shutdown` 시에도 지워지므로, 이전 세션의 오래된 게이트가 동일한 Pi 프로세스에서 시작된 새 세션으로 누출될 수 없습니다. +- Pi가 종료된 후, 거부 사유는 Pi 세션 ID로 키링된 메모리에 캡처됩니다. 동일한 Pi 프로세스에서 제출하는 바로 다음 프롬프트에서 이를 소비합니다: LLM은 시스템 프롬프트 상단에 `MANDATORY ACTION REQUIRED` 지시문을 보고, 커밋(또는 푸시/PR 생성/CI 대기)을 수행한 후 요청을 계속 처리합니다. 캡처된 거부 사유는 일회성입니다 — 소비되면 게이트가 해제됩니다. +- 게이트는 Pi의 프로세스 수명에 의해 제한됩니다. 턴 사이에 Pi를 `Ctrl+C`로 종료하거나 나가면, 인메모리 항목이 프로세스와 함께 삭제되어 게이트가 누락됩니다. Claude, Copilot, Cursor, OpenCode도 동일한 제한이 있습니다(에이전트를 종료하면 게이트가 누락됨) — Pi는 에이전트가 눈에 띄게 종료되기 때문에 더 명확하게 보일 뿐입니다. +- 대기 중인 거부는 어떤 이유로든 `session_shutdown`(`new` / `resume` / `fork` / `quit`) 시 해제되므로, 이전 세션의 오래된 게이트가 동일한 Pi 프로세스에서 시작된 새 세션으로 누출되지 않습니다. -Claude 스타일의 동일 루프 재시도가 필요하면 다른 5개 지원 CLI 중 하나에서 `Stop` 정책을 실행하세요. 이 격차를 해소할 수 있는 `AgentEndEvent`의 향후 Result 타입에 대해 Pi 업스트림을 추적 중입니다. +Claude 스타일의 동일 루프 재시도가 필요한 경우, 나머지 5개의 지원 CLI 중 하나에서 `Stop` 정책을 실행하세요. 이 격차를 해소할 수 있는 `AgentEndEvent`의 미래 Result 타입을 위해 Pi 업스트림을 추적하고 있습니다. ### `require-commit-before-stop` **이벤트:** Stop -**기본값:** 커밋되지 않은 변경사항(수정됨, 스테이징됨, 추적되지 않은 파일)이 있을 때 중지를 거부합니다. 작업 디렉토리가 깨끗할 때는 정보 메시지를 반환합니다. +**기본값:** 커밋되지 않은 변경 사항(수정, 스테이징, 추적되지 않은 파일)이 있을 때 종료를 거부합니다. 작업 디렉터리가 깨끗할 때는 정보 메시지를 반환합니다. 매개변수 없음. @@ -764,13 +762,13 @@ Claude 스타일의 동일 루프 재시도가 필요하면 다른 5개 지원 C ### `require-push-before-stop` **이벤트:** Stop -**기본값:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 중지를 거부합니다. 필요한 경우 추적 브랜치를 생성하기 위해 `git push -u`를 제안합니다. 리모트가 설정되지 않은 경우 fail-open 방식으로 처리합니다. +**기본값:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 종료를 거부합니다. 필요한 경우 추적 브랜치를 생성하기 위해 `git push -u`를 제안합니다. 원격이 설정되지 않은 경우 fail-open으로 동작합니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | 푸시할 리모트 이름. | +| `remote` | `string` | `"origin"` | 푸시할 원격 이름. | **예시:** @@ -789,13 +787,13 @@ Claude 스타일의 동일 루프 재시도가 필요하면 다른 5개 지원 C ### `require-pr-before-stop` **이벤트:** Stop -**기본값:** 현재 브랜치에 대한 풀 리퀘스트가 없거나 기존 PR이 머지 없이 닫혀 있을 때 중지를 거부합니다. Claude에게 `gh pr create`로 PR을 생성하도록 안내합니다. PR이 **머지**되면 정책이 허용합니다 (작업이 배포됨) 하고 브랜치를 전환하도록 힌트를 제공합니다 (`git checkout main && git pull`). +**기본값:** 현재 브랜치에 풀 리퀘스트가 없거나 기존 PR이 머지되지 않고 닫혔을 때 종료를 거부합니다. `gh pr create`로 PR을 생성하도록 Claude에게 지시합니다. PR이 **머지**된 경우, 정책은 허용하며(작업이 배포됨) 브랜치에서 전환하도록 힌트를 제공합니다(`git checkout main && git pull`). 매개변수 없음. -이 정책을 사용하려면 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되고 인증되어 있어야 합니다. -풀 리퀘스트에 대한 읽기 접근을 위한 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우 정책은 fail-open으로 처리되고 이유를 Claude에게 보고합니다. +이 정책은 [GitHub CLI](https://cli.github.com/)(`gh`)가 설치되어 인증된 상태여야 합니다. +풀 리퀘스트에 대한 읽기 접근을 위한 `repo` 범위를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우, 정책은 fail-open으로 동작하고 Claude에게 사유를 보고합니다. --- @@ -803,21 +801,21 @@ Claude 스타일의 동일 루프 재시도가 필요하면 다른 5개 지원 C ### `require-no-conflicts-before-stop` **이벤트:** Stop -**기본값:** 현재 브랜치가 베이스 브랜치에 깔끔하게 머지될 수 없을 때 중지를 거부합니다. 정책은 먼저 브랜치에 대한 GitHub의 `OPEN` PR이 있는지 확인합니다 — PR이 없으면 머지 대상이 없으므로 전체 정책이 단락되어 허용합니다. `OPEN` PR이 확인되면 두 가지 독립적인 프로브가 실행됩니다: +**기본값:** 현재 브랜치가 베이스 브랜치에 깨끗하게 머지될 수 없을 때 종료를 거부합니다. 정책은 먼저 브랜치에 GitHub의 `OPEN` PR이 있는지 확인합니다 — PR이 없으면 강제할 머지 대상이 없으므로 전체 정책이 허용으로 단락됩니다. `OPEN` PR이 확인되면 두 가지 독립적인 프로브가 실행됩니다: -1. **로컬** — `git merge-tree --write-tree --name-only origin/ HEAD`. 충돌 시 deny 메시지에 충돌 파일이 명시되어 Claude가 정확히 무엇을 해결해야 하는지 알 수 있습니다. -2. **GitHub** — 사전 확인에서 이미 가져온 `gh pr view --json mergeable,state` 결과를 재사용합니다. 마지막 fetch 이후 누군가가 `main`에 충돌하는 PR을 병합한 경우처럼 오래된 로컬 `origin/`가 놓칠 수 있는 충돌을 감지합니다. `CONFLICTING` 결과는 거부됩니다. `UNKNOWN` 결과도 거부되며 Claude에게 다시 중지를 시도하기 전에 약 10초 기다리고 재확인하도록 안내합니다 — GitHub가 재계산하는 동안 거짓 음성을 방지합니다. +1. **로컬** — `git merge-tree --write-tree --name-only origin/ HEAD`. 충돌 시, 거부 메시지에 충돌 파일 이름이 포함되어 Claude가 정확히 무엇을 해결해야 하는지 알 수 있습니다. +2. **GitHub** — 사전 확인에서 이미 가져온 `gh pr view --json mergeable,state` 결과를 재사용합니다. 오래된 로컬 `origin/`가 놓칠 수 있는 충돌을 포착합니다(예: 마지막 페치 이후 누군가가 `main`에 충돌하는 PR을 머지한 경우). `CONFLICTING` 결과는 거부됩니다. `UNKNOWN` 결과도 거부되며, Claude에게 다시 종료를 시도하기 전에 약 10초 기다리고 재확인하도록 지시합니다 — GitHub가 재계산하는 동안 발생하는 거짓 음성을 방지합니다. -다음의 경우 완전히 건너뜁니다 (허용): `gh`가 설치되지 않음, 브랜치에 PR이 없음, PR 상태가 `OPEN`이 아님 (예: `MERGED`, `CLOSED`), 또는 `gh pr view`가 파싱할 수 없는 출력을 반환함. 로컬에 `origin/`가 없거나 베이스보다 앞서는 커밋이 없는 경우에도 fail-open으로 처리됩니다 — 이러한 레이어 1 폴스루는 허용하기 전에 캐시된 PR 병합 가능성을 여전히 참조합니다. +다음의 경우 완전히 건너뜁니다(허용): `gh`가 설치되지 않은 경우, 브랜치에 PR이 없는 경우, PR 상태가 `OPEN`이 아닌 경우(예: `MERGED`, `CLOSED`), 또는 `gh pr view`가 파싱할 수 없는 출력을 반환하는 경우. 로컬에 `origin/`가 없거나 베이스보다 앞선 커밋이 없는 경우에도 fail-open으로 동작합니다 — 이러한 레이어 1 폴스루는 허용하기 전에 캐시된 PR 머지 가능성을 여전히 확인합니다. **매개변수:** -| 매개변수 | 유형 | 기본값 | 설명 | +| 파라미터 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | 충돌을 확인할 베이스 브랜치. | +| `baseBranch` | `string` | `"main"` | 충돌 여부를 확인할 베이스 브랜치. | -이 정책에는 GitHub CLI (`gh`)가 필요합니다. 정책은 충돌 프로브를 실행하기 전에 `gh pr view`를 사용하여 `OPEN` PR이 있는지 확인합니다 — `gh` 없이는 정책이 단락되어 허용합니다. 풀 리퀘스트에 대한 읽기 접근을 위한 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. +이 정책은 GitHub CLI(`gh`)가 필요합니다. 정책은 `gh pr view`를 사용하여 충돌 프로브를 실행하기 전에 `OPEN` PR이 있는지 확인합니다 — `gh` 없이는 정책이 허용으로 단락됩니다. 풀 리퀘스트에 대한 읽기 접근을 위한 `repo` 범위를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. --- @@ -825,13 +823,13 @@ Claude 스타일의 동일 루프 재시도가 필요하면 다른 5개 지원 C ### `require-ci-green-before-stop` **이벤트:** Stop -**기본값:** 현재 브랜치에서 CI 확인이 실패하거나 아직 실행 중일 때 중지를 거부합니다. GitHub Actions 워크플로 실행과 서드파티 봇 확인(예: CodeRabbit, SonarCloud, Codecov)을 모두 확인합니다. `skipped`, `cancelled`, `neutral` 결론은 실패하지 않는 것으로 처리합니다 (후자는 예를 들어 외부 기여자 PR에서 앱이 의도적으로 성공/실패 대신 neutral을 보고하는 Socket Security 알림을 포함합니다). 모든 확인이 통과되면 정보 메시지를 반환합니다. +**기본값:** 현재 브랜치에서 CI 검사가 실패하거나 아직 실행 중일 때 종료를 거부합니다. GitHub Actions 워크플로 실행과 서드파티 봇 검사(예: CodeRabbit, SonarCloud, Codecov)를 모두 확인합니다. `skipped`, `cancelled`, `neutral` 결론은 실패로 처리하지 않습니다(후자는 예를 들어 외부 기여자 PR에서 앱이 의도적으로 성공/실패 대신 neutral을 보고하는 Socket Security 알림 등을 커버합니다). 모든 검사가 통과하면 정보 메시지를 반환합니다. 매개변수 없음. -이 정책을 사용하려면 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되고 인증되어 있어야 합니다. -Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위한 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우 정책은 fail-open으로 처리되고 이유를 Claude에게 보고합니다. +이 정책은 [GitHub CLI](https://cli.github.com/)(`gh`)가 설치되어 인증된 상태여야 합니다. +Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위한 `repo` 범위를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우, 정책은 fail-open으로 동작하고 Claude에게 사유를 보고합니다. --- @@ -840,7 +838,7 @@ Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위한 `re ## 개별 정책 비활성화 -설정의 `enabledPolicies`에서 특정 정책을 제거하거나 대시보드의 Policies 탭에서 비활성화하세요. +설정의 `enabledPolicies`에서 특정 정책을 제거하거나, 대시보드의 Policies 탭에서 토글로 끄세요. ```json { diff --git a/docs/ko/cli/audit.mdx b/docs/ko/cli/audit.mdx index 8f393fb4..4ac8c5c2 100644 --- a/docs/ko/cli/audit.mdx +++ b/docs/ko/cli/audit.mdx @@ -1,21 +1,19 @@ --- -title: 과거 세션 감사 (베타) -description: "과거 트랜스크립트에서 에이전트가 낭비적이거나 위험한 작업을 수행한 빈도 분석" +title: 과거 세션 감사(베타) +description: "과거 트랜스크립트에서 에이전트가 낭비적이거나 위험한 행동을 얼마나 자주 했는지 집계" --- **베타 기능.** 초기 피드백을 수집하는 동안 감사 기능은 베타로 제공됩니다. - 디텍터 카탈로그와 리포트 형식은 다음 안정 버전 출시 전에 변경될 수 있습니다. - 이상한 점이 있으면 이슈를 열어 주세요. + 탐지기 카탈로그와 보고서 형식은 다음 안정 버전 출시 전에 변경될 수 있습니다. + 이상한 점이 있으면 이슈를 열어주세요. -감사 기능은 과거 에이전트 CLI 트랜스크립트를 failproofai의 정책 엔진으로 재실행하고, -**`/audit` 대시보드 페이지**에 공유 가능한 시각적 리포트를 렌더링합니다 — -에이전트의 아키타입, 0~100 점수, 그리고 어떤 정책이 무엇을 포착했을지 정확히 보여줍니다. +감사 기능은 과거 에이전트 CLI 트랜스크립트를 failproofai의 정책 엔진을 통해 재실행하고, **`/audit` 대시보드 페이지**에 공유 가능한 시각적 보고서를 렌더링합니다 — 에이전트의 아키타입, 0~100 점수, 그리고 어떤 정책이 어떤 상황을 잡아냈을지 정확히 표시합니다. ## 실행 방법 -세 가지 방법 모두 동일한 `/audit` 리포트로 이동합니다. +세 가지 방법 모두 동일한 `/audit` 보고서로 연결됩니다. @@ -35,97 +33,89 @@ failproofai - `npx -y failproofai audit`은 failproofai를 가져와 스캔을 실행하고 - 대시보드를 자동으로 열어줍니다 — 사전 설치가 필요 없습니다. + `npx -y failproofai audit`는 failproofai를 가져와 스캔을 실행하고 대시보드를 자동으로 열어줍니다 — 사전 설치가 필요 없습니다. - `failproofai audit`은 터미널에서 스캔을 실행한 후, - 완료되면 `localhost:8020/audit`을 자동으로 엽니다. + `failproofai audit`는 터미널에서 스캔을 실행한 뒤, 완료되면 `localhost:8020/audit`을 자동으로 엽니다. - `failproofai`를 실행하고 내비게이션 바의 **Audit**을 클릭하거나(Policies와 - Projects 사이에 위치), `/audit`을 직접 열면 됩니다. + `failproofai`를 실행하고 내비게이션 바(Policies와 Projects 사이)에서 **Audit**을 클릭하거나, `/audit`을 직접 열면 됩니다. - `failproofai audit -h` (또는 `--help`)를 실행하면 사용법을 확인할 수 있습니다. - 감사는 **완전 오프라인**으로 실행되며 — 계정이나 네트워크가 필요 없습니다 — - `Ctrl+C`로 중단할 때까지 대시보드가 계속 서비스됩니다. + `failproofai audit -h`(또는 `--help`)를 실행하면 사용법을 확인할 수 있습니다. 감사는 **완전히 오프라인**으로 실행됩니다 — 계정이나 네트워크가 필요 없습니다 — 대시보드는 `Ctrl+C`로 종료할 때까지 계속 서빙됩니다. -대시보드는 이 기기의 과거 에이전트 CLI 트랜스크립트(Claude Code, Codex, Copilot, Cursor, OpenCode, Pi)를 스캔하고, 에이전트가 failproofai가 차단하도록 설계된 동작을 얼마나 자주 했는지 리포트합니다 — 환경 변수 체크, 강제 푸시, 불필요한 `cd ` 접두사, sleep 폴링 루프, 방금 편집한 파일 재읽기 등. +대시보드는 이 머신에서 과거 에이전트 CLI 트랜스크립트(Claude Code, Codex, Copilot, Cursor, OpenCode, Pi)를 스캔하고, failproofai가 막도록 설계된 행동들 — 환경 변수 체크, 강제 푸시, 불필요한 `cd ` 접두사, sleep 폴링 루프, 방금 편집한 파일 재읽기 등 — 이 얼마나 자주 발생했는지 보고합니다. -각 트랜스크립트에서 모든 도구 사용 이벤트는 39개의 내장 정책과 런타임 정책으로는 아직 커버되지 않는 패턴을 감지하는 8개의 감사 전용 디텍터를 통해 재실행됩니다. 모든 세션에서 정책/디텍터별 카운트가 집계됩니다. +각 트랜스크립트마다 모든 도구 사용 이벤트는 39개의 내장 정책 **및** 런타임 정책에서 아직 다루지 않는 패턴을 잡는 8개의 감사 전용 탐지기를 통해 재실행됩니다. 카운트는 모든 세션에 걸쳐 정책/탐지기별로 집계됩니다. ## 결과물 `/audit` 페이지는 단일 화면의 공유 가능한 **포스터**와 그 아래 네 개의 섹션으로 구성됩니다: -1. **포스터** — 에이전트의 정체성을 한눈에: **아키타입** (8가지 중 하나 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), 페르소나 키워드, 해당 아키타입의 희귀도, 티어 밴드(`S`부터 `bottom tier`)가 포함된 **0~100 점수**. 공유용으로 설계 — X나 LinkedIn에 게시하거나 PNG로 다운로드할 수 있습니다. -2. **`// strengths`** — 에이전트가 이미 잘 하는 것들을 스캔의 실제 수치로 표시 (예: 클린 도구 호출 비율, `0`번의 main 브랜치 푸시 시도). 관련 정책이 깨끗한 기록을 가진 경우에만 표시됩니다. -3. **`// quirks`** — 놓친 것들: failproofai가 포착했을 동작의 순위표 — *마지막 발생 시점*, *무엇이 놓쳤는지* (차단했을 내장 정책 포함), *심각도*, 그리고 얼마나 자주 *발생했는지* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — 권장 수정 목록: 복사 붙여넣기 가능한 `failproofai policy add `가 포함된 정책별 행, 모든 권장 사항을 한 번에 활성화하는 **install all** 버튼과 적용 시의 **예상 점수** 표시. -5. **`// come back better`** — 습관 형성: 재감사 이메일 **리마인더** 설정 (`3d` / `7d` / `14d` / `30d`) 또는 지금 재감사 실행, **친구 초대**를 통한 자체 감사 실행 (failproof.ai에서 발송, 참조로 사용자 포함). 리마인더와 초대는 로그인이 필요합니다. +1. **포스터** — 에이전트의 정체성을 한눈에: **아키타입**(8종 중 하나 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), 페르소나 키워드, 해당 아키타입의 희귀도, 티어 밴드와 함께하는 **0~100 점수**(`S`부터 `bottom tier`까지). 공유용으로 제작 — X나 LinkedIn에 게시하거나 PNG로 다운로드할 수 있습니다. +2. **`// strengths`** — 에이전트가 이미 잘하고 있는 것들: 스캔에서 나온 실제 수치(예: clean-tool-call %, push-to-main 시도 `0`회)로, 관련 정책에 깨끗한 기록이 있는 경우에만 표시됩니다. +3. **`// quirks`** — 빠져나간 것들: failproofai가 잡았을 행동들의 순위 표 — *언제* 마지막으로 발생했는지, *무엇이 빠져나갔는지*(그리고 이를 차단했을 내장 정책), *심각도*, 얼마나 자주 *발견됐는지*(`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — 처방된 수정 목록: 복사-붙여넣기 가능한 `failproofai policy add `가 있는 정책별 행과, 모든 권장 사항을 한 번에 활성화하는 **install all** 버튼 및 실행했을 때의 **예상 점수** 표시. +5. **`// come back better`** — 습관 만들기: 재감사 이메일 **리마인더** 설정(`3d` / `7d` / `14d` / `30d`) 또는 지금 재감사, 그리고 **친구 초대**로 직접 감사를 실행하게 하기(failproof.ai에서 발송, 수신자에게 참조). 리마인더와 초대는 로그인이 필요합니다. ## 예약 감사 -**failproofaid 데몬**을 실행 중이라면 ([`failproofai config`](/ko/cli/install-policies) 참조), -일정에 따라 감사를 자동으로 재실행하고 백그라운드에서 `/audit` 리포트를 갱신할 수 있습니다. -기본적으로 **비활성화**되어 있습니다. 이 기기의 모든 에이전트 세션 트랜스크립트 *내용*을 -읽기 때문에 — 명시적으로 요청하기 전까지는 타이머로 스캔이 실행되지 않습니다. +**failproofaid 데몬**을 실행 중이라면([`failproofai config`](/ko/cli/install-policies) 참고), +일정에 따라 감사를 재실행하고 `/audit` 보고서를 백그라운드에서 새로고침할 수 있습니다. +**기본적으로 비활성화**되어 있습니다. 스캔은 이 머신의 모든 에이전트 세션 트랜스크립트의 *내용*을 읽기 때문에 — 직접 요청하기 전까지는 타이머로 스캔되는 것이 없습니다. -`~/.failproofai/config.toml`에서 활성화하세요: +`~/.failproofai/config.json`에서 활성화할 수 있습니다 — 파일에 이미 있는 내용 옆에 `audit` 키를 추가하세요: -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | 키 | 의미 | |---|---| -| `auto` | `true`로 설정하면 예약 스캔이 활성화됩니다. 그 외 — 없음, `false`, `"yes"` — 는 비활성화입니다. | -| `interval_days` | 스캔 간격(일). 1~90으로 제한되며, `0`, 음수, 숫자가 아닌 값은 `7`로 대체됩니다. | - -- 일정은 **실제 시계** 기준이므로 절전 및 재부팅 후에도 유지됩니다: 예정 시간을 지나 - 절전 상태였던 노트북은 깨어난 후 **한 번만** 실행되며, 밀린 작업을 누적하지 않습니다. -- 각 실행은 별도의 낮은 우선순위(`nice 19`) 프로세스로 실행됩니다 — 도구 호출 응답을 - 위해 항상 여유 있는 데몬의 훅 경로에는 영향을 주지 않습니다. -- `failproofai audit` 또는 대시보드의 재실행이 이미 진행 중인 경우 스캔을 건너뛰며, - 실패로 처리하는 대신 잠시 후 재시도합니다. -- 진행 상황은 `~/.failproofai/state/audit-schedule.json`에 기록됩니다 (마지막 실행, - 다음 예정). 해당 파일은 데몬이 관리하며 — 주기는 `config.toml`에서 변경하세요. +| `auto` | `true`로 설정하면 예약 스캔이 활성화됩니다. 그 외의 값 — 없거나, `false`, `"yes"` — 은 비활성화입니다. | +| `interval_days` | 스캔 간격(일). 1~90으로 제한; `0`, 음수, 숫자가 아닌 값은 `7`로 대체됩니다. | + +- 일정은 **벽시계 기준**이라 절전 및 재부팅 이후에도 유지됩니다: 예정 시간을 지나 절전 상태였던 노트북은 깨어난 후 **한 번** 실행되며, 밀린 실행은 없습니다. +- 각 실행은 별도의 낮은 우선순위(`nice 19`) 프로세스입니다 — 도구 호출에 응답하는 데몬의 훅 경로는 절대 차지하지 않습니다. +- `failproofai audit` 또는 대시보드의 재실행이 이미 진행 중이면 스캔은 건너뛰고, 실패로 처리하는 대신 잠시 후 재시도됩니다. +- 진행 상황은 `~/.failproofai/state/audit-schedule.json`에 기록됩니다(마지막 실행, 다음 예정 시간). 데몬이 해당 파일을 관리하므로 — 주기는 `config.json`에서 변경하세요. -이전 버전의 failproofai로 설정된 기기에서 이 기능을 활성화했다면, -`failproofai config`를 한 번 실행하세요. CLI를 시작하기 전에 데몬의 서비스 정의에 -추가 항목이 하나 필요하며, 해당 명령 실행 시 갱신됩니다. +오래된 failproofai로 설정된 머신에서 이 기능을 활성화했다면, +`failproofai config`를 한 번 실행하세요. 데몬의 서비스 정의에 CLI를 실행하기 위한 +항목이 하나 더 필요하며, 해당 명령어에 새로고침이 포함되어 있습니다. -## 감사 전용 디텍터 +## 감사 전용 탐지기 -런타임에 아직 적용되지 않는 "불합리한 동작" 패턴을 감지합니다. 감사 중에만 실행되며 -라이브 도구 호출을 절대 차단하지 않습니다. +이 탐지기들은 실시간으로 (아직) 강제되지 않는 "비효율적인 동작" 패턴을 감지합니다. 감사 중에만 실행되며 라이브 도구 호출을 절대 차단하지 않습니다. -| 디텍터 | 감지 내용 | +| 탐지기 | 집계 대상 | |---|---| -| `redundant-cd-cwd` | 명령이 이미 `cwd`에서 실행되는데도 `cd && …`로 시작하는 Bash 명령. | +| `redundant-cd-cwd` | 명령어가 이미 `cwd`에서 실행되는데 `cd && …`로 시작하는 Bash 명령어. | | `prefer-edit-over-read-cat` | 단일 소스 파일에 대한 `cat`/`head`/`tail`/`less`/`more` — `Read` 도구를 사용하세요. | | `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` 인플레이스 편집 — `Edit` 도구를 사용하세요. | -| `prefer-write-over-heredoc` | Heredoc / 멀티라인 `echo > file` 파일 쓰기 — `Write` 도구를 사용하세요. | -| `sleep-polling-loop` | 긴 `sleep N` (≥ 30초) 또는 `while …; sleep …; done` 폴링 루프. | -| `find-from-root` | `find /`, `find /home`, `find /usr` 등 — `cwd`로 범위를 제한하세요. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, 훅 건너뜀. | -| `reread-after-edit` | 같은 세션에서 `Edit`/`Write`된 직후 파일을 `Read`하는 경우. | +| `prefer-write-over-heredoc` | Heredoc / 여러 줄 `echo > file` 파일 쓰기 — `Write` 도구를 사용하세요. | +| `sleep-polling-loop` | 긴 `sleep N`(≥ 30초) 또는 `while …; sleep …; done` 폴링 루프. | +| `find-from-root` | `find /`, `find /home`, `find /usr` 등 — `cwd`로 범위를 좁히세요. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, 훅을 건너뜀. | +| `reread-after-edit` | 같은 세션에서 방금 `Edit`/`Write`한 파일을 `Read`하는 경우. | ## 캐시 -- **트랜스크립트별 캐시**: `(mtime, size, engineVersion, detectorVersion)`을 키로 하는 `~/.failproofai/cache/audit/.json` — 트랜스크립트나 정책/디텍터 코드가 변경되면 자동으로 무효화됩니다. 각 항목에는 **TTL 메타데이터**로 `cachedAt` 타임스탬프가 저장됩니다 (캐시 키의 일부는 아님). **7일**이 지난 항목은 읽을 때 거부되어 오래된 결과가 변화하는 디텍터 의도를 초과하지 않도록 합니다. -- **전체 결과 캐시**: `~/.failproofai/audit-dashboard.json` (모드 0600). 재실행 없이 대시보드가 탐색 시 즉시 렌더링될 수 있도록 합니다. **7일 TTL**이 지나면 읽기 시 거부되며 — `/audit`은 빈 상태로 돌아가 새 실행을 요청합니다. 리포트 하단의 `[ re-audit now ]`를 클릭하면 갱신됩니다 — 재감사는 `noCache: true`를 전송하므로 트랜스크립트별 캐시를 우회하고 캐시된 결과 대신 모든 트랜스크립트를 재스캔합니다. 실행 중 진행 상황은 상단의 고정 스트립으로 스트리밍되며 성공 시 결과가 제자리에서 교체됩니다 (페이지 새로고침 없음; 재감사 실패 시 이전 리포트 유지). +- **트랜스크립트별 캐시**는 `~/.failproofai/cache/audit/.json`에 `(mtime, size, engineVersion, detectorVersion)` 키로 저장 — 트랜스크립트나 정책/탐지기 코드가 변경되면 자동으로 무효화됩니다. 각 항목에는 **TTL 메타데이터**로 `cachedAt` 타임스탬프가 저장됩니다(캐시 키의 일부가 아님); **7일**이 지난 항목은 읽을 때 거부되므로 오래된 결과가 탐지기 의도의 변화를 넘어 지속되지 않습니다. +- **전체 결과 캐시**는 `~/.failproofai/audit-dashboard.json`(모드 0600)에 저장됩니다. 대시보드가 재실행 없이 즉시 렌더링되도록 합니다. **7일 TTL**이 지나면 읽기 시 거부 — `/audit`은 빈 상태로 폴백하고 새 실행을 안내합니다. 보고서 하단의 `[ re-audit now ]`를 클릭해 새로고침 — 재감사는 `noCache: true`를 전송하므로 트랜스크립트별 캐시를 우회하고 캐시된 결과를 반환하는 대신 모든 트랜스크립트를 재스캔합니다; 실행은 상단 고정 스트립으로 진행 상황을 스트리밍하고 성공 시 결과를 제자리에서 교체합니다(페이지 새로고침 없음; 재감사 실패 시 이전 보고서 유지). ## 참고 사항 -- **변경 없음.** 감사는 읽기 전용 모드로 재실행됩니다. `warn-repeated-tool-calls`는 세션별 사이드카가 수정될 수 있으므로 건너뜁니다. -- **워크플로 정책 건너뜀.** `require-*-before-stop` 정책은 `Stop` 이벤트에서만 실행되고 라이브 git 상태에 대해 `execSync`를 호출합니다 — "2025년에 어떤 일이 일어났을까"에 대한 의미 있는 해석이 없으므로 감사 카운트에 나타나지 않습니다. -- **커스텀 정책 건너뜀.** 사용자가 제공한 커스텀 훅은 재실행되지 않습니다 (원래 세션 이후 변경되었을 수 있기 때문입니다). \ No newline at end of file +- **변경 없음.** 감사는 읽기 전용 모드로 재실행됩니다. `warn-repeated-tool-calls`는 건너뜁니다. 그렇지 않으면 세션별 사이드카가 수정될 수 있기 때문입니다. +- **워크플로 정책 건너뜀.** `require-*-before-stop` 정책은 `Stop` 이벤트에서만 실행되고 라이브 git 상태에 대해 `execSync`를 호출합니다 — "2025년에 어떤 일이 일어났을까"라는 의미 있는 해석이 없으므로 감사 카운트에 포함되지 않습니다. +- **커스텀 정책 건너뜀.** 사용자가 제공한 커스텀 훅은 재실행되지 않습니다(원래 세션 이후 변경되었을 수 있습니다). \ No newline at end of file diff --git a/docs/ko/cli/dashboard.mdx b/docs/ko/cli/dashboard.mdx index 02a5cd33..43507ae7 100644 --- a/docs/ko/cli/dashboard.mdx +++ b/docs/ko/cli/dashboard.mdx @@ -1,6 +1,6 @@ --- title: 세션 보기 -description: "대시보드를 실행하여 에이전트 세션을 탐색하고 정책을 관리합니다" +description: "대시보드를 실행하여 에이전트 세션을 탐색하고 정책을 관리하세요" --- ```bash @@ -13,17 +13,17 @@ failproofai | 플래그 | 설명 | |--------|------| -| `--port ` | 수신할 포트 (기본값: `8020`) | -| `--allowed-origins ` | 개발 리소스에 접근할 수 있는 쉼표로 구분된 호스트/IP 목록 | +| `--port ` | 수신 대기할 포트 (기본값: `8020`) | +| `--allowed-origins ` | 개발 리소스에 접근할 수 있는 호스트/IP 목록 (쉼표로 구분) | -기본값이 아닌 Claude 프로젝트 폴더를 대시보드에 지정하려면, 실행 시 `CLAUDE_PROJECTS_PATH` 환경 변수를 설정하세요. +대시보드가 기본값이 아닌 Claude 프로젝트 폴더를 가리키도록 하려면, 실행 시 `CLAUDE_PROJECTS_PATH` 환경 변수를 설정하세요. ## 예시 ```bash -# Launch on a different port +# 다른 포트로 실행 failproofai --port 9000 -# Use a custom Claude projects path via environment variable +# 환경 변수를 통해 커스텀 Claude 프로젝트 경로 사용 CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/ko/cli/environment-variables.mdx b/docs/ko/cli/environment-variables.mdx index db963bad..96decd4d 100644 --- a/docs/ko/cli/environment-variables.mdx +++ b/docs/ko/cli/environment-variables.mdx @@ -1,6 +1,6 @@ --- title: 환경 변수 -description: "환경 변수로 failproofai 동작 설정하기" +description: "환경 변수로 failproofai 동작을 구성하세요" --- ## 대시보드 @@ -8,54 +8,54 @@ description: "환경 변수로 failproofai 동작 설정하기" | 변수 | 설명 | |----------|-------------| | `PORT` | 대시보드 포트 (기본값: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Claude Code 프로젝트 폴더 위치 재정의 | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 숨길 대시보드 페이지를 쉼표로 구분하여 지정 | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | 개발 리소스 접근을 허용할 호스트/IP. `--allowed-origins`와 동일. | +| `CLAUDE_PROJECTS_PATH` | Claude Code 프로젝트 폴더 위치를 재정의합니다 | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 숨길 대시보드 페이지를 쉼표로 구분하여 지정합니다 | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | 개발 리소스에 접근을 허용할 호스트/IP. `--allowed-origins`와 동일합니다. | ## 로깅 | 변수 | 설명 | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | 서버 로그 레벨 (기본값: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | 커스텀 훅 로그 파일 경로, 또는 기본 경로(`~/.failproofai/logs/hooks.log`)를 사용하려면 `true` | +| `FAILPROOFAI_HOOK_LOG_FILE` | 커스텀 훅 로그 파일 경로, 또는 기본 경로(`~/.failproofai/logs/hooks.log`)를 사용하려면 `true`로 설정합니다 | ## 텔레메트리 -failproofai는 기본적으로 익명 사용 텔레메트리를 전송합니다. 비활성화하는 방법은 -두 가지가 있으며, 더 제한적인 설정이 우선 적용됩니다. 즉, 환경 변수로는 설정 -파일에서 비활성화한 기능을 다시 활성화할 수 없습니다. +failproofai는 기본적으로 익명 사용 텔레메트리를 전송합니다. 비활성화하는 방법은 두 가지이며, 더 제한적인 설정이 우선 적용됩니다. 즉, 환경 변수로 설정 파일에서 비활성화한 항목을 다시 활성화할 수 없습니다. | 변수 | 설명 | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 현재 프로세스에서 익명 사용 텔레메트리 비활성화 | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 현재 프로세스의 익명 사용 텔레메트리를 비활성화합니다 | -머신에서 영구적으로 비활성화하려면 `~/.failproofai/config.toml`에 다음을 추가하세요: +시스템 전체에서 영구적으로 비활성화하려면 `~/.failproofai/config.json`에 다음을 추가하세요: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -**failproofaid 데몬**을 실행 중이라면 설정 파일 방식을 사용해야 합니다. -데몬은 시스템 범위 서비스이며, 셸에서 내보낸 환경 변수를 포함하지 않으므로 -`FAILPROOFAI_TELEMETRY_DISABLED`가 데몬에 전달되지 않습니다. `[telemetry] enabled = false`는 CLI와 데몬 모두에서 읽힙니다. +**failproofaid 데몬**을 실행하는 경우에는 설정 파일을 사용하세요. +데몬은 시스템 범위의 서비스이므로, 셸에서 내보낸 환경 변수를 포함하지 않습니다. 따라서 `FAILPROOFAI_TELEMETRY_DISABLED`는 데몬에 적용되지 않습니다. `[telemetry] enabled = false`는 CLI와 데몬 모두에서 읽힙니다. -데몬은 자체적인 **라이프사이클** 이벤트만 보고합니다. 시작 여부(이전 실행이 정상 종료되었는지 포함), 중지, 평가 워커의 생성 또는 재시작, 수집기 작업 실패, 클라우드 정책 가져오기 결과 등입니다. 이 데이터는 낮은 카디널리티 값과 카운트만 포함하며, 파일 경로, 명령어, 정책, 프롬프트, 또는 트랜스크립트에서 읽은 내용은 절대 포함되지 않습니다. 도구 호출별 이벤트는 존재하지 않습니다. +데몬은 자체 **라이프사이클** 정보만 보고합니다. 시작 여부(이전 실행이 정상 종료되었는지 포함), 중지, 평가 워커의 생성 또는 재시작, 컬렉터 작업 실패, 클라우드 정책 가져오기 결과 등이 해당됩니다. 이 데이터에는 낮은 카디널리티 값과 횟수만 포함되며, 파일 경로, 명령, 정책, 프롬프트, 또는 트랜스크립트에서 읽어온 어떠한 내용도 포함되지 않습니다. 도구 호출별 이벤트는 없습니다. ## 인증 | 변수 | 설명 | |----------|-------------| -| `FAILPROOF_API_URL` | 대시보드 인증 다이얼로그에서 사용하는 API 서버 기본 URL 재정의. 기본값은 `https://api.befailproof.ai`이며, 로컬 API 서버 실행 시 `http://localhost:8080`(또는 해당 주소)으로 설정. | -| `FAILPROOFAI_AUTH_DIR` | `auth.json` 저장 위치 재정의 (기본값: `~/.failproofai`). 주로 격리된 테스트 환경에서 유용. | +| `FAILPROOF_API_URL` | 대시보드 인증 다이얼로그에서 사용하는 API 서버 기본 URL을 재정의합니다. 기본값은 `https://api.befailproof.ai`이며, 로컬 API 서버를 실행할 때는 `http://localhost:8080`(또는 해당 주소)으로 설정하세요. | +| `FAILPROOFAI_AUTH_DIR` | `auth.json`이 저장되는 위치를 재정의합니다 (기본값: `~/.failproofai`). 주로 격리된 테스트 환경에서 유용합니다. | ## 최초 실행 프롬프트 | 변수 | 설명 | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | `failproofai`를 처음 단독 실행할 때 정책 설치를 제안하는 프롬프트 건너뛰기 | +| `FAILPROOFAI_NO_FIRST_RUN=1` | `failproofai`를 처음 실행할 때 정책 설치를 제안하는 프롬프트를 건너뜁니다 | ## LLM (정책 평가용) diff --git a/docs/ko/cli/hook.mdx b/docs/ko/cli/hook.mdx index 6427a7bb..4e1ea879 100644 --- a/docs/ko/cli/hook.mdx +++ b/docs/ko/cli/hook.mdx @@ -7,15 +7,15 @@ description: "각 도구 이벤트마다 Claude Code가 호출하는 서브프 failproofai --hook ``` -이 명령은 `failproofai policies --install`이 Claude Code의 `settings.json`에 등록하는 명령입니다. 일반적으로 직접 호출하지 않습니다. +이 명령어는 `failproofai policies --install`이 Claude Code의 `settings.json`에 등록하는 명령어입니다. 일반적으로 직접 호출하지 않습니다. -stdin으로부터 JSON 페이로드를 읽고, 활성화된 모든 정책을 평가한 뒤, 결정 내용을 나타내는 종료 코드와 함께 프로세스를 종료합니다: +stdin으로부터 JSON 페이로드를 읽고, 활성화된 모든 정책을 평가한 뒤, 결정 내용을 나타내는 종료 코드와 함께 종료됩니다: | 종료 코드 | 결정 | 효과 | |-----------|----------|--------| -| `0` | `allow` | 작업을 허용합니다 | -| `1` | `deny` | 작업을 차단합니다 — Claude는 거부 사유를 확인합니다 | -| `2` | `instruct` | Claude의 컨텍스트에 가이드를 주입합니다 | +| `0` | `allow` | 작업 허용 | +| `1` | `deny` | 작업 차단 - Claude가 거부 이유를 확인함 | +| `2` | `instruct` | Claude의 컨텍스트에 가이던스 주입 | ### 지원되는 이벤트 유형 diff --git a/docs/ko/cli/install-policies.mdx b/docs/ko/cli/install-policies.mdx index 9d25fa9b..fafb68ab 100644 --- a/docs/ko/cli/install-policies.mdx +++ b/docs/ko/cli/install-policies.mdx @@ -1,13 +1,13 @@ --- title: 정책 설치 -description: "에이전트의 모든 도구 호출에서 정책이 실행되도록 활성화합니다" +description: "에이전트의 모든 도구 호출 시 정책이 실행되도록 활성화합니다" --- ```bash failproofai policies --install [policy-names...] [options] ``` -설치된 에이전트 CLI(Claude Code, OpenAI Codex, 또는 GitHub Copilot CLI _(베타)_)의 설정 파일에 훅 항목을 작성하여 failproofai가 도구 호출을 가로챌 수 있도록 합니다. +설치된 에이전트 CLI(Claude Code, OpenAI Codex, 또는 GitHub Copilot CLI _(베타)_)의 설정 파일에 훅 항목을 기록하여 failproofai가 도구 호출을 가로챌 수 있도록 합니다. 별칭: `failproofai p -i` @@ -15,19 +15,19 @@ failproofai policies --install [policy-names...] [options] | 플래그 | 설명 | |------|-------------| -| `--cli claude\|codex\|copilot` | 설치할 에이전트 CLI; 공백으로 구분(예: `--cli claude codex copilot`)하거나 반복 사용 가능. 생략하면 설치된 CLI를 자동으로 감지하고 선택 프롬프트를 표시합니다. | -| `--scope user` | 사용자 범위 설정 파일에 설치합니다(Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). 기본값. | -| `--scope project` | 프로젝트 범위 설정 파일에 설치합니다(Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--cli claude\|codex\|copilot` | 설치할 대상 에이전트 CLI. 공백으로 구분하거나(예: `--cli claude codex copilot`) 반복 지정 가능. 생략하면 설치된 CLI를 자동으로 감지하고 선택을 묻는 프롬프트가 표시됩니다. | +| `--scope user` | 사용자 범위 설정 파일에 설치합니다 (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). 기본값. | +| `--scope project` | 프로젝트 범위 설정 파일에 설치합니다 (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | | `--scope local` | Claude 전용 — `/.claude/settings.local.json`에 설치합니다. Codex와 Copilot은 `local` 범위를 지원하지 않습니다. | | `--custom ` / `-c` | 사용자 정의 훅 정책이 담긴 JS 파일 경로 | ## 동작 방식 - **정책 이름 미지정** - 정책을 선택할 수 있는 대화형 프롬프트가 열립니다 -- **특정 이름 지정** - 해당 정책을 활성화합니다(이미 활성화된 정책에 추가됩니다) +- **특정 이름 지정** - 해당 정책을 활성화합니다 (이미 활성화된 정책에 추가됩니다) - **`all`** - 사용 가능한 모든 정책을 활성화합니다 -설치는 누적 방식으로 동작합니다. `--install`을 다시 실행해도 기존 정책이 제거되지 않고 새로운 정책만 추가됩니다. +설치는 누적 방식으로 동작합니다. `--install`을 다시 실행하면 기존 정책을 제거하지 않고 새 정책만 추가됩니다. ## 예시 @@ -47,11 +47,11 @@ failproofai policies --install --custom ./my-policies.js # OpenAI Codex에 설치 (프로젝트 범위) failproofai policies --install --cli codex --scope project -# 현재 프로젝트에 GitHub Copilot CLI (베타) 설치 +# GitHub Copilot CLI (베타)에 현재 프로젝트 범위로 설치 failproofai policies --install --cli copilot --scope project -# 세 가지 CLI 모두에 한 번에 설치 +# 세 CLI 모두에 한 번에 설치 failproofai policies --install --cli claude codex copilot ``` -`--custom `가 지정된 경우, 파일이 즉시 유효성 검사를 거칩니다 — `customPolicies.add()`를 최소 한 번 이상 호출해야 합니다. 확인된 경로는 `customPoliciesPath`로 `policies-config.json`에 저장됩니다. \ No newline at end of file +`--custom `가 지정되면 파일이 즉시 유효성 검사를 거칩니다. 파일은 반드시 `customPolicies.add()`를 한 번 이상 호출해야 합니다. 해석된 경로는 `customPoliciesPath`로 `policies-config.json`에 저장됩니다. \ No newline at end of file diff --git a/docs/ko/cli/list-policies.mdx b/docs/ko/cli/list-policies.mdx index 39962694..f25ffdb4 100644 --- a/docs/ko/cli/list-policies.mdx +++ b/docs/ko/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- -title: 정책 목록 보기 -description: "활성화된 정책, 매개변수, 커스텀 정책 확인하기" +title: 정책 목록 확인 +description: "활성화된 정책, 해당 매개변수, 커스텀 정책 확인" --- ```bash failproofai policies ``` -모든 정책의 상태, 구성된 매개변수, 커스텀 정책을 표시합니다. +모든 정책의 상태, 설정된 매개변수, 커스텀 정책을 표시합니다. ## 출력 예시 @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -`policyParams`에 알 수 없는 키가 있으면 이 목록에 표시되므로 오타를 조기에 발견할 수 있습니다. \ No newline at end of file +`policyParams`에 알 수 없는 키가 있으면 여기에 표시되므로 오타를 조기에 발견할 수 있습니다. \ No newline at end of file diff --git a/docs/ko/cli/migrate.mdx b/docs/ko/cli/migrate.mdx new file mode 100644 index 00000000..63827473 --- /dev/null +++ b/docs/ko/cli/migrate.mdx @@ -0,0 +1,86 @@ +--- +title: 홈 디렉터리 마이그레이션 +description: "~/.failproofai를 현재 버전에 맞는 구조로 업데이트하거나, 실행 전에 예상 결과를 미리 확인하세요" +--- + +```bash +failproofai migrate --dry-run # 계획만 출력하고 아무것도 변경하지 않음 +failproofai migrate # 실제 실행 +``` + +대부분의 경우 이 명령을 직접 입력할 필요는 없습니다. 업그레이드 후 첫 번째 명령을 실행할 때 자동으로 수행되며, [`failproofai update`](/ko/cli/update)에도 포함되어 있습니다. 실행 전에 계획을 미리 확인하거나 마이그레이션을 단독으로 실행하고 싶을 때 직접 사용하세요. + +## 버전이 아닌 레이아웃 기준 + +`~/.failproofai/VERSION`에는 릴리스 버전이 아닌 **레이아웃** 번호가 기록됩니다. 이는 디렉터리의 구조를 나타내며, 마이그레이션은 이 번호를 기준으로 동작합니다. 덕분에 버전 간격이 크더라도 비용이 적게 듭니다. + +- npm 버전은 모든 릴리스마다 변경되며, 두 레이아웃 사이에도 수십 번 바뀔 수 있습니다. +- 따라서 **레이아웃 변경 없이** 서른 번의 릴리스를 건너뛴 머신은 서른 번의 no-op 대신 **마이그레이션을 실행하지 않습니다**. +- 그리고 여러 레이아웃을 한 번에 건너뛴 머신은 각 단계를 순서대로 실행하며, 각 단계는 자신의 양 끝만을 처리합니다. + +npm은 설치된 패키지를 자동으로 업데이트할 수 없기 때문에 이 점이 중요합니다. 오랫동안 한 버전에 머물다가 여러 레이아웃을 한 번에 건너뛰는 경우는 예외적인 상황이 아니라 일반적인 경우입니다. + +## 드라이 런 + +`--dry-run`은 실행될 전체 체인과 먼저 저장될 파일 목록을 출력하며, 마이그레이션, 백업, 기록 등 아무것도 변경하지 않습니다. + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## 보존되는 항목과 재생성되는 항목 + +홈 디렉터리의 각 경로는 보유한 데이터의 종류를 나타내며, 이에 따라 마이그레이션이 해당 데이터를 삭제할 수 있는지 여부가 결정됩니다. 규칙은 다음과 같습니다. **파생되었거나 다시 가져올 수 있는 데이터는 삭제될 수 있고, 직접 입력한 항목, 아직 전달되지 않은 항목, 머신을 식별하는 항목은 보존됩니다.** + +| 보존 | 재생성 또는 재수집 | +|---|---| +| `config.json` — 설정, `daemon.configured`, 추가 캡처 경로 | 감사 캐시 | +| `credentials.json` — 클라우드 등록 정보 | 클라우드 관리 배포 (다음 폴링 시 재수집 및 다이제스트 검증) | +| `policies-config.json` — 정책 선택 및 파라미터 | 데몬 임시 상태 | +| `policies/` — 직접 작성한 정책 파일 및 해당 파일이 임포트하는 헬퍼 | | +| `hook-activity/` — 대시보드가 읽는 결정 로그 | | +| 업로드 대기 중인 미전달 이벤트 | | +| `cursors/` — 컬렉터 워터마크 | | +| `bin/`의 데몬 바이너리 | | + + + 미전달 이벤트는 삭제하면 속도만 느려지는 것이 아니라 영구적으로 손실되기 때문에 보존됩니다. 컬렉터의 워터마크가 스풀에 있는 데이터를 이미 지나쳤기 때문에, 해당 트랜스크립트 범위를 다시 읽는 것은 불가능합니다. 마이그레이션은 완료 즉시 데몬에게 스풀에 남은 데이터를 전달하도록 요청하므로, 일반적으로 보존할 항목이 남지 않습니다. + + +*더 최신* 버전이 `config.json`, `credentials.json`, `policies-config.json`에 기록한 키도 이전 버전 리더에 의해 삭제되지 않고 보존됩니다. + +## 남겨지는 기록 + +``` +~/.failproofai/migrations/ + applied.json 단계별 항목: 레이아웃, CLI, 타임스탬프, 소요 시간, 결과 + backup-layout/ 첫 번째 단계 실행 전에 복사한 복원 불가능한 파일들 +``` + +`applied.json`은 "이 머신이 실제로 어떤 과정을 거쳤는가"라는 질문에 답합니다. 업그레이드 후 문제가 발생했을 때 가장 먼저 확인해야 할 파일입니다. 버그 리포트에 첨부하세요. + +백업은 디렉터리 전체 복사본이 아닌 의도적으로 소규모로 유지됩니다. 마이그레이션은 설계상 복원 불가능한 항목을 더 이상 삭제하지 않으므로, 보험이 필요한 경우는 *단계 내 결함*이며, 이 몇 개의 파일이 그러한 결함의 영향을 받는 대상입니다. + +## 단계가 실패할 경우 + +해당 지점에서 체인이 중단됩니다. `VERSION`은 완료된 단계에서만 기록되므로, 홈 디렉터리는 이전 레이아웃으로 표시된 채 유지되고 다음 명령이 재시도합니다. 마이그레이션이 부분적으로만 완료된 상태에서 홈이 최신으로 표시되는 일은 없습니다. 해당 단계는 `"ok": false`로 `applied.json`에 기록되며, 백업은 생성된 위치에 그대로 남습니다. + +## 더 최신의 홈 디렉터리는 마이그레이션되지 않고 거부됩니다 + +현재 실행 중인 failproofai보다 **더 최신** failproofai가 `~/.failproofai/`에 기록한 경우, 명령이 중단되고 업그레이드를 안내합니다. 해당 데이터는 정상이며 더 최신 CLI가 읽을 수 있습니다. "앞으로" 마이그레이션하는 것은 존재하지 않는 개념이며, 초기화하면 복구 가능한 데이터를 잃게 됩니다. + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +데몬도 동일한 규칙을 적용합니다. `failproofaid`는 인식할 수 없는 레이아웃에 대해 이동된 경로를 읽고 쓰는 대신, 시작 자체를 거부합니다. \ No newline at end of file diff --git a/docs/ko/cli/remove-policies.mdx b/docs/ko/cli/remove-policies.mdx index f227e922..1ee546c2 100644 --- a/docs/ko/cli/remove-policies.mdx +++ b/docs/ko/cli/remove-policies.mdx @@ -24,7 +24,7 @@ Claude Code의 `settings.json`에서 failproofai 훅 항목을 제거합니다. ## 동작 방식 - **정책 이름 미지정** - 설정 파일에서 모든 failproofai 훅 항목을 제거합니다 -- **특정 이름 지정** - 해당 정책을 비활성화하되 훅은 설치된 상태로 유지합니다 +- **특정 이름 지정** - 해당 정책을 비활성화하지만 훅은 설치된 상태로 유지합니다 ## 예시 @@ -32,7 +32,7 @@ Claude Code의 `settings.json`에서 failproofai 훅 항목을 제거합니다. # 전역에서 모든 훅 제거 failproofai policies --uninstall -# 특정 정책 비활성화 (훅은 설치 상태 유지) +# 특정 정책 비활성화 (훅은 설치된 상태 유지) failproofai policies --uninstall block-sudo # 모든 범위에서 훅 제거 diff --git a/docs/ko/cli/update.mdx b/docs/ko/cli/update.mdx new file mode 100644 index 00000000..d60e8f89 --- /dev/null +++ b/docs/ko/cli/update.mdx @@ -0,0 +1,74 @@ +--- +title: 업그레이드 후 업데이트 +description: "npm이 처리하지 못하는 나머지 절반의 업그레이드 완료: 홈 디렉토리 마이그레이션과 데몬 동기화" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +업그레이드는 이것으로 전부입니다. `npm`이 CLI를 교체하고, `failproofai update`가 나머지를 처리합니다. + +## 두 번째 명령이 필요한 이유 + +`npm install -g`는 한 가지만 교체합니다 — CLI입니다. failproofai 설치의 나머지 두 구성 요소는 의도적으로 패키지 외부에 위치하며, npm이 실행될 때 어느 것도 이동하지 않습니다. + +- **`~/.failproofai/`** — 설정, 클라우드 등록, 정책 선택 및 히스토리가 저장되는 곳입니다. 새 버전은 이 구조를 다르게 구성할 수 있으며, 재구성은 두 가지 형태를 모두 아는 코드가 수행해야 합니다. +- **`failproofaid` 데몬 바이너리** — `~/.failproofai/bin/failproofaid-`에 위치합니다. 이것은 의도적으로 `node_modules` *내부에 두지 않습니다*. 실행 중인 서비스 아래에서 파일을 교체하면 다른 소스로 빌드된 바이너리를 가리키게 되고, 패키지를 제거하면 서비스가 부팅 시마다 크래시 루프에 빠지게 됩니다. + +따라서 `npm install -g`만 실행하면 CLI는 최신 버전이지만 데몬은 그렇지 않습니다. `failproofaid`는 자신이 인식하지 못하는 홈 레이아웃에 대해 시작을 거부합니다 — 조용히 넘어가는 것이 아닌 명확한 오류를 발생시킵니다 — 따라서 두 부분을 함께 맞추는 작업이 필요합니다. 바로 `failproofai update`가 그 역할을 합니다. + +## 수행 내용 + + + + `~/.failproofai/VERSION`에 기록된 레이아웃을 읽고, 현재 버전이 사용하는 레이아웃으로 + 전환하는 단계를 실행합니다. 대부분의 경우 수행할 내용이 없습니다 — + [`failproofai migrate`](/ko/cli/migrate)를 참고하세요. + + + 가능한 경우 npm이 이미 다운로드한 플랫폼 패키지에서 가져옵니다(네트워크 불필요). + 그렇지 않으면 정확히 이 버전의 릴리스 에셋에서 가져오며, 사용 전에 SHA-256 검증을 수행합니다. + + + 가정이 아닌 실제 프로브로 확인합니다 — 서비스 관리자는 프로세스가 포크되는 순간 활성 상태로 보고하는데, + 이것이 실제로 작동하는 것과는 다릅니다. + + + +## 옵션 + +| 플래그 | 효과 | +|--------|------| +| `--no-daemon` | 데몬을 현재 버전으로 유지한 채 홈 디렉토리만 마이그레이션합니다. | + + + `--no-daemon`을 사용하면 버전이 맞지 않는 데몬이 그대로 남습니다. 데몬이 필수로 구성된 머신에서는 + 데몬이 응답하지 못할 경우 모든 훅 이벤트가 **fail closed** 처리됩니다 — 마이그레이션된 홈에 대해 + 시작을 거부하는 데몬은 응답할 수 없습니다. 데몬 부분도 함께 실행하는 것을 권장합니다. + + +## 문제 발생 시 + +명령은 0이 아닌 종료 코드와 함께 어느 부분에서 실패했는지 알려줍니다. 알아두어야 할 두 가지 경우: + +- **마이그레이션 단계가 완료되지 않은 경우.** 홈 디렉토리는 *이전* 레이아웃으로 표시된 상태로 유지되므로 다음 명령 실행 시 재시도합니다 — 부분 마이그레이션이 완료된 것으로 표시되는 일은 없습니다. 실행 전에 설정 및 등록 정보의 사본이 `~/.failproofai/migrations/backup-layout/`에 저장됩니다. +- **비밀번호 없이 데몬을 재시작할 수 없는 경우.** `sudo -n`이 의도적으로 사용되므로, 진행 상황 표시 중에 비밀번호를 묻는 일은 없습니다. 명령은 직접 실행해야 할 정확한 명령줄을 출력합니다. + + + 이 과정에서 대화형 설정 마법사는 필요하지 않습니다. 설정, 클라우드 등록, 정책 선택은 업그레이드 후에도 + 그대로 유지되므로, 마이그레이션된 머신은 이전과 동일하게 정책을 적용합니다 — 이는 CI 러너, 플릿 + 박스, 헤드리스 게이트웨이처럼 아무도 앞에 앉아 있지 않은 머신에서 특히 중요합니다. + + +## 자동화 + +`failproofai update`는 비대화형으로 동작하며, 수행할 내용이 없어도 안전하게 실행할 수 있습니다 — +"마이그레이션이 필요하지 않았습니다"를 보고하고 0으로 종료합니다. 프로비저닝 스크립트나 Dockerfile에서 +매 업그레이드 후에 실행하는 것이 의도된 사용 방식입니다. + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(이미지 빌드 시에는 `--no-daemon`을 사용합니다. 아직 재시작할 서비스가 없기 때문입니다.) \ No newline at end of file diff --git a/docs/ko/configuration.mdx b/docs/ko/configuration.mdx index 79cef960..a290220a 100644 --- a/docs/ko/configuration.mdx +++ b/docs/ko/configuration.mdx @@ -1,28 +1,28 @@ --- title: 설정 -description: "설정 파일 형식, 세 가지 스코프 시스템, 그리고 병합 규칙" +description: "설정 파일 형식, 세 가지 스코프 시스템 및 병합 규칙" icon: gear --- -failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화될지, 정책이 어떻게 동작할지, 커스텀 정책을 어디서 불러올지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되어 있습니다 — 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다. +failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화되어 있는지, 정책이 어떻게 동작하는지, 커스텀 정책이 어디서 로드되는지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되어 있습니다 - 레포지토리에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다. --- ## 설정 스코프 -설정 스코프는 세 가지이며, 우선순위 순서대로 평가됩니다: +세 가지 설정 스코프가 있으며, 우선순위 순서대로 평가됩니다: -| 스코프 | 파일 경로 | 목적 | +| 스코프 | 파일 경로 | 용도 | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | 저장소별 설정, 버전 관리에 커밋 | -| **local** | `.failproofai/policies-config.local.json` | 개인 저장소별 재정의, gitignore 처리 | -| **global** | `~/.failproofai/policies-config.json` | 모든 프로젝트에 걸친 사용자 수준 기본값 | +| **project** | `.failproofai/policies-config.json` | 버전 관리에 커밋되는 레포지토리별 설정 | +| **local** | `.failproofai/policies-config.local.json` | gitignore된 개인 레포지토리별 재정의 | +| **global** | `~/.failproofai/policies-config.json` | 모든 프로젝트에 적용되는 사용자 수준 기본값 | -failproofai가 훅 이벤트를 수신하면, 현재 작업 디렉터리에 존재하는 세 파일을 모두 불러와 병합합니다. +failproofai가 훅 이벤트를 수신하면 현재 작업 디렉토리에 존재하는 세 파일을 모두 로드하여 병합합니다. ### 병합 규칙 -**`enabledPolicies`** — 세 스코프의 합집합입니다. 어느 한 레벨에서라도 활성화된 정책은 모두 적용됩니다. +**`enabledPolicies`** - 세 스코프의 합집합. 어느 레벨에서든 활성화된 정책은 적용됩니다. ```text project: ["block-sudo"] @@ -32,13 +32,13 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← 중복 제거된 합집합 ``` -**`policyParams`** — 특정 정책에 대한 파라미터를 먼저 정의한 스코프가 전적으로 우선합니다. 정책의 파라미터 내부 값은 깊은 병합(deep merge)이 이루어지지 않습니다. +**`policyParams`** - 특정 정책에 대한 파라미터를 먼저 정의한 스코프가 완전히 우선합니다. 정책 파라미터 내의 값은 깊은 병합이 이루어지지 않습니다. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project가 우선, global은 무시됨 +resolved: { allowPatterns: ["sudo apt-get update"] } ← project 우선, global 무시 ``` ```text @@ -46,14 +46,14 @@ project: (block-sudo 항목 없음) local: (block-sudo 항목 없음) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← global까지 내려감 +resolved: { allowPatterns: ["sudo systemctl status"] } ← global로 폴스루 ``` -**`customPoliciesPaths` / `customPoliciesPath`** — 두 형태 중 어느 하나를 먼저 정의한 스코프가 우선합니다. +**`customPoliciesPaths` / `customPoliciesPath`** - 두 형식 중 하나를 먼저 정의한 스코프가 우선합니다. -**`disabledCustomPolicies`** — 모든 스코프의 합집합입니다. 명시적 또는 컨벤션 정책 파일에서 개별 정책을 비활성화하면 대시보드가 소스가 포함된 ID를 여기에 기록합니다. 목록에 없는 정책은 기본적으로 활성화 상태를 유지합니다. ID에는 소스 파일이 포함되어 있어, 여러 파일에 동일한 이름의 정책이 있더라도 독립적으로 제어할 수 있습니다. +**`disabledCustomPolicies`** - 모든 스코프에서 합집합. 대시보드에서 명시적 또는 컨벤션 정책 파일의 개별 정책을 끄면 소스 한정 ID가 여기에 기록됩니다. 목록에 없는 정책은 기본적으로 활성화 상태로 유지됩니다. ID에는 소스 파일이 포함되므로 여러 파일에서 동일한 이름의 정책을 독립적으로 제어할 수 있습니다. -**`llm`** — 먼저 정의한 스코프가 우선합니다. +**`llm`** - 먼저 정의한 스코프가 우선합니다. --- @@ -104,27 +104,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global까지 내려 타입: `string[]` -활성화할 정책 이름 목록입니다. 이름은 `failproofai policies`에 표시되는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 [기본 제공 정책](/ko/built-in-policies)을 참조하세요. +활성화할 정책 이름 목록. 이름은 `failproofai policies`에 표시되는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 [기본 제공 정책](/ko/built-in-policies)을 참조하세요. -`enabledPolicies`에 없는 정책은 `policyParams`에 항목이 있더라도 비활성 상태입니다. +`enabledPolicies`에 없는 정책은 `policyParams`에 항목이 있더라도 비활성화됩니다. ### `policyParams` 타입: `Record>` -정책별 파라미터 재정의입니다. 외부 키는 정책 이름이고, 내부 키는 각 정책에 고유합니다. 각 정책의 사용 가능한 파라미터는 [기본 제공 정책](/ko/built-in-policies)에서 확인할 수 있습니다. +정책별 파라미터 재정의. 외부 키는 정책 이름이고, 내부 키는 정책별로 다릅니다. 각 정책의 사용 가능한 파라미터는 [기본 제공 정책](/ko/built-in-policies)에 문서화되어 있습니다. -파라미터가 있는 정책이라도 직접 지정하지 않으면 해당 정책의 기본값이 사용됩니다. `policyParams`를 전혀 설정하지 않은 사용자는 이전 버전과 동일하게 동작합니다. +정책에 파라미터가 있지만 지정하지 않으면 정책의 기본값이 사용됩니다. `policyParams`를 전혀 설정하지 않은 사용자는 이전 버전과 동일하게 동작합니다. -정책 파라미터 블록의 알 수 없는 키는 훅 실행 시에는 자동으로 무시되지만, `failproofai policies`를 실행할 때는 경고로 표시됩니다. +정책의 파라미터 블록 내 알 수 없는 키는 훅 실행 시 조용히 무시되지만, `failproofai policies`를 실행하면 경고로 표시됩니다. -#### `hint` (공통 옵션) +#### `hint` (공통) -타입: `string` (선택 사항) +타입: `string` (선택) -정책이 `deny` 또는 `instruct`를 반환할 때 사유에 추가되는 메시지입니다. 정책 자체를 수정하지 않고도 Claude에게 실행 가능한 안내를 제공할 수 있습니다. +정책이 `deny` 또는 `instruct`를 반환할 때 이유에 추가되는 메시지. 정책 자체를 수정하지 않고 Claude에게 실행 가능한 지침을 제공하는 데 사용하세요. -기본 제공 정책, 커스텀 정책(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 등 모든 정책 유형에서 동작합니다. +기본 제공, 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 등 모든 정책 타입에 적용됩니다. ```json { @@ -143,47 +143,52 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global까지 내려 } ``` -`block-force-push`가 거부하면 Claude는 다음 메시지를 받습니다: *"Force-pushing is blocked. Try creating a fresh branch instead."* +`block-force-push`가 거부하면 Claude는 다음을 보게 됩니다: *"Force-pushing is blocked. Try creating a fresh branch instead."* -문자열이 아닌 값과 빈 문자열은 자동으로 무시됩니다. `hint`를 설정하지 않으면 동작은 변경되지 않습니다(하위 호환). +문자열이 아닌 값과 빈 문자열은 조용히 무시됩니다. `hint`가 설정되지 않으면 동작이 변경되지 않습니다(하위 호환성 유지). ### `customPoliciesPath` 타입: `string` (절대 경로) -커스텀 훅 정책이 담긴 JavaScript 파일의 경로입니다. `failproofai policies --install --custom ` 명령으로 자동 설정되며, 경로는 저장 전 절대 경로로 변환됩니다. +커스텀 훅 정책이 포함된 JavaScript 파일 경로. `failproofai policies --install --custom `에 의해 자동으로 설정됩니다(경로는 저장 전에 절대 경로로 변환됩니다). -이 파일은 훅 이벤트마다 새로 불러옵니다 — 캐싱이 없습니다. 작성 방법은 [커스텀 정책](/ko/custom-policies)을 참조하세요. +파일은 모든 훅 이벤트마다 새로 로드되며 캐싱이 없습니다. 작성 방법은 [커스텀 정책](/ko/custom-policies)을 참조하세요. ### 컨벤션 기반 정책 -명시적인 `customPoliciesPath` 외에도, failproofai는 `.failproofai/policies/` 디렉터리에서 정책 파일을 자동으로 탐색하고 불러옵니다: +명시적인 `customPoliciesPath` 외에도, failproofai는 `.failproofai/policies/` 디렉토리에서 자동으로 정책 파일을 탐색하고 로드합니다: -| 레벨 | 디렉터리 | 스코프 | +| 레벨 | 디렉토리 | 스코프 | |-------|-----------|-------| -| 프로젝트 | `.failproofai/policies/` | 버전 관리로 팀과 공유 | -| 사용자 | `~/.failproofai/policies/custom-policies/` | 개인용, 모든 프로젝트에 적용 | +| 프로젝트 | `.failproofai/policies/` | 버전 관리를 통해 팀과 공유 | +| 사용자 | `~/.failproofai/policies/` | 개인용, 모든 프로젝트에 적용 | - 사용자 수준 디렉터리가 홈 디렉터리 재구성으로 한 단계 아래로 이동했습니다. - 이전 경로인 `~/.failproofai/policies/`에 남아 있는 파일은 업그레이드 후 - 처음 `failproofai` 명령을 실행할 때 `custom-policies/`로 자동으로 이동되며, - 어떤 파일이 이동됐는지 안내 메시지가 표시됩니다. + 정책 파일은 `~/.failproofai/policies/`에 바로 넣으면 됩니다. 그 옆의 + `cloud-policies/` 폴더는 조직이 이 머신에 배포한 정책을 보관하며, + 탐색은 하위 디렉토리로 내려가지 않으므로 스캔되지 않고 `policies/`에 + 넣은 파일과 충돌하지 않습니다. + + `~/.failproofai/policies/custom-policies/`를 사용하던 이전 버전에서 + 업그레이드하는 경우, 해당 폴더의 모든 파일 — 정책 파일, 임포트하는 + `lib/` 헬퍼, 읽는 데이터 파일 — 은 `failproofai` 명령을 처음 실행할 때 + 자동으로 상위로 이동되며, 무엇이 이동되었는지 알려줍니다. -**파일 매칭:** `*policies.{js,mjs,ts}` 패턴과 일치하는 파일만 불러옵니다(예: `security-policies.mjs`, `workflow-policies.js`). 디렉터리의 다른 파일은 무시됩니다. +**파일 매칭:** `*policies.{js,mjs,ts}` 패턴과 일치하는 파일만 로드됩니다(예: `security-policies.mjs`, `workflow-policies.js`). 디렉토리의 다른 파일은 무시됩니다. -**설정 불필요:** 컨벤션 정책은 `policies-config.json`에 항목을 추가할 필요가 없습니다. 디렉터리에 파일을 넣기만 하면 다음 훅 이벤트 시 자동으로 인식됩니다. +**설정 불필요:** 컨벤션 정책은 `policies-config.json`에 항목이 필요 없습니다. 파일을 디렉토리에 넣기만 하면 다음 훅 이벤트에서 자동으로 적용됩니다. -**합집합 로딩:** 프로젝트와 사용자 컨벤션 디렉터리가 모두 스캔됩니다. 두 레벨의 일치하는 파일이 모두 불러와집니다(`customPoliciesPath`는 첫 번째 스코프 우선이지만, 컨벤션 정책은 그렇지 않습니다). +**통합 로드:** 프로젝트와 사용자 컨벤션 디렉토리 모두 스캔됩니다. 두 레벨의 일치하는 파일이 모두 로드됩니다(`customPoliciesPath`와 달리 첫 번째 스코프 우선 방식을 사용하지 않음). 자세한 내용과 예시는 [커스텀 정책](/ko/custom-policies)을 참조하세요. ### `llm` -타입: `object` (선택 사항) +타입: `object` (선택) -AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. 대부분의 설정에서는 필요하지 않습니다. +AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정. 대부분의 경우에는 필요하지 않습니다. ```json { @@ -198,24 +203,24 @@ AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. ## CLI에서 설정 관리 -`policies --install`과 `policies --uninstall` 명령은 에이전트 CLI의 훅 설정 파일(훅 진입점)에 쓰는 반면, `policies-config.json`은 직접 관리하는 파일입니다. 두 가지는 별개입니다: - -- **에이전트 CLI 설정** — 에이전트가 각 도구 사용 시 `failproofai --hook `를 호출하도록 지시합니다: - - **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) - - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex에는 `local` 스코프가 없음 - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot에는 `local` 스코프가 없습니다. 훅 항목은 `timeoutSec`와 함께 Copilot의 OS별 `bash`/`powershell` 커맨드 필드를 사용하며, 파일에는 최상위 `version: 1` 마커가 있습니다. Copilot CLI 지원은 **beta** 단계로, 공개 문서에 명시되지 않은 `events.jsonl` 레코드 스키마를 더 많은 실제 세션을 통해 검증 중입니다. **VS Code Copilot Chat 에이전트 모드 (Preview)**는 `chat.hookFilesLocations` 설정에 따라 `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, `~/.claude/settings.json`에서 훅 설정을 읽으며, Claude 형식의 `{hookSpecificOutput:{permissionDecision:"deny",…}}` 계약을 사용합니다 — 이는 `copilot` 통합과 `claude` 통합(`~/.claude/settings.json`)이 이미 쓰는 경로이므로, `failproofai policies --install --cli copilot` (또는 `--cli claude`)으로 별도의 `vscode` 통합 없이 **VS Code 에이전트 모드에서 이미 적용됩니다**(VS Code 검색 로그에서 확인됨). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor에는 `local` 스코프가 없습니다. 훅 항목은 Claude 형식의 `{type, command, timeout}` 구조를 사용하지만(`bash`/`powershell` 분리 없음), Cursor의 [훅 스키마](https://cursor.com/docs/hooks)에 따라 camelCase 이벤트 키(`preToolUse`, `beforeSubmitPrompt`, …) 아래 평면 배열로 저장됩니다. 파일에는 최상위 `version: 1` 마커가 있습니다. 핸들러는 `CURSOR_EVENT_MAP`을 통해 camelCase를 PascalCase로 정규화하므로 기존 기본 제공 정책이 변경 없이 실행됩니다. Cursor Agent 지원은 **beta** 단계로, 공개 문서에 명시되지 않은 Cursor의 트랜스크립트 온디스크 형식을 더 많은 실제 설치를 통해 검증 중입니다. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode에는 `local` 스코프가 없습니다. 다른 다섯 CLI와 달리 OpenCode에는 **외부 명령 훅 시스템이 없습니다**: `opencode.json`의 `plugin: []` 배열을 통해 명시적으로 등록된 인프로세스 JS/TS 플러그인을 불러옵니다(`.opencode/plugins/`에서의 자동 검색은 opencode v1.14.33에서 플러그인 로드 방식이 **아닙니다**). 설치 시 failproofai 바이너리를 서브프로세스로 호출하고 바이너리의 Claude 형식 JSON 응답을 플러그인 시맨틱으로 변환하는 소형 생성 플러그인 심(shim)이 배포됩니다: 도구 이벤트 거부에는 `throw new Error()`(도구 호출 취소), instruct와 `Stop` / `SubagentStop` 거부에는 `client.session.prompt(...)`(거부 사유를 다음 사용자 메시지로 제출 — `session.idle`은 알림 전용이고 여기서 throw는 no-op이라 유일한 강제 재시도 채널), allow에는 no-op입니다. 심은 도구 이름(`OPENCODE_TOOL_MAP`을 통해 소문자 → PascalCase)과 도구 입력 인수 키(`OPENCODE_TOOL_INPUT_MAP`을 통해 `Read` / `Write` / `Edit`에 대해 camelCase → snake_case, 예: `filePath` → `file_path`, `oldString` → `old_string`)를 정규화한 후 바이너리에 전달하므로, `block-read-outside-cwd`, `block-env-files`, `block-secrets-write` 같은 경로 검사 기본 정책이 OpenCode 도구 호출에서 변경 없이 실행됩니다. 세션은 `~/.local/share/opencode/opencode.db`의 OpenCode SQLite DB에 저장되며, 대시보드의 세션 뷰어는 `opencode db --format json`과 `opencode export `를 통해 이를 읽습니다. OpenCode 지원은 **beta** 단계로, 버전별 동작 및 더 많은 실제 세션을 통해 검증 중입니다. [OpenCode 플러그인 문서](https://opencode.ai/docs/plugins/)를 참조하세요. - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi에는 `local` 스코프가 없습니다. Pi는 시작 시 TypeScript 확장 패키지를 로드하며, 설정 파일은 `{"packages": ["./relative/path", …]}` 형태의 평면 문자열 배열입니다. failproofai는 번들된 `pi-extension/` 디렉터리를 가리키는 단일 packages-array 항목을 씁니다. 확장은 내부적으로 Pi의 `tool_call` / `user_bash` / `input` / `session_start` 이벤트를 구독하고 `failproofai --hook --cli pi`를 셸아웃합니다. 핸들러는 `PI_EVENT_MAP`을 통해 underscore_lower_snake_case를 PascalCase로 정규화하므로 기존 기본 제공 정책이 변경 없이 실행됩니다. 도구 입력 인수도 `PI_TOOL_INPUT_MAP`을 통해 정규화됩니다(Pi의 Read / Write / Edit는 `file_path` 대신 `path`를 사용하며, 최상위 키를 매핑하면 `block-env-files`와 `block-secrets-write`가 실행됩니다 — `block-read-outside-cwd`는 이미 `path` 폴백이 있었습니다). Pi 지원은 **beta** 단계로, Pi의 확장 API와 세션 로그 레이아웃이 안정화되는 동안 검증 중입니다. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**user 스코프만** — Hermes에는 project/local 설정이 없음). Hermes는 Slack/Telegram **게이트웨이**이므로, 설치 한 번으로 모든 플랫폼(Slack/Telegram/cli/cron)의 도구 호출과 내부 서브에이전트를 가로챕니다. 훅 항목은 Hermes의 snake_case 이벤트(`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`)를 키로 하는 `hooks:` 맵 아래의 `{command, timeout}` 쌍이며, timeout은 **초** 단위입니다. 핸들러는 `HERMES_EVENT_MAP`을 통해 이벤트를, `HERMES_TOOL_MAP`을 통해 도구 이름을 정규화하므로 기본 제공 정책이 변경 없이 실행됩니다. 설정은 주석을 보존하는 YAML `Document` 라운드트립으로 편집되므로 운영자의 다른 설정이 유지되며, 설치 시 `hooks_auto_accept: true`를 설정하여 헤드리스 게이트웨이(TTY 없음)가 동의 프롬프트 없이 훅을 실행합니다. 평가자는 Hermes의 `{"decision":"block","reason"}` stdout 계약을 출력합니다(Hermes는 종료 코드를 무시합니다). **제한 사항:** Hermes에는 턴 종료 `Stop` 이벤트가 없으므로 `require-*-before-stop` 기본 정책이 실행되지 않습니다(적용 불가이지, 버그가 아님). `instruct`는 allow-with-logged-note로 성능이 저하됩니다(추가 컨텍스트 채널 없음). 출력 시크릿 편집(`sanitize-*`)은 셸 훅 계약을 통해 도구 출력을 재작성할 수 없습니다. Hermes는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.hermes/state.db`에서 게이트웨이 세션을 직접 읽습니다. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**user 스코프만** — OpenClaw에는 project/local 설정이 없음). Hermes처럼 OpenClaw도 자체 호스팅 멀티채널 **게이트웨이**이므로, 설치 한 번으로 모든 채널과 내부 서브에이전트의 도구 호출을 가로챕니다. 적용은 OpenClaw의 **인프로세스 플러그인 훅**을 통해 실행됩니다(파일 기반 내부 훅은 관찰 전용으로 차단 불가). 따라서 OpenCode/Pi와 마찬가지로 failproofai는 failproofai 바이너리를 비동기로 스폰하고 판정 결과를 변환하는 정적 `openclaw-plugin/` 패키지를 제공합니다. 설치 시 `openclaw.json`의 `plugins.load.paths[]`에 제공된 플러그인 디렉터리를 등록하고 `plugins.entries.failproofai` 아래에서 활성화합니다(`hooks.allowConversationAccess: true` 포함, 원시 대화 훅에 필요). 평가자는 평면 `{permission, reason}` 판정을 출력하고 심이 이를 각 훅의 네이티브 반환 형태로 매핑합니다: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), `before_agent_finalize → {action:"revise", reason}` (**Stop** — 실제 턴 종료 게이트이므로 `require-*-before-stop` 기본 정책이 Hermes와 달리 OpenClaw에서 **적용됩니다**). 이벤트와 도구 이름은 `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`(`exec→Bash`, `read→Read`, …)을 통해 바이너리 측에서 정규화되므로 기본 제공 정책이 변경 없이 실행됩니다. 심은 스폰/파싱/타임아웃 오류 시 열린 상태로 실패합니다. OpenClaw는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.openclaw/agents//sessions/.jsonl`의 JSONL 세션을 읽습니다. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (user), `/.factory/hooks.json` (project) — Factory에는 `local` 스코프가 없습니다. droid는 Claude 형식의 외부 명령 훅 시스템을 제공하지만, droid v0.171.0에서 실제로 검증된 두 가지 특이점이 있습니다: (1) 이벤트 이름은 `hooks.json`의 **최상위 레벨**에 위치합니다 — **`"hooks"` 래퍼가 없습니다**(droid가 거부함). 도구 이벤트(`PreToolUse`/`PostToolUse`)는 `"matcher": "*"`를 포함하고, 비도구 이벤트는 생략합니다. (2) 거부는 JSON 결정이 아니라 훅 **종료 코드 2 + stderr**로 처리됩니다 — 평가자의 `factory` 브랜치는 도구/프롬프트 이벤트에 대해 종료 코드 2를 반환하고, 턴 종료 `Stop` 이벤트(droid의 유일한 강제 재시도 채널)에서만 `{decision:"block", reason}`을 반환합니다. 이벤트는 이미 PascalCase이며(이벤트 맵 불필요), 페이로드는 Claude snake_case입니다. 도구 이름만 `FACTORY_TOOL_MAP`(`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …)을 통해 정규화됩니다. Factory는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.factory/sessions//.jsonl`의 온디스크 JSONL 세션을 읽습니다. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (user), `/.devin/config.json` (project) — Devin에는 `local` 스코프가 없습니다. Devin은 devin v3000.1.27에서 실제로 검증된 **순수 Claude 클론**입니다: 표준 Claude `"hooks"` 래퍼 스키마를 사용하고(쓰기는 병합 보존 방식이라 설정 파일의 다른 키 — `org_id`, `theme_mode`, … — 가 유지됨), 이미 PascalCase 이벤트 이름(이벤트 맵 없음, 핸들러 브랜치 없음), Claude snake_case stdin 페이로드(정규화 불필요)를 사용합니다. 평가자의 `devin` 브랜치는 **모든** 이벤트에 대해 종료 코드 0에서 `{"decision":"block","reason"}` JSON을 stdout으로 출력하여 거부합니다(검증됨 — 블록이 `--permission-mode dangerous`를 재정의함). 턴 종료 `Stop` 이벤트에서는 `require-*-before-stop` 기본 정책이 적용되도록 사유에 MANDATORY-ACTION 강제 재시도 문구가 포함됩니다. 도구 이름만 `DEVIN_TOOL_MAP`(`exec→Bash`; `tool_input.command`는 이미 정규화됨)을 통해 정규화됩니다. Devin은 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.local/share/devin/cli/sessions.db`의 SQLite 세션을 읽습니다(각 `sessions` 행에 실제 `working_directory`가 있어, Claude처럼 프로젝트 cwd별로 세션이 그룹화됨). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (user), `/.agents/hooks.json` (project) — Antigravity에는 `local` 스코프가 없습니다. Factory/Devin과 달리 Antigravity는 agy v1.1.2에서 실제로 검증된 **자체 계약**(Claude 클론이 아님)을 사용합니다. `hooks.json`은 **이름 있는 훅** 스키마를 사용합니다: 최상위 키는 훅 *이름*(`"failproofai"`)이며, 그 값은 이벤트 → 핸들러 맵입니다 — 도구 이벤트(`PreToolUse`/`PostToolUse`)는 핸들러를 `{matcher:"*", hooks:[…]}`로 감싸고, `PreInvocation`/`Stop`은 **평면** 핸들러 배열입니다(다른 이름 있는 훅은 보존됩니다). stdin 페이로드는 **camelCase protojson** 형식(`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`)으로, failproofai는 정책 실행 전 이를 snake_case로 정규화하고 `run_command`의 PascalCase 인수(`CommandLine`/`Cwd`)를 `ANTIGRAVITY_TOOL_INPUT_MAP`으로 매핑합니다. 평가자의 `antigravity` 브랜치는 Antigravity의 **자체** 응답 형태를 사용합니다: `{decision:"deny", reason}`은 도구/프롬프트를 차단하고(종료 0), 턴 종료 `Stop`에서 `{decision:"continue", reason}`은 루프를 재진입하므로(`require-*-before-stop` 기본 정책이 적용됨), `{injectSteps:[{ephemeralMessage}]}`는 `PreInvocation`(→ `UserPromptSubmit`)에서 지시를 주입합니다. 도구 이름은 `ANTIGRAVITY_TOOL_MAP`(`run_command→Bash`, `view_file→Read`, …)을 통해 정규화됩니다. Antigravity는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl`의 일반 JSONL 트랜스크립트를 읽습니다(대화 인덱스는 `conversation_summaries.db`에 있음). - - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (user), `/.agents/plugins/failproofai/hooks/hooks.json` (project) — Goose에는 `local` 스코프가 없습니다. 적용은 Goose의 **훅** 시스템인 크로스에이전트 **Open Plugins** 스펙을 통해 이루어집니다: 설치 시 `failproofai` 플러그인 디렉터리만 배포하면 Goose가 시작 시 자동으로 검색합니다(이를 `~/.config/goose/config.yaml`에 자동 등록). `hooks.json`은 최상위 `"hooks"` 래퍼가 **있는** Open Plugins 스키마를 사용하며, **모든** 이벤트에서 matcher가 **생략됩니다** — 단순 `"*"`는 아무것도 일치하지 않는 잘못된 정규식입니다(goose v1.43.0에서 실제로 검증됨). 이벤트 이름은 이미 PascalCase이며(이벤트 맵 불필요), stdin 페이로드는 `event`/`working_dir`를 사용하고 핸들러가 이를 `hook_event_name`/`cwd`로 정규화합니다. 평가자의 `goose` 브랜치는 종료 코드 0에서 `{"decision":"block","reason"}` JSON을 stdout으로 출력하며, **`PreToolUse`** 이벤트에서만 적용됩니다(goose ≥ v1.37.0에 제공됨) — 이는 셸 도구와 **위임된 서브에이전트 내부** 모두에서 실행되므로 유일하게 충분한 거부 지점입니다. 다른 훅 오류는 **열린 상태로** 실패합니다. Goose에는 **`Stop` 이벤트가 없으므로** `require-*-before-stop` 기본 정책이 적용되지 않습니다(Hermes와 동일). 도구 이름은 `GOOSE_TOOL_MAP`(`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …)을 통해, 경로 키는 `GOOSE_TOOL_INPUT_MAP`(`path`/`source` → `file_path`)을 통해 정규화됩니다. Goose는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.local/share/goose/sessions/sessions.db`의 SQLite 세션을 읽습니다(각 `sessions` 행에 실제 `working_dir`가 있어 Devin처럼 프로젝트 cwd별로 세션이 그룹화됨. `--no-session` 임시 실행은 필터링됨). -- **`policies-config.json`** — failproofai가 어떤 정책을 어떤 파라미터로 평가할지 지시합니다(모든 에이전트 CLI에서 공유) - -특정 에이전트를 지정하려면 `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`를 전달하세요(공백으로 구분하거나 반복 사용하여 부분 집합 지정 가능): +`policies --install` 및 `policies --uninstall` 명령은 에이전트 CLI의 훅 설정 파일(훅 엔트리 포인트)에 기록하는 반면, `policies-config.json`은 직접 관리하는 파일입니다. 두 가지는 별개입니다: + +- **에이전트 CLI 설정** — 각 도구 사용 시 에이전트가 `failproofai --hook `를 호출하도록 지시합니다: + - **Claude Code**: `~/.claude/settings.json` (사용자), `/.claude/settings.json` (프로젝트), `/.claude/settings.local.json` (로컬) + - **OpenAI Codex**: `~/.codex/hooks.json` (사용자), `/.codex/hooks.json` (프로젝트) — Codex에는 `local` 스코프가 없음 + - **GitHub Copilot CLI _(베타)_**: `~/.copilot/hooks/failproofai.json` (사용자), `/.github/hooks/failproofai.json` (프로젝트) — Copilot에는 `local` 스코프가 없음. 훅 항목은 `timeoutSec`과 함께 Copilot의 OS별 `bash`/`powershell` 명령 필드를 사용하며, 파일 최상위에 `version: 1` 마커가 있음. `events.jsonl` 레코드 스키마(공개 문서에 명시되지 않음)를 더 많은 실제 세션으로 검증하는 동안 Copilot CLI 지원은 **베타**입니다. **VS Code Copilot Chat 에이전트 모드(Preview)**는 `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, `~/.claude/settings.json`에서 훅 설정을 읽으며(`chat.hookFilesLocations` 설정으로 관리), Claude와 동일한 `{hookSpecificOutput:{permissionDecision:"deny",…}}` 계약을 사용합니다 — 이는 `copilot` 통합과 `claude` 통합(`~/.claude/settings.json`)이 이미 기록하는 경로이므로 `failproofai policies --install --cli copilot`(또는 `--cli claude`)는 **별도의 `vscode` 통합 없이 이미 VS Code 에이전트 모드에서 적용됩니다**(VS Code 탐색 로그로 확인). + - **Cursor Agent _(베타)_**: `~/.cursor/hooks.json` (사용자), `/.cursor/hooks.json` (프로젝트) — Cursor에는 `local` 스코프가 없음. 훅 항목은 Claude 형태의 `{type, command, timeout}`을 사용하지만(`bash`/`powershell` 분리 없음), Cursor의 [훅 스키마](https://cursor.com/docs/hooks)에 따라 camelCase 이벤트 키(`preToolUse`, `beforeSubmitPrompt`, …) 아래 평면 배열에 저장되며 파일 최상위에 `version: 1` 마커가 있음. 핸들러는 `CURSOR_EVENT_MAP`을 통해 camelCase → PascalCase로 정규화하므로 기존 기본 제공 정책이 변경 없이 실행됩니다. Cursor의 전사 온디스크 형식(공개 문서에 명시되지 않음)을 더 많은 실제 설치로 검증하는 동안 Cursor Agent 지원은 **베타**입니다. + - **OpenCode _(베타)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (사용자), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (프로젝트) — OpenCode에는 `local` 스코프가 없음. 다른 다섯 CLI와 달리 OpenCode에는 **외부 명령 훅 시스템이 없습니다**: `opencode.json`의 `plugin: []` 배열을 통해 명시적으로 등록된 인프로세스 JS/TS 플러그인을 로드합니다(`.opencode/plugins/`에서의 자동 탐색은 opencode v1.14.33에서 플러그인이 로드되는 방식이 **아닙니다**). 설치 시 failproofai 바이너리를 서브프로세스로 호출하고 바이너리의 Claude 형태 JSON 응답을 플러그인 시맨틱으로 변환하는 소형 생성 플러그인 심이 생성됩니다: 도구 이벤트 거부에는 `throw new Error()` (도구 호출 취소), instruct와 `Stop` / `SubagentStop` 거부에는 `client.session.prompt(...)` (거부 이유를 다음 사용자 메시지로 제출 — `session.idle`이 알림 전용이고 여기서 throw해도 no-op이므로 유일한 강제 재시도 채널), allow에는 no-op. 심은 도구 이름(소문자 → `OPENCODE_TOOL_MAP`을 통해 PascalCase)과 도구 입력 인수 키(`OPENCODE_TOOL_INPUT_MAP`을 통해 camelCase → snake_case, `Read` / `Write` / `Edit`에 대해 예: `filePath` → `file_path`, `oldString` → `old_string`)를 모두 정규화한 후 바이너리로 전달하므로 `block-read-outside-cwd`, `block-env-files`, `block-secrets-write` 같은 경로 확인 기본 정책이 OpenCode 도구 호출에서 변경 없이 실행됩니다. 세션은 `~/.local/share/opencode/opencode.db`의 opencode SQLite DB에 저장되며, 대시보드의 세션 뷰어는 `opencode db --format json`과 `opencode export `로 이를 읽습니다. 버전 간 동작 및 더 많은 실제 세션 검증 동안 OpenCode 지원은 **베타**입니다. [OpenCode 플러그인 문서](https://opencode.ai/docs/plugins/)를 참조하세요. + - **Pi _(베타)_**: `~/.pi/agent/settings.json` (사용자), `/.pi/settings.json` (프로젝트) — Pi에는 `local` 스코프가 없음. Pi는 시작 시 TypeScript 확장 패키지를 로드하며, 설정 파일은 평면 문자열 배열 `{"packages": ["./relative/path", …]}`입니다. failproofai는 번들된 `pi-extension/` 디렉토리를 가리키는 단일 패키지 배열 항목을 기록합니다. 확장은 내부적으로 Pi의 `tool_call` / `user_bash` / `input` / `session_start` 이벤트를 구독하고 `failproofai --hook --cli pi`를 실행합니다. 핸들러는 `PI_EVENT_MAP`을 통해 underscore_lower_snake_case → PascalCase로 정규화하므로 기존 기본 제공 정책이 변경 없이 실행됩니다. 도구 입력 인수도 `PI_TOOL_INPUT_MAP`을 통해 정규화됩니다(Pi의 Read / Write / Edit는 `file_path` 대신 `path`를 전달하며, 최상위 키를 매핑하면 `block-env-files`와 `block-secrets-write`가 실행됨 — `block-read-outside-cwd`는 이미 `path` 폴백이 있었음). Pi의 확장 API와 세션 로그 레이아웃이 안정화되는 동안 Pi 지원은 **베타**입니다. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**사용자 스코프만** — Hermes에는 프로젝트/로컬 설정이 없음). Hermes는 Slack/Telegram **게이트웨이**이므로 하나의 설치로 모든 플랫폼(Slack/Telegram/cli/cron)**과** 내부 서브에이전트의 도구 호출을 차단합니다. 훅 항목은 Hermes의 snake_case 이벤트(`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) 키의 `hooks:` 맵 아래 `{command, timeout}` 쌍(타임아웃 단위: **초**)입니다. 핸들러는 `HERMES_EVENT_MAP`으로 이벤트를, `HERMES_TOOL_MAP`으로 도구 이름을 정규화하므로 기본 제공 정책이 변경 없이 실행됩니다. 설정은 주석을 보존하는 YAML `Document` 라운드트립으로 편집되므로 운영자의 다른 설정이 유지되며, 설치 시 `hooks_auto_accept: true`로 설정되어 헤드리스 게이트웨이(TTY 없음)가 동의 프롬프트 없이 훅을 실행합니다. 평가기는 Hermes의 `{"decision":"block","reason"}` stdout 계약을 내보냅니다(Hermes는 종료 코드 무시). **제한:** Hermes에는 턴 종료 `Stop` 이벤트가 없으므로 `require-*-before-stop` 기본 정책은 실행되지 않습니다(해당 없음, 오류 아님). `instruct`는 allow-with-logged-note로 격하됩니다(추가 컨텍스트 채널 없음). 출력 시크릿 편집(`sanitize-*`)은 셸 훅 계약으로 도구 출력을 재작성할 수 없습니다. Hermes는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.hermes/state.db`에서 직접 게이트웨이 세션을 읽습니다. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**사용자 스코프만** — OpenClaw에는 프로젝트/로컬 설정이 없음). Hermes와 마찬가지로 OpenClaw는 자체 호스팅 다중 채널 **게이트웨이**이므로 하나의 설치로 모든 채널과 내부 서브에이전트의 도구 호출을 차단합니다. 적용은 OpenClaw의 **인프로세스 플러그인 훅**을 통해 실행됩니다(파일 기반 내부 훅은 관찰 전용이며 차단 불가). 따라서 OpenCode/Pi와 마찬가지로 failproofai는 failproofai 바이너리를 비동기 스폰하고 판정을 변환하는 정적 `openclaw-plugin/` 패키지를 제공합니다. 설치 시 `openclaw.json`의 `plugins.load.paths[]`에 제공된 플러그인 디렉토리를 등록하고 `plugins.entries.failproofai` 아래 활성화합니다(`hooks.allowConversationAccess: true` 포함, 원시 대화 훅에 필요). 평가기는 평면 `{permission, reason}` 판정을 내보내며 심은 이를 각 훅의 네이티브 반환 형태로 매핑합니다: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), `before_agent_finalize → {action:"revise", reason}` (**Stop** — 실제 턴 종료 게이트이므로 Hermes와 달리 OpenClaw에서 `require-*-before-stop` 기본 정책이 **적용됩니다**). 이벤트와 도구 이름은 `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`을 통해 바이너리 측에서 정규화됩니다(`exec→Bash`, `read→Read`, …). 스폰/파싱/타임아웃 오류 시 심은 오픈으로 실패합니다. OpenClaw는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.openclaw/agents//sessions/.jsonl`의 JSONL 세션을 읽습니다. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (사용자), `/.factory/hooks.json` (프로젝트) — Factory에는 `local` 스코프가 없음. droid는 Claude 스타일의 외부 명령 훅 시스템을 제공하지만 droid v0.171.0으로 실제 검증된 두 가지 특이점이 있습니다: (1) 이벤트 이름은 `hooks.json`의 **최상위**에 위치합니다 — **`"hooks"` 래퍼가 없습니다**(droid가 거부). 도구 이벤트(`PreToolUse`/`PostToolUse`)에는 `"matcher": "*"`가 있고, 비도구 이벤트에는 없습니다. (2) 거부는 JSON 판정이 아닌 훅 **종료 코드 2 + stderr**로 구동됩니다 — 평가기의 `factory` 브랜치는 도구/프롬프트 이벤트에서 종료 코드 2를 반환하고, 턴 종료 `Stop` 이벤트(droid의 유일한 강제 재시도 채널)에서만 `{decision:"block", reason}`을 반환합니다. 이벤트는 이미 PascalCase이며(이벤트 맵 없음) 페이로드는 Claude snake_case입니다. 도구 이름만 `FACTORY_TOOL_MAP`을 통해 정규화됩니다(`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.factory/sessions//.jsonl`의 온디스크 JSONL 세션을 읽습니다. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (사용자), `/.devin/config.json` (프로젝트) — Devin에는 `local` 스코프가 없음. Devin은 devin v3000.1.27로 실제 검증된 **순수 Claude 클론**입니다: 표준 Claude `"hooks"` 래퍼 스키마를 사용하며(기록은 병합 보존 방식으로 설정 파일의 다른 키 — `org_id`, `theme_mode`, … — 가 유지됨), 이미 PascalCase 이벤트 이름(이벤트 맵 없음, 핸들러 브랜치 없음)과 Claude snake_case stdin 페이로드(정규화 없음)를 사용합니다. 평가기의 `devin` 브랜치는 종료 코드 0에서 stdout에 `{"decision":"block","reason"}` JSON으로 **모든** 이벤트를 거부합니다(검증됨 — 블록이 `--permission-mode dangerous`를 재정의했음). 턴 종료 `Stop` 이벤트에서는 이유에 MANDATORY-ACTION 강제 재시도 문구가 포함되어 `require-*-before-stop` 기본 정책이 적용됩니다. 도구 이름만 `DEVIN_TOOL_MAP`을 통해 정규화됩니다(`exec→Bash`; `tool_input.command`는 이미 표준). Devin은 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.local/share/devin/cli/sessions.db`의 SQLite 세션을 읽습니다(각 `sessions` 행에는 실제 `working_directory`가 있어 Claude처럼 프로젝트 cwd별로 세션이 그룹화됨). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (사용자), `/.agents/hooks.json` (프로젝트) — Antigravity에는 `local` 스코프가 없음. Factory/Devin과 달리 Antigravity는 agy v1.1.2로 실제 검증된 **자체** 계약을 가지고 있습니다(Claude 클론이 아님). `hooks.json`은 **명명된 훅** 스키마를 사용합니다: 최상위 키는 훅 *이름*(`"failproofai"`)이며 그 값은 이벤트→핸들러 맵입니다 — 도구 이벤트(`PreToolUse`/`PostToolUse`)는 핸들러를 `{matcher:"*", hooks:[…]}`로 래핑하고, `PreInvocation`/`Stop`은 **평면** 핸들러 배열입니다(다른 명명된 훅은 보존됨). stdin 페이로드는 **camelCase protojson**(`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`)입니다 — failproofai는 정책 실행 전에 이를 snake_case로 정규화하고, `ANTIGRAVITY_TOOL_INPUT_MAP`을 통해 `run_command`의 PascalCase 인수(`CommandLine`/`Cwd`)를 매핑합니다. 평가기의 `antigravity` 브랜치는 Antigravity **자체** 응답 형태를 사용합니다: `{decision:"deny", reason}`은 도구/프롬프트를 차단하고(종료 코드 0), 턴 종료 `Stop`에서 `{decision:"continue", reason}`은 루프를 재진입하며(따라서 `require-*-before-stop` 기본 정책이 적용됨), `{injectSteps:[{ephemeralMessage}]}`는 `PreInvocation` (→ `UserPromptSubmit`)에서 지시를 주입합니다. 도구 이름은 `ANTIGRAVITY_TOOL_MAP`을 통해 정규화됩니다(`run_command→Bash`, `view_file→Read`, …). Antigravity는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl`의 일반 JSONL 전사본을 읽습니다(대화 색인은 `conversation_summaries.db`에 있음). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (사용자), `/.agents/plugins/failproofai/hooks/hooks.json` (프로젝트) — Goose에는 `local` 스코프가 없음. 적용은 Goose의 **훅** 시스템, 즉 크로스 에이전트 **Open Plugins** 스펙을 사용합니다: 설치 시 `failproofai` 플러그인 디렉토리를 생성하기만 하면 Goose가 시작 시 자동으로 탐색합니다(`~/.config/goose/config.yaml`에 자동 등록). `hooks.json`은 최상위 `"hooks"` 래퍼가 **있는** Open Plugins 스키마를 사용하며, 매처는 모든 이벤트에서 **생략됩니다** — 단독 `"*"`는 아무것도 매칭하지 않는 유효하지 않은 정규식입니다(goose v1.43.0으로 실제 검증됨). 이벤트 이름은 이미 PascalCase이며(이벤트 맵 없음), stdin 페이로드는 `event`/`working_dir`를 사용하고 핸들러가 이를 `hook_event_name`/`cwd`로 정규화합니다. 평가기의 `goose` 브랜치는 종료 코드 0에서 stdout에 `{"decision":"block","reason"}` JSON으로 거부하며, **`PreToolUse`** 이벤트에서만 적용됩니다(goose ≥ v1.37.0에 탑재) — 셸 도구**와 위임된 서브에이전트 내부** 모두에서 실행되므로 단일 충분한 거부 지점입니다. 다른 훅 오류는 **오픈**으로 실패합니다. Goose에는 **`Stop` 이벤트가 없으므로** `require-*-before-stop` 기본 정책은 적용되지 않습니다(Hermes와 마찬가지). 도구 이름은 `GOOSE_TOOL_MAP`을 통해(`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …), 경로 키는 `GOOSE_TOOL_INPUT_MAP`을 통해(`path`/`source` → `file_path`) 정규화됩니다. Goose는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.local/share/goose/sessions/sessions.db`의 SQLite 세션을 읽습니다(각 `sessions` 행에는 실제 `working_dir`가 있어 Devin처럼 프로젝트 cwd별로 세션이 그룹화됨. `--no-session` 스크래치 실행은 필터링됨). +- **`policies-config.json`** — failproofai에게 어떤 정책을 어떤 파라미터로 평가할지 지시합니다(모든 에이전트 CLI에서 공유됨) + +특정 에이전트를 대상으로 하려면 `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`를 전달하세요(공백으로 구분하거나 반복 가능): ```bash failproofai policies --install --cli codex --scope project @@ -232,20 +237,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -`--cli`를 생략하면 `failproofai`가 설치된 에이전트 CLI를 자동으로 감지합니다(`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +`--cli`를 생략하면 `failproofai`는 설치된 에이전트 CLI를 자동 감지합니다(`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **CLI 하나 감지** — 프롬프트 없이 해당 CLI를 자동으로 선택합니다. -- **여러 CLI 감지** (인터랙티브 터미널) — `Detected (N)` 섹션(`Install for all N detected` 통합 행 + 감지된 각 CLI)과 `Not installed (M) · install hooks ahead of time` 섹션(감지되지 않은 모든 지원 CLI를 사전 설치 옵션으로 표시)으로 구성된 화살표 키 단일 선택 프롬프트를 표시합니다(↑↓로 이동, Enter로 선택, ^C로 종료). 제거 흐름에서는 Detected 섹션만 표시합니다. -- **여러 CLI 감지** (비인터랙티브 실행, TTY 없음 — CI 등) — 프롬프트 없이 감지된 모든 CLI에 설치합니다. -- **감지 없음** — `claude`로 폴백하며, PATH에서 에이전트 바이너리를 찾을 수 없다는 경고를 표시합니다. 훅 명령은 그래도 기록되어, 설치 후 즉시 활성화됩니다. +- **하나의 CLI 감지** — 프롬프트 없이 해당 CLI를 자동으로 선택합니다. +- **대화형 터미널에서 여러 CLI 감지** — `Detected (N)` 섹션(`Install for all N detected` 집계 행 + 감지된 각 CLI 개별)과 `Not installed (M) · install hooks ahead of time` 섹션(감지되지 않은 지원 CLI를 사전 설치 옵션으로 나열)으로 그룹화된 화살표 키 단일 선택 프롬프트를 표시합니다(↑↓ 이동, Enter 선택, ^C 종료). 제거 흐름에는 Detected 섹션만 표시됩니다. +- **비대화형 실행(CI, TTY 없음)에서 여러 CLI 감지** — 프롬프트 없이 감지된 모든 CLI에 설치합니다. +- **아무것도 감지되지 않음** — `claude`로 폴백하며, PATH에서 에이전트 바이너리를 찾을 수 없다는 경고를 표시합니다. 훅 명령은 여전히 기록되므로 설치 즉시 활성화됩니다. -`policies-config.json`은 언제든지 직접 편집할 수 있으며, 재시작 없이 다음 훅 이벤트부터 즉시 변경 사항이 적용됩니다. +`policies-config.json`은 언제든지 직접 편집할 수 있으며, 변경 사항은 재시작 없이 다음 훅 이벤트에서 즉시 적용됩니다. + +## 업그레이드 시 설정 유지 + +새 버전의 failproofai는 `~/.failproofai/`를 다르게 구성할 수 있습니다. 그럴 경우 업그레이드 후 첫 번째 명령이 디렉토리를 마이그레이션하며, **설정은 초기화되지 않고 그대로 이전됩니다**: + +| 유지됨 | 재생성됨 | +|---|---| +| 정책 선택 및 파라미터 (`policies-config.json`) | 감사 캐시 | +| `daemon.configured` 및 추가 캡처 경로를 포함한 설정 (`config.json`) | 클라우드 관리 정책 배포 — 다음 폴링 시 재가져오기 및 다이제스트 검증 | +| 클라우드 등록 (`credentials.json`) | 데몬 스크래치 상태 | +| `policies/`의 자체 정책 파일 및 임포트하는 헬퍼 | | +| 대시보드가 읽는 결정 로그 및 아직 전달되지 않은 이벤트 | | + +*최신* failproofai가 기록한 키도 이전 리더에 의해 삭제되지 않고 보존됩니다 — 따라서 버전 간 이동 시 어느 방향으로든 설정이 자동으로 사라지지 않습니다. + +마이그레이션 후 설정을 다시 실행할 필요가 없습니다: 마이그레이션된 머신은 이전과 정확히 동일하게 적용되며, 이것이 아무도 앉아 있지 않은 머신에서 업그레이드를 안전하게 만드는 이유입니다. 모든 마이그레이션은 `~/.failproofai/migrations/applied.json`에 기록되며, 대체 불가능한 파일은 실행 전에 `~/.failproofai/migrations/backup-layout/`에 복사됩니다. + +원라인 업그레이드는 [`failproofai update`](/ko/cli/update)를, `--dry-run`을 포함한 세부 정보는 [`failproofai migrate`](/ko/cli/migrate)를 참조하세요. --- ## 예시: 팀 기본값이 포함된 프로젝트 수준 설정 -`.failproofai/policies-config.json`을 저장소에 커밋하세요: +`.failproofai/policies-config.json`을 레포지토리에 커밋하세요: ```json { @@ -264,4 +287,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her } ``` -그러면 각 개발자는 팀원에게 영향을 주지 않고 개인 재정의를 위해 `.failproofai/policies-config.local.json`(gitignore 처리됨)을 별도로 만들 수 있습니다. \ No newline at end of file +그런 다음 각 개발자는 팀원에게 영향을 주지 않고 개인 재정의를 위해 `.failproofai/policies-config.local.json`(gitignore됨)을 생성할 수 있습니다. \ No newline at end of file diff --git a/docs/ko/custom-policies.mdx b/docs/ko/custom-policies.mdx index 2ae99733..af6446d1 100644 --- a/docs/ko/custom-policies.mdx +++ b/docs/ko/custom-policies.mdx @@ -1,14 +1,14 @@ --- title: 커스텀 정책 -description: "JavaScript로 직접 정책 작성 - 컨벤션 강제, 드리프트 방지, 실패 감지, 외부 시스템 연동" +description: "JavaScript로 자신만의 정책을 작성하세요 — 컨벤션 강제, 드리프트 방지, 실패 감지, 외부 시스템 통합 등" icon: code --- -커스텀 정책을 사용하면 에이전트 동작에 관한 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 강제, 드리프트 방지, 위험한 작업 차단, 멈춘 에이전트 감지, Slack 연동, 승인 워크플로우 등 다양한 용도로 활용할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다. +커스텀 정책을 사용하면 에이전트 동작에 대한 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 강제, 드리프트 방지, 위험한 작업 차단, 멈춘 에이전트 감지, Slack이나 승인 워크플로우 연동 등 다양한 용도로 활용할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다. --- -## 빠른 예시 +## 빠른 예제 ```js // my-policies.js @@ -39,57 +39,57 @@ failproofai policies --install --custom ./my-policies.js ## 커스텀 정책을 로드하는 두 가지 방법 -### 옵션 1: 컨벤션 기반 (권장) +### 방법 1: 컨벤션 기반 (권장) -`.failproofai/policies/` 디렉터리에 `*policies.{js,mjs,ts}` 파일을 추가하면 자동으로 로드됩니다 — 별도 플래그나 설정 변경이 필요 없습니다. git hooks처럼 파일을 추가하기만 하면 바로 동작합니다. +`.failproofai/policies/` 디렉토리에 `*policies.{js,mjs,ts}` 파일을 넣으면 별도 플래그나 설정 변경 없이 자동으로 로드됩니다. git 훅처럼 파일만 넣으면 바로 동작합니다. ``` -# 프로젝트 레벨 — git에 커밋되어 팀과 공유 +# 프로젝트 수준 — git에 커밋, 팀과 공유 .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# 사용자 레벨 — 개인용, 모든 프로젝트에 적용 +# 사용자 수준 — 개인용, 모든 프로젝트에 적용 ~/.failproofai/policies/my-policies.mjs ``` **동작 방식:** -- 프로젝트 및 사용자 디렉터리 모두 스캔됨 (합집합 방식 — 첫 번째 스코프 우선이 아님) -- 각 디렉터리 내에서 파일은 알파벳 순으로 로드됨. 순서 조정이 필요하면 `01-`, `02-` 등의 접두사 사용 -- `*policies.{js,mjs,ts}` 패턴에 매칭되는 파일만 로드되며, 그 외 파일은 무시됨 -- 각 파일은 독립적으로 로드됨 (파일 단위 fail-open) -- 명시적 `--custom` 및 내장 정책과 함께 동작 +- 프로젝트 디렉토리와 사용자 디렉토리 모두 스캔됩니다 (합집합 — 첫 번째 스코프 우선이 아님) +- 각 디렉토리 내에서 파일은 알파벳 순서로 로드됩니다. 순서를 제어하려면 `01-`, `02-` 접두사를 사용하세요 +- `*policies.{js,mjs,ts}` 패턴에 맞는 파일만 로드되며, 나머지 파일은 무시됩니다 +- 각 파일은 독립적으로 로드됩니다 (파일별 fail-open) +- 명시적인 `--custom` 및 내장 정책과 함께 사용 가능합니다 -컨벤션 정책은 조직의 품질 기준을 세우는 가장 쉬운 방법입니다. `.failproofai/policies/`를 git에 커밋하면 모든 팀원이 별도 설정 없이 동일한 규칙을 자동으로 적용받습니다. 새로운 실패 패턴을 발견할 때마다 정책을 추가하고 푸시하세요. 시간이 지날수록 팀의 기여로 점점 개선되는 살아있는 품질 기준이 됩니다. +컨벤션 정책은 조직의 품질 기준을 수립하는 가장 쉬운 방법입니다. `.failproofai/policies/`를 git에 커밋하면 모든 팀원이 별도 설정 없이 동일한 규칙을 자동으로 적용받습니다. 팀이 새로운 실패 패턴을 발견할 때마다 정책을 추가하고 푸시하세요. 시간이 지날수록 이 정책들은 매 기여마다 발전하는 살아있는 품질 기준이 됩니다. -### 옵션 2: 명시적 파일 경로 +### 방법 2: 명시적 파일 경로 ```bash -# 커스텀 정책 파일로 설치 +# 커스텀 정책 파일과 함께 설치 failproofai policies --install --custom ./my-policies.js # 커스텀 정책 경로 교체 failproofai policies --install --custom ./new-policies.js -# 여러 파일 설정 (플래그 순서대로 로드) +# 여러 명시적 파일 설정 (플래그 순서대로 로드) failproofai policies --install --custom ./security.js --custom ./workflow.js # 설정에서 모든 명시적 커스텀 정책 경로 제거 failproofai policies --uninstall --custom ``` -해석된 절대 경로는 `policies-config.json`에 `customPoliciesPaths`로 저장됩니다. 여러 파일을 설정하려면 `--custom`을 반복해서 사용하세요. 레거시 `customPoliciesPath` 필드를 사용하는 기존 설정도 계속 동작합니다. 파일은 훅 이벤트마다 새로 로드되며 — 이벤트 간 캐싱은 없습니다. +절대 경로로 변환된 경로는 `policies-config.json`의 `customPoliciesPaths`에 저장됩니다. `--custom`을 반복 사용해 여러 파일을 설정할 수 있습니다. 기존의 레거시 `customPoliciesPath` 필드를 사용하는 설정도 계속 동작합니다. 파일은 매 훅 이벤트마다 새로 로드되며, 이벤트 간 캐싱은 없습니다. -등록된 각 정책은 대시보드에서 개별 토글로 표시됩니다. 정책을 비활성화하면 소스 한정 ID가 `disabledCustomPolicies`에 기록되고, 해당 파일과 다른 정책들은 계속 로드되지만 비활성화된 정책은 이벤트 매칭 전에 제외됩니다. 파일이 달라도 같은 이름의 정책은 각각 독립적인 토글을 갖습니다. +등록된 각 정책은 대시보드에서 개별 토글로 표시됩니다. 정책을 비활성화하면 해당 정책의 소스 기반 ID가 `disabledCustomPolicies`에 기록됩니다. 파일과 그 안의 다른 정책들은 계속 로드되지만, 비활성화된 정책은 이벤트 매칭 전에 제외됩니다. 여러 파일에 동일한 이름의 정책이 있을 경우 각각 독립적인 토글이 생성됩니다. ### 두 방법 함께 사용하기 컨벤션 정책과 명시적 `--custom` 파일은 함께 사용할 수 있습니다. 로드 순서: -1. 명시적 `customPoliciesPaths` 파일 (설정된 순서) -2. 프로젝트 컨벤션 파일 (`{cwd}/.failproofai/policies/`, 알파벳 순) -3. 사용자 컨벤션 파일 (`~/.failproofai/policies/`, 알파벳 순) +1. 명시적 `customPoliciesPaths` 파일 (설정된 순서대로) +2. 프로젝트 컨벤션 파일 (`{cwd}/.failproofai/policies/`, 알파벳순) +3. 사용자 컨벤션 파일 (`~/.failproofai/policies/`, 알파벳순) --- @@ -103,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -정책을 등록합니다. 같은 파일에 여러 정책을 등록하려면 원하는 만큼 호출하세요. +정책을 등록합니다. 같은 파일에 여러 정책을 등록하려면 원하는 만큼 반복 호출하세요. ```ts customPolicies.add({ name: string; // 필수 - 고유 식별자 description?: string; // `failproofai policies` 출력에 표시됨 - match?: { events?: HookEventType[] }; // 이벤트 타입으로 필터링; 생략하면 모든 이벤트에 매칭 + match?: { events?: HookEventType[] }; // 이벤트 타입으로 필터링; 생략 시 모든 이벤트에 매칭 fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### 결정 헬퍼 +### 결정 헬퍼 함수 | 함수 | 효과 | 사용 시점 | |----------|--------|----------| -| `allow()` | 작업을 조용히 허용 | 작업이 안전하며 메시지가 필요 없을 때 | -| `deny(message)` | 작업 차단 | 에이전트가 이 작업을 수행하지 않아야 할 때 | -| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트가 올바른 방향을 유지하도록 추가 컨텍스트를 제공할 때 | +| `allow()` | 작업을 조용히 허용 | 해당 작업이 안전하여 메시지가 필요 없을 때 | +| `deny(message)` | 작업을 차단 | 에이전트가 해당 작업을 수행해서는 안 될 때 | +| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트가 올바른 방향을 유지하도록 추가 정보를 제공할 때 | -`deny(message)` — 메시지는 `"Blocked by failproofai:"` 접두사와 함께 Claude에 표시됩니다. 하나의 `deny`가 발생하면 이후 모든 평가가 단락됩니다. +`deny(message)` — 메시지는 `"Blocked by failproofai:"` 접두사와 함께 Claude에게 전달됩니다. `deny`가 하나라도 있으면 이후 모든 평가가 단락됩니다. -`instruct(message)` — 메시지는 현재 툴 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다. +`instruct(message)` — 메시지는 현재 도구 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다. -`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 `deny` 또는 `instruct` 메시지에 추가 안내를 덧붙일 수 있습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [Configuration → hint](/ko/configuration#hint-cross-cutting)를 참고하세요. +`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 `deny`나 `instruct` 메시지에 추가 안내를 덧붙일 수 있습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 사용 가능합니다. 자세한 내용은 [설정 → hint](/ko/configuration#hint-cross-cutting)를 참고하세요. ### 정보성 allow 메시지 -`allow(message)`는 작업을 허용하면서 **동시에** Claude에 정보성 메시지를 전송합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달됩니다 — `instruct`와 동일한 메커니즘이지만 의미상 차이가 있습니다. 경고가 아닌 상태 업데이트입니다. +`allow(message)`는 작업을 허용하면서 **동시에** Claude에게 정보성 메시지를 전달합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달되며, `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({ @@ -165,27 +165,27 @@ customPolicies.add({ | 필드 | 타입 | 설명 | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | 호출되는 툴 (예: `"Bash"`, `"Write"`, `"Read"`) | -| `toolInput` | `Record \| undefined` | 툴의 입력 파라미터 | +| `toolName` | `string \| undefined` | 호출되는 도구 (예: `"Bash"`, `"Write"`, `"Read"`) | +| `toolInput` | `Record \| undefined` | 도구의 입력 파라미터 | | `payload` | `Record` | Claude Code에서 전달된 전체 원시 이벤트 페이로드 | -| `session` | `SessionMetadata \| undefined` | 세션 컨텍스트 (아래 참고) | +| `session` | `SessionMetadata \| undefined` | 세션 컨텍스트 (아래 참조) | ### `SessionMetadata` 필드 | 필드 | 타입 | 설명 | |-------|------|-------------| | `sessionId` | `string` | Claude Code 세션 식별자 | -| `cwd` | `string` | Claude Code 세션의 작업 디렉터리 | +| `cwd` | `string` | Claude Code 세션의 작업 디렉토리 | | `transcriptPath` | `string` | 세션의 JSONL 트랜스크립트 파일 경로 | ### 이벤트 타입 | 이벤트 | 발생 시점 | `toolInput` 내용 | |-------|--------------|----------------------| -| `PreToolUse` | Claude가 툴을 실행하기 전 | 툴의 입력 (예: Bash의 경우 `{ command: "..." }`) | -| `PostToolUse` | 툴 실행 완료 후 | 툴의 입력 + `tool_result` (출력) | -| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 반드시 `allow()`를 반환해야 하며, 알림을 차단할 수 없음 | -| `Stop` | Claude 세션이 종료될 때 | 비어있음 | +| `PreToolUse` | Claude가 도구를 실행하기 전 | 도구의 입력 (예: Bash의 경우 `{ command: "..." }`) | +| `PostToolUse` | 도구 실행 완료 후 | 도구의 입력 + `tool_result` (출력) | +| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 반드시 `allow()`를 반환해야 하며, 알림을 차단할 수 없습니다 | +| `Stop` | Claude 세션이 종료될 때 | 비어 있음 | --- @@ -193,20 +193,20 @@ customPolicies.add({ 정책은 다음 순서로 평가됩니다: -1. 내장 정책 (정의 순서) -2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 순서) -3. 프로젝트 `.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서) -4. 사용자 `~/.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서) +1. 내장 정책 (정의 순서대로) +2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 호출 순서대로) +3. 프로젝트 `.failproofai/policies/`의 컨벤션 정책 (파일 알파벳순, 파일 내 `.add()` 순서) +4. 사용자 `~/.failproofai/policies/`의 컨벤션 정책 (파일 알파벳순, 파일 내 `.add()` 순서) -첫 번째 `deny`가 이후 모든 정책을 단락시킵니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다. +첫 번째 `deny`가 이후 모든 정책 평가를 단락시킵니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다. --- -## 전이적 가져오기 +## 전이적 임포트 -커스텀 정책 파일은 상대 경로를 사용하여 로컬 모듈을 가져올 수 있습니다: +커스텀 정책 파일은 상대 경로를 사용해 로컬 모듈을 임포트할 수 있습니다: ```js // my-policies.js @@ -223,46 +223,46 @@ customPolicies.add({ }); ``` -엔트리 파일에서 접근 가능한 모든 상대 가져오기가 해석됩니다. 이는 `from "failproofai"` 가져오기를 실제 dist 경로로 재작성하고 ESM 호환성을 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다. +진입 파일에서 도달 가능한 모든 상대 임포트가 해석됩니다. 이는 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하고 ESM 호환성을 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다. --- ## 이벤트 타입 필터링 -`match.events`를 사용하여 정책이 발동되는 시점을 제한할 수 있습니다: +`match.events`를 사용해 정책이 발동되는 시점을 제한할 수 있습니다: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // 세션이 종료될 때만 발동됨 - // ctx.session.transcriptPath에 전체 세션 로그가 포함됨 + // 세션이 종료될 때만 발동됩니다 + // ctx.session.transcriptPath에 전체 세션 로그가 있습니다 return allow(); }, }); ``` -모든 이벤트 타입에서 발동시키려면 `match`를 완전히 생략하세요. +`match`를 완전히 생략하면 모든 이벤트 타입에서 발동됩니다. --- ## 오류 처리 및 실패 모드 -커스텀 정책은 **fail-open** 방식입니다. 오류가 발생해도 내장 정책이 차단되거나 훅 핸들러가 크래시되지 않습니다. +커스텀 정책은 **fail-open** 방식으로 동작합니다. 오류가 발생해도 내장 정책을 차단하거나 훅 핸들러를 중단시키지 않습니다. -| 실패 원인 | 동작 | +| 실패 상황 | 동작 | |---------|----------| -| `customPoliciesPath` 미설정 | 명시적 커스텀 정책 미실행; 컨벤션 정책 및 내장 정책은 정상 계속 | -| 파일을 찾을 수 없음 | `~/.failproofai/hook.log`에 경고 기록; 내장 정책 계속 | -| 구문/가져오기 오류 (명시적) | `~/.failproofai/hook.log`에 오류 기록; 명시적 커스텀 정책 건너뜀 | -| 구문/가져오기 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 로드 | -| `fn` 런타임 오류 | 오류 기록; 해당 훅은 `allow`로 처리; 다른 훅 계속 | -| `fn` 10초 초과 | 타임아웃 기록; `allow`로 처리 | -| 컨벤션 디렉터리 없음 | 컨벤션 정책 미실행; 오류 없음 | +| `customPoliciesPath` 미설정 | 명시적 커스텀 정책이 실행되지 않으며, 컨벤션 정책과 내장 정책은 정상 동작 | +| 파일을 찾을 수 없음 | 경고가 `~/.failproofai/hook.log`에 기록되며, 내장 정책은 계속 실행 | +| 구문/임포트 오류 (명시적) | 오류가 `~/.failproofai/hook.log`에 기록되며, 명시적 커스텀 정책은 건너뜀 | +| 구문/임포트 오류 (컨벤션) | 오류가 기록되고 해당 파일은 건너뛰며, 다른 컨벤션 파일은 계속 로드 | +| 런타임에서 `fn` 예외 발생 | 오류가 기록되고 해당 훅은 `allow`로 처리되며, 다른 훅은 계속 실행 | +| `fn` 실행이 10초 초과 | 타임아웃이 기록되고 `allow`로 처리 | +| 컨벤션 디렉토리 없음 | 컨벤션 정책이 실행되지 않으며, 오류 없음 | -커스텀 정책 오류를 디버그하려면 로그 파일을 실시간으로 확인하세요: +커스텀 정책 오류를 디버깅하려면 로그 파일을 실시간으로 확인하세요: ```bash tail -f ~/.failproofai/hook.log @@ -271,13 +271,13 @@ tail -f ~/.failproofai/hook.log --- -## 전체 예시: 여러 정책 +## 전체 예제: 여러 정책 ```js // 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", @@ -290,7 +290,7 @@ customPolicies.add({ }, }); -// 에이전트 방향 유지: 커밋 전 테스트 확인 +// 에이전트 방향 유지: 커밋 전 테스트 검증 customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -326,33 +326,33 @@ export { customPolicies }; --- -## 예시 파일 +## 예제 파일 -`examples/` 디렉터리에 바로 사용할 수 있는 정책 파일이 포함되어 있습니다: +`examples/` 디렉토리에는 바로 실행 가능한 정책 파일들이 포함되어 있습니다: | 파일 | 내용 | |------|----------| -| `examples/policies-basic.js` | 일반적인 에이전트 실패 패턴을 다루는 5가지 기본 정책 | -| `examples/policies-advanced/index.js` | 고급 패턴: 전이적 가져오기, 비동기 호출, 출력 스크러빙, 세션 종료 훅 | -| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 파일 쓰기 차단, git 히스토리 재작성 방지) | -| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로우 정책 (테스트 리마인더, 감사 파일 쓰기) | +| `examples/policies-basic.js` | 일반적인 에이전트 실패 패턴을 다루는 5개의 기본 정책 | +| `examples/policies-advanced/index.js` | 고급 패턴: 전이적 임포트, 비동기 호출, 출력 스크러빙, 세션 종료 훅 | +| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 쓰기 차단, git 히스토리 재작성 방지) | +| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로우 정책 (테스트 리마인더, 파일 쓰기 감사) | -### 명시적 파일 예시 사용 +### 명시적 파일 예제 사용 ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### 컨벤션 기반 예시 사용 +### 컨벤션 기반 예제 사용 ```bash -# 프로젝트 레벨로 복사 +# 프로젝트 수준으로 복사 mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# 또는 사용자 레벨로 복사 +# 또는 사용자 수준으로 복사 mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -별도 설치 명령이 필요 없습니다 — 다음 훅 이벤트 시 파일이 자동으로 감지됩니다. \ No newline at end of file +설치 명령이 필요 없습니다 — 다음 훅 이벤트 시 파일이 자동으로 감지됩니다. \ No newline at end of file diff --git a/docs/ko/dashboard.mdx b/docs/ko/dashboard.mdx index 221155f9..7c56b945 100644 --- a/docs/ko/dashboard.mdx +++ b/docs/ko/dashboard.mdx @@ -1,10 +1,10 @@ --- title: 대시보드 -description: "에이전트 세션 모니터링, 도구 호출 검토, 정책 관리" +description: "에이전트 세션 모니터링, 도구 호출 검토 및 정책 관리" icon: chart-line --- -failproofai 대시보드는 AI 에이전트 세션을 모니터링하고 정책을 관리하는 로컬 웹 애플리케이션입니다. 자리를 비운 동안 에이전트가 무엇을 했는지 확인하세요. +failproofai 대시보드는 AI 에이전트 세션을 모니터링하고 정책을 관리하기 위한 로컬 웹 애플리케이션입니다. 자리를 비운 사이 에이전트가 무엇을 했는지 확인해 보세요. --- @@ -16,7 +16,7 @@ failproofai `http://localhost:8020`에서 열립니다. -대시보드는 로컬 프로젝트, 세션, failproofai 설정 데이터를 파일시스템에서 직접 읽어옵니다. 감사 알림 및 초대와 같은 선택적 인증 기능은 해당 요청에 필요한 정보(이메일 주소 포함)를 원격 API로 전송합니다. +대시보드는 로컬 프로젝트, 세션, failproofai 구성 데이터를 파일 시스템에서 직접 읽습니다. 감사 알림 및 초대와 같은 선택적 인증 기능은 해당 요청에 필요한 정보(이메일 주소 포함)를 원격 API로 전송합니다. --- @@ -24,69 +24,69 @@ failproofai ### 프로젝트 -머신에서 발견된 Claude Code, OpenAI Codex, GitHub Copilot CLI _(베타)_, Cursor Agent _(베타)_, OpenCode _(베타)_, Pi _(베타)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 프로젝트를 모두 나열합니다. Claude 프로젝트는 `~/.claude/projects/`(또는 `CLAUDE_PROJECTS_PATH`로 설정된 경로)에서 검색됩니다. Codex 프로젝트는 `~/.codex/sessions///
/*.jsonl` 아래의 모든 트랜스크립트를 스캔하고 각 세션의 첫 번째 레코드에 기록된 `cwd`로 그룹화하여 검색됩니다. Copilot CLI 프로젝트는 각 `~/.copilot/session-state//workspace.yaml`(`COPILOT_HOME`으로 설정 가능)을 스캔하고 `cwd` 필드로 그룹화하여 검색됩니다. Cursor Agent 프로젝트는 `~/.cursor/agent-sessions//`(`CURSOR_HOME`으로 설정 가능, `conversations/`와 `sessions/`를 대체 경로로 탐색) 아래의 세션별 메타데이터를 스캔하여 `meta.json` / `session.json` / `workspace.yaml`의 `cwd` 스칼라 값으로 검색됩니다. OpenCode 프로젝트는 `~/.local/share/opencode/opencode.db`의 SQLite DB를 `opencode db --format json`으로 쿼리하여 검색됩니다(`session` 및 `project` 테이블을 읽고 `project_id`로 그룹화). Pi 프로젝트는 `~/.pi/agent/sessions//_.jsonl`(`PI_SESSIONS_DIR`으로 설정 가능) 아래의 세션별 JSONL 트랜스크립트를 스캔하고 각 세션의 첫 번째 레코드에서 `cwd`를 가져와 검색됩니다. Hermes 게이트웨이 세션은 모든 프로필의 SQLite 스토어(~/.hermes/state.db와 `~/.hermes/profiles//state.db`, `HERMES_HOME` 또는 단일 데이터베이스의 경우 `HERMES_DB_PATH`로 재정의 가능)에서 직접 읽혀 프로필과 `source`(Slack/Telegram/cli/cron — 게이트웨이 세션에는 cwd가 없음)로 `hermes--` 프로젝트에 그룹화됩니다. OpenClaw 게이트웨이 세션은 `~/.openclaw/agents//sessions/*.jsonl`에서 읽혀 에이전트와 채널로 `openclaw--` 프로젝트에 그룹화됩니다(역시 cwd 없음). Factory Droid 프로젝트는 `~/.factory/sessions//*.jsonl`의 JSONL 트랜스크립트에서 cwd로 그룹화하여 검색됩니다. Devin 프로젝트는 `~/.local/share/devin/cli/sessions.db`의 SQLite DB에서(각 세션의 `working_directory`로 그룹화), Antigravity 프로젝트는 `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`의 JSONL 트랜스크립트에서 cwd로 그룹화하여, Goose 프로젝트는 `~/.local/share/goose/sessions/sessions.db`의 SQLite DB에서(각 세션의 `working_dir`로 그룹화) 검색됩니다. 여러 CLI에서 사용된 프로젝트는 해당하는 모든 배지가 표시된 단일 행으로 렌더링됩니다. 테이블 위의 **CLI** 드롭다운을 사용하여 특정 에이전트 CLI로 필터링할 수 있으며, URL은 선택 항목을 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` 형식으로 보존합니다. +머신에서 발견된 모든 Claude Code, OpenAI Codex, GitHub Copilot CLI _(베타)_, Cursor Agent _(베타)_, OpenCode _(베타)_, Pi _(베타)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 프로젝트를 나열합니다. Claude 프로젝트는 `~/.claude/projects/`(또는 `CLAUDE_PROJECTS_PATH`로 설정된 경로)에서 검색됩니다. Codex 프로젝트는 `~/.codex/sessions///
/*.jsonl` 아래의 모든 트랜스크립트를 스캔하여 각 세션의 첫 번째 레코드에 기록된 `cwd`를 기준으로 그룹화됩니다. Copilot CLI 프로젝트는 각 `~/.copilot/session-state//workspace.yaml`(`COPILOT_HOME`을 통해 구성 가능)을 스캔하여 `cwd` 필드를 기준으로 그룹화됩니다. Cursor Agent 프로젝트는 `~/.cursor/agent-sessions//`(`CURSOR_HOME`을 통해 구성 가능하며, 폴백으로 `conversations/` 및 `sessions/` 탐색) 아래의 세션별 메타데이터를 스캔하여 `meta.json` / `session.json` / `workspace.yaml`의 `cwd` 스칼라를 기준으로 합니다. OpenCode 프로젝트는 `opencode db --format json`을 통해 `~/.local/share/opencode/opencode.db`의 SQLite DB를 쿼리하여 검색되며(`session` 및 `project` 테이블을 읽고 `project_id`로 그룹화), Pi 프로젝트는 `~/.pi/agent/sessions//_.jsonl`(`PI_SESSIONS_DIR`을 통해 구성 가능) 아래의 세션별 JSONL 트랜스크립트를 스캔하여 각 세션의 첫 번째 레코드에서 `cwd`를 추출합니다. Hermes 게이트웨이 세션은 모든 프로필의 SQLite 스토어에서 직접 읽혀집니다 — `~/.hermes/state.db`와 `~/.hermes/profiles//state.db`(`HERMES_HOME`으로 재정의 가능하며, 단일 데이터베이스는 `HERMES_DB_PATH` 사용) — 그리고 프로필과 `source`(Slack/Telegram/cli/cron — 게이트웨이 세션에는 cwd 없음)를 기준으로 `hermes--` 프로젝트로 그룹화됩니다. OpenClaw 게이트웨이 세션은 `~/.openclaw/agents//sessions/*.jsonl`에서 읽혀지고 에이전트와 채널을 기준으로 `openclaw--` 프로젝트로 그룹화됩니다(cwd 없음). Factory Droid 프로젝트는 `~/.factory/sessions//*.jsonl`의 JSONL 트랜스크립트에서 검색되어 cwd를 기준으로 그룹화됩니다. Devin 프로젝트는 `~/.local/share/devin/cli/sessions.db`의 SQLite DB(각 세션의 `working_directory`로 그룹화)에서, Antigravity 프로젝트는 `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`의 JSONL 트랜스크립트에서 cwd를 기준으로 그룹화되며, Goose 프로젝트는 `~/.local/share/goose/sessions/sessions.db`의 SQLite DB(각 세션의 `working_dir`로 그룹화)에서 검색됩니다. 여러 CLI에서 사용된 프로젝트는 일치하는 모든 배지와 함께 단일 행으로 렌더링됩니다. 표 위의 **CLI** 드롭다운을 사용하여 특정 에이전트 CLI로 필터링하세요. URL은 선택 사항을 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`로 유지합니다. -Hermes와 OpenClaw는 사용자 범위이며 그룹화할 작업 디렉터리가 없으므로 **접을 수 있는 폴더 트리**로 렌더링됩니다(프로필 또는 에이전트가 최상위 레벨, 그 아래에 채널). cwd 기반 CLI는 모두 플랫 행으로 유지됩니다. 폴더 행은 하위 항목의 세션 수와 가장 최근 활동을 집계하고, 접힌 폴더 상태는 방문 간에 기억되며, 키워드 검색은 일치하는 항목을 자동으로 펼칩니다. +Hermes와 OpenClaw는 사용자 범위이며 그룹화할 작업 디렉토리가 없으므로 **접을 수 있는 폴더 트리**로 렌더링됩니다 — 최상위 레벨에 프로필(또는 에이전트), 그 아래에 채널 — cwd 기반 CLI는 플랫 행으로 유지됩니다. 폴더 행은 하위 항목의 세션 수와 가장 최근 활동을 합산하고, 접힌 폴더는 방문 간에 기억되며, 키워드 검색은 일치하는 항목을 확장합니다. -각 프로젝트에는 다음이 표시됩니다: +각 프로젝트에 표시되는 항목: - 프로젝트 이름 (폴더 경로에서 파생) -- CLI 배지 — `Claude Code`(주황), `OpenAI Codex`(보라), `GitHub Copilot`(파랑), `Cursor Agent`(에메랄드), `OpenCode`(앰버), `Pi`(분홍), `Hermes`(인디고) 중 하나 이상 +- CLI 배지 — `Claude Code` (주황색), `OpenAI Codex` (보라색), `GitHub Copilot` (파란색), `Cursor Agent` (에메랄드색), `OpenCode` (황색), `Pi` (분홍색), 및/또는 `Hermes` (인디고) - 가장 최근 세션 활동 날짜 프로젝트를 클릭하면 해당 세션을 볼 수 있습니다. ### 세션 -프로젝트 내 모든 세션을 나열합니다. 각 세션에는 다음이 표시됩니다: +프로젝트 내 모든 세션을 나열합니다. 각 세션에 표시되는 항목: - 세션 ID - 시작 및 종료 타임스탬프 - 도구 호출 횟수 -- 훅 활동 횟수 (실행된 정책) +- 후크 활동 횟수 (실행된 정책) -날짜 범위 필터와 세션 ID 검색을 사용하여 목록을 좁힐 수 있습니다. 세션은 페이지네이션됩니다. +날짜 범위 필터와 세션 ID 검색을 사용하여 목록을 좁히세요. 세션은 페이지로 나뉩니다. 세션을 클릭하면 세션 뷰어가 열립니다. ### 세션 뷰어 -세션 뷰어는 자율 에이전트에 대한 핵심 질문에 답합니다: 에이전트가 무엇을 했으며, 올바른 방향을 유지했는가? 헤더 옆의 CLI 배지는 해당 세션이 Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 트랜스크립트 중 어느 것인지 나타냅니다. 세션에서 발생한 모든 것의 타임라인이 표시됩니다: +세션 뷰어는 자율 에이전트에 대한 핵심 질문에 답합니다: 에이전트가 무엇을 했고, 올바른 방향을 유지했는가? 헤더 옆의 CLI 배지는 세션이 Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, 또는 Goose 트랜스크립트인지를 나타냅니다. 세션에서 발생한 모든 일의 타임라인을 보여줍니다: -- **메시지** - Claude의 텍스트 응답과 사용자 프롬프트 +- **메시지** - Claude의 텍스트 응답 및 사용자 프롬프트 - **도구 호출** - Claude가 호출한 모든 도구와 입력 및 출력 - **정책 활동** - 각 도구 호출에 대해 어떤 정책이 실행되었고 어떤 결정을 반환했는지 -상단의 통계 표시줄에는 세션 지속 시간, 총 도구 호출 횟수, 훅 결정 요약(allow / deny / instruct 횟수)이 표시됩니다. +상단의 통계 바에는 세션 지속 시간, 총 도구 호출 수, 후크 결정 요약(allow / deny / instruct 횟수)이 표시됩니다. -**로그 다운로드** 버튼을 클릭하면 세션을 내보낼 수 있습니다. Claude Code, Codex, Copilot, Cursor, Pi 세션의 경우 디스크에 있는 원본 JSONL 트랜스크립트를 바이트 그대로 가져오고, OpenCode(세션이 디스크가 아닌 SQLite에 저장)의 경우 기본 `session` / `messages` / `parts` 테이블을 미러링한 JSON 문서를 가져옵니다. +**로그 다운로드** 버튼을 클릭하여 세션을 내보냅니다. Claude Code, Codex, Copilot, Cursor, Pi 세션의 경우 디스크에 있는 원본 JSONL 트랜스크립트를 바이트 단위로 그대로 받습니다. OpenCode(세션이 디스크가 아닌 SQLite에 저장)의 경우 기본 `session` / `messages` / `parts` 테이블을 미러링한 JSON 문서를 받습니다. ### 감사 -지난 세션 전반에 걸쳐 에이전트가 실제로 어떻게 행동해왔는지에 대한 성격 기반 보고서입니다. `failproofai audit` CLI와 동일한 스캔을 실행하지만, 단일 화면의 공유 가능한 포스터와 스크롤 아래의 네 개 섹션으로 렌더링됩니다: +과거 세션 전반에 걸쳐 에이전트가 실제로 어떻게 동작해왔는지에 대한 개성 중심 보고서입니다. `failproofai audit` CLI와 동일한 스캔을 실행하되, 단일 화면 공유 가능 포스터 + 스크롤 아래 네 가지 섹션으로 렌더링합니다: -1. **포스터** — 첫 번째 뷰포트를 채웁니다. failproof_ai 워드마크 + 감사 레이블 · 아키타입 인덱스(`№ NN of 08`) + 감사 날짜 · 수치 점수(0–100) + 백분위 순위 pill(`top 15%`) · 아키타입 이름(`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` 중 하나) + 3개 키워드 스트립 · `// only N% of agents are this archetype` 희귀도 라인 · 8×8 픽셀 시길 타일 · `audit yours → failproof.ai` 푸터가 포함된 독립형 PNG 캡처 영역. 캡처 박스 바로 바깥에 세 개의 공유 버튼이 있습니다: `post your archetype`(X intent), `share on linkedin`, `download poster`. 캡처는 `html-to-image`를 통해 실행되어 PNG가 화면 렌더링과 픽셀 단위로 일치합니다(점선 테두리, SVG 로고 마스크, 그라디언트, 폰트 메트릭 모두 보존). -2. **장점** — 에이전트가 이미 올바르게 수행하고 있는 동작의 체크 목록으로, 실시간 감사 데이터(깨끗한 도구 호출 비율, 메인에 직접 푸시 없음, 자격증명 유출 없음, 재시도 폭풍 없음)에서 도출됩니다. 감사 기간 동안 관련 정책이 깨끗한 기록을 가진 경우에만 각 항목이 표시됩니다. -3. **문제점** — 발생한 문제를 심각도 순으로 정렬한 테이블: `발생 시점 · 무엇이 문제였는지 + 이를 감지했을 정책 · 심각도 pill · 발생 횟수`. 재발 횟수는 `new`(1회), `N× seen`(2–9회), `recurring`(10회 이상)으로 표시됩니다. -4. **개선 방법** — 권장 정책별 목록: 흰색으로 정책 이름, 한 줄 설명, 오른쪽에 설치 명령어 + 복사 버튼. 섹션 헤더는 `enable all N → projected · `(모든 수정 사항 적용 시 도달할 점수)로 표시되며, `[install all]` 버튼은 모든 권장 정책에 대한 `failproofai policy add a b c …` 명령어 전체를 복사합니다. -5. **더 나은 복귀** — 나란히 배치된 두 개의 카드. 왼쪽: 알림 설정(`3d` / `7d` / `14d` / `30d` 주기 선택기; 인증 후 `/api/auth/reminder`를 통해 저장). 오른쪽: failproof 혜택 잠금 해제 — `invite a friend`는 친구 이메일을 쉼표/공백/줄바꿈으로 구분하여 입력하는 모달을 열고(한 번에 최대 10명), `/api/audit/invite`로 POST하여 api-server의 `POST /v0/invite`로 전달합니다. api-server는 `invite@failproof.ai`에서 수신자당 한 통의 이메일을 발송하며 발신자를 참조(Cc)로 추가하고 `Reply-To`를 설정합니다. 따라서 수신자는 누가 초대했는지 확인할 수 있고 발신자는 받은 편지함에 사본을 받게 됩니다. 익명 사용자는 초대 발송 전에 발신자 이메일을 확인하기 위해 먼저 `AuthDialog`로 안내됩니다. 권한 부여 / 혜택 이행은 추후 진행될 예정입니다. +1. **포스터** — 첫 번째 뷰포트를 채웁니다. failproof_ai 워드마크 + 감사 레이블 · 아키타입 인덱스(`№ NN of 08`) + 감사 날짜 · 숫자 점수(0–100) + 백분위 순위 알약(`top 15%`) · 아키타입 이름(`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` 중 하나) + 3가지 키워드 스트립 · `// only N% of agents are this archetype` 희귀도 라인 · 8×8 픽셀 시질 타일 · `audit yours → failproof.ai` 푸터가 포함된 독립형 PNG 캡처 영역. 캡처 박스 바로 바깥에 세 개의 공유 버튼이 있습니다: `post your archetype` (X 인텐트), `share on linkedin`, `download poster`. 캡처는 `html-to-image`를 통해 실행되어 PNG가 화면 렌더링과 픽셀 단위로 일치합니다(점선 테두리, SVG 로고 마스크, 그라디언트, 폰트 메트릭 — 모두 보존). +2. **강점** — 에이전트가 이미 올바르게 수행하는 동작의 차분한 ✓ 행 목록으로, 실시간 감사 데이터(깨끗한 도구 호출 비율, main에 직접 푸시 없음, 자격증명 유출 없음, 재시도 폭풍 없음)에서 도출됩니다 — 관련 정책이 감사 기간 동안 깨끗한 기록을 가질 때만 표시됩니다. +3. **특이점** — 심각도 순으로 정렬된 통과된 항목 표: `when · what slipped + the policy that would've caught it · severity pill · seen`, 재발 횟수는 `new`(1회), `N× seen`(2–9회), 또는 `recurring`(10회 이상)으로 읽힙니다. +4. **개선 방법** — 처방된 정책별 차분한 행 목록: 흰색으로 표시된 정책 이름, 한 줄 설명, 오른쪽에 설치 명령 + 복사 버튼. 섹션 헤더는 `enable all N → projected · `(모든 수정 사항 적용 시 도달할 점수)로 읽히며, `[install all]` 버튼은 모든 처방된 정책에 대한 결합된 `failproofai policy add a b c …` 명령을 복사합니다. +5. **더 나은 상태로 돌아오기** — 두 개의 나란히 배치된 카드. 왼쪽: 알림 설정(`3d` / `7d` / `14d` / `30d` 주기 선택기; 인증 후 `/api/auth/reminder`를 통해 유지). 오른쪽: failproof 혜택 잠금 해제 — `invite a friend`는 쉼표/공백/줄바꿈으로 구분된 친구 이메일 목록(전송당 최대 10개)을 입력받는 모달을 열고 `/api/audit/invite`에 POST하며, api-server의 `POST /v0/invite`로 전달됩니다. api-server는 발신자를 참조(Cc)로 포함하고 `Reply-To`를 설정하여 `invite@failproof.ai`에서 수신자당 하나의 이메일을 보내므로, 수신자는 누가 초대했는지 확인할 수 있고 발신자는 받은 편지함에 사본을 받습니다. 익명 사용자는 초대가 발송되기 전에 발신자의 이메일을 알 수 있도록 먼저 `AuthDialog`로 라우팅됩니다. 자격 부여 / 혜택 이행은 후속 작업입니다. -`failproofai audit` 런타임으로 구동됩니다 — 기본 스캔 엔진, 지원 플래그, 트랜스크립트별 캐시 불변성에 대해서는 [감사 CLI](/ko/cli/audit)를 참고하세요. 대시보드는 최신 결과를 `~/.failproofai/audit-dashboard.json`(모드 `0600`, 단일 슬롯, 새 실행 시 덮어씀)에 캐시하므로 재방문 시 즉시 로드됩니다. **트랜스크립트별 캐시와 전체 결과 캐시 모두 7일이 지나면 읽기 시 거부되어** 대시보드가 1주일 된 결과를 조용히 제공하는 일이 없습니다. TTL이 지나면 `/audit`는 빈 상태로 돌아가 새 실행을 요청합니다. 보고서 하단의 `[ re-audit now ]`를 클릭하면 `noCache: true`와 함께 `/api/audit/run`에 POST합니다. 재감사는 트랜스크립트별 캐시를 우회하고 캐시된 결과를 조용히 반환하는 대신 모든 트랜스크립트를 처음부터 다시 스캔합니다. 대시보드는 실행이 완료될 때까지 1Hz로 `/api/audit/status`를 폴링하며, 실행 중에는 경과 타이머와 함께 핑크색 진행 표시줄이 뷰포트 상단에 고정됩니다. 성공하면 새 결과가 전체 페이지 새로고침 없이 즉시 교체됩니다. 재감사 실패 시 표시줄은 `RerunError.kind`(`timeout` / `network` / `post_failed`)에 따른 메시지와 함께 빨간색으로 변하며 이전 보고서는 그대로 유지됩니다. 빈 상태(캐시 없음 또는 만료)와 세션 없는 상태(캐시는 있지만 스캔에서 트랜스크립트를 찾지 못함)는 별도로 표시됩니다. +`failproofai audit` 런타임에 의해 구동됩니다 — 기본 스캔 엔진, 지원되는 플래그 및 트랜스크립트별 캐시 불변성은 [감사 CLI](/ko/cli/audit)를 참조하세요. 대시보드는 최신 결과를 `~/.failproofai/audit-dashboard.json`(모드 `0600`, 단일 슬롯, 새 실행이 덮어씀)에 캐시하여 재방문이 즉시 이루어집니다. **트랜스크립트별 캐시와 전체 결과 캐시 모두 7일이 지나면 읽을 때 거부됩니다** — TTL이 지나면 `/audit`는 빈 상태로 대체되어 새 실행을 요청합니다. 보고서 하단 근처의 `[ re-audit now ]`를 클릭하면 `noCache: true`와 함께 `/api/audit/run`에 POST됩니다 — 재감사는 트랜스크립트별 캐시를 우회하고 캐시된 결과를 조용히 반환하는 대신 처음부터 모든 트랜스크립트를 다시 스캔합니다 — 대시보드는 실행이 완료될 때까지 1Hz로 `/api/audit/status`를 폴링합니다. 실행 중에는 경과 타이머와 함께 고정된 분홍색 진행 스트립이 뷰포트 상단에 고정되며, 성공 시 새 결과가 제자리에 교체됩니다(전체 페이지 새로고침 없음; 재감사 실패 시 이전 보고서는 그대로 유지). 실패 시 스트립은 `RerunError.kind`(`timeout` / `network` / `post_failed`)에 맞는 텍스트와 함께 빨간색으로 변합니다. 빈 상태(캐시 없음 또는 만료)와 세션 없음 상태(캐시는 있지만 스캔에서 트랜스크립트를 찾지 못함)는 별도로 표시됩니다. ### 정책 -정책을 관리하고 활동을 검토하는 두 개의 탭으로 구성된 페이지입니다. +정책을 관리하고 활동을 검토하기 위한 두 개의 탭 페이지입니다. - - 단일 패널에서 failproofai가 보호할 에이전트 CLI를 다중 선택합니다 — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Hermes가 각각 설치 상태(`Active` / `Detected` / `Inactive`), 사용자 범위 설정 경로, 브랜드 색상 액센트와 함께 행으로 표시됩니다. 원하는 CLI를 체크하거나 해제하고 `Apply changes`를 클릭하면 차이점을 한 번에 설치/제거할 수 있습니다. PATH에서 바이너리가 감지된 CLI는 미리 체크됩니다. - - 클릭 한 번으로 개별 정책을 켜거나 끕니다(`~/.failproofai/policies-config.json`에 쓰여지며 모든 설치된 CLI에서 공유됨) - - 정책을 펼쳐 매개변수를 구성합니다(`policyParams`를 지원하는 정책에 한함) - - 사용자 정의 정책 파일 경로 설정 + - 단일 패널에서 failproofai가 보호할 에이전트 CLI를 다중 선택 — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Hermes 모두 설치 상태(`Active` / `Detected` / `Inactive`), 사용자 범위 설정 경로, 브랜드 색상 강조와 함께 행으로 표시됩니다. 원하는 CLI를 체크하거나 체크 해제하고 `Apply changes`를 클릭하여 한 번에 설치/제거합니다. PATH에서 감지된 바이너리가 있는 CLI는 미리 체크됩니다. + - 단일 클릭으로 개별 정책 활성화 또는 비활성화(`~/.failproofai/policies-config.json`에 기록 — 모든 설치된 CLI에서 공유) + - 정책을 확장하여 매개변수 구성(`policyParams`를 지원하는 정책의 경우) + - 커스텀 정책 파일 경로 설정 - - 모든 세션에서 실행된 모든 훅 이벤트의 페이지네이션된 전체 이력 + - 모든 세션에 걸쳐 실행된 모든 후크 이벤트의 전체 페이지별 기록 - 결정, 이벤트 유형, CLI(Claude Code / OpenAI Codex / GitHub Copilot _(베타)_ / Cursor Agent _(베타)_ / OpenCode _(베타)_ / Pi _(베타)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), 정책 이름, 또는 세션 ID로 필터링 - - 각 행에 표시되는 항목: 타임스탬프, 정책 이름, 결정, CLI 배지(주황 = Claude Code, 보라 = OpenAI Codex, 파랑 = GitHub Copilot, 에메랄드 = Cursor Agent, 앰버 = OpenCode, 분홍 = Pi, 인디고 = Hermes, 청록 = OpenClaw, 로즈 = Factory Droid, 바이올렛 = Devin, 시안 = Antigravity, 라임 = Goose), 도구 이름, 세션 ID, deny/instruct 결정의 이유 - - 세션 ID를 클릭하면 트랜스크립트가 열립니다 — 뷰어는 훅을 실행한 CLI(Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`)를 자동 감지하고 헤더에 해당 CLI 배지를 렌더링합니다 + - 각 행에 표시되는 항목: 타임스탬프, 정책 이름, 결정, CLI 배지(주황색 = Claude Code, 보라색 = OpenAI Codex, 파란색 = GitHub Copilot, 에메랄드색 = Cursor Agent, 황색 = OpenCode, 분홍색 = Pi, 인디고 = Hermes, 청록색 = OpenClaw, 장미색 = Factory Droid, 바이올렛 = Devin, 시안 = Antigravity, 라임 = Goose), 도구 이름, 세션 ID, deny/instruct 결정 이유 + - 세션 ID를 클릭하면 트랜스크립트가 열립니다 — 뷰어는 어떤 CLI가 후크를 실행했는지 자동 감지하고(Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) 헤더에 일치하는 CLI 배지를 렌더링합니다 @@ -94,13 +94,13 @@ Hermes와 OpenClaw는 사용자 범위이며 그룹화할 작업 디렉터리가 ## 자동 새로고침 -대시보드 상단 네비게이션에는 자동 새로고침 토글이 있습니다. 활성화하면 현재 페이지가 주기적으로 새로고침되어 새로운 세션과 정책 활동이 나타날 때 표시됩니다. 장시간 실행되는 자율 에이전트 세션을 모니터링할 때 필수적인 기능입니다. +대시보드에는 상단 내비게이션에 자동 새로고침 토글이 있습니다. 활성화하면 현재 페이지가 주기적으로 새로고침되어 새 세션과 정책 활동이 나타나는 대로 표시됩니다. 장시간 실행되는 자율 에이전트 세션을 모니터링할 때 필수적입니다. --- ## 페이지 비활성화 -대시보드의 일부 기능만 필요한 경우, `FAILPROOFAI_DISABLE_PAGES`를 비활성화할 페이지 이름의 쉼표 구분 목록으로 설정하세요: +대시보드의 일부만 필요한 경우 `FAILPROOFAI_DISABLE_PAGES`를 쉼표로 구분된 페이지 이름 목록으로 설정하세요: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -112,7 +112,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## 프로젝트 경로 구성 -기본적으로 대시보드는 표준 Claude Code 프로젝트 디렉터리에서 읽어옵니다. 사용자 정의 설정을 위해 재정의할 수 있습니다: +기본적으로 대시보드는 표준 Claude Code 프로젝트 디렉토리에서 읽습니다. 커스텀 설정의 경우 재정의하세요: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -122,30 +122,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## localhost가 아닌 호스트에서 접근하기 -**개발 모드**(`npm run dev`)로 대시보드를 실행하고 localhost가 아닌 호스트명(예: 사용자 정의 도메인, 원격 IP, 터널링된 URL)에서 접근하는 경우 다음과 같은 경고가 표시될 수 있습니다: +**개발 모드**(`npm run dev`)에서 대시보드를 실행하고 localhost가 아닌 호스트 이름(예: 커스텀 도메인, 원격 IP, 터널링된 URL)에서 접근하는 경우 다음과 같은 경고가 표시될 수 있습니다: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -이는 Next.js가 개발 전용 기능인 HMR(핫 모듈 리로드) 웹소켓에 대한 교차 출처 접근을 차단하는 것입니다. 호스트를 허용하려면 `--allowed-origins` 플래그를 사용하세요: +이는 Next.js가 개발 전용 기능인 HMR(hot module reload) 웹소켓에 대한 교차 출처 접근을 차단하는 것입니다. 호스트를 허용하려면 `--allowed-origins` 플래그를 사용하세요: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -여러 호스트나 IP의 경우 쉼표 구분 목록을 전달하세요: +여러 호스트 또는 IP의 경우 쉼표로 구분된 목록을 전달하세요: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -`FAILPROOFAI_ALLOWED_DEV_ORIGINS` 환경 변수를 대신 설정할 수도 있습니다: +대신 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 환경 변수를 설정할 수도 있습니다: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -이는 개발 모드에만 적용됩니다. `failproofai`(프로덕션 모드)를 실행할 때는 HMR 웹소켓도 없고 교차 출처 개발 리소스 문제도 발생하지 않습니다. +이는 개발 모드에만 적용됩니다. `failproofai`(프로덕션 모드)를 실행할 때는 HMR 웹소켓이 없으며 교차 출처 개발 리소스 문제도 없습니다. \ No newline at end of file diff --git a/docs/ko/examples.mdx b/docs/ko/examples.mdx index dd83aaaa..cff1bf02 100644 --- a/docs/ko/examples.mdx +++ b/docs/ko/examples.mdx @@ -1,16 +1,16 @@ --- title: 예제 -description: "Claude Code 및 Agents SDK에 훅을 설정하는 방법" +description: "Claude Code와 Agents SDK에 훅을 설정하는 방법" icon: book-open --- -일반적인 시나리오에 바로 사용할 수 있는 예제 모음입니다. 각 예제는 설치 방법과 예상 동작을 안내합니다. +일반적인 시나리오에 바로 사용할 수 있는 예제들입니다. 각 예제는 설치 방법과 예상 동작을 설명합니다. --- ## Claude Code에 훅 설정하기 -Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/docs/claude-code/hooks)을 통해 통합됩니다. `failproofai policies --install`을 실행하면, 모든 도구 호출 시 실행되는 훅 명령어가 Claude Code의 `settings.json`에 등록됩니다. +Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/docs/claude-code/hooks)을 통해 통합됩니다. `failproofai policies --install`을 실행하면 Claude Code의 `settings.json`에 훅 명령어가 등록되어 모든 도구 호출 시 실행됩니다. @@ -28,14 +28,14 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc cat ~/.claude/settings.json | grep failproofai ``` - `PreToolUse`, `PostToolUse`, `Notification`, `Stop` 이벤트에 대한 훅 항목이 보여야 합니다. + `PreToolUse`, `PostToolUse`, `Notification`, `Stop` 이벤트에 대한 훅 항목이 표시되어야 합니다. ```bash claude ``` - 이제 모든 도구 호출 시 정책이 자동으로 실행됩니다. Claude에게 `sudo rm -rf /`를 실행해보라고 요청해보세요 — 차단됩니다. + 이제 모든 도구 호출 시 정책이 자동으로 실행됩니다. Claude에게 `sudo rm -rf /` 실행을 요청해 보세요 — 차단됩니다. @@ -43,7 +43,7 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc ## Agents SDK에 훅 설정하기 -[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)로 개발 중이라면, 동일한 훅 시스템을 프로그래밍 방식으로 사용할 수 있습니다. +[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)로 개발하는 경우 동일한 훅 시스템을 프로그래밍 방식으로 사용할 수 있습니다. @@ -51,8 +51,8 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc npm install failproofai ``` - - 에이전트 프로세스 생성 시 훅 명령어를 전달하세요. 훅은 Claude Code와 동일한 방식으로 — stdin/stdout JSON을 통해 — 동작합니다: + + 에이전트 프로세스를 생성할 때 훅 명령어를 전달합니다. 훅은 Claude Code와 동일하게 stdin/stdout JSON을 통해 실행됩니다: ```bash failproofai --hook PreToolUse # called before each tool @@ -88,21 +88,21 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc ## 파괴적인 명령어 차단 -가장 일반적인 설정으로, 에이전트가 되돌릴 수 없는 피해를 입히는 것을 방지합니다. +가장 일반적인 설정 — 에이전트가 되돌릴 수 없는 손상을 일으키는 것을 방지합니다. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -각 정책의 역할: -- `block-sudo` — 모든 `sudo` 명령어를 차단합니다 -- `block-rm-rf` — 재귀적 파일 삭제를 차단합니다 -- `block-force-push` — `git push --force`를 차단합니다 -- `block-curl-pipe-sh` — 원격 스크립트를 셸로 파이프하는 것을 차단합니다 +이 설정의 동작: +- `block-sudo` - 모든 `sudo` 명령어 차단 +- `block-rm-rf` - 재귀적 파일 삭제 차단 +- `block-force-push` - `git push --force` 차단 +- `block-curl-pipe-sh` - 원격 스크립트를 셸로 파이프하는 것 차단 --- -## 시크릿 유출 방지 +## 비밀 정보 유출 방지 에이전트가 도구 출력에서 자격 증명을 보거나 유출하는 것을 방지합니다. @@ -110,13 +110,13 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -이 정책들은 `PostToolUse` 시점에 실행됩니다 — 도구가 실행된 후, 에이전트가 출력을 보기 전에 민감한 정보를 제거합니다. +이 정책들은 `PostToolUse` 시 실행됩니다 — 도구 실행 후 에이전트가 출력을 보기 전에 민감한 정보를 제거합니다. --- -## 에이전트가 대기 중일 때 Slack 알림 받기 +## 에이전트 주의 필요 시 Slack 알림 받기 -알림 훅을 사용하여 유휴 알림을 Slack으로 전달합니다. +알림 훅을 사용하여 대기 중 알림을 Slack으로 전달합니다. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -160,7 +160,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## 에이전트를 특정 브랜치에 고정 -에이전트가 브랜치를 변경하거나 보호된 브랜치에 푸시하는 것을 방지합니다. +에이전트가 다른 브랜치로 전환하거나 보호된 브랜치에 푸시하는 것을 방지합니다. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +184,7 @@ customPolicies.add({ ## 커밋 전 테스트 실행 요구 -커밋 전에 테스트를 실행하도록 에이전트에게 알립니다. +에이전트에게 커밋 전 테스트를 실행하도록 안내합니다. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -206,9 +206,9 @@ customPolicies.add({ --- -## 프로덕션 저장소 보호 +## 프로덕션 저장소 잠금 -프로젝트 수준의 설정을 커밋하여 팀의 모든 개발자가 동일한 정책을 적용받도록 합니다. +프로젝트 수준 구성을 커밋하여 팀의 모든 개발자가 동일한 정책을 적용받도록 합니다. 저장소에 `.failproofai/policies-config.json`을 생성합니다: @@ -238,16 +238,16 @@ git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -failproofai가 설치된 모든 팀원에게 이 규칙이 자동으로 적용됩니다. +failproofai가 설치된 모든 팀원은 이 규칙을 자동으로 적용받게 됩니다. --- -## 컨벤션 정책으로 조직 전체 품질 기준 수립 +## 컨벤션 정책으로 조직 전체 품질 표준 구축 -가장 효과적인 설정: 프로젝트에 맞게 커스터마이징한 정책을 `.failproofai/policies/`에 저장하고 저장소에 커밋하세요. 모든 팀원이 자동으로 적용받으며, 별도의 설치 명령어나 설정 변경이 필요 없습니다. +가장 효과적인 설정: 프로젝트에 맞게 커스터마이징된 정책을 담은 `.failproofai/policies/`를 저장소에 커밋합니다. 모든 팀원이 자동으로 적용받습니다 — 별도의 설치 명령어나 구성 변경 없이. - + ```bash mkdir -p .failproofai/policies ``` @@ -289,8 +289,8 @@ failproofai가 설치된 모든 팀원에게 이 규칙이 자동으로 적용 git commit -m "Add team quality policies" ``` - - 팀에서 새로운 문제가 발생할 때마다 정책을 추가하고 푸시하세요. 모든 팀원이 다음 `git pull` 시 업데이트를 받게 됩니다. 이 정책들은 팀과 함께 성장하는 살아있는 품질 기준이 됩니다. + + 팀이 새로운 문제 상황을 경험할 때마다 정책을 추가하고 푸시합니다. 모든 팀원은 다음 `git pull` 시 업데이트를 받습니다. 이 정책들은 팀과 함께 성장하는 살아있는 품질 표준이 됩니다. @@ -298,10 +298,10 @@ failproofai가 설치된 모든 팀원에게 이 규칙이 자동으로 적용 ## 더 많은 예제 -저장소의 [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) 디렉토리에 다음이 포함되어 있습니다: +저장소의 [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) 디렉터리에는 다음 파일들이 포함되어 있습니다: | 파일 | 내용 | |------|---------------| -| `policies-basic.js` | 기본 정책 — 프로덕션 쓰기, 강제 푸시, 파이프된 스크립트 차단 | -| `policies-notification.js` | 유휴 알림 및 세션 종료 시 Slack 알림 | -| `policies-advanced/index.js` | 전이적 임포트, 비동기 훅, PostToolUse 출력 제거, Stop 이벤트 처리 | \ No newline at end of file +| `policies-basic.js` | 기본 정책 — 프로덕션 쓰기, force-push, 파이프 스크립트 차단 | +| `policies-notification.js` | 대기 중 알림 및 세션 종료 시 Slack 알림 | +| `policies-advanced/index.js` | 전이적 임포트, 비동기 훅, PostToolUse 출력 스크러빙, Stop 이벤트 처리 | \ No newline at end of file diff --git a/docs/ko/for-agents.mdx b/docs/ko/for-agents.mdx index ef0f48bd..d9035035 100644 --- a/docs/ko/for-agents.mdx +++ b/docs/ko/for-agents.mdx @@ -1,9 +1,9 @@ --- title: "에이전트용" -description: "한 줄의 명령으로 코딩 에이전트에 Failproof AI 지식을 추가하세요. Claude Code, Cursor, Windsurf 등과 함께 작동합니다." +description: "한 줄의 명령어로 코딩 에이전트에 Failproof AI 지식을 추가하세요. Claude Code, Cursor, Windsurf 등과 호환됩니다." --- -한 줄의 명령으로 코딩 에이전트에 Failproof AI 전체 레퍼런스를 추가하세요. Claude Code, Cursor, Windsurf 및 스킬을 지원하는 모든 에이전트와 함께 작동합니다. +한 줄의 명령어로 Failproof AI 전체 레퍼런스를 코딩 에이전트에 추가하세요. Claude Code, Cursor, Windsurf를 비롯해 스킬을 지원하는 모든 에이전트와 호환됩니다. ```bash npx skills add https://docs.befailproof.ai @@ -15,19 +15,19 @@ npx skills add https://docs.befailproof.ai | 영역 | 포함 내용 | |------|----------------| -| 정책 | 기본 제공 정책 이름, 이벤트 타입, 파라미터, 활성화/비활성화 | -| 커스텀 정책 | `customPolicies.add()`, 매치 필터, `allow`/`deny`/`instruct` API | +| 정책 | 기본 제공 정책 이름, 이벤트 유형, 파라미터, 활성화/비활성화 | +| 커스텀 정책 | `customPolicies.add()`, 매칭 필터, `allow`/`deny`/`instruct` API | | 컨텍스트 객체 | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| 구성 | `policies-config.json` 구조, 스코프 병합, `policyParams` | +| 설정 | `policies-config.json` 구조, 스코프 병합, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, 스코프 | | 대시보드 | 세션 뷰어, 정책 활동, 환경 변수 | | 아키텍처 | 훅 핸들러 흐름, 종료 코드, stdin/stdout 계약 | -## 스킬은 완전한가요? +## 스킬이 완전한가요? -Mintlify는 내비게이션의 모든 페이지에서 `llms.txt`를 생성합니다. Failproof AI 문서는 전체 API를 다루며, 모든 정책, 옵션, 예제가 포함되어 있습니다. 누락된 내용이 있다면 소스는 `https://docs.befailproof.ai/llms-full.txt`에서 확인할 수 있습니다. +Mintlify는 네비게이션의 모든 페이지로부터 `llms.txt`를 생성합니다. Failproof AI 문서는 전체 API를 포괄하며, 모든 정책, 옵션, 예제가 포함되어 있습니다. 누락된 내용이 있다면 `https://docs.befailproof.ai/llms-full.txt`에서 원본을 확인할 수 있습니다. -특정 맥락에 집중하려면 특정 페이지에 직접 링크하세요: +특정 컨텍스트만 필요하다면 특정 페이지에 직접 링크하세요: ```bash # 커스텀 정책 API만 diff --git a/docs/ko/getting-started.mdx b/docs/ko/getting-started.mdx index cdbc5ddf..dc2f6059 100644 --- a/docs/ko/getting-started.mdx +++ b/docs/ko/getting-started.mdx @@ -4,10 +4,10 @@ description: "failproofai를 설치하고, 정책을 활성화하여 에이전 icon: rocket --- -## 요구사항 +## 요구 사항 - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (선택사항 - 소스에서 빌드할 때만 필요) +- **Bun** >= 1.3.0 (선택 사항 - 소스에서 빌드할 때만 필요) --- @@ -31,15 +31,15 @@ bun add -g failproofai - 정책은 에이전트의 모든 툴 호출 전후에 실행되는 규칙입니다. 파괴적인 명령, 시크릿 유출, 그 외 장애 유형을 피해가 발생하기 전에 사전 차단합니다. + 정책은 에이전트의 모든 도구 호출 전후에 실행되는 규칙입니다. 파괴적인 명령, 시크릿 유출, 그 외 장애 요인이 실제 피해를 유발하기 전에 차단합니다. ```bash failproofai policies --install ``` - 이 명령은 설치된 에이전트 CLI에 훅 항목을 기록합니다 (Claude Code의 `~/.claude/settings.json`, OpenAI Codex의 `~/.codex/hooks.json`, GitHub Copilot CLI의 `~/.copilot/hooks/failproofai.json`, Cursor Agent의 `~/.cursor/hooks.json`, OpenCode의 `~/.config/opencode/plugins/failproofai.mjs` 생성 플러그인 심 및 `~/.config/opencode/opencode.json`의 `plugin` 배열에 등록 항목, Pi의 `~/.pi/agent/settings.json`, Hermes의 `~/.hermes/config.yaml`, OpenClaw의 `~/.openclaw/openclaw.json`, Factory Droid의 `~/.factory/hooks.json`, Devin CLI의 `~/.config/devin/config.json`, Antigravity CLI의 `~/.gemini/config/hooks.json`, 또는 Goose의 `~/.agents/plugins/failproofai/hooks/hooks.json` 자동 탐색 플러그인 디렉터리). 두 개 이상 감지되면 선택 프롬프트가 표시됩니다. `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose`(임의 조합)를 전달하면 프롬프트를 건너뜁니다. + 이 명령은 설치된 에이전트 CLI에 훅 항목을 기록합니다 (Claude Code의 `~/.claude/settings.json`, OpenAI Codex의 `~/.codex/hooks.json`, GitHub Copilot CLI의 `~/.copilot/hooks/failproofai.json`, Cursor Agent의 `~/.cursor/hooks.json`, OpenCode의 `~/.config/opencode/plugins/failproofai.mjs` 플러그인 심(shim) 및 `~/.config/opencode/opencode.json`의 `plugin` 배열 등록 항목, Pi의 `~/.pi/agent/settings.json`, Hermes의 `~/.hermes/config.yaml`, OpenClaw의 `~/.openclaw/openclaw.json`, Factory Droid의 `~/.factory/hooks.json`, Devin CLI의 `~/.config/devin/config.json`, Antigravity CLI의 `~/.gemini/config/hooks.json`, 또는 Goose의 `~/.agents/plugins/failproofai/hooks/hooks.json` 자동 검색 플러그인 디렉터리). 여러 CLI가 설치되어 있을 경우 선택 프롬프트가 표시됩니다. `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (원하는 조합)를 전달하면 프롬프트를 건너뜁니다. - GitHub Copilot CLI, Cursor Agent, OpenCode, Pi는 **베타** 지원입니다 — `--cli copilot`, `--cli cursor`, `--cli opencode`, 또는 `--cli pi`로 설치하세요. Hermes(hermes-agent, Slack/Telegram 게이트웨이)는 `--cli hermes`로 사용자 범위에 설치되며 **오프라인 감사 소스**이기도 합니다. OpenClaw(openclaw 게이트웨이, 셀프호스팅 멀티채널 어시스턴트)는 `--cli openclaw`로 사용자 범위에 설치되고 — 인프로세스 플러그인 훅(`before_agent_finalize`는 실제 턴 종료 게이트이므로 `require-*-before-stop` 내장 정책이 적용됨)을 통해 정책이 실행됩니다 — 역시 **오프라인 감사 소스**입니다. Factory Droid(`droid`)는 `--cli factory`(사용자 + 프로젝트 범위)로 설치되며 **오프라인 감사 소스**이기도 합니다. Devin CLI(`devin`, Cognition)는 `--cli devin`(사용자 + 프로젝트 범위)으로 설치되며 **오프라인 감사 소스**이기도 합니다. Antigravity CLI(`agy`)는 `--cli antigravity`(사용자 + 프로젝트 범위)로 설치되며 **오프라인 감사 소스**이기도 합니다. Goose(코드명 goose, Block)는 `--cli goose`(사용자 + 프로젝트 범위)로 설치됩니다 — 인스톨러가 `~/.agents/plugins/failproofai/`에 플러그인 디렉터리를 생성하면 Goose가 자동으로 감지하며, 역시 **오프라인 감사 소스**입니다. + GitHub Copilot CLI, Cursor Agent, OpenCode, Pi 지원은 **베타** 단계입니다 — 각각 `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`로 설치하세요. Hermes (hermes-agent, Slack/Telegram 게이트웨이)는 `--cli hermes`로 사용자 범위에 설치되며 **오프라인 감사 소스**이기도 합니다. OpenClaw (openclaw 게이트웨이, 셀프 호스팅 멀티 채널 어시스턴트)는 `--cli openclaw`로 사용자 범위에 설치되며 — 인프로세스 플러그인 훅으로 강제 적용됩니다 (`before_agent_finalize`가 실제 턴 종료 게이트이므로 `require-*-before-stop` 내장 정책이 적용됨) — **오프라인 감사 소스**이기도 합니다. Factory Droid (`droid`)는 `--cli factory` (사용자 + 프로젝트 범위)로 설치되며 **오프라인 감사 소스**이기도 합니다. Devin CLI (`devin`, Cognition)는 `--cli devin` (사용자 + 프로젝트 범위)로 설치되며 **오프라인 감사 소스**이기도 합니다. Antigravity CLI (`agy`)는 `--cli antigravity` (사용자 + 프로젝트 범위)로 설치되며 **오프라인 감사 소스**이기도 합니다. Goose (코드명 goose, Block)는 `--cli goose` (사용자 + 프로젝트 범위)로 설치됩니다 — 설치 시 `~/.agents/plugins/failproofai/`에 플러그인 디렉터리를 생성하며 Goose가 자동으로 검색하고, **오프라인 감사 소스**이기도 합니다. ```bash failproofai policies --install --scope project @@ -62,25 +62,25 @@ bun add -g failproofai failproofai policies ``` - 모든 정책과 활성화 여부, 설정된 파라미터를 표시합니다. + 모든 정책, 활성화 여부, 설정된 파라미터를 표시합니다. ```bash failproofai ``` - `http://localhost:8020`에서 로컬 대시보드를 열어 세션을 탐색하고, 툴 호출을 검사하며, 정책을 관리할 수 있습니다. + `http://localhost:8020`에 로컬 대시보드를 열어 세션 조회, 도구 호출 검사, 정책 관리를 할 수 있습니다. - Claude Code를 평소처럼 시작하세요. 에이전트가 위험한 작업을 시도하면 failproofai가 자동으로 차단합니다. 에이전트를 무인으로 실행한 뒤 대시보드에서 발생한 내용을 검토하세요. + Claude Code를 평소처럼 시작하세요. 에이전트가 위험한 작업을 시도하면 failproofai가 자동으로 차단합니다. 에이전트를 무인 상태로 실행하고, 이후 대시보드에서 활동 내역을 확인하세요. --- -## 정책 작동 방식 +## 정책 동작 방식 -에이전트가 툴을 실행할 때마다 Claude Code는 failproofai를 서브프로세스로 호출합니다. +에이전트가 도구를 실행할 때마다 Claude Code는 failproofai를 서브프로세스로 호출합니다: ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -88,21 +88,21 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON writes decision to stdout ``` -각 정책은 세 가지 결정 중 하나를 반환합니다. +각 정책은 세 가지 결정 중 하나를 반환합니다: -- **allow** - 에이전트가 정상적으로 진행 -- **deny** - 해당 작업이 차단되고, 에이전트에게 이유가 전달됨 -- **instruct** - 에이전트 프롬프트에 추가 컨텍스트가 삽입됨 +- **allow** - 에이전트가 정상적으로 진행됩니다 +- **deny** - 작업이 차단되고 에이전트에게 이유가 전달됩니다 +- **instruct** - 에이전트의 프롬프트에 추가 컨텍스트가 삽입됩니다 -정책은 로컬 프로세스에서 실행됩니다. 원격 서비스로 전송되는 데이터는 없습니다. +정책은 로컬 프로세스에서 실행됩니다. 원격 서비스로 데이터가 전송되지 않습니다. --- ## 컨벤션 기반 정책으로 팀 정책 설정하기 -팀 전체에 품질 기준을 빠르게 적용하는 방법은 `.failproofai/policies/` 컨벤션을 활용하는 것입니다. 이 디렉터리에 정책 파일을 넣으면 자동으로 로드됩니다 — 플래그, 설정 변경, 설치 명령이 필요 없습니다. +팀 전체에 품질 기준을 빠르게 도입하는 가장 쉬운 방법은 `.failproofai/policies/` 컨벤션입니다. 이 디렉터리에 정책 파일을 넣으면 자동으로 로드됩니다 — 플래그, 설정 변경, 설치 명령이 필요 없습니다. @@ -111,13 +111,13 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON ``` - 예제 파일을 복사하거나 직접 작성하세요. + 예제 파일을 복사하거나 직접 작성하세요: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - 또는 새로 만들기: + 또는 새 파일을 직접 만드세요: ```js // .failproofai/policies/team-policies.mjs @@ -142,24 +142,26 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON git commit -m "Add team quality policies" ``` - failproofai가 설치된 팀원 모두가 이 정책을 자동으로 사용하게 됩니다. 개발자별 별도 설정이 필요 없습니다. + failproofai가 설치된 모든 팀원에게 이 정책이 자동으로 적용됩니다. 개발자별 별도 설정이 필요 없습니다. -`.failproofai/policies/`를 저장소에 커밋하면 팀 전체가 동일한 기준을 공유합니다. 새로운 장애 유형을 발견할 때마다 정책을 추가하고 푸시하면 모든 팀원이 다음 `git pull` 시 업데이트를 받습니다. 시간이 지날수록 이 정책들은 지속적으로 개선되는 살아있는 품질 기준이 됩니다. +`.failproofai/policies/`를 저장소에 커밋하여 팀 전체가 동일한 기준을 공유하세요. 새로운 장애 패턴을 발견할 때마다 정책을 추가하고 푸시하면 — 팀원 모두가 다음 `git pull` 시 업데이트를 받습니다. 시간이 지남에 따라 이 정책들은 지속적으로 발전하는 살아있는 품질 기준이 됩니다. --- -## 데이터 저장소 +## 데이터 저장 위치 -모든 설정과 로그는 로컬 머신에 저장됩니다. +모든 설정과 로그는 로컬 머신에 저장됩니다: | 경로 | 저장 내용 | |------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | 전역 정책 설정 | -| `~/.failproofai/hook-activity/` | 훅 실행 이력 (페이징된 JSONL) | +| `~/.failproofai/policies-config.json` | 전역 정책 설정 | +| `~/.failproofai/policies/` | 사용자 정의 정책 — `*-policies.mjs` 파일을 넣으면 별도 설정 없이 로드됨 | +| `~/.failproofai/policies/cloud-policies/` | 조직에서 이 머신에 배포한 정책 | +| `~/.failproofai/hook-activity/` | 훅 실행 이력 (페이지 단위 JSONL) | | `~/.failproofai/logs/` | 커스텀 훅 오류 디버그 로그 | | `.failproofai/policies-config.json` | 프로젝트별 설정 (커밋됨) | | `.failproofai/policies-config.local.json` | 개인 오버라이드 (gitignore 처리됨) | @@ -181,15 +183,15 @@ failproofai policies --uninstall - 범위(Scope) 및 설정 파일 형식 + 범위 및 설정 파일 형식 - 파라미터를 포함한 26가지 정책 전체 목록 + 파라미터를 포함한 26가지 정책 전체 설명 - JavaScript로 나만의 정책 작성하기 + JavaScript로 직접 정책 작성하기 diff --git a/docs/ko/introduction.mdx b/docs/ko/introduction.mdx index 15a73178..1a8958da 100644 --- a/docs/ko/introduction.mdx +++ b/docs/ko/introduction.mdx @@ -5,32 +5,32 @@ description: "FailproofAI는 AI 에이전트에 39가지 내장 실패 정책을 [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -**AI 실패 처리**, **오류 복구**, **LLM 안정성**을 위한 훅과 정책 모음입니다. **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI**, 그리고 **Agents SDK**에서 AI 에이전트를 안정적이고 자율적으로 운영하세요. +**AI 실패 처리**, **오류 복구**, **LLM 안정성**을 위한 훅과 정책. **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI**, 그리고 **Agents SDK**에서 AI 에이전트를 안정적으로 자율 실행하세요. -AI 에이전트는 예측 가능한 방식으로 실패합니다. 파괴적인 명령을 실행하거나, 시크릿을 유출하거나, 작업 범위를 벗어나거나, 루프에 빠지거나, main 브랜치에 직접 푸시하기도 합니다. 방치하면 사소한 실패가 서비스 장애, 자격 증명 유출, 작업 손실로 이어질 수 있습니다. +AI 에이전트는 예측 가능한 방식으로 실패합니다. 파괴적인 명령을 실행하거나, 시크릿을 유출하거나, 작업 범위를 벗어나거나, 루프에 빠지거나, main 브랜치에 직접 푸시하기도 합니다. 방치하면 작은 실패가 서비스 장애, 자격증명 유출, 작업 손실로 이어집니다. -FailproofAI는 **정책(policies)**으로 이 문제를 해결합니다. 이 규칙들은 모든 에이전트 도구 호출에 훅으로 연결되어 **실패를 감지**하고, **완화 조치**(차단, 지시, 정제)를 취하며, 주의가 필요한 상황이 발생하면 **알림을 전송**합니다. 로컬 대시보드에서는 모든 도구 호출, 에이전트 실패, 복구 조치를 사후에 검토할 수 있습니다. +FailproofAI는 **정책(policies)**으로 이 문제를 해결합니다. 이 규칙들은 모든 에이전트 도구 호출에 연결되어 **실패를 감지**하고, **완화**(차단, 지시, 정제)하며, 주의가 필요한 상황을 **알려줍니다**. 로컬 대시보드에서 모든 도구 호출, 에이전트 실패, 복구 조치를 이후에 검토할 수 있습니다. -트랜스크립트와 정책 평가 결과는 사용자 머신에 저장됩니다. 데이터는 인증된 감사 알림이나 초대 등 온라인 기능을 명시적으로 사용할 때만 전송됩니다. +트랜스크립트와 정책 평가 결과는 사용자 컴퓨터에만 저장됩니다. 인증된 감사 알림이나 초대 등 온라인 기능을 명시적으로 사용할 때만 데이터가 전송됩니다. ## 시작하기 - 파괴적인 명령 차단, 시크릿 유출 방지, 에이전트를 프로젝트 경계 내로 제한하는 등 다양한 기능을 즉시 사용할 수 있습니다. + 파괴적인 명령 차단, 시크릿 유출 방지, 에이전트가 프로젝트 범위를 벗어나지 않도록 제한하는 등의 기능을 기본으로 제공합니다. - 간단한 allow / deny / instruct API를 사용하여 JavaScript로 직접 규칙을 작성하세요. + 간단한 allow / deny / instruct API로 JavaScript를 사용해 직접 규칙을 작성하세요. - 자리를 비운 사이 에이전트가 무엇을 했는지 확인하세요. 세션 탐색, 도구 호출 검사, 정책이 실행된 위치 검토가 가능합니다. + 자리를 비운 동안 에이전트가 무엇을 했는지 확인하세요. 세션을 탐색하고, 도구 호출을 검사하며, 정책이 적용된 위치를 검토할 수 있습니다. - 코드 없이 어떤 정책이든 조정할 수 있습니다. 프로젝트별 또는 전역으로 허용 목록, 보호 브랜치, 임계값을 설정하세요. + 코드 없이 모든 정책을 조정하세요. 프로젝트별 또는 전역으로 허용 목록, 보호된 브랜치, 임계값을 설정할 수 있습니다. @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -전체 안내는 [시작 가이드](/ko/getting-started)를 참고하세요. \ No newline at end of file +전체 안내는 [시작하기](/ko/getting-started) 가이드를 참고하세요. \ No newline at end of file diff --git a/docs/ko/package-aliases.mdx b/docs/ko/package-aliases.mdx index 9a636459..e02bbb3b 100644 --- a/docs/ko/package-aliases.mdx +++ b/docs/ko/package-aliases.mdx @@ -1,12 +1,12 @@ --- title: 패키지 별칭 -description: "등록된 오타 방지 별칭과 작동 방식" +description: "등록된 타이포스쿼팅 방지 별칭 및 동작 방식" icon: copy --- ## 공식 패키지 -npm의 공식 패키지는 **`failproofai`**입니다: +npm의 공식 패키지명은 **`failproofai`**입니다: ```bash npm install -g failproofai @@ -16,20 +16,20 @@ bun add -g failproofai --- -## 별칭을 직접 소유하는 이유 +## 별칭 이름을 직접 소유하는 이유 -타이포스쿼팅(typosquatting)은 공급망 공격의 일반적인 수법으로, 악의적인 행위자가 인기 있는 패키지 이름에서 한 글자만 다른 패키지 이름을 등록합니다. 설치 명령어를 잘못 입력한 사용자는 시스템 전체에 대한 접근 권한을 가진 공격자가 제어하는 코드를 실행하게 됩니다. 이것이 바로 Failproof AI가 방어하도록 설계된 위협 유형입니다. +타이포스쿼팅은 공급망 공격의 대표적인 유형으로, 악의적인 행위자가 인기 패키지명에서 키 하나만 다른 이름을 등록하는 방식입니다. 설치 명령어를 잘못 입력한 사용자는 시스템 전체 접근 권한을 가진 공격자 제어 코드를 실행하게 됩니다. 이는 Failproof AI가 방어하도록 설계된 바로 그 위협입니다. -이러한 취약점을 제거하기 위해, **`failproofai`의 흔한 오타 및 포맷 변형 이름을 모두 npm에 선제적으로 등록**해 두었습니다. 이 이름들은 제3자가 등록할 수 없습니다. 각각은 실제 `failproofai` 패키지를 설치하고 위임하는 얇은 프록시입니다. +이러한 공격 표면을 제거하기 위해, **npm에서 `failproofai`의 흔한 오탈자 및 표기 변형을 모두 선점하여 소유**하고 있습니다. 이 이름들은 제3자가 등록할 수 없으며, 각각은 실제 `failproofai` 패키지를 설치하고 위임하는 얇은 프록시입니다. --- ## 등록된 별칭 -**포맷 변형** - "failproof ai"를 표기하는 다양한 방식: +**표기 변형** - "failproof ai"를 작성하는 다양한 방식: | 패키지 | 상태 | -|---------|--------| +|--------|------| | `failproof` | ✅ 게시됨 | | `failproof-ai` | ⏳ npm 승인 대기 중 | | `fail-proof-ai` | ⏳ npm 승인 대기 중 | @@ -37,27 +37,27 @@ bun add -g failproofai | `fail_proof_ai` | ⏳ npm 승인 대기 중 | | `fail-proofai` | ⏳ npm 승인 대기 중 | -**`failprof*` 오타** - "proof"에서 `o` 하나가 빠진 경우: +**`failprof*` 오탈자** - "proof"에서 `o` 하나가 빠진 경우: | 패키지 | 상태 | -|---------|--------| +|--------|------| | `failprof` | ✅ 게시됨 | | `failprof-ai` | ✅ 게시됨 | | `failprofai` | ⏳ npm 승인 대기 중 | | `fail-prof-ai` | ⏳ npm 승인 대기 중 | | `failprof_ai` | ⏳ npm 승인 대기 중 | -**`faliproof*` 오타** - `a`와 `i`가 뒤바뀐 경우: +**`faliproof*` 오탈자** - `a`와 `i`가 뒤바뀐 경우: | 패키지 | 상태 | -|---------|--------| +|--------|------| | `faliproof` | ✅ 게시됨 | | `faliproof-ai` | ✅ 게시됨 | | `faliproofai` | ⏳ npm 승인 대기 중 | -> **왜 대기 중인가요?** npm의 스팸 방지 정책은 구두점을 제거하고 유사도 검사를 실행했을 때 기존 패키지와 동일한 문자열로 정규화되는 이름의 등록을 차단합니다. 저희는 안티스쿼팅 목적으로 이 이름들을 예약하기 위해 npm 지원팀에 연락했으며, 승인되는 대로 활성화될 예정입니다. +> **대기 중인 이유는?** npm의 스팸 방지 정책은 구두점 제거 및 유사도 검사를 거쳤을 때 기존 패키지와 동일한 문자열로 정규화되는 이름의 등록을 차단합니다. 저희는 안티스쿼팅 목적으로 이 이름들을 예약하기 위해 npm 지원팀에 연락한 상태입니다. 승인되면 활성화될 예정입니다. -게시된 별칭이 저희 소유인지 확인하실 수 있습니다: +게시된 별칭이 저희 소유인지 확인하는 방법: ```bash npm info failproof @@ -66,17 +66,17 @@ npm info failproof --- -## 별칭 작동 방식 +## 별칭의 동작 방식 -각 별칭 패키지는 다음과 같이 동작합니다: +각 별칭 패키지는 다음과 같이 작동합니다: -1. `failproofai`를 의존성으로 등록하여 실제 패키지가 설치되고 바이너리를 사용할 수 있게 합니다. -2. 자체 이름(예: `failprof-ai`)과 일치하는 바이너리를 제공하여 모든 인수를 `failproofai` 바이너리에 위임합니다. +1. `failproofai`를 의존성으로 등록하여 실제 패키지가 설치되고 바이너리가 사용 가능해집니다 +2. 자신의 이름(예: `failprof-ai`)에 해당하는 바이너리를 노출하여 모든 인자를 `failproofai` 바이너리에 위임합니다 -프록시는 두 줄짜리 Node 스크립트이며, 로직도 없고 네트워크 호출도 없으며 `failproofai` 자체가 수행하는 것 이외의 데이터 수집도 일절 없습니다. +프록시는 두 줄짜리 Node 스크립트로, 로직도 없고 네트워크 호출도 없으며, `failproofai` 자체가 수행하는 것 이외의 데이터 수집도 전혀 없습니다. --- -## 누락된 이름을 발견했다면 +## 누락된 이름을 발견한 경우 [failproofai/failproofai](https://github.com/failproofai/failproofai/issues)에 이슈를 열어 주시면 해당 이름을 등록하겠습니다. \ No newline at end of file diff --git a/docs/ko/testing.mdx b/docs/ko/testing.mdx index fad3a32b..56334c52 100644 --- a/docs/ko/testing.mdx +++ b/docs/ko/testing.mdx @@ -1,20 +1,20 @@ --- title: 테스트 -description: "유닛 테스트, E2E 테스트, 테스트 헬퍼" +description: "단위 테스트, E2E 테스트, 테스트 헬퍼" icon: flask-vial --- -failproofai에는 두 가지 테스트 스위트가 있습니다: **유닛 테스트** (빠름, 모킹 사용)와 **엔드투엔드 테스트** (실제 서브프로세스 호출). +failproofai에는 두 가지 테스트 스위트가 있습니다: **단위 테스트** (빠르고 모킹 사용)와 **엔드-투-엔드 테스트** (실제 서브프로세스 호출). --- ## 테스트 실행 ```bash -# 유닛 테스트 한 번 실행 +# 단위 테스트 한 번 실행 bun run test:run -# 유닛 테스트 워치 모드로 실행 +# 단위 테스트 watch 모드 실행 bun run test # E2E 테스트 실행 (사전 설정 필요 - 아래 참고) @@ -29,9 +29,9 @@ bun run lint --- -## 유닛 테스트 +## 단위 테스트 -유닛 테스트는 `__tests__/` 디렉토리에 위치하며 `jsdom`과 함께 [Vitest](https://vitest.dev)를 사용합니다. +단위 테스트는 `__tests__/` 디렉토리에 위치하며, `jsdom`과 함께 [Vitest](https://vitest.dev)를 사용합니다. ```text __tests__/ @@ -41,7 +41,7 @@ __tests__/ policy-evaluator.test.ts # 파라미터 주입 및 평가 순서 custom-hooks-registry.test.ts # globalThis 레지스트리 추가/조회/초기화 custom-hooks-loader.test.ts # ESM 로더, 전이적 임포트, 에러 처리 - manager.test.ts # install/remove/list 작업 + manager.test.ts # 설치/제거/목록 조회 작업 components/ sessions-list.test.tsx # 세션 목록 컴포넌트 project-list.test.tsx # 프로젝트 목록 컴포넌트 @@ -61,7 +61,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### 정책 유닛 테스트 작성하기 +### 정책 단위 테스트 작성하기 ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -108,39 +108,39 @@ describe("block-sudo", () => { --- -## 엔드투엔드 테스트 +## 엔드-투-엔드 테스트 -E2E 테스트는 실제 `failproofai` 바이너리를 서브프로세스로 호출하고, JSON 페이로드를 stdin으로 파이프한 뒤, stdout 출력과 종료 코드를 검증합니다. 이를 통해 Claude Code가 사용하는 전체 통합 경로를 테스트합니다. +E2E 테스트는 실제 `failproofai` 바이너리를 서브프로세스로 호출하고, JSON 페이로드를 stdin에 전달한 뒤, stdout 출력과 종료 코드를 검증합니다. 이를 통해 Claude Code가 사용하는 전체 통합 경로를 테스트합니다. ### 설정 -E2E 테스트는 레포지토리 소스에서 직접 바이너리를 실행합니다. 최초 실행 전에, 커스텀 훅 파일이 `'failproofai'`에서 임포트할 때 사용하는 CJS 번들을 빌드하세요: +E2E 테스트는 저장소 소스에서 바이너리를 직접 실행합니다. 첫 실행 전에, 커스텀 훅 파일이 `'failproofai'`에서 임포트할 때 사용하는 CJS 번들을 빌드하세요: ```bash bun build src/index.ts --outdir dist --target node --format cjs ``` -이후 테스트를 실행합니다: +그 다음 테스트를 실행합니다: ```bash bun run test:e2e ``` -공개 훅 API (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, `src/hooks/policy-types.ts`)를 수정할 때마다 `dist/`를 다시 빌드하세요. +공개 훅 API(`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, 또는 `src/hooks/policy-types.ts`)를 변경할 때마다 `dist/`를 다시 빌드하세요. ### E2E 테스트 구조 ```text __tests__/e2e/ helpers/ - hook-runner.ts # 바이너리 실행, 페이로드 JSON 파이프, 종료 코드 + stdout + stderr 캡처 + hook-runner.ts # 바이너리 실행, 페이로드 JSON 전달, 종료 코드 + stdout + stderr 캡처 fixture-env.ts # 테스트별 격리된 임시 디렉토리 및 설정 파일 - payloads.ts # 각 이벤트 타입별 Claude 호환 페이로드 팩토리 + payloads.ts # 각 이벤트 타입에 대한 Claude 정확도 높은 페이로드 팩토리 hooks/ builtin-policies.e2e.test.ts # 실제 서브프로세스로 각 빌트인 정책 테스트 custom-hooks.e2e.test.ts # 커스텀 훅 로딩 및 평가 - config-scopes.e2e.test.ts # 프로젝트/로컬/전역 간 설정 병합 - policy-params.e2e.test.ts # 파라미터화된 정책별 파라미터 주입 + config-scopes.e2e.test.ts # 프로젝트/로컬/글로벌 간 설정 병합 + policy-params.e2e.test.ts # 파라미터화된 각 정책에 대한 파라미터 주입 ``` ### E2E 헬퍼 사용하기 @@ -151,8 +151,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - 임시 디렉토리; .failproofai/policies-config.json 을 인식하려면 payload.cwd로 전달 -// env.home - 격리된 홈 디렉토리; 실제 ~/.failproofai 가 유입되지 않음 +// env.cwd - 임시 디렉토리; .failproofai/policies-config.json을 로드하려면 payload.cwd로 전달 +// env.home - 격리된 홈 디렉토리; 실제 ~/.failproofai가 유입되지 않음 env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - 미리 만들어진 페이로드 팩토리: +**`Payloads`** - 미리 준비된 페이로드 팩토리: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -237,8 +237,8 @@ describe("block-rm-rf (E2E)", () => { |----------|-----------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Instruct (Stop 제외) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | stdout 비어 있음; 이유는 stderr에 출력 | +| Instruct (Stop 아님) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Stop instruct | `2` | 빈 stdout; 이유는 stderr에 출력 | | Allow | `0` | 빈 문자열 | ### Vitest 설정 @@ -246,15 +246,15 @@ describe("block-rm-rf (E2E)", () => { E2E 테스트는 `vitest.config.e2e.mts`를 사용하며 다음과 같이 구성됩니다: - `environment: "node"` - 브라우저 전역 변수 불필요 -- `pool: "forks"` - 진정한 프로세스 격리 (테스트가 서브프로세스를 생성) +- `pool: "forks"` - 진정한 프로세스 격리 (테스트가 서브프로세스를 생성함) - `testTimeout: 20_000` - 테스트당 20초 (바이너리 시작 + 훅 평가) -`forks` 풀은 중요합니다: 스레드 기반 워커는 `globalThis`를 공유하므로 서브프로세스를 생성하는 테스트에 간섭이 발생할 수 있습니다. 프로세스 기반 포크는 이 문제를 방지합니다. +`forks` 풀이 중요한 이유: 스레드 기반 워커는 `globalThis`를 공유하기 때문에 서브프로세스를 생성하는 테스트에 영향을 줄 수 있습니다. 프로세스 기반 포크는 이를 방지합니다. --- ## CI -머지 전에 전체 CI 실행 (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`)이 통과되어야 합니다. E2E 스위트는 별도의 CI 작업으로 병렬 실행됩니다. +머지 전에 전체 CI 실행(`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`)이 통과해야 합니다. E2E 스위트는 별도의 CI 작업으로 병렬 실행됩니다. -완전한 머지 전 체크리스트는 [Contributing](../CONTRIBUTING.md)을 참고하세요. \ No newline at end of file +전체 머지 전 체크리스트는 [Contributing](../CONTRIBUTING.md)을 참고하세요. \ No newline at end of file diff --git a/docs/pt-br/agenteye/alerts.mdx b/docs/pt-br/agenteye/alerts.mdx index 0397e07a..80071ef0 100644 --- a/docs/pt-br/agenteye/alerts.mdx +++ b/docs/pt-br/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "Alertas" -description: "Saiba no momento em que algo ultrapassa seu limite, no canal que sua equipe já monitora, em vez de ficar sabendo pelo cliente." +description: "Saiba no momento em que algo ultrapassa seus limites, no canal que seu time já usa, em vez de ficar sabendo pelo cliente." --- -Saiba no momento em que algo ultrapassa seu limite, no canal que sua equipe já monitora, em vez de ficar sabendo pelo cliente. Configure uma regra uma vez e a Observabilidade do Failproof AI verifica ela periodicamente, depois te notifica por e-mail, Slack, webhook ou direto no dashboard. +Saiba no momento em que algo ultrapassa seus limites, no canal que seu time já usa, em vez de ficar sabendo pelo cliente. Configure uma regra uma vez e o Failproof AI Observability a verifica periodicamente, notificando você por e-mail, Slack, webhook ou direto no dashboard. -![A página de Alertas: uma grade de cartões de regras de alerta, cada um mostrando seu gatilho, janela de avaliação, canais e um selo de severidade informativo, de aviso ou crítico](/agenteye/images/alerts.png) -*Todas as regras de alerta de relance: o que monitoram, com que frequência, onde notificam e qual a urgência.* +![A página de Alertas: uma grade de cards de regras de alerta, cada um mostrando seu gatilho, janela de avaliação, canais e um badge de severidade informativo, de aviso ou crítico](/agenteye/images/alerts.png) +*Todas as regras de alerta de um relance: o que monitora, com que frequência, onde notifica e qual a urgência.* ## Saiba dos problemas antes dos seus usuários -Pare de ficar atualizando um dashboard na esperança de capturar uma regressão. Use um alerta sempre que houver um sinal que você precisaria saber mesmo quando ninguém está olhando, e receba-o onde você já está: +Pare de ficar atualizando um dashboard na esperança de pegar uma regressão. Crie um alerta sempre que houver um sinal que você vai querer receber mesmo quando ninguém estiver olhando, e faça ele chegar onde você já está: - **E-mail**, para quem precisa saber. -- **Slack**, uma mensagem rica com um botão que vai direto ao incidente. -- **Webhook**, um POST JSON para PagerDuty, Opsgenie ou seu próprio endpoint, com uma assinatura opcional para que o receptor possa confiar nele. +- **Slack**, uma mensagem rica com um botão que vai direto para o incidente. +- **Webhook**, um POST JSON para PagerDuty, Opsgenie ou seu próprio endpoint, com uma assinatura opcional para que o receptor possa confiar nela. - **No dashboard**, discreto por design, para quando você está ajustando uma regra e ainda não quer notificar ninguém. -Combine qualquer combinação em uma única regra, e a severidade (informativo, aviso ou crítico) é incluída para que os urgentes pareçam urgentes. +Combine qualquer um desses canais em uma única regra, e a severidade (informativo, aviso ou crítico) vai junto para que os urgentes pareçam urgentes. ## Monte a regra em um formulário, não em JSON -Você descreve o que "quebrado" significa em um formulário, e a Observabilidade do Failproof AI escreve a regra subjacente para você. A especificação JSON é apenas o que esse formulário produz nos bastidores, então você pode lê-la para entender uma regra, mas raramente precisa digitá-la. +Você descreve o que significa "quebrado" em um formulário, e o Failproof AI Observability escreve a regra por baixo dos panos. A especificação JSON é apenas o que o formulário produz internamente, então você pode lê-la para entender uma regra, mas raramente precisará digitá-la. -![O formulário de novo alerta: nome e descrição, um botão de ativar/desativar, e um seletor de gatilho oferecendo limite de métrica, SQL personalizado, pontuação de avaliação, avaliação composta e condições por evento](/agenteye/images/alert-new.png) -*Escolha um gatilho e o formulário exibe os campos corretos; Salvar grava a regra.* +![O formulário de novo alerta: nome e descrição, um toggle de ativação e um seletor de gatilho oferecendo limiar de métrica, SQL customizado, pontuação de avaliação, avaliação composta e condições por evento](/agenteye/images/alert-new.png) +*Escolha um gatilho e o formulário mostra os campos certos; Salvar grava a regra.* -O caminho feliz é rápido: dê um nome, escolha um **gatilho** (o que monitorar), defina o **limite e a janela** (quão grave, por quanto tempo), adicione pelo menos um **canal**, depois **Salve** e clique em **Testar** para disparar uma notificação sintética e confirmar que cada destino está configurado. Por baixo dos panos, isso produz uma pequena especificação como: +O caminho feliz é rápido: dê um nome, escolha um **gatilho** (o que monitorar), defina o **limite e a janela** (quão grave, ao longo de quanto tempo), adicione pelo menos um **canal**, depois **Salve** e clique em **Testar** para disparar uma notificação sintética e confirmar que cada destino está configurado corretamente. Por baixo dos panos, isso gera uma especificação pequena como: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -Você não está limitado a um tipo de sinal. Escolha o gatilho que corresponde à forma como você pensa sobre a falha: +Você não está limitado a um único tipo de sinal. Escolha o gatilho que corresponde a como você pensa sobre a falha: | Gatilho | Dispara quando | |---|---| -| **Limite de métrica** | uma métrica predefinida (taxa de erros, latência p95 ou p99, contagens de eventos ou erros, gasto com tokens) ultrapassa seu limite em uma janela | -| **SQL personalizado** | sua própria consulta somente leitura retorna uma linha, ou um valor calculado ultrapassa um limite | +| **Limiar de métrica** | uma métrica predefinida (taxa de erros, latência p95 ou p99, contagens de eventos ou erros, gasto com tokens) ultrapassa seu limite em uma janela | +| **SQL customizado** | sua própria consulta somente leitura retorna uma linha, ou um valor calculado ultrapassa um limite | | **Pontuação de avaliação** | a média da pontuação de um avaliador (por exemplo, alucinação) ultrapassa um limite | -| **Avaliação composta** | várias verificações de pontuação se combinam com lógica any, all ou pelo-menos-N, para capturar uma regressão que só aparece entre pontuações | +| **Avaliação composta** | várias verificações de pontuação combinadas com lógica any, all ou pelo-menos-N, para detectar uma regressão que só aparece entre pontuações | | **Por evento** | um único evento correspondente ocorre: um agente específico, um tipo de erro específico ou uma substring de mensagem | -Já está olhando para uma falha na [página de Erros](/pt-br/agenteye/error-tracking)? Cada linha lá tem um botão **+ alerta** que abre esse mesmo formulário preenchido para capturar exatamente aquela falha novamente, de modo que o incidente que você acabou de triar se torna o próximo a te notificar. +Já está analisando uma falha na [página de Erros](/pt-br/agenteye/error-tracking)? Cada linha lá tem um botão **+ alerta** que abre esse mesmo formulário preenchido para capturar exatamente aquela falha novamente, de modo que o incidente que você acabou de triar se torna o que vai te notificar da próxima vez. -**Onde encontrar:** Os alertas ficam em `//alerts`. Criar, editar, excluir e testar regras requer **`alerts:write`**; `alerts:read` é suficiente para visualizar. O seletor de destinatários lista os membros da sua organização por nome, para que você possa notificar uma pessoa sem sair do formulário. +**Onde encontrar:** Alertas ficam em `//alerts`. Criar, editar, excluir e testar regras requer **`alerts:write`**; `alerts:read` é suficiente para visualizar. O seletor de destinatários lista os membros da sua organização pelo nome, então você pode notificar uma pessoa sem sair do formulário. -## Notifique-me apenas quando for real +## Notifique-me só quando for real -Uma medição ruim não deveria te acordar. O filtro de ruído **M de N** controla quantas das últimas verificações precisam falhar antes que o alerta realmente te notifique. Defina como **3 de 5** e a regra só dispara após ter ultrapassado o limite em três das últimas cinco verificações, evitando que um sinal instável gere alarmes falsos; deixe no padrão **1 de 1** para disparar na primeira violação. Você também escolhe com que frequência a regra é executada, a partir de predefinições de 1m, 5m, 15m e 1h, adequadas à velocidade com que o sinal realmente se move. +Uma medição ruim não deve te acordar. O filtro de ruído **M de N** controla quantas das últimas verificações precisam falhar antes que o alerta realmente te notifique. Configure como **3 de 5** e a regra dispara somente após violar três das últimas cinco verificações, evitando que um sinal instável gere alarmes falsos; deixe no padrão **1 de 1** para disparar na primeira violação. Você também escolhe com que frequência a regra é executada, entre predefinições de 1m, 5m, 15m e 1h, adequadas à velocidade real do sinal. ## O que acontece quando um alerta dispara -Uma violação abre um **incidente** e notifica seus canais uma vez. A partir daí, sua equipe confirma o recebimento, atribui um responsável, discute o problema e o resolve, tudo contra um registro limpo e atribuído. Esse fluxo de triagem tem seu próprio espaço: veja [Incidentes](/pt-br/agenteye/incidents). +Uma violação abre um **incidente** e notifica seus canais uma vez. A partir daí, seu time reconhece, atribui um responsável, discute e resolve, tudo contra um registro limpo e atribuído. Esse fluxo de triagem tem seu próprio espaço: veja [Incidentes](/pt-br/agenteye/incidents). ## Relacionados -- [Incidentes](/pt-br/agenteye/incidents): acompanhe um alerta disparado do estado aberto ao confirmado e ao resolvido. +- [Incidentes](/pt-br/agenteye/incidents): acompanhe um alerta disparado do aberto ao reconhecido e ao resolvido. - [Rastreamento de erros](/pt-br/agenteye/error-tracking): agrupe falhas de agentes e promova uma delas a um alerta com um clique. - [Dashboards](/pt-br/agenteye/dashboards): monitore os painéis compartilhados de onde vêm os limites que você alerta. -- [CLI e agentes](/pt-br/agenteye/cli-and-agents): crie alertas e confirme incidentes pelo terminal, ou automatize-os no CI. \ No newline at end of file +- [CLI e agentes](/pt-br/agenteye/cli-and-agents): crie alertas e reconheça incidentes pelo terminal, ou automatize no CI. \ No newline at end of file diff --git a/docs/pt-br/agenteye/api-keys.mdx b/docs/pt-br/agenteye/api-keys.mdx index 084e1c50..f429c14a 100644 --- a/docs/pt-br/agenteye/api-keys.mdx +++ b/docs/pt-br/agenteye/api-keys.mdx @@ -1,57 +1,57 @@ --- -title: "API Keys" -description: "As API keys controlam quem e o que pode acessar seu servidor de Observabilidade do Failproof AI, para que um coletor possa enviar eventos sem nunca obter poderes de leitura ou administração." +title: "Chaves de API" +description: "As chaves de API controlam quem e o que pode acessar seu servidor de Observabilidade Failproof AI, permitindo que um coletor envie eventos sem nunca obter poderes de leitura ou administração." --- -As API keys controlam quem e o que pode acessar seu servidor de Observabilidade do Failproof AI, para que um coletor possa enviar eventos sem nunca obter poderes de leitura ou administração. Cada chave carrega uma ou mais permissões, e cada permissão controla rotas específicas do servidor; você concede apenas as necessárias para cada função. A maioria dos deployments cria apenas três tipos de chave. +As chaves de API controlam quem e o que pode acessar seu servidor de Observabilidade Failproof AI, permitindo que um coletor envie eventos sem nunca obter poderes de leitura ou administração. Cada chave carrega uma ou mais permissões, e cada permissão controla rotas específicas do servidor; você concede apenas as que um determinado trabalho precisa. A maioria das implantações cria apenas três tipos de chave. -## As 3 chaves que a maioria dos deployments precisa +## Os 3 tipos de chave que a maioria das implantações precisa | Chave | Permissões | Quem usa | |---|---|---| -| Chave de coletor | `events:add` | O `agenteye-collector` em cada máquina de agente, para enviar eventos. | +| Chave do coletor | `events:add` | O `agenteye-collector` em cada máquina de agente, para enviar eventos. | | Chave de leitura do dashboard | `events:read`, `keys:read` | Um operador somente leitura ou integração que consulta dados sem modificá-los. | -| Chave admin bootstrap | todas as permissões | O operador que inicializa a instância (e o dashboard) pela primeira vez. Gerada a partir da variável de ambiente `ADMIN_KEY`. Veja [Chave admin bootstrap](#bootstrap-admin-key). | +| Chave de administração bootstrap | todas as permissões | O operador que inicializa a instância pela primeira vez (e o dashboard). Semeada a partir da variável de ambiente `ADMIN_KEY`. Veja [Chave de administração bootstrap](#bootstrap-admin-key). | -Comece por aqui. Recorra ao catálogo completo de permissões abaixo apenas quando precisar de uma chave personalizada com escopo mais restrito. Veja também [Layout de chaves recomendado](#recommended-key-layout) e [Criando chaves](#creating-keys). +Comece aqui. Consulte o catálogo completo de permissões abaixo apenas quando precisar de uma chave com escopo mais restrito e personalizado. Veja também [Layout de chaves recomendado](#recommended-key-layout) e [Criando chaves](#creating-keys). --- ## Permissões -O servidor aplica um catálogo fixo de permissões; cada uma controla rotas HTTP específicas. Uma **chave admin** possui todas elas; uma chave com escopo definido possui o subconjunto que você concede na criação. Strings de permissão desconhecidas são rejeitadas ao criar uma chave. +O servidor aplica um catálogo fixo de permissões; cada uma controla rotas HTTP específicas. Uma **chave de administração** possui todas elas; uma chave com escopo possui o subconjunto que você concede na criação. Strings de permissão desconhecidas são rejeitadas quando uma chave é criada. -> **Nota:** Duas permissões válidas são exclusivas para humanos/dashboard e não podem ser concedidas a uma API key: `orgs:admin` (administração da instância, exclusiva do operador) e `keys:update`. Uma requisição para `POST /keys` ou `PATCH /keys/:id` que tente conceder qualquer uma delas é rejeitada com HTTP 422. Veja a linha `keys:update` abaixo para entender por que uma chave bearer pode criar chaves, mas nunca editá-las. +> **Nota:** Duas permissões válidas são exclusivas para humanos/dashboard e não podem ser concedidas a uma chave de API: `orgs:admin` (administração da instância, exclusiva do operador) e `keys:update`. Uma requisição a `POST /keys` ou `PATCH /keys/:id` que tente conceder qualquer uma delas é rejeitada com HTTP 422. Veja a linha `keys:update` abaixo para entender por que uma chave bearer pode criar chaves, mas nunca editá-las. ### Ingestão e consulta de eventos | Permissão | Rotas HTTP | O que permite | |---|---|---| | `events:add` | `POST /events` | Ingerir lotes de eventos de um coletor. É a única permissão que um coletor precisa. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Consultar eventos, listar os ambientes conhecidos, listar os identificadores de modelos vistos nos dados (usados pela visualização de Modelos e filtros de modelo), calcular o agregado de latência que alimenta o mapa de calor / banda de percentil, e exportar uma sessão como JSONL. Os endpoints de faceta do filtro compartilhado `GET /events/environments` e `GET /events/agent_ids` são acessíveis com **qualquer um** de `events:read` **ou** `evaluations:read`, para que a página de sessões (restrita a `evaluations:read`) reutilize a mesma faceta por organização. `GET /events/models` não é um deles: requer `events:read`, então um principal que possui apenas `evaluations:read` recebe um 403 nessa rota. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Consultar eventos, listar os ambientes conhecidos, listar os identificadores de modelos vistos nos dados (usado pela visão de Modelos e filtros de modelos), calcular o agregado de latência que alimenta o mapa de calor/faixa de percentil, e exportar uma sessão como JSONL. Os endpoints de facetas da barra de filtros compartilhada `GET /events/environments` e `GET /events/agent_ids` são acessíveis com **`events:read`** **ou** `evaluations:read`, então a página de sessões (protegida por `evaluations:read`) reutiliza a mesma faceta por organização. `GET /events/models` não é um deles: requer `events:read`, portanto um principal que possui apenas `evaluations:read` recebe um 403 ao acessá-lo. | ### Sessões e avaliações | Permissão | Rotas HTTP | O que permite | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Listar sessões, ler resultados de avaliações, a saúde consolidada de avaliações usada pelos dashboards, e o estado da fila de trabalhadores de jobs de avaliação. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Listar sessões, ler resultados de avaliações, a saúde consolidada de avaliações usada pelos dashboards, e o estado da fila de trabalhos de avaliação. | | `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Enfileirar manualmente uma reavaliação para uma sessão concluída. | ### Dashboards | Permissão | Rotas HTTP | O que permite | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Listar dashboards, carregar um e ler seus tiles. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Criar e editar dashboards, adicionar / editar / remover tiles, e reordenar o grid de tiles. | -| `dashboards:delete` | `DELETE /dashboards/:id` | Excluir um dashboard inteiro (a exclusão no nível de tile fica em `dashboards:write`). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Listar dashboards, carregar um deles e ler seus tiles. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Criar e editar dashboards, adicionar/editar/remover tiles e reorganizar a grade de tiles. | +| `dashboards:delete` | `DELETE /dashboards/:id` | Excluir um dashboard inteiro (a exclusão no nível de tile está em `dashboards:write`). | ### Consultas salvas (compositor SQL) | Permissão | Rotas HTTP | O que permite | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Listar consultas salvas, carregar uma e inspecionar o schema somente leitura que o compositor usa como alvo. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | Criar e editar consultas salvas. O SQL ainda é roteado pelo mesmo papel somente leitura e verificações de SQL protegidas que uma chamada `queries:run`. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Listar consultas salvas, carregar uma delas e inspecionar o schema somente leitura que o compositor usa como alvo. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | Criar e editar consultas salvas. O SQL ainda é roteado pelo mesmo papel somente leitura e verificações SQL protegidas que uma chamada `queries:run`. | | `queries:delete` | `DELETE /queries/:id` | Excluir uma consulta salva. | | `queries:run` | `POST /queries/run` | Executar SQL salvo ou ad-hoc contra o papel somente leitura usado pelo compositor. | @@ -59,97 +59,97 @@ O servidor aplica um catálogo fixo de permissões; cada uma controla rotas HTTP | Permissão | Rotas HTTP | O que permite | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Conversar com o assistente de IA e gerenciar suas próprias conversas (privadas). Necessário no **usuário** para ver o painel do assistente; a chave própria do assistente é `dashboard-assistant` e é gerada separadamente (veja abaixo). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Conversar com o assistente de IA e gerenciar suas próprias conversas (privadas). Necessário no **usuário** para ver o painel do assistente; a chave própria do assistente é `dashboard-assistant` e é semeada separadamente (veja abaixo). | -### API keys +### Chaves de API | Permissão | Rotas HTTP | O que permite | |---|---|---| -| `keys:create` | `POST /keys` | Criar uma nova API key com escopo definido. **Não** concede edição das permissões de uma chave existente (isso é `keys:update`). | -| `keys:read` | `GET /keys` | Listar chaves existentes. Segredos nunca são retornados por este endpoint. | -| `keys:update` | `PATCH /keys/:id` | Editar as permissões de uma chave existente. Permissão **exclusiva para humanos/dashboard**; não pode ser atribuída a uma API key (uma chave bearer pode criar chaves, mas nunca editá-las). | -| `keys:disable` | `POST /keys/:id/disable` | Revogar uma chave. Chaves protegidas (`admin`, `dashboard-assistant`) não podem ser desativadas; faça a rotação por variável de ambiente + reinicialização. | -| `keys:regenerate` | `POST /keys/:id/regenerate` | Rotacionar o segredo de uma chave. Chaves protegidas não podem ser regeneradas por esta rota. | +| `keys:create` | `POST /keys` | Criar uma nova chave de API com escopo. **Não** concede a edição das permissões de uma chave existente (isso é `keys:update`). | +| `keys:read` | `GET /keys` | Listar chaves existentes. Segredos nunca são retornados por esse endpoint. | +| `keys:update` | `PATCH /keys/:id` | Editar as permissões de uma chave existente. Uma permissão **exclusiva para humanos/dashboard**; não pode ser atribuída a uma chave de API (uma chave bearer pode criar chaves, mas nunca editá-las). | +| `keys:disable` | `POST /keys/:id/disable` | Revogar uma chave. Chaves protegidas (`admin`, `dashboard-assistant`) não podem ser desabilitadas; rotacione-as via variável de ambiente + reinicialização. | +| `keys:regenerate` | `POST /keys/:id/regenerate` | Rotacionar o segredo de uma chave. Chaves protegidas não podem ser regeneradas por essa rota. | ### Usuários do dashboard | Permissão | Rotas HTTP | O que permite | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | Convidar um novo usuário do dashboard (envia um e-mail + login com senha de uso único (OTP)) e ler o conjunto de permissões padrão configurado no dashboard usado para pré-preencher o formulário de convite. | +| `users:create` | `POST /users`, `GET /users/defaults` | Convidar um novo usuário do dashboard (emite um e-mail + login com código de uso único (OTP)) e ler o conjunto de permissões padrão configurado no dashboard, usado para preencher o formulário de convite. | | `users:read` | `GET /users`, `GET /users/:id` | Listar usuários e carregar um registro de usuário individual. | -| `users:update` | `PUT /users/:id` | Editar as permissões de um usuário. As atualizações enviam um e-mail de alteração de permissões ao usuário afetado e entram em vigor na próxima requisição dele; nenhum novo login é necessário. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Desativar um usuário (revoga suas sessões imediatamente) e reativar um usuário anteriormente desativado. | +| `users:update` | `PUT /users/:id` | Editar as permissões de um usuário. As atualizações enviam um e-mail de alteração de permissão ao usuário afetado e entram em vigor na próxima requisição; não é necessário fazer login novamente. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Desabilitar um usuário (revoga suas sessões imediatamente) e reativar um usuário previamente desabilitado. | -Essas permissões sustentam a página **Users** do dashboard, onde os escopos concedidos a cada membro são exibidos como chips: +Essas permissões sustentam a página **Usuários** do dashboard, onde os escopos concedidos a cada membro são exibidos como chips: -![A página Users: um card por usuário do dashboard com seu e-mail, permissões concedidas e controles de edição/desativação](/agenteye/images/users.png) +![A página Usuários: um cartão por usuário do dashboard com seu e-mail, permissões concedidas e controles de edição/desabilitação](/agenteye/images/users.png) ### Configurações operacionais | Permissão | Rotas HTTP | O que permite | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Visualizar configurações operacionais gerenciadas pelo dashboard e seus metadados; listar substituições de janela de contexto por modelo; e resolver a janela efetiva para um modelo. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Editar configurações operacionais e adicionar, alterar ou remover substituições de janela de contexto por modelo. As alterações afetam novos eventos sem reiniciar o servidor. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Visualizar configurações operacionais gerenciadas pelo dashboard e seus metadados; listar substituições de janelas de contexto por modelo; e resolver a janela efetiva para um modelo. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Editar configurações operacionais e adicionar, alterar ou remover substituições de janelas de contexto por modelo. As alterações afetam novos eventos sem reiniciar o servidor. | -![A página Settings: configurações operacionais gerenciadas pelo dashboard, como logins permitidos e tempos de vida de sessão/OTP, editáveis sem reinicialização](/agenteye/images/settings.png) +![A página de Configurações: configurações operacionais gerenciadas pelo dashboard, como logins permitidos e tempos de vida de sessão/OTP, editáveis sem reinicialização](/agenteye/images/settings.png) ### Alertas e incidentes | Permissão | Rotas HTTP | O que permite | |---|---|---| -| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Visualizar definições de alertas configurados. | +| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Visualizar definições de alertas configuradas. | | `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Criar, editar, excluir e disparar alertas de teste. | | `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Visualizar incidentes e seu histórico de triagem. | | `incidents:write` | `POST /alerts/:id/incidents` | Abrir um incidente manualmente contra um alerta existente. | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Reconhecer, atribuir, resolver e comentar incidentes. | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Reconhecer, atribuir, resolver e comentar em incidentes. | ### Auditorias | Permissão | Rotas HTTP | O que permite | |---|---|---| | `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Visualizar definições de auditoria, histórico de execuções e achados. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Criar, editar, excluir e executar auditorias; triar achados (reconhecer / silenciar / descartar / resolver / reabrir / atribuir). | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Criar, editar, excluir e executar auditorias; triar achados (reconhecer/silenciar/descartar/resolver/reabrir/atribuir). | -> **Nota:** Para conceder a uma chave acesso à superfície de auditoria, conceda `audits:*` a ela explicitamente. Veja [Notas de atualização e compatibilidade retroativa](#upgrade-and-backward-compatibility-notes) para saber como os beneficiários existentes foram migrados quando Auditorias foi lançado. +> **Nota:** Para conceder a uma chave acesso à superfície de auditoria, conceda `audits:*` explicitamente. Veja [Notas de atualização e compatibilidade retroativa](#upgrade-and-backward-compatibility-notes) para saber como os titulares existentes foram migrados quando o módulo de Auditorias foi lançado. -> O endpoint de seleção de destinatários `GET /alerts/recipients` (que lista os e-mails de membros que um editor de alertas pode notificar) é acessível por um portador de **qualquer um** de `alerts:read` **ou** `alerts:write`, para que editores de alertas possam preencher o seletor sem precisar de `users:read`. +> O endpoint do seletor de destinatários `GET /alerts/recipients` (que lista os e-mails de membros que um editor de alertas pode notificar) é acessível pelo titular de **`alerts:read`** **ou** `alerts:write`, para que editores de alertas possam preencher o seletor sem precisar de `users:read`. -> Um visualizador de dashboards precisa de **ambos** `dashboards:read` (para carregar as visualizações salvas) e `evaluations:read` (as métricas de saúde são calculadas a partir de dados de avaliação). Conceda `dashboards:write` para permitir que um usuário crie ou edite dashboards, e `dashboards:delete` para removê-los. +> Um visualizador de dashboards precisa de **ambos** `dashboards:read` (para carregar as visões salvas) e `evaluations:read` (as métricas de saúde são calculadas a partir dos dados de avaliação). Conceda `dashboards:write` para permitir que um usuário crie ou edite dashboards, e `dashboards:delete` para removê-los. -> `/health` e `/auth/*` (solicitação de OTP, verificação de OTP, verificação de sessão, logout) são não autenticados por design; são o fluxo de login e a sonda de disponibilidade. `GET /access-granters` requer uma chave válida, mas nenhuma permissão específica, para que qualquer usuário logado possa ver quais admins contatar sobre alterações de acesso. +> `/health` e `/auth/*` (solicitação OTP, verificação OTP, verificação de sessão, logout) são não autenticados por design; eles compõem o fluxo de login e a sonda de liveness. `GET /access-granters` requer uma chave válida, mas nenhuma permissão específica, para que qualquer usuário logado possa ver quais administradores contatar sobre alterações de acesso. --- ## Conjuntos de Permissões -Os conjuntos de permissões permitem aplicar um papel nomeado em vez de selecionar tokens individuais manualmente toda vez. Em vez de selecionar uma dúzia de permissões uma a uma para cada novo usuário do dashboard ou API key, você escolhe um conjunto, e todos os atribuídos a ele carregam uma concessão consistente e revisável. Editar um conjunto personalizado reaplicará a nova concessão a todos os usuários já atribuídos a ele, portanto uma mudança de papel é uma única edição, e não uma varredura por todos os membros. +Os conjuntos de permissões permitem aplicar um papel nomeado em vez de selecionar tokens individuais manualmente toda vez. Em vez de escolher uma dúzia de permissões uma a uma para cada novo usuário do dashboard ou chave de API, você escolhe um conjunto, e todos atribuídos a ele carregam uma concessão consistente e revisável. Editar um conjunto personalizado reaaplica a nova concessão a todos os usuários já atribuídos a ele, portanto uma mudança de papel é uma única edição em vez de uma varredura por todos os membros. -Cada organização é inicializada com três conjuntos integrados: +Cada organização é semeada com três conjuntos integrados: | Conjunto | Permissões | Destinado a | |---|---|---| | `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Acesso somente leitura em todas as superfícies operacionais. | -| `standard` | tudo em `read-only`, mais `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Somente leitura mais as ações cotidianas do plantão: executar consultas, reavaliar sessões, reconhecer incidentes e usar o assistente de IA. | +| `standard` | tudo em `read-only`, mais `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Somente leitura mais as ações cotidianas de quem está de plantão: executar consultas, reavaliar sessões, reconhecer incidentes e usar o assistente de IA. | | `admin` | todas as permissões atribuíveis | Controle total da organização. | -Os três conjuntos integrados são **imutáveis**; seus nomes sempre significam a mesma coisa, portanto `read-only`, `standard` e `admin` são seguros para referenciar em políticas e onboarding. Um operador pode criar **conjuntos personalizados** adicionais para modelar papéis específicos da sua organização (por exemplo, um papel de "autor de dashboard" ou "somente coletor"). +Os três conjuntos integrados são **imutáveis**; seus nomes sempre significam a mesma coisa, então `read-only`, `standard` e `admin` são seguros para referenciar em políticas e onboarding. Um operador pode criar **conjuntos personalizados** adicionais para modelar papéis específicos da sua organização (por exemplo, um papel de "autor de dashboard" ou um papel de "somente coletor"). -Os conjuntos são exibidos no dashboard e gerenciados pela API em `GET /permission-sets` (listar, restrito a `users:read`) e `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (criar, editar, excluir um conjunto personalizado, restrito a `settings:write`). Excluir ou editar um conjunto integrado é recusado. +Os conjuntos são exibidos no dashboard e gerenciados pela API em `GET /permission-sets` (listar, protegido por `users:read`) e `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (criar, editar, excluir um conjunto personalizado, protegido por `settings:write`). A exclusão ou edição de um conjunto integrado é recusada. A associação a conjuntos sustenta dois outros recursos: -- **`DEFAULT_USER_PERMISSIONS`** (a concessão pré-selecionada quando um admin abre **+ novo usuário**) tem como padrão o conjunto `standard`. -- **A flag `--set`** no `agenteye-orgctl` (gerenciamento de membros pelo operador) inicia um membro a partir de um conjunto nomeado, que você então ajusta com `--add` / `--remove`. +- **`DEFAULT_USER_PERMISSIONS`** (a concessão pré-selecionada quando um administrador abre **+ novo usuário**) tem como padrão o conjunto `standard`. +- **O flag `--set`** no `agenteye-orgctl` (gerenciamento de membros pelo operador) inicializa um membro a partir de um conjunto nomeado, que você depois ajusta com `--add` / `--remove`. -> **Nota:** Quando um conjunto inclui uma permissão que não pode ser atribuída a chaves (por exemplo, um conjunto personalizado que carrega `keys:update`), ao gerar uma chave a partir desse conjunto, os tokens não atribuíveis são descartados; caso contrário, o servidor rejeitaria a chave com HTTP 422. Usuários do dashboard não estão sujeitos a essa restrição. +> **Nota:** Quando um conjunto inclui uma permissão que não pode ser atribuída a chaves (por exemplo, um conjunto personalizado com `keys:update`), semear uma chave a partir desse conjunto descarta os tokens não atribuíveis; caso contrário, o servidor rejeitaria a chave com HTTP 422. Usuários do dashboard não estão sujeitos a essa restrição. --- -## Chave Admin Bootstrap +## Chave de Administração Bootstrap -A chave admin é a única credencial raiz que permite a um operador inicializar o acesso do zero: com ela você pode criar todas as outras chaves com escopo definido, convidar os primeiros usuários do dashboard e configurar a instância antes que qualquer outra chave exista. É a única chave que você não cria pela API de chaves; ela é provisionada a partir do ambiente para que o servidor seja acessível na primeira inicialização. +A chave de administração é a credencial raiz única que permite a um operador inicializar o acesso do zero: com ela você pode criar todas as outras chaves com escopo, convidar os primeiros usuários do dashboard e configurar a instância antes que qualquer outra chave exista. É a única chave que você não cria através da API de chaves; ela é provisionada a partir do ambiente para que o servidor seja acessível na primeira inicialização. -Defina a variável de ambiente `ADMIN_KEY` no servidor. A cada inicialização, o servidor faz um upsert desse valor como uma chave admin com todas as permissões. +Defina a variável de ambiente `ADMIN_KEY` no servidor. Em cada inicialização, o servidor faz um upsert desse valor como uma chave de administração com todas as permissões. Para rotacionar: altere `ADMIN_KEY` para um novo segredo e reinicie o servidor. @@ -157,17 +157,17 @@ Para rotacionar: altere `ADMIN_KEY` para um novo segredo e reinicie o servidor. ## Escopo por organização -**As organizações em si são criadas e gerenciadas fora de banda por um operador, não por esta API de chaves.** O ciclo de vida de organizações e membros (criar / renomear / excluir / purgar uma organização; adicionar / atualizar / remover um membro) é feito com o CLI **`agenteye-orgctl`**; não há API HTTP nem botão no dashboard para isso. O que *não* muda: **as API keys por organização ainda são criadas no dashboard (ou via esta API de chaves)** por membros da organização. +**As organizações em si são criadas e gerenciadas fora de banda por um operador, não através desta API de chaves.** O ciclo de vida de organizações e membros (criar/renomear/excluir/purgar uma organização; adicionar/atualizar/remover um membro) é feito com a CLI **`agenteye-orgctl`**; não há API HTTP nem botão no dashboard para isso. O que *permanece* inalterado: **chaves de API por organização ainda são criadas no dashboard (ou via esta API de chaves)** por membros da organização. -Em um deployment multi-organização, cada chave que um membro da organização cria (por esta API de chaves ou pela página **Keys** do dashboard) pertence a **uma organização** e só pode ler ou escrever os dados dessa organização; a organização é registrada na chave na criação e aplicada em cada requisição. As duas chaves bootstrap são a única exceção: a chave `admin` (gerada a partir de `ADMIN_KEY`) e a chave `dashboard-assistant` (gerada a partir de `AGENT_API_KEY`) têm **escopo de instância** (não carregam nenhuma organização). O dashboard se autentica com a chave `admin` para poder fazer proxy de requisições por organização em nome dos membros logados. Deployments de locatário único não precisam se preocupar com isso; todas as chaves pertencem à organização `default` integrada. +Em uma implantação multi-organização, cada chave que um membro da organização cria (através desta API de chaves ou da página **Keys** do dashboard) pertence a **uma organização** e só pode ler ou gravar dados dessa organização; a organização é registrada na chave no momento da criação e aplicada em cada requisição. As duas chaves bootstrap são a única exceção: a chave `admin` (semeada de `ADMIN_KEY`) e a chave `dashboard-assistant` (semeada de `AGENT_API_KEY`) têm **escopo de instância** (não carregam organização). O dashboard se autentica com a chave `admin` para poder fazer proxy de requisições por organização em nome dos membros logados. Implantações single-tenant não precisam se preocupar com isso; todas as chaves pertencem à organização `default` integrada. --- ## Criando Chaves -Use a chave admin (ou qualquer chave com permissão `keys:create`) para criar chaves com escopo adicional. +Use a chave de administração (ou qualquer chave com permissão `keys:create`) para criar chaves adicionais com escopo. -### Chave de coletor (somente ingestão) +### Chave do coletor (somente ingestão) ```bash curl -s -X POST http://your-server/keys \ @@ -180,7 +180,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### Chave de dashboard (somente leitura) +### Chave do dashboard (somente leitura) ```bash curl -s -X POST http://your-server/keys \ @@ -193,7 +193,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -Ao criar uma chave pela API HTTP, você fornece o valor de `key` por conta própria; escolha um segredo forte e armazene-o com segurança. (O dashboard funciona de forma diferente: ele gera um segredo forte para você e o exibe uma única vez na criação; veja [Gerenciamento de Chaves no Dashboard](#key-management-in-the-dashboard).) A resposta confirma que a chave foi criada: +Ao criar uma chave via API HTTP, você fornece o valor de `key` você mesmo; escolha um segredo forte e armazene-o com segurança. (O dashboard funciona de forma diferente: ele gera um segredo forte para você e o exibe uma única vez na criação; veja [Gerenciamento de chaves no dashboard](#key-management-in-the-dashboard).) A resposta confirma que a chave foi criada: ```json { @@ -217,9 +217,9 @@ Os segredos das chaves não são retornados nas respostas de listagem, apenas ID --- -## Desativando uma Chave +## Desabilitando uma Chave -Desativar revoga o acesso imediatamente sem excluir o registro da chave. +Desabilitar revoga o acesso imediatamente sem excluir o registro da chave. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -237,17 +237,17 @@ curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -A resposta inclui o novo segredo em texto simples, **exibido apenas uma vez**. +A resposta inclui o novo segredo em texto puro, **exibido apenas uma vez**. --- ## Gerenciamento de Chaves no Dashboard -A página **Keys** no dashboard fornece uma interface para todas as operações acima. Você precisa de uma chave com permissão `keys:read` para visualizar a lista, e `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` para as ações de criar / editar / desativar / regenerar, respectivamente. Editar as permissões de uma chave (`keys:update`) é separado de criar uma (`keys:create`), portanto você pode conceder a um operador a capacidade de criar chaves sem a capacidade de reescopar as existentes, ou vice-versa. A chave admin cobre todas essas ações. +A página **Keys** no dashboard fornece uma interface para todas as operações acima. Você precisa de uma chave com permissão `keys:read` para visualizar a lista, e `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` para as ações de criar/editar/desabilitar/regenerar respectivamente. Editar as permissões de uma chave (`keys:update`) é separado de criar uma (`keys:create`), então você pode conceder a um operador a capacidade de criar chaves sem a capacidade de redefinir o escopo de chaves existentes, ou vice-versa. A chave de administração cobre todas essas operações. -Ao criar uma chave pelo dashboard, você não fornece o segredo; o dashboard gera um segredo forte para você e o exibe **uma única vez** na criação. Copie-o imediatamente e armazene-o com segurança; ele nunca será exibido novamente, exatamente como em uma regeneração. Você ainda pode escolher as permissões da chave diretamente ou gerá-las a partir de um conjunto de permissões (veja abaixo). +Ao criar uma chave pelo dashboard, você não fornece o segredo; o dashboard gera um segredo forte para você e o exibe **uma única vez** na criação. Copie-o imediatamente e armazene-o com segurança; ele nunca é exibido novamente, exatamente como acontece com uma regeneração. Você ainda pode escolher as permissões da chave diretamente, ou semeá-las a partir de um conjunto de permissões (veja abaixo). -![A página API Keys: um card por chave mostrando seu nome, permissões concedidas e horário de criação, com ações de regenerar e desativar; chaves protegidas como `admin` são marcadas](/agenteye/images/api-keys.png) +![A página de Chaves de API: um cartão por chave mostrando seu nome, permissões concedidas e horário de criação, com ações de regeneração e desabilitação; chaves protegidas como `admin` são marcadas](/agenteye/images/api-keys.png) --- @@ -256,25 +256,25 @@ Ao criar uma chave pelo dashboard, você não fornece o segredo; o dashboard ger | Chave | Permissões | Usada por | |---|---|---| | `admin` (bootstrap via variável de ambiente `ADMIN_KEY`) | todas | Ops/configuração, e o dashboard (autentica com `ADMIN_KEY`, faz proxy de requisições de usuários com verificações de permissão) | -| Chave de coletor por host | `events:add` | Coletor em cada máquina de agente | -| `dashboard-assistant` (bootstrap via variável de ambiente `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistente de IA, gerado automaticamente, **protegido**; não pode ser editado pela API | +| Chave do coletor por host | `events:add` | Coletor em cada máquina de agente | +| `dashboard-assistant` (bootstrap via variável de ambiente `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Assistente de IA, semeado automaticamente, **protegido**; não pode ser editado através da API | | Chave de telemetria do assistente (opcional) | `events:add` | Auto-instrumentação do assistente de IA, se habilitada | -> **Nota:** A chave do assistente é **gerada automaticamente** pelo servidor a partir da variável de ambiente `AGENT_API_KEY` (o mesmo segredo que o agente apresenta como `AGENTEYE_API_KEY`); não há etapa manual de criação de chave nem envolvimento da chave admin. Suas permissões são fixadas no código-fonte para que o escopo não possa ser ampliado por má configuração: leitura de eventos / avaliações / dashboards, mais gravação de dashboards e leitura / gravação / execução de consultas para o fluxo de criação de "Pedir à IA para escrever uma consulta". Todo o SQL ainda passa pelo mesmo papel somente leitura e caminho SQL protegido que uma consulta escrita pelo usuário, portanto isso amplia a *superfície de criação*, não a superfície de dados; operações destrutivas (`queries:delete`, `dashboards:delete`) são deliberadamente mantidas fora da chave do assistente. Assim como a chave `admin`, ela é **protegida**: não pode ser desativada ou regenerada pela API de chaves, apenas rotacionada alterando `AGENT_API_KEY` e reiniciando. Os *usuários* do dashboard também precisam da permissão `agent:use` para ver e usar o assistente. Se você habilitar a auto-instrumentação, dê ao assistente uma chave separada somente com `events:add`. +> **Nota:** A chave do assistente é **semeada automaticamente** pelo servidor a partir da variável de ambiente `AGENT_API_KEY` (o mesmo segredo que o agente apresenta como `AGENTEYE_API_KEY`); não há etapa manual de criação de chave nem chave de administração envolvida. Suas permissões são fixadas no código-fonte para que o escopo não possa ser ampliado por má configuração: leitura de eventos/avaliações/dashboards, mais escrita de dashboards e leitura/escrita/execução de consultas para o fluxo de criação de consultas via IA. Todo SQL ainda passa pelo mesmo papel somente leitura e caminho SQL protegido que uma consulta escrita pelo usuário, portanto isso amplia a *superfície de criação*, não a superfície de dados; operações destrutivas (`queries:delete`, `dashboards:delete`) deliberadamente ficam fora da chave do assistente. Assim como a chave `admin`, ela é **protegida**: não pode ser desabilitada ou regenerada através da API de chaves, apenas rotacionada alterando `AGENT_API_KEY` e reiniciando. Os *usuários* do dashboard precisam adicionalmente da permissão `agent:use` para ver e usar o assistente. Se você habilitar a auto-instrumentação, forneça ao assistente uma chave separada somente com `events:add`. --- ## Notas de atualização e compatibilidade retroativa -Você só precisa disso se estiver atualizando uma instância existente; novos deployments podem pular esta seção. +Você só precisa destas informações se estiver atualizando uma instância existente; novas implantações podem ignorá-las. -> Quando Auditorias foi lançado, os beneficiários existentes tiveram seus escopos ampliados seguindo os mesmos formatos de papel que os alertas: todo usuário e conjunto de permissões que possuía `alerts:read` ganhou `audits:read`, e todo portador de `alerts:write` ganhou `audits:write`. As API keys existentes **não** foram ampliadas. Conceda `audits:*` a uma chave explicitamente se ela precisar da superfície de auditoria. +> Quando o módulo de Auditorias foi lançado, os titulares existentes tiveram suas permissões ampliadas seguindo os mesmos formatos de papel que os alertas: todo usuário e conjunto de permissões com `alerts:read` ganhou `audits:read`, e todo titular de `alerts:write` ganhou `audits:write`. As chaves de API existentes **não** foram ampliadas. Conceda `audits:*` a uma chave explicitamente se ela precisar da superfície de auditoria. -> Concessões armazenadas do token legado `alerts:ack` são interpretadas como `incidents:ack` para que os plantões mantenham o acesso sem precisar criar novas chaves. O token não é mais atribuível pelo editor de usuários do dashboard; a matriz oferece `incidents:ack` em seu lugar. +> Concessões armazenadas do token legado `alerts:ack` são interpretadas como `incidents:ack` para que os plantonistas mantenham o acesso sem precisar trocar de chave. O token não é mais atribuível pelo editor de usuários do dashboard; a matriz oferece `incidents:ack` em vez disso. --- ## Próximos passos - [Python SDK](/pt-br/agenteye/python-sdk): como o código do seu agente se autentica ao enviar eventos. -- [Segurança](/pt-br/agenteye/security): como funcionam o login, o controle de acesso e o isolamento de dados por organização. \ No newline at end of file +- [Segurança](/pt-br/agenteye/security): como o login, controle de acesso e isolamento de dados por organização funcionam. \ No newline at end of file diff --git a/docs/pt-br/agenteye/assistant.mdx b/docs/pt-br/agenteye/assistant.mdx index 628d1547..cedfce86 100644 --- a/docs/pt-br/agenteye/assistant.mdx +++ b/docs/pt-br/agenteye/assistant.mdx @@ -1,63 +1,63 @@ --- title: "Assistente de IA" -description: "Faça uma pergunta em português simples sobre os dados do seu agente e receba uma resposta com links diretos para as evidências." +description: "Faça perguntas sobre os dados dos seus agentes em linguagem natural e obtenha respostas com links diretos para as evidências." --- -Faça uma pergunta em linguagem natural sobre os dados do seu agente e receba uma resposta com links diretos para as evidências. Sem SQL para escrever, sem dashboards para vasculhar — o assistente do **Failproof AI Observability** é a forma mais rápida de qualquer pessoa da sua equipe obter respostas sobre seus agentes. +Faça perguntas sobre os dados dos seus agentes em linguagem natural e obtenha respostas com links diretos para as evidências. Sem SQL para escrever, sem dashboards para vasculhar — o assistente do **Failproof AI Observability** é a forma mais rápida para qualquer membro da sua equipe obter respostas sobre seus agentes. -![O assistente do Failproof AI Observability respondendo uma pergunta em linguagem natural dentro do dashboard, exibindo uma tabela de Atividade de Agentes ao vivo, um detalhamento de uso de modelos por agente e conclusões por escrito, com as consultas executadas mostradas inline](/agenteye/images/assistant.png) -*Pergunte em linguagem natural e receba uma resposta construída a partir dos seus próprios dados. Aqui, ele detalha quais agentes estão mais ocupados e quais modelos utilizam, e mostra as consultas executadas para que você possa verificar cada número.* +![O assistente do Failproof AI Observability respondendo a uma pergunta em linguagem natural dentro do dashboard, mostrando uma tabela de Atividade de Agentes ao vivo, um detalhamento de uso de modelo por agente e conclusões escritas, com as consultas executadas exibidas inline](/agenteye/images/assistant.png) +*Pergunte em linguagem natural e receba uma resposta construída a partir dos seus próprios dados. Aqui ele detalha quais agentes estão mais ocupados e quais modelos eles utilizam, e mostra as consultas executadas para que você possa verificar cada número.* Não há nada para aprender. Abra o chat, digite o que você quer saber e siga os links que ele retorna: ``` -Você: quais sessões tiveram erro hoje? -IA: 5 sessões tiveram erros hoje, das mais recentes para as mais antigas. Cada uma tem um link: +Você: quais sessões tiveram erros hoje? +IA: 5 sessões tiveram erros hoje, as mais recentes primeiro. Cada uma está vinculada: • checkout-agent 14:02 timeout de ferramenta • billing-agent 11:47 erro não tratado • ...e mais 3 -Você: resuma esta sessão (perguntado enquanto visualizava uma execução) +Você: resuma esta sessão (perguntado enquanto visualiza uma execução) IA: Esta execução teve 12 etapas em 3 ferramentas e falhou perto do fim quando uma - ferramenta de pagamento retornou um erro. Ela teve uma pontuação baixa na sua avaliação "resolved". - Links: a sessão, o evento que falhou e essa avaliação. + ferramenta de pagamento retornou um erro. Ela recebeu uma pontuação baixa na + avaliação "resolvido". Links: a sessão, o evento com falha e essa avaliação. ``` ## Pergunte e vá direto para a prova -Você para de adivinhar e para de escrever consultas. Pergunte "como está a qualidade em produção esta semana?", "quais sessões tiveram erro hoje?" ou "resuma esta sessão", e você obtém uma resposta direta em segundos — sem precisar montar uma consulta e interpretá-la por conta própria. +Você para de adivinhar e para de escrever consultas. Pergunte "como está a qualidade em produção esta semana?", "quais sessões tiveram erros hoje?" ou "resuma esta sessão," e obtenha uma resposta direta em segundos em vez de construir uma consulta e interpretá-la você mesmo. -Cada resposta vem acompanhada de suas fontes. O assistente linka as sessões exatas, as consultas salvas e os dashboards que usou para chegar à resposta, para que você possa clicar e confirmar em vez de simplesmente confiar na palavra dele. Ele também é **consciente da página**: pergunte sobre "esta sessão" enquanto estiver visualizando uma e ele já sabe a qual execução você se refere. Reabra qualquer conversa anterior pelo seletor de histórico e continue de onde parou. +Cada resposta vem com suas evidências. O assistente vincula exatamente as sessões, consultas salvas e dashboards que usou para chegar à resposta, para que você possa clicar e confirmar em vez de simplesmente confiar nele. Ele também é **consciente da página**: pergunte sobre "esta sessão" enquanto estiver visualizando uma e ele já sabe a qual execução você se refere. Reabra qualquer conversa anterior mais tarde pelo seletor de histórico e continue de onde parou. -## Transforme uma boa resposta em consulta salva ou dashboard +## Transforme uma boa resposta em uma consulta salva ou dashboard -Quando uma resposta vale a pena guardar, peça ao assistente para salvá-la. Ele elabora o SQL para uma consulta salva ou monta um dashboard a partir dessas consultas e, em seguida, exibe um card de **Aprovar / Rejeitar**. Nada é gravado até você clicar em Aprovar, então você tem a agilidade do "é só perguntar" com a palavra final sempre sendo sua. +Quando uma resposta vale a pena guardar, peça ao assistente para salvá-la. Ele elabora o SQL para uma consulta salva, ou monta um dashboard a partir dessas consultas, e então exibe um cartão de **Aprovar / Rejeitar**. Nada é gravado até que você clique em Aprovar, então você tem a agilidade do "só perguntar" com a última palavra sempre sendo sua. -Na página de **Queries**, ele vai além e assume o papel de autor de SQL: descreva a consulta que você quer ("mostrar taxa de erros por agente nos últimos 7 dias") e ele transmite o SQL diretamente para o editor, abrindo uma visualização de diff para que você possa **Aceitar** ou **Rejeitar** a alteração antes que ela seja aplicada. +Na página de **Consultas** ele vai um passo além e se torna um autor de SQL: descreva a consulta que você quer ("mostrar taxa de erros por agente nos últimos 7 dias") e ele transmite o SQL diretamente para o editor, abrindo uma visualização de diff para que você possa **Aceitar** ou **Rejeitar** a alteração antes que ela seja aplicada. -![A página de Queries do Observability e seu editor de SQL](/agenteye/images/query-lab.png) -*A página de Queries: é neste editor que o assistente transmite um rascunho de consulta, somente leitura, para você aceitar ou rejeitar.* +![A página de Consultas do Observability e seu editor SQL](/agenteye/images/query-lab.png) +*A página de Consultas: este editor é onde o assistente transmite um rascunho de consulta somente leitura para você aceitar ou rejeitar.* -Criar SQL por meio de perguntas aqui usa a permissão `queries:run`, a mesma por trás do botão **Run** do editor. O chat em todos os outros lugares requer `agent:use`. +Criar SQL perguntando aqui usa a permissão `queries:run`, a mesma por trás do botão **Executar** do editor. O chat em todos os outros lugares requer `agent:use`. ## Seguro para toda a equipe -Você pode abrir o assistente para todos sem se preocupar com o que ele pode acessar: +Você pode abrir o assistente para todos sem se preocupar com o que ele pode tocar: - **Ele lê apenas o que você já pode ver.** As respostas são limitadas às suas próprias permissões de leitura, portanto ele nunca amplia sua superfície de dados. -- **Toda escrita aguarda sua aprovação.** Consultas salvas e dashboards só são criados após seu clique explícito em Aprovar, e não há nenhuma configuração que desative essa barreira. -- **Ele nunca pode excluir nada.** Nenhuma ferramenta de exclusão está exposta e o assistente não possui permissão de exclusão. As exclusões permanecem em suas mãos, no dashboard. -- **Ele fica dentro da sua organização.** O assistente só visualiza a organização que você está acessando no momento. -- **Suas perguntas são suas.** Prompts e respostas ficam armazenados no seu próprio banco de dados do Observability; a análise de produto registra apenas metadados de uso, nunca o texto dos seus prompts. +- **Toda escrita aguarda sua confirmação.** Consultas salvas e dashboards são criados somente após seu clique explícito em Aprovar, e não existe configuração que desative essa proteção. +- **Ele nunca pode deletar nada.** Nenhuma ferramenta de exclusão é exposta e o assistente não possui permissão de exclusão. As exclusões permanecem em suas mãos, no dashboard. +- **Ele fica dentro da sua organização.** O assistente sempre vê apenas a organização que você está visualizando no momento. +- **Suas perguntas são suas.** Prompts e respostas ficam no seu próprio banco de dados do Observability; o analytics de produto registra apenas metadados de uso, nunca o texto dos seus prompts. ## Onde encontrá-lo -O assistente acompanha a borda direita de cada página dentro da sua organização (`//...`). Clique na barra lateral ou pressione `⌘J` / `Ctrl+J` para expandi-lo no painel de chat completo; arraste sua borda para redimensionar — a largura escolhida é lembrada entre recarregamentos. Você precisa da permissão **`agent:use`** para utilizá-lo; caso contrário, a barra estará desativada. Se ele ainda não foi ativado na sua instalação (é necessária uma conexão com um LLM), você verá uma barra silenciosa no lugar de um chat funcional. +O assistente fica na borda direita de cada página dentro da sua organização (`//...`). Clique na barra lateral, ou pressione `⌘J` / `Ctrl+J`, para expandi-lo no painel de chat completo, e arraste sua borda para redimensioná-lo; sua largura é lembrada entre recarregamentos. Você precisa da permissão **`agent:use`** para utilizá-lo, caso contrário a barra lateral fica acinzentada. Se ele ainda não foi ativado para sua implantação (é necessária uma conexão com um LLM), você verá uma barra lateral desativada no lugar de um chat funcional. ## Relacionados - [CLI e agentes](/pt-br/agenteye/cli-and-agents) -- [Queries](/pt-br/agenteye/queries) +- [Consultas](/pt-br/agenteye/queries) - [Dashboards](/pt-br/agenteye/dashboards) - [Suite de avaliação](/pt-br/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/pt-br/agenteye/audits.mdx b/docs/pt-br/agenteye/audits.mdx index abf2cecb..77304ac9 100644 --- a/docs/pt-br/agenteye/audits.mdx +++ b/docs/pt-br/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- -title: "Auditorias: seu analista de confiabilidade automático" -description: "O Failproof AI Observability vai atrás das falhas para as quais você nunca criou uma regra e entrega uma lista de tarefas priorizadas, com evidências, mostrando exatamente o que corrigir." +title: "Audits: seu analista de confiabilidade automático" +description: "O Failproof AI Observability vasculha suas falhas — inclusive as que você nunca escreveu uma regra para detectar — e entrega uma lista priorizada de exatamente o que corrigir, com evidências." --- -O Failproof AI Observability vai atrás das falhas para as quais você nunca criou uma regra e entrega uma lista de tarefas priorizadas, com evidências, mostrando exatamente o que corrigir. É como ter um analista vasculhando seus logs toda noite e deixando o resumo na sua mesa de manhã. +O Failproof AI Observability vasculha suas falhas — inclusive as que você nunca escreveu uma regra para detectar — e entrega uma lista priorizada de exatamente o que corrigir, com evidências. É como ter um analista passando pente-fino nos seus logs toda noite e deixando um resumo objetivo na sua mesa pela manhã.
-*Um tour de dois minutos: de uma execução agendada a uma correção que você pode tomar como ação.* +*Um tour de dois minutos: de uma execução agendada a uma correção que você pode agir imediatamente.* -![A página de Auditorias: jobs recorrentes que analisam suas sessões em busca de padrões de falha, cada um com um cronograma e sensibilidade](/agenteye/images/audits.png) -*Cada auditoria é um job recorrente que minera suas sessões e gera recomendações priorizadas com base em evidências.* +![A página de Audits: jobs recorrentes que varrem suas sessões em busca de padrões de falha, cada um com um agendamento e uma sensibilidade](/agenteye/images/audits.png) +*Cada audit é um job recorrente que minera suas sessões e produz recomendações priorizadas e embasadas em evidências.* ## Pare de adivinhar o que corrigir a seguir -Alertas detectam os problemas que você já sabe monitorar. Auditorias detectam os que você não sabe. Em um cronograma que você define, uma auditoria percorre todas as suas sessões de agente e caça os padrões que valem a pena corrigir — para que você gaste seu tempo agindo sobre os achados em vez de rolar logs esperando encontrá-los sozinho. +Alertas capturam os problemas que você já sabe que precisa monitorar. Audits capturam os que você ainda não sabe. Em um agendamento que você define, um audit lê todas as suas sessões de agente e caça os padrões que valem a pena corrigir — para que você gaste seu tempo agindo sobre os resultados, e não rolando logs na esperança de encontrar algo sozinho. Uma única execução vai atrás dos modos de falha que realmente quebram agentes em produção: -- **Clusters de erros**: a mesma falha se repetindo com uma causa raiz comum. -- **Desvio em relação a uma linha de base**: comportamento deslizando silenciosamente para fora de uma janela conhecida como boa. -- **Falha de objetivo em transcrições**: execuções que tecnicamente terminaram, mas nunca cumpriram o objetivo. -- **Uso incorreto de ferramentas**: a ferramenta errada, argumentos inválidos ou loops que desperdiçam chamadas. -- **Trade-offs de qualidade e custo**: onde você está pagando caro por uma saída que poderia obter mais barato. -- **Lacunas de cobertura**: comportamento que nenhuma avaliação ou alerta está monitorando. +- **Clusters de erros**: a mesma falha se repetindo sob uma causa raiz comum. +- **Desvio em relação a uma baseline**: comportamento se afastando silenciosamente de uma janela conhecida e saudável. +- **Falha de objetivo em transcrições**: execuções que tecnicamente terminaram, mas nunca cumpriram o que precisavam. +- **Uso incorreto de ferramentas**: ferramenta errada, argumentos ruins ou loops que desperdiçam chamadas. +- **Trade-offs de qualidade e custo**: onde você está pagando mais do que deveria por um resultado que poderia ser mais barato. +- **Lacunas de cobertura**: comportamentos que nenhum eval ou alerta está monitorando. -Você decide com que intensidade a auditoria analisa usando uma única configuração de **sensibilidade** (baixa, média ou alta), para que um agente barulhento de staging e um de produção mais restrito possam ser ajustados ao sinal que você deseja. +Você define a intensidade da análise com uma única configuração de **sensibilidade** (baixa, média ou alta), para que um agente barulhento de staging e um de produção bem controlado possam ser ajustados ao sinal que você quer receber. ## Cada recomendação vem com evidências -Você nunca precisa aceitar um achado por fé. Cada recomendação cita as sessões exatas de onde veio e o SQL que a trouxe à tona, para que você possa abrir as evidências e confirmar o problema com um clique em vez de ter que reverter uma afirmação. +Você nunca precisa aceitar um resultado pela fé. Cada recomendação cita as sessões exatas de onde veio e o SQL que a originou, para que você possa abrir a evidência e confirmar o problema com um clique, em vez de tentar reconstruir uma afirmação do zero. -Quando um achado é sobre uma credencial vazada, ele vai um passo além e vincula os eventos individuais que corresponderam. Clique em um e você cai naquele momento exato da sessão, já selecionado — não no topo de uma longa transcrição para rolar. O link nomeia o evento; ele nunca copia o segredo detectado para o achado, então ler um achado não é um segundo lugar onde sua credencial está escrita. Se um evento não estiver mais lá porque a sessão passou da sua janela de retenção, a página informa isso claramente em vez de deixá-lo se perguntando se clicou na coisa errada. +Quando um resultado é sobre uma credencial vazada, vai um passo além e vincula os eventos individuais que foram identificados. Clique em um e você vai direto para aquele momento exato na sessão, já selecionado — não para o topo de uma longa transcrição para rolar. O link identifica o evento; ele nunca copia o segredo detectado para dentro do resultado, então ler um resultado não é um segundo lugar onde sua credencial fica registrada. Se um evento não estiver mais lá porque a sessão ultrapassou sua janela de retenção, a página informa isso claramente, em vez de deixar você se perguntando se clicou na coisa errada. -É também o que mantém as auditorias honestas. O servidor verifica se cada sessão citada realmente existe e **descarta qualquer recomendação cujas evidências não se sustentem**, então a auditoria investiga, mas nunca inventa. O que aparece na sua lista é real, reproduzível e classificado por importância, com os maiores ganhos no topo. +Isso também é o que mantém os audits honestos. O servidor verifica que cada sessão citada realmente existe e **descarta qualquer recomendação cujas evidências não se sustentam** — então o audit investiga, mas nunca inventa. O que chega à sua lista é real, reproduzível e priorizado por relevância, com os maiores ganhos no topo. ## Transforme uma correção em uma proteção -Corrigir um problema é apenas metade da vitória. A outra metade é garantir que ele não volte silenciosamente. Cada achado traz um **atalho de um clique que cria um rascunho de alerta de recorrência**, pré-preenchido com um gatilho inicial razoável que você pode ajustar. Feche o achado, ative o alerta e, na próxima vez que esse padrão aparecer, você será notificado em vez de redescobri-lo em uma auditoria futura. +Corrigir um problema é só metade da vitória. A outra metade é garantir que ele não volte silenciosamente. Cada resultado traz um **atalho de um clique que cria um alerta de recorrência**, já preenchido com um gatilho inicial razoável que você pode ajustar. Feche o resultado, ative o alerta e, na próxima vez que aquele padrão aparecer, você é notificado em vez de redescobri-lo em um audit futuro. ## Onde encontrar -As auditorias ficam no dashboard em **`//audits`** (barra lateral em *analyze* > *audits*). Visualizar execuções e achados requer **`audits:read`**; criar, editar e triar auditorias requer **`audits:write`**. Defina o escopo e a cadência de uma auditoria e clique em **Run now** sempre que quiser resultados imediatamente em vez de esperar pela próxima execução agendada. +Os Audits ficam no dashboard em **`//audits`** (barra lateral em *analyze* → *audits*). Visualizar execuções e resultados requer **`audits:read`**; criar, editar e triar audits requer **`audits:write`**. Defina o escopo e a cadência de um audit, depois clique em **Run now** sempre que quiser resultados imediatamente, sem esperar o próximo ciclo agendado. ## Relacionados -- [Alertas](/pt-br/agenteye/alerts): seja notificado no momento em que um limite que você já conhece for ultrapassado. -- [Avaliações](/pt-br/agenteye/evaluations): pontue cada execução para que regressões de qualidade apareçam por conta própria. -- [Rastreamento de erros](/pt-br/agenteye/error-tracking): agrupe e acompanhe os erros que seus agentes lançam. -- [Incidentes](/pt-br/agenteye/incidents): acompanhe um problema encontrado por uma auditoria até a sua correção. \ No newline at end of file +- [Alerts](/pt-br/agenteye/alerts): seja notificado no momento em que um limite que você já conhece for ultrapassado. +- [Evaluations](/pt-br/agenteye/evaluations): pontue cada execução para que regressões de qualidade apareçam por conta própria. +- [Error tracking](/pt-br/agenteye/error-tracking): agrupe e acompanhe os erros que seus agentes lançam. +- [Incidents](/pt-br/agenteye/incidents): acompanhe um problema identificado por um audit até a sua correção. \ No newline at end of file diff --git a/docs/pt-br/agenteye/cli-and-agents.mdx b/docs/pt-br/agenteye/cli-and-agents.mdx index 38873d7f..7c035203 100644 --- a/docs/pt-br/agenteye/cli-and-agents.mdx +++ b/docs/pt-br/agenteye/cli-and-agents.mdx @@ -1,80 +1,80 @@ --- title: "CLI" -description: "Todo o seu deployment de Observabilidade do Failproof AI a um comando de distância." +description: "Todo o seu deployment do Failproof AI Observability a um comando de distância." --- -Todo o seu deployment de Observabilidade do Failproof AI a um comando de distância. Verifique produção, gere uma chave de API ou reconheça um incidente sem sair do terminal — e ainda automatize tudo isso em CI, ou deixe um agente de código fazer por você em linguagem natural. +Todo o seu deployment do Failproof AI Observability a um comando de distância. Verifique produção, gere uma chave de API ou reconheça um incidente sem sair do terminal — depois automatize tudo isso no CI ou deixe um agente de código fazer por você em linguagem natural. ```bash pipx install agenteye -agenteye login --email você@exemplo.com # um código de 6 dígitos chega na sua caixa de entrada -agenteye --json sessions --since 24h # todas as execuções de agentes das últimas 24h, mais recentes primeiro +agenteye login --email voce@exemplo.com # um código de 6 dígitos chega na sua caixa de entrada +agenteye --json sessions --since 24h # todas as execuções de agentes do último dia, mais recentes primeiro ``` *O CLI `agenteye` se comunica com o seu dashboard. É uma ferramenta diferente do coletor, que envia eventos para o servidor.* -## Todo o seu deployment, a um comando de distância +## Todo o seu deployment a um comando de distância -Pare de alternar entre abas para responder uma pergunta rápida. O CLI `agenteye` lê seus dados e administra sua organização a partir de um único binário, então uma verificação que antes exigia clicar pelo dashboard vira uma linha que você pode reexecutar, criar um alias ou colar em um runbook. Você tem quatro superfícies: +Pare de ficar alternando entre abas para responder a uma pergunta rápida. O CLI `agenteye` lê seus dados e administra sua organização a partir de um único binário, então uma verificação que antes exigia navegar pelo dashboard vira uma linha que você pode reutilizar, criar um alias ou colar em um runbook. Você tem quatro superfícies: - **Leia seus dados:** `sessions`, `events`, `evals` e `errors`, filtrados por tempo, agente e ambiente. - **Gerencie sua organização:** `keys`, `users`, `settings`, `alerts` e `incidents`. - **Execute análises:** SQL salvo mais um executor `query` ad-hoc sobre seus dados de eventos. -- **Consulte o assistente:** `agent ask` acessa o mesmo analista somente leitura com quem você conversa no dashboard. +- **Consulte o assistente:** `agent ask` acessa o mesmo analista somente leitura com o qual você conversa no dashboard. -Instale uma vez com `pipx`, faça login com um código de 6 dígitos enviado por e-mail e está pronto. A sessão dura cerca de um dia; reexecute `agenteye login` quando expirar. Use-o para verificar produção, provisionar uma chave ou triagear um incidente ativo — tudo sem abrir um navegador: +Instale uma vez com `pipx`, faça login com um código de 6 dígitos enviado por e-mail e você está pronto. A sessão dura cerca de um dia; execute `agenteye login` novamente quando expirar. Use-o para verificar produção pontualmente, provisionar uma chave ou triar um incidente ativo, tudo sem abrir um navegador: ```bash agenteye errors --since 24h --aggregate # o que está quebrando, agrupado por tipo de erro agenteye incidents list --state firing # o que está pegando fogo agora -agenteye keys create ci --add events:add # uma chave que só pode enviar eventos, secret exibido uma vez +agenteye keys create ci --add events:add # uma chave que só pode enviar eventos, segredo exibido uma vez ``` -Um hábito importante: opções globais como `--json` vão antes do comando. `agenteye --json sessions` está correto; `agenteye sessions --json` não está. +Um comportamento importante: opções globais como `--json` vão antes do comando. `agenteye --json sessions` está correto; `agenteye sessions --json` não está. -## Automatize, integre ao CI +## Automatize e integre ao CI -Todo comando aceita `--json`, e isso muda tudo. JSON limpo vai para stdout enquanto status e avisos para humanos vão para stderr, então uma captura com `--json` vai direto para o `jq` sem nenhuma linha extra para remover. É isso que torna o CLI igualmente útil para você no terminal e para um agente de código analisando a saída: +Todos os comandos aceitam `--json`, e isso muda tudo. O JSON limpo vai para stdout enquanto status e avisos legíveis por humanos vão para stderr, então uma captura com `--json` pode ser passada diretamente para o `jq` sem precisar remover linhas extras. É isso que torna o CLI igualmente útil para você no prompt e para um agente de código analisando a saída: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -Ele foi construído para rodar de forma não supervisionada. Prompts de confirmação são ignorados automaticamente quando não há terminal conectado, então nada trava em um pipeline, e todo comando retorna um código de saída significativo: `0` sucesso, `4` não autenticado, `5` sem permissão (a mensagem nomeia qual, por exemplo `alerts:write`), `3` dashboard inacessível. Um script pode ramificar em um `4` para reautenticar ou em um `5` para dizer exatamente o que pedir a um administrador, em vez de falhar silenciosamente. +Ele foi desenvolvido para rodar sem supervisão. Prompts de confirmação são pulados automaticamente quando não há terminal conectado, então nada trava em um pipeline, e cada comando retorna um código de saída significativo: `0` sucesso, `4` não autenticado, `5` permissão insuficiente (a mensagem a identifica, por exemplo `alerts:write`), `3` dashboard inacessível. Um script pode ramificar em `4` para reautenticar ou em `5` para saber exatamente o que solicitar a um administrador, em vez de falhar às cegas. -## Deixe um agente de código conduzir em linguagem natural +## Deixe um agente de código operar em linguagem natural -Ainda melhor: você não deveria precisar lembrar nenhuma dessas flags. A **CLI skill** é uma pequena pasta Agent Skill chamada `agenteye-cli` que ensina um agente de código como Claude Code ou Codex a conduzir o CLI a partir de pedidos em linguagem natural. Pergunte "tem algo quebrado hoje?" e o agente escolhe o comando, executa como você e responde em prosa. +Melhor ainda: você não deveria precisar lembrar nenhuma dessas flags. A **habilidade de CLI** é uma pequena pasta de Agent Skill chamada `agenteye-cli` que ensina um agente de código como Claude Code ou Codex a operar o CLI a partir de solicitações em linguagem natural. Pergunte "tem alguma coisa quebrada hoje?" e o agente escolhe o comando, executa como você e responde em prosa. -Para Claude Code, coloque a pasta `agenteye-cli` em `~/.claude/skills/` e ela é descoberta automaticamente. O Failproof AI Observability fornece a pasta; não há nada extra para instalar, pois ela apenas conduz o CLI que você já instalou. Faça login você mesmo primeiro: a skill não consegue completar o login por código enviado por e-mail por você. +Para o Claude Code, coloque a pasta `agenteye-cli` em `~/.claude/skills/` e ela é descoberta automaticamente. O Failproof AI Observability fornece a pasta; não há nada extra para instalar, pois ela apenas opera o CLI que você já instalou. Faça login você mesmo primeiro: a habilidade não consegue completar o login por código enviado por e-mail em seu lugar. -Como o agente executa o CLI como você, ele pode fazer tudo que seu login permite, tanto leituras quanto escritas: criar chaves, alterar configurações, resolver incidentes. O prompt "tem certeza?" do CLI não é acionado para um agente, então a skill foi escrita para declarar o comando exato e aguardar sua aprovação antes de qualquer alteração. Você é a etapa de confirmação. +Como o agente executa o CLI como você, ele pode fazer tudo que seu login permite, leituras e escritas inclusive: criar chaves, alterar configurações, resolver incidentes. O prompt de confirmação do CLI não é acionado para um agente, então a habilidade foi escrita para declarar o comando exato e aguardar sua aprovação antes de qualquer alteração. Você é a etapa de confirmação. ```text -você Por que a sessão run-001 falhou? +você Por que a sessão run-001 falhou? -agente Executando: agenteye --json events --session-id run-001 --all - O checkout-agent encontrou um TimeoutError em sua terceira chamada de ferramenta. +agente Executando: agenteye --json events --session-id run-001 --all + O checkout-agent encontrou um TimeoutError em sua terceira chamada de ferramenta. ``` -Leituras são instantâneas, e toda escrita pausa para você: +Leituras permanecem instantâneas, e toda escrita pausa para você: ```text -você Dê ao CI uma chave que só possa enviar eventos. +você Crie uma chave para o CI que só possa enviar eventos. -agente Isso cria uma chave de API. Vou executar: - agenteye keys create ci --add events:add - Pode prosseguir? +agente Isso cria uma chave de API. Vou executar: + agenteye keys create ci --add events:add + Pode prosseguir? -você sim +você sim -agente Feito. Chave "ci" criada com events:add apenas. O secret é exibido uma vez, então guarde agora. +agente Pronto. Chave "ci" criada com events:add apenas. O segredo é exibido uma vez, então guarde agora. ``` -## Relacionado +## Relacionados - [Referência do CLI](/pt-br/agenteye/cli): todos os comandos, flags e formatos JSON. - [Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes): padrões `jq` para copiar e colar e tratamento de códigos de saída. -- [CLI agent skill](/pt-br/agenteye/cli-skill): instale e execute a skill `agenteye-cli`. -- [Assistente de IA](/pt-br/agenteye/assistant): o analista no dashboard com quem `agent ask` se comunica. \ No newline at end of file +- [Habilidade de CLI para agentes](/pt-br/agenteye/cli-skill): instale e execute a habilidade `agenteye-cli`. +- [Assistente de IA](/pt-br/agenteye/assistant): o analista integrado ao dashboard que `agent ask` utiliza. \ No newline at end of file diff --git a/docs/pt-br/agenteye/cli-recipes.mdx b/docs/pt-br/agenteye/cli-recipes.mdx index 6c1d2280..1e76ca6b 100644 --- a/docs/pt-br/agenteye/cli-recipes.mdx +++ b/docs/pt-br/agenteye/cli-recipes.mdx @@ -1,41 +1,41 @@ --- title: "Receitas de CLI para agentes" -description: "Padrões de consulta prontos para copiar e receitas jq que transformam dados de sessão, evento e avaliação em algo que um script ou agente de codificação pode automatizar." +description: "Padrões de consulta prontos para uso e receitas de jq que transformam dados de sessão, evento e avaliação em algo que um script ou agente de código pode automatizar." --- -Extraia dados de sessão, evento e avaliação (e dispare reavaliações) diretamente de um script ou agente de codificação, com JSON limpo no stdout que pode ser redirecionado diretamente para `jq`. Essas receitas transformam os dados da Failproof AI Observability em algo que um usuário de terminal ou um agente de codificação com IA (Claude Code, Cursor) pode consultar e automatizar, sem precisar clicar no dashboard. +Busque dados de sessão, evento e avaliação (e acione reavaliações) diretamente de um script ou agente de código, com JSON limpo no stdout que conecta diretamente ao `jq`. Estas receitas transformam os dados do Failproof AI Observability em algo que um usuário de terminal ou um agente de código IA (Claude Code, Cursor) pode consultar e automatizar, sem precisar clicar pelo painel. -Os padrões abaixo estão prontos para copiar e usar com a CLI da Failproof AI Observability (`agenteye`). Para instalação, autenticação e a lista completa de opções, consulte [CLI](/pt-br/agenteye/cli); execute `agenteye -h` ou `agenteye -h` para a ajuda integrada. +Os padrões abaixo estão prontos para copiar e colar para o CLI do Failproof AI Observability (`agenteye`). Para instalação, autenticação e a lista completa de opções, veja [CLI](/pt-br/agenteye/cli); execute `agenteye -h` ou `agenteye -h` para a ajuda integrada. ## Regras de ouro -1. **As opções globais vão *antes* do comando.** `agenteye --json sessions` está correto; `agenteye sessions --json` não está. As opções globais são `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Passe `--json` sempre que for parsear a saída.** Os dados vão para o **stdout** como JSON; mensagens de status e erros para humanos vão para o **stderr**, mantendo o stdout limpo para redirecionar ao `jq`. -3. **Ramifique pelo código de saída**, não pelo texto do stderr: `0` ok · `1` erro inesperado · `2` argumentos inválidos · `3` não foi possível alcançar o dashboard · `4` não autenticado ou sessão expirada · `5` permissão ausente · `6` recurso não encontrado. +1. **Opções globais vão *antes* do comando.** `agenteye --json sessions` está correto; `agenteye sessions --json` não está. As opções globais são `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Passe `--json` sempre que for interpretar a saída.** Os dados vão para o **stdout** como JSON; status humano e erros vão para o **stderr**, então o stdout fica limpo para conectar ao `jq`. +3. **Ramifique pelo código de saída**, não pelo texto do stderr: `0` ok · `1` erro inesperado · `2` argumentos inválidos · `3` não consegue acessar o painel · `4` não autenticado ou sessão expirada · `5` permissão ausente · `6` recurso não encontrado. 4. **Explore com `-h`.** Cada comando documenta seus filtros, formatos de valores e estrutura JSON. -## Configuração inicial +## Configuração única ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # para não repetir --base-url -agenteye login --email you@example.com # cole o código enviado por e-mail; válido por ~24h +agenteye login --email you@example.com # cole o código enviado por e-mail; válido ~24h ``` ## Confirme a autenticação antes de executar tarefas -`whoami` nunca retorna erro em caso de sessão ausente ou expirada; ele reporta `logged_in:false` em vez disso, para que um agente possa verificar o estado de autenticação com segurança. (Ainda pode sair com código diferente de zero se nenhuma URL base estiver definida ou se o dashboard estiver inacessível.) +`whoami` nunca retorna erro por sessão ausente ou expirada; ele reporta `logged_in:false` em vez disso, para que um agente possa verificar o estado de autenticação com segurança. (Ainda pode sair com código diferente de zero se nenhuma URL base estiver definida ou se o painel estiver inacessível.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then - echo "Não autenticado. Execute: agenteye login" >&2; exit 1 + echo "Not authenticated. Run: agenteye login" >&2; exit 1 fi ``` ## Encontre sessões com falha ou pontuação baixa ```bash -# sessões nas últimas 24h cujas avaliações retornaram erro +# sessões nas últimas 24h cuja avaliação retornou erro agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' # avaliações com pontuação <= 0.5 em helpfulness, para um agente específico @@ -43,35 +43,35 @@ agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -A filtragem por pontuação fica no **`evals`**, não em `sessions`. `--score KEY:MIN..MAX` é repetível e combinado com AND; qualquer um dos limites é opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Você pode passar até 20 filtros de pontuação por requisição; mais que isso retorna HTTP 400. `sessions` compartilha os filtros `--env`, `--status`, `--agent-id`, `--session-id` e de intervalo de tempo com `evals`, mas não possui `--score`. +A filtragem por pontuação fica em **`evals`**, não em `sessions`. `--score KEY:MIN..MAX` é repetível e combinado com AND; qualquer limite é opcional (`..0.5` significa ≤ 0,5, `0.9..` significa ≥ 0,9). Você pode passar até 20 filtros de pontuação por requisição; mais do que isso retorna HTTP 400. `sessions` compartilha os filtros `--env`, `--status`, `--agent-id`, `--session-id` e de intervalo de tempo com `evals`, mas não tem `--score`. ## Leia uma sessão do início ao fim -Não existe um único comando `session show`. Combine o histórico de eventos com a avaliação da sessão: +Não existe um único comando `session show`. Combine o registro de eventos com a avaliação da sessão: ```bash -# a avaliação mais recente da sessão (status + pontuações) +# avaliação mais recente da sessão (status + pontuações) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' # todos os eventos da execução (aumente --limit para uma varredura completa) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# apenas as chamadas de ferramenta em uma sessão (--full é obrigatório para obter o payload bruto) +# apenas as chamadas de ferramenta em uma sessão (--full é necessário para obter o payload bruto) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **Nota:** Por padrão, `events` lê um feed rápido sem payload. Cada evento carrega um `summary` de uma linha calculado pelo servidor, além de flags como `is_error` e contagens de tokens, mas `payload` retorna como `{}`. Para obter o payload bruto, adicione `--full` (ou `--fields payload`). O feed completo é mais lento em grande escala, então mantenha-o delimitado: combine `--full` com um único `--session-id`. +> **Observação:** Por padrão, `events` lê um feed rápido sem payload. Cada evento carrega um `summary` de uma linha calculado pelo servidor, além de flags como `is_error` e contagens de tokens, mas `payload` retorna como `{}`. Para obter o payload bruto, adicione `--full` (ou `--fields payload`). O feed completo é mais lento em escala, então mantenha-o delimitado: combine `--full` com um único `--session-id`. ## Busque tudo (paginação) -Os resultados são os mais recentes primeiro e paginados por cursor. +Os resultados são ordenados do mais recente para o mais antigo e paginados por cursor. ```bash -# de uma vez: busca até 500 linhas em páginas de 200 +# de uma vez: busca até 500 linhas em páginas de 200 linhas agenteye --json events --session-id run-001 --limit 500 --all > events.json -# paginação manual: repasse o next_cursor +# paginação manual: passe next_cursor de volta page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -79,14 +79,14 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## Reduza a saída com --fields -Restrinja as chaves (tanto na tabela quanto em `--json`) para diminuir o que um agente precisa ler. +Restrinja as chaves (tanto na tabela quanto com `--json`) para diminuir o que um agente precisa ler. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Nomes de campos desconhecidos são rejeitados (saída `2`) com a lista de campos válidos — uma forma simples de descobri-los. +Nomes de campo desconhecidos são rejeitados (saída `2`) com a lista de nomes válidos — uma forma prática de descobrir os nomes dos campos. ## Descubra valores de filtro válidos @@ -101,19 +101,19 @@ agenteye --json list score_filters | jq -r '.values[]' # KEY válida para --sco Se você pertence a mais de uma organização, escolha o tenant ativo no login (ele é salvo): ```bash -agenteye login --org acme --email you@corp.com # define o tenant na mesma etapa do login +agenteye login --org acme --email you@corp.com # define o tenant no mesmo passo do login agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # sobrescreve para um único comando +agenteye --org globex --json sessions --since 24h # substitui para um único comando ``` -Um login em múltiplas organizações sem `--org` sai com código diferente de zero e exibe as organizações disponíveis para escolha. +Um login com múltiplas organizações sem `--org` sai com código diferente de zero e exibe as organizações disponíveis para escolha. ## Provisione uma chave de API para o SDK/coletor ```bash -# o segredo é exibido UMA ÚNICA VEZ; com --json, ele fica no campo .key +# o segredo é exibido UMA VEZ; com --json, fica no campo .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # rotacionar; agenteye keys disable ci-bot --yes para revogar +agenteye keys regenerate ci-bot --yes # rotaciona; use agenteye keys disable ci-bot --yes para revogar ``` ## Execute uma consulta salva ou ad-hoc @@ -123,7 +123,7 @@ agenteye --json query run --sql "select count(*) from analytics.events" | jq '.r agenteye --json query run errs --arg prod | jq '.rows' # uma consulta salva + um argumento posicional $1 ``` -## Faça a triagem de um incidente sem interação +## Faça triagem de um incidente de forma não interativa ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **Nota:** Mutações pulam automaticamente a confirmação interativa quando `--json` está ativo ou quando o stdin não é um TTY, para que agentes nunca fiquem travados; passe `--yes`/`-y` para pulá-la explicitamente em outros contextos. +> **Observação:** Mutações ignoram automaticamente o prompt de confirmação quando usadas com `--json` ou quando o stdin não é um TTY, para que os agentes nunca fiquem travados; passe `--yes`/`-y` para ignorá-lo explicitamente em outros contextos. ## Tratamento de código de saída em um script @@ -140,10 +140,10 @@ agenteye incidents resolve "$id" --yes out=$(agenteye --json sessions --since 1h) || code=$? case "${code:-0}" in 0) echo "$out" | jq '.sessions | length' ;; - 4) echo "Sessão expirada - execute 'agenteye login'." >&2 ;; - 5) echo "Permissão ausente (peça ao administrador a permissão evaluations:read)." >&2 ;; - 3) echo "Dashboard inacessível - verifique a URL." >&2 ;; - *) echo "Erro inesperado (saída ${code})." >&2 ;; + 4) echo "Session expired - run 'agenteye login'." >&2 ;; + 5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;; + 3) echo "Dashboard unreachable - check the URL." >&2 ;; + *) echo "Unexpected error (exit ${code})." >&2 ;; esac ``` @@ -158,22 +158,22 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` exibido uma única vez) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` exibido uma vez) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | | create/update/delete (qualquer) | o objeto do recurso, ou `{"deleted": true, "id"}` para exclusões | | falha (qualquer, com `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` no stdout | -- Cada item de **evento** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Observe que `payload` é `{}` a menos que você solicite o feed completo com `--full` (ou `--fields payload`). +- Cada item de **evento** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Note que `payload` é `{}` a menos que você solicite o feed completo com `--full` (ou `--fields payload`). - Cada item de **avaliação** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Cada item de **sessão** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -O `--fields` de cada comando aceita exatamente os nomes de campos do seu próprio item. O conjunto difere entre `sessions` e `evals`, então um nome válido para um pode ser rejeitado pelo outro. +O `--fields` de cada comando aceita exatamente os nomes de campo do seu próprio item. O conjunto difere entre `sessions` e `evals`, então um nome válido para um pode ser rejeitado pelo outro. ## Próximos passos - [CLI](/pt-br/agenteye/cli): instalação, autenticação e a referência completa de opções para cada comando. -- [Skill de agente CLI](/pt-br/agenteye/cli-skill): empacote essas receitas como uma skill que seu agente de codificação pode carregar. -- [Chaves de API](/pt-br/agenteye/api-keys): crie e delimite as chaves com as quais a CLI, o SDK e o coletor se autenticam. -- [Python SDK](/pt-br/agenteye/python-sdk): envie eventos para a Failproof AI Observability para que haja dados que essas receitas possam consultar. \ No newline at end of file +- [Skill de agente CLI](/pt-br/agenteye/cli-skill): empacote estas receitas como uma skill que seu agente de código pode carregar. +- [Chaves de API](/pt-br/agenteye/api-keys): crie e defina o escopo das chaves com as quais o CLI, o SDK e o coletor se autenticam. +- [Python SDK](/pt-br/agenteye/python-sdk): envie eventos para o Failproof AI Observability para que haja dados para estas receitas consultarem. \ No newline at end of file diff --git a/docs/pt-br/agenteye/cli-skill.mdx b/docs/pt-br/agenteye/cli-skill.mdx index 3c9b15fb..688dc0e3 100644 --- a/docs/pt-br/agenteye/cli-skill.mdx +++ b/docs/pt-br/agenteye/cli-skill.mdx @@ -1,67 +1,67 @@ --- -title: "Skill de Agente CLI de Observabilidade do Failproof AI" -description: "Pergunte ao seu agente de codificação 'tem algo quebrado hoje?' e deixe-o responder com dados ao vivo do Failproof AI Observability, sem precisar memorizar nenhum comando." +title: "Failproof AI Observability CLI Agent Skill" +description: "Pergunte ao seu agente de codificação \"algo está quebrado hoje?\" e deixe-o responder com seus dados ao vivo do Failproof AI Observability, sem precisar memorizar comandos." --- -Pergunte ao seu agente de codificação *"tem algo quebrado hoje?"* e deixe-o responder com seus dados ao vivo do Failproof AI Observability, sem precisar memorizar nenhum comando. A **skill de CLI do Failproof AI Observability** (`agenteye-cli`) é uma *Agent Skill*: uma pequena pasta de instruções que um agente de codificação como Claude Code ou Codex carrega sob demanda. Ela ensina o agente a operar seu deployment de Observability por meio do [`agenteye` CLI](/pt-br/agenteye/cli) a partir de pedidos em linguagem natural como *"dê ao CI uma chave que só pode enviar eventos"* ou *"confirme o incidente ativo e atribua a mim."* +Pergunte ao seu agente de codificação *"algo está quebrado hoje?"* e deixe-o responder com seus dados ao vivo do Failproof AI Observability, sem precisar memorizar comandos. A **Failproof AI Observability CLI skill** (`agenteye-cli`) é uma *Agent Skill*: uma pequena pasta de instruções que um agente de codificação como Claude Code ou Codex carrega sob demanda. Ela ensina o agente a operar seu deployment de Observability através da [`agenteye` CLI](/pt-br/agenteye/cli) a partir de solicitações em linguagem natural como *"dê ao CI uma chave que só possa enviar eventos"* ou *"reconheça o incidente ativo e atribua-o a mim."* -Ela **não** é um serviço nem um binário separado; não há nada para implantar. Ela funciona sobre o CLI que você já tem instalado: o agente executa `agenteye --json …`, analisa o JSON limpo e responde em texto. Tudo o que ela pode fazer, você mesmo poderia fazer digitando os mesmos comandos. +Ela **não** é um serviço nem um binário separado; não há nada para fazer deploy. Ela funciona sobre a CLI que você já instalou: o agente executa `agenteye --json …`, analisa o JSON limpo e responde em prosa. Tudo o que ela pode fazer, você poderia fazer digitando os mesmos comandos. --- ## Como ela se relaciona com as outras interfaces do Failproof AI Observability -O Failproof AI Observability oferece quatro formas de acessar os mesmos dados e controles. Elas se complementam: +O Failproof AI Observability oferece quatro maneiras de acessar os mesmos dados e controles. Elas se complementam: | Interface | O que é | Onde roda | Use quando | |---|---|---|---| -| **[CLI](/pt-br/agenteye/cli)** | Referência de comandos e flags para `agenteye` | Seu terminal | Você quer executar ou automatizar um comando específico | -| **[Receitas de CLI](/pt-br/agenteye/cli-recipes)** | Padrões de `jq`/pipeline para copiar e colar | Seu terminal / scripts | Você está integrando o CLI em automações | -| **CLI skill** (este doc) | Uma interface em linguagem natural sobre o CLI | Seu agente de codificação, na sua estação de trabalho | Você quer *simplesmente perguntar* e deixar o agente escolher o comando | -| **[Evaluator skill](/pt-br/agenteye/evaluator-skill)** | Uma skill irmã que projeta e constrói seu serviço de pontuação | Seu agente de codificação, na sua estação de trabalho | Você quer *produzir* pontuações de avaliação em vez de lê-las | +| **[CLI](/pt-br/agenteye/cli)** | A referência de comandos/flags do `agenteye` | Seu terminal | Você quer executar ou automatizar um comando específico | +| **[Receitas da CLI](/pt-br/agenteye/cli-recipes)** | Padrões `jq`/pipeline para copiar e colar | Seu terminal / scripts | Você está integrando a CLI em automações | +| **CLI skill** (este doc) | Uma porta de entrada em linguagem natural para a CLI | Seu agente de codificação, na sua estação de trabalho | Você quer *simplesmente perguntar* e deixar o agente escolher o comando | +| **[Evaluator skill](/pt-br/agenteye/evaluator-skill)** | Uma skill irmã que projeta e constrói seu serviço de scoring | Seu agente de codificação, na sua estação de trabalho | Você quer *produzir* pontuações de avaliação em vez de lê-las | | **[Python SDK skill](/pt-br/agenteye/python-sdk-skill)** | Uma skill irmã que instrumenta seu agente para emitir telemetria | Seu agente de codificação, na sua estação de trabalho | Você quer que seu agente *produza* os eventos que esta skill lê | -| **[Assistente de IA no dashboard](/pt-br/agenteye/assistant)** | Um chat embutido no dashboard | No servidor (dentro do dashboard) | Você quer Q&A dentro do dashboard sobre seus dados | +| **[Assistente de IA no dashboard](/pt-br/agenteye/assistant)** | Um chat embutido no dashboard | No servidor (dentro do dashboard) | Você quer fazer perguntas sobre seus dados diretamente no dashboard | -A skill em si não tem privilégios próprios; ela apenas transforma suas palavras em chamadas de CLI que rodam como você: +A skill em si não tem privilégios próprios; ela apenas transforma suas palavras em chamadas de CLI executadas como você: ```mermaid flowchart TD - YOU["você: 'confirme o incidente ativo'"] --> AGENT["agente de codificação (Claude Code / Codex)
carrega a skill agenteye-cli"] + YOU["você: 'reconheça o incidente ativo'"] --> AGENT["agente de codificação (Claude Code / Codex)
carrega a skill agenteye-cli"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|sua sessão de CLI autenticada| API["API do dashboard de Observabilidade"] + CLI -->|sua sessão autenticada da CLI| API["API do dashboard de Observability"] ``` ### vs. o assistente de IA no dashboard: uma distinção importante -Essas são duas ferramentas diferentes com alcances de ação muito distintos: +São duas ferramentas diferentes com impactos muito distintos: -- O **assistente de IA no dashboard** ([AI assistant](/pt-br/agenteye/assistant)) é um chat embutido no dashboard, com suporte do serviço de agente. Ele é **somente leitura mais criação com aprovação**: pode rascunhar queries salvas e dashboards, mas toda escrita pausa para sua aprovação explícita com um clique, e ele nunca exclui nada. É restrito pela permissão `agent:use` e só enxerga dados da organização que você está visualizando. -- A **CLI skill** roda na *sua* estação de trabalho dentro do *seu* agente de codificação e aciona o `agenteye` CLI **como você**. Ela pode executar toda a **superfície do CLI, incluindo mutações** (criar/rotacionar/desativar chaves de API, alterar configurações da org, resolver incidentes, excluir queries salvas), limitada apenas pelas permissões do seu login no CLI. Trate-a com exatamente o mesmo cuidado com que trataria executar esses comandos manualmente. +- O **assistente de IA no dashboard** ([AI assistant](/pt-br/agenteye/assistant)) é um chat embutido no dashboard, respaldado pelo serviço de agente. Ele é **somente leitura mais criação com aprovação**: pode rascunhar queries salvas e dashboards, mas toda escrita pausa aguardando sua aprovação explícita por clique, e nunca deleta. Ele é controlado pela permissão `agent:use` e só acessa dados da organização que você está visualizando. +- A **CLI skill** roda na *sua* estação de trabalho dentro do *seu* agente de codificação e controla a `agenteye` CLI **como você**. Ela pode executar a **superfície completa da CLI, incluindo mutações** (criar/rotacionar/desabilitar chaves de API, alterar configurações da organização, resolver incidentes, deletar queries salvas), limitada apenas pelas permissões do seu login na CLI. Trate-a com exatamente o mesmo cuidado que você teria ao executar esses comandos manualmente. --- ## Pré-requisitos -1. O **`agenteye` CLI instalado** e no `PATH` (veja a referência do [CLI](/pt-br/agenteye/cli): `pipx install agenteye`). +1. A **`agenteye` CLI instalada** e no `PATH` (veja a referência da [CLI](/pt-br/agenteye/cli): `pipx install agenteye`). 2. Sua **URL do dashboard** configurada (`AGENTEYE_DASHBOARD_URL`, ou o agente passa `--base-url`). -3. Uma **sessão autenticada**: execute `agenteye login` você mesmo primeiro. A skill **não consegue** completar o login por código enviado por e-mail para você; ela dirá para executar `agenteye login` se a sessão estiver ausente ou expirada (código de saída do CLI `4`). +3. Uma **sessão autenticada**: execute `agenteye login` você mesmo primeiro. A skill **não consegue** concluir o login via código de uso único enviado por e-mail; ela instruirá você a executar `agenteye login` caso a sessão esteja ausente ou expirada (código de saída da CLI `4`). --- -## Onde obter +## Onde encontrá-la -A skill está publicada na coleção pública de skills do Failproof AI: +A skill está publicada na coleção pública de skills da Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -Não há nenhuma restrição de acesso — o repositório é público e a skill não precisa de nenhuma credencial própria, pois ela apenas aciona o `agenteye` CLI **público** contra o *seu* dashboard, usando a sessão com a qual *você* fez login. Você não precisa pedir permissão a ninguém. +Nada nela é restrito — o repositório é público e a skill não precisa de credenciais próprias, pois apenas executa a `agenteye` CLI **pública** contra *seu* dashboard, usando a sessão com a qual *você* fez login. Você não precisa pedir permissão a ninguém. -Observe que ela é publicada como sua própria pasta e **não** está dentro do pacote `pipx install agenteye`, portanto não procure por ela lá. +Observe que ela vem como sua própria pasta e **não** está dentro do pacote `pipx install agenteye`, portanto não a procure lá. ## Instalando a skill -O caminho mais rápido é o CLI [`skills`](https://skills.sh), que busca a pasta e a coloca onde seu agente procura: +O caminho mais rápido é a CLI [`skills`](https://skills.sh), que baixa a pasta e a coloca onde seu agente procura: ```bash # Claude Code, somente este projeto @@ -74,7 +74,7 @@ npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -Depois gerencie como qualquer outra skill: +Depois gerencie-a como qualquer outra skill: ```bash npx skills list -a claude-code # o que está instalado @@ -84,18 +84,18 @@ npx skills remove agenteye-cli # remover Prefere instalar manualmente? Uma Agent Skill é apenas uma pasta contendo um `SKILL.md` (mais referências opcionais), então copiá-la também funciona: -- **Claude Code**: coloque a pasta `agenteye-cli/` em `~/.claude/skills/` (todos os projetos) ou `/.claude/skills/` (somente aquele repositório). Claude Code a descobre automaticamente — verifique com a lista `/skills`, ou simplesmente faça uma pergunta que corresponda à sua descrição. -- **Codex (OpenAI)**: o Codex lê o mesmo `SKILL.md`. O `agents/openai.yaml` incluído define `allow_implicit_invocation: true`, então o Codex seleciona a skill automaticamente quando uma tarefa combina; caso contrário, invoque-a explicitamente como `$agenteye-cli`. +- **Claude Code**: coloque a pasta `agenteye-cli/` em `~/.claude/skills/` (todos os projetos) ou `/.claude/skills/` (somente aquele repositório). Claude Code a descobre automaticamente — verifique com a lista `/skills`, ou simplesmente faça uma pergunta que corresponda à sua descrição. +- **Codex (OpenAI)**: o Codex lê o mesmo `SKILL.md`. O `agents/openai.yaml` incluído define `allow_implicit_invocation: true`, portanto o Codex seleciona a skill automaticamente quando uma tarefa corresponde; caso contrário, invoque-a explicitamente como `$agenteye-cli`. --- -## Segurança: mutações NÃO solicitam confirmação quando um agente executa o CLI +## Segurança: mutações NÃO exibem confirmação quando um agente executa a CLI -> **Aviso:** Leia isso antes de permitir que um agente faça alterações. +> **Atenção:** Leia isto antes de permitir que um agente faça alterações. -O `agenteye` CLI normalmente pergunta *"tem certeza?"* antes de uma ação destrutiva. Ele **pula automaticamente essa confirmação sempre que não está conectado a um terminal (que é exatamente como um agente de codificação o executa), e `--json` também a pula.** Portanto, o aviso de segurança **não** será acionado para o agente. +A `agenteye` CLI normalmente pergunta *"tem certeza?"* antes de uma ação destrutiva. Ela **pula automaticamente essa confirmação quando não está conectada a um terminal (que é exatamente como um agente de codificação a executa), e `--json` também a pula.** Portanto, a solicitação de confirmação **não** será acionada para o agente. -A skill foi escrita para compensar isso: ela é instruída a declarar o comando exato que irá executar e obter seu **OK explícito antes de qualquer alteração de estado**. Mantenha essa disciplina. Quando você aciona o Failproof AI Observability por meio de um agente, *você* é a etapa de confirmação. Os comandos que alteram estado para ficar atento: +A skill foi escrita para compensar isso: ela é instruída a declarar o comando exato que executará e obter sua aprovação explícita **antes de qualquer alteração de estado**. Mantenha essa disciplina. Quando você opera o Failproof AI Observability por meio de um agente, *você* é a etapa de confirmação. Os comandos que alteram estado e merecem atenção: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` @@ -108,23 +108,23 @@ A skill foi escrita para compensar isso: ela é instruída a declarar o comando Tudo em **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) é somente leitura e não altera nada. -Como o agente age **como você**, ele só pode fazer o que seu login tem permissão para fazer; as permissões são resolvidas **por org** (veja [API keys](/pt-br/agenteye/api-keys)). Um comando para o qual você não tem permissão retorna o código de saída `5` com o nome exato da permissão faltante, para que o agente possa informar precisamente o que pedir a um administrador em vez de falhar de forma opaca. +Como o agente age **como você**, ele só pode fazer o que seu login tem permissão para fazer; as permissões são resolvidas **por organização** (veja [API keys](/pt-br/agenteye/api-keys)). Um comando para o qual você não tem permissão retorna código de saída `5` com o nome exato da permissão necessária, para que o agente possa dizer precisamente o que solicitar a um administrador em vez de falhar de forma opaca. --- ## O que você pode perguntar -Veja como é uma interação real — uma leitura, depois uma alteração que aguarda sua confirmação: +Veja como é uma interação real — uma leitura, depois uma alteração que aguarda sua aprovação: ```text -você ▸ Tem algo quebrado no último dia? +você ▸ Algo está quebrado no último dia? agente▸ Executando: agenteye --json errors --since 24h --aggregate 3 tipos de erro nas últimas 24h. O maior é TimeoutError (18 ocorrências, todas no checkout-agent), depois RateLimited (5). - Quer ver as sessões com falha de TimeoutError? + Quer as sessões com falha para TimeoutError? -você ▸ Dê ao CI uma chave que só pode enviar eventos. +você ▸ Dê ao CI uma chave que só possa enviar eventos. agente▸ Isso cria uma chave de API. Vou executar: agenteye keys create ci --add events:add @@ -132,28 +132,28 @@ agente▸ Isso cria uma chave de API. Vou executar: você ▸ sim -agente▸ Concluído. Chave "ci" criada com events:add apenas. - O segredo é exibido apenas uma vez, então guarde agora. Não consigo reexibi-lo. +agente▸ Pronto. Chave "ci" criada somente com events:add. + O segredo é exibido apenas uma vez, guarde-o agora. Não posso reimprimí-lo. ``` A skill mapeia cada intenção em linguagem natural para o comando `agenteye` correto, descobrindo valores válidos primeiro (`list `, `whoami`) para não adivinhar, e declarando o comando exato antes de qualquer alteração. Mais exemplos: -- *"Tem algo quebrado / falhando nas últimas 24 horas?"* → `errors --since 24h --aggregate`, depois um resumo. +- *"Algo está quebrado / falhando nas últimas 24 horas?"* → `errors --since 24h --aggregate`, depois um detalhamento. - *"Por que a sessão `run-001` falhou?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *"Como está a qualidade esta semana?"* → `evals --aggregate --since 7d`, depois detalhes das execuções com baixa pontuação. -- *"Dê ao CI uma chave que só pode enviar eventos."* → `keys create ci --add events:add` (declara o comando, depois cria e captura o segredo único). -- *"Quem tem acesso? Torne a Dana somente leitura."* → `users list` → `users update dana@… --permission-set read-only` (após confirmar com você). -- *"Confirme o incidente ativo e atribua a mim."* → `incidents list --state firing` → `incidents ack ` / `incidents assign você@…`. +- *"Como a qualidade está evoluindo esta semana?"* → `evals --aggregate --since 7d`, depois análise das execuções com baixa pontuação. +- *"Dê ao CI uma chave que só possa enviar eventos."* → `keys create ci --add events:add` (declara o comando, cria a chave e captura o segredo de uso único). +- *"Quem tem acesso? Deixe a Dana somente leitura."* → `users list` → `users update dana@… --permission-set read-only` (após confirmação com você). +- *"Reconheça o incidente ativo e atribua-o a mim."* → `incidents list --state firing` → `incidents ack ` / `incidents assign você@…`. -Para os comandos exatos, flags e estruturas JSON por trás dessas interações, veja a referência do [CLI](/pt-br/agenteye/cli) e as [receitas de CLI para agentes](/pt-br/agenteye/cli-recipes). +Para os comandos exatos, flags e formatos JSON por trás desses exemplos, consulte a referência da [CLI](/pt-br/agenteye/cli) e as [receitas de CLI para agentes](/pt-br/agenteye/cli-recipes). --- ## Próximos passos -- **[CLI](/pt-br/agenteye/cli)**: referência completa de comandos e flags para `agenteye`. -- **[Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes)**: padrões de `jq` para copiar e colar e tratamento de códigos de saída. +- **[CLI](/pt-br/agenteye/cli)**: referência completa de comandos e flags do `agenteye`. +- **[Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes)**: padrões `jq` para copiar e colar e tratamento de códigos de saída. - **[Evaluator agent skill](/pt-br/agenteye/evaluator-skill)**: a skill irmã, para construir o avaliador cujas pontuações `agenteye evals` lê. -- **[Python SDK agent skill](/pt-br/agenteye/python-sdk-skill)**: a skill irmã, para instrumentar um agente para que ele emita a telemetria que `agenteye` lê. +- **[Python SDK agent skill](/pt-br/agenteye/python-sdk-skill)**: a skill irmã, para instrumentar um agente e fazê-lo emitir a telemetria que o `agenteye` lê. - **[AI assistant](/pt-br/agenteye/assistant)**: o assistente no dashboard (não confundir com esta skill de terminal). -- **[API keys](/pt-br/agenteye/api-keys)**: o modelo de permissões por org que delimita o que a skill pode fazer. \ No newline at end of file +- **[API keys](/pt-br/agenteye/api-keys)**: o modelo de permissões por organização que limita o que a skill pode fazer. \ No newline at end of file diff --git a/docs/pt-br/agenteye/cli.mdx b/docs/pt-br/agenteye/cli.mdx index 9e17758b..ba6f23d5 100644 --- a/docs/pt-br/agenteye/cli.mdx +++ b/docs/pt-br/agenteye/cli.mdx @@ -1,34 +1,33 @@ --- title: "CLI" -description: "Controle toda a Observabilidade do Failproof AI pelo terminal ou por um script: sem precisar acessar o dashboard." +description: "Gerencie toda a Observabilidade do Failproof AI pelo terminal ou por um script: sem precisar acessar o dashboard." --- - -Controle toda a Observabilidade do Failproof AI pelo terminal ou por um script: sem precisar acessar o dashboard. O CLI `agenteye` consulta seus dados (sessões, logs de eventos, avaliações) e administra sua organização (chaves de API, usuários, configurações, alertas, incidentes, consultas salvas), sendo ideal para automatizar verificações, integrar a Observabilidade ao CI ou permitir que um agente de codificação inspecione o ambiente de produção. Todos os comandos suportam o flag `--json`, funcionando igualmente bem para uso interativo no terminal ou para um agente de codificação (Claude Code, Cursor) que executa o comando e processa o resultado. +Gerencie toda a Observabilidade do Failproof AI pelo terminal ou por um script: sem precisar acessar o dashboard. A CLI `agenteye` consulta seus dados (sessões, logs de eventos, avaliações) e administra sua organização (chaves de API, usuários, configurações, alertas, incidentes, consultas salvas), sendo ideal para automatizar verificações, integrar a Observabilidade ao CI ou permitir que um agente de codificação inspecione o ambiente de produção. Todos os comandos suportam o flag `--json`, funcionando igualmente bem para uso interativo no terminal ou para agentes de codificação (Claude Code, Cursor) que executam comandos e processam o resultado. Com um único binário você pode: - **Ler seus dados**: `sessions`, `events`, `evals`, `errors` (filtre por tempo, agente, ambiente, pontuação). - **Gerenciar sua organização**: `keys`, `users`, `settings`, `alerts`, `incidents`. - **Executar análises**: SQL salvo e um executor de consultas ad-hoc (`query`). -- **Consultar o assistente de IA**: o mesmo analista somente leitura disponível no dashboard (`agent`). +- **Conversar com o assistente de IA**: o mesmo analista somente leitura disponível no dashboard (`agent`). -> **Nota:** Este é o CLI `agenteye`, uma ferramenta diferente do daemon coletor (`agenteye-collector`). O CLI se comunica com o seu dashboard; o coletor envia eventos para o servidor. +> **Nota:** Esta é a CLI `agenteye`, uma ferramenta diferente do daemon coletor (`agenteye-collector`). A CLI se comunica com o seu dashboard; o coletor envia eventos para o servidor. --- ## Início rápido -Do zero ao seu primeiro resultado em quatro linhas. Aponte o CLI para o seu dashboard, faça login, confirme quem você é e, em seguida, busque as execuções das últimas 24 horas: +Do zero ao primeiro resultado em quatro linhas. Aponte a CLI para o seu dashboard, faça login, confirme sua identidade e busque as execuções do último dia: ```bash pipx install agenteye agenteye --base-url https://agenteye.example.com login --email you@example.com # código de 6 dígitos enviado por e-mail -agenteye whoami # confirma usuário + org ativa +agenteye whoami # confirma usuário + organização ativa agenteye --json sessions --since 24h # uma linha por execução do agente, últimas 24h ``` -O último comando imprime um objeto JSON com as sessões mais recentes (as mais novas primeiro, limitado a 50 por padrão). Encadeie com `jq` para filtrar, ou remova `--json` para obter uma tabela colorida em caixas. Cada linha contém o status da execução e, se um avaliador atribuiu uma pontuação, as métricas correspondentes (abreviadas aqui): +O último comando imprime um objeto JSON com as sessões mais recentes (mais novas primeiro, limitado a 50 por padrão). Redirecione para `jq` para filtrar, ou remova `--json` para ver uma tabela colorida e formatada. Cada linha traz o status da execução e, se um avaliador a pontuou, as métricas correspondentes (abreviadas aqui): ```json { @@ -48,13 +47,13 @@ O último comando imprime um objeto JSON com as sessões mais recentes (as mais } ``` -O restante desta página explica cada parte: [instalação](#installation) em ambiente isolado, [autenticação](#authentication), [configuração](#configuration), as [convenções globais](#global-options--conventions) compartilhadas por todos os comandos e a [referência completa de comandos](#command-reference). +O restante desta página explica cada parte: [instalação](#installation) isolada, [autenticação](#authentication), [configuração](#configuration), as [convenções globais](#global-options--conventions) compartilhadas por todos os comandos e a [referência completa de comandos](#command-reference). --- ## Instalação -O CLI é um pacote público no PyPI chamado **`agenteye`**. Instale-o em um ambiente isolado para que sempre tenha suas próprias dependências: +A CLI é um pacote público do PyPI chamado **`agenteye`**. Instale-o em um ambiente isolado para que sempre tenha suas próprias dependências: ```bash pipx install agenteye @@ -69,13 +68,13 @@ agenteye --version agenteye --help ``` -> **Nota:** O SDK Python de Observabilidade do Failproof AI também usa o nome de distribuição `agenteye`. Instalar o CLI com `pipx` ou `uv tool` (em vez de `pip install` em um virtualenv compartilhado) evita conflitos entre os dois. Um simples `pip install agenteye` só é adequado se o SDK não estiver instalado no mesmo ambiente. +> **Nota:** O SDK Python de Observabilidade do Failproof AI também usa o nome de distribuição `agenteye`. Instalar a CLI com `pipx` ou `uv tool` (em vez de `pip install` em um virtualenv compartilhado) evita conflitos entre os dois. Um simples `pip install agenteye` só é adequado se o SDK não estiver instalado no mesmo ambiente. --- ## Autenticação -O CLI autentica no **dashboard** com um código de uso único enviado por e-mail: +A CLI autentica no **dashboard** com um código único enviado por e-mail: ```bash agenteye login --email you@example.com @@ -85,13 +84,13 @@ agenteye login --email you@example.com O token de sessão é armazenado em `~/.agenteye/cli.json` (legível apenas por você, modo `0600`) e é válido por 24 horas por padrão. Quando expirar, execute `agenteye login` novamente. ```bash -agenteye whoami # exibe o usuário atual, a org ativa e as permissões +agenteye whoami # exibe o usuário atual, a organização ativa e as permissões agenteye logout # revoga a sessão e limpa o token armazenado ``` -`whoami` nunca retorna erro por sessão ausente ou expirada; em vez disso, retorna `logged_in: false`, para que um script ou agente possa verificar o estado de autenticação com segurança (ainda pode sair com código diferente de zero se nenhuma URL base estiver definida ou se o dashboard estiver inacessível). +`whoami` nunca retorna erro quando a sessão está ausente ou expirada; em vez disso, reporta `logged_in: false`, permitindo que um script ou agente verifique o estado de autenticação com segurança (ainda pode sair com código não zero se nenhuma URL base estiver configurada ou se o dashboard estiver inacessível). -**Requisitos:** seu e-mail deve ter permissão para acessar o dashboard (solicite ao administrador do Failproof AI Observability), e o dashboard deve estar acessível na sua URL base (consulte [Configuração](#configuration)). Se você solicitar um código e ele não chegar, provavelmente seu e-mail ainda não está habilitado para acesso ao dashboard. +**Requisitos:** seu e-mail precisa ter permissão para acessar o dashboard (solicite ao administrador da Observabilidade do Failproof AI), e o dashboard deve estar acessível na sua URL base (veja [Configuração](#configuration)). Se você solicitou um código e ele não chegou, seu e-mail provavelmente ainda não está habilitado para acesso ao dashboard. --- @@ -100,13 +99,13 @@ agenteye logout # revoga a sessão e limpa o token armazenado Se sua conta pertence a mais de uma organização, escolha a ativa **no momento do login**; ela é salva e usada em todos os comandos subsequentes: ```bash -agenteye login --org acme # autentica e define o tenant ativo em uma etapa -agenteye orgs list # as orgs que você pode acessar (a ativa está marcada) +agenteye login --org acme # autentica e define o tenant ativo em uma única etapa +agenteye orgs list # as organizações que você pode acessar (a ativa está marcada) agenteye orgs switch globex # altera o padrão salvo -agenteye --org globex sessions # substituição para um único comando +agenteye --org globex sessions # substitui para um único comando ``` -Se você pertence a exatamente uma organização, ela é selecionada automaticamente e você pode ignorar `--org` completamente. Se pertencer a várias e não escolher uma, o CLI lista-as e solicita que você reexecute com `--org `. A org ativa é enviada ao dashboard em cada requisição, e suas permissões são resolvidas **por organização**; `agenteye whoami` exibe a org ativa, suas permissões nela e todas as suas associações. +Se você pertence a exatamente uma organização, ela é selecionada automaticamente e você pode ignorar `--org` completamente. Se pertencer a várias e não escolher uma, a CLI as lista e solicita que você execute novamente com `--org `. A organização ativa é enviada ao dashboard em cada requisição, e suas permissões são resolvidas **por organização**; `agenteye whoami` mostra a organização ativa, suas permissões nela e todos os seus vínculos. --- @@ -115,14 +114,14 @@ Se você pertence a exatamente uma organização, ela é selecionada automaticam | Configuração | Flag | Variável de ambiente | Padrão | |---|---|---|---| | URL base do dashboard | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **obrigatório** (sem padrão) | -| Org/tenant ativa | `--org` | `AGENTEYE_ORG` | definida no login; salva em `~/.agenteye/cli.json` | +| Organização/tenant ativo | `--org` | `AGENTEYE_ORG` | escolhido no login; salvo em `~/.agenteye/cli.json` | | Token de sessão | `--token` | `AGENTEYE_CLI_TOKEN` | de `~/.agenteye/cli.json` | | Saída JSON | `--json` | `AGENTEYE_CLI_JSON` | desativado | | Ignorar verificação TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | desativado (salvo no login) | -| Timeout da requisição (segundos) | `--timeout` | _(nenhum)_ | 30 | -| Desativar telemetria de uso | _(nenhum)_ | `AGENTEYE_ANALYTICS_DISABLED` (ou `DO_NOT_TRACK`) | telemetria está desativada no momento; nada é enviado | +| Timeout da requisição (segundos) | `--timeout` | _(nenhuma)_ | 30 | +| Desativar telemetria de uso | _(nenhuma)_ | `AGENTEYE_ANALYTICS_DISABLED` (ou `DO_NOT_TRACK`) | telemetria atualmente desativada; nada é enviado | -A ordem de resolução é **flag → variável de ambiente → arquivo de configuração**. Não há padrão; você deve apontar o CLI para o seu dashboard, seja por comando (`--base-url https://agenteye.example.com`) ou uma vez via variável de ambiente (também é salvo após o primeiro `login`): +A ordem de resolução é **flag → variável de ambiente → arquivo de configuração**. Não há valor padrão; você deve apontar a CLI para o seu dashboard, seja por comando (`--base-url https://agenteye.example.com`) ou uma única vez via variável de ambiente (também é salvo após o primeiro `login`): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com @@ -130,43 +129,43 @@ export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com O diretório de configuração respeita `AGENTEYE_HOME` (a mesma convenção usada pelo SDK e pelo coletor); se definido, `cli.json` fica em `$AGENTEYE_HOME/cli.json`. -### TLS autoassinado ou interno +### TLS auto-assinado ou interno -Se o seu dashboard usa HTTPS com um certificado autoassinado ou interno (por exemplo, o nome de host bruto de um balanceador de carga), a verificação TLS rejeita a conexão com um erro `CERTIFICATE_VERIFY_FAILED`. Use `--insecure` para ignorar a verificação de certificado: +Se o seu dashboard for servido via HTTPS com um certificado auto-assinado ou interno (por exemplo, um hostname de load balancer bruto), a verificação TLS o rejeitará com um erro `CERTIFICATE_VERIFY_FAILED`. Passe `--insecure` para ignorar a verificação de certificado: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` é **salvo em `cli.json` quando você faz login**, portanto os comandos posteriores ignoram a verificação automaticamente; você não precisa repetir o flag. Use `--secure` para uma chamada verificada pontual, ou para restaurar a verificação no próximo login. O CLI exibe um aviso no stderr antes de qualquer comando que contate o dashboard com a verificação desativada. Ignorar a verificação remove a proteção contra ataques man-in-the-middle; certifique-se de confiar no caminho de rede até o seu dashboard (VPN, sub-rede privada etc.) antes de depender disso. +`--insecure` é **salvo em `cli.json` quando você faz login**, portanto comandos posteriores ignoram a verificação automaticamente; você não precisa repetir o flag. Passe `--secure` para uma chamada verificada pontual, ou para salvar a verificação ativada no próximo login. A CLI exibe um aviso no stderr antes de qualquer comando que contate o dashboard com a verificação desativada. Ignorar a verificação remove a proteção contra ataques man-in-the-middle; certifique-se de confiar no caminho de rede até o seu dashboard (VPN, sub-rede privada, etc.) antes de depender disso. --- ## Telemetria e privacidade -> **Nota:** O CLI distribuído **não envia telemetria de uso hoje.** Um interruptor mestre está ativo, portanto nada é transmitido independentemente do seu ambiente. A seção abaixo descreve a capacidade de desativação para quando a telemetria vier a ser habilitada. +> **Nota:** A CLI distribuída **não envia telemetria de uso atualmente.** Um interruptor mestre está ativado, então nada é transmitido independentemente do seu ambiente. A seção abaixo descreve a funcionalidade de opt-out para o caso de a telemetria ser habilitada no futuro. -Mesmo quando habilitada, a telemetria seria **apenas análises de uso anônimo**, nunca seus dados de agente, sessão ou eventos: +Mesmo quando habilitada, a telemetria seria **apenas análise de uso anônima**, nunca seus dados de agente, sessão ou eventos: -- **Nenhum dado de agente, sessão ou evento sai da sua infraestrutura.** Apenas o uso do CLI seria reportado: o nome do comando e subcomando (ex.: `keys create`), os **nomes** dos flags usados (nunca seus valores), status de sucesso/saída e duração, além de um evento por ação para mutações (ex.: `api_key_created`, `query_run`) contendo apenas nomes/enums estáticos e contagens aproximadas. Sua URL do dashboard, token de sessão, e-mail, slug da org, IDs de recursos, SQL, segredos de chaves e filtros de consulta **nunca** seriam enviados. Os operadores seriam identificados apenas por um ID interno opaco, nunca por e-mail. -- **Desative antecipadamente** definindo `AGENTEYE_ANALYTICS_DISABLED=1` no ambiente do CLI (o CLI também respeita a convenção entre ferramentas `DO_NOT_TRACK=1`). Isso entra em vigor no momento em que a telemetria for ativada, permitindo que um ambiente voltado para privacidade permaneça desativado permanentemente. -- Se a telemetria fosse habilitada, o CLI enviaria diretamente para o PostHog (`https://us.i.posthog.com`); uma máquina com esse host bloqueado simplesmente não enviaria nada e o CLI não seria afetado. +- **Nenhum dado de agente, sessão ou evento jamais sai da sua infraestrutura.** Apenas o uso da CLI seria reportado: o nome do comando e subcomando (ex.: `keys create`), os **nomes** dos flags utilizados (nunca seus valores), status de sucesso/saída e duração, além de um evento por ação para mutações (ex.: `api_key_created`, `query_run`) contendo apenas nomes/enums estáticos e contagens aproximadas. Sua URL do dashboard, token de sessão, e-mail, slug da organização, IDs de recursos, SQL, segredos de chaves e filtros de consulta **nunca** seriam enviados. Os operadores seriam identificados apenas por um ID interno opaco, nunca por e-mail. +- **Faça opt-out antecipado** definindo `AGENTEYE_ANALYTICS_DISABLED=1` no ambiente da CLI (a CLI também respeita a convenção entre ferramentas `DO_NOT_TRACK=1`). Isso entra em vigor no momento em que a telemetria for ativada, permitindo que ambientes com requisitos de privacidade permaneçam com opt-out permanentemente. +- Se a telemetria fosse habilitada, a CLI enviaria diretamente para o PostHog (`https://us.i.posthog.com`); uma máquina com esse host bloqueado não enviaria nada silenciosamente e a CLI não seria afetada. --- ## Opções globais e convenções -Leia esta seção uma vez; ela se aplica a todos os comandos. +Leia isto uma vez; aplica-se a todos os comandos. -- **As opções globais vêm ANTES do comando.** `agenteye --json sessions` está correto; `agenteye sessions --json` é um erro de uso. As opções globais são `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` e `--no-color`. -- **`--json` imprime JSON puro no stdout e nada mais.** Linhas de status, avisos e erros vão para o **stderr**, para que uma captura do stdout com `--json` permaneça limpa para encadear com `jq`, mesmo quando uma linha de status é exibida. Sem `--json`, você obtém uma visualização colorida em caixas para leitura humana. -- **Descubra com `--help`.** Cada comando e subcomando tem `--help` (e o alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. O help de nível superior também lista os códigos de saída e as opções globais. Não há uma superfície global legível por máquina; use `--help` por comando, além de `agenteye query schema` e `agenteye settings schema` específicos de domínio para esses dois registros. -- **Confirmações são ignoradas automaticamente para scripts e agentes.** Comandos de criação/atualização/exclusão exibem "tem certeza?" em um terminal interativo, mas **ignoram esse prompt automaticamente sob `--json` ou quando o stdin não é um TTY** (um TTY é uma sessão de terminal interativa; um pipe ou um runner de CI não é), para que scripts e agentes nunca fiquem travados. Use `--yes`/`-y` para ignorá-lo explicitamente. Como o prompt não será exibido para um agente, ele deve confirmar ações destrutivas com o humano antes de executar. -- **Paginação:** os resultados são os mais novos primeiro e usam paginação por cursor (cada página retorna um token para buscar a próxima). `--limit N` (alias `-n`) limita as linhas e **tem padrão de 50**; `--all` pagina automaticamente (em blocos de 200 linhas) **até `--limit`**, portanto um `--all` simples ainda para em 50. Para uma varredura completa, passe um limite alto explícito: `--all --limit 1000`. `--page-size N` controla o bloco por requisição (máximo 200); `--cursor ` retoma a partir do `next_cursor` de uma página anterior. -- **Filtros de tempo:** `--since` aceita uma janela relativa: `15m`, `1h`, `6h`, `24h`, `7d` ou `all` (os presets do dashboard). Para um intervalo mais longo ou personalizado (como os últimos 30 dias), use `--from`/`--to`: timestamps UTC explícitos no formato ISO-8601 **com `T` e timezone** (ex.: `2026-06-01T00:00:00Z`) que substituem `--since`. Um valor separado por espaço ou sem timezone é um erro de uso. -- **`--fields a,b,c`** (em `events`, `sessions`, `evals`, `errors`) restringe a saída a essas chaves, tanto na tabela quanto no `--json`. Nomes desconhecidos são rejeitados com a lista válida, uma forma barata de descobrir os nomes de campos. -- **`--file payload.json`** (ou `--file -` para ler do stdin) fornece um corpo de requisição JSON completo quando um recurso tem uma forma complexa (em `alerts create/update`, `settings set` e `users create/update`). SQL de consultas salvas usa `--sql @file.sql` em vez disso. -- **Filtros com múltiplos valores** são separados por vírgula → correspondidos como um conjunto (união dentro de um filtro, AND entre filtros): `--event-type tool_use,tool_result`. As opções Click não são variádicas, portanto `--add a b` não funciona. Use `--add a,b`, repita o flag (`--add a --add b`) ou use aspas (`--add "a b"`). +- **Opções globais vão ANTES do comando.** `agenteye --json sessions` é correto; `agenteye sessions --json` é um erro de uso. As opções globais são `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` e `--no-color`. +- **`--json` imprime JSON puro no stdout, e nada mais.** Linhas de status, avisos e erros para humanos vão para o **stderr**, então uma captura de stdout com `--json` permanece limpa para redirecionar para `jq` mesmo quando uma linha de status é exibida. Sem `--json`, você obtém uma visão formatada e colorida para leitura humana. +- **Descubra com `--help`.** Todos os comandos e subcomandos têm `--help` (e o alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. O help de nível superior também lista os códigos de saída e as opções globais. Não há uma listagem global legível por máquina; use `--help` por comando, mais `agenteye query schema` e `agenteye settings schema` para esses dois registros. +- **Confirmações são ignoradas automaticamente em scripts e agentes.** Comandos de criação/atualização/exclusão solicitam confirmação em um terminal interativo, mas **ignoram automaticamente esse prompt sob `--json` ou sempre que stdin não for um TTY** (um TTY é uma sessão de terminal interativa; um pipe ou executor de CI não é), para que scripts e agentes nunca fiquem travados. Passe `--yes`/`-y` para ignorar explicitamente. Como o prompt não aparecerá para um agente, ele deve confirmar ações destrutivas com o usuário antes. +- **Paginação:** os resultados são os mais recentes primeiro e paginados por cursor (cada página retorna um token que você usa para buscar a próxima). `--limit N` (alias `-n`) limita as linhas e **tem padrão 50**; `--all` pagina automaticamente (em blocos de 200 linhas) **até `--limit`**, então um `--all` simples ainda para em 50. Para uma varredura completa, passe um limite alto explícito: `--all --limit 1000`. `--page-size N` controla o bloco por requisição (máx. 200); `--cursor ` retoma a partir do `next_cursor` de uma página anterior. +- **Filtros de tempo:** `--since` aceita uma janela relativa: `15m`, `1h`, `6h`, `24h`, `7d` ou `all` (os presets do dashboard). Para um intervalo mais longo ou personalizado (como os últimos 30 dias), use `--from`/`--to`: timestamps UTC explícitos no formato ISO-8601 **com `T` e fuso horário** (ex.: `2026-06-01T00:00:00Z`) que substituem `--since`. Um valor separado por espaço ou sem fuso horário é um erro de uso. +- **`--fields a,b,c`** (em `events`, `sessions`, `evals`, `errors`) restringe a saída a essas chaves, tanto na tabela quanto em `--json`. Nomes desconhecidos são rejeitados com a lista válida, uma forma rápida de descobrir nomes de campos. +- **`--file payload.json`** (ou `--file -` para ler stdin) fornece um corpo de requisição JSON completo quando um recurso tem uma estrutura complexa (em `alerts create/update`, `settings set` e `users create/update`). O SQL de consultas salvas usa `--sql @file.sql` em vez disso. +- **Filtros com múltiplos valores** são separados por vírgula → correspondidos como conjunto (união dentro de um filtro, AND entre filtros): `--event-type tool_use,tool_result`. As opções Click não são variádicas, então `--add a b` não funciona. Use `--add a,b`, repita o flag (`--add a --add b`) ou use aspas (`--add "a b"`). --- @@ -174,40 +173,40 @@ Leia esta seção uma vez; ela se aplica a todos os comandos. ### Os 5 comandos que você mais usará -A maior parte do trabalho cotidiano passa por um conjunto de comandos de leitura. Comece por aqui e recorra à superfície completa abaixo quando necessário: +A maior parte do trabalho diário passa por alguns comandos de leitura. Comece por aqui e recorra à superfície completa abaixo quando necessário: | Comando | O que faz | Experimente | |---|---|---| -| `sessions` | Uma linha por execução do agente: tempo, ambiente, agente, status, última pontuação. | `agenteye --json sessions --since 24h --status error` | -| `events` | O rastro bruto passo a passo dentro de uma execução (adicione `--full` para os payloads). | `agenteye --json events --session-id run-001 --all` | -| `evals` | Resultados de avaliação e pontuações; `--aggregate` os agrega. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `sessions` | Uma linha por execução do agente: tempo, ambiente, agente, status, pontuação mais recente. | `agenteye --json sessions --since 24h --status error` | +| `events` | O rastro bruto passo a passo dentro de uma execução (adicione `--full` para payloads). | `agenteye --json events --session-id run-001 --all` | +| `evals` | Resultados e pontuações de avaliação; `--aggregate` os consolida. | `agenteye --json evals --aggregate --since 7d --env prod` | | `errors` | Apenas os eventos com erro; `--aggregate` para contagens por tipo. | `agenteye --json errors --since 24h --aggregate` | -| `list` | Descubra os valores de filtro válidos (agentes, ambientes, modelos, …). | `agenteye list agents` | +| `list` | Descubra os valores válidos de filtro (agentes, ambientes, modelos, …). | `agenteye list agents` | -### Tudo o que o CLI pode fazer +### Tudo que a CLI pode fazer -A superfície completa segue abaixo. O CLI tem **18 comandos de nível superior**. Todos os comandos de leitura aceitam `--json` e as opções globais acima; execute `agenteye -h` (ou ` -h`) para a lista completa de flags e o formato JSON de qualquer um deles. +A superfície completa segue abaixo. A CLI tem **18 comandos de nível superior**. Todos os comandos de leitura aceitam `--json` e as opções globais acima; execute `agenteye -h` (ou ` -h`) para a lista completa de flags e o formato JSON de qualquer um. ### Identidade: `login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash -agenteye login --email you@example.com [--org acme] # código de uso único por e-mail; salva a sessão +agenteye login --email you@example.com [--org acme] # código único por e-mail; salva a sessão agenteye logout # limpa a sessão salva nesta máquina -agenteye whoami # usuário atual, org ativa, permissões -agenteye version # exibe a versão do CLI (igual a --version) +agenteye whoami # usuário atual, organização ativa, permissões +agenteye version # exibe a versão da CLI (igual a --version) agenteye help # help de nível superior (igual a --help) ``` -`orgs` inspeciona e alterna o tenant ativo: +`orgs` inspeciona e altera o tenant ativo: ```bash -agenteye orgs list # suas orgs + sua função em cada uma (a ativa está marcada) -agenteye orgs switch acme # altera a org ativa salva (omita o slug para escolher de uma lista em um TTY) -agenteye orgs current # cartão de identidade da org ativa -agenteye orgs perms # suas permissões na org ativa, agrupadas por recurso +agenteye orgs list # suas organizações + seu papel em cada uma (a ativa está marcada) +agenteye orgs switch acme # altera a organização ativa salva (omita o slug para escolher de uma lista em TTY) +agenteye orgs current # cartão de identidade da organização ativa +agenteye orgs perms # suas permissões na organização ativa, agrupadas por recurso ``` -### Observar (somente leitura): `events` · `sessions` · `evals` · `errors` · `list` +### Observação (somente leitura): `events` · `sessions` · `evals` · `errors` · `list` Nenhum desses requer confirmação. Filtros compartilhados: `--session-id`, `--agent-id`, `--env` (**não** `--environment`) e o intervalo de tempo (`--since` / `--from` / `--to`). @@ -216,44 +215,44 @@ Nenhum desses requer confirmação. Filtros compartilhados: `--session-id`, `--a agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' -# sessions: uma linha por execução do agente (tempo/ambiente/agente/sessão/status; sem filtro por pontuação) +# sessions: uma linha por execução do agente (tempo/ambiente/agente/sessão/status; sem filtragem por pontuação) agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 -# evals: resultados de avaliação + pontuações; --score filtra por métrica, --aggregate agrega +# evals: resultados de avaliação + pontuações; --score filtra por métrica, --aggregate consolida agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 agenteye --json evals --aggregate --since 7d --env prod # mix de status + estatísticas de pontuação por chave -# errors: eventos com erro; --aggregate para contagens/sessões/agentes/último registro +# errors: eventos com erro; --aggregate para contagens/sessões/agentes/último visto agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 -# list: descubra valores de filtro válidos antes de filtrar +# list: descubra valores válidos de filtro antes de filtrar agenteye list envs # também: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (em **`evals`**, não em `sessions`) é repetível e combinado com AND; qualquer um dos limites é opcional (`..0.5` significa ≤ 0,5; `0.9..` significa ≥ 0,9). Até 20 filtros de pontuação por requisição. `evals --scores-full` é um flag de exibição **apenas para a tabela humana**; mostra todos os pares de pontuação em vez dos primeiros mais uma contagem `+N`. Não tem efeito com `--json`, que sempre retorna o objeto de pontuação completo. Para ler **uma sessão de ponta a ponta**, combine o rastro de eventos com sua avaliação: +`--score KEY:MIN..MAX` (em **`evals`**, não em `sessions`) é repetível e combinado com AND; qualquer um dos limites é opcional (`..0.5` significa ≤ 0,5; `0.9..` significa ≥ 0,9). Até 20 filtros de pontuação por requisição. `evals --scores-full` é um flag de exibição **somente para a tabela humana**; mostra todos os pares de pontuação em vez dos primeiros mais um contador `+N`. Não tem efeito em `--json`, que sempre retorna o objeto de pontuação completo. Para ler **uma sessão de ponta a ponta**, combine o rastro de eventos com sua avaliação: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' agenteye --json evals --session-id run-001 # suas pontuações + status ``` -### Gerenciar (com controle de permissão): `keys` · `users` · `settings` · `alerts` · `incidents` +### Gerenciamento (com controle de permissão): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: chaves de API. O segredo é gerado localmente, enviado ao servidor (que armazena apenas um hash) e **exibido uma única vez** no momento da criação/regeneração; capture-o imediatamente. Com `--json` ele aparece apenas no campo `key`. Referenciado por **nome**. +**`keys`**: chaves de API. O segredo é gerado localmente, enviado ao servidor (que armazena apenas um hash) e **exibido uma única vez** na criação/regeneração; capture-o nesse momento. Com `--json`, ele aparece apenas no campo `key`. Referenciados por **nome**. ```bash agenteye keys list # chaves ativas primeiro, depois revogadas agenteye keys show ci-bot -agenteye keys create ci-bot --add events:read.add # escopo mínimo necessário; imprime o segredo UMA VEZ -agenteye keys create ops --permission-set standard --remove queries:run # começa com um preset, depois ajusta +agenteye keys create ci-bot --add events:read.add # limite ao necessário; imprime o segredo UMA VEZ +agenteye keys create ops --permission-set standard --remove queries:run # comece com um preset e ajuste agenteye keys update ci-bot --add evaluations:read --yes -agenteye keys regenerate ci-bot --yes # rotaciona o segredo (o anterior para de funcionar) -agenteye keys disable ci-bot --yes # revoga +agenteye keys regenerate ci-bot --yes # rotaciona o segredo (o antigo para de funcionar) +agenteye keys disable ci-bot --yes # revogar ``` -As permissões funcionam como `(permission-set ∪ --add) − --remove`. Os tokens são `slug:action` (ex.: `events:read`) ou `slug:action.action` para expandir várias ações em um recurso (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. Permissões exclusivas para humanos (`keys:update`) não podem ser concedidas a uma chave. +As permissões funcionam como `(permission-set ∪ --add) − --remove`. Tokens são `slug:action` (ex.: `events:read`) ou `slug:action.action` para expandir várias ações em um recurso (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. Permissões exclusivas para humanos (`keys:update`) não podem ser concedidas a uma chave. **`users`**: membros da organização, referenciados por **e-mail** (um UUID de id também é aceito). @@ -262,7 +261,7 @@ agenteye users list [--active-only] agenteye users show dev@corp.com agenteye users create dev@corp.com --permission-set standard agenteye users update dev@corp.com --add alerts:write --remove queries:delete # prevê + confirma -agenteye users disable dev@corp.com --yes # possui proteções para usuário protegido/próprio +agenteye users disable dev@corp.com --yes # tem proteções para usuário protegido/próprio agenteye users enable dev@corp.com ``` @@ -274,7 +273,7 @@ agenteye settings schema # o que cada chave aceita ( agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: definições de alertas, referenciadas por **nome**. `create` aceita um NOME posicional mais flags ou um corpo JSON completo via `--file`. +**`alerts`**: definições de alerta, referenciadas por **nome**. `create` recebe um NAME posicional mais flags ou um corpo JSON completo via `--file`. ```bash agenteye alerts list @@ -285,7 +284,7 @@ agenteye alerts test high-errors --yes # dispara uma noti agenteye alerts delete high-errors --yes ``` -**`incidents`**: incidentes de alerta, referenciados por id (ids curtos são aceitos). `show` imprime o log completo de atividades; leia-o antes de agir. +**`incidents`**: incidentes de alerta, referenciados por id (IDs curtos são aceitos). `show` exibe o log completo de atividade; leia antes de agir. ```bash agenteye incidents list --state firing # também: acknowledged, resolved @@ -294,7 +293,7 @@ agenteye incidents show agenteye incidents ack agenteye incidents assign you@corp.com # o responsável deve ser um operador agenteye incidents resolve --yes -agenteye incidents open --alert-id --severity critical # abre manualmente contra um alerta +agenteye incidents open --alert-id --severity critical # abrir manualmente contra um alerta agenteye incidents comment-add "root cause: upstream 5xx" agenteye incidents comment-list ; agenteye incidents comment-delete agenteye incidents subscribe ; agenteye incidents unsubscribe ; agenteye incidents subscribers @@ -302,7 +301,7 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### Análises e assistente: `query` · `agent` -**`query`**: SQL salvo contra seu armazenamento de análises mais um executor ad-hoc. Consultas salvas são referenciadas por **nome**; o SQL é validado no servidor (apenas SELECT/WITH, timeout de instrução, limite de linhas). +**`query`**: SQL salvo no seu armazenamento de análises mais um executor ad-hoc. Consultas salvas são referenciadas por **nome**; o SQL é validado no servidor (apenas SELECT/WITH, timeout de instrução, limite de linhas). ```bash agenteye query schema [TABLE] # layout de colunas das views de análise @@ -313,13 +312,13 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: fala com o **assistente de IA** integrado (o mesmo analista somente leitura disponível para chat no dashboard). Os chats são referenciados por um chat-id curto (resolvido por prefixo). +**`agent`**: conversa com o **assistente de IA** integrado (o mesmo analista somente leitura disponível no dashboard). Conversas são referenciadas por um chat-id curto (resolvido por prefixo). ```bash -agenteye agent health # verifica se o assistente de IA está configurado/acessível -agenteye agent models # modelos que podem ser passados para --model (o padrão está marcado) -agenteye agent ask "which agents errored most in the last day?" # inicia um chat; imprime seu id curto -agenteye agent ask --chat "and which tools did they call?" # continua aquele chat +agenteye agent health # o assistente de IA está configurado/acessível +agenteye agent models # modelos que você pode passar para --model (padrão marcado) +agenteye agent ask "which agents errored most in the last day?" # inicia uma conversa; imprime seu id curto +agenteye agent ask --chat "and which tools did they call?" # continua essa conversa agenteye agent chats ; agenteye agent show agenteye agent rename --title "error triage" ; agenteye agent delete ``` @@ -338,13 +337,13 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | 5 | Autenticado, mas sua conta não tem a permissão necessária (a mensagem a identifica) | | 6 | O recurso solicitado não foi encontrado (ex.: sessão ou id de incidente desconhecido) | -Esses códigos tornam o CLI seguro para scripts: um agente de codificação pode ramificar em um `4` para solicitar reautenticação, ou em um `5` para expor a permissão ausente. Consulte [Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes) para padrões de tratamento de códigos de saída e formatos de saída JSON. +Esses códigos tornam a CLI segura para uso em scripts: um agente de codificação pode se ramificar em um `4` para solicitar reautenticação, ou em um `5` para reportar a permissão ausente. Veja [receitas de CLI para agentes](/pt-br/agenteye/cli-recipes) para padrões de tratamento de códigos de saída e formatos de saída JSON. --- ## Próximos passos -- **[Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes)**: padrões de consulta prontos para uso, one-liners com `jq`, projeções com `--fields`, tratamento de códigos de saída e formatos de saída JSON, escritos para agentes de codificação que operam o CLI. -- **[Skill de agente CLI](/pt-br/agenteye/cli-skill)**: empacote este CLI como uma *skill* instalável para Claude Code / Codex, permitindo que um agente de codificação opere o Failproof AI Observability com solicitações em linguagem natural. +- **[Receitas de CLI para agentes](/pt-br/agenteye/cli-recipes)**: padrões de consulta para copiar e colar, one-liners com `jq`, projeções com `--fields`, tratamento de códigos de saída e formatos de saída JSON, escritos para agentes de codificação que usam a CLI. +- **[Skill de agente para CLI](/pt-br/agenteye/cli-skill)**: empacote esta CLI como uma *skill* instalável para Claude Code / Codex para que um agente de codificação gerencie a Observabilidade do Failproof AI a partir de pedidos em linguagem natural. - **[Chaves de API](/pt-br/agenteye/api-keys)**: o modelo de permissões por trás de `keys create --add …`. -- **[Assistente de IA](/pt-br/agenteye/assistant)**: habilitando o assistente que `agent ask` utiliza. \ No newline at end of file +- **[Assistente de IA](/pt-br/agenteye/assistant)**: habilitando o assistente com o qual `agent ask` se comunica. \ No newline at end of file diff --git a/docs/pt-br/agenteye/codex-capture.mdx b/docs/pt-br/agenteye/codex-capture.mdx index 4db292e5..ce5d74c1 100644 --- a/docs/pt-br/agenteye/codex-capture.mdx +++ b/docs/pt-br/agenteye/codex-capture.mdx @@ -1,33 +1,33 @@ --- -title: "Captura de sessão do Codex" -description: "Transmita as sessões locais do OpenAI Codex da sua equipe para o AgentEye como sessões e eventos comuns — sem nenhuma alteração na forma como eles executam o Codex." +title: "Captura de sessões do Codex" +description: "Transmita as sessões locais do OpenAI Codex da sua equipe para o AgentEye como sessões e eventos comuns — sem nenhuma alteração na forma como eles utilizam o Codex." --- -Seus engenheiros já executam o OpenAI Codex todos os dias. A captura de sessão do Codex traz essas sessões de codificação para o AgentEye como sessões e eventos comuns, para que você possa pesquisar, reproduzir e avaliar junto a tudo o mais que você observa. Ela complementa o [Python SDK](/pt-br/agenteye/python-sdk): o SDK instrumenta os agentes que você escreve, enquanto este recurso captura o trabalho que sua equipe já realiza no Codex — sem nenhuma alteração na forma como eles o executam. +Seus engenheiros já utilizam o OpenAI Codex diariamente. A captura de sessões do Codex traz essas sessões de programação para o AgentEye como sessões e eventos comuns, para que você possa pesquisar, reproduzir e avaliar tudo junto com os demais dados observados. Ela complementa o [Python SDK](/pt-br/agenteye/python-sdk): o SDK instrumenta os agentes que você desenvolve, enquanto esta funcionalidade captura o trabalho que sua equipe já realiza no Codex — sem nenhuma alteração na forma como o utilizam. -Um pequeno coletor em segundo plano lê os transcritos de sessão locais do Codex à medida que são gravados e os envia para o AgentEye. Um coletor por máquina captura todas as superfícies locais do Codex de uma vez — sem necessidade de configuração por superfície. +Um pequeno coletor em segundo plano lê os transcritos locais de sessão do Codex conforme são gravados e os envia para o AgentEye. Um único coletor por máquina captura todas as interfaces locais do Codex de uma só vez — não há configuração por interface. -O mesmo coletor também captura outros agentes — veja [OpenClaw](/pt-br/agenteye/openclaw-capture) e [Hermes](/pt-br/agenteye/hermes-capture). Ative cada um que você utiliza; um único coletor pode capturar vários ao mesmo tempo. +O mesmo coletor também captura outros agentes — consulte [OpenClaw](/pt-br/agenteye/openclaw-capture) e [Hermes](/pt-br/agenteye/hermes-capture). Ative cada um que você utiliza; um único coletor pode capturar vários simultaneamente. --- ## O que é capturado -Toda superfície do Codex que executa **localmente** produz os mesmos transcritos de sessão em disco, e o coletor processa todos eles: +Toda interface do Codex executada **localmente** produz os mesmos transcritos de sessão em disco, e o coletor lê todos eles: -- o **CLI** do Codex e o `codex exec` -- a **extensão para VS Code / IDE** +- o **CLI** do Codex e `codex exec` +- a **extensão para VS Code / IDEs** - o **aplicativo desktop**, quando executa uma sessão localmente -Cada sessão do Codex se torna uma [sessão](/pt-br/agenteye/sessions) no AgentEye; suas mensagens de usuário e assistente, raciocínio, chamadas de ferramentas, resultados de ferramentas e uso de tokens se tornam os [eventos](/pt-br/agenteye/event-stream) correspondentes. A superfície de origem de cada sessão (CLI, IDE ou desktop) é registrada, permitindo diferenciá-las. +Cada sessão do Codex se torna uma [sessão](/pt-br/agenteye/sessions) no AgentEye; suas mensagens de usuário e assistente, raciocínio, chamadas de ferramentas, resultados de ferramentas e uso de tokens se tornam os [eventos](/pt-br/agenteye/event-stream) correspondentes. A interface de origem de cada sessão (CLI, IDE ou desktop) é registrada, permitindo diferenciá-las. -> **Sessões na nuvem não são capturadas.** O aplicativo desktop executa cada vez mais sessões na nuvem do Codex e mantém apenas os metadados na máquina — não há transcrito local para leitura. Somente sessões executadas localmente são capturadas. +> **Sessões na nuvem não são capturadas.** O aplicativo desktop executa cada vez mais sessões na nuvem do Codex e mantém apenas os metadados na máquina — não há transcrito local para leitura. Apenas sessões executadas localmente são capturadas. --- ## Como ativar -A captura está desativada até que você a habilite. Instale o coletor com uma chave de API que tenha a permissão `events:add` (veja [Chaves de API](/pt-br/agenteye/api-keys)) e ative a captura do Codex: +A captura fica desativada até que você a habilite. Instale o coletor com uma chave de API que tenha a permissão `events:add` (consulte [Chaves de API](/pt-br/agenteye/api-keys)) e ative a captura do Codex: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ @@ -40,16 +40,16 @@ Isso instala o coletor, registra-o como um serviço em segundo plano e inicia a agenteye-collector health ``` -Na primeira execução, suas sessões do Codex existentes são preenchidas retroativamente uma vez e, em seguida, novas atividades são transmitidas em segundos. Os arquivos do próprio Codex são apenas lidos — nunca modificados, movidos ou excluídos — e cada sessão é enviada exatamente uma vez, mesmo entre reinicializações. +Na primeira execução, suas sessões do Codex existentes são retroalimentadas uma única vez e, a partir daí, a nova atividade é transmitida em segundos. Os arquivos do próprio Codex são apenas lidos — nunca modificados, movidos ou excluídos — e cada sessão é enviada exatamente uma vez, mesmo após reinicializações. --- ## Onde aparece -As sessões capturadas aparecem em **Sessions**, e seus eventos no fluxo **Events**, da mesma forma que qualquer outro agente que você observa — portanto, [replay de sessão](/pt-br/agenteye/sessions), [pesquisa](/pt-br/agenteye/queries), [avaliações](/pt-br/agenteye/evaluations) e [alertas](/pt-br/agenteye/alerts) funcionam normalmente nelas. Filtre pelo agente do Codex para visualizá-las separadamente. +As sessões capturadas aparecem em **Sessions**, e seus eventos no fluxo de **Events**, da mesma forma que qualquer outro agente observado — portanto, [reprodução de sessão](/pt-br/agenteye/sessions), [pesquisa](/pt-br/agenteye/queries), [avaliações](/pt-br/agenteye/evaluations) e [alertas](/pt-br/agenteye/alerts) funcionam normalmente. Filtre pelo agente Codex para visualizá-las de forma isolada. --- ## Privacidade -Os transcritos do Codex contêm a sessão completa — incluindo saída de comandos, conteúdo de arquivos e tudo o que o Codex leu ou escreveu — e podem conter segredos. As sessões capturadas são enviadas como estão, portanto, ative a captura apenas em máquinas e para equipes nas quais centralizar esse conteúdo no AgentEye seja adequado, e forneça ao coletor uma chave com escopo apenas para `events:add`. Veja [Segurança](/pt-br/agenteye/security) para entender como seus dados são mantidos isolados. \ No newline at end of file +Os transcritos do Codex contêm a sessão completa — incluindo saída de comandos, conteúdo de arquivos e tudo que o Codex leu ou gravou — e podem conter informações sensíveis. As sessões capturadas são enviadas sem modificação, portanto, ative a captura apenas em máquinas e para equipes onde centralizar esse conteúdo no AgentEye seja adequado, e forneça ao coletor uma chave com escopo restrito a `events:add`. Consulte [Segurança](/pt-br/agenteye/security) para saber como seus dados são mantidos isolados. \ No newline at end of file diff --git a/docs/pt-br/agenteye/concepts.mdx b/docs/pt-br/agenteye/concepts.mdx index 8aef517f..42bbeb0e 100644 --- a/docs/pt-br/agenteye/concepts.mdx +++ b/docs/pt-br/agenteye/concepts.mdx @@ -1,83 +1,82 @@ --- title: "Conceitos" -description: "O vocabulário por trás da Observabilidade do Failproof AI — eventos, sessões, avaliações, auditorias, descobertas e incidentes — definido em um só lugar." +description: "O vocabulário por trás da Observabilidade do Failproof AI — eventos, sessões, avaliações, auditorias, findings e incidentes — definidos em um único lugar." --- - -Esta página define o vocabulário utilizado pela Observabilidade do Failproof AI. Se algum termo em outro guia parecer desconhecido, ele está definido aqui. Você não precisa ler do início ao fim: percorra rapidamente ou volte quando quiser esclarecer uma palavra específica. +Esta página define o vocabulário utilizado pela Observabilidade do Failproof AI. Se um termo em outro guia for desconhecido, ele está definido aqui. Não é necessário ler do início ao fim: faça uma leitura diagonal ou volte quando precisar esclarecer um termo específico. --- ## O modelo de dados **Evento** -A menor unidade de dados. Um evento registra um único passo executado pelo seu agente: um `tool_use`, um `model_request`, um `hook_completed`, um `error`, entre outros. Seu agente emite eventos por meio do [Python SDK](/pt-br/agenteye/python-sdk); eles aparecem em tempo real na página **Events**. +A menor unidade de dado. Um evento registra um único passo executado pelo seu agente: um `tool_use`, um `model_request`, um `hook_completed`, um `error`, entre outros. Seu agente emite eventos por meio do [Python SDK](/pt-br/agenteye/python-sdk); eles aparecem em tempo real na página de **Eventos**. **Sessão** -Uma execução do agente, identificada por um `session_id`. Uma sessão é composta por todos os eventos que compartilham esse id, consolidados em uma única linha na página **Sessions** e representados como um grafo de execução na página de detalhes. Uma sessão normalmente começa com `agent_start` e termina com `agent_end`. +Uma execução do agente, identificada por um `session_id`. Uma sessão reúne todos os eventos que compartilham esse id, consolidados em uma única linha na página de **Sessões** e representados como um grafo de execução na página de detalhes. Normalmente, uma sessão começa com `agent_start` e termina com `agent_end`. **Agente** -Um ator nomeado dentro de uma execução, identificado por um `agent_id`. Uma execução pode envolver vários agentes: por exemplo, um planejador que cria um sub-agente de resumo. Sub-agentes carregam um `parent_id`, que é o que permite ao Failproof AI Observability exibi-los em suas próprias faixas no grafo de execução. +Um ator nomeado dentro de uma execução, identificado por um `agent_id`. Uma execução pode envolver vários agentes: por exemplo, um planejador que instancia um sub-agente de sumarização. Sub-agentes carregam um `parent_id`, que permite ao Failproof AI Observability representá-los em suas próprias faixas no grafo de execução. **Ambiente** -Um rótulo que indica onde a execução ocorreu: `production`, `staging`, `dev`. Você o define uma única vez ao configurar o SDK. Quase todas as páginas do dashboard permitem filtrar por ambiente. +Um rótulo que indica onde a execução ocorreu: `production`, `staging`, `dev`. Você o define uma única vez ao configurar o SDK. Praticamente todas as páginas do dashboard permitem filtrar por ambiente. **Preenchimento da janela de contexto** -O percentual da janela de contexto de um modelo consumido por uma resposta. O Failproof AI Observability registra esse valor em eventos `model_response` para os modelos que reconhece, tornando o crescimento do prompt e a compactação iminente visíveis diretamente no fluxo de eventos. +O percentual da janela de contexto de um modelo consumido por uma resposta. O Failproof AI Observability registra esse valor nos eventos `model_response` para os modelos que reconhece, tornando o crescimento do prompt e a compactação iminente visíveis diretamente no fluxo de eventos. --- ## Qualidade **Avaliação** -Uma pontuação de qualidade para uma sessão concluída, produzida por um serviço de pontuação que você executa. As avaliações são opcionais: até que você conecte um avaliador, as sessões são registradas, mas não pontuadas. Cada avaliação pode conter várias pontuações nomeadas (por exemplo, `helpfulness`, `factuality`, `tool_efficiency`), cada uma com uma breve nota de raciocínio. Veja [Evaluation suite](/pt-br/agenteye/evaluation-suite). +Uma pontuação de qualidade para uma sessão finalizada, produzida por um serviço de pontuação que você executa. As avaliações são opcionais: até que você conecte um avaliador, as sessões são registradas, mas não pontuadas. Cada avaliação pode conter diversas pontuações nomeadas (por exemplo, `helpfulness`, `factuality`, `tool_efficiency`), cada uma com uma breve nota de justificativa. Consulte [Evaluation suite](/pt-br/agenteye/evaluation-suite). **Chave de pontuação** -O nome de uma dimensão que um avaliador reporta, como `helpfulness`. Alertas e auditorias podem monitorar uma chave de pontuação específica ao longo do tempo. +O nome de uma dimensão reportada por um avaliador, como `helpfulness`. Alertas e auditorias podem monitorar uma chave de pontuação específica ao longo do tempo. **Avaliador** -Seu serviço de pontuação. O Failproof AI Observability faz um POST com a transcrição de uma execução concluída para ele e armazena as pontuações retornadas. Não há um avaliador padrão incluído; a lógica de pontuação é sua. +Seu serviço de pontuação. O Failproof AI Observability envia via POST a transcrição de uma execução finalizada para ele e armazena as pontuações retornadas. Não há um avaliador padrão incluído; a lógica de pontuação é sua. --- ## Identificando e corrigindo falhas **Hook** -Uma salvaguarda ou efeito colateral que seu framework de agentes executa em torno de um passo: uma verificação de segurança de conteúdo, anonimização de dados pessoais, um controle de orçamento. Hooks emitem eventos `hook_triggered` / `hook_completed` com um `outcome` (allow, deny, modify) e têm sua própria página de observação. +Uma proteção ou efeito colateral que seu framework de agentes executa em torno de um passo: uma verificação de segurança de conteúdo, anonimização de PII, um controle de orçamento. Hooks emitem eventos `hook_triggered` / `hook_completed` com um `outcome` (allow, deny, modify) e possuem sua própria página de observação. **Regra de alerta** -Uma regra que é acionada quando uma métrica ultrapassa um limite definido por você: taxa de erros, latência p95, custo em tokens ou uma pontuação de avaliação. Quando uma regra é acionada, ela abre um incidente e notifica os canais escolhidos (e-mail, Slack, webhook, no dashboard). Veja [Alerts](/pt-br/agenteye/alerts). +Uma regra que é acionada quando uma métrica ultrapassa um limiar definido por você: taxa de erros, latência p95, custo de tokens ou uma pontuação do avaliador. Quando uma regra é acionada, ela abre um incidente e notifica os canais configurados (e-mail, Slack, webhook, in-dashboard). Consulte [Alerts](/pt-br/agenteye/alerts). **Incidente** -Uma questão em aberto criada quando uma regra de alerta é acionada. Incidentes têm um ciclo de vida (reconhecer, atribuir, resolver) e uma linha do tempo de atividades que registra cada ação. Você também pode abrir um manualmente. +Um problema em aberto criado quando uma regra de alerta é acionada. Incidentes possuem um ciclo de vida (reconhecer, atribuir, resolver) e uma linha do tempo de atividades que registra cada ação. Você também pode abrir um manualmente. **Auditoria** -Uma investigação recorrente (de hora em hora a semanalmente) que analisa seus logs *entre* sessões em busca de padrões de falha para os quais você ainda não escreveu uma regra: clusters de erros, pontuações baixas, outliers de latência, loops de chamadas de ferramentas e execuções que nunca foram concluídas. Enquanto um alerta monitora uma métrica que você já conhece, uma auditoria indica o que você deve examinar a seguir. Veja [Audits](/pt-br/agenteye/audits). +Uma investigação recorrente (de hora em hora até semanal) que analisa seus logs *entre* sessões em busca de padrões de falha para os quais você ainda não escreveu uma regra: clusters de erros, pontuações baixas, outliers de latência, loops de chamadas de ferramentas e execuções que nunca foram concluídas. Enquanto um alerta monitora uma métrica que você já conhece, uma auditoria indica o que você deve analisar a seguir. Consulte [Audits](/pt-br/agenteye/audits). -**Descoberta** -Um resultado classificado e embasado em evidências proveniente de uma execução de auditoria. Uma descoberta nomeia um padrão, vincula às sessões exatas que o sustentam e possui um ciclo de vida de triagem (reconhecer, resolver, silenciar, descartar). O Failproof AI Observability deduplica descobertas entre execuções, de forma que um padrão conhecido seja atualizado em vez de se acumular. +**Finding** +Um resultado ranqueado e fundamentado em evidências de uma execução de auditoria. Um finding nomeia um padrão, vincula às sessões exatas que o originaram e possui um ciclo de vida de triagem (reconhecer, resolver, silenciar, descartar). O Failproof AI Observability deduplica findings entre execuções, de modo que um padrão já conhecido é atualizado em vez de acumular duplicatas. **O assistente de IA** -O chat integrado ao dashboard que responde perguntas sobre seus agentes em linguagem natural, utilizando seus próprios dados. Por padrão, é somente leitura; qualquer coisa que ele crie (uma consulta salva, um dashboard) requer aprovação, e ele nunca pode excluir dados. Veja [AI assistant](/pt-br/agenteye/assistant). +O chat integrado ao dashboard que responde perguntas sobre seus agentes em linguagem natural, com base nos seus próprios dados. Por padrão, é somente leitura; qualquer coisa que ele crie (uma consulta salva, um dashboard) requer aprovação, e ele nunca pode excluir dados. Consulte [AI assistant](/pt-br/agenteye/assistant). --- -## Operação +## Executando **Organização (tenant)** -Um espaço de trabalho isolado. Uma instância do Failproof AI Observability pode hospedar várias organizações, cada uma com seus próprios usuários, chaves e dados. Toda URL do dashboard é delimitada pelo slug da sua organização (`//…`). +Um workspace isolado. Uma única instância do Failproof AI Observability pode hospedar várias organizações, cada uma com seus próprios usuários, chaves e dados. Toda URL do dashboard é escopada sob o slug da sua organização (`//…`). **Coletor** -`agenteye-collector`, o daemon leve que é executado em cada máquina de agente, agrupa os eventos que o SDK grava em disco e os envia para o servidor. +`agenteye-collector`, o daemon leve que roda em cada máquina de agente, agrupa os eventos que o SDK grava em disco e os envia para o servidor. **Chave de API** -Um token com escopo definido que autentica um cliente junto ao servidor. As chaves carregam permissões granulares (por exemplo, `events:add` para o coletor, escopos somente leitura para uma chave de dashboard). Veja [API keys](/pt-br/agenteye/api-keys). +Um token escopado que autentica um cliente no servidor. As chaves possuem permissões granulares (por exemplo, `events:add` para o coletor, escopos somente leitura para uma chave de dashboard). Consulte [API keys](/pt-br/agenteye/api-keys). **Servidor** O serviço de ingestão e API. Ele ingere eventos, armazena o estado operacional nos seus bancos de dados e serve o dashboard e a CLI. **Dashboard** -A interface web. Cada página é delimitada a uma organização e lê os dados por meio da API do servidor. +A interface web. Cada página é escopada a uma organização e lê os dados por meio da API do servidor. --- diff --git a/docs/pt-br/agenteye/dashboards.mdx b/docs/pt-br/agenteye/dashboards.mdx index 72b6704f..d8725cdd 100644 --- a/docs/pt-br/agenteye/dashboards.mdx +++ b/docs/pt-br/agenteye/dashboards.mdx @@ -1,45 +1,45 @@ --- title: "Dashboards" -description: "Transforme os dados ao vivo do seu agente em uma visão compartilhada que toda a equipe acompanha." +description: "Transforme os dados ao vivo do seu agente em uma visão compartilhada que toda a sua equipe acompanha." --- -Transforme os dados ao vivo do seu agente em uma visão compartilhada que toda a equipe acompanha. Fixe as consultas mais importantes como gráficos e todos têm acesso aos mesmos números de forma imediata, sem precisar executar uma única consulta novamente. +Transforme os dados ao vivo do seu agente em uma visão compartilhada que toda a sua equipe acompanha. Fixe as consultas mais importantes como gráficos e todos terão acesso aos mesmos números de relance, sem precisar reexecutar nenhuma consulta. -![Um dashboard construído a partir de consultas salvas: uma linha de eventos por hora, uma barra de erros por tipo, um gráfico de área de latência e tokens por modelo](/agenteye/images/dashboard-fleet.png) +![Um dashboard criado a partir de consultas salvas: uma linha de eventos por hora, um gráfico de barras de erros por tipo, um gráfico de área de latência e tokens por modelo](/agenteye/images/dashboard-fleet.png) *Um painel, quatro consultas salvas: eventos por hora, erros por tipo, latência e tokens por modelo.* ## Todos veem a mesma realidade -Pare de colar capturas de tela no chat e de executar a mesma consulta cinco vezes por dia. Um dashboard é um painel compartilhado, visível para toda a organização, que qualquer membro da equipe pode abrir e ver exatamente a mesma visão. Quando os dados subjacentes mudam, os gráficos acompanham, então o painel está sempre atualizado e ninguém discute por causa de números desatualizados. +Pare de colar capturas de tela no chat e de reexecutar a mesma consulta cinco vezes por dia. Um dashboard é um painel compartilhado, disponível para toda a organização, que qualquer membro da sua equipe pode abrir e ver exatamente a mesma visualização. Quando os dados subjacentes mudam, os gráficos acompanham, então o painel está sempre atualizado e ninguém precisa discutir números desatualizados. -O dashboard de frota acima é um bom ponto de partida para operações do dia a dia: +O dashboard de frota acima é um bom ponto de partida para as operações do dia a dia: -- uma linha de **eventos por hora**, para acompanhar o throughput e detectar quedas repentinas -- uma barra de **erros por tipo**, para que as principais categorias de falha fiquem evidentes -- um gráfico de área de **latência**, para que lentidões apareçam antes que os usuários reclamem -- uma divisão de **tokens por modelo**, para manter os custos sempre visíveis +- uma linha de **eventos por hora**, para monitorar o throughput e identificar quedas repentinas +- um gráfico de barras de **erros por tipo**, para destacar as principais categorias de falha +- um gráfico de área de **latência**, para detectar lentidões antes que os usuários reclamem +- um detalhamento de **tokens por modelo**, para manter os custos em evidência Você encontrará seus painéis em `//dashboards`. ## Fixe as consultas que você já salvou -Cada tile começa como uma consulta salva. Crie e salve a consulta desejada na biblioteca de [Queries](/pt-br/agenteye/queries) (presets integrados mais os seus próprios, sobre seus eventos e avaliações) e, em seguida, fixe-a em um dashboard como o gráfico que melhor representa os dados: uma **linha** para tendências ao longo do tempo, uma **barra** para comparar categorias, uma **área** para volume ou um **pizza** para mostrar distribuição percentual. +Cada bloco começa como uma consulta salva. Construa e salve a consulta desejada na biblioteca de [Consultas](/pt-br/agenteye/queries) (presets integrados mais os seus próprios, sobre seus eventos e avaliações) e, em seguida, fixe-a em um dashboard como o gráfico que melhor representa os dados: uma **linha** para tendências ao longo do tempo, uma **barra** para comparar categorias, uma **área** para volume ou um **pizza** para mostrar proporções. -Como um tile é apenas sua consulta salva renderizada como gráfico, não há nada para sincronizar manualmente. Atualize a consulta uma vez e todos os dashboards que a utilizam são atualizados automaticamente. +Como um bloco é simplesmente sua consulta salva renderizada como gráfico, não há nada para sincronizar manualmente. Atualize a consulta uma vez e todos os dashboards que a utilizam serão atualizados também. ## Monitore qualidade, não apenas volume -Volume indica que os agentes estão ocupados. Qualidade indica que eles estão realmente fazendo o trabalho. Aponte um dashboard para suas [pontuações de avaliação](/pt-br/agenteye/evaluations) e você terá um painel que acompanha o desempenho das execuções ao longo do tempo — assim, uma regressão de qualidade aparece como uma queda no gráfico, e não como uma surpresa vinda de um cliente. +O volume indica que os agentes estão ocupados. A qualidade indica que eles estão realmente cumprindo o trabalho. Aponte um dashboard para suas [pontuações de avaliação](/pt-br/agenteye/evaluations) e você terá um painel que acompanha a qualidade das execuções ao longo do tempo, de modo que uma regressão de qualidade aparece como uma queda em um gráfico em vez de uma surpresa vinda de um cliente. -![Um dashboard focado em qualidade construído a partir de consultas de avaliação salvas](/agenteye/images/dashboard-quality.png) +![Um dashboard focado em qualidade criado a partir de consultas de avaliação salvas](/agenteye/images/dashboard-quality.png) *Um painel de qualidade mantém suas pontuações de avaliação em destaque, lado a lado com os números operacionais.* -Mantenha um painel de operações e um painel de qualidade lado a lado e sua equipe terá um único lugar para responder tanto "está funcionando?" quanto "está sendo feito bem?" — sem que ninguém precise executar uma consulta novamente. +Mantenha um painel de operações e um painel de qualidade lado a lado e sua equipe terá um único lugar para responder tanto "está funcionando?" quanto "está funcionando bem?", sem que ninguém precise reexecutar uma consulta. ## Relacionados -- [Queries](/pt-br/agenteye/queries): crie e salve as consultas que se tornarão seus tiles. -- [Evaluations](/pt-br/agenteye/evaluations): pontue suas execuções para poder visualizar a qualidade ao longo do tempo. -- [Alerts](/pt-br/agenteye/alerts): transforme um limite em qualquer uma dessas métricas em um alerta. \ No newline at end of file +- [Consultas](/pt-br/agenteye/queries): construa e salve as consultas que se tornam seus blocos. +- [Avaliações](/pt-br/agenteye/evaluations): pontue suas execuções para poder monitorar a qualidade ao longo do tempo. +- [Alertas](/pt-br/agenteye/alerts): converta um limite em qualquer uma dessas métricas em uma notificação. \ No newline at end of file diff --git a/docs/pt-br/agenteye/error-tracking.mdx b/docs/pt-br/agenteye/error-tracking.mdx index aa61661d..e4825671 100644 --- a/docs/pt-br/agenteye/error-tracking.mdx +++ b/docs/pt-br/agenteye/error-tracking.mdx @@ -1,32 +1,33 @@ --- title: "Rastreamento de Erros" -description: "Veja todas as falhas dos seus agentes em um único lugar, agrupadas para que uma enxurrada de erros apareça como um único problema." +description: "Veja todas as falhas dos seus agentes em um só lugar, agrupadas para que uma rajada de erros apareça como um único problema." --- -Veja todas as falhas dos seus agentes em um único lugar, agrupadas para que uma enxurrada de erros apareça como um único problema. Você tem um caminho de um clique entre "algo está vermelho" e a execução exata que quebrou, sem precisar rolar um feed ao vivo para encontrá-la. -![A página de Erros: um histograma de falhas ao longo do tempo acima de linhas de erros vermelhas agrupadas, cada uma com um botão "+ alerta" de um clique](/agenteye/images/errors.png) -*A página de Erros: um histograma de falhas ao longo do tempo, com falhas repetidas agrupadas em uma única linha por incidente.* +Veja todas as falhas dos seus agentes em um só lugar, agrupadas para que uma rajada de erros apareça como um único problema. Você tem um caminho de um clique de "algo está vermelho" até a execução exata que quebrou, sem precisar rolar um feed ao vivo para encontrá-la. + +![A página de Erros: um histograma de falhas ao longo do tempo acima de linhas de erros vermelhos agrupados, cada uma com um botão "+ alert" de um clique](/agenteye/images/errors.png) +*A página de Erros: um histograma de falhas ao longo do tempo, com falhas repetidas recolhidas em uma única linha por incidente.* ## Todas as falhas, já coletadas para você -Quando um agente quebra, você não deveria precisar rolar um stream de eventos ao vivo esperando capturar as linhas vermelhas antes que desapareçam. A página **Errors** faz a coleta por você. Ela reúne tudo o que o dashboard pintaria de vermelho em uma única superfície de triagem, para que a primeira coisa que você veja seja o que está falhando, não onde procurar. +Quando um agente quebra, você não deveria precisar rolar um stream de eventos ao vivo torcendo para capturar as linhas vermelhas antes que desapareçam. A página **Errors** faz a coleta por você. Ela reúne tudo o que o dashboard pintaria de vermelho em uma única superfície de triagem, para que a primeira coisa que você veja seja o que está falhando, e não onde ir procurar. -E ela captura mais do que as falhas óbvias. Além dos eventos explícitos de `error`, o Failproof AI Observability também exibe as falhas silenciosas: qualquer `tool_result`, `hook_completed` ou `agent_end` cujo payload indique uma falha aparece aqui. Uma ferramenta que retornou um erro ou um hook que terminou com problema não passa mais despercebido só porque nenhuma exceção barulhenta foi lançada. +E ela captura mais do que as falhas óbvias. Além dos eventos `error` explícitos, o Failproof AI Observability também expõe as falhas silenciosas: qualquer `tool_result`, `hook_completed` ou `agent_end` cujo payload carregue uma falha aparece aqui. Uma ferramenta que retornou um erro, ou um hook que terminou com falha, não passa mais despercebido só porque nenhuma exceção ruidosa foi lançada. -No topo, um histograma plota os erros ao longo do tempo. Uma olhada já diz se é um gotejamento constante de fundo ou um pico que começou há alguns minutos, para que você saiba imediatamente se deve largar o que está fazendo. +No topo, um histograma plota os erros ao longo do tempo. Uma olhada já te diz se é um gotejamento constante de fundo ou um pico que começou há alguns minutos — assim você sabe na hora se deve largar o que está fazendo. -Como toda superfície de observação, a página de Errors é limitada à sua organização e filtra por intervalo de datas, ambiente, agente e sessão. Isso significa que você pode pegar uma lista de toda a frota e reduzi-la ao único agente ou ambiente que realmente importa. +Como toda superfície de observação, a página de Erros é delimitada pela sua organização e filtra por intervalo de datas, ambiente, agente e sessão. Isso significa que você pode pegar uma lista de toda a frota e afunilar até o agente ou ambiente que realmente importa. -## Um incidente, não cem linhas idênticas +## Um incidente, não centenas de linhas idênticas -Uma única dependência quebrada pode disparar o mesmo erro centenas de vezes por minuto. Sem tratamento, isso é uma parede de linhas quase idênticas que enterra exatamente o que você precisa ver. +Uma única dependência quebrada pode disparar o mesmo erro centenas de vezes por minuto. Sem nenhum agrupamento, isso vira uma parede de linhas quase idênticas que enterra a única coisa que você realmente precisa ver. -O Failproof AI Observability agrupa falhas repetidas que compartilham a mesma sessão e tipo de erro em uma única linha. Uma enxurrada aparece como um único incidente. Você acaba contando problemas, não linhas de log, e o sinal que importa permanece no topo em vez de ser afogado pelo seu próprio volume. +O Failproof AI Observability recolhe falhas repetidas que compartilham a mesma sessão e tipo de erro em uma única linha. Uma rajada aparece como um incidente. Você termina contando problemas, não linhas de log, e o sinal que importa permanece no topo em vez de ser afogado pelo seu próprio volume. ## De "algo está vermelho" ao evento exato -Clique em qualquer linha para ir direto para a sessão daquela execução, posicionado no evento exato que falhou. Sem copiar IDs de sessão, sem rolar para encontrar o momento em que deu errado: você chega direto nele, com o gráfico de execução completo a uma olhada de distância para ver o que o agente fez nos momentos antes de quebrar. +Clique em qualquer linha para cair direto dentro da sessão daquela execução, posicionado no evento exato que falhou. Sem copiar IDs de sessão, sem rolar para encontrar o momento em que deu errado: você chega direto nele, com o grafo de execução completo a um olhar de distância para que você possa ver o que o agente fez nos momentos antes de quebrar. Se você tiver `alerts:write`, cada linha também traz um botão **+ alert**. Clique nele e o Observability abre uma nova regra de alerta já preenchida para capturar essa mesma falha novamente. O incidente que você acabou de triar se torna o que vai te notificar na próxima vez, em vez de te surpreender duas vezes. @@ -34,7 +35,7 @@ Se você tiver `alerts:write`, cada linha também traz um botão **+ alert**. Cl ## Relacionados -- [Alertas](/pt-br/agenteye/alerts): transforme qualquer falha em uma regra de notificação. -- [Incidentes](/pt-br/agenteye/incidents): acompanhe um alerta ativo do início à resolução. -- [Sessões](/pt-br/agenteye/sessions): abra a execução completa por trás de qualquer erro. -- [Auditorias](/pt-br/agenteye/audits): deixe o Observability encontrar padrões de falha nas suas execuções para você. \ No newline at end of file +- [Alerts](/pt-br/agenteye/alerts): transforme qualquer falha em uma regra de notificação. +- [Incidents](/pt-br/agenteye/incidents): acompanhe um alerta disparado do início à resolução. +- [Sessions](/pt-br/agenteye/sessions): abra a execução completa por trás de qualquer erro. +- [Audits](/pt-br/agenteye/audits): deixe o Observability encontrar padrões de falha em suas execuções para você. \ No newline at end of file diff --git a/docs/pt-br/agenteye/evaluation-suite.mdx b/docs/pt-br/agenteye/evaluation-suite.mdx index 20517a6c..76d4fbcb 100644 --- a/docs/pt-br/agenteye/evaluation-suite.mdx +++ b/docs/pt-br/agenteye/evaluation-suite.mdx @@ -1,22 +1,22 @@ --- title: "Suite de Avaliação" -description: "O Failproof AI Observability pode pontuar automaticamente cada execução de agente concluída em termos de qualidade: você fornece um pequeno serviço de pontuação e o Observability cuida do restante." +description: "O Failproof AI Observability pode pontuar automaticamente cada execução concluída do agente quanto à qualidade: você fornece um pequeno serviço de pontuação, e o Observability cuida do resto." --- -O Failproof AI Observability pode pontuar automaticamente cada execução de agente concluída em termos de qualidade: você fornece um pequeno serviço de pontuação e o Observability cuida do restante. Use-o para acompanhar as dimensões que importam para você (utilidade, eficiência de ferramentas, veracidade, segurança — você escolhe), identificar regressões cedo e comparar agentes ou ambientes de forma rápida. A pontuação é opcional: o pipeline não faz nada até que você defina `EVALUATOR_ENDPOINT` no servidor. +O Failproof AI Observability pode pontuar automaticamente cada execução concluída do agente quanto à qualidade: você fornece um pequeno serviço de pontuação, e o Observability cuida do resto. Use-o para acompanhar as dimensões que importam para você (utilidade, eficiência de ferramentas, factualidade, segurança — você escolhe), detectar regressões cedo e comparar agentes ou ambientes de forma simples. A pontuação é opcional: o pipeline não faz nada até que você configure `EVALUATOR_ENDPOINT` no servidor. -> **Nota:** Você define as dimensões de pontuação. Seu avaliador pode retornar quaisquer chaves numéricas que desejar; o Observability armazena, acompanha tendências e exibe tudo o que você enviar. +> **Observação:** Você define as dimensões de pontuação. Seu avaliador pode retornar quaisquer chaves numéricas que desejar; o Observability armazena, acompanha tendências e exibe tudo o que você enviar. -## Resumo +## Visão geral -1. **Escreva um avaliador.** Suba um pequeno serviço HTTP que leia a transcrição de uma sessão e retorne pontuações. O Observability inclui um exemplo funcional que você pode copiar. Veja [Escrevendo um avaliador com o SDK](#writing-an-evaluator-with-the-sdk). -2. **Aponte o Observability para ele.** Defina `EVALUATOR_ENDPOINT` (e um `EVALUATOR_TOKEN` compartilhado) no processo do servidor. +1. **Escreva um avaliador.** Configure um pequeno serviço HTTP que lê a transcrição de uma sessão e retorna pontuações. O Observability já inclui uma referência funcional que você pode copiar. Consulte [Escrevendo um avaliador com o SDK](#writing-an-evaluator-with-the-sdk). +2. **Aponte o Observability para ele.** Configure `EVALUATOR_ENDPOINT` (e um `EVALUATOR_TOKEN` compartilhado) no processo do servidor. 3. **Acompanhe as pontuações.** Cada sessão concluída é pontuada automaticamente; os resultados aparecem na página de detalhes da sessão, na grade de sessões e nos dashboards salvos. -![Uma visualização de detalhes da sessão com o resumo da avaliação, barras de pontuação por dimensão e texto de raciocínio no painel direito](/agenteye/images/session-detail.png) +![Uma visualização de detalhes de sessão com o resumo da avaliação, barras de pontuação por dimensão e texto de raciocínio no painel direito](/agenteye/images/session-detail.png) -*Após configurar um avaliador, cada execução concluída é pontuada e os resultados aparecem no painel direito da sessão: o resumo no topo, seguido pelas barras de pontuação por dimensão com o raciocínio correspondente.* +*Depois que um avaliador é configurado, cada execução concluída é pontuada e os resultados aparecem no painel direito da sessão: o resumo no topo, seguido de barras de pontuação por dimensão com raciocínio.* --- @@ -36,46 +36,46 @@ Quando o SDK do Observability emite um evento `agent_end` para uma sessão, o se agenda uma avaliação. Em seguida, ele envia via POST a transcrição completa de eventos para o seu serviço avaliador, que pode: -- **Retornar o resultado inline** com `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. O - resultado é anexado à linha do tempo de avaliações da sessão. `reasoning` e +- **Retornar o resultado de forma síncrona** com `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. O + resultado é anexado à linha do tempo de avaliação da sessão. `reasoning` e `summary` são opcionais. - **Adiar** com `{"status":"pending", "job_id":"abc-123"}`. O Observability então chama `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` até que seu avaliador retorne `{"status":"done", ...}` ou `{"status":"error", "error":"..."}`. - O intervalo de polling é por job: uma resposta `pending` pode incluir - `next_poll_secs` para sobrescrever o valor padrão; caso contrário, o Observability usa o - valor `default_poll_interval_secs` de `GET /config`; caso contrário, o servidor - recorre a `EVALUATOR_POLLING_INTERVAL_SECS` (padrão: 10s). Todos os valores + O intervalo de polling é por tarefa: uma resposta `pending` pode incluir + `next_poll_secs` para sobrescrever; caso contrário, o Observability usa o valor + `default_poll_interval_secs` de `GET /config`; caso contrário, o servidor + usa `EVALUATOR_POLLING_INTERVAL_SECS` como fallback (padrão: 10s). Todos os valores são limitados ao intervalo [1s, 1h]. Sessões que nunca emitem `agent_end` (por exemplo, um processo de agente que travou) também podem ser processadas: o `GET /config` do avaliador pode retornar `{"inactivity_timeout_secs": 1800}`, e o Observability avaliará qualquer sessão -que estiver inativa por esse tempo. Defina o campo como `null` ou omita-o para -desabilitar esse fallback. +que ficar inativa por esse tempo. Defina o campo como `null` ou omita-o para +desativar esse fallback. -O pipeline é completamente inativo quando `EVALUATOR_ENDPOINT` não está definido. +O pipeline não faz nada quando `EVALUATOR_ENDPOINT` não está configurado. Uma sessão pode acumular **múltiplas avaliações terminais ao longo do tempo**: cada -evento `agent_end` (e cada re-avaliação manual pelo dashboard) acrescenta uma -nova linha de avaliação. Esta é a forma recomendada de avaliar uma conversa retomada: -um usuário encerra um agente, volta mais tarde, envia mais eventos, +evento `agent_end` (e cada reavaliação manual pelo dashboard) adiciona uma +nova linha de avaliação. Essa é a forma recomendada de avaliar uma conversa +retomada: um usuário encerra um agente, volta mais tarde, envia mais eventos, encerra o agente novamente, e uma segunda avaliação é executada contra a transcrição -completa atualizada. O dashboard exibe a avaliação mais recente como título -e as avaliações anteriores como uma linha do tempo recolhível. Enquanto uma -avaliação está em andamento para uma sessão, eventos `agent_end` adicionais para essa -sessão são ignorados; o próximo evento após a conclusão da avaliação em andamento +completa e atualizada. O dashboard renderiza a avaliação mais recente como +principal e as avaliações anteriores como uma linha do tempo recolhível. Enquanto uma +avaliação está em execução para uma sessão, eventos `agent_end` adicionais para essa +sessão são ignorados; o próximo após a conclusão da avaliação em andamento enfileirará uma nova avaliação normalmente. -O fallback por inatividade também se aplica a sessões retomadas: se novos eventos +O fallback de inatividade também se ativa em sessões retomadas: se novos eventos chegarem após uma avaliação terminal anterior e a sessão ficar inativa -além de `inactivity_timeout_secs`, uma nova avaliação é enfileirada. +por mais de `inactivity_timeout_secs`, uma nova avaliação é enfileirada. Falhas transitórias (5xx, 429, timeouts, erros de rede) são repetidas com backoff exponencial até `EVALUATOR_MAX_ATTEMPTS`; respostas 4xx são -terminais. O Observability pode ser executado com múltiplas instâncias de servidor -com escalonamento horizontal; o trabalho é particionado para que a mesma sessão nunca seja +terminais. O Observability pode ser executado com segurança em múltiplas instâncias +de servidor com escalonamento horizontal; o trabalho é particionado para que a mesma sessão nunca seja despachada duas vezes simultaneamente. --- @@ -83,21 +83,21 @@ despachada duas vezes simultaneamente. ## Contrato HTTP Todas as rotas autenticadas usam **autenticação por bearer token**. O mesmo valor deve ser -configurado nos dois lados: +configurado em ambos os lados: - Servidor do Observability: variável de ambiente `EVALUATOR_TOKEN` - Serviço avaliador: configurado da mesma forma (o SDK `agenteye-evaluator` lê `EVALUATOR_TOKEN` por convenção) -Se `EVALUATOR_TOKEN` não estiver definido, o servidor não envia o cabeçalho `Authorization`; o -avaliador pode então aceitar requisições anônimas, o que é aceitável para uma -rede interna, mas não é recomendado na internet pública. +Se `EVALUATOR_TOKEN` não estiver configurado, o servidor não envia cabeçalho `Authorization`; o +avaliador pode então aceitar requisições anônimas, o que é aceitável para redes +internas, mas não recomendado na internet pública. ### Rotas que o avaliador deve servir | Rota | Corpo / parâmetros | Resposta | |---|---|---| -| `GET /health` | nenhum | `{"status":"ok"}` (aberta, sem autenticação) | +| `GET /health` | nenhum | `{"status":"ok"}` (aberto, sem autenticação) | | `GET /config` | nenhum | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | | `POST /evaluate` | JSON `EvalRequest` | `{"status":"done", ...}` ou `{"status":"pending", "job_id":"..."}` | | `GET /evaluate/{id}` | nenhum | mesmo formato de resposta que `/evaluate` | @@ -135,12 +135,12 @@ rede interna, mas não é recomendado na internet pública. } ``` -`reasoning` (um mapa de justificativa por pontuação) e `summary` (uma narrativa -geral em um parágrafo) são ambos opcionais. As chaves em `reasoning` devem -espelhar as chaves em `scores`; o dashboard renderiza cada entrada inline abaixo -da barra de pontuação correspondente. Avaliadores mais antigos que retornam apenas `scores` continuam -funcionando sem alterações; `reasoning` e `summary` simplesmente são lidos como null e -os elementos visuais correspondentes na interface são omitidos. +`reasoning` (um mapa de justificativa por pontuação) e `summary` (uma +narrativa geral de um parágrafo) são ambos opcionais. As chaves em `reasoning` devem +corresponder às chaves em `scores`; o dashboard renderiza cada entrada logo abaixo +da sua barra de pontuação. Avaliadores mais antigos que retornam apenas `scores` continuam +funcionando sem alterações; `reasoning` e `summary` simplesmente ficam como null e +os elementos de UI correspondentes são omitidos. **Assíncrono (adiado):** @@ -148,9 +148,9 @@ os elementos visuais correspondentes na interface são omitidos. { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` é opcional; se omitido, o servidor recorre ao -`default_poll_interval_secs` do avaliador em `/config` e, em seguida, à sua própria -variável de ambiente `EVALUATOR_POLLING_INTERVAL_SECS`. +`next_poll_secs` é opcional; se omitido, o servidor usa o valor +`default_poll_interval_secs` do avaliador em `/config` como fallback e, em seguida, +a própria variável de ambiente `EVALUATOR_POLLING_INTERVAL_SECS`. **Erro terminal no lado do avaliador:** @@ -158,21 +158,21 @@ variável de ambiente `EVALUATOR_POLLING_INTERVAL_SECS`. { "status": "error", "error": "model service unavailable" } ``` -O servidor trata qualquer outro corpo 2xx como um erro de protocolo e registra um +O servidor trata qualquer outro corpo 2xx como erro de protocolo e registra um `error` terminal para a sessão. --- ## Escrevendo um avaliador com o SDK -Você não precisa implementar o contrato HTTP manualmente. O pacote Python `agenteye-evaluator` -fornece um wrapper FastAPI tipado que cuida da autenticação, roteamento e +Você não precisa implementar o contrato HTTP manualmente. O pacote Python +`agenteye-evaluator` fornece um wrapper FastAPI tipado que cuida de autenticação, roteamento e dos formatos de requisição/resposta por você. O Failproof AI Observability também inclui um **avaliador de referência funcional** que -pontua `helpfulness`, `tool_efficiency` e `factuality` a partir do formato da +pontua `helpfulness`, `tool_efficiency` e `factuality` com base no formato da transcrição. Copie-o como ponto de partida e substitua pela sua própria lógica: um -juiz LLM, um motor de regras, o que melhor se adequar ao seu padrão de qualidade. +juiz LLM, um motor de regras, o que melhor se encaixar nos seus critérios de qualidade. Avaliador mínimo viável: @@ -193,14 +193,14 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -A instância `app` roda sob qualquer servidor ASGI, portanto `uvicorn module:app` a inicializa. +A instância `app` é executada em qualquer servidor ASGI, então `uvicorn module:app` a inicia. -Para avaliadores que precisam adiar trabalho pesado, retorne `JobPending` +Para avaliadores que precisam adiar trabalho custoso, retorne `JobPending` em vez disso e registre um handler `@app.job_lookup`; o servidor do Observability -faz polling em `GET /evaluate/{job_id}` até que você retorne um status terminal ou o +consulta `GET /evaluate/{job_id}` até que você retorne um status terminal ou o limite `EVALUATOR_MAX_POLL_DURATION_SECS` (padrão: 1 h) seja atingido. -A referência completa da API, o padrão assíncrono e o esquema de eventos estão documentados no +A referência completa da API, o padrão assíncrono e o schema de eventos estão documentados no README do SDK `agenteye-evaluator`. --- @@ -208,41 +208,41 @@ README do SDK `agenteye-evaluator`. ## Executando seu avaliador O avaliador é **seu serviço** — o Failproof AI Observability não inclui um -avaliador padrão, então você o constrói e executa onde preferir. -Ele roda sob qualquer servidor ASGI (por exemplo, `uvicorn my_evaluator:app`); sirva -as rotas `/health`, `/config` e `/evaluate` conforme o -[contrato HTTP](#http-contract) e então aponte o servidor para ele (veja +avaliador padrão, então você o cria e executa onde quer que execute seus próprios serviços. +Ele é executado em qualquer servidor ASGI (por exemplo, `uvicorn my_evaluator:app`); sirva +as rotas `/health`, `/config` e `/evaluate` do +[contrato HTTP](#http-contract) e, em seguida, aponte o servidor para ele (consulte [Configurando o servidor](#configuring-the-server)). -Quando o avaliador estiver acessível, `GET /health` retorna `{"status":"ok"}`. Após -uma execução completa do agente, `GET /evaluations` no servidor retorna uma linha com -`status: "done"` e as pontuações produzidas pelo seu avaliador. +Assim que o avaliador estiver acessível, `GET /health` retorna `{"status":"ok"}`. Depois +que um agente executa de ponta a ponta, `GET /evaluations` no servidor retorna uma linha com +`status: "done"` e as pontuações que seu avaliador produziu. --- ## Configurando o servidor -Defina no processo do servidor: +Configure no processo do servidor: | Variável de ambiente | Significado | |---|---| -| `EVALUATOR_ENDPOINT` | URL base do seu avaliador (`http://evaluator:9000`). Sem definição = pipeline desabilitado. | +| `EVALUATOR_ENDPOINT` | URL base do seu avaliador (`http://evaluator:9000`). Não configurado = pipeline desativado. | | `EVALUATOR_TOKEN` | Bearer token. Deve ser igual ao valor configurado no serviço avaliador. | | `EVALUATOR_WORKERS` | Tarefas de worker por instância do servidor (padrão: 2). | -| `EVALUATOR_CLAIM_BATCH` | Linhas processadas por tick do worker (padrão: 4). Os lotes são processados **de forma concorrente**; a concorrência efetiva no endpoint do avaliador é `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_CLAIM_BATCH` | Linhas reivindicadas por tick do worker (padrão: 4). Os lotes são processados **de forma concorrente**; a concorrência efetiva no endpoint do avaliador é `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | | `EVALUATOR_POLL_IDLE_SECS` | Quanto tempo um worker dorme entre tentativas de despacho quando nenhuma avaliação está pendente (padrão: 2s). | | `EVALUATOR_POLLING_INTERVAL_SECS` | Fallback final para o intervalo de `GET /evaluate/{id}` quando nem `next_poll_secs` por resposta nem `default_poll_interval_secs` do avaliador estão definidos (padrão: 10s). | | `EVALUATOR_REQUEST_TIMEOUT_MS` | Timeout por requisição (padrão: 30000). | | `EVALUATOR_MAX_ATTEMPTS` | Após esse número de falhas transitórias, o resultado é registrado como `error` terminal (padrão: 5). | | `EVALUATOR_CONFIG_REFRESH_SECS` | Intervalo de `GET /config` (padrão: 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Tempo máximo de relógio que uma sessão pode permanecer na fila de polling antes de ser encerrada como `timeout` (padrão: 3600s). Protege contra avaliadores que ficam retornando `pending` indefinidamente. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Tempo máximo de clock que uma sessão pode permanecer na fila de polling antes de ser encerrada como `timeout` (padrão: 3600s). Protege contra avaliadores que ficam retornando `pending` indefinidamente. | -Para ativar a pontuação automática, defina tanto `EVALUATOR_ENDPOINT` quanto -`EVALUATOR_TOKEN` no servidor e, em seguida, reinicie-o para aplicar a mudança. Com -`EVALUATOR_ENDPOINT` não definido, o pipeline permanece inativo. +Para ativar a pontuação automática, configure tanto `EVALUATOR_ENDPOINT` quanto +`EVALUATOR_TOKEN` no servidor e reinicie-o para aplicar as mudanças. Com +`EVALUATOR_ENDPOINT` não configurado, o pipeline permanece inativo. -Os ajustes acima são opcionais; defina as variáveis de ambiente correspondentes -no servidor somente se precisar sobrescrever os valores padrão. +Os parâmetros de ajuste acima são opcionais; configure as variáveis de ambiente +correspondentes no servidor somente se precisar sobrescrever os valores padrão. --- @@ -250,22 +250,22 @@ no servidor somente se precisar sobrescrever os valores padrão. | Método | Caminho | Permissão necessária | Finalidade | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Consultar resultados terminais. Suporta `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` tem padrão 50 e máximo 200 (diferente de `/events`, que tem máximo 1000). `environment` aceita uma lista separada por vírgula (ex.: `environment=prod,staging`); valores únicos também funcionam. Com `latest_per_session=true`, a resposta contém no máximo uma linha por `session_id` (a mais recente por `completed_at`), usada pela página de lista de sessões para condensar a linha do tempo de avaliações de uma sessão ao seu título atual. O padrão é false (retorna o histórico completo). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | Métricas consolidadas de saúde de avaliação para um subconjunto filtrado: contagem total, breakdown de done/error/timeout, estatísticas por chave de pontuação (contagem/média/mín/máx/p50 sobre as chaves arbitrárias de `scores`) e uma linha do tempo por intervalos de tempo. Aceita os **mesmos parâmetros de filtro que `/evaluations`** mais `featured_keys` (CSV de chaves de pontuação para tendências) e `latest_per_session`. Alimenta o recurso de Dashboards; as métricas são exatas sobre todo o conjunto correspondente, sem amostragem. | -| `GET` | `/evaluations/environments` | `evaluations:read` | Valores distintos de environment da tabela `evaluations`. Usado para preencher dropdowns de filtro com escopo de dados legíveis por avaliação. | +| `GET` | `/evaluations` | `evaluations:read` | Consulta resultados terminais. Aceita `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` padrão é 50 e limitado a 200 (diferente de `/events`, que limita a 1000). `environment` aceita uma lista separada por vírgulas (ex.: `environment=prod,staging`); valores únicos ainda funcionam. Com `latest_per_session=true`, a resposta contém no máximo uma linha por `session_id` (a mais recente por `completed_at`) usada pela página de listagem de sessões para recolher a linha do tempo de avaliação de uma sessão ao seu estado atual. Padrão: false (retorna o histórico completo). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | Métricas consolidadas de saúde de avaliação para um conjunto filtrado: contagem total, detalhamento done/error/timeout, estatísticas por chave de pontuação (count/avg/min/max/p50 sobre as chaves arbitrárias de `scores`) e uma linha do tempo por bucket de tempo. Aceita os **mesmos parâmetros de filtro que `/evaluations`** mais `featured_keys` (CSV de chaves de pontuação para tendências) e `latest_per_session`. Alimenta o recurso de Dashboards; as métricas são exatas sobre todo o conjunto correspondente, não amostradas. | +| `GET` | `/evaluations/environments` | `evaluations:read` | Valores distintos de environment da tabela `evaluations`. Usado para preencher dropdowns de filtro com escopo nos dados legíveis por avaliação. | | `GET` | `/evaluation-jobs` | `evaluations:read` | Visibilidade sobre avaliações em andamento. Filtre por `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | Transmitir os eventos brutos de uma sessão. Suporta `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` e `order`. `order` é `desc` (mais recente primeiro, padrão) ou `asc` (mais antigo primeiro); um valor não reconhecido recorre a `desc`. Pagine via cursor usando o `next_cursor` da resposta (um id de evento): passe-o de volta como `cursor` para obter a próxima página; com `asc` a próxima página contém eventos após esse id, com `desc` os eventos antes dele. `limit` tem padrão 50 e máximo 1000. | -| `GET` | `/sessions/:session_id/export` | `events:read` | Retorna o corpo JSON exato que o avaliador receberia para esta sessão, servido como um anexo para download chamado `session-.json`. Útil para reproduzir sessões de produção pelo `agenteye-evaluator` em testes offline. Os bytes são idênticos ao que o pipeline do avaliador envia. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Enfileirar uma nova avaliação para uma sessão; executa independentemente de uma avaliação anterior existir. O novo resultado é **anexado** à linha do tempo de avaliações da sessão em vez de sobrescrever o anterior, para que as pontuações anteriores permaneçam visíveis como histórico. Retorna `202` ao enfileirar, `404` para uma sessão desconhecida, `409` se uma avaliação já estiver em andamento. Use isso após implantar um novo avaliador ou para sessões que nunca emitiram `agent_end`. | +| `GET` | `/events` | `events:read` | Transmite os eventos brutos de uma sessão. Aceita `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` e `order`. `order` é `desc` (mais recente primeiro, padrão) ou `asc` (mais antigo primeiro); um valor não reconhecido usa `desc` como fallback. Pagine via `next_cursor` da resposta (um id de evento): passe-o de volta como `cursor` para obter a próxima página; com `asc` a próxima página são os eventos após aquele id, com `desc` os eventos antes dele. `limit` padrão é 50 e limitado a 1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | Retorna o corpo JSON exato que o avaliador receberia para essa sessão, servido como um anexo para download chamado `session-.json`. Útil para reproduzir sessões de produção no `agenteye-evaluator` para testes offline. Os bytes são idênticos ao que o pipeline do avaliador envia. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Enfileira uma nova avaliação para uma sessão; executa independentemente de existir ou não uma avaliação anterior. O novo resultado é **anexado** à linha do tempo de avaliação da sessão em vez de sobrescrever o anterior, para que as pontuações anteriores permaneçam visíveis como histórico. Retorna `202` ao enfileirar, `404` para sessão desconhecida, `409` se uma avaliação já está em andamento. Use isso após implantar um novo avaliador ou para sessões que nunca emitiram `agent_end`. | -### Filtragem por intervalo de pontuação: `score_filters` +### Filtrando por intervalo de pontuação: `score_filters` `GET /evaluations` aceita um parâmetro opcional `score_filters` que -restringe resultados por valores numéricos dentro do objeto `scores`. O -parâmetro é uma lista separada por vírgula de entradas `chave:mín..máx`; qualquer -um dos limites pode ser omitido. Múltiplas entradas são combinadas com AND lógico. Linhas +restringe os resultados por valores numéricos dentro do objeto `scores`. O +parâmetro é uma lista separada por vírgulas de entradas `key:min..max`; qualquer +limite pode ser omitido. Múltiplas entradas se combinam com AND lógico. Linhas onde a chave nomeada está ausente ou não é numérica são excluídas. Uma requisição pode -ter no máximo 20 entradas de filtro; exceder isso retorna HTTP 400. +conter no máximo 20 entradas de filtro; exceder esse limite retorna HTTP 400. Exemplos: ```text @@ -275,28 +275,28 @@ GET /evaluations?score_filters=helpfulness:0.5..0.8 # tool_efficiency no máximo 0.3 (sem limite inferior) GET /evaluations?score_filters=tool_efficiency:..0.3 -# helpfulness >= 0.5 E factuality >= 0.9 +# helpfulness >= 0.5 AND factuality >= 0.9 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` -Cada objeto de resposta de `/evaluations` tem os seguintes campos: +Cada objeto de resposta de `/evaluations` tem estes campos: | Campo | Tipo | Notas | |---|---|---| -| `evaluation_id` | string (UUID) | O identificador canônico desta avaliação terminal. Cada avaliação terminal recebe um novo UUID; uma única sessão pode ter múltiplas. | +| `evaluation_id` | string (UUID) | O identificador canônico para esta avaliação terminal. Cada avaliação terminal recebe um novo UUID; uma única sessão pode ter múltiplos. | | `id` | string (UUID) | Alias de compatibilidade retroativa com o mesmo valor que `evaluation_id`. | | `session_id` | string | A sessão contra a qual esta avaliação foi executada. Uma sessão pode ter múltiplas avaliações na linha do tempo. | | `agent_id` | string | Identifica o agente que produziu a sessão. | | `environment` | string | Rótulo de ambiente copiado da sessão. | | `status` | enum | Um de `"done"`, `"error"`, `"timeout"`. | | `scores` | object \| null | Pontuações retornadas pelo seu avaliador. | -| `reasoning` | object \| null | Mapa opcional de justificativa por pontuação retornado pelo seu avaliador. As chaves geralmente espelham as de `scores`. O dashboard renderiza cada entrada abaixo da barra de pontuação correspondente. | -| `summary` | string \| null | Narrativa geral opcional em um parágrafo retornada pelo seu avaliador. O dashboard a renderiza acima do detalhamento por pontuação como título da avaliação. | -| `error` | string \| null | Preenchido somente em `"error"` / `"timeout"`. | +| `reasoning` | object \| null | Mapa de justificativa por pontuação opcional retornado pelo seu avaliador. As chaves geralmente espelham as de `scores`. O dashboard renderiza cada entrada abaixo da sua barra de pontuação. | +| `summary` | string \| null | Narrativa geral opcional de um parágrafo retornada pelo seu avaliador. O dashboard renderiza isso acima do detalhamento por pontuação como o título da avaliação. | +| `error` | string \| null | Preenchido apenas em `"error"` / `"timeout"`. | | `attempt_count` | integer | Número de tentativas de despacho (≥ 1). | | `duration_ms` | integer \| null | Duração da tentativa final. | | `completed_at` | string (ISO 8601 UTC) | Quando o resultado terminal foi registrado. Os resultados são ordenados por `completed_at` (mais recente primeiro). | -| `created_at` | string (ISO 8601 UTC) | Carrega o mesmo timestamp que `completed_at` (semântica de escrita única). | +| `created_at` | string (ISO 8601 UTC) | Contém o mesmo timestamp que `completed_at` (semântica de escrita única). | --- @@ -305,69 +305,68 @@ Cada objeto de resposta de `/evaluations` tem os seguintes campos: | Permissão | Concede | |---|---| | `evaluations:read` | Listar resultados de avaliação, visualizar pontuações no dashboard e carregar métricas de saúde do dashboard. | -| `evaluations:trigger` | Enfileirar manualmente uma avaliação para uma sessão via `POST /sessions/:session_id/re-evaluate` ou pelo botão de re-avaliação no dashboard. | +| `evaluations:trigger` | Enfileirar manualmente uma avaliação para uma sessão via `POST /sessions/:session_id/re-evaluate` ou o botão de reavaliar no dashboard. | | `dashboards:read` | Visualizar dashboards salvos (também requer `evaluations:read` para carregar suas métricas). | | `dashboards:write` | Criar e editar dashboards. | | `dashboards:delete` | Excluir dashboards. | -O admin bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) recebe todas essas permissões automaticamente. +O administrador bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) recebe essas permissões automaticamente. --- ## Visualizando resultados -- **`/sessions/`**: linha do tempo de eventos + painel direito exibindo as pontuações - da sessão e qualquer erro da tentativa de despacho. Se sua chave tiver - `evaluations:trigger`, um botão de **re-avaliar** aparece ao lado do botão de exportar, - útil para sessões que nunca emitiram `agent_end` ou para atualizar - pontuações após implantar um novo avaliador. O dashboard faz polling pelo - novo resultado e atualiza o painel direito quando ele chegar. -- **`/sessions`**: grade de sessões filtráveis; a coluna de pontuação exibe o +- **`/sessions/`**: linha do tempo de eventos + painel direito mostrando as + pontuações da sessão e qualquer erro da tentativa de despacho. Se sua chave tiver + `evaluations:trigger`, um botão **reavaliar** aparece ao lado do botão de exportar, + útil para sessões que nunca emitiram `agent_end` ou para atualizar pontuações + após implantar um novo avaliador. O dashboard monitora o novo resultado e atualiza o painel direito quando ele chegar. +- **`/sessions`**: grade de sessões filtrável; a coluna de pontuação mostra o status de avaliação e as pontuações de cada sessão de forma rápida. -- **`/dashboards`**: visualizações salvas de saúde de avaliação (veja [Dashboards](#dashboards) abaixo). +- **`/dashboards`**: visualizações salvas de saúde de avaliação (consulte [Dashboards](#dashboards) abaixo). -![A grade de Sessões com pílulas de status de avaliação por sessão e emblemas de pontuação codificados por cor (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) +![A grade de Sessões com pílulas de status de avaliação por sessão e badges de pontuação coloridos (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) -*A grade de sessões exibe o status de avaliação e as pontuações de cada execução de forma rápida; emblemas em vermelho/âmbar/verde destacam pontuações baixas.* +*A grade de sessões mostra o status de avaliação e as pontuações de cada execução de forma rápida; badges vermelho/âmbar/verde destacam pontuações baixas.* --- ## Dashboards -A página **Dashboards** (`/dashboards`) permite salvar uma combinação de -filtros de avaliação como uma visualização nomeada e reutilizável, e acompanhar como esse -subconjunto de avaliações está se saindo de forma rápida. Os dashboards são **compartilhados em toda a sua organização**; +A página de **Dashboards** (`/dashboards`) permite salvar uma combinação de filtros de avaliação +como uma visualização nomeada e reutilizável, e acompanhar como aquela fatia de avaliações está +se saindo de forma rápida. Os Dashboards são **compartilhados em toda a sua organização**; todos com `dashboards:read` veem o mesmo conjunto. Cada dashboard fixa: - **Filtros**: os mesmos controles da página de sessões: ambiente, status, - agente, uma janela de tempo rolante e filtros de intervalo de pontuação (`chave:mín..máx`). -- **Uma configuração de exibição**: quais chaves de pontuação destacar, os limites de saúde - verde/âmbar/vermelho, quais painéis exibir e se deve condensar à avaliação mais recente - por sessão. + agente, uma janela de tempo contínua e filtros de intervalo de pontuação (`key:min..max`). +- **Uma configuração de exibição**: quais chaves de pontuação destacar, os limiares de saúde + verde/âmbar/vermelho, quais painéis mostrar e se deve recolher para a avaliação + mais recente por sessão. -Cada card exibe o número de sessões correspondentes, um breakdown de done/error/timeout, -a média de cada pontuação destacada e um pequeno sparkline de tendência. Ao abrir um -dashboard, os painéis são exibidos em tamanho completo; **"abrir em sessões"** leva você à -página de sessões pré-filtrada exatamente para aquele subconjunto. As métricas são calculadas -no servidor sobre todo o conjunto correspondente (via `GET /evaluations/aggregate`), portanto -os números são exatos em vez de amostrados. +Cada card mostra o número de sessões correspondentes, um detalhamento done/error/timeout, +a média de cada pontuação destacada e um pequeno sparkline de tendência. Abrir um +dashboard mostra os painéis em tamanho completo; **"abrir em sessões"** leva você à +página de sessões pré-filtrada exatamente para aquela fatia. As métricas são calculadas +no servidor sobre todo o conjunto correspondente (via `GET /evaluations/aggregate`), então +os números são exatos, não amostrados. -![Um dashboard de saúde de avaliação com barras de pontuação média por dimensão do avaliador, um breakdown de ferramenta ok vs. erro, principais ferramentas e uma tendência de eventos por hora](/agenteye/images/dashboard-quality.png) +![Um dashboard de saúde de avaliação com barras de pontuação média por dimensão do avaliador, um detalhamento de ok vs. erro de ferramentas, principais ferramentas e uma tendência de eventos por hora](/agenteye/images/dashboard-quality.png) **Permissões:** visualizar requer tanto `dashboards:read` quanto `evaluations:read`; criar e editar requer `dashboards:write`; excluir requer `dashboards:delete`. -O admin bootstrap recebe todas essas permissões automaticamente. +O administrador bootstrap recebe todas essas permissões automaticamente. --- ## Solução de problemas -**Sessões existem, mas nenhuma avaliação é criada.** Confirme que `EVALUATOR_ENDPOINT` -está definido no processo do servidor, que o servidor e o avaliador compartilham o mesmo -valor de `EVALUATOR_TOKEN` e que o endpoint `/health` do avaliador está -acessível a partir do servidor. Com `EVALUATOR_ENDPOINT` não definido, o pipeline é inativo. +**As sessões existem, mas nenhuma avaliação é criada.** Confirme que `EVALUATOR_ENDPOINT` +está configurado no processo do servidor, que o servidor e o avaliador compartilham o mesmo +valor de `EVALUATOR_TOKEN`, e que o endpoint `/health` do avaliador é +acessível a partir do servidor. Com `EVALUATOR_ENDPOINT` não configurado, o pipeline é inativo. **Avaliações em andamento se acumulam.** Consulte `GET /evaluation-jobs` para ver a fila em andamento. Inspecione `attempt_count`, `next_attempt_at` e `last_error` @@ -377,16 +376,16 @@ avaliador assíncrono que retorna `pending` indefinidamente (veja abaixo). **Sessões concluídas, mas sem avaliação terminal.** Consulte `GET /evaluation-jobs?status=polling`; o resultado pode ainda estar em andamento. -Se um job estiver preso em `pending`, o servidor está tendo dificuldade para alcançar o +Se uma tarefa estiver travada em `pending`, o servidor está com dificuldade de alcançar o avaliador; verifique se o avaliador está em execução e se `EVALUATOR_TOKEN` corresponde. **`HTTP 401 from evaluator: invalid bearer token`.** O `EVALUATOR_TOKEN` no servidor não corresponde ao valor configurado no serviço avaliador. Eles devem ser idênticos. -**O avaliador assíncrono retorna `pending` indefinidamente.** O servidor faz polling em +**O avaliador assíncrono retorna `pending` indefinidamente.** O servidor consulta `GET /evaluate/{job_id}` até que o avaliador retorne `done` ou `error`, ou -até que `EVALUATOR_MAX_POLL_DURATION_SECS` (padrão: 1 h) expire. Após o limite, +até que `EVALUATOR_MAX_POLL_DURATION_SECS` (padrão: 1 h) seja atingido. Após o limite, a avaliação é registrada como `timeout` e removida da fila em andamento. Aumente `EVALUATOR_MAX_POLL_DURATION_SECS` se seu avaliador legitimamente precisar de mais tempo do que o padrão. @@ -395,7 +394,7 @@ de mais tempo do que o padrão. ## Próximos passos -- [Habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill): tenha um agente de código projetando suas dimensões a partir de sessões reais e construindo este serviço para você. +- [Habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill): tenha um agente de codificação projetando suas dimensões com base em sessões reais e construindo este serviço para você. - [SDK Python](/pt-br/agenteye/python-sdk): emita os eventos `agent_end` que acionam a pontuação. - [Chaves de API](/pt-br/agenteye/api-keys): as permissões `evaluations:read` e `evaluations:trigger`. -- [Auditorias](/pt-br/agenteye/audits): o outro recurso de qualidade automatizado do Observability, para revisão baseada em políticas. \ No newline at end of file +- [Auditorias](/pt-br/agenteye/audits): o outro recurso de qualidade automatizada do Observability, para revisão baseada em políticas. \ No newline at end of file diff --git a/docs/pt-br/agenteye/evaluations.mdx b/docs/pt-br/agenteye/evaluations.mdx index 0823e4a7..71887508 100644 --- a/docs/pt-br/agenteye/evaluations.mdx +++ b/docs/pt-br/agenteye/evaluations.mdx @@ -1,51 +1,50 @@ --- title: "Avaliações" -description: "Problemas de qualidade chegam até você antes de virar reclamação de usuário." +description: "Problemas de qualidade chegam até você agora, em vez de você ficar sabendo por uma reclamação de usuário." --- +Problemas de qualidade chegam até você agora, em vez de você ficar sabendo por uma reclamação de usuário. Conecte seu próprio serviço de pontuação uma única vez e a Observabilidade do Failproof AI avalia automaticamente cada execução concluída — assim, uma queda na utilidade ou um pico de alucinações aparece por conta própria, antes que um cliente sinta o impacto. -Problemas de qualidade chegam até você antes de virar reclamação de usuário. Conecte seu próprio serviço de pontuação uma única vez e a Observabilidade do Failproof AI avalia automaticamente cada execução concluída — assim, uma queda na utilidade ou um pico de alucinações aparece sozinho, antes que qualquer cliente sinta. +![A grade de Sessões com uma coluna de pontuação: cada execução traz um indicador de status de avaliação e emblemas codificados por cor para utilidade, factualidade e eficiência de ferramentas](/agenteye/images/sessions-list.png) -![A grade de Sessões com uma coluna de pontuação: cada execução exibe um indicador de status de avaliação e badges com código de cores para utilidade, factualidade e eficiência de ferramentas](/agenteye/images/sessions-list.png) +*Cada execução na grade de sessões exibe suas pontuações; emblemas vermelhos, âmbar e verdes destacam as execuções problemáticas sem que você precise abrir uma única transcrição.* -*Cada execução na grade de sessões carrega suas pontuações; badges vermelhos, âmbar e verdes destacam as execuções problemáticas sem que você precise abrir uma única transcrição.* +## Pare de inspecionar execuções manualmente -## Pare de amostrar execuções manualmente +Antes, você verificava um punhado de execuções e torcia para que o restante estivesse bem. Agora, toda sessão concluída é pontuada no momento em que termina, nas dimensões que importam para você: utilidade, eficiência de ferramentas, factualidade, segurança — qualquer que seja o seu padrão de qualidade. Você define as chaves de pontuação; a Observabilidade do Failproof AI armazena, acompanha tendências e exibe tudo o que seu avaliador retornar. Nenhuma execução passa sem pontuação, e você deixa de descobrir regressões por um ticket de suporte. -Antes, você verificava algumas execuções aleatoriamente e torcia para que o restante estivesse bem. Agora, toda sessão concluída é pontuada no momento em que termina, nas dimensões que importam para você: utilidade, eficiência de ferramentas, factualidade, segurança — qualquer que seja o seu critério de qualidade. Você define as chaves de pontuação; a Observabilidade do Failproof AI armazena, analisa tendências e exibe tudo que o seu avaliador retornar. Nenhuma execução fica sem pontuação, e você para de descobrir regressões por meio de tickets de suporte. - -As pontuações aparecem na grade de sessões em **`//sessions`** (barra lateral → *observe* → *sessions*), com um cluster de badges por linha. Quer ver apenas as execuções que ficaram abaixo do esperado? Filtre a grade por intervalo de pontuação — por exemplo, utilidade abaixo de 0,5 — e acesse exatamente as execuções que valem a pena examinar. Para visualizar pontuações, é necessária a permissão `evaluations:read`. +As pontuações aparecem na grade de sessões em **`//sessions`** (barra lateral → *observe* → *sessions*), com um conjunto de emblemas por linha. Quer ver apenas as execuções que ficaram abaixo do esperado? Filtre a grade por faixa de pontuação — digamos, utilidade abaixo de 0,5 — e acesse exatamente as execuções que merecem atenção. Para visualizar pontuações, é necessária a permissão `evaluations:read`. ## Entenda por que uma execução teve pontuação baixa -Um número te diz que uma execução foi fraca; a página da sessão te diz o porquê. Abra qualquer execução e o painel lateral começa com o resumo geral, depois exibe uma barra por dimensão com o próprio raciocínio do avaliador abaixo de cada uma — assim você vai de "essa execução tirou 0,4 em factualidade" até a afirmação exata que deu errado, em segundos. +Um número indica que uma execução foi fraca; a página da sessão mostra o porquê. Abra qualquer execução e o painel lateral direito começa com um resumo geral e, em seguida, exibe uma barra por dimensão com o raciocínio do próprio avaliador abaixo de cada uma — assim, você vai de "isso pontuou 0,4 em factualidade" à afirmação exata que estava errada em segundos. -![O painel lateral de uma sessão: o resumo da avaliação no topo, depois barras de pontuação por dimensão cada uma com uma linha de raciocínio, ao lado da linha do tempo completa de eventos](/agenteye/images/session-detail.png) +![O painel lateral direito de uma sessão: o resumo da avaliação no topo, seguido de barras de pontuação por dimensão com uma linha de raciocínio cada, ao lado da linha do tempo completa de eventos](/agenteye/images/session-detail.png) -*A visualização de detalhe da sessão: resumo, barras de pontuação por dimensão e o raciocínio por trás de cada pontuação, bem ao lado da linha do tempo de eventos da execução.* +*A visualização de detalhe da sessão: resumo, barras de pontuação por dimensão e o raciocínio por trás de cada pontuação, ao lado da linha do tempo de eventos da execução.* -Implantou um avaliador mais preciso, ou está olhando para uma execução que travou antes de ser pontuada? Um botão **re-evaluate** (bloqueado por `evaluations:trigger`) reponua a sessão no lugar e adiciona o novo resultado à sua linha do tempo, preservando as pontuações anteriores como histórico. Você o encontrará em **`//sessions/`**. +Publicou um avaliador mais preciso, ou está analisando uma execução que falhou antes de ser pontuada? Um botão de **re-avaliar** (protegido por `evaluations:trigger`) reprocessa a pontuação da sessão e adiciona o novo resultado à sua linha do tempo, mantendo as pontuações anteriores visíveis como histórico. Você o encontrará em **`//sessions/`**. ## Acompanhe a tendência de qualidade em toda a frota -Uma execução com pontuação baixa é ruído; uma coorte inteira caindo é um sinal. Dashboards salvos transformam suas pontuações em uma tendência que você pode acompanhar de relance: média de utilidade desta semana versus a semana passada, por agente, por ambiente. +Uma execução com pontuação baixa é ruído; uma coorte inteira caindo é um sinal. Dashboards salvos transformam suas pontuações em uma tendência que você pode acompanhar de relance: média de utilidade desta semana comparada à da semana passada, por agente, por ambiente. ![Um dashboard de qualidade: barras de pontuação média por dimensão do avaliador ao lado de uma tendência ao longo do tempo](/agenteye/images/dashboard-quality.png) -*Um dashboard de qualidade salvo mostra a tendência das chaves de pontuação que você destaca, tornando uma deriva lenta óbvia muito antes de se tornar um incidente.* +*Um dashboard de qualidade salvo acompanha as chaves de pontuação que você destaca, tornando uma deriva gradual óbvia muito antes de se tornar um incidente.* -Os dashboards ficam em **`//dashboards`** (barra lateral → *analyze* → *dashboards*), são compartilhados com toda a sua organização, e cada card consolida as sessões correspondentes: quantas houve, a média de cada pontuação destacada e um sparkline de tendência. "Open in sessions" leva você diretamente às execuções pré-filtradas por trás de qualquer número. Para visualizar, são necessárias as permissões `dashboards:read` e `evaluations:read`. +Os dashboards ficam em **`//dashboards`** (barra lateral → *analyze* → *dashboards*), são compartilhados com toda a sua organização, e cada card consolida as sessões correspondentes: quantidade, média de cada pontuação destacada e um gráfico de tendência em miniatura. "Abrir em sessões" leva você diretamente às execuções pré-filtradas por trás de qualquer número. Para visualizar, são necessárias as permissões `dashboards:read` e `evaluations:read`. ## Conecte um avaliador uma única vez -A pontuação é opt-in e fica completamente desativada até que você aponte a Observabilidade do Failproof AI para um avaliador. Você sobe um pequeno serviço HTTP (a Observabilidade inclui uma referência funcional que você pode copiar), define dois valores no seu servidor, e a partir daí toda execução é pontuada automaticamente. O guia completo, o contrato de pontuação e o SDK estão no guia detalhado. +A pontuação é opcional e permanece completamente desativada até que você aponte a Observabilidade do Failproof AI para um avaliador. Você sobe um pequeno serviço HTTP (a Observabilidade inclui uma referência funcional que você pode copiar), define dois valores no seu servidor, e todas as execuções a partir daí são pontuadas automaticamente. O guia completo, o contrato de pontuação e o SDK estão no guia detalhado. -Não tem certeza de quais dimensões valem a pena pontuar? A [habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill) faz com que seu agente de código descubra isso com base nas suas próprias sessões, depois cria e implanta o serviço. +Não sabe quais dimensões vale a pena pontuar? A [habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill) faz seu agente de codificação descobrir isso a partir das suas próprias sessões, e depois criar e implantar o serviço. ## Relacionados - [Suite de avaliação](/pt-br/agenteye/evaluation-suite): conecte seu avaliador, o contrato de pontuação e o SDK. -- [Habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill): deixe um agente de código escolher suas dimensões de pontuação e construir o avaliador. -- [Sessões](/pt-br/agenteye/sessions): a grade execução por execução onde as pontuações aparecem. +- [Habilidade de agente avaliador](/pt-br/agenteye/evaluator-skill): deixe um agente de codificação escolher suas dimensões de pontuação e criar o avaliador. +- [Sessions](/pt-br/agenteye/sessions): a grade execução por execução onde as pontuações aparecem. - [Dashboards](/pt-br/agenteye/dashboards): salve e compartilhe tendências de qualidade em toda a sua organização. -- [Auditorias](/pt-br/agenteye/audits): outro recurso automático de qualidade da Observabilidade, para investigações entre sessões. \ No newline at end of file +- [Audits](/pt-br/agenteye/audits): o outro recurso de qualidade automática da Observabilidade, para investigações entre sessões. \ No newline at end of file diff --git a/docs/pt-br/agenteye/evaluator-skill.mdx b/docs/pt-br/agenteye/evaluator-skill.mdx index c38fdd66..cbe35ea6 100644 --- a/docs/pt-br/agenteye/evaluator-skill.mdx +++ b/docs/pt-br/agenteye/evaluator-skill.mdx @@ -1,75 +1,75 @@ --- -title: "Habilidade de Agente Avaliador de Observabilidade Failproof AI" -description: "Vá de 'acho que nosso agente às vezes falha' a um serviço de pontuação implantado, com seu agente de codificação tanto decidindo quanto construindo." +title: "Skill de Avaliador de Observabilidade do Failproof AI" +description: "Vá de 'acho que nosso agente às vezes erra' a um serviço de pontuação em produção, com seu agente de código tanto decidindo o que avaliar quanto construindo o serviço." --- -Vá de *"acho que nosso agente às vezes falha"* a um serviço de pontuação implantado, com seu agente de codificação tanto decidindo quanto construindo. A **habilidade de avaliador de Observabilidade Failproof AI** (`agenteye-evaluator`) é uma *Agent Skill*: uma pequena pasta de instruções que um agente de codificação como Claude Code ou Codex carrega sob demanda. Ela ensina o agente a determinar quais dimensões de qualidade valem a pena rastrear para o *seu* agente, e então escrever, testar e implantar o [serviço avaliador](/pt-br/agenteye/evaluation-suite) que os pontua. +Vá de *"acho que nosso agente às vezes erra"* a um serviço de pontuação em produção, com seu agente de código tanto decidindo o que avaliar quanto construindo o serviço. A **skill de avaliador de Observabilidade do Failproof AI** (`agenteye-evaluator`) é uma *Agent Skill*: uma pequena pasta de instruções que um agente de código como Claude Code ou Codex carrega sob demanda. Ela ensina o agente a determinar quais dimensões de qualidade valem a pena monitorar para o *seu* agente, e depois escrever, testar e implantar o [serviço de avaliação](/pt-br/agenteye/evaluation-suite) que as pontua. -Ela **não** é um pontuador hospedado, um registro para o qual você faz upload, ou um sistema de plugins. Seu avaliador permanece sendo seu próprio serviço HTTP na sua própria infraestrutura, exatamente como descrito no guia [Evaluation suite](/pt-br/agenteye/evaluation-suite). A habilidade apenas ensina seu agente a construí-lo bem, de modo que tudo o que ela faz, você poderia fazer escrevendo o mesmo código. +Ela **não** é um pontuador hospedado, um registro para o qual você faz upload, nem um sistema de plugins. Seu avaliador continua sendo seu próprio serviço HTTP na sua própria infraestrutura, exatamente conforme descrito no guia de [Suíte de avaliação](/pt-br/agenteye/evaluation-suite). A skill apenas ensina seu agente a construí-lo bem — tudo o que ela faz, você mesmo poderia fazer escrevendo o mesmo código. --- ## A parte difícil é decidir o que pontuar -A superfície do SDK é pequena — um decorator e dois modelos — e um agente pode escrever isso apenas com o [contrato](/pt-br/agenteye/evaluation-suite#http-contract). Não é aí que os avaliadores falham. Eles falham porque pontuam a coisa errada, e um avaliador que pontua a coisa errada é pior do que nenhum: ele produz um dashboard que todos aprendem a ignorar. +A superfície do SDK é pequena — um decorator e dois models — e um agente consegue escrever isso a partir do [contrato](/pt-br/agenteye/evaluation-suite#http-contract) sozinho. Esse não é o ponto onde os avaliadores falham. Eles falham porque pontuam a coisa errada, e um avaliador que pontua a coisa errada é pior do que nenhum: ele produz um dashboard que todos aprendem a ignorar. -Por isso, a maior parte da habilidade é a etapa anterior a qualquer código. Ela faz o agente entrevistá-lo (*"descreva uma execução que correu bem; agora uma que correu mal"*), depois puxa suas sessões reais pelo [`agenteye` CLI](/pt-br/agenteye/cli) e as lê do início ao fim. Essas duas metades geralmente discordam, e a lacuna é exatamente o ponto: o que você pretende medir versus o que suas transcrições podem realmente suportar. Uma dimensão só sobrevive se for **computável** a partir dos eventos e **discriminatória** — se pontua 0,9 tanto na sua boa execução quanto na ruim, não ensina nada e é cortada. +Por isso, a maior parte da skill é a etapa anterior a qualquer código. Ela faz o agente te entrevistar (*"descreva uma execução que correu bem; agora uma que correu mal"*), depois puxa suas sessões reais pela [CLI `agenteye`](/pt-br/agenteye/cli) e as lê do início ao fim. As duas metades costumam discordar, e essa lacuna é o ponto central: o que você pretende medir versus o que suas transcrições conseguem de fato suportar. Uma dimensão só sobrevive se for **computável** a partir dos eventos e **discriminante** — se ela pontua 0,9 tanto na sua execução boa quanto na ruim, não ensina nada e é descartada. -O resultado é uma proposta de 2 a 4 dimensões com o raciocínio anexado, para você aprovar antes que uma linha seja escrita. +O resultado é uma proposta de 2 a 4 dimensões com o raciocínio anexado, para você aprovar antes de qualquer linha ser escrita. ```mermaid flowchart TD - YOU["você: 'quero avaliações para meu bot de suporte'"] --> AGENT["agente de codificação (Claude Code / Codex)
carrega a habilidade agenteye-evaluator"] + YOU["você: 'quero evals para meu bot de suporte'"] --> AGENT["agente de código (Claude Code / Codex)
carrega a skill agenteye-evaluator"] AGENT -->|"entrevista: como é bom vs ruim?"| YOU AGENT -->|"agenteye --json sessions / events"| DATA["suas sessões reais
o que realmente acontece"] DATA --> DIMS["2-4 dimensões, você aprova"] - DIMS --> SVC["seu serviço avaliador
SDK agenteye-evaluator"] - SVC --> SCORES["pontuações chegam no dashboard
e em agenteye evals"] + DIMS --> SVC["seu serviço de avaliação
SDK agenteye-evaluator"] + SVC --> SCORES["pontuações aparecem no dashboard
e em agenteye evals"] ``` --- -## Como ela se relaciona com as outras partes de avaliação +## Como se relaciona com as outras peças de avaliação -Quatro documentos cobrem pontuação, e eles se encadeiam em ordem: +Quatro documentos cobrem pontuação, e eles se passam a tocha em ordem: -| Página | O que é | Consulte quando | +| Página | O que é | Use quando | |---|---|---| -| **[Evaluations](/pt-br/agenteye/evaluations)** | O recurso: pontuações na grade de sessões, dashboards, reavaliar | Você quer saber o que a pontuação automática oferece | -| **[Evaluation suite](/pt-br/agenteye/evaluation-suite)** | O contrato HTTP, o SDK, as variáveis de ambiente do servidor | Você está implementando ou depurando o avaliador por conta própria | -| **Habilidade de avaliador** (este documento) | Uma porta de entrada em linguagem natural para projetar *e* construir o pontuador | Você quer ir de "quero avaliações" a um serviço em execução | -| **[CLI skill](/pt-br/agenteye/cli-skill)** | Uma porta de entrada em linguagem natural para o `agenteye` CLI | Você quer *ler* as pontuações que já possui | -| **[Python SDK skill](/pt-br/agenteye/python-sdk-skill)** | Uma porta de entrada em linguagem natural para instrumentar seu agente | Seu agente ainda não está emitindo sessões — não há nada para pontuar | +| **[Avaliações](/pt-br/agenteye/evaluations)** | O recurso: pontuações na grade de sessões, dashboards, re-avaliação | Você quer saber o que a pontuação automática oferece | +| **[Suíte de avaliação](/pt-br/agenteye/evaluation-suite)** | O contrato HTTP, o SDK, as variáveis de ambiente do servidor | Você está implementando ou depurando o avaliador por conta própria | +| **Skill de avaliador** (este doc) | Uma porta de entrada em linguagem natural para projetar *e* construir o pontuador | Você quer ir de "quero evals" a um serviço em execução | +| **[CLI skill](/pt-br/agenteye/cli-skill)** | Uma porta de entrada em linguagem natural para a CLI `agenteye` | Você quer *ler* as pontuações que já possui | +| **[Python SDK skill](/pt-br/agenteye/python-sdk-skill)** | Uma porta de entrada em linguagem natural para instrumentar seu agente | Seu agente ainda não emite sessões — não há nada para pontuar | ### vs. a CLI skill: construir versus ler -As duas habilidades são deliberadamente não sobrepostas, e instalar ambas é a configuração normal — o agente escolhe entre elas com base no que você pede: +As duas skills são deliberadamente não-sobrepostas, e instalar ambas é a configuração normal — o agente escolhe entre elas com base no que você pede: -- **`agenteye-evaluator`** (este documento) constrói a coisa que *produz* pontuações. Seu trabalho termina quando as pontuações chegam pela primeira vez. -- **[`agenteye-cli`](/pt-br/agenteye/cli-skill)** lê pontuações que já existem (`agenteye evals`). *"A qualidade caiu esta semana?"* é a pergunta dela, não desta habilidade. +- **`agenteye-evaluator`** (este doc) constrói o que *produz* pontuações. Seu trabalho termina quando as pontuações chegam pela primeira vez. +- **[`agenteye-cli`](/pt-br/agenteye/cli-skill)** lê pontuações que já existem (`agenteye evals`). *"A qualidade caiu esta semana?"* é a pergunta dela, não desta skill. --- ## Pré-requisitos -1. O **`agenteye` CLI instalado e com login efetuado** (`pipx install agenteye`, depois `agenteye login`). A habilidade depende dele duas vezes: para puxar as sessões reais com as quais projeta, e para confirmar que suas pontuações chegaram ao final. Seu login precisa de `events:read`, mais `evaluations:read` para essa verificação final. Como acontece com a CLI skill, ela **não pode** completar o login com código único enviado por e-mail por você. -2. **Um lugar para o avaliador residir.** Ele é construído em uma imagem e executado como um serviço de longa duração, portanto precisa de um repositório real, não de um arquivo temporário. Avaliadores geralmente vivem em seu próprio repositório, separado do agente sendo pontuado — a habilidade procura um existente e pergunta antes de criar um novo. +1. A **CLI `agenteye` instalada e autenticada** (`pipx install agenteye`, depois `agenteye login`). A skill a utiliza duas vezes: para puxar as sessões reais contra as quais projeta, e para confirmar que suas pontuações chegaram no final. Seu login precisa de `events:read`, mais `evaluations:read` para essa verificação final. Assim como com a CLI skill, ela **não consegue** completar o login com código de uso único enviado por e-mail por você. +2. **Um lugar para o avaliador residir.** Ele é construído em uma imagem e executado como um serviço de longa duração, então precisa de um repositório real, não de um arquivo temporário. Avaliadores frequentemente residem em seu próprio repositório, separado do agente sendo pontuado — a skill procura um existente e pergunta antes de criar um novo. 3. **O wheel do SDK `agenteye-evaluator`** — leia a próxima seção antes de deixar seu agente começar a digitar comandos `pip`. --- ## Onde obtê-la -A habilidade está publicada na coleção pública de habilidades da Failproof AI: +A skill está publicada na coleção pública de skills do Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -O repositório é público e a habilidade não precisa de nenhuma credencial própria — ela apenas aciona o `agenteye` CLI com a sessão com a qual *você* fez login, e escreve código no *seu* repositório. Observe que ela é distribuída como sua própria pasta e **não** está dentro do pacote `pipx install agenteye`, portanto não a procure lá. +O repositório é público e a skill não precisa de credenciais próprias — ela apenas aciona a CLI `agenteye` com a sessão em que *você* se autenticou, e escreve código no *seu* repositório. Note que ela é publicada como sua própria pasta e **não** está dentro do pacote `pipx install agenteye`, então não a procure lá. -## Instalando a habilidade +## Instalando a skill -O caminho mais rápido é o CLI [`skills`](https://skills.sh), que busca a pasta e a coloca onde seu agente procura: +O caminho mais rápido é a CLI [`skills`](https://skills.sh), que busca a pasta e a coloca onde seu agente procura: ```bash # Claude Code, somente este projeto @@ -82,18 +82,18 @@ npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g - npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -Depois gerencie como qualquer outra habilidade: +Depois gerencie-a como qualquer outra skill: ```bash npx skills list -a claude-code # o que está instalado -npx skills update agenteye-evaluator # baixar a versão mais recente +npx skills update agenteye-evaluator # obter a versão mais recente npx skills remove agenteye-evaluator # remover ``` Prefere instalar manualmente? Uma Agent Skill é apenas uma pasta contendo um `SKILL.md` (mais referências opcionais), então copiá-la também funciona: -- **Claude Code**: coloque a pasta `agenteye-evaluator/` em `~/.claude/skills/` (todos os projetos) ou `/.claude/skills/` (somente aquele repositório). Claude Code a descobre automaticamente — verifique com a lista `/skills`, ou simplesmente peça avaliações. -- **Codex (OpenAI)**: Codex lê o mesmo `SKILL.md`. O arquivo `agents/openai.yaml` incluído define `allow_implicit_invocation: true`, então o Codex seleciona automaticamente a habilidade quando uma tarefa combina; caso contrário, invoque-a explicitamente como `$agenteye-evaluator`. +- **Claude Code**: coloque a pasta `agenteye-evaluator/` em `~/.claude/skills/` (todos os projetos) ou `/.claude/skills/` (somente aquele repositório). Claude Code a descobre automaticamente — verifique com a lista `/skills`, ou simplesmente peça por evals. +- **Codex (OpenAI)**: o Codex lê o mesmo `SKILL.md`. O arquivo `agents/openai.yaml` incluído define `allow_implicit_invocation: true`, então o Codex seleciona automaticamente a skill quando uma tarefa se encaixa; caso contrário, invoque-a explicitamente como `$agenteye-evaluator`. --- @@ -101,67 +101,67 @@ Prefere instalar manualmente? Uma Agent Skill é apenas uma pasta contendo um `S > **Aviso:** Leia isso antes de deixar um agente instalar o SDK. -A habilidade é pública; o SDK que ela aciona não é. O `agenteye-evaluator` é distribuído apenas como um artefato de release privado e, ao contrário do `agenteye`, o nome está **sem registro no PyPI público** — então um simples `pip install agenteye-evaluator` poderia puxar o pacote de um desconhecido para o serviço que lê suas transcrições de produção. Isso é um problema de cadeia de suprimentos, não um erro de digitação. +A skill é pública; o SDK que ela aciona não é. `agenteye-evaluator` é publicado apenas como um artefato de release privado, e diferente do `agenteye`, o nome está **sem dono no PyPI público** — então um simples `pip install agenteye-evaluator` poderia puxar o pacote de um desconhecido para o serviço que lê suas transcrições de produção. Isso é um problema de cadeia de suprimentos, não um erro de digitação. -A habilidade sabe disso e percorre uma escada de instalação em vez disso, parando no primeiro degrau que se aplica: o código-fonte do monorepo se você estiver dentro do repositório AgentEye, caso contrário o wheel de release privado do GitHub Releases (requer acesso), e se nenhum estiver acessível ela **para e diz para você perguntar ao seu contato na Failproof AI pelo wheel** em vez de improvisar. +A skill sabe disso e percorre uma escada de instalação, parando no primeiro degrau que se aplica: o código-fonte do monorepo se você estiver dentro do repositório AgentEye, caso contrário o wheel de release privado do GitHub Releases (requer acesso), e se nenhum dos dois estiver acessível ela **para e te diz para pedir o wheel ao seu contato do Failproof AI** em vez de improvisar. -Portanto, se seu agente propõe um simples `pip install agenteye-evaluator` do PyPI público, isso é o sinal de que a habilidade nunca foi carregada. Pare aí e verifique se ela está instalada. +Portanto, se seu agente propõe um `pip install agenteye-evaluator` direto do PyPI público, isso é sinal de que a skill nunca foi carregada. Pare ali e verifique se ela está instalada. --- -## O que você pode pedir a ela +## O que você pode pedir -Uma rodada completa começa com uma solicitação vaga e termina com um design aprovado, não com código: +Uma rodada real começa com um pedido vago e termina com um design aprovado, não com código: ```text -você ▸ Quero avaliações para nosso bot de suporte. Acho que às vezes ele falha. +você ▸ Quero evals para nosso bot de suporte. Acho que ele às vezes erra. -agente▸ Antes de escrever qualquer coisa: descreva uma execução que correu bem, - e uma que correu mal. +agente▸ Antes de escrever qualquer coisa: descreva uma execução que correu + bem, e uma que correu mal. -você ▸ Boa: ele responde pela documentação. Ruim: ele inventa coisas, +você ▸ Bem: ele responde com base na documentação. Mal: ele inventa coisas, ou desiste e diz "entre em contato com o suporte". agente▸ Executando: agenteye --json sessions --status error --since 7d - Lendo 5 sessões, incluindo duas que você consideraria ruins. + Lendo 5 sessões, incluindo duas que você chamaria de ruins. - Suas palavras dizem factualidade e desvio. As transcrições - concordam com desvio (2 de 5 terminam com encaminhamento ao suporte, - e está claro em model_response.content), mas factualidade - precisa de uma resposta de referência que seus eventos não carregam. + Suas palavras dizem factualidade e esquiva. As transcrições + concordam com esquiva (2 de 5 terminam com transferência para + suporte, e está claro em model_response.content), mas factualidade + precisa de um ground truth que seus eventos não contêm. Então eu pontuaria três coisas: - deflection regras, barato, separa suas duas execuções - - tool_efficiency regras, captura o loop de retentativa em run-004 - - groundedness juiz LLM: cada afirmação está nos documentos recuperados? + - tool_efficiency regras, detecta o loop de retry na run-004 + - groundedness juiz LLM: cada afirmação está nos docs recuperados? - "factuality" precisaria de resposta de referência que não temos; groundedness - é o mais próximo que suas transcrições podem realmente suportar. + "factuality" precisaria de ground truth que não temos; groundedness + é o mais próximo que suas transcrições conseguem suportar de fato. OK com esses três nomes? Renomear depois divide o histórico. você ▸ sim -agente▸ Nenhum avaliador neste repositório. Devo criar um aqui, ou você - tem um em outro lugar? +agente▸ Nenhum avaliador neste repositório. Devo criar a estrutura aqui, ou + você tem um em outro lugar? ``` -A partir daí ele escreve primeiro as dimensões baseadas em regras (gratuitas, instantâneas, determinísticas), testa-as contra uma sessão real capturada, incluindo as vazias e as nunca concluídas que travam avaliadores ingênuos, e só recorre a um juiz LLM na dimensão subjetiva. Ele conhece os [limites do dispatcher](/pt-br/agenteye/evaluation-suite#configuring-the-server) — um timeout de requisição de 30s e 8 chamadas concorrentes em todo o deployment — portanto, se o juiz não couber de forma confiável, ele vai assíncrono com `JobPending` em vez de deixar seu juiz ser cancelado e repetido cinco vezes ao custo de cinco vezes mais. +A partir daí, ele escreve primeiro as dimensões baseadas em regras (gratuitas, instantâneas, determinísticas), testa-as contra uma sessão real capturada — incluindo as vazias e as que nunca terminaram, que travam avaliadores ingênuos — e só recorre a um juiz LLM para a dimensão subjetiva. Ele conhece os [limites do dispatcher](/pt-br/agenteye/evaluation-suite#configuring-the-server) — um timeout de requisição de 30s e 8 chamadas concorrentes em todo o deployment — então se o juiz não couber de forma confiável, ele vai assíncrono com `JobPending` em vez de deixar seu juiz ser cancelado e reexecutado cinco vezes com cinco vezes o custo. -Depois implanta, configura as duas variáveis de ambiente do servidor e confirma com `agenteye --json evals --session-id ` que as pontuações realmente chegaram. As pontuações chegando é a única prova. +Depois ele implanta, define as duas variáveis de ambiente do servidor, e confirma com `agenteye --json evals --session-id ` que as pontuações realmente chegaram. As pontuações chegando é a única prova. --- ## O que observar -- **Nomes de dimensões são quase permanentes.** As chaves de pontuação são strings arbitrárias e a plataforma rastreia tendências de tudo o que você envia, o que significa que nada downstream corrige uma escolha ruim. Renomeie depois e o histórico se divide: sessões antigas mantêm a chave antiga e a tendência se quebra. É por isso que a habilidade obtém aprovação explícita antes de escrever código — leve esse prompt a sério. -- **Fixtures são transcrições reais de produção.** Projetar contra sessões reais significa baixá-las para o disco, e elas podem conter dados de clientes. A habilidade pergunta antes de commitá-las no git; em caso de dúvida, mantenha `fixtures/` fora do repositório e peça a cada desenvolvedor que baixe as suas próprias. -- **O agente escreve e implanta um serviço que lê todas as transcrições.** Ele age como você, limitado pelas permissões do seu login no CLI, mas revise o avaliador como qualquer outro código que toca dados de produção. +- **Nomes de dimensão são quase permanentes.** Chaves de pontuação são strings arbitrárias e a plataforma rastreia tendências de tudo o que você envia, o que significa que nada downstream corrige uma escolha ruim. Renomeie depois e o histórico se divide: sessões antigas mantêm a chave antiga e a tendência se rompe. É por isso que a skill exige aprovação explícita antes de escrever código — leve esse prompt a sério. +- **Fixtures são transcrições reais de produção.** Projetar contra sessões reais significa puxá-las para o disco, e elas podem conter dados de clientes. A skill pergunta antes de fazer commit delas no git; em caso de dúvida, mantenha `fixtures/` fora do repositório e faça com que cada desenvolvedor puxe as suas próprias. +- **O agente escreve e implanta um serviço que lê cada transcrição.** Ele age como você, limitado pelas permissões do seu login na CLI, mas revise o avaliador como qualquer outro código que toca dados de produção. --- ## Próximos passos -- **[Evaluation suite](/pt-br/agenteye/evaluation-suite)**: o contrato HTTP, o SDK e as variáveis de ambiente do servidor que a habilidade configura. -- **[Evaluations](/pt-br/agenteye/evaluations)**: onde as pontuações aparecem assim que chegam. -- **[CLI skill](/pt-br/agenteye/cli-skill)**: a habilidade irmã, para ler resultados em vez de construir o pontuador. -- **[CLI](/pt-br/agenteye/cli)**: a referência de comandos por trás dos dados de sessão com os quais a habilidade projeta. \ No newline at end of file +- **[Suíte de avaliação](/pt-br/agenteye/evaluation-suite)**: o contrato HTTP, o SDK e as variáveis de ambiente do servidor que a skill configura. +- **[Avaliações](/pt-br/agenteye/evaluations)**: onde as pontuações aparecem depois de chegarem. +- **[CLI skill](/pt-br/agenteye/cli-skill)**: a skill irmã, para ler resultados em vez de construir o pontuador. +- **[CLI](/pt-br/agenteye/cli)**: a referência de comandos por trás dos dados de sessão contra os quais a skill projeta. \ No newline at end of file diff --git a/docs/pt-br/agenteye/event-stream.mdx b/docs/pt-br/agenteye/event-stream.mdx index 530a552f..7cd5d17f 100644 --- a/docs/pt-br/agenteye/event-stream.mdx +++ b/docs/pt-br/agenteye/event-stream.mdx @@ -1,50 +1,50 @@ --- -title: "Event Stream" +title: "Stream de Eventos" description: "No momento em que seu agente faz algo, você vê." --- -No momento em que seu agente faz algo, você vê. O Event Stream é o seu pulso em tempo real sobre cada agente em produção: sem espera, sem vasculhar logs, sem precisar adivinhar o que acabou de acontecer. +No momento em que seu agente faz algo, você vê. O Stream de Eventos é o seu pulso em tempo real sobre cada agente em produção: sem esperar, sem vasculhar logs, sem adivinhar o que acabou de acontecer. -![O Event Stream ao vivo: linhas de eventos com código de cores atualizando em tempo real, filtráveis por ambiente, agente, sessão, tipo de evento e texto livre](/agenteye/images/events-stream.png) +![O Stream de Eventos ao vivo: linhas de eventos com código de cores chegando em tempo real, filtráveis por ambiente, agente, sessão, tipo de evento e texto livre](/agenteye/images/events-stream.png) -*Todos os eventos de todos os agentes da sua organização, os mais recentes primeiro, atualizando conforme acontecem.* +*Cada evento de cada agente da sua organização, do mais recente para o mais antigo, atualizando conforme acontece.* ## Seu pulso em tempo real sobre cada agente -Quando um agente inicia uma execução, chama um modelo, dispara uma ferramenta, executa um hook ou encontra um erro, a linha aparece no topo do stream no exato momento em que acontece. Ele acompanha todos os eventos de todos os agentes da sua organização, os mais recentes primeiro, para que você tenha sempre uma visão atual em vez de uma desatualizada. +Quando um agente inicia uma execução, chama um modelo, dispara uma ferramenta, executa um hook ou encontra um erro, a linha aparece no topo do stream no exato momento em que acontece. Ele acompanha cada evento de cada agente da sua organização, do mais recente para o mais antigo, para que você sempre tenha uma visão atual em vez de desatualizada. -Isso significa sem ficar monitorando arquivos de log em algum servidor, sem vasculhar máquinas com grep, sem juntar timestamps manualmente. Você abre uma página e já está observando a produção. +Isso significa que não é preciso acompanhar arquivos de log em algum servidor, não é preciso vasculhar múltiplas máquinas, não é preciso juntar timestamps manualmente. Você abre uma página e já está monitorando a produção. -As linhas têm código de cores por tipo, então você consegue ler o stream de relance em vez de analisar cada linha. De uma olhada, cada linha mostra: +As linhas têm código de cores por tipo, para que você consiga ler o stream de relance em vez de analisar cada linha. De um vistazo, cada linha mostra: -- **Seu tipo**, com código de cores: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, entre outros. -- **Um resumo em uma linha** do que aconteceu, para que raramente seja necessário abrir algo só para entender o geral. -- **Contagens de tokens** para a etapa. -- **Um indicador de preenchimento da janela de contexto** onde aplicável, tornando o crescimento do prompt e uma compactação iminente visíveis antes que se tornem um problema. +- **O tipo**, com código de cores: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` e outros. +- **Um resumo em uma linha** do que aconteceu, para que você raramente precise abrir algo só para entender o essencial. +- **Contagens de tokens** para o passo. +- **Um indicador de preenchimento da janela de contexto** onde aplicável, para que o crescimento do prompt e uma compactação iminente sejam visíveis antes de se tornarem um problema. -Acompanhar ao vivo significa que você identifica um deploy problemático, um loop descontrolado ou uma rajada de erros assim que acontece — não na revisão de logs do dia seguinte. +Monitorar ao vivo significa que você detecta um deploy problemático, um loop descontrolado ou uma rajada de erros conforme acontece — não na revisão de logs do dia seguinte. ## Encontre a execução que importa -Quando algo parece errado, você não quer o fluxo completo de dados. Você quer a única execução que quebrou. O stream filtra rapidamente: por ambiente, por agente, por sessão, por tipo de evento ou por texto livre. +Quando algo parece errado, você não quer o volume total de dados. Você quer a única execução que quebrou. O stream filtra rapidamente: por ambiente, por agente, por sessão, por tipo de evento ou por texto livre. -Filtre por ID de sessão ou ID de agente para acompanhar uma execução do primeiro ao último evento. Filtre por tipo de evento para isolar um único tipo de atividade — por exemplo, todos os `error` da organização em uma única visão. Combine filtros para ir de "tudo, em todo lugar" para "este agente, em prod, com erro" em alguns cliques, e então aja sobre o que encontrar. +Filtre por id de sessão ou id de agente para acompanhar uma execução do primeiro ao último evento. Filtre por tipo de evento para isolar um único tipo de atividade — por exemplo, todos os `error` da organização em uma única visão. Combine filtros para ir de "tudo, em todo lugar" até "este agente, em produção, com erros" em alguns cliques e, em seguida, aja sobre o que encontrar. -A busca por texto livre vai direto a uma mensagem, um nome de ferramenta ou um ID que você já tem em mãos, então um relato de cliente se transforma na execução exata em segundos. +A busca por texto livre vai direto a uma mensagem, nome de ferramenta ou id que você já tem em mãos, transformando um relatório de cliente na execução exata em segundos. ## Onde encontrar -O Event Stream é a página inicial da sua organização. Faça login e é a primeira tela que você vê, em `//`, para que o triagem comece no segundo em que você chega. +O Stream de Eventos é a página inicial da sua organização. Ao fazer login, é a primeira tela em que você chega, em `//`, para que a triagem comece no segundo em que você chega. -Por baixo, seus agentes emitem eventos pelo SDK, o coletor os envia ao seu servidor de Observabilidade Failproof AI, e o stream os acompanha conforme chegam na infraestrutura que você controla. Quando quiser a visão consolidada em vez do rastro bruto, os eventos de cada execução se recolhem em uma única linha em Sessions, a um clique de distância. +Por trás disso, seus agentes emitem eventos pelo SDK, o coletor os envia para o servidor de Observabilidade do Failproof AI, e o stream os acompanha conforme chegam na infraestrutura que você controla. Quando você quiser a visão consolidada em vez do rastro bruto, os eventos de cada execução se colapsam em uma única linha em Sessões, a um clique de distância. -Esta é a fonte primária de verdade sobre a qual todas as outras superfícies de observabilidade se baseiam — então quando um número parece errado em outro lugar, o stream é onde você confirma o que realmente aconteceu. +Esta é a fonte de verdade bruta sobre a qual todas as outras superfícies de observação são construídas; portanto, quando um número parece errado em outro lugar, o stream é onde você confirma o que realmente aconteceu. -## Relacionado +## Relacionados -- [Sessions](/pt-br/agenteye/sessions): os mesmos eventos consolidados em uma linha por execução, com um gráfico de execução no estilo git. -- [Telemetry](/pt-br/agenteye/telemetry): o que seus agentes enviam e como os eventos chegam ao stream. -- [Error tracking](/pt-br/agenteye/error-tracking): uma única superfície de triagem para tudo que deu errado. -- [Alerts](/pt-br/agenteye/alerts): transforme qualquer limite em uma regra de notificação. -- [CLI and agents](/pt-br/agenteye/cli-and-agents): o mesmo rastro ao vivo pelo seu terminal. \ No newline at end of file +- [Sessões](/pt-br/agenteye/sessions): os mesmos eventos agrupados em uma linha por execução, com um gráfico de execução no estilo git. +- [Telemetria](/pt-br/agenteye/telemetry): o que seus agentes enviam e como os eventos chegam ao stream. +- [Rastreamento de erros](/pt-br/agenteye/error-tracking): uma superfície de triagem única para tudo que deu errado. +- [Alertas](/pt-br/agenteye/alerts): transforme qualquer limite em uma regra de notificação. +- [CLI e agentes](/pt-br/agenteye/cli-and-agents): o mesmo rastro ao vivo pelo seu terminal. \ No newline at end of file diff --git a/docs/pt-br/agenteye/hermes-capture.mdx b/docs/pt-br/agenteye/hermes-capture.mdx index 73b07cf6..3d013087 100644 --- a/docs/pt-br/agenteye/hermes-capture.mdx +++ b/docs/pt-br/agenteye/hermes-capture.mdx @@ -5,30 +5,30 @@ description: "Traga as sessões do gateway Hermes da sua equipe — Slack, Teleg O [Hermes](https://hermes-agent.nousresearch.com) responde à sua equipe de onde quer que ela já trabalhe — Slack, Telegram, CLI, execuções agendadas. A captura de sessões do Hermes traz tudo isso para o AgentEye como sessões e eventos comuns, tornando o assistente com o qual sua equipe conversa todos os dias tão observável quanto os agentes que você mesmo escreve. -Um pequeno coletor em segundo plano lê o armazenamento local de sessões do Hermes conforme ele é escrito e envia as sessões para o AgentEye. Funciona da mesma forma que a captura do [Codex](/pt-br/agenteye/codex-capture) e do [OpenClaw](/pt-br/agenteye/openclaw-capture), e um único coletor pode capturar vários ao mesmo tempo. +Um pequeno coletor em segundo plano lê o armazenamento local de sessões do Hermes conforme ele é gravado e envia as sessões para o AgentEye. Funciona da mesma forma que a captura do [Codex](/pt-br/agenteye/codex-capture) e do [OpenClaw](/pt-br/agenteye/openclaw-capture), e um único coletor pode capturar vários ao mesmo tempo. --- ## O que é capturado -Todas as sessões do Hermes na máquina são capturadas, independentemente do canal de origem. Cada uma se torna uma [sessão](/pt-br/agenteye/sessions) no AgentEye; suas mensagens de usuário e assistente, chamadas de ferramenta e resultados de ferramenta se tornam os [eventos](/pt-br/agenteye/event-stream) correspondentes. +Todas as sessões do Hermes na máquina são capturadas, independentemente do canal de origem. Cada uma se torna uma [sessão](/pt-br/agenteye/sessions) no AgentEye; suas mensagens do usuário e do assistente, chamadas de ferramentas e resultados de ferramentas se tornam os [eventos](/pt-br/agenteye/event-stream) correspondentes. -O canal pelo qual uma sessão foi iniciada — Slack, Telegram, CLI ou uma execução agendada — é registrado na sessão, para que você possa diferenciá-las e filtrar por uma de cada vez. Junto a isso, são registrados o modelo usado na sessão, o chat e a pessoa que a iniciou e, quando uma sessão originou outra, o vínculo com a sessão pai. +O canal pelo qual a sessão foi iniciada — Slack, Telegram, CLI ou uma execução agendada — é registrado na sessão, para que você possa diferenciá-los e filtrar por um de cada vez. Junto com isso, são registrados o modelo em que a sessão foi executada, o chat e a pessoa que a iniciou e, quando uma sessão gerou outra, o link de volta para a sessão pai. -As sessões aparecem assim que o Hermes as inicia, mesmo que nada tenha sido dito ainda, e a resposta de um turno e suas chamadas de ferramenta são mantidas na ordem em que realmente ocorreram. Quando uma sessão termina, você também obtém o motivo do encerramento, o custo e a quantidade de tokens utilizados. +As sessões aparecem assim que o Hermes as inicia, independentemente de algo ter sido dito ou não, e a resposta de um turno e suas chamadas de ferramentas permanecem na ordem em que realmente aconteceram. Quando uma sessão termina, você também obtém o motivo do encerramento, o custo e a quantidade de tokens utilizados. --- ## Como ativar -A captura fica desativada até você habilitá-la. Instale o coletor com uma chave de API que tenha a permissão `events:add` (consulte [Chaves de API](/pt-br/agenteye/api-keys)) e ative a captura do Hermes: +A captura fica desativada até que você a habilite. Instale o coletor com uma chave de API que tenha a permissão `events:add` (consulte [Chaves de API](/pt-br/agenteye/api-keys)) e ative a captura do Hermes: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -Isso instala o coletor, o registra como um serviço em segundo plano e inicia a captura. Confirme que está em execução: +Isso instala o coletor, registra-o como um serviço em segundo plano e inicia a captura. Confirme que está em execução: ```bash agenteye-collector health @@ -36,18 +36,18 @@ agenteye-collector health Capturando mais de um agente na mesma máquina? Adicione a flag de cada um ao mesmo comando — por exemplo, `--hermes-enabled --codex-enabled`. -Na primeira execução, suas sessões existentes do Hermes são preenchidas retroativamente uma vez, e a nova atividade passa a ser transmitida em segundos. Os dados do próprio Hermes são apenas lidos — nunca modificados ou excluídos — e cada mensagem é enviada uma única vez, mesmo após reinicializações. +Na primeira execução, suas sessões existentes do Hermes são preenchidas retroativamente uma vez, e a nova atividade passa a ser transmitida em segundos. Os dados do próprio Hermes são apenas lidos — nunca modificados ou excluídos — e cada mensagem é enviada uma única vez, mesmo entre reinicializações. -O `health` também informa se tudo que o coletor capturou realmente chegou ao AgentEye. Se um lote não puder ser entregue, ele é mantido e reenviado em vez de descartado, e a verificação reporta estado não saudável enquanto houver itens pendentes — portanto, "saudável" significa que seus dados chegaram, não apenas que o processo está ativo. +O comando `health` também informa se tudo o que o coletor capturou realmente chegou ao AgentEye. Se um lote não puder ser entregue, ele é mantido e reenviado em vez de descartado, e a verificação reporta estado não saudável enquanto houver itens pendentes — portanto, "saudável" significa que seus dados chegaram, não apenas que o processo está ativo. --- ## Onde aparece -As sessões capturadas aparecem em **Sessions**, e seus eventos na stream de **Events**, da mesma forma que qualquer outro agente que você observa — portanto, o [replay de sessão](/pt-br/agenteye/sessions), a [busca](/pt-br/agenteye/queries), as [avaliações](/pt-br/agenteye/evaluations) e os [alertas](/pt-br/agenteye/alerts) funcionam normalmente com elas. Filtre pelo agente Hermes para visualizá-las separadamente. +As sessões capturadas aparecem em **Sessions**, e seus eventos no stream de **Events**, da mesma forma que qualquer outro agente que você observa — portanto, [replay de sessão](/pt-br/agenteye/sessions), [busca](/pt-br/agenteye/queries), [avaliações](/pt-br/agenteye/evaluations) e [alertas](/pt-br/agenteye/alerts) funcionam normalmente nelas. Filtre pelo agente Hermes para visualizá-las separadamente. --- ## Privacidade -As sessões do Hermes contêm a transcrição completa — incluindo saída de comandos, conteúdo de arquivos e tudo que o agente leu ou escreveu — e podem conter segredos. As sessões capturadas são enviadas no estado em que se encontram, portanto, ative a captura somente onde centralizar esse conteúdo no AgentEye for adequado, e forneça ao coletor uma chave com escopo limitado a `events:add`. Consulte [Segurança](/pt-br/agenteye/security) para saber como seus dados são mantidos isolados. \ No newline at end of file +As sessões do Hermes contêm a transcrição completa — incluindo saída de comandos, conteúdo de arquivos e tudo o que o agente leu ou escreveu — e podem conter segredos. As sessões capturadas são enviadas como estão, portanto, ative a captura somente onde for apropriado centralizar esse conteúdo no AgentEye, e forneça ao coletor uma chave com escopo restrito a `events:add`. Consulte [Segurança](/pt-br/agenteye/security) para saber como seus dados são mantidos isolados. \ No newline at end of file diff --git a/docs/pt-br/agenteye/incidents.mdx b/docs/pt-br/agenteye/incidents.mdx index a96d6085..6d8153f9 100644 --- a/docs/pt-br/agenteye/incidents.mdx +++ b/docs/pt-br/agenteye/incidents.mdx @@ -1,26 +1,26 @@ --- title: "Incidentes" -description: "Quando um alerta dispara, todos podem ver que o incidente está aberto, quem é o responsável e o que aconteceu até agora — em uma linha do tempo atribuída." +description: "Quando um alerta dispara, todos podem ver que o incidente está aberto, quem é o responsável e o que aconteceu até agora — em uma única linha do tempo atribuída." --- -Quando um alerta dispara, a primeira pergunta é sempre "quem está cuidando disso?" Os incidentes respondem a essa questão: no momento em que algo ultrapassa um limiar, todos podem ver que o incidente está aberto, quem é o responsável e exatamente o que aconteceu até agora, com um registro limpo e atribuído que pode ser entregue diretamente para uma análise pós-incidente. +Quando um alerta dispara, a primeira pergunta é sempre "quem está cuidando disso?" Os incidentes respondem isso: no momento em que algo é violado, todos podem ver que o incidente está aberto, quem é o responsável e exatamente o que aconteceu até agora, com um registro limpo e atribuído que você pode levar direto para um post-mortem. -![A caixa de entrada de Incidentes: cartões de incidentes vinculados a alertas e abertos manualmente, agrupados por estado, cada um com um badge de severidade e um responsável](/agenteye/images/incidents.png) +![A caixa de entrada de Incidentes: cards de incidentes vinculados a alertas e abertos manualmente, agrupados por estado, cada um com um badge de severidade e um responsável](/agenteye/images/incidents.png) *A caixa de entrada agrupa os incidentes abertos por estado e filtra por severidade e responsável, para que você veja o que precisa de atenção humana agora.* ## Saiba quem está cuidando, de relance -Chega de "alguém está olhando para isso?" em uma thread de chat. Uma violação abre um incidente automaticamente e o coloca em uma caixa de entrada compartilhada, agrupada por estado. Reconheça-o e seu nome estará nele, para que o restante da equipe saiba que está sendo tratado. O reconhecimento é compartilhado: vários operadores podem reconhecer o mesmo incidente e cada um é registrado individualmente, para que uma equipe completa de resposta apareça por nome em vez de se sobrepor. Atribua um único responsável pelo triagem e filtre a caixa de entrada por severidade ou responsável para reduzir ao que é seu. +Chega de "alguém está olhando para isso?" em uma thread de chat. Uma violação abre um incidente automaticamente e o coloca em uma caixa de entrada compartilhada, agrupada por estado. Reconheça-o e seu nome estará nele, para que o restante da equipe saiba que está sendo tratado. O reconhecimento é compartilhado: vários operadores podem reconhecer o mesmo incidente e cada um é registrado individualmente, então uma war room completa aparece com os nomes em vez de se sobreporem. Atribua um único responsável para o triagem e filtre a caixa de entrada por severidade ou responsável para visualizar apenas o que é seu. -## Toda a história, em uma única linha do tempo +## A história completa, em uma única linha do tempo -Quando o incidente termina, você já tem o relatório. Abra qualquer incidente e você terá as evidências da violação, seus responsáveis e assinantes, uma thread de comentários para coordenação no local e uma linha do tempo de atividade somente de acréscimo. +Quando o incidente termina, você já tem o relatório. Abra qualquer incidente e você verá as evidências da violação, seus responsáveis e assinantes, uma thread de comentários para coordenação no lugar e uma linha do tempo de atividades que só permite adição. -![Uma visualização detalhada de incidente: o alerta pai e o resumo da violação, responsáveis e assinantes, uma linha do tempo de atividade atribuída e uma thread de comentários](/agenteye/images/incident-detail.png) -*Tudo o que aconteceu, em ordem, cada linha assinada por quem fez a ação.* +![Uma visão detalhada de incidente: o alerta pai e o resumo da violação, responsáveis e assinantes, uma linha do tempo de atividades atribuída e uma thread de comentários](/agenteye/images/incident-detail.png) +*Tudo o que aconteceu, em ordem, cada linha assinada por quem o fez.* -Cada ação (aberto, reconhecido, resolvido, e assim por diante) é gravada nessa linha do tempo e nunca é editada. Cada entrada é atribuída: ao operador que a executou, por e-mail, ou como **automatizado** para qualquer coisa que o Failproof AI Observability fez por conta própria, como abrir o incidente na violação. Nada é anônimo e nada se perde, então a análise pós-incidente praticamente se escreve sozinha. +Cada ação (aberto, reconhecido, resolvido e assim por diante) é escrita nessa linha do tempo e nunca é editada. Cada entrada é atribuída: ao operador que a realizou, por e-mail, ou a **automated** para qualquer coisa que o Failproof AI Observability fez por conta própria, como abrir o incidente na violação. Nada é anônimo e nada se perde, então o post-mortem praticamente se escreve sozinho. ## Como um incidente evolui @@ -34,17 +34,17 @@ stateDiagram-v2 ``` - **Aberto (firing):** a violação abre o incidente e notifica seus canais uma vez. Violações repetidas são incorporadas ao mesmo incidente e atualizam suas evidências em vez de notificá-lo repetidamente. -- **Reconhecido (acknowledged):** um operador assume o incidente. Ele permanece aberto, e violações posteriores atualizam as evidências silenciosamente. -- **Resolvido (resolved):** um operador encerra o incidente. A resolução automática quando a condição se normaliza está planejada, mas ainda não habilitada — portanto, um incidente permanece aberto até que um humano o resolva, o que mantém todos honestos sobre o que realmente foi resolvido. Um novo incidente pode ser aberto no mesmo alerta posteriormente. +- **Reconhecido (acknowledged):** um operador assume o caso. Ele permanece aberto e violações posteriores atualizam as evidências silenciosamente. +- **Resolvido (resolved):** um operador o encerra. A resolução automática quando a condição é corrigida está planejada, mas ainda não está habilitada — portanto, um incidente permanece aberto até que um humano o resolva, o que mantém todos honestos sobre o que realmente foi corrigido. Um novo incidente pode ser aberto no mesmo alerta posteriormente. -Um alerta mantém no máximo um incidente aberto por vez, portanto uma regra instável não pode te soterrar em duplicatas. Você também pode abrir um incidente manualmente: um independente para algo que nenhum alerta capturou, ou um vinculado a um alerta existente, se você tiver a permissão `incidents:write`. +Um alerta mantém no máximo um incidente aberto por vez, então uma regra instável não pode te enterrar em duplicatas. Você também pode abrir um incidente manualmente: um independente para algo que nenhum alerta capturou, ou um vinculado a um alerta existente, se você tiver `incidents:write`. ## Onde encontrar -Os incidentes estão em `//incidents`. Para visualizar, é necessária a permissão **`incidents:read`**; para abrir um incidente manual, **`incidents:write`**; para reconhecer, atribuir, comentar e resolver, **`incidents:ack`**. Chaves mais antigas que concediam a permissão descontinuada `alerts:ack` continuam funcionando, pois ela é tratada como `incidents:ack`, portanto sua rotação de plantão não precisa ser reemitida. +Os incidentes ficam em `//incidents`. Para visualizar, é necessário **`incidents:read`**; para abrir um incidente manual, **`incidents:write`**; para reconhecer, atribuir, comentar e resolver, **`incidents:ack`**. Chaves mais antigas que concediam o `alerts:ack` descontinuado continuam funcionando, pois é reconhecido como `incidents:ack`, então sua rotação de plantão não precisa ser reemitida. ## Relacionados -- [Alertas](/pt-br/agenteye/alerts): as regras que abrem esses incidentes quando um limiar é ultrapassado. -- [Rastreamento de erros](/pt-br/agenteye/error-tracking): veja todas as falhas em um único lugar e promova uma delas a um alerta. +- [Alertas](/pt-br/agenteye/alerts): as regras que abrem esses incidentes quando um limite é violado. +- [Rastreamento de erros](/pt-br/agenteye/error-tracking): veja todas as falhas em um único lugar e promova uma a um alerta. - [Auditorias](/pt-br/agenteye/audits): o analista agendado que encontra as falhas que nenhuma regra estava monitorando. \ No newline at end of file diff --git a/docs/pt-br/agenteye/observability.mdx b/docs/pt-br/agenteye/observability.mdx index 4db702b2..b094c6ec 100644 --- a/docs/pt-br/agenteye/observability.mdx +++ b/docs/pt-br/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- title: "Observar" -description: "As superfícies de observação são onde você acompanha o que seus agentes estão fazendo agora e analisa qualquer execução individual." +description: "As superfícies de observação são onde você acompanha o que seus agentes estão fazendo agora e detalha qualquer execução individual." --- -As superfícies de observação são onde você acompanha o que seus agentes estão fazendo agora e analisa qualquer execução individual. Tudo aqui é em tempo real, com escopo para sua organização e filtrável por intervalo de datas, ambiente, agente e sessão — para que você passe de "algo parece errado" para a execução exata em segundos. +As superfícies de observação são onde você acompanha o que seus agentes estão fazendo agora e detalha qualquer execução individual. Tudo aqui é em tempo real, com escopo da sua organização, e filtrável por intervalo de datas, ambiente, agente e sessão — assim você vai de "algo parece errado" até a execução exata em segundos. -![O Event Stream ao vivo, com código de cores por tipo e filtrável por ambiente, agente e sessão](/agenteye/images/events-stream.png) +![O Event Stream ao vivo, codificado por cores por tipo e filtrável por ambiente, agente e sessão](/agenteye/images/events-stream.png) Quatro superfícies, cada uma com sua própria página: -- **[Event stream](/pt-br/agenteye/event-stream)**: o rastro ao vivo, passo a passo, de cada execução em todos os agentes, da mais recente para a mais antiga. É a página inicial da sua organização e o primeiro ponto de triagem. -- **[Sessões e grafo de execução](/pt-br/agenteye/sessions)**: esses eventos consolidados em uma linha por execução, além de uma visualização no estilo git de como cada execução se desenrolou. +- **[Stream de eventos](/pt-br/agenteye/event-stream)**: o rastro ao vivo, por etapa, de cada execução em todos os agentes, do mais recente para o mais antigo. A página inicial da sua organização e o primeiro ponto de triagem. +- **[Sessões e grafo de execução](/pt-br/agenteye/sessions)**: esses eventos consolidados em uma linha por execução, mais uma representação visual no estilo git de como cada execução se desenrolou. - **[Métricas de desempenho](/pt-br/agenteye/telemetry)**: mapas de calor de latência e indicadores p50/p95/p99 para seus modelos, ferramentas e hooks, para que um pico na cauda se destaque da mediana. -- **[Rastreamento de erros](/pt-br/agenteye/error-tracking)**: uma única superfície de triagem para tudo que deu errado, a um clique de um alerta disparado até a execução que falhou. +- **[Rastreamento de erros](/pt-br/agenteye/error-tracking)**: uma superfície de triagem para tudo que deu errado, a um clique de um alerta ativo até a execução que falhou. -## Relacionado +## Relacionados -- [Avaliações](/pt-br/agenteye/evaluations): pontue cada execução pela qualidade. +- [Avaliações](/pt-br/agenteye/evaluations): avalie a qualidade de cada execução. - [Alertas](/pt-br/agenteye/alerts): transforme qualquer limite em uma regra de notificação. -- [Auditorias](/pt-br/agenteye/audits): deixe a Observabilidade do Failproof AI encontrar padrões de falha entre sessões para você. -- [CLI e agentes](/pt-br/agenteye/cli-and-agents): a mesma observabilidade a partir do seu terminal. \ No newline at end of file +- [Auditorias](/pt-br/agenteye/audits): deixe o Failproof AI Observability encontrar padrões de falha entre sessões para você. +- [CLI e agentes](/pt-br/agenteye/cli-and-agents): a mesma observabilidade direto do seu terminal. \ No newline at end of file diff --git a/docs/pt-br/agenteye/openclaw-capture.mdx b/docs/pt-br/agenteye/openclaw-capture.mdx index 23649dd5..55fd3270 100644 --- a/docs/pt-br/agenteye/openclaw-capture.mdx +++ b/docs/pt-br/agenteye/openclaw-capture.mdx @@ -1,49 +1,49 @@ --- -title: "Captura de sessão OpenClaw" -description: "Envie as sessões locais OpenClaw da sua equipe para o AgentEye como sessões e eventos comuns — sem alterar a forma como o OpenClaw é executado." +title: "Captura de sessões do OpenClaw" +description: "Monitore as sessões locais do OpenClaw da sua equipe no AgentEye como sessões e eventos comuns — sem nenhuma alteração na forma como o OpenClaw é executado." --- -Se sua equipe utiliza o [OpenClaw](https://docs.openclaw.ai), a captura de sessão OpenClaw traz essas sessões para o AgentEye como sessões e eventos comuns, permitindo que você pesquise, reproduza e avalie-as junto com tudo o mais que você observa. Ela complementa o [Python SDK](/pt-br/agenteye/python-sdk): o SDK instrumenta os agentes que você escreve, enquanto esta captura o trabalho OpenClaw que sua equipe já realiza — sem nenhuma alteração na forma como eles o executam. +Se sua equipe utiliza o [OpenClaw](https://docs.openclaw.ai), a captura de sessões do OpenClaw traz essas sessões para o AgentEye como sessões e eventos comuns, permitindo que você pesquise, reproduza e avalie-as junto com tudo o mais que você observa. Ela complementa o [Python SDK](/pt-br/agenteye/python-sdk): o SDK instrumenta os agentes que você escreve, enquanto esta funcionalidade captura o trabalho do OpenClaw que sua equipe já realiza — sem nenhuma mudança na forma como eles o executam. -Um pequeno coletor em segundo plano lê os transcritos de sessão locais do OpenClaw conforme são gravados e os envia para o AgentEye. Ele funciona da mesma forma que a [captura do Codex](/pt-br/agenteye/codex-capture), e um único coletor pode capturar ambos ao mesmo tempo. +Um pequeno coletor em segundo plano lê as transcrições de sessão locais do OpenClaw conforme são gravadas e as envia ao AgentEye. Ele funciona da mesma forma que a [captura do Codex](/pt-br/agenteye/codex-capture), e um único coletor pode capturar ambos ao mesmo tempo. --- ## O que é capturado -Cada agente configurado na instalação OpenClaw de uma máquina é capturado pelo coletor dessa máquina — não é necessária nenhuma configuração por agente. +Cada agente configurado no OpenClaw de uma máquina é capturado pelo coletor daquela máquina — não há configuração por agente. -Cada sessão OpenClaw se torna uma [sessão](/pt-br/agenteye/sessions) no AgentEye; suas mensagens de usuário e assistente, chamadas de ferramentas e resultados de ferramentas se tornam os [eventos](/pt-br/agenteye/event-stream) correspondentes. +Cada sessão do OpenClaw se torna uma [sessão](/pt-br/agenteye/sessions) no AgentEye; suas mensagens de usuário e assistente, chamadas de ferramentas e resultados de ferramentas se tornam os [eventos](/pt-br/agenteye/event-stream) correspondentes. --- ## Como ativar -A captura fica desativada até que você a habilite. Instale o coletor com uma chave de API que tenha a permissão `events:add` (consulte [Chaves de API](/pt-br/agenteye/api-keys)) e ative a captura OpenClaw: +A captura está desativada até que você a habilite. Instale o coletor com uma chave de API que tenha a permissão `events:add` (consulte [Chaves de API](/pt-br/agenteye/api-keys)) e ative a captura do OpenClaw: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -Isso instala o coletor, registra-o como um serviço em segundo plano e inicia a captura. Confirme que está em execução: +Isso instala o coletor, registra-o como um serviço em segundo plano e inicia a captura. Para confirmar que está em execução: ```bash agenteye-collector health ``` -Capturando mais de um agente na mesma máquina? Adicione a flag de cada um ao mesmo comando — por exemplo, `--openclaw-enabled --codex-enabled`. +Capturando mais de um agente na mesma máquina? Adicione a flag de cada um no mesmo comando — por exemplo, `--openclaw-enabled --codex-enabled`. -Na primeira execução, suas sessões OpenClaw existentes são preenchidas retroativamente uma vez, e as novas atividades passam a ser transmitidas em segundos. Os próprios arquivos do OpenClaw são apenas lidos — nunca modificados, movidos ou excluídos — e cada sessão é enviada exatamente uma vez, mesmo entre reinicializações. +Na primeira execução, suas sessões existentes do OpenClaw são preenchidas retroativamente uma vez, e a nova atividade passa a ser transmitida em segundos. Os arquivos do próprio OpenClaw são apenas lidos — nunca modificados, movidos ou excluídos — e cada sessão é enviada exatamente uma vez, mesmo após reinicializações. --- -## Onde aparecem +## Onde as sessões aparecem -As sessões capturadas aparecem em **Sessões**, e seus eventos no fluxo de **Eventos**, da mesma forma que qualquer outro agente que você observa — portanto, [replay de sessão](/pt-br/agenteye/sessions), [pesquisa](/pt-br/agenteye/queries), [avaliações](/pt-br/agenteye/evaluations) e [alertas](/pt-br/agenteye/alerts) funcionam normalmente nelas. Filtre pelo agente OpenClaw para visualizá-las de forma isolada. +As sessões capturadas aparecem em **Sessões**, e seus eventos no fluxo de **Eventos**, da mesma forma que qualquer outro agente que você observa — portanto, [reprodução de sessão](/pt-br/agenteye/sessions), [pesquisa](/pt-br/agenteye/queries), [avaliações](/pt-br/agenteye/evaluations) e [alertas](/pt-br/agenteye/alerts) funcionam normalmente para elas. Filtre pelo agente OpenClaw para visualizá-las separadamente. --- ## Privacidade -Os transcritos do OpenClaw contêm a sessão completa — incluindo saída de comandos, conteúdo de arquivos e tudo o que o agente leu ou escreveu — e podem conter segredos. As sessões capturadas são enviadas como estão, portanto, ative a captura somente em máquinas e para equipes onde centralizar esse conteúdo no AgentEye seja apropriado, e forneça ao coletor uma chave com escopo restrito a `events:add`. Consulte [Segurança](/pt-br/agenteye/security) para saber como seus dados são mantidos isolados. \ No newline at end of file +As transcrições do OpenClaw contêm a sessão completa — incluindo saída de comandos, conteúdo de arquivos e tudo o que o agente leu ou gravou — e podem conter segredos. As sessões capturadas são enviadas no estado em que se encontram, portanto, habilite a captura apenas em máquinas e para equipes onde centralizar esse conteúdo no AgentEye seja apropriado, e forneça ao coletor uma chave com escopo restrito a `events:add`. Consulte [Segurança](/pt-br/agenteye/security) para entender como seus dados são mantidos isolados. \ No newline at end of file diff --git a/docs/pt-br/agenteye/overview.mdx b/docs/pt-br/agenteye/overview.mdx index c121944c..17947752 100644 --- a/docs/pt-br/agenteye/overview.mdx +++ b/docs/pt-br/agenteye/overview.mdx @@ -1,18 +1,18 @@ --- -title: "Failproof AI: Observe Agentes em Busca de Falhas" -description: "Failproof AI Observability é uma plataforma auto-hospedada para observar, avaliar e aprimorar seus agentes de IA em produção." +title: "Failproof AI: Monitore Agentes em Busca de Falhas" +description: "O Failproof AI Observability é uma plataforma self-hosted para observar, avaliar e melhorar seus agentes de IA em produção." --- -Failproof AI Observability é uma plataforma auto-hospedada para observar, avaliar e aprimorar seus agentes de IA em produção. Ela registra tudo o que seus agentes fazem (cada chamada de ferramenta, requisição ao modelo, hook e erro), pontua a qualidade de cada execução e expõe as falhas que você não sabia que precisava procurar — tudo em um dashboard que roda dentro da sua própria infraestrutura. +O Failproof AI Observability é uma plataforma self-hosted para observar, avaliar e melhorar seus agentes de IA em produção. Ele registra tudo o que seus agentes fazem (cada chamada de ferramenta, requisição ao modelo, hook e erro), pontua a qualidade de cada execução e revela as falhas que você nem sabia que precisava procurar — tudo em um dashboard que você executa dentro da sua própria infraestrutura. -Se você coloca agentes de IA em produção e está cansado de tentar adivinhar por que uma execução deu errado, este é o ponto de partida certo. Aqui você entende o que Failproof AI Observability oferece e como as peças se encaixam, antes mesmo de instalar qualquer coisa. +Se você publica agentes de IA e está cansado de tentar adivinhar por que uma execução deu errado, este é o ponto de partida. Aqui você vai entender o que o Failproof AI Observability oferece e como as peças se encaixam, antes de instalar qualquer coisa. -> **Failproof AI Observability é um produto empresarial da Failproof AI.** Quer ver em ação? Solicite uma demonstração: envie um e-mail para [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +> **O Failproof AI Observability é um produto enterprise da Failproof AI.** Quer ver em ação? Solicite uma demonstração: envie um e-mail para [nikita@befailproof.ai](mailto:nikita@befailproof.ai). -![Uma sessão do Failproof AI Observability representada como um grafo de execução no estilo git ao lado da sua linha do tempo de eventos, com um detalhamento por execução de ferramentas, modelos e hooks na coluna da direita](/agenteye/images/session-detail.png) +![Uma sessão do Failproof AI Observability representada como um grafo de execução no estilo git ao lado de sua linha do tempo de eventos, com um detalhamento por execução de ferramentas, modelos e hooks na coluna da direita](/agenteye/images/session-detail.png) -*Cada execução de agente é representada como um grafo de execução no estilo git (esquerda) ao lado da sua linha do tempo de eventos. Sub-agentes paralelos recebem sua própria faixa; a coluna da direita detalha as ferramentas, modelos, hooks e consumo de tokens da execução.* +*Cada execução do agente é representada como um grafo de execução no estilo git (à esquerda) ao lado de sua linha do tempo de eventos. Sub-agentes paralelos têm sua própria faixa; a coluna da direita detalha as ferramentas, modelos, hooks e consumo de tokens da execução.* --- @@ -24,85 +24,85 @@ Dois vídeos curtos mostram as duas coisas que as equipes buscam primeiro: rastr -*Rastreamento de agentes: acompanhe uma única execução passo a passo, do objetivo às ferramentas até a resposta final.* +*Rastreamento de agente: acompanhe uma única execução passo a passo, do objetivo às ferramentas até a resposta final.*
-*Failproof Audit: deixe o Failproof AI Observability minerar seus logs entre sessões e identificar o que precisa ser corrigido.* +*Failproof Audit: deixe o Failproof AI Observability minerar seus logs entre sessões e indicar o que precisa ser corrigido.* --- ## Por que as equipes usam - **Veja o que seu agente realmente fez.** Cada execução se torna um grafo de execução legível no estilo git: quais ferramentas rodaram em paralelo, quais sub-agentes se ramificaram, onde travou e quanto consumiu. -- **Detecte regressões de qualidade automaticamente.** Conecte um pequeno serviço de pontuação e o Failproof AI Observability pontua cada execução concluída — uma queda na utilidade ou um pico de alucinações aparece por conta própria. -- **Encontre falhas para as quais você não escreveu uma regra.** Auditorias recorrentes mineram seus logs entre sessões em busca de clusters de erros, outliers de latência, pontuações baixas e execuções travadas, entregando descobertas classificadas e fundamentadas em evidências. -- **Seja alertado quando importa.** Regras de threshold disparam sobre taxa de erro, latência, custo ou pontuações de avaliadores e abrem incidentes que você pode reconhecer, atribuir e resolver. -- **Faça perguntas em linguagem natural.** Um assistente de IA integrado ao dashboard responde perguntas como "como está a qualidade em prod esta semana?" sobre seus próprios dados. Qualquer alteração que ele faça requer aprovação. -- **Mantenha seus dados.** Failproof AI Observability é auto-hospedado: eventos, prompts e análises ficam na infraestrutura que você controla. +- **Detecte regressões de qualidade automaticamente.** Conecte um pequeno serviço de pontuação e o Failproof AI Observability avalia cada execução concluída — assim, uma queda na utilidade ou um pico de alucinações aparece por conta própria. +- **Encontre falhas para as quais você não escreveu regras.** Auditorias recorrentes mineram seus logs entre sessões em busca de clusters de erros, outliers de latência, pontuações baixas e execuções travadas — e entregam descobertas ranqueadas e embasadas em evidências. +- **Seja alertado quando importa.** Regras de limiar disparam sobre taxa de erros, latência, custo ou pontuações de avaliadores e abrem incidentes que você pode reconhecer, atribuir e resolver. +- **Faça perguntas em linguagem natural.** Um assistente de IA integrado ao dashboard responde perguntas como "como está evoluindo a qualidade em produção esta semana?" sobre seus próprios dados. Qualquer mudança que ele faça passa por aprovação. +- **Mantenha seus dados.** O Failproof AI Observability é self-hosted: eventos, prompts e análises ficam na infraestrutura que você controla. --- -## O que você recebe +## O que você obtém -Failproof AI Observability é organizado em torno de três ideias (**observe**, **analyze** e **admin**), refletidas na barra lateral esquerda do dashboard. +O Failproof AI Observability é organizado em torno de três ideias (**observar**, **analisar** e **administrar**), refletidas na barra lateral esquerda do dashboard. -**Observe** (a realidade bruta do que aconteceu): +**Observar** (a verdade bruta do que aconteceu): -- **[Event stream](/pt-br/agenteye/event-stream)**: o rastro em tempo real, passo a passo, de cada execução (chamadas de ferramentas, chamadas ao modelo, hooks, erros). -- **[Sessions](/pt-br/agenteye/sessions)**: esses eventos consolidados em uma linha por execução, cada uma pronta para ser pontuada, com um grafo de execução no estilo git. -- **[Performance metrics](/pt-br/agenteye/telemetry)**: mapas de calor de latência por superfície e métricas p50/p95/p99 para modelos, ferramentas e hooks, de modo que um pico na cauda se destaque da mediana. -- **[Error tracking](/pt-br/agenteye/error-tracking)**: uma superfície de triagem unificada para tudo que deu errado, a um clique de um alerta disparado. +- **[Fluxo de eventos](/pt-br/agenteye/event-stream)**: o rastro em tempo real, passo a passo, de cada execução (chamadas de ferramentas, chamadas ao modelo, hooks, erros). +- **[Sessões](/pt-br/agenteye/sessions)**: esses eventos consolidados em uma linha por execução, cada uma pronta para ser pontuada, com um grafo de execução no estilo git. +- **[Métricas de desempenho](/pt-br/agenteye/telemetry)**: mapas de calor de latência por superfície e vitais p50/p95/p99 para modelos, ferramentas e hooks, para que um pico na cauda se destaque da mediana. +- **[Rastreamento de erros](/pt-br/agenteye/error-tracking)**: uma superfície de triagem para tudo que deu errado, a um clique de um alerta ativo. -![A página de observação de Tools: um mapa de calor de latência, uma faixa de percentil e uma barra de distribuição de ferramentas ao longo de 24 intervalos de tempo](/agenteye/images/tools.png) +![A página de observação de Ferramentas: um mapa de calor de latência, uma faixa de percentil e uma barra de distribuição de ferramentas em 24 intervalos de tempo](/agenteye/images/tools.png) -*Cada superfície de observação combina um sparkline e métricas p50/p95/p99 com um mapa de calor de latência e uma faixa de percentil. Mostrado aqui: Tools.* +*Cada superfície de observação combina um sparkline e vitais p50/p95/p99 com um mapa de calor de latência e uma faixa de percentil. Mostrado aqui: Ferramentas.* -**Analyze** (transforme atividade em respostas): +**Analisar** (transforme atividade em respostas): -- **[Queries](/pt-br/agenteye/queries)** e **[dashboards](/pt-br/agenteye/dashboards)**: SQL salvo sobre seus eventos e avaliações, transformado em dashboards compartilhados com escopo de organização. -- **[Evaluations](/pt-br/agenteye/evaluations)**: pontuações de qualidade produzidas pelo seu próprio serviço de avaliação, com raciocínio por pontuação. -- **[Audits](/pt-br/agenteye/audits)**: investigações recorrentes que expõem padrões de falha entre sessões. -- **[Alerts](/pt-br/agenteye/alerts)** e **[incidents](/pt-br/agenteye/incidents)**: regras de threshold que alertam você, mais um fluxo de trabalho de incidentes para triagem. +- **[Consultas](/pt-br/agenteye/queries)** e **[dashboards](/pt-br/agenteye/dashboards)**: SQL salvo sobre seus eventos e avaliações, visualizado em dashboards compartilhados com escopo organizacional. +- **[Avaliações](/pt-br/agenteye/evaluations)**: pontuações de qualidade produzidas pelo seu próprio serviço avaliador, com raciocínio por pontuação. +- **[Auditorias](/pt-br/agenteye/audits)**: investigações recorrentes que revelam padrões de falha entre sessões. +- **[Alertas](/pt-br/agenteye/alerts)** e **[incidentes](/pt-br/agenteye/incidents)**: regras de limiar que notificam você, mais um fluxo de trabalho de incidentes para triá-los. **Interfaces** (acesse seus dados do seu jeito): -- **[CLI](/pt-br/agenteye/cli-and-agents)**: controle todo o seu deployment pelo terminal ou por um script, e deixe um agente de codificação fazer isso por você em linguagem natural. -- **[AI assistant](/pt-br/agenteye/assistant)**: faça perguntas sobre seus agentes em linguagem natural, diretamente no dashboard. -- **REST API**: tudo o que o dashboard e o CLI fazem é respaldado por uma REST API que você pode chamar diretamente com uma [chave de API](/pt-br/agenteye/api-keys) com escopo — ingira eventos, consulte sessões e avaliações, e gerencie dashboards, alertas, auditorias, usuários e chaves, para integrar o Failproof AI Observability às suas próprias ferramentas. +- **[CLI](/pt-br/agenteye/cli-and-agents)**: gerencie todo o seu deployment pelo terminal ou por um script, e deixe um agente de código fazer isso por você em linguagem natural. +- **[Assistente de IA](/pt-br/agenteye/assistant)**: faça perguntas sobre seus agentes em linguagem natural, direto no dashboard. +- **REST API**: tudo que o dashboard e o CLI fazem é respaldado por uma REST API que você pode chamar diretamente com uma [chave de API](/pt-br/agenteye/api-keys) com escopo — ingira eventos, consulte sessões e avaliações, e gerencie dashboards, alertas, auditorias, usuários e chaves, para integrar o Failproof AI Observability às suas próprias ferramentas. -**Admin** (gerencie para sua equipe): +**Administrar** (execute para sua equipe): -- **[API keys](/pt-br/agenteye/api-keys)**: tokens com escopo para o coletor, o dashboard e o assistente. -- **Users**: login sem senha, baseado em e-mail, com lista de permissões. -- **Settings**: configuração por organização, incluindo substituições de janela de contexto do modelo. +- **[Chaves de API](/pt-br/agenteye/api-keys)**: tokens com escopo para o coletor, o dashboard e o assistente. +- **Usuários**: autenticação sem senha, baseada em e-mail, com lista de permissões. +- **Configurações**: configuração por organização, incluindo substituições de janela de contexto do modelo. --- ## Como as peças se encaixam -Os dados fluem em uma única direção, do código do seu agente até o dashboard: seu agente (via SDK Python) emite eventos para o agenteye-collector, que os envia ao servidor, que serve o dashboard. Dois serviços opcionais completam o conjunto — um serviço de pontuação (avaliações) e um serviço de assistente de IA (o chat integrado ao dashboard). +Os dados fluem em uma única direção, do código do seu agente até o dashboard: seu agente (via Python SDK) emite eventos para o agenteye-collector, que os envia ao servidor, que serve o dashboard. Dois serviços opcionais complementam o sistema — um serviço de pontuação (avaliações) e um serviço de assistente de IA (o chat integrado ao dashboard). -- **SDK Python**: você adiciona algumas chamadas `agenteye.event.*` ao seu agente; os eventos são armazenados em buffer localmente. +- **Python SDK**: você adiciona algumas chamadas `agenteye.event.*` ao seu agente; os eventos são armazenados em buffer localmente. - **agenteye-collector**: um daemon leve em cada máquina de agente que agrupa eventos em lotes e os envia ao servidor. -- **Servidor**: ingere seus eventos, mantém o estado operacional nos seus próprios bancos de dados e serve a REST API utilizada pelo dashboard, CLI e suas próprias integrações. +- **Servidor**: ingere seus eventos, mantém o estado operacional nos seus próprios bancos de dados e serve a REST API que o dashboard, o CLI e suas integrações utilizam. - **Dashboard**: onde você explora tudo. - **Serviços opcionais**: um serviço de pontuação (avaliações) e um serviço de assistente de IA (o chat integrado ao dashboard). -Para o vocabulário usado ao longo da documentação (*event, session, evaluation, audit, finding, incident*), consulte [Concepts](/pt-br/agenteye/concepts). +Para o vocabulário utilizado em toda a documentação (*event, session, evaluation, audit, finding, incident*), consulte [Conceitos](/pt-br/agenteye/concepts). --- ## Obtendo o Failproof AI Observability -Failproof AI Observability é um produto empresarial da Failproof AI e funciona em conjunto com o Failproof AI Enforcement — o produto de políticas e guardrails — sob a marca Failproof AI. Ele roda inteiramente no seu próprio ambiente. Se você ainda não tem acesso aos pacotes, solicite uma demonstração e entraremos em contato: envie um e-mail para [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +O Failproof AI Observability é um produto enterprise da Failproof AI e funciona em conjunto com o Failproof AI Enforcement — o produto de políticas e guardrails — sob a marca Failproof AI. Ele roda inteiramente no seu próprio ambiente. Se você ainda não tem acesso aos pacotes, solicite uma demonstração e vamos te configurar: envie um e-mail para [nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- ## Próximos passos -- [Concepts](/pt-br/agenteye/concepts): o vocabulário do Failproof AI Observability em um único lugar. -- [Observability](/pt-br/agenteye/observability): acompanhe o que seus agentes fazem, execução por execução. -- [Security](/pt-br/agenteye/security): como o Failproof AI Observability mantém seus dados isolados e sob seu controle. \ No newline at end of file +- [Conceitos](/pt-br/agenteye/concepts): o vocabulário do Failproof AI Observability em um só lugar. +- [Observabilidade](/pt-br/agenteye/observability): acompanhe o que seus agentes fazem, execução por execução. +- [Segurança](/pt-br/agenteye/security): como o Failproof AI Observability mantém seus dados isolados e sob seu controle. \ No newline at end of file diff --git a/docs/pt-br/agenteye/python-sdk-skill.mdx b/docs/pt-br/agenteye/python-sdk-skill.mdx index fd5981db..7b9a0b7a 100644 --- a/docs/pt-br/agenteye/python-sdk-skill.mdx +++ b/docs/pt-br/agenteye/python-sdk-skill.mdx @@ -1,37 +1,37 @@ --- -title: "Agent Skill Python SDK de Observabilidade do Failproof AI" -description: "Saia de um agente sem instrumentação para eventos visíveis, com seu agente de código encontrando os pontos de instrumentação, escrevendo-os e provando que funcionaram." +title: "Failproof AI Observability Python SDK Agent Skill" +description: "Passe de um agente sem instrumentação para eventos visíveis, com seu agente de código encontrando os pontos de instrumentação, escrevendo-os e comprovando que funcionaram." --- -Diga ao seu agente de código *"adicione Observabilidade do Failproof AI a este agente"* e deixe-o ler seu loop, identificar onde a instrumentação deve ficar, escrevê-la e verificar os eventos antes de declarar o trabalho concluído. +Diga ao seu agente de código *"adicione o Failproof AI Observability a este agente"* e deixe-o ler o seu loop, identificar onde a instrumentação deve ir, escrevê-la e verificar os eventos antes de considerar o trabalho concluído. -A **skill Python SDK** (`agenteye-python-sdk`) é um *Agent Skill*: uma pasta de instruções que um agente de código como Claude Code ou Codex carrega sob demanda quando uma tarefa corresponde a ela. Ela ensina o agente a usar o [Python SDK](/pt-br/agenteye/python-sdk) — não é uma biblioteca e não muda nada sobre como o SDK funciona. +A **skill Python SDK** (`agenteye-python-sdk`) é um *Agent Skill*: uma pasta de instruções que um agente de código como Claude Code ou Codex carrega sob demanda quando uma tarefa corresponde a ela. Ela ensina o agente a usar o [Python SDK](/pt-br/agenteye/python-sdk) — não é uma biblioteca e não altera nada sobre o funcionamento do SDK. -## Instrumentação é fácil de escrever e fácil de errar silenciosamente +## A instrumentação é fácil de escrever e fácil de errar silenciosamente -O SDK é pequeno: treze métodos de eventos, todos com argumentos nomeados. Um agente de código pode ler a referência do [Python SDK](/pt-br/agenteye/python-sdk) e produzir instrumentação plausível em um minuto. +O SDK é pequeno: treze métodos de evento, todos com argumentos nomeados. Um agente de código consegue ler a referência do [Python SDK](/pt-br/agenteye/python-sdk) e produzir uma instrumentação plausível em minutos. -O problema é que esse SDK não levanta exceções quando você erra, e uma instrumentação incorreta parece exatamente com uma correta — até alguém abrir um dashboard e encontrá-lo vazio. Os erros que custam tempo real são todos silêncios: +O problema é que esse SDK não lança exceções quando algo está errado, e uma instrumentação incorreta parece exatamente igual a uma correta — até alguém abrir o dashboard e encontrá-lo vazio. Os erros que custam tempo real são todos silêncios: | O erro | O que você vê | |---|---| | Sem `agent_start` | Todos os eventos chegam. Zero sessões. | -| Ambiente nunca definido | Tudo funciona, arquivado como `dev`. | -| `outcome="failure"` | A execução aparece como verde — apenas `failed`, `error`, `timeout`, `rejected` contam. | +| Ambiente nunca definido | Tudo funciona, registrado como `dev`. | +| `outcome="failure"` | A execução aparece como verde — só `failed`, `error`, `timeout`, `rejected` contam. | | Nome de campo com erro de digitação | Aceito e armazenado como um novo campo. | -| Eventos emitidos de um thread pool | Descartados silenciosamente. | +| Eventos emitidos de um pool de threads | Descartados silenciosamente. | -Nenhum desses levanta exceções. Nenhum aparece em testes. Cada um está na skill, declarado como um contrato com a verificação que o detecta. +Nenhum desses lança exceção. Nenhum aparece em testes. Cada um está na skill, descrito como um contrato com a verificação que o detecta. ## O que ela faz, em ordem A skill executa os mesmos três passos que um engenheiro cuidadoso seguiria: -1. **Planejar.** Ela lê seu loop de agente e faz as duas perguntas que só você pode responder: o que conta como uma execução (seu `session_id`) e quem são os atores distinguíveis (seu `agent_id`). Ela obtém essas respostas antes de escrever código, porque mudá-las depois divide seu histórico e quebra as tendências. -2. **Escrever.** Ela vincula a identidade uma vez por execução em vez de passá-la por todos os pontos de chamada, e escolhe uma forma segura para concorrência — um detalhe que importa, porque o atalho óbvio silenciosamente mistura duas execuções sobrepostas em uma única sessão. -3. **Verificar.** Ela executa seu agente e lê os arquivos de eventos resultantes, verificando se `agent_start` está presente, se o ambiente está correto e se uma execução produziu uma sessão. +1. **Planejar.** Lê o seu loop de agente e faz as duas perguntas que só você pode responder: o que conta como uma execução (seu `session_id`) e quem são os atores identificáveis (seu `agent_id`). Isso é acordado antes de escrever qualquer código, porque mudá-los depois divide o histórico e quebra as tendências. +2. **Escrever.** Vincula a identidade uma vez por execução em vez de passá-la por cada ponto de chamada, e escolhe uma forma segura para concorrência — um detalhe que importa, porque o atalho óbvio mistura silenciosamente duas execuções sobrepostas em uma única sessão. +3. **Verificar.** Executa o agente e lê os arquivos de eventos resultantes, verificando que `agent_start` está presente, o ambiente está correto e uma execução produziu uma sessão. -Esse terceiro passo é o que as pessoas pulam. O SDK grava eventos em arquivos locais, então uma integração completa pode ser provada em um laptop sem servidor, sem chave de API e sem rede — e é exatamente por isso que a skill insiste em fazê-lo. +Esse terceiro passo é o que as pessoas pulam. O SDK grava eventos em arquivos locais, então uma integração completa pode ser comprovada num laptop sem servidor, sem chave de API e sem rede — e é exatamente por isso que a skill insiste em fazer isso. ## Como ela se relaciona com as outras skills @@ -39,19 +39,19 @@ Três skills, uma divisão clara: | Skill | Use quando | O que ela toca | |---|---|---| -| **Skill Python SDK** (esta página) | Você quer que seu agente *emita* telemetria — "adicionar observabilidade", "por que meu agente não está aparecendo?" | Escreve código no repositório do seu agente. Não lê nada. | -| **[Skill Evaluator](/pt-br/agenteye/evaluator-skill)** | Você quer *pontuar* execuções — "o que devemos medir?" | Escreve código no seu repositório; lê telemetria | -| **[Skill CLI](/pt-br/agenteye/cli-skill)** | Você quer *ler* o que aconteceu, ou operar seu deployment | Usa o CLI como você, incluindo alterações | +| **Python SDK skill** (esta página) | Você quer que seu agente *emita* telemetria — "adicionar observabilidade", "por que meu agente não aparece?" | Escreve código no repositório do seu agente. Não lê nada. | +| **[Evaluator skill](/pt-br/agenteye/evaluator-skill)** | Você quer *pontuar* execuções — "o que devemos medir?" | Escreve código no seu repositório; lê telemetria | +| **[CLI skill](/pt-br/agenteye/cli-skill)** | Você quer *ler* o que aconteceu, ou operar seu deploy | Aciona o CLI como você, incluindo alterações | -Elas se encadeiam nessa ordem: esta skill faz os eventos fluírem, o evaluator os pontua, e o CLI os lê de volta. Não há nada para avaliar e nada para ler até que seu agente emita sessões — então, se você está começando do zero, comece aqui. +Elas se encadeiam nessa ordem: esta skill faz os eventos fluírem, o avaliador os pontua, o CLI os lê de volta. Não há nada para avaliar e nada para ler até que seu agente emita sessões — então, se você está começando do zero, comece aqui. ## Pré-requisitos -1. **Python 3.10+** e a base de código do agente que você deseja instrumentar. -2. **O SDK.** Ele é distribuído aos clientes como um wheel privado, não de um índice público — seu onboarding cobre como obtê-lo e instalá-lo. A skill conhece o caminho de instalação e perguntará a você em vez de adivinhar, caso não consiga encontrá-lo. -3. **Nada mais.** Sem login no dashboard, sem chave de API, sem rede. A skill verifica contra os arquivos de eventos que o SDK grava, portanto pode concluir e provar seu trabalho offline. +1. **Python 3.10+** e o código-base do agente que você quer instrumentar. +2. **O SDK.** Ele é distribuído a clientes como um wheel privado, e não por um índice público — o onboarding cobre como obtê-lo e instalá-lo. A skill conhece o caminho de instalação e perguntará a você em vez de adivinhar caso não o encontre. +3. **Nada mais.** Sem login no dashboard, sem chave de API, sem rede. A skill verifica contra os arquivos de eventos que o SDK grava, então pode concluir e comprovar seu trabalho offline. -## Onde encontrá-la +## Onde obtê-la A skill está na coleção pública [`FailproofAI/skills`](https://github.com/FailproofAI/skills): @@ -59,74 +59,69 @@ A skill está na coleção pública [`FailproofAI/skills`](https://github.com/Fa npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -Adicione `-g` para instalá-la em todos os projetos em vez de apenas no atual, e `--copy` se seu ambiente não suporta symlinks. Para Codex, passe `-a codex`. +Adicione `-g` para instalá-la em todos os projetos em vez de apenas no atual, e `--copy` se o seu ambiente não suportar symlinks. Para Codex, passe `-a codex`. ## Instalando manualmente -Agent Skills são pastas contendo um `SKILL.md` mais referências. Se preferir não usar o instalador: +Agent Skills são pastas contendo um `SKILL.md` e referências. Se você preferir não usar o instalador: -- **Claude Code**: copie a pasta `agenteye-python-sdk/` para `~/.claude/skills/` (todos os projetos) ou `/.claude/skills/` (somente aquele repositório). Claude Code a descobre automaticamente — verifique a lista `/skills`, ou simplesmente pergunte algo que corresponda a ela. +- **Claude Code**: copie a pasta `agenteye-python-sdk/` para `~/.claude/skills/` (todos os projetos) ou `/.claude/skills/` (apenas aquele repositório). Claude Code a descobre automaticamente — verifique na lista `/skills`, ou simplesmente peça algo que corresponda a ela. - **Codex**: o Codex lê o mesmo `SKILL.md`. O arquivo `agents/openai.yaml` incluído define `allow_implicit_invocation: true`, então ela é selecionada automaticamente quando uma tarefa corresponde; caso contrário, invoque-a como `$agenteye-python-sdk`. -Execute seu agente **no repositório que contém o código que você deseja instrumentar** — a skill lê seu loop de agente antes de propor qualquer coisa. +Execute seu agente **no repositório que contém o código que você quer instrumentar** — a skill lê o loop do seu agente antes de propor qualquer coisa. -## Como uma sessão se parece +## Como uma sessão parece ```text -você ▸ Adicione Observabilidade do Failproof AI a este agente. +you ▸ Add Failproof AI Observability to this agent. -agente▸ Li seu loop — um dispatcher de ferramentas em tools.py, um - wrapper do Anthropic em llm.py. Duas perguntas antes de - escrever qualquer coisa. +agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic + wrapper in llm.py. Two questions before I write anything. - O que conta como uma execução? Você lida com requisições - concorrentemente, então eu usaria o id de requisição que você - já tem em ctx.request_id — assim uma sessão aqui e uma - requisição nos seus logs são a mesma string. + What counts as one run? You handle requests concurrently, so I'd + use the request id you already have in ctx.request_id — then a + session here and a request in your logs are the same string. - E quem são os atores? Vejo um caminho de planejador e um - caminho de pesquisador. Rotulo-os separadamente, ou é um único - agente para você? + And who are the actors? I see a planner path and a researcher + path. Label them separately, or is that one agent to you? -você ▸ O id de requisição está certo. São um único agente, chame de - "assistant". +you ▸ Request id is right. They're one agent, call it "assistant". -agente▸ Pronto. Envolvi o dispatcher e o cliente LLM; agent_start e - agent_end delimitam handle_request, incluindo o caminho de erro. - Usei um context-local para identidade — seu dispatcher executa - ferramentas em um thread pool, e a abordagem mais simples teria - misturado execuções concorrentes em uma única sessão sem - reclamar. +agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and + agent_end bracket handle_request, including the error path. Used + a context-local for identity — your dispatcher runs tools in a + thread pool, and the simpler approach would have mixed concurrent + runs into one session without complaining. - Verificado contra uma execução real: 11 eventos em 4 arquivos — + Verified against a real run: 11 events across 4 files — agent_start, model_request/response, tool_use/tool_result x3, - agent_end (outcome=success). environment=production, uma sessão - por requisição, durações pareadas. + agent_end (outcome=success). environment=production, one session + per request, durations paired. - Uma coisa que eu NÃO fiz: seu worker pool em batch.py submete - diretamente ao executor, então eventos de lá seriam descartados. - Quer que eu corrija esses também? + One thing I did NOT do: your worker pool in batch.py submits + straight to the executor, so events from there would be dropped. + Want me to fix those too? ``` -O padrão a observar: ele leu o código antes de propor, fez apenas as perguntas que só você pode responder, reutilizou um id que você já tinha, escolheu a forma segura para concorrência *porque* viu um thread pool, e **verificou lendo os eventos reais** em vez de declarar sucesso — e então sinalizou o único lugar que sabia que falharia silenciosamente. +O padrão a observar: ela leu o código antes de propor, fez apenas as perguntas que só você pode responder, reutilizou um id que você já tinha, escolheu a forma segura para concorrência *porque* viu um pool de threads, e **verificou lendo os eventos reais** em vez de declarar sucesso — e então sinalizou o único lugar que ela sabia que falharia silenciosamente. -## O que você pode pedir +## O que você pode pedir a ela -- *"Por que meu agente não está aparecendo no dashboard?"* → percorre a escada: os eventos estão sendo gravados, `agent_start` está lá, o ambiente está correto, o collector está lendo o mesmo lugar. -- *"Tudo está chegando como dev."* → o ambiente nunca foi definido, ou foi redefinido por uma chamada posterior. -- *"Adicione rastreamento de tokens."* → encontra seu wrapper LLM e registra modelo, motivo de parada e uso. -- *"Instrumente os sub-agentes também."* → uma sessão, rótulos de agentes distintos, aninhados sob seu pai. -- *"Escreva testes para a instrumentação."* → aponta o SDK para um diretório temporário e faz asserções sobre os eventos que ele gravou. +- *"Por que meu agente não está aparecendo no dashboard?"* → percorre a escada: os eventos estão sendo gravados, `agent_start` está presente, o ambiente está correto, o coletor está lendo o mesmo local. +- *"Tudo está chegando em dev."* → o ambiente nunca foi definido, ou foi redefinido por uma chamada posterior. +- *"Adicionar rastreamento de tokens."* → encontra seu wrapper de LLM e registra modelo, motivo de parada e uso. +- *"Instrumentar os sub-agentes também."* → uma sessão, rótulos de agentes distintos, aninhados sob o pai. +- *"Escrever testes para a instrumentação."* → aponta o SDK para um diretório temporário e faz asserções sobre os eventos gravados. ## O que observar -**Deixe-o verificar.** O passo que torna esta skill útil é o último — executar seu agente e ler os eventos de volta. Um agente que escreve instrumentação e para fez a metade fácil, e a metade que falha silenciosamente é a outra. +**Deixe-a verificar.** O passo que torna esta skill valiosa é o último — executar o agente e ler os eventos de volta. Um agente que escreve a instrumentação e para fez a metade fácil, e a metade que falha silenciosamente é a outra. -**Concorde com os nomes antes do código.** `session_id` e `agent_id` são os eixos pelos quais toda superfície agrupa. Renomeá-los depois divide o histórico: execuções antigas mantêm os rótulos antigos e suas tendências se quebram. A skill vai perguntar; a resposta vale um minuto de reflexão. +**Acorde os nomes antes do código.** `session_id` e `agent_id` são os eixos pelos quais toda superfície agrupa os dados. Renomeá-los depois divide o histórico: execuções antigas mantêm os rótulos antigos e suas tendências quebram. A skill vai perguntar; a resposta vale um momento de reflexão. -**Se seu agente propuser instalar o SDK de um índice público, a skill não carregou.** O SDK é distribuído de forma privada. Essa proposta é um sinal confiável de que seu agente de código está adivinhando em vez de seguir a skill — pare-o ali e verifique se a skill está instalada. +**Se o seu agente propuser instalar o SDK de um índice público, a skill não foi carregada.** O SDK é distribuído de forma privada. Essa proposta é um sinal claro de que seu agente de código está chutando em vez de seguir a skill — interrompa ali e verifique se a skill está instalada. -Além disso, seu raio de ação é pequeno: ela escreve código no seu diretório de trabalho e arquivos de eventos onde você mandar. Não lê nada do seu deployment e não muda nada nele. +Fora isso, seu raio de ação é pequeno: ele escreve código no seu diretório de trabalho e arquivos de eventos onde você indicar. Não lê nada do seu deploy e não altera nada nele. ## Próximos passos diff --git a/docs/pt-br/agenteye/python-sdk.mdx b/docs/pt-br/agenteye/python-sdk.mdx index 76bb31cf..2c0da4a7 100644 --- a/docs/pt-br/agenteye/python-sdk.mdx +++ b/docs/pt-br/agenteye/python-sdk.mdx @@ -4,11 +4,11 @@ description: "Veja exatamente o que seus agentes de IA fizeram em produção: ca --- -Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição ao modelo, hook e intervenção humana. O SDK Python de Observabilidade do Failproof AI registra esse rastro de dentro do seu código de agente para que você possa depurar, auditar e avaliar o que aconteceu. Use-o sempre que quiser que a Observabilidade do Failproof AI monitore seus agentes. +Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição ao modelo, hook e intervenção humana. O SDK Python de Observabilidade do Failproof AI registra esse rastro diretamente no código do seu agente para que você possa depurar, auditar e avaliar o que aconteceu. Use-o sempre que quiser que a Observabilidade do Failproof AI monitore seus agentes. -Por baixo dos panos, o SDK grava eventos estruturados em arquivos JSONL locais, e o daemon coletor os busca e os envia para a plataforma automaticamente. Você não gerencia esses arquivos diretamente. +Internamente, o SDK grava eventos estruturados em arquivos JSONL locais, e o daemon coletor os captura e os envia automaticamente para a plataforma. Você não precisa gerenciar esses arquivos. -> **Dica:** Novo na Observabilidade do Failproof AI? Esta página é a referência completa de eventos do SDK. +> **Dica:** Está começando com a Observabilidade do Failproof AI? Esta página é a referência completa de eventos do SDK.
@@ -18,7 +18,7 @@ Por baixo dos panos, o SDK grava eventos estruturados em arquivos JSONL locais, ## Instalação -O SDK é distribuído aos clientes como um wheel privado, e não a partir de um índice público de pacotes. O processo de onboarding cobre como obtê-lo, instalá-lo e fixar sua versão — fale com seu contato na Failproof AI se precisar de acesso. +O SDK é distribuído aos clientes como um wheel privado, e não por meio de um índice público de pacotes. O processo de onboarding cobre como obtê-lo, instalá-lo e fixá-lo — fale com seu contato no Failproof AI se precisar de acesso. Após a instalação, confirme que está disponível: @@ -26,7 +26,7 @@ Após a instalação, confirme que está disponível: python -c "import agenteye; print(agenteye.__version__)" ``` -Prefere deixar um agente de código fazer toda a integração? A [Python SDK Agent Skill](/pt-br/agenteye/python-sdk-skill) conhece o caminho de instalação, planeja os pontos de instrumentação, os implementa e verifica se os eventos chegam corretamente. +Prefere deixar um agente de codificação fazer toda a integração? O [Python SDK Agent Skill](/pt-br/agenteye/python-sdk-skill) conhece o caminho de instalação, planeja os pontos de instrumentação, os implementa e verifica se os eventos chegam corretamente. --- @@ -60,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Instrumentando uma chamada real -Na prática, você envolve o código do seu agente existente. Envolva uma chamada ao modelo com `model_request` antes e `model_response` depois, para que os dois eventos abranjam a requisição real e a Observabilidade do Failproof AI possa associá-los: +Na prática, você envolve o código existente do seu agente. Envolva uma chamada ao modelo com `model_request` antes e `model_response` depois, de forma que os dois eventos abranjam a requisição real e a Observabilidade do Failproof AI possa correlacioná-los: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Envolva as chamadas de ferramenta da mesma forma com `tool_use` e `tool_result`, reutilizando um mesmo `tool_call_id` no par. +Envolva as chamadas de ferramenta da mesma forma com `tool_use` e `tool_result`, reutilizando o mesmo `tool_call_id` no par. -Veja como esses eventos aparecem no dashboard, com código de cores por tipo e filtráveis por ambiente, agente e sessão: +Veja como esses eventos aparecem no dashboard após chegarem, com código de cores por tipo e filtráveis por ambiente, agente e sessão: -![O stream de Eventos ao vivo, com código de cores por tipo de evento e filtrável por ambiente, agente e sessão](/agenteye/images/events-stream.png) +![O stream de eventos ao vivo, com código de cores por tipo de evento e filtráveis por ambiente, agente e sessão](/agenteye/images/events-stream.png) --- @@ -113,18 +113,18 @@ agenteye.configure( ) ``` -Chame uma vez antes de qualquer chamada a `event.*`. Pode ser omitido com segurança; os valores padrão funcionam imediatamente. Todos os argumentos são somente por palavra-chave; passe-os pelo nome conforme mostrado acima. +Chame uma vez antes de qualquer chamada `event.*`. Pode ser omitido com segurança; os valores padrão funcionam sem configuração adicional. Todos os argumentos são keyword-only; passe-os pelo nome como mostrado acima. Quando `base_dir` é `None` (o padrão), o SDK lê `$AGENTEYE_HOME` se estiver definido, -caso contrário, utiliza `~/.agenteye`. Isso corresponde à resolução do próprio coletor, -então uma única variável de ambiente `AGENTEYE_HOME` configura o spool de eventos -compartilhado tanto para o SDK quanto para o coletor. +caso contrário usa `~/.agenteye` como fallback. Isso corresponde à resolução do próprio coletor, +de modo que uma única variável de ambiente `AGENTEYE_HOME` configura o spool de eventos +compartilhado tanto pelo SDK quanto pelo coletor. --- ## Ambiente -Identifique cada evento com um ambiente de implantação (`production`, `staging`, `qa`, `canary`, etc.). Defina uma vez; o SDK o anexa a cada evento automaticamente. +Rotule cada evento com um ambiente de implantação (`production`, `staging`, `qa`, `canary`, etc.). Defina uma vez; o SDK o anexa a cada evento automaticamente. **Opção 1: via `configure()`:** @@ -138,27 +138,27 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**Prioridade:** `configure(environment=...)` prevalece sobre a variável de ambiente. Se nenhum dos dois estiver definido, o padrão é `"dev"`. +**Prioridade:** `configure(environment=...)` tem precedência sobre a variável de ambiente. Se nenhum dos dois estiver definido, o padrão é `"dev"`. O valor do ambiente aparece como um filtro de primeira classe no dashboard e é armazenado no servidor para consultas rápidas. -> **Aviso:** Os valores de ambiente não devem conter uma vírgula `,` literal. Os filtros do dashboard utilizam múltipla seleção separada por vírgula na requisição (`?environment=prod,staging`), então um ambiente chamado `prod,blue` seria dividido em dois valores. Eventos com ambientes contendo vírgulas são rejeitados no momento da ingestão. +> **Aviso:** Os valores de ambiente não devem conter uma vírgula literal `,`. Os filtros do dashboard usam multi-seleção separada por vírgula na URL (`?environment=prod,staging`), portanto um ambiente chamado `prod,blue` seria dividido em dois valores. Eventos com ambientes contendo vírgulas são rejeitados na ingestão. --- ## Dados e privacidade -O SDK registra apenas os campos que você passa explicitamente. Prompts, mensagens, entradas e saídas de ferramentas e conteúdo do modelo são capturados somente porque você os fornece a uma chamada `event.*`. Nada é lido do seu processo ou capturado implicitamente. Qualquer campo que você deixar sem definir é omitido do evento por completo; não é gravado em disco. +O SDK registra apenas os campos que você passa explicitamente. Prompts, mensagens, entradas e saídas de ferramentas e conteúdo do modelo são capturados somente porque você os passa para uma chamada `event.*`. Nada é lido do seu processo ou capturado implicitamente. Qualquer campo que você deixar sem definir é omitido do evento inteiramente; ele não é gravado em disco. -Isso torna a redação uma escolha e responsabilidade sua. Se um prompt ou payload de ferramenta contiver PII ou segredos que você prefere não armazenar, remova ou mascare-os antes de passá-los ao método de evento. +Isso torna a redação sua escolha e sua responsabilidade. Se um prompt ou payload de ferramenta contiver PII ou segredos que você prefere não armazenar, remova ou mascare antes de passá-los para o método de evento. --- ## Referência de Eventos -A maioria dos eventos vem em pares início/fim que compartilham um ID de correlação: `tool_use` e `tool_result` compartilham um `tool_call_id`, `hook_triggered` e `hook_completed` compartilham um `hook_id`, e `human_wait` e `human_input` compartilham um `input_id`. Emita o evento de início, execute o trabalho e, em seguida, emita o evento de fim com o mesmo ID. A Observabilidade do Failproof AI associa o par e calcula o `duration_ms` para você, portanto, você nunca passa `duration_ms` diretamente. +A maioria dos eventos vem em pares início/fim que compartilham um ID de correlação: `tool_use` e `tool_result` compartilham um `tool_call_id`, `hook_triggered` e `hook_completed` compartilham um `hook_id`, e `human_wait` e `human_input` compartilham um `input_id`. Emita o evento de início, execute o trabalho e emita o evento de fim com o mesmo ID. A Observabilidade do Failproof AI correlaciona o par e calcula `duration_ms` automaticamente, então você nunca precisa passar `duration_ms` manualmente. -![O gráfico de execução no estilo git de uma sessão ao lado de sua linha do tempo de eventos, reconstruído a partir dos eventos pareados, com o painel de detalhamento de ferramenta/modelo/hook](/agenteye/images/session-detail.png) +![O grafo de execução no estilo git de uma sessão ao lado de sua linha do tempo de eventos, reconstruído a partir dos eventos pareados, com o painel de detalhamento de ferramenta/modelo/hook](/agenteye/images/session-detail.png) Todos os métodos de evento exigem estes dois campos: @@ -173,7 +173,7 @@ Todos os métodos também aceitam `**kwargs` arbitrários para metadados persona ### `event.agent_start()` -Emitido quando um agente inicia o trabalho. +Emitido quando um agente começa a trabalhar. ```python agenteye.event.agent_start( @@ -188,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Emitido quando um agente conclui o trabalho. +Emitido quando um agente termina o trabalho. ```python agenteye.event.agent_end( @@ -203,7 +203,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Emitido quando um agente invoca uma ferramenta. Emparelhe com `tool_result`; o SDK calcula `duration_ms` automaticamente. +Emitido quando um agente invoca uma ferramenta. Pare com `tool_result`; o SDK calcula `duration_ms` automaticamente. ```python agenteye.event.tool_use( @@ -237,7 +237,7 @@ agenteye.event.tool_result( ### `event.model_request()` -Emitido imediatamente antes de enviar um prompt a um LLM. +Emitido imediatamente antes de enviar um prompt para um LLM. ```python agenteye.event.model_request( @@ -254,7 +254,7 @@ agenteye.event.model_request( ) ``` -As entradas de `messages` aceitam tanto uma string simples `content` quanto `content` no estilo Anthropic com lista de blocos. Parâmetros de amostragem (`temperature`, `max_tokens`, etc.) podem ser passados como kwargs extras. +As entradas de `messages` aceitam tanto uma string simples em `content` quanto `content` no estilo Anthropic com lista de blocos. Parâmetros de amostragem (`temperature`, `max_tokens`, etc.) podem ser passados como kwargs extras. --- @@ -277,13 +277,13 @@ agenteye.event.model_response( ) ``` -`content` aceita tanto uma string simples (provedores genéricos) quanto uma lista de blocos de conteúdo no estilo Anthropic. As chamadas de ferramenta ficam dentro de `content` como blocos `{"type": "tool_use", ...}`, sem campo `tool_calls` separado. +`content` aceita tanto uma string simples (provedores genéricos) quanto uma lista de blocos de conteúdo no estilo Anthropic. Chamadas de ferramenta ficam dentro de `content` como blocos `{"type": "tool_use", ...}`, sem um campo separado `tool_calls`. --- ### `event.hook_triggered()` -Emitido quando um hook é acionado. Emparelhe com `hook_completed`; o SDK calcula `duration_ms` automaticamente. +Emitido quando um hook é acionado. Pare com `hook_completed`; o SDK calcula `duration_ms` automaticamente. ```python agenteye.event.hook_triggered( @@ -300,7 +300,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Emitido quando um hook é concluído. Correlaciona com `hook_triggered` via `hook_id`. +Emitido quando um hook termina. Correlaciona com `hook_triggered` via `hook_id`. ```python agenteye.event.hook_completed( @@ -319,7 +319,7 @@ agenteye.event.hook_completed( ### `event.error()` -Emitido quando ocorre um erro não tratado. +Emitido quando um erro não tratado ocorre. ```python agenteye.event.error( @@ -333,13 +333,13 @@ agenteye.event.error( --- -## Eventos de Humano no Processo +## Eventos de Humano no Ciclo -Os eventos de humano no processo (human-in-the-loop) oferecem visibilidade sobre os momentos em que uma pessoa intervém na execução do agente (aguardando aprovação, fornecendo entrada, pausando ou parando o agente). Eles permitem medir quanto tempo os humanos levam para responder (o SDK calcula `duration_ms` automaticamente nos eventos pareados), auditar quem pausou ou interrompeu um agente, e construir fluxos de trabalho de aprovação e supervisão que aparecem no dashboard. +Os eventos de humano no ciclo (human-in-the-loop) oferecem supervisão dos momentos em que uma pessoa entra na execução do agente (aguardando aprovação, fornecendo entrada, pausando ou interrompendo o agente). Eles permitem medir quanto tempo os humanos levam para responder (o SDK calcula `duration_ms` automaticamente nos eventos pareados), auditar quem pausou ou interrompeu um agente, e construir fluxos de trabalho de aprovação e supervisão que aparecem no dashboard. ### `event.human_wait()` -Emitido quando o agente pausa a execução para aguardar que um humano forneça entrada. Emparelhe com `human_input`; o SDK calcula `duration_ms` automaticamente (quanto tempo o humano levou para responder). +Emitido quando o agente pausa a execução para aguardar que um humano forneça entrada. Pare com `human_input`; o SDK calcula `duration_ms` automaticamente (quanto tempo o humano levou para responder). ```python agenteye.event.human_wait( @@ -354,7 +354,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Emitido quando um humano fornece entrada e o agente retoma a execução. Correlaciona com `human_wait` via `input_id`. O `duration_ms` é calculado automaticamente e não deve ser passado pelo chamador. +Emitido quando um humano fornece entrada e o agente retoma. Correlaciona com `human_wait` via `input_id`. `duration_ms` é calculado automaticamente e não deve ser passado pelo chamador. ```python agenteye.event.human_input( @@ -368,7 +368,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Emitido quando um humano pausa ativamente o agente (por exemplo, via um controle no dashboard). O agente é suspenso, mas não encerrado. +Emitido quando um humano pausa ativamente o agente (por exemplo, via um controle do dashboard). O agente é suspenso, mas não encerrado. ```python agenteye.event.human_pause( @@ -381,7 +381,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -Emitido quando um humano para ativamente o agente no meio da execução. Diferentemente de `human_pause`, o trabalho do agente é encerrado em vez de suspenso. +Emitido quando um humano para ativamente o agente no meio da execução. Diferente de `human_pause`, o trabalho do agente é encerrado em vez de suspenso. ```python agenteye.event.human_interrupt( @@ -410,9 +410,9 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type` e `environment` são reservados e lançam `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passados como campos personalizados. `session_id` e `agent_id` são parâmetros obrigatórios em todos os métodos de evento e não podem ser fornecidos uma segunda vez; o Python lança `TypeError` se você fizer isso. Defina o ambiente com `configure(environment=...)` (ou a variável `AGENTEYE_ENVIRONMENT`). +`timestamp`, `type` e `environment` são reservados e levantam `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passados como campos personalizados. `session_id` e `agent_id` são parâmetros obrigatórios em todo método de evento e não podem ser fornecidos uma segunda vez; o Python levanta `TypeError` se você fizer isso. Defina o ambiente com `configure(environment=...)` (ou a variável `AGENTEYE_ENVIRONMENT`) em vez disso. -Mantenha os payloads como JSON estruturado quando quiser consultar seus campos. Valores que o JSON não suporta nativamente — como datetimes, UUIDs, decimais, conjuntos, bytes ou objetos de modelo — são convertidos para strings para que o registro continue com segurança. +Mantenha os payloads como JSON estruturado quando quiser consultar seus campos. Valores que o JSON não suporta nativamente — como datetimes, UUIDs, decimais, sets, bytes ou objetos de modelo — são convertidos para strings para que a gravação continue com segurança. --- @@ -424,13 +424,13 @@ Os eventos são armazenados em buffer no processo e descarregados em disco a cad ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -O coletor monitora esse diretório e faz upload dos arquivos automaticamente. Você não precisa gerenciar esses arquivos diretamente. +O coletor monitora este diretório e faz o upload dos arquivos automaticamente. Você não precisa gerenciar esses arquivos diretamente. -Cada arquivo é gravado atomicamente: o SDK grava em um arquivo temporário e então o renomeia para o lugar final, de modo que o coletor nunca veja um arquivo gravado pela metade. Uma descarga final também é executada quando seu processo encerra, de forma que eventos armazenados em buffer no último intervalo não sejam perdidos. Se o coletor estiver offline, os eventos simplesmente se acumulam como arquivos em disco e são enviados assim que ele voltar. +Cada arquivo é gravado atomicamente: o SDK escreve em um arquivo temporário e então o renomeia para o destino final, de modo que o coletor nunca vê um arquivo gravado pela metade. Um descarte final também é executado quando o processo encerra, para que os eventos armazenados no último intervalo não sejam perdidos. Se o coletor estiver offline, os eventos simplesmente se acumulam como arquivos em disco e são enviados assim que ele voltar. --- ## Próximos passos - [Stream de eventos](/pt-br/agenteye/event-stream): acompanhe esses eventos chegando ao vivo, com código de cores e filtráveis por ambiente, agente e sessão. -- [Sessões](/pt-br/agenteye/sessions): veja como os eventos pareados reconstroem cada execução de agente como um gráfico de execução e uma linha do tempo. \ No newline at end of file +- [Sessões](/pt-br/agenteye/sessions): veja como os eventos pareados reconstroem cada execução de agente como um grafo de execução e uma linha do tempo. \ No newline at end of file diff --git a/docs/pt-br/agenteye/queries.mdx b/docs/pt-br/agenteye/queries.mdx index e69dbbda..c74961b7 100644 --- a/docs/pt-br/agenteye/queries.mdx +++ b/docs/pt-br/agenteye/queries.mdx @@ -1,56 +1,56 @@ --- -title: "Consultas" +title: "Queries" description: "Faça qualquer pergunta sobre os dados do seu agente e obtenha uma resposta em segundos." --- -Faça qualquer pergunta sobre os dados do seu agente e obtenha uma resposta em segundos. A Observabilidade do Failproof AI oferece uma biblioteca de consultas salvas, prontas para execução, sobre seus eventos e avaliações — assim você começa a partir de um exemplo funcional em vez de um editor SQL em branco. +Faça qualquer pergunta sobre os dados do seu agente e obtenha uma resposta em segundos. O Failproof AI Observability oferece uma biblioteca de queries prontas para execução sobre seus eventos e avaliações, para que você comece a partir de um exemplo funcional em vez de um editor SQL em branco. -![A biblioteca de consultas salvas: uma grade de consultas reutilizáveis, incluindo predefinições integradas e personalizadas](/agenteye/images/queries.png) +![A biblioteca de queries salvas: uma grade de queries reutilizáveis, tanto presets integrados quanto personalizados](/agenteye/images/queries.png) -*Sua biblioteca de consultas salvas em `//queries`: predefinições integradas ao lado das consultas que sua equipe salvou.* +*Sua biblioteca de queries salvas em `//queries`: presets integrados lado a lado com as queries que sua equipe salvou.* -## Comece por uma predefinição, não por uma página em branco +## Comece por um preset, não por uma página em branco -Você não precisa lembrar nomes de tabelas nem escrever SQL do zero. A biblioteca abre com predefinições integradas para as perguntas mais frequentes das equipes, dispostas ao lado das consultas que sua própria equipe salvou e nomeou. Escolha uma que se aproxime do que você precisa e você já estará na maior parte do caminho até a resposta. +Você não precisa lembrar nomes de tabelas nem escrever SQL do zero. A biblioteca abre com presets integrados para as perguntas mais frequentes das equipes, logo ao lado das queries que sua própria equipe salvou e nomeou. Escolha uma próxima do que você precisa e você já estará na maior parte do caminho até a resposta. -Cada consulta salva tem escopo por organização e é compartilhada — então as consultas úteis que seus colegas criam também ficam disponíveis para você. Dê um nome e uma descrição a uma consulta uma única vez, e qualquer pessoa da sua organização poderá encontrá-la, executá-la ou fixar seus resultados em um dashboard posteriormente. +Toda query salva tem escopo de organização e é compartilhada, então as úteis que seus colegas escrevem também ficam disponíveis para você. Nomeie uma query e adicione uma descrição uma única vez, e qualquer pessoa na sua organização poderá encontrá-la, executá-la ou fixar seus resultados em um dashboard posteriormente. Acesse em `//queries`. -## Ajuste e execute no compositor SQL +## Ajuste e execute no composer SQL -Abra qualquer consulta e ela será carregada no compositor SQL, onde você pode ajustá-la e ver a resposta imediatamente: sem exportação, sem idas e vindas, sem esperar por outra pessoa. +Abra qualquer query e ela será carregada no composer SQL, onde você pode ajustá-la e ver a resposta imediatamente: sem exportação, sem idas e vindas, sem esperar por outra pessoa. -![O compositor de consultas SQL executando uma consulta salva, com uma barra lateral de esquema e uma grade de resultados ao vivo](/agenteye/images/query-lab.png) +![O composer de queries SQL executando uma query salva, com uma barra lateral de schema e uma grade de resultados ao vivo](/agenteye/images/query-lab.png) -*O compositor SQL: sua consulta à esquerda, uma barra lateral de esquema para que você nunca precise adivinhar o nome de uma coluna, e uma grade de resultados ao vivo abaixo.* +*O composer SQL: sua query à esquerda, uma barra lateral de schema para que você nunca precise adivinhar o nome de uma coluna, e uma grade de resultados ao vivo abaixo.* -- **Uma barra lateral de esquema** exibe as tabelas analíticas e suas colunas, para que você possa moldar uma consulta sem precisar caçar nomes de campos. -- **Uma grade de resultados ao vivo** retorna as linhas assim que você executa, permitindo que você itere em segundos em vez de ficar tentando adivinhar. -- **Somente leitura por design.** As consultas são executadas contra seu armazenamento de eventos e validadas no servidor: apenas instruções `SELECT` e `WITH` são permitidas, com um tempo limite de execução e um limite de linhas. Uma consulta exploratória nunca pode modificar seus dados, e uma consulta fora de controle é interrompida automaticamente para você. +- **Uma barra lateral de schema** exibe as tabelas de analytics e suas colunas, para que você possa estruturar uma query sem precisar buscar nomes de campos. +- **Uma grade de resultados ao vivo** retorna as linhas no momento em que você executa, para que você itere em segundos em vez de ficar tentando e errando. +- **Somente leitura por design.** As queries são executadas contra seu event store e validadas no servidor: apenas instruções `SELECT` e `WITH` são permitidas, com um timeout de instrução e um limite de linhas. Uma query exploratória nunca pode modificar seus dados, e uma que sair de controle é interrompida automaticamente. -Gostou do resultado? Salve-o de volta na biblioteca para que toda a equipe herde, ou fixe a saída em um dashboard como um tile de linha, barra, área ou pizza. +Satisfeito com o resultado? Salve-o de volta na biblioteca para que toda a equipe herde, ou fixe sua saída em um dashboard como um tile de linha, barra, área ou pizza. -## Execute a partir do terminal ou deixe o assistente escrevê-las +## Execute pelo terminal ou deixe o assistente escrever -As mesmas consultas salvas acompanham você onde quer que trabalhe: +As mesmas queries salvas acompanham você onde quer que trabalhe: -- **Pelo terminal.** O CLI `agenteye` lista, executa e salva as mesmas consultas, para que você possa inserir um resultado em um script, integrá-lo ao CI ou passá-lo para um agente de código. +- **Pelo terminal.** A CLI `agenteye` lista, executa e salva exatamente as mesmas queries, para que você possa inserir um resultado em um script, integrar ao CI ou passar para um agente de codificação. ```bash -agenteye query list # as mesmas consultas salvas, pelo seu terminal -agenteye query run errs --arg prod # execute uma e imprima as linhas (adicione --json para redirecionar) +agenteye query list # as mesmas queries salvas, pelo seu terminal +agenteye query run errs --arg prod # execute uma e imprima as linhas (adicione --json para usar pipe) ``` Consulte [CLI e agentes](/pt-br/agenteye/cli-and-agents) para o conjunto completo de comandos. -- **Pelo assistente de IA.** Não tem certeza de como formular o SQL? Pergunte ao [assistente de IA](/pt-br/agenteye/assistant) no dashboard em linguagem natural e ele rascunhará a consulta e a salvará na sua biblioteca. +- **Pelo assistente de IA.** Não tem certeza de como formular o SQL? Pergunte ao [assistente de IA](/pt-br/agenteye/assistant) no dashboard em linguagem natural e ele rascunhará a query e a salvará na sua biblioteca. -A execução de uma consulta salva é controlada pela permissão `queries:run`, separada das permissões para criar ou excluir consultas — assim você pode conceder acesso de leitura sem permitir que todos reescrevam a biblioteca. +A execução de uma query salva é controlada pela permissão `queries:run`, separada das permissões para criar ou excluir queries, para que você possa conceder acesso de leitura sem permitir que todos reescrevam a biblioteca. ## Relacionados -- [Dashboards](/pt-br/agenteye/dashboards): fixe resultados de consultas em gráficos compartilhados para toda a organização. -- [Assistente de IA](/pt-br/agenteye/assistant): faça perguntas em linguagem natural e obtenha uma consulta como resposta. -- [CLI e agentes](/pt-br/agenteye/cli-and-agents): execute e salve as mesmas consultas pelo seu terminal. \ No newline at end of file +- [Dashboards](/pt-br/agenteye/dashboards): fixe resultados de queries em gráficos compartilhados para toda a organização. +- [Assistente de IA](/pt-br/agenteye/assistant): faça perguntas em linguagem natural e receba uma query de volta. +- [CLI e agentes](/pt-br/agenteye/cli-and-agents): execute e salve as mesmas queries pelo seu terminal. \ No newline at end of file diff --git a/docs/pt-br/agenteye/security.mdx b/docs/pt-br/agenteye/security.mdx index e66cb71c..96a00375 100644 --- a/docs/pt-br/agenteye/security.mdx +++ b/docs/pt-br/agenteye/security.mdx @@ -1,68 +1,67 @@ --- title: "Segurança" -description: "O Failproof AI Observability foi projetado para ficar próximo aos seus agentes em produção, o que significa que ele vê seus prompts, entradas de ferramentas e saídas." +description: "O Failproof AI Observability foi construído para operar próximo aos seus agentes em produção, o que significa que ele tem acesso aos seus prompts, entradas de ferramentas e saídas." --- - -O Failproof AI Observability foi projetado para ficar próximo aos seus agentes em produção, o que significa que ele vê seus prompts, entradas de ferramentas e saídas. Esta página explica como esses dados são mantidos isolados, controlados e nas suas mãos. Se você está avaliando o Failproof AI Observability para uma revisão de segurança, comece por aqui. +O Failproof AI Observability foi construído para operar próximo aos seus agentes em produção, o que significa que ele tem acesso aos seus prompts, entradas de ferramentas e saídas. Esta página explica como ele mantém esses dados isolados, controlados e em suas mãos. Se você está avaliando o Failproof AI Observability para uma revisão de segurança, comece por aqui. --- -## Seus dados ficam no seu ambiente +## Seus dados permanecem no seu ambiente O Failproof AI Observability é auto-hospedado. Eventos, prompts, respostas do modelo e análises são armazenados nos seus próprios bancos de dados, no seu próprio ambiente. Nada é enviado para um SaaS de terceiros para armazenamento, e seus dados permanecem na sua própria conta de nuvem. --- -## Isolamento de tenant +## Isolamento de inquilinos -Uma instância do Failproof AI Observability pode hospedar várias organizações, e cada uma é isolada na camada de armazenamento — aplicado pelo banco de dados, não apenas pela interface: +Uma instância do Failproof AI Observability pode hospedar muitas organizações, e cada uma é isolada na camada de armazenamento — aplicado pelo banco de dados, não apenas pela interface: -- Os dados operacionais de uma organização (usuários, chaves, dashboards, consultas salvas) são restritos àquela org, e leituras entre organizações são bloqueadas pelo próprio banco de dados. -- Todo evento ingerido é marcado com a organização proprietária, de modo que os eventos de uma organização nunca podem ser lidos por outra. +- Os dados operacionais de uma organização (usuários, chaves, dashboards, consultas salvas) são escopados para aquela org, e leituras entre orgs são bloqueadas pelo próprio banco de dados. +- Todo evento ingerido é marcado com a org proprietária, de modo que os eventos de uma organização nunca podem ser lidos por outra. -Cada rota de dashboard é delimitada por um slug de org (`//…`). +Cada rota de dashboard é escopada sob um slug de org (`//…`). --- -## Login +## Autenticação -O Failproof AI Observability utiliza login sem senha, baseado em e-mail. Não há senha para ser furtada ou vazada. Um usuário solicita um código de uso único (ou um magic link de clique único), que é enviado por e-mail e expira rapidamente. O login é controlado por uma **lista de permissões**: somente endereços de e-mail (ou domínios) que você autorizar podem se autenticar. +O Failproof AI Observability utiliza autenticação sem senha, baseada em e-mail. Não há senha para ser roubada ou vazada. O usuário solicita um código de uso único (ou um link mágico de clique único), que é enviado por e-mail e expira rapidamente. O acesso é controlado por uma **lista de permissões**: somente endereços de e-mail (ou domínios) que você autorizar podem se autenticar. -![A tela de login do Failproof AI Observability, que envia um código de uso único para seu e-mail](/agenteye/images/login.png) +![A tela de autenticação do Failproof AI Observability, que envia um código de uso único para o seu e-mail](/agenteye/images/login.png) --- -## Acesso restrito com chaves de API +## Acesso escopado com chaves de API -Cada cliente se autentica com uma chave de API que carrega permissões granulares e de menor privilégio. Um coletor precisa apenas de `events:add`; uma chave de dashboard ou assistente pode ser somente leitura; ações destrutivas (exclusão, regeneração) são concessões separadas que você escolhe incluir. +Cada cliente se autentica com uma chave de API que carrega permissões granulares de menor privilégio. Um coletor precisa apenas de `events:add`; uma chave de dashboard ou assistente pode ser somente leitura; ações destrutivas (excluir, regenerar) são concessões separadas que você escolhe incluir. -![A página de chaves de API: as permissões de cada chave, com código de cores por escopo de leitura, escrita e destrutivo](/agenteye/images/api-keys.png) +![A página de chaves de API: as concessões de permissão de cada chave, com código de cores por escopo de leitura, escrita e destrutivo](/agenteye/images/api-keys.png) -Mantenha a chave de bootstrap de administrador para a configuração inicial e emita chaves restritas para todo o resto. Consulte [Chaves de API](/pt-br/agenteye/api-keys). +Guarde a chave de bootstrap de administrador para configuração e emita chaves restritas para todo o restante. Consulte [Chaves de API](/pt-br/agenteye/api-keys). --- ## Um assistente somente leitura com aprovação obrigatória -O [assistente de IA](/pt-br/agenteye/assistant) integrado ao dashboard responde perguntas sobre seus dados, mas é restrito por design: +O [assistente de IA](/pt-br/agenteye/assistant) integrado ao dashboard responde perguntas sobre seus dados, mas é limitado por design: -- É **somente leitura por padrão**: o SQL que ele executa passa por um guard que permite apenas consultas `SELECT`/`WITH`, instrução única, com limite de linhas. -- Tudo que ele cria (uma consulta salva, um dashboard) **requer aprovação**: você revisa e aprova cada escrita antes que ela aconteça. +- É **somente leitura por padrão**: seu SQL passa por um guardião que permite apenas consultas `SELECT`/`WITH`, com instrução única e um limite de linhas. +- Tudo o que ele cria (uma consulta salva, um dashboard) exige **aprovação**: você revisa e aprova cada escrita antes que ela aconteça. - Ele **nunca pode excluir**. -Assim, um colega de equipe pode perguntar "quais agentes tiveram mais erros esta semana?" e agir com base na resposta, sem que o assistente consiga alterar ou remover seus dados por conta própria. +Assim, um colega pode perguntar "quais agentes apresentaram mais erros esta semana?" e agir com base na resposta, sem que o assistente possa alterar ou remover seus dados por conta própria. --- ## Em trânsito -Todo o tráfego é transmitido via HTTPS. Você encerra o TLS com seus próprios certificados, de modo que o tráfego do coletor para o servidor e do navegador para o servidor é criptografado em trânsito. +Todo o tráfego utiliza HTTPS. Você encerra o TLS com seus próprios certificados, de modo que o tráfego do coletor para o servidor e do navegador para o servidor é criptografado em trânsito. --- ## Próximos passos - [Visão geral](/pt-br/agenteye/overview): como o Failproof AI Observability se encaixa. -- [Chaves de API](/pt-br/agenteye/api-keys): restrinja o acesso para o coletor, dashboard e assistente. +- [Chaves de API](/pt-br/agenteye/api-keys): controle o acesso para o coletor, dashboard e assistente. - [Observabilidade](/pt-br/agenteye/observability): o que o Failproof AI Observability captura dos seus agentes. \ No newline at end of file diff --git a/docs/pt-br/agenteye/sessions.mdx b/docs/pt-br/agenteye/sessions.mdx index 63037c8f..ec4f3446 100644 --- a/docs/pt-br/agenteye/sessions.mdx +++ b/docs/pt-br/agenteye/sessions.mdx @@ -1,56 +1,57 @@ --- title: "Sessões e Grafo de Execução" -description: "Todos os eventos de uma execução consolidados em uma linha legível e exibidos como um grafo de execução no estilo git, que você lê em segundos." +description: "Todos os eventos de uma execução consolidados em uma linha legível e visualizados como um grafo de execução no estilo git, que você consegue interpretar em segundos." --- -Chega de adivinhar por que uma execução falhou. A Observabilidade do Failproof AI consolida todos os eventos de uma execução em uma única linha legível e, em seguida, desenha toda a execução como uma imagem no estilo git que você pode interpretar em segundos — assim você vê exatamente o que seu agente fez, passo a passo. -![A lista de Sessões: uma linha por execução, entre ambientes e agentes, com indicadores de status e emblemas de pontuação de avaliação](/agenteye/images/sessions-list.png) +Pare de tentar adivinhar por que uma execução falhou. O Failproof AI Observability consolida todos os eventos de uma execução em uma linha legível, e depois desenha a execução inteira como um diagrama no estilo git que você consegue interpretar em segundos — assim você vê exatamente o que seu agente fez, passo a passo. -*Uma linha por execução: o indicador de status mostra como a execução terminou de relance, e um emblema de pontuação aparece assim que um avaliador é conectado.* +![A lista de Sessões: uma linha por execução, entre ambientes e agentes, com indicadores de status e badges de pontuação de avaliação](/agenteye/images/sessions-list.png) + +*Uma linha por execução: o indicador de status mostra como a execução terminou de relance, e um badge de pontuação aparece assim que um avaliador é conectado.*
-*Rastreamento de agentes: acompanhe uma única execução passo a passo, do objetivo às ferramentas até a resposta final.* +*Rastreamento de agente: acompanhe uma única execução passo a passo, do objetivo às ferramentas até a resposta final.* --- ## Veja todas as execuções de relance -O rastro bruto de eventos é a fonte da verdade de cada etapa, mas quando você tem milhares de etapas distribuídas em dezenas de execuções, o que você precisa é da execução, não da etapa. A página de Sessões consolida todos os eventos de uma execução em uma única linha, transformando um dia inteiro de atividade em uma lista fácil de percorrer, em vez de um fluxo interminável de dados. +O rastro bruto de eventos é a fonte da verdade para cada etapa, mas quando você tem milhares de etapas espalhadas por dezenas de execuções, você precisa da execução, não da etapa. A página de Sessões consolida todos os eventos de uma execução em uma única linha, transformando um dia inteiro de atividade em uma lista escaneável em vez de um fluxo interminável de dados. -Cada linha carrega um indicador de status, de modo que uma execução com falha se destaca de uma saudável antes mesmo de você clicar em qualquer coisa. Filtre por intervalo de datas, ambiente, agente ou sessão para ir de "tudo" até "a execução que me interessa" em alguns cliques. +Cada linha possui um indicador de status, então uma execução com falha se destaca de uma saudável antes mesmo de você clicar em qualquer coisa. Filtre por intervalo de datas, ambiente, agente ou sessão para ir de "tudo" para "a execução que me interessa" em alguns cliques. -Quando você conectar um avaliador, cada execução concluída recebe uma pontuação automaticamente, e a pontuação mais recente aparece na linha como um emblema. Você pode filtrar por qualquer faixa de pontuação — então "mostre-me todas as execuções de produção com pontuação baixa desta semana" vira um filtro, não uma revisão manual. Enquanto você não configurar um avaliador, as sessões continuam capturando a execução completa; elas simplesmente ainda não exibem uma pontuação. +Assim que você conecta um avaliador, cada execução concluída recebe uma pontuação automaticamente e a pontuação mais recente aparece na linha como um badge. Você pode filtrar por qualquer intervalo de pontuação, então "mostre-me todas as execuções em produção com baixa pontuação desta semana" é um filtro, não uma revisão manual. Até que você configure um avaliador, as sessões ainda capturam a execução completa — só não exibem uma pontuação ainda. --- -## Leia toda a execução como uma imagem +## Leia toda a execução como um diagrama -![O grafo de execução no estilo git de uma sessão ao lado da linha do tempo de eventos, com o painel de detalhamento de ferramentas, modelos e hooks](/agenteye/images/session-detail.png) +![O grafo de execução no estilo git de uma sessão ao lado do seu histórico de eventos, com o painel de detalhamento de ferramentas, modelos e hooks](/agenteye/images/session-detail.png) -*O grafo de execução (à esquerda) fica ao lado da linha do tempo de eventos; o painel direito detalha as ferramentas, modelos, hooks e o consumo de tokens da execução.* +*O grafo de execução (à esquerda) fica ao lado do histórico de eventos; a coluna da direita detalha as ferramentas, modelos, hooks e o consumo de tokens da execução.* -Clique em qualquer sessão para abrir o grafo de execução: uma visualização no estilo git de como agentes, ferramentas, hooks e chamadas de modelo se desenrolaram ao longo do tempo. Sub-agentes paralelos se ramificam em suas próprias trilhas, então você consegue ver quais trabalhos rodaram simultaneamente, qual sub-agente travou e onde a execução saiu dos trilhos — sem precisar remontar a cena mentalmente a partir de um muro de logs. +Clique em qualquer sessão para abrir seu grafo de execução: uma visualização no estilo git de como agentes, ferramentas, hooks e chamadas de modelo se desenrolaram ao longo do tempo. Sub-agentes paralelos se ramificam em suas próprias faixas, para que você possa ver quais tarefas rodaram lado a lado, qual sub-agente travou e onde a execução saiu dos trilhos — sem precisar repassar mentalmente um muro de logs. -O painel direito oferece o detalhamento por execução: quais ferramentas e modelos rodaram, quais hooks foram disparados e quanto a execução consumiu em tokens. É a resposta para "por que essa execução custou tanto?" ou "qual ferramenta está lenta?" — ali mesmo, ao lado do grafo que a gerou. +A coluna da direita oferece o detalhamento por execução: quais ferramentas e modelos foram usados, quais hooks foram disparados e quanto a execução consumiu em tokens. Essa é a resposta para "por que essa execução custou tanto?" ou "qual ferramenta é a mais lenta?" — tudo ali do lado do grafo que originou a situação. -Eventos individuais são endereçáveis, então você pode passar para alguém um link para um momento específico em vez de dizer "a sessão, lá pelo terço final". Copie o link de qualquer evento, ou siga um link de uma descoberta de [auditoria](/pt-br/agenteye/audits) ou de um erro, e a sessão abre com aquele evento selecionado e na posição certa. Isso funciona mesmo em execuções muito longas: a linha do tempo carrega uma janela delimitada para poupar seu navegador, e um link que aponta para além dessa janela ainda encontra o evento em vez de te jogar no início. Se o evento tiver ultrapassado o período de retenção, a página informa isso em vez de silenciosamente não selecionar nada. +Eventos individuais são endereçáveis, então você pode enviar a alguém um link para um momento específico em vez de "a sessão, lá pela metade". Copie o link de qualquer evento, ou siga um a partir de uma descoberta de [auditoria](/pt-br/agenteye/audits) ou de um erro, e a sessão abre com aquele evento selecionado e rolado até ele. Isso vale também para execuções muito longas: o histórico carrega uma janela delimitada para preservar o desempenho do seu navegador, e um link apontando para além dessa janela ainda encontra seu evento em vez de te jogar no início. Se o evento já saiu da sua janela de retenção, a página informa isso explicitamente em vez de simplesmente não selecionar nada. --- ## Onde encontrar -Cada página do dashboard é escopada à sua organização (`//…`). Sessões fica em **Observe** na barra lateral esquerda, ao lado de Eventos, com os filtros de intervalo de datas, ambiente, agente e sessão no topo da lista. Cada linha está a um clique do seu grafo de execução completo. +Cada página do painel está vinculada à sua organização (`//…`). Sessões fica em **Observe** na barra lateral esquerda, ao lado de Eventos, com os filtros de intervalo de datas, ambiente, agente e sessão na parte superior da lista. Cada linha está a um clique do seu grafo de execução completo. -Para ativar os emblemas de pontuação e a filtragem por faixa de pontuação, conecte um avaliador: consulte [Avaliações](/pt-br/agenteye/evaluations). +Para ativar os badges de pontuação e a filtragem por intervalo de pontuação, conecte um avaliador: veja [Avaliações](/pt-br/agenteye/evaluations). --- ## Relacionados -- [Fluxo de eventos](/pt-br/agenteye/event-stream): o rastro bruto por etapa a partir do qual cada sessão é consolidada. -- [Avaliações](/pt-br/agenteye/evaluations): conecte um avaliador para que cada execução receba um emblema de pontuação pelo qual você pode filtrar. +- [Fluxo de eventos](/pt-br/agenteye/event-stream): o rastro bruto, por etapa, do qual cada sessão é consolidada. +- [Avaliações](/pt-br/agenteye/evaluations): conecte um avaliador para que cada execução receba um badge de pontuação pelo qual você pode filtrar. - [Telemetria](/pt-br/agenteye/telemetry): como as execuções chegam do seu agente até essas sessões. \ No newline at end of file diff --git a/docs/pt-br/agenteye/telemetry.mdx b/docs/pt-br/agenteye/telemetry.mdx index 5cdfbf84..149702e0 100644 --- a/docs/pt-br/agenteye/telemetry.mdx +++ b/docs/pt-br/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- title: "Métricas de Performance" -description: "Veja no instante em que seus modelos, ferramentas ou hooks ficam lentos ou aumentam sua fatura, e detecte um pico de latência na cauda antes que seus usuários percebam." +description: "Veja no instante em que seus modelos, ferramentas ou hooks ficam lentos ou geram custos, e identifique um pico de latência de cauda antes que seus usuários o percebam." --- -Veja no instante em que seus modelos, ferramentas ou hooks ficam lentos ou aumentam sua fatura, e detecte um pico de latência na cauda antes que seus usuários percebam. Três páginas dedicadas transformam tempos brutos em p50, p95 e p99 que você lê de relance. +Veja no instante em que seus modelos, ferramentas ou hooks ficam lentos ou geram custos, e identifique um pico de latência de cauda antes que seus usuários o percebam. Três páginas dedicadas transformam tempos brutos em p50, p95 e p99 que você lê de relance. -![A página Models exibindo um mapa de calor de latência, uma faixa de percentis e valores de tokens, custo e janela de contexto por modelo](/agenteye/images/models.png) -*A página Models: um mapa de calor de latência, uma faixa de percentis e, por modelo, tokens, custo estimado e ocupação da janela de contexto.* +![A página de Modelos exibindo um mapa de calor de latência, uma faixa de percentis e valores de tokens, custo e janela de contexto por modelo](/agenteye/images/models.png) +*A página de Modelos: um mapa de calor de latência, uma faixa de percentis e, por modelo, tokens, custo estimado e preenchimento da janela de contexto.* ## Pare de deixar as médias esconderem suas piores execuções -Um número médio de latência é reconfortante e inútil: ele suaviza aquela chamada em cinquenta que trava e aciona seu plantão às 2h da manhã. As páginas Models, Tools e Hooks recusam fazer isso. Cada uma tem o mesmo formato, então você aprende uma vez: +Um número médio de latência é reconfortante e inútil: ele suaviza aquela chamada em cinquenta que trava e aciona seu plantão às 2 da manhã. As páginas de Modelos, Ferramentas e Hooks recusam fazer isso. Cada uma compartilha o mesmo formato, então você aprende uma vez: -- Um **sparkline de 24 bins** para a tendência de relance: isso está piorando? +- Um **sparkline de 24 intervalos** para a tendência de relance: isso está piorando? - Uma **faixa de vitais** com latência p50, p95 e p99, para que a execução típica e a cauda fiquem lado a lado. -- Um **mapa de calor de latência**, com 24 bins de tempo por buckets de latência, que mostra *quando* as chamadas lentas se agruparam. -- Uma **faixa de percentis**: uma linha p50 com faixas sombreadas de p25 a p75 e p10 a p90 e pontos p99, para que a dispersão permaneça visível em vez de ser diluída na média. +- Um **mapa de calor de latência**, com 24 intervalos de tempo por buckets de latência, que mostra *quando* as chamadas lentas se concentraram. +- Uma **faixa de percentis**: uma linha p50 com faixas sombreadas de p25 a p75 e de p10 a p90, além de pontos p99, para que a dispersão permaneça visível em vez de ser ocultada pela média. -Um crosshair de hover compartilhado conecta o mapa de calor e a faixa, então um pico na cauda se alinha no tempo nos dois em vez de se esconder atrás de uma única linha de média. Encontre as três páginas na seção **observe** do seu dashboard, cada uma com escopo para sua organização e filtrável por intervalo de datas, ambiente, agente e sessão. +Um crosshair de hover compartilhado vincula o mapa de calor e a faixa, de modo que um pico de cauda se alinha no tempo em ambos, em vez de se esconder atrás de uma única linha de média. Encontre todas as três páginas na seção **observe** do seu dashboard, cada uma com escopo para sua organização e filtrável por intervalo de datas, ambiente, agente e sessão. -## Models: veja exatamente o que cada modelo custa +## Modelos: veja exatamente o que cada modelo custa para você -A página Models (exibida acima) responde às duas perguntas que uma fatura sempre levanta: qual modelo e quanto. Além da visão de latência compartilhada, ela adiciona **consumo de tokens por modelo**, **custo estimado** e **ocupação da janela de contexto**, para que o crescimento descontrolado de prompts e uma compactação iminente sejam visíveis antes de te surpreenderem. +A página de Modelos (exibida acima) responde às duas perguntas que uma fatura sempre levanta: qual modelo e quanto. Além da visualização de latência compartilhada, ela adiciona **consumo de tokens por modelo**, **custo estimado** e **preenchimento da janela de contexto**, para que o crescimento descontrolado de prompts e uma compactação iminente sejam visíveis antes de te surpreender. -O Failproof AI Observability reconhece IDs de modelos comuns automaticamente. Se uma janela parecer incorreta, ou se você rodar um modelo próprio privado, corrija ou adicione um em **Settings**, em **model context windows**, e as leituras de ocupação se atualizam. +O Failproof AI Observability reconhece IDs de modelos comuns automaticamente. Se uma janela parecer incorreta, ou se você usar um modelo privado próprio, corrija-a ou adicione uma em **Settings**, em **model context windows**, e as leituras de preenchimento serão atualizadas. -## Tools: distinga o lento do quebrado +## Ferramentas: diferencie o lento do quebrado -Uma chamada de ferramenta pode ser lenta ou pode estar falhando silenciosamente, e você quer saber qual é o caso em segundos, não após vasculhar logs. +Uma chamada de ferramenta pode estar lenta ou falhando silenciosamente, e você quer saber qual delas em segundos, não depois de vasculhar logs. -![A página Tools exibindo o mapa de calor de latência e a faixa de percentis compartilhados ao lado de uma divisão de sucesso e falha e uma barra de distribuição de ferramentas](/agenteye/images/tools.png) -*A página Tools: o mesmo mapa de calor e faixa de percentis, mais uma divisão de sucesso e falha e uma barra de distribuição de ferramentas.* +![A página de Ferramentas exibindo o mapa de calor de latência compartilhado e a faixa de percentis ao lado de um detalhamento de sucesso e falha e uma barra de distribuição de ferramentas](/agenteye/images/tools.png) +*A página de Ferramentas: o mesmo mapa de calor e faixa de percentis, mais um detalhamento de sucesso e falha e uma barra de distribuição de ferramentas.* -Junto à visão de latência compartilhada, a página Tools adiciona uma **divisão de sucesso e falha** e uma **barra de distribuição de ferramentas**, para que você veja de relance em quais ferramentas você mais depende e quais estão consumindo seu orçamento de erros. +Junto com a visualização de latência compartilhada, a página de Ferramentas adiciona um **detalhamento de sucesso e falha** e uma **barra de distribuição de ferramentas**, para que você veja de relance em quais ferramentas você mais depende e quais estão consumindo seu orçamento de erros. ## Hooks: identifique o hook e o gatilho exatos -Quando um hook de ciclo de vida atrasa uma execução, "os hooks estão lentos" não é algo sobre o qual você pode agir. A página Hooks leva você até o que importa. +Quando um hook de ciclo de vida atrasa uma execução, "os hooks estão lentos" não é algo que você possa resolver. A página de Hooks leva você diretamente ao que importa. -![A página Hooks exibindo a latência detalhada por nome de hook e evento de gatilho sobre o mapa de calor e a faixa de percentis compartilhados](/agenteye/images/hooks.png) -*A página Hooks: latência detalhada por nome de hook e evento de gatilho.* +![A página de Hooks exibindo a latência detalhada por nome de hook e evento de gatilho sobre o mapa de calor e a faixa de percentis compartilhados](/agenteye/images/hooks.png) +*A página de Hooks: latência detalhada por nome de hook e evento de gatilho.* -Sobre o mesmo mapa de calor de latência e faixa de percentis, a página Hooks detalha a atividade por **nome do hook** e **evento de gatilho**, para que você chegue ao único hook e ao único evento que precisam de atenção. +Sobre o mesmo mapa de calor de latência e faixa de percentis, a página de Hooks detalha a atividade por **nome de hook** e **evento de gatilho**, para que você chegue ao hook único e ao evento único que precisam de atenção. ## Relacionados -- [Event stream](/pt-br/agenteye/event-stream): o rastro em tempo real, com código de cores, de cada evento. -- [Sessions](/pt-br/agenteye/sessions): agrupe eventos em uma linha por execução e abra seu grafo de execução. -- [Error tracking](/pt-br/agenteye/error-tracking): uma superfície de triagem unificada para tudo que o dashboard pinta de vermelho. -- [Dashboards](/pt-br/agenteye/dashboards): visões consolidadas de toda a sua frota. \ No newline at end of file +- [Fluxo de eventos](/pt-br/agenteye/event-stream): o rastro em tempo real, codificado por cores, de cada evento. +- [Sessões](/pt-br/agenteye/sessions): agrupe eventos em uma linha por execução e abra seu grafo de execução. +- [Rastreamento de erros](/pt-br/agenteye/error-tracking): uma superfície de triagem única para tudo que o dashboard pinta de vermelho. +- [Dashboards](/pt-br/agenteye/dashboards): visualizações consolidadas de toda a sua frota. \ No newline at end of file diff --git a/docs/pt-br/architecture.mdx b/docs/pt-br/architecture.mdx index b442d169..26dfebe9 100644 --- a/docs/pt-br/architecture.mdx +++ b/docs/pt-br/architecture.mdx @@ -1,10 +1,10 @@ --- title: Arquitetura -description: "Como o handler de hooks, o carregamento de configurações e a avaliação de políticas funcionam internamente" +description: "Como o handler de hook, o carregamento de configuração e a avaliação de políticas funcionam internamente" icon: sitemap --- -Este documento explica como o failproofai funciona internamente: como o sistema de hooks intercepta chamadas de ferramentas do agente, como as configurações são carregadas e mescladas, como as políticas são avaliadas e como o dashboard monitora a atividade do agente. +Este documento explica como o failproofai funciona internamente: como o sistema de hooks intercepta chamadas de ferramentas do agente, como a configuração é carregada e mesclada, como as políticas são avaliadas e como o dashboard monitora a atividade do agente. --- @@ -12,8 +12,8 @@ Este documento explica como o failproofai funciona internamente: como o sistema O failproofai possui dois subsistemas independentes: -1. **Hook handler** - Um subprocesso CLI rápido que o Claude Code invoca a cada chamada de ferramenta do agente. Avalia políticas e retorna uma decisão. -2. **Agent Monitor (Dashboard)** - Uma aplicação web Next.js para monitorar sessões de agente e gerenciar políticas. +1. **Hook handler** - Um subprocesso de CLI rápido que o Claude Code invoca em cada chamada de ferramenta do agente. Avalia políticas e retorna uma decisão. +2. **Monitor de Agentes (Dashboard)** - Uma aplicação web Next.js para monitorar sessões de agentes e gerenciar políticas. Ambos os subsistemas compartilham arquivos de configuração em `~/.failproofai/` e no diretório `.failproofai/` do projeto, mas são executados como processos separados e se comunicam apenas pelo sistema de arquivos. @@ -23,7 +23,7 @@ Ambos os subsistemas compartilham arquivos de configuração em `~/.failproofai/ ### Integração com o Claude Code -Quando você executa `failproofai policies --install`, ele escreve entradas como esta no `~/.claude/settings.json`: +Ao executar `failproofai policies --install`, entradas como esta são escritas em `~/.claude/settings.json`: ```json { @@ -44,7 +44,7 @@ Quando você executa `failproofai policies --install`, ele escreve entradas como } ``` -O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin. +O Claude Code então invoca `failproofai --hook PreToolUse` como um subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin. ### Formato do payload @@ -62,9 +62,9 @@ O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso ant Para eventos `PostToolUse`, o payload também contém `tool_result` com a saída da ferramenta. -O handler impõe um limite de 1 MB para o stdin. Payloads que excedem esse limite são descartados e todas as políticas implicitamente permitem a operação. +O handler impõe um limite de 1 MB no stdin. Payloads que excedam esse limite são descartados e todas as políticas implicitamente permitem a operação. -### Formato de resposta +### Formato da resposta **Deny (PreToolUse):** ```json @@ -94,9 +94,9 @@ O handler impõe um limite de 1 MB para o stdin. Payloads que excedem esse limit } ``` -**Instruct no evento Stop:** +**Instruct para evento Stop:** - Código de saída: `2` -- Motivo escrito no stderr (não no stdout) +- Motivo escrito em stderr (não em stdout) **Allow:** - Código de saída: `0` @@ -104,7 +104,7 @@ O handler impõe um limite de 1 MB para o stdin. Payloads que excedem esse limit **Allow com mensagem:** -`allow(message)` permite que uma política envie contexto informativo de volta ao Claude mesmo quando a operação é permitida. O hook handler escreve o seguinte JSON no **stdout** (não em um arquivo de configuração — esta é a resposta do handler ao Claude Code, assim como as respostas de deny e instruct acima): +`allow(message)` permite que uma política envie contexto informativo de volta ao Claude mesmo quando a operação é permitida. O hook handler escreve o seguinte JSON em **stdout** (não em um arquivo de configuração — esta é a resposta do handler ao Claude Code, assim como as respostas de deny e instruct acima): ```json // Written to stdout by the hook handler process @@ -115,8 +115,8 @@ O handler impõe um limite de 1 MB para o stdin. Payloads que excedem esse limit } ``` - Código de saída: `0` (a operação é permitida) -- Quando múltiplas políticas retornam `allow` com uma mensagem, suas mensagens são unidas com quebras de linha em uma única string `additionalContext` -- Se nenhuma política fornecer uma mensagem, o stdout fica vazio (como antes) +- Quando múltiplas políticas retornam `allow` com uma mensagem, as mensagens são unidas com quebras de linha em uma única string `additionalContext` +- Se nenhuma política fornecer uma mensagem, o stdout fica vazio (comportamento padrão) ### Pipeline de processamento @@ -139,7 +139,7 @@ stdin JSON → exit ``` -Todo o processo é executado em menos de 100ms para payloads típicos, sem chamadas a LLM. +Todo o processo é executado em menos de 100ms para payloads típicos, sem chamadas a LLMs. --- @@ -156,8 +156,8 @@ Todo o processo é executado em menos de 100ms para payloads típicos, sem chama Lógica de mesclagem: - `enabledPolicies` - união deduplicada entre os três arquivos - `policyParams` - por chave de política, o primeiro arquivo que a define prevalece inteiramente -- `customPoliciesPath` - o primeiro arquivo que a define prevalece -- `llm` - o primeiro arquivo que a define prevalece +- `customPoliciesPath` - o primeiro arquivo que define prevalece +- `llm` - o primeiro arquivo que define prevalece O dashboard web usa `readHooksConfig()` (somente global) para leitura e escrita, pois não é invocado com um cwd de projeto. @@ -169,24 +169,24 @@ O dashboard web usa `readHooksConfig()` (somente global) para leitura e escrita, Para cada política: -1. Busca o schema de `params` da política (se houver). +1. Busca o schema de `params` da política (se existir). 2. Lê `policyParams[policy.name]` da configuração mesclada. 3. Mescla os valores fornecidos pelo usuário sobre os padrões do schema para produzir `ctx.params`. 4. Chama `policy.fn(ctx)` com o contexto resolvido. -5. Se o resultado for `deny`, interrompe imediatamente e retorna essa decisão. +5. Se o resultado for `deny`, para imediatamente e retorna essa decisão. 6. Se o resultado for `instruct`, acumula a mensagem e continua. 7. Se o resultado for `allow`, continua para a próxima política. Após todas as políticas serem executadas: - Se algum `deny` foi retornado, emite a resposta de deny. -- Se algum retorno de `instruct` foi coletado, emite uma única resposta de instruct com todas as mensagens unidas. -- Caso contrário, emite uma resposta de allow (stdout vazio, saída 0). +- Se algum retorno `instruct` foi coletado, emite uma única resposta de instruct com todas as mensagens unidas. +- Caso contrário, emite uma resposta de allow (stdout vazio, exit 0). --- -## Políticas embutidas +## Políticas integradas -`src/hooks/builtin-policies.ts` define todas as 39 políticas embutidas como objetos `BuiltinPolicyDefinition`: +`src/hooks/builtin-policies.ts` define todas as 39 políticas integradas como objetos `BuiltinPolicyDefinition`: ```typescript interface BuiltinPolicyDefinition { @@ -204,13 +204,13 @@ interface BuiltinPolicyDefinition { } ``` -Políticas que aceitam `params` declaram um `PolicyParamsSchema` com tipos e valores padrão para cada parâmetro. O avaliador de políticas injeta os valores resolvidos em `ctx.params` antes de chamar `fn`. As funções de política leem `ctx.params` sem verificações de nulo porque os padrões são sempre aplicados primeiro. +Políticas que aceitam `params` declaram um `PolicyParamsSchema` com tipos e padrões para cada parâmetro. O avaliador de políticas injeta os valores resolvidos em `ctx.params` antes de chamar `fn`. As funções de política leem `ctx.params` sem verificações de nulo, pois os padrões são sempre aplicados primeiro. -A correspondência de padrões dentro das políticas usa tokens de comando analisados (argv), não correspondência de strings brutas. Isso evita contorno via injeção de operadores shell (por exemplo, um padrão para `sudo systemctl status *` não pode ser contornado adicionando `; rm -rf /` ao comando). +A correspondência de padrões dentro das políticas usa tokens de comando interpretados (argv), não correspondência bruta de strings. Isso evita bypass por injeção de operadores shell (por exemplo, um padrão para `sudo systemctl status *` não pode ser contornado adicionando `; rm -rf /` ao comando). --- -## Políticas personalizadas +## Políticas customizadas `src/hooks/custom-hooks-registry.ts` implementa um registro baseado em `globalThis`: @@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` carrega o arquivo de política do usuário: +`src/hooks/custom-hooks-loader.ts` carrega o arquivo de políticas do usuário: 1. Lê `customPoliciesPath` da configuração; ignora se ausente. 2. Resolve para caminho absoluto; verifica se o arquivo existe. -3. Reescreve todas as importações `from "failproofai"` para o caminho real do dist, de modo que `customPolicies` resolva para o mesmo registro `globalThis`. +3. Reescreve todas as importações `from "failproofai"` para o caminho real de dist, de modo que `customPolicies` resolva para o mesmo registro `globalThis`. 4. Reescreve recursivamente importações locais transitivas para garantir compatibilidade com ESM. -5. Escreve arquivos `.mjs` temporários e importa o arquivo de entrada com `import()`. +5. Escreve arquivos `.mjs` temporários e faz `import()` do arquivo de entrada. 6. Chama `getCustomHooks()` para recuperar os hooks registrados. 7. Remove todos os arquivos temporários em um bloco `finally`. -Em caso de erro (arquivo não encontrado, erro de sintaxe, falha de importação), o erro é registrado em `~/.failproofai/hook.log` e o loader retorna um array vazio. As políticas embutidas não são afetadas. +Em caso de qualquer erro (arquivo não encontrado, erro de sintaxe, falha de importação), o erro é registrado em `~/.failproofai/hook.log` e o loader retorna um array vazio. As políticas integradas não são afetadas. -As políticas personalizadas são avaliadas após todas as políticas embutidas. Um `deny` de uma política personalizada ainda interrompe as políticas personalizadas seguintes (mas todos os embutidos já terão sido executados nesse ponto). +As políticas customizadas são avaliadas após todas as políticas integradas. Um `deny` de política customizada ainda encerra o processamento das demais políticas customizadas (mas todas as integradas já terão sido executadas nesse ponto). --- ## Log de atividade -Após cada evento de hook, o handler anexa uma linha JSONL ao `~/.failproofai/hook-activity/current.jsonl`, que é rotacionado para `page--.jsonl` ao atingir o tamanho de uma página: +Após cada evento de hook, o handler anexa uma linha JSONL a `~/.failproofai/hook-activity/current.jsonl`, que rotaciona para `page--.jsonl` ao atingir o tamanho de uma página: ```json { @@ -264,18 +264,18 @@ Uma linha por política que tomou uma decisão diferente de allow. Decisões de ## Arquitetura do dashboard -O dashboard é uma aplicação **Next.js 16** que usa o App Router com React Server Components e Server Actions. +O dashboard é uma aplicação **Next.js 16** que utiliza o App Router com React Server Components e Server Actions. ```text app/ - layout.tsx ← Layout raiz (tema, telemetria, nav) + layout.tsx ← Layout raiz (tema, telemetria, navegação) projects/page.tsx ← Server component: lista todos os projetos Claude - project/[name]/page.tsx ← Server component: lista sessões em um projeto + project/[name]/page.tsx ← Server component: lista sessões de um projeto project/[name]/session/ [sessionId]/page.tsx ← Server component: renderiza o visualizador de sessão policies/page.tsx ← Client component: gerenciamento de políticas + log de atividade actions/ - get-hooks-config.ts ← Lê a configuração + lista de políticas + get-hooks-config.ts ← Lê configuração + lista de políticas update-hooks-config.ts ← Ativa/desativa política update-policy-params.ts ← Atualiza parâmetros de política get-hook-activity.ts ← Pagina/pesquisa o log de atividade @@ -286,16 +286,16 @@ app/ **Fluxo de dados:** -- Componentes de página chamam `lib/projects.ts` e `lib/log-entries.ts` para ler dados de projetos/sessões diretamente do sistema de arquivos (sem camada de API para leituras). -- A página de Políticas usa Server Actions para todas as mutações (toggle, atualização de params, instalar/remover). +- Os componentes de página chamam `lib/projects.ts` e `lib/log-entries.ts` para ler dados de projetos/sessões diretamente do sistema de arquivos (sem camada de API para leituras). +- A página de Políticas usa Server Actions para todas as mutações (ativar/desativar, atualização de parâmetros, instalar/remover). - O visualizador de sessão analisa o formato de transcrição JSONL do Claude e renderiza uma linha do tempo de mensagens e chamadas de ferramentas. -**Decisões de design principais:** +**Principais decisões de design:** -- Sem banco de dados - todo o estado persistente está em arquivos simples (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions para mutações - nenhuma API REST necessária para operações CRUD. +- Sem banco de dados - todo estado persistente está em arquivos simples (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions para mutações - sem necessidade de API REST para operações CRUD. - React Server Components para páginas de leitura - carregamento inicial mais rápido, sem bundle de cliente para busca de dados. -- Client components apenas onde há necessidade de interatividade (toggles de política, busca de atividade, visualizador de log). +- Client components apenas onde interatividade é necessária (alternância de políticas, pesquisa de atividade, visualizador de logs). --- @@ -308,15 +308,15 @@ failproofai/ ├── src/hooks/ │ ├── handler.ts # Pipeline de eventos de hook │ ├── builtin-policies.ts # 39 definições de políticas -│ ├── policy-evaluator.ts # Motor de execução de políticas -│ ├── policy-registry.ts # Registro e lookup de políticas +│ ├── policy-evaluator.ts # Engine de execução de políticas +│ ├── policy-registry.ts # Registro e busca de políticas │ ├── policy-types.ts # Interfaces TypeScript │ ├── hooks-config.ts # Carregamento de configuração multi-escopo │ ├── custom-hooks-registry.ts # Registro de hooks baseado em globalThis │ ├── custom-hooks-loader.ts # Loader ESM para hooks JS do usuário -│ ├── manager.ts # Operações de instalar / remover / listar +│ ├── manager.ts # Operações de install / remove / list │ ├── install-prompt.ts # Prompt interativo de seleção de políticas -│ ├── hook-logger.ts # Logging para hook.log +│ ├── hook-logger.ts # Log em hook.log │ ├── hook-activity-store.ts # Persiste atividade em hook-activity/ │ └── llm-client.ts # Cliente de API LLM (para políticas com IA) ├── app/ # Dashboard Next.js (páginas + server actions) @@ -327,6 +327,6 @@ failproofai/ │ └── ... ├── components/ # Componentes React de UI compartilhados ├── contexts/ # Provedores de contexto React (tema, auto-refresh, telemetria) -├── examples/ # Exemplos de arquivos de hook personalizados +├── examples/ # Exemplos de arquivos de hook customizado └── __tests__/ # Testes unitários e E2E ``` \ No newline at end of file diff --git a/docs/pt-br/built-in-policies.mdx b/docs/pt-br/built-in-policies.mdx index 6641b93a..e177de4e 100644 --- a/docs/pt-br/built-in-policies.mdx +++ b/docs/pt-br/built-in-policies.mdx @@ -1,14 +1,14 @@ --- title: Políticas Integradas -description: "Todas as 39 políticas integradas que detectam modos de falha comuns de agentes" +description: "Todas as 39 políticas integradas que detectam falhas comuns de agentes" icon: shield --- -failproofai vem com 39 políticas integradas que detectam modos de falha comuns de agentes. Cada política é disparada em um tipo de evento de hook específico e nome de ferramenta. Dezenove políticas aceitam parâmetros que permitem ajustar seu comportamento sem escrever código. Cinco políticas de fluxo de trabalho impõem um pipeline de commit → push → PR → CI antes que Claude pare. +failproofai vem com 39 políticas integradas que detectam falhas comuns de agentes. Cada política é acionada em um tipo específico de evento de hook e nome de ferramenta. Dezenove políticas aceitam parâmetros que permitem ajustar seu comportamento sem escrever código. Cinco políticas de fluxo de trabalho impõem um pipeline commit → push → PR → CI antes que Claude pare. --- -## Visão geral +## Visão Geral As políticas são agrupadas em categorias: @@ -26,17 +26,17 @@ As políticas são agrupadas em categorias: | [Fluxo de trabalho](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | - **`block-`** — impede o agente de prosseguir. -- **`warn-`** — fornece ao agente contexto adicional para que ele possa se autocorrigir. -- **`sanitize-`** — remove dados sensíveis da saída da ferramenta antes que o agente os veja. +- **`warn-`** — fornece contexto adicional ao agente para que ele possa se autocorrigir. +- **`sanitize-`** — remove dados sensíveis da saída da ferramenta antes que o agente a veja. ### Namespaces -Toda política reside em um slot `/`. As políticas integradas pertencem ao +Cada política reside em um slot `/`. As políticas integradas pertencem ao namespace **`failproofai/`** — por exemplo, `failproofai/sanitize-jwt`. O namespace evita colisões quando você também carrega políticas personalizadas ou de terceiros -com nomes curtos semelhantes. +com nomes curtos similares. -Na sua configuração, você pode referenciar uma política integrada pelo nome curto ou pelo +Na sua configuração, você pode referenciar uma política integrada pelo seu nome curto ou pelo nome qualificado; ambas as formas resolvem para a mesma política: ```json @@ -55,33 +55,33 @@ Se um nome não contém `/`, failproofai o trata como pertencente ao namespace p --- -Toda política suporta um campo opcional `hint` em `policyParams`. O hint é adicionado à mensagem de deny ou instruct que Claude vê, fornecendo orientação acionável sem modificar o código da política. Funciona com políticas integradas, personalizadas e de convenção. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes. +Toda política suporta um campo opcional `hint` em `policyParams`. O hint é anexado à mensagem de deny ou instruct que Claude vê, fornecendo orientações práticas sem modificar o código da política. Funciona com políticas integradas, personalizadas e de convenção. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes. --- ## Comandos perigosos -Impede agentes de executar operações difíceis de desfazer ou que possam danificar o sistema hospedeiro. +Impede que agentes executem operações difíceis de desfazer ou que possam danificar o sistema host. ### `block-sudo` **Evento:** PreToolUse (Bash) **Padrão:** Nega qualquer comando `sudo` ou `doas`. -Bloqueia um comando que executa um binário de elevação **na posição de comando**. A correspondência é estrutural, não textual: o comando é dividido em segmentos como um shell faria, atribuições de prefixo (`FOO=bar`), redirecionamentos e executores com seus flags (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) são removidos, e o binário resultante é comparado pelo **basename**. Portanto, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` e `bash -c "sudo …"` são todos negados, e `doas` é tratado como a mesma capacidade sob um nome diferente. +Bloqueia um comando que executa um binário de elevação **na posição de comando**. A correspondência é estrutural em vez de textual: o comando é dividido em segmentos da forma que um shell faria, atribuições de prefixo (`FOO=bar`), redirecionamentos e executores com suas flags (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) são removidos, e o binário resultante é comparado pelo **basename**. Assim, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` e `bash -c "sudo …"` são todos negados, e `doas` é tratado como a mesma capacidade com nome diferente. -Como ancora na posição de comando e não na ocorrência da palavra em qualquer lugar, ele **não** é disparado em comandos que apenas o mencionam — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, ou uma alternância de `grep` contendo a palavra são executados normalmente. +Por ancorar na posição do comando em vez de na palavra aparecendo em qualquer lugar, ele **não** é acionado em comandos que apenas mencionam o termo — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, ou uma alternação `grep` contendo a palavra funcionam normalmente. -Isso detém a tentativa óbvia; não fecha a classe inteira. Um agente que pode executar shell arbitrário ainda pode alcançar elevação indiretamente — por meio de uma variável (`S=sudo; $S …`), um pipe com base64 decodificado, ou um script wrapper em disco — porque nenhuma inspeção de uma única string de comando pode seguir esses caminhos. Trate isso como uma proteção contra erros e escalação casual, não como uma barreira de segurança contra um agente determinado. Uma barreira real precisa ser imposta abaixo do shell. +Isso impede a tentativa óbvia; não fecha toda a classe. Um agente capaz de executar shell arbitrário ainda pode atingir a elevação indiretamente — por meio de uma variável (`S=sudo; $S …`), um pipe com base64 decodificado, ou um script wrapper em disco — porque nenhuma inspeção de uma única string de comando pode seguir esses caminhos. Trate isso como uma barreira contra erros e escalonamento casual, não como um limite de segurança contra um agente determinado. Um limite real precisa ser imposto abaixo do shell. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefixos de comando exatos que são permitidos. Cada entrada é comparada contra os tokens argv analisados. | +| `allowPatterns` | `string[]` | `[]` | Prefixos de comando exatos que são permitidos. Cada entrada é comparada com os tokens argv analisados. | **Exemplo:** @@ -95,10 +95,10 @@ Isso detém a tentativa óbvia; não fecha a classe inteira. Um agente que pode } ``` -Com esta configuração, `sudo systemctl status nginx` é permitido, mas `sudo rm /etc/hosts` é negado. +Com essa configuração, `sudo systemctl status nginx` é permitido, mas `sudo rm /etc/hosts` é negado. -Os padrões são comparados contra os tokens analisados, não a string de comando bruta. Isso evita bypass por meio de operadores de shell anexados (ex.: `sudo systemctl status x; rm -rf /` não corresponde a `sudo systemctl status *`). +Os padrões são comparados com tokens analisados, não com a string de comando bruta. Isso evita bypass por meio de operadores shell anexados (ex.: `sudo systemctl status x; rm -rf /` não corresponde a `sudo systemctl status *`). --- @@ -112,7 +112,7 @@ Os padrões são comparados contra os tokens analisados, não a string de comand | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Caminhos que são seguros para exclusão recursiva (ex.: `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Caminhos que podem ser excluídos recursivamente com segurança (ex.: `/tmp`). | **Exemplo:** @@ -140,7 +140,7 @@ Sem parâmetros. ### `block-failproofai-commands` **Evento:** PreToolUse (Bash) -**Padrão:** Nega comandos que desinstalariam ou desativariam o próprio failproofai (ex.: `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Padrão:** Nega comandos que desinstalariam ou desabilitariam o próprio failproofai (ex.: `npm uninstall failproofai`, `failproofai policies --uninstall`). Sem parâmetros. @@ -149,11 +149,11 @@ Sem parâmetros. ### `block-self-pause` **Evento:** PreToolUse (Bash) -**Padrão:** Nega `failproofai config --pause`, que suspende a aplicação para uma sessão. Pausar é uma decisão humana — um agente capaz de executar isso poderia desativar todas as outras políticas com um único comando. +**Padrão:** Nega `failproofai config --pause`, que suspende a execução de políticas por uma sessão. Pausar é uma decisão humana — um agente capaz de executar isso poderia desativar todas as outras políticas com um único comando. -Mais restrito que [`block-failproofai-commands`](#block-failproofai-commands) propositalmente, e não coberto por ele: essa política ancora em um limite de comando, então `npx -y failproofai config --pause` não corresponde a ela, e por ser abrangente é frequentemente desativada para que agentes possam executar `failproofai audit`. `--resume` e `--status` são permitidos — nenhum remove a aplicação. +Mais restrito que [`block-failproofai-commands`](#block-failproofai-commands) propositalmente, e não coberto por ele: essa política ancora em um limite de comando, então `npx -y failproofai config --pause` não corresponde a ela, e por ser ampla, frequentemente é desativada para que agentes possam executar `failproofai audit`. `--resume` e `--status` são permitidos — nenhum deles remove a execução de políticas. -Isso detém a tentativa direta, não a classe inteira: um agente ainda pode alcançar o mesmo estado por meio de um alias ou script wrapper. Fechar completamente requer que a pausa seja inacessível a partir de uma chamada de ferramenta. +Isso impede a tentativa direta, não toda a classe: um agente ainda pode atingir o mesmo estado por meio de um alias ou script wrapper. Fechar completamente requer que a pausa seja inacessível a partir de uma chamada de ferramenta. Sem parâmetros. @@ -161,9 +161,9 @@ Sem parâmetros. ## Comandos de infraestrutura -Impede agentes de codificação de executar CLIs de infraestrutura ou acionar pipelines de CI/CD. Todas as políticas nesta categoria são **opt-in** (`defaultEnabled: false`) — agentes que legitimamente precisam chamar `kubectl`, `terraform`, etc. não serão perturbados, a menos que você habilite a política. Quando habilitado, toda invocação do CLI correspondente é negada, a menos que o comando corresponda a uma entrada em `allowPatterns`. +Impede que agentes de codificação executem CLIs de infraestrutura ou acionem pipelines de CI/CD. Todas as políticas nesta categoria são **opt-in** (`defaultEnabled: false`) — agentes que legitimamente precisam chamar `kubectl`, `terraform`, etc. não serão interrompidos a menos que você habilite a política. Quando habilitada, cada invocação do CLI correspondente é negada, a menos que o comando corresponda a uma entrada em `allowPatterns`. -A gramática de padrões é a mesma que [`block-sudo`](#block-sudo): os tokens são comparados contra argv analisado, `*` é um curinga para um token, e qualquer comando contendo um operador de shell autônomo (`&&`, `||`, `|`, `;`) ou um token com metacaracteres de shell embutidos é rejeitado antes da correspondência com a lista de permissões para evitar bypasses por injeção. +A gramática de padrões é a mesma de [`block-sudo`](#block-sudo): os tokens são comparados com argv analisado, `*` é um curinga para um token, e qualquer comando contendo um operador shell standalone (`&&`, `||`, `|`, `;`) ou um token com metacaracteres shell embutidos é rejeitado antes da correspondência com a allowlist para evitar bypasses de injeção. ### `block-kubectl` @@ -188,7 +188,7 @@ A gramática de padrões é a mesma que [`block-sudo`](#block-sudo): os tokens s } ``` -Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f deploy.yaml` é negado. +Com essa configuração, `kubectl get pods` é permitido, mas `kubectl apply -f deploy.yaml` é negado. --- @@ -226,7 +226,7 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefixos de comando aws CLI que são permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefixos de comando do CLI aws que são permitidos. | **Exemplo:** @@ -276,7 +276,7 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefixos de comando az CLI que são permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefixos de comando do CLI az que são permitidos. | **Exemplo:** @@ -320,7 +320,7 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f ### `block-gh-pipeline` **Evento:** PreToolUse (Bash) -**Padrão:** Nega os seguintes subcomandos do CLI `gh` que mutam estado ou acionam pipelines: +**Padrão:** Nega os seguintes subcomandos do CLI `gh` que alteram estado ou acionam pipelines: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -329,13 +329,13 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f - `gh cache delete` - `gh secret set`, `gh secret delete` -Subcomandos `gh` somente leitura como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...` **não** são correspondidos por esta política — eles são rotineiramente necessários para verificações de fluxo de trabalho (incluindo o próprio `require-ci-green-before-stop` do failproofai). +Subcomandos `gh` somente leitura como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...` **não** são correspondidos por esta política — eles são frequentemente necessários para verificações de fluxo de trabalho (incluindo o próprio `require-ci-green-before-stop` do failproofai). **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocações scriptadas específicas a serem permitidas, mesmo que de outra forma seriam negadas. | +| `allowPatterns` | `string[]` | `[]` | Invocações específicas com script para permitir mesmo que normalmente fossem negadas. | **Exemplo:** @@ -353,7 +353,7 @@ Subcomandos `gh` somente leitura como `gh pr view`, `gh pr list`, `gh run list`, ## Segredos (sanitizadores) -Impede agentes de vazar credenciais em seu contexto ou saída. Políticas de sanitização são disparadas em eventos **PostToolUse**. Quando Claude executa um comando Bash, lê um arquivo ou chama qualquer ferramenta, essas políticas inspecionam a saída antes que ela seja retornada a Claude. Se um padrão de segredo for detectado, a política retorna uma decisão de deny que impede a saída de ser passada de volta. +Impede que agentes vazem credenciais para seu contexto ou saída. As políticas sanitizadoras são acionadas em eventos **PostToolUse**. Quando Claude executa um comando Bash, lê um arquivo ou chama qualquer ferramenta, essas políticas inspecionam a saída antes de ela ser retornada ao Claude. Se um padrão de segredo for detectado, a política retorna uma decisão de negação que impede a saída de ser repassada. ### `sanitize-jwt` @@ -367,13 +367,13 @@ Sem parâmetros. ### `sanitize-api-keys` **Evento:** PostToolUse (todas as ferramentas) -**Padrão:** Redige formatos comuns de chave de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chaves de acesso AWS (`AKIA`), chaves Stripe (`sk_live_`, `sk_test_`) e chaves Google API (`AIza`). +**Padrão:** Redige formatos comuns de chaves de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chaves de acesso AWS (`AKIA`), chaves Stripe (`sk_live_`, `sk_test_`) e chaves de API Google (`AIza`). **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Padrões de regex adicionais a serem tratados como segredos. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Padrões regex adicionais para tratar como segredos. | **Exemplo:** @@ -421,14 +421,14 @@ Sem parâmetros. ## Ambiente -Protege a configuração sensível do ambiente de ser lida ou exposta por agentes. +Protege configurações sensíveis de ambiente contra leitura ou exposição por agentes. ### `block-env-files` **Evento:** PreToolUse (Bash, Read) **Padrão:** Nega a leitura de arquivos `.env` via `cat .env`, chamadas da ferramenta `Read` com `.env` como caminho do arquivo, etc. -Não bloqueia `.envrc` ou outros arquivos adjacentes ao ambiente — apenas arquivos nomeados exatamente `.env`. +Não bloqueia `.envrc` ou outros arquivos relacionados a ambiente — apenas arquivos nomeados exatamente `.env`. Sem parâmetros. @@ -445,18 +445,18 @@ Sem parâmetros. ## Acesso a arquivos -Mantém os agentes trabalhando dentro dos limites do projeto e longe de arquivos sensíveis. +Mantém agentes trabalhando dentro dos limites do projeto e longe de arquivos sensíveis. ### `block-read-outside-cwd` **Evento:** PreToolUse (Read, Bash) -**Padrão:** Nega a leitura de arquivos fora da raiz do projeto. O limite é `CLAUDE_PROJECT_DIR` (definido uma vez por sessão pelo Claude Code), com fallback para o diretório de trabalho atual da sessão quando essa variável não estiver definida. Usar a raiz do projeto em vez do `cwd` atual significa que o limite permanece estável mesmo após Claude entrar com `cd` em um subdiretório. +**Padrão:** Nega a leitura de arquivos fora da raiz do projeto. O limite é `CLAUDE_PROJECT_DIR` (definido uma vez por sessão pelo Claude Code), com fallback para o diretório de trabalho atual da sessão quando essa variável não está definida. Usar a raiz do projeto em vez do `cwd` ativo significa que o limite permanece estável mesmo depois que Claude entra em um subdiretório com `cd`. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Prefixos de caminho absoluto que são permitidos mesmo fora da raiz do projeto. | +| `allowPaths` | `string[]` | `[]` | Prefixos de caminho absoluto que são permitidos mesmo se estiverem fora da raiz do projeto. | **Exemplo:** @@ -475,13 +475,13 @@ Mantém os agentes trabalhando dentro dos limites do projeto e longe de arquivos ### `block-secrets-write` **Evento:** PreToolUse (Write, Edit) -**Padrão:** Nega escritas em arquivos comumente usados para chaves privadas e certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Padrão:** Nega gravações em arquivos comumente usados para chaves privadas e certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Padrões de nome de arquivo adicionais (estilo glob) a serem bloqueados. | +| `additionalPatterns` | `string[]` | `[]` | Padrões adicionais de nome de arquivo (estilo glob) para bloquear. | **Exemplo:** @@ -499,7 +499,7 @@ Mantém os agentes trabalhando dentro dos limites do projeto e longe de arquivos ## Git -Previne pushes acidentais, force-pushes e erros de branch difíceis de desfazer. +Previne pushes acidentais, force-pushes e erros de branch que são difíceis de desfazer. ### `block-push-master` @@ -510,7 +510,7 @@ Previne pushes acidentais, force-pushes e erros de branch difíceis de desfazer. | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branch que não podem receber push diretamente. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branches que não podem receber push direto. | **Exemplo:** @@ -525,7 +525,7 @@ Previne pushes acidentais, force-pushes e erros de branch difíceis de desfazer. ``` -Para permitir push para todos os branches (efetivamente desativando esta política sem removê-la de `enabledPolicies`), defina `protectedBranches: []`. +Para permitir push em todos os branches (desabilitando efetivamente esta política sem removê-la de `enabledPolicies`), defina `protectedBranches: []`. --- @@ -533,13 +533,13 @@ Para permitir push para todos os branches (efetivamente desativando esta políti ### `block-work-on-main` **Evento:** PreToolUse (Bash) -**Padrão:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` enquanto a árvore de trabalho está em `main` ou `master`. A criação e troca de branch (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) não são afetadas. +**Padrão:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` enquanto a árvore de trabalho está no branch `main` ou `master`. Criação e troca de branches (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) não são afetadas. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branch nos quais commit/merge/rebase/cherry-pick é negado. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branches nos quais commit/merge/rebase/cherry-pick é negado. | --- @@ -548,7 +548,7 @@ Para permitir push para todos os branches (efetivamente desativando esta políti **Evento:** PreToolUse (Bash) **Padrão:** Nega `git push --force` e `git push -f`. -Sem parâmetros específicos de política. Use o [`hint`](/pt-br/configuration#hint-cross-cutting) transversal para sugerir alternativas: +Sem parâmetros específicos da política. Use o [`hint`](/pt-br/configuration#hint-cross-cutting) transversal para sugerir alternativas: ```json { @@ -591,12 +591,12 @@ Sem parâmetros. ## Banco de dados -Captura operações SQL destrutivas antes que sejam executadas em seu banco de dados. +Detecta operações SQL destrutivas antes que sejam executadas no seu banco de dados. ### `warn-destructive-sql` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a confirmar antes de executar SQL contendo `DROP TABLE`, `DROP DATABASE` ou `DELETE` sem uma cláusula `WHERE`. +**Padrão:** Instrui Claude a confirmar antes de executar SQL contendo `DROP TABLE`, `DROP DATABASE` ou `DELETE` sem cláusula `WHERE`. Sem parâmetros. @@ -639,7 +639,7 @@ Fornece contexto extra aos agentes antes de operações potencialmente arriscada ``` -O handler do hook impõe um limite de 1 MB de stdin em payloads. Para testar esta política com conteúdo pequeno, defina `thresholdKb` para um valor bem abaixo de 1024. +O handler de hook impõe um limite de 1 MB de stdin nos payloads. Para testar esta política com conteúdo pequeno, defina `thresholdKb` para um valor bem abaixo de 1024. --- @@ -673,19 +673,19 @@ Sem parâmetros. ## Gerenciadores de pacotes -Impõe quais gerenciadores de pacotes o agente tem permissão para usar. +Define quais gerenciadores de pacotes o agente pode usar. ### `prefer-package-manager` **Evento:** PreToolUse (Bash) -**Padrão:** Desabilitado. Quando habilitado, bloqueia qualquer comando de gerenciador de pacotes que não esteja na lista `allowed` e instrui Claude a reescrever o comando usando um gerenciador permitido. +**Padrão:** Desabilitado. Quando habilitado, bloqueia qualquer comando de gerenciador de pacotes que não esteja na lista `allowed` e diz ao Claude para reescrever o comando usando um gerenciador permitido. Detecta: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parâmetro | Tipo | Padrão | Descrição | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Nomes de gerenciadores de pacotes permitidos. Qualquer gerenciador detectado que não esteja nesta lista é bloqueado. Quando vazio, a política é uma no-op. | -| `blocked` | string[] | `[]` | Nomes adicionais de gerenciadores a bloquear além da lista integrada (ex.: `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Nomes de gerenciadores de pacotes permitidos. Qualquer gerenciador detectado que não esteja nesta lista é bloqueado. Quando vazio, a política não faz nada. | +| `blocked` | string[] | `[]` | Nomes adicionais de gerenciadores para bloquear além da lista integrada (ex.: `['pdm', 'pipx']`). | A lista de bloqueio integrada cobre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Use `blocked` para adicionar gerenciadores que não estão nesta lista. @@ -703,13 +703,13 @@ A lista de bloqueio integrada cobre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, } ``` -Com esta configuração, `pip install flask` e `pdm install flask` são ambos negados com uma mensagem instruindo Claude a usar `uv` ou `bun` em vez disso. Comandos como `uv pip install flask` são permitidos porque `uv` está na lista de permissões e é verificado primeiro. +Com essa configuração, `pip install flask` e `pdm install flask` são ambos negados com uma mensagem dizendo ao Claude para usar `uv` ou `bun` em vez disso. Comandos como `uv pip install flask` são permitidos porque `uv` está na allowlist e é verificado primeiro. --- ## Comportamento de IA -Detecta quando agentes travam ou se comportam de forma inesperada. +Detecta quando agentes ficam travados ou se comportam de forma inesperada. ### `warn-repeated-tool-calls` @@ -722,39 +722,39 @@ Sem parâmetros. ## Fluxo de trabalho -Impõe um fluxo de trabalho disciplinado ao final da sessão. Essas políticas são disparadas no evento **Stop** e negam ao agente a possibilidade de parar até que cada condição seja atendida. Elas seguem uma cadeia de dependência natural: commit → push → PR → CI. Se uma política negar, as políticas posteriores na cadeia são ignoradas (deny curto-circuita). +Impõe um fluxo de trabalho disciplinado no final da sessão. Essas políticas são acionadas no evento **Stop** e impedem o agente de parar até que cada condição seja atendida. Elas seguem uma cadeia de dependência natural: commit → push → PR → CI. Se uma política negar, as políticas posteriores na cadeia são ignoradas (a negação causa curto-circuito). Todas as políticas de fluxo de trabalho são **fail-open**: se a ferramenta necessária não estiver disponível (ex.: `gh` não instalado, sem remote git), a política permite com uma mensagem informativa explicando por que a verificação foi ignorada. ### Semântica de Stop por CLI -A aplicação de Stop parece ligeiramente diferente entre os seis CLIs suportados porque cada um expõe um contrato de hook de "agente finalizado" diferente. O **resultado** é o mesmo — o agente não consegue parar enquanto um gate de fluxo de trabalho está falhando — mas os **mecanismos** diferem. A tabela abaixo resume; apenas o Pi tem uma peculiaridade visível ao usuário que vale entender antes de habilitar uma política `require-*-before-stop`. +A execução do Stop difere ligeiramente entre os seis CLIs suportados porque cada um expõe um contrato de hook diferente para "agente terminou". O **resultado** é o mesmo — o agente não consegue parar enquanto um gate de fluxo de trabalho está falhando — mas os **mecanismos** diferem. A tabela abaixo resume; apenas o Pi tem uma peculiaridade visível ao usuário que vale entender antes de habilitar uma política `require-*-before-stop`. -| CLI | Quando o gate dispara | O que você vê | +| CLI | Quando o gate é acionado | O que você vê | |---|---|---| -| Claude Code | Mesmo loop de agente, imediatamente | Claude continua trabalhando — corrige o problema e então tenta terminar novamente. Sem interrupção visível para você. | -| Codex | Mesmo loop de agente, imediatamente | Igual ao Claude. | -| GitHub Copilot CLI | Mesmo loop de agente, imediatamente | Igual ao Claude (usa o canal de retry `{decision:"block", reason}` do Copilot — verificado empiricamente contra o Copilot CLI 1.0.41). | -| Cursor Agent | Mesmo loop de agente, imediatamente | Igual ao Claude (usa o canal `{followup_message}` do Cursor — limitado ao `loop_limit`, padrão de 5 tentativas). | -| OpenCode | Mesmo loop de agente, imediatamente | Igual ao Claude (usa a chamada SDK `client.session.prompt(...)` do OpenCode roteada através de `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Próximo turno do usuário** | **Pi para visivelmente** quando o gate dispara — seu loop de agente sai e você é retornado ao prompt. O gate então dispara na próxima vez que você enviar um prompt: failproofai adiciona uma diretiva `MANDATORY ACTION REQUIRED` ao prompt de sistema daquele turno, instruindo o LLM a completar a etapa de fluxo de trabalho (commit, push, etc.) antes de fazer o que você pediu. | +| Claude Code | Mesmo loop do agente, imediatamente | Claude continua trabalhando — corrige o problema e tenta terminar novamente. Nenhuma interrupção visível para você. | +| Codex | Mesmo loop do agente, imediatamente | Igual ao Claude. | +| GitHub Copilot CLI | Mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal de retry `{decision:"block", reason}` do Copilot — verificado empiricamente contra Copilot CLI 1.0.41). | +| Cursor Agent | Mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal `{followup_message}` do Cursor — limitado por `loop_limit`, padrão 5 tentativas). | +| OpenCode | Mesmo loop do agente, imediatamente | Igual ao Claude (usa a chamada SDK `client.session.prompt(...)` do OpenCode roteada por `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Próximo turno do usuário** | **Pi para visivelmente** quando o gate é acionado — seu loop de agente sai e você é devolvido ao prompt. O gate então é acionado na próxima vez que você submete um prompt: failproofai adiciona uma diretiva `MANDATORY ACTION REQUIRED` ao início do system prompt desse turno, instruindo o LLM a completar a etapa de fluxo de trabalho (commit, push, etc.) antes de fazer o que você pediu. | -**Limitação do Pi.** O `AgentEndEvent` do Pi (o equivalente upstream do hook `Stop` do Claude) não tem tipo Result — quando dispara, o loop de agente do Pi já saiu. O Pi não pode ser forçado a repetir o mesmo loop da forma que Claude / Copilot / Cursor / OpenCode podem. failproofai desloca o gate para o evento `before_agent_start` do Pi (que dispara após o próximo prompt do usuário) para que a verificação de fluxo de trabalho ainda seja aplicada, apenas no próximo turno em vez do atual. +**Limitação do Pi.** O `AgentEndEvent` do Pi (equivalente upstream do hook `Stop` do Claude) não tem tipo Result — no momento em que ele é acionado, o loop de agente do Pi já saiu. O Pi não pode ser forçado a repetir o mesmo loop da forma que Claude / Copilot / Cursor / OpenCode podem. failproofai desloca o gate para o evento `before_agent_start` do Pi (que é acionado após o próximo prompt do usuário) para que a verificação de fluxo de trabalho ainda seja imposta, apenas no próximo turno em vez do atual. **O que isso significa na prática:** -- Após o Pi parar, o motivo da negação é capturado na memória com chave pelo id de sessão do Pi. O próximo prompt que você enviar no mesmo processo Pi o consome: o LLM vê a diretiva `MANDATORY ACTION REQUIRED` no topo do seu prompt de sistema, faz o commit (ou push / abre o PR / aguarda o CI) e somente então continua com sua solicitação. O motivo de negação capturado é de uso único — uma vez consumido, o gate está limpo. -- O gate é limitado pelo tempo de vida do processo do Pi. Se você der `Ctrl+C` no Pi ou sair entre os turnos, a entrada na memória é descartada junto com o processo e o gate é perdido. Claude, Copilot, Cursor e OpenCode têm o mesmo limite (encerrar o agente e o gate é perdido) — o Pi apenas o torna mais visível porque o agente sai visivelmente antes do gate disparar. -- Uma negação pendente também é limpa em `session_shutdown` por qualquer motivo (`new` / `resume` / `fork` / `quit`), portanto um gate obsoleto de uma sessão anterior não pode vazar para uma nova sessão iniciada no mesmo processo Pi. +- Após o Pi parar, o motivo de negação é capturado em memória com chave pelo id de sessão do Pi. O próximo prompt que você submeter no mesmo processo Pi o drena: o LLM vê a diretiva `MANDATORY ACTION REQUIRED` no topo do seu system prompt, faz o commit (ou push / abre o PR / aguarda CI) e só então continua com sua solicitação. O motivo de negação capturado é de uso único — uma vez drenado, o gate está limpo. +- O gate é limitado pelo tempo de vida do processo Pi. Se você der `Ctrl+C` no Pi ou sair entre os turnos, a entrada em memória é descartada junto com o processo e o gate é perdido. Claude, Copilot, Cursor e OpenCode têm o mesmo limite (matar o agente e o gate é perdido) — o Pi apenas torna isso mais visível porque o agente sai visivelmente antes de o gate ser acionado. +- Uma negação pendente também é limpa no `session_shutdown` por qualquer motivo (`new` / `resume` / `fork` / `quit`), então um gate obsoleto de uma sessão anterior não pode vazar para uma nova sessão iniciada no mesmo processo Pi. -Se você precisar de retry no mesmo loop no estilo Claude, execute suas políticas `Stop` sob qualquer um dos outros cinco CLIs suportados. Estamos acompanhando o Pi upstream para um futuro tipo Result em `AgentEndEvent` que nos permitiria fechar essa lacuna. +Se você precisa de retry no mesmo loop no estilo Claude, execute suas políticas `Stop` em qualquer um dos outros cinco CLIs suportados. Estamos acompanhando o upstream do Pi para um futuro tipo Result no `AgentEndEvent` que nos permitiria fechar essa lacuna. ### `require-commit-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando há alterações não commitadas (arquivos modificados, staged ou não rastreados). Retorna uma mensagem informativa quando o diretório de trabalho está limpo. +**Padrão:** Nega a parada quando há mudanças não commitadas (arquivos modificados, staged ou não rastreados). Retorna uma mensagem informativa quando o diretório de trabalho está limpo. Sem parâmetros. @@ -763,13 +763,13 @@ Sem parâmetros. ### `require-push-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando há commits não enviados por push ou quando o branch atual não tem um branch de rastreamento remoto. Sugere `git push -u` para criar um branch de rastreamento se necessário. Falha aberto se nenhum remote estiver configurado. +**Padrão:** Nega a parada quando há commits não enviados ou quando o branch atual não tem branch de rastreamento remoto. Sugere `git push -u` para criar um branch de rastreamento se necessário. Falha aberto se nenhum remote estiver configurado. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Nome do remote para o qual fazer push. | +| `remote` | `string` | `"origin"` | Nome do remote para fazer push. | **Exemplo:** @@ -788,14 +788,14 @@ Sem parâmetros. ### `require-pr-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando não existe pull request para o branch atual, ou quando o PR existente está fechado sem merge. Instrui Claude a criar um PR com `gh pr create`. Quando o PR é **mergeado**, a política permite (o trabalho foi entregue) e a mensagem sugere mudar do branch (`git checkout main && git pull`). +**Padrão:** Nega a parada quando não existe pull request para o branch atual, ou quando o PR existente está fechado sem merge. Instrui Claude a criar um PR com `gh pr create`. Quando o PR está **merged**, a política permite (o trabalho foi entregue) e a mensagem sugere trocar de branch (`git checkout main && git pull`). Sem parâmetros. Esta política requer o [GitHub CLI](https://cli.github.com/) (`gh`) instalado e autenticado. Execute `gh auth login` com um personal access token que tenha o escopo `repo` para acesso de leitura a -pull requests. Se `gh` não estiver instalado ou autenticado, a política falha aberta e reporta o motivo a Claude. +pull requests. Se `gh` não estiver instalado ou autenticado, a política falha aberto e reporta o motivo ao Claude. --- @@ -803,12 +803,12 @@ pull requests. Se `gh` não estiver instalado ou autenticado, a política falha ### `require-no-conflicts-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando o branch atual não consegue fazer merge limpo no branch base. A política primeiro confirma que há um PR `OPEN` no GitHub para o branch — sem um, não há alvo de merge a impor, então toda a política curto-circuita para permitir. Uma vez que um PR `OPEN` é confirmado, dois probes independentes são executados: +**Padrão:** Nega a parada quando o branch atual não pode ser mergeado limpo no branch base. A política primeiro confirma que há um PR `OPEN` no GitHub para o branch — sem um, não há alvo de merge a impor, então toda a política faz curto-circuito para permitir. Uma vez confirmado um PR `OPEN`, duas verificações independentes são executadas: -1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. Em caso de conflito, a mensagem de negação nomeia os arquivos em conflito para que Claude saiba exatamente o que resolver. -2. **GitHub** — reutiliza o resultado de `gh pr view --json mergeable,state` já obtido na pré-verificação. Captura conflitos que um `origin/` local desatualizado perderia (ex.: alguém fez merge de um PR conflitante em `main` desde o último fetch). Um resultado `CONFLICTING` nega. Um resultado `UNKNOWN` também nega e instrui Claude a aguardar ~10 segundos e re-verificar antes de tentar parar novamente — isso previne falsos negativos enquanto o GitHub recalcula. +1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. Em conflito, a mensagem de negação nomeia os arquivos conflitantes para que Claude saiba exatamente o que resolver. +2. **GitHub** — reutiliza o resultado de `gh pr view --json mergeable,state` já obtido na pré-verificação. Detecta conflitos que um `origin/` local desatualizado perderia (ex.: alguém fez merge de um PR conflitante em `main` desde o último fetch). Um resultado `CONFLICTING` nega. Um resultado `UNKNOWN` também nega e instrui Claude a aguardar ~10 segundos e reverificar antes de tentar parar novamente — isso evita falsos negativos enquanto o GitHub recomputa. -Ignora completamente (permite) quando: `gh` não está instalado, não há PR para o branch, o estado do PR não é `OPEN` (ex.: `MERGED`, `CLOSED`), ou `gh pr view` retorna saída não analisável. Também falha aberto quando `origin/` está ausente localmente ou quando não há commits à frente da base — esses fall-throughs da Camada 1 ainda consultam a mesclabilidade do PR em cache antes de permitir. +Ignora completamente (permite) quando: `gh` não está instalado, nenhum PR existe para o branch, o estado do PR não é `OPEN` (ex.: `MERGED`, `CLOSED`), ou `gh pr view` retorna saída não analisável. Também falha aberto quando `origin/` está ausente localmente ou quando não há commits à frente do base — esses fall-throughs da Camada 1 ainda consultam a mergeabilidade do PR em cache antes de permitir. **Parâmetros:** @@ -818,8 +818,8 @@ Ignora completamente (permite) quando: `gh` não está instalado, não há PR pa O GitHub CLI (`gh`) é necessário para esta política. A política usa `gh pr view` para confirmar -que existe um PR `OPEN` antes de executar qualquer probe de conflito — sem `gh`, a política -curto-circuita para permitir. Execute `gh auth login` com um personal access token que tenha +que existe um PR `OPEN` antes de executar qualquer verificação de conflito — sem `gh`, a política +faz curto-circuito para permitir. Execute `gh auth login` com um personal access token que tenha o escopo `repo` para acesso de leitura a pull requests. @@ -828,14 +828,14 @@ o escopo `repo` para acesso de leitura a pull requests. ### `require-ci-green-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando verificações de CI estão falhando ou ainda em execução no branch atual. Verifica tanto as execuções de fluxo de trabalho do GitHub Actions quanto as verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata conclusões `skipped`, `cancelled` e `neutral` como não-falhas (este último cobre, por exemplo, alertas do Socket Security em PRs de contribuidores externos, onde o app intencionalmente reporta neutro em vez de sucesso/falha). Retorna uma mensagem informativa quando todas as verificações passam. +**Padrão:** Nega a parada quando as verificações de CI estão falhando ou ainda em execução no branch atual. Verifica tanto as execuções de workflow do GitHub Actions quanto as verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata as conclusões `skipped`, `cancelled` e `neutral` como não-falhas (a última cobre, por exemplo, alertas do Socket Security em PRs de contribuidores externos, onde o app intencionalmente reporta neutral em vez de success/failure). Retorna uma mensagem informativa quando todas as verificações passam. Sem parâmetros. Esta política requer o [GitHub CLI](https://cli.github.com/) (`gh`) instalado e autenticado. Execute `gh auth login` com um personal access token que tenha o escopo `repo` para acesso de leitura a -execuções de fluxo de trabalho do Actions e à API de Verificações. Se `gh` não estiver instalado ou autenticado, a política falha aberta e reporta o motivo a Claude. +execuções de workflow do Actions e à API de verificações. Se `gh` não estiver instalado ou autenticado, a política falha aberto e reporta o motivo ao Claude. --- diff --git a/docs/pt-br/cli/audit.mdx b/docs/pt-br/cli/audit.mdx index 30cb14ac..86bee694 100644 --- a/docs/pt-br/cli/audit.mdx +++ b/docs/pt-br/cli/audit.mdx @@ -1,26 +1,26 @@ --- -title: Auditar sessões passadas (beta) -description: "Conte com que frequência o agente fez coisas desnecessárias ou arriscadas em transcrições anteriores" +title: Auditar sessões anteriores (beta) +description: "Conte quantas vezes o agente fez coisas desnecessárias ou arriscadas em transcrições passadas" --- - **Recurso em beta.** O recurso de auditoria é lançado em beta enquanto coletamos feedback inicial. - O catálogo de detectores e o formato do relatório podem mudar antes da próxima versão estável. - Abra uma issue se algo parecer errado. + **Funcionalidade beta.** O audit está em beta enquanto coletamos feedback inicial. + O catálogo de detectores e o formato do relatório podem mudar antes da próxima + versão estável. Abra uma issue se algo parecer errado. -A auditoria reproduz suas transcrições passadas da CLI do agente pelo mecanismo de políticas do failproofai -e gera um relatório visual e compartilhável na **página do dashboard `/audit`** -— o arquétipo do seu agente, uma pontuação de 0–100 e exatamente quais políticas +O audit reproduz suas transcrições passadas do agent-CLI pela engine de políticas do failproofai +e gera um relatório visual e compartilhável na **página `/audit` do dashboard** +— o arquétipo do seu agente, uma pontuação de 0 a 100, e exatamente quais políticas teriam identificado o quê. ## Como executar -Três formas de acessar — todas levam ao mesmo relatório `/audit`. +Três formas de entrar — todas levam ao mesmo relatório `/audit`. -```bash npx (sem instalação) +```bash npx (sem instalar) npx -y failproofai audit ``` @@ -35,98 +35,102 @@ failproofai - - `npx -y failproofai audit` baixa o failproofai, executa a varredura e abre o - dashboard para você — nada precisa ser instalado antes. + + `npx -y failproofai audit` baixa o failproofai, executa o scan e abre o + dashboard para você — sem precisar instalar nada antes. - `failproofai audit` executa a varredura no seu terminal e abre - `localhost:8020/audit` automaticamente ao finalizar. + `failproofai audit` executa o scan no seu terminal e abre + `localhost:8020/audit` automaticamente ao terminar. Execute `failproofai` e clique em **Audit** na barra de navegação (entre Policies e - Projects), ou abra `/audit` diretamente. + Projects), ou acesse `/audit` diretamente. - Execute `failproofai audit -h` (ou `--help`) para ver o uso. A auditoria roda **completamente + Execute `failproofai audit -h` (ou `--help`) para ver o uso. O audit roda **completamente offline** — sem conta ou rede necessária — e o dashboard continua disponível até você encerrá-lo com `Ctrl+C`. -O dashboard varre transcrições passadas da CLI do agente nesta máquina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) e relata com que frequência o agente fez coisas que o failproofai foi criado para prevenir — verificações de variáveis de ambiente, force pushes, prefixos redundantes `cd `, loops de polling com sleep, releitura de arquivos recém-editados, e mais. +O dashboard escaneia transcrições passadas do agent CLI nesta máquina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) e informa com que frequência o agente fez coisas que o failproofai foi criado para impedir — verificações de variáveis de ambiente, force pushes, prefixos redundantes `cd `, loops de sleep-polling, releituras de arquivos recém-editados, e mais. -Para cada transcrição, cada evento de uso de ferramenta é reproduzido pelas 39 políticas embutidas **e** pelos 8 detectores exclusivos de auditoria que identificam padrões ainda não cobertos por políticas em tempo real. As contagens são agregadas por política/detector em todas as sessões. +Para cada transcrição, todo evento de uso de ferramenta é reproduzido pelas 39 políticas embutidas **e** por 8 detectores exclusivos do audit que identificam padrões ainda não cobertos pelas políticas em tempo real. As contagens são agregadas por política/detector em todas as sessões. ## O que você recebe -A página `/audit` é um **pôster** de tela única e compartilhável seguido por quatro seções abaixo da dobra: +A página `/audit` é um **poster** de tela única e compartilhável seguido por quatro seções abaixo da dobra: -1. **Pôster** — a identidade do seu agente em um relance: seu **arquétipo** (um de 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), as palavras-chave da persona, o quão raro esse arquétipo é e uma **pontuação de 0–100** com uma faixa de nível (`S` até `bottom tier`). Feito para compartilhar — poste no X ou LinkedIn, ou baixe como PNG. -2. **`// strengths`** — o que seu agente já faz bem, como números reais da varredura (ex.: % de chamadas de ferramenta limpas, `0` tentativas de push para main), exibido apenas onde a política relevante tem um histórico limpo. -3. **`// quirks`** — o que passou despercebido: uma tabela classificada de comportamentos que o failproofai teria capturado — *quando* aconteceu pela última vez, *o que passou* (e o detector embutido que teria bloqueado), sua *gravidade* e com que frequência foi *visto* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — a lista de correções prescritas: uma linha por política com um `failproofai policy add ` para copiar e colar, além de um botão **install all** que habilita todas as recomendações de uma vez e mostra sua **pontuação projetada** caso você o faça. -5. **`// come back better`** — crie o hábito: defina um **lembrete** de re-auditoria por e-mail (`3d` / `7d` / `14d` / `30d`) ou re-audite agora, e **convide um amigo** para fazer sua própria auditoria (enviado pelo failproof.ai, com cópia para você). Lembretes e convites requerem login. +1. **Poster** — a identidade do seu agente de relance: seu **arquétipo** (um dos 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), suas palavras-chave de persona, quão raro é esse arquétipo e uma **pontuação de 0 a 100** com uma faixa de tier (`S` até `bottom tier`). Feito para compartilhar — publique no X ou LinkedIn, ou baixe como PNG. +2. **`// strengths`** — o que seu agente já faz bem, com números reais do scan (ex.: % de chamadas de ferramenta limpas, `0` tentativas de push para main), exibido apenas onde a política relevante tem um histórico limpo. +3. **`// quirks`** — o que passou despercebido: uma tabela classificada de comportamentos que o failproofai teria detectado — *quando* ocorreu pela última vez, *o que passou* (e o builtin que teria bloqueado), sua *severidade* e com que frequência foi *visto* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — a lista de correções prescritas: uma linha por política com um `failproofai policy add ` para copiar e colar, mais um botão **install all** que ativa todas as recomendações de uma vez e exibe sua **pontuação projetada** caso você o faça. +5. **`// come back better`** — crie o hábito: configure um **lembrete** de re-audit por e-mail (`3d` / `7d` / `14d` / `30d`) ou faça um re-audit agora, e **convide um amigo** para executar o próprio audit (enviado pelo failproof.ai, com cópia para você). Lembretes e convites exigem login. -## Auditorias agendadas +## Audits agendados -Se você executa o **daemon failproofaid** (veja [`failproofai config`](/pt-br/cli/install-policies)), -ele pode re-executar a auditoria para você em um agendamento e atualizar o relatório `/audit` -em segundo plano. Está **desativado por padrão**, pois a varredura lê o *conteúdo* -de cada transcrição de sessão do agente nesta máquina — nada é varrido por um timer +Se você executar o **daemon failproofaid** (veja [`failproofai config`](/pt-br/cli/install-policies)), +ele pode re-executar o audit em um agendamento e atualizar o relatório `/audit` em +segundo plano. Está **desativado por padrão**, pois o scan lê o *conteúdo* +de cada transcrição de sessão do agente nesta máquina — nada escaneia em um timer até que você solicite. -Ative em `~/.failproofai/config.toml`: +Ative em `~/.failproofai/config.json` — adicione a chave `audit` junto com +o que mais o arquivo já contém: -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | Chave | Significado | |---|---| -| `auto` | `true` habilita a varredura agendada. Qualquer outra coisa — ausente, `false`, `"yes"` — está desativado. | -| `interval_days` | Dias entre varreduras. Limitado a 1–90; `0`, um número negativo ou não numérico cai de volta para `7`. | +| `auto` | `true` ativa o scan agendado. Qualquer outra coisa — ausente, `false`, `"yes"` — está desativado. | +| `interval_days` | Dias entre scans. Limitado a 1–90; `0`, um valor negativo ou não numérico usa `7` como padrão. | -- O agendamento é **baseado no relógio de parede**, então sobrevive a suspensões e reinicializações: um laptop - que estava dormindo além do horário previsto executa **uma vez** ao acordar, nunca um acúmulo. +- O agendamento é baseado em **horário do relógio**, então sobrevive a suspensões e reinicializações: um laptop + que estava em suspensão além do prazo executa **uma vez** ao acordar, nunca um backlog. - Cada execução é um processo separado de baixa prioridade (`nice 19`) — nunca o caminho de hook do daemon, - que permanece livre para responder a chamadas de ferramentas. -- Uma varredura é ignorada se `failproofai audit` ou o re-run do dashboard já estiver em andamento; ela é - repetida logo depois em vez de ser tratada como falha. + que fica livre para responder chamadas de ferramentas. +- Um scan é ignorado se `failproofai audit` ou o re-run do dashboard já estiver em andamento; + é repetido logo depois em vez de ser tratado como falha. - O progresso é gravado em `~/.failproofai/state/audit-schedule.json` (última execução, - próximo prazo). O daemon é o responsável por esse arquivo — altere a cadência em `config.toml`. + próximo prazo). O daemon é o dono desse arquivo — altere a cadência em `config.json`. -Se você habilitou isso em uma máquina configurada com uma versão mais antiga do failproofai, execute +Se você ativou isso em uma máquina configurada com uma versão antiga do failproofai, execute `failproofai config` uma vez. A definição de serviço do daemon precisa de uma entrada extra antes de poder iniciar o CLI, e a atualização faz parte desse comando. -## Detectores exclusivos de auditoria +## Detectores exclusivos do audit -Esses detectores identificam padrões de "comportamento ineficiente" que não são (ainda) aplicados em tempo real. Eles são executados apenas durante a auditoria e nunca bloqueiam uma chamada de ferramenta ao vivo. +Estes detectam padrões de "comportamento ineficiente" que ainda não são aplicados em tempo real. Eles rodam apenas durante o audit e nunca bloqueiam uma chamada de ferramenta ao vivo. | Detector | O que conta | |---|---| -| `redundant-cd-cwd` | Comandos Bash começando com `cd && …` mesmo que os comandos já sejam executados em `cwd`. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` em um único arquivo fonte — use a ferramenta `Read`. | +| `redundant-cd-cwd` | Comandos Bash começando com `cd && …` mesmo que os comandos já rodem em `cwd`. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` em um único arquivo de código-fonte — use a ferramenta `Read`. | | `prefer-edit-over-sed-awk` | Edições in-place com `sed -i` / `awk … > file` — use a ferramenta `Edit`. | -| `prefer-write-over-heredoc` | Escrita de arquivos com Heredoc / `echo > file` multilinha — use a ferramenta `Write`. | -| `sleep-polling-loop` | `sleep N` longo (≥ 30s) ou loops de polling `while …; sleep …; done`. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — limite ao `cwd` em vez disso. | +| `prefer-write-over-heredoc` | Escrita de arquivos com heredoc / `echo > file` multilinha — use a ferramenta `Write`. | +| `sleep-polling-loop` | Loops de polling com `sleep N` longo (≥ 30s) ou `while …; sleep …; done`. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — restrinja ao `cwd`. | | `git-commit-no-verify` | `git commit … --no-verify` / `-n`, ignorando hooks. | -| `reread-after-edit` | `Read` de um arquivo que acabou de ser editado com `Edit`/`Write` na mesma sessão. | +| `reread-after-edit` | `Read` de um arquivo que acabou de ser modificado com `Edit`/`Write` na mesma sessão. | ## Caches -- **Cache por transcrição** em `~/.failproofai/cache/audit/.json` com chave por `(mtime, size, engineVersion, detectorVersion)` — invalidado automaticamente quando a transcrição ou o código de política/detector muda. Cada entrada também armazena um timestamp `cachedAt` como **metadado de TTL** (não faz parte da chave de cache); entradas com mais de **7 dias** são rejeitadas na leitura para que resultados de longa duração não sobrevivam à evolução da intenção dos detectores. -- **Cache do resultado completo** em `~/.failproofai/audit-dashboard.json` (modo 0600). Permite que o dashboard seja renderizado instantaneamente na navegação sem re-executar. Também rejeitado na leitura após o **TTL de 7 dias** — `/audit` então cai em seu estado vazio e solicita uma nova execução. Clique em `[ re-audit now ]` próximo ao final do relatório para atualizar — o re-audit envia `noCache: true`, contornando o cache por transcrição e revarrendo todas as transcrições em vez de retornar o resultado em cache; a execução transmite o progresso via uma faixa fixa no topo e substitui o resultado no lugar ao concluir com sucesso (sem recarregamento de página; um re-audit com falha mantém o relatório anterior). +- **Cache por transcrição** em `~/.failproofai/cache/audit/.json` com chave `(mtime, size, engineVersion, detectorVersion)` — invalida automaticamente quando a transcrição ou o código de política/detector muda. Cada entrada também armazena um timestamp `cachedAt` como **metadados de TTL** (não faz parte da chave de cache); entradas com mais de **7 dias** são rejeitadas na leitura para que resultados antigos não sobrevivam à evolução dos detectores. +- **Cache do resultado completo** em `~/.failproofai/audit-dashboard.json` (modo 0600). Permite que o dashboard renderize instantaneamente na navegação sem re-executar. Também rejeitado na leitura após o **TTL de 7 dias** — o `/audit` então cai para seu estado vazio e solicita uma nova execução. Clique em `[ re-audit now ]` perto do final do relatório para atualizar — o re-audit envia `noCache: true`, ignorando o cache por transcrição e re-escaneando todas as transcrições em vez de retornar o resultado em cache; a execução transmite o progresso via uma faixa fixa no topo e substitui o resultado no lugar ao terminar com sucesso (sem recarregar a página; um re-audit com falha mantém o relatório anterior). ## Notas -- **Sem mutação.** A auditoria é reproduzida em modo somente leitura. `warn-repeated-tool-calls` é ignorado porque seu sidecar por sessão seria modificado de outra forma. -- **Políticas de fluxo de trabalho ignoradas.** Políticas `require-*-before-stop` são acionadas apenas em eventos `Stop` e `execSync` contra o estado git ao vivo — elas não têm uma interpretação significativa de "o que teria acontecido em 2025", portanto não aparecem nas contagens de auditoria. -- **Políticas personalizadas ignoradas.** Hooks personalizados fornecidos pelo usuário não são reproduzidos (eles podem ter mudado desde a sessão original). \ No newline at end of file +- **Sem mutação.** O audit reproduz em modo somente leitura. `warn-repeated-tool-calls` é ignorado porque seu sidecar por sessão seria modificado de outra forma. +- **Políticas de workflow ignoradas.** As políticas `require-*-before-stop` disparam apenas em eventos `Stop` e `execSync` contra o estado git ao vivo — elas não têm interpretação significativa de "o que teria acontecido em 2025", então não aparecem nas contagens do audit. +- **Políticas customizadas ignoradas.** Hooks customizados fornecidos pelo usuário não são reproduzidos (podem ter mudado desde a sessão original). \ No newline at end of file diff --git a/docs/pt-br/cli/dashboard.mdx b/docs/pt-br/cli/dashboard.mdx index b66adb58..9fec7c44 100644 --- a/docs/pt-br/cli/dashboard.mdx +++ b/docs/pt-br/cli/dashboard.mdx @@ -1,13 +1,13 @@ --- -title: Visualizar sessões -description: "Inicie o painel para navegar pelas sessões do agente e gerenciar políticas" +title: Ver sessões +description: "Inicie o dashboard para navegar pelas sessões do agente e gerenciar políticas" --- ```bash failproofai ``` -Inicia o painel web em `http://localhost:8020`. +Inicia o dashboard web em `http://localhost:8020`. ## Opções @@ -16,7 +16,7 @@ Inicia o painel web em `http://localhost:8020`. | `--port ` | Porta para escutar (padrão: `8020`) | | `--allowed-origins ` | Hosts/IPs separados por vírgula com permissão para acessar recursos de desenvolvimento | -Para apontar o painel para uma pasta de projeto Claude diferente da padrão, defina a variável de ambiente `CLAUDE_PROJECTS_PATH` ao iniciar. +Para apontar o dashboard para uma pasta de projetos Claude diferente da padrão, defina a variável de ambiente `CLAUDE_PROJECTS_PATH` ao iniciar. ## Exemplos diff --git a/docs/pt-br/cli/environment-variables.mdx b/docs/pt-br/cli/environment-variables.mdx index 503eea06..b153d2ed 100644 --- a/docs/pt-br/cli/environment-variables.mdx +++ b/docs/pt-br/cli/environment-variables.mdx @@ -6,67 +6,70 @@ description: "Configure o comportamento do failproofai com variáveis de ambient ## Dashboard | Variável | Descrição | -|----------|-----------| +|----------|-------------| | `PORT` | Porta do dashboard (padrão: `8020`) | | `CLAUDE_PROJECTS_PATH` | Substitui o local onde as pastas de projetos do Claude Code são encontradas | | `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Páginas do dashboard a ocultar, separadas por vírgula | | `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs com permissão para acessar recursos de desenvolvimento. Equivalente a `--allowed-origins`. | -## Logs +## Logging | Variável | Descrição | -|----------|-----------| +|----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Nível de log do servidor (padrão: `warn`) | | `FAILPROOFAI_HOOK_LOG_FILE` | Caminho personalizado para o arquivo de log de hooks, ou `true` para o padrão (`~/.failproofai/logs/hooks.log`) | ## Telemetria O failproofai envia telemetria de uso anônima por padrão. Há duas formas de -desativá-la, e prevalece sempre a mais restritiva — uma variável de ambiente -nunca pode reativar algo que o arquivo de configuração desligou. +desativá-la, e prevalece sempre a opção mais restritiva — uma variável de +ambiente nunca pode reativar algo que o arquivo de configuração desativou. | Variável | Descrição | -|----------|-----------| +|----------|-------------| | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Desativa a telemetria de uso anônima para este processo | -Para desativar permanentemente na máquina, adicione o seguinte ao `~/.failproofai/config.toml`: +Para desativá-la permanentemente na máquina, adicione o seguinte ao `~/.failproofai/config.json`: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -O arquivo de configuração é a opção recomendada se você executa o **daemon failproofaid**. -O daemon é um serviço de escopo do sistema, e seu ambiente não inclui -variáveis exportadas pelo seu shell — portanto, `FAILPROOFAI_TELEMETRY_DISABLED` não -chega até ele. `[telemetry] enabled = false` é lido tanto pela CLI quanto pelo daemon. +O arquivo de configuração é a opção recomendada caso você execute o **daemon failproofaid**. +O daemon é um serviço com escopo de sistema e seu ambiente não inclui +variáveis exportadas do seu shell — portanto, `FAILPROOFAI_TELEMETRY_DISABLED` não +chegará até ele. `[telemetry] enabled = false` é lido tanto pela CLI quanto pelo daemon. -O daemon reporta apenas seu próprio **ciclo de vida**: quando iniciou (e se a -execução anterior encerrou corretamente), quando parou, quando seu worker de avaliação -foi iniciado ou reiniciado, quando uma tarefa de coleta falhou e o resultado de uma -sincronização de políticas da nuvem. Esses eventos carregam valores de baixa cardinalidade -e contagens — nunca um caminho de arquivo, um comando, uma política, um prompt ou -qualquer conteúdo lido de uma transcrição. Não há evento por chamada de ferramenta. +O daemon reporta apenas seu próprio **ciclo de vida**: que foi iniciado (e se a +execução anterior encerrou normalmente), que foi parado, quando seu worker de avaliação +foi criado ou reiniciado, quando uma tarefa de coleta falhou e o resultado de uma +sincronização de políticas na nuvem. Esses eventos carregam valores e contagens de baixa +cardinalidade — nunca um caminho de arquivo, um comando, uma política, um prompt ou +qualquer dado lido de uma transcrição. Não existe evento por chamada de ferramenta. ## Autenticação | Variável | Descrição | -|----------|-----------| +|----------|-------------| | `FAILPROOF_API_URL` | Substitui a URL base do servidor de API usada pelo diálogo de autenticação do dashboard. O padrão é `https://api.befailproof.ai`; defina como `http://localhost:8080` (ou outro endereço) ao executar um servidor de API local. | | `FAILPROOFAI_AUTH_DIR` | Substitui o local onde `auth.json` é armazenado (padrão: `~/.failproofai`). Útil principalmente para testes isolados. | ## Prompt de primeira execução | Variável | Descrição | -|----------|-----------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignora o prompt que oferece a instalação de políticas na primeira invocação simples do `failproofai` | +|----------|-------------| +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignora o prompt que oferece a instalação de políticas na primeira execução simples do `failproofai` | ## LLM (para avaliação de políticas) | Variável | Descrição | -|----------|-----------| +|----------|-------------| | `FAILPROOFAI_LLM_BASE_URL` | Endpoint da API do LLM (padrão: `https://api.openai.com/v1`) | | `FAILPROOFAI_LLM_API_KEY` | Chave de API para políticas baseadas em LLM | | `FAILPROOFAI_LLM_MODEL` | Nome do modelo (padrão: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/pt-br/cli/hook.mdx b/docs/pt-br/cli/hook.mdx index 4c36ab78..9f5acbb2 100644 --- a/docs/pt-br/cli/hook.mdx +++ b/docs/pt-br/cli/hook.mdx @@ -14,16 +14,16 @@ Lê um payload JSON do stdin, avalia todas as políticas habilitadas e encerra c | Código de saída | Decisão | Efeito | |-----------------|---------|--------| | `0` | `allow` | Permite a ação | -| `1` | `deny` | Bloqueia a ação — Claude recebe o motivo da negação | +| `1` | `deny` | Bloqueia a ação — o Claude recebe o motivo da negação | | `2` | `instruct` | Injeta orientações no contexto do Claude | -### Tipos de eventos suportados +### Tipos de evento suportados | Categoria | Eventos | |-----------|---------| | **Execução de ferramentas** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Ciclo de vida da sessão** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | -| **Interação com o usuário** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | +| **Interação do usuário** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | | **Subagentes e tarefas** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **Configuração** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **Sistema de arquivos** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | diff --git a/docs/pt-br/cli/install-policies.mdx b/docs/pt-br/cli/install-policies.mdx index 45761ffb..9301edb6 100644 --- a/docs/pt-br/cli/install-policies.mdx +++ b/docs/pt-br/cli/install-policies.mdx @@ -15,7 +15,7 @@ Aliases: `failproofai p -i` | Flag | Descrição | |------|-----------| -| `--cli claude\|codex\|copilot` | CLI(s) do agente para instalação; separados por espaço (ex.: `--cli claude codex copilot`) ou repetidos. Omita para detectar os CLIs instalados e exibir um prompt. | +| `--cli claude\|codex\|copilot` | CLI(s) do agente para instalar; separados por espaço (ex.: `--cli claude codex copilot`) ou repetidos. Omita para detectar os CLIs instalados e exibir um prompt. | | `--scope user` | Instala no arquivo de configurações com escopo de usuário (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Padrão. | | `--scope project` | Instala no arquivo de configurações com escopo de projeto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | | `--scope local` | Apenas Claude — instala em `/.claude/settings.local.json`. Codex e Copilot não possuem escopo `local`. | @@ -24,7 +24,7 @@ Aliases: `failproofai p -i` ## Comportamento - **Sem nomes de política** — abre um prompt interativo para selecionar políticas -- **Nomes específicos** — habilita essas políticas (adicionadas às que já estiverem habilitadas) +- **Nomes específicos** — habilita essas políticas (adicionadas às que já estão habilitadas) - **`all`** — habilita todas as políticas disponíveis A instalação é aditiva: executar `--install` novamente adiciona novas políticas sem remover as existentes. @@ -44,10 +44,10 @@ failproofai policies --install all # Instalar com um arquivo de políticas personalizado failproofai policies --install --custom ./my-policies.js -# Instalar para OpenAI Codex (escopo de projeto) +# Instalar para o OpenAI Codex (escopo de projeto) failproofai policies --install --cli codex --scope project -# Instalar para GitHub Copilot CLI (beta) no projeto atual +# Instalar para o GitHub Copilot CLI (beta) no projeto atual failproofai policies --install --cli copilot --scope project # Instalar para os três CLIs de uma vez diff --git a/docs/pt-br/cli/migrate.mdx b/docs/pt-br/cli/migrate.mdx new file mode 100644 index 00000000..5c26045c --- /dev/null +++ b/docs/pt-br/cli/migrate.mdx @@ -0,0 +1,117 @@ +--- +title: Migrar o diretório home +description: "Atualiza ~/.failproofai para o layout desta versão e permite visualizar o que aconteceria antes de executar" +--- + +```bash +failproofai migrate --dry-run # exibe o plano, sem alterar nada +failproofai migrate # executa a migração +``` + +A maioria das pessoas nunca precisa digitar esse comando. Ele é executado +automaticamente no primeiro comando após uma atualização, e o +[`failproofai update`](/pt-br/cli/update) já o inclui. Use-o diretamente quando quiser +visualizar o plano antes que ele aconteça, ou para executar a migração por conta +própria. + +## Baseado no layout, não na versão + +`~/.failproofai/VERSION` registra um número de **layout** — a estrutura do +diretório, não a versão que o criou. As migrações são indexadas por esse número, +o que torna a diferença entre versões muito distantes barata: + +- As versões do npm mudam a cada lançamento, podendo haver dezenas entre dois layouts. +- Assim, uma máquina que pula trinta lançamentos **sem nenhuma mudança de layout** executa **zero** migrações, e não trinta operações sem efeito. +- E uma máquina que pula vários layouts de uma vez executa cada etapa em ordem, com cada etapa conhecendo apenas seus dois extremos. + +Isso importa porque o npm não consegue atualizar um pacote instalado por conta própria. Uma máquina que fica em uma versão por meses e depois pula vários layouts é o caso normal, não o excepcional. + +## A simulação (dry run) + +`--dry-run` exibe a cadeia exata e os arquivos que seriam salvos primeiro, sem +alterar absolutamente nada — nenhuma migração, nenhum backup, nenhum registro: + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## O que é preservado e o que é recriado + +Cada caminho no diretório home declara o tipo de dado que contém, e isso determina +se uma migração pode descartá-lo. A regra: **dados derivados e que podem ser +buscados novamente podem ser descartados; qualquer coisa que você digitou, +qualquer coisa ainda não entregue e qualquer coisa que identifica a máquina é +preservada.** + +| Preservado | Recriado ou buscado novamente | +|---|---| +| `config.json` — configurações, `daemon.configured`, caminhos de captura adicionais | O cache de auditoria | +| `credentials.json` — sua inscrição na nuvem | Implantações gerenciadas pela nuvem (buscadas novamente e verificadas por digest na próxima consulta) | +| `policies-config.json` — sua seleção de políticas e parâmetros | Estado temporário do daemon | +| `policies/` — seus próprios arquivos de política e os auxiliares que eles importam | | +| `hook-activity/` — o log de decisões que o dashboard lê | | +| Eventos ainda na fila aguardando envio | | +| `cursors/` — marcas d'água do coletor | | +| O binário do daemon em `bin/` | | + + + Os eventos ainda não entregues são preservados em vez de descartados porque a + perda seria permanente, não apenas lenta: a marca d'água do coletor já avançou + além de qualquer coisa na fila, portanto nada leria novamente aquele intervalo + de uma transcrição. A migração também instrui o daemon a entregar o que está na + fila assim que terminar, então o resultado habitual é que não sobra nada a + preservar. + + +Chaves que uma versão *mais nova* escreveu em `config.json`, `credentials.json` ou +`policies-config.json` também são preservadas, em vez de descartadas por um leitor +mais antigo. + +## O registro que fica + +``` +~/.failproofai/migrations/ + applied.json uma entrada por etapa: layout, CLI, timestamp, duração, resultado + backup-layout/ cópias dos arquivos insubstituíveis, feitas antes da primeira etapa +``` + +`applied.json` é o que responde "por quais etapas esta máquina realmente passou" — +a primeira pergunta que vale fazer quando algo parece errado após uma atualização. +Anexe-o a um relatório de bug. + +O backup é deliberadamente pequeno, em vez de uma cópia de todo o diretório: a +migração não exclui mais nada insubstituível por design, portanto o que vale a +pena proteger é um *defeito em uma etapa*, e esses poucos arquivos são onde tal +defeito causaria dano. + +## Se uma etapa falhar + +A cadeia para nesse ponto. `VERSION` só é atualizado por uma etapa que foi +concluída com sucesso, portanto o diretório home permanece marcado com o layout +antigo e o próximo comando tentará novamente — um diretório home nunca é marcado +como atual com base em uma migração parcial. A etapa é registrada em `applied.json` +com `"ok": false`, e o backup permanece onde foi feito. + +## Um diretório home mais novo é recusado, não migrado + +Se `~/.failproofai/` foi escrito por uma versão do failproofai **mais nova** do +que a que você está executando, o comando para e instrui você a atualizar. Os +dados estão íntegros e uma CLI mais nova os lê; migrar "para frente" a partir +deles não é algo que existe, e redefini-los destruiria algo recuperável. + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +O daemon aplica a mesma regra: `failproofaid` se recusa a iniciar com um layout +que não reconhece, em vez de ler e escrever em caminhos que foram movidos. \ No newline at end of file diff --git a/docs/pt-br/cli/remove-policies.mdx b/docs/pt-br/cli/remove-policies.mdx index 511db0c6..c8d51135 100644 --- a/docs/pt-br/cli/remove-policies.mdx +++ b/docs/pt-br/cli/remove-policies.mdx @@ -38,6 +38,6 @@ failproofai policies --uninstall block-sudo # Remover hooks de todos os escopos failproofai policies --uninstall --scope all -# Limpar o caminho de políticas customizadas +# Limpar o caminho de políticas personalizadas failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/pt-br/cli/update.mdx b/docs/pt-br/cli/update.mdx new file mode 100644 index 00000000..2e4a9af7 --- /dev/null +++ b/docs/pt-br/cli/update.mdx @@ -0,0 +1,64 @@ +--- +title: Atualizar após um upgrade +description: "Conclua a metade de um upgrade que o npm não consegue fazer: migrar o diretório home e sincronizar o daemon" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +Esse é o upgrade completo. O `npm` substitui a CLI; o `failproofai update` faz o restante. + +## Por que existe um segundo comando + +O `npm install -g` substitui apenas uma coisa — a CLI. Outras duas partes de uma instalação do failproofai ficam fora do pacote intencionalmente, e nenhuma delas é movida quando o npm é executado: + +- **`~/.failproofai/`**, suas configurações, registro em nuvem, seleção de políticas e histórico. Uma nova versão pode organizá-lo de forma diferente, e essa reorganização precisa ser feita por código que conhece as duas estruturas. +- **O binário do daemon `failproofaid`**, em `~/.failproofai/bin/failproofaid-`. Ele é deliberadamente *fora* do `node_modules`: um upgrade que substituísse o arquivo enquanto um serviço está em execução redirecionaria um daemon ativo para um binário compilado de uma fonte diferente, e remover o pacote o deletaria de baixo de um serviço que então entraria em loop de falhas a cada inicialização. + +Portanto, após o `npm install -g` sozinho, a CLI está atualizada e o daemon não está. O `failproofaid` se recusa a iniciar com um layout de diretório home que não reconhece — a versão barulhenta desse conflito, em vez da silenciosa — por isso as duas metades precisam ser sincronizadas. O `failproofai update` é essa etapa. + +## O que ele faz + + + + Lê o layout registrado em `~/.failproofai/VERSION` e executa os passos necessários para atualizá-lo para o que esta versão utiliza. Normalmente nenhum — veja [`failproofai migrate`](/pt-br/cli/migrate). + + + A partir do pacote de plataforma que o npm já baixou, quando possível (sem acesso à rede), caso contrário a partir do asset de release desta versão exata, verificado com SHA-256 antes de ser utilizado. + + + Verificado por sondagem, não por suposição — um gerenciador de serviços reporta um processo como ativo no momento em que ele bifurca, o que não é o mesmo que estar funcionando corretamente. + + + +## Opções + +| Flag | Efeito | +|------|--------| +| `--no-daemon` | Migra apenas o diretório home, deixando o daemon na versão atual. | + + + `--no-daemon` deixa um daemon com versão desatualizada no lugar. Em uma máquina configurada para exigir o daemon, todo evento de hook **falha de forma fechada** se o daemon não conseguir responder — e um daemon que se recusa a iniciar com um diretório home migrado não consegue responder. Prefira deixar a metade do daemon ser executada. + + +## Se algo der errado + +O comando encerra com código diferente de zero e indica qual metade falhou. Dois casos importantes: + +- **Uma etapa de migração não foi concluída.** O diretório home é deixado marcado com seu layout *antigo*, então o próximo comando tentará novamente — nenhum diretório home é marcado como atual com base em uma migração parcial. Cópias das suas configurações e registro foram salvas antes de qualquer execução, em `~/.failproofai/migrations/backup-layout/`. +- **O daemon não pôde ser reiniciado sem uma senha.** O `sudo -n` é utilizado deliberadamente, para que nada solicite senha durante uma exibição de progresso. O comando imprime a linha exata para você executar manualmente. + + + Nada aqui requer o assistente de configuração interativo. Suas configurações, registro em nuvem e seleção de políticas sobrevivem a um upgrade, então uma máquina migrada aplica as políticas exatamente como antes — o que importa mais nas máquinas sem ninguém na frente delas: um runner de CI, uma máquina de frota, um gateway headless. + + +## Automatizando + +O `failproofai update` é não-interativo e seguro de executar quando não há nada a fazer — ele reporta "nenhuma migração foi necessária" e encerra com código 0. Adicioná-lo após cada upgrade em um script de provisionamento ou Dockerfile é o uso pretendido: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` em um build de imagem, onde ainda não há serviço para reiniciar.) \ No newline at end of file diff --git a/docs/pt-br/cli/version.mdx b/docs/pt-br/cli/version.mdx index adec07d2..14f63d0b 100644 --- a/docs/pt-br/cli/version.mdx +++ b/docs/pt-br/cli/version.mdx @@ -1,11 +1,11 @@ --- title: Verificar versão -description: "Exibir a versão instalada do failproofai" +description: "Exibe a versão instalada do failproofai" --- ```bash failproofai --version -# or +# ou failproofai -v ``` diff --git a/docs/pt-br/configuration.mdx b/docs/pt-br/configuration.mdx index f0fb8329..99d533f7 100644 --- a/docs/pt-br/configuration.mdx +++ b/docs/pt-br/configuration.mdx @@ -4,7 +4,7 @@ description: "Formato do arquivo de configuração, sistema de três escopos e r icon: gear --- -failproofai utiliza arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde as políticas personalizadas são carregadas. A configuração foi projetada para ser fácil de compartilhar com sua equipe — faça commit no repositório e todos os desenvolvedores terão a mesma rede de segurança do agente. +failproofai usa arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde políticas personalizadas são carregadas. A configuração foi projetada para ser fácil de compartilhar com sua equipe — faça o commit no seu repositório e todos os desenvolvedores terão a mesma rede de segurança para o agente. --- @@ -18,7 +18,7 @@ Existem três escopos de configuração, avaliados em ordem de prioridade: | **local** | `.failproofai/policies-config.local.json` | Substituições pessoais por repositório, ignoradas pelo git | | **global** | `~/.failproofai/policies-config.json` | Padrões no nível do usuário para todos os projetos | -Quando failproofai recebe um evento de hook, ele carrega e mescla todos os três arquivos que existem para o diretório de trabalho atual. +Quando failproofai recebe um evento de hook, ele carrega e mescla os três arquivos que existem para o diretório de trabalho atual. ### Regras de mesclagem @@ -29,10 +29,10 @@ project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← união com deduplicação +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← união sem duplicatas ``` -**`policyParams`** — o primeiro escopo que define parâmetros para uma determinada política vence completamente. Não há mesclagem profunda de valores dentro dos parâmetros de uma política. +**`policyParams`** — o primeiro escopo que define parâmetros para uma determinada política vence por completo. Não há mesclagem profunda de valores dentro dos parâmetros de uma política. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,16 +42,20 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project vence, global ``` ```text -project: (sem entrada block-sudo) -local: (sem entrada block-sudo) +project: (sem entrada de block-sudo) +local: (sem entrada de block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← cai para o global +resolved: { allowPatterns: ["sudo systemctl status"] } ← passa para o global ``` **`customPoliciesPaths` / `customPoliciesPath`** — o primeiro escopo que define qualquer uma das formas vence. -**`disabledCustomPolicies`** — união entre todos os escopos. O painel escreve um ID qualificado pela fonte aqui quando você desativa uma política individual de um arquivo de políticas explícito ou de convenção. Políticas não listadas permanecem habilitadas por padrão; os IDs incluem o arquivo de origem para que políticas com o mesmo nome em múltiplos arquivos possam ser controladas de forma independente. +**`disabledCustomPolicies`** — união entre todos os escopos. O painel escreve um +ID qualificado pela fonte aqui quando você desativa uma política individual de um +arquivo de política explícito ou de convenção. Políticas não listadas permanecem habilitadas por +padrão; os IDs incluem o arquivo de origem para que políticas com o mesmo nome em múltiplos arquivos +possam ser controladas de forma independente. **`llm`** — o primeiro escopo que o define vence. @@ -106,7 +110,7 @@ Tipo: `string[]` Lista de nomes de políticas a habilitar. Os nomes devem corresponder exatamente aos identificadores de política exibidos por `failproofai policies`. Consulte [Políticas Integradas](/pt-br/built-in-policies) para a lista completa. -Políticas que não estão em `enabledPolicies` estão inativas, mesmo que tenham entradas em `policyParams`. +Políticas que não estão em `enabledPolicies` ficam inativas, mesmo que tenham entradas em `policyParams`. ### `policyParams` @@ -114,7 +118,7 @@ Tipo: `Record>` Substituições de parâmetros por política. A chave externa é o nome da política; as chaves internas são específicas de cada política. Cada política documenta seus parâmetros disponíveis em [Políticas Integradas](/pt-br/built-in-policies). -Se uma política tiver parâmetros, mas você não os especificar, os padrões integrados da política serão utilizados. Usuários que não configuram `policyParams` obtêm comportamento idêntico às versões anteriores. +Se uma política tem parâmetros mas você não os especifica, os padrões integrados da política são usados. Usuários que não configuram `policyParams` de forma alguma têm comportamento idêntico ao das versões anteriores. Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento do disparo do hook, mas sinalizadas como avisos quando você executa `failproofai policies`. @@ -122,7 +126,7 @@ Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenc Tipo: `string` (opcional) -Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use-a para fornecer orientações acionáveis ao Claude sem modificar a própria política. +Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use para fornecer ao Claude orientações acionáveis sem modificar a própria política. Funciona com qualquer tipo de política — integrada, personalizada (`custom/`), convenção de projeto (`.failproofai-project/`) ou convenção de usuário (`.failproofai-user/`). @@ -143,40 +147,45 @@ Funciona com qualquer tipo de política — integrada, personalizada (`custom/`) } ``` -Quando `block-force-push` bloqueia, Claude vê: *"Force-pushing is blocked. Try creating a fresh branch instead."* +Quando `block-force-push` nega, Claude vê: *"Force-pushing is blocked. Try creating a fresh branch instead."* -Valores não-string e strings vazias são silenciosamente ignorados. Se `hint` não estiver definido, o comportamento permanece inalterado (compatível com versões anteriores). +Valores não string e strings vazias são silenciosamente ignorados. Se `hint` não estiver definido, o comportamento permanece inalterado (compatível com versões anteriores). ### `customPoliciesPath` Tipo: `string` (caminho absoluto) -Caminho para um arquivo JavaScript contendo políticas de hook personalizadas. Isso é definido automaticamente por `failproofai policies --install --custom ` (o caminho é resolvido para absoluto antes de ser armazenado). +Caminho para um arquivo JavaScript contendo políticas de hook personalizadas. Este campo é definido automaticamente por `failproofai policies --install --custom ` (o caminho é resolvido para absoluto antes de ser armazenado). O arquivo é carregado novamente a cada evento de hook — não há cache. Consulte [Políticas Personalizadas](/pt-br/custom-policies) para detalhes de criação. ### Políticas baseadas em convenção -Além do `customPoliciesPath` explícito, failproofai descobre e carrega automaticamente arquivos de políticas de diretórios `.failproofai/policies/`: +Além do `customPoliciesPath` explícito, failproofai descobre e carrega automaticamente arquivos de política dos diretórios `.failproofai/policies/`: | Nível | Diretório | Escopo | |-------|-----------|-------| | Projeto | `.failproofai/policies/` | Compartilhado com a equipe via controle de versão | -| Usuário | `~/.failproofai/policies/custom-policies/` | Pessoal, aplicado a todos os projetos | +| Usuário | `~/.failproofai/policies/` | Pessoal, aplica-se a todos os projetos | - O diretório no nível do usuário foi movido um nível abaixo na reorganização - do diretório home. Arquivos deixados no antigo `~/.failproofai/policies/` são - movidos para `custom-policies/` automaticamente na primeira vez que você - executa qualquer comando `failproofai` após a atualização, e o comando informa - quais arquivos foram movidos. + Coloque suas políticas diretamente em `~/.failproofai/policies/`. A + pasta `cloud-policies/` ao lado delas contém políticas que sua organização implantou + nesta máquina — a descoberta não desce em subdiretórios, portanto ela + nunca é escaneada, e nada que você colocar em `policies/` pode colidir com ela. + + Se você estiver atualizando de uma versão que usava + `~/.failproofai/policies/custom-policies/`, tudo nessa pasta — seus + arquivos de política, qualquer `lib/` de auxiliares que eles importam e quaisquer arquivos de dados que leem + — é movido de volta automaticamente na primeira vez que você executa um comando `failproofai`, + e o comando informa o que foi movido. -**Correspondência de arquivos:** Somente arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados (por exemplo, `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados. +**Correspondência de arquivos:** Apenas arquivos que correspondem a `*policies.{js,mjs,ts}` são carregados (por exemplo, `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados. -**Sem necessidade de configuração:** Políticas de convenção não requerem entradas em `policies-config.json`. Basta colocar os arquivos no diretório e eles serão detectados no próximo evento de hook. +**Sem necessidade de configuração:** Políticas de convenção não exigem entradas em `policies-config.json`. Basta colocar os arquivos no diretório e eles serão detectados no próximo evento de hook. -**Carregamento em união:** Tanto o projeto quanto os diretórios de convenção do usuário são verificados. Todos os arquivos correspondentes de ambos os níveis são carregados (ao contrário de `customPoliciesPath`, que usa o primeiro escopo que vence). +**Carregamento por união:** Ambos os diretórios de convenção — de projeto e de usuário — são escaneados. Todos os arquivos correspondentes de ambos os níveis são carregados (diferentemente de `customPoliciesPath`, que usa o primeiro escopo que vence). Consulte [Políticas Personalizadas](/pt-br/custom-policies) para mais detalhes e exemplos. @@ -199,24 +208,24 @@ Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é ## Gerenciando a configuração pela CLI -Os comandos `policies --install` e `policies --uninstall` escrevem no arquivo de configurações de hook da CLI do agente (os pontos de entrada do hook), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados: +Os comandos `policies --install` e `policies --uninstall` escrevem no arquivo de configurações de hooks da CLI do seu agente (os pontos de entrada do hook), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados: -- **Configurações da CLI do agente** — instrui o agente a chamar `failproofai --hook ` em cada uso de ferramenta: +- **Configurações da CLI do agente** — instrui o agente a chamar `failproofai --hook ` a cada uso de ferramenta: - **Claude Code**: `~/.claude/settings.json` (usuário), `/.claude/settings.json` (projeto), `/.claude/settings.local.json` (local) - - **OpenAI Codex**: `~/.codex/hooks.json` (usuário), `/.codex/hooks.json` (projeto) — Codex não possui escopo `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuário), `/.github/hooks/failproofai.json` (projeto) — Copilot não possui escopo `local`. As entradas de hook usam os campos de comando `bash`/`powershell` com chave de SO do Copilot com `timeoutSec`; o arquivo carrega um marcador de nível superior `version: 1`. O suporte ao Copilot CLI está em **beta** enquanto verificamos o esquema de registro `events.jsonl` (que os documentos públicos não especificam) em mais sessões do mundo real. **O modo agente do VS Code Copilot Chat (Preview)** lê configurações de hook de `.github/hooks/*.json`, `~/.copilot/hooks/*.json` e `~/.claude/settings.json` (governado pela configuração `chat.hookFilesLocations`) usando o mesmo contrato no formato Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exatamente os caminhos que esta integração `copilot` e a integração `claude` (`~/.claude/settings.json`) já escrevem, então `failproofai policies --install --cli copilot` (ou `--cli claude`) **já aplica no modo agente do VS Code** sem necessidade de uma integração `vscode` separada (confirmado ao vivo pelos logs de descoberta do VS Code). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuário), `/.cursor/hooks.json` (projeto) — Cursor não possui escopo `local`. As entradas de hook usam o formato no estilo Claude `{type, command, timeout}` (sem divisão `bash`/`powershell`), mas armazenadas sob chaves de evento em camelCase (`preToolUse`, `beforeSubmitPrompt`, …) em um array plano conforme o [esquema de hooks](https://cursor.com/docs/hooks) do Cursor; o arquivo carrega um marcador de nível superior `version: 1`. O handler canonicaliza camelCase → PascalCase via `CURSOR_EVENT_MAP` para que as políticas integradas existentes disparem sem alterações. O suporte ao Cursor Agent está em **beta** enquanto verificamos o formato de transcrição em disco do Cursor (não especificado nos documentos públicos) em mais instalações do mundo real. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuário), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projeto) — OpenCode não possui escopo `local`. Ao contrário das outras cinco CLIs, o OpenCode **não possui sistema de hook de comando externo**: ele carrega plugins JS/TS em processo registrados explicitamente via o array `plugin: []` em `opencode.json` (a autodescoberta de `.opencode/plugins/` **não** é como os plugins carregam no opencode v1.14.33). A instalação inclui um pequeno shim de plugin gerado que chama o binário failproofai em subprocesso e traduz a resposta JSON no formato Claude de volta para a semântica do plugin: `throw new Error()` para negação de evento de ferramenta (cancela a chamada da ferramenta), `client.session.prompt(...)` para instruct E para negação de `Stop` / `SubagentStop` (envia o motivo da negação como a próxima mensagem do usuário — o único canal de força de nova tentativa, já que `session.idle` é apenas notificação e lançar a partir dele é um no-op), e no-op para allow. O shim canonicaliza tanto nomes de ferramentas (minúsculas → PascalCase via `OPENCODE_TOOL_MAP`) quanto chaves de argumentos de entrada de ferramenta (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, por exemplo `filePath` → `file_path`, `oldString` → `old_string`) antes de encaminhar para o binário, para que builtins de verificação de caminho como `block-read-outside-cwd`, `block-env-files` e `block-secrets-write` disparem sem alterações nas chamadas de ferramenta do OpenCode. As sessões ficam no banco de dados SQLite do opencode em `~/.local/share/opencode/opencode.db`; o visualizador de sessões do painel as lê via `opencode db --format json` e `opencode export `. O suporte ao OpenCode está em **beta** enquanto verificamos o comportamento em versões diferentes e em mais sessões do mundo real. Veja a [documentação de plugins do OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuário), `/.pi/settings.json` (projeto) — Pi não possui escopo `local`. O Pi carrega pacotes de extensão TypeScript na inicialização; o arquivo de configurações é um array de strings plano `{"packages": ["./relative/path", …]}`. failproofai escreve uma única entrada no array de pacotes apontando para seu diretório `pi-extension/` empacotado. A extensão internamente se inscreve nos eventos `tool_call` / `user_bash` / `input` / `session_start` do Pi e executa `failproofai --hook --cli pi` em shell; o handler canonicaliza underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` para que as políticas integradas existentes disparem sem alterações. Os argumentos de entrada de ferramenta também são canonicalizados via `PI_TOOL_INPUT_MAP` (Read / Write / Edit do Pi entregam `path` em vez de `file_path`; mapear a chave de nível superior permite que `block-env-files` e `block-secrets-write` disparem — `block-read-outside-cwd` já tinha um fallback para `path`). O suporte ao Pi está em **beta** enquanto a API de extensão e o layout do log de sessão do Pi se estabilizam. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**somente escopo de usuário** — Hermes não possui configuração de projeto/local). Hermes é um **gateway** Slack/Telegram, então uma única instalação intercepta chamadas de ferramentas de cada plataforma (Slack/Telegram/cli/cron) **e** subagentes internos. As entradas de hook são um par `{command, timeout}` (timeout em **segundos**) sob um mapa `hooks:` com chave pelos eventos snake_case do Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); o handler canonicaliza eventos via `HERMES_EVENT_MAP` e nomes de ferramentas via `HERMES_TOOL_MAP` para que as políticas integradas disparem sem alterações. A configuração é editada por meio de um round-trip YAML `Document` com preservação de comentários para que as outras configurações do operador sobrevivam, e a instalação define `hooks_auto_accept: true` para que o gateway headless (sem TTY) execute os hooks sem um prompt de consentimento. O avaliador emite o contrato stdout `{"decision":"block","reason"}` do Hermes (Hermes ignora códigos de saída). **Limitações:** Hermes não possui evento `Stop` de fim de turno, então os builtins `require-*-before-stop` nunca disparam para ele (não aplicável, não quebrado); `instruct` degrada para allow com nota registrada (sem canal de contexto adicional); e a redação de segredo de saída (`sanitize-*`) não pode reescrever a saída da ferramenta pelo contrato de hook de shell. Hermes é **também** uma fonte de **auditoria** offline — o painel lê suas sessões de gateway diretamente de `~/.hermes/state.db`. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**somente escopo de usuário** — OpenClaw não possui configuração de projeto/local). Como o Hermes, OpenClaw é um **gateway** multi-canal auto-hospedado, então uma única instalação intercepta chamadas de ferramentas de cada canal e seus subagentes internos. A aplicação é executada por meio dos **hooks de plugin em processo** do OpenClaw (seus hooks internos baseados em arquivo são apenas de observação e não podem bloquear), então — como OpenCode/Pi — failproofai inclui um pacote estático `openclaw-plugin/` que gera o binário failproofai de forma assíncrona e traduz o veredicto. A instalação registra o diretório de plugin incluído em `plugins.load.paths[]` do `openclaw.json` e o habilita em `plugins.entries.failproofai` (com `hooks.allowConversationAccess: true`, necessário para os hooks de conversa bruta). O avaliador emite um veredicto plano `{permission, reason}` e o shim o mapeia para o formato de retorno nativo de cada hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**) e `before_agent_finalize → {action:"revise", reason}` (**Stop** — uma verdadeira barreira de fim de turno, então os builtins `require-*-before-stop` **aplicam** no OpenClaw, ao contrário do Hermes). Eventos e nomes de ferramentas são canonicalizados no lado do binário via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) para que as políticas integradas disparem sem alterações; o shim falha aberto em qualquer erro de spawn/parse/timeout. OpenClaw é **também** uma fonte de **auditoria** offline — o painel lê suas sessões JSONL em `~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (usuário), `/.factory/hooks.json` (projeto) — Factory não possui escopo `local`. droid inclui um sistema de hook de comando externo no estilo Claude, mas com duas peculiaridades verificadas ao vivo contra droid v0.171.0: (1) os nomes dos eventos ficam no **nível superior** de `hooks.json` — **não há wrapper `"hooks"`** (droid rejeita um); eventos de ferramenta (`PreToolUse`/`PostToolUse`) carregam `"matcher": "*"`, eventos sem ferramenta o omitem. (2) A negação é conduzida pelo **código de saída 2 + stderr** do hook, não por uma decisão JSON — o branch `factory` do avaliador retorna saída 2 para eventos de ferramenta/prompt e `{decision:"block", reason}` apenas no evento de fim de turno `Stop` (o único canal de força de nova tentativa do droid). Os eventos já são PascalCase (sem mapa de eventos) e o payload é snake_case do Claude; apenas nomes de ferramentas são canonicalizados via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory é **também** uma fonte de **auditoria** offline — o painel lê suas sessões JSONL em disco em `~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (usuário), `/.devin/config.json` (projeto) — Devin não possui escopo `local`. Devin é um **clone puro do Claude** verificado ao vivo contra devin v3000.1.27: usa o esquema padrão com wrapper `"hooks"` do Claude (as escritas são de mesclagem preservadora para que outras chaves do arquivo de configuração — `org_id`, `theme_mode`, … — sobrevivam), nomes de eventos já em PascalCase (sem mapa de eventos, sem branch de handler) e um payload de stdin snake_case do Claude (sem normalização). O branch `devin` do avaliador nega com JSON `{"decision":"block","reason"}` no stdout na saída 0 para **todos** os eventos (verificado — o bloqueio substituiu `--permission-mode dangerous`); no evento de fim de turno `Stop`, o motivo carrega o texto de força de nova tentativa MANDATORY-ACTION para que os builtins `require-*-before-stop` sejam aplicados. Apenas nomes de ferramentas são canonicalizados via `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` já é canônico). Devin é **também** uma fonte de **auditoria** offline — o painel lê suas sessões SQLite em `~/.local/share/devin/cli/sessions.db` (cada linha `sessions` carrega um `working_directory` real, então as sessões são agrupadas por cwd do projeto como o Claude). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (usuário), `/.agents/hooks.json` (projeto) — Antigravity não possui escopo `local`. Ao contrário do Factory/Devin, Antigravity tem seu **próprio** contrato (não é um clone do Claude), verificado ao vivo contra agy v1.1.2. `hooks.json` usa um esquema de **hook nomeado**: a chave de nível superior é um *nome* de hook (`"failproofai"`) cujo valor é um mapa de evento→handlers — eventos de ferramenta (`PreToolUse`/`PostToolUse`) envolvem handlers em `{matcher:"*", hooks:[…]}`, enquanto `PreInvocation`/`Stop` são arrays de handler **planos** (outros hooks nomeados são preservados). O payload de stdin é **protojson em camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai o normaliza para snake_case antes das políticas executarem, e mapeia os args PascalCase do `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. O branch `antigravity` do avaliador usa as **próprias** formas de resposta do Antigravity: `{decision:"deny", reason}` bloqueia uma ferramenta/prompt (saída 0), `{decision:"continue", reason}` no evento de fim de turno `Stop` reingressa no loop (então os builtins `require-*-before-stop` são aplicados) e `{injectSteps:[{ephemeralMessage}]}` injeta uma instrução em `PreInvocation` (→ `UserPromptSubmit`). Nomes de ferramentas são canonicalizados via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity é **também** uma fonte de **auditoria** offline — o painel lê suas transcrições JSONL simples em `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (índice de conversas em `conversation_summaries.db`). - - **Goose (codinome goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (usuário), `/.agents/plugins/failproofai/hooks/hooks.json` (projeto) — Goose não possui escopo `local`. A aplicação usa o sistema de **hooks** do Goose, a especificação **Open Plugins** entre agentes: o instalador apenas coloca o diretório do plugin `failproofai` e o Goose o autodescobre na inicialização (registrando-o automaticamente em `~/.config/goose/config.yaml`). O `hooks.json` usa um esquema Open Plugins **com** um wrapper `"hooks"` de nível superior, e o matcher é **omitido** em todos os eventos — um `"*"` simples é uma regex inválida que não corresponde a nada (verificado ao vivo contra goose v1.43.0). Os nomes dos eventos já são PascalCase (sem mapa de eventos); o payload de stdin usa `event`/`working_dir`, que o handler normaliza para `hook_event_name`/`cwd`. O branch `goose` do avaliador nega com JSON `{"decision":"block","reason"}` no stdout na saída 0, honrado **apenas** no evento **`PreToolUse`** (incluído no goose ≥ v1.37.0) — que dispara para a ferramenta shell **e dentro de subagentes delegados**, sendo o único ponto de negação suficiente; qualquer outro erro de hook falha **aberto**. Goose **não possui evento `Stop`**, então os builtins `require-*-before-stop` não se aplicam (como no Hermes). Nomes de ferramentas são canonicalizados via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) e chaves de caminho via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose é **também** uma fonte de **auditoria** offline — o painel lê suas sessões SQLite em `~/.local/share/goose/sessions/sessions.db` (cada linha `sessions` carrega um `working_dir` real, então as sessões são agrupadas por cwd do projeto como o Devin; execuções rápidas com `--no-session` são filtradas). -- **`policies-config.json`** — informa ao failproofai quais políticas avaliar e com quais parâmetros (compartilhado entre todas as CLIs de agentes) - -Passe `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` para selecionar um agente específico (separado por espaços ou repetido para qualquer subconjunto): + - **OpenAI Codex**: `~/.codex/hooks.json` (usuário), `/.codex/hooks.json` (projeto) — Codex não tem escopo `local` + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuário), `/.github/hooks/failproofai.json` (projeto) — Copilot não tem escopo `local`. As entradas de hook usam os campos de comando `bash`/`powershell` com chave de SO do Copilot com `timeoutSec`; o arquivo carrega um marcador de nível superior `version: 1`. O suporte ao Copilot CLI está em **beta** enquanto verificamos o esquema de registro `events.jsonl` (que os documentos públicos não especificam) em relação a mais sessões do mundo real. **O modo de agente do VS Code Copilot Chat (Preview)** lê configurações de hook de `.github/hooks/*.json`, `~/.copilot/hooks/*.json` e `~/.claude/settings.json` (governado pela configuração `chat.hookFilesLocations`) usando o mesmo contrato no formato Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exatamente os caminhos que esta integração `copilot` e a integração `claude` (`~/.claude/settings.json`) já escrevem, portanto `failproofai policies --install --cli copilot` (ou `--cli claude`) **já aplica no modo de agente do VS Code** sem necessidade de uma integração `vscode` separada (confirmado em tempo real pelos logs de descoberta do VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuário), `/.cursor/hooks.json` (projeto) — Cursor não tem escopo `local`. As entradas de hook usam o formato no estilo Claude `{type, command, timeout}` (sem divisão `bash`/`powershell`), mas armazenadas sob chaves de evento em camelCase (`preToolUse`, `beforeSubmitPrompt`, …) em um array plano por [esquema de hooks](https://cursor.com/docs/hooks) do Cursor; o arquivo carrega um marcador de nível superior `version: 1`. O handler canonicaliza camelCase → PascalCase via `CURSOR_EVENT_MAP` para que as políticas integradas existentes disparem sem alterações. O suporte ao Cursor Agent está em **beta** enquanto verificamos o formato de transcrição em disco do Cursor (não especificado nos documentos públicos) em relação a mais instalações do mundo real. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuário), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projeto) — OpenCode não tem escopo `local`. Ao contrário das outras cinco CLIs, OpenCode **não tem sistema de hook de comando externo**: ele carrega plugins JS/TS em processo explicitamente registrados via array `plugin: []` no `opencode.json` (a descoberta automática em `.opencode/plugins/` **não** é como os plugins carregam no opencode v1.14.33). A instalação coloca um pequeno shim de plugin gerado que chama o binário failproofai em subprocesso e traduz a resposta JSON no formato Claude de volta para a semântica de plugin: `throw new Error()` para negação de evento de ferramenta (cancela a chamada de ferramenta), `client.session.prompt(...)` para instruct E para negação de `Stop` / `SubagentStop` (submete o motivo da negação como a próxima mensagem do usuário — o único canal de força de nova tentativa, já que `session.idle` é apenas notificação e lançar uma exceção dele não tem efeito), e no-op para allow. O shim canonicaliza tanto os nomes de ferramentas (minúsculas → PascalCase via `OPENCODE_TOOL_MAP`) quanto as chaves de argumento de entrada de ferramenta (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, por exemplo `filePath` → `file_path`, `oldString` → `old_string`) antes de encaminhar ao binário, para que os integrados de verificação de caminho como `block-read-outside-cwd`, `block-env-files` e `block-secrets-write` disparem sem alterações nas chamadas de ferramenta do OpenCode. As sessões vivem no banco de dados SQLite do opencode em `~/.local/share/opencode/opencode.db`; o visualizador de sessões do painel as lê via `opencode db --format json` e `opencode export `. O suporte ao OpenCode está em **beta** enquanto verificamos o comportamento entre versões e em relação a mais sessões do mundo real. Consulte os [documentos de plugins do OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuário), `/.pi/settings.json` (projeto) — Pi não tem escopo `local`. O Pi carrega pacotes de extensão TypeScript na inicialização; o arquivo de configurações é um array plano de strings `{"packages": ["./relative/path", …]}`. failproofai escreve uma única entrada no array de pacotes apontando para seu diretório `pi-extension/` empacotado. A extensão internamente assina os eventos `tool_call` / `user_bash` / `input` / `session_start` do Pi e chama `failproofai --hook --cli pi`; o handler canonicaliza underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` para que as políticas integradas existentes disparem sem alterações. Os argumentos de entrada de ferramenta também são canonicalizados via `PI_TOOL_INPUT_MAP` (Read / Write / Edit do Pi entregam `path` em vez de `file_path`; mapear a chave de nível superior permite que `block-env-files` e `block-secrets-write` disparem — `block-read-outside-cwd` já tinha um fallback para `path`). O suporte ao Pi está em **beta** enquanto a API de extensão do Pi e o layout do log de sessão se estabilizam. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**somente escopo de usuário** — Hermes não tem configuração de projeto/local). Hermes é um **gateway** Slack/Telegram, portanto uma instalação intercepta chamadas de ferramenta de todas as plataformas (Slack/Telegram/cli/cron) **e** subagentes internos. As entradas de hook são um par `{command, timeout}` (timeout em **segundos**) sob um mapa `hooks:` com chave pelos eventos snake_case do Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); o handler canonicaliza eventos via `HERMES_EVENT_MAP` e nomes de ferramentas via `HERMES_TOOL_MAP` para que as políticas integradas disparem sem alterações. A configuração é editada por meio de um round-trip YAML `Document` que preserva comentários para que as outras configurações do operador sobrevivam, e a instalação define `hooks_auto_accept: true` para que o gateway headless (sem TTY) execute os hooks sem uma solicitação de consentimento. O avaliador emite o contrato stdout `{"decision":"block","reason"}` do Hermes (Hermes ignora códigos de saída). **Limitações:** Hermes não tem evento `Stop` de fim de turno, portanto os integrados `require-*-before-stop` nunca disparam para ele (inaplicável, não quebrado); `instruct` é degradado para allow-com-nota-registrada (sem canal de contexto adicional); e a redação de segredos de saída (`sanitize-*`) não pode reescrever a saída de ferramenta pelo contrato de hook de shell. Hermes também é uma fonte de **auditoria** offline — o painel lê suas sessões de gateway diretamente de `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**somente escopo de usuário** — OpenClaw não tem configuração de projeto/local). Como o Hermes, OpenClaw é um **gateway** multi-canal auto-hospedado, portanto uma instalação intercepta chamadas de ferramenta de todos os canais e seus subagentes internos. A aplicação ocorre por meio dos **hooks de plugin em processo** do OpenClaw (seus hooks internos baseados em arquivo são apenas de observação e não podem bloquear), portanto — como OpenCode/Pi — failproofai inclui um pacote `openclaw-plugin/` estático que gera o binário failproofai de forma assíncrona e traduz o veredicto. A instalação registra o diretório de plugin incluído em `plugins.load.paths[]` do `openclaw.json` e o habilita em `plugins.entries.failproofai` (com `hooks.allowConversationAccess: true`, necessário para os hooks de conversa bruta). O avaliador emite um veredicto plano `{permission, reason}` e o shim o mapeia para o formato de retorno nativo de cada hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**) e `before_agent_finalize → {action:"revise", reason}` (**Stop** — um portão real de fim de turno, portanto os integrados `require-*-before-stop` **aplicam** no OpenClaw, ao contrário do Hermes). Eventos e nomes de ferramentas são canonicalizados do lado do binário via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) para que as políticas integradas disparem sem alterações; o shim falha aberto em qualquer erro de spawn/parse/timeout. OpenClaw também é uma fonte de **auditoria** offline — o painel lê suas sessões JSONL em `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (usuário), `/.factory/hooks.json` (projeto) — Factory não tem escopo `local`. O droid inclui um sistema de hook de comando externo no estilo Claude, mas com duas peculiaridades verificadas em tempo real contra o droid v0.171.0: (1) os nomes de eventos ficam no **nível superior** do `hooks.json` — **não há wrapper `"hooks"`** (droid rejeita um); eventos de ferramenta (`PreToolUse`/`PostToolUse`) carregam `"matcher": "*"`, eventos não-ferramenta o omitem. (2) A negação é conduzida pelo **código de saída 2 + stderr** do hook, não por uma decisão JSON — o branch `factory` do avaliador retorna saída 2 para eventos de ferramenta/prompt e `{decision:"block", reason}` apenas no evento de fim de turno `Stop` (único canal de força de nova tentativa do droid). Os eventos já estão em PascalCase (sem mapa de eventos) e o payload está em snake_case Claude; apenas os nomes de ferramentas são canonicalizados via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory também é uma fonte de **auditoria** offline — o painel lê suas sessões JSONL em disco em `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (usuário), `/.devin/config.json` (projeto) — Devin não tem escopo `local`. Devin é um **clone puro do Claude** verificado em tempo real contra o devin v3000.1.27: usa o esquema padrão com wrapper `"hooks"` do Claude (as escritas preservam a mesclagem para que outras chaves do arquivo de configuração — `org_id`, `theme_mode`, … — sobrevivam), nomes de eventos já em PascalCase (sem mapa de eventos, sem branch de handler) e um payload stdin em snake_case Claude (sem normalização). O branch `devin` do avaliador nega com JSON `{"decision":"block","reason"}` no stdout na saída 0 para **todos** os eventos (verificado — o bloco sobrepôs `--permission-mode dangerous`); no evento de fim de turno `Stop`, o motivo carrega o texto de força de nova tentativa MANDATORY-ACTION para que os integrados `require-*-before-stop` apliquem. Apenas os nomes de ferramentas são canonicalizados via `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` já é canônico). Devin também é uma fonte de **auditoria** offline — o painel lê suas sessões SQLite em `~/.local/share/devin/cli/sessions.db` (cada linha `sessions` carrega um `working_directory` real, portanto as sessões se agrupam por cwd de projeto como Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (usuário), `/.agents/hooks.json` (projeto) — Antigravity não tem escopo `local`. Ao contrário de Factory/Devin, Antigravity tem seu **próprio** contrato (não é um clone do Claude), verificado em tempo real contra o agy v1.1.2. `hooks.json` usa um esquema de **hook nomeado**: a chave de nível superior é um *nome* de hook (`"failproofai"`) cujo valor é um mapa de evento→handlers — eventos de ferramenta (`PreToolUse`/`PostToolUse`) envolvem handlers em `{matcher:"*", hooks:[…]}`, enquanto `PreInvocation`/`Stop` são arrays de handler **planos** (outros hooks nomeados são preservados). O payload stdin está em **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai o normaliza para snake_case antes de as políticas serem executadas, e mapeia os argumentos PascalCase de `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. O branch `antigravity` do avaliador usa os **próprios** formatos de resposta do Antigravity: `{decision:"deny", reason}` bloqueia uma ferramenta/prompt (saída 0), `{decision:"continue", reason}` no evento de fim de turno `Stop` reinicia o loop (para que os integrados `require-*-before-stop` apliquem) e `{injectSteps:[{ephemeralMessage}]}` injeta uma instrução em `PreInvocation` (→ `UserPromptSubmit`). Os nomes de ferramentas são canonicalizados via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity também é uma fonte de **auditoria** offline — o painel lê suas transcrições JSONL simples em `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (índice de conversação em `conversation_summaries.db`). + - **Goose (codinome goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (usuário), `/.agents/plugins/failproofai/hooks/hooks.json` (projeto) — Goose não tem escopo `local`. A aplicação usa o sistema de **hooks** do Goose, a especificação **Open Plugins** cross-agent: o instalador apenas coloca o diretório de plugin `failproofai` e o Goose o descobre automaticamente na inicialização (auto-registrando-o em `~/.config/goose/config.yaml`). O `hooks.json` usa um esquema Open Plugins **com** wrapper `"hooks"` de nível superior, e o matcher é **omitido** em todos os eventos — um `"*"` simples é uma regex inválida que não corresponde a nada (verificado em tempo real contra o goose v1.43.0). Os nomes de eventos já estão em PascalCase (sem mapa de eventos); o payload stdin usa `event`/`working_dir`, que o handler normaliza para `hook_event_name`/`cwd`. O branch `goose` do avaliador nega com JSON `{"decision":"block","reason"}` no stdout na saída 0, honrado **apenas** no evento **`PreToolUse`** (incluído no goose ≥ v1.37.0) — que dispara para a ferramenta shell **e dentro de subagentes delegados**, portanto é o único ponto de negação suficiente; qualquer outro erro de hook falha **aberto**. Goose **não tem evento `Stop`**, portanto os integrados `require-*-before-stop` não se aplicam (como com Hermes). Os nomes de ferramentas são canonicalizados via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) e as chaves de caminho via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose também é uma fonte de **auditoria** offline — o painel lê suas sessões SQLite em `~/.local/share/goose/sessions/sessions.db` (cada linha `sessions` carrega um `working_dir` real, portanto as sessões se agrupam por cwd de projeto como Devin; execuções rápidas `--no-session` são filtradas). +- **`policies-config.json`** — instrui failproofai sobre quais políticas avaliar e com quais parâmetros (compartilhado entre todas as CLIs de agente) + +Passe `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` para direcionar um agente específico (separado por espaço ou repetido para qualquer subconjunto): ```bash failproofai policies --install --cli codex --scope project @@ -233,20 +242,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Quando `--cli` é omitido, `failproofai` detecta quais CLIs de agentes estão instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +Quando `--cli` é omitido, `failproofai` detecta quais CLIs de agente estão instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): - **Uma CLI detectada** — seleciona automaticamente essa CLI sem solicitar confirmação. -- **Múltiplas CLIs detectadas** em um terminal interativo — exibe um prompt de seleção única com teclas de seta agrupado em uma seção `Detected (N)` (com uma linha agregada `Install for all N detected` + cada CLI detectada individualmente) e uma seção `Not installed (M) · install hooks ahead of time` listando cada CLI suportada não detectada como opção de instalação antecipada (↑↓ para mover, Enter para selecionar, ^C para sair). O fluxo de desinstalação exibe apenas a seção Detected. +- **Múltiplas CLIs detectadas** em um terminal interativo — exibe um prompt de seleção única por teclas de seta agrupado em uma seção `Detected (N)` (com uma linha agregada `Install for all N detected` + cada CLI detectada individualmente) e uma seção `Not installed (M) · install hooks ahead of time` listando todas as CLIs suportadas não detectadas como opção de instalação antecipada (↑↓ para mover, Enter para selecionar, ^C para sair). O fluxo de desinstalação mostra apenas a seção Detected. - **Múltiplas CLIs detectadas** em uma execução não interativa (CI, sem TTY) — instala para todas as CLIs detectadas sem solicitar confirmação. -- **Nenhuma detectada** — usa `claude` como fallback, com um aviso de que nenhum binário de agente foi encontrado no PATH; o comando de hook ainda é escrito para ser ativado assim que você instalar um. +- **Nenhuma detectada** — recai para `claude`, com um aviso de que nenhum binário de agente foi encontrado no PATH; o comando de hook ainda é escrito para ativar assim que você instalar um. Você pode editar `policies-config.json` diretamente a qualquer momento; as alterações entram em vigor imediatamente no próximo evento de hook sem necessidade de reinicialização. +## Atualizações mantêm sua configuração + +Uma nova versão do failproofai pode organizar `~/.failproofai/` de forma diferente. Quando isso acontece, o primeiro comando após a atualização migra o diretório e **sua configuração é mantida, não redefinida**: + +| Mantido | Reconstruído | +|---|---| +| Sua seleção de políticas e parâmetros (`policies-config.json`) | O cache de auditoria | +| Suas configurações, incluindo `daemon.configured` e caminhos de captura extras (`config.json`) | Implantações de políticas gerenciadas na nuvem — rebuscadas e verificadas por digest no próximo poll | +| Seu registro na nuvem (`credentials.json`) | Estado temporário do daemon | +| Seus próprios arquivos de política em `policies/` e os auxiliares que eles importam | | +| O log de decisões que o painel lê e os eventos ainda não entregues | | + +Chaves escritas por uma versão *mais nova* do failproofai também são preservadas, em vez de serem descartadas por uma versão mais antiga — portanto, alternar entre versões não descarta configurações silenciosamente em nenhuma direção. + +Você **não** precisa executar a configuração novamente depois: uma máquina migrada aplica exatamente como antes, o que é o que torna uma atualização segura em máquinas sem ninguém presente. Cada migração é registrada em `~/.failproofai/migrations/applied.json`, e os arquivos insubstituíveis são copiados para `~/.failproofai/migrations/backup-layout/` antes de qualquer coisa ser executada. + +Consulte [`failproofai update`](/pt-br/cli/update) para a atualização em uma linha e [`failproofai migrate`](/pt-br/cli/migrate) — incluindo `--dry-run` — para os detalhes. + --- ## Exemplo: configuração no nível do projeto com padrões da equipe -Faça commit de `.failproofai/policies-config.json` no seu repositório: +Faça o commit de `.failproofai/policies-config.json` no seu repositório: ```json { diff --git a/docs/pt-br/custom-policies.mdx b/docs/pt-br/custom-policies.mdx index a18d9400..c831e0d2 100644 --- a/docs/pt-br/custom-policies.mdx +++ b/docs/pt-br/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: Políticas Personalizadas -description: "Escreva suas próprias políticas em JavaScript - aplique convenções, previna desvios, detecte falhas e integre com sistemas externos" +description: "Escreva suas próprias políticas em JavaScript - aplique convenções, evite desvios, detecte falhas e integre com sistemas externos" icon: code --- -As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplicar convenções do projeto, prevenir desvios, bloquear operações destrutivas, detectar agentes travados ou integrar com Slack, fluxos de aprovação e muito mais. Elas utilizam o mesmo sistema de eventos de hook e as decisões `allow`, `deny`, `instruct` das políticas embutidas. +As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplicar convenções do projeto, evitar desvios, bloquear operações destrutivas, detectar agentes travados ou integrar com Slack, fluxos de aprovação e muito mais. Elas utilizam o mesmo sistema de eventos de hook e as mesmas decisões `allow`, `deny`, `instruct` das políticas integradas. --- @@ -29,7 +29,7 @@ customPolicies.add({ }); ``` -Instale: +Instale com: ```bash failproofai policies --install --custom ./my-policies.js @@ -39,12 +39,12 @@ failproofai policies --install --custom ./my-policies.js ## Duas formas de carregar políticas personalizadas -### Opção 1: Baseada em convenção (recomendada) +### Opção 1: Por convenção (recomendado) -Coloque arquivos `*policies.{js,mjs,ts}` na pasta `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como git hooks: adicione o arquivo e pronto. +Coloque arquivos `*policies.{js,mjs,ts}` dentro de `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como git hooks: basta adicionar o arquivo e pronto. ``` -# Nível de projeto — commitado no git, compartilhado com o time +# Nível de projeto — commitado no git, compartilhado com a equipe .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -53,14 +53,14 @@ Coloque arquivos `*policies.{js,mjs,ts}` na pasta `.failproofai/policies/` e ele ``` **Como funciona:** -- Os diretórios de projeto e de usuário são escaneados juntos (união — não é primeiro-escopo-vence) -- Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use o prefixo `01-`, `02-` para controlar a ordem -- Somente arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados; outros arquivos são ignorados +- Os diretórios do projeto e do usuário são escaneados (união — não vence o primeiro escopo) +- Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use prefixos `01-`, `02-` para controlar a ordem +- Apenas arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados; outros arquivos são ignorados - Cada arquivo é carregado de forma independente (fail-open por arquivo) -- Funciona junto com `--custom` explícito e políticas embutidas +- Funciona junto com `--custom` explícito e políticas integradas -As políticas por convenção são a forma mais fácil de construir um padrão de qualidade para sua organização. Faça commit de `.failproofai/policies/` no git e todos os membros do time receberão as mesmas regras automaticamente — sem configuração individual. À medida que o time identifica novos modos de falha, adicione uma política e faça push. Com o tempo, elas se tornam um padrão de qualidade vivo que melhora a cada contribuição. +Políticas por convenção são a forma mais fácil de construir um padrão de qualidade para sua organização. Faça commit de `.failproofai/policies/` no git e todos os membros da equipe receberão as mesmas regras automaticamente — sem configuração por desenvolvedor. À medida que sua equipe descobre novos modos de falha, adicione uma política e faça push. Com o tempo, elas se tornam um padrão de qualidade vivo que melhora a cada contribuição. ### Opção 2: Caminho de arquivo explícito @@ -79,15 +79,15 @@ failproofai policies --install --custom ./security.js --custom ./workflow.js failproofai policies --uninstall --custom ``` -Os caminhos absolutos resolvidos são armazenados em `policies-config.json` como `customPoliciesPaths`. Repita `--custom` para configurar múltiplos arquivos. Configurações existentes que usam o campo legado `customPoliciesPath` continuam funcionando. Os arquivos são carregados frescos a cada evento de hook — não há cache entre eventos. +Os caminhos absolutos resolvidos são armazenados em `policies-config.json` como `customPoliciesPaths`. Repita `--custom` para configurar múltiplos arquivos. Configurações existentes que usam o campo legado `customPoliciesPath` continuam funcionando. Os arquivos são carregados novamente a cada evento de hook — não há cache entre eventos. -Cada política registrada aparece com seu próprio toggle no dashboard. Desativar uma política registra seu ID qualificado por fonte em `disabledCustomPolicies`; o arquivo e suas outras políticas continuam sendo carregados, enquanto a política desativada é excluída antes da correspondência de eventos. Nomes de políticas duplicados entre arquivos têm toggles independentes. +Cada política registrada aparece com seu próprio toggle no painel. Desativar uma política registra seu ID qualificado por fonte em `disabledCustomPolicies`; o arquivo e suas outras políticas continuam sendo carregados, enquanto a política desativada é excluída antes da correspondência de eventos. Nomes de políticas duplicados entre arquivos têm toggles independentes. -### Usando as duas formas juntas +### Usando ambas juntas -As políticas por convenção e os arquivos `--custom` explícitos podem coexistir. Ordem de carregamento: +Políticas por convenção e arquivos `--custom` explícitos podem coexistir. Ordem de carregamento: -1. Arquivos `customPoliciesPaths` explícitos (na ordem configurada) +1. Arquivos explícitos de `customPoliciesPaths` (na ordem configurada) 2. Arquivos de convenção do projeto (`{cwd}/.failproofai/policies/`, em ordem alfabética) 3. Arquivos de convenção do usuário (`~/.failproofai/policies/`, em ordem alfabética) @@ -95,7 +95,7 @@ As políticas por convenção e os arquivos `--custom` explícitos podem coexist ## API -### Import +### Importação ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -103,44 +103,44 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registra uma política. Chame quantas vezes forem necessárias para múltiplas políticas no mesmo arquivo. +Registra uma política. Chame quantas vezes precisar para múltiplas políticas no mesmo arquivo. ```ts customPolicies.add({ name: string; // obrigatório - identificador único description?: string; // exibido na saída de `failproofai policies` - match?: { events?: HookEventType[] }; // filtra por tipo de evento; omita para corresponder a todos + match?: { events?: HookEventType[] }; // filtrar por tipo de evento; omitir para corresponder a todos fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Helpers de decisão +### Funções auxiliares de decisão -| Função | Efeito | Quando usar | -|--------|--------|-------------| -| `allow()` | Permite a operação silenciosamente | A ação é segura, nenhuma mensagem é necessária | -| `deny(message)` | Bloqueia a operação | O agente não deve executar esta ação | +| Função | Efeito | Use quando | +|----------|--------|----------| +| `allow()` | Permite a operação silenciosamente | A ação é segura, sem mensagem necessária | +| `deny(message)` | Bloqueia a operação | O agente não deve realizar esta ação | | `instruct(message)` | Adiciona contexto sem bloquear | Fornece contexto extra ao agente para mantê-lo no caminho certo | -`deny(message)` - a mensagem aparece para Claude com o prefixo `"Blocked by failproofai:"`. Um único `deny` interrompe toda avaliação subsequente. +`deny(message)` — a mensagem aparece para o Claude com o prefixo `"Blocked by failproofai:"`. Um único `deny` interrompe toda avaliação subsequente. -`instruct(message)` - a mensagem é adicionada ao contexto de Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas. +`instruct(message)` — a mensagem é adicionada ao contexto do Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas. -Você pode acrescentar orientações extras a qualquer mensagem de `deny` ou `instruct` adicionando um campo `hint` em `policyParams` — sem necessidade de alterar o código. Isso funciona para políticas personalizadas (`custom/`), políticas de convenção de projeto (`.failproofai-project/`) e políticas de convenção de usuário (`.failproofai-user/`) também. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes. +Você pode adicionar orientações extras a qualquer mensagem `deny` ou `instruct` incluindo um campo `hint` em `policyParams` — sem necessidade de alterar o código. Isso funciona para políticas personalizadas (`custom/`), de convenção de projeto (`.failproofai-project/`) e de convenção de usuário (`.failproofai-user/`) também. Consulte [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para mais detalhes. ### Mensagens informativas de allow -`allow(message)` permite a operação **e** envia uma mensagem informativa de volta para Claude. A mensagem é entregue como `additionalContext` na resposta stdout do handler de hook — o mesmo mecanismo usado por `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso. +`allow(message)` permite a operação **e** envia uma mensagem informativa de volta ao Claude. A mensagem é entregue como `additionalContext` na resposta stdout do handler de hook — o mesmo mecanismo usado pelo `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso. -| Função | Efeito | Quando usar | -|--------|--------|-------------| -| `allow(message)` | Permite e envia contexto para Claude | Confirmar que uma verificação passou, ou explicar por que foi ignorada | +| Função | Efeito | Use quando | +|----------|--------|----------| +| `allow(message)` | Permite e envia contexto ao Claude | Confirmar que uma verificação passou, ou explicar por que uma verificação foi ignorada | Casos de uso: -- **Confirmações de status:** `allow("All CI checks passed.")` — informa a Claude que tudo está em ordem -- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa a Claude por que uma verificação foi pulada para que ela tenha contexto completo +- **Confirmações de status:** `allow("All CI checks passed.")` — informa ao Claude que tudo está verde +- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa ao Claude por que uma verificação foi ignorada para que ele tenha contexto completo - **Múltiplas mensagens se acumulam:** se várias políticas retornarem `allow(message)`, todas as mensagens são unidas com quebras de linha e entregues juntas ```js @@ -160,31 +160,31 @@ customPolicies.add({ }); ``` -### Campos de `PolicyContext` +### Campos do `PolicyContext` | Campo | Tipo | Descrição | -|-------|------|-----------| +|-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | A ferramenta sendo chamada (ex.: `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Os parâmetros de entrada da ferramenta | -| `payload` | `Record` | Payload bruto completo do evento do Claude Code | +| `payload` | `Record` | Payload completo do evento bruto do Claude Code | | `session` | `SessionMetadata \| undefined` | Contexto da sessão (veja abaixo) | -### Campos de `SessionMetadata` +### Campos do `SessionMetadata` | Campo | Tipo | Descrição | -|-------|------|-----------| +|-------|------|-------------| | `sessionId` | `string` | Identificador da sessão do Claude Code | | `cwd` | `string` | Diretório de trabalho da sessão do Claude Code | | `transcriptPath` | `string` | Caminho para o arquivo de transcrição JSONL da sessão | -### Tipos de evento +### Tipos de eventos -| Evento | Quando dispara | Conteúdo de `toolInput` | -|--------|---------------|------------------------| -| `PreToolUse` | Antes de Claude executar uma ferramenta | A entrada da ferramenta (ex.: `{ command: "..." }` para Bash) | -| `PostToolUse` | Após uma ferramenta ser concluída | A entrada da ferramenta + `tool_result` (a saída) | -| `Notification` | Quando Claude envia uma notificação | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks devem sempre retornar `allow()`, não podem bloquear notificações | +| Evento | Quando é disparado | Conteúdo de `toolInput` | +|-------|--------------|----------------------| +| `PreToolUse` | Antes do Claude executar uma ferramenta | A entrada da ferramenta (ex.: `{ command: "..." }` para Bash) | +| `PostToolUse` | Após uma ferramenta concluir | A entrada da ferramenta + `tool_result` (a saída) | +| `Notification` | Quando o Claude envia uma notificação | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks sempre devem retornar `allow()`, não podem bloquear notificações | | `Stop` | Quando a sessão do Claude termina | Vazio | --- @@ -193,10 +193,10 @@ customPolicies.add({ As políticas são avaliadas nesta ordem: -1. Políticas embutidas (na ordem de definição) +1. Políticas integradas (na ordem de definição) 2. Políticas personalizadas explícitas de `customPoliciesPath` (na ordem de `.add()`) -3. Políticas de convenção do projeto em `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada um) -4. Políticas de convenção do usuário em `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada um) +3. Políticas de convenção do projeto em `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo) +4. Políticas de convenção do usuário em `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo) O primeiro `deny` interrompe todas as políticas subsequentes. Todas as mensagens `instruct` são acumuladas e entregues juntas. @@ -204,9 +204,9 @@ O primeiro `deny` interrompe todas as políticas subsequentes. Todas as mensagen --- -## Imports transitivos +## Importações transitivas -Arquivos de política personalizados podem importar módulos locais usando caminhos relativos: +Arquivos de políticas personalizadas podem importar módulos locais usando caminhos relativos: ```js // my-policies.js @@ -223,7 +223,7 @@ customPolicies.add({ }); ``` -Todos os imports relativos acessíveis a partir do arquivo de entrada são resolvidos. Isso é implementado reescrevendo os imports `from "failproofai"` para o caminho real do dist e criando arquivos `.mjs` temporários para garantir compatibilidade com ESM. +Todas as importações relativas acessíveis a partir do arquivo de entrada são resolvidas. Isso é implementado reescrevendo as importações `from "failproofai"` para o caminho real de dist e criando arquivos `.mjs` temporários para garantir compatibilidade com ESM. --- @@ -236,7 +236,7 @@ customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Só dispara quando a sessão termina + // Disparado apenas quando a sessão termina // ctx.session.transcriptPath contém o log completo da sessão return allow(); }, @@ -249,15 +249,15 @@ Omita `match` completamente para disparar em todos os tipos de evento. ## Tratamento de erros e modos de falha -As políticas personalizadas são **fail-open**: erros nunca bloqueiam as políticas embutidas nem travam o handler de hook. +Políticas personalizadas são **fail-open**: erros nunca bloqueiam políticas integradas nem travam o handler de hook. | Falha | Comportamento | -|-------|---------------| -| `customPoliciesPath` não definido | Nenhuma política personalizada explícita é executada; políticas de convenção e embutidas continuam normalmente | -| Arquivo não encontrado | Aviso registrado em `~/.failproofai/hook.log`; embutidas continuam | -| Erro de sintaxe/import (explícito) | Erro registrado em `~/.failproofai/hook.log`; políticas personalizadas explícitas ignoradas | -| Erro de sintaxe/import (convenção) | Erro registrado; aquele arquivo é ignorado, outros arquivos de convenção ainda são carregados | -| `fn` lança exceção em tempo de execução | Erro registrado; aquele hook tratado como `allow`; outros hooks continuam | +|---------|----------| +| `customPoliciesPath` não definido | Nenhuma política personalizada explícita é executada; políticas de convenção e integradas continuam normalmente | +| Arquivo não encontrado | Aviso registrado em `~/.failproofai/hook.log`; políticas integradas continuam | +| Erro de sintaxe/importação (explícito) | Erro registrado em `~/.failproofai/hook.log`; políticas personalizadas explícitas ignoradas | +| Erro de sintaxe/importação (convenção) | Erro registrado; aquele arquivo é ignorado, outros arquivos de convenção ainda são carregados | +| `fn` lança exceção em tempo de execução | Erro registrado; aquele hook é tratado como `allow`; outros hooks continuam | | `fn` demora mais de 10s | Timeout registrado; tratado como `allow` | | Diretório de convenção ausente | Nenhuma política de convenção é executada; sem erro | @@ -328,16 +328,16 @@ export { customPolicies }; ## Exemplos -O diretório `examples/` contém arquivos de política prontos para uso: +O diretório `examples/` contém arquivos de políticas prontos para uso: | Arquivo | Conteúdo | -|---------|----------| -| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos de falha comuns de agentes | -| `examples/policies-advanced/index.js` | Padrões avançados: imports transitivos, chamadas assíncronas, limpeza de saída e hooks de fim de sessão | -| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloqueio de escrita em .env, prevenção de reescrita de histórico git) | -| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho baseadas em convenção (lembretes de testes, auditoria de escrita em arquivos) | +|------|----------| +| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos comuns de falha de agentes | +| `examples/policies-advanced/index.js` | Padrões avançados: importações transitivas, chamadas assíncronas, limpeza de saída e hooks de fim de sessão | +| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloquear escrita em .env, evitar reescrita do histórico do git) | +| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho baseadas em convenção (lembretes de testes, auditoria de escrita de arquivos) | -### Usando exemplos de arquivo explícito +### Usando exemplos com arquivo explícito ```bash failproofai policies --install --custom ./examples/policies-basic.js diff --git a/docs/pt-br/dashboard.mdx b/docs/pt-br/dashboard.mdx index 25d8ad74..e5a56dc0 100644 --- a/docs/pt-br/dashboard.mdx +++ b/docs/pt-br/dashboard.mdx @@ -24,14 +24,14 @@ O dashboard lê dados locais de projeto, sessão e configuração do failproofai ### Projetos -Lista todos os projetos de Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity e Goose encontrados na sua máquina. Projetos Claude são descobertos em `~/.claude/projects/` (ou no caminho definido por `CLAUDE_PROJECTS_PATH`); projetos Codex são descobertos escaneando todas as transcrições em `~/.codex/sessions///
/*.jsonl` e agrupando pelo `cwd` registrado no primeiro registro de cada sessão; projetos Copilot CLI são descobertos escaneando cada `~/.copilot/session-state//workspace.yaml` (configurável via `COPILOT_HOME`) e agrupando pelo campo `cwd`; projetos Cursor Agent são descobertos escaneando metadados por sessão em `~/.cursor/agent-sessions//` (configurável via `CURSOR_HOME`, com `conversations/` e `sessions/` como fallbacks) buscando um escalar `cwd` em `meta.json` / `session.json` / `workspace.yaml`; projetos OpenCode são descobertos consultando seu banco SQLite em `~/.local/share/opencode/opencode.db` via `opencode db --format json` (lemos as tabelas `session` e `project` e agrupamos por `project_id`); projetos Pi são descobertos escaneando transcrições JSONL por sessão em `~/.pi/agent/sessions//_.jsonl` (configurável via `PI_SESSIONS_DIR`) e obtendo o `cwd` do primeiro registro de cada sessão; sessões do gateway Hermes são lidas diretamente do armazenamento SQLite de cada perfil — `~/.hermes/state.db` mais `~/.hermes/profiles//state.db` (substituível via `HERMES_HOME`, ou `HERMES_DB_PATH` para um único banco) — e agrupadas em projetos `hermes--` por perfil e `source` (Slack/Telegram/cli/cron — sessões de gateway não têm cwd); sessões do gateway OpenClaw são lidas de `~/.openclaw/agents//sessions/*.jsonl` e agrupadas em projetos `openclaw--` por agente e canal (também sem cwd); projetos Factory Droid são descobertos a partir das transcrições JSONL em `~/.factory/sessions//*.jsonl` e agrupados por cwd; projetos Devin a partir de seu banco SQLite em `~/.local/share/devin/cli/sessions.db` (agrupados pelo `working_directory` de cada sessão); projetos Antigravity a partir das transcrições JSONL em `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` e agrupados por cwd; e projetos Goose a partir de seu banco SQLite em `~/.local/share/goose/sessions/sessions.db` (agrupados pelo `working_dir` de cada sessão). Um projeto que foi utilizado por múltiplos CLIs aparece como uma única linha com todos os badges correspondentes. Use o menu suspenso **CLI** acima da tabela para filtrar por um agente CLI específico; a URL preserva sua seleção como `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Lista todos os projetos Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity e Goose encontrados em sua máquina. Projetos Claude são descobertos em `~/.claude/projects/` (ou no caminho definido por `CLAUDE_PROJECTS_PATH`); projetos Codex são descobertos escaneando todas as transcrições em `~/.codex/sessions///
/*.jsonl` e agrupando pelo `cwd` registrado no primeiro registro de cada sessão; projetos Copilot CLI são descobertos escaneando cada `~/.copilot/session-state//workspace.yaml` (configurável via `COPILOT_HOME`) e agrupando pelo campo `cwd`; projetos Cursor Agent são descobertos escaneando metadados por sessão em `~/.cursor/agent-sessions//` (configurável via `CURSOR_HOME`, com `conversations/` e `sessions/` como alternativas) para um escalar `cwd` em `meta.json` / `session.json` / `workspace.yaml`; projetos OpenCode são descobertos consultando seu banco SQLite em `~/.local/share/opencode/opencode.db` via `opencode db --format json` (lemos as tabelas `session` e `project` e agrupamos por `project_id`); projetos Pi são descobertos escaneando transcrições JSONL por sessão em `~/.pi/agent/sessions//_.jsonl` (configurável via `PI_SESSIONS_DIR`) e extraindo o `cwd` do primeiro registro de cada sessão; sessões do gateway Hermes são lidas diretamente do armazenamento SQLite de cada perfil — `~/.hermes/state.db` mais `~/.hermes/profiles//state.db` (substituível via `HERMES_HOME`, ou `HERMES_DB_PATH` para um único banco) — e agrupadas em projetos `hermes--` por perfil e `source` (Slack/Telegram/cli/cron — sessões de gateway não têm cwd); sessões do gateway OpenClaw são lidas de `~/.openclaw/agents//sessions/*.jsonl` e agrupadas em projetos `openclaw--` por agente e canal (também sem cwd); projetos Factory Droid são descobertos a partir das transcrições JSONL em `~/.factory/sessions//*.jsonl` e agrupados por cwd; projetos Devin a partir de seu banco SQLite em `~/.local/share/devin/cli/sessions.db` (agrupado pelo `working_directory` de cada sessão); projetos Antigravity a partir das transcrições JSONL em `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` e agrupados por cwd; e projetos Goose a partir de seu banco SQLite em `~/.local/share/goose/sessions/sessions.db` (agrupado pelo `working_dir` de cada sessão). Um projeto utilizado por múltiplas CLIs é exibido como uma única linha com todos os badges correspondentes. Use o dropdown **CLI** acima da tabela para filtrar por um agente CLI específico; a URL preserva sua seleção como `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -Hermes e OpenClaw são de escopo de usuário e não possuem diretório de trabalho para agrupamento, portanto são exibidos como uma **árvore de pastas recolhível** — perfil (ou agente) no nível superior, com seus canais abaixo — enquanto todos os CLIs baseados em cwd permanecem como linhas planas. Linhas de pasta consolidam a contagem de sessões e a atividade mais recente de tudo abaixo delas, pastas recolhidas são lembradas entre visitas, e uma busca por palavra-chave expande o que corresponder. +Hermes e OpenClaw são escopados por usuário e não possuem diretório de trabalho para agrupar, então são renderizados como uma **árvore de pastas recolhível** — perfil (ou agente) no nível superior, seus canais abaixo — enquanto toda CLI baseada em cwd permanece como uma linha simples. Linhas de pasta consolidam a contagem de sessões e a atividade mais recente de tudo abaixo delas, pastas recolhidas são lembradas entre visitas, e uma busca por palavra-chave expande o que corresponder. Cada projeto exibe: - Nome do projeto (derivado do caminho da pasta) - Um badge de CLI — `Claude Code` (laranja), `OpenAI Codex` (roxo), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (âmbar), `Pi` (rosa) e/ou `Hermes` (índigo) -- Data da atividade mais recente da sessão +- Data da atividade de sessão mais recente Clique em um projeto para ver suas sessões. @@ -49,44 +49,44 @@ Clique em uma sessão para abrir o visualizador de sessão. ### Visualizador de sessão -O visualizador de sessão responde à pergunta central sobre agentes autônomos: o que o agente fez e ele se manteve no caminho certo? Um badge de CLI ao lado do cabeçalho indica se a sessão é uma transcrição de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ou Goose. Ele exibe uma linha do tempo de tudo o que aconteceu em uma sessão: +O visualizador de sessão responde à pergunta principal sobre agentes autônomos: o que o agente fez, e ele se manteve no caminho certo? Um badge de CLI ao lado do cabeçalho indica se a sessão é uma transcrição de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ou Goose. Ele exibe uma linha do tempo de tudo que aconteceu em uma sessão: - **Mensagens** - Respostas de texto do Claude e prompts do usuário -- **Chamadas de ferramentas** - Cada ferramenta invocada pelo Claude, com sua entrada e saída +- **Chamadas de ferramentas** - Cada ferramenta que o Claude invocou, com sua entrada e saída - **Atividade de políticas** - Para cada chamada de ferramenta, quais políticas foram acionadas e qual decisão retornaram -A barra de estatísticas no topo exibe a duração da sessão, total de chamadas de ferramentas e um resumo das decisões de hook (contagens de allow / deny / instruct). +A barra de estatísticas no topo exibe a duração da sessão, total de chamadas de ferramentas e um resumo das decisões de hooks (contagens de allow / deny / instruct). -Clique no botão **Download Logs** para exportar a sessão. Para sessões de Claude Code, Codex, Copilot, Cursor e Pi, você recebe a transcrição JSONL original em disco, byte a byte; para OpenCode (cujas sessões residem em SQLite, não em disco) você recebe um documento JSON espelhando as tabelas subjacentes `session` / `messages` / `parts`. +Clique no botão **Download Logs** para exportar a sessão. Para sessões Claude Code, Codex, Copilot, Cursor e Pi, você obtém a transcrição JSONL original em disco byte a byte; para OpenCode (cujas sessões residem no SQLite, não em disco) você obtém um documento JSON espelhando as tabelas subjacentes `session` / `messages` / `parts`. ### Auditoria -Um relatório com personalidade sobre como seu agente realmente se comportou ao longo das sessões passadas. Executa o mesmo escaneamento do CLI `failproofai audit`, mas renderiza como um pôster de tela única compartilhável + quatro seções abaixo da dobra: +Um relatório com personalidade sobre como seu agente realmente tem se comportado nas sessões anteriores. Executa o mesmo escaneamento do CLI `failproofai audit`, mas renderiza como um pôster compartilhável em tela única + quatro seções abaixo da dobra: -1. **Pôster** — preenche o primeiro viewport. Região de captura PNG autossuficiente com o wordmark failproof_ai + rótulo de auditoria · índice de arquétipo (`№ NN of 08`) + data de auditoria · pontuação numérica (0–100) + pílula de percentil (`top 15%`) · o nome do arquétipo (um de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + faixa de 3 palavras-chave · linha de raridade `// only N% of agents are this archetype` · tile de sigilo 8×8 pixels · rodapé `audit yours → failproof.ai`. Três botões de compartilhamento ficam logo fora da caixa de captura: `post your archetype` (X intent), `share on linkedin`, `download poster`. A captura é feita via `html-to-image` para que o PNG corresponda pixel a pixel ao que é exibido na tela (bordas tracejadas, máscara de logo SVG, gradientes, métricas de fonte — tudo preservado). -2. **Pontos fortes** — lista de linhas ✓ tranquilas com comportamentos que seu agente já faz corretamente, derivados dos dados da auditoria ao vivo (taxa de chamada de ferramentas limpa, sem pushes diretos para main, zero vazamentos de credenciais, zero tempestades de tentativas) — cada um exibido apenas quando a política relevante tem um histórico limpo durante a janela de auditoria. -3. **Peculiaridades** — tabela do que passou despercebido, ordenado por gravidade: `quando · o que passou + a política que teria detectado · pílula de severidade · visto`, onde a recorrência aparece como `new` (uma vez), `N× seen` (2–9 vezes) ou `recurring` (10+). -4. **Como melhorar** — lista de linhas tranquilas, uma por política prescrita: nome da política em branco, descrição em uma linha, comando de instalação + botão de cópia no lado direito. O cabeçalho da seção exibe `enable all N → projected · ` (a pontuação que você alcançaria com todas as correções aplicadas), e seu botão `[install all]` copia o comando combinado `failproofai policy add a b c …` para cada política prescrita. -5. **Volte melhorado** — dois cards lado a lado. Esquerda: definir um lembrete (seletor de cadência `3d` / `7d` / `14d` / `30d`; persiste via `/api/auth/reminder` após autenticação). Direita: desbloquear benefícios failproof — `invite a friend` abre um modal que aceita uma lista de e-mails de amigos separados por vírgula/espaço/quebra de linha (máx. 10 por envio), faz POST para `/api/audit/invite`, que encaminha para o `POST /v0/invite` do api-server. O api-server envia um e-mail por destinatário a partir de `invite@failproof.ai` com o remetente em Cc e `Reply-To` configurado, para que o destinatário veja quem o convidou e o remetente receba uma cópia em sua caixa de entrada. Usuários anônimos são redirecionados pelo `AuthDialog` primeiro para que o e-mail do remetente seja conhecido antes de os convites serem enviados. Direitos / cumprimento de benefícios é um acompanhamento futuro. +1. **Pôster** — preenche o primeiro viewport. Região de captura PNG autossuficiente com o logotipo failproof_ai + rótulo de auditoria · índice de arquétipo (`№ NN de 08`) + data da auditoria · pontuação numérica (0–100) + pílula de ranking percentil (`top 15%`) · o nome do arquétipo (um de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + faixa de 3 palavras-chave · linha de raridade `// only N% of agents are this archetype` · tile de sigil 8×8 pixels · rodapé `audit yours → failproof.ai`. Três botões de compartilhamento ficam logo fora da caixa de captura: `post your archetype` (X intent), `share on linkedin`, `download poster`. A captura é feita via `html-to-image`, portanto o PNG corresponde ao renderizado em tela pixel por pixel (bordas tracejadas, máscara de logo SVG, gradientes, métricas de fonte — tudo preservado). +2. **Pontos fortes** — lista de comportamentos com ✓ que seu agente já faz corretamente, derivada dos dados de auditoria ao vivo (taxa de chamadas de ferramentas limpa, sem pushes diretos para main, zero vazamentos de credenciais, zero tempestades de retry) — cada um exibido apenas quando a política relevante tem um histórico limpo na janela de auditoria. +3. **Peculiaridades** — tabela do que passou despercebido, classificado por severidade: `when · what slipped + the policy that would've caught it · severity pill · seen`, onde a recorrência é `new` (uma vez), `N× seen` (2–9 vezes) ou `recurring` (10+). +4. **Como melhorar** — lista calma por linha, uma por política prescrita: nome da política em branco, descrição de uma linha, comando de instalação + botão de copiar no lado direito. O cabeçalho da seção exibe `enable all N → projected · ` (a pontuação que você atingiria com todas as correções aplicadas), e seu botão `[install all]` copia o comando combinado `failproofai policy add a b c …` para cada política prescrita. +5. **Volte melhorado** — dois cards lado a lado. Esquerda: definir um lembrete (seletor de cadência `3d` / `7d` / `14d` / `30d`; persiste via `/api/auth/reminder` após autenticado). Direita: desbloquear benefícios failproof — `invite a friend` abre um modal que aceita uma lista separada por vírgula/espaço/nova linha de e-mails de amigos (máx. 10 por envio), envia POST para `/api/audit/invite`, que repassa para o `POST /v0/invite` do api-server. O api-server envia um e-mail por destinatário de `invite@failproof.ai` com o remetente em Cc e `Reply-To` definido, para que o destinatário veja quem o convidou e o remetente receba uma cópia em sua caixa de entrada. Usuários anônimos são direcionados primeiro pelo `AuthDialog` para que o e-mail do remetente seja conhecido antes de os convites serem enviados. Direitos / cumprimento de benefícios é um acompanhamento. -Impulsionado pelo runtime `failproofai audit` — consulte [CLI de Auditoria](/pt-br/cli/audit) para o mecanismo de escaneamento subjacente, flags suportadas e invariantes de cache por transcrição. O dashboard armazena em cache o resultado mais recente em `~/.failproofai/audit-dashboard.json` (modo `0600`, slot único, novas execuções sobrescrevem) para que revisitas sejam instantâneas; **tanto os caches por transcrição quanto os de resultado completo são rejeitados na leitura após 7 dias** para que o dashboard nunca sirva silenciosamente um resultado com uma semana de atraso — após o TTL, `/audit` vai para seu estado vazio e solicita uma nova execução. Clicar em `[ re-audit now ]` próximo ao final do relatório faz POST em `/api/audit/run` com `noCache: true` — uma re-auditoria ignora o cache por transcrição e re-escaneia cada transcrição do zero em vez de retornar silenciosamente o resultado em cache — e o dashboard faz polling em `/api/audit/status` a 1Hz até que a execução termine; uma faixa rosa fixa de progresso é fixada no topo do viewport durante a execução com um cronômetro decorrido, e o resultado atualizado substitui o anterior ao concluir com sucesso (sem recarregamento completo da página; uma re-auditoria com falha deixa o relatório anterior intacto). Em caso de falha, a faixa fica vermelha com texto baseado no `RerunError.kind` (`timeout` / `network` / `post_failed`). Estado vazio (sem cache ou expirado) e estado de zero sessões (cache existe, mas o escaneamento não encontrou transcrições) são apresentados separadamente. +Impulsionado pelo runtime `failproofai audit` — consulte [Audit CLI](/pt-br/cli/audit) para o mecanismo de escaneamento subjacente, flags suportadas e invariantes de cache por transcrição. O dashboard armazena o resultado mais recente em `~/.failproofai/audit-dashboard.json` (modo `0600`, slot único, novas execuções sobrescrevem) para que revisitas sejam instantâneas; **tanto os caches por transcrição quanto os de resultado completo são rejeitados na leitura quando têm mais de 7 dias**, portanto o dashboard nunca serve silenciosamente um resultado de uma semana atrás — após o TTL, `/audit` retorna ao estado vazio e solicita uma nova execução. Clicar em `[ re-audit now ]` perto do final do relatório envia POST para `/api/audit/run` com `noCache: true` — a re-auditoria ignora o cache por transcrição e reescande todas as transcrições do zero em vez de retornar silenciosamente o resultado em cache — e o dashboard consulta `/api/audit/status` a 1Hz até a execução terminar; uma faixa de progresso rosa fixa é fixada no topo do viewport durante a execução com um cronômetro, e o resultado atualizado é inserido no lugar ao concluir com sucesso (sem recarregamento de página completo; uma re-auditoria com falha mantém o relatório anterior intacto). Em caso de falha, a faixa fica vermelha com mensagem vinculada ao `RerunError.kind` (`timeout` / `network` / `post_failed`). Estado vazio (sem cache ou expirado) e estado de zero sessões (cache existe, mas o escaneamento não encontrou transcrições) são exibidos separadamente. ### Políticas Uma página com duas abas para gerenciar políticas e revisar atividades. - - - Seleção múltipla de quais CLIs de agentes o failproofai protege a partir de um único painel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Hermes têm uma linha com status de instalação (`Active` / `Detected` / `Inactive`), o caminho de configurações de escopo de usuário e um destaque colorido por marca. Marque ou desmarque os CLIs desejados e clique em `Apply changes` para instalar/desinstalar a diferença em uma etapa. CLIs cujo binário é detectado no PATH são pré-marcados. - - Ative ou desative políticas individuais com um único clique (salva em `~/.failproofai/policies-config.json` — compartilhado entre todos os CLIs instalados) + + - Selecione múltiplas CLIs de agentes que o failproofai protege a partir de um único painel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Hermes têm uma linha com status de instalação (`Active` / `Detected` / `Inactive`), o caminho de configurações do escopo do usuário e um destaque colorido da marca. Marque ou desmarque as CLIs que deseja e clique em `Apply changes` para instalar/desinstalar a diferença em um único passo. CLIs cujo binário é detectado no PATH são pré-marcadas. + - Ative ou desative políticas individuais com um único clique (escreve em `~/.failproofai/policies-config.json` — compartilhado entre todas as CLIs instaladas) - Expanda uma política para configurar seus parâmetros (para políticas que suportam `policyParams`) - Defina um caminho de arquivo de políticas personalizado - - - Histórico paginado completo de cada evento de hook disparado em todas as sessões - - Filtre por decisão, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nome da política ou ID de sessão - - Cada linha exibe: timestamp, nome da política, decisão, badge de CLI (laranja = Claude Code, roxo = OpenAI Codex, azul = GitHub Copilot, esmeralda = Cursor Agent, âmbar = OpenCode, rosa = Pi, índigo = Hermes, verde-azulado = OpenClaw, rosa-avermelhado = Factory Droid, violeta = Devin, ciano = Antigravity, lima = Goose), nome da ferramenta, ID de sessão e o motivo para decisões de deny/instruct - - Clique em um ID de sessão para abrir sua transcrição — o visualizador detecta automaticamente qual CLI disparou o hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) e renderiza o badge do CLI correspondente no cabeçalho + + - Histórico paginado completo de cada evento de hook que foi acionado em todas as sessões + - Filtre por decisão, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nome de política ou ID de sessão + - Cada linha exibe: timestamp, nome da política, decisão, badge de CLI (laranja = Claude Code, roxo = OpenAI Codex, azul = GitHub Copilot, esmeralda = Cursor Agent, âmbar = OpenCode, rosa = Pi, índigo = Hermes, teal = OpenClaw, rose = Factory Droid, violeta = Devin, ciano = Antigravity, lima = Goose), nome da ferramenta, ID de sessão e o motivo para decisões deny/instruct + - Clique em um ID de sessão para abrir sua transcrição — o visualizador detecta automaticamente qual CLI acionou o hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) e renderiza o badge de CLI correspondente no cabeçalho @@ -94,13 +94,13 @@ Uma página com duas abas para gerenciar políticas e revisar atividades. ## Atualização automática -O dashboard possui um botão de alternância de atualização automática na navegação superior. Quando ativado, a página atual é atualizada periodicamente para exibir novas sessões e atividades de políticas conforme aparecem. Essencial para monitorar sessões de agentes autônomos de longa duração. +O dashboard possui um botão de atualização automática na navegação superior. Quando ativado, a página atual é atualizada periodicamente para exibir novas sessões e atividade de políticas conforme surgem. Essencial para monitorar sessões de agentes autônomos de longa duração. --- -## Desabilitando páginas +## Desativando páginas -Se você precisar apenas de algumas partes do dashboard, defina `FAILPROOFAI_DISABLE_PAGES` com uma lista de nomes de páginas separados por vírgula: +Se você precisar apenas de algumas partes do dashboard, defina `FAILPROOFAI_DISABLE_PAGES` com uma lista separada por vírgulas dos nomes das páginas: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -112,7 +112,7 @@ Valores válidos: `policies`, `projects`, `audit`. ## Configurando o caminho dos projetos -Por padrão, o dashboard lê do diretório padrão de projetos do Claude Code. Substitua para configurações personalizadas: +Por padrão, o dashboard lê do diretório padrão de projetos do Claude Code. Substitua-o para configurações personalizadas: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,7 +120,7 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Acessando de um host diferente de localhost +## Acessando a partir de um host diferente de localhost Ao executar o dashboard em **modo dev** (`npm run dev`) e acessá-lo a partir de um hostname diferente de `localhost` — por exemplo, um domínio personalizado, um IP remoto ou uma URL tunelada — você pode ver um aviso como: @@ -128,7 +128,7 @@ Ao executar o dashboard em **modo dev** (`npm run dev`) e acessá-lo a partir de ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Isso é o Next.js bloqueando o acesso cross-origin ao seu websocket de HMR (hot module reload), que é um recurso exclusivo do modo dev. Para permitir seu host, use a flag `--allowed-origins`: +Isso é o Next.js bloqueando o acesso de origem cruzada ao seu websocket HMR (hot module reload), que é um recurso exclusivo de desenvolvimento. Para permitir seu host, use a flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -147,5 +147,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Isso se aplica apenas ao modo dev. Ao executar `failproofai` (modo produção), não há websocket de HMR nem problema de recurso dev cross-origin. +Isso se aplica apenas ao modo dev. Ao executar `failproofai` (modo de produção), não há websocket HMR nem problema de recurso de desenvolvimento de origem cruzada. \ No newline at end of file diff --git a/docs/pt-br/examples.mdx b/docs/pt-br/examples.mdx index 07754d3e..504ab665 100644 --- a/docs/pt-br/examples.mdx +++ b/docs/pt-br/examples.mdx @@ -8,9 +8,9 @@ Exemplos prontos para uso em cenários comuns. Cada um mostra como instalar e o --- -## Configurando hooks para o Claude Code +## Configurando hooks para Claude Code -O Failproof AI integra-se ao Claude Code por meio do seu [sistema de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando você executa `failproofai policies --install`, ele registra comandos de hook no `settings.json` do Claude Code que são acionados a cada chamada de ferramenta. +Failproof AI integra com Claude Code por meio do seu [sistema de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Ao executar `failproofai policies --install`, ele registra comandos de hook no `settings.json` do Claude Code que são disparados a cada chamada de ferramenta. @@ -52,7 +52,7 @@ Se você está desenvolvendo com o [Agents SDK](https://docs.anthropic.com/en/do ``` - Passe comandos de hook ao criar o processo do seu agente. Os hooks são acionados da mesma forma que no Claude Code — via stdin/stdout JSON: + Passe comandos de hook ao criar o processo do seu agente. Os hooks são disparados da mesma forma que no Claude Code — via stdin/stdout JSON: ```bash failproofai --hook PreToolUse # chamado antes de cada ferramenta @@ -88,7 +88,7 @@ Se você está desenvolvendo com o [Agents SDK](https://docs.anthropic.com/en/do ## Bloquear comandos destrutivos -A configuração mais comum — impedir que agentes causem danos irreversíveis. +A configuração mais comum — impede que agentes causem danos irreversíveis. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -104,19 +104,19 @@ O que isso faz: ## Prevenir vazamento de segredos -Impeça que agentes visualizem ou vazem credenciais na saída de ferramentas. +Impede que agentes visualizem ou vazem credenciais na saída das ferramentas. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Essas políticas são acionadas no `PostToolUse` — após a execução de uma ferramenta, elas limpam a saída antes que o agente a veja. +Esses hooks são disparados no `PostToolUse` — após a execução de uma ferramenta, eles limpam a saída antes que o agente a veja. --- ## Receber alertas no Slack quando agentes precisam de atenção -Use o hook de notificação para encaminhar alertas de inatividade ao Slack. +Use o hook de notificação para encaminhar alertas de ociosidade ao Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -Instale com: +Instale assim: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -160,7 +160,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## Manter agentes em uma branch -Impeça que agentes troquem de branch ou façam push para branches protegidas. +Impede que agentes troquem de branch ou façam push em branches protegidas. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +184,7 @@ customPolicies.add({ ## Exigir testes antes de commits -Lembre os agentes de executar os testes antes de fazer commit. +Lembra os agentes de executar os testes antes de fazer commit. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -206,7 +206,7 @@ customPolicies.add({ --- -## Proteger um repositório de produção +## Bloquear um repositório de produção Faça commit de uma configuração no nível do projeto para que todos os desenvolvedores do seu time utilizem as mesmas políticas. @@ -244,7 +244,7 @@ Todo membro do time que tiver o failproofai instalado irá receber essas regras ## Construir um padrão de qualidade organizacional com políticas de convenção -A configuração de maior impacto: faça commit de `.failproofai/policies/` no seu repositório com políticas ajustadas ao seu projeto. Todos os membros do time as recebem automaticamente — sem comandos de instalação, sem alterações de configuração. +A configuração de maior impacto: faça commit de `.failproofai/policies/` no seu repositório com políticas adaptadas ao seu projeto. Todos os membros do time as recebem automaticamente — sem comandos de instalação, sem alterações de configuração. @@ -290,7 +290,7 @@ A configuração de maior impacto: faça commit de `.failproofai/policies/` no s ``` - À medida que o seu time encontrar novos problemas, adicione políticas e faça push. Todos recebem a atualização no próximo `git pull`. Essas políticas se tornam um padrão de qualidade vivo que cresce junto com o time. + À medida que seu time encontrar novos problemas, adicione políticas e faça push. Todos recebem a atualização no próximo `git pull`. Essas políticas se tornam um padrão de qualidade vivo que cresce junto com o time. @@ -302,6 +302,6 @@ O diretório [`examples/`](https://github.com/failproofai/failproofai/tree/main/ | Arquivo | O que demonstra | |---------|-----------------| -| `policies-basic.js` | Políticas iniciais — bloquear escritas em produção, force-push e scripts redirecionados | -| `policies-notification.js` | Alertas no Slack para notificações de inatividade e encerramento de sessão | -| `policies-advanced/index.js` | Importações transitivas, hooks assíncronos, limpeza de saída no PostToolUse e tratamento do evento Stop | \ No newline at end of file +| `policies-basic.js` | Políticas iniciais — bloquear escritas em produção, force-push, scripts redirecionados | +| `policies-notification.js` | Alertas no Slack para notificações de ociosidade e encerramento de sessão | +| `policies-advanced/index.js` | Importações transitivas, hooks assíncronos, limpeza de saída no PostToolUse, tratamento do evento Stop | \ No newline at end of file diff --git a/docs/pt-br/for-agents.mdx b/docs/pt-br/for-agents.mdx index df384387..5f24bf6b 100644 --- a/docs/pt-br/for-agents.mdx +++ b/docs/pt-br/for-agents.mdx @@ -1,9 +1,9 @@ --- title: "Para agentes" -description: "Adicione o conhecimento do Failproof AI ao seu agente de codificação com um único comando. Funciona com Claude Code, Cursor, Windsurf e muito mais." +description: "Adicione o conhecimento do Failproof AI ao seu agente de programação com um único comando. Compatível com Claude Code, Cursor, Windsurf e muito mais." --- -Adicione a referência completa do Failproof AI ao seu agente de codificação com um único comando. Funciona com Claude Code, Cursor, Windsurf e qualquer outro agente que suporte skills. +Adicione a referência completa do Failproof AI ao seu agente de programação com um único comando. Compatível com Claude Code, Cursor, Windsurf e qualquer outro agente que suporte skills. ```bash npx skills add https://docs.befailproof.ai @@ -15,17 +15,17 @@ O `npx skills` detecta quais agentes você tem instalados e adiciona a skill no | Área | O que está incluído | |------|----------------| -| Policies | Nomes de policies nativas, tipos de eventos, parâmetros, ativar/desativar | +| Policies | Nomes de políticas integradas, tipos de eventos, parâmetros, habilitar/desabilitar | | Custom policies | `customPolicies.add()`, filtros de correspondência, API `allow`/`deny`/`instruct` | | Objeto de contexto | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configuração | Estrutura do `policies-config.json`, mesclagem de escopos, `policyParams` | +| Configuração | Estrutura do `policies-config.json`, mesclagem de escopo, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, escopos | -| Dashboard | Visualizador de sessões, atividade de policies, variáveis de ambiente | +| Dashboard | Visualizador de sessão, atividade de políticas, variáveis de ambiente | | Arquitetura | Fluxo do hook handler, códigos de saída, contrato stdin/stdout | ## A skill está completa? -O Mintlify gera o `llms.txt` a partir de todas as páginas da navegação. A documentação do Failproof AI cobre a API completa — cada policy, opção e exemplo está incluído. Se você encontrar algo faltando, a fonte está em `https://docs.befailproof.ai/llms-full.txt`. +O Mintlify gera o `llms.txt` a partir de todas as páginas da navegação. A documentação do Failproof AI cobre a API completa — cada política, opção e exemplo está incluído. Se você encontrar algo faltando, a fonte está em `https://docs.befailproof.ai/llms-full.txt`. Para contexto direcionado, vincule diretamente a uma página específica: @@ -33,6 +33,6 @@ Para contexto direcionado, vincule diretamente a uma página específica: # Apenas a API de custom policies npx skills add https://docs.befailproof.ai/custom-policies -# Apenas as built-in policies +# Apenas as políticas integradas npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/pt-br/getting-started.mdx b/docs/pt-br/getting-started.mdx index bbcef174..03157694 100644 --- a/docs/pt-br/getting-started.mdx +++ b/docs/pt-br/getting-started.mdx @@ -1,6 +1,6 @@ --- title: Primeiros passos -description: "Instale o failproofai, ative as políticas e deixe seus agentes funcionando com confiabilidade" +description: "Instale o failproofai, ative as políticas e deixe seus agentes funcionando de forma confiável" icon: rocket --- @@ -37,9 +37,9 @@ bun add -g failproofai failproofai policies --install ``` - Isso insere entradas de hook nos CLIs de agente instalados (o `~/.claude/settings.json` do Claude Code, o `~/.codex/hooks.json` do OpenAI Codex, o `~/.copilot/hooks/failproofai.json` do GitHub Copilot CLI, o `~/.cursor/hooks.json` do Cursor Agent, o shim de plugin gerado pelo OpenCode em `~/.config/opencode/plugins/failproofai.mjs` mais uma entrada de registro no array `plugin` do `~/.config/opencode/opencode.json`, o `~/.pi/agent/settings.json` do Pi, o `~/.hermes/config.yaml` do Hermes, o `~/.openclaw/openclaw.json` do OpenClaw, o `~/.factory/hooks.json` do Factory Droid, o `~/.config/devin/config.json` do Devin CLI, o `~/.gemini/config/hooks.json` do Antigravity CLI, ou o diretório de plugin autodescoberto do Goose em `~/.agents/plugins/failproofai/hooks/hooks.json`). Quando mais de um estiver presente, você será solicitado a escolher; passe `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (qualquer subconjunto) para pular a solicitação. + Isso escreve entradas de hook nos CLIs de agente instalados (o `~/.claude/settings.json` do Claude Code, o `~/.codex/hooks.json` do OpenAI Codex, o `~/.copilot/hooks/failproofai.json` do GitHub Copilot CLI, o `~/.cursor/hooks.json` do Cursor Agent, o shim de plugin gerado pelo OpenCode em `~/.config/opencode/plugins/failproofai.mjs` mais uma entrada de registro no array `plugin` do `~/.config/opencode/opencode.json`, o `~/.pi/agent/settings.json` do Pi, o `~/.hermes/config.yaml` do Hermes, o `~/.openclaw/openclaw.json` do OpenClaw, o `~/.factory/hooks.json` do Factory Droid, o `~/.config/devin/config.json` do Devin CLI, o `~/.gemini/config/hooks.json` do Antigravity CLI, ou o diretório de plugin autodescoberto do Goose em `~/.agents/plugins/failproofai/hooks/hooks.json`). Quando mais de um estiver presente, você será solicitado a escolher; passe `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (qualquer subconjunto) para pular o prompt. - O suporte ao GitHub Copilot CLI, Cursor Agent, OpenCode e Pi está em **beta** — instale com `--cli copilot`, `--cli cursor`, `--cli opencode` ou `--cli pi`. O Hermes (hermes-agent, um gateway Slack/Telegram) é instalado no escopo do usuário com `--cli hermes` e é **também** uma fonte de auditoria offline. O OpenClaw (gateway openclaw, um assistente multicanal auto-hospedado) é instalado no escopo do usuário com `--cli openclaw` — a aplicação de políticas ocorre por meio de seus hooks de plugin em processo (`before_agent_finalize` é uma barreira real de fim de turno, portanto os built-ins `require-*-before-stop` são aplicados) — e é **também** uma fonte de auditoria offline. O Factory Droid (`droid`) é instalado com `--cli factory` (escopo de usuário e projeto) e é **também** uma fonte de auditoria offline. O Devin CLI (`devin`, Cognition) é instalado com `--cli devin` (escopo de usuário e projeto) e é **também** uma fonte de auditoria offline. O Antigravity CLI (`agy`) é instalado com `--cli antigravity` (escopo de usuário e projeto) e é **também** uma fonte de auditoria offline. O Goose (codinome goose, Block) é instalado com `--cli goose` (escopo de usuário e projeto) — o instalador simplesmente cria um diretório de plugin em `~/.agents/plugins/failproofai/` que o Goose autodescobre, e é **também** uma fonte de auditoria offline. + O suporte ao GitHub Copilot CLI, Cursor Agent, OpenCode e Pi está em **beta** — instale com `--cli copilot`, `--cli cursor`, `--cli opencode` ou `--cli pi`. O Hermes (hermes-agent, um gateway Slack/Telegram) instala com escopo de usuário via `--cli hermes` e é **também** uma fonte de auditoria offline. O OpenClaw (gateway openclaw, um assistente multicanal auto-hospedado) instala com escopo de usuário via `--cli openclaw` — a aplicação das regras ocorre através dos hooks de plugin em processo (`before_agent_finalize` é um gate real de fim de turno, portanto os builtins `require-*-before-stop` são aplicados) — e é **também** uma fonte de auditoria offline. O Factory Droid (`droid`) instala com `--cli factory` (escopo de usuário e projeto) e é **também** uma fonte de auditoria offline. O Devin CLI (`devin`, Cognition) instala com `--cli devin` (escopo de usuário e projeto) e é **também** uma fonte de auditoria offline. O Antigravity CLI (`agy`) instala com `--cli antigravity` (escopo de usuário e projeto) e é **também** uma fonte de auditoria offline. O Goose (codinome goose, Block) instala com `--cli goose` (escopo de usuário e projeto) — o instalador apenas cria um diretório de plugin em `~/.agents/plugins/failproofai/` que o Goose autodescobre, e é **também** uma fonte de auditoria offline. ```bash failproofai policies --install --scope project @@ -62,17 +62,17 @@ bun add -g failproofai failproofai policies ``` - Exibe todas as políticas, se estão habilitadas e quaisquer parâmetros configurados. + Exibe todas as políticas, se estão ativas e quaisquer parâmetros configurados. - + ```bash failproofai ``` - Abre um painel local em `http://localhost:8020` onde você pode navegar por sessões, inspecionar chamadas de ferramentas e gerenciar políticas. + Abre um dashboard local em `http://localhost:8020` onde você pode navegar pelas sessões, inspecionar chamadas de ferramentas e gerenciar políticas. - Inicie o Claude Code normalmente. Se o agente tentar algo arriscado, o failproofai intercepta automaticamente. Deixe-o rodando sem supervisão e revise o que aconteceu no painel. + Inicie o Claude Code normalmente. Se o agente tentar algo arriscado, o failproofai o intercepta automaticamente. Deixe-o em execução sem supervisão e revise o que aconteceu no dashboard. @@ -80,7 +80,7 @@ bun add -g failproofai ## Como as políticas funcionam -Sempre que um agente executa uma ferramenta, o Claude Code chama o failproofai como subprocesso: +Toda vez que um agente executa uma ferramenta, o Claude Code chama o failproofai como um subprocesso: ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -92,17 +92,17 @@ Cada política retorna uma de três decisões: - **allow** - o agente prossegue normalmente - **deny** - a ação é bloqueada e o agente é informado do motivo -- **instruct** - contexto adicional é inserido no prompt do agente +- **instruct** - contexto adicional é adicionado ao prompt do agente -As políticas são executadas em seu processo local. Nada é enviado para um serviço remoto. +As políticas são executadas no seu processo local. Nada é enviado para um serviço remoto. --- ## Configure políticas de equipe com políticas baseadas em convenção -A maneira mais rápida de estabelecer padrões de qualidade em toda a sua equipe é a convenção `.failproofai/policies/`. Coloque arquivos de política neste diretório e eles serão carregados automaticamente — sem flags, sem alterações de configuração, sem comandos de instalação. +A maneira mais rápida de estabelecer padrões de qualidade em toda a sua equipe é a convenção `.failproofai/policies/`. Coloque arquivos de política neste diretório e eles são carregados automaticamente — sem flags, sem mudanças de configuração, sem comandos de instalação. @@ -136,33 +136,35 @@ A maneira mais rápida de estabelecer padrões de qualidade em toda a sua equipe }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Todos os membros da equipe que têm o failproofai instalado recebem essas políticas automaticamente. Nenhuma configuração por desenvolvedor é necessária. + Todo membro da equipe que tem o failproofai instalado recebe essas políticas automaticamente. Nenhuma configuração individual por desenvolvedor é necessária. -Faça commit de `.failproofai/policies/` no seu repositório para que toda a equipe compartilhe os mesmos padrões. À medida que sua equipe descobre novos modos de falha, adicione políticas e faça push — todos recebem a atualização no próximo `git pull`. Com o tempo, essas políticas se tornam um padrão de qualidade vivo que continua melhorando. +Faça commit de `.failproofai/policies/` no seu repositório para que toda a equipe compartilhe os mesmos padrões. À medida que sua equipe descobrir novos modos de falha, adicione políticas e faça push — todos receberão a atualização no próximo `git pull`. Com o tempo, essas políticas se tornam um padrão de qualidade vivo que continua melhorando. --- ## Armazenamento de dados -Todas as configurações e logs permanecem na sua máquina: +Toda a configuração e os logs ficam na sua máquina: | Caminho | O que armazena | -|------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | Configuração global de políticas | +|---------|----------------| +| `~/.failproofai/policies-config.json` | Configuração global de políticas | +| `~/.failproofai/policies/` | Suas próprias políticas — adicione arquivos `*-policies.mjs`, sem necessidade de configuração | +| `~/.failproofai/policies/cloud-policies/` | Políticas implantadas nesta máquina pela sua organização | | `~/.failproofai/hook-activity/` | Histórico de execução de hooks (JSONL paginado) | | `~/.failproofai/logs/` | Logs de depuração para erros de hooks personalizados | -| `.failproofai/policies-config.json` | Configuração por projeto (versionada) | -| `.failproofai/policies-config.local.json` | Substituições pessoais (ignoradas pelo git) | +| `.failproofai/policies-config.json` | Configuração por projeto (commitada) | +| `.failproofai/policies-config.local.json` | Substituições pessoais (ignorado pelo git) | --- @@ -181,18 +183,18 @@ Remove as entradas de hook do `~/.claude/settings.json`. Os arquivos de configur - Escopos e formato dos arquivos de configuração + Escopos e formato do arquivo de configuração - Todas as 26 políticas com seus parâmetros + Todas as 26 políticas com parâmetros Escreva suas próprias políticas em JavaScript - + Monitore sessões e revise a atividade das políticas diff --git a/docs/pt-br/introduction.mdx b/docs/pt-br/introduction.mdx index 4b1ab604..db8944c1 100644 --- a/docs/pt-br/introduction.mdx +++ b/docs/pt-br/introduction.mdx @@ -1,24 +1,24 @@ --- title: "Failproof AI" -description: "FailproofAI oferece aos agentes de IA 39 políticas de falha integradas que detectam loops, vazamentos de segredos, chamadas de ferramentas destrutivas e muito mais em uma única instalação." +description: "FailproofAI oferece 39 políticas de falha integradas para agentes de IA que detectam loops, vazamentos de segredos, chamadas destrutivas de ferramentas e muito mais em uma única instalação." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) Hooks e políticas para **tratamento de falhas de IA**, **recuperação de erros** e **confiabilidade de LLM**. Mantenha seus agentes de IA confiáveis e funcionando de forma autônoma no **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** e no **Agents SDK**. -Agentes de IA falham de maneiras previsíveis. Eles executam comandos destrutivos, vazam segredos, desviam de suas tarefas, ficam presos em loops ou fazem push diretamente para a branch main. Sem supervisão, pequenas falhas se transformam em indisponibilidades, credenciais expostas e trabalho perdido. +Agentes de IA falham de maneiras previsíveis. Eles executam comandos destrutivos, vazam segredos, desviam da tarefa, ficam presos em loops ou fazem push direto para a main. Sem supervisão, pequenas falhas se transformam em interrupções, credenciais expostas e trabalho perdido. -O FailproofAI resolve isso com **políticas**. Essas regras se conectam a cada chamada de ferramenta do agente para **detectar falhas**, **mitigá-las** (bloquear, instruir, sanitizar) e **alertar você** quando algo precisa de atenção. Um painel local permite revisar cada chamada de ferramenta, falha de agente e ação de recuperação depois. +O FailproofAI resolve isso com **políticas**. Essas regras se conectam a cada chamada de ferramenta do agente para **detectar falhas**, **mitigá-las** (bloquear, instruir, sanitizar) e **alertar você** quando algo requer atenção. Um painel local permite revisar cada chamada de ferramenta, falha do agente e ação de recuperação depois do fato. -Transcrições e avaliações de políticas ficam na sua máquina. Os dados são enviados apenas quando você usa explicitamente um recurso online, como lembretes de auditoria autenticados ou convites. +Transcrições e avaliações de políticas permanecem na sua máquina. Os dados são enviados apenas quando você usa explicitamente um recurso online, como lembretes de auditoria autenticados ou convites. ## Primeiros passos - Bloqueie comandos destrutivos, evite vazamentos de segredos, mantenha os agentes dentro dos limites do projeto e muito mais. Tudo pronto para uso. + Bloqueie comandos destrutivos, evite vazamentos de segredos, mantenha os agentes dentro dos limites do projeto e muito mais. Tudo pronto para usar. @@ -26,11 +26,11 @@ Transcrições e avaliações de políticas ficam na sua máquina. Os dados são - Veja o que seus agentes fizeram enquanto você estava ausente. Navegue por sessões, inspecione chamadas de ferramentas e revise onde as políticas foram acionadas. + Veja o que seus agentes fizeram enquanto você estava ausente. Navegue pelas sessões, inspecione chamadas de ferramentas e revise onde as políticas foram acionadas. - Ajuste qualquer política sem escrever código. Defina allowlists, branches protegidas ou limites por projeto ou globalmente. + Ajuste qualquer política sem escrever código. Defina listas de permissões, branches protegidas ou limites por projeto ou globalmente. diff --git a/docs/pt-br/package-aliases.mdx b/docs/pt-br/package-aliases.mdx index 66957295..96857b99 100644 --- a/docs/pt-br/package-aliases.mdx +++ b/docs/pt-br/package-aliases.mdx @@ -16,11 +16,11 @@ bun add -g failproofai --- -## Por que detemos os nomes de alias +## Por que registramos os nomes de alias -Typosquatting é um ataque comum à cadeia de suprimentos de software, onde um agente malicioso registra um nome de pacote que difere por apenas um caractere de um pacote popular. Usuários desavisados que digitam incorretamente o comando de instalação acabam executando código controlado pelo atacante com acesso total ao sistema — exatamente o tipo de ameaça que o Failproof AI foi projetado para combater. +Typosquatting é um ataque comum à cadeia de suprimentos de software, no qual um agente malicioso registra um nome de pacote com apenas um erro de digitação em relação a um pacote popular. Usuários desatentos que digitam o comando de instalação incorretamente acabam executando código controlado pelo atacante com acesso total ao sistema — exatamente o tipo de ameaça que o Failproof AI foi projetado para combater. -Para eliminar essa superfície de ataque, **detemos preventivamente todas as grafias incorretas comuns e variantes de formatação** de `failproofai` no npm. Nenhum desses nomes pode ser registrado por terceiros. Cada um é um proxy simples que instala e delega para o pacote real `failproofai`. +Para eliminar essa superfície de ataque, **registramos preventivamente todos os erros ortográficos comuns e variantes de formatação** de `failproofai` no npm. Nenhum desses nomes pode ser registrado por terceiros. Cada um é um proxy simples que instala e delega ao pacote real `failproofai`. --- @@ -31,11 +31,11 @@ Para eliminar essa superfície de ataque, **detemos preventivamente todas as gra | Pacote | Status | |--------|--------| | `failproof` | ✅ Publicado | -| `failproof-ai` | ⏳ Aguardando aprovação do npm | -| `fail-proof-ai` | ⏳ Aguardando aprovação do npm | -| `failproof_ai` | ⏳ Aguardando aprovação do npm | -| `fail_proof_ai` | ⏳ Aguardando aprovação do npm | -| `fail-proofai` | ⏳ Aguardando aprovação do npm | +| `failproof-ai` | ⏳ Aguardando suporte do npm | +| `fail-proof-ai` | ⏳ Aguardando suporte do npm | +| `failproof_ai` | ⏳ Aguardando suporte do npm | +| `fail_proof_ai` | ⏳ Aguardando suporte do npm | +| `fail-proofai` | ⏳ Aguardando suporte do npm | **Erros de digitação `failprof*`** — faltando um `o` em "proof": @@ -43,19 +43,19 @@ Para eliminar essa superfície de ataque, **detemos preventivamente todas as gra |--------|--------| | `failprof` | ✅ Publicado | | `failprof-ai` | ✅ Publicado | -| `failprofai` | ⏳ Aguardando aprovação do npm | -| `fail-prof-ai` | ⏳ Aguardando aprovação do npm | -| `failprof_ai` | ⏳ Aguardando aprovação do npm | +| `failprofai` | ⏳ Aguardando suporte do npm | +| `fail-prof-ai` | ⏳ Aguardando suporte do npm | +| `failprof_ai` | ⏳ Aguardando suporte do npm | -**Erros de digitação `faliproof*`** — `a` e `i` invertidos: +**Erros de digitação `faliproof*`** — `a` e `i` trocados de posição: | Pacote | Status | |--------|--------| | `faliproof` | ✅ Publicado | | `faliproof-ai` | ✅ Publicado | -| `faliproofai` | ⏳ Aguardando aprovação do npm | +| `faliproofai` | ⏳ Aguardando suporte do npm | -> **Por que aguardando aprovação?** A política de prevenção de spam do npm bloqueia nomes que são normalizados para a mesma string de um pacote existente após remoção de pontuação e verificações de similaridade. Entramos em contato com o suporte do npm para reservar esses nomes com fins anti-typosquatting. Eles serão ativados após aprovação. +> **Por que estão pendentes?** A política de prevenção de spam do npm bloqueia nomes que, após remoção de pontuação e verificações de similaridade, se normalizam para a mesma string de um pacote existente. Entramos em contato com o suporte do npm para reservar esses nomes com fins anti-typosquatting. Eles serão ativados após aprovação. Você pode verificar que qualquer alias publicado pertence a nós: @@ -68,12 +68,12 @@ npm info failproof ## Como os aliases funcionam -Cada pacote de alias: +Cada pacote alias: 1. Lista `failproofai` como dependência — assim o pacote real é instalado e seu binário fica disponível -2. Expõe um binário correspondente ao seu próprio nome (ex.: `failprof-ai`) que repassa todos os argumentos para o binário `failproofai` +2. Expõe um binário com seu próprio nome (ex.: `failprof-ai`) que repassa todos os argumentos para o binário `failproofai` -O proxy é um script Node de duas linhas; não há lógica adicional, chamadas de rede nem coleta de dados além do que o próprio `failproofai` já realiza. +O proxy é um script Node de duas linhas; não há lógica adicional, chamadas de rede, nem coleta de dados além do que o próprio `failproofai` realiza. --- diff --git a/docs/pt-br/testing.mdx b/docs/pt-br/testing.mdx index d48f29ac..65ff8c65 100644 --- a/docs/pt-br/testing.mdx +++ b/docs/pt-br/testing.mdx @@ -17,7 +17,7 @@ bun run test:run # Executar testes unitários em modo watch bun run test -# Executar testes E2E (requer configuração — veja abaixo) +# Executar testes E2E (requer configuração - veja abaixo) bun run test:e2e # Verificar tipos sem compilar @@ -31,12 +31,12 @@ bun run lint ## Testes unitários -Os testes unitários ficam em `__tests__/` e utilizam [Vitest](https://vitest.dev) com `jsdom`. +Os testes unitários ficam em `__tests__/` e usam [Vitest](https://vitest.dev) com `jsdom`. ```text __tests__/ hooks/ - builtin-policies.test.ts # Lógica de políticas para cada builtin + builtin-policies.test.ts # Lógica de política para cada builtin hooks-config.test.ts # Carregamento de configuração e mesclagem de escopos policy-evaluator.test.ts # Injeção de parâmetros e ordem de avaliação custom-hooks-registry.test.ts # Registro globalThis: add/get/clear @@ -110,11 +110,11 @@ describe("block-sudo", () => { ## Testes end-to-end -Os testes E2E invocam o binário real do `failproofai` como subprocesso, enviam um payload JSON via stdin e validam a saída no stdout e o código de saída. Isso testa o caminho completo de integração que o Claude Code utiliza. +Os testes E2E invocam o binário real do `failproofai` como subprocesso, enviam um payload JSON via stdin e verificam a saída no stdout e o código de saída. Isso testa o caminho completo de integração que o Claude Code utiliza. ### Configuração -Os testes E2E executam o binário diretamente a partir do código-fonte do repositório. Antes da primeira execução, compile o bundle CJS que os arquivos de hook customizados utilizam ao importar de `'failproofai'`: +Os testes E2E executam o binário diretamente a partir do código-fonte do repositório. Antes da primeira execução, compile o bundle CJS que os arquivos de hook personalizados utilizam ao importar de `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -133,26 +133,26 @@ Recompile o `dist/` sempre que alterar a API pública de hooks (`src/hooks/custo ```text __tests__/e2e/ helpers/ - hook-runner.ts # Inicia o binário, envia o payload JSON, captura código de saída + stdout + stderr - fixture-env.ts # Diretórios temporários isolados por teste com arquivos de configuração + hook-runner.ts # Inicia o binário, envia payload JSON, captura código de saída + stdout + stderr + fixture-env.ts # Diretórios temporários isolados por teste, com arquivos de configuração payloads.ts # Fábricas de payload fiéis ao Claude para cada tipo de evento hooks/ builtin-policies.e2e.test.ts # Cada política builtin com subprocesso real - custom-hooks.e2e.test.ts # Carregamento e avaliação de hooks customizados + custom-hooks.e2e.test.ts # Carregamento e avaliação de hooks personalizados config-scopes.e2e.test.ts # Mesclagem de configuração entre escopos project/local/global policy-params.e2e.test.ts # Injeção de parâmetros para cada política parametrizada ``` ### Usando os utilitários E2E -**`FixtureEnv`** — ambiente isolado por teste: +**`FixtureEnv`** - ambiente isolado por teste: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); // env.cwd - diretório temporário; passe como payload.cwd para carregar .failproofai/policies-config.json -// env.home - diretório home isolado; nenhum dado real de ~/.failproofai vaza para os testes +// env.home - diretório home isolado; evita vazamento do ~/.failproofai real env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -164,7 +164,7 @@ env.writeConfig({ `createFixtureEnv()` registra a limpeza via `afterEach` automaticamente. -**`runHook`** — invoca o binário: +**`runHook`** - invoca o binário: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** — fábricas de payload prontas para uso: +**`Payloads`** - fábricas de payload prontas para uso: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -237,19 +237,19 @@ describe("block-rm-rf (E2E)", () => { |----------|-----------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Instruct (não-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | | Stop instruct | `2` | stdout vazio; motivo no stderr | | Allow | `0` | string vazia | ### Configuração do Vitest -Os testes E2E utilizam `vitest.config.e2e.mts` com: +Os testes E2E usam `vitest.config.e2e.mts` com: -- `environment: "node"` — sem globals de browser -- `pool: "forks"` — isolamento real de processos (os testes iniciam subprocessos) -- `testTimeout: 20_000` — 20s por teste (inicialização do binário + avaliação do hook) +- `environment: "node"` - sem necessidade de globals do navegador +- `pool: "forks"` - isolamento real de processos (os testes criam subprocessos) +- `testTimeout: 20_000` - 20s por teste (inicialização do binário + avaliação do hook) -O pool `forks` é importante: workers baseados em threads compartilham `globalThis`, o que pode interferir em testes que iniciam subprocessos. Forks baseados em processos evitam esse problema. +O pool `forks` é importante: workers baseados em threads compartilham `globalThis`, o que pode interferir com testes que criam subprocessos. Forks baseados em processos evitam esse problema. --- @@ -257,4 +257,4 @@ O pool `forks` é importante: workers baseados em threads compartilham `globalTh A execução completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) deve passar antes de qualquer merge. O conjunto de testes E2E é executado como um job de CI separado, em paralelo. -Consulte [Contributing](../CONTRIBUTING.md) para o checklist completo de pré-merge. \ No newline at end of file +Consulte [Contributing](../CONTRIBUTING.md) para o checklist completo pré-merge. \ No newline at end of file diff --git a/docs/ru/agenteye/alerts.mdx b/docs/ru/agenteye/alerts.mdx index 4126172f..c4266ad1 100644 --- a/docs/ru/agenteye/alerts.mdx +++ b/docs/ru/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "Оповещения" -description: "Узнайте о проблеме в тот момент, когда она возникает, в канале, который уже смотрит ваша команда, вместо того чтобы услышать об этом от клиента." +description: "Узнайте в тот момент, когда что-то выходит за допустимые пределы, в канале, который уже отслеживает ваша команда, вместо того чтобы узнать об этом от клиента." --- -Узнайте о проблеме в тот момент, когда она возникает, в канале, который уже смотрит ваша команда, вместо того чтобы услышать об этом от клиента. Установите правило один раз, и Failproof AI Observability будет проверять его по расписанию, затем отправит вам уведомление по электронной почте, Slack, webhook или прямо в панель управления. +Узнайте в тот момент, когда что-то выходит за допустимые пределы, в канале, который уже отслеживает ваша команда, вместо того чтобы узнать об этом от клиента. Установите правило один раз, и Failproof AI Observability будет проверять его по расписанию, а затем отправит уведомление по электронной почте, Slack, webhook или прямо на панель мониторинга. -![Страница оповещений: сетка карточек правил оповещений, каждая из которых показывает триггер, окно оценки, каналы и значок серьезности (информация, предупреждение или критический уровень)](/agenteye/images/alerts.png) -*Все правила оповещений с первого взгляда: что они контролируют, как часто, куда отправляются уведомления и как срочны.* +![Страница оповещений: сетка карточек правил оповещений, каждая показывает триггер, окно оценки, каналы и значок серьезности (информация, предупреждение или критическое)](/agenteye/images/alerts.png) +*Каждое правило оповещения с первого взгляда: что оно отслеживает, как часто, куда отправляет уведомления и насколько это срочно.* -## Узнайте о проблемах прежде, чем о них узнают пользователи +## Узнавайте о проблемах раньше пользователей -Прекратите обновлять панель управления в надежде поймать регрессию. Установите оповещение для любого сигнала, о котором вы хотели бы узнать даже когда никто не смотрит, и доставьте его туда, где уже находится ваша команда: +Перестаньте обновлять панель мониторинга в надежде поймать регрессию. Используйте оповещение, когда есть сигнал, о котором вы хотите узнать даже когда никто не смотрит, и получайте его там, где вы уже находитесь: -- **По электронной почте** тем, кому нужно знать. -- **В Slack** с расширенным сообщением и кнопкой, которая прямо переводит на инцидент. -- **По webhook** в виде JSON POST для PagerDuty, Opsgenie или собственной конечной точки с опциональной сигнатурой, чтобы получатель мог доверять источнику. -- **В панели управления** — по умолчанию без уведомлений для тех случаев, когда вы настраиваете правило и еще не хотите никого беспокоить. +- **Электронная почта**, тем, кому нужно знать. +- **Slack**, форматированное сообщение с кнопкой, которая ведет прямо на инцидент. +- **Webhook**, JSON POST для PagerDuty, Opsgenie или вашего собственного эндпоинта, с дополнительной подписью, чтобы получатель мог ему доверять. +- **На панели мониторинга**, ненавязчиво по умолчанию, для случаев когда вы настраиваете правило и не хотите беспокоить никого. -Прикрепите любую комбинацию к одному правилу, и его серьезность (информация, предупреждение или критический уровень) будет передана вместе, чтобы срочные оповещения выглядели как срочные. +Подключите любую комбинацию к одному правилу, и его серьезность (информация, предупреждение или критическое) будет соответствующей, чтобы срочные оповещения выглядели срочными. -## Создавайте правило в форме, а не в JSON +## Создавайте правило с помощью формы, а не JSON -Вы описываете, что означает «сбой», в форме, а Failproof AI Observability создает базовое правило за вас. JSON спецификация — это просто то, что создает эта форма под капотом, поэтому вы можете его прочитать, чтобы понять правило, но редко вводите его вручную. +Вы описываете, что означает "неисправность", в форме, а Failproof AI Observability написал базовое правило за вас. JSON-спецификация — это просто то, что производит эта форма под капотом, поэтому вы можете прочитать его, чтобы понять правило, но редко его пишите. -![Форма нового оповещения: имя и описание, переключатель включения и выбор триггера с предложениями порога метрики, пользовательского SQL, оценки оценивания, составного оценивания и условий для каждого события](/agenteye/images/alert-new.png) -*Выберите триггер и форма заменит нужные поля; нажмите Сохранить.* +![Форма нового оповещения: имя и описание, переключатель включения и выбор триггера, предлагающий пороги метрик, пользовательский SQL, оценку оценивания, составную оценку и условия для каждого события](/agenteye/images/alert-new.png) +*Выберите триггер, и форма подставит нужные поля; сохранение написывает правило.* -Быстрый путь прост: дайте имя, выберите **триггер** (что контролировать), установите **пороговое значение и окно** (насколько плохо, в течение какого времени), прикрепите по крайней мере один **канал**, затем **Сохраните** и нажмите **Тест**, чтобы отправить синтетическое уведомление и подтвердить, что все назначения настроены правильно. Под капотом это создает небольшую спецификацию вроде: +Быстрый путь прост: назовите его, выберите **триггер** (что отслеживать), установите **пороги и окно** (насколько плохо, на какой период), подключите хотя бы один **канал**, затем **сохраните** и нажмите **тест**, чтобы отправить синтетическое уведомление и подтвердить, что каждый адресат настроен правильно. Под капотом это создает небольшую спецификацию вроде: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -Вы не ограничены одним видом сигнала. Выберите триггер, который соответствует тому, как вы думаете об ошибке: +Вы не ограничены одним типом сигнала. Выберите триггер, который соответствует вашему представлению об отказе: -| Триггер | Срабатывает, когда | +| Триггер | Срабатывает когда | |---|---| -| **Порог метрики** | заданная метрика (частота ошибок, задержка p95 или p99, количество событий или ошибок, трата токенов) пересекает вашу линию в течение окна | -| **Пользовательский SQL** | ваш собственный запрос только для чтения возвращает строку, или вычисленное им значение пересекает пороговое значение | -| **Оценка оценивания** | среднее значение оценки оценивающего (например, галлюцинация) пересекает пороговое значение | -| **Составное оценивание** | несколько проверок оценки объединяются логикой any, all или at-least-N, чтобы поймать регрессию, которая проявляется только в разных оценках | -| **Для каждого события** | приходит одно соответствующее событие: конкретный агент, конкретный тип ошибки или подстрока сообщения | +| **Пороги метрик** | предустановленная метрика (частота ошибок, p95 или p99 задержка, количество событий или ошибок, трата токенов) пересекает ваш предел на протяжении окна | +| **Пользовательский SQL** | ваш собственный запрос только для чтения возвращает строку, или значение, которое он вычисляет, пересекает пороги | +| **Оценка оценивания** | среднее оценка оценивателя (например, галлюцинация) пересекает пороги | +| **Составная оценка** | несколько проверок оценок объединяются с логикой any, all или at-least-N, чтобы поймать регрессию, которая проявляется только на нескольких оценках | +| **Для каждого события** | приходит одно подходящее событие: конкретный агент, конкретный тип ошибки или подстрока сообщения | -Уже смотрите на сбой на [странице Ошибок](/ru/agenteye/error-tracking)? Каждая строка там имеет кнопку **+ оповещение**, которая открывает эту же форму предварительно заполненную, чтобы поймать эту точную ошибку снова, так что инцидент, который вы только что разобрали, станет тем, который вас предупредит в следующий раз. +Уже смотрите на отказ на [странице ошибок](/ru/agenteye/error-tracking)? Каждая строка там имеет кнопку **+ оповещение**, которая открывает эту же форму предзаполненную для того, чтобы поймать эту точно такую же ошибку снова, поэтому инцидент, который вы только что обработали, станет тем, который вас разбудит в следующий раз. -**Где это найти:** Оповещения находятся по адресу `//alerts`. Создание, редактирование, удаление и тестирование правил требует **`alerts:write`**; `alerts:read` достаточно для просмотра. Выбор получателя показывает членов вашей организации по имени, поэтому вы можете отправить уведомление человеку, не выходя из формы. +**Где это найти:** оповещения находятся по адресу `//alerts`. Создание, редактирование, удаление и тестирование правил требует **`alerts:write`**; `alerts:read` достаточно для просмотра. Выбор получателя отображает членов вашей организации по имени, поэтому вы можете уведомить человека не выходя из формы. -## Уведомляй меня только когда это действительно важно +## Уведомляйте меня только когда это реально -Одно плохое измерение не должно вас будить. Фильтр шума **M из N** контролирует, сколько из последних нескольких проверок должны не пройти, прежде чем оповещение действительно вас уведомит. Установите его на **3 из 5**, и правило срабатывает только после того, как оно нарушено в трех из последних пяти проверок, так что дрожащий сигнал прекращает ложные тревоги; оставьте значение по умолчанию **1 из 1**, чтобы срабатывать при первом нарушении. Вы также выбираете, как часто запускается правило, из предустановок 1m, 5m, 15m и 1h, подобранных в соответствии с тем, насколько быстро движется сигнал. +Одно плохое измерение не должно вас будить. Фильтр шума **M из N** контролирует, сколько из последних нескольких проверок должны не пройтись перед тем, как оповещение действительно вас уведомит. Установите **3 из 5**, и правило сработает только после того, как оно не пройдет три из последних пяти проверок, поэтому нестабильный сигнал перестанет вызывать ложные тревоги; оставьте значение по умолчанию **1 из 1**, чтобы сработать при первом отказе. Вы также выбираете, как часто правило работает, из предустановок 1м, 5м, 15м и 1ч, согласованных с тем, насколько быстро движется сигнал. -## Что происходит, когда срабатывает оповещение +## Что происходит при срабатывании оповещения -Нарушение открывает **инцидент** и уведомляет ваши каналы один раз. После этого ваша команда подтверждает его, назначает владельца, обсуждает и разрешает, все с чистой атрибутированной записью. Этот рабочий процесс сортировки имеет свой собственный дом: см. [Инциденты](/ru/agenteye/incidents). +Отказ открывает **инцидент** и уведомляет ваши каналы один раз. Оттуда ваша команда подтверждает его, назначает владельца, обсуждает его и разрешает его, все это против чистого, атрибутированного записи. Этот рабочий процесс обработки имеет свой собственный дом: см. [Инциденты](/ru/agenteye/incidents). ## Связанное -- [Инциденты](/ru/agenteye/incidents): отслеживайте срабатывающее оповещение от открытия до подтверждения до разрешения. -- [Отслеживание ошибок](/ru/agenteye/error-tracking): группируйте ошибки агентов и повысьте одну до оповещения в один клик. -- [Панели управления](/ru/agenteye/dashboards): смотрите общие доски, из которых берутся пороги, для которых вы устанавливаете оповещения. -- [CLI и агенты](/ru/agenteye/cli-and-agents): создавайте оповещения и подтверждайте инциденты из терминала, или встраивайте их в CI. \ No newline at end of file +- [Инциденты](/ru/agenteye/incidents): отслеживайте срабатывающее оповещение от открытия к подтверждению к разрешению. +- [Отслеживание ошибок](/ru/agenteye/error-tracking): группируйте отказы агентов и повышайте один до оповещения в один клик. +- [Панели мониторинга](/ru/agenteye/dashboards): смотрите общие доски, пороги которых вы уведомляете, исходят из. +- [CLI и агенты](/ru/agenteye/cli-and-agents): создавайте оповещения и подтверждайте инциденты из терминала, или включайте их в CI. \ No newline at end of file diff --git a/docs/ru/agenteye/api-keys.mdx b/docs/ru/agenteye/api-keys.mdx index 8051a6b6..628d801c 100644 --- a/docs/ru/agenteye/api-keys.mdx +++ b/docs/ru/agenteye/api-keys.mdx @@ -1,105 +1,106 @@ --- +--- title: "API ключи" -description: "API ключи контролируют, кто и что может получить доступ к вашему серверу Failproof AI Observability, позволяя коллектору отправлять события без предоставления прав на чтение или администрирование." +description: "API ключи контролируют, кто и что может получить доступ к серверу Failproof AI Observability, позволяя collector отправлять события без получения прав на чтение или администрирование." --- -API ключи контролируют, кто и что может получить доступ к вашему серверу Failproof AI Observability, позволяя коллектору отправлять события без предоставления прав на чтение или администрирование. Каждый ключ имеет одно или несколько разрешений, и каждое разрешение ограничивает доступ к определённым маршрутам сервера; вы даёте только те разрешения, которые необходимы для работы. В большинстве развёртываний требуется всего три типа ключей. +API ключи контролируют, кто и что может получить доступ к серверу Failproof AI Observability, позволяя collector отправлять события без получения прав на чтение или администрирование. Каждый ключ несет одно или несколько разрешений, и каждое разрешение ограничивает доступ к определенным маршрутам сервера; вы даете только те, которые необходимы. Большинство развертываний создают всего три типа ключей. -## Три ключа, необходимые большинству развёртываний +## 3 ключа, необходимые большинству развертываний | Ключ | Разрешения | Кто его использует | |---|---|---| -| Ключ коллектора | `events:add` | `agenteye-collector` на каждой машине агента для отправки событий. | -| Ключ для чтения панели управления | `events:read`, `keys:read` | Оператор только для чтения или интеграция, которая запрашивает данные без их изменения. | -| Ключ начальной загрузки администратора | все разрешения | Оператор, который впервые запускает экземпляр (и панель управления). Инициализируется из переменной окружения `ADMIN_KEY`. Смотрите [Ключ начальной загрузки администратора](#bootstrap-admin-key). | +| Ключ сборщика | `events:add` | `agenteye-collector` на каждой машине агента для отправки событий. | +| Ключ чтения панели | `events:read`, `keys:read` | Оператор, доступный только для чтения, или интеграция, которая запрашивает данные без их изменения. | +| Начальный ключ администратора | все разрешения | Оператор, который впервые развертывает экземпляр (и панель). Инициализируется из переменной окружения `ADMIN_KEY`. См. [Начальный ключ администратора](#начальный-ключ-администратора). | -Начните отсюда. Обращайтесь к полному каталогу разрешений ниже только если вам нужен узкоспециализированный ключ с пользовательской областью действия. Смотрите также [Рекомендуемая структура ключей](#recommended-key-layout) и [Создание ключей](#creating-keys). +Начните отсюда. Обратитесь к полному каталогу разрешений ниже только когда вам нужен более узкий, пользовательский ключ. См. также [Рекомендуемая структура ключей](#рекомендуемая-структура-ключей) и [Создание ключей](#создание-ключей). --- ## Разрешения -Сервер обеспечивает фиксированный каталог разрешений; каждое из них ограничивает доступ к определённым HTTP маршрутам. **Ключ администратора** содержит все разрешения; ограниченный ключ содержит подмножество, которое вы предоставляете при создании. Неизвестные строки разрешений отклоняются при создании ключа. +Сервер применяет фиксированный каталог разрешений; каждое из них ограничивает доступ к определенным HTTP маршрутам. **Ключ администратора** содержит все из них; обусловленный ключ содержит подмножество, которое вы предоставляете при создании. Неизвестные строки разрешений отклоняются при создании ключа. -> **Примечание:** Два действительных разрешения предназначены только для человека/панели управления и не могут быть предоставлены API ключу: `orgs:admin` (администрирование экземпляра, только для операторов) и `keys:update`. Запрос `POST /keys` или `PATCH /keys/:id`, пытающийся предоставить любое из них, отклоняется с кодом HTTP 422. Смотрите строку `keys:update` ниже, чтобы понять, почему ключ-носитель может создавать ключи, но никогда их не редактирует. +> **Примечание:** Два допустимых разрешения предназначены только для людей/панели и не могут быть предоставлены API ключу: `orgs:admin` (администрирование экземпляра, только для операторов) и `keys:update`. Запрос к `POST /keys` или `PATCH /keys/:id`, который пытается предоставить одно из них, отклоняется с HTTP 422. См. строку `keys:update` ниже, чтобы понять, почему ключ-носитель может создавать ключи, но не может их редактировать. -### Приём и запрос событий +### Прием и запрос событий | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `events:add` | `POST /events` | Приём пакетов событий от коллектора. Единственное разрешение, которое нужно коллектору. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Запрос событий, список известных окружений, список идентификаторов моделей в данных (используется представлением Models и фильтрами моделей), расчёт агрегированной задержки, которая питает тепловую карту / полосы процентилей, и экспорт сеанса в JSONL. Общие конечные точки фильтров `GET /events/environments` и `GET /events/agent_ids` доступны с **либо** `events:read` **либо** `evaluations:read`, так что страница сеансов (ограниченная `evaluations:read`) переиспользует те же грани для каждой организации. `GET /events/models` не является одной из них: требует `events:read`, поэтому участник, имеющий только `evaluations:read`, получает 403 от неё. | +| `events:add` | `POST /events` | Прием пакетов событий от сборщика. Единственное разрешение, которое нужно сборщику. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Запрос событий, список известных окружений, список идентификаторов моделей, видимых в данных (используется представлением «Модели» и фильтрами моделей), вычисление агрегата задержки, который питает тепловую карту / полосу процентиля, и экспорт сеанса как JSONL. Общие конечные точки фасета строки фильтра `GET /events/environments` и `GET /events/agent_ids` доступны при наличии **либо** `events:read` **либо** `evaluations:read`, поэтому страница сеансов (с воротами `evaluations:read`) использует один и тот же фасет для каждой организации. `GET /events/models` не является одним из них: требуется `events:read`, поэтому субъект, имеющий только `evaluations:read`, получает от него 403. | ### Сеансы и оценки | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Список сеансов, чтение результатов оценки, свёрнутое здоровье оценки, используемое панелями управления, и состояние очереди рабочих заданий оценки. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Ручной расчёт переоценки для завершённого сеанса. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Список сеансов, чтение результатов оценки, свернутое здоровье оценки, используемое панелями, и состояние очереди обработки задания оценки. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Ручная постановка в очередь переоценки для завершенного сеанса. | -### Панели управления +### Панели | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Список панелей управления, загрузка одной и чтение её плиток. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Создание и редактирование панелей управления, добавление / редактирование / удаление плиток и переупорядочение сетки плиток. | -| `dashboards:delete` | `DELETE /dashboards/:id` | Удаление всей панели управления (удаление на уровне плиток находится под `dashboards:write`). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Список панелей, загрузка одной и чтение ее плиток. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Создание и редактирование панелей, добавление / редактирование / удаление плиток и переупорядочение сетки плиток. | +| `dashboards:delete` | `DELETE /dashboards/:id` | Удаление целой панели (удаление на уровне плиток находится под `dashboards:write`). | -### Сохранённые запросы (SQL редактор) +### Сохраненные запросы (SQL композитор) | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Список сохранённых запросов, загрузка одного и проверка схемы только для чтения, которая используется редактором. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | Создание и редактирование сохранённых запросов. SQL по-прежнему маршрутизируется через ту же роль только для чтения и охранявшие проверки SQL, что и вызов `queries:run`. | -| `queries:delete` | `DELETE /queries/:id` | Удаление сохранённого запроса. | -| `queries:run` | `POST /queries/run` | Выполнение сохранённых или произвольных SQL запросов против роли только для чтения, используемой редактором. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Список сохраненных запросов, загрузка одного и проверка схемы только для чтения, на которую ориентирован композитор. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | Создание и редактирование сохраненных запросов. SQL все еще маршрутизируется через ту же роль только для чтения и защищенные проверки SQL, что и вызов `queries:run`. | +| `queries:delete` | `DELETE /queries/:id` | Удаление сохраненного запроса. | +| `queries:run` | `POST /queries/run` | Выполнение сохраненного или специального SQL против роли только для чтения, используемой композитором. | ### AI ассистент | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Общение с AI ассистентом и управление вашими собственными (приватными) разговорами. Требуется для **пользователя** увидеть панель ассистента; собственный ключ ассистента `dashboard-assistant` и инициализируется отдельно (смотрите ниже). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Общение с AI ассистентом и управление своими (приватными) беседами. Требуется у **пользователя**, чтобы увидеть док ассистента; собственный ключ ассистента — `dashboard-assistant` и инициализируется отдельно (см. ниже). | ### API ключи | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `keys:create` | `POST /keys` | Создание нового ограниченного API ключа. **Не** предоставляет редактирование разрешений существующего ключа (это `keys:update`). | +| `keys:create` | `POST /keys` | Создание нового обусловленного API ключа. **Не** предоставляет редактирование разрешений существующего ключа (это `keys:update`). | | `keys:read` | `GET /keys` | Список существующих ключей. Секреты никогда не возвращаются этой конечной точкой. | -| `keys:update` | `PATCH /keys/:id` | Редактирование разрешений существующего ключа. **Разрешение только для человека/панели управления**; не может быть назначено API ключу (ключ-носитель может создавать ключи, но никогда их не редактирует). | -| `keys:disable` | `POST /keys/:id/disable` | Отозвание ключа. Защищённые ключи (`admin`, `dashboard-assistant`) не могут быть отключены; ротируйте их через переменную окружения + перезагрузка. | -| `keys:regenerate` | `POST /keys/:id/regenerate` | Ротация секрета ключа. Защищённые ключи не могут быть восстановлены через этот маршрут. | +| `keys:update` | `PATCH /keys/:id` | Редактирование разрешений существующего ключа. Разрешение **только для людей/панели**; не может быть назначено API ключу (ключ-носитель может создавать ключи, но не может их редактировать). | +| `keys:disable` | `POST /keys/:id/disable` | Отзыв ключа. Защищенные ключи (`admin`, `dashboard-assistant`) не могут быть отключены; поверните их через переменную окружения + перезагрузку. | +| `keys:regenerate` | `POST /keys/:id/regenerate` | Ротация секрета ключа. Защищенные ключи не могут быть переиспользованы через этот маршрут. | -### Пользователи панели управления +### Пользователи панели | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | Приглашение нового пользователя панели управления (отправляет электронное письмо + одноразовый код доступа (OTP)) и чтение набора разрешений по умолчанию, настроенного панелью управления, используемого при заполнении формы приглашения. | +| `users:create` | `POST /users`, `GET /users/defaults` | Приглашение нового пользователя панели (отправляет email + одноразовый пароль (OTP) для входа) и чтение набора разрешений по умолчанию, настроенного панелью, используемого при заполнении формы приглашения. | | `users:read` | `GET /users`, `GET /users/:id` | Список пользователей и загрузка одной записи пользователя. | -| `users:update` | `PUT /users/:id` | Редактирование разрешений пользователя. Обновления отправляют электронное письмо об изменении разрешений затронутому пользователю и вступают в силу при его следующем запросе; повторный вход не требуется. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Отключение пользователя (немедленно отзывает его сеансы) и повторное включение ранее отключённого пользователя. | +| `users:update` | `PUT /users/:id` | Редактирование разрешений пользователя. Обновления отправляют email об изменении разрешений затронутому пользователю и вступают в силу при его следующем запросе; переввод не требуется. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Отключение пользователя (немедленно отзывает его сеансы) и повторное включение ранее отключенного пользователя. | -Эти разрешения поддерживают страницу панели управления **Пользователи**, где предоставленные области действия каждого участника отображаются в виде чипов: +Эти разрешения поддерживают страницу **Пользователи** панели, где показаны предоставленные каждому участнику области как чипы: -![Страница Пользователи: карточка на каждого пользователя панели управления с его электронной почтой, предоставленными разрешениями и элементами управления редактированием/отключением](/agenteye/images/users.png) +![Страница «Пользователи»: карточка на пользователя панели с их email, предоставленными разрешениями и элементами управления редактированием/отключением](/agenteye/images/users.png) ### Операционные параметры | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Просмотр операционных параметров, управляемых панелью управления, и их метаданных; список переопределений окна контекста для каждой модели; и разрешение эффективного окна для модели. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Редактирование операционных параметров и добавление, изменение или удаление переопределений окна контекста для каждой модели. Изменения влияют на новые события без перезагрузки сервера. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Просмотр параметров операционной сети, управляемых панелью, и их метаданных; список переопределений окна контекста для каждой модели; и разрешение эффективного окна для модели. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Редактирование параметров операционной сети и добавление, изменение или удаление переопределений окна контекста для каждой модели. Изменения влияют на новые события без перезагрузки сервера. | -![Страница параметров: операционные параметры, управляемые панелью управления, такие как разрешённые входы и время жизни сеанса/OTP, редактируемые без перезагрузки](/agenteye/images/settings.png) +![Страница параметров: параметры операционной сети, управляемые панелью, такие как разрешенные входы и время жизни сеанса/OTP, редактируемые без перезагрузки](/agenteye/images/settings.png) ### Оповещения и инциденты | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| | `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Просмотр настроенных определений оповещений. | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Создание, редактирование, удаление и тестовое срабатывание определений оповещений. | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Просмотр инцидентов и их тактики сортировки. | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Создание, редактирование, удаление и тестовый запуск определений оповещений. | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Просмотр инцидентов и их пути сортировки. | | `incidents:write` | `POST /alerts/:id/incidents` | Ручное открытие инцидента против существующего оповещения. | | `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Подтверждение, назначение, разрешение и комментирование инцидентов. | @@ -107,67 +108,67 @@ API ключи контролируют, кто и что может получ | Разрешение | HTTP маршруты | Что это позволяет | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Просмотр определений аудитов, истории запусков и результатов. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Создание, редактирование, удаление и запуск аудитов; сортировка результатов (подтверждение / отключение звука / отклонение / разрешение / повторное открытие / назначение). | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Просмотр определений аудитов, истории запусков и выводов. | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Создание, редактирование, удаление и запуск аудитов; сортировка выводов (подтверждение / отключение / отклонение / разрешение / переоткрытие / назначение). | -> **Примечание:** Чтобы дать ключу поверхность аудита, явно предоставьте `audits:*`. Смотрите [Примечания об обновлении и обратной совместимости](#upgrade-and-backward-compatibility-notes), чтобы узнать, как существующие получатели были мигрированы при появлении Audits. +> **Примечание:** Чтобы дать ключу поверхность аудита, явно предоставьте `audits:*`. См. [Примечания об обновлении и обратной совместимости](#примечания-об-обновлении-и-обратной-совместимости) для того, как существующие получатели были перенесены при поставке аудитов. -> Конечная точка средства выбора получателей `GET /alerts/recipients` (в которой указаны адреса электронной почты участников, которых редактор оповещений может уведомить), доступна держателем **либо** `alerts:read` **либо** `alerts:write`, так что редакторы оповещений могут заполнить средство выбора без предоставления `users:read`. +> Конечная точка выбора получателя `GET /alerts/recipients` (которая перечисляет email участников, которых может уведомить редактор оповещения) доступна держателю **либо** `alerts:read` **либо** `alerts:write`, поэтому редакторы оповещений могут заполнить выбор без предоставления `users:read`. -> Просмотрелю панели управления требуется **как** `dashboards:read` (для загрузки сохранённых представлений), так и `evaluations:read` (показатели здоровья вычисляются из данных оценки). Предоставьте `dashboards:write` для позволить пользователю создавать или редактировать панели управления, и `dashboards:delete` для их удаления. +> Зритель панелей нуждается в **обоих** `dashboards:read` (для загрузки сохраненных представлений) и `evaluations:read` (метрики здоровья вычисляются из данных оценки). Предоставьте `dashboards:write`, чтобы позволить пользователю создавать или редактировать панели, и `dashboards:delete`, чтобы их удалять. -> `/health` и `/auth/*` (запрос OTP, проверка OTP, проверка сеанса, выход) по замыслу не требуют аутентификации; это процесс входа и проверка работоспособности. `GET /access-granters` требует действительный ключ, но без конкретного разрешения, поэтому любой зарегистрировавшийся пользователь может увидеть, какие администраторы могут контактировать об изменениях доступа. +> `/health` и `/auth/*` (OTP запрос, OTP проверка, проверка сеанса, выход) без аутентификации по конструкции; это поток входа и проверка живости. `GET /access-granters` требует действительный ключ, но никакое конкретное разрешение, поэтому любой вошедший пользователь может увидеть, какие администраторы нужно контактировать об изменениях доступа. --- ## Наборы разрешений -Наборы разрешений позволяют применить именованную роль вместо выбора отдельных токенов каждый раз. Вместо выбора десятка разрешений один за другим для каждого нового пользователя панели управления или API ключа вы выбираете набор, и все назначенные ему получают последовательное, проверяемое право. Редактирование пользовательского набора повторно применяет новое право каждому пользователю, уже назначенному ему, так что изменение роли — это один edit вместо обхода каждого участника. +Наборы разрешений позволяют применить именованную роль вместо ручного выбора отдельных токенов каждый раз. Вместо выбора дюжины разрешений один за другим для каждого нового пользователя панели или API ключа, вы выбираете набор, и каждый, назначенный ему, получает согласованный, проверяемый грант. Редактирование пользовательского набора повторно применяет новый грант каждому уже назначенному пользователю, поэтому изменение роли — это одно редактирование, а не проход через каждого участника. -Каждая организация инициализируется с тремя встроенными наборами: +Каждая организация инициализируется тремя встроенными наборами: -| Набор | Разрешения | Предназначен для | +| Набор | Разрешения | Предназначено для | |---|---|---| -| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Доступ только для просмотра ко всей операционной поверхности. | -| `standard` | всё из `read-only`, плюс `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Только для чтения плюс повседневные действия дежурного: запуск запросов, переоценка сеансов, подтверждение инцидентов и использование AI ассистента. | +| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Доступ только для просмотра на всех операционных поверхностях. | +| `standard` | все в `read-only`, плюс `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Доступ только для чтения плюс повседневные действия по вызовам: запуск запросов, переоценка сеансов, подтверждение инцидентов и использование AI ассистента. | | `admin` | каждое назначаемое разрешение | Полный контроль над организацией. | -Три встроенных набора **неизменяемы**; их имена всегда означают одно и то же, поэтому `read-only`, `standard` и `admin` безопасны для ссылки в политике и адаптации. Оператор может создавать дополнительные **пользовательские наборы** для моделирования ролей, специфичных для вашей организации (например, роль документ создателя или роль только-коллектора). +Три встроенных набора **неизменяемы**; их имена всегда означают одно и то же, поэтому `read-only`, `standard` и `admin` безопасны для ссылок в политике и подготовке. Оператор может создать дополнительные **пользовательские наборы** для моделирования ролей, специфичных для вашей организации (например, роль «автор панели» или «только сборщик»). -Наборы находятся на панели управления и управляются через API по адресу `GET /permission-sets` (список, ограничен `users:read`) и `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (создание, редактирование, удаление пользовательского набора, ограничено `settings:write`). Удаление или редактирование встроенного набора отклоняется. +Наборы отображаются на панели и управляются по API на `GET /permission-sets` (список, с воротами `users:read`) и `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (создание, редактирование, удаление пользовательского набора, с воротами `settings:write`). Попытка удалить или отредактировать встроенный набор отклоняется. -Членство в наборе поддерживает две другие функции: +Принадлежность к набору — это то, что поддерживает две другие функции: -- **`DEFAULT_USER_PERMISSIONS`** (право, предварительно выбранное, когда администратор открывает **+ новый пользователь**) по умолчанию использует набор `standard`. -- **Флаг `--set`** на `agenteye-orgctl` (управление участниками организации) запускает участника из именованного набора, который вы затем можете точно настроить с помощью `--add` / `--remove`. +- **`DEFAULT_USER_PERMISSIONS`** (грант, предварительно выбранный при открытии администратором **+ новый пользователь**) по умолчанию использует набор `standard`. +- **Флаг `--set`** на `agenteye-orgctl` (управление участниками операторов) начинает участника из именованного набора, который затем вы уточняете с помощью `--add` / `--remove`. -> **Примечание:** Если набор включает разрешение, которое не может быть назначено ключу (например, пользовательский набор, несущий `keys:update`), инициализация ключа из этого набора отбрасывает неназначаемые токены; сервер иначе отклонил бы ключ с HTTP 422. Пользователи панели управления не подвергаются этому ограничению. +> **Примечание:** Когда набор включает разрешение, которое не может быть назначено ключу (например пользовательский набор с `keys:update`), инициализация ключа из этого набора отбрасывает неназначаемые токены; сервер в противном случае отклонил бы ключ с HTTP 422. Пользователи панели не подчиняются этому ограничению. --- -## Ключ начальной загрузки администратора +## Начальный ключ администратора -Ключ администратора — это единственная корневая учётная данные, которая позволяет оператору запустить доступ с нуля: с его помощью вы можете создавать каждый другой ограниченный ключ, приглашать первых пользователей панели управления и настраивать экземпляр до того, как будет существовать другой ключ. Это единственный ключ, который вы не создаёте через API ключей; он подготавливается из окружения, чтобы сервер был доступен при первой загрузке. +Ключ администратора — это единственное корневое учетное данные, позволяющее оператору создать доступ с нуля: с его помощью вы можете создавать все остальные обусловленные ключи, приглашать первых пользователей панели и настраивать экземпляр до того, как какой-либо другой ключ существует. Это единственный ключ, который вы не создаете через API ключей; он подготавливается из окружения, так что сервер доступен при первой загрузке. -Установите переменную окружения `ADMIN_KEY` на сервере. При каждом запуске сервер обновляет это значение как ключ администратора со всеми разрешениями. +Установите переменную окружения `ADMIN_KEY` на сервере. При каждом запуске сервер вставляет это значение как ключ администратора со всеми разрешениями. -Для ротации: измените `ADMIN_KEY` на новый секрет и перезагрузите сервер. +Чтобы ротировать: измените `ADMIN_KEY` на новый секрет и перезагрузите сервер. --- ## Область действия организации -**Организации сами создаются и управляются вне записей этого API ключей оператором.** Жизненный цикл организации и участника (создание / переименование / удаление / очистка организации; добавление / обновление / удаление участника) выполняется с помощью **CLI `agenteye-orgctl`**; нет HTTP API или кнопки панели управления для этого. Что **остаётся** неизменным: **ключи API для каждой организации по-прежнему создаются на панели управления (или через этот API ключей)** членами организации. +**Организации сами создаются и управляются оператором вне этого API ключей.** Жизненный цикл организации и члена (создание / переименование / удаление / очистка организации; добавление / обновление / удаление члена) выполняется с помощью CLI **`agenteye-orgctl`**; нет HTTP API или кнопки панели для этого. Что остается без изменений: **API ключи для каждой организации по-прежнему создаются на панели (или через этот API ключей)** членами организации. -В развёртывании с несколькими организациями каждый ключ, который создаёт член организации (через этот API ключей или страницу панели управления **Ключи**), принадлежит **одной организации** и может только читать или писать данные этой организации; организация отмечена на ключе при создании и обеспечивается при каждом запросе. Два ключа начальной загрузки — единственное исключение: ключ `admin` (инициализирован из `ADMIN_KEY`) и ключ `dashboard-assistant` (инициализирован из `AGENT_API_KEY`) — это **ключи области действия экземпляра** (они не имеют организации). Панель управления аутентифицируется с помощью ключа `admin`, чтобы она могла прокси-запросы для каждой организации от имени вошедших участников. Развёртывания на одного арендатора не должны об этом думать; все ключи принадлежат встроенной организации `default`. +В развертывании с несколькими организациями каждый ключ, созданный членом организации (через этот API ключей или страницу панели **Ключи**), принадлежит **одной организации** и может только читать или писать данные той организации; организация штампуется на ключе при создании и применяется при каждом запросе. Два начальных ключа — единственное исключение: ключ `admin` (инициализированный из `ADMIN_KEY`) и ключ `dashboard-assistant` (инициализированный из `AGENT_API_KEY`) — это **ключи уровня экземпляра** (они не несут организации). Панель аутентифицируется с ключом `admin`, чтобы она могла прокси-запросы для каждой организации от имени вошедших участников. Развертывания с единственным клиентом не должны об этом думать; все ключи принадлежат встроенной организации `default`. --- ## Создание ключей -Используйте ключ администратора (или любой ключ с разрешением `keys:create`) для создания дополнительных ограниченных ключей. +Используйте ключ администратора (или любой ключ с разрешением `keys:create`) для создания дополнительных обусловленных ключей. -### Ключ коллектора (только приём) +### Ключ сборщика (только прием) ```bash curl -s -X POST http://your-server/keys \ @@ -180,7 +181,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### Ключ панели управления (только чтение) +### Ключ панели (только чтение) ```bash curl -s -X POST http://your-server/keys \ @@ -193,7 +194,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -При создании ключа через HTTP API вы предоставляете значение `key` сами; выберите сильный секрет и храните его безопасно. (Панель управления работает иначе: она генерирует сильный секрет для вас и показывает его один раз при создании; смотрите [Управление ключами в панели управления](#key-management-in-the-dashboard).) Ответ подтверждает, что ключ был создан: +Когда вы создаете ключ через HTTP API, вы сами предоставляете значение `key`; выберите сильный секрет и храните его безопасно. (Панель работает по-другому: она генерирует для вас сильный секрет и показывает его один раз при создании; см. [Управление ключами на панели](#управление-ключами-на-панели).) Ответ подтверждает, что ключ был создан: ```json { @@ -206,14 +207,14 @@ curl -s -X POST http://your-server/keys \ --- -## Перечисление ключей +## Список ключей ```bash curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -Секреты ключей не возвращаются в ответах списков, только ID, имена и разрешения. +Секреты ключей не возвращаются в ответах списка, только ID, имена и разрешения. --- @@ -228,26 +229,26 @@ curl -s -X POST http://your-server/keys//disable \ --- -## Восстановление ключа +## Переиспользование ключа -Генерирует новый секрет для существующего ключа. Старый секрет немедленно становится недействительным. +Генерирует новый секрет для существующего ключа. Старый секрет немедленно инвалидируется. ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -Ответ включает новый открытый секрет, **показанный только один раз**. +Ответ включает новый открытый текст секрета, **показанный только один раз**. --- -## Управление ключами в панели управления +## Управление ключами на панели -Страница **Ключи** в панели управления предоставляет UI для всех вышеупомянутых операций. Вам нужен ключ с разрешением `keys:read` для просмотра списка, и `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` для действий создания / редактирования / отключения / восстановления соответственно. Редактирование разрешений ключа (`keys:update`) отделено от создания одного (`keys:create`), так что вы можете предоставить оператору возможность создавать ключи без возможности переопределения существующих, или наоборот. Ключ администратора охватывает все это. +Страница **Ключи** на панели предоставляет пользовательский интерфейс для всех вышеперечисленных операций. Вам нужен ключ с разрешением `keys:read`, чтобы просмотреть список, и `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` для действий создания / редактирования / отключения / переиспользования соответственно. Редактирование разрешений ключа (`keys:update`) отделено от создания одного (`keys:create`), поэтому вы можете предоставить оператору возможность создавать ключи без возможности переопределения существующих, или наоборот. Ключ администратора охватывает все это. -При создании ключа с панели управления вы не предоставляете секрет; панель управления генерирует сильный секрет для вас и отображает его **один раз** при создании. Скопируйте его немедленно и храните безопасно; он никогда не будет показан снова, точно как при восстановлении. Вы всё ещё можете выбрать разрешения ключа непосредственно или инициализировать их из набора разрешений (смотрите ниже). +Когда вы создаете ключ с панели, вы не предоставляете секрет; панель генерирует для вас сильный секрет и отображает его **один раз** при создании. Скопируйте его немедленно и храните безопасно; он никогда больше не показывается, как при переиспользовании. Вы по-прежнему можете выбрать разрешения ключа напрямую или инициализировать их из набора разрешений (см. ниже). -![Страница API ключей: карточка на каждый ключ с его именем, предоставленными разрешениями и временем создания, с действиями восстановления и отключения; защищённые ключи, такие как `admin`, отмечены](/agenteye/images/api-keys.png) +![Страница API ключей: карточка на ключ, показывающая его имя, предоставленные разрешения и время создания, с действиями переиспользования и отключения; защищенные ключи, такие как `admin`, отмечены](/agenteye/images/api-keys.png) --- @@ -255,26 +256,26 @@ curl -s -X POST http://your-server/keys//regenerate \ | Ключ | Разрешения | Используется | |---|---|---| -| `admin` (начальная загрузка через переменную окружения `ADMIN_KEY`) | все | Ops/установка и панель управления (аутентифицируется с `ADMIN_KEY`, прокси-запросы пользователей с проверками разрешений) | -| Ключ коллектора для каждого хоста | `events:add` | Коллектор на каждой машине агента | -| `dashboard-assistant` (начальная загрузка через переменную окружения `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI ассистент, инициализирован автоматически, **защищён**; не может быть отредактирован через API | +| `admin` (инициализация через переменную окружения `ADMIN_KEY`) | все | Операции/настройка и панель (аутентифицируется с `ADMIN_KEY`, прокси запросы пользователя с проверками разрешений) | +| Ключ сборщика для каждого хоста | `events:add` | Сборщик на каждой машине агента | +| `dashboard-assistant` (инициализация через переменную окружения `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI ассистент, инициализируется автоматически, **защищен**; не может быть отредактирован через API | | Ключ телеметрии ассистента (опционально) | `events:add` | Самоинструментирование AI ассистента, если включено | -> **Примечание:** Ключ ассистента **инициализирован автоматически** сервером из переменной окружения `AGENT_API_KEY` (тот же секрет, который агент представляет как `AGENTEYE_API_KEY`); нет ручного этапа создания ключей и нет задействованного ключа администратора. Его разрешения зафиксированы в исходном коде, поэтому область действия не может быть расширена неправильной конфигурацией: читать через события / оценки / панели управления, плюс dashboards-write и queries-read / write / run для потока автора с возможностью попросить AI написать запрос. Все SQL по-прежнему проходит через ту же роль только для чтения и охранявший путь SQL, что и написанный пользователем запрос, поэтому это расширяет *поверхность создания*, а не поверхность данных; деструктивные операции (`queries:delete`, `dashboards:delete`) намеренно остаются вне ключа ассистента. Как ключ `admin`, он **защищён**: не может быть отключен или восстановлен через API ключей, только ротирован путём изменения `AGENT_API_KEY` и перезагрузки. Пользователи панели управления дополнительно нуждаются в разрешении `agent:use` для просмотра и использования ассистента. Если вы включите самоинструментирование, дайте ассистенту отдельный ключ только для `events:add`. +> **Примечание:** Ключ ассистента **инициализируется автоматически** сервером из переменной окружения `AGENT_API_KEY` (тот же секрет, который агент предоставляет как `AGENTEYE_API_KEY`); нет ручного этапа создания ключа и никакого ключа администратора. Его разрешения зафиксированы в исходном коде, поэтому область не может быть расширена неправильной конфигурацией: чтение событий / оценок / панелей, плюс написание панелей и чтение / написание / запуск запросов для потока создания «Попросить AI написать запрос». Все SQL по-прежнему проходит через ту же роль только для чтения и защищенный путь SQL, что и пользовательский запрос, поэтому это расширяет *поверхность создания*, а не поверхность данных; деструктивные операции (`queries:delete`, `dashboards:delete`) намеренно остаются вне ключа ассистента. Как ключ `admin`, он **защищен**: не может быть отключен или переиспользован через API ключей, только ротирован изменением `AGENT_API_KEY` и перезагрузкой. Пользователи панели дополнительно нуждаются в разрешении `agent:use`, чтобы увидеть и использовать ассистента. Если вы включите самоинструментирование, дайте ассистенту отдельный ключ только с `events:add`. --- ## Примечания об обновлении и обратной совместимости -Они нужны только, если вы обновляете существующий экземпляр; новые развёртывания могут их пропустить. +Вам нужны только они, если вы обновляете существующий экземпляр; новые развертывания могут их пропустить. -> Когда Audits был выпущен, существующие получатели были расширены вдоль тех же форм ролей, как оповещения: каждый пользователь и набор разрешений, держащий `alerts:read`, получили `audits:read`, и каждый держатель `alerts:write` получил `audits:write`. Существующие API ключи **не** были расширены. Явно предоставьте `audits:*` ключу, если ему нужна поверхность аудита. +> Когда аудиты были поставлены, существующие получатели были расширены по тем же формам ролей, что и оповещения: каждый пользователь и набор разрешений, держащий `alerts:read`, получили `audits:read`, и каждый держатель `alerts:write` получил `audits:write`. Существующие API ключи **не были** расширены. Явно предоставьте `audits:*` ключу, если ему нужна поверхность аудита. -> Сохранённые права устаревшего токена `alerts:ack` анализируются как `incidents:ack`, так что дежурные сохраняют доступ без повторного создания ключей. Токен больше не может быть назначен из редактора пользователей панели управления; матрица предлагает `incidents:ack` вместо этого. +> Сохраненные гранты устаревшего токена `alerts:ack` анализируются как `incidents:ack`, поэтому включения в список сохраняют доступ без повторного создания ключа. Токен больше не может быть назначен из редактора пользователя панели; матрица предоставляет `incidents:ack` вместо этого. --- ## Следующие шаги - [Python SDK](/ru/agenteye/python-sdk): как ваш код агента аутентифицируется при отправке событий. -- [Безопасность](/ru/agenteye/security): как работают вход, контроль доступа и изоляция данных для каждой организации. \ No newline at end of file +- [Безопасность](/ru/agenteye/security): как работают вход, контроль доступа и изоляция данных на организацию. \ No newline at end of file diff --git a/docs/ru/agenteye/assistant.mdx b/docs/ru/agenteye/assistant.mdx index f03273f6..93e6ac9d 100644 --- a/docs/ru/agenteye/assistant.mdx +++ b/docs/ru/agenteye/assistant.mdx @@ -1,63 +1,63 @@ --- title: "AI Assistant" -description: "Задайте вопрос о данных вашего агента на простом русском языке и получите ответ со ссылками прямо на источники данных." +description: "Задайте вопрос о данных вашего агента на простом английском языке и получите ответ со ссылками прямо на доказательства." --- -Задайте вопрос о данных вашего агента на простом русском языке и получите ответ со ссылками прямо на источники данных. Не нужно писать SQL, не нужно копаться в дашбордах — помощник **Failproof AI Observability** — это самый быстрый способ для кого угодно в вашей команде получить ответы об агентах. +Задайте вопрос о данных вашего агента на простом английском языке и получите ответ со ссылками прямо на доказательства. Никаких запросов SQL, никаких дашбордов — помощник **Failproof AI Observability** — самый быстрый способ для любого члена вашей команды получить ответы о ваших агентах. -![Помощник Failproof AI Observability отвечает на вопрос на простом английском языке внутри дашборда, показывая активность агентов в реальном времени, разбор использования модели по агентам и выводы, с отображением выполненных запросов](/agenteye/images/assistant.png) -*Спросите на простом языке и получите ответ на основе ваших собственных данных. Здесь показано, какие агенты загружены больше всего и какие модели они используют, с отображением выполненных запросов, чтобы вы могли проверить каждую цифру.* +![Помощник Failproof AI Observability отвечает на вопрос на простом английском языке в дашборде, показывая таблицу активности агентов в реальном времени, распределение использования моделей по агентам и выводы, с отображением выполненных запросов](/agenteye/images/assistant.png) +*Задавайте вопросы на простом английском языке и получайте ответы на основе ваших собственных данных. Здесь показано, какие агенты работают больше всего и какие модели они используют, а также выполненные запросы, чтобы вы могли проверить каждую цифру.* -Нечего учить. Откройте чат, введите вопрос и переходите по ссылкам, которые он вернёт: +Нечего учить. Откройте чат, напишите, что хотите узнать, и перейдите по ссылкам, которые он вам предоставит: ``` -Вы: какие сессии ошибались сегодня? -AI: 5 сессий ошибались сегодня, от новых к старым. Каждая имеет ссылку: - • checkout-agent 14:02 тайм-аут инструмента - • billing-agent 11:47 необработанная ошибка - • ...и ещё 3 - -Вы: суммируй эту сессию (спрос при просмотре сеанса) -AI: Этот сеанс выполнил 12 шагов с использованием 3 инструментов и упал - в конце, когда инструмент оплаты вернул ошибку. Оценка по критерию - "resolved" низкая. Ссылки: сессия, событие с ошибкой и оценка. +Вы: какие сеансы ошибались сегодня? +AI: Сегодня ошибались 5 сеансов, новые первыми. На каждый есть ссылка: + • checkout-agent 14:02 tool timeout + • billing-agent 11:47 unhandled error + • ...и 3 ещё + +Вы: подведи итоги этого сеанса (спрашиваете, просматривая запуск) +AI: Этот запуск занял 12 шагов через 3 инструмента и завершился ошибкой, + когда инструмент платежа вернул ошибку. Оценка низкая по вашей + evals "resolved". Ссылки: сеанс, событие ошибки и эта оценка. ``` -## Просто спросите и перейдите прямо к доказательству +## Просто спросите и перейдите прямо к доказательствам -Вы перестаёте гадать и писать запросы. Спросите «как тренды качества на боевом сервере на этой неделе?», «какие сессии ошибались сегодня?» или «суммируй эту сессию», и получите чёткий ответ за секунды, вместо того чтобы строить запрос и читать его сами. +Вы перестанете гадать и писать запросы. Спросите «как меняется качество в prod на этой неделе?», «какие сеансы ошибались сегодня?» или «подведи итоги этого сеанса» — и вы получите четкий ответ за секунды вместо построения запроса и его чтения. -Каждый ответ содержит подтверждение. Помощник ссылается на точные сессии, сохранённые запросы и дашборды, которые он использовал для ответа, поэтому вы можете перейти и всё проверить, вместо того чтобы верить на слово. Он также **контекстный**: спросите о «этой сессии» во время просмотра сеанса, и он уже знает, какой запуск вы имеете в виду. Переоткройте любой предыдущий диалог позже из переключателя истории и продолжите с того же места. +Каждый ответ приходит с подтверждением. Помощник связывает точные сеансы, сохраненные запросы и дашборды, которые он использовал для ответа, чтобы вы могли перейти по ссылкам и подтвердить вместо того, чтобы верить на слово. Он также **осведомлен о странице**: спросите о «этом сеансе» во время просмотра одного — и он уже знает, какой запуск вы имеете в виду. Откройте позже любой предыдущий разговор из переключателя истории и продолжайте с того же места. -## Превратите хороший ответ в сохранённый запрос или дашборд +## Превратите хороший ответ в сохраненный запрос или дашборд -Когда ответ стоит сохранить, попросите помощника его сохранить. Он подготавливает SQL для сохранённого запроса или собирает дашборд из этих запросов и показывает вам карточку **Одобрить / Отклонить**. Ничто не записывается, пока вы не нажмёте «Одобрить», поэтому вы получаете скорость «просто спросите» с полным контролем в ваших руках. +Когда ответ стоит сохранить, попросите помощника его сохранить. Он подготовит SQL для сохраненного запроса или соберет дашборд из этих запросов, а затем покажет вам карточку **Одобрить / Отклонить**. Ничего не записывается, пока вы не нажмете Одобрить, поэтому вы получаете скорость режима «просто спросите» с последним словом всегда за вами. -На странице **Queries** он делает ещё больше и превращается в автора SQL: опишите нужный вам запрос («показать процент ошибок по агентам за последние 7 дней»), и он выведет SQL прямо в редактор, откроет представление различий, чтобы вы смогли **принять** или **отклонить** изменение перед внедрением. +На странице **Queries** он идет дальше и становится автором SQL: опишите запрос, который вам нужен («показать процент ошибок по агентам за последние 7 дней»), и он выведет SQL прямо в редактор, открыв диффпросмотр, чтобы вы могли **Принять** или **Отклонить** изменение перед его применением. -![Страница Observability Queries и её редактор SQL](/agenteye/images/query-lab.png) -*Страница Queries: в этом редакторе помощник выводит проект запроса только для чтения, который вы можете принять или отклонить.* +![Страница Observability Queries и ее редактор SQL](/agenteye/images/query-lab.png) +*Страница Queries: в этом редакторе помощник выводит черновик запроса только для чтения, который вы можете принять или отклонить.* -Написание SQL через вопросы здесь использует разрешение `queries:run`, то же самое, что за кнопкой **Run** в редакторе. Чат везде остаёт требует `agent:use`. +Написание SQL путем запроса здесь использует разрешение `queries:run`, то же самое, что стоит за кнопкой **Run** редактора. Чат везде остальном требует `agent:use`. ## Безопасно для всей команды -Вы можете открыть помощника для всех, не беспокоясь о том, к чему он может получить доступ: +Вы можете открыть помощника всем, не беспокоясь о том, что он может коснуться: -- **Он читает только то, что видите вы.** Ответы ограничены вашими разрешениями на чтение, поэтому он никогда не расширяет доступ к вашим данным. -- **Каждое изменение ждёт вашего подтверждения.** Сохранённые запросы и дашборды создаются только после вашего явного клика на «Одобрить», и нет никакой настройки, которая отключит эту защиту. -- **Он не может удалять ничего.** Нет инструмента удаления, и помощник не имеет разрешения на удаление. Удаления остаются в ваших руках, в дашборде. -- **Он остаётся внутри вашей организации.** Помощник видит только организацию, которую вы сейчас просматриваете. -- **Ваши вопросы остаются вашими.** Запросы и ответы хранятся в вашей собственной базе данных Observability; аналитика продукта записывает только метаданные использования, никогда ваш текст запроса. +- **Он читает только то, что вы уже видите.** Ответы ограничены вашими собственными разрешениями на чтение, поэтому он никогда не расширяет вашу поверхность данных. +- **Каждая запись ждет вас.** Сохраненные запросы и дашборды создаются только после вашего явного клика Одобрить, и нет настройки, которая отключит этот механизм. +- **Он никогда ничего не удаляет.** Инструмент удаления не подвергается воздействию, и помощник не имеет разрешения на удаление. Удаления остаются в ваших руках, в дашборде. +- **Он остается в вашей организации.** Помощник видит только организацию, которую вы сейчас просматриваете. +- **Ваши вопросы остаются вашими.** Подсказки и ответы хранятся в вашей собственной базе данных Observability; аналитика продукта записывает только метаданные об использовании, никогда текст вашей подсказки. ## Где его найти -Помощник находится на правом краю каждой страницы под вашей организацией (`//...`). Нажмите на панель или нажмите `⌘J` / `Ctrl+J`, чтобы развернуть полную панель чата, и перетащите её край для изменения размера; ваша ширина сохраняется при перезагрузке. Вам нужно разрешение **`agent:use`**, чтобы использовать его, иначе панель будет неактивна. Если он ещё не включён для вашего развёртывания (требуется подключение к LLM), вы увидите неактивную панель вместо работающего чата. +Помощник находится на правом краю каждой страницы под вашей организацией (`//...`). Нажмите на рельс или нажмите `⌘J` / `Ctrl+J`, чтобы развернуть его в полную панель чата, и перетащите его край, чтобы изменить размер; ваша ширина будет запомнена при перезагрузке. Вам нужно разрешение **`agent:use`**, чтобы его использовать, в противном случае рельс будет затемнен. Если он еще не был включен для вашего развертывания (ему нужно соединение LLM), вы увидите приглушенный рельс вместо рабочего чата. -## Связанное +## Связанные материалы -- [CLI and agents](/ru/agenteye/cli-and-agents) +- [CLI и агенты](/ru/agenteye/cli-and-agents) - [Queries](/ru/agenteye/queries) - [Dashboards](/ru/agenteye/dashboards) - [Evaluation suite](/ru/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/ru/agenteye/audits.mdx b/docs/ru/agenteye/audits.mdx index 5406cc08..33378834 100644 --- a/docs/ru/agenteye/audits.mdx +++ b/docs/ru/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- title: "Audits: ваш автоматический аналитик надёжности" -description: "Failproof AI Observability ищет те сбои, для которых вы никогда не писали правил, и выдаёт вам ранжированный, подкреплённый доказательствами список того, что именно нужно исправить." +description: "Failproof AI Observability ищет сбои, которые вы не описали в правилах, и выдаёт вам ранжированный список с доказательствами, что именно нужно исправить." --- -Failproof AI Observability ищет те сбои, для которых вы никогда не писали правил, и выдаёт вам ранжированный, подкреплённый доказательствами список того, что именно нужно исправить. Это как если бы аналитик каждую ночь прочёсывал ваши логи, а утром оставлял краткий список на вашем столе. +Failproof AI Observability ищет сбои, которые вы не описали в правилах, и выдаёт вам ранжированный список с доказательствами, что именно нужно исправить. Это как если бы аналитик каждую ночь просматривал ваши логи, а с утра оставлял краткий список на столе.
- +
-*Двухминутное введение: от запланированного запуска к исправлению, на которое вы можете действовать.* +*Двухминутный обзор: от запланированного запуска к действенному исправлению.* -![Страница Audits: повторяющиеся задачи, которые сканируют ваши сессии в поисках паттернов сбоев, каждая с расписанием и чувствительностью](/agenteye/images/audits.png) -*Каждый аудит — это повторяющаяся задача, которая анализирует ваши сессии и составляет ранжированные, подкреплённые доказательствами рекомендации.* +![Страница Audits: периодические задачи, которые сканируют ваши сессии на предмет паттернов сбоев, с расписанием и чувствительностью](/agenteye/images/audits.png) +*Каждый audit — это периодическая задача, которая анализирует ваши сессии и составляет ранжированные рекомендации с доказательствами.* -## Перестаньте гадать, что исправить в следующий раз +## Перестаньте гадать, что исправлять в следующую очередь -Оповещения ловят проблемы, которые вы уже знаете. Аудиты ловят те, о которых вы не знали. По установленному вами расписанию аудит просматривает все ваши сессии агентов и ищет паттерны, стоящие внимания, чтобы вы тратили время на действия, а не на прокрутку логов в поисках проблем. +Алерты ловят проблемы, которые вы уже знаете, как отследить. Audits ловят те, про которые вы не знаете. По установленному вами расписанию audit проверяет все сессии вашего агента и ищет паттерны, которые стоит исправить, чтобы вы могли действовать на основе результатов вместо того, чтобы просматривать логи в поисках проблем. -Один запуск нацелен на режимы отказа, которые действительно ломают агентов в production: +За один запуск проверяются режимы отказа, которые действительно ломают агентов в production: -- **Кластеры ошибок**: одна и та же ошибка, повторяющаяся из-за общей корневой причины. -- **Дрейф от базовой линии**: поведение, которое тихо отходит от известного хорошего окна. -- **Отказ в достижении цели в стенограммах**: запуски, которые технически завершились, но не выполнили работу. -- **Неправильное использование инструментов**: неправильный инструмент, плохие аргументы или циклы, которые сжигают вызовы. -- **Компромиссы между качеством и стоимостью**: места, где вы переплачиваете за результат, который можно получить дешевле. -- **Пробелы в покрытии**: поведение, которое никакая проверка или оповещение не отслеживает. +- **Кластеры ошибок**: одна и та же ошибка повторяется из-за общей причины. +- **Дрейф от базовой линии**: поведение незаметно смещается за границы известной хорошей зоны. +- **Невыполнение целей в транскриптах**: запуски, которые технически завершились, но не выполнили задачу. +- **Неправильное использование инструментов**: неправильный инструмент, плохие аргументы или циклы, которые тратят вызовы. +- **Компромиссы между качеством и стоимостью**: где вы переплачиваете за результат, который можно получить дешевле. +- **Пробелы в покрытии**: поведение, которое ни один eval и ни один alert не отслеживает. -Вы решаете, насколько тщательно искать, с помощью одного параметра **sensitivity** (low, medium или high), чтобы шумный агент в staging и закрытый агент в production могли быть настроены каждый на свой сигнал. +Вы контролируете интенсивность поиска единственной настройкой **sensitivity** (низкая, средняя или высокая), поэтому шумный агент в staging и заблокированный агент в production могут быть настроены каждый на нужный вам сигнал. -## Каждая рекомендация подкреплена доказательствами +## Каждая рекомендация поставляется с доказательствами -Вам никогда не нужно верить находке на слово. Каждая рекомендация указывает на точные сессии, из которых она получена, и SQL, который её выявил, поэтому вы можете открыть доказательство и подтвердить проблему в один клик вместо того, чтобы обратный-инженерить утверждение. +Вам никогда не нужно верить результату на слово. Каждая рекомендация ссылается на точные сессии, из которых она была получена, и SQL-запрос, который её нашёл, чтобы вы могли открыть доказательства и подтвердить проблему в один клик вместо того, чтобы обратным инжинирингом восстанавливать утверждение. -Когда находка касается утёкшего учётного данного, она идёт дальше и связывает отдельные события, которые она совпала. Щелкните на одно, и вы окажетесь в точном моменте сессии, уже выбранном — а не в начале длинной стенограммы, которую нужно прокручивать. Ссылка называет событие; она никогда не копирует обнаруженный секрет в находку, поэтому чтение находки — не второе место, где написано ваше учётное данное. Если события больше нет, потому что сессия прошла вашу схему хранения, страница скажет об этом ясно, а не оставит вас в раздумьях, правильно ли вы щелкнули. +Когда результат касается утечки учётных данных, это идёт ещё дальше и ссылается на отдельные события, которые были найдены. Кликните на одно — и вы попадёте в этот точный момент в сессии, уже выделенный — а не в начало длинного транскрипта, который нужно прокручивать. Ссылка называет событие; она никогда не копирует обнаруженный секрет в результат, поэтому чтение результата — это не второе место, где ваши учётные данные записаны. Если события больше нет, потому что сессия вышла за границы окна хранения, страница скажет об этом явно, вместо того чтобы оставлять вас в сомнении, правильно ли вы кликнули. -Это также то, что держит аудиты честными. Сервер проверяет, что каждая упомянутая сессия действительно существует, и **отбрасывает любую рекомендацию, чьи доказательства не выдерживают проверку**, поэтому аудит исследует, но никогда не выдумывает. То, что попадёт в ваш список, реально, воспроизводимо и ранжировано по значимости, с наибольшими выигрышами в начале. +Это также держит audits в честности. Сервер проверяет, что каждая упоминаемая сессия действительно существует, и **отбрасывает любую рекомендацию, доказательства которой не подтверждаются**, поэтому audit исследует, но никогда не придумывает. Что попадает в ваш список — это реально, воспроизводимо и ранжировано по значимости, с самыми важными выигрышами в начале. -## Превратите исправление в охранное правило +## Превратите исправление в защиту -Исправление проблемы — только половина выигрыша. Другая половина — убедиться, что она не может тихо вернуться. Каждая находка содержит **ярлык в один клик, который составляет повторяющееся оповещение**, предварительно заполненный разумным начальным триггером, который вы можете настроить. Закройте находку, активируйте оповещение, и в следующий раз, когда этот паттерн снова появится, вы получите уведомление вместо того, чтобы заново открыть его в будущем аудите. +Исправление проблемы — это только половина победы. Другая половина — убедиться, что она не может вернуться незаметно. Каждый результат содержит **ярлык в один клик, который создаёт рекомендацию повторения**, предзаполненный разумным исходным триггером, который вы можете отрегулировать. Закройте результат, активируйте алерт, и в следующий раз, когда этот паттерн вернётся, вы получите оповещение вместо того, чтобы переоткрывать его в будущем audit. -## Где его найти +## Где это найти -Audits находятся в панели управления по адресу **`//audits`** (боковая панель на *analyze* к *audits*). Просмотр запусков и находок требует **`audits:read`**; создание, редактирование и триаж аудитов требует **`audits:write`**. Установите область действия и кадency аудита, затем нажмите **Run now**, если хотите получить результаты немедленно, вместо того чтобы ждать следующего запланированного запуска. +Audits находятся на панели управления по адресу **`//audits`** (боковая панель → *analyze* → *audits*). Для просмотра запусков и результатов нужно разрешение **`audits:read`**; для создания, редактирования и сортировки audits нужно **`audits:write`**. Установите область и периодичность audit, затем нажмите **Run now** когда вы хотите получить результаты немедленно вместо ожидания следующего запланированного запуска. -## Связанное +## Смотрите также -- [Alerts](/ru/agenteye/alerts): получайте уведомление в момент пересечения известного вам порога. -- [Evaluations](/ru/agenteye/evaluations): оценивайте каждый запуск, чтобы регрессии качества всплывали сами. +- [Alerts](/ru/agenteye/alerts): получайте оповещение в момент, когда пересекается известный вам порог. +- [Evaluations](/ru/agenteye/evaluations): оценивайте каждый запуск, чтобы регрессии качества выявлялись сами по себе. - [Error tracking](/ru/agenteye/error-tracking): группируйте и отслеживайте ошибки, которые выбрасывают ваши агенты. -- [Incidents](/ru/agenteye/incidents): отслеживайте проблему, которую аудит выявил, вплоть до её исправления. \ No newline at end of file +- [Incidents](/ru/agenteye/incidents): отслеживайте проблему от audit до её исправления. \ No newline at end of file diff --git a/docs/ru/agenteye/cli-and-agents.mdx b/docs/ru/agenteye/cli-and-agents.mdx index 51571561..29c0f879 100644 --- a/docs/ru/agenteye/cli-and-agents.mdx +++ b/docs/ru/agenteye/cli-and-agents.mdx @@ -1,10 +1,11 @@ --- +--- title: "CLI" -description: "Весь ваш Failproof AI Observability, развёрнутый одной командой." +description: "Весь процесс развёртывания Failproof AI Observability — одна команда. Проверьте production, создайте API-ключ или подтвердите инцидент, не покидая терминал, затем автоматизируйте всё в CI или позвольте агенту-кодировщику сделать это на простом английском." --- -Весь ваш Failproof AI Observability, развёрнутый одной командой. Проверьте production, создайте API-ключ или подтвердите инцидент, не покидая терминала, а затем автоматизируйте всё это в CI или позвольте coding-агенту сделать это на простом английском языке. +Весь процесс развёртывания Failproof AI Observability — одна команда. Проверьте production, создайте API-ключ или подтвердите инцидент, не покидая терминал, затем автоматизируйте всё в CI или позвольте агенту-кодировщику сделать это на простом английском. ```bash pipx install agenteye @@ -12,18 +13,18 @@ agenteye login --email you@example.com # a 6-digit code lands in your inbox agenteye --json sessions --since 24h # every agent run from the last day, newest first ``` -*CLI `agenteye` взаимодействует с вашим dashboard. Это отдельный инструмент от collector, который отправляет события на сервер.* +*CLI `agenteye` обращается к вашему дашборду. Это отдельный инструмент от сборщика событий, который отправляет данные на сервер.* -## Весь deployment в одной команде +## Весь процесс развёртывания — одна команда -Перестаньте прыгать по табам, чтобы ответить на быстрый вопрос. CLI `agenteye` читает ваши данные и управляет организацией из единого бинарного файла, поэтому проверка, которая раньше требовала кликов в dashboard, становится одной строкой, которую можно переиспользовать, создать alias или вставить в runbook. Вы получаете четыре интерфейса: +Перестаньте переключаться между вкладками, чтобы ответить на быстрый вопрос. CLI `agenteye` читает ваши данные и управляет организацией из одного бинарного файла, поэтому проверка, которая раньше требовала кликов по дашборду, становится одной строкой, которую вы можете переиспользовать, создать алиас или вставить в runbook. Вы получаете четыре интерфейса: - **Читайте ваши данные:** `sessions`, `events`, `evals` и `errors`, отфильтрованные по времени, агенту и окружению. - **Управляйте организацией:** `keys`, `users`, `settings`, `alerts` и `incidents`. -- **Запускайте аналитику:** сохранённые SQL-запросы плюс ad-hoc `query` для анализа данных о событиях. -- **Спросите ассистента:** `agent ask` подключает того же read-only аналитика, с которым вы общаетесь в dashboard. +- **Запускайте аналитику:** сохранённые SQL-запросы плюс ad-hoc `query` для ваших данных событий. +- **Общайтесь с ассистентом:** `agent ask` обращается к тому же аналитику (режим только чтение), с которым вы общаетесь в дашборде. -Установите один раз с помощью `pipx`, войдите, используя 6-значный код из письма, и готово. Сессия длится около дня; переустановите `agenteye login` когда она истечёт. Используйте его для проверки production, подготовки ключа или триажа срабатывающего инцидента, всё без открытия браузера: +Установите один раз с помощью `pipx`, авторизуйтесь 6-значным кодом по email и вы готовы к работе. Сессия длится около дня; переустановите `agenteye login`, когда она истечёт. Используйте его для проверки production, создания ключа или диагностики срабатывающего инцидента, всё без открытия браузера: ```bash agenteye errors --since 24h --aggregate # what is breaking, grouped by error type @@ -31,50 +32,50 @@ agenteye incidents list --state firing # what is on fire right now agenteye keys create ci --add events:add # a key that can only push events, secret shown once ``` -Один привычный нюанс: глобальные опции вроде `--json` идут перед командой. `agenteye --json sessions` правильно; `agenteye sessions --json` неправильно. +Один важный момент: глобальные опции вроде `--json` идут перед командой. `agenteye --json sessions` — правильно; `agenteye sessions --json` — нет. -## Автоматизируйте, подключите к CI +## Автоматизируйте, встройте в CI -Каждая команда поддерживает `--json`, и это меняет всё. Чистый JSON идёт в stdout, а статус и предупреждения для человека — в stderr, поэтому захват с `--json` направляется прямо в `jq` без лишних строк для очистки. Именно это делает CLI одинаково полезным как для вас в командной строке, так и для coding-агента, парсящего выходные данные: +Каждая команда поддерживает `--json`, и это меняет всё. Чистый JSON идёт в stdout, а статус и предупреждения — в stderr, поэтому захват `--json` напрямую передаётся в `jq` без лишних строк для удаления. Это делает CLI одинаково полезным как для вас в терминале, так и для агента-кодировщика, который парсит вывод: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -Построен для работы без присмотра. Запросы подтверждения пропускаются автоматически, когда терминал не подключён, поэтому ничего не зависает в pipeline, и каждая команда возвращает значимый exit code: `0` успех, `4` не залогинены, `5` недостаточны разрешения (сообщение указывает их, например `alerts:write`), `3` dashboard недоступен. Скрипт может ветвиться на `4` для переаутентификации или на `5` чтобы рассказать вам, что именно нужно попросить у администратора, вместо того чтобы упасть без информации. +Это создано для работы без присмотра. Запросы подтверждения пропускаются автоматически, если терминал не подключён, поэтому ничего не зависает в pipeline, и каждая команда возвращает осмысленный код выхода: `0` успех, `4` не авторизирован, `5` нет прав (сообщение указывает именно какие, например `alerts:write`), `3` дашборд недоступен. Скрипт может ветвиться по `4` для переавторизации или по `5` чтобы точно сказать вам, что попросить у администратора, вместо безслёзного отказа. -## Позвольте coding-агенту управлять им на простом английском +## Позвольте агенту-кодировщику управлять этим на простом английском -Лучше ещё — вам не должно требоваться помнить все эти флаги вообще. **CLI skill** — это небольшая папка Agent Skill под названием `agenteye-cli`, которая учит coding-агента такого как Claude Code или Codex управлять CLI из простых запросов на английском языке. Спросите "что-нибудь сломалось сегодня?" и агент выберет команду, запустит её от вашего имени и ответит прозой. +Ещё лучше, вам не нужно помнить все эти флаги. **CLI skill** — это маленькая папка Agent Skill с названием `agenteye-cli`, которая обучает агента-кодировщика вроде Claude Code или Codex управлять CLI через запросы на простом английском. Спросите "что-нибудь сломалось сегодня?" и агент выберет команду, запустит её как вы и ответит прозой. -Для Claude Code поместите папку `agenteye-cli` в `~/.claude/skills/` и она будет автоматически обнаружена. Failproof AI Observability предоставляет папку; нет ничего дополнительного для установки, потому что она только управляет CLI, который вы уже установили. Залогиньтесь сами первыми: skill не может завершить для вас login с кодом из письма. +Для Claude Code просто положите папку `agenteye-cli` в `~/.claude/skills/` и она будет обнаружена автоматически. Failproof AI Observability предоставляет эту папку; нечего дополнительно устанавливать, потому что она только управляет уже установленным CLI. Авторизуйтесь сами первым: skill не может завершить авторизацию по коду email для вас. -Поскольку агент запускает CLI от вашего имени, он может делать всё, что позволяет ваш логин, чтение и запись: создавать ключи, менять настройки, разрешать инциденты. Prompt "вы уверены?" CLI не срабатывает для агента, поэтому skill написан так, чтобы указать точную команду и ждать вашего ОК перед любым изменением. Вы — шаг подтверждения. +Поскольку агент запускает CLI от вашего имени, он может делать всё, что позволяют ваши права, и читать, и писать: создавать ключи, менять настройки, разрешать инциденты. Подтверждающий запрос CLI не срабатывает для агента, поэтому skill написан так, чтобы выводить точную команду и ждать вашего OK перед любым изменением. Вы — это этап подтверждения. ```text -вы Почему упала сессия run-001? +you Why did session run-001 fail? -агент Running: agenteye --json events --session-id run-001 --all +agent Running: agenteye --json events --session-id run-001 --all The checkout-agent hit a TimeoutError on its third tool call. ``` -Чтения остаются мгновенными, и каждая запись приостанавливается для вас: +Чтение остаётся мгновенным, а каждая запись замирает в ожидании вас: ```text -вы Дайте CI ключ, который может только отправлять события. +you Give CI a key that can only push events. -агент This creates an API key. I'll run: +agent This creates an API key. I'll run: agenteye keys create ci --add events:add OK to proceed? -вы yes +you yes -агент Done. Key "ci" created with events:add only. The secret is shown once, so store it now. +agent Done. Key "ci" created with events:add only. The secret is shown once, so store it now. ``` -## Связанное +## Related -- [CLI reference](/ru/agenteye/cli): все команды, флаги и JSON-структуры. -- [CLI recipes for agents](/ru/agenteye/cli-recipes): паттерны `jq` и обработка exit-кодов для копирования-вставки. -- [CLI agent skill](/ru/agenteye/cli-skill): установка и запуск skill `agenteye-cli`. -- [AI assistant](/ru/agenteye/assistant): аналитик в dashboard, с которым общается `agent ask`. \ No newline at end of file +- [CLI reference](/ru/agenteye/cli): каждая команда, флаг и JSON-структура. +- [CLI recipes for agents](/ru/agenteye/cli-recipes): готовые паттерны `jq` и обработка кодов выхода. +- [CLI agent skill](/ru/agenteye/cli-skill): установите и запустите skill `agenteye-cli`. +- [AI assistant](/ru/agenteye/assistant): встроенный в дашборд аналитик, с которым общается `agent ask`. \ No newline at end of file diff --git a/docs/ru/agenteye/cli-recipes.mdx b/docs/ru/agenteye/cli-recipes.mdx index 86affd35..817df9c8 100644 --- a/docs/ru/agenteye/cli-recipes.mdx +++ b/docs/ru/agenteye/cli-recipes.mdx @@ -1,30 +1,30 @@ --- -title: "CLI recipes for agents" -description: "Copy-paste query patterns and jq recipes that turn session, event, and evaluation data into something a script or coding agent can automate." +title: "CLI рецепты для агентов" +description: "Готовые к копированию паттерны запросов и рецепты jq, которые превращают данные сессий, событий и оценок в то, что скрипт или кодирующий агент может автоматизировать." --- -Pull session, event, and evaluation data (and trigger re-evaluations) straight from a script or coding agent, with clean JSON on stdout that pipes directly into `jq`. These recipes turn Failproof AI Observability's data into something a terminal user or an AI coding agent (Claude Code, Cursor) can query and automate, without clicking through the dashboard. +Получайте данные сессий, событий и оценок (и инициируйте переоценки) прямо из скрипта или кодирующего агента с чистым JSON на stdout, который можно передать прямо в `jq`. Эти рецепты превращают данные Failproof AI Observability в то, что терминальный пользователь или кодирующий AI-агент (Claude Code, Cursor) может запросить и автоматизировать без клика по дашборду. -The patterns below are copy-paste ready for the Failproof AI Observability CLI (`agenteye`). For installation, authentication, and the full option list see [CLI](/ru/agenteye/cli); run `agenteye -h` or `agenteye -h` for the built-in help. +Паттерны ниже готовы к копированию в CLI Failproof AI Observability (`agenteye`). Для установки, аутентификации и полного списка опций см. [CLI](/ru/agenteye/cli); запустите `agenteye -h` или `agenteye -h` для встроенной справки. -## Golden rules +## Золотые правила -1. **Global options go *before* the command.** `agenteye --json sessions` is correct; `agenteye sessions --json` is not. The globals are `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Pass `--json` whenever you parse output.** Data goes to **stdout** as JSON; human status and errors go to **stderr**, so stdout stays clean to pipe into `jq`. -3. **Branch on the exit code**, not on stderr text: `0` ok · `1` unexpected error · `2` bad arguments · `3` cannot reach the dashboard · `4` not logged in or expired · `5` missing permission · `6` resource not found. -4. **Discover with `-h`.** Every command documents its filters, value formats, and JSON shape. +1. **Глобальные опции идут *перед* командой.** `agenteye --json sessions` правильно; `agenteye sessions --json` нет. Глобальные опции: `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Передавайте `--json` всякий раз, когда парсите вывод.** Данные идут на **stdout** как JSON; статус для человека и ошибки идут на **stderr**, так что stdout остаётся чистым для передачи в `jq`. +3. **Ветвитесь по коду выхода**, не по тексту stderr: `0` ок · `1` неожиданная ошибка · `2` неверные аргументы · `3` не удаётся достичь дашборда · `4` не авторизован или истекла сессия · `5` отсутствует разрешение · `6` ресурс не найден. +4. **Откройте для себя с `-h`.** Каждая команда документирует свои фильтры, форматы значений и форму JSON. -## One-time setup +## Одноразовая настройка ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # so you don't repeat --base-url -agenteye login --email you@example.com # paste the emailed code; valid ~24h +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # чтобы не повторять --base-url +agenteye login --email you@example.com # вставьте отправленный код; действителен ~24ч ``` -## Confirm auth before doing work +## Подтвердите аутентификацию перед работой -`whoami` never errors on a missing or expired session; it reports `logged_in:false` instead, so an agent can probe auth state safely. (It can still exit non-zero if no base URL is set or the dashboard is unreachable.) +`whoami` никогда не ошибается при отсутствующей или истекшей сессии; вместо этого она сообщает `logged_in:false`, поэтому агент может безопасно проверить состояние аутентификации. (Это всё ещё может выйти с ненулевым кодом, если не установлен базовый URL или дашборд недостижим.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,98 +32,98 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Find failing or low-scoring sessions +## Найдите неудачные или низкооценённые сессии ```bash -# sessions in the last 24h whose evaluation errored +# сессии за последние 24ч, у которых оценка ошибилась agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# evaluations scoring <= 0.5 on helpfulness, for one agent +# оценки с баллом <= 0.5 по helpfulness для одного агента agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Score filtering lives on **`evals`**, not `sessions`. `--score KEY:MIN..MAX` is repeatable and AND-combined; either bound is optional (`..0.5` means ≤ 0.5, `0.9..` means ≥ 0.9). You can pass up to 20 score filters per request; more returns HTTP 400. `sessions` shares the `--env`, `--status`, `--agent-id`, `--session-id`, and time-range filters with `evals`, but has no `--score`. +Фильтрация по баллам находится в **`evals`**, а не в `sessions`. `--score KEY:MIN..MAX` повторяема и применяется логическим И; любая граница опциональна (`..0.5` означает ≤ 0.5, `0.9..` означает ≥ 0.9). Вы можете передать до 20 фильтров баллов за запрос; больше возвращает HTTP 400. `sessions` использует фильтры `--env`, `--status`, `--agent-id`, `--session-id` и временные диапазоны с `evals`, но не имеет `--score`. -## Read one session end-to-end +## Прочитайте одну сессию от начала до конца -There is no single `session show` command. Combine the event trail with the session's evaluation: +Нет единственной команды `session show`. Объедините цепочку событий с оценкой сессии: ```bash -# the session's latest evaluation (status + scores) +# последняя оценка сессии (статус + баллы) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# every event in the run (raise --limit for a full sweep) +# каждое событие в прогоне (повысьте --limit для полного сканирования) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# just the tool calls in a session (--full is required to get the raw payload) +# только вызовы инструментов в сессии (--full требуется для получения сырой полезной нагрузки) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **Note:** By default, `events` reads a fast, payload-free feed. Each event carries a server-computed one-line `summary` plus flags like `is_error` and token counts, but `payload` comes back as `{}`. To pull the raw payload, add `--full` (or `--fields payload`). The full feed is slower at scale, so keep it bounded: pair `--full` with a single `--session-id`. +> **Примечание:** По умолчанию `events` читает быструю ленту без полезной нагрузки. Каждое событие содержит вычисленное сервером однострочное резюме `summary` плюс флаги вроде `is_error` и подсчёт токенов, но `payload` возвращается как `{}`. Чтобы получить сырую полезную нагрузку, добавьте `--full` (или `--fields payload`). Полная лента медленнее в масштабе, поэтому держите её ограниченной: спарьте `--full` с единственным `--session-id`. -## Fetch everything (pagination) +## Получите всё (пагинация) -Results are newest-first and cursor-paginated. +Результаты отсортированы от новейших к старейшим и подвергаются курсор-пагинации. ```bash -# one shot: fetch up to 500 rows in 200-row pages +# одним разом: получите до 500 строк страницами по 200 agenteye --json events --session-id run-001 --limit 500 --all > events.json -# manual paging: feed next_cursor back in +# ручная пагинация: передайте next_cursor обратно page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## Slim the output with --fields +## Сократите вывод с помощью --fields -Restrict the keys (in both the table and `--json`) to reduce what an agent must read. +Ограничьте ключи (как в таблице, так и в `--json`) чтобы сократить то, что должен прочитать агент. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Unknown field names are rejected (exit `2`) with the valid list, a cheap way to discover field names. +Неизвестные имена полей отклоняются (выход `2`) со списком допустимых — дешёвый способ открыть имена полей. -## Discover valid filter values +## Откройте допустимые значения фильтров ```bash -agenteye --json list envs | jq -r '.values[]' # values for --env -agenteye --json list tools | jq -r '.values[]' # tool names; also agents, models, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # valid KEY for --score KEY:MIN..MAX +agenteye --json list envs | jq -r '.values[]' # значения для --env +agenteye --json list tools | jq -r '.values[]' # имена инструментов; также agents, models, event_types, … +agenteye --json list score_filters | jq -r '.values[]' # допустимый KEY для --score KEY:MIN..MAX ``` -## Pick your org (multi-tenant) +## Выберите вашу организацию (мульти-тенант) -If you belong to more than one org, choose the active tenant at login (it's saved): +Если вы входите в несколько организаций, выберите активный тенант при входе (это сохраняется): ```bash -agenteye login --org acme --email you@corp.com # set the tenant in the same step as login +agenteye login --org acme --email you@corp.com # установите тенант в один шаг с входом agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # override for one command +agenteye --org globex --json sessions --since 24h # переопределите для одной команды ``` -A multi-org login without `--org` exits non-zero and prints the orgs to choose from. +Мульти-организационный вход без `--org` выходит с ненулевым кодом и печатает организации на выбор. -## Provision an API key for the SDK/collector +## Создайте API-ключ для SDK/коллектора ```bash -# the secret is printed ONCE, with --json it's the .key field +# секрет печатается ОДИН РАЗ, при --json это поле .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # rotate; agenteye keys disable ci-bot --yes to revoke +agenteye keys regenerate ci-bot --yes # ротируйте; agenteye keys disable ci-bot --yes для отзыва ``` -## Run a saved or ad-hoc query +## Запустите сохранённый или ad-hoc запрос ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # a saved query + a positional $1 +agenteye --json query run errs --arg prod | jq '.rows' # сохранённый запрос + позиционный $1 ``` -## Triage an incident non-interactively +## Разберитесь с инцидентом неинтерактивно ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,9 +132,9 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **Note:** Mutations auto-skip their confirmation prompt under `--json` or when stdin isn't a TTY, so agents never hang; pass `--yes`/`-y` to skip it explicitly elsewhere. +> **Примечание:** Мутации автоматически пропускают подтверждение под `--json` или когда stdin не TTY, так что агенты никогда не зависают; передайте `--yes`/`-y` чтобы пропустить явно в другом месте. -## Exit-code handling in a script +## Обработка кодов выхода в скрипте ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -147,33 +147,33 @@ case "${code:-0}" in esac ``` -## JSON output shapes +## Формы вывода JSON -| Command | stdout JSON (with `--json`) | +| Команда | JSON на stdout (с `--json`) | |---|---| -| `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` or `{"logged_in": false}` | +| `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` или `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | | `events` | `{"events": [...], "next_cursor": }` | | `evals` | `{"evaluations": [...], "next_cursor": }` | | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` shown once) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` показывается один раз) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (any) | the resource object, or `{"deleted": true, "id"}` for deletes | -| failure (any, with `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` on stdout | +| create/update/delete (любое) | объект ресурса, или `{"deleted": true, "id"}` для удалений | +| ошибка (любая, с `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` на stdout | -- Each **event** item (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Note that `payload` is `{}` unless you request the full feed with `--full` (or `--fields payload`). -- Each **evaluation** item (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- Each **session** item (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- Каждый элемент **события** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Обратите внимание, что `payload` — это `{}` если вы не запросили полную ленту с `--full` (или `--fields payload`). +- Каждый элемент **оценки** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- Каждый элемент **сессии** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -Each command's `--fields` accepts exactly its own item's field names. The set differs between `sessions` and `evals`, so a name valid for one may be rejected by the other. +`--fields` каждой команды принимает ровно имена полей своего элемента. Набор отличается между `sessions` и `evals`, поэтому имя, допустимое для одного, может быть отклонено другим. -## Next steps +## Следующие шаги -- [CLI](/ru/agenteye/cli): installation, authentication, and the full option reference for every command. -- [CLI agent skill](/ru/agenteye/cli-skill): package these recipes as a skill your coding agent can load. -- [API keys](/ru/agenteye/api-keys): create and scope the keys the CLI, SDK, and collector authenticate with. -- [Python SDK](/ru/agenteye/python-sdk): send events into Failproof AI Observability so there is data for these recipes to query. \ No newline at end of file +- [CLI](/ru/agenteye/cli): установка, аутентификация и полная справка опций для каждой команды. +- [CLI agent skill](/ru/agenteye/cli-skill): упакуйте эти рецепты как скилл, который ваш кодирующий агент может загрузить. +- [API keys](/ru/agenteye/api-keys): создавайте и масштабируйте ключи, которые используют CLI, SDK и коллектор для аутентификации. +- [Python SDK](/ru/agenteye/python-sdk): отправляйте события в Failproof AI Observability так, чтобы были данные для запроса этими рецептами. \ No newline at end of file diff --git a/docs/ru/agenteye/cli-skill.mdx b/docs/ru/agenteye/cli-skill.mdx index 272fb6c7..23172ac6 100644 --- a/docs/ru/agenteye/cli-skill.mdx +++ b/docs/ru/agenteye/cli-skill.mdx @@ -1,67 +1,67 @@ --- title: "Failproof AI Observability CLI Agent Skill" -description: "Спросите у вашего coding agent \"сегодня что-нибудь сломалось?\" и позвольте ему ответить на основе ваших live данных Failproof AI Observability, без необходимости запоминать команды." +description: "Спросите у своего кодирующего агента «что-то сломалось сегодня?» и позвольте ему ответить на основе ваших живых данных Failproof AI Observability без необходимости запоминать команды." --- -Спросите у вашего coding agent *«сегодня что-нибудь сломалось?»* и позвольте ему ответить на основе ваших live данных Failproof AI Observability, без необходимости запоминать команды. **Failproof AI Observability CLI skill** (`agenteye-cli`) — это *Agent Skill*: небольшая папка с инструкциями, которую coding agent, такой как Claude Code или Codex, загружает по требованию. Она учит agent управлять вашей Observability deploymentом через [`agenteye` CLI](/ru/agenteye/cli) на основе запросов на обычном английском языке, таких как *«выдай CI ключ, который может только отправлять события»* или *«подтверди активный инцидент и назначь его на меня»*. +Спросите у своего кодирующего агента *«что-то сломалось сегодня?»* и позвольте ему ответить на основе ваших живых данных Failproof AI Observability без необходимости запоминать команды. **Навык Failproof AI Observability CLI** (`agenteye-cli`) — это *Agent Skill*: небольшая папка с инструкциями, которую кодирующий агент, такой как Claude Code или Codex, загружает по требованию. Она учит агента управлять вашим развёртыванием Observability через [`agenteye` CLI](/ru/agenteye/cli) на основе обычных англоязычных запросов вроде *«выдай CI ключ, который может только отправлять события»* или *«подтверди активный инцидент и назначь его на меня»*. -Это **не** сервис и не отдельный бинарный файл; нет ничего, что нужно разворачивать. Он работает поверх уже установленного вами CLI: agent выполняет `agenteye --json …`, парсит чистый JSON и отвечает вам прозой. Всё, что он может сделать, вы можете сделать сами, набрав те же команды. +Это **не** сервис и не отдельный бинарный файл; нет ничего для развёртывания. Она работает поверх уже установленного вами CLI: агент вызывает `agenteye --json …`, парсит чистый JSON и отвечает вам прозой. Всё, что она может делать, вы можете делать сами, вводя те же команды. --- -## Как это соотносится с другими интерфейсами Failproof AI Observability +## Как это связано с другими интерфейсами Failproof AI Observability -Failproof AI Observability предоставляет четыре способа доступа к одним и тем же данным и элементам управления. Они дополняют друг друга: +Failproof AI Observability предоставляет четыре способа доступа к одним и тем же данным и управлению ими. Они дополняют друг друга: -| Интерфейс | Что это такое | Где выполняется | Используйте, когда | +| Интерфейс | Что это | Где работает | Используйте, когда | |---|---|---|---| -| **[CLI](/ru/agenteye/cli)** | Справочник команд и флагов для `agenteye` | Ваш терминал | Вы хотите запустить или создать сценарий для конкретной команды | -| **[CLI recipes](/ru/agenteye/cli-recipes)** | Шаблоны `jq`/pipelines для копирования и вставки | Ваш терминал / скрипты | Вы интегрируете CLI в автоматизацию | -| **CLI skill** (этот документ) | Дверь с естественным языком для CLI | Ваш coding agent на рабочей станции | Вы просто хотите спросить и позволить agent выбрать команду | -| **[Evaluator skill](/ru/agenteye/evaluator-skill)** | Родственный skill, который проектирует и создаёт ваш сервис оценивания | Ваш coding agent на рабочей станции | Вы хотите *производить* баллы оценивания, а не только их читать | -| **[Python SDK skill](/ru/agenteye/python-sdk-skill)** | Родственный skill, который инструментирует agent, чтобы он вообще испускал телеметрию | Ваш coding agent на рабочей станции | Вы хотите, чтобы agent *производил* события, которые этот skill читает | -| **[In-dashboard AI assistant](/ru/agenteye/assistant)** | Чат, встроенный в приборную панель | Серверная сторона (в приборной панели) | Вы хотите Q&A в приборной панели над вашими данными | +| **[CLI](/ru/agenteye/cli)** | Справочник команд и флагов для `agenteye` | Ваш терминал | Вы хотите запустить или написать скрипт для конкретной команды | +| **[CLI рецепты](/ru/agenteye/cli-recipes)** | Готовые к вставке паттерны `jq` / конвейеры | Ваш терминал / скрипты | Вы интегрируете CLI в автоматизацию | +| **CLI навык** (этот документ) | Естественно-языковой фасад к CLI | Ваш кодирующий агент на вашей рабочей станции | Вы хотите просто спросить и позволить агенту выбрать команду | +| **[Evaluator навык](/ru/agenteye/evaluator-skill)** | Родственный навык, который проектирует и создаёт ваш сервис скоринга | Ваш кодирующий агент на вашей рабочей станции | Вы хотите создавать оценки оценивания вместо их чтения | +| **[Python SDK навык](/ru/agenteye/python-sdk-skill)** | Родственный навык, который инструментирует ваш агент для излучения телеметрии | Ваш кодирующий агент на вашей рабочей станции | Вы хотите, чтобы ваш агент создавал события, которые этот навык читает | +| **[Встроенный в дашборд AI ассистент](/ru/agenteye/assistant)** | Чат, встроенный в дашборд | На сервере (в дашборде) | Вы хотите получить ответы на вопросы в дашборде по своим данным | -Сам skill не имеет собственных привилегий; он просто преобразует ваши слова в вызовы CLI, которые выполняются от вас: +Сам навык не имеет собственных привилегий; он просто преобразует ваши слова в вызовы CLI, которые выполняются от вашего имени: ```mermaid flowchart TD - YOU["вы: 'подтверди активный инцидент'"] --> AGENT["coding agent (Claude Code / Codex)
загружает agenteye-cli skill"] + YOU["вы: 'подтверди активный инцидент'"] --> AGENT["кодирующий агент (Claude Code / Codex)
загружает навык agenteye-cli"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|ваша аутентифицированная CLI сессия| API["Observability dashboard API"] + CLI -->|ваш аутентифицированный CLI сеанс| API["API дашборда Observability"] ``` -### в сравнении с in-dashboard AI assistant: важное различие +### против встроенного AI ассистента: важное различие -Это два совершенно разных инструмента с очень разными областями влияния: +Это два совершенно разных инструмента с очень разными радиусами действия: -- **In-dashboard AI assistant** ([AI assistant](/ru/agenteye/assistant)) — это чат, встроенный в приборную панель, поддерживаемый сервисом agent. Он **только для чтения плюс создание с одобрением**: он может создавать черновики сохранённых запросов и панелей управления, но каждая запись требует вашего явного подтверждения, и он никогда не удаляет. Он защищён разрешением `agent:use` и видит только данные организации, которую вы просматриваете. -- **CLI skill** работает на *вашей* рабочей станции внутри *вашего* coding agent и управляет `agenteye` CLI от вас. Он может выполнять **полный набор CLI, включая изменения** (создание/ротация/отключение API ключей, изменение параметров org, разрешение инцидентов, удаление сохранённых запросов), ограниченные только разрешениями вашей CLI-сессии. Относитесь к этому ровно так же осторожно, как вы относились бы к выполнению этих команд вручную. +- **Встроенный в дашборд AI ассистент** ([AI ассистент](/ru/agenteye/assistant)) — это чат в дашборде, поддерживаемый агентом-сервисом. Это **только для чтения плюс одобрение для авторства**: он может создавать проекты сохранённых запросов и дашбордов, но каждая запись ждёт вашего явного клика-подтверждения, и он никогда не удаляет. Он контролируется разрешением `agent:use` и всегда видит только данные для организации, которую вы просматриваете. +- **CLI навык** работает на *вашей* рабочей станции внутри *вашего* кодирующего агента и управляет CLI `agenteye` как **вы**. Он может выполнять **весь спектр CLI, включая мутации** (создание/ротация/отключение API ключей, изменение параметров организации, разрешение инцидентов, удаление сохранённых запросов), ограниченный только разрешениями вашего CLI входа. Относитесь к нему ровно так же осторожно, как если бы вы вводили эти команды вручную. --- ## Предварительные требования -1. **`agenteye` CLI установлен** и находится в `PATH` (см. [CLI](/ru/agenteye/cli) справочник: `pipx install agenteye`). -2. Ваш **URL приборной панели установлен** (`AGENTEYE_DASHBOARD_URL`, или agent передаёт `--base-url`). -3. **Сессия с аутентификацией**: сначала запустите `agenteye login` сами. Skill **не может** завершить отправку одноразового кода по электронной почте за вас; он подскажет вам запустить `agenteye login`, если сессия отсутствует или истекла (CLI код выхода `4`). +1. **`agenteye` CLI установлен** и в `PATH` (см. справочник [CLI](/ru/agenteye/cli): `pipx install agenteye`). +2. Ваш **URL дашборда установлен** (`AGENTEYE_DASHBOARD_URL`, или агент передаёт `--base-url`). +3. **Авторизованный сеанс**: сначала запустите `agenteye login` сами. Навык **не может** завершить отправленный по почте одноразовый код входа за вас; он скажет вам запустить `agenteye login`, если сеанс отсутствует или истёк (код выхода CLI `4`). --- -## Где это взять +## Где это получить -Skill опубликован в публичной коллекции skills Failproof AI: +Навык опубликован в публичной коллекции навыков Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -Ничто в нём не защищено — репозиторий открыт, и skill не требует собственных учётных данных, потому что он только управляет **публичным** `agenteye` CLI против *вашей* приборной панели, используя сессию, под которую *вы* вошли. Вам не нужно ничего у кого-то просить. +Ничего в нём не контролируется — репозиторий публичный и навык не требует собственных учётных данных, так как он только управляет **публичным** CLI `agenteye` для *вашего* дашборда, используя сеанс *вашего* входа. Вам не нужно просить его у кого-либо. -Обратите внимание, что он поставляется как отдельная папка и **не находится** в пакете `pipx install agenteye`, поэтому не ищите его там. +Учтите, что он поставляется как отдельная папка и **не входит** в пакет `pipx install agenteye`, поэтому не ищите его там. -## Установка skill +## Установка навыка -Самый быстрый способ — это [`skills`](https://skills.sh) CLI, который загружает папку и размещает её там, где ваш agent её ищет: +Самый быстрый способ — это CLI [`skills`](https://skills.sh), который загружает папку и кладёт её туда, где ваш агент её ищет: ```bash # Claude Code, только этот проект @@ -74,86 +74,86 @@ npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -Затем управляйте им как любым другим skill: +Затем управляйте им как любым другим навыком: ```bash npx skills list -a claude-code # что установлено -npx skills update agenteye-cli # загрузить последнюю версию +npx skills update agenteye-cli # получить последнюю версию npx skills remove agenteye-cli # удалить его ``` -Предпочитаете установку вручную? Agent Skill — это просто папка, содержащая `SKILL.md` (плюс дополнительные справки), поэтому копирование тоже работает: +Предпочитаете устанавливать вручную? Agent Skill — это просто папка, содержащая `SKILL.md` (плюс опциональные справочники), поэтому копирование тоже работает: -- **Claude Code**: положите папку `agenteye-cli/` в `~/.claude/skills/` (каждый проект) или `<ваш-репо>/.claude/skills/` (только этот репо). Claude Code автоматически её обнаруживает — проверьте со списком `/skills` или просто задайте вопрос, который совпадает с её описанием. -- **Codex (OpenAI)**: Codex читает тот же `SKILL.md`. Включённый `agents/openai.yaml` устанавливает `allow_implicit_invocation: true`, поэтому Codex автоматически выбирает skill, когда задача совпадает; в противном случае вызовите его явно как `$agenteye-cli`. +- **Claude Code**: поместите папку `agenteye-cli/` в `~/.claude/skills/` (каждый проект) или `<ваш-репо>/.claude/skills/` (только этот репо). Claude Code автоматически обнаруживает её — проверьте через список `/skills` или просто задайте вопрос, соответствующий её описанию. +- **Codex (OpenAI)**: Codex читает тот же `SKILL.md`. Входящий в комплект `agents/openai.yaml` устанавливает `allow_implicit_invocation: true`, поэтому Codex автоматически выбирает навык, когда задача совпадает; в противном случае вызовите его явно как `$agenteye-cli`. --- -## Безопасность: изменения НЕ требуют подтверждения, когда agent запускает CLI +## Безопасность: мутации НЕ запрашивают подтверждение, когда агент запускает CLI -> **Warning:** Прочитайте это перед тем, как позволить agent вносить изменения. +> **Внимание:** Прочитайте это перед тем, как позволить агенту вносить изменения. -`agenteye` CLI обычно запрашивает *«ты уверен?»* перед деструктивным действием. Он **автоматически пропускает это подтверждение, когда он не подключён к терминалу (что является в точности тем, как coding agent его запускает), и `--json` тоже пропускает это.** Поэтому подсказка о безопасности **не будет** активирована для agent. +CLI `agenteye` обычно спрашивает *«вы уверены?»* перед деструктивным действием. Он **автоматически пропускает это подтверждение, когда он не подключён к терминалу (что ровно то, как кодирующий агент его запускает), и `--json` тоже его пропускает.** Поэтому подсказка безопасности **не срабатывает** для агента. -Skill написан, чтобы это компенсировать: ему дано указание указать точную команду, которую он будет запускать, и получить ваше явное **ОК перед любым изменением состояния**. Соблюдайте эту дисциплину. Когда вы управляете Failproof AI Observability через agent, *вы* — это шаг подтверждения. Команды, изменяющие состояние, на которые нужно обратить внимание: +Навык написан для компенсации: ему инструктируется указать точную команду, которую он будет запускать, и получить ваше явное **ОК перед любым изменением состояния**. Сохраняйте эту дисциплину. Когда вы управляете Failproof AI Observability через агента, *вы* являетесь шагом подтверждения. Команды, изменяющие состояние, на которые нужно обратить внимание: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` - `settings set` - `alerts create` / `update` / `delete` / `test` -- команды записи `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` +- подкоманды записи `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` - `query create` / `update` / `delete` - `agent rename` / `delete` - `orgs switch` -Всё под **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) — только для чтения и ничего не меняет. +Всё под **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) только для чтения и ничего не изменяет. -Поскольку agent действует от вас, он может делать только то, что разрешено вашей сессией; разрешения разрешаются **на организацию** (см. [API keys](/ru/agenteye/api-keys)). Команда, на которую у вас нет разрешения, возвращает код выхода `5` с точно названным разрешением, поэтому agent может точно сказать вам, что просить у администратора, вместо того чтобы неясно отказать. +Поскольку агент действует как **вы**, он может делать только то, что вашему входу разрешено делать; разрешения разрешаются **по организации** (см. [API ключи](/ru/agenteye/api-keys)). Команда, на которую у вас нет разрешения, возвращает код выхода `5` с точно названным разрешением, поэтому агент может точно сказать вам, что просить у администратора, вместо того чтобы неудачно молчать. --- -## Что вы можете его попросить +## Что вы можете у него спросить -Вот что выглядит реальный обмен, сначала чтение, затем изменение, которое ждёт вашего ОК: +Вот как выглядит реальный обмен туда-обратно, чтение, а затем изменение, которое ждёт вашего ОК: ```text -вы ▸ Что-нибудь сломалось за последний день? +вы ▸ Что-то сломалось в последний день? -agent ▸ Запуск: agenteye --json errors --since 24h --aggregate - 3 типа ошибок за последние 24 часа. Самый большой — TimeoutError +агент ▸ Выполняю: agenteye --json errors --since 24h --aggregate + 3 типа ошибок за последние 24ч. Самая большая — TimeoutError (18 попаданий, все на checkout-agent), затем RateLimited (5). - Хотите получить сбойные сессии для TimeoutError? + Хотите видеть падающие сеансы для TimeoutError? вы ▸ Выдай CI ключ, который может только отправлять события. -agent ▸ Это создаёт API ключ. Я запущу: +агент ▸ Это создаст API ключ. Я выполню: agenteye keys create ci --add events:add - Продолжить? + ОК продолжить? вы ▸ да -agent ▸ Готово. Ключ "ci" создан с только events:add. - Секрет показан только один раз, поэтому сохраните его сейчас. Я не могу его переиспечатать. +агент ▸ Готово. Ключ "ci" создан только с events:add. + Секрет показывается только один раз, поэтому сохраните его сейчас. Я не могу его перепечатать. ``` -Skill отображает каждое намерение на простом языке на правильную `agenteye` команду, сначала открывая допустимые значения (`list `, `whoami`), чтобы не угадывать, и указывая точную команду перед любым изменением. Больше примеров: +Навык отображает каждое намерение на естественном языке на правильную команду `agenteye`, сначала обнаруживая действительные значения (`list `, `whoami`), чтобы он не угадывал, и указывая точную команду перед любым изменением. Ещё примеры: -- *«Что-нибудь сломалось / сбойное за последние 24 часа?»* → `errors --since 24h --aggregate`, затем разбивка. -- *«Почему сессия `run-001` сбойная?»* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *«Как качество тренднулось на этой неделе?»* → `evals --aggregate --since 7d`, затем углубиться в низко оценённые прогоны. -- *«Выдай CI ключ, который может только отправлять события»* → `keys create ci --add events:add` (он указывает команду, затем создаёт её и захватывает одноразовый секрет). -- *«Кто имеет доступ? Сделай Dana только для чтения»* → `users list` → `users update dana@… --permission-set read-only` (после подтверждения с вами). -- *«Подтверди активный инцидент и назначь его на меня»* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. +- *«Что-то сломалось / отказывает в последние 24 часа?»* → `errors --since 24h --aggregate`, затем описание. +- *«Почему сеанс `run-001` отказал?»* → `events --session-id run-001 --all` + `evals --session-id run-001`. +- *«Как качество меняется на неделю?»* → `evals --aggregate --since 7d`, затем углубление в низкооценённые прогоны. +- *«Выдай CI ключ, который может только отправлять события.»* → `keys create ci --add events:add` (она указывает команду, затем создаёт её и захватывает одноразовый секрет). +- *«Кто имеет доступ? Сделай Dana только для чтения.»* → `users list` → `users update dana@… --permission-set read-only` (после подтверждения с вами). +- *«Подтверди активный инцидент и назначь его на меня.»* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. -Для точных команд, флагов и JSON форм за этим смотрите справочник [CLI](/ru/agenteye/cli) и [CLI recipes для agents](/ru/agenteye/cli-recipes). +Для точных команд, флагов и JSON форм за ними, см. справочник [CLI](/ru/agenteye/cli) и [CLI рецепты для агентов](/ru/agenteye/cli-recipes). --- -## Следующие шаги +## Дальнейшие шаги - **[CLI](/ru/agenteye/cli)**: полный справочник команд и флагов для `agenteye`. -- **[CLI recipes для agents](/ru/agenteye/cli-recipes)**: шаблоны `jq` и обработка кодов выхода для копирования и вставки. -- **[Evaluator agent skill](/ru/agenteye/evaluator-skill)**: родственный skill для создания evaluator, чьи баллы читает `agenteye evals`. -- **[Python SDK agent skill](/ru/agenteye/python-sdk-skill)**: родственный skill для инструментирования agent, чтобы он испускал телеметрию, которую читает `agenteye`. -- **[AI assistant](/ru/agenteye/assistant)**: in-dashboard ассистент (не путать с этим terminal skill). -- **[API keys](/ru/agenteye/api-keys)**: модель разрешений на организацию, которая ограничивает то, что может делать skill. \ No newline at end of file +- **[CLI рецепты для агентов](/ru/agenteye/cli-recipes)**: готовые к вставке паттерны `jq` и обработка кодов выхода. +- **[Evaluator агент навык](/ru/agenteye/evaluator-skill)**: родственный навык для построения оценивателя, чьи оценки читает `agenteye evals`. +- **[Python SDK агент навык](/ru/agenteye/python-sdk-skill)**: родственный навык для инструментирования агента, чтобы он излучал телеметрию, которую читает `agenteye`. +- **[AI ассистент](/ru/agenteye/assistant)**: встроенный в дашборд ассистент (не путайте с этим терминальным навыком). +- **[API ключи](/ru/agenteye/api-keys)**: модель разрешений по организации, которая ограничивает то, что может делать навык. \ No newline at end of file diff --git a/docs/ru/agenteye/cli.mdx b/docs/ru/agenteye/cli.mdx index 58c0b5df..7bceb624 100644 --- a/docs/ru/agenteye/cli.mdx +++ b/docs/ru/agenteye/cli.mdx @@ -1,34 +1,33 @@ --- title: "CLI" -description: "Управляйте всеми функциями Failproof AI Observability из терминала или скрипта: без навигации по веб-интерфейсу." +description: "Управляйте всем Failproof AI Observability из терминала или скрипта: без необходимости обращаться к веб-интерфейсу." --- - -Управляйте всеми функциями Failproof AI Observability из терминала или скрипта: без навигации по веб-интерфейсу. CLI `agenteye` позволяет запрашивать ваши данные (сеансы, журналы событий, оценки) и администрировать организацию (API ключи, пользователи, параметры, оповещения, инциденты, сохранённые запросы), поэтому используйте его для автоматизации проверок, интеграции Observability в CI или инспекции продакшена посредством coding agent. Каждая команда поддерживает флаг `--json`, поэтому работает одинаково хорошо как для вас в терминале, так и для coding agent'а (Claude Code, Cursor), выполняющего команду и разбирающего результат. +Управляйте всем Failproof AI Observability из терминала или скрипта: без необходимости обращаться к веб-интерфейсу. CLI `agenteye` запрашивает ваши данные (сеансы, логи событий, оценки) и администрирует вашу организацию (API-ключи, пользователи, параметры, оповещения, инциденты, сохранённые запросы), поэтому используйте его, когда хотите автоматизировать проверку, интегрировать Observability в CI или дать кодирующему агенту инспектировать production. Каждая команда поддерживает флаг `--json`, поэтому она работает одинаково хорошо как для вас в командной строке, так и для кодирующего агента (Claude Code, Cursor), вызывающего её и обрабатывающего результат. С одним бинарным файлом вы можете: - **Читать ваши данные**: `sessions`, `events`, `evals`, `errors` (фильтровать по времени, агенту, окружению, оценке). - **Управлять организацией**: `keys`, `users`, `settings`, `alerts`, `incidents`. -- **Запускать аналитику**: сохранённый SQL и интерактивный runner запросов (`query`). -- **Общаться с AI помощником**: тем же read-only аналитиком, с которым вы общаетесь в веб-интерфейсе (`agent`). +- **Запускать аналитику**: сохранённый SQL и интерактивный запросчик (`query`). +- **Общаться с AI-ассистентом**: тот же только-чтение аналитик, с которым вы общаетесь в веб-интерфейсе (`agent`). -> **Примечание:** Это CLI `agenteye`, отличный инструмент от демона-коллектора (`agenteye-collector`). CLI общается с вашим веб-интерфейсом; коллектор отправляет события на сервер. +> **Примечание:** Это CLI `agenteye`, другой инструмент, чем демон-сборщик (`agenteye-collector`). CLI общается с вашим веб-интерфейсом; сборщик отправляет события на сервер. --- ## Быстрый старт -От нуля до первого результата в четыре строки. Укажите CLI адрес вашего веб-интерфейса, войдите, подтвердите вашу личность, затем получите запуски за последний день: +От нуля до первого результата в четыре строки. Укажите CLI на ваш веб-интерфейс, войдите, подтвердите вашу личность, а затем получите запуски за последний день: ```bash pipx install agenteye -agenteye --base-url https://agenteye.example.com login --email you@example.com # emailed 6-digit code -agenteye whoami # confirm user + active org -agenteye --json sessions --since 24h # one row per agent run, last 24h +agenteye --base-url https://agenteye.example.com login --email you@example.com # на почту отправлен 6-значный код +agenteye whoami # подтвердить пользователя + активную организацию +agenteye --json sessions --since 24h # одна строка на один запуск агента, за последние 24ч ``` -Последняя команда выводит JSON объект последних сеансов (от новейших к старым, по умолчанию не более 50). Пропустите через `jq` для выборки, или опустите `--json` для таблицы в рамке с раскраской. Каждая строка содержит статус запуска и, если оценщик его оценил, его метрики (сокращено): +Последняя команда выводит JSON-объект самых последних сеансов (новые в начале, по умолчанию ограничено 50). Передайте его в `jq` для среза или удалите `--json` для выделенной цветной таблицы. Каждая строка содержит статус запуска и, если его оценила система оценок, метрики (здесь сокращены): ```json { @@ -48,65 +47,65 @@ agenteye --json sessions --since 24h } ``` -Остальная часть этой страницы объясняет каждый элемент: [установка](#installation) отдельно, [вход](#authentication), [конфигурация](#configuration), [глобальные соглашения](#global-options--conventions), общие для каждой команды, и [полный справочник команд](#command-reference). +Далее на этой странице объясняется каждый элемент: [установка](#installation) отдельно, [вход](#authentication), [конфигурация](#configuration), [глобальные соглашения](#global-options--conventions), которые разделяют все команды, и [полный справочник команд](#command-reference). --- ## Установка -CLI — это общедоступный пакет PyPI с именем **`agenteye`**. Установите его в изолированную среду, чтобы он всегда имел свои собственные зависимости: +CLI — это публичный пакет PyPI с именем **`agenteye`**. Установите его в изолированное окружение, чтобы он всегда имел собственные зависимости: ```bash pipx install agenteye -# or +# или uv tool install agenteye ``` -Требует Python 3.10+. Установленная команда — **`agenteye`**: +Требуется Python 3.10+. Установленная команда — **`agenteye`**: ```bash agenteye --version agenteye --help ``` -> **Примечание:** Python SDK Failproof AI Observability также использует имя дистрибутива `agenteye`. Установка CLI с помощью `pipx` или `uv tool` (вместо `pip install` в общую virtualenv) предотвращает их конфликт. Простой `pip install agenteye` допустим только если SDK не установлен в той же среде. +> **Примечание:** Python SDK Failproof AI Observability также использует имя дистрибутива `agenteye`. Установка CLI через `pipx` или `uv tool` (вместо `pip install` в общий virtualenv) предотвращает их конфликт. Простой `pip install agenteye` приемлем только если SDK не установлен в том же окружении. --- ## Аутентификация -CLI аутентифицируется на **веб-интерфейсе** с одноразовым кодом, отправленным по электронной почте: +CLI аутентифицируется на **веб-интерфейсе** с помощью высланного одноразового кода: ```bash agenteye login --email you@example.com -# A 6-digit code is emailed to you; paste it at the prompt. +# 6-значный код высылается вам; вставьте его в приглашение. ``` -Токен сеанса хранится в `~/.agenteye/cli.json` (доступен только вам, режим `0600`) и действителен 24 часа по умолчанию. Когда он истекает, снова запустите `agenteye login`. +Токен сеанса сохраняется в `~/.agenteye/cli.json` (читаем только вами, режим `0600`) и действителен по умолчанию 24 часа. Когда он истечёт, запустите `agenteye login` снова. ```bash -agenteye whoami # show the current user, active org, and permissions -agenteye logout # revoke the session and clear the stored token +agenteye whoami # показать текущего пользователя, активную организацию и разрешения +agenteye logout # отозвать сеанс и удалить сохранённый токен ``` -`whoami` никогда не выводит ошибку при отсутствующем или истекшем сеансе; вместо этого сообщает `logged_in: false`, поэтому скрипт или агент могут безопасно проверить состояние аутентификации (он всё ещё может выйти с кодом non-zero если не установлен базовый URL или веб-интерфейс недоступен). +`whoami` никогда не выдаёт ошибку при отсутствии или истечении сеанса; вместо этого сообщает `logged_in: false`, поэтому скрипт или агент может безопасно проверить состояние аутентификации (всё ещё может выход ненулевой, если базовый URL не установлен или веб-интерфейс недоступен). -**Требования:** ваша электронная почта должна быть разрешена для входа в веб-интерфейс (обратитесь к администратору Failproof AI Observability), и веб-интерфейс должен быть доступен по его базовому URL (см. [Конфигурация](#configuration)). Если вы запросили код и он не приходит, ваша электронная почта вероятно ещё не активирована для доступа к веб-интерфейсу. +**Требования:** ваша почта должна быть разрешена для входа в веб-интерфейс (обратитесь к администратору Failproof AI Observability), и веб-интерфейс должен быть доступен по его базовому URL (см. [Конфигурация](#configuration)). Если вы запросили код и он не пришёл, ваша почта, вероятно, ещё не активирована для доступа к веб-интерфейсу. --- -## Выбор вашей организации (мультитенантность) +## Выбор организации (мультитенантность) -Если ваш аккаунт принадлежит более чем одной организации, выберите активную **при входе**; она сохраняется и используется для каждой последующей команды: +Если ваша учётная запись принадлежит более чем одной организации, выберите активную **при входе**; она сохраняется и используется для каждой последующей команды: ```bash -agenteye login --org acme # authenticate and set the active tenant in one step -agenteye orgs list # the orgs you can access (the active one is marked) -agenteye orgs switch globex # change the saved default -agenteye --org globex sessions # override for a single command +agenteye login --org acme # аутентифицироваться и установить активный тенант за раз +agenteye orgs list # организации, к которым вы можете получить доступ (активная отмечена) +agenteye orgs switch globex # изменить сохранённое значение по умолчанию +agenteye --org globex sessions # переопределить для одной команды ``` -Если вы принадлежите ровно одной организации, она выбирается автоматически и вы можете полностью игнорировать `--org`. Если вы принадлежите нескольким и не выбрали одну, CLI выведет их список и попросит перезапустить с `--org `. Активная организация отправляется на веб-интерфейс при каждом запросе, и ваши разрешения разрешаются **по организации**; `agenteye whoami` показывает активную организацию, ваши разрешения в ней и все ваши членства. +Если вы принадлежите ровно одной организации, она выбирается автоматически и вы можете полностью игнорировать `--org`. Если вы принадлежите нескольким и не выбрали одну, CLI их перечислит и попросит вас переустановить с `--org `. Активная организация отправляется на веб-интерфейс с каждым запросом, и ваши разрешения разрешаются **по организации**; `agenteye whoami` показывает активную организацию, ваши разрешения в ней и все ваши членства. --- @@ -114,212 +113,212 @@ agenteye --org globex sessions # override for a single command | Параметр | Флаг | Переменная окружения | По умолчанию | |---|---|---|---| -| Базовый URL веб-интерфейса | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **требуется** (нет значения по умолчанию) | +| Базовый URL веб-интерфейса | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **обязателен** (нет по умолчанию) | | Активная организация/тенант | `--org` | `AGENTEYE_ORG` | выбирается при входе; сохраняется в `~/.agenteye/cli.json` | | Токен сеанса | `--token` | `AGENTEYE_CLI_TOKEN` | из `~/.agenteye/cli.json` | -| JSON вывод | `--json` | `AGENTEYE_CLI_JSON` | выключен | -| Пропустить проверку TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | выключена (сохраняется при входе) | -| Timeout запроса (секунды) | `--timeout` | _(нет)_ | 30 | -| Отключить телеметрию использования | _(нет)_ | `AGENTEYE_ANALYTICS_DISABLED` (или `DO_NOT_TRACK`) | телеметрия в данный момент отключена; ничего не отправляется | +| JSON-вывод | `--json` | `AGENTEYE_CLI_JSON` | выключено | +| Пропустить проверку TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | выключено (сохраняется при входе) | +| Тайм-аут запроса (секунды) | `--timeout` | _(отсутствует)_ | 30 | +| Отключить телеметрию использования | _(отсутствует)_ | `AGENTEYE_ANALYTICS_DISABLED` (или `DO_NOT_TRACK`) | телеметрия в настоящий момент отключена; ничего не отправляется | -Порядок разрешения: **флаг → переменная окружения → файл конфигурации**. По умолчанию нет; вы должны указать CLI адрес вашего веб-интерфейса, либо в каждой команде (`--base-url https://agenteye.example.com`), либо один раз через окружение (также сохраняется после первого `login`): +Порядок разрешения: **флаг → переменная окружения → файл конфигурации**. По умолчанию нет; вы должны указать CLI на ваш веб-интерфейс, либо для каждой команды (`--base-url https://agenteye.example.com`), либо один раз через окружение (он также сохраняется после первого `login`): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -Директория конфигурации соответствует `AGENTEYE_HOME` (то же соглашение, что и SDK и коллектор); если установлена, `cli.json` живёт в `$AGENTEYE_HOME/cli.json`. +Директория конфигурации соблюдает `AGENTEYE_HOME` (то же соглашение, что используют SDK и сборщик); если установлена, `cli.json` находится в `$AGENTEYE_HOME/cli.json`. -### Self-signed или внутренний TLS +### Самоподписанный или внутренний TLS -Если ваш веб-интерфейс обслуживается через HTTPS с self-signed или внутренним сертификатом (например, raw hostname load balancer'а), проверка TLS отклоняет его с ошибкой `CERTIFICATE_VERIFY_FAILED`. Передайте `--insecure` чтобы пропустить проверку сертификата: +Если ваш веб-интерфейс обслуживается по HTTPS с самоподписанным или внутренним сертификатом (например, имя хоста балансировщика нагрузки), проверка TLS отклоняет его ошибкой `CERTIFICATE_VERIFY_FAILED`. Передайте `--insecure` для пропуска проверки сертификата: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` **сохраняется в `cli.json` при входе**, поэтому последующие команды автоматически пропускают проверку; вам не нужно повторять флаг. Передайте `--secure` для разовой проверяемой команды, или чтобы сохранить проверку при следующем входе. CLI выводит предупреждение в stderr перед любой командой, контактирующей с веб-интерфейсом при отключённой проверке. Пропуск проверки убирает защиту от атак man-in-the-middle; убедитесь, что вы доверяете сетевому пути к вашему веб-интерфейсу (VPN, приватная сеть и т.д.) перед его использованием. +`--insecure` **сохраняется в `cli.json` при входе**, поэтому последующие команды пропускают проверку автоматически; вам не нужно повторять флаг. Передайте `--secure` для одноразового проверенного вызова или чтобы сохранить проверку обратно при следующем входе. CLI выводит предупреждение в stderr перед любой командой, которая обращается к веб-интерфейсу с отключённой проверкой. Пропуск проверки снимает защиту от атак типа человек-в-середине; убедитесь, что вы доверяете сетевому пути к вашему веб-интерфейсу (VPN, приватная подсеть и т. д.) перед тем как на неё полагаться. --- -## Телеметрия и приватность +## Телеметрия и конфиденциальность -> **Примечание:** Поставляемый CLI **на данный момент не отправляет никакую телеметрию.** Главный выключатель включён, поэтому ничего не передаётся независимо от вашего окружения. Раздел ниже описывает возможность отключения на случай, если телеметрия когда-либо будет включена. +> **Примечание:** Поставляемый CLI **сегодня не отправляет телеметрию использования.** Главный переключатель включен, поэтому ничего не передаётся независимо от вашего окружения. Раздел ниже описывает возможность отказа на случай, если телеметрия когда-нибудь будет включена. -Даже если включена, телеметрия была бы **только анонимной аналитикой использования**, никогда не ваши данные агента, сеанса или события: +Даже если включена, телеметрия была бы **только анонимной аналитикой использования**, никогда вашими агентом, сеансом или данными событий: -- **Данные агента, сеанса или события никогда не покидают вашу инфраструктуру.** Только использование CLI будет сообщаться: имя команды и подкоманды (например `keys create`), **имена** используемых флагов (никогда их значения), статус успеха/выхода и длительность, плюс пер-событие для мутаций (например `api_key_created`, `query_run`) содержащее только статические имена/enums и грубые подсчёты. Ваш URL веб-интерфейса, токен сеанса, электронная почта, slug организации, id ресурсов, SQL, секреты ключей и фильтры запросов **никогда** не будут отправлены. Операторы будут идентифицированы только по opaque internal id, никогда по электронной почте. -- **Отключитесь заранее**, установив `AGENTEYE_ANALYTICS_DISABLED=1` в окружение CLI (CLI также соответствует кроссинструментальному соглашению `DO_NOT_TRACK=1`). Это вступает в силу в момент включения телеметрии, поэтому конфиденциальное окружение может оставаться отключённым постоянно. -- Если бы телеметрия была включена, CLI отправлял бы прямо в PostHog (`https://us.i.posthog.com`); машина с этим хостом в блокировке молча не отправляла бы ничего и CLI был бы не затронут. +- **Данные агента, сеанса или события никогда не покидают вашу инфраструктуру.** Сообщалось бы только использование CLI: имя команды и подкоманды (например, `keys create`), **имена** флагов, которые вы использовали (никогда их значения), статус успеха/выхода и длительность, плюс одно действие на событие для мутаций (например, `api_key_created`, `query_run`), содержащее только статические имена/перечисления и грубые счёты. Ваш URL веб-интерфейса, токен сеанса, электронная почта, слаг организации, идентификаторы ресурсов, SQL, секреты ключей и фильтры запросов **никогда** не будут отправлены. Операторы идентифицировались бы только непрозрачным внутренним идентификатором, никогда по электронной почте. +- **Откажитесь заранее**, установив `AGENTEYE_ANALYTICS_DISABLED=1` в окружении CLI (CLI также соблюдает кроссплатформенное соглашение `DO_NOT_TRACK=1`). Это вступает в силу в момент включения телеметрии, поэтому ориентированное на конфиденциальность окружение может оставаться отключённым постоянно. +- Если бы телеметрия была включена, CLI отправлял бы напрямую в PostHog (`https://us.i.posthog.com`); машина с заблокированным этим хостом молча отправляла бы ничего и CLI остался бы незатронут. --- ## Глобальные опции и соглашения -Прочитайте один раз; это применяется к каждой команде. +Прочитайте один раз; это применяется ко всем командам. -- **Глобальные опции идут ДО команды.** `agenteye --json sessions` верно; `agenteye sessions --json` это ошибка использования. Глобальные опции: `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, и `--no-color`. -- **`--json` выводит чистый JSON на stdout, и ничего больше.** Статусные строки для человека, предупреждения и ошибки идут в **stderr**, поэтому capture `--json` stdout остаётся чистым для передачи в `jq` даже если статусная строка показана. Без `--json` вы получаете рамочный, раскрашенный вид для человеческих глаз. -- **Открывайте с `--help`.** Каждая команда и подкоманда имеет `--help` (и alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. Топ-уровень help также выводит коды выхода и глобальные опции. Нет глобального машиночитаемого дампа поверхности; используйте пер-команду `--help`, плюс доменно-специфичные `agenteye query schema` и `agenteye settings schema` для этих двух реестров. -- **Подтверждения авто-пропускаются для скриптов и агентов.** Команды create/update/delete выводят запрос "вы уверены?" в интерактивном терминале, но **авто-пропускают этот запрос под `--json` или когда stdin не TTY** (TTY это интерактивная сессия терминала; pipe или CI runner это не так), поэтому скрипты и агенты никогда не зависают. Передайте `--yes`/`-y` чтобы явно пропустить. Потому что запрос не срабатывает для агента, агент должен подтвердить деструктивные действия с человеком сначала. -- **Пагинация:** результаты от новейших к старым и cursor-paginated (каждая страница возвращает токен для получения следующей). `--limit N` (alias `-n`) ограничивает строки и **по умолчанию 50**; `--all` авто-пагинирует (по 200-строковым блокам) **вплоть до `--limit`**, поэтому bare `--all` всё ещё останавливается на 50. Для полного сканирования передайте высокий явный лимит: `--all --limit 1000`. `--page-size N` контролирует пер-запрос блок (макс 200); `--cursor ` возобновляет с предыдущей `next_cursor` страницы. -- **Временные фильтры:** `--since` принимает относительное окно: `15m`, `1h`, `6h`, `24h`, `7d`, или `all` (предустановки веб-интерфейса). Для более длинного или пользовательского диапазона (скажем последние 30 дней), используйте `--from`/`--to`: явные ISO-8601 UTC timestamps **с `T` и временной зоной** (например `2026-06-01T00:00:00Z`) которые переопределяют `--since`. Значение с пробелом или без временной зоны это ошибка использования. -- **`--fields a,b,c`** (на `events`, `sessions`, `evals`, `errors`) ограничивает вывод этими ключами, как для таблицы, так и `--json`. Неизвестные имена отклоняются с валидным списком, дешёвый способ открыть имена полей. -- **`--file payload.json`** (или `--file -` чтобы читать stdin) поставляет полное JSON тело запроса где ресурс имеет сложную форму (на `alerts create/update`, `settings set`, и `users create/update`). Сохранённый SQL запроса использует `--sql @file.sql` вместо. -- **Мультизначные фильтры** разделены запятыми → совпадают как набор (объединение внутри одного фильтра, AND поперёк фильтров): `--event-type tool_use,tool_result`. Клик опции не вариадичны, поэтому `--add a b` ломается. Используйте `--add a,b`, повторяйте флаг (`--add a --add b`), или кавычки (`--add "a b"`). +- **Глобальные опции идут ДО команды.** `agenteye --json sessions` — правильно; `agenteye sessions --json` — ошибка использования. Глобальные — это `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` и `--no-color`. +- **`--json` выводит чистый JSON в stdout и ничего больше.** Строки статуса человека, предупреждения и ошибки идут в **stderr**, поэтому захват stdout с `--json` остаётся чистым для передачи в `jq` даже когда показана строка статуса. Без `--json` вы получаете выделенный цветной вид для человеческих глаз. +- **Откройте с `--help`.** Каждая команда и подкоманда имеет `--help` (и псевдоним `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. Справка верхнего уровня также перечисляет коды выхода и глобальные опции. Нет глобального машиночитаемого дампа поверхности; используйте для каждой команды `--help`, плюс предметно-специфичные `agenteye query schema` и `agenteye settings schema` для этих двух реестров. +- **Подтверждения автоматически пропускаются для скриптов и агентов.** Команды создания/обновления/удаления выдают "вы уверены?" в интерактивном терминале, но **автоматически пропускают это приглашение под `--json` или когда stdin не является TTY** (TTY — это сеанс интерактивного терминала; канал или CI-runner — нет), поэтому скрипты и агенты никогда не зависают. Передайте `--yes`/`-y` для явного пропуска. Так как приглашение не выдаётся агенту, агент должен подтвердить деструктивные действия с человеком сначала. +- **Пагинация:** результаты самые новые сначала и с курсорной пагинацией (каждая страница возвращает токен, который вы используете для получения следующей). `--limit N` (псевдоним `-n`) ограничивает строки и **по умолчанию равен 50**; `--all` автоматически разбивает на страницы (в куски по 200 строк) **вплоть до `--limit`**, поэтому голая `--all` всё ещё останавливается на 50. Для полного охвата передайте высокий явный лимит: `--all --limit 1000`. `--page-size N` контролирует размер куска за запрос (максимум 200); `--cursor ` продолжает с предыдущего `next_cursor` страницы. +- **Фильтры времени:** `--since` принимает относительное окно: `15m`, `1h`, `6h`, `24h`, `7d` или `all` (предустановки веб-интерфейса). Для более длительного или пользовательского диапазона (скажем, последние 30 дней) используйте `--from`/`--to`: явные ISO-8601 UTC временные метки **с `T` и часовым поясом** (например, `2026-06-01T00:00:00Z`), которые переопределяют `--since`. Значение с пробелом или без часового пояса — ошибка использования. +- **`--fields a,b,c`** (на `events`, `sessions`, `evals`, `errors`) ограничивает вывод этими ключами, как для таблицы, так и для `--json`. Неизвестные имена отклоняются с действительным списком — дешёвый способ открыть имена полей. +- **`--file payload.json`** (или `--file -` для чтения stdin) предоставляет полное тело запроса JSON, где ресурс имеет сложную форму (на `alerts create/update`, `settings set` и `users create/update`). Сохранённый SQL использует `--sql @file.sql` вместо этого. +- **Фильтры с несколькими значениями** разделены запятыми → сопоставлены как набор (объединение в одном фильтре, И через фильтры): `--event-type tool_use,tool_result`. Опции клика не вариативны, поэтому `--add a b` ломается. Используйте `--add a,b`, повторяйте флаг (`--add a --add b`) или кавычки (`--add "a b"`). --- ## Справочник команд -### Вы будете использовать эти 5 команд больше всего +### Вы будете использовать эти 5 команд чаще всего -Большая часть повседневной работы проходит через несколько команд чтения. Начните отсюда, затем обращайтесь к полной поверхности ниже когда вам это понадобится: +Большинство повседневных работ выполняется через несколько команд чтения. Начните отсюда, затем обратитесь к полной поверхности ниже когда вам это понадобится: | Команда | Что она делает | Попробуйте | |---|---|---| | `sessions` | Одна строка на запуск агента: время, окружение, агент, статус, последняя оценка. | `agenteye --json sessions --since 24h --status error` | -| `events` | Raw пер-шаг trail внутри запуска (добавьте `--full` для payloads). | `agenteye --json events --session-id run-001 --all` | -| `evals` | Результаты оценок и оценки; `--aggregate` их суммирует. | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | Только errored события; `--aggregate` для подсчётов по типу. | `agenteye --json errors --since 24h --aggregate` | -| `list` | Открывайте валидные значения фильтров (агенты, окружения, модели, …). | `agenteye list agents` | +| `events` | Сырой след за каждый шаг внутри запуска (добавьте `--full` для полезных нагрузок). | `agenteye --json events --session-id run-001 --all` | +| `evals` | Результаты оценок и оценки; `--aggregate` их свёртывает. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | Только события с ошибками; `--aggregate` для счётов по типам. | `agenteye --json errors --since 24h --aggregate` | +| `list` | Откройте действительные значения фильтров (агенты, окружения, модели, …). | `agenteye list agents` | -### Всё, что CLI может делать +### Всё, что может делать CLI -Полная поверхность следует. CLI имеет **18 топ-уровневых команд**. Все команды чтения принимают `--json` и глобальные опции выше; запустите `agenteye -h` (или ` -h`) для исчерпывающего списка флагов и JSON формы любой из них. +Следует полная поверхность. CLI имеет **18 команд верхнего уровня**. Все команды чтения принимают `--json` и глобальные опции выше; запустите `agenteye -h` (или ` -h`) для исчерпывающего списка флагов и JSON-формы любой из них. -### Идентичность: `login` · `logout` · `whoami` · `orgs` · `version` · `help` +### Идентификация: `login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash -agenteye login --email you@example.com [--org acme] # emailed one-time code; saves the session -agenteye logout # clear the saved session on this machine -agenteye whoami # current user, active org, permissions -agenteye version # print the CLI version (same as --version) -agenteye help # top-level help (same as --help) +agenteye login --email you@example.com [--org acme] # высланный одноразовый код; сохраняет сеанс +agenteye logout # очистить сохранённый сеанс на этой машине +agenteye whoami # текущий пользователь, активная организация, разрешения +agenteye version # вывести версию CLI (то же, что --version) +agenteye help # справка верхнего уровня (то же, что --help) ``` `orgs` проверяет и переключает активный тенант: ```bash -agenteye orgs list # your orgs + your role in each (active one marked) -agenteye orgs switch acme # change the saved active org (omit the slug to pick from a list on a TTY) -agenteye orgs current # identity card for the active org -agenteye orgs perms # your permissions in the active org, grouped by resource +agenteye orgs list # ваши организации + ваша роль в каждой (активная отмечена) +agenteye orgs switch acme # изменить сохранённую активную организацию (опустите слаг для выбора из списка на TTY) +agenteye orgs current # карточка идентификации активной организации +agenteye orgs perms # ваши разрешения в активной организации, сгруппированные по ресурсу ``` ### Наблюдение (только чтение): `events` · `sessions` · `evals` · `errors` · `list` -Ни одна из них не требует подтверждения. Общие фильтры: `--session-id`, `--agent-id`, `--env` (**не** `--environment`), и временной диапазон (`--since` / `--from` / `--to`). +Ни одна из них не нуждается в подтверждении. Общие фильтры: `--session-id`, `--agent-id`, `--env` (**не** `--environment`) и диапазон времени (`--since` / `--from` / `--to`). ```bash -# events (alias: the raw per-step trail), newest first +# events (псевдоним: сырой след за каждый шаг), новые в начале agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' -# sessions: one row per agent run (time/env/agent/session/status; no score filtering) +# sessions: одна строка на запуск агента (время/окружение/агент/сеанс/статус; без фильтрации по оценке) agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 -# evals: evaluation results + scores; --score filters by metric, --aggregate rolls up +# evals: результаты оценок + оценки; --score фильтрует по метрике, --aggregate свёртывает agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 -agenteye --json evals --aggregate --since 7d --env prod # status mix + per-key score stats +agenteye --json evals --aggregate --since 7d --env prod # микс статусов + статистика по оценке на ключ -# errors: errored events; --aggregate for counts/sessions/agents/last-seen +# errors: события с ошибками; --aggregate для счётов/сеансов/агентов/последнего-видения agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 -# list: discover valid filter values before you filter -agenteye list envs # also: agents event_types score_filters models hooks tools error_types +# list: откройте действительные значения фильтров перед фильтрацией +agenteye list envs # также: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (на **`evals`**, не `sessions`) повторяется и AND-комбинируется; либо граница опциональна (`..0.5` значит ≤ 0.5, `0.9..` значит ≥ 0.9). До 20 score фильтров за запрос. `evals --scores-full` это флаг отображения **только для таблицы человека**; показывает каждую пару оценок вместо первых нескольких плюс `+N` count. У этого нет эффекта под `--json`, который всегда возвращает полный score объект. Чтобы прочитать **один сеанс от начала до конца**, комбинируйте event trail с его оценкой: +`--score KEY:MIN..MAX` (на **`evals`**, не `sessions`) повторяемо и AND-комбинируется; любая граница опциональна (`..0.5` означает ≤ 0.5, `0.9..` означает ≥ 0.9). До 20 фильтров по оценкам за запрос. `evals --scores-full` — это флаг отображения **только для человеческой таблицы**; он показывает каждую пару оценок вместо первых нескольких плюс `+N` счёт. Это не влияет на `--json`, который всегда возвращает полный объект оценки. Чтобы прочитать **один сеанс от начала до конца**, объедините след событий с его оценкой: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -agenteye --json evals --session-id run-001 # its scores + status +agenteye --json evals --session-id run-001 # его оценки + статус ``` -### Управление (ограничено разрешениями): `keys` · `users` · `settings` · `alerts` · `incidents` +### Управление (защита разрешениями): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: API ключи. Секрет генерируется локально, отправляется на сервер (который хранит только хеш), и **показывается один раз** на create/regenerate; capture его тогда. С `--json` он появляется только в поле `key`. На которые ссылаются по **имени**. +**`keys`**: API-ключи. Секрет генерируется локально, отправляется на сервер (который хранит только хэш) и **показывается один раз** при создании/регенерации; захватите его тогда. С `--json` он появляется только в поле `key`. На которые ссылаются по **имени**. ```bash -agenteye keys list # active keys first, then revoked +agenteye keys list # активные ключи сначала, затем отозванные agenteye keys show ci-bot -agenteye keys create ci-bot --add events:read.add # scope to what you need; prints the secret ONCE -agenteye keys create ops --permission-set standard --remove queries:run # seed a preset, then trim +agenteye keys create ci-bot --add events:read.add # ограничить тем, что вам нужно; выводит секрет ОДИН РАЗ +agenteye keys create ops --permission-set standard --remove queries:run # начальное значение предустановки, затем урезать agenteye keys update ci-bot --add evaluations:read --yes -agenteye keys regenerate ci-bot --yes # rotate the secret (the old one stops working) -agenteye keys disable ci-bot --yes # revoke +agenteye keys regenerate ci-bot --yes # повернуть секрет (старый перестаёт работать) +agenteye keys disable ci-bot --yes # отозвать ``` -Разрешения работают как `(permission-set ∪ --add) − --remove`. Токены это `slug:action` (например `events:read`) или `slug:action.action` чтобы расширить несколько на одном ресурсе (`events:read.add` → `events:read`, `events:add`). Предустановки: `read-only`, `standard`, `admin`. Разрешения только для человека (`keys:update`) не могут быть предоставлены ключу. +Разрешения работают как `(permission-set ∪ --add) − --remove`. Токены — это `slug:action` (например, `events:read`) или `slug:action.action` для разворачивания нескольких на одном ресурсе (`events:read.add` → `events:read`, `events:add`). Предустановки: `read-only`, `standard`, `admin`. Разрешения только-человека (`keys:update`) не могут быть даны ключу. -**`users`**: члены организации, на которых ссылаются по **электронной почте** (UUID id также принимается). +**`users`**: члены организации, на которые ссылаются по **электронной почте** (также принимается UUID id). ```bash agenteye users list [--active-only] agenteye users show dev@corp.com agenteye users create dev@corp.com --permission-set standard -agenteye users update dev@corp.com --add alerts:write --remove queries:delete # predicts + confirms -agenteye users disable dev@corp.com --yes # has protected/self guards +agenteye users update dev@corp.com --add alerts:write --remove queries:delete # предсказывает + подтверждает +agenteye users disable dev@corp.com --yes # имеет защищённые/само-охраны agenteye users enable dev@corp.com ``` -**`settings`**: фиксированный реестр (вы читаете и меняете существующие ключи; вы не можете создавать новые). +**`settings`**: фиксированный реестр (вы читаете и изменяете существующие ключи; вы не можете создавать новые). ```bash -agenteye settings list # key · value · type · updated (secrets masked) -agenteye settings schema # what each key accepts (type · range · description) +agenteye settings list # ключ · значение · тип · обновлено (секреты скрыты) +agenteye settings schema # что каждый ключ принимает (тип · диапазон · описание) agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: определения оповещений, на которые ссылаются по **имени**. `create` принимает позиционный NAME плюс флаги или полное JSON тело через `--file`. +**`alerts`**: определения оповещений, на которые ссылаются по **имени**. `create` принимает позиционный NAME плюс флаги или полное тело JSON через `--file`. ```bash agenteye alerts list agenteye alerts show high-errors -agenteye alerts create high-errors --file alert.json # NAME is required (positional) +agenteye alerts create high-errors --file alert.json # NAME обязателен (позиционный) agenteye alerts update high-errors --severity critical --yes -agenteye alerts test high-errors --yes # fire a test notification +agenteye alerts test high-errors --yes # отправить тестовое уведомление agenteye alerts delete high-errors --yes ``` -**`incidents`**: инциденты оповещений, на которые ссылаются по id (короткие id принимаются). `show` выводит полный журнал активности; прочитайте перед действием. +**`incidents`**: инциденты оповещений, на которые ссылаются по id (принимаются короткие id). `show` выводит полный журнал активности; прочитайте перед действием. ```bash -agenteye incidents list --state firing # also: acknowledged, resolved +agenteye incidents list --state firing # также: acknowledged, resolved agenteye incidents count agenteye incidents show agenteye incidents ack -agenteye incidents assign you@corp.com # assignee must be an operator +agenteye incidents assign you@corp.com # ответственный должен быть оператором agenteye incidents resolve --yes -agenteye incidents open --alert-id --severity critical # open one manually against an alert +agenteye incidents open --alert-id --severity critical # открыть вручную против оповещения agenteye incidents comment-add "root cause: upstream 5xx" agenteye incidents comment-list ; agenteye incidents comment-delete agenteye incidents subscribe ; agenteye incidents unsubscribe ; agenteye incidents subscribers ``` -### Аналитика и помощник: `query` · `agent` +### Аналитика и ассистент: `query` · `agent` -**`query`**: сохранённый SQL против вашего хранилища аналитики плюс интерактивный runner. Сохранённые запросы на которые ссылаются по **имени**; SQL проверяется на сервере (SELECT/WITH только, statement timeout, row cap). +**`query`**: сохранённый SQL против вашего хранилища аналитики плюс интерактивный запросчик. Сохранённые запросы на которые ссылаются по **имени**; SQL проверяется на стороне сервера (только SELECT/WITH, тайм-аут оператора, лимит строк). ```bash -agenteye query schema [TABLE] # column layout of the analytics views +agenteye query schema [TABLE] # макет столбца аналитических представлений agenteye query run --sql "select count(*) from analytics.events" -agenteye query run errs --arg prod --limit 100 # run a saved query + a positional $1 +agenteye query run errs --arg prod --limit 100 # запустить сохранённый запрос + позиционный $1 agenteye query list ; agenteye query show errs agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: общается с встроенным **AI помощником** (тем же read-only аналитиком, с которым вы можете общаться в веб-интерфейсе). Чаты на которые ссылаются по короткому chat-id (prefix-resolved). +**`agent`**: общается со встроенным **AI-ассистентом** (тот же только-чтение аналитик, с которым вы можете общаться в веб-интерфейсе). Чаты на которые ссылаются по короткому chat-id (разрешение префиксом). ```bash -agenteye agent health # is the AI assistant configured/reachable -agenteye agent models # models you can pass to --model (default marked) -agenteye agent ask "which agents errored most in the last day?" # starts a chat; prints its short id -agenteye agent ask --chat "and which tools did they call?" # continue that chat +agenteye agent health # AI-ассистент настроен/доступен +agenteye agent models # модели, которые вы можете передать --model (по умолчанию отмечена) +agenteye agent ask "which agents errored most in the last day?" # начинает чат; выводит его короткий id +agenteye agent ask --chat "and which tools did they call?" # продолжить этот чат agenteye agent chats ; agenteye agent show agenteye agent rename --title "error triage" ; agenteye agent delete ``` @@ -331,20 +330,20 @@ agenteye agent rename --title "error triage" ; agenteye agent delete | Код | Значение | |---|---| | 0 | Успех | -| 1 | Неожиданная ошибка (например веб-интерфейс вернул 5xx) | -| 2 | Ошибка использования (неверные аргументы, неизвестная команда/флаг, конфликт имён) | +| 1 | Неожиданная ошибка (например, веб-интерфейс вернул 5xx) | +| 2 | Ошибка использования (неверные аргументы, неизвестная команда/флаг, коллизия имён) | | 3 | Невозможно достичь веб-интерфейс | -| 4 | Не залогированы или сеанс истёк; запустите `agenteye login` | -| 5 | Аутентифицирован, но ваш аккаунт не имеет требуемое разрешение (сообщение его указывает) | -| 6 | Запрашиваемый ресурс не найден (например неизвестный session или incident id) | +| 4 | Не авторизован или сеанс истёк; запустите `agenteye login` | +| 5 | Аутентифицирован, но ваша учётная запись лишена требуемого разрешения (сообщение его называет) | +| 6 | Запрашиваемый ресурс не найден (например, неизвестный session или incident id) | -Это делает CLI безопасным для скриптов: coding agent может ветвиться на `4` чтобы попросить вас переаутентифицироваться, или на `5` чтобы вывести отсутствующее разрешение. См. [CLI рецепты для агентов](/ru/agenteye/cli-recipes) для exit-code-handling паттернов и JSON output форм. +Это делает CLI безопасным для скриптов: кодирующий агент может ветвиться на `4` для запроса повторной аутентификации, или на `5` для всплывающего отсутствующего разрешения. Смотрите [CLI рецепты для агентов](/ru/agenteye/cli-recipes) для обработки кода выхода и JSON-форм. --- ## Следующие шаги -- **[CLI рецепты для агентов](/ru/agenteye/cli-recipes)**: copy-paste паттерны запросов, `jq` one-liners, `--fields` проекции, обработка exit-code, и JSON output формы, написанные для coding agents управляющих CLI. -- **[CLI агент скилл](/ru/agenteye/cli-skill)**: упакуйте этот CLI как устанавливаемый Claude Code / Codex *скилл* чтобы coding agent управлял Failproof AI Observability из plain-English запросов. -- **[API ключи](/ru/agenteye/api-keys)**: модель разрешений за `keys create --add …`. -- **[AI помощник](/ru/agenteye/assistant)**: включение помощника на который `agent ask` разговаривает. \ No newline at end of file +- **[CLI рецепты для агентов](/ru/agenteye/cli-recipes)**: скопируйте-вставьте шаблоны запросов, `jq` однострочники, проекции `--fields`, обработку кода выхода и JSON-формы, написанные для кодирующих агентов, управляющих CLI. +- **[CLI агентское умение](/ru/agenteye/cli-skill)**: упакуйте этот CLI как установляемое Claude Code / Codex *умение*, чтобы кодирующий агент управлял Failproof AI Observability из простых англоязычных запросов. +- **[API-ключи](/ru/agenteye/api-keys)**: модель разрешений за `keys create --add …`. +- **[AI-ассистент](/ru/agenteye/assistant)**: включение ассистента, с которым общается `agent ask`. \ No newline at end of file diff --git a/docs/ru/agenteye/codex-capture.mdx b/docs/ru/agenteye/codex-capture.mdx index 77567f0d..76584b90 100644 --- a/docs/ru/agenteye/codex-capture.mdx +++ b/docs/ru/agenteye/codex-capture.mdx @@ -1,55 +1,55 @@ --- -title: "Запись сессий Codex" -description: "Собирайте локальные сессии OpenAI Codex вашей команды в AgentEye как обычные сессии и события — без каких-либо изменений в том, как они запускают Codex." +title: "Capture сессий Codex" +description: "Переправляйте локальные сессии OpenAI Codex вашей команды в AgentEye как обычные сессии и события — без каких-либо изменений в том, как они запускают Codex." --- -Ваши инженеры уже ежедневно используют OpenAI Codex. Запись сессий Codex переносит эти сессии кодирования в AgentEye как обычные сессии и события, так что вы можете искать, проигрывать и оценивать их вместе со всем остальным, что вы наблюдаете. Это дополняет [Python SDK](/ru/agenteye/python-sdk): SDK инструментирует написанные вами агенты, а это захватывает работу в Codex, которую ваша команда уже выполняет — без каких-либо изменений в том, как они его запускают. +Ваши инженеры уже используют OpenAI Codex каждый день. Capture сессий Codex переносит эти сеансы кодирования в AgentEye как обычные сессии и события, так что вы можете искать, воспроизводить и оценивать их наряду со всем остальным, что вы наблюдаете. Это дополняет [Python SDK](/ru/agenteye/python-sdk): SDK инструментирует агентов, которых вы пишете, а это захватывает работу с Codex, которую уже выполняет ваша команда — без каких-либо изменений в том, как они его запускают. -Небольшой фоновый сборщик считывает локальные расшифровки сессий Codex по мере их записи и отправляет их в AgentEye. Один сборщик на машину захватывает все локальные поверхности Codex одновременно — настройка каждой поверхности не требуется. +Небольшой фоновый коллектор читает локальные транскрипты сессий Codex по мере их создания и отправляет их в AgentEye. Один коллектор на машину захватывает все локальные интерфейсы Codex одновременно — настройка для каждого интерфейса не требуется. -Тот же сборщик захватывает и других агентов — см. [OpenClaw](/ru/agenteye/openclaw-capture) и [Hermes](/ru/agenteye/hermes-capture). Включите каждого, кого вы запускаете; один сборщик может захватывать несколько одновременно. +Тот же коллектор захватывает и других агентов — см. [OpenClaw](/ru/agenteye/openclaw-capture) и [Hermes](/ru/agenteye/hermes-capture). Включите каждый из них, который вы используете; один коллектор может захватывать несколько одновременно. --- ## Что он захватывает -Каждая поверхность Codex, работающая **локально**, создает одинаковые расшифровки сессий на диске, и сборщик захватывает все из них: +Каждый интерфейс Codex, который работает **локально**, создает те же транскрипты сессий на диске, и коллектор подбирает все из них: - **CLI** Codex и `codex exec` - **расширение VS Code / IDE** -- **настольное приложение**, когда оно запускает сессию локально +- **приложение для рабочего стола**, когда оно выполняет сеанс локально -Каждая сессия Codex становится AgentEye [сессией](/ru/agenteye/sessions); её сообщения пользователя и ассистента, рассуждения, вызовы инструментов, результаты инструментов и использование токенов становятся соответствующими [событиями](/ru/agenteye/event-stream). Записывается поверхность, из которой пришла каждая сессия (CLI, IDE или настольное приложение), так что вы можете их различить. +Каждая сессия Codex становится [сессией](/ru/agenteye/sessions) AgentEye; её сообщения пользователя и ассистента, рассуждения, вызовы инструментов, результаты инструментов и использование токенов становятся соответствующими [событиями](/ru/agenteye/event-stream). Интерфейс, из которого поступила каждая сессия (CLI, IDE или приложение для рабочего стола), записывается, поэтому вы можете их различать. -> **Облачные сессии не захватываются.** Настольное приложение всё чаще запускает сессии в облаке Codex и хранит только их метаданные на машине — нет локальной расшифровки для чтения. Захватываются только локально выполняемые сессии. +> **Облачные сессии не захватываются.** Приложение для рабочего стола все чаще выполняет сеансы в облаке Codex и хранит только их метаданные на машине — локального транскрипта для чтения нет. Захватываются только локально выполняемые сессии. --- -## Включение +## Включите его -Захват отключен до включения. Установите сборщик с ключом API, который имеет разрешение `events:add` (см. [API keys](/ru/agenteye/api-keys)), и включите захват Codex: +Capture отключен до тех пор, пока вы его не включите. Установите коллектор с API-ключом, который имеет разрешение `events:add` (см. [API keys](/ru/agenteye/api-keys)), и включите capture Codex: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -Это устанавливает сборщик, регистрирует его как фоновый сервис и начинает захват. Убедитесь, что он работает: +Это устанавливает коллектор, регистрирует его как фоновый сервис и начинает захватывать. Подтвердите, что он работает: ```bash agenteye-collector health ``` -При первом запуске существующие сессии Codex заполняются один раз, а новая активность затем поступает в течение нескольких секунд. Файлы самого Codex только считываются — никогда не изменяются, не перемещаются и не удаляются — и каждая сессия отправляется ровно один раз, даже при перезагрузках. +При первом запуске ваши существующие сессии Codex заполняются один раз, и новая активность потом транслируется в течение нескольких секунд. Файлы самого Codex никогда только читаются — никогда не изменяются, не перемещаются и не удаляются — и каждая сессия отправляется ровно один раз, даже при перезагрузке. --- ## Где это отображается -Захваченные сессии появляются в **Sessions**, а их события в потоке **Events**, как и любой другой наблюдаемый вами агент — поэтому [проигрывание сессий](/ru/agenteye/sessions), [поиск](/ru/agenteye/queries), [оценки](/ru/agenteye/evaluations) и [оповещения](/ru/agenteye/alerts) работают на них. Отфильтруйте по агенту Codex, чтобы увидеть их отдельно. +Захваченные сессии появляются в **Sessions**, а их события в потоке **Events**, как и любой другой агент, который вы наблюдаете — поэтому [воспроизведение сессии](/ru/agenteye/sessions), [поиск](/ru/agenteye/queries), [оценки](/ru/agenteye/evaluations) и [оповещения](/ru/agenteye/alerts) все работают с ними. Отфильтруйте по агенту Codex, чтобы увидеть их отдельно. --- ## Приватность -Расшифровки Codex содержат полную сессию — включая вывод команд, содержимое файлов и всё, что Codex читал или писал — и могут содержать секреты. Захваченные сессии отправляются как есть, поэтому включайте захват только на машинах и для команд, где централизация этого содержимого в AgentEye целесообразна, и предоставьте сборщику ключ с областью `events:add` только. См. [Security](/ru/agenteye/security), чтобы узнать, как ваши данные остаются изолированными. \ No newline at end of file +Транскрипты Codex содержат полную сессию — включая вывод команд, содержимое файлов и всё, что читал или писал Codex — и могут содержать секреты. Захваченные сессии отправляются как есть, поэтому включайте capture только на машинах и для команд, где централизация этого контента в AgentEye целесообразна, и дайте коллектору ключ с областью действия только `events:add`. См. [Security](/ru/agenteye/security) для того, как ваши данные остаются изолированными. \ No newline at end of file diff --git a/docs/ru/agenteye/concepts.mdx b/docs/ru/agenteye/concepts.mdx index 4bdc66e7..53379fcc 100644 --- a/docs/ru/agenteye/concepts.mdx +++ b/docs/ru/agenteye/concepts.mdx @@ -1,82 +1,81 @@ --- title: "Концепции" -description: "Словарь Failproof AI Observability — события, сеансы, оценки, аудиты, результаты и инциденты — определены в одном месте." +description: "Словарь Failproof AI Observability — события, сеансы, оценки, аудиты, выявления и инциденты — определены в одном месте." --- - -На этой странице определены термины, которые использует Failproof AI Observability. Если в другом руководстве вам встретится незнакомый термин, его определение здесь. Вам не нужно читать всё подряд: просто просмотрите или вернитесь сюда, когда встретите слово, которое нужно уточнить. +На этой странице определены термины, используемые в Failproof AI Observability. Если вы встретите незнакомый термин в другом руководстве, его определение можно найти здесь. Вам не нужно читать всё от начала до конца: просто просмотрите или вернитесь сюда, когда вам нужно уточнить какое-то понятие. --- ## Модель данных **Event (событие)** -Наименьшая единица данных. Одно событие записывает один шаг, который выполнил ваш агент: `tool_use`, `model_request`, `hook_completed`, `error` и т. д. Ваш агент генерирует события через [Python SDK](/ru/agenteye/python-sdk); они отображаются в реальном времени на странице **Events** (события). +Наименьшая единица данных. Одно событие записывает один шаг, который выполнил ваш агент: `tool_use`, `model_request`, `hook_completed`, `error` и так далее. Ваш агент генерирует события через [Python SDK](/ru/agenteye/python-sdk); они отображаются в реальном времени на странице **Events**. **Session (сеанс)** -Один запуск агента, идентифицируемый `session_id`. Сеанс — это все события, имеющие этот идентификатор, сведённые в одну строку на странице **Sessions** (сеансы) и отображённые в виде графика выполнения на странице подробностей. Сеанс обычно начинается с `agent_start` и заканчивается `agent_end`. +Один запуск агента, идентифицируемый по `session_id`. Сеанс — это все события, которые имеют один и тот же идентификатор и отображаются в виде одной строки на странице **Sessions** и в виде графика выполнения на странице деталей. Сеанс обычно начинается с `agent_start` и завершается с `agent_end`. **Agent (агент)** -Именованный участник в запуске, идентифицируемый `agent_id`. Запуск может включать несколько агентов: например, планировщик, который порождает подагента-summarizer. Подагенты имеют `parent_id`, который позволяет Failproof AI Observability отображать их на отдельных линиях в графике выполнения. +Именованный участник запуска, идентифицируемый по `agent_id`. Один запуск может включать несколько агентов: например, планировщик, который создаёт подагента-сумматор. Подагенты имеют `parent_id`, что позволяет Failproof AI Observability отображать их на отдельных дорожках в графике выполнения. **Environment (окружение)** -Метка, указывающая, где происходил запуск: `production`, `staging`, `dev`. Вы устанавливаете его один раз при настройке SDK. Почти все страницы панели управления могут фильтроваться по окружению. +Метка, указывающая, где произошёл запуск: `production`, `staging`, `dev`. Вы устанавливаете её один раз при конфигурации SDK. Почти каждая страница панели инструментов может фильтровать по окружению. **Context-window fill (заполнение контекстного окна)** -Процент контекстного окна модели, который потребил ответ. Failproof AI Observability проставляет этот показатель для событий `model_response` для распознаваемых моделей, чтобы рост промтов и предстоящая компрессия были видны прямо в потоке событий. +Процент от контекстного окна модели, потреблённый ответом. Failproof AI Observability отмечает это значение на событиях `model_response` для известных моделей, чтобы увеличение подсказки и приближающееся сжатие были видны прямо в потоке событий. --- ## Качество **Evaluation (оценка)** -Оценка качества завершённого сеанса, созданная вашим сервисом оценки. Оценки опциональны: до подключения оценщика сеансы записываются, но не оцениваются. Каждая оценка может содержать несколько именованных баллов (например `helpfulness`, `factuality`, `tool_efficiency`), каждый с кратким примечанием рассуждений. См. [Evaluation suite](/ru/agenteye/evaluation-suite). +Оценка качества завершённого сеанса, произведённая сервисом оценки, который вы запускаете. Оценки опциональны: пока вы не подключите оценитель, сеансы будут записаны, но не оценены. Каждая оценка может содержать несколько именованных баллов (например `helpfulness`, `factuality`, `tool_efficiency`), каждый с кратким пояснением. См. [Evaluation suite](/ru/agenteye/evaluation-suite). **Score key (ключ оценки)** -Название одного измерения, о котором сообщает оценщик, например `helpfulness`. Оповещения и аудиты могут отслеживать определённый ключ оценки со временем. +Название одного измерения, которое отчитывает оценитель, такое как `helpfulness`. Оповещения и аудиты могут отслеживать конкретный ключ оценки в течение времени. -**Evaluator (оценщик)** -Ваш сервис оценки. Failproof AI Observability отправляет POST-запрос стенограмму завершённого запуска и сохраняет возвращаемые оценки. Служба не поставляется с оценщиком по умолчанию; логика оценки — ваша. +**Evaluator (оценитель)** +Ваш сервис оценки. Failproof AI Observability отправляет транскрипт завершённого запуска на этот сервис и сохраняет возвращаемые им оценки. Он не поставляет оценитель по умолчанию; логика оценки — это ваша ответственность. --- -## Поиск и исправление ошибок +## Обнаружение и исправление ошибок -**Hook (хук)** -Guardrail или побочный эффект, который выполняет ваш фреймворк агента вокруг шага: проверка безопасности контента, редакция PII, guard для бюджета. Хуки генерируют события `hook_triggered` / `hook_completed` с `outcome` (allow, deny, modify) и имеют собственную страницу наблюдения. +**Hook (перехватчик)** +Защитная мера или побочный эффект, который ваш фреймворк агента выполняет на каждом шаге: проверка безопасности содержимого, редакция PII, контроль бюджета. Перехватчики генерируют события `hook_triggered` / `hook_completed` с `outcome` (allow, deny, modify) и имеют собственную страницу наблюдения. **Alert rule (правило оповещения)** -Правило, которое срабатывает, когда метрика пересекает установленный вами порог: error rate, p95 latency, token cost или оценка оценщика. Когда срабатывает правило, оно открывает инцидент и отправляет уведомления в выбранные каналы (email, Slack, webhook, в панель управления). См. [Alerts](/ru/agenteye/alerts). +Правило, которое срабатывает, когда метрика пересекает установленный вами порог: частота ошибок, p95 задержки, стоимость токенов или оценка оценителя. Когда правило срабатывает, оно создаёт инцидент и отправляет уведомление в выбранные каналы (электронная почта, Slack, webhook, в панель инструментов). См. [Alerts](/ru/agenteye/alerts). **Incident (инцидент)** -Открытая проблема, созданная при срабатывании правила оповещения. Инциденты имеют жизненный цикл (acknowledge, assign, resolve) и временную шкалу активности, которая записывает каждое действие. Вы также можете открыть инцидент вручную. +Открытая проблема, созданная при срабатывании правила оповещения. Инциденты имеют жизненный цикл (подтверждение, назначение, разрешение) и временную шкалу действий, которая записывает каждое действие. Вы также можете открыть инцидент вручную. **Audit (аудит)** -Периодическое расследование (ежечасное до еженедельного), которое анализирует журналы *между* сеансами в поисках паттернов сбоев, для которых вы ещё не написали правило: кластеры ошибок, низкие оценки, выбросы latency, циклы вызовов инструментов и запуски, которые никогда не завершились. Если оповещение отслеживает метрику, о которой вы уже знаете, аудит указывает, на что смотреть дальше. См. [Audits](/ru/agenteye/audits). +Повторяющееся исследование (ежечасно или еженедельно), которое анализирует ваши логи *за все* сеансы в поиске паттернов ошибок, которые вы ещё не описали в правилах: кластеры ошибок, низкие оценки, выбросы задержек, циклы вызовов инструментов и запусти, которые никогда не завершились. Если оповещение отслеживает известную вам метрику, то аудит подскажет вам, на что обратить внимание дальше. См. [Audits](/ru/agenteye/audits). -**Finding (результат)** -Один ранжированный, подкреплённый доказательствами результат запуска аудита. Результат называет паттерн, ссылается на точные сеансы, лежащие в его основе, и имеет жизненный цикл сортировки (acknowledge, resolve, mute, dismiss). Failproof AI Observability дедублирует результаты от запуска к запуску, поэтому известный паттерн обновляется вместо накопления. +**Finding (выявление)** +Один ранжированный, подкреплённый доказательствами результат из запуска аудита. Выявление называет паттерн, ссылается на точные сеансы, которые его составляют, и имеет жизненный цикл сортировки (подтверждение, разрешение, отключение, отклонение). Failproof AI Observability дедублирует выявления от запуска к запуску, поэтому известный паттерн обновляется вместо накопления. -**The AI assistant (AI-ассистент)** -Встроенный в панель управления чат, который отвечает на вопросы об ваших агентах на простом английском языке, используя ваши собственные данные. По умолчанию он работает в режиме чтения; всё, что он создаёт (сохранённый запрос, панель управления), требует одобрения, и он никогда не может удалять. См. [AI assistant](/ru/agenteye/assistant). +**The AI assistant (AI помощник)** +Встроенный в панель инструментов чат, который отвечает на вопросы об ваших агентах на простом английском языке на основе ваших данных. По умолчанию он только для чтения; всё, что он создаёт (сохранённый запрос, панель инструментов), требует одобрения, и он никогда не может удалять. См. [AI assistant](/ru/agenteye/assistant). --- ## Запуск **Organization (tenant) (организация)** -Изолированное рабочее пространство. Один экземпляр Failproof AI Observability может размещать множество организаций, каждая со своими пользователями, ключами и данными. Каждый URL панели управления ограничена вашим слагом организации (`//…`). +Изолированное рабочее пространство. Один экземпляр Failproof AI Observability может хостить множество организаций, каждая со своими пользователями, ключами и данными. Каждый URL панели инструментов ограничен вашей организацией (`//…`). -**Collector (коллектор)** -`agenteye-collector`, лёгкий демон, который работает на каждой машине агента, объединяет события, которые SDK записывает на диск, и отправляет их на сервер. +**Collector (сборщик)** +`agenteye-collector`, лёгкий демон, который запускается на каждой машине агента, группирует события, которые SDK записывает на диск, и отправляет их на сервер. -**API key (API-ключ)** -Токен с ограниченной областью, который аутентифицирует клиент на сервере. Ключи имеют детальные разрешения (например `events:add` для коллектора, read-only области для ключа панели управления). См. [API keys](/ru/agenteye/api-keys). +**API key (ключ API)** +Токен с ограниченной областью действия, который аутентифицирует клиент на сервере. Ключи имеют детальные разрешения (например `events:add` для сборщика, только для чтения области для ключа панели инструментов). См. [API keys](/ru/agenteye/api-keys). **Server (сервер)** -Сервис ingestion и API. Он принимает события, хранит операционное состояние в ваших базах данных и обслуживает панель управления и CLI. +Сервис приёма и API. Он принимает события, сохраняет операционное состояние в ваших базах данных и предоставляет панель инструментов и CLI. -**Dashboard (панель управления)** +**Dashboard (панель инструментов)** Веб-интерфейс. Каждая страница ограничена организацией и читает данные через API сервера. --- diff --git a/docs/ru/agenteye/dashboards.mdx b/docs/ru/agenteye/dashboards.mdx index 4979fe13..0f6a952e 100644 --- a/docs/ru/agenteye/dashboards.mdx +++ b/docs/ru/agenteye/dashboards.mdx @@ -1,46 +1,46 @@ --- -title: "Приборные панели" -description: "Превратите ваши живые данные агентов в одну общую картину, за которой следит вся команда." +title: "Дашборды" +description: "Превратите живые данные ваших агентов в одну общую картину, которую смотрит вся команда." --- -Превратите ваши живые данные агентов в одну общую картину, за которой следит вся команда. Закрепите важные запросы в виде графиков, и каждый сможет увидеть одни и те же цифры с первого взгляда, без повторного выполнения запросов. +Превратите живые данные ваших агентов в одну общую картину, которую смотрит вся команда. Закрепляйте важные запросы как графики, и все видят одни и те же цифры с первого взгляда, без необходимости повторного запуска запросов. -![Приборная панель, построенная из сохраненных запросов: линия событий в час, столбчатая диаграмма ошибок по типам, диаграмма площади для задержки и распределение токенов по модели](/agenteye/images/dashboard-fleet.png) +![A dashboard built from saved queries: an events-per-hour line, an errors-by-type bar, a latency area chart, and tokens-by-model](/agenteye/images/dashboard-fleet.png) -*Одна панель, четыре сохраненных запроса: события в час, ошибки по типам, задержка и токены по модели.* +*Один дашборд, четыре сохранённых запроса: события в час, ошибки по типам, задержка и токены по модели.* -## Все видят одну истину +## Все видят одну правду -Перестаньте отправлять скриншоты в чат и перестаньте выполнять один и тот же запрос пять раз в день. Приборная панель — это общая, общеорганизационная доска, которую любой член команды может открыть и увидеть одно и то же представление. Когда базовые данные меняются, графики меняются вместе с ними, поэтому панель всегда актуальна и никто не спорит о устаревших числах. +Перестаньте скидывать скриншоты в чат и повторно запускать один и тот же запрос пять раз в день. Дашборд — это общая для всей организации доска, которую любой член команды может открыть и увидеть одно и то же. Когда изменяются основные данные, графики движутся вместе с ними, поэтому доска всегда актуальна и никто не спорит об устаревших цифрах. -Панель флота выше — это хороший исходный вид для ежедневной работы: +Дашборд флота выше — хороший начальный вариант для ежедневных операций: -- **линия событий в час**, чтобы вы могли отслеживать пропускную способность и заметить резкое падение -- **столбчатая диаграмма ошибок по типам**, чтобы ваши самые большие категории сбоев выделялись -- **диаграмма площади задержки**, чтобы замедления были видны до жалоб пользователей -- **распределение токенов по модели**, чтобы расходы оставались в поле зрения +- линия **событий в час**, чтобы отслеживать пропускную способность и заметить резкий спад +- столбчатая диаграмма **ошибок по типам**, чтобы выделялись основные категории сбоев +- график **задержки** по площади, чтобы замедления были видны до жалоб пользователей +- распределение **токенов по модели**, чтобы держать расходы в поле зрения -Ваши панели находятся по адресу `//dashboards`. +Ваши дашборды находятся по адресу `//dashboards`. -## Закрепляйте уже сохраненные запросы +## Закрепляйте уже сохранённые запросы -Каждая плитка начинается как сохраненный запрос. Создайте и сохраните нужный вам запрос в библиотеке [Запросов](/ru/agenteye/queries) (встроенные предустановки плюс ваши собственные, по вашим событиям и оценкам), затем закрепите его на приборной панели как график, который подходит данным: **линия** для тенденций во времени, **столбцы** для сравнения категорий, **площадь** для объема или **круговая диаграмма** для распределения долей. +Каждая плитка начинается как сохранённый запрос. Постройте и сохраните интересующий вас запрос в библиотеке [Queries](/ru/agenteye/queries) (встроенные шаблоны плюс ваши собственные, над вашими событиями и оценками), затем закрепите его на дашборде как график, который подходит данным: **линия** для тенденций во времени, **столбцы** для сравнения категорий, **площадь** для объёма или **круговая диаграмма** для доли. -Поскольку плитка — это просто ваш сохраненный запрос, отображаемый как график, нечего синхронизировать вручную. Обновите запрос один раз, и каждая приборная панель, которая его использует, обновится тоже. +Поскольку плитка — это просто ваш сохранённый запрос, отображённый как график, нечего синхронизировать вручную. Обновите запрос один раз, и все дашборды, которые его используют, обновятся автоматически. -## Отслеживайте качество, а не просто объем +## Смотрите качество, а не только объём -Объем говорит вам, что агенты заняты. Качество говорит вам, что они действительно выполняют работу. Направьте приборную панель на ваши [оценки качества](/ru/agenteye/evaluations) и получите панель, которая отслеживает, насколько хорошо идут запуски с течением времени, так что регрессия качества появится как провал на графике вместо сюрприза от клиента. +Объём показывает, что агенты заняты. Качество показывает, что они действительно выполняют работу. Направьте дашборд на ваши [оценки качества](/ru/agenteye/evaluations) и получите доску, которая отслеживает, насколько хорошо идут запуски со временем, чтобы регрессия качества проявлялась как спад на графике, а не как неожиданность от клиента. -![Приборная панель, ориентированная на качество, созданная на основе сохраненных запросов оценок](/agenteye/images/dashboard-quality.png) +![A quality-focused dashboard built from saved evaluation queries](/agenteye/images/dashboard-quality.png) -*Панель качества держит ваши оценки в центре внимания, прямо рядом с операционными показателями.* +*Дашборд качества держит оценки оценок в центре внимания, рядом с операционными показателями.* -Держите панель операций и панель качества рядом, и ваша команда получит одно место для ответа на оба вопроса: «это работает?» и «это хорошо?», без повторного выполнения запросов кем-то из команды. +Держите дашборд операций и дашборд качества рядом, и ваша команда будет иметь одно место для ответа на оба вопроса: «это работает?» и «это хорошо?», без необходимости повторного запуска запросов. ## Связанное -- [Запросы](/ru/agenteye/queries): создавайте и сохраняйте запросы, которые становятся вашими плитками. -- [Оценки](/ru/agenteye/evaluations): оценивайте ваши запуски, чтобы отслеживать качество с течением времени. -- [Оповещения](/ru/agenteye/alerts): превратите пороговое значение любой из этих метрик в уведомление. \ No newline at end of file +- [Queries](/ru/agenteye/queries): постройте и сохраните запросы, которые становятся вашими плитками. +- [Evaluations](/ru/agenteye/evaluations): оценивайте ваши запуски, чтобы отслеживать качество со временем. +- [Alerts](/ru/agenteye/alerts): преобразуйте порог любого из этих метрик в оповещение. \ No newline at end of file diff --git a/docs/ru/agenteye/error-tracking.mdx b/docs/ru/agenteye/error-tracking.mdx index 938578f2..6dbc43a9 100644 --- a/docs/ru/agenteye/error-tracking.mdx +++ b/docs/ru/agenteye/error-tracking.mdx @@ -1,41 +1,41 @@ --- title: "Отслеживание ошибок" -description: "Просматривайте все сбои ваших агентов в одном месте, сгруппированные так, чтобы множество похожих ошибок отображалось как одна проблема." +description: "Смотрите каждый сбой ваших агентов в одном месте, сгруппированные так, чтобы шумный поток читался как одна проблема." --- -Просматривайте все сбои ваших агентов в одном месте, сгруппированные так, чтобы множество похожих ошибок отображалось как одна проблема. Вы получаете прямой путь от "что-то красное" к точному запуску, который вызвал сбой, без прокрутки живого потока событий. +Смотрите каждый сбой ваших агентов в одном месте, сгруппированные так, чтобы шумный поток читался как одна проблема. Вы получаете однокликовый путь от «что-то красное» к точному запуску, который сломался, без прокрутки живого потока для его поиска. -![Страница ошибок: гистограмма сбоев во времени над сгруппированными красными строками ошибок, каждая с кнопкой "+ alert" в один клик](/agenteye/images/errors.png) -*Страница ошибок: гистограмма сбоев во времени с повторяющимися сбоями, свёрнутыми в одну строку на инцидент.* +![Страница Errors: гистограмма сбоев во времени выше сгруппированных красных строк ошибок, каждая с однокликовой кнопкой «+ alert»](/agenteye/images/errors.png) +*Страница Errors: гистограмма сбоев во времени с повторяющимися сбоями, сложенными в одну строку на инцидент.* ## Каждый сбой уже собран для вас -Когда агент ломается, вам не нужно прокручивать живой поток событий в надежде поймать красные строки перед тем, как они исчезнут. Страница **Errors** (Ошибки) собирает это за вас. Она объединяет всё, что приборная панель отметила бы как красное, в одну поверхность для сортировки, так что первое, что вы видите — это что именно ломается, а не где это искать. +Когда агент дает сбой, вам не нужно прокручивать поток живых событий в надежде поймать красные строки до того, как они уйдут из виду. Страница **Errors** делает сбор за вас. Она собирает все, что панель инструментов окрасила бы в красный цвет, в одну поверхность триажа, так что первое, что вы видите — это что именно дает сбой, а не где его искать. -И она ловит больше, чем только очевидные сбои. Наряду с явными событиями `error`, Failproof AI Observability выявляет и тихие сбои: любой `tool_result`, `hook_completed` или `agent_end`, в полезной нагрузке которого есть сбой, появляется здесь. Инструмент, вернувший ошибку, или хук, завершившийся неудачно, больше не пройдёт мимо вас просто потому, что ничего не выбросило громкого исключения. +И она ловит не только очевидные. Наряду с явными событиями `error`, Failproof AI Observability выводит на поверхность и тихие сбои: любые `tool_result`, `hook_completed` или `agent_end`, чья полезная нагрузка содержит сбой, появляются здесь. Инструмент, который вернул ошибку, или хук, который завершился неудачно, больше не ускользает от вас только потому, что ничего не выбросило громкое исключение. -В верхней части гистограмма отображает ошибки во времени. Один взгляд подскажет вам, это постоянный фоновый поток или всплеск, начавшийся несколько минут назад, так что вы сразу узнаете, стоит ли отвлекаться. +Поперек верхней части гистограмма отображает ошибки во времени. Один взгляд говорит вам, является ли это стабильным фоновым потоком или всплеском, начавшимся несколько минут назад, поэтому вы сразу знаете, нужно ли вам отложить то, что вы делаете. -Как и каждая страница observe, страница Errors ограничена вашей организацией и фильтруется по диапазону дат, окружению, агенту и сессии. Это означает, что вы можете взять список всего флота и сузить его до одного агента или одного окружения, которое вас действительно интересует. +Как и на каждой поверхности observe, страница Errors относится к вашей организации и фильтруется по диапазону дат, окружению, агенту и сеансу. Это означает, что вы можете взять список всего флота и сузить его до одного агента или одного окружения, которое вас действительно интересует. ## Один инцидент, а не сотня одинаковых строк -Одна сломанная зависимость может вызвать одну и ту же ошибку сотни раз в минуту. В необработанном виде это стена из практически идентичных строк, которая скрывает единственное, что вам действительно нужно увидеть. +Одна поломанная зависимость может срабатывать одну и ту же ошибку сотни раз в минуту. В необработанном виде это стена почти идентичных строк, которая скрывает одно, что вам действительно нужно увидеть. -Failproof AI Observability сворачивает повторяющиеся сбои, которые имеют одинаковую сессию и тип ошибки, в одну строку. Всплеск читается как один инцидент. Вы в итоге считаете проблемы, а не строки логов, и сигнал, который имеет значение, остаётся на виду вместо того, чтобы быть захороненным своим собственным объёмом. +Failproof AI Observability сворачивает повторяющиеся сбои, которые имеют одинаковый сеанс и тип ошибки, в одну строку. Всплеск читается как один инцидент. Вы в итоге считаете проблемы, а не строки логов, и сигнал, который имеет значение, остается на вершине вместо того, чтобы быть затопленным собственным объемом. -## От "что-то красное" к точному событию +## От «что-то красное» к точному событию -Нажмите на любую строку, чтобы перейти прямо в сессию этого запуска, позиционированную на точном событии, которое привело к сбою. Никакого копирования ID сессий, никакой прокрутки в поисках момента, когда всё пошло не так: вы окажетесь прямо на нём, с полным графиком выполнения в одном взгляде, чтобы вы могли увидеть, что делал агент в моменты перед тем, как он сломался. +Нажмите на любую строку, чтобы попасть прямо в сеанс этого запуска, позиционированном на точном событии, которое дало сбой. Без копирования идентификаторов сеанса, без прокрутки в поисках момента, когда все пошло не так: вы попадаете прямо на него, с полным графом выполнения в одном взгляде, так что вы можете видеть, что делал агент в моменты перед тем, как произошел сбой. -Если у вас есть `alerts:write`, каждая строка также содержит кнопку **+ alert**. Нажмите на неё, и Observability откроет новое правило оповещения, уже заполненное для отлова того же сбоя снова. Инцидент, который вы только что рассортировали, станет тем, который вас оповестит в следующий раз, вместо того чтобы застать вас врасплох дважды. +Если у вас есть `alerts:write`, каждая строка также содержит кнопку **+ alert**. Нажмите на нее, и Observability откроет новое правило оповещения, уже заполненное для перехвата того же сбоя снова. Инцидент, который вы только что триажировали, становится тем, который вас оповестит в следующий раз, вместо того чтобы удивить вас дважды. -**Где это найти:** страница **Errors** находится в разделе observe приборной панели по адресу `//errors`. +**Где это найти:** страница **Errors** находится в разделе observe панели инструментов по адресу `//errors`. ## Связанное - [Alerts](/ru/agenteye/alerts): превратите любой сбой в правило оповещения. - [Incidents](/ru/agenteye/incidents): отслеживайте срабатывающее оповещение от открытия до разрешения. - [Sessions](/ru/agenteye/sessions): откройте полный запуск за любой ошибкой. -- [Audits](/ru/agenteye/audits): позвольте Observability найти закономерности в сбоях ваших запусков. \ No newline at end of file +- [Audits](/ru/agenteye/audits): позвольте Observability найти закономерности сбоев во всех ваших запусках. \ No newline at end of file diff --git a/docs/ru/agenteye/evaluation-suite.mdx b/docs/ru/agenteye/evaluation-suite.mdx index 6e73fe6c..788a1fcb 100644 --- a/docs/ru/agenteye/evaluation-suite.mdx +++ b/docs/ru/agenteye/evaluation-suite.mdx @@ -1,22 +1,22 @@ --- -title: "Evaluation Suite" -description: "Failproof AI Observability может автоматически оценивать качество каждого завершённого запуска агента: вы предоставляете небольшой сервис оценки, а Observability берёт на себя остальное." +title: "Набор средств оценки" +description: "Failproof AI Observability может автоматически оценивать качество каждого завершённого запуска агента: вы предоставляете небольшой сервис оценки, а Observability берёт всё остальное на себя." --- -Failproof AI Observability может автоматически оценивать качество каждого завершённого запуска агента: вы предоставляете небольшой сервис оценки, а Observability берёт на себя остальное. Используйте её для отслеживания интересующих вас параметров (полезность, эффективность инструментов, фактичность, безопасность — выбираете вы), раннего выявления регрессий и быстрого сравнения агентов или окружений. Оценка является дополнительной функцией: конвейер ничего не делает, пока вы не установите `EVALUATOR_ENDPOINT` на сервере. +Failproof AI Observability может автоматически оценивать качество каждого завершённого запуска агента: вы предоставляете небольшой сервис оценки, а Observability берёт всё остальное на себя. Используйте это для отслеживания интересующих вас параметров (полезность, эффективность инструментов, фактичность, безопасность — вы выбираете), раннего обнаружения регрессий и сравнения агентов или окружений с первого взгляда. Оценка является опциональной: конвейер не работает до тех пор, пока вы не установите `EVALUATOR_ENDPOINT` на сервере. -> **Примечание:** Вы определяете параметры оценки. Ваш оценивающий сервис может возвращать любые числовые ключи; Observability сохраняет, отслеживает и отображает всё, что вы отправляете. +> **Примечание:** вы определяете размеры оценок. Ваш оценщик может возвращать любые числовые ключи; Observability сохраняет, отслеживает и отображает всё, что вы отправляете. -## Кратко +## Краткий обзор -1. **Напишите оценивающий сервис.** Создайте небольшой HTTP-сервис, который читает транскрипт сессии и возвращает оценки. Observability поставляется с рабочим примером, который вы можете скопировать. См. [Написание оценивающего сервиса с SDK](#writing-an-evaluator-with-the-sdk). -2. **Укажите Observability на него.** Установите `EVALUATOR_ENDPOINT` (и общий `EVALUATOR_TOKEN`) на процесс сервера. -3. **Смотрите, как появляются оценки.** Каждая завершённая сессия автоматически оценивается; результаты отображаются на странице деталей сессии, в сетке сессий и на сохранённых панелях. +1. **Напишите оценщик.** Разверните небольшой HTTP-сервис, который читает расшифровку сеанса и возвращает оценки. Observability поставляется с рабочей справкой, которую вы можете скопировать. См. [Написание оценщика с помощью SDK](#написание-оценщика-с-помощью-sdk). +2. **Укажите Observability на него.** Установите `EVALUATOR_ENDPOINT` (и общий `EVALUATOR_TOKEN`) в процессе сервера. +3. **Следите за оценками.** Каждый завершённый сеанс оценивается автоматически; результаты появляются на странице деталей сеанса, в сетке сеансов и в сохранённых панелях. -![Представление деталей сессии с резюме оценки, полосами оценок по параметрам и текстом обоснования на правой панели](/agenteye/images/session-detail.png) +![Представление деталей сеанса с резюме оценки, столбцами оценок по каждому измерению и текстом рассуждений в правой панели](/agenteye/images/session-detail.png) -*После настройки оценивающего сервиса каждый завершённый запуск оценивается, и результаты появляются на правой панели сессии: резюме вверху, затем полосы оценок по параметрам с обоснованием.* +*После настройки оценщика каждый завершённый запуск оценивается, и результаты появляются в правой панели сеанса: сводка сверху, затем столбцы оценок по каждому измерению с рассуждениями.* --- @@ -32,77 +32,44 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Когда Failproof AI Observability SDK генерирует событие `agent_end` для сессии, сервер -планирует оценку. Затем он отправляет полный транскрипт событий в ваш -оценивающий сервис, который может: - -- **Вернуть результат сразу** с `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Результат - добавляется в временную линию оценок сессии. `reasoning` и - `summary` опциональны. -- **Отложить** с `{"status":"pending", "job_id":"abc-123"}`. Observability затем - вызывает `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` до тех пор, пока ваш оценивающий сервис - не вернёт `{"status":"done", ...}` или `{"status":"error", "error":"..."}`. - - Интервал опроса зависит от задачи: ответ `pending` может включать - `next_poll_secs` для переопределения; в противном случае Observability использует - значение `default_poll_interval_secs` из `GET /config`; если его нет, сервер - использует `EVALUATOR_POLLING_INTERVAL_SECS` (по умолчанию 10 сек). Все значения - ограничиваются диапазоном [1 сек, 1 ч]. - -Сессии, которые никогда не генерируют `agent_end` (например, упавший процесс агента), -также могут быть обработаны: конфигурация оценивающего сервиса `GET /config` может возвращать -`{"inactivity_timeout_secs": 1800}`, и Observability будет оценивать любую сессию, -которая неактивна в течение этого времени. Установите поле в `null` или опустите его, -чтобы отключить этот резервный механизм. +Когда Observability SDK отправляет событие `agent_end` для сеанса, сервер планирует оценку. Затем он отправляет полную расшифровку события на ваш сервис оценщика, который может: + +- **Вернуть результат немедленно** с помощью `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Результат добавляется в шкалу времени оценки сеанса. `reasoning` и `summary` опциональны. +- **Отложить** с помощью `{"status":"pending", "job_id":"abc-123"}`. Затем Observability вызывает `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` до тех пор, пока ваш оценщик не вернёт `{"status":"done", ...}` или `{"status":"error", "error":"..."}`. + + Частота опроса зависит от задачи: ответ `pending` может включать `next_poll_secs` для переопределения; в противном случае Observability использует значение `default_poll_interval_secs` из `GET /config`; в противном случае сервер переходит к `EVALUATOR_POLLING_INTERVAL_SECS` (по умолчанию 10s). Все значения зажимаются до [1s, 1h]. + +Сеансы, которые никогда не отправляют `agent_end` (например, упавший процесс агента), также могут быть обработаны: `GET /config` оценщика может вернуть `{"inactivity_timeout_secs": 1800}`, и Observability будет оценивать любой сеанс, который был неактивен в течение этого времени. Установите это поле на `null` или опустите его для отключения этого резервного варианта. Конвейер полностью неактивен, когда `EVALUATOR_ENDPOINT` не установлен. -Сессия может накапливать **несколько финальных оценок в течение времени**: каждое -событие `agent_end` (и каждая ручная переоценка с панели) добавляет -свежую строку оценки. Это поддерживаемый способ оценки продолжённой -беседы: пользователь завершает работу агента, возвращается позже, отправляет больше событий, -завершает работу агента снова, и вторая оценка запускается против полного обновлённого -транскрипта. Панель отображает самую последнюю оценку как заголовок, -а предыдущие оценки как свёртываемую временную линию. Пока одна -оценка выполняется для сессии, дополнительные события `agent_end` для этой -сессии игнорируются; следующий после завершения выполняемой оценки -будет поставлен в очередь для свежей оценки как обычно. - -Резервный механизм неактивности повторно активируется и на возобновлённых сессиях: если новые события -поступают после предыдущей финальной оценки и сессия затем становится неактивной дольше -`inactivity_timeout_secs`, свежая оценка ставится в очередь. - -Преходящие сбои (5xx, 429, таймауты, сетевые ошибки) повторяются с -экспоненциальной задержкой до `EVALUATOR_MAX_ATTEMPTS`; ответы 4xx являются -финальными. Observability безопасно запускается с несколькими горизонтально масштабируемыми экземплярами сервера; -работа разбита так, чтобы одна сессия никогда не была отправлена -дважды одновременно. +Сеанс может накапливать **несколько окончательных оценок с течением времени**: каждое событие `agent_end` (и каждая ручная переоценка с панели) добавляет новую строку оценки. Это поддерживаемый способ оценки возобновлённого разговора: пользователь заканчивает агента, возвращается позже, отправляет дополнительные события, заканчивает агента снова, и вторая оценка запускается на полной обновлённой расшифровке. Панель отображает самую свежую оценку в качестве заголовка и предыдущие оценки как свёртываемую шкалу времени. Пока для сеанса выполняется одна оценка, дополнительные события `agent_end` для этого сеанса игнорируются; следующее после завершения выполняющейся оценки поставит в очередь новую оценку как обычно. + +Резервный вариант неактивности снова активируется для возобновлённых сеансов: если новые события поступают после предыдущей окончательной оценки и сеанс затем переходит в режим ожидания за пределы `inactivity_timeout_secs`, новая оценка ставится в очередь. + +Временные ошибки (5xx, 429, тайм-ауты, ошибки сети) повторяются с экспоненциальной задержкой до `EVALUATOR_MAX_ATTEMPTS`; ответы 4xx являются окончательными. Observability безопасно работает с несколькими горизонтально масштабируемыми экземплярами сервера; работа разбита так, чтобы один сеанс никогда не отправлялся дважды одновременно. --- ## HTTP контракт -Каждый защищённый маршрут использует **аутентификацию по токену носителя**. Одно и то же значение должно быть -настроено с обеих сторон: +Каждый маршрут с аутентификацией использует **аутентификацию по токену носителя**. Одно и то же значение должно быть настроено с обеих сторон: - Сервер Observability: переменная окружения `EVALUATOR_TOKEN` -- Сервис оценки: настроен аналогично (SDK `agenteye-evaluator` - по соглашению читает `EVALUATOR_TOKEN`) +- Сервис оценщика: настроен тем же образом (SDK `agenteye-evaluator` читает `EVALUATOR_TOKEN` по соглашению) -Если `EVALUATOR_TOKEN` не установлен, сервер не отправляет заголовок `Authorization`; оценивающий сервис -может затем принимать анонимные запросы, что нормально для -сети только внутри, но не рекомендуется в открытом интернете. +Если `EVALUATOR_TOKEN` не установлен, сервер не отправляет заголовок `Authorization`; оценщик может затем принимать анонимные запросы, что приемлемо для сети только для внутреннего использования, но не рекомендуется в общедоступном интернете. -### Маршруты, которые должен обслуживать оценивающий сервис +### Маршруты, которые должен обслуживать оценщик | Маршрут | Тело / параметры | Ответ | |---|---|---| | `GET /health` | нет | `{"status":"ok"}` (открыт, без аутентификации) | -| `GET /config` | нет | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| опущено}` | +| `GET /config` | нет | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| опустить}` | | `POST /evaluate` | JSON `EvalRequest` | `{"status":"done", ...}` или `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | нет | аналогичная форма ответа как `/evaluate` | +| `GET /evaluate/{id}` | нет | та же форма ответа, что и `/evaluate` | -### Тело `EvalRequest`, отправляемое сервером +### Тело `EvalRequest`, отправленное сервером ```json { @@ -121,7 +88,7 @@ flowchart LR ### Формы ответов -**Синхронная (готово):** +**Синхронно (готово):** ```json { @@ -135,46 +102,33 @@ flowchart LR } ``` -`reasoning` (карта обоснований для каждой оценки) и `summary` (общее -описание в один абзац) оба опциональны. Ключи в `reasoning` должны -соответствовать ключам в `scores`; панель отображает каждую запись встроенной -под её полосой оценки. Старые оценивающие сервисы, возвращающие только `scores`, продолжают -работать без изменений; `reasoning` и `summary` просто читаются как null и -соответствующие элементы UI опускаются. +`reasoning` (карта обоснования для каждой оценки) и `summary` (общее однопараграфное повествование) являются опциональными. Ключи в `reasoning` должны совпадать с ключами в `scores`; панель отображает каждую запись встроенной под её столбцом оценки. Более старые оценщики, которые возвращают только `scores`, продолжают работать без изменений; `reasoning` и `summary` просто читаются как null и соответствующие элементы интерфейса опускаются. -**Асинхронная (отложенная):** +**Асинхронно (отложено):** ```json { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` опционален; если опущен, сервер использует -`default_poll_interval_secs` оценивающего сервиса из `/config`, затем его собственную -переменную окружения `EVALUATOR_POLLING_INTERVAL_SECS`. +`next_poll_secs` опционален; если опущен, сервер переходит к `default_poll_interval_secs` оценщика из `/config`, затем к его собственной переменной окружения `EVALUATOR_POLLING_INTERVAL_SECS`. -**Финальная ошибка на стороне оценивающего сервиса:** +**Окончательная ошибка со стороны оценщика:** ```json { "status": "error", "error": "model service unavailable" } ``` -Сервер обрабатывает любое другое тело 2xx как ошибку протокола и записывает -финальную `error` для сессии. +Сервер рассматривает любое другое тело 2xx как ошибку протокола и записывает окончательное `error` для сеанса. --- -## Написание оценивающего сервиса с SDK +## Написание оценщика с помощью SDK -Вам не нужно реализовывать HTTP контракт вручную. Пакет Python `agenteye-evaluator` -предоставляет типизированную обёртку FastAPI, которая обрабатывает аутентификацию, маршрутизацию и -формы запроса/ответа для вас. +Вам не нужно реализовывать HTTP контракт вручную. Пакет Python `agenteye-evaluator` предоставляет типизированную оболочку FastAPI, которая обрабатывает аутентификацию, маршрутизацию и формы запросов/ответов за вас. -Failproof AI Observability также поставляется с **рабочим примером оценивающего сервиса**, который -оценивает `helpfulness`, `tool_efficiency` и `factuality` на основе формы -транскрипта. Скопируйте его как отправную точку и замените вашей собственной логикой: судья LLM, -механизм правил, что угодно, соответствующее вашему уровню качества. +Failproof AI Observability также поставляется с **рабочим справочным оценщиком**, который оценивает `helpfulness`, `tool_efficiency` и `factuality` на основе формы расшифровки. Скопируйте его как отправную точку и замените свою логику: судья LLM, механизм правил, всё, что соответствует вашему стандарту качества. -Минимально жизнеспособный оценивающий сервис: +Минимально жизнеспособный оценщик: ```python import os @@ -193,89 +147,70 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -Экземпляр `app` работает под любым ASGI сервером, поэтому `uvicorn module:app` его запускает. +Экземпляр `app` работает под любым ASGI-сервером, поэтому `uvicorn module:app` его запускает. -Для оценивающих сервисов, которым нужно отложить дорогостоящую работу, верните `JobPending` -вместо этого и зарегистрируйте обработчик `@app.job_lookup`; сервер Observability -опрашивает `GET /evaluate/{job_id}` до тех пор, пока вы не вернёте финальный статус или не истечёт -лимит `EVALUATOR_MAX_POLL_DURATION_SECS` (по умолчанию 1 ч). +Для оценщиков, которым нужно отложить дорогостоящую работу, верните `JobPending` и зарегистрируйте обработчик `@app.job_lookup`; сервер Observability опрашивает `GET /evaluate/{job_id}` до тех пор, пока вы не вернёте окончательный статус или не истечёт крышка `EVALUATOR_MAX_POLL_DURATION_SECS` (по умолчанию 1 ч). -Полный справочник API, асинхронный паттерн и схема событий задокументированы в -README SDK `agenteye-evaluator`. +Полная справка API, асинхронный шаблон и схема события документированы в README SDK `agenteye-evaluator`. --- -## Запуск вашего оценивающего сервиса +## Запуск вашего оценщика -Оценивающий сервис — **ваш сервис** — Failproof AI Observability не поставляет -оценивающий сервис по умолчанию, поэтому вы строите и запускаете его там же, где запускаете ваши сервисы. -Он работает под любым ASGI сервером (например `uvicorn my_evaluator:app`); обслуживайте -маршруты `/health`, `/config` и `/evaluate` из -[HTTP контракта](#http-contract), затем укажите на него сервер (см. -[Настройка сервера](#configuring-the-server)). +Оценщик — **ваш сервис** — Failproof AI Observability не поставляется с оценщиком по умолчанию, поэтому вы строите и запускаете его там, где вы запускаете свои собственные сервисы. Он работает под любым ASGI-сервером (например `uvicorn my_evaluator:app`); обслуживайте маршруты `/health`, `/config` и `/evaluate` из [HTTP контракта](#http-контракт), затем укажите сервер на него (см. [Настройка сервера](#настройка-сервера)). -Как только оценивающий сервис доступен, `GET /health` возвращает `{"status":"ok"}`. После -того как агент завершит работу полностью, `GET /evaluations` на сервере возвращает строку с -`status: "done"` и оценками, которые произвёл ваш оценивающий сервис. +Как только оценщик достижим, `GET /health` возвращает `{"status":"ok"}`. После завершения запуска агента `GET /evaluations` на сервере возвращает строку со статусом `status: "done"` и оценками, которые создал ваш оценщик. --- ## Настройка сервера -Установите на процесс сервера: +Установите в процессе сервера: | Переменная окружения | Значение | |---|---| -| `EVALUATOR_ENDPOINT` | Базовый URL вашего оценивающего сервиса (`http://evaluator:9000`). Не установлено = конвейер отключен. | -| `EVALUATOR_TOKEN` | Токен носителя. Должен быть равен значению, с которым настроен сервис оценки. | +| `EVALUATOR_ENDPOINT` | Базовый URL вашего оценщика (`http://evaluator:9000`). Не установлено = конвейер отключен. | +| `EVALUATOR_TOKEN` | Токен носителя. Должно совпадать со значением, которым настроен сервис оценщика. | | `EVALUATOR_WORKERS` | Рабочие задачи на экземпляр сервера (по умолчанию 2). | -| `EVALUATOR_CLAIM_BATCH` | Строки, заявляемые за тик рабочего (по умолчанию 4). Пакеты обрабатываются **одновременно**; эффективная параллельность на вашей конечной точке оценки: `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Как долго рабочий спит между попытками отправки, когда нет оценки в очереди (по умолчанию 2 сек). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Финальный резервный вариант для интервала `GET /evaluate/{id}`, когда ни `next_poll_secs` в ответе, ни `default_poll_interval_secs` оценивающего сервиса не установлены (по умолчанию 10 сек). | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | Таймаут для одного запроса (по умолчанию 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | После этого количества преходящих сбоев результат записывается как финальная `error` (по умолчанию 5). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | Интервал `GET /config` (по умолчанию 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Максимальное настоящее время, которое сессия может оставаться в очереди опроса перед завершением как `timeout` (по умолчанию 3600 сек). Защищает от оценивающего сервиса, который продолжает возвращать `pending` бесконечно. | +| `EVALUATOR_CLAIM_BATCH` | Строки, заявленные за тик работника (по умолчанию 4). Пакеты обрабатываются **одновременно**; эффективная одновременность на вашей конечной точке оценщика — `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Как долго рабочий спит между попытками отправки, когда оценка не требуется (по умолчанию 2s). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Окончательный резервный вариант для частоты `GET /evaluate/{id}`, когда ни `next_poll_secs` на каждый ответ, ни `default_poll_interval_secs` оценщика не установлены (по умолчанию 10s). | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Тайм-аут для каждого запроса (по умолчанию 30000). | +| `EVALUATOR_MAX_ATTEMPTS` | После такого количества временных ошибок результат записывается как окончательное `error` (по умолчанию 5). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | Частота `GET /config` (по умолчанию 300). | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Максимальное время в реальном времени, в течение которого сеанс может оставаться в очереди опроса, прежде чем он будет завершён как `timeout` (по умолчанию 3600s). Защита от оценщика, который продолжает возвращать `pending` вечно. | -Чтобы включить автоматическую оценку, установите `EVALUATOR_ENDPOINT` и -`EVALUATOR_TOKEN` на сервере, затем перезагрузите его, чтобы применить изменение. С -`EVALUATOR_ENDPOINT` не установленным конвейер остаётся неактивным. +Чтобы включить автоматическую оценку, установите оба `EVALUATOR_ENDPOINT` и `EVALUATOR_TOKEN` на сервере, затем перезагрузите его, чтобы применить изменения. С неустановленным `EVALUATOR_ENDPOINT` конвейер остаётся неактивным. -Вышеуказанные настраиваемые параметры опциональны; устанавливайте соответствующие переменные -окружения на сервере только если вам нужно переопределить значения по умолчанию. +Приведённые выше регулировочные ручки являются опциональными; установите соответствующие переменные окружения на сервере только если вам нужно переопределить значения по умолчанию. --- -## Справочник API +## Справка API | Метод | Путь | Требуемое разрешение | Назначение | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Запрос финальных результатов. Поддерживает `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` по умолчанию 50 и ограничен на 200 (обратите внимание, это отличается от `/events`, который ограничен на 1000). `environment` принимает список через запятую (например `environment=prod,staging`); одиночные значения также работают. С `latest_per_session=true` ответ содержит максимум одну строку для каждого `session_id` (самую последнюю по `completed_at`), используется страницей списка сессий для свёртывания временной линии оценок сессии к её текущему заголовку. По умолчанию false (возвращает полную историю). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | Свёрнутое здоровье оценок для отфильтрованного набора: общее количество, разбор done/error/timeout, статистика для каждого ключа оценки (count/avg/min/max/p50 над произвольными ключами `scores`), и временная линия, разбитая на временные интервалы. Принимает **те же параметры фильтра, что и `/evaluations`** плюс `featured_keys` (CSV ключей оценок для отслеживания) и `latest_per_session`. Питает функцию Dashboards; метрики являются точными по всему совпадающему набору, не выборкой. | -| `GET` | `/evaluations/environments` | `evaluations:read` | Различные значения окружения из таблицы `evaluations`. Используется для заполнения фильтров-выпадающих меню, ограниченных данными, читаемыми для оценок. | -| `GET` | `/evaluation-jobs` | `evaluations:read` | Видимость в процессе выполняемых оценок. Фильтруйте по `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | Потоковая передача необработанных событий сессии. Поддерживает `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` и `order`. `order` — это `desc` (новое первым, по умолчанию) или `asc` (старое первым); неузнанное значение падает обратно на `desc`. Разбор по курсору через `next_cursor` ответа (id события): передайте его обратно как `cursor` для получения следующей страницы; с `asc` следующая страница — это события после этого id, с `desc` — события перед ним. `limit` по умолчанию 50 и ограничен на 1000. | -| `GET` | `/sessions/:session_id/export` | `events:read` | Возвращает точное тело JSON, которое оценивающий сервис получит для этой сессии, обслуживаемое как загружаемое вложение с именем `session-.json`. Полезно для воспроизведения производственных сессий через `agenteye-evaluator` для автономного тестирования. Байты идентичны тому, что отправляет конвейер оценки. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Поставить в очередь свежую оценку для сессии; запускается независимо от того, существует ли предыдущая оценка. Новый результат **добавляется** к временной линии оценок сессии вместо перезаписи предыдущей, поэтому предыдущие оценки остаются видимыми как история. Возвращает `202` при постановке в очередь, `404` для неизвестной сессии, `409` если оценка уже выполняется. Используйте это после развёртывания нового оценивающего сервиса или для сессий, которые никогда не генерировали `agent_end`. | +| `GET` | `/evaluations` | `evaluations:read` | Запрос окончательных результатов. Поддерживает `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` по умолчанию 50 и ограничен 200 (учтите, что это отличается от `/events`, который ограничен 1000). `environment` принимает разделённый запятыми список (например `environment=prod,staging`); отдельные значения также работают. С `latest_per_session=true` ответ содержит максимум одну строку на `session_id` (самую свежую по `completed_at`), используемую страницей списка сеансов для свёртывания шкалы времени оценки сеанса до текущего заголовка. По умолчанию false (возвращает полную историю). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | Свёрнутое здоровье оценки для отфильтрованного среза: общее количество, разбор done/error/timeout, статистика по ключам каждой оценки (count/avg/min/max/p50 по произвольным ключам `scores`) и шкала времени с временными рамками. Принимает **те же параметры фильтра, что и `/evaluations`** плюс `featured_keys` (CSV ключей оценок для отслеживания) и `latest_per_session`. Работает функция Dashboards; метрики точны по всему соответствующему набору, а не выборочны. | +| `GET` | `/evaluations/environments` | `evaluations:read` | Различные значения окружения из таблицы `evaluations`. Используется для заполнения раскрывающихся списков фильтров в масштабе данных, для которых можно читать оценки. | +| `GET` | `/evaluation-jobs` | `evaluations:read` | Видимость в полёте оценок. Фильтр по `status` (`pending`/`polling`). | +| `GET` | `/events` | `events:read` | Потоковая передача необработанных событий сеанса. Поддерживает `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` и `order`. `order` — это `desc` (новые-первые, по умолчанию) или `asc` (старые-первые); неузнанное значение возвращается к `desc`. Курсорная пагинация через `next_cursor` ответа (ID события): передайте его как `cursor` для получения следующей страницы; с `asc` следующая страница — события после этого ID, с `desc` — события перед ним. `limit` по умолчанию 50 и ограничен 1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | Возвращает точное тело JSON, которое получит оценщик для этого сеанса, обслуживаемое как загружаемое вложение с именем `session-.json`. Полезно для воспроизведения рабочих сеансов через `agenteye-evaluator` для автономного тестирования. Байты идентичны тем, которые отправляет конвейер оценщика. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Поставить в очередь новую оценку для сеанса; запускается независимо от того, существует ли предыдущая оценка. Новый результат **добавляется** в шкалу времени оценки сеанса вместо перезаписи предыдущего, поэтому предыдущие оценки остаются видимыми как история. Возвращает `202` при постановке в очередь, `404` для неизвестного сеанса, `409` если оценка уже выполняется. Используйте это после развёртывания нового оценщика или для сеансов, которые никогда не отправляли `agent_end`. | ### Фильтрация по диапазону оценок: `score_filters` -`GET /evaluations` принимает дополнительный параметр `score_filters`, который -сужает результаты по числовым значениям внутри объекта `scores`. Параметр -является списком, разделённым запятыми, записей `key:min..max`; любая граница может быть -опущена. Несколько записей объединяются логическим И. Строки, -где названный ключ отсутствует или не числовой, исключены. Запрос может -содержать максимум 20 записей фильтра; превышение этого возвращает HTTP 400. +`GET /evaluations` принимает опциональный параметр `score_filters`, который сужает результаты по числовым значениям внутри объекта `scores`. Параметр — это разделённый запятыми список записей `key:min..max`; любая граница может быть опущена. Несколько записей объединяются с логическим AND. Строки, в которых указанный ключ отсутствует или не является числовым, исключаются. Запрос может содержать максимум 20 записей фильтра; превышение этого возвращает HTTP 400. Примеры: ```text -# helpfulness в [0.5, 0.8] +# helpfulness in [0.5, 0.8] GET /evaluations?score_filters=helpfulness:0.5..0.8 -# tool_efficiency максимум 0.3 (без нижней границы) +# tool_efficiency at most 0.3 (no lower bound) GET /evaluations?score_filters=tool_efficiency:..0.3 -# helpfulness >= 0.5 И factuality >= 0.9 +# helpfulness >= 0.5 AND factuality >= 0.9 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` @@ -283,119 +218,83 @@ GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. | Поле | Тип | Примечания | |---|---|---| -| `evaluation_id` | строка (UUID) | Канонический идентификатор этой финальной оценки. Каждая финальная оценка получает новый UUID; одна сессия может содержать несколько. | -| `id` | строка (UUID) | Обратная совместимость, получает такое же значение как `evaluation_id`. | -| `session_id` | строка | Сессия, для которой запустилась оценка. Сессия может иметь несколько оценок в временной линии. | -| `agent_id` | строка | Идентифицирует агента, который произвёл сессию. | -| `environment` | строка | Метка окружения, скопированная из сессии. | +| `evaluation_id` | строка (UUID) | Каноническое имя этой окончательной оценки. Каждая окончательная оценка получает новый UUID; один сеанс может содержать несколько. | +| `id` | строка (UUID) | Псевдоним обратной совместимости с тем же значением, что и `evaluation_id`. | +| `session_id` | строка | Сеанс, на котором была запущена эта оценка. Сеанс может иметь несколько оценок в шкале времени. | +| `agent_id` | строка | Идентифицирует агента, который создал сеанс. | +| `environment` | строка | Этикетка окружения, скопированная из сеанса. | | `status` | enum | Одно из `"done"`, `"error"`, `"timeout"`. | -| `scores` | объект \| null | Оценки, возвращённые вашим оценивающим сервисом. | -| `reasoning` | объект \| null | Опциональная карта обоснований для каждой оценки, возвращённая вашим оценивающим сервисом. Ключи типично зеркалируют те, что в `scores`. Панель отображает каждую запись под её полосой оценки. | -| `summary` | строка \| null | Опциональное описание в один абзац, возвращённое вашим оценивающим сервисом. Панель отображает это выше разбора по параметрам как заголовок оценки. | -| `error` | строка \| null | Заполнено только на `"error"` / `"timeout"`. | +| `scores` | объект \| null | Оценки, возвращённые вашим оценщиком. | +| `reasoning` | объект \| null | Опциональная карта обоснования для каждой оценки, возвращённая вашим оценщиком. Ключи обычно совпадают с ключами в `scores`. Панель отображает каждую запись под своей полосой оценки. | +| `summary` | строка \| null | Опциональное однопараграфное общее повествование, возвращённое вашим оценщиком. Панель отображает это над разбором по оценкам как заголовок оценки. | +| `error` | строка \| null | Заполнено только для `"error"` / `"timeout"`. | | `attempt_count` | целое число | Количество попыток отправки (≥ 1). | -| `duration_ms` | целое число \| null | Продолжительность финальной попытки. | -| `completed_at` | строка (ISO 8601 UTC) | Когда был записан финальный результат. Результаты упорядочены по `completed_at` (новое первым). | -| `created_at` | строка (ISO 8601 UTC) | Имеет такой же таймстэмп как `completed_at` (семантика write-once). | +| `duration_ms` | целое число \| null | Длительность последней попытки. | +| `completed_at` | строка (ISO 8601 UTC) | Когда был записан окончательный результат. Результаты упорядочены по `completed_at` (новые первыми). | +| `created_at` | строка (ISO 8601 UTC) | Переносит то же самое время, что и `completed_at` (семантика записи один раз). | --- ## Разрешения -| Разрешение | Предоставляет доступ к | +| Разрешение | Предоставляет | |---|---| -| `evaluations:read` | Список результатов оценок, просмотр оценок на панели, загрузка метрик здоровья панели. | -| `evaluations:trigger` | Ручное поставление в очередь оценки для сессии через `POST /sessions/:session_id/re-evaluate` или кнопку переоценки на панели. | -| `dashboards:read` | Просмотр сохранённых панелей (также нужен `evaluations:read` для загрузки их метрик). | +| `evaluations:read` | Список результатов оценки, просмотр оценок на панели и загрузка метрик здоровья панели. | +| `evaluations:trigger` | Вручную поставить в очередь оценку для сеанса через `POST /sessions/:session_id/re-evaluate` или кнопку переоценки на панели. | +| `dashboards:read` | Просмотр сохранённых панелей (также нужно `evaluations:read` для загрузки их метрик). | | `dashboards:write` | Создание и редактирование панелей. | | `dashboards:delete` | Удаление панелей. | -Администратор начальной загрузки (`ADMIN_KEY`, `ADMIN_EMAIL`) автоматически получает эти. +Администратор-инициалиризатор (`ADMIN_KEY`, `ADMIN_EMAIL`) автоматически получает эти разрешения. --- ## Просмотр результатов -- **`/sessions/`**: временная линия событий + правая панель, отображающая - оценки сессии и любую ошибку попытки отправки. Если ваш ключ имеет - `evaluations:trigger`, кнопка **переоценить** появляется рядом с кнопкой экспорта, - полезно для сессий, которые никогда не генерировали `agent_end`, или для - обновления оценок после развёртывания нового оценивающего сервиса. Панель опрашивает новый - результат и обновляет правую панель когда он приходит. -- **`/sessions`**: фильтруемая сетка сессий; столбец оценок показывает статус - оценки каждой сессии и оценки с первого взгляда. -- **`/dashboards`**: сохранённые представления здоровья оценок (см. [Dashboards](#dashboards) ниже). +- **`/sessions/`**: шкала времени событий + правая панель, показывающая оценки сеанса и любую ошибку из попытки отправки. Если ваш ключ имеет `evaluations:trigger`, рядом с кнопкой экспорта появляется кнопка **переоценки**, полезная для сеансов, которые никогда не отправляли `agent_end`, или для обновления оценок после развёртывания нового оценщика. Панель опрашивает новый результат и обновляет правую панель когда он приходит. +- **`/sessions`**: фильтруемая сетка сеансов; столбец оценок показывает статус оценки каждого сеанса и оценки с первого взгляда. +- **`/dashboards`**: сохранённые представления здоровья оценки (см. [Панели](#панели) ниже). -![Сетка Sessions с табличками статуса оценки для каждой сессии и значками оценок с цветовой кодировкой (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) +![Сетка Sessions с таблетками статуса оценки для каждого сеанса и цветными значками оценок (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) -*Сетка сессий показывает статус оценки каждого запуска и оценки с первого взгляда; красные/янтарные/зелёные значки выделяют низкие оценки.* +*Сетка сеансов показывает статус оценки каждого запуска и оценки с первого взгляда; красные/жёлтые/зелёные значки заставляют низкие оценки выделяться.* --- -## Dashboards +## Панели -Страница **Dashboards** (`/dashboards`) позволяет вам сохранить комбинацию фильтров оценок как -именованное, переиспользуемое представление и смотреть, как этот срез оценок -работает с первого взгляда. Dashboards **совместно используются всей вашей организацией**; -все с `dashboards:read` видят одно и то же множество. +Страница **Dashboards** (`/dashboards`) позволяет вам сохранить комбинацию фильтров оценки как именованное, повторно используемое представление и смотреть, как этот срез оценок делает с первого взгляда. Панели **общие для всей вашей организации**; все с `dashboards:read` видят один и тот же набор. Каждая панель закрепляет: -- **Filters**: те же элементы управления, что на странице сессий: окружение, статус, - агент, скользящее окно времени и фильтры диапазонов оценок (`key:min..max`). -- **Конфигурацию отображения**: какие ключи оценок выделить, пороги здоровья зелёный/янтарный/красный, - какие панели показывать и сворачивать ли на самую последнюю - оценку для каждой сессии. +- **Фильтры**: те же элементы управления, что на странице сеансов: окружение, статус, агент, скользящее временное окно и фильтры диапазона оценок (`key:min..max`). +- **Конфигурация отображения**: какие ключи оценок выделить, зелёные/жёлтые/красные пороги здоровья, какие панели показать и следует ли свёртывать до самой свежей оценки для каждого сеанса. -Каждая карточка показывает количество совпадающих сессий, разбор done/error/timeout, -среднее значение каждой выделенной оценки и небольшую тренд-спарклайн. Открытие -панели показывает полные панели; **"открыть в сессиях"** берёт вас на -страницу сессий с предустановленным фильтром на точно этот срез. Метрики вычисляются -на сервере по всему совпадающему набору (через `GET /evaluations/aggregate`), поэтому -числа точные вместо выборки. +Каждая карточка показывает количество соответствующих сеансов, разбор done/error/timeout, среднее значение каждой выделенной оценки и небольшую линию тренда. Открытие панели показывает полнораз панели; **"открыть в сеансах"** переносит вас на страницу сеансов предварительно отфильтрованную ровно на этот срез. Метрики вычисляются на сервере по всему соответствующему набору (через `GET /evaluations/aggregate`), так что числа точны, а не выборочны. -![Панель здоровья оценок со средними полосами оценок для каждого измерения оценивающего сервиса, разбором инструментов ok-vs-error, топ-инструментами и трендом событий в час](/agenteye/images/dashboard-quality.png) +![Панель eval-health со столбцами средней оценки для каждого измерения оценщика, разбором инструмента ok-vs-error, лучшими инструментами и трендом событий в час](/agenteye/images/dashboard-quality.png) -**Разрешения:** просмотр нуждается в `dashboards:read` и `evaluations:read`; -создание и редактирование нужны `dashboards:write`; удаление нужно `dashboards:delete`. -Администратор начальной загрузки автоматически получает все эти. +**Разрешения:** просмотр требует оба `dashboards:read` и `evaluations:read`; создание и редактирование требует `dashboards:write`; удаление требует `dashboards:delete`. Администратор-инициалиризатор получает все эти разрешения автоматически. --- -## Решение проблем +## Устранение неполадок -**Сессии существуют, но оценки не создаются.** Подтвердите, что `EVALUATOR_ENDPOINT` -установлен на процесс сервера, что сервер и оценивающий сервис разделяют одно и то же -значение `EVALUATOR_TOKEN`, и что конечная точка `/health` оценивающего сервиса -доступна с сервера. С `EVALUATOR_ENDPOINT` не установленным конвейер неактивен. +**Сеансы существуют, но не создаются оценки.** Подтвердите, что `EVALUATOR_ENDPOINT` установлен в процессе сервера, что сервер и оценщик совместно используют то же значение `EVALUATOR_TOKEN`, и что конечная точка `/health` оценщика достижима с сервера. С неустановленным `EVALUATOR_ENDPOINT` конвейер не работает. -**Выполняемые оценки накапливаются.** Запросите `GET /evaluation-jobs`, чтобы увидеть -очередь выполняемых. Проверьте `attempt_count`, `next_attempt_at` и `last_error` -на каждой строке. Обычные причины: сервис оценки недоступен или возвращает 5xx -(повторяется с задержкой), неправильный `EVALUATOR_TOKEN` (401 является финальной), или -асинхронный оценивающий сервис, который возвращает `pending` бесконечно (см. ниже). +**Оценки в полёте накапливаются.** Запросите `GET /evaluation-jobs` для просмотра очереди в полёте. Проверьте `attempt_count`, `next_attempt_at` и `last_error` в каждой строке. Частые причины: сервис оценщика недостижим или возвращает 5xx (повторяется с задержкой), неправильный `EVALUATOR_TOKEN` (401 окончательный), или асинхронный оценщик, который возвращает `pending` неопределённо долго (см. ниже). -**Сессии завершены, но нет финальной оценки.** Запросите -`GET /evaluation-jobs?status=polling`; результат может всё ещё выполняться. -Если задача зависла на `pending`, сервер испытывает сложности с доступом к оценивающему сервису; -проверьте, что оценивающий сервис работает и что `EVALUATOR_TOKEN` совпадает. +**Сеансы завершены, но нет окончательной оценки.** Запросите `GET /evaluation-jobs?status=polling`; результат может всё ещё быть в полёте. Если задача застрянула в `pending`, серверу не удаётся достичь оценщика; проверьте, что оценщик работает и что `EVALUATOR_TOKEN` совпадает. -**`HTTP 401 от оценивающего сервиса: неверный токен носителя`.** `EVALUATOR_TOKEN` -на сервере не совпадает со значением, с которым настроен сервис оценки. -Они должны быть идентичны. +**`HTTP 401 from evaluator: invalid bearer token`.** `EVALUATOR_TOKEN` на сервере не совпадает со значением, которым настроен сервис оценщика. Они должны быть идентичны. -**Асинхронный оценивающий сервис возвращает `pending` бесконечно.** Сервер опрашивает -`GET /evaluate/{job_id}` до тех пор, пока оценивающий сервис не вернёт `done` или `error`, -или пока не истечёт `EVALUATOR_MAX_POLL_DURATION_SECS` (по умолчанию 1 ч). После лимита -оценка записывается как `timeout` и удаляется из очереди выполняемых. -Увеличьте `EVALUATOR_MAX_POLL_DURATION_SECS`, если ваш оценивающий сервис законно нуждается -в большем времени, чем по умолчанию. +**Асинхронный оценщик возвращает `pending` вечно.** Сервер опрашивает `GET /evaluate/{job_id}` до тех пор, пока оценщик не вернёт `done` или `error`, или до истечения `EVALUATOR_MAX_POLL_DURATION_SECS` (по умолчанию 1 ч). После превышения крышки оценка записывается как `timeout` и удаляется из очереди в полёте. Поднимите `EVALUATOR_MAX_POLL_DURATION_SECS`, если вашему оценщику законно требуется больше времени, чем по умолчанию. --- -## Следующие шаги +## Дальнейшие шаги -- [Evaluator agent skill](/ru/agenteye/evaluator-skill): попросите кодирующего агента спроектировать ваши параметры на основе реальных сессий и построить для вас этот сервис. -- [Python SDK](/ru/agenteye/python-sdk): генерируйте события `agent_end`, которые запускают оценку. -- [API keys](/ru/agenteye/api-keys): разрешения `evaluations:read` и `evaluations:trigger`. -- [Audits](/ru/agenteye/audits): другая автоматизированная функция качества Observability для проверки на основе политик. \ No newline at end of file +- [Навык агента оценщика](/ru/agenteye/evaluator-skill): попросите кодирующего агента спроектировать ваши размеры против реальных сеансов и построить этот сервис для вас. +- [Python SDK](/ru/agenteye/python-sdk): отправьте события `agent_end`, которые запускают оценку. +- [Ключи API](/ru/agenteye/api-keys): разрешения `evaluations:read` и `evaluations:trigger`. +- [Аудиты](/ru/agenteye/audits): другая автоматизированная функция качества Observability, для рецензирования на основе политики. \ No newline at end of file diff --git a/docs/ru/agenteye/evaluations.mdx b/docs/ru/agenteye/evaluations.mdx index e2b9ccca..0eaf45c4 100644 --- a/docs/ru/agenteye/evaluations.mdx +++ b/docs/ru/agenteye/evaluations.mdx @@ -1,51 +1,51 @@ --- title: "Оценки" -description: "Проблемы качества находятся вами сейчас, а не узнаются из жалоб пользователей." +description: "Проблемы качества находят вас сейчас, вместо того чтобы вы узнали о них из жалобы пользователя." --- -Проблемы качества находятся вами сейчас, а не узнаются из жалоб пользователей. Подключите свой сервис оценки один раз, и Failproof AI Observability автоматически оценит каждый завершённый запуск, поэтому снижение полезности или всплеск галлюцинаций проявится сами по себе, до того как это почувствует клиент. +Проблемы качества находят вас сейчас, вместо того чтобы вы узнали о них из жалобы пользователя. Подключите свой сервис оценки один раз, и Failproof AI Observability автоматически оценивает каждый завершённый запуск, поэтому падение полезности или всплеск галлюцинаций проявятся сами по себе, прежде чем это почувствует клиент. -![Сетка сессий с колонкой оценки: каждый запуск содержит статус оценки и цветовые значки полезности, факт-проверяемости и эффективности использования инструментов](/agenteye/images/sessions-list.png) +![Таблица сессий со столбцом оценки: каждый запуск содержит значок статуса оценки и цветные значки полезности, фактичности и эффективности использования инструментов](/agenteye/images/sessions-list.png) -*Каждый запуск в сетке сессий содержит свои оценки; красные, жёлтые и зелёные значки выделяют слабые запуски без необходимости открывать транскрипты.* +*Каждый запуск в таблице сессий содержит свои оценки; красные, жёлтые и зелёные значки делают слабые запуски заметными без открытия единой стенограммы.* -## Прекратите выборочную проверку запусков вручную +## Прекратите проверку запусков вручную -Раньше вы проверяли вручную несколько запусков и надеялись, что остальные в порядке. Теперь каждая завершённая сессия оценивается в момент завершения по интересующим вас параметрам: полезность, эффективность использования инструментов, факт-проверяемость, безопасность, любые ваши критерии качества. Вы определяете ключи оценки; Failproof AI Observability сохраняет, отслеживает и отображает любую информацию, которую возвращает ваша система оценки. Ни один запуск не остаётся без оценки, и вы перестаёте узнавать о регрессии из тикета поддержки. +Раньше вы выборочно проверяли несколько запусков и надеялись, что остальные прошли хорошо. Теперь каждая завершённая сессия оценивается сразу же после завершения по интересующим вас параметрам: полезность, эффективность использования инструментов, фактичность, безопасность — всё, что определяет ваш уровень качества. Вы определяете ключи оценки; Failproof AI Observability хранит, отслеживает и отображает всё, что отправляет ваш оценщик. Ни один запуск не остаётся без оценки, и вы перестаёте узнавать о регрессии из письма в поддержку. -Оценки отображаются в сетке сессий по адресу **`//sessions`** (боковая панель → *observe* → *sessions*), с кластером значков в каждой строке. Хотите только запуски, которые не прошли? Отфильтруйте сетку по диапазону оценок, например полезность ниже 0,5, и вы получите ровно те запуски, которые стоит прочитать. Для просмотра оценок требуется разрешение `evaluations:read`. +Оценки отображаются в таблице сессий **`//sessions`** (боковая панель → *observe* → *sessions*), один кластер значков в строку. Хотите увидеть только запуски, не соответствующие требованиям? Отфильтруйте таблицу по диапазону оценок, например полезность ниже 0,5, и получите ровно те запуски, которые стоит прочитать. Для просмотра оценок требуется разрешение `evaluations:read`. ## Узнайте, почему запуск получил низкую оценку -Число говорит вам, что запуск был слабым; страница сессии объясняет почему. Откройте любой запуск, и правая панель показывает краткое резюме, затем полосу для каждого параметра с собственными рассуждениями оценщика под каждой, чтобы вы перешли от «это получило 0,4 за факт-проверяемость» к точному утверждению, в котором ошибка, за секунды. +Число показывает, что запуск был слабым; страница сессии показывает почему. Откройте любой запуск, и правая колонка начнётся с краткого резюме, затем покажет полосу для каждого параметра с объяснением вашего оценщика под каждой, поэтому вы переходите от «это получило 0,4 по фактичности» к точному утверждению, которое оно неправильно интерпретировало, за секунды. -![Правая панель сессии: сводка оценки вверху, затем полосы оценок для каждого параметра с кратким обоснованием рядом с полной временной шкалой событий](/agenteye/images/session-detail.png) +![Правая колонка сессии: сводка оценки сверху, затем полосы оценок для каждого параметра, каждая с пояснением, рядом с полной временной шкалой событий](/agenteye/images/session-detail.png) -*Вид деталей сессии: резюме, полосы оценок для каждого параметра и обоснование каждой оценки прямо рядом с временной шкалой событий запуска.* +*Представление деталей сессии: сводка, полосы оценок для каждого параметра и обоснование каждой оценки рядом с временной шкалой событий запуска.* -Развернули улучшенную систему оценки или рассматриваете запуск, который упал до оценки? Кнопка **re-evaluate** (с ограничением `evaluations:trigger`) переоценивает сессию на месте и добавляет свежий результат на её временную шкалу, поэтому более старые оценки остаются видны как история. Вы найдёте её по адресу **`//sessions/`**. +Развернули более совершенный оценщик или рассматриваете запуск, который вылетел до того, как мог быть оценен? Кнопка **re-evaluate** (управляется `evaluations:trigger`) переоценивает сессию на месте и добавляет свежий результат в её временную шкалу, поэтому предыдущие оценки остаются видны как история. Вы найдёте её на **`//sessions/`**. -## Следите за тенденциями качества по всему парку +## Наблюдайте тренд качества по всему парку -Один запуск с низкой оценкой — это шум; целая группа с понижением — это сигнал. Сохранённые панели превращают ваши оценки в тенденцию, которую вы можете отслеживать с первого взгляда: средняя полезность на этой неделе против прошлой, по агентам, по окружениям. +Один запуск с низкой оценкой — это шум; целая группа, скользящая вниз — это сигнал. Сохранённые панели инструментов превращают ваши оценки в тренд, который вы можете отследить с первого взгляда: средняя полезность на этой неделе против прошлой, по агенту, по окружению. -![Панель качества: столбцы средних оценок для каждого параметра оценки рядом с графиком тренда во времени](/agenteye/images/dashboard-quality.png) +![Панель качества: полосы средней оценки для каждого измерения оценщика рядом с трендом во времени](/agenteye/images/dashboard-quality.png) -*Сохранённая панель качества отслеживает трендовые ключи оценок, которые вы выбрали, поэтому медленный дрейф становится очевиден задолго до того, как он перейдёт в инцидент.* +*Сохранённая панель качества отслеживает ключи оценок, которые вы выделили, поэтому медленный дрейф очевиден задолго до того, как он станет инцидентом.* -Панели находятся по адресу **`//dashboards`** (боковая панель → *analyze* → *dashboards*), общие для всей организации, и каждая карточка агрегирует соответствующие сессии: сколько их, среднее значение каждой отображаемой оценки и спарклайн тренда. «Open in sessions» переводит вас непосредственно в предварительно отфильтрованные запуски, стоящие за любым числом. Для просмотра требуется `dashboards:read` плюс `evaluations:read`. +Панели инструментов находятся на **`//dashboards`** (боковая панель → *analyze* → *dashboards*), используются всей организацией, и каждая карточка подводит итоги по соответствующим сессиям: сколько их, среднее значение каждой выделенной оценки и спарклайн тренда. «Open in sessions» доставляет вас прямо в предварительно отфильтрованные запуски, лежащие в основе любого числа. Для просмотра требуется `dashboards:read` плюс `evaluations:read`. ## Подключите оценщика один раз -Оценка — это опциональный компонент и остаётся полностью отключённой до тех пор, пока вы не укажете Failproof AI Observability адрес оценщика. Вы поднимаете один небольшой HTTP-сервис (в Observability есть работающий эталон, который вы можете скопировать), устанавливаете два значения на вашем сервере, и каждый запуск с этого момента оценивается для вас. Полное пошаговое руководство, контракт оценки и SDK находятся в подробном руководстве. +Оценка является дополнительной и остаётся полностью отключённой до тех пор, пока вы не укажете Failproof AI Observability на оценщик. Вы создаёте один небольшой HTTP-сервис (Observability поставляется с рабочей ссылкой, которую вы можете скопировать), устанавливаете два значения на вашем сервере, и каждый запуск с этого момента оценивается для вас. Полное пошаговое руководство, контракт оценки и SDK находятся в подробном руководстве. -Не уверены, какие параметры в принципе стоит оценивать? [Навык агента-оценщика](/ru/agenteye/evaluator-skill) поможет вашему кодирующему агенту разобраться с этим на основе ваших собственных сессий, а затем построить и развернуть сервис. +Не уверены, какие параметры вообще стоит оценивать? [Навык агента оценщика](/ru/agenteye/evaluator-skill) поможет вашему кодирующему агенту разобраться в этом на основе ваших собственных сессий, а затем построить и развернуть сервис. -## Связанные разделы +## Связанные материалы -- [Набор оценок](/ru/agenteye/evaluation-suite): подключение оценщика, контракт оценки и SDK. -- [Навык агента-оценщика](/ru/agenteye/evaluator-skill): позвольте кодирующему агенту выбрать параметры оценки и построить оценщик. -- [Сессии](/ru/agenteye/sessions): сетка запусков, где отображаются оценки. -- [Панели](/ru/agenteye/dashboards): сохраняйте и делитесь тенденциями качества в вашей организации. -- [Аудиты](/ru/agenteye/audits): другая автоматическая функция качества Observability для кроссе-сессионных расследований. \ No newline at end of file +- [Evaluation suite](/ru/agenteye/evaluation-suite): подключите ваш оценщик, контракт оценки и SDK. +- [Evaluator agent skill](/ru/agenteye/evaluator-skill): позвольте кодирующему агенту выбрать ваши параметры оценки и построить оценщик. +- [Sessions](/ru/agenteye/sessions): таблица запусков, где появляются оценки. +- [Dashboards](/ru/agenteye/dashboards): сохраняйте и делитесь трендами качества в вашей организации. +- [Audits](/ru/agenteye/audits): другая автоматическая функция качества Observability для исследований между сессиями. \ No newline at end of file diff --git a/docs/ru/agenteye/evaluator-skill.mdx b/docs/ru/agenteye/evaluator-skill.mdx index 1afb464b..ea010101 100644 --- a/docs/ru/agenteye/evaluator-skill.mdx +++ b/docs/ru/agenteye/evaluator-skill.mdx @@ -1,76 +1,76 @@ --- --- -title: "Навык Failproof AI Observability Evaluator Agent" -description: "От «я думаю, что наш агент иногда работает плохо» к развёрнутому сервису оценки, где кодирующий агент сам принимает решения и строит решение." +title: "Умение агента оценки наблюдаемости Failproof AI" +description: "От «мне кажется, наш агент иногда работает плохо» к развёрнутому сервису оценки, где ваш кодирующий агент и решает, и строит." --- -От *«я думаю, что наш агент иногда работает плохо»* к развёрнутому сервису оценки, где кодирующий агент сам принимает решения и строит решение. **Навык Failproof AI Observability evaluator** (`agenteye-evaluator`) — это *Agent Skill*: небольшая папка с инструкциями, которые кодирующий агент, такой как Claude Code или Codex, загружает по требованию. Она учит агента определять, какие показатели качества стоит отслеживать для *вашего* агента, а затем писать, тестировать и развёртывать [сервис оценки](/ru/agenteye/evaluation-suite), который их оценивает. +От *«мне кажется, наш агент иногда работает плохо»* к развёрнутому сервису оценки, где ваш кодирующий агент и решает, и строит. **Умение оценки наблюдаемости Failproof AI** (`agenteye-evaluator`) — это *Agent Skill*: небольшая папка с инструкциями, которую по требованию загружает кодирующий агент, такой как Claude Code или Codex. Она учит агента определять, какие аспекты качества стоит отслеживать для *вашего* агента, а затем писать, тестировать и развёртывать [сервис оценки](/ru/agenteye/evaluation-suite), который их оценивает. -Это **не** размещённый скорер, реестр для загрузки или система плагинов. Ваша оценка остаётся вашей собственной HTTP-службой на вашей инфраструктуре, точно так, как описано в руководстве [Evaluation suite](/ru/agenteye/evaluation-suite). Навык только учит вашего агента строить её правильно, поэтому всё, что она делает, вы могли бы сделать сами, написав тот же код. +Это **не** размещённый на сервере скорер, реестр, в который вы загружаете данные, и не система плагинов. Ваш оценщик остаётся вашим собственным HTTP-сервисом на вашей собственной инфраструктуре, точно так, как описано в руководстве [Набор инструментов оценки](/ru/agenteye/evaluation-suite). Умение только учит вашего агента строить его хорошо, поэтому всё, что он делает, вы могли бы сделать сами, написав тот же код. --- -## Сложная часть — решить, что оценивать +## Самое сложное — решить, что оценивать -Поверхность SDK небольшая — декоратор и две модели — и агент может написать это просто по [контракту](/ru/agenteye/evaluation-suite#http-contract). В этом не проблема оценок. Они не работают, потому что оценивают неправильное, и оценка, которая оценивает неправильное, хуже, чем никакая: она создаёт панель управления, которую все учатся игнорировать. +Поверхность SDK мала — декоратор и две модели — и агент может написать это только из [контракта](/ru/agenteye/evaluation-suite#http-contract). Вот где не происходит сбой оценщиков. Они сбиваются, потому что оценивают не то, и оценщик, оценивающий не то, хуже, чем никакой: он создаёт приборную панель, которую все учатся игнорировать. -Поэтому большая часть навыка — это часть до того, как существует код. Агент берёт у вас интервью (*«опишите сеанс, который прошёл хорошо; теперь один, который прошёл плохо»*), затем загружает ваши реальные сеансы через [`agenteye` CLI](/ru/agenteye/cli) и читает их от начала до конца. Эти две части обычно не совпадают, и разрыв — это именно то, что нужно: что вы намерены измерять против того, что ваши расшифровки могут реально поддерживать. Измерение выживает только если оно **вычислимо** из событий и **дискриминирующее** — если оно выставляет 0,9 как для вашего хорошего, так и для вашего плохого сеанса, оно ничему не учит и исключается. +Поэтому большая часть умения — это часть до того, как существует какой-либо код. Оно заставляет агента взять у вас интервью (*«опишите хороший запуск; теперь плохой»*), затем вытащить ваши реальные сессии через [`agenteye` CLI](/ru/agenteye/cli) и прочитать их от начала до конца. Эти две половины обычно не совпадают, и разрыв в том и есть суть: что вы намереваетесь измерить, против того, что ваши расшифровки могут фактически поддержать. Измерение выживает только если оно **вычислимо** на основе событий и **различительно** — если оно оценивает 0,9 и на вашем хорошем запуске, и на плохом, это ничему не учит и отсеивается. -То, что возвращается — предложение 2-4 измерений с приложенным обоснованием, которое вы подписываете перед тем, как будет написана строка кода. +Что возвращается — это предложение 2–4 измерений с приложенным обоснованием, чтобы вы одобрили его до того, как будет написана строка кода. ```mermaid flowchart TD - YOU["вы: 'Мне нужна оценка для моего бота поддержки'"] --> AGENT["кодирующий агент (Claude Code / Codex)
загружает навык agenteye-evaluator"] - AGENT -->|"интервью: как выглядит хорошее vs плохое?"| YOU - AGENT -->|"agenteye --json sessions / events"| DATA["ваши реальные сеансы
что действительно происходит"] - DATA --> DIMS["2-4 измерения, вы подписываете"] + YOU["вы: 'Мне нужны оценки для моего бота поддержки'"] --> AGENT["кодирующий агент (Claude Code / Codex)
загружает умение agenteye-evaluator"] + AGENT -->|"интервью: как выглядят хорошее и плохое?"| YOU + AGENT -->|"agenteye --json sessions / events"| DATA["ваши реальные сессии
что фактически происходит"] + DATA --> DIMS["2–4 измерения, вы одобряете"] DIMS --> SVC["ваш сервис оценки
agenteye-evaluator SDK"] - SVC --> SCORES["оценки попадают на панель
и в agenteye evals"] + SVC --> SCORES["оценки попадают на приборную панель
и в agenteye evals"] ``` --- -## Как это относится к другим частям оценки +## Как это связано с другими частями оценки -Четыре документа охватывают оценку и передают информацию друг другу по очереди: +Четыре документа охватывают оценку и передают друг другу по порядку: | Страница | Что это | Используйте, когда | |---|---|---| -| **[Evaluations](/ru/agenteye/evaluations)** | Функция: оценки на сетке сеансов, панели, переоценка | Вы хотите узнать, что вы получаете от автоматической оценки | -| **[Evaluation suite](/ru/agenteye/evaluation-suite)** | HTTP контракт, SDK, переменные окружения сервера | Вы реализуете или отлаживаете оценку самостоятельно | -| **Evaluator skill** (этот документ) | Естественный язык для проектирования *и* построения скорера | Вы хотите перейти от «мне нужна оценка» к работающему сервису | -| **[CLI skill](/ru/agenteye/cli-skill)** | Естественный язык для `agenteye` CLI | Вы хотите *читать* оценки, которые уже у вас есть | -| **[Python SDK skill](/ru/agenteye/python-sdk-skill)** | Естественный язык для инструментирования вашего агента | Ваш агент ещё не генерирует сеансы — нечего оценивать | +| **[Оценки](/ru/agenteye/evaluations)** | Функция: оценки на сетке сессий, приборные панели, переоценка | Вы хотите узнать, что даёт вам автоматическая оценка | +| **[Набор инструментов оценки](/ru/agenteye/evaluation-suite)** | HTTP-контракт, SDK, переменные окружения сервера | Вы реализуете или отлаживаете оценщик самостоятельно | +| **Умение оценщика** (этот документ) | Естественно-языковой фасад для проектирования *и* построения скорера | Вы хотите перейти от «мне нужны оценки» к работающему сервису | +| **[Умение CLI](/ru/agenteye/cli-skill)** | Естественно-языковой фасад для `agenteye` CLI | Вы хотите *читать* оценки, которые у вас уже есть | +| **[Умение Python SDK](/ru/agenteye/python-sdk-skill)** | Естественно-языковой фасад для инструментирования вашего агента | Ваш агент ещё не выводит сессии — нечего оценивать | -### vs. CLI skill: построение vs чтение +### в сравнении с умением CLI: построение против чтения -Два навыка намеренно неперекрывающиеся, и установка обоих — это обычная конфигурация — агент выбирает между ними в зависимости от того, что вы просите: +Два умения намеренно не перекрываются, и установка обоих — обычная установка — агент выбирает между ними на основе того, что вы просите: -- **`agenteye-evaluator`** (этот документ) строит то, что *производит* оценки. Его работа заканчивается, когда оценки появляются в первый раз. -- **[`agenteye-cli`](/ru/agenteye/cli-skill)** читает оценки, которые уже существуют (`agenteye evals`). *«Качество упало на этой неделе?»* — это его вопрос, не этого навыка. +- **`agenteye-evaluator`** (этот документ) строит то, что *производит* оценки. Его работа заканчивается, когда оценки впервые поступают. +- **[`agenteye-cli`](/ru/agenteye/cli-skill)** читает оценки, которые уже существуют (`agenteye evals`). *«Упало ли качество на этой неделе?»* — его вопрос, не этого умения. --- -## Предварительные требования +## Требования -1. **`agenteye` CLI установлен и подключён** (`pipx install agenteye`, затем `agenteye login`). Навык использует его дважды: для загрузки реальных сеансов, на которых он проектирует, и для подтверждения того, что ваши оценки появились в конце. Ваш логин нуждается в `events:read`, плюс `evaluations:read` для этой окончательной проверки. Как и в случае с CLI skill, он **не может** завершить отправленный по почте вход с одноразовым кодом за вас. -2. **Место для жизни оценки.** Она строится в образ и работает как долгоживущий сервис, поэтому ей нужно настоящее хранилище, а не временный файл. Оценки часто живут в собственном хранилище, отдельно от оцениваемого агента — навык ищет существующее и спрашивает перед построением нового. -3. **Колесо `agenteye-evaluator` SDK** — прочитайте следующий раздел перед тем, как ваш агент начнёт вводить команды `pip`. +1. **`agenteye` CLI установлен и вы вошли в систему** (`pipx install agenteye`, затем `agenteye login`). Умение опирается на него дважды: для получения реальных сессий, против которых оно проектирует, и для подтверждения того, что ваши оценки поступили в конце. Ваша учетная запись должна иметь `events:read`, плюс `evaluations:read` для этой финальной проверки. Как и с умением CLI, оно **не может** завершить для вас вход по отправленному по электронной почте одноразовому коду. +2. **Место для хранения оценщика.** Он собирается в образ и работает как долгоживущий сервис, поэтому ему нужна реальная репозитория, а не временный файл. Оценщики часто живут в отдельной репозитории, отдельно от оцениваемого агента — умение ищет существующую и спрашивает перед созданием новой. +3. **Колесо SDK `agenteye-evaluator`** — прочитайте следующий раздел перед тем, как ваш агент начнёт печатать команды `pip`. --- -## Где это получить +## Где его получить -Навык опубликован в публичной коллекции навыков Failproof AI: +Умение опубликовано в общественной коллекции умений Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -Хранилище публичное и навыку не нужно никаких собственных учётных данных — он только управляет `agenteye` CLI с сеансом, на который *вы* подключились, и пишет код в *ваше* хранилище. Обратите внимание, что он поставляется как собственная папка и **не** находится внутри пакета `pipx install agenteye`, поэтому не ищите его там. +Репозитория общедоступна и умению не требуется собственный пропуск — оно только управляет `agenteye` CLI с сессией, в которую вы вошли, и пишет код в *вашей* репозитории. Учтите, что оно поставляется как отдельная папка и **не** входит в пакет `pipx install agenteye`, поэтому не ищите его там. -## Установка навыка +## Установка умения -Самый быстрый способ — это CLI [`skills`](https://skills.sh), которая загружает папку и помещает её туда, где ваш агент ищет: +Самый быстрый путь — это CLI [`skills`](https://skills.sh), который получает папку и кладёт её туда, где ваш агент ищет: ```bash # Claude Code, только этот проект @@ -79,11 +79,11 @@ npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code # каждый проект (устанавливает в ~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy -# вместо этого Codex +# Codex вместо этого npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -Затем управляйте ею как любым другим навыком: +Затем управляйте им, как любым другим умением: ```bash npx skills list -a claude-code # что установлено @@ -91,81 +91,81 @@ npx skills update agenteye-evaluator # получить последнюю npx skills remove agenteye-evaluator # удалить ``` -Предпочитаете установить вручную? Agent Skill — это просто папка, содержащая `SKILL.md` (плюс опциональные ссылки), поэтому копирование тоже работает: +Предпочитаете устанавливать вручную? Agent Skill — это просто папка, содержащая `SKILL.md` (плюс опциональные ссылки), поэтому копирование работает: -- **Claude Code**: поместите папку `agenteye-evaluator/` в `~/.claude/skills/` (каждый проект) или `/.claude/skills/` (только это хранилище). Claude Code автоматически её обнаруживает — проверьте с помощью списка `/skills` или просто попросите оценки. -- **Codex (OpenAI)**: Codex читает тот же `SKILL.md`. Включённый `agents/openai.yaml` устанавливает `allow_implicit_invocation: true`, поэтому Codex автоматически выбирает навык при совпадении задачи; иначе вызовите его явно как `$agenteye-evaluator`. +- **Claude Code**: положите папку `agenteye-evaluator/` в `~/.claude/skills/` (каждый проект) или `/.claude/skills/` (только этот репозиторий). Claude Code автоматически его обнаруживает — проверьте с помощью списка `/skills` или просто попросите оценки. +- **Codex (OpenAI)**: Codex читает тот же `SKILL.md`. Включённый `agents/openai.yaml` устанавливает `allow_implicit_invocation: true`, поэтому Codex автоматически выбирает умение, когда задача совпадает; иначе вызывайте его явно как `$agenteye-evaluator`. --- -## SDK не на публичном PyPI +## SDK не в публичном PyPI > **Предупреждение:** прочитайте это перед тем, как позволить агенту установить SDK. -Навык публичный; SDK, который он управляет — нет. `agenteye-evaluator` поставляется только как приватный артефакт выпуска, и в отличие от `agenteye`, имя **не заявлено на публичном PyPI** — поэтому голый `pip install agenteye-evaluator` может загрузить пакет незнакомца в сервис, который читает ваши производственные расшифровки. Это проблема цепочки поставок, а не опечатка. +Умение общедоступно; SDK, который оно использует, нет. `agenteye-evaluator` поставляется только как приватный артефакт выпуска, и в отличие от `agenteye`, имя **не зарезервировано в общедоступном PyPI** — поэтому голая команда `pip install agenteye-evaluator` могла бы вытащить пакет незнакомца в сервис, который читает ваши производственные расшифровки. Это проблема цепочки поставок, а не опечатка. -Навык знает это и работает по лестнице установки, останавливаясь на первой применимой ступени: исходный код монорепозитория, если вы внутри репозитория AgentEye, иначе приватное колесо выпуска из GitHub Releases (нужен доступ), и если ни одно не достижимо, он **останавливается и говорит вам попросить колесо у вашего контакта Failproof AI** вместо импровизации. +Умение это знает и работает вниз по лестнице установки, останавливаясь на первой применимой ступени: исходный код монорепо, если вы внутри репозитория AgentEye, иначе приватное колесо выпуска из GitHub Releases (требует доступ), и если ни то, ни другое недоступно, оно **останавливается и просит вас попросить колесо у вашего контакта в Failproof AI** вместо импровизации. -Поэтому если ваш агент предлагает голый `pip install agenteye-evaluator` с публичного PyPI, это признак того, что навык никогда не загружался. Остановитесь там и проверьте, что он установлен. +Поэтому если ваш агент предлагает голую `pip install agenteye-evaluator` из общедоступного PyPI, это признак того, что умение никогда не загружалось. Остановитесь там и проверьте, установлено ли оно. --- -## Что вы можете просить +## Что вы можете у него спросить -Настоящий полный цикл начинается с нечёткого запроса и заканчивается подписанным дизайном, а не кодом: +Реальное полное путешествие начинается с неопределённого запроса и заканчивается одобренным дизайном, а не кодом: ```text -вы ▸ Мне нужна оценка для нашего бота поддержки. Я думаю, что - иногда он работает плохо. +вы ▸ Мне нужны оценки для нашего бота поддержки. Мне кажется, + он иногда работает плохо. -агент ▸ Перед тем, как писать: опишите сеанс, который прошёл - хорошо, и один, который прошёл плохо. +агент ▸ Перед тем как я что-то писал: опишите запуск, который + прошёл хорошо, и один, который прошёл плохо. -вы ▸ Хорошо: он отвечает из документов. Плохо: он выдумывает - или сдаётся и говорит «свяжитесь с поддержкой». +вы ▸ Хорошо: отвечает из документов. Плохо: выдумывает, + или сдаётся и говорит «обратитесь в поддержку». агент ▸ Запуск: agenteye --json sessions --status error --since 7d - Чтение 5 сеансов, включая два, которые вы назовёте плохими. - - Ваши слова говорят о точности фактов и отказах. - Расшифровки согласны на отказы (2 из 5 заканчиваются - переводом на поддержку, и это видно в model_response.content), - но точность фактов нужна истина, которую ваши события не содержат. - - Поэтому я буду оценивать три вещи: - - deflection правила, дёшево, разделяет ваши два сеанса - - tool_efficiency правила, ловят цикл переповтора в run-004 - - groundedness судья LLM: каждое ли утверждение в загруженных - документах? - - «точность фактов» потребовала бы истину, которой у нас нет; - groundedness — это ближайшее, что ваши расшифровки могут - действительно поддержать. Хорошо с этими тремя названиями? + Чтение 5 сессий, включая две, которые вы бы назвали плохими. + + Ваши слова говорят о фактичности и отклонениях. Расшифровки + согласны об отклонениях (2 из 5 заканчиваются передачей + поддержке, и это видно в model_response.content), но + фактичность нуждается в основании истины, которое ваши + события не содержат. + + Поэтому я оценил бы три вещи: + - deflection правила, дешёво, разделяет ваши два запуска + - tool_efficiency правила, ловит цикл повторов в run-004 + - groundedness судья LLM: каждое утверждение в полученных документах? + + «factuality» потребует основание истины, которого нет; + groundedness — это ближайшее, что ваши расшифровки + фактически поддерживают. Согласны ли вы с этими тремя? Переименование позже разбивает историю. вы ▸ да -агент ▸ Нет оценки в этом хранилище. Мне построить здесь новую - или у вас она есть где-то ещё? +агент ▸ Нет оценщика в этом репозитории. Я должен создать его + здесь, или у вас он есть в другом месте? ``` -Отсюда он пишет правила-измерения сначала (бесплатные, мгновенные, детерминированные), тестирует их против реального захваченного сеанса, включая пустые и никогда не завершённые, которые ломают наивные оценки, и только затем обращается к судье LLM для субъективного измерения. Он знает [ограничения диспетчера](/ru/agenteye/evaluation-suite#configuring-the-server) — 30-секундный таймаут запроса и 8 одновременных вызовов в развёртывании — поэтому если судья не поместится надёжно, он идёт асинхронно с `JobPending` вместо того, чтобы позволить вашему судье быть отменённым и переправленным пять раз в пять раз дороже. +Оттуда он пишет первыми правила-основанные измерения (бесплатно, мгновенно, детерминированно), тестирует их против реальной сохранённой сессии, включая пустые и никогда не завершённые, которые разбивают наивные оценщики, и только затем обращается к судье LLM для субъективного измерения. Он знает [пределы диспетчера](/ru/agenteye/evaluation-suite#configuring-the-server) — 30-секундный таймаут запроса и 8 одновременных вызовов развёртывания в целом — поэтому если судья не будет надёжно умещаться, он идёт асинхронно с `JobPending` вместо того, чтобы дать вашему судье быть отменённым и перепробованным пять раз в пять раз дороже. -Затем он развёртывает, устанавливает две переменные окружения сервера и подтверждает с помощью `agenteye --json evals --session-id `, что оценки действительно появились. Появление оценок — единственное доказательство. +Затем он развёртывает, устанавливает две переменные окружения сервера и подтверждает с `agenteye --json evals --session-id `, что оценки фактически поступили. Поступление оценок — единственное доказательство. --- ## На что обратить внимание -- **Названия измерений почти постоянны.** Ключи оценок — произвольные строки, и платформа тренирует всё, что вы отправляете, что означает, что ничто ниже не исправляет плохой выбор. Переименование позже и история разбивается: старые сеансы хранят старый ключ и тренд разбивается. Вот почему навык получает явное одобрение перед написанием кода — отнеситесь к этому приглашению серьёзно. -- **Фиксации — настоящие производственные расшифровки.** Проектирование против реальных сеансов означает их загрузку на диск, и они могут содержать данные клиентов. Навык спрашивает перед фиксацией в git; если сомневаетесь, держите `fixtures/` вне хранилища и попросите каждого разработчика загрузить свои собственные. -- **Агент пишет и развёртывает сервис, который читает каждую расшифровку.** Он действует от вашего имени, ограниченный разрешениями логина вашего CLI, но просмотрите оценку как любой другой код, который касается производственных данных. +- **Названия измерений близки к постоянным.** Ключи оценок — произвольные строки, и платформа тренирует всё, что вы отправляете, что означает, что ничто ниже не исправляет плохой выбор. Переименуйте позже и история разделится: старые сессии сохранят старый ключ и тренд сломается. Вот почему умение получает явное одобрение перед написанием кода — отнеситесь к этому приглашению серьёзно. +- **Фиксированные данные — реальные производственные расшифровки.** Проектирование против реальных сессий означает их вытягивание на диск, и они могут содержать данные клиентов. Умение спрашивает перед коммитом в git; если сомневаетесь, держите `fixtures/` вне репозитория и попросите каждого разработчика получить своего. +- **Агент пишет и развёртывает сервис, который читает каждую расшифровку.** Он действует от вашего имени, ограниченный разрешениями вашей учетной записи CLI, но проверьте оценщик, как и любой другой код, который касается производственных данных. --- ## Следующие шаги -- **[Evaluation suite](/ru/agenteye/evaluation-suite)**: HTTP контракт, SDK и переменные окружения сервера, которые навык конфигурирует. -- **[Evaluations](/ru/agenteye/evaluations)**: где оценки показываются, когда они появляются. -- **[CLI skill](/ru/agenteye/cli-skill)**: родственный навык для чтения результатов вместо построения скорера. -- **[CLI](/ru/agenteye/cli)**: справочник команд за данными сеансов, против которых навык проектирует. \ No newline at end of file +- **[Набор инструментов оценки](/ru/agenteye/evaluation-suite)**: HTTP-контракт, SDK и переменные окружения сервера, которые настраивает умение. +- **[Оценки](/ru/agenteye/evaluations)**: где появляются оценки, когда они поступают. +- **[Умение CLI](/ru/agenteye/cli-skill)**: родственное умение для чтения результатов вместо построения скорера. +- **[CLI](/ru/agenteye/cli)**: справочник команд за данными сессии, против которых проектирует умение. \ No newline at end of file diff --git a/docs/ru/agenteye/event-stream.mdx b/docs/ru/agenteye/event-stream.mdx index 9a4d55bf..ddcf3a8e 100644 --- a/docs/ru/agenteye/event-stream.mdx +++ b/docs/ru/agenteye/event-stream.mdx @@ -1,51 +1,50 @@ --- ---- -title: "Event Stream" -description: "В момент, когда ваш агент что-то делает, вы это видите." +title: "Поток событий" +description: "Вот что происходит: вы видите это в режиме реального времени." --- -В момент, когда ваш агент что-то делает, вы это видите. Event Stream — это живой пульс каждого агента в продакшене: без ожидания, без поиска в логах, без угадывания того, что произошло. +Вот что происходит: вы видите это в режиме реального времени. Поток событий — это живой пульс каждого агента в production: без ожидания, без поиска в логах, без догадок о том, что только что произошло. -![The live Event Stream: colour-coded event rows tailing in real time, filterable by environment, agent, session, event type, and free text](/agenteye/images/events-stream.png) +![Живой Поток событий: события с цветовым кодированием, обновляющиеся в реальном времени, фильтруемые по среде, агенту, сессии, типу события и поисковому запросу](/agenteye/images/events-stream.png) -*Каждое событие от каждого агента в вашей организации, новые сверху, обновляется в реальном времени.* +*Каждое событие от каждого агента в вашей организации, новые в начале, обновляется по мере происходления.* ## Живой пульс каждого агента -Когда агент начинает запуск, вызывает модель, запускает инструмент, выполняет hook или встречает ошибку, строка появляется в верхней части потока в момент это происходит. Он отслеживает каждое событие от каждого агента в вашей организации, новые первыми, чтобы у вас всегда была актуальная картина вместо устаревшей. +Когда агент начинает выполнение, вызывает модель, запускает инструмент, выполняет hook или сталкивается с ошибкой, строка появляется в верхней части потока в тот момент, когда это происходит. Он отслеживает каждое событие от каждого агента в вашей организации, новые в начале, чтобы вы всегда имели актуальное представление вместо устаревшего. -Это означает, что вам не нужно следить за логами на каком-то сервере, не нужно искать по машинам, не нужно собирать временные метки вручную. Вы открываете одну страницу и уже смотрите продакшен. +Это означает, что нет необходимости просматривать файлы логов на каком-то сервере, искать данные на разных машинах, вручную сопоставлять временные метки. Вы открываете одну страницу — и вы уже наблюдаете production. -Строки окрашены в разные цвета по типам, поэтому вы можете читать поток с первого взгляда вместо разбора каждой строки. На первый взгляд каждая строка показывает вам: +Строки имеют цветовой код по типам, поэтому вы можете читать поток с первого взгляда вместо разбора каждой строки. На первый взгляд каждая строка показывает вам: -- **Её тип**, окрашенный в цвет: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` и другие. -- **Однострочное резюме** того, что произошло, чтобы вам редко нужно было открывать что-то только для общего понимания. -- **Количество токенов** для этого шага. -- **Значок заполнения контекстного окна** где применимо, чтобы рост промпта и приближающееся сжатие были видны до того, как они проявятся. +- **Её тип**, обозначенный цветом: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` и другие. +- **Однострочное резюме** того, что произошло, так что вам редко нужно открывать что-то только для общей информации. +- **Подсчёт токенов** для этого шага. +- **Значок заполнения контекстного окна**, где применимо, поэтому рост prompt и приближающаяся компактизация видны до того, как они создадут проблемы. -Просмотр в реальном времени означает, что вы поймёте неудачное развёртывание, зацикленный процесс или всплеск ошибок в момент их возникновения, а не при завтрашнем разборе логов. +Просмотр в реальном времени означает, что вы замечаете неудачное развёртывание, бесконечный цикл или всплеск ошибок в тот момент, когда это происходит, а не при завтрашнем обзоре логов. -## Найдите нужный запуск +## Найдите один запуск, который имеет значение -Когда что-то выглядит странно, вам нужен не весь поток событий. Вам нужен один запуск, который сломался. Поток быстро фильтруется: по окружению, по агенту, по сессии, по типу события или по свободному тексту. +Когда что-то выглядит не так, вам не нужен весь поток данных. Вам нужен единственный запуск, который вызвал проблему. Поток фильтруется быстро: по среде, по агенту, по сессии, по типу события или по поисковому запросу. -Фильтруйте по id сессии или id агента, чтобы проследить один запуск от первого события до последнего. Фильтруйте по типу события, чтобы изолировать один вид активности, например все `error` во всей организации в одном представлении. Комбинируйте фильтры, чтобы сузить от «всё везде» к «этот агент в prod с ошибками» в несколько кликов, а затем действуйте в соответствии с тем, что вы найдёте. +Фильтруйте по идентификатору сессии или идентификатору агента, чтобы следить за одним запуском от первого события до последнего. Фильтруйте по типу события, чтобы выделить один вид активности, например все `error` по всей организации в одном представлении. Комбинируйте фильтры, чтобы сузить диапазон от «всё везде» к «этот агент, в prod, с ошибками» за несколько кликов, а затем действуйте на основе найденного. -Поиск по свободному тексту приводит прямо к сообщению, имени инструмента или id, который у вас уже есть, поэтому отчёт клиента превращается в нужный запуск за секунды. +Полнотекстовый поиск ведёт прямо к сообщению, имени инструмента или идентификатору, который у вас уже есть под рукой, поэтому отчёт клиента превращается в нужный запуск за секунды. ## Где это найти -Event Stream — это ваша домашняя страница организации. Войдите, и это первая поверхность, на которую вы попадаете, по адресу `//`, поэтому классификация начинается в момент вашего прибытия. +Поток событий — это главная страница вашей организации. После входа это первая страница, на которую вы попадаете, по адресу `//`, поэтому сортировка начинается с момента вашего приезда. -За кулисами ваши агенты генерируют события через SDK, сборщик отправляет их на ваш сервер Failproof AI Observability, а поток отслеживает их по мере поступления в управляемую вами инфраструктуру. Когда вы хотите сводное представление вместо необработанного следа, события каждого запуска сворачиваются в одну строку на Sessions, в один клик. +За кулисами ваши агенты генерируют события через SDK, сборщик отправляет их на ваш сервер Failproof AI Observability, и поток отслеживает их по мере поступления в управляемую вами инфраструктуру. Когда вам нужна сводная информация вместо необработанного следа, события каждого запуска сворачиваются в одну строку на Sessions, одного клика от вас. -Это основной источник истины, на котором строятся все остальные поверхности наблюдения, поэтому когда где-то числа выглядят неправильно, поток — это место, где вы подтверждаете, что на самом деле произошло. +Это необработанный источник истины, на котором построены все остальные поверхности наблюдения, поэтому когда число выглядит неправильно где-то ещё, поток — это место, где вы подтверждаете, что на самом деле произошло. -## Связанные материалы +## Связанные темы -- [Sessions](/ru/agenteye/sessions): те же события, объединённые в одну строку за запуск, с графиком выполнения в стиле git. -- [Telemetry](/ru/agenteye/telemetry): что отправляют ваши агенты и как события попадают в поток. -- [Error tracking](/ru/agenteye/error-tracking): единая поверхность классификации для всего, что пошло не так. -- [Alerts](/ru/agenteye/alerts): превратите любой порог в правило уведомления. -- [CLI and agents](/ru/agenteye/cli-and-agents): тот же живой след прямо из вашего терминала. \ No newline at end of file +- [Sessions](/ru/agenteye/sessions): те же события, свёрнутые в одну строку за запуск, с графиком выполнения в стиле git. +- [Telemetry](/ru/agenteye/telemetry): что отправляют ваши агенты и как события достигают потока. +- [Error tracking](/ru/agenteye/error-tracking): единая поверхность сортировки для всего, что пошло не так. +- [Alerts](/ru/agenteye/alerts): превратите любой порог в правило оповещения. +- [CLI and agents](/ru/agenteye/cli-and-agents): тот же живой след из вашего терминала. \ No newline at end of file diff --git a/docs/ru/agenteye/hermes-capture.mdx b/docs/ru/agenteye/hermes-capture.mdx index 6a63a423..bf7d7b00 100644 --- a/docs/ru/agenteye/hermes-capture.mdx +++ b/docs/ru/agenteye/hermes-capture.mdx @@ -1,53 +1,53 @@ --- -title: "Захват сессий Hermes" -description: "Переносите сессии Hermes gateway вашей команды — Slack, Telegram, CLI и запланированные запуски — в AgentEye как обычные сессии и события." +title: "Capture сеансов Hermes" +description: "Привнесите сеансы шлюза Hermes вашей команды — Slack, Telegram, CLI и запланированные запуски — в AgentEye как обычные сеансы и события." --- -[Hermes](https://hermes-agent.nousresearch.com) отвечает вашей команде из любого места, где она уже работает — Slack, Telegram, CLI, запланированные запуски. Захват сессий Hermes переносит всё это в AgentEye как обычные сессии и события, поэтому помощник, с которым ваша команда общается каждый день, становится таким же наблюдаемым, как агенты, которых вы пишете сами. +[Hermes](https://hermes-agent.nousresearch.com) отвечает вашей команде там, где она уже работает — Slack, Telegram, CLI, запланированные запуски. Capture сеансов Hermes собирает всё это в AgentEye как обычные сеансы и события, так что помощник, с которым ваша команда разговаривает каждый день, так же наблюдаем, как агенты, которых вы пишете сами. -Небольшой фоновый сборщик читает локальное хранилище сессий Hermes по мере его обновления и отправляет сессии в AgentEye. Он работает так же, как захват [Codex](/ru/agenteye/codex-capture) и [OpenClaw](/ru/agenteye/openclaw-capture), и один сборщик может одновременно захватывать несколько сессий. +Небольшой фоновый сборщик читает локальное хранилище сеансов Hermes по мере его записи и отправляет сеансы в AgentEye. Это работает так же, как capture [Codex](/ru/agenteye/codex-capture) и [OpenClaw](/ru/agenteye/openclaw-capture), и один сборщик может одновременно захватывать несколько агентов. --- -## Что захватывается +## Что именно захватывается -Каждая сессия Hermes на машине захватывается, независимо от канала, с которого она пришла. Каждая становится [сессией](/ru/agenteye/sessions) AgentEye; её сообщения пользователя и ассистента, вызовы инструментов и результаты инструментов становятся соответствующими [событиями](/ru/agenteye/event-stream). +Каждый сеанс Hermes на машине захватывается, независимо от того, из какого канала он поступил. Каждый становится [сеансом](/ru/agenteye/sessions) AgentEye; сообщения пользователя и помощника, вызовы инструментов и результаты инструментов становятся соответствующими [событиями](/ru/agenteye/event-stream). -Канал, с которого началась сессия — Slack, Telegram, CLI или запланированный запуск — записывается в сессию, поэтому вы можете их различить и фильтровать по одному. Вместе с этим фиксируются модель, на которой выполнялась сессия, чат и человек, от которого она была запущена, и, когда сессия порождала другую, ссылка на родительскую сессию. +Канал, из которого был запущен сеанс — Slack, Telegram, CLI или запланированный запуск — записывается в сеансе, так что вы можете их различать и фильтровать по одному. Рядом с ним указываются модель, на которой работал сеанс, чат и человек, который его запустил, и, когда сеанс породил другой, связь обратно к родительскому. -Сессии появляются сразу же, когда Hermes их запускает, независимо от того, что-то ли в них было написано или нет, и ответ хода и его вызовы инструментов остаются в порядке, в котором они фактически произошли. Когда сессия завершается, вы также получаете причину завершения, её стоимость и количество использованных токенов. +Сеансы появляются сразу же, как только Hermes их начинает, независимо от того, было ли что-то сказано или нет, и ответ хода и его вызовы инструментов остаются в порядке, в котором они на самом деле произошли. Когда сеанс заканчивается, вы также получаете причину завершения, его стоимость и количество использованных токенов. --- -## Включение +## Включите capture -Захват отключен по умолчанию. Установите сборщик с API ключом, который имеет разрешение `events:add` (см. [API ключи](/ru/agenteye/api-keys)), и включите захват Hermes: +Capture отключён до тех пор, пока вы его не включите. Установите сборщик с API-ключом, имеющим разрешение `events:add` (см. [API keys](/ru/agenteye/api-keys)), и включите capture Hermes: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -Это установит сборщик, зарегистрирует его как фоновый сервис и начнёт захват. Убедитесь, что он работает: +Это устанавливает сборщик, регистрирует его как фоновую службу и начинает захват. Убедитесь, что он работает: ```bash agenteye-collector health ``` -Захватываете более одного агента на одной машине? Добавьте флаг каждого к одной команде — например `--hermes-enabled --codex-enabled`. +Захватываете более одного агента на одной машине? Добавьте флаг каждого к той же команде — например `--hermes-enabled --codex-enabled`. -При первом запуске ваши существующие сессии Hermes заполняются один раз, а новая активность затем потоком поступает в течение нескольких секунд. Данные самого Hermes только читаются — никогда не изменяются и не удаляются — и каждое сообщение отправляется один раз, даже при перезагрузках. +При первом запуске ваши существующие сеансы Hermes заполняются один раз, а новая активность затем передаётся в течение нескольких секунд. Данные самого Hermes только читаются — никогда не изменяются и не удаляются — и каждое сообщение отправляется один раз, даже при перезапусках. -`health` также показывает, всё ли, что сборщик захватил, фактически достигло AgentEye. Если пакет не удалось доставить, он сохраняется и повторяется попытка, а не отбрасывается, и проверка сообщает о неполадках, пока что-то ещё ожидает обработки — поэтому "healthy" означает, что ваши данные прибыли, а не просто что процесс живой. +`health` также говорит вам, действительно ли всё, что захватил сборщик, дошло до AgentEye. Если пакет не был доставлен, он сохраняется и повторяется, а не отбрасывается, и проверка сообщает о нездоровом состоянии, пока что-то ещё не выполнено — так что «healthy» означает, что ваши данные пришли, а не просто то, что процесс жив. --- ## Где это отображается -Захваченные сессии появляются в разделе **Sessions**, а их события в потоке **Events**, так же как любой другой наблюдаемый вами агент — поэтому [воспроизведение сессии](/ru/agenteye/sessions), [поиск](/ru/agenteye/queries), [оценки](/ru/agenteye/evaluations) и [оповещения](/ru/agenteye/alerts) работают на них. Отфильтруйте по агенту Hermes, чтобы видеть их отдельно. +Захваченные сеансы появляются в разделе **Sessions**, их события в потоке **Events**, так же как и любой другой наблюдаемый агент — поэтому [session replay](/ru/agenteye/sessions), [поиск](/ru/agenteye/queries), [evaluations](/ru/agenteye/evaluations) и [alerts](/ru/agenteye/alerts) все работают с ними. Фильтруйте по агенту Hermes, чтобы увидеть их отдельно. --- ## Конфиденциальность -Сессии Hermes содержат полный транскрипт — включая вывод команд, содержимое файлов и всё, что агент читал или писал — и могут содержать секреты. Захваченные сессии отправляются как есть, поэтому включайте захват только там, где централизация этого содержимого в AgentEye уместна, и выдайте сборщику ключ, ограниченный только разрешением `events:add`. См. [Безопасность](/ru/agenteye/security), чтобы узнать, как ваши данные хранятся отдельно. \ No newline at end of file +Сеансы Hermes содержат полный транскрипт — включая выходные данные команд, содержимое файлов и всё, что агент читал или писал — и могут содержать секреты. Захваченные сеансы отправляются как есть, поэтому включайте capture только там, где централизация этого содержимого в AgentEye уместна, и дайте сборщику ключ с областью действия только `events:add`. См. [Security](/ru/agenteye/security) о том, как ваши данные остаются изолированными. \ No newline at end of file diff --git a/docs/ru/agenteye/incidents.mdx b/docs/ru/agenteye/incidents.mdx index c7d2b710..24ea846f 100644 --- a/docs/ru/agenteye/incidents.mdx +++ b/docs/ru/agenteye/incidents.mdx @@ -1,28 +1,28 @@ --- title: "Инциденты" -description: "Когда срабатывает оповещение, все видят, что инцидент открыт, кто за него отвечает и что произошло — в одной упорядоченной временной шкале." +description: "Когда срабатывает алерт, все видят, что инцидент открыт, кто за него отвечает и что произошло — на одной атрибутированной шкале времени." --- -Когда срабатывает оповещение, первый вопрос всегда один: «кто этим займётся?» Инциденты отвечают на него: в момент обнаружения нарушения все видят, что инцидент открыт, кто за него отвечает и ровно что произошло, с чистой и упорядоченной записью, которую можно сразу передать на анализ после инцидента. +Когда срабатывает алерт, первый вопрос всегда один: "кто за это отвечает?" Инциденты дают ответ: в момент нарушения все видят, что инцидент открыт, кто его берёт на себя и ровно что произошло, с чистой, атрибутированной записью, которую можно сразу отправить на post-mortem. -![Входящие инциденты: карточки инцидентов, связанные с оповещениями и открытые вручную, сгруппированные по статусу, каждая с значком серьёзности и назначенным ответственным](/agenteye/images/incidents.png) -*Входящие группируют открытые инциденты по статусу и фильтруют по серьёзности и ответственному, чтобы вы видели, что требует внимания человека прямо сейчас.* +![Входящие инциденты: карточки инцидентов, связанные с алертами и открытые вручную, сгруппированные по статусу, каждая с бейджем серьёзности и назначенным оператором](/agenteye/images/incidents.png) +*Входящие группируют открытые инциденты по статусу и фильтруют по серьёзности и назначенному оператору, так что вы видите, что требует внимания прямо сейчас.* -## Сразу видно, кто этим занимается +## Сразу видите, кто за это отвечает -Больше не нужно спрашивать «кто-нибудь это смотрит?» в чате. Нарушение автоматически открывает инцидент и помещает его в общую входящую папку, сгруппированную по статусам. Подтвердите его — и ваше имя будет на нём, так команда узнает, что это берётся в работу. Подтверждение общее: несколько операторов могут подтвердить один инцидент, и каждое подтверждение записывается отдельно, так что полный боевой штаб видно по именам без перепутанности. Назначьте одного ответственного за первичный анализ и фильтруйте входящие по серьёзности или ответственному, чтобы видеть только то, что вам нужно. +Больше не нужно спрашивать "кто-нибудь смотрит на это?" в чате. Нарушение автоматически открывает инцидент и кладёт его в общую входящую, отсортированную по статусу. Подтвердите его — и ваше имя на нём, так что остальная команда видит, что это под контролем. Подтверждение общее: несколько операторов могут подтвердить один инцидент, и каждое подтверждение записывается отдельно, так что весь боевой коллектив виден по именам вместо того, чтобы друг другу мешать. Назначьте одного владельца для сортировки, и фильтруйте входящие по серьёзности или назначенному оператору, чтобы оставить только нужное. -## Вся история в одной шкале времени +## Вся история на одной шкале времени -Когда инцидент завершён, у вас уже есть описание. Откройте любой инцидент — и вы увидите свидетельства нарушения, его ответственных и подписчиков, цепочку комментариев для координации и неизменяемую временную шкалу активности. +Когда инцидент закрыт, протокол уже готов. Откройте любой инцидент — получите доказательства нарушения, назначенных операторов и подписчиков, ветку комментариев для координации на месте и добавляемую-только-в-конец шкалу времени активности. -![Детальный вид инцидента: родительское оповещение и краткое описание нарушения, ответственные и подписчики, упорядоченная по времени временная шкала активности и цепочка комментариев](/agenteye/images/incident-detail.png) -*Все события, по порядку, каждая строка подписана тем, кто её создал.* +![Представление детали инцидента: родительский алерт и краткое резюме нарушения, назначенные операторы и подписчики, атрибутированная шкала времени активности, и ветка комментариев](/agenteye/images/incident-detail.png) +*Всё, что произошло, по порядку, каждая строка подписана тем, кто это сделал.* -Каждое действие (открыто, подтверждено, разрешено и так далее) записывается в эту временную шкалу и никогда не изменяется. Каждая запись имеет автора: оператора, который её выполнил, с указанием почты, или **automated** для всего, что Failproof AI Observability сделал самостоятельно, например открыл инцидент при обнаружении нарушения. Ничего не анонимно и ничего не теряется, так что анализ после инцидента практически пишется сам по себе. +Каждое действие (открыто, подтверждено, разрешено и так далее) записывается на эту шкалу и никогда не редактируется. Каждая запись атрибутирована: оператору, который это сделал, по email, или **automated** для всего, что Failproof AI Observability сделал само, например открыло инцидент на нарушении. Ничего анонимного и ничего потеряного, так что post-mortem более или менее пишет сам себя. -## Как инцидент развивается +## Как инцидент переходит между статусами ```mermaid stateDiagram-v2 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **Открыт (firing):** нарушение открывает инцидент и пингует ваши каналы один раз. Повторные нарушения объединяются в один инцидент и обновляют его свидетельства вместо повторных пингов. -- **Подтверждён (acknowledged):** оператор взял его в работу. Он остаётся открытым, и позже нарушения тихо обновляют свидетельства. -- **Разрешён (resolved):** оператор закрывает его. Автоматическое разрешение при исчезновении условия планируется, но ещё не включено, поэтому инцидент остаётся открытым до ручного разрешения оператором, что держит всех в курсе о том, что действительно решено. Новый инцидент может открыться по тому же оповещению позже. +- **Open (firing):** нарушение открывает инцидент и пейджирует ваши каналы один раз. Повторные нарушения складываются в один инцидент и обновляют его доказательства вместо того, чтобы пейджировать вас снова и снова. +- **Acknowledged:** оператор его берёт. Он остаётся открыт, и позже нарушения тихо обновляют доказательства. +- **Resolved:** оператор его закрывает. Автоматическое разрешение, когда условие исчезает, планируется, но пока не включено, так что инцидент остаётся открыт до тех пор, пока человек его не разрешит, что держит всех честными относительно того, что действительно разрешилось. Новый инцидент может открыться по тому же алерту позже. -Одно оповещение может иметь максимум один открытый инцидент одновременно, так что нестабильное правило не закидает вас дубликатами. Вы также можете открыть инцидент вручную: самостоятельный для чего-то, что не поймало ни одно оповещение, или привязанный к существующему оповещению, если у вас есть `incidents:write`. +Один алерт держит максимум один открытый инцидент в единый момент времени, так что мерцающее правило не может вас похоронить в дубликатах. Вы также можете открыть инцидент вручную: автономный для чего-то, что не поймал ни один алерт, или связанный с существующим алертом, если у вас есть `incidents:write`. -## Где его найти +## Где это найти -Инциденты находятся по адресу `//incidents`. Просмотр требует **`incidents:read`**; открытие ручного инцидента требует **`incidents:write`**; подтверждение, назначение, комментирование и разрешение требуют **`incidents:ack`**. Старые ключи, которым был дан снятый с производства `alerts:ack`, продолжают работать, так как он признаётся как `incidents:ack`, поэтому вашу ротацию дежурных не нужно переиздавать. +Инциденты находятся по адресу `//incidents`. Просмотр требует **`incidents:read`**; открытие ручного инцидента требует **`incidents:write`**; подтверждение, назначение, комментирование и разрешение требуют **`incidents:ack`**. Старые ключи, получившие снятый с производства `alerts:ack`, продолжают работать, так как он почитается как `incidents:ack`, так что вашу дежурную смену не нужно переиздавать. ## Связанное -- [Оповещения](/ru/agenteye/alerts): правила, которые открывают эти инциденты при нарушении порога. -- [Отслеживание ошибок](/ru/agenteye/error-tracking): смотрите все сбои в одном месте и повысьте один до оповещения. -- [Аудиты](/ru/agenteye/audits): запланированный аналитик, который находит сбои, за которыми не наблюдало ни одно правило. \ No newline at end of file +- [Alerts](/ru/agenteye/alerts): правила, которые открывают эти инциденты, когда порог нарушается. +- [Error tracking](/ru/agenteye/error-tracking): смотрите каждый отказ в одном месте и повысьте один до алерта. +- [Audits](/ru/agenteye/audits): запланированный аналитик, который находит отказы, за которыми ни одно правило не смотрело. \ No newline at end of file diff --git a/docs/ru/agenteye/observability.mdx b/docs/ru/agenteye/observability.mdx index acc5b7fd..5ef13478 100644 --- a/docs/ru/agenteye/observability.mdx +++ b/docs/ru/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- -title: "Observe" -description: "Surfaces наблюдения — это место, где вы видите, что делают ваши агенты прямо сейчас и анализируете любой отдельный запуск." +title: "Наблюдение" +description: "Поверхности наблюдения позволяют отслеживать, что делают ваши агенты прямо сейчас, и анализировать любой отдельный запуск." --- -Surfaces наблюдения — это место, где вы видите, что делают ваши агенты прямо сейчас и анализируете любой отдельный запуск. Все данные здесь поступают в реальном времени, ограничены областью вашей организации и отфильтрованы по диапазону дат, окружению, агенту и сеансу, поэтому вы переходите от «что-то не так» к точному запуску за секунды. +Поверхности наблюдения позволяют отслеживать, что делают ваши агенты прямо сейчас, и анализировать любой отдельный запуск. Все данные здесь поступают в реальном времени, ограничены вашей организацией и могут быть отфильтрованы по диапазону дат, окружению, агенту и сессии — так вы переходите от "что-то не так" к нужному запуску за секунды. -![Live Event Stream с цветовой кодировкой по типам и фильтрацией по окружению, агенту и сеансу](/agenteye/images/events-stream.png) +![Живой поток событий, раскрашенный по типам и фильтруемый по окружению, агенту и сессии](/agenteye/images/events-stream.png) -Четыре surface, каждый со своей страницей: +Четыре поверхности, каждая со своей страницей: -- **[Event stream](/ru/agenteye/event-stream)**: live хронология каждого шага каждого запуска на всех агентах, новейшие сначала. Главная страница вашей организации и первая остановка для триажа. -- **[Sessions and execution graph](/ru/agenteye/sessions)**: эти события свернуты в одну строку на запуск плюс картина в стиле git того, как каждый запуск развивался. -- **[Performance metrics](/ru/agenteye/telemetry)**: heat-maps задержки и p50/p95/p99 показатели для ваших моделей, инструментов и hooks, чтобы всплески на хвосте отличались от медианы. -- **[Error tracking](/ru/agenteye/error-tracking)**: единый surface триажа для всего, что пошло не так, одним кликом от срабатывающего оповещения к запуску, который сломался. +- **[Поток событий](/ru/agenteye/event-stream)**: живой, пошаговый журнал каждого запуска для каждого агента, новые в начале. Домашняя страница вашей организации и первая остановка для триажа. +- **[Сессии и граф выполнения](/ru/agenteye/sessions)**: события, собранные в одну строку на запуск, плюс граф в стиле git, показывающий, как развивался каждый запуск. +- **[Метрики производительности](/ru/agenteye/telemetry)**: тепловые карты задержек и жизненно важные показатели p50/p95/p99 для ваших моделей, инструментов и хуков, чтобы скачки на хвосте выделялись на фоне медианы. +- **[Отслеживание ошибок](/ru/agenteye/error-tracking)**: единая поверхность триажа для всего, что пошло не так, один клик от сработавшего алерта до запуска, который сломался. ## Связанное -- [Evaluations](/ru/agenteye/evaluations): оценка каждого запуска по качеству. -- [Alerts](/ru/agenteye/alerts): превратите любой порог в правило повызова. -- [Audits](/ru/agenteye/audits): позвольте Failproof AI Observability найти для вас закономерности отказов во всех сеансах. -- [CLI and agents](/ru/agenteye/cli-and-agents): та же наблюдаемость из вашего терминала. \ No newline at end of file +- [Оценки](/ru/agenteye/evaluations): оцените каждый запуск по качеству. +- [Алерты](/ru/agenteye/alerts): превратите любой порог в правило для оповещения. +- [Аудиты](/ru/agenteye/audits): позвольте Failproof AI Observability найти закономерности сбоев в сессиях для вас. +- [CLI и агенты](/ru/agenteye/cli-and-agents): то же наблюдение из вашего терминала. \ No newline at end of file diff --git a/docs/ru/agenteye/openclaw-capture.mdx b/docs/ru/agenteye/openclaw-capture.mdx index 4604477a..a52c9695 100644 --- a/docs/ru/agenteye/openclaw-capture.mdx +++ b/docs/ru/agenteye/openclaw-capture.mdx @@ -1,49 +1,49 @@ --- -title: "Захват сеансов OpenClaw" -description: "Собирайте локальные сеансы OpenClaw вашей команды в AgentEye как обычные сеансы и события — без изменения способа работы OpenClaw." +title: "Захват сессий OpenClaw" +description: "Отправляйте локальные сессии OpenClaw вашей команды в AgentEye как обычные сессии и события — без каких-либо изменений в работе OpenClaw." --- -Если ваша команда использует [OpenClaw](https://docs.openclaw.ai), захват сеансов OpenClaw переносит эти сеансы в AgentEye как обычные сеансы и события, так что вы можете искать, воспроизводить и оценивать их наряду со всем остальным, что вы наблюдаете. Это дополнение к [Python SDK](/ru/agenteye/python-sdk): SDK инструментирует агентов, которых вы пишете, а захват собирает работу OpenClaw, которую ваша команда уже выполняет — без каких-либо изменений в способе её запуска. +Если ваша команда использует [OpenClaw](https://docs.openclaw.ai), захват сессий OpenClaw доставляет эти сессии в AgentEye как обычные сессии и события, так что вы можете искать, воспроизводить и оценивать их наряду со всем остальным, что вы наблюдаете. Он дополняет [Python SDK](/ru/agenteye/python-sdk): SDK инструментирует агентов, которых вы пишете, а этот сервис захватывает работу OpenClaw, которую ваша команда уже выполняет — без каких-либо изменений в том, как они его используют. -Небольшой фоновый сборщик читает локальные расшифровки сеансов OpenClaw по мере их записи и отправляет их в AgentEye. Он работает так же, как [захват Codex](/ru/agenteye/codex-capture), и один сборщик может захватывать оба одновременно. +Небольшой фоновый сборщик читает локальные транскрипты сессий OpenClaw по мере их записи и отправляет их в AgentEye. Это работает так же, как [захват Codex](/ru/agenteye/codex-capture), и один сборщик может одновременно захватывать оба. --- ## Что захватывается -Каждый агент, настроенный в локальной установке OpenClaw машины, захватывается сборщиком этой машины — не требуется настройка для каждого агента отдельно. +Каждый агент, настроенный в установке OpenClaw на машине, захватывается сборщиком этой машины — не требуется настройка для каждого агента. -Каждый сеанс OpenClaw становится [сеансом](/ru/agenteye/sessions) AgentEye; его сообщения пользователя и ассистента, вызовы инструментов и результаты инструментов становятся соответствующими [событиями](/ru/agenteye/event-stream). +Каждая сессия OpenClaw становится [сессией](/ru/agenteye/sessions) AgentEye; её сообщения пользователя и ассистента, вызовы инструментов и результаты инструментов становятся соответствующими [событиями](/ru/agenteye/event-stream). --- ## Включение захвата -Захват отключен до тех пор, пока вы его не включите. Установите сборщик с API ключом, имеющим разрешение `events:add` (см. [API ключи](/ru/agenteye/api-keys)), и включите захват OpenClaw: +Захват отключён по умолчанию. Установите сборщик с API-ключом, имеющим разрешение `events:add` (см. [API-ключи](/ru/agenteye/api-keys)), и включите захват OpenClaw: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -Это установит сборщик, зарегистрирует его как фоновый сервис и начнёт захват. Убедитесь, что он запущен: +Это установит сборщик, зарегистрирует его как фоновый сервис и начнёт захват. Убедитесь, что он работает: ```bash agenteye-collector health ``` -Захватываете более одного агента на одной машине? Добавьте флаг каждого в одну команду — например `--openclaw-enabled --codex-enabled`. +Захватываете более одного агента на одной машине? Добавьте флаг каждого к одной команде — например `--openclaw-enabled --codex-enabled`. -При первом запуске ваши существующие сеансы OpenClaw будут загружены задним числом один раз, а новая активность будет поступать в течение нескольких секунд. Файлы OpenClaw только читаются — никогда не изменяются, не перемещаются и не удаляются — и каждый сеанс отправляется ровно один раз, даже при перезагрузках. +При первом запуске ваши существующие сессии OpenClaw будут загружены один раз, а затем новая активность будет поступать в течение нескольких секунд. Файлы OpenClaw никогда не будут изменены, перемещены или удалены — и каждая сессия будет отправлена ровно один раз, даже при перезагрузках. --- -## Где это появляется +## Где это отображается -Захваченные сеансы появляются в **Sessions**, а их события в потоке **Events**, так же как любой другой наблюдаемый агент — поэтому [воспроизведение сеансов](/ru/agenteye/sessions), [поиск](/ru/agenteye/queries), [оценки](/ru/agenteye/evaluations) и [оповещения](/ru/agenteye/alerts) работают на них. Отфильтруйте по агенту OpenClaw, чтобы увидеть их отдельно. +Захваченные сессии появляются в **Sessions**, а их события в потоке **Events**, как и любой другой наблюдаемый вами агент — поэтому [воспроизведение сессий](/ru/agenteye/sessions), [поиск](/ru/agenteye/queries), [оценки](/ru/agenteye/evaluations) и [оповещения](/ru/agenteye/alerts) работают на них. Отфильтруйте по агенту OpenClaw, чтобы увидеть их отдельно. --- -## Приватность +## Конфиденциальность -Расшифровки OpenClaw содержат полный сеанс — включая выходные данные команд, содержимое файлов и всё, что агент прочитал или написал — и могут содержать секреты. Захваченные сеансы отправляются как есть, поэтому включайте захват только на машинах и для команд, где централизация этого контента в AgentEye уместна, и выдайте сборщику ключ с областью действия только `events:add`. См. [Security](/ru/agenteye/security) для информации о том, как ваши данные остаются изолированными. \ No newline at end of file +Транскрипты OpenClaw содержат полную сессию — включая вывод команд, содержимое файлов и всё, что прочитал или записал агент — и могут содержать секреты. Захваченные сессии отправляются в исходном виде, поэтому включайте захват только на машинах и для команд, где централизация этого содержимого в AgentEye уместна, и выдайте сборщику ключ с областью действия только `events:add`. See [Security](/ru/agenteye/security) для получения информации о том, как ваши данные остаются изолированными. \ No newline at end of file diff --git a/docs/ru/agenteye/overview.mdx b/docs/ru/agenteye/overview.mdx index 8f42c045..fa5d57a1 100644 --- a/docs/ru/agenteye/overview.mdx +++ b/docs/ru/agenteye/overview.mdx @@ -1,107 +1,108 @@ --- -title: "Failproof AI: Наблюдение за отказами агентов" -description: "Failproof AI Observability — это самостоятельно размещаемая платформа для наблюдения, оценки и улучшения ваших AI-агентов в продакшене." +title: "Failproof AI: наблюдение за агентами для выявления ошибок" +description: "Failproof AI Observability — это самостоятельно размещаемая платформа для наблюдения, оценки и улучшения ваших AI-агентов в production." --- -Failproof AI Observability — это самостоятельно размещаемая платформа для наблюдения, оценки и улучшения ваших AI-агентов в продакшене. Она фиксирует всё, что делают ваши агенты (каждый вызов инструмента, запрос к модели, hook и ошибку), оценивает качество каждого запуска и выявляет сбои, на которые вы не смотрели, всё это в панели управления, работающей в вашей инфраструктуре. -Если вы развёртываете AI-агентов и устали гадать, почему запуск пошёл не так, эта страница — ваша отправная точка. Здесь объясняется, что вам даёт Failproof AI Observability и как всё взаимодействует, прежде чем вы что-то устанавливать. +Failproof AI Observability — это самостоятельно размещаемая платформа для наблюдения, оценки и улучшения ваших AI-агентов в production. Она записывает все действия ваших агентов (каждый вызов инструмента, запрос к модели, хук и ошибку), оценивает качество каждого запуска и выявляет сбои, о которых вы даже не знали, все это в панели управления, работающей в вашей собственной инфраструктуре. -> **Failproof AI Observability — это корпоративный продукт компании Failproof AI.** Хотите увидеть его в действии? Запросите демонстрацию: напишите на [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Если вы развертываете AI-агентов и устали гадать, почему запуск прошел неправильно, это правильная страница для начала. Она объясняет, что вам дает Failproof AI Observability и как все части работают вместе, прежде чем вы что-либо устанавливаете. -![Сеанс Failproof AI Observability, изображённый в виде графа выполнения в стиле git рядом с временной шкалой событий, с разбивкой каждого запуска на инструменты, модели и hooks в правой панели](/agenteye/images/session-detail.png) +> **Failproof AI Observability — это корпоративный продукт от Failproof AI.** Хотите увидеть его в действии? Запросите демонстрацию: отправьте письмо на [nikita@befailproof.ai](mailto:nikita@befailproof.ai). -*Каждый запуск агента отображается в виде графа выполнения в стиле git (слева) рядом с его временной шкалой событий. Параллельные под-агенты получают свою полосу; в правой панели показаны инструменты, модели, hooks и расход токенов для запуска.* +![Сессия Failproof AI Observability, изображенная в виде графика выполнения в стиле git рядом с временной шкалой событий, с разбивкой по запускам инструментов, моделей и хуков в правой панели](/agenteye/images/session-detail.png) + +*Каждый запуск агента отображается в виде графика выполнения в стиле git (слева) рядом с его временной шкалой событий. Параллельные подагенты получают свою собственную полосу; правая панель показывает инструменты, модели, хуки и расход токенов для запуска.* --- ## Посмотрите в действии -Два коротких видео показывают две вещи, на которые команды обращают внимание в первую очередь: трассировка запуска и автоматический поиск сбоев. +Два коротких видео демонстрируют две вещи, к которым команды обращаются в первую очередь: отслеживание запуска и автоматическое обнаружение ошибок.
-*Трассировка агента: следите за одним запуском шаг за шагом, от цели к инструментам и финальному ответу.* +*Отслеживание агента: следите за одним запуском шаг за шагом, от цели до инструментов до финального ответа.*
-*Failproof Audit: позвольте Failproof AI Observability проанализировать ваши логи во всех сеансах и показать, что нужно исправить.* +*Failproof Audit: позвольте Failproof AI Observability анализировать ваши логи во всех сессиях и рассказать вам, что нужно исправить.* --- -## Почему команды её используют +## Почему команды используют это -- **Узнайте, что действительно делал ваш агент.** Каждый запуск становится читаемым графом выполнения в стиле git: какие инструменты работали параллельно, какие под-агенты ветвились, где он зависал и что стоило. -- **Автоматически ловите падение качества.** Подключите небольшой сервис оценки, и Failproof AI Observability оценит каждый завершённый запуск, чтобы падение полезности или всплеск галлюцинаций стали очевидны. -- **Найдите сбои, для которых вы не написали правила.** Повторяющиеся аудиты анализируют ваши логи во всех сеансах в поиске кластеров ошибок, выбросов латентности, низких оценок и зависаний, а затем выдают вам ранжированные, подтвёрённые результаты. -- **Получайте уведомления, когда это важно.** Правила по порогам срабатывают на основе частоты ошибок, латентности, стоимости или оценок оценивателя и открывают инциденты, которые вы можете подтвердить, назначить и разрешить. -- **Задавайте вопросы на обычном английском.** AI-ассистент в панели управления ответит на вопросы вроде «как качество развивается в продакшене на этой неделе?» по вашим данным. Любое изменение требует одобрения. -- **Держите ваши данные под контролем.** Failproof AI Observability является самостоятельно размещаемым: события, промпты и аналитика остаются в инфраструктуре, которую вы контролируете. +- **Посмотрите, что ваш агент на самом деле сделал.** Каждый запуск становится читаемым графиком выполнения в стиле git: какие инструменты работали параллельно, какие подагенты ветвились, где он зависал и какие ресурсы потребил. +- **Автоматически ловите регрессии качества.** Подключите небольшой сервис оценки, и Failproof AI Observability оценит каждый завершенный запуск, так что снижение полезности или всплеск галлюцинаций появятся сами по себе. +- **Найдите сбои, для которых вы не написали правило.** Периодические аудиты анализируют ваши логи во всех сессиях на предмет кластеров ошибок, выбросов задержек, низких оценок и зависших запусков, а затем предоставляют вам ранжированные, обоснованные результаты. +- **Получайте уведомления, когда это важно.** Правила порога срабатывают по частоте ошибок, задержке, стоимости или оценкам оценивателя и открывают инциденты, которые вы можете подтвердить, назначить и разрешить. +- **Задавайте вопросы на обычном английском языке.** Ассистент AI на панели управления ответит на вопрос типа "как меняется качество в prod на этой неделе?" на основе ваших данных. Любое изменение, которое он сделает, требует одобрения. +- **Сохраняйте ваши данные.** Failproof AI Observability самостоятельно размещается: события, промпты и аналитика остаются в инфраструктуре, которой вы управляете. --- ## Что вы получаете -Failproof AI Observability организована вокруг трёх концепций (**observe**, **analyze** и **admin**), отражённых в левой боковой панели панели управления. +Failproof AI Observability организована вокруг трех идей (**наблюдение**, **анализ** и **администрирование**), отраженных в левой боковой панели панели управления. -**Observe** (сырая правда о том, что произошло): +**Наблюдение** (истинная картина того, что произошло): -- **[Поток событий](/ru/agenteye/event-stream)**: живая, пошаговая цепь всех запусков (вызовы инструментов, вызовы моделей, hooks, ошибки). -- **[Сеансы](/ru/agenteye/sessions)**: эти события сведены в одну строку на запуск, каждый готов к оценке, с графом выполнения в стиле git. -- **[Метрики производительности](/ru/agenteye/telemetry)**: тепловые карты латентности для каждой поверхности и жизненно важные показатели p50/p95/p99 для моделей, инструментов и hooks, чтобы всплеск на хвосте выделялся из медианы. -- **[Отслеживание ошибок](/ru/agenteye/error-tracking)**: единая поверхность для триажа всего, что пошло не так, в один клик от срабатывающего предупреждения. +- **[Поток событий](/ru/agenteye/event-stream)**: живой трейл каждого запуска в разбивке по шагам (вызовы инструментов, вызовы моделей, хуки, ошибки). +- **[Сессии](/ru/agenteye/sessions)**: эти события объединены в одну строку на запуск, каждая готова к оценке, с графиком выполнения в стиле git. +- **[Метрики производительности](/ru/agenteye/telemetry)**: тепловые карты задержек на уровне поверхности и значения p50/p95/p99 для моделей, инструментов и хуков, чтобы всплеск в хвосте был виден отдельно от медианы. +- **[Отслеживание ошибок](/ru/agenteye/error-tracking)**: единая поверхность тriage для всего, что пошло не так, с одного щелчка от сработавшего оповещения. -![Страница инструментов в Observe: тепловая карта латентности, полоса перцентилей и диаграмма распределения инструментов более 24 временных бинов](/agenteye/images/tools.png) +![Страница наблюдения за инструментами Failproof AI: тепловая карта задержек, полоса процентилей и столбец распределения инструментов по 24 временным интервалам](/agenteye/images/tools.png) -*Каждая поверхность наблюдения объединяет искромётную линию и жизненно важные показатели p50/p95/p99 с тепловой картой латентности и полосой перцентилей. Показано здесь: инструменты.* +*Каждая поверхность наблюдения объединяет спарклайн и значения p50/p95/p99 с тепловой картой задержек и полосой процентилей. Показано здесь: инструменты.* -**Analyze** (преобразуйте активность в ответы): +**Анализ** (преобразование активности в ответы): -- **[Запросы](/ru/agenteye/queries)** и **[панели управления](/ru/agenteye/dashboards)**: сохранённый SQL по вашим событиям и оценкам, представленный в виде общих, ориентированных на организацию панелей управления. -- **[Оценки](/ru/agenteye/evaluations)**: оценки качества, полученные от вашего собственного сервиса оценивателя, с рассуждением для каждой оценки. -- **[Аудиты](/ru/agenteye/audits)**: повторяющиеся исследования, выявляющие закономерности сбоев во всех сеансах. -- **[Предупреждения](/ru/agenteye/alerts)** и **[инциденты](/ru/agenteye/incidents)**: правила по порогам, которые вызывают уведомления, плюс рабочий процесс инцидентов для их триажа. +- **[Запросы](/ru/agenteye/queries)** и **[панели управления](/ru/agenteye/dashboards)**: сохраненный SQL над вашими событиями и оценками, отображаемый в виде общих, ограниченных по организации панелей управления. +- **[Оценки](/ru/agenteye/evaluations)**: оценки качества, полученные вашим собственным сервисом оценки, с рассуждениями по каждой оценке. +- **[Аудиты](/ru/agenteye/audits)**: периодические расследования, которые выявляют паттерны сбоев во всех сессиях. +- **[Оповещения](/ru/agenteye/alerts)** и **[инциденты](/ru/agenteye/incidents)**: правила порога, которые вас уведомляют, плюс рабочий процесс для их классификации. -**Интерфейсы** (получайте доступ к вашим данным своим способом): +**Интерфейсы** (получите доступ к своим данным удобным для вас способом): -- **[CLI](/ru/agenteye/cli-and-agents)**: управляйте всем развёртыванием из терминала или скрипта, и позвольте кодирующему агенту делать это за вас на обычном английском. -- **[AI-ассистент](/ru/agenteye/assistant)**: задавайте вопросы о ваших агентах на обычном английском прямо в панели управления. -- **REST API**: всё, что делают панель управления и CLI, поддерживается REST API, который вы можете вызывать напрямую с помощью ограниченного [API ключа](/ru/agenteye/api-keys) — принимайте события, запрашивайте сеансы и оценки, управляйте панелями управления, предупреждениями, аудитами, пользователями и ключами, чтобы интегрировать Failproof AI Observability в свой инструментарий. +- **[CLI](/ru/agenteye/cli-and-agents)**: управляйте всем развертыванием из терминала или скрипта и позвольте coding агенту сделать это за вас на обычном английском языке. +- **[AI ассистент](/ru/agenteye/assistant)**: задавайте вопросы об ваших агентах на обычном английском языке прямо на панели управления. +- **REST API**: все, что делают панель управления и CLI, поддерживается REST API, который вы можете вызывать напрямую с ограниченным [API ключом](/ru/agenteye/api-keys) — загружайте события, запрашивайте сессии и оценки, управляйте панелями управления, оповещениями, аудитами, пользователями и ключами, так что вы можете интегрировать Failproof AI Observability в ваш собственный инструментарий. -**Admin** (управляйте это для своей команды): +**Администрирование** (запустите для вашей команды): -- **[API ключи](/ru/agenteye/api-keys)**: ограниченные токены для коллектора, панели управления и ассистента. -- **Пользователи**: вход без пароля на основе электронной почты с использованием списка разрешений. -- **Параметры**: конфигурация для каждой организации, включая переопределения размера контекстного окна модели. +- **[API ключи](/ru/agenteye/api-keys)**: ограниченные токены для сборщика, панели управления и ассистента. +- **Пользователи**: вход без пароля на основе email с белым списком. +- **Параметры**: конфигурация по организации, включая переопределение контекстного окна модели. --- -## Как всё взаимодействует +## Как части работают вместе -Данные движутся в одном направлении, от вашего кода агента к панели управления: ваш агент (через Python SDK) выпускает события в agenteye-collector, который отправляет их на сервер, который служит панелью управления. Два дополнительных сервиса завершают картину — сервис оценки (оценки) и сервис AI-ассистента (чат в панели управления). +Данные движутся в одном направлении, от кода вашего агента к панели управления: ваш агент (через Python SDK) отправляет события в agenteye-collector, который отправляет их на сервер, который обслуживает панель управления. Два дополнительных сервиса дополняют это — сервис оценки (оценки) и сервис AI ассистента (чат на панели управления). - **Python SDK**: вы добавляете несколько вызовов `agenteye.event.*` в ваш агент; события буферизуются локально. -- **agenteye-collector**: лёгкий демон на каждой машине с агентом, который группирует события и отправляет их на сервер. -- **Сервер**: принимает ваши события, хранит операционное состояние в ваших собственных базах данных и служит REST API, который используют панель управления, CLI и ваши собственные интеграции. -- **Панель управления**: где вы изучаете всё. -- **Дополнительные сервисы**: сервис оценки (оценки) и сервис AI-ассистента (чат в панели управления). +- **agenteye-collector**: легкий демон на каждой машине агента, который группирует события и отправляет их на сервер. +- **Сервер**: поглощает ваши события, хранит рабочее состояние в ваших собственных базах данных и обслуживает REST API, который используют панель управления, CLI и ваши собственные интеграции. +- **Панель управления**: где вы исследуете все. +- **Дополнительные сервисы**: сервис оценки (оценки) и сервис AI ассистента (чат на панели управления). -Для словаря, используемого во всей документации (*event, session, evaluation, audit, finding, incident*), см. [Concepts](/ru/agenteye/concepts). +Для словаря, используемого во всей документации (*событие, сессия, оценка, аудит, результат, инцидент*), см. [Концепции](/ru/agenteye/concepts). --- ## Получение Failproof AI Observability -Failproof AI Observability — это корпоративный продукт компании Failproof AI, и он работает вместе с Failproof AI Enforcement — продуктом политик и ограждений — под брендом Failproof AI. Он полностью работает в вашей среде. Если у вас ещё нет доступа к пакетам, запросите демонстрацию, и мы вас настроим: напишите на [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Failproof AI Observability — это корпоративный продукт от Failproof AI, и он работает вместе с Failproof AI Enforcement — продуктом политик и guardrails — под брендом Failproof AI. Он работает полностью в вашей собственной среде. Если у вас еще нет доступа к пакетам, запросите демонстрацию и мы вас настроим: отправьте письмо на [nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- ## Следующие шаги -- [Concepts](/ru/agenteye/concepts): словарь Failproof AI Observability в одном месте. -- [Observability](/ru/agenteye/observability): следите за тем, что делают ваши агенты, запуск за запуском. -- [Security](/ru/agenteye/security): как Failproof AI Observability держит ваши данные изолированными и под вашим контролем. \ No newline at end of file +- [Концепции](/ru/agenteye/concepts): словарь Failproof AI Observability в одном месте. +- [Наблюдаемость](/ru/agenteye/observability): следите за действиями ваших агентов, запуск за запуском. +- [Безопасность](/ru/agenteye/security): как Failproof AI Observability хранит ваши данные в изоляции и под вашим контролем. \ No newline at end of file diff --git a/docs/ru/agenteye/python-sdk-skill.mdx b/docs/ru/agenteye/python-sdk-skill.mdx index f6372430..4de8a825 100644 --- a/docs/ru/agenteye/python-sdk-skill.mdx +++ b/docs/ru/agenteye/python-sdk-skill.mdx @@ -1,76 +1,77 @@ --- +--- title: "Failproof AI Observability Python SDK Agent Skill" -description: "Переход от неинструментированного агента к событиям, которые вы можете видеть, с кодирующим агентом, находящим точки инструментирования, написанием их и проверкой их внедрения." +description: "Перейдите от не инструментированного агента к событиям, которые вы можете видеть, благодаря тому, что ваш кодирующий агент находит точки инструментирования, пишет их и проверяет, что они применены." --- -Скажите своему кодирующему агенту *"добавь Failproof AI Observability к этому агенту"* и позвольте ему прочитать ваш цикл, определить, где должна быть инструментировка, написать её и проверить события перед завершением работы. +Скажите своему кодирующему агенту *«add Failproof AI Observability to this agent»* и позвольте ему прочитать вашу петлю, определить, где нужна инструментировка, написать её и проверить события перед завершением работы. -**Python SDK skill** (`agenteye-python-sdk`) — это *Agent Skill*: папка инструкций, которую кодирующий агент, такой как Claude Code или Codex, загружает по требованию при совпадении задачи. Она обучает агента использованию [Python SDK](/ru/agenteye/python-sdk) — это не библиотека и не меняет ничего в том, как работает SDK. +**Python SDK skill** (`agenteye-python-sdk`) — это *Agent Skill*: папка с инструкциями, которые кодирующий агент, например Claude Code или Codex, загружает по требованию, когда задача соответствует навыку. Он учит агента использовать [Python SDK](/ru/agenteye/python-sdk) — это не библиотека и ничего не меняет в работе SDK. -## Инструментировка легко написать и легко сделать неправильно незаметно +## Инструментировка легко писать и легко неправильно написать незаметно -SDK небольшой: тринадцать методов событий, все только с ключевыми параметрами. Кодирующий агент может прочитать справочник [Python SDK](/ru/agenteye/python-sdk) и создать приемлемую инструментировку за минуту. +SDK невелик: тринадцать методов событий, все только именованные параметры. Кодирующий агент может прочитать справочник [Python SDK](/ru/agenteye/python-sdk) и написать правдоподобную инструментировку за минуту. -Загвоздка в том, что этот SDK не выдаёт ошибку, когда вы ошибаетесь, и неправильная инструментировка выглядит точно так же, как правильная, пока кто-то не откроет панель и не обнаружит пустоту. Ошибки, которые требуют реального времени для исправления — это все молчанцы: +Ловушка в том, что этот SDK не вызывает исключения, когда вы ошибаетесь, и неправильная инструментировка выглядит ровно как правильная, пока кто-то не откроет панель управления и не обнаружит её пустой. Ошибки, которые стоят реального времени — это молчание: | Ошибка | Что вы видите | |---|---| -| Нет `agent_start` | Все события приходят. Нулевых сессий. | -| Окружение никогда не установлено | Всё работает, заархивировано под `dev`. | -| `outcome="failure"` | Запуск показывает зелень — только `failed`, `error`, `timeout`, `rejected` учитываются. | -| Опечатка в имени поля | Принято и сохранено как новое поле. | +| Нет `agent_start` | Все события попадают. Ноль сеансов. | +| Окружение никогда не установлено | Всё работает, классифицируется как `dev`. | +| `outcome="failure"` | Запуск выглядит зелёным — только `failed`, `error`, `timeout`, `rejected` считаются. | +| Опечатка в имени поля | Принимается и сохраняется как новое поле. | | События, испущенные из пула потоков | Молча отброшены. | -Никакая из них не выдаёт ошибку. Ни одна не появляется в тестах. Каждая есть в skill, установленная как контракт с проверкой, которая её ловит. +Ничто из этого не вызывает исключения. Ничто не проявляется в тестах. Всё это есть в навыке, описано как контракт с проверкой, которая его ловит. -## Что она делает, по порядку +## Что он делает, по порядку -Skill выполняет те же три шага, которые выполнил бы аккуратный инженер: +Навык выполняет те же три шага, которые выполнил бы внимательный инженер: -1. **План.** Он читает цикл вашего агента и задаёт два вопроса, на которые может ответить только вы: что считается одним запуском (ваш `session_id`) и кто различимые участники (ваш `agent_id`). Он получает согласие перед написанием кода, потому что изменение их позже разделяет вашу историю и ломает тренды. -2. **Написать.** Он связывает идентичность один раз за запуск, а не проводит её через каждый вызов, и выбирает форму, безопасную для одновременности — деталь, которая имеет значение, потому что очевидный ярлык молча смешивает два перекрывающихся запуска в одну сессию. -3. **Проверить.** Он запускает ваш агент и читает полученные файлы событий, проверяя наличие `agent_start`, правильность окружения и то, что один запуск произвёл одну сессию. +1. **Планирование.** Он читает вашу петлю агента и задаёт два вопроса, на которые может ответить только вы: что считать одним запуском (ваш `session_id`), и кто отличимые акторы (ваш `agent_id`). Он получает согласие перед написанием кода, потому что изменение их позже разделяет вашу историю и ломает тренды. +2. **Написание.** Он привязывает идентичность один раз за запуск, а не пропускает её через каждый сайт вызова, и выбирает форму, безопасную для параллелизма — деталь, которая имеет значение, потому что очевидный ярлык молча смешивает два перекрывающихся запуска в один сеанс. +3. **Проверка.** Он запускает ваш агент и читает полученные файлы событий, проверяя, что `agent_start` присутствует, окружение правильное, и один запуск создал один сеанс. -Третий шаг — это тот, который люди пропускают. SDK записывает события в локальные файлы, поэтому полную интеграцию можно доказать на ноутбуке без сервера, без API ключа и без сети — что именно почему skill настаивает на этом. +Третий шаг — это то, что люди пропускают. SDK пишет события в локальные файлы, поэтому полная интеграция может быть доказана на ноутбуке без сервера, без API ключа и без сети — и именно поэтому навык настаивает на этом. -## Как это соотносится с другими skills +## Как это связано с другими навыками -Три skills, один чистый разделение: +Три навыка, одно чистое разделение: -| Skill | Используйте его когда | Что он трогает | +| Навык | Используйте, когда | Что он трогает | |---|---|---| -| **Python SDK skill** (эта страница) | Вы хотите, чтобы ваш агент *выдавал* телеметрию — "добавить наблюдаемость", "почему мой агент не показывается?" | Пишет код в репо вашего агента. Ничего не читает. | -| **[Evaluator skill](/ru/agenteye/evaluator-skill)** | Вы хотите *оценить* запуски — "что нам вообще измерять?" | Пишет код в вашу репо; читает телеметрию | -| **[CLI skill](/ru/agenteye/cli-skill)** | Вы хотите *прочитать* что случилось, или управлять вашим развёртыванием | Управляет CLI как вы, включая изменения | +| **Python SDK skill** (эта страница) | Вы хотите, чтобы ваш агент *испускал* телеметрию — «add observability», «почему мой агент не показывается?» | Пишет код в репозитории агента. Ничего не читает. | +| **[Evaluator skill](/ru/agenteye/evaluator-skill)** | Вы хотите *оценивать* запуски — «что мы вообще должны измерять?» | Пишет код в вашем репозитории; читает телеметрию | +| **[CLI skill](/ru/agenteye/cli-skill)** | Вы хотите *читать* что произошло, или управлять вашим развёртыванием | Управляет CLI как вы, включая изменения | -Они передают друг другу в этом порядке: этот skill запускает поток событий, эвалюатор их оценивает, CLI читает их обратно. Нечего оценивать и нечего читать, пока ваш агент не выдаёт сессии, поэтому если вы начинаете с нуля, начните отсюда. +Они передают эстафету в этом порядке: этот навык запускает поток событий, оценщик их оценивает, CLI читает их обратно. Нечего оценивать и нечего читать, пока ваш агент не испускает сеансы, поэтому если вы начинаете с нуля, начните отсюда. -## Предусловия +## Требования 1. **Python 3.10+** и кодовая база агента, которую вы хотите инструментировать. -2. **SDK.** Он распространяется среди клиентов как приватное колесо вместо общедоступного индекса — ваш онбординг охватывает как его получить и установить. Skill знает путь установки и попросит вас, если не сможет его найти. -3. **Ничего больше.** Нет входа на панель, нет API ключа, нет сети. Skill проверяет по файлам событий, которые пишет SDK, поэтому может завершиться и доказать свою работу оффлайн. +2. **SDK.** Он распространяется клиентам как приватный wheel, а не из публичного индекса — ваша адаптация рассказывает, как его получить и установить. Навык знает путь установки и попросит вас, а не будет угадывать, если не сможет его найти. +3. **Ничего больше.** Никакого входа на панель управления, никакого API ключа, никакой сети. Навык проверяет против файлов событий, которые пишет SDK, поэтому он может завершиться и доказать свою работу в автономном режиме. ## Где его получить -Skill находится в общей коллекции [`FailproofAI/skills`](https://github.com/FailproofAI/skills): +Навык находится в публичной коллекции [`FailproofAI/skills`](https://github.com/FailproofAI/skills): ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -Добавьте `-g` для установки для каждого проекта вместо только текущего, и `--copy` если ваше окружение не следует симлинкам. Для Codex передайте `-a codex`. +Добавьте `-g` для установки для каждого проекта вместо только текущего, и `--copy`, если ваша среда не следует symlink. Для Codex передайте `-a codex`. ## Установка вручную -Agent Skills — это папки, содержащие `SKILL.md` плюс справки. Если вы предпочитаете не использовать установщик: +Agent Skills — это папки, содержащие `SKILL.md` плюс ссылки. Если вы предпочитаете не использовать установщик: -- **Claude Code**: скопируйте папку `agenteye-python-sdk/` в `~/.claude/skills/` (каждый проект) или `/.claude/skills/` (только этот репо). Claude Code автоматически её обнаружит — проверьте список `/skills` или просто спросите что-нибудь, что на неё совпадает. -- **Codex**: Codex читает то же самое `SKILL.md`. Bundled `agents/openai.yaml` устанавливает `allow_implicit_invocation: true`, поэтому она автоматически выбирается при совпадении задачи; иначе вызовите как `$agenteye-python-sdk`. +- **Claude Code**: скопируйте папку `agenteye-python-sdk/` в `~/.claude/skills/` (для каждого проекта) или `/.claude/skills/` (только для этого репозитория). Claude Code обнаруживает её автоматически — проверьте список `/skills` или просто спросите что-то соответствующее. +- **Codex**: Codex читает тот же `SKILL.md`. Bundled `agents/openai.yaml` устанавливает `allow_implicit_invocation: true`, поэтому он автоматически выбирается, когда задача совпадает; в противном случае вызовите его как `$agenteye-python-sdk`. -Запустите ваш агент **в репозитории, содержащем код, который вы хотите инструментировать** — skill читает цикл вашего агента перед тем как что-либо предложить. +Запустите ваш агент **в репозитории, содержащем код, который вы хотите инструментировать** — навык читает вашу петлю агента, прежде чем что-то предлагать. -## Как выглядит сессия +## Как выглядит сеанс ```text you ▸ Add Failproof AI Observability to this agent. @@ -103,29 +104,29 @@ agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and Want me to fix those too? ``` -Закономерность, на которую стоит обратить внимание: он прочитал код перед предложением, задал только вопросы, на которые вы можете ответить, переиспользовал уже имеющийся id, выбрал форму, безопасную для одновременности *потому что* увидел пул потоков, и **проверил путём чтения фактических событий** вместо объявления успеха — затем отметил единственное место, которое, как он знал, молча провалилось. +Паттерн, на который стоит обратить внимание: он прочитал код перед предложением, задал только вопросы, на которые вы можете ответить, переиспользовал уже имеющийся id, выбрал форму, безопасную для параллелизма, *потому что* увидел пул потоков, и **проверил, прочитав реальные события** вместо того, чтобы объявить успех — затем указал на единственное место, где он знал, что это молча сломается. -## Что вы можете у неё спросить +## Что вы можете попросить -- *"Почему мой агент не показывается на панели?"* → прочитает лестницу: записываются ли события, есть ли там `agent_start`, правильно ли окружение, читает ли сборщик из того же места. -- *"Всё приходит под dev."* → окружение никогда не было установлено, или было сброшено позже. -- *"Добавь отслеживание токенов."* → находит ваш LLM wrapper и записывает модель, причину остановки и использование. -- *"Инструментируй субагентов тоже."* → одна сессия, различные метки агентов, вложенные под своим родителем. -- *"Напиши тесты для инструментировки."* → указывает SDK на временную директорию и проверяет события, которые она написала. +- *«Why isn't my agent showing up on the dashboard?»* → проходит по лестнице: пишутся ли события, есть ли `agent_start`, правильно ли окружение, читает ли сборщик то же место. +- *«Everything's landing under dev.»* → окружение никогда не было установлено, или было сброшено более поздним вызовом. +- *«Add token tracking.»* → находит ваш LLM wrapper и записывает модель, причину остановки и использование. +- *«Instrument the sub-agents too.»* → один сеанс, отличные метки агентов, вложены в их родителя. +- *«Write tests for the instrumentation.»* → указывает SDK на временный каталог и проверяет события, которые он написал. -## На что нужно обратить внимание +## На что следует обратить внимание -**Позвольте ей проверить.** Шаг, который делает этот skill стоящим использования — последний — запуск вашего агента и чтение событий обратно. Агент, который пишет инструментировку и останавливается, выполнил лёгкую половину, а половину, которая молча падает, другую. +**Позвольте ему проверить.** Шаг, который делает этот навык стоящим использования — последний — запуск вашего агента и чтение событий обратно. Агент, который пишет инструментировку и останавливается, выполнил лёгкую половину, и половина, которая молча ломается — это другая. -**Согласуйте имена перед кодом.** `session_id` и `agent_id` — оси, по которым каждая поверхность группирует. Переименование их позже разделяет историю: старые запуски сохраняют старые метки и ваши тренды ломаются. Skill попросит; ответ стоит минуты размышления. +**Согласуйте имена перед кодом.** `session_id` и `agent_id` — это оси, по которым группирует каждая поверхность. Переименование их позже разделяет историю: старые запуски сохраняют старые метки и ваши тренды ломаются. Навык будет спрашивать; ответ стоит минуты размышления. -**Если ваш агент предлагает установить SDK из общедоступного индекса, skill не загрузился.** SDK распространяется приватно. Это предложение — надёжный признак того, что ваш кодирующий агент угадывает вместо следования skill — остановите его там и проверьте что skill установлен. +**Если ваш агент предлагает установить SDK из публичного индекса, навык не загрузился.** SDK распространяется приватно. Это предложение — надёжный признак того, что ваш кодирующий агент угадывает, а не следует навыку — остановите его там и проверьте, что навык установлен. -Кроме того его радиус взрыва небольшой: он пишет код в вашу рабочую директорию и файлы событий, где вы ему скажете. Он ничего не читает из вашего развёртывания и не меняет о нём ничего. +Кроме того, его радиус взрыва мал: он пишет код в вашем рабочем каталоге и файлы событий там, где вы говорите. Он ничего не читает из вашего развёртывания и ничего не меняет в нём. ## Следующие шаги -- **[Python SDK](/ru/agenteye/python-sdk)**: полная справка по событиям — каждый тип события и поле — стоящая за этим что automation этого skill. -- **[Sessions](/ru/agenteye/sessions)**: что производит ваша инструментировка как только события приходят. -- **[Evaluator Agent Skill](/ru/agenteye/evaluator-skill)**: следующий шаг как только запуски приходят — их оценка. +- **[Python SDK](/ru/agenteye/python-sdk)**: полная справка событий — каждый тип события и поле — за тем, что этот навык автоматизирует. +- **[Sessions](/ru/agenteye/sessions)**: что производит ваша инструментировка, когда события попадают. +- **[Evaluator Agent Skill](/ru/agenteye/evaluator-skill)**: следующий шаг, как только запуски приземляются — их оценка. - **[CLI Agent Skill](/ru/agenteye/cli-skill)**: чтение вашей телеметрии обратно. \ No newline at end of file diff --git a/docs/ru/agenteye/python-sdk.mdx b/docs/ru/agenteye/python-sdk.mdx index c83ae6bc..679eaf48 100644 --- a/docs/ru/agenteye/python-sdk.mdx +++ b/docs/ru/agenteye/python-sdk.mdx @@ -1,15 +1,14 @@ --- ---- title: "Python SDK" -description: "Посмотрите, что именно сделали ваши AI-агенты в продакшене: каждый запуск агента, вызов инструмента, запрос к модели, хук и вмешательство человека." +description: "Посмотрите точно, что делали ваши AI-агенты в production: каждый запуск агента, вызов инструмента, запрос модели, хук и вмешательство человека." --- -Посмотрите, что именно сделали ваши AI-агенты в продакшене: каждый запуск агента, вызов инструмента, запрос к модели, хук и вмешательство человека. Python SDK Failproof AI Observability записывает эту цепочку событий изнутри кода вашего агента, чтобы вы могли отлаживать, аудировать и оценивать происходящее. Используйте его, когда захотите, чтобы Failproof AI Observability наблюдал за вашими агентами. +Посмотрите точно, что делали ваши AI-агенты в production: каждый запуск агента, вызов инструмента, запрос модели, хук и вмешательство человека. Failproof AI Observability Python SDK записывает эту цепочку событий изнутри вашего кода агента, позволяя вам отлаживать, проверять и оценивать произошедшее. Используйте его всякий раз, когда вы хотите, чтобы Failproof AI Observability отслеживал ваших агентов. -Под капотом SDK записывает структурированные события в локальные JSONL-файлы, а демон сборщика подхватывает их и автоматически отправляет на платформу. Вам не нужно самостоятельно управлять этими файлами. +Под капотом SDK записывает структурированные события в локальные JSONL-файлы, а демон-сборщик подхватывает их и автоматически отправляет на платформу. Вы не управляете этими файлами самостоятельно. -> **Совет:** Новичок в Failproof AI Observability? Эта страница является полным справочником событий SDK. +> **Совет:** Новичок в Failproof AI Observability? Эта страница — полный справочник событий SDK.
@@ -19,15 +18,15 @@ description: "Посмотрите, что именно сделали ваши ## Установка -SDK распространяется клиентам как приватный wheel, а не из публичного индекса пакетов. В процессе подключения объясняется, как его получить, установить и зафиксировать версию — обратитесь к вашему контакту Failproof AI, если вам нужен доступ. +SDK распространяется клиентам в виде приватного wheel-файла, а не из публичного индекса пакетов. На этапе onboarding вы узнаете, как его получить, установить и зафиксировать версию — обратитесь к вашему контакту в Failproof AI, если вам нужен доступ. -После установки проверьте её наличие: +После установки проверьте, что она прошла успешно: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Предпочитаете позволить кодирующему агенту выполнить всю интеграцию? [Python SDK Agent Skill](/ru/agenteye/python-sdk-skill) знает путь установки, планирует точки инструментирования, пишет их и проверяет, что события доходят. +Предпочитаете, чтобы агент-кодировщик выполнил всю интеграцию? [Python SDK Agent Skill](/ru/agenteye/python-sdk-skill) знает путь установки, планирует точки инструментирования, пишет их и проверяет, что события доходят до сервера. --- @@ -61,7 +60,7 @@ agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="succ ### Инструментирование реального вызова -На практике вы оборачиваете существующий код агента. Заключите вызов модели с `model_request` перед и `model_response` после, чтобы два события охватывали реальный запрос и Failproof AI Observability смогла их связать: +На практике вы оборачиваете существующий код агента. Окружите вызов модели с `model_request` перед и `model_response` после, чтобы эти два события охватывали реальный запрос и Failproof AI Observability мог их связать: ```python import anthropic @@ -96,11 +95,11 @@ agenteye.event.model_response( ) ``` -Оборачивайте вызовы инструментов аналогично с `tool_use` и `tool_result`, переиспользуя один `tool_call_id` для обеих операций. +Оборачивайте вызовы инструментов так же, используя `tool_use` и `tool_result`, переиспользуя один `tool_call_id` для обеих событий. -Вот как выглядят эти события на дашборде — они раскрашены по типам и фильтруются по среде, агенту и сессии: +Вот как эти события выглядят на панели управления, раскрашены по типам и фильтруемы по окружению, агенту и сессии: -![Живой поток событий, раскрашенный по типам событий и фильтруемый по среде, агенту и сессии](/agenteye/images/events-stream.png) +![Живой поток событий с раскраской по типам событий и фильтрацией по окружению, агенту и сессии](/agenteye/images/events-stream.png) --- @@ -108,16 +107,16 @@ agenteye.event.model_response( ```python agenteye.configure( - base_dir=None, # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye - flush_interval=0.5, # float, seconds between flush cycles - environment=None, # str | None. Deployment environment label + base_dir=None, # Path | str | None. По умолчанию: $AGENTEYE_HOME или ~/.agenteye + flush_interval=0.5, # float, секунды между циклами сброса + environment=None, # str | None. Метка окружения развёртывания ) ``` -Вызовите один раз перед любым вызовом `event.*`. Безопасно опустить; значения по умолчанию работают из коробки. Все аргументы являются только именованными; передавайте их по имени, как показано выше. +Вызовите один раз перед любым вызовом `event.*`. Безопасно пропустить; значения по умолчанию работают из коробки. Все аргументы только именованные; передавайте их по имени, как показано выше. Когда `base_dir` равен `None` (по умолчанию), SDK читает `$AGENTEYE_HOME`, если он установлен, -в противном случае возвращается к `~/.agenteye`. Это соответствует собственному разрешению сборщика, +иначе переходит на `~/.agenteye`. Это соответствует собственному разрешению сборщика, поэтому одна переменная окружения `AGENTEYE_HOME` настраивает общую очередь событий для обоих SDK и сборщика. @@ -125,7 +124,7 @@ SDK и сборщика. ## Окружение -Помечайте каждое событие средой развёртывания (`production`, `staging`, `qa`, `canary` и т. д.). Установите один раз; SDK автоматически прикрепляет его к каждому событию. +Помечайте каждое событие окружением развёртывания (`production`, `staging`, `qa`, `canary` и т.д.). Установите его один раз; SDK автоматически присоединяет его к каждому событию. **Вариант 1: через `configure()`:** @@ -139,34 +138,34 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**Приоритет:** `configure(environment=...)` имеет приоритет над переменной окружения. Если ничего не установлено, по умолчанию используется `"dev"`. +**Приоритет:** `configure(environment=...)` имеет приоритет над переменной окружения. Если ни то, ни другое не установлено, по умолчанию используется `"dev"`. -Значение окружения появляется как фильтр первого уровня на дашборде и хранится на сервере для быстрых запросов. +Значение окружения отображается как фильтр первого уровня в панели управления и хранится на сервере для быстрых запросов. -> **Предупреждение:** Значения окружения не должны содержать буквальную запятую `,`. Фильтры дашборда используют множественный выбор, разделённый запятыми (`?environment=prod,staging`), поэтому окружение с именем `prod,blue` было бы разделено на два значения. События с окружениями, содержащими запятые, отклоняются при приёме. +> **Предупреждение:** Значения окружения не должны содержать литеральную запятую `,`. Фильтры панели управления используют разделённый запятыми мультивыбор (`?environment=prod,staging`), поэтому окружение с названием `prod,blue` было бы разделено на два значения. События с окружениями, содержащими запятые, отклоняются при поступлении. --- ## Данные и приватность -SDK записывает только поля, которые вы явно передаёте. Подсказки, сообщения, входные и выходные данные инструментов, а также содержимое модели захватываются исключительно потому, что вы передаёте их в вызов `event.*`. Ничто не читается из вашего процесса и не захватывается неявно. Любое поле, которое вы не установили, полностью опускается из события; оно не записывается на диск. +SDK записывает только те поля, которые вы явно передали. Подсказки, сообщения, входные и выходные данные инструментов, а также содержимое модели захватываются только потому, что вы передали их вызову `event.*`. Ничто не читается из вашего процесса и не захватывается неявно. Любое поле, которое вы не установили, полностью опускается из события; оно не записывается на диск. -Это делает редактирование вашим выбором и вашей ответственностью. Если подсказка или полезная нагрузка инструмента содержит PII или секреты, которые вы не хотите хранить, очистите или замаскируйте их перед передачей методу события. +Это делает редакцию вашим выбором и вашей ответственностью. Если подсказка или полезная нагрузка инструмента содержит PII или секреты, которые вы предпочитаете не хранить, удалите или замаскируйте их перед передачей методу события. --- ## Справочник событий -Большинство событий поступают в парах начало/конец, которые разделяют идентификатор корреляции: `tool_use` и `tool_result` разделяют `tool_call_id`, `hook_triggered` и `hook_completed` разделяют `hook_id`, а `human_wait` и `human_input` разделяют `input_id`. Выпустите событие начала, выполните работу, затем выпустите событие завершения с тем же ID. Failproof AI Observability соответствует паре и вычисляет `duration_ms` за вас, поэтому вы никогда не передаёте `duration_ms` сами. +Большинство событий приходят парами начало/конец, которые общий ID корреляции: `tool_use` и `tool_result` общий `tool_call_id`, `hook_triggered` и `hook_completed` общий `hook_id`, а `human_wait` и `human_input` общий `input_id`. Отправьте начальное событие, выполните работу, затем отправьте конечное событие с тем же ID. Failproof AI Observability связывает пару и автоматически вычисляет `duration_ms`, поэтому вы никогда не передаёте `duration_ms` сами. -![Граф выполнения сессии в стиле git рядом с временной шкалой событий, реконструированный из парных событий, с панелью разбивки инструмента/модели/хука](/agenteye/images/session-detail.png) +![График выполнения сессии в стиле git рядом с её временной шкалой событий, восстановленный из связанных событий, с панелью разбивки инструмента/модели/хука](/agenteye/images/session-detail.png) Все методы событий требуют эти два поля: | Поле | Тип | Описание | |---|---|---| -| `session_id` | `str` | Определяет верхнеуровневый запуск агента | -| `agent_id` | `str` | Определяет, какой агент в сессии выпустил событие | +| `session_id` | `str` | Идентифицирует запуск агента верхнего уровня | +| `agent_id` | `str` | Идентифицирует, какой агент в сессии отправил событие | Все методы также принимают произвольные `**kwargs` для пользовательских метаданных (см. [Пользовательские поля](#custom-fields)). @@ -174,14 +173,14 @@ SDK записывает только поля, которые вы явно п ### `event.agent_start()` -Выпускается, когда агент начинает работу. +Отправляется, когда агент начинает работу. ```python agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - parent agent_id for nested agents + parent_id=None, # str | None - agent_id родителя для вложенных агентов ) ``` @@ -189,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Выпускается, когда агент завершает работу. +Отправляется, когда агент завершает работу. ```python agenteye.event.agent_end( @@ -204,14 +203,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -Выпускается, когда агент вызывает инструмент. Сопарьте с `tool_result`; SDK автоматически вычисляет `duration_ms`. +Отправляется, когда агент вызывает инструмент. Свяжите с `tool_result`; SDK автоматически вычисляет `duration_ms`. ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", - tool_name="web_search", # str, required - tool_call_id="toolu_01", # str, required - correlation key for the matching tool_result + tool_name="web_search", # str, требуется + tool_call_id="toolu_01", # str, требуется - ключ корреляции для соответствующего tool_result input={"query": "..."}, # dict | None ) ``` @@ -220,17 +219,17 @@ agenteye.event.tool_use( ### `event.tool_result()` -Выпускается, когда инструмент возвращает результат. Коррелирует с `tool_use` через `tool_call_id`. +Отправляется, когда инструмент возвращает результат. Коррелирует с `tool_use` через `tool_call_id`. ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # must match the prior tool_use + tool_call_id="toolu_01", # должна совпадать с предыдущим tool_use output={"results": ["..."]}, # Any | None - error=None, # str | None - set if the tool raised - # duration_ms is computed automatically - do not pass it + error=None, # str | None - установите, если инструмент вызвал ошибку + # duration_ms вычисляется автоматически - не передавайте её ) ``` @@ -238,60 +237,60 @@ agenteye.event.tool_result( ### `event.model_request()` -Выпускается непосредственно перед отправкой подсказки в LLM. +Отправляется непосредственно перед отправкой подсказки в LLM. ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - any provider/model string; not validated - messages=[ # list[dict] | None - conversation turns + model="claude-sonnet-4-6", # str | None - любая строка провайдера/модели; не валидируется + messages=[ # list[dict] | None - витки разговора {"role": "user", "content": "..."}, ], - system="You are helpful.", # Any | None - str or list of content blocks - tools=[ # list[dict] | None - tool schemas offered to the model + system="You are helpful.", # Any | None - str или список блоков контента + tools=[ # list[dict] | None - схемы инструментов, предложенные модели {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -Записи `messages` принимают либо простую строку `content`, либо список блоков в стиле Anthropic `content`. Параметры выборки (`temperature`, `max_tokens` и т. д.) можно передать в виде дополнительных kwargs. +Записи `messages` принимают либо простую строку `content`, либо список блоков в стиле Anthropic `content`. Параметры сэмплирования (`temperature`, `max_tokens` и т.д.) могут быть переданы как дополнительные kwargs. --- ### `event.model_response()` -Выпускается, когда LLM возвращает ответ. +Отправляется, когда LLM возвращает ответ. ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - any provider/model string; not validated + model="claude-sonnet-4-6", # str | None - любая строка провайдера/модели; не валидируется stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None - content=[ # Any | None - str, or list of content blocks + content=[ # Any | None - str или список блоков контента {"type": "text", "text": "..."}, ], role="assistant", # str | None ) ``` -`content` принимает либо простую строку (универсальные провайдеры), либо список блоков контента в стиле Anthropic. Вызовы инструментов находятся внутри `content` как блоки `{"type": "tool_use", ...}`, без отдельного поля `tool_calls`. +`content` принимает либо простую строку (для универсальных провайдеров), либо список блоков контента в стиле Anthropic. Вызовы инструментов находятся внутри `content` как блоки `{"type": "tool_use", ...}`, без отдельного поля `tool_calls`. --- ### `event.hook_triggered()` -Выпускается, когда срабатывает хук. Сопарьте с `hook_completed`; SDK автоматически вычисляет `duration_ms`. +Отправляется, когда срабатывает хук. Свяжите с `hook_completed`; SDK автоматически вычисляет `duration_ms`. ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", - hook_name="pre_tool_use", # str, required - hook_id="hook-abc", # str, required - correlation key + hook_name="pre_tool_use", # str, требуется + hook_id="hook-abc", # str, требуется - ключ корреляции trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -301,18 +300,18 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Выпускается, когда хук завершается. Коррелирует с `hook_triggered` через `hook_id`. +Отправляется, когда хук завершает работу. Коррелирует с `hook_triggered` через `hook_id`. ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # must match the prior hook_triggered + hook_id="hook-abc", # должна совпадать с предыдущим hook_triggered outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms is computed automatically - do not pass it + # duration_ms вычисляется автоматически - не передавайте её ) ``` @@ -320,77 +319,77 @@ agenteye.event.hook_completed( ### `event.error()` -Выпускается, когда возникает необработанная ошибка. +Отправляется, когда возникает необработанная ошибка. ```python agenteye.event.error( session_id="run-001", agent_id="planner", - error_type="TimeoutError", # str, required - message="timed out", # str, required + error_type="TimeoutError", # str, требуется + message="timed out", # str, требуется traceback="Traceback...", # str | None ) ``` --- -## События взаимодействия человека и системы +## События с участием человека -События взаимодействия человека и системы предоставляют вам контроль над моментами, когда человек вступает в выполнение агента (ожидание одобрения, предоставление ввода, пауза или остановка агента). Они позволяют измерить, сколько времени люди берут для ответа (SDK автоматически вычисляет `duration_ms` для парных событий), аудировать, кто приостановил или прервал агента, и создавать рабочие процессы одобрения и контроля, которые отображаются на дашборде. +События с участием человека дают вам контроль над моментами, когда человек вмешивается в выполнение агента (ожидание одобрения, предоставление входных данных, пауза или остановка агента). Они позволяют вам измерить, сколько времени люди тратят на ответ (SDK автоматически вычисляет `duration_ms` для связанных событий), проверить, кто приостановил или прервал агента, и создавать рабочие процессы одобрения и контроля, которые отображаются в панели управления. ### `event.human_wait()` -Выпускается, когда агент приостанавливает выполнение в ожидании ввода человека. Сопарьте с `human_input`; SDK автоматически вычисляет `duration_ms` (сколько времени человек занял на ответ). +Отправляется, когда агент приостанавливает выполнение в ожидании, что человек предоставит входные данные. Свяжите с `human_input`; SDK автоматически вычисляет `duration_ms` (сколько времени человеку потребовалось, чтобы ответить). ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - correlation key for the matching human_input - prompt="Do you approve this action?", # str | None - the question shown to the human - options=["approve", "reject", "defer"], # list[str] | None - choices presented to the human - reason="approval_required", # str | None - why the agent is waiting + input_id="inp-abc", # str, требуется - ключ корреляции для соответствующего human_input + prompt="Do you approve this action?", # str | None - вопрос, показываемый человеку + options=["approve", "reject", "defer"], # list[str] | None - варианты, предложенные человеку + reason="approval_required", # str | None - почему агент ждёт ) ``` ### `event.human_input()` -Выпускается, когда человек предоставляет ввод и агент возобновляет работу. Коррелирует с `human_wait` через `input_id`. `duration_ms` вычисляется автоматически и не должна передаваться вызывающей стороной. +Отправляется, когда человек предоставляет входные данные и агент возобновляет работу. Коррелирует с `human_wait` через `input_id`. `duration_ms` вычисляется автоматически и не должен передаваться вызывающей стороной. ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - must match the prior human_wait - response="approve", # str | None - the human's answer (free text or selected option) - # duration_ms is computed automatically - do not pass it + input_id="inp-abc", # str, требуется - должна совпадать с предыдущим human_wait + response="approve", # str | None - ответ человека (свободный текст или выбранный вариант) + # duration_ms вычисляется автоматически - не передавайте её ) ``` ### `event.human_pause()` -Выпускается, когда человек активно приостанавливает агента (например, через управление дашборда). Агент приостановлен, но не завершен. +Отправляется, когда человек активно приостанавливает агента (например, через управление на панели управления). Агент приостановлен, но не завершён. ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - who paused the agent + user_id="usr_42", # str | None - кто приостановил агента ) ``` ### `event.human_interrupt()` -Выпускается, когда человек активно останавливает агента во время выполнения. В отличие от `human_pause`, работа агента завершается, а не приостанавливается. +Отправляется, когда человек активно останавливает агента во время выполнения. В отличие от `human_pause`, работа агента завершается, а не просто приостанавливается. ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - who interrupted the agent - at_step="tool_use:web_search", # str | None - what the agent was doing when stopped + user_id="usr_42", # str | None - кто прервал агента + at_step="tool_use:web_search", # str | None - чем был занят агент при остановке ) ``` @@ -398,7 +397,7 @@ agenteye.event.human_interrupt( ## Пользовательские поля -Любые дополнительные аргументы ключевого слова добавляются к событию после стандартных полей: +Любые дополнительные именованные аргументы добавляются к событию после стандартных полей: ```python agenteye.event.tool_use( @@ -406,32 +405,32 @@ agenteye.event.tool_use( agent_id="planner", tool_name="db_query", tool_call_id="toolu_02", - tenant_id="acme", # custom field - region="us-east-1", # custom field + tenant_id="acme", # пользовательское поле + region="us-east-1", # пользовательское поле ) ``` -`timestamp`, `type` и `environment` зарезервированы и вызывают `ValueError` (`Reserved field names cannot be used as custom fields: [...]`), если переданы как пользовательские поля. `session_id` и `agent_id` являются обязательными параметрами для каждого метода события и не могут быть переданы второй раз; Python вызовет `TypeError`, если вы это сделаете. Вместо этого установите окружение с помощью `configure(environment=...)` (или переменной `AGENTEYE_ENVIRONMENT`). +`timestamp`, `type` и `environment` зарезервированы и выбрасывают `ValueError` (`Reserved field names cannot be used as custom fields: [...]`), если переданы как пользовательские поля. `session_id` и `agent_id` — требуемые параметры в каждом методе события и не могут быть предоставлены второй раз; Python выбросит `TypeError`, если вы это сделаете. Вместо этого установите окружение с помощью `configure(environment=...)` (или переменной `AGENTEYE_ENVIRONMENT`). -Сохраняйте полезные нагрузки как структурированный JSON, если хотите запрашивать их поля. Значения, которые JSON не поддерживает изначально — такие как даты/время, UUID, десятичные числа, наборы, байты или объекты моделей — преобразуются в строки, чтобы запись продолжалась безопасно. +Сохраняйте полезные нагрузки как структурированный JSON, когда хотите запросить их поля. Значения, которые JSON не поддерживает изначально — такие как даты и времена, UUIDs, десятичные числа, множества, байты или объекты моделей — преобразуются в строки, чтобы запись продолжалась безопасно. --- -## Как записываются события +## Как события записываются -События буферизуются в процессе и записываются на диск каждые `flush_interval` секунд (по умолчанию 500 мс). Каждая запись в буфер записывает один JSONL-файл: +События буферизируются в процессе и сбрасываются на диск каждые `flush_interval` секунд (по умолчанию 500 мс). Каждый сброс записывает один JSONL-файл: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Сборщик отслеживает этот каталог и автоматически загружает файлы. Вам не нужно напрямую управлять этими файлами. +Сборщик наблюдает этот каталог и автоматически загружает файлы. Вам не нужно управлять этими файлами напрямую. -Каждый файл записывается атомарно: SDK пишет во временный файл, а затем переименовывает его на место, поэтому сборщик никогда не видит наполовину записанного файла. Финальная запись в буфер также выполняется при выходе процесса, поэтому события, буферизованные в последний интервал, не теряются. Если сборщик в автономном режиме, события просто накапливаются как файлы на диске и отправляются, когда он снова включается. +Каждый файл записывается атомарно: SDK пишет во временный файл и затем переименовывает его на месте, поэтому сборщик никогда не видит полузаписанный файл. Окончательный сброс также выполняется при выходе вашего процесса, поэтому события, буферизированные в последнем интервале, не теряются. Если сборщик офлайн, события просто накапливаются как файлы на диске и отправляются, как только он вернулся в онлайн. --- -## Дальнейшие шаги +## Следующие шаги -- [Поток событий](/ru/agenteye/event-stream): смотрите эти события в прямом эфире, раскрашенные и фильтруемые по среде, агенту и сессии. -- [Сессии](/ru/agenteye/sessions): смотрите, как парные события реконструируют каждый запуск агента как граф выполнения и временную шкалу. \ No newline at end of file +- [Поток событий](/ru/agenteye/event-stream): смотрите, как эти события прибывают в реальном времени, раскрашенные и фильтруемые по окружению, агенту и сессии. +- [Сессии](/ru/agenteye/sessions): посмотрите, как связанные события восстанавливают каждый запуск агента как график выполнения и временную шкалу. \ No newline at end of file diff --git a/docs/ru/agenteye/queries.mdx b/docs/ru/agenteye/queries.mdx index c53959c2..2029ecbc 100644 --- a/docs/ru/agenteye/queries.mdx +++ b/docs/ru/agenteye/queries.mdx @@ -4,53 +4,53 @@ description: "Задавайте любые вопросы о данных ва --- -Задавайте любые вопросы о данных вашего агента и получайте ответы за секунды. Observability от Failproof AI предоставляет вам библиотеку сохранённых готовых к запуску запросов над вашими событиями и оценками, чтобы вы начали с рабочего примера вместо пустого редактора SQL. +Задавайте любые вопросы о данных вашего агента и получайте ответы за секунды. Failproof AI Observability предоставляет библиотеку сохранённых, готовых к использованию запросов к вашим событиям и оценкам, чтобы вы начали с рабочего примера вместо пустого редактора SQL. -![Библиотека сохранённых запросов: сетка переиспользуемых запросов, как встроенных предустановок, так и пользовательских](/agenteye/images/queries.png) +![Библиотека сохранённых запросов: сетка переиспользуемых запросов, встроенных предустановок и пользовательских](/agenteye/images/queries.png) *Ваша библиотека сохранённых запросов на `//queries`: встроенные предустановки рядом с запросами, которые сохранила ваша команда.* ## Начните с предустановки, а не с пустой страницы -Вам не нужно помнить названия таблиц или писать SQL с нуля. Библиотека открывается со встроенными предустановками для вопросов, которые команды задают чаще всего, расположенными рядом с запросами, которые сохранила и назвала ваша команда. Выберите тот, который близок к тому, что вам нужно, и вы будете на полпути к ответу. +Вам не нужно помнить названия таблиц или писать SQL с нуля. Библиотека открывается с встроенными предустановками для вопросов, которые задают команды чаще всего, размещённых рядом с запросами, которые сохранила и назвала ваша команда. Выберите один, который близок к тому, что вам нужно, и вы получите большую часть ответа. -Каждый сохранённый запрос имеет область действия организации и является общим, поэтому полезные запросы, которые пишут ваши коллеги, становятся и вашими. Назовите запрос и добавьте описание один раз, и любой в вашей организации сможет его найти, запустить или позже закрепить его результаты на панели управления. +Каждый сохранённый запрос ограничен областью организации и общий, поэтому полезные запросы, которые пишут ваши коллеги, становятся и вашими. Назовите запрос и дайте ему описание один раз, и любой в вашей организации сможет его найти, запустить или позже закрепить его результаты на панели. -Найдите его на `//queries`. +Найдите на `//queries`. -## Отредактируйте его и запустите в редакторе SQL +## Отредактируйте и запустите в SQL-редакторе -Откройте любой запрос, и он откроется в редакторе SQL, где вы сможете его изменить и сразу увидеть ответ: без экспорта, без круговорота, без ожидания помощи от кого-то другого. +Откройте любой запрос — он загрузится в SQL-редактор, где вы можете его отредактировать и сразу увидеть ответ: никакого экспорта, никаких возвратов, никакого ожидания других. -![Редактор SQL-запросов с запущенным сохранённым запросом, боковой панелью схемы и таблицей результатов](/agenteye/images/query-lab.png) +![SQL-редактор запросов, запускающий сохранённый запрос с панелью схемы и сеткой живых результатов](/agenteye/images/query-lab.png) -*Редактор SQL: ваш запрос слева, боковая панель схемы, чтобы вы никогда не угадывали название колонки, и таблица результатов снизу.* +*SQL-редактор: ваш запрос слева, панель схемы, чтобы вы никогда не угадывали название столбца, и сетка живых результатов внизу.* -- **Боковая панель схемы** показывает таблицы аналитики и их колонки, чтобы вы могли составить запрос без поиска названий полей. -- **Таблица результатов в реальном времени** возвращает строки в момент запуска, поэтому вы итерируете за секунды вместо того, чтобы гадать и пересчитывать. -- **Только чтение по умолчанию.** Запросы выполняются для хранилища событий и проверяются на сервере: разрешены только операторы `SELECT` и `WITH` с тайм-аутом и ограничением на количество строк. Поисковый запрос никогда не может изменить ваши данные, и вышедший из-под контроля запрос будет остановлен за вас. +- **Панель схемы** раскладывает таблицы аналитики и их столбцы, чтобы вы могли составить запрос без поиска названий полей. +- **Сетка живых результатов** возвращает строки в момент запуска, так что вы итерируете за секунды, а не угадываете снова и снова. +- **Защита от записи по умолчанию.** Запросы выполняются против вашего хранилища событий и проверяются на сервере: разрешены только statements `SELECT` и `WITH`, с таймаутом statement и ограничением по строкам. Исследовательский запрос никогда не может изменить ваши данные, и неправильный запрос будет остановлен за вас. -Довольны результатом? Сохраните его обратно в библиотеку, чтобы вся команда его унаследовала, или закрепите его результат на панели управления как линейную диаграмму, столбчатую диаграмму, площадную диаграмму или круговую диаграмму. +Доволены результатом? Сохраните обратно в библиотеку, чтобы вся команда получила его, или закрепите его вывод на панель как линейный, столбчатый, площадной или круговой элемент. -## Запускайте их из терминала или позвольте помощнику их написать +## Запускайте из терминала или позвольте ассистенту их написать -Те же сохранённые запросы следуют за вами, где бы вы ни работали: +Те же сохранённые запросы следуют за вами везде, где вы работаете: -- **Из терминала.** CLI `agenteye` выводит список, запускает и сохраняет те же самые запросы, поэтому вы можете вставить результат в скрипт, интегрировать его в CI или передать кодирующему агенту. +- **Из терминала.** CLI `agenteye` выводит список, запускает и сохраняет те же самые запросы, чтобы вы могли вставить результат в скрипт, подключить в CI или передать агенту кодирования. ```bash -agenteye query list # те же сохранённые запросы из вашего терминала +agenteye query list # те же сохранённые запросы, из вашего терминала agenteye query run errs --arg prod # запустить один и вывести строки (добавьте --json для передачи) ``` См. [CLI и агенты](/ru/agenteye/cli-and-agents) для полного набора команд. -- **От AI-помощника.** Не уверены, как сформулировать SQL? Спросите встроенного в панель [AI-помощника](/ru/agenteye/assistant) на простом английском языке, и он напишет запрос и сохранит его в вашу библиотеку за вас. +- **От AI ассистента.** Не уверены, как сформулировать SQL? Спросите встроенного в панель [AI ассистента](/ru/agenteye/assistant) на простом английском, и он составит запрос и сохранит его в вашу библиотеку. -Запуск сохранённого запроса контролируется разрешением `queries:run`, отделённым от разрешений на создание или удаление запросов, поэтому вы можете предоставить доступ на чтение без разрешения переписывать библиотеку. +Запуск сохранённого запроса контролируется разрешением `queries:run`, отделённым от разрешений на создание или удаление запросов, так что вы можете предоставить доступ на чтение без позволения всем переписывать библиотеку. ## Связанное -- [Панели управления](/ru/agenteye/dashboards): закрепляйте результаты запросов на общих диаграммах уровня организации. -- [AI-помощник](/ru/agenteye/assistant): задавайте вопросы на простом английском языке и получайте запрос в ответ. +- [Панели](/ru/agenteye/dashboards): закрепляйте результаты запросов в общих, масштабируемых организацией диаграммах. +- [AI ассистент](/ru/agenteye/assistant): задавайте вопросы на простом английском и получайте запрос в ответ. - [CLI и агенты](/ru/agenteye/cli-and-agents): запускайте и сохраняйте те же запросы из вашего терминала. \ No newline at end of file diff --git a/docs/ru/agenteye/security.mdx b/docs/ru/agenteye/security.mdx index 9028e2a1..660d6c73 100644 --- a/docs/ru/agenteye/security.mdx +++ b/docs/ru/agenteye/security.mdx @@ -1,68 +1,68 @@ --- title: "Безопасность" -description: "Failproof AI Observability разработана для работы рядом с вашими production агентами, что означает, что она видит ваши промпты, входные данные инструментов и результаты их работы." +description: "Failproof AI Observability разработана для интеграции с вашими production-агентами, что означает, что она имеет доступ к вашим промптам, входам инструментов и выходам." --- -Failproof AI Observability разработана для работы рядом с вашими production агентами, что означает, что она видит ваши промпты, входные данные инструментов и результаты их работы. На этой странице объясняется, как она хранит данные в изолированном виде, под контролем и в ваших руках. Если вы оцениваете Failproof AI Observability для проверки безопасности, начните отсюда. +Failproof AI Observability разработана для интеграции с вашими production-агентами, что означает, что она имеет доступ к вашим промптам, входам инструментов и выходам. На этой странице объясняется, как она обеспечивает изоляцию данных, их контроль и остаются в ваших руках. Если вы оцениваете Failproof AI Observability для проверки безопасности, начните отсюда. --- ## Ваши данные остаются в вашей среде -Failproof AI Observability развернута локально. События, промпты, ответы модели и аналитика хранятся в ваших собственных базах данных, в вашей собственной среде. Ничто не отправляется на сторонний SaaS для хранения, и ваши данные остаются в вашем облачном аккаунте. +Failproof AI Observability размещается на вашей стороне. События, промпты, ответы модели и аналитика хранятся в ваших собственных базах данных, в вашей собственной среде. Ничего не отправляется на стороннее SaaS-решение для хранения, и ваши данные остаются в вашем облачном аккаунте. --- -## Изоляция между тенантами +## Изоляция тенантов -Один экземпляр Failproof AI Observability может размещать множество организаций, каждая из которых изолирована на уровне хранилища — это обеспечивается самой базой данных, а не просто интерфейсом: +Один экземпляр Failproof AI Observability может размещать множество организаций, и каждая изолирована на уровне хранилища — это обеспечивается базой данных, а не только интерфейсом: -- Операционные данные организации (пользователи, ключи, панели управления, сохранённые запросы) относятся только к этой организации, и межорганизационное чтение блокируется самой базой данных. -- Каждое поступившее событие отмечается организацией-владельцем, поэтому события одной организации никогда не могут быть прочитаны другой. +- Операционные данные организации (пользователи, ключи, дашборды, сохранённые запросы) привязаны к этой организации, и кросс-организационные чтения блокируются самой базой данных. +- Каждое поступившее событие помечается организацией-владельцем, поэтому события одной организации никогда не могут быть прочитаны другой. -Каждый маршрут панели управления привязан к организации (`//…`). +Каждый маршрут дашборда находится в области видимости слага организации (`//…`). --- ## Вход в систему -Failproof AI Observability использует вход без пароля, на основе электронной почты. Пароля нет, поэтому нечего фишировать или раскрывать. Пользователь запрашивает одноразовый код (или однокликовую волшебную ссылку), который отправляется ему по электронной почте и быстро истекает. Вход контролируется **списком разрешённых адресов**: только те адреса электронной почты (или домены), которые вы разрешите, смогут пройти проверку подлинности. +Failproof AI Observability использует беспарольный вход на основе электронной почты. Здесь нет пароля, который можно украсть или перехватить. Пользователь запрашивает одноразовый код (или ссылку одного клика), который отправляется ему по электронной почте и быстро истекает. Вход в систему защищён с помощью **списка разрешений**: только адреса электронной почты (или домены), которые вы разрешите, смогут пройти аутентификацию. ![Экран входа Failproof AI Observability, который отправляет одноразовый код на вашу электронную почту](/agenteye/images/login.png) --- -## Ограниченный доступ с помощью API ключей +## Ограниченный доступ с помощью API-ключей -Каждый клиент проходит проверку подлинности с помощью API ключа, который имеет детализированные разрешения минимальных привилегий. Сборщику нужно только `events:add`; ключ панели управления или помощника может быть только для чтения; деструктивные действия (удаление, переполучение) — это отдельные разрешения, которые вы решаете включить. +Каждый клиент аутентифицируется с помощью API-ключа с детализированными разрешениями наименьших привилегий. Сборщик требует только `events:add`; ключ дашборда или помощника может быть только для чтения; деструктивные действия (удаление, регенерация) — это отдельные разрешения, которые вы выбираете. -![Страница API ключей: разрешения каждого ключа, цветокодированные по областям чтения, записи и деструктивных операций](/agenteye/images/api-keys.png) +![Страница API-ключей: разрешения каждого ключа, обозначенные цветом по областям чтения, записи и деструктивных операций](/agenteye/images/api-keys.png) -Сохраните начальный административный ключ для настройки и выдавайте узкие ключи для всего остального. См. [API ключи](/ru/agenteye/api-keys). +Сохраняйте административный загрузочный ключ для установки и выпускайте узкие ключи для всего остального. См. [API-ключи](/ru/agenteye/api-keys). --- -## Ассистент только для чтения с одобрением +## Помощник только для чтения с одобрением -Встроенный в панель управления [AI ассистент](/ru/agenteye/assistant) отвечает на вопросы по вашим данным, но он ограничен по замыслу: +Встроенный [AI-помощник](/ru/agenteye/assistant) в дашборде отвечает на вопросы по вашим данным, но ограничен по дизайну: -- Он **предназначен только для чтения по умолчанию**: его SQL проходит через защиту, которая допускает только запросы `SELECT`/`WITH`, однооператорные, с ограничением по строкам. -- Все, что он создаёт (сохранённый запрос, панель управления), **требует одобрения**: вы проверяете и одобряете каждую запись перед её выполнением. +- Он **только для чтения по умолчанию**: его SQL проходит через защиту, которая позволяет только запросы `SELECT`/`WITH`, однооператорные, с ограничением по строкам. +- Всё, что он создаёт (сохранённый запрос, дашборд), **требует одобрения**: вы проверяете и одобряете каждую запись перед её выполнением. - Он **никогда не может удалять**. -Таким образом, коллега может спросить, например, какие агенты дали сбой на этой неделе больше всего, и действовать на основе ответа, при этом ассистент не сможет изменить или удалить ваши данные самостоятельно. +Таким образом, коллега может спросить "какие агенты чаще всего ошибались на этой неделе?" и действовать на основе ответа, без риска того, что помощник самостоятельно изменит или удалит ваши данные. --- ## При передаче -Весь трафик передаётся по HTTPS. Вы завершаете TLS своими собственными сертификатами, поэтому трафик от сборщика к серверу и от браузера к серверу зашифрован при передаче. +Весь трафик передаётся по HTTPS. Вы завершаете TLS с собственными сертификатами, поэтому трафик от сборщика к серверу и от браузера к серверу зашифрован при передаче. --- ## Следующие шаги - [Обзор](/ru/agenteye/overview): как Failproof AI Observability работает вместе. -- [API ключи](/ru/agenteye/api-keys): ограничьте доступ для сборщика, панели управления и ассистента. -- [Наблюдаемость](/ru/agenteye/observability): что Failproof AI Observability захватывает из ваших агентов. \ No newline at end of file +- [API-ключи](/ru/agenteye/api-keys): ограничьте доступ для сборщика, дашборда и помощника. +- [Наблюдаемость](/ru/agenteye/observability): что Failproof AI Observability захватывает от ваших агентов. \ No newline at end of file diff --git a/docs/ru/agenteye/sessions.mdx b/docs/ru/agenteye/sessions.mdx index 00e4b67b..c2cf39b1 100644 --- a/docs/ru/agenteye/sessions.mdx +++ b/docs/ru/agenteye/sessions.mdx @@ -1,57 +1,56 @@ --- title: "Сессии и граф выполнения" -description: "Каждое событие из запуска, объединённое в одну читаемую строку и представленное в виде git-подобного графа выполнения, который можно понять за секунды." +description: "Каждое событие из запуска в одной удобной строке, отображённое в виде графа выполнения в стиле git, который можно прочитать за секунды." --- +Прекратите гадать, почему запуск завершился ошибкой. Failproof AI Observability объединяет каждое событие из запуска в одну удобную строку, а затем отображает весь запуск как картинку в стиле git, которую можно прочитать за секунды. Так вы увидите ровно то, что сделал ваш агент, шаг за шагом. -Хватит гадать, почему запуск не сработал. Failproof AI Observability объединяет все события запуска в одну читаемую строку, а затем рисует весь запуск как git-подобное изображение, которое можно прочитать за секунды. Так вы видите в точности, что сделал ваш агент, шаг за шагом. +![Список сессий: одна строка на запуск, по окружениям и агентам, с индикаторами статуса и значками оценок](/agenteye/images/sessions-list.png) -![Список сессий: одна строка на запуск, в разных окружениях и агентах, с индикаторами статуса и значками оценки](/agenteye/images/sessions-list.png) - -*Одна строка на запуск: индикатор статуса показывает, как закончился запуск с первого взгляда, а значок оценки появляется, когда подключен оценивающий модуль.* +*Одна строка на запуск: индикатор статуса показывает, как завершился запуск, а значок оценки появляется после подключения оценщика.*
- +
-*Отслеживание агента: следите за одним запуском шаг за шагом, от цели к инструментам и к финальному ответу.* +*Трассировка агента: следуйте за одним запуском шаг за шагом, от цели до инструментов и финального ответа.* --- -## Видьте каждый запуск с первого взгляда +## Увидьте каждый запуск с первого взгляда -Сырой журнал событий — это правда каждого шага, но когда у вас есть тысячи шагов в десятках запусков, вам нужен запуск, а не шаг. На странице Sessions все события запуска объединяются в одну строку, поэтому день активности превращается в просканируемый список вместо потока данных. +Необработанный журнал событий — источник истины каждого шага, но когда у вас тысячи шагов в десятках запусков, вам нужен запуск, а не шаг. Страница сессий объединяет все события запуска в одну строку, так что день активности превращается в сканируемый список вместо потока информации. -Каждая строка содержит индикатор статуса, поэтому неудачный запуск выделяется среди здоровых задолго до того, как вы что-нибудь нажмёте. Отфильтруйте по диапазону дат, окружению, агенту или сессии, чтобы перейти от «всего» к «нужному мне запуску» в несколько кликов. +Каждая строка содержит индикатор статуса, поэтому неудачный запуск выделяется среди здоровых запусков ещё до того, как вы что-нибудь нажмёте. Фильтруйте по диапазону дат, окружению, агенту или сессии, чтобы перейти от «всего» к «интересующему меня запуску» в пару кликов. -Когда вы подключите оценивающий модуль, каждый завершённый запуск автоматически получит оценку, и её последнее значение появится на строке в виде значка. Вы можете отфильтровать по любому диапазону оценок, поэтому «покажи мне все низкооценённые запуски в prod на этой неделе» становится фильтром, а не ручной проверкой. Пока вы его не настроите, сессии всё равно записывают полный запуск — они просто ещё не имеют оценки. +После подключения оценщика каждый завершённый запуск получает оценку автоматически, и его последняя оценка отображается на строке значком. Вы можете фильтровать по любому диапазону оценок, так что «показать мне все запуски с низкой оценкой в продакшене на этой неделе» — это фильтр, а не ручная проверка. Пока вы не установили оценщик, сессии по-прежнему захватывают полный запуск; они просто ещё не содержат оценку. --- ## Прочитайте весь запуск как картинку -![Git-подобный граф выполнения сессии рядом с временной шкалой событий, с панелью разбора инструментов, моделей и hooks](/agenteye/images/session-detail.png) +![Граф выполнения в стиле git сессии рядом с временной шкалой событий, с панелью разбора инструментов, моделей и хуков](/agenteye/images/session-detail.png) -*Граф выполнения (слева) находится рядом с временной шкалой событий; правая панель показывает инструменты, модели, hooks и расход токенов для запуска.* +*Граф выполнения (слева) находится рядом с временной шкалой событий; правая панель показывает разбор инструментов, моделей, хуков и трат токенов для запуска.* -Кликните на любую сессию, чтобы открыть её граф выполнения: git-подобное представление того, как агенты, инструменты, hooks и вызовы моделей разворачивались во времени. Параллельные под-агенты ветвятся на свои линии, поэтому вы видите, какая работа выполнялась одновременно, какой под-агент завис и где запуск сошёл с курса, не перечитывая логи в уме. +Кликните по любой сессии, чтобы открыть её граф выполнения: представление в стиле git того, как агенты, инструменты, хуки и вызовы моделей развивались во времени. Параллельные подагенты переходят на свои собственные дорожки, так что вы можете увидеть, какие работы выполнялись одновременно, какой подагент завис и где запуск сошёл с курса, без необходимости мысленно проигрывать это из стены логов. -Правая панель даёт вам разбор по запуску: какие инструменты и модели запустились, какие hooks сработали и сколько токенов потратил запуск. Это ответ на вопросы «почему этот запуск стоил так дорого?» или «какой инструмент работает медленно?» прямо рядом с графом, который это вызвал. +Правая панель даёт вам разбор по запускам: какие инструменты и модели выполнялись, какие хуки срабатывали и сколько токенов потратил запуск. Это ответ на вопросы «почему этот запуск стоил так дорого?» или «какой инструмент медленный?», находящийся прямо рядом с графом, который это вызвал. -Отдельные события имеют адресацию, поэтому вы можете дать кому-то ссылку на один момент вместо «сессия, примерно на две трети вниз». Скопируйте ссылку любого события или следите за ней из [аудита](/ru/agenteye/audits) или ошибки, и сессия откроется с выбранным событием и прокруткой к нему. Это работает даже для очень длинных запусков: временная шкала загружает ограниченное окно для вашего браузера, а ссылка, указывающая за пределы этого окна, всё равно найдёт его событие вместо того, чтобы вернуть вас в начало. Если событие устарело из вашего окна хранения, страница скажет вам об этом вместо того, чтобы молча ничего не выбирать. +Отдельные события имеют адреса, поэтому вы можете отправить кому-нибудь ссылку на один момент вместо «сессия, примерно две трети вниз». Скопируйте ссылку с любого события или следуйте ей из результата [аудита](/ru/agenteye/audits) или ошибки, и сессия откроется с этим событием выбранным и прокруткой до него. Это работает и для очень длинных запусков: временная шкала загружает ограниченное окно ради вашего браузера, и ссылка, указывающая за границы этого окна, всё равно найдёт своё событие вместо того, чтобы начать с начала. Если событие вышло за границы окна хранения, страница вам об этом скажет вместо того, чтобы молча ничего не выбирать. --- -## Где его найти +## Где это найти -Каждая страница приборной панели относится к вашей организации (`//…`). Sessions находится в разделе **Observe** на левой боковой панели рядом с Events, с фильтрами диапазона дат, окружения, агента и сессии в верхней части списка. Каждая строка находится в одном клике от её полного графа выполнения. +Каждая страница панели инструментов ограничена вашей организацией (`//…`). Сессии находятся в разделе **Observe** на левой боковой панели, рядом с Events, с фильтрами по диапазону дат, окружению, агенту и сессии в верхней части списка. Каждая строка — один клик от полного графа выполнения. -Чтобы включить значки оценок и фильтрацию по диапазону оценок, подключите оценивающий модуль: см. [Evaluations](/ru/agenteye/evaluations). +Чтобы включить значки оценок и фильтрацию по диапазону оценок, подключите оценщик: см. [Evaluations](/ru/agenteye/evaluations). --- ## Связанное -- [Event stream](/ru/agenteye/event-stream): сырой, пошаговый журнал, из которого объединяются все сессии. -- [Evaluations](/ru/agenteye/evaluations): подключите оценивающий модуль, чтобы каждый запуск получил значок оценки, по которому можно фильтровать. -- [Telemetry](/ru/agenteye/telemetry): как запуски попадают из вашего агента в эти сессии. \ No newline at end of file +- [Event stream](/ru/agenteye/event-stream): необработанный журнал событий по шагам, из которого свёрнуты все сессии. +- [Evaluations](/ru/agenteye/evaluations): подключите оценщик, чтобы каждый запуск получил значок оценки, по которому можно фильтровать. +- [Telemetry](/ru/agenteye/telemetry): как запуски из вашего агента попадают в эти сессии. \ No newline at end of file diff --git a/docs/ru/agenteye/telemetry.mdx b/docs/ru/agenteye/telemetry.mdx index 754f6bf1..5194cf8c 100644 --- a/docs/ru/agenteye/telemetry.mdx +++ b/docs/ru/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- title: "Метрики производительности" -description: "Заметьте в тот же миг, когда модели, инструменты или хуки замедляются или начинают потреблять ресурсы, и перехватите скачок хвостовой задержки до того, как это почувствуют пользователи." +description: "Видите в реальном времени, когда ваши модели, инструменты или хуки замедляются или увеличивают счёт, и перехватите скачок хвостовой задержки до того, как его почувствуют ваши пользователи." --- -Заметьте в тот же миг, когда модели, инструменты или хуки замедляются или начинают потреблять ресурсы, и перехватите скачок хвостовой задержки до того, как это почувствуют пользователи. Три отдельные страницы превращают сырые временные данные в p50, p95 и p99, которые можно оценить с первого взгляда. +Видите в реальном времени, когда ваши модели, инструменты или хуки замедляются или увеличивают счёт, и перехватите скачок хвостовой задержки до того, как его почувствуют ваши пользователи. Три отдельные страницы превращают сырые временные данные в p50, p95 и p99, которые вы можете прочитать с одного взгляда. ![Страница Models с тепловой картой задержки, полосой процентилей и показателями токенов, стоимости и размера контекстного окна для каждой модели](/agenteye/images/models.png) -*Страница Models: тепловая карта задержки, полоса процентилей и показатели токенов, расчётная стоимость и коэффициент заполнения контекстного окна.* +*Страница Models: тепловая карта задержки, полоса процентилей и показатели токенов, прогнозируемой стоимости и заполнения контекстного окна для каждой модели.* -## Не позволяйте средним значениям скрывать ваши худшие прогоны +## Перестаньте позволять средним значениям скрывать ваши худшие запуски -Средняя задержка — утешительна и бесполезна: она скрывает один из пятидесяти вызовов, который зависает и будит дежурного в 2 часа ночи. Страницы Models, Tools и Hooks этого не делают. Каждая имеет одинаковую структуру, поэтому вы разбираетесь один раз: +Среднее значение задержки утешает и бесполезно: оно сглаживает один из пятидесяти вызовов, который зависает и будит вашего дежурного в 2 ночи. Страницы Models, Tools и Hooks не делают этого. Каждая имеет одинаковую структуру, поэтому вы учитесь один раз: -- **24-позиционная мини-диаграмма** для тренда с первого взгляда: становится ли хуже? -- **Полоса жизненно важных показателей** с задержками p50, p95 и p99, чтобы типичный прогон и хвостовая часть сидели рядом. -- **Тепловая карта задержки**, 24 временных интервала на корзины задержек, показывающая, *когда* кластеризовались медленные вызовы. -- **Полоса процентилей**: линия p50 с затемнёнными лентами p25 до p75 и p10 до p90 и точками p99, чтобы разброс оставался видимым вместо усреднения. +- **24-ячеечная микросхема** для тренда с одного взгляда: становится ли это хуже? +- **полоса жизненных показателей** с задержкой p50, p95 и p99, чтобы типичный запуск и хвост были рядом. +- **тепловая карта задержки**, 24 временных ячейки по бакетам задержки, которая показывает, *когда* медленные вызовы кластеризовались. +- **полоса процентилей**: линия p50 с затемнёнными лентами p25 к p75 и p10 к p90 и точками p99, чтобы разброс оставался видимым вместо того, чтобы быть усреднённым. -Общий перекрестие при наведении связывает тепловую карту и полосу, поэтому скачок хвоста выравнивается во времени на обоих вместо того, чтобы скрываться за одной средней линией. Найдите все три страницы в разделе **observe** вашей панели управления, каждая ограничена вашей организацией и отфильтрована по диапазону дат, окружению, агенту и сеансу. +Общий перекрестник при наведении связывает тепловую карту и полосу, поэтому скачок хвоста выравнивается по времени в обеих, вместо того чтобы скрываться за единственной средней линией. Найдите все три страницы в разделе **observe** вашей панели инструментов, каждая охватывает вашу организацию и фильтруется по диапазону дат, окружению, агенту и сессии. -## Models: узнайте точно, что каждая модель вам стоит +## Models: видите точно, что каждая модель вас стоит -Страница Models (показана выше) отвечает на два вопроса, которые всегда возникают при получении счёта: какая модель и сколько. Поверх общего представления задержки она добавляет **потребление токенов для каждой модели**, **расчётную стоимость** и **заполнение контекстного окна**, чтобы неконтролируемый рост приглашения и предстоящее сжатие были видны до того, как они вас застанут врасплох. +Страница Models (показана выше) ответит на два вопроса, которые всегда возникают при счёте: какая модель и сколько. В дополнение к общему виду задержки она добавляет **потребление токенов для каждой модели**, **прогнозируемую стоимость** и **заполнение контекстного окна**, поэтому неконтролируемый рост подсказки и предстоящая компактификация видны до того, как вас застигнут врасплох. -Failproof AI Observability автоматически распознаёт обычные ID моделей. Если окно выглядит неправильно или вы используете собственную приватную модель, исправьте это или добавьте её в разделе **Settings**, в **model context windows**, и показатели заполнения будут следовать за изменениями. +Failproof AI Observability автоматически распознаёт общие ID моделей. Если окно выглядит неправильно, или вы используете собственную приватную модель, исправьте его или добавьте его в **Settings**, в **model context windows**, и показания заполнения будут следовать. ## Tools: отличите медленное от сломанного -Вызов инструмента может быть медленным или тихо не работать, и вы хотите узнать, что именно происходит, за секунды, а не после раскопок в логах. +Вызов инструмента может быть медленным, или он может тихо терпеть неудачу, и вы хотите узнать, какой именно за секунды, а не после того, как просеяли логи. ![Страница Tools с общей тепловой картой задержки и полосой процентилей рядом с разбивкой по успехам и ошибкам и полосой распределения инструментов](/agenteye/images/tools.png) -*Страница Tools: одна и та же тепловая карта и полоса процентилей, плюс разбивка по успехам и ошибкам и полоса распределения инструментов.* +*Страница Tools: та же тепловая карта и полоса процентилей, плюс разбивка по успехам и ошибкам и полоса распределения инструментов.* -Рядом с общим представлением задержки страница Tools добавляет **разбивку по успехам и ошибкам** и **полосу распределения инструментов**, чтобы вы видели с первого взгляда, какими инструментами вы больше всего пользуетесь и какие съедают ваш бюджет ошибок. +Рядом с общим видом задержки страница Tools добавляет **разбивку по успехам и ошибкам** и **полосу распределения инструментов**, поэтому вы видите с одного взгляда, на какие инструменты вы полагаетесь больше всего и какие поедают ваш бюджет ошибок. -## Hooks: точно определите нужный хук и триггер +## Hooks: определите точный хук и событие срабатывания -Когда жизненный цикл хука замедляет прогон, фраза "хуки медленные" — это не то, на что вы можете действовать. Страница Hooks доставляет вас к тому, что имеет значение. +Когда хук жизненного цикла замедляет запуск, «хуки медленные» — это не то, что вы можете исправить. Страница Hooks приводит вас к тому, который имеет значение. -![Страница Hooks с задержкой, разбитой по имени хука и событию-триггеру поверх общей тепловой карты и полосы процентилей](/agenteye/images/hooks.png) -*Страница Hooks: задержка разбита по имени хука и событию-триггеру.* +![Страница Hooks с задержкой, разбитой по имени хука и событию срабатывания, поверх общей тепловой карты и полосы процентилей](/agenteye/images/hooks.png) +*Страница Hooks: задержка, разбитая по имени хука и событию срабатывания.* -На той же тепловой карте задержки и полосе процентилей страница Hooks разбивает активность по **имени хука** и **событию-триггеру**, чтобы вы сосредоточились на одном хуке и одном событии, требующих внимания. +На той же тепловой карте задержки и полосе процентилей страница Hooks разбивает активность по **имени хука** и **событию срабатывания**, чтобы вы приземлились на единственный хук и единственное событие, которое требует внимания. ## Связанное -- [Event stream](/ru/agenteye/event-stream): живая, цветовая кодировка всех событий. -- [Sessions](/ru/agenteye/sessions): свёртывает события в одну строку за прогон и открывает его граф выполнения. -- [Error tracking](/ru/agenteye/error-tracking): единая поверхность сортировки для всего, что панель управления отмечает красным. -- [Dashboards](/ru/agenteye/dashboards): сводные представления для всего вашего флота. \ No newline at end of file +- [Event stream](/ru/agenteye/event-stream): живой цветной след каждого события. +- [Sessions](/ru/agenteye/sessions): сводит события в одну строку на запуск и открывает его граф выполнения. +- [Error tracking](/ru/agenteye/error-tracking): одна триажная поверхность для всего, что панель инструментов закрашивает красным. +- [Dashboards](/ru/agenteye/dashboards): сводные представления по всему вашему флоту. \ No newline at end of file diff --git a/docs/ru/architecture.mdx b/docs/ru/architecture.mdx index 3ce44000..7a5b07a8 100644 --- a/docs/ru/architecture.mdx +++ b/docs/ru/architecture.mdx @@ -1,11 +1,11 @@ --- --- title: Архитектура -description: "Как внутри работают обработчик хука, загрузка конфигурации и оценка политик" +description: "Как внутренне работают обработчик хука, загрузка конфигурации и оценка политик" icon: sitemap --- -Этот документ объясняет, как работает failproofai изнутри: как система хуков перехватывает вызовы инструментов агента, как загружается и объединяется конфигурация, как вычисляются политики и как приборная панель отслеживает активность агента. +В этом документе объясняется, как failproofai работает внутренне: как система хуков перехватывает вызовы инструментов агента, как загружается и объединяется конфигурация, как оцениваются политики и как панель мониторинга отслеживает активность агента. --- @@ -13,10 +13,10 @@ icon: sitemap failproofai состоит из двух независимых подсистем: -1. **Обработчик хука** — быстрый CLI-подпроцесс, который Claude Code вызывает при каждом вызове инструмента агентом. Вычисляет политики и возвращает решение. -2. **Монитор агента (приборная панель)** — веб-приложение Next.js для мониторинга сеансов агента и управления политиками. +1. **Обработчик хука** — быстрый подпроцесс CLI, который Claude Code вызывает при каждом вызове инструмента агента. Оценивает политики и возвращает решение. +2. **Монитор агента (Dashboard)** — веб-приложение Next.js для мониторинга сеансов агента и управления политиками. -Обе подсистемы используют одни и те же файлы конфигурации в `~/.failproofai/` и в директории `.failproofai/` проекта, но запускаются как отдельные процессы и взаимодействуют только через файловую систему. +Обе подсистемы используют общие файлы конфигурации в `~/.failproofai/` и в директории `.failproofai/` проекта, но работают как отдельные процессы и взаимодействуют только через файловую систему. --- @@ -24,7 +24,7 @@ failproofai состоит из двух независимых подсисте ### Интеграция с Claude Code -Когда вы запускаете `failproofai policies --install`, в `~/.claude/settings.json` записываются записи вроде этой: +Когда вы выполняете `failproofai policies --install`, команда записывает записи вроде этой в `~/.claude/settings.json`: ```json { @@ -45,7 +45,7 @@ failproofai состоит из двух независимых подсисте } ``` -Claude Code затем вызывает `failproofai --hook PreToolUse` как подпроцесс перед каждым вызовом инструмента, передавая JSON-полезную нагрузку на stdin. +Затем Claude Code вызывает `failproofai --hook PreToolUse` как подпроцесс перед каждым вызовом инструмента, передавая JSON-полезную нагрузку на stdin. ### Формат полезной нагрузки @@ -63,7 +63,7 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как Для событий `PostToolUse` полезная нагрузка также содержит `tool_result` с выходом инструмента. -Обработчик устанавливает лимит stdin в 1 МБ. Полезные нагрузки, превышающие этот лимит, отбрасываются и все политики неявно разрешают операцию. +Обработчик соблюдает ограничение stdin в 1 МБ. Полезные нагрузки, превышающие это, отбрасываются и все политики неявно разрешают операцию. ### Формат ответа @@ -97,7 +97,7 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как **Instruct события Stop:** - Код выхода: `2` -- Причина написана в stderr (не stdout) +- Причина записана в stderr (не stdout) **Allow:** - Код выхода: `0` @@ -105,7 +105,7 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как **Allow с сообщением:** -`allow(message)` позволяет политике отправить информационный контекст обратно в Claude, даже когда операция разрешена. Обработчик хука записывает следующий JSON в **stdout** (не в файл конфигурации — это ответ обработчика Claude Code, как и ответы deny и instruct выше): +`allow(message)` позволяет политике отправить информационный контекст обратно в Claude даже когда операция разрешена. Обработчик хука записывает следующий JSON в **stdout** (не в файл конфигурации — это ответ обработчика на Claude Code, как и ответы deny и instruct выше): ```json // Записано в stdout процессом обработчика хука @@ -116,8 +116,8 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` - Код выхода: `0` (операция разрешена) -- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются переводами строк в одну строку `additionalContext` -- Если ни одна политика не предоставляет сообщение, stdout пуст (как и раньше) +- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются с переводами строк в одну строку `additionalContext` +- Если ни одна политика не предоставляет сообщение, stdout пуст (как раньше) ### Конвейер обработки @@ -125,63 +125,63 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как ```text stdin JSON - → разбор полезной нагрузки (макс. 1 МБ) - → извлечение метаданных сеанса (session_id, cwd, tool_name, tool_input и т.д.) - → readMergedHooksConfig(cwd) ← объединение конфигурации проекта + локальной + глобальной - → регистрация включенных встроенных политик с разрешенными параметрами + → разбор полезной нагрузки (макс 1 МБ) + → извлечение метаданных сеанса (session_id, cwd, tool_name, tool_input, etc.) + → readMergedHooksConfig(cwd) ← объединяет конфиг проекта + локальный + глобальный + → регистрация включённых встроенных политик с разрешёнными параметрами → загрузка пользовательских политик из customPoliciesPath (если установлено) - → регистрация пользовательских политик в реестре политик - → вычисление всех политик (встроенные первыми, затем пользовательские) + → регистрация пользовательских политик в реестр политик + → оценка всех политик (встроенные первыми, потом пользовательские) → первый deny прерывает выполнение → решения instruct накапливаются → сообщения allow накапливаются - → запись решения JSON в stdout + → запись JSON решения в stdout → сохранение события в ~/.failproofai/hook-activity/current.jsonl → выход ``` -Весь процесс выполняется менее чем за 100 мс для типичных полезных нагрузок без LLM-вызовов. +Весь процесс занимает менее 100 мс для типичных полезных нагрузок без вызовов LLM. --- ## Загрузка конфигурации -`src/hooks/hooks-config.ts` реализует загрузку конфигурации в три области видимости. +`src/hooks/hooks-config.ts` реализует загрузку конфигурации с тремя областями видимости. ```text -[1] {cwd}/.failproofai/policies-config.json ← проект (высший приоритет) -[2] {cwd}/.failproofai/policies-config.local.json ← локальная -[3] ~/.failproofai/policies-config.json ← глобальная (низший приоритет) +[1] {cwd}/.failproofai/policies-config.json ← проект (наивысший приоритет) +[2] {cwd}/.failproofai/policies-config.local.json ← локальный +[3] ~/.failproofai/policies-config.json ← глобальный (наименьший приоритет) ``` Логика объединения: -- `enabledPolicies` — дедублицированное объединение всех трех файлов -- `policyParams` — ключ для каждой политики, первый файл, который определяет его, побеждает полностью -- `customPoliciesPath` — первый файл, который определяет его, побеждает -- `llm` — первый файл, который определяет его, побеждает +- `enabledPolicies` — дедублицированное объединение по всем трём файлам +- `policyParams` — по ключу политики, первый файл, который его определит, полностью выигрывает +- `customPoliciesPath` — первый файл, который его определит, выигрывает +- `llm` — первый файл, который его определит, выигрывает -Веб-приборная панель использует `readHooksConfig()` (только глобальная) для чтения и записи, так как она не вызывается с cwd проекта. +Веб-панель использует `readHooksConfig()` (только глобальный) для чтения и записи, так как она не вызывается с cwd проекта. --- -## Вычисление политик +## Оценка политик `src/hooks/policy-evaluator.ts` выполняет политики по порядку. Для каждой политики: 1. Поиск схемы `params` политики (если она есть). -2. Чтение `policyParams[policy.name]` из объединенной конфигурации. -3. Объединение предоставленных пользователем значений поверх стандартных значений схемы для получения `ctx.params`. -4. Вызов `policy.fn(ctx)` с разрешенным контекстом. -5. Если результат — `deny`, остановиться немедленно и вернуть это решение. -6. Если результат — `instruct`, накопить сообщение и продолжить. -7. Если результат — `allow`, перейти к следующей политике. +2. Чтение `policyParams[policy.name]` из объединённой конфигурации. +3. Объединение пользовательских значений над значениями по умолчанию из схемы для получения `ctx.params`. +4. Вызов `policy.fn(ctx)` с разрешённым контекстом. +5. Если результат `deny`, остановиться немедленно и вернуть это решение. +6. Если результат `instruct`, накопить сообщение и продолжить. +7. Если результат `allow`, перейти к следующей политике. После выполнения всех политик: -- Если было возвращено какое-либо `deny`, выдать ответ deny. -- Если собраны какие-либо возвраты `instruct`, выдать один ответ instruct со всеми сообщениями, объединенными вместе. -- Иначе выдать ответ allow (пустой stdout, выход 0). +- Если был возвращён `deny`, отправить ответ deny. +- Если были собраны возвраты `instruct`, отправить единственный ответ instruct со всеми сообщениями, объединёнными вместе. +- Иначе, отправить ответ allow (пустой stdout, выход 0). --- @@ -205,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -Политики, которые принимают `params`, объявляют `PolicyParamsSchema` с типами и стандартными значениями для каждого параметра. Оценщик политик внедряет разрешенные значения в `ctx.params` перед вызовом `fn`. Функции политик читают `ctx.params` без защиты от null, так как стандартные значения всегда применяются первыми. +Политики, которые принимают `params`, объявляют `PolicyParamsSchema` с типами и значениями по умолчанию для каждого параметра. Оценка политик внедряет разрешённые значения в `ctx.params` перед вызовом `fn`. Функции политик читают `ctx.params` без проверки на null, потому что значения по умолчанию всегда применяются сначала. -Сопоставление шаблонов внутри политик использует разобранные токены команд (argv), а не сопоставление сырых строк. Это предотвращает обход путем инъекции оператора оболочки (например, шаблон для `sudo systemctl status *` не может быть обойден путем добавления `; rm -rf /` к команде). +Сопоставление с шаблоном внутри политик использует разобранные токены команды (argv), а не простое сопоставление строк. Это предотвращает обход путём внедрения оператора оболочки (например, шаблон для `sudo systemctl status *` не может быть обойден путём добавления `; rm -rf /` к команде). --- ## Пользовательские политики -`src/hooks/custom-hooks-registry.ts` реализует реестр на базе `globalThis`: +`src/hooks/custom-hooks-registry.ts` реализует реестр на основе `globalThis`: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -228,23 +228,23 @@ export function clearCustomHooks(): void { ... } // используется в `src/hooks/custom-hooks-loader.ts` загружает файл политики пользователя: -1. Чтение `customPoliciesPath` из конфигурации; пропуск если отсутствует. -2. Преобразование в абсолютный путь; проверка существования файла. -3. Переписывание всех импортов `from "failproofai"` на фактический путь dist, чтобы `customPolicies` разрешалось на тот же реестр `globalThis`. -4. Рекурсивное переписывание транзитивных локальных импортов для обеспечения совместимости ESM. -5. Запись временных файлов `.mjs` и `import()` входного файла. -6. Вызов `getCustomHooks()` для получения зарегистрированных хуков. -7. Очистка всех временных файлов в блоке `finally`. +1. Прочитать `customPoliciesPath` из конфигурации; пропустить если отсутствует. +2. Разрешить абсолютный путь; проверить, существует ли файл. +3. Переписать все импорты `from "failproofai"` на фактический путь dist так, чтобы `customPolicies` разрешался в один и тот же реестр `globalThis`. +4. Рекурсивно переписать переходные локальные импорты для обеспечения совместимости ESM. +5. Записать временные файлы `.mjs` и импортировать файл точки входа. +6. Вызвать `getCustomHooks()` для получения зарегистрированных хуков. +7. Очистить все временные файлы в блоке `finally`. -При любой ошибке (файл не найден, синтаксическая ошибка, ошибка импорта) ошибка записывается в `~/.failproofai/hook.log` и загрузчик возвращает пустой массив. Встроенные политики не затрагиваются. +При любой ошибке (файл не найден, синтаксическая ошибка, сбой импорта) ошибка регистрируется в `~/.failproofai/hook.log` и загрузчик возвращает пустой массив. Встроенные политики не затронуты. -Пользовательские политики вычисляются после всех встроенных политик. `deny` пользовательской политики все еще прерывает дальнейшие пользовательские политики (но все встроенные уже выполнены к этому времени). +Пользовательские политики оцениваются после всех встроенных политик. Deny пользовательской политики всё ещё прерывает дальнейшие пользовательские политики (но все встроенные к этому моменту уже выполнены). --- ## Логирование активности -После каждого события хука обработчик добавляет строку JSONL в `~/.failproofai/hook-activity/current.jsonl`, которая ротирует в `page--.jsonl` после достижения размера страницы: +После каждого события хука обработчик добавляет строку JSONL в `~/.failproofai/hook-activity/current.jsonl`, которая ротируется в `page--.jsonl` по достижении страницы: ```json { @@ -259,22 +259,22 @@ export function clearCustomHooks(): void { ... } // используется в } ``` -Одна строка на политику, которая приняла решение не-allow. Решения allow не логируются (чтобы файл оставался небольшим). +Одна строка на политику, которая приняла решение, отличное от allow. Решения allow не регистрируются (чтобы файл оставался небольшим). --- -## Архитектура приборной панели +## Архитектура панели -Приборная панель — это приложение **Next.js 16** с использованием App Router с React Server Components и Server Actions. +Панель — это приложение **Next.js 16**, использующее App Router с React Server Components и Server Actions. ```text app/ layout.tsx ← Корневой макет (тема, телеметрия, навигация) - projects/page.tsx ← Компонент сервера: список всех проектов Claude - project/[name]/page.tsx ← Компонент сервера: список сеансов в проекте + projects/page.tsx ← Server компонент: список всех проектов Claude + project/[name]/page.tsx ← Server компонент: список сеансов в проекте project/[name]/session/ - [sessionId]/page.tsx ← Компонент сервера: рендеринг просмотра сеанса - policies/page.tsx ← Компонент клиента: управление политиками + журнал активности + [sessionId]/page.tsx ← Server компонент: рендер средства просмотра сеанса + policies/page.tsx ← Client компонент: управление политиками + журнал активности actions/ get-hooks-config.ts ← Чтение конфигурации + список политик update-hooks-config.ts ← Включение/отключение политики @@ -282,52 +282,52 @@ app/ get-hook-activity.ts ← Разбиение на страницы/поиск в журнале активности install-hooks-web.ts ← Установка/удаление хуков из браузера api/ - download/[project]/[session]/route.ts ← Экспорт по сеансу CLI (JSONL или JSON) + download/[project]/[session]/route.ts ← Экспорт сеанса по CLI (JSONL или JSON) ``` **Поток данных:** -- Компоненты страницы вызывают `lib/projects.ts` и `lib/log-entries.ts` для прямого чтения данных проекта/сеанса из файловой системы (нет API-слоя для чтения). -- Страница политик использует Server Actions для всех изменений (переключение, обновление параметров, установка/удаление). -- Просмотр сеанса разбирает формат JSONL-транскрипта Claude и рендерит временную шкалу сообщений и вызовов инструментов. +- Компоненты страниц вызывают `lib/projects.ts` и `lib/log-entries.ts` для чтения данных проекта/сеанса прямо из файловой системы (нет слоя API для чтения). +- Страница Policies использует Server Actions для всех мутаций (включение/отключение, обновление параметров, установка/удаление). +- Средство просмотра сеанса разбирает формат JSONL транскрипта Claude и отображает временную шкалу сообщений и вызовов инструментов. -**Ключевые решения по дизайну:** +**Ключевые решения по проектированию:** -- Нет базы данных — все постоянное состояние хранится в простых файлах (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions для изменений — REST API не требуется для операций CRUD. -- React Server Components для страниц чтения — более быстрая первоначальная загрузка, отсутствие клиентского пакета для получения данных. -- Клиентские компоненты только там, где требуется интерактивность (переключатели политик, поиск в активности, просмотр журнала). +- Нет базы данных — все постоянное состояние находится в простых файлах (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions для мутаций — не требуется REST API для CRUD операций. +- React Server Components для страниц чтения — быстрая начальная загрузка, нет клиентского пакета для извлечения данных. +- Client компоненты только где нужна интерактивность (переключатели политик, поиск активности, средство просмотра журнала). --- -## Макет файлов +## Структура файлов ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI маршрутизатор (hook / dashboard / install / и т.д.) +│ └── failproofai.mjs # Маршрутизатор CLI (hook / dashboard / install / etc.) ├── src/hooks/ -│ ├── handler.ts # Конвейер события хука +│ ├── handler.ts # Конвейер событий хука │ ├── builtin-policies.ts # 39 определений политик -│ ├── policy-evaluator.ts # Двигатель выполнения политик +│ ├── policy-evaluator.ts # Механизм выполнения политик │ ├── policy-registry.ts # Регистрация и поиск политик │ ├── policy-types.ts # Интерфейсы TypeScript -│ ├── hooks-config.ts # Загрузка конфигурации в несколько областей видимости -│ ├── custom-hooks-registry.ts # Реестр хуков на базе globalThis -│ ├── custom-hooks-loader.ts # ESM-загрузчик для пользовательских JS-хуков -│ ├── manager.ts # Операции install / remove / list +│ ├── hooks-config.ts # Загрузка конфигурации с несколькими областями видимости +│ ├── custom-hooks-registry.ts # Реестр, поддерживаемый globalThis +│ ├── custom-hooks-loader.ts # Загрузчик ESM для пользовательских JS хуков +│ ├── manager.ts # операции install / remove / list │ ├── install-prompt.ts # Интерактивное приглашение выбора политики │ ├── hook-logger.ts # Логирование в hook.log │ ├── hook-activity-store.ts # Сохранение активности в hook-activity/ -│ └── llm-client.ts # LLM API клиент (для политик с AI-поддержкой) -├── app/ # Приборная панель Next.js (страницы + server actions) +│ └── llm-client.ts # Клиент API LLM (для политик на основе AI) +├── app/ # Панель Next.js (страницы + server actions) ├── lib/ # Общие утилиты │ ├── projects.ts # Перечисление проектов Claude из файловой системы -│ ├── log-entries.ts # Разбор формата Claude JSONL-транскрипта +│ ├── log-entries.ts # Разбор формата JSONL транскрипта Claude │ ├── paths.ts # Разрешение системных путей │ └── ... ├── components/ # Общие компоненты React UI -├── contexts/ # Поставщики контекста React (тема, автообновление, телеметрия) +├── contexts/ # Поставщики React контекста (тема, автообновление, телеметрия) ├── examples/ # Примеры файлов пользовательских хуков └── __tests__/ # Модульные и E2E тесты ``` \ No newline at end of file diff --git a/docs/ru/built-in-policies.mdx b/docs/ru/built-in-policies.mdx index 84313e0e..99cbad02 100644 --- a/docs/ru/built-in-policies.mdx +++ b/docs/ru/built-in-policies.mdx @@ -1,39 +1,39 @@ --- title: Встроенные политики -description: "Все 39 встроенных политик, которые перехватывают распространённые режимы отказа агентов" +description: "Все 39 встроенных политик, которые перехватывают типичные режимы отказа агентов" icon: shield --- -failproofai поставляется с 39 встроенными политиками, которые перехватывают распространённые режимы отказа агентов. Каждая политика срабатывает на определённый тип события хука и имя инструмента. Девятнадцать политик принимают параметры, позволяющие настраивать их поведение без написания кода. Пять политик рабочего процесса обеспечивают соблюдение конвейера commit → push → PR → CI перед остановкой Claude. +failproofai поставляется с 39 встроенными политиками, которые перехватывают типичные режимы отказа агентов. Каждая политика срабатывает на определённый тип события hook и имя инструмента. Девятнадцать политик принимают параметры, позволяющие вам настраивать их поведение без написания кода. Пять рабочих политик обеспечивают выполнение конвейера commit → push → PR → CI перед остановкой Claude. --- ## Обзор -Политики сгруппированы по категориям: +Политики разделены на категории: -| Категория | Политики | Тип хука | -|----------|----------|---------| -| [Опасные команды](#опасные-команды) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | -| [Инфраструктурные команды](#инфраструктурные-команды) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Секреты (санитайзеры)](#секреты-санитайзеры) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | -| [Окружение](#окружение) | block-env-files, protect-env-vars | PreToolUse | -| [Доступ к файлам](#доступ-к-файлам) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| Категория | Политики | Тип hook | +|----------|----------|-----------| +| [Опасные команды](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | +| [Команды инфраструктуры](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [Секреты (санитайзеры)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Окружение](#environment) | block-env-files, protect-env-vars | PreToolUse | +| [Доступ к файлам](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | -| [База данных](#база-данных) | warn-destructive-sql, warn-schema-alteration | PreToolUse | -| [Предупреждения](#предупреждения) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [Менеджеры пакетов](#менеджеры-пакетов) | prefer-package-manager | PreToolUse | -| [Рабочий процесс](#рабочий-процесс) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | +| [База данных](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | +| [Предупреждения](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | +| [Менеджеры пакетов](#package-managers) | prefer-package-manager | PreToolUse | +| [Рабочий процесс](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | - **`block-`** — остановить агента от продолжения. -- **`warn-`** — дать агенту дополнительный контекст, чтобы он мог самостоятельно исправиться. -- **`sanitize-`** — удалить чувствительные данные из вывода инструмента, прежде чем агент их увидит. +- **`warn-`** — дать агенту дополнительный контекст для самокоррекции. +- **`sanitize-`** — удалить конфиденциальные данные из выходных данных инструмента перед тем, как агент их увидит. ### Пространства имён -Каждая политика находится в слоте `/`. Встроенные политики принадлежат пространству имён **`failproofai/`** — например, `failproofai/sanitize-jwt`. Пространство имён предотвращает конфликты при загрузке пользовательских или сторонних политик с похожими короткими именами. +Каждая политика находится в слоте `/`. Встроенные политики принадлежат пространству имён **`failproofai/`** — например, `failproofai/sanitize-jwt`. Пространство имён предотвращает конфликты при загрузке пользовательских или сторонних политик с похожими короткими названиями. -В вашей конфигурации вы можете ссылаться на встроенную политику либо по её короткому имени, либо по полному имени; обе формы разрешаются в одну и ту же политику: +В конфигурации вы можете ссылаться на встроенную политику либо по её короткому названию, либо по полному названию; обе формы разрешают одну и ту же политику: ```json { @@ -44,38 +44,38 @@ failproofai поставляется с 39 встроенными политик } ``` -Если имя не содержит `/`, failproofai обрабатывает его как принадлежащее пространству имён по умолчанию `failproofai`. Имена, которые уже содержат `/` (например `myorg/foo`, `custom/my-hook`), остаются без изменений. +Если имя не содержит `/`, failproofai рассматривает его как принадлежащее пространству имён по умолчанию `failproofai`. Имена, которые уже содержат `/` (например `myorg/foo`, `custom/my-hook`), остаются неизменными. - **`require-`** — заблокировать событие Stop до выполнения условий. --- -Каждая политика поддерживает необязательное поле `hint` в `policyParams`. Подсказка добавляется к сообщению deny или instruct, которое видит Claude, обеспечивая практическое руководство без изменения кода политики. Работает со встроенными, пользовательскими и условными политиками. Подробнее в [Конфигурация → hint](/ru/configuration#hint-cross-cutting). +Каждая политика поддерживает необязательное поле `hint` в `policyParams`. Подсказка добавляется к сообщению отказа или инструкции, которое видит Claude, предоставляя действенное руководство без изменения кода политики. Работает со встроенными, пользовательскими и конвенционными политиками. См. [Конфигурация → hint](/ru/configuration#hint-cross-cutting) для подробностей. --- ## Опасные команды -Предотвращают запуск агентами операций, которые сложно отменить или которые могут повредить хост-систему. +Предотвратить выполнение агентами операций, которые сложно отменить или которые могут повредить хост-систему. ### `block-sudo` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любую команду `sudo` или `doas`. +**По умолчанию:** Запрещает любую команду `sudo` или `doas`. -Блокирует команду, которая запускает бинарный файл повышения привилегий **в позиции команды**. Сопоставление структурное, а не текстовое: команда разбивается на сегменты так, как это делает shell, префиксные присваивания (`FOO=bar`), перенаправления и запускающие программы с их флагами (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) отбрасываются, и полученный бинарный файл сравнивается по **базовому имени**. Поэтому `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` и `bash -c "sudo …"` всё отклоняется, а `doas` рассматривается как та же возможность под другим названием. +Блокирует команду, которая запускает бинарный файл повышения привилегий **в позиции команды**. Сопоставление является структурным, а не текстовым: команда разбивается на сегменты так, как это делает shell, префиксные присваивания (`FOO=bar`), перенаправления и запускающие программы с их флагами (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) обходятся, и полученный бинарный файл сравнивается по **базовому имени**. Таким образом, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` и `bash -c "sudo …"` все запрещены, а `doas` рассматривается как одна и та же возможность под другим именем. -Поскольку политика привязана к позиции команды, а не к появлению слова в любом месте, она **не** срабатывает на команды, которые просто его упоминают — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"` или `grep` с альтернацией, содержащей слово, выполняются нормально. +Поскольку она привязана к позиции команды, а не к появлению слова где-либо, она **не** срабатывает на команды, которые просто его упоминают — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"` или `grep` с чередованием, содержащее слово, все выполняются нормально. -Это останавливает очевидную попытку; это не закрывает класс. Агент, который может запускать произвольный shell, всё ещё может достичь повышения привилегий косвенно — через переменную (`S=sudo; $S …`), базовый 64-кодированный конвейер или оболочку скрипта на диске — потому что ни одна проверка одной строки команды не может этого отследить. Рассматривайте это как ограду от ошибок и случайного повышения привилегий, а не как граница безопасности против решительного агента. Настоящая граница должна быть реализована ниже уровня shell. +Это останавливает очевидную попытку; это не закрывает класс. Агент, который может запустить произвольный shell, всё ещё может достичь повышения привилегий косвенно — через переменную (`S=sudo; $S …`), через base64-декодированный конвейер или скрипт-обёртку на диске — потому что никакой анализ одной строки команды не может их отследить. Рассматривайте это как ограждение от ошибок и небрежного повышения привилегий, а не как границу безопасности против решительного агента. Реальная граница должна быть обеспечена ниже уровня shell. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| +|-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | Точные префиксы команд, которые разрешены. Каждая запись сопоставляется с разобранными токенами argv. | **Пример:** @@ -90,10 +90,10 @@ failproofai поставляется с 39 встроенными политик } ``` -С этой конфигурацией `sudo systemctl status nginx` разрешается, но `sudo rm /etc/hosts` отклоняется. +С такой конфигурацией `sudo systemctl status nginx` разрешена, а `sudo rm /etc/hosts` запрещена. -Шаблоны сопоставляются с разобранными токенами, а не с исходной строкой команды. Это предотвращает обход путём добавления операторов shell (например `sudo systemctl status x; rm -rf /` не соответствует `sudo systemctl status *`). +Шаблоны сопоставляются с разобранными токенами, а не с исходной строкой команды. Это предотвращает обход через добавленные операторы shell (например `sudo systemctl status x; rm -rf /` не совпадает с `sudo systemctl status *`). --- @@ -101,12 +101,12 @@ failproofai поставляется с 39 встроенными политик ### `block-rm-rf` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет `rm -rf`, `rm -fr` и похожие формы рекурсивного удаления. +**По умолчанию:** Запрещает `rm -rf`, `rm -fr` и аналогичные формы рекурсивного удаления. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| +|-------|------|---------|-------------| | `allowPaths` | `string[]` | `[]` | Пути, которые безопасно рекурсивно удалять (например `/tmp`). | **Пример:** @@ -126,50 +126,50 @@ failproofai поставляется с 39 встроенными политик ### `block-curl-pipe-sh` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет `curl | bash`, `curl | sh`, `wget | bash` и похожие шаблоны. +**По умолчанию:** Запрещает `curl | bash`, `curl | sh`, `wget | bash` и аналогичные шаблоны. -Без параметров. +Нет параметров. --- ### `block-failproofai-commands` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет команды, которые бы удалили или отключили сам failproofai (например `npm uninstall failproofai`, `failproofai policies --uninstall`). +**По умолчанию:** Запрещает команды, которые удаляют или отключают сам failproofai (например `npm uninstall failproofai`, `failproofai policies --uninstall`). -Без параметров. +Нет параметров. --- ### `block-self-pause` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет `failproofai config --pause`, что приостанавливает исполнение на сеанс. Пауза — это решение человека — агент, который может её запустить, мог бы отключить каждую другую политику одной командой. +**По умолчанию:** Запрещает `failproofai config --pause`, который приостанавливает применение политик на сессию. Паузирование — это решение человека — агент, способный её выполнить, может отключить все остальные политики одной командой. -Более узкая, чем [`block-failproofai-commands`](#block-failproofai-commands) намеренно и не охватывается ею: та политика привязана к границе команды, поэтому `npx -y failproofai config --pause` её не соответствует, и будучи широкой, её часто отключают, чтобы агенты могли запускать `failproofai audit`. `--resume` и `--status` разрешены — ни один из них не удаляет исполнение. +Уже по дизайну уже, чем [`block-failproofai-commands`](#block-failproofai-commands) и не охватывается им: эта политика привязана к границе команды, поэтому `npx -y failproofai config --pause` не совпадает с ней, и, будучи широкой, она часто отключается, чтобы агенты могли запустить `failproofai audit`. `--resume` и `--status` разрешены — ни один не удаляет применение политик. -Это останавливает прямую попытку, а не весь класс: агент всё ещё может достичь того же состояния через алиас или оболочку скрипта. Полное закрытие требует, чтобы пауза была недоступна из вызова инструмента вообще. +Это останавливает прямую попытку, а не весь класс: агент всё ещё может достичь того же состояния через алиас или скрипт-обёртку. Полное её закрытие требует, чтобы пауза была недоступна из вызова инструмента вообще. -Без параметров. +Нет параметров. --- -## Инфраструктурные команды +## Команды инфраструктуры -Остановить агентов кодирования от запуска инфраструктурных CLI или срабатывания конвейеров CI/CD. Все политики в этой категории **opt-in** (`defaultEnabled: false`) — агенты, которым законно нужно вызывать `kubectl`, `terraform` и т. д., не будут нарушены, если вы не включите политику. При включении каждый вызов сопоставленного CLI отклоняется, если только команда не соответствует записи в `allowPatterns`. +Остановить кодирующих агентов от запуска инфраструктурных CLI или запуска конвейеров CI/CD. Все политики в этой категории являются **необязательными** (`defaultEnabled: false`) — агенты, которые законно должны вызывать `kubectl`, `terraform` и т. д., не будут нарушены, если вы не включите политику. При включении каждый вызов согласованного CLI запрещён, если команда не совпадает с записью в `allowPatterns`. -Грамматика шаблонов та же, что в [`block-sudo`](#block-sudo): токены сопоставляются с разобранными argv, `*` — подстановочный знак для одного токена, и любая команда, содержащая автономный оператор shell (`&&`, `||`, `|`, `;`) или токен с встроенными метасимволами shell, отклоняется перед сопоставлением списка разрешений, чтобы предотвратить обход впрыска. +Грамматика шаблона такая же, как в [`block-sudo`](#block-sudo): токены сопоставляются с разобранными argv, `*` — подстановочный символ для одного токена, и любая команда, содержащая автономный оператор shell (`&&`, `||`, `|`, `;`) или токен с встроенными метасимволами shell, отклоняется перед сопоставлением со списком разрешений для предотвращения обходов инъекций. ### `block-kubectl` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов `kubectl`. +**По умолчанию:** Запрещает любой вызов `kubectl`. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд kubectl, которые разрешены. | +|-------|------|---------|-------------| +| `allowPatterns` | `string[]` | `[]` | Разрешённые префиксы команд kubectl. | **Пример:** @@ -183,20 +183,20 @@ failproofai поставляется с 39 встроенными политик } ``` -С этой конфигурацией `kubectl get pods` разрешается, но `kubectl apply -f deploy.yaml` отклоняется. +С такой конфигурацией `kubectl get pods` разрешена, но `kubectl apply -f deploy.yaml` запрещена. --- ### `block-terraform` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов `terraform` или `tofu` (OpenTofu). +**По умолчанию:** Запрещает любой вызов `terraform` или `tofu` (OpenTofu). **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд terraform/tofu, которые разрешены. | +|-------|------|---------|-------------| +| `allowPatterns` | `string[]` | `[]` | Разрешённые префиксы команд terraform/tofu. | **Пример:** @@ -215,13 +215,13 @@ failproofai поставляется с 39 встроенными политик ### `block-aws-cli` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов CLI `aws`. +**По умолчанию:** Запрещает любой вызов AWS CLI. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд aws CLI, которые разрешены. | +|-------|------|---------|-------------| +| `allowPatterns` | `string[]` | `[]` | Разрешённые префиксы команд AWS CLI. | **Пример:** @@ -240,13 +240,13 @@ failproofai поставляется с 39 встроенными политик ### `block-gcloud` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов CLI `gcloud` (Google Cloud). +**По умолчанию:** Запрещает любой вызов gcloud (Google Cloud) CLI. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд gcloud, которые разрешены. | +|-------|------|---------|-------------| +| `allowPatterns` | `string[]` | `[]` | Разрешённые префиксы команд gcloud. | **Пример:** @@ -265,13 +265,13 @@ failproofai поставляется с 39 встроенными политик ### `block-az-cli` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов CLI `az` (Azure). +**По умолчанию:** Запрещает любой вызов az (Azure) CLI. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд az CLI, которые разрешены. | +|-------|------|---------|-------------| +| `allowPatterns` | `string[]` | `[]` | Разрешённые префиксы команд az CLI. | **Пример:** @@ -290,13 +290,13 @@ failproofai поставляется с 39 встроенными политик ### `block-helm` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов `helm`. +**По умолчанию:** Запрещает любой вызов `helm`. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд helm, которые разрешены. | +|-------|------|---------|-------------| +| `allowPatterns` | `string[]` | `[]` | Разрешённые префиксы команд helm. | **Пример:** @@ -315,7 +315,7 @@ failproofai поставляется с 39 встроенными политик ### `block-gh-pipeline` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет следующие подкоманды `gh` CLI, которые мутируют состояние или срабатывают конвейеры: +**По умолчанию:** Запрещает следующие подкоманды `gh` CLI, которые изменяют состояние или запускают конвейеры: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -324,13 +324,13 @@ failproofai поставляется с 39 встроенными политик - `gh cache delete` - `gh secret set`, `gh secret delete` -Подкоманды `gh` только для чтения, такие как `gh pr view`, `gh pr list`, `gh run list`, `gh release view` и `gh api repos/.../...` **не** соответствуют этой политике — они регулярно нужны для проверок рабочего процесса (включая собственную `require-ci-green-before-stop` failproofai). +Только для чтения подкоманды `gh`, такие как `gh pr view`, `gh pr list`, `gh run list`, `gh release view` и `gh api repos/.../...` **не** совпадают с этой политикой — они обычно требуются для проверки рабочего процесса (включая собственный `require-ci-green-before-stop` failproofai). **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowPatterns` | `string[]` | `[]` | Специфичные привязанные вызовы, которые нужно разрешить, хотя они иначе были бы отклонены. | +|-------|------|---------|-------------| +| `allowPatterns` | `string[]` | `[]` | Конкретные скриптовые вызовы для разрешения, даже если они иначе были бы запрещены. | **Пример:** @@ -348,27 +348,27 @@ failproofai поставляется с 39 встроенными политик ## Секреты (санитайзеры) -Остановить агентов от утечки учётных данных в их контекст или вывод. Санитайзерные политики срабатывают на событиях **PostToolUse**. Когда Claude запускает команду Bash, читает файл или вызывает любой инструмент, эти политики проверяют вывод перед его возвращением Claude. Если обнаружена схема секрета, политика возвращает решение deny, которое предотвращает передачу вывода обратно. +Остановить утечку учётных данных агентов в их контекст или выходные данные. Политики санитайзера срабатывают на события **PostToolUse**. Когда Claude запускает команду Bash, читает файл или вызывает любой инструмент, эти политики проверяют выходные данные перед их возвратом Claude. Если обнаруживается секретный шаблон, политика возвращает решение отказа, которое предотвращает возвращение выходных данных. ### `sanitize-jwt` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает JWT токены (три сегмента base64url, разделённые `.`). +**По умолчанию:** Удаляет JWT токены (три сегмента base64url, разделённые `.`). -Без параметров. +Нет параметров. --- ### `sanitize-api-keys` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает распространённые форматы ключей API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS ключи доступа (`AKIA`), Stripe ключи (`sk_live_`, `sk_test_`), и Google API ключи (`AIza`). +**По умолчанию:** Удаляет распространённые форматы ключей API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS ключи доступа (`AKIA`), Stripe ключи (`sk_live_`, `sk_test_`) и Google API ключи (`AIza`). **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Дополнительные regex шаблоны для обработки как секреты. | +|-------|------|---------|-------------| +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Дополнительные regex шаблоны для рассмотрения в качестве секретов. | **Пример:** @@ -390,68 +390,68 @@ failproofai поставляется с 39 встроенными политик ### `sanitize-connection-strings` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает строки подключения к базе данных, которые содержат встроенные учётные данные (например `postgresql://user:password@host/db`). +**По умолчанию:** Удаляет строки подключения базы данных, содержащие встроенные учётные данные (например `postgresql://user:password@host/db`). -Без параметров. +Нет параметров. --- ### `sanitize-private-key-content` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает PEM блоки (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` и т. д.). +**По умолчанию:** Удаляет PEM блоки (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` и т. д.). -Без параметров. +Нет параметров. --- ### `sanitize-bearer-tokens` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает заголовки `Authorization: Bearer `, где токен 20 или более символов. +**По умолчанию:** Удаляет заголовки `Authorization: Bearer `, где токен содержит 20 или более символов. -Без параметров. +Нет параметров. --- ## Окружение -Защитить чувствительную конфигурацию окружения от чтения или разоблачения агентами. +Защитить конфиденциальную конфигурацию окружения от чтения или разглашения агентами. ### `block-env-files` **Событие:** PreToolUse (Bash, Read) -**По умолчанию:** Отклоняет чтение файлов `.env` через `cat .env`, вызовы инструмента Read с `.env` в качестве пути файла и т. д. +**По умолчанию:** Запрещает чтение файлов `.env` через `cat .env`, вызовы инструмента Read с `.env` как путём файла и т. д. -Не блокирует `.envrc` или другие файлы, связанные с окружением — только файлы с именем ровно `.env`. +Не блокирует `.envrc` или другие связанные с окружением файлы — только файлы, названные точно `.env`. -Без параметров. +Нет параметров. --- ### `protect-env-vars` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет команды, которые выводят переменные окружения: `printenv`, `env`, `echo $VAR`. +**По умолчанию:** Запрещает команды, которые выводят переменные окружения: `printenv`, `env`, `echo $VAR`. -Без параметров. +Нет параметров. --- ## Доступ к файлам -Держать агентов внутри границ проекта и вдалеке от чувствительных файлов. +Держите агентов работающими внутри границ проекта и вдали от конфиденциальных файлов. ### `block-read-outside-cwd` **Событие:** PreToolUse (Read, Bash) -**По умолчанию:** Отклоняет чтение файлов вне корня проекта. Границей является `CLAUDE_PROJECT_DIR` (устанавливается один раз за сеанс Claude Code), с возвратом к текущему рабочему каталогу сеанса, когда та переменная не установлена. Использование корня проекта вместо живого `cwd` означает, что граница остаётся стабильной даже после того, как Claude переходит в подкаталог. +**По умолчанию:** Запрещает чтение файлов вне корня проекта. Граница — это `CLAUDE_PROJECT_DIR` (устанавливается один раз за сеанс Claude Code), с откатом к текущему рабочему каталогу сеанса, когда эта переменная не установлена. Использование корня проекта вместо живого `cwd` означает, что граница остаётся стабильной даже после того, как Claude `cd`-ит в подкаталог. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowPaths` | `string[]` | `[]` | Абсолютные префиксы пути, которые разрешены даже если вне корня проекта. | +|-------|------|---------|-------------| +| `allowPaths` | `string[]` | `[]` | Абсолютные префиксы путей, которые разрешены даже если находятся вне корня проекта. | **Пример:** @@ -470,13 +470,13 @@ failproofai поставляется с 39 встроенными политик ### `block-secrets-write` **Событие:** PreToolUse (Write, Edit) -**По умолчанию:** Отклоняет запись в файлы, обычно используемые для приватных ключей и сертификатов: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**По умолчанию:** Запрещает запись в файлы, обычно используемые для закрытых ключей и сертификатов: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `additionalPatterns` | `string[]` | `[]` | Дополнительные шаблоны имени файла (в стиле glob) для блокирования. | +|-------|------|---------|-------------| +| `additionalPatterns` | `string[]` | `[]` | Дополнительные шаблоны имён файлов (glob-стиль) для блокировки. | **Пример:** @@ -494,18 +494,18 @@ failproofai поставляется с 39 встроенными политик ## Git -Предотвратить случайные push, force-push и ошибки ветвей, которые сложно отменить. +Предотвратить случайные push, force-push и ошибки ветвления, которые сложно отменить. ### `block-push-master` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет `git push origin main` и `git push origin master`. +**По умолчанию:** Запрещает `git push origin main` и `git push origin master`. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, которые нельзя напрямую пушить. | +|-------|------|---------|-------------| +| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, на которые нельзя напрямую push-ить. | **Пример:** @@ -520,7 +520,7 @@ failproofai поставляется с 39 встроенными политик ``` -Чтобы разрешить пушинг на все ветви (эффективно отключив эту политику без удаления её из `enabledPolicies`), установите `protectedBranches: []`. +Чтобы разрешить push на все ветви (эффективно отключить эту политику без удаления её из `enabledPolicies`), установите `protectedBranches: []`. --- @@ -528,28 +528,28 @@ failproofai поставляется с 39 встроенными политик ### `block-work-on-main` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет `git commit`, `git merge`, `git rebase` и `git cherry-pick`, пока рабочее дерево находится на `main` или `master`. Создание ветвей и переключение (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) не затронуты. +**По умолчанию:** Запрещает `git commit`, `git merge`, `git rebase` и `git cherry-pick`, пока рабочее дерево находится на `main` или `master`. Создание ветвей и переключение (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) не затрагиваются. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, на которых commit/merge/rebase/cherry-pick отклоняются. | +|-------|------|---------|-------------| +| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, на которых commit/merge/rebase/cherry-pick запрещён. | --- ### `block-force-push` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет `git push --force` и `git push -f`. +**По умолчанию:** Запрещает `git push --force` и `git push -f`. -Нет специфичных параметров политики. Используйте кросс-секционный [`hint`](/ru/configuration#hint-cross-cutting) для предложения альтернатив: +Нет специфичных для политики параметров. Используйте кросс-секционную [`hint`](/ru/configuration#hint-cross-cutting) для предложения альтернатив: ```json { "policyParams": { "block-force-push": { - "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b `) and push that instead." + "hint": "Создайте новую ветвь из вашего текущего HEAD (например `git checkout -b `) и push-ьте её вместо этого." } } } @@ -562,7 +562,7 @@ failproofai поставляется с 39 встроенными политик **Событие:** PreToolUse (Bash) **По умолчанию:** Инструктирует Claude действовать осторожно при запуске `git commit --amend`. Не блокирует команду. -Без параметров. +Нет параметров. --- @@ -571,55 +571,55 @@ failproofai поставляется с 39 встроенными политик **Событие:** PreToolUse (Bash) **По умолчанию:** Инструктирует Claude подтвердить перед запуском `git stash drop`. Не блокирует команду. -Без параметров. +Нет параметров. --- ### `warn-all-files-staged` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude проверить, что он ставит на сцену, при запуске `git add -A` или `git add .`. Не блокирует команду. +**По умолчанию:** Инструктирует Claude проверить, что он stage-ит при запуске `git add -A` или `git add .`. Не блокирует команду. -Без параметров. +Нет параметров. --- ## База данных -Перехватить деструктивные SQL операции перед их выполнением против вашей базы данных. +Перехватить разрушительные SQL операции перед их выполнением для вашей базы данных. ### `warn-destructive-sql` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед запуском SQL, содержащего `DROP TABLE`, `DROP DATABASE` или `DELETE` без предложения `WHERE`. +**По умолчанию:** Инструктирует Claude подтвердить перед запуском SQL, содержащей `DROP TABLE`, `DROP DATABASE` или `DELETE` без предложения `WHERE`. -Без параметров. +Нет параметров. --- ### `warn-schema-alteration` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед запуском выражений `ALTER TABLE`. +**По умолчанию:** Инструктирует Claude подтвердить перед запуском инструкций `ALTER TABLE`. -Без параметров. +Нет параметров. --- ## Предупреждения -Дать агентам дополнительный контекст перед потенциально рискованными, но не деструктивными операциями. +Дать агентам дополнительный контекст перед потенциально рискованными, но не разрушительными операциями. ### `warn-large-file-write` **Событие:** PreToolUse (Write) -**По умолчанию:** Инструктирует Claude подтвердить перед записью файлов размером больше 1024 KB. +**По умолчанию:** Инструктирует Claude подтвердить перед записью файлов больше 1024 КБ. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `thresholdKb` | `number` | `1024` | Порог размера файла в килобайтах, выше которого выдаётся предупреждение. | +|-------|------|---------|-------------| +| `thresholdKb` | `number` | `1024` | Пороговое значение размера файла в килобайтах, выше которого выдаётся предупреждение. | **Пример:** @@ -634,7 +634,7 @@ failproofai поставляется с 39 встроенными политик ``` -Обработчик хука применяет ограничение stdin 1 MB на полезные нагрузки. Чтобы протестировать эту политику с малым содержимым, установите `thresholdKb` на значение значительно ниже 1024. +Обработчик hook обеспечивает предел stdin в 1 МБ для полезных нагрузок. Чтобы протестировать эту политику с малым содержимым, установите `thresholdKb` на значение хорошо ниже 1024. --- @@ -644,7 +644,7 @@ failproofai поставляется с 39 встроенными политик **Событие:** PreToolUse (Bash) **По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm publish`. -Без параметров. +Нет параметров. --- @@ -653,7 +653,7 @@ failproofai поставляется с 39 встроенными политик **Событие:** PreToolUse (Bash) **По умолчанию:** Инструктирует Claude быть осторожным при запуске фоновых процессов через `nohup`, `&`, `disown` или `screen`. -Без параметров. +Нет параметров. --- @@ -662,27 +662,27 @@ failproofai поставляется с 39 встроенными политик **Событие:** PreToolUse (Bash) **По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm install -g`, `yarn global add` или `pip install` без виртуального окружения. -Без параметров. +Нет параметров. --- ## Менеджеры пакетов -Обеспечить, какие менеджеры пакетов агент может использовать. +Обеспечить, какие менеджеры пакетов позволены агенту использовать. ### `prefer-package-manager` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отключено. При включении блокирует любую команду менеджера пакетов, не входящую в список `allowed`, и сообщает Claude переписать команду, используя разрешённый менеджер. +**По умолчанию:** Отключено. При включении блокирует любую команду менеджера пакетов, отсутствующую в списке `allowed`, и говорит Claude переписать команду, используя разрешённый менеджер. Обнаруживает: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `allowed` | string[] | `[]` | Разрешённые имена менеджеров пакетов. Любой обнаруженный менеджер не в этом списке блокируется. Когда пусто, политика неэффективна. | -| `blocked` | string[] | `[]` | Дополнительные имена менеджеров для блокирования помимо встроенного списка (например `['pdm', 'pipx']`). | +|-----------|------|---------|-------------| +| `allowed` | string[] | `[]` | Разрешённые имена менеджеров пакетов. Любой обнаруженный менеджер, не находящийся в этом списке, блокирован. Если пусто, политика не работает. | +| `blocked` | string[] | `[]` | Дополнительные имена менеджеров для блокировки сверх встроенного списка (например `['pdm', 'pipx']`). | -Встроенный список блокирования охватывает: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Используйте `blocked` чтобы добавить менеджеры, не входящие в этот список. +Встроенный список блокировки охватывает: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Используйте `blocked` для добавления менеджеров, не входящих в этот список. **Пример конфигурации:** @@ -698,73 +698,73 @@ failproofai поставляется с 39 встроенными политик } ``` -С этой конфигурацией `pip install flask` и `pdm install flask` оба отклоняются с сообщением, говорящим Claude использовать вместо этого `uv` или `bun`. Команды такие как `uv pip install flask` разрешены, потому что `uv` в списке разрешений и проверяется первым. +С этой конфигурацией `pip install flask` и `pdm install flask` обе запрещены с сообщением, говорящим Claude использовать `uv` или `bun` вместо этого. Команды вроде `uv pip install flask` разрешены, потому что `uv` находится в списке разрешений и проверяется первым. --- ## Поведение AI -Обнаруживать, когда агенты застревают или ведут себя неожиданно. +Обнаружить, когда агенты застревают или ведут себя неожиданно. ### `warn-repeated-tool-calls` **Событие:** PreToolUse (все инструменты) **По умолчанию:** Инструктирует Claude пересмотреть, когда один и тот же инструмент вызывается 3+ раз с идентичными параметрами — частый признак того, что агент застрял в цикле. -Без параметров. +Нет параметров. --- ## Рабочий процесс -Обеспечить дисциплинированный рабочий процесс конца сеанса. Эти политики срабатывают на событии **Stop** и отклоняют агента от остановки до выполнения каждого условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика отклоняет, более поздние политики в цепочке пропускаются (deny коротко замыкает). +Обеспечить дисциплинированный рабочий процесс конца сеанса. Эти политики срабатывают на событие **Stop** и запрещают агенту остановиться до выполнения каждого условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика запрещает, более поздние политики в цепочке пропускаются (отказ короче-замыкает). -Все политики рабочего процесса **fail-open**: если требуемый инструмент недоступен (например `gh` не установлен, нет удалённого git), политика разрешает с информационным сообщением, объясняющим, почему проверка была пропущена. +Все рабочие политики **fail-open**: если требуемый инструмент недоступен (например `gh` не установлен, нет git remote), политика разрешает с информационным сообщением, объясняющим, почему проверка была пропущена. -### Семантика Stop для каждого CLI +### Семантика Stop по CLI -Исполнение Stop выглядит немного иначе на различных шести поддерживаемых CLI, потому что каждый предоставляет другой контракт хука об окончании работы агента. **Результат** одинаков — агент не уходит от остановки, когда ворота рабочего процесса отказывают — но **механика** отличается. Таблица ниже резюмирует; только Pi имеет видимую пользователю особенность, стоящую понимания, прежде чем вы включите политику `require-*-before-stop`. +Применение Stop выглядит немного по-разному в шести поддерживаемых CLI, потому что каждый раскрывает другой контракт hook «агент закончил». **Результат** один и тот же — агент не может остановиться, пока ворота рабочего процесса срабатывают — но **механика** отличается. Таблица ниже резюмирует; только Pi имеет видимую пользователю особенность, стоящую понять перед включением политики `require-*-before-stop`. | CLI | Когда срабатывают ворота | Что вы видите | |---|---|---| -| Claude Code | Тот же цикл агента, немедленно | Claude продолжает работать — исправляет проблему, затем снова пытается завершить. Для вас нет видимого прерывания. | -| Codex | Тот же цикл агента, немедленно | То же, что Claude. | -| GitHub Copilot CLI | Тот же цикл агента, немедленно | То же, что Claude (использует канал повтора `{decision:"block", reason}` Copilot — проверено эмпирически против Copilot CLI 1.0.41). | -| Cursor Agent | Тот же цикл агента, немедленно | То же, что Claude (использует канал `{followup_message}` Cursor — ограничен `loop_limit`, значение по умолчанию 5 повторов). | -| OpenCode | Тот же цикл агента, немедленно | То же, что Claude (использует вызов SDK `client.session.prompt(...)` OpenCode, направленный через `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Следующий ход пользователя** | **Pi видимо останавливается** когда срабатывают ворота — его цикл агента выходит и вы возвращаетесь к приглашению. Ворота затем срабатывают в следующий раз, когда вы отправляете приглашение: failproofai добавляет директиву `MANDATORY ACTION REQUIRED` к системному приглашению этого хода, инструктирующую LLM завершить шаг рабочего процесса (commit, push и т. д.) перед тем, как делать то, что вы попросили. | +| Claude Code | Этот же цикл агента, немедленно | Claude продолжает работать — исправляет проблему, затем пытается закончить снова. Никакого перерыва, видимого для вас. | +| Codex | Этот же цикл агента, немедленно | То же, что Claude. | +| GitHub Copilot CLI | Этот же цикл агента, немедленно | То же, что Claude (использует канал повтора Copilot `{decision:"block", reason}` — проверено эмпирически против Copilot CLI 1.0.41). | +| Cursor Agent | Этот же цикл агента, немедленно | То же, что Claude (использует канал `{followup_message}` Cursor — ограничено `loop_limit`, по умолчанию 5 повторов). | +| OpenCode | Этот же цикл агента, немедленно | То же, что Claude (использует вызов SDK `client.session.prompt(...)` OpenCode, маршрутизированный через `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Следующий ход пользователя** | **Pi видимо останавливается**, когда срабатывают ворота — его цикл агента выходит и вы возвращаетесь к подсказке. Ворота затем срабатывают в следующий раз, когда вы отправляете подсказку: failproofai предваряет директиву `MANDATORY ACTION REQUIRED` в системную подсказку этого хода, инструктируя LLM завершить шаг рабочего процесса (commit, push и т. д.) перед тем, как делать то, что вы просили. | -**Ограничение Pi.** `AgentEndEvent` Pi (эквивалент потока Claude для хука `Stop`) не имеет типа Result — к тому времени, когда оно срабатывает, цикл агента Pi уже вышел. Pi не может быть вынужден повторять тот же цикл, как это могут Claude / Copilot / Cursor / OpenCode. failproofai перемещает ворота на событие Pi `before_agent_start` (которое срабатывает после следующего приглашения пользователя), поэтому проверка рабочего процесса всё ещё обеспечивается, просто на следующий ход, а не на текущий. +**Ограничение Pi.** Pi's `AgentEndEvent` (эквивалент upstream Claude's `Stop` hook) не имеет типа Result — когда он срабатывает, цикл агента Pi уже вышел. Pi не может быть принуждена повторить попытку того же цикла так, как Claude / Copilot / Cursor / OpenCode могут. failproofai смещает ворота к событию Pi's `before_agent_start` (которое срабатывает после следующей подсказки пользователя), так что проверка рабочего процесса всё ещё обеспечивает, только в следующий ход, а не в текущий. **Что это означает на практике:** -- После остановки Pi причина отказа захватывается в памяти по ключу id сеанса Pi. Самое следующее приглашение, которое вы отправляете в том же процессе Pi, сливает его: LLM видит директиву `MANDATORY ACTION REQUIRED` в верхней части своего системного приглашения, совершает (или пушит / открывает PR / ждёт CI) и только затем продолжает с вашим запросом. Захваченная причина отказа одноразовая — один раз слита, ворота чисты. -- Ворота ограничены временем жизни процесса Pi. Если вы `Ctrl+C` Pi или выйдете между ходами, запись в памяти отбросится вместе с процессом и ворота будут пропущены. Claude, Copilot, Cursor и OpenCode имеют ту же границу (убить агента и ворота пропущены) — Pi просто делает это более видимым, потому что агент видимо выходит перед срабатыванием ворот. -- Ожидающий отказ также очищается на `session_shutdown` по любой причине (`new` / `resume` / `fork` / `quit`), поэтому устаревшие ворота из приоритетного сеанса не могут просачиваться в свежий сеанс, запущенный в том же процессе Pi. +- После остановки Pi, причина отказа захватывается в памяти, ключ которой — Pi session id. Очень следующая подсказка, которую вы отправляете в том же процессе Pi, её сливает: LLM видит директиву `MANDATORY ACTION REQUIRED` в верхней части своей системной подсказки, коммитит (или push-ит / открывает PR / ждёт CI) и только затем продолжает с вашей просьбой. Захваченная причина отказа — one-shot — один раз слита, ворота чистые. +- Ворота ограничены временем жизни процесса Pi. Если вы `Ctrl+C` Pi или выходите между ходами, запись в памяти сбрасывается вместе с процессом и ворота пропущены. Claude, Copilot, Cursor и OpenCode имеют ту же границу (убить агента и ворота пропущены) — Pi просто делает это более видимым, потому что агент видимо выходит перед срабатыванием ворот. +- Ожидающий отказ также очищается на `session_shutdown` по любой причине (`new` / `resume` / `fork` / `quit`), поэтому устаревшие ворота из предыдущего сеанса не могут пролиться в свежий сеанс, запущенный в том же процессе Pi. -Если вам нужен повтор Claude-стиля в том же цикле, запустите ваши политики `Stop` под любым из других пяти поддерживаемых CLI. Мы отслеживаем Pi потоком для будущего типа Result на `AgentEndEvent`, который бы позволил нам закрыть этот разрыв. +Если вам нужен повтор одного цикла, как Claude, запустите ваши политики `Stop` в любом из пяти других поддерживаемых CLI. Мы отслеживаем Pi upstream для будущего типа Result в `AgentEndEvent`, который позволил бы нам закрыть этот пробел. ### `require-commit-before-stop` **Событие:** Stop -**По умолчанию:** Отклоняет остановку, когда есть незафиксированные изменения (изменённые, поставленные на сцену или неотслеживаемые файлы). Возвращает информационное сообщение, когда рабочий каталог чист. +**По умолчанию:** Запрещает остановку, когда есть незакоммиченные изменения (изменённые, staged или untracked файлы). Возвращает информационное сообщение, когда рабочий каталог чистый. -Без параметров. +Нет параметров. --- ### `require-push-before-stop` **Событие:** Stop -**По умолчанию:** Отклоняет остановку, когда есть непушенные коммиты или когда текущая ветвь не имеет удалённой отслеживаемой ветви. Предлагает `git push -u` для создания отслеживаемой ветви если нужно. Fails open, если нет настроенного удалённого. +**По умолчанию:** Запрещает остановку, когда есть неотправленные коммиты или когда текущая ветвь не имеет ветви удалённого отслеживания. Предлагает `git push -u` для создания ветви отслеживания, если необходимо. Fails open, если удалённый сервер не настроен. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `remote` | `string` | `"origin"` | Имя удалённого для пушинга. | +|-------|------|---------|-------------| +| `remote` | `string` | `"origin"` | Имя удалённого сервера для push. | **Пример:** @@ -783,14 +783,13 @@ failproofai поставляется с 39 встроенными политик ### `require-pr-before-stop` **Событие:** Stop -**По умолчанию:** Отклоняет остановку, когда нет pull request для текущей ветви, или когда существующий PR закрыт без слияния. Инструктирует Claude создать PR с `gh pr create`. Когда PR **объединён**, политика разрешает (работа отправлена) и сообщение намекает переключиться с ветви (`git checkout main && git pull`). +**По умолчанию:** Запрещает остановку, когда нет pull request для текущей ветви, или когда существующий PR закрыт без merge. Инструктирует Claude создать PR с `gh pr create`. Когда PR **merged**, политика разрешает (работа отправлена) и сообщение намекает переключить ветвь (`git checkout main && git pull`). -Без параметров. +Нет параметров. -Эта политика требует [GitHub CLI](https://cli.github.com/) (`gh`) для установки и аутентификации. -Запустите `gh auth login` с личным токеном доступа, имеющим область `repo` для доступа на чтение к -pull requests. Если `gh` не установлен или не аутентифицирован, политика fails open и сообщает причину Claude. +Эта политика требует установки и аутентификации [GitHub CLI](https://cli.github.com/) (`gh`). +Запустите `gh auth login` с личным токеном доступа, имеющим область `repo` для чтения pull requests. Если `gh` не установлен или не аутентифицирован, политика fails open и сообщает причину Claude. --- @@ -798,24 +797,21 @@ pull requests. Если `gh` не установлен или не аутент ### `require-no-conflicts-before-stop` **Событие:** Stop -**По умолчанию:** Отклоняет остановку, когда текущая ветвь не может чистко объединиться в базовую ветвь. Политика сначала подтверждает, что есть `OPEN` PR на GitHub для ветви — без одного, нет целевого объединения для обеспечения, поэтому вся политика коротко замыкает на разрешение. Один раз `OPEN` PR подтверждён, два независимых зонда запускаются: +**По умолчанию:** Запрещает остановку, когда текущая ветвь не может чисто merged в ветвь base. Политика сначала подтверждает, есть ли `OPEN` PR на GitHub для ветви — без одного, нет цели merge для обеспечения, поэтому вся политика short-circuits для разрешения. Один раз `OPEN` PR подтверждён, два независимых зонда работают: -1. **Локально** — `git merge-tree --write-tree --name-only origin/ HEAD`. При конфликте сообщение deny называет конфликтующие файлы, поэтому Claude знает ровно что разрешить. -2. **GitHub** — повторно использует результат `gh pr view --json mergeable,state`, уже выбранный в предварительной проверке. Перехватывает конфликты, которые устаревший локальный `origin/` бы пропустил (например кто-то посадил конфликтующий PR на `main` с последнего выборки). Результат `CONFLICTING` отклоняет. Результат `UNKNOWN` также отклоняет и инструктирует Claude подождать ~10 секунд и переповторить перед попыткой остановиться снова — это предотвращает ложные отрицания, пока GitHub пересчитывает. +1. **Локальный** — `git merge-tree --write-tree --name-only origin/ HEAD`. При конфликте, сообщение отказа называет конфликтующие файлы, так что Claude знает точно, что разрешить. +2. **GitHub** — переиспользует результат `gh pr view --json mergeable,state`, уже выбранный в предварительной проверке. Перехватывает конфликты, которые устаревший локальный `origin/` пропустил бы (например, кто-то landed конфликтующий PR на `main` с момента последнего fetch). Результат `CONFLICTING` запрещает. Результат `UNKNOWN` также запрещает и инструктирует Claude ждать ~10 секунд и пере-проверить перед попыткой остановиться снова — это предотвращает ложные негативы, пока GitHub пересчитывает. -Пропускает полностью (разрешает), когда: `gh` не установлен, нет PR для ветви, состояние PR не `OPEN` (например `MERGED`, `CLOSED`), или `gh pr view` возвращает непарсируемый вывод. Также fails open, когда `origin/` отсутствует локально или когда нет коммитов впереди базы — те Layer 1 сквозные проходы всё ещё консультируют кэшированное слияние PR перед разрешением. +Пропускает полностью (разрешает), когда: `gh` не установлен, нет PR для ветви, состояние PR не `OPEN` (например `MERGED`, `CLOSED`), или `gh pr view` возвращает непарсируемый выход. Также fails open, когда `origin/` отсутствует локально или когда нет коммитов впереди base — эти Layer 1 fall-throughs всё ещё консультируют кэшированный PR mergeability перед разрешением. **Параметры:** | Параметр | Тип | По умолчанию | Описание | -|----------|-----|---------|----------| -| `baseBranch` | `string` | `"main"` | Базовая ветвь для проверки на конфликты. | +|-------|------|---------|-------------| +| `baseBranch` | `string` | `"main"` | Ветвь base для проверки конфликтов. | -GitHub CLI (`gh`) требуется для этой политики. Политика использует `gh pr view` для подтверждения -существования `OPEN` PR перед запуском любого зонда конфликта — без `gh`, политика -коротко замыкает на разрешение. Запустите `gh auth login` с личным токеном доступа, имеющим -область `repo` для доступа на чтение к pull requests. +GitHub CLI (`gh`) требуется для этой политики. Политика использует `gh pr view` для подтверждения `OPEN` PR существует перед запуском любого зонда конфликта — без `gh`, политика short-circuits для разрешения. Запустите `gh auth login` с личным токеном доступа, имеющим область `repo` для чтения pull requests. --- @@ -823,14 +819,13 @@ GitHub CLI (`gh`) требуется для этой политики. Поли ### `require-ci-green-before-stop` **Событие:** Stop -**По умолчанию:** Отклоняет остановку, когда проверки CI отказывают или всё ещё работают на текущей ветви. Проверяет как GitHub Actions запуски рабочего процесса, так и сторонние проверки ботов (например CodeRabbit, SonarCloud, Codecov). Обрабатывает `skipped`, `cancelled` и `neutral` заключения как неправильные (последнее охватывает например Socket Security предупреждения на PR внешних участников, где приложение намеренно докладывает нейтрально вместо успеха/отказа). Возвращает информационное сообщение, когда все проверки прошли. +**По умолчанию:** Запрещает остановку, когда CI проверки срабатывают или всё ещё работают на текущей ветви. Проверяет оба GitHub Actions рабочего процесса и третьи сторон bot проверки (например CodeRabbit, SonarCloud, Codecov). Рассматривает `skipped`, `cancelled` и `neutral` заключения как non-failing (последнее охватывает например Socket Security оповещения на PR внешних контрибьютеров, где приложение намеренно сообщает neutral вместо success/failure). Возвращает информационное сообщение, когда все проверки проходят. -Без параметров. +Нет параметров. -Эта политика требует [GitHub CLI](https://cli.github.com/) (`gh`) для установки и аутентификации. -Запустите `gh auth login` с личным токеном доступа, имеющим область `repo` для доступа на чтение к -запускам рабочего процесса Actions и Checks API. Если `gh` не установлен или не аутентифицирован, политика fails open и сообщает причину Claude. +Эта политика требует установки и аутентификации [GitHub CLI](https://cli.github.com/) (`gh`). +Запустите `gh auth login` с личным токеном доступа, имеющим область `repo` для чтения Actions рабочего процесса и Checks API. Если `gh` не установлен или не аутентифицирован, политика fails open и сообщает причину Claude. --- @@ -839,7 +834,7 @@ GitHub CLI (`gh`) требуется для этой политики. Поли ## Отключение отдельных политик -Удалите определённую политику из `enabledPolicies` в вашей конфигурации, или выключите её в вкладке Policies приборной панели. +Удалите конкретную политику из `enabledPolicies` в вашей конфигурации или переключите её в вкладке Политики на панели управления. ```json { @@ -850,4 +845,4 @@ GitHub CLI (`gh`) требуется для этой политики. Поли } ``` -Политики, не перечисленные в `enabledPolicies`, не запускаются, даже если существуют записи `policyParams` для них. \ No newline at end of file +Политики, не указанные в `enabledPolicies`, не запускаются, даже если существуют записи `policyParams` для них. \ No newline at end of file diff --git a/docs/ru/cli/audit.mdx b/docs/ru/cli/audit.mdx index 0626cf13..6ab31198 100644 --- a/docs/ru/cli/audit.mdx +++ b/docs/ru/cli/audit.mdx @@ -1,21 +1,20 @@ --- ---- -title: Аудит прошлых сеансов (бета) -description: "Подсчитайте, как часто агент совершал неэффективные или рискованные действия в прошлых записях" +title: Аудит прошлых сессий (бета) +description: "Подсчитайте, как часто агент совершал неэффективные или рискованные действия в прошлых транскриптах" --- - **Бета-функция.** Аудит поставляется в бета-версии, пока мы собираем - ранние отзывы. Каталог детекторов и формат отчета могут измениться до - следующего стабильного выпуска. Пожалуйста, откройте issue, если что-то + **Бета-функция.** Аудит поставляется в виде бета-версии, пока мы собираем + первоначальные отзывы. Каталог детекторов и формат отчета могут измениться + перед следующим стабильным выпуском. Пожалуйста, откройте issue, если что-то выглядит неправильно. -Аудит воспроизводит ваши прошлые записи agent-CLI через систему политик failproofai и отображает поделяемый визуальный отчет на **странице `/audit`** — архетип вашего агента, оценку от 0 до 100 и точно то, какие политики могли бы поймать что. +Аудит воспроизводит ваши прошлые транскрипты agent-CLI через механизм политик failproofai и создает общедоступный визуальный отчет на странице **`/audit` панели управления** — архетип агента, оценка от 0 до 100 и ровно то, какие политики что блокировали. -## Запустить +## Запуск -Три способа — все приводят к одному отчету `/audit`. +Три способа — все ведут к одному отчету `/audit`. @@ -36,10 +35,10 @@ failproofai `npx -y failproofai audit` загружает failproofai, запускает сканирование и - открывает для вас панель управления — ничего не нужно устанавливать заранее. + открывает панель управления — ничего не нужно устанавливать заранее. - `failproofai audit` запускает сканирование в вашем терминале, затем автоматически + `failproofai audit` запускает сканирование в терминале, а затем автоматически открывает `localhost:8020/audit` по завершении. @@ -49,84 +48,88 @@ failproofai - Запустите `failproofai audit -h` (или `--help`) для справки. Аудит работает - **полностью автономно** — учетная запись или сеть не требуются — и панель - управления продолжает работать, пока вы не остановите ее с помощью `Ctrl+C`. + Запустите `failproofai audit -h` (или `--help`) для просмотра справки. Аудит + работает **полностью в автономном режиме** — не требует аккаунт или сети — + и панель управления продолжает работать, пока вы не остановите её командой + `Ctrl+C`. -Панель управления сканирует прошлые записи agent CLI на этом компьютере (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) и сообщает, как часто агент совершал действия, которые failproofai предназначен останавливать — проверки переменных окружения, принудительные push'и, избыточные префиксы `cd `, sleep-polling циклы, повторное чтение только что отредактированных файлов и многое другое. +Панель управления сканирует прошлые транскрипты agent CLI на этой машине (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) и сообщает, как часто агент совершал действия, которые failproofai предназначен блокировать — проверки переменных окружения, force push'и, избыточные префиксы `cd `, циклы с ожиданием, повторное чтение только что отредактированных файлов и многое другое. -Для каждой записи каждое событие использования инструмента воспроизводится через 39 встроенных политик **и** через 8 аудит-специфичных детекторов, которые ловят паттерны, еще не охватываемые политиками реального времени. Подсчеты агрегируются по политикам / детекторам во всех сеансах. +Для каждого транскрипта каждое событие использования инструмента воспроизводится через 39 встроенных политик **и** через 8 только-аудит детекторов, которые ловят паттерны, не охваченные политиками времени выполнения. Счетчики агрегируются по политикам / детекторам во всех сессиях. ## Что вы получите -Страница `/audit` — это один экран, поделяемый **постер**, за которым следуют четыре раздела ниже сгиба: +Страница `/audit` — это единый экран, общедоступный **постер**, за которым следуют четыре раздела ниже: -1. **Постер** — личность вашего агента с первого взгляда: его **архетип** (один из 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), ключевые слова его персоны, насколько редок этот архетип, и **оценка от 0 до 100** с полосой уровня (`S` вплоть до `bottom tier`). Разработано для того, чтобы поделиться — опубликуйте в X или LinkedIn или загрузите как PNG. -2. **`// strengths`** — то, что ваш агент уже делает хорошо, как реальные цифры из сканирования (например, clean-tool-call %, `0` попыток push-to-main), показано только там, где соответствующая политика имеет чистую историю. -3. **`// quirks`** — то, что прошло незамеченным: ранжированная таблица поведений, которые failproofai бы перехватил — *когда* это произошло в последний раз, *что прошло* (и встроенная политика, которая бы это заблокировала), его *серьезность* и как часто *встречалось* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — список предписанных исправлений: по одной строке на политику с копируемой командой `failproofai policy add `, плюс кнопка **install all**, которая включает каждую рекомендацию сразу и показывает вашу **спрогнозированную оценку**, если вы это сделаете. -5. **`// come back better`** — создайте привычку: установите **напоминание** о переаудите по электронной почте (`3d` / `7d` / `14d` / `30d`) или переаудит сейчас, и **пригласите друга** запустить собственный аудит (отправлено с failproof.ai, Cc для вас). Напоминания и приглашения требуют входа. +1. **Постер** — идентичность вашего агента с первого взгляда: его **архетип** (один из 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), ключевые слова персоны, насколько редок этот архетип, и **оценка от 0 до 100** с полосой ранга (`S` до `bottom tier`). Сделано для поделиться — опубликуйте в X или LinkedIn или скачайте как PNG. +2. **`// strengths`** — что ваш агент уже делает хорошо, как реальные числа из сканирования (например, clean-tool-call %, `0` попыток push-to-main), показано только там, где соответствующая политика имеет чистый рекорд. +3. **`// quirks`** — что прошло сквозь: ранжированная таблица поведения, которое failproofai блокировал бы — *когда* это произошло в последний раз, *что прошло* (и встроенная политика, которая это блокировала бы), *серьезность*, и как часто это было *замечено* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — рекомендуемый список исправлений: одна строка на политику с копируемой командой `failproofai policy add `, плюс кнопка **install all**, которая включает все рекомендации сразу и показывает вашу **прогнозируемую оценку**, если вы это сделаете. +5. **`// come back better`** — вырабатывайте привычку: установите **напоминание** по расписанию переаудита (`3d` / `7d` / `14d` / `30d`) или переаудит сейчас, и **пригласите друга** запустить их собственный аудит (отправляется от failproof.ai, копия вам). Напоминания и приглашения требуют входа. ## Запланированные аудиты Если вы запустите **failproofaid daemon** (см. [`failproofai config`](/ru/cli/install-policies)), он может переаудировать для вас по расписанию и обновлять отчет `/audit` в -фоновом режиме. Это **отключено по умолчанию**, потому что сканирование читает *содержимое* -каждой записи сеанса агента на этом компьютере — ничего не сканируется по таймеру, -пока вы не попросите. - -Включите это в `~/.failproofai/config.toml`: - -```toml -[audit] -auto = true -interval_days = 7 +фоне. Это **отключено по умолчанию**, потому что сканирование читает *содержимое* +каждого транскрипта сессии агента на этой машине — ничего не сканируется по таймеру, +пока вы об этом не попросите. + +Включите в `~/.failproofai/config.json` — добавьте ключ `audit` рядом с +остальным содержимым файла: + +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | Ключ | Значение | |---|---| -| `auto` | `true` включает запланированное сканирование. Всё остальное — отсутствие, `false`, `"yes"` — отключено. | -| `interval_days` | Дни между сканированиями. Ограничено 1–90; `0`, отрицательное или не-число откатывается на `7`. | +| `auto` | `true` включает запланированное сканирование. Всё остальное — отсутствие, `false`, `"yes"` — означает отключено. | +| `interval_days` | Дни между сканированиями. Зажимается в диапазон 1–90; `0`, отрицательное значение или не-число возвращается к `7`. | -- Расписание **по стенным часам**, поэтому оно переживает спящий режим и перезагрузки: ноутбук, - который спал после положенного времени, запускает **один раз** при пробуждении, никогда накопления. -- Каждый запуск — это отдельный процесс с низким приоритетом (`nice 19`) — никогда путь - hook'а демона, который остается свободным для ответа на вызовы инструментов. +- Расписание **привязано к стеновым часам**, поэтому оно сохраняется при спящем режиме и перезагрузках: ноутбук, + который спал дольше назначенного времени, запускает сканирование **один раз** при пробуждении, никогда не накапливает очередь. +- Каждый запуск — отдельный, низкоприоритетный (`nice 19`) процесс — никогда не путь daemon'а + хука, который остается свободным для ответа на вызовы инструментов. - Сканирование пропускается, если `failproofai audit` или переаудит панели управления уже - выполняется; он переповторяется вскоре после, а не рассматривается как ошибка. + выполняется; оно повторяется вскоре после, а не рассматривается как ошибка. - Прогресс записывается в `~/.failproofai/state/audit-schedule.json` (последний запуск, - когда следующий). Демон владеет этим файлом — измените кадр в `config.toml`. + следующий срок). Daemon владеет этим файлом — измените ритм в `config.json`. -Если вы включили это на машине, установленной старой failproofai, запустите -`failproofai config` один раз. Определение сервиса демона нуждается в одной -дополнительной записи, прежде чем он сможет запустить CLI, и обновление -является частью этой команды. +Если вы включили это на машине, установленной старым failproofai, запустите +`failproofai config` один раз. Определение сервиса daemon'а нуждается в одной +дополнительной записи перед запуском CLI, и обновление является частью этой команды. -## Аудит-специфичные детекторы +## Только-аудит детекторы -Эти детекторы ловят паттерны "глупого поведения", не (пока) не принудительные в реальном времени. Они работают только во время аудита и никогда не блокируют живой вызов инструмента. +Они обнаруживают паттерны "глупого поведения", не (еще) принудительно применяемые в реальном времени. Они работают только во время аудита и никогда не блокируют прямой вызов инструмента. -| Детектор | Что он считает | +| Детектор | Что подсчитывает | |---|---| -| `redundant-cd-cwd` | Bash команды, начинающиеся с `cd && …`, хотя команды уже запускаются в `cwd`. | +| `redundant-cd-cwd` | Bash команды, начинающиеся с `cd && …` хотя команды уже выполняются в `cwd`. | | `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` на одном исходном файле — используйте инструмент `Read`. | | `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` встроенные правки — используйте инструмент `Edit`. | -| `prefer-write-over-heredoc` | Heredoc / многострочный `echo > file` запись файлов — используйте инструмент `Write`. | -| `sleep-polling-loop` | Длинный `sleep N` (≥ 30s) или `while …; sleep …; done` polling циклы. | -| `find-from-root` | `find /`, `find /home`, `find /usr` и т.д. — ограничьте до `cwd`. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, пропуск hook'ов. | -| `reread-after-edit` | `Read` файла, который был только что `Edit`/`Write` в том же сеансе. | +| `prefer-write-over-heredoc` | Heredoc / многострочный `echo > file` для записи файлов — используйте инструмент `Write`. | +| `sleep-polling-loop` | Долгий `sleep N` (≥ 30s) или `while …; sleep …; done` циклы опроса. | +| `find-from-root` | `find /`, `find /home`, `find /usr` и т.д. — сузьте область на `cwd`. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, пропуск хуков. | +| `reread-after-edit` | `Read` файла, который был только что `Edit`/`Write` в той же сессии. | ## Кэши -- **Кэш для каждой записи** в `~/.failproofai/cache/audit/.json` с ключом по `(mtime, size, engineVersion, detectorVersion)` — автоматически инвалидируется при изменении записи или кода политики/детектора. Каждая запись также хранит timestamp `cachedAt` как **TTL метаданные** (не часть ключа кэша); записи старше **7 дней** отклоняются при чтении, поэтому долгоживущие результаты не переживают развивающееся назначение детектора. -- **Кэш полного результата** в `~/.failproofai/audit-dashboard.json` (режим 0600). Позволяет панели управления отображаться мгновенно при навигации без переаудита. Также отклоняется при чтении спустя **7 дней TTL** — `/audit` затем падает на пустое состояние и запрашивает свежий запуск. Нажмите `[ re-audit now ]` около дна отчета для обновления — переаудит отправляет `noCache: true`, поэтому он обходит кэш для каждой записи и повторно сканирует каждую запись вместо возврата кэшированного результата; запуск транслирует прогресс через закрепленную верхнюю полосу и меняет результат на месте при успехе (без перезагрузки страницы; неудачный переаудит сохраняет предыдущий отчет). +- **Кэш по-транскрипту** в `~/.failproofai/cache/audit/.json` с ключом `(mtime, size, engineVersion, detectorVersion)` — автоматически инвалидируется, когда транскрипт или код политик/детекторов меняется. Каждая запись также хранит метаданные `cachedAt` в виде **TTL** (не часть ключа кэша); записи старше **7 дней** отклоняются при чтении, чтобы долгоживущие результаты не пережили развивающееся намерение детектора. +- **Кэш всего результата** в `~/.failproofai/audit-dashboard.json` (режим 0600). Позволяет панели управления отрисовываться мгновенно при навигации без переаудита. Также отклоняется при чтении после **7-дневного TTL** — `/audit` затем переходит в пустое состояние и предлагает свежий запуск. Нажмите `[ re-audit now ]` у нижней части отчета для обновления — переаудит отправляет `noCache: true`, поэтому обходит кэш по-транскрипту и переканирует каждый транскрипт вместо возврата кэшированного результата; запуск передает прогресс через липкую верхнюю полосу и меняет результат на месте при успехе (без перезагрузки страницы; неудачный переаудит сохраняет предыдущий отчет). ## Примечания -- **Без изменений.** Аудит воспроизводится в режиме только чтения. `warn-repeated-tool-calls` пропускается, потому что его сайдкар для каждого сеанса иначе был бы изменен. -- **Политики рабочего процесса пропускаются.** Политики `require-*-before-stop` срабатывают только на события `Stop` и `execSync` против живого состояния git — они не имеют значимой интерпретации "что бы произошло в 2025", поэтому они не появляются в подсчетах аудита. -- **Пользовательские политики пропускаются.** User-supplied пользовательские hook'и не воспроизводятся (они могли измениться с момента исходного сеанса). \ No newline at end of file +- **Без изменений.** Аудит воспроизводится в режиме только для чтения. `warn-repeated-tool-calls` пропускается, потому что его побочный сопроводитель по-сессии иначе был бы изменен. +- **Политики рабочего потока пропущены.** Политики `require-*-before-stop` срабатывают только на событиях `Stop` и `execSync` против прямого состояния git — они не имеют значимого толкования "что произойдет в 2025", поэтому они не появляются в счетчиках аудита. +- **Пользовательские политики пропущены.** Пользовательские хуки не воспроизводятся (они могли измениться с момента исходной сессии). \ No newline at end of file diff --git a/docs/ru/cli/dashboard.mdx b/docs/ru/cli/dashboard.mdx index 9d642124..542b26c1 100644 --- a/docs/ru/cli/dashboard.mdx +++ b/docs/ru/cli/dashboard.mdx @@ -9,14 +9,14 @@ failproofai Запускает веб-панель управления по адресу `http://localhost:8020`. -## Опции +## Параметры | Флаг | Описание | -|------|---------| +|------|----------| | `--port ` | Порт для прослушивания (по умолчанию: `8020`) | -| `--allowed-origins ` | Разделённые запятыми хосты/IP-адреса, разрешённые для доступа к ресурсам разработки | +| `--allowed-origins ` | Разделённые запятыми хосты/IP адреса, которым разрешён доступ к ресурсам разработки | -Чтобы перенаправить панель управления на папку Claude проекта, отличную от стандартной, установите переменную окружения `CLAUDE_PROJECTS_PATH` при запуске. +Чтобы направить панель управления в папку проекта Claude, отличную от папки по умолчанию, установите переменную окружения `CLAUDE_PROJECTS_PATH` при запуске. ## Примеры @@ -24,6 +24,6 @@ failproofai # Запуск на другом порту failproofai --port 9000 -# Использование пользовательского пути к проектам Claude через переменную окружения +# Использование пользовательского пути проектов Claude через переменную окружения CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/ru/cli/environment-variables.mdx b/docs/ru/cli/environment-variables.mdx index cadf44a6..89084736 100644 --- a/docs/ru/cli/environment-variables.mdx +++ b/docs/ru/cli/environment-variables.mdx @@ -3,13 +3,13 @@ title: Переменные окружения description: "Настройте поведение failproofai с помощью переменных окружения" --- -## Dashboard +## Панель управления | Переменная | Описание | |----------|-------------| -| `PORT` | Порт Dashboard (по умолчанию: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Переопределить расположение папок проектов Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Разделённый запятыми список страниц Dashboard, которые нужно скрыть | +| `PORT` | Порт панели управления (по умолчанию: `8020`) | +| `CLAUDE_PROJECTS_PATH` | Переопределение пути к папкам проектов Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Разделённый запятыми список страниц панели управления для скрытия | | `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Хосты/IP-адреса, разрешённые для доступа к ресурсам разработки. Аналогично `--allowed-origins`. | ## Логирование @@ -17,56 +17,50 @@ description: "Настройте поведение failproofai с помощь | Переменная | Описание | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Уровень логирования сервера (по умолчанию: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Пользовательский путь к файлу логов hook, или `true` для значения по умолчанию (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Пользовательский путь к файлу логов hook или `true` для значения по умолчанию (`~/.failproofai/logs/hooks.log`) | ## Телеметрия -failproofai по умолчанию отправляет анонимную телеметрию использования. Есть два способа -отключить её, и они применяют наиболее строгий вариант — переменная окружения -никогда не сможет повторно включить то, что отключено в конфигурационном файле. +failproofai по умолчанию отправляет анонимную телеметрию использования. Существует два способа её отключить, и применяется более строгий из них — переменная окружения никогда не сможет повторно включить то, что было отключено в файле конфигурации. | Переменная | Описание | |----------|-------------| | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Отключить анонимную телеметрию использования для этого процесса | -Чтобы отключить её постоянно для машины, добавьте это в `~/.failproofai/config.toml`: +Чтобы отключить её постоянно для компьютера, добавьте следующее в `~/.failproofai/config.json`: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -Конфигурационный файл — это опция, которую нужно использовать, если вы запускаете **демон failproofaid**. -Демон является системным сервисом, и его окружение не включает -переменные, экспортированные из вашей оболочки — поэтому `FAILPROOFAI_TELEMETRY_DISABLED` не может -до него достичь. `[telemetry] enabled = false` читается и CLI, и демоном. +Файл конфигурации следует использовать, если вы запускаете **демон failproofaid**. +Демон является системным сервисом, и его окружение не включает переменные, экспортированные из вашей оболочки — поэтому `FAILPROOFAI_TELEMETRY_DISABLED` не сможет до него добраться. `[telemetry] enabled = false` читается как CLI, так и демоном. -Демон отправляет только собственную **жизненный цикл**: что он запустился (и завершился ли -предыдущий запуск корректно), что он остановился, когда был порождён или перезапущен его worker оценки, -когда задача сборщика завершилась ошибкой, и результат -pull облачной политики. Они содержат низкомощные значения и счётчики — никогда путь файла, -команду, политику, промпт или что-либо прочитанное из транскрипта. Нет -события per-tool-call. +Демон отправляет только свой **жизненный цикл**: что он был запущен (и завершилось ли предыдущее выполнение корректно), что он был остановлен, когда был запущен или перезапущен рабочий процесс оценки, когда задача сборщика завершилась ошибкой и результат извлечения облачной политики. Эти данные содержат значения с низкой кардинальностью и счётчики — никогда пути к файлам, команды, политики, подсказки или что-либо из расшифровки. События не отправляются для каждого вызова инструмента. ## Аутентификация | Переменная | Описание | |----------|-------------| -| `FAILPROOF_API_URL` | Переопределить базовый URL api-сервера, используемый диалогом аутентификации Dashboard. По умолчанию `https://api.befailproof.ai`; установите `http://localhost:8080` (или другой адрес) при запуске локального api-сервера. | -| `FAILPROOFAI_AUTH_DIR` | Переопределить расположение, где хранится `auth.json` (по умолчанию: `~/.failproofai`). В основном полезно для изолированных тестов. | +| `FAILPROOF_API_URL` | Переопределение базового URL API-сервера, используемого диалогом аутентификации панели управления. По умолчанию `https://api.befailproof.ai`; установите в `http://localhost:8080` (или другое место) при запуске локального API-сервера. | +| `FAILPROOFAI_AUTH_DIR` | Переопределение пути к хранилищу `auth.json` (по умолчанию: `~/.failproofai`). В основном полезно для изолированных тестов. | -## Подсказка первого запуска +## Приглашение при первом запуске | Переменная | Описание | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Пропустить подсказку, предлагающую установить политики при первом вызове `failproofai` без аргументов | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Пропустить приглашение об установке политик при первом вызове простой команды `failproofai` | ## LLM (для оценки политик) | Переменная | Описание | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | Endpoint API LLM (по умолчанию: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_BASE_URL` | Endpoint LLM API (по умолчанию: `https://api.openai.com/v1`) | | `FAILPROOFAI_LLM_API_KEY` | API ключ для политик на основе LLM | | `FAILPROOFAI_LLM_MODEL` | Название модели (по умолчанию: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/ru/cli/hook.mdx b/docs/ru/cli/hook.mdx index 4af9c29a..9e48e357 100644 --- a/docs/ru/cli/hook.mdx +++ b/docs/ru/cli/hook.mdx @@ -7,9 +7,9 @@ description: "Подпроцесс, который Claude Code вызывает failproofai --hook ``` -Это команда, зарегистрированная в `settings.json` Claude Code командой `failproofai policies --install`. Вы обычно не вызываете это напрямую. +Это команда, зарегистрированная в `settings.json` Claude Code командой `failproofai policies --install`. Обычно вы не вызываете её напрямую. -Читает JSON-полезную нагрузку из stdin, оценивает все включённые политики и завершается с кодом, указывающим решение: +Читает JSON-полезную нагрузку из stdin, оценивает все включённые политики и завершает работу с кодом, указывающим на решение: | Код выхода | Решение | Эффект | |-----------|---------|--------| @@ -20,7 +20,7 @@ failproofai --hook ### Поддерживаемые типы событий | Категория | События | -|----------|---------| +|-----------|---------| | **Выполнение инструментов** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Жизненный цикл сессии** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **Взаимодействие пользователя** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | diff --git a/docs/ru/cli/install-policies.mdx b/docs/ru/cli/install-policies.mdx index 499c0bdc..8029adad 100644 --- a/docs/ru/cli/install-policies.mdx +++ b/docs/ru/cli/install-policies.mdx @@ -7,27 +7,27 @@ description: "Включите политики, чтобы они запуск failproofai policies --install [policy-names...] [options] ``` -Добавляет записи хуков в файл настроек установленного CLI агента (Claude Code, OpenAI Codex или GitHub Copilot CLI _(beta)_), чтобы failproofai перехватывал вызовы инструментов. +Записывает записи hook в файл параметров установленного CLI агента (Claude Code, OpenAI Codex или GitHub Copilot CLI _(beta)_), чтобы failproofai перехватывал вызовы инструментов. -Сокращения: `failproofai p -i` +Псевдонимы: `failproofai p -i` ## Опции | Флаг | Описание | |------|---------| -| `--cli claude\|codex\|copilot` | CLI агента(ов) для установки; через пробел (например `--cli claude codex copilot`) или повторно. Пропустите, чтобы автоматически определить установленные CLI и выбрать. | -| `--scope user` | Установить в файл настроек пользователя (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). По умолчанию. | -| `--scope project` | Установить в файл настроек проекта (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Только Claude — установить в `/.claude/settings.local.json`. Codex и Copilot не имеют области `local`. | -| `--custom ` / `-c` | Путь к файлу JS с пользовательскими политиками хуков | +| `--cli claude\|codex\|copilot` | CLI агента (или несколько) для установки; через пробел (например `--cli claude codex copilot`) или повторены. Опустите, чтобы автоматически обнаружить установленные CLI и запросить выбор. | +| `--scope user` | Установить в файл параметров с областью пользователя (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). По умолчанию. | +| `--scope project` | Установить в файл параметров с областью проекта (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Только Claude — устанавливает в `/.claude/settings.local.json`. Codex и Copilot не имеют области `local`. | +| `--custom ` / `-c` | Путь к файлу JS, содержащему пользовательские политики hook | ## Поведение -- **Без имён политик** - открывает интерактивное меню для выбора политик -- **Конкретные имена** - включает эти политики (добавляет к уже включённым) -- **`all`** - включает все доступные политики +- **Без имён политик** — открывает интерактивное меню выбора политик +- **Конкретные имена** — включает эти политики (добавляются к уже включённым) +- **`all`** — включает все доступные политики -Установка является аддитивной: повторный запуск `--install` добавит новые политики без удаления существующих. +Установка является накопительной: повторный запуск `--install` добавляет новые политики без удаления существующих. ## Примеры @@ -41,7 +41,7 @@ failproofai policies --install block-sudo sanitize-api-keys --scope project # Включить все политики сразу failproofai policies --install all -# Установить с файлом пользовательских политик +# Установить с пользовательским файлом политик failproofai policies --install --custom ./my-policies.js # Установить для OpenAI Codex (область проекта) @@ -50,8 +50,8 @@ failproofai policies --install --cli codex --scope project # Установить для GitHub Copilot CLI (beta) для текущего проекта failproofai policies --install --cli copilot --scope project -# Установить для всех трёх CLI одновременно +# Установить для всех трёх CLI сразу failproofai policies --install --cli claude codex copilot ``` -Когда указана опция `--custom `, файл немедленно проверяется — он должен вызвать `customPolicies.add()` хотя бы один раз. Разрешённый путь сохраняется в `policies-config.json` как `customPoliciesPath`. \ No newline at end of file +Когда указан `--custom `, файл проверяется немедленно — он должен вызвать `customPolicies.add()` хотя бы один раз. Разрешённый путь сохраняется в `policies-config.json` как `customPoliciesPath`. \ No newline at end of file diff --git a/docs/ru/cli/list-policies.mdx b/docs/ru/cli/list-policies.mdx index 105d8eae..23e5c7ca 100644 --- a/docs/ru/cli/list-policies.mdx +++ b/docs/ru/cli/list-policies.mdx @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Неизвестные ключи в `policyParams` здесь помечаются, чтобы вы могли рано обнаружить опечатки. \ No newline at end of file +Неизвестные ключи в `policyParams` отмечаются здесь, чтобы вы могли выявить ошибки на ранних этапах. \ No newline at end of file diff --git a/docs/ru/cli/migrate.mdx b/docs/ru/cli/migrate.mdx new file mode 100644 index 00000000..8994b7b4 --- /dev/null +++ b/docs/ru/cli/migrate.mdx @@ -0,0 +1,86 @@ +--- +title: Перенести домашний каталог +description: "Обновить ~/.failproofai до макета этой версии и сначала увидеть, что произойдёт" +--- + +```bash +failproofai migrate --dry-run # вывести план, ничего не менять +failproofai migrate # выполнить +``` + +Большинство людей никогда не вводят это вручную. Команда запускается автоматически при первом использовании после обновления, и [`failproofai update`](/ru/cli/update) включает её. Вводите её напрямую, если хотите увидеть план перед его выполнением или запустить миграцию отдельно. + +## Зависит от макета, а не от версии + +`~/.failproofai/VERSION` хранит номер **макета** — форму каталога, а не релиз, который её создал. Миграции привязаны к этому номеру, что делает большой промежуток времени дешёвым: + +- Версии npm меняются в каждом релизе, их бывает десятки между двумя макетами. +- Поэтому машина, которая пропустила тридцать релизов без **изменения макета**, запустит **ноль** миграций, а не тридцать холостых операций. +- А машина, которая пропустила несколько макетов сразу, выполнит каждый шаг по порядку, каждый из них зная только свои два конца. + +Это важно, потому что npm не может обновить установленный пакет самостоятельно. Машина, которая неделями сидит на одной версии, а затем прыгает сразу на несколько макетов — это обычный случай, а не экзотический. + +## Пробный запуск + +`--dry-run` выводит точную цепь и файлы, которые будут сохранены в первую очередь, и совсем ничего не меняет — никакой миграции, никакой резервной копии, никакой записи в журнал: + +``` +На диске макет 2; эта сборка говорит 3. +Будет выполнено 1 шаг(ов): + 2 → 3 макет 2 → 3: перенести config.toml и credentials.toml в JSON, сдвинуть + custom-policies/ обратно в policies/, вложить конфиг политик в корень + +Они будут сначала скопированы в ~/.failproofai/migrations/backup-layout2: + VERSION + config.toml + credentials.toml +``` + +## Что переносится, а что перестраивается + +Каждый путь в домашнем каталоге объявляет, какой тип данных он содержит, и это решает, может ли миграция его отбросить. Правило: **производное и пересчитываемое может быть удалено; всё, что вы печатали, всё ещё не доставленное и всё, что идентифицирует машину — переносится.** + +| Переносится | Перестраивается или переполучается | +|---|---| +| `config.json` — параметры, `daemon.configured`, дополнительные пути захвата | Кеш аудита | +| `credentials.json` — ваша облачная регистрация | Управляемые облаком развёртывания (переполучаются и проверяются по дайджесту при следующем опросе) | +| `policies-config.json` — ваш выбор политик и их параметры | Временное состояние демона | +| `policies/` — ваши собственные файлы политик и вспомогательные функции, которые они импортируют | | +| `hook-activity/` — журнал решений, который читает панель управления | | +| Недоставленные события, всё ещё в очереди на загрузку | | +| `cursors/` — водяные знаки сборщика | | +| Бинарный файл демона в `bin/` | | + + + Недоставленные события переносятся вместо удаления, потому что потеря была бы постоянной, а не просто медленной: водяной знак сборщика уже продвинулся дальше всего, что находится в очереди, поэтому ничто никогда не прочитает этот диапазон транскрипта снова. Миграция также просит демона доставить то, что находится в очереди, сразу после завершения, поэтому обычный результат — что нечего переносить. + + +Ключи, которые *более новая* версия записала в `config.json`, `credentials.json` или `policies-config.json`, тоже сохраняются вместо удаления более старым читателем. + +## Запись, которую она оставляет + +``` +~/.failproofai/migrations/ + applied.json по одной записи за шаг: макет, CLI, временная метка, длительность, результат + backup-layout/ копии незаменимых файлов, взятые перед первым шагом +``` + +`applied.json` отвечает на вопрос «через что на самом деле прошла эта машина» — первый вопрос, который стоит задать, когда что-то выглядит неправильно после обновления. Приложите её к отчёту об ошибке. + +Резервная копия намеренно маленькая, а не копия всего каталога: миграция больше ничего незаменимого не удаляет по дизайну, поэтому от чего стоит защищаться — это *дефект в шаге*, и эти несколько файлов — место, где такой дефект нанесёт ущерб. + +## Если шаг не выполнится + +Цепь останавливается там. `VERSION` отмечается временной меткой только завершённым шагом, поэтому домашний каталог остаётся отмеченным со своим старым макетом и следующая команда повторит попытку — домашний каталог никогда не помечается как текущий на основе частичной миграции. Шаг записывается в `applied.json` с `"ok": false`, и резервная копия остаётся там, где она была взята. + +## Более новый домашний каталог отклоняется, не мигрируется + +Если `~/.failproofai/` был написан **более новой** версией failproofai, чем та, которую вы используете, команда останавливается и говорит вам обновиться вместо этого. Эти данные хороши и более новый CLI их читает; миграция «вперёд» из них — это то, что не существует, и сброс их уничтожит что-то восстановимое. + +``` +Каталог failproofai этой машины был написан более новой версией (макет 4; +эта сборка говорит 3). Обновитесь вместо миграции: + npm install -g failproofai@latest +``` + +Демон применяет то же правило: `failproofaid` отказывается запускаться с макетом, который он не понимает, вместо того чтобы читать и писать пути, которые переместились. \ No newline at end of file diff --git a/docs/ru/cli/remove-policies.mdx b/docs/ru/cli/remove-policies.mdx index 76d68a6c..a0179c8b 100644 --- a/docs/ru/cli/remove-policies.mdx +++ b/docs/ru/cli/remove-policies.mdx @@ -1,31 +1,31 @@ --- --- title: Удаление политик -description: "Удаление записей hook из настроек Claude Code" +description: "Удалите записи hook из settings Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -Удаляет записи hook failproofai из файла `settings.json` Claude Code. +Удаляет записи hook failproofai из `settings.json` Claude Code. -Псевдонимы: `failproofai p -u` +Альтернативные названия: `failproofai p -u` -## Параметры +## Опции | Флаг | Описание | |------|-------------| -| `--scope user` | Удалить из глобальных настроек (по умолчанию) | -| `--scope project` | Удалить из настроек проекта | -| `--scope local` | Удалить из локальных настроек | -| `--scope all` | Удалить из всех областей сразу | +| `--scope user` | Удалить из глобальных параметров (по умолчанию) | +| `--scope project` | Удалить из параметров проекта | +| `--scope local` | Удалить из локальных параметров | +| `--scope all` | Удалить из всех областей одновременно | | `--custom` / `-c` | Очистить `customPoliciesPath` из конфигурации | ## Поведение -- **Без названий политик** — удаляет все записи hook failproofai из файла настроек -- **Конкретные названия** — отключает эти политики, но оставляет hooks установленными +- **Без названий политик** - удаляет все записи hook failproofai из файла параметров +- **Конкретные названия** - отключает эти политики, но оставляет hooks установленными ## Примеры @@ -33,12 +33,12 @@ failproofai policies --uninstall [policy-names...] [options] # Удалить все hooks глобально failproofai policies --uninstall -# Отключить конкретную политику (hooks остаются установленными) +# Отключить конкретную политику (оставляет hooks установленными) failproofai policies --uninstall block-sudo # Удалить hooks из всех областей failproofai policies --uninstall --scope all -# Очистить путь пользовательских политик +# Очистить путь к пользовательским политикам failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/ru/cli/update.mdx b/docs/ru/cli/update.mdx new file mode 100644 index 00000000..c937453b --- /dev/null +++ b/docs/ru/cli/update.mdx @@ -0,0 +1,73 @@ +--- +title: Обновление после upgrade +description: "Завершите вторую половину upgrade, которую npm не может выполнить: мигрируйте home и синхронизируйте daemon" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +Это весь процесс upgrade. `npm` заменяет CLI; `failproofai update` делает всё остальное. + +## Почему нужна вторая команда + +`npm install -g` заменяет только одно — CLI. Два других компонента failproofai установки находятся вне пакета намеренно, и оба не перемещаются при запуске npm: + +- **`~/.failproofai/`**, ваши настройки, облачная регистрация, выбор политик и история. Новая версия может организовать это по-другому, и перестройка должна выполняться кодом, который знает обе структуры. +- **Бинарный файл daemon `failproofaid`**, расположенный по адресу + `~/.failproofai/bin/failproofaid-`. Он намеренно *не* находится в + `node_modules`: upgrade, который заменит файл во время работы сервиса, переведёт живой daemon на бинарный файл, собранный из другого исходного кода, а удаление пакета удалит его из-под сервиса, который затем будет crash-loop при каждой загрузке. + +Поэтому после одного только `npm install -g` CLI обновлён, а daemon — нет. +`failproofaid` отказывается запускаться против формата home, который он не понимает — явная версия этого несовпадения, а не скрытая — поэтому обе части нужно привести в соответствие. `failproofai update` — это этот шаг. + +## Что он делает + + + + Читает структуру, записанную в `~/.failproofai/VERSION`, и запускает шаги, которые приводят её к той, которую понимает эта версия. Обычно их нет — см. + [`failproofai migrate`](/ru/cli/migrate). + + + Из пакета платформы, который npm уже загрузил, где возможно (без сети), + иначе из ресурса release для этой точной версии с проверкой SHA-256 перед использованием. + + + Проверяется, а не предполагается — менеджер сервиса сообщает о процессе как активном в момент fork, что не то же самое, что работоспособность. + + + +## Параметры + +| Флаг | Эффект | +|------|--------| +| `--no-daemon` | Мигрируйте только home, оставляя daemon в текущей версии. | + + + `--no-daemon` оставляет daemon с рассогласованной версией. На машине, настроенной требовать daemon, каждое событие hook **fails closed**, если daemon не может ответить — а daemon, который отказывается запускаться против мигрированного home, не может ответить. Предпочтите позволить выполнить вторую половину daemon. + + +## Если что-то пошло не так + +Команда завершается с ненулевым кодом и указывает, какая часть не удалась. Два случая, которые стоит знать: + +- **Шаг миграции не завершился.** Home остаётся отмеченным с его *старой* + структурой, поэтому следующая команда повторит попытку — ни один home никогда не отмечается как текущий на основании частичной миграции. Копии ваших настроек и регистрации были сохранены перед запуском в `~/.failproofai/migrations/backup-layout/`. +- **Daemon не удалось перезапустить без пароля.** `sudo -n` используется намеренно, поэтому ничего никогда не запрашивает под дисплеем прогресса. Команда выводит точную строку для самостоятельного запуска. + + + Ничего здесь не требует интерактивного мастера настройки. Ваши настройки, облачная + регистрация и выбор политик сохраняются при upgrade, поэтому мигрированная машина + работает точно так же, как раньше — что особенно важно на машинах, где никто не сидит: + CI runner, fleet box, headless gateway. + + +## Автоматизация + +`failproofai update` не требует интерактивного ввода и безопасна для запуска, когда нечего делать — она сообщает "миграция не требовалась" и выходит с 0. Размещение её после каждого upgrade в скрипте provisioning или Dockerfile — это предусмотренный способ использования: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` при сборке образа, где еще нет сервиса для перезапуска.) \ No newline at end of file diff --git a/docs/ru/cli/version.mdx b/docs/ru/cli/version.mdx index cdae01fb..f233367e 100644 --- a/docs/ru/cli/version.mdx +++ b/docs/ru/cli/version.mdx @@ -1,4 +1,5 @@ --- +--- title: Проверка версии description: "Вывести установленную версию failproofai" --- diff --git a/docs/ru/configuration.mdx b/docs/ru/configuration.mdx index 445d0542..63ec7fbb 100644 --- a/docs/ru/configuration.mdx +++ b/docs/ru/configuration.mdx @@ -1,11 +1,11 @@ --- --- title: Конфигурация -description: "Формат файла конфигурации, система трёх уровней и правила слияния" +description: "Формат файла конфигурации, трёхуровневая система и правила объединения" icon: gear --- -failproofai использует JSON-файлы конфигурации для управления активными политиками, их поведением и местом загрузки пользовательских политик. Конфигурация разработана так, чтобы её было легко делить в команде — зафиксируйте её в репозитории, и каждый разработчик получит одну и ту же защиту агента. +failproofai использует JSON-файлы конфигурации для управления активными политиками, их поведением и источниками пользовательских политик. Конфигурация разработана так, чтобы быть удобной для совместной работы — добавьте её в репозиторий, и каждый разработчик получит одинаковую защиту агента. --- @@ -15,15 +15,15 @@ failproofai использует JSON-файлы конфигурации для | Уровень | Путь файла | Назначение | |---------|-----------|-----------| -| **project** | `.failproofai/policies-config.json` | Параметры для конкретного репозитория, добавлены в контроль версий | -| **local** | `.failproofai/policies-config.local.json` | Личные переопределения для репозитория, исключены из Git | -| **global** | `~/.failproofai/policies-config.json` | Пользовательские значения по умолчанию для всех проектов | +| **project** | `.failproofai/policies-config.json` | Параметры репозитория, фиксируются в контроле версий | +| **local** | `.failproofai/policies-config.local.json` | Персональные переопределения для репозитория, в gitignore | +| **global** | `~/.failproofai/policies-config.json` | Параметры пользователя для всех проектов | -Когда failproofai получает событие hook, он загружает и объединяет все три файла, которые существуют для текущей рабочей директории. +Когда failproofai получает событие хука, он загружает и объединяет все три файла (если они существуют) для текущей директории. -### Правила слияния +### Правила объединения -**`enabledPolicies`** — объединение всех трёх уровней. Политика, включённая на любом уровне, активна. +**`enabledPolicies`** — объединение всех трёх уровней. Политика, активированная на любом уровне, активна. ```text project: ["block-sudo"] @@ -33,28 +33,28 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← дедублицированное объединение ``` -**`policyParams`** — первый уровень, определивший параметры для политики, полностью побеждает. Глубокого слияния значений внутри параметров политики не происходит. +**`policyParams`** — первый уровень, определяющий параметры для политики, полностью побеждает. Глубокого объединения значений внутри параметров политики нет. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project побеждает, global игнорируется +resolved: { allowPatterns: ["sudo apt-get update"] } ← побеждает project, global игнорируется ``` ```text -project: (запись block-sudo отсутствует) -local: (запись block-sudo отсутствует) +project: (no block-sudo entry) +local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← переходит на global ``` -**`customPoliciesPaths` / `customPoliciesPath`** — первый уровень, определивший любую форму, побеждает. +**`customPoliciesPaths` / `customPoliciesPath`** — первый уровень, определяющий любую форму, побеждает. -**`disabledCustomPolicies`** — объединение всех уровней. Панель управления записывает сюда квалифицированный по источнику ID при отключении отдельной политики из явного или конвенционального файла политик. Политики, не указанные в списке, остаются включёнными по умолчанию; ID включают источник файла, поэтому политики с одинаковыми названиями в разных файлах можно управлять независимо. +**`disabledCustomPolicies`** — объединение всех уровней. Панель управления пишет сюда квалифицированный по источнику ID при отключении отдельной политики из явного или условного файла политик. Политики, не указанные в списке, остаются включенными по умолчанию; ID включают источник, так что одноимённые политики в нескольких файлах можно контролировать независимо. -**`llm`** — первый уровень, определивший его, побеждает. +**`llm`** — первый уровень, определяющий это, побеждает. --- @@ -105,87 +105,94 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← переходит Тип: `string[]` -Список имён политик для включения. Имена должны точно совпадать с идентификаторами политик, показываемыми `failproofai policies`. Полный список см. в [Встроенные политики](/ru/built-in-policies). +Список имён политик для активации. Имена должны точно совпадать с идентификаторами политик, показываемыми `failproofai policies`. Полный список см. в разделе [Встроенные политики](/ru/built-in-policies). -Политики, не указанные в `enabledPolicies`, неактивны, даже если они содержат записи в `policyParams`. +Политики, не входящие в `enabledPolicies`, неактивны, даже если имеют записи в `policyParams`. ### `policyParams` Тип: `Record>` -Переопределения параметров для каждой политики. Внешний ключ — это имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует доступные параметры в [Встроенные политики](/ru/built-in-policies). +Переопределения параметров для каждой политики. Внешний ключ — имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует доступные параметры в разделе [Встроенные политики](/ru/built-in-policies). -Если политика имеет параметры, но вы их не указали, используются встроенные по умолчанию значения политики. Пользователи, которые вообще не настраивают `policyParams`, получают поведение, идентичное предыдущим версиям. +Если у политики есть параметры, но вы их не указываете, используются встроенные значения по умолчанию. Пользователи, которые не конфигурируют `policyParams` вообще, получают идентичное поведение предыдущим версиям. -Неизвестные ключи внутри блока параметров политики молча игнорируются при срабатывании hook, но отмечаются как предупреждения при запуске `failproofai policies`. +Неизвестные ключи внутри блока параметров политики молча игнорируются при срабатывании хука, но помечаются как предупреждения при запуске `failproofai policies`. -#### `hint` (сквозной параметр) +#### `hint` (кросс-политика) -Тип: `string` (опционально) +Тип: `string` (необязательный) -Сообщение, добавляемое к причине, когда политика возвращает `deny` или `instruct`. Используйте его, чтобы дать Claude действенное руководство без изменения самой политики. +Сообщение, добавляемое к причине, когда политика возвращает `deny` или `instruct`. Используйте его, чтобы дать Claude действенные рекомендации без изменения самой политики. -Работает с любым типом политики — встроенной, пользовательской (`custom/`), проектной конвенции (`.failproofai-project/`) или пользовательской конвенции (`.failproofai-user/`). +Работает с любым типом политики — встроенной, пользовательской (`custom/`), проектной условной (`.failproofai-project/`) или пользовательской условной (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "Попробуйте создать свежую ветку вместо этого." + "hint": "Попробуйте создать новую ветку вместо этого." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], "hint": "Используйте apt-get напрямую без sudo." }, "custom/my-policy": { - "hint": "Сначала попросите одобрение у пользователя." + "hint": "Сначала попросите разрешение у пользователя." } } } ``` -Когда `block-force-push` отклоняет, Claude видит: *«Force-push заблокирован. Попробуйте создать свежую ветку вместо этого.»* +Когда `block-force-push` отклоняет, Claude видит: *«Force-push заблокирован. Попробуйте создать новую ветку вместо этого.»* -Не-строковые значения и пустые строки молча игнорируются. Если `hint` не установлен, поведение остаётся неизменным (обратная совместимость). +Не-строковые значения и пустые строки молча игнорируются. Если `hint` не установлен, поведение не изменяется (обратная совместимость). ### `customPoliciesPath` Тип: `string` (абсолютный путь) -Путь к файлу JavaScript, содержащему пользовательские hook-политики. Устанавливается автоматически `failproofai policies --install --custom ` (путь разрешается на абсолютный перед сохранением). +Путь к JavaScript-файлу, содержащему пользовательские политики хука. Устанавливается автоматически `failproofai policies --install --custom ` (путь разрешается до абсолютного перед сохранением). -Файл загружается заново при каждом событии hook — кэширования нет. Подробности разработки см. в [Пользовательские политики](/ru/custom-policies). +Файл загружается заново при каждом событии хука — кеширования нет. Подробности см. в разделе [Пользовательские политики](/ru/custom-policies). -### Политики, основанные на конвенции +### Условные политики -Помимо явного `customPoliciesPath`, failproofai автоматически обнаруживает и загружает файлы политик из директорий `.failproofai/policies/`: +Кроме явного `customPoliciesPath`, failproofai автоматически обнаруживает и загружает файлы политик из директорий `.failproofai/policies/`: -| Уровень | Директория | Уровень конфигурации | -|---------|-----------|-----------| -| Project | `.failproofai/policies/` | Общее с командой через контроль версий | -| User | `~/.failproofai/policies/custom-policies/` | Личное, применяется ко всем проектам | +| Уровень | Директория | Уровень | +|---------|-----------|---------| +| Проект | `.failproofai/policies/` | Общее с командой через контроль версий | +| Пользователь | `~/.failproofai/policies/` | Персональное, применяется ко всем проектам | - Директория на уровне пользователя переместилась на уровень ниже при - переорганизации домашней директории. Файлы, оставленные в старой - `~/.failproofai/policies/`, автоматически перемещаются в `custom-policies/` - при первом запуске любой команды `failproofai` после обновления, и команда - сообщает вам, какие файлы она переместила. + Размещайте политики прямо в `~/.failproofai/policies/`. Папка + `cloud-policies/` рядом содержит политики, развёрнутые вашей организацией + на этой машине — обнаружение не спускается в подпапки, поэтому она + никогда не сканируется, и ничто, что вы поместите в `policies/`, не + может конфликтовать с ней. + + Если вы обновляетесь с версии, использующей + `~/.failproofai/policies/custom-policies/`, всё в этой папке — файлы + политик, любые `lib/` вспомогательные модули, которые они импортируют, и + все файлы данных, которые они читают — автоматически перемещается обратно + при первом запуске любой команды `failproofai`, и команда скажет вам, что + она переместила. -**Совпадение файлов:** загружаются только файлы, совпадающие с `*policies.{js,mjs,ts}` (например, `security-policies.mjs`, `workflow-policies.js`). Другие файлы в директории игнорируются. +**Совпадение файлов:** Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}` (например, `security-policies.mjs`, `workflow-policies.js`). Другие файлы в директории игнорируются. -**Конфигурация не требуется:** конвенциональные политики не требуют записей в `policies-config.json`. Просто поместите файлы в директорию, и они будут подхвачены при следующем событии hook. +**Конфигурация не требуется:** Условные политики не требуют записей в `policies-config.json`. Просто поместите файлы в директорию и они будут подобраны при следующем событии хука. -**Объединённая загрузка:** сканируются обе директории конвенциональных политик — проектная и пользовательская. Все совпадающие файлы с обоих уровней загружаются (в отличие от `customPoliciesPath`, которая использует принцип «первый уровень побеждает»). +**Объединённая загрузка:** Сканируются обе директории условных политик — проектная и пользовательская. Все совпадающие файлы с обоих уровней загружаются (в отличие от `customPoliciesPath`, которая использует первый-уровень-побеждает). -Подробности и примеры см. в [Пользовательские политики](/ru/custom-policies). +Подробности и примеры см. в разделе [Пользовательские политики](/ru/custom-policies). ### `llm` -Тип: `object` (опционально) +Тип: `object` (необязательный) -Конфигурация LLM-клиента для политик, совершающих вызовы ИИ. Не требуется для большинства установок. +Конфигурация LLM-клиента для политик, которые делают вызовы AI. Не требуется для большинства настроек. ```json { @@ -200,24 +207,24 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← переходит ## Управление конфигурацией из CLI -Команды `policies --install` и `policies --uninstall` записывают в файл настроек hook вашего agent CLI (входные точки hook), тогда как `policies-config.json` — это файл, которым вы управляете непосредственно. Они разделены: - -- **Параметры Agent CLI** — говорит агенту вызывать `failproofai --hook ` при каждом использовании инструмента: - - **Claude Code**: `~/.claude/settings.json` (пользователь), `/.claude/settings.json` (проект), `/.claude/settings.local.json` (локально) - - **OpenAI Codex**: `~/.codex/hooks.json` (пользователь), `/.codex/hooks.json` (проект) — у Codex нет локального уровня - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (пользователь), `/.github/hooks/failproofai.json` (проект) — у Copilot нет локального уровня. Записи hook используют поля команды `bash`/`powershell` Copilot с ключом OS и `timeoutSec`; файл содержит маркер `version: 1` на верхнем уровне. Поддержка Copilot CLI находится в **бета**, пока мы проверяем схему записей `events.jsonl` (которая не указана в публичной документации) против большего количества реальных сессий. **VS Code Copilot Chat режим агента (Preview)** читает конфиги hook из `.github/hooks/*.json`, `~/.copilot/hooks/*.json` и `~/.claude/settings.json` (управляется параметром `chat.hookFilesLocations`) используя ту же Claude-подобную контрактную форму `{hookSpecificOutput:{permissionDecision:"deny",…}}` — точно те пути, которые `copilot`-интеграция и `claude`-интеграция (`~/.claude/settings.json`) уже записывают, поэтому `failproofai policies --install --cli copilot` (или `--cli claude`) **уже реализует в режиме VS Code agent** без отдельной интеграции `vscode` (подтверждено live из логов обнаружения VS Code). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (пользователь), `/.cursor/hooks.json` (проект) — у Cursor нет локального уровня. Записи hook используют Claude-подобную форму `{type, command, timeout}` (без разделения `bash`/`powershell`), но хранятся с ключами в camelCase (`preToolUse`, `beforeSubmitPrompt`, …) в плоском массиве в соответствии со [схемой hooks](https://cursor.com/docs/hooks) Cursor; файл содержит маркер `version: 1` на верхнем уровне. Обработчик канонизирует camelCase → PascalCase через `CURSOR_EVENT_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Поддержка Cursor Agent находится в **бета**, пока мы проверяем формат транскрипта Cursor на диске (не указан в публичной документации) против большего количества реальных установок. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (пользователь), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (проект) — у OpenCode нет локального уровня. В отличие от остальных пяти CLI, OpenCode **не имеет системы внешних hook-команд**: он загружает встроенные JS/TS плагины, явно зарегистрированные через массив `plugin: []` в `opencode.json` (автообнаружение из `.opencode/plugins/` **не** является способом загрузки плагинов в opencode v1.14.33). Install размещает небольшой сгенерированный шим плагина, который вызывает binary failproofai через subprocess и переводит JSON-ответ binary обратно в семантику плагина: `throw new Error()` для отклонения tool-события (отменяет вызов инструмента), `client.session.prompt(...)` для `instruct` И для `Stop` / `SubagentStop` отклонения (отправляет причину отклонения как следующее сообщение пользователя — единственный канал force-retry, поскольку `session.idle` является только уведомлением и выброс из неё не имеет эффекта), и no-op для allow. Шим канонизирует имена инструментов (lowercase → PascalCase через `OPENCODE_TOOL_MAP`) и ключи input-аргументов инструмента (camelCase → snake_case через `OPENCODE_TOOL_INPUT_MAP` для `Read` / `Write` / `Edit`, например `filePath` → `file_path`, `oldString` → `old_string`) перед отправкой на binary, поэтому встроенные проверки путей, такие как `block-read-outside-cwd`, `block-env-files` и `block-secrets-write`, срабатывают без изменений на вызовах инструментов OpenCode. Сессии хранятся в SQLite DB OpenCode в `~/.local/share/opencode/opencode.db`; просмотрщик сессий панели управления читает их через `opencode db --format json` и `opencode export `. Поддержка OpenCode находится в **бета**, пока мы проверяем поведение на разных версиях и против большего количества реальных сессий. См. [документацию плагинов OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (пользователь), `/.pi/settings.json` (проект) — у Pi нет локального уровня. Pi загружает пакеты расширений TypeScript при запуске; файл параметров — это плоский массив строк `{"packages": ["./relative/path", …]}`. failproofai записывает одну запись packages-массива, указывающую на его распакованную директорию `pi-extension/`. Расширение внутри подписывается на события Pi `tool_call` / `user_bash` / `input` / `session_start` и вызывает оболочку `failproofai --hook --cli pi`; обработчик канонизирует underscore_lower_snake_case → PascalCase через `PI_EVENT_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Аргументы input инструмента также канонизируются через `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit предоставляют `path` вместо `file_path`; маппирование ключа верхнего уровня позволяет `block-env-files` и `block-secrets-write` срабатывать — `block-read-outside-cwd` уже имел fallback `path`). Поддержка Pi находится в **бета**, пока API расширений Pi и layout журнала сессии стабилизируются. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**только пользовательский уровень** — у Hermes нет проектной/локальной конфигурации). Hermes — это **шлюз** Slack/Telegram, поэтому одна установка перехватывает вызовы инструментов со всех платформ (Slack/Telegram/cli/cron) **и** внутренних субагентов. Записи hook — это пара `{command, timeout}` (timeout в **секундах**) под картой `hooks:`, ключи которой — это события Hermes в snake_case (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); обработчик канонизирует события через `HERMES_EVENT_MAP` и имена инструментов через `HERMES_TOOL_MAP`, поэтому встроенные политики срабатывают без изменений. Конфиг редактируется через comment-preserving YAML `Document` round-trip, поэтому другие параметры оператора остаются, и install устанавливает `hooks_auto_accept: true`, поэтому безголовой шлюз (нет TTY) запускает hooks без запроса согласия. Оценивающий выпускает контрактную форму Hermes `{"decision":"block","reason"}` на stdout (Hermes игнорирует exit codes). **Ограничения:** у Hermes нет turn-end события `Stop`, поэтому встроенные `require-*-before-stop` никогда не срабатывают для неё (неприменимо, не сломано); `instruct` снижается до allow-with-logged-note (нет канала дополнительного контекста); и редакция выходных секретов (`sanitize-*`) не может переписать выход инструмента через shell-hook контракт. Hermes — также **offline audit** источник — панель управления читает её сессии шлюза напрямую из `~/.hermes/state.db`. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**только пользовательский уровень** — у OpenClaw нет проектной/локальной конфигурации). Как Hermes, OpenClaw является self-hosted **шлюзом** с поддержкой нескольких каналов, поэтому одна установка перехватывает вызовы инструментов со всех каналов и внутренних субагентов. Реализация работает через **встроенные plugin hooks** OpenClaw (её file-based internal hooks только для наблюдения и не могут блокировать), поэтому — как OpenCode/Pi — failproofai поставляет статический пакет `openclaw-plugin/`, который async-запускает binary failproofai и переводит вердикт. Install регистрирует поставленную директорию плагина в `openclaw.json`'s `plugins.load.paths[]` и включает её под `plugins.entries.failproofai` (с `hooks.allowConversationAccess: true`, требуется для raw-conversation hooks). Оценивающий выпускает плоский `{permission, reason}` вердикт и шим маппирует его в собственную форму возврата каждого hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), и `before_agent_finalize → {action:"revise", reason}` (**Stop** — real turn-end gate, поэтому встроенные `require-*-before-stop` **реализуют** на OpenClaw, в отличие от Hermes). События и имена инструментов канонизируются на стороне binary через `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …), поэтому встроенные политики срабатывают без изменений; шим fails open при любой ошибке spawn/parse/timeout. OpenClaw — также **offline audit** источник — панель управления читает его JSONL сессии в `~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (пользователь), `/.factory/hooks.json` (проект) — у Factory нет локального уровня. droid поставляет систему внешних hook-команд в стиле Claude, но с двумя особенностями, проверенными live против droid v0.171.0: (1) имена событий находятся на **верхнем уровне** `hooks.json` — нет **обёртки `"hooks"`** (droid её отклоняет); инструментальные события (`PreToolUse`/`PostToolUse`) имеют `"matcher": "*"`, non-инструментальные события его пропускают. (2) Deny управляется hook **exit code 2 + stderr**, а не JSON решением — ветвь `factory` оценивающего возвращает exit 2 для tool/prompt событий и `{decision:"block", reason}` только на turn-end событии `Stop` (единственный force-retry канал droid). События уже в PascalCase (нет event map) и payload в Claude snake_case; только имена инструментов канонизируются через `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory — также **offline audit** источник — панель управления читает её on-disk JSONL сессии в `~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (пользователь), `/.devin/config.json` (проект) — у Devin нет локального уровня. Devin — это **чистый Claude-клон**, проверенный live против devin v3000.1.27: он использует стандартную Claude схему с обёрткой `"hooks"` (записи merge-preserving, поэтому другие ключи файла конфигурации — `org_id`, `theme_mode`, … — остаются), уже-PascalCase имена событий (нет event map, нет ветви обработчика) и Claude snake_case stdin payload (нет нормализации). Ветвь `devin` оценивающего отклоняет с `{"decision":"block","reason"}` JSON на stdout при exit 0 для **каждого** события (проверено — блокировка переопределила `--permission-mode dangerous`); на turn-end событии `Stop` причина содержит обязательный force-retry текст действия, поэтому встроенные `require-*-before-stop` реализуют. Только имена инструментов канонизируются через `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` уже канонический). Devin — также **offline audit** источник — панель управления читает его SQLite сессии в `~/.local/share/devin/cli/sessions.db` (каждая строка `sessions` содержит реальный `working_directory`, поэтому сессии группируются по проекту cwd, как Claude). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (пользователь), `/.agents/hooks.json` (проект) — у Antigravity нет локального уровня. В отличие от Factory/Devin, Antigravity имеет **собственный** контракт (не Claude-клон), проверенный live против agy v1.1.2. `hooks.json` использует **named-hook** схему: верхнеуровневый ключ — это имя hook'а (*`"failproofai"`*) чьё значение — событие→handlers map — инструментальные события (`PreToolUse`/`PostToolUse`) оборачивают handlers в `{matcher:"*", hooks:[…]}`, тогда как `PreInvocation`/`Stop` — это **плоские** arrays handlers (другие named hooks сохраняются). Stdin payload — это **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai нормализует его в snake_case перед запуском политик и маппирует PascalCase аргументы `run_command` (`CommandLine`/`Cwd`) через `ANTIGRAVITY_TOOL_INPUT_MAP`. Ветвь `antigravity` оценивающего использует собственные формы ответов Antigravity: `{decision:"deny", reason}` блокирует tool/prompt (exit 0), `{decision:"continue", reason}` на turn-end событии `Stop` re-входит в loop (поэтому встроенные `require-*-before-stop` реализуют), и `{injectSteps:[{ephemeralMessage}]}` инжектит инструкцию на `PreInvocation` (→ `UserPromptSubmit`). Имена инструментов канонизируются через `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity — также **offline audit** источник — панель управления читает его plain-JSONL транскрипты в `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (индекс разговора в `conversation_summaries.db`). - - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (пользователь), `/.agents/plugins/failproofai/hooks/hooks.json` (проект) — у Goose нет локального уровня. Реализация использует **hooks** систему Goose, кроссагентную **Open Plugins** спецификацию: installer просто размещает `failproofai` plugin dir и Goose auto-открывает его при запуске (self-регистрируя его в `~/.config/goose/config.yaml`). `hooks.json` использует Open Plugins схему **с** верхнеуровневой обёрткой `"hooks"`, и matcher — **опущен** на каждом событии — голая `"*"` — это невалидный regex, который ничего не совпадает (проверено live против goose v1.43.0). Имена событий уже PascalCase (нет event map); stdin payload использует `event`/`working_dir`, которые обработчик нормализует в `hook_event_name`/`cwd`. Ветвь `goose` оценивающего отклоняет с `{"decision":"block","reason"}` JSON на stdout при exit 0, honoured на событии **`PreToolUse`** только (поставляется в goose ≥ v1.37.0) — которое срабатывает для shell tool **и внутри делегированных субагентов**, поэтому это единственная достаточная point отклонения; любая другая ошибка hook fails **open**. У Goose нет события **`Stop`**, поэтому встроенные `require-*-before-stop` не применяются (как с Hermes). Имена инструментов канонизируются через `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) и ключи path через `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose — также **offline audit** источник — панель управления читает его SQLite сессии в `~/.local/share/goose/sessions/sessions.db` (каждая строка `sessions` содержит реальный `working_dir`, поэтому сессии группируются по проекту cwd, как Devin; `--no-session` scratch runs отфильтрованы). -- **`policies-config.json`** — сообщает failproofai, какие политики оценивать и с какими параметрами (общее для всех agent CLI) - -Передайте `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` для выбора конкретного агента (пробелом-разделённый или повторённый для любого подмножества): +Команды `policies --install` и `policies --uninstall` пишут в файл параметров хука вашего агента CLI (точки входа хука), тогда как `policies-config.json` — это файл, которым вы управляете непосредственно. Это два разных файла: + +- **Параметры агента CLI** — указывает агенту вызывать `failproofai --hook ` при каждом использовании инструмента: + - **Claude Code**: `~/.claude/settings.json` (пользователь), `/.claude/settings.json` (проект), `/.claude/settings.local.json` (локальный) + - **OpenAI Codex**: `~/.codex/hooks.json` (пользователь), `/.codex/hooks.json` (проект) — Codex не имеет локального уровня + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (пользователь), `/.github/hooks/failproofai.json` (проект) — Copilot без локального уровня. Записи хука используют поля команд Copilot, привязанные к ОС (`bash`/`powershell`) с `timeoutSec`; файл содержит маркер верхнего уровня `version: 1`. Поддержка Copilot CLI — **beta**, пока мы проверяем схему записи `events.jsonl` (которая не указана в публичных документах) против большего количества реальных сессий. **VS Code Copilot Chat агент режим (Preview)** читает конфигурации хука из `.github/hooks/*.json`, `~/.copilot/hooks/*.json` и `~/.claude/settings.json` (управляется параметром `chat.hookFilesLocations`), используя тот же контракт, привязанный к Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — точные пути, которые интеграция `copilot` и интеграция `claude` (`~/.claude/settings.json`) уже пишут, поэтому `failproofai policies --install --cli copilot` (или `--cli claude`) **уже обеспечивает в VS Code режиме агента** без отдельной интеграции `vscode` (подтверждено живыми логами обнаружения VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (пользователь), `/.cursor/hooks.json` (проект) — Cursor без локального уровня. Записи хука используют форму `{type, command, timeout}`, похожую на Claude (без разделения `bash`/`powershell`), но хранятся под camelCase ключами событий (`preToolUse`, `beforeSubmitPrompt`, …) в плоском массиве согласно [схеме хуков](https://cursor.com/docs/hooks) Cursor; файл содержит маркер верхнего уровня `version: 1`. Обработчик канонизирует camelCase → PascalCase через `CURSOR_EVENT_MAP`, так что существующие встроенные политики срабатывают без изменений. Поддержка Cursor Agent — **beta**, пока мы проверяем формат записи транскрипта Cursor на диске (не указан в публичных документах) против большего количества реальных установок. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (пользователь), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (проект) — OpenCode без локального уровня. В отличие от остальных пяти CLI, OpenCode **не имеет системы внешних хуков**: он загружает встроенные JS/TS плагины, явно зарегистрированные через массив `plugin: []` в `opencode.json` (автообнаружение из `.opencode/plugins/` — **не** то, как плагины загружаются на opencode v1.14.33). Установка размещает небольшой сгенерированный шим плагина, который вызывает бинарный файл failproofai подпроцессом и переводит JSON-ответ бинарного файла Claude-формы обратно в семантику плагина: `throw new Error()` для отклонения события инструмента (отменяет вызов инструмента), `client.session.prompt(...)` для `instruct` И для отклонения `Stop` / `SubagentStop` (отправляет причину отклонения как следующее сообщение пользователя — единственный канал форсированного повтора, так как `session.idle` — уведомление только и выброс из него — нет-оп), и нет-оп для allow. Шим канонизирует имена инструментов (нижний регистр → PascalCase через `OPENCODE_TOOL_MAP`) и ключи входа инструмента (camelCase → snake_case через `OPENCODE_TOOL_INPUT_MAP` для `Read` / `Write` / `Edit`, например `filePath` → `file_path`, `oldString` → `old_string`) перед передачей бинарному файлу, так что встроенные проверки пути вроде `block-read-outside-cwd`, `block-env-files` и `block-secrets-write` срабатывают без изменений при вызовах инструмента OpenCode. Сессии находятся в SQLite БД opencode по адресу `~/.local/share/opencode/opencode.db`; зритель сессий панели управления читает их через `opencode db --format json` и `opencode export `. Поддержка OpenCode — **beta**, пока мы проверяем поведение во всех версиях и против большего количества реальных сессий. См. [документацию плагинов OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (пользователь), `/.pi/settings.json` (проект) — Pi без локального уровня. Pi загружает пакеты расширений TypeScript при запуске; файл параметров — это плоский строковый массив `{"packages": ["./relative/path", …]}`. failproofai пишет единственную запись packages-array, указывающую на встроенный каталог `pi-extension/`. Расширение внутри подписывается на события `tool_call` / `user_bash` / `input` / `session_start` Pi и вызывает через shell `failproofai --hook --cli pi`; обработчик канонизирует underscore_lower_snake_case → PascalCase через `PI_EVENT_MAP`, так что существующие встроенные политики срабатывают без изменений. Аргументы входа инструмента также канонизируются через `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit доставляют `path` вместо `file_path`; отображение верхнего уровня ключа позволяет `block-env-files` и `block-secrets-write` срабатывать — `block-read-outside-cwd` уже имел fallback `path`). Поддержка Pi — **beta**, пока API расширения Pi и макет журнала сессии стабилизируются. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**только пользовательский уровень** — Hermes без конфигурации проекта/локальной). Hermes — это **шлюз** Slack/Telegram, так что одна установка перехватывает вызовы инструментов с каждой платформы (Slack/Telegram/cli/cron) **и** внутренних подагентов. Записи хука — это пара `{command, timeout}` (тайм-аут в **секундах**) под картой `hooks:`, ключ которой — события snake_case Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); обработчик канонизирует события через `HERMES_EVENT_MAP` и имена инструментов через `HERMES_TOOL_MAP`, так что встроенные политики срабатывают без изменений. Конфигурация редактируется через сохраняющий комментарии YAML `Document` цикл, так что другие параметры оператора сохраняются, и установка устанавливает `hooks_auto_accept: true`, так что безголовый шлюз (без TTY) запускает хуки без запроса согласия. Оценщик выдаёт контракт stdout Hermes `{"decision":"block","reason"}` (Hermes игнорирует коды выхода). **Ограничения:** Hermes не имеет события конца хода `Stop`, так что встроенные `require-*-before-stop` никогда не срабатывают для него (неприменимо, не сломано); `instruct` деградирует до allow-with-logged-note (без дополнительного-контекстного канала); и редакция секретов вывода (`sanitize-*`) не может переписать вывод инструмента через контракт shell-hook. Hermes — **также** источник **аудита** в режиме offline — панель управления читает его сессии шлюза прямо из `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**только пользовательский уровень** — OpenClaw без конфигурации проекта/локальной). Как Hermes, OpenClaw — это самостоящийся **шлюз** многоканальный, так что одна установка перехватывает вызовы инструментов с каждого канала и его внутренних подагентов. Применение запускается через **встроенные хуки плагина** OpenClaw (его файловые встроенные хуки только для наблюдения и не могут блокировать), так что — как OpenCode/Pi — failproofai поставляется со статическим пакетом `openclaw-plugin/`, который асинхронно вызывает бинарный файл failproofai и переводит вердикт. Установка регистрирует поставляемый каталог плагина в `openclaw.json`'s `plugins.load.paths[]` и включает его под `plugins.entries.failproofai` (с `hooks.allowConversationAccess: true`, требуется для raw-conversation хуков). Оценщик выдаёт плоский вердикт `{permission, reason}` и шим отображает его на нативную форму возврата каждого хука: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), и `before_agent_finalize → {action:"revise", reason}` (**Stop** — реальные врата конца хода, так что встроенные `require-*-before-stop` **обеспечивают** на OpenClaw, в отличие от Hermes). События и имена инструментов канонизируют бинарно-сторону через `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …), так что встроенные политики срабатывают без изменений; шим не срабатывает открытым при любой spawn/parse/timeout ошибке. OpenClaw — **также** источник **аудита** в режиме offline — панель управления читает его сессии JSONL по адресу `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (пользователь), `/.factory/hooks.json` (проект) — Factory без локального уровня. droid поставляется с системой хуков внешних команд, похожей на Claude, но с двумя особенностями, проверенными живыми против droid v0.171.0: (1) имена событий находятся на **верхнем уровне** `hooks.json` — там **нет `"hooks"` обёртки** (droid отклоняет её); события инструмента (`PreToolUse`/`PostToolUse`) содержат `"matcher": "*"`, события не-инструмента его опускают. (2) Отклонение управляется кодом выхода хука **2 + stderr**, не JSON вердиктом — ветка `factory` оценщика возвращает выход 2 для событий инструмента/подсказки и `{decision:"block", reason}` только на событии конца хода `Stop` (единственный канал форсированного повтора droid). События уже PascalCase (нет event map) и полезная нагрузка — Claude snake_case; канонизируются только имена инструментов через `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory — **также** источник **аудита** в режиме offline — панель управления читает его сессии JSONL на диске по адресу `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (пользователь), `/.devin/config.json` (проект) — Devin без локального уровня. Devin — это **чистый Claude-клон**, проверенный живыми против devin v3000.1.27: он использует стандартную схему Claude с `"hooks"`-обёрткой (записи сохраняют слияние, так что другие ключи файла конфигурации — `org_id`, `theme_mode`, … — выживают), уже-PascalCase имена событий (нет event map, нет ветки обработчика) и Claude snake_case полезную нагрузку stdin (нет нормализации). Ветка `devin` оценщика отклоняет с JSON `{"decision":"block","reason"}` на stdout при выходе 0 для **каждого** события (проверено — блокировка переопределила `--permission-mode dangerous`); на событии конца хода `Stop` причина содержит ОБЯЗАТЕЛЬНОЕ-ДЕЙСТВИЕ wording форсированного повтора, так что встроенные `require-*-before-stop` обеспечивают. Канонизируются только имена инструментов через `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` уже canonical). Devin — **также** источник **аудита** в режиме offline — панель управления читает его сессии SQLite по адресу `~/.local/share/devin/cli/sessions.db` (каждая строка `sessions` несёт реальный `working_directory`, так что сессии группируются по проекту cwd как Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (пользователь), `/.agents/hooks.json` (проект) — Antigravity без локального уровня. В отличие от Factory/Devin, Antigravity имеет свой **собственный** контракт (не Claude-клон), проверенный живыми против agy v1.1.2. `hooks.json` использует **named-hook** схему: верхний уровень ключа — имя хука *name* (`"failproofai"`), значение которого — карта событие→handlers — события инструмента (`PreToolUse`/`PostToolUse`) оборачивают handlers в `{matcher:"*", hooks:[…]}`, тогда как `PreInvocation`/`Stop` — **плоские** массивы handler (другие именованные хуки сохраняются). Полезная нагрузка stdin — **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai нормализует это к snake_case перед запуском политик и отображает PascalCase аргументы `run_command` (`CommandLine`/`Cwd`) через `ANTIGRAVITY_TOOL_INPUT_MAP`. Ветка `antigravity` оценщика использует собственные формы ответов Antigravity: `{decision:"deny", reason}` блокирует инструмент/подсказку (выход 0), `{decision:"continue", reason}` на событии конца хода `Stop` повторно входит в цикл (так что встроенные `require-*-before-stop` обеспечивают) и `{injectSteps:[{ephemeralMessage}]}` вводит инструкцию на `PreInvocation` (→ `UserPromptSubmit`). Имена инструментов канонизируют через `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity — **также** источник **аудита** в режиме offline — панель управления читает его плоские транскрипты JSONL по адресу `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (индекс бесед в `conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (пользователь), `/.agents/plugins/failproofai/hooks/hooks.json` (проект) — Goose без локального уровня. Применение использует систему **hooks** Goose, кросс-агентную спецификацию **Open Plugins**: установщик просто размещает каталог плагина `failproofai` и Goose автообнаруживает его при запуске (самостоятельно регистрируя его в `~/.config/goose/config.yaml`). `hooks.json` использует Open Plugins схему **с** обёрткой верхнего уровня `"hooks"`, и matcher **опускается** при каждом событии — голый `"*"` — неправильный regex, который ничего не соответствует (проверено живыми против goose v1.43.0). Имена событий уже PascalCase (нет event map); полезная нагрузка stdin использует `event`/`working_dir`, которые обработчик нормализует к `hook_event_name`/`cwd`. Ветка `goose` оценщика отклоняет с JSON `{"decision":"block","reason"}` на stdout при выходе 0, чтимая на событии **`PreToolUse`** только (поставляется в goose ≥ v1.37.0) — которое срабатывает для shell инструмента **и внутри делегированных подагентов**, так что это единственная достаточная точка отклонения; любая другая ошибка хука не срабатывает **открыто**. Goose **без события `Stop`**, так что встроенные `require-*-before-stop` не применяются (как с Hermes). Имена инструментов канонизируют через `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) и ключи пути через `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose — **также** источник **аудита** в режиме offline — панель управления читает его сессии SQLite по адресу `~/.local/share/goose/sessions/sessions.db` (каждая строка `sessions` несёт реальный `working_dir`, так что сессии группируются по проекту cwd как Devin; запуски `--no-session` scratch фильтруются). +- **`policies-config.json`** — указывает failproofai, какие политики оценивать и с какими параметрами (общее для всех агентов CLI) + +Передайте `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`, чтобы нацелиться на конкретного агента (разделённые пробелом или повторённые для любого подмножества): ```bash failproofai policies --install --cli codex --scope project @@ -234,20 +241,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Когда `--cli` опущен, `failproofai` обнаруживает какие agent CLI установлены (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +Когда `--cli` опущен, failproofai обнаруживает, какие агенты CLI установлены (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): - **Один CLI обнаружен** — автоматически выбирает этот CLI без запроса. -- **Несколько CLI обнаружено** в интерактивном терминале — показывает prompt одиночного выбора со стрелками, сгруппированный в секцию `Detected (N)` (с aggregate row `Install for all N detected` + каждый обнаруженный CLI отдельно) и секцию `Not installed (M) · install hooks ahead of time`, выводящую каждый необнаруженный поддерживаемый CLI как forward-install опцию (↑↓ для движения, Enter для выбора, ^C для выхода). Flow uninstall показывает только секцию Detected. -- **Несколько CLI обнаружено** в non-interactive запуске (CI, нет TTY) — устанавливает для всех обнаруженных CLI без запроса. -- **Ничего не обнаружено** — fallback на `claude`, с предупреждением, что ни один agent binary не найден в PATH; hook команда всё ещё записывается, поэтому она активируется как только вы установите один. +- **Несколько CLI обнаружено** в интерактивном терминале — показывает подсказку одиночного выбора со стрелками, сгруппированную в секцию `Detected (N)` (со строкой агрегата `Install for all N detected` + каждый обнаруженный CLI отдельно) и секцию `Not installed (M) · install hooks ahead of time`, перечисляющую каждый необнаруженный поддерживаемый CLI как опцию forward-install (↑↓ для перемещения, Enter для выбора, ^C для выхода). Поток uninstall показывает только секцию Detected. +- **Несколько CLI обнаружено** в неинтерактивном запуске (CI, нет TTY) — устанавливает для всех обнаруженных CLI без запроса. +- **Ни один не обнаружен** — откатывается на `claude` с предупреждением, что бинарный агент не найден в PATH; команда хука всё ещё пишется, так что она активируется, как только вы установите один. + +Вы можете редактировать `policies-config.json` напрямую в любое время; изменения вступают в силу немедленно при следующем событии хука без необходимости перезагрузки. + +## Обновления сохраняют вашу конфигурацию + +Новая версия failproofai может организовать `~/.failproofai/` иначе. Когда это происходит, первая команда после обновления мигрирует директорию, и **ваша конфигурация переносится, не сбрасывается**: + +| Сохранено | Перестроено | +|---|---| +| Ваш выбор политик и параметры (`policies-config.json`) | Кэш аудита | +| Ваши параметры, включая `daemon.configured` и доп. пути захвата (`config.json`) | Развёрнутые облачные политики — перезагруженные и проверенные по дайджесту при следующем опросе | +| Ваша облачная запись (`credentials.json`) | Состояние scratch демона | +| Ваши собственные файлы политик в `policies/` и вспомогательные модули, которые они импортируют | | +| Журнал решений, который читает панель управления, и события ещё не доставленные | | + +Ключи, написанные более *новым* failproofai, также сохраняются, а не отбрасываются более старым читателем — так что перемещение между версиями не молча отбрасывает параметры ни в одну сторону. + +Вам **не** нужно перезапускать установку после этого: мигрированная машина применяет ровно так же, как раньше, что делает обновление безопасным на машинах, где никто не сидит за ними. Каждая миграция записывается в `~/.failproofai/migrations/applied.json`, и незаменимые файлы копируются в `~/.failproofai/migrations/backup-layout/` перед любым запуском. -Вы можете редактировать `policies-config.json` напрямую в любое время; изменения вступают в силу немедленно при следующем событии hook, без необходимости перезагрузки. +См. [`failproofai update`](/ru/cli/update) для однострочного обновления и [`failproofai migrate`](/ru/cli/migrate) — включая `--dry-run` — для подробностей. --- -## Пример: конфигурация на уровне проекта с командными значениями по умолчанию +## Пример: конфигурация на уровне проекта с командными по умолчанию -Зафиксируйте `.failproofai/policies-config.json` в вашем репо: +Зафиксируйте `.failproofai/policies-config.json` в вашем репозитории: ```json { @@ -266,4 +291,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her } ``` -Затем каждый разработчик может создать `.failproofai/policies-config.local.json` (исключённый из Git) для личных переопределений без влияния на товарищей. \ No newline at end of file +Каждый разработчик может затем создать `.failproofai/policies-config.local.json` (в gitignore) для персональных переопределений без влияния на товарищей по команде. \ No newline at end of file diff --git a/docs/ru/custom-policies.mdx b/docs/ru/custom-policies.mdx index cbe5cc86..7120515b 100644 --- a/docs/ru/custom-policies.mdx +++ b/docs/ru/custom-policies.mdx @@ -1,10 +1,11 @@ --- +--- title: Пользовательские политики -description: "Напишите свои правила на JavaScript — обеспечивайте соблюдение соглашений, предотвращайте дрейф, обнаруживайте сбои, интегрируйте с внешними системами" +description: "Напишите свои правила на JavaScript — применяйте соглашения, предотвращайте дрейф, обнаруживайте отказы, интегрируйте с внешними системами" icon: code --- -Пользовательские политики позволяют писать правила для любого поведения агента: обеспечивать соблюдение соглашений проекта, предотвращать дрейф, блокировать деструктивные операции, обнаруживать зависшие агенты или интегрироваться с Slack, рабочими процессами одобрения и многим другим. Они используют ту же систему событий-хуков и решения `allow`, `deny`, `instruct`, что и встроенные политики. +Пользовательские политики позволяют вам написать правила для любого поведения агента: применять соглашения проекта, предотвращать дрейф, ограничивать деструктивные операции, обнаруживать зависшие агенты или интегрироваться с Slack, рабочими процессами одобрения и многим другим. Они используют ту же систему событий hooks и решения `allow`, `deny`, `instruct`, что и встроенные политики. --- @@ -39,57 +40,57 @@ failproofai policies --install --custom ./my-policies.js ## Два способа загрузки пользовательских политик -### Вариант 1: На основе соглашений (рекомендуется) +### Способ 1: На основе соглашения (рекомендуется) -Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они автоматически загружаются — никаких флагов или изменений конфигурации не требуется. Это работает как git-хуки: положите файл, и всё просто работает. +Поместите файлы `*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` и встроенными политиками -Политики на основе соглашений — самый простой способ создать стандарт качества для вашей организации. Коммитьте `.failproofai/policies/` в git, и каждый член команды получит те же правила автоматически — никаких настроек по разработчикам не требуется. По мере обнаружения командой новых режимов отказа добавьте политику и отправьте. Со временем эти политики становятся живым стандартом качества, который постоянно улучшается с каждым вкладом. +Политики на основе соглашения — это самый простой способ установить стандарт качества для вашей организации. Закоммитьте `.failproofai/policies/` в git, и каждый член команды получит одни и те же правила автоматически — не требуется настройка для каждого разработчика. По мере того как ваша команда обнаруживает новые режимы отказа, добавьте политику и отправьте. Со временем это становится живым стандартом качества, который совершенствуется с каждым взносом. -### Вариант 2: Явный путь к файлу +### Способ 2: Явный путь к файлу ```bash -# Установить с файлом пользовательских политик +# Установите с файлом пользовательских политик failproofai policies --install --custom ./my-policies.js -# Заменить пути пользовательских политик +# Замените пути пользовательских политик failproofai policies --install --custom ./new-policies.js -# Настроить несколько явных файлов (загружаются в порядке флагов) +# Настройте несколько явных файлов (загружаются в порядке флагов) failproofai policies --install --custom ./security.js --custom ./workflow.js -# Удалить все явные пути пользовательских политик из конфигурации +# Удалите все явные пути пользовательских политик из конфигурации failproofai policies --uninstall --custom ``` -Разрешённые абсолютные пути хранятся в `policies-config.json` как `customPoliciesPaths`. Повторите `--custom` для настройки нескольких файлов. Существующие конфигурации с устаревшим полем `customPoliciesPath` продолжают работать. Файлы загружаются заново при каждом событии-хуке — кэширования между событиями нет. +Разрешённые абсолютные пути хранятся в `policies-config.json` как `customPoliciesPaths`. Повторите `--custom` для настройки нескольких файлов. Существующие конфигурации, использующие устаревшее поле `customPoliciesPath`, продолжают работать. Файлы загружаются заново при каждом событии hook — кеширование между событиями отсутствует. -Каждая зарегистрированная политика отображается со своим переключателем на панели управления. Отключение политики записывает её ID с определением источника в `disabledCustomPolicies`; файл и его остальные политики продолжают загружаться, а отключённая политика исключается перед сопоставлением событий. Имена политик, дублирующиеся в разных файлах, имеют независимые переключатели. +Каждая зарегистрированная политика отображается с собственным переключателем на панели управления. Отключение политики записывает её квалифицированный по источнику ID в `disabledCustomPolicies`; файл и его другие политики продолжают загружаться, а отключённая политика исключается перед сопоставлением событий. Политики с одинаковыми названиями в разных файлах имеют независимые переключатели. ### Использование обоих вместе -Политики на основе соглашений и явные файлы `--custom` могут сосуществовать. Порядок загрузки: +Политики на основе соглашения и явные файлы `--custom` могут сосуществовать. Порядок загрузки: -1. Явные файлы `customPoliciesPaths` (в настроенном порядке) -2. Файлы соглашений проекта (`{cwd}/.failproofai/policies/`, в алфавитном порядке) -3. Файлы соглашений пользователя (`~/.failproofai/policies/`, в алфавитном порядке) +1. Явные файлы `customPoliciesPaths` (в сконфигурированном порядке) +2. Файлы соглашения проекта (`{cwd}/.failproofai/policies/`, в алфавитном порядке) +3. Файлы соглашения пользователя (`~/.failproofai/policies/`, в алфавитном порядке) --- @@ -103,45 +104,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Регистрирует политику. Вызывайте сколько угодно раз для нескольких политик в одном файле. +Регистрирует политику. Вызывайте столько раз, сколько нужно для нескольких политик в одном файле. ```ts customPolicies.add({ - name: string; // обязательно — уникальный идентификатор + name: string; // обязательно - уникальный идентификатор description?: string; // показывается в выводе `failproofai policies` - match?: { events?: HookEventType[] }; // фильтр по типу события; опустите для сопоставления всех + match?: { events?: HookEventType[] }; // фильтр по типу события; пропустите для совпадения с любым fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Вспомогательные функции решений +### Вспомогательные функции для принятия решений | Функция | Эффект | Используйте когда | |----------|--------|----------| -| `allow()` | Разрешить операцию без вывода сообщения | Действие безопасно, сообщение не требуется | +| `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` накапливаются и доставляются вместе. -Вы можете добавить дополнительные рекомендации к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — никаких изменений кода не требуется. Это работает для пользовательских (`custom/`), проектных соглашений (`.failproofai-project/`) и пользовательских соглашений (`.failproofai-user/`) политик. Подробнее см. [Configuration → hint](/ru/configuration#hint-cross-cutting). +Вы можете добавить дополнительное руководство к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), соглашений проекта (`.failproofai-project/`), и соглашений пользователя (`.failproofai-user/`) политик. См. [Configuration → hint](/ru/configuration#hint-cross-cutting) для деталей. -### Информационные сообщения разрешения +### Информационные сообщения allow -`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика хука — тот же механизм, что используется `instruct`, но семантически отличается: это обновление статуса, а не предупреждение. +`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика hook — тот же механизм, что используется `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({ @@ -163,43 +164,43 @@ customPolicies.add({ ### Поля `PolicyContext` | Поле | Тип | Описание | -|-------|------|-------------| +|------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | Вызываемый инструмент (например `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Входные параметры инструмента | -| `payload` | `Record` | Полная сырая полезная нагрузка события от Claude Code | -| `session` | `SessionMetadata \| undefined` | Контекст сеанса (см. ниже) | +| `payload` | `Record` | Полный необработанный payload события от Claude Code | +| `session` | `SessionMetadata \| undefined` | Контекст сессии (см. ниже) | ### Поля `SessionMetadata` | Поле | Тип | Описание | -|-------|------|-------------| -| `sessionId` | `string` | Идентификатор сеанса Claude Code | -| `cwd` | `string` | Рабочий каталог сеанса Claude Code | -| `transcriptPath` | `string` | Путь к файлу-стенограмме JSONL сеанса | +|------|------|-------------| +| `sessionId` | `string` | Идентификатор сессии Claude Code | +| `cwd` | `string` | Рабочая директория сессии Claude Code | +| `transcriptPath` | `string` | Путь к файлу JSONL транскрипта сессии | ### Типы событий -| Событие | Когда оно срабатывает | Содержание `toolInput` | +| Событие | Когда срабатывает | Содержимое `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()`) -3. Политики соглашений из проектного `.failproofai/policies/` (файлы в алфавитном порядке, `.add()` внутри) -4. Политики соглашений из пользовательского `~/.failproofai/policies/` (файлы в алфавитном порядке, `.add()` внутри) +3. Политики соглашения из проекта `.failproofai/policies/` (файлы в алфавитном порядке, `.add()` в порядке) +4. Политики соглашения из пользователя `~/.failproofai/policies/` (файлы в алфавитном порядке, `.add()` в порядке) -Первый `deny` сокращает все последующие политики. Все сообщения `instruct` накапливаются и доставляются вместе. +Первый `deny` прерывает все последующие политики. Все сообщения `instruct` накапливаются и доставляются вместе. --- @@ -223,46 +224,46 @@ customPolicies.add({ }); ``` -Все относительные импорты, достижимые из файла точки входа, разрешаются. Это реализуется путём переписывания импортов `from "failproofai"` в фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM. +Все относительные импорты достижимые из входного файла разрешаются. Это реализовано путём переписи импортов `from "failproofai"` на фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM. --- ## Фильтрация типов событий -Используйте `match.events` для ограничения срабатывания политики: +Используйте `match.events` для ограничения когда срабатывает политика: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Срабатывает только при завершении сеанса - // ctx.session.transcriptPath содержит полный журнал сеанса + // Срабатывает только когда сессия заканчивается + // ctx.session.transcriptPath содержит полный лог сессии return allow(); }, }); ``` -Опустите `match` полностью, чтобы срабатывала при каждом типе события. +Пропустите `match` полностью для срабатывания при каждом типе события. --- ## Обработка ошибок и режимы отказа -Пользовательские политики **fail-open**: ошибки никогда не блокируют встроенные политики и не вызывают сбой обработчика хука. +Пользовательские политики **fail-open**: ошибки никогда не блокируют встроенные политики и не вызывают сбой обработчика hook. | Отказ | Поведение | |---------|----------| -| `customPoliciesPath` не установлен | Явные пользовательские политики не запускаются; встроенные и соглашения работают нормально | -| Файл не найден | Предупреждение логируется в `~/.failproofai/hook.log`; встроенные продолжают | -| Ошибка синтаксиса/импорта (явная) | Ошибка логируется в `~/.failproofai/hook.log`; явные пользовательские политики пропускаются | -| Ошибка синтаксиса/импорта (соглашение) | Ошибка логируется; этот файл пропускается, остальные файлы соглашений загружаются | -| `fn` выбросил исключение во время выполнения | Ошибка логируется; этот хук считается `allow`; остальные хуки продолжают | -| `fn` занял больше 10 сек | Timeout логируется; считается `allow` | -| Каталог соглашений отсутствует | Политики соглашений не запускаются; нет ошибки | +| `customPoliciesPath` не установлен | Явные пользовательские политики не работают; соглашения и встроенные политики продолжают нормально | +| Файл не найден | Предупреждение залогировано в `~/.failproofai/hook.log`; встроенные продолжают | +| Ошибка синтаксиса/импорта (явная) | Ошибка залогирована в `~/.failproofai/hook.log`; явные пользовательские политики пропущены | +| Ошибка синтаксиса/импорта (соглашение) | Ошибка залогирована; этот файл пропущен, другие файлы соглашения загружаются | +| `fn` выбрасывает исключение во время выполнения | Ошибка залогирована; этот hook обрабатывается как `allow`; другие hooks продолжают | +| `fn` занимает больше 10 сек | Timeout залогирован; обработан как `allow` | +| Директория соглашения отсутствует | Политики соглашения не работают; ошибки нет | -Для отладки ошибок пользовательских политик смотрите файл журнала: +Для отладки ошибок пользовательских политик следите за файлом лога: ```bash tail -f ~/.failproofai/hook.log @@ -277,7 +278,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Prevent agent from writing to secrets/ directory +// Предотвратить агенту писать в директорию secrets/ customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -290,7 +291,7 @@ customPolicies.add({ }, }); -// 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", @@ -305,7 +306,7 @@ customPolicies.add({ }, }); -// Prevent unplanned dependency changes during freeze +// Предотвратить незапланированные изменения зависимостей во время заморозки customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -328,22 +329,22 @@ export { customPolicies }; ## Примеры -Каталог `examples/` содержит готовые к запуску файлы политик: +Директория `examples/` содержит готовые файлы политик: -| Файл | Содержание | +| Файл | Содержимое | |------|----------| -| `examples/policies-basic.js` | Пять начальных политик, охватывающих распространённые режимы отказа агента | -| `examples/policies-advanced/index.js` | Продвинутые паттерны: транзитивные импорты, асинхронные вызовы, скрубинг вывода и хуки завершения сеанса | -| `examples/convention-policies/security-policies.mjs` | Политики безопасности на основе соглашений (блокировка записей .env, предотвращение переписывания истории git) | -| `examples/convention-policies/workflow-policies.mjs` | Политики рабочего процесса на основе соглашений (напоминания о тестах, аудит записей файлов) | +| `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 ``` -### Использование примеров на основе соглашений +### Использование примеров на основе соглашения ```bash # Скопировать на уровень проекта @@ -355,4 +356,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Команда install не требуется — файлы автоматически подбираются при следующем событии-хуке. \ No newline at end of file +Команда install не требуется — файлы подхватываются автоматически при следующем событии hook. \ No newline at end of file diff --git a/docs/ru/dashboard.mdx b/docs/ru/dashboard.mdx index c0c7ee56..5d4cc91d 100644 --- a/docs/ru/dashboard.mdx +++ b/docs/ru/dashboard.mdx @@ -1,6 +1,6 @@ --- title: Панель управления -description: "Отслеживайте сеансы агентов, просматривайте вызовы инструментов и управляйте политиками" +description: "Мониторьте сеансы агентов, просматривайте вызовы инструментов и управляйте политиками" icon: chart-line --- @@ -16,7 +16,7 @@ failproofai Откроется по адресу `http://localhost:8020`. -Панель управления читает данные локального проекта, сеанса и конфигурации failproofai непосредственно из файловой системы. Дополнительные функции с аутентификацией, такие как напоминания об аудите и приглашения, отправляют необходимую информацию для этих запросов (включая адреса электронной почты) на удалённые API. +Панель управления читает данные локального проекта, сеанса и конфигурации failproofai непосредственно из файловой системы. Опциональные аутентифицированные функции, такие как напоминания об аудите и приглашения, отправляют информацию, необходимую для этих запросов (включая адреса электронной почты), в удалённые API. --- @@ -24,73 +24,69 @@ failproofai ### Проекты -Отображает все проекты Claude Code, OpenAI Codex, GitHub Copilot CLI _(бета)_, Cursor Agent _(бета)_, OpenCode _(бета)_, Pi _(бета)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity и Goose, найденные на вашем компьютере. Проекты Claude обнаруживаются в `~/.claude/projects/` (или пути, установленном через `CLAUDE_PROJECTS_PATH`); проекты Codex обнаруживаются сканированием каждой записи под `~/.codex/sessions///
/*.jsonl` и группировкой по `cwd`, указанному в первой записи каждого сеанса; проекты Copilot CLI обнаруживаются сканированием каждого `~/.copilot/session-state//workspace.yaml` (настраивается через `COPILOT_HOME`) и группировкой по его полю `cwd`; проекты Cursor Agent обнаруживаются сканированием метаданных каждого сеанса под `~/.cursor/agent-sessions//` (настраивается через `CURSOR_HOME`, с проверкой `conversations/` и `sessions/` как резервных вариантов) для скалярного `cwd` в `meta.json` / `session.json` / `workspace.yaml`; проекты OpenCode обнаруживаются запросом к его БД SQLite по адресу `~/.local/share/opencode/opencode.db` через `opencode db --format json` (мы читаем таблицы `session` и `project` и группируем по `project_id`); проекты Pi обнаруживаются сканированием JSONL-записей каждого сеанса под `~/.pi/agent/sessions//_.jsonl` (настраивается через `PI_SESSIONS_DIR`) и извлечением `cwd` из первой записи каждого сеанса; сеансы шлюза Hermes читаются непосредственно из хранилища SQLite каждого профиля — `~/.hermes/state.db` плюс `~/.hermes/profiles//state.db` (переопределяется через `HERMES_HOME` или `HERMES_DB_PATH` для одной базы данных) — и группируются в проекты `hermes--` по профилю и `source` (Slack/Telegram/cli/cron — сеансы шлюза не имеют cwd); сеансы шлюза OpenClaw читаются из `~/.openclaw/agents//sessions/*.jsonl` и группируются в проекты `openclaw--` по агенту и каналу (также без cwd); проекты Factory Droid обнаруживаются из JSONL-записей по адресу `~/.factory/sessions//*.jsonl` и группируются по cwd; проекты Devin из её БД SQLite по адресу `~/.local/share/devin/cli/sessions.db` (группируются по `working_directory` каждого сеанса); проекты Antigravity из JSONL-записей по адресу `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` и группируются по cwd; проекты Goose из её БД SQLite по адресу `~/.local/share/goose/sessions/sessions.db` (группируются по `working_dir` каждого сеанса). Проект, используемый несколькими CLI, отображается одной строкой со всеми соответствующими значками. Используйте раскрывающееся меню **CLI** над таблицей для фильтрации по определённому CLI агента; URL сохраняет ваш выбор как `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Список всех проектов Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity и Goose, найденных на вашей машине. Проекты Claude обнаруживаются в `~/.claude/projects/` (или по пути, установленному переменной `CLAUDE_PROJECTS_PATH`); проекты Codex обнаруживаются путём сканирования каждого транскрипта в `~/.codex/sessions///
/*.jsonl` и группировки по `cwd`, записанному в первой записи сеанса; проекты Copilot CLI обнаруживаются путём сканирования каждого `~/.copilot/session-state//workspace.yaml` (настраивается через `COPILOT_HOME`) и группировки по его полю `cwd`; проекты Cursor Agent обнаруживаются путём сканирования метаданных по сеансам в `~/.cursor/agent-sessions//` (настраивается через `CURSOR_HOME`, с запасными вариантами `conversations/` и `sessions/`) для скалярного значения `cwd` в `meta.json` / `session.json` / `workspace.yaml`; проекты OpenCode обнаруживаются путём запроса к его БД SQLite в `~/.local/share/opencode/opencode.db` через `opencode db --format json` (мы читаем таблицы `session` и `project` и группируем по `project_id`); проекты Pi обнаруживаются путём сканирования транскриптов JSONL по сеансам в `~/.pi/agent/sessions//_.jsonl` (настраивается через `PI_SESSIONS_DIR`) и извлечения `cwd` из первой записи каждого сеанса; сеансы шлюза Hermes читаются непосредственно из хранилища SQLite каждого профиля — `~/.hermes/state.db` плюс `~/.hermes/profiles//state.db` (переопределяется через `HERMES_HOME` или `HERMES_DB_PATH` для одной базы данных) — и группируются в проекты `hermes--` по профилю и `source` (Slack/Telegram/cli/cron — сеансы шлюза не имеют cwd); сеансы шлюза OpenClaw читаются из `~/.openclaw/agents//sessions/*.jsonl` и группируются в проекты `openclaw--` по агенту и каналу (также без cwd); проекты Factory Droid обнаруживаются из транскриптов JSONL в `~/.factory/sessions//*.jsonl` и группируются по cwd; проекты Devin из её БД SQLite в `~/.local/share/devin/cli/sessions.db` (группируются по `working_directory` каждого сеанса); проекты Antigravity из транскриптов JSONL в `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` и группируются по cwd; и проекты Goose из её БД SQLite в `~/.local/share/goose/sessions/sessions.db` (группируются по `working_dir` каждого сеанса). Проект, который использовался несколькими CLI, отображается как одна строка со всеми соответствующими значками. Используйте раскрывающееся меню **CLI** над таблицей для фильтрации по определённому агенту CLI; URL сохраняет ваш выбор как `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -Hermes и OpenClaw имеют область пользователя и не имеют рабочего каталога для группировки, поэтому они отображаются как **сворачиваемое дерево папок** — профиль (или агент) на верхнем уровне, его каналы под ним — в то время как каждый CLI на основе cwd остаётся плоской строкой. Строки папок объединяют количество сеансов и самую последнюю активность всего, что под ними, свёрнутые папки запоминаются между визитами, а поиск по ключевому слову разворачивает совпадения. +Hermes и OpenClaw охватывают пользователя и не имеют рабочей директории для группировки, поэтому отображаются как **свернуть/развернуть дерево папок** — профиль (или агент) на верхнем уровне, его каналы ниже — в то время как все CLI на основе cwd остаются плоской строкой. Строки папок свёртывают количество сеансов и самую недавнюю активность всего под ними, свёрнутые папки запоминаются между визитами, а поиск по ключевым словам расширяет всё, что он находит. Каждый проект показывает: -- Имя проекта (производное от пути папки) -- Значок CLI — `Claude Code` (оранжевый), `OpenAI Codex` (фиолетовый), `GitHub Copilot` (синий), `Cursor Agent` (изумрудный), `OpenCode` (янтарный), `Pi` (розовый) и/или `Hermes` (индиго) -- Дата самой последней активности сеанса +- Название проекта (производное от пути папки) +- Значок CLI — `Claude Code` (оранжевый), `OpenAI Codex` (фиолетовый), `GitHub Copilot` (синий), `Cursor Agent` (изумруд), `OpenCode` (янтарь), `Pi` (розовый), и/или `Hermes` (индиго) +- Дату самой недавней активности сеанса Нажмите на проект, чтобы увидеть его сеансы. ### Сеансы -Отображает все сеансы в проекте. Каждый сеанс показывает: +Список всех сеансов в проекте. Каждый сеанс показывает: - ID сеанса -- Время начала и окончания +- Временные метки начала и завершения - Количество вызовов инструментов -- Количество активности хука (политики, которые были применены) +- Количество активности перехватчика (политики, которые срабатывали) -Используйте фильтр по диапазону дат и поиск по ID сеанса для сужения списка. Сеансы разбиваются на страницы. +Используйте фильтр диапазона дат и поиск по ID сеанса для сужения списка. Сеансы разбиваются на страницы. -Нажмите на сеанс, чтобы открыть средство просмотра сеансов. +Нажмите на сеанс, чтобы открыть просмотр сеанса. -### Средство просмотра сеансов +### Просмотр сеанса -Средство просмотра сеансов ответит на ключевой вопрос для автономных агентов: что сделал агент и остался ли он в пределах задачи? Значок CLI рядом с заголовком указывает, является ли сеанс записью Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity или Goose. Он показывает временную шкалу всего, что произошло в сеансе: +Просмотр сеанса отвечает на ключевой вопрос для автономных агентов: что делал агент и оставался ли он на курсе? Значок CLI рядом с заголовком указывает, является ли сеанс транскриптом Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity или Goose. Он показывает временную шкалу всего, что произошло в сеансе: -- **Сообщения** — текстовые ответы Claude и подсказки пользователя -- **Вызовы инструментов** — каждый инструмент, вызванный Claude, с его входными и выходными данными -- **Активность политик** — для каждого вызова инструмента, какие политики были применены и какое решение они вернули +- **Сообщения** - текстовые ответы Claude и подсказки пользователя +- **Вызовы инструментов** - каждый инструмент, который вызвал Claude, с его вводом и выводом +- **Активность политики** - для каждого вызова инструмента, какие политики срабатывали и какое решение они возвращали -Полоса статистики вверху показывает продолжительность сеанса, общее количество вызовов инструментов и сводку решений хука (количество allow / deny / instruct). +Полоса статистики в верхней части показывает продолжительность сеанса, общее количество вызовов инструментов и сводку решений перехватчика (количество allow / deny / instruct). -Нажмите кнопку **Download Logs** для экспорта сеанса. Для сеансов Claude Code, Codex, Copilot, Cursor и Pi вы получаете оригинальную запись JSONL с диска без изменений; для OpenCode (чьи сеансы находятся в SQLite, а не на диске) вы получаете документ JSON, отражающий основные таблицы `session` / `messages` / `parts`. +Нажмите кнопку **Download Logs**, чтобы экспортировать сеанс. Для сеансов Claude Code, Codex, Copilot, Cursor и Pi вы получаете исходный транскрипт JSONL на диске побайтово; для OpenCode (чьи сеансы хранятся в SQLite, а не на диске) вы получаете документ JSON, отражающий базовые таблицы `session` / `messages` / `parts`. ### Аудит -Ориентированный на личность отчёт о том, как ваш агент на самом деле вёл себя в прошлых сеансах. Запускает то же сканирование, что и CLI `failproofai audit`, но отображает его как одноэкранный общий постер + четыре раздела ниже сгиба: +Отчёт, управляемый личностью, о том, как ваш агент на самом деле вёл себя в предыдущих сеансах. Запускает то же сканирование, что и CLI `failproofai audit`, но отображает его как один экран в виде распечатываемого плаката + четыре раздела ниже сгиба: -1. **Постер** — заполняет первый видимый экран. Самодостаточный регион для захвата PNG с словесным знаком failproof_ai + этикетка аудита · индекс архетипа (`№ NN из 08`) + дата аудита · числовой балл (0–100) + таблетка рейтинга процентиля (`топ 15%`) · имя архетипа (один из `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + полоса 3 ключевых слов · строка редкости `// только N% агентов такого архетипа` · плитка сигила 8×8 пикселей · нижний колонтитул `audit yours → failproof.ai`. Три кнопки общего доступа расположены сразу за пределами окна захвата: `post your archetype` (X intent), `share on linkedin`, `download poster`. Захват выполняется через `html-to-image` так что PNG соответствует на экране визуализации пиксель за пиксель (пунктирные границы, маска логотипа SVG, градиенты, метрики шрифтов — всё сохраняется). +1. **Плакат** — заполняет первый видеопорт. Отдельный регион захвата PNG с логотипом failproof_ai + метка аудита · индекс архетипа (`№ NN из 08`) + дата аудита · числовой балл (0–100) + таблетка процентиля (`top 15%`) · имя архетипа (одно из `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + полоса из 3 ключевых слов · строка редкости `// only N% of agents are this archetype` · плитка сигила 8×8 пиксель · подвал `audit yours → failproof.ai`. Три кнопки поделиться находятся прямо за границей поля захвата: `post your archetype` (X intent), `share on linkedin`, `download poster`. Захват выполняется через `html-to-image`, поэтому PNG совпадает с отображением на экране пиксель за пиксель (пунктирные границы, маска логотипа SVG, градиенты, метрики шрифта — всё сохранено). +2. **Сильные стороны** — спокойный список ✓ поведений, которые ваш агент уже делает правильно, извлекённый из данных живого аудита (чистый коэффициент вызовов инструментов, без прямых push в main, без утечек учётных данных, без штормов повтора) — каждый поверхностный только когда соответствующая политика имеет чистый рекорд в окне аудита. +3. **Причуды** — таблица того, что проскользнуло, отранжированная по серьёзности: `when · what slipped + the policy that would've caught it · severity pill · seen`, где повторение читается `new` (один раз), `N× seen` (2–9 раз) или `recurring` (10+). +4. **Как улучшить** — спокойный список строк, по одной на рекомендуемую политику: имя политики белым, однострочное описание, команда установки + кнопка копирования на правой стороне. Заголовок раздела читается `enable all N → projected · ` (балл, который вы получите со всеми исправлениями), и его кнопка `[install all]` копирует объединённую команду `failproofai policy add a b c …` для каждой рекомендуемой политики. +5. **Вернитесь лучше** — две рядом расположенные карты. Слева: установите напоминание (выбор кадра `3d` / `7d` / `14d` / `30d`; сохраняется через `/api/auth/reminder` после аутентификации). Справа: разблокируйте преимущества failproof — `invite a friend` открывает модальное окно, которое принимает разделённый запятыми/пробелом/новой строкой список электронных писем друзей (максимум 10 за отправку), POST их на `/api/audit/invite`, что пересылает на `/v0/invite` api-server. api-server отправляет одно письмо для каждого получателя от `invite@failproof.ai` с Cc отправителя и `Reply-To` установленным, поэтому получатель видит, кто их пригласил, а отправитель получает копию в папку входящих. Анонимные пользователи маршрутизируются через `AuthDialog` сначала, поэтому адрес электронной почты отправителя известен до отправки приглашений. Выполнение прав / преимуществ будет позже. -2. **Сильные стороны** — спокойный список ✓ поведения, которое ваш агент уже делает правильно, вытекающее из данных живого аудита (чистый коэффициент вызовов инструментов, без прямых push в main, нет утечек учётных данных, нет штормов переповторов) — каждое появляется только когда соответствующая политика имеет чистую запись во времени аудита. - -3. **Причуды** — таблица того, что прошло незамеченным, ранжированная по серьёзности: `когда · что прошло + политика, которая бы это поймала · таблетка серьёзности · видно`, где повторяемость читается как `новое` (один раз), `N× видно` (2–9 раз) или `повторяющееся` (10+). - -4. **Как улучшить** — спокойный список, один на рекомендуемую политику: имя политики белым, однострочное описание, команда установки + кнопка копирования на правой стороне. Заголовок раздела читается как `включить всё N → прогнозируемый · ` (оценка, которую вы получите со всеми исправлениями), и его кнопка `[install all]` копирует объединённую команду `failproofai policy add a b c …` для каждой рекомендуемой политики. - -5. **Вернись лучше** — две карточки рядом. Слева: установить напоминание (выбор частоты `3d` / `7d` / `14d` / `30d`; сохраняется через `/api/auth/reminder` после аутентификации). Справа: разблокировать привилегии failproof — `invite a friend` открывает модальное окно, которое принимает список адресов электронной почты друзей, разделённых запятыми/пробелами/переводами строк (максимум 10 за отправку), POST их на `/api/audit/invite`, что перенаправляет на `POST /v0/invite` сервера api. Сервер api отправляет одно письмо на каждого получателя от `invite@failproof.ai` с копией отправителя и установленным `Reply-To`, так что получатель видит, кто его пригласил, а отправитель получает копию в своем почтовом ящике. Анонимные пользователи маршрутизируются через `AuthDialog` сначала, чтобы адрес электронной почты отправителя был известен до отправки приглашений. Выполнение прав / привилегий — последующее действие. - -Управляется выполнением `failproofai audit` — см. [Audit CLI](/ru/cli/audit) для базового механизма сканирования, поддерживаемых флагов и инвариантов кэша для каждой записи. Панель управления кэширует последний результат в `~/.failproofai/audit-dashboard.json` (режим `0600`, одиночный слот, новые запуски перезаписывают), поэтому повторные посещения мгновенны; **оба кэши для каждой записи и полного результата отклоняются при чтении, когда они старше 7 дней**, поэтому панель управления никогда не служит результатом возрастом в неделю — после TTL `/audit` переходит в состояние пустого значения и предлагает свежий запуск. Нажатие `[ re-audit now ]` близко внизу отчёта POST `/api/audit/run` с `noCache: true` — повторный аудит пропускает кэш для каждой записи и повторно сканирует каждую запись с нуля вместо того, чтобы молча возвращать кэшированный результат — и панель управления опрашивает `/api/audit/status` на частоте 1Hz до завершения запуска; липкая розовая полоса прогресса прикрепляется к верхней части видимого экрана во время запуска с таймером истекшего времени, и свежий результат переходит на место при успехе (без перезагрузки полной страницы; неудачный повторный аудит оставляет предыдущий отчёт нетронутым). При ошибке полоса становится красной с копией, ключируемой по `RerunError.kind` (`timeout` / `network` / `post_failed`). Состояние пустого значения (нет кэша или истекло) и состояние нулевых сеансов (кэш существует, но сканирование не нашло записей) выводятся отдельно. +Управляется средой выполнения `failproofai audit` — см. [Audit CLI](/ru/cli/audit) для базовой системы сканирования, поддерживаемых флагов и инвариантов кэша за транскрипт. Панель управления кэширует последний результат в `~/.failproofai/audit-dashboard.json` (режим `0600`, одиночный слот, новые запуски перезаписывают), поэтому повторные визиты происходят мгновенно; **оба кэша за транскрипт и весь результат отклоняются при чтении, когда им больше 7 дней**, поэтому панель управления никогда не обслуживает результат неделю назад — прошедший TTL `/audit` падает в своё пустое состояние и подсказывает свежий запуск. Нажатие `[ re-audit now ]` рядом с нижней частью отчёта POST на `/api/audit/run` с `noCache: true` — переаудит пропускает кэш за транскрипт и повторно сканирует каждый транскрипт с нуля вместо того, чтобы молча возвращать кэшированный результат — и панель управления опрашивает `/api/audit/status` при 1Hz до завершения выполнения; липкая розовая полоса прогресса закрепляется в верхней части видеопорта во время выполнения с истекшим таймером, и свежий результат меняется на место при успехе (без перезагрузки полной страницы; неудачный переаудит оставляет предыдущий отчёт нетронутым). При сбое полоса становится красной с копией, основанной на `RerunError.kind` (`timeout` / `network` / `post_failed`). Пустое состояние (кэш отсутствует или истекло) и состояние нулевых сеансов (кэш существует, но сканирование не нашло транскриптов) отображаются отдельно. ### Политики -Двухвкладочная страница для управления политиками и проверки активности. +Страница с двумя вкладками для управления политиками и просмотра активности. - - - Множественный выбор защиты каких CLI агентов failproofai обеспечивает с одной панели — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi и Hermes все имеют строку со статусом установки (`Active` / `Detected` / `Inactive`), путём настроек области пользователя и брендовым акцентом. Отметьте или снимите флажки CLI, которые вы хотите, и нажмите `Apply changes` для установки/удаления diff за один шаг. CLI, двоичные файлы которых обнаруживаются в PATH, предварительно отмечены. - - Включайте или выключайте отдельные политики одним щелчком (пишет в `~/.failproofai/policies-config.json` — общий доступ для каждого установленного CLI) + + - Мультиселект, какие агенты CLI защищает failproofai, из одной панели — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi и Hermes имеют строку со статусом установки (`Active` / `Detected` / `Inactive`), пути параметров пользовательской области и акцентом фирменного цвета. Отметьте или снимите отметку с CLI, которые вам нужны, и нажмите `Apply changes` для установки/удаления различий за один шаг. CLI, чей двоичный файл обнаруживается на PATH, предварительно проверены. + - Включайте или отключайте отдельные политики одним щелчком (записывает в `~/.failproofai/policies-config.json` — общее для каждого установленного CLI) - Разверните политику для настройки её параметров (для политик, поддерживающих `policyParams`) - Установите пользовательский путь файла политик - - - Полная разбитая на страницы история каждого события хука, которое было применено во всех сеансах - - Фильтр по решению, типу события, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(бета)_ / Cursor Agent _(бета)_ / OpenCode _(бета)_ / Pi _(бета)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), имени политики или ID сеанса - - Каждая строка показывает: время, имя политики, решение, значок CLI (оранжевый = Claude Code, фиолетовый = OpenAI Codex, синий = GitHub Copilot, изумрудный = Cursor Agent, янтарный = OpenCode, розовый = Pi, индиго = Hermes, сине-зелёный = OpenClaw, розовый = Factory Droid, фиолетовый = Devin, голубой = Antigravity, лаймовый = Goose), имя инструмента, ID сеанса и причину решений deny/instruct - - Нажмите на ID сеанса, чтобы открыть его запись — средство просмотра автоматически определяет, какой CLI применил хук (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) и отображает соответствующий значок CLI в заголовке + + - Полная постраничная история каждого события перехватчика, которое срабатывало во всех сеансах + - Фильтруйте по решению, типу события, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), имени политики или ID сеанса + - Каждая строка показывает: временную метку, имя политики, решение, значок CLI (оранжевый = Claude Code, фиолетовый = OpenAI Codex, синий = GitHub Copilot, изумруд = Cursor Agent, янтарь = OpenCode, розовый = Pi, индиго = Hermes, голубой = OpenClaw, роза = Factory Droid, фиолетовый = Devin, голубой = Antigravity, лайм = Goose), имя инструмента, ID сеанса и причину решений deny/instruct + - Нажмите на ID сеанса для открытия его транскрипта — средство просмотра автоматически определяет, какой CLI срабатывал перехватчик (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) и отображает соответствующий значок CLI в заголовке @@ -98,13 +94,13 @@ Hermes и OpenClaw имеют область пользователя и не и ## Автоматическое обновление -Панель управления имеет переключатель автоматического обновления в верхней навигации. При включении текущая страница периодически обновляется, чтобы показать новые сеансы и активность политик по мере их появления. Необходимо для мониторинга долгоживущих сеансов автономных агентов. +Панель управления имеет переключатель автоматического обновления в верхней навигации. При включении текущая страница периодически обновляется, чтобы показать новые сеансы и активность политики по мере их появления. Необходимо для мониторинга длительных сеансов автономных агентов. --- ## Отключение страниц -Если вам нужны только некоторые части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` в список имён страниц, разделённый запятыми: +Если вам нужны только некоторые части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` в разделённый запятыми список имён страниц: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -116,7 +112,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## Настройка пути проектов -По умолчанию панель управления читает из стандартного каталога проектов Claude Code. Переопределите его для пользовательских установок: +По умолчанию панель управления читает из стандартной директории проектов Claude Code. Переопределите её для пользовательских настроек: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -124,32 +120,32 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Доступ с небольшого хоста localhost +## Доступ с хоста, отличного от localhost -При запуске панели управления в **режиме разработки** (`npm run dev`) и доступе к ней с имени хоста, отличного от `localhost` — например, пользовательского домена, удалённого IP или туннелированного URL — вы можете увидеть предупреждение вроде: +При запуске панели управления в **режиме разработки** (`npm run dev`) и доступе к ней с имени хоста, отличного от `localhost` — например, пользовательского домена, удалённого IP или туннелированного URL — вы можете увидеть предупреждение подобно: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Это Next.js, блокирующий кросс-источник доступ к его HMR (горячая загрузка модулей) вебсокету, который является функцией только для разработки. Чтобы разрешить ваш хост, используйте флаг `--allowed-origins`: +Это Next.js, блокирующий кроссоригинный доступ к его HMR (горячая перезагрузка модуля) веб-сокету, который является функцией только разработки. Чтобы разрешить ваш хост, используйте флаг `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -Для нескольких хостов или IP передайте список, разделённый запятыми: +Для нескольких хостов или IP передайте разделённый запятыми список: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Вы также можете установить переменную окружения `FAILPROOFAI_ALLOWED_DEV_ORIGINS` вместо этого: +Вы также можете установить переменную среды `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Это применяется только к режиму разработки. При запуске `failproofai` (режим производства) не существует вебсокета HMR и нет проблемы кросс-источника с ресурсом разработки. +Это применяется только к режиму разработки. При запуске `failproofai` (режиме производства) нет веб-сокета HMR и нет проблемы с кроссоригинными ресурсами разработки. \ No newline at end of file diff --git a/docs/ru/examples.mdx b/docs/ru/examples.mdx index 5ac63b18..d44e5ef6 100644 --- a/docs/ru/examples.mdx +++ b/docs/ru/examples.mdx @@ -1,83 +1,83 @@ --- title: Примеры -description: "Как настроить хуки для Claude Code и Agents SDK" +description: "Как настроить hooks для Claude Code и Agents SDK" icon: book-open --- -Готовые примеры для часто встречающихся сценариев. Каждый показывает, как установить и чего ожидать. +Готовые к использованию примеры для типичных сценариев. Каждый пример показывает, как установить и чего ожидать. --- -## Настройка хуков для Claude Code +## Настройка hooks для Claude Code -Failproof AI интегрируется с Claude Code через его [систему хуков](https://docs.anthropic.com/en/docs/claude-code/hooks). Когда вы запускаете `failproofai policies --install`, он регистрирует команды хуков в файле `settings.json` Claude Code, которые срабатывают при каждом вызове инструмента. +Failproof AI интегрируется с Claude Code через его [систему hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Когда вы запускаете `failproofai policies --install`, он регистрирует команды hooks в `settings.json` Claude Code, которые запускаются при каждом вызове инструмента. - + ```bash npm install -g failproofai ``` - + ```bash failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - Вы должны увидеть записи хуков для событий `PreToolUse`, `PostToolUse`, `Notification` и `Stop`. + Вы должны увидеть записи hooks для событий `PreToolUse`, `PostToolUse`, `Notification` и `Stop`. - + ```bash claude ``` - Политики теперь автоматически запускаются при каждом вызове инструмента. Попросите Claude выполнить `sudo rm -rf /` — это будет заблокировано. + Политики теперь работают автоматически при каждом вызове инструмента. Попробуйте попросить Claude выполнить `sudo rm -rf /` — это будет заблокировано. --- -## Настройка хуков для Agents SDK +## Настройка hooks для Agents SDK -Если вы разрабатываете с использованием [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), вы можете использовать ту же систему хуков программно. +Если вы разрабатываете с использованием [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), вы можете использовать ту же систему hooks программно. - + ```bash npm install failproofai ``` - - Передайте команды хуков при создании процесса агента. Хуки срабатывают так же, как в Claude Code — через JSON в stdin/stdout: + + Передайте команды hooks при создании процесса агента. Hooks срабатывают так же, как в Claude Code — через stdin/stdout JSON: ```bash failproofai --hook PreToolUse # вызывается перед каждым инструментом failproofai --hook PostToolUse # вызывается после каждого инструмента ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "limit-to-project-dir", - description: "Keep the agent inside the project directory", + description: "Держать агента внутри директории проекта", match: { events: ["PreToolUse"] }, fn: async (ctx) => { const path = String(ctx.toolInput?.file_path ?? ""); if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) { - return deny("Agent is restricted to the project directory"); + return deny("Агент ограничен директорией проекта"); } return allow(); }, }); ``` - + ```bash failproofai policies --install --custom ./my-agent-policies.js ``` @@ -86,9 +86,9 @@ Failproof AI интегрируется с Claude Code через его [сис --- -## Блокировка деструктивных команд +## Блокировать деструктивные команды -Наиболее распространенная настройка — предотвращение необратимых действий агентами. +Самая распространённая настройка — предотвратить необратимый ущерб от агентов. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -98,38 +98,38 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur - `block-sudo` — блокирует все команды `sudo` - `block-rm-rf` — блокирует рекурсивное удаление файлов - `block-force-push` — блокирует `git push --force` -- `block-curl-pipe-sh` — блокирует передачу удаленных скриптов в оболочку +- `block-curl-pipe-sh` — блокирует передачу удалённых скриптов в shell --- -## Предотвращение утечек секретов +## Предотвратить утечку секретов -Остановите агентов от просмотра или утечки учетных данных в выводе инструмента. +Помешайте агентам видеть или раскрывать учётные данные в выводе инструмента. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Они срабатывают на `PostToolUse` — после выполнения инструмента они очищают вывод перед тем, как агент его увидит. +Эти политики срабатывают на `PostToolUse` — после запуска инструмента они удаляют конфиденциальные данные из вывода перед тем, как агент его увидит. --- -## Получайте оповещения Slack, когда агентам нужно внимание +## Получать уведомления Slack, когда агентам нужно внимание -Используйте хук уведомления для отправки предупреждений об ожидании в Slack. +Используйте notification hook для отправки оповещений простоя в Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "slack-on-idle", - description: "Alert Slack when the agent is waiting for input", + description: "Отправить оповещение в Slack, когда агент ожидает ввода", match: { events: ["Notification"] }, fn: async (ctx) => { const webhookUrl = process.env.SLACK_WEBHOOK_URL; if (!webhookUrl) return allow(); - const message = String(ctx.payload?.message ?? "Agent is waiting"); + const message = String(ctx.payload?.message ?? "Агент ожидает"); const project = ctx.session?.cwd ?? "unknown"; try { @@ -137,12 +137,12 @@ customPolicies.add({ method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ - text: `*${message}*\nProject: \`${project}\``, + text: `*${message}*\nПроект: \`${project}\``, }), signal: AbortSignal.timeout(5000), }); } catch { - // never block the agent if Slack is unreachable + // никогда не блокируйте агента, если Slack недоступен } return allow(); @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -Установите это: +Установить это: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -158,22 +158,22 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## Держите агентов на ветке +## Держать агентов на ветке -Предотвратите переключение ветвей агентами или отправку в защищенные ветви. +Предотвратить переключение ветвей агентов или push в защищённые ветви. ```javascript import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "stay-on-branch", - description: "Prevent the agent from checking out other branches", + description: "Предотвратить переключение агента на другие ветви", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+checkout\s+(?!-b)/.test(cmd)) { - return deny("Stay on the current branch. Create a new branch with -b if needed."); + return deny("Оставайтесь на текущей ветви. При необходимости создайте новую ветвь с -b."); } return allow(); }, @@ -182,22 +182,22 @@ customPolicies.add({ --- -## Требуйте тесты перед коммитом +## Требовать тесты перед коммитами -Напомните агентам запустить тесты перед коммитом. +Напоминайте агентам запускать тесты перед коммитом. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "test-before-commit", - description: "Remind the agent to run tests before committing", + description: "Напомнить агенту запустить тесты перед коммитом", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+commit/.test(cmd)) { - return instruct("Run tests before committing. Use `npm test` or `bun test` first."); + return instruct("Запустите тесты перед коммитом. Сначала используйте `npm test` или `bun test`."); } return allow(); }, @@ -206,9 +206,9 @@ customPolicies.add({ --- -## Заблокируйте производственный репозиторий +## Закрепить production репозиторий -Зафиксируйте конфигурацию на уровне проекта, чтобы каждый разработчик вашей команды получал одинаковые политики. +Закоммитьте конфигурацию на уровне проекта, чтобы каждый разработчик вашей команды получил одинаковые политики. Создайте `.failproofai/policies-config.json` в вашем репозитории: @@ -231,7 +231,7 @@ customPolicies.add({ } ``` -Затем зафиксируйте это: +Затем закоммитьте это: ```bash git add .failproofai/policies-config.json @@ -242,12 +242,12 @@ git commit -m "Add failproofai team policies" --- -## Создайте стандарт качества на уровне организации с политиками по соглашению +## Построить стандарт качества на уровне организации с конвенциональными политиками -Наиболее эффективная настройка: зафиксируйте `.failproofai/policies/` в вашем репозитории с политиками, адаптированными к вашему проекту. Каждый член команды получает их автоматически — без команд установки, без изменения конфигурации. +Самая влиятельная настройка: закоммитьте `.failproofai/policies/` в ваш репозиторий с политиками, адаптированными к вашему проекту. Каждый член команды получит их автоматически — без команд установки, без изменения конфигурации. - + ```bash mkdir -p .failproofai/policies ``` @@ -256,52 +256,52 @@ git commit -m "Add failproofai team policies" // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Enforce your team's preferred package manager - // (or enable the built-in prefer-package-manager policy instead) + // Требовать предпочитаемый менеджер пакетов вашей команды + // (или вместо этого включить встроенную политику prefer-package-manager) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); - if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm."); + if (/\bnpm\b/.test(cmd)) return deny("Используйте bun вместо npm."); return allow(); }, }); - // Remind the agent to run tests before committing + // Напомнить агенту запустить тесты перед коммитом 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 instruct("Запустите тесты перед коммитом."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Когда ваша команда сталкивается с новыми режимами отказа, добавляйте политики и отправляйте их. Каждый получит обновление при следующем `git pull`. Эти политики становятся живым стандартом качества, который растет вместе с вашей командой. + По мере того, как ваша команда сталкивается с новыми сбоями, добавляйте политики и отправляйте их. Все получат обновление при следующем `git pull`. Эти политики становятся живым стандартом качества, который растёт вместе с вашей командой. --- -## Больше примеров +## Ещё примеры Директория [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) в репозитории содержит: -| Файл | Что он показывает | +| Файл | Что он демонстрирует | |------|---------------| -| `policies-basic.js` | Базовые политики — блокировка производственных записей, force-push, скриптов с передачей | -| `policies-notification.js` | Оповещения Slack для уведомлений об ожидании и завершении сессии | -| `policies-advanced/index.js` | Транзитивные импорты, асинхронные хуки, очистка выводов PostToolUse, обработка события Stop | \ No newline at end of file +| `policies-basic.js` | Стартовые политики — блокировка записей production, force-push, передачи скриптов | +| `policies-notification.js` | Оповещения Slack для простоя и завершения сессии | +| `policies-advanced/index.js` | Транзитивные импорты, асинхронные hooks, очистка вывода PostToolUse, обработка события Stop | \ No newline at end of file diff --git a/docs/ru/for-agents.mdx b/docs/ru/for-agents.mdx index e1b86574..20d5c276 100644 --- a/docs/ru/for-agents.mdx +++ b/docs/ru/for-agents.mdx @@ -1,36 +1,36 @@ --- title: "Для агентов" -description: "Добавьте справку Failproof AI в ваш кодирующий агент одной командой. Работает с Claude Code, Cursor, Windsurf и другими." +description: "Добавьте справку Failproof AI вашему агенту кодирования одной командой. Работает с Claude Code, Cursor, Windsurf и другими." --- -Добавьте полную справку Failproof AI в ваш кодирующий агент одной командой. Работает с Claude Code, Cursor, Windsurf и любым другим агентом, поддерживающим skills. +Добавьте полную справку Failproof AI вашему агенту кодирования одной командой. Работает с Claude Code, Cursor, Windsurf и любым другим агентом, поддерживающим skills. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` автоматически определяет, какие агенты у вас установлены, и добавляет skill в правильном формате для каждого. +`npx skills` автоматически определяет, какие агенты установлены, и добавляет skill в правильном формате для каждого. ## Что охватывает skill | Область | Что включено | |------|----------------| -| Policies | Встроенные имена политик, типы событий, параметры, включение/отключение | -| Custom policies | `customPolicies.add()`, фильтры сопоставления, API `allow`/`deny`/`instruct` | -| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configuration | Структура `policies-config.json`, объединение областей, `policyParams` | -| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, области | -| Dashboard | Просмотр сессий, активность политик, переменные окружения | -| Architecture | Поток обработчика хуков, коды выхода, контракт stdin/stdout | +| Политики | Встроенные имена политик, типы событий, параметры, включение/отключение | +| Пользовательские политики | `customPolicies.add()`, фильтры сопоставления, API `allow`/`deny`/`instruct` | +| Объект контекста | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | +| Конфигурация | Структура `policies-config.json`, слияние областей видимости, `policyParams` | +| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, области видимости | +| Панель управления | Просмотр сеансов, активность политик, переменные окружения | +| Архитектура | Поток обработчика хука, коды завершения, контракт stdin/stdout | -## Полноценен ли skill? +## Полон ли skill? -Mintlify генерирует `llms.txt` из всех страниц в навигации. Документация Failproof AI охватывает полный API — каждая политика, опция и пример включены. Если вы обнаружите что-то пропущенное, источник находится на `https://docs.befailproof.ai/llms-full.txt`. +Mintlify генерирует `llms.txt` из всех страниц в навигации. Документация Failproof AI охватывает полный API — каждая политика, опция и пример включены. Если вы обнаружите что-то недостающее, источник находится в `https://docs.befailproof.ai/llms-full.txt`. Для целевого контекста ссылайтесь непосредственно на конкретную страницу: ```bash -# Только API custom policies +# Только API пользовательских политик npx skills add https://docs.befailproof.ai/custom-policies # Только встроенные политики diff --git a/docs/ru/getting-started.mdx b/docs/ru/getting-started.mdx index a6356193..ffbce72a 100644 --- a/docs/ru/getting-started.mdx +++ b/docs/ru/getting-started.mdx @@ -1,13 +1,13 @@ --- title: Начало работы -description: "Установите failproofai, включите политики и позвольте вашим агентам работать надёжно" +description: "Установите failproofai, включите политики и позвольте вашим агентам работать надежно" icon: rocket --- ## Требования - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (опционально - требуется только для сборки из исходников) +- **Bun** >= 1.3.0 (опционально — требуется только для сборки из источника) --- @@ -31,15 +31,15 @@ bun add -g failproofai - Политики — это правила, которые выполняются до и после каждого вызова инструмента агентом. Они перехватывают деструктивные команды, утечки секретов и другие режимы отказов до того, как они причинят вред. + Политики — это правила, которые выполняются перед и после каждого вызова инструмента агента. Они перехватывают деструктивные команды, утечки секретов и другие сбои до того, как они вызовут проблемы. ```bash failproofai policies --install ``` - Это добавляет записи крючков в установленные CLI агентов (Claude Code в `~/.claude/settings.json`, OpenAI Codex в `~/.codex/hooks.json`, GitHub Copilot CLI в `~/.copilot/hooks/failproofai.json`, Cursor Agent в `~/.cursor/hooks.json`, OpenCode в сгенерированный модуль плагина `~/.config/opencode/plugins/failproofai.mjs` плюс запись регистрации в массиве `plugin` файла `~/.config/opencode/opencode.json`, Pi в `~/.pi/agent/settings.json`, Hermes в `~/.hermes/config.yaml`, OpenClaw в `~/.openclaw/openclaw.json`, Factory Droid в `~/.factory/hooks.json`, Devin CLI в `~/.config/devin/config.json`, Antigravity CLI в `~/.gemini/config/hooks.json` или Goose в автоматически обнаруживаемую директорию плагинов `~/.agents/plugins/failproofai/hooks/hooks.json`). Если присутствует более одного, вам будет предложено выбрать; передайте `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (любое подмножество), чтобы пропустить запрос. + Эта команда добавляет записи hook в установленные CLI агентов (Claude Code в `~/.claude/settings.json`, OpenAI Codex в `~/.codex/hooks.json`, GitHub Copilot CLI в `~/.copilot/hooks/failproofai.json`, Cursor Agent в `~/.cursor/hooks.json`, OpenCode в сгенерированный shim плагина `~/.config/opencode/plugins/failproofai.mjs` плюс запись регистрации в массиве `plugin` в `~/.config/opencode/opencode.json`, Pi в `~/.pi/agent/settings.json`, Hermes в `~/.hermes/config.yaml`, OpenClaw в `~/.openclaw/openclaw.json`, Factory Droid в `~/.factory/hooks.json`, Devin CLI в `~/.config/devin/config.json`, Antigravity CLI в `~/.gemini/config/hooks.json` или Goose в автоматически обнаруживаемую директорию плагина `~/.agents/plugins/failproofai/hooks/hooks.json`). Если присутствует более одного, вам будет предложен выбор; передайте `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (любое подмножество), чтобы пропустить подсказку. - Поддержка GitHub Copilot CLI, Cursor Agent, OpenCode и Pi находится на **стадии бета** — устанавливайте с `--cli copilot`, `--cli cursor`, `--cli opencode` или `--cli pi`. Hermes (hermes-agent, шлюз Slack/Telegram) устанавливается с пользовательской областью с `--cli hermes` и также является **источником офлайн-аудита**. OpenClaw (шлюз openclaw, самостоятельно размещаемый многоканальный помощник) устанавливается с пользовательской областью с `--cli openclaw` — принудительное применение работает через его встроенные крючки плагина (`before_agent_finalize` — это реальный запрос на конец хода, поэтому встроенные `require-*-before-stop` применяются) — и является **также источником офлайн-аудита**. Factory Droid (`droid`) устанавливается с `--cli factory` (пользовательская + проектная область) и является **также источником офлайн-аудита**. Devin CLI (`devin`, Cognition) устанавливается с `--cli devin` (пользовательская + проектная область) и является **также источником офлайн-аудита**. Antigravity CLI (`agy`) устанавливается с `--cli antigravity` (пользовательская + проектная область) и является **также источником офлайн-аудита**. Goose (кодовое имя goose, Block) устанавливается с `--cli goose` (пользовательская + проектная область) — установщик просто создаёт директорию плагина в `~/.agents/plugins/failproofai/`, которую Goose автоматически обнаруживает, и это **также источник офлайн-аудита**. + GitHub Copilot CLI, Cursor Agent, OpenCode и поддержка Pi находятся в **бета-версии** — установите с `--cli copilot`, `--cli cursor`, `--cli opencode` или `--cli pi`. Hermes (hermes-agent, шлюз Slack/Telegram) устанавливается на уровне пользователя с `--cli hermes` и **также** является источником автономного аудита. OpenClaw (шлюз openclaw, самостоятельный многоканальный помощник) устанавливается на уровне пользователя с `--cli openclaw` — принудительное применение осуществляется через его встроенные в процесс hook плагина (`before_agent_finalize` — это реальные ворота конца хода, поэтому встроенные модули `require-*-before-stop` работают) — и **также** является источником автономного аудита. Factory Droid (`droid`) устанавливается с `--cli factory` (уровень пользователя + проекта) и **также** является источником автономного аудита. Devin CLI (`devin`, Cognition) устанавливается с `--cli devin` (уровень пользователя + проекта) и **также** является источником автономного аудита. Antigravity CLI (`agy`) устанавливается с `--cli antigravity` (уровень пользователя + проекта) и **также** является источником автономного аудита. Goose (кодовое имя goose, Block) устанавливается с `--cli goose` (уровень пользователя + проекта) — установщик просто создает директорию плагина `~/.agents/plugins/failproofai/`, которую Goose автоматически обнаруживает, и это **также** является источником автономного аудита. ```bash failproofai policies --install --scope project @@ -62,17 +62,17 @@ bun add -g failproofai failproofai policies ``` - Показывает все политики, включены ли они и любые настроенные параметры. + Показывает каждую политику, включена ли она и любые настроенные параметры. ```bash failproofai ``` - Открывает локальную панель управления по адресу `http://localhost:8020`, где вы можете просматривать сеансы, проверять вызовы инструментов и управлять политиками. + Открывает локальную панель управления на `http://localhost:8020`, где вы можете просматривать сеансы, проверять вызовы инструментов и управлять политиками. - - Запустите Claude Code как обычно. Если агент попытается сделать что-то рискованное, failproofai автоматически это перехватит. Оставьте его работать без присмотра и посмотрите что произошло на панели управления. + + Запустите Claude Code как обычно. Если агент попытается сделать что-то рискованное, failproofai автоматически это перехватит. Оставьте его работать без присмотра и просмотрите то, что произошло, на панели управления. @@ -85,24 +85,24 @@ bun add -g failproofai ```text Claude Code → failproofai --hook PreToolUse → читает JSON из stdin оценивает политики - записывает решение в stdout + пишет решение в stdout ``` -Каждая политика возвращает одно из трёх решений: +Каждая политика возвращает одно из трех решений: -- **allow** - агент работает нормально -- **deny** - действие блокируется, агенту объясняют почему -- **instruct** - дополнительный контекст добавляется в приглашение агента +- **allow** — агент продолжает работу нормально +- **deny** — действие блокируется, агенту объясняется почему +- **instruct** — дополнительный контекст добавляется в подсказку агента -Политики выполняются в вашем локальном процессе. Ничего не отправляется удалённому сервису. +Политики выполняются в вашем локальном процессе. Ничего не отправляется на удаленный сервис. --- -## Настройка командных политик с помощью политик на основе соглашений +## Установите командные политики с использованием политик на основе соглашений -Самый быстрый способ установить стандарты качества в вашей команде — это соглашение `.failproofai/policies/`. Поместите файлы политик в эту директорию и они будут загружены автоматически — без флагов, без изменения конфигурации, без команд установки. +Самый быстрый способ установить стандарты качества во всей команде — это соглашение `.failproofai/policies/`. Поместите файлы политик в эту директорию, и они будут загружены автоматически — без флагов, без изменений конфигурации, без команд установки. @@ -111,7 +111,7 @@ Claude Code → failproofai --hook PreToolUse → читает JSON из std ``` - Скопируйте примеры для начинающих или напишите свои: + Скопируйте примеры стартера или напишите свои: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -136,33 +136,35 @@ Claude Code → failproofai --hook PreToolUse → читает JSON из std }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Каждый член команды с установленным failproofai автоматически получает эти политики. Не требуется настройка для каждого разработчика. + Каждый член команды, у которого установлен failproofai, автоматически получит эти политики. Никакой настройки для каждого разработчика не требуется. -Закоммитьте `.failproofai/policies/` в ваш репозиторий, чтобы вся команда придерживалась одних и тех же стандартов. По мере того как ваша команда открывает новые режимы отказов, добавляйте политики и отправляйте их — все получат обновление при следующем `git pull`. Со временем эти политики становятся живым стандартом качества, который постоянно улучшается. +Залейте `.failproofai/policies/` в ваш репозиторий, чтобы вся команда придерживалась одних и тех же стандартов. По мере того как ваша команда обнаруживает новые режимы сбоев, добавляйте политики и отправляйте их — все получат обновление при следующем `git pull`. С течением времени эти политики становятся живым стандартом качества, который постоянно улучшается. --- -## Хранение данных +## Хранилище данных -Вся конфигурация и логи остаются на вашей машине: +Вся конфигурация и логи остаются на вашем компьютере: -| Путь | Что хранится | +| Путь | Что здесь хранится | |------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | Глобальная конфигурация политик | -| `~/.failproofai/hook-activity/` | История выполнения крючков (постраничный JSONL) | -| `~/.failproofai/logs/` | Логи отладки для ошибок пользовательских крючков | -| `.failproofai/policies-config.json` | Конфигурация на проект (коммитится) | -| `.failproofai/policies-config.local.json` | Личные переопределения (в .gitignore) | +| `~/.failproofai/policies-config.json` | Глобальная конфигурация политик | +| `~/.failproofai/policies/` | Ваши собственные политики — просто поместите `*-policies.mjs`, конфигурация не требуется | +| `~/.failproofai/policies/cloud-policies/` | Политики, развернутые на этой машине вашей организацией | +| `~/.failproofai/hook-activity/` | История выполнения hook (постраничная JSONL) | +| `~/.failproofai/logs/` | Логи отладки для ошибок пользовательских hook | +| `.failproofai/policies-config.json` | Конфигурация для проекта (в репозитории) | +| `.failproofai/policies-config.local.json` | Личные переопределения (в gitignore) | --- @@ -172,11 +174,11 @@ Claude Code → failproofai --hook PreToolUse → читает JSON из std failproofai policies --uninstall ``` -Удаляет записи крючков из `~/.claude/settings.json`. Файлы конфигурации в `~/.failproofai/` сохраняются. +Удаляет записи hook из `~/.claude/settings.json`. Файлы конфигурации в `~/.failproofai/` сохраняются. --- -## Следующие шаги +## Дальнейшие шаги @@ -192,8 +194,8 @@ failproofai policies --uninstall Напишите свои политики на JavaScript - - Мониторьте сеансы и просматривайте активность политик + + Отслеживайте сеансы и просматривайте активность политик \ No newline at end of file diff --git a/docs/ru/introduction.mdx b/docs/ru/introduction.mdx index 90038880..d256e99e 100644 --- a/docs/ru/introduction.mdx +++ b/docs/ru/introduction.mdx @@ -1,37 +1,36 @@ --- ---- title: "Failproof AI" -description: "FailproofAI предоставляет AI-агентам 39 встроенных политик отказоустойчивости, которые ловят циклы, утечки секретов, деструктивные вызовы инструментов и многое другое с помощью одной установки." +description: "FailproofAI предоставляет AI-агентам 39 встроенных политик отказоустойчивости, которые ловят зацикливание, утечки секретов, деструктивные вызовы инструментов и многое другое при одной установке." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Хуки и политики для **обработки сбоев AI**, **восстановления после ошибок** и **надежности LLM**. Делайте ваши AI-агенты надежными и работающими автономно в **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** и **Agents SDK**. +Хуки и политики для **обработки отказов AI**, **восстановления после ошибок** и **надёжности LLM**. Держите ваших AI-агентов надёжными и работающими автономно в **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** и **Agents SDK**. -AI-агенты отказывают предсказуемым образом. Они выполняют деструктивные команды, утекают секреты, отклоняются от задачи, застревают в циклах или пушат прямо в основную ветку. Без контроля небольшие сбои перерастают в сбои системы, утечки учетных данных и потерю работы. +AI-агенты отказывают предсказуемо. Они запускают деструктивные команды, утекают секреты, отклоняются от задачи, застревают в циклах или делают push прямо в main. Без присмотра небольшие ошибки накапливаются в перебои в работе, утечки учётных данных и потерю работы. -FailproofAI решает эту проблему с помощью **политик**. Эти правила перехватывают каждый вызов инструмента агента для **обнаружения сбоев**, **их смягчения** (блокировка, инструктирование, санитизация) и **оповещения вас** о проблемах, требующих внимания. Локальная панель мониторинга позволяет просмотреть каждый вызов инструмента, отказ агента и действие восстановления впоследствии. +FailproofAI решает эту проблему с помощью **политик**. Эти правила подключаются к каждому вызову инструмента агента, чтобы **обнаруживать отказы**, **смягчать их** (блокировать, инструктировать, санировать) и **оповещать вас**, когда требуется внимание. Локальная панель позволяет позже просмотреть каждый вызов инструмента, отказ агента и действие восстановления. -Стенограммы и оценка политик остаются на вашем компьютере. Данные отправляются только при явном использовании онлайн-функции, такой как аутентифицированные напоминания об аудите или приглашения. +Стенограммы и оценка политик остаются на вашем устройстве. Данные отправляются только при явном использовании онлайн-функции, например при аутентифицированных напоминаниях об аудите или приглашениях. -## Начало работы +## Начните работу - Блокируйте деструктивные команды, предотвращайте утечки секретов, держите агентов в границах проекта и многое другое. Все из коробки. + Блокируйте деструктивные команды, предотвращайте утечки секретов, держите агентов в границах проекта и многое другое. Всё готово к использованию. - Напишите свои собственные правила на JavaScript с простым API allow / deny / instruct. + Напишите собственные правила на JavaScript с простым API allow / deny / instruct. - Смотрите, что делали ваши агенты, пока вас не было. Просматривайте сессии, проверяйте вызовы инструментов, смотрите, где срабатывали политики. + Смотрите, что делали ваши агенты, пока вас не было. Просматривайте сессии, проверяйте вызовы инструментов, узнавайте, где сработали политики. - Настраивайте любую политику без кода. Установите списки разрешений, защищенные ветки или пороги для каждого проекта или глобально. + Настраивайте любую политику без кода. Устанавливайте списки допустимых адресов, защищённые ветви или пороги для отдельного проекта или глобально. @@ -51,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # включить политики (или пропустить — `failproofai` предложит настроить их при первом запуске) -failproofai # запустить панель мониторинга +failproofai policies --install # включить политики (или пропустить — `failproofai` предложит их настроить при первом запуске) +failproofai # открыть панель ``` -Полный обзор см. в руководстве [Начало работы](/ru/getting-started). \ No newline at end of file +Полное руководство смотрите в [Getting started](/ru/getting-started). \ No newline at end of file diff --git a/docs/ru/package-aliases.mdx b/docs/ru/package-aliases.mdx index 731a1ced..ac969e3f 100644 --- a/docs/ru/package-aliases.mdx +++ b/docs/ru/package-aliases.mdx @@ -1,12 +1,13 @@ --- -title: Aliases пакетов -description: "Зарегистрированные aliases для предотвращения опечаток и как они работают" +--- +title: Псевдонимы пакетов +description: "Зарегистрированные псевдонимы для предотвращения опечаток и их работа" icon: copy --- ## Официальный пакет -Канонический npm пакет — это **`failproofai`**: +Канонический пакет npm — это **`failproofai`**: ```bash npm install -g failproofai @@ -16,67 +17,67 @@ bun add -g failproofai --- -## Почему мы владеем этими aliases +## Почему мы владеем этими псевдонимами -Typosquatting — это распространённая атака на цепочку поставок, при которой злоумышленник регистрирует название пакета, отличающееся от популярного пакета на один символ. Пользователи, которые случайно ошибаются при вводе команды установки, запускают контролируемый атакующим код с полным доступом к системе — именно против такого рода угроз разработана система Failproof AI. +Typosquatting — это распространённый вид атаки на цепочку поставок, при котором злоумышленник регистрирует имя пакета, отличающееся от популярного пакета на одну опечатку. Неосторожные пользователи, допустившие ошибку при вводе команды установки, запускают контролируемый атакующим код с полным доступом к системе — ровно ту угрозу, против которой разработана Failproof AI. -Чтобы исключить эту уязвимость, **мы заблаговременно зарегистрировали все распространённые опечатки и варианты написания** `failproofai` на npm. Никто из третьих лиц не может зарегистрировать эти названия. Каждое из них — это тонкий proxy, который устанавливает и делегирует работу реальному пакету `failproofai`. +Чтобы исключить этот риск, **мы заранее зарегистрировали все распространённые опечатки и форматные варианты** названия `failproofai` на npm. Ни одно из этих имён не может быть зарегистрировано третьей стороной. Каждый из них — это тонкий прокси, который устанавливает реальный пакет `failproofai` и перенаправляет ему вызовы. --- -## Зарегистрированные aliases +## Зарегистрированные псевдонимы -**Варианты написания** — разные способы написания "failproof ai": +**Форматные варианты** — различные способы написания "failproof ai": | Пакет | Статус | |---------|--------| -| `failproof` | ✅ Опубликовано | +| `failproof` | ✅ Опубликован | | `failproof-ai` | ⏳ Ожидание поддержки npm | | `fail-proof-ai` | ⏳ Ожидание поддержки npm | | `failproof_ai` | ⏳ Ожидание поддержки npm | | `fail_proof_ai` | ⏳ Ожидание поддержки npm | | `fail-proofai` | ⏳ Ожидание поддержки npm | -**`failprof*` опечатки** — пропущена одна буква `o` в слове "proof": +**Опечатки `failprof*`** — пропущена одна буква `o` в слове "proof": | Пакет | Статус | |---------|--------| -| `failprof` | ✅ Опубликовано | -| `failprof-ai` | ✅ Опубликовано | +| `failprof` | ✅ Опубликован | +| `failprof-ai` | ✅ Опубликован | | `failprofai` | ⏳ Ожидание поддержки npm | | `fail-prof-ai` | ⏳ Ожидание поддержки npm | | `failprof_ai` | ⏳ Ожидание поддержки npm | -**`faliproof*` опечатки** — переставлены буквы `a` и `i`: +**Опечатки `faliproof*`** — переставлены буквы `a` и `i`: | Пакет | Статус | |---------|--------| -| `faliproof` | ✅ Опубликовано | -| `faliproof-ai` | ✅ Опубликовано | +| `faliproof` | ✅ Опубликован | +| `faliproof-ai` | ✅ Опубликован | | `faliproofai` | ⏳ Ожидание поддержки npm | -> **Почему ожидание?** Политика npm по борьбе со спамом блокирует названия, которые нормализуются в ту же строку, что и существующий пакет, после удаления пунктуации и применения проверок на схожесть. Мы обратились в поддержку npm, чтобы зарезервировать эти названия в целях предотвращения squat-атак. Они будут активированы после одобрения. +> **Почему статус ожидания?** Политика npm по борьбе со спамом блокирует имена, которые нормализуются в ту же строку, что и существующий пакет, после удаления пунктуации и проверки схожести. Мы обратились в службу поддержки npm для зарезервирования этих имён в целях защиты от перехвата. Они будут активированы после одобрения. -Вы можете проверить, что любой опубликованный alias принадлежит нам: +Вы можете проверить, что любой опубликованный псевдоним принадлежит нам: ```bash npm info failproof -# Найдите: "ExosphereHost Inc." в поле maintainers +# Поищите: "ExosphereHost Inc." в поле maintainers ``` --- -## Как работают aliases +## Как работают псевдонимы -Каждый alias пакет: +Каждый пакет-псевдоним: -1. Указывает `failproofai` как зависимость — таким образом устанавливается реальный пакет и становится доступным его binary -2. Предоставляет binary с именем, совпадающим с его собственным названием (например `failprof-ai`), который передаёт все аргументы в binary `failproofai` +1. Указывает `failproofai` как зависимость — поэтому реальный пакет устанавливается и его бинарный файл становится доступным +2. Открывает бинарный файл с именем, совпадающим с его собственным именем (например `failprof-ai`), который перенаправляет все аргументы бинарному файлу `failproofai` -Proxy — это двухстрочный скрипт Node.js; в нём нет логики, сетевых запросов и сбора данных помимо того, что делает сам `failproofai`. +Прокси — это двухстрочный скрипт Node.js; в нём нет логики, сетевых запросов и сбора данных сверх того, что делает сам `failproofai`. --- -## Если мы пропустили какое-то название +## Если вы обнаружили пропущенное имя -Откройте issue в [failproofai/failproofai](https://github.com/failproofai/failproofai/issues), и мы зарегистрируем его. \ No newline at end of file +Откройте issue на [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) и мы его зарегистрируем. \ No newline at end of file diff --git a/docs/ru/testing.mdx b/docs/ru/testing.mdx index cf9b7d54..74f9b7d0 100644 --- a/docs/ru/testing.mdx +++ b/docs/ru/testing.mdx @@ -1,10 +1,10 @@ --- title: Тестирование -description: "Модульные тесты, E2E-тесты и вспомогательные утилиты для тестирования" +description: "Модульные тесты, E2E тесты и помощники для тестирования" icon: flask-vial --- -failproofai имеет два набора тестов: **модульные тесты** (быстрые, с моками) и **сквозные тесты** (реальные вызовы подпроцессов). +failproofai имеет два набора тестов: **модульные тесты** (быстрые, с моками) и **end-to-end тесты** (реальные вызовы подпроцессов). --- @@ -17,13 +17,13 @@ bun run test:run # Запустить модульные тесты в режиме наблюдения bun run test -# Запустить E2E-тесты (требует предварительной настройки - см. ниже) +# Запустить E2E тесты (требуется подготовка — см. ниже) bun run test:e2e # Проверка типов без сборки bunx tsc --noEmit -# Проверка кода +# Linting bun run lint ``` @@ -36,12 +36,12 @@ bun run lint ```text __tests__/ hooks/ - builtin-policies.test.ts # Логика политик для каждой встроенной политики - hooks-config.test.ts # Загрузка конфига и слияние областей видимости - policy-evaluator.test.ts # Инъекция параметров и порядок оценки - custom-hooks-registry.test.ts # Регистр globalThis - добавление/получение/очистка + builtin-policies.test.ts # Логика политик для каждой встроенной + hooks-config.test.ts # Загрузка конфига и слияние областей + policy-evaluator.test.ts # Внедрение параметров и порядок оценки + custom-hooks-registry.test.ts # Реестр globalThis для добавления/получения/очистки custom-hooks-loader.test.ts # ESM загрузчик, транзитивные импорты, обработка ошибок - manager.test.ts # Операции установки/удаления/списания + manager.test.ts # Операции установки/удаления/списка components/ sessions-list.test.tsx # Компонент списка сессий project-list.test.tsx # Компонент списка проектов @@ -108,13 +108,13 @@ describe("block-sudo", () => { --- -## Сквозные тесты +## End-to-end тесты -E2E-тесты вызывают реальный бинарный файл `failproofai` в виде подпроцесса, отправляют JSON-полезную нагрузку в stdin и проверяют вывод на stdout и код выхода. Это тестирует полный путь интеграции, который использует Claude Code. +E2E тесты вызывают реальный бинарный файл `failproofai` как подпроцесс, передают JSON-полезную нагрузку в stdin и проверяют вывод stdout и код выхода. Это тестирует полный путь интеграции, который использует Claude Code. -### Настройка +### Подготовка -E2E-тесты запускают бинарный файл непосредственно из исходного кода репозитория. Перед первым запуском соберите CJS-пакет, который используют файлы пользовательских hook при импорте из `'failproofai'`: +E2E тесты запускают бинарный файл непосредственно из исходного кода репозитория. Перед первым запуском соберите CJS-бандл, который файлы пользовательских хуков используют при импорте из `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,33 +126,33 @@ bun build src/index.ts --outdir dist --target node --format cjs bun run test:e2e ``` -Пересоберите `dist/` каждый раз, когда вы изменяете публичный API hook (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` или `src/hooks/policy-types.ts`). +Пересобирайте `dist/` каждый раз, когда вы изменяете публичный API хуков (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` или `src/hooks/policy-types.ts`). -### Структура E2E-теста +### Структура E2E теста ```text __tests__/e2e/ helpers/ - hook-runner.ts # Запуск бинарного файла, отправка JSON в stdin, получение кода выхода + stdout + stderr + hook-runner.ts # Запуск бинарного файла, передача JSON в stdin, захват кода выхода + stdout + stderr fixture-env.ts # Изолированные для каждого теста временные директории с файлами конфига - payloads.ts # Фабрики полезных нагрузок для каждого типа события, совместимые с Claude + payloads.ts # Фабрики полезных нагрузок для каждого типа события, точные как в Claude hooks/ builtin-policies.e2e.test.ts # Каждая встроенная политика с реальным подпроцессом - custom-hooks.e2e.test.ts # Загрузка и оценка пользовательских hook - config-scopes.e2e.test.ts # Слияние конфига в проекте/локально/глобально - policy-params.e2e.test.ts # Инъекция параметров для каждой параметризованной политики + custom-hooks.e2e.test.ts # Загрузка и оценка пользовательских хуков + config-scopes.e2e.test.ts # Слияние конфига в проекте/локальное/глобальное + policy-params.e2e.test.ts # Внедрение параметров для каждой параметризованной политики ``` -### Использование E2E-вспомогательных утилит +### Использование E2E помощников -**`FixtureEnv`** - изолированная среда для каждого теста: +**`FixtureEnv`** — изолированная окружение для каждого теста: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - временная директория; передайте как payload.cwd для использования .failproofai/policies-config.json -// env.home - изолированная домашняя директория; никакие настоящие ~/.failproofai не протекают +// env.cwd - временная директория; передайте как payload.cwd для загрузки .failproofai/policies-config.json +// env.home - изолированная директория home; реальные ~/.failproofai не загружаются env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` автоматически регистрирует очистку `afterEach`. +`createFixtureEnv()` автоматически регистрирует очистку в `afterEach`. -**`runHook`** - вызов бинарного файла: +**`runHook`** — вызов бинарного файла: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - готовые фабрики полезных нагрузок: +**`Payloads`** — готовые фабрики полезных нагрузок: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -192,7 +192,7 @@ Payloads.notification(message, cwd) Payloads.stop(cwd) ``` -### Написание E2E-теста +### Написание E2E теста ```typescript import { describe, it, expect } from "vitest"; @@ -226,7 +226,7 @@ describe("block-rm-rf (E2E)", () => { ); expect(result.exitCode).toBe(0); - expect(result.stdout).toBe(""); // разрешено → пустой stdout + expect(result.stdout).toBe(""); // allow → пустой stdout }); }); ``` @@ -235,19 +235,19 @@ describe("block-rm-rf (E2E)", () => { | Решение | Код выхода | stdout | |----------|-----------|--------| -| `PreToolUse` отклонено | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | -| `PostToolUse` отклонено | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Инструкция (не Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop-инструкция | `2` | пустой stdout; причина в stderr | -| Разрешить | `0` | пустая строка | +| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | +| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | +| Instruct (не-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Stop instruct | `2` | пустой stdout; причина в stderr | +| Allow | `0` | пустая строка | ### Конфиг Vitest -E2E-тесты используют `vitest.config.e2e.mts` с: +E2E тесты используют `vitest.config.e2e.mts` с: -- `environment: "node"` - браузерные глобальные переменные не требуются -- `pool: "forks"` - истинная изоляция процессов (тесты запускают подпроцессы) -- `testTimeout: 20_000` - 20s на тест (запуск бинарного файла + оценка hook) +- `environment: "node"` — глобали браузера не требуются +- `pool: "forks"` — настоящая изоляция процессов (тесты запускают подпроцессы) +- `testTimeout: 20_000` — 20s на тест (запуск бинарного файла + оценка хука) Пул `forks` важен: рабочие на основе потоков совместно используют `globalThis`, что может помешать тестам, запускающим подпроцессы. Форки на основе процессов избегают этого. @@ -255,6 +255,6 @@ E2E-тесты используют `vitest.config.e2e.mts` с: ## CI -Полный запуск CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) должен пройти перед слиянием. E2E-набор запускается как отдельное задание CI параллельно. +Полный CI запуск (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) должен пройти перед слиянием. E2E набор запускается как отдельное задание CI параллельно. -Смотрите [Участие в разработке](../CONTRIBUTING.md) для полного контрольного списка перед слиянием. \ No newline at end of file +Смотрите [Contributing](../CONTRIBUTING.md) для полного контрольного списка перед слиянием. \ No newline at end of file diff --git a/docs/tr/agenteye/alerts.mdx b/docs/tr/agenteye/alerts.mdx index c07458bd..21848d9d 100644 --- a/docs/tr/agenteye/alerts.mdx +++ b/docs/tr/agenteye/alerts.mdx @@ -1,33 +1,33 @@ --- title: "Uyarılar" -description: "Müşterinizden duyar duymaz, ekibinizin zaten izlediği kanala bir şey limitinizi aşan an da haberi alın." +description: "Müşteri haberi vermeden önce sınırınızı aşan şeyi tam o anda öğrenin, ekibinizin zaten izlediği kanalda." --- -Müşterinizden duyar duymaz, ekibinizin zaten izlediği kanala bir şey limitinizi aşan an da haberi alın. Kuralı bir kez ayarlayın ve Failproof AI Observability bunu düzenli olarak kontrol etsin, sonra sizi e-posta, Slack, webhook veya doğrudan panoda bildirsin. +Müşteri haberi vermeden önce sınırınızı aşan şeyi tam o anda öğrenin, ekibinizin zaten izlediği kanalda. Kuralı bir kez ayarlayın ve Failproof AI Observability bunu düzenli olarak kontrol ederek, e-posta, Slack, webhook aracılığıyla veya doğrudan gösterge panelinde sizi bilgilendirir. -![Uyarılar sayfası: her biri tetikleyicisini, değerlendirme penceresini, kanallarını ve bilgi, uyarı veya kritik öncelik rozetini gösteren uyarı kuralı kartlarının ızgarası](/agenteye/images/alerts.png) -*Her uyarı kuralı bir bakışta: neyi izliyor, ne sıklıkta, nereye bildiriyor ve ne kadar acil.* +![Uyarılar sayfası: her biri tetikleyicisi, değerlendirme penceresi, kanalları ve bilgi, uyarı veya kritik önem rozetini gösteren bir uyarı kuralı kartları ızgarası](/agenteye/images/alerts.png) +*Her uyarı kuralı bir bakışta: neyi izlediği, ne sıklıkla, nereye bilgilendirdiği ve ne kadar acil olduğu.* -## Kullanıcılarınız bilmeden sorunları öğrenin +## Kullanıcılarınızdan önce sorunları öğrenin -Bir regresyonu yakalamak için panoyu sürekli yenilemeyi bırakın. Hiç kimse bakmıyorken bile duymanız gereken bir sinyal olduğunda bir uyarıya başvurun ve bunu zaten bulunduğunuz yere iletişim kurun: +Bir regresyonu yakalamak umuduyla gösterge panelini yenilemek yerine, kimse bakmadığında bile haber almak isteyeceğiniz her sinyal için bir uyarıya başvurun ve zaten bulunduğunuz yere iletilmesini sağlayın: -- **E-posta**, bilmesi gereken herkese. -- **Slack**, olayın tam bulunduğu noktaya atlayan düğmeli zengin bir mesaj. -- **Webhook**, PagerDuty, Opsgenie veya kendi uç noktanız için, alıcının buna güvenebilmesi için isteğe bağlı imzalı JSON POST. -- **Panoda**, sessiz tasarımla, bir kuralı ayarlarken henüz kimseyi bildirmek istemediğiniz zamanlar için. +- **E-posta**, bilmesi gerekenler için. +- **Slack**, hemen olaya gitmek için bir düğme içeren zengin bir mesaj. +- **Webhook**, PagerDuty, Opsgenie veya kendi uç noktanız için isteğe bağlı imza ile bir JSON POST'u, alıcının buna güvenebilmesi için. +- **Gösterge panelinde**, sessiz olarak tasarlandı, kural ayarlarken kimseyi bilgilendirmek istemediğiniz zamanlar için. -Herhangi bir kombinasyonu tek bir kurala ekleyin ve önem derecesi (bilgi, uyarı veya kritik) o kuralla beraber gider, böylece acil olanlar acil görünür. +Tek bir kurala herhangi bir kombinasyon ekleyin ve önem düzeyi (bilgi, uyarı veya kritik) birlikte gider, böylece acil olanlar acil görünür. -## Kuralı JSON değil, formda oluşturun +## Kuralı JSON'da değil, bir formda oluşturun -Bir formda "bozuk" demek ne anlama geldiğini açıklayın ve Failproof AI Observability size altında yatan kuralı yazacak. JSON özellikleri sadece o formun altında ürettiği şeydir, bu nedenle onu okuyarak bir kuralı anlayabilirsiniz ama nadiren yazarsınız. +"Bozuk" kelimesinin ne anlama geldiğini bir formda açıklarsınız ve Failproof AI Observability temel kuralı sizin için yazar. JSON spec sadece o formun altında ürettiği şeydir, bu nedenle kuralı anlamak için okuyabilirsiniz ancak ender olarak yazarsınız. -![Yeni uyarı formu: ad ve açıklama, etkinleştirme geçişi ve metrik eşiği, özel SQL, değerlendirme puanı, bileşik değerlendirme ve etkinlik başına koşullar sunan tetikleyici seçici](/agenteye/images/alert-new.png) +![Yeni uyarı formu: ad ve açıklama, etkinleştir kaydırıcısı ve metrik eşik, özel SQL, değerlendirme puanı, bileşik eval ve olay başına koşullar sunan bir tetikleyici seçici](/agenteye/images/alert-new.png) *Bir tetikleyici seçin ve form doğru alanları değiştirir; Kaydet kuralı yazar.* -Mutlu yol hızlıdır: adını verin, bir **tetikleyici** seçin (neyi izleyeceğiniz), **eşik ve pencereyi** ayarlayın (ne kadar kötü, ne kadar süre), en az bir **kanal** ekleyin, sonra **Kaydet** yapın ve her hedefin bağlı olduğunu doğrulamak için **Test** e tıklayarak sentetik bir bildirim gönderin. Altında buna benzer küçük bir spec üretir: +Mutlu yol hızlı: adlandırın, bir **tetikleyici** seçin (neyi izleyecek), **eşik ve pencereyi** ayarlayın (ne kadar kötü, ne kadar süre), en az bir **kanal** ekleyin, **Kaydet** ve sentetik bir bildirim göndermek ve her hedefin kablolu olduğunu doğrulamak için **Test** tuşuna basın. Altında şöyle bir spec üretir: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } @@ -35,29 +35,29 @@ Mutlu yol hızlıdır: adını verin, bir **tetikleyici** seçin (neyi izleyece Bir sinyal türüyle sınırlı değilsiniz. Hatayı nasıl düşündüğünüzle eşleşen tetikleyiciyi seçin: -| Tetikleyici | Ateşlenir | +| Tetikleyici | Ne zaman ateşlenir | |---|---| -| **Metrik eşiği** | önceden ayarlanmış bir metrik (hata oranı, p95 veya p99 gecikmesi, olay veya hata sayıları, token harcaması) bir pencere üzerinde limitinizi aştığında | -| **Özel SQL** | kendi salt okunur sorgunuz bir satır döndürdüğünde veya hesapladığı bir değer eşiği aştığında | -| **Değerlendirme puanı** | bir değerlendirici puanının ortalaması (örneğin, halüsinasyon) eşiği aştığında | -| **Bileşik değerlendirme** | birkaç puan kontrolü herhangi, tümü veya en az N mantığıyla birleştirilir, yalnızca puanlar arasında görünen bir regresyonu yakalaması için | -| **Etkinlik başına** | eşleşen tek bir olay gelir: belirli bir ajan, belirli bir hata türü veya bir mesaj alt dizesi | +| **Metrik eşik** | önceden ayarlanmış bir metrik (hata oranı, p95 veya p99 latency, olay veya hata sayıları, token harcaması) bir pencere üzerinde sınırınızı aşarsa | +| **Özel SQL** | kendi salt okunur sorgunuz bir satır döndürürse veya hesapladığı bir değer bir eşiği aşarsa | +| **Değerlendirme puanı** | bir değerlendirici puanının ortalaması (örneğin, halüsinasyon) bir eşiği aşarsa | +| **Bileşik eval** | yalnızca puanlar arasında görünen regresyonu yakalamak için birkaç puan kontrolü, herhangi biri, tümü veya en-az-N mantığıyla birleşirse | +| **Olay başına** | belirli bir eşleşen olay varırsa: belirli bir ajan, belirli bir hata türü veya ileti alt dizesi | -Zaten [Hatalar sayfasında](/tr/agenteye/error-tracking) bir hataya bakıyor musunuz? Oradaki her satırın bu aynı formu tam olarak şu hatayı yakalamak için önceden doldurmuş bir **+ uyarı** düğmesi vardır, bu nedenle az önce triajladığınız olay bir sonraki seferde sizi bildiren olur. +Zaten [Hatalar sayfasında](/tr/agenteye/error-tracking) bir hataya bakıyor musunuz? Orada her satırda bu aynı formu tam o hatayı yeniden yakalamak için önceden doldurulmuş olarak açan bir **+ uyarı** düğmesi vardır, böylece az önce triaj ettiğiniz olay bir sonraki sefere sizi bilgilendiren olay haline gelir. -**Nerede bulunur:** Uyarılar `//alerts` adresinde bulunur. Kurallar oluşturmak, düzenlemek, silmek ve test etmek **`alerts:write`** gerektirir; bakmak için `alerts:read` yeterlidir. Alıcı seçici kuruluşunuzun üyelerini ad ile listeler, bu nedenle formu bırakmadan bir kişiyi bildirebilirsiniz. +**Nerede bulacaksınız:** Uyarılar `//alerts` adresinde bulunur. Kuralları oluşturmak, düzenlemek, silmek ve test etmek **`alerts:write`** gerektirir; `alerts:read` bakışı yeterlidir. Alıcı seçici, kuruluşunuzun üyelerini ad ile listeler, böylece formu terk etmeden bir kişiyi bilgilendirebilirsiniz. -## Beni sadece gerçek olduğunda bildirin +## Beni yalnızca gerçek olduğunda bilgilendir -Bir kötü ölçüm sizi uyandırmamalı. **M of N** gürültü filtresi, uyarının aslında sizi bildirmesinden önce son birkaç kontrolün kaçının başarısız olması gerektiğini denetler. Bunu **3 of 5** olarak ayarlayın ve kural sadece son beş kontrolünün üçünü ihlal ettikten sonra ateşlenir, bu nedenle titreşimli bir sinyal çığlık atmayı durdurur; ilk ihlali ateşlemek için varsayılan **1 of 1** de bırakın. Ayrıca kuralın ne sıklıkta çalışacağını da seçersiniz: 1m, 5m, 15m ve 1h ön ayarlarından, sinyalin gerçekten ne kadar hızlı hareket ettiğine göre eşleştirilmiştir. +Bir kötü ölçüm sizi uyandırmamalı. **M of N** gürültü filtresi, uyarı gerçekte sizi bilgilendirmeden önce son birkaç kontrol ile kaçının başarısız olması gerektiğini kontrol eder. **3 of 5** olarak ayarlayın ve kural yalnızca son beş kontrol ile üçünü ihlal ettikten sonra ateşlenir, böylece titrek bir sinyal yanlış alarm yapmayı durdurur; ilk ihlalde ateşlenecek şekilde varsayılan **1 of 1** bırakın. Ayrıca kuralın ne sıklıkta çalıştığını seçersiniz, 1m, 5m, 15m ve 1s önceden ayarlanmış değerlerden, sinyalin gerçekte ne kadar hızlı hareket ettiğine uyumlu. -## Bir uyarı ateşlendiğinde ne olur +## Uyarı tetiklendiğinde ne olur -Bir ihlal bir **olayı** açar ve kanallarınızı bir kez bildirir. Oradan ekibiniz bunu onaylar, sahibini atar, üzerinde tartışır ve temiz, atfedilmiş bir kayda karşı çözer. O triaj iş akışının kendi evi vardır: [Olaylar](/tr/agenteye/incidents) konusuna bakın. +Bir ihlal bir **olay** açar ve kanallarınızı bir kez bilgilendirir. Oradan ekibiniz bunu kabul eder, sahibini atar, tartışır ve çözer, hepsi temiz, atfedilen bir kayıta karşı. Bu triaj akışının kendi evi vardır: [Olaylar](/tr/agenteye/incidents) bölümüne bakın. ## İlgili -- [Olaylar](/tr/agenteye/incidents): ateşlenen bir uyarıyı açıktan onaylanana çözüme kadar izleyin. -- [Hata izleme](/tr/agenteye/error-tracking): ajan hatalarını gruplandırın ve bir tıkla birini uyarıya yükseltin. -- [Panolar](/tr/agenteye/dashboards): uyarıda bulunduğunuz eşiklerin geldiği paylaşılan panoları izleyin. -- [CLI ve ajanlar](/tr/agenteye/cli-and-agents): terminalinizden uyarılar oluşturun ve olayları onaylayın veya CI'ye yazın. \ No newline at end of file +- [Olaylar](/tr/agenteye/incidents): ateşlenen bir uyarıyı açıktan kabul edilene kadar çözülene kadar izleyin. +- [Hata takibi](/tr/agenteye/error-tracking): ajan hatalarını gruplandırın ve bir tıkla biri uyarıya yükseltin. +- [Gösterge panelleri](/tr/agenteye/dashboards): uyarı verdiğiniz eşiklerin geldiği paylaşılan panoları izleyin. +- [CLI ve ajanlar](/tr/agenteye/cli-and-agents): terminalinizden uyarılar oluşturun ve olayları onayla veya bunları CI'ye yazın. \ No newline at end of file diff --git a/docs/tr/agenteye/api-keys.mdx b/docs/tr/agenteye/api-keys.mdx index 6dee33c5..424d7a40 100644 --- a/docs/tr/agenteye/api-keys.mdx +++ b/docs/tr/agenteye/api-keys.mdx @@ -1,172 +1,172 @@ --- title: "API Anahtarları" -description: "API anahtarları Failproof AI Gözlemlenebilirlik sunucunuza erişebilecek olanları ve neleri kontrol eder, bu sayede bir toplayıcı hiçbir zaman okuma veya yönetici yetkisi kazanmadan olayları gönderebilir." +description: "API anahtarları, Failproof AI Observability sunucunuza kimlerin ve nelerin erişebileceğini kontrol eder; böylece bir toplayıcı hiçbir zaman okuma veya yönetici haklarına sahip olmadan olayları gönderebilir." --- -API anahtarları Failproof AI Gözlemlenebilirlik sunucunuza erişebilecek olanları ve neleri kontrol eder, bu sayede bir toplayıcı hiçbir zaman okuma veya yönetici yetkisi kazanmadan olayları gönderebilir. Her anahtar bir veya daha fazla izne sahiptir ve her izin belirli sunucu rotalarını denetler; yalnızca bir işin ihtiyacı olan izinleri verirsiniz. Çoğu dağıtımda sadece üç tür anahtar oluşturulur. +API anahtarları, Failproof AI Observability sunucunuza kimlerin ve nelerin erişebileceğini kontrol eder; böylece bir toplayıcı hiçbir zaman okuma veya yönetici haklarına sahip olmadan olayları gönderebilir. Her anahtar bir veya daha fazla izne sahiptir ve her izin belirli sunucu rotalarını kilitler; yalnızca bir işin ihtiyaç duyduğu kadarını verirsiniz. Çoğu dağıtım sadece üç tür anahtar oluşturur. -## Çoğu dağıtımın ihtiyacı olan 3 anahtar +## Çoğu dağıtımın ihtiyaç duyduğu 3 anahtar | Anahtar | İzinler | Kullanan | |---|---|---| | Toplayıcı anahtarı | `events:add` | Her ajan makinesindeki `agenteye-collector`, olayları göndermek için. | -| Kontrol paneli okuma anahtarı | `events:read`, `keys:read` | Verileri değiştirmeden sorgulayan salt okunur operatör veya entegrasyon. | -| Önyükleme yönetici anahtarı | tüm izinler | İlk kez örneği ayağa kaldıran operatör (ve kontrol paneli). `ADMIN_KEY` ortam değişkeninden başlatılır. Bkz. [Önyükleme yönetici anahtarı](#önyükleme-yönetici-anahtarı). | +| Pano okuma anahtarı | `events:read`, `keys:read` | Verileri değiştirmeden sorgulayan salt okunur operatör veya entegrasyon. | +| Önyükleme yönetici anahtarı | tüm izinler | Örneği ilk kez başlatan (ve panoyu) operatör. `ADMIN_KEY` ortam değişkeninden yapılır. Bkz. [Önyükleme yönetici anahtarı](#önyükleme-yönetici-anahtarı). | -Buradan başlayın. Daha dar, özel kapsamlı bir anahtar gerekirse, aşağıdaki tam izin kataloğuna başvurun. Ayrıca bkz. [Önerilen anahtar düzeni](#önerilen-anahtar-düzeni) ve [Anahtar oluşturma](#anahtar-oluşturma). +Buradan başlayın. Daha dar, özel kapsamlı bir anahtar gerektiğinde tam izin kataloğuna aşağıda bakın. Ayrıca bkz. [Önerilen anahtar düzeni](#önerilen-anahtar-düzeni) ve [Anahtar oluşturma](#anahtar-oluşturma). --- ## İzinler -Sunucu sabit bir izin kataloğu uygular; her biri belirli HTTP rotalarını denetler. Bir **yönetici anahtarı** hepsini tutar; kapsamlı bir anahtar oluşturma sırasında verdiğiniz alt kümesini tutar. Bilinmeyen izin dizeleri anahtar oluşturulduğunda reddedilir. +Sunucu sabit bir izin kataloğu uygular; her biri belirli HTTP rotalarını kilitler. Bir **yönetici anahtarı** bunların hepsini içerir; kapsamlı bir anahtar oluşturmada size verdiğiniz alt kümesini içerir. Bilinmeyen izin dizgileri, bir anahtar oluşturulduğunda reddedilir. -> **Not:** İki geçerli izin insan/kontrol paneli özeldir ve API anahtarına verilemez: `orgs:admin` (örnek yönetimi, yalnızca operatör için) ve `keys:update`. Bu ikisinden birini vermeye çalışan bir `POST /keys` veya `PATCH /keys/:id` isteği HTTP 422 ile reddedilir. Bir taşıyıcı anahtarın anahtarlar oluşturabilmesinin ama hiçbir zaman bunları düzenleyememesinin nedenini görmek için aşağıdaki `keys:update` satırına bakın. +> **Not:** İki geçerli izin insan/pano-yalnız ve bir API anahtarına verilemez: `orgs:admin` (örnek yönetimi, operatör-yalnız) ve `keys:update`. `POST /keys` veya `PATCH /keys/:id` isteği, bunlardan birini vermeyi denemek HTTP 422 ile reddedilir. Taşıyıcı anahtarın neden anahtar oluşturabileceği ancak bunları asla düzenleyemeyeceğini anlamak için aşağıdaki `keys:update` satırına bakın. -### Olayları yutma ve sorgulama +### Olay alımı ve sorgulama -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `events:add` | `POST /events` | Toplayıcıdan olay gruplarını yut. Toplayıcının ihtiyacı olan tek izin. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Olayları sorgula, bilinen ortamları listele, verilerde görülen model tanımlayıcılarını listele (Modeller görünümü ve model filtreleri tarafından kullanılır), ısı haritası / yüzdelik bandı güçlendiren gecikme toplamasını hesapla ve bir oturumu JSONL olarak dışa aktar. Paylaşılan filtre çubuğu faset uç noktaları `GET /events/environments` ve `GET /events/agent_ids` **ya da** `events:read` **ya da** `evaluations:read` ile erişilebilir, bu nedenle oturumlar sayfası (gated `evaluations:read`) aynı org başına faset'i yeniden kullanır. `GET /events/models` bunlardan biri değildir: `events:read` gerektirir, bu nedenle yalnızca `evaluations:read` tutan bir asıl bundan 403 alır. | +| `events:add` | `POST /events` | Toplayıcıdan olay gruplarını alın. Bir toplayıcının ihtiyaç duyduğu tek izin. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Olayları sorgulayın, bilinen ortamları listeleyin, verilerde görülen model tanımlayıcılarını listeleyin (Modeller görünümü ve model filtreleri tarafından kullanılır), ısı haritası / yüzdelik bandını güçlendiren gecikme toplamını hesaplayın ve bir oturumu JSONL olarak dışa aktarın. Paylaşılan filtre çubuğu faset uç noktaları `GET /events/environments` ve `GET /events/agent_ids` **ya** `events:read` **ya da** `evaluations:read` ile erişilebilir, böylece oturumlar sayfası (`evaluations:read` kilitli) aynı kuruluş başına faset'i yeniden kullanır. `GET /events/models` bunlardan biri değildir: `events:read` gerektirir, bu nedenle yalnızca `evaluations:read` tutan bir ilke 403 alır. | ### Oturumlar ve değerlendirmeler -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Oturumları listele, değerlendirme sonuçlarını oku, kontrol panoları tarafından kullanılan toplanmış eval sağlığını ve değerlendirme-iş işçi kuyruğu durumunu. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Tamamlanan bir oturuma yönelik yeniden değerlendirmeyi el ile kuyruğa al. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Oturumları listeleyin, değerlendirme sonuçlarını okuyun, panolar tarafından kullanılan toplanmış eval sağlığını ve değerlendirme-işi işçi kuyruğu durumunu. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Bitmiş bir oturum için el ile yeniden değerlendirme sırasına alın. | -### Kontrol Panoları +### Panolar -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Kontrol panellerini listele, birini yükle ve kutularını oku. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Kontrol panellerini oluştur ve düzenle, kutu ekle / düzenle / kaldır ve kutu ızgarasını yeniden sırala. | -| `dashboards:delete` | `DELETE /dashboards/:id` | Tüm kontrol panelini sil (kutu seviyesi silme `dashboards:write` altında yaşar). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Panoları listeleyin, birini yükleyin ve kutucuklarını okuyun. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Panoları oluşturun ve düzenleyin, kutucukları ekleyin / düzenleyin / kaldırın ve kutucuk ızgarasını yeniden sıralayın. | +| `dashboards:delete` | `DELETE /dashboards/:id` | Tüm panoyu silin (kutucuk düzeyinde silme `dashboards:write` altında yer alır). | -### Kaydedilmiş sorgular (SQL oluşturucu) +### Kaydedilen sorgular (SQL bestecisi) -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Kaydedilmiş sorguları listele, birini yükle ve oluşturucunun hedeflediği salt okunur şemayı incele. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | Kaydedilmiş sorguları oluştur ve düzenle. SQL hala aynı salt okunur rol üzerinden yönlendirilir ve `queries:run` çağrısı olarak korunan SQL kontrollerinden geçer. | -| `queries:delete` | `DELETE /queries/:id` | Kaydedilmiş sorguyu sil. | -| `queries:run` | `POST /queries/run` | Oluşturucu tarafından kullanılan salt okunur rolle karşı kaydedilmiş veya geçici SQL çalıştır. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Kaydedilen sorguları listeleyin, birini yükleyin ve bestecinin hedeflediği salt okunur şemayı inceleyin. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | Kaydedilen sorguları oluşturun ve düzenleyin. SQL, `queries:run` çağrısıyla aynı salt okunur rol üzerinden ve korumalı SQL denetimleriyle yönlendirilir. | +| `queries:delete` | `DELETE /queries/:id` | Kaydedilen sorguyu silin. | +| `queries:run` | `POST /queries/run` | Besteci tarafından kullanılan salt okunur rol üzerine kaydedilen veya ad hoc SQL'i yürütün. | -### Yapay zeka asistanı +### AI asistanı -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Yapay zeka asistanı ile konuş ve kendi (özel) sohbetlerini yönet. Asistan rıhtımını görmek için **kullanıcıya** gerekli; asistanın kendi anahtarı `dashboard-assistant` ve ayrı olarak başlatılır (aşağıya bakın). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | AI asistanıyla konuşun ve kendi (özel) konuşmalarınızı yönetin. Asistan dokunuşunu görmek için **kullanıcı** üzerinde gereklidir; asistanın kendi anahtarı `dashboard-assistant` ve ayrı olarak yapılır (aşağıya bakın). | -### API Anahtarları +### API anahtarları -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `keys:create` | `POST /keys` | Yeni kapsamlı API anahtarı oluştur. Mevcut bir anahtarın izinlerini düzenlemeyi **vermez** (bu `keys:update` dır). | -| `keys:read` | `GET /keys` | Mevcut anahtarları listele. Sırlar bu uç nokta tarafından asla döndürülmez. | -| `keys:update` | `PATCH /keys/:id` | Mevcut anahtarın izinlerini düzenle. **İnsan/kontrol paneli özeldir** izin; API anahtarına atanmaz (taşıyıcı anahtar anahtarlar oluşturabilir ama hiçbir zaman bunları düzenleyemez). | -| `keys:disable` | `POST /keys/:id/disable` | Anahtarı iptal et. Korunan anahtarlar (`admin`, `dashboard-assistant`) devre dışı bırakılamaz; ortam değişkeni + yeniden başlatma yoluyla döndürün. | -| `keys:regenerate` | `POST /keys/:id/regenerate` | Anahtarın sırrını döndür. Korunan anahtarlar bu rota üzerinden yeniden oluşturulamaz. | +| `keys:create` | `POST /keys` | Yeni kapsamlı bir API anahtarı oluşturun. Mevcut bir anahtarın izinlerini düzenleme izni **vermez** (bu `keys:update`). | +| `keys:read` | `GET /keys` | Mevcut anahtarları listeleyin. Sırlar bu uç noktadan asla döndürülmez. | +| `keys:update` | `PATCH /keys/:id` | Mevcut anahtarın izinlerini düzenleyin. Bir **insan/pano-yalnız** izin; bir API anahtarına atanması mümkün değildir (taşıyıcı anahtar anahtar oluşturabilir ancak asla bunları düzenleyemez). | +| `keys:disable` | `POST /keys/:id/disable` | Anahtarı iptal edin. Korumalı anahtarlar (`admin`, `dashboard-assistant`) devre dışı bırakılamaz; ortam değişkeni + yeniden başlatma aracılığıyla döndürün. | +| `keys:regenerate` | `POST /keys/:id/regenerate` | Anahtarın sırrını döndürün. Korumalı anahtarlar bu rota aracılığıyla yeniden oluşturulamaz. | -### Kontrol Paneli Kullanıcıları +### Pano kullanıcıları -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | Yeni kontrol paneli kullanıcısını davet et (e-posta + tek seferlik parola (OTP) girişi) ve daveti oluşturmayı oluşturmak için önceden seçilmiş kontrol paneli yapılandırma varsayılan izin setini oku. | -| `users:read` | `GET /users`, `GET /users/:id` | Kullanıcıları listele ve tek bir kullanıcı kaydını yükle. | -| `users:update` | `PUT /users/:id` | Kullanıcının izinlerini düzenle. Güncellemeler etkilenen kullanıcıya bir izin değişikliği e-postası gönderir ve bir sonraki isteklerinde yürürlüğe girer; yeniden oturum açma gerekli değildir. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Kullanıcıyı devre dışı bırak (oturumlarını hemen iptal et) ve önceden devre dışı bırakılan kullanıcıyı yeniden etkinleştir. | +| `users:create` | `POST /users`, `GET /users/defaults` | Yeni bir pano kullanıcısı davet edin (e-posta + tek seferlik şifre (OTP) girişi yayınlar) ve daveti form oluşturmayı başlatmak için kullanılan pano tarafından yapılandırılan varsayılan izin setini okuyun. | +| `users:read` | `GET /users`, `GET /users/:id` | Kullanıcıları listeleyin ve tek bir kullanıcı kaydını yükleyin. | +| `users:update` | `PUT /users/:id` | Kullanıcının izinlerini düzenleyin. Güncellemeler, etkilenen kullanıcıya izin değişikliği e-postası gönderir ve bir sonraki isteklerinde etkili olur; yeniden girişe gerek yoktur. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Bir kullanıcıyı devre dışı bırakın (oturumlarını hemen iptal edin) ve önceden devre dışı bırakılan bir kullanıcıyı yeniden etkinleştirin. | -Bu izinler kontrol panelinin **Kullanıcılar** sayfasını destekler; burada her üyenin verilen kapsamları yonga olarak gösterilir: +Bu izinler, her üyenin verilen kapsamlarının çipler olarak gösterildiği panodaki **Kullanıcılar** sayfasını destekler: -![Kullanıcılar sayfası: kontrol paneli kullanıcısı başına kart, e-posta, verilen izinler ve düzenle/devre dışı bırak kontrolleriyle](/agenteye/images/users.png) +![Kullanıcılar sayfası: her pano kullanıcısı için e-postası, verilen izinleri ve düzenle/devre dışı bırak kontrolleriyle bir kart](/agenteye/images/users.png) ### İşletimsel ayarlar -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Kontrol paneli tarafından yönetilen işletimsel ayarları ve meta verilerini görüntüle; model başına bağlam penceresi geçersiz kılmalarını listele; ve bir model için etkili pencereyi çöz. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | İşletimsel ayarları düzenle ve model başına bağlam penceresi geçersiz kılmalarını ekle, değiştir veya kaldır. Değişiklikler sunucuyu yeniden başlatmadan yeni olayları etkiler. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Pano tarafından yönetilen işletimsel ayarları ve bunların meta verilerini görüntüleyin; model başına bağlam penceresi geçersiz kılmalarını listeleyin; ve bir model için etkili pencereyi çözümleyin. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | İşletimsel ayarları düzenleyin ve model başına bağlam penceresi geçersiz kılmalarını ekleyin, değiştirin veya kaldırın. Değişiklikler sunucuyu yeniden başlatmadan yeni olayları etkiler. | -![Ayarlar sayfası: sunucuyu yeniden başlatmadan düzenlenebilen izin verilen oturum açmalar ve oturum/OTP yaşam süreleri gibi kontrol paneli tarafından yönetilen işletimsel ayarlar](/agenteye/images/settings.png) +![Ayarlar sayfası: izin verilen oturum açma işlemleri ve oturum/OTP yaşam süreleri gibi pano tarafından yönetilen işletimsel ayarlar, yeniden başlatma olmadan düzenlenebilir](/agenteye/images/settings.png) ### Uyarılar ve olaylar -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Yapılandırılan uyarı tanımlarını görüntüle. | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Uyarı tanımlarını oluştur, düzenle, sil ve test-ateş. | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Olayları ve bunların sınıflandırma izini görüntüle. | -| `incidents:write` | `POST /alerts/:id/incidents` | Mevcut bir uyarıya karşı el ile bir olay aç. | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Olayları onaylamak, atamak, çözmek ve yorum yapmak. | +| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Yapılandırılan uyarı tanımlarını görüntüleyin. | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Uyarı tanımlarını oluşturun, düzenleyin, silin ve test gönderin. | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Olayları ve bunların önceliklendirme izini görüntüleyin. | +| `incidents:write` | `POST /alerts/:id/incidents` | Mevcut bir uyarıya karşı manuel olarak bir olay açın. | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Olayları onaylayın, atayın, çözümleyin ve yorum yapın. | ### Denetimler -| İzin | HTTP Rotaları | İzin verdiği şey | +| İzin | HTTP rotaları | Ne izin verir | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Denetim tanımlarını, çalıştırma geçmişini ve bulguları görüntüle. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Denetimler oluştur, düzenle, sil ve çalıştır; bulguları sınıflandır (kabul et / sustur / yoksay / çöz / yeniden aç / ata). | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Denetim tanımlarını, çalıştırma geçmişini ve bulguları görüntüleyin. | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Denetim tanımlarını oluşturun, düzenleyin, silin ve çalıştırın; bulguları önceliklendirin (onayla / sustur / reddet / çöz / yeniden aç / ata). | -> **Not:** Bir anahtara denetim yüzeyini vermek için `audits:*` açıkça veriniz. Denetimler yayınlandığında mevcut izin alanlarının nasıl taşındığını görmek için [Yükseltme ve geriye dönük uyumluluk notları](#yükseltme-ve-geriye-dönük-uyumluluk-notları) bölümüne bakın. +> **Not:** Bir anahtara denetim yüzeyini vermek için `audits:*` açıkça verin. Denetimler gönderildiğinde mevcut imtiyaz sahiplerinin nasıl geçirildiğini öğrenmek için [Yükseltme ve geriye dönük uyumluluğu notları](#yükseltme-ve-geriye-dönük-uyumluluğu-notları) bölümüne bakın. -> Alıcı seçici uç noktası `GET /alerts/recipients` (uyarı editörünün bildirilebileceği üye e-postalarını listeler) **ya da** `alerts:read` **ya da** `alerts:write` sahibi tarafından erişilebilir, bu nedenle uyarı editörleri `users:read` verilmeden seçiciyi doldurabiliyor. +> Alıcı-seçici uç noktası `GET /alerts/recipients` (bir uyarı editörünün bildirebileceği üye e-postalarını listeler), **ya** `alerts:read` **ya da** `alerts:write` tutucusu tarafından erişilebilir, böylece uyarı editörleri seçiciyi `users:read` verilmeden doldurabilir. -> Pano görüntüleyicisi **hem de** `dashboards:read` (kaydedilmiş görünümleri yüklemek için) hem de `evaluations:read` gerekli (sağlık metrikleri değerlendirme verilerinden hesaplanır). Bir kullanıcıya pano oluşturmaya veya düzenlemesine izin vermek için `dashboards:write` verin ve bunları kaldırmak için `dashboards:delete` verin. +> Pano görüntüleyicisi, kaydedilen görünümleri yüklemek için **hem** `dashboards:read` (hem de sağlık metrikleri değerlendirme verilerinden hesaplanır `evaluations:read`). Kullanıcının panoları oluşturması veya düzenlemesi için `dashboards:write` verin ve onları kaldırmak için `dashboards:delete` verin. -> `/health` ve `/auth/*` (OTP isteği, OTP doğrula, oturum kontrol, çıkış) tasarım gereği kimlik doğrulamadan uzak; bunlar oturum açma akışı ve canlılık koşuşturmacasıdır. `GET /access-granters` geçerli bir anahtar gerektirir ama belirli izin yok, bu nedenle oturum açmış herhangi bir kullanıcı erişim değişiklikleri hakkında hangi yöneticilere başvurması gerektiğini görebilir. +> `/health` ve `/auth/*` (OTP isteği, OTP doğrula, oturum kontrol et, oturumu kapat) tasarım gereği kimliği doğrulanmamıştır; bunlar oturum açma akışı ve canlılık sondası. `GET /access-granters` geçerli bir anahtar gerektirir ancak özel izin yoktur, bu nedenle oturum açan herhangi bir kullanıcı hangi yöneticileriyle erişim değişiklikleri hakkında iletişim kuracağını görebilir. --- ## İzin Setleri -İzin setleri her seferinde bireysel jetonları el ile seçmek yerine adlandırılmış bir rol uygulamanıza izin verir. Her yeni kontrol paneli kullanıcısı veya API anahtarı için bir düzine izni tek tek seçmek yerine, bir set seçersiniz ve herkese atanan set tutarlı, gözden geçirilebilir bir hibe taşır. Özel bir set düzenlemek zaten buna atanan her kullanıcıya yeni hibe yeniden uygular, bu nedenle bir rol değişikliği her üyeyi taramak yerine bir düzenleme olur. +İzin setleri, her defasında bireysel belirteçleri el ile seçmek yerine adlandırılmış bir rol uygulamanıza izin verir. Her yeni pano kullanıcısı veya API anahtarı için düzinelerce izni birer birer seçmek yerine, bir set seçersiniz ve herkese atanan bir dizi tutarlı, gözden geçirilebilir hibe taşır. Özel bir set'i düzenleme, zaten atanan her kullanıcıya yeni hibeyi yeniden uygular, böylece bir rol değişikliği her üye arasında süpürme yerine tek bir düzenlemedir. -Her kuruluş üç yerleşik sette başlatılır: +Her kuruluş üç yerleşik set ile yapılır: -| Set | İzinler | Amaçlanan | +| Set | İzinler | Yönelik | |---|---|---| -| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Her operasyonel yüzey genelinde salt görüntüleme erişimi. | -| `standard` | `read-only` içindeki her şey, artı `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Salt okunur, artı günlük ara vardiyası eylemleri: sorguları çalıştır, oturumları yeniden değerlendir, olayları kabul et ve yapay zeka asistanını kullan. | -| `admin` | atanabilir her izin | Org üzerinde tam kontrol. | +| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Her işletimsel yüzey üzerinde salt görüntüleme erişimi. | +| `standard` | `read-only` içindeki her şey artı `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Salt okunur artı günlük çağrı üzerine eylemler: sorguları çalıştırın, oturumları yeniden değerlendirin, olayları onaylayın ve AI asistanı kullanın. | +| `admin` | atanabilir her izin | Kuruluşun tam kontrolü. | -Üç yerleşik set **değişmez**; adları her zaman aynı şeyi anlamlandırır, bu nedenle `read-only`, `standard` ve `admin` ilke ve getirişte referans vermek güvenlidir. Bir operatör kuruluşunuza özel rolleri modellemek için ek **özel setler** oluşturabilir (örneğin, bir "pano yazarı" rolü veya "toplayıcı-yalnızca" rolü). +Üç yerleşik set **değişmez**; bunların adları her zaman aynı şeyi anlamına gelir, bu nedenle `read-only`, `standard` ve `admin` politika ve ön yüklemede başvuruda bulunması güvenlidir. Bir operatör, kuruluşunuza özgü roller modellemek için ek **özel setler** oluşturabilir (örneğin, bir pano yazar rolü veya bir toplayıcı-yalnız rolü). -Setler kontrol panelinde yüzeylendirilir ve `GET /permission-sets` (liste, `users:read` tarafından gated) ve `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (özel bir seti oluştur, düzenle, sil, `settings:write` tarafından gated) üzerinde API'de yönetilir. Yerleşik bir seti silmek veya düzenlemek reddedilir. +Setler pano tarafından sunulur ve `GET /permission-sets` (`users:read` tarafından kilitlenmiş, listele) ve `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (özel set oluştur, düzenle, sil, `settings:write` tarafından kilitlenmiş) API'de yönetilir. Yerleşik bir set'i silme veya düzenleme reddedilir. -Set üyeliği iki diğer özelliği destekler: +Set üyeliği iki diğer özelliği yedekler: -- **`DEFAULT_USER_PERMISSIONS`** (yönetici **+ yeni kullanıcı** açtığında önceden seçilen hibe) `standard` setine varsayılan olarak ayarlanır. -- **`agenteye-orgctl` üzerinde `--set` bayrağı** (operatör üyesi yönetimi) bir üyeyi adlandırılmış bir setten başlatır; bunu daha sonra `--add` / `--remove` ile ince ayar yaparsınız. +- **`DEFAULT_USER_PERMISSIONS`** (yönetici **+ yeni kullanıcı** açtığında önceden seçilen hibe) `standard` set'in varsayılanları. +- **`agenteye-orgctl` üzerindeki `--set` bayrağı** (operatör üye yönetimi) bir üyeyi adlandırılmış bir set'ten başlatır, ardından `--add` / `--remove` ile ince ayar yaparsınız. -> **Not:** Bir set anahtar atanabilir olmayan bir izni içerdiğinde (örneğin `keys:update` taşıyan özel bir set), bu setten bir anahtar tohumlamak atanabilir olmayan jetonları bırakır; sunucu aksi takdirde anahtarı HTTP 422 ile reddederdi. Kontrol paneli kullanıcıları bu kısıtlamaya tabi değildir. +> **Not:** Bir set, anahtar atanabilir olmayan bir izin içeriyorsa (örneğin `keys:update` taşıyan özel bir set), bu set'ten bir anahtar tohumu atanabilir olmayan belirteçleri düşürür; sunucu aksi takdirde anahtarı HTTP 422 ile reddeder. Pano kullanıcıları o kısıtlamaya tabi değildir. --- ## Önyükleme Yönetici Anahtarı -Yönetici anahtarı, bir operatörün hiçbir şeyden erişimi getirmesine izin veren tek kök kimlik bilgileridir: bununla, diğer her kapsamlı anahtar oluşturabilir, ilk kontrol paneli kullanıcılarını davet edebilir ve başka hiçbir anahtar bulunmadığında örneği yapılandırabilirsiniz. Anahtarlar API'si aracılığıyla oluşturulmadığınız tek anahtarıdır; ilk önyüklemede sunucuya ulaşılabilir olması için ortamdan sağlanır. +Yönetici anahtarı, bir operatörün hiçlikten erişimi getirmesine izin veren tek kök kimlik bilgisidir: bununla diğer kapsamlı anahtarları basabilir, ilk pano kullanıcılarını davet edebilir ve başka hiçbir anahtar var olmadan örneği yapılandırabilirsiniz. Bu, anahtarlar API'si aracılığıyla oluşturmadığınız tek anahtardır; sunucu ilk önyüklemede erişilebilir olması için ortamdan sağlanır. -Sunucuda `ADMIN_KEY` ortam değişkenini ayarlayın. Her başlatmada sunucu bu değeri tüm izinlere sahip bir yönetici anahtarı olarak upserts. +Sunucuda `ADMIN_KEY` ortam değişkenini ayarlayın. Her başlangıçta sunucu bu değeri tüm izinleri taşıyan yönetici anahtarı olarak günceller veya oluşturur. -Döndürmek için: `ADMIN_KEY` olarak yeni bir sıra değiştirin ve sunucuyu yeniden başlatın. +Döndürmek için: `ADMIN_KEY` öğesini yeni bir sırra değiştirin ve sunucuyu yeniden başlatın. --- -## Organizasyon Kapsamı +## Kuruluş kapsamı -**Kuruluşlar kendileri operatör tarafından banda dışı oluşturulur ve yönetilir, bu anahtarlar API'si aracılığıyla değil.** Org ve üye yaşam döngüsü (kuruluş oluştur / yeniden adlandır / sil / temizle; üye ekle / güncelle / kaldır) **`agenteye-orgctl`** CLI ile yapılır; bunun için HTTP API veya kontrol paneli düğmesi yoktur. Değişmeyen şey budur: **org başına API anahtarları hala kontrol panelinde (veya bu anahtarlar API'si aracılığıyla)** org üyeleri tarafından oluşturulur. +**Kuruluşlar kendileri operatör tarafından sıra dışında oluşturulur ve yönetilir, bu anahtarlar API'si aracılığıyla değil.** Kuruluş ve üye yaşam döngüsü (kuruluş oluştur / yeniden adlandır / sil / temizle; üye ekle / güncelleştir / kaldır) **`agenteye-orgctl`** CLI'si ile yapılır; bunun için HTTP API veya pano düğmesi yoktur. Değişmeyen *şey*: **kuruluş başına API anahtarları hala pano tarafından (veya bu anahtarlar API'si aracılığıyla) kuruluş üyeleri tarafından basılır**. -Çok org dağıtımında, org üyesinin oluşturduğu her anahtar (bu anahtarlar API'si veya kontrol paneli **Anahtarlar** sayfası aracılığıyla) **tek bir kuruluşa** aittir ve yalnızca o org'un verilerine okuyabilir veya yazabilir; org oluşturma sırasında anahtara damgalanır ve her istekte uygulanır. İki önyükleme anahtarı tek istisnadır: `admin` anahtarı (`ADMIN_KEY` başlatılır) ve `dashboard-assistant` anahtarı (`AGENT_API_KEY` başlatılır) **örnek kapsamlıdır** (org taşımaz). Kontrol paneli `admin` anahtarıyla kimlik doğrulaması yapar, bu nedenle oturum açmış üyeler adına kuruluş başına istekleri vekil edebilir. Tek kiracılı dağıtımlar bunun hakkında düşünmeye gerek duymaz; tüm anahtarlar yerleşik `default` org'a aittir. +Çok kuruluşlu bir dağıtımda, bir kuruluş üyesinin oluşturduğu her anahtar (bu anahtarlar API'si veya pano **Anahtarlar** sayfası aracılığıyla) **bir kuruluşa** aittir ve yalnızca o kuruluşun verilerini okuyabilir veya yazabilir; kuruluş anahtarda oluşturmada damgalanır ve her istekte uygulanır. İki önyükleme anahtarı tek istisnaa: `admin` anahtarı (`ADMIN_KEY` öğesinden yapılır) ve `dashboard-assistant` anahtarı (`AGENT_API_KEY` öğesinden yapılır) **örnek kapsamlı** (kuruluş taşımaz). Pano, imzalı üyeleri adına kuruluş başına istekleri temsil edebilmesi için `admin` anahtarıyla doğrular. Tek kiracılı dağıtımlar bunu düşünmek zorunda değildir; tüm anahtarlar yerleşik `default` kuruluşa aittir. --- ## Anahtar Oluşturma -Ek kapsamlı anahtarlar oluşturmak için yönetici anahtarını (veya `keys:create` izni olan herhangi bir anahtarı) kullanın. +Ek kapsamlı anahtarlar oluşturmak için yönetici anahtarını (veya `keys:create` izni olan başka bir anahtarı) kullanın. -### Toplayıcı anahtarı (yalnızca yutma) +### Toplayıcı anahtarı (yalnızca alımı) ```bash curl -s -X POST http://your-server/keys \ @@ -179,7 +179,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### Kontrol paneli anahtarı (salt okunur) +### Pano anahtarı (salt okunur) ```bash curl -s -X POST http://your-server/keys \ @@ -192,7 +192,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -HTTP API'nin üzerinden bir anahtar oluşturduğunuzda, `key` değerini kendiniz sağlarsınız; güçlü bir sıra seçin ve bunu güvenle saklayın. (Kontrol paneli başka şekilde çalışır: sizin için güçlü bir sıra oluşturur ve oluşturmada bir kez gösterir; bkz. [Kontrol Panelinde Anahtar Yönetimi](#kontrol-panelinde-anahtar-yönetimi).) Yanıt anahtarın oluşturulduğunu onaylar: +HTTP API'si üzerinde bir anahtar oluşturduğunuzda `key` değerini kendiniz sağlarsınız; güçlü bir sır seçin ve güvenli bir şekilde saklayın. (Pano başka şekilde çalışır: sizin için güçlü bir sır oluşturur ve oluşturmada bir kez gösterir; bkz. [Panodaki anahtar yönetimi](#panodaki-anahtar-yönetimi).) Yanıt, anahtarın oluşturulduğunu doğrular: ```json { @@ -218,7 +218,7 @@ Anahtar sırları liste yanıtlarında döndürülmez, yalnızca kimlikler, adla ## Anahtarı Devre Dışı Bırakma -Devre dışı bırakmak anahtar kaydını silmeden erişimi hemen iptal eder. +Devre dışı bırakma, anahtar kaydını silmeden erişimi hemen iptal eder. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -229,24 +229,24 @@ curl -s -X POST http://your-server/keys//disable \ ## Anahtarı Yeniden Oluşturma -Mevcut bir anahtar için yeni bir sıra oluşturur. Eski sıra hemen geçersiz kılınır. +Mevcut bir anahtar için yeni bir sır oluşturur. Eski sır hemen geçersiz kılınır. ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -Yanıt yeni düz metinlik sırrı içerir, **yalnızca bir kez gösterilir**. +Yanıt yeni düz metin sırrı içerir, **yalnızca bir kez gösterilen**. --- -## Kontrol Panelinde Anahtar Yönetimi +## Panodaki Anahtar Yönetimi -Kontrol panelindeki **Anahtarlar** sayfası yukarıdaki tüm işlemler için bir kullanıcı arayüzü sağlar. Listeyi görüntülemek için `keys:read` izni olan bir anahtara ihtiyacınız vardır ve oluşturma / düzenle / devre dışı bırak / yeniden oluşturma eylemleri sırasıyla `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` gerekir. Bir anahtarın izinlerini düzenlemek (`keys:update`) bir tane oluşturmaktan (`keys:create`) ayrıdır, bu nedenle bir operatöre anahtarları bastırma yeteneğini mevcut olanları yeniden kapsamlandırma yeteneği olmadan veya tam tersi verebilirsiniz. Yönetici anahtarı bunların hepsini kapsar. +Pano içindeki **Anahtarlar** sayfası, yukarıdaki tüm işlemler için bir UI sağlar. Listeyi görüntülemek için `keys:read` izni olan bir anahtara ve oluştur / düzenle / devre dışı bırak / yeniden oluştur eylemlerine karşılık sırasıyla `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` gerekir. Bir anahtarın izinlerini düzenleme (`keys:update`) oluşturmaktan ayrıdır (`keys:create`), bu nedenle mevcut anahtarları yeniden kapsamlandırma özelliği olmadan anahtar basabilecek bir operatöre izin verebilir veya tam tersi. Yönetici anahtarı bunların hepsini kapsar. -Kontrol panelinden bir anahtar oluşturduğunuzda sırrı sağlamıyorsunuz; kontrol paneli sizin için güçlü bir sıra oluşturur ve oluşturmada **bir kez** görüntüler. Hemen kopyalayın ve güvenle saklayın; yeniden oluşturma gibi asla tekrar gösterilmez. Yine de anahtarın izinlerini doğrudan seçebilir veya bir izin setinden tohumlayabilirsiniz (aşağıya bakın). +Panodan bir anahtar oluşturduğunuzda sırrı sağlamazsınız; pano sizin için güçlü bir sır oluşturur ve oluşturmada **bir kez** görüntüler. Hemen kopyalayın ve güvenli bir şekilde saklayın; yeniden oluşturma ile tam olarak bir daha asla gösterilmez. Yine de anahtarın izinlerini doğrudan seçebilir veya bir izin set'inden tohum atabilirsiniz (aşağıya bakın). -![API Anahtarları sayfası: anahtar başına kart, adını, verilen izinleri ve oluşturma zamanını gösterir, yeniden oluştur ve devre dışı bırak eylemleriyle; `admin` gibi korunan anahtarlar işaretlenir](/agenteye/images/api-keys.png) +![API Anahtarları sayfası: her anahtar için adı, verilen izinleri ve oluşturma zamanını gösteren kart, yeniden oluştur ve devre dışı bırak eylemleri; `admin` gibi korumalı anahtarlar işaretlenir](/agenteye/images/api-keys.png) --- @@ -254,26 +254,26 @@ Kontrol panelinden bir anahtar oluşturduğunuzda sırrı sağlamıyorsunuz; kon | Anahtar | İzinler | Kullanan | |---|---|---| -| `admin` (ortam değişkeni `ADMIN_KEY` aracılığıyla önyükleme) | tümü | Ops/kurulum ve kontrol paneli (kimlik doğrulama `ADMIN_KEY` ile, kullanıcı isteklerini izin kontrolleriyle vekil eder) | -| Ana bilgisayar başına toplayıcı anahtarı | `events:add` | Her ajan makinesinde toplayıcı | -| `dashboard-assistant` (ortam değişkeni `AGENT_API_KEY` aracılığıyla önyükleme) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Yapay zeka asistanı, otomatik olarak başlatıldı, **korunan**; API aracılığıyla düzenlenemez | -| Asistan telemetrisi anahtarı (isteğe bağlı) | `events:add` | Yapay zeka asistanı öz enstrümantasyonu, etkinleştirilmişse | +| `admin` (`ADMIN_KEY` ortam değişkeni aracılığıyla önyükleme) | tümü | Ops/kurulum ve pano (`ADMIN_KEY` ile doğrular, izin denetimleriyle kullanıcı isteklerini temsil eder) | +| Konak başına toplayıcı anahtarı | `events:add` | Her ajan makinesindeki toplayıcı | +| `dashboard-assistant` (`AGENT_API_KEY` ortam değişkeni aracılığıyla önyükleme) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI asistanı, otomatik olarak yapılır, **korumalı**; API aracılığıyla düzenlenemiyor | +| Asistan telemetrisi anahtarı (isteğe bağlı) | `events:add` | AI asistanı kendi-araçlandırma, etkinse | -> **Not:** Asistanın anahtarı sunucu tarafından `AGENT_API_KEY` ortam değişkeninden **otomatik olarak başlatılır** (ajanın `AGENTEYE_API_KEY` olarak sunduğu aynı sıra); el ile anahtar damgalanma adımı yoktur ve hiçbir yönetici anahtarı söz konusu değildir. İzinleri kaynak kodda sabitlenmiş, böylece kapsam yanlış yapılandırma tarafından genişletilemez: olaylar / değerlendirmeler / panoları genelinde oku, artı panoları-yaz ve sorguları-oku / yaz / çalıştır "Yapay zekaya sorgu yazması isteme" yazarlık akışı için. Tüm SQL hala kullanıcı tarafından yazılan bir sorgu olarak aynı salt okunur rol ve korunan SQL yolu üzerinden gider, bu nedenle bu *yazarlık yüzeyini* genişletir, veri yüzeyini değil; yıkıcı işlemler (`queries:delete`, `dashboards:delete`) kasıtlı olarak asistan anahtarının dışında kalır. `admin` anahtarı gibi, **korunan**: anahtarlar API'si aracılığıyla devre dışı bırakılamaz veya yeniden oluşturulamaz, yalnızca `AGENT_API_KEY` değiştirerek ve yeniden başlatarak döndürülür. Kontrol paneli *kullanıcıları* ek olarak asistanı görmek ve kullanmak için `agent:use` izni gerektirir. Öz enstrümantasyonu etkinleştirirseniz, asistana ayrı bir `events:add`-yalnızca anahtarı verin. +> **Not:** Asistanın anahtarı **otomatik olarak `AGENT_API_KEY` ortam değişkeninden sunucu tarafından yapılır** (ajanın `AGENTEYE_API_KEY` olarak sunduğu aynı sır); el ile anahtar basının adımı yoktur ve yönetici anahtarı söz konusu değildir. Bunun izinleri kaynak kodda sabittir, bu nedenle kapsam yanlış yapılandırma tarafından genişletilemiyor: olaylar / değerlendirmeler / panolar arasında okuma, artı dashboards-write ve sorguları-okuma / yazma / çalıştırma AI yazma akışı için sorgu yazması için. Tüm SQL hala kullanıcı tarafından yazılan sorgu olarak aynı salt okunur rol ve korumalı SQL yolu üzerinden gider, bu nedenle bu veri yüzeyinin değil *yazma yüzeyini* genişletir; yıkıcı işlemler (`queries:delete`, `dashboards:delete`) kasıtlı olarak asistan anahtarının dışında kalır. `admin` anahtarı gibi, **korumalur**: anahtarlar API'si aracılığıyla devre dışı bırakılamaz veya yeniden oluşturulamaz, yalnızca `AGENT_API_KEY` değiştirerek ve yeniden başlatarak döndürülür. Pano *kullanıcıları* ek olarak asistanı görmek ve kullanmak için `agent:use` izni gerektirir. Kendi-araçlandırmayı etkinleştirirseniz, asistana ayrı `events:add`-yalnız anahtar verin. --- -## Yükseltme ve geriye dönük uyumluluk notları +## Yükseltme ve geriye dönük uyumluluğu notları -Yalnızca mevcut bir örneği yükseltiyorsanız bunlara ihtiyacınız vardır; yeni dağıtımlar bunları atlayabilir. +Varolan bir örneği yükseltiyorsanız, bunlara yalnızca gereksinim duyarsınız; yeni dağıtımlar bunları atlayabilir. -> Denetimler yayınlandığında, mevcut izin alanları uyarılar olarak aynı rol şekilleriyle genişletildi: `alerts:read` tutan her kullanıcı ve izin seti `audits:read` kazandı ve `alerts:write` sahibi `audits:write` kazandı. Mevcut API anahtarları **genişletilmedi**. Denetim yüzeyine ihtiyacı olan bir anahtara `audits:*` açıkça verin. +> Denetimler gönderildiğinde, mevcut imtiyaz sahipleri uyarılarla aynı rol şekillerine göre genişletildi: `alerts:read` tutan her kullanıcı ve izin seti `audits:read` kazandı ve `alerts:write` tutucusu `audits:write` kazandı. Mevcut API anahtarları **genişletilmedi**. Denetim yüzeyine ihtiyaç duyuyorsa, bir anahtara `audits:*` açıkça verin. -> Eski `alerts:ack` jetonunun depolanan hibeleri `incidents:ack` olarak ayrıştırılır, bu nedenle araçlar erişimi anahtarlamadan saklar. Jetons daha fazla kontrol paneli kullanıcı editöründen atanabilir değildir; matris bunun yerine `incidents:ack` sunar. +> Eski `alerts:ack` belirtecinin depolanmış hibesi, çağrı üzerine operatörleri yeniden kutuya gerek olmadan erişimi koruyacak şekilde `incidents:ack` olarak ayrıştırılır. Belirteç artık pano kullanıcı editöründen atanabilir değildir; matris bunun yerine `incidents:ack` sunar. --- -## Sonraki Adımlar +## Sonraki adımlar -- [Python SDK](/tr/agenteye/python-sdk): ajan kodunuz olayları gönderirken nasıl kimlik doğrulaması yapar. -- [Güvenlik](/tr/agenteye/security): oturum açma, erişim denetimi ve kuruluş başına veri yalıtması nasıl çalışır. \ No newline at end of file +- [Python SDK](/tr/agenteye/python-sdk): ajan kodunuz olayları gönderirken nasıl doğrular. +- [Güvenlik](/tr/agenteye/security): oturum açma, erişim denetimi ve kuruluş başına veri yalıtımı nasıl çalışır. \ No newline at end of file diff --git a/docs/tr/agenteye/assistant.mdx b/docs/tr/agenteye/assistant.mdx index 10fac333..84332664 100644 --- a/docs/tr/agenteye/assistant.mdx +++ b/docs/tr/agenteye/assistant.mdx @@ -1,63 +1,64 @@ --- title: "AI Asistanı" -description: "Aracı verilerinize düz İngilizce ile bir soru sorun ve kanıtlara doğrudan bağlanan bir yanıt alın." +description: "Aracı verilerinize düz İngilizcede bir soru sorun ve doğrudan kanıtlara bağlanan bir yanıt alın." --- -Aracı verilerinize düz İngilizce ile bir soru sorun ve kanıtlara doğrudan bağlanan bir yanıt alın. SQL yazmaya gerek yok, panoları araştırmaya gerek yok — **Failproof AI Observability** asistanı, ekibinizdeki herkesin aracılarınız hakkında cevap almasının en hızlı yoludur. +Aracı verilerinize düz İngilizcede bir soru sorun ve doğrudan kanıtlara bağlanan bir yanıt alın. SQL yazmanıza gerek yok, panolara bakmanıza gerek yok — **Failproof AI Gözlemlenebilirlik** asistanı, ekibinizin herhangi birinin aracılarınız hakkında yanıt almasının en hızlı yoludur. -![Failproof AI Observability asistanı, paneldeki düz İngilizce soruyu yanıtlarken, canlı Agent Activity tablosu, agent başına model kullanım dökümü ve yazılı çıkarımları gösteriyor, çalıştırdığı sorgular satır içinde gösterilmektedir](/agenteye/images/assistant.png) -*Düz İngilizce sorun ve kendi verilerinizden oluşturulmuş bir yanıt alın. Burada hangi aracıların en meşgul olduğunu, hangi modelleri kullandıklarını analiz ediyor ve çalıştırdığı sorguları göstererek her sayıyı doğrulayabilmenizi sağlıyor.* +![Failproof AI Gözlemlenebilirlik asistanı, pano içinde düz İngilizcede sorulan bir soruya yanıt veriyor, canlı Ajan Aktivitesi tablosu, ajan başına model kullanımı dökümü ve yazılı çıkarımları gösteriyor, çalıştırdığı sorgular satır içinde gösteriliyor](/agenteye/images/assistant.png) +*Düz İngilizcede sorun ve kendi verilerinizden oluşturulmuş bir yanıt alın. Burada hangi aracıların en meşgul olduğunu, hangi modelleri kullandıklarını açıklıyor ve çalıştırdığı sorguları gösteriyor, böylece her sayıyı doğrulayabilirsiniz.* -Öğrenecek bir şey yok. Sohbeti açın, bilmek istediğinizi yazın ve geri aldığı bağlantıları takip edin: +Öğrenecek bir şey yok. Sohbeti açın, ne bilmek istediğinizi yazın ve geri aldığı bağlantıları takip edin: ``` -You: which sessions errored today? -AI: 5 sessions errored today, newest first. Each one is linked: - • checkout-agent 14:02 tool timeout - • billing-agent 11:47 unhandled error - • ...and 3 more - -You: summarize this session (asked while viewing a run) -AI: This run took 12 steps across 3 tools and failed near the end when a - payment tool returned an error. It scored low on your "resolved" eval. - Links: the session, the failing event, and that evaluation. +Siz: hangi oturumlar bugün hata verdi? +Asistan: Bugün 5 oturum hata verdi, en yeniden başlayarak. Her biri bağlantılı: + • checkout-agent 14:02 tool timeout + • billing-agent 11:47 unhandled error + • ...ve 3 tane daha + +Siz: bu oturumu özetle (bir çalıştırma görüntülenirken soruldu) +Asistan: Bu çalıştırma 3 araç üzerinde 12 adımdan geçti ve bir ödeme aracı + hata döndürdüğünde sonda başarısız oldu. İçindeki "resolved" + değerlendirmesinde düşük puan aldı. Bağlantılar: oturum, hatalı + olay ve bu değerlendirme. ``` -## Sadece sorun ve kanıta doğrudan geçin +## Sadece sorun ve doğrudan kanıta gidin -Tahminde bulunmayı bırakırsınız ve sorgu yazmayı bırakırsınız. "Bu haftada prod'da kalite nasıl eğiliyor?", "Bugün hangi oturumlar hata verdi?" veya "Bu oturumu özetle" gibi sorular sorun ve sorgu oluşturmak ve kendiniz okumak yerine saniyeler içinde doğrudan bir yanıt alın. +Tahmin etmeyi bırakırsınız ve sorgu yazmayı bırakırsınız. "Kalite bu hafta prod'de nasıl gidiyor?", "hangi oturumlar bugün hata verdi?" veya "bu oturumu özetle" sorusu sorun ve sorgu oluşturmak ve kendiniz okumak yerine saniyeler içinde doğru bir yanıt alın. -Her yanıt ispatları ile birlikte gelir. Asistan, yanıta ulaşmak için kullandığı tam oturumları, kaydedilmiş sorguları ve panoları bağlar, böylece söylenenlere inanmak yerine tıklayarak doğrulayabilirsiniz. Ayrıca **sayfaya duyarlıdır**: bir oturumu görüntülerken "bu oturum" hakkında sorun ve hangi çalıştırmayı kastettiğinizi zaten bilir. Geçmiş değiştirici menüsünden daha önceki herhangi bir konuşmayı yeniden açın ve kaldığınız yerden devam edin. +Her yanıt gerekçesiyle gelir. Asistan, yanıta ulaşmak için kullandığı tam oturumları, kaydedilmiş sorguları ve panoları bağlar, böylece sözüne inanmak yerine tıklayıp doğrulayabilirsiniz. Aynı zamanda **sayfa farkındadır**: bir oturum görüntülenirken "bu oturum" hakkında sorun sorun, hangi çalıştırmadan bahsettiğinizi zaten bilir. Geçmiş değiştiriciden daha sonra önceki herhangi bir konuşmayı yeniden açın ve kaldığınız yerden devam edin. -## İyi bir cevabı kaydedilmiş bir sorguya veya panoya dönüştürün +## İyi bir yanıtı kaydedilmiş bir sorguya veya panoya dönüştürün -Bir yanıt tutmaya değer olduğunda, asistanı kaydetmesi için isteyin. SQL'i kaydedilmiş bir sorgu için tasarlar veya bu sorgulardan bir pano oluşturur, ardından size bir **Onayla / Reddet** kartı gösterir. Onay'ı tıklayana kadar hiçbir şey yazılmaz, böylece "sadece sor" hızını elde edersiniz ve son söz her zaman sizindir. +Bir yanıt saklayacak değerdeyse, asistandan onu kaydetmesini isteyin. Kaydedilmiş bir sorgu için SQL tasarlar veya bu sorgulardan bir pano oluşturur, ardından **Onayla / Reddet** kartını gösterir. Siz Onayla'yı tıklayana kadar hiçbir şey yazılmaz, böylece "sadece sor"un hızını son söz her zaman sizin olan şekilde alırsınız. -**Sorgular** sayfasında bir adım daha ileri gider ve bir SQL yazarı olur: istediğiniz sorguyu açıklayın ("Son 7 gün için agent başına hata oranını göster") ve SQL'i doğrudan editöre aktarır, değişiklikleri kabul etmeden veya reddetmeden önce görebilmeniz için bir diff görünümü açar. +**Sorgular** sayfasında daha ileri gider ve bir SQL yazarı olur: istediğiniz sorguyu tanımlayın ("son 7 gün için ajan başına hata oranını göster") ve asistan SQL'i doğrudan editöre akıtır, değişiklik değişiklik yer almadan önce **Kabul Et** veya **Reddet** yaptığınız bir diff görünümü açar. -![Observability Sorgular sayfası ve SQL editörü](/agenteye/images/query-lab.png) -*Sorgular sayfası: bu editör, asistanın draft, salt okunur sorgu aktardığı yerdir ve siz kabul veya reddedebilirsiniz.* +![Gözlemlenebilirlik Sorgular sayfası ve SQL editörü](/agenteye/images/query-lab.png) +*Sorgular sayfası: bu editör, asistanın kabul edilebilir sadece okunan bir sorgu taslağını aktığı yerdir.* -Burada SQL yazılı olarak yazılması `queries:run` iznini kullanır, editörün **Çalıştır** düğmesinin arkasındakiyle aynıdır. Başka yerlerde sohbet `agent:use` gerektirir. +Burada SQL yazma işlemi `queries:run` izni kullanır, editörün **Çalıştır** düğmesinin arkasında aynı izin. Başka yerlerde sohbet, `agent:use` gerektirir. -## Tüm takıma vermek için güvenli +## Tüm ekibe güvenli şekilde devredilebilir -Asistanı neyle temas edebileceğinden endişe etmeden herkese açabilirsiniz: +Asistanı ne ile karşılaşabileceğini endişelenmeden herkese açabilirsiniz: -- **Sadece zaten görebildiğiniz şeyi okur.** Yanıtlar kendi okuma izinlerinize kapsanır, böylece hiç veri yüzeyinizi genişletmez. -- **Her yazı sizin onayınızı bekler.** Kaydedilmiş sorgular ve panolar yalnızca açık Onayla tıklama işleminden sonra oluşturulur ve bunu kapatacak bir ayar yoktur. -- **Hiçbir şeyi silemez.** Hiçbir silme aracı açılmaz ve asistan hiçbir silme izni tutmaz. Silmeler sizin elinizde kalır, panoda. -- **Kuruluşunuzun içinde kalır.** Asistan yalnızca şu anda görüntüledüğiniz kuruluşu görebilir. -- **Sorularınız sizin kalır.** İstemler ve yanıtlar kendi Observability veritabanınızda yaşar; ürün analitikleri yalnızca kullanım meta verilerini kaydeder, asla istem metninizi değil. +- **Sadece zaten görebildiğiniz şeyleri okur.** Yanıtlar kendi okuma izinlerinize kapsamlıdır, bu nedenle veri yüzeyinizi hiçbir zaman genişletmez. +- **Her yazma sizin için bekler.** Kaydedilmiş sorgular ve panolar yalnızca açık Onayla tıklamanızdan sonra oluşturulur ve bunu kapatacak bir ayar yoktur. +- **Asla hiçbir şeyi silemez.** Hiçbir silme aracı gösterilmez ve asistanın hiçbir silme izni yoktur. Silmeler sizin elinde kalır, panoda. +- **Kuruluşunuzun içinde kalır.** Asistan yalnızca şu anda görüntülediğiniz kuruluşu görür. +- **Sorularınız size kalır.** Hızlı istekler ve yanıtlar kendi Gözlemlenebilirlik veritabanınızda yaşar; ürün analitikleri yalnızca kullanım meta verilerini kaydeder, hiçbir zaman hızlı metin metni kaydeder. ## Nerede bulunur -Asistan, kuruluşunuz altında her sayfanın sağ kenarına bindirme şeklinde yer alır (`//...`). Raya tıklayın veya `⌘J` / `Ctrl+J` tuşlarına basın, tam sohbet paneline genişletin ve kenarını yeniden boyutlandırmak için sürükleyin; genişliğiniz yeniden yükleme sırasında hatırlanır. Kullanmak için **`agent:use`** izni gereklidir, aksi takdirde ray gri renkte görünür. Dağıtımınız için henüz etkinleştirilmemişse (bir LLM bağlantısı gerektirir), çalışan bir sohbet yerine donuk bir ray göreceksiniz. +Asistan, kuruluşunuzun altındaki her sayfanın sağ kenarında (`//...`) birlikte gelir. Raya tıklayın veya tam sohbet paneline genişletmek için `⌘J` / `Ctrl+J` tuşlarına basın ve genişliğini yeniden boyutlandırmak için kenarını sürükleyin; genişliğiniz yeniden yüklemeler arasında hatırlanır. Bunu kullanmak için **`agent:use`** izniniz gerekir, aksi takdirde ray grileştirilir. Dağıtımınız için henüz açılmadıysa (bir LLM bağlantısı gerekir), çalışan sohbet yerine kapalı bir ray göreceksiniz. ## İlgili -- [CLI and agents](/tr/agenteye/cli-and-agents) -- [Queries](/tr/agenteye/queries) -- [Dashboards](/tr/agenteye/dashboards) -- [Evaluation suite](/tr/agenteye/evaluation-suite) \ No newline at end of file +- [CLI ve aracılar](/tr/agenteye/cli-and-agents) +- [Sorgular](/tr/agenteye/queries) +- [Panolar](/tr/agenteye/dashboards) +- [Değerlendirme paketi](/tr/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/tr/agenteye/audits.mdx b/docs/tr/agenteye/audits.mdx index 743bb7da..8b7f1d70 100644 --- a/docs/tr/agenteye/audits.mdx +++ b/docs/tr/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- -title: "Denetimler: otomatik güvenilirlik analistiniz" -description: "Failproof AI Observability, hiçbir kural yazmadığınız hataları bulur ve tam olarak neyi düzeltmeniz gerektiğini sıralı, kanıtlarla desteklenmiş bir yapılacaklar listesi olarak size sunar." +title: "Auditler: otomatik güvenilirlik analisti" +description: "Failproof AI Observability, hiçbir kural yazmamasına rağmen meydana gelen hataları bulur ve tam olarak neyi düzeltmeniz gerektiğine dair sıralanmış, kanıtlarla desteklenmiş bir yapılacaklar listesi sunar." --- -Failproof AI Observability, hiçbir kural yazmadığınız hataları bulur ve tam olarak neyi düzeltmeniz gerektiğini sıralı, kanıtlarla desteklenmiş bir yapılacaklar listesi olarak size sunar. Adeta her gece günlüklerinizi tarayan bir analisti işe alıp, sabah masanızda kısa listeyi bırakmış olmak gibi. +Failproof AI Observability, hiçbir kural yazmamasına rağmen meydana gelen hataları bulur ve tam olarak neyi düzeltmeniz gerektiğine dair sıralanmış, kanıtlarla desteklenmiş bir yapılacaklar listesi sunar. Bir analistin her gece günlüklerinizi incelemesi, ardından sabah masanızda kısa bir listeyi bırakması gibidir.
-*İki dakikalık tur: planlanmış bir çalıştırmadan üzerine hareket edebileceğiniz bir düzeltmeye.* +*İki dakikalık tur: planlı bir çalıştırmadan hareket edebileceğiniz bir düzeltmeye kadar.* -![Denetimler sayfası: oturumlarınızı hata desenleri açısından tarayan, her biri bir zamanlama ve duyarlılığa sahip olan yinelenen işler](/agenteye/images/audits.png) -*Her denetim, oturumlarınızda hata arama yapan ve sıralı, kanıtlarla desteklenmiş öneriler sunan bir yinelenen işdir.* +![Auditler sayfası: oturumlarınızı başarısızlık desenleri açısından taraayan, her biri bir zamanlama ve hassasiyet ayarına sahip olan yinelenen işler](/agenteye/images/audits.png) +*Her audit, oturumlarınızda bilgi arayan ve sıralanmış, kanıtlarla desteklenmiş öneriler sunan yinelenen bir işdir.* -## Sonraki neyi düzeltmeniz gerektiğini tahmin etmeyi bırakın +## Sonra neyi düzeltmeniz gerektiğini tahmin etmeyi bırakın -Uyarılar, zaten izlenmesi gerektiğini bildiğiniz sorunları yakalar. Denetimler, bilmediğiniz sorunları yakalar. Belirlediğiniz bir çizelgeye göre, bir denetim tüm aracı oturumlarınızı okur ve düzeltilmeye değer desenleri arar; böylece zamanınızı bulguları üzerine hareket etmeye harcarsınız ve günlükleri kaydırarak kendiniz bulmayı umut etmeye değil. +Uyarılar zaten bildiğiniz sorunları yakalar. Auditler ise bilmediğiniz sorunları yakalar. Belirlediğiniz bir zamanlamaya göre, bir audit tüm agent oturumlarınızı okur ve düzeltmeye değer desenleri arar; böylece zamanınızı bulgularla ilgilenmek için kullanırsınız, günlüklerle dolaşıp kendiliğinden sorunları bulmaya çalışmak yerine. -Tek bir çalıştırma, aslında üretimdeki aracıları kesintiye uğratan hata modlarını hedefler: +Tek bir çalıştırma, production ortamında ajanları bozan gerçek başarısızlık modlarını araştırır: -- **Hata kümeleri**: paylaşılan bir kök nedenin altında aynı hatanın tekrarlanması. -- **Taban çizgisine karşı sapma**: bilinen iyi bir pencereden sessizce uzaklaşan davranış. -- **Transkriptlerde amaç başarısızlığı**: teknik olarak tamamlanan ancak işi asla yapmayan çalıştırmalar. +- **Hata kümeleri**: aynı başarısızlık ortak bir kök nedeni altında tekrarlanır. +- **Bazlinden kayma**: davranış bilinen iyi bir pencereden sessizce uzaklaşır. +- **Transkriptlerde hedef hatası**: teknik olarak tamamlanan ama işi asla yapmayan çalıştırmalar. - **Araç yanlış kullanımı**: yanlış araç, kötü argümanlar veya çağrıları tüketen döngüler. -- **Kalite ve maliyet dengesi**: daha ucuza elde edebileceğiniz çıktı için fazla ödediğiniz yerler. -- **Kapsama boşlukları**: hiçbir değerlendirme veya uyarı tarafından izlenmeyen davranış. +- **Kalite ve maliyet dengesi**: daha ucuza alabilecek çıktı için fazla para harcadığınız yerler. +- **Kapsama boşlukları**: hiçbir değerlendirme veya uyarının izlemediği davranış. -Tek bir **duyarlılık** ayarı (düşük, orta veya yüksek) ile ne kadar yoğun araştırma yapacağına siz karar verirsiniz; böylece gürültülü bir evreleme aracı ve kilitli bir üretim aracı, istediğiniz sinyale göre her biri ayarlanabilir. +Tek bir **hassasiyet** ayarı (düşük, orta veya yüksek) ile ne kadar hızlı arayacağını siz belirlersiniz; gürültülü bir staging ajanı ve kilitli bir production ajanı her biri istediğiniz sinyale göre ayarlanabilir. -## Her öneri kanıtlarla gelir +## Her önerinin kanıtları vardır -Hiçbir bulguya inanç temeli üzerinden güvenmeniz gerekmez. Her öneri, onun kaynaklandığı tam oturumları ve bunu ortaya çıkaran SQL'i alıntılar; böylece bir tıklamayla kanıtı açabilir ve iddiayı ters mühendislik yapmak yerine sorunu doğrulayabilirsiniz. +Bir bulguyu hiçbir zaman inanç esasına almak zorunda değilsiniz. Her önerinin geldiği tam oturumları ve bunları ortaya koyan SQL'i alıntıladığı için, kanıtları açabilir ve bir tıkla sorunu doğrulayabilirsiniz; bir iddiayı mühendislik açısından tersinden çözmek yerine. -Bir bulgu sızdırılan bir kimlik bilgisiyle ilgiliyse, bir adım daha ileri gider ve eşleştirdiği bireysel olayların bağlantısını verir. Birine tıklayın ve o oturumun tam o anında, zaten seçilmiş halde inersiniz — uzun bir transkripti kaydırmanız gereken bir yerin tepesinde değil. Bağlantı olayın adını verir; algılanan sırrı bulguya asla kopyalamaz; böylece bir bulguyu okumak, kimlik bilgisinin yazıldığı ikinci bir yer değildir. Oturum saklama pencerenizi geçtiği için bir olay artık orada değilse, sayfa bunu açıkça söyler ve yanlış şeyi tıkladığınızı merak etmenizi bırakmaz. +Bulgu sızan bir kimlik bilgisiyle ilgiliyse, bir adım daha ileri gider ve eşleştirdiği bireysel olayları bağlantılandırır. Birine tıklayın ve tam o anda oturumda yer alın, zaten seçili durumda — uzun bir transkriptin başında değil. Bağlantı olayı adlandırır; algılanan sırrı bulguya asla kopyalamaz, bu nedenle bir bulguyu okumak kimlik bilginizin yazıldığı ikinci bir yer değildir. Oturum saklama pencerenizi geçtiği için bir olay artık orada değilse, sayfa bunu açıkça söyler; siz yanlış şey mi tıkladığınızı merak etmek durumunda kalmazsınız. -Bu aynı zamanda denetimleri dürüst tutar. Sunucu, alıntı yapılan her oturumun gerçekten var olduğunu kontrol eder ve **kanıtı dayanmayan herhangi bir öneriyi siler**; denetim soruşturur ama asla icat etmez. Listenize inen her şey gerçek, tekrarlanabilir ve ne kadar önemli olduğuna göre sıralanır; en büyük kazançlar başta. +Bu aynı zamanda auditleri dürüst tutar. Sunucu, alıntılanan her oturumun gerçekten var olduğunu kontrol eder ve **kanıtları geçerli olmayan herhangi bir öneriyi atar**, böylece audit araştırır ama asla icat etmez. Listenize gelen şey gerçek, tekrarlanabilir ve ne kadar önemli olduğu açısından sıralanmış olup, en büyük kazançlar başta yer alır. -## Bir düzeltmeyi bir korkuluğa dönüştürün +## Bir düzeltmeyi koruma bariyerlerine dönüştürün -Bir sorunu düzeltmek sadece yarısı. Diğer yarısı, bunun sessizce geri gelmesinin mümkün olmamasını sağlamaktır. Her bulgu, **bir tıklamayla tekrarlama uyarısı taslağı yapan bir kısayol** taşır; ayarlayabileceğiniz makul bir başlangıç tetiklemesi önceden doldurulmuştur. Buluşu kapatın, uyarıyı aktive edin ve bu desen sonraki sefer ortaya çıktığında gelecekteki bir denetimde keşfetmek yerine çağrı alırsınız. +Bir sorunu düzeltmek yalnızca yarısı kazanıdır. Diğer yarısı, sessizce geri gelmemesini sağlamaktır. Her bulgu, **bir tıkla tekrar uyarısı taslağı oluşturan kısayol** taşır; makul bir başlangıç tetikleyicisiyle doldurulmuş ve siz de ayarlayabilirsiniz. Bulguyu kapatın, uyarıyı etkinleştirin ve bu desen bir sonraki görüldüğünde bildirim alırsınız; gelecekteki bir auditte yeniden keşfetmek yerine. -## Nereden bulacaksınız +## Nerede bulacaksınız -Denetimler, pano içinde **`//audits`** adresinde yer alır (kenar çubuk → *analiz* → *denetimler*). Çalıştırmaları ve bulguları görüntülemek **`audits:read`** gerektirir; denetimleri oluşturmak, düzenlemek ve değerlendirmek **`audits:write`** gerektirir. Bir denetimin kapsamını ve sıklığını ayarlayın, ardından sonraki planlanan geçişi beklemek yerine hemen sonuç almak istediğinizde **Şimdi Çalıştır**'ı tıklayın. +Auditler **`//audits`** konumundaki panoda yer alır (kenar çubuk — *analyze* — *audits*). Çalıştırmaları ve bulguları görüntülemek için **`audits:read`** gerekli; auditler oluşturmak, düzenlemek ve sınıflandırmak için **`audits:write`** gereklidir. Bir auditin kapsamını ve zamanlamasını ayarlayın, sonra sonuç istediğinizde zamanlanmış bir sonraki geçişi beklemek yerine **Run now** (Şimdi Çalıştır) seçeneğini isabet ettirin. -## İlgili +## İlişkili -- [Uyarılar](/tr/agenteye/alerts): zaten bildiğiniz bir eşik geçilir geçilmez çağrı alın. -- [Değerlendirmeler](/tr/agenteye/evaluations): her çalıştırmayı puanlandırın, böylece kalite gerillemeleri kendini gösterir. -- [Hata izleme](/tr/agenteye/error-tracking): aracılarınızın attığı hataları gruplandırın ve takip edin. -- [Olaylar](/tr/agenteye/incidents): bir denetimin ortaya çıkardığı sorunu düzeltilmesine kadar takip edin. \ No newline at end of file +- [Uyarılar](/tr/agenteye/alerts): zaten bildiğiniz bir eşik aşıldığı anda bildirim alın. +- [Değerlendirmeler](/tr/agenteye/evaluations): her çalıştırmayı puanlayın böylece kalite gerilemeleri kendi başlarına ortaya çıksın. +- [Hata izleme](/tr/agenteye/error-tracking): ajanlarınızın attığı hataları gruplandırın ve izleyin. +- [Olaylar](/tr/agenteye/incidents): bir auditin ortaya koyduğu sorunu düzeltilene kadar izleyin. \ No newline at end of file diff --git a/docs/tr/agenteye/cli-and-agents.mdx b/docs/tr/agenteye/cli-and-agents.mdx index 7d5ad5fe..ba07d146 100644 --- a/docs/tr/agenteye/cli-and-agents.mdx +++ b/docs/tr/agenteye/cli-and-agents.mdx @@ -1,10 +1,10 @@ --- title: "CLI" -description: "Tüm Failproof AI Observability dağıtımınız, tek bir komut uzağında." +description: "Tüm Failproof AI Observability dağıtımınız, tek komut uzağında." --- -Tüm Failproof AI Observability dağıtımınız, tek bir komut uzağında. Production'ı kontrol edin, bir API anahtarı oluşturun veya bir olayı onaylayın—hiç terminalinizi terk etmeden. Ardından herhangi birini CI'ye entegre edin veya bir kodlama aracısının bunu düz İngilizce ile yapmasına izin verin. +Tüm Failproof AI Observability dağıtımınız, tek komut uzağında. Üretim ortamınızı kontrol edin, bir API anahtarı oluşturun veya olayı onaylayın — hepsi terminalinizi terk etmeden. Bunu CI'ye entegre edin veya bir kod aracısına düz İngilizce ile yaptırın. ```bash pipx install agenteye @@ -12,18 +12,18 @@ agenteye login --email you@example.com # a 6-digit code lands in your inbox agenteye --json sessions --since 24h # every agent run from the last day, newest first ``` -*`agenteye` CLI'si panoyla iletişim kurar. Sunucuya olayları gönderen collector'dan farklı bir araçtır.* +*`agenteye` CLI'si panonuzla iletişim kurar. Etkinlikleri sunucuya gönderen toplayıcıdan farklı bir araçtır.* -## Tüm dağıtımınız, tek bir komut uzağında +## Tüm dağıtımınız, tek komut uzağında -Hızlı bir soruyu cevaplamak için sekme atlama işini bırakın. `agenteye` CLI'si verilerinizi okur ve kuruluşunuzu tek bir ikili dosyadan yönetir; böylece dashboard'da tıklayarak cevap bulmanız gereken bir kontrol, yeniden çalıştırabileceğiniz, takma ad oluşturabileceğiniz veya bir runbook'a yapıştırabileceğiniz tek bir satıra dönüşür. Dört yüzeye erişebilirsiniz: +Hızlı bir soruyu yanıtlamak için sekmeler arasında dolaşmayı bırakın. `agenteye` CLI'si verilerinizi okur ve kuruluşunuzu tek bir ikili dosyadan yönetir, böylece panoda birkaç tıkla yapılan bir kontrol artık tek bir satıra dönüşür — bunu yeniden çalıştırabilir, takma ad oluşturabilir veya bir runbook'a yapıştırabilirsiniz. Dört araç yüzeyi elde edersiniz: -- **Verilerinizi okuyun:** `sessions`, `events`, `evals` ve `errors`—zaman, agent ve ortama göre filtrelenmiş. +- **Verilerinizi okuyun:** `sessions`, `events`, `evals` ve `errors` — zaman, ajan ve ortama göre filtrelenmiş. - **Kuruluşunuzu yönetin:** `keys`, `users`, `settings`, `alerts` ve `incidents`. -- **Analitik çalıştırın:** kaydedilmiş SQL artı olay verileriniz üzerinde ad hoc `query` çalıştırıcı. -- **Asistana sorun:** `agent ask` dashboard'da sohbet ettiğiniz salt okunur analistle bağlantı kurar. +- **Analitik çalıştırın:** kaydedilmiş SQL ve olay verileriniz üzerinde geçici `query` çalıştırıcı. +- **Asistana sorun:** `agent ask` panodaki aynı salt okunur analistle sohbet eder. -`pipx` ile bir kez kurun, bir e-postaya gelen 6 haneli koduyla oturum açın ve hazırsınız. Oturum yaklaşık bir gün sürer; süresi dolduğunda `agenteye login` komutunu yeniden çalıştırın. Production'ı hızlıca kontrol etmek, bir anahtar sağlamak veya çalışan bir olayı triage etmek için kullanın—tarayıcı açmadan: +`pipx` ile bir kez yükleyin, e-posta gelen kutunuza gelen 6 haneli kodla oturum açın ve hazırsınız. Oturum yaklaşık bir gün sürer; süresi dolduktan sonra `agenteye login` komutunu tekrar çalıştırın. Üretim ortamını kontrol etmek, anahtar sağlamak veya fırlayan bir olayı sınıflandırmak için kullanın — tarayıcı açmaya gerek yok: ```bash agenteye errors --since 24h --aggregate # what is breaking, grouped by error type @@ -31,25 +31,25 @@ agenteye incidents list --state firing # what is on fire right now agenteye keys create ci --add events:add # a key that can only push events, secret shown once ``` -Önemli bir alışkanlık: `--json` gibi global seçenekler komuttan önce gelir. `agenteye --json sessions` doğru; `agenteye sessions --json` değildir. +Bilinmesi gereken bir alışkanlık: `--json` gibi global seçenekler komuttan önce gelir. `agenteye --json sessions` doğru; `agenteye sessions --json` değildir. -## Betik haline getirin, CI'ye entegre edin +## Bunu kodlayın, CI'ye entegre edin -Her komut `--json` alır ve bu her şeyi değiştirir. Temiz JSON stdout'a yazılır, insan durumu ve uyarılar stderr'e gider; böylece `--json` çıktısı `jq`'ya doğrudan gider, kırpılacak hiçbir satır olmaz. Bu, CLI'yi hem sizin bir komut isteminde hem de kodlama aracısının çıktısını ayrıştırırken eşit derecede iyi kılar: +Her komut `--json` alır ve bu her şeyi değiştirir. Temiz JSON stdout'a gider, insan durumu ve uyarılar stderr'e gider, böylece `--json` çıktısı doğrudan `jq` ile birleşir — temizlenecek hiçbir satır yoktur. Bu, CLI'yi hem siz bir komut isteminde hem de çıktıyı ayrıştıran bir kod aracısı için eşit derecede iyi yapar: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -Gözetimsiz çalışmak için tasarlanmıştır. Terminal bağlı olmadığında onay istemleri otomatik olarak atlanır; böylece hiçbir şey bir pipeline'da kalmaz ve her komut anlamlı bir çıkış kodu döndürür: `0` başarılı, `4` oturum açılmamış, `5` izin eksik (ileti adını verir, örneğin `alerts:write`), `3` dashboard ulaşılamaz. Bir betik kodu `4` için yeniden kimlik doğrulamak veya `5` için tam olarak bir yöneticiye ne sorması gerektiğini söylemek için dallanabilir, kör şekilde başarısız olmak yerine. +Gözetimsiz çalışmak üzere inşa edilmiştir. Onay istemleri terminal bağlı olmadığında otomatik olarak atlanır, böylece işlem hattında hiçbir şey takılmaz ve her komut anlamlı bir çıkış kodu döndürür: `0` başarı, `4` giriş yapılmamış, `5` izin eksik (ileti adını verir, örneğin `alerts:write`), `3` pano erişilemez. Bir komut dosyası, `4` üzerinde yeniden kimlik doğrulaması yapmak veya `5` üzerinde bir yöneticiye tam olarak ne isteyeceğinizi söylemek için şubeler oluşturabilir — kör bir şekilde başarısız olmak yerine. -## Bir kodlama aracısının bunu düz İngilizce ile yapmasına izin verin +## Bir kod aracısını düz İngilizce ile yönlendirelim -Daha da iyisi, tüm bu bayrakları hatırlamanız gerekmemeli. **CLI skill'i**, bir kodlama aracısı (Claude Code veya Codex gibi) CLI'yi düz İngilizce isteklerden yönlendirir öğreten `agenteye-cli` adlı küçük bir Agent Skill klasörüdür. "Bugün bir şey bozuk mu?" sorun ve aracı komutu seçer, sizin olarak çalıştırır ve cevabı yazılı olarak verir. +Daha da iyisi, hiç bu bayrakları hatırlamanız gerekmez. **CLI becerisi**, bir kod aracısı (Claude Code veya Codex gibi) CLI'yi düz İngilizce isteklerinden yönlendirmeyi öğreten `agenteye-cli` adlı küçük bir Agent Skill klasörüdür. "Bugün bir şey bozuk mu?" deyin ve ajan komutu seçer, sizin olarak çalıştırır ve düz metin olarak yanıt verir. -Claude Code için, `agenteye-cli` klasörünü `~/.claude/skills/` dizinine bırakın ve otomatik olarak keşfedilir. Failproof AI Observability klasörü sağlar; zaten kurduğunuz CLI'yi yönlendirdiği için ekstra kurmaya gerek yoktur. Önce kendiniz oturum açın: skill, e-postaya gelen kod oturumunu sizin için tamamlayamaz. +Claude Code için `agenteye-cli` klasörünü `~/.claude/skills/` içine bırakın ve otomatik olarak bulunur. Failproof AI Observability klasörü sağlar; kurulacak ek bir şey yoktur, çünkü yalnızca zaten yükledığiniz CLI'yi yönlendirir. Önce kendiniz oturum açın: ajan sizin için e-posta gelen kodlu oturum açmayı tamamlayamaz. -Aracı CLI'yi sizin olarak çalıştırdığından, oturmunuzun izin verdiği her şeyi yapabilir—okuma ve yazma işlemleri: anahtarlar oluşturun, ayarları değiştirin, olayları çözün. CLI'nin "emin misiniz?" istemi bir aracı için ateşlenmez; böylece skill yazılmıştır—tam komutu belirtir ve herhangi bir değişiklikten önce onay bekler. Siz onay adımısınız. +Ajan sizin olarak CLI'yi çalıştırdığından, oturum açmanızın izin verdiği her şeyi yapabilir — okuma ve yazma: anahtarları oluşturmak, ayarları değiştirmek, olayları çözmek. CLI'nin "emin misiniz?" istemi bir ajan için çalışmaz, bu nedenle beceri tam komutu belirtir ve herhangi bir değişiklikten önce onay bekler. Siz onay adımısınız. ```text you Why did session run-001 fail? @@ -58,7 +58,7 @@ agent Running: agenteye --json events --session-id run-001 --all The checkout-agent hit a TimeoutError on its third tool call. ``` -Okuma işlemleri anlıktır ve her yazma işlemi duraklar: +Okuma işlemleri anlık kalır ve her yazma sizin için duraklar: ```text you Give CI a key that can only push events. @@ -74,7 +74,7 @@ agent Done. Key "ci" created with events:add only. The secret is shown once, so ## İlgili -- [CLI reference](/tr/agenteye/cli): her komut, bayrak ve JSON şekli. -- [Aracılar için CLI tarifleri](/tr/agenteye/cli-recipes): kopyala-yapıştır `jq` desenleri ve çıkış kodu işleme. -- [CLI aracı skill'i](/tr/agenteye/cli-skill): `agenteye-cli` skill'ini kurun ve çalıştırın. -- [AI asistanı](/tr/agenteye/assistant): `agent ask` ile konuşan pano içi analist. \ No newline at end of file +- [CLI referansı](/tr/agenteye/cli): her komut, bayrak ve JSON şekli. +- [Ajanlar için CLI tarifleri](/tr/agenteye/cli-recipes): `jq` desenlerini ve çıkış kodu işlemeyi kopyalayıp yapıştırın. +- [CLI ajan becerisi](/tr/agenteye/cli-skill): `agenteye-cli` becerisini yükleyin ve çalıştırın. +- [AI asistanı](/tr/agenteye/assistant): `agent ask` ile konuşan panodaki analistin. \ No newline at end of file diff --git a/docs/tr/agenteye/cli-recipes.mdx b/docs/tr/agenteye/cli-recipes.mdx index 623f24dd..6fd9b193 100644 --- a/docs/tr/agenteye/cli-recipes.mdx +++ b/docs/tr/agenteye/cli-recipes.mdx @@ -1,30 +1,30 @@ --- title: "Ajanlar için CLI tarifleri" -description: "Oturum, olay ve değerlendirme verilerini bir betiğin veya kodlama ajanının otomatikleştirebileceği şeye dönüştüren copy-paste sorgu desenleri ve jq tarifleri." +description: "Oturum, olay ve değerlendirme verilerini bir komut dosyasının veya kodlama ajanının otomatikleştirebileceği şeye dönüştüren kopyala-yapıştır sorgu desenleri ve jq tarifleri." --- -Oturum, olay ve değerlendirme verilerini (ve yeniden değerlendirmeleri tetikleyin) doğrudan bir betikten veya kodlama ajanından çekin, stdout'a temiz JSON çıkışı ile `jq`'ya doğrudan aktarılan veriler. Bu tarifler Failproof AI Observability'nin verilerini terminal kullanıcısı veya bir AI kodlama ajandan (Claude Code, Cursor) sorgulanabilir ve otomatikleştirilebilir şeye dönüştürür, pano üzerinde tıklama yapmanız gerekmeden. +Oturum, olay ve değerlendirme verilerini doğrudan bir komut dosyasından veya kodlama ajanından çekin (ve yeniden değerlendirmeleri tetikleyin), `jq` içine doğrudan aktarılan temiz JSON ile stdout üzerinde. Bu tarifler, Failproof AI Observability'nin verilerini bir terminal kullanıcısı veya bir AI kodlama ajanı (Claude Code, Cursor) tarafından sorgulanan ve otomatikleştirilmiş bir şeye dönüştürür; pano üzerinde tıklamaya gerek kalmaz. -Aşağıdaki desenleri Failproof AI Observability CLI'sı (`agenteye`) için copy-paste olarak kullanabilirsiniz. Kurulum, kimlik doğrulama ve tam seçenek listesi için bkz. [CLI](/tr/agenteye/cli); yerleşik yardım için `agenteye -h` veya `agenteye -h` komutunu çalıştırın. +Aşağıdaki desenler, Failproof AI Observability CLI'si (`agenteye`) için kopyala-yapıştır hazırdır. Kurulum, kimlik doğrulama ve tam seçenek listesi için [CLI](/tr/agenteye/cli) bölümüne bakın; yerleşik yardım için `agenteye -h` veya `agenteye -h` komutlarını çalıştırın. ## Altın kurallar -1. **Global seçenekler komuttan *öncesine* gelir.** `agenteye --json sessions` doğrudur; `agenteye sessions --json` değildir. Global seçenekler şunlardır: `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Çıktıyı ayrıştırırken `--json` geçirin.** Veriler **stdout**'a JSON olarak gider; insan durumu ve hatalar **stderr**'e gider, bu nedenle stdout `jq`'ya aktarılmak üzere temiz kalır. -3. **Exit kodu üzerinden branch yapın**, stderr metni üzerinden değil: `0` tamam · `1` beklenmeyen hata · `2` hatalı argümanlar · `3` panoya ulaşılamıyor · `4` oturum açılmamış veya süresi dolmuş · `5` izin eksik · `6` kaynak bulunamadı. -4. **`-h` ile keşfedin.** Her komut filtrelerini, değer biçimlerini ve JSON şeklini belgeler. +1. **Genel seçenekler komutu *öncesinde* gelir.** `agenteye --json sessions` doğru; `agenteye sessions --json` değildir. Genel seçenekler `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color` dir. +2. **Çıktıyı ayrıştırırken `--json` geçirin.** Veriler **stdout** üzerinde JSON olarak gider; insan durumu ve hatalar **stderr** öğesine gider, böylece stdout `jq` içine aktarılmak için temiz kalır. +3. **Çıkış kodunda dallanmayın, stderr metninde değil**: `0` tamam · `1` beklenmeyen hata · `2` hatalı argümanlar · `3` pano erişilemez · `4` oturum açılmamış veya süresi dolmuş · `5` izin eksik · `6` kaynak bulunamadı. +4. **`-h` ile keşfet.** Her komut filtrelerini, değer biçimlerini ve JSON şeklini belgeler. ## Tek seferlik kurulum ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # böylece --base-url tekrarlamayın -agenteye login --email you@example.com # emaille gelen kodu yapıştırın; ~24s geçerli +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # tekrar --base-url geçirmeyesiniz diye +agenteye login --email you@example.com # e-postayla gelen kodu yapıştırın; ~24s geçerli ``` -## İşe başlamadan önce kimlik doğrulamayı onaylayın +## İş yapmadan önce kimlik doğrulamayı doğrulayın -`whoami` eksik veya süresi dolmuş oturumda hiçbir zaman hata vermez; bunun yerine `logged_in:false` raporlar, bu nedenle bir ajan auth durumunu güvenli bir şekilde araştırabilir. (Base URL ayarlanmamışsa veya pano erişilemezse yine de sıfır olmayan bir şekilde çıkabilir.) +`whoami` eksik veya süresi dolmuş bir oturum üzerinde asla hata vermez; bunun yerine `logged_in:false` bildirin, böylece bir ajan kimlik doğrulama durumunu güvenle sorgulanabilir. (Hiçbir temel URL ayarlanmamışsa veya pano erişilemezse yine de sıfır olmayan bir çıkış yapabilir.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -35,25 +35,25 @@ fi ## Başarısız veya düşük puanlı oturumları bulun ```bash -# son 24 saatte değerlendirmesi hatayla sonuçlanan oturumlar +# son 24s içinde değerlendirmesi hata alan oturumlar agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# bir ajan için yardımcılık açısından <= 0.5 puan alan değerlendirmeler +# bir ajan için yardımcılık konusunda 0,5 ve altında puan alan değerlendirmeler agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Puan filtreleme **`evals`** üzerinde canlıdır, `sessions` üzerinde değil. `--score KEY:MIN..MAX` tekrarlanabilir ve AND-birleştirilmiş; her iki sınır da isteğe bağlıdır (`..0.5` anlamı ≤ 0.5, `0.9..` anlamı ≥ 0.9). İstek başına 20'ye kadar puan filtresi geçirebilirsiniz; daha fazlası HTTP 400 döndürür. `sessions`, `evals` ile `--env`, `--status`, `--agent-id`, `--session-id` ve zaman aralığı filtrelerini paylaşır, ancak `--score`'a sahip değildir. +Puan filtreleme **`evals`** üzerinde yaşar, `sessions` üzerinde değil. `--score KEY:MIN..MAX` tekrarlanabilir ve AND ile birleştirilmiş; her iki sınır isteğe bağlı (`..0.5` ≤ 0.5 anlamına gelir, `0.9..` ≥ 0.9 anlamına gelir). İstek başına 20 adama kadar puan filtresi geçirebilirsiniz; daha fazlası HTTP 400 döndürür. `sessions`, `evals` ile `--env`, `--status`, `--agent-id`, `--session-id` ve zaman aralığı filtrelerini paylaşır, ancak `--score` öğesi yoktur. ## Bir oturumu baştan sona okuyun -Tek bir `session show` komutu yoktur. Olay kaydını oturumun değerlendirmesiyle birleştirin: +Tek bir `session show` komutu yoktur. Etkinlik kaydını oturumun değerlendirmesiyle birleştirin: ```bash # oturumun en son değerlendirmesi (durum + puanlar) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# çalıştırmada her olay (tam bir gezinti için --limit yükseltin) +# çalıştırmadaki her olay (tam tarama için --limit'i yükseltin) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' # bir oturumdaki yalnızca araç çağrıları (ham yükü almak için --full gereklidir) @@ -61,69 +61,69 @@ agenteye --json events --full --session-id run-001 --event-type tool_use,tool_re | jq '.events[].payload' ``` -> **Not:** Varsayılan olarak, `events` hızlı, yüksüz bir akış okur. Her olay sunucu tarafından hesaplanan tek satırlık bir `summary` ve `is_error` ve belirteç sayıları gibi bayraklar taşır, ancak `payload` `{}` olarak geri gelir. Ham yükü çekmek için `--full` (veya `--fields payload`) ekleyin. Tam akış ölçekte daha yavaştır, bu nedenle onu sınırlandırılmış tutun: `--full` ile tek bir `--session-id` eşleyin. +> **Not:** Varsayılan olarak, `events` hızlı, yüksüz beslemesini okur. Her olay sunucu tarafından hesaplanan bir satırlık `summary` artı `is_error` ve belirteç sayıları gibi bayraklar taşır, ancak `payload` `{}` olarak geri gelir. Ham yükü çekmek için `--full` (veya `--fields payload`) ekleyin. Tam beslemesi, ölçekte daha yavaştır, bu nedenle sınırlandırılmış tutun: `--full` öğesini tek bir `--session-id` ile eşleştirin. -## Tümünü getir (sayfalandırma) +## Her şeyi getir (sayfalandırma) -Sonuçlar yeniden başlayan ve imleç sayfalandırılmıştır. +Sonuçlar en yeniden en eskiye doğru sıralanmış ve imleç sayfalandırılmıştır. ```bash -# bir kez: 200 satırlık sayfalarda 500 satıra kadar getir +# tek kez: 200 satırlık sayfalar halinde 500 satıra kadar getir agenteye --json events --session-id run-001 --limit 500 --all > events.json -# manuel sayfalama: sonraki imleyici geri besle +# manuel sayfalandırma: next_cursor öğesini geri aktar page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## `--fields` ile çıktıyı azalt +## Çıktıyı --fields ile daraltın -Anahtarları kısıtlayın (hem tabloda hem de `--json`'da) bir ajanın okuması gereken şeyi azaltmak için. +Bir ajanın okuması gereken şeyi azaltmak için anahtarları (hem tabloda hem de `--json` içinde) sınırlayın. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Bilinmeyen alan adları `2` çıkışı (exit) ile reddedilir ve geçerli listesi vardır, alan adlarını keşfetmenin ucuz bir yoludur. +Bilinmeyen alan adları reddedilir (çıkış `2`) geçerli listele, alan adlarını keşfetmenin ucuz bir yolu. -## Geçerli filtre değerlerini keşfedin +## Geçerli filtre değerlerini keşfet ```bash agenteye --json list envs | jq -r '.values[]' # --env için değerler -agenteye --json list tools | jq -r '.values[]' # araç adları; ayrıca ajanlar, modeller, event_types, … +agenteye --json list tools | jq -r '.values[]' # araç adları; ayrıca ajanlar, modeller, event_types, vb. agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX için geçerli KEY ``` -## Org'unuzu seçin (çok kiracılı) +## Kuruluşunuzu seçin (çok kiracılı) -Birden fazla org'a aitse, login sırasında etkin kiracıyı seçin (kaydedilir): +Birden fazla kuruluşa aitseniz, etkin kiracıyı oturum açma sırasında seçin (kaydedilir): ```bash -agenteye login --org acme --email you@corp.com # login ile aynı adımda kiracıyı ayarla +agenteye login --org acme --email you@corp.com # oturum açmayla aynı adımda kiracıyı ayarla agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # bir komut için geçersiz kıl ``` -`--org` olmayan çok org login sıfır olmayan bir değerle çıkar ve seçilebilecek org'ları yazdırır. +`--org` olmayan çok kuruluşlu oturum açma sıfır olmayan çıkış yaparak seçilecek kuruluşları yazdırır. -## SDK/toplayıcı için bir API anahtarı sağlayın +## SDK/toplayıcı için bir API anahtarı sağla ```bash -# gizli bir kez yazdırılır, --json ile .key alanıdır +# gizli dizi BİR KEZ yazdırılır, --json ile `.key` alanı key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # döndür; agenteye keys disable ci-bot --yes iptal etmek için +agenteye keys regenerate ci-bot --yes # döndür; iptal etmek için agenteye keys disable ci-bot --yes ``` -## Kaydedilmiş veya geçici bir sorgu çalıştırın +## Kaydedilmiş veya ad hoc sorgu çalıştır ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # kaydedilmiş sorgu + konumsal $1 +agenteye --json query run errs --arg prod | jq '.rows' # kaydedilmiş bir sorgu + konumsal $1 ``` -## Etkileşimsiz bir olayı ayıkla +## Olayı etkileşimsiz şekilde önemseyin ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,9 +132,9 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **Not:** Mutasyonlar `--json` altında veya stdin bir TTY olmadığında onay istemini otomatik olarak atlar, bu nedenle ajanlar asla takılmaz; başka yerlerde açıkça atlamak için `--yes`/`-y` geçirin. +> **Not:** Mutasyonlar `--json` altında veya stdin TTY olmadığında onay istemleri otomatik olarak atlar, böylece ajanlar hiç asılı kalmazlar; başka yerde açıkça atlamak için `--yes`/`-y` geçirin. -## Bir betikte exit-code işleme +## Bir komut dosyasında çıkış kodu işleme ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -147,7 +147,7 @@ case "${code:-0}" in esac ``` -## JSON çıkış şekilleri +## JSON çıktı şekilleri | Komut | stdout JSON (`--json` ile) | |---|---| @@ -158,22 +158,22 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` bir kez gösterilir) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` bir kez gösterildi) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| oluştur/güncelle/sil (herhangi) | kaynak nesnesi, veya silmeler için `{"deleted": true, "id"}` | -| başarısızlık (herhangi, `--json` ile) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` stdout'da | +| oluştur/güncelle/sil (herhangi) | kaynak nesnesi veya siler için `{"deleted": true, "id"}` | +| hata (herhangi, `--json` ile) | stdout üzerinde `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | -- Her **olay** öğesi (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. `payload`'ın `--full` (veya `--fields payload`) ile tam akışı istememedikçe `{}` olduğuna dikkat edin. +- Her **olay** öğesi (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. `payload` öğesinin `{}` olduğunu unutmayın; `--full` ile tam beslemesini talep etmezseniz (veya `--fields payload`). - Her **değerlendirme** öğesi (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Her **oturum** öğesi (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -Her komutun `--fields` tam olarak kendi öğesinin alan adlarını kabul eder. Set `sessions` ve `evals` arasında farklıdır, bu nedenle birisi için geçerli bir ad diğeri tarafından reddedilebilir. +Her komutun `--fields` tam olarak kendi öğesinin alan adlarını kabul eder. Küme `sessions` ve `evals` arasında farklıdır, bu nedenle bir için geçerli olan bir ad, diğeri tarafından reddedilebilir. ## Sonraki adımlar -- [CLI](/tr/agenteye/cli): kurulum, kimlik doğrulama ve her komut için tam seçenek başvurusu. +- [CLI](/tr/agenteye/cli): kurulum, kimlik doğrulama ve her komut için tam seçenek referansı. - [CLI ajan becerisi](/tr/agenteye/cli-skill): bu tarifleri kodlama ajanınızın yükleyebileceği bir beceri olarak paketleyin. -- [API anahtarları](/tr/agenteye/api-keys): CLI, SDK ve toplayıcının kimlik doğrulaması yaptığı anahtarları oluşturun ve kapsamlayın. -- [Python SDK](/tr/agenteye/python-sdk): Failproof AI Observability'ye olaylar gönderin, böylece bu tarifler tarafından sorgulanacak veriler olur. \ No newline at end of file +- [API anahtarları](/tr/agenteye/api-keys): CLI, SDK ve toplayıcıyı kimlik doğrulayan anahtarları oluşturun ve kapsamını belirleyin. +- [Python SDK](/tr/agenteye/python-sdk): bu tariflerin sorgulayabileceği veriler olması için Failproof AI Observability'ye etkinlikler gönderin. \ No newline at end of file diff --git a/docs/tr/agenteye/cli-skill.mdx b/docs/tr/agenteye/cli-skill.mdx index 7bbfbf83..a6a7ac18 100644 --- a/docs/tr/agenteye/cli-skill.mdx +++ b/docs/tr/agenteye/cli-skill.mdx @@ -1,102 +1,102 @@ --- --- title: "Failproof AI Observability CLI Agent Skill" -description: "Kodlama aracınıza \"bugün bir şey bozuk mu?\" sorusu sorun ve Failproof AI Observability verilerinizden canlı yanıt alın — hiç komut ezberlemek zorunda değilsiniz." +description: "Kodlama acentenize \"bugün bir şey bozuk mu?\" sorusunu sorun ve canlı Failproof AI Observability verilerinizden yanıt alın, ezberlenecek komut yoktur." --- -Kodlama aracınıza *"bugün bir şey bozuk mu?"* sorusu sorun ve Failproof AI Observability canlı verilerinizden yanıt alın — hiç komut ezberlemek zorunda değilsiniz. **Failproof AI Observability CLI becerisi** (`agenteye-cli`), bir *Agent Becerisi*dir: kodlama aracı olarak Claude Code veya Codex'in isteğe bağlı olarak yükleyebileceği küçük bir talimat klasörü. Aracınızı, *"sadece etkinlik gönderebilecek CI için bir anahtar ver"* veya *"açık olayı onayla ve bana ata"* gibi basit İngilizce isteklerle [`agenteye` CLI](/tr/agenteye/cli) aracılığıyla Observability dağıtımınızı kullanmayı öğretir. +Kodlama acentenize *"bugün bir şey bozuk mu?"* sorusunu sorun ve canlı Failproof AI Observability verilerinizden yanıt alın. **Failproof AI Observability CLI becerisi** (`agenteye-cli`), bir *Agent Becerisi*dir: bir kodlama acentesi (Claude Code veya Codex gibi) tarafından isteğe bağlı olarak yüklenen küçük bir yönerge klasörü. Acenteyi, [`agenteye` CLI](/tr/agenteye/cli) aracılığıyla Observability dağıtımınızı işletmeyi öğretir; *"CI'a yalnızca etkinlik gönderebilen bir anahtar ver"* veya *"tetiklenen olayı onayla ve bana ata"* gibi düz İngilizce isteklerle. -Bu **değildir** bir hizmet veya ayrı bir ikili dosya; dağıtılacak hiçbir şey yoktur. Zaten yüklemiş olduğunuz CLI'nin üzerinde çalışır: ajan `agenteye --json …` komutunu çalıştırır, temiz JSON'u ayrıştırır ve size cevapı düz metin şeklinde verir. Yapabileceği her şey, aynı komutları kendiniz yazarak da yapabilirsiniz. +Bu, bir hizmet veya ayrı bir ikili **değildir**; dağıtılacak hiçbir şey yoktur. Zaten yüklenmiş olduğunuz CLI'nın üzerine oturur: aracı `agenteye --json …`'e çıkarır, temiz JSON'u ayrıştırır ve size düz yazıyla yanıt verir. Yapabileceği her şey, aynı komutları yazarak kendiniz de yapabilirsiniz. --- ## Diğer Failproof AI Observability arayüzleriyle ilişkisi -Failproof AI Observability aynı verilere ve kontrollere ulaşmanız için dört yol sunar. Birbirlerini tamamlarlar: +Failproof AI Observability size aynı verilere ve denetimlere ulaşmak için dört yol sunur. Birbirini tamamlarlar: -| Arayüz | Ne olduğu | Nerede çalışır | Şu durumlarda kullanın | +| Arayüz | Nedir | Nerede çalışır | Ne zaman kullanılır | |---|---|---|---| | **[CLI](/tr/agenteye/cli)** | `agenteye` için komut/bayrak başvurusu | Terminaliniz | Belirli bir komutu çalıştırmak veya betiklemek istediğinizde | -| **[CLI tarifleri](/tr/agenteye/cli-recipes)** | Kopyala-yapıştır `jq`/pipeline desenleri | Terminaliniz / betikleriniz | CLI'yi otomasyon içine bağlıyorsanız | -| **CLI becerisi** (bu belge) | CLI üzerinde doğal dil giriş kapısı | Kodlama aracınız, iş istasyonunuzda | Sadece sormak ve aracın komutu seçmesini bırakmak istediğinizde | -| **[Evaluator becerisi](/tr/agenteye/evaluator-skill)** | Puanlama hizmetinizi tasarlayan ve kuran kardeş beceri | Kodlama aracınız, iş istasyonunuzda | Puanlamayı *üretmek* istediğinizde, okumak değil | -| **[Python SDK becerisi](/tr/agenteye/python-sdk-skill)** | Aracınıza telemetri yayması için enstrüman takılan kardeş beceri | Kodlama aracınız, iş istasyonunuzda | Aracınızın bu becerinin okuduğu olayları *üretmesini* istediğinizde | -| **[Panodaki AI asistanı](/tr/agenteye/assistant)** | Panoya gömülü sohbet | Sunucu tarafı (panoda) | Verileriniz üzerinde pano içi soru-cevap istediğinizde | +| **[CLI tarifleri](/tr/agenteye/cli-recipes)** | Kopyala-yapıştır `jq`/pipeline desenleri | Terminaliniz / betikler | CLI'yi otomasyona entegre ettiğinizde | +| **CLI becerisi** (bu doküman) | CLI'ye doğal dil ön kapısı | Kodlama acenteniz, iş istasyonunuzda | Sadece sormak ve acentenin komutu seçmesine izin vermek istediğinizde | +| **[Evaluator becerisi](/tr/agenteye/evaluator-skill)** | Puanlama hizmetinizi tasarlamak ve oluşturmak için kardeş beceri | Kodlama acenteniz, iş istasyonunuzda | Puanları okumak yerine *oluşturmak* istediğinizde | +| **[Python SDK becerisi](/tr/agenteye/python-sdk-skill)** | Acentenizi telemetri yayması için enstrüman etmek için kardeş beceri | Kodlama acenteniz, iş istasyonunuzda | Acentenizin bu becerinin okuduğu olayları *üretmesini* istediğinizde | +| **[Panoda yerleşik AI asistanı](/tr/agenteye/assistant)** | Panoda yerleştirilmiş sohbet | Sunucu tarafı (panoda) | Verileriniz üzerinde panoda soru-cevap istediğinizde | -Becerinin kendi imtiyazı yoktur; sadece sözlerinizi sizin olarak çalışan CLI çağrılarına dönüştürür: +Becerinin kendisinin kendi ayrıcalığı yoktur; yalnızca sözcüklerinizi siz olarak çalışan CLI çağrılarına dönüştürür: ```mermaid flowchart TD - YOU["siz: 'açık olayı onayla'"] --> AGENT["kodlama aracı (Claude Code / Codex)
agenteye-cli becerisini yükler"] + YOU["siz: 'tetiklenen olayı onayla'"] --> AGENT["kodlama acentesi (Claude Code / Codex)
agenteye-cli becerisini yükler"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|kimliğiniz doğrulanan CLI oturumu| API["Observability panosu API"] + CLI -->|kimliğinizin doğrulandığı CLI oturumu| API["Observability panosu API'si"] ``` -### Panodaki AI asistanına karşı: önemli bir fark +### Panoda yerleşik AI asistanı ile karşılaştırma: önemli bir ayrım Bunlar çok farklı etki alanlarına sahip iki farklı araçtır: -- **Panodaki AI asistanı** ([AI asistanı](/tr/agenteye/assistant)) panoya gömülü bir sohbet, ajan hizmeti tarafından desteklenir. **Yalnızca okunur artı onay gerektiren yazma**: kaydedilen sorguları ve panoları hazırlayabilir, ancak her yazma işlemi açık tıklamanızı bekler ve hiçbir zaman silmez. `agent:use` izni tarafından korunan ve yalnızca görüntülediğiniz kuruluşun verilerini görür. -- **CLI becerisi** *sizin* iş istasyonunuzda *sizin* kodlama aracınız içinde çalışır ve `agenteye` CLI'yi **sizin olarak** kullanır. CLI'nin **tam yüzeyini, değişiklikleri** (API anahtarları oluşturma/döndürme/devre dışı bırakma, kuruluş ayarlarını değiştirme, olayları çözme, kaydedilen sorguları silme) gerçekleştirebilir; bunlar yalnızca CLI oturumunuzun izinleriyle sınırlanır. Bunu tam olarak bu komutları elle çalıştırıyor gibi dikkatle kullanın. +- **Panoda yerleşik AI asistanı** ([AI asistanı](/tr/agenteye/assistant)), pano tarafından desteklenen panoda yerleştirilmiş bir sohbettir. **Yalnızca okuma artı onay kapısı yazma**'dır: kaydedilmiş sorguları ve panoları taslağını çizebilir, ancak her yazma işlemi açık tıklamanız için duraklatılır ve asla silmez. `agent:use` izni tarafından kapılanır ve yalnızca izlemekte olduğunuz kuruluş için verileri görür. +- **CLI becerisi** *sizin* iş istasyonunuzda *sizin* kodlama acentenizin içinde çalışır ve `agenteye` CLI'nı **siz olarak** yürütür. CLI'nin **tam yüzeyini, değişimleri de içerecek şekilde** gerçekleştirebilir (API anahtarları oluşturma/döndürme/devre dışı bırakma, kuruluş ayarlarını değiştirme, olayları çözme, kaydedilmiş sorguları silme), yalnızca CLI oturum açma izinlerinizle sınırlanır. Bunu, bu komutları elle çalıştıracakmış gibi dikkatle değerlendirin. --- ## Ön koşullar -1. **`agenteye` CLI yüklü** ve `PATH` içinde (bkz. [CLI](/tr/agenteye/cli) başvurusu: `pipx install agenteye`). -2. **Pano URL'niz ayarlanmış** (`AGENTEYE_DASHBOARD_URL` veya ajan `--base-url` iletir). -3. **Oturum açmış bir oturum**: önce kendiniz `agenteye login` çalıştırın. Beceri **yapamaz** e-postayla gelen tek seferlik kod girişini sizin için tamamlamak; oturum eksikse veya süresi dolmuşsa (`CLI çıkış kodu 4`) size `agenteye login` çalıştırmasını söyler. +1. **`agenteye` CLI yüklü** ve `PATH`'te (bkz. [CLI](/tr/agenteye/cli) başvurusu: `pipx install agenteye`). +2. **Pano URL'iniz ayarlanmış** (`AGENTEYE_DASHBOARD_URL` veya aracı `--base-url` geçirir). +3. **Oturum açmış bir oturum**: önce kendiniz `agenteye login` çalıştırın. Beceri e-postayla gelen tek seferlik kodlu oturum açmayı **tamamlayamaz**; oturum eksikse veya süresi dolmuşsa (CLI çıkış kodu `4`) `agenteye login` çalıştırmanızı söyler. --- -## Nerede bulabileceğiniz +## Nereden bulacağınız -Beceri, Failproof AI'nın genel beceri koleksiyonunda yayınlanır: +Beceri Failproof AI'nın genel beceri koleksiyonunda yayınlanmıştır: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -Hiçbir şey kilitli değildir — depo halka açıktır ve becerinin kendi kimlik bilgisine ihtiyacı yoktur, çünkü sadece **genel** `agenteye` CLI'yi *sizin* panonuza karşı, *sizin* oturum açtığınız oturumu kullanarak kullanır. Bunu almak için kimseye sormak zorunda değilsiniz. +Hiçbir şey kapılanmamıştır — depo herkese açıktır ve becerinin kendi kimliği gerekmez, çünkü yalnızca **genel** `agenteye` CLI'sini *sizin* pano *kullanarak* siz oturum açtıysanız yürütür. Bunu talep etmek için kimseye sormanız gerekmez. -`pipx install agenteye` paketi içinde kendi klasörü olarak gönderildiğine, **değil** içinde olduğunu, bu nedenle orada arama yapmayın. +`pipx install agenteye` paketinin içinde olmadığı için kendi klasörü olarak gelir, bu nedenle orada aramayın. ## Beceriyi yükleme -En hızlı yol [`skills`](https://skills.sh) CLI'dir; bu klasörü getirir ve aracınızın aradığı yere koyar: +En hızlı yol [`skills`](https://skills.sh) CLI'sidir; bu, klasörü getirir ve acentenizin aradığı yere bırakır: ```bash # Claude Code, yalnızca bu proje npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -# her proje (~/.claude/skills/ dizinine yükler) +# her proje (~/.claude/skills/ öğesine yükler) npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy # Bunun yerine Codex npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -Sonra bunu başka herhangi bir beceri gibi yönetin: +Ardından bunu başka herhangi bir beceri gibi yönetin: ```bash npx skills list -a claude-code # yüklü olanlar -npx skills update agenteye-cli # en son sürümü al +npx skills update agenteye-cli # en son sürümü çek npx skills remove agenteye-cli # kaldır ``` -El ile yüklemeyi tercih ediyor musunuz? Bir Agent Becerisi sadece bir `SKILL.md` (artı isteğe bağlı referanslar) içeren bir klasördür; kopyalama da işe yarar: +Elle yüklemeyi tercih eder misiniz? Bir Agent Becerisi yalnızca `SKILL.md` içeren (artı isteğe bağlı referanslar) bir klasördür, bu nedenle kopyalama da işe yarar: -- **Claude Code**: `agenteye-cli/` klasörünü `~/.claude/skills/` (her proje) veya `/.claude/skills/` (yalnızca o repo) içine koyun. Claude Code otomatik olarak keşfeder — `/skills` listinde doğrulayın veya açıklamasıyla eşleşen bir soru sorun. -- **Codex (OpenAI)**: Codex aynı `SKILL.md` dosyasını okur. Paketlenen `agents/openai.yaml`, `allow_implicit_invocation: true` olarak ayarlanmıştır; bu nedenle görev eşleştiğinde Codex beceriyi otomatik olarak seçer; aksi takdirde bunu açıkça `$agenteye-cli` olarak çağırın. +- **Claude Code**: `agenteye-cli/` klasörünü `~/.claude/skills/` (her proje) veya `/.claude/skills/` (yalnızca o depo) içine koyun. Claude Code otomatik olarak keşfeder — `/skills` listesi ile doğrulayın veya açıklaması eşleşen bir soru sorun. +- **Codex (OpenAI)**: Codex aynı `SKILL.md` öğesini okur. Paketlenmiş `agents/openai.yaml`, `allow_implicit_invocation: true` öğesini ayarlar, bu nedenle Codex bir görev eşleştiğinde beceriyi otomatik olarak seçer; aksi takdirde `$agenteye-cli` olarak açıkça çağırın. --- -## Güvenlik: değişiklikler bir ajan CLI çalıştırdığında uyarı vermez +## Güvenlik: aracı CLI çalıştırdığında değişiklikler uyarı VERMEZ -> **Uyarı:** Bir ajanın değişiklik yapmasına izin vermeden önce bunu okuyun. +> **Uyarı:** Bir acenteye değişiklik yapmasına izin vermeden önce bunu okuyun. -`agenteye` CLI normalde yıkıcı bir eylemden önce *"emin misiniz?"* sorular. **Hiçbir zaman terminale bağlı olmadığında (tam olarak bir kodlama aracının onu çalıştırma şekli) ve `--json` de atlar onayı, bu onaylamayı otomatik olarak atlayın.** Bu nedenle güvenlik uyarısı ajan için **ateşlenmez**. +`agenteye` CLI normalde yıkıcı bir işlemden önce *"emin misiniz?"* sorar. **Her zaman bir terminale bağlı olmadığında (bu tam olarak bir kodlama acentesinin bunu çalıştırma şeklidir) bu onayı otomatik olarak atlar ve `--json` de atlar.** Bu nedenle güvenlik isteği aracı için **ateşlenmez**. -Beceri bunu telafi etmek için yazılmıştır: çalıştıracağı tam komutu belirtmesi ve herhangi bir durum değişikliğinden önce açık **OK** alması talimatı verilir. Bu disiplini koruyun. Failproof AI Observability'yi bir ajan aracılığıyla kullanırken, *siz* onaylama adımısınız. İzlenecek durum değiştiren komutlar: +Beceri bunu telafi etmek için yazılmıştır: tam olarak çalıştıracağı komutu belirtmesi ve herhangi bir durum değişikliğinden önce açık **Tamam** almanız talimatı verilir. Bu disiplini koruyu. Failproof AI Observability'yi bir aracı aracılığıyla yürüttüğünüzde, *siz* onay adımısınız. İzlenecek durum değiştirici komutlar: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` @@ -107,55 +107,54 @@ Beceri bunu telafi etmek için yazılmıştır: çalıştıracağı tam komutu b - `agent rename` / `delete` - `orgs switch` -**Gözlem** altındaki her şey (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) yalnızca okunur ve hiçbir şeyi değiştirmez. +**Gözlemle** altındaki her şey (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) yalnızca okunur ve hiçbir şeyi değiştirmez. -Ajan **sizin olarak** davrandığı için, yalnızca oturum açmanızın izin verdiği işlemleri yapabilir; izinler **kuruluş başına** çözülür (bkz. [API anahtarları](/tr/agenteye/api-keys)). İzniniz olmayan bir komut, çıkış kodu `5` ile tam izin adı döndürür; bu sayede ajan hata alması yerine tam olarak ne isteyeceğini bir yöneticiden söyleyebilir. +Aracı **siz** olarak hareket ettiğinden, yalnızca oturum açma işleminizin yapmasına izin verdiği şeyleri yapabilir; izinler **kuruluş başına** çözülür (bkz. [API anahtarları](/tr/agenteye/api-keys)). İznin olmadığınız komut, tam izin adıyla çıkış kodu `5` döndürür, bu nedenle aracı hata almak yerine tam olarak ne talebinde bulunacağınızı söyleyebilir. --- -## Ne sorabilirsiniz +## Ne isteyebilirsiniz -İşte gerçek bir gidiş-dönüş; bir okuma, ardından sizin tamam vermesini bekleyen bir değişiklik: +İşte gerçek bir gidiş-dönüş, bir okuma, ardından onayınız için bekleyen bir değişiklik: ```text -siz ▸ Son gün içinde bir şey bozuk mu? +siz ▸ Son gün içinde bir şey bozuk mu? -ajan ▸ Çalıştırılıyor: agenteye --json errors --since 24h --aggregate - Son 24 saat içinde 3 hata türü. En büyüğü TimeoutError - (18 isabet, tamamı checkout-agent üzerinde), ardından RateLimited (5). - TimeoutError için başarısız oturumları görmek ister misiniz? +aracı ▸ Çalışıyor: agenteye --json errors --since 24h --aggregate + Son 24 saatte 3 hata türü. En büyüğü TimeoutError + (18 isabet, hepsi checkout-agent'te), sonra RateLimited (5). + TimeoutError için başarısız oturumları istemiş misiniz? -siz ▸ CI'ye sadece etkinlik gönderebilecek bir anahtar ver. +siz ▸ CI'a yalnızca etkinlik gönderebilen bir anahtar ver. -ajan ▸ Bu bir API anahtarı oluşturur. Çalıştıracağım: - agenteye keys create ci --add events:add - Devam etmeye izin var mı? +aracı ▸ Bu bir API anahtarı oluşturur. Şunu çalıştıracağım: + agenteye keys create ci --add events:add + Devam etmek OK mi? -siz ▸ evet +siz ▸ evet -ajan ▸ Bitti. "ci" anahtarı events:add ile oluşturuldu. - Sır sadece bir kez gösterilir, bu nedenle şimdi kaydedin. - Yeniden yazdıramam. +aracı ▸ Bitti. "ci" anahtarı yalnızca events:add ile oluşturuldu. + Gizli yalnızca bir kez gösterilir, bu nedenle şimdi saklayın. Yeniden yazdıramam. ``` -Beceri her basit İngilizce niyeti doğru `agenteye` komutuna eşler; geçerli değerleri önceden keşfeder (`list `, `whoami`) böylece tahmin etmez ve herhangi bir değişiklikten önce tam komutu belirtir. Daha fazla örnek: +Beceri, her düz dil niyetini doğru `agenteye` komutuna eşler; geçerli değerleri ilk olarak keşfeder (`list `, `whoami`), böylece tahmin etmez ve herhangi bir değişiklikten önce tam komutu belirtir. Daha fazla örnek: -- *"Son gün içinde bir şey bozuk / başarısız mı?"* → `errors --since 24h --aggregate`, sonra bir döküm. +- *"Son 24 saatte bir şey bozuk / başarısız mı?"* → `errors --since 24h --aggregate`, ardından bir döküm. - *"Oturum `run-001` neden başarısız oldu?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *"Bu hafta kalite nasıl gidiyor?"* → `evals --aggregate --since 7d`, sonra düşük puanlamaya dalın. -- *"CI'ye sadece etkinlik gönderebilecek bir anahtar ver."* → `keys create ci --add events:add` (komutu belirtir, sonra oluşturur ve tek seferlik sırrı yakalar). -- *"Kimin erişimi var? Dana'yı salt okunur yap."* → `users list` → `users update dana@… --permission-set read-only` (sizinle onayladıktan sonra). -- *"Açık olayı onayla ve bana ata."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. +- *"Bu hafta kalite nasıl ilerliyor?"* → `evals --aggregate --since 7d`, ardından düşük puanlamış çalıştırmaları deton et. +- *"CI'a yalnızca etkinlik gönderebilen bir anahtar ver."* → `keys create ci --add events:add` (komutu belirtir, ardından oluşturur ve tek seferlik gizliyi yakalar). +- *"Kimlerin erişimi var? Dana'yı salt okunur yap."* → `users list` → `users update dana@… --permission-set read-only` (sizinle onayladıktan sonra). +- *"Tetiklenen olayı onayla ve bana ata."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. -Bunların arkasındaki tam komutlar, bayraklar ve JSON şekilleri için bkz. [CLI](/tr/agenteye/cli) başvurusu ve [Ajanlar için CLI tarifleri](/tr/agenteye/cli-recipes). +Bunların arkasındaki kesin komutlar, bayraklar ve JSON şekilleri için bkz. [CLI](/tr/agenteye/cli) başvurusu ve [aracılar için CLI tarifleri](/tr/agenteye/cli-recipes). --- ## Sonraki adımlar - **[CLI](/tr/agenteye/cli)**: `agenteye` için tam komut ve bayrak başvurusu. -- **[Ajanlar için CLI tarifleri](/tr/agenteye/cli-recipes)**: kopyala-yapıştır `jq` desenleri ve çıkış kodu işleme. -- **[Evaluator ajan becerisi](/tr/agenteye/evaluator-skill)**: kardeş beceri, `agenteye evals` içindeki puanları okuyan puanlayıcıyı kurmak için. -- **[Python SDK ajan becerisi](/tr/agenteye/python-sdk-skill)**: kardeş beceri, `agenteye` nin okuduğu telemetriyi yayması için aracı enstrüman takma için. -- **[AI asistanı](/tr/agenteye/assistant)**: pano içi asistan (bu terminal beceriyle karıştırılmamalıdır). -- **[API anahtarları](/tr/agenteye/api-keys)**: becerinin yapabileceklerini sınırlayan kuruluş başına izin modeli. \ No newline at end of file +- **[Aracılar için CLI tarifleri](/tr/agenteye/cli-recipes)**: kopyala-yapıştır `jq` desenleri ve çıkış kodu işleme. +- **[Evaluator aracı becerisi](/tr/agenteye/evaluator-skill)**: kardeş beceri, `agenteye evals` öğesinin okuduğu puanlayıcıyı oluşturmak için. +- **[Python SDK aracı becerisi](/tr/agenteye/python-sdk-skill)**: kardeş beceri, acenteyi `agenteye` öğesinin okuduğu telemetri yayması için enstrüman etmek için. +- **[AI asistanı](/tr/agenteye/assistant)**: panoda yerleşik asistan (bu terminal becerisinden karıştırılmaması için). +- **[API anahtarları](/tr/agenteye/api-keys)**: becerinin yapabileceğini sınırlandıran kuruluş başına izin modeli. \ No newline at end of file diff --git a/docs/tr/agenteye/cli.mdx b/docs/tr/agenteye/cli.mdx index 58a3586c..1ce925e0 100644 --- a/docs/tr/agenteye/cli.mdx +++ b/docs/tr/agenteye/cli.mdx @@ -1,25 +1,25 @@ --- title: "CLI" -description: "Failproof AI Observability'nin tüm işlevlerini terminalden veya bir betikten yönetin: pano gezintisine gerek yoktur." +description: "Failproof AI Observability'nin tüm özelliklerini terminalden veya bir betikten kullanın: pano ziyaretlerine gerek yok." --- -Failproof AI Observability'nin tüm işlevlerini terminalden veya bir betikten yönetin: pano gezintisine gerek yoktur. `agenteye` CLI'si verilerinizi sorgular (oturumlar, olay günlükleri, değerlendirmeler) ve kuruluşunuzu yönetir (API anahtarları, kullanıcılar, ayarlar, uyarılar, olaylar, kaydedilmiş sorgular), bu nedenle bir denetimi otomatikleştirmek, Gözlenebilirliği CI'ye bağlamak veya bir kodlama ajanına üretim incelemesi yapmasını istediğinizde buraya başvurun. Her komut `--json` bayrağını destekler, bu nedenle hem siz bir istemde hem de bir kodlama ajanı (Claude Code, Cursor) çıkış ayrıştırırken eşit şekilde çalışır. +Failproof AI Observability'nin tüm özelliklerini terminalden veya bir betikten kullanın: pano ziyaretlerine gerek yok. `agenteye` CLI verilerinizi (oturumlar, etkinlik günlükleri, değerlendirmeler) sorgular ve kuruluşunuzu yönetir (API anahtarları, kullanıcılar, ayarlar, uyarılar, olaylar, kaydedilmiş sorgular), bu nedenle bir denetimi otomatikleştirmek, Observability'yi CI'ye entegre etmek veya bir kodlama aracısının üretim ortamını incelemesine olanak vermek istediğinizde kullanın. Her komut `--json` bayrağını destekler, bu nedenle komut isteminizde sizin için veya bir kodlama aracısı (Claude Code, Cursor) sonuçları alıp ayrıştırırken eşit derecede iyi çalışır. Bir tek ikili dosya ile şunları yapabilirsiniz: -- **Verilerinizi okuyun**: `sessions`, `events`, `evals`, `errors` (zamana, ajanaya, ortama, puana göre filtreleyin). +- **Verilerinizi okuyun**: `sessions`, `events`, `evals`, `errors` (zaman, aracı, env, puan ile filtreleyin). - **Kuruluşunuzu yönetin**: `keys`, `users`, `settings`, `alerts`, `incidents`. -- **Analitik çalıştırın**: kaydedilmiş SQL ve geçici sorgu çalıştırıcısı (`query`). -- **AI asistanına sorun**: panoda sohbet ettiğiniz aynı salt-okunur analist (`agent`). +- **Analitik çalıştırın**: kaydedilmiş SQL ve geçici sorgu çalıştırıcı (`query`). +- **AI asistanına sorun**: panoda sohbet ettiğiniz aynı salt okunur analist (`agent`). -> **Not:** Bu `agenteye` CLI'si, toplayıcı daemon'ından (`agenteye-collector`) farklı bir araçtır. CLI panonuzla konuşur; toplayıcı olayları sunucuya gönderir. +> **Not:** Bu `agenteye` CLI'si, toplayıcı daemon'u (`agenteye-collector`) ile farklı bir araçtır. CLI panonuzla konuşur; toplayıcı etkinlikleri sunucuya gönderir. --- ## Hızlı Başlangıç -Hiçbir şeyden ilk sonuca dört satırda ulaşın. CLI'yi panonuza yönlendirin, oturum açın, kim olduğunuzu onaylayın, ardından son günün çalıştırmalarını çekin: +Sıfırdan ilk sonuca dört satırda. CLI'yi panonuza işaret edin, oturum açın, kimliğinizi doğrulayın ve ardından son bir günün çalıştırmalarını çekin: ```bash pipx install agenteye @@ -28,7 +28,7 @@ agenteye whoami agenteye --json sessions --since 24h # one row per agent run, last 24h ``` -Bu son komut en son oturumların bir JSON nesnesi yazdırır (en yeniden itibaren, varsayılan olarak 50 ile sınırlı). Bunu `jq`'ye yönlendirerek dilimleyin veya `--json`'i bırakıp kutulanmış, renklendirilmiş bir tablo alın. Her satır çalıştırmanın durumunu ve varsa bir değerlendirici tarafından puanlandırıldıysa metrik puanlarını (burada kısaltılmış) taşır: +Bu son komut, en son oturumların JSON nesnesini yazdırır (yeniden itibaren, varsayılan olarak 50 ile sınırlı). Bunu `jq`'ye yönlendirerek dilimleme yapın veya düzenli bir tablo için `--json` seçeneğini kaldırın. Her satır çalıştırmanın durumunu ve varsa bir değerlendirici bunu puanlamışsa metrik puanlarını içerir (burada kısaltılmış): ```json { @@ -48,13 +48,13 @@ Bu son komut en son oturumların bir JSON nesnesi yazdırır (en yeniden itibare } ``` -Bu sayfanın geri kalanı her parçayı açıklar: izole ortamda [kurulum](#installation), [oturum açma](#authentication), [yapılandırma](#configuration), her komutun paylaştığı [genel kurallar](#global-options--conventions) ve [tam komut başvurusu](#command-reference). +Bu sayfanın geri kalanı her birini açıklar: [yükleme](#installation) izole ortamda, [oturum açma](#authentication), [yapılandırma](#configuration), her komutun paylaştığı [genel kurallar](#global-options--conventions) ve [tam komut başvurusu](#command-reference). --- -## Kurulum +## Yükleme -CLI, **`agenteye`** adlı genel bir PyPI paketidir. Her zaman kendi bağımlılıklarına sahip olması için bunu izole bir ortamda kurun: +CLI, **`agenteye`** adlı halka açık PyPI paketidir. Her zaman kendi bağımlılıklarına sahip olması için izole bir ortama yükleyin: ```bash pipx install agenteye @@ -62,42 +62,42 @@ pipx install agenteye uv tool install agenteye ``` -Python 3.10+ gerektirir. Yüklü komut **`agenteye`**'dir: +Python 3.10+ gerektirir. Yüklenen komut **`agenteye`** olmaktadır: ```bash agenteye --version agenteye --help ``` -> **Not:** Failproof AI Observability Python SDK de `agenteye` dağıtım adını kullanır. CLI'yi `pipx` veya `uv tool` ile kurulumla (paylaşılan bir virtualenv'e `pip install` yerine) ikisinin çakışmasını önlersiniz. Düz `pip install agenteye` yalnızca SDK aynı ortamda yüklü değilse sorun değildir. +> **Not:** Failproof AI Observability Python SDK de `agenteye` dağıtım adını kullanır. CLI'yi `pipx` veya `uv tool` ile yüklemek (paylaşılan bir virtualenv'e `pip install` yerine) ikisinin çarpışmasını önler. Düz bir `pip install agenteye`, SDK aynı ortamda yüklü değilse iyidir. --- -## Kimlik Doğrulaması +## Kimlik Doğrulama -CLI, **pano** ile e-postayla gönderilen bir kerelik kodla kimlik doğrulaması yapar: +CLI, **pano** ile e-posta gönderilen tek kullanımlık kod kullanılarak kimlik doğrulaması yapar: ```bash agenteye login --email you@example.com # A 6-digit code is emailed to you; paste it at the prompt. ``` -Oturum belirteci `~/.agenteye/cli.json`'de (yalnızca sizin tarafınızdan okunur, mod `0600`) depolanır ve varsayılan olarak 24 saat geçerlidir. Süresi dolduğunda `agenteye login` komutunu tekrar çalıştırın. +Oturum belirteci `~/.agenteye/cli.json` dosyasında saklanır (yalnızca sizde okunabilir, mod `0600`) ve varsayılan olarak 24 saat geçerlidir. Süresi dolduğunda `agenteye login` komutunu yeniden çalıştırın. ```bash agenteye whoami # show the current user, active org, and permissions agenteye logout # revoke the session and clear the stored token ``` -`whoami` hiçbir zaman eksik veya süresi dolmuş oturum hatasını vermez; bunun yerine `logged_in: false` raporlar, bu nedenle bir betik veya ajan kimlik doğrulama durumunu güvenle araştırabilir (pano belirtilen bir temel URL yoksa veya erişilemezse yine de sıfır olmayan çıkabilir). +`whoami` eksik veya süresi dolmuş bir oturumda hiçbir zaman hata vermez; bunun yerine `logged_in: false` bildirir, böylece bir betik veya aracı kimlik doğrulama durumunu güvenli bir şekilde inceleyebilir (temel URL ayarlanmadıysa veya pano erişilemezse hala sıfır olmayan bir çıkış kodu çıkabilir). -**Gereksinimler:** e-postanız panoya oturum açmaya izin verilen (Failproof AI Observability yöneticinize sorun) olmalı ve pano temel URL'sinde erişilebilir olmalıdır (bkz. [Yapılandırma](#configuration)). Bir kod talep eder ve hiçbiri gelmezse, e-postanız muhtemelen henüz pano erişimi için etkinleştirilmemiştir. +**Gereksinimler:** e-postanız pano oturumu açmak için izne sahip olmalıdır (Failproof AI Observability yöneticinize sorun) ve pano temel URL'sinde erişilebilir olmalıdır (bkz. [Yapılandırma](#configuration)). Bir kod talep eder ve hiçbiri gelmezse, e-postanız muhtemelen henüz pano erişimi için etkinleştirilmemiştir. --- -## Kuruluşunuzu Seçme (çok kiracılı) +## Kuruluşunuzu Seçme (çok kiracı) -Hesabınız birden fazla kuruluşa aitse, **oturum açarken** etkin olanı seçin; kaydedilir ve sonraki her komut için kullanılır: +Hesabınız birden fazla kuruluşa aitse, **oturum açma sırasında** etkin olanı seçin; kaydedilir ve daha sonra her komut için kullanılır: ```bash agenteye login --org acme # authenticate and set the active tenant in one step @@ -106,7 +106,7 @@ agenteye orgs switch globex # change the saved default agenteye --org globex sessions # override for a single command ``` -Tam olarak bir kuruluşa aitse otomatik olarak seçilir ve `--org`'yi tamamen görmezden gelebilirsiniz. Çeşitli kuruluşa ait iseniz ve birini seçmezseniz, CLI bunları listeler ve `--org ` ile yeniden çalıştırmanızı ister. Etkin kuruluş her istekte panoya gönderilir ve izinleriniz **kuruluş başına** çözülür; `agenteye whoami` etkin kuruluşu, içindeki izinlerinizi ve tüm üyeliklerinizi gösterir. +Tam olarak bir kuruluşa ait olursanız, otomatik olarak seçilir ve `--org` seçeneğini tamamen göz ardı edebilirsiniz. Birden fazla kuruluşa ait olursanız ve bir tane seçmezseniz, CLI bunları listeler ve `--org ` ile yeniden çalıştırmanızı ister. Etkin kuruluş panoya yapılan her istekte gönderilir ve izinleriniz **kuruluş başına** çözülür; `agenteye whoami` etkin kuruluşu, içindeki izinlerinizi ve tüm üyeliklerinizi gösterir. --- @@ -114,43 +114,43 @@ Tam olarak bir kuruluşa aitse otomatik olarak seçilir ve `--org`'yi tamamen g | Ayar | Bayrak | Ortam değişkeni | Varsayılan | |---|---|---|---| -| Pano temel URL'si | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **gerekli** (varsayılan yok) | -| Etkin kuruluş/kiracı | `--org` | `AGENTEYE_ORG` | oturum açmada seçilir; `~/.agenteye/cli.json`'de kaydedilir | -| Oturum belirteci | `--token` | `AGENTEYE_CLI_TOKEN` | `~/.agenteye/cli.json`'den | -| JSON çıktısı | `--json` | `AGENTEYE_CLI_JSON` | kapalı | -| TLS doğrulamasını atla | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | kapalı (oturum açmada kaydedilir) | -| İstek zaman aşımı (saniye) | `--timeout` | _(yok)_ | 30 | -| Kullanım telemetrisi devre dışı | _(yok)_ | `AGENTEYE_ANALYTICS_DISABLED` (veya `DO_NOT_TRACK`) | telemetri şu anda devre dışı; hiçbir şey gönderilmez | +| Pano temel URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **gerekli** (varsayılan yok) | +| Etkin kuruluş/kiracı | `--org` | `AGENTEYE_ORG` | oturum açmada seçilen; `~/.agenteye/cli.json` dosyasında kaydedilen | +| Oturum belirteci | `--token` | `AGENTEYE_CLI_TOKEN` | `~/.agenteye/cli.json` dosyasından | +| JSON çıkışı | `--json` | `AGENTEYE_CLI_JSON` | kapalı | +| TLS doğrulamasını atla | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | kapalı (oturum açmada kaydedilen) | +| İstek zaman aşımı (saniye) | `--timeout` | _(none)_ | 30 | +| Kullanım telemetrisini devre dışı bırak | _(none)_ | `AGENTEYE_ANALYTICS_DISABLED` (veya `DO_NOT_TRACK`) | telemetri şu anda devre dışı; hiçbir şey gönderilmez | -Çözüm sırası **bayrak → ortam değişkeni → yapılandırma dosyası**'dır. Varsayılan yoktur; CLI'yi panonuza işaret etmelisiniz, komut başına (`--base-url https://agenteye.example.com`) veya ortam üzerinden bir kez (ilk `login`'den sonra kaydedilir): +Çözüm sırası **bayrak → ortam değişkeni → yapılandırma dosyası**. Varsayılan değer yoktur; CLI'yi panonuza işaret etmelisiniz, komut başına (`--base-url https://agenteye.example.com`) veya ortam yoluyla bir kez (ilk `login`'den sonra da kaydedilir): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -Yapılandırma dizini `AGENTEYE_HOME`'u onurlandırır (SDK ve toplayıcı tarafından kullanılan aynı kural); ayarlanırsa, `cli.json` `$AGENTEYE_HOME/cli.json`'de bulunur. +Yapılandırma dizini `AGENTEYE_HOME`'u dikkate alır (SDK ve toplayıcı tarafından kullanılan aynı kural); ayarlanmışsa `cli.json` `$AGENTEYE_HOME/cli.json`'da bulunur. ### Kendi imzalı veya dahili TLS -Panonuz kendi imzalı veya dahili sertifika ile HTTPS üzerinden sunuluyorsa (örneğin, ham yük dengeleyici ana bilgisayar adı), TLS doğrulaması bunu `CERTIFICATE_VERIFY_FAILED` hatası ile reddeder. Sertifika doğrulamasını atlamak için `--insecure` geçirin: +Panonuz kendi imzalı veya dahili bir sertifika ile HTTPS üzerinden sunuluyorsa (örneğin, ham bir yük dengeleyici ana adı), TLS doğrulaması bunu `CERTIFICATE_VERIFY_FAILED` hatası ile reddeder. Sertifika doğrulamasını atlamak için `--insecure` seçeneğini geçin: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` **oturum açarken `cli.json`'de kaydedilir**, bu nedenle sonraki komutlar doğrulamayı otomatik olarak atlar; bayrağı tekrarlamanız gerekmez. Tek seferlik doğrulanmış bir çağrı için `--secure`'ü geçirin veya bir sonraki oturum açmada doğrulamayı geri açmak için kullanın. CLI pano ile iletişim kuran her komuttan önce stderr'e doğrulama devre dışı bırakıldığında bir uyarı yazdırır. Doğrulamayı atlamak, ortadaki adam saldırılarına karşı korumayı kaldırır; panonuza olan ağ yoluna güvenmeden önce buna güvendiğinizden emin olun (VPN, özel alt ağ vb.). +`--insecure` **oturum açarken `cli.json`'a kaydedilir**, bu nedenle daha sonraki komutlar doğrulamayı otomatik olarak atlar; bayrağı tekrarlamanıza gerek yok. Tek seferlik doğrulanmış bir çağrı için `--secure` seçeneğini geçin veya bir sonraki oturum açmada doğrulamayı geri açın. CLI, doğrulama devre dışı bırakılmışken pano ile iletişim kuran herhangi bir komuttan önce stderr'ye bir uyarı yazdırır. Doğrulamayı atlamak ortadaki adam saldırılarına karşı korumayı kaldırır; panonuza olan ağ yoluna (VPN, özel alt ağ, vb.) güvenmeden önce buna dayanmayın. --- ## Telemetri ve Gizlilik -> **Not:** Gönderilen CLI **bugün hiçbir kullanım telemetrisi göndermez.** Ana bir kill switch açık olduğundan ortamınız ne olursa olsun hiçbir şey iletilmez. Aşağıdaki bölüm telemetri hiç etkinleştirilirse çıkış yapma yeteneğini açıklar. +> **Not:** Sevk edilen CLI **bugün hiçbir kullanım telemetrisi göndermiyor.** Ana bir kill anahtarı açık, bu nedenle ortamınız ne olursa olsun hiçbir şey iletilmez. Aşağıdaki bölümde telemetri etkinleştirilirse devre dışı bırakma yeteneği açıklanmaktadır. -Etkinleştirildiğinde bile telemetri **yalnızca anonim kullanım analitikleri** olurdu, asla ajanınız, oturum veya olay verileriniz değil: +Etkin olsa bile, telemetri **yalnızca anonim kullanım analitikleri** olacak, hiçbir zaman aracı, oturum veya etkinlik verileriniz değil: -- **Ajan, oturum veya olay verisi hiçbir zaman altyapınızı bırakmaz.** Yalnızca CLI kullanımı raporlanacaktır: komut ve alt komut adı (örneğin `keys create`), kullandığınız bayrakların **adları** (hiçbir zaman değerleri), başarı/çıkış durumu ve süresi, artı mutasyonlar için eylem başına etkinlik (örneğin `api_key_created`, `query_run`) yalnızca statik adlar/enum ve kaba sayılar taşıyan. Pano URL'niz, oturum belirteci, e-posta, kuruluş slug'ı, kaynak kimlikleri, SQL, anahtar gizli anahtarları ve sorgu filtreleri **asla** gönderilmez. Operatörler yalnızca opak dahili kimlikle tanımlanacak, asla e-postaya göre değil. -- **Zaman içinde önceden çıkış yapın** ortamda `AGENTEYE_ANALYTICS_DISABLED=1` ayarlayarak (CLI de çapraz araç `DO_NOT_TRACK=1` kuralına uyar). Bu telemetri hiç etkinleştirilir etkinleştirilmez devreye girer, bu nedenle gizlilik bilincine sahip bir ortam kalıcı olarak çıkış yapabilir. -- Telemetri etkinleştirilirse, CLI doğrudan PostHog'a gönderecektir (`https://us.i.posthog.com`); o ana bilgisayar bloklanan bir makine sessizce hiçbir şey göndermez ve CLI etkilenmez. +- **Aracı, oturum veya etkinlik verileriniz hiçbir zaman altyapınızdan dışarı çıkmaz.** Yalnızca CLI kullanımı rapor edilir: komut ve alt komut adı (ör. `keys create`), kullandığınız bayrakların **adları** (asla değerleri değil), başarı/çıkış durumu ve süresi, artı mutasyonlar için eylem başına etkinlik (ör. `api_key_created`, `query_run`) yalnızca statik adlar/numaralandırmalar ve kaba sayılar taşıyan. Pano URL'niz, oturum belirteci, e-postanız, kuruluş slugu, kaynak kimlikleri, SQL, anahtar sırları ve sorgu filtreleri **hiçbir zaman** gönderilmez. Operatörler yalnızca opak bir dahili id ile tanımlanır, asla e-posta ile değil. +- **`AGENTEYE_ANALYTICS_DISABLED=1` ortam değişkenini CLI ortamında ayarlayarak önceden devre dışı bırakın** (CLI aynı zamanda araçlar arası `DO_NOT_TRACK=1` kuralını da dikkate alır). Bu, telemetri etkinleştirildiği anda yürürlüğe girer, bu nedenle gizlilik bilincine sahip bir ortam kalıcı olarak devre dışı kalabilir. +- Telemetri etkinleştirilirse, CLI doğrudan PostHog'a (`https://us.i.posthog.com`) gönderecektir; bu ana adres engellenerek bir makine sessizce hiçbir şey göndermez ve CLI etkilenmez. --- @@ -158,35 +158,35 @@ Etkinleştirildiğinde bile telemetri **yalnızca anonim kullanım analitikleri* Bunu bir kez okuyun; her komuta uygulanır. -- **Genel seçenekler komuttan ÖNCE gider.** `agenteye --json sessions` doğrudur; `agenteye sessions --json` bir kullanım hatasıdır. Globaller `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` ve `--no-color`'dir. -- **`--json` saf JSON'u stdout'a ve başka bir şeye yazdırır.** İnsan durum satırları, uyarılar ve hatalar **stderr**'e gider, bu nedenle `--json` stdout yakalaması bir durum satırı gösterildiğinde bile `jq`'ye borulama için temiz kalır. `--json` olmadan insan gözleri için kutulanmış, renklendirilmiş bir görünüm alırsınız. -- **`--help` ile keşfet.** Her komut ve alt komutun `--help` (ve `-h` takma adı) vardır: `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. Üst düzey yardım ayrıca çıkış kodlarını ve genel seçenekleri listeler. Genel makine tarafından okunabilir yüzey dökümü yoktur; komut başına `--help` artı `agenteye query schema` ve `agenteye settings schema` bu iki kayıt defteri için kullanın. -- **Onaylar etkileşimli olmayan ortamlarda otomatik olarak atlanır.** Oluştur/güncelle/sil komutları etkileşimli terminalde "emin misiniz?" ister, ancak **`--json` altında veya stdin bir TTY olmadığında otomatik olarak bu istemi atlar** (TTY etkileşimli bir terminal oturumudur; bir boru veya CI çalıştırıcısı değil), bu nedenle betikler ve ajanlar asla beklemez. Bunu açık olarak atlamak için `--yes`/`-y` geçirin. İstem bir ajan için çalışmayacağından, ajan yıkıcı işlemleri insanla önceden onaylamalıdır. -- **Sayfalandırma:** sonuçlar en yeniden itibaren ve imleç sayfalandırılır (her sayfa sonraki sayfayı getirmek için kullandığınız bir belirteç döndürür). `--limit N` (takma ad `-n`) satırları kapaklar ve **varsayılan olarak 50**; `--all` otomatik sayfalandırır (**200 satırlık parçalarda**) **`--limit`'e kadar**, bu nedenle çıplak `--all` yine 50'de durur. Tam bir tarama için yüksek açık bir kapak geçirin: `--all --limit 1000`. `--page-size N` istek başına parçayı kontrol eder (max 200); `--cursor ` önceki sayfanın `next_cursor`'ından devam eder. -- **Zaman filtreleri:** `--since` göreli bir pencere alır: `15m`, `1h`, `6h`, `24h`, `7d` veya `all` (panonun ön ayarları). Daha uzun veya özel bir aralık için (örneğin son 30 gün), `--from`/`--to`'yu kullanın: açık ISO-8601 UTC zaman damgaları **`T` ve saat dilimi ile** (örneğin `2026-06-01T00:00:00Z`) `--since`'i geçersiz kılır. Boşluk ayrılmış veya saat dilimi olmayan bir değer bir kullanım hatasıdır. -- **`--fields a,b,c`** (`events`, `sessions`, `evals`, `errors` üzerinde) çıktıyı bu anahtarlara kısıtlar, hem tablo hem de `--json` için. Bilinmeyen adlar geçerli liste ile reddedilir, alan adlarını keşfetmek için ucuz bir yol. -- **`--file payload.json`** (veya stdin'i okumak için `--file -`) bir kaynak karmaşık bir şekle sahipse tam bir JSON istek gövdesini sağlar (`alerts create/update`, `settings set` ve `users create/update` üzerinde). Kaydedilmiş sorgu SQL'i bunun yerine `--sql @file.sql` kullanır. -- **Çoklu değer filtreleri** virgülle ayrılır → küme olarak eşleştirilir (bir filtre içinde birleşim, filtreler arasında VE): `--event-type tool_use,tool_result`. Tıklama seçenekleri varyabilir değildir, bu nedenle `--add a b` kopar. `--add a,b` kullanın, bayrağı tekrarlayın (`--add a --add b`) veya alıntı yapın (`--add "a b"`). +- **Genel seçenekler komuttan ÖNCEsine gider.** `agenteye --json sessions` doğru; `agenteye sessions --json` kullanım hatasıdır. Genel seçenekler `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` ve `--no-color` seçenekleridir. +- **`--json` stdout'a saf JSON yazdırır ve başka hiçbir şey yazdırmaz.** İnsan durum satırları, uyarılar ve hatalar **stderr**'e gider, bu nedenle `--json` stdout yaklaması `jq`'ye borulanmış halde temiz kalır, bir durum satırı gösterilse bile. `--json` olmadan, insan gözleri için kutulanmış, renklendirilmiş bir görünüm elde edersiniz. +- **`--help` ile keşfet.** Her komut ve alt komutun `--help` seçeneği (ve `-h` takma adı) vardır: `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. Üst düzey yardım aynı zamanda çıkış kodlarını ve genel seçenekleri de listeler. Genel makine tarafından okunabilir bir yüzey dökümü yoktur; komut başına `--help` kullanın, artı bu iki kayıt için etki alanına özgü `agenteye query schema` ve `agenteye settings schema` seçenekleri. +- **Onaylar betikler ve aracılar için otomatik olarak atlanır.** Oluştur/güncelle/sil komutları etkileşimli bir terminalde "emin misiniz?" isteminde sorulur, ancak **`--json` altında veya stdin TTY olmadığında otomatik olarak bu istemi atlar** (TTY etkileşimli bir terminal oturumudur; bir boru veya CI çalıştırıcısı değildir), bu nedenle betikler ve aracılar asla askıda kalmazlar. Açıkça atlamak için `--yes`/`-y` seçeneğini geçin. Aracı için istem ateşlenmeyeceğinden, bir aracı yıkıcı işlemleri önce insan ile doğrulamalıdır. +- **Sayfalandırma:** sonuçlar yeniye ilk, imleç sayfalandırılmış (her sayfa bir sonraki getirmek için kullandığınız bir belirteç döndürür). `--limit N` (takma ad `-n`) satırları sınırlar ve **varsayılan olarak 50**; `--all` otomatik sayfalandırır (200 satır öbeklerinde) **`--limit`'e kadar**, bu nedenle yalın bir `--all` hala 50'de durur. Tam bir tarama için yüksek bir açık sınır geçin: `--all --limit 1000`. `--page-size N` istekteki öbek boyutunu kontrol eder (maks 200); `--cursor ` bir önceki sayfanın `next_cursor`'undan devam eder. +- **Zaman filtreleri:** `--since` bağıl bir pencere alır: `15m`, `1h`, `6h`, `24h`, `7d` veya `all` (panonun ön ayarları). Daha uzun veya özel bir aralık için (örneğin son 30 gün), `--from`/`--to` seçeneğini kullanın: `T` ve bir saat dilimi (ör. `2026-06-01T00:00:00Z`) ile açık ISO-8601 UTC zaman damgaları `--since` seçeneğini geçersiz kılar. Boşluk ile ayrılmış veya saat dilimi olmayan bir değer kullanım hatasıdır. +- **`--fields a,b,c`** (`events`, `sessions`, `evals`, `errors` üzerinde) çıkışı bu anahtarlarla kısıtlar, hem tablo hem de `--json` için. Bilinmeyen adlar geçerli liste ile reddedilir, alan adlarını keşfetmek için ucuz bir yol. +- **`--file payload.json`** (veya stdin okumak için `--file -`) bir kaynağın karmaşık bir şekle sahip olduğu durumlarda tam bir JSON istek gövdesini sağlar (`alerts create/update`, `settings set` ve `users create/update` üzerinde). Kaydedilmiş sorgu SQL yerine `--sql @file.sql` seçeneğini kullanır. +- **Çok değerli filtreler** virgülle ayrılmış → bir küme olarak eşleştirilir (bir filtre içinde birlik, filtreler arasında AND): `--event-type tool_use,tool_result`. Tıkla seçenekleri varyatik değildir, bu nedenle `--add a b` kırılır. `--add a,b` seçeneğini kullanın, bayrağı tekrarla (`--add a --add b`) veya tırnak alın (`--add "a b"`). --- ## Komut Başvurusu -### Bu 5 komutu en çok kullanacaksınız +### En Çok Kullanacağınız 5 Komut -Çoğu günlük çalışma bir avuç okuma komutu aracılığıyla çalışır. Buradan başlayın, ardından daha fazla yüzeye ihtiyacınız olduğunda aşağıdakine ulaşın: +Günlük çalışmalarının çoğu birkaç okuma komutu aracılığıyla çalışır. Buradan başlayın, ardından ihtiyacınız olduğunda aşağıdaki tam yüzeyi kullanın: | Komut | Ne yaptığı | Deneyin | |---|---|---| -| `sessions` | Ajan çalıştırması başına bir satır: zaman, ortam, ajan, durum, en son puan. | `agenteye --json sessions --since 24h --status error` | +| `sessions` | Aracı çalıştırma başına bir satır: zaman, env, aracı, durum, en son puan. | `agenteye --json sessions --since 24h --status error` | | `events` | Bir çalıştırmanın içindeki ham adım adım izi (yükler için `--full` ekleyin). | `agenteye --json events --session-id run-001 --all` | -| `evals` | Değerlendirme sonuçları ve puanları; `--aggregate` bunları topla. | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | Sadece hata alan olaylar; `--aggregate` türe göre sayımlar için. | `agenteye --json errors --since 24h --aggregate` | -| `list` | Geçerli filtre değerlerini keşfet (ajanlar, ortamlar, modeller, …). | `agenteye list agents` | +| `evals` | Değerlendirme sonuçları ve puanları; `--aggregate` bunları yukarı kaydırır. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | Sadece hatalı etkinlikler; `--aggregate` tür başına sayımlar için. | `agenteye --json errors --since 24h --aggregate` | +| `list` | Geçerli filtre değerlerini keşfet (aracılar, envs, modeller, …). | `agenteye list agents` | -### CLI'nin yapabileceği her şey +### CLI'nin Yapabileceği Herşey -Tam yüzey takip eder. CLI'nin **18 üst düzey komutu** vardır. Tüm okuma komutları `--json` ve yukarıdaki genel seçenekleri kabul eder; herhangi birinin kapsamlı bayrak listesi ve JSON şekli için `agenteye -h` (veya ` -h`) çalıştırın. +Tam yüzey aşağıdadır. CLI'nin **18 üst düzey komutu** vardır. Tüm okuma komutları `--json` ve yukarıdaki genel seçenekleri kabul eder; herhangi birinin ayrıntılı bayrak listesini ve JSON şeklini görmek için `agenteye -h` (veya ` -h`) seçeneğini çalıştırın. ### Kimlik: `login` · `logout` · `whoami` · `orgs` · `version` · `help` @@ -207,9 +207,9 @@ agenteye orgs current # identity card for the active org agenteye orgs perms # your permissions in the active org, grouped by resource ``` -### Gözlem (salt okunur): `events` · `sessions` · `evals` · `errors` · `list` +### Gözlemle (salt okunur): `events` · `sessions` · `evals` · `errors` · `list` -Bunların hiçbiri bir onay gerektirmez. Paylaşılan filtreler: `--session-id`, `--agent-id`, `--env` (**not** `--environment`), ve zaman aralığı (`--since` / `--from` / `--to`). +Bunların hiçbiri onay gerektirmez. Paylaşılan filtreler: `--session-id`, `--agent-id`, `--env` (**not** `--environment`), ve zaman aralığı (`--since` / `--from` / `--to`). ```bash # events (alias: the raw per-step trail), newest first @@ -232,16 +232,16 @@ agenteye --json errors --since 24h --error-type timeout --all --limit 1000 agenteye list envs # also: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (**`evals`** üzerinde, `sessions` değil) tekrarlanabilir ve VE-birleşik; her iki sınır isteğe bağlıdır (`..0.5` ≤ 0.5 anlamında, `0.9..` ≥ 0.9 anlamında). İstek başına 20'ye kadar puan filtresi. `evals --scores-full` **yalnızca insan tablosu için** bir görüntü bayrağıdır; ilk birkaçın yerine her puan çiftini artı `+N` sayısını gösterir. `--json` altında hiçbir etkisi yoktur, bu her zaman tam puan nesnesini döndürür. **Bir oturumu uçtan uca** okumak için olay izini değerlendirmesi ile birleştirin: +**`evals`** (değil `sessions`) üzerinde `--score KEY:MIN..MAX` tekrarlanabilir ve AND-birleşik; her iki sınır da isteğe bağlı (`..0.5` ≤ 0.5 anlamına gelir, `0.9..` ≥ 0.9 anlamına gelir). İstek başına en fazla 20 puan filtresi. `evals --scores-full` **yalnızca insan tablosu için** görüntü bayrağıdır; ilk kaçtan sonra `+N` sayımı yerine her puan çiftini gösterir. `--json` altında etkisi yoktur, bu her zaman tam puan nesnesini döndürür. **Bir oturumun uçtan uca okumak için** etkinlik izini değerlendirmesi ile birleştirin: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' agenteye --json evals --session-id run-001 # its scores + status ``` -### Yönet (izin kapılı): `keys` · `users` · `settings` · `alerts` · `incidents` +### Yönet (izin geçidi): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: API anahtarları. Gizli dizi yerel olarak oluşturulur, sunucuya gönderilir (yalnızca bir karması depolar) ve oluşturma/yeniden oluşturma sırasında **bir kez gösterilir**; o zaman yakala. `--json` ile yalnızca `key` alanında görünür. **Ad** tarafından referans alınır. +**`keys`**: API anahtarları. Gizli dizi yerel olarak oluşturulur, sunucuya gönderilir (sunucu yalnızca bir hash depolar) ve oluştur/yeniden oluştur sırasında **bir kez gösterilir**; o zaman yakala. `--json` altında yalnızca `key` alanında görünür. **Ad** ile başvurulur. ```bash agenteye keys list # active keys first, then revoked @@ -253,9 +253,9 @@ agenteye keys regenerate ci-bot --yes # rotate the secret (the ol agenteye keys disable ci-bot --yes # revoke ``` -İzinler `(permission-set ∪ --add) − --remove` olarak çalışır. Belirteçleri `slug:action` (örneğin `events:read`) veya bir kaynak üzerinde birkaçını genişletmek için `slug:action.action` (`events:read.add` → `events:read`, `events:add`). Ön ayarlar: `read-only`, `standard`, `admin`. İnsan yalnızca izinler (`keys:update`) bir anahtara verilemez. +İzinler `(permission-set ∪ --add) − --remove` olarak çalışır. Belirteçler `slug:action` (ör. `events:read`) veya bir kaynakta birden fazla `slug:action.action` seçeneğini genişletmek içindir (`events:read.add` → `events:read`, `events:add`). Ön ayarlar: `read-only`, `standard`, `admin`. İnsan tarafından yapılabilecek izinler (`keys:update`) bir anahtara verilemez. -**`users`**: kuruluş üyeleri, **e-posta** tarafından referans alınır (UUID kimliği de kabul edilir). +**`users`**: kuruluş üyeleri, **e-posta** ile başvurulur (UUID id de kabul edilir). ```bash agenteye users list [--active-only] @@ -266,7 +266,7 @@ agenteye users disable dev@corp.com --yes # has protected/self guards agenteye users enable dev@corp.com ``` -**`settings`**: sabit bir kayıt defteri (varolan anahtarları okuyup değiştirirsiniz; yenileri oluşturamazsınız). +**`settings`**: sabit bir kayıt (var olan anahtarları okur ve değiştirir; yeni olanlar oluşturamazsınız). ```bash agenteye settings list # key · value · type · updated (secrets masked) @@ -274,7 +274,7 @@ agenteye settings schema # what each key accepts (ty agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: uyarı tanımları, **ad** tarafından referans alınır. `create` konumsal BİR AD artı bayrakları veya `--file` aracılığıyla tam JSON gövdesini alır. +**`alerts`**: uyarı tanımları, **ad** ile başvurulur. `create` konumsal bir NAME artı bayrakları veya `--file` aracılığıyla tam bir JSON gövdesini alır. ```bash agenteye alerts list @@ -285,7 +285,7 @@ agenteye alerts test high-errors --yes # fire a test noti agenteye alerts delete high-errors --yes ``` -**`incidents`**: uyarı olayları, kimlikle referans alınır (kısa kimlikler kabul edilir). `show` tam etkinlik günlüğünü yazdırır; davranmadan önce okuyun. +**`incidents`**: uyarı olayları, id ile başvurulur (kısa id'ler kabul edilir). `show` tam etkinlik günlüğünü yazdırır; hareket etmeden önce okuyun. ```bash agenteye incidents list --state firing # also: acknowledged, resolved @@ -300,9 +300,9 @@ agenteye incidents comment-list ; agenteye incidents comment-delete ; agenteye incidents unsubscribe ; agenteye incidents subscribers ``` -### Analitik ve asistan: `query` · `agent` +### Analitik ve Asistan: `query` · `agent` -**`query`**: analitik deponuza karşı kaydedilmiş SQL artı geçici çalıştırıcı. Kaydedilmiş sorgular **ad** tarafından referans alınır; SQL sunucu tarafı tarafından doğrulanır (SEÇME/İLE yalnızca, deyim zaman aşımı, satır kapakları). +**`query`**: analitik mağazanıza karşı kaydedilmiş SQL artı geçici bir çalıştırıcı. Kaydedilmiş sorgular **ad** ile başvurulur; SQL sunucu tarafında doğrulanır (yalnızca SELECT/WITH, deyim zaman aşımı, satır sınırı). ```bash agenteye query schema [TABLE] # column layout of the analytics views @@ -313,7 +313,7 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: yerleşik **AI asistanı** ile konuşur (panoda sohbet edebileceğiniz aynı salt-okunur analist). Sohbetler kısa bir sohbet kimliğine göre referans alınır (ön ek çözümlenmiş). +**`agent`**: yerleşik **AI asistanı** ile konuşur (panoda sohbet edebileceğiniz aynı salt okunur analist). Sohbetler kısa bir sohbet-id tarafından başvurulur (ön ek çözümlü). ```bash agenteye agent health # is the AI assistant configured/reachable @@ -326,25 +326,25 @@ agenteye agent rename --title "error triage" ; agenteye agent delete --- -## Çıkış kodları +## Çıkış Kodları -| Kod | Anlamı | +| Kod | Anlam | |---|---| | 0 | Başarı | -| 1 | Beklenmeyen hata (örneğin pano 5xx döndürdü) | -| 2 | Kullanım hatası (geçersiz argümanlar, bilinmeyen komut/bayrak, ad çakışması) | -| 3 | Panoya ulaşılamıyor | -| 4 | Oturum açmamış veya süresi dolmuş; `agenteye login` komutunu çalıştırın | -| 5 | Kimlik doğrulaması yapıldı, ancak hesabınız gerekli izne sahip değil (ileti adlandırır) | -| 6 | İstenen kaynak bulunamadı (örneğin bilinmeyen oturum veya olay kimliği) | +| 1 | Beklenmeyen hata (ör. pano 5xx döndürdü) | +| 2 | Kullanım hatası (geçersiz argümanlar, bilinmeyen komut/bayrak, ad çarpışması) | +| 3 | Panoya ulaşılamaz | +| 4 | Oturum açılmamış veya oturum süresi dolmuş; `agenteye login` seçeneğini çalıştırın | +| 5 | Kimlik doğrulandı, ancak hesabınız gerekli izne sahip değil (ileti bunu adlandırır) | +| 6 | İstenen kaynak bulunamadı (ör. bilinmeyen oturum veya olay id'si) | -Bunlar CLI'yi betiklemek için güvenli hale getirir: bir kodlama ajanı yeniden kimlik doğrulama istemek için bir `4`'e veya eksik izni yüzeyle çıkarmak için bir `5`'e dallanabilir. Ajanlar için çıkış kodu işleme desenleri ve JSON çıkış şekilleri için [Ajanlar için CLI Tarifleri](/tr/agenteye/cli-recipes) bölümüne bakın. +Bunlar CLI'yi betiklemek için güvenli kılar: bir kodlama aracısı yeniden kimlik doğrulaması istemek için 4 üzerinde dallanabilir veya eksik izni yüzeye çıkarmak için 5 üzerinde dallanabilir. Çıkış kodu işleme desenleri ve JSON çıkış şekilleri için [Aracılar için CLI Tarifleri](/tr/agenteye/cli-recipes) seçeneğine bakın. --- -## Sonraki adımlar +## Sonraki Adımlar -- **[Ajanlar için CLI Tarifleri](/tr/agenteye/cli-recipes)**: kopyala-yapıştır sorgu desenleri, `jq` tek satırlıkları, `--fields` projeksiyonları, çıkış kodu işleme ve JSON çıkış şekilleri, kodlama ajanları CLI'yi sürüyor için yazılmış. -- **[CLI ajan becerisi](/tr/agenteye/cli-skill)**: bu CLI'yi bir kurulabilir Claude Code / Codex *becerisi* olarak paketleyin ve bir kodlama ajanı düz İngilizce isteklerinden Failproof AI Observability'yi sürsün. -- **[API anahtarları](/tr/agenteye/api-keys)**: `keys create --add …`'ın arkasındaki izin modeli. -- **[AI asistanı](/tr/agenteye/assistant)**: `agent ask`'ın konuştuğu asistanı etkinleştirme. \ No newline at end of file +- **[Aracılar için CLI Tarifleri](/tr/agenteye/cli-recipes)**: copy-paste sorgu desenleri, `jq` tek satırlıkları, `--fields` projeksiyonları, çıkış kodu işleme ve JSON çıkış şekilleri, kodlama aracıları CLI'yi sürüyor. +- **[CLI aracı becerisi](/tr/agenteye/cli-skill)**: bu CLI'yi yüklenebilir Claude Code / Codex *becerisi* olarak paketleyin, böylece bir kodlama aracısı Failproof AI Observability'yi düz İngilizce isteklerden çalıştırır. +- **[API anahtarları](/tr/agenteye/api-keys)**: `keys create --add …`'nin arkasındaki izin modeli. +- **[AI asistanı](/tr/agenteye/assistant)**: `agent ask` ile konuşan asistanı etkinleştirme. \ No newline at end of file diff --git a/docs/tr/agenteye/codex-capture.mdx b/docs/tr/agenteye/codex-capture.mdx index 708eb7c5..f2c94358 100644 --- a/docs/tr/agenteye/codex-capture.mdx +++ b/docs/tr/agenteye/codex-capture.mdx @@ -1,56 +1,56 @@ --- --- -title: "Codex oturum yakalama" -description: "Ekibinizin yerel OpenAI Codex oturumlarını AgentEye'a sıradan oturumlar ve etkinlikler olarak takip edin — Codex'i nasıl çalıştırdıklarında hiçbir değişiklik olmadan." +title: "Codex oturumu yakalama" +description: "Ekibinizin yerel OpenAI Codex oturumlarını AgentEye'a sıradan oturumlar ve etkinlikler olarak yönlendirin — Codex'i çalıştırma şeklinizde hiçbir değişiklik yapmadan." --- -Mühendisleriniz zaten her gün OpenAI Codex kullanıyor. Codex oturum yakalama, bu kodlama oturumlarını AgentEye'a sıradan oturumlar ve etkinlikler olarak getirerek, bunları gözlemlediğiniz diğer her şeyin yanında arayabilir, tekrar oynatabilir ve değerlendirebilirsiniz. [Python SDK](/tr/agenteye/python-sdk) ile tamamlayıcı özelliktedir: SDK yazdığınız ajanları enstrümente ederken, bu özellik ekibinizin zaten yaptığı Codex işini yakalar — çalışma biçiminde hiçbir değişiklik olmadan. +Mühendisleriniz zaten her gün OpenAI Codex'i çalıştırıyorlar. Codex oturumu yakalama, bu kodlama oturumlarını AgentEye'a sıradan oturumlar ve etkinlikler olarak getirir, böylece gözlemlediğiniz diğer her şeyin yanında onları arayabilir, oynatabilir ve değerlendirebilirsiniz. [Python SDK](/tr/agenteye/python-sdk) tamamlayıcısıdır: SDK yazdığınız ajanları enstrüman ederken, bu özellik ekibinizin zaten yaptığı Codex çalışmasını yakalar — Codex'i çalıştırma şeklinizde hiçbir değişiklik olmadan. -Küçük bir arka plan toplayıcısı, Codex'in yerel oturum transkriptlerini yazılırken okur ve AgentEye'a gönderir. Makine başına bir toplayıcı, bir kerede tüm yerel Codex yüzeyini yakalar — yüzey başına kurulum gerekmez. +Küçük bir arka plan toplayıcısı, Codex'in yerel oturum transkripsiyonlarını yazıldıkça okur ve bunları AgentEye'a gönderir. Makine başına bir toplayıcı, tüm yerel Codex arayüzlerini aynı anda yakalar — yüzey başına kurulum yoktur. -Aynı toplayıcı diğer ajanları da yakalar — bkz. [OpenClaw](/tr/agenteye/openclaw-capture) ve [Hermes](/tr/agenteye/hermes-capture). Çalıştırdığınız her birini etkinleştirin; tek bir toplayıcı aynı anda birkaçını yakalayabilir. +Aynı toplayıcı diğer ajanları da yakalar — bkz. [OpenClaw](/tr/agenteye/openclaw-capture) ve [Hermes](/tr/agenteye/hermes-capture). Çalıştırdığınız her birini etkinleştirin; tek bir toplayıcı aynı anda birkaçını yakayabilir. --- -## Neler yakalanır +## Neyi yakalar -**Yerel** olarak çalışan her Codex yüzeyi, diske yazılan aynı oturum transkriptlerini üretir ve toplayıcı bunların tümünü alır: +**Yerel olarak** çalışan her Codex arayüzü aynı diske yazılı oturum transkripsiyonlarını üretir ve toplayıcı hepsi tarafından bulunur: - Codex **CLI** ve `codex exec` - **VS Code / IDE uzantısı** -- **masaüstü uygulaması**, yerel olarak oturum çalıştırdığında +- **masaüstü uygulaması**, yerel olarak bir oturum çalıştırdığında -Her Codex oturumu bir AgentEye [oturum](/tr/agenteye/sessions) haline gelir; kullanıcı ve asistan mesajları, akıl yürütme, araç çağrıları, araç sonuçları ve token kullanımı eşleşen [etkinlik](/tr/agenteye/event-stream) olur. Her oturumun geldiği yüzey (CLI, IDE veya masaüstü) kaydedilir, böylece bunları ayırt edebilirsiniz. +Her Codex oturumu bir AgentEye [oturumu](/tr/agenteye/sessions) haline gelir; kullanıcı ve asistan mesajları, akıl yürütme, araç çağrıları, araç sonuçları ve token kullanımı eşleşen [etkinliklere](/tr/agenteye/event-stream) dönüşür. Her oturumun geldiği arayüz (CLI, IDE veya masaüstü) kaydedilir, böylece bunları ayırt edebilirsiniz. -> **Bulut oturumları yakalanmaz.** Masaüstü uygulaması giderek daha fazla oturumu Codex bulutunda çalıştırır ve makinede yalnızca meta verilerini tutarken — okunacak yerel transkript yoktur. Yalnızca yerel olarak yürütülen oturumlar yakalanır. +> **Bulut oturumları yakalanmaz.** Masaüstü uygulaması giderek daha fazla oturumu Codex bulutunda çalıştırır ve makinede yalnızca bunların meta verilerini tutar — okunacak yerel bir transkripsiyon yoktur. Yalnızca yerel olarak yürütülen oturumlar yakalanır. --- ## Etkinleştirme -Yakalama, etkinleştirene kadar kapalıdır. Toplayıcıyı `events:add` izni olan bir API anahtarıyla kurun (bkz. [API anahtarları](/tr/agenteye/api-keys)) ve Codex yakalamayı etkinleştirin: +Siz etkinleştirene kadar yakalama kapalıdır. Toplayıcıyı `events:add` izni olan bir API anahtarı ile yükleyin (bkz. [API anahtarları](/tr/agenteye/api-keys)) ve Codex yakalamayı açın: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -Bu toplayıcıyı kurar, arka plan hizmeti olarak kaydeder ve yakalamaya başlar. Çalıştığını doğrulayın: +Bu, toplayıcıyı yükler, onu bir arka plan hizmeti olarak kaydeder ve yakalamayı başlatır. Çalıştığını doğrulayın: ```bash agenteye-collector health ``` -İlk çalıştırmada, mevcut Codex oturumlarınız bir kez geri doldurulur ve yeni etkinlik birkaç saniye içinde akışa başlar. Codex'in kendi dosyaları yalnızca okunur — asla değiştirilmez, taşınmaz veya silinmez — ve her oturum, yeniden başlatmalar arasında bile tam olarak bir kez gönderilir. +İlk çalıştırmada, mevcut Codex oturumlarınız bir kez geri doldurulur ve yeni etkinlik daha sonra saniyeler içinde akışa başlar. Codex'in kendi dosyaları yalnızca okunur — hiçbir zaman değiştirilmez, taşınmaz veya silinmez — ve her oturum, yeniden başlatmalar arasında bile tam olarak bir kez gönderilir. --- -## Nerede görüntülenir +## Nerede görünür -Yakalanan oturumlar **Oturumlar**'da ve etkinlikleri **Etkinlik** akışında görüntülenir, gözlemlediğiniz diğer herhangi bir ajan gibi — bu nedenle [oturum tekrar oynatma](/tr/agenteye/sessions), [arama](/tr/agenteye/queries), [değerlendirmeler](/tr/agenteye/evaluations) ve [uyarılar](/tr/agenteye/alerts) tümü bunlar üzerinde çalışır. Codex ajanına göre filtreleyerek bunları tek başına görün. +Yakalanan oturumlar **Oturumlar**'da ve bunların etkinlikleri **Etkinlikler** akışında görünür, gözlemlediğiniz diğer herhangi bir ajan gibi — böylece [oturum oynatması](/tr/agenteye/sessions), [arama](/tr/agenteye/queries), [değerlendirmeler](/tr/agenteye/evaluations) ve [uyarılar](/tr/agenteye/alerts) bunlar üzerinde çalışır. Sadece bunları görmek için Codex ajanına göre filtreleyin. --- ## Gizlilik -Codex transkriptleri tam oturumu içerir — komut çıktısı, dosya içeriği ve Codex'in okuduğu veya yazdığı her şey dahil — ve sırlar içerebilir. Yakalanan oturumlar olduğu gibi gönderilir, bu nedenle yakalamayı yalnızca bu içeriği AgentEye'da merkezi hale getirmenin uygun olduğu makinelerde ve takımlar için etkinleştirin ve toplayıcıya yalnızca `events:add` kapsamında bir anahtar verin. Verilerinizin nasıl yalıtılı tutulduğu hakkında [Güvenlik](/tr/agenteye/security) bölümüne bakın. \ No newline at end of file +Codex transkripsiyonları tam oturumu içerir — komut çıktısı, dosya içeriği ve Codex'in okuduğu veya yazdığı her şey dahil — ve sırlar içerebilir. Yakalanan oturumlar olduğu gibi gönderilir, bu nedenle yakalamayı yalnızca bu içeriği AgentEye'da merkezileştirmenin uygun olduğu makinelerde ve takımlar için etkinleştirin ve toplayıcıya yalnızca `events:add` kapsamına sahip bir anahtar verin. Verilerinizin nasıl izole tutulduğu hakkında bkz. [Güvenlik](/tr/agenteye/security). \ No newline at end of file diff --git a/docs/tr/agenteye/concepts.mdx b/docs/tr/agenteye/concepts.mdx index 3d7dec42..286930b3 100644 --- a/docs/tr/agenteye/concepts.mdx +++ b/docs/tr/agenteye/concepts.mdx @@ -1,87 +1,87 @@ --- title: "Kavramlar" -description: "Failproof AI Observability'nin sözlüğü — etkinlikler, oturumlar, değerlendirmeler, denetimler, bulgular ve olaylar — tek bir yerde tanımlanmıştır." +description: "Failproof AI Observability'nin arkasındaki sözlük — olaylar, oturumlar, değerlendirmeler, denetimler, bulgular ve olaylar — bir yerde tanımlanmıştır." --- -Bu sayfa, Failproof AI Observability'nin kullandığı sözlüğü tanımlar. Diğer bir kılavuzda karşılaştığınız bir terim yabancı geliyorsa, burada tanımlanmıştır. Bunu baştan sona okumanız gerekmez: göz atın veya anlamını netleştirmek istediğiniz bir kelimeye ulaştığında geri dönün. +Bu sayfa Failproof AI Observability'nin kullandığı sözlüğü tanımlar. Başka bir kılavuzda karşılaştığınız bir terim tanınmıyorsa, burada tanımlanmıştır. Baştan sona okumanız gerekmez: hızlıca göz atın veya anlamını öğrenmek istediğiniz bir kelimeyi gördüğünüzde geri dönün. --- ## Veri modeli -**Etkinlik** -En küçük veri birimi. Bir etkinlik, aracınızın attığı tek bir adımı kaydeder: bir `tool_use`, bir `model_request`, bir `hook_completed`, bir `error` vb. Aracınız etkinlikleri [Python SDK](/tr/agenteye/python-sdk) aracılığıyla yayar; bunlar **Events** sayfasında canlı olarak görünür. +**Olay (Event)** +Verilerin en küçük birimi. Bir olay, ajanınızın attığı tek bir adımı kaydeder: `tool_use`, `model_request`, `hook_completed`, `error` vb. Ajanınız [Python SDK](/tr/agenteye/python-sdk) aracılığıyla olaylar yayar; **Olaylar** sayfasında canlı olarak görülür. -**Oturum** -Bir aracı çalıştırması, `session_id` ile tanımlanır. Bir oturum, bu kimliği paylaşan tüm etkinliklerin **Sessions** sayfasında tek bir satırda toplandığı ve ayrıntı sayfasında bir yürütme grafiği olarak çizildiği haldir. Bir oturum genellikle `agent_start` ile başlar ve `agent_end` ile biter. +**Oturum (Session)** +Bir ajanda çalıştırılması, `session_id` ile tanımlanır. Bir oturum, bu kimliği paylaşan tüm olaylardan oluşur; **Oturumlar** sayfasında tek bir satıra toplanır ve ayrıntı sayfasında yürütme grafiği olarak çizilir. Bir oturum genellikle `agent_start` ile başlar ve `agent_end` ile biter. -**Aracı** -Bir çalıştırma içindeki `agent_id` ile tanımlanan adlandırılmış bir aktör. Bir çalıştırma birkaç aracı içerebilir: örneğin, bir özet aracı oluşturan bir planlayıcı. Alt aracılar bir `parent_id` taşır; bu, Failproof AI Observability'nin yürütme grafiğinde onları kendi şeritlerinde çizmesini sağlayan şeydir. +**Ajan (Agent)** +Bir çalıştırma içinde adlandırılmış bir aktör, `agent_id` ile tanımlanır. Bir çalıştırma birkaç ajanı içerebilir: örneğin, bir özetleyici alt-ajanı oluşturan bir planlayıcı. Alt-ajanlar `parent_id` taşır; bu, Failproof AI Observability'nin onları yürütme grafiğinde kendi şeritlerde çizmesine izin verir. -**Ortam** -Çalıştırmanın nerede gerçekleştiğini gösteren bir etiket: `production`, `staging`, `dev`. SDK'yı yapılandırırken bunu bir kez ayarlarsınız. Hemen hemen her pano sayfası ortama göre filtreleyebilir. +**Ortam (Environment)** +Çalıştırmanın gerçekleştiği yer için bir etiket: `production`, `staging`, `dev`. SDK'yı yapılandırırken bir kez ayarlarsınız. Neredeyse her pano sayfası ortama göre filtreleme yapabilir. -**Bağlam penceresi doldurma** -Bir modelin bağlam penceresinin bir yanıt tarafından tüketilen yüzdesi. Failproof AI Observability bunu tanıdığı modellerde `model_response` etkinliklerine damgalar, bu sayede istem büyümesi ve yaklaşan sıkıştırma doğrudan etkinlik akışında görünür. +**İçerik penceresi doldurması (Context-window fill)** +Bir modelin içerik penceresinin bir yanıtın tükettiği yüzde. Failproof AI Observability bunu tanıdığı modeller için `model_response` olaylarına damgalar, böylece istem büyümesi ve yaklaşan sıkıştırma doğrudan olay akışında görünür hale gelir. --- ## Kalite -**Değerlendirme** -Çalıştırdığınız bir puanlama hizmeti tarafından üretilen bitmişs oturum için bir kalite puanı. Değerlendirmeler isteğe bağlıdır: bir değerlendiriciye bağlanana kadar oturumlar kaydedilir ancak puanlanmaz. Her değerlendirme birkaç adlandırılmış puan taşıyabilir (örneğin `helpfulness`, `factuality`, `tool_efficiency`), her biri kısa bir gerekçe notu ile. Bkz. [Evaluation suite](/tr/agenteye/evaluation-suite). +**Değerlendirme (Evaluation)** +Çalıştırdığınız bir puanlama hizmetinin ürettiği, bitmiş bir oturum için kalite puanı. Değerlendirmeler isteğe bağlıdır: bir değerlendirici bağlanıncaya kadar oturumlar kaydedilir ancak puanlanmaz. Her değerlendirme birkaç adlandırılmış puan içerebilir (örneğin `helpfulness`, `factuality`, `tool_efficiency`), her birinin kısa bir akıl yürütme notu vardır. Bkz. [Değerlendirme paketi](/tr/agenteye/evaluation-suite). -**Puan anahtarı** -Değerlendirici tarafından bildirilen bir boyutun adı, örneğin `helpfulness`. Uyarılar ve denetimler belirli bir puan anahtarını zaman içinde izleyebilir. +**Puan anahtarı (Score key)** +Bir değerlendirmenin bildirdiği tek bir boyutun adı, `helpfulness` gibi. Uyarılar ve denetimler zaman içinde belirli bir puan anahtarını izleyebilir. -**Değerlendiricisi** -Puanlama hizmetiniz. Failproof AI Observability, bitmişs bir çalıştırmanın transkriptini ona POST eder ve döndürdüğü puanları depolar. Varsayılan bir değerlendiricisi göndermiyor; puanlama mantığı sizindir. +**Değerlendirici (Evaluator)** +Puanlama hizmetiniz. Failproof AI Observability, bitmiş bir çalıştırmanın transkriptini buna POST yapar ve döndürdüğü puanları depolar. Varsayılan bir değerlendirici göndermez; puanlama mantığı sizinkidir. --- ## Başarısızlıkları bulma ve düzeltme -**Hook** -Aracı çerçevesinin bir adımın etrafında çalıştırdığı bir koruma veya yan etki: içerik güvenliği kontrolü, KŞV redaksiyonu, bütçe koruması. Hook'lar `hook_triggered` / `hook_completed` etkinlikleri bir `outcome` (allow, deny, modify) ile yayar ve kendi gözlem sayfasını alırlar. +**Kanca (Hook)** +Ajan çerçevenizin bir adım etrafında çalıştırdığı bir koruma veya yan etki: içerik güvenliği kontrolü, KYT redaksiyonu, bütçe koruması. Kancalar `hook_triggered` / `hook_completed` olaylarını bir `outcome` (`allow`, `deny`, `modify`) ile yayar ve gözlemlenecek sayfasını alırlar. -**Uyarı kuralı** -Bir metrik ayarladığınız eşiği aştığında ateşlenen bir kural: hata oranı, p95 gecikme, token maliyeti veya bir değerlendiricisi puanı. Bir kural ateşlendiğinde, bir olay açar ve seçtiğiniz kanallara (e-posta, Slack, webhook, pano içi) bildirir. Bkz. [Alerts](/tr/agenteye/alerts). +**Uyarı kuralı (Alert rule)** +Bir metrik belirlediğiniz bir eşiği aştığında harekete geçen kural: hata oranı, p95 gecikme süresi, token maliyeti veya bir değerlendirici puanı. Kural harekete geçtiğinde, bir olayı açar ve seçtiğiniz kanallara (e-posta, Slack, webhook, pano içi) bildirim gönderir. Bkz. [Uyarılar](/tr/agenteye/alerts). -**Olay** -Bir uyarı kuralı ateşlendiğinde açılan açık bir sorun. Olayların bir yaşam döngüsü (kabullenme, atama, çözme) ve her eylemi kaydeden bir etkinlik zaman çizelgesi vardır. Ayrıca manuel olarak da açabilirsiniz. +**Olay (Incident)** +Bir uyarı kuralı harekete geçtiğinde oluşturulan açık bir sorun. Olayların bir yaşam döngüsü (kabul etme, atama, çözme) ve her işlemi kaydeden bir aktivite zaman çizelgesi vardır. Ayrıca el ile bir tane açabilirsiniz. -**Denetim** -Henüz bir kural yazmadığınız hata kalıpları için oturumlar *arasında* günlükleri inceleyen yinelenen bir araştırma (saatlik ila haftalık): hata kümeleri, düşük puanlar, gecikme aykırı değerleri, araç çağrısı döngüleri ve hiç bitmemiş çalıştırmalar. Bir uyarı zaten hakkında bildiğiniz bir metriği izlerken, denetim sonra neye bakmanız gerektiğini söyler. Bkz. [Audits](/tr/agenteye/audits). +**Denetim (Audit)** +Yazmadığınız başarısızlık desenleri için günlüklerinizi oturumlar *arasında* madenciliği yapan yinelenen bir araştırma (saatlik ila haftalık): hata kümeleri, düşük puanlar, gecikme süresi aykırı değerleri, araç çağrı döngüleri ve hiçbir zaman bitmeyen çalıştırmalar. Bir uyarı zaten bildiğiniz bir metriği izlerken, bir denetim size daha sonra neye bakmanız gerektiğini söyler. Bkz. [Denetimler](/tr/agenteye/audits). -**Bulgu** -Bir denetim çalıştırmasından sıralanmış, kanıtla desteklenmiş bir sonuç. Bir bulgu bir kalıp adlandırır, arkasındaki tam oturumları bağlar ve triyaj yaşam döngüsü (kabullenme, çözme, sessiz yapma, reddetme) taşır. Failproof AI Observability, bulgularını çalıştırmadan çalıştırmaya yineleme ortadan kaldırır, böylece bilinen bir kalıp birikirmek yerine güncellenir. +**Bulgu (Finding)** +Bir denetim çalıştırmasından sıralanmış, kanıtla desteklenen bir sonuç. Bir bulgu bir deseni adlandırır, arkasındaki tam oturumlara bağlantı verir ve bir sınıflama yaşam döngüsü (kabul etme, çözme, sessiz tutma, reddetme) taşır. Failproof AI Observability, çalıştırmaları tekrarlamadan bulguları çoğalması yerine bilinen bir desen güncellemeleri için devreye alır. -**AI asistanı** -Aracılarınız hakkında sorulara düz İngilizce olarak, kendi verileriniz üzerinde cevap veren pano içi sohbet. Varsayılan olarak salt okunurdur; oluşturduğu herhangi bir şey (kaydedilen sorgu, pano) onay kapısından geçer ve asla silemez. Bkz. [AI assistant](/tr/agenteye/assistant). +**AI asistanı (The AI assistant)** +Ajanlarınız hakkında sorulara kendi verilerinizin üzerinden düz İngilizce olarak cevap veren pano içi sohbet. Varsayılan olarak salt okunurdur; oluşturduğu her şey (kaydedilmiş bir sorgu, pano) onay geçitlidir ve hiçbir zaman silemez. Bkz. [AI asistanı](/tr/agenteye/assistant). --- ## Çalıştırma -**Kuruluş (kiracı)** -Yalıtılmış bir çalışma alanı. Bir Failproof AI Observability örneği birçok kuruluşu barındırabilir, her biri kendi kullanıcıları, anahtarları ve verileri ile. Her pano URL'si kuruluş slug'ınızın altında kapsamlıdır (`//…`). +**Kuruluş (kiracı) (Organization (tenant))** +Yalıtılmış bir çalışma alanı. Bir Failproof AI Observability örneği birçok kuruluşu barındırabilir; her birinin kendi kullanıcıları, anahtarları ve verileri vardır. Her pano URL'si kuruluş slug'ınız (`//…`) altında kapsam içindedir. -**Toplayıcı** -`agenteye-collector`, her aracı makinesinde çalışan, SDK'nın diske yazdığı etkinlikleri toplu hale getiren ve sunucuya gönderen hafif daemon. +**Toplayıcı (Collector)** +`agenteye-collector`, her ajan makinesinde çalışan, SDK'nın diske yazdığı olayları toplu olarak alan ve sunucuya gönderen hafif daemon. -**API anahtarı** -Bir istemciyi sunucuya karşı kimlik doğrulayan kapsamlı bir belirteç. Anahtarlar granüler izinler taşır (örneğin toplayıcı için `events:add`, pano anahtarı için salt okunur kapsamlar). Bkz. [API keys](/tr/agenteye/api-keys). +**API anahtarı (API key)** +İstemciyi sunucuda doğrulayan kapsamlı bir token. Anahtarlar granüler izinler taşır (örneğin toplayıcı için `events:add`, pano anahtarı için salt okunur kapsamlar). Bkz. [API anahtarları](/tr/agenteye/api-keys). -**Sunucu** -Alım ve API hizmeti. Etkinlikleri alır, operasyonel durumu veritabanlarınızda depolar ve panoyu ve CLI'yi sunar. +**Sunucu (Server)** +Alım ve API hizmeti. Olayları alır, işletimsel durumu veritabanlarınızda depolar ve pano ve CLI'yi hizmet eder. -**Pano** -Web kullanıcı arabirimi. Her sayfa bir kuruluşun kapsamında ve sunucunun API'si aracılığıyla okunur. +**Pano (Dashboard)** +Web kullanıcı arayüzü. Her sayfa bir kuruluşa kapsam içindedir ve sunucunun API'si aracılığıyla okunur. --- ## Sonraki adımlar -- [Overview](/tr/agenteye/overview): bu parçaların nasıl birbirine uyduğu. -- [Observability](/tr/agenteye/observability): gözlem yüzeyleri (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file +- [Genel Bakış](/tr/agenteye/overview): bu parçaların nasıl bir araya geldiği. +- [Gözlemlenebilirlik](/tr/agenteye/observability): gözlem yüzeyleri (Olaylar, Oturumlar, Modeller, Araçlar, Kancalar, Hatalar). \ No newline at end of file diff --git a/docs/tr/agenteye/dashboards.mdx b/docs/tr/agenteye/dashboards.mdx index 420e4855..efe7e96a 100644 --- a/docs/tr/agenteye/dashboards.mdx +++ b/docs/tr/agenteye/dashboards.mdx @@ -3,44 +3,43 @@ title: "Panolar" description: "Canlı aracı verilerinizi tüm ekibinizin izlediği tek bir görüntüye dönüştürün." --- +Canlı aracı verilerinizi tüm ekibinizin izlediği tek bir görüntüye dönüştürün. Önemli sorguları grafikler olarak sabitleyin ve herkes tek bir bakışta aynı verileri görsün, hiçbir sorguyu yeniden çalıştırmadan. -Canlı aracı verilerinizi tüm ekibinizin izlediği tek bir görüntüye dönüştürün. Önemli sorgularını grafikler olarak sabitleyin ve herkes bir bakışta aynı sayıları görür—hiç bir sorguyu yeniden çalıştırmaya gerek kalmaz. +![Kaydedilmiş sorgulardan oluşturulmuş bir pano: saatlik olaylar çizgisi, tür başına hatalar çubuğu, gecikme alan grafiği ve modele göre jetonlar](/agenteye/images/dashboard-fleet.png) -![Kaydedilmiş sorgulardan oluşturulmuş bir pano: saatlik olayların satırı, türe göre hatalar çubuğu, gecikme alan grafiği ve modele göre tokenler](/agenteye/images/dashboard-fleet.png) - -*Bir pano, dört kaydedilmiş sorgu: saatlik olaylar, türe göre hatalar, gecikme ve modele göre tokenler.* +*Bir pano, dört kaydedilmiş sorgu: saatlik olaylar, tür başına hatalar, gecikme ve modele göre jetonlar.* ## Herkes aynı gerçeği görür -Ekran görüntülerini sohbete yapıştırmayı ve aynı sorguyu günde beş kez çalıştırmayı bırakın. Pano, ekibinizdeki herkesin tam olarak aynı görünümü açabileceği paylaşılan, kuruluş genelinde bir tahta olur. Alttaki veriler değiştiğinde, grafikler bununla birlikte hareket eder, bu nedenle pano her zaman günceldir ve kimse eski sayılar üzerinde tartışmaz. +Ekran görüntülerini sohbete yapıştırmayı bırakın ve aynı sorguyu günde beş kez çalıştırmayı bırakın. Pano, ekibinizdeki herkesin tam olarak aynı görünümü açabileceği paylaşılan, kuruluş çapında bir tahtadır. Altta yatan veriler değiştiğinde, grafikler de onunla birlikte hareket eder, bu nedenle pano her zaman güncel kalır ve kimse eski numaralar üzerine tartışmaz. -Yukarıdaki filo panosu günlük işlemler için iyi bir başlangıç şeklidir: +Yukarıdaki filo panosu günlük operasyonlar için iyi bir başlangıç şeklidir: -- bir **saatlik olayları** satırı, böylece verimliliği izleyebilir ve ani bir düşüşü yakalayabilirsiniz -- bir **türe göre hatalar** çubuğu, böylece en büyük başarısızlık kategorileriniz hemen göze çarpar -- bir **gecikme** alan grafiği, böylece yavaşlamalar kullanıcılar şikayetçi olmadan görülür -- bir **modele göre tokenler** dökümü, böylece maliyet göz önünde tutulur +- bir **saatlik olaylar** çizgisi, böylece aktarım hızını izleyebilir ve ani bir düşüşü yakalayabilirsiniz +- bir **tür başına hatalar** çubuğu, böylece en büyük hata kategorileriniz öne çıkar +- bir **gecikme** alan grafiği, böylece yavaşlamalar kullanıcılar şikayet etmeden ortaya çıkar +- bir **modele göre jetonlar** dökümü, böylece maliyet görüş alanında kalır -Panolarınızı `//dashboards` adresinde bulacaksınız. +Panolarınızı `//dashboards` adresinde bulabilirsiniz. ## Zaten kaydettiğiniz sorguları sabitleyin -Her karo kaydedilmiş bir sorguyla başlar. [Sorguları](/tr/agenteye/queries) kütüphanesinde (yerleşik ön ayarlar artı kendi öğeleriniz, olaylarınız ve değerlendirmeleriniz üzerinde) önemsediğiniz sorguyu oluşturun ve kaydedin, ardından bunu veriye uygun grafik olarak bir panoya sabitleyin: trend için bir **satır**, kategorileri karşılaştırmak için bir **çubuk**, hacim için bir **alan** veya hisse dökümü için bir **pasta**. +Her karo kaydedilmiş bir sorgudan başlar. [Sorguları](/tr/agenteye/queries) kütüphanesinde önemsediğiniz sorguyu derleyin ve kaydedin (yerleşik ön ayarlar artı sizin kendi ön ayarlarınız, olaylarınız ve değerlendirmeleriniz üzerinde), ardından bunu veriye uygun grafik olarak bir panoya sabitleyin: trend görmek için **çizgi**, kategorileri karşılaştırmak için **çubuk**, hacmi göstermek için **alan** veya paylaşım dökümü için **pasta**. -Bir karo sadece kaydedilmiş sorgunuz grafik olarak gösterildiğinden, elimiz tarafından senkronizasyonda tutulacak bir şey yoktur. Sorguyu bir kez güncelleyin ve onu kullanan her pano da güncellenir. +Bir karo yalnızca kaydedilmiş sorgunuzun grafik olarak gösterilmesi olduğundan, elle senkronize tutacak hiçbir şey yoktur. Sorguyu bir kez güncelleyin ve onu kullanan her pano da güncellenir. -## Sadece hacmi değil, kaliteyi izleyin +## Hacim değil, kaliteyi izleyin -Hacim, aracıların meşgul olduğunu gösterir. Kalite, aslında işi yaptıklarını gösterir. Bir panoları [değerlendirme puanlarınıza](/tr/agenteye/evaluations) yönlendirin ve zamanla çalıştırmaların ne kadar iyi gittiğini izleyen bir pano alırsınız, bu nedenle kalite gerilemeleri bir müşteriden sürpriz yerine bir grafikte düşüş olarak görülür. +Hacim aracıların meşgul olduğunu söyler. Kalite aslında işi yaptıklarını söyler. Bir panoya [değerlendirme puanlarınızı](/tr/agenteye/evaluations) yönlendirin ve çalıştırmaların zaman içinde ne kadar iyi gidiş gösterdiğini izleyen bir pano elde edersiniz, böylece bir kalite gerilemeleri müşteriden gelen bir sürpriz yerine bir grafikteki düşüş olarak ortaya çıkar. -![Kaydedilmiş değerlendirme sorgularından oluşturulmuş, kaliteye odaklanan bir pano](/agenteye/images/dashboard-quality.png) +![Kaydedilmiş değerlendirme sorgularından oluşturulmuş kaliteye odaklı pano](/agenteye/images/dashboard-quality.png) -*Bir kalite panosu, değerlendirme puanlarınızı ön plana ve merkeze alır, işletimsel sayıların hemen yanında.* +*Bir kalite panosu, değerlendirme puanlarınızı ön planda ve merkezi konumda tutar, operasyonel numaralarının hemen yanında.* -Operasyon panolarını ve kalite panolarını yan yana tutun ve ekibinizin "çalışıyor mu?" ve "iyi mi?" soruların her ikisine de cevap vermek için bir yeri vardır, hiç kimse bir sorguyu yeniden çalıştırmaz. +Bir operasyon panosu ve bir kalite panosu yan yana tutun ve ekibinizin her ikisini de "çalışıyor mu?" ve "iyi mi?" sorularını cevaplamak için tek bir yeri vardır, kimse bir sorguyu yeniden çalıştırmaz. -## İlgili +## İlişkili -- [Sorgular](/tr/agenteye/queries): karolar haline gelen sorguları oluşturun ve kaydedin. -- [Değerlendirmeler](/tr/agenteye/evaluations): zamanla kaliteyi grafiklendirmek için çalıştırmalarınız puanlayın. -- [Uyarılar](/tr/agenteye/alerts): bu ölçümlerden herhangi birine bir eşik dönüştürün. \ No newline at end of file +- [Sorgular](/tr/agenteye/queries): karolanız haline gelen sorguları derleyin ve kaydedin. +- [Değerlendirmeler](/tr/agenteye/evaluations): zaman içinde kaliteyi grafikleyebilmek için çalıştırmalarınızı puanlayın. +- [Uyarılar](/tr/agenteye/alerts): bu ölçümlerden herhangi birindeki eşiği bir sayfaya çevirin. \ No newline at end of file diff --git a/docs/tr/agenteye/error-tracking.mdx b/docs/tr/agenteye/error-tracking.mdx index 480a46ef..fa0cfc34 100644 --- a/docs/tr/agenteye/error-tracking.mdx +++ b/docs/tr/agenteye/error-tracking.mdx @@ -1,41 +1,41 @@ --- title: "Hata İzleme" -description: "Aracılarınızın ürettiği her hatayı tek bir yerde görün, gruplandırılmış şekilde bir kümede oluşan hatalar tek bir sorun olarak görüntülensin." +description: "Ajanlarınızın ürettiği her hatayı tek bir yerde görün; gürültülü patlamalar tek bir sorun olarak gruplandırılır." --- -Aracılarınızın ürettiği her hatayı tek bir yerde görün, gruplandırılmış şekilde bir kümede oluşan hatalar tek bir sorun olarak görüntülensin. Canlı bir akışta kaymadan "bir şey kırmızı" durumundan hatasına neden olan tam çalışmaya kadar tek tıklamayla ulaşırsınız. +Ajanlarınızın ürettiği her hatayı tek bir yerde görün; gürültülü patlamalar tek bir sorun olarak gruplandırılır. "Bir şey kırmızı" durumundan canlı bir akışı kaydırmak zorunda kalmadan arızaya neden olan tam çalışmaya tek tıkla ulaşırsınız. -![Hatalar sayfası: zamana göre hataların histogramı ve her biri tek tıklamalı "+ uyarı" düğmesine sahip gruplandırılmış kırmızı hata satırları](/agenteye/images/errors.png) -*Hatalar sayfası: zamana göre hataların histogramı, tekrarlanan hatalar olay başına bir satırda daraltılmış.* +![Errors sayfası: zaman içinde hata histogramı, her biri tek tıkla "+ alert" düğmesi olan gruplandırılmış kırmızı hata satırları](/agenteye/images/errors.png) +*Errors sayfası: zaman içinde hata histogramı, tekrarlanan hatalar olay başına bir satırda daraltılmıştır.* -## Her hata, sizin için zaten toplanmış +## Her hata sizin için zaten toplanmış -Bir aracı arızalandığında, canlı bir olay akışını kaymadan kırmızı satırları çıkıp gitmeden yakalamayı ummamalısınız. **Hatalar** sayfası toplama işini sizin için yapar. Gösterge tablosunun kırmızıya boyayacağı her şeyi bir triage yüzeyinde bir araya getirir; böylece ilk gördüğünüz şey, neyin başarısız olduğudur, nerede arama yapacağınız değil. +Bir ajan kırdığında, kırmızı satırları kırmızı olarak kayıp gitmeden yakalayarak canlı bir olay akışını kaydırmak zorunda kalmamalısınız. **Errors** sayfası bu toplama işini sizin için yapar. Pano kırmızıyla işaretleyeceği her şeyi tek bir triyaj yüzeyinde bir araya getirir; böylece ilk gördüğünüz şey başarısızlık olur, nereye bakacağınız değil. -Açık olanlardan daha fazlasını yakalar. Açık `error` olaylarının yanı sıra, Failproof AI Observability sessiz başarısızlıkları da ortaya çıkarır: yükü başarısızlık taşıyan herhangi bir `tool_result`, `hook_completed` veya `agent_end` burada gösterilir. Bir hata döndüren araç veya kötü çıkan bir hook artık yalnızca gürültülü bir istisna atılmadığı için gözünüzden kaçmaz. +Ve açık olanlardan daha fazlasını yakalar. Açık `error` olaylarının yanında, Failproof AI Observability sessiz başarısızlıkları da yüzeye çıkarır: yükü bir başarısızlık taşıyan herhangi bir `tool_result`, `hook_completed` veya `agent_end` burada görünür. Hata döndüren bir araç veya kötü çıkış yapan bir hook, sadece yüksek sesli bir istisna atılmadığı için artık gözden kaçmaz. -En üstte, bir histogram hataları zamana göre çizer. Bir bakışta bunun sabit bir arka plan akışı mı yoksa birkaç dakika önce başlayan bir ani artış mı olduğunu anlarsınız, böylece hemen ne yapacağınızı bilirsiniz. +En üstte, bir histogram zamanı içinde hataları çizer. Bir bakış size bunun sabit bir arka plan akışı mı yoksa birkaç dakika önce başlayan bir doruk mu olduğunu söyler; böylece hemen ne yapacağınızı bilirsiniz. -Her gözlem yüzeyinde olduğu gibi, Hatalar sayfası kuruluşunuza özgüdür ve tarih aralığı, ortam, aracı ve oturuma göre filtrelenir. Bu, bir filo genelinde oluşan listeyi almanız ve aslında önem verdiğiniz tek aracıya veya tek ortama daraltmanız anlamına gelir. +Her gözlem yüzeyinde olduğu gibi, Errors sayfası da kuruluşunuza kapsamlıdır ve tarih aralığı, ortam, ajan ve oturum ile filtrelenir. Bu, gemi genelindeki bir listeyi alıp sadece önemsediğiniz bir ajanın veya bir ortamın olduğu yere daraltabileceğiniz anlamına gelir. -## Yüz özdeş satırdan bir olayı +## Yüz özdeş satır değil, bir olay -Tek bir kırık bağımlılık, dakikada aynı hatayı yüzlerce kez çıkarabilir. Ham haliyle, bu neredeyse özdeş satırlar duvarıdır ve aslında görmeniz gereken tek şeyi gömülüdür. +Tek bir kırık bağımlılık, dakika başına yüzlerce kez aynı hatayı tetikleyebilir. Ham haliyle, bu neredeyse özdeş satırlar duvarıdır ve gerçekten görülmesi gereken tek şeyi gömülür. -Failproof AI Observability, aynı oturum ve hata türünü paylaşan tekrarlanan hataları tek bir satırda daraltır. Bir küme bir olayı okur. Sonunda sorunları sayarsınız, günlük satırları değil ve önemli olan sinyal kendi hacmi tarafından boğulmak yerine üstte kalır. +Failproof AI Observability, aynı oturum ve hata türünü paylaşan tekrarlanan hataları tek bir satırda daraltır. Bir patlama bir olay olarak görünür. Sonunda günlük satırlarını değil, sorunları sayarsınız ve önemli olan sinyal kendi hacmi tarafından boğulmak yerine en üstte kalır. -## "Bir şey kırmızı"dan tam olaya kadar +## "Bir şey kırmızı"dan tam olaya -Herhangi bir satırı tıklatın ve başarısız olan tam olayda konumlandırılmış şekilde o çalışmanın oturumunun içine inin. Oturum kimliklerini kopyalama, neyin yanlış gittiği anı aramak için kaydırma: tam oraya varırsınız, tüm yürütme grafiği bir bakışta uzakta olacak şekilde aracının kırılmadan önce anlarında ne yaptığını görebilirsiniz. +Herhangi bir satırı tıklatın ve doğrudan o çalıştırmanın oturumunun içine inmek, arızaya neden olan tam olayda konumlandırılmış olun. Oturum kimliklerini kopyalamayın, yanlış gidişin ne zaman gerçekleştiğini bulmak için kaydırmayın: tam olaya varırsınız; tam yürütme grafiği bir bakış uzağında olduğundan ajanın kırılmadan önceki anlarda ne yaptığını görebilirsiniz. -`alerts:write` iznine sahipseniz, her satırda **+ uyarı** düğmesi de vardır. Bunu tıklatın ve Observability, aynı hatayı yeniden yakalaması için zaten doldurulmuş yeni bir uyarı kuralı açar. Az önce triage ettiğiniz olay, sizi tekrar şaşırtmak yerine bir sonraki sefer sizi çağıracak olan olay haline gelir. +`alerts:write` yetkiniz varsa, her satırda bir **+ alert** düğmesi de bulunur. Tıklatın ve Observability, o aynı hatayı yeniden yakalamak için zaten doldurulmuş yeni bir uyarı kuralı açar. Az önce triyaj ettiğiniz olay, sizi bir sonraki sefer şaşırtmak yerine, sizi çağıran olur. -**Nerede bulunur:** **Hatalar** sayfası gösterge tablosunun observe bölümünde `//errors` konumunda yer alır. +**Nerede bulacağınız:** **Errors** sayfası panonun observe bölümünde bulunur, `//errors` adresinde. ## İlgili -- [Uyarılar](/tr/agenteye/alerts): herhangi bir hatayı bir çağrı kuralına dönüştürün. -- [Olaylar](/tr/agenteye/incidents): açık uyarıyı çözülene kadar takip edin. -- [Oturumlar](/tr/agenteye/sessions): herhangi bir hatanın arkasındaki tam çalışmayı açın. -- [Denetimler](/tr/agenteye/audits): Observability'nin çalışmalarınızda hata desenleri bulmasını sağlayın. \ No newline at end of file +- [Alerts](/tr/agenteye/alerts): herhangi bir başarısızlığı bir sayfalama kuralına dönüştürün. +- [Incidents](/tr/agenteye/incidents): ateşlenen bir uyarıyı açıktan çözüme kadar izleyin. +- [Sessions](/tr/agenteye/sessions): herhangi bir hata arkasındaki tam çalıştırmayı açın. +- [Audits](/tr/agenteye/audits): Observability'nin çalıştırmalarınız arasında başarısızlık kalıplarını bulmasına izin verin. \ No newline at end of file diff --git a/docs/tr/agenteye/evaluation-suite.mdx b/docs/tr/agenteye/evaluation-suite.mdx index 16aec075..0dce3273 100644 --- a/docs/tr/agenteye/evaluation-suite.mdx +++ b/docs/tr/agenteye/evaluation-suite.mdx @@ -1,21 +1,21 @@ --- title: "Değerlendirme Paketi" -description: "Failproof AI Observability, her tamamlanan agent çalışmasını kalite açısından otomatik olarak puanlandırabilir: küçük bir puanlama hizmeti sağlarsınız ve Observability geri kalanını halleder." +description: "Failproof AI Observability, tamamlanan her agent çalıştırmasını otomatik olarak kalite açısından puanlandırabilir: siz küçük bir puanlama hizmeti sağlarsınız, Observability geriye kalan her şeyi yönetir." --- -Failproof AI Observability, her tamamlanan agent çalışmasını kalite açısından otomatik olarak puanlandırabilir: küçük bir puanlama hizmeti sağlarsınız ve Observability geri kalanını halleder. Önem verdiğiniz boyutları (yararlılık, araç verimliliği, doğruluk, güvenlik; siz seçersiniz) izlemek, gerilemeyi erkenden yakalamak ve agent'ları veya ortamları bir bakışta karşılaştırmak için kullanın. Puanlama isteğe bağlıdır: sunucuda `EVALUATOR_ENDPOINT` ayarlanana kadar işlem hattı hiçbir şey yapmaz. +Failproof AI Observability, tamamlanan her agent çalıştırmasını otomatik olarak kalite açısından puanlandırabilir: siz küçük bir puanlama hizmeti sağlarsınız, Observability geriye kalan her şeyi yönetir. Önem verdiğiniz boyutları izlemek için (yararlılık, araç verimliliği, doğruluk, güvenlik; siz seçersiniz), gerilemeyi erkenden yakalamak ve agentları ya da ortamları bir bakışta karşılaştırmak için kullanın. Puanlama isteğe bağlıdır: sunucuda `EVALUATOR_ENDPOINT` ayarlanana kadar ardışık işlem hiçbir şey yapmaz. -> **Not:** Puan boyutlarını siz tanımlarsınız. Değerlendiricininiz istediği sayısal anahtarları döndürebilir; Observability geri gönderdiğiniz her şeyi depolar, trendini oluşturur ve görüntüler. +> **Not:** Puan boyutlarını siz tanımlarsınız. Değerlendiriciler istediği herhangi bir sayısal anahtar döndürebilir; Observability geri gönderdiğiniz her şeyi saklar, trendi oluşturur ve gösterir. -## Bakış +## Bir bakışta -1. **Bir puanlayıcı yazın.** Oturum transkriptini okuyan ve puanlar döndüren küçük bir HTTP hizmeti kurun. Observability, kopyalayabileceğiniz çalışan bir referans seviyesiyle gelir. Bkz. [SDK ile Değerlendirici Yazma](#sdk-ile-değerlendirici-yazma). -2. **Observability'yi ona gösterin.** Sunucu işlemine `EVALUATOR_ENDPOINT` (ve paylaşılan `EVALUATOR_TOKEN`) ayarlayın. -3. **Puanları izleyin.** Her tamamlanan oturum otomatik olarak puanlandırılır; sonuçlar oturum detay sayfasında, oturumlar ızgarasında ve kaydedilmiş panolarda görünür. +1. **Bir değerlendirici yazın.** Oturum transkriptini okuyan ve puanları döndüren küçük bir HTTP hizmeti kurun. Observability kopyalayabileceğiniz çalışan bir referans ile birlikte gelir. Bkz. [SDK ile evaluator yazma](#writing-an-evaluator-with-the-sdk). +2. **Observability'yi işaret edin.** Sunucu işleminde `EVALUATOR_ENDPOINT` (ve paylaşılan `EVALUATOR_TOKEN`) ayarlayın. +3. **Puanların gelmesini izleyin.** Tamamlanan her oturum otomatik olarak puanlandırılır; sonuçlar oturum detay sayfasında, oturumlar ızgarasında ve kaydedilmiş panolarda görünür. -![Değerlendirme özeti, boyut başına puan çubukları ve sağ panelde akıl yürütme metni bulunan bir oturum detay görünümü](/agenteye/images/session-detail.png) +![Sağ panelde değerlendirme özeti, boyut başına puan çubukları ve gerekçe metni gösteren bir oturum detay görünümü](/agenteye/images/session-detail.png) -*Bir değerlendirici yapılandırıldığında, her tamamlanan çalışma puanlandırılır ve sonuçlar oturumun sağ panelinde görünür: üstte özet, ardından akıl yürütmeli boyut başına puan çubukları.* +*Bir evaluator yapılandırıldıktan sonra, her tamamlanan çalıştırma puanlandırılır ve sonuçlar oturumun sağ panelinde görünür: üstte özet, ardından gerekçeli boyut başına puan çubukları.* --- @@ -31,42 +31,42 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Failproof AI Observability SDK bir oturum için `agent_end` olayını yaydığında, sunucu bir değerlendirmeyi programlar. Daha sonra tam olay transkriptini değerlendirici hizmetinize POST eder; bu şunlardan birini yapabilir: +Observability SDK bir oturum için `agent_end` olayı yayınladığında, sunucu bir değerlendirme zamanlar. Ardından tam olay transkriptini değerlendirici hizmetinize POST gönderir ve bu hizmet şunlardan birini yapabilir: - **Sonucu satır içi döndürün** `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}` ile. Sonuç oturumun değerlendirme zaman çizelgesine eklenir. `reasoning` ve `summary` isteğe bağlıdır. -- **Erteleyin** `{"status":"pending", "job_id":"abc-123"}` ile. Observability daha sonra değerlendiricininiz `{"status":"done", ...}` veya `{"status":"error", "error":"..."}` döndürene kadar `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` çağrısını yapar. +- **Ertele** `{"status":"pending", "job_id":"abc-123"}` ile. Observability daha sonra `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` öğesini çağırır ve değerlendiricin `{"status":"done", ...}` ya da `{"status":"error", "error":"..."}` döndürene kadar devam eder. - Yoklama sıklığı iş başına değişir: `pending` yanıtı `next_poll_secs` içerebilir; aksi takdirde Observability `GET /config` yapılandırıcısından `default_poll_interval_secs` değerini kullanır; aksi takdirde sunucu `EVALUATOR_POLLING_INTERVAL_SECS` (varsayılan 10s) değerine geri döner. Tüm değerler [1s, 1h] aralığına sabitlenir. + Yoklama hızı iş başına yapılır: `pending` yanıt isteğe bağlı olarak `next_poll_secs` içerebilir; aksi takdirde Observability `GET /config` öğesinden `default_poll_interval_secs` değerini kullanır; aksi takdirde sunucu `EVALUATOR_POLLING_INTERVAL_SECS` değerine geri döner (varsayılan 10s). Tüm değerler [1s, 1h] aralığına klampe edilir. -`agent_end` yaymayan oturumlar (örneğin, kilitlenmişs agent işlemi) da alınabilir: değerlendiricinin `GET /config` `{"inactivity_timeout_secs": 1800}` döndürebilir ve Observability bu kadar süre boşta kalan herhangi bir oturumu değerlendirir. Bu işlev devre dışı bırakmak için alanı `null` olarak ayarlayın veya atlayın. +Hiçbir zaman `agent_end` yayınlamayan oturumlar (örneğin, çöken bir agent işlemi) da alınabilir: değerlendiricinin `GET /config` öğesi `{"inactivity_timeout_secs": 1800}` döndürebilir ve Observability bu kadar uzun süredir boşta kalmış herhangi bir oturumu değerlendirir. Bu geri dönüş yöntemi devre dışı bırakmak için alanı `null` veya atla ayarlayın. -`EVALUATOR_ENDPOINT` ayarlanmadığında işlem hattı tamamen işlemsizdir. +`EVALUATOR_ENDPOINT` ayarlanmadığında ardışık işlem tamamen no-op'tur. -Bir oturum zaman içinde **birden fazla terminal değerlendirmesi** biriktire bilir: her `agent_end` olayı (ve panodan her manuel yeniden değerlendirme) yeni bir değerlendirme satırı ekler. Bu, devam eden bir konuşmayı değerlendirmenin desteklenen yoludur: bir kullanıcı bir agent'ı sonlandırır, daha sonra geri gelir, daha fazla olay gönderir, agent'ı tekrar sonlandırır ve tam güncellenmiş transkript için ikinci bir değerlendirme çalışır. Pano en son değerlendirmeyi başlık olarak ve önceki değerlendirmeleri daraltılabilir zaman çizelgesi olarak gösterir. Bir oturum için bir değerlendirme çalışırken, o oturum için ek `agent_end` olayları yoksayılır; çalışan değerlendirme tamamlandıktan sonrakı ilk olay her zamanki gibi yeni bir değerlendirmeyi sıraya alır. +Bir oturum zaman içinde **birden çok terminal değerlendirme** biriktirebilir: her `agent_end` olayı (ve panodaki her manuel yeniden değerlendirme) yeni bir değerlendirme satırı ekler. Bu, devam eden bir konuşmayı değerlendirmenin desteklenen yoludur: bir kullanıcı ajanı sona erdirir, daha sonra geri gelir, daha fazla olay gönderir, ajanı tekrar sona erdirir ve ikinci bir değerlendirme tam güncellenmiş transkripte karşı çalışır. Pano en son değerlendirmeyi başlık olarak ve önceki değerlendirmeleri daraltılabilir bir zaman çizelge olarak oluşturur. Bir oturum için bir değerlendirme çalışırken, o oturum için ek `agent_end` olayları yoksayılır; çalışan değerlendirme tamamlandıktan sonraki olay, zamanki gibi yeni bir değerlendirmeyi sıraya alır. -Hareketsizlik geri dönüş, devam eden oturumlar üzerinde de yeniden etkinleştirilir: bir önceki terminal değerlendirmeden sonra yeni olaylar gelirse ve oturum `inactivity_timeout_secs` ötesine boşta kalırsa, yeni bir değerlendirme sıraya alınır. +Hareketsizlik geri dönüşü de devam eden oturumlarda yeniden harekete geçer: yeni olaylar önceki bir terminal değerlendirmeden sonra gelirse ve oturum daha sonra `inactivity_timeout_secs` boyunca boşta kalırsa, yeni bir değerlendirme sıraya alınır. -Geçici hatalar (5xx, 429, zaman aşımları, ağ hataları) `EVALUATOR_MAX_ATTEMPTS` değerine kadar üstel geri dönüşle yeniden denenilir; 4xx yanıtları terminaldir. Observability, birden çok yatay ölçeklenmiş sunucu örnekleriyle güvenle çalışabilir; çalışma bölümlere ayrılır, böylece aynı oturum asla eşzamanlı olarak iki kez gönderilmez. +Geçici arızalar (5xx, 429, zaman aşımları, ağ hataları) `EVALUATOR_MAX_ATTEMPTS` kadar üstel geri tepme ile yeniden denenir; 4xx yanıtları terminaldir. Observability birden çok yatay olarak ölçeklendirilmiş sunucu örneğiyle çalıştırılmak güvenlidir; iş bölümlendirilir, böylece aynı oturum hiçbir zaman eşzamanlı olarak iki kez gönderilmez. --- ## HTTP sözleşmesi -Her kimliği doğrulanan rota **taşıyıcı token kimlik doğrulaması** kullanır. Aynı değer her iki tarafta da yapılandırılması gerekir: +Her kimliği doğrulanmış rota **taşıyıcı belirteci kimlik doğrulamasını** kullanır. Aynı değer her iki tarafta da yapılandırılmalıdır: - Observability sunucusu: ortam değişkeni `EVALUATOR_TOKEN` -- Değerlendirici hizmeti: aynı şekilde yapılandırılmış (agenteye-evaluator SDK kuralı gereği `EVALUATOR_TOKEN` okur) +- Evaluator hizmeti: aynı şekilde yapılandırılmış (agenteye-evaluator SDK'sı kural olarak `EVALUATOR_TOKEN` öğesini okur) -`EVALUATOR_TOKEN` ayarlanmadığında, sunucu `Authorization` başlığı göndermez; değerlendirici anonim istekleri kabul edebilir, bu da yalnızca ağ için iyidir ancak genel internet üzerinde önerilmez. +`EVALUATOR_TOKEN` ayarlanmamışsa, sunucu `Authorization` başlığı göndermez; değerlendirici daha sonra anonim istekleri kabul edebilir, bu da yalnızca dahili bir ağ için uygun olsa da genel internet üzerinde önerilmez. -### Değerlendiricinin sunması gereken rotalar +### Değerlendiricinin sunması gereken yollar -| Rota | Gövde / parametreler | Yanıt | +| Yol | Gövde / parametreler | Yanıt | |---|---|---| -| `GET /health` | hiçbiri | `{"status":"ok"}` (açık, kimlik doğrulaması yok) | -| `GET /config` | hiçbiri | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | -| `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` veya `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | hiçbiri | `/evaluate` ile aynı yanıt şekli | +| `GET /health` | yok | `{"status":"ok"}` (açık, kimlik doğrulaması yok) | +| `GET /config` | yok | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| atlandı}` | +| `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` ya da `{"status":"pending", "job_id":"..."}` | +| `GET /evaluate/{id}` | yok | `/evaluate` ile aynı yanıt şekli | ### Sunucu tarafından gönderilen `EvalRequest` gövdesi @@ -87,7 +87,7 @@ Her kimliği doğrulanan rota **taşıyıcı token kimlik doğrulaması** kullan ### Yanıt şekilleri -**Senkron (tamamlandı):** +**Eşzamanlı (tamamlandı):** ```json { @@ -101,33 +101,33 @@ Her kimliği doğrulanan rota **taşıyıcı token kimlik doğrulaması** kullan } ``` -`reasoning` (puan başına gerekçe haritası) ve `summary` (genel tek paragraf anlatısı) her ikisi de isteğe bağlıdır. `reasoning` içindeki anahtarlar `scores` içindeki anahtarları yansıtmalıdır; pano her girişi puan çubuğunun altında satır içi olarak gösterir. Yalnızca `scores` döndüren eski değerlendericiler değiştirilmeden çalışmaya devam eder; `reasoning` ve `summary` basitçe null olarak okunur ve karşılık gelen UI olanakları çıkarılır. +`reasoning` (puan başına gerekçe haritası) ve `summary` (genel bir paragraf anlatı) her ikisi de isteğe bağlıdır. `reasoning` içindeki anahtarlar `scores` içindeki anahtarları yansıtmalıdır; pano her girişi puan çubuğunun altında satır içi olarak oluşturur. Yalnızca `scores` döndüren eski değerlendiriciler değişmeden çalışmaya devam eder; `reasoning` ve `summary` basitçe null olarak okunur ve ilgili UI olanakları atlanır. -**Asenkron (ertelendi):** +**Eşzamansız (ertelendi):** ```json { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` isteğe bağlıdır; atlanırsa sunucu `/config` değerlendiricisinin `default_poll_interval_secs` değerine, ardından kendi `EVALUATOR_POLLING_INTERVAL_SECS` ortam değişkenine geri döner. +`next_poll_secs` isteğe bağlıdır; atlanırsa sunucu değerlendiricinin `default_poll_interval_secs` öğesine `/config` adresinden geri döner, ardından kendi `EVALUATOR_POLLING_INTERVAL_SECS` ortam değişkenine döner. -**Terminal değerlendirici tarafı hatası:** +**Terminal evaluator tarafı hatası:** ```json { "status": "error", "error": "model service unavailable" } ``` -Sunucu diğer 2xx gövdeleri protokol hatası olarak ele alır ve oturum için terminal `error` kaydeder. +Sunucu diğer 2xx gövdelerine protokol hatası olarak davranır ve oturum için terminal `error` kaydeder. --- -## SDK ile Değerlendirici Yazma +## SDK ile evaluator yazma -HTTP sözleşmesini elle uygulamamanız gerekmez. `agenteye-evaluator` Python paketi, kimlik doğrulamayı, yönlendirmeyi ve istek/yanıt şekillerini sizin için işleyen yazılan bir FastAPI sarmalayıcısı sağlar. +HTTP sözleşmesini elle uygulamak zorunda değilsiniz. `agenteye-evaluator` Python paketi, kimlik doğrulama, yönlendirme ve istek/yanıt şekillerini sizin için işleyen yazılı bir FastAPI sarmalayıcısı sağlar. -Failproof AI Observability ayrıca transkript şeklinden `helpfulness`, `tool_efficiency` ve `factuality` puanlandıran **çalışan bir referans değerlendiricisi** ile gelir. Başlangıç noktası olarak kopyalayın ve kendi mantığınızla değiştirin: bir LLM yargıçsı, bir kural motoru, kalite standartlarınıza uygun her şey. +Failproof AI Observability ayrıca transkriptin şeklinden `helpfulness` (yararlılık), `tool_efficiency` (araç verimliliği) ve `factuality` (doğruluk) puanlandıran **çalışan bir referans evaluator** ile birlikte gelir. Başlangıç noktası olarak kopyalayın ve kendi mantığınızı değiştirin: bir LLM yargıcı, bir kural motoru, kalite standardınıza uygun her şey. -Minimum uygulanabilir değerlendirici: +En az uygulanabilir evaluator: ```python import os @@ -137,7 +137,7 @@ app = Evaluator(token=os.environ["EVALUATOR_TOKEN"]) @app.evaluator def run(req: EvalRequest) -> EvalResponse: - # Inspect req.events (the full session transcript) and return scores. + # req.events (tam oturum transkripti) inceleyin ve puanları döndürün. tool_calls = sum(1 for e in req.events if e.event_type == "tool_use") return EvalResponse( scores={"tool_calls": float(tool_calls)}, @@ -148,40 +148,40 @@ def run(req: EvalRequest) -> EvalResponse: `app` örneği herhangi bir ASGI sunucusu altında çalışır, bu nedenle `uvicorn module:app` başlatır. -Pahalı işi ertelemeleri gereken değerlendiriciler için, bunun yerine `JobPending` döndürün ve `@app.job_lookup` işleyicisini kaydedin; Observability sunucusu terminal durum döndürene veya `EVALUATOR_MAX_POLL_DURATION_SECS` sınırı (varsayılan 1 sa) geçene kadar `GET /evaluate/{job_id}` yoklaması yapar. +Pahalı işi ertelemeye ihtiyaç duyan değerlendiriciler için, bunun yerine `JobPending` döndürün ve `@app.job_lookup` işleyicisi kaydedin; Observability sunucusu `GET /evaluate/{job_id}` öğesini `EVALUATOR_MAX_POLL_DURATION_SECS` başlığı (varsayılan 1 s) sona erinceye kadar terminal durumu döndürene kadar yoklar. -Tam API başvurusu, asenkron desen ve olay şeması `agenteye-evaluator` SDK'sının README'sinde belgelenmiştir. +Tam API başvurusu, eşzamansız desen ve olay şeması `agenteye-evaluator` SDK'sının README'sinde belgelenmiştir. --- -## Değerlendiricininizi Çalıştırma +## Evaluator'unuzu çalıştırma -Değerlendirici **sizin hizmetinizdir** — Failproof AI Observability varsayılan bir değerlendirici seviyesiyle gelmez, bu nedenle kendi hizmetlerinizi çalıştırdığınız yerde oluşturup çalıştırırsınız. Herhangi bir ASGI sunucusu altında çalışır (örneğin `uvicorn my_evaluator:app`); [HTTP sözleşmesinden](#http-sözleşmesi) `/health`, `/config` ve `/evaluate` rotalarını sunun, ardından sunucuyu ona gösterin (bkz. [Sunucuyu Yapılandırma](#sunucuyu-yapılandırma)). +Evaluator **sizin hizmetinizdir** — Failproof AI Observability varsayılan bir evaluator ile birlikte gelmez, bu nedenle kendi hizmetlerinizi çalıştırdığınız yerde kurar ve çalıştırırsınız. Herhangi bir ASGI sunucusu altında çalışır (örneğin `uvicorn my_evaluator:app`); [HTTP sözleşmesinden](#http-contract) `/health`, `/config` ve `/evaluate` yollarını sunun, ardından sunucuyu işaret edin (bkz. [Sunucuyu yapılandırma](#configuring-the-server)). -Değerlendirici erişilebilir olduğunda, `GET /health` `{"status":"ok"}` döndürür. Bir agent'ı uçtan uca çalıştırdıktan sonra, sunucudaki `GET /evaluations` değerlendiricininizin ürediği puanlarla `status: "done"` olan bir satır döndürür. +Evaluator ulaşılabilir olduğunda, `GET /health` `{"status":"ok"}` döndürür. Bir agent uçtan uca çalıştıktan sonra, sunucudaki `GET /evaluations` puanlarınızı değerlendiricinin ürettiği `status: "done"` ve puanlarla bir satır döndürür. --- -## Sunucuyu Yapılandırma +## Sunucuyu yapılandırma -Sunucu işlemi üzerinde ayarlayın: +Sunucu işleminde ayarlayın: | Ortam değişkeni | Anlamı | |---|---| -| `EVALUATOR_ENDPOINT` | Değerlendiricininizin temel URL'si (`http://evaluator:9000`). Ayarlanmadı = işlem hattı devre dışı. | -| `EVALUATOR_TOKEN` | Taşıyıcı token. Değerlendirici hizmetinin yapılandırıldığı değerle eşit olmalıdır. | -| `EVALUATOR_WORKERS` | Sunucu örneği başına işçi görevleri (varsayılan 2). | -| `EVALUATOR_CLAIM_BATCH` | İşçi setiği başına talep edilen satırlar (varsayılan 4). Toplu işler **eşzamanlı olarak** işlenir; değerlendirici uç noktasında etkili eşzamanlılık `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` değeridir. | -| `EVALUATOR_POLL_IDLE_SECS` | Hiçbir değerlendirme ödenmezken bir işçinin gönderme denemeleri arasında kaç saniye uyuduğu (varsayılan 2s). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | `GET /evaluate/{id}` sıklığında nihai geri dönüş, ne yanıt başına `next_poll_secs` ne de değerlendiricinin `default_poll_interval_secs` ayarlanmadığında (varsayılan 10s). | +| `EVALUATOR_ENDPOINT` | Evaluator'unuzun temel URL'si (`http://evaluator:9000`). Ayarlanmadı = ardışık işlem devre dışı. | +| `EVALUATOR_TOKEN` | Taşıyıcı belirteci. Evaluator hizmetinin yapılandırıldığı değere eşit olmalıdır. | +| `EVALUATOR_WORKERS` | Sunucu örneği başına çalışan görevleri (varsayılan 2). | +| `EVALUATOR_CLAIM_BATCH` | Çalışan başına talep edilen satırlar (varsayılan 4). Toplar **eşzamanlı olarak** işlenir; evaluator uç noktanız üzerinde etkin eşzamanlılık `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` şeklindedir. | +| `EVALUATOR_POLL_IDLE_SECS` | Hiçbir değerlendirme vadesi olmadığında çalışanın gönderim girişimleri arasında uyuduğu süre (varsayılan 2s). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | `GET /evaluate/{id}` hızı için nihai geri dönüş, ne per-response `next_poll_secs` ne de evaluator'un `default_poll_interval_secs` ayarlandığında (varsayılan 10s). | | `EVALUATOR_REQUEST_TIMEOUT_MS` | İstek başına zaman aşımı (varsayılan 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | Bu kadar geçici hata sonrasında sonuç terminal `error` olarak kaydedilir (varsayılan 5). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` sıklığı (varsayılan 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Bir oturumun `timeout` olarak sonlandırılmadan önce yoklama kuyruğunda kalabileceği maksimum gerçek saat (varsayılan 3600s). Değerlendirici tarafından `pending` döndüren bir değerlendiriciye karşı koruma. | +| `EVALUATOR_MAX_ATTEMPTS` | Bu kadar geçici arızadan sonra sonuç terminal `error` olarak kaydedilir (varsayılan 5). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` hızı (varsayılan 300). | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Bir oturumun yoklama kuyruğunda kalabileceği maksimum duvar saati zamanı, `timeout` olarak sonlandırılmadan önce (varsayılan 3600s). Sonsuza kadar `pending` döndüren bir evaluator'a karşı koruma. | -Otomatik puanlamayı açmak için sunucuda `EVALUATOR_ENDPOINT` ve `EVALUATOR_TOKEN` ayarlayın, ardından değişikliği seçmek için yeniden başlatın. `EVALUATOR_ENDPOINT` ayarlanmadığında işlem hattı bir no-op kalır. +Otomatik puanlamayı etkinleştirmek için, sunucuda hem `EVALUATOR_ENDPOINT` hem de `EVALUATOR_TOKEN` ayarlayın, ardından değişikliği almak için yeniden başlatın. `EVALUATOR_ENDPOINT` ayarlanmadığında ardışık işlem no-op kalır. -Yukarıdaki tuning düğmeleri isteğe bağlıdır; varsayılanları geçersiz kılmanız gerekiyorsa karşılık gelen ortam değişkenlerini yalnızca sunucuda ayarlayın. +Yukarıdaki tuning düğmeleri isteğe bağlıdır; varsayılanları geçersiz kılmanız gerekirse, yalnızca karşılık gelen ortam değişkenlerini sunucuda ayarlayın. --- @@ -189,24 +189,24 @@ Yukarıdaki tuning düğmeleri isteğe bağlıdır; varsayılanları geçersiz k | Yöntem | Yol | Gerekli izin | Amaç | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Terminal sonuçları sorgulayın. `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session` destekler. `limit` varsayılan olarak 50'dir ve 200 ile sınırlandırılmıştır (bunun `/events` öğesinden farklı olduğunu unutmayın, bu da 1000 ile sınırlandırılmıştır). `environment` virgülle ayrılmış bir liste kabul eder (örn. `environment=prod,staging`); tek değerler hala çalışır. `latest_per_session=true` ile yanıt en fazla `session_id` başına bir satır (en sonraki `completed_at` tarafından) içerir, bu da bir oturumun değerlendirme zaman çizelgesini mevcut başlığına daraltmak için oturumlar listesi sayfasında kullanılır. Varsayılan olarak false (tam geçmişi döndürür). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | Filtrelenmiş bir dilim için toplanmış eval sağlığı: toplam sayı, bir done/error/timeout dökümü, puan başına anahtar istatistikleri (keyfi `scores` anahtarları üzerinde sayı/ort/min/maks/p50) ve zaman sınırlı zaman çizelgesi. `/evaluations` **ile aynı filtre parametrelerini** artı `featured_keys` (trendli puan anahtarlarının CSV'si) ve `latest_per_session` kabul eder. Panolar özelliğini destekler; metrikler tam eşleşen küme üzerinde kesin, örneklanmamış. | -| `GET` | `/evaluations/environments` | `evaluations:read` | `evaluations` tablosundan ayrı ortam değerleri. Değerlendirme-okunabilir verilere kapsamlı filtre açılır listelerini doldurmak için kullanılır. | -| `GET` | `/evaluation-jobs` | `evaluations:read` | Uçuştaki değerlendirmelere yönelik görünürlük. `status` (`pending`/`polling`) ile filtreleyin. | -| `GET` | `/events` | `events:read` | Bir oturumun ham olaylarını akışa alın. `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` ve `order` destekler. `order` `desc` (yeni ilk, varsayılan) veya `asc` (eski ilk); tanınmayan bir değer `desc` değerine geri döner. İmleci yanıtın `next_cursor` (olay id'si) aracılığıyla sayfalayın: sonraki sayfayı almak için `cursor` olarak geri geçirin; `asc` ile sonraki sayfa, `desc` ile bu id'den önceki olaylar bu id'den sonra olaylar. `limit` varsayılan olarak 50'dir ve 1000 ile sınırlandırılmıştır. | -| `GET` | `/sessions/:session_id/export` | `events:read` | Değerlendiricinin bu oturum için alacağı tam JSON gövdesini `session-.json` adlı indirilebilir bir ek olarak döndürür. Çevrimdışı test için üretim oturumlarını `agenteye-evaluator` aracılığıyla yeniden oynatmak için faydalı. Baytlar değerlendirici işlem hattının gönderdiği şeyle bayt olarak özdeştir. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Bir oturum için yeni bir değerlendirmeyi sıraya alın; önceki bir değerlendirme olup olmadığına bakılmaksızın çalışır. Yeni sonuç, önceki oturumun değerlendirme zaman çizelgesine **eklenir** ve üzerine yazılmaz, bu nedenle önceki puanlar tarih olarak görünür kalır. Sıraya alma sırasında `202`, bilinmeyen oturum için `404`, bir değerlendirme zaten uçuştaysa `409` döndürür. Bunu yeni bir değerlendirici dağıttıktan sonra veya `agent_end` yaymayan oturumlar için kullanın. | +| `GET` | `/evaluations` | `evaluations:read` | Terminal sonuçlarını sorgula. `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session` öğesini destekler. `limit` varsayılan olarak 50 ve 200 ile sınırlandırılır (`/events` ile fark, 1000 ile sınırlandırılır). `environment` virgülle ayrılmış bir liste kabul eder (örn. `environment=prod,staging`); tek değerler yine de çalışır. `latest_per_session=true` ile yanıt en fazla `session_id` başına bir satır içerir (`completed_at` ile en son) oturumlar listesi sayfası tarafından kullanılan bir oturumun değerlendirme zaman çizelgesini geçerli başlığına daraltmak. Varsayılan olarak false (tam geçmiş döndürür). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | Filtrelenmiş bir dilim için yukarı doğru değerlendirme sağlığı: toplam sayı, done/error/timeout dökümü, puan başına anahtar istatistikleri (count/avg/min/max/p50 rasgele `scores` anahtarları üzerinde) ve zaman tabanlı bir zaman çizelge. `/evaluations` ile **aynı filtre parametrelerini** artı `featured_keys` (trend yapılacak puan anahtarlarının CSV'si) ve `latest_per_session` kabul eder. Panolar özelliğini güçlendirir; metrikler örneklenmemiş, tüm eşleşen küme üzerinden kesindir. | +| `GET` | `/evaluations/environments` | `evaluations:read` | `evaluations` tablosundan farklı ortam değerleri. Değerlendirme tarafından okunabilen verilere kapsamlı filtre açılır listelerini doldurmak için kullanılır. | +| `GET` | `/evaluation-jobs` | `evaluations:read` | Uçuş içi değerlendirmelere görünürlük. `status` (`pending`/`polling`) tarafından filtreleyin. | +| `GET` | `/events` | `events:read` | Bir oturumun ham olaylarını akışla aktarın. `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` ve `order` öğesini destekler. `order` `desc` (en yeniden ilk, varsayılan) veya `asc` (en eskiden ilk); tanınmayan bir değer `desc` öğesine geri döner. Yanıtın `next_cursor` (bir olay id) aracılığıyla imleç-sayfalandır: sonraki sayfayı almak için `cursor` olarak geri geçirin; `asc` ile sonraki sayfa bu id'den sonraki olaylar, `desc` ile bu kimlikten önceki olaylardır. `limit` varsayılan olarak 50 ve 1000 ile sınırlandırılır. | +| `GET` | `/sessions/:session_id/export` | `events:read` | Evaluator'un bu oturum için alacağı tam JSON gövdesini döndürür ve `session-.json` adlı indirilebilir bir ek olarak sunulur. Üretim oturumlarını çevrimdışı testler için `agenteye-evaluator` aracılığıyla yeniden oynatmak için kullanışlıdır. Baytlar evaluator ardışık işleminin gönderdiği şeylerle byte-özdeş olur. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Bir oturum için yeni bir değerlendirme kuyruğa al; önceki bir değerlendirme olup olmadığına bakılmaksızın çalışır. Yeni sonuç önceki satırın üzerine yazılmak yerine oturumun değerlendirme zaman çizelgesine **eklenir**, bu nedenle önceki puanlar tarih olarak görünür kalır. Kuyruğa alınırsa `202` döndürür, bilinmeyen bir oturum için `404` döndürür, bir değerlendirme zaten uçuş halindeyse `409` döndürür. Bunu yeni bir evaluator'u dağıttıktan sonra veya hiçbir zaman `agent_end` yayınlamayan oturumlar için kullanın. | ### Puan aralığına göre filtreleme: `score_filters` -`GET /evaluations` `scores` nesnesi içindeki sayısal değerlere göre sonuçları daraltırsa isteğe bağlı bir `score_filters` parametresini kabul eder. Parametre, virgülle ayrılmış `key:min..max` girdilerinin bir listesidir; her iki sınır atlanabilir. Birden çok girdi mantıksal AND ile birleştirilir. Adlandırılmış anahtarın olmadığı veya sayısal olmayan satırlar hariç tutulur. Bir istek en fazla 20 filtre girişi taşıyabilir; bunu aşmak HTTP 400 döndürür. +`GET /evaluations`, `scores` nesnesi içindeki sayısal değerlere göre sonuçları daraltacak isteğe bağlı bir `score_filters` parametresi kabul eder. Parametre, virgülle ayrılmış `key:min..max` girdilerinin bir listesidir; her iki sınır da atlanabilir. Birden çok giriş mantıksal AND ile birleşir. Adlandırılmış anahtarı olmayan veya sayısal olmayan satırlar hariç tutulur. İstek en fazla 20 filtre girişi taşıyabilir; aşılması HTTP 400 döndürür. Örnekler: ```text -# helpfulness in [0.5, 0.8] +# helpfulness [0.5, 0.8] içinde GET /evaluations?score_filters=helpfulness:0.5..0.8 -# tool_efficiency at most 0.3 (no lower bound) +# tool_efficiency en fazla 0.3 (alt sınır yok) GET /evaluations?score_filters=tool_efficiency:..0.3 # helpfulness >= 0.5 AND factuality >= 0.9 @@ -217,83 +217,83 @@ Her `/evaluations` yanıt nesnesinin bu alanları vardır: | Alan | Tür | Notlar | |---|---|---| -| `evaluation_id` | dize (UUID) | Bu terminal değerlendirmesi için kanonik tanımlayıcı. Her terminal değerlendirme yeni bir UUID alır; tek bir oturum birden çok tutabilir. | -| `id` | dize (UUID) | `evaluation_id` ile aynı değeri taşıyan geri uyumluluk diğer adı. | -| `session_id` | dize | Bu değerlendirmenin karşı koştuğu oturum. Bir oturumun zaman çizelgesinde birden çok değerlendirmesi olabilir. | -| `agent_id` | dize | Oturumu üreten agent'ı tanımlar. | -| `environment` | dize | Oturumdan kopyalanan ortam etiketi. | +| `evaluation_id` | string (UUID) | Bu terminal değerlendirme için kanonik kimlik. Her terminal değerlendirme yeni bir UUID alır; tek bir oturum birden çok tutuculabilir. | +| `id` | string (UUID) | `evaluation_id` ile aynı değeri taşıyan geriye dönük uyumluluk takma adı. | +| `session_id` | string | Bu değerlendirmenin karşı koştuğu oturum. Bir oturum zaman çizelgede birden çok değerlendirme yapabilir. | +| `agent_id` | string | Oturumu üreten ajanı tanımlar. | +| `environment` | string | Oturumdan kopyalanan ortam etiketi. | | `status` | enum | Biri `"done"`, `"error"`, `"timeout"`. | -| `scores` | nesne \| null | Değerlendiricininiz tarafından döndürülen puanlar. | -| `reasoning` | nesne \| null | Değerlendiricininiz tarafından döndürülen isteğe bağlı puan başına gerekçe haritası. Anahtarlar genellikle `scores` içindekileri yansıtır. Pano her girişi puan çubuğunun altında gösterir. | -| `summary` | dize \| null | Değerlendiricininiz tarafından döndürülen isteğe bağlı tek paragraf genel anlatısı. Pano bunu değerlendirmenin başlığı olarak puan başına dökümün üzerinde gösterir. | -| `error` | dize \| null | Yalnızca `"error"` / `"timeout"` üzerinde doldurulmuş. | -| `attempt_count` | tamsayı | Gönderme denemesi sayısı (≥ 1). | -| `duration_ms` | tamsayı \| null | Son denemenin süresi. | -| `completed_at` | dize (ISO 8601 UTC) | Terminal sonuç kaydedildiğinde. Sonuçlar `completed_at` (en yeni ilk) tarafından sıralanır. | -| `created_at` | dize (ISO 8601 UTC) | `completed_at` ile aynı zaman damgasını taşır (yazma bir kez semantiği). | +| `scores` | object \| null | Değerlendiricinin döndürdüğü puanlar. | +| `reasoning` | object \| null | Değerlendiricinin döndürdüğü isteğe bağlı puan başına gerekçe haritası. Anahtarlar tipik olarak `scores` içindekileri yansıtır. Pano her girişi puan çubuğunun altında oluşturur. | +| `summary` | string \| null | Değerlendiricinin döndürdüğü isteğe bağlı bir paragraf genel anlatı. Pano bunu puan başına dökümün üzerinde değerlendirmenin başlığı olarak oluşturur. | +| `error` | string \| null | Yalnızca `"error"` / `"timeout"` üzerinde doldurulur. | +| `attempt_count` | integer | Gönderim denemelerinin sayısı (≥ 1). | +| `duration_ms` | integer \| null | Son denemesinin süresi. | +| `completed_at` | string (ISO 8601 UTC) | Terminal sonuç kaydedildiğinde. Sonuçlar `completed_at` (en yeniden ilk) ile sıralanır. | +| `created_at` | string (ISO 8601 UTC) | `completed_at` ile aynı zaman damgasını taşır (bir kez yazma semantiği). | --- ## İzinler -| İzin | Verir | +| İzin | Hibe | |---|---| -| `evaluations:read` | Değerlendirme sonuçlarını listeleyin, panoda puanları görüntüleyin ve pano sağlığı metriklerini yükleyin. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` aracılığıyla veya panonun yeniden değerlendirme düğmesinden bir oturum için manuel olarak bir değerlendirmeyi sıraya alın. | -| `dashboards:read` | Kaydedilmiş panoları görüntüleyin (metriklerini yüklemek için `evaluations:read` de gerekir). | -| `dashboards:write` | Panolar oluşturun ve düzenleyin. | -| `dashboards:delete` | Panolar silin. | +| `evaluations:read` | Değerlendirme sonuçlarını listele, panoda puanları görüntüle ve pano sağlık metriklerini yükle. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` aracılığıyla veya panodaki yeniden değerlendirme düğmesinden bir oturum için değerlendirmeyi manuel olarak kuyruğa al. | +| `dashboards:read` | Kaydedilmiş panoları görüntüle (metriklerini yüklemek için `evaluations:read` da gerekli). | +| `dashboards:write` | Panoları oluştur ve düzenle. | +| `dashboards:delete` | Panoları sil. | -Bootstrap admin (`ADMIN_KEY`, `ADMIN_EMAIL`) otomatik olarak bunları alır. +Önyükleme yöneticisi (`ADMIN_KEY`, `ADMIN_EMAIL`) otomatik olarak bunların hepsini alır. --- -## Sonuçları Görüntüleme +## Sonuçları görüntüleme -- **`/sessions/`**: olay zaman çizelgesi + oturumun puanlarını ve gönderme denemesinden herhangi bir hatayı gösteren sağ panel. Anahtarınız `evaluations:trigger` izniyle gelirse, export düğmesinin yanında **yeniden değerlendirme** düğmesi görünür, `agent_end` yaymayan oturumlar için veya yeni bir değerlendirici dağıttıktan sonra puanları yenilemek için yararlıdır. Pano yeni sonuç için yoklar ve iniş yaptığında sağ paneli günceller. +- **`/sessions/`**: olaylar zaman çizelgesi + oturumun puanlarını ve gönderim denemesinden herhangi bir hatayı gösteren sağ ray. Anahtarınız `evaluations:trigger` öğesine sahipse, bir **yeniden değerlendirme** düğmesi ihracat düğmesinin yanında görünür; bu hiçbir zaman `agent_end` yayınlamayan oturumlar veya yeni bir evaluator dağıttıktan sonra puanları yenileştirmek için kullanışlıdır. Pano yeni sonuç için yoklar ve sağ ray güncellenir. - **`/sessions`**: filtrelenebilir oturum ızgarası; puan sütunu her oturumun değerlendirme durumunu ve puanlarını bir bakışta gösterir. -- **`/dashboards`**: kaydedilmiş eval-sağlığı görünümleri (aşağıdaki [Panolar](#panolar) öğesine bakın). +- **`/dashboards`**: kaydedilmiş eval-sağlık görünümleri (bkz. [Panolar](#dashboards) aşağıda). -![Oturum başına değerlendirme durumu hapları ve renk kodluylu puan rozetleri (yararlılık, doğruluk, tool_efficiency, güvenlik, uyum) bulunan Oturumlar ızgarası](/agenteye/images/sessions-list.png) +![Her oturum değerlendirme durumu hapları ve renkli puan rozetleri (yararlılık, doğruluk, araç_verimliliği, güvenlik, tutarlılık) gösteren oturumlar ızgarası](/agenteye/images/sessions-list.png) -*Oturumlar ızgarası her çalışmanın değerlendirme durumunu ve puanlarını bir bakışta gösterir; kırmızı/turuncu/yeşil rozet düşük puanları öne çıkarır.* +*Oturumlar ızgarası her çalıştırmanın değerlendirme durumunu ve puanlarını bir bakışta gösterir; kırmızı/sarı/yeşil rozetler düşük puanları fark ettirir.* --- ## Panolar -**Panolar** sayfası (`/dashboards`) değerlendirme filtrelerinin bir kombinasyonunu adlı, yeniden kullanılabilir bir görünüm olarak kaydetmenize ve değerlendirmelerin o diliminin nasıl yaptığını bir bakışta izlemenize olanak tanır. Panolar **bütün kuruluşunuz genelinde paylaşılır**; `dashboards:read` olan herkes aynı seti görür. +**Panolar** sayfası (`/dashboards`), değerlendirme filtrelerinin bir kombinasyonunu adlandırılmış, yeniden kullanılabilir bir görünüm olarak kaydetmenizi ve o değerlendirme diliminin nasıl olduğunu bir bakışta izlemenizi sağlar. Panolar **tüm kuruluşunuz arasında paylaşılır**; `dashboards:read` öğesi olan herkes aynı seti görür. -Her pano sabitler: +Her pano şunları işaret eder: -- **Filtreler**: oturumlar sayfasıyla aynı denetimler: ortam, durum, agent, kayan bir zaman penceresi ve puan aralığı filtreleri (`key:min..max`). -- **Bir görüntü yapılandırması**: hangi puan anahtarlarının öne çıkarılacağı, yeşil/turuncu/kırmızı sağlık eşikleri, hangi panelerin gösterileceği ve oturum başına en son değerlendirmeye daraltılıp daraltılmayacağı. +- **Filtreler**: oturumlar sayfasıyla aynı kontroller: ortam, durum, ajan, dönen bir zaman penceresi ve puan aralığı filtreleri (`key:min..max`). +- **Bir görüntü yapılandırması**: hangi puan anahtarlarının öne çıkarılacağı, yeşil/sarı/kırmızı sağlık eşikleri, hangi panelların gösterildiği ve en son oturumun oturum başına daraltılıp daraltılmayacağı. -Her kart eşleşen oturum sayısını, bir done/error/timeout dökümünü, her öne çıkarılan puanın ortalamasını ve küçük bir trend sparkline'ını gösterir. Bir panoyu açmak tam boyutlu panelları gösterir; **"oturumları aç"** sizi tam olarak bu dilime önceden filtrelenmiş oturumlar sayfasına bırakır. Metrikler sunucu tarafında tam eşleşen küme üzerinden (via `GET /evaluations/aggregate`) hesaplanır, bu nedenle sayılar örneklenmiş yerine kesindir. +Her kart eşleşen oturum sayısını, done/error/timeout dökümünü, her özellikli puanın ortalamasını ve küçük bir trend mini grafiğini gösterir. Bir pano açılması tam boyutlu paneleri gösterir; **"oturumlarda aç"** sizi bu dilime tam olarak önceden filtrelenmiş oturumlar sayfasına bırakır. Metrikler sunucu tarafı üzerinden hesaplanır (via `GET /evaluations/aggregate`), bu nedenle sayılar örneklenmemiş yerine kesindir. -![Ortalama puan çubukları, araç tamam-vs-hata dökümü, en iyi araçlar ve saat başına olaylar trendi bulunan bir eval-sağlığı panosu](/agenteye/images/dashboard-quality.png) +![Ortalama puan çubukları, araç tamam-vs-hata dökümü, en iyi araçlar ve saatlik olaylar trendi gösteren bir eval-sağlık panosu](/agenteye/images/dashboard-quality.png) -**İzinler:** görüntüleme hem `dashboards:read` hem de `evaluations:read` gerektirir; oluşturma ve düzenleme `dashboards:write` gerektirir; silme `dashboards:delete` gerektirir. Bootstrap admin bunların tümünü otomatik olarak alır. +**İzinler:** görüntülenme hem `dashboards:read` hem de `evaluations:read` gerektirir; oluşturma ve düzenleme `dashboards:write` gerektirir; silme `dashboards:delete` gerektirir. Önyükleme yöneticisi bunların hepsini otomatik olarak alır. --- -## Sorun Giderme +## Sorun giderme -**Oturumlar var ancak değerlendirme oluşturulmadı.** `EVALUATOR_ENDPOINT` sunucu işleminde ayarlandığını, sunucu ve değerlendiricinin aynı `EVALUATOR_TOKEN` değerini paylaştığını ve değerlendiricinin `/health` uç noktasının sunucudan erişilebilir olduğunu doğrulayın. `EVALUATOR_ENDPOINT` ayarlanmadığında işlem hattı bir no-op'tur. +**Oturumlar var ama değerlendirme oluşturulmamış.** Sunucu işleminde `EVALUATOR_ENDPOINT` ayarlandığını, sunucunun ve evaluator'un aynı `EVALUATOR_TOKEN` değerini paylaştığını ve evaluator'un `/health` uç noktasının sunucudan ulaşılabilir olduğunu doğrulayın. `EVALUATOR_ENDPOINT` ayarlanmadığında ardışık işlem no-op'tur. -**Uçuştaki değerlendirmeler yığın halinde birikir.** Uçuştaki kuyruğu görmek için `GET /evaluation-jobs` sorgusunu çalıştırın. Her satırda `attempt_count`, `next_attempt_at` ve `last_error` inceleyin. Yaygın nedenler: değerlendirici hizmeti ulaşılamıyor veya 5xx döndürüyor (geri dönüş ile yeniden deneniyor), yanlış `EVALUATOR_TOKEN` (401 terminaldir) veya `pending` tanımsız olarak döndüren asenkron değerlendirici (aşağıya bakın). +**Uçuş içi değerlendirmeler birikir.** Uçuş içi kuyruğu görmek için `GET /evaluation-jobs` sorgulayın. Her satırda `attempt_count`, `next_attempt_at` ve `last_error` inceleyin. Yaygın nedenler: evaluator hizmeti ulaşılamaz veya 5xx döndürüyor (geri tepme ile yeniden denenmiş), yanlış `EVALUATOR_TOKEN` (401 terminaldir) veya `pending` sonsuza kadar döndüren eşzamansız bir evaluator (bkz. aşağıda). -**Oturumlar tamamlandı ancak terminal değerlendirmesi yok.** `GET /evaluation-jobs?status=polling` sorgusu çalıştırın; sonuç hala uçuştaysa olabilir. Bir iş `pending` de takılıysa sunucu değerlendiriciye ulaşmakta zorluk çekiyor; değerlendiricinin açık olduğunu ve `EVALUATOR_TOKEN` eşleştiğini kontrol edin. +**Oturumlar tamamlandı ama terminal değerlendirme yok.** `GET /evaluation-jobs?status=polling` öğesini sorgulayın; sonuç hala uçuş halinde olabilir. Bir iş `pending` konumunda takılıysa, sunucu evaluator'a ulaşmakta sorun yaşıyor; evaluator'un açık olduğunu ve `EVALUATOR_TOKEN` eşleştiğini kontrol edin. -**`HTTP 401 from evaluator: invalid bearer token`.** Sunucudaki `EVALUATOR_TOKEN` değerlendirici hizmetinin yapılandırıldığı değerle eşleşmez. Özdeş olması gerekir. +**Evaluator'dan `HTTP 401: geçersiz taşıyıcı belirteci`.** Sunucudaki `EVALUATOR_TOKEN` evaluator hizmetinin yapılandırıldığı değerle eşleşmiyor. Aynı olmalıdırlar. -**Asenkron değerlendirici `pending` tanımsız olarak döndürür.** Sunucu değerlendirici `done` veya `error` döndürene veya `EVALUATOR_MAX_POLL_DURATION_SECS` (varsayılan 1 sa) geçene kadar `GET /evaluate/{job_id}` yoklaması yapar. Limit geçtikten sonra değerlendirme `timeout` olarak kaydedilir ve uçuş kuyruğundan kaldırılır. Değerlendiricininiz meşru olarak varsayılandan daha uzun süreye ihtiyacsa `EVALUATOR_MAX_POLL_DURATION_SECS` artırın. +**Eşzamansız evaluator sonsuza kadar `pending` döndürüyor.** Sunucu `GET /evaluate/{job_id}` yoklar, evaluator `done` veya `error` döndürene kadar veya `EVALUATOR_MAX_POLL_DURATION_SECS` (varsayılan 1 s) sona erinceye kadar. Başlığın ardından değerlendirme `timeout` olarak kaydedilir ve uçuş içi kuyruktan çıkarılır. Evaluator'unuz varsayılandan daha uzun süre gerçekten ihtiyaç duyuyorsa `EVALUATOR_MAX_POLL_DURATION_SECS` yükseltin. --- ## Sonraki adımlar -- [Değerlendirici agent becerisi](/tr/agenteye/evaluator-skill): kodlama agent'ının boyutlarınızı gerçek oturumlara karşı tasarlaması ve bu hizmeti sizin için oluşturması. +- [Evaluator agent becerisi](/tr/agenteye/evaluator-skill): boyutlarınızı gerçek oturumları tasarlamak ve bu hizmeti sizin için oluşturmak için bir kodlama ajanı var. - [Python SDK](/tr/agenteye/python-sdk): puanlamayı tetikleyen `agent_end` olaylarını yayın. - [API anahtarları](/tr/agenteye/api-keys): `evaluations:read` ve `evaluations:trigger` izinleri. -- [Denetimler](/tr/agenteye/audits): Observability'nin diğer otomatik kalite özelliği, ilke tabanlı inceleme için. \ No newline at end of file +- [Denetimler](/tr/agenteye/audits): Observability'nin diğer otomatik kalite özelliği, politika tabanlı gözden geçirme için. \ No newline at end of file diff --git a/docs/tr/agenteye/evaluations.mdx b/docs/tr/agenteye/evaluations.mdx index e3fe9afe..ff56d910 100644 --- a/docs/tr/agenteye/evaluations.mdx +++ b/docs/tr/agenteye/evaluations.mdx @@ -1,51 +1,51 @@ --- title: "Değerlendirmeler" -description: "Kalite sorunları artık sizin bulduğunuz yer, müşteri şikayeti olarak duymak yerine." +description: "Kalite sorunları sizi bulur; müşteri şikayetinden haberdar olmak yerine." --- -Kalite sorunları artık sizin bulduğunuz yer, müşteri şikayeti olarak duymak yerine. Kendi puanlama hizmetinizi bir kez bağlayın ve Failproof AI Observability, tamamlanan her çalışmayı otomatik olarak değerlendirerek, yardımcılıkta bir düşüş veya halüsinasyonlarda bir yükseliş, müşteri bunu hissetmeden kendi kendine ortaya çıkar. +Kalite sorunları sizi bulur; müşteri şikayetinden haberdar olmak yerine. Failproof AI Observability'ye bir kez puanlama hizmetinizi bağlayın ve her tamamlanan çalıştırma otomatik olarak derecelendirilir. Yararlılık düşüşü veya halüsinasyonlarda bir artış, müşteri bunu hissetmeden kendi kendine ortaya çıkar. -![Puan sütunlu Oturumlar ızgarası: her çalışma bir değerlendirme durumu rozeti ve renk kodlu yardımcılık, doğruluk ve araç verimlilik rozetleri taşır](/agenteye/images/sessions-list.png) +![Skor sütunu olan Oturumlar ızgarası: her çalıştırma bir değerlendirme durumu rozeti ve renk kodlu yararlılık, gerçekçilik ve araç-verimlilik rozetleri taşır](/agenteye/images/sessions-list.png) -*Oturumlar ızgarasındaki her çalışma puanlarını taşır; kırmızı, sarı ve yeşil rozetler, tek bir transkrip açmadan zayıf çalışmaları hemen ortaya çıkarır.* +*Oturumlar ızgarasındaki her çalıştırma puanlarını taşır; kırmızı, turuncu ve yeşil rozetler zayıf çalıştırmaları tek bir transkripti bile açmadan öne çıkarır.* -## El ile çalışmaları örneklemeyi durdurun +## El ile çalıştırmaları örnekleme işini durdurun -Eskiden bir avuç çalışmayı spot kontrol etmeniz ve geri kalanın iyi olacağını ummanız gerekiyordu. Artık tamamlanan her oturum, sizin önemsediğiniz boyutlarda anlık olarak puanlanıyor: yardımcılık, araç verimliliği, doğruluk, güvenlik, ne olursa olsun kalite standardınız. Siz puan anahtarlarını tanımlarsınız; Failproof AI Observability, değerlendiricinin geri gönderdiği her şeyi saklayıp, trend gösterir ve görüntüler. Hiçbir çalışma puanlanmadan kaçmaz ve destek talebinden regresyon hakkında öğrenmeyi bırakırsınız. +Daha önce bir avuç çalıştırmayı spot-check yapardınız ve geri kalanının iyi olduğunu umardınız. Artık her tamamlanan oturum, önemli olduğunuz boyutlarda bitişi olmamış puanlanır: yararlılık, araç verimliliği, gerçekçilik, güvenlik, sizin kalite standardınız ne olursa olsun. Siz skor anahtarlarını tanımlarsınız; Failproof AI Observability, değerlendiricinizin geri gönderdiği her şeyi depolar, trendi oluşturur ve görüntüler. Hiçbir çalıştırma puanlandırılmadan kaçmaz ve bir destek biletinden regresyon hakkında bilgi almayı durdurursunuz. -Puanlar **`//sessions`** adresindeki oturumlar ızgarasında yer alır (kenar çubuğu → *observe* → *sessions*), satır başına bir rozet kümesi. Sadece başarısız olan çalışmaları mı istiyorsunuz? Izgarayı puan aralığına göre filtreleyin, diyelim ki 0,5'in altında yardımcılık ve tam olarak okunmaya değer çalışmaları açın. Puanları görüntülemek için `evaluations:read` iznine ihtiyaç duyarsınız. +Puanlar **`//sessions`** adresindeki oturumlar ızgarasında (kenar çubuğu → *observe* → *sessions*) bulunur; her satırda bir rozet kümesi. Yalnızca yetersiz kalan çalıştırmaları mı istiyorsunuz? Izgarayı skor aralığına göre filtreleyebilirsiniz; örneğin yararlılık 0,5'in altında, ve okumaya değer tam çalıştırmaları görebilirsiniz. Puanları görüntülemek `evaluations:read` izni gerektirir. -## Bir çalışmanın neden düşük puan aldığını görün +## Bir çalıştırmanın neden düşük puan aldığını görün -Bir sayı size bir çalışmanın zayıf olduğunu söyler; oturum sayfası sana neden olduğunu söyler. Herhangi bir çalışmayı açın ve sağ panel başlık özeti ile başlar, sonra her boyut başına sizin değerlendiricinin kendi muhakemesi ile bir bar gösterir; böylece "bu, doğrulukta 0,4 aldı" ila yanlış yaptığı kesin iddianın saniyeler içinde olursunuz. +Bir sayı size bir çalıştırmanın zayıf olduğunu söyler; oturum sayfası size neden olduğunu gösterir. Herhangi bir çalıştırmayı açın ve sağ panel başlık özeti ile başlar, ardından her boyut için bir çubuk ve değerlendiricinizin her birinin altında kendi akıl yürütmesini gösterir. Böylece "bu gerçekçilikte 0,4 puan aldı" yerine tam olarak saniye cinsinde yanlış anlaşıldığı iddiayı görürsünüz. -![Bir oturumun sağ paneli: üstteki değerlendirme özeti, sonra her boyut puan barı ve her birinin altında gerekçelendirme, tam çalışma etkinliği zaman çizelgesi yanında](/agenteye/images/session-detail.png) +![Bir oturumun sağ paneli: üstte değerlendirme özeti, sonra her boyut başına skor çubukları ve her birinin altında akıl yürütme, tam olay zaman çizelgesinin yanında](/agenteye/images/session-detail.png) -*Oturum detay görünümü: özet, boyut başına puan barları ve her puanın ardındaki gerekçelendirme, çalışmanın etkinlik zaman çizelgesi yanında.* +*Oturum ayrıntı görünümü: özet, boyut başına skor çubukları ve her puanın gerekçesi, çalıştırmanın etkinlik zaman çizelgesiyle yanyana.* -Daha keskin bir değerlendirici yayınladınız mı veya puanlanmadan önce çöken bir çalışmaya mı bakıyorsunuz? Bir **re-evaluate** (yeniden değerlendir) düğmesi (`evaluations:trigger` tarafından kısıtlanmış) oturumu yerinde yeniden puanlar ve taze sonucu zaman çizelgesine ekler; böylece eski puanlar geçmiş olarak görünür kalır. **`//sessions/`** adresinde bulacaksınız. +Daha keskin bir değerlendirici mi gönderdiz, yoksa çalıştırılmadan önce kilitlenmemiş bir çalıştırmaya mı bakıyorsunuz? Bir **re-evaluate** düğmesi (`evaluations:trigger` tarafından kontrol edilen) oturumu yerinde yeniden puanlar ve yeni sonucu zaman çizelgesine ekler, böylece önceki puanlar geçmiş olarak görünür kalır. Bunu **`//sessions/`** adresinde bulacaksınız. -## Kaliteyi filo genelinde izleyin +## Kalite eğilimini filodaki tüm birimler arasında izleyin -Bir çalışmanın düşük puanlaması gürültüdür; bütün bir kohort kayıyorsa bu sinyaldir. Kaydedilmiş panolar puanlarınızı bir bakışta izleyebileceğiniz bir eğilime dönüştürür: bu hafta ortalama yardımcılık, geçen hafta ile karşılaştırılır, aracı başına, ortam başına. +Bir çalıştırma düşük puan almak gürültüdür; bütün bir kohortin kayması bir sinyal. Kaydedilmiş panolar puanlarınızı bir bakışta izleyebileceğiniz bir trende dönüştürür: bu hafta ortalama yararlılık geçen haftaya kıyasla, aracı başına, ortam başına. -![Bir kalite panosu: değerlendirici boyutu başına ortalama puan barları ve zaman içinde bir trend](/agenteye/images/dashboard-quality.png) +![Kalite panosu: değerlendirici boyutu başına ortalama puan çubukları zaman içinde bir trendi ile birlikte](/agenteye/images/dashboard-quality.png) -*Kaydedilmiş bir kalite panosu, öne çıkardığınız puan anahtarlarını trendler; böylece yavaş bir sürükleme, olay haline gelmeden çok önce açık hale gelir.* +*Kaydedilmiş kalite panosu, öne sürdüğünüz skor anahtarlarını trendi oluşturur, böylece yavaş kayış olay haline gelmeden çok önce açıkça görülür.* -Panolar **`//dashboards`** adresinde yaşarlar (kenar çubuğu → *analyze* → *dashboards*), tüm kuruluşunuz genelinde paylaşılır ve her kart eşleşen oturumları toplar: kaç tane, her öne çıkan puanın ortalaması ve trend kıvılcım çizgisi. "Oturumlarda aç", sizi doğrudan herhangi bir numaranın arkasındaki önceden filtrelenmiş çalışmalara bırakır. Görüntülemek için `dashboards:read` artı `evaluations:read` gerekir. +Panolar **`//dashboards`** adresinde bulunur (kenar çubuğu → *analyze* → *dashboards*), tüm kuruluşunuz genelinde paylaşılır ve her kart eşleşen oturumları toplar: kaç tane, her öne sürülen skorun ortalaması ve bir eğilim kıvılcımı. "Oturumlarda aç" sizi herhangi bir sayının arkasındaki önceden filtrelenmiş çalıştırmalara doğrudan bırakır. Görüntülemek `dashboards:read` artı `evaluations:read` gerektirir. -## Bir kez değerlendiriciye bağlanın +## Bir değerlendiriciyi bir kez bağlayın -Puanlama gönüllü ve Failproof AI Observability'yi bir puanlayıcıya işaret edene kadar tamamen kapalı kalır. Bir küçük HTTP hizmeti (Observability, kopyalayabileceğiniz çalışan bir referans seviyesiyle birlikte gelir), sunucunuzda iki değer ayarlarsınız ve o zamandan sonraki her çalışma sizin için puanlanır. Tam gözden geçirme, puanlama kontratı ve SDK derin kılavuzda yaşıyor. +Puanlama opsiyonel'dir ve Failproof AI Observability'yi bir puanlamacıya işaret edene kadar tamamen kapalı kalır. Bir küçük HTTP hizmeti ayarlarsınız (Observability kopyalayabileceğiniz çalışan bir referans ile gelir), sunucunuzda iki değer belirlersiniz ve o andan itibaren her çalıştırma sizin için puanlanır. Tam kılavuz, puanlama sözleşmesi ve SDK, derinlemesine kılavuzda bulunur. -Hangi boyutların başlangıçta puanlamaya değer olduğundan emin misiniz? [Değerlendirici aracı yeteneği](/tr/agenteye/evaluator-skill), kodlama aracınızın kendi oturumlarınıza karşı bunu belirlemesini sağlar, ardından hizmeti kurar ve dağıtır. +Hangi boyutların ilk etapta puanlanmaya değer olduğundan emin misiniz? [Değerlendirici aracı becerisi](/tr/agenteye/evaluator-skill) kodlama aracınızın bunu kendi oturumlarınıza karşı işlemesini sağlar, ardından hizmeti derler ve dağıtır. -## İlişkili +## İlgili -- [Değerlendirme paketi](/tr/agenteye/evaluation-suite): değerlendiriciye, puanlama kontratına ve SDK'ya bağlanın. -- [Değerlendirici aracı yeteneği](/tr/agenteye/evaluator-skill): bir kodlama aracının puan boyutlarınızı seçmesine ve değerlendiriciye oluşturmasına izin verin. -- [Oturumlar](/tr/agenteye/sessions): puanların göründüğü çalışma başına ızgara. +- [Değerlendirme paketi](/tr/agenteye/evaluation-suite): değerlendiricinizi, puanlama sözleşmesini ve SDK'yı bağlayın. +- [Değerlendirici aracı becerisi](/tr/agenteye/evaluator-skill): kodlama aracınızın skor boyutlarınızı seçip değerlendiricisini derlemesini sağlayın. +- [Oturumlar](/tr/agenteye/sessions): puanların göründüğü çalıştırma başına ızgara. - [Panolar](/tr/agenteye/dashboards): kuruluşunuz genelinde kalite eğilimlerini kaydedin ve paylaşın. -- [Denetimler](/tr/agenteye/audits): Observability'nin diğer otomatik kalite özelliği, oturum arası araştırmalar için. \ No newline at end of file +- [Denetimler](/tr/agenteye/audits): Observability'nin diğer otomatik kalite özelliği; oturum öncesi araştırmalar için. \ No newline at end of file diff --git a/docs/tr/agenteye/evaluator-skill.mdx b/docs/tr/agenteye/evaluator-skill.mdx index 08ca9861..924b1d52 100644 --- a/docs/tr/agenteye/evaluator-skill.mdx +++ b/docs/tr/agenteye/evaluator-skill.mdx @@ -1,167 +1,168 @@ --- -title: "Failproof AI Gözlemlenebilirlik Değerlendirici Ajan Becerisi" -description: "\"Ajanımız bazen kötü performans gösteriyor\" düşüncesinden dağıtılmış bir puanlama hizmetine geçin; kodlama ajanınız hem kararı hem de oluşturmayı yapsın." +title: "Failproof AI Gözlemlenebilirlik Değerlendirici Ajanı Becerisi" +description: "\"Sanırım ajanımız bazen kötü performans gösteriyor\" düzeyinden dağıtılmış bir puanlama hizmetine geçin; kodlama ajanınız hem karar verme hem de oluşturma işlemini yapıyor." --- -*"Ajanımız bazen kötü performans gösteriyor"* düşüncesinden dağıtılmış bir puanlama hizmetine geçin; kodlama ajanınız hem kararı hem de oluşturmayı yapsın. **Failproof AI Gözlemlenebilirlik değerlendirici becerisi** (`agenteye-evaluator`), bir *Ajan Becerisidir*: bir kodlama ajan (Claude Code veya Codex gibi) tarafından isteğe bağlı olarak yüklenen, bir klasör içinde barındırılan talimatlar. Ajanı, *sizin* ajan için izlenmeye değer olan kalite boyutlarını belirlemek, ardından [değerlendirici hizmetini](/tr/agenteye/evaluation-suite) yazıp, test edip ve dağıtmak öğretir. -Bu sistem **değildir**: barındırılan bir puanlayıcı, yüklendiğiniz bir kayıt defteri veya bir eklenti sistemi. Değerlendiricileriniz, [Değerlendirme paketi](/tr/agenteye/evaluation-suite) kılavuzunda açıklandığı gibi, kendi altyapınızda çalışan kendi HTTP hizmetiniz olarak kalır. Beceri, ajanınızı bunu iyi inşa etmeyi öğretir; bu nedenle yaptığı her şey, aynı kodu yazarak siz de yapabilirsiniz. +*"Sanırım ajanımız bazen kötü performans gösteriyor"* düzeyinden dağıtılmış bir puanlama hizmetine geçin; kodlama ajanınız hem karar verme hem de oluşturma işlemini yapıyor. **Failproof AI Gözlemlenebilirlik değerlendirici becerisi** (`agenteye-evaluator`), bir *Ajan Becerisi*'dir: bir kodlama ajanının (Claude Code veya Codex gibi) isteğe bağlı olarak yüklediği, küçük bir talimat klasörü. Ajanı, *sizin* ajanınız için izlenmeye değer kalite boyutlarını belirlemesi, ardından bu boyutları puanlayan [değerlendirici hizmetini](/tr/agenteye/evaluation-suite) yazmasını, test etmesini ve dağıtmasını öğretir. + +Bu, barındırılan bir puanlayıcı, bir kayıt defteri ya da bir eklenti sistemi **değildir**. Değerlendiricileriniz, [Evaluation suite](/tr/agenteye/evaluation-suite) kılavuzunda açıklandığı gibi tamamen sizin altyapınızda kendi HTTP hizmetiniz olarak kalır. Beceri sadece ajanınızın bunu iyi bir şekilde oluşturmasını öğretir; yani yaptığı her şeyi siz de aynı kodu yazarak yapabilirsiniz. --- -## Zor kısım neyi puanlamak gerektiğine karar vermek +## Zor kısım ne puanlanacağına karar vermektir -SDK yüzeyi küçüktür — bir dekoratör ve iki model — ve bir ajan bunu [kontratı](/tr/agenteye/evaluation-suite#http-contract) tek başına yazabilir. Sorun burada değildir. Sorun, yanlış şeyi puanlamalarıdır; yanlış şeyi puanlayan bir değerlendirici hiç olmamasından daha kötüdür: herkesin görmezden gelmeyi öğrendiği bir pano üretir. +SDK yüzeyi küçüktür — bir dekoratör ve iki model — ve bir ajan bunu tek başına [sözleşmeden](/tr/agenteye/evaluation-suite#http-contract) yazabilir. Sorun burası değildir. Değerlendiriciler yanlış şeyi puanladıkları için başarısız olurlar ve yanlış şeyi puanlayan bir değerlendirici hiçbirinden daha kötüdür: herkesin görmezden gelmeyi öğrendiği bir gösterge paneli üretir. -Bu nedenle becerinin çoğu, kod yazmadan önceki kısımdır. Ajanı sizi görüşmeye (*"iyi giden bir işlemi anlatın; şimdi kötü gideni"*), ardından [`agenteye` CLI](/tr/agenteye/cli) aracılığıyla gerçek seanslarınızı çekerek end-to-end okumaya alır. Bu iki yarı genellikle anlaşamaz ve arası fark önemlidir: ölçmeyi niyet ettiğiniz şey ile transkriplerinizin gerçekten destekleyebileceği şey arasındaki boşluk. Bir boyut ancak **olaylardan hesaplanabilir** ve **ayırıcı** ise hayatta kalır — eğer hem iyi çalışmanızda hem de kötü çalışmanızda 0.9 puan alırsa, hiçbir şey öğretmez ve kesilir. +Bu nedenle becerinin çoğu, herhangi bir kod yazılmadan önceki kısımdır. Ajan sizi sorgulamasını yapması (*"iyi giden bir çalıştırmayı açıklayın; şimdi kötü giden bir tane"*), ardından gerçek oturumlarınızı [`agenteye` CLI](/tr/agenteye/cli) aracılığıyla çekerek ve bunları baştan sona okuması. Bu iki yarı genellikle anlaşamaz ve bu boşluk amaçtadır: ölçmeyi niyetlediğiniz şey ile transkriptlerinizin gerçekte destekleyebileceği şey arasındaki fark. Bir boyut sadece etkinliklerden **hesaplanabilir** ve **ayırt edici** ise ayakta kalır — eğer iyi çalıştırmanızda ve kötü çalıştırmanızda 0,9 puan alırsa, hiçbir şey öğretmez ve silinir. -Geri dönen şey, 2-4 boyutun bir teklifi ve ona ilişkin akıl yürütmedir; bir satır yazılmadan önce sizin onay vermeniz için. +Geri dönen şey, herhangi bir satır yazılmadan önce onayınız için verilen, akıl yürütme ekli 2-4 boyutun bir önerisidir. ```mermaid flowchart TD - YOU["siz: 'Destek botum için evaluasyonlar istiyorum'"] --> AGENT["kodlama ajan (Claude Code / Codex)
agenteye-evaluator becerisini yükler"] - AGENT -->|"görüşme: iyi vs kötü nasıl görünür?"| YOU - AGENT -->|"agenteye --json sessions / events"| DATA["gerçek seanslarınız
aslında ne olur"] - DATA --> DIMS["2-4 boyut, siz onay verirsiniz"] - DIMS --> SVC["değerlendirici hizmetiniz
agenteye-evaluator SDK"] - SVC --> SCORES["puanlar panoya
ve agenteye evallere iner"] + YOU["siz: 'Destek botumuz için evals istiyorum'"] --> AGENT["kodlama ajanı (Claude Code / Codex)
agenteye-evaluator becerisini yükler"] + AGENT -->|"görüşme: iyi ve kötü neye benziyor?"| YOU + AGENT -->|"agenteye --json sessions / events"| DATA["sizin gerçek oturumlarınız
gerçekte neler oluyor"] + DATA --> DIMS["2-4 boyut, onayınız için"] + DIMS --> SVC["sizin değerlendirici hizmetiniz
agenteye-evaluator SDK"] + SVC --> SCORES["puanlar gösterge paneline
ve agenteye evals'e düşer"] ``` --- -## Diğer değerlendirme bileşenleriyle ilişkisi +## Diğer değerlendirme parçalarıyla ilişkisi -Dört belge puanlamayı kapsar ve sırayla birbirini devreye sokar: +Dört belge puanlamayı kapsar ve sırayla birbirlerine devredilir: -| Sayfa | Nedir | Ne zaman kullanın | +| Sayfa | Ne olduğu | Ne zaman kullanılır | |---|---|---| -| **[Değerlendirmeler](/tr/agenteye/evaluations)** | Özellik: oturum ızgarasında puanlar, panolar, yeniden değerlendir | Otomatik puanlamanın ne getirdiğini bilmek istiyorsunuz | -| **[Değerlendirme paketi](/tr/agenteye/evaluation-suite)** | HTTP kontratı, SDK, sunucu ortam değişkenleri | Değerlendiricinin kendisini uygulıyor veya debug ediyor | -| **Değerlendirici becerisi** (bu belge) | Puanlaycı tasarlamada *ve* oluşturmada doğal dil giriş kapısı | "Evaluasyonlar istiyorum" ile çalışan bir hizmetin kapısında olmak istiyorsunuz | -| **[CLI becerisi](/tr/agenteye/cli-skill)** | `agenteye` CLI'de doğal dil giriş kapısı | Zaten sahip olduğunuz puanları *okumak* istiyorsunuz | -| **[Python SDK becerisi](/tr/agenteye/python-sdk-skill)** | Ajanınızı enstrümanter etmekte doğal dil giriş kapısı | Ajanınız henüz seanslar yaymıyor — puanlanacak hiçbir şey yok | +| **[Evaluations](/tr/agenteye/evaluations)** | Özellik: oturumlar ızgarasında puanlar, gösterge panelleri, yeniden değerlendir | Otomatik puanlamanın size ne getirdiğini bilmek istiyorsunuz | +| **[Evaluation suite](/tr/agenteye/evaluation-suite)** | HTTP sözleşmesi, SDK, sunucu ortam değişkenleri | Değerlendiriciyi kendiniz uyguluyorsunuz veya hata ayıklıyorsunuz | +| **Evaluator skill** (bu belge) | Puanlayıcı tasarımı *ve* oluşturma üzerine doğal dil ön kapısı | "Evals istiyorum" düzeyinden çalışan bir hizmete geçmek istiyorsunuz | +| **[CLI skill](/tr/agenteye/cli-skill)** | `agenteye` CLI üzerine doğal dil ön kapısı | Zaten sahip olduğunuz puanları *okumak* istiyorsunuz | +| **[Python SDK skill](/tr/agenteye/python-sdk-skill)** | Ajanınızı enstrüman etme üzerine doğal dil ön kapısı | Ajanınız henüz oturum göndermiyorsa — puanlanacak hiçbir şey yok | -### CLI becerisi ile karşılaştırma: oluştur versus oku +### CLI becerisine karşı: oluşturma versus okuma -İki beceri kasıtlı olarak örtüşmez ve her ikisini yüklemek normal kurulumudur — ajan ne sorduğunuza bağlı olarak aralarında seçim yapar: +İki beceri bilinçli olarak çakışmayan, ve her ikisini de kurmak normal ayar — ajan, sorduğunuza göre ikisi arasında seçim yapar: -- **`agenteye-evaluator`** (bu belge) puanları *üreten* şeyi oluşturur. İşi puanlar ilk kez inmesi sırasında biter. -- **[`agenteye-cli`](/tr/agenteye/cli-skill)** zaten var olan puanları okur (`agenteye evals`). *"Bu hafta kalite düştü mü?"* onun sorusudur, bu becerinin değil. +- **`agenteye-evaluator`** (bu belge) puanları *üreten* şeyi oluşturur. İşi puanlar ilk kez iniş yaptığında biter. +- **[`agenteye-cli`](/tr/agenteye/cli-skill)** zaten var olan puanları okur (`agenteye evals`). *"Kalite bu hafta düştü mü?"* onun sorusudur, bu becerinin değil. --- ## Ön Koşullar -1. **`agenteye` CLI yüklü ve oturum açmış** (`pipx install agenteye`, ardından `agenteye login`). Beceri bunu iki kez kullanır: tasarladığı gerçek seansları çekmek için ve seansların sonunda puanlarınızın geldiğini doğrulamak için. Oturumunuzun `events:read` gereksinimi vardır, ayrıca bu son kontrol için `evaluations:read`. CLI becerisi ile birlikte, e-posta ile gönderilen tek kullanımlık kod girişini **tamamlayamaz**. -2. **Değerlendiricinin yaşayacağı bir yer.** Bir imaja yerleştirilir ve uzun süreli bir hizmet olarak çalıştırılır; bu nedenle gerçek bir repo'ya ihtiyaç vardır, geçici bir dosyaya değil. Değerlendiriciler sık sık kendi repo'sunda yaşar, puanlanan ajanından ayrı — beceri var olanı arar ve yeni bir tane oluşturmadan önce sorar. -3. **`agenteye-evaluator` SDK tekerleği** — ajanınız `pip` komutlarını yazmaya başlamadan sonraki bölümü okuyun. +1. **`agenteye` CLI yüklenmiş ve oturum açılmış** (`pipx install agenteye`, ardından `agenteye login`). Beceri bunu iki kez kullanır: tasarladığı gerçek oturumları çekmek için ve puanlarınızın sonunda indiğini onaylamak için. Oturumunuzun `events:read` ve son kontrol için `evaluations:read` izinleri gerekir. CLI becerisinde olduğu gibi, e-postayla gelen tek seferlik kod girişini sizin için **tamamlayamaz**. +2. **Değerlendiricinin yaşayacağı bir yer.** Bir görüntüye oluşturulur ve uzun süreli bir hizmet olarak çalıştırılır; bu nedenle gerçek bir depo gerekir, scratch dosyası değil. Değerlendiriciler genellikle puanlandığı ajandan ayrı, kendi deposunda yaşarlar — beceri mevcut olanı arar ve yeni bir tane oluşturmadan önce sorar. +3. **`agenteye-evaluator` SDK tekerleği** — ajanınız `pip` komutları yazmaya başlamadan önce sonraki bölümü okuyun. --- -## Nereden alınır +## Nereden bulabilirsiniz -Beceri, Failproof AI'ın herkese açık beceri koleksiyonunda yayınlanır: +Beceri, Failproof AI'ın genel becerileri koleksiyonunda yayınlanmıştır: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -Depo herkese açıktır ve becerinin kendi kimlik bilgisine ihtiyacı yoktur — yalnızca `agenteye` CLI'yi oturum açtığınız seansla çalıştırır ve kodunuzu *kendi* repo'nuzda yazar. Kendi klasörü olarak gönderilir ve `pipx install agenteye` paketi içinde **değildir**; bu nedenle onu orada aramayın. +Depo halkadır ve becerinin kendi kimlik bilgisine ihtiyacı yoktur — sadece `agenteye` CLI'yi oturum açtığınız seansla çalıştırır ve kodunuzu *sizin* depoda yazmanız. Kendi klasörü olarak gönderilir ve `pipx install agenteye` paketi içinde **değildir**, bu nedenle orada aramayın. -## Becerisini Kurma +## Beceriyi Kurma -En hızlı yol [`skills`](https://skills.sh) CLI'dir; bu klasörü getirir ve ajanınızın baktığı yere bırakır: +En hızlı yol [`skills`](https://skills.sh) CLI'sidir, klasörü getirin ve ajanınızın aradığı yere bırakır: ```bash -# Claude Code, yalnızca bu proje +# Claude Code, sadece bu proje npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -# her proje (~/.claude/skills/ dosyasına yükler) +# her proje (~/.claude/skills/ kurulu) npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy -# Yerine Codex +# Codex yerine npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -Ardından diğer beceriler gibi yönetin: +Diğer beceriler gibi yönetin: ```bash -npx skills list -a claude-code # ne yüklü -npx skills update agenteye-evaluator # en son sürümü çek +npx skills list -a claude-code # neler yüklenmiş +npx skills update agenteye-evaluator # en son versiyonu çek npx skills remove agenteye-evaluator # kaldır ``` -Elle yüklemek tercih misiniz? Bir Ajan Becerisi, `SKILL.md` içeren bir klasördür (artı isteğe bağlı referanslar); bu nedenle kopyalama işe yarar: +El ile kurmayı tercih ediyor? Ajan Becerisi sadece bir `SKILL.md` içeren bir klasördür (plus isteğe bağlı referanslar), böylece kopyalama da işe yarar: -- **Claude Code**: `agenteye-evaluator/` klasörünü `~/.claude/skills/` (her proje) veya `/.claude/skills/` (yalnızca bu repo) içine koyun. Claude Code bunu otomatik olarak bulur — `/skills` listesi ile doğrulayın veya sadece evaluasyonlar isteyin. -- **Codex (OpenAI)**: Codex aynı `SKILL.md` dosyasını okur. Paketlenmiş `agents/openai.yaml`, `allow_implicit_invocation: true` ayarlar; bu nedenle bir görev eşleştiğinde Codex beceriyi otomatik seçer; aksi takdirde açıkça `$agenteye-evaluator` olarak çağırın. +- **Claude Code**: `agenteye-evaluator/` klasörünü `~/.claude/skills/` (her proje) veya `/.claude/skills/` (sadece o depo) içine koyun. Claude Code bunu otomatik keşfeder — `/skills` listesi ile doğrulayın veya sadece evals isteyin. +- **Codex (OpenAI)**: Codex aynı `SKILL.md`'yi okur. Bundled `agents/openai.yaml` `allow_implicit_invocation: true` ayarlanmıştır, bu nedenle bir görev eşleştiğinde Codex becerileri otomatik olarak seçer; aksi takdirde `$agenteye-evaluator` olarak açıkça çağırın. --- ## SDK genel PyPI'de değildir -> **Uyarı:** Bir ajanın SDK yüklemesine izin vermeden önce bunu okuyun. +> **Uyarı:** Ajanın SDK'yı kurmasına izin vermeden önce bunu okuyun. -Beceri herkese açıktır; onu çalıştırdığı SDK değildir. `agenteye-evaluator` yalnızca özel bir sürüm yapı olarak gönderilir ve `agenteye` gibi farklı olarak, ad **genel PyPI'de açıklanmadıdır** — bu nedenle basit `pip install agenteye-evaluator` komutu, üretim transkriplerinizi okuyan hizmete başka bir kişinin paketini çekebilir. Bu bir yazım hatası değil, bir tedarik zinciri sorunudur. +Beceri halkadır; bunu çalıştırması gereken SDK değil. `agenteye-evaluator` sadece özel sürüm yapısı olarak gönderilir ve `agenteye` aksine, ad genel PyPI'de **talep edilmemiş** — bu nedenle `pip install agenteye-evaluator` üretim transkriptlerinizi okuyan hizmete başka birinin paketini çekebilir. Bu yazım hatası değil, bir tedarik zinciri sorunudur. -Beceri bunu bilir ve yerine bir yükleme merdiveninde aşağı doğru çalışır; ilk geçerli basamağında durur: AgentEye repo'sunun içindeyseniz monorepo kaynağı; aksi takdirde GitHub Releases'ten özel sürüm tekerleği (erişim gerekir); ikisi de erişilemezse **durur ve Failproof AI iletişim kişinizden tekerleği istemenizi söyler** uydurmak yerine. +Beceri bunu bilir ve bunun yerine bir kurulum merdiveninden aşağıya doğru çalışır, uygulanacak ilk basamağında durur: AgentEye deposunun içindeyseniz monorepo kaynağı, aksi takdirde GitHub Releases'ten özel sürüm tekerleği (erişim gerekir) ve hiçbiri ulaşılamıyorsa **durur ve sizi Failproof AI temasa geçmesi için tekerleği istemeye söyler** improvize etmek yerine. -Eğer ajanınız genel PyPI'den basit `pip install agenteye-evaluator` önerirse, bu becerinin hiç yüklenmediğini gösterir. Orada durun ve yüklendiğini kontrol edin. +Yani ajanınız genel PyPI'den çıplak `pip install agenteye-evaluator` önerirse, bu becerinin asla yüklenmediğinin işaretidir. Orada durun ve kurulu olup olmadığını kontrol edin. --- -## Ona ne sorabilirsiniz +## Ne sorabileceğiniz -Gerçek bir tur sonu, belirsiz bir sorudan imza faydalı bir tasarımla biter, kodla değil: +Gerçek bir gidiş-dönüş, muğlak bir istek ile başlar ve kod ile değil, imzalı bir tasarım ile biter: ```text -siz ▸ Destek botumuz için evaluasyonlar istiyorum. Bazen kötü - olduğunu düşünüyorum. +siz ▸ Destek botumuz için evals istiyorum. Sanırım bazen kötü performans gösteriyor. -ajan ▸ Herhangi bir şey yazmadan önce: iyi giden bir işlemi anlatın, - ve kötü gideni. +ajan ▸ Herhangi bir şey yazmadan önce: iyi giden bir çalıştırmayı ve + kötü giden bir çalıştırmayı açıklayın. -siz ▸ İyi: dokümanlardan cevaplar. Kötü: yok sayıyor, - veya "destek ile iletişime geçin" diyor. +siz ▸ İyi: belgelerden cevap veriyor. Kötü: uydurma yapıyor, + ya da vazgeçip "destek ekibiyle iletişime geçin" diyor. -ajan ▸ Çalışıyor: agenteye --json sessions --status error --since 7d - 5 seansı okuyorum, ikisini kötü olarak yazıyorsunuz. +ajan ▸ Çalıştırıyor: agenteye --json sessions --status error --since 7d + 5 oturumu okuyuyor, kötü dediğiniz ikisini içeren. - Söyledikleriniz gerçekçiliği ve sapıtmayı söylüyor. Transkripler - sapıtmada anlaşıyor (5'in 2'si destek devredimiyle bitiyor, - ve model_response.content'de açık), fakat gerçekçiliğin - olaylarda taşımadığı bir yer gerçeğine ihtiyacı vardır. + Sözcükleriniz doğruluk ve kaçınmadan bahsediyor. Transkriptler + kaçınmada anlaşıyor (5'ten 2'si destek yönlendirmesi ile bitiyor, + ve model_response.content'te açık), ama doğruluk için + etkinliklerinizin taşımadığı bir yer gerçeği gerekiyor. - Yani üç şeyi puanlarım: - - sapıtma kurallar, ucuz, iki işlemi ayırır - - araç_verimliği kurallar, işlemler arası döngüyü yakalar - - temelcilik LLM hakim: aldığı doklarda her iddia var mı? + Yani üç şey puanlardım: + - kaçınma kurallar, ucuz, çalıştırmalarınızı ayırıyor + - tool_efficiency kurallar, run-004'teki retry döngüsünü yakalar + - groundedness LLM hakim: alınan belgelerdeki her iddia geçerli mi? - "gerçekçiliğin" olmayan yer gerçeğine ihtiyacı vardır; temelcilik - transkriplerinizin fiilen destekleyebildiği en yakın şey. - Bu üç adla iyi misiniz? Daha sonra yeniden adlandırma geçmişi böler. + "doğruluk" bizim sahip olmadığımız yer gerçeği gerekir; + groundedness transkriptlerinizin gerçekte destekleyebileceği + en yakın şeydir. Bu üç adla sorun var mı? Sonra yeniden adlandırma + geçmişi böler. -siz ▸ evet +siz ▸ hayır -ajan ▸ Bu repo'da değerlendirici yok. Bir tane buraya kurmalı mıyım, - yoksa başka yerde varsa? +ajan ▸ Bu depoda değerlendirici yok. Burada bir tane oluşturasını mı istiyorsunuz, + yoksa başka bir yerde var mı? ``` -Buradan kurallar tabanlı boyutları ilk yazar (bedava, anında, belirleyici), bunları kilitlenmeler ve asla bitmeyenler de dahil gerçek yakalanmış seanslar aracılığıyla test eder, ve yalnızca öznel boyut için LLM hakime ulaşır. [Gönderici sınırlarını](/tr/agenteye/evaluation-suite#configuring-the-server) bilir — 30s istek zaman aşımı ve 8 eşzamanlı çağrı dağıtım genelinde — yani hakim güvenilir şekilde sığmazsa, `JobPending` ile eşzamansız gider, hakim iptal edilmiş ve beş kez yeniden denenmiş olmasına izin vermez. +Oradan kural tabanlı boyutları ilk yazıyor (ücretsiz, anında, belirlenimci), bunları çıkan ve asla bitmeyen, naif değerlendiricileri çöken gerçek oturumlar dahil test ediyor, ve sadece öznel boyut üzerinde LLM hakimi yer alıyor. [Gönderen sınırlarını](/tr/agenteye/evaluation-suite#configuring-the-server) biliyor — 30s istek zaman aşımı ve dağıtım genelinde 8 eşzamanlı çağrı — böylece hakim güvenilir bir şekilde uymayacaksa, `JobPending` ile eşzamansız gidiyor, hakim iptal edilip beş kere yeniden denesin ve beş kat maliyet artsın diye. -Daha sonra dağıtır, iki sunucu ortam değişkenini ayarlar, ve `agenteye --json evals --session-id ` ile doğrular ki puanlar gerçekten indi. Puanlar inmek tek kanıttır. +Ardından dağıtıyor, iki sunucu ortam değişkenini ayarlıyor, ve `agenteye --json evals --session-id ` ile puanların gerçekten indiğini onaylıyor. Puanlar inmek tek ispattır. --- -## Nelere dikkat edin +## Dikkat Edilmesi Gerekenler -- **Boyut adları neredeyse kalıcıdır.** Puan anahtarları keyfi dizeler ve platform gönderdiğiniz şeyi eğilimlendirir; bu nedenle aşağı akış hiçbir şey kötü seçimi düzeltmez. Daha sonra yeniden adlandırın ve geçmiş bölünür: eski seanslar eski anahtarı tutar ve eğilim kırılır. Bu, becerinin kod yazmadan önce açık onay aldığı nedeni — bu istem ciddiye alın. -- **Sabitler gerçek üretim transkriplerileridir.** Gerçek seanslar aracılığıyla tasarlamak onları diske çekmek anlamına gelir ve müşteri verisi içerebilirler. Beceri git'e teslim etmeden önce sorar; şüphede, `fixtures/` repo dışında tutun ve her geliştirici kendi tarafını çeksin. -- **Ajan her transkripti okuyan bir hizmet yazar ve dağıtır.** Sizin olarak davranır, CLI oturumunuzun izinleriyle sınırlı; fakat üretim verisine dokunulan diğer kodlar gibi değerlendiriciye bakın. +- **Boyut adları neredeyse kalıcıdır.** Puan anahtarları keyfi dizelerdir ve platform gönderdiğiniz her şeyi eğilimlendirir, bu da aşağıda hiçbir şey kötü seçimi düzeltmez. Sonra yeniden adlandırın ve geçmiş bölünür: eski oturumlar eski anahtarı tutarlar ve trend kırılır. Bu yüzden beceri kod yazmadan önce açık onay alır — o istemi ciddiye alın. +- **Fixtures gerçek üretim transkriptleridir.** Gerçek oturumlar karşısında tasarımı öğrenmek onları diske çekerek başka yoldan yapılır ve müşteri verisi içerebilirler. Beceri git'e taahhüt etmeden önce sorar; şüphede ise `fixtures/`'i depo dışında tutun ve her geliştirici kendi'ilerini çeksin. +- **Ajan, her transkripti okuyan bir hizmet yazar ve dağıtır.** Siz olarak davranır, CLI oturumunuzun izinleriyle sınırlandırılmış, ama değerlendiriciyi üretim verilerine dokunan diğer kodlar gibi gözden geçirin. --- -## Sonraki adımlar +## Sonraki Adımlar -- **[Değerlendirme paketi](/tr/agenteye/evaluation-suite)**: HTTP kontratı, SDK ve becerinin yapılandırdığı sunucu ortam değişkenleri. -- **[Değerlendirmeler](/tr/agenteye/evaluations)**: puanlar indikten sonra nerede gösterildiği. -- **[CLI becerisi](/tr/agenteye/cli-skill)**: puan oluşturmak yerine sonuçları okuyan kardeş beceri. -- **[CLI](/tr/agenteye/cli)**: becerinin tasarladığı seanslar verilerinin arkasındaki komut referansı. \ No newline at end of file +- **[Evaluation suite](/tr/agenteye/evaluation-suite)**: HTTP sözleşmesi, SDK ve becerinin yapılandırdığı sunucu ortam değişkenleri. +- **[Evaluations](/tr/agenteye/evaluations)**: puanlar iniş yaptığında gösterilmeleri. +- **[CLI skill](/tr/agenteye/cli-skill)**: puanlayıcı oluşturmak yerine sonuçları okumak için kardeş beceri. +- **[CLI](/tr/agenteye/cli)**: becerinin tasarladığı oturum verilerinin arkasındaki komut referansı. \ No newline at end of file diff --git a/docs/tr/agenteye/event-stream.mdx b/docs/tr/agenteye/event-stream.mdx index 0bb5f16d..3be72824 100644 --- a/docs/tr/agenteye/event-stream.mdx +++ b/docs/tr/agenteye/event-stream.mdx @@ -1,50 +1,50 @@ --- title: "Olay Akışı" -description: "Ajanınız bir şey yaptığı anda, siz bunu görürsünüz." +description: "Aracınız bir şey yaptığı anda, siz bunu görürsünüz." --- -Ajanınız bir şey yaptığı anda, siz bunu görürsünüz. Olay Akışı, üretim ortamındaki her ajan hakkında canlı bilgi almanın yoludur: bekleme yok, log dosyalarında arama yok, ne olduğunu tahmin etme yok. +Aracınız bir şey yaptığı anda, siz bunu görürsünüz. Olay Akışı, üretimdeki her aracının canlı nabzıdır: bekleme yok, log dosyalarında arama yok, ne olduğu hakkında tahmin yok. -![Canlı Olay Akışı: renk kodlu olay satırları gerçek zamanlı olarak aşağıya doğru ilerliyor, ortam, ajan, oturum, olay türü ve serbest metin ile filtrelenebiliyor](/agenteye/images/events-stream.png) +![Canlı Olay Akışı: gerçek zamanlı akan, renkle kodlanmış olay satırları, ortam, ajan, oturum, olay türü ve serbest metne göre filtrelenebilir](/agenteye/images/events-stream.png) -*Kuruluşunuzdaki her ajandan gelen her olay, en yenisi önce, olur olmaz güncelleniyor.* +*Kuruluşunuzdaki her aracıdan gelen her olay, en yeniler önce, gerçekleştikçe güncelleniyor.* -## Her ajan hakkında canlı bilgi +## Her aracının canlı nabzı -Bir ajan çalışmaya başladığında, bir modeli çağırdığında, bir aracı tetiklediğinde, bir hook çalıştırdığında veya bir hatayla karşılaştığında, satır olur olmaz akışın en üstünde görünür. Kuruluşunuzdaki her ajandan gelen her olayı izler, en yenisi önce, böylece her zaman güncel bir resim yerine eski bir resme sahip olmaktan kurtulursunuz. +Bir ajan bir çalıştırma başlattığında, bir modeli çağırdığında, bir araç tetiklediğinde, bir hook çalıştırdığında veya bir hatayla karşılaştığında, satır o an akışın en üstünde görünür. Kuruluşunuzdaki her aracıdan gelen her olayı, en yeniler önce takip eder; böylece her zaman güncel bir görüntünüze sahip olursunuz, eski bir görüntü değil. -Bu, bir yerde log dosyalarını izlemeyi, makineler arasında arama yapmayı, zaman damgalarını elle bir araya getirmeyi gerektirmez. Bir sayfa açarsınız ve zaten üretim ortamını izliyorsunuz. +Bu, bir yerdeki günlük dosyalarını takip etmek anlamına gelmez, makineler arasında arama yapmak anlamına gelmez, zamanı elle bir araya getirmek anlamına gelmez. Bir sayfayı açarsınız ve zaten üretimi izliyor olursunuz. -Satırlar türe göre renk kodludur, böylece her satırı ayrıştırmak yerine akışı bir bakışta okuyabilirsiniz. Bir bakışta, her satır size şunları gösterir: +Satırlar türe göre renkle kodlanmıştır, böylece akışı satır satır ayrıştırmak yerine bir bakışta okuyabilirsiniz. Bir bakışta, her satır size şunları gösterir: -- **Türü**, renk kodlu: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` ve daha fazlası. -- **Neler oldu hakkında tek satırlık bir özet**, çoğu zaman hiçbir şey açmaya gerek kalmadan fikir sahibi olmanız için. -- **Token sayıları** adım için. -- **Bağlam penceresi dolu rozeti** uygulanabilir olduğu durumlarda, böylece komut isteminin büyümesi ve yaklaşan sıkıştırma problem yaşamadan önce görülebilir. +- **Türü**, renkle kodlanmış: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` ve daha fazlası. +- **Olan olayın tek satırlı özeti**, böylece genellikle genel fikir almak için hiçbir şey açmanız gerekmez. +- **Adım için jeton sayıları**. +- **Bağlam penceresi doldurma rozeti**, uygulanabilir olduğu yerde, böylece istem büyümesi ve yaklaşan bir sıkıştırma, sorun olmadan önce görünür hale gelir. -Canlı izlemek, kötü bir dağıtımı, kaçak bir döngüyü veya hata patlamasını yarın log incelemesinde değil, olur olmaz yakalamanız anlamına gelir. +Bunu canlı izlemek, hatalı bir dağıtımı, kaçak bir döngüyü veya hata patlamasını yarın günlük incelemesinde değil, olur olmaz yakalar. -## Önemli olan o tek çalışmayı bulun +## Önemli olan tek çalıştırmayı bulun -Bir şey yanlış görünüyorsa, tüm veriyi istemezsiniz. İstediğiniz, arızalanan tek çalışmadır. Akış hızla filtrelenir: ortama göre, ajana göre, oturuma göre, olay türüne göre veya serbest metne göre. +Bir şey yanlış göründüğünde, ateş borusu istemezsiniz. İstediğiniz, bozulan tek çalıştırmadır. Akış hızla filtre uygulanır: ortama göre, aracıya göre, oturuma göre, olay türüne göre veya serbest metne göre. -Tek bir çalışmayı ilk olayından son olayına kadar izlemek için oturum kimliğine veya ajan kimliğine göre filtreleyin. Tek bir etkinlik türünü yalıtmak için olay türüne göre filtreleyin, örneğin kuruluş genelinde her `error`. Filtreleri yığın halinde birleştirerek "her yer, her şey" den "bu ajan, üretim ortamında, hata veriyor" a birkaç tıklamayla daraltın, ardından bulduğunuz şey üzerinde harekete geçin. +Oturum kimliğine veya ajan kimliğine göre filtre uygulayarak bir çalıştırmayı ilk olayından son olayına kadar takip edin. Olay türüne göre filtre uygulayarak tek bir etkinlik türünü izole edin, örneğin kuruluş genelinde tek bir görünümde her `error`. Filtreleri "her yerde her şey"den "bu ajan, prod'da, hata veriyor"a birkaç tıkta daraltmak için yığıştırın, ardından bulduklarınız hakkında işlem yapın. -Serbest metin araması, elinizde zaten bulunan bir mesaja, bir araç adına veya bir kimliğe doğru gider, böylece müşteri raporu saniyeler içinde tam çalışmaya dönüşür. +Serbest metin araması, elinizde zaten olan bir mesaja, araç adına veya kimliğe doğrudan gider, böylece bir müşteri raporu saniyeler içinde tam çalıştırmaya dönüşür. -## Nerede bulunur +## Nerede bulabileceğiniz -Olay Akışı kuruluş ana sayfanızdır. Oturum açarsınız ve onu ilk inen yüzey, `//` konumundadır, böylece triage anda başlar. +Olay Akışı, kuruluş ana sayfanızdır. Oturum açarsınız ve bu, `//` konumunda iniş yaptığınız ilk yüzeydir, böylece sorun giderme, vardığınız saniye başlar. -Arkasında, ajanlarınız SDK aracılığıyla olaylar yayınlar, toplayıcı bunları Failproof AI Observability sunucunuza gönderir ve akış kontrol ettiğiniz altyapıya ulaştıkça bunları izler. Işık İzler yerine özetlenmiş görünümü istediğinizde, her çalışmanın olayları Sessions'da tek bir satıra daraltılır, bir tıkla uzaktadır. +Arkasında, aracılar SDK aracılığıyla olaylar yayınlar, toplayıcı bunları Failproof AI Observability sunucunuza gönderir ve akış kontrol ettiğiniz altyapıya ulaştıkça bunları izler. Ham iz yerine toplu görünümü istediğinizde, her çalıştırmanın olayları Sessions üzerinde tek bir satırda daraltılır, bir tıkla uzakta. -Bu, her diğer gözlemci yüzeyinin üzerine inşa ettiği ham doğru kaynaktır, bu nedenle bir sayı başka bir yerde yanlış görünüyorsa, akış aslında ne olduğunu onayladığınız yerdir. +Bu, diğer her gözlem yüzeyinin üzerine inşa ettiği ham gerçek kaynağıdır, bu nedenle başka bir yerde bir sayı yanlış göründüğünde, akış aslında ne olduğunu doğruladığınız yerdir. ## İlgili -- [Sessions](/tr/agenteye/sessions): aynı olaylar çalışma başına tek satıra özetlenerek git tarzı yürütme grafiği ile birlikte. -- [Telemetry](/tr/agenteye/telemetry): ajanlarınızın ne gönderdiği ve olayların akışa nasıl ulaştığı. -- [Error tracking](/tr/agenteye/error-tracking): her şeyin yanlış gittiği bir triage yüzeyi. +- [Sessions](/tr/agenteye/sessions): aynı olaylar çalıştırma başına bir satırda toplamlanmış, git tarzı yürütme grafiğiyle. +- [Telemetry](/tr/agenteye/telemetry): aracılarınız ne gönderir ve olaylar akışa nasıl ulaşır. +- [Error tracking](/tr/agenteye/error-tracking): yanlış giden her şey için tek bir sorun giderme yüzeyi. - [Alerts](/tr/agenteye/alerts): herhangi bir eşiği bir çağrı kuralına dönüştürün. -- [CLI and agents](/tr/agenteye/cli-and-agents): terminalinizden gelen aynı canlı izleme. \ No newline at end of file +- [CLI and agents](/tr/agenteye/cli-and-agents): terminalinizden aynı canlı iz. \ No newline at end of file diff --git a/docs/tr/agenteye/hermes-capture.mdx b/docs/tr/agenteye/hermes-capture.mdx index 5abbbee2..94eb6084 100644 --- a/docs/tr/agenteye/hermes-capture.mdx +++ b/docs/tr/agenteye/hermes-capture.mdx @@ -1,53 +1,53 @@ --- -title: "Hermes session capture" -description: "Ekibinizin Hermes gateway oturumlarını — Slack, Telegram, CLI ve zamanlanmış çalışmalar — AgentEye'a sıradan oturumlar ve olaylar olarak getirin." +title: "Hermes oturum yakalama" +description: "Ekibinizin Hermes gateway oturumlarını — Slack, Telegram, CLI ve zamanlanmış çalıştırmalar — AgentEye'da sıradan oturum ve olaylar olarak getirin." --- -[Hermes](https://hermes-agent.nousresearch.com) ekibinize zaten çalıştıkları yerden cevap verir — Slack, Telegram, CLI, zamanlanmış çalışmalar. Hermes session capture tümünü AgentEye'a sıradan oturumlar ve olaylar olarak getirir, böylece ekibinizin her gün konuştuğu asistan, yazarken yazdığınız ajanlar kadar gözlemlenebilir olur. +[Hermes](https://hermes-agent.nousresearch.com) ekibinize zaten çalıştıkları yerden yanıt verir — Slack, Telegram, CLI, zamanlanmış çalıştırmalar. Hermes oturum yakalama, tümünü AgentEye'da sıradan oturum ve olaylar olarak getirerek, ekibinizin her gün konuştuğu asistan sizin yazdığınız ajanlar kadar gözlemlenebilir hale gelir. -Küçük bir arka plan toplayıcısı Hermes'in yerel oturum deposunu yazıldığı sırada okur ve oturumları AgentEye'a gönderir. [Codex](/tr/agenteye/codex-capture) ve [OpenClaw](/tr/agenteye/openclaw-capture) capture ile aynı şekilde çalışır ve bir toplayıcı aynı anda birkaçını capture edebilir. +Küçük bir arka plan toplayıcı, Hermes'in yerel oturum deposunu yazıldığı sırada okur ve oturumları AgentEye'a gönderir. [Codex](/tr/agenteye/codex-capture) ve [OpenClaw](/tr/agenteye/openclaw-capture) yakalamalarıyla aynı şekilde çalışır ve bir toplayıcı aynı anda birkaçını yakalayabilir. --- -## Ne capture eder +## Neyi yakalar -Makinedeki her Hermes oturumu, hangi kanaldan geldiğine bakılmaksızın capture edilir. Her biri bir AgentEye [session](/tr/agenteye/sessions) olur; kullanıcı ve asistan mesajları, araç çağrıları ve araç sonuçları eşleşen [events](/tr/agenteye/event-stream) olur. +Makinedeki her Hermes oturumu, hangi kanaldan gelirse gelsin yakalanır. Her biri bir AgentEye [oturumu](/tr/agenteye/sessions) haline gelir; kullanıcı ve asistan mesajları, araç çağrıları ve araç sonuçları eşleşen [olaylar](/tr/agenteye/event-stream) olur. -Oturumun başladığı kanal — Slack, Telegram, CLI veya zamanlanmış çalışma — oturumda kaydedilir, böylece onları ayırt edebilir ve birer birer filtreleyebilirsiniz. Yanında oturumun çalıştığı model, başlatıldığı sohbet ve kişi, ve bir oturum başka bir oturum oluşturduğunda, parent'a geri bağlantı gelir. +Oturumun başladığı kanal — Slack, Telegram, CLI veya zamanlanmış çalıştırma — oturumda kaydedilir, böylece onları ayırt edebilir ve birer birer filtreleyebilirsiniz. Yanında oturumun çalıştığı model, sohbetin ve başlatıldığı kişinin ve bir oturum başka birini oluşturduğunda ebeveyn oturuma geri bağlantı gelir. -Oturumlar Hermes tarafından başlatılır başlatılmaz görünür, henüz bir şey söylenmemiş olsa bile, ve bir çevirinin yanıtı ile araç çağrıları gerçekten olduğu sırada kalır. Bir oturum sona erdiğinde neden sona erdiğini, ne kadar tuttuğunu ve kaç token kullandığını da alırsınız. +Oturumlar Hermes bunları başlattığında görüntülenir; henüz hiçbir şey söylenmemiş olsa bile. Bir turun yanıtı ve araç çağrıları gerçekten gerçekleştikleri sırayla kalır. Bir oturum sona erdiğinde, neden sona erdiğini, ne kadar maliyet olduğunu ve kaç token kullandığını da alırsınız. --- -## Açın +## Bunu açın -Capture, etkinleştirene kadar kapalıdır. Toplayıcıyı `events:add` izni olan bir API anahtarıyla kurun ([API keys](/tr/agenteye/api-keys) bölümünü görmek için) ve Hermes capture'ı açın: +Yakalama siz etkinleştirene kadar kapalıdır. Toplayıcıyı `events:add` izni olan bir API anahtarıyla yükleyin ([API anahtarlarına](/tr/agenteye/api-keys) bakın) ve Hermes yakalamayı açın: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -Bu toplayıcıyı kurar, onu arka plan hizmeti olarak kaydeder ve capture'ı başlatır. Çalıştığını doğrulayın: +Bu toplayıcıyı yükler, arka plan hizmeti olarak kaydeder ve yakalamaya başlar. Çalıştığını doğrulayın: ```bash agenteye-collector health ``` -Aynı makinede birden fazla ajan capture ediyor musunuz? Her birinin bayrağını aynı komuta ekleyin — örneğin `--hermes-enabled --codex-enabled`. +Aynı makinede birden fazla ajan yakalıyor musunuz? Her birinin bayrağını aynı komuta ekleyin — örneğin `--hermes-enabled --codex-enabled`. -İlk çalışmada, mevcut Hermes oturumlarınız bir kez backfill edilir ve yeni aktivite birkaç saniye içinde akışa başlar. Hermes'in kendi verileri yalnızca okunur — asla değiştirilmez veya silinmez — ve her mesaj yeniden başlatmalar arasında bile bir kez gönderilir. +İlk çalıştırmada, mevcut Hermes oturumlarınız bir kez geri doldurulur ve yeni aktivite ardından saniyeler içinde akar. Hermes'in kendi verileri yalnızca okunur — hiçbir şekilde değiştirilmez veya silinmez — ve her mesaj, yeniden başlatmalar arasında bile bir kez gönderilir. -`health` ayrıca toplayıcının capture ettiği her şeyin gerçekten AgentEye'a ulaşıp ulaşmadığını da söyler. Bir batch teslim edilemezse tutulur ve yeniden denenir, atılmaz, ve kontrol hala bekleyen bir şey varken sağlıksız rapor verir — bu nedenle "healthy" verilerinizin geldiği anlamına gelir, sadece işlem canlı değildir. +`health` aynı zamanda toplayıcının yakaladığı her şeyin gerçekten AgentEye'a ulaşıp ulaşmadığını size söyler. Bir batch teslimat edilemezse saklanır ve atılmak yerine yeniden denenirken, herhangi bir şey henüz beklemede olduğunda kontrol sağlıksız rapor verir — yani "sağlıklı" verilerinizin ulaştığı anlamına gelir, yalnızca işlemin canlı olduğu değil. --- -## Nerede göründüğü +## Nerede görüntülenir -Capture edilen oturumlar **Sessions**'da ve olayları **Events** akışında görünür, gözlemlediğiniz diğer tüm ajanlar gibi — bu nedenle [session replay](/tr/agenteye/sessions), [search](/tr/agenteye/queries), [evaluations](/tr/agenteye/evaluations) ve [alerts](/tr/agenteye/alerts) hepsi bunlar üzerinde çalışır. Hermes ajanına göre filtreleyerek onları ayrı ayrı görebilirsiniz. +Yakalanan oturumlar **Sessions**'da ve olayları **Events** akışında görüntülenir; gözlemlediğiniz diğer herhangi bir ajan gibi — böylece [oturum tekrar oynatma](/tr/agenteye/sessions), [arama](/tr/agenteye/queries), [değerlendirmeler](/tr/agenteye/evaluations) ve [uyarılar](/tr/agenteye/alerts) bunların tümünde çalışır. Hermes ajanına göre filtreleyin ve bunları kendi başına görün. --- ## Gizlilik -Hermes oturumları tam transkripti içerir — komut çıktısı, dosya içeriği ve ajanın okuduğu veya yazdığı her şey dahil — ve sırlar içerebilir. Capture edilen oturumlar olduğu gibi gönderilir, bu nedenle capture'ı yalnızca bu içeriği AgentEye'da merkezileştirmenin uygun olduğu yerlerde etkinleştirin ve toplayıcıya yalnızca `events:add` ile sınırlandırılmış bir anahtar verin. Verilerinizin nasıl izole tutulduğu hakkında [Security](/tr/agenteye/security) bölümünü görmek için. \ No newline at end of file +Hermes oturumları tam transkripti içerir — komut çıktısı, dosya içeriği ve ajanın okuduğu veya yazdığı her şey dahil — ve sırlar içerebilir. Yakalanan oturumlar olduğu gibi gönderilir, bu nedenle yakalamayı yalnızca bu içeriği AgentEye'da merkezileştirmenin uygun olduğu yerlerde etkinleştirin ve toplayıcıya yalnızca `events:add` kapsamlı bir anahtar verin. Verilerinizin nasıl izole tutulduğu hakkında [Güvenlik](/tr/agenteye/security) bölümüne bakın. \ No newline at end of file diff --git a/docs/tr/agenteye/incidents.mdx b/docs/tr/agenteye/incidents.mdx index fea1afa2..83e9a0e5 100644 --- a/docs/tr/agenteye/incidents.mdx +++ b/docs/tr/agenteye/incidents.mdx @@ -1,50 +1,50 @@ --- title: "Olaylar" -description: "Bir uyarı tetiklendiğinde, herkes olayın açık olduğunu, kimin sahip olduğunu ve şimdiye kadar neler olduğunu görebilir — bir atfedilen zaman çizelgesinde." +description: "Bir uyarı tetiklendiğinde, herkes olayın açık olduğunu, kime ait olduğunu ve şimdiye kadar neler olduğunu görebilir — tek bir atfedilmiş zaman çizelgesinde." --- -Bir uyarı tetiklendiğinde, ilk soru her zaman "kim bunu ele alıyor?" Olaylar buna yanıt verir: bir şey ihlal olduğu anda, herkes olayın açık olduğunu, kimin sahip olduğunu ve tam olarak şimdiye kadar neler olduğunu görebilir; doğrudan bir post-mortem'e verebileceğiniz temiz, atfedilen bir kaydı ile. +Bir uyarı tetiklendiğinde, ilk soru her zaman "kim bununla ilgileniyor?" Olaylar buna cevap verir: bir şey ihlal edildiğinde, herkes olayın açık olduğunu, kime ait olduğunu ve şimdiye kadar tam olarak neler olduğunu görebilir — temiz, atfedilmiş bir kayıt sayesinde bunu doğrudan bir olay sonrası incelemeye sunabilirsiniz. -![Olaylar gelen kutusu: uyarı bağlantılı ve manuel olarak açılmış olay kartları, duruma göre gruplandırılmış, her birinin bir önem düzeyi rozeti ve bir sorumlusu var](/agenteye/images/incidents.png) -*Gelen kutusu açık olayları duruma göre gruplandırır ve önem düzeyi ve sorumlulu göre filtreler, böylece şu anda insan müdahalesine ihtiyaç duyan şeyleri görürsünüz.* +![Olaylar gelen kutusu: uyarıya bağlı ve manuel olarak açılan olay kartları, duruma göre gruplandırılmış, her birinin ciddiyet rozeti ve atanmış kişi bilgisi](/agenteye/images/incidents.png) +*Gelen kutusu açık olayları duruma göre gruplandırır ve ciddiyete ve atanmış kişiye göre filtreler, böylece şu anda insan ilgisine ihtiyaç duyan şeyler görülür.* -## Kimin sahip olduğunu bir bakışta bilin +## Kimin bununla ilgilendiğini bir bakışta bilin -Artık bir sohbet dizisinde "bunu kim bakıyor?" sorusu yok. Bir ihlal otomatik olarak bir olay açar ve bunu paylaşılan bir gelen kutusuna koyar, duruma göre gruplandırılmış. Bunu kabul ederseniz, adınız üzerine yazılır, böylece takımın geri kalanı bunun ele alındığını bilir. Kabul paylaşılmıştır: birçok operatör aynı olayı kabul edebilir ve her biri kendi başına kaydedilir, böylece tam bir savaş odası adları ile gösterilir, birbirinin üzerine basılmaz. Triage için bir sahip atayın ve gelen kutuyu önem düzeyi veya sorumluya göre filtreleyin ve bunu sizinkine indirin. +Artık sohbet başlığında "birisi buna bakıyor mu?" diye sormanıza gerek yok. Bir ihlal otomatik olarak bir olay açar ve bunu paylaşılan bir gelen kutusuna düşürür, duruma göre gruplandırılır. Bunu kabul ettiğinizde adınız üzerine yazılır, böylece takımın geri kalanı bunun halledildiğini bilir. Onay paylaşılır: birden fazla operatör aynı olayı onaylayabilir ve her biri kendi başına kaydedilir, böylece tam bir savaş odası isimlerle gösterilir ve birbirinin üzerine gelir. Triyaj için tek bir sahibi atayın ve ciddiyete veya atanmış kişiye göre gelen kutusunu filtreleyin, böylece yalnızca sizinkini göresiniz. -## Tüm hikaye, bir zaman çizelgesinde +## Tüm hikaye, tek bir zaman çizelgesinde -Olay bittiğinde, zaten yazı işleriniz hazırdır. Herhangi bir olayı açın ve ihlal kanıtını, sorumluları ve abone uygulamasını, yerinde koordinasyon için bir yorum dizisini ve append-only etkinlik zaman çizelgesini alırsınız. +Olay bittiğinde, raporunuz zaten hazırdır. Herhangi bir olayı açın ve ihlal kanıtını, atanmış kişilerini ve abonelerini, koordinasyon için kullanılan bir yorum başlığını ve salt ekleme yapılabilen bir aktivite zaman çizelgesini görürsünüz. -![Bir olay detay görünümü: ana uyarı ve ihlal özeti, sorumlular ve abone uygulaması, atfedilen etkinlik zaman çizelgesi ve yorum dizisi](/agenteye/images/incident-detail.png) -*Olan her şey, sırayla, her satır bunu yapan tarafından imzalanmış.* +![Bir olay detay görünümü: ana uyarı ve ihlal özeti, atanmış kişiler ve aboneler, atfedilmiş aktivite zaman çizelgesi ve bir yorum başlığı](/agenteye/images/incident-detail.png) +*Neler olduğunu sırayla ve her satır bunu yapanın imzasıyla.* -Her eylem (açıldı, kabul edildi, çözüldü, vb.) bu zaman çizelgesine yazılır ve hiçbir zaman düzenlenmez. Her giriş atfedilir: onu yapan operatöre, e-posta ile veya Failproof AI Observability'nin kendi başına yaptığı her şey için **automated** olarak (ihlal üzerine olay açmak gibi). Hiçbir şey anonim değildir ve hiçbir şey kaybolmaz, bu nedenle post-mortem daha az çok kendi kendini yazar. +Her işlem (açıldı, onaylandı, çözüldü vb.) bu zaman çizelgesine yazılır ve asla düzenlenmez. Her giriş atfedilir: bunu yapan operatöre, e-postaya göre veya Failproof AI Observability'nin kendi başına yaptığı (ihlal için olayı açmak gibi) şeyler için **otomasyona**. Hiçbir şey anonim değildir ve hiçbir şey kaybolmaz, böylece olay sonrası inceleme neredeyse kendini yazar. ## Bir olay nasıl hareket eder ```mermaid stateDiagram-v2 [*] --> firing - firing --> acknowledged: bir operatör kabul eder - firing --> resolved: bir operatör çözer - acknowledged --> resolved: bir operatör çözer + firing --> acknowledged: an operator acks + firing --> resolved: an operator resolves + acknowledged --> resolved: an operator resolves resolved --> [*] ``` -- **Açık (tetikleniyor):** ihlal olayı açar ve kanallarınıza bir kez sayfa gösterir. Tekrarlanan ihlaller aynı olaya katlanır ve sizi tekrar tekrar sayfa göstermek yerine kanıtlarını yeniler. -- **Kabul edildi:** bir operatör bunu ele alır. Açık kalır ve sonraki ihlaller kanıtları sessizce günceller. -- **Çözüldü:** bir operatör bunu kapatır. Koşul temizlendiğinde otomatik çözüm planlanmıştır ancak henüz etkinleştirilmemiştir, bu nedenle bir olay bir insan onu çözene kadar açık kalır ve bu herkesin gerçekte neler temizlendiği konusunda dürüst olmasını sağlar. Aynı uyarıda daha sonra yeni bir olay açılabilir. +- **Açık (tetikleniyor):** ihlal olayı açar ve kanallarınızı bir kez çağırır. Tekrarlanan ihlalleri aynı olayda bir araya getiri ve kanıtlarını yenile, sizi tekrar tekrar çağırmaz. +- **Onaylandı:** bir operatör bunu ele alır. Açık kalır ve sonraki ihlalleri kanıtları sessizce günceller. +- **Çözüldü:** bir operatör bunu kapatır. Koşul temizlendiğinde otomatik çözüm planlanmıştır ancak henüz etkin değildir, bu nedenle bir olay bir insan bunu çözene kadar açık kalır, bu da herkesin gerçekte neyin temizlendiği konusunda dürüst davranmasını sağlar. Aynı uyarıda daha sonra yeni bir olay açılabilir. -Bir uyarı aynı anda en fazla bir açık olayı tutar, bu nedenle titreşen bir kural sizi çiftliklere gömeemez. Ayrıca bir olayı elle açabilirsiniz: hiçbir uyarının yakalamadığı bir şey için bağımsız bir olay veya `incidents:write` varsa mevcut bir uyarıya bağlı bir olay. +Bir uyarı bir seferde en fazla bir açık olayı tutar, bu nedenle titreşen bir kural sizi kopyalarla gömenemez. Ayrıca manuel olarak bir olay açabilirsiniz: hiçbir uyarının yakalamadığı bir şey için bağımsız bir olay veya `incidents:write` izniniz varsa mevcut bir uyarıya bağlı bir olay. -## Nerede bulabilirim +## Nerede bulacaksınız -Olaylar `//incidents` konumunda bulunur. Görüntüleme **`incidents:read`** gerektirir; manuel bir olay açmak **`incidents:write`** gerektirir; kabul etme, atama, yorum yapma ve çözüm **`incidents:ack`** gerektirir. Emekli `alerts:ack` tuşu verilen eski anahtarlar `incidents:ack` olarak onurlandırıldığından çalışmaya devam eder, bu nedenle on-call rotasyonunuz yeniden verilmesi gerekmez. +Olaylar `//incidents` adresinde bulunur. Görüntüleme **`incidents:read`** gerektirir; manuel olay açma **`incidents:write`** gerektirir; onaylama, atama, yorum yapma ve çözme **`incidents:ack`** gerektirir. Emekli `alerts:ack` verilen eski anahtarlar çalışmaya devam eder, çünkü `incidents:ack` olarak kabul edilir, bu nedenle nöbet rotasyonunuz yeniden verilmesi gerekmez. -## İlişkili +## İlgili -- [Uyarılar](/tr/agenteye/alerts): bir eşik ihlal ettiğinde bu olayları açan kurallar. -- [Hata izleme](/tr/agenteye/error-tracking): her hatayı tek bir yerde görün ve birini uyarıya yükseltin. -- [Denetim](/tr/agenteye/audits): hiçbir kuralın izlemediği hataları bulan zamanlanmış analist. \ No newline at end of file +- [Uyarılar](/tr/agenteye/alerts): bir eşik ihlal edildiğinde bu olayları açan kurallar. +- [Hata izleme](/tr/agenteye/error-tracking): bir yerde her hatayı görün ve birini bir uyarıya yükseltin. +- [Denetimler](/tr/agenteye/audits): hiçbir kuralın izlemediği hataları bulan planlı analist. \ No newline at end of file diff --git a/docs/tr/agenteye/observability.mdx b/docs/tr/agenteye/observability.mdx index 3c8e0fd4..cff7d22a 100644 --- a/docs/tr/agenteye/observability.mdx +++ b/docs/tr/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- title: "Gözlemle" -description: "Gözlem yüzeyleri, aracılarınızın şu anda ne yaptığını izlediğiniz ve herhangi bir çalıştırmayı detaylı incelediğiniz yerdir." +description: "Gözlem yüzeyleri, ajanlarınızın şu anda ne yaptığını izlediğiniz ve herhangi bir çalıştırmayı detaylı inceleyebildiğiniz yerlerdir." --- -Gözlem yüzeyleri, aracılarınızın şu anda ne yaptığını izlediğiniz ve herhangi bir çalıştırmayı detaylı incelediğiniz yerdir. Buradaki her şey canlı, kuruluşunuza ait ve tarih aralığı, ortam, ajan ve oturum tarafından filtrelenebilir, böylece "bir şeyler ters gitmiş gibi görünüyor" durumundan tam çalıştırmaya saniyeler içinde ulaşırsınız. +Gözlem yüzeyleri, ajanlarınızın şu anda ne yaptığını izlediğiniz ve herhangi bir çalıştırmayı detaylı inceleyebildiğiniz yerlerdir. Buradaki her şey canlıdır, kuruluşunuza kapsam dahilindedir ve tarih aralığı, ortam, ajan ve oturum ile filtrelenebilir; böylelikle "bir şeyler yanlış görünüyor" durumundan tam çalıştırmaya saniyeler içinde ulaşabilirsiniz. -![Canlı Etkinlik Akışı, türe göre renklendirilmiş ve ortam, ajan ve oturum tarafından filtrelenebilir](/agenteye/images/events-stream.png) +![Türe göre renklendirilmiş ve ortam, ajan ve oturum ile filtrelenebilen canlı Olay Akışı](/agenteye/images/events-stream.png) -Dört yüzey, her biri kendi sayfasına sahip: +Dört yüzey, her birinin kendi sayfası: -- **[Etkinlik akışı](/tr/agenteye/event-stream)**: her ajan arasında her çalıştırmanın canlı, adım adım kaydı (en yenisi ilk). Kuruluşunuzun ana sayfası ve sorun giderilmesi için ilk durak. -- **[Oturumlar ve yürütme grafiği](/tr/agenteye/sessions)**: bu etkinlikler her çalıştırma için bir satırda birleştirilmiş, artı her çalıştırmanın nasıl ilerlediğinin git tarzı resmi. -- **[Performans metrikleri](/tr/agenteye/telemetry)**: gecikme sıcaklık haritaları ve modelleriniz, araçlarınız ve kancalarınız için p50/p95/p99 yaşam bulguları, böylece kuyruk artışı ortalamanın dışında göze çarpar. -- **[Hata takibi](/tr/agenteye/error-tracking)**: her şeyin ters gittiği tek bir sorun giderme yüzeyi, uyarıdan çalıştırmaya tek bir tıklamayla. +- **[Olay akışı](/tr/agenteye/event-stream)**: her ajan genelinde her çalıştırmanın canlı, adım adım izleme izi, en yenisi önce. Kuruluşunuzun ana sayfası ve triage için ilk durak. +- **[Oturumlar ve yürütme grafiği](/tr/agenteye/sessions)**: bu olaylar bir satıra bir çalıştırma halinde toplanmış, ayrıca her çalıştırmanın nasıl gerçekleştiğinin git tarzı görseli. +- **[Performans metrikleri](/tr/agenteye/telemetry)**: gecikme ısı haritaları ve modelleriniz, araçlarınız ve kancalarınız için p50/p95/p99 vitalleri; böylece bir kuyruk artışı ortalamanın dışına çıkar. +- **[Hata izleme](/tr/agenteye/error-tracking)**: her şeyin yanlış gittiğini gösteren tek triage yüzeyi, uyarı tetiklemesinden koşuyu kıran işleme bir tıkla erişim. ## İlgili - [Değerlendirmeler](/tr/agenteye/evaluations): her çalıştırmayı kalite açısından puanlandırın. - [Uyarılar](/tr/agenteye/alerts): herhangi bir eşiği bir sayfalama kuralına dönüştürün. -- [Denetimler](/tr/agenteye/audits): Failproof AI Observability'nin oturumlar arasında hata desenlerini bulmasına izin verin. -- [CLI ve aracılar](/tr/agenteye/cli-and-agents): terminalinizden aynı gözlemlenebilirlik. \ No newline at end of file +- [Denetimler](/tr/agenteye/audits): Failproof AI Observability'nin oturumlar arasında hata desenleri bulmasını sağlayın. +- [CLI ve ajanlar](/tr/agenteye/cli-and-agents): terminalinizden aynı gözlemlenebilirlik. \ No newline at end of file diff --git a/docs/tr/agenteye/openclaw-capture.mdx b/docs/tr/agenteye/openclaw-capture.mdx index 23ded95a..28ed56bd 100644 --- a/docs/tr/agenteye/openclaw-capture.mdx +++ b/docs/tr/agenteye/openclaw-capture.mdx @@ -1,50 +1,49 @@ --- ---- title: "OpenClaw oturumu yakalama" -description: "Takımınızın yerel OpenClaw oturumlarını AgentEye'a sıradan oturumlar ve etkinlikler olarak aktarın — OpenClaw'un çalışma şeklinde hiçbir değişiklik olmadan." +description: "Ekibinizin yerel OpenClaw oturumlarını AgentEye'a sıradan oturumlar ve etkinlikler olarak aktarın — OpenClaw'un çalışma şeklinde hiçbir değişiklik yapmadan." --- -Takımınız [OpenClaw](https://docs.openclaw.ai) çalıştırıyorsa, OpenClaw oturumu yakalama bu oturumları AgentEye'a sıradan oturumlar ve etkinlikler olarak getirir; böylece bunları arayabilir, yeniden oynatabilir ve gözlemlediğiniz diğer her şeyin yanında değerlendirebilirsiniz. [Python SDK](/tr/agenteye/python-sdk) ile tamamlayıcı: SDK yazdığınız aracıları enstrümente ederken, bu takımınızın zaten yaptığı OpenClaw çalışmasını yakalar — çalıştırılış şeklinde hiçbir değişiklik olmadan. +Ekibiniz [OpenClaw](https://docs.openclaw.ai) çalıştırıyorsa, OpenClaw oturumu yakalama bu oturumları AgentEye'a sıradan oturumlar ve etkinlikler olarak getirir; böylece bunları arayabilir, yeniden oynatabilir ve gözlemlediğiniz diğer her şeyin yanında değerlendirebilirsiniz. [Python SDK](/tr/agenteye/python-sdk) tamamlayıcısıdır: SDK yazdığınız ajanları enstrümanlarken, bu, ekibinizin zaten yaptığı OpenClaw çalışmasını yakalar — çalışma şeklinde hiçbir değişiklik olmadan. -Küçük bir arka plan toplayıcısı OpenClaw'un yerel oturum transkriptlerini yazılırken okur ve bunları AgentEye'a gönderir. [Codex yakalama](/tr/agenteye/codex-capture) ile aynı şekilde çalışır ve bir toplayıcı aynı anda her ikisini de yakalayabilir. +Küçük bir arka plan toplayıcısı, OpenClaw'un yerel oturum transkripsiyonlarını yazıldıkça okur ve bunları AgentEye'a gönderir. Bu, [Codex yakalamada](/tr/agenteye/codex-capture) olduğu gibi çalışır ve bir toplayıcı aynı anda her ikisini de yakalayabilir. --- -## Ne yakalar +## Neyi yakalar -Bir makinenin OpenClaw kurulumunda yapılandırılan her aracı, o makinenin toplayıcısı tarafından yakalanır — aracı başına kurulum yoktur. +Makinenin OpenClaw kurulumunda yapılandırılan her ajan, o makinenin toplayıcısı tarafından yakalanır — ajan başına kurulum yoktur. -Her OpenClaw oturumu bir AgentEye [oturumu](/tr/agenteye/sessions) olur; kullanıcı ve asistan mesajları, araç çağrıları ve araç sonuçları, eşleşen [etkinliklere](/tr/agenteye/event-stream) dönüşür. +Her OpenClaw oturumu bir AgentEye [oturumu](/tr/agenteye/sessions) olur; kullanıcı ve asistan mesajları, araç çağrıları ve araç sonuçları eşleşen [etkinliklere](/tr/agenteye/event-stream) dönüşür. --- -## Etkinleştirin +## Etkinleştir -Yakalama, etkinleştirene kadar kapalıdır. `events:add` iznine sahip bir API anahtarı ile toplayıcıyı yükleyin ([API anahtarları](/tr/agenteye/api-keys) bölümüne bakın) ve OpenClaw yakalamayı açın: +Yakalama, etkinleştirene kadar kapalıdır. Toplayıcıyı `events:add` izni olan bir API anahtarı ile kurun ([API anahtarları](/tr/agenteye/api-keys) bölümüne bakın) ve OpenClaw yakalamayı açın: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -Bu, toplayıcıyı kurar, onu arka plan hizmeti olarak kaydeder ve yakalamayı başlatır. Çalıştığını doğrulayın: +Bu, toplayıcıyı kurar, onu bir arka plan hizmeti olarak kaydeder ve yakalamaya başlar. Çalıştığını doğrulayın: ```bash agenteye-collector health ``` -Aynı makinede birden fazla aracı mı yakalıyorsunuz? Her birinin bayrağını aynı komuta ekleyin — örneğin `--openclaw-enabled --codex-enabled`. +Aynı makinede birden fazla ajan mı yakallıyorsunuz? Her birinin bayrağını aynı komuta ekleyin — örneğin `--openclaw-enabled --codex-enabled`. -İlk çalıştırmada, mevcut OpenClaw oturumlarınız bir kez geri doldurulur ve yeni etkinlik birkaç saniye içinde akışa alınır. OpenClaw'un kendi dosyaları yalnızca okunur — asla değiştirilmez, taşınmaz veya silinmez — ve her oturum, yeniden başlatmalar arasında bile tam olarak bir kez gönderilir. +İlk çalıştırmada, mevcut OpenClaw oturumlarınız bir kez geri doldurulur ve yeni etkinlik daha sonra saniyeler içinde akmaya başlar. OpenClaw'un kendi dosyaları yalnızca okunur — asla değiştirilmez, taşınmaz veya silinmez — ve her oturum, yeniden başlamalar arasında bile tam olarak bir kez gönderilir. --- ## Nerede görünür -Yakalanan oturumlar **Sessions**'da gösterilir ve bunların etkinlikleri **Events** akışında, gözlemlediğiniz başka herhangi bir aracı ile aynı şekilde görünür — böylece [oturum yeniden oynatma](/tr/agenteye/sessions), [arama](/tr/agenteye/queries), [değerlendirmeler](/tr/agenteye/evaluations) ve [uyarılar](/tr/agenteye/alerts) hepsi bunlarda çalışır. OpenClaw aracısına göre filtreleyin ve bunları kendileri başına görün. +Yakalanan oturumlar **Oturumlar**'da ve bunların etkinlikleri **Etkinlikler** akışında görünür; gözlemlediğiniz diğer herhangi bir ajan gibi — böylece [oturum yeniden oynatması](/tr/agenteye/sessions), [arama](/tr/agenteye/queries), [değerlendirmeler](/tr/agenteye/evaluations) ve [uyarılar](/tr/agenteye/alerts) hepsi bunlar üzerinde çalışır. Onları kendi başlarına görmek için OpenClaw ajanına göre filtreleyin. --- ## Gizlilik -OpenClaw transkriptleri tam oturumu içerir — komut çıktısı, dosya içeriği ve aracının okuduğu veya yazdığı her şey dahil — ve sırlar içerebilir. Yakalanan oturumlar olduğu gibi gönderilir; bu nedenle yakalamayı yalnızca bu içeriği AgentEye'da merkezi hale getirmenin uygun olduğu makinelerde ve takımlar için etkinleştirin ve toplayıcıya yalnızca `events:add` kapsamına sahip bir anahtar verin. Verilerinizin nasıl izole tutulduğu hakkında [Güvenlik](/tr/agenteye/security) bölümüne bakın. \ No newline at end of file +OpenClaw transkripsiyonları tam oturumu içerir — komut çıktısı, dosya içeriği ve ajanın okuduğu veya yazdığı her şey dahil — ve gizli bilgileri içerebilir. Yakalanan oturumlar olduğu gibi gönderilir, bu nedenle yakalamayı yalnızca bu içeriği AgentEye'a merkezileştirmenin uygun olduğu makinelerde ve ekipler için etkinleştirin ve toplayıcıya yalnızca `events:add` kapsamlı bir anahtar verin. Verilerinizin nasıl izole tutulduğu hakkında [Güvenlik](/tr/agenteye/security) bölümüne bakın. \ No newline at end of file diff --git a/docs/tr/agenteye/overview.mdx b/docs/tr/agenteye/overview.mdx index 602f2429..e8dc2a33 100644 --- a/docs/tr/agenteye/overview.mdx +++ b/docs/tr/agenteye/overview.mdx @@ -1,107 +1,107 @@ --- title: "Failproof AI: Ajanlarınızdaki Hataları Gözlemleyin" -description: "Failproof AI Observability, üretim ortamında AI ajanlarınızı gözlemlemek, değerlendirmek ve geliştirmek için kendi sunucunuzda çalışan bir platformdur." +description: "Failproof AI Observability, üretim ortamında AI ajanlarınızı gözlemlemek, değerlendirmek ve geliştirmek için kendi altyapınızda barındırılan bir platformdur." --- -Failproof AI Observability, üretim ortamında AI ajanlarınızı gözlemlemek, değerlendirmek ve geliştirmek için kendi sunucunuzda çalışan bir platformdur. Ajanlarınızın yaptığı her şeyi kaydeder (her araç çağrısı, model isteği, hook ve hata), her çalıştırmanın kalitesini puanlandırır ve bilmediğiniz hataları ortaya çıkarır — tamamı kendi altyapınızda çalıştırdığınız bir panoda. +Failproof AI Observability, üretim ortamında AI ajanlarınızı gözlemlemek, değerlendirmek ve geliştirmek için kendi altyapınızda barındırılan bir platformdur. Ajanlarınızın yaptığı her şeyi kaydeder (her araç çağrısı, model isteği, hook ve hata), her çalıştırmanın kalitesini puanlar ve bilmediğiniz hataları ortaya çıkarır; tümü kendi altyapınızda çalıştırdığınız bir panoda. -AI ajanları yayınladıysanız ve bir çalıştırmanın neden başarısız olduğunu tahmin etmekten bıktıysanız, burası başlamanız gereken sayfa. Failproof AI Observability'nin size ne sunduğunu ve parçaların nasıl bir araya geldiğini açıklar; herhangi bir şey yüklemeden önce okuyun. +AI ajanları dağıtıyorsanız ve bir çalıştırmanın neden yanlış gittiğini tahmin etmekten yorulduysanız, burası başlamanız gereken sayfa. Failproof AI Observability'nin size neler sunduğunu ve parçaların nasıl bir araya geldiğini açıklar; herhangi bir şey kurmadan önce. -> **Failproof AI Observability, Failproof AI'dan bir kurumsal üründür.** Canlı olarak görmek ister misiniz? Bir demo talep edin: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) adresine e-posta gönderin. +> **Failproof AI Observability, Failproof AI'dan bir kurumsal üründür.** Bunu çalışırken görmek ister misiniz? Bir demo talep edin: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) adresine e-posta gönderin. -![Failproof AI Observability oturumu, git tarzı bir yürütme grafiği olarak çizilmiş, yanında olay zaman çizelgesi ve sağ panelde araçlar, modeller ve hooklar ayrıntısı](/agenteye/images/session-detail.png) +![Failproof AI Observability oturumu, git tarzı bir yürütme grafiği olarak çizilmiş ve yanında olay zaman çizelgesi, sağ panelde araçlar, modeller ve hooklar için çalıştırma başına dökümü gösteriyor](/agenteye/images/session-detail.png) -*Her ajan çalıştırması, git tarzı bir yürütme grafiği (sol) olarak çizilmiş ve yanında olay zaman çizelgesi vardır. Paralel alt ajanların her birinin kendi şeridi vardır; sağ panel, çalıştırmanın araçlarını, modellerini, hooklarını ve token harcamasını ayrıntılarıyla gösterir.* +*Her ajan çalıştırması git tarzı bir yürütme grafiği (sol) olarak çizilir ve yanında olay zaman çizelgesi bulunur. Paralel alt-ajanların her birinin kendi şeridi vardır; sağ panel, çalıştırma için araçları, modelleri, hookları ve token harcamasını özetler.* --- -## Canlı olarak görmek +## Bunu çalışırken görmek -İki kısa video, ekiplerin ilk başta yaptığı iki şeyi gösterir: bir çalıştırmayı izlemek ve hataları otomatik olarak bulma. +İki kısa video, takımların ilk olarak ulaştığı iki şeyi gösterir: bir çalıştırmayı izleme ve hataları otomatik olarak bulma.
- +
-*Ajan izleme: hedeften araçlara ve son cevaba kadar tek bir çalıştırmayı adım adım izleyin.* +*Ajan izlemesi: hedeften araçlara ve son yanıta kadar tek bir çalıştırmayı adım adım izleyin.*
- +
-*Failproof Audit: Failproof AI Observability'nin günlüklerinizi oturumlar arasında analiz etmesine izin verin ve ne düzeltmesi gerektiğini öğrenin.* +*Failproof Audit: Failproof AI Observability'nin oturumlar arasındaki günlüklerinizi incelemesine ve düzeltmeniz gerekenleri söylemesine izin verin.* --- -## Ekipler neden kullanıyor +## Takımlar neden bunu kullanır -- **Ajanınızın gerçekte ne yaptığını görün.** Her çalıştırma okunabilir bir git tarzı yürütme grafiğine dönüşür: hangi araçlar paralel çalıştı, hangi alt ajanlar dallandı, nerede durdu ve ne harcadı. -- **Kalite gerilemeşini otomatik olarak yakalayın.** Küçük bir puanlama hizmetini bağlayın ve Failproof AI Observability her tamamlanan çalıştırmayı puanlandırır; böylece yardımcılıkta düşüş veya halüsinasyonlarda artış kendi kendine ortaya çıkar. -- **Kuralı yazacağınızı bilmediğiniz hataları bulun.** Yinelenen denetimler, günlüklerinizi oturumlar arasında hata kümeleri, gecikme aykırı değerleri, düşük puanlar ve takılı çalıştırmalar açısından analiz eder, ardından size sıralanmış, kanıtla desteklenmiş bulgular sunar. -- **Önemli olduğunda sayfa alın.** Eşik kuralları hata oranı, gecikme, maliyet veya değerlendirici puanlarında çalışır ve yanıtlayabileceğiniz, atayabileceğiniz ve çözebileceğiniz olaylar açar. -- **Düz İngilizcede sorular sorun.** Panoda yer alan bir AI asistanı, kendi verileriniz üzerinde „bu hafta üretimde kalite nasıl gelişiyor?" gibi soruları yanıtlar. Yaptığı her değişiklik onay geçidir. -- **Verilerinizi tutun.** Failproof AI Observability kendi sunucunuzda çalışır: olaylar, istemler ve analizler kontrol ettiğiniz altyapıda kalır. +- **Ajanınızın gerçekte ne yaptığını görün.** Her çalıştırma okunabilir, git tarzı bir yürütme grafiğine dönüşür: hangi araçlar paralel olarak çalıştı, hangi alt-ajanlar ayrıldı, nerede durdu ve neler harcadı. +- **Kalite gerillemelerini otomatik olarak yakalayın.** Küçük bir puanlama hizmeti bağlayın ve Failproof AI Observability her tamamlanan çalıştırmayı puanlar; böylece yardımcılıkta bir düşüş veya halüsinasyonlarda bir artış kendi kendine ortaya çıkar. +- **Yazı yazmadığınız kurallar için hataları bulun.** Yinelenen denetimler, oturumlar arasındaki günlüklerinizi hata kümeleri, gecikme aykırılıkları, düşük puanlar ve takılı çalıştırmalar için inceleyerek sıralanmış, kanıtla desteklenmiş bulgular sunar. +- **Önemli olduğunda uyarı alın.** Eşik kuralları hata oranı, gecikme, maliyet veya değerlendirici puanlarında tetiklenir ve kabul edebileceğiniz, atayabileceğiniz ve çözebileceğiniz olaylar açar. +- **Düz İngilizce ile sorular sorun.** Panodaki AI asistanı, kendi verileriniz üzerinde yapılan değişiklikler onay geçidine tabı olduğundan, sorular yanıtlar. +- **Verilerinizi koruyun.** Failproof AI Observability kendi barındırılan: etkinlikler, istemler ve analitikler kontrolünüz altındaki altyapıda kalır. --- -## Ne alıyorsunuz +## Neler alırsınız -Failproof AI Observability, üç fikir etrafında organize edilmiştir (**gözlemle**, **analiz et** ve **yönet**), panelin sol kenar çubuğuna yansıtılır. +Failproof AI Observability üç fikir etrafında organize edilir (**observe**, **analyze** ve **admin**); panodun sol kenar çubuğunda yansıtılır. -**Gözlemle** (ne olduğunun ham gerçeği): +**Observe** (olan şeyin ham gerçeği): -- **[Olay akışı](/tr/agenteye/event-stream)**: her çalıştırmanın canlı, adım adım izi (araç çağrıları, model çağrıları, hooklar, hatalar). -- **[Oturumlar](/tr/agenteye/sessions)**: bu olaylar, çalıştırma başına bir satır halinde, her biri puanlandırılmaya hazır, git tarzı bir yürütme grafiği ile birlikte sunulur. -- **[Performans metrikleri](/tr/agenteye/telemetry)**: yüzey başına gecikme harita grafikleri ve modeller, araçlar ve hooklar için p50/p95/p99 vitalleri; böylece kuyruk artışı ortalamanın dışında görünür. -- **[Hata izleme](/tr/agenteye/error-tracking)**: her şeyin ters gittiği tek bir işlem yüzeyinde; bir uyarının ateşlenmesinden tek bir tıkla uzak. +- **[Event stream](/tr/agenteye/event-stream)**: her çalıştırmanın canlı, adım adım izi (araç çağrıları, model çağrıları, hooklar, hatalar). +- **[Sessions](/tr/agenteye/sessions)**: bu etkinlikler çalıştırma başına bir satıra toplanmış, her biri puanlanmaya hazır, git tarzı bir yürütme grafiği ile. +- **[Performance metrics](/tr/agenteye/telemetry)**: yüzey başına gecikme ısı haritaları ve modeller, araçlar ve hooklar için p50/p95/p99 vitalleri; bu sayede bir tail spike medyandan öne çıkar. +- **[Error tracking](/tr/agenteye/error-tracking)**: yanlış giden her şey için bir triage yüzeyi, patlayan bir alarmdan bir tıklama uzağında. -![Tools gözlemle sayfası: gecikme harita grafiği, yüzdelik dilim bandı ve 24 zaman kutusu üzerinde araç dağılım çubuğu](/agenteye/images/tools.png) +![Araçlar observe sayfası: bir gecikme ısı haritası, yüzdelik bir bant ve 24 zaman kutusu üzerinde bir araç dağıtım çubuğu](/agenteye/images/tools.png) -*Her gözlemle yüzeyi, bir kıvılcım çizgisi ve p50/p95/p99 vitalleriyle bir gecikme harita grafiği ve yüzdelik dilim bandını eşleştirir. Gösterilen: Araçlar.* +*Her observe yüzeyi bir sparkline ve p50/p95/p99 vitalleri bir gecikme ısı haritası ve yüzdelik bant ile eşleştirir. Gösterilen: Araçlar.* -**Analiz et** (etkinliği cevaplara dönüştürün): +**Analyze** (aktiviteyi cevaplara dönüştürün): -- **[Sorgular](/tr/agenteye/queries)** ve **[panolar](/tr/agenteye/dashboards)**: olaylarınız ve değerlendirmeleriniz üzerinde kaydedilmiş SQL, paylaşılan, kurum kapsamı panolara çizilmiştir. -- **[Değerlendirmeler](/tr/agenteye/evaluations)**: kendi değerlendirici hizmetiniz tarafından üretilen kalite puanları, puan başına akıl yürütmesi ile. -- **[Denetimler](/tr/agenteye/audits)**: oturumlar arasında hata modellerini ortaya çıkaran yinelenen araştırmalar. -- **[Uyarılar](/tr/agenteye/alerts)** ve **[olaylar](/tr/agenteye/incidents)**: sizi sayfaya alan eşik kuralları, artı bunları işlemek için bir olay iş akışı. +- **[Queries](/tr/agenteye/queries)** ve **[dashboards](/tr/agenteye/dashboards)**: etkinlikleriniz ve değerlendirmeleriniz üzerinde kaydedilmiş SQL; paylaşılan, org kapsamlı panolara çizilir. +- **[Evaluations](/tr/agenteye/evaluations)**: kendi değerlendirici hizmetiniz tarafından üretilen kalite puanları, puан başına akıl yürütme ile. +- **[Audits](/tr/agenteye/audits)**: oturumlar arasında hata kalıplarını ortaya çıkaran yinelenen araştırmalar. +- **[Alerts](/tr/agenteye/alerts)** ve **[incidents](/tr/agenteye/incidents)**: sizi uyaran eşik kuralları, artı bunları triage etmek için bir olay akışı. -**Arayüzler** (verilerinize kendi yolunuzla ulaşın): +**Interfaces** (verilerinize kendi yolunuzla ulaşın): -- **[CLI](/tr/agenteye/cli-and-agents)**: tüm dağıtımınızı terminalden veya bir betikten çalıştırın ve bir kodlama ajanının bunu düz İngilizcede yapmasına izin verin. -- **[AI asistanı](/tr/agenteye/assistant)**: ajanlarınız hakkında düz İngilizcede soru sorun, doğrudan panoda. -- **REST API**: panelin ve CLI'nin yaptığı her şey, kapsamlı bir [API anahtarı](/tr/agenteye/api-keys) ile doğrudan çağırabileceğiniz bir REST API tarafından desteklenir — olayları alın, oturumları ve değerlendirmeleri sorgulayın ve panoları, uyarıları, denetimleri, kullanıcıları ve anahtarları yönetin; böylece Failproof AI Observability'yi kendi araçlarınızla entegre edin. +- **[CLI](/tr/agenteye/cli-and-agents)**: tüm dağıtımınızı terminalden veya bir komut dosyasından kontrol edin ve bir kodlama ajanının bunu düz İngilizce'de yapmasına izin verin. +- **[AI assistant](/tr/agenteye/assistant)**: ajanlarınız hakkında düz İngilizce'de sorular sorun; doğru panodun içinde. +- **REST API**: panodun ve CLI'nin yaptığı her şey, kapsamlı bir [API key](/tr/agenteye/api-keys) ile doğrudan arayabileceğiniz bir REST API tarafından desteklenir — etkinlikleri alıştırın, oturumları ve değerlendirmeleri sorgulayın ve panolar, uyarılar, denetimler, kullanıcılar ve anahtarları yönetin; böylece Failproof AI Observability'yi kendi araçlarinıza entegre edebilirsiniz. -**Yönet** (ekibiniz için çalıştırın): +**Admin** (bunu takımınız için çalıştırın): -- **[API anahtarları](/tr/agenteye/api-keys)**: toplayıcı, pano ve asistan için kapsamlı jetonlar. -- **Kullanıcılar**: şifresiz, e-posta tabanlı oturum açma ve izin listesiyle. -- **Ayarlar**: kurum başına yapılandırma, model bağlam penceresi geçersiz kılmalar dahil. +- **[API keys](/tr/agenteye/api-keys)**: toplayıcı, pano ve asistan için kapsamlı token'lar. +- **Users**: beyaz liste ile şifresiz, e-posta tabanlı oturum açma. +- **Settings**: org başına konfigürasyon; model bağlam penceresi geçersiz kılmalarını da içerir. --- ## Parçalar nasıl bir araya gelir -Veri bir yönde akar, ajan kodunuzdan panoya: ajanınız (Python SDK aracılığıyla) agenteye-toplayıcıya olaylar yayınlar; bu olaylar sunucuya gönderilir ve sunucu panoyu sunar. İki isteğe bağlı hizmet bunu tamamlar — bir puanlama hizmet (değerlendirmeler) ve bir AI asistan hizmet (panoda sohbet). +Veriler tek yönde akar; ajan kodunuzdan panoya: ajanınız (Python SDK aracılığıyla) agenteye-collector'a etkinlikler yayar; bu da sunucuya gönderir; sunucu da panoya sunduğu. İki isteğe bağlı hizmet bunu tamamlar — bir puanlama hizmeti (değerlendirmeler) ve bir AI asistan hizmeti (panodaki sohbet). -- **Python SDK**: ajanınıza birkaç `agenteye.event.*` çağrısı eklersiniz; olaylar yerel olarak arabelleğe alınır. -- **agenteye-toplayıcı**: her ajan makinesinde, olayları toplu olarak işleyen ve sunucuya gönderen hafif bir daemon. -- **Sunucu**: olaylarınızı alır, operasyonel durumu kendi veritabanlarınızda tutar ve pano, CLI ve kendi entegrasyonlarınızın hepsinin kullandığı REST API'yi sunar. -- **Pano**: her şeyi keşfettiğiniz yer. -- **İsteğe bağlı hizmetler**: bir puanlama hizmet (değerlendirmeler) ve bir AI asistan hizmet (panoda sohbet). +- **Python SDK**: ajanınıza birkaç `agenteye.event.*` çağrısı eklersiniz; etkinlikler yerel olarak arabelleğe alınır. +- **agenteye-collector**: her ajan makinesinde hafif bir daemon; etkinlikleri toplu hale getirir ve sunucuya gönderir. +- **Server**: etkinliklerinizi alıştırır, operasyonel durumun kendi veritabanlarınızda tutar ve pano, CLI ve kendi entegrasyonlarınızın hepsinin kullandığı REST API'yi sunduğu. +- **Dashboard**: her şeyi keşfettiğiniz yer. +- **Optional services**: bir puanlama hizmeti (değerlendirmeler) ve bir AI asistan hizmeti (panodaki sohbet). -Belgeler genelinde kullanılan kelime dağarcığı (*olay, oturum, değerlendirme, denetim, bulgu, olay*) için bkz. [Kavramlar](/tr/agenteye/concepts). +Belgeler boyunca kullanılan kelime dağarcığı için (*event, session, evaluation, audit, finding, incident*), bkz. [Concepts](/tr/agenteye/concepts). --- ## Failproof AI Observability'yi Almak -Failproof AI Observability, Failproof AI'dan bir kurumsal üründür ve Failproof AI Enforcement — politika ve korkuluk ürünü — ile Failproof AI markası altında birlikte çalışır. Tamamen kendi ortamınızda çalışır. Paketlere henüz erişiminiz yoksa, bir demo talep edin ve sizi hazırlayacağız: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) adresine e-posta gönderin. +Failproof AI Observability, Failproof AI'dan bir kurumsal üründür ve Failproof AI Enforcement — politika ve guardrail ürünü — ile Failproof AI markası altında birlikte çalışır. Tamamen kendi ortamınızda çalışır. Henüz paketlere erişiminiz yoksa, bir demo talep edin ve sizi ayarlayacağız: [nikita@befailproof.ai](mailto:nikita@befailproof.ai) adresine e-posta gönderin. --- ## Sonraki adımlar -- [Kavramlar](/tr/agenteye/concepts): Failproof AI Observability kelime dağarcığı bir yerde. -- [Observabilite](/tr/agenteye/observability): ajanlarınızın ne yaptığını, çalıştırmayı izleyin. -- [Güvenlik](/tr/agenteye/security): Failproof AI Observability verilerinizi nasıl izole tuttuğu ve kontrol altında tuttuğu. \ No newline at end of file +- [Concepts](/tr/agenteye/concepts): Failproof AI Observability kelime dağarcığı bir yerde. +- [Observability](/tr/agenteye/observability): ajanlarınızın yaptığını çalıştırma başına izleyin. +- [Security](/tr/agenteye/security): Failproof AI Observability verilerinizi nasıl izole tutar ve kontrolünüzde tutarsa. \ No newline at end of file diff --git a/docs/tr/agenteye/python-sdk-skill.mdx b/docs/tr/agenteye/python-sdk-skill.mdx index 72b79dab..20a3349e 100644 --- a/docs/tr/agenteye/python-sdk-skill.mdx +++ b/docs/tr/agenteye/python-sdk-skill.mdx @@ -1,130 +1,134 @@ --- title: "Failproof AI Observability Python SDK Agent Skill" -description: "Enstrümente edilmemiş bir ajanı gözlemlenebilir olaylarına dönüştürün; kodlama ajanınız enstrümantasyon noktalarını bulacak, yazacak ve doğrulayacaktır." +description: "Enstrümente edilmemiş bir ajanı, görebileceğiniz etkinliklere dönüştürün. Kodlama ajanı enstrümantasyon noktalarını bulur, yazar ve doğrulanmış olarak teslim eder." --- -Kodlama ajanınıza *"bu ajana Failproof AI Observability ekle"* deyin ve ajanın döngünüzü okumasına, enstrümantasyonun nereye ait olduğunu çözmesine, yazmasına ve olayları doğrulamasına izin verin. +Kodlama ajanınıza *"bu ajana Failproof AI Observability ekle"* deyin ve ajanın döngünüzü okumasına, enstrümentasyonun nereye ait olduğunu anlamasına, yazmasına ve etkinlikleri doğrulamasına izin verin. -**Python SDK becerisi** (`agenteye-python-sdk`) bir *Agent Skill*'dir: bir görev bununla eşleştiğinde Claude Code veya Codex gibi bir kodlama ajanının talep üzerine yüklediği bir talimatlar klasörü. Ajana [Python SDK](/tr/agenteye/python-sdk) kullanmayı öğretir — bu bir kütüphane değildir ve SDK'nın çalışma şeklini hiçbir şekilde değiştirmez. +**Python SDK skill** (`agenteye-python-sdk`) bir *Agent Skill*'tir: kodlama ajanı (Claude Code veya Codex gibi) tarafından görev eşleştiğinde talep üzerine yüklenen bir talimat klasörü. Ajana [Python SDK](/tr/agenteye/python-sdk) kullanmayı öğretir — bir kütüphane değildir ve SDK'nın çalışma şeklini değiştirmez. -## Enstrümantasyon yazması kolay ama sessizce yanlış olmak kolay +## Enstrümantasyon yazması kolay ama sessizce yanlış olmayabilir -SDK küçüktür: on üç olay yöntemi, hepsi salt anahtar sözcük. Bir kodlama ajanı [Python SDK](/tr/agenteye/python-sdk) referansını okuyabilir ve makul enstrümantasyon bir dakikada üretebilir. +SDK küçüktür: on üç etkinlik metodu, hepsi sadece anahtar sözcük olarak. Kodlama ajanı [Python SDK](/tr/agenteye/python-sdk) referansını okuyabilir ve bir dakika içinde makul enstrümantasyon üretebilir. -Sorun şu ki, bu SDK yanlış olduğunuzda hata vermez ve yanlış enstrümantasyon doğru enstrümantasyon gibi görünür; ta ki birisi bir panoyu açıp boş bulana kadar. Gerçek zaman kaybettiren hatalar hep sessizliklerdir: +Yakalanacak nokta, bu SDK'nın yanlış yaptığınızda hata yükseltmemesi ve yanlış enstrümantasyonun biri dashboard'u açana ve boş bulana kadar doğru enstrümantasyondan tamamen aynı görünmesidir. Gerçek zaman harcayan hatalar hep sessizliktir: | Hata | Ne görürsünüz | |---|---| -| `agent_start` yok | Her olay iniyor. Sıfır oturum. | -| Ortam hiç ayarlanmadı | Herşey çalışıyor, `dev` altında dosyalanıyor. | -| `outcome="failure"` | Çalıştırma yeşil görünüyor — sadece `failed`, `error`, `timeout`, `rejected` sayılır. | -| Yazım hatası yapılan alan adı | Kabul ediliyor ve yeni alan olarak depolanıyor. | -| İş parçacığı havuzundan yayılan olaylar | Sessizce düşürülüyor. | +| `agent_start` yok | Her etkinlik iner. Sıfır oturum. | +| Ortam asla ayarlanmadı | Her şey çalışır, `dev` olarak dosyalanır. | +| `outcome="failure"` | Çalışma yeşil gösterilir — yalnızca `failed`, `error`, `timeout`, `rejected` sayılır. | +| Yanlış yazılan alan adı | Kabul edilir ve yeni bir alan olarak depolanır. | +| İş parçacığı havuzundan gönderilen etkinlikler | Sessizce bırakılır. | -Bunların hiçbiri hata vermez. Hiçbiri testlerde görünmez. Hepsi beceriye katılır, bunu yakalayan kontrol olarak belirtilir. +Bunların hiçbiri hata yükseltmez. Hiçbiri testlerde gösterilmez. Her biri skill'de yer alır ve bunu yakalayan kontrol ile bir sözleşme olarak belirtilir. -## Sırasıyla ne yapar +## Sırayla ne yapıyor -Beceri, dikkatli bir mühendisçinin yapacağı aynı üç adımı izler: +Skill, dikkatli bir mühendisçinin yapacağı aynı üç adımı çalıştırır: -1. **Plan.** Ajand döngünüzü okur ve sadece siz cevap verebileceğiniz iki soruyu sorar: bir çalıştırma nedir (`session_id`), ve ayırt edilebilir aktörler kimdir (`agent_id`). Kod yazmadan önce bunlar üzerinde anlaşmaya varır, çünkü daha sonra değiştirmek tarihinizi böler ve trendleri kırar. -2. **Yaz.** Kimliği çalıştırma başına bir kez bağlar, her çağrı sitesinden geçirmez ve eşzamanlılığa güvenli bir şekil seçer — bu önemlidir, çünkü bariz kısayol iki örtüşen çalıştırmayı sessizce bir oturumda karıştırır. -3. **Doğrula.** Ajanınızı çalıştırır ve ortaya çıkan olay dosyalarını okur; `agent_start` mevcutsa, ortam doğruysa ve bir çalıştırma bir oturum ürettiyse kontrol eder. +1. **Plan.** Ajan döngünüzü okur ve yalnızca sizin cevaplayabileceğiniz iki soruyu sorar: bir çalışma neyi sayar (`session_id`), ayırt edilebilir aktörler kimlerdir (`agent_id`). Kod yazmadan önce bunu anlaştırır, çünkü daha sonra değiştirmek geçmişinizi böler ve eğilimlerinizi kırabilir. +2. **Yaz.** Kimliği çalışma başına bir kez bağlar, her çağrı sitesinden geçirmez ve eşzamanlılık açısından güvenli bir şekil seçer — önemli bir detay, çünkü bariz kısayol sessizce iki çakışan çalışmayı bir oturuma karıştırabilir. +3. **Doğrula.** Ajanınızı çalıştırır ve ortaya çıkan etkinlik dosyalarını okuyarak `agent_start` mevcutsa, ortam doğruysa ve bir çalışmanın bir oturum oluşturduysa kontrol eder. -Bu üçüncü adım insanların atladığı adımdır. SDK olayları yerel dosyalara yazar, bu nedenle tam bir entegrasyon sunucu olmadan, API anahtarı olmadan ve ağ olmadan dizüstü bilgisayarda kanıtlanabilir — bu tam olarak becerinin bunu yapması ısrar ettiği nedendir. +Bu üçüncü adım, insanların atlayacağı adımdır. SDK etkinlikleri yerel dosyalara yazar, bu nedenle tam bir entegrasyon sunucu, API anahtarı ve ağ olmadan bir dizüstü bilgisayarda kanıtlanabilir — bu tam olarak skill'in bunu yapması ısrarcı olmasının nedenidir. -## Diğer becerilerle ilişkisi +## Diğer skill'lerle ilişkisi -Üç beceri, bir temiz bölünme: +Üç skill, bir net bölme: -| Beceri | Ne zaman kullanılır | Ne değiştirir | +| Skill | Ne zaman kullanılır | Neyi etkiler | |---|---|---| -| **Python SDK becerisi** (bu sayfa) | Ajanınızın telemetri yaymasını istiyorsunuz — "observability ekle", "ajanom neden görünmüyor?" | Ajanın reposunda kod yazar. Hiçbir şey okumaz. | -| **[Evaluator becerisi](/tr/agenteye/evaluator-skill)** | Çalıştırmaları *puanlamak* istiyorsunuz — "ne ölçmemiz gerekiyor?" | Repoda kod yazar; telemetri okur | -| **[CLI becerisi](/tr/agenteye/cli-skill)** | Ne olduğunu *okumak* ya da dağıtımınızı işletmek istiyorsunuz | CLI'yi siz olarak yönetir, değişiklikler dahil | +| **Python SDK skill** (bu sayfa) | Ajanınızın telemetri *yaymak* istediğinizde — "gözlemlenebilirlik ekle", "ajanam neden gösterilmiyor?" | Ajanın repo'sunda kod yazar. Hiçbir şey okumaz. | +| **[Evaluator skill](/tr/agenteye/evaluator-skill)** | Çalışmaları *puanlandırmak* istediğinizde — "neyi ölçmeliyiz?" | Repo'nuzda kod yazar; telemetriyi okur | +| **[CLI skill](/tr/agenteye/cli-skill)** | Ne olduğunu *okumak* veya dağıtımı işletmek istediğinizde | CLI'yi siz olarak yönetir (değişiklikleri dahil) | -Bu sırayla devrederler: bu beceri olayları akışa sokar, evaluatör onları puanlar, CLI bunları geri okur. Ajanınız oturumlar yayına kadar değerlendirilecek hiçbir şey yoktur ve okunacak hiçbir şey yoktur, bu nedenle sıfırdan başlıyorsanız, burada başlayın. +Sırayla teslim ederler: bu skill etkinlikleri akışa getirir, değerlendirici onları puanlandırır, CLI onları geri okur. Ajanınız oturum yayınlayana kadar değerlendirilecek ve okunacak hiçbir şey yoktur, bu nedenle sıfırdan başlıyorsanız burada başlayın. -## Ön Koşullar +## Ön koşullar 1. **Python 3.10+** ve enstrümente etmek istediğiniz ajan kod tabanı. -2. **SDK.** Müşterilere özel bir wheel olarak dağıtılır, herkese açık bir indeksden değil — onboarding'iniz bunu nasıl elde edeceğinizi ve yükleyeceğinizi kapsar. Beceri yükleme yolunu bilir ve bulamazsa sizin yerine tahmin etmek yerine sorar. -3. **Başka bir şey yok.** Pano girişi yok, API anahtarı yok, ağ yok. Beceri SDK'nın yazdığı olay dosyalarına karşı doğrular, bu nedenle tamamlayabilir ve çalışmasını çevrimdışı olarak kanıtlayabilir. +2. **SDK.** Müşterilere özel bir wheel olarak dağıtılır, genel bir indeksten değil — onboarding'iniz onu nasıl alacağınızı ve kuracağınızı kapsamaktadır. Skill kurulum yolunu bilir ve bulamıyorsa tahmin etmek yerine sizden sorabilir. +3. **Başka hiçbir şey.** Dashboard girişi, API anahtarı, ağ yok. Skill, SDK'nın yazdığı etkinlik dosyalarına karşı doğrular, bu nedenle çevrimdışı olarak bitire ve işini kanıtlayabilir. -## Nereden bulabilirsiniz +## Nereden bulunur -Beceri genel [`FailproofAI/skills`](https://github.com/FailproofAI/skills) koleksiyonunda bulunur: +Skill, herkese açık [`FailproofAI/skills`](https://github.com/FailproofAI/skills) koleksiyonunda yer alır: ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -Yalnızca mevcut proje yerine her proje için yüklemek için `-g` ekleyin ve ortamınız sembolik bağlantıları takip etmezse `--copy` ekleyin. Codex için `-a codex` geçirin. +Her proje için kurulum yapmak istiyorsanız (sadece geçerli değil) `-g` ekleyin, ortamınız sembolik bağları takip etmiyorsa `--copy` ekleyin. Codex için `-a codex` kullanın. -## Elle yükleme +## Elle kurulum -Agent Skills, `SKILL.md` ve referanslar içeren klasörlerdir. Yükleyiciyi kullanmak istemiyorsanız: +Agent Skills, `SKILL.md` artı referanslar içeren klasörlerdir. Yükleyiciyi kullanmamayı tercih ederseniz: -- **Claude Code**: `agenteye-python-sdk/` klasörünü `~/.claude/skills/` içine (her proje) veya `/.claude/skills/` içine (sadece bu repo) kopyalayın. Claude Code otomatik olarak keşfeder — `/skills` listesini kontrol edin ya da bununla eşleşen bir şey sorun. -- **Codex**: Codex aynı `SKILL.md` okur. Paketlenmiş `agents/openai.yaml` `allow_implicit_invocation: true` ayarlar, bu nedenle bir görev eşleştiğinde otomatik seçilir; aksi halde `$agenteye-python-sdk` olarak çağırın. +- **Claude Code**: `agenteye-python-sdk/` klasörünü `~/.claude/skills/` (her proje) veya `/.claude/skills/` (sadece o repo) içine kopyalayın. Claude Code otomatik olarak bulur — `/skills` listesini kontrol edin veya eşleşen bir şey sorun. +- **Codex**: Codex aynı `SKILL.md` okur. Paketlenmiş `agents/openai.yaml`, `allow_implicit_invocation: true` ayarlar, bu nedenle görev eşleştiğinde otomatik seçilir; aksi takdirde `$agenteye-python-sdk` olarak çağırın. -Ajanınızı **enstrümente etmek istediğiniz kodu tutan depoda çalıştırın** — beceri ajand döngünüzü herhangi bir şey önermenin önce okur. +Ajanınızı **enstrümente etmek istediğiniz kodu tutan depoda çalıştırın** — skill ajan döngünüzü okuyor. -## Bir oturum nasıl görünür +## Bir oturum neye benziyor ```text -siz ▸ Bu ajana Failproof AI Observability ekle. +siz ▸ Failproof AI Observability'yi bu ajana ekle. -ajan ▸ Döngünüzü okudum — tools.py'da bir araç dağıtıcı, llm.py'da bir Anthropic - sarmalayıcı. Herhangi bir kod yazmadan önce iki sorum var. +ajan ▸ Döngünüzü okudum — tools.py'de bir araç dispatcher, llm.py'de + bir Anthropic wrapper. Hiçbir şey yazmadan önce iki sorum var. - Bir çalıştırma nedir? İstekleri eşzamanlı olarak işliyorsunuz, bu yüzden - ctx.request_id'de zaten sahip olduğunuz istek id'sini kullanırım — - sonra burada bir oturum ve günlüklerdeki bir istek aynı dizedir. + Bir çalışma neyi sayar? Istekleri eşzamanlı olarak işletiyor + sunuz, bu yüzden zaten ctx.request_id'de sahip olduğunuz istek + kimliğini kullanırım — o zaman burada bir oturum ve + loglarınızdaki istek aynı stringdir. - Ve aktörler kimdir? Bir planlayıcı yolu ve araştırıcı yolu görüyorum. - Bunları ayrı etiketlemeli misiniz, yoksa senin için bir ajandır? + Ve aktörler kimler? Bir planlayıcı yolu ve araştırmacı yolu + görüyorum. Bunları ayrı etiketleyin ya da siz için bu tek bir + ajan mı? -siz ▸ İstek id doğru. Onlar bir ajan, buna "asistan" de. +siz ▸ İstek kimliği doğru. Bunlar tek bir ajan, buna "asistan" de. -ajan ▸ Tamamlandı. Dağıtıcı ve LLM istemcisi sardım; agent_start ve agent_end - hata yolunu da dahil ederek handle_request'i ayraç içine aldı. Kimlik - için bağlam-yerel kullandı — dağıtıcınız araçları iş parçacığı havuzunda - çalıştırıyor ve daha basit yaklaşım eşzamanlı çalıştırmaları sessizce - bir oturumda karıştırmış olurdu. +ajan ▸ Bitti. Dispatcher ve LLM istemcisini kaydettim; agent_start ve + agent_end hata yolu da dahil olmak üzere handle_request'i + çerçeveler. Kimlik için bağlama-yerel bir değer kullandım — + dispatcher'ınız araçları bir iş parçacığı havuzunda çalıştırıyor + ve daha basit yaklaşım eşzamanlı çalışmaları bir oturuma + karıştırabilirdi sessizce. - Gerçek çalıştırmaya karşı doğrulandı: 4 dosya genelinde 11 olay — - agent_start, model_request/response, tool_use/tool_result x3, - agent_end (outcome=success). environment=production, istek başına bir - oturum, durations eşlenmiş. + Gerçek bir çalışmaya karşı doğrulama: 4 dosya arasında 11 etkinlik + — agent_start, model_request/response, tool_use/tool_result x3, + agent_end (outcome=success). environment=production, istek başına + bir oturum, süreleri eşleştirildi. - Bir şey YAPMADıM: batch.py'daki işçi havuzu doğrudan executor'a gönderiyor, - oradan gelen olaylar düşürülürdü. Şu da düzeltmek ister misin? + BİR şey yapmadım: batch.py'deki işçi havuzunuz doğrudan + executor'a gönderiliyor, bu nedenle oradan gelen etkinlikler + bırakılacak. Onlar da düzeltmemi ister misiniz? ``` -Dikkat edilecek model: kodunuzu önermenin önce okudu, sadece cevaplayabileceğiniz soruları sordu, zaten sahip olduğunuz bir id'yi yeniden kullandı, iş parçacığı havuzu gördüğü için eşzamanlılığa güvenli şekil seçti ve başarı beyan etmek yerine **gerçek olayları okuyarak doğruladı** — sonra sessizce başarısız olacak tek yeri işaretledi. +Dikkat etecek örüntü: kodu önerme yapılmadan okudu, yalnızca yanıtlayabileceğiniz soruları sordu, zaten sahip olduğunuz bir kimliği yeniden kullandı, bir iş parçacığı havuzu gördüğü *için* eşzamanlılık açısından güvenli şekli seçti ve başarıyı ilan etmek yerine gerçek etkinlikleri okuyarak doğruladı — o zaman sessizce başarısız olacağını bildiği bir yeri işaretledi. -## Ne sorabilirsiniz +## Ne sorabileceğiniz -- *"Ajanom neden panoda görünmüyor?"* → merdiveni yürür: olaylar yazılıyor mu, `agent_start` var mı, ortam doğru mu, toplayıcı aynı yeri okuyor mu. -- *"Herşey dev altında iniyor."* → ortam hiç ayarlanmadı ya da daha sonra çağrı tarafından sıfırlandı. -- *"Token takibi ekle."* → LLM sarmalayıcınızı bulur ve model, durdurma nedeni ve kullanımı kaydeder. -- *"Alt-ajanları da enstrümente et."* → bir oturum, farklı ajan etiketleri, üstlerinin altında iç içe. -- *"Enstrümantasyon için testler yaz."* → SDK'yı geçici bir dizine yönlendirir ve yazdığı olaylar hakkında onaylar. +- *"Ajanam neden dashboard'da gösterilmiyor?"* → merdiveni yürür: etkinlikler yazılıyor mu, `agent_start` orada mı, ortam doğru mu, toplayıcı aynı yeri okuyor mu. +- *"Her şey dev altında iniyor."* → ortam asla ayarlanmadı veya daha sonraki bir çağrı tarafından sıfırlandı. +- *"Token takibini ekle."* → LLM wrapper'ınızı bulur ve model, durdurma nedenini ve kullanımı kaydeder. +- *"Alt ajanları da enstrümente et."* → bir oturum, farklı ajan etiketleri, üst öğelerinin altında iç içe. +- *"Enstrümantasyon için testler yaz."* → SDK'yı geçici bir dizine yönlendirir ve yazdığı etkinlikleri doğrular. -## Nelere dikkat edin +## Dikkat edilecek noktalar -**Doğrulamaya izin verin.** Bu beceriyi kullanmaya değer kılan adım son adımdır — ajanınızı çalıştırın ve olayları geri okuyun. Enstrümantasyon yazan ve duran bir ajan kolay yarısını yapmıştır ve sessizce başarısız olan yarısı diğeridir. +**Doğrulamaya izin verin.** Bu skill'in kullanılmaya değer olmasını sağlayan adım son adımdır — ajanınızı çalıştırmak ve etkinlikleri geri okumak. Enstrümantasyon yazan ve duran bir ajan kolay yarıyı yapmıştır ve sessizce başarısız olan yarı öteki yarıdır. -**Koddan önce adlar üzerinde anlaşın.** `session_id` ve `agent_id` her yüzeyin gruplandığı eksenlerdir. Daha sonra yeniden adlandırmak tarihi böler: eski çalıştırmalar eski etiketleri tutar ve trendleri kırılır. Beceri sorar; cevap bir dakikasını düşünmeye değer. +**Kod yazmadan önce adları mutabık kılın.** `session_id` ve `agent_id`, her yüzeyin gruplandırdığı eksenlerdir. Onları daha sonra yeniden adlandırmak geçmişi böler: eski çalışmalar eski etiketleri tutar ve eğilimleriniz kırılır. Skill sorabilir; cevap bir dakikalık düşüne değer. -**Ajanınız SDK'yı genel bir indeksden yüklemeyi önerirse, beceri yüklenmedi.** SDK özel olarak dağıtılır. Bu teklif, kodlama ajanınızın beceriyi takip etmek yerine tahmin ettiğinin güvenilir bir işaretidir — oraya dur ve becerinin yüklendiğini kontrol et. +**Ajanınız SDK'yı genel bir indeksten kurma öneriyorsa, skill yüklenmedi.** SDK özel olarak dağıtılır. Bu öneri, kodlama ajanınızın tahmin ettiğinin güvenilir bir göstergesidir — orada durdurun ve skill'in kurulu olduğunu kontrol edin. -Bunun ötesinde patlaması alanı küçüktür: çalışma dizininizde kod ve sizi ne söylerse olaylar yazılır. Dağıtımınızdan hiçbir şey okumaz ve hiçbir şey değiştirmez. +Bunun ötesinde patlama yarıçapı küçüktür: çalışma dizininizde kod ve etkinlik dosyaları yazdığınız yere yazıyor. Dağıtımınızdan hiçbir şey okumaz ve hakkında hiçbir şeyi değiştirmez. ## Sonraki adımlar -- **[Python SDK](/tr/agenteye/python-sdk)**: bu becerinin otomatikleştirdiği şeyin arkasında — her olay türü ve alan — tam olay referansı. -- **[Oturumlar](/tr/agenteye/sessions)**: olaylar iniş yaptıktan sonra enstrümantasyonunuzun ürettiği. -- **[Evaluator Agent Becerisi](/tr/agenteye/evaluator-skill)**: çalıştırmalar iniş yaptıktan sonra sonraki adım — bunları puanlamak. -- **[CLI Agent Becerisi](/tr/agenteye/cli-skill)**: telemetrinizi geri okumak. \ No newline at end of file +- **[Python SDK](/tr/agenteye/python-sdk)**: bu skill'in otomatikleştirdiği şeyin arkasında — tam etkinlik referansı, her etkinlik türü ve alan. +- **[Sessions](/tr/agenteye/sessions)**: etkinlikler iniş yaptıktan sonra enstrümentasyonunuzun üreteceği şey. +- **[Evaluator Agent Skill](/tr/agenteye/evaluator-skill)**: çalışmalar iniş yaptıktan sonra sonraki adım — onları puanlandırmak. +- **[CLI Agent Skill](/tr/agenteye/cli-skill)**: telemetrinizi geri okumak. \ No newline at end of file diff --git a/docs/tr/agenteye/python-sdk.mdx b/docs/tr/agenteye/python-sdk.mdx index 4ef73ed3..3257d73a 100644 --- a/docs/tr/agenteye/python-sdk.mdx +++ b/docs/tr/agenteye/python-sdk.mdx @@ -1,15 +1,15 @@ --- --- title: "Python SDK" -description: "Üretim ortamında AI ajanlarınızın tam olarak ne yaptığını görün: her ajan çalışması, araç çağrısı, model isteği, hook ve insan müdahalesi." +description: "Üretimde AI agenlerinizin tam olarak ne yaptığını görün: her agent çalışması, araç çağrısı, model isteği, hook ve insan müdahalesi." --- -Üretim ortamında AI ajanlarınızın tam olarak ne yaptığını görün: her ajan çalışması, araç çağrısı, model isteği, hook ve insan müdahalesi. Failproof AI Observability Python SDK, ajan kodunuzun içinden bu izi kaydeder, böylece neler olduğunu hata ayıklamak, denetlemek ve değerlendirmek yapabilirsiniz. Failproof AI Observability'nin ajanlarınızı gözlemlemesini istediğiniz her zaman bunu kullanın. +Üretimde AI agenlerinizin tam olarak ne yaptığını görün: her agent çalışması, araç çağrısı, model isteği, hook ve insan müdahalesi. Failproof AI Gözlemlenebilirlik Python SDK'sı bu kayıtları agent kodunuzun içinden tutar, böylece ne olduğunu hata ayıklamak, denetlemek ve değerlendirmek için kullanabilirsiniz. Failproof AI Gözlemlenebilirlik'in agenlerinizi gözlemlemesini istediğiniz zaman kullanın. -Arka planda SDK, yapılandırılmış olayları yerel JSONL dosyalarına yazar ve toplayıcı daemon bunları otomatik olarak alır ve platforma gönderir. Bu dosyaları kendiniz yönetmezsiniz. +Arka planda, SDK yapılandırılmış olayları yerel JSONL dosyalarına yazar ve toplayıcı daemon bunları alıp otomatik olarak platforma gönderir. Bu dosyaları kendiniz yönetmeniz gerekmez. -> **İpucu:** Failproof AI Observability'ye yeni mi başlıyorsunuz? Bu sayfa, tam SDK olay referansıdır. +> **İpucu:** Failproof AI Gözlemlenebilirlik'te yeni misiniz? Bu sayfa tam SDK olay başvurusudur.
@@ -19,15 +19,15 @@ Arka planda SDK, yapılandırılmış olayları yerel JSONL dosyalarına yazar v ## Kurulum -SDK, müşterilere genel bir paket indeksinden değil, özel bir wheel olarak dağıtılır. Onboarding'iniz bunu nasıl elde edeceğinizi, yükleyeceğinizi ve sabitleceğinizi kapsar — erişim gerekiyorsa Failproof AI temsilcinize başvurun. +SDK müşterilere genel bir paket dizini yerine özel bir wheel olarak dağıtılır. Onboarding'iniz bunu nasıl elde edeceğinizi, yükleyeceğinizi ve sabitleyeceğinizi ele alır — erişim için gerekirse Failproof AI temsilcinizle iletişim kurun. -Kurulduktan sonra sahip olduğunuzu doğrulayın: +Kurulduktan sonra, sahip olduğunuzu doğrulayın: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Bir kodlama ajanının tüm entegrasyonu yapmasını tercih mi ediyorsunuz? [Python SDK Agent Skill](/tr/agenteye/python-sdk-skill) kurulum yolunu bilir, araçlaştırma noktalarını planlar, onları yazar ve olayların ulaştığını doğrular. +Bir kodlama agenine tüm entegrasyonu yaptırmayı mı tercih edersiniz? [Python SDK Agent Skill](/tr/agenteye/python-sdk-skill) kurulum yolunu bilir, enstrümantasyon noktalarını planlar, yazar ve olayların gelişini doğrular. --- @@ -59,9 +59,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### Gerçek bir çağrı araçlaştırması +### Gerçek bir çağrıyı enstrümante etme -Pratikte mevcut ajan kodunuzu sararsınız. Bir model çağrısını `model_request` ve `model_response` ile parantez içine alın, böylece iki olay gerçek isteği kapsar ve Failproof AI Observability onları eşleştirebilir: +Uygulamada mevcut agent kodunuzu sararsınız. Model çağrısını `model_request` ile öncesine ve `model_response` ile sonrasına koyun, böylece iki olay gerçek isteği kapsar ve Failproof AI Gözlemlenebilirlik bunları eşleştirebilir: ```python import anthropic @@ -96,11 +96,11 @@ agenteye.event.model_response( ) ``` -Araç çağrılarını da aynı şekilde `tool_use` ve `tool_result` ile sarın, çift arasında aynı `tool_call_id` kullanın. +Araç çağrılarını da aynı şekilde `tool_use` ve `tool_result` ile sarın, çiftin her iki tarafında aynı `tool_call_id`'yi yeniden kullanın. -Bu olaylar panoya ulaştığında nasıl görünüyor, türe göre renkle gösterilmiş ve ortam, ajan ve oturum tarafından filtrelenebilir: +Bu olaylar pano'ya ulaştığında nasıl göründükleri burada, tür başına renk kodlanmış ve ortam, agent ve oturum başına filtrelenebilir: -![Canlı Events akışı, olay türüne göre renkle gösterilmiş ve ortam, ajan ve oturum tarafından filtrelenebilir](/agenteye/images/events-stream.png) +![Canlı Olaylar akışı, olay türüne göre renk kodlanmış ve ortam, agent ve oturum başına filtrelenebilir](/agenteye/images/events-stream.png) --- @@ -114,17 +114,18 @@ agenteye.configure( ) ``` -Herhangi bir `event.*` çağrısından önce bir kez çağırın. Atlayabilmek güvenlidir; varsayılanlar hazır çalışır. Tüm bağımsız değişkenler yalnızca anahtar sözcüktür; yukarıda gösterildiği gibi adıyla geçirin. +Herhangi bir `event.*` çağrısından önce bir kez çağırın. Atlamak güvenlidir; varsayılanlar kullanıma hazır çalışır. Tüm bağımsız değişkenler salt anahtar sözcük; yukarıda gösterildiği gibi adıyla geçirin. -`base_dir` `None` olduğunda (varsayılan), SDK `$AGENTEYE_HOME` okur, ayarlanmışsa, -aksi takdirde `~/.agenteye` dosyasına geri döner. Bu, toplayıcının kendi çözümlemesiyle eşleşir, -bu nedenle tek bir `AGENTEYE_HOME` ortam değişkeni, SDK ve toplayıcı için paylaşılan olay spoolunu yapılandırır. +`base_dir` `None` olduğunda (varsayılan), SDK `$AGENTEYE_HOME` ayarlanmışsa onu okur, +aksi halde `~/.agenteye` öğesine geri döner. Bu toplayıcının kendi çözünürlüğüyle eşleşir, +bu nedenle tek bir `AGENTEYE_HOME` ortam değişkeni hem SDK hem de toplayıcı için +paylaşılan olay spool'unu yapılandırır. --- ## Ortam -Her olayı bir dağıtım ortamı (`production`, `staging`, `qa`, `canary`, vb.) ile etiketleyin. Bir kez ayarlayın; SDK bunu otomatik olarak her olaya ekler. +Her olayı bir dağıtım ortamı ile etiketleyin (`production`, `staging`, `qa`, `canary`, vb.). Bir kez ayarlayın; SDK bunu otomatik olarak her olaya ekler. **Seçenek 1: `configure()` aracılığıyla:** @@ -138,49 +139,49 @@ agenteye.configure(environment="production") export AGENTEYE_ENVIRONMENT=production ``` -**Öncelik:** `configure(environment=...)` ortam değişkenini geçersiz kılar. İkisi de ayarlanmamışsa, varsayılan olarak `"dev"` dir. +**Öncelik:** `configure(environment=...)` ortam değişkenini geçersiz kılar. İkisi de ayarlanmamışsa, varsayılan olarak `"dev"` olur. -Ortam değişkeni, panodaki birinci sınıf filtre olarak görünür ve sunucuda hızlı sorgular için depolanır. +Ortam değişkeni pano'da birinci sınıf bir filtre olarak görünür ve hızlı sorgular için sunucuya kaydedilir. -> **Uyarı:** Ortam değerleri sabit bir `,` virgül içermemelidir. Pano filtreleri tel üzerinde virgülle ayrılmış çoklu seçimi kullanır (`?environment=prod,staging`), bu nedenle `prod,blue` adlı bir ortam iki değere bölünür. Virgül içeren ortamlarla gelen olaylar yutma zamanında reddedilir. +> **Uyarı:** Ortam değerleri literal `,` virgül içermemelidir. Pano filtreleri virgülle ayrılmış çoklu seçimi tel üzerinde kullanır (`?environment=prod,staging`), bu nedenle `prod,blue` adında bir ortam iki değere bölünür. Virgül içeren ortamları olan olaylar yutma zamanında reddedilir. --- ## Veri ve gizlilik -SDK yalnızca açıkça ilettiğiniz alanları kaydeder. İstekler, iletiler, araç girdileri ve çıktıları ve model içeriği, bunları bir `event.*` çağrısına ilettiğiniz için yakalanır. İşleminizden hiçbir şey okunmaz veya örtülü olarak yakalanmaz. Ayarlamadığınız herhangi bir alan, olaydan tamamen atlanır; diske yazılmaz. +SDK yalnızca açıkça ilettiğiniz alanları kaydeder. İstemleri, iletileri, araç girişlerini ve çıktılarını, model içeriğini sadece bunları bir `event.*` çağrısına ilettiğinizde yakalar. Hiçbir şey işleminizden okunmaz veya dolaylı olarak yakalanmaz. Ayarlamazsanız herhangi bir alan olaydan tamamen atlanır; diske yazılmaz. -Bu, redaksiyonu seçiminiz ve sorumluluğunuz yapar. Bir istekte veya araç yükünde depolamak yerine tercih etmeyeceğiniz KKV veya sırlar varsa, olay yöntemine iletmeden önce bunları çıkarın veya maskeleyebilirsiniz. +Bu, redaksiyonu sizin seçiminiz ve sorumluluğunuz haline getirir. İstem veya araç yükü, depolamak istemediğiniz PII veya sırları içeriyorsa, olay yöntemine geçmeden önce çıkarın veya maskeleyebilir. --- -## Olay Referansı +## Olay Başvurusu -Çoğu olay, ilişki kimliği paylaşan başlangıç/bitiş çiftleri halinde gelir: `tool_use` ve `tool_result` bir `tool_call_id` paylaşır, `hook_triggered` ve `hook_completed` bir `hook_id` paylaşır ve `human_wait` ve `human_input` bir `input_id` paylaşır. Başlangıç olayını yayınlayın, işi yapın, ardından aynı kimlikle bitiş olayını yayınlayın. Failproof AI Observability çifti eşleştirir ve `duration_ms` sizin için hesaplar, bu nedenle asla kendiniz `duration_ms` geçirmezsiniz. +Çoğu olay korelasyon kimliğini paylaşan başlangıç/bitiş çiftleri halinde gelir: `tool_use` ve `tool_result` bir `tool_call_id` paylaşır, `hook_triggered` ve `hook_completed` bir `hook_id` paylaşır ve `human_wait` ve `human_input` bir `input_id` paylaşır. Başlangıç olayını yayın, işi yapın, sonra bitiş olayını aynı kimlikle yayın. Failproof AI Gözlemlenebilirlik çifti eşleştirir ve `duration_ms`'yi sizin için hesaplar, bu nedenle `duration_ms`'yi kendiniz hiçbir zaman geçmezsiniz. -![Eşli olaylardan yeniden yapılandırılan bir oturumun git tarzı yürütme grafiği, olay zaman çizelgesi ile birlikte, araç/model/hook dökümü paneli](/agenteye/images/session-detail.png) +![Bir oturumun git tarzı yürütme grafiği yanında zaman çizelgesi, eşleştirilmiş olaylardan yeniden oluşturulmuş, araç/model/hook dağılım paneli ile](/agenteye/images/session-detail.png) Tüm olay yöntemleri bu iki alanı gerektirir: | Alan | Tür | Açıklama | |---|---|---| -| `session_id` | `str` | Üst düzey ajan çalışmasını tanımlar | -| `agent_id` | `str` | Olayı hangi ajanın yayınladığını tanımlar | +| `session_id` | `str` | Üst düzey agent çalışmasını tanımlar | +| `agent_id` | `str` | Oturumda olayı hangi agenin yayınladığını tanımlar | -Tüm yöntemler ayrıca özel meta veri için `**kwargs` kabul eder (bkz. [Özel Alanlar](#özel-alanlar)). +Tüm yöntemler ayrıca özel meta veriler için keyfi `**kwargs`'ı kabul eder ([Özel Alanlar](#custom-fields) bölümüne bakın). --- ### `event.agent_start()` -Bir ajan çalışmaya başladığında yayınlanır. +Bir agent çalışmaya başladığında yayınlanır. ```python agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - parent agent_id for nested agents + parent_id=None, # str | None - nested agents için parent agent_id ) ``` @@ -188,7 +189,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Bir ajan işi bitirdiğinde yayınlanır. +Bir agent çalışmayı bitirdiğinde yayınlanır. ```python agenteye.event.agent_end( @@ -203,14 +204,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -Bir ajan bir araç çağırdığında yayınlanır. `tool_result` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar. +Bir agent bir araç çağırdığında yayınlanır. `tool_result` ile eşleştirin; SDK otomatik olarak `duration_ms`'yi hesaplar. ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", tool_name="web_search", # str, required - tool_call_id="toolu_01", # str, required - correlation key for the matching tool_result + tool_call_id="toolu_01", # str, required - eşleşen tool_result için korelasyon anahtarı input={"query": "..."}, # dict | None ) ``` @@ -219,17 +220,17 @@ agenteye.event.tool_use( ### `event.tool_result()` -Bir araç döndüğünde yayınlanır. `tool_call_id` aracılığıyla `tool_use` ile ilişkili. +Bir araç döndüğünde yayınlanır. `tool_call_id` aracılığıyla `tool_use` ile ilişkilendirilir. ```python agenteye.event.tool_result( session_id="run-001", agent_id="planner", tool_name="web_search", - tool_call_id="toolu_01", # must match the prior tool_use + tool_call_id="toolu_01", # prior tool_use ile eşleşmelidir output={"results": ["..."]}, # Any | None - error=None, # str | None - set if the tool raised - # duration_ms is computed automatically - do not pass it + error=None, # str | None - araç yayınlarsa ayarlayın + # duration_ms otomatik olarak hesaplanır - geçmeyin ) ``` @@ -237,24 +238,24 @@ agenteye.event.tool_result( ### `event.model_request()` -Bir istekte hemen bir LLM'ye gönderilmeden önce yayınlanır. +Bir isteği bir LLM'ye göndermeden hemen önce yayınlanır. ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - any provider/model string; not validated - messages=[ # list[dict] | None - conversation turns + model="claude-sonnet-4-6", # str | None - herhangi bir sağlayıcı/model dizesi; doğrulanmaz + messages=[ # list[dict] | None - konuşma dönüşleri {"role": "user", "content": "..."}, ], - system="You are helpful.", # Any | None - str or list of content blocks - tools=[ # list[dict] | None - tool schemas offered to the model + system="You are helpful.", # Any | None - str veya içerik blokları listesi + tools=[ # list[dict] | None - modele sunulan araç şemaları {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -`messages` girdileri düz bir dize `content` veya Anthropic tarzında blok listesi `content` kabul eder. Örnekleme parametreleri (`temperature`, `max_tokens`, vb.) ekstra kwargs olarak geçirilebilir. +`messages` girişleri düz bir dize `content` veya Anthropic tarzı blok listesi `content`'i kabul eder. Örnekleme parametreleri (`temperature`, `max_tokens`, vb.) ekstra kwargs olarak geçirilebilir. --- @@ -266,31 +267,31 @@ LLM bir yanıt döndüğünde yayınlanır. agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - any provider/model string; not validated + model="claude-sonnet-4-6", # str | None - herhangi bir sağlayıcı/model dizesi; doğrulanmaz stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None - content=[ # Any | None - str, or list of content blocks + content=[ # Any | None - dize veya Anthropic tarzı içerik blokları listesi {"type": "text", "text": "..."}, ], role="assistant", # str | None ) ``` -`content`, düz bir dize (genel sağlayıcılar) veya Anthropic tarzında içerik blokları listesini kabul eder. Araç çağrıları `content` içinde `{"type": "tool_use", ...}` blokları olarak yaşar, ayrı `tool_calls` alanı yok. +`content` düz bir dizeyi (genel sağlayıcılar) veya Anthropic tarzı içerik blokları listesini kabul eder. Araç çağrıları `content` içinde `{"type": "tool_use", ...}` blokları olarak yaşar, ayrı `tool_calls` alanı olmaz. --- ### `event.hook_triggered()` -Bir hook ateşlendiğinde yayınlanır. `hook_completed` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar. +Bir hook ateşlendiğinde yayınlanır. `hook_completed` ile eşleştirin; SDK otomatik olarak `duration_ms`'yi hesaplar. ```python agenteye.event.hook_triggered( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", # str, required - hook_id="hook-abc", # str, required - correlation key + hook_id="hook-abc", # str, required - korelasyon anahtarı trigger_event="tool_use", # str | None input={"tool": "search"}, # Any | None ) @@ -300,18 +301,18 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Bir hook bittiğinde yayınlanır. `hook_id` aracılığıyla `hook_triggered` ile ilişkili. +Hook bittiğinde yayınlanır. `hook_id` aracılığıyla `hook_triggered` ile ilişkilendirilir. ```python agenteye.event.hook_completed( session_id="run-001", agent_id="planner", hook_name="pre_tool_use", - hook_id="hook-abc", # must match the prior hook_triggered + hook_id="hook-abc", # prior hook_triggered ile eşleşmelidir outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms is computed automatically - do not pass it + # duration_ms otomatik olarak hesaplanır - geçmeyin ) ``` @@ -319,7 +320,7 @@ agenteye.event.hook_completed( ### `event.error()` -İşlenmeyen bir hata oluştuğunda yayınlanır. +İşlenmemiş bir hata oluştuğunda yayınlanır. ```python agenteye.event.error( @@ -333,63 +334,63 @@ agenteye.event.error( --- -## İnsan-Döngü-Olay Olayları +## İnsan-in-the-Loop Olayları -İnsan döngüsü içinde olaylar, bir kişinin ajan yürütmesine girdiği anları (onay bekleme, giriş sağlama, duraklatma veya ajan durdurma) size denetim sağlar. İnsanların yanıt vermesinin ne kadar sürdüğünü ölçmenize (SDK eşli olaylarda `duration_ms` otomatik olarak hesaplar), ajan duraklatılan veya kesilen kişiyi denetlemenize ve pano oluşturmak için onay ve gözetim iş akışları oluşturmanıza olanak tanırlar. +İnsan-in-the-loop olayları, bir kişinin agent'ın yürütülmesine girdiği anlara gözetim verirsiniz (onay bekleme, giriş sağlama, duraklatma veya agent'ı durdurma). Bunlar insanların yanıt vermesinin ne kadar sürdüğünü ölçmenize (SDK eşleştirilmiş olaylarda `duration_ms`'yi otomatik olarak hesaplar), kimin bir agent'ı duraklatıp kestiğini denetlemenize ve pano'da yüzey olan onay ve gözetim iş akışları oluşturmanıza izin verir. ### `event.human_wait()` -Ajan bir kişinin giriş sağlamasını beklemek için yürütmeyi duraklatsa yayınlanır. `human_input` ile eşleştirin; SDK otomatik olarak `duration_ms` hesaplar (insanın yanıt vermesi ne kadar sürdü). +Agent yürütülmeyi durdurup bir insanın girdi sağlamasını beklediğinde yayınlanır. `human_input` ile eşleştirin; SDK otomatik olarak `duration_ms`'yi hesaplar (insanın yanıt vermesinin ne kadar sürdüğü). ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - correlation key for the matching human_input - prompt="Do you approve this action?", # str | None - the question shown to the human - options=["approve", "reject", "defer"], # list[str] | None - choices presented to the human - reason="approval_required", # str | None - why the agent is waiting + input_id="inp-abc", # str, required - eşleşen human_input için korelasyon anahtarı + prompt="Do you approve this action?", # str | None - insana gösterilen soru + options=["approve", "reject", "defer"], # list[str] | None - insana sunulan seçimler + reason="approval_required", # str | None - agenin neden beklediği ) ``` ### `event.human_input()` -Bir insan giriş sağladığında ve ajan devam ettiğinde yayınlanır. `input_id` aracılığıyla `human_wait` ile ilişkili. `duration_ms` otomatik olarak hesaplanır ve çağıran tarafından geçirilmemelidir. +Bir insan girdi sağladığında ve agent devam ettiğinde yayınlanır. `input_id` aracılığıyla `human_wait` ile ilişkilendirilir. `duration_ms` otomatik olarak hesaplanır ve çağıran tarafından geçirilmemesi gerekir. ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str, required - must match the prior human_wait - response="approve", # str | None - the human's answer (free text or selected option) - # duration_ms is computed automatically - do not pass it + input_id="inp-abc", # str, required - prior human_wait ile eşleşmelidir + response="approve", # str | None - insanın yanıtı (serbest metin veya seçili seçenek) + # duration_ms otomatik olarak hesaplanır - geçmeyin ) ``` ### `event.human_pause()` -Bir insan etkin olarak ajan duraklatsa yayınlanır (örneğin bir pano kontrolü aracılığıyla). Ajan askıya alınır ancak sonlandırılmaz. +Bir insan agent'ı aktif olarak duraklattığında yayınlanır (ör. pano kontrolü aracılığıyla). Agent askıya alınır ancak sonlandırılmaz. ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - who paused the agent + user_id="usr_42", # str | None - agent'ı kimin durduğu ) ``` ### `event.human_interrupt()` -Bir insan etkin olarak ajan yürütme ortasında durdursa yayınlanır. `human_pause` aksine, ajanın işi askıya alınmak yerine sonlandırılır. +Bir insan yürütüldüğü sırada agent'ı aktif olarak durdurduğunda yayınlanır. `human_pause` aksine, agent'ın çalışması askıya alınmaktan ziyade sonlandırılır. ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - who interrupted the agent - at_step="tool_use:web_search", # str | None - what the agent was doing when stopped + user_id="usr_42", # str | None - agent'ı kimin kestiği + at_step="tool_use:web_search", # str | None - durdurulduğu zaman agenin ne yaptığı ) ``` @@ -397,7 +398,7 @@ agenteye.event.human_interrupt( ## Özel Alanlar -Herhangi bir ekstra anahtar sözcük bağımsız değişkeni, standart alanlardan sonra olaya eklenir: +Herhangi bir ekstra anahtar sözcük bağımsız değişkeni standart alanlardan sonra olaya eklenir: ```python agenteye.event.tool_use( @@ -405,20 +406,20 @@ agenteye.event.tool_use( agent_id="planner", tool_name="db_query", tool_call_id="toolu_02", - tenant_id="acme", # custom field - region="us-east-1", # custom field + tenant_id="acme", # özel alan + region="us-east-1", # özel alan ) ``` -`timestamp`, `type` ve `environment` ayrılmıştır ve özel alanlar olarak iletilirse `ValueError` yükseltir (`Reserved field names cannot be used as custom fields: [...]`). `session_id` ve `agent_id` her olay yönteminde gerekli parametrelerdir ve ikinci kez sağlanamaz; bunu yaparsanız Python `TypeError` yükseltir. Bunun yerine ortamı `configure(environment=...)` (veya `AGENTEYE_ENVIRONMENT` değişkeni) ile ayarlayın. +`timestamp`, `type` ve `environment` ayrılmıştır ve özel alanlar olarak geçirilirse `ValueError` yükseltir (`Reserved field names cannot be used as custom fields: [...]`). `session_id` ve `agent_id`, her olay yönteminde gerekli parametrelerdir ve ikinci bir kez sağlanamaz; bunu yaparsanız Python `TypeError` yükseltir. Bunun yerine `configure(environment=...)` (veya `AGENTEYE_ENVIRONMENT` değişkeni) ile ortamı ayarlayın. -Alanlarını sorgulamak istediğinizde yüklemeleri yapılandırılmış JSON olarak tutun. JSON'un yerel olarak desteklemediği değerler (tarihler, UUID'ler, ondalıklar, setler, baytlar veya model nesneleri gibi) kayıt güvenli bir şekilde devam etmesi için dizelere dönüştürülür. +Alanlarını sorgulamak istediğinizde yükleri yapılandırılmış JSON olarak tutun. JSON'un yerel olarak desteklemediği değerler — tarihler, UUID'ler, ondalıklar, kümeler, baytlar veya model nesneleri gibi — kayıt güvenli bir şekilde devam etmesi için dizelere dönüştürülür. --- ## Olaylar Nasıl Yazılır -Olaylar işlemde arabelleğe alınır ve `flush_interval` saniye (varsayılan 500 ms) başına diske boşaltılır. Her boşaltma bir JSONL dosyası yazar: +Olaylar işlem içinde arabellekte tutulur ve her `flush_interval` saniye (varsayılan 500 ms) diske yıkılır. Her yıkama bir JSONL dosyası yazar: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl @@ -426,11 +427,11 @@ Olaylar işlemde arabelleğe alınır ve `flush_interval` saniye (varsayılan 50 Toplayıcı bu dizini izler ve dosyaları otomatik olarak yükler. Bu dosyaları doğrudan yönetmeniz gerekmez. -Her dosya atomik olarak yazılır: SDK geçici bir dosyaya yazar ve sonra onu yerine adlandırır, bu nedenle toplayıcı hiçbir zaman yarı yazılmış dosya görmez. Son bir boşaltma ayrıca işleminiz çıktığında çalışır, bu nedenle son aralıkta arabelleğe alınan olaylar kaybolmaz. Toplayıcı çevrimdışıysa, olaylar diska dosya olarak birikir ve bir kez geri geldiğinde gönderilir. +Her dosya atomik olarak yazılır: SDK geçici bir dosyaya yazar ve ardından yerleştiriyor, bu nedenle toplayıcı hiçbir zaman yarı yazılmış bir dosya görmez. Son yıkama da işleminiz çıktığında çalışır, bu nedenle son aralamada arabellekte tutulan olaylar kaybolmaz. Toplayıcı çevrimdışıysa, olaylar diskte dosya olarak birikir ve çevrimiçi geldiğinde gönderilir. --- ## Sonraki adımlar -- [Olay akışı](/tr/agenteye/event-stream): bu olayların canlı ulaştığını izleyin, ortam, ajan ve oturum tarafından renkle gösterilmiş ve filtrelenebilir. -- [Oturumlar](/tr/agenteye/sessions): eşli olayların her ajan çalışmasını yürütme grafiği ve zaman çizelgesi olarak nasıl yeniden yapılandırdığını görün. \ No newline at end of file +- [Olay akışı](/tr/agenteye/event-stream): bu olayları canlı olarak izleyin, renk kodlanmış ve ortam, agent ve oturum başına filtrelenebilir. +- [Oturumlar](/tr/agenteye/sessions): eşleştirilmiş olayların her agent çalışmasını bir yürütme grafiği ve zaman çizelgesi olarak nasıl yeniden oluşturduğunu görün. \ No newline at end of file diff --git a/docs/tr/agenteye/queries.mdx b/docs/tr/agenteye/queries.mdx index e15b8545..daf88075 100644 --- a/docs/tr/agenteye/queries.mdx +++ b/docs/tr/agenteye/queries.mdx @@ -1,55 +1,56 @@ --- title: "Sorgular" -description: "Agent verilerinize herhangi bir soru sorun ve saniyeler içinde cevap alın." +description: "Ajan verilerinize herhangi bir soru sorun ve saniyeler içinde cevap alın." --- -Agent verilerinize herhangi bir soru sorun ve saniyeler içinde cevap alın. Failproof AI Observability, etkinlikleriniz ve değerlendirmeleriniz üzerinde kaydedilmiş, hazır kullanıma sunulmuş sorguların bir kütüphanesini sunar; böylelikle boş bir SQL düzenleyicisinden başlamak yerine çalışan bir örnek üzerinden başlarsınız. -![Kaydedilmiş sorgular kütüphanesi: yeniden kullanılabilir sorguların ızgarası, hem yerleşik ön ayarlar hem de özel olanlar](/agenteye/images/queries.png) +Ajan verilerinize herhangi bir soru sorun ve saniyeler içinde cevap alın. Failproof AI Observability, etkinlik ve değerlendirmeleriniz üzerinde kayıtlı, çalışmaya hazır sorgulardan oluşan bir kütüphane sunarak, boş bir SQL editöründen değil, çalışan bir örnek kullanarak başlamanızı sağlar. -*`//queries` konumundaki kaydedilmiş sorgular kütüphanesi: yerleşik ön ayarlar ekibinizin kaydettiği sorgularla yan yana yer almakta.* +![Kaydedilmiş sorgular kütüphanesi: hem yerleşik ön ayarlar hem de özel sorgulardan oluşan yeniden kullanılabilir sorgular ızgarası](/agenteye/images/queries.png) + +*`//queries` adresindeki kaydedilmiş sorgular kütüphanesi: yerleşik ön ayarlar, takımınızın kaydettiği sorgularla birlikte.* ## Boş bir sayfadan değil, bir ön ayardan başlayın -Tablo adlarını hatırlamanız veya sıfırdan SQL yazmanız gerekmez. Kütüphane, ekiplerin en sık sorduğu sorulara yönelik yerleşik ön ayarlarla açılır ve bu ön ayarlar kendi ekibinizin kaydettiği ve adlandırdığı sorgularla yan yana yer alır. İstediğinize yakın birini seçin ve cevaba ulaşmak için gereken yolun çoğunu tamamlamış olursunuz. +Tablo adlarını hatırlamanız veya SQL'i sıfırdan yazmanız gerekmez. Kütüphane, takımların en sık sorduğu sorular için yerleşik ön ayarlarla açılır ve bunlar takımınızın kaydettiği ve adlandırdığı sorgularla birlikte bulunur. İstediğinize yakın olanı seçin ve cevaba varmak için çoğunu başarmış olursunuz. -Her kaydedilmiş sorgu kuruluş kapsamlıdır ve paylaşılıdır; bu nedenle ekip üyelerinizin yazdığı faydalı olanlar sizin de olur. Sorguyu bir kez adlandırıp bir açıklama ekleyin ve kuruluşunuzdaki herkes onu bulabilir, çalıştırabilir veya sonuçlarını daha sonra bir panoya sabitleyebilir. +Her kaydedilmiş sorgu org kapsamlıdır ve paylaşılır, bu nedenle takım arkadaşlarınızın yazdığı yararlı olanlar sizin de olur. Bir sorguyu adlandırın ve bir açıklama verin, ve kuruluşunuzdaki herkes onu bulabilir, çalıştırabilir veya sonuçlarını daha sonra bir panoya sabitleyebilir. -`//queries` konumunda bulabilirsiniz. +`//queries` adresinde bulabilirsiniz. -## Düzenleyin ve SQL bestecisinde çalıştırın +## Onu ayarlayın ve SQL bestecisinde çalıştırın -Herhangi bir sorguyu açın ve SQL bestecisine iner; burada sorguyu ayarlayabilir ve cevabı hemen görebilirsiniz: dışa aktarma yok, gidiş-dönüş yok, başkasının beklenmesi yok. +Herhangi bir sorguyu açın ve SQL bestecisine iner, burada onu ayarlayabilir ve cevabı hemen görebilirsiniz: dışa aktarma yok, gidiş-dönüş yok, başka biri için bekleme yok. -![Kaydedilmiş sorguyu çalıştıran SQL sorgu bestecisi, şema kenar çubuğu ve canlı sonuç ızgarası](/agenteye/images/query-lab.png) +![Kaydedilmiş bir sorguyu çalıştıran SQL sorgusu bestecisi, şema kenar çubuğu ve canlı sonuç ızgarası](/agenteye/images/query-lab.png) -*SQL bestecisi: sol tarafta sorgunuz, kolon adını asla tahmin etmeniz gerekmeyen şema kenar çubuğu ve altta canlı sonuç ızgarası.* +*SQL bestecisi: solda sorgunuz, sütun adını hiçbir zaman tahmin etmemeniz için şema kenar çubuğu ve aşağıda canlı sonuç ızgarası.* -- **Şema kenar çubuğu** analitik tabloları ve sütunlarını gösterir; böylelikle alan adlarını aramadan sorgu oluşturabilirsiniz. -- **Canlı sonuç ızgarası** çalıştırdığınız anda satırları döndürür; bu nedenle tahmin etme ve yeniden tahmin etme yerine saniyeler içinde yineleme yaparsınız. -- **Tasarım gereği salt okunurdur.** Sorgular olay deponunuza karşı çalıştırılır ve sunucuda doğrulanır: yalnızca `SELECT` ve `WITH` deyimleri, deyim zaman aşımı ve satır sınırıyla birlikte izin verilir. Keşifsel bir sorgu verilerinizi asla değiştiremez ve kaçan bir sorgu sizin için durdurulur. +- **Bir şema kenar çubuğu**, analitik tabloları ve bunların sütunlarını göstererek, alan adlarını aramadan bir sorgu oluşturabilmenizi sağlar. +- **Canlı bir sonuç ızgarası**, çalıştırmanın hemen ardından satırları döndürür, bu nedenle tahminde bulunup yeniden tahminde bulunmak yerine saniyeler içinde yineleyebilirsiniz. +- **Tasarım gereği salt okunur.** Sorgular olay deponuza karşı çalıştırılır ve sunucuda doğrulanır: yalnızca `SELECT` ve `WITH` deyimleri, ifade zaman aşımı ve satır sınırlaması ile izin verilir. Keşifsel bir sorgu verilerinizi hiçbir zaman değiştiremez ve kaçak bir sorgu sizin için durdurulur. -Sonuçtan memnun musunuz? Bunu kütüphaneye geri kaydedin; böylelikle tüm ekip bundan faydalanır veya çıktısını bir panoya çizgi, çubuk, alan veya pasta döşemesi olarak sabitleyin. +Sonuçtan memnun musunuz? Tüm takımın onu devralması için bunu kütüphaneye geri kaydedin veya çıkışını çizgi, çubuk, alan veya pasta döşemesi olarak bir panoya sabitleyin. -## Terminal'den çalıştırın veya asistanın bunları yazmasına izin verin +## Terminal'den çalıştırın veya yardımcının bunları yazmasını sağlayın -Aynı kaydedilmiş sorgular çalışmakta olduğunuz her yerde sizi takip eder: +Aynı kaydedilmiş sorgular nerede çalışırsanız çalışın sizi takip eder: -- **Terminal'den.** `agenteye` CLI'ı tam da aynı sorguları listeler, çalıştırır ve kaydeder; böylelikle sonucu bir komut dosyasına bırakabilir, CI'ye bağlayabilir veya bir kodlama ajanına verebilirsiniz. +- **Terminal'den.** `agenteye` CLI'si, aynı sorgularla birlikte, sonucu bir betiğe düşürebilir, CI'ye bağlayabilir veya bir kodlama ajanına verebilirsiniz. ```bash -agenteye query list # terminal'deki aynı kaydedilmiş sorgular -agenteye query run errs --arg prod # birini çalıştırın ve satırları yazdırın (boru için --json ekleyin) +agenteye query list # aynı kaydedilmiş sorgular, terminal'inizden +agenteye query run errs --arg prod # birini çalıştırın ve satırları yazdırın (borulama için --json ekleyin) ``` - Tam komut seti için [CLI ve ajanlar](/tr/agenteye/cli-and-agents) konusuna bakın. + Tam komut seti için [CLI ve ajanlar](/tr/agenteye/cli-and-agents) bölümünü görebilirsiniz. -- **AI asistanından.** SQL'i nasıl ifade edeceğiniz konusunda emin değil misiniz? Panodaki [AI asistanına](/tr/agenteye/assistant) düz İngilizce sorun ve sorguyu taslak halinde oluşturup kütüphaneyinize kaydedecektir. +- **AI yardımcısından.** SQL'i nasıl ifade edeceğinizden emin değil misiniz? Panodaki [AI yardımcısına](/tr/agenteye/assistant) düz İngilizce soruda bulunun ve sorguyu hazırlayıp kütüphanenize kaydedecektir. -Kaydedilmiş sorguyu çalıştırmak `queries:run` izni tarafından kontrol edilir; sorgu oluşturma veya silme izinlerinden ayrı tutulur; bu nedenle herkesin kütüphaneyi yeniden yazmasına izin vermeden okuma erişimi verebilirsiniz. +Kaydedilmiş bir sorguyu çalıştırmak `queries:run` izni tarafından yasaklanmıştır, sorgular oluşturma veya silme izinlerinden ayrı tutulmuştur, bu nedenle herkesin kütüphaneyi yeniden yazmasına izin vermeden okuma erişimi verebilirsiniz. -## İlgili +## İlişkili -- [Panolar](/tr/agenteye/dashboards): sorgu sonuçlarını paylaşılan, kuruluş genelinde çizelgelere sabitleyin. -- [AI asistanı](/tr/agenteye/assistant): sorulara düz İngilizce olarak sorun ve sorgu alın. -- [CLI ve ajanlar](/tr/agenteye/cli-and-agents): terminal'den aynı sorguları çalıştırın ve kaydedin. \ No newline at end of file +- [Panolar](/tr/agenteye/dashboards): sorgu sonuçlarını paylaşılan, org genelinde grafikler halinde sabitleyin. +- [AI yardımcısı](/tr/agenteye/assistant): sorguları düz İngilizce ile sorun ve cevap alın. +- [CLI ve ajanlar](/tr/agenteye/cli-and-agents): terminal'inizden aynı sorgularla birlikte çalıştırın ve kaydedin. \ No newline at end of file diff --git a/docs/tr/agenteye/security.mdx b/docs/tr/agenteye/security.mdx index 4a0fd8ac..a6a4ba6f 100644 --- a/docs/tr/agenteye/security.mdx +++ b/docs/tr/agenteye/security.mdx @@ -1,26 +1,25 @@ --- ---- title: "Güvenlik" -description: "Failproof AI Observability, üretim aracılarınızın yakınına yerleştirilmek üzere oluşturulmuştur; bu, istemlerinizi, araç girdilerini ve çıktılarını görebilmesi anlamına gelir." +description: "Failproof AI Observability, üretim ajanlarınızın yanında yer alacak şekilde tasarlanmıştır; bu da istemlerinizi, araç girdilerini ve çıktılarını görebildiği anlamına gelir." --- -Failproof AI Observability, üretim aracılarınızın yakınına yerleştirilmek üzere oluşturulmuştur; bu, istemlerinizi, araç girdilerini ve çıktılarını görebilmesi anlamına gelir. Bu sayfa, bu verileri nasıl izole, kontrollü ve sizin elinizde tuttuğunu açıklamaktadır. Failproof AI Observability'yi bir güvenlik incelemesi için değerlendiriyorsanız, buradan başlayın. +Failproof AI Observability, üretim ajanlarınızın yanında yer alacak şekilde tasarlanmıştır; bu da istemlerinizi, araç girdilerini ve çıktılarını görebildiği anlamına gelir. Bu sayfa verileri nasıl izole, kontrollü ve sizin elinizde tuttuğunu açıklamaktadır. Failproof AI Observability'yi güvenlik incelemesi için değerlendiriyorsanız, buradan başlayın. --- ## Verileriniz kendi ortamınızda kalır -Failproof AI Observability, kendi kendine barındırılır. Olaylar, istemler, model yanıtları ve analizler kendi veritabanlarınızda, kendi ortamınızda depolanır. Hiçbir şey depolama için bir üçüncü taraf SaaS'a gönderilmez ve verileriniz kendi bulut hesabınızda kalır. +Failproof AI Observability kendi sunucularınızda barındırılır. Olaylar, istemler, model yanıtları ve analizler kendi veritabanlarınızda, kendi ortamınızda depolanır. Hiçbir şey üçüncü taraf bir SaaS'a depolama için gönderilmez ve verileriniz kendi bulut hesabınızda kalır. --- ## Kiracı izolasyonu -Bir Failproof AI Observability örneği birçok kuruluşu barındırabilir ve her biri depolama katmanında izole edilir — yalnızca kullanıcı arayüzü tarafından değil, veritabanı tarafından uygulanır: +Bir Failproof AI Observability örneği birçok kuruluşu barındırabilir ve her biri depolama katmanında izole edilmiştir — sadece UI tarafından değil, veritabanı tarafından zorunlu kılınmıştır: -- Bir kuruluşun işletimsel verileri (kullanıcılar, anahtarlar, panolar, kaydedilmiş sorgular) o kuruluşa ait olup, kuruluşlar arası okumalar veritabanı tarafından engellenir. -- Her alınan olaya sahip olduğu kuruluş damgası vurulur, böylece bir kuruluşun olayları asla başka bir kuruluş tarafından okunamaz. +- Bir kuruluşun operasyonel verileri (kullanıcılar, anahtarlar, panolar, kaydedilmiş sorgular) o kuruluşa kapsamlandırılır ve kuruluşlar arası okumalar veritabanı tarafından engellenir. +- Her ingestion edilen olay, sahibi olan kuruluşla işaretlenir; bu nedenle bir kuruluşun olayları asla başka bir kuruluş tarafından okunamaz. Her pano rotası bir kuruluş slug'ı altında kapsamlandırılır (`//…`). @@ -28,42 +27,42 @@ Her pano rotası bir kuruluş slug'ı altında kapsamlandırılır (`/ ## Oturum açma -Failproof AI Observability, şifresiz, e-posta tabanlı oturum açma kullanır. Kimse tarafından ele geçirilebilecek veya sızan bir şifre yoktur. Bir kullanıcı tek seferlik bir kod (veya tek tıklamalı sihirli bir bağlantı) talep eder, bu onlara e-posta ile gönderilir ve hızlı bir şekilde sona erer. Oturum açma bir **izin listesi** tarafından korunur: yalnızca izin verdiğiniz e-posta adresleri (veya etki alanları) kimlik doğrulaması yapabilir. +Failproof AI Observability, şifresiz, e-posta tabanlı oturum açmayı kullanır. Kimlik avına uğrayacak veya sızdırılacak bir şifre yoktur. Bir kullanıcı, kendilerine e-postayla gönderilen ve hızlı bir şekilde geçerliliğini yitiren tek kullanımlık bir kod (veya tek tıklamalı bir sihirli bağlantı) talep eder. Oturum açma bir **izin listesi** tarafından kısıtlanır: sadece izin verdiğiniz e-posta adresleri (veya etki alanları) kimlik doğrulaması yapabilir. -![Failproof AI Observability oturum açma ekranı; tek kullanımlık bir kod e-postanıza gönderir](/agenteye/images/login.png) +![Failproof AI Observability oturum açma ekranı, e-postanıza tek kullanımlık bir kod gönderir](/agenteye/images/login.png) --- -## API anahtarlarıyla kapsamlı erişim +## API anahtarlarıyla kapsamlandırılmış erişim -Her istemci, ayrıntılı, en düşük ayrıcalık izinlerine sahip bir API anahtarı ile kimlik doğrulaması yapar. Bir toplayıcının yalnızca `events:add` öğesi gerekir; bir pano veya asistan anahtarı salt okunur olabilir; yıkıcı eylemler (silme, yeniden oluşturma) dahil etmeyi seçtiğiniz ayrı yetkilendirmelerdir. +Her istemci, ayrıntılı, en az ayrıcalık izinleri taşıyan bir API anahtarı ile kimlik doğrulaması yapar. Bir toplayıcının sadece `events:add` öğesine ihtiyacı vardır; bir pano veya asistan anahtarı salt okunur olabilir; yıkıcı eylemler (silme, yeniden oluşturma) dahil etmeyi seçtiğiniz ayrı izinlerdir. -![API anahtarları sayfası: her anahtarın izin verileri, okuma, yazma ve yıkıcı kapsama göre renk kodlu](/agenteye/images/api-keys.png) +![API anahtarları sayfası: her anahtarın izin verileri, okuma, yazma ve yıkıcı kapsama göre renklendirilmiş](/agenteye/images/api-keys.png) -Kurulum için yönetici önyükleme anahtarını tutun ve diğer her şey için dar anahtarlar yayınlayın. [API anahtarları](/tr/agenteye/api-keys) sayfasına bakın. +Kurulum için yönetici bootstrap anahtarını saklayın ve diğer her şey için dar anahtarlar verin. [API anahtarları](/tr/agenteye/api-keys) başlıklı makaleye bakın. --- -## Salt okunur, onay kapılı asistan +## Salt okunur, onay geçitli bir asistan -Pano içindeki [yapay zeka asistanı](/tr/agenteye/assistant) verileriniz üzerinde soruları yanıtlar, ancak tasarım gereği sınırlandırılmıştır: +Panodaki [AI asistanı](/tr/agenteye/assistant) verileriniz hakkında soruları yanıtlar, ancak tasarım gereği kısıtlıdır: -- Varsayılan olarak **salt okunur**: SQL'i yalnızca `SELECT`/`WITH` sorgularına, tek deyimli, satır sınırı ile izin veren bir koruma yoluyla çalıştırır. -- Oluşturduğu her şey (kaydedilmiş bir sorgu, bir pano) **onay kapılı**: gerçekleşmeden önce her yazıyı gözden geçirip onaylarsınız. +- **Varsayılan olarak salt okunur**: SQL'i sadece `SELECT`/`WITH` sorgularına, tek deyim olarak ve satır sınırı ile izin veren bir koruma gözetmeniyle çalıştırır. +- Oluşturduğu her şey (kaydedilmiş bir sorgu, bir pano) **onay geçitli**: her yazma işleminden önce gözden geçirin ve onaylayın. - **Asla silemez**. -Yani bir takım arkadaşı "bu hafta hangi aracılar en çok hata verdi?" diye sorabilir ve cevaba göre hareket edebilir, asistan kendi başına verilerinizi değiştirip kaldıramadan. +Böylece bir takım arkadaşı "bu hafta hangi ajanlar en fazla hata verdi?" diye sorabilir ve cevabı işletebilir; asistan kendi başına verilerinizi değiştiremiyor veya kaldıramıyor. --- -## Aktarım sırasında +## Transit sırasında -Tüm trafik HTTPS üzerinde çalışır. TLS'yi kendi sertifikalarınızla sonlandırırsınız, böylece toplayıcıdan sunucuya ve tarayıcıdan sunucuya trafik aktarımda şifrelenir. +Tüm trafik HTTPS üzerinden çalışır. Kendi sertifikalarınız ile TLS sonlandırırsınız; böylece toplayıcı-sunucu ve tarayıcı-sunucu trafiği transit sırasında şifrelenir. --- ## Sonraki adımlar -- [Genel Bakış](/tr/agenteye/overview): Failproof AI Observability'nin nasıl bir araya geldiği. +- [Genel Bakış](/tr/agenteye/overview): Failproof AI Observability nasıl bir araya gelir. - [API anahtarları](/tr/agenteye/api-keys): toplayıcı, pano ve asistan için erişimi kapsamlandırın. -- [Gözlenebilirlik](/tr/agenteye/observability): Failproof AI Observability'nin aracılarınızdan neleri yakaladığı. \ No newline at end of file +- [Gözlemlenebilirlik](/tr/agenteye/observability): Failproof AI Observability ajanlarınızdan neyi yakalar. \ No newline at end of file diff --git a/docs/tr/agenteye/sessions.mdx b/docs/tr/agenteye/sessions.mdx index 32b9b557..556a7bac 100644 --- a/docs/tr/agenteye/sessions.mdx +++ b/docs/tr/agenteye/sessions.mdx @@ -1,57 +1,57 @@ --- title: "Oturumlar ve Yürütme Grafiği" -description: "Bir çalıştırmadan gelen her olay, tek bir okunabilir satırda toplanmış ve git stili bir yürütme grafiği olarak çizilmiş; saniyeler içinde okuyabilirsiniz." +description: "Bir çalıştırmadan gelen her olay, tek bir okunabilir satıra dönüştürülür ve git tarzı bir yürütme grafiği olarak çizilir; saniyeler içinde okuyabilirsiniz." --- -Bir çalıştırmanın neden başarısız olduğunu tahmin etmeyi bırakın. Failproof AI Observability, bir çalıştırmadan gelen her olayı tek bir okunabilir satıra derler, sonra tüm çalıştırmayı saniyeler içinde okuyabileceğiniz git stili bir resim olarak çizer; böylece aracınızın tam olarak ne yaptığını, adım adım görebilirsiniz. +Bir çalıştırmanın neden başarısız olduğunu tahmin etmeyi bırakın. Failproof AI Observability, bir çalıştırmadan gelen her olayı tek bir okunabilir satıra dönüştürür, ardından tüm çalıştırmayı saniyeler içinde okuyabileceğiniz git tarzı bir görüntü olarak çizer; böylece aracınızın tam olarak ne yaptığını, adım adım görürsünüz. -![Oturumlar listesi: ortamlar ve aracılar arasında çalıştırma başına bir satır, durum rozetleri ve değerlendirme puanı rozet işaretleriyle](/agenteye/images/sessions-list.png) +![Oturumlar listesi: ortamlar ve aracılar arasında çalıştırma başına bir satır, durum göstergeleri ve değerlendirme puanı rozetleri ile](/agenteye/images/sessions-list.png) -*Çalıştırma başına bir satır: durum rozeti çalıştırmanın nasıl sonlandığını bir bakışta gösterir ve bir değerlendirici bağlandıktan sonra bir puan rozeti yanında yer alır.* +*Çalıştırma başına bir satır: durum göstergesi, çalıştırmanın nasıl sonuçlandığını bir bakışta gösterir ve bir değerlendirici bağlandığında puan rozeti görünür.*
-*Aracı izleme: hedeften araçlara ve son cevaba kadar tek bir çalıştırmayı adım adım takip edin.* +*Aracı izleme: tek bir çalıştırmayı adım adım, hedeften araçlara, son cevaba kadar takip edin.* --- ## Her çalıştırmayı bir bakışta görün -Ham olay izleri her adımın gerçeği olmasına rağmen, düzinelerce çalıştırma arasında binlerce adımınız olduğunda, adıma değil çalıştırmaya ihtiyacınız vardır. Oturumlar sayfası, bir çalıştırmanın tüm olaylarını tek bir satıra derler; böylece bir günün etkinliği, bir bilgi akışı yerine taranabilir bir listeye dönüşür. +Ham olay izi, her adımın gerçeğidir, ancak düzinelerce çalıştırma arasında binlerce adımınız olduğunda, adıma değil çalıştırmaya ihtiyacınız vardır. Oturumlar sayfası, bir çalıştırmanın tüm olaylarını tek bir satırda birleştirir, böylece bir günün etkinliği taranabilir bir liste haline gelir. -Her satır bir durum rozeti taşır; böylece başarısız bir çalıştırma, sağlıklı bir çalıştırmadan hiçbir şeye tıklamadan öne çıkar. Tarih aralığı, ortam, aracı veya oturuma göre filtreleyin; "her şey"ten "önemsediğim çalıştırma"ya birkaç tıklamada ulaşın. +Her satır bir durum göstergesi taşır, bu nedenle başarısız bir çalıştırma, hiçbir şeye tıklamadan önce sağlıklı bir çalıştırmadan öne çıkar. Tarih aralığı, ortam, aracı veya oturuma göre filtreleyin; "her şey"ten "önem verdiğim çalıştırma"ya birkaç tıklama ile gidin. -Bir değerlendirici bağladıktan sonra, her tamamlanan çalıştırma otomatik olarak puanlanır ve en son puanı satırda bir rozet olarak görünür. Herhangi bir puan aralığına göre filtre yapabilirsiniz; böylece "bu hafta tüm düşük puanlı üretim çalıştırmalarını göster" manual inceleme değil, bir filtredir. Birini kurmayana kadar oturumlar tam çalıştırmayı yakalar; sadece henüz bir puanı yoktur. +Bir değerlendirici bağladığınızda, tamamlanan her çalıştırma otomatik olarak puanlanır ve en son puanı satırda rozet olarak görünür. Herhangi bir puan aralığına göre filtreleyebilirsiniz; bu nedenle "bu hafta düşük puanlı tüm üretim çalıştırmalarını göster" manuel bir inceleme değil, bir filtredir. Siz bir tane kuruncaya kadar, oturumlar yine de tam çalıştırmayı yakalarlar; sadece henüz puan taşımadıkları için. --- -## Tüm çalıştırmayı bir resim olarak okuyun +## Tüm çalıştırmayı bir görüntü olarak okuyun -![Git stili yürütme grafiği, olay zaman çizelgesi yanında, araç, model ve kanca dağılımı paneli](/agenteye/images/session-detail.png) +![Bir oturumun git tarzı yürütme grafiği, olay zaman çizelgesinin yanında, araç, model ve hook dökümü paneli ile](/agenteye/images/session-detail.png) -*Yürütme grafiği (sol) olay zaman çizelgesinin yanında yer alır; sağ ray, çalıştırma için araçları, modelleri, kancaları ve jeton harcamasını ayrıntılarıyla gösterir.* +*Yürütme grafiği (sol) olay zaman çizelgesinin yanında yer alır; sağ raya çalıştırmanın araçlar, modeller, hooklar ve token harcaması dökümü yazılır.* -Herhangi bir oturumu açmak için tıklayın ve yürütme grafiğini görmek: aracıların, araçların, kancaların ve model çağrılarının zaman içinde nasıl ortaya çıktığının git stili görünümü. Paralel alt aracıların her biri kendi şeridine dallanır; böylece hangi işin yan yana çalıştığını, hangi alt aracının durduğunu ve çalıştırmanın nerede yoldan çıktığını görebilirsiniz; bunu günlük duvarından başınızda oynatmanıza gerek kalmaz. +Herhangi bir oturumu açmak için tıklayın ve yürütme grafiğini görüntüleyin: aracıların, araçların, hookların ve model çağrılarının zaman içinde nasıl geliştiğinin git tarzı görünümü. Parallel alt aracıların her biri kendi şeride dallanır, böylece hangi işin yan yana çalıştığını, hangi alt aracının takıldığını ve çalıştırmanın nerede hatalı gittiğini görebilirsiniz; bunu kafa içinde günlüklerin bir duvarından tekrar oynatmanıza gerek kalmaz. -Sağ ray, çalıştırma başına dağılımı sunar: hangi araçlar ve modeller çalıştı, hangi kancalar tetiklendi ve çalıştırma jetonlarda ne kadar harcadı. Bu, "bu çalıştırma neden bu kadar çok maliyetli oldu?" veya "hangi araç yavaş olan?" sorusunun cevabıdır; grafiğin hemen yanında yer alır. +Sağ raya çalıştırma başına dökümü verir: hangi araçlar ve modeller çalıştı, hangi hooklar tetiklendi ve çalıştırma token olarak ne harcadı. Bu, "bu çalıştırma neden bu kadar pahalıya mal oldu?" veya "hangi araç yavaş olan?" sorusunun cevabı, bunu tetikleyen grafiğin hemen yanında oturmaktadır. -Bireysel olaylar adreslenebilir; böylece birine "oturumun, yaklaşık üçte ikisi kadar aşağı" yerine bir anın bağlantısını verebilirsiniz. Herhangi bir olaydan bağlantıyı kopyalayın veya bir [denetim](/tr/agenteye/audits) bulgusu veya hatadan birini takip edin; oturumlar açılır ve o olay seçilir ve konumlandırılır. Bu çok uzun çalıştırmalar için de geçerlidir: zaman çizelgesi tarayıcınız uğruna sınırlandırılmış bir pencere yükler ve bu pencereyi aşan bir bağlantı yine de olayını bulur ve sizi başlangıca bırakmaz. Olay saklama pencerenizden yaşlanmışsa, sayfa sessizce hiçbir şey seçmek yerine bunu size söyler. +Bireysel olaylar adreslenebilir, bu nedenle birilerine "oturum, yaklaşık üçte iki aşağıda" demek yerine bir olaya bağlantı verebilirsiniz. Herhangi bir olaydan bağlantıyı kopyalayın veya bir [audit](/tr/agenteye/audits) bulgusu veya hatadan birini takip edin; oturum o olay seçili ve kaydırılmış şekilde açılır. Bu, çok uzun çalıştırmalar için de geçerlidir: zaman çizelgesi, tarayıcınızın iyiliği için sınırlı bir pencere yükler ve bu pencereyi geçen bir bağlantı, başlangıca bırakmak yerine olayını bulur. Olay, bekletme pencerenizin dışında yaşlanmışsa, sayfa sessizce hiçbir şey seçmek yerine size bunu söyler. --- ## Nerede bulunur -Her pano sayfası org kapsamındadır (`//…`). Oturumlar, sol yan çubukta **Gözlemle** altında, Olayların yanında yer alır; listenin en üstünde tarih aralığı, ortam, aracı ve oturumsal filtreler bulunur. Her satır, tam yürütme grafiğinden bir tıklama uzaktadır. +Her kontrol paneli sayfası, kuruluşunuza göre kapsama alınmıştır (`//…`). Oturumlar, sol kenar çubuğundaki **Gözlemle** altında, Olayların yanında bulunur; tarih aralığı, ortam, aracı ve oturum filtreleri listenin üstünde yer alır. Her satır, tam yürütme grafiğine bir tıkla uzaklıktadır. -Puan rozetlerini ve puan aralığı filtrelemesini açmak için bir değerlendirici bağlayın: bkz. [Değerlendirmeler](/tr/agenteye/evaluations). +Puan rozetlerini ve puan aralığı filtrelemesini açmak için bir değerlendirici bağlayın: [Değerlendirmeler](/tr/agenteye/evaluations) bölümüne bakın. --- ## İlgili -- [Olay akışı](/tr/agenteye/event-stream): her oturumun toplanmış olduğu ham, adım başına izleme. -- [Değerlendirmeler](/tr/agenteye/evaluations): her çalıştırmanın filtre yapabileceğiniz bir puan rozeti alması için bir değerlendirici bağlayın. -- [Telemetri](/tr/agenteye/telemetry): çalıştırmalar aracınızdan bu oturumlara nasıl ulaşır? \ No newline at end of file +- [Olay akışı](/tr/agenteye/event-stream): her oturumun yukarı haddelendiği ham, adım başına iz. +- [Değerlendirmeler](/tr/agenteye/evaluations): her çalıştırmanın puan rozeti alması için bir değerlendirici bağlayın; buna göre filtreleyebilirsiniz. +- [Telemetri](/tr/agenteye/telemetry): çalıştırmalar aracınızdan bu oturumlara nasıl gider. \ No newline at end of file diff --git a/docs/tr/agenteye/telemetry.mdx b/docs/tr/agenteye/telemetry.mdx index 6e4dde0a..0eb4c6d3 100644 --- a/docs/tr/agenteye/telemetry.mdx +++ b/docs/tr/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- title: "Performans Metrikleri" -description: "Modellerinizin, araçlarınızın veya hook'larınızın yavaşladığı veya maliyeti artırdığı anı görün ve kullanıcılarınız bunu hissetmeden tail-latency artışını yakalayın." +description: "Modellerinizin, araçlarınızın veya hook'larınızın yavaşladığı veya maliyetinizi artırdığı anı görün ve tail-latency artışını kullanıcılarınız hissetmeden önce yakalayın." --- -Modellerinizin, araçlarınızın veya hook'larınızın yavaşladığı veya maliyeti artırdığı anı görün ve kullanıcılarınız bunu hissetmeden tail-latency artışını yakalayın. Üç ayrı sayfa ham zamanlama verilerini p50, p95 ve p99'a dönüştürerek bir bakışta okuyabileceğiniz hale getirir. +Modellerinizin, araçlarınızın veya hook'larınızın yavaşladığı veya maliyetinizi artırdığı anı görün ve tail-latency artışını kullanıcılarınız hissetmeden önce yakalayın. Üç ayrı sayfa ham zamanlamaları p50, p95 ve p99'a dönüştürerek bir bakışta okuyabileceğiniz veriler sunar. -![Models sayfası, latency ısı haritasını, yüzdelik bantı ve model başına token, maliyet ve bağlam penceresi rakamlarını gösteriyor](/agenteye/images/models.png) -*Models sayfası: latency ısı haritası, yüzdelik bandı ve model başına tokenler, tahmini maliyet ve bağlam penceresi doldurma.* +![Latency ısı haritası, yüzdelik dilim bandı ve model başına token, maliyet ve context-window rakamlarını gösteren Models sayfası](/agenteye/images/models.png) +*Models sayfası: latency ısı haritası, yüzdelik dilim bandı ve model başına tokenler, tahmini maliyet ve context-window doldurma oranı.* -## Ortalamaların kötü çalışmaları saklamasına izin vermeyin +## Ortalamaların kötü çalıştırmaları gizlemesine izin vermeyin -Ortalama latency numarası rahatlatıcı ve işe yaramaz: elli çağrıdan birinin takılıp kalıp sabah 2'de on-call personelini çağırmasının üzerini örter. Models, Tools ve Hooks sayfaları bunu yapmayı reddeder. Her biri aynı yapıya sahiptir, böylece bunu bir kez öğrenirsiniz: +Ortalama latency numarası rahatlatıcıdır ve işe yaramaz: elli çağrıdan birini donduran ve saat 2'de nöbetçiyi çağıran durumu gizler. Models, Tools ve Hooks sayfaları bunu yapmayı reddeder. Her biri aynı yapıda olduğu için bir kez öğrenirsiniz: -- Trendi bir bakışta görmek için **24-kutulu sparkline**: bu durum kötüye gidiyor mu? -- p50, p95 ve p99 latency ile **vitals şeridi**, böylece tipik çalışma ve tail yan yana oturur. -- **Latency ısı haritası**, 24 zaman kutusu x latency segmentleri, *ne zaman* yavaş çağrıların kümelendiğini gösterir. -- **Yüzdelik bant**: p50 çizgisi ile p25 ila p75 ve p10 ila p90 gölgeli şeritleri ve p99 noktaları, böylece yayılma ortalama yerine görünür kalır. +- Trendi bir bakışta görmek için bir **24-bin kısa grafik**: bu daha mı kötüleşiyor? +- p50, p95 ve p99 latency'li bir **vitals şeridi**, böylece tipik çalıştırma ve tail yan yana durur. +- **Latency ısı haritası**, yatayda 24 zaman dilimi dikey olarak latency seviyeleri, yavaş çağrıların *ne zaman* kümelendiğini gösterir. +- **Yüzdelik dilim bandı**: p50 çizgisi ve p25 ile p75 arasında gölgelendirilmiş şeritler, p10 ile p90 arasında gölgelendirilmiş şeritler ve p99 noktaları, böylece yayılım ortalamanın arkasında kaybolmak yerine görünür kalır. -Paylaşılan bir hover crosshair ısı haritasını ve bandı zaman olarak bağlar, böylece tail spike her ikisinde de zaman içinde sıralanır ve tek bir ortalama çizgisinin arkasında gizlenmez. Üç sayfayı da panonuzun **observe** bölümünde bulun, her biri kuruluşunuza kapsamlı ve tarih aralığı, ortam, agent ve oturum ile filtrelenebilir. +Paylaşılan bir hover çaprazı ısı haritası ile bandı bağlar, böylece bir tail artışı zaman içinde her ikisinde de hizalanır ve tek bir ortalama çizginin arkasında gizlenmez. Üç sayfayı da panoninizin **observe** bölümünde bulun, her biri kuruluşunuzun kapsamında ve tarih aralığı, ortam, agent ve oturum tarafından filtrelenebilir. -## Models: her modelin size ne kadara mal olduğunu tam olarak görün +## Models: her modelin size tam olarak maliyetini görün -Models sayfası (üstte gösterilmiştir) bir faturanın her zaman ortaya çıkardığı iki soruya yanıt verir: hangi model ve ne kadar. Paylaşılan latency görünümünün üzerine, **model başına token tüketimi**, **tahmini maliyet** ve **bağlam penceresi doldurma** ekler, böylece kontrolsüz prompt büyümesi ve yaklaşan sıkıştırma sizi şaşırtmadan önce görünür. +Models sayfası (yukarıda gösterilmiştir) bir faturanın her zaman gündeme getirdiği iki soruyu yanıtlar: hangi model ve ne kadar. Paylaşılan latency görünümüne ek olarak, **model başına token tüketimi**, **tahmini maliyet** ve **context-window doldurma oranı** ekler, böylece kontrolsüz prompt büyümesi ve yaklaşan sıkıştırma sizi şaşırtmadan görünür olur. -Failproof AI Observability ortak model kimliklerini otomatik olarak tanır. Bir pencere yanlış görünüyorsa veya kendi özel modelinizi çalıştırıyorsanız, **Settings** altında, **model context windows** içinde düzeltin veya ekleyin ve doldurma okumaları bunu takip eder. +Failproof AI Observability, yaygın model kimliklerini otomatik olarak tanır. Bir pencere yanlış görünüyorsa veya kendi özel modelinizi çalıştırıyorsanız, **Settings**'de **model context windows** bölümünde düzeltin veya ekleyin, ardından doldurma oranları takip eder. -## Tools: yavaş olanı kırık olandan ayırt edin +## Tools: yavaş olanları kırılan olanlardan ayırt edin -Bir tool çağrısı yavaş olabilir veya sessizce başarısız olabilir ve bunu günlükleri inceledikten sonra değil de saniyeler içinde bilmek istersiniz. +Bir tool çağrısı yavaş olabilir veya sessizce başarısız olabilir ve bunu günlükleri inceledikten sonra değil, saniyeler içinde bilmek isteyebilirsiniz. -![Tools sayfası, paylaşılan latency ısı haritasını ve yüzdelik bandı yanında başarı ve hata dökümü ile tool dağılım çubuğunu gösteriyor](/agenteye/images/tools.png) -*Tools sayfası: aynı ısı haritası ve yüzdelik bant, artı başarı ve hata dökümü ile tool dağılım çubuğu.* +![Paylaşılan latency ısı haritası ve yüzdelik dilim bandı ile başarı ve başarısızlık dökümü ve tool dağılım çubuğunu gösteren Tools sayfası](/agenteye/images/tools.png) +*Tools sayfası: aynı ısı haritası ve yüzdelik dilim bandı, artı başarı ve başarısızlık dökümü ve tool dağılım çubuğu.* -Paylaşılan latency görünümünün yanında, Tools sayfası bir **başarı ve hata dökümü** ve **tool dağılım çubuğu** ekler, böylece bir bakışta hangi toolları en çok kullandığınızı ve hangilerinin hata bütçenizi tükettiğini görürsünüz. +Paylaşılan latency görünümünün yanında, Tools sayfası bir **başarı ve başarısızlık dökümü** ve bir **tool dağılım çubuğu** ekler, böylece bir bakışta hangi araçlara en çok güvendiğinizi ve hangi araçların hata bütçenizi yediğini görürsünüz. -## Hooks: tam hook ve trigger'ı belirleyin +## Hooks: tam olarak hangi hook'u ve tetikleyiciyi bulun -Bir lifecycle hook bir çalışmayı yavaşlatırken, "hook'lar yavaş" üzerinde harekete geçebileceğiniz bir şey değildir. Hooks sayfası sizi önemli olana götürür. +Bir lifecycle hook bir çalıştırmayı yavaşlattığında, "hook'lar yavaş" üzerinde harekete geçebileceğiniz bir şey değildir. Hooks sayfası sizi önemli olan kişiye götürür. -![Hooks sayfası, latency'nin paylaşılan ısı haritası ve yüzdelik bandı üzerinde hook adı ve trigger olayına göre dökülmüş olarak gösteriyor](/agenteye/images/hooks.png) -*Hooks sayfası: latency'nin hook adı ve trigger olayına göre dökülmüş.* +![Latency'i hook adı ve tetikleyici olaya göre kırılmış ve paylaşılan ısı haritası ile yüzdelik dilim bandı üzerinde gösteren Hooks sayfası](/agenteye/images/hooks.png) +*Hooks sayfası: latency hook adı ve tetikleyici olaya göre kırılmış.* -Aynı latency ısı haritası ve yüzdelik bandı üzerinde, Hooks sayfası etkinliği **hook adı** ve **trigger olayı** tarafından kırıyor, böylece ilgilenilmesi gereken tek hook'a ve tek olaya inersiniz. +Aynı latency ısı haritası ve yüzdelik dilim bandı üzerinde, Hooks sayfası aktiviteyi **hook adı** ve **tetikleyici olaya** göre böler, böylece dikkat gerektiren tek hook'a ve tek olaya inersiniz. ## İlgili -- [Event stream](/tr/agenteye/event-stream): her olayın canlı, renkle kodlanmış izi. -- [Sessions](/tr/agenteye/sessions): olayları çalışma başına bir satırda toplayın ve yürütme grafiğini açın. -- [Error tracking](/tr/agenteye/error-tracking): panoda kırmızı olan her şey için tek triage yüzeyi. -- [Dashboards](/tr/agenteye/dashboards): filoğunuz genelinde toparlama görünümleri. \ No newline at end of file +- [Event stream](/tr/agenteye/event-stream): her olayın canlı, renkli izi. +- [Sessions](/tr/agenteye/sessions): olayları bir çalıştırma başına bir satırda toplayın ve yürütme grafiğini açın. +- [Error tracking](/tr/agenteye/error-tracking): panoda kırmızıya çevirilen her şey için bir triage yüzeyi. +- [Dashboards](/tr/agenteye/dashboards): filo genelinde özet görünümler. \ No newline at end of file diff --git a/docs/tr/architecture.mdx b/docs/tr/architecture.mdx index 74d27996..8922c925 100644 --- a/docs/tr/architecture.mdx +++ b/docs/tr/architecture.mdx @@ -1,10 +1,11 @@ --- +--- title: Mimari -description: "Hook işleyicisinin, config yüklemesinin ve politika değerlendirmesinin dahili olarak nasıl çalıştığı" +description: "Hook handler, config yükleme ve policy değerlendirmesinin dahili olarak nasıl çalıştığı" icon: sitemap --- -Bu belge failproofai'nin dahili olarak nasıl çalıştığını açıklar: hook sistemi aracı araç çağrılarını nasıl engeller, yapılandırma nasıl yüklenir ve birleştirilir, politikalar nasıl değerlendirilir ve dashboard aracı aktivitesini nasıl izler. +Bu dokümanda failproofai'nin dahili olarak nasıl çalıştığı anlatılmaktadır: hook sistemi agent tool çağrılarını nasıl kesintiye uğratır, konfigürasyon nasıl yüklenir ve birleştirilir, policyler nasıl değerlendirilir ve dashboard agent aktivitesini nasıl izler. --- @@ -12,18 +13,18 @@ Bu belge failproofai'nin dahili olarak nasıl çalıştığını açıklar: hook failproofai iki bağımsız alt sisteme sahiptir: -1. **Hook işleyicisi** - Claude Code'un her aracı araç çağrısında çağırdığı hızlı bir CLI alt işlemi. Politikaları değerlendirir ve bir karar döndürür. -2. **Aracı İzleme (Dashboard)** - Aracı oturumlarını izlemek ve politikaları yönetmek için bir Next.js web uygulaması. +1. **Hook handler** - Claude Code'un her agent tool çağrısında çağırdığı hızlı bir CLI alt işlemi. Policyları değerlendirir ve bir karar döndürür. +2. **Agent Monitor (Dashboard)** - Agent oturumlarını izlemek ve policyları yönetmek için bir Next.js web uygulaması. -Her iki alt sistem de `~/.failproofai/` ve projenin `.failproofai/` dizininde bulunan yapılandırma dosyalarını paylaşır, ancak ayrı işlemler olarak çalışır ve yalnızca dosya sistemi üzerinden iletişim kurar. +Her iki alt sistem de `~/.failproofai/` ve projenin `.failproofai/` dizinindeki konfigürasyon dosyalarını paylaşır, ancak ayrı işlemler olarak çalışırlar ve yalnızca dosya sistemi üzerinden iletişim kurarlar. --- -## Hook işleyicisi +## Hook handler -### Claude Code ile entegrasyon +### Claude Code ile Entegrasyon -`failproofai policies --install` komutunu çalıştırdığınızda, `~/.claude/settings.json` dosyasına şu gibi girdiler yazılır: +`failproofai policies --install` komutunu çalıştırdığınızda, `~/.claude/settings.json` dosyasına şu gibi girişler yazılır: ```json { @@ -44,9 +45,9 @@ Her iki alt sistem de `~/.failproofai/` ve projenin `.failproofai/` dizininde bu } ``` -Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreToolUse` komutunu bir alt işlem olarak çağırır ve stdin üzerinden bir JSON yükü iletir. +Claude Code daha sonra her tool çağrısından önce `failproofai --hook PreToolUse` komutunu bir alt işlem olarak çağırarak stdin'de bir JSON payload gönderir. -### Yükü biçimi +### Payload formatı ```json { @@ -60,11 +61,11 @@ Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreTo } ``` -`PostToolUse` olayları için, yükü ayrıca aracın çıktısı ile birlikte `tool_result` içerir. +`PostToolUse` olayları için payload, tool çıktısıyla birlikte `tool_result` de içerir. -İşleyici 1 MB stdin sınırını zorunlu kılar. Bu sınırı aşan yükler atılır ve tüm politikalar örtük olarak izin verir. +Handler 1 MB stdin sınırını uygular. Bu sınırı aşan payloadlar atılır ve tüm policyler örtük olarak izin verir. -### Yanıt biçimi +### Yanıt formatı **Reddet (PreToolUse):** ```json @@ -85,7 +86,7 @@ Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreTo } ``` -**Yönerge (Stop hariç herhangi bir olay):** +**Talimat ver (Stop dışında herhangi bir olay):** ```json { "hookSpecificOutput": { @@ -94,9 +95,9 @@ Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreTo } ``` -**Durdur olayı yönergesi:** +**Stop olayı talimatı:** - Çıkış kodu: `2` -- Sebep stderr'ye yazılır (stdout değil) +- Sebep stderr'e yazılır (stdout'a değil) **İzin ver:** - Çıkış kodu: `0` @@ -104,10 +105,10 @@ Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreTo **İleti ile izin ver:** -`allow(message)` bir politikanın işlem izin verildiğinde bile bilgilendirici bağlamı Claude'a geri göndermesini sağlar. Hook işleyicisi aşağıdaki JSON'ı **stdout**'a yazar (bir config dosyasına değil — bu, yukarıdaki reddet ve yönerge yanıtları gibi, hook işleyicisinin Claude Code'a verdiği yanıttır): +`allow(message)` bir policy'nin işlem izin verildiğinde bile Claude'a bilgilendirici bağlam göndermesine olanak tanır. Hook handler stdout'a şu JSON'ı yazar (bir config dosyası değil — bu, deny ve talimat yanıtları gibi handler'ın Claude Code'a yanıtıdır): ```json -// Hook işleyicisi işlemi tarafından stdout'a yazılmış +// Hook handler işlemi tarafından stdout'a yazılır { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." @@ -115,78 +116,78 @@ Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreTo } ``` - Çıkış kodu: `0` (işlem izin verilir) -- Birden fazla politika bir ileti ile `allow` döndüğünde, bunların mesajları yeni satırlarla birleştirilerek tek bir `additionalContext` dizesine dönüştürülür -- Hiçbir politika ileti sağlamazsa, stdout boş olur (daha önce olduğu gibi) +- Birden fazla policy ileti ile `allow` döndürdüğünde, mesajları yeni satırlarla birleştirerek tek bir `additionalContext` string'ine dönüştürülür +- Hiçbir policy mesaj sağlamadığında, stdout boş olur (öncekiyle aynı) -### İşleme ardışık düzeni +### İşleme hattı -`src/hooks/handler.ts` tam ardışık düzeni uygular: +`src/hooks/handler.ts` tam hattı uygular: ```text stdin JSON - → yükü ayrıştır (max 1 MB) - → oturum meta verilerini çıkar (session_id, cwd, tool_name, tool_input, vb.) - → readMergedHooksConfig(cwd) ← proje + yerel + genel config'i birleştirir - → etkinleştirilmiş yerleşik politikaları çözülen parametrelerle kaydet - → customPoliciesPath'den özel politikaları yükle (ayarlanmışsa) - → özel politikaları politika kayıt defterine kaydet - → tüm politikaları değerlendir (yerleşikleri önce, ardından özel olanları) - → ilk reddet kısa devre - → yönerge kararları birikir - → izin iletileri birikir - → JSON kararı stdout'a yaz - → olayı ~/.failproofai/hook-activity/current.jsonl dosyasına kaydet - → çık + → parse payload (max 1 MB) + → extract session metadata (session_id, cwd, tool_name, tool_input, etc.) + → readMergedHooksConfig(cwd) ← merges project + local + global config + → register enabled builtin policies with resolved params + → load custom policies from customPoliciesPath (if set) + → register custom policies into policy registry + → evaluate all policies (builtins first, then custom) + → first deny short-circuits + → instruct decisions accumulate + → allow messages accumulate + → write JSON decision to stdout + → persist event to ~/.failproofai/hook-activity/current.jsonl + → exit ``` -Tüm işlem LLM çağrıları olmayan tipik yükler için 100ms'den kısa sürer. +Tüm işlem, LLM çağrısı olmayan tipik payloadlar için 100ms altında çalışır. --- -## Yapılandırma yükleme +## Konfigürasyon yükleme -`src/hooks/hooks-config.ts` üç kaplam yapılandırması yükleme uygular. +`src/hooks/hooks-config.ts` üç kapsam config yüklemesini uygular. ```text -[1] {cwd}/.failproofai/policies-config.json ← proje (en yüksek öncelik) -[2] {cwd}/.failproofai/policies-config.local.json ← yerel -[3] ~/.failproofai/policies-config.json ← genel (en düşük öncelik) +[1] {cwd}/.failproofai/policies-config.json ← project (highest priority) +[2] {cwd}/.failproofai/policies-config.local.json ← local +[3] ~/.failproofai/policies-config.json ← global (lowest priority) ``` Birleştirme mantığı: -- `enabledPolicies` - üç dosya arasında çoğaltılmamış birleşim -- `policyParams` - politika başına anahtar, onu tanımlayan ilk dosya tamamen kazanır -- `customPoliciesPath` - onu tanımlayan ilk dosya kazanır -- `llm` - onu tanımlayan ilk dosya kazanır +- `enabledPolicies` - üç dosya genelinde kaldırılan duplikatlarla birleşim +- `policyParams` - her policy başına anahtar, onu tanımlayan ilk dosya tamamen kazanır +- `customPoliciesPath` - bunu tanımlayan ilk dosya kazanır +- `llm` - bunu tanımlayan ilk dosya kazanır -Web dashboard, bir proje cwd ile çağrılmadığından, okuma ve yazma için `readHooksConfig()` (yalnızca genel) kullanır. +Web dashboard, proje cwd'si olmadığı için okuma ve yazma işlemleri için `readHooksConfig()` (yalnızca global) kullanır. --- -## Politika değerlendirmesi +## Policy değerlendirmesi -`src/hooks/policy-evaluator.ts` politikaları sırayla çalıştırır. +`src/hooks/policy-evaluator.ts` policyları sırayla çalıştırır. -Her politika için: +Her policy için: -1. Politikanın `params` şemasını arayın (varsa). -2. Birleştirilmiş config'den `policyParams[policy.name]` okuyun. -3. Kullanıcı tarafından sağlanan değerleri şema varsayılanları üzerine birleştirerek `ctx.params` üretin. -4. Çözülen bağlamla `policy.fn(ctx)` çağırın. +1. Policy'nin `params` şemasını arayın (eğer varsa). +2. Birleştirilmiş configten `policyParams[policy.name]` dosyasını okuyun. +3. `ctx.params` oluşturmak için şema varsayılanlarının üzerine kullanıcı tarafından sağlanan değerleri birleştirin. +4. Çözümlenen bağlamla `policy.fn(ctx)` çağırın. 5. Sonuç `deny` ise, hemen durdurun ve bu kararı döndürün. -6. Sonuç `instruct` ise, mesajı biriktirir ve devam edin. -7. Sonuç `allow` ise, sonraki politikaya geçin. +6. Sonuç `instruct` ise, mesajı biriktirin ve devam edin. +7. Sonuç `allow` ise, bir sonraki policye geçin. -Tüm politikalar çalıştıktan sonra: -- Herhangi bir `deny` döndürüldüyse, reddet yanıtını yayınlayın. -- Herhangi bir `instruct` dönüşü toplandıysa, tüm mesajlar birleştirilmiş tek bir yönerge yanıtı yayınlayın. -- Aksi takdirde, izin yanıtı yayınlayın (boş stdout, çıkış 0). +Tüm policyler çalıştıktan sonra: +- Herhangi bir `deny` döndürüldüyse, deny yanıtını gönderin. +- Herhangi bir `instruct` dönüşü toplandıysa, tüm mesajları birleştirerek tek bir instruct yanıtı gönderin. +- Aksi takdirde, izin yanıtı gönderin (boş stdout, çıkış 0). --- -## Yerleşik politikalar +## Yerleşik policyler -`src/hooks/builtin-policies.ts` tüm 39 yerleşik politikayı `BuiltinPolicyDefinition` nesneleri olarak tanımlar: +`src/hooks/builtin-policies.ts` tüm 39 yerleşik policy'yi `BuiltinPolicyDefinition` nesneleri olarak tanımlar: ```typescript interface BuiltinPolicyDefinition { @@ -204,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -`params` kabul eden politikalar her parametre için tür ve varsayılan değerler içeren `PolicyParamsSchema` bildirir. Politika değerlendiricisi `fn` çağrısından önce çözülen değerleri `ctx.params` öğesine enjekte eder. Politika işlevleri `ctx.params` öğesini null-koruması olmadan okur çünkü varsayılanlar her zaman önce uygulanır. +`params` kabul eden policyler, her parametre için türler ve varsayılanlar içeren bir `PolicyParamsSchema` bildirir. Policy değerlendirici, `fn` çağrılmadan önce çözümlenen değerleri `ctx.params` içine enjekte eder. Policy fonksiyonları `ctx.params` değerlerini varsayılanlar ilk uygulandığından null-guard olmadan okur. -Politikalar içindeki desen eşleşmesi ham dizge eşleşmesi değil, ayrıştırılmış komut jetonlarını (argv) kullanır. Bu, shell işleci enjeksiyonu yoluyla atlatmayı engeller (örn. `sudo systemctl status *` için bir desen `; rm -rf /` eklemek suretiyle atlatılamaz). +Policyler içindeki desen eşleştirmesi ham string eşleştirmesi değil, ayrıştırılmış komut tokens'ları (argv) kullanır. Bu, shell operatörü enjeksiyonu aracılığıyla bypass'ı önler (örneğin `sudo systemctl status *` için bir desen, komuta `; rm -rf /` eklenerek bypass edilemez). --- -## Özel politikalar +## Özel policyler -`src/hooks/custom-hooks-registry.ts` bir `globalThis` tabanlı kayıt defteri uygular: +`src/hooks/custom-hooks-registry.ts` `globalThis`'e dayalı bir kayıt defteri uygular: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -222,28 +223,28 @@ export const customPolicies = { }; export function getCustomHooks(): CustomHook[] { ... } -export function clearCustomHooks(): void { ... } // testlerde kullanılır +export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` kullanıcının politika dosyasını yükler: +`src/hooks/custom-hooks-loader.ts` kullanıcının policy dosyasını yükler: -1. Config'den `customPoliciesPath` okuyun; yoksa atla. -2. Mutlak yola çözün; dosya varlığını kontrol edin. -3. Tüm `from "failproofai"` importlarını gerçek dist yoluna yeniden yazın, böylece `customPolicies` aynı `globalThis` kayıt defterine çözülür. -4. ESM uyumluluğunu sağlamak için transitif yerel importları özyinelemeli olarak yeniden yazın. -5. Geçici `.mjs` dosyaları yazın ve giriş dosyasını `import()` edin. -6. Kayıtlı kancaları almak için `getCustomHooks()` çağırın. +1. Configten `customPoliciesPath` dosyasını okuyun; yoksa atlayın. +2. Mutlak yola çözümleyin; dosyanın var olduğunu kontrol edin. +3. `customPolicies` aynı `globalThis` kayıt defterine çözümlemesin diye tüm `from "failproofai"` importlarını gerçek dist yoluna yeniden yazın. +4. ESM uyumluluğu sağlamak için geçişli yerel importları yinelemeli olarak yeniden yazın. +5. Geçici `.mjs` dosyaları yazın ve entry dosyasını `import()` edin. +6. Kayıtlı hook'ları almak için `getCustomHooks()` çağırın. 7. `finally` bloğunda tüm geçici dosyaları temizleyin. -Herhangi bir hata durumunda (dosya bulunamadı, sözdizimi hatası, import hatası), hata `~/.failproofai/hook.log` dosyasına kaydedilir ve yükleyici boş bir dizi döndürür. Yerleşik politikalar etkilenmez. +Herhangi bir hatada (dosya bulunamadı, sözdizimi hatası, import hatası), hata `~/.failproofai/hook.log` dosyasına kaydedilir ve loader boş bir dizi döndürür. Yerleşik policyler etkilenmez. -Özel politikalar tüm yerleşik politikaların ardından değerlendirilir. Özel bir politika `deny` yine de başka özel politikaları kısa devreye sokar (ancak bu noktada tüm yerleşikler zaten çalışmıştır). +Özel policyler tüm yerleşik policylerden sonra değerlendirilir. Özel bir policy `deny` dönüşü hâlâ başka özel policyler'i kısa devreye uğratır (ancak bu noktada tüm yerleşikler zaten çalıştırılmıştır). --- ## Aktivite günlüğü -Her hook olayından sonra, işleyici `~/.failproofai/hook-activity/current.jsonl` dosyasına bir JSONL satırı ekler; bu, bir sayfaya ulaştığında `page--.jsonl` dosyasına döner: +Her hook olayından sonra, handler `~/.failproofai/hook-activity/current.jsonl` dosyasına bir JSONL satırı ekler ve bir sayfaya ulaştığında `page--.jsonl` dosyasına dönüştürülür: ```json { @@ -258,44 +259,44 @@ Her hook olayından sonra, işleyici `~/.failproofai/hook-activity/current.jsonl } ``` -İzin vermeyen bir karar alan her politika için bir satır. İzin kararları günlüğe kaydedilmez (dosyayı küçük tutmak için). +Non-allow kararı veren her policy için bir satır. Allow kararları günlüğe kaydedilmez (dosyayı küçük tutmak için). --- ## Dashboard mimarisi -Dashboard, React Server Components ve Server Actions ile App Router kullanan bir **Next.js 16** uygulamasıdır. +Dashboard, React Server Components ve Server Actions'ı kullanan App Router'ı olan bir **Next.js 16** uygulamasıdır. ```text app/ - layout.tsx ← Kök düzeni (tema, telemetri, nav) - projects/page.tsx ← Sunucu bileşeni: tüm Claude projelerini listele - project/[name]/page.tsx ← Sunucu bileşeni: projedeki oturumları listele + layout.tsx ← Root layout (theme, telemetry, nav) + projects/page.tsx ← Server component: list all Claude projects + project/[name]/page.tsx ← Server component: list sessions in a project project/[name]/session/ - [sessionId]/page.tsx ← Sunucu bileşeni: oturum görüntüleyicisini işle - policies/page.tsx ← İstemci bileşeni: politika yönetimi + aktivite günlüğü + [sessionId]/page.tsx ← Server component: render session viewer + policies/page.tsx ← Client component: policy management + activity log actions/ - get-hooks-config.ts ← Config + politika listesini oku - update-hooks-config.ts ← Politikayı aç/kapat - update-policy-params.ts ← Politika parametrelerini güncelle - get-hook-activity.ts ← Aktivite günlüğünü sayfalandır/ara - install-hooks-web.ts ← Tarayıcıdan kancaları kur/kaldır + get-hooks-config.ts ← Read config + policy list + update-hooks-config.ts ← Toggle policy on/off + update-policy-params.ts ← Update policy parameters + get-hook-activity.ts ← Paginate/search activity log + install-hooks-web.ts ← Install/remove hooks from the browser api/ - download/[project]/[session]/route.ts ← CLI başına oturum dışa aktarması (JSONL veya JSON) + download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` **Veri akışı:** -- Sayfa bileşenleri dosya sisteminden proje/oturum verilerini doğrudan okumak için `lib/projects.ts` ve `lib/log-entries.ts` çağırır (okumalar için API katmanı yok). -- Politikalar sayfası tüm mutasyonlar için Server Actions kullanır (aç/kapat, parametreler güncellemesi, kur/kaldır). -- Oturum görüntüleyicisi Claude'un JSONL transkript biçimini ayrıştırır ve mesajların ve araç çağrılarının bir zaman çizelgesini işler. +- Sayfa bileşenleri, dosya sisteminden proje/oturum verisini doğrudan okumak için `lib/projects.ts` ve `lib/log-entries.ts` dosyalarını çağırır (okumalar için API katmanı yok). +- Policies sayfası tüm mutasyonlar (toggle, params güncelleme, install/remove) için Server Actions kullanır. +- Oturum viewer'ı Claude'un JSONL transkript formatını ayrıştırır ve mesajlar ile tool çağrılarının bir zaman çizelgesini render eder. -**Temel tasarım kararları:** +**Önemli tasarım kararları:** - Veritabanı yok - tüm kalıcı durum düz dosyalardadır (`~/.failproofai/`, `~/.claude/projects/`). -- Mutasyonlar için Server Actions - CRUD işlemleri için REST API gerekmez. -- Okuma sayfaları için React Server Components - daha hızlı ilk yüklemeler, veri getirme için istemci paketi yok. -- İstemci bileşenleri yalnızca etkileşim gerekli olduğunda (politika açma/kapatma, aktivite arama, günlük görüntüleyicisi). +- Mutasyonlar için Server Actions - CRUD işlemleri için REST API'ye gerek yok. +- Okuma sayfaları için React Server Components - daha hızlı ilk yükleme, veri getirme için istemci bundle'ı yok. +- İstemci bileşenleri yalnızca etkileşimin gerekli olduğu yerlerde (policy toggle'ları, aktivite araması, log viewer'ı). --- @@ -304,29 +305,29 @@ app/ ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI yönlendirici (hook / dashboard / install / vb.) +│ └── failproofai.mjs # CLI router (hook / dashboard / install / etc.) ├── src/hooks/ -│ ├── handler.ts # Hook olayı ardışık düzeni -│ ├── builtin-policies.ts # 39 politika tanımı -│ ├── policy-evaluator.ts # Politika yürütme motoru -│ ├── policy-registry.ts # Politika kaydı ve arama -│ ├── policy-types.ts # TypeScript arayüzleri -│ ├── hooks-config.ts # Çok kaplam yapılandırması yükleme -│ ├── custom-hooks-registry.ts # globalThis tabanlı kanca kayıt defteri -│ ├── custom-hooks-loader.ts # Kullanıcı JS kancaları için ESM yükleyici -│ ├── manager.ts # kur / kaldır / listele işlemleri -│ ├── install-prompt.ts # Etkileşimli politika seçim istemi -│ ├── hook-logger.ts # hook.log dosyasına günlüğe kaydet -│ ├── hook-activity-store.ts # Aktiviteyi hook-activity/ dosyasına kaydet -│ └── llm-client.ts # LLM API istemcisi (yapay zeka destekli politikalar için) -├── app/ # Next.js dashboard (sayfalar + sunucu eylemleri) -├── lib/ # Paylaşılan yardımcı programlar -│ ├── projects.ts # Dosya sisteminden Claude projelerini numaralandır -│ ├── log-entries.ts # Claude transkript JSONL biçimini ayrıştır -│ ├── paths.ts # Sistem yollarını çöz +│ ├── handler.ts # Hook event pipeline +│ ├── builtin-policies.ts # 39 policy definitions +│ ├── policy-evaluator.ts # Policy execution engine +│ ├── policy-registry.ts # Policy registration and lookup +│ ├── policy-types.ts # TypeScript interfaces +│ ├── hooks-config.ts # Multi-scope config loading +│ ├── custom-hooks-registry.ts # globalThis-backed hook registry +│ ├── custom-hooks-loader.ts # ESM loader for user JS hooks +│ ├── manager.ts # install / remove / list operations +│ ├── install-prompt.ts # Interactive policy selection prompt +│ ├── hook-logger.ts # Logging to hook.log +│ ├── hook-activity-store.ts # Persist activity to hook-activity/ +│ └── llm-client.ts # LLM API client (for AI-powered policies) +├── app/ # Next.js dashboard (pages + server actions) +├── lib/ # Shared utilities +│ ├── projects.ts # Enumerate Claude projects from filesystem +│ ├── log-entries.ts # Parse Claude transcript JSONL format +│ ├── paths.ts # Resolve system paths │ └── ... -├── components/ # Paylaşılan React UI bileşenleri -├── contexts/ # React bağlam sağlayıcıları (tema, otomatik yenileme, telemetri) -├── examples/ # Örnek özel kanca dosyaları -└── __tests__/ # Birim ve E2E testleri +├── components/ # Shared React UI components +├── contexts/ # React context providers (theme, auto-refresh, telemetry) +├── examples/ # Example custom hook files +└── __tests__/ # Unit and E2E tests ``` \ No newline at end of file diff --git a/docs/tr/built-in-policies.mdx b/docs/tr/built-in-policies.mdx index e49645ad..a02927ad 100644 --- a/docs/tr/built-in-policies.mdx +++ b/docs/tr/built-in-policies.mdx @@ -1,10 +1,10 @@ --- title: Yerleşik İlkeler -description: "Yaygın aracı hata modlarını yakalayan 39 yerleşik ilke" +description: "Yaygın ajan başarısızlık modlarını yakalan 39 yerleşik ilke" icon: shield --- -failproofai, yaygın aracı hata modlarını yakalayan 39 yerleşik ilke ile birlikte gelir. Her ilke belirli bir hook olay türü ve araç adı üzerinde tetiklenir. On dokuz ilke, kodu yazmadan davranışını ayarlamanıza izin veren parametreleri kabul eder. Beş iş akışı ilkesi, Claude'un durması öncesinde bir commit → push → PR → CI ardışık düzenini zorlar. +failproofai, yaygın ajan başarısızlık modlarını yakalayan 39 yerleşik ilke ile birlikte gelir. Her ilke belirli bir kanca olay türü ve araç adında etkinleşir. On dokuz ilke, davranışlarını kod yazılmadan ayarlamanıza olanak veren parametreleri kabul eder. Beş iş akışı ilkesi, Claude durduğunda bir commit → push → PR → CI ardışık düzenini uygular. --- @@ -12,11 +12,11 @@ failproofai, yaygın aracı hata modlarını yakalayan 39 yerleşik ilke ile bir İlkeler kategorilere ayrılır: -| Kategori | İlkeler | Hook türü | +| Kategori | İlkeler | Kanca türü | |----------|---------|-----------| | [Tehlikeli komutlar](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | | [Altyapı komutları](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Sırlar (temizleyiciler)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Sırlar (sanitizers)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [Ortam](#environment) | block-env-files, protect-env-vars | PreToolUse | | [Dosya erişimi](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | @@ -25,15 +25,15 @@ failproofai, yaygın aracı hata modlarını yakalayan 39 yerleşik ilke ile bir | [Paket yöneticileri](#package-managers) | prefer-package-manager | PreToolUse | | [İş akışı](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — aracının devam etmesini engelle. -- **`warn-`** — aracıya kendini düzeltebilmesi için ek bağlam sağla. -- **`sanitize-`** — aracı görmeden önce araç çıktısından hassas verileri temizle. +- **`block-`** — ajanın devam etmesini engelleyin. +- **`warn-`** — ajanın kendi kendini düzeltebilmesi için ek bağlam verin. +- **`sanitize-`** — ajan görmeden önce hassas verileri araç çıktısından temizleyin. ### Ad Alanları -Her ilke bir `/` yuvasında bulunur. Yerleşik ilkeler **`failproofai/`** ad alanına aittir — örneğin, `failproofai/sanitize-jwt`. Ad alanı, benzer kısa adlara sahip özel veya üçüncü taraf ilkeler yüklerken çakışmaları önler. +Her ilke bir `/` yuvasında yer alır. Yerleşik ilkeler **`failproofai/`** ad alanına aittir — örneğin, `failproofai/sanitize-jwt`. Ad alanı, benzer kısa adlara sahip özel veya üçüncü taraf ilkeler yüklediğinizde çakışmaları önler. -Yapılandırmanızda, yerleşik bir ilkeye kısa adı veya nitelenmiş adı ile başvurabilirsiniz; her iki form aynı ilkeyi çözer: +Yapılandırmanızda yerleşik bir ilkeye kısa adıyla veya nitelikli adıyla başvurabilirsiniz; her iki form aynı ilkeyi çözer: ```json { @@ -44,39 +44,39 @@ Yapılandırmanızda, yerleşik bir ilkeye kısa adı veya nitelenmiş adı ile } ``` -Bir adda `/` yoksa, failproofai bunu varsayılan `failproofai` ad alanına ait olarak değerlendirir. Zaten `/` içeren adlar (ör. `myorg/foo`, `custom/my-hook`) olduğu gibi kalır. -- **`require-`** — koşullar karşılanana kadar Stop olayını engelle. +Bir ad `/` içermiyorsa, failproofai bunu varsayılan ad alanı `failproofai`'e ait olarak değerlendirir. Zaten `/` içeren adlar (ör. `myorg/foo`, `custom/my-hook`) olduğu gibi tutulur. +- **`require-`** — koşullar yerine getirilene kadar Stop olayını engelleyin. --- -Her ilke, `policyParams` içinde isteğe bağlı bir `hint` alanını destekler. İpucu, Claude'un gördüğü deny veya instruct mesajına eklenir ve ilke kodunu değiştirmeden eyleme geçirilebilir rehberlik sağlar. Yerleşik, özel ve kural ilkeleriyle çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın. +Her ilke `policyParams` içinde isteğe bağlı bir `hint` alanını destekler. İpucu, Claude'un gördüğü reddet veya talimat mesajına eklenir ve ilke kodunu değiştirmeden işlem önerileri sunar. Yerleşik, özel ve kural ilkeleriyle çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın. --- ## Tehlikeli komutlar -Aracıları geri almması zor veya konak sistemi hasara uğratabilecek işlemleri çalıştırmaktan koruyun. +Ajanların geri almaktan zor olan veya ana sistem hasarına neden olabilecek işlemleri çalıştırmasını önleyin. ### `block-sudo` **Olay:** PreToolUse (Bash) -**Varsayılan:** Tüm `sudo` veya `doas` komutlarını reddeder. +**Varsayılan:** Herhangi bir `sudo` veya `doas` komutunu reddeder. -**Komut konumunda** bir yükseltme ikili dosyasını çalıştıran komutu engeller. Eşleştirme metinsel değil, yapısal: komut, bir kabuğun böleceği şekilde bölümlere ayrılır, ön atamalar (`FOO=bar`), yönlendirmeler ve çalıştırıcılar ile bayraklarları (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) kaldırılır ve sonuçlanan ikili dosya **basename** ile karşılaştırılır. Yani `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` ve `bash -c "sudo …"` hepsi reddedilir ve `doas` aynı yetenek için farklı bir ad olarak değerlendirilir. +**Komut konumunda** bir yükseltme ikilisini çalıştıran komutu engeller. Eşleştirme metin temelli değil yapısal olur: komut bir shell'in yapacağı şekilde bölümlere ayrılır, ön ek atamaları (`FOO=bar`), yönlendirmeler ve çalışan bayraklarıyla birlikte (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) kaldırılır ve sonuçtaki ikili **basename** ile karşılaştırılır. Yani `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` ve `bash -c "sudo …"` tümü reddedilir ve `doas` da aynı yetenek farklı bir ad altında olarak değerlendirilir. -Komut konumuna bağlı olduğu için, sözcüğün herhangi bir yerde görünmesinden ziyade bu durumda tetiklenmez — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"` veya kelimeyi içeren bir `grep` alternatifi normalde çalışır. +Komut konumunda sabitlendiği için metinde herhangi bir yerde görüldüğü zaman tetiklenmez — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"` veya sözcüğü içeren bir `grep` alternatifi normalde çalışır. -Bu açık deneyi durduruyor; sınıfını kapatmıyor. Rasgele kabuk çalıştırabilen bir aracı, yine de yükseltmeye dolaylı yollardan ulaşabilir — bir değişken aracılığıyla (`S=sudo; $S …`), base64 kod çözülmüş bir boru veya diskteki bir sarmalayıcı betik — çünkü tek bir komut dizgelerinin incelenmesi bunu takip edemez. Bunu hatalara ve tesadüfi yükseltmeye karşı bir koruma olarak değerlendirin, kararlı bir aracıya karşı güvenlik sınırı değil. Gerçek bir sınır kabuğun altında uygulanmalıdır. +Bu bariz denemekten durur; sınıfı kapamaz. Rastgele shell çalıştırabilen bir ajan, yükseltmeye dolaylı olarak ulaşabilir — bir değişken (`S=sudo; $S …`), base64 kod çözülmüş bir boru veya diskteki sarmalayıcı script aracılığıyla — çünkü tek bir komut dizesinin incelenmesi bunları takip edemez. Bunu hataları ve tesadüfi yükseltmeye karşı bir koruma olarak değerlendirin, kararlı bir ajana karşı güvenlik sınırı olarak değil. Gerçek sınır kabuğun altında uygulanmalıdır. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `allowPatterns` | `string[]` | `[]` | İzin verilen tam komut önekleri. Her giriş, ayrıştırılmış argv jetonlarına karşı eşleştirilir. | +|-------|-----|-----------|----------| +| `allowPatterns` | `string[]` | `[]` | İzin verilen tam komut önekleri. Her giriş ayrıştırılan argv belirteçlerine karşı eşleştirilir. | **Örnek:** @@ -90,10 +90,10 @@ Bu açık deneyi durduruyor; sınıfını kapatmıyor. Rasgele kabuk çalıştı } ``` -Bu yapılandırmayla, `sudo systemctl status nginx` izin verilir, ancak `sudo rm /etc/hosts` reddedilir. +Bu yapılandırmayla `sudo systemctl status nginx` izin verilir ama `sudo rm /etc/hosts` reddedilir. -Desenler, ham komut dizgesi değil, ayrıştırılmış jetontara karşı eşleştirilir. Bu, eklenen kabuk operatörleri aracılığıyla baypası önler (ör. `sudo systemctl status x; rm -rf /`, `sudo systemctl status *` ile eşleşmez). +Desenlerin ham komut dizesine değil, ayrıştırılan belirteçlere karşı eşleştirilmesi sağlanır. Bu, eklenen shell operatörleri aracılığıyla atlama girişimlerini önler (ör. `sudo systemctl status x; rm -rf /` `sudo systemctl status *` ile eşleşmez). --- @@ -101,13 +101,13 @@ Desenler, ham komut dizgesi değil, ayrıştırılmış jetontara karşı eşle ### `block-rm-rf` **Olay:** PreToolUse (Bash) -**Varsayılan:** `rm -rf`, `rm -fr` ve benzer yinelemeli silme formlarını reddeder. +**Varsayılan:** `rm -rf`, `rm -fr` ve benzeri özyinelemeli silme biçimlerini reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `allowPaths` | `string[]` | `[]` | Yinelemeli olarak silinmesi güvenli olan yollar (ör. `/tmp`). | +|-------|-----|-----------|----------| +| `allowPaths` | `string[]` | `[]` | Özyinelemeli olarak silinmesi güvenli olan yollar (ör. `/tmp`). | **Örnek:** @@ -126,49 +126,49 @@ Desenler, ham komut dizgesi değil, ayrıştırılmış jetontara karşı eşle ### `block-curl-pipe-sh` **Olay:** PreToolUse (Bash) -**Varsayılan:** `curl | bash`, `curl | sh`, `wget | bash` ve benzer desenleri reddeder. +**Varsayılan:** `curl | bash`, `curl | sh`, `wget | bash` ve benzeri desenleri reddeder. -Parametresi yoktur. +Parametresi yok. --- ### `block-failproofai-commands` **Olay:** PreToolUse (Bash) -**Varsayılan:** failproofai'ı kendisini kaldıracak veya devre dışı bırakacak komutları reddeder (ör. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Varsayılan:** failproofai'in kendisini kaldırıp devre dışı bırakacak komutları reddeder (ör. `npm uninstall failproofai`, `failproofai policies --uninstall`). -Parametresi yoktur. +Parametresi yok. --- ### `block-self-pause` **Olay:** PreToolUse (Bash) -**Varsayılan:** `failproofai config --pause` komutunu reddeder ve bu komut bir oturumu kısıtlamayı askıya alır. Duraklatma bir insan kararıdır — bunu çalıştırabilen bir aracı tek bir komutla diğer tüm ilkeleri kapatabilir. +**Varsayılan:** `failproofai config --pause` komutunu reddeder ve bu da bir oturum için uygulamayı askıya alır. Duraklama bir insan kararıdır — bunu çalıştırabilen bir ajan tek bir komutla her diğer ilkeyi kapatabilir. -Amaçlı olarak [`block-failproofai-commands`](#block-failproofai-commands) kadar geniş değildir ve tarafından kapsanmaz: bu ilke bir komut sınırına bağlı olduğu için `npx -y failproofai config --pause` bununla eşleşmez ve geniş olması nedeniyle aracıların `failproofai audit` çalıştırabileceği şekilde sık sık kapatılır. `--resume` ve `--status` izin verilir — ikisi de uygulamayı kaldırmaz. +[`block-failproofai-commands`](#block-failproofai-commands) olarak amaçlı olarak daha dar ve onun tarafından kapsanmaz: bu ilke komut sınırında tutturulur, bu yüzden `npx -y failproofai config --pause` eşleşmez ve geniş olduğu için sıklıkla kapatılır, ajanlar `failproofai audit` çalıştırabilir. `--resume` ve `--status` izin verilir — ikisi de uygulamayı kaldırmaz. -Bu doğrudan deneyi durduruyor, tüm sınıfı değil: bir aracı, bir takma ad veya sarmalayıcı betik aracılığıyla aynı duruma ulaşabilir. Tamamen kapatmak, duraklatmanın araç çağrısından tamamen erişilemez olmasını gerektirir. +Bu doğrudan denemekten durur, sınıfın tamamından değil: bir ajan, takma ad veya sarmalayıcı script aracılığıyla aynı duruma ulaşabilir. Bunu tamamen kapatmak, duraklamayı bir araç çağrısından tamamen erişilemez hale getirmeyi gerektirir. -Parametresi yoktur. +Parametresi yok. --- ## Altyapı komutları -Kodlama aracılarının altyapı CLIlerini çalıştırmaktan veya CI/CD ardışık düzenlerini tetiklemekten koruyun. Bu kategorideki tüm ilkeler **opt-in** (`defaultEnabled: false`) — `kubectl`, `terraform`, vb. aracısıyla meşru şekilde çağırması gereken aracılar, ilke etkinleştirilmedikçe engellenmeyecektir. Etkinleştirildiğinde, eşleşen CLIinin her bir çağırması, komut `allowPatterns` içindeki bir girişle eşleşmediği sürece reddedilir. +Kodlama ajanlarını altyapı CLI'lerini çalıştırmaktan veya CI/CD ardışık düzenini tetiklemekten durdurun. Bu kategorideki tüm ilkeler **opt-in** (`defaultEnabled: false`) — meşru bir şekilde `kubectl`, `terraform` vb. çağırması gereken ajanlar ilke etkinleştirilmedikçe kesintiye uğramaz. Etkinleştirildiğinde, eşleştirilmiş CLI'nin her çağrısı, komut `allowPatterns` içindeki bir girdiye uygun olmadıkça reddedilir. -Desen dilbilgisi [`block-sudo`](#block-sudo) ile aynıdır: jetonlar ayrıştırılmış argv'ye karşı eşleştirilir, `*` tek bir jeton için joker karttır ve bağımsız bir kabuk operatörü (`&&`, `||`, `|`, `;`) veya gömülü kabuk metakarakteri içeren herhangi bir jeton içeren komutlar, enjeksiyon baypaslarını önlemek için beyaz liste eşleştirmesinden önce reddedilir. +Desen dilbilgisi, [`block-sudo`](#block-sudo) ile aynıdır: belirteçler ayrıştırılan argv'ye karşı eşleştirilir, `*` bir belirteç için joker karttır ve herhangi bir tek başına shell operatörü (`&&`, `||`, `|`, `;`) veya ekleme shell üstverilerine sahip bir belirteç içeren komutlar, enjeksiyon atlama işlemlerini önlemek için izin listesi eşleştirmesinden önce reddedilir. ### `block-kubectl` **Olay:** PreToolUse (Bash) -**Varsayılan:** Tüm `kubectl` çağırışını reddeder. +**Varsayılan:** Herhangi bir `kubectl` çağrısını reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| +|-------|-----|-----------|----------| | `allowPatterns` | `string[]` | `[]` | İzin verilen kubectl komut önekleri. | **Örnek:** @@ -183,19 +183,19 @@ Desen dilbilgisi [`block-sudo`](#block-sudo) ile aynıdır: jetonlar ayrıştır } ``` -Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f deploy.yaml` reddedilir. +Bu yapılandırmayla `kubectl get pods` izin verilir ama `kubectl apply -f deploy.yaml` reddedilir. --- ### `block-terraform` **Olay:** PreToolUse (Bash) -**Varsayılan:** Tüm `terraform` veya `tofu` (OpenTofu) çağırışını reddeder. +**Varsayılan:** Herhangi bir `terraform` veya `tofu` (OpenTofu) çağrısını reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| +|-------|-----|-----------|----------| | `allowPatterns` | `string[]` | `[]` | İzin verilen terraform/tofu komut önekleri. | **Örnek:** @@ -215,12 +215,12 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-aws-cli` **Olay:** PreToolUse (Bash) -**Varsayılan:** Tüm `aws` CLI çağırışını reddeder. +**Varsayılan:** Herhangi bir `aws` CLI çağrısını reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| +|-------|-----|-----------|----------| | `allowPatterns` | `string[]` | `[]` | İzin verilen aws CLI komut önekleri. | **Örnek:** @@ -240,12 +240,12 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-gcloud` **Olay:** PreToolUse (Bash) -**Varsayılan:** Tüm `gcloud` (Google Cloud) CLI çağırışını reddeder. +**Varsayılan:** Herhangi bir `gcloud` (Google Cloud) CLI çağrısını reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| +|-------|-----|-----------|----------| | `allowPatterns` | `string[]` | `[]` | İzin verilen gcloud komut önekleri. | **Örnek:** @@ -265,12 +265,12 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-az-cli` **Olay:** PreToolUse (Bash) -**Varsayılan:** Tüm `az` (Azure) CLI çağırışını reddeder. +**Varsayılan:** Herhangi bir `az` (Azure) CLI çağrısını reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| +|-------|-----|-----------|----------| | `allowPatterns` | `string[]` | `[]` | İzin verilen az CLI komut önekleri. | **Örnek:** @@ -290,12 +290,12 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-helm` **Olay:** PreToolUse (Bash) -**Varsayılan:** Tüm `helm` çağırışını reddeder. +**Varsayılan:** Herhangi bir `helm` çağrısını reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| +|-------|-----|-----------|----------| | `allowPatterns` | `string[]` | `[]` | İzin verilen helm komut önekleri. | **Örnek:** @@ -315,7 +315,7 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-gh-pipeline` **Olay:** PreToolUse (Bash) -**Varsayılan:** Durumu değiştiren veya ardışık düzeni tetikleyen aşağıdaki `gh` CLI alt komutlarını reddeder: +**Varsayılan:** Durumu değiştiren veya ardışık düzeni tetikleyen şu `gh` CLI alt komutlarını reddeder: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -324,13 +324,13 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de - `gh cache delete` - `gh secret set`, `gh secret delete` -`gh pr view`, `gh pr list`, `gh run list`, `gh release view` ve `gh api repos/.../...` gibi salt okunur `gh` alt komutları **bu ilke tarafından eşleştirilmez** — iş akışı denetimleri için (failproofai'ın kendi `require-ci-green-before-stop` dahil) rutin olarak gereklidir. +`gh pr view`, `gh pr list`, `gh run list`, `gh release view` ve `gh api repos/.../...` gibi salt okunur `gh` alt komutları bu ilke tarafından eşleştirilmez — iş akışı kontrolü için rutin olarak gereklidir (failproofai'in kendi `require-ci-green-before-stop` dahil). **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `allowPatterns` | `string[]` | `[]` | Aksi takdirde reddedilecek belirli betikli çağırışlara izin vermek için. | +|-------|-----|-----------|----------| +| `allowPatterns` | `string[]` | `[]` | Aksi takdirde reddedilecek belirli korunmuş çağrılar. | **Örnek:** @@ -346,29 +346,29 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de --- -## Sırlar (temizleyiciler) +## Sırlar (sanitizers) -Aracıların kimlik bilgilerini bağlamlarına veya çıktılarına sızlamasını önleyin. Temizleyici ilkeler **PostToolUse** olaylarında tetiklenir. Claude bir Bash komutu çalıştırdığında, bir dosya okuduğunda veya herhangi bir aracı çağırdığında, bu ilkeler çıktıyı Claude'a geri dönmeden önce inceler. Bir gizli desen algılanırsa, ilke çıktının geri aktarılmasını önleyen bir deny kararı verir. +Ajanların kimlik bilgilerini bağlamlarına veya çıktısına sızmasını durdurun. Sanitizer ilkeleri **PostToolUse** olaylarında etkinleşir. Claude bir Bash komutu çalıştırdığında, bir dosya okuduğunda veya herhangi bir araçu çağırdığında, bu ilkeler Claude'a geri dönmeden önce çıktıyı inceler. Gizli bir desen algılanırsa, ilke çıktısının geri geçirilmesini engelleyen bir reddet kararı döndürür. ### `sanitize-jwt` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** JWT jetonlarını (`.` ile ayrılmış üç base64url segmenti) yeniden düzenler. +**Varsayılan:** JWT belirteçlerini gizler (`.` ile ayrılmış üç base64url segmenti). -Parametresi yoktur. +Parametresi yok. --- ### `sanitize-api-keys` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** Yaygın API anahtar biçimlerini yeniden düzenler: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT'leri (`ghp_`), AWS erişim anahtarları (`AKIA`), Stripe anahtarları (`sk_live_`, `sk_test_`) ve Google API anahtarları (`AIza`). +**Varsayılan:** Yaygın API anahtarı biçimlerini gizler: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT'leri (`ghp_`), AWS erişim anahtarları (`AKIA`), Stripe anahtarları (`sk_live_`, `sk_test_`) ve Google API anahtarları (`AIza`). **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Gizli olarak değerlendirilecek ek regex desenleri. | +|-------|-----|-----------|----------| +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Gizli olarak davranılacak ek düzenli ifade desenleri. | **Örnek:** @@ -377,8 +377,8 @@ Parametresi yoktur. "policyParams": { "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" }, - { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo iç API anahtarı" }, + { "regex": "pat_[0-9a-f]{40}", "label": "İç PAT" } ] } } @@ -390,42 +390,42 @@ Parametresi yoktur. ### `sanitize-connection-strings` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** Gömülü kimlik bilgileri içeren veritabanı bağlantı dizgelerini (ör. `postgresql://user:password@host/db`) yeniden düzenler. +**Varsayılan:** Eklenen kimlik bilgilerini içeren veritabanı bağlantı dizelerini gizler (ör. `postgresql://user:password@host/db`). -Parametresi yoktur. +Parametresi yok. --- ### `sanitize-private-key-content` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** PEM bloklarını (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, vb.) yeniden düzenler. +**Varsayılan:** PEM bloklarını gizler (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, vb.). -Parametresi yoktur. +Parametresi yok. --- ### `sanitize-bearer-tokens` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** `Authorization: Bearer ` başlıklarını, belirtecin 20 veya daha fazla karakter olduğu yerlerde yeniden düzenler. +**Varsayılan:** `Authorization: Bearer ` başlıklarını gizler ve belirteç 20 veya daha fazla karakter olur. -Parametresi yoktur. +Parametresi yok. --- ## Ortam -Hassas ortam yapılandırmasının aracılar tarafından okunması veya maruz kalması riskinden koruyun. +Hassas ortam yapılandırmasını ajanlar tarafından okunmasından veya açıklanmasından koruyun. ### `block-env-files` **Olay:** PreToolUse (Bash, Read) -**Varsayılan:** `cat .env`, `.env` dosya yolu ile Read aracı çağrıları vb. aracılığıyla `.env` dosyalarını okumayı reddeder. +**Varsayılan:** `.env` dosyalarının `cat .env` veya `.env` dosya yolu ile Read araç çağrıları aracılığıyla okunmasını reddeder. -`.envrc` veya diğer ortam adlı dosyaları engellemeyi reddeder — yalnızca tam olarak `.env` adlı dosyaları. +`.envrc` veya diğer ortam komşu dosyalarını engellenmez — yalnızca tam olarak `.env` adlı dosyalar. -Parametresi yoktur. +Parametresi yok. --- @@ -434,23 +434,23 @@ Parametresi yoktur. **Olay:** PreToolUse (Bash) **Varsayılan:** Ortam değişkenlerini yazdıran komutları reddeder: `printenv`, `env`, `echo $VAR`. -Parametresi yoktur. +Parametresi yok. --- ## Dosya erişimi -Aracıları proje sınırları içinde ve hassas dosyalardan uzakta çalışırken tutun. +Ajanları proje sınırlarında çalışır durumda tutun ve hassas dosyalardan uzak tutun. ### `block-read-outside-cwd` **Olay:** PreToolUse (Read, Bash) -**Varsayılan:** Proje kökünün dışındaki dosyaları okumayı reddeder. Sınır, `CLAUDE_PROJECT_DIR` (her oturum için Claude Code tarafından bir kez ayarlanır) ile oturumun geçerli çalışma dizinine geri dönüş olur. Proje kökünü canlı `cwd` yerine kullanmak, Claude `cd` olduktan sonra bile sınırın sabit kalmasını sağlar. +**Varsayılan:** Proje kökünün dışındaki dosyaları okumasını reddeder. Sınır `CLAUDE_PROJECT_DIR` (Claude Code tarafından oturum başına ayarlanır), bu değişken ayarlanmamışsa oturum geçerli çalışma dizinine geri döner. Canlı `cwd` yerine proje kökünü kullanmak, Claude bir alt dizine `cd` yaptıktan sonra bile sınırın sabit kalmasını sağlar. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| +|-------|-----|-----------|----------| | `allowPaths` | `string[]` | `[]` | Proje kökünün dışında olsa bile izin verilen mutlak yol önekleri. | **Örnek:** @@ -470,13 +470,13 @@ Aracıları proje sınırları içinde ve hassas dosyalardan uzakta çalışırk ### `block-secrets-write` **Olay:** PreToolUse (Write, Edit) -**Varsayılan:** Özel anahtarlar ve sertifikalar için yaygın olarak kullanılan dosyalara yazma işlemlerini reddeder: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Varsayılan:** Özel anahtarlar ve sertifikalar için yaygın olarak kullanılan dosyalara yazmayı reddeder: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `additionalPatterns` | `string[]` | `[]` | Engelleme için ek dosya adı desenleri (glob stili). | +|-------|-----|-----------|----------| +| `additionalPatterns` | `string[]` | `[]` | Engellenmesi gereken ek dosya adı desenleri (glob stili). | **Örnek:** @@ -494,7 +494,7 @@ Aracıları proje sınırları içinde ve hassas dosyalardan uzakta çalışırk ## Git -Tesadüfi itişleri, zorla itişleri ve geri almması zor dal hatalarını önleyin. +Yanlışlıkla yapılan push'ları, force-push'ları ve geri almaktan zor olan branch hatalarını önleyin. ### `block-push-master` @@ -504,8 +504,8 @@ Tesadüfi itişleri, zorla itişleri ve geri almması zor dal hatalarını önle **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Doğrudan itilemeyen dal adları. | +|-------|-----|-----------|----------| +| `protectedBranches` | `string[]` | `["main", "master"]` | Doğrudan push yapılamayan branch adları. | **Örnek:** @@ -520,7 +520,7 @@ Tesadüfi itişleri, zorla itişleri ve geri almması zor dal hatalarını önle ``` -Tüm dallara itişe izin vermek için (bu ilkeyi `enabledPolicies` öğesinden kaldırmadan etkili şekilde devre dışı bırakmak), `protectedBranches: []` ayarlayın. +Tüm branched push yapmasına izin vermek için (`enabledPolicies` içinden kaldırmadan bu ilkeyi devre dışı bırakmak), `protectedBranches: []` olarak ayarlayın. --- @@ -528,13 +528,13 @@ Tüm dallara itişe izin vermek için (bu ilkeyi `enabledPolicies` öğesinden k ### `block-work-on-main` **Olay:** PreToolUse (Bash) -**Varsayılan:** Çalışma ağacı `main` veya `master` üzerinde olduğu sürece `git commit`, `git merge`, `git rebase` ve `git cherry-pick` komutlarını reddeder. Dal oluşturma ve geçiş (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) etkilenmez. +**Varsayılan:** Çalışma ağacı `main` veya `master` üzerindeyken `git commit`, `git merge`, `git rebase` ve `git cherry-pick` komutlarını reddeder. Branch oluşturma ve değiştirme (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) etkilenmez. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Commit/merge/rebase/cherry-pick öğesinin reddedildiği dal adları. | +|-------|-----|-----------|----------| +| `protectedBranches` | `string[]` | `["main", "master"]` | Commit/merge/rebase/cherry-pick'in reddedileceği branch adları. | --- @@ -543,13 +543,13 @@ Tüm dallara itişe izin vermek için (bu ilkeyi `enabledPolicies` öğesinden k **Olay:** PreToolUse (Bash) **Varsayılan:** `git push --force` ve `git push -f` komutlarını reddeder. -İlkeye özgü parametresi yoktur. Alternatifler önerisi için çapraz kesim [`hint`](/tr/configuration#hint-cross-cutting) öğesini kullanın: +İlke'e özel parametre yok. Alternatifler önerecek şekilde çapraz kesim [`hint`](/tr/configuration#hint-cross-cutting) kullanın: ```json { "policyParams": { "block-force-push": { - "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b `) and push that instead." + "hint": "Mevcut HEAD'inizden yeni bir branch oluşturun (ör. `git checkout -b `) ve bunun yerine push yapın." } } } @@ -560,65 +560,65 @@ Tüm dallara itişe izin vermek için (bu ilkeyi `enabledPolicies` öğesinden k ### `warn-git-amend` **Olay:** PreToolUse (Bash) -**Varsayılan:** Claude'u `git commit --amend` komutu çalıştırırken dikkatle ilerlemesi için talimatlandırır. Komutu engellemeyin. +**Varsayılan:** Claude'u `git commit --amend` çalıştırırken dikkatli hareket etmesi konusunda talimatlandırır. Komutu engellenmez. -Parametresi yoktur. +Parametresi yok. --- ### `warn-git-stash-drop` **Olay:** PreToolUse (Bash) -**Varsayılan:** Claude'u `git stash drop` komutunu çalıştırmadan önce onaylaması için talimatlandırır. Komutu engellemeyin. +**Varsayılan:** Claude'u `git stash drop` çalıştırmadan önce onaylaması konusunda talimatlandırır. Komutu engellenmez. -Parametresi yoktur. +Parametresi yok. --- ### `warn-all-files-staged` **Olay:** PreToolUse (Bash) -**Varsayılan:** Claude'u `git add -A` veya `git add .` komutu çalıştırırken neyi sahnelendiğini incelemesi için talimatlandırır. Komutu engellemeyin. +**Varsayılan:** Claude'u `git add -A` veya `git add .` çalıştırdığında neyi aşamalandırdığını incelemesi konusunda talimatlandırır. Komutu engellenmez. -Parametresi yoktur. +Parametresi yok. --- ## Veritabanı -Yıkıcı SQL işlemlerini veritabanınızda yürütülmeden önce yakalayın. +Veritabanınıza karşı yürütüldüğünden önce yıkıcı SQL işlemlerini yakala. ### `warn-destructive-sql` **Olay:** PreToolUse (Bash) -**Varsayılan:** Claude'u `DROP TABLE`, `DROP DATABASE` veya `WHERE` yan tümcesi olmayan `DELETE` içeren SQL çalıştırmadan önce onaylaması için talimatlandırır. +**Varsayılan:** Claude'u `DROP TABLE`, `DROP DATABASE` veya `WHERE` yan tümcesi olmayan `DELETE` içeren SQL çalıştırmadan önce onaylaması konusunda talimatlandırır. -Parametresi yoktur. +Parametresi yok. --- ### `warn-schema-alteration` **Olay:** PreToolUse (Bash) -**Varsayılan:** Claude'u `ALTER TABLE` deyimlerini çalıştırmadan önce onaylaması için talimatlandırır. +**Varsayılan:** Claude'u `ALTER TABLE` deyimleri çalıştırmadan önce onaylaması konusunda talimatlandırır. -Parametresi yoktur. +Parametresi yok. --- ## Uyarılar -Aracılara potansiyel riski taşıyan ama yıkıcı olmayan işlemler öncesi ek bağlam sağlayın. +Ajanları potansiyel olarak riskli ama yıkıcı olmayan işlemlerden önce ekstra bağlam verin. ### `warn-large-file-write` **Olay:** PreToolUse (Write) -**Varsayılan:** Claude'u 1024 KB'dan büyük dosyalar yazmadan önce onaylaması için talimatlandırır. +**Varsayılan:** Claude'u 1024 KB'den daha büyük dosyaları yazmadan önce onaylaması konusunda talimatlandırır. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| +|-------|-----|-----------|----------| | `thresholdKb` | `number` | `1024` | Uyarı verilen dosya boyutu eşiği (kilobayt cinsinden). | **Örnek:** @@ -634,7 +634,7 @@ Aracılara potansiyel riski taşıyan ama yıkıcı olmayan işlemler öncesi ek ``` -Hook işleyici yüklerde 1 MB stdin sınırı zorlar. Bu ilkeyi küçük içerikle test etmek için, `thresholdKb` öğesini 1024'ün çok altında bir değere ayarlayın. +Kanca işleyicisi yüklemi üzerinde 1 MB stdin sınırını uygular. Bu ilkeyi küçük içerikle test etmek için `thresholdKb` 1024'ün çok altında bir değere ayarlayın. --- @@ -642,47 +642,47 @@ Hook işleyici yüklerde 1 MB stdin sınırı zorlar. Bu ilkeyi küçük içerik ### `warn-package-publish` **Olay:** PreToolUse (Bash) -**Varsayılan:** Claude'u `npm publish` komutu çalıştırmadan önce onaylaması için talimatlandırır. +**Varsayılan:** Claude'u `npm publish` çalıştırmadan önce onaylaması konusunda talimatlandırır. -Parametresi yoktur. +Parametresi yok. --- ### `warn-background-process` **Olay:** PreToolUse (Bash) -**Varsayılan:** Claude'u `nohup`, `&`, `disown` veya `screen` aracılığıyla arka plan işlemleri başlatırken dikkatli olması için talimatlandırır. +**Varsayılan:** Claude'u `nohup`, `&`, `disown` veya `screen` aracılığıyla arka plan süreçleri başlatırken dikkatli olması konusunda talimatlandırır. -Parametresi yoktur. +Parametresi yok. --- ### `warn-global-package-install` **Olay:** PreToolUse (Bash) -**Varsayılan:** Claude'u `npm install -g`, `yarn global add` veya sanal ortam olmadan `pip install` komutu çalıştırmadan önce onaylaması için talimatlandırır. +**Varsayılan:** Claude'u `npm install -g`, `yarn global add` veya sanal ortam olmadan `pip install` çalıştırmadan önce onaylaması konusunda talimatlandırır. -Parametresi yoktur. +Parametresi yok. --- ## Paket yöneticileri -Aracının hangi paket yöneticilerine izin verildiğini zorlayın. +Ajanın kullanmasına izin verilen paket yöneticilerini uygulayın. ### `prefer-package-manager` **Olay:** PreToolUse (Bash) -**Varsayılan:** Devre dışı. Etkinleştirildiğinde, `allowed` listesinde olmayan paket yöneticisi komutunu engeller ve Claude'u komutu izin verilen bir yöneticiyi kullanarak yeniden yazması için talimatlandırır. +**Varsayılan:** Devre dışı. Etkinleştirildiğinde, `allowed` listesinde olmayan herhangi bir paket yöneticisi komutunu engeller ve Claude'a komutu izin verilen bir yönetici kullanarak yeniden yazması talimatını verir. Algılar: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parametre | Tür | Varsayılan | Açıklama | -|-----------|-----|-----------|---------| -| `allowed` | string[] | `[]` | İzin verilen paket yöneticisi adları. Bu listede olmayan algılanan yönetici engellenir. Boş olduğunda, ilke hiçbir şey yapmaz. | -| `blocked` | string[] | `[]` | Yerleşik listesi ötesinde engelleme yapılacak ek yönetici adları (ör. `['pdm', 'pipx']`). | +|-----------|-----|-----------|----------| +| `allowed` | string[] | `[]` | İzin verilen paket yöneticisi adları. Bu listede olmayan algılanan yöneticiler engellenir. Boş olduğunda ilke bir no-op'tir. | +| `blocked` | string[] | `[]` | Yerleşik listeye ek olarak engellenecek yönetici adları (ör. `['pdm', 'pipx']`). | -Yerleşik engel listesi şunları kapsar: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Bu listede olmayan yöneticileri eklemek için `blocked` öğesini kullanın. +Yerleşik engel listesi şunları kapsar: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Bu listede olmayan yöneticileri eklemek için `blocked` kullanın. **Örnek yapılandırma:** @@ -698,73 +698,73 @@ Yerleşik engel listesi şunları kapsar: pip, pip3, npm, npx, yarn, pnpm, pnpx, } ``` -Bu yapılandırmayla, `pip install flask` ve `pdm install flask` ikisi de reddedilir ve Claude'a `uv` veya `bun` kullanmasını söyleyen bir mesajla birlikte gelir. `uv pip install flask` gibi komutlar, `uv` izin listesinde olduğu için ve ilk olarak denetlendiği için izin verilir. +Bu yapılandırmayla `pip install flask` ve `pdm install flask` her ikisi de reddedilir ve Claude'a bunun yerine `uv` veya `bun` kullanması söylenir. `uv pip install flask` gibi komutlar izin verilir çünkü `uv` izin listesindedir ve önce kontrol edilir. --- ## AI davranışı -Aracıları tıkanıp kalırken veya beklenmedik şekilde davranırken algılayın. +Ajanlar sıkışıp kaldığında veya beklenmedik şekilde davrandığında algıla. ### `warn-repeated-tool-calls` **Olay:** PreToolUse (tüm araçlar) -**Varsayılan:** Claude'u aynı araç 3+ kez aynı parametrelerle çağrıldığında — aracının bir döngüde takılı kalmasının yaygın bir işareti — yeniden düşünmesi için talimatlandırır. +**Varsayılan:** Claude'u aynı araçu özdeş parametrelerle 3+ kez çağırırken düşünmesi konusunda talimatlandırır — bu yaygın olarak ajanın bir döngüde takılı olduğunun işaretidir. -Parametresi yoktur. +Parametresi yok. --- -## İş Akışı +## İş akışı -Disiplinli oturum sonu iş akışı uygulayın. Bu ilkeler **Stop** olayında tetiklenir ve her koşul karşılanana kadar aracının durmasını engeller. Doğal bir bağımlılık zincirini izlerler: commit → push → PR → CI. Bir ilke reddederse, zincirdeki sonraki ilkeler atlanır (deny kısa devredir). +Disiplinli bir oturum sonu iş akışını uygulayın. Bu ilkeler **Stop** olayında etkinleşir ve her koşul yerine getirilene kadar ajanı durdurmasını engeller. Doğal bir bağımlılık zincirini takip ederler: commit → push → PR → CI. Bir ilke reddederse, zincirdeki sonraki ilkeler atlanır (reddet kısaltır). -Tüm iş akışı ilkeleri **fail-open**: gerekli araç kullanılamaz durumda ise (ör. `gh` yüklenmedi, git uzaklaştırması yok), ilke kontrol neden atlandığını açıklayan bilgi mesajıyla izin verir. +Tüm iş akışı ilkeleri **fail-open** (açık başarısız): gerekli araç kullanılamıyorsa (`gh` yüklü değil, git uzak yok), ilke bir bilgilendirme mesajı vererek izin verir ve kontrolün atlanma nedenini açıklar. ### CLI başına Stop semantiği -Stop uygulaması, desteklenen altı CLI'nin her biri farklı bir aracı tamamlandı hook sözleşmesini ortaya koymaktadır. **Sonuç** aynıdır — aracı iş akışı kapısı başarısız iken durabilir — ancak **mekaniğii** farklıdır. Aşağıdaki tablo özeti; Bir `require-*-before-stop` ilkesini etkinleştirmeden anlamaya değer Pi'nin yalnızca bir kullanıcı taraflı garip şekli vardır. +Stop uygulaması, desteklenen altı CLI'de biraz farklı görünür çünkü her biri farklı bir "ajan bitti" kanca sözleşmesi sunar. **Sonuç** aynıdır — ajan iş akışı kapısı başarısızken durdurmayı kurtaramaz — ama **mekanik** farklıdır. Aşağıdaki tablo bir özeti sağlar; yalnızca Pi, `require-*-before-stop` ilkesini etkinleştirmeden önce anlaşılması gereken kullanıcı tarafından görülebilir bir tuhaflığa sahiptir. -| CLI | Kapı ne zaman tetiklenir | Ne görüyorsunuz | +| CLI | Kapı ne zaman etkinleşir | Ne görsünüz | |---|---|---| -| Claude Code | Aynı aracı döngüsü, hemen | Claude çalışmaya devam eder — sorunu düzeltir, ardından tamamlamayı yeniden dener. Size görünür kesinti yok. | -| Codex | Aynı aracı döngüsü, hemen | Claude ile aynı. | -| GitHub Copilot CLI | Aynı aracı döngüsü, hemen | Copilot'un `{decision:"block", reason}` yeniden deneme kanalı kullanan Claude ile aynı (Copilot CLI 1.0.41 karşısında deneysel olarak doğrulanmış). | -| Cursor Agent | Aynı aracı döngüsü, hemen | Cursor'un `{followup_message}` kanalını kullanan Claude ile aynı (varsayılan `loop_limit` 5 yeniden denemeyle sınırlanmış). | -| OpenCode | Aynı aracı döngüsü, hemen | OpenCode'un `client.session.prompt(...)` SDK çağrısını `hookSpecificOutput.additionalContext` aracılığıyla yönlendiren Claude ile aynı. | -| **Pi (pi-coding-agent)** | **Sonraki kullanıcı sırası** | **Pi görünür şekilde durur** — aracı döngüsü çıkar ve istem döner. Kapı sonra tetiklenir siz bir istemi gönder: failproofai istemci öncesinde `MANDATORY ACTION REQUIRED` yönergesi hazırlanır bu turun sistem istemine, LLM'ye iş akışı adımı (commit, push, vb.) tamamlamayı önceden ve ardından istediğinizi yapmayı talimatlandırır. | +| Claude Code | Aynı ajan döngüsü, hemen | Claude çalışmaya devam eder — sorunu düzeltir, sonra bitirmeyi tekrar dener. Size görünür kesinti yok. | +| Codex | Aynı ajan döngüsü, hemen | Claude ile aynı. | +| GitHub Copilot CLI | Aynı ajan döngüsü, hemen | Claude ile aynı (Copilot'un `{decision:"block", reason}` yeniden deneme kanalını kullanır — Copilot CLI 1.0.41'e karşı ampirik olarak doğrulanmıştır). | +| Cursor Agent | Aynı ajan döngüsü, hemen | Claude ile aynı (Cursor'un `{followup_message}` kanalını kullanır — `loop_limit` ile sınırlanır, varsayılan 5 yeniden deneme). | +| OpenCode | Aynı ajan döngüsü, hemen | Claude ile aynı (OpenCode'un `client.session.prompt(...)` SDK çağrısını `hookSpecificOutput.additionalContext` aracılığıyla kullanır). | +| **Pi (pi-coding-agent)** | **Sonraki kullanıcı sırası** | **Pi görünür şekilde durur** — kapı etkinleştirildiğinde ajan döngüsü çıkar ve soruya dönürsünüz. Kapı sonra tetiklenir sonraki kez bir istem gönderdikçe: failproofai o dönüş sistem isteminin başına bir `MANDATORY ACTION REQUIRED` yönergesi ekler ve LLM'ye iş akışı adımını (commit, push, vb.) tamamlaması ve ancak o zaman istediğiniz şeyi yapması talimatını verir. | -**Pi sınırlaması.** Pi'nin `AgentEndEvent` (Claude'ın `Stop` hook'u eşdeğeri), Result türü yoktur — tetiklendiği zaman, Pi'nin aracı döngüsü zaten çıkmıştır. Pi, Claude / Copilot / Cursor / OpenCode'un yapabildiği şekilde aynı döngüyü yeniden denemesi için zorlanamaz. failproofai kapıyı Pi'nin `before_agent_start` olayına kaydırır (sonraki kullanıcı isteminden sonra tetiklenir) iş akışı denetimi hala başarılı olur, sadece mevcut yerine sonraki tur üzerinde. +**Pi sınırlaması.** Pi'nin `AgentEndEvent` (Claude'un `Stop` kancanın upstream eşdeğeri) bir Result türüne sahip değildir — etkinleşir zamana gelindiğinde, Pi'nin ajan döngüsü zaten çıkmıştır. Pi'nin Claude / Copilot / Cursor / OpenCode'un yapabildiği şekilde aynı döngüyü yeniden denemesi zorlananamaz. failproofai kapıyı Pi'nin `before_agent_start` olayına kaydırır (sonraki kullanıcı isteminden sonra etkinleşir) böylece iş akışı kontrolü yine uygulanır, yalnızca mevcut dönüş yerine sonraki turda. -**Uygulamada ne anlama gelir:** +**Pratikte bu ne anlama gelir:** -- Pi durulduktan sonra, deny nedeni Pi oturum kimliği tarafından anahtarlı bellekte yakalanır. Sizin gönderdiğiniz çok sonraki ilk istem aynı Pi işleminde bunu boşaltır: LLM sistem isteminin en üstündeki `MANDATORY ACTION REQUIRED` yönergesini görür, commit (veya push / PR açar / CI'ı bekler) ve sadece ardından istediğinize devam eder. Yakalanan deny nedeni bir defalık — boşaltıldıktan sonra, kapı açıktır. -- Kapı Pi'nin işlem ömrü ile sınırlandırılır. Pi'yi `Ctrl+C` yaparsanız veya turlararasında çıkarsanız, bellekteki giriş işlemle birlikte bırakılır ve kapı kaçırılır. Claude, Copilot, Cursor ve OpenCode aynı bağa sahiptir (aracıyı öldür ve kapıyı kaçır) — Pi bunu daha görünür hale getirir çünkü aracı kapı tetiklenmeden önce görünür şekilde çıkar. -- Beklemede olan bir deny, herhangi bir nedenle `session_shutdown` öğesinde da temizlenir (`new` / `resume` / `fork` / `quit`), bu nedenle önceki bir oturumdan eski bir kapı aynı Pi işleminde başlatılan yeni bir oturuma sızamaz. +- Pi durduğunda, reddet nedeni bellek içinde Pi oturum kimliğiyle anahtarlanır. Aynı Pi sürecinde göndereceğiniz çok sonraki istem bunu boşaltır: LLM sistem isteminin başında `MANDATORY ACTION REQUIRED` yönergesini görür, commit eder (veya push / PR açar / CI'ı bekler) ve ancak o zaman isteğinizle devam eder. Tutulan reddet nedeni tek seferlik — bir kez boşaltıldığında kapı temizdir. +- Kapı Pi'nin süreç ömrü ile sınırlanır. Turlar arasında Pi'yi `Ctrl+C` yaparsanız veya çıkarsanız, bellek içi giriş işlem ile birlikte düşer ve kapı atlanır. Claude, Copilot, Cursor ve OpenCode aynı sınırı içerir (ajandan çıkın ve kapı atlanır) — Pi bunu yalnızca daha görünür hale getirir çünkü ajan kapı etkinleşmeden önce görünür şekilde çıkar. +- Bekleyen bir reddet de herhangi bir nedenle (`new` / `resume` / `fork` / `quit`) `session_shutdown` üzerinde temizlenir, yani önceki oturumdan eski bir kapı aynı Pi işleminde başlatılan yeni oturuma sızamaz. -Claude stili aynı döngü yeniden denemesi gerekiyorsa, `Stop` ilkelerinizi desteklenen diğer beş CLI'nin herhangi birinin altında çalıştırın. Bunu kapatmamıza izin verecek bir gelecek Result türü için Pi'nin yukarısını izliyoruz. +Claude stili aynı döngü yeniden denemesine ihtiyacınız varsa, `Stop` ilkelerinizi diğer beş desteklenen CLI'den herhangi birinin altında çalıştırın. Bizi upstream Pi'de izliyoruz — `AgentEndEvent` üzerinde bunu kapatmamıza olanak verecek bir Result türü gelecek için. ### `require-commit-before-stop` **Olay:** Stop -**Varsayılan:** Yapılmamış değişiklikler (değiştirilmiş, hazırlanmış veya izlenmeyen dosyalar) olduğunda durmasını engeller. Çalışma dizini temiz olduğunda bilgi mesajını döndürür. +**Varsayılan:** Yayın olmayan değişiklikler (değiştirilen, aşamalı veya izlenmeyen dosyalar) olduğunda durdurmasını reddeder. Çalışma dizini temiz olduğunda bir bilgisel mesaj döndürür. -Parametresi yoktur. +Parametresi yok. --- ### `require-push-before-stop` **Olay:** Stop -**Varsayılan:** İtilmemiş commit olduğunda veya mevcut dal uzaktan izleme dalı olmadığında durmasını engeller. Gerekirse izleme dalı oluşturmak için `git push -u` önerir. Yapılandırılan uzak yoksa açık başarısız olur. +**Varsayılan:** Push edilmemiş işlemler olduğunda veya mevcut branch uzaktan takip eden bir brancha sahip olmadığında durdurmasını reddeder. Gerekirse izleme branşını oluşturmak için `git push -u` önerir. Uzak konfigüre edilmemişse açık başarısız olur. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `remote` | `string` | `"origin"` | İtilecek uzak ad. | +|-------|-----|-----------|----------| +| `remote` | `string` | `"origin"` | Push yapılacak uzak adı. | **Örnek:** @@ -783,13 +783,13 @@ Parametresi yoktur. ### `require-pr-before-stop` **Olay:** Stop -**Varsayılan:** Mevcut dal için çekme isteği olmadığında veya mevcut PR birleştirilmeden kapatıldığında durmasını engeller. Claude'u `gh pr create` ile PR oluşturmayı talimatlandırır. PR **birleştirildiğinde**, ilke izin verir (çalışma sevk edildi) ve mesaj daldan geçmeyi önerir (`git checkout main && git pull`). +**Varsayılan:** Mevcut branch için bir pull request olmadığında veya mevcut PR birleştirilmeden kapatıldığında durdurmasını reddeder. Claude'u `gh pr create` ile bir PR oluşturması talimatlandırır. PR **birleştirildiğinde**, ilke izin verir (çalışma yayımlanmıştır) ve mesaj branştan çıkış önerir (`git checkout main && git pull`). -Parametresi yoktur. +Parametresi yok. -Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve kimlik doğrulamasından geçmiş olması gerekir. -Çekme istekleri için okuma erişimi olan `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` komutunu çalıştırın. `gh` yüklü değilse veya kimlik doğrulaması yapılmamışsa, ilke açık başarısız olur ve nedenini Claude'a raporta eder. +Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve doğrulanmış olmasını gerektirir. +Pull request'lere okuma erişimi için `repo` kapsamı olan kişisel erişim belirteci ile `gh auth login` çalıştırın. `gh` yüklü veya doğrulanmadıysa, ilke açık başarısız olur ve nedenini Claude'a bildirir. --- @@ -797,21 +797,21 @@ Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve kimlik doğrulam ### `require-no-conflicts-before-stop` **Olay:** Stop -**Varsayılan:** Mevcut dal temiz şekilde taban dalına birleştirilemezse durmasını engeller. İlke ilk olarak dal için GitHub'da `OPEN` çekme isteği olup olmadığını doğrular — olmadığında, birleştirilecek hedef olmadığından tüm ilke kısa devredir ve izin verir. Bir `OPEN` PR doğrulandıktan sonra, iki bağımsız probe çalışır: +**Varsayılan:** Mevcut branch taban branch'a temiz şekilde birleşemediğinde durdurmasını reddeder. İlke önce branch için GitHub'da bir `OPEN` PR olduğunu teyit eder — biri yoksa, birleştirme hedefi olmadığından ilke kısa devreler ve izin verir. Bir `OPEN` PR onaylandığında, iki bağımsız araştırma çalışır: -1. **Yerel** — `git merge-tree --write-tree --name-only origin/ HEAD`. Çatışma durumunda, deny mesajı, Claude'un tam olarak neleri çözeceğini bilmesi için çatışmalı dosyaları adlandırır. -2. **GitHub** — ön denetimde zaten alınmış `gh pr view --json mergeable,state` sonucunu yeniden kullanır. Yerel `origin/` eski olacağını çatışmaları yakalar (örn. birisi son getirmeden sonra `main` üzerinde çatışmalı PR iniş). `CONFLICTING` sonuç engeller. `UNKNOWN` sonuç da engeller ve Claude'u ~10 saniye beklemesini ve durlamaya çalışmadan önce yeniden denetlemesini talimatlandırır — bu yanlış negatifleri engeller GitHub yeniden hesaplarken. +1. **Yerel** — `git merge-tree --write-tree --name-only origin/ HEAD`. Çakışmada, reddet mesajı çakışan dosyaları adlandırır böylece Claude tam olarak neyi çözeceğini bilir. +2. **GitHub** — ön kontrolde zaten getirilen `gh pr view --json mergeable,state` sonucunu yeniden kullanır. Eski bir yerel `origin/` kaybedecek çakışmaları yakalar (ör. biri son getirmeden sonra `main` üzerine çakışan bir PR yayımladı). Çakışmada bir `CONFLICTING` sonucu reddeder. Bir `UNKNOWN` sonucu da reddeder ve Claude'a tekrar kontrol etmesini beklemesi ve durdurmayı yeniden deneme yapmadan ~10 saniye beklemesi talimatını verir — bu yanlış negatifleri engel GitHub yeniden hesaplarken. -Tamamen atlanır (izin verir) ne zaman: `gh` yüklü değilse, dal için PR yoksa, PR'nin durumu `OPEN` değilse (örn. `MERGED`, `CLOSED`), veya `gh pr view` ayrıştırılamazsa. Ayrıca `origin/` yerel olarak eksikse veya tabandan hiç commit olmadığında açık başarısız olur — Katman 1 geçişleri birleştirilebilirliği kontrol etmeden önce izin vermek için hala cachelenen PR'yi danışırlar. +Atlanır (izin verir): `gh` yüklü değil, branch için PR yok, PR'ın durumu `OPEN` değil (ör. `MERGED`, `CLOSED`) veya `gh pr view` ayrıştırılamaz çıktı döndürür. Ayrıca `origin/` yerel olarak eksik veya base'ten önce komit olmadığında açık başarısız — bu Layer 1 fall-through'ları izin vermeden önce önbelleğe alınan PR birleştirilebilirliğine danışır. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | -|-------|-----|-----------|---------| -| `baseBranch` | `string` | `"main"` | Çatışmalar için kontrol edilecek taban dalı. | +|-------|-----|-----------|----------| +| `baseBranch` | `string` | `"main"` | Çakışmaları kontrol etmek için taban branch. | -Bu ilke GitHub CLI (`gh`) gerektirir. İlke, herhangi bir çatışma probesini çalıştırmadan önce — `gh` olmadan bir `OPEN` PR var olup olmadığını doğrulamak için `gh pr view` kullanır, ilke kısa devredir ve izin verir. Çekme istekleri için okuma erişimi olan `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` komutunu çalıştırın. +Bu ilke GitHub CLI (`gh`) gerektirir. İlke herhangi bir çakışma araştırması çalıştırmadan — `gh` olmadan ilke açık başarısız hale gelir — branch için bir `OPEN` PR olduğunu teyit etmek için `gh pr view` kullanır. Pull request'lere okuma erişimi için `repo` kapsamı olan kişisel erişim belirteci ile `gh auth login` çalıştırın. --- @@ -819,13 +819,13 @@ Bu ilke GitHub CLI (`gh`) gerektirir. İlke, herhangi bir çatışma probesini ### `require-ci-green-before-stop` **Olay:** Stop -**Varsayılan:** Mevcut dal üzerinde CI denetimleri başarısız oluyor veya çalışmaya devam ederken durmasını engeller. Hem GitHub Actions iş akışı çalışmalarını hem de üçüncü taraf bot denetimlerini (ör. CodeRabbit, SonarCloud, Codecov) denetler. `skipped`, `cancelled` ve `neutral` sonuçlarını başarısız olmama olarak değerlendirir (sonuncusu, örn. dış katkı PR'lerde Socket Security uyarılarını kapsar, burada uygulama kasıtlı olarak başarı/başarısızlık yerine nötr bildir). Tüm denetimler geçtiğinde bilgi mesajını döndürür. +**Varsayılan:** Mevcut branch üzerindeki CI kontrolleri başarısız olduğunda veya yine de çalışırken durdurmasını reddeder. Hem GitHub Actions iş akışı çalışmalarını hem de üçüncü taraf bot kontrollerini (ör. CodeRabbit, SonarCloud, Codecov) kontrol eder. `skipped`, `cancelled` ve `neutral` sonuçlarını başarısız olmayan olarak değerlendirir (ikincisi ör. Socket Security uyarılarını dış katkıyapan PR'larında kapsar ve uygulama başarı/başarısızlık yerine tarafsız olarak rapor verir). Tüm kontroller geçtiğinde bir bilgisel mesaj döndürür. -Parametresi yoktur. +Parametresi yok. -Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve kimlik doğrulamasından geçmiş olması gerekir. -İş akışı çalışmaları ve Denetimler API'ı için okuma erişimi olan `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` komutunu çalıştırın. `gh` yüklü değilse veya kimlik doğrulaması yapılmamışsa, ilke açık başarısız olur ve nedenini Claude'a raporta eder. +Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve doğrulanmış olmasını gerektirir. +Actions iş akışı çalışmalarına ve Checks API'sine okuma erişimi için `repo` kapsamı olan kişisel erişim belirteci ile `gh auth login` çalıştırın. `gh` yüklü veya doğrulanmadıysa, ilke açık başarısız olur ve nedenini Claude'a bildirir. --- @@ -834,7 +834,7 @@ Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve kimlik doğrulam ## Bireysel ilkeleri devre dışı bırakma -Yapılandırmanızda `enabledPolicies` öğesinden belirli bir ilkeyi kaldırın veya panodaki İlkeler sekmesinde kapatın. +Yapılandırmanızdaki `enabledPolicies` içinden belirli bir ilkeyi kaldırın veya panodaki İlkeler sekmesinde kapatın. ```json { @@ -845,4 +845,4 @@ Yapılandırmanızda `enabledPolicies` öğesinden belirli bir ilkeyi kaldırın } ``` -`enabledPolicies` öğesinde listelenmemiş ilkeler `policyParams` girdileri olsa bile çalışmaz. \ No newline at end of file +`enabledPolicies` içinde listelenmemiş ilkeler, `policyParams` girdileri için bile çalışmaz. \ No newline at end of file diff --git a/docs/tr/cli/audit.mdx b/docs/tr/cli/audit.mdx index 8ff1c114..8c6d5853 100644 --- a/docs/tr/cli/audit.mdx +++ b/docs/tr/cli/audit.mdx @@ -1,19 +1,20 @@ --- +--- title: Geçmiş oturumları denetle (beta) -description: "Aracının geçmiş transkriptler üzerinde ne sıklıkta savurgan veya riskli işler yaptığını say" +description: "Ajanın geçmiş transkriptler arasında ne sıklıkla israf veya riskli şeyler yaptığını say" --- - **Beta özellik.** Denetim, erken geri bildirim toplarken beta olarak sunulmaktadır. - Dedektör kataloğu ve rapor formatı, sonraki kararlı sürümden önce değişebilir. - Herhangi bir sorun görürseniz lütfen bir sorun açın. + **Beta özelliği.** Denetim, erken geri bildirim toplarken beta olarak sunulmaktadır. + Dedektör kataloğu ve rapor biçimi, bir sonraki kararlı sürümden önce değişebilir. + Herhangi bir şey yanlış görünürse lütfen bir sorun açın. -Denetim, geçmiş agent-CLI transkriptlerinizi failproofai'nin politika motoru üzerinden yeniden oynatır ve **`/audit` pano sayfasında** paylaşılabilir, görsel bir rapor sunar — aracınızın arketipi, 0–100 puanı ve hangi politikaların hangi durumları yakalamış olacağı tam olarak gösterilir. +Denetim, geçmiş ajan-CLI transkriptlerinizi failproofai'nin politika motoru aracılığıyla yeniden oynatır ve **`/audit` pano sayfasında** paylaşılabilir, görsel bir rapor sunar — ajanın arketipi, 0–100 puanı ve tam olarak hangi politikaların neyi yakalayabileceği. ## Çalıştırın -Üç giriş yolu — hepsi aynı `/audit` raporuna ulaşır. +Üç giriş yolu — hepsi aynı `/audit` raporunda biter. @@ -33,85 +34,88 @@ failproofai - `npx -y failproofai audit` failproofai'yi getirir, taramayı çalıştırır ve panoyu sizin için açar — öncesinde kurulum yapmanız gerekmez. + `npx -y failproofai audit` failproofai'yi alır, taramayı çalıştırır ve panoyu sizin için açar — öncesinde kurulum gerekmez. - `failproofai audit` taramayı terminalinizde çalıştırır, ardından bittiğinde `localhost:8020/audit` adresini otomatik olarak açar. + `failproofai audit` taramayı terminalinizde çalıştırır, ardından bittiğinde `localhost:8020/audit` otomatik olarak açılır. - `failproofai` komutunu çalıştırın ve navbar'da **Audit** seçeneğine tıklayın (Policies ve Projects arasında) veya `/audit` adresini doğrudan açın. + `failproofai` çalıştırın ve navbar'da **Audit**'e tıklayın (Policies ve Projects arasında) veya `/audit`'i doğrudan açın. - Kullanım bilgilerini görmek için `failproofai audit -h` (veya `--help`) komutunu çalıştırın. Denetim **tamamen çevrimdışı** çalışır — hesap veya ağ bağlantısı gerekli değildir — ve pano `Ctrl+C` ile durdurana kadar sunmaya devam eder. + Kullanımı görmek için `failproofai audit -h` (veya `--help`) komutunu çalıştırın. Denetim **tamamen çevrimdışı** çalışır — hesap veya ağ gerekmez — ve `Ctrl+C` ile durdurana kadar pano sunulmaya devam eder. -Pano, bu makinedeki geçmiş agent CLI transkriptlerini tarar (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) ve aracının failproofai'nin durdurmak için inşa edildiği şeyleri ne sıklıkta yaptığını raporlar — ortam değişkeni kontrolleri, güç şeklinde push'lar, gereksiz `cd ` önekleri, uyku-yoklama döngüleri, yeni düzenlenen dosyaları yeniden okuma ve daha fazlası. +Pano, bu makinedeki geçmiş ajan CLI transkriptlerini tarar (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) ve ajanın failproofai'nin durdurmak için inşa edildiği şeyleri ne sıklıkla yaptığını raporlar — ortam değişkeni kontrolleri, force push'lar, gereksiz `cd ` ön ekleri, sleep-polling döngüleri, az önce düzenlenmiş dosyaları yeniden okuma ve daha fazlası. -Her transkript için, her araç-kullanım olayı 39 yerleşik politika **ve** runtime politikaları tarafından henüz kapsanmayan desenleri yakalayan 8 denetim-yalnızca dedektörü üzerinden yeniden oynatılır. Sayılar tüm oturumlar arasında politika/dedektör başına toplanır. +Her transkript için, her bir tool-use olayı 39 yerleşik politika **ve** runtime politikaları tarafından henüz kapsanmayan desenleri yakalayan 8 denetim-yalnız dedektörün aracılığıyla yeniden oynatılır. Sayılar tüm oturumlar arasında politika / dedektör başına toplanır. -## Ne alacaksınız +## Ne elde edersiniz -`/audit` sayfası, tek ekranlı, paylaşılabilir bir **poster** ve ardından dört alt bölümdür: +`/audit` sayfası, tek ekranlı, paylaşılabilir bir **poster** ve ardından dört sayfanın altındaki bölümü içerir: -1. **Poster** — aracınızın kimliği bir bakışta: **arketipi** (8'den biri — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), kişi anahtar sözcükleri, bu arketipin ne kadar nadir olduğu ve **0–100 puanı** bir seviye bandı ile (`S` ila `bottom tier`). Paylaşmak için tasarlandı — X veya LinkedIn'e gönderin veya PNG olarak indirin. -2. **`// strengths`** — aracınızın zaten iyi yaptığı şeyler, taramadan gelen gerçek sayılar olarak (ör. temiz araç çağrısı %, `0` push-to-main denemesi), yalnızca ilgili politikanın temiz bir rekoru olan yerlerde gösterilir. -3. **`// quirks`** — sıyrılan: failproofai'nin yakalamış olacağı davranışların sıralanmış tablosu — *ne zaman* en son gerçekleştiği, *ne sıyrıldı* (ve bunu engellemiş olacak yerleşik), *önem derecesi* ve *ne sıklıkta* *görüldüğü* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — önerilen düzeltme listesi: politika başına bir satır `failproofai policy add ` kopyala-yapıştır ile, artı **install all** düğmesi, tüm önerileri bir kerede etkinleştirir ve bunu yaparsanız **projected score** gösterir. -5. **`// come back better`** — alışkanlık inşa edin: yeniden denetim e-posta **reminder** ayarlayın (`3d` / `7d` / `14d` / `30d`) veya şimdi yeniden denetim yapın, ve **bir arkadaşınızı davet edin** kendi denetimini çalıştırmaları (failproof.ai'den gönderilir, Cc sizinle). Reminders ve davetler oturum açma gerektirir. +1. **Poster** — ajanın kimliği bir bakışta: **arketipi** (8'den biri — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), persona anahtar kelimeleri, o arketip ne kadar nadir ve **0–100 puanı** bir tier bandı ile (`S` ile `bottom tier` arasında). Paylaşmak için tasarlanmış — X veya LinkedIn'e gönderin veya PNG olarak indirin. +2. **`// strengths`** — ajanın zaten iyi yaptığı şeyler, taramadan gerçek sayılar olarak (örneğin clean-tool-call %, `0` push-to-main denemeleri), yalnızca ilgili politikanın temiz bir kaydı olduğu yerlerde gösterilir. +3. **`// quirks`** — sıyrılan şeyler: failproofai'nin yakalayabileceği davranışların sıralanmış tablosu — *ne zaman* son olarak oldu, *ne sıyrıldı* (ve bunu engelleyecek yerleşik), *önem düzeyi* ve ne sıklıkta *görüldüğü* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — önerilen düzeltme listesi: politika başına bir satır `failproofai policy add ` kopyala-yapıştır ile, artı **tümünü yükle** düğmesi her tavsiyeyi aynı anda etkinleştirir ve bunu yaparsanız **öngörülen puanınız** gösterir. +5. **`// come back better`** — alışkanlık oluşturun: yeniden denetim e-posta **hatırlatıcısını** ayarlayın (`3d` / `7d` / `14d` / `30d`) veya şimdi yeniden denetleyin ve **bir arkadaşı davet edin** kendi denetimini çalıştırmalarını (failproof.ai'den gönderilir, Cc'ye eklenir). Hatırlatıcılar ve davetiyeler oturum açmayı gerektirir. -## Planlanan denetimler +## Planlı denetimler -**failproofaid daemon** komutunu çalıştırırsanız (bkz. [`failproofai config`](/tr/cli/install-policies)), -bu, denetimi sizin için bir programa göre yeniden çalıştırabilir ve `/audit` raporunu arka planda yenileyebilir. **Varsayılan olarak kapalıdır**, çünkü tarama, bu makinedeki her agent oturumu transkriptinin *içeriğini* okur — bir zamanlayıcıda hiçbir şey taranamaz, siz bunu istemediğiniz sürece. +**failproofaid daemon**'u çalıştırırsanız (bkz. [`failproofai config`](/tr/cli/install-policies)), +denetimi sizin için bir programa göre yeniden çalıştırabilir ve `/audit` raporunu arka planda yenileyebilir. **Varsayılan olarak kapalıdır**, çünkü tarama bu makinedeki her ajan oturumu transkriptinin *içeriğini* okur — hiçbir şey zamanlamaya göre taranmaz ta ki siz bunu isteyin. -Bunu `~/.failproofai/config.toml` dosyasında açın: +`~/.failproofai/config.json` içinde açın — `audit` anahtarını dosyanın halihazırda tuttuğu başka şeylerin yanına ekleyin: -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` -| Anahtar | Anlam | +| Anahtar | Anlamı | |---|---| -| `auto` | `true` planlanan taramayı etkinleştirir. Başka herhangi bir şey — yoksa, `false`, `"yes"` — kapalıdır. | -| `interval_days` | Taramalar arasındaki gün sayısı. 1–90 aralığına sabitlenir; `0`, negatif veya sayı olmayan değer `7`'ye geri döner. | +| `auto` | `true` planlı taramayı etkinleştirir. Başka her şey — yokluğu, `false`, `"yes"` — kapalıdır. | +| `interval_days` | Taramalar arasındaki gün sayısı. 1–90 aralığında sınırlandırılır; `0`, negatif veya sayı olmayan değer `7` olarak döner. | -- Zamanlama **duvar saati** tabanlıdır, bu nedenle askı ve yeniden başlatmayı ayakta tutar: zamanı geçmiş bir dizüstü bilgisayar **bir kez** uyandığında çalışır, hiçbir zaman bir yedek değildir. -- Her çalıştırma ayrı, düşük öncelikli (`nice 19`) bir işlemdir — hiçbir zaman daemon'un hook yolu değildir, bu da araç çağrılarını cevaplamaya boş kalır. -- `failproofai audit` veya pano yeniden çalıştırması zaten uçuştaysa bir tarama atlanır; başarısızlık olarak değil de kısa bir süre sonra yeniden denenir. -- İlerleme `~/.failproofai/state/audit-schedule.json` dosyasına yazılır (son çalıştırma, sonraki gözlemle). Daemon bu dosyaya sahiptir — kadansı `config.toml` dosyasında değiştirin. +- Takvim saati tabanlı olduğundan **askıya alma ve yeniden başlatmalar** ayakta kalır: uyku süresi nedeniyle hazır olduğu zamanı kaçıran bir dizüstü bilgisayar uyandığında **bir kez** çalışır, asla bir birikme değil. +- Her çalıştırma ayrı, düşük öncelik (`nice 19`) işlem — asla daemon'ın hook yolu değil, bu tool çağrılarına cevap vermek için serbest kalır. +- `failproofai audit` veya panonun yeniden çalıştırması zaten uçuştaysa tarama atlanır; başarısız olarak değil de kısa süre sonra yeniden denenmiş olur. +- İlerleme `~/.failproofai/state/audit-schedule.json` (son çalıştırma, sonraki hazır) dosyasına yazılır. Daemon bu dosyaya sahiptir — `config.json` içinde adımı değiştirin. -Bunu daha eski failproofai tarafından kurulan bir makinede etkinleştirdiyseniz, -`failproofai config` komutunu bir kez çalıştırın. Daemon'un hizmet tanımı, -CLI'yi başlatabilmesi için ek bir giriş gerektirir ve yenileme bu komutun bir parçasıdır. +Bunu eski failproofai tarafından kurulan bir makinede etkinleştirdiyseniz, +`failproofai config` komutunu bir kez çalıştırın. Daemon'ın hizmet tanımı +CLI'yi başlatabilmesi için bir ekstra giriş gerektirir ve yenileme bu komutun bir parçasıdır. -## Denetim-yalnızca dedektörleri +## Denetim-yalnız dedektörler -Bunlar, gerçek zamanlı olarak (henüz) uygulanmayan "aptalca davranış" desenlerini algılar. Yalnızca denetim sırasında çalışırlar ve hiçbir zaman canlı araç çağrısını engellemezler. +Gerçek zamanlı olarak (henüz) uygulanmayan "aptalca davranış" desenlerini algılar. Yalnızca denetim sırasında çalışır ve hiçbir zaman canlı tool çağrılarını engellenmez. -| Dedektör | Ne sayıyor | +| Dedektör | Ne saydığı | |---|---| -| `redundant-cd-cwd` | `cd && …` ile başlayan Bash komutları, hatta komutlar zaten `cwd`'de çalışıyor. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` tek bir kaynak dosyada — `Read` aracını kullanın. | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` yerinde düzenlemeler — `Edit` aracını kullanın. | -| `prefer-write-over-heredoc` | Heredoc / çok satırlı `echo > file` yazma dosyaları — `Write` aracını kullanın. | -| `sleep-polling-loop` | Uzun `sleep N` (≥ 30s) veya `while …; sleep …; done` yoklama döngüleri. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, vb. — `cwd`'ye kapsam belirleyin. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, hook'ları atlama. | -| `reread-after-edit` | Aynı oturumda `Edit`/`Write` yapılan bir dosyanın `Read`'i. | +| `redundant-cd-cwd` | `cd && …` ile başlayan Bash komutları, oysa komutlar zaten `cwd` içinde çalışır. | +| `prefer-edit-over-read-cat` | Tek bir kaynak dosyada `cat`/`head`/`tail`/`less`/`more` — `Read` aracını kullanın. | +| `prefer-edit-over-sed-awk` | Yerinde `sed -i` / `awk … > file` düzenlemesi — `Edit` aracını kullanın. | +| `prefer-write-over-heredoc` | Dosya yazmak için Heredoc / çok satırlı `echo > file` — `Write` aracını kullanın. | +| `sleep-polling-loop` | Uzun `sleep N` (≥ 30s) veya `while …; sleep …; done` polling döngüleri. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, vb. — `cwd` yerine kapsamlı olun. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, kancaları atlayarak. | +| `reread-after-edit` | Aynı oturumda az önce `Edit`/`Write` yapılmış bir dosyanın `Read` işlemi. | ## Önbellekler -- **Per-transcript cache** `~/.failproofai/cache/audit/.json` konumunda `(mtime, size, engineVersion, detectorVersion)` ile anahtarlanmış — transkript veya politika/dedektör kodu değiştiğinde otomatik olarak geçersiz kılınır. Her giriş ayrıca **TTL metaveri** olarak bir `cachedAt` zaman damgası depolar (önbellek anahtarının parçası değil); **7 günden** eski girişler, uzun süreli sonuçlar gelişen dedektör amacından daha uzun yaşanmasın diye okunmada reddedilir. -- **Whole-result cache** `~/.failproofai/audit-dashboard.json` konumunda (mode 0600). Pano, yeniden çalıştırmadan navigasyon üzerinde anında işlenmesini sağlar. Ayrıca **7 günlük TTL** geçtikten sonra okunmada reddedilir — `/audit` daha sonra boş durumuna döner ve yeni bir çalıştırma istenir. Raporun alt kısmı yakınında `[ re-audit now ]` seçeneğini tıklayarak yenileyin — yeniden denetim `noCache: true` gönderir, bu nedenle per-transcript önbelleğini atlar ve her transkripti yeniden tarar; çalıştırma yapışkan üst şerit üzerinden ilerlemeyi akışla iletir ve başarıda sonucu yerinde değiştirir (sayfa yeniden yükleme yok; başarısız bir yeniden denetim önceki raporu tutar). +- **Transkript başına önbellek** `~/.failproofai/cache/audit/.json` adresinde `(mtime, size, engineVersion, detectorVersion)` anahtarıyla — transkript veya politika/dedektör kodu değiştiğinde otomatik olarak geçersiz kılınır. Her giriş aynı zamanda **TTL meta verisi** olarak bir `cachedAt` zaman damgası depolar (önbellek anahtarının parçası değil); **7 gün** yaşlı girdiler, uzun süreli sonuçlar gelişen dedektör niyetinden daha uzun ömürlü olmamak üzere okuma sırasında reddedilir. +- **Tüm sonuç önbelleği** `~/.failproofai/audit-dashboard.json` adresinde (mod 0600). Panoyu yeniden çalıştırmadan gezintide anında oluşturmaya izin verir. Ayrıca **7 günlük TTL**'den sonra okuma sırasında reddedilir — `/audit` ardından boş durumuna düşer ve yeni çalıştırma ister. Raporu raporun alt kısmı yakınında `[ re-audit now ]`'a tıklayarak yenileyin — yeniden denetim `noCache: true` gönderir, bu nedenle transkript başına önbelleği atlar ve önbelleğe alınan sonucu dönüştürmek yerine her transkripti yeniden tarar; çalıştırma yapışkan üst şerit aracılığıyla ilerlemeyi akışa alır ve başarıda sonucu yerinde değiştirir (sayfa yeniden yüklenmesi yok; başarısız yeniden denetim önceki raporu tutar). ## Notlar -- **Mutasyon yok.** Denetim salt okunur modda oynatılır. `warn-repeated-tool-calls` atlanır, çünkü oturum başına yan araç aksi takdirde değiştirilir. -- **Workflow policies atlandı.** `require-*-before-stop` politikaları yalnızca `Stop` olaylarında ve canlı git durumuna karşı `execSync` öğesinde ateş eder — "2025'te ne olmuş olurdu" anlamı yoktur, bu nedenle denetim sayılarında görünmezler. -- **Özel politikalar atlandı.** Kullanıcı tarafından sağlanan özel hook'lar yeniden oynatılmaz (orijinal oturumdan bu yana değişmiş olabilir). \ No newline at end of file +- **Mutasyon yok.** Denetim salt okunur modda yeniden oynatılır. `warn-repeated-tool-calls` atlanır, çünkü oturum başına sidecar'ı aksi takdirde değiştirilecektir. +- **İş akışı politikaları atlanır.** `require-*-before-stop` politikaları yalnızca `Stop` olaylarında ve canlı git durumuna karşı `execSync` üzerinde etkinleşir — bunların "2025'te ne olmuş olabilir" yorumu yok, bu nedenle denetim sayılarında görünmezler. +- **Özel politikalar atlanır.** Kullanıcı tarafından sağlanan özel kancalar yeniden oynatılmaz (orijinal oturumdan bu yana değişmiş olabilirler). \ No newline at end of file diff --git a/docs/tr/cli/dashboard.mdx b/docs/tr/cli/dashboard.mdx index aa57bf2a..26a1c76d 100644 --- a/docs/tr/cli/dashboard.mdx +++ b/docs/tr/cli/dashboard.mdx @@ -1,6 +1,6 @@ --- title: Oturumları görüntüle -description: "Aracı oturumlarına göz atmak ve politikaları yönetmek için panoyu başlatın" +description: "Ajan oturumlarına göz atmak ve politikaları yönetmek için panoyu başlatın" --- ```bash @@ -14,16 +14,16 @@ Web panosunu `http://localhost:8020` adresinde başlatır. | Bayrak | Açıklama | |------|-------------| | `--port ` | Dinlenecek port (varsayılan: `8020`) | -| `--allowed-origins ` | Geliştirme kaynaklarına erişime izin verilen virgülle ayrılmış konaklar/IP'ler | +| `--allowed-origins ` | Geliştirme kaynaklarına erişime izin verilen virgülle ayrılmış ana bilgisayarlar/IP'ler | Panoyu varsayılan olmayan bir Claude proje klasörüne yönlendirmek için başlatırken `CLAUDE_PROJECTS_PATH` ortam değişkenini ayarlayın. ## Örnekler ```bash -# Farklı bir portta başlatın +# Farklı bir portta başlat failproofai --port 9000 -# Ortam değişkeni aracılığıyla özel bir Claude projeleri yolu kullanın +# Ortam değişkeni aracılığıyla özel bir Claude projeleri yolu kullan CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/tr/cli/environment-variables.mdx b/docs/tr/cli/environment-variables.mdx index 23a16551..8913aab3 100644 --- a/docs/tr/cli/environment-variables.mdx +++ b/docs/tr/cli/environment-variables.mdx @@ -1,65 +1,67 @@ --- title: Ortam değişkenleri -description: "Ortam değişkenleriyle failproofai davranışını yapılandırın" +description: "failproofai davranışını ortam değişkenleriyle yapılandırın" --- -## Gösterge Paneli +## Dashboard | Değişken | Açıklama | |----------|----------| -| `PORT` | Gösterge paneli portu (varsayılan: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Claude Code proje klasörlerinin bulunduğu yeri geçersiz kıl | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Gizlenecek gösterge paneli sayfaları (virgülle ayrılmış) | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Dev kaynaklarına erişime izin verilen hosts/IPs. `--allowed-origins` ile aynı. | +| `PORT` | Dashboard portu (varsayılan: `8020`) | +| `CLAUDE_PROJECTS_PATH` | Claude Code proje klasörlerinin bulunduğu konumu geçersiz kılın | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Gizlenecek dashboard sayfaları (virgülle ayrılmış) | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Dev kaynaklarına erişime izin verilen hostlar/IP'ler. `--allowed-origins` ile aynı. | ## Günlükleme | Değişken | Açıklama | |----------|----------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Sunucu günlük seviyesi (varsayılan: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Özel hook günlük dosyası yolu veya `true` (varsayılan: `~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Özel hook günlük dosyası yolu veya varsayılan için `true` (`~/.failproofai/logs/hooks.log`) | ## Telemetri -failproofai varsayılan olarak anonim kullanım telemetrisi gönderir. Bunu kapatmanın iki yolu vardır ve daha kısıtlayıcı olanı geçerli olur — bir ortam değişkeni yapılandırma dosyasının kapatıp devre dışı bıraktığı şeyi asla yeniden etkinleştiremez. +failproofai varsayılan olarak anonim kullanım telemetrisi bildirir. Bunu kapatmanın iki yolu vardır ve bunlar daha kısıtlayıcı olanı seçer — bir ortam değişkeni, yapılandırma dosyasının kapatmış olduğu bir şeyi asla yeniden açamaz. | Değişken | Açıklama | |----------|----------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Bu işlem için anonim kullanım telemetrisi devre dışı bırak | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Bu işlem için anonim kullanım telemetrilerini devre dışı bırakın | -Makine için kalıcı olarak devre dışı bırakmak için bunu `~/.failproofai/config.toml` dosyasına ekleyin: +Makine için kalıcı olarak devre dışı bırakmak için, bunu `~/.failproofai/config.json` dosyasına ekleyin: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -Yapılandırma dosyası, **failproofaid daemon** çalıştırıyorsanız kullanılacak seçenektir. -Daemon sistem kapsamında bir hizmettir ve ortamı kabuğunuzdan dışarı aktarılan -değişkenleri içermez — bu nedenle `FAILPROOFAI_TELEMETRY_DISABLED` ona ulaşamaz. -`[telemetry] enabled = false` hem CLI hem de daemon tarafından okunur. +Yapılandırma dosyası, **failproofaid daemon** uygulamasını çalıştırıyorsanız kullanılacak seçenektir. +Daemon, sistem kapsamında bir hizmettir ve ortamı, kabuktan aktarılan değişkenleri içermez — bu nedenle +`FAILPROOFAI_TELEMETRY_DISABLED` onu ulaşamaz. `[telemetry] enabled = false` hem CLI hem de daemon tarafından okunur. -Daemon yalnızca kendi **yaşam döngüsünü** raportar: başladığı (ve önceki çalışmanın temiz bir şekilde çıkıp çıkmadığı), durduğu, değerlendirme çalışanı oluşturulduğu veya yeniden başlatıldığı, bir toplayıcı görev başarısız olduğunda ve bulut-ilkesi çekme sonucu. Bunlar düşük kardinaliteli değerler ve sayıları taşır — asla dosya yolu, komut, ilke, istem veya transkriptten okunan hiçbir şey taşımaz. Araç başına çağrı olayı yoktur. +Daemon yalnızca kendi **yaşam döngüsünü** bildirir: başlatıldığı (ve önceki çalışmanın temiz çıkış yapıp yapmadığı), durduğu, değerlendirme çalışanının oluşturulduğu veya yeniden başlatıldığı, bir toplayıcı görevinin başarısız olduğu ve bulut politikası çekme sonucu. Bunlar düşük kardinalite değerleri ve sayımları taşır — asla dosya yolu, komut, politika, istem veya transkriptten okunan hiçbir şey değildir. Tool çağrısı başına etkinlik yoktur. -## Kimlik Doğrulama +## Kimlik doğrulama | Değişken | Açıklama | |----------|----------| -| `FAILPROOF_API_URL` | Gösterge paneli kimlik doğrulama iletişim kutusu tarafından kullanılan api-sunucusu temel URL'sini geçersiz kıl. Varsayılan `https://api.befailproof.ai`; yerel api-sunucusu çalıştırırken `http://localhost:8080` (veya başka bir yer) olarak ayarlayın. | -| `FAILPROOFAI_AUTH_DIR` | `auth.json` dosyasının depolandığı yeri geçersiz kıl (varsayılan: `~/.failproofai`). Çoğunlukla izole testler için yararlıdır. | +| `FAILPROOF_API_URL` | Dashboard kimlik doğrulama iletişim kutusu tarafından kullanılan API sunucusu temel URL'sini geçersiz kılın. Varsayılan olarak `https://api.befailproof.ai`; yerel API sunucusu çalıştırırken `http://localhost:8080` (veya başka bir yer) olarak ayarlayın. | +| `FAILPROOFAI_AUTH_DIR` | `auth.json` dosyasının depolanduğu konumu geçersiz kılın (varsayılan: `~/.failproofai`). Çoğunlukla izole testler için kullanışlı. | ## İlk çalıştırma istemi | Değişken | Açıklama | |----------|----------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | İlk boş `failproofai` çağrısında ilkeleri yüklemeyi teklif eden istemi atla | +| `FAILPROOFAI_NO_FIRST_RUN=1` | İlk basit `failproofai` çağrısında politika yüklemeyi teklif eden istemi atlayın | -## LLM (ilke değerlendirmesi için) +## LLM (politika değerlendirmesi için) | Değişken | Açıklama | |----------|----------| | `FAILPROOFAI_LLM_BASE_URL` | LLM API uç noktası (varsayılan: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | LLM destekli ilkeler için API anahtarı | +| `FAILPROOFAI_LLM_API_KEY` | LLM destekli politikalar için API anahtarı | | `FAILPROOFAI_LLM_MODEL` | Model adı (varsayılan: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/tr/cli/hook.mdx b/docs/tr/cli/hook.mdx index 83412edd..b858c341 100644 --- a/docs/tr/cli/hook.mdx +++ b/docs/tr/cli/hook.mdx @@ -1,7 +1,6 @@ --- ---- -title: Hook işleyicisi (dahili) -description: "Claude Code'un her araç olayında çağırdığı alt işlem" +title: Hook handler (iç kullanım) +description: "Her tool olayında Claude Code'un çağırdığı subprocess" --- ```bash @@ -10,22 +9,22 @@ failproofai --hook Bu, `failproofai policies --install` tarafından Claude Code'un `settings.json` dosyasına kaydedilen komuttur. Normalde bunu doğrudan çağırmazsınız. -stdin'den bir JSON yükü okur, tüm etkin politikaları değerlendirir ve kararı gösteren bir çıkış kodu ile sonlanır: +stdin'den bir JSON payload'ı okur, etkinleştirilmiş tüm politikaları değerlendirir ve kararı belirten bir çıkış kodu ile sonlandırır: | Çıkış kodu | Karar | Etki | -|-----------|-------|------| -| `0` | `allow` | Eylemi izin ver | -| `1` | `deny` | Eylemi engelle - Claude reddetme nedenini görür | +|-----------|--------|--------| +| `0` | `allow` | İşleme izin ver | +| `1` | `deny` | İşlemi engelle - Claude ret nedenini görür | | `2` | `instruct` | Claude'un bağlamına rehberlik ekle | -### Desteklenen olay türleri +### Desteklenen event türleri -| Kategori | Olaylar | -|----------|---------| -| **Araç yürütme** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | +| Kategori | Event'ler | +|----------|--------| +| **Tool yürütme** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Oturum yaşam döngüsü** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **Kullanıcı etkileşimi** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **Alt ajanlar ve görevler** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **Subagent'ler ve görevler** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **Yapılandırma** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **Dosya sistemi** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **Bağlam** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/tr/cli/install-policies.mdx b/docs/tr/cli/install-policies.mdx index 1887d644..09934271 100644 --- a/docs/tr/cli/install-policies.mdx +++ b/docs/tr/cli/install-policies.mdx @@ -1,33 +1,33 @@ --- title: Politikaları yükle -description: "Politikaları etkinleştirerek her ajan aracı çağrısında çalışmalarını sağlayın" +description: "Politikaları etkinleştir ve her agent araç çağrısında çalıştır" --- ```bash failproofai policies --install [policy-names...] [options] ``` -failproofai'nin araç çağrılarını yakalaması için yüklü ajan CLI'nizin (Claude Code, OpenAI Codex veya GitHub Copilot CLI _(beta)_) ayarlar dosyasına hook girişleri yazar. +Yüklü agent CLI'nizin (Claude Code, OpenAI Codex veya GitHub Copilot CLI _(beta)_) ayarlar dosyasına hook girdileri yazar, böylece failproofai araç çağrılarını durdurur. Takma adlar: `failproofai p -i` ## Seçenekler | Bayrak | Açıklama | -|------|-------------| -| `--cli claude\|codex\|copilot` | Yüklenecek ajan CLI'leri; boşlukla ayrılmış (ör. `--cli claude codex copilot`) veya tekrarlı. Yüklü CLI'leri algılamak ve sormak için atlanabilir. | -| `--scope user` | Kullanıcı kapsamı ayarlar dosyasına yükle (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Varsayılan. | -| `--scope project` | Proje kapsamı ayarlar dosyasına yükle (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Yalnızca Claude — `/.claude/settings.local.json` dosyasına yükle. Codex ve Copilot'un `local` kapsamı yoktur. | +|--------|----------| +| `--cli claude\|codex\|copilot` | Yüklü olacak Agent CLI'si(ları); boşlukla ayrılmış (örn. `--cli claude codex copilot`) veya tekrarlı. Yüklü CLI'leri algılamak ve seçim istemi göstermek için bırakın. | +| `--scope user` | Kullanıcı kapsamlı ayarlar dosyasına yükle (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Varsayılan. | +| `--scope project` | Proje kapsamlı ayarlar dosyasına yükle (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Yalnızca Claude — `/.claude/settings.local.json` dosyasına yükler. Codex ve Copilot için `local` kapsamı yoktur. | | `--custom ` / `-c` | Özel hook politikalarını içeren JS dosyasının yolu | ## Davranış -- **Politika adı belirtilmedi** - politika seçmek için etkileşimli bir istem açar -- **Belirli adlar** - bu politikaları etkinleştirir (zaten etkin olanların üzerine eklenir) -- **`all`** - mevcut tüm politikaları etkinleştirir +- **Politika adı yok** - politika seçmek için etkileşimli bir istem açar +- **Belirli adlar** - bu politikaları etkinleştirir (zaten etkinleştirilenlerle birlikte eklenir) +- **`all`** - kullanılabilir her politikayı etkinleştirir -Yükleme kümülatiftir: `--install` komutunu yeniden çalıştırmak yeni politikalar ekler ancak mevcut olanları kaldırmaz. +Kurulum kümülatiftir: `--install` komutunu tekrar çalıştırmak yeni politikaları ekler ve mevcut olanları kaldırmaz. ## Örnekler @@ -35,23 +35,23 @@ Yükleme kümülatiftir: `--install` komutunu yeniden çalıştırmak yeni polit # Tüm varsayılan politikaları genel olarak yükle (etkileşimli) failproofai policies --install -# Geçerli proje için belirli politikaları yükle +# Mevcut proje için belirli politikaları yükle failproofai policies --install block-sudo sanitize-api-keys --scope project # Tüm politikaları aynı anda etkinleştir failproofai policies --install all -# Özel bir politika dosyası ile yükle +# Özel politikalar dosyasıyla yükle failproofai policies --install --custom ./my-policies.js -# OpenAI Codex için (proje kapsamı) yükle +# OpenAI Codex için yükle (proje kapsamı) failproofai policies --install --cli codex --scope project -# GitHub Copilot CLI (beta) için geçerli proje kapsamında yükle +# GitHub Copilot CLI (beta) için mevcut proje için yükle failproofai policies --install --cli copilot --scope project -# Üç CLI için birden yükle +# Üç CLI için de aynı anda yükle failproofai policies --install --cli claude codex copilot ``` -`--custom ` sağlandığında, dosya hemen doğrulanır — en az bir kez `customPolicies.add()` çağrısı yapmalıdır. Çözümlenen yol `policies-config.json` dosyasına `customPoliciesPath` olarak kaydedilir. \ No newline at end of file +`--custom ` sağlandığında, dosya hemen doğrulanır — en az bir kez `customPolicies.add()` çağrı yapması gerekir. Çözümlenen yol, `policies-config.json` dosyasına `customPoliciesPath` olarak kaydedilir. \ No newline at end of file diff --git a/docs/tr/cli/list-policies.mdx b/docs/tr/cli/list-policies.mdx index 9309e516..aa2c0c73 100644 --- a/docs/tr/cli/list-policies.mdx +++ b/docs/tr/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- -title: İlkeleri Listele -description: "Hangi ilkelerin etkin olduğunu, parametrelerini ve özel ilkeleri görün" +title: Politikaları listele +description: "Hangi politikaların etkinleştirildiğini, parametrelerini ve özel politikaları göz önüne alın" --- ```bash failproofai policies ``` -Tüm ilkeleri durumları, yapılandırılan parametreleri ve özel ilkeleriyle birlikte gösterir. +Tüm politikaları durumu, yapılandırılmış parametreleri ve özel politikaları ile birlikte gösterir. ## Örnek çıktı @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -`policyParams` içindeki bilinmeyen anahtarlar burada işaretlenir, böylece yazım hatalarını erkenden yakalayabilirsiniz. \ No newline at end of file +`policyParams` içindeki bilinmeyen anahtarlar burada işaretlenmiş olup, yazım hataları nedeniyle erken uyarı alabilirsiniz. \ No newline at end of file diff --git a/docs/tr/cli/migrate.mdx b/docs/tr/cli/migrate.mdx new file mode 100644 index 00000000..fdf17318 --- /dev/null +++ b/docs/tr/cli/migrate.mdx @@ -0,0 +1,86 @@ +--- +title: Ana dizini taşı +description: "~/.failproofai dosyasını bu sürümün konuştuğu düzene getir ve önce ne olacağını gör" +--- + +```bash +failproofai migrate --dry-run # planı yazdır, hiçbir şey değiştirme +failproofai migrate # çalıştır +``` + +Bunu yazan çoğu insan hiç olmaz. Bir yükseltmeden sonra ilk komutta kendi kendine çalışır ve [`failproofai update`](/tr/cli/update) bunu içerir. Önce planı görmek istediğinde veya geçişi kendi başına çalıştırmak istediğinde doğrudan buna ulaş. + +## Sürüme değil düzene göre anahtarlanmış + +`~/.failproofai/VERSION` bir **düzen** numarası kaydeder — sürümün şekli değil, dizinin şekli. Geçişler bu numaraya göre anahtarlanır, bu da uzun bir boşluğu ucuz yapar: + +- npm sürümleri her sürümde değişir, iki düzen arasında düzinelerce tane vardır. +- Yani **hiçbir düzen değişikliği** olmadan otuz sürümü atlayan bir makine **otuz** boş işlem değil, **sıfır** geçiş çalıştırır. +- Ve bir kerede birkaç düzeni atlayan bir makine her adımı sırasıyla çalıştırır, her adım sadece kendi iki ucunu bilir. + +Bu önemlidir çünkü npm kendi başına yüklü bir paketi güncelleyemez. Bir makine aylar boyunca bir sürüme sabitlenmiş olup sonra birkaç düzeni atlaması normal olay, egzotik olay değildir. + +## Kuru çalışma + +`--dry-run` tam zinciri ve önce kaydedilecek dosyaları yazdırır ve hiçbir şeyi değiştirmez — hiçbir geçiş, hiçbir yedekleme, hiçbir defter girişi: + +``` +Diskte Düzen 2; bu derleme 3'ü konuşuyor. +1 adım(lar) çalışacak: + 2 → 3 düzen 2 → 3: config.toml ve credentials.toml JSON'a taşı, custom-policies/ + politikaların geri yukarısına taşı, politika yapılandırmasını kökün altında iç içe yerleştir + +Bunlar ilk olarak ~/.failproofai/migrations/backup-layout2 içine kopyalanacak: + VERSION + config.toml + credentials.toml +``` + +## Neyin taşındığı ve neyin yeniden oluşturulduğu + +Ana dizindeki her yol ne tür veri tuttuğunu bildiri ve bu bir geçişin bunu atıp atabileceğini belirler. Kural: **türetilmiş ve yeniden getirilebilir atılabilir; yazdığın her şey, henüz teslim edilmemiş her şey ve makinayı tanımlayan her şey taşınır.** + +| Taşınan | Yeniden oluşturulan veya yeniden getirilen | +|---|---| +| `config.json` — ayarlar, `daemon.configured`, ekstra yakalama yolları | Denetim önbelleği | +| `credentials.json` — bulut kaydınız | Bulut tarafından yönetilen dağıtımlar (sonraki yoklamada yeniden getirilir ve özet doğrulanır) | +| `policies-config.json` — politika seçiminiz ve parametreleri | Daemon çalışma durumu | +| `policies/` — kendi politika dosyalarınız ve içe aktardıkları yardımcılar | | +| `hook-activity/` — panonun okuduğu karar günlüğü | | +| Hala yüklenmek üzere kuyruğa alınmış teslim edilmemiş olaylar | | +| `cursors/` — toplayıcı filigranları | | +| `bin/` içindeki daemon ikili dosyası | | + + + Teslim edilmemiş olaylar atılmaktan ziyade taşınır çünkü kayıp kalıcı olur, yavaş değil: toplayıcının filigranı spoolda oturmuş herhangi bir şeyin ötesine geçmiştir, bu nedenle hiçbir şey bu aralığı bir transkripsiyonda asla okumazdı. Geçiş ayrıca daemon'u bitirdikten sonra spoolanmış olanı hemen teslim etmesini söyler, bu nedenle normal sonuç taşıacak hiçbir şeyin kalmamasıdır. + + +Daha *yeni* bir sürümün `config.json`, `credentials.json` veya `policies-config.json` içine yazdığı anahtarlar da eski bir okuyucu tarafından atılmaktan ziyade korunur. + +## Bıraktığı kayıt + +``` +~/.failproofai/migrations/ + applied.json her adım için bir giriş: düzen, CLI, zaman damgası, süre, sonuç + backup-layout/ ilk adımdan önce alınan yenisiyle değiştirilemeyecek dosyaların kopyaları +``` + +`applied.json`, "bu makine gerçekte neyi geçti" sorusunun cevabıdır — bir yükseltmeden sonra bir şey yanlış göründüğünde sormaya değer ilk soru. Bunu bir hata raporuna ekle. + +Yedekleme, açık tasarım gereği geçiş herhangi bir şeyi yenisiyle değiştirilemez bir şeyi silmediğinden, tüm dizinin kopyası olmak yerine kasıtlı olarak küçüktür, bu nedenle sigorta olması değer olan bir *adımdaki kusur*, ve bu birkaç dosya böyle bir kusuru kırpacak yerdir. + +## Bir adım başarısız olursa + +Zincir orada durur. `VERSION` yalnızca tamamlanan bir adım tarafından damgalanır, bu nedenle ana dizin eski düzeniyle işaretlenir ve sonraki komut bunu yeniden dener — bir ana dizin kısmi bir geçişin gücüne dayanarak asla güncel işaretlenmez. Adım `applied.json` içinde `"ok": false` ile kaydedilir ve yedekleme alındığı yerdir. + +## Daha yeni bir ana dizin geçiş yapılmaz, reddedilir + +Eğer `~/.failproofai/` failproofai'nin çalıştırdığından **daha yeni** bir sürümü tarafından yazılmışsa, komut durur ve bunun yerine yükseltmeyi söyler. Bu veri iyidir ve daha yeni bir CLI bunu okur; bundan "ileri" geçiş yapılması var olan bir şey değildir ve bunu sıfırlamak kurtarılabilir bir şeyi yok ederdi. + +``` +Bu makinenin failproofai dizini daha yeni bir sürüm (düzen 4; bu derleme 3'ü konuşuyor) +tarafından yazılmış. Geçiş yapmak yerine yükseltle: + npm install -g failproofai@latest +``` + +Daemon aynı kuralı uygular: `failproofaid` konuşmadığı bir düzene karşı başlatılmayı reddeder, taşınmış yolları okuyup yazmak yerine. \ No newline at end of file diff --git a/docs/tr/cli/remove-policies.mdx b/docs/tr/cli/remove-policies.mdx index cfa9b528..3f113fee 100644 --- a/docs/tr/cli/remove-policies.mdx +++ b/docs/tr/cli/remove-policies.mdx @@ -1,5 +1,5 @@ --- -title: Politikaları kaldır +title: Politikaları kaldırma description: "Claude Code'un ayarlarından hook girdilerini kaldırın" --- @@ -15,29 +15,29 @@ Takma adlar: `failproofai p -u` | Bayrak | Açıklama | |------|-------------| -| `--scope user` | Genel ayarlardan kaldırın (varsayılan) | -| `--scope project` | Proje ayarlarından kaldırın | -| `--scope local` | Yerel ayarlardan kaldırın | -| `--scope all` | Tüm kapsamlardan aynı anda kaldırın | -| `--custom` / `-c` | Yapılandırmadaki `customPoliciesPath` öğesini temizleyin | +| `--scope user` | Genel ayarlardan kaldırır (varsayılan) | +| `--scope project` | Proje ayarlarından kaldırır | +| `--scope local` | Yerel ayarlardan kaldırır | +| `--scope all` | Tüm kapsamlardan aynı anda kaldırır | +| `--custom` / `-c` | Konfigürasyondan `customPoliciesPath` öğesini temizler | ## Davranış - **Politika adı yok** - ayarlar dosyasından tüm failproofai hook girdilerini kaldırır -- **Belirli adlar** - bu politikaları devre dışı bırakır ancak hookları yüklü tutar +- **Belirli adlar** - bu politikaları devre dışı bırakır ancak hook'ları yüklü tutar ## Örnekler ```bash -# Tüm hookları genel olarak kaldırın +# Tüm hook'ları genel olarak kaldırır failproofai policies --uninstall -# Belirli bir politikayı devre dışı bırakın (hookları yüklü tutar) +# Belirli bir politikayı devre dışı bırakır (hook'ları yüklü tutar) failproofai policies --uninstall block-sudo -# Hookları her kapsamdan kaldırın +# Hook'ları her kapsamdan kaldırır failproofai policies --uninstall --scope all -# Özel politikalar yolunu temizleyin +# Özel politikalar yolunu temizler failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/tr/cli/update.mdx b/docs/tr/cli/update.mdx new file mode 100644 index 00000000..89b93e50 --- /dev/null +++ b/docs/tr/cli/update.mdx @@ -0,0 +1,64 @@ +--- +title: Yükseltmeden sonra güncelleme +description: "Yükseltmenin npm'nin yapamadığı yarısını tamamlayın: ana dizini geçirin ve daemon'u eşleştirin" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +Tüm yükseltme işlemi bu kadar. `npm` CLI'yi değiştirir; `failproofai update` geri kalanını yapar. + +## İkinci komutun neden var olduğu + +`npm install -g` bir şeyi değiştirir — CLI'yi. failproofai kurulumunun diğer iki parçası kasıtlı olarak paketin dışında bulunur ve npm çalıştığında hiçbiri yer değiştirmez: + +- **`~/.failproofai/`**, ayarlarınız, bulut kaydı, politika seçimi ve geçmişi. Yeni bir sürüm bunu farklı şekilde organize edebilir ve yeniden organizasyon her iki şekli de bilen kod tarafından yapılmalıdır. +- **`failproofaid` daemon ikili dosyası**, `~/.failproofai/bin/failproofaid-` konumunda. Kasıtlı olarak `node_modules` içinde *değildir*: çalışan bir hizmetin altındaki dosyayı değiştiren bir yükseltme, canlı bir daemon'u farklı kaynaktan oluşturulmuş bir ikiliye yeniden işaret edecek ve paketi kaldırmak onu hizmetin altından silecek ve sonrasında her açılışta kilitlenecektir. + +Yani `npm install -g` tek başına çalıştırıldığında, CLI yeni ve daemon eski kalır. `failproofaid` konuşmadığı bir ana dizin düzeniyle başlatmayı reddeder — bu uyumsuzluğun sessiz versiyonu yerine gürültülü versiyonudur — bu nedenle iki yarı bir araya getirilmesi gerekir. `failproofai update` bu adımdır. + +## Ne yapar + + + + `~/.failproofai/VERSION` içinde kaydedilen düzeni okur ve onu bu sürümün konuştuğu düzene getiren adımları çalıştırır. Genellikle hiç yok — [`failproofai migrate`](/tr/cli/migrate) konusuna bakın. + + + npm'nin zaten indirdiği platform paketinden mümkün olduğunda (ağ yok), aksi takdirde bu tam sürüm için yayın varlığından, kullanılmadan önce SHA-256 doğrulanır. + + + Varsayılmak yerine provalanır — bir hizmet yöneticisi fork edildiği an bir süreci aktif olarak bildirir, bu işçi aynı değildir. + + + +## Seçenekler + +| Bayrak | Etki | +|--------|------| +| `--no-daemon` | Daemon'u mevcut sürümünde bırakarak yalnızca ana dizini geçirin. | + + + `--no-daemon` sürüm farklılığı olan bir daemon'u yerinde bırakır. Daemon gerektirecek şekilde yapılandırılmış bir makinede, daemon cevap veremezse her hook olayı **kapalı başarısız olur** — ve geçişi yapılan bir ana dizine karşı başlatmayı reddeden daemon cevap veremez. Daemon yarısını çalıştırmasına izin vermeyi tercih edin. + + +## Bir şey yanlış giderse + +Komut sıfırdan farklı bir değerle çıkılır ve hangi yarının başarısız olduğunu söyler. Bilmeye değer iki durum: + +- **Bir geçiş adımı tamamlanmadı.** Ana dizin *eski* düzeniyle işaretlenmiş olarak bırakılır, bu nedenle sonraki komut onu yeniden dener — kısmi bir geçişin gücüne dayanarak hiçbir ana dizin hiçbir zaman mevcut olarak işaretlenmez. Ayarlarınız ve kaydınızın kopyaları, `~/.failproofai/migrations/backup-layout/` içinde, her şey çalışmadan önce kaydedildi. +- **Daemon şifre olmadan yeniden başlatılamadı.** `sudo -n` kasıtlı olarak kullanılır, bu nedenle hiçbir şey bir ilerleme görüntüsü altından hiçbir zaman uyarı yapmaz. Komut kendiniz çalıştırmanız için tam satırı yazdırır. + + + Burada hiçbir şey etkileşimli kurulum sihirbazına ihtiyaç duymaz. Ayarlarınız, bulut kaydı ve politika seçimi bir yükseltmeden sağ kalır, bu nedenle geçişi yapılan bir makine tam olarak önceki gibi uygulanır — bu oturan hiç kimse olmayan makinelerde en önemlidir: bir CI koşucusu, bir filo kutusu, başsız bir ağ geçidi. + + +## Otomatikleştirme + +`failproofai update` etkileşimsizdir ve yapılacak bir şey olmadığında çalıştırmak güvenlidir — "geçişe gerek yoktu" bildirir ve 0 ile çıkılır. Bunu bir sağlama betiğinde veya Dockerfile'de her yükseltmeden sonra koymak amaçlanan kullanımdır: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(Henüz yeniden başlatılacak bir hizmet olmayan bir görüntü derlemesinde `--no-daemon`.) \ No newline at end of file diff --git a/docs/tr/configuration.mdx b/docs/tr/configuration.mdx index ec4c0c23..ae1c50a2 100644 --- a/docs/tr/configuration.mdx +++ b/docs/tr/configuration.mdx @@ -1,25 +1,24 @@ --- ---- -title: Konfigürasyon -description: "Konfigürasyon dosyası formatı, üç kapsamlı sistem ve birleştirme kuralları" +title: Yapılandırma +description: "Config dosya formatı, üç kapsamlı sistem ve birleştirme kuralları" icon: gear --- -failproofai, hangi politikaların aktif olduğunu, nasıl davrandıklarını ve özel politikaların nereden yükleneceğini kontrol etmek için JSON konfigürasyon dosyalarını kullanır. Konfigürasyon, takımınızla paylaşmak için tasarlanmıştır - bunu deponuza gönderin ve her geliştirici aynı aracı güvenlik ağını alır. +failproofai, hangi politikaların aktif olduğunu, nasıl davrandıklarını ve özel politikaların nereden yüklendiğini kontrol etmek için JSON yapılandırma dosyalarını kullanır. Yapılandırma, ekibinizle paylaşmak için tasarlanmıştır - bunu deponuza işleyin ve her geliştirici aynı aracı güvenliğine sahip olur. --- -## Konfigürasyon kapsamları +## Yapılandırma kapsamları -Üç konfigürasyon kapsamı vardır ve öncelik sırasına göre değerlendirilir: +Öncelik sırasına göre değerlendirilen üç yapılandırma kapsamı vardır: | Kapsam | Dosya yolu | Amaç | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | Depo başına ayarlar, sürüm denetimine kaydedilir | -| **local** | `.failproofai/policies-config.local.json` | Kişisel depo başına geçersiz kılmalar, gitignored | -| **global** | `~/.failproofai/policies-config.json` | Tüm projeler arasında kullanıcı düzeyinde varsayılanlar | +| **project** | `.failproofai/policies-config.json` | Depo başına ayarlar, sürüm kontrolüne işlenir | +| **local** | `.failproofai/policies-config.local.json` | Kişisel depo başına geçersiz kılmalar, gitignore'lanmış | +| **global** | `~/.failproofai/policies-config.json` | Tüm projeler arasında kullanıcı düzeyi varsayılanları | -failproofai bir kanca olayı aldığında, geçerli çalışma dizini için var olan üç dosyayı yükler ve birleştirir. +failproofai bir hook olayı aldığında, geçerli çalışma dizini için var olan üç dosyanın tümünü yükler ve birleştirir. ### Birleştirme kuralları @@ -30,7 +29,7 @@ project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← tekilleştirilmiş birleşim +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← çoğaltmalar kaldırılmış birleşim ``` **`policyParams`** - belirli bir politika için parametreleri tanımlayan ilk kapsam tamamen kazanır. Bir politikanın parametreleri içinde derin birleştirme yoktur. @@ -43,22 +42,22 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project kazanır, glo ``` ```text -project: (block-sudo girdisi yok) -local: (block-sudo girdisi yok) +project: (block-sudo girişi yok) +local: (block-sudo girişi yok) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← global'e düşer ``` -**`customPoliciesPaths` / `customPoliciesPath`** - her iki formu tanımlayan ilk kapsam kazanır. +**`customPoliciesPaths` / `customPoliciesPath`** - her iki formu da tanımlayan ilk kapsam kazanır. -**`disabledCustomPolicies`** - tüm kapsamlar arasında birleşim. Pano, bir bireysel politikayı açık veya kural politikası dosyasından kapatırken burada kaynakla nitelendirilen bir kimlik yazar. Listelenmemiş politikalar varsayılan olarak etkindir; kimlikler kaynak dosyasını içerir, böylece birden fazla dosyada aynı adlı politikalar bağımsız olarak kontrol edilebilir. +**`disabledCustomPolicies`** - tüm kapsamlara göre birleşim. Pano, bir politikayı açık veya uyum politikası dosyasından kapatırken buraya kaynak nitelemeli bir kimlik yazar. Listelenmemiş politikalar varsayılan olarak etkindir; kimlikler kaynak dosyayı içerir, bu nedenle birden çok dosyadaki aynı adlı politikalar bağımsız olarak kontrol edilebilir. -**`llm`** - tanımlayan ilk kapsam kazanır. +**`llm`** - bunu tanımlayan ilk kapsam kazanır. --- -## Konfigürasyon dosyası formatı +## Config dosya formatı ```json { @@ -105,37 +104,37 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global'e düşer Tür: `string[]` -Etkinleştirilecek politika adlarının listesi. Adlar, `failproofai policies` tarafından gösterilen politika tanımlayıcılarına tam olarak eşleşmelidir. Tam liste için [Yerleşik Politikalar](/tr/built-in-policies) sayfasına bakın. +Etkinleştirilecek politika adlarının listesi. Adlar, `failproofai policies` tarafından gösterilen politika tanımlayıcılarıyla tam olarak eşleşmelidir. Tam liste için [Built-in Policies](/tr/built-in-policies) bölümüne bakın. -`enabledPolicies` içinde olmayan politikalar, `policyParams` içinde girdileri olsa bile, etkin değildir. +`enabledPolicies` içinde olmayan politikalar, `policyParams` içinde girdileri olsa bile, deaktif kalır. ### `policyParams` Tür: `Record>` -Politika başına parametre geçersiz kılmaları. Dış anahtar politika adıdır; iç anahtarlar politikaya özeldir. Her politika, [Yerleşik Politikalar](/tr/built-in-policies) sayfasında mevcut parametrelerini belgeler. +Politika başına parametre geçersiz kılmaları. Dış anahtar politika adıdır; iç anahtarlar politikaya özgüdür. Her politika, [Built-in Policies](/tr/built-in-policies) içinde mevcut parametrelerini belgelemektedir. -Bir politikanın parametreleri varsa ancak bunları belirtmezseniz, politikanın yerleşik varsayılanları kullanılır. `policyParams` yapılandırmayan kullanıcılar, önceki sürümlerle özdeş davranış alırlar. +Bir politikanın parametreleri varsa ancak siz onları belirtmezseniz, politikanın yerleşik varsayılanları kullanılır. `policyParams` hiç yapılandırmayan kullanıcılar önceki sürümlerle aynı davranışı alır. -Bir politikanın parametreler bloğu içindeki bilinmeyen anahtarlar, kanca ateşlemesi sırasında sessizce yoksayılır, ancak `failproofai policies` komutunu çalıştırdığınızda uyarı olarak işaretlenir. +Bir politikanın parametre bloğu içindeki bilinmeyen anahtarlar, hook ateşlemesinde sessizce yoksayılır ancak `failproofai policies` çalıştırdığınızda uyarı olarak işaretlenir. -#### `hint` (kesişen alan) +#### `hint` (çapraz kesme) Tür: `string` (isteğe bağlı) -Bir politika `deny` veya `instruct` döndürdüğünde nedene eklenen bir ileti. Politikanın kendisini değiştirmeden Claude'a işlem yapılabilir rehberlik vermek için kullanın. +Bir politika `deny` veya `instruct` döndürdüğünde nedene eklenen bir ileti. Bunu, politikanın kendisini değiştirmeden Claude'a işlem yapılabilir rehberlik vermek için kullanın. -Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), proje kuralı (`.failproofai-project/`) veya kullanıcı kuralı (`.failproofai-user/`). +Her politika türü ile çalışır — yerleşik, özel (`custom/`), proje kuralı (`.failproofai-project/`) veya kullanıcı kuralı (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "Bunun yerine yeni bir dal oluşturmayı deneyin." + "hint": "Bunun yerine yeni bir branch oluşturmayı deneyin." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "sudo olmadan doğrudan apt-get kullanın." + "hint": "Sudo olmadan apt-get'i doğrudan kullanın." }, "custom/my-policy": { "hint": "İlk olarak kullanıcıdan onay isteyin." @@ -144,47 +143,46 @@ Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), pr } ``` -`block-force-push` reddettiğinde, Claude şunu görür: *"Force-push engellenmiştir. Bunun yerine yeni bir dal oluşturmayı deneyin."* +`block-force-push` reddedildiğinde, Claude şu mesajı görür: *"Force-push engellenmektedir. Bunun yerine yeni bir branch oluşturmayı deneyin."* -Dize olmayan değerler ve boş dizeler sessizce yoksayılır. `hint` ayarlanmamışsa, davranış değişmez (geriye doğru uyumlu). +Dize olmayan değerler ve boş dizeler sessizce yoksayılır. `hint` ayarlanmamışsa, davranış değişmez (geriye dönük uyumlu). ### `customPoliciesPath` Tür: `string` (mutlak yol) -Özel kanca politikaları içeren bir JavaScript dosyasının yolu. Bu, `failproofai policies --install --custom ` tarafından otomatik olarak ayarlanır (yol depolanmadan önce mutlak olarak çözümlenir). +Özel hook politikaları içeren bir JavaScript dosyasına giden yol. Bu, `failproofai policies --install --custom ` tarafından otomatik olarak ayarlanır (yol depolanmadan önce mutlak değere çözülür). -Dosya her kanca olayında taze yüklenir - önbelleğe alma yoktur. Yazarlık ayrıntıları için [Özel Politikalar](/tr/custom-policies) sayfasına bakın. +Dosya, her hook olayında yeni yüklenir - hiçbir önbellek yoktur. Yazım ayrıntıları için [Custom Policies](/tr/custom-policies) bölümüne bakın. -### Kural tabanlı politikalar +### Uyum tabanlı politikalar Açık `customPoliciesPath` ek olarak, failproofai `.failproofai/policies/` dizinlerinden politika dosyalarını otomatik olarak keşfeder ve yükler: | Düzey | Dizin | Kapsam | |-------|-----------|-------| -| Proje | `.failproofai/policies/` | Sürüm denetimi yoluyla takımla paylaşılır | -| Kullanıcı | `~/.failproofai/policies/custom-policies/` | Kişisel, tüm projeler için geçerlidir | +| Proje | `.failproofai/policies/` | Sürüm kontrolü aracılığıyla takımla paylaşılmış | +| Kullanıcı | `~/.failproofai/policies/` | Kişisel, tüm projelere uygulanır | - Kullanıcı düzeyinde dizin, ev dizini yeniden organizasyonunda bir seviye aşağı taşındı. - Eski `~/.failproofai/policies/` yolunda bırakılan dosyalar, yükseltmeden sonra herhangi bir `failproofai` - komutunu çalıştırdığınızda `custom-policies/` içine otomatik olarak taşınır ve komut hangi dosyaları - taşıdığını söyler. + Politikalarınızı doğrudan `~/.failproofai/policies/` içine yerleştirin. Yanlarında bulunan `cloud-policies/` klasörü, kuruluşunuzun bu makineye dağıttığı politikaları içerir — keşif alt dizinlere inmez, bu nedenle hiçbir zaman taranmaz ve `policies/` içine koyduğunuz hiçbir şey onunla çakışamaz. + + `~/.failproofai/policies/custom-policies/` kullanan bir sürümden yükseltiyorsanız, o klasördeki her şey — politika dosyalarınız, içe aktardıkları `lib/` yardımcıları ve okudukları veri dosyaları — bir `failproofai` komutunu ilk kez çalıştırdığınızda otomatik olarak geri taşınır ve komut neyi taşıdığını söyler. **Dosya eşleştirmesi:** Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir (örn. `security-policies.mjs`, `workflow-policies.js`). Dizindeki diğer dosyalar yoksayılır. -**Konfigürasyon gerekmez:** Kural politikaları `policies-config.json` içinde girdiler gerektirmez. Dosyaları dizine bırakın ve sonraki kanca olayında alınırlar. +**Config gerekmez:** Uyum politikaları `policies-config.json` içinde herhangi bir giriş gerektirmez. Dosyaları dizine bırakın ve sonraki hook olayında toplanırlar. -**Birleşim yüklemesi:** Hem proje hem de kullanıcı kural dizinleri taranır. Her iki düzeyden tüm eşleşen dosyalar yüklenir (`customPoliciesPath` ilk-kapsam-kazanır kullanan aksine). +**Birleşim yüklemesi:** Hem proje hem de kullanıcı uyum dizinleri taranır. Her iki düzeyden eşleşen tüm dosyalar yüklenir (`customPoliciesPath` ilk kapsamı kazanan kullandığından farklı). -Daha fazla ayrıntı ve örnekler için [Özel Politikalar](/tr/custom-policies) sayfasına bakın. +Daha fazla ayrıntı ve örnekler için [Custom Policies](/tr/custom-policies) bölümüne bakın. ### `llm` Tür: `object` (isteğe bağlı) -AI çağrıları yapan politikalar için LLM istemci konfigürasyonu. Çoğu kurulum için gerekli değildir. +AI çağrıları yapan politikalar için LLM istemci yapılandırması. Çoğu kurulum için gerekli değildir. ```json { @@ -197,26 +195,26 @@ AI çağrıları yapan politikalar için LLM istemci konfigürasyonu. Çoğu kur --- -## CLI'den konfigürasyonu yönetme +## CLI'dan yapılandırmayı yönetme -`policies --install` ve `policies --uninstall` komutları aracı CLI'nizin kanca ayarları dosyasına yazarken (kanca giriş noktaları), `policies-config.json` doğrudan yönettiğiniz dosyadır. İkisi ayrıdır: +`policies --install` ve `policies --uninstall` komutları, aracı CLI'nızın hook ayarları dosyasına (hook giriş noktaları) yazarken, `policies-config.json` doğrudan yönettiğiniz dosyadır. İkisi ayrıdır: -- **Aracı CLI ayarları** — aracıya her araç kullanımında `failproofai --hook ` çağırmasını söyler: +- **Aracı CLI ayarları** — aracıya her araç kullanımında `failproofai --hook ` çağrısını söyler: - **Claude Code**: `~/.claude/settings.json` (kullanıcı), `/.claude/settings.json` (proje), `/.claude/settings.local.json` (yerel) - - **OpenAI Codex**: `~/.codex/hooks.json` (kullanıcı), `/.codex/hooks.json` (proje) — Codex yerel kapsama sahip değildir - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (kullanıcı), `/.github/hooks/failproofai.json` (proje) — Copilot yerel kapsama sahip değildir. Kanca girdileri Copilot'un OS tarafından anahtarlanan `bash`/`powershell` komut alanlarını `timeoutSec` ile kullanır; dosya üst düzey `version: 1` işaretleyicisini taşır. Copilot CLI desteği, halk belgeleri belirtmeyen `events.jsonl` kayıt şemasını (pano) daha gerçek dünya oturumlarına karşı doğrularken **beta**'dır. **VS Code Copilot Chat aracı modu (Önizleme)**, `.github/hooks/*.json`, `~/.copilot/hooks/*.json` ve `~/.claude/settings.json` (tarafından yönetilen `chat.hookFilesLocations` ayarı tarafından) kanca yapılandırmalarını aynı Claude şekilli `{hookSpecificOutput:{permissionDecision:"deny",…}}` sözleşmesini kullanarak okur — tam olarak bu `copilot` entegrasyonunun ve `claude` entegrasyonunun (`~/.claude/settings.json`) yazması gereken yollar, bu nedenle `failproofai policies --install --cli copilot` (veya `--cli claude`) **VS Code aracı modunda zaten uygular** ayrı `vscode` entegrasyonu gerekmeden (VS Code'un keşif günlüklerinden canlı olarak onaylandı). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (kullanıcı), `/.cursor/hooks.json` (proje) — Cursor yerel kapsama sahip değildir. Kanca girdileri Claude şekilli `{type, command, timeout}` formunu kullanır (`bash`/`powershell` bölünümü yoktur), ancak Cursor'un [kancalar şemasına](https://cursor.com/docs/hooks) göre düz bir dizi başına camelCase olay anahtarları (`preToolUse`, `beforeSubmitPrompt`, …) altında saklanır; dosya üst düzey `version: 1` işaretleyicisini taşır. İşleyici camelCase → PascalCase'i `CURSOR_EVENT_MAP` aracılığıyla normalleştirir; bu nedenle mevcut yerleşik politikalar değişmeden ateşlenir. Cursor Agent desteği, Cursor'un disk üzerindeki transkript formatını (halk belgelerde belirtilmeyen) daha gerçek dünya yüklemelerine karşı doğrularken **beta**'dır. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (kullanıcı), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proje) — OpenCode yerel kapsama sahip değildir. Diğer beş CLI'den farklı olarak, OpenCode **harici komut kanca sistemi yok**: `plugin: []` dizisine açıkça kayıtlı olan işlem içi JS/TS eklentileri yükler `opencode.json` içinde (`.opencode/plugins/` otomatik keşfi eklentilerin opencode v1.14.33'te nasıl yükleneceği **değildir**). Yükleme, failproofai ikili dosyasını alt işlem çağıran ve ikili dosyanın Claude şekilli JSON yanıtını eklenti semantiğine çeviren küçük bir oluşturulan eklenti parçası bırakır: araç olayı reddi için `throw new Error()` (araç çağrısını iptal eder), `client.session.prompt(...)` `instruct` ve sıra sonu `Stop` / `SubagentStop` reddi için (`session.idle` bildir yapısı olduğu ve bundan atma yapısı bir işlemi için — `instruct` için (reddi nedeni bir sonraki kullanıcı iletisi olarak gönderilir — tek zorla yeniden deneme kanalı) ve izin vermeyi allow için no-op (`OPENCODE_TOOL_INPUT_MAP` aracılığıyla `filePath` → `file_path`, `oldString` → `old_string` gibi) normalleştirir, böylece `block-read-outside-cwd`, `block-env-files` ve `block-secrets-write` gibi yol denetimi yerleşik öğeleri OpenCode araç çağrılarında değişmeden ateşlenir. Oturumlar opencode'un SQLite DB'sinde `~/.local/share/opencode/opencode.db` adında yaşar; panonun oturum görüntüleyeni bunları `opencode db --format json` ve `opencode export ` aracılığıyla okur. OpenCode desteği davranış sürümler arasında ve daha gerçek dünya oturumlarına karşı doğrulanırken **beta**'dır. [OpenCode eklentileri belgelerine](https://opencode.ai/docs/plugins/) bakın. - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (kullanıcı), `/.pi/settings.json` (proje) — Pi yerel kapsama sahip değildir. Pi başlangıçta TypeScript uzantı paketlerini yükler; ayarlar dosyası düz bir dize dizisidir `{"packages": ["./relative/path", …]}`. failproofai, paketlenen `pi-extension/` dizinine işaret eden tek bir paketler-dizisi girdisi yazar. Uzantı dahili olarak Pi'nin `tool_call` / `user_bash` / `input` / `session_start` olaylarına abone olur ve `failproofai --hook --cli pi` öğesine çıkar; işleyici alt çizgi_alt_snek_kasa → PascalCase'i `PI_EVENT_MAP` aracılığıyla normalleştirir, böylece mevcut yerleşik politikalar değişmeden ateşlenir. Araç giriş argümanları da `PI_TOOL_INPUT_MAP` aracılığıyla normalleştirilir (Pi'nin Read / Write / Edit, `file_path` yerine `path` teslim eder; üst düzey anahtarı eşlemek `block-env-files` ve `block-secrets-write` ateşlemesine izin verir — `block-read-outside-cwd` zaten bir `path` geri dönüşüne sahipti). Pi desteği Pi'nin uzantı API'si ve oturum günlüğü düzeni stabilize olurken **beta**'dır. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**yalnızca kullanıcı kapsamı** — Hermes proje/yerel yapılandırmaya sahip değildir). Hermes bir Slack/Telegram **ağ geçidi**dir, bu nedenle bir yükleme her platformdan (Slack/Telegram/cli/cron) araç çağrılarını **ve** iç alt aracıları keser. Kanca girdileri, Hermes'in snek_kasa olayları (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) tarafından anahtarlanan `hooks:` haritası altında bir `{command, timeout}` çiftidir; işleyici olayları `HERMES_EVENT_MAP` aracılığıyla ve araç adlarını `HERMES_TOOL_MAP` aracılığıyla normalleştirir, böylece yerleşik politikalar değişmeden ateşlenir. Yapılandırma, yorum koruyan bir YAML `Document` gidiş dönüş yapılarak düzenlenir, bu nedenle operatörün diğer ayarları kalır ve yükleme `hooks_auto_accept: true` ayarlar, böylece başsız ağ geçidi (TTY yok) kancaları izin istemi olmadan çalıştırır. Değerlendirici Hermes'in `{"decision":"block","reason"}` stdout sözleşmesini yayar (Hermes çıkış kodlarını yoksayar). **Sınırlamalar:** Hermes sıra sonu `Stop` olayına sahip değildir, bu nedenle `require-*-before-stop` yerleşik öğeleri hiçbir zaman onun için ateşlenmez (inapplicable, kırılmış değil); `instruct` günlüğe kaydedilen notla allow öğesine düşer (ek içerik kanalı yoktur); ve çıkış sırrı redaksiyonu (`sanitize-*`) kabuk kanca sözleşmesi üzerinde araç çıkışını yeniden yazamaz. Hermes, çevrimdışı bir **denetim** kaynağıdır — pano oturumlarını doğrudan `~/.hermes/state.db` adresinden okur. - - **OpenClaw (openclaw ağ geçidi)**: `~/.openclaw/openclaw.json` (**yalnızca kullanıcı kapsamı** — OpenClaw proje/yerel yapılandırmaya sahip değildir). Hermes gibi, OpenClaw kendi kendine barındırılan çok kanallı bir **ağ geçidi**dir, bu nedenle bir yükleme her kanaldan araç çağrılarını ve iç alt aracılarını keser. Uygulama OpenClaw'un **işlem içi eklenti kancastları** aracılığıyla çalışır (dosya tabanlı iç kancastları yalnızca gözlem amaçlıdır ve engelleyemez), bu nedenle — OpenCode/Pi gibi — failproofai statik bir `openclaw-plugin/` paketi gönderir; bu, failproofai ikili dosyasını eş zamansız olarak çıkarır ve kararı çevirir. Yükleme, gönderilen eklenti dizinini `openclaw.json`'nin `plugins.load.paths[]` içinde kaydeder ve `plugins.entries.failproofai` altında etkinleştirir (`hooks.allowConversationAccess: true` ile, ham konuşma kancastları için gereklidir). Değerlendirici düz bir `{permission, reason}` kararı yayar ve şim bunu her kancanın yerel dönüş şekline eşler: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), ve `before_agent_finalize → {action:"revise", reason}` (**Stop** — gerçek bir sıra sonu kapısı, bu nedenle `require-*-before-stop` yerleşik öğeleri **uygular**, Hermes'in aksine). Olaylar ve araç adları ikili tarafında `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) aracılığıyla normalleştirilir, böylece yerleşik politikalar değişmeden ateşlenir; şim herhangi bir çıkarma/ayrıştırma/zaman aşımı hatasında açık başarısız olur. OpenClaw, çevrimdışı bir **denetim** kaynağıdır — pano JSONL oturumlarını `~/.openclaw/agents//sessions/.jsonl` adresinden okur. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (kullanıcı), `/.factory/hooks.json` (proje) — Factory yerel kapsama sahip değildir. droid, Claude stilinde harici komut kanca sistemini gönderir, ancak droid v0.171.0'a karşı canlı olarak doğrulanmış iki tuhaflık vardır: (1) olay adları `hooks.json` **üst düzeyinde** yaşar — **bir `"hooks"` sarıcı yoktur** (droid birini reddeder); araç olayları (`PreToolUse`/`PostToolUse`) `"matcher": "*"` taşır, araç olmayan olaylar bunu atlar. (2) Reddi, kanca **çıkış kodu 2 + stderr** tarafından yapılır, JSON kararı değil — değerlendirici'nin `factory` dalı araç/istem olayları için çıkış 2 ve sıra sonu `Stop` olayında `{decision:"block", reason}` döndürür (droid'in tek zorla yeniden deneme kanalı). Olaylar zaten PascalCase'dir (olay eşlemesi yoktur) ve yük Claude snek_kasa'dır; yalnızca araç adları `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …) aracılığıyla normalleştirilir. Factory, çevrimdışı bir **denetim** kaynağıdır — pano disk üzerindeki JSONL oturumlarını `~/.factory/sessions//.jsonl` adresinden okur. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (kullanıcı), `/.devin/config.json` (proje) — Devin yerel kapsama sahip değildir. Devin bir **saf Claude klonudur** devin v3000.1.27'ye karşı canlı olarak doğrulanmıştır: standart Claude `"hooks"` sarıcısı şemasını kullanır (yazma işlemleri korunan yollar, bu nedenle yapılandırma dosyasının diğer anahtarları — `org_id`, `theme_mode`, … — kalır), zaten PascalCase olay adları (olay eşlemesi, işleyici dalı yoktur) ve Claude snek_kasa stdin yükü (normalleştirme yoktur). Değerlendirici'nin `devin` dalı **her** olay için çıkış 0'da `{"decision":"block","reason"}` JSON ile reddeder; sıra sonu `Stop` olayında neden, `require-*-before-stop` yerleşik öğelerinin uygulanması için ZORUNLU İŞLEM zorla yeniden deneme ifadesini taşır. Yalnızca araç adları `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` zaten Canonical'dir) aracılığıyla normalleştirilir. Devin, çevrimdışı bir **denetim** kaynağıdır — pano SQLite oturumlarını `~/.local/share/devin/cli/sessions.db` adresinden okur (her `sessions` satırı gerçek bir `working_directory` taşır, bu nedenle oturumlar proje cwd tarafından gruplandırılır; Claude gibi). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (kullanıcı), `/.agents/hooks.json` (proje) — Antigravity yerel kapsama sahip değildir. Factory/Devin'in aksine, Antigravity agy v1.1.2'ye karşı canlı olarak doğrulanan **kendi** sözleşmesine sahiptir. `hooks.json`, **adlandırılmış kanca** şemasını kullanır: üst düzey anahtar bir kanca *adıdır* (`"failproofai"`), değeri olay→işleyiciler haritasıdır — araç olayları (`PreToolUse`/`PostToolUse`) işleyicileri `{matcher:"*", hooks:[…]}` içine sarmalanır, `PreInvocation`/`Stop` **düz** işleyici dizileridir (diğer adlandırılmış kancalar korunur). stdin yükü **camelCase protojson**'dur (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai bunu politikalar çalışmadan önce snek_kasa'ya normalleştirir ve `run_command`'in PascalCase argümanlarını (`CommandLine`/`Cwd`) `ANTIGRAVITY_TOOL_INPUT_MAP` aracılığıyla eşler. Değerlendirici'nin `antigravity` dalı Antigravity'nin **kendi** yanıt şekillerini kullanır: `{decision:"deny", reason}` araç/istemi engeller (çıkış 0), sıra sonu `Stop` olayında `{decision:"continue", reason}` döngüyü yeniden girer (bu nedenle `require-*-before-stop` yerleşik öğeleri uygularlar) ve `{injectSteps:[{ephemeralMessage}]}` `PreInvocation` (→ `UserPromptSubmit`) üzerine bir talimat enjekte eder. Araç adları `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …) aracılığıyla normalleştirilir. Antigravity, çevrimdışı bir **denetim** kaynağıdır — pano düz JSONL transkriptlerini `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` adresinden okur (konuşma dizini `conversation_summaries.db`'de). - - **Goose (kod adı goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (kullanıcı), `/.agents/plugins/failproofai/hooks/hooks.json` (proje) — Goose yerel kapsama sahip değildir. Uygulama Goose'un **kancalar** sistemini, çapraz aracı **Açık Eklentiler** spesifikasyonunu kullanır: yükleyici sadece `failproofai` eklenti dizinini bırakır ve Goose başlangıçta onu otomatik keşfeder (bunu `~/.config/goose/config.yaml`'ye kendi kendine kaydeder). `hooks.json`, üst düzey `"hooks"` sarıcı **içeren** Açık Eklentiler şemasını kullanır ve eşleyici **her olay için atlanır** — çıplak `"*"` hiçbir şeyinle eşleşmeyen geçersiz bir regex'tir (goose v1.43.0'ye karşı canlı olarak doğrulanan). Olay adları zaten PascalCase'dir (olay eşlemesi yoktur); stdin yükü `event`/`working_dir` kullanır; işleyici bunu `hook_event_name`/`cwd` için normalleştirir. Değerlendirici'nin `goose` dalı çıkış 0'da `{"decision":"block","reason"}` JSON ile reddeder, **`PreToolUse`** olayında onurlanır (goose ≥ v1.37.0'de gönderilen) — bu, kabuk aracı **ve temsilci seçilen alt aracılar içinde** ateşlenir, bu nedenle tek yeterli reddi noktasıdır; diğer herhangi bir kanca hatası **açık başarısız** olur. Goose, **`Stop` olayına sahip değildir**, bu nedenle `require-*-before-stop` yerleşik öğeleri uygulanmaz (Hermes'te olduğu gibi). Araç adları `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) ve yol anahtarları `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`) aracılığıyla normalleştirilir. Goose, çevrimdışı bir **denetim** kaynağıdır — pano SQLite oturumlarını `~/.local/share/goose/sessions/sessions.db` adresinden okur (her `sessions` satırı gerçek bir `working_dir` taşır, bu nedenle oturumlar proje cwd tarafından gruplandırılır; Devin gibi; `--no-session` karalama çalıştırmaları filtrelenir). -- **`policies-config.json`** — failproofai'ya hangi politikaları değerlendireceğini ve hangi parametrelerle (tüm aracı CLI'leri arasında paylaşılan) söyler - -Belirli bir aracıyı hedeflemek için `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` geçirin (boşlukla ayrılmış veya herhangi bir alt küme için tekrarlanan): + - **OpenAI Codex**: `~/.codex/hooks.json` (kullanıcı), `/.codex/hooks.json` (proje) — Codex'in yerel kapsamı yoktur + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (kullanıcı), `/.github/hooks/failproofai.json` (proje) — Copilot'un yerel kapsamı yoktur. Hook girdileri `timeoutSec` ile Copilot'un işletim sistemi anahtarlı `bash`/`powershell` komut alanlarını kullanır; dosya üst düzey `version: 1` belirtecini taşır. Copilot CLI desteği **beta** aşamasındadır, `events.jsonl` kayıt şemasını (genel belgeler belirtmez) daha fazla gerçek dünya oturumuna karşı doğruladığımız sürece. **VS Code Copilot Chat aracı modu (Önizleme)** hook yapılandırmaları `.github/hooks/*.json`, `~/.copilot/hooks/*.json` ve `~/.claude/settings.json` adreslerinden okur (`chat.hookFilesLocations` ayarı tarafından yönetilir) ve `claude` entegrasyonu (`~/.claude/settings.json`) tarafından yazılan tam yolları (doğrudan koddan doğrulanmıştır) kullanırken aynı Claude şeklindeki `{hookSpecificOutput:{permissionDecision:"deny",…}}` sözleşmesini kullanır, bu nedenle `failproofai policies --install --cli copilot` (veya `--cli claude`) **zaten VS Code aracı modunda** ek `vscode` entegrasyonuna ihtiyaç olmaksızın **uygulanır** (VS Code keşif günlüklerinden doğrulanmıştır). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (kullanıcı), `/.cursor/hooks.json` (proje) — Cursor'un yerel kapsamı yoktur. Hook girdileri Claude şeklindeki `{type, command, timeout}` formunu kullanır (`bash`/`powershell` bölünmesi yoktur) ancak Cursor'un [hooks şemasına](https://cursor.com/docs/hooks) göre düz bir dizi başına camelCase olay anahtarları altında depolanır (`preToolUse`, `beforeSubmitPrompt`, …); dosya üst düzey `version: 1` belirtecini taşır. İşleyici, `CURSOR_EVENT_MAP` aracılığıyla camelCase → PascalCase'i kanonik hale getirir, böylece mevcut yerleşik politikalar değişmeden ateşlenir. Cursor Agent desteği **beta** aşamasındadır, Cursor'un disk üzerindeki transkript formatını (genel belgeler belirtmez) daha fazla gerçek dünya yüklemesine karşı doğruladığımız sürece. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (kullanıcı), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proje) — OpenCode'un yerel kapsamı yoktur. Diğer beş CLI'nın aksine, OpenCode **harici komut hook sistemi yoktur**: açıkça `opencode.json` içindeki `plugin: []` dizisi aracılığıyla kaydedilen işlem içi JS/TS eklentilerini yükler (`.opencode/plugins/` adresinden otomatik keşif, opencode v1.14.33'te eklentilerin nasıl yüklendiği **değildir**). Yükleme, failproofai ikilisini alt işlemde çağıran ve ikili'nin Claude şekli JSON yanıtını eklenti semantiğine geri çeviren küçük bir oluşturulmuş eklenti parçası bırakır: araç olayı reddetme için `throw new Error()` (araç çağrısını iptal eder), `client.session.prompt(...)` hem `instruct` hem de `Stop` / `SubagentStop` reddetme (reddetme nedenini sonraki kullanıcı iletisi olarak gönderir — `session.idle` bildirim yalnızca ve ondan atılan istisna hiçbir işlem yapmadığından — tek zorla yeniden deneme kanalı), ve izin için no-op. Parçalama, hem araç adlarını (küçük harf → PascalCase `OPENCODE_TOOL_MAP` aracılığıyla) hem de araç giriş bağımsız değişkeni anahtarlarını (camelCase → snake_case `OPENCODE_TOOL_INPUT_MAP` aracılığıyla `Read` / `Write` / `Edit` için, örn. `filePath` → `file_path`, `oldString` → `old_string`) ikiliye iletilmeden önce kanonik hale getirir, böylece `block-read-outside-cwd`, `block-env-files` ve `block-secrets-write` gibi yol kontrol yapılanları OpenCode araç çağrılarında değişmeden ateşlenir. Oturumlar opencode'un SQLite DB'sinde `~/.local/share/opencode/opencode.db` adresinde yaşar; pano oturumu görüntüleyicisi `opencode db --format json` ve `opencode export ` aracılığıyla onları okur. OpenCode desteği **beta** aşamasındadır, sürümler arasında ve daha fazla gerçek dünya oturumuna karşı davranışı doğruladığımız sürece. [OpenCode eklentileri belgelerine](https://opencode.ai/docs/plugins/) bakın. + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (kullanıcı), `/.pi/settings.json` (proje) — Pi'nin yerel kapsamı yoktur. Pi, başlangıçta TypeScript uzantı paketlerini yükler; ayarlar dosyası düz bir dize dizisidir `{"packages": ["./relative/path", …]}`. failproofai, paketleri dizisine işlenmiş `pi-extension/` dizinine işaret eden tek bir giriş yazar. Uzantı dahili olarak Pi'nin `tool_call` / `user_bash` / `input` / `session_start` olaylarına abone olur ve `failproofai --hook --cli pi` adresine kabuğu çıkarır; işleyici underscore_lower_snake_case → PascalCase'i `PI_EVENT_MAP` aracılığıyla kanonik hale getirir, böylece mevcut yerleşik politikalar değişmeden ateşlenir. Araç giriş bağımsız değişkenleri de `PI_TOOL_INPUT_MAP` aracılığıyla kanonik hale getirir (Pi'nin Read / Write / Edit, `file_path` yerine `path` iletir; üst düzey anahtarı eşleştirmek `block-env-files` ve `block-secrets-write` adlarının ateşlenmesine izin verir — `block-read-outside-cwd` zaten bir `path` geri dönüşüne sahipti). Pi desteği **beta** aşamasındadır, Pi'nin uzantı API'si ve oturum günlüğü düzeni istikrar kazanır. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**sadece kullanıcı kapsamı** — Hermes'in proje/yerel yapılandırması yoktur). Hermes bir Slack/Telegram **ağ geçididir**, bu nedenle bir yükleme **her platformdan** (Slack/Telegram/cli/cron) araç çağrılarını **ve** dahili alt aracıları yakalar. Hook girdileri, Hermes'in snake_case olayları (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) tarafından anahtarlanan `hooks:` haritası altında `{command, timeout}` çiftidir; işleyici olayları `HERMES_EVENT_MAP` aracılığıyla ve araç adlarını `HERMES_TOOL_MAP` aracılığıyla kanonik hale getirir, böylece yerleşik politikalar değişmeden ateşlenir. Yapılandırma, yorum koruyan YAML `Document` turası aracılığıyla düzenlenmiştir, böylece operatörün diğer ayarları hayatta kalır ve yükleme, başsız ağ geçidinin (TTY yok) onay istemi olmadan hook'ları çalıştırması için `hooks_auto_accept: true` ayarını yapar. Değerlendirici, Hermes'in `{"decision":"block","reason"}` stdout sözleşmesini yayar (Hermes çıkış kodlarını yoksayar). **Sınırlamalar:** Hermes'in hiçbir `Stop` olayı yok, bu nedenle `require-*-before-stop` yapılanları hiçbir zaman onun için ateşlenmez (uygulanamaz, bozuk değil); `instruct`, izinle-günlüğe-not'a indirir (ek bağlam kanalı yoktur); ve çıkış gizli dizi redaksiyonu (`sanitize-*`) kabuk hook sözleşmesinde araç çıkışını yeniden yazamaz. Hermes aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, ağ geçidi oturumlarını doğrudan `~/.hermes/state.db` adresinden okur. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**sadece kullanıcı kapsamı** — OpenClaw'un proje/yerel yapılandırması yoktur). Hermes gibi, OpenClaw de kendi kendini barındıran çok kanallı **ağ geçididir**, bu nedenle bir yükleme her kanaldan ve dahili alt aracılardan araç çağrılarını yakalar. Uygulamadan OpenClaw'un **işlem içi eklenti hook'ları** aracılığıyla çalışır (dosya tabanlı dahili hook'ları yalnızca gözlemdir ve bloke edemez), bu nedenle — OpenCode/Pi gibi — failproofai, failproofai ikilisini zaman uyumsuz olarak üretir ve kararı çeviren statik `openclaw-plugin/` paketi gönderir. Yükleme, gönderilen eklenti dizinini `openclaw.json`'in `plugins.load.paths[]` içine kaydeder ve `plugins.entries.failproofai` altında etkinleştirir (`hooks.allowConversationAccess: true`, ham konuşma hook'ları için gerekli). Değerlendirici, düz `{permission, reason}` kararını yayar ve parçalama bunu her hook'un yerel dönüş şekline eşler: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), ve `before_agent_finalize → {action:"revise", reason}` (**Stop** — gerçek bir dönüş sonu kapısı, bu nedenle `require-*-before-stop` yapılanları **uygulanır** OpenClaw'da, Hermes'ten farklı). Olaylar ve araç adları, ikili tarafı `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) aracılığıyla kanonik hale getirir, böylece yerleşik politikalar değişmeden ateşlenir; parçalama, herhangi bir üretim/ayrıştırma/zaman aşımı hatasında açık olarak başarısız olur. OpenClaw aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, JSONL oturumlarını `~/.openclaw/agents//sessions/.jsonl` adresinden okur. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (kullanıcı), `/.factory/hooks.json` (proje) — Factory'nin yerel kapsamı yoktur. droid, droid v0.171.0 canlı olarak doğrulanmış iki tuhaflık ile Claude stili harici komut hook sistemini gönderir: (1) olay adları `hooks.json` **üst düzeyinde** yaşar — **hiçbir `"hooks"` sarmalayıcı yok** (droid bir taneyi reddeder); araç olayları (`PreToolUse`/`PostToolUse`) `"matcher": "*"` taşır, araç olmayan olaylar bunu atlar. (2) Reddetme, hook **çıkış kodu 2 + stderr** tarafından yönlendirilir, JSON kararı değil — değerlendirici'nin `factory` dalı araç/istem olayları için çıkış 2 döndürür ve dönüş sonu `Stop` olayında (`{decision:"block", reason}` döndürür (droid'in tek zorla yeniden deneme kanalı). Olaylar zaten PascalCase'dir (olay haritası yok) ve yük Claude snake_case'idir; yalnızca araç adları `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …) aracılığıyla kanonik hale getirilir. Factory aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, disk üzerindeki JSONL oturumlarını `~/.factory/sessions//.jsonl` adresinden okur. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (kullanıcı), `/.devin/config.json` (proje) — Devin'in yerel kapsamı yoktur. Devin, devin v3000.1.27'ye karşı doğrulanmış **saf Claude klonudur**: standart Claude `"hooks"` sarmalayıcı şemasını kullanır (yazılar, yapılandırma dosyasının diğer anahtarlarını — `org_id`, `theme_mode`, … — koruduğundan koruma sağlıyor), zaten PascalCase olay adlarını (olay haritası yok, işleyici dalı yok) ve Claude snake_case stdin yükünü (normalleştirme yok). Değerlendirici'nin `devin` dalı, **her** olay için stdout'ta `{"decision":"block","reason"}` JSON ile çıkış 0'da reddeder (doğrulanmıştır — block, `--permission-mode dangerous` adresini geçersiz kıldı); dönüş sonu `Stop` olayında neden, zorunlu aksiyonlu zorla yeniden deneme sözcüğünü taşır, bu nedenle `require-*-before-stop` yapılanları uygulanır. Yalnızca araç adları `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` zaten kanonik) aracılığıyla kanonik hale getirilir. Devin aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, SQLite oturumlarını `~/.local/share/devin/cli/sessions.db` adresinden okur (her `sessions` satırı gerçek bir `working_directory` taşır, bu nedenle oturumlar Claude gibi proje cwd tarafından gruplandırılır). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (kullanıcı), `/.agents/hooks.json` (proje) — Antigravity'nin yerel kapsamı yoktur. Factory/Devin'in aksine, Antigravity agy v1.1.2 canlı olarak doğrulanan **kendi** sözleşmesine sahiptir. `hooks.json` **adlandırılmış hook** şemasını kullanır: üst düzey anahtar bir hook *adıdır* (`"failproofai"`) değeri bir olay→işleyicileri haritasıdır — araç olayları (`PreToolUse`/`PostToolUse`) işleyicileri `{matcher:"*", hooks:[…]}` içine sardığında, `PreInvocation`/`Stop` **düz** işleyici dizileridir (diğer adlandırılmış hook'lar korunur). stdin yükü **camelCase protojson'dur** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai bunu politikalar çalışmadan önce snake_case'e normalleştirir ve `run_command`'ın PascalCase bağımsız değişkenlerini (`CommandLine`/`Cwd`) `ANTIGRAVITY_TOOL_INPUT_MAP` aracılığıyla eşler. Değerlendirici'nin `antigravity` dalı Antigravity'nin **kendi** tepki şekillerini kullanır: `{decision:"deny", reason}` araç/istemi bloke eder (çıkış 0), dönüş sonu `Stop` olayında `{decision:"continue", reason}` döngüye yeniden girer (bu nedenle `require-*-before-stop` yapılanları uygulanır) ve `PreInvocation` (→ `UserPromptSubmit`) üzerine bir talimat enjekte etmek için `{injectSteps:[{ephemeralMessage}]}`. Araç adları `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …) aracılığıyla kanonik hale getirilir. Antigravity aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, düz JSONL transkriptlerini `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` adresinden okur (konuşma dizini `conversation_summaries.db` içinde). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (kullanıcı), `/.agents/plugins/failproofai/hooks/hooks.json` (proje) — Goose'un yerel kapsamı yoktur. Uygulamadan Goose'un **hooks** sistemini, çapraz aracı **Open Plugins** belirtimini kullanır: yükleyici sadece `failproofai` eklenti dizinini bırakır ve Goose başlangıçta onu otomatik olarak keşfeder (kendi kendini `~/.config/goose/config.yaml` içine kaydeder). `hooks.json`, üst düzey `"hooks"` sarmalayıcıya **sahip** Open Plugins şemasını kullanır ve eşleştirici **her olay üzerinde atlanır** — düz `"*"` hiçbir şeyle eşleşmeyen geçersiz bir regex'tir (goose v1.43.0 canlı olarak doğrulanmıştır). Olay adları zaten PascalCase'dir (olay haritası yok); stdin yükü `event`/`working_dir` kullanır, işleyici bunu `hook_event_name`/`cwd` adresine normalleştirir. Değerlendirici'nin `goose` dalı, çıkış 0'da `{"decision":"block","reason"}` JSON ile reddeder, **`PreToolUse`** olayında yalnızca onurlandırılır (goose ≥ v1.37.0 içinde gönderilen) — hangisi kabuk aracı **için ve temsilci alt aracılar içinde** ateşlenir, bu nedenle tek yeterli reddetme noktasıdır; diğer hook hataları **açık** olarak başarısız olur. Goose'un **`Stop` olayı yoktur**, bu nedenle `require-*-before-stop` yapılanları uygulanmaz (Hermes gibi). Araç adları `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) aracılığıyla ve yol anahtarları `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`) aracılığıyla kanonik hale getirilir. Goose aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, SQLite oturumlarını `~/.local/share/goose/sessions/sessions.db` adresinden okur (her `sessions` satırı gerçek bir `working_dir` taşır, bu nedenle oturumlar Devin gibi proje cwd tarafından gruplandırılır; `--no-session` kazı çalışmaları filtrelenir). +- **`policies-config.json`** — failproofai'ye hangi politikaları değerlendireceğini ve hangi parametrelerle yapılacağını söyler (tüm aracı CLI'ları arasında paylaşılır) + +Belirli bir aracıyı hedeflemek için `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` adresini geçin (boşlukla ayrılmış veya herhangi bir alt küme için tekrarlanmış): ```bash failproofai policies --install --cli codex --scope project @@ -233,20 +231,38 @@ failproofai policies --install --cli goose --scope project failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -`--cli` atlandığında, `failproofai` hangi aracı CLI'lerinin kurulu olduğunu algılar (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): +`--cli` omit olduğunda, `failproofai` hangi aracı CLI'larının yüklü olduğunu algılar (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): + +- **Bir CLI algılanmış** — istem göstermeden bu CLI'yı otomatik olarak seçer. +- **Etkileşimli bir terminalde birden fazla CLI algılanmış** — `Detected (N)` bölümünde gruplanmış (toplam `Install for all N detected` satırı + her algılanan CLI ayrı ayrı) ve `Not installed (M) · install hooks ahead of time` bölümünde desteklenen her algılanmamış CLI'yı listeleme ok tuşu tek seçim istemi gösterir (↑↓ taşı, Enter seç, ^C çık). Kaldırma akışı yalnızca Algılanan bölümü gösterir. +- **Etkileşimli olmayan bir çalışma (CI, TTY yok) adresinde birden fazla CLI algılanmış** — istem göstermeden algılanan tüm CLI'lar için yükler. +- **Hiçbiri algılanmadı** — `claude` adresine geri döner, PATH'de hiçbir aracı ikilisinin bulunmadığını söyleyen bir uyarı ile; hook komutu yine yazılır, böylece biri yüklenir yüklemez etkinleşir. + +`policies-config.json` adresini doğrudan herhangi bir zamanda düzenleyebilirsiniz; değişiklikler yeniden başlatma gerekmeksizin sonraki hook olayında etkili olur. + +## Yükseltmeler yapılandırmanızı tutar + +failproofai'nin yeni bir sürümü `~/.failproofai/` adresini farklı şekilde düzenleyebilir. Bunu yaptığında, yükseltmeden sonra ilk komut dizini geçirir ve **yapılandırmanız taşınır, sıfırlanmaz**: + +| Tutulan | Yeniden oluşturulan | +|---|---| +| Politika seçiminiz ve parametreleriniz (`policies-config.json`) | Denetim önbelleği | +| `daemon.configured` ve ek yakalama yolları (`config.json`) dahil ayarlarınız | Bulut tarafından yönetilen politika dağıtımları — sonraki anketde yeniden getirilir ve özet doğrulanır | +| Bulut kaydınız (`credentials.json`) | Daemon çizik durumu | +| `policies/` içindeki kendi politika dosyalarınız ve içe aktardıkları yardımcılar | | +| Panonun okuduğu karar günlüğü ve henüz iletilmemiş olaylar | | + +Daha *yeni* bir failproofai tarafından yazılan anahtarlar da korunur, eski bir okuyucu tarafından bırakılmış yerine — bu nedenle sürümler arasında hareket etmek, her iki yönde de ayarları sessizce atmaz. -- **Bir CLI algılandı** — onay istemeksizin o CLI'yi otomatik seçer. -- **Çok sayıda CLI algılandı** etkileşimli terminalde — `Detected (N)` bölümüne gruplandırılmış ok tuşu tek seçim istemi gösterir (`Install for all N detected` toplam satırı + her algılanan CLI ayrı ayrı) ve `Not installed (M) · install hooks ahead of time` bölümü her desteklenen CLI'yi ileriye dönük yükleme seçeneği olarak listeler (↑↓ taşı, Enter seç, ^C çık). Kaldırma akışı yalnızca Algılanan bölümü gösterir. -- **Çok sayıda CLI algılandı** etkileşimsiz çalıştırmada (CI, TTY yoktur) — onay istemeksizin tüm algılanan CLI'ler için yüklenir. -- **Hiç algılanmadı** — `claude` olarak geri döner ve PATH'de aracı ikili bulunmadığını uyarır; kanca komutu yine yazılır, bu nedenle bir tanesi yükler yüklenmez etkinleşir. +Sonrasında kurulumu yeniden çalıştırmanız **gerekmez**: geçirilmiş bir makine, önceden yaptığı gibi tam olarak uygulanır, bu da yükseltmeyi, kimsenin oturduğu makinelerde güvenli kılan şeydir. Her geçiş `~/.failproofai/migrations/applied.json` adresinde kaydedilir ve yerine geçemez dosyalar, herhangi bir şey çalışmadan önce `~/.failproofai/migrations/backup-layout/` adresine kopyalanır. -`policies-config.json` öğesini dilediğiniz zaman doğrudan düzenleyebilir; değişiklikler yeniden başlama gerekmeksizin sonraki kanca olayında etkili olur. +Tek satırlık yükseltme için [`failproofai update`](/tr/cli/update) bölümüne ve ayrıntılar için [`failproofai migrate`](/tr/cli/migrate) — `--dry-run` dahil — bölümüne bakın. --- -## Örnek: takım varsayılanları olan proje düzeyinde konfigürasyon +## Örnek: ekip varsayılanları ile proje düzeyi yapılandırma -`.failproofai/policies-config.json` öğesini deponuza gönderin: +`.failproofai/policies-config.json` adresini deponuza işleyin: ```json { @@ -265,4 +281,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her } ``` -Her geliştirici daha sonra `.failproofai/policies-config.local.json` (gitignored) oluşturabilir; takım arkadaşlarını etkilemeden kişisel geçersiz kılmalar için. \ No newline at end of file +Her geliştirici daha sonra kişisel geçersiz kılmalar için (gitignore'lanmış) `.failproofai/policies-config.local.json` oluşturabilir, takım arkadaşlarını etkilemeksizin. \ No newline at end of file diff --git a/docs/tr/custom-policies.mdx b/docs/tr/custom-policies.mdx index b89ca523..13fda10a 100644 --- a/docs/tr/custom-policies.mdx +++ b/docs/tr/custom-policies.mdx @@ -1,10 +1,11 @@ --- -title: Özel İlkeler -description: "JavaScript'te kendi ilkelerinizi yazın - kuralları uygulayın, kaymaları önleyin, başarısızlıkları algılayın, dış sistemlerle entegre olun" +--- +title: Özel Politikalar +description: "JavaScript'te kendi politikalarınızı yazın - kuralları zorlayın, sapmayı önleyin, hataları algılayın, harici sistemlerle entegre olun" icon: code --- -Özel ilkeler, herhangi bir aracı davranışı için kurallar yazmanıza izin verir: proje kurallarını uygulayın, kaymaları önleyin, yıkıcı işlemleri engelleyin, takılı kalan aracıları algılayın veya Slack, onay iş akışları ve daha fazlasıyla entegre olun. Yerleşik ilkelerle aynı kanca olay sistemini ve `allow`, `deny`, `instruct` kararlarını kullanırlar. +Özel politikalar, herhangi bir ajan davranışı için kurallar yazmanıza izin verir: proje kurallarını zorlayın, sapmayı önleyin, yıkıcı işlemleri kısıtlayın, takılmış ajanları algılayın veya Slack, onay iş akışları ve daha fazlasıyla entegre olun. Yerleşik politikalarla aynı hook olay sistemini ve `allow`, `deny`, `instruct` kararlarını kullanırlar. --- @@ -37,65 +38,65 @@ failproofai policies --install --custom ./my-policies.js --- -## Özel ilkeleri yüklemenin iki yolu +## Özel politikaları yüklemek için iki yol -### Seçenek 1: Kurala dayalı (önerilen) +### Seçenek 1: Kural tabanlı (önerilen) -`*policies.{js,mjs,ts}` dosyalarını `.failproofai/policies/` içine bırakın ve otomatik olarak yüklenir — bayrak veya yapılandırma değişikliğine gerek yok. Bu git kancaları gibi çalışır: bir dosya bırakın, işi görür. +`*policies.{js,mjs,ts}` dosyalarını `.failproofai/policies/` dizinine bırakın ve otomatik olarak yüklenirler — bayrak veya config değişikliğine gerek yok. Bu git hooks gibi çalışır: dosya bırakın, işte oldu. ``` -# Proje düzeyi — git'e kaydedildi, takımla paylaşıldı +# Proje seviyesi — git'e kaydedilmiş, takımla paylaşılan .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Kullanıcı düzeyi — kişisel, tüm projeler için uygulanır +# Kullanıcı seviyesi — kişisel, tüm projelere uygulanır ~/.failproofai/policies/my-policies.mjs ``` **Nasıl çalışır:** -- Hem proje hem de kullanıcı dizinleri taranır (birleşim — birinci kapsamı kazanır değil) -- Dosyalar her dizin içinde alfabetik olarak yüklenir. Sırayı kontrol etmek için `01-`, `02-` ile önek atın -- Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir; diğer dosyalar yok sayılır +- Hem proje hem de kullanıcı dizinleri taranır (birleşim — ilk kapsam kazanmıyor) +- Dosyalar her dizin içinde alfabetik sırayla yüklenir. Sırayı kontrol etmek için `01-`, `02-` ön eki kullanın +- Sadece `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir; diğer dosyalar yoksayılır - Her dosya bağımsız olarak yüklenir (dosya başına başarısız açık) -- Açık `--custom` ve yerleşik ilkelerle birlikte çalışır +- Açık `--custom` ve yerleşik politikalarla birlikte çalışır -Kurala dayalı ilkeler, kuruluşunuz için bir kalite standardı oluşturmanın en kolay yoludur. `.failproofai/policies/` öğesini git'e kaydedin ve her takım üyesi otomatik olarak aynı kuralları alır — geliştirici başına kuruluma gerek yok. Takımınız yeni başarısızlık modlarını keşfettikçe, bir ilke ekleyin ve gönderin. Zamanla bunlar, her katkı ile iyileşmeye devam eden, canlı bir kalite standardı haline gelir. +Kural tabanlı politikalar, kuruluşunuz için bir kalite standardı oluşturmanın en kolay yoludur. `.failproofai/policies/` dizinini git'e kaydedin ve her takım üyesi otomatik olarak aynı kuralları alır — geliştirici başına kurulum gerekmez. Takımınız yeni hata modlarını keşfettikçe, bir politika ekleyin ve gönderin. Zamanla bunlar, her katkıyla iyileşmeye devam eden yaşayan bir kalite standardı haline gelir. ### Seçenek 2: Açık dosya yolu ```bash -# Özel ilkeler dosyasıyla yükleyin +# Özel politika dosyasıyla yükleyin failproofai policies --install --custom ./my-policies.js -# Özel ilke yollarını değiştirin +# Özel politika yollarını değiştirin failproofai policies --install --custom ./new-policies.js -# Birden fazla açık dosyayı yapılandırın (bayrağa göre sırada yüklenir) +# Birden fazla açık dosya yapılandırın (bayrak sırasında yüklenir) failproofai policies --install --custom ./security.js --custom ./workflow.js -# Yapılandırmadaki tüm açık özel ilke yollarını kaldırın +# Tüm açık özel politika yollarını konfigürasyondan kaldırın failproofai policies --uninstall --custom ``` -Çözümlenen mutlak yollar `policies-config.json` dosyasında `customPoliciesPaths` olarak depolanır. Birden fazla dosyayı yapılandırmak için `--custom` öğesini yineleyin. Eski `customPoliciesPath` alanını kullanan mevcut yapılandırmalar çalışmaya devam eder. Dosyalar her kanca olayında yeni yüklenir — olaylar arasında önbelleğe alma yoktur. +Çözümlenen mutlak yollar `policies-config.json` içinde `customPoliciesPaths` olarak depolanır. Birden fazla dosyayı yapılandırmak için `--custom` yinelenin. Eski `customPoliciesPath` alanını kullanan mevcut konfigürasyonlar çalışmaya devam eder. Dosyalar her hook olayında yeniden yüklenir - olaylar arasında önbelleğe alma yoktur. -Her kayıtlı ilke, panodan kendi geçişiyle görünür. Bir ilkeyi kapatmak, kaynaktan nitelendirilmiş kimliğini `disabledCustomPolicies` içinde kaydeder; dosya ve diğer ilkeleri yüklenmeye devam eder, devre dışı bırakılan ilke olay eşleştirmesinden önce hariç tutulur. Dosyalar arasında yinelenen ilke adlarının bağımsız geçişleri vardır. +Her kayıtlı politika panoda kendi geçiş öğesiyle görünür. Bir politikayı kapatmak, kaynak nitelikli kimliğini `disabledCustomPolicies` içinde kaydeder; dosya ve diğer politikaları yüklemeye devam eder, kapalı politika olay eşleştirmesinden önce hariç tutulur. Dosyalar arasında yinelenen politika adları bağımsız geçişlere sahiptir. ### Her ikisini birlikte kullanma -Kurala dayalı ilkeler ve açık `--custom` dosyaları birlikte olabilir. Yükleme sırası: +Kural tabanlı politikalar ve açık `--custom` dosyaları birlikte bulunabilir. Yükleme sırası: 1. Açık `customPoliciesPaths` dosyaları (yapılandırılan sırada) -2. Proje kurala dayalı dosyaları (`{cwd}/.failproofai/policies/`, alfabetik) -3. Kullanıcı kurala dayalı dosyaları (`~/.failproofai/policies/`, alfabetik) +2. Proje kural dosyaları (`{cwd}/.failproofai/policies/`, alfabetik) +3. Kullanıcı kural dosyaları (`~/.failproofai/policies/`, alfabetik) --- ## API -### İçe aktarma +### İçe aktar ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -103,13 +104,13 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Bir ilkeyi kaydeder. Aynı dosyada birden fazla ilke için gerektiği kadar çağırın. +Bir politikayı kaydeder. Aynı dosyada birden fazla politika için gerektiği kadar çağırın. ```ts customPolicies.add({ name: string; // gerekli - benzersiz tanımlayıcı description?: string; // `failproofai policies` çıktısında gösterilir - match?: { events?: HookEventType[] }; // olay türüne göre filtreleyin; hepsine eşleştirmek için atla + match?: { events?: HookEventType[] }; // olay türüne göre filtrele; tümü eşleştirmek için çıkar fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` @@ -117,31 +118,31 @@ customPolicies.add({ ### Karar yardımcıları | İşlev | Etki | Ne zaman kullanılır | -|----------|--------|----------| -| `allow()` | İşleme sessizce izin ver | İşlem güvenli, mesaja gerek yok | -| `deny(message)` | İşlemi engelle | Aracı bu işlemi gerçekleştirmemelidir | -| `instruct(message)` | Engellememeden bağlam ekle | Aracıya yolunda kalması için ek bağlam ver | +|-------|------|-------------------| +| `allow()` | İşleme sessizce izin ver | İşlem güvenli, mesaj gerekmez | +| `deny(message)` | İşlemi engelle | Ajan bu işlemi yapmamalı | +| `instruct(message)` | Engelleme olmadan içerik ekle | Ajanı yolunda tutmak için ekstra bağlam ver | -`deny(message)` - mesaj Claude'a `"Blocked by failproofai:"` ön ekiyle görünür. Tek bir `deny` tüm sonraki değerlendirmeleri kısa devre yapar. +`deny(message)` - mesaj Claude'a `"Blocked by failproofai:"` ön eki ile görünür. Tek bir `deny` tüm ileri değerlendirmeyi kısa devresi. -`instruct(message)` - mesaj mevcut araç çağrısı için Claude'un bağlamına eklenir. Tüm `instruct` mesajları biriktirilir ve birlikte iletilir. +`instruct(message)` - mesaj, geçerli araç çağrısı için Claude'un bağlamına eklenir. Tüm `instruct` mesajları biriktirilir ve birlikte iletilir. -`policyParams` içine bir `hint` alanı ekleyerek herhangi bir `deny` veya `instruct` mesajına ekstra rehberlik ekleyebilirsiniz — kod değişikliğine gerek yok. Bu, özel (`custom/`), proje kurala dayalı (`.failproofai-project/`), ve kullanıcı kurala dayalı (`.failproofai-user/`) ilkeleri için de çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın. +Kod değişikliğine gerek kalmadan `policyParams` içinde `hint` alanı ekleyerek herhangi bir `deny` veya `instruct` mesajına ekstra rehberlik ekleyebilirsiniz. Bu, özel (`custom/`), proje kural (`.failproofai-project/`) ve kullanıcı kural (`.failproofai-user/`) politikaları için de çalışır. Ayrıntılar için bkz. [Yapılandırma → hint](/tr/configuration#hint-cross-cutting). ### Bilgilendirici izin mesajları -`allow(message)` işleme izin verir **ve** Claude'a bir bilgilendirici mesaj geri gönderir. Mesaj, kanca işleyicisinin stdout yanıtında `additionalContext` olarak iletilir — `instruct` tarafından kullanılan aynı mekanizma, ancak anlam olarak farklı: bir uyarı değil, bir durum güncellemesidir. +`allow(message)` işleme izin verir **ve** Claude'a bir bilgilendirici mesaj gönderir. Mesaj, hook işleyicisinin stdout yanıtında `additionalContext` olarak iletilir — `instruct` tarafından kullanılan mekanizmayla aynı, ancak semantik olarak farklı: bir uyarı değil, bir durum güncellemesidir. | İşlev | Etki | Ne zaman kullanılır | -|----------|--------|----------| -| `allow(message)` | İzin ver ve Claude'a bağlam gönder | Bir kontrolün geçtiğini onaylayın veya bir kontrolün neden atlandığını açıklayın | +|-------|------|-------------------| +| `allow(message)` | İzin ver ve Claude'a bağlam gönder | Bir kontrolün geçtiğini onaylayın veya kontrolün neden atlandığını açıklayın | Kullanım durumları: - **Durum onayları:** `allow("All CI checks passed.")` — Claude'a her şeyin yeşil olduğunu söyler -- **Başarısız açık açıklamalar:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude'a tam bağlamı alması için bir kontrolün neden atlandığını söyler -- **Birden fazla mesaj birikir:** birden fazla ilke her biri `allow(message)` döndürürse, tüm mesajlar yeni satırlarla birleştirilir ve birlikte iletilir +- **Başarısız açık açıklamalar:** `allow("GitHub CLI not installed, skipping CI check.")` — bir kontrolün neden atlandığını Claude'a söyler; böylece tam bağlama sahiptir +- **Birden fazla mesaj birikir:** birden fazla politika `allow(message)` döndürürse, tüm mesajlar yeni satırlarla birleştirilir ve birlikte iletilir ```js customPolicies.add({ @@ -151,7 +152,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... branch durumunu kontrol et ... + // ... şube durumunu kontrol et ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -163,9 +164,9 @@ customPolicies.add({ ### `PolicyContext` alanları | Alan | Tür | Açıklama | -|-------|------|-------------| +|------|-----|---------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | Çağrılan araç (örn. `"Bash"`, `"Write"`, `"Read"`) | +| `toolName` | `string \| undefined` | Çağrılan araç (ör. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Aracın giriş parametreleri | | `payload` | `Record` | Claude Code'dan tam ham olay yükü | | `session` | `SessionMetadata \| undefined` | Oturum bağlamı (aşağıya bakın) | @@ -173,40 +174,40 @@ customPolicies.add({ ### `SessionMetadata` alanları | Alan | Tür | Açıklama | -|-------|------|-------------| +|------|-----|---------| | `sessionId` | `string` | Claude Code oturum tanımlayıcısı | | `cwd` | `string` | Claude Code oturumunun çalışma dizini | | `transcriptPath` | `string` | Oturumun JSONL transkript dosyasının yolu | ### Olay türleri -| Olay | Ne zaman ateşlenir | `toolInput` içeriği | -|------|--------------|----------------------| -| `PreToolUse` | Claude bir araç çalıştırmadan önce | Aracın girdisi (örn. Bash için `{ command: "..." }`) | +| Olay | Ne zaman tetiklenir | `toolInput` içeriği | +|------|------------------|-------------------| +| `PreToolUse` | Claude bir araç çalıştırmadan önce | Aracın girdisi (ör. Bash için `{ command: "..." }`) | | `PostToolUse` | Bir araç tamamlandıktan sonra | Aracın girdisi + `tool_result` (çıktı) | -| `Notification` | Claude bir bildirim gönderdiğinde | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - kancaları her zaman `allow()` döndürmelidir, bildirimleri engelleyemezler | -| `Stop` | Claude oturumu bittiğinde | Boş | +| `Notification` | Claude bir bildirim gönderdiğinde | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - kancalar her zaman `allow()` döndürmelidir, bildirimleri engelleyemez | +| `Stop` | Claude oturumu sona erdiğinde | Boş | --- ## Değerlendirme sırası -İlkeler şu sırada değerlendirilir: +Politikalar şu sırada değerlendirilir: -1. Yerleşik ilkeler (tanım sırasında) -2. `customPoliciesPath` öğesinden açık özel ilkeler (`.add()` sırasında) -3. Proje `.failproofai/policies/` öğesinden kurala dayalı ilkeler (dosyalar alfabetik, içinde `.add()` sırası) -4. Kullanıcı `~/.failproofai/policies/` öğesinden kurala dayalı ilkeler (dosyalar alfabetik, içinde `.add()` sırası) +1. Yerleşik politikalar (tanım sırasında) +2. `customPoliciesPath` içinden açık özel politikalar (`.add()` sırasında) +3. Proje `.failproofai/policies/` içinden kural politikaları (dosyalar alfabetik, içinde `.add()` sırası) +4. Kullanıcı `~/.failproofai/policies/` içinden kural politikaları (dosyalar alfabetik, içinde `.add()` sırası) -İlk `deny` tüm sonraki ilkeleri kısa devre yapar. Tüm `instruct` mesajları biriktirilir ve birlikte iletilir. +İlk `deny` tüm sonraki politikaları kısa devresi yapar. Tüm `instruct` mesajları biriktirilir ve birlikte iletilir. --- ## Geçişli içe aktarmalar -Özel ilke dosyaları göreli yollar kullanarak yerel modülleri içe aktarabilir: +Özel politika dosyaları göreli yolları kullanarak yerel modülleri içe aktarabilir: ```js // my-policies.js @@ -223,46 +224,46 @@ customPolicies.add({ }); ``` -Giriş dosyasından ulaşılabilecek tüm göreli içe aktarmalar çözülür. Bu, `from "failproofai"` içe aktarmalarını gerçek dist yoluna yeniden yazarak ve ESM uyumluluğunu sağlamak için geçici `.mjs` dosyaları oluşturarak uygulanır. +Giriş dosyasından ulaşılabilen tüm göreli içe aktarmalar çözümlenir. Bu, `from "failproofai"` içe aktarmalarını gerçek dağıtım yoluna yeniden yazarak ve ESM uyumluluğunu sağlamak için geçici `.mjs` dosyaları oluşturarak uygulanır. --- -## Olay türü filtreleme +## Olay türü filtrelemesi -Bir ilkenin ne zaman ateşleneceğini sınırlamak için `match.events` öğesini kullanın: +Bir politikanın ne zaman tetiklendiğini sınırlamak için `match.events` kullanın: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Yalnızca oturum sona erdiğinde ateşlenir + // Sadece oturum sona erdiğinde tetiklenir // ctx.session.transcriptPath tam oturum günlüğünü içerir return allow(); }, }); ``` -Her olay türünde ateşlemek için `match` öğesini tamamen atla. +Her olay türünde tetiklemesi için `match` tamamen çıkarın. --- -## Hata işleme ve başarısızlık modları +## Hata işleme ve hata modları -Özel ilkeler **başarısız açık** olarak tanımlanır: hatalar yerleşik ilkeleri asla engellemez veya kanca işleyicisini çökertemez. +Özel politikalar **başarısız açık** durumdadır: hatalar asla yerleşik politikaları engelleme veya hook işleyicisini çökmez. -| Başarısızlık | Davranış | -|---------|----------| -| `customPoliciesPath` ayarlanmadı | Açık özel ilkeler çalışmaz; kurala dayalı ilkeler ve yerleşik olanlar normal olarak devam eder | -| Dosya bulunamadı | Uyarı `~/.failproofai/hook.log` öğesine kaydedilir; yerleşik olanlar devam eder | -| Sözdizimi/içe aktarma hatası (açık) | Hata `~/.failproofai/hook.log` öğesine kaydedilir; açık özel ilkeler atlanır | -| Sözdizimi/içe aktarma hatası (kurala dayalı) | Hata kaydedilir; bu dosya atlanır, diğer kurala dayalı dosyalar hala yüklenir | -| `fn` çalışma zamanında hata atarsa | Hata kaydedilir; bu kanca `allow` olarak işlenir; diğer kancalar devam eder | -| `fn` 10 saniyeden uzun sürerse | Zaman aşımı kaydedilir; `allow` olarak işlenir | -| Kurala dayalı dizin eksikse | Kurala dayalı ilkeler çalışmaz; hata yok | +| Hata | Davranış | +|------|----------| +| `customPoliciesPath` ayarlanmamış | Açık özel politikalar çalışmaz; kural politikaları ve yerleşikler normal olarak devam eder | +| Dosya bulunamadı | Uyarı `~/.failproofai/hook.log` dosyasına kaydedilir; yerleşikler devam eder | +| Söz dizimi/içe aktarma hatası (açık) | Hata `~/.failproofai/hook.log` dosyasına kaydedilir; açık özel politikalar atlanır | +| Söz dizimi/içe aktarma hatası (kural) | Hata kaydedilir; bu dosya atlanır, diğer kural dosyaları yüklenir | +| `fn` çalışma zamanında hatalar | Hata kaydedilir; bu kanca `allow` olarak işlenir; diğer kancalar devam eder | +| `fn` 10 saniyeden daha uzun sürer | Zaman aşımı kaydedilir; `allow` olarak işlenir | +| Kural dizini eksik | Kural politikaları çalışmaz; hata yok | -Özel ilke hatalarını hata ayıklamak için günlük dosyasını izleyin: +Özel politika hatalarını hata ayıklamak için günlük dosyasını izleyin: ```bash tail -f ~/.failproofai/hook.log @@ -271,13 +272,13 @@ tail -f ~/.failproofai/hook.log --- -## Tam örnek: birden fazla ilke +## Tam örnek: birden fazla politika ```js // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Aracıyı secrets/ dizinine yazmaktan engelle +// Ajanın secrets/ dizinine yazmasını önle customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -290,7 +291,7 @@ customPolicies.add({ }, }); -// Aracıyı yolunda tut: taahhüt etmeden önce testleri doğrula +// Ajanı yolunda tut: işlemeyi gerçekleştirmeden önce testleri doğrula customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -305,7 +306,7 @@ customPolicies.add({ }, }); -// Dondurma döneminde planlanmamış bağımlılık değişikliklerini engelle +// Dondurma döneminde planlanmamış bağımlılık değişikliklerini önle customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -328,14 +329,14 @@ export { customPolicies }; ## Örnekler -`examples/` dizini çalıştırmaya hazır ilke dosyalarını içerir: +`examples/` dizini hemen çalıştırılabilir politika dosyaları içerir: | Dosya | İçerik | -|------|----------| -| `examples/policies-basic.js` | Genel aracı başarısızlık modlarını kapsayan beş başlangıç ilkesi | -| `examples/policies-advanced/index.js` | İleri desenler: geçişli içe aktarmalar, zaman uyumsuz çağrılar, çıktı temizleme ve oturum sonu kancaları | -| `examples/convention-policies/security-policies.mjs` | Kurala dayalı güvenlik ilkeleri (.env yazmasını engelle, git geçmişini yeniden yazmasını önle) | -| `examples/convention-policies/workflow-policies.mjs` | Kurala dayalı iş akışı ilkeleri (test anımsatıcıları, denetim dosyası yazmaları) | +|-------|--------| +| `examples/policies-basic.js` | Yaygın ajan hata modlarını kapsayan beş başlangıç politikası | +| `examples/policies-advanced/index.js` | Gelişmiş modeller: geçişli içe aktarmalar, async çağrıları, çıktı temizlemesi ve oturum sonu kancaları | +| `examples/convention-policies/security-policies.mjs` | Kural tabanlı güvenlik politikaları (.env yazılarını engelle, git geçmişi yeniden yazmasını önle) | +| `examples/convention-policies/workflow-policies.mjs` | Kural tabanlı iş akışı politikaları (test hatırlatmaları, dosya yazılarını denetle) | ### Açık dosya örneklerini kullanma @@ -343,16 +344,16 @@ export { customPolicies }; failproofai policies --install --custom ./examples/policies-basic.js ``` -### Kurala dayalı örnekleri kullanma +### Kural tabanlı örnekleri kullanma ```bash -# Proje düzeyine kopyala +# Proje seviyesine kopyala mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# Veya kullanıcı düzeyine kopyala +# Veya kullanıcı seviyesine kopyala mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Yükleme komutu gerekmez — dosyalar bir sonraki kanca olayında otomatik olarak alınır. \ No newline at end of file +Yükleme komutu gerekmez — dosyalar bir sonraki hook olayında otomatik olarak alınır. \ No newline at end of file diff --git a/docs/tr/dashboard.mdx b/docs/tr/dashboard.mdx index 02efd1b1..7e534d85 100644 --- a/docs/tr/dashboard.mdx +++ b/docs/tr/dashboard.mdx @@ -1,15 +1,15 @@ --- --- -title: Pano -description: "Ajan oturumlarını izleyin, araç çağrılarını gözden geçirin ve politikaları yönetin" +title: Kontrol Paneli +description: "Agent oturumlarını izleyin, araç çağrılarını gözden geçirin ve politikaları yönetin" icon: chart-line --- -failproofai panosu, AI ajan oturumlarınızı izlemek ve politikaları yönetmek için tasarlanmış yerel bir web uygulamasıdır. Ajanlarınız sizin yokken neler yaptığını görün. +failproofai kontrol paneli, AI agent oturumlarınızı izlemek ve politikaları yönetmek için yerel bir web uygulamasıdır. Agent'larınız yokken neler yaptığını görün. --- -## Panoyu başlatma +## Kontrol panelini başlatma ```bash failproofai @@ -17,7 +17,7 @@ failproofai `http://localhost:8020` adresinde açılır. -Pano, proje, oturum ve failproofai yapılandırma verilerini doğrudan dosya sisteminden okur. Denetim hatırlatıcıları ve davetler gibi isteğe bağlı kimlik doğrulamalı özellikler, bu istekler için gereken bilgileri (e-posta adresleri dahil) uzak API'lere gönderir. +Kontrol paneli, yerel proje, oturum ve failproofai yapılandırma verilerini doğrudan dosya sisteminden okur. Denetim anımsatıcıları ve davetler gibi isteğe bağlı kimlik doğrulamalı özellikler, bu istekler için gereken bilgileri (e-posta adresleri dahil) uzak API'lere gönderir. --- @@ -25,69 +25,69 @@ Pano, proje, oturum ve failproofai yapılandırma verilerini doğrudan dosya sis ### Projeler -Makinenizde bulunan tüm Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ve Goose projelerini listeler. Claude projeleri `~/.claude/projects/` konumundan keşfedilir (`CLAUDE_PROJECTS_PATH` tarafından ayarlanan yol); Codex projeleri `~/.codex/sessions///
/*.jsonl` konumundaki her transkripti tarayarak ve her oturumun ilk kaydında kayıtlı `cwd` ile gruplandırılarak keşfedilir; Copilot CLI projeleri `~/.copilot/session-state//workspace.yaml` konumundan (`COPILOT_HOME` aracılığıyla yapılandırılabilir) taranarak ve `cwd` alanı ile gruplandırılarak keşfedilir; Cursor Agent projeleri `~/.cursor/agent-sessions//` konumundaki oturum başına meta veriler taranarak (`CURSOR_HOME` aracılığıyla yapılandırılabilir, `conversations/` ve `sessions/` yedek olarak kullanılır) `meta.json` / `session.json` / `workspace.yaml` içinde `cwd` skaleri aranarak keşfedilir; OpenCode projeleri `~/.local/share/opencode/opencode.db` konumundaki SQLite DB'sine `opencode db --format json` aracılığıyla sorgu yapılarak keşfedilir (`session` ve `project` tabloları okunur ve `project_id` ile gruplandırılır); Pi projeleri `~/.pi/agent/sessions//_.jsonl` konumundaki oturum başına JSONL transkriptleri tarayarak (`PI_SESSIONS_DIR` aracılığıyla yapılandırılabilir) her oturumun ilk kaydından `cwd` çekerek keşfedilir; Hermes ağ geçidi oturumları her profilin SQLite deposundan doğrudan okunur — `~/.hermes/state.db` artı `~/.hermes/profiles//state.db` (`HERMES_HOME` veya tek bir veritabanı için `HERMES_DB_PATH` ile geçersiz kılınabilir) — ve `hermes--` projelerine profil ve `source` (Slack/Telegram/cli/cron — ağ geçidi oturumlarının cwd'si yoktur) ile gruplandırılır; OpenClaw ağ geçidi oturumları `~/.openclaw/agents//sessions/*.jsonl` konumundan okunur ve `openclaw--` projelerine ajan ve kanal ile gruplandırılır (ayrıca cwd'si yoktur); Factory Droid projeleri `~/.factory/sessions//*.jsonl` konumundaki JSONL transkriptlerinden keşfedilir ve cwd ile gruplandırılır; Devin projeleri `~/.local/share/devin/cli/sessions.db` konumundaki SQLite DB'sinden (her oturumun `working_directory` ile gruplandırılır); Antigravity projeleri `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` konumundaki JSONL transkriptlerinden keşfedilir ve cwd ile gruplandırılır; ve Goose projeleri `~/.local/share/goose/sessions/sessions.db` konumundaki SQLite DB'sinden (her oturumun `working_dir` ile gruplandırılır). Birden fazla CLI tarafından kullanılan bir proje, tüm eşleşen rozetler ile tek satır olarak gösterilir. Belirli bir ajan CLI'sına göre filtrelemek için tablonun üzerindeki **CLI** açılır menüsünü kullanın; URL seçiminizi `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` olarak saklar. +Makinenizde bulunan tüm Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ve Goose projelerini listeler. Claude projeleri `~/.claude/projects/` öğesinden keşfedilir (veya `CLAUDE_PROJECTS_PATH` tarafından ayarlanan yoldan); Codex projeleri `~/.codex/sessions///
/*.jsonl` altındaki her transkripti tarayarak ve her oturumun ilk kaydında kaydedilen `cwd` tarafından gruplandırılarak keşfedilir; Copilot CLI projeleri her `~/.copilot/session-state//workspace.yaml` tarayarak keşfedilir (`COPILOT_HOME` ile yapılandırılabilir) ve `cwd` alanına göre gruplandırılır; Cursor Agent projeleri `~/.cursor/agent-sessions//` altındaki oturum başına meta veriler tarayarak keşfedilir (`CURSOR_HOME` ile yapılandırılabilir, `conversations/` ve `sessions/` geri dönüş olarak araştırılır) `meta.json` / `session.json` / `workspace.yaml` içinde `cwd` skaler için; OpenCode projeleri `opencode db --format json` aracılığıyla `~/.local/share/opencode/opencode.db` adresindeki SQLite DB'yi sorgulanarak keşfedilir (`session` ve `project` tabloları okunur ve `project_id` ile gruplandırılır); Pi projeleri `~/.pi/agent/sessions//_.jsonl` altındaki oturum başına JSONL transkriptlerini tarayarak keşfedilir (`PI_SESSIONS_DIR` ile yapılandırılabilir) ve her oturumun ilk kaydından `cwd` çıkarılır; Hermes ağ geçidi oturumları her profilin SQLite deposundan doğrudan okunur — `~/.hermes/state.db` ve `~/.hermes/profiles//state.db` (`HERMES_HOME` ile geçersiz kılınabilir veya tek bir veritabanı için `HERMES_DB_PATH`) — ve profil ve `source` (Slack/Telegram/cli/cron — ağ geçidi oturumlarının cwd'si yoktur) tarafından `hermes--` projelerine gruplandırılır; OpenClaw ağ geçidi oturumları `~/.openclaw/agents//sessions/*.jsonl` öğesinden okunur ve agent ve kanal tarafından `openclaw--` projelerine gruplandırılır (ayrıca cwd'si yoktur); Factory Droid projeleri `~/.factory/sessions//*.jsonl` adresindeki JSONL transkriptlerinden keşfedilir ve cwd tarafından gruplandırılır; Devin projeleri `~/.local/share/devin/cli/sessions.db` adresindeki SQLite DB'sinden (her oturumun `working_directory` ile gruplandırılır); Antigravity projeleri `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` adresindeki JSONL transkriptlerinden ve cwd tarafından gruplandırılır; Goose projeleri `~/.local/share/goose/sessions/sessions.db` adresindeki SQLite DB'sinden (her oturumun `working_dir` ile gruplandırılır). Birden fazla CLI tarafından kullanılan bir proje, tüm eşleşen rozetleri içeren tek bir satır olarak görüntülenir. Belirli bir agent CLI'ye göre filtrelemek için tablonun üzerindeki **CLI** açılır menüsünü kullanın; URL seçiminizi `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` olarak korur. -Hermes ve OpenClaw kullanıcı kapsamlıdır ve gruplandırılacak çalışma dizini olmadığından **daraltılabilir klasör ağacı** olarak gösterilir — üst düzeyden profil (veya ajan), altında kanalları — diğer tüm cwd tabanlı CLI'ler düz satır olarak kalır. Klasör satırları, altındaki her şeyin oturum sayısını ve en son etkinliğini toplayır, daraltılan klasörler ziyaretler arasında hatırlanır ve anahtar sözcük araması eşleştirdiklerini genişletir. +Hermes ve OpenClaw kullanıcı kapsamlıdır ve gruplandıracak çalışma dizini olmadığı için, **daraltılabilir bir klasör ağacı** olarak görüntülenir — profilin (veya ajanın) en üst düzey, altında kanalları — diğer tüm cwd tabanlı CLI'ler düz bir satır olarak kalır. Klasör satırları, altlarındaki her şeyin oturum sayısını ve en son etkinliğini toplar; daraltılmış klasörler ziyaretler arasında hatırlanır ve bir anahtar sözcük araması eşleştirdiği her şeyi genişletir. -Her proje şunları gösterir: +Her proje gösterir: - Proje adı (klasör yolundan türetilmiş) -- CLI rozeti — `Claude Code` (turuncu), `OpenAI Codex` (mor), `GitHub Copilot` (mavi), `Cursor Agent` (zümrüt yeşili), `OpenCode` (kehribar), `Pi` (pembe), ve/veya `Hermes` (indigo) +- CLI rozeti — `Claude Code` (turuncu), `OpenAI Codex` (mor), `GitHub Copilot` (mavi), `Cursor Agent` (zümrüt), `OpenCode` (kehribar), `Pi` (pembe) ve/veya `Hermes` (gökyüzü mavisi) - En son oturum etkinliğinin tarihi Oturumlarını görmek için bir projeye tıklayın. ### Oturumlar -Bir projedeki tüm oturumları listeler. Her oturum şunları gösterir: -- Oturum kimliği +Bir proje içindeki tüm oturumları listeler. Her oturum gösterir: +- Oturum ID'si - Başlangıç ve bitiş zaman damgaları -- Araç çağrısı sayısı -- Hook etkinlik sayısı (ateşlenen politikalar) +- Araç çağrı sayısı +- Hook etkinlik sayısı (çalışan politikalar) -Listeyi daraltmak için tarih aralığı filtresini ve oturum kimliği aramasını kullanın. Oturumlar sayfalandırılmıştır. +Listeyi daraltmak için tarih aralığı filtresini ve oturum ID'si aramasını kullanın. Oturumlar sayfalandırılır. -Oturum görüntüleyicisini açmak için bir oturuma tıklayın. +Oturum görüntüleyiciyi açmak için bir oturuma tıklayın. ### Oturum görüntüleyici -Oturum görüntüleyici, otonom ajanlar için ana soruyu yanıtlar: ajan ne yaptı ve yolundan sapmadı mı? Başlık yanındaki CLI rozeti, oturumun Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity veya Goose transkripti olup olmadığını gösterir. Bir oturumda gerçekleşen her şeyin zaman çizelgesini gösterir: +Oturum görüntüleyici, otonom ajanlar için temel soruyu yanıtlar: acan ne yaptı ve yolunda kalıdı mı? Başlığın yanındaki CLI rozeti, oturumun Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity veya Goose transkripti olup olmadığını gösterir. Bir oturumda gerçekleşen her şeyin bir zaman çizelgesini gösterir: -- **Mesajlar** - Claude'un metin yanıtları ve kullanıcı istemleri -- **Araç çağrıları** - Claude'un çağırdığı her araç, girdisi ve çıktısı ile -- **Politika etkinliği** - Her araç çağrısı için, hangi politikaların ateşlendiği ve hangi kararı döndürdüğü +- **Mesajlar** - Claude'un metin yanıtları ve kullanıcı yönergeleri +- **Araç çağrıları** - Claude'un çağırdığı her araç, giriş ve çıkışıyla birlikte +- **Politika etkinliği** - Her araç çağrısı için, hangi politikaların çalıştığı ve ne karar döndürdükleri -Üstteki istatistik çubuğu, oturum süresini, toplam araç çağrılarını ve hook kararlarının özetini (allow / deny / instruct sayıları) gösterir. +Üst kısımdaki istatistik çubuğu oturum süresini, toplam araç çağrılarını ve hook kararlarının özetini (izin ver / reddet / yönerge sayıları) gösterir. -Oturumu dışa aktarmak için **Günlükleri İndir** düğmesine tıklayın. Claude Code, Codex, Copilot, Cursor ve Pi oturumları için orijinal diskte JSONL transkriptini bayt-bayt olarak alırsınız; OpenCode oturumları için (oturumlar diskte değil SQLite'da yaşadığından) temel `session` / `messages` / `parts` tablolarını yansıtan bir JSON belgesi alırsınız. +Oturumu dışa aktarmak için **Günlükleri İndir** düğmesine tıklayın. Claude Code, Codex, Copilot, Cursor ve Pi oturumları için orijinal disk üzerindeki JSONL transkriptini bayt-bayta alırsınız; OpenCode (oturumları SQLite'da, diskte değil) için alınan temel `session` / `messages` / `parts` tablolarını yansıtan bir JSON belgesi. ### Denetim -Ajanınızın geçmiş oturumlar arasında gerçekten nasıl davrandığının kişiliği yönüyle raporlaması. `failproofai audit` CLI ile aynı taraması çalıştırır ancak bunu tek ekranlı paylaşılabilir bir poster + dört aşağıda kalan bölüm olarak işler: +Agent'ınızın geçmiş oturumlar arasında gerçekte nasıl davrandığının kişilik yönelimli bir raporu. `failproofai audit` CLI ile aynı taramasını çalıştırır ancak bunu tek ekranlı paylaşılabilir bir poster + dört aşağıdaki bölüm olarak görüntüler: -1. **Poster** — ilk viewport'u doldurur. failproof_ai sözcük işareti + denetim etiketi · tip indeksi (`№ NN of 08`) + denetim tarihi · sayısal puan (0–100) + yüzdelik sıralama hapı (`top 15%`) · tip adı (`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` birinden) + 3 anahtar sözcük şeridi · `// only N% of agents are this archetype` nadirlik satırı · 8×8 piksel sigil döşemesi · `audit yours → failproof.ai` altbilgi içeren kendi başına yeterli PNG yakalama bölgesi. Üç paylaşma düğmesi yakalama kutusunun dışında yer alır: `post your archetype` (X intent), `share on linkedin`, `download poster`. Yakalama `html-to-image` aracılığıyla çalışır, böylece PNG ekranda görünen işlemeyle piksel-piksel eşleşir (kesik çizgili kenarlıklar, SVG logo maskesi, degradeler, yazı tipi ölçütleri — tümü korunur). -2. **Güçlü Yönler** — sakin ✓ satır listesi, ajanınızın zaten doğru yaptığı davranışlar, canlı denetim verilerinden türetilmiş (temiz araç çağrı oranı, ana kola doğrudan hiçbir push, sıfır kimlik bilgisi sızıntısı, sıfır yeniden deneme fırtınaları) — ilgili politika denetim penceresi genelinde temiz kayıtlara sahip olduğu zaman her biri ortaya çıkarılır. -3. **Tuhaflıklar** — sıyrıldığı şeylerin tablosu, ciddiyet tarafından sıralanmış: `when · what slipped + the policy that would've caught it · severity pill · seen`, tekrar okuması `new` (bir kez), `N× seen` (2–9 kez) veya `recurring` (10+). -4. **Nasıl İyileştirilir** — sakin satır listesi, önerilen her politika başına birer tane: politika adı beyazda, tek satır açıklama, sağ tarafta yükleme komutu + kopyala düğmesi. Bölüm başlığı `enable all N → projected · ` okur (her düzeltme uygulandığında ulaşacağınız puan) ve onun `[install all]` düğmesi, her önerilen politika için birleşik `failproofai policy add a b c …` komutunu kopyalar. -5. **Daha İyi Geri Dön** — yan yana iki kart. Sol: hatırlatıcı ayarla (`3d` / `7d` / `14d` / `30d` temposu seçici; kimlik doğrulandıktan sonra `/api/auth/reminder` aracılığıyla kalıcı). Sağ: failproof avantajlarının kilidini açın — `invite a friend` virgül/boşluk/yeni satır ile ayrılmış bir arkadaş e-postası listesini alan bir modal açar (gönderim başına maksimum 10), onları `/api/audit/invite` konumuna POST eder, bu da api-sunucusunun `POST /v0/invite` konumuna iletilir. Api-sunucusu, gönderici Cc'ye sahip ve `Reply-To` ayarlanmış şekilde `invite@failproof.ai` konumundan her alıcı için bir e-posta gönderir, böylece alıcı onları kimin davet ettiğini görür ve gönderici gelen kutularında bir kopya alır. Anonim kullanıcılar, davetler gönderilmeden önce gönderenin e-postası bilinir diye `AuthDialog` aracılığıyla yönlendirilir. Hak / avantaj yerine getirme sonraki bir aşamadır. +1. **Poster** — ilk görüntü alanını doldurur. failproof_ai sözcük işareti + denetim etiketi ile kendi kendine yeterli PNG-yakalama bölgesi · arketip dizini (`№ NN of 08`) + denetim tarihi · sayısal puan (0–100) + yüzdelik sıra rozeti (`top 15%`) · arketip adı (`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` içlerinden biri) + 3 anahtar sözcük şeridi · `// only N% of agents are this archetype` nadir kullanılan satır · 8×8 piksel sigil döşemesi · `audit yours → failproof.ai` altbilgisi. Yakalama kutusunun hemen dışında üç paylaş düğmesi bulunur: `post your archetype` (X amaçlı), `share on linkedin`, `download poster`. Yakalama `html-to-image` aracılığıyla çalışır, böylece PNG ekran üzerinde piksel-piksel (kesikli kenarlıklar, SVG logo maskesi, degradeler, yazı tipi ölçümleri — tümü korunur) eşleşir. +2. **Güçlü Yönler** — sakin ✓ satır listesi, agent'ınızın zaten doğru yaptığı davranışlar, canlı denetim verilerinden türetilmiş (temiz araç çağrı oranı, ana dalına doğrudan itme yok, sıfır kimlik bilgisi sızıntısı, sıfır yeniden deneme fırtınaları) — her biri yalnızca ilgili politika denetim penceresi genelinde temiz bir kayıta sahip olduğunda ortaya çıkar. +3. **Tuhaflıklar** — şunları sıralayan tablo: `when · what slipped + the policy that would've caught it · severity pill · seen`, nerede tekrarlanma `new` (bir kez), `N× seen` (2–9 kez) veya `recurring` (10+) olarak okunur. +4. **Nasıl iyileştirilir** — sakin satır listesi, önerilen her politika başına bir: politika adı beyaz, tek satırlı açıklama, yükleme komutu + sağ tarafta kopyala düğmesi. Bölüm başlığı `enable all N → projected · ` olarak okunur (her düzeltme uygulandığında ulaşacağınız puan), ve `[install all]` düğmesi her önerilen politika için birleştirilmiş `failproofai policy add a b c …` komutunu kopyalar. +5. **Daha iyi dön** — yan yana iki kart. Sol: anımsatıcı ayarla (`3d` / `7d` / `14d` / `30d` cadans seçici; kimlik doğrulandığında `/api/auth/reminder` aracılığıyla devam eder). Sağ: failproof avantajlarının kilidini aç — `invite a friend` virgül/boşluk/satır sonuyla ayrılmış bir arkadaş e-postaları listesini alacak bir modal açar (gönderi başına maksimum 10), bunları `/api/audit/invite` öğesine POSTlar, bu da api-sunucusunun `POST /v0/invite` öğesine iletilir. Api-sunucusu, göndereni Cc olarak ve `Reply-To` ayarlanmış şekilde `invite@failproof.ai` adresinden her alıcıya bir e-posta gönderir, böylece alıcı onları kimin davet ettiğini görür ve gönderici gelen kutularında bir kopya alır. Anonim kullanıcılar davetler gönderilmeden önce gönderenin e-postası bilindiği şekilde ilk olarak `AuthDialog` üzerinden yönlendirilir. Yetki / avantajlar yerine getirilmesi takip edilir. -`failproofai audit` çalışma zamanı tarafından yönlendirilir — temel tarama motoru, desteklenen bayraklar ve per-transkript önbellek değişmezleri için [Denetim CLI](/tr/cli/audit) konusuna bakın. Pano, en son sonucu `~/.failproofai/audit-dashboard.json` konumunda önbelleğe alır (mod `0600`, tek yuva, yeni çalıştırmalar üzerine yazar) böylece yeniden ziyaretler anlıktır; **hem per-transkript hem de tam sonuç önbellekleri okunduklarında 7 günü aştıklarında reddedilir** böylece pano hiçbir zaman bir haftaya kadar eski bir sonucu sessizce sunmaz — TTL geçtikten sonra `/audit` boş durumuna düşer ve yeni bir çalıştırma isteminden geçer. Raporun alt kısmında `[ re-audit now ]` düğmesine tıklamak `/api/audit/run` konumuna `noCache: true` ile POST gönderir — yeniden denetim per-transkript önbelleğini atlar ve her transkripti sessizce önbelleğe alınan sonucu döndürmek yerine sıfırdan yeniden tarar — ve pano çalıştırma bitene kadar `/api/audit/status` konumunu 1Hz'de yoklar; yapışkan pembe ilerleme şeridi çalışma sırasında viewport'un üstüne tutturulur ve geçen bir zamanlayıcı ile başarıda yeni sonuç yerine değiştirilir (tam sayfa yeniden yüklemesi yok; başarısız yeniden denetim önceki raporu sağlam bırakır). Başarısızlıkta şerit, `RerunError.kind` ('timeout' / 'network' / 'post_failed') konusunda anahtar kopyayla kırmızıya döner. Boş durum (önbellek yok veya süresi dolmuş) ve sıfır oturum durumu (önbellek var ancak tarama transkript bulamadı) ayrı olarak ortaya çıkarılır. +`failproofai audit` çalışması tarafından yönlendirilir — altta yatan tarama motoru, desteklenen bayraklar ve oturum başına önbellek değişmezleri için [Denetim CLI](/tr/cli/audit) sayfasına bakın. Kontrol paneli en son sonucu `~/.failproofai/audit-dashboard.json` adresinde önbelleğe alır (mod `0600`, tek yuvası, yeni çalıştırmalar üzerine yazarlar) böylece yeniden ziyaretler anlıktır; **hem oturum başına hem de tüm sonuç önbellekleri 7 günden eski olduğunda okunurken reddedilir**, böylece kontrol paneli asla sessizce bir hafta eski bir sonuç sunmaz — TTL geçtikten sonra `/audit` boş durumuna düşer ve yeni bir çalıştırma ister. Raporun altı yakınlarında `[ re-audit now ]` öğesine tıklamak, `noCache: true` ile `/api/audit/run` öğesine POSTlar — yeniden denetim, oturum başına önbelleği atlar ve her transkripti sıfırdan yeniden tararken sessizce önbelleğe alınan sonucu döndürmez — ve kontrol paneli `/api/audit/status` öğesini 1Hz'de yoklar; çalıştırma sırasında yapışkan bir pembe ilerleme şeridi görüntü penceresinin üstüne yapıştırılır ve başarıda taze sonuç yerinde değiştirilir (tam sayfa yeniden yüklemesi yok; başarısız yeniden denetim önceki raporu bozulmamış bırakır). Başarısızlığı geri döndürülürse şerit `RerunError.kind` (`timeout` / `network` / `post_failed`) tarafından tuş kesilmiş olarak kırmızıya döner. Boş durum (önbellek yok veya süresi dolu) ve sıfır oturum durumu (önbellek var ancak tarama hiç transkript bulamadı) ayrı olarak ortaya çıkar. ### Politikalar -Politikaları yönetmek ve etkinliği gözden geçirmek için iki sekmeli sayfa. +Politikaları yönetmek ve etkinliği incelemek için iki sekmeli bir sayfa. - - failproofai'ın tek bir panelden koruduğu ajan CLI'lerini çoklu seçin — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi ve Hermes'in tümü yükleme durumu (`Active` / `Detected` / `Inactive`), kullanıcı kapsamı ayarları yolu ve marka renkli aksan içeren bir satır alır. İstediğiniz CLI'leri işaretleyin veya işaretini kaldırın ve tek adımda farkı yüklemek/kaldırmak için `Apply changes` düğmesine tıklayın. PATH'ta ikili tespit edilen CLI'ler önceden işaretlidir. - - Bireysel politikaları tek tıklamayla açın veya kapatın (bunu `~/.failproofai/policies-config.json` konumuna yazar — tüm yüklü CLI'ler arasında paylaşılır) + - failproofai'ın tek bir panelden koruduğu agent CLI'lerini çok seçmeli olarak seçin — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi ve Hermes'in tümü yükleme durumu (`Active` / `Detected` / `Inactive`), kullanıcı kapsamı ayarları yolu ve marka renginde bir aksanı olan bir satır. İstediğiniz CLI'leri işaretleyin veya işaretini kaldırın ve `Apply changes` öğesine tıklayarak farkı tek bir adımda yükleyin/kaldırın. PATH'de ikili dosyası algılanan CLI'ler önceden işaretlenir. + - Bireysel politikaları tek bir tıklamayla açıp kapatın (yazma `~/.failproofai/policies-config.json` — tüm yüklenmiş CLI'ler arasında paylaşılır) - Bir politikayı genişleterek parametrelerini yapılandırın (`policyParams` destekleyen politikalar için) - - Özel politikalar dosyası yolunu ayarlayın + - Özel politikalar dosya yolunu ayarla - - Tüm oturumlar arasında ateşlenen her hook olayının tam sayfalandırılmış geçmişi - - Kararı, olay türünü, CLI'yi (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), politika adını veya oturum kimliğini filtreyin - - Her satır şunları gösterir: zaman damgası, politika adı, karar, CLI rozeti (turuncu = Claude Code, mor = OpenAI Codex, mavi = GitHub Copilot, zümrüt yeşili = Cursor Agent, kehribar = OpenCode, pembe = Pi, indigo = Hermes, turkuaz = OpenClaw, gül = Factory Droid, menekşe = Devin, cyan = Antigravity, yeşilimsi = Goose), araç adı, oturum kimliği ve deny/instruct kararlarının nedeni - - Transkriptini açmak için bir oturum kimliğine tıklayın — görüntüleyici hangi CLI'nin hook'u ateşlediğini otomatik olarak algılar (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) ve başlıkta eşleşen CLI rozetini işler + - Tüm oturumlar arasında çalıştırılan her hook olayının tam sayfalandırılmış geçmişi + - Karar, etkinlik türü, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), politika adı veya oturum ID'sine göre filtreleme yapın + - Her satır gösterir: zaman damgası, politika adı, karar, CLI rozeti (turuncu = Claude Code, mor = OpenAI Codex, mavi = GitHub Copilot, zümrüt = Cursor Agent, kehribar = OpenCode, pembe = Pi, gökyüzü mavisi = Hermes, turkuaz = OpenClaw, şeftali = Factory Droid, mor = Devin, cyan = Antigravity, şireşah = Goose), araç adı, oturum ID'si ve reddet/yönerge kararlarının nedeni + - Transkripsiyonu açmak için bir oturum ID'sine tıklayın — görüntüleyici hangi CLI'nin hook'u çalıştırdığını otomatik olarak algılar (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) ve başlıkta eşleşen CLI rozetini görüntüler @@ -95,13 +95,13 @@ Politikaları yönetmek ve etkinliği gözden geçirmek için iki sekmeli sayfa. ## Otomatik yenileme -Pano üst gezintide otomatik yenileme açma/kapatma düğmesine sahiptir. Etkinleştirildiğinde, geçerli sayfa yeni oturumlar ve politika etkinliği göstermek için periyodik olarak yenilenir. Uzun süren otonom ajan oturumlarının izlenmesi için gereklidir. +Kontrol panelinde üst navigasyonda bir otomatik yenileme değiştirici bulunur. Etkinleştirildiğinde, mevcut sayfa yeni oturumları ve politika etkinliğini göstermek için periyodik olarak yenilenir. Uzun süreli otonom agent oturumlarını izlemek için gereklidir. --- ## Sayfaları devre dışı bırakma -Pano'nun yalnızca bazı bölümlerine ihtiyacınız varsa, `FAILPROOFAI_DISABLE_PAGES` ortam değişkenini virgülle ayrılmış sayfa adlarının bir listesine ayarlayın: +Kontrol panelinin yalnızca bazı kısımlarına ihtiyacınız varsa, `FAILPROOFAI_DISABLE_PAGES` öğesini virgülle ayrılmış sayfa adlarının bir listesine ayarlayın: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -111,9 +111,9 @@ Geçerli değerler: `policies`, `projects`, `audit`. --- -## Proje yolunu yapılandırma +## Projeler yolunu yapılandırma -Pano, varsayılan olarak standart Claude Code projeleri dizininden okur. Özel kurulumlar için geçersiz kılın: +Varsayılan olarak, kontrol paneli standart Claude Code projeleri dizininden okur. Özel kurulumlar için bunu geçersiz kılın: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -123,13 +123,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Localhost olmayan bir konaktan erişim -Panoyu **geliştirme modu**'nda (`npm run dev`) çalıştırırken ve buna `localhost` dışında bir ana bilgisayar adından erişirken - örneğin, özel etki alanı, uzak IP veya tünel yapılmış URL - şöyle bir uyarı görebilirsiniz: +Kontrol panelini **dev modunda** (`npm run dev`) çalıştırırken ve `localhost` dışında bir ana bilgisayar adından erişirken — örneğin özel bir alan adı, uzak bir IP veya tünelli bir URL — şu gibi bir uyarı görebilirsiniz: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Bu, Next.js'nin HMR (sıcak modül yeniden yükleme) web soketine çapraz kaynaklı erişimi engellemesi, bu da yalnızca geliştirme özelliğidir. Ana bilgisayarınıza izin vermek için `--allowed-origins` bayrağını kullanın: +Bu, Next.js'nin, geliştirme özelliği olan HMR (sıcak modül yeniden yükleme) WebSocket'ine çapraz kaynaklı erişimi engellediğidir. Konağınıza izin vermek için `--allowed-origins` bayrağını kullanın: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -148,5 +148,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Bu yalnızca geliştirme moduna uygulanır. `failproofai` çalıştırırken (üretim modu), HMR web soketi ve çapraz kaynaklı dev kaynak sorunu yoktur. +Bu yalnızca dev modunda geçerlidir. `failproofai` çalıştırırken (üretim modu), HMR WebSocket'i ve çapraz kaynaklı geliştirme kaynağı sorunu yoktur. \ No newline at end of file diff --git a/docs/tr/examples.mdx b/docs/tr/examples.mdx index 3a931e17..88a37b1a 100644 --- a/docs/tr/examples.mdx +++ b/docs/tr/examples.mdx @@ -1,19 +1,20 @@ --- +--- title: Örnekler description: "Claude Code ve Agents SDK için hook'ları nasıl ayarlayacağınız" icon: book-open --- -Yaygın senaryolar için hazır örnekler. Her biri kurulumun nasıl yapılacağını ve neyi bekleyeceğinizi gösterir. +Yaygın senaryolar için kullanıma hazır örnekler. Her biri kurulumun nasıl yapılacağını ve neler bekleyeceğinizi gösterir. --- ## Claude Code için hook'ları ayarlama -Failproof AI, Claude Code ile [hook'lar sistemi](https://docs.anthropic.com/en/docs/claude-code/hooks) aracılığıyla entegre olur. `failproofai policies --install` komutunu çalıştırdığınızda, Claude Code'un `settings.json` dosyasına her araç çağrısında tetiklenen hook komutlarını kaydeder. +Failproof AI, Claude Code ile [hook sistemi](https://docs.anthropic.com/en/docs/claude-code/hooks) aracılığıyla entegre olur. `failproofai policies --install` komutunu çalıştırdığınızda, her araç çağrısında çalışan hook komutlarını Claude Code'un `settings.json` dosyasına kaydeder. - + ```bash npm install -g failproofai ``` @@ -28,14 +29,14 @@ Failproof AI, Claude Code ile [hook'lar sistemi](https://docs.anthropic.com/en/d cat ~/.claude/settings.json | grep failproofai ``` - `PreToolUse`, `PostToolUse`, `Notification` ve `Stop` olayları için hook girdilerini görmüş olmalısınız. + `PreToolUse`, `PostToolUse`, `Notification` ve `Stop` olayları için hook girdilerini görmelisiniz. ```bash claude ``` - Politikalar şimdi her araç çağrısında otomatik olarak çalışır. Claude'dan `sudo rm -rf /` komutunu çalıştırmasını istemeyi deneyin - bloke edilecektir. + Politikalar artık her araç çağrısında otomatik olarak çalışır. Claude'a `sudo rm -rf /` komutunu çalıştırmasını istemeyi deneyin - bloke edilecektir. @@ -43,20 +44,20 @@ Failproof AI, Claude Code ile [hook'lar sistemi](https://docs.anthropic.com/en/d ## Agents SDK için hook'ları ayarlama -[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) ile geliştiriyorsanız, aynı hook sistemi programlı olarak kullanılabilir. +[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) ile geliştiriyorsanız, aynı hook sistemini programlı olarak kullanabilirsiniz. - + ```bash npm install failproofai ``` - Ajan işlemi oluştururken hook komutlarını geçin. Hook'lar Claude Code'daki gibi çalışır - stdin/stdout JSON aracılığıyla: + Ajan sürecinizi oluştururken hook komutlarını geçin. Hook'lar Claude Code'da olduğu gibi çalışır - stdin/stdout JSON aracılığıyla: ```bash - failproofai --hook PreToolUse # her araçtan önce çağrılır - failproofai --hook PostToolUse # her araçtan sonra çağrılır + failproofai --hook PreToolUse # her araçtan önce çalıştırılır + failproofai --hook PostToolUse # her araçtan sonra çalıştırılır ``` @@ -86,37 +87,37 @@ Failproof AI, Claude Code ile [hook'lar sistemi](https://docs.anthropic.com/en/d --- -## Yıkıcı komutları bloke etme +## Yıkıcı komutları engelleme -En yaygın kurulum - ajanların geri döndürülemez hasara neden olmasını önlemek. +En yaygın kurulum - ajanların geri dönülemez hasarı yapmasını önleyin. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -Bunu ne yapar: -- `block-sudo` - tüm `sudo` komutlarını bloke eder -- `block-rm-rf` - özyinelemeli dosya silmeyi bloke eder -- `block-force-push` - `git push --force` komutunu bloke eder -- `block-curl-pipe-sh` - uzak betikleri shell'e yönlendirmeyi bloke eder +Bunu yapan şey: +- `block-sudo` - tüm `sudo` komutlarını engeller +- `block-rm-rf` - özyinelemeli dosya silmeyi engeller +- `block-force-push` - `git push --force` komutunu engeller +- `block-curl-pipe-sh` - uzak betiklerin shell'e aktarılmasını engeller --- -## Gizli bilgi sızıntısını önleme +## Gizli bilgi sızıntısını engelleme -Ajanların kimlik bilgilerini görmesini veya araç çıktısında sızdırmasını engelleyin. +Ajanların araç çıktısında kimlik bilgilerini görmesini veya sızıtmasını durdurun. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Bunlar `PostToolUse` etkinliğinde çalışır - bir araç çalıştıktan sonra, ajan bunu görmeden önce çıktıyı temizlerler. +Bunlar `PostToolUse` sırasında çalışır - bir araç çalıştıktan sonra, çıktıyı ajandan görmeden önce temizlerler. --- -## Ajanlar ilgilenilmesi gerektiğinde Slack uyarıları alın +## Ajanlar dikkat gerektirdiğinde Slack uyarıları alın -Bildirim hook'unu kullanarak boş bekleme uyarılarını Slack'e gönderin. +Bildirim hook'unu kullanarak boş uyarıları Slack'e iletin. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -158,9 +159,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## Ajanları bir dal üzerinde tutun +## Ajanları bir dalda tutun -Ajanların dal değiştirmesini veya korumalı dallara push etmesini engelleyin. +Ajanların dal değiştirmesini veya korumalı dallara push yapmasını önleyin. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -182,9 +183,9 @@ customPolicies.add({ --- -## Commit öncesi test gerekli kıl +## Taahhütler öncesinde testleri zorunlu kılın -Ajanları commit etmeden önce test çalıştırmaya hatırlatın. +Ajanları taahhüt etmeden önce testleri çalıştırmaları için hatırlatın. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -206,9 +207,9 @@ customPolicies.add({ --- -## Production deposunu kilitle +## Bir üretim deposunu kilitleyin -Proje düzeyinde bir yapılandırma commit edin, böylece ekibinizin her geliştirici aynı politikaları alır. +Projeye özgü bir yapılandırma taahhüt edin ve takımınızdaki her geliştirici aynı politikaları alsın. Deponuzda `.failproofai/policies-config.json` oluşturun: @@ -231,23 +232,23 @@ Deponuzda `.failproofai/policies-config.json` oluşturun: } ``` -Sonra commit edin: +Sonra taahhüt edin: ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -failproofai yüklü olan her ekip üyesi bu kuralları otomatik olarak alacaktır. +failproofai yüklü olan her takım üyesi otomatik olarak bu kuralları alacaktır. --- -## Konvention politikaları ile kuruluş çapında kalite standardı oluşturun +## Kural politikaları ile kuruluş çapında kalite standardı oluşturun -En etkili kurulum: projenize commit edin `.failproofai/policies/` ve politikalarınızı projenize uygun hale getirin. Her ekip üyesi bunları otomatik olarak alır — kurulum komutlarına gerek yok, yapılandırma değişikliklerine gerek yok. +En etkili kurulum: `.failproofai/policies/` klasörünü projenize yükleyin ve projenize özel politikalar ekleyin. Her takım üyesi otomatik olarak bunları alacaktır — yükleme komutları yok, yapılandırma değişiklikleri yok. - + ```bash mkdir -p .failproofai/policies ``` @@ -283,14 +284,14 @@ En etkili kurulum: projenize commit edin `.failproofai/policies/` ve politikalar }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - - Ekibiniz yeni hata modlarıyla karşılaştıkça, politika ekleyin ve push edin. Herkes bir sonraki `git pull` yapışında güncellemeleri alır. Bu politikalar, ekibinizle birlikte büyüyen canlı bir kalite standardı haline gelir. + + Takımınız yeni başarısızlık modlarıyla karşılaştıkça, politikalar ekleyin ve push yapın. Herkes bir sonraki `git pull` sırasında güncellemeleri alacaktır. Bu politikalar, takımınızla birlikte büyüyen bir canlı kalite standardı haline gelir. @@ -298,10 +299,10 @@ En etkili kurulum: projenize commit edin `.failproofai/policies/` ve politikalar ## Daha fazla örnek -Depolardaki [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) dizini şunları içerir: +Depodaki [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) dizini şunları içerir: | Dosya | Ne gösterir | |------|---------------| -| `policies-basic.js` | Başlangıç politikaları - production yazısını, force-push'ı, piped betikleri bloke eder | +| `policies-basic.js` | Başlangıç politikaları - üretim yazılarını, force-push'u ve piped scriptleri engelle | | `policies-notification.js` | Boş bildirimler ve oturum sonu için Slack uyarıları | -| `policies-advanced/index.js` | Geçişli içeri aktarımlar, eşzamansız hook'lar, PostToolUse çıktı temizleme, Stop etkinliği yönetimi | \ No newline at end of file +| `policies-advanced/index.js` | Geçişli içe aktarımlar, eş zamanlı hook'lar, PostToolUse çıktı temizliği, Stop olayı işleme | \ No newline at end of file diff --git a/docs/tr/for-agents.mdx b/docs/tr/for-agents.mdx index 7a5a4f67..544523f6 100644 --- a/docs/tr/for-agents.mdx +++ b/docs/tr/for-agents.mdx @@ -3,36 +3,36 @@ title: "Ajanlar için" description: "Failproof AI bilgisini kodlama ajanınıza tek komutla ekleyin. Claude Code, Cursor, Windsurf ve daha fazlasıyla çalışır." --- -Failproof AI başvuru rehberinin tamamını kodlama ajanınıza tek komutla ekleyin. Claude Code, Cursor, Windsurf ve beceri desteği olan diğer tüm ajanlarla çalışır. +Failproof AI başvuru belgelerinin tamamını kodlama ajanınıza tek komutla ekleyin. Claude Code, Cursor, Windsurf ve beceri destekleyen diğer tüm ajanlarla çalışır. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` hangi ajanları yüklü olduğunu tespit eder ve beceriyi her biri için doğru biçimde otomatik olarak ekler. +`npx skills`, hangi ajanların yüklü olduğunu algılar ve beceriyi her biri için otomatik olarak doğru biçimde ekler. -## Beceri neyi kapsar +## Beceri neleri kapsar? -| Alan | İçindekiler | -|------|------------| -| Politikalar | Yerleşik politika adları, olay türleri, parametreler, etkinleştirme/devre dışı bırakma | -| Özel politikalar | `customPolicies.add()`, eşleşme filtreleri, `allow`/`deny`/`instruct` API | -| Context nesnesi | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | +| Alan | İçeriği | +|------|---------| +| İlkeler | Yerleşik ilke adları, olay türleri, parametreler, etkinleştir/devre dışı bırak | +| Özel ilkeler | `customPolicies.add()`, eşleştirme filtreleri, `allow`/`deny`/`instruct` API | +| İçerik nesnesi | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Yapılandırma | `policies-config.json` yapısı, kapsam birleştirme, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, kapsamlar | -| Dashboard | Oturum görüntüleyicisi, politika aktivitesi, ortam değişkenleri | -| Mimari | Hook işleyici akışı, çıkış kodları, stdin/stdout sözleşmesi | +| Pano | Oturum görüntüleyicisi, ilke etkinliği, ortam değişkenleri | +| Mimari | Hook işleyicisi akışı, çıkış kodları, stdin/stdout sözleşmesi | ## Beceri tam mı? -Mintlify, `llms.txt` dosyasını gezintideki tüm sayfalardan oluşturur. Failproof AI dokümanları tam API'yi kapsar - her politika, seçenek ve örnek dahil edilmiştir. Eksik bir şey bulursanız, kaynak `https://docs.befailproof.ai/llms-full.txt` konumundadır. +Mintlify, `llms.txt` dosyasını gezinti menüsündeki tüm sayfalardan oluşturur. Failproof AI belgeleri tam API'yi kapsar - her ilke, seçenek ve örnek dahildir. Eksik bir şey bulursanız, kaynak `https://docs.befailproof.ai/llms-full.txt` adresindedir. -Hedeflenen içerik için doğrudan belirli bir sayfaya bağlantı verin: +Hedefli içerik için doğrudan belirli bir sayfaya bağlantı verin: ```bash -# Yalnızca özel politikalar API'si +# Yalnızca özel ilkeler API'si npx skills add https://docs.befailproof.ai/custom-policies -# Yalnızca yerleşik politikalar +# Yalnızca yerleşik ilkeler npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/tr/getting-started.mdx b/docs/tr/getting-started.mdx index 6eadd93a..41045449 100644 --- a/docs/tr/getting-started.mdx +++ b/docs/tr/getting-started.mdx @@ -1,13 +1,13 @@ --- -title: Başlarken -description: "failproofai yükleyin, politikaları etkinleştirin ve aracılarınızı güvenilir şekilde çalıştırın" +title: Başlangıç +description: "failproofai yükleyin, politikaları etkinleştirin ve aracılarınızın güvenilir şekilde çalışmasını sağlayın" icon: rocket --- ## Gereksinimler - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (isteğe bağlı - yalnızca kaynaktan derlemek için gerekli) +- **Bun** >= 1.3.0 (isteğe bağlı - sadece kaynaktan derlemek için gerekli) --- @@ -31,15 +31,15 @@ bun add -g failproofai - Politikalar, her aracı araç çağrısından önce ve sonra çalışan kurallardır. Yıkıcı komutları, gizli dizi sızıntısını ve hasar oluşturmadan önce diğer hata modlarını yakalarlar. + Politikalar, her aracı araç çağrısından önce ve sonra çalışan kurallardır. Yıkıcı komutları, gizli dizi sızıntısını ve hasar vermeden önce diğer arıza modlarını yakalar. ```bash failproofai policies --install ``` - Bu, yüklü aracı CLI'lerinize kanca girdileri yazar (Claude Code'un `~/.claude/settings.json`, OpenAI Codex'in `~/.codex/hooks.json`, GitHub Copilot CLI'nin `~/.copilot/hooks/failproofai.json`, Cursor Agent'ın `~/.cursor/hooks.json`, OpenCode'un `~/.config/opencode/plugins/failproofai.mjs` adresindeki oluşturulan eklenti dolgusuna ve `~/.config/opencode/opencode.json` dosyasının `plugin` dizisindeki kayıt girişine, Pi'nin `~/.pi/agent/settings.json`, Hermes'in `~/.hermes/config.yaml`, OpenClaw'ın `~/.openclaw/openclaw.json`, Factory Droid'in `~/.factory/hooks.json`, Devin CLI'nin `~/.config/devin/config.json`, Antigravity CLI'nin `~/.gemini/config/hooks.json` veya Goose'un `~/.agents/plugins/failproofai/hooks/hooks.json` adresindeki otomatik keşfedilen eklenti dizinine). Birden fazlası mevcut olduğunda sizden seçim istenir; istemi atlamak için `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (herhangi bir alt küme) geçirin. + Bu, yüklü aracı CLI'lerinize hook girdileri yazar (Claude Code'un `~/.claude/settings.json`, OpenAI Codex'in `~/.codex/hooks.json`, GitHub Copilot CLI'nin `~/.copilot/hooks/failproofai.json`, Cursor Agent'ın `~/.cursor/hooks.json`, OpenCode'un `~/.config/opencode/plugins/failproofai.mjs`'deki oluşturulan eklenti parçacığı artı `~/.config/opencode/opencode.json`'daki `plugin` dizisine kayıt girdisi, Pi'nin `~/.pi/agent/settings.json`, Hermes'in `~/.hermes/config.yaml`, OpenClaw'ın `~/.openclaw/openclaw.json`, Factory Droid'in `~/.factory/hooks.json`, Devin CLI'nin `~/.config/devin/config.json`, Antigravity CLI'nin `~/.gemini/config/hooks.json`, veya Goose'un `~/.agents/plugins/failproofai/hooks/hooks.json`'daki otomatik keşfedilen eklenti dizini). Birden fazla varsa istenecektir; istemi atlamak için `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (herhangi bir altküme) geçirin. - GitHub Copilot CLI, Cursor Agent, OpenCode ve Pi desteği **beta** aşamasındadır — `--cli copilot`, `--cli cursor`, `--cli opencode` veya `--cli pi` ile yükleyin. Hermes (hermes-agent, bir Slack/Telegram ağ geçidi) `--cli hermes` ile kullanıcı kapsamında yüklenir ve **aynı zamanda** çevrimdışı bir denetim kaynağıdır. OpenClaw (openclaw ağ geçidi, kendi barındırılan çok kanallı asistan) `--cli openclaw` ile kullanıcı kapsamında yüklenir — uygulama, işlem içi eklenti kankaları aracılığıyla çalışır (`before_agent_finalize` gerçek bir tur sonu kapısıdır, bu nedenle `require-*-before-stop` yerleşikleri uygular) — ve **aynı zamanda** çevrimdışı bir denetim kaynağıdır. Factory Droid (`droid`) `--cli factory` ile yüklenir (kullanıcı + proje kapsamı) ve **aynı zamanda** çevrimdışı bir denetim kaynağıdır. Devin CLI (`devin`, Cognition) `--cli devin` ile yüklenir (kullanıcı + proje kapsamı) ve **aynı zamanda** çevrimdışı bir denetim kaynağıdır. Antigravity CLI (`agy`) `--cli antigravity` ile yüklenir (kullanıcı + proje kapsamı) ve **aynı zamanda** çevrimdışı bir denetim kaynağıdır. Goose (kod adı goose, Block) `--cli goose` ile yüklenir (kullanıcı + proje kapsamı) — yükleyici yalnızca `~/.agents/plugins/failproofai/` adresine bir eklenti dizini bırakır ve Goose bunu otomatik olarak keşfeder; **aynı zamanda** çevrimdışı bir denetim kaynağıdır. + GitHub Copilot CLI, Cursor Agent, OpenCode ve Pi desteği **betadır** — `--cli copilot`, `--cli cursor`, `--cli opencode`, veya `--cli pi` ile yükleyin. Hermes (hermes-agent, bir Slack/Telegram ağ geçidi) `--cli hermes` ile kullanıcı kapsamına yüklenir ve **aynı zamanda** çevrimdışı denetim kaynağıdır. OpenClaw (openclaw ağ geçidi, kendi barındırılan çok kanallı asistan) `--cli openclaw` ile kullanıcı kapsamına yüklenir — zorlama işlemi içi işlem eklentisi hooks'ları (`before_agent_finalize` gerçek bir tur sonu kapısıdır, bu nedenle `require-*-before-stop` yerleşikleri zorlama yapabilir) — ve **aynı zamanda** çevrimdışı denetim kaynağıdır. Factory Droid (`droid`) `--cli factory` ile yüklenir (kullanıcı + proje kapsamı) ve **aynı zamanda** çevrimdışı denetim kaynağıdır. Devin CLI (`devin`, Cognition) `--cli devin` ile yüklenir (kullanıcı + proje kapsamı) ve **aynı zamanda** çevrimdışı denetim kaynağıdır. Antigravity CLI (`agy`) `--cli antigravity` ile yüklenir (kullanıcı + proje kapsamı) ve **aynı zamanda** çevrimdışı denetim kaynağıdır. Goose (kod adı goose, Block) `--cli goose` ile yüklenir (kullanıcı + proje kapsamı) — yükleyici `~/.agents/plugins/failproofai/` dizinine bir eklenti dizini bırakır ve Goose bunu otomatik olarak keşfeder, ve **aynı zamanda** çevrimdışı denetim kaynağıdır. ```bash failproofai policies --install --scope project @@ -69,10 +69,10 @@ bun add -g failproofai failproofai ``` - `http://localhost:8020` adresinde yerel bir pano açar; burada oturumları göz atabilir, araç çağrılarını inceleyebilir ve politikaları yönetebilirsiniz. + `http://localhost:8020` adresinde yerel bir pano açar; burada oturumları inceleyebilir, araç çağrılarını inceleyebilir ve politikaları yönetebilirsiniz. - Claude Code'u her zamanki gibi başlatın. Aracı riskli bir şey yapmaya çalışırsa, failproofai bunu otomatik olarak keser. Onu çalışır bırakın ve panoda ne olduğunu gözden geçirin. + Claude Code'u her zamanki gibi başlatın. Aracı riskli bir şey denerse, failproofai bunu otomatik olarak keser. Bunu çalışır durumda bırakın ve panoda neler olduğunu gözden geçirin. @@ -80,29 +80,29 @@ bun add -g failproofai ## Politikalar nasıl çalışır -Bir aracı her araç çalıştırdığında, Claude Code failproofai'yi bir alt işlem olarak çağırır: +Her aracı bir araç çalıştırdığında, Claude Code failproofai'yi bir alt işlem olarak çağırır: ```text -Claude Code → failproofai --hook PreToolUse → stdin JSON'ı okur - politikaları değerlendirir - stdout'a karar yazar +Claude Code → failproofai --hook PreToolUse → stdin JSON'u okur + politikaları değerlendirir + stdout'a karar yazar ``` Her politika üç karardan birini döndürür: - **allow** - aracı normal şekilde devam eder -- **deny** - işlem engellenir, aracıya neden engellediği söylenir -- **instruct** - aracının istemi'ne ekstra bağlam eklenir +- **deny** - eylem engellenir, aracıya neden olduğu söylenir +- **instruct** - aracının istemine ekstra bağlam eklenir -Politikalar yerel işleminizde çalışır. Hiçbir şey uzak bir hizmete gönderilmez. +Politikalar yerel işleminizde çalışır. Hiçbir şey uzak bir servise gönderilmez. --- -## Kural tabanlı politikalar ile takım politikaları ayarlayın +## Kuralı temel politikalarla takım politikalarını ayarlayın -Ekibiniz genelinde kalite standartları oluşturmanın en hızlı yolu `.failproofai/policies/` kuralıdır. Politika dosyalarını bu dizine bırakın ve otomatik olarak yüklenir — bayrak yok, yapılandırma değişikliği yok, kurulum komutu yok. +Ekibiniz genelinde kalite standartları oluşturmanın en hızlı yolu `.failproofai/policies/` kuralıdır. Politika dosyalarını bu dizine bırakın ve bunlar otomatik olarak yüklenir — hiç bayrak, hiç yapılandırma değişikliği, hiç yükleme komutu yoktur. @@ -111,7 +111,7 @@ Ekibiniz genelinde kalite standartları oluşturmanın en hızlı yolu `.failpro ``` - Başlangıç örneklerini kopyalayın veya kendininkini yazın: + Başlangıç örneklerini kopyalayın veya kendi politikalarınızı yazın: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -129,50 +129,52 @@ Ekibiniz genelinde kalite standartları oluşturmanın en hızlı yolu `.failpro fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Taahhüt etmeden önce testleri çalıştırın."); + return instruct("Commit etmeden önce testleri çalıştırın."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Takım kalite politikaları ekleyin" ``` - failproofai yüklü olan her takım üyesi bu politikaları otomatik olarak alır. Geliştirici başına kurulum yapılması gerekmez. + failproofai'yi yüklü olan her takım üyesi bu politikaları otomatik olarak alır. Geliştirici başına kuruluma gerek yoktur. -`.failproofai/policies/` deposuna taahhüt edin; böylece tüm takım aynı standartları paylaşır. Takımınız yeni hata modlarını keşfettikçe, politikalar ekleyin ve gönderin — herkes bir sonraki `git pull` komutunda güncellemeyi alır. Zaman içinde bu politikalar, iyileşmeye devam eden yaşayan bir kalite standartı haline gelir. +Tüm takımın aynı standartları paylaşması için `.failproofai/policies/`'i repo'nuza işleyin. Takımınız yeni arıza modları keşfettikçe politikalar ekleyin ve gönderin — herkes sonraki `git pull`'da güncellemeleri alır. Zamanla bu politikalar, gelişmeye devam eden yaşayan bir kalite standardı haline gelir. --- -## Veri depolama +## Veri depolaması Tüm yapılandırma ve günlükler makinenizde kalır: -| Yol | Depoladığı şey | +| Yol | Neler depolandığı | |------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | Genel politika yapılandırması | -| `~/.failproofai/hook-activity/` | Kanca yürütme geçmişi (sayfalı JSONL) | -| `~/.failproofai/logs/` | Özel kanca hataları için hata ayıklama günlükleri | -| `.failproofai/policies-config.json` | Proje başına yapılandırma (taahhüt edildi) | +| `~/.failproofai/policies-config.json` | Genel politika yapılandırması | +| `~/.failproofai/policies/` | Kendi politikalarınız — `*-policies.mjs` dosyalarını bırakın, yapılandırma gerekmez | +| `~/.failproofai/policies/cloud-policies/` | Kuruluşunuz tarafından bu makineye dağıtılan politikalar | +| `~/.failproofai/hook-activity/` | Hook yürütme geçmişi (sayfalanmış JSONL) | +| `~/.failproofai/logs/` | Özel hook hataları için hata ayıklama günlükleri | +| `.failproofai/policies-config.json` | Proje başına yapılandırma (işlenmiş) | | `.failproofai/policies-config.local.json` | Kişisel geçersiz kılmalar (gitignored) | --- -## Kaldırılıyor +## Kaldırma ```bash failproofai policies --uninstall ``` -`~/.claude/settings.json` dosyasından kanca girdilerini kaldırır. `~/.failproofai/` dizinindeki yapılandırma dosyaları tutulur. +`~/.claude/settings.json`'dan hook girdilerini kaldırır. `~/.failproofai/` içindeki yapılandırma dosyaları tutulur. --- @@ -181,11 +183,11 @@ failproofai policies --uninstall - Kapsamlar ve yapılandırma dosyası biçimi + Kapsamlar ve yapılandırma dosyası formatı - Parametreler ile tüm 26 politika + Parametrelerle 26 politikanın tümü @@ -193,7 +195,7 @@ failproofai policies --uninstall - Oturumları izleyin ve politika aktivitesini gözden geçirin + Oturumları izleyin ve politika faaliyetini gözden geçirin \ No newline at end of file diff --git a/docs/tr/introduction.mdx b/docs/tr/introduction.mdx index 5cec8eeb..f46c1e14 100644 --- a/docs/tr/introduction.mdx +++ b/docs/tr/introduction.mdx @@ -1,36 +1,36 @@ --- title: "Failproof AI" -description: "FailproofAI, AI aracılarına 39 yerleşik başarısızlık politikası sağlayarak döngüleri, gizli sızdırmaları, yıkıcı araç çağrılarını ve daha pbirçok sorunu tek bir kurulumla yakalar." +description: "FailproofAI, yapay zeka agenlerine 39 yerleşik hata politikası sağlayarak döngüleri, gizli dilimleri, yıkıcı araç çağrılarını ve daha fazlasını tek bir kurulumda yakalar." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -**AI başarısızlık yönetimi**, **hata kurtarma** ve **LLM güvenilirliği** için kancalar ve politikalar. AI aracılarınızı **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** ve **Agents SDK** üzerinde güvenilir ve otonom şekilde çalıştırın. +**Yapay zeka hata yönetimi**, **hata kurtarma** ve **LLM güvenilirliği** için hook'lar ve politikalar. Yapay zeka agenlerinizi **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** ve **Agents SDK** arasında güvenilir ve otonom olarak çalışan tutun. -AI aracıları öngörülebilir şekillerde başarısız olur. Yıkıcı komutlar çalıştırırlar, gizli bilgiler sızdırırlar, görevden sapıyor, döngülerde sıkışırlar veya doğrudan ana dala gönderim yaparlar. Denetimsiz bırakıldığında, küçük başarısızlıklar kesintilere, sızdırılan kimlik bilgilerine ve kaybedilen işlere dönüşebilir. +Yapay zeka agentleri öngörülebilir şekillerde başarısız olur. Yıkıcı komutlar çalıştırırlar, gizli dizileri sızıtırlar, görevden saparlar, döngülerde sıkışırlar veya doğrudan main dalına iter. Denetimsiz bırakıldığında, küçük başarısızlıklar kesintilere, sızdırılan kimlik bilgilerine ve kayıp çalışmaya dönüşebilir. -FailproofAI bunu **politikalar** ile çözer. Bu kurallar her araç çağrısına takılarak **başarısızlıkları tespit eder**, **bunları hafifletir** (engelle, talimat ver, dezenfekte et) ve **dikkat gerektiğinde sizi uyarır**. Yerel bir pano, her araç çağrısını, aracı başarısızlığını ve kurtarma eylemini daha sonra gözden geçirmenizi sağlar. +FailproofAI bunu **politikalar** ile çözer. Bu kurallar, her agent araç çağrısına takılarak **başarısızlıkları tespit eder**, **bunları azaltır** (engelle, talimat ver, temizle) ve **dikkat gereken bir şey olduğunda sizi uyarır**. Yerel bir pano, sonrasında her araç çağrısını, agent başarısızlığını ve kurtarma eylemini incelemenizi sağlar. -Transkriptler ve politika değerlendirmesi makinenizde kalır. Veriler yalnızca doğrulanan denetim hatırlatıcıları veya davetler gibi çevrimiçi bir özelliği açıkça kullandığınızda gönderilir. +Transkriptler ve politika değerlendirmesi makinenizde kalır. Veriler, yalnızca kimlik doğrulamalı denetim anıştırmaları veya davetiyeler gibi çevrimiçi bir özelliği açık şekilde kullandığınızda gönderilir. -## Başlayın +## Başlangıç - Yıkıcı komutları engelleyin, gizli sızıntısını önleyin, aracıları proje sınırları içinde tutun ve daha pbirçok şey. Hepsi kutu içinde. + Yıkıcı komutları engelle, gizli dilimleri sızıntısını önle, agenlerinizi proje sınırları içinde tutun ve daha fazlası. Hepsi hazır durumdadır. - Basit allow / deny / instruct API'si ile JavaScript'te kendi kurallarınızı yazın. + Basit bir allow / deny / instruct API'si ile JavaScript'te kendi kurallarınızı yazın. - - Aracılarınız yokkenken ne yaptığını görün. Oturumları tarayın, araç çağrılarını inceleyin, politikaların nerede etkinleştiğini gözden geçirin. + + Agenlerinizin yokken neler yaptığını görün. Oturumları tarayın, araç çağrılarını inceleyin, politikaların nerede çalıştığını gözden geçirin. - Herhangi bir politikayı kod olmadan ayarlayın. İzin listelerini, korunan dalları veya eşikleri proje başına veya genel olarak ayarlayın. + Herhangi bir politikayı kod olmadan ayarlayın. İzin listelerini, korumalı dalları veya eşikleri proje başına veya genel olarak ayarlayın. @@ -50,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # politikaları etkinleştir (veya atla — `failproofai` ilk çalıştırmada bunları ayarlamayı teklif edecek) +failproofai policies --install # politikaları etkinleştir (veya atla — ilk çalıştırmada `failproofai` kurulumu teklif edecektir) failproofai # panoyu başlat ``` -Tam yer gösterimler için [Başlangıç](/tr/getting-started) kılavuzuna bakın. \ No newline at end of file +Tam kılavuz için [Başlangıç](/tr/getting-started) kılavuzuna bakın. \ No newline at end of file diff --git a/docs/tr/package-aliases.mdx b/docs/tr/package-aliases.mdx index 2efec383..aa6eb725 100644 --- a/docs/tr/package-aliases.mdx +++ b/docs/tr/package-aliases.mdx @@ -1,16 +1,16 @@ --- title: Paket Takma Adları -description: "Kayıtlı yazım hatası önleme takma adları ve nasıl çalıştıkları" +description: "Kayıtlı yazım yanlışı önleme takma adları ve bunların nasıl çalıştığı" icon: copy --- ## Resmi paket -Kanonik npm paketi **`failproofai`**: +Kanonik npm paketi **`failproofai`** dir: ```bash npm install -g failproofai -# or +# veya bun add -g failproofai ``` @@ -18,65 +18,65 @@ bun add -g failproofai ## Neden takma ad adlarına sahibiz -Yazım hatası ile kötüye kullanım, bir saldırganın popüler bir paket adından tek tuş kadar uzakta olan bir paket adını kaydettiği yaygın bir tedarik zinciri saldırısıdır. Kurulum komutunu yanlış yazan şüphelenmeyen kullanıcılar, saldırgana ait kod ile tam sistem erişimi sağlanarak çalıştırılır - tam olarak Failproof AI'nin savunmak için tasarlandığı tehdit türüdür. +Yazım yanlışı saldırısı (typosquatting), kötü niyetli bir aktörün popüler bir paketinkinden bir tuş uzağında olan bir paket adını kaydettiği yaygın bir tedarik zinciri saldırısıdır. Install komutunu yanlış yazan şüphelenmeyen kullanıcılar, tam sistem erişimi ile saldırgan kontrollü kodu çalıştırırlar - tam olarak Failproof AI'nin savunması için tasarlandığı tehdit türü. -Bu riski ortadan kaldırmak için, **npm üzerinde `failproofai`'nin tüm yaygın yazım hatalarına ve biçimlendirme varyantlarına proaktif olarak sahibiz**. Bu adlardan hiçbiri üçüncü taraf tarafından kayıtlanamaz. Her biri, gerçek `failproofai` paketini kuran ve ona devredilen ince bir proxy'dir. +Bu riski ortadan kaldırmak için, **`failproofai` ın tüm yaygın yazım yanlışları ve biçimlendirme varyantlarının sahibi olmayı önceden planladık** npm üzerinde. Bu adların hiçbiri üçüncü bir taraf tarafından kaydedilememektedir. Her biri, gerçek `failproofai` paketine yükler ve delegeler yapan ince bir vekil (proxy) dir. --- -## Kayıtlı takma adlar +## Kayıtlı takma adları **Biçimlendirme varyantları** - "failproof ai" yazmanın farklı yolları: | Paket | Durum | |---------|--------| -| `failproof` | ✅ Yayımlandı | +| `failproof` | ✅ Yayınlandı | | `failproof-ai` | ⏳ npm desteği bekleniyor | | `fail-proof-ai` | ⏳ npm desteği bekleniyor | | `failproof_ai` | ⏳ npm desteği bekleniyor | | `fail_proof_ai` | ⏳ npm desteği bekleniyor | | `fail-proofai` | ⏳ npm desteği bekleniyor | -**`failprof*` yazım hataları** - "proof" kelimesinden bir `o` eksik: +**`failprof*` yazım yanlışları** - "proof" ten bir `o` eksik: | Paket | Durum | |---------|--------| -| `failprof` | ✅ Yayımlandı | -| `failprof-ai` | ✅ Yayımlandı | +| `failprof` | ✅ Yayınlandı | +| `failprof-ai` | ✅ Yayınlandı | | `failprofai` | ⏳ npm desteği bekleniyor | | `fail-prof-ai` | ⏳ npm desteği bekleniyor | | `failprof_ai` | ⏳ npm desteği bekleniyor | -**`faliproof*` yazım hataları** - `a` ve `i` yer değişimi: +**`faliproof*` yazım yanlışları** - `a` ve `i` yer değişimi: | Paket | Durum | |---------|--------| -| `faliproof` | ✅ Yayımlandı | -| `faliproof-ai` | ✅ Yayımlandı | +| `faliproof` | ✅ Yayınlandı | +| `faliproof-ai` | ✅ Yayınlandı | | `faliproofai` | ⏳ npm desteği bekleniyor | -> **Neden bekleniyor?** npm'nin spam önleme politikası, noktalama işaretleri çıkarıldıktan sonra ve benzerlik kontrolleri yapıldıktan sonra mevcut bir paket ile aynı dizeye normalleşen adları engeller. Bu adları yazım hatası ile kötüye kullanımı önleme amaçlı rezerve etmek için npm desteğine başvurduk. Onaylandıktan sonra etkinleştirilecektir. +> **Neden bekleniyor?** npm'nin spam önleme politikası, noktalama işaretleri kaldırıldıktan ve benzerlik kontrolleri yapıldıktan sonra varolan bir paket ile aynı dizeye normalleştirilen adları engeller. Anti-squatting amaçları için bu adları ayırmak için npm desteğine başvurduk. Onaylı olduğunda etkinleştirilecektir. -Herhangi bir yayımlanmış takma adın bize ait olduğunu doğrulayabilirsiniz: +Yayınlanan herhangi bir takma adının bize ait olduğunu doğrulayabilirsiniz: ```bash npm info failproof -# Bak: maintainers alanında "ExosphereHost Inc." +# Bak: maintainers alanında "ExosphereHost Inc." için ``` --- -## Takma adlar nasıl çalışır +## Takma adları nasıl çalışırlar Her takma ad paketi: -1. `failproofai`'yi bir bağımlılık olarak listeler - böylece gerçek paket kurulur ve onun binary dosyası kullanılabilir hale gelir -2. Kendi adıyla eşleşen bir binary'yi (örneğin `failprof-ai`) açığa çıkarır ve tüm argümanları `failproofai` binary'sine proxy eder +1. `failproofai` öğesini bir bağımlılık olarak listeler - böylece gerçek paket kurulur ve ikili dosyası kullanılabilir hale gelir +2. Tüm argümanları `failproofai` ikili dosyasına vekil (proxy) yapmak için kendi adı ile eşleşen bir ikili dosya ortaya koymaktadır (örn. `failprof-ai`) -Proxy, iki satırlık bir Node scriptidir; hiçbir mantık, hiçbir ağ çağrısı ve `failproofai`'nin kendisinin yaptığı şeyden başka veri toplama yoktur. +Vekil, iki satırlık bir Node betiğidir; `failproofai` nin kendisinin yaptığı şeyin ötesinde hiç mantık, ağ çağrısı ve veri toplama yoktur. --- ## Kaçırdığımız bir ad bulursanız -[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) adresinde bir issue açın ve biz onu kaydedeceğiz. \ No newline at end of file +[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) adresinde bir issue açın ve bunu kaydedeceğiz. \ No newline at end of file diff --git a/docs/tr/testing.mdx b/docs/tr/testing.mdx index 84743c38..4f720b7a 100644 --- a/docs/tr/testing.mdx +++ b/docs/tr/testing.mdx @@ -1,11 +1,10 @@ --- ---- title: Test Etme -description: "Birim testleri, uçtan uca testleri ve test yardımcıları" +description: "Birim testleri, E2E testleri ve test yardımcıları" icon: flask-vial --- -failproofai iki test paketine sahiptir: **birim testleri** (hızlı, mock edilmiş) ve **uçtan uca testleri** (gerçek alt işlem çağrıları). +failproofai'nin iki test paketi vardır: **birim testleri** (hızlı, mock'lanmış) ve **uçtan uca testler** (gerçek subprocess çağrıları). --- @@ -21,10 +20,10 @@ bun run test # E2E testlerini çalıştır (kurulum gerekli - aşağıya bakın) bun run test:e2e -# Derleme yapmadan tür kontrolü yap +# Derleme olmadan tip denetimi yap bunx tsc --noEmit -# Lint kontrolü +# Lint kontrol et bun run lint ``` @@ -32,16 +31,16 @@ bun run lint ## Birim testleri -Birim testleri `__tests__/` içinde yaşar ve [Vitest](https://vitest.dev) ile `jsdom` kullanır. +Birim testleri `__tests__/` dizininde bulunur ve [Vitest](https://vitest.dev) ile `jsdom` kullanır. ```text __tests__/ hooks/ - builtin-policies.test.ts # Her yerleşik ilke için ilke mantığı - hooks-config.test.ts # Konfigürasyon yükleme ve kapsam birleştirme - policy-evaluator.test.ts # Parametre enjeksiyonu ve değerlendirme sırası - custom-hooks-registry.test.ts # globalThis kaydı ekle/al/temizle - custom-hooks-loader.test.ts # ESM yükleyici, geçişli içe aktarımlar, hata işleme + builtin-policies.test.ts # Her bir yerleşik politika için mantık + hooks-config.test.ts # Config yükleme ve scope birleştirme + policy-evaluator.test.ts # Param enjeksiyonu ve değerlendirme sırası + custom-hooks-registry.test.ts # globalThis kayıt defteri ekle/al/temizle + custom-hooks-loader.test.ts # ESM yükleyici, geçişli importlar, hata işleme manager.test.ts # yükle/kaldır/listele işlemleri components/ sessions-list.test.tsx # Oturum listesi bileşeni @@ -62,7 +61,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### İlke birim testi yazma +### Politika birim testi yazma ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -109,13 +108,13 @@ describe("block-sudo", () => { --- -## Uçtan uca testleri +## Uçtan uca testler -E2E testleri gerçek `failproofai` ikilisini alt işlem olarak çağırır, stdin'e bir JSON yükü gönderir ve stdout çıktısı ile çıkış koduna karşı doğrulama yapar. Bu, Claude Code'un kullandığı tam entegrasyon yolunu test eder. +E2E testleri gerçek `failproofai` ikili dosyasını subprocess olarak çalıştırır, stdin'e JSON yükü gönderir ve stdout çıktısı ile çıkış kodu üzerinde onaylama yapır. Bu, Claude Code'un kullandığı tam entegrasyon yolunu test eder. ### Kurulum -E2E testleri ikiliyi doğrudan depo kaynağından çalıştırır. İlk çalıştırmadan önce, özel kancı dosyalarının `'failproofai'`'den içe aktarırken kullandığı CJS paketini derleyin: +E2E testleri ikili dosyayı doğrudan repo kaynağından çalıştırır. İlk çalıştırma öncesinde, özel hook dosyalarının `'failproofai'`'den import yaparken kullandığı CJS paketini derleyin: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -127,21 +126,21 @@ Ardından testleri çalıştırın: bun run test:e2e ``` -Genel kancı API'sini değiştirdikçe (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` veya `src/hooks/policy-types.ts`) `dist/` yeniden derleyin. +Genel hook API'sini (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` veya `src/hooks/policy-types.ts`) değiştirdiğinizde `dist/` dizinini yeniden derleyin. ### E2E test yapısı ```text __tests__/e2e/ helpers/ - hook-runner.ts # İkiliyi başlat, yük JSON'ını gönder, çıkış kodu + stdout + stderr yakala - fixture-env.ts # Yapılandırma dosyaları ile test başına izole edilmiş geçici dizinler - payloads.ts # Her olay türü için Claude-doğru yük fabrikaları + hook-runner.ts # İkili dosyayı başlat, yük JSON'ını gönder, çıkış kodu + stdout + stderr yakala + fixture-env.ts # Her test için izole edilmiş geçici dizinler ve config dosyaları + payloads.ts # Her olay türü için Claude'ya uygun yük fabrikaları hooks/ - builtin-policies.e2e.test.ts # Gerçek alt işlem ile her yerleşik ilke - custom-hooks.e2e.test.ts # Özel kancı yükleme ve değerlendirmesi - config-scopes.e2e.test.ts # Proje/yerel/genel arasında yapılandırma birleştirme - policy-params.e2e.test.ts # Parametreli her ilke için parametre enjeksiyonu + builtin-policies.e2e.test.ts # Her bir yerleşik politika gerçek subprocess ile + custom-hooks.e2e.test.ts # Özel hook yükleme ve değerlendirme + config-scopes.e2e.test.ts # Proje/lokal/genel arasında config birleştirme + policy-params.e2e.test.ts # Parametreli her politika için parametre enjeksiyonu ``` ### E2E yardımcılarını kullanma @@ -152,8 +151,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - geçici dizin; .failproofai/policies-config.json'ı almak için payload.cwd olarak geçir -// env.home - izole edilmiş ev dizini; gerçek ~/.failproofai sızıntısı yok +// env.cwd - geçici dir; .failproofai/policies-config.json'ı almak için payload.cwd olarak geçin +// env.home - izole edilmiş home dir; gerçek ~/.failproofai sızıntısı yok env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -163,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` `afterEach` temizliğini otomatik olarak kaydeder. +`createFixtureEnv()` otomatik olarak `afterEach` temizliğini kaydeder. -**`runHook`** - ikiliyi çağır: +**`runHook`** - ikili dosyayı çağır: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -232,30 +231,30 @@ describe("block-rm-rf (E2E)", () => { }); ``` -### E2E yanıt şekilleri +### E2E yanıt biçimleri | Karar | Çıkış kodu | stdout | |----------|-----------|--------| | `PreToolUse` reddet | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` reddet | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Talimat (Stop dışında) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop talimatı | `2` | boş stdout; nedeni stderr'de | +| Talimat ver (Stop olmayan) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Stop talimatı | `2` | boş stdout; neden stderr'de | | İzin ver | `0` | boş dize | -### Vitest yapılandırması +### Vitest konfigürasyonu -E2E testleri `vitest.config.e2e.mts` ile kullanır: +E2E testleri `vitest.config.e2e.mts` ile şu özellikler kullanır: -- `environment: "node"` - tarayıcı globals gerekli değil -- `pool: "forks"` - gerçek işlem izolasyonu (testler alt işlemler başlatır) -- `testTimeout: 20_000` - test başına 20s (ikili başlatma + kancı değerlendirmesi) +- `environment: "node"` - tarayıcı global değişkenleri gerekli değil +- `pool: "forks"` - gerçek süreç izolasyonu (testler subprocess başlatır) +- `testTimeout: 20_000` - test başına 20 saniye (ikili başlangıç + hook değerlendirmesi) -`forks` havuzu önemlidir: iş parçacığı tabanlı çalışanlar `globalThis` paylaşırlar, bu da alt işlem başlatma testlerini etkileyebilir. İşlem tabanlı forklar bunu önler. +`forks` havuzu önemlidir: thread tabanlı workers `globalThis` paylaşır ve bu subprocess başlatma testlerini engelleyebilir. Process tabanlı forks bunu önler. --- ## CI -Tam CI çalıştırması (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) birleştirmeden önce geçmesi gerekir. E2E paketi paralel olarak ayrı bir CI işi olarak çalışır. +Tam CI çalıştırması (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) birleştirmeden önce geçmesi gerekir. E2E paketi ayrı bir CI işi olarak paralel olarak çalışır. -Tam birleştirme öncesi kontrol listesi için [Katkı](../CONTRIBUTING.md)'ya bakın. \ No newline at end of file +Tam ön birleştirme kontrol listesi için [Katkı Sağlama](../CONTRIBUTING.md) sayfasına bakın. \ No newline at end of file diff --git a/docs/vi/agenteye/alerts.mdx b/docs/vi/agenteye/alerts.mdx index 01b5e42c..267a61c7 100644 --- a/docs/vi/agenteye/alerts.mdx +++ b/docs/vi/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "Cảnh báo" -description: "Phát hiện ngay khi có vấn đề vượt quá ngưỡng của bạn, trên kênh mà nhóm của bạn đã theo dõi, thay vì nghe từ khách hàng." +description: "Nhận thông báo ngay lập tức khi có vấn đề, trên kênh mà nhóm bạn đã theo dõi, thay vì nghe từ khách hàng." --- -Phát hiện ngay khi có vấn đề vượt quá ngưỡng của bạn, trên kênh mà nhóm của bạn đã theo dõi, thay vì nghe từ khách hàng. Đặt một quy tắc một lần và Failproof AI Observability kiểm tra nó theo lịch trình, sau đó gửi thông báo cho bạn qua email, Slack, webhook, hoặc ngay trên bảng điều khiển. +Nhận thông báo ngay lập tức khi có vấn đề, trên kênh mà nhóm bạn đã theo dõi, thay vì nghe từ khách hàng. Đặt quy tắc một lần và Failproof AI Observability sẽ kiểm tra nó theo lịch trình, sau đó gửi thông báo qua email, Slack, webhook hoặc trực tiếp trên bảng điều khiển. -![Trang Cảnh báo: một lưới các thẻ quy tắc cảnh báo, mỗi thẻ hiển thị kích hoạt của nó, cửa sổ đánh giá, kênh và một huy hiệu mức độ nghiêm trọng thông tin, cảnh báo hoặc quan trọng](/agenteye/images/alerts.png) -*Mỗi quy tắc cảnh báo trong một cái nhìn: nó theo dõi cái gì, tần suất bao nhiêu, nơi nó gửi thông báo, và mức độ khẩn cấp như thế nào.* +![Trang Cảnh báo: một lưới các thẻ quy tắc cảnh báo, mỗi thẻ hiển thị kích hoạt, cửa sổ đánh giá, các kênh và huy hiệu mức độ nghiêm trọng thông tin, cảnh báo hoặc quan trọng](/agenteye/images/alerts.png) +*Mọi quy tắc cảnh báo một cái nhìn tổng quát: nó theo dõi cái gì, tần suất bao nhiêu, gửi thông báo ở đâu và mức độ khẩn cấp như thế nào.* -## Biết về các vấn đề trước khi người dùng của bạn biết +## Biết về các vấn đề trước khi người dùng của bạn phát hiện -Ngừng làm mới bảng điều khiển hy vọng bắt kịp một lùi. Sử dụng cảnh báo bất cứ khi nào có tín hiệu mà bạn muốn biết ngay cả khi không ai đang theo dõi, và gửi nó đến nơi bạn đã có: +Ngừng làm mới bảng điều khiển hy vọng bắt được sự thoái lui. Hãy sử dụng cảnh báo bất cứ khi nào có tín hiệu bạn muốn biết ngay cả khi không ai đang theo dõi, và để nó đến nơi bạn đã có: -- **Email**, cho bất cứ ai cần biết. -- **Slack**, một tin nhắn phong phú với nút bấm nhảy thẳng đến sự cố. -- **Webhook**, một JSON POST cho PagerDuty, Opsgenie, hoặc điểm cuối của riêng bạn, với chữ ký tùy chọn để người nhận có thể tin tưởng nó. -- **Trên bảng điều khiển**, yên tĩnh theo thiết kế, khi bạn điều chỉnh một quy tắc và không muốn thông báo cho ai cả. +- **Email**, cho những người cần biết. +- **Slack**, một tin nhắn phong phú với nút sẽ nhảy thẳng đến sự cố. +- **Webhook**, một JSON POST cho PagerDuty, Opsgenie hoặc endpoint của riêng bạn, với chữ ký tùy chọn để người nhận có thể tin tưởng. +- **Trên bảng điều khiển**, yên tĩnh theo thiết kế, dành cho khi bạn điều chỉnh quy tắc và không muốn gửi thông báo cho ai cả. -Gắn kết bất kỳ sự kết hợp nào vào một quy tắc duy nhất, và mức độ nghiêm trọng của nó (thông tin, cảnh báo hoặc quan trọng) đi kèm để những quy tắc khẩn cấp trông khẩn cấp. +Đính kèm bất kỳ tổ hợp nào vào một quy tắc duy nhất, và mức độ nghiêm trọng của nó (thông tin, cảnh báo hoặc quan trọng) sẽ đi kèm để những quy tắc khẩn cấp trông khẩn cấp. ## Xây dựng quy tắc trong một biểu mẫu, không phải JSON -Bạn mô tả điều gì có nghĩa là "bị hỏng" trong một biểu mẫu, và Failproof AI Observability viết quy tắc cơ bản cho bạn. Thông số kỹ thuật JSON chỉ là những gì biểu mẫu đó tạo ra dưới nắp động cơ, vì vậy bạn có thể đọc nó để hiểu một quy tắc nhưng bạn hiếm khi nhập nó. +Bạn mô tả "hỏng" có nghĩa là gì trong một biểu mẫu, và Failproof AI Observability sẽ viết quy tắc cơ bản cho bạn. Thông số kỹ thuật JSON chỉ là những gì biểu mẫu đó tạo ra bên dưới, vì vậy bạn có thể đọc nó để hiểu quy tắc nhưng bạn hiếm khi nhập nó. -![Biểu mẫu cảnh báo mới: tên và mô tả, bộ chuyển đổi bật, và một bộ chọn kích hoạt cung cấp ngưỡng metric, SQL tùy chỉnh, điểm đánh giá, đánh giá compound, và các điều kiện cho mỗi sự kiện](/agenteye/images/alert-new.png) -*Chọn một kích hoạt và biểu mẫu hoán đổi các trường phù hợp; Lưu viết quy tắc.* +![Biểu mẫu cảnh báo mới: tên và mô tả, công tắc bật, và bộ chọn kích hoạt cung cấp ngưỡng chỉ số, SQL tùy chỉnh, điểm đánh giá, đánh giá ghép và điều kiện theo sự kiện](/agenteye/images/alert-new.png) +*Chọn một kích hoạt và biểu mẫu sẽ hoán đổi các trường thích hợp; Lưu sẽ viết quy tắc.* -Con đường hạnh phúc là nhanh: đặt tên cho nó, chọn một **kích hoạt** (cái gì cần theo dõi), đặt **ngưỡng và cửa sổ** (tệ như thế nào, trong bao lâu), gắn kết ít nhất một **kênh**, sau đó **Lưu** và nhấn **Kiểm tra** để kích hoạt một thông báo tổng hợp và xác nhận mọi đích đến đã được kết nối. Dưới nắp động cơ điều đó tạo ra một thông số kỹ thuật nhỏ như: +Con đường hạnh phúc rất nhanh: đặt tên cho nó, chọn **kích hoạt** (cái gì cần theo dõi), đặt **ngưỡng và cửa sổ** (tồi tệ bao nhiêu, trong bao lâu), đính kèm ít nhất một **kênh**, sau đó **Lưu** và bấm **Kiểm tra** để kích hoạt thông báo tổng hợp và xác nhận mọi đích đến được kết nối. Bên dưới đó tạo ra một thông số kỹ thuật nhỏ như: ```json { "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 } ``` -Bạn không bị giới hạn ở một loại tín hiệu. Chọn kích hoạt phù hợp với cách bạn nghĩ về lỗi: +Bạn không bị giới hạn chỉ một loại tín hiệu. Chọn kích hoạt phù hợp với cách bạn suy nghĩ về sự cố: | Kích hoạt | Kích hoạt khi | |---|---| -| **Ngưỡng metric** | một metric được định sẵn (tỷ lệ lỗi, độ trễ p95 hoặc p99, số sự kiện hoặc lỗi, chi phí token) vượt quá ngưỡng của bạn trong một cửa sổ | -| **SQL tùy chỉnh** | truy vấn chỉ đọc của riêng bạn trả về một hàng, hoặc một giá trị nó tính toán vượt quá ngưỡng | -| **Điểm đánh giá** | trung bình điểm của một người đánh giá (ví dụ, ảo tưởng) vượt quá ngưỡng | -| **Đánh giá compound** | nhiều kiểm tra điểm kết hợp với bất kỳ, tất cả, hoặc logic ít nhất-N, để bắt một lùi chỉ xuất hiện trên các điểm | -| **Cho mỗi sự kiện** | một sự kiện khớp đơn lẻ đến: một agent cụ thể, một loại lỗi cụ thể, hoặc một chuỗi con tin nhắn | +| **Ngưỡng chỉ số** | một chỉ số được đặt trước (tỷ lệ lỗi, p95 hoặc độ trễ p99, số sự kiện hoặc lỗi, chi tiêu token) vượt quá giới hạn của bạn trong một cửa sổ | +| **SQL tùy chỉnh** | truy vấn chỉ đọc của riêng bạn trả về một hàng hoặc giá trị nó tính toán vượt quá ngưỡng | +| **Điểm đánh giá** | trung bình điểm đánh giá (ví dụ: ảo tưởng) vượt quá ngưỡng | +| **Đánh giá ghép** | nhiều kiểm tra điểm kết hợp với bất kỳ, tất cả hoặc logic ít nhất N, để bắt được sự thoái lui chỉ hiển thị trên các điểm | +| **Theo sự kiện** | một sự kiện khớp duy nhất đến: một agent cụ thể, một loại lỗi cụ thể hoặc chuỗi con tin nhắn | -Đã staring tại một lỗi trên [trang Lỗi](/vi/agenteye/error-tracking)? Mỗi hàng ở đó có nút **+ alert** mở cùng biểu mẫu này được điền sẵn để bắt lỗi chính xác đó lại, vì vậy sự cố bạn vừa phân loại trở thành sự cố sẽ gửi cho bạn lần tiếp theo. +Đã nhìn thấy sự cố trên [trang Lỗi](/vi/agenteye/error-tracking)? Mọi hàng ở đó đều có nút **+ cảnh báo** sẽ mở cùng biểu mẫu này được điền trước để bắt lại chính xác sự cố đó, vì vậy sự cố bạn vừa phân loại sẽ trở thành sự cố sẽ gửi thông báo cho bạn lần tới. -**Nơi tìm thấy nó:** Cảnh báo nằm ở `//alerts`. Tạo, chỉnh sửa, xóa và kiểm tra quy tắc cần **`alerts:write`**; `alerts:read` là đủ để xem. Bộ chọn người nhận liệt kê các thành viên của tổ chức bạn theo tên, vì vậy bạn có thể gửi thông báo cho một người mà không cần rời khỏi biểu mẫu. +**Nơi tìm kiếm:** Cảnh báo nằm tại `//alerts`. Tạo, chỉnh sửa, xóa và kiểm tra quy tắc cần **`alerts:write`**; `alerts:read` là đủ để xem. Bộ chọn người nhận liệt kê các thành viên của tổ chức bạn theo tên, vì vậy bạn có thể gửi thông báo cho một người mà không cần rời khỏi biểu mẫu. -## Chỉ gửi cho tôi khi nó là thật +## Chỉ gửi thông báo cho tôi khi nó là thực tế -Một phép đo xấu không nên làm bạn thức dậy. Bộ lọc nhiễu **M của N** kiểm soát có bao nhiêu trong số những kiểm tra gần đây phải thất bại trước khi cảnh báo thực sự gửi cho bạn. Đặt nó thành **3 của 5** và quy tắc kích hoạt chỉ sau khi nó đã vi phạm ba trong năm kiểm tra gần đây của nó, vì vậy tín hiệu không ổn định sẽ ngừng gây sốt; để nó ở mức mặc định **1 của 1** để kích hoạt khi vi phạm đầu tiên. Bạn cũng chọn tần suất chạy quy tắc, từ các preset của 1m, 5m, 15m và 1h, phù hợp với tốc độ tín hiệu thực sự di chuyển. +Một phép đo xấu không nên làm bạn thức dậy. Bộ lọc nhiễu **M of N** kiểm soát bao nhiêu trong số các kiểm tra cuối cùng phải không thành công trước khi cảnh báo thực sự gửi thông báo cho bạn. Đặt nó thành **3 of 5** và quy tắc sẽ kích hoạt chỉ sau khi nó đã vi phạm ba trong năm kiểm tra cuối cùng, vì vậy tín hiệu không ổn định sẽ ngừng kêu gọi; để nó ở mặc định **1 of 1** để kích hoạt ngay lần đầu tiên vi phạm. Bạn cũng chọn tần suất chạy quy tắc, từ các cài đặt sẵn là 1m, 5m, 15m và 1h, phù hợp với tốc độ thực sự của tín hiệu. -## Điều gì xảy ra khi một cảnh báo kích hoạt +## Điều gì xảy ra khi cảnh báo kích hoạt -Một vi phạm mở một **sự cố** và gửi thông báo cho các kênh của bạn một lần. Từ đó nhóm của bạn xác nhận nó, gán một chủ sở hữu, thảo luận nó, và giải quyết nó, tất cả so với một bản ghi sạch và được ghi. Quy trình phân loại đó có nhà riêng: xem [Sự cố](/vi/agenteye/incidents). +Vi phạm sẽ mở một **sự cố** và gửi thông báo cho các kênh của bạn một lần. Từ đó nhóm của bạn sẽ xác nhận nó, chỉ định chủ sở hữu, thảo luận và giải quyết nó, tất cả dựa trên hồ sơ sạch sẽ được quy trách. Quy trình phân loại đó có nhà riêng: xem [Sự cố](/vi/agenteye/incidents). ## Liên quan -- [Sự cố](/vi/agenteye/incidents): theo dõi một cảnh báo kích hoạt từ mở đến xác nhận đến đã giải quyết. -- [Theo dõi lỗi](/vi/agenteye/error-tracking): nhóm các lỗi agent và quảng bá một lỗi thành cảnh báo chỉ bằng một cú nhấp chuột. -- [Bảng điều khiển](/vi/agenteye/dashboards): theo dõi các bảng chia sẻ mà các ngưỡng bạn cảnh báo đến từ. -- [CLI và agents](/vi/agenteye/cli-and-agents): tạo cảnh báo và xác nhận sự cố từ terminal của bạn, hoặc script chúng vào CI. \ No newline at end of file +- [Sự cố](/vi/agenteye/incidents): theo dõi cảnh báo kích hoạt từ mở đến được xác nhận đến được giải quyết. +- [Theo dõi lỗi](/vi/agenteye/error-tracking): nhóm các lỗi của agent và nâng cao một lên cảnh báo chỉ bằng một cú nhấp chuột. +- [Bảng điều khiển](/vi/agenteye/dashboards): theo dõi các bảng dùng chung các ngưỡng bạn cảnh báo đến từ đó. +- [CLI và agents](/vi/agenteye/cli-and-agents): tạo cảnh báo và xác nhận sự cố từ terminal của bạn, hoặc tập lệnh chúng vào CI. \ No newline at end of file diff --git a/docs/vi/agenteye/api-keys.mdx b/docs/vi/agenteye/api-keys.mdx index e0e13c65..3ba2d157 100644 --- a/docs/vi/agenteye/api-keys.mdx +++ b/docs/vi/agenteye/api-keys.mdx @@ -1,173 +1,173 @@ --- -title: "API Keys" -description: "API keys kiểm soát ai và những gì có thể tiếp cận máy chủ Failproof AI Observability của bạn, vì vậy một collector có thể gửi sự kiện mà không bao giờ có được quyền đọc hoặc quyền admin." +title: "Khóa API" +description: "Khóa API kiểm soát ai và cái gì có thể truy cập máy chủ Failproof AI Observability của bạn, vì vậy một bộ sưu tập có thể gửi sự kiện mà không bao giờ có quyền đọc hoặc quản trị viên." --- -API keys kiểm soát ai và những gì có thể tiếp cận máy chủ Failproof AI Observability của bạn, vì vậy một collector có thể gửi sự kiện mà không bao giờ có được quyền đọc hoặc quyền admin. Mỗi key mang một hoặc nhiều quyền, và mỗi quyền kiểm soát các route máy chủ cụ thể; bạn chỉ cấp những quyền mà công việc cần. Hầu hết các triển khai chỉ tạo ba loại key. +Khóa API kiểm soát ai và cái gì có thể truy cập máy chủ Failproof AI Observability của bạn, vì vậy một bộ sưu tập có thể gửi sự kiện mà không bao giờ có quyền đọc hoặc quản trị viên. Mỗi khóa mang một hoặc nhiều quyền hạn, và mỗi quyền hạn kiểm soát các tuyến máy chủ cụ thể; bạn chỉ cấp những quyền hạn mà một công việc cần. Hầu hết các triển khai chỉ tạo ba loại khóa. -## 3 key mà hầu hết các triển khai cần +## Ba khóa mà hầu hết các triển khai cần -| Key | Quyền | Ai sử dụng | +| Khóa | Quyền hạn | Ai sử dụng nó | |---|---|---| -| Collector key | `events:add` | `agenteye-collector` trên mỗi máy agent, để gửi sự kiện. | -| Dashboard read key | `events:read`, `keys:read` | Một nhà điều hành chỉ đọc hoặc tích hợp truy vấn dữ liệu mà không thay đổi nó. | -| Bootstrap admin key | tất cả quyền | Nhà điều hành đưa instance lên lần đầu tiên (và dashboard). Được khởi tạo từ biến môi trường `ADMIN_KEY`. Xem [Bootstrap admin key](#bootstrap-admin-key). | +| Khóa bộ sưu tập | `events:add` | `agenteye-collector` trên mỗi máy agent, để gửi sự kiện. | +| Khóa đọc bảng điều khiển | `events:read`, `keys:read` | Một nhà điều hành hoặc tích hợp chỉ đọc truy vấn dữ liệu mà không thay đổi nó. | +| Khóa bootstrap quản trị viên | tất cả quyền hạn | Nhà điều hành lần đầu tiên khởi động instance (và bảng điều khiển). Được hạt giống từ biến môi trường `ADMIN_KEY`. Xem [Khóa bootstrap quản trị viên](#bootstrap-admin-key). | -Bắt đầu từ đây. Chỉ sử dụng danh mục quyền đầy đủ dưới đây khi bạn cần một key tùy chỉnh hạn chế hơn. Xem thêm [Recommended key layout](#recommended-key-layout) và [Creating keys](#creating-keys). +Bắt đầu ở đây. Tham khảo danh mục quyền hạn đầy đủ dưới đây chỉ khi bạn cần một khóa có phạm vi hẹp hơn và tùy chỉnh. Xem thêm [Bố cục khóa được đề xuất](#recommended-key-layout) và [Tạo khóa](#creating-keys). --- -## Quyền +## Quyền hạn -Máy chủ thực thi một danh mục quyền cố định; mỗi cái kiểm soát các route HTTP cụ thể. Một **admin key** nắm giữ tất cả chúng; một key có phạm vi nắm giữ tập hợp con bạn cấp khi tạo. Các chuỗi quyền không xác định bị từ chối khi tạo key. +Máy chủ thực thi một danh mục cố định các quyền hạn; mỗi cái kiểm soát các tuyến HTTP cụ thể. Một **khóa quản trị viên** giữ tất cả chúng; một khóa có phạm vi giữ tập con bạn cấp khi tạo. Các chuỗi quyền hạn không rõ sẽ bị từ chối khi một khóa được tạo. -> **Lưu ý:** Hai quyền hợp lệ chỉ dành cho dashboard con người và không thể được cấp cho API key: `orgs:admin` (quản trị instance, chỉ dành cho nhà điều hành) và `keys:update`. Một yêu cầu `POST /keys` hoặc `PATCH /keys/:id` cố gắng cấp một trong hai quyền bị từ chối với HTTP 422. Xem hàng `keys:update` dưới đây để biết lý do tại sao một bearer key có thể tạo key nhưng không bao giờ chỉnh sửa chúng. +> **Lưu ý:** Hai quyền hạn hợp lệ chỉ dành cho con người/bảng điều khiển và không thể được cấp cho khóa API: `orgs:admin` (quản trị instance, chỉ dành cho nhà điều hành) và `keys:update`. Một yêu cầu `POST /keys` hoặc `PATCH /keys/:id` cố gắng cấp một trong hai quyền sẽ bị từ chối với HTTP 422. Xem hàng `keys:update` dưới đây để biết tại sao một khóa bearer có thể tạo khóa nhưng không bao giờ chỉnh sửa chúng. -### Events ingest & query +### Nhập & truy vấn sự kiện -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `events:add` | `POST /events` | Nhập các lô sự kiện từ một collector. Quyền duy nhất mà một collector cần. | -| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Truy vấn sự kiện, liệt kê các môi trường đã biết, liệt kê các định danh mô hình được nhìn thấy trong dữ liệu (được sử dụng bởi chế độ xem Models và bộ lọc mô hình), tính toán tổng hợp độ trễ cung cấp năng lượng cho heat-map / dải phần trăm, và xuất phiên dưới dạng JSONL. Các endpoint facet bộ lọc chung `GET /events/environments` và `GET /events/agent_ids` có thể truy cập được với **bất kỳ** `events:read` **hoặc** `evaluations:read`, vì vậy trang sessions (gated `evaluations:read`) sử dụng lại cùng một facet mỗi tổ chức. `GET /events/models` không phải là một trong số đó: nó yêu cầu `events:read`, vì vậy một principal chỉ nắm giữ `evaluations:read` nhận được 403 từ nó. | +| `events:add` | `POST /events` | Nhập các loạt sự kiện từ một bộ sưu tập. Quyền hạn duy nhất mà một bộ sưu tập cần. | +| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Truy vấn sự kiện, liệt kê các môi trường được biết đến, liệt kê các định danh mô hình được nhìn thấy trong dữ liệu (được sử dụng bởi chế độ xem Mô hình và bộ lọc mô hình), tính toán tổng hợp độ trễ hỗ trợ bản đồ nhiệt / dải phần trăm, và xuất phiên dưới dạng JSONL. Các điểm cuối khía cạnh thanh lọc được chia sẻ `GET /events/environments` và `GET /events/agent_ids` có thể truy cập được với **hoặc** `events:read` **hoặc** `evaluations:read`, vì vậy trang phiên (cổng `evaluations:read`) sử dụng lại cùng một khía cạnh mỗi tổ chức. `GET /events/models` không phải là một trong số đó: nó yêu cầu `events:read`, vì vậy một nguyên tắc chỉ giữ `evaluations:read` sẽ nhận 403 từ nó. | -### Sessions & evaluations +### Phiên & đánh giá -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Liệt kê phiên, đọc kết quả đánh giá, tình trạng eval được tóm gọn lại được sử dụng bởi dashboard, và trạng thái hàng đợi worker công việc đánh giá. | -| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Thủ công đưa một phiên hoàn tất vào hàng đợi đánh giá lại. | +| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Liệt kê phiên, đọc kết quả đánh giá, sức khỏe eval được tổng hợp được sử dụng bởi bảng điều khiển, và trạng thái hàng đợi công nhân công việc đánh giá. | +| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Thủ công xếp hàng đợi một đánh giá lại cho một phiên đã kết thúc. | -### Dashboards +### Bảng điều khiển -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Liệt kê dashboard, tải một cái, và đọc các tile của nó. | -| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Tạo và chỉnh sửa dashboard, thêm / chỉnh sửa / xóa tile, và sắp xếp lại lưới tile. | -| `dashboards:delete` | `DELETE /dashboards/:id` | Xóa toàn bộ một dashboard (xóa cấp độ tile nằm trong `dashboards:write`). | +| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Liệt kê bảng điều khiển, tải một bảng, và đọc các ô của nó. | +| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Tạo và chỉnh sửa bảng điều khiển, thêm / chỉnh sửa / loại bỏ ô, và sắp xếp lại lưới ô. | +| `dashboards:delete` | `DELETE /dashboards/:id` | Xóa toàn bộ bảng điều khiển (xóa cấp ô nằm dưới `dashboards:write`). | -### Saved queries (SQL composer) +### Truy vấn đã lưu (Trình soạn SQL) -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Liệt kê các truy vấn đã lưu, tải một cái, và kiểm tra schema chỉ đọc mà composer nhắm đến. | -| `queries:write` | `POST /queries`, `PUT /queries/:id` | Tạo và chỉnh sửa các truy vấn đã lưu. SQL vẫn được định tuyến qua cùng một role chỉ đọc và các kiểm tra SQL được bảo vệ như một lệnh gọi `queries:run`. | +| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Liệt kê truy vấn đã lưu, tải một truy vấn, và kiểm tra schema chỉ đọc mà trình soạn nhắm tới. | +| `queries:write` | `POST /queries`, `PUT /queries/:id` | Tạo và chỉnh sửa truy vấn đã lưu. SQL vẫn được định tuyến qua cùng một vai trò chỉ đọc và kiểm tra SQL được bảo vệ như một cuộc gọi `queries:run`. | | `queries:delete` | `DELETE /queries/:id` | Xóa một truy vấn đã lưu. | -| `queries:run` | `POST /queries/run` | Thực thi SQL đã lưu hoặc ad-hoc cho role chỉ đọc được sử dụng bởi composer. | +| `queries:run` | `POST /queries/run` | Thực hiện SQL được lưu hoặc ad-hoc lên vai trò chỉ đọc được sử dụng bởi trình soạn. | -### AI assistant +### Trợ lý AI -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Nói chuyện với trợ lý AI và quản lý các cuộc trò chuyện của riêng bạn (private). Cần thiết trên **người dùng** để xem dock trợ lý; key của trợ lý tự nó là `dashboard-assistant` và được khởi tạo riêng (xem dưới đây). | +| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Trò chuyện với trợ lý AI và quản lý các cuộc trò chuyện của riêng bạn (riêng tư). Bắt buộc trên **người dùng** để xem dock trợ lý; khóa của chính trợ lý là `dashboard-assistant` và được hạt giống riêng biệt (xem dưới đây). | -### API keys +### Khóa API -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `keys:create` | `POST /keys` | Tạo một API key có phạm vi mới. **Không** cấp việc chỉnh sửa quyền của key hiện tại (đó là `keys:update`). | -| `keys:read` | `GET /keys` | Liệt kê các key hiện tại. Secrets không bao giờ được trả lại bởi endpoint này. | -| `keys:update` | `PATCH /keys/:id` | Chỉnh sửa quyền của key hiện tại. Một quyền **chỉ dành cho dashboard con người**; nó không thể được gán cho API key (một bearer key có thể tạo key nhưng không bao giờ chỉnh sửa chúng). | -| `keys:disable` | `POST /keys/:id/disable` | Thu hồi một key. Các key được bảo vệ (`admin`, `dashboard-assistant`) không thể bị vô hiệu hóa; xoay chúng qua biến env + khởi động lại. | -| `keys:regenerate` | `POST /keys/:id/regenerate` | Xoay secret của key. Các key được bảo vệ không thể được tái tạo thông qua route này. | +| `keys:create` | `POST /keys` | Tạo một khóa API có phạm vi mới. Làm **không** cấp chỉnh sửa quyền hạn của khóa hiện tại (đó là `keys:update`). | +| `keys:read` | `GET /keys` | Liệt kê các khóa hiện tại. Bí mật không bao giờ được trả lại bởi điểm cuối này. | +| `keys:update` | `PATCH /keys/:id` | Chỉnh sửa quyền hạn của một khóa hiện tại. Một quyền hạn **chỉ dành cho con người/bảng điều khiển**; nó không thể được gán cho một khóa API (một khóa bearer có thể tạo khóa nhưng không bao giờ chỉnh sửa chúng). | +| `keys:disable` | `POST /keys/:id/disable` | Khóa một khóa. Các khóa được bảo vệ (`admin`, `dashboard-assistant`) không thể bị tắt; xoay chúng qua biến env + khởi động lại. | +| `keys:regenerate` | `POST /keys/:id/regenerate` | Xoay bí mật của một khóa. Các khóa được bảo vệ không thể được tạo lại thông qua tuyến này. | -### Dashboard users +### Người dùng bảng điều khiển -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `users:create` | `POST /users`, `GET /users/defaults` | Mời một người dùng dashboard mới (phát hành email + one-time passcode (OTP) login) và đọc tập hợp quyền mặc định được cấu hình dashboard được sử dụng để khởi tạo biểu mẫu mời. | +| `users:create` | `POST /users`, `GET /users/defaults` | Mời một người dùng bảng điều khiển mới (phát hành email + đăng nhập mã lần duy nhất (OTP)) và đọc tập quyền hạn mặc định được cấu hình bảng điều khiển được sử dụng để hạt giống biểu mẫu lời mời. | | `users:read` | `GET /users`, `GET /users/:id` | Liệt kê người dùng và tải một bản ghi người dùng duy nhất. | -| `users:update` | `PUT /users/:id` | Chỉnh sửa quyền của người dùng. Cập nhật gửi email thay đổi quyền đến người dùng bị ảnh hưởng và có hiệu lực khi yêu cầu tiếp theo của họ; không cần đăng nhập lại. | -| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Vô hiệu hóa một người dùng (thu hồi các phiên của họ ngay lập tức) và kích hoạt lại một người dùng đã bị vô hiệu hóa trước đó. | +| `users:update` | `PUT /users/:id` | Chỉnh sửa quyền hạn của một người dùng. Cập nhật gửi email thay đổi quyền hạn cho người dùng bị ảnh hưởng và có hiệu lực khi yêu cầu tiếp theo của họ; không cần đăng nhập lại. | +| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Vô hiệu hóa một người dùng (khóa phiên của họ ngay lập tức) và bật lại một người dùng đã bị vô hiệu hóa trước đó. | -Các quyền này hỗ trợ trang **Users** của dashboard, nơi mà các phạm vi được cấp của mỗi thành viên được hiển thị dưới dạng chip: +Những quyền hạn này hỗ trợ trang **Người dùng** của bảng điều khiển, nơi các phạm vi được cấp của mỗi thành viên được hiển thị dưới dạng chip: -![Trang Users: một thẻ cho mỗi người dùng dashboard với email, quyền được cấp, và điều khiển chỉnh sửa/vô hiệu hóa của họ](/agenteye/images/users.png) +![Trang Người dùng: một thẻ cho mỗi người dùng bảng điều khiển với email, quyền hạn được cấp và điều khiển chỉnh sửa/vô hiệu hóa của họ](/agenteye/images/users.png) -### Operational settings +### Cài đặt hoạt động -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Xem các cài đặt hoạt động được quản lý bằng dashboard và siêu dữ liệu của chúng; liệt kê các ghi đè cửa sổ ngữ cảnh mỗi mô hình; và giải quyết cửa sổ hiệu quả cho một mô hình. | -| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Chỉnh sửa các cài đặt hoạt động và thêm, thay đổi, hoặc xóa các ghi đè cửa sổ ngữ cảnh mỗi mô hình. Các thay đổi ảnh hưởng đến các sự kiện mới mà không cần khởi động lại máy chủ. | +| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Xem cài đặt hoạt động được quản lý bảng điều khiển và metadata của chúng; liệt kê ghi đè cửa sổ bối cảnh mỗi mô hình; và giải quyết cửa sổ hiệu quả cho một mô hình. | +| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Chỉnh sửa cài đặt hoạt động và thêm, thay đổi hoặc loại bỏ ghi đè cửa sổ bối cảnh mỗi mô hình. Những thay đổi ảnh hưởng đến các sự kiện mới mà không cần khởi động lại máy chủ. | -![Trang Settings: các cài đặt hoạt động được quản lý bằng dashboard như đăng nhập được phép và tuổi thọ session/OTP, có thể chỉnh sửa mà không cần khởi động lại](/agenteye/images/settings.png) +![Trang Cài đặt: cài đặt hoạt động được quản lý bảng điều khiển như các đăng nhập được phép và thời gian sống phiên/OTP, có thể chỉnh sửa mà không cần khởi động lại](/agenteye/images/settings.png) -### Alerts & incidents +### Cảnh báo & sự cố -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| | `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Xem các định nghĩa cảnh báo được cấu hình. | -| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Tạo, chỉnh sửa, xóa, và test-fire các định nghĩa cảnh báo. | -| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Xem các incident và dấu vết triage của chúng. | -| `incidents:write` | `POST /alerts/:id/incidents` | Mở một incident theo cách thủ công đối với một cảnh báo hiện tại. | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Xác nhận, gán, giải quyết, và bình luận trên incident. | +| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Tạo, chỉnh sửa, xóa và phát cảnh báo thử nghiệm các định nghĩa cảnh báo. | +| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Xem các sự cố và vết triage của chúng. | +| `incidents:write` | `POST /alerts/:id/incidents` | Mở một sự cố thủ công chống lại một cảnh báo hiện tại. | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Xác nhận, gán, giải quyết và bình luận về các sự cố. | -### Audits +### Kiểm toán -| Quyền | HTTP routes | Những gì nó cho phép | +| Quyền hạn | Tuyến HTTP | Nó cho phép gì | |---|---|---| -| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Xem các định nghĩa audit, lịch sử chạy, và những phát hiện. | -| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Tạo, chỉnh sửa, xóa, và chạy audit; triage finding (xác nhận / im lặng / bỏ qua / giải quyết / mở lại / gán). | +| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Xem các định nghĩa kiểm toán, lịch sử chạy và kết quả phát hiện. | +| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Tạo, chỉnh sửa, xóa và chạy kiểm toán; triage phát hiện (xác nhận / tắt tiếng / loại bỏ / giải quyết / mở lại / gán). | -> **Lưu ý:** Để cấp cho key bề mặt audit, cấp `audits:*` cho nó một cách rõ ràng. Xem [Upgrade and backward-compatibility notes](#upgrade-and-backward-compatibility-notes) để biết các grantee hiện tại được di chuyển khi Audits vận hành. +> **Lưu ý:** Để cấp cho một khóa bề mặt kiểm toán, cấp `audits:*` cho nó một cách rõ ràng. Xem [Ghi chú nâng cấp và tương thích ngược](#upgrade-and-backward-compatibility-notes) để biết cách các người cấp hiện tại đã được di chuyển khi Audits được vận chuyển. -> Endpoint bộ chọn người nhận `GET /alerts/recipients` (liệt kê các email thành viên mà trình chỉnh sửa cảnh báo có thể thông báo) có thể truy cập được bởi một người nắm giữ **bất kỳ** `alerts:read` **hoặc** `alerts:write`, vì vậy các trình chỉnh sửa cảnh báo có thể điền bộ chọn mà không được cấp `users:read`. +> Điểm cuối bộ chọn người nhận `GET /alerts/recipients` (liệt kê email thành viên mà trình chỉnh sửa cảnh báo có thể thông báo) có thể truy cập được bởi người giữ **hoặc** `alerts:read` **hoặc** `alerts:write`, vì vậy các trình chỉnh sửa cảnh báo có thể điền bộ chọn mà không cần được cấp `users:read`. -> Một người xem dashboard cần **cả hai** `dashboards:read` (để tải các chế độ xem đã lưu) và `evaluations:read` (các chỉ số sức khỏe được tính từ dữ liệu đánh giá). Cấp `dashboards:write` để cho phép người dùng tạo hoặc chỉnh sửa dashboard, và `dashboards:delete` để xóa chúng. +> Một người xem bảng điều khiển cần **cả hai** `dashboards:read` (để tải các chế độ xem được lưu) và `evaluations:read` (các chỉ số sức khỏe được tính toán từ dữ liệu đánh giá). Cấp `dashboards:write` để cho phép người dùng tạo hoặc chỉnh sửa bảng điều khiển, và `dashboards:delete` để loại bỏ chúng. -> `/health` và `/auth/*` (yêu cầu OTP, xác minh OTP, kiểm tra phiên, đăng xuất) không được xác thực theo thiết kế; chúng là dòng đăng nhập và liveness probe. `GET /access-granters` yêu cầu một key hợp lệ nhưng không có quyền cụ thể nào, vì vậy bất kỳ người dùng đã đăng nhập nào cũng có thể xem những admin nào để liên hệ về các thay đổi truy cập. +> `/health` và `/auth/*` (yêu cầu OTP, xác minh OTP, kiểm tra phiên, đăng xuất) không được xác thực theo thiết kế; chúng là luồng đăng nhập và điểm dò sống. `GET /access-granters` yêu cầu một khóa hợp lệ nhưng không có quyền hạn cụ thể, vì vậy bất kỳ người dùng đã đăng nhập nào cũng có thể xem những người quản trị viên nào cần liên hệ về các thay đổi truy cập. --- -## Permission Sets +## Bộ quyền hạn -Permission sets cho phép bạn áp dụng một vai trò được đặt tên thay vì chọn tay từng token mỗi lần. Thay vì chọn tá quyền một cách từng cái một cho mỗi người dùng dashboard hoặc API key mới, bạn chọn một tập hợp, và mọi người được gán cho nó mang một cấp phát nhất quán, có thể xem xét. Chỉnh sửa một tập hợp tùy chỉnh tái áp dụng cấp phát mới cho mọi người dùng đã được gán cho nó, vì vậy một thay đổi vai trò là một chỉnh sửa chứ không phải một quét qua mỗi thành viên. +Bộ quyền hạn cho phép bạn áp dụng một vai trò được đặt tên thay vì chọn từng token một cách thủ công mỗi lần. Thay vì chọn một lúc một tá quyền hạn cho mỗi người dùng bảng điều khiển hoặc khóa API mới, bạn chọn một bộ, và mọi người được gán cho nó đều mang một khoản cấp nhất quán, có thể xem xét được. Chỉnh sửa một bộ tùy chỉnh sẽ áp dụng lại khoản cấp mới cho mọi người dùng đã được gán cho nó, vì vậy thay đổi vai trò là một chỉnh sửa chứ không phải một quét qua mỗi thành viên. -Mỗi tổ chức được khởi tạo với ba tập hợp tích hợp: +Mỗi tổ chức được hạt giống với ba bộ được xây dựng sẵn: -| Tập hợp | Quyền | Dành cho | +| Bộ | Quyền hạn | Dự định cho | |---|---|---| | `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Truy cập chỉ xem trên mọi bề mặt hoạt động. | -| `standard` | mọi thứ trong `read-only`, cộng với `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Chỉ đọc cộng với các hành động trên gọi hàng ngày: chạy truy vấn, đánh giá lại phiên, xác nhận incident, và sử dụng trợ lý AI. | -| `admin` | mọi quyền có thể gán | Kiểm soát toàn bộ tổ chức. | +| `standard` | tất cả trong `read-only`, cộng với `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Chỉ đọc cộng với các hành động on-caller hàng ngày: chạy truy vấn, đánh giá lại phiên, xác nhận sự cố và sử dụng trợ lý AI. | +| `admin` | mọi quyền hạn có thể gán | Kiểm soát đầy đủ của tổ chức. | -Ba tập hợp tích hợp là **bất biến**; các tên của chúng luôn có nghĩa giống nhau, vì vậy `read-only`, `standard`, và `admin` an toàn để tham chiếu trong chính sách và onboarding. Một nhà điều hành có thể tạo các **tập hợp tùy chỉnh** bổ sung để mô hình hóa các vai trò cụ thể cho tổ chức của bạn (ví dụ: vai trò "dashboard author" hoặc vai trò "collector-only"). +Ba bộ được xây dựng sẵn là **bất biến**; tên của chúng luôn có cùng một ý nghĩa, vì vậy `read-only`, `standard` và `admin` là an toàn để tham khảo trong chính sách và onboarding. Một nhà điều hành có thể tạo thêm **bộ tùy chỉnh** để mô hình hóa các vai trò cụ thể cho tổ chức của bạn (ví dụ: vai trò "tác giả bảng điều khiển" hoặc vai trò "chỉ bộ sưu tập"). -Các tập hợp được hiển thị trong dashboard và được quản lý trên API tại `GET /permission-sets` (danh sách, gated bởi `users:read`) và `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (tạo, chỉnh sửa, xóa tập hợp tùy chỉnh, gated bởi `settings:write`). Xóa hoặc chỉnh sửa một tập hợp tích hợp bị từ chối. +Bộ được hiển thị trên bảng điều khiển và được quản lý qua API tại `GET /permission-sets` (danh sách, cổng được bởi `users:read`) và `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (tạo, chỉnh sửa, xóa một bộ tùy chỉnh, cổng được bởi `settings:write`). Xóa hoặc chỉnh sửa một bộ được xây dựng sẵn sẽ bị từ chối. -Thành viên tập hợp là những gì hỗ trợ hai tính năng khác: +Tư cách thành viên của bộ là những gì hỗ trợ hai tính năng khác: -- **`DEFAULT_USER_PERMISSIONS`** (cấp được chọn trước khi admin mở **+ new user**) mặc định cho tập hợp `standard`. -- **Flag `--set`** trên `agenteye-orgctl` (quản lý thành viên nhà điều hành) bắt đầu một thành viên từ một tập hợp được đặt tên, mà sau đó bạn tinh chỉnh với `--add` / `--remove`. +- **`DEFAULT_USER_PERMISSIONS`** (khoản cấp được chọn trước khi một quản trị viên mở **+ người dùng mới**) mặc định đến bộ `standard`. +- **Cờ `--set`** trên `agenteye-orgctl` (quản lý thành viên nhà điều hành) bắt đầu một thành viên từ một bộ được đặt tên, mà sau đó bạn sẽ tinh chỉnh với `--add` / `--remove`. -> **Lưu ý:** Khi một tập hợp bao gồm một quyền không thể gán key (ví dụ: một tập hợp tùy chỉnh mang `keys:update`), khởi tạo một key từ tập hợp đó sẽ loại bỏ các token không thể gán; máy chủ sẽ từ chối key khác với HTTP 422. Những người dùng dashboard không phải chịu hạn chế đó. +> **Lưu ý:** Khi một bộ bao gồm một quyền hạn không thể gán khóa (ví dụ: một bộ tùy chỉnh mang `keys:update`), hạt giống một khóa từ bộ đó sẽ loại bỏ các token không thể gán; máy chủ ngoài ra sẽ từ chối khóa với HTTP 422. Người dùng bảng điều khiển không phải tuân theo hạn chế đó. --- -## Bootstrap Admin Key +## Khóa Bootstrap Quản trị viên -Admin key là thông tin xác thực gốc duy nhất cho phép nhà điều hành đưa quyền lên từ không có gì: với nó, bạn có thể tạo ra mỗi key được phạm vi khác, mời những người dùng dashboard đầu tiên, và cấu hình instance trước khi bất kỳ key nào khác tồn tại. Nó là key duy nhất mà bạn không tạo thông qua keys API; nó được cung cấp từ môi trường vì vậy máy chủ có thể đạt được khi khởi động lần đầu. +Khóa quản trị viên là thông tin xác thực gốc duy nhất cho phép một nhà điều hành khởi động quyền truy cập từ không có gì: với nó bạn có thể tạo mỗi khóa có phạm vi khác, mời các người dùng bảng điều khiển đầu tiên, và cấu hình instance trước khi có khóa khác tồn tại. Đó là khóa duy nhất bạn không tạo thông qua các khóa API; nó được cung cấp từ môi trường vì vậy máy chủ có thể truy cập được khi khởi động lần đầu tiên. -Đặt biến môi trường `ADMIN_KEY` trên máy chủ. Khi mỗi lần khởi động, máy chủ upsert giá trị này như một admin key với tất cả quyền. +Đặt biến môi trường `ADMIN_KEY` trên máy chủ. Trên mỗi lần khởi động máy chủ sẽ upsert giá trị này dưới dạng khóa quản trị viên với tất cả quyền hạn. -Để xoay: thay đổi `ADMIN_KEY` thành một secret mới và khởi động lại máy chủ. +Để xoay: thay đổi `ADMIN_KEY` thành một bí mật mới và khởi động lại máy chủ. --- -## Organization scoping +## Phạm vi tổ chức -**Các tổ chức chính nó được tạo và quản lý ngoài hệ thống bởi một nhà điều hành, không thông qua keys API này.** Vòng đời tổ chức và thành viên (tạo / đổi tên / xóa / xóa sạch một tổ chức; thêm / cập nhật / xóa một thành viên) được thực hiện với **CLI `agenteye-orgctl`**; không có HTTP API hoặc nút dashboard cho nó. Những gì *không thay đổi*: **các API key mỗi tổ chức vẫn được tạo trong dashboard (hoặc qua keys API này)** bởi các thành viên tổ chức. +**Các tổ chức tự được tạo và quản lý ngoài dòng bởi một nhà điều hành, không phải thông qua các khóa API này.** Chu kỳ tổ chức và thành viên (tạo / đổi tên / xóa / làm sạch một tổ chức; thêm / cập nhật / loại bỏ một thành viên) được thực hiện với **`agenteye-orgctl`** CLI; không có HTTP API hoặc nút bảng điều khiển cho nó. Những gì *là* không thay đổi: **các khóa API mỗi tổ chức vẫn được tạo trong bảng điều khiển (hoặc qua các khóa API này)** bởi các thành viên tổ chức. -Trong một triển khai đa tổ chức, mỗi key mà một thành viên tổ chức tạo (thông qua keys API này hoặc trang **Keys** của dashboard) thuộc về **một tổ chức** và chỉ có thể đọc hoặc ghi dữ liệu của tổ chức đó; tổ chức được đóng dấu trên key khi tạo và được thực thi khi mỗi yêu cầu. Hai bootstrap key là ngoại lệ duy nhất: key `admin` (khởi tạo từ `ADMIN_KEY`) và key `dashboard-assistant` (khởi tạo từ `AGENT_API_KEY`) là **instance-scoped** (chúng không mang tổ chức). Dashboard xác thực bằng key `admin` để nó có thể ủy đại các yêu cầu mỗi tổ chức thay mặt cho các thành viên đã đăng nhập. Các triển khai single-tenant không cần nghĩ về điều này; tất cả các key thuộc về tổ chức `default` tích hợp. +Trong một triển khai multi-org, mỗi khóa mà một thành viên tổ chức tạo (thông qua các khóa API này hoặc trang **Khóa** của bảng điều khiển) thuộc về **một tổ chức** và chỉ có thể đọc hoặc viết dữ liệu của tổ chức đó; tổ chức được đóng dấu trên khóa khi tạo và được thực thi trên mỗi yêu cầu. Hai khóa bootstrap là ngoại lệ duy nhất: khóa `admin` (được hạt giống từ `ADMIN_KEY`) và khóa `dashboard-assistant` (được hạt giống từ `AGENT_API_KEY`) là **phạm vi instance** (chúng không mang tổ chức). Bảng điều khiển xác thực bằng khóa `admin` vì vậy nó có thể proxy các yêu cầu mỗi tổ chức thay mặt các thành viên đã đăng nhập. Các triển khai đơn thuê không cần phải suy nghĩ về điều này; tất cả các khóa thuộc về tổ chức tích hợp `default`. --- -## Creating Keys +## Tạo khóa -Sử dụng admin key (hoặc bất kỳ key nào có quyền `keys:create`) để tạo các key có phạm vi bổ sung. +Sử dụng khóa quản trị viên (hoặc bất kỳ khóa nào có quyền hạn `keys:create`) để tạo các khóa có phạm vi bổ sung. -### Collector key (ingest only) +### Khóa bộ sưu tập (chỉ nhập) ```bash curl -s -X POST http://your-server/keys \ @@ -180,7 +180,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### Dashboard key (read only) +### Khóa bảng điều khiển (chỉ đọc) ```bash curl -s -X POST http://your-server/keys \ @@ -193,7 +193,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -Khi bạn tạo một key trên HTTP API, bạn cung cấp giá trị `key` của riêng mình; chọn một secret mạnh và lưu trữ nó một cách an toàn. (Dashboard hoạt động theo cách khác: nó tạo ra một secret mạnh cho bạn và hiển thị nó một lần khi tạo; xem [Key Management in the Dashboard](#key-management-in-the-dashboard).) Phản hồi xác nhận key được tạo: +Khi bạn tạo một khóa qua HTTP API, bạn cung cấp giá trị `key` của chính mình; chọn một bí mật mạnh và lưu trữ nó một cách an toàn. (Bảng điều khiển hoạt động theo cách khác: nó tạo một bí mật mạnh cho bạn và hiển thị nó một lần khi tạo; xem [Quản lý khóa trong bảng điều khiển](#key-management-in-the-dashboard).) Phản hồi xác nhận khóa đã được tạo: ```json { @@ -206,20 +206,20 @@ Khi bạn tạo một key trên HTTP API, bạn cung cấp giá trị `key` củ --- -## Listing Keys +## Liệt kê khóa ```bash curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -Các secret key không được trả lại trong các phản hồi danh sách, chỉ ID, tên, và quyền. +Bí mật khóa không được trả lại trong các phản hồi danh sách, chỉ ID, tên và quyền hạn. --- -## Disabling a Key +## Vô hiệu hóa một khóa -Vô hiệu hóa thu hồi quyền truy cập ngay lập tức mà không xóa bản ghi key. +Vô hiệu hóa khóa truy cập ngay lập tức mà không xóa bản ghi khóa. ```bash curl -s -X POST http://your-server/keys//disable \ @@ -228,53 +228,53 @@ curl -s -X POST http://your-server/keys//disable \ --- -## Regenerating a Key +## Tạo lại một khóa -Tạo ra một secret mới cho một key hiện tại. Secret cũ được vô hiệu hóa ngay lập tức. +Tạo một bí mật mới cho một khóa hiện tại. Bí mật cũ bị vô hiệu hóa ngay lập tức. ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -Phản hồi bao gồm secret plaintext mới, **hiển thị chỉ một lần**. +Phản hồi bao gồm bí mật văn bản thông thường mới, **chỉ được hiển thị một lần**. --- -## Key Management in the Dashboard +## Quản lý khóa trong bảng điều khiển -Trang **Keys** trong dashboard cung cấp một UI cho tất cả các hoạt động trên. Bạn cần một key có quyền `keys:read` để xem danh sách, và `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` cho các hành động tạo / chỉnh sửa / vô hiệu hóa / tái tạo tương ứng. Chỉnh sửa quyền của key (`keys:update`) là riêng biệt với việc tạo một cái (`keys:create`), vì vậy bạn có thể cấp cho nhà điều hành khả năng tạo key mà không có khả năng phạm vi lại key hiện tại, hoặc ngược lại. Admin key bao gồm tất cả những cái này. +Trang **Khóa** trong bảng điều khiển cung cấp một UI cho tất cả các hoạt động ở trên. Bạn cần một khóa với quyền hạn `keys:read` để xem danh sách, và `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` cho các hành động tạo / chỉnh sửa / vô hiệu hóa / tạo lại tương ứng. Chỉnh sửa quyền hạn của một khóa (`keys:update`) là riêng biệt với việc tạo một khóa (`keys:create`), vì vậy bạn có thể cấp cho một nhà điều hành khả năng tạo khóa mà không có khả năng xác định lại phạm vi các khóa hiện tại, hoặc ngược lại. Khóa quản trị viên bao gồm tất cả những cái này. -Khi bạn tạo một key từ dashboard, bạn không cung cấp secret; dashboard tạo ra một secret mạnh cho bạn và hiển thị nó **một lần** khi tạo. Sao chép nó ngay lập tức và lưu trữ nó một cách an toàn; nó không bao giờ được hiển thị lại, giống như một lần tái tạo. Bạn vẫn có thể chọn quyền của key một cách trực tiếp, hoặc khởi tạo chúng từ một permission set (xem dưới đây). +Khi bạn tạo một khóa từ bảng điều khiển, bạn không cung cấp bí mật; bảng điều khiển tạo một bí mật mạnh cho bạn và hiển thị nó **một lần** khi tạo. Sao chép nó ngay lập tức và lưu trữ nó một cách an toàn; nó không bao giờ được hiển thị lại, giống như với việc tạo lại. Bạn vẫn có thể chọn quyền hạn của khóa trực tiếp, hoặc hạt giống chúng từ một bộ quyền hạn (xem dưới đây). -![Trang API Keys: một thẻ cho mỗi key hiển thị tên, quyền được cấp, và thời gian tạo, với các hành động tái tạo và vô hiệu hóa; các key được bảo vệ như `admin` được đánh dấu](/agenteye/images/api-keys.png) +![Trang Khóa API: một thẻ cho mỗi khóa hiển thị tên, quyền hạn được cấp và thời gian tạo của nó, với các hành động tạo lại và vô hiệu hóa; các khóa được bảo vệ như `admin` được đánh dấu](/agenteye/images/api-keys.png) --- -## Recommended Key Layout +## Bố cục khóa được đề xuất -| Key | Quyền | Được sử dụng bởi | +| Khóa | Quyền hạn | Được sử dụng bởi | |---|---|---| -| `admin` (bootstrap qua biến env `ADMIN_KEY`) | tất cả | Ops/setup, và dashboard (xác thực bằng `ADMIN_KEY`, ủy đại yêu cầu người dùng với các kiểm tra quyền) | -| Per-host collector key | `events:add` | Collector trên mỗi máy agent | -| `dashboard-assistant` (bootstrap qua biến env `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Trợ lý AI, khởi tạo tự động, **protected**; không thể chỉnh sửa qua API | -| Assistant telemetry key (optional) | `events:add` | AI assistant self-instrumentation, nếu được bật | +| `admin` (bootstrap qua biến env `ADMIN_KEY`) | tất cả | Ops/setup, và bảng điều khiển (xác thực bằng `ADMIN_KEY`, proxy yêu cầu người dùng với kiểm tra quyền hạn) | +| Khóa bộ sưu tập mỗi máy chủ | `events:add` | Bộ sưu tập trên mỗi máy agent | +| `dashboard-assistant` (bootstrap qua biến env `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Trợ lý AI, được hạt giống tự động, **được bảo vệ**; không thể được chỉnh sửa qua API | +| Khóa telemetry trợ lý (tùy chọn) | `events:add` | Tự nhập ráp trợ lý AI, nếu được bật | -> **Lưu ý:** Key của trợ lý **được khởi tạo tự động** bởi máy chủ từ biến env `AGENT_API_KEY` (secret giống nhau mà agent trình bày dưới dạng `AGENTEYE_API_KEY`); không có bước tạo key thủ công và không có admin key liên quan. Các quyền của nó được khắc phục trong source code vì vậy phạm vi không thể được mở rộng bởi cấu hình sai: đọc trên sự kiện / đánh giá / dashboard, cộng với dashboards-write và queries-read / write / run cho dòng tác giả "Ask AI to write a query". Tất cả SQL vẫn đi qua cùng một role chỉ đọc và đường dẫn SQL được bảo vệ như một truy vấn do người dùng viết, vì vậy điều này mở rộng *bề mặt tác giả*, không phải bề mặt dữ liệu; các hoạt động phá hủy (`queries:delete`, `dashboards:delete`) cố ý ở ngoài assistant key. Giống như key `admin`, nó **được bảo vệ**: nó không thể bị vô hiệu hóa hoặc tái tạo thông qua keys API, chỉ xoay bằng cách thay đổi `AGENT_API_KEY` và khởi động lại. Người dùng *dashboard* cần quyền `agent:use` để xem và sử dụng trợ lý. Nếu bạn bật self-instrumentation, hãy cung cấp cho trợ lý một key riêng chỉ `events:add`. +> **Lưu ý:** Khóa của trợ lý được **hạt giống tự động** bởi máy chủ từ biến env `AGENT_API_KEY` (cùng bí mật mà agent hiện như `AGENTEYE_API_KEY`); không có bước tạo khóa thủ công và không có khóa quản trị viên liên quan. Quyền hạn của nó được sửa trong mã nguồn vì vậy phạm vi không thể được mở rộng bằng sai cấu hình: đọc trên các sự kiện / đánh giá / bảng điều khiển, cộng với dashboards-write và queries-read / write / run cho luồng soạn thảo "Yêu cầu AI viết một truy vấn". Tất cả SQL vẫn đi qua cùng một vai trò chỉ đọc và đường dẫn SQL được bảo vệ như một truy vấn được viết bởi người dùng, vì vậy điều này mở rộng bề mặt *soạn thảo*, không phải bề mặt dữ liệu; các hoạt động tàn phá (`queries:delete`, `dashboards:delete`) có ý định ở ngoài khóa trợ lý. Giống như khóa `admin`, nó là **được bảo vệ**: nó không thể bị vô hiệu hóa hoặc tạo lại thông qua các khóa API, chỉ được xoay bằng cách thay đổi `AGENT_API_KEY` và khởi động lại. Người dùng bảng điều khiển *bổ sung* cần quyền hạn `agent:use` để xem và sử dụng trợ lý. Nếu bạn bật tự nhập ráp, hãy cung cấp cho trợ lý một khóa riêng biệt chỉ `events:add`. --- -## Upgrade and backward-compatibility notes +## Ghi chú nâng cấp và tương thích ngược Bạn chỉ cần những cái này nếu bạn đang nâng cấp một instance hiện tại; các triển khai mới có thể bỏ qua chúng. -> Khi Audits được vận hành, các grantee hiện tại được mở rộng cùng các hình dạng vai trò với alert: mỗi người dùng và permission set nắm giữ `alerts:read` đã đạt được `audits:read`, và mỗi người nắm giữ `alerts:write` đã đạt được `audits:write`. Các API key hiện tại **không** được mở rộng. Cấp `audits:*` cho một key một cách rõ ràng nếu nó cần bề mặt audit. +> Khi Audits được vận chuyển, các người cấp hiện tại đã được mở rộng dọc theo các hình dạng vai trò giống như cảnh báo: mỗi người dùng và bộ quyền hạn giữ `alerts:read` đã lợi `audits:read`, và mỗi người giữ `alerts:write` đã lợi `audits:write`. Các khóa API hiện tại **không** bị mở rộng. Cấp `audits:*` cho một khóa một cách rõ ràng nếu nó cần bề mặt kiểm toán. -> Cấp của legacy token `alerts:ack` được lưu trữ được phân tích cú pháp thành `incidents:ack` vì vậy on-caller vẫn giữ quyền truy cập mà không cần đổi key. Token không còn có thể gán từ trình chỉnh sửa người dùng của dashboard; ma trận cung cấp `incidents:ack` thay thế. +> Cấp được lưu trữ của mã thông báo `alerts:ack` kế thừa được phân tích cú pháp thành `incidents:ack` vì vậy on-callers giữ lại quyền truy cập mà không cần rekeying. Mã thông báo không còn có thể gán từ trình chỉnh sửa người dùng của bảng điều khiển; ma trận đề xuất `incidents:ack` thay thế. --- -## Các bước tiếp theo +## Bước tiếp theo - [Python SDK](/vi/agenteye/python-sdk): cách mã agent của bạn xác thực khi gửi sự kiện. -- [Security](/vi/agenteye/security): cách đăng nhập, kiểm soát truy cập, và cách cô lập dữ liệu mỗi tổ chức hoạt động. \ No newline at end of file +- [Bảo mật](/vi/agenteye/security): cách đăng nhập, kiểm soát truy cập và cách hoạt động cách ly dữ liệu mỗi tổ chức. \ No newline at end of file diff --git a/docs/vi/agenteye/assistant.mdx b/docs/vi/agenteye/assistant.mdx index 512891de..cf69887f 100644 --- a/docs/vi/agenteye/assistant.mdx +++ b/docs/vi/agenteye/assistant.mdx @@ -1,15 +1,16 @@ --- +--- title: "Trợ lý AI" -description: "Đặt câu hỏi cho dữ liệu agent của bạn bằng tiếng Anh thuần túy và nhận được câu trả lời có liên kết trực tiếp đến bằng chứng." +description: "Đặt câu hỏi về dữ liệu agent của bạn bằng tiếng Anh thông thường và nhận được câu trả lời có liên kết trực tiếp đến bằng chứng." --- -Đặt câu hỏi cho dữ liệu agent của bạn bằng tiếng Anh thuần túy và nhận được câu trả lời có liên kết trực tiếp đến bằng chứng. Không cần viết SQL, không cần tìm kiếm trong các bảng điều khiển — trợ lý **Failproof AI Observability** là cách nhanh nhất để bất kỳ ai trong nhóm của bạn có thể nhận được câu trả lời về các agent của bạn. +Đặt câu hỏi về dữ liệu agent của bạn bằng tiếng Anh thông thường và nhận được câu trả lời có liên kết trực tiếp đến bằng chứng. Không cần viết SQL, không cần xem qua các bảng điều khiển — trợ lý **Failproof AI Observability** là cách nhanh nhất để bất kỳ ai trong đội của bạn có thể tìm được câu trả lời về các agent của bạn. -![Trợ lý Failproof AI Observability trả lời một câu hỏi bằng tiếng Anh thuần túy bên trong bảng điều khiển, hiển thị bảng Hoạt động Agent trực tiếp, phân tích sử dụng mô hình theo từng agent và các điểm chính, cùng với các truy vấn mà nó chạy được hiển thị inline](/agenteye/images/assistant.png) -*Đặt câu hỏi bằng tiếng Anh thuần túy và nhận được câu trả lời được xây dựng từ dữ liệu của riêng bạn. Ở đây nó phân tích những agent nào bận rộn nhất và những mô hình nào họ sử dụng, đồng thời hiển thị các truy vấn mà nó chạy để bạn có thể xác minh từng con số.* +![Trợ lý Failproof AI Observability trả lời câu hỏi bằng tiếng Anh thông thường bên trong bảng điều khiển, hiển thị bảng Agent Activity trực tiếp, phân tích mức độ sử dụng mô hình theo từng agent, và các nhận xét đã viết, với các truy vấn nó đã chạy được hiển thị nội tuyến](/agenteye/images/assistant.png) +*Hỏi bằng tiếng Anh thông thường và nhận được câu trả lời được xây dựng từ dữ liệu của riêng bạn. Ở đây nó phân tích những agent nào bận rộn nhất và những mô hình nào chúng sử dụng, đồng thời hiển thị các truy vấn nó đã chạy để bạn có thể xác minh từng con số.* -Không có gì phải học. Mở cuộc trò chuyện, gõ những gì bạn muốn biết, và theo dõi các liên kết mà nó cung cấp: +Không có gì phải học. Mở cuộc trò chuyện, nhập những gì bạn muốn biết, và theo dõi các liên kết nó cung cấp: ``` You: which sessions errored today? @@ -24,40 +25,40 @@ AI: This run took 12 steps across 3 tools and failed near the end when a Links: the session, the failing event, and that evaluation. ``` -## Chỉ cần hỏi và nhảy thẳng đến bằng chứng +## Chỉ cần hỏi, và nhảy thẳng đến bằng chứng -Bạn không còn phải đoán và không cần phải viết truy vấn. Hỏi "chất lượng đang xu hướng như thế nào trong prod tuần này?", "phiên nào bị lỗi hôm nay?", hoặc "tóm tắt phiên này", và bạn sẽ nhận được câu trả lời rõ ràng trong vài giây thay vì phải xây dựng truy vấn và tự đọc kết quả. +Bạn không còn phải đoán và không còn phải viết các truy vấn. Hỏi "chất lượng đang xu hướng như thế nào trong prod tuần này?", "những phiên nào gặp lỗi hôm nay?" hay "tóm tắt phiên này," và bạn sẽ nhận được câu trả lời rõ ràng trong vòng vài giây thay vì xây dựng truy vấn và tự đọc nó. -Mọi câu trả lời đều kèm theo bằng chứng của nó. Trợ lý liên kết đến các phiên chính xác, các truy vấn đã lưu và bảng điều khiển mà nó sử dụng để đưa ra câu trả lời, vì vậy bạn có thể nhấp để xác nhận thay vì chỉ tin tưởng theo lời nó. Nó cũng **nhận biết trang**: hỏi về "phiên này" khi bạn đang xem một phiên và nó đã biết bạn muốn nói về phiên chạy nào. Mở lại bất kỳ cuộc trò chuyện trước đó nào từ công tắc lịch sử và tiếp tục từ nơi bạn để dở. +Mỗi câu trả lời đều kèm theo biên lai của nó. Trợ lý liên kết các phiên chính xác, truy vấn đã lưu, và các bảng điều khiển mà nó sử dụng để đạt được câu trả lời, vì vậy bạn có thể nhấp vào và xác nhận thay vì tin lời của nó. Nó cũng **nhận biết trang**: hỏi về "phiên này" khi bạn đang xem một phiên và nó đã biết bạn đang nói đến phiên chạy nào. Mở lại bất kỳ cuộc trò chuyện trước đó từ bộ chuyển đổi lịch sử và tiếp tục từ nơi bạn dừng. ## Biến một câu trả lời tốt thành truy vấn đã lưu hoặc bảng điều khiển -Khi một câu trả lời xứng đáng được giữ, yêu cầu trợ lý lưu nó. Nó soạn SQL cho một truy vấn đã lưu hoặc lắp ráp một bảng điều khiển từ các truy vấn đó, sau đó hiển thị cho bạn thẻ **Phê duyệt / Từ chối**. Không gì được ghi lại cho đến khi bạn nhấp Phê duyệt, vì vậy bạn có thể trải nghiệm tốc độ của "chỉ cần hỏi" với quyền quyết định cuối cùng luôn thuộc về bạn. +Khi một câu trả lời đáng giá để giữ, yêu cầu trợ lý lưu nó. Nó soạn thảo SQL cho truy vấn đã lưu, hoặc tập hợp bảng điều khiển từ những truy vấn đó, sau đó hiển thị cho bạn một thẻ **Phê duyệt / Từ chối**. Không có gì được ghi lại cho đến khi bạn nhấp vào Phê duyệt, vì vậy bạn có được tốc độ của "chỉ cần hỏi" với quyền quyết định cuối cùng luôn ở với bạn. -Trên trang **Truy vấn** nó đi xa hơn một bước và trở thành tác giả SQL: mô tả truy vấn bạn muốn ("hiển thị tỷ lệ lỗi theo agent cho 7 ngày qua") và nó sẽ phát trực tiếp SQL vào trình chỉnh sửa, mở chế độ diff để bạn có thể **Chấp nhận** hoặc **Từ chối** thay đổi trước khi nó được áp dụng. +Trên trang **Truy vấn**, nó đi xa hơn một bước và trở thành tác giả SQL: mô tả truy vấn bạn muốn ("hiển thị tỷ lệ lỗi theo agent trong 7 ngày qua") và nó truyền SQL trực tiếp vào trình chỉnh sửa, mở chế độ xem khác biệt để bạn có thể **Chấp nhận** hoặc **Từ chối** thay đổi trước khi nó được thực hiện. ![Trang Truy vấn Observability và trình chỉnh sửa SQL của nó](/agenteye/images/query-lab.png) -*Trang Truy vấn: trình chỉnh sửa này là nơi trợ lý phát một bản nháp truy vấn chỉ đọc cho bạn chấp nhận hoặc từ chối.* +*Trang Truy vấn: trình chỉnh sửa này là nơi trợ lý truyền một truy vấn nháp chỉ đọc để bạn chấp nhận hoặc từ chối.* -Soạn SQL bằng cách hỏi ở đây sử dụng quyền `queries:run`, quyền giống như quyền đằng sau nút **Chạy** của trình chỉnh sửa. Chat ở mọi nơi khác cần `agent:use`. +Tác giả SQL bằng cách hỏi ở đây sử dụng quyền `queries:run`, cùng quyền đằng sau nút **Chạy** của trình chỉnh sửa. Trò chuyện ở những nơi khác cần `agent:use`. -## An toàn để giao cho toàn bộ nhóm +## An toàn để giao cho toàn bộ đội -Bạn có thể mở trợ lý cho tất cả mọi người mà không lo lắng về những gì nó có thể chạm vào: +Bạn có thể mở trợ lý cho mọi người mà không cần lo lắng về những gì nó có thể chạm vào: -- **Nó chỉ đọc những gì bạn đã có thể thấy.** Câu trả lời được giới hạn trong quyền đọc của riêng bạn, vì vậy nó không bao giờ mở rộng diện tích dữ liệu của bạn. -- **Mọi lần ghi đều chờ bạn.** Các truy vấn và bảng điều khiển đã lưu chỉ được tạo sau khi bạn nhấp Phê duyệt một cách rõ ràng, và không có cài đặt nào tắt cổng này. -- **Nó không bao giờ có thể xóa bất cứ điều gì.** Không có công cụ xóa nào được hiển thị và trợ lý không có quyền xóa. Các lần xóa vẫn nằm trong tay bạn, trên bảng điều khiển. -- **Nó ở bên trong tổ chức của bạn.** Trợ lý chỉ khi nào cũng chỉ nhìn thấy tổ chức bạn đang xem hiện tại. -- **Các câu hỏi của bạn vẫn là của bạn.** Lời nhắc và câu trả lời sống trong cơ sở dữ liệu Observability riêng của bạn; phân tích sản phẩm chỉ ghi lại siêu dữ liệu sử dụng, không bao giờ văn bản lời nhắc của bạn. +- **Nó chỉ đọc những gì bạn đã có thể nhìn thấy.** Các câu trả lời được phạm vi giới hạn theo quyền đọc của riêng bạn, vì vậy nó không bao giờ mở rộng bề mặt dữ liệu của bạn. +- **Mỗi lần ghi đều chờ bạn.** Truy vấn đã lưu và bảng điều khiển được tạo chỉ sau khi nhấp Phê duyệt rõ ràng của bạn, và không có cài đặt nào tắt cổng đó. +- **Nó không bao giờ có thể xóa bất cứ điều gì.** Không có công cụ xóa nào được phơi bày và trợ lý không có quyền xóa. Các lần xóa vẫn nằm trong tay bạn, trong bảng điều khiển. +- **Nó ở trong tổ chức của bạn.** Trợ lý chỉ bao giờ nhìn thấy tổ chức bạn đang xem hiện tại. +- **Các câu hỏi của bạn vẫn là của bạn.** Lời nhắc và câu trả lời sống trong cơ sở dữ liệu Observability của riêng bạn; phân tích sản phẩm chỉ ghi lại siêu dữ liệu sử dụng, không bao giờ văn bản lời nhắc của bạn. ## Nơi tìm nó -Trợ lý nằm dọc theo cạnh bên phải của mọi trang dưới tổ chức của bạn (`//...`). Nhấp vào ray hoặc nhấn `⌘J` / `Ctrl+J` để mở rộng nó thành bảng trò chuyện đầy đủ, và kéo cạnh của nó để thay đổi kích thước; chiều rộng của bạn được lưu nhớ qua các lần tải lại. Bạn cần quyền **`agent:use`** để sử dụng nó, nếu không ray sẽ bị làm mờ. Nếu nó chưa được bật cho triển khai của bạn (nó cần kết nối LLM), bạn sẽ thấy ray bị làm mờ thay vì trò chuyện hoạt động. +Trợ lý đi kèm theo cạnh phải của mỗi trang dưới tổ chức của bạn (`//...`). Nhấp vào thanh, hoặc nhấn `⌘J` / `Ctrl+J`, để mở rộng nó thành bảng trò chuyện đầy đủ, và kéo cạnh của nó để thay đổi kích thước; chiều rộng của bạn được ghi nhớ khi tải lại. Bạn cần quyền **`agent:use`** để sử dụng nó, nếu không thanh sẽ bị xám đi. Nếu nó chưa được bật cho triển khai của bạn (nó cần kết nối LLM), bạn sẽ thấy một thanh muted thay cho trò chuyện đang hoạt động. ## Liên quan -- [CLI and agents](/vi/agenteye/cli-and-agents) -- [Queries](/vi/agenteye/queries) -- [Dashboards](/vi/agenteye/dashboards) -- [Evaluation suite](/vi/agenteye/evaluation-suite) \ No newline at end of file +- [CLI và agents](/vi/agenteye/cli-and-agents) +- [Truy vấn](/vi/agenteye/queries) +- [Bảng điều khiển](/vi/agenteye/dashboards) +- [Bộ đánh giá](/vi/agenteye/evaluation-suite) \ No newline at end of file diff --git a/docs/vi/agenteye/audits.mdx b/docs/vi/agenteye/audits.mdx index 2c6e9e1f..beed12ed 100644 --- a/docs/vi/agenteye/audits.mdx +++ b/docs/vi/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- title: "Audits: trợ lý phân tích độ tin cậy tự động của bạn" -description: "Failproof AI Observability tìm kiếm các lỗi mà bạn chưa bao giờ viết quy tắc cho chúng và cung cấp cho bạn danh sách việc cần làm được xếp hạng, có bằng chứng chính xác về những gì cần sửa." +description: "Failproof AI Observability tìm kiếm các lỗi mà bạn chưa bao giờ viết quy tắc cho và cung cấp cho bạn một danh sách việc cần làm được xếp hạng, có bằng chứng để bạn biết chính xác phải sửa gì." --- -Failproof AI Observability tìm kiếm các lỗi mà bạn chưa bao giờ viết quy tắc cho chúng và cung cấp cho bạn danh sách việc cần làm được xếp hạng, có bằng chứng chính xác về những gì cần sửa. Nó giống như có một nhà phân tích duyệt qua nhật ký của bạn mỗi tối, rồi để lại danh sách ngắn gọn trên bàn của bạn vào sáng hôm sau. +Failproof AI Observability tìm kiếm các lỗi mà bạn chưa bao giờ viết quy tắc cho và cung cấp cho bạn một danh sách việc cần làm được xếp hạng, có bằng chứng để bạn biết chính xác phải sửa gì. Nó giống như việc có một nhà phân tích duyệt qua các nhật ký của bạn mỗi đêm, rồi để lại danh sách ngắn trên bàn của bạn vào sáng hôm sau.
-*Một bài tour hai phút: từ một lần chạy theo lịch đến một bản sửa mà bạn có thể thực hiện.* +*Một chuyến tham quan hai phút: từ một lần chạy theo lịch trình đến một bản sửa mà bạn có thể thực hiện.* -![Trang Audits: các công việc định kỳ quét các phiên của bạn tìm kiếm các mẫu lỗi, mỗi công việc có lịch trình và độ nhạy cảm](/agenteye/images/audits.png) -*Mỗi audit là một công việc định kỳ khai thác các phiên của bạn và viết các khuyến nghị được xếp hạng, có bằng chứng.* +![Trang Audits: các công việc định kỳ quét các phiên của bạn để tìm kiếm mẫu lỗi, mỗi công việc có một lịch trình và độ nhạy cảm](/agenteye/images/audits.png) +*Mỗi audit là một công việc định kỳ khai thác các phiên của bạn và đưa ra các khuyến nghị được xếp hạng và có bằng chứng.* -## Ngừng đoán xem cần sửa gì tiếp theo +## Dừng đoán mò những gì cần sửa tiếp theo -Cảnh báo bắt các vấn đề mà bạn đã biết cần theo dõi. Audits bắt những vấn đề bạn không biết. Theo lịch trình bạn đặt, một audit đọc qua tất cả các phiên của agent bạn và tìm kiếm các mẫu đáng được sửa, do đó bạn dành thời gian thực hiện các phát hiện thay vì cuộn qua nhật ký hy vọng tự mình phát hiện chúng. +Các cảnh báo bắt các vấn đề bạn đã biết cần theo dõi. Audits bắt những cái bạn không biết. Theo lịch trình bạn đặt, một audit sẽ đọc qua tất cả các phiên agent của bạn và tìm kiếm các mẫu đáng để sửa, vì vậy bạn dành thời gian để hành động dựa trên kết quả thay vì cuộn qua nhật ký hy vọng tự mình phát hiện chúng. -Một lần chạy duy nhất nhắm vào các chế độ lỗi thực sự phá vỡ các agent trong production: +Một lần chạy duy nhất sẽ hướng tới các chế độ lỗi thực tế làm hỏng các agent trong môi trường sản xuất: - **Cụm lỗi**: cùng một lỗi lặp lại dưới một nguyên nhân gốc chung. -- **D漂drift so với đường cơ sở**: hành vi âm thầm trôi ra khỏi một cửa sổ đã biết là tốt. -- **Lỗi mục tiêu trong bản ghi**: các lần chạy về mặt kỹ thuật đã hoàn thành nhưng không bao giờ thực hiện công việc. -- **Sử dụng công cụ sai**: công cụ sai, đối số xấu, hoặc các vòng lặp tiêu burn các lệnh gọi. -- **Tối ưu hóa chất lượng và chi phí**: nơi bạn chi trả quá mức cho đầu ra mà bạn có thể nhận được rẻ hơn. -- **Khoảng trống phạm vi**: hành vi mà không có eval hoặc cảnh báo nào đang theo dõi. +- **Độ trôi so với đường cơ sở**: hành vi im lặng trượt khỏi một cửa sổ đã biết tốt. +- **Lỗi mục tiêu trong bảng điểm**: các lần chạy kỹ thuật đã hoàn thành nhưng không bao giờ hoàn thành công việc. +- **Sử dụng công cụ sai**: công cụ sai, đối số xấu hoặc các vòng lặp đốt các lệnh gọi. +- **Sự cân bằng giữa chất lượng và chi phí**: nơi bạn đang trả quá nhiều tiền cho đầu ra mà bạn có thể nhận được rẻ hơn. +- **Khoảng trống phạm vi**: hành vi mà không có eval hay cảnh báo nào đang theo dõi. -Bạn quyết định nó tìm kiếm bao nhiêu với một cài đặt **sensitivity** (thấp, trung bình hoặc cao), vì vậy một agent staging ồn ào và một agent production bị khóa chặt có thể được điều chỉnh riêng để có được tín hiệu bạn muốn. +Bạn quyết định mức độ tìm kiếm của nó bằng một cài đặt **độ nhạy cảm** duy nhất (thấp, trung bình hoặc cao), vì vậy một agent staging ồn ào và một agent sản xuất khóa chặt có thể được điều chỉnh cho từng tín hiệu mà bạn muốn. ## Mỗi khuyến nghị đều có bằng chứng -Bạn không bao giờ phải tin một phát hiện không cần kiểm chứng. Mỗi khuyến nghị trích dẫn các phiên chính xác mà nó đến từ đó và SQL đã làm nổi bật nó, vì vậy bạn có thể mở bằng chứng và xác nhận vấn đề chỉ trong một cú nhấp chuột thay vì reverse-engineering một yêu cầu. +Bạn không bao giờ phải chấp nhận một kết quả dựa trên lòng tin. Mỗi khuyến nghị trích dẫn các phiên chính xác mà nó đến từ đó và SQL đã hiển thị nó, vì vậy bạn có thể mở bằng chứng và xác nhận vấn đề trong một cú nhấp chuột thay vì đảo ngược kỹ thuật một yêu cầu. -Khi một phát hiện là về thông tin đăng nhập bị rò rỉ, nó đi thêm một bước nữa và liên kết các sự kiện riêng lẻ mà nó đã khớp. Nhấp vào một sự kiện và bạn sẽ đến đúng thời điểm đó trong phiên, đã được chọn — không phải đầu của một bản ghi dài để cuộn qua. Liên kết đặt tên cho sự kiện; nó không bao giờ sao chép bí mật được phát hiện vào phát hiện, vì vậy đọc một phát hiện không phải là nơi thứ hai thông tin đăng nhập của bạn được viết ra. Nếu một sự kiện không còn ở đó vì phiên đã vượt quá cửa sổ lưu giữ của bạn, trang sẽ nói rõ điều đó thay vì để bạn tự hỏi liệu bạn đã nhấp vào sai thứ gì. +Khi một kết quả liên quan đến thông tin xác thực bị rò rỉ, nó tiến thêm một bước và liên kết các sự kiện riêng lẻ mà nó khớp. Nhấp vào một sự kiện và bạn sẽ hạ cánh vào thời điểm chính xác trong phiên, đã được chọn — không phải đầu một bảng điểm dài để cuộn qua. Liên kết đặt tên sự kiện; nó không bao giờ sao chép bí mật được phát hiện vào kết quả, vì vậy đọc một kết quả không phải là nơi thứ hai bí mật của bạn được viết xuống. Nếu một sự kiện không còn ở đó vì phiên đã vượt quá cửa sổ lưu giữ của bạn, trang nói rõ ràng như vậy thay vì để bạn tự hỏi liệu bạn có nhấp vào điều gì đó sai hay không. -Đó cũng là thứ giữ cho các audit trung thực. Máy chủ kiểm tra rằng mỗi phiên được trích dẫn thực sự tồn tại và **loại bỏ bất kỳ khuyến nghị nào có bằng chứng không chứng thực được**, vì vậy audit điều tra nhưng không bao giờ phát minh ra. Những gì được đưa lên danh sách của bạn là có thật, có thể tái tạo được, và được xếp hạng theo mức độ quan trọng của nó, với những chiến thắng lớn nhất ở phía trên. +Đó cũng là những gì giữ cho các audit trung thực. Máy chủ kiểm tra rằng mỗi phiên được trích dẫn thực sự tồn tại và **loại bỏ bất kỳ khuyến nghị nào có bằng chứng không đạt**, vì vậy audit điều tra nhưng không bao giờ bịa đặt. Những gì được đưa vào danh sách của bạn là thực tế, có thể tái tạo được và được xếp hạng theo mức độ quan trọng của nó, với những chiến thắng lớn nhất ở trên cùng. -## Chuyển một bản sửa thành một biện pháp bảo vệ +## Biến một bản sửa thành một guardrail -Sửa một vấn đề chỉ là nửa chiến thắng. Nửa kia là đảm bảo nó không thể âm thầm quay trở lại. Mỗi phát hiện mang theo **một phím tắt một cú nhấp chuột nháp một cảnh báo tái diễn**, được điền trước một trích kích hoạt hợp lý mà bạn có thể điều chỉnh. Đóng phát hiện, vũ trang cảnh báo, và lần tiếp theo mẫu đó xuất hiện bạn sẽ được trang thái thay vì tái khám phá nó trong một audit tương lai. +Sửa một vấn đề chỉ là nửa chiến thắng. Nửa còn lại là đảm bảo nó không thể im lặng quay lại. Mỗi kết quả đều có **một phím tắt nhấp chuột tạo cảnh báo tái phát**, được điền trước với trình kích hoạt bắt đầu hợp lý mà bạn có thể điều chỉnh. Đóng kết quả, kích hoạt cảnh báo và lần tiếp theo khi mẫu đó xuất hiện lại, bạn sẽ nhận được trang thông báo thay vì phát hiện lại nó trong một audit trong tương lai. -## Tìm nó ở đâu +## Nơi tìm nó -Audits nằm trong bảng điều khiển tại **`//audits`** (thanh bên đến *analyze* đến *audits*). Xem các lần chạy và phát hiện cần **`audits:read`**; tạo, chỉnh sửa và phân loại các audit cần **`audits:write`**. Đặt phạm vi và tần suất của một audit, rồi nhấp **Run now** bất cứ khi nào bạn muốn kết quả ngay lập tức thay vì chờ lần chạy theo lịch tiếp theo. +Audits nằm trên bảng điều khiển tại **`//audits`** (thanh bên thành *analyze* thành *audits*). Xem các lần chạy và kết quả cần **`audits:read`**; tạo, chỉnh sửa và phân loại các audit cần **`audits:write`**. Đặt phạm vi và tần suất của một audit, sau đó nhấn **Run now** bất cứ khi nào bạn muốn kết quả ngay lập tức thay vì chờ đợi lần chạy theo lịch trình tiếp theo. ## Liên quan -- [Alerts](/vi/agenteye/alerts): nhận thông báo thời điểm ngưỡng bạn đã biết được vượt qua. -- [Evaluations](/vi/agenteye/evaluations): đánh điểm mỗi lần chạy để các hồi quy chất lượng tự nổi bật. -- [Error tracking](/vi/agenteye/error-tracking): nhóm và theo dõi các lỗi mà agent của bạn ném ra. -- [Incidents](/vi/agenteye/incidents): theo dõi một vấn đề mà audit phát hiện cho đến khi sửa nó. \ No newline at end of file +- [Alerts](/vi/agenteye/alerts): nhận thông báo vào thời điểm một ngưỡng mà bạn đã biết được vượt qua. +- [Evaluations](/vi/agenteye/evaluations): đánh điểm mỗi lần chạy để các thoái hóa chất lượng tự xuất hiện. +- [Error tracking](/vi/agenteye/error-tracking): nhóm và theo dõi các lỗi mà agent của bạn ném. +- [Incidents](/vi/agenteye/incidents): theo dõi một vấn đề mà một audit phát hiện cho đến khi sửa chữa. \ No newline at end of file diff --git a/docs/vi/agenteye/cli-and-agents.mdx b/docs/vi/agenteye/cli-and-agents.mdx index c53e5ea6..a6c6a4b8 100644 --- a/docs/vi/agenteye/cli-and-agents.mdx +++ b/docs/vi/agenteye/cli-and-agents.mdx @@ -4,7 +4,7 @@ description: "Toàn bộ triển khai Failproof AI Observability của bạn, ch --- -Toàn bộ triển khai Failproof AI Observability của bạn, chỉ cách một lệnh. Kiểm tra production, tạo khóa API, hoặc xác nhận sự cố mà không cần rời khỏi terminal, sau đó đưa bất kỳ lệnh nào vào CI, hoặc để một coding agent thực hiện cho bạn bằng ngôn ngữ tự nhiên. +Toàn bộ triển khai Failproof AI Observability của bạn, chỉ cách một lệnh. Kiểm tra production, tạo API key, hoặc xác nhận một sự cố mà không cần rời khỏi terminal của bạn, sau đó viết script bất kỳ điều gì vào CI, hoặc để một coding agent thực hiện nó cho bạn bằng tiếng Anh thường. ```bash pipx install agenteye @@ -12,18 +12,18 @@ agenteye login --email you@example.com # a 6-digit code lands in your inbox agenteye --json sessions --since 24h # every agent run from the last day, newest first ``` -*CLI `agenteye` giao tiếp với dashboard của bạn. Đây là một công cụ khác biệt với collector, công cụ này gửi sự kiện đến máy chủ.* +*CLI `agenteye` kết nối với dashboard của bạn. Nó là một công cụ khác biệt so với collector, nơi gửi các sự kiện đến máy chủ.* ## Toàn bộ triển khai của bạn, chỉ cách một lệnh -Dừng việc chuyển tab để trả lời một câu hỏi nhanh. CLI `agenteye` đọc dữ liệu của bạn và quản trị tổ chức của bạn từ một tệp nhị phân duy nhất, vì vậy một kiểm tra mà trước đây có nghĩa là nhấp vào dashboard trở thành một dòng mà bạn có thể chạy lại, tạo bí danh hoặc dán vào runbook. Bạn có bốn giao diện: +Dừng việc chuyển đổi giữa các tab để trả lời một câu hỏi nhanh. CLI `agenteye` đọc dữ liệu của bạn và quản lý tổ chức của bạn từ một tệp nhị phân duy nhất, vì vậy một kiểm tra trước đây có nghĩa là nhấp qua dashboard giờ đây chỉ là một dòng mà bạn có thể chạy lại, tạo bí danh hoặc dán vào runbook. Bạn có bốn giao diện: - **Đọc dữ liệu của bạn:** `sessions`, `events`, `evals`, và `errors`, được lọc theo thời gian, agent và môi trường. - **Quản lý tổ chức của bạn:** `keys`, `users`, `settings`, `alerts`, và `incidents`. -- **Chạy phân tích:** SQL được lưu cùng với trình chạy `query` ad-hoc trên dữ liệu sự kiện của bạn. -- **Hỏi trợ lý:** `agent ask` tiếp cận cùng một nhà phân tích chỉ đọc mà bạn trò chuyện với trong dashboard. +- **Chạy phân tích:** SQL đã lưu cộng với runner `query` ad-hoc trên dữ liệu sự kiện của bạn. +- **Hỏi trợ lý:** `agent ask` kết nối với nhà phân tích chỉ đọc tương tự như bạn trò chuyện với trong dashboard. -Cài đặt một lần bằng `pipx`, đăng nhập bằng mã 6 chữ số được gửi qua email, và bạn đã sẵn sàng. Phiên kéo dài khoảng một ngày; chạy lại `agenteye login` khi nó hết hạn. Dùng nó để kiểm tra production, cấp phát khóa, hoặc phân loại sự cố kích hoạt, tất cả mà không cần mở trình duyệt: +Cài đặt nó một lần bằng `pipx`, đăng nhập bằng mã 6 chữ số được gửi qua email, và bạn đã sẵn sàng. Phiên kéo dài khoảng một ngày; chạy lại `agenteye login` khi hết hạn. Sử dụng nó để kiểm tra production nhanh chóng, cấp phát key, hoặc phân loại một sự cố kích hoạt, tất cả mà không cần mở trình duyệt: ```bash agenteye errors --since 24h --aggregate # what is breaking, grouped by error type @@ -31,25 +31,25 @@ agenteye incidents list --state firing # what is on fire right now agenteye keys create ci --add events:add # a key that can only push events, secret shown once ``` -Một thói quen cần biết: các tùy chọn toàn cục như `--json` đi trước lệnh. `agenteye --json sessions` là đúng; `agenteye sessions --json` là sai. +Một thói quen cần biết: các tùy chọn toàn cầu như `--json` đặt trước lệnh. `agenteye --json sessions` là đúng; `agenteye sessions --json` là sai. -## Viết script nó, tích hợp vào CI +## Viết script nó, kết nối nó vào CI -Mọi lệnh đều nhận `--json`, và điều đó thay đổi mọi thứ. JSON sạch đi đến stdout trong khi trạng thái và cảnh báo của con người đi đến stderr, vì vậy việc capture `--json` đi thẳng vào `jq` mà không có dòng lạc để xóa. Đó là những gì làm cho CLI tốt như nhau cho bạn khi nhắc lệnh và cho một coding agent phân tích đầu ra: +Mọi lệnh đều nhận `--json`, và điều đó thay đổi mọi thứ. JSON sạch sẽ đi ra stdout trong khi trạng thái con người và cảnh báo đi đến stderr, vì vậy một bộ đệm `--json` kết nối trực tiếp vào `jq` mà không có dòng lạc nào để loại bỏ. Đó là điều làm cho CLI tốt như nhau cho bạn ở dấu nhắc lệnh và cho một coding agent phân tích đầu ra: ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -Nó được xây dựng để chạy không được giám sát. Các lời nhắc xác nhận tự động bỏ qua khi không có terminal được đính kèm, vì vậy không có gì bị treo trong đường ống, và mọi lệnh đều trả về mã thoát có ý nghĩa: `0` thành công, `4` chưa đăng nhập, `5` thiếu quyền (thông báo đặt tên nó, ví dụ `alerts:write`), `3` dashboard không thể tiếp cận. Một script có thể phân nhánh trên `4` để xác thực lại hoặc `5` để cho bạn biết chính xác những gì để yêu cầu admin, thay vì thất bại mù quáng. +Nó được xây dựng để chạy không được giám sát. Các lời nhắc xác nhận tự động bỏ qua khi không có terminal được kết nối, vì vậy không có gì bị treo trong một pipeline, và mọi lệnh trả về một mã thoát có ý nghĩa: `0` thành công, `4` chưa đăng nhập, `5` thiếu một quyền (thông báo đặt tên cho nó, ví dụ `alerts:write`), `3` dashboard không thể tiếp cận. Một script có thể rẽ nhánh trên `4` để xác thực lại hoặc `5` để cho bạn biết chính xác những gì để yêu cầu quản trị viên, thay vì thất bại mà không biết gì. -## Để một coding agent điều khiển nó bằng ngôn ngữ tự nhiên +## Để một coding agent điều khiển nó bằng tiếng Anh thường -Tốt hơn, bạn không nên phải nhớ bất kỳ cờ nào trong số này. **CLI skill** là một thư mục Agent Skill nhỏ có tên `agenteye-cli` dạy một coding agent chẳng hạn như Claude Code hoặc Codex cách điều khiển CLI từ các yêu cầu bằng ngôn ngữ tự nhiên. Hỏi "có bất cứ điều gì bị hỏng hôm nay không?" và agent chọn lệnh, chạy nó dưới danh nghĩa bạn, và trả lời bằng văn bản. +Tốt hơn nữa, bạn không nên phải nhớ bất kỳ những cờ này cả. **CLI skill** là một thư mục Agent Skill nhỏ có tên `agenteye-cli` dạy cho một coding agent như Claude Code hoặc Codex cách điều khiển CLI từ các yêu cầu tiếng Anh thường. Hỏi "có cái gì bị hỏng hôm nay không?" và agent chọn lệnh, chạy nó dưới tư cách bạn, và trả lời bằng văn xuôi. -Đối với Claude Code, thả thư mục `agenteye-cli` vào `~/.claude/skills/` và nó sẽ được tự động phát hiện. Failproof AI Observability cung cấp thư mục; không có gì thêm để cài đặt, vì nó chỉ điều khiển CLI mà bạn đã cài đặt. Đăng nhập chính mình trước: skill không thể hoàn tất đăng nhập mã email cho bạn. +Đối với Claude Code, thả thư mục `agenteye-cli` vào `~/.claude/skills/` và nó được tự động phát hiện. Failproof AI Observability cung cấp thư mục; không có gì thêm để cài đặt, vì nó chỉ điều khiển CLI mà bạn đã cài đặt. Đăng nhập chính bạn trước tiên: skill không thể hoàn thành đăng nhập mã được gửi qua email cho bạn. -Vì agent chạy CLI dưới danh nghĩa bạn, nó có thể làm mọi thứ mà đăng nhập của bạn cho phép, cả đọc và ghi: tạo khóa, thay đổi cài đặt, giải quyết sự cố. Lời nhắc "bạn có chắc chắn không?" của CLI không kích hoạt đối với agent, vì vậy skill được viết để nêu lệnh chính xác và chờ OK của bạn trước bất kỳ thay đổi nào. Bạn là bước xác nhận. +Vì agent chạy CLI dưới tư cách bạn, nó có thể làm mọi thứ mà đăng nhập của bạn cho phép, đọc và ghi cả hai: tạo key, thay đổi cài đặt, giải quyết sự cố. Lời nhắc "bạn có chắc chắn không?" của CLI không kích hoạt cho một agent, vì vậy skill được viết để nêu ra lệnh chính xác và chờ OK của bạn trước bất kỳ thay đổi nào. Bạn là bước xác nhận. ```text you Why did session run-001 fail? @@ -58,7 +58,7 @@ agent Running: agenteye --json events --session-id run-001 --all The checkout-agent hit a TimeoutError on its third tool call. ``` -Các lần đọc vẫn nhanh tức thời, và mỗi lần ghi tạm dừng cho bạn: +Các lần đọc vẫn tức thì, và mọi lần ghi đều tạm dừng cho bạn: ```text you Give CI a key that can only push events. @@ -74,7 +74,7 @@ agent Done. Key "ci" created with events:add only. The secret is shown once, so ## Liên quan -- [Tham khảo CLI](/vi/agenteye/cli): mọi lệnh, cờ và hình dạng JSON. -- [Công thức CLI cho agent](/vi/agenteye/cli-recipes): mẫu `jq` sao chép dán và xử lý mã thoát. +- [CLI reference](/vi/agenteye/cli): mọi lệnh, cờ và hình dạng JSON. +- [CLI recipes for agents](/vi/agenteye/cli-recipes): các mẫu `jq` copy-paste và xử lý mã thoát. - [CLI agent skill](/vi/agenteye/cli-skill): cài đặt và chạy skill `agenteye-cli`. -- [Trợ lý AI](/vi/agenteye/assistant): nhà phân tích trong dashboard mà `agent ask` giao tiếp với. \ No newline at end of file +- [AI assistant](/vi/agenteye/assistant): nhà phân tích trong dashboard mà `agent ask` kết nối với. \ No newline at end of file diff --git a/docs/vi/agenteye/cli-recipes.mdx b/docs/vi/agenteye/cli-recipes.mdx index 12178479..18be7e07 100644 --- a/docs/vi/agenteye/cli-recipes.mdx +++ b/docs/vi/agenteye/cli-recipes.mdx @@ -1,29 +1,29 @@ --- title: "Công thức CLI cho agents" -description: "Sao chép các mẫu truy vấn và công thức jq giúp chuyển dữ liệu phiên, sự kiện và đánh giá thành thứ gì đó mà script hoặc coding agent có thể tự động hóa." +description: "Các mẫu truy vấn sẵn sàng sao chép và công thức jq biến dữ liệu phiên, sự kiện và đánh giá thành thứ mà một script hoặc coding agent có thể tự động hóa." --- -Pull dữ liệu phiên, sự kiện và đánh giá (cũng như kích hoạt lại các đánh giá) trực tiếp từ script hoặc coding agent, với JSON sạch trên stdout có thể pipe trực tiếp vào `jq`. Những công thức này biến dữ liệu Failproof AI Observability thành thứ gì đó mà người dùng terminal hoặc AI coding agent (Claude Code, Cursor) có thể truy vấn và tự động hóa, mà không cần click qua dashboard. +Kéo dữ liệu phiên, sự kiện và đánh giá (và kích hoạt lại các đánh giá) trực tiếp từ một script hoặc coding agent, với JSON sạch sẽ trên stdout có thể được piped trực tiếp vào `jq`. Các công thức này biến dữ liệu Failproof AI Observability thành thứ mà một người dùng terminal hoặc một coding agent (Claude Code, Cursor) có thể truy vấn và tự động hóa, mà không cần click qua dashboard. -Các mẫu bên dưới đã sẵn sàng để sao chép cho Failproof AI Observability CLI (`agenteye`). Để cài đặt, xác thực và danh sách tùy chọn đầy đủ, hãy xem [CLI](/vi/agenteye/cli); chạy `agenteye -h` hoặc `agenteye -h` để xem trợ giúp tích hợp. +Các mẫu dưới đây đã sẵn sàng để sao chép cho Failproof AI Observability CLI (`agenteye`). Để cài đặt, xác thực và danh sách tùy chọn đầy đủ, xem [CLI](/vi/agenteye/cli); chạy `agenteye -h` hoặc `agenteye -h` để xem trợ giúp tích hợp. -## Quy tắc vàng +## Các quy tắc vàng -1. **Các tùy chọn toàn cục phải đứng *trước* lệnh.** `agenteye --json sessions` là đúng; `agenteye sessions --json` là sai. Các tùy chọn toàn cục là `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Luôn truyền `--json` khi bạn phân tích kết quả.** Dữ liệu đi tới **stdout** dưới dạng JSON; thông tin trạng thái con người và lỗi đi tới **stderr**, vì vậy stdout vẫn sạch để pipe vào `jq`. -3. **Branch dựa trên exit code, không phải trên text stderr**: `0` ok · `1` lỗi không mong muốn · `2` đối số không hợp lệ · `3` không thể liên lạc với dashboard · `4` chưa đăng nhập hoặc hết hạn · `5` quyền bị thiếu · `6` tài nguyên không tìm thấy. -4. **Khám phá bằng `-h`.** Mỗi lệnh ghi chép các bộ lọc, định dạng giá trị và hình dạng JSON của nó. +1. **Các tùy chọn toàn cục đi *trước* lệnh.** `agenteye --json sessions` là đúng; `agenteye sessions --json` là không. Các tùy chọn toàn cục là `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Luôn truyền `--json` khi bạn phân tích đầu ra.** Dữ liệu đi đến **stdout** dưới dạng JSON; trạng thái con người và lỗi đi đến **stderr**, vì vậy stdout được giữ sạch sẽ để pipe vào `jq`. +3. **Phân nhánh dựa trên exit code**, không phải trên văn bản stderr: `0` ok · `1` lỗi không mong muốn · `2` đối số xấu · `3` không thể tiếp cận dashboard · `4` chưa đăng nhập hoặc hết hạn · `5` thiếu quyền · `6` không tìm thấy tài nguyên. +4. **Khám phá với `-h`.** Mọi lệnh đều ghi chép các bộ lọc, định dạng giá trị và hình dạng JSON. -## Cài đặt một lần +## Thiết lập một lần ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # để bạn không lặp lại --base-url -agenteye login --email you@example.com # dán mã được gửi qua email; hợp lệ ~24h +agenteye login --email you@example.com # dán mã được gửi qua email; có hiệu lực ~24h ``` ## Xác nhận xác thực trước khi làm việc -`whoami` không bao giờ xảy ra lỗi trên phiên bị thiếu hoặc hết hạn; thay vào đó nó báo cáo `logged_in:false`, vì vậy agent có thể an toàn kiểm tra trạng thái xác thực. (Nó vẫn có thể thoát khác không nếu không có URL cơ sở được đặt hoặc dashboard không thể tiếp cận.) +`whoami` không bao giờ báo lỗi khi phiên bị thiếu hoặc hết hạn; nó báo cáo `logged_in:false` thay vào đó, vì vậy một agent có thể an toàn kiểm tra trạng thái xác thực. (Nó vẫn có thể thoát khác không nếu không đặt URL cơ sở hoặc dashboard không thể truy cập.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -31,61 +31,61 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Tìm phiên thất bại hoặc điểm thấp +## Tìm các phiên không thành công hoặc có điểm thấp ```bash -# phiên trong 24h qua có đánh giá bị lỗi +# phiên trong 24h qua mà đánh giá gặp lỗi agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# đánh giá với điểm <= 0.5 về tính hữu ích, cho một agent +# đánh giá có điểm <= 0.5 về tính hữu ích, cho một agent agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Lọc điểm nằm trên **`evals`**, không phải `sessions`. `--score KEY:MIN..MAX` có thể lặp lại và kết hợp AND; bất kỳ giới hạn nào cũng tùy chọn (`..0.5` có nghĩa là ≤ 0.5, `0.9..` có nghĩa là ≥ 0.9). Bạn có thể truyền tối đa 20 bộ lọc điểm trên mỗi yêu cầu; nhiều hơn trả về HTTP 400. `sessions` chia sẻ các bộ lọc `--env`, `--status`, `--agent-id`, `--session-id` và phạm vi thời gian với `evals`, nhưng không có `--score`. +Bộ lọc điểm nằm trên **`evals`**, không phải `sessions`. `--score KEY:MIN..MAX` có thể lặp lại và được kết hợp AND; mỗi giới hạn là tùy chọn (`..0.5` có nghĩa là ≤ 0.5, `0.9..` có nghĩa là ≥ 0.9). Bạn có thể truyền tối đa 20 bộ lọc điểm cho mỗi yêu cầu; nhiều hơn sẽ trả về HTTP 400. `sessions` chia sẻ các bộ lọc `--env`, `--status`, `--agent-id`, `--session-id` và phạm vi thời gian với `evals`, nhưng không có `--score`. ## Đọc một phiên từ đầu đến cuối -Không có lệnh `session show` duy nhất. Kết hợp đường dẫn sự kiện với đánh giá phiên: +Không có lệnh `session show` duy nhất. Kết hợp dấu vết sự kiện với đánh giá của phiên: ```bash # đánh giá mới nhất của phiên (trạng thái + điểm) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# mọi sự kiện trong lần chạy (nâng --limit để quét đầy đủ) +# mọi sự kiện trong lần chạy (tăng --limit để quét đầy đủ) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# chỉ các cuộc gọi công cụ trong phiên (--full được yêu cầu để lấy payload thô) +# chỉ các lệnh gọi công cụ trong một phiên (--full được yêu cầu để lấy payload thô) agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **Lưu ý:** Theo mặc định, `events` đọc một nguồn cấp nhanh không có payload. Mỗi sự kiện mang một tóm tắt một dòng được tính toán bởi máy chủ `summary` cộng với các cờ như `is_error` và số lượng token, nhưng `payload` trả về là `{}`. Để lấy payload thô, thêm `--full` (hoặc `--fields payload`). Nguồn cấp đầy đủ chậm hơn ở quy mô, vì vậy hãy giữ nó bị giới hạn: kết hợp `--full` với một `--session-id` duy nhất. +> **Lưu ý:** Theo mặc định, `events` đọc một nguồn cấp dữ liệu nhanh không có payload. Mỗi sự kiện mang một dòng một dòng `summary` được tính toán bởi máy chủ cộng với các cờ như `is_error` và số lượng token, nhưng `payload` quay lại dưới dạng `{}`. Để kéo payload thô, thêm `--full` (hoặc `--fields payload`). Nguồn cấp dữ liệu đầy đủ chậm hơn ở quy mô lớn, vì vậy hãy giữ nó bị giới hạn: ghép `--full` với một `--session-id` duy nhất. -## Lấy mọi thứ (phân trang) +## Tìm nạp mọi thứ (phân trang) -Kết quả là mới nhất trước tiên và được phân trang với con trỏ. +Kết quả mới nhất trước tiên và được phân trang con trỏ. ```bash -# một lần: lấy tối đa 500 hàng trong các trang 200 hàng +# một lần: tìm nạp tối đa 500 hàng trong các trang 200 hàng agenteye --json events --session-id run-001 --limit 500 --all > events.json -# phân trang thủ công: đưa next_cursor trở lại +# phân trang thручу: cho con trỏ tiếp theo quay lại page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## Làm gọn kết quả với --fields +## Giảm bớt đầu ra với --fields -Hạn chế các khóa (trong cả bảng và `--json`) để giảm những gì agent phải đọc. +Hạn chế các khóa (trong cả bảng và `--json`) để giảm những gì một agent phải đọc. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Tên trường không xác định bị từ chối (thoát `2`) với danh sách hợp lệ, một cách rẻ tiền để khám phá tên trường. +Các tên trường không xác định bị từ chối (thoát `2`) cùng với danh sách hợp lệ, một cách rẻ tiền để khám phá tên trường. ## Khám phá các giá trị bộ lọc hợp lệ @@ -95,19 +95,19 @@ agenteye --json list tools | jq -r '.values[]' # tên công cụ; cũng agenteye --json list score_filters | jq -r '.values[]' # KEY hợp lệ cho --score KEY:MIN..MAX ``` -## Chọn org của bạn (đa người thuê) +## Chọn tổ chức của bạn (đa người thuê) -Nếu bạn thuộc về nhiều hơn một org, hãy chọn tenant hoạt động tại lúc đăng nhập (nó được lưu): +Nếu bạn thuộc về nhiều hơn một tổ chức, hãy chọn người thuê hoạt động khi đăng nhập (nó được lưu): ```bash -agenteye login --org acme --email you@corp.com # đặt tenant trong cùng bước với đăng nhập +agenteye login --org acme --email you@corp.com # đặt người thuê trong cùng bước với đăng nhập agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # ghi đè cho một lệnh ``` -Đăng nhập đa org mà không có `--org` thoát khác không và in các org để chọn từ. +Đăng nhập đa tổ chức mà không có `--org` sẽ thoát khác không và in các tổ chức để chọn. -## Cung cấp khóa API cho SDK/collector +## Cấp một khóa API cho SDK/collector ```bash # bí mật được in MỘT LẦN, với --json nó là trường .key @@ -115,14 +115,14 @@ key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # xoay vòng; agenteye keys disable ci-bot --yes để thu hồi ``` -## Chạy truy vấn đã lưu hoặc ad-hoc +## Chạy một truy vấn đã lưu hoặc ad-hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # một truy vấn đã lưu + positional $1 +agenteye --json query run errs --arg prod | jq '.rows' # một truy vấn đã lưu + một $1 vị trí ``` -## Phân loại sự cố không tương tác +## Phân loại một sự cố không tương tác ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -131,9 +131,9 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **Lưu ý:** Các đột biến tự động bỏ qua lời nhắc xác nhận của chúng dưới `--json` hoặc khi stdin không phải TTY, vì vậy agent không bao giờ treo; truyền `--yes`/`-y` để bỏ qua nó một cách rõ ràng ở nơi khác. +> **Lưu ý:** Các đột biến tự động bỏ qua lời nhắc xác nhận của họ dưới `--json` hoặc khi stdin không phải là TTY, vì vậy agents không bao giờ treo; truyền `--yes`/`-y` để bỏ qua nó rõ ràng ở nơi khác. -## Xử lý exit-code trong script +## Xử lý mã thoát trong một script ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -157,22 +157,22 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (key được hiển thị một lần) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` hiển thị một lần) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (any) | đối tượng tài nguyên, hoặc `{"deleted": true, "id"}` cho xóa | -| failure (any, với `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` trên stdout | +| tạo/cập nhật/xóa (bất kỳ) | đối tượng tài nguyên, hoặc `{"deleted": true, "id"}` cho các xóa | +| lỗi (bất kỳ, với `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` trên stdout | -- Mỗi mục **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Lưu ý rằng `payload` là `{}` trừ khi bạn yêu cầu nguồn cấp đầy đủ với `--full` (hoặc `--fields payload`). -- Mỗi mục **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- Mỗi mục **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- Mỗi mục **sự kiện** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`. Lưu ý rằng `payload` là `{}` trừ khi bạn yêu cầu nguồn cấp dữ liệu đầy đủ với `--full` (hoặc `--fields payload`). +- Mỗi mục **đánh giá** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- Mỗi mục **phiên** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -`--fields` của mỗi lệnh chấp nhận chính xác tên trường của mục riêng của nó. Tập hợp khác nhau giữa `sessions` và `evals`, vì vậy một tên hợp lệ cho một có thể bị từ chối bởi cái khác. +Mỗi `--fields` của lệnh chấp nhận chính xác tên trường của mục riêng của nó. Tập hợp khác nhau giữa `sessions` và `evals`, vì vậy tên hợp lệ cho một có thể bị từ chối bởi cái khác. ## Các bước tiếp theo -- [CLI](/vi/agenteye/cli): cài đặt, xác thực và tham chiếu tùy chọn đầy đủ cho mỗi lệnh. -- [CLI agent skill](/vi/agenteye/cli-skill): đóng gói những công thức này dưới dạng kỹ năng mà coding agent của bạn có thể tải. -- [API keys](/vi/agenteye/api-keys): tạo và xác định phạm vi các khóa mà CLI, SDK và collector xác thực bằng. -- [Python SDK](/vi/agenteye/python-sdk): gửi các sự kiện vào Failproof AI Observability để có dữ liệu để những công thức này truy vấn. \ No newline at end of file +- [CLI](/vi/agenteye/cli): cài đặt, xác thực và tham chiếu tùy chọn đầy đủ cho mọi lệnh. +- [CLI agent skill](/vi/agenteye/cli-skill): đóng gói các công thức này dưới dạng một kỹ năng mà coding agent của bạn có thể tải. +- [API keys](/vi/agenteye/api-keys): tạo và giới hạn các khóa CLI, SDK và collector xác thực. +- [Python SDK](/vi/agenteye/python-sdk): gửi sự kiện vào Failproof AI Observability để có dữ liệu cho các công thức này để truy vấn. \ No newline at end of file diff --git a/docs/vi/agenteye/cli-skill.mdx b/docs/vi/agenteye/cli-skill.mdx index f7e86787..ec87945d 100644 --- a/docs/vi/agenteye/cli-skill.mdx +++ b/docs/vi/agenteye/cli-skill.mdx @@ -1,159 +1,160 @@ --- -title: "Failproof AI Observability CLI Agent Skill" -description: "Hỏi agent coding của bạn \"có cái gì bị hỏng hôm nay không?\" và để nó trả lời từ dữ liệu Failproof AI Observability trực tiếp, không cần nhớ bất kỳ lệnh nào." +--- +title: "Kỹ năng CLI Agent Quan sát Failproof AI" +description: "Hỏi agent lập trình của bạn \"có gì bị hỏng hôm nay không?\" và để nó trả lời từ dữ liệu Quan sát Failproof AI trực tiếp của bạn, mà không cần nhớ các lệnh." --- -Hỏi agent coding của bạn *"có cái gì bị hỏng hôm nay không?"* và để nó trả lời từ dữ liệu Failproof AI Observability trực tiếp, không cần nhớ bất kỳ lệnh nào. **Failproof AI Observability CLI skill** (`agenteye-cli`) là một *Agent Skill*: một thư mục nhỏ chứa hướng dẫn mà một agent coding như Claude Code hoặc Codex có thể tải theo yêu cầu. Nó dạy agent cách vận hành deployment Observability của bạn thông qua [`agenteye` CLI](/vi/agenteye/cli) từ những yêu cầu bằng tiếng Anh thông thường như *"cấp cho CI một key chỉ có thể push events"* hoặc *"ack sự cố đang phát sinh và gán cho tôi."* +Hỏi agent lập trình của bạn *"có gì bị hỏng hôm nay không?"* và để nó trả lời từ dữ liệu Quan sát Failproof AI trực tiếp của bạn, mà không cần nhớ các lệnh. **Kỹ năng CLI Quan sát Failproof AI** (`agenteye-cli`) là một *Agent Skill*: một thư mục nhỏ chứa các hướng dẫn mà agent lập trình như Claude Code hoặc Codex có thể tải khi cần. Nó dạy agent cách hoạt động với triển khai Quan sát của bạn thông qua [`agenteye` CLI](/vi/agenteye/cli) từ các yêu cầu bằng tiếng Anh bình thường như *"tạo khóa cho CI chỉ có thể đẩy sự kiện"* hoặc *"xác nhận sự cố đang kích hoạt và gán cho tôi."* -Nó **không phải** một dịch vụ hoặc một binary riêng; không có gì để deploy. Nó chạy trên CLI bạn đã cài đặt: agent shell out tới `agenteye --json …`, phân tích JSON sạch, và trả lời bạn bằng văn bản. Mọi thứ nó có thể làm, bạn cũng có thể làm bằng cách gõ các lệnh tương tự. +Nó **không phải** là một dịch vụ hoặc một tệp nhị phân riêng biệt; không có gì để triển khai. Nó chạy trên CLI mà bạn đã cài đặt: agent gọi đến `agenteye --json …`, phân tích cú pháp JSON sạch sẽ, và trả lời bạn bằng văn bản. Mọi thứ nó có thể làm, bạn có thể tự làm bằng cách gõ các lệnh tương tự. --- -## Nó liên quan như thế nào đến các giao diện Failproof AI Observability khác +## Mối quan hệ với các giao diện Quan sát Failproof AI khác -Failproof AI Observability cung cấp bốn cách để truy cập dữ liệu và điều khiển giống nhau. Chúng bổ sung cho nhau: +Failproof AI Observability cung cấp cho bạn bốn cách để tiếp cận cùng một dữ liệu và điều khiển. Chúng bổ sung cho nhau: -| Giao diện | Nó là gì | Chạy ở đâu | Dùng khi | +| Giao diện | Nó là gì | Chạy ở đâu | Sử dụng khi | |---|---|---|---| -| **[CLI](/vi/agenteye/cli)** | Tham chiếu lệnh/flag cho `agenteye` | Terminal của bạn | Bạn muốn chạy hoặc viết script một lệnh cụ thể | -| **[CLI recipes](/vi/agenteye/cli-recipes)** | Các mẫu `jq`/pipeline sao chép được | Terminal/scripts của bạn | Bạn đang kết nối CLI vào tự động hóa | -| **CLI skill** (tài liệu này) | Cửa vào ngôn ngữ tự nhiên trên CLI | Agent coding của bạn, trên workstation | Bạn muốn *chỉ cần hỏi* và để agent chọn lệnh | -| **[Evaluator skill](/vi/agenteye/evaluator-skill)** | Một skill anh em thiết kế và xây dựng dịch vụ scoring của bạn | Agent coding của bạn, trên workstation | Bạn muốn *tạo* eval scores thay vì đọc chúng | -| **[Python SDK skill](/vi/agenteye/python-sdk-skill)** | Một skill anh em instrument agent của bạn để nó phát ra telemetry | Agent coding của bạn, trên workstation | Bạn muốn agent của bạn *tạo* các sự kiện mà skill này đọc | -| **[In-dashboard AI assistant](/vi/agenteye/assistant)** | Một chat nhúng trong dashboard | Phía server (trong dashboard) | Bạn muốn Q&A trong dashboard trên dữ liệu của bạn | +| **[CLI](/vi/agenteye/cli)** | Tham chiếu lệnh/cờ cho `agenteye` | Terminal của bạn | Bạn muốn chạy hoặc viết kịch bản một lệnh cụ thể | +| **[Công thức CLI](/vi/agenteye/cli-recipes)** | Các mẫu `jq`/đường dẫn sao chép dán | Terminal / kịch bản của bạn | Bạn đang kết nối CLI vào tự động hóa | +| **Kỹ năng CLI** (tài liệu này) | Cửa ngôn ngữ tự nhiên trên CLI | Agent lập trình của bạn, trên máy trạm của bạn | Bạn muốn *chỉ cần hỏi* và để agent chọn lệnh | +| **[Kỹ năng Evaluator](/vi/agenteye/evaluator-skill)** | Một kỹ năng anh em thiết kế và xây dựng dịch vụ ghi điểm của bạn | Agent lập trình của bạn, trên máy trạm của bạn | Bạn muốn *tạo* điểm đánh giá thay vì đọc chúng | +| **[Kỹ năng Python SDK](/vi/agenteye/python-sdk-skill)** | Một kỹ năng anh em để agent phát hành telemetry | Agent lập trình của bạn, trên máy trạm của bạn | Bạn muốn agent của bạn *tạo* các sự kiện mà kỹ năng này đọc | +| **[Trợ lý AI trong bảng điều khiển](/vi/agenteye/assistant)** | Một cuộc trò chuyện nhúng trong bảng điều khiển | Phía máy chủ (trong bảng điều khiển) | Bạn muốn Q&A trong bảng điều khiển trên dữ liệu của bạn | -Bản thân skill không có đặc quyền riêng; nó chỉ biến lời nói của bạn thành các lệnh CLI chạy với tư cách của bạn: +Bản thân kỹ năng không có đặc quyền riêng; nó chỉ chuyển các từ của bạn thành các cuộc gọi CLI chạy dưới tên bạn: ```mermaid flowchart TD - YOU["bạn: 'ack sự cố đang phát sinh'"] --> AGENT["agent coding (Claude Code / Codex)
tải agenteye-cli skill"] + YOU["bạn: 'xác nhận sự cố đang kích hoạt'"] --> AGENT["agent lập trình (Claude Code / Codex)
tải kỹ năng agenteye-cli"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|phiên CLI được xác thực của bạn| API["API dashboard Observability"] + CLI -->|phiên CLI đã xác thực của bạn| API["API bảng điều khiển Quan sát"] ``` -### so với in-dashboard AI assistant: một phân biệt quan trọng +### so với trợ lý AI trong bảng điều khiển: một sự phân biệt quan trọng -Đây là hai công cụ khác nhau với phạm vi ảnh hưởng rất khác nhau: +Đây là hai công cụ khác nhau với tầm ảnh hưởng rất khác nhau: -- **In-dashboard AI assistant** ([AI assistant](/vi/agenteye/assistant)) là một chat nhúng trong dashboard, được hỗ trợ bởi dịch vụ agent. Nó là **chỉ đọc cộng tác giả gated phê duyệt**: nó có thể soạn thảo các truy vấn đã lưu và dashboard, nhưng mọi ghi tạm dừng để chờ click phê duyệt rõ ràng của bạn, và nó không bao giờ xóa. Nó được gated bởi quyền `agent:use` và chỉ bao giờ nhìn thấy dữ liệu cho org bạn đang xem. -- **CLI skill** chạy trên *workstation* của bạn bên trong *agent* coding của bạn và điều khiển `agenteye` CLI với tư cách **bạn**. Nó có thể thực hiện **toàn bộ bề mặt của CLI, bao gồm cả mutations** (tạo/xoay/vô hiệu hóa API keys, thay đổi cài đặt org, giải quyết sự cố, xóa truy vấn đã lưu), được giới hạn chỉ bởi quyền của CLI login của bạn. Hãy coi nó chính xác như cách bạn sẽ chạy các lệnh đó bằng tay. +- **Trợ lý AI trong bảng điều khiển** ([AI assistant](/vi/agenteye/assistant)) là một cuộc trò chuyện nhúng trong bảng điều khiển, được hỗ trợ bởi dịch vụ agent. Nó **chỉ đọc cộng với tác giả có cấp phép**: nó có thể soạn thảo các truy vấn và bảng điều khiển đã lưu, nhưng mọi thao tác ghi đều tạm dừng để bạn phê duyệt rõ ràng, và nó không bao giờ xóa. Nó được kiểm soát bằng quyền `agent:use` và chỉ khi nào cũng chỉ nhìn thấy dữ liệu cho tổ chức bạn đang xem. +- **Kỹ năng CLI** chạy trên *máy trạm của bạn* bên trong *agent lập trình của bạn* và điều khiển `agenteye` CLI như **bạn**. Nó có thể thực hiện **toàn bộ bề mặt của CLI, bao gồm các thay đổi** (tạo/xoay/vô hiệu hóa khóa API, thay đổi cài đặt tổ chức, giải quyết sự cố, xóa truy vấn đã lưu), giới hạn chỉ bởi các quyền của đăng nhập CLI của bạn. Hãy xử lý nó chính xác như cách bạn sẽ xử lý khi chạy các lệnh đó bằng tay. --- ## Điều kiện tiên quyết -1. **`agenteye` CLI được cài đặt** và trên `PATH` (xem tham chiếu [CLI](/vi/agenteye/cli): `pipx install agenteye`). -2. **URL dashboard của bạn được đặt** (`AGENTEYE_DASHBOARD_URL`, hoặc agent truyền `--base-url`). -3. **Một phiên đã đăng nhập**: chạy `agenteye login` trước. Skill **không thể** hoàn thành login mã một lần được gửi qua email cho bạn; nó sẽ yêu cầu bạn chạy `agenteye login` nếu phiên bị mất hoặc hết hạn (mã thoát CLI `4`). +1. **`agenteye` CLI đã cài đặt** và trên `PATH` (xem tham chiếu [CLI](/vi/agenteye/cli): `pipx install agenteye`). +2. **URL bảng điều khiển của bạn** đã được đặt (`AGENTEYE_DASHBOARD_URL`, hoặc agent truyền `--base-url`). +3. **Phiên đăng nhập**: tự chạy `agenteye login` trước. Kỹ năng **không thể** hoàn thành đăng nhập mã một lần được gửi qua email cho bạn; nó sẽ bảo bạn chạy `agenteye login` nếu phiên bị mất hoặc hết hạn (mã thoát CLI `4`). --- -## Nơi để lấy nó +## Nơi lấy nó -Skill được xuất bản trong bộ sưu tập skills công cộng của Failproof AI: +Kỹ năng được công bố trong bộ sưu tập kỹ năng công khai của Failproof AI: **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -Không có gì về nó bị gated — kho lưu trữ là công cộng và skill không cần bất kỳ thông tin xác thực nào của riêng nó, vì nó chỉ điều khiển **công cộng** `agenteye` CLI chống lại *dashboard* của bạn, sử dụng phiên *bạn* đã đăng nhập. Bạn không cần phải yêu cầu ai để lấy nó. +Không có gì bị giới hạn về nó — kho lưu trữ là công khai và kỹ năng không cần bất kỳ thông tin xác thực riêng nào, bởi vì nó chỉ điều khiển CLI `agenteye` **công khai** với bảng điều khiển *của bạn*, sử dụng phiên *mà bạn* đã đăng nhập. Bạn không cần phải yêu cầu ai cấp nó. -Lưu ý nó được cung cấp dưới dạng thư mục riêng của nó và **không** nằm trong gói `pipx install agenteye`, vì vậy đừng tìm kiếm nó ở đó. +Lưu ý rằng nó được gửi dưới dạng thư mục riêng và **không** nằm trong gói `pipx install agenteye`, vì vậy đừng tìm kiếm nó ở đó. -## Cài đặt skill +## Cài đặt kỹ năng -Con đường nhanh nhất là CLI [`skills`](https://skills.sh), nó tìm nạp thư mục và đặt nó vào nơi agent của bạn tìm kiếm: +Đường dẫn nhanh nhất là CLI [`skills`](https://skills.sh), lấy thư mục và đặt nó nơi agent của bạn tìm kiếm: ```bash -# Claude Code, chỉ project này +# Claude Code, chỉ dự án này npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -# mọi project (cài đặt vào ~/.claude/skills/) +# mọi dự án (cài đặt vào ~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy -# Codex thay thế +# Codex thay vào đó npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -Sau đó quản lý nó như bất kỳ skill nào khác: +Sau đó quản lý nó như bất kỳ kỹ năng nào khác: ```bash -npx skills list -a claude-code # cái gì được cài đặt +npx skills list -a claude-code # những gì đã cài đặt npx skills update agenteye-cli # kéo phiên bản mới nhất -npx skills remove agenteye-cli # loại bỏ nó +npx skills remove agenteye-cli # xóa nó ``` -Thích cài đặt bằng tay? Một Agent Skill chỉ là một thư mục chứa `SKILL.md` (cộng với tham chiếu tùy chọn), vì vậy sao chép nó cũng hoạt động: +Thích cài đặt bằng tay? Một Agent Skill chỉ là một thư mục chứa `SKILL.md` (cộng với các tham chiếu tùy chọn), vì vậy sao chép nó cũng hoạt động: -- **Claude Code**: đặt thư mục `agenteye-cli/` trong `~/.claude/skills/` (mọi project) hoặc `/.claude/skills/` (chỉ repo đó). Claude Code tự động khám phá nó — xác minh bằng danh sách `/skills`, hoặc chỉ cần hỏi một câu hỏi phù hợp với mô tả của nó. -- **Codex (OpenAI)**: Codex đọc `SKILL.md` giống nhau. `agents/openai.yaml` đi kèm đặt `allow_implicit_invocation: true`, vì vậy Codex tự động chọn skill khi một tác vụ phù hợp; nếu không thì gọi nó rõ ràng là `$agenteye-cli`. +- **Claude Code**: đặt thư mục `agenteye-cli/` trong `~/.claude/skills/` (mọi dự án) hoặc `/.claude/skills/` (chỉ dự án đó). Claude Code tự động khám phá nó — xác minh với danh sách `/skills`, hoặc chỉ cần đặt câu hỏi phù hợp với mô tả của nó. +- **Codex (OpenAI)**: Codex đọc `SKILL.md` giống nhau. `agents/openai.yaml` đi kèm đặt `allow_implicit_invocation: true`, vì vậy Codex tự động chọn kỹ năng khi tác vụ phù hợp; nếu không, gọi nó rõ ràng là `$agenteye-cli`. --- -## Bảo mật: mutations KHÔNG nhắc khi agent chạy CLI +## An toàn: các thay đổi KHÔNG nhắc khi agent chạy CLI -> **Cảnh báo:** Đọc điều này trước khi để agent thực hiện các thay đổi. +> **Cảnh báo:** Đọc phần này trước khi để agent thực hiện các thay đổi. -CLI `agenteye` thường hỏi *"bạn có chắc không?"* trước một hành động phá hoại. Nó **tự động bỏ qua xác nhận đó bất cứ khi nào nó không được gắn vào terminal (đó chính xác là cách một agent coding chạy nó), và `--json` cũng bỏ qua nó.** Vì vậy dấu nhắc bảo mật sẽ **không** kích hoạt cho agent. +CLI `agenteye` thường hỏi *"bạn có chắc chắn không?"* trước một hành động phá hoại. Nó **tự động bỏ qua xác nhận đó bất cứ khi nào nó không được kết nối với thiết bị đầu cuối (đó chính xác là cách agent chạy nó), và `--json` cũng bỏ qua nó.** Vì vậy, lời nhắc bảo vệ sẽ **không** kích hoạt cho agent. -Skill được viết để bù đắp: nó được hướng dẫn để phát biểu lệnh chính xác mà nó sẽ chạy và nhận được **OK rõ ràng của bạn trước bất kỳ thay đổi trạng thái**. Giữ kỷ luật đó. Khi bạn điều khiển Failproof AI Observability thông qua một agent, *bạn* là bước xác nhận. Các lệnh thay đổi trạng thái để xem: +Kỹ năng được viết để bù đắp: nó được hướng dẫn để nêu ra lệnh chính xác mà nó sẽ chạy và nhận **OK rõ ràng từ bạn trước bất kỳ thay đổi trạng thái nào**. Giữ kỷ luật đó. Khi bạn điều khiển Failproof AI Observability thông qua agent, *bạn* là bước xác nhận. Các lệnh thay đổi trạng thái cần xem: - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` - `settings set` - `alerts create` / `update` / `delete` / `test` -- các lệnh con `incidents` ghi: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` +- các lệnh ghi của `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` - `query create` / `update` / `delete` - `agent rename` / `delete` - `orgs switch` -Mọi thứ dưới **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) là chỉ đọc và không thay đổi gì. +Mọi thứ dưới **Quan sát** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) chỉ đọc và không thay đổi gì. -Vì agent hoạt động với tư cách **bạn**, nó chỉ có thể làm những gì login của bạn được phép làm; quyền được phân giải **mỗi org** (xem [API keys](/vi/agenteye/api-keys)). Một lệnh bạn thiếu quyền cho nó trả về mã thoát `5` với quyền chính xác được đặt tên, vì vậy agent có thể cho bạn biết chính xác cần yêu cầu admin cái gì thay vì thất bại không rõ ràng. +Vì agent hoạt động như **bạn**, nó chỉ có thể làm những gì đăng nhập của bạn được phép làm; quyền được giải quyết **theo tổ chức** (xem [Khóa API](/vi/agenteye/api-keys)). Một lệnh mà bạn không có quyền trả về mã thoát `5` với quyền chính xác được đặt tên, vì vậy agent có thể cho bạn biết chính xác những gì cần yêu cầu từ quản trị viên thay vì thất bại một cách mờ ám. --- -## Bạn có thể hỏi nó gì +## Những gì bạn có thể hỏi -Đây là những gì một chuyến đi thực tế trông như thế nào, một lần đọc, sau đó là một thay đổi chờ OK của bạn: +Đây là cách một vòng lặp thực tế trông như thế nào, đọc trước, sau đó là một thay đổi chờ OK của bạn: ```text -bạn ▸ Có cái gì bị hỏng trong 24h qua không? +bạn ▸ Có gì bị hỏng trong ngày qua không? agent ▸ Chạy: agenteye --json errors --since 24h --aggregate - 3 loại lỗi trong 24h qua. Cái lớn nhất là TimeoutError - (18 lần, đều trên checkout-agent), sau đó là RateLimited (5). - Bạn muốn các phiên bị lỗi cho TimeoutError không? + 3 loại lỗi trong 24 giờ qua. Lớn nhất là TimeoutError + (18 lần, tất cả trên checkout-agent), sau đó RateLimited (5). + Bạn có muốn biết các phiên bị hỏng cho TimeoutError không? -bạn ▸ Cấp cho CI một key chỉ có thể push events. +bạn ▸ Tạo khóa cho CI chỉ có thể đẩy sự kiện. -agent ▸ Điều này tạo một API key. Tôi sẽ chạy: +agent ▸ Điều này tạo một khóa API. Tôi sẽ chạy: agenteye keys create ci --add events:add OK để tiếp tục? -bạn ▸ yes +bạn ▸ có -agent ▸ Xong. Key "ci" được tạo với chỉ events:add. - Secret chỉ được hiển thị một lần, vì vậy lưu trữ nó ngay bây giờ. Tôi không thể in lại nó. +agent ▸ Hoàn thành. Khóa "ci" được tạo với chỉ events:add. + Bí mật chỉ hiển thị một lần, vì vậy hãy lưu trữ nó bây giờ. Tôi không thể in lại nó. ``` -Skill ánh xạ mỗi ý định ngôn ngữ tự nhiên thành lệnh `agenteye` đúng, khám phá các giá trị hợp lệ trước (`list `, `whoami`) để nó không đoán, và phát biểu lệnh chính xác trước bất kỳ thay đổi. Ví dụ thêm: +Kỹ năng ánh xạ mỗi ý định bằng ngôn ngữ tự nhiên tới lệnh `agenteye` phù hợp, khám phá các giá trị hợp lệ trước (`list `, `whoami`) vì vậy nó không đoán, và nêu lệnh chính xác trước bất kỳ thay đổi nào. Thêm ví dụ: -- *"Có cái gì bị hỏng / fail trong 24h qua không?"* → `errors --since 24h --aggregate`, sau đó là một phân tích. -- *"Tại sao phiên `run-001` lại fail?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. -- *"Chất lượng đang xu hướng như thế nào tuần này?"* → `evals --aggregate --since 7d`, sau đó đi sâu vào các chạy có điểm thấp. -- *"Cấp cho CI một key chỉ có thể push events."* → `keys create ci --add events:add` (nó phát biểu lệnh, sau đó tạo nó và bắt secret một lần). -- *"Ai có quyền truy cập? Làm Dana chỉ đọc."* → `users list` → `users update dana@… --permission-set read-only` (sau khi xác nhận với bạn). -- *"Ack sự cố đang phát sinh và gán cho tôi."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. +- *"Có gì bị hỏng / thất bại trong 24 giờ qua không?"* → `errors --since 24h --aggregate`, sau đó là một bảng phân tích. +- *"Tại sao phiên `run-001` thất bại?"* → `events --session-id run-001 --all` + `evals --session-id run-001`. +- *"Chất lượng đang xu hướng như thế nào tuần này?"* → `evals --aggregate --since 7d`, sau đó đi sâu vào các lần chạy có điểm thấp. +- *"Tạo khóa cho CI chỉ có thể đẩy sự kiện."* → `keys create ci --add events:add` (nó nêu ra lệnh, sau đó tạo nó và nắm bí mật một lần). +- *"Ai có quyền truy cập? Làm cho Dana chỉ đọc."* → `users list` → `users update dana@… --permission-set read-only` (sau khi xác nhận với bạn). +- *"Xác nhận sự cố đang kích hoạt và gán cho tôi."* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`. -Để xem các lệnh chính xác, flag, và hình dạng JSON đằng sau những thứ này, xem tham chiếu [CLI](/vi/agenteye/cli) và [CLI recipes cho agents](/vi/agenteye/cli-recipes). +Để biết các lệnh, cờ và hình dạng JSON chính xác đằng sau những điều này, xem tham chiếu [CLI](/vi/agenteye/cli) và [Công thức CLI cho agent](/vi/agenteye/cli-recipes). --- ## Bước tiếp theo -- **[CLI](/vi/agenteye/cli)**: tham chiếu lệnh và flag đầy đủ cho `agenteye`. -- **[CLI recipes cho agents](/vi/agenteye/cli-recipes)**: các mẫu `jq` sao chép được và xử lý mã thoát. -- **[Evaluator agent skill](/vi/agenteye/evaluator-skill)**: skill anh em, để xây dựng evaluator mà `agenteye evals` đọc. -- **[Python SDK agent skill](/vi/agenteye/python-sdk-skill)**: skill anh em, để instrument agent để nó phát ra telemetry mà `agenteye` đọc. -- **[AI assistant](/vi/agenteye/assistant)**: assistant trong dashboard (không nên nhầm lẫn với skill terminal này). -- **[API keys](/vi/agenteye/api-keys)**: mô hình quyền mỗi org bounding cái gì skill có thể làm. \ No newline at end of file +- **[CLI](/vi/agenteye/cli)**: tham chiếu lệnh và cờ đầy đủ cho `agenteye`. +- **[Công thức CLI cho agent](/vi/agenteye/cli-recipes)**: các mẫu `jq` sao chép dán và xử lý mã thoát. +- **[Kỹ năng agent Evaluator](/vi/agenteye/evaluator-skill)**: kỹ năng anh em, để xây dựng evaluator mà `agenteye evals` đọc. +- **[Kỹ năng agent Python SDK](/vi/agenteye/python-sdk-skill)**: kỹ năng anh em, để agent công cụ phát hành telemetry mà `agenteye` đọc. +- **[Trợ lý AI](/vi/agenteye/assistant)**: trợ lý trong bảng điều khiển (không nên nhầm lẫn với kỹ năng terminal này). +- **[Khóa API](/vi/agenteye/api-keys)**: mô hình quyền theo tổ chức giới hạn những gì kỹ năng có thể làm. \ No newline at end of file diff --git a/docs/vi/agenteye/cli.mdx b/docs/vi/agenteye/cli.mdx index ae75a77b..856f99f0 100644 --- a/docs/vi/agenteye/cli.mdx +++ b/docs/vi/agenteye/cli.mdx @@ -1,24 +1,24 @@ --- title: "CLI" -description: "Điều khiển toàn bộ Failproof AI Observability từ terminal hoặc script: không cần quay vòng bảng điều khiển." +description: "Điều khiển toàn bộ Failproof AI Observability từ terminal hoặc một script: không cần truy cập dashboard." --- -Điều khiển toàn bộ Failproof AI Observability từ terminal hoặc script: không cần quay vòng bảng điều khiển. CLI `agenteye` truy vấn dữ liệu của bạn (phiên, nhật ký sự kiện, đánh giá) và quản lý tổ chức (khóa API, người dùng, cài đặt, cảnh báo, sự cố, truy vấn đã lưu), vì vậy hãy sử dụng nó khi muốn tự động hóa một kiểm tra, tích hợp Observability vào CI, hoặc cho một tác nhân mã hóa kiểm tra sản xuất. Mọi lệnh đều hỗ trợ cờ `--json`, vì vậy nó hoạt động như nhau cho bạn ở dòng lệnh hoặc cho một tác nhân mã hóa (Claude Code, Cursor) thực thi và phân tích kết quả. +Điều khiển toàn bộ Failproof AI Observability từ terminal hoặc một script: không cần truy cập dashboard. CLI `agenteye` truy vấn dữ liệu của bạn (sessions, event logs, evaluations) và quản trị tổ chức của bạn (API keys, users, settings, alerts, incidents, saved queries), vì vậy hãy sử dụng nó khi bạn muốn tự động hóa một kiểm tra, kết nối Observability vào CI, hoặc để cho một coding agent kiểm tra production. Mỗi lệnh hỗ trợ flag `--json`, vì vậy nó hoạt động như nhau cho bạn ở dòng lệnh hoặc cho một coding agent (Claude Code, Cursor) thực thi lệnh và phân tích kết quả. -Với một nhị phân bạn có thể: +Với một binary duy nhất bạn có thể: -- **Đọc dữ liệu của bạn**: `sessions`, `events`, `evals`, `errors` (lọc theo thời gian, tác nhân, môi trường, điểm số). +- **Đọc dữ liệu của bạn**: `sessions`, `events`, `evals`, `errors` (lọc theo thời gian, agent, env, score). - **Quản lý tổ chức**: `keys`, `users`, `settings`, `alerts`, `incidents`. -- **Chạy phân tích**: SQL đã lưu và trình chạy truy vấn ad-hoc (`query`). -- **Hỏi trợ lý AI**: cùng một nhà phân tích chỉ đọc mà bạn trò chuyện trong bảng điều khiển (`agent`). +- **Chạy analytics**: SQL đã lưu và trình chạy truy vấn ad-hoc (`query`). +- **Hỏi trợ lý AI**: cùng một nhà phân tích read-only mà bạn trò chuyện với trong dashboard (`agent`). -> **Lưu ý:** Đây là CLI `agenteye`, một công cụ khác biệt với daemon bộ sưu tập (`agenteye-collector`). CLI tương tác với bảng điều khiển của bạn; bộ sưu tập gửi sự kiện đến máy chủ. +> **Lưu ý:** Đây là CLI `agenteye`, một công cụ khác với daemon collector (`agenteye-collector`). CLI giao tiếp với dashboard của bạn; collector vận chuyển events đến server. --- -## Khởi động nhanh +## Quickstart -Từ không có gì đến kết quả đầu tiên trong bốn dòng. Trỏ CLI đến bảng điều khiển, đăng nhập, xác nhận danh tính của bạn, sau đó kéo lên các lần chạy của ngày hôm qua: +Từ không có gì đến kết quả đầu tiên của bạn trong bốn dòng. Hướng CLI đến dashboard của bạn, đăng nhập, xác nhận danh tính của bạn, rồi lấy các lần chạy từ ngày hôm qua: ```bash pipx install agenteye @@ -27,7 +27,7 @@ agenteye whoami agenteye --json sessions --since 24h # one row per agent run, last 24h ``` -Lệnh cuối cùng in một đối tượng JSON của các phiên gần đây nhất (mới nhất trước, giới hạn ở 50 theo mặc định). Đẩy nó vào `jq` để cắt nó, hoặc bỏ `--json` để có bảng được khoanh vùng và màu hóa. Mỗi hàng mang trạng thái của lần chạy và, nếu người đánh giá chấm điểm, các điểm số mã (được viết tắt ở đây): +Lệnh cuối cùng in một object JSON của các sessions gần đây nhất (mới nhất trước, giới hạn 50 theo mặc định). Pipe nó vào `jq` để cắt nó, hoặc bỏ `--json` để có một bảng được boxed và colorized. Mỗi dòng có trạng thái của lần chạy và, nếu một evaluator chấm điểm nó, các điểm số metric của nó (viết tắt ở đây): ```json { @@ -47,13 +47,13 @@ Lệnh cuối cùng in một đối tượng JSON của các phiên gần đây } ``` -Phần còn lại của trang này giải thích từng phần: [cài đặt](#installation) riêng lẻ, [đăng nhập](#authentication), [cấu hình](#configuration), [quy ước toàn cầu](#global-options--conventions) mà mọi lệnh chia sẻ, và [tài liệu tham khảo lệnh đầy đủ](#command-reference). +Phần còn lại của trang này giải thích từng phần: [cài đặt](#installation) trong sự cô lập, [đăng nhập](#authentication), [cấu hình](#configuration), các [quy ước toàn cầu](#global-options--conventions) mà mỗi lệnh chia sẻ, và [tham chiếu lệnh đầy đủ](#command-reference). --- -## Cài đặt +## Installation -CLI là một gói PyPI công khai có tên **`agenteye`**. Cài đặt nó trong một môi trường cách ly để nó luôn có những phụ thuộc riêng của nó: +CLI là một package PyPI công khai có tên **`agenteye`**. Cài đặt nó trong một môi trường cô lập để nó luôn có các dependencies riêng của nó: ```bash pipx install agenteye @@ -68,35 +68,35 @@ agenteye --version agenteye --help ``` -> **Lưu ý:** SDK Python Failproof AI Observability cũng sử dụng tên phân phối `agenteye`. Cài đặt CLI với `pipx` hoặc `uv tool` (thay vì `pip install` vào một virtualenv chia sẻ) giữ hai cái khác nhau. `pip install agenteye` đơn giản là tốt chỉ khi SDK không được cài đặt trong cùng một môi trường. +> **Lưu ý:** SDK Python Failproof AI Observability cũng sử dụng tên phân phối `agenteye`. Cài đặt CLI với `pipx` hoặc `uv tool` (thay vì `pip install` vào một shared virtualenv) ngăn chặn hai cái này không va chạm. Một `pip install agenteye` đơn giản là ổn chỉ nếu SDK không được cài đặt trong cùng một môi trường. --- -## Xác thực +## Authentication -CLI xác thực với **bảng điều khiển** bằng mã một lần được gửi qua email: +CLI xác thực cho **dashboard** với một mã một lần được gửi qua email: ```bash agenteye login --email you@example.com # A 6-digit code is emailed to you; paste it at the prompt. ``` -Mã thông báo phiên được lưu trữ trong `~/.agenteye/cli.json` (chỉ có thể đọc được bởi bạn, chế độ `0600`) và hợp lệ trong 24 giờ theo mặc định. Khi nó hết hạn, chạy `agenteye login` lại. +Session token được lưu trữ trong `~/.agenteye/cli.json` (chỉ có thể đọc bởi bạn, mode `0600`) và hợp lệ trong 24 giờ theo mặc định. Khi nó hết hạn, chạy `agenteye login` lại. ```bash agenteye whoami # show the current user, active org, and permissions agenteye logout # revoke the session and clear the stored token ``` -`whoami` không bao giờ gặp lỗi trên một phiên bị mất hoặc hết hạn; nó báo cáo `logged_in: false` thay thế, vì vậy một script hoặc tác nhân có thể kiểm tra trạng thái xác thực một cách an toàn (nó vẫn có thể thoát khác không nếu không có URL cơ sở được đặt hoặc bảng điều khiển không thể tiếp cận). +`whoami` không bao giờ gặp lỗi trên một session bị mất hoặc hết hạn; nó báo cáo `logged_in: false` thay thế, vì vậy một script hoặc agent có thể điều tra auth state một cách an toàn (nó vẫn có thể thoát với mã khác 0 nếu không có base URL được đặt hoặc dashboard không thể truy cập được). -**Yêu cầu:** email của bạn phải được phép đăng nhập vào bảng điều khiển (hãy yêu cầu quản trị viên Failproof AI Observability), và bảng điều khiển phải có thể tiếp cận được tại URL cơ sở của nó (xem [Cấu hình](#configuration)). Nếu bạn yêu cầu mã và không có mã nào đến, email của bạn có thể chưa được kích hoạt để truy cập bảng điều khiển. +**Yêu cầu:** email của bạn phải được phép đăng nhập vào dashboard (hãy hỏi quản trị viên Failproof AI Observability của bạn), và dashboard phải có thể truy cập được tại base URL của nó (xem [Configuration](#configuration)). Nếu bạn yêu cầu một mã và không có gì được gửi, email của bạn có thể chưa được kích hoạt để truy cập dashboard. --- -## Chọn tổ chức của bạn (đa người thuê) +## Choosing your org (multi-tenant) -Nếu tài khoản của bạn thuộc về nhiều hơn một tổ chức, chọn tổ chức hoạt động **tại lúc đăng nhập**; nó được lưu và sử dụng cho mọi lệnh sau này: +Nếu tài khoản của bạn thuộc về nhiều hơn một org, chọn org hoạt động **tại login**; nó được lưu và sử dụng cho mỗi lệnh sau này: ```bash agenteye login --org acme # authenticate and set the active tenant in one step @@ -105,89 +105,89 @@ agenteye orgs switch globex # change the saved default agenteye --org globex sessions # override for a single command ``` -Nếu bạn chỉ thuộc về chính xác một tổ chức, nó sẽ được chọn tự động và bạn có thể bỏ qua `--org` hoàn toàn. Nếu bạn thuộc về nhiều và không chọn một cái, CLI liệt kê chúng và yêu cầu bạn chạy lại với `--org `. Tổ chức hoạt động được gửi đến bảng điều khiển trên mọi yêu cầu, và các quyền của bạn được giải quyết **cho mỗi tổ chức**; `agenteye whoami` hiển thị tổ chức hoạt động, các quyền của bạn trong đó và tất cả các thành viên của bạn. +Nếu bạn chỉ thuộc về chính xác một org thì nó được chọn tự động và bạn có thể bỏ qua `--org` hoàn toàn. Nếu bạn thuộc về nhiều org và không chọn một, CLI liệt kê chúng và yêu cầu bạn chạy lại với `--org `. Org hoạt động được gửi đến dashboard trên mỗi yêu cầu, và quyền của bạn được phân quyền **per org**; `agenteye whoami` hiển thị org hoạt động, quyền của bạn trong đó, và tất cả các thành viên của bạn. --- -## Cấu hình +## Configuration -| Cài đặt | Cờ | Biến môi trường | Mặc định | +| Setting | Flag | Environment variable | Default | |---|---|---|---| -| URL cơ sở bảng điều khiển | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **bắt buộc** (không có mặc định) | -| Tổ chức/người thuê hoạt động | `--org` | `AGENTEYE_ORG` | được chọn tại lúc đăng nhập; được lưu trong `~/.agenteye/cli.json` | -| Mã thông báo phiên | `--token` | `AGENTEYE_CLI_TOKEN` | từ `~/.agenteye/cli.json` | -| Đầu ra JSON | `--json` | `AGENTEYE_CLI_JSON` | tắt | -| Bỏ qua xác minh TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | tắt (được lưu tại lúc đăng nhập) | -| Hết thời gian yêu cầu (giây) | `--timeout` | _(không có)_ | 30 | -| Vô hiệu hóa telemetry sử dụng | _(không có)_ | `AGENTEYE_ANALYTICS_DISABLED` (hoặc `DO_NOT_TRACK`) | telemetry hiện được vô hiệu hóa; không có gì được gửi | +| Dashboard base URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **required** (no default) | +| Active org/tenant | `--org` | `AGENTEYE_ORG` | chosen at login; saved in `~/.agenteye/cli.json` | +| Session token | `--token` | `AGENTEYE_CLI_TOKEN` | from `~/.agenteye/cli.json` | +| JSON output | `--json` | `AGENTEYE_CLI_JSON` | off | +| Skip TLS verification | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | off (saved at login) | +| Request timeout (seconds) | `--timeout` | _(none)_ | 30 | +| Disable usage telemetry | _(none)_ | `AGENTEYE_ANALYTICS_DISABLED` (or `DO_NOT_TRACK`) | telemetry is currently disabled; nothing is sent | -Thứ tự phân giải là **cờ → biến môi trường → tệp cấu hình**. Không có mặc định; bạn phải trỏ CLI đến bảng điều khiển, cho mỗi lệnh (`--base-url https://agenteye.example.com`) hoặc một lần qua môi trường (nó cũng được lưu sau `login` đầu tiên của bạn): +Thứ tự phân quyết là **flag → environment variable → config file**. Không có mặc định; bạn phải hướng CLI đến dashboard của bạn, theo lệnh (`--base-url https://agenteye.example.com`) hoặc một lần qua environment (nó cũng được lưu sau `login` đầu tiên của bạn): ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -Thư mục cấu hình tôn trọng `AGENTEYE_HOME` (cùng quy ước được sử dụng bởi SDK và bộ sưu tập); nếu được đặt, `cli.json` nằm trong `$AGENTEYE_HOME/cli.json`. +Thư mục cấu hình tôn trọng `AGENTEYE_HOME` (cùng quy ước được sử dụng bởi SDK và collector); nếu được đặt, `cli.json` sống trong `$AGENTEYE_HOME/cli.json`. -### TLS tự ký hoặc nội bộ +### Self-signed or internal TLS -Nếu bảng điều khiển của bạn được phục vụ qua HTTPS với chứng chỉ tự ký hoặc nội bộ (ví dụ: tên máy chủ cân bằng tải thô), xác minh TLS sẽ từ chối nó với lỗi `CERTIFICATE_VERIFY_FAILED`. Chuyển `--insecure` để bỏ qua xác minh chứng chỉ: +Nếu dashboard của bạn được phục vụ qua HTTPS với chứng chỉ self-signed hoặc nội bộ (ví dụ, hostname load-balancer thô), xác minh TLS từ chối nó với lỗi `CERTIFICATE_VERIFY_FAILED`. Chuyển `--insecure` để bỏ qua xác minh chứng chỉ: ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -`--insecure` **được lưu vào `cli.json` khi bạn đăng nhập**, vì vậy các lệnh sau bỏ qua xác minh tự động; bạn không phải lặp lại cờ. Chuyển `--secure` cho một lệnh đã xác minh một lần, hoặc để lưu xác minh lại tại `login` tiếp theo của bạn. CLI in một cảnh báo đến stderr trước bất kỳ lệnh nào liên hệ với bảng điều khiển trong khi xác minh bị vô hiệu hóa. Bỏ qua xác minh loại bỏ bảo vệ chống tấn công trung gian; hãy đảm bảo bạn tin tưởng đường dẫn mạng đến bảng điều khiển của bạn (VPN, mạng con riêng, v.v.) trước khi dựa vào nó. +`--insecure` được **lưu vào `cli.json` khi bạn đăng nhập**, vì vậy các lệnh sau này bỏ qua xác minh tự động; bạn không phải lặp lại flag. Chuyển `--secure` để một cuộc gọi được xác minh một lần, hoặc để lưu xác minh trở lại bật tại `login` tiếp theo của bạn. CLI in một cảnh báo đến stderr trước bất kỳ lệnh nào liên hệ với dashboard trong khi xác minh bị vô hiệu hóa. Bỏ qua xác minh loại bỏ bảo vệ chống lại các cuộc tấn công man-in-the-middle; đảm bảo bạn tin tưởng đường đi mạng tới dashboard của bạn (VPN, private subnet, v.v.) trước khi dựa vào nó. --- -## Telemetry & quyền riêng tư +## Telemetry & privacy -> **Lưu ý:** CLI được gửi **không có telemetry sử dụng ngày hôm nay.** Một công tắc tắt chính được bật, vì vậy không có gì được truyền tải bất kể môi trường của bạn. Phần dưới đây mô tả khả năng từ chối nếu và khi telemetry bao giờ được kích hoạt. +> **Lưu ý:** CLI được vận chuyển **không gửi telemetry sử dụng nào hôm nay.** Một master kill switch được bật, vì vậy không có gì được truyền bất kể environment của bạn. Phần bên dưới mô tả khả năng opt-out cho trường hợp telemetry bao giờ được bật. -Ngay cả khi được kích hoạt, telemetry sẽ **chỉ là phân tích sử dụng ẩn danh**, không bao giờ tác nhân, phiên hoặc dữ liệu sự kiện của bạn: +Ngay cả khi được kích hoạt, telemetry sẽ là **anonymous usage analytics only**, không bao giờ agent, session, hoặc event data của bạn: -- **Dữ liệu tác nhân, phiên hoặc sự kiện không bao giờ rời khỏi cơ sở hạ tầng của bạn.** Chỉ sử dụng CLI sẽ được báo cáo: tên lệnh và lệnh con (ví dụ: `keys create`), **tên** các cờ bạn sử dụng (không bao giờ giá trị của chúng), trạng thái thành công/thoát và thời lượng, cộng với một sự kiện cho mỗi hành động cho các đột biến (ví dụ: `api_key_created`, `query_run`) chỉ mang tên/enums tĩnh và số lượng thô. URL bảng điều khiển, mã thông báo phiên, email, slug org, id tài nguyên, SQL, bí mật khóa và bộ lọc truy vấn sẽ **không bao giờ** được gửi. Các nhà khai thác sẽ được xác định chỉ bằng id nội bộ không rõ, không bao giờ bằng email. -- **Chọn không** trước thời hạn bằng cách đặt `AGENTEYE_ANALYTICS_DISABLED=1` trong môi trường CLI (CLI cũng tôn trọng quy ước `DO_NOT_TRACK=1` liên công cụ). Điều này có hiệu lực ngay khi telemetry bao giờ được bật, vì vậy một môi trường có ý thức về quyền riêng tư có thể ở ngoài vĩnh viễn. -- Nếu telemetry được kích hoạt, CLI sẽ gửi trực tiếp đến PostHog (`https://us.i.posthog.com`); một máy có máy chủ đó bị chặn sẽ im lặng gửi không có gì và CLI sẽ không bị ảnh hưởng. +- **Không có agent, session, hoặc event data nào bao giờ rời khỏi cơ sở hạ tầng của bạn.** Chỉ CLI usage sẽ được báo cáo: tên command và subcommand (ví dụ `keys create`), **tên** các flag bạn sử dụng (không bao giờ giá trị của chúng), trạng thái thành công/thoát, và thời lượng, cộng với mỗi action event cho mutations (ví dụ `api_key_created`, `query_run`) chỉ mang các tên/enums tĩnh và số lượng thô. URL dashboard, session token, email, org slug, resource ids, SQL, key secrets, và query filters của bạn sẽ **không bao giờ** được gửi. Operators sẽ được xác định chỉ bởi một id nội bộ mơ hồ, không bao giờ bởi email. +- **Opt out trước thời gian** bằng cách đặt `AGENTEYE_ANALYTICS_DISABLED=1` trong environment của CLI (CLI cũng tôn trọng quy ước cross-tool `DO_NOT_TRACK=1`). Điều này có hiệu lực khi telemetry bao giờ được bật, vì vậy một environment có ý thức về quyền riêng tư có thể được opt out vĩnh viễn. +- Nếu telemetry được bật, CLI sẽ gửi trực tiếp đến PostHog (`https://us.i.posthog.com`); một máy có host đó bị chặn sẽ im lặng gửi không gì cả và CLI sẽ không bị ảnh hưởng. --- -## Tùy chọn toàn cầu & quy ước +## Global options & conventions -Đọc cái này một lần; nó áp dụng cho mọi lệnh. +Đọc cái này một lần; nó áp dụng cho mỗi lệnh. -- **Các tùy chọn toàn cầu đi TRƯỚC lệnh.** `agenteye --json sessions` là chính xác; `agenteye sessions --json` là lỗi sử dụng. Các toàn cầu là `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` và `--no-color`. -- **`--json` in JSON thuần túy đến stdout, và không có gì khác.** Các dòng trạng thái con người, cảnh báo và lỗi đi đến **stderr**, vì vậy bộ sưu tập `--json` stdout sạch để đẩy vào `jq` ngay cả khi một dòng trạng thái được hiển thị. Không có `--json` bạn có được một cái nhìn được khoanh vùng, màu hóa cho con người. -- **Khám phá với `--help`.** Mọi lệnh và lệnh con đều có `--help` (và bí danh `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. Trợ giúp cấp cao nhất cũng liệt kê các mã thoát và tùy chọn toàn cầu. Không có bề mặt toàn cầu có thể đọc được máy; sử dụng `--help` cho mỗi lệnh, cộng với các trích dẫn dành riêng cho miền `agenteye query schema` và `agenteye settings schema` cho hai sổ đăng ký đó. -- **Xác nhận tự động bỏ qua đối với script và tác nhân.** Các lệnh tạo/cập nhật/xóa nhắc "bạn có chắc chắn?" trong một thiết bị đầu cuối tương tác, nhưng **tự động bỏ qua lời nhắc đó dưới `--json` hoặc bất cứ khi nào stdin không phải là TTY** (TTY là một phiên terminal tương tác; một đường ống hoặc trình chạy CI không phải), vì vậy các script và tác nhân không bao giờ treo. Chuyển `--yes`/`-y` để bỏ qua nó một cách rõ ràng. Vì lời nhắc sẽ không kích hoạt cho tác nhân, tác nhân sẽ xác nhận các hành động phá hủy với con người trước tiên. -- **Phân trang:** kết quả là mới nhất trước và con trỏ phân trang (mỗi trang trả về mã thông báo bạn sử dụng để tìm nạp tiếp theo). `--limit N` (bí danh `-n`) giới hạn hàng và **mặc định là 50**; `--all` tự động phân trang (trong 200 hàng) **lên đến `--limit`**, vì vậy `--all` không có gì vẫn dừng lại ở 50. Để quét đầy đủ, chuyển một giới hạn rõ ràng cao: `--all --limit 1000`. `--page-size N` kiểm soát khoảng con trỏ (tối đa 200); `--cursor ` tiếp tục từ `next_cursor` của trang trước. -- **Bộ lọc thời gian:** `--since` lấy một cửa sổ tương đối: `15m`, `1h`, `6h`, `24h`, `7d` hoặc `all` (cài đặt của bảng điều khiển). Cho một khoảng dài hơn hoặc tùy chỉnh (nói 30 ngày trước), sử dụng `--from`/`--to`: dấu thời gian UTC ISO-8601 rõ ràng **với `T` và múi giờ** (ví dụ: `2026-06-01T00:00:00Z`) ghi đè `--since`. Giá trị được phân tách bằng dấu cách hoặc không có múi giờ là lỗi sử dụng. +- **Global options đi TRƯỚC lệnh.** `agenteye --json sessions` là đúng; `agenteye sessions --json` là một lỗi sử dụng. Các globals là `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, và `--no-color`. +- **`--json` in pure JSON đến stdout, và không có gì khác.** Các dòng trạng thái human, warnings, và errors đi đến **stderr**, vì vậy một `--json` stdout capture vẫn sạch để pipe vào `jq` ngay cả khi một dòng trạng thái được hiển thị. Không có `--json` bạn nhận được một boxed, colorised view cho con mắt con người. +- **Khám phá với `--help`.** Mỗi lệnh và subcommand có `--help` (và alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. Giúp đỡ top-level cũng liệt kê các exit codes và global options. Không có global machine-readable surface dump; sử dụng per-command `--help`, cộng với domain-specific `agenteye query schema` và `agenteye settings schema` cho hai registries đó. +- **Confirmations auto-skip cho scripts và agents.** Create/update/delete commands prompt "are you sure?" trong một interactive terminal, nhưng **auto-skip prompt đó dưới `--json` hoặc bất cứ khi nào stdin không phải là TTY** (TTY là một interactive terminal session; pipe hoặc CI runner không phải), vì vậy scripts và agents không bao giờ hang. Chuyển `--yes`/`-y` để bỏ qua nó rõ ràng. Vì prompt sẽ không kích hoạt cho một agent, một agent nên xác nhận các hành động tàn phá với human trước. +- **Pagination:** kết quả là newest-first và cursor-paginated (mỗi trang trả về một token bạn sử dụng để lấy tiếp theo). `--limit N` (alias `-n`) cấp dòng và **mặc định là 50**; `--all` auto-paginates (trong 200-row chunks) **lên đến `--limit`**, vì vậy một `--all` trần vẫn dừng lại ở 50. Cho một full sweep chuyển một cap cao rõ ràng: `--all --limit 1000`. `--page-size N` kiểm soát per-request chunk (max 200); `--cursor ` tiếp tục từ prior page's `next_cursor`. +- **Time filters:** `--since` có một cửa sổ tương đối: `15m`, `1h`, `6h`, `24h`, `7d`, hoặc `all` (các presets của dashboard). Cho một phạm vi dài hơn hoặc tùy chỉnh (ví dụ 30 ngày gần đây), sử dụng `--from`/`--to`: rõ ràng ISO-8601 UTC timestamps **với `T` và timezone** (ví dụ `2026-06-01T00:00:00Z`) ghi đè `--since`. Một giá trị không có khoảng cách hoặc không có timezone là một lỗi sử dụng. - **`--fields a,b,c`** (trên `events`, `sessions`, `evals`, `errors`) hạn chế đầu ra cho những khóa đó, cho cả bảng và `--json`. Các tên không xác định bị từ chối với danh sách hợp lệ, một cách rẻ để khám phá tên trường. -- **`--file payload.json`** (hoặc `--file -` để đọc stdin) cung cấp toàn bộ phần thân yêu cầu JSON nơi tài nguyên có hình dạng phức tạp (trên `alerts create/update`, `settings set` và `users create/update`). SQL truy vấn đã lưu sử dụng `--sql @file.sql` thay thế. -- **Bộ lọc đa giá trị** được phân tách bằng dấu phẩy → so khớp như một tập hợp (liên hiệp trong một bộ lọc, AND trên các bộ lọc): `--event-type tool_use,tool_result`. Các tùy chọn nhấp không phải là variadic, vì vậy `--add a b` phá vỡ. Sử dụng `--add a,b`, lặp lại cờ (`--add a --add b`) hoặc trích dẫn (`--add "a b"`). +- **`--file payload.json`** (hoặc `--file -` để đọc stdin) cung cấp một full JSON request body nơi một resource có một hình dạng phức tạp (trên `alerts create/update`, `settings set`, và `users create/update`). Saved-query SQL sử dụng `--sql @file.sql` thay thế. +- **Multi-value filters** được comma-separated → matched as a set (union within one filter, AND across filters): `--event-type tool_use,tool_result`. Click options không phải là variadic, vì vậy `--add a b` breaks. Sử dụng `--add a,b`, lặp lại flag (`--add a --add b`), hoặc quote (`--add "a b"`). --- -## Tài liệu tham khảo lệnh +## Command reference -### 5 lệnh bạn sẽ sử dụng nhất +### You'll use these 5 commands most -Phần lớn công việc hàng ngày chạy qua một số ít lệnh đọc. Bắt đầu ở đây, sau đó hãy sử dụng bề mặt đầy đủ dưới đây khi bạn cần: +Hầu hết công việc hàng ngày chạy qua một số lệnh đọc. Bắt đầu ở đây, rồi tiếp cận toàn bộ bề mặt dưới đây khi bạn cần nó: -| Lệnh | Nó làm gì | Thử nó | +| Command | What it does | Try it | |---|---|---| -| `sessions` | Một hàng cho mỗi lần chạy tác nhân: thời gian, env, tác nhân, trạng thái, điểm số mới nhất. | `agenteye --json sessions --since 24h --status error` | -| `events` | Dấu vết thô từng bước bên trong lần chạy (thêm `--full` cho tải trọng). | `agenteye --json events --session-id run-001 --all` | -| `evals` | Kết quả đánh giá và điểm số; `--aggregate` cuộn chúng lên. | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | Chỉ các sự kiện bị lỗi; `--aggregate` cho số lượng theo loại. | `agenteye --json errors --since 24h --aggregate` | -| `list` | Khám phá các giá trị bộ lọc hợp lệ (tác nhân, envs, mô hình, ...). | `agenteye list agents` | +| `sessions` | One row per agent run: time, env, agent, status, latest score. | `agenteye --json sessions --since 24h --status error` | +| `events` | The raw per-step trail inside a run (add `--full` for payloads). | `agenteye --json events --session-id run-001 --all` | +| `evals` | Evaluation results and scores; `--aggregate` rolls them up. | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | Just the errored events; `--aggregate` for counts by type. | `agenteye --json errors --since 24h --aggregate` | +| `list` | Discover the valid filter values (agents, envs, models, …). | `agenteye list agents` | -### Tất cả những gì CLI có thể làm +### Everything the CLI can do -Bề mặt đầy đủ theo sau. CLI có **18 lệnh cấp cao nhất**. Tất cả các lệnh đọc chấp nhận `--json` và các tùy chọn toàn cầu ở trên; chạy `agenteye -h` (hoặc ` -h`) cho danh sách cờ kiệt sức và hình dạng JSON của bất kỳ cái nào. +Toàn bộ bề mặt theo sau. CLI có **18 top-level commands**. Tất cả read commands chấp nhận `--json` và global options ở trên; chạy `agenteye -h` (hoặc ` -h`) cho danh sách flag exhaustive và JSON shape của bất kỳ cái nào. -### Nhận dạng: `login` · `logout` · `whoami` · `orgs` · `version` · `help` +### Identity: `login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash agenteye login --email you@example.com [--org acme] # emailed one-time code; saves the session @@ -197,7 +197,7 @@ agenteye version # print the CLI version (s agenteye help # top-level help (same as --help) ``` -`orgs` kiểm tra và chuyển người thuê hoạt động: +`orgs` kiểm tra và chuyển active tenant: ```bash agenteye orgs list # your orgs + your role in each (active one marked) @@ -206,9 +206,9 @@ agenteye orgs current # identity card for the active org agenteye orgs perms # your permissions in the active org, grouped by resource ``` -### Quan sát (chỉ đọc): `events` · `sessions` · `evals` · `errors` · `list` +### Observe (read-only): `events` · `sessions` · `evals` · `errors` · `list` -Không ai trong số này cần xác nhận. Bộ lọc được chia sẻ: `--session-id`, `--agent-id`, `--env` (**không phải** `--environment`) và phạm vi thời gian (`--since` / `--from` / `--to`). +Không ai trong số này cần một confirmation. Shared filters: `--session-id`, `--agent-id`, `--env` (**không** `--environment`), và time range (`--since` / `--from` / `--to`). ```bash # events (alias: the raw per-step trail), newest first @@ -231,16 +231,16 @@ agenteye --json errors --since 24h --error-type timeout --all --limit 1000 agenteye list envs # also: agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX` (trên **`evals`**, không phải `sessions`) có thể lặp lại và kết hợp AND; bất kỳ ràng buộc nào cũng là tùy chọn (`..0.5` có nghĩa là ≤ 0,5, `0.9..` có nghĩa là ≥ 0,9). Tối đa 20 bộ lọc điểm số cho mỗi yêu cầu. `evals --scores-full` là cờ hiển thị cho **bảng con người chỉ**; nó cho thấy mọi cặp điểm số thay vì một vài cái đầu tiên cộng với số lượng `+N`. Nó không có hiệu lực dưới `--json`, luôn trả về đối tượng điểm số hoàn chỉnh. Để đọc **một phiên từ đầu đến cuối**, kết hợp dấu vết sự kiện với đánh giá của nó: +`--score KEY:MIN..MAX` (trên **`evals`**, không `sessions`) có thể lặp lại và AND-combined; bất kỳ bound nào là tùy chọn (`..0.5` có nghĩa là ≤ 0.5, `0.9..` có nghĩa là ≥ 0.9). Lên đến 20 score filters trên mỗi request. `evals --scores-full` là một display flag cho **human table only**; nó hiển thị mỗi cặp điểm thay vì vài cái đầu tiên cộng với một `+N` count. Nó không có hiệu lực dưới `--json`, luôn trả về complete score object. Để đọc **một session end-to-end**, kết hợp event trail với evaluation của nó: ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' agenteye --json evals --session-id run-001 # its scores + status ``` -### Quản lý (được bảo vệ bằng quyền): `keys` · `users` · `settings` · `alerts` · `incidents` +### Manage (permission-gated): `keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**: khóa API. Bí mật được tạo cục bộ, gửi đến máy chủ (chỉ lưu trữ một hàm băm), và **hiển thị một lần** trên tạo/tạo lại; nắm bắt nó sau đó. Với `--json` nó chỉ xuất hiện trong trường `key`. Được tham chiếu bằng **tên**. +**`keys`**: API keys. Secret được tạo cục bộ, được gửi đến server (chỉ lưu trữ một hash), và **hiển thị một lần** trên create/regenerate; capture nó khi đó. Với `--json` nó xuất hiện chỉ trong trường `key`. Được tham chiếu bằng **name**. ```bash agenteye keys list # active keys first, then revoked @@ -252,9 +252,9 @@ agenteye keys regenerate ci-bot --yes # rotate the secret (the ol agenteye keys disable ci-bot --yes # revoke ``` -Quyền hoạt động như `(permission-set ∪ --add) − --remove`. Mã thông báo là `slug:action` (ví dụ: `events:read`) hoặc `slug:action.action` để mở rộng nhiều cái trên một tài nguyên (`events:read.add` → `events:read`, `events:add`). Cài đặt: `read-only`, `standard`, `admin`. Quyền chỉ dành cho con người (`keys:update`) không thể được cấp cho một khóa. +Permissions hoạt động như `(permission-set ∪ --add) − --remove`. Tokens là `slug:action` (ví dụ `events:read`) hoặc `slug:action.action` để mở rộng một số trên một resource (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. Human-only permissions (`keys:update`) không thể được cấp cho một key. -**`users`**: thành viên tổ chức, được tham chiếu bằng **email** (id UUID cũng được chấp nhận). +**`users`**: org members, được tham chiếu bằng **email** (một UUID id cũng được chấp nhận). ```bash agenteye users list [--active-only] @@ -265,7 +265,7 @@ agenteye users disable dev@corp.com --yes # has protected/self guards agenteye users enable dev@corp.com ``` -**`settings`**: một sổ đăng ký cố định (bạn đọc và thay đổi các khóa hiện có; bạn không thể tạo ra những khóa mới). +**`settings`**: một fixed registry (bạn đọc và thay đổi các khóa hiện có; bạn không thể tạo cái mới). ```bash agenteye settings list # key · value · type · updated (secrets masked) @@ -273,7 +273,7 @@ agenteye settings schema # what each key accepts (ty agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**: định nghĩa cảnh báo, được tham chiếu bằng **tên**. `create` lấy tên vị trí cộng với cờ hoặc toàn bộ phần thân JSON qua `--file`. +**`alerts`**: alert definitions, được tham chiếu bằng **name**. `create` có một NAME vị trí cộng với flags hoặc một full JSON body qua `--file`. ```bash agenteye alerts list @@ -284,7 +284,7 @@ agenteye alerts test high-errors --yes # fire a test noti agenteye alerts delete high-errors --yes ``` -**`incidents`**: các sự cố cảnh báo, được tham chiếu bởi id (các id ngắn được chấp nhận). `show` in nhật ký hoạt động đầy đủ; đọc nó trước khi hành động. +**`incidents`**: alert incidents, được tham chiếu bằng id (short ids chấp nhận). `show` in full activity log; đọc nó trước khi hành động. ```bash agenteye incidents list --state firing # also: acknowledged, resolved @@ -299,9 +299,9 @@ agenteye incidents comment-list ; agenteye incidents comment-delete ; agenteye incidents unsubscribe ; agenteye incidents subscribers ``` -### Phân tích & trợ lý: `query` · `agent` +### Analytics & assistant: `query` · `agent` -**`query`**: SQL đã lưu lên kho lưu trữ phân tích của bạn cộng với trình chạy ad-hoc. Truy vấn đã lưu được tham chiếu bằng **tên**; SQL được xác thực phía máy chủ (SELECT/WITH chỉ, hết thời gian tuyên bố, giới hạn hàng). +**`query`**: saved SQL chống lại analytics store của bạn cộng với một ad-hoc runner. Saved queries được tham chiếu bằng **name**; SQL được xác thực server-side (SELECT/WITH only, statement timeout, row cap). ```bash agenteye query schema [TABLE] # column layout of the analytics views @@ -312,7 +312,7 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**: nói chuyện với **trợ lý AI** tích hợp (cùng một nhà phân tích chỉ đọc mà bạn có thể trò chuyện trong bảng điều khiển). Trò chuyện được tham chiếu bằng id trò chuyện ngắn (phân giải tiền tố). +**`agent`**: nói chuyện với **AI assistant** được xây dựng (cùng read-only analyst bạn có thể trò chuyện với trong dashboard). Chats được tham chiếu bằng một short chat-id (prefix-resolved). ```bash agenteye agent health # is the AI assistant configured/reachable @@ -325,25 +325,25 @@ agenteye agent rename --title "error triage" ; agenteye agent delete --- -## Mã thoát +## Exit codes -| Mã | Ý nghĩa | +| Code | Meaning | |---|---| -| 0 | Thành công | -| 1 | Lỗi không mong muốn (ví dụ: bảng điều khiển trả về 5xx) | -| 2 | Lỗi sử dụng (đối số không hợp lệ, lệnh/cờ không xác định, va chạm tên) | -| 3 | Không thể truy cập bảng điều khiển | -| 4 | Chưa đăng nhập hoặc phiên hết hạn; chạy `agenteye login` | -| 5 | Được xác thực, nhưng tài khoản của bạn thiếu quyền cần thiết (thông báo đặt tên nó) | -| 6 | Tài nguyên được yêu cầu không được tìm thấy (ví dụ: id phiên hoặc sự cố không xác định) | +| 0 | Success | +| 1 | Unexpected error (e.g. the dashboard returned a 5xx) | +| 2 | Usage error (invalid arguments, unknown command/flag, name collision) | +| 3 | Cannot reach the dashboard | +| 4 | Not logged in or session expired; run `agenteye login` | +| 5 | Authenticated, but your account lacks the required permission (the message names it) | +| 6 | The requested resource was not found (e.g. unknown session or incident id) | -Những điều này làm cho CLI an toàn để viết kịch bản: một tác nhân mã hóa có thể nhánh trên `4` để nhắc bạn xác thực lại, hoặc `5` để bề mặt quyền bị thiếu. Xem [Công thức CLI cho tác nhân](/vi/agenteye/cli-recipes) cho mẫu xử lý mã thoát và hình dạng đầu ra JSON. +Những cái này làm cho CLI an toàn để script: một coding agent có thể branch trên một `4` để nhắc bạn xác thực lại, hoặc một `5` để bề mặt permission bị thiếu. Xem [CLI recipes for agents](/vi/agenteye/cli-recipes) cho exit-code-handling patterns và JSON output shapes. --- -## Bước tiếp theo +## Next steps -- **[Công thức CLI cho tác nhân](/vi/agenteye/cli-recipes)**: sao chép - dán mẫu truy vấn, `jq` một-dòng, `--fields` hình chiếu, xử lý mã thoát và hình dạng đầu ra JSON, được viết cho các tác nhân mã hóa điều khiển CLI. -- **[Kỹ năng tác nhân CLI](/vi/agenteye/cli-skill)**: gói CLI này dưới dạng kỹ năng Claude Code / Codex **installable** để tác nhân mã hóa điều khiển Failproof AI Observability từ các yêu cầu bằng tiếng Anh đơn giản. -- **[Khóa API](/vi/agenteye/api-keys)**: mô hình quyền phía sau `keys create --add …`. -- **[Trợ lý AI](/vi/agenteye/assistant)**: kích hoạt trợ lý mà `agent ask` nói chuyện. \ No newline at end of file +- **[CLI recipes for agents](/vi/agenteye/cli-recipes)**: copy-paste query patterns, `jq` one-liners, `--fields` projections, exit-code handling, và JSON output shapes, được viết cho coding agents điều khiển CLI. +- **[CLI agent skill](/vi/agenteye/cli-skill)**: package CLI này như một installable Claude Code / Codex *skill* để một coding agent điều khiển Failproof AI Observability từ plain-English requests. +- **[API keys](/vi/agenteye/api-keys)**: permission model đằng sau `keys create --add …`. +- **[AI assistant](/vi/agenteye/assistant)**: kích hoạt assistant mà `agent ask` nói chuyện với. \ No newline at end of file diff --git a/docs/vi/agenteye/codex-capture.mdx b/docs/vi/agenteye/codex-capture.mdx index ba7f1f4d..39f17574 100644 --- a/docs/vi/agenteye/codex-capture.mdx +++ b/docs/vi/agenteye/codex-capture.mdx @@ -1,55 +1,55 @@ --- title: "Ghi lại phiên Codex" -description: "Theo dõi các phiên Codex OpenAI cục bộ của đội ngũ bạn vào AgentEye dưới dạng các phiên và sự kiện thông thường — mà không cần thay đổi cách họ chạy Codex." +description: "Theo dõi các phiên Codex OpenAI trên máy của nhóm bạn vào AgentEye dưới dạng các phiên và sự kiện thông thường — mà không cần thay đổi cách họ sử dụng Codex." --- -Các kỹ sư của bạn đã chạy OpenAI Codex mỗi ngày. Ghi lại phiên Codex đưa những phiên coding đó vào AgentEye dưới dạng các phiên và sự kiện thông thường, để bạn có thể tìm kiếm, phát lại và đánh giá chúng cùng với tất cả những gì khác bạn quan sát. Nó bổ sung cho [Python SDK](/vi/agenteye/python-sdk): SDK này cấy cứu các agent bạn viết, trong khi đây ghi lại công việc Codex mà đội ngũ bạn đã làm — mà không cần thay đổi cách họ chạy nó. +Các kỹ sư của bạn đã sử dụng OpenAI Codex hàng ngày. Ghi lại phiên Codex đưa những phiên làm việc về mã hóa đó vào AgentEye dưới dạng các phiên và sự kiện thông thường, để bạn có thể tìm kiếm, phát lại và đánh giá chúng cùng với mọi thứ khác mà bạn quan sát. Nó bổ sung cho [Python SDK](/vi/agenteye/python-sdk): SDK cấp độ dụng cụ cho các agent mà bạn viết, trong khi tính năng này ghi lại công việc Codex mà nhóm của bạn đã làm — mà không cần thay đổi cách họ sử dụng nó. -Một bộ sưu tập nền nhỏ đọc các bản ghi phiên Codex cục bộ khi chúng được viết và gửi chúng đến AgentEye. Một bộ sưu tập trên mỗi máy ghi lại mọi bề mặt Codex cục bộ cùng một lúc — không cần thiết lập cho từng bề mặt. +Một trình thu thập nền nhỏ đọc các bản ghi phiên Codex trên máy cục bộ khi chúng được ghi và gửi chúng đến AgentEye. Một trình thu thập trên mỗi máy ghi lại mọi bề mặt Codex cục bộ cùng một lúc — không cần thiết lập riêng từng bề mặt. -Bộ sưu tập tương tự cũng ghi lại các agent khác — xem [OpenClaw](/vi/agenteye/openclaw-capture) và [Hermes](/vi/agenteye/hermes-capture). Kích hoạt từng cái bạn chạy; một bộ sưu tập có thể ghi lại nhiều cái cùng một lúc. +Trình thu thập tương tự cũng ghi lại các agent khác — xem [OpenClaw](/vi/agenteye/openclaw-capture) và [Hermes](/vi/agenteye/hermes-capture). Bật mỗi cái mà bạn chạy; một trình thu thập duy nhất có thể ghi lại nhiều cái cùng một lúc. --- -## Nó ghi lại những gì +## Nó ghi lại cái gì -Mọi bề mặt Codex chạy **cục bộ** đều tạo ra các bản ghi phiên trên đĩa giống nhau, và bộ sưu tập chọn tất cả chúng: +Mỗi bề mặt Codex chạy **trên máy cục bộ** tạo ra những bản ghi phiên on-disk giống nhau, và trình thu thập chọn tất cả chúng: - **CLI** Codex và `codex exec` -- phần **mở rộng VS Code / IDE** -- **ứng dụng desktop**, khi nó chạy một phiên cục bộ +- **Tiện ích mở rộng VS Code / IDE** +- **Ứng dụng desktop**, khi nó chạy một phiên trên máy cục bộ -Mỗi phiên Codex trở thành một [phiên](/vi/agenteye/sessions) AgentEye; các tin nhắn của người dùng và trợ lý, lý luận, lệnh gọi công cụ, kết quả công cụ và mức sử dụng token của nó trở thành các [sự kiện](/vi/agenteye/event-stream) phù hợp. Bề mặt mà mỗi phiên đến từ (CLI, IDE hoặc desktop) được ghi lại, để bạn có thể phân biệt chúng. +Mỗi phiên Codex trở thành một [phiên](/vi/agenteye/sessions) AgentEye; tin nhắn của người dùng và trợ lý, lý luận, các lệnh gọi công cụ, kết quả công cụ và mức sử dụng token của nó trở thành các [sự kiện](/vi/agenteye/event-stream) phù hợp. Bề mặt mà mỗi phiên đến từ (CLI, IDE hoặc desktop) được ghi lại, để bạn có thể phân biệt chúng. -> **Các phiên trên đám mây không được ghi lại.** Ứng dụng desktop ngày càng chạy các phiên trong đám mây Codex và chỉ giữ lại siêu dữ liệu của chúng trên máy — không có bản ghi cục bộ nào để đọc. Chỉ các phiên thực thi cục bộ mới được ghi lại. +> **Các phiên đám mây không được ghi lại.** Ứng dụng desktop ngày càng chạy các phiên trong đám mây Codex và chỉ giữ siêu dữ liệu của chúng trên máy — không có bản ghi cục bộ để đọc. Chỉ các phiên được thực thi cục bộ mới được ghi lại. --- ## Bật nó lên -Ghi lại bị tắt cho đến khi bạn bật nó. Cài đặt bộ sưu tập với một khóa API có quyền `events:add` (xem [API keys](/vi/agenteye/api-keys)) và bật ghi lại Codex: +Ghi lại bị tắt cho đến khi bạn bật nó. Cài đặt trình thu thập với khóa API có quyền `events:add` (xem [Khóa API](/vi/agenteye/api-keys)) và bật ghi lại Codex: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -Điều đó cài đặt bộ sưu tập, đăng ký nó như một dịch vụ nền và bắt đầu ghi lại. Xác nhận rằng nó đang chạy: +Điều đó cài đặt trình thu thập, đăng ký nó dưới dạng dịch vụ nền và bắt đầu ghi lại. Xác nhận rằng nó đang chạy: ```bash agenteye-collector health ``` -Lần chạy đầu tiên, các phiên Codex hiện có của bạn sẽ được điền lại một lần và hoạt động mới sau đó sẽ truyền phát trong vài giây. Các tệp của chính Codex chỉ được đọc — không bao giờ được sửa đổi, di chuyển hoặc xóa — và mỗi phiên được gửi chính xác một lần, ngay cả trong các lần khởi động lại. +Lần chạy đầu tiên, các phiên Codex hiện có của bạn được lấp đầy một lần và hoạt động mới sau đó phát trực tuyến trong vài giây. Các tệp của Codex chỉ bao giờ được đọc — không bao giờ bị sửa đổi, di chuyển hoặc xóa — và mỗi phiên được gửi đúng một lần, thậm chí trên các lần khởi động lại. --- ## Nó xuất hiện ở đâu -Các phiên được ghi lại xuất hiện trong **Sessions** và các sự kiện của chúng trong luồng **Events**, giống như bất kỳ agent nào khác bạn quan sát — vì vậy [phát lại phiên](/vi/agenteye/sessions), [tìm kiếm](/vi/agenteye/queries), [đánh giá](/vi/agenteye/evaluations) và [cảnh báo](/vi/agenteye/alerts) đều hoạt động trên chúng. Lọc theo agent Codex để xem chúng riêng biệt. +Các phiên được ghi lại xuất hiện trong **Sessions** và các sự kiện của chúng trong luồng **Events**, giống như bất kỳ agent nào khác mà bạn quan sát — vì vậy [phát lại phiên](/vi/agenteye/sessions), [tìm kiếm](/vi/agenteye/queries), [đánh giá](/vi/agenteye/evaluations) và [cảnh báo](/vi/agenteye/alerts) đều hoạt động trên chúng. Lọc theo agent Codex để xem chúng riêng lẻ. --- ## Quyền riêng tư -Các bản ghi phiên Codex chứa toàn bộ phiên — bao gồm đầu ra lệnh, nội dung tệp và bất cứ điều gì Codex đọc hoặc viết — và có thể chứa các bí mật. Các phiên được ghi lại được gửi nguyên trạng, vì vậy chỉ bật ghi lại trên các máy và cho các đội nơi tập trung nội dung đó trong AgentEye là thích hợp, và cung cấp cho bộ sưu tập một khóa được giới hạn trong `events:add` chỉ. Xem [Security](/vi/agenteye/security) để biết cách dữ liệu của bạn được giữ cách ly. \ No newline at end of file +Bản ghi Codex chứa toàn bộ phiên — bao gồm kết quả lệnh, nội dung tệp và bất cứ thứ gì Codex đã đọc hoặc ghi — và có thể chứa bí mật. Các phiên được ghi lại được gửi nguyên trạng, vì vậy chỉ bật ghi lại trên các máy và cho các nhóm trong đó tập trung nội dung đó trong AgentEye là phù hợp, và cấp cho trình thu thập một khóa được giới hạn ở `events:add` duy nhất. Xem [Bảo mật](/vi/agenteye/security) để biết cách dữ liệu của bạn được giữ cách biệt. \ No newline at end of file diff --git a/docs/vi/agenteye/concepts.mdx b/docs/vi/agenteye/concepts.mdx index c7d6440f..ccb1d23a 100644 --- a/docs/vi/agenteye/concepts.mdx +++ b/docs/vi/agenteye/concepts.mdx @@ -1,88 +1,87 @@ --- ---- title: "Khái niệm" -description: "Từ vựng đằng sau Failproof AI Observability — sự kiện, phiên làm việc, đánh giá, kiểm toán, phát hiện và sự cố — được định nghĩa tại một nơi." +description: "Từ vựng của Failproof AI Observability — events, sessions, evaluations, audits, findings, và incidents — được định nghĩa tại một nơi." --- -Trang này định nghĩa từ vựng mà Failproof AI Observability sử dụng. Nếu một thuật ngữ trong hướng dẫn khác không quen thuộc, nó được định nghĩa ở đây. Bạn không cần phải đọc nó từ đầu đến cuối: hãy lướt qua, hoặc quay lại khi bạn muốn làm rõ một từ. +Trang này định nghĩa từ vựng mà Failproof AI Observability sử dụng. Nếu một thuật ngữ trong các hướng dẫn khác không quen thuộc, nó được định nghĩa ở đây. Bạn không cần phải đọc nó từ đầu đến cuối: hãy lướt qua hoặc quay lại khi bạn gặp một từ bạn muốn làm rõ. --- ## Mô hình dữ liệu -**Event (Sự kiện)** -Đơn vị dữ liệu nhỏ nhất. Một sự kiện ghi lại một bước duy nhất mà agent của bạn thực hiện: một `tool_use`, một `model_request`, một `hook_completed`, một `error`, v.v. Agent của bạn phát ra các sự kiện thông qua [Python SDK](/vi/agenteye/python-sdk); chúng xuất hiện trực tiếp trên trang **Events**. +**Event** +Đơn vị dữ liệu nhỏ nhất. Một event ghi lại một bước đơn lẻ mà agent của bạn thực hiện: một `tool_use`, một `model_request`, một `hook_completed`, một `error`, v.v. Agent của bạn phát ra các event thông qua [Python SDK](/vi/agenteye/python-sdk); chúng xuất hiện trực tiếp trên trang **Events**. -**Session (Phiên làm việc)** -Một lần chạy agent, được xác định bằng `session_id`. Một phiên là tất cả các sự kiện chia sẻ id đó, được tổng hợp thành một hàng trên trang **Sessions** và được vẽ dưới dạng biểu đồ thực thi trên trang chi tiết của nó. Một phiên thường bắt đầu bằng `agent_start` và kết thúc bằng `agent_end`. +**Session** +Một lần chạy agent, được xác định bằng `session_id`. Một session là tất cả các event chia sẻ id đó, được tập hợp thành một hàng trên trang **Sessions** và được vẽ dưới dạng biểu đồ thực thi trên trang chi tiết của nó. Một session thường bắt đầu bằng `agent_start` và kết thúc bằng `agent_end`. **Agent** -Một diễn viên được đặt tên bên trong một lần chạy, được xác định bằng `agent_id`. Một lần chạy có thể liên quan đến nhiều agent: ví dụ, một bộ lập kế hoạch sinh ra một sub-agent tóm tắt. Các sub-agent mang theo `parent_id`, đây là cách cho phép Failproof AI Observability vẽ chúng trên các làn riêng của chúng trong biểu đồ thực thi. +Một diễn viên có tên trong một lần chạy, được xác định bằng `agent_id`. Một lần chạy có thể liên quan đến nhiều agent: ví dụ như một bộ lập kế hoạch sinh ra một sub-agent tóm tắt. Các sub-agent mang theo `parent_id`, đây là cách Failproof AI Observability vẽ chúng trên các làn riêng biệt trong biểu đồ thực thi. -**Environment (Môi trường)** -Một nhãn cho nơi lần chạy xảy ra: `production`, `staging`, `dev`. Bạn đặt nó một lần khi cấu hình SDK. Hầu hết mọi trang bảng điều khiển đều có thể lọc theo môi trường. +**Environment** +Một nhãn cho nơi lần chạy diễn ra: `production`, `staging`, `dev`. Bạn đặt nó một lần khi cấu hình SDK. Hầu như mọi trang bảng điều khiển đều có thể lọc theo environment. -**Context-window fill (Mức độ lấp đầy cửa sổ ngữ cảnh)** -Phần trăm cửa sổ ngữ cảnh của model mà một phản hồi tiêu thụ. Failproof AI Observability dấu nó trên các sự kiện `model_response` cho các model mà nó nhận dạng, để quá trình tăng trưởng prompt và việc nén sắp xảy ra là rõ ràng ngay trong luồng sự kiện. +**Context-window fill** +Tỷ lệ phần trăm của cửa sổ ngữ cảnh của mô hình mà một phản hồi tiêu thụ. Failproof AI Observability đóng dấu nó trên các event `model_response` cho các mô hình mà nó nhận dạng, vì vậy sự phát triển của prompt và sự nén sắp tới có thể nhìn thấy ngay trong luồng event. --- ## Chất lượng -**Evaluation (Đánh giá)** -Điểm chất lượng cho một phiên hoàn thành, được tạo bởi dịch vụ chấm điểm bạn chạy. Đánh giá là tùy chọn: cho đến khi bạn kết nối một bộ đánh giá, các phiên được ghi lại nhưng không được chấm điểm. Mỗi đánh giá có thể mang theo nhiều điểm có tên (ví dụ `helpfulness`, `factuality`, `tool_efficiency`), mỗi điểm có ghi chú lý do ngắn. Xem [Evaluation suite](/vi/agenteye/evaluation-suite). +**Evaluation** +Điểm chất lượng cho một session đã hoàn thành, do dịch vụ chấm điểm bạn chạy tạo ra. Evaluations là tùy chọn: cho đến khi bạn kết nối một evaluator, các session được ghi lại nhưng không được chấm điểm. Mỗi evaluation có thể mang theo nhiều điểm được đặt tên (ví dụ `helpfulness`, `factuality`, `tool_efficiency`), mỗi điểm có kèm theo một ghi chú lý do ngắn gọn. Xem [Evaluation suite](/vi/agenteye/evaluation-suite). -**Score key (Khóa điểm)** -Tên của một chiều mà bộ đánh giá báo cáo, chẳng hạn như `helpfulness`. Cảnh báo và kiểm toán có thể theo dõi một khóa điểm cụ thể theo thời gian. +**Score key** +Tên của một chiều mà một evaluator báo cáo, chẳng hạn như `helpfulness`. Các cảnh báo và kiểm toán có thể theo dõi một score key cụ thể theo thời gian. -**Evaluator (Bộ đánh giá)** -Dịch vụ chấm điểm của bạn. Failproof AI Observability POST phần giới thiệu của một lần chạy hoàn thành cho nó và lưu trữ các điểm nó trả về. Nó không cung cấp bộ đánh giá mặc định; logic chấm điểm là của bạn. +**Evaluator** +Dịch vụ chấm điểm của bạn. Failproof AI Observability POST bảng điểm của một lần chạy đã hoàn thành đến nó và lưu trữ các điểm mà nó trả về. Nó không cung cấp một evaluator mặc định; logic chấm điểm là của bạn. --- -## Tìm kiếm và sửa chữa các lỗi +## Tìm và sửa các lỗi -**Hook (Móc)** -Một guardrail hoặc side-effect mà framework agent của bạn chạy xung quanh một bước: một kiểm tra an toàn nội dung, PII redaction, một bảo vệ ngân sách. Hooks phát ra các sự kiện `hook_triggered` / `hook_completed` với một `outcome` (allow, deny, modify), và có trang observe riêng của chúng. +**Hook** +Một guardrail hoặc side-effect mà framework agent của bạn chạy xung quanh một bước: một kiểm tra an toàn nội dung, redaction PII, một bảo vệ ngân sách. Hooks phát ra các event `hook_triggered` / `hook_completed` với một `outcome` (allow, deny, modify), và có trang observe riêng của chúng. -**Alert rule (Quy tắc cảnh báo)** -Một quy tắc kích hoạt khi một số liệu vượt qua ngưỡng bạn đặt: tỷ lệ lỗi, độ trễ p95, chi phí token, hoặc điểm bộ đánh giá. Khi một quy tắc kích hoạt, nó mở một sự cố và thông báo cho các kênh bạn chọn (email, Slack, webhook, trong bảng điều khiển). Xem [Alerts](/vi/agenteye/alerts). +**Alert rule** +Một quy tắc kích hoạt khi một số liệu vượt quá ngưỡng bạn đặt: error rate, latency p95, chi phí token, hoặc một điểm evaluator. Khi một quy tắc kích hoạt, nó mở một incident và thông báo cho các kênh bạn chọn (email, Slack, webhook, trong-dashboard). Xem [Alerts](/vi/agenteye/alerts). -**Incident (Sự cố)** -Một vấn đề mở được tạo khi một quy tắc cảnh báo kích hoạt. Các sự cố có vòng đời (acknowledge, assign, resolve) và dòng thời gian hoạt động ghi lại mọi hành động. Bạn cũng có thể mở nó thủ công. +**Incident** +Một vấn đề mở được tạo khi một alert rule kích hoạt. Các incident có vòng đời (acknowledge, assign, resolve) và một timeline hoạt động ghi lại mọi hành động. Bạn cũng có thể mở một thủ công. -**Audit (Kiểm toán)** -Một cuộc điều tra định kỳ (hàng giờ đến hàng tuần) khai thác nhật ký của bạn *trên* các phiên để tìm các mẫu lỗi bạn chưa viết quy tắc: các cụm lỗi, điểm thấp, các ngoại lệ độ trễ, vòng lặp tool-call, và các lần chạy không bao giờ kết thúc. Trong khi cảnh báo theo dõi một số liệu bạn đã biết, kiểm toán cho bạn biết tiếp theo nên nhìn vào đâu. Xem [Audits](/vi/agenteye/audits). +**Audit** +Một cuộc điều tra định kỳ (hàng giờ đến hàng tuần) khai thác nhật ký của bạn *trên* các session để tìm kiếm các mẫu lỗi mà bạn chưa viết quy tắc: các cụm lỗi, điểm thấp, outlier latency, tool-call loops, và các lần chạy không bao giờ hoàn thành. Trong khi một alert theo dõi một số liệu bạn đã biết, một audit cho bạn biết tiếp theo phải nhìn vào cái gì. Xem [Audits](/vi/agenteye/audits). -**Finding (Phát hiện)** -Một kết quả được xếp hạng, được hỗ trợ bằng bằng chứng từ một lần chạy kiểm toán. Một phát hiện đặt tên cho một mẫu, liên kết đến các phiên chính xác phía sau nó, và mang theo vòng đời phân loại (acknowledge, resolve, mute, dismiss). Failproof AI Observability loại bỏ trùng lặp các phát hiện từ lần chạy này sang lần chạy khác để một mẫu đã biết cập nhật thay vì tích tụ. +**Finding** +Một kết quả được xếp hạng và được hỗ trợ bằng bằng chứng từ một lần chạy audit. Một finding đặt tên cho một mẫu, liên kết đến các session chính xác đằng sau nó, và mang theo một vòng đời triage (acknowledge, resolve, mute, dismiss). Failproof AI Observability khử trùng các finding từ lần chạy này sang lần chạy tiếp theo sao cho một mẫu đã biết cập nhật thay vì chồng chất. -**The AI assistant (Trợ lý AI)** -Trò chuyện trong bảng điều khiển trả lời các câu hỏi về agent của bạn bằng tiếng Anh đơn giản, trên dữ liệu của riêng bạn. Nó chỉ đọc theo mặc định; bất cứ thứ gì nó tạo (một truy vấn đã lưu, một bảng điều khiển) đều được phê duyệt cổng, và nó không bao giờ có thể xóa. Xem [AI assistant](/vi/agenteye/assistant). +**The AI assistant** +Chat trong-dashboard trả lời các câu hỏi về agent của bạn bằng tiếng Anh đơn giản, trên dữ liệu của riêng bạn. Theo mặc định nó ở chế độ chỉ đọc; bất cứ điều gì nó tạo (một truy vấn đã lưu, một bảng điều khiển) đều bị chặn phê duyệt, và nó không bao giờ có thể xóa. Xem [AI assistant](/vi/agenteye/assistant). --- ## Chạy nó -**Organization (tenant) (Tổ chức - người thuê)** -Một không gian làm việc được cô lập. Một phiên bản Failproof AI Observability có thể lưu trữ nhiều tổ chức, mỗi tổ chức có người dùng, khóa và dữ liệu riêng. Mọi URL bảng điều khiển được phạm vi dưới dấu hiệu tổ chức của bạn (`//…`). +**Organization (tenant)** +Một không gian làm việc bị cô lập. Một instance Failproof AI Observability có thể lưu trữ nhiều organizations, mỗi cái có những người dùng, khóa và dữ liệu riêng của mình. Mỗi URL bảng điều khiển được phạm vi dưới slug org của bạn (`//…`). -**Collector (Bộ sưu tập)** -`agenteye-collector`, daemon nhẹ chạy trên mỗi máy agent, phân loại các sự kiện mà SDK ghi vào đĩa, và gửi chúng đến máy chủ. +**Collector** +`agenteye-collector`, daemon nhẹ chạy trên mỗi máy agent, batch các event mà SDK ghi vào đĩa, và vận chuyển chúng đến máy chủ. -**API key (Khóa API)** -Một token có phạm vi xác thực client đối với máy chủ. Các khóa mang quyền chi tiết (ví dụ `events:add` cho bộ sưu tập, phạm vi chỉ đọc cho khóa bảng điều khiển). Xem [API keys](/vi/agenteye/api-keys). +**API key** +Một token phạm vi xác thực một máy khách đối với máy chủ. Các khóa mang các quyền chi tiết (ví dụ `events:add` cho collector, phạm vi chỉ đọc cho một khóa bảng điều khiển). Xem [API keys](/vi/agenteye/api-keys). -**Server (Máy chủ)** -Dịch vụ tiếp nhận và API. Nó tiếp nhận sự kiện, lưu trữ trạng thái hoạt động trong cơ sở dữ liệu của bạn, và phục vụ bảng điều khiển và CLI. +**Server** +Dịch vụ ingest và API. Nó nạp các event, lưu trữ trạng thái hoạt động trong các cơ sở dữ liệu của bạn, và cung cấp bảng điều khiển và CLI. -**Dashboard (Bảng điều khiển)** -Giao diện người dùng web. Mọi trang được phạm vi cho một tổ chức và đọc thông qua API của máy chủ. +**Dashboard** +Giao diện người dùng web. Mỗi trang được phạm vi đến một organization và đọc thông qua API của máy chủ. --- ## Các bước tiếp theo -- [Overview](/vi/agenteye/overview): cách các phần này phù hợp với nhau. -- [Observability](/vi/agenteye/observability): các bề mặt observe (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file +- [Overview](/vi/agenteye/overview): cách các phần này kết hợp với nhau. +- [Observability](/vi/agenteye/observability): các bề mặt quan sát (Events, Sessions, Models, Tools, Hooks, Errors). \ No newline at end of file diff --git a/docs/vi/agenteye/dashboards.mdx b/docs/vi/agenteye/dashboards.mdx index 785923ea..9b16ee65 100644 --- a/docs/vi/agenteye/dashboards.mdx +++ b/docs/vi/agenteye/dashboards.mdx @@ -1,46 +1,46 @@ --- title: "Bảng điều khiển" -description: "Biến dữ liệu agent trực tiếp của bạn thành một bức tranh chung mà toàn bộ team theo dõi." +description: "Biến dữ liệu agent trực tiếp của bạn thành một bức tranh chung mà toàn bộ đội của bạn theo dõi." --- -Biến dữ liệu agent trực tiếp của bạn thành một bức tranh chung mà toàn bộ team theo dõi. Ghim các truy vấn quan trọng dưới dạng biểu đồ, và mọi người đều nhìn thấy cùng một bộ số liệu một cách rõ ràng, mà không cần chạy lại bất kỳ truy vấn nào. +Biến dữ liệu agent trực tiếp của bạn thành một bức tranh chung mà toàn bộ đội của bạn theo dõi. Ghim các truy vấn quan trọng dưới dạng biểu đồ, và mọi người đều nhìn thấy cùng những con số trong nháy mắt, mà không cần chạy lại bất kỳ truy vấn nào. -![A dashboard built from saved queries: an events-per-hour line, an errors-by-type bar, a latency area chart, and tokens-by-model](/agenteye/images/dashboard-fleet.png) +![Một bảng điều khiển được xây dựng từ các truy vấn đã lưu: một dòng sự kiện mỗi giờ, một thanh lỗi theo loại, một biểu đồ diện tích độ trễ và token theo mô hình](/agenteye/images/dashboard-fleet.png) -*Một bảng, bốn truy vấn đã lưu: sự kiện mỗi giờ, lỗi theo loại, độ trễ, và token theo mô hình.* +*Một bảng, bốn truy vấn đã lưu: sự kiện mỗi giờ, lỗi theo loại, độ trễ và token theo mô hình.* -## Mọi người đều nhìn thấy cùng một sự thật +## Mọi người đều thấy cùng một sự thật -Ngừng dán ảnh chụp màn hình vào chat và ngừng chạy lại cùng một truy vấn năm lần mỗi ngày. Bảng điều khiển là một bảng chung, toàn công ty mà bất kỳ ai trong team của bạn đều có thể mở để xem chính xác cùng một view. Khi dữ liệu cơ bản thay đổi, biểu đồ cũng thay đổi theo, do đó bảng luôn được cập nhật và không ai phải tranh cãi về những con số cũ. +Hãy dừng việc dán các ảnh chụp màn hình vào trò chuyện và dừng chạy lại cùng một truy vấn năm lần mỗi ngày. Một bảng điều khiển là một bảng được chia sẻ trên toàn tổ chức mà bất kỳ ai trong đội của bạn đều có thể mở để xem chính xác cùng một khung nhìn. Khi dữ liệu cơ bản thay đổi, các biểu đồ sẽ thay đổi theo, vì vậy bảng luôn được cập nhật và không ai tranh cải về những con số cũ. -Bảng fleet ở trên là một hình dạng tốt để bắt đầu cho hoạt động hàng ngày: +Bảng điều khiển fleet ở trên là một hình dạng khởi đầu tốt cho các hoạt động hàng ngày: -- một dòng **events-per-hour**, để bạn có thể theo dõi thông lượng và phát hiện một sự giảm đột ngột -- một biểu đồ cột **errors-by-type**, để các danh mục lỗi lớn nhất nổi bật -- một biểu đồ khu vực **latency**, để các sự chậm lại được nhìn thấy trước khi người dùng phàn nàn +- một dòng **events-per-hour**, để bạn có thể theo dõi thông lượng và bắt được sự sụt giảm đột ngột +- một thanh **errors-by-type**, để các danh mục lỗi lớn nhất của bạn nổi bật +- một biểu đồ diện tích **latency**, để các sự chậm lại xuất hiện trước khi người dùng phàn nàn - một bảng phân tích **tokens-by-model**, để chi phí luôn nằm trong tầm nhìn Bạn sẽ tìm thấy các bảng của mình tại `//dashboards`. ## Ghim các truy vấn bạn đã lưu -Mỗi ô bắt đầu như một truy vấn đã lưu. Xây dựng và lưu truy vấn bạn quan tâm trong thư viện [Queries](/vi/agenteye/queries) (các cài đặt sẵn tích hợp cộng với các truy vấn của riêng bạn, trên các sự kiện và đánh giá của bạn), sau đó ghim nó vào bảng điều khiển dưới dạng biểu đồ phù hợp với dữ liệu: một **line** cho xu hướng theo thời gian, một **bar** để so sánh các danh mục, một **area** cho khối lượng, hoặc một **pie** để chia nhỏ tỷ lệ. +Mỗi ô bắt đầu như một truy vấn đã lưu. Xây dựng và lưu truy vấn bạn quan tâm trong thư viện [Truy vấn](/vi/agenteye/queries) (cài sẵn plus của riêng bạn, qua các sự kiện và đánh giá của bạn), sau đó ghim nó vào bảng điều khiển dưới dạng biểu đồ phù hợp với dữ liệu: một **line** cho xu hướng theo thời gian, một **bar** để so sánh các danh mục, một **area** cho khối lượng hoặc một **pie** cho phân tích chia sẻ. -Vì một ô chỉ là truy vấn đã lưu của bạn được hiển thị dưới dạng biểu đồ, không có gì cần giữ đồng bộ bằng tay. Cập nhật truy vấn một lần và mỗi bảng điều khiển sử dụng nó sẽ được cập nhật. +Vì một ô chỉ là truy vấn đã lưu của bạn được hiển thị dưới dạng biểu đồ, không có gì phải giữ đồng bộ bằng tay. Cập nhật truy vấn một lần và mọi bảng điều khiển sử dụng nó sẽ cập nhật theo. ## Theo dõi chất lượng, không chỉ khối lượng -Khối lượng cho bạn biết rằng các agent đang bận rộn. Chất lượng cho bạn biết rằng họ thực sự đang làm công việc. Hướng bảng điều khiển tới [điểm đánh giá](/vi/agenteye/evaluations) của bạn và bạn sẽ nhận được một bảng theo dõi mức độ hoàn thành tốt của các lần chạy theo thời gian, do đó một sự suy giảm chất lượng sẽ hiển thị dưới dạng một dip trên biểu đồ thay vì một bất ngờ từ khách hàng. +Khối lượng cho bạn biết các agent đang bận. Chất lượng cho bạn biết họ thực sự đang làm công việc. Hướng một bảng điều khiển đến [điểm đánh giá](/vi/agenteye/evaluations) của bạn và bạn sẽ có được một bảng theo dõi mức độ tốt của các lần chạy theo thời gian, vì vậy sự suy giảm chất lượng xuất hiện dưới dạng một dip trên biểu đồ thay vì một bất ngờ từ khách hàng. -![A quality-focused dashboard built from saved evaluation queries](/agenteye/images/dashboard-quality.png) +![Một bảng điều khiển tập trung vào chất lượng được xây dựng từ các truy vấn đánh giá đã lưu](/agenteye/images/dashboard-quality.png) *Một bảng chất lượng giữ điểm đánh giá của bạn ở vị trí trung tâm, ngay bên cạnh các con số hoạt động.* -Giữ một bảng hoạt động và một bảng chất lượng cạnh nhau và team của bạn sẽ có một nơi duy nhất để trả lời cả "nó có hoạt động không?" và "nó có tốt không?", mà không ai cần chạy lại một truy vấn. +Giữ một bảng hoạt động và một bảng chất lượng cạnh nhau và đội của bạn sẽ có một nơi để trả lời cả "nó có hoạt động không?" và "nó có tốt không?", mà không cần ai chạy lại một truy vấn. ## Liên quan -- [Queries](/vi/agenteye/queries): xây dựng và lưu các truy vấn trở thành các ô của bạn. -- [Evaluations](/vi/agenteye/evaluations): đánh giá các lần chạy của bạn để bạn có thể vẽ biểu đồ chất lượng theo thời gian. -- [Alerts](/vi/agenteye/alerts): biến một ngưỡng trên bất kỳ một trong những số liệu này thành một trang. \ No newline at end of file +- [Truy vấn](/vi/agenteye/queries): xây dựng và lưu các truy vấn trở thành các ô của bạn. +- [Đánh giá](/vi/agenteye/evaluations): ghi điểm các lần chạy của bạn để bạn có thể biểu đồ chất lượng theo thời gian. +- [Cảnh báo](/vi/agenteye/alerts): biến một ngưỡng trên bất kỳ một trong các số liệu này thành một trang. \ No newline at end of file diff --git a/docs/vi/agenteye/error-tracking.mdx b/docs/vi/agenteye/error-tracking.mdx index 0a17c586..ee247e00 100644 --- a/docs/vi/agenteye/error-tracking.mdx +++ b/docs/vi/agenteye/error-tracking.mdx @@ -1,41 +1,41 @@ --- -title: "Theo dõi Lỗi" -description: "Xem mọi lỗi mà agents của bạn tạo ra ở một nơi, được nhóm lại để một loạt lỗi ồn ào hiển thị như một vấn đề duy nhất." +title: "Theo Dõi Lỗi" +description: "Xem mọi lỗi mà các agent của bạn tạo ra ở một nơi, được nhóm lại để một loạt lỗi lớn được đọc là một vấn đề duy nhất." --- -Xem mọi lỗi mà agents của bạn tạo ra ở một nơi, được nhóm lại để một loạt lỗi ồn ào hiển thị như một vấn đề duy nhất. Bạn có một đường dẫn một lần bấm từ "có thứ gì đó bị lỗi" đến chính xác lần chạy bị hỏng, mà không cần cuộn qua nguồn cấp dữ liệu trực tiếp để tìm nó. +Xem mọi lỗi mà các agent của bạn tạo ra ở một nơi, được nhóm lại để một loạt lỗi lớn được đọc là một vấn đề duy nhất. Bạn có một con đường một cú nhấp chuột từ "có thứ gì đó là lỗi" đến chính xác chạy bị hỏng, mà không cần cuộn một luồng trực tiếp để tìm nó. -![Trang Lỗi: một biểu đồ cột của các lỗi theo thời gian ở trên các hàng lỗi màu đỏ được nhóm lại, mỗi hàng có nút "+ cảnh báo" một lần bấm](/agenteye/images/errors.png) -*Trang Lỗi: một biểu đồ cột của các lỗi theo thời gian, với các lỗi lặp lại được thu gọn thành một hàng cho mỗi sự cố.* +![Trang Errors: một biểu đồ tần suất của các lỗi theo thời gian ở trên các hàng lỗi màu đỏ được nhóm lại, mỗi hàng có nút "+ alert" có thể nhấp một lần](/agenteye/images/errors.png) +*Trang Errors: một biểu đồ tần suất của các lỗi theo thời gian, với các lỗi lặp lại được thu gọn thành một hàng cho mỗi sự cố.* -## Mọi lỗi, đã được thu thập cho bạn +## Mọi lỗi đều được thu thập cho bạn -Khi một agent bị lỗi, bạn không nên phải cuộn qua luồng sự kiện trực tiếp hy vọng bắt được các hàng màu đỏ trước khi chúng cuộn đi. Trang **Lỗi** làm việc thu thập cho bạn. Nó kéo tất cả những gì bảng điều khiển sẽ tô màu đỏ vào một bề mặt phân loại duy nhất, vì vậy điều đầu tiên bạn thấy là những gì đang bị lỗi, không phải nơi để tìm kiếm nó. +Khi một agent bị hỏng, bạn không nên phải cuộn một luồng sự kiện trực tiếp hy vọng bắt được các hàng lỗi trước khi chúng cuộn đi. Trang **Errors** sẽ thu thập cho bạn. Nó kéo lại mọi thứ mà bảng điều khiển sẽ hiển thị bằng màu đỏ vào một bề mặt phân loại, vì vậy điều đầu tiên bạn thấy là cái gì đang bị hỏng, chứ không phải nơi phải đi tìm. -Và nó bắt được nhiều hơn những cái hiển nhiên. Bên cạnh các sự kiện `error` rõ ràng, Failproof AI Observability cũng hiển thị những lỗi yên tĩnh: bất kỳ `tool_result`, `hook_completed`, hoặc `agent_end` nào có payload chứa lỗi sẽ xuất hiện ở đây. Một công cụ trả về lỗi, hoặc một hook thoát không tốt, không còn bỏ qua bạn chỉ vì không có gì ném ra một ngoại lệ to tiếng. +Và nó bắt được nhiều hơn những cái rõ ràng. Bên cạnh các sự kiện `error` rõ ràng, Failproof AI Observability cũng hiển thị các lỗi yên tĩnh: bất kỳ `tool_result`, `hook_completed`, hoặc `agent_end` có payload mang lỗi đều xuất hiện ở đây. Một công cụ đã trả về lỗi, hoặc một hook đã thoát kém, không còn trơn tru qua bạn chỉ vì không có gì ném một ngoại lệ lớn. -Trên cùng, một biểu đồ cột vẽ các lỗi theo thời gian. Một cái nhìn sẽ cho bạn biết liệu đây là một dòng nền ổn định hay một loạt bắt đầu vài phút trước, vì vậy bạn biết ngay lập tức xem có nên bỏ công việc của bạn hay không. +Trên toàn bộ phía trên, một biểu đồ tần suất vẽ các lỗi theo thời gian. Một cái nhìn cho bạn biết liệu đây là một dòng nền ổn định hay một spike bắt đầu vài phút trước, vì vậy bạn sẽ biết ngay lập tức có nên bỏ những gì bạn đang làm hay không. -Giống như mọi bề mặt observe, trang Lỗi được phạm vi để tổ chức của bạn và lọc theo phạm vi ngày, môi trường, agent và phiên. Điều đó có nghĩa là bạn có thể lấy danh sách toàn bộ đội máy bay và thu hẹp nó thành một agent duy nhất hoặc một môi trường duy nhất mà bạn thực sự quan tâm. +Giống như mọi bề mặt quan sát, trang Errors được phạm vi đến tổ chức của bạn và lọc theo phạm vi ngày, môi trường, agent và phiên. Điều đó có nghĩa là bạn có thể lấy danh sách toàn bộ đội và thu hẹp xuống thành một agent hoặc một môi trường bạn thực sự quan tâm. ## Một sự cố, không phải một trăm hàng giống hệt nhau -Một phụ thuộc bị hỏng có thể kích hoạt cùng một lỗi hàng trăm lần một phút. Để lại ở trạng thái thô, đó là một bức tường gần như các dòng giống hệt nhau cô lập điều duy nhất mà bạn thực sự cần thấy. +Một phụ thuộc bị hỏng có thể kích hoạt cùng một lỗi hàng trăm lần mỗi phút. Để lại ở trạng thái thô, đó là một bức tường của các dòng gần như giống hệt nhau ẩn đi một thứ duy nhất bạn thực sự cần thấy. -Failproof AI Observability thu gọn các lỗi lặp lại có cùng phiên và loại lỗi thành một hàng duy nhất. Một loạt đọc như một sự cố duy nhất. Bạn kết thúc việc đếm các vấn đề, không phải các dòng nhật ký, và tín hiệu quan trọng vẫn ở trên cùng thay vì bị chìm dưới khối lượng của chính nó. +Failproof AI Observability sụp đổ các lỗi lặp lại chia sẻ cùng một phiên và loại lỗi thành một hàng duy nhất. Một loạt đọc như một sự cố. Bạn kết thúc việc đếm các vấn đề, không phải các dòng nhật ký, và tín hiệu quan trọng vẫn ở trên cùng thay vì bị chìm dưới khối lượng của chính nó. -## Từ "có thứ gì đó bị lỗi" đến sự kiện chính xác +## Từ "có thứ gì đó là lỗi" đến sự kiện chính xác -Nhấp vào bất kỳ hàng nào để hạ cánh thẳng bên trong phiên của lần chạy đó, được định vị trên sự kiện chính xác bị lỗi. Không sao chép ID phiên, không cuộn để tìm kiếm thời điểm nó bị lỗi: bạn hạ cánh đúng trên nó, với toàn bộ biểu đồ thực thi một cái nhìn mắt xa vì vậy bạn có thể thấy agent đã làm gì ở những khoảnh khắc trước khi nó bị hỏng. +Nhấp vào bất kỳ hàng nào để đi thẳng vào phiên của chạy đó, được định vị trên sự kiện chính xác đã thất bại. Không sao chép ID phiên, không cuộn để tìm kiếm thời điểm nó sai: bạn đến ngay trên nó, với biểu đồ thực thi đầy đủ chỉ cách xa một cái nhìn để bạn có thể thấy cái gì agent đã làm trong những khoảnh khắc trước khi nó bị hỏng. -Nếu bạn có `alerts:write`, mọi hàng cũng có nút **+ cảnh báo**. Nhấp vào nó và Observability mở một quy tắc cảnh báo mới đã được điền để bắt cùng một lỗi lần nữa. Sự cố bạn vừa phân loại trở thành cái sẽ trang báo bạn lần tiếp theo, thay vì làm bạn ngạc nhiên hai lần. +Nếu bạn có `alerts:write`, mỗi hàng cũng mang một nút **+ alert**. Nhấp vào nó và Observability mở một quy tắc cảnh báo mới đã được điền sẵn để bắt lỗi giống nhau lần tới. Sự cố bạn vừa phân loại trở thành cái sẽ cảnh báo cho bạn lần tới, thay vì làm bạn ngạc nhiên hai lần. -**Nơi tìm thấy nó:** trang **Lỗi** nằm trong phần observe của bảng điều khiển, tại `//errors`. +**Nơi để tìm nó:** trang **Errors** nằm trong phần quan sát của bảng điều khiển, tại `//errors`. ## Liên quan -- [Cảnh báo](/vi/agenteye/alerts): biến bất kỳ lỗi nào thành một quy tắc trang báo. -- [Sự cố](/vi/agenteye/incidents): theo dõi một cảnh báo được kích hoạt từ mở đến đã giải quyết. -- [Phiên](/vi/agenteye/sessions): mở toàn bộ lần chạy đằng sau bất kỳ lỗi nào. -- [Kiểm toán](/vi/agenteye/audits): cho phép Observability tìm ra các mô hình lỗi trên các lần chạy của bạn cho bạn. \ No newline at end of file +- [Alerts](/vi/agenteye/alerts): biến bất kỳ lỗi nào thành quy tắc cảnh báo. +- [Incidents](/vi/agenteye/incidents): theo dõi cảnh báo kích hoạt từ mở đến giải quyết. +- [Sessions](/vi/agenteye/sessions): mở chạy đầy đủ phía sau bất kỳ lỗi nào. +- [Audits](/vi/agenteye/audits): cho phép Observability tìm các mẫu lỗi trên tất cả các chạy của bạn cho bạn. \ No newline at end of file diff --git a/docs/vi/agenteye/evaluation-suite.mdx b/docs/vi/agenteye/evaluation-suite.mdx index 37082f06..06650db8 100644 --- a/docs/vi/agenteye/evaluation-suite.mdx +++ b/docs/vi/agenteye/evaluation-suite.mdx @@ -1,26 +1,25 @@ --- -title: "Bộ Công Cụ Đánh Giá" -description: "Failproof AI Observability có thể tự động chấm điểm mọi phiên chạy agent đã hoàn thành về chất lượng: bạn cung cấp một dịch vụ chấm điểm nhỏ, và Observability sẽ xử lý phần còn lại." +title: "Bộ Đánh Giá" +description: "Failproof AI Observability có thể tự động chấm điểm mỗi lần chạy agent hoàn thành để đánh giá chất lượng: bạn cung cấp một dịch vụ chấm điểm nhỏ, và Observability sẽ xử lý phần còn lại." --- +Failproof AI Observability có thể tự động chấm điểm mỗi lần chạy agent hoàn thành để đánh giá chất lượng: bạn cung cấp một dịch vụ chấm điểm nhỏ, và Observability sẽ xử lý phần còn lại. Sử dụng nó để theo dõi các yếu tố bạn quan tâm (hữu ích, hiệu quả công cụ, độ chính xác, an toàn; bạn lựa chọn), phát hiện các vấn đề suy giảm sớm và so sánh các agent hoặc môi trường một cách nhanh chóng. Chấm điểm là tùy chọn: quy trình không thực hiện bất kỳ điều gì cho đến khi bạn đặt `EVALUATOR_ENDPOINT` trên máy chủ. -Failproof AI Observability có thể tự động chấm điểm mọi phiên chạy agent đã hoàn thành về chất lượng: bạn cung cấp một dịch vụ chấm điểm nhỏ, và Observability sẽ xử lý phần còn lại. Sử dụng nó để theo dõi các chiều độ bạn quan tâm (tính hữu ích, hiệu quả công cụ, tính xác thực, bảo mật; bạn lựa chọn), phát hiện sự suy giảm sớm và so sánh các agent hoặc môi trường một cách nhanh chóng. Chấm điểm là tùy chọn: đường dẫn sẽ không hoạt động cho đến khi bạn đặt `EVALUATOR_ENDPOINT` trên máy chủ. +> **Lưu ý:** Bạn xác định các chiều chấm điểm. Trình đánh giá của bạn có thể trả về bất kỳ khóa số nào; Observability lưu trữ, theo dõi xu hướng và hiển thị bất cứ gì bạn gửi lại. -> **Ghi chú:** Bạn định nghĩa các chiều chấm điểm. Bộ đánh giá của bạn có thể trả về bất kỳ khóa số nào mà nó muốn; Observability lưu trữ, theo dõi xu hướng và hiển thị bất cứ thứ gì bạn gửi lại. +## Tổng quan -## Tóm tắt nhanh +1. **Viết một trình chấm điểm.** Thiết lập một dịch vụ HTTP nhỏ đọc phiên bản ghi và trả về điểm số. Observability cung cấp tham chiếu hoạt động mà bạn có thể sao chép. Xem [Viết một trình đánh giá với SDK](#writing-an-evaluator-with-the-sdk). +2. **Trỏ Observability đến nó.** Đặt `EVALUATOR_ENDPOINT` (và một `EVALUATOR_TOKEN` được chia sẻ) trên quy trình máy chủ. +3. **Theo dõi điểm số.** Mỗi phiên hoàn thành được chấm điểm tự động; kết quả xuất hiện trên trang chi tiết phiên, lưới phiên và bảng điều khiển đã lưu. -1. **Viết một bộ chấm điểm.** Thiết lập một dịch vụ HTTP nhỏ đọc bản ghi phiên và trả về điểm số. Observability cung cấp một bản tham khảo hoạt động mà bạn có thể sao chép. Xem [Viết bộ đánh giá với SDK](#writing-an-evaluator-with-the-sdk). -2. **Chỉ đến nó với Observability.** Đặt `EVALUATOR_ENDPOINT` (và một `EVALUATOR_TOKEN` được chia sẻ) trên quy trình máy chủ. -3. **Theo dõi điểm số.** Mọi phiên hoàn thành được chấm điểm tự động; kết quả hiển thị trên trang chi tiết phiên, lưới phiên và bảng điều khiển đã lưu. +![Chế độ xem chi tiết phiên với bản tóm tắt đánh giá, thanh điểm theo chiều, và văn bản giải thích ở cột bên phải](/agenteye/images/session-detail.png) -![Chế độ xem chi tiết phiên với bản tóm tắt đánh giá, thanh điểm số từng chiều và văn bản lý do trong thanh bên phải](/agenteye/images/session-detail.png) - -*Sau khi bộ đánh giá được định cấu hình, mỗi lần chạy được hoàn thành được chấm điểm và kết quả xuất hiện trong thanh bên phải của phiên: bản tóm tắt ở trên cùng, sau đó là thanh điểm số từng chiều với lý do.* +*Sau khi cấu hình trình đánh giá, mỗi lần chạy hoàn thành được chấm điểm và kết quả xuất hiện ở cột bên phải của phiên: bản tóm tắt ở trên, sau đó là thanh điểm theo chiều với giải thích.* --- -## Cách nó hoạt động +## Cách hoạt động ```mermaid flowchart LR @@ -32,44 +31,44 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -Khi Failproof AI Observability SDK phát ra sự kiện `agent_end` cho một phiên, máy chủ sẽ lên lịch đánh giá. Sau đó, nó POSTs bản ghi sự kiện đầy đủ tới dịch vụ bộ đánh giá của bạn, dịch vụ này có thể: +Khi SDK Observability phát ra sự kiện `agent_end` cho một phiên, máy chủ lên lịch một đánh giá. Sau đó, nó POSTs toàn bộ phiên bản ghi sự kiện đến dịch vụ trình đánh giá của bạn, có thể: -- **Trả về kết quả ngay lập tức** với `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Kết quả được thêm vào dòng thời gian đánh giá của phiên. `reasoning` và `summary` là tùy chọn. -- **Trì hoãn** với `{"status":"pending", "job_id":"abc-123"}`. Observability sau đó gọi `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` cho đến khi bộ đánh giá của bạn trả về `{"status":"done", ...}` hoặc `{"status":"error", "error":"..."}`. +- **Trả về kết quả nội tuyến** với `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`. Kết quả được thêm vào dòng thời gian đánh giá của phiên. `reasoning` và `summary` là tùy chọn. +- **Trì hoãn** với `{"status":"pending", "job_id":"abc-123"}`. Observability sau đó gọi `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123` cho đến khi trình đánh giá của bạn trả về `{"status":"done", ...}` hoặc `{"status":"error", "error":"..."}`. - Tần suất thăm dò được theo công việc: phản hồi `pending` có thể bao gồm `next_poll_secs` để ghi đè; nếu không, Observability sử dụng giá trị `default_poll_interval_secs` từ `GET /config`; nếu không, máy chủ quay lại `EVALUATOR_POLLING_INTERVAL_SECS` (mặc định 10 giây). Tất cả các giá trị được giới hạn trong [1 giây, 1 giờ]. + Tần suất thăm dò là theo công việc: phản hồi `pending` có thể bao gồm `next_poll_secs` để ghi đè; nếu không Observability sử dụng giá trị `default_poll_interval_secs` từ `GET /config`; nếu không máy chủ quay lại `EVALUATOR_POLLING_INTERVAL_SECS` (mặc định 10s). Tất cả các giá trị được giới hạn ở [1s, 1h]. -Các phiên không bao giờ phát ra `agent_end` (ví dụ: quy trình agent bị sập) cũng có thể được nhận: `GET /config` của bộ đánh giá có thể trả về `{"inactivity_timeout_secs": 1800}`, và Observability sẽ đánh giá bất kỳ phiên nào không hoạt động trong khoảng thời gian đó. Đặt trường thành `null` hoặc bỏ qua nó để tắt dự phòng này. +Các phiên không bao giờ phát ra `agent_end` (ví dụ, quá trình agent bị sự cố) cũng có thể được nhặt lên: `GET /config` của trình đánh giá có thể trả về `{"inactivity_timeout_secs": 1800}`, và Observability sẽ đánh giá bất kỳ phiên nào không hoạt động trong thời gian đó. Đặt trường thành `null` hoặc bỏ qua nó để tắt lựa chọn dự phòng này. -Đường dẫn hoàn toàn không hoạt động khi `EVALUATOR_ENDPOINT` chưa được đặt. +Quy trình hoàn toàn không hoạt động khi `EVALUATOR_ENDPOINT` không được đặt. -Một phiên có thể tích lũy **nhiều đánh giá terminal theo thời gian**: mỗi sự kiện `agent_end` (và mỗi lần đánh giá lại thủ công từ bảng điều khiển) thêm một hàng đánh giá mới. Đây là cách được hỗ trợ để đánh giá một cuộc trò chuyện được tiếp tục: người dùng kết thúc một agent, quay lại sau đó, gửi thêm sự kiện, kết thúc agent một lần nữa, và đánh giá thứ hai chạy so với bản ghi sự kiện đầy đủ được cập nhật. Bảng điều khiển hiển thị đánh giá gần đây nhất làm tiêu đề và các đánh giá trước đó dưới dạng dòng thời gian có thể thu gọn. Trong khi một đánh giá đang chạy cho một phiên, các sự kiện `agent_end` bổ sung cho phiên đó bị bỏ qua; cái tiếp theo sau khi đánh giá đang chạy hoàn thành sẽ xếp hàng một đánh giá mới như bình thường. +Một phiên có thể tích lũy **nhiều đánh giá cuối cùng theo thời gian**: mỗi sự kiện `agent_end` (và mỗi lần đánh giá lại thủ công từ bảng điều khiển) thêm một hàng đánh giá tươi. Đây là cách được hỗ trợ để đánh giá một cuộc trò chuyện được tiếp tục: người dùng kết thúc agent, quay lại sau, gửi thêm sự kiện, kết thúc agent lần nữa, và đánh giá thứ hai chạy so với phiên bản ghi đầy đủ được cập nhật. Bảng điều khiển hiển thị đánh giá gần đây nhất là tiêu đề và các đánh giá trước đó dưới dạng dòng thời gian có thể gập lại. Khi một đánh giá đang chạy cho một phiên, các sự kiện `agent_end` bổ sung cho phiên đó bị bỏ qua; sự kiện tiếp theo sau khi đánh giá đang chạy hoàn thành sẽ xếp hàng đợi một đánh giá tươi như bình thường. -Dự phòng không hoạt động cũng tái bật trên các phiên được tiếp tục: nếu các sự kiện mới đến sau một đánh giá terminal trước đó và phiên sau đó không hoạt động quá `inactivity_timeout_secs`, một đánh giá mới được xếp hàng. +Lựa chọn dự phòng không hoạt động sẽ tái kích hoạt trên các phiên được tiếp tục: nếu các sự kiện mới đến sau khi đánh giá cuối cùng trước đó và phiên sau đó không hoạt động quá `inactivity_timeout_secs`, một đánh giá tươi sẽ được xếp hàng đợi. -Các lỗi tạm thời (5xx, 429, timeout, lỗi mạng) được thử lại với backoff lũy thừa lên đến `EVALUATOR_MAX_ATTEMPTS`; phản hồi 4xx là terminal. Observability an toàn để chạy với nhiều phiên bản máy chủ được mở rộng ngang; công việc được phân vùng để phiên tương tự không bao giờ được gửi hai lần cùng một lúc. +Các lỗi tạm thời (5xx, 429, hết thời gian chờ, lỗi mạng) được thử lại với lùi mũ theo `EVALUATOR_MAX_ATTEMPTS`; phản hồi 4xx là cuối cùng. Observability an toàn khi chạy với nhiều instances máy chủ được mở rộng theo chiều ngang; công việc được phân vùng để phiên tương tự không bao giờ được gửi hai lần đồng thời. --- ## Hợp đồng HTTP -Mọi tuyến được xác thực sử dụng **xác thực bearer token**. Cùng một giá trị phải được định cấu hình ở cả hai bên: +Mỗi tuyến đường được xác thực sử dụng **xác thực mã thông báo người mang**. Cùng một giá trị phải được cấu hình ở cả hai bên: -- Máy chủ Observability: biến môi trường `EVALUATOR_TOKEN` -- Dịch vụ đánh giá: được định cấu hình theo cách tương tự (SDK `agenteye-evaluator` đọc `EVALUATOR_TOKEN` theo quy ước) +- Máy chủ Observability: biến env `EVALUATOR_TOKEN` +- Dịch vụ trình đánh giá: được cấu hình theo cách tương tự (SDK `agenteye-evaluator` đọc `EVALUATOR_TOKEN` theo quy ước) -Nếu `EVALUATOR_TOKEN` chưa được đặt, máy chủ không gửi tiêu đề `Authorization`; bộ đánh giá sau đó có thể chấp nhận yêu cầu ẩn danh, điều này tốt cho một mạng nội bộ nhưng không được khuyến khích trên internet công cộng. +Nếu `EVALUATOR_TOKEN` không được đặt, máy chủ không gửi tiêu đề `Authorization`; trình đánh giá có thể chấp nhận các yêu cầu ẩn danh, điều này tốt cho mạng chỉ dành cho nội bộ nhưng không được khuyến khích trên internet công cộng. -### Các tuyến bộ đánh giá phải phục vụ +### Các tuyến đường trình đánh giá phải cung cấp -| Tuyến | Nội dung / tham số | Phản hồi | +| Tuyến đường | Phần thân / tham số | Phản hồi | |---|---|---| -| `GET /health` | không có | `{"status":"ok"}` (mở, không có xác thực) | -| `GET /config` | không có | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | +| `GET /health` | không | `{"status":"ok"}` (mở, không xác thực) | +| `GET /config` | không | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | | `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` hoặc `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | không có | cùng hình dạng phản hồi như `/evaluate` | +| `GET /evaluate/{id}` | không | hình dạng phản hồi giống như `/evaluate` | -### Nội dung `EvalRequest` được gửi bởi máy chủ +### Phần thân `EvalRequest` được gửi bởi máy chủ ```json { @@ -102,7 +101,7 @@ Nếu `EVALUATOR_TOKEN` chưa được đặt, máy chủ không gửi tiêu đ } ``` -`reasoning` (bản đồ lý do cho mỗi điểm) và `summary` (câu chuyện toàn cảnh một đoạn) đều là tùy chọn. Các khóa trong `reasoning` phải phản ánh các khóa trong `scores`; bảng điều khiển hiển thị mỗi mục nội tuyến dưới thanh điểm số của nó. Các bộ đánh giá cũ chỉ trả về `scores` tiếp tục hoạt động không thay đổi; `reasoning` và `summary` chỉ được đọc là null và các phần giao diện tương ứng bị bỏ qua. +`reasoning` (bản đồ biện minh theo điểm số) và `summary` (một câu chuyện đoạn duy nhất) đều là tùy chọn. Các khóa trong `reasoning` phải phản ánh các khóa trong `scores`; bảng điều khiển hiển thị mỗi mục nội tuyến dưới thanh điểm của nó. Các trình đánh giá cũ chỉ trả về `scores` tiếp tục hoạt động không thay đổi; `reasoning` và `summary` đơn giản là đọc là null và các affordances UI tương ứng bị bỏ qua. **Không đồng bộ (trì hoãn):** @@ -110,25 +109,25 @@ Nếu `EVALUATOR_TOKEN` chưa được đặt, máy chủ không gửi tiêu đ { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } ``` -`next_poll_secs` là tùy chọn; nếu bỏ qua máy chủ quay lại `default_poll_interval_secs` của bộ đánh giá từ `/config`, sau đó là biến `EVALUATOR_POLLING_INTERVAL_SECS` riêng của nó. +`next_poll_secs` là tùy chọn; nếu bỏ qua máy chủ quay lại `default_poll_interval_secs` của trình đánh giá từ `/config`, sau đó đến biến env `EVALUATOR_POLLING_INTERVAL_SECS` của chính nó. -**Lỗi terminal phía bộ đánh giá:** +**Lỗi cuối cùng phía trình đánh giá:** ```json { "status": "error", "error": "model service unavailable" } ``` -Máy chủ coi bất kỳ nội dung 2xx khác làm lỗi giao thức và ghi lại một `error` terminal cho phiên. +Máy chủ coi bất kỳ phần thân 2xx nào khác là lỗi giao thức và ghi lại một `error` cuối cùng cho phiên. --- -## Viết bộ đánh giá với SDK +## Viết một trình đánh giá với SDK -Bạn không phải triển khai hợp đồng HTTP bằng tay. Gói Python `agenteye-evaluator` cung cấp cho bạn một trình bao bọc FastAPI được gõ xử lý xác thực, định tuyến và các hình dạng yêu cầu/phản hồi cho bạn. +Bạn không phải triển khai hợp đồng HTTP bằng tay. Gói Python `agenteye-evaluator` cung cấp cho bạn một trình bao bọc FastAPI được nhập để xử lý xác thực, định tuyến và các hình dạng yêu cầu/phản hồi cho bạn. -Failproof AI Observability cũng cung cấp một **bộ đánh giá tham khảo hoạt động** chấm điểm `helpfulness`, `tool_efficiency` và `factuality` từ hình dạng của bản ghi. Sao chép nó làm điểm khởi đầu và hoán đổi logic của riêng bạn: một trọng tài LLM, một công cụ quy tắc, bất cứ thứ gì phù hợp với tiêu chuẩn chất lượng của bạn. +Failproof AI Observability cũng cung cấp một **trình đánh giá tham chiếu hoạt động** chấm `helpfulness`, `tool_efficiency` và `factuality` từ hình dạng phiên bản ghi. Sao chép nó như một điểm khởi đầu và thay thế logic của riêng bạn: một trình xét xử LLM, một công cụ quy tắc, bất cứ gì phù hợp với thanh chất lượng của bạn. -Bộ đánh giá tối thiểu khả thi: +Trình đánh giá tối thiểu khả thi: ```python import os @@ -147,60 +146,60 @@ def run(req: EvalRequest) -> EvalResponse: ) ``` -Phiên bản `app` chạy dưới bất kỳ máy chủ ASGI nào, vì vậy `uvicorn module:app` bắt đầu nó. +Instance `app` chạy dưới bất kỳ máy chủ ASGI nào, vì vậy `uvicorn module:app` khởi động nó. -Đối với các bộ đánh giá cần phải trì hoãn công việc tốn kém, hãy trả về `JobPending` thay thế và đăng ký trình xử lý `@app.job_lookup`; máy chủ Observability thăm dò `GET /evaluate/{job_id}` cho đến khi bạn trả về trạng thái terminal hoặc giới hạn `EVALUATOR_MAX_POLL_DURATION_SECS` (mặc định 1 giờ) hết hạn. +Đối với các trình đánh giá cần trì hoãn công việc tốn kém, hãy trả về `JobPending` thay thế và đăng ký trình xử lý `@app.job_lookup`; máy chủ Observability thăm dò `GET /evaluate/{job_id}` cho đến khi bạn trả về trạng thái cuối cùng hoặc giới hạn `EVALUATOR_MAX_POLL_DURATION_SECS` (mặc định 1 h) đã trôi qua. -Tài liệu tham khảo API đầy đủ, mô hình không đồng bộ và lược đồ sự kiện được ghi lại trong README của SDK `agenteye-evaluator`. +Tham chiếu API đầy đủ, mẫu không đồng bộ và lược đồ sự kiện được ghi chép trong README của SDK `agenteye-evaluator`. --- -## Chạy bộ đánh giá của bạn +## Chạy trình đánh giá của bạn -Bộ đánh giá là **dịch vụ của bạn** — Failproof AI Observability không cung cấp bộ đánh giá mặc định, vì vậy bạn xây dựng và chạy nó ở bất cứ nơi nào bạn chạy các dịch vụ riêng của mình. Nó chạy dưới bất kỳ máy chủ ASGI nào (ví dụ `uvicorn my_evaluator:app`); phục vụ các tuyến `/health`, `/config` và `/evaluate` từ [hợp đồng HTTP](#http-contract), sau đó chỉ máy chủ tới nó (xem [Định cấu hình máy chủ](#configuring-the-server)). +Trình đánh giá là **dịch vụ của bạn** — Failproof AI Observability không cung cấp trình đánh giá mặc định, vì vậy bạn xây dựng và chạy nó ở bất kỳ nơi bạn chạy các dịch vụ của riêng bạn. Nó chạy dưới bất kỳ máy chủ ASGI nào (ví dụ `uvicorn my_evaluator:app`); phục vụ các tuyến đường `/health`, `/config` và `/evaluate` từ [hợp đồng HTTP](#http-contract), sau đó trỏ máy chủ đến nó (xem [Cấu hình máy chủ](#configuring-the-server)). -Sau khi bộ đánh giá có thể truy cập được, `GET /health` trả về `{"status":"ok"}`. Sau khi một agent chạy từ đầu đến cuối, `GET /evaluations` trên máy chủ trả về một hàng có `status: "done"` và điểm số bộ đánh giá của bạn tạo ra. +Khi trình đánh giá có thể truy cập được, `GET /health` trả về `{"status":"ok"}`. Sau khi agent chạy từ đầu đến cuối, `GET /evaluations` trên máy chủ trả về một hàng có `status: "done"` và điểm số mà trình đánh giá của bạn tạo ra. --- -## Định cấu hình máy chủ +## Cấu hình máy chủ Đặt trên quy trình máy chủ: -| Biến môi trường | Ý nghĩa | +| Biến Env | Ý nghĩa | |---|---| -| `EVALUATOR_ENDPOINT` | URL cơ sở của bộ đánh giá của bạn (`http://evaluator:9000`). Chưa đặt = đường dẫn bị vô hiệu hóa. | -| `EVALUATOR_TOKEN` | Bearer token. Phải bằng giá trị dịch vụ bộ đánh giá được định cấu hình với. | -| `EVALUATOR_WORKERS` | Tác vụ công nhân trên phiên bản máy chủ (mặc định 2). | -| `EVALUATOR_CLAIM_BATCH` | Hàng được yêu cầu trên mỗi tick công nhân (mặc định 4). Các lô được xử lý **đồng thời**; hiệu ứng đồng thời trên điểm cuối bộ đánh giá của bạn là `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Công nhân ngủ bao lâu giữa các nỗ lực gửi khi không có đánh giá nào đến hạn (mặc định 2 giây). | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Dự phòng cuối cùng cho tần suất `GET /evaluate/{id}` khi không có `next_poll_secs` trên mỗi phản hồi cũng như `default_poll_interval_secs` của bộ đánh giá được đặt (mặc định 10 giây). | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | Timeout mỗi yêu cầu (mặc định 30000). | -| `EVALUATOR_MAX_ATTEMPTS` | Sau nhiều lỗi tạm thời này kết quả được ghi lại là `error` terminal (mặc định 5). | +| `EVALUATOR_ENDPOINT` | URL cơ sở của trình đánh giá của bạn (`http://evaluator:9000`). Không được đặt = quy trình bị tắt. | +| `EVALUATOR_TOKEN` | Mã thông báo người mang. Phải bằng giá trị mà dịch vụ trình đánh giá được cấu hình. | +| `EVALUATOR_WORKERS` | Công việc nhân viên trên mỗi instance máy chủ (mặc định 2). | +| `EVALUATOR_CLAIM_BATCH` | Hàng được yêu cầu trên mỗi bước nhân viên (mặc định 4). Các lô được xử lý **đồng thời**; đồng thời hiệu dụng trên điểm cuối trình đánh giá của bạn là `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Nhân viên ngủ bao lâu giữa các lần cố gắng gửi khi không có đánh giá do (mặc định 2s). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Lựa chọn dự phòng cuối cùng cho tần suất `GET /evaluate/{id}` khi `next_poll_secs` theo phản hồi và `default_poll_interval_secs` của trình đánh giá không được đặt (mặc định 10s). | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Hết thời gian chờ mỗi yêu cầu (mặc định 30000). | +| `EVALUATOR_MAX_ATTEMPTS` | Sau kết quả này nhiều lỗi tạm thời được ghi lại dưới dạng `error` cuối cùng (mặc định 5). | | `EVALUATOR_CONFIG_REFRESH_SECS` | Tần suất `GET /config` (mặc định 300). | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Thời gian tối đa một phiên có thể ở trong hàng đợi thăm dò trước khi bị kết thúc làm `timeout` (mặc định 3600 giây). Bảo vệ chống lại bộ đánh giá luôn trả về `pending` mãi mãi. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Thời gian tường tối đa một phiên có thể ở trong hàng đợi thăm dò trước khi nó được chấm dứt là `timeout` (mặc định 3600s). Bảo vệ chống lại trình đánh giá luôn trả về `pending` mãi mãi. | -Để bật chấm điểm tự động, đặt cả `EVALUATOR_ENDPOINT` và `EVALUATOR_TOKEN` trên máy chủ, sau đó khởi động lại nó để áp dụng thay đổi. Khi `EVALUATOR_ENDPOINT` chưa được đặt đường dẫn vẫn là một no-op. +Để bật chấm điểm tự động, hãy đặt cả `EVALUATOR_ENDPOINT` và `EVALUATOR_TOKEN` trên máy chủ, sau đó khởi động lại nó để nhận được thay đổi. Với `EVALUATOR_ENDPOINT` không được đặt, quy trình vẫn là no-op. -Các nút tinh chỉnh ở trên là tùy chọn; chỉ đặt các biến môi trường tương ứng trên máy chủ nếu bạn cần ghi đè các mặc định. +Các nút điều chỉnh ở trên là tùy chọn; chỉ đặt các biến môi trường tương ứng trên máy chủ nếu bạn cần ghi đè các mặc định. --- -## Tài liệu tham khảo API +## Tham chiếu API -| Phương thức | Đường dẫn | Quyền cần thiết | Mục đích | +| Phương thức | Đường dẫn | Quyền bắt buộc | Mục đích | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | Kết quả terminal truy vấn. Hỗ trợ `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` mặc định là 50 và được capped ở 200 (lưu ý điều này khác với `/events`, được capped ở 1000). `environment` chấp nhận danh sách được phân tách bằng dấu phẩy (ví dụ: `environment=prod,staging`); các giá trị duy nhất vẫn hoạt động. Với `latest_per_session=true` phản hồi chứa tối đa một hàng cho mỗi `session_id` (gần đây nhất theo `completed_at`) được sử dụng bởi trang danh sách phiên để thu gọn dòng thời gian đánh giá của phiên thành tiêu đề hiện tại của nó. Mặc định là false (trả về toàn bộ lịch sử). | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | Sức khỏe eval được tổng hợp cho một lát được lọc: tổng số, phân tích done/error/timeout, thống kê per-score-key (count/avg/min/max/p50 trên các khóa `scores` tùy ý) và dòng thời gian được phân trang. Chấp nhận **các tham số lọc giống như `/evaluations`** cộng với `featured_keys` (CSV của các khóa điểm để theo dõi) và `latest_per_session`. Tính năng Dashboards; chỉ số chính xác trên toàn bộ bộ phù hợp, không được lấy mẫu. | -| `GET` | `/evaluations/environments` | `evaluations:read` | Giá trị môi trường riêng biệt từ bảng `evaluations`. Được sử dụng để điền các menu thả xuống bộ lọc có phạm vi dữ liệu có thể đọc được đánh giá. | -| `GET` | `/evaluation-jobs` | `evaluations:read` | Khả năng hiển thị các đánh giá đang bay. Lọc theo `status` (`pending`/`polling`). | -| `GET` | `/events` | `events:read` | Luồng các sự kiện thô của phiên. Hỗ trợ `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` và `order`. `order` là `desc` (mới nhất trước, mặc định) hoặc `asc` (cũ nhất trước); một giá trị không được nhận dạng quay lại `desc`. Phân trang con trỏ qua `next_cursor` của phản hồi (một id sự kiện): chuyển nó lại làm `cursor` để nhận trang tiếp theo; với `asc` trang tiếp theo là các sự kiện sau id đó, với `desc` là các sự kiện trước nó. `limit` mặc định là 50 và được capped ở 1000. | -| `GET` | `/sessions/:session_id/export` | `events:read` | Trả về chính xác nội dung JSON mà bộ đánh giá sẽ nhận cho phiên này, phục vụ như một tệp đính kèm có thể tải xuống được đặt tên là `session-.json`. Hữu ích cho việc phát lại các phiên sản xuất thông qua `agenteye-evaluator` để kiểm tra ngoại tuyến. Các byte giống hệt với những gì đường dẫn bộ đánh giá gửi. | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Xếp hàng một đánh giá mới cho một phiên; chạy cho dù có hay không có đánh giá trước đó. Kết quả mới được **thêm vào** dòng thời gian đánh giá của phiên thay vì ghi đè lên kết quả trước đó, vì vậy điểm số trước đó vẫn hiển thị như lịch sử. Trả về `202` khi xếp hàng, `404` cho phiên không xác định, `409` nếu một đánh giá đã đang tiến hành. Sử dụng sau khi triển khai một bộ đánh giá mới hoặc cho các phiên không bao giờ phát ra `agent_end`. | +| `GET` | `/evaluations` | `evaluations:read` | Kết quả cuối cùng truy vấn. Hỗ trợ `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`. `limit` mặc định là 50 và được giới hạn ở 200 (lưu ý điều này khác với `/events`, được giới hạn ở 1000). `environment` chấp nhận danh sách được phân tách bằng dấu phẩy (ví dụ `environment=prod,staging`); các giá trị duy nhất vẫn hoạt động. Với `latest_per_session=true` phản hồi chứa tối đa một hàng trên mỗi `session_id` (gần đây nhất theo `completed_at`) được sử dụng bởi trang danh sách phiên để gập dòng thời gian đánh giá của phiên thành tiêu đề hiện tại của nó. Mặc định là false (trả về lịch sử đầy đủ). | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | Sức khỏe đánh giá được tổng hợp cho một lát cắt được lọc: tổng số lượng, phân tích hoàn thành/lỗi/hết thời gian, thống kê theo khóa điểm số (đếm/trung bình/tối thiểu/tối đa/p50 trên các khóa `scores` tùy ý) và dòng thời gian gộp theo thời gian. Chấp nhận **các tham số bộ lọc giống như `/evaluations`** cộng với `featured_keys` (CSV của khóa điểm số để theo dõi xu hướng) và `latest_per_session`. Cơ năng tính năng Dashboards; các chỉ số chính xác trên toàn bộ tập hợp phù hợp, không được lấy mẫu. | +| `GET` | `/evaluations/environments` | `evaluations:read` | Giá trị môi trường riêng biệt từ bảng `evaluations`. Được sử dụng để điền các menu thả xuống bộ lọc được xác định phạm vi để đánh giá dữ liệu có thể đọc được. | +| `GET` | `/evaluation-jobs` | `evaluations:read` | Khả năng hiển thị các đánh giá đang hoạt động. Lọc theo `status` (`pending`/`polling`). | +| `GET` | `/events` | `events:read` | Truyền các sự kiện thô của phiên. Hỗ trợ `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit` và `order`. `order` là `desc` (mới nhất-đầu tiên, mặc định) hoặc `asc` (cũ nhất-đầu tiên); giá trị không được nhận dạng quay lại `desc`. Phân trang con trỏ thông qua `next_cursor` của phản hồi (một id sự kiện): chuyển nó lại làm `cursor` để nhận trang tiếp theo; với `asc` trang tiếp theo là các sự kiện sau id đó, với `desc` các sự kiện trước đó. `limit` mặc định là 50 và được giới hạn ở 1000. | +| `GET` | `/sessions/:session_id/export` | `events:read` | Trả về phần thân JSON chính xác mà trình đánh giá sẽ nhận được cho phiên này, được phục vụ dưới dạng tệp đính kèm có thể tải xuống có tên `session-.json`. Hữu ích để phát lại các phiên sản xuất thông qua `agenteye-evaluator` để kiểm tra ngoại tuyến. Các byte giống hệt với những gì quy trình trình đánh giá gửi. | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | Xếp hàng đợi một đánh giá tươi cho một phiên; chạy cho dù có đánh giá trước đó hay không. Kết quả mới được **thêm vào** dòng thời gian đánh giá của phiên thay vì ghi đè lên kết quả trước đó, vì vậy các điểm số trước vẫn có thể nhìn thấy dưới dạng lịch sử. Trả về `202` khi xếp hàng đợi, `404` cho một phiên không rõ, `409` nếu một đánh giá đã đang hoạt động. Sử dụng sau khi triển khai trình đánh giá mới hoặc cho các phiên không bao giờ phát ra `agent_end`. | -### Lọc theo phạm vi điểm: `score_filters` +### Lọc theo phạm vi điểm số: `score_filters` -`GET /evaluations` chấp nhận tham số `score_filters` tùy chọn thu hẹp kết quả theo các giá trị số bên trong đối tượng `scores`. Tham số là danh sách được phân tách bằng dấu phẩy của các mục `key:min..max`; bất kỳ ràng buộc nào cũng có thể được bỏ qua. Các mục múi hợp với AND logic. Các hàng trong đó khóa được đặt tên bị thiếu hoặc không phải số được loại trừ. Một yêu cầu có thể mang tối đa 20 mục lọc; vượt quá điều đó trả về HTTP 400. +`GET /evaluations` chấp nhận một tham số `score_filters` tùy chọn giới hạn kết quả theo giá trị số bên trong đối tượng `scores`. Tham số là danh sách được phân tách bằng dấu phẩy của các mục `key:min..max`; có thể bỏ qua cả hai giới hạn. Nhiều mục kết hợp với AND logic. Hàng nơi khóa đặt tên vắng mặt hoặc không phải số được loại trừ. Yêu cầu có thể mang tối đa 20 mục bộ lọc; vượt quá giá trị đó trả về HTTP 400. Ví dụ: ```text @@ -216,85 +215,85 @@ GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. Mỗi đối tượng phản hồi `/evaluations` có các trường này: -| Trường | Kiểu | Ghi chú | +| Trường | Loại | Ghi chú | |---|---|---| -| `evaluation_id` | string (UUID) | Định danh chính tắc cho đánh giá terminal này. Mỗi đánh giá terminal nhận được một UUID mới; một phiên có thể giữ nhiều. | -| `id` | string (UUID) | Bí danh tương thích ngược mang cùng giá trị như `evaluation_id`. | -| `session_id` | string | Phiên này đánh giá chạy lại. Một phiên có thể có nhiều đánh giá trong dòng thời gian. | -| `agent_id` | string | Xác định agent tạo ra phiên. | -| `environment` | string | Nhãn môi trường được sao chép từ phiên. | +| `evaluation_id` | chuỗi (UUID) | Định danh chính tắc cho đánh giá cuối cùng này. Mỗi đánh giá cuối cùng nhận được một UUID mới; một phiên duy nhất có thể giữ nhiều. | +| `id` | chuỗi (UUID) | Bí danh tương thích ngược mang cùng giá trị với `evaluation_id`. | +| `session_id` | chuỗi | Phiên mà đánh giá này chạy. Một phiên có thể có nhiều đánh giá trong dòng thời gian. | +| `agent_id` | chuỗi | Định danh agent tạo ra phiên. | +| `environment` | chuỗi | Nhãn môi trường được sao chép từ phiên. | | `status` | enum | Một trong `"done"`, `"error"`, `"timeout"`. | -| `scores` | object \| null | Điểm số được trả về bởi bộ đánh giá của bạn. | -| `reasoning` | object \| null | Bản đồ lý do tùy chọn trên mỗi điểm được trả về bởi bộ đánh giá của bạn. Các khóa thường phản ánh những cái trong `scores`. Bảng điều khiển hiển thị mỗi mục dưới thanh điểm số của nó. | -| `summary` | string \| null | Tóm tắt toàn cảnh tùy chọn một đoạn được trả về bởi bộ đánh giá của bạn. Bảng điều khiển hiển thị điều này trên phân tích per-score làm tiêu đề của đánh giá. | -| `error` | string \| null | Được điền trên `"error"` / `"timeout"` chỉ. | -| `attempt_count` | integer | Số nỗ lực gửi (≥ 1). | -| `duration_ms` | integer \| null | Thời lượng của nỗ lực cuối cùng. | -| `completed_at` | string (ISO 8601 UTC) | Khi kết quả terminal được ghi lại. Kết quả được sắp xếp theo `completed_at` (mới nhất trước). | -| `created_at` | string (ISO 8601 UTC) | Mang cùng dấu thời gian với `completed_at` (ngữ nghĩa ghi một lần). | +| `scores` | đối tượng \| null | Điểm số được trả về bởi trình đánh giá của bạn. | +| `reasoning` | đối tượng \| null | Bản đồ biện minh theo điểm số tùy chọn được trả về bởi trình đánh giá của bạn. Các khóa thường phản ánh những khóa trong `scores`. Bảng điều khiển hiển thị mỗi mục dưới thanh điểm của nó. | +| `summary` | chuỗi \| null | Tóm tắt đoạn một toàn cầu tùy chọn được trả về bởi trình đánh giá của bạn. Bảng điều khiển hiển thị điều này ở trên phần phân tích theo điểm số như tiêu đề của đánh giá. | +| `error` | chuỗi \| null | Được điền vào `"error"` / `"timeout"` chỉ. | +| `attempt_count` | số nguyên | Số lần cố gắng gửi (≥ 1). | +| `duration_ms` | số nguyên \| null | Thời lượng của nỗ lực cuối cùng. | +| `completed_at` | chuỗi (ISO 8601 UTC) | Khi kết quả cuối cùng được ghi lại. Kết quả được sắp xếp theo `completed_at` (mới nhất trước). | +| `created_at` | chuỗi (ISO 8601 UTC) | Mang cùng dấu thời gian với `completed_at` (ngữ nghĩa viết một lần). | --- -## Quyền +## Quyền hạn -| Quyền | Cấp quyền | +| Quyền hạn | Cấp phép | |---|---| -| `evaluations:read` | Liệt kê kết quả đánh giá, xem điểm trong bảng điều khiển và tải chỉ số sức khỏe bảng điều khiển. | -| `evaluations:trigger` | Xếp hàng một đánh giá thủ công cho một phiên thông qua `POST /sessions/:session_id/re-evaluate` hoặc nút đánh giá lại của bảng điều khiển. | -| `dashboards:read` | Xem bảng điều khiển đã lưu (cũng cần `evaluations:read` để tải chỉ số của chúng). | +| `evaluations:read` | Liệt kê kết quả đánh giá, xem điểm số trong bảng điều khiển và tải các chỉ số sức khỏe của bảng điều khiển. | +| `evaluations:trigger` | Xếp hàng đợi một đánh giá thủ công cho một phiên thông qua `POST /sessions/:session_id/re-evaluate` hoặc nút đánh giá lại của bảng điều khiển. | +| `dashboards:read` | Xem bảng điều khiển đã lưu (cũng cần `evaluations:read` để tải các chỉ số của họ). | | `dashboards:write` | Tạo và chỉnh sửa bảng điều khiển. | | `dashboards:delete` | Xóa bảng điều khiển. | -Admin bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) tự động nhận những cái này. +Quản trị viên bootstrap (`ADMIN_KEY`, `ADMIN_EMAIL`) tự động nhận được những điều này. --- ## Xem kết quả -- **`/sessions/`**: dòng thời gian sự kiện + thanh bên phải hiển thị điểm số của phiên và bất kỳ lỗi nào từ nỗ lực gửi. Nếu khóa của bạn có `evaluations:trigger`, một nút **đánh giá lại** xuất hiện bên cạnh nút xuất bản, hữu ích cho các phiên không bao giờ phát ra `agent_end` hoặc để làm mới điểm số sau khi triển khai bộ đánh giá mới. Bảng điều khiển thăm dò kết quả mới và cập nhật thanh bên phải khi nó xuất hiện. +- **`/sessions/`**: dòng thời gian sự kiện + cột bên phải hiển thị điểm số của phiên và bất kỳ lỗi nào từ nỗ lực gửi. Nếu khóa của bạn có `evaluations:trigger`, nút **đánh giá lại** sẽ xuất hiện bên cạnh nút xuất, hữu ích cho các phiên không bao giờ phát ra `agent_end` hoặc để làm mới điểm số sau khi triển khai trình đánh giá mới. Bảng điều khiển thăm dò kết quả mới và cập nhật cột bên phải khi nó đáp ứng. - **`/sessions`**: lưới phiên có thể lọc; cột điểm số hiển thị trạng thái đánh giá và điểm số của mỗi phiên một cách nhanh chóng. -- **`/dashboards`**: chế độ xem sức khỏe eval được lưu (xem [Bảng điều khiển](#dashboards) dưới đây). +- **`/dashboards`**: chế độ xem sức khỏe đánh giá đã lưu (xem [Bảng điều khiển](#dashboards) dưới đây). -![Lưới Sessions với viên thuốc trạng thái đánh giá trên mỗi phiên và huy hiệu điểm được mã hóa màu (helpfulness, factuality, tool_efficiency, safety, coherence)](/agenteye/images/sessions-list.png) +![Lưới Phiên với viên thuốc trạng thái đánh giá theo phiên và huy hiệu điểm được mã hóa màu (hữu ích, độ chính xác, tool_efficiency, an toàn, sự gắn kết)](/agenteye/images/sessions-list.png) -*Lưới phiên hiển thị trạng thái đánh giá và điểm số của mỗi lần chạy một cách nhanh chóng; huy hiệu đỏ/hổ phách/xanh làm cho điểm số thấp nổi bật.* +*Lưới phiên hiển thị trạng thái đánh giá và điểm số của mỗi lần chạy một cách nhanh chóng; các huy hiệu đỏ/hổ phách/xanh làm cho điểm số thấp nổi bật.* --- ## Bảng điều khiển -Trang **Dashboards** (`/dashboards`) cho phép bạn lưu một sự kết hợp các bộ lọc đánh giá làm chế độ xem có tên, có thể tái sử dụng và theo dõi cách lát cắt đó của đánh giá đang làm một cách nhanh chóng. Bảng điều khiển được **chia sẻ trên toàn bộ tổ chức của bạn**; mọi người có `dashboards:read` nhìn thấy cùng một bộ. +Trang **Bảng điều khiển** (`/dashboards`) cho phép bạn lưu một kết hợp các bộ lọc đánh giá dưới dạng chế độ xem có tên, có thể tái sử dụng và theo dõi cách lát cắt của các đánh giá đó hoạt động một cách nhanh chóng. Bảng điều khiển được **chia sẻ trên toàn bộ tổ chức của bạn**; mọi người có `dashboards:read` nhìn thấy cùng một tập hợp. Mỗi bảng điều khiển ghim: -- **Bộ lọc**: các điều khiển tương tự như trang phiên: môi trường, trạng thái, agent, cửa sổ thời gian lăn và bộ lọc phạm vi điểm (`key:min..max`). -- **Cấu hình hiển thị**: các khóa điểm để nổi bật, ngưỡng sức khỏe xanh/hổ phách/đỏ, các bảng điều khiển nào để hiển thị và liệu có nên thu gọn thành đánh giá mới nhất trên mỗi phiên. +- **Bộ lọc**: các điều khiển giống như trang phiên: môi trường, trạng thái, agent, cửa sổ thời gian lăn và bộ lọc phạm vi điểm số (`key:min..max`). +- **Cấu hình hiển thị**: các khóa điểm số nào để tính năng, ngưỡng sức khỏe xanh/hổ phách/đỏ, bảng nào để hiển thị và có gập lại để đánh giá gần đây nhất trên mỗi phiên hay không. -Mỗi thẻ hiển thị số lượng phiên phù hợp, phân tích done/error/timeout, trung bình của mỗi điểm nổi bật và một sparkline xu hướng nhỏ. Mở bảng điều khiển hiển thị các bảng điều khiển toàn kích thước; **mở trong phiên** hạ bạn vào trang phiên được lọc trước chính xác lát cắt đó. Chỉ số được tính toán phía máy chủ trên toàn bộ bộ phù hợp (thông qua `GET /evaluations/aggregate`), vì vậy các số chính xác thay vì được lấy mẫu. +Mỗi thẻ hiển thị số phiên phù hợp, phân tích hoàn thành/lỗi/hết thời gian, trung bình của mỗi điểm số được tính năng và biểu đồ xu hướng nhỏ. Mở bảng điều khiển hiển thị các bảng toàn kích thước; **"mở trong phiên"** thả bạn vào trang phiên được lọc sẵn để chính xác lát cắt đó. Các chỉ số được tính toán phía máy chủ trên toàn bộ tập hợp phù hợp (thông qua `GET /evaluations/aggregate`), vì vậy các số chính xác hơn là được lấy mẫu. -![Bảng điều khiển sức khỏe eval với thanh điểm trung bình trên mỗi chiều đánh giá, phân tích tool ok-vs-error, công cụ hàng đầu và xu hướng sự kiện mỗi giờ](/agenteye/images/dashboard-quality.png) +![Bảng điều khiển sức khỏe đánh giá với thanh điểm trung bình cho mỗi chiều đánh giá, phân tích công cụ ok-vs-lỗi, các công cụ hàng đầu và xu hướng sự kiện mỗi giờ](/agenteye/images/dashboard-quality.png) -**Quyền:** xem yêu cầu cả `dashboards:read` và `evaluations:read`; tạo và chỉnh sửa yêu cầu `dashboards:write`; xóa yêu cầu `dashboards:delete`. Admin bootstrap nhận tất cả những cái này tự động. +**Quyền hạn:** xem cần cả `dashboards:read` và `evaluations:read`; tạo và chỉnh sửa cần `dashboards:write`; xóa cần `dashboards:delete`. Quản trị viên bootstrap nhận tất cả những điều này tự động. --- -## Khắc phục sự cố +## Xử lý sự cố -**Phiên tồn tại nhưng không có đánh giá nào được tạo.** Xác nhận `EVALUATOR_ENDPOINT` được đặt trên quy trình máy chủ, máy chủ và bộ đánh giá chia sẻ cùng một giá trị `EVALUATOR_TOKEN` và điểm cuối `/health` của bộ đánh giá có thể truy cập được từ máy chủ. Khi `EVALUATOR_ENDPOINT` chưa được đặt đường dẫn là một no-op. +**Các phiên tồn tại nhưng không có đánh giá nào được tạo.** Xác nhận `EVALUATOR_ENDPOINT` được đặt trên quy trình máy chủ, máy chủ và trình đánh giá chia sẻ giá trị `EVALUATOR_TOKEN` giống nhau và điểm cuối `/health` của trình đánh giá có thể truy cập được từ máy chủ. Với `EVALUATOR_ENDPOINT` không được đặt, quy trình là no-op. -**Các đánh giá đang bay tích lũy.** Truy vấn `GET /evaluation-jobs` để xem hàng đợi đang bay. Kiểm tra `attempt_count`, `next_attempt_at` và `last_error` trên mỗi hàng. Nguyên nhân phổ biến: dịch vụ bộ đánh giá không thể truy cập hoặc trả về 5xx (thử lại với backoff), `EVALUATOR_TOKEN` sai (401 là terminal) hoặc bộ đánh giá không đồng bộ trả về `pending` mãi mãi (xem dưới đây). +**Các đánh giá đang hoạt động chồng chất.** Truy vấn `GET /evaluation-jobs` để xem hàng đợi đang hoạt động. Kiểm tra `attempt_count`, `next_attempt_at` và `last_error` trên mỗi hàng. Nguyên nhân thường gặp: dịch vụ trình đánh giá không thể truy cập hoặc trả về 5xx (thử lại với lùi), `EVALUATOR_TOKEN` sai (401 là cuối cùng) hoặc trình đánh giá không đồng bộ trả về `pending` vô thời hạn (xem bên dưới). -**Phiên hoàn thành nhưng không có đánh giá terminal.** Truy vấn `GET /evaluation-jobs?status=polling`; kết quả vẫn có thể đang bay. Nếu một công việc bị mắc kẹt trong `pending`, máy chủ gặp sự cố khi đạt tới bộ đánh giá; kiểm tra rằng bộ đánh giá đang chạy và `EVALUATOR_TOKEN` khớp. +**Các phiên đã hoàn thành nhưng không có đánh giá cuối cùng.** Truy vấn `GET /evaluation-jobs?status=polling`; kết quả có thể vẫn đang hoạt động. Nếu công việc bị kẹt trong `pending`, máy chủ đang gặp khó khăn khi truy cập trình đánh giá; kiểm tra rằng trình đánh giá đang chạy và `EVALUATOR_TOKEN` khớp. -**`HTTP 401 from evaluator: invalid bearer token`.** `EVALUATOR_TOKEN` trên máy chủ không khớp với giá trị dịch vụ bộ đánh giá được định cấu hình. Chúng phải giống hệt nhau. +**`HTTP 401 from evaluator: invalid bearer token`.** `EVALUATOR_TOKEN` trên máy chủ không khớp với giá trị mà dịch vụ trình đánh giá được cấu hình. Chúng phải giống hệt nhau. -**Bộ đánh giá không đồng bộ trả về `pending` mãi mãi.** Máy chủ thăm dò `GET /evaluate/{job_id}` cho đến khi bộ đánh giá trả về `done` hoặc `error`, hoặc cho đến khi `EVALUATOR_MAX_POLL_DURATION_SECS` (mặc định 1 giờ) hết hạn. Sau khi vượt qua giới hạn, đánh giá được ghi lại là `timeout` và được loại bỏ khỏi hàng đợi đang bay. Nâng cao `EVALUATOR_MAX_POLL_DURATION_SECS` nếu bộ đánh giá của bạn thực sự cần lâu hơn mặc định. +**Trình đánh giá không đồng bộ trả về `pending` mãi mãi.** Máy chủ thăm dò `GET /evaluate/{job_id}` cho đến khi trình đánh giá trả về `done` hoặc `error`, hoặc cho đến khi `EVALUATOR_MAX_POLL_DURATION_SECS` (mặc định 1 h) đã trôi qua. Sau khi giới hạn, đánh giá được ghi lại là `timeout` và được loại bỏ khỏi hàng đợi đang hoạt động. Nâng `EVALUATOR_MAX_POLL_DURATION_SECS` nếu trình đánh giá của bạn hợp pháp cần lâu hơn mặc định. --- -## Các bước tiếp theo +## Bước tiếp theo -- [Kỹ năng agent đánh giá](/vi/agenteye/evaluator-skill): có một agent mã thiết kế các chiều của bạn chống lại các phiên thực tế và xây dựng dịch vụ này cho bạn. -- [Python SDK](/vi/agenteye/python-sdk): phát ra các sự kiện `agent_end` kích hoạt chấm điểm. -- [Khóa API](/vi/agenteye/api-keys): các quyền `evaluations:read` và `evaluations:trigger`. -- [Kiểm toán](/vi/agenteye/audits): tính năng tự động chất lượng khác của Observability, để xem xét dựa trên chính sách. \ No newline at end of file +- [Kỹ năng agent đánh giá](/vi/agenteye/evaluator-skill): có một agent mã hóa thiết kế các chiều của bạn so với các phiên thực và xây dựng dịch vụ này cho bạn. +- [SDK Python](/vi/agenteye/python-sdk): phát ra các sự kiện `agent_end` kích hoạt chấm điểm. +- [Khóa API](/vi/agenteye/api-keys): quyền `evaluations:read` và `evaluations:trigger`. +- [Kiểm tra](/vi/agenteye/audits): tính năng chất lượng tự động khác của Observability, để xem xét dựa trên chính sách. \ No newline at end of file diff --git a/docs/vi/agenteye/evaluations.mdx b/docs/vi/agenteye/evaluations.mdx index c36dab0c..6f10acc0 100644 --- a/docs/vi/agenteye/evaluations.mdx +++ b/docs/vi/agenteye/evaluations.mdx @@ -1,51 +1,51 @@ --- title: "Đánh giá" -description: "Các vấn đề chất lượng được phát hiện ngay bây giờ, thay vì bạn nghe về chúng từ khiếu nại của người dùng." +description: "Các vấn đề về chất lượng được phát hiện ngay bây giờ, thay vì bạn nghe về chúng từ khiếu nại của người dùng." --- -Các vấn đề chất lượng được phát hiện ngay bây giờ, thay vì bạn nghe về chúng từ khiếu nại của người dùng. Kết nối dịch vụ chấm điểm của riêng bạn một lần và Failproof AI Observability tự động đánh giá mọi lần chạy hoàn tất, vì vậy một sự suy giảm trong hữu ích hoặc sự tăng đột biến trong ảo giác sẽ hiển thị trên chính nó, trước khi khách hàng cảm nhận được nó. +Các vấn đề về chất lượng được phát hiện ngay bây giờ, thay vì bạn nghe về chúng từ khiếu nại của người dùng. Kết nối dịch vụ chấm điểm của riêng bạn một lần và Failproof AI Observability sẽ tự động xếp hạng mọi lần chạy hoàn thành, vì vậy sự giảm độ hữu ích hoặc sự tăng đột biến trong các ảo giác sẽ tự hiện lên, trước khi khách hàng cảm nhận được. -![Lưới phiên với cột điểm: mỗi lần chạy mang theo huy hiệu trạng thái đánh giá và huy hiệu có màu mã hữu ích, tính xác thực và hiệu quả công cụ](/agenteye/images/sessions-list.png) +![Lưới Sessions với cột điểm số: mỗi lần chạy có một bảng trạng thái đánh giá và các huy hiệu mã màu cho độ hữu ích, độ chính xác và hiệu quả công cụ](/agenteye/images/sessions-list.png) -*Mỗi lần chạy trên lưới phiên đều có điểm của nó; các huy hiệu đỏ, vàng và xanh làm cho những lần chạy yếu nổi bật mà không cần bạn mở một bảng điểm duy nhất.* +*Mỗi lần chạy trên lưới sessions mang theo điểm số của nó; các huy hiệu đỏ, vàng và xanh làm cho những lần chạy yếu nổi bật mà không cần bạn mở một bản ghi nhật ký nào.* -## Dừng lấy mẫu các lần chạy bằng tay +## Ngừng lấy mẫu các lần chạy bằng tay -Bạn thường kiểm tra một số lần chạy và hy vọng phần còn lại đều ổn. Bây giờ mọi phiên hoàn tất đều được chấm điểm ngay khi hoàn tất, trên các chiều mà bạn quan tâm: hữu ích, hiệu quả công cụ, tính xác thực, an toàn, bất cứ tiêu chuẩn chất lượng nào của bạn. Bạn xác định các khóa điểm; Failproof AI Observability lưu trữ, theo dõi xu hướng và hiển thị bất cứ thứ gì bộ đánh giá của bạn gửi lại. Không có lần chạy nào bị bỏ qua mà không được chấm điểm, và bạn sẽ không còn biết về một sự suy thoái từ một vé hỗ trợ. +Bạn từng kiểm tra một vài lần chạy và hy vọng phần còn lại ổn định. Bây giờ mỗi phiên hoàn thành được chấm điểm ngay khi nó kết thúc, trên các khía cạnh bạn quan tâm: độ hữu ích, hiệu quả công cụ, độ chính xác, an toàn, bất cứ thứ gì là tiêu chí chất lượng của bạn. Bạn xác định các khóa điểm số; Failproof AI Observability lưu trữ, theo dõi xu hướng và hiển thị bất cứ thứ gì công cụ đánh giá của bạn gửi lại. Không có lần chạy nào bị bỏ qua mà không được chấm điểm, và bạn sẽ ngừng tìm hiểu về sự suy giảm từ một vé hỗ trợ. -Điểm được hiển thị trên lưới phiên tại **`//sessions`** (thanh bên → *quan sát* → *phiên*), một cụm huy hiệu trên mỗi hàng. Chỉ muốn những lần chạy không đạt yêu cầu? Lọc lưới theo phạm vi điểm, ví dụ hữu ích dưới 0,5, và kéo lên chính xác những lần chạy đáng đọc. Xem điểm cần quyền `evaluations:read`. +Các điểm số xuất hiện trên lưới sessions tại **`//sessions`** (thanh bên → *observe* → *sessions*), một cụm huy hiệu cho mỗi hàng. Chỉ muốn các lần chạy không đạt yêu cầu? Lọc lưới theo phạm vi điểm số, chẳng hạn độ hữu ích dưới 0,5, và kéo lên chính xác các lần chạy đáng đọc. Xem các điểm số cần quyền `evaluations:read`. -## Xem lý do tại sao một lần chạy được chấm điểm thấp +## Xem tại sao một lần chạy có điểm thấp -Một con số cho bạn biết một lần chạy là yếu; trang phiên cho bạn biết lý do tại sao. Mở bất kỳ lần chạy nào và thanh bên phải dẫn đầu với tóm tắt tiêu đề, sau đó hiển thị một thanh trên mỗi chiều với lý do của bộ đánh giá của bạn dưới mỗi chiều, vì vậy bạn chuyển từ lần chạy này được chấm điểm 0,4 về tính xác thực sang yêu cầu chính xác mà nó sai trong vài giây. +Một con số cho bạn biết một lần chạy là yếu; trang phiên cho bạn biết tại sao. Mở bất kỳ lần chạy nào và thanh bên phải bắt đầu với tóm tắt nổi bật, sau đó hiển thị một thanh cho mỗi khía cạnh với lý do của công cụ đánh giá của bạn dưới mỗi cái, vì vậy bạn chuyển từ "cái này ghi 0,4 về độ chính xác" sang tuyên bố chính xác mà nó ghi sai trong vài giây. -![Thanh bên phải của phiên: tóm tắt đánh giá ở trên, sau đó là các thanh điểm trên mỗi chiều mỗi cái có một dòng lý do, bên cạnh dòng thời gian sự kiện đầy đủ](/agenteye/images/session-detail.png) +![Thanh bên phải của một phiên: tóm tắt đánh giá ở trên cùng, sau đó các thanh điểm số cho mỗi khía cạnh với dòng lý do, bên cạnh dòng thời gian sự kiện đầy đủ](/agenteye/images/session-detail.png) -*Chế độ xem chi tiết phiên: tóm tắt, các thanh điểm trên mỗi chiều và lý do đằng sau mỗi điểm, ngay cạnh dòng thời gian sự kiện của lần chạy.* +*Chế độ xem chi tiết phiên: tóm tắt, các thanh điểm số cho mỗi khía cạnh và lý do đằng sau mỗi điểm số, ngay bên cạnh dòng thời gian sự kiện của lần chạy.* -Đã triển khai một bộ đánh giá sắc sảo hơn, hoặc đang xem một lần chạy gặp sự cố trước khi nó có thể được chấm điểm? Nút **đánh giá lại** (được kiểm soát bởi `evaluations:trigger`) chấm điểm lại phiên tại chỗ và thêm kết quả mới vào dòng thời gian của nó, vì vậy các điểm trước đó vẫn hiển thị dưới dạng lịch sử. Bạn sẽ tìm thấy nó tại **`//sessions/`**. +Đã triển khai một công cụ đánh giá tốt hơn, hoặc đang xem một lần chạy đã bị lỗi trước khi nó có thể được chấm điểm? Nút **re-evaluate** (được kiểm soát bởi `evaluations:trigger`) sẽ chấm điểm lại phiên tại chỗ và thêm kết quả mới vào dòng thời gian của nó, vì vậy các điểm số trước đó vẫn hiển thị dưới dạng lịch sử. Bạn sẽ tìm thấy nó tại **`//sessions/`**. ## Theo dõi xu hướng chất lượng trên toàn bộ đội -Một lần chạy được chấm điểm thấp là tiếng ồn; toàn bộ nhóm trượt là một tín hiệu. Các bảng điều khiển đã lưu biến điểm của bạn thành xu hướng mà bạn có thể theo dõi ngay: trung bình hữu ích tuần này so với tuần trước, trên mỗi đại lý, trên mỗi môi trường. +Một lần chạy có điểm thấp là tiếng ồn; toàn bộ nhóm trượt là một tín hiệu. Các bảng điều khiển đã lưu giữ biến các điểm số của bạn thành một xu hướng bạn có thể theo dõi lướt qua: độ hữu ích trung bình tuần này so với tuần trước, cho mỗi tác nhân, cho mỗi môi trường. -![Bảng điều khiển chất lượng: các thanh điểm trung bình trên mỗi chiều bộ đánh giá cùng với xu hướng theo thời gian](/agenteye/images/dashboard-quality.png) +![Bảng điều khiển chất lượng: các thanh điểm trung bình cho mỗi khía cạnh công cụ đánh giá cùng với xu hướng theo thời gian](/agenteye/images/dashboard-quality.png) -*Một bảng điều khiển chất lượng đã lưu theo dõi xu hướng các khóa điểm mà bạn đặc trưng, vì vậy một sự trôi dạt chậm là rõ ràng lâu trước khi nó trở thành sự cố.* +*Một bảng điều khiển chất lượng đã lưu giữ xu hướng các khóa điểm số bạn nổi bật, vì vậy sự trôi dạt chậm rõ ràng lâu trước khi nó trở thành một sự cố.* -Bảng điều khiển nằm tại **`//dashboards`** (thanh bên → *phân tích* → *bảng điều khiển*), được chia sẻ trên toàn bộ tổ chức của bạn, và mỗi thẻ tổng hợp các phiên phù hợp: có bao nhiêu, trung bình của mỗi điểm đặc trưng, và một dòng xu hướng tia lửa. "Mở trong phiên" đưa bạn trực tiếp vào các lần chạy được lọc trước phía sau bất kỳ số nào. Xem cần `dashboards:read` cộng với `evaluations:read`. +Các bảng điều khiển tồn tại tại **`//dashboards`** (thanh bên → *analyze* → *dashboards*), được chia sẻ trong toàn bộ tổ chức của bạn, và mỗi thẻ tổng hợp các phiên phù hợp: bao nhiêu, giá trị trung bình của mỗi điểm số nổi bật và một dòng xu hướng. "Open in sessions" đưa bạn trực tiếp vào các lần chạy được lọc trước đó phía sau bất kỳ con số nào. Xem cần `dashboards:read` cộng với `evaluations:read`. -## Kết nối một bộ đánh giá một lần +## Kết nối một công cụ đánh giá một lần -Chấm điểm là tùy chọn và vẫn hoàn toàn tắt cho đến khi bạn chỉ Failproof AI Observability vào một công cụ ghi điểm. Bạn thiết lập một dịch vụ HTTP nhỏ (Observability gửi một tham chiếu hoạt động mà bạn có thể sao chép), đặt hai giá trị trên máy chủ của bạn, và mọi lần chạy từ đó trở đi đều được chấm điểm cho bạn. Toàn bộ hướng dẫn, hợp đồng chấm điểm và SDK nằm trong hướng dẫn sâu. +Chấm điểm là tùy chọn và hoàn toàn tắt cho đến khi bạn chỉ cho Failproof AI Observability một người chấm điểm. Bạn thiết lập một dịch vụ HTTP nhỏ (Observability vận chuyển một tham chiếu làm việc bạn có thể sao chép), đặt hai giá trị trên máy chủ của bạn, và mọi lần chạy từ đó trở đi được chấm điểm cho bạn. Toàn bộ hướng dẫn chi tiết, hợp đồng chấm điểm và SDK nằm trong hướng dẫn sâu. -Không chắc chắn những chiều nào đáng chấm điểm ngay từ đầu? [Kỹ năng đại lý đánh giá](/vi/agenteye/evaluator-skill) có đại lý mã hóa của bạn làm điều đó chống lại các phiên của riêng bạn, sau đó xây dựng và triển khai dịch vụ. +Không chắc chắn những khía cạnh nào đáng được chấm điểm ngay từ đầu? [Kỹ năng tác nhân đánh giá](/vi/agenteye/evaluator-skill) có tác nhân mã hóa của bạn làm việc đó dựa trên các phiên của riêng bạn, sau đó xây dựng và triển khai dịch vụ. ## Liên quan -- [Bộ đánh giá](/vi/agenteye/evaluation-suite): kết nối bộ đánh giá của bạn, hợp đồng chấm điểm và SDK. -- [Kỹ năng đại lý đánh giá](/vi/agenteye/evaluator-skill): để đại lý mã hóa chọn các chiều điểm của bạn và xây dựng bộ đánh giá. -- [Phiên](/vi/agenteye/sessions): lưới chạy từng lần nơi xuất hiện điểm. -- [Bảng điều khiển](/vi/agenteye/dashboards): lưu và chia sẻ xu hướng chất lượng trên tổ chức của bạn. -- [Kiểm tra](/vi/agenteye/audits): tính năng chất lượng tự động khác của Observability, để điều tra xuyên phiên. \ No newline at end of file +- [Bộ đánh giá](/vi/agenteye/evaluation-suite): kết nối công cụ đánh giá, hợp đồng chấm điểm và SDK của bạn. +- [Kỹ năng tác nhân đánh giá](/vi/agenteye/evaluator-skill): cho phép một tác nhân mã hóa chọn các khía cạnh điểm số của bạn và xây dựng công cụ đánh giá. +- [Sessions](/vi/agenteye/sessions): lưới run-by-run nơi các điểm số xuất hiện. +- [Bảng điều khiển](/vi/agenteye/dashboards): lưu và chia sẻ xu hướng chất lượng trên toàn bộ tổ chức của bạn. +- [Audits](/vi/agenteye/audits): tính năng chất lượng tự động khác của Observability, dành cho các điều tra xuyên phiên. \ No newline at end of file diff --git a/docs/vi/agenteye/evaluator-skill.mdx b/docs/vi/agenteye/evaluator-skill.mdx index 4b3d0fb2..749ba7d9 100644 --- a/docs/vi/agenteye/evaluator-skill.mdx +++ b/docs/vi/agenteye/evaluator-skill.mdx @@ -1,61 +1,61 @@ --- title: "Kỹ năng Failproof AI Observability Evaluator Agent" -description: "Từ 'Tôi nghĩ agent của chúng tôi đôi khi có vấn đề' đến một dịch vụ scoring được triển khai, với coding agent của bạn vừa quyết định vừa xây dựng." +description: "Từ 'Tôi nghĩ agent của chúng tôi đôi khi không tốt' đến một dịch vụ chấm điểm được triển khai, với agent lập trình của bạn vừa quyết định vừa xây dựng." --- -Từ *"Tôi nghĩ agent của chúng tôi đôi khi có vấn đề"* đến một dịch vụ scoring được triển khai, với coding agent của bạn vừa quyết định vừa xây dựng. **Kỹ năng Failproof AI Observability evaluator** (`agenteye-evaluator`) là một *Agent Skill*: một thư mục nhỏ chứa hướng dẫn mà một coding agent như Claude Code hay Codex có thể tải khi cần. Nó dạy agent cách xác định những chiều chất lượng nào đáng theo dõi cho *agent của bạn*, sau đó viết, kiểm thử và triển khai [dịch vụ evaluator](/vi/agenteye/evaluation-suite) để chấm điểm chúng. +Từ *"Tôi nghĩ agent của chúng tôi đôi khi không tốt"* đến một dịch vụ chấm điểm được triển khai, với agent lập trình của bạn vừa quyết định vừa xây dựng. **Kỹ năng Failproof AI Observability evaluator** (`agenteye-evaluator`) là một *Agent Skill*: một thư mục nhỏ chứa các hướng dẫn mà một agent lập trình như Claude Code hoặc Codex có thể tải theo yêu cầu. Nó dạy cho agent cách xác định những thứ ngách chất lượng nào có giá trị theo dõi cho *agent của bạn*, sau đó viết, kiểm tra và triển khai [dịch vụ evaluator](/vi/agenteye/evaluation-suite) để chấm điểm chúng. -Nó **không** phải là một scorer được lưu trữ, một registry bạn tải lên, hay một hệ thống plugin. Evaluator của bạn vẫn là dịch vụ HTTP riêng trên cơ sở hạ tầng riêng của bạn, chính xác như mô tả trong hướng dẫn [Evaluation suite](/vi/agenteye/evaluation-suite). Kỹ năng này chỉ dạy agent của bạn cách xây dựng nó tốt, vì vậy mọi thứ nó làm, bạn cũng có thể tự làm bằng cách viết cùng một đoạn mã. +Đây **không** phải là một người chấm điểm được lưu trữ, một bộ đăng ký bạn tải lên, hoặc một hệ thống plugin. Evaluator của bạn vẫn là dịch vụ HTTP riêng của bạn trên cơ sở hạ tầng riêng của bạn, chính xác như được mô tả trong hướng dẫn [Evaluation suite](/vi/agenteye/evaluation-suite). Kỹ năng chỉ dạy agent của bạn cách xây dựng nó tốt, vì vậy mọi thứ nó làm, bạn cũng có thể tự làm bằng cách viết cùng một mã. --- -## Phần khó là quyết định cái gì cần chấm điểm +## Phần khó là quyết định những gì cần chấm điểm -Bề mặt SDK rất nhỏ — một decorator và hai model — và agent có thể viết từ [contract](/vi/agenteye/evaluation-suite#http-contract) một mình. Đó không phải là nơi evaluator thất bại. Chúng thất bại vì chúng chấm điểm những thứ sai, và một evaluator chấm những thứ sai thì còn tệ hơn không có gì: nó tạo ra một bảng điều khiển mà mọi người học cách bỏ qua. +Bề mặt SDK rất nhỏ — một decorator và hai model — và một agent có thể viết được từ [hợp đồng](/vi/agenteye/evaluation-suite#http-contract) một mình. Đó không phải là chỗ mà những evaluator thất bại. Chúng thất bại vì chúng chấm điểm những thứ sai, và một evaluator chấm điểm những thứ sai còn tệ hơn không có: nó tạo ra một dashboard mà mọi người học cách bỏ qua. -Vì vậy, hầu hết kỹ năng là phần trước khi bất kỳ mã nào tồn tại. Nó có agent phỏng vấn bạn (*"mô tả một lần chạy diễn ra tốt; bây giờ mô tả một lần chạy diễn ra xấu"*), sau đó kéo các phiên thực tế của bạn qua [`agenteye` CLI](/vi/agenteye/cli) và đọc chúng từ đầu đến cuối. Hai nửa này thường không đồng ý, và khoảng cách chính là điểm: những gì bạn định đo so với những gì transcript của bạn thực sự có thể hỗ trợ. Một chiều chỉ tồn tại nếu nó **có thể tính toán** từ các sự kiện và **phân biệt** — nếu nó chấm 0.9 cho cả lần chạy tốt và lần chạy xấu của bạn, nó không dạy gì cả và sẽ bị loại. +Vì vậy phần lớn kỹ năng là phần trước khi bất kỳ mã nào tồn tại. Nó có agent phỏng vấn bạn (*"mô tả một lần chạy tốt; bây giờ một cái xấu"*), sau đó kéo các phiên thực tế của bạn qua [`agenteye` CLI](/vi/agenteye/cli) và đọc chúng từ đầu đến cuối. Hai nửa này thường không đồng ý, và khoảng cách là điểm: những gì bạn dự định đo lường so với những gì mà các bảng ghi của bạn thực sự có thể hỗ trợ. Một thứ ngách chỉ tồn tại nếu nó **có thể tính toán được** từ các sự kiện và **phân biệt được** — nếu nó chấm 0,9 trên cả lần chạy tốt và xấu của bạn, nó không dạy gì cả và bị cắt. -Kết quả là một đề xuất 2-4 chiều kèm theo lý do, để bạn phê duyệt trước khi bất kỳ dòng nào được viết. +Những gì quay trở lại là một đề xuất 2-4 thứ ngách với lý do kèm theo, để bạn phê duyệt trước khi viết một dòng code. ```mermaid flowchart TD - YOU["bạn: 'Tôi muốn evals cho support bot của tôi'"] --> AGENT["coding agent (Claude Code / Codex)
tải kỹ năng agenteye-evaluator"] - AGENT -->|"phỏng vấn: good vs bad trông như thế nào?"| YOU + YOU["bạn: 'Tôi muốn evals cho support bot của tôi'"] --> AGENT["agent lập trình (Claude Code / Codex)
tải kỹ năng agenteye-evaluator"] + AGENT -->|"phỏng vấn: cái tốt vs xấu trông như thế nào?"| YOU AGENT -->|"agenteye --json sessions / events"| DATA["các phiên thực tế của bạn
những gì thực sự xảy ra"] - DATA --> DIMS["2-4 chiều, bạn phê duyệt"] + DATA --> DIMS["2-4 thứ ngách, bạn phê duyệt"] DIMS --> SVC["dịch vụ evaluator của bạn
agenteye-evaluator SDK"] - SVC --> SCORES["điểm chấm xuất hiện trong bảng điều khiển
và agenteye evals"] + SVC --> SCORES["điểm chấm xuất hiện trong dashboard
và agenteye evals"] ``` --- -## Nó liên quan như thế nào với những phần evaluation khác +## Nó liên quan như thế nào đến các phần đánh giá khác -Bốn tài liệu đề cập đến scoring, và chúng trao quyền cho nhau theo thứ tự: +Bốn tài liệu bao gồm chấm điểm, và chúng chuyển giao cho nhau theo thứ tự: -| Trang | Nó là gì | Tìm đến nó khi | +| Trang | Đó là gì | Sử dụng khi | |---|---|---| -| **[Evaluations](/vi/agenteye/evaluations)** | Tính năng: điểm trên lưới phiên, bảng điều khiển, đánh giá lại | Bạn muốn biết automatic scoring mang lại gì | -| **[Evaluation suite](/vi/agenteye/evaluation-suite)** | HTTP contract, SDK, server env vars | Bạn đang triển khai hoặc gỡ lỗi evaluator | -| **Evaluator skill** (tài liệu này) | Một cửa ngôn ngữ tự nhiên để thiết kế *và* xây dựng scorer | Bạn muốn từ "Tôi muốn evals" đến dịch vụ chạy | -| **[CLI skill](/vi/agenteye/cli-skill)** | Một cửa ngôn ngữ tự nhiên cho `agenteye` CLI | Bạn muốn *đọc* điểm bạn đã có | -| **[Python SDK skill](/vi/agenteye/python-sdk-skill)** | Một cửa ngôn ngữ tự nhiên để instrument agent của bạn | Agent của bạn chưa phát hành phiên — không có gì để chấm điểm | +| **[Evaluations](/vi/agenteye/evaluations)** | Tính năng: điểm trên lưới phiên, dashboard, đánh giá lại | Bạn muốn biết điều gì mà chấm điểm tự động mang lại | +| **[Evaluation suite](/vi/agenteye/evaluation-suite)** | Hợp đồng HTTP, SDK, các biến môi trường máy chủ | Bạn đang triển khai hoặc gỡ lỗi evaluator của riêng bạn | +| **Evaluator skill** (tài liệu này) | Một cửa trước ngôn ngữ tự nhiên về thiết kế *và* xây dựng người chấm điểm | Bạn muốn đi từ "Tôi muốn evals" đến một dịch vụ chạy | +| **[CLI skill](/vi/agenteye/cli-skill)** | Một cửa trước ngôn ngữ tự nhiên trên CLI `agenteye` | Bạn muốn *đọc* những điểm bạn đã có | +| **[Python SDK skill](/vi/agenteye/python-sdk-skill)** | Một cửa trước ngôn ngữ tự nhiên về cấu hình agent của bạn | Agent của bạn chưa phát hành phiên — không có gì để chấm điểm | -### so với CLI skill: xây dựng versus đọc +### so với CLI skill: xây dựng so với đọc -Hai kỹ năng có ý định không trùng lặp, và cài đặt cả hai là thiết lập bình thường — agent chọn giữa chúng dựa trên những gì bạn hỏi: +Hai kỹ năng này được thiết kế cố ý không trùng lặp, và cài đặt cả hai là thiết lập bình thường — agent chọn giữa chúng dựa trên những gì bạn yêu cầu: -- **`agenteye-evaluator`** (tài liệu này) xây dựng thứ *tạo ra* điểm. Công việc của nó kết thúc khi điểm xuất hiện lần đầu tiên. -- **[`agenteye-cli`](/vi/agenteye/cli-skill)** đọc điểm đã tồn tại (`agenteye evals`). *"Chất lượng có giảm tuần này không?"* là câu hỏi của nó, không phải của kỹ năng này. +- **`agenteye-evaluator`** (tài liệu này) xây dựng thứ *tạo ra* điểm. Công việc của nó kết thúc khi điểm chấm xuất hiện lần đầu tiên. +- **[`agenteye-cli`](/vi/agenteye/cli-skill)** đọc các điểm đã tồn tại (`agenteye evals`). *"Chất lượng có giảm tuần này không?"* là câu hỏi của nó, không phải của kỹ năng này. --- ## Điều kiện tiên quyết -1. **`agenteye` CLI được cài đặt và đăng nhập** (`pipx install agenteye`, sau đó `agenteye login`). Kỹ năng dựa vào nó hai lần: để kéo các phiên thực tế nó thiết kế cho, và để xác nhận điểm của bạn xuất hiện ở cuối. Đăng nhập của bạn cần `events:read`, cộng với `evaluations:read` để kiểm tra cuối cùng đó. Giống như CLI skill, nó **không thể** hoàn thành đăng nhập mã một lần qua email cho bạn. -2. **Một nơi cho evaluator ở.** Nó được xây dựng thành một image và chạy như một dịch vụ chạy liên tục, vì vậy nó cần một repo thực, không phải một tệp tạm thời. Các evaluator thường sống trong repo riêng của chúng, tách biệt với agent đang được chấm điểm — kỹ năng tìm kiếm một cái hiện có và hỏi trước khi tạo cái mới. -3. **Wheel SDK `agenteye-evaluator`** — đọc phần tiếp theo trước khi agent của bạn bắt đầu gõ lệnh `pip`. +1. **`agenteye` CLI được cài đặt và đăng nhập** (`pipx install agenteye`, sau đó `agenteye login`). Kỹ năng dựa vào nó hai lần: để kéo các phiên thực tế mà nó thiết kế chống lại, và để xác nhận điểm của bạn chấp hành khi kết thúc. Đăng nhập của bạn cần `events:read`, cộng với `evaluations:read` cho lần kiểm tra cuối cùng đó. Như với CLI skill, nó **không thể** hoàn thành đăng nhập mã một lần gửi qua email cho bạn. +2. **Nơi cho evaluator sống.** Nó được xây dựng thành một image và chạy như một dịch vụ chạy dài hạn, vì vậy nó cần một repo thực sự, không phải tệp tạm thời. Các evaluator thường sống trong repo của riêng chúng, tách biệt từ agent được chấm điểm — kỹ năng tìm kiếm một cái hiện có và hỏi trước khi xây dựng scaffolding cái mới. +3. **Bánh xe SDK `agenteye-evaluator`** — hãy đọc phần tiếp theo trước khi agent của bạn bắt đầu gõ các lệnh `pip`. --- @@ -65,60 +65,59 @@ Kỹ năng được công bố trong bộ sưu tập kỹ năng công khai của **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -Kho lưu trữ là công khai và kỹ năng không cần bất kỳ thông tin xác thực riêng nào — nó chỉ điều khiển `agenteye` CLI với phiên *bạn* đã đăng nhập, và viết mã trong *repo của bạn*. Lưu ý nó được gửi như là một thư mục riêng và **không** nằm bên trong gói `pipx install agenteye`, vì vậy đừng tìm nó ở đó. +Kho lưu trữ là công khai và kỹ năng không cần bất kỳ thông tin xác thực riêng — nó chỉ điều khiển CLI `agenteye` với phiên *bạn* đã đăng nhập, và viết code trong *repo của bạn*. Lưu ý rằng nó được phát hành dưới dạng thư mục riêng của nó và **không** nằm trong gói `pipx install agenteye`, vì vậy đừng tìm nó ở đó. ## Cài đặt kỹ năng -Cách nhanh nhất là CLI [`skills`](https://skills.sh), nó tìm nạp thư mục và đặt nó nơi agent của bạn tìm: +Con đường nhanh nhất là [`skills`](https://skills.sh) CLI, lấy thư mục và thả nó nơi agent của bạn tìm kiếm: ```bash -# Claude Code, dự án này chỉ +# Claude Code, chỉ dự án này npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code # mọi dự án (cài đặt vào ~/.claude/skills/) npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy -# Codex thay vào đó +# Codex thay thế npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` -Sau đó quản lý nó như bất kỳ kỹ năng nào khác: +Sau đó quản lý nó như bất kỳ kỹ năng khác: ```bash -npx skills list -a claude-code # cái gì được cài đặt +npx skills list -a claude-code # những gì được cài đặt npx skills update agenteye-evaluator # kéo phiên bản mới nhất -npx skills remove agenteye-evaluator # xóa nó +npx skills remove agenteye-evaluator # gỡ bỏ nó ``` -Thích cài đặt bằng tay? An Agent Skill chỉ là một thư mục chứa một `SKILL.md` (cộng với các tham chiếu tuỳ chọn), vì vậy sao chép nó cũng hoạt động: +Thích cài đặt bằng tay? Một Agent Skill chỉ là một thư mục chứa `SKILL.md` (cộng với các tham chiếu tùy chọn), vì vậy sao chép nó cũng hoạt động: -- **Claude Code**: đặt thư mục `agenteye-evaluator/` trong `~/.claude/skills/` (mọi dự án) hoặc `/.claude/skills/` (chỉ repo đó). Claude Code tự khám phá nó — xác minh bằng danh sách `/skills`, hoặc chỉ cần hỏi về evals. -- **Codex (OpenAI)**: Codex đọc cùng một `SKILL.md`. `agents/openai.yaml` được đi kèm đặt `allow_implicit_invocation: true`, vì vậy Codex tự chọn kỹ năng khi một tác vụ phù hợp; nếu không hãy gọi nó rõ ràng như `$agenteye-evaluator`. +- **Claude Code**: đặt thư mục `agenteye-evaluator/` trong `~/.claude/skills/` (mọi dự án) hoặc `/.claude/skills/` (chỉ repo đó). Claude Code tự động phát hiện — xác minh với danh sách `/skills`, hoặc chỉ cần yêu cầu evals. +- **Codex (OpenAI)**: Codex đọc cùng `SKILL.md`. `agents/openai.yaml` được gói kèm đặt `allow_implicit_invocation: true`, vì vậy Codex tự động chọn kỹ năng khi một tác vụ phù hợp; nếu không, gọi nó rõ ràng là `$agenteye-evaluator`. --- -## SDK không nằm trên public PyPI công khai +## SDK không nằm trên PyPI công khai > **Cảnh báo:** Đọc điều này trước khi để agent cài đặt SDK. -Kỹ năng là công khai; SDK nó điều khiển thì không. `agenteye-evaluator` được gửi chỉ như một artifact phát hành riêng, và không giống như `agenteye`, tên **chưa được áp dụng trên public PyPI** — vì vậy một `pip install agenteye-evaluator` trần truồng có thể kéo gói của người lạ vào dịch vụ đọc transcript sản xuất của bạn. Đó là một vấn đề chuỗi cung ứng, không phải một lỗi đánh máy. +Kỹ năng là công khai; SDK nó điều khiển không phải. `agenteye-evaluator` chỉ được phát hành dưới dạng tạo phẩm phát hành riêng, và không giống như `agenteye`, tên **không được yêu cầu trên PyPI công khai** — vì vậy một `pip install agenteye-evaluator` trần có thể kéo gói của người lạ vào dịch vụ đọc bản ghi sản xuất của bạn. Đó là một vấn đề chuỗi cung cấp, không phải một lỗi đánh máy. -Kỹ năng biết điều này và thay vào đó hoạt động xuống một cầu thang cài đặt, dừng lại ở bậc đầu tiên áp dụng: nguồn monorepo nếu bạn ở trong repo AgentEye, nếu không là wheel phát hành riêng từ GitHub Releases (cần truy cập), và nếu cái nào không có sẵn nó **dừng lại và cho bạn biết hãy hỏi Failproof AI contact của bạn để lấy wheel** thay vì ứng phó. +Kỹ năng biết điều này và hoạt động xuống một thang cài đặt, dừng lại ở bậc đầu tiên áp dụng: nguồn monorepo nếu bạn ở trong repo AgentEye, nếu không thì bánh xe phát hành riêng từ GitHub Releases (cần truy cập), và nếu không thể tiếp cận được cái nào thì nó **dừng lại và bảo bạn hỏi liên hệ Failproof AI của bạn về bánh xe** thay vì tức thì. -Vì vậy nếu agent của bạn đề xuất một `pip install agenteye-evaluator` trần truồng từ public PyPI, đó là dấu hiệu kỹ năng không bao giờ được tải. Dừng ở đó và kiểm tra nó được cài đặt. +Vì vậy nếu agent của bạn đề xuất một `pip install agenteye-evaluator` trần từ PyPI công khai, đó là dấu hiệu cho thấy kỹ năng không bao giờ được tải. Dừng lại ở đó và kiểm tra xem nó có được cài đặt không. --- -## Những gì bạn có thể hỏi nó +## Những gì bạn có thể yêu cầu nó -Một vòng chuyến thực tế bắt đầu với một yêu cầu mơ hồ và kết thúc bằng một thiết kế được ký duyệt, không phải mã: +Một vòng chuyến thực tế bắt đầu với một yêu cầu mơ hồ và kết thúc bằng một thiết kế được ký phê duyệt, không phải với mã: ```text -bạn ▸ Tôi muốn evals cho support bot của chúng tôi. Tôi nghĩ - nó đôi khi có vấn đề. +bạn ▸ Tôi muốn evals cho support bot của chúng tôi. Tôi nghĩ nó đôi khi không tốt. -agent ▸ Trước khi tôi viết bất cứ thứ gì: mô tả một lần chạy - diễn ra tốt, và một lần chạy diễn ra xấu. +agent ▸ Trước khi tôi viết bất cứ điều gì: mô tả một lần chạy tốt, + và một lần xấu. bạn ▸ Tốt: nó trả lời từ các tài liệu. Xấu: nó bịa chuyện, hoặc từ bỏ và nói "liên hệ hỗ trợ". @@ -126,46 +125,43 @@ bạn ▸ Tốt: nó trả lời từ các tài liệu. Xấu: nó bịa chuy agent ▸ Chạy: agenteye --json sessions --status error --since 7d Đọc 5 phiên, bao gồm hai bạn gọi là xấu. - Lời của bạn nói tính thực tế và sự chối từ. Các transcript - đồng ý về sự chối từ (2 trong 5 kết thúc bằng một tay qua - hỗ trợ, và nó rõ ràng trong model_response.content), nhưng - tính thực tế cần một sự thật mặt đất mà sự kiện của bạn - không mang theo. + Lời của bạn nói tính xác thực và chuyển hướng. Các bản ghi + đồng ý về chuyển hướng (2 trong 5 kết thúc bằng trao đổi hỗ trợ, + và nó rõ ràng trong model_response.content), nhưng tính xác thực + cần một sự thật mặt đất mà sự kiện của bạn không mang theo. - Vì vậy tôi sẽ chấm ba điều: - - deflection quy tắc, rẻ, tách hai lần chạy của bạn - - tool_efficiency quy tắc, bắt vòng lặp lại trong run-004 - - groundedness LLM judge: mỗi yêu cầu trong tài liệu - nó lấy lại đều có trong tài liệu? + Vì vậy tôi sẽ chấm điểm ba thứ: + - chuyển hướng quy tắc, rẻ, phân tách hai lần chạy của bạn + - hiệu quả_công cụ quy tắc, bắt vòng lặp thử lại trong lần chạy-004 + - có căn cứ thẩm phán LLM: là mọi khiếu nại trong tài liệu nó lấy ra? - "factuality" sẽ cần một sự thật mặt đất mà chúng tôi - không có; groundedness là thứ gần nhất mà transcript của - bạn thực sự có thể hỗ trợ. OK với ba tên đó? Đổi tên - sau này sẽ tách lịch sử. + "tính xác thực" sẽ cần sự thật mặt đất mà chúng ta không có; có căn cứ + là thứ gần nhất mà bảng ghi của bạn thực sự có thể hỗ trợ. + Được không ba tên đó? Đổi tên sau sẽ tách lịch sử. -bạn ▸ có +bạn ▸ được -agent ▸ Không có evaluator trong repo này. Tôi có nên tạo một ở - đây, hay bạn có một ở nơi khác? +agent ▸ Không có evaluator trong repo này. Tôi nên xây dựng scaffolding + cái ở đây, hay bạn có cái khác ở nơi khác? ``` -Từ đó nó viết các chiều dựa trên quy tắc trước tiên (miễn phí, tức thì, xác định), kiểm thử chúng với một phiên thực tế bao gồm những cái rỗng và không bao giờ hoàn thành mà làm hỏng các evaluator ngây thơ, và chỉ tìm đến một LLM judge cho chiều chủ quan. Nó biết [giới hạn của dispatcher](/vi/agenteye/evaluation-suite#configuring-the-server) — timeout yêu cầu 30 giây và 8 cuộc gọi đồng thời triển khai toàn diện — vì vậy nếu judge không vừa một cách đáng tin cậy, nó đi không đồng bộ với `JobPending` thay vì để judge của bạn bị hủy và thử lại năm lần với chi phí gấp năm lần. +Từ đó nó viết các thứ ngách dựa trên quy tắc trước (miễn phí, tức thì, xác định), kiểm tra chúng chống lại một phiên thực tế được chụp bao gồm cái trống và không bao giờ hoàn thành khiến các evaluator ngây thơ sập, và chỉ tiếp cận một thẩm phán LLM trên thứ ngách chủ quan. Nó biết [các giới hạn của dispatcher](/vi/agenteye/evaluation-suite#configuring-the-server) — timeout yêu cầu 30s và 8 lệnh gọi đồng thời trên toàn bộ triển khai — vì vậy nếu thẩm phán sẽ không vừa một cách đáng tin cậy, nó sẽ đi không đồng bộ với `JobPending` thay vì để thẩm phán của bạn bị hủy và thử lại năm lần với chi phí năm lần. -Sau đó nó triển khai, đặt hai server env vars, và xác nhận bằng `agenteye --json evals --session-id ` rằng điểm thực sự xuất hiện. Điểm xuất hiện là bằng chứng duy nhất. +Sau đó nó triển khai, đặt hai biến môi trường máy chủ, và xác nhận bằng `agenteye --json evals --session-id ` rằng điểm thực sự chấp hành. Điểm chấp hành là bằng chứng duy nhất. --- -## Những gì cần chú ý +## Những gì cần xem -- **Tên chiều gần như vĩnh viễn.** Các khóa điểm là các chuỗi tuỳ ý và nền tảng xu hướng bất cứ thứ gì bạn gửi, có nghĩa là không có gì hạ lưu sửa một lựa chọn xấu. Đổi tên sau và lịch sử bị tách: các phiên cũ giữ khóa cũ và xu hướng bị ngắt. Đó là lý do tại sao kỹ năng nhận ký duyệt rõ ràng trước khi viết mã — hãy xem xét lời nhắc đó một cách nghiêm túc. -- **Fixture là các transcript sản xuất thực tế.** Thiết kế dựa trên các phiên thực tế có nghĩa là kéo chúng xuống đĩa, và chúng có thể chứa dữ liệu khách hàng. Kỹ năng hỏi trước khi commit chúng vào git; nếu không chắc chắn, giữ `fixtures/` ngoài repo và để mỗi nhà phát triển kéo riêng của họ. -- **Agent viết và triển khai một dịch vụ đọc mọi transcript.** Nó hoạt động như bạn, giới hạn bởi quyền hạn đăng nhập CLI của bạn, nhưng xem xét evaluator như bất kỳ mã nào khác chạm vào dữ liệu sản xuất. +- **Tên thứ ngách gần như là vĩnh viễn.** Khóa chấm điểm là các chuỗi tùy ý và nền tảng xu hướng bất kỳ cái gì bạn gửi, có nghĩa là không có gì hạ lưu sửa một lựa chọn xấu. Đổi tên sau và lịch sử sẽ chia cắt: các phiên cũ giữ khóa cũ và xu hướng bị phá vỡ. Đây là lý do tại sao kỹ năng nhận được phê duyệt rõ ràng trước khi viết mã — lấy dấu nhắc đó nghiêm túc. +- **Fixture là các bản ghi sản xuất thực tế.** Thiết kế chống lại các phiên thực tế có nghĩa là kéo chúng xuống đĩa, và chúng có thể chứa dữ liệu khách hàng. Kỹ năng hỏi trước khi commit chúng vào git; nếu có nghi ngờ, giữ `fixtures/` ngoài repo và để mỗi nhà phát triển kéo của họ. +- **Agent viết và triển khai một dịch vụ đọc mọi bản ghi.** Nó hoạt động như bạn, bị giới hạn bởi quyền của đăng nhập CLI của bạn, nhưng hãy xem xét evaluator như bất kỳ mã nào khác chạm vào dữ liệu sản xuất. --- ## Bước tiếp theo -- **[Evaluation suite](/vi/agenteye/evaluation-suite)**: HTTP contract, SDK, và server env vars mà kỹ năng cấu hình. -- **[Evaluations](/vi/agenteye/evaluations)**: nơi các điểm xuất hiện sau khi chúng xuất hiện. -- **[CLI skill](/vi/agenteye/cli-skill)**: kỹ năng em gái, để đọc kết quả thay vì xây dựng scorer. -- **[CLI](/vi/agenteye/cli)**: tham chiếu lệnh đằng sau dữ liệu phiên mà kỹ năng thiết kế. \ No newline at end of file +- **[Evaluation suite](/vi/agenteye/evaluation-suite)**: hợp đồng HTTP, SDK, và biến môi trường máy chủ mà kỹ năng cấu hình. +- **[Evaluations](/vi/agenteye/evaluations)**: nơi điểm xuất hiện khi chúng chấp hành. +- **[CLI skill](/vi/agenteye/cli-skill)**: kỹ năng anh em, để đọc kết quả thay vì xây dựng người chấm điểm. +- **[CLI](/vi/agenteye/cli)**: tham chiếu lệnh đằng sau dữ liệu phiên mà kỹ năng thiết kế chống lại. \ No newline at end of file diff --git a/docs/vi/agenteye/event-stream.mdx b/docs/vi/agenteye/event-stream.mdx index 22af3ab9..99a0d147 100644 --- a/docs/vi/agenteye/event-stream.mdx +++ b/docs/vi/agenteye/event-stream.mdx @@ -1,50 +1,49 @@ --- title: "Event Stream" -description: "Ngay khi agent của bạn làm gì đó, bạn sẽ thấy nó." +description: "Khoảnh khắc agent của bạn thực hiện hành động gì đó, bạn sẽ thấy nó." --- +Khoảnh khắc agent của bạn thực hiện hành động gì đó, bạn sẽ thấy nó. Event Stream là mạch nhịp trực tiếp của bạn trên mọi agent trong production: không chờ đợi, không phải tìm kiếm trong log, không phải đoán xem điều gì vừa xảy ra. -Ngay khi agent của bạn làm gì đó, bạn sẽ thấy nó. Event Stream là nhịp đập trực tiếp của bạn trên mọi agent trong production: không chờ đợi, không cần grep log, không cần đoán xem vừa xảy ra điều gì. - -![Event Stream trực tiếp: các dòng sự kiện được mã hóa màu sắc hiển thị theo thời gian thực, có thể lọc theo môi trường, agent, phiên, loại sự kiện và tìm kiếm tự do](/agenteye/images/events-stream.png) +![Event Stream trực tiếp: các hàng sự kiện được tô màu, cập nhật theo thời gian thực, có thể lọc theo môi trường, agent, phiên, loại sự kiện và văn bản tự do](/agenteye/images/events-stream.png) *Mọi sự kiện từ mọi agent trong tổ chức của bạn, sự kiện mới nhất trước, cập nhật khi nó xảy ra.* -## Nhịp đập trực tiếp trên mọi agent +## Mạch nhịp trực tiếp trên mọi agent -Khi một agent bắt đầu chạy, gọi một mô hình, kích hoạt một tool, chạy một hook, hoặc gặp lỗi, dòng đó xuất hiện ở đầu stream vào thời điểm nó xảy ra. Nó theo dõi mọi sự kiện trên mọi agent trong tổ chức của bạn, sự kiện mới nhất trước, để bạn luôn có một hình ảnh hiện tại thay vì một hình ảnh cũ. +Khi một agent bắt đầu chạy, gọi một mô hình, kích hoạt một công cụ, chạy một hook, hoặc gặp lỗi, hàng này sẽ xuất hiện ở đầu luồng ngay khi nó xảy ra. Nó theo dõi mọi sự kiện trên mọi agent trong tổ chức của bạn, sự kiện mới nhất trước, để bạn luôn có hình ảnh hiện tại thay vì một hình ảnh cũ. -Điều đó có nghĩa là không cần tail log files trên một máy ở đâu đó, không cần grep trên các máy, không cần ghép các dấu thời gian lại với nhau bằng tay. Bạn mở một trang và bạn đã bắt đầu xem production. +Điều đó có nghĩa là không phải tìm kiếm các tập tin log trên một máy nào đó, không phải tìm kiếm trên các máy, không phải ghép các dấu thời gian lại với nhau bằng tay. Bạn mở một trang và bạn đã đang theo dõi production. -Các dòng được mã hóa màu sắc theo loại, để bạn có thể đọc stream một cách nhanh chóng thay vì phải phân tích từng dòng. Nhìn nhanh, mỗi dòng cho bạn thấy: +Các hàng được tô màu theo loại, để bạn có thể đọc luồng một cách nhanh chóng thay vì phân tích từng dòng. Lập tức, mỗi hàng cho bạn thấy: -- **Loại của nó**, được mã hóa màu sắc: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, và nhiều loại khác. -- **Tóm tắt một dòng** về những gì đã xảy ra, vì vậy bạn hiếm khi cần mở bất cứ điều gì chỉ để hiểu ý chính. -- **Số lượng token** cho bước đó. -- **Huy hiệu tính toán context-window** khi áp dụng, để tăng trưởng prompt và sự nén gần kề được nhìn thấy trước khi chúng gây ra vấn đề. +- **Loại của nó**, được tô màu: `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error`, và nhiều hơn nữa. +- **Tóm tắt một dòng** về những gì đã xảy ra, để bạn hiếm khi cần mở bất kỳ thứ gì chỉ để hiểu được ý chính. +- **Số lượng token** cho bước này. +- **Huy hiệu tình trạng cửa sổ ngữ cảnh** nếu có, để bạn có thể thấy sự tăng trưởng prompt và sự nén sắp tới trước khi nó trở thành vấn đề. -Xem nó trực tiếp có nghĩa là bạn bắt được một deployment xấu, một vòng lặp không kiểm soát, hoặc một lượt lỗi khi nó xảy ra, chứ không phải trong đánh giá log ngày mai. +Theo dõi trực tiếp có nghĩa là bạn bắt được một bản triển khai tồi, một vòng lặp chạy quá mức, hoặc một loạt lỗi khi nó xảy ra, không phải trong bài xem xét log ngày hôm sau. -## Tìm ra run duy nhất quan trọng +## Tìm chính xác cuộc chạy mà bạn cần -Khi có gì đó trông không ổn, bạn không muốn dòng chảy liên tục. Bạn muốn run duy nhất đã bị hỏng. Stream lọc xuống nhanh chóng: theo môi trường, theo agent, theo phiên, theo loại sự kiện, hoặc theo tìm kiếm tự do. +Khi có gì đó không ổn, bạn không muốn toàn bộ luồng dữ liệu. Bạn muốn cuộc chạy duy nhất bị lỗi. Luồng này lọc xuống nhanh chóng: theo môi trường, theo agent, theo phiên, theo loại sự kiện, hoặc theo văn bản tự do. -Lọc theo session id hoặc agent id để theo dõi một run từ sự kiện đầu tiên đến sự kiện cuối cùng. Lọc theo loại sự kiện để cách ly một loại hoạt động duy nhất, ví dụ mọi `error` trên toàn tổ chức trong một chế độ xem. Xếp chồng các bộ lọc để thu hẹp từ "mọi thứ, ở mọi nơi" thành "agent này, trong prod, gặp lỗi" chỉ trong vài cú nhấp chuột, sau đó hành động dựa trên những gì bạn tìm thấy. +Lọc theo session id hoặc agent id để theo dõi một cuộc chạy từ sự kiện đầu tiên đến sự kiện cuối cùng. Lọc theo loại sự kiện để tách riêng một loạt hoạt động, ví dụ mọi `error` trên toàn org trong một chế độ xem. Xếp chồng các bộ lọc để thu hẹp từ "mọi thứ, ở mọi nơi" xuống "agent này, trong prod, có lỗi" chỉ trong vài cú nhấp chuột, sau đó hành động dựa trên những gì bạn tìm thấy. -Tìm kiếm văn bản tự do đi thẳng đến một tin nhắn, tên tool, hoặc id mà bạn đã có trong tay, vì vậy báo cáo khách hàng biến thành run chính xác trong vài giây. +Tìm kiếm văn bản tự do cắt ngay đến một thông báo, tên công cụ, hoặc id mà bạn đã có sẵn, để một báo cáo từ khách hàng biến thành chính xác cuộc chạy đó chỉ trong vài giây. -## Nơi tìm nó +## Nơi tìm thấy nó -Event Stream là trang chủ tổ chức của bạn. Đăng nhập và nó là bề mặt đầu tiên bạn hạ cánh, tại `//`, vì vậy phân loại bắt đầu ngay khi bạn đến. +Event Stream là trang chủ tổ chức của bạn. Đăng nhập và đó là bề mặt đầu tiên bạn đến, tại `//`, để bạn bắt đầu phân loại ngay khi bạn tới. -Phía sau nó, các agent của bạn phát ra các sự kiện thông qua SDK, bộ sưu tập gửi chúng đến máy chủ Failproof AI Observability của bạn, và stream theo dõi chúng khi chúng đến trong cơ sở hạ tầng bạn kiểm soát. Khi bạn muốn chế độ xem tóm tắt thay vì dấu vết thô, các sự kiện của mỗi run sụp đổ thành một dòng duy nhất trên Sessions, chỉ cách một cú nhấp chuột. +Ở phía sau, các agent của bạn phát ra sự kiện thông qua SDK, bộ thu thập gửi chúng đến máy chủ Failproof AI Observability của bạn, và luồng theo dõi chúng khi chúng đến trong cơ sở hạ tầng mà bạn kiểm soát. Khi bạn muốn chế độ xem tổng hợp thay vì dấu vết thô, các sự kiện của mỗi cuộc chạy sẽ thu gọn thành một hàng trên Sessions, chỉ cách một cú nhấp chuột. -Đây là nguồn sự thật thô của tất cả các bề mặt quan sát khác được xây dựng, vì vậy khi một số liệu trông sai ở nơi khác, stream là nơi bạn xác nhận những gì thực sự xảy ra. +Đây là nguồn sự thật thô ban đầu mà mọi bề mặt quan sát khác xây dựng trên đó, vì vậy khi một con số trông không đúng ở nơi khác, luồng này là nơi bạn xác nhận những gì thực sự đã xảy ra. ## Liên quan -- [Sessions](/vi/agenteye/sessions): các sự kiện tương tự tóm tắt thành một dòng cho mỗi run, với một đồ thị thực thi kiểu git. -- [Telemetry](/vi/agenteye/telemetry): những gì các agent của bạn gửi và cách các sự kiện đến stream. +- [Sessions](/vi/agenteye/sessions): cùng các sự kiện được tổng hợp thành một hàng trên mỗi lần chạy, với biểu đồ thực thi kiểu git. +- [Telemetry](/vi/agenteye/telemetry): những gì các agent của bạn gửi và cách các sự kiện đến luồng. - [Error tracking](/vi/agenteye/error-tracking): một bề mặt phân loại cho mọi thứ đã xảy ra sai. -- [Alerts](/vi/agenteye/alerts): biến bất kỳ ngưỡng nào thành quy tắc tìm kiếm. -- [CLI and agents](/vi/agenteye/cli-and-agents): dấu vết trực tiếp tương tự từ terminal của bạn. \ No newline at end of file +- [Alerts](/vi/agenteye/alerts): biến bất kỳ ngưỡng nào thành một quy tắc paging. +- [CLI and agents](/vi/agenteye/cli-and-agents): cùng dấu vết trực tiếp từ terminal của bạn. \ No newline at end of file diff --git a/docs/vi/agenteye/hermes-capture.mdx b/docs/vi/agenteye/hermes-capture.mdx index 645647b2..ec106f57 100644 --- a/docs/vi/agenteye/hermes-capture.mdx +++ b/docs/vi/agenteye/hermes-capture.mdx @@ -1,53 +1,53 @@ --- -title: "Hermes session capture" -description: "Đưa các phiên Hermes gateway của nhóm bạn — Slack, Telegram, CLI và các lần chạy được lên lịch — vào AgentEye dưới dạng các phiên và sự kiện thông thường." +title: "Chụp phiên làm việc Hermes" +description: "Đưa các phiên Hermes gateway của nhóm bạn — Slack, Telegram, CLI và các lần chạy định kỳ — vào AgentEye dưới dạng các phiên và sự kiện thông thường." --- -[Hermes](https://hermes-agent.nousresearch.com) trả lời nhóm bạn từ bất cứ nơi nào họ đã làm việc — Slack, Telegram, CLI, các lần chạy được lên lịch. Hermes session capture đưa tất cả những thứ đó vào AgentEye dưới dạng các phiên và sự kiện thông thường, để trợ lý mà nhóm bạn nói chuyện mỗi ngày có khả năng quan sát giống như các agent mà bạn viết. +[Hermes](https://hermes-agent.nousresearch.com) trả lời nhóm của bạn từ bất cứ nơi nào họ đã làm việc — Slack, Telegram, CLI, các lần chạy định kỳ. Chụp phiên làm việc Hermes đưa tất cả chúng vào AgentEye dưới dạng các phiên và sự kiện thông thường, do đó trợ lý mà nhóm của bạn nói chuyện mỗi ngày có thể quan sát được cũng giống như các agent mà bạn viết. -Một trình thu thập nền nhỏ đọc kho lưu trữ phiên cục bộ của Hermes khi nó được ghi và gửi các phiên tới AgentEye. Nó hoạt động giống như cách [Codex](/vi/agenteye/codex-capture) và [OpenClaw](/vi/agenteye/openclaw-capture) capture, và một trình thu thập có thể chụp nhiều cái cùng một lúc. +Một bộ thu thập nền nhỏ đọc kho phiên làm việc cục bộ của Hermes khi nó được ghi và gửi các phiên đến AgentEye. Nó hoạt động giống như cách [Codex](/vi/agenteye/codex-capture) và [OpenClaw](/vi/agenteye/openclaw-capture) chụp, và một bộ thu thập có thể chụp nhiều cái cùng một lúc. --- ## Nó chụp cái gì -Mọi phiên Hermes trên máy được chụp, bất kể từ kênh nào nó đến. Mỗi cái trở thành một [phiên](/vi/agenteye/sessions) AgentEye; các tin nhắn của người dùng và trợ lý, lệnh gọi công cụ và kết quả công cụ trở thành các [sự kiện](/vi/agenteye/event-stream) phù hợp. +Mọi phiên làm việc Hermes trên máy đều được chụp, bất kể từ kênh nào nó đến. Mỗi một phiên trở thành một [phiên](/vi/agenteye/sessions) AgentEye; các tin nhắn người dùng và trợ lý, cuộc gọi công cụ và kết quả công cụ của nó trở thành các [sự kiện](/vi/agenteye/event-stream) phù hợp. -Kênh mà phiên được bắt đầu từ — Slack, Telegram, CLI, hoặc một lần chạy được lên lịch — được ghi lại trên phiên, để bạn có thể phân biệt chúng và lọc từng cái một lần. Kèm theo đó là mô hình mà phiên chạy trên đó, cuộc trò chuyện và người nó được bắt đầu từ, và, khi một phiên tạo ra phiên khác, liên kết quay lại phiên cha của nó. +Kênh mà phiên bắt đầu từ — Slack, Telegram, CLI hay một lần chạy định kỳ — được ghi lại trên phiên, để bạn có thể phân biệt chúng và lọc từng cái một lúc. Cùng với đó là mô hình mà phiên chạy, cuộc trò chuyện và người mà nó được bắt đầu từ đó, và khi một phiên tạo ra một phiên khác, liên kết trở lại phiên cha của nó. -Các phiên xuất hiện ngay khi Hermes bắt đầu chúng, bất kể có bất cứ điều gì được nói hay không, và câu trả lời của một lượt và các lệnh gọi công cụ của nó vẫn giữ nguyên thứ tự chúng thực sự xảy ra. Khi một phiên kết thúc, bạn cũng sẽ nhận được lý do tại sao nó kết thúc, chi phí của nó và bao nhiêu token nó sử dụng. +Các phiên xuất hiện ngay khi Hermes bắt đầu chúng, bất kể có điều gì được nói hay không, và phản hồi của một lượt và các cuộc gọi công cụ của nó vẫn giữ nguyên thứ tự chúng thực sự xảy ra. Khi một phiên kết thúc, bạn cũng nhận được lý do tại sao nó kết thúc, nó tiêu tốn bao nhiêu và nó sử dụng bao nhiêu token. --- -## Bật nó +## Bật nó lên -Capture bị tắt cho đến khi bạn bật nó. Cài đặt trình thu thập với một khóa API có quyền `events:add` (xem [API keys](/vi/agenteye/api-keys)) và bật Hermes capture: +Chụp bị tắt cho đến khi bạn bật nó. Cài đặt bộ thu thập với một khóa API có quyền `events:add` (xem [API keys](/vi/agenteye/api-keys)) và bật chụp Hermes: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -Điều đó cài đặt trình thu thập, đăng ký nó như một dịch vụ nền và bắt đầu chụp. Xác nhận nó đang chạy: +Điều đó cài đặt bộ thu thập, đăng ký nó như một dịch vụ nền và bắt đầu chụp. Xác nhận rằng nó đang chạy: ```bash agenteye-collector health ``` -Chụp nhiều hơn một agent trên cùng một máy? Thêm cờ của từng cái vào cùng một lệnh — ví dụ `--hermes-enabled --codex-enabled`. +Chụp nhiều hơn một agent trên cùng một máy? Thêm cờ của mỗi cái vào cùng một lệnh — ví dụ `--hermes-enabled --codex-enabled`. -Lần chạy đầu tiên, các phiên Hermes hiện có của bạn được điền lại một lần và hoạt động mới sau đó được truyển trong vòng vài giây. Dữ liệu của Hermes chỉ được đọc — không bao giờ được sửa đổi hoặc xóa — và mỗi tin nhắn được gửi một lần, thậm chí qua các lần khởi động lại. +Lần chạy đầu tiên, các phiên Hermes hiện có của bạn được điền lại một lần và hoạt động mới sau đó truyền phát trong vòng vài giây. Dữ liệu của Hermes chỉ được đọc — không bao giờ được sửa đổi hoặc xóa — và mỗi thông báo được gửi một lần, ngay cả qua các lần khởi động lại. -`health` cũng cho bạn biết liệu mọi thứ mà trình thu thập chụp thực sự đã đến AgentEye hay không. Nếu một lô không thể được gửi, nó được giữ lại và thử lại thay vì bị loại bỏ, và kiểm tra báo cáo không lành mạnh trong khi bất cứ điều gì vẫn còn nợ — vì vậy "lành mạnh" có nghĩa là dữ liệu của bạn đã tới, không chỉ là quá trình còn sống. +`health` cũng cho bạn biết liệu mọi thứ mà bộ thu thập đã chụp có thực sự đến AgentEye hay không. Nếu một lô không thể được gửi, nó sẽ được giữ lại và thử lại thay vì bị loại bỏ, và kiểm tra báo cáo không lành mạnh khi bất cứ thứ gì vẫn còn chưa được giải quyết — vì vậy "lành mạnh" có nghĩa là dữ liệu của bạn đã đến, không chỉ là quá trình còn sống. --- ## Nó xuất hiện ở đâu -Các phiên được chụp xuất hiện trong **Sessions**, và các sự kiện của chúng trong luồng **Events**, giống như bất kỳ agent nào khác mà bạn quan sát — vì vậy [session replay](/vi/agenteye/sessions), [search](/vi/agenteye/queries), [evaluations](/vi/agenteye/evaluations), và [alerts](/vi/agenteye/alerts) đều hoạt động trên chúng. Lọc theo agent Hermes để xem chúng riêng biệt. +Các phiên được chụp xuất hiện trong **Sessions**, và các sự kiện của chúng trong luồng **Events**, giống như bất kỳ agent nào khác mà bạn quan sát — vì vậy [session replay](/vi/agenteye/sessions), [search](/vi/agenteye/queries), [evaluations](/vi/agenteye/evaluations) và [alerts](/vi/agenteye/alerts) đều hoạt động trên chúng. Lọc theo agent Hermes để xem chúng riêng. --- ## Quyền riêng tư -Các phiên Hermes chứa toàn bộ bản ghi — bao gồm đầu ra lệnh, nội dung tệp và bất cứ điều gì mà agent đã đọc hoặc viết — và có thể chứa bí mật. Các phiên được chụp được gửi nguyên trạng, vì vậy chỉ bật capture nơi tập trung nội dung đó trong AgentEye là phù hợp, và cấp cho trình thu thập một khóa phạm vi chỉ `events:add`. Xem [Security](/vi/agenteye/security) để biết dữ liệu của bạn được giữ cách ly như thế nào. \ No newline at end of file +Các phiên Hermes chứa toàn bộ bản ghi — bao gồm đầu ra lệnh, nội dung tệp và bất cứ thứ gì agent đã đọc hoặc viết — và có thể chứa các bí mật. Các phiên được chụp được gửi nguyên trạng, vì vậy chỉ bật chụp nơi tập trung nội dung đó trong AgentEye là thích hợp và cấp cho bộ thu thập một khóa có phạm vi là `events:add` chỉ. Xem [Security](/vi/agenteye/security) để biết cách dữ liệu của bạn được giữ cách ly. \ No newline at end of file diff --git a/docs/vi/agenteye/incidents.mdx b/docs/vi/agenteye/incidents.mdx index e39eec06..1e15fdd1 100644 --- a/docs/vi/agenteye/incidents.mdx +++ b/docs/vi/agenteye/incidents.mdx @@ -1,28 +1,28 @@ --- -title: "Sự Cố" -description: "Khi một cảnh báo phát động, mọi người có thể thấy sự cố đang mở, ai sở hữu nó và những gì đã xảy ra cho đến nay — trên một dòng thời gian được ghi nhận rõ ràng." +title: "Sự cố" +description: "Khi cảnh báo phát động, mọi người có thể thấy sự cố đang mở, ai là người chịu trách nhiệm, và những gì đã xảy ra cho đến nay — trên một dòng thời gian có ghi nhận rõ ràng." --- -Khi một cảnh báo phát động, câu hỏi đầu tiên luôn là "ai đang xử lý?" Sự cố trả lời nó: ngay lập tức khi có vi phạm, mọi người có thể thấy sự cố đang mở, ai sở hữu nó và chính xác những gì đã xảy ra cho đến nay, với một bản ghi được ghi nhận rõ ràng mà bạn có thể chuyển thẳng cho cuộc họp hậu sự. +Khi cảnh báo phát động, câu hỏi đầu tiên luôn là "ai đang xử lý?" Sự cố trả lời điều đó: vào thời điểm có vi phạm, mọi người có thể thấy sự cố đang mở, ai là người chịu trách nhiệm, và chính xác những gì đã xảy ra cho đến nay, với một bản ghi rõ ràng và có ghi nhận mà bạn có thể gửi trực tiếp cho cuộc họp sau sự cố. -![Hộp thư sự cố: thẻ sự cố được liên kết với cảnh báo và được mở thủ công, nhóm theo trạng thái, mỗi thẻ có huy hiệu mức độ nghiêm trọng và người được giao nhiệm vụ](/agenteye/images/incidents.png) -*Hộp thư nhóm các sự cố mở theo trạng thái và lọc theo mức độ nghiêm trọng và người được giao nhiệm vụ, để bạn thấy những gì cần con người bây giờ.* +![Hộp thư Sự cố: các thẻ sự cố được liên kết với cảnh báo và được mở thủ công, nhóm theo trạng thái, mỗi thẻ có một huy hiệu mức độ nghiêm trọng và người được giao việc](/agenteye/images/incidents.png) +*Hộp thư nhóm các sự cố mở theo trạng thái và lọc theo mức độ nghiêm trọng và người được giao việc, để bạn thấy những gì cần con người xử lý ngay bây giờ.* -## Biết ai đang xử lý, trong nháy mắt +## Biết ai đang xử lý, một cách nhanh chóng -Không còn "có ai đang xem cái này không?" trong một luồng trò chuyện. Một vi phạm sẽ tự động mở một sự cố và đặt nó vào hộp thư được chia sẻ, nhóm theo trạng thái. Xác nhận nó và tên bạn được ghi lên, vì vậy phần còn lại của đội biết rằng nó đã được xử lý. Xác nhận được chia sẻ: nhiều nhà điều hành có thể xác nhận cùng một sự cố và mỗi cái được ghi lại riêng, vì vậy một phòng chiến tranh đầy đủ sẽ xuất hiện theo tên thay vì làm hỏng lẫn nhau. Gán một chủ sở hữu cho phân loại và lọc hộp thư theo mức độ nghiêm trọng hoặc người được giao nhiệm vụ để cắt xuống những gì là của bạn. +Không còn "có ai đang xem cái này không?" trong các luồng trò chuyện. Vi phạm mở một sự cố tự động và đưa nó vào hộp thư chung, nhóm theo trạng thái. Xác nhận nó và tên của bạn sẽ được ghi lại, để phần còn lại của nhóm biết nó đã được xử lý. Xác nhận được chia sẻ: nhiều nhà điều hành có thể xác nhận cùng một sự cố và mỗi người được ghi lại riêng biệt, vì vậy một phòng chiến đấu toàn bộ sẽ xuất hiện theo tên thay vì gây trở ngại cho nhau. Giao cho một người chủ sở hữu để phân loại, và lọc hộp thư theo mức độ nghiêm trọng hoặc người được giao việc để thu hẹp xuống những gì của bạn. ## Toàn bộ câu chuyện, trong một dòng thời gian -Khi sự cố kết thúc, bạn đã có bản viết. Mở bất kỳ sự cố nào và bạn sẽ nhận được bằng chứng vi phạm, những người được giao nhiệm vụ và người đăng ký của nó, một luồng bình luận để phối hợp tại chỗ, và một dòng thời gian hoạt động chỉ thêm vào. +Khi sự cố kết thúc, bạn đã có bản viết. Mở bất kỳ sự cố nào và bạn sẽ nhận được bằng chứng vi phạm, những người được giao việc và những người theo dõi của nó, một luồng bình luận để phối hợp tại chỗ, và một dòng thời gian hoạt động chỉ được thêm vào. -![Một chế độ xem chi tiết sự cố: cảnh báo cha và tóm tắt vi phạm, những người được giao nhiệm vụ và người đăng ký, một dòng thời gian hoạt động được ghi nhận, và một luồng bình luận](/agenteye/images/incident-detail.png) -*Mọi thứ đã xảy ra, theo thứ tự, mỗi dòng được ký bởi người đã làm nó.* +![Dạng xem chi tiết sự cố: cảnh báo cha và tóm tắt vi phạm, những người được giao việc và những người theo dõi, một dòng thời gian hoạt động có ghi nhận, và một luồng bình luận](/agenteye/images/incident-detail.png) +*Mọi thứ đã xảy ra, theo thứ tự, mỗi dòng được ký bởi bất cứ ai đã làm điều đó.* -Mỗi hành động (mở, xác nhận, giải quyết, v.v.) được ghi vào dòng thời gian đó và không bao giờ được chỉnh sửa. Mỗi mục được ghi nhận: cho nhà điều hành đã thực hiện nó, theo email, hoặc thành **automated** cho bất kỳ điều gì Failproof AI Observability đã tự làm, như mở sự cố trên vi phạm. Không có gì ẩn danh và không có gì bị mất, vì vậy cuộc họp hậu sự hầu như tự viết. +Mỗi hành động (mở, xác nhận, giải quyết, v.v.) được ghi vào dòng thời gian đó và không bao giờ được chỉnh sửa. Mỗi mục được ghi nhận: cho toán tử người điều hành nó, theo email, hoặc **automated** cho bất cứ điều gì Failproof AI Observability đã làm tự động, như mở sự cố trên vi phạm. Không có gì ẩn danh và không có gì bị mất, vì vậy cuộc họp sau sự cố tự viết ra. -## Sự cố di chuyển như thế nào +## Sự cố diễn tiến như thế nào ```mermaid stateDiagram-v2 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **Mở (firing):** vi phạm mở sự cố và trang một lần trên các kênh của bạn. Các vi phạm lặp lại được gộp vào cùng một sự cố và làm mới bằng chứng của nó thay vì trang bạn nhiều lần. +- **Mở (đang phát):** vi phạm mở sự cố và gửi trang cho các kênh của bạn một lần. Các vi phạm lặp lại gập vào cùng một sự cố và làm mới bằng chứng của nó thay vì gửi trang cho bạn lại lần nữa. - **Đã xác nhận:** một nhà điều hành nhận nó. Nó vẫn mở, và các vi phạm sau này cập nhật bằng chứng một cách yên tĩnh. -- **Đã giải quyết:** một nhà điều hành đóng nó lại. Giải quyết tự động khi điều kiện được xóa đã được lên kế hoạch nhưng chưa được bật, vì vậy một sự cố vẫn mở cho đến khi con người giải quyết nó, điều này giữ cho mọi người trung thực về những gì đã thực sự được xóa. Một sự cố mới có thể mở trên cùng một cảnh báo sau đó. +- **Đã giải quyết:** một nhà điều hành đóng nó. Giải quyết tự động khi điều kiện xóa đi đã được lên kế hoạch nhưng chưa được kích hoạt, vì vậy sự cố vẫn mở cho đến khi con người giải quyết nó, điều này giữ mọi người trung thực về những gì thực sự đã xóa. Một sự cố mới có thể mở trên cùng một cảnh báo sau này. -Một cảnh báo chứa nhiều nhất một sự cố mở tại một thời điểm, vì vậy một quy tắc dao động không thể chôn bạn trong các bản sao. Bạn cũng có thể mở một sự cố bằng tay: một sự cố độc lập cho một cái gì đó không có cảnh báo nào bắt được, hoặc một sự cố được đính kèm vào một cảnh báo hiện có, nếu bạn có `incidents:write`. +Một cảnh báo chứa tối đa một sự cố mở tại một thời điểm, vì vậy một quy tắc nhấp nháy không thể chôn bạn trong các bản sao. Bạn cũng có thể mở một sự cố bằng tay: một sự cố độc lập cho thứ gì đó không có cảnh báo bắt được, hoặc một sự cố được đính kèm vào một cảnh báo hiện có, nếu bạn có `incidents:write`. ## Nơi tìm nó -Các sự cố nằm tại `//incidents`. Xem cần **`incidents:read`**; mở một sự cố thủ công cần **`incidents:write`**; xác nhận, gán, bình luận và giải quyết cần **`incidents:ack`**. Các kóa cũ hơn được cấp `alerts:ack` đã ngừng hoạt động vẫn hoạt động, vì nó được công nhận là `incidents:ack`, vì vậy ca trực của bạn không cần được phát hành lại. +Sự cố nằm tại `//incidents`. Xem cần **`incidents:read`**; mở một sự cố thủ công cần **`incidents:write`**; xác nhận, giao việc, bình luận, và giải quyết cần **`incidents:ack`**. Các khóa cũ hơn cấp `alerts:ack` đã loại bỏ tiếp tục hoạt động, vì nó được công nhận là `incidents:ack`, vì vậy vòng xoay on-call của bạn không cần tái phát hành. ## Liên quan -- [Alerts](/vi/agenteye/alerts): các quy tắc mở những sự cố này khi một ngưỡng vi phạm. -- [Error tracking](/vi/agenteye/error-tracking): xem mỗi lỗi ở một nơi và nâng một lên thành cảnh báo. -- [Audits](/vi/agenteye/audits): nhà phân tích lên lịch tìm thấy những lỗi không có quy tắc nào đang xem. \ No newline at end of file +- [Cảnh báo](/vi/agenteye/alerts): các quy tắc mở những sự cố này khi ngưỡng bị vi phạm. +- [Theo dõi lỗi](/vi/agenteye/error-tracking): xem mọi lỗi ở một nơi và nâng cao một trong số đó thành cảnh báo. +- [Kiểm toán](/vi/agenteye/audits): nhà phân tích được lên lịch tìm thấy các lỗi không có quy tắc nào đang theo dõi. \ No newline at end of file diff --git a/docs/vi/agenteye/observability.mdx b/docs/vi/agenteye/observability.mdx index c5c97598..8d61ff81 100644 --- a/docs/vi/agenteye/observability.mdx +++ b/docs/vi/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- -title: "Observe" -description: "Các bề mặt observe là nơi bạn theo dõi các agent đang làm gì ngay bây giờ và xem chi tiết bất kỳ lần chạy nào." +title: "Quan sát" +description: "Các bề mặt quan sát là nơi bạn theo dõi những gì các agent của bạn đang làm ngay bây giờ và phân tích chi tiết bất kỳ lần chạy nào." --- -Các bề mặt observe là nơi bạn theo dõi các agent đang làm gì ngay bây giờ và xem chi tiết bất kỳ lần chạy nào. Mọi thứ ở đây đều trực tiếp, được giới hạn trong tổ chức của bạn, và có thể lọc theo khoảng thời gian, môi trường, agent và phiên, vì vậy bạn có thể từ "có cái gì đó không ổn" đến chính xác lần chạy đó trong vài giây. +Các bề mặt quan sát là nơi bạn theo dõi những gì các agent của bạn đang làm ngay bây giờ và phân tích chi tiết bất kỳ lần chạy nào. Mọi thứ ở đây đều được trực tiếp, được phạm vi trong tổ chức của bạn, và có thể lọc theo khoảng ngày, môi trường, agent và phiên làm việc, vì vậy bạn có thể đi từ "có gì đó không ổn" đến lần chạy chính xác trong vài giây. -![Event Stream trực tiếp, được mã hóa màu theo loại và có thể lọc theo môi trường, agent và phiên](/agenteye/images/events-stream.png) +![Luồng sự kiện trực tiếp, được mã hóa theo màu sắc theo loại và có thể lọc theo môi trường, agent và phiên làm việc](/agenteye/images/events-stream.png) -Bốn bề mặt, mỗi cái có trang riêng: +Bốn bề mặt, mỗi cái có trang của riêng nó: -- **[Event stream](/vi/agenteye/event-stream)**: đuôi trực tiếp từng bước của mọi lần chạy trên mọi agent, mới nhất trước. Trang chủ tổ chức của bạn và điểm dừng đầu tiên để phân loại. -- **[Sessions and execution graph](/vi/agenteye/sessions)**: những sự kiện đó được gộp lại thành một hàng cho mỗi lần chạy, cộng với một bức tranh kiểu git về cách mỗi lần chạy diễn ra. -- **[Performance metrics](/vi/agenteye/telemetry)**: biểu đồ nhiệt độ trễ và số liệu quan trọng p50/p95/p99 cho các mô hình, công cụ và hook của bạn, vì vậy một loại spike tail nổi bật so với trung vị. -- **[Error tracking](/vi/agenteye/error-tracking)**: một bề mặt phân loại cho mọi thứ đã xảy ra sai, một cú nhấp chuột từ cảnh báo được kích hoạt đến lần chạy bị hỏng. +- **[Luồng sự kiện](/vi/agenteye/event-stream)**: đường dẫu trực tiếp từng bước của mọi lần chạy trên mọi agent, những cái mới nhất trước. Trang chủ của tổ chức bạn và điểm dừng đầu tiên để phân loại. +- **[Phiên làm việc và biểu đồ thực thi](/vi/agenteye/sessions)**: những sự kiện đó được tổng hợp thành một hàng cho mỗi lần chạy, cộng với hình ảnh theo kiểu git về cách mỗi lần chạy diễn ra. +- **[Số liệu hiệu suất](/vi/agenteye/telemetry)**: bản đồ nhiệt độ trễ và chỉ số quan trọng p50/p95/p99 cho các mô hình, công cụ và hook của bạn, vì vậy độ chênh lệch ở đuôi nổi bật so với trung vị. +- **[Theo dõi lỗi](/vi/agenteye/error-tracking)**: một bề mặt phân loại cho mọi thứ đã xảy ra sai, chỉ cần một cú nhấp chuột từ cảnh báo đang kích hoạt đến lần chạy bị lỗi. ## Liên quan -- [Evaluations](/vi/agenteye/evaluations): đánh điểm mỗi lần chạy để có chất lượng. -- [Alerts](/vi/agenteye/alerts): biến bất kỳ ngưỡng nào thành một quy tắc phân trang. -- [Audits](/vi/agenteye/audits): để Failproof AI Observability tìm các mẫu lỗi trên các phiên cho bạn. -- [CLI and agents](/vi/agenteye/cli-and-agents): cùng một khả năng quan sát từ terminal của bạn. \ No newline at end of file +- [Đánh giá](/vi/agenteye/evaluations): tính điểm cho mỗi lần chạy để đánh giá chất lượng. +- [Cảnh báo](/vi/agenteye/alerts): biến bất kỳ ngưỡng nào thành quy tắc thông báo. +- [Kiểm toán](/vi/agenteye/audits): để Failproof AI Observability tìm các mô hình lỗi trên các phiên làm việc cho bạn. +- [CLI và agent](/vi/agenteye/cli-and-agents): khả năng quan sát tương tự từ terminal của bạn. \ No newline at end of file diff --git a/docs/vi/agenteye/openclaw-capture.mdx b/docs/vi/agenteye/openclaw-capture.mdx index 5577fe56..25fd8213 100644 --- a/docs/vi/agenteye/openclaw-capture.mdx +++ b/docs/vi/agenteye/openclaw-capture.mdx @@ -1,32 +1,33 @@ --- -title: "Tính năng ghi lại phiên làm việc OpenClaw" -description: "Đưa các phiên làm việc OpenClaw cục bộ của nhóm của bạn vào AgentEye dưới dạng các phiên và sự kiện thông thường — mà không cần thay đổi cách OpenClaw hoạt động." +--- +title: "Ghi lại phiên làm việc OpenClaw" +description: "Theo dõi các phiên làm việc OpenClaw cục bộ của nhóm bạn vào AgentEye dưới dạng các phiên làm việc và sự kiện thông thường — mà không cần thay đổi cách OpenClaw hoạt động." --- -Nếu nhóm của bạn sử dụng [OpenClaw](https://docs.openclaw.ai), tính năng ghi lại phiên làm việc OpenClaw sẽ đưa những phiên đó vào AgentEye dưới dạng các phiên và sự kiện thông thường, giúp bạn tìm kiếm, phát lại và đánh giá chúng cùng với tất cả những gì khác mà bạn quan sát. Nó bổ sung cho [Python SDK](/vi/agenteye/python-sdk): SDK sẽ theo dõi các agent mà bạn viết, trong khi tính năng này ghi lại công việc OpenClaw mà nhóm của bạn đã thực hiện — mà không cần thay đổi cách họ chạy nó. +Nếu nhóm bạn chạy [OpenClaw](https://docs.openclaw.ai), chức năng ghi lại phiên làm việc OpenClaw sẽ đưa những phiên làm việc đó vào AgentEye dưới dạng các phiên làm việc và sự kiện thông thường, để bạn có thể tìm kiếm, phát lại và đánh giá chúng cùng với mọi thứ khác mà bạn quan sát. Nó bổ sung cho [Python SDK](/vi/agenteye/python-sdk): SDK cấp máy các agent bạn viết, trong khi tính năng này ghi lại công việc OpenClaw mà nhóm bạn đã làm — mà không cần thay đổi cách họ chạy nó. -Một bộ thu thập dữ liệu nền nhỏ đọc các bảng ghi chép phiên làm việc OpenClaw cục bộ khi chúng được ghi và gửi chúng đến AgentEye. Nó hoạt động giống như [Codex capture](/vi/agenteye/codex-capture), và một bộ thu thập có thể ghi lại cả hai cùng một lúc. +Một bộ sưu tập dữ liệu nền nhỏ đọc các bản ghi phiên làm việc OpenClaw cục bộ khi chúng được viết và gửi chúng đến AgentEye. Nó hoạt động giống như [ghi lại Codex](/vi/agenteye/codex-capture), và một bộ sưu tập có thể ghi lại cả hai cùng một lúc. --- -## Điều gì được ghi lại +## Nó ghi lại cái gì -Mọi agent được cấu hình trong cài đặt OpenClaw của một máy đều được ghi lại bởi bộ thu thập của máy đó — không cần cài đặt riêng cho từng agent. +Mọi agent được cấu hình trong thiết lập OpenClaw của một máy sẽ được ghi lại bởi bộ sưu tập của máy đó — không có thiết lập cho từng agent. -Mỗi phiên làm việc OpenClaw trở thành một [phiên](/vi/agenteye/sessions) AgentEye; các tin nhắn của người dùng và trợ lý, lệnh gọi công cụ và kết quả công cụ trở thành những [sự kiện](/vi/agenteye/event-stream) tương ứng. +Mỗi phiên làm việc OpenClaw trở thành một [phiên làm việc](/vi/agenteye/sessions) AgentEye; các tin nhắn người dùng và trợ lý của nó, lệnh gọi công cụ và kết quả công cụ trở thành các [sự kiện](/vi/agenteye/event-stream) phù hợp. --- -## Bật tính năng này +## Bật nó lên -Tính năng ghi lại được tắt cho đến khi bạn bật nó. Cài đặt bộ thu thập với một khóa API có quyền `events:add` (xem [API keys](/vi/agenteye/api-keys)), và bật tính năng ghi lại OpenClaw: +Ghi lại bị tắt cho đến khi bạn bật nó. Cài đặt bộ sưu tập với khóa API có quyền `events:add` (xem [Khóa API](/vi/agenteye/api-keys)) và bật ghi lại OpenClaw: ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -Điều này sẽ cài đặt bộ thu thập, đăng ký nó làm dịch vụ nền, và bắt đầu ghi lại. Xác nhận rằng nó đang chạy: +Điều đó cài đặt bộ sưu tập, đăng ký nó như một dịch vụ nền, và bắt đầu ghi lại. Xác nhận rằng nó đang chạy: ```bash agenteye-collector health @@ -34,16 +35,16 @@ agenteye-collector health Ghi lại nhiều hơn một agent trên cùng một máy? Thêm cờ của mỗi cái vào cùng một lệnh — ví dụ `--openclaw-enabled --codex-enabled`. -Lần chạy đầu tiên, các phiên làm việc OpenClaw hiện có của bạn sẽ được điền lại một lần và sau đó hoạt động mới sẽ truyến phát trong vòng vài giây. Các tệp của chính OpenClaw chỉ được đọc — không bao giờ được sửa đổi, di chuyển hoặc xóa — và mỗi phiên được gửi đúng một lần, thậm chí qua các lần khởi động lại. +Khi chạy lần đầu tiên, các phiên làm việc OpenClaw hiện có của bạn sẽ được điền lại một lần và hoạt động mới sau đó được truyền trong vòng vài giây. Các tệp của OpenClaw chỉ được đọc — không bao giờ được sửa đổi, di chuyển hoặc xóa — và mỗi phiên làm việc được gửi chính xác một lần, ngay cả khi khởi động lại. --- -## Nơi nó xuất hiện +## Nó xuất hiện ở đâu -Các phiên được ghi lại xuất hiện trong **Sessions**, và các sự kiện của chúng trong luồng **Events**, giống như bất kỳ agent nào khác mà bạn quan sát — vì vậy [session replay](/vi/agenteye/sessions), [search](/vi/agenteye/queries), [evaluations](/vi/agenteye/evaluations), và [alerts](/vi/agenteye/alerts) đều hoạt động trên chúng. Lọc theo agent OpenClaw để xem chúng riêng biệt. +Các phiên làm việc được ghi lại xuất hiện trong **Sessions** và các sự kiện của chúng trong luồng **Events**, giống như bất kỳ agent nào khác mà bạn quan sát — do đó [phát lại phiên làm việc](/vi/agenteye/sessions), [tìm kiếm](/vi/agenteye/queries), [đánh giá](/vi/agenteye/evaluations) và [cảnh báo](/vi/agenteye/alerts) đều hoạt động trên chúng. Lọc theo agent OpenClaw để xem chúng riêng biệt. --- -## Bảo mật +## Quyền riêng tư -Các bảng ghi chép OpenClaw chứa toàn bộ phiên — bao gồm đầu ra lệnh, nội dung tệp và bất cứ điều gì mà agent đã đọc hoặc ghi — và có thể chứa các bí mật. Các phiên được ghi lại được gửi như cũ, vì vậy chỉ bật tính năng ghi lại trên các máy và cho các nhóm nơi tập trung nội dung đó trong AgentEye là thích hợp, và cấp cho bộ thu thập một khóa được phạm vi chỉ `events:add`. Xem [Security](/vi/agenteye/security) để biết cách dữ liệu của bạn được giữ riêng biệt. \ No newline at end of file +Các bản ghi OpenClaw chứa toàn bộ phiên làm việc — bao gồm đầu ra lệnh, nội dung tệp và bất cứ thứ gì agent đọc hoặc viết — và có thể chứa các bí mật. Các phiên làm việc được ghi lại được gửi nguyên trạng, do đó chỉ bật ghi lại trên các máy và đối với các nhóm mà việc tập trung nội dung đó trong AgentEye là thích hợp, và cấp cho bộ sưu tập một khóa có phạm vi chỉ `events:add`. Xem [Bảo mật](/vi/agenteye/security) để biết cách dữ liệu của bạn được giữ riêng biệt. \ No newline at end of file diff --git a/docs/vi/agenteye/overview.mdx b/docs/vi/agenteye/overview.mdx index 0092fb58..e48637f2 100644 --- a/docs/vi/agenteye/overview.mdx +++ b/docs/vi/agenteye/overview.mdx @@ -1,25 +1,23 @@ --- +title: "Failproof AI: Quan sát các Agents để phát hiện lỗi" +description: "Failproof AI Observability là một nền tảng tự lưu trữ để quan sát, đánh giá và cải thiện các AI agents của bạn trong môi trường production." --- -title: "Failproof AI: Quan sát Agents để phát hiện lỗi" -description: "Failproof AI Observability là một nền tảng tự lưu trữ để quan sát, đánh giá và cải thiện các AI agents của bạn trong production." ---- - -Failproof AI Observability là một nền tảng tự lưu trữ để quan sát, đánh giá và cải thiện các AI agents của bạn trong production. Nó ghi lại mọi thứ mà agents của bạn thực hiện (mọi lệnh gọi công cụ, yêu cầu mô hình, hook và lỗi), chấm điểm chất lượng của mỗi lần chạy, và phát hiện những lỗi bạn không biết cần tìm kiếm, tất cả trong một bảng điều khiển chạy bên trong cơ sở hạ tầng của riêng bạn. +Failproof AI Observability là một nền tảng tự lưu trữ để quan sát, đánh giá và cải thiện các AI agents của bạn trong môi trường production. Nó ghi lại mọi thứ agents của bạn thực hiện (mọi lệnh gọi công cụ, yêu cầu mô hình, hook và lỗi), đánh giá chất lượng của từng lần chạy, và đưa ra những lỗi bạn không biết cần tìm kiếm, tất cả trong một bảng điều khiển chạy trên cơ sở hạ tầng của riêng bạn. -Nếu bạn triển khai AI agents và mệt mỏi với việc đoán tại sao một lần chạy không thành công, đây là trang để bắt đầu. Nó giải thích những gì Failproof AI Observability mang lại cho bạn và cách các phần ghép lại với nhau, trước khi bạn cài đặt bất cứ thứ gì. +Nếu bạn triển khai AI agents và mệt mỏi vì phải đoán tại sao một lần chạy bị sai, đây là trang để bắt đầu. Nó giải thích những gì Failproof AI Observability cung cấp cho bạn và cách các thành phần hoạt động cùng nhau, trước khi bạn cài đặt bất cứ thứ gì. -> **Failproof AI Observability là một sản phẩm doanh nghiệp từ Failproof AI.** Muốn xem nó hoạt động? Yêu cầu một bản demo: gửi email tới [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +> **Failproof AI Observability là một sản phẩm dành cho doanh nghiệp từ Failproof AI.** Muốn xem nó hoạt động? Yêu cầu bản demo: email [nikita@befailproof.ai](mailto:nikita@befailproof.ai). -![Một phiên Failproof AI Observability được vẽ dưới dạng đồ thị thực thi kiểu git bên cạnh dòng thời gian sự kiện của nó, với phân tích từng lần chạy của các công cụ, mô hình và hook ở cột phải](/agenteye/images/session-detail.png) +![Một phiên Failproof AI Observability được vẽ dưới dạng biểu đồ thực thi kiểu git bên cạnh dòng thời gian sự kiện của nó, với một bảng phân tích từng lần chạy về các công cụ, mô hình và hook ở thanh bên phải](/agenteye/images/session-detail.png) -*Mỗi lần chạy agent được vẽ dưới dạng đồ thị thực thi kiểu git (bên trái) bên cạnh dòng thời gian sự kiện của nó. Các sub-agents song song mỗi cái có làn riêng; cột phải hiển thị chi tiết công cụ, mô hình, hook và chi phí token cho lần chạy.* +*Mỗi lần chạy agent được vẽ dưới dạng biểu đồ thực thi kiểu git (bên trái) bên cạnh dòng thời gian sự kiện của nó. Mỗi sub-agent chạy song song có một làn riêng của nó; thanh bên phải phân tích chi tiết các công cụ, mô hình, hook và chi phí token cho lần chạy.* --- ## Xem nó hoạt động -Hai video ngắn cho thấy hai thứ mà các nhóm thường cần trước tiên: theo dõi một lần chạy và tìm kiếm lỗi tự động. +Hai video ngắn cho thấy hai điều mà các đội thường tìm đến trước tiên: theo dõi một lần chạy và tìm kiếm lỗi tự động.
@@ -31,79 +29,79 @@ Hai video ngắn cho thấy hai thứ mà các nhóm thường cần trước ti
-*Failproof Audit: để Failproof AI Observability khai thác nhật ký của bạn qua các phiên và cho bạn biết cần sửa chữa gì.* +*Failproof Audit: cho phép Failproof AI Observability khai thác nhật ký của bạn trên các phiên và cho bạn biết những gì cần sửa.* --- -## Tại sao các nhóm sử dụng nó +## Tại sao các đội sử dụng nó -- **Xem agent của bạn thực sự đã làm gì.** Mỗi lần chạy trở thành một đồ thị thực thi dễ đọc, kiểu git: công cụ nào chạy song song, sub-agents nào phân nhánh, nơi nó bị trì trệ, và nó đã chi tiêu bao nhiêu. -- **Phát hiện sự suy giảm chất lượng tự động.** Kết nối một dịch vụ chấm điểm nhỏ và Failproof AI Observability chấm điểm mỗi lần chạy hoàn tất, để sự giảm sút về hữu ích hoặc tăng đột biến về ảo giác tự hiển thị. -- **Tìm kiếm lỗi bạn chưa viết quy tắc cho.** Kiểm toán định kỳ khai thác nhật ký của bạn qua các phiên để tìm các cụm lỗi, ngoại lệ về độ trễ, điểm thấp và các lần chạy bị mắc kẹt, sau đó trao cho bạn các phát hiện được xếp hạng, hỗ trợ bằng bằng chứng. -- **Nhận thông báo khi nó quan trọng.** Các quy tắc ngưỡng kích hoạt trên tỷ lệ lỗi, độ trễ, chi phí hoặc điểm đánh giá và mở các sự cố bạn có thể xác nhận, gán và giải quyết. -- **Đặt câu hỏi bằng tiếng Anh thuần túy.** Một trợ lý AI trong bảng điều khiển trả lời những câu hỏi như "chất lượng trong prod tuần này có xu hướng như thế nào?" trên dữ liệu của bạn. Bất kỳ thay đổi nào mà nó thực hiện đều được phê duyệt. -- **Giữ dữ liệu của bạn.** Failproof AI Observability tự lưu trữ: sự kiện, prompt và phân tích ở lại trong cơ sở hạ tầng bạn kiểm soát. +- **Xem agent của bạn thực sự làm được gì.** Mỗi lần chạy trở thành một biểu đồ thực thi kiểu git dễ đọc: những công cụ nào chạy song song, những sub-agent nào rẽ nhánh, nó bị trì hoãn ở đâu và chi phí là bao nhiêu. +- **Phát hiện sự suy giảm chất lượng tự động.** Kết nối một dịch vụ tính điểm nhỏ và Failproof AI Observability sẽ tính điểm cho mỗi lần chạy hoàn tất, vì vậy sự giảm giúp ích hoặc tăng đột ngột trong ảo tưởng sẽ hiển thị tự động. +- **Tìm kiếm lỗi bạn không viết quy tắc cho.** Các cuộc kiểm toán định kỳ khai thác nhật ký của bạn trên các phiên để tìm kiếm các cụm lỗi, các ngoại lệ về độ trễ, điểm thấp và các lần chạy bị kẹt, sau đó cung cấp cho bạn các phát hiện được xếp hạng với bằng chứng. +- **Nhận cảnh báo khi nó quan trọng.** Các quy tắc ngưỡng kích hoạt trên tỷ lệ lỗi, độ trễ, chi phí hoặc điểm evaluator và mở các sự cố bạn có thể xác nhận, gán và giải quyết. +- **Đặt câu hỏi bằng tiếng Anh thường ngày.** Một trợ lý AI trong bảng điều khiển trả lời "chất lượng đang xu hướng như thế nào trong prod tuần này?" trên dữ liệu của riêng bạn. Bất kỳ thay đổi nào mà nó thực hiện đều được phê duyệt. +- **Giữ dữ liệu của bạn.** Failproof AI Observability tự lưu trữ: các sự kiện, lời nhắc và phân tích vẫn nằm trong cơ sở hạ tầng bạn kiểm soát. --- ## Những gì bạn nhận được -Failproof AI Observability được tổ chức xung quanh ba ý tưởng (**observe**, **analyze** và **admin**), phản ánh trong thanh bên trái của bảng điều khiển. +Failproof AI Observability được tổ chức xung quanh ba ý tưởng (**observe**, **analyze** và **admin**), được phản ánh trong thanh bên trái của bảng điều khiển. -**Observe** (sự thật thô của những gì đã xảy ra): +**Observe** (sự thật thô về những gì đã xảy ra): -- **[Luồng sự kiện](/vi/agenteye/event-stream)**: dòng sự kiện trực tiếp, từng bước của mỗi lần chạy (lệnh gọi công cụ, lệnh gọi mô hình, hook, lỗi). -- **[Phiên](/vi/agenteye/sessions)**: những sự kiện đó được tổng hợp thành một hàng trên mỗi lần chạy, mỗi cái sẵn sàng được chấm điểm, với một đồ thị thực thi kiểu git. -- **[Chỉ số hiệu suất](/vi/agenteye/telemetry)**: bản đồ nhiệt độ trễ trên mỗi bề mặt và chỉ số p50/p95/p99 cho mô hình, công cụ và hook, để một tăng đột biến ở phần đuôi nổi bật so với mức trung bình. -- **[Theo dõi lỗi](/vi/agenteye/error-tracking)**: một bề mặt phân loại cho mọi thứ không ổn, chỉ cách một cú nhấp chuột từ một cảnh báo kích hoạt. +- **[Event stream](/vi/agenteye/event-stream)**: dòng trực tiếp, từng bước của mỗi lần chạy (lệnh gọi công cụ, lệnh gọi mô hình, hook, lỗi). +- **[Sessions](/vi/agenteye/sessions)**: những sự kiện đó được tổng hợp thành một hàng cho mỗi lần chạy, mỗi hàng sẵn sàng được tính điểm, với một biểu đồ thực thi kiểu git. +- **[Performance metrics](/vi/agenteye/telemetry)**: bản đồ nhiệt độ trễ trên mỗi bề mặt và các chỉ số p50/p95/p99 cho mô hình, công cụ và hook, vì vậy một đột biến đuôi sẽ nổi bật so với trung vị. +- **[Error tracking](/vi/agenteye/error-tracking)**: một bề mặt phân loại cho mọi thứ đã sai, một bước nhấp chuột từ một cảnh báo được kích hoạt. -![Trang Tools observe: một bản đồ nhiệt độ trễ, một dải phần trăm và một thanh phân phối công cụ trên 24 thùng thời gian](/agenteye/images/tools.png) +![Trang observe Tools: một bản đồ nhiệt độ độ trễ, một dải phân vị và một thanh phân phối công cụ trên 24 thùng thời gian](/agenteye/images/tools.png) -*Mỗi bề mặt observe kết hợp một sparkline và chỉ số p50/p95/p99 với một bản đồ nhiệt độ trễ và một dải phần trăm. Hiển thị ở đây: Công cụ.* +*Mỗi bề mặt observe ghép một đường tính và các chỉ số p50/p95/p99 với một bản đồ nhiệt độ độ trễ và một dải phân vị. Được hiển thị ở đây: Tools.* -**Analyze** (chuyển hoạt động thành câu trả lời): +**Analyze** (biến hoạt động thành câu trả lời): -- **[Truy vấn](/vi/agenteye/queries)** và **[bảng điều khiển](/vi/agenteye/dashboards)**: SQL đã lưu trên sự kiện và đánh giá của bạn, biểu đồ thành các bảng điều khiển được chia sẻ, phạm vi tổ chức. -- **[Đánh giá](/vi/agenteye/evaluations)**: điểm chất lượng do dịch vụ đánh giá của riêng bạn tạo ra, với lý do cho mỗi điểm. -- **[Kiểm toán](/vi/agenteye/audits)**: các cuộc điều tra định kỳ phát hiện các mô hình lỗi qua các phiên. -- **[Cảnh báo](/vi/agenteye/alerts)** và **[sự cố](/vi/agenteye/incidents)**: các quy tắc ngưỡng thông báo cho bạn, cộng với quy trình xử lý sự cố để phân loại chúng. +- **[Queries](/vi/agenteye/queries)** và **[dashboards](/vi/agenteye/dashboards)**: SQL đã lưu trên các sự kiện và đánh giá của bạn, được biểu đồ thành bảng điều khiển được chia sẻ, có phạm vi tổ chức. +- **[Evaluations](/vi/agenteye/evaluations)**: điểm chất lượng được tạo ra bởi dịch vụ evaluator của riêng bạn, với lý do cho từng điểm. +- **[Audits](/vi/agenteye/audits)**: các cuộc điều tra định kỳ đưa ra các mẫu lỗi trên các phiên. +- **[Alerts](/vi/agenteye/alerts)** và **[incidents](/vi/agenteye/incidents)**: các quy tắc ngưỡng để cảnh báo bạn, cộng với một quy trình sự cố để phân loại chúng. -**Giao diện** (truy cập dữ liệu của bạn cách bạn muốn): +**Interfaces** (tiếp cận dữ liệu của bạn theo cách của bạn): -- **[CLI](/vi/agenteye/cli-and-agents)**: điều khiển toàn bộ triển khai của bạn từ terminal hoặc script, và để một agent lập mã làm điều đó cho bạn bằng tiếng Anh thuần túy. -- **[Trợ lý AI](/vi/agenteye/assistant)**: đặt câu hỏi về các agent của bạn bằng tiếng Anh thuần túy, ngay bên trong bảng điều khiển. -- **REST API**: mọi thứ mà bảng điều khiển và CLI làm được hỗ trợ bởi một REST API bạn có thể gọi trực tiếp với một [khóa API](/vi/agenteye/api-keys) được phân phối — nhập sự kiện, truy vấn phiên và đánh giá, và quản lý bảng điều khiển, cảnh báo, kiểm toán, người dùng và khóa, để bạn có thể tích hợp Failproof AI Observability vào công cụ của riêng bạn. +- **[CLI](/vi/agenteye/cli-and-agents)**: điều khiển toàn bộ triển khai của bạn từ terminal hoặc một script, và để một agent mã hóa làm điều đó cho bạn bằng tiếng Anh thường ngày. +- **[AI assistant](/vi/agenteye/assistant)**: đặt câu hỏi về các agents của bạn bằng tiếng Anh thường ngày, ngay bên trong bảng điều khiển. +- **REST API**: mọi thứ mà bảng điều khiển và CLI làm đều được hỗ trợ bởi một REST API bạn có thể gọi trực tiếp bằng một [API key](/vi/agenteye/api-keys) có phạm vi - nhập sự kiện, truy vấn phiên và đánh giá, và quản lý bảng điều khiển, cảnh báo, kiểm toán, người dùng và khóa, vì vậy bạn có thể tích hợp Failproof AI Observability vào các công cụ của riêng bạn. -**Admin** (chạy nó cho nhóm của bạn): +**Admin** (chạy nó cho đội của bạn): -- **[Khóa API](/vi/agenteye/api-keys)**: token được phân phối cho bộ sưu tập, bảng điều khiển và trợ lý. -- **Người dùng**: đăng nhập không mật khẩu, dựa trên email với danh sách cho phép. -- **Cài đặt**: cấu hình trên mỗi tổ chức, bao gồm ghi đè cửa sổ ngữ cảnh mô hình. +- **[API keys](/vi/agenteye/api-keys)**: token có phạm vi cho trình thu thập, bảng điều khiển và trợ lý. +- **Users**: đăng nhập dựa trên email không mật khẩu với một danh sách cho phép. +- **Settings**: cấu hình trên mỗi tổ chức, bao gồm các ghi đè cửa sổ ngữ cảnh mô hình. --- -## Cách các phần ghép lại +## Cách các thành phần hoạt động cùng nhau -Dữ liệu chảy theo một hướng, từ mã agent của bạn tới bảng điều khiển: agent của bạn (thông qua Python SDK) phát hành sự kiện cho agenteye-collector, nó gửi tới server, server phục vụ bảng điều khiển. Hai dịch vụ tùy chọn hoàn thiện nó — một dịch vụ chấm điểm (đánh giá) và một dịch vụ trợ lý AI (chat trong bảng điều khiển). +Dữ liệu chảy theo một hướng, từ mã agent của bạn đến bảng điều khiển: agent của bạn (thông qua SDK Python) phát ra các sự kiện cho agenteye-collector, nó chuyển chúng đến máy chủ, máy chủ cung cấp bảng điều khiển. Hai dịch vụ tùy chọn hoàn thiện nó - một dịch vụ tính điểm (đánh giá) và một dịch vụ trợ lý AI (trò chuyện trong bảng điều khiển). -- **Python SDK**: bạn thêm một vài lệnh gọi `agenteye.event.*` vào agent của bạn; sự kiện được đệm cục bộ. -- **agenteye-collector**: một daemon nhẹ trên mỗi máy agent mà tập hợp các sự kiện và gửi chúng tới server. -- **Server**: nhập sự kiện của bạn, giữ trạng thái hoạt động trong cơ sở dữ liệu của riêng bạn, và phục vụ REST API mà bảng điều khiển, CLI và các tích hợp của riêng bạn đều sử dụng. -- **Bảng điều khiển**: nơi bạn khám phá mọi thứ. -- **Dịch vụ tùy chọn**: một dịch vụ chấm điểm (đánh giá) và một dịch vụ trợ lý AI (chat trong bảng điều khiển). +- **Python SDK**: bạn thêm một vài lệnh gọi `agenteye.event.*` vào agent của mình; các sự kiện được lưu vào bộ đệm cục bộ. +- **agenteye-collector**: một daemon nhẹ trên mỗi máy agent mà tính toán các sự kiện theo lô và chuyển chúng đến máy chủ. +- **Server**: nhập các sự kiện của bạn, giữ trạng thái hoạt động trong các cơ sở dữ liệu của riêng bạn, và cung cấp REST API mà bảng điều khiển, CLI và các tích hợp của riêng bạn đều sử dụng. +- **Dashboard**: nơi bạn khám phá mọi thứ. +- **Optional services**: một dịch vụ tính điểm (đánh giá) và một dịch vụ trợ lý AI (trò chuyện trong bảng điều khiển). -Đối với từ vựng được sử dụng trong toàn bộ tài liệu (*event, session, evaluation, audit, finding, incident*), xem [Khái niệm](/vi/agenteye/concepts). +Đối với từ vựng được sử dụng trong toàn bộ tài liệu (*event, session, evaluation, audit, finding, incident*), xem [Concepts](/vi/agenteye/concepts). --- ## Nhận Failproof AI Observability -Failproof AI Observability là một sản phẩm doanh nghiệp từ Failproof AI, và nó hoạt động cùng với Failproof AI Enforcement — sản phẩm chính sách và guardrail — dưới thương hiệu Failproof AI. Nó chạy hoàn toàn trong môi trường của riêng bạn. Nếu bạn chưa có quyền truy cập vào các gói, hãy yêu cầu một bản demo và chúng tôi sẽ thiết lập cho bạn: gửi email tới [nikita@befailproof.ai](mailto:nikita@befailproof.ai). +Failproof AI Observability là một sản phẩm dành cho doanh nghiệp từ Failproof AI, và nó hoạt động cùng với Failproof AI Enforcement — sản phẩm chính sách và guardrail — dưới thương hiệu Failproof AI. Nó chạy hoàn toàn trong môi trường của riêng bạn. Nếu bạn chưa có quyền truy cập vào các gói, hãy yêu cầu bản demo và chúng tôi sẽ giúp bạn thiết lập: email [nikita@befailproof.ai](mailto:nikita@befailproof.ai). --- -## Bước tiếp theo +## Các bước tiếp theo -- [Khái niệm](/vi/agenteye/concepts): từ vựng Failproof AI Observability trong một nơi. -- [Quan sát](/vi/agenteye/observability): theo dõi những gì các agent của bạn làm, lần chạy sau lần chạy. -- [Bảo mật](/vi/agenteye/security): cách Failproof AI Observability giữ dữ liệu của bạn được cô lập và dưới sự kiểm soát của bạn. \ No newline at end of file +- [Concepts](/vi/agenteye/concepts): từ vựng Failproof AI Observability trong một nơi. +- [Observability](/vi/agenteye/observability): theo dõi những gì các agents của bạn làm, từng lần chạy. +- [Security](/vi/agenteye/security): cách Failproof AI Observability giữ dữ liệu của bạn cô lập và trong sự kiểm soát của bạn. \ No newline at end of file diff --git a/docs/vi/agenteye/python-sdk-skill.mdx b/docs/vi/agenteye/python-sdk-skill.mdx index acc33404..87b77a28 100644 --- a/docs/vi/agenteye/python-sdk-skill.mdx +++ b/docs/vi/agenteye/python-sdk-skill.mdx @@ -1,131 +1,131 @@ --- -title: "Failproof AI Observability Python SDK Agent Skill" -description: "Go from an uninstrumented agent to events you can see, with your coding agent finding the instrumentation points, writing them, and proving they landed." +title: "Kỹ năng Python SDK Agent cho Failproof AI Observability" +description: "Từ một agent không có instrumentation đến những sự kiện bạn có thể thấy được, với agent coding của bạn tìm ra các điểm instrumentation, viết chúng và chứng minh chúng đã được triển khai." --- -Hãy bảo công cụ code agent của bạn *"add Failproof AI Observability to this agent"* và để nó đọc vòng lặp của bạn, tìm ra nơi cần thêm instrumentation, viết nó, và xác minh các sự kiện trước khi hoàn thành công việc. +Hãy bảo agent coding của bạn *"thêm Failproof AI Observability vào agent này"* và để nó đọc vòng lặp của bạn, tìm ra nơi instrumentation cần thiết, viết chúng và xác minh các sự kiện trước khi hoàn thành công việc. -**Python SDK skill** (`agenteye-python-sdk`) là một *Agent Skill*: một thư mục chứa hướng dẫn mà công cụ code agent như Claude Code hoặc Codex tải theo yêu cầu khi một tác vụ phù hợp với nó. Nó dạy agent cách sử dụng [Python SDK](/vi/agenteye/python-sdk) — nó không phải là một thư viện, và nó không thay đổi bất cứ điều gì về cách SDK hoạt động. +**Kỹ năng Python SDK** (`agenteye-python-sdk`) là một *Agent Skill*: một thư mục hướng dẫn mà agent coding như Claude Code hoặc Codex tải theo yêu cầu khi một tác vụ phù hợp với nó. Nó dạy agent cách sử dụng [Python SDK](/vi/agenteye/python-sdk) — đây không phải là một thư viện và nó không thay đổi gì về cách SDK hoạt động. -## Instrumentation dễ viết nhưng dễ sai một cách câm lặng +## Instrumentation dễ viết nhưng cũng dễ sai một cách âm thầm -SDK rất nhỏ: mười ba phương thức sự kiện, tất cả đều chỉ nhận tham số theo từ khóa. Công cụ code agent có thể đọc tài liệu tham khảo [Python SDK](/vi/agenteye/python-sdk) và tạo ra instrumentation hợp lý trong một phút. +SDK rất nhỏ: mười ba phương thức sự kiện, tất cả chỉ dùng keyword. Agent coding có thể đọc tài liệu tham khảo [Python SDK](/vi/agenteye/python-sdk) và tạo ra instrumentation hợp lý trong vòng một phút. -Vấn đề là SDK này không phát sinh lỗi khi bạn làm sai, và instrumentation sai trông giống hệt như instrumentation đúng cho đến khi ai đó mở bảng điều khiển và thấy nó trống rỗng. Những lỗi tốn thời gian thực tế đều là những im lặng: +Vấn đề là SDK này không báo lỗi khi bạn làm sai, và instrumentation sai trông giống hệt như instrumentation đúng cho đến khi ai đó mở dashboard và thấy nó trống rỗng. Những sai lầm tốn thời gian thực tế đều là những im lặng: -| Lỗi | Bạn thấy gì | +| Sai lầm | Bạn thấy | |---|---| -| Không có `agent_start` | Mọi sự kiện được ghi nhận. Không có phiên làm việc. | -| Môi trường không bao giờ được thiết lập | Mọi thứ hoạt động, được lưu dưới `dev`. | -| `outcome="failure"` | Quá trình chạy hiển thị xanh — chỉ `failed`, `error`, `timeout`, `rejected` mới được tính. | -| Tên trường bị gõ sai | Được chấp nhận và lưu trữ như một trường mới. | -| Sự kiện phát ra từ thread pool | Bị loại bỏ âm thầm. | +| Không có `agent_start` | Mỗi sự kiện được ghi nhận. Zero session. | +| Environment không bao giờ được thiết lập | Mọi thứ hoạt động, được phân loại dưới `dev`. | +| `outcome="failure"` | Lần chạy hiển thị xanh — chỉ `failed`, `error`, `timeout`, `rejected` mới được tính. | +| Tên trường bị lỗi chính tả | Được chấp nhận và lưu trữ như một trường mới. | +| Sự kiện được phát ra từ thread pool | Im lặng bị loại bỏ. | -Không có cái nào trong số này phát sinh lỗi. Không cái nào hiển thị trong các bài kiểm tra. Mỗi cái đều nằm trong skill, được nêu ra như một hợp đồng với kiểm tra phát hiện nó. +Không cái nào trong số này được báo lỗi. Không cái nào xuất hiện trong các kiểm tra. Mỗi cái đều có trong kỹ năng, được nêu ra như một hợp đồng với kiểm tra bắt nó. ## Nó làm gì, theo thứ tự -Skill chạy ba bước giống như một kỹ sư cẩn thận sẽ làm: +Kỹ năng này chạy ba bước giống như một kỹ sư cẩn thận sẽ làm: -1. **Lập kế hoạch.** Nó đọc vòng lặp agent của bạn và đặt hai câu hỏi chỉ bạn mới trả lời được: cái gì được coi là một lần chạy (của bạn `session_id`), và những tác nhân nào khác biệt (của bạn `agent_id`). Nó đạt được sự đồng ý trước khi viết mã, vì thay đổi chúng sau này sẽ chia tách lịch sử của bạn và phá vỡ xu hướng. -2. **Viết.** Nó liên kết danh tính một lần mỗi lần chạy thay vì chuyển nó qua mỗi call site, và nó chọn một hình dạng an toàn đồng thời — một chi tiết quan trọng, vì cách tắt hiển nhiên sẽ âm thầm trộn hai lần chạy chồng chéo thành một phiên. -3. **Xác minh.** Nó chạy agent của bạn và đọc các tệp sự kiện kết quả, kiểm tra xem `agent_start` có hiện diện, môi trường có đúng, và một lần chạy có tạo một phiên. +1. **Lên kế hoạch.** Nó đọc vòng lặp agent của bạn và đặt hai câu hỏi chỉ bạn mới có thể trả lời: cái gì được coi là một lần chạy (của bạn `session_id`), và những diễn viên có thể phân biệt được là ai (của bạn `agent_id`). Nó đạt được sự đồng ý trước khi viết mã, vì thay đổi chúng sau sẽ chia nhỏ lịch sử của bạn và phá vỡ xu hướng. +2. **Viết.** Nó ràng buộc nhận dạng một lần cho mỗi lần chạy thay vì luồng nó qua mỗi điểm gọi, và nó chọn một hình dạng an toàn về đồng thời — một chi tiết quan trọng, vì cách tắt hiển nhiên sẽ im lặng trộn hai lần chạy chồng lấp thành một session. +3. **Xác minh.** Nó chạy agent của bạn và đọc các tệp sự kiện kết quả, kiểm tra xem `agent_start` có mặt không, environment có đúng không, và một lần chạy tạo ra một session. -Bước thứ ba là bước mà mọi người bỏ qua. SDK viết các sự kiện vào tệp cục bộ, vì vậy một sự tích hợp hoàn chỉnh có thể được chứng minh trên máy tính xách tay mà không cần máy chủ, không cần khóa API, và không cần mạng — chính vì thế skill nhất định phải thực hiện nó. +Bước thứ ba là bước mà mọi người bỏ qua. SDK viết sự kiện vào các tệp cục bộ, vì vậy một tích hợp hoàn chỉnh có thể được chứng minh trên laptop không cần máy chủ, không có khóa API và không có mạng — đó chính xác là lý do tại sao kỹ năng này khăng khăng làm điều đó. -## Nó liên quan như thế nào với các skill khác +## Nó liên quan như thế nào đến các kỹ năng khác -Ba skill, một phân chia sạch sẽ: +Ba kỹ năng, một sự phân chia sạch: -| Skill | Sử dụng khi | Nó chạm vào cái gì | +| Kỹ năng | Sử dụng khi | Nó chạm gì | |---|---|---| -| **Python SDK skill** (trang này) | Bạn muốn agent của bạn *phát ra* telemetry — "add observability", "tại sao agent của tôi không hiện lên?" | Viết mã trong repo của agent. Không đọc gì cả. | -| **[Evaluator skill](/vi/agenteye/evaluator-skill)** | Bạn muốn *đánh điểm* các lần chạy — "chúng ta nên đo lường cái gì?" | Viết mã trong repo của bạn; đọc telemetry | -| **[CLI skill](/vi/agenteye/cli-skill)** | Bạn muốn *đọc* những gì đã xảy ra, hoặc vận hành deployment | Điều khiển CLI như bạn, bao gồm các thay đổi | +| **Kỹ năng Python SDK** (trang này) | Bạn muốn agent của mình *phát ra* dữ liệu đo đạc — "thêm observability", "tại sao agent của tôi không xuất hiện?" | Viết mã trong kho lưu trữ agent. Không đọc gì cả. | +| **[Kỹ năng Evaluator](/vi/agenteye/evaluator-skill)** | Bạn muốn *chấm điểm* các lần chạy — "chúng ta thậm chí nên đo đạc cái gì?" | Viết mã trong kho lưu trữ của bạn; đọc dữ liệu đo đạc | +| **[Kỹ năng CLI](/vi/agenteye/cli-skill)** | Bạn muốn *đọc* những gì đã xảy ra, hoặc vận hành triển khai của bạn | Điều khiển CLI như bạn, bao gồm cả những thay đổi | -Chúng được chuyển giao theo thứ tự đó: skill này làm cho sự kiện chảy, evaluator đánh điểm chúng, CLI đọc chúng lại. Không có gì để đánh điểm và không có gì để đọc cho đến khi agent của bạn phát ra các phiên, vì vậy nếu bạn bắt đầu từ đầu, hãy bắt đầu từ đây. +Chúng bàn giao theo thứ tự đó: kỹ năng này làm cho sự kiện chảy, evaluator chấm điểm chúng, CLI đọc chúng trở lại. Không có gì để đánh giá và không có gì để đọc cho đến khi agent của bạn phát ra các session, vì vậy nếu bạn bắt đầu từ đầu, hãy bắt đầu ở đây. -## Điều kiện tiên quyết +## Yêu cầu tiên quyết -1. **Python 3.10+** và codebase agent bạn muốn đặt instrumentation. -2. **SDK.** Nó được phân phối cho khách hàng dưới dạng wheel riêng tư chứ không phải từ chỉ mục công cộng — onboarding của bạn sẽ bao gồm cách lấy và cài đặt nó. Skill biết đường dẫn cài đặt và sẽ hỏi bạn thay vì đoán nếu nó không thể tìm thấy nó. -3. **Không gì khác.** Không cần đăng nhập bảng điều khiển, không cần khóa API, không cần mạng. Skill xác minh dựa trên các tệp sự kiện mà SDK viết, vì vậy nó có thể hoàn thành và chứng minh công việc của nó ngoại tuyến. +1. **Python 3.10+** và codebase agent mà bạn muốn instrumentation. +2. **SDK.** Nó được phân phối cho khách hàng như một wheel riêng tư thay vì từ một chỉ mục công khai — onboarding của bạn bao gồm cách lấy nó và cài đặt nó. Kỹ năng biết đường dẫn cài đặt và sẽ hỏi bạn thay vì đoán nếu nó không thể tìm thấy nó. +3. **Không gì cả.** Không có đăng nhập dashboard, không có khóa API, không có mạng. Kỹ năng xác minh dựa trên các tệp sự kiện mà SDK viết, vì vậy nó có thể kết thúc và chứng minh công việc của nó ngoại tuyến. -## Lấy nó ở đâu +## Nơi để lấy nó -Skill nằm trong bộ sưu tập công cộng [`FailproofAI/skills`](https://github.com/FailproofAI/skills): +Kỹ năng này nằm trong bộ sưu tập công khai [`FailproofAI/skills`](https://github.com/FailproofAI/skills): ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -Thêm `-g` để cài đặt nó cho mỗi dự án thay vì chỉ dự án hiện tại, và `--copy` nếu môi trường của bạn không hỗ trợ symlink. Đối với Codex, truyền `-a codex`. +Thêm `-g` để cài đặt nó cho mỗi dự án thay vì chỉ dự án hiện tại, và `--copy` nếu môi trường của bạn không theo dõi các symlink. Đối với Codex, chuyển `-a codex`. -## Cài đặt thủ công +## Cài đặt nó bằng tay -Agent Skills là các thư mục chứa `SKILL.md` cộng với các tham chiếu. Nếu bạn không muốn sử dụng trình cài đặt: +Agent Skills là các thư mục chứa `SKILL.md` cộng với các tài liệu tham khảo. Nếu bạn không muốn sử dụng trình cài đặt: -- **Claude Code**: sao chép thư mục `agenteye-python-sdk/` vào `~/.claude/skills/` (mọi dự án) hoặc `/.claude/skills/` (chỉ repo đó). Claude Code tự động phát hiện nó — kiểm tra danh sách `/skills`, hoặc chỉ cần hỏi điều gì phù hợp với nó. -- **Codex**: Codex đọc cùng một `SKILL.md`. `agents/openai.yaml` được đóng gói thiết lập `allow_implicit_invocation: true`, vì vậy nó được tự động chọn khi tác vụ phù hợp; nếu không thì gọi nó là `$agenteye-python-sdk`. +- **Claude Code**: sao chép thư mục `agenteye-python-sdk/` vào `~/.claude/skills/` (mỗi dự án) hoặc `/.claude/skills/` (chỉ kho lưu trữ đó). Claude Code tự động khám phá nó — kiểm tra danh sách `/skills`, hoặc chỉ cần hỏi điều gì phù hợp với nó. +- **Codex**: Codex đọc cùng `SKILL.md`. Tệp `agents/openai.yaml` được đóng gói đặt `allow_implicit_invocation: true`, vì vậy nó được tự động chọn khi một tác vụ phù hợp; nếu không, hãy gọi nó là `$agenteye-python-sdk`. -Chạy agent của bạn **trong repository chứa mã bạn muốn đặt instrumentation** — skill đọc vòng lặp agent của bạn trước khi nó đề xuất bất cứ điều gì. +Chạy agent của bạn **trong kho lưu trữ chứa mã bạn muốn instrumentation** — kỹ năng đọc vòng lặp agent của bạn trước khi nó đề xuất bất cứ điều gì. -## Một phiên trông như thế nào +## Một session trông như thế nào ```text -you ▸ Add Failproof AI Observability to this agent. +bạn ▸ Thêm Failproof AI Observability vào agent này. -agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic - wrapper in llm.py. Two questions before I write anything. +agent ▸ Đọc vòng lặp của bạn — một trình phân phối công cụ trong tools.py, một + wrapper Anthropic trong llm.py. Hai câu hỏi trước khi tôi viết bất cứ điều gì. - What counts as one run? You handle requests concurrently, so I'd - use the request id you already have in ctx.request_id — then a - session here and a request in your logs are the same string. + Cái gì được coi là một lần chạy? Bạn xử lý yêu cầu đồng thời, vì vậy tôi sẽ + sử dụng id yêu cầu bạn đã có trong ctx.request_id — sau đó một + session ở đây và một yêu cầu trong nhật ký của bạn là cùng một chuỗi. - And who are the actors? I see a planner path and a researcher - path. Label them separately, or is that one agent to you? + Và các diễn viên là ai? Tôi thấy một đường dẫn planner và một + đường dẫn researcher. Gắn nhãn chúng riêng biệt, hay đó là một agent đối với bạn? -you ▸ Request id is right. They're one agent, call it "assistant". +bạn ▸ Id yêu cầu là đúng. Họ là một agent, gọi nó là "assistant". -agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and - agent_end bracket handle_request, including the error path. Used - a context-local for identity — your dispatcher runs tools in a - thread pool, and the simpler approach would have mixed concurrent - runs into one session without complaining. +agent ▸ Xong. Đã bao quanh trình phân phối và khách hàng LLM; agent_start và + agent_end ngoặc handle_request, bao gồm cả đường lỗi. Sử dụng + một ngữ cảnh cục bộ cho nhận dạng — trình phân phối của bạn chạy công cụ trong + thread pool, và cách tiếp cận đơn giản hơn sẽ đã trộn những lần chạy đồng thời + thành một session mà không có cảnh báo. - Verified against a real run: 11 events across 4 files — + Xác minh với một lần chạy thực tế: 11 sự kiện trên 4 tệp — agent_start, model_request/response, tool_use/tool_result x3, - agent_end (outcome=success). environment=production, one session - per request, durations paired. + agent_end (outcome=success). environment=production, một session + cho mỗi yêu cầu, thời lượng được ghép nối. - One thing I did NOT do: your worker pool in batch.py submits - straight to the executor, so events from there would be dropped. - Want me to fix those too? + Một điều tôi KHÔNG làm: worker pool của bạn trong batch.py gửi + trực tiếp đến executor, vì vậy sự kiện từ đó sẽ bị loại bỏ. + Bạn muốn tôi sửa những cái đó không? ``` -Mẫu cần lưu ý: nó đọc mã trước khi đề xuất, chỉ hỏi những câu hỏi bạn mới trả lời được, tái sử dụng một id bạn đã có, chọn hình dạng an toàn đồng thời *vì* nó thấy thread pool, và **xác minh bằng cách đọc các sự kiện thực tế** thay vì tuyên bố thành công — rồi cảnh báo về nơi duy nhất nó biết rằng sẽ thất bại âm thầm. +Mẫu để chú ý: nó đã đọc mã trước khi đề xuất, chỉ hỏi những câu hỏi bạn có thể trả lời, tái sử dụng một id bạn đã có, chọn hình dạng an toàn về đồng thời *vì* nó thấy thread pool, và **xác minh bằng cách đọc các sự kiện thực tế** thay vì tuyên bố thành công — sau đó đánh dấu nơi duy nhất mà nó biết sẽ thất bại im lặng. -## Bạn có thể yêu cầu nó làm gì +## Bạn có thể hỏi nó cái gì -- *"Tại sao agent của tôi không hiện lên trên bảng điều khiển?"* → đi theo từng bước: các sự kiện có được viết không, `agent_start` có ở đó không, môi trường có đúng không, collector có đang đọc cùng một nơi không. -- *"Mọi thứ đang hạ cánh dưới dev."* → môi trường không bao giờ được thiết lập, hoặc được đặt lại bởi một lệnh gọi sau. -- *"Thêm theo dõi token."* → tìm trình bao bọc LLM của bạn và ghi lại mô hình, lý do dừng, và cách sử dụng. -- *"Đặt instrumentation cho các sub-agent."* → một phiên, nhãn agent riêng biệt, lồng dưới phần tử cha của chúng. -- *"Viết bài kiểm tra cho instrumentation."* → chỉ SDK vào một thư mục tạm thời và khẳng định các sự kiện nó đã viết. +- *"Tại sao agent của tôi không xuất hiện trên dashboard?"* → đi bộ thang: các sự kiện có được viết không, có `agent_start` không, environment có đúng không, bộ sưu tập có đọc cùng một nơi không. +- *"Mọi thứ đang hạ cánh dưới dev."* → environment không bao giờ được đặt, hoặc được đặt lại bởi một cuộc gọi sau này. +- *"Thêm theo dõi token."* → tìm wrapper LLM của bạn và ghi lại mô hình, lý do dừng lại và sử dụng. +- *"Instrumentation các sub-agent cũng."* → một session, nhãn agent riêng biệt, lồng dưới cha mẹ của chúng. +- *"Viết kiểm tra cho instrumentation."* → chỉ SDK tại một thư mục tạm thời và khẳng định các sự kiện nó viết. -## Điều cần chú ý +## Những gì để chú ý -**Để nó xác minh.** Bước cuối cùng làm cho skill này đáng sử dụng — chạy agent của bạn và đọc các sự kiện lại. Một agent viết instrumentation và dừng lại đã thực hiện nửa dễ dàng, và nửa thất bại âm thầm là nửa kia. +**Hãy để nó xác minh.** Bước cuối cùng làm cho kỹ năng này đáng sử dụng — chạy agent của bạn và đọc các sự kiện trở lại. Một agent viết instrumentation và dừng lại đã làm nửa dễ dàng, và nửa không thất bại im lặng là nửa còn lại. -**Đồng ý tên trước mã.** `session_id` và `agent_id` là các trục mọi bề mặt nhóm theo. Đổi tên chúng sau chia tách lịch sử: các lần chạy cũ giữ các nhãn cũ và xu hướng của bạn sẽ phá vỡ. Skill sẽ hỏi; câu trả lời đáng tiêu tốn một phút suy nghĩ. +**Đồng ý tên trước mã.** `session_id` và `agent_id` là các trục mà mỗi bề mặt nhóm. Đổi tên chúng sau sẽ chia nhỏ lịch sử: các lần chạy cũ giữ các nhãn cũ và xu hướng của bạn sẽ phá vỡ. Kỹ năng sẽ hỏi; câu trả lời đáng một phút suy nghĩ. -**Nếu agent của bạn đề xuất cài đặt SDK từ chỉ mục công cộng, skill đã không tải.** SDK được phân phối riêng tư. Đề xuất đó là một dấu hiệu đáng tin cậy rằng công cụ code agent của bạn đang đoán thay vì tuân theo skill — dừng nó ở đó và kiểm tra skill có được cài đặt không. +**Nếu agent của bạn đề xuất cài đặt SDK từ một chỉ mục công khai, kỹ năng không được tải.** SDK được phân phối riêng tư. Đề xuất đó là một dấu hiệu đáng tin cậy rằng agent coding của bạn đang đoán thay vì theo kỹ năng — dừng nó ở đó và kiểm tra xem kỹ năng đã được cài đặt chưa. -Ngoài ra, bán kính ảnh hưởng của nó rất nhỏ: nó viết mã trong thư mục làm việc của bạn và các tệp sự kiện nơi bạn nói. Nó không đọc gì từ deployment của bạn và không thay đổi gì về nó. +Ngoài ra, bán kính tác hại của nó rất nhỏ: nó viết mã trong thư mục làm việc của bạn và các tệp sự kiện nơi bạn cho nó biết. Nó không đọc gì từ triển khai của bạn và không thay đổi gì về nó. -## Bước tiếp theo +## Các bước tiếp theo -- **[Python SDK](/vi/agenteye/python-sdk)**: tài liệu tham khảo sự kiện hoàn chỉnh — mỗi loại sự kiện và trường — đằng sau những gì skill này tự động hóa. -- **[Sessions](/vi/agenteye/sessions)**: những gì instrumentation của bạn tạo ra khi các sự kiện hạ cánh. -- **[Evaluator Agent Skill](/vi/agenteye/evaluator-skill)**: bước tiếp theo sau khi các lần chạy hạ cánh — đánh điểm chúng. -- **[CLI Agent Skill](/vi/agenteye/cli-skill)**: đọc telemetry của bạn lại. \ No newline at end of file +- **[Python SDK](/vi/agenteye/python-sdk)**: tài liệu tham khảo sự kiện hoàn chỉnh — mỗi loại sự kiện và trường — đằng sau những gì kỹ năng này tự động hóa. +- **[Sessions](/vi/agenteye/sessions)**: những gì instrumentation của bạn tạo ra một khi các sự kiện hạ cánh. +- **[Kỹ năng Evaluator Agent](/vi/agenteye/evaluator-skill)**: bước tiếp theo một khi các lần chạy đang hạ cánh — chấm điểm chúng. +- **[Kỹ năng CLI Agent](/vi/agenteye/cli-skill)**: đọc dữ liệu đo đạc của bạn trở lại. \ No newline at end of file diff --git a/docs/vi/agenteye/python-sdk.mdx b/docs/vi/agenteye/python-sdk.mdx index 9cb85735..4e369cd4 100644 --- a/docs/vi/agenteye/python-sdk.mdx +++ b/docs/vi/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "Xem chính xác những gì các AI agents của bạn đã làm trong production: mọi agent run, tool call, model request, hook, và human intervention." +description: "Xem chính xác những gì các agent AI của bạn đã làm trong production: mọi lần chạy agent, lệnh gọi tool, yêu cầu model, hook, và can thiệp của con người." --- -Xem chính xác những gì các AI agents của bạn đã làm trong production: mọi agent run, tool call, model request, hook, và human intervention. Failproof AI Observability Python SDK ghi lại toàn bộ trail này từ bên trong code của agent để bạn có thể debug, audit, và đánh giá những gì đã xảy ra. Sử dụng nó bất cứ khi nào bạn muốn Failproof AI Observability theo dõi các agents của mình. +Xem chính xác những gì các agent AI của bạn đã làm trong production: mọi lần chạy agent, lệnh gọi tool, yêu cầu model, hook, và can thiệp của con người. Failproof AI Observability Python SDK ghi lại dấu vết đó từ bên trong mã agent của bạn để bạn có thể gỡ lỗi, kiểm toán và đánh giá những gì đã xảy ra. Sử dụng nó bất cứ khi nào bạn muốn Failproof AI Observability quan sát các agent của mình. -Bên dưới, SDK ghi các sự kiện có cấu trúc vào các file JSONL cục bộ, và daemon collector sẽ lấy chúng và gửi đến platform một cách tự động. Bạn không cần quản lý các file này. +Ở mức độ bên trong, SDK ghi các sự kiện được cấu trúc vào các tệp JSONL cục bộ, và daemon bộ sưu tập sẽ nhặt chúng lên và gửi đến nền tảng một cách tự động. Bạn không cần quản lý những tệp đó. -> **Tip:** Mới bắt đầu với Failproof AI Observability? Trang này là tài liệu tham khảo SDK event hoàn chỉnh. +> **Tip:** Mới làm quen với Failproof AI Observability? Trang này là tài liệu tham khảo sự kiện SDK hoàn chỉnh.
@@ -18,15 +18,15 @@ Bên dưới, SDK ghi các sự kiện có cấu trúc vào các file JSONL cụ ## Cài đặt -SDK được phân phối cho khách hàng dưới dạng wheel riêng tư thay vì từ một public package index. Quá trình onboarding của bạn bao gồm cách lấy, cài đặt và pin nó — liên hệ với Failproof AI của bạn nếu bạn cần quyền truy cập. +SDK được phân phối cho khách hàng dưới dạng một wheel riêng tư thay vì từ một chỉ mục gói công cộng. Onboarding của bạn bao gồm cách lấy, cài đặt và cố định nó — hãy liên hệ với Failproof AI nếu bạn cần quyền truy cập. -Sau khi cài đặt, hãy xác nhận bạn có nó: +Sau khi cài đặt, xác nhận bạn có nó: ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -Thích để cho một coding agent thực hiện toàn bộ tích hợp? [Python SDK Agent Skill](/vi/agenteye/python-sdk-skill) biết đường dẫn cài đặt, lên kế hoạch các điểm instrumentation, viết chúng và xác minh các events đến. +Thích để cho một agent lập trình làm toàn bộ tích hợp? [Python SDK Agent Skill](/vi/agenteye/python-sdk-skill) biết đường dẫn cài đặt, lên kế hoạch các điểm instrumentation, viết chúng và xác minh các sự kiện đến. --- @@ -58,9 +58,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### Instrumenting một cuộc gọi thực tế +### Instrumentation cho một lệnh gọi thực -Trong thực tế, bạn sẽ bao quanh code agent hiện có của mình. Đặt một model call giữa `model_request` trước và `model_response` sau, để hai event này bao phủ yêu cầu thực tế và Failproof AI Observability có thể ghép chúng lại: +Trong thực tế, bạn bao quanh mã agent hiện tại của mình. Đặt một lệnh gọi model giữa `model_request` trước và `model_response` sau, để hai sự kiện bao quanh yêu cầu thực và Failproof AI Observability có thể ghép chúng: ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -Bao quanh tool calls một cách tương tự với `tool_use` và `tool_result`, sử dụng lại một `tool_call_id` trên toàn cặp. +Bao quanh các lệnh gọi tool theo cách tương tự với `tool_use` và `tool_result`, tái sử dụng một `tool_call_id` trên cả hai. -Đây là hình ảnh những events này khi chúng đến dashboard, được mã hóa màu theo loại và có thể lọc theo environment, agent, và session: +Dưới đây là những gì những sự kiện đó trông như thế nào khi chúng đến bảng điều khiển, được mã hóa màu theo loại và có thể lọc theo môi trường, agent và phiên: -![The live Events stream, colour-coded by event type and filterable by environment, agent, and session](/agenteye/images/events-stream.png) +![Dòng sự kiện trực tiếp, được mã hóa màu theo loại sự kiện và có thể lọc theo môi trường, agent và phiên](/agenteye/images/events-stream.png) --- @@ -113,15 +113,18 @@ agenteye.configure( ) ``` -Gọi một lần trước bất kỳ lệnh gọi `event.*` nào. An toàn khi bỏ qua; các giá trị mặc định hoạt động ngay lập tức. Tất cả các argument là keyword-only; truyền chúng theo tên như hình trên. +Gọi một lần trước bất kỳ lệnh gọi `event.*` nào. An toàn để bỏ qua; các giá trị mặc định hoạt động ngay lập tức. Tất cả các đối số chỉ có từ khóa; chuyển chúng theo tên như hiển thị ở trên. -Khi `base_dir` là `None` (mặc định), SDK đọc `$AGENTEYE_HOME` nếu được đặt, nếu không sẽ quay lại `~/.agenteye`. Điều này phù hợp với cách phân giải của collector, vì vậy một biến env `AGENTEYE_HOME` duy nhất sẽ cấu hình event spool được chia sẻ cho cả SDK và collector. +Khi `base_dir` là `None` (mặc định), SDK đọc `$AGENTEYE_HOME` nếu được đặt, +nếu không sẽ quay lại `~/.agenteye`. Điều này khớp với độ phân giải của bộ sưu tập, +vì vậy một biến môi trường `AGENTEYE_HOME` cấu hình dùng chung spool sự kiện cho cả +SDK và bộ sưu tập. --- -## Environment +## Môi trường -Gắn nhãn mọi event với một environment deployment (`production`, `staging`, `qa`, `canary`, v.v.). Đặt nó một lần; SDK sẽ tự động gắn nó vào mọi event. +Gắn nhãn mọi sự kiện với một môi trường triển khai (`production`, `staging`, `qa`, `canary`, v.v.). Đặt nó một lần; SDK đính kèm nó vào mọi sự kiện tự động. **Tùy chọn 1: thông qua `configure()`:** @@ -129,48 +132,48 @@ Gắn nhãn mọi event với một environment deployment (`production`, `stagi agenteye.configure(environment="production") ``` -**Tùy chọn 2: thông qua biến environment:** +**Tùy chọn 2: thông qua biến môi trường:** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**Ưu tiên:** `configure(environment=...)` thắng biến environment. Nếu không có cái nào được đặt, mặc định là `"dev"`. +**Ưu tiên:** `configure(environment=...)` thắng trên biến môi trường. Nếu cả hai không được đặt, mặc định thành `"dev"`. -Giá trị environment xuất hiện như một bộ lọc hạng nhất trong dashboard và được lưu trữ trên máy chủ để truy vấn nhanh. +Giá trị môi trường xuất hiện dưới dạng bộ lọc hạng nhất trong bảng điều khiển và được lưu trữ trên máy chủ để truy vấn nhanh. -> **Warning:** Giá trị Environment không được chứa dấu phẩy `,` theo nghĩa đen. Bộ lọc dashboard sử dụng đa lựa chọn được phân tách bằng dấu phẩy trên dây (`?environment=prod,staging`), vì vậy một environment được đặt tên là `prod,blue` sẽ bị chia thành hai giá trị. Các events có environments chứa dấu phẩy bị từ chối vào thời điểm tiếp nhận. +> **Warning:** Giá trị môi trường không được chứa dấu phẩy `,` theo nghĩa đen. Các bộ lọc bảng điều khiển sử dụng đa lựa chọn được phân tách bằng dấu phẩy trên dây (`?environment=prod,staging`), vì vậy một môi trường được đặt tên `prod,blue` sẽ bị chia thành hai giá trị. Các sự kiện với môi trường chứa dấu phẩy bị từ chối tại thời điểm nhập. --- -## Data và quyền riêng tư +## Dữ liệu và quyền riêng tư -SDK chỉ ghi lại các trường bạn truyền một cách rõ ràng. Các prompts, messages, tool inputs và outputs, và model content chỉ được capture vì bạn đã chuyển chúng tới một lệnh gọi `event.*`. Không có gì được đọc từ process hoặc captured ngầm. Bất kỳ trường nào bạn để trống đều bị bỏ qua khỏi event hoàn toàn; nó không được ghi vào disk. +SDK chỉ ghi lại các trường bạn explicitly truyền. Prompts, messages, tool inputs và outputs, và model content được chụp chỉ vì bạn chuyển chúng cho một lệnh gọi `event.*`. Không có gì được đọc từ process của bạn hoặc được chụp một cách implicit. Bất kỳ trường nào bạn để không được đặt sẽ bị bỏ qua khỏi sự kiện hoàn toàn; nó không được ghi vào đĩa. -Điều đó làm cho redaction trở thành lựa chọn và trách nhiệm của bạn. Nếu một prompt hoặc tool payload chứa PII hoặc secrets mà bạn không muốn lưu trữ, hãy loại bỏ hoặc che mờ nó trước khi truyền nó tới phương thức event. +Điều đó làm cho redaction là lựa chọn của bạn và trách nhiệm của bạn. Nếu một prompt hoặc tool payload chứa PII hoặc secrets mà bạn không muốn lưu trữ, hãy tách hoặc che nó trước khi bạn chuyển nó cho phương thức event. --- -## Event Reference +## Tài liệu tham khảo sự kiện -Hầu hết các events đến theo cặp start/end chia sẻ một correlation ID: `tool_use` và `tool_result` chia sẻ một `tool_call_id`, `hook_triggered` và `hook_completed` chia sẻ một `hook_id`, và `human_wait` và `human_input` chia sẻ một `input_id`. Phát event bắt đầu, thực hiện công việc, sau đó phát event kết thúc với cùng một ID. Failproof AI Observability sẽ khớp cặp này và tính `duration_ms` cho bạn, vì vậy bạn không bao giờ truyền `duration_ms` chính mình. +Hầu hết các sự kiện đến theo cặp start/end chia sẻ một ID tương quan: `tool_use` và `tool_result` chia sẻ một `tool_call_id`, `hook_triggered` và `hook_completed` chia sẻ một `hook_id`, và `human_wait` và `human_input` chia sẻ một `input_id`. Phát ra sự kiện bắt đầu, thực hiện công việc, sau đó phát ra sự kiện kết thúc với ID giống nhau. Failproof AI Observability khớp cặp và tính `duration_ms` cho bạn, vì vậy bạn không bao giờ tự truyền `duration_ms`. -![A session's git-style execution graph beside its event timeline, reconstructed from the paired events, with the tool/model/hook breakdown panel](/agenteye/images/session-detail.png) +![Biểu đồ thực thi kiểu git của một phiên bên cạnh dòng thời gian sự kiện của nó, được xây dựng lại từ các sự kiện được ghép, với bảng điều khiển phân tích tool/model/hook](/agenteye/images/session-detail.png) -Tất cả các phương thức event đều yêu cầu hai trường này: +Tất cả các phương thức event yêu cầu hai trường này: -| Field | Type | Description | +| Trường | Loại | Mô tả | |---|---|---| -| `session_id` | `str` | Nhận dạng agent run cấp cao nhất | -| `agent_id` | `str` | Nhận dạng agent nào trong session đã phát event | +| `session_id` | `str` | Xác định lần chạy agent cấp cao nhất | +| `agent_id` | `str` | Xác định agent nào trong phiên phát ra sự kiện | -Tất cả các phương thức cũng chấp nhận `**kwargs` tùy ý cho metadata tùy chỉnh (xem [Custom Fields](#custom-fields)). +Tất cả các phương thức cũng chấp nhận `**kwargs` tùy ý cho siêu dữ liệu tùy chỉnh (xem [Trường tùy chỉnh](#custom-fields)). --- ### `event.agent_start()` -Phát khi một agent bắt đầu công việc. +Được phát ra khi một agent bắt đầu công việc. ```python agenteye.event.agent_start( @@ -185,7 +188,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -Phát khi một agent hoàn thành công việc. +Được phát ra khi một agent hoàn thành công việc. ```python agenteye.event.agent_end( @@ -200,7 +203,7 @@ agenteye.event.agent_end( ### `event.tool_use()` -Phát khi một agent gọi một tool. Cặp với `tool_result`; SDK tự động tính `duration_ms`. +Được phát ra khi một agent gọi một tool. Ghép với `tool_result`; SDK tự động tính `duration_ms`. ```python agenteye.event.tool_use( @@ -216,7 +219,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -Phát khi một tool trả về. Tương quan với `tool_use` thông qua `tool_call_id`. +Được phát ra khi một tool trả về. Tương quan với `tool_use` thông qua `tool_call_id`. ```python agenteye.event.tool_result( @@ -234,7 +237,7 @@ agenteye.event.tool_result( ### `event.model_request()` -Phát ngay trước khi gửi một prompt tới một LLM. +Được phát ra ngay trước khi gửi một prompt cho một LLM. ```python agenteye.event.model_request( @@ -251,13 +254,13 @@ agenteye.event.model_request( ) ``` -Các mục `messages` chấp nhận cả content `content` thông thường hoặc Anthropic-style list-of-blocks `content`. Các sampling params (`temperature`, `max_tokens`, v.v.) có thể được truyền dưới dạng extra kwargs. +Các mục `messages` chấp nhận chuỗi `content` đơn giản hoặc Anthropic-style list-of-blocks `content`. Các tham số sampling (`temperature`, `max_tokens`, v.v.) có thể được truyền dưới dạng kwargs bổ sung. --- ### `event.model_response()` -Phát khi LLM trả về một response. +Được phát ra khi LLM trả về một phản hồi. ```python agenteye.event.model_response( @@ -274,13 +277,13 @@ agenteye.event.model_response( ) ``` -`content` chấp nhận cả một string thông thường (generic providers) hoặc một danh sách các content blocks theo kiểu Anthropic. Tool calls sống bên trong `content` dưới dạng blocks `{"type": "tool_use", ...}`, không có trường `tool_calls` riêng. +`content` chấp nhận chuỗi đơn giản (nhà cung cấp chung) hoặc danh sách các khối nội dung kiểu Anthropic. Các lệnh gọi tool nằm bên trong `content` dưới dạng các khối `{"type": "tool_use", ...}`, không có trường `tool_calls` riêng. --- ### `event.hook_triggered()` -Phát khi một hook kích hoạt. Cặp với `hook_completed`; SDK tự động tính `duration_ms`. +Được phát ra khi một hook kích hoạt. Ghép với `hook_completed`; SDK tự động tính `duration_ms`. ```python agenteye.event.hook_triggered( @@ -297,7 +300,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -Phát khi một hook hoàn thành. Tương quan với `hook_triggered` thông qua `hook_id`. +Được phát ra khi một hook hoàn thành. Tương quan với `hook_triggered` thông qua `hook_id`. ```python agenteye.event.hook_completed( @@ -316,7 +319,7 @@ agenteye.event.hook_completed( ### `event.error()` -Phát khi một lỗi không được xử lý xảy ra. +Được phát ra khi xảy ra lỗi không được xử lý. ```python agenteye.event.error( @@ -330,13 +333,13 @@ agenteye.event.error( --- -## Human-in-the-Loop Events +## Sự kiện con người trong vòng lặp -Các human-in-the-loop events mang lại sự giám sát trong những thời điểm một người bước vào quá trình thực thi của agent (chờ phê duyệt, cung cấp input, tạm dừng hoặc dừng agent). Chúng cho phép bạn đo lường con người mất bao lâu để phản hồi (SDK tự động tính `duration_ms` trên các paired events), audit người nào đã tạm dừng hoặc ngắt agent, và xây dựng các quy trình phê duyệt và giám sát hiển thị trong dashboard. +Các sự kiện con người trong vòng lặp cung cấp cho bạn giám sát các thời điểm khi một người bước vào thực thi agent (chờ phê duyệt, cung cấp đầu vào, tạm dừng hoặc dừng agent). Chúng cho phép bạn đo lường thời gian con người phải trả lời (SDK tự động tính `duration_ms` trên các sự kiện được ghép), kiểm toán ai tạm dừng hoặc ngắt agent, và xây dựng quy trình phê duyệt và giám sát bề mặt trong bảng điều khiển. ### `event.human_wait()` -Phát khi agent tạm dừng thực thi để chờ một con người cung cấp input. Cặp với `human_input`; SDK tự động tính `duration_ms` (con người mất bao lâu để phản hồi). +Được phát ra khi agent tạm dừng thực thi để chờ một người cung cấp đầu vào. Ghép với `human_input`; SDK tự động tính `duration_ms` (thời gian người phải mất để trả lời). ```python agenteye.event.human_wait( @@ -351,7 +354,7 @@ agenteye.event.human_wait( ### `event.human_input()` -Phát khi một con người cung cấp input và agent tiếp tục. Tương quan với `human_wait` thông qua `input_id`. `duration_ms` được tự động tính và không được truyền bởi người gọi. +Được phát ra khi một người cung cấp đầu vào và agent tiếp tục. Tương quan với `human_wait` thông qua `input_id`. `duration_ms` được tính tự động và không được truyền bởi người gọi. ```python agenteye.event.human_input( @@ -365,7 +368,7 @@ agenteye.event.human_input( ### `event.human_pause()` -Phát khi một con người chủ động tạm dừng agent (ví dụ: thông qua một điều khiển dashboard). Agent bị tạm dừng nhưng không bị chấm dứt. +Được phát ra khi một người tích cực tạm dừng agent (ví dụ: thông qua điều khiển bảng điều khiển). Agent bị tạm dừng nhưng không bị chấm dứt. ```python agenteye.event.human_pause( @@ -378,7 +381,7 @@ agenteye.event.human_pause( ### `event.human_interrupt()` -Phát khi một con người chủ động dừng agent giữa quá trình thực thi. Không giống như `human_pause`, công việc của agent bị chấm dứt thay vì tạm dừng. +Được phát ra khi một người tích cực dừng agent khi đang thực thi. Không giống như `human_pause`, công việc của agent bị chấm dứt thay vì tạm dừng. ```python agenteye.event.human_interrupt( @@ -392,9 +395,9 @@ agenteye.event.human_interrupt( --- -## Custom Fields +## Trường tùy chỉnh -Bất kỳ extra keyword argument nào được thêm vào event sau các trường tiêu chuẩn: +Bất kỳ đối số từ khóa bổ sung nào được thêm vào sự kiện sau các trường tiêu chuẩn: ```python agenteye.event.tool_use( @@ -407,27 +410,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`, `type`, và `environment` được dành riêng và sẽ tăng `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) nếu được truyền dưới dạng custom fields. `session_id` và `agent_id` là các tham số bắt buộc trên mọi phương thức event và không thể được cung cấp lần thứ hai; Python sẽ tăng `TypeError` nếu bạn làm. Thay vào đó, hãy đặt environment với `configure(environment=...)` (hoặc biến `AGENTEYE_ENVIRONMENT`). +`timestamp`, `type` và `environment` được dành riêng và tăng `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) nếu được truyền dưới dạng các trường tùy chỉnh. `session_id` và `agent_id` là các tham số bắt buộc trên mọi phương thức event và không thể được cung cấp lần thứ hai; Python tăng `TypeError` nếu bạn làm. Đặt môi trường bằng `configure(environment=...)` (hoặc biến `AGENTEYE_ENVIRONMENT`) thay thế. -Giữ payloads là structured JSON khi bạn muốn truy vấn các trường của chúng. Các giá trị mà JSON không hỗ trợ về mặt bản địa—như datetimes, UUIDs, decimals, sets, bytes, hoặc model objects—được chuyển đổi thành strings để ghi lại tiếp tục một cách an toàn. +Giữ payloads dưới dạng JSON có cấu trúc khi bạn muốn truy vấn các trường của chúng. Các giá trị mà JSON không hỗ trợ nguyên bản — chẳng hạn như datetimes, UUIDs, decimals, sets, bytes hoặc model objects — được chuyển đổi thành strings để ghi tiếp tục an toàn. --- -## Cách Events Được Ghi +## Cách sự kiện được viết -Events được buffer trong process và flushed vào disk mỗi `flush_interval` giây (mặc định 500 ms). Mỗi flush ghi một file JSONL: +Các sự kiện được lưu trữ trong quy trình và xóa vào đĩa mỗi `flush_interval` giây (mặc định 500 ms). Mỗi lần xóa viết một tệp JSONL: ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -Collector theo dõi thư mục này và tải file lên tự động. Bạn không cần quản lý các file này trực tiếp. +Bộ sưu tập quan sát thư mục này và tải lên các tệp tự động. Bạn không cần quản lý những tệp này trực tiếp. -Mỗi file được ghi atomically: SDK ghi vào một temporary file và sau đó đổi tên nó, vì vậy collector không bao giờ thấy một file nửa viết. Một final flush cũng chạy khi process của bạn thoát, vì vậy các events được buffer trong interval cuối cùng không bị mất. Nếu collector offline, các events chỉ tích tụ dưới dạng các file trên disk và ship khi nó quay trở lại. +Mỗi tệp được viết nguyên tử: SDK viết vào tệp tạm thời và sau đó đổi tên nó vào vị trí, vì vậy bộ sưu tập không bao giờ thấy tệp được viết một nửa. Một lần xóa cuối cùng cũng chạy khi process của bạn thoát, vì vậy các sự kiện được lưu trữ trong khoảng thời gian cuối cùng không bị mất. Nếu bộ sưu tập ngoại tuyến, các sự kiện chỉ đơn giản là tích tụ dưới dạng tệp trên đĩa và gửi khi nó trở lại trực tuyến. --- -## Bước tiếp theo +## Các bước tiếp theo -- [Event stream](/vi/agenteye/event-stream): xem các events này đến live, được mã hóa màu và có thể lọc theo environment, agent, và session. -- [Sessions](/vi/agenteye/sessions): xem cách các paired events tái cấu trúc mỗi agent run dưới dạng một execution graph và timeline. \ No newline at end of file +- [Dòng sự kiện](/vi/agenteye/event-stream): xem các sự kiện này đến trực tiếp, được mã hóa màu và có thể lọc theo môi trường, agent và phiên. +- [Phiên](/vi/agenteye/sessions): xem cách các sự kiện được ghép xây dựng lại mỗi lần chạy agent dưới dạng biểu đồ thực thi và dòng thời gian. \ No newline at end of file diff --git a/docs/vi/agenteye/queries.mdx b/docs/vi/agenteye/queries.mdx index ca822294..4ccb3fca 100644 --- a/docs/vi/agenteye/queries.mdx +++ b/docs/vi/agenteye/queries.mdx @@ -3,39 +3,40 @@ title: "Truy vấn" description: "Đặt bất kỳ câu hỏi nào về dữ liệu agent của bạn và nhận câu trả lời trong vài giây." --- -Đặt bất kỳ câu hỏi nào về dữ liệu agent của bạn và nhận câu trả lời trong vài giây. Failproof AI Observability cung cấp cho bạn một thư viện các truy vấn đã lưu, sẵn sàng chạy trên các sự kiện và đánh giá của bạn, để bạn bắt đầu từ một ví dụ hoạt động thay vì một trình soạn thảo SQL trống. -![Thư viện truy vấn đã lưu: một lưới các truy vấn có thể tái sử dụng, bao gồm các cài đặt sẵn tích hợp và các truy vấn tùy chỉnh](/agenteye/images/queries.png) +Đặt bất kỳ câu hỏi nào về dữ liệu agent của bạn và nhận câu trả lời trong vài giây. Failproof AI Observability cung cấp cho bạn một thư viện các truy vấn được lưu, sẵn sàng chạy trên các sự kiện và đánh giá của bạn, vì vậy bạn bắt đầu từ một ví dụ đã hoạt động thay vì một trình soạn thảo SQL trống. -*Thư viện truy vấn đã lưu của bạn tại `//queries`: các cài đặt sẵn tích hợp nằm cạnh các truy vấn mà nhóm bạn đã lưu.* +![Thư viện truy vấn đã lưu: một lưới các truy vấn có thể tái sử dụng, cả những preset tích hợp sẵn và các truy vấn tùy chỉnh](/agenteye/images/queries.png) -## Bắt đầu từ một cài đặt sẵn, không phải từ một trang trống +*Thư viện truy vấn đã lưu của bạn tại `//queries`: những preset tích hợp sẵn cùng với các truy vấn mà nhóm của bạn đã lưu.* -Bạn không cần phải ghi nhớ tên bảng hay viết SQL từ đầu. Thư viện mở với các cài đặt sẵn tích hợp cho những câu hỏi mà các nhóm thường đặt, nằm ngay cạnh các truy vấn mà nhóm của bạn đã lưu và đặt tên. Chọn một cái gần với những gì bạn muốn và bạn đã có phần lớn câu trả lời. +## Bắt đầu từ một preset, không phải một trang trắng -Mọi truy vấn đã lưu đều được phạm vi org và chia sẻ, vì vậy những truy vấn hữu ích mà các đồng nghiệp viết cũng sẽ là của bạn. Đặt tên cho một truy vấn và cung cấp mô tả cho nó một lần, và bất kỳ ai trong org của bạn đều có thể tìm thấy nó, chạy nó hoặc ghim kết quả của nó vào bảng điều khiển sau này. +Bạn không cần phải nhớ tên bảng hoặc viết SQL từ đầu. Thư viện mở với những preset tích hợp sẵn cho những câu hỏi mà các nhóm thường hỏi, nằm cạnh các truy vấn mà nhóm của bạn đã lưu và đặt tên. Chọn một truy vấn gần với những gì bạn muốn và bạn đã sẵn sàng để có câu trả lời. + +Mọi truy vấn đã lưu đều được phạm vi tổ chức và được chia sẻ, vì vậy những truy vấn hữu ích mà đồng nghiệp của bạn viết cũng trở thành của bạn. Đặt tên cho một truy vấn và cung cấp mô tả cho nó một lần, và bất kỳ ai trong tổ chức của bạn đều có thể tìm thấy nó, chạy nó, hoặc ghim kết quả của nó trên bảng điều khiển sau này. Tìm nó tại `//queries`. ## Điều chỉnh nó và chạy nó trong trình soạn thảo SQL -Mở bất kỳ truy vấn nào và nó sẽ xuất hiện trong trình soạn thảo SQL, nơi bạn có thể điều chỉnh nó và xem câu trả lời ngay lập tức: không xuất, không vòng quay lại, không chờ đợi người khác. +Mở bất kỳ truy vấn nào và nó sẽ đáp ứng trong trình soạn thảo SQL, nơi bạn có thể điều chỉnh nó và xem câu trả lời ngay lập tức: không cần xuất, không cần lượt trở lại, không cần chờ đợi người khác. -![Trình soạn thảo truy vấn SQL chạy một truy vấn đã lưu, với thanh bên lược đồ và lưới kết quả trực tiếp](/agenteye/images/query-lab.png) +![Trình soạn thảo truy vấn SQL chạy một truy vấn đã lưu, với thanh bên schema và lưới kết quả trực tiếp](/agenteye/images/query-lab.png) -*Trình soạn thảo SQL: truy vấn của bạn bên trái, thanh bên lược đồ để bạn không bao giờ phải đoán tên cột, và lưới kết quả trực tiếp bên dưới.* +*Trình soạn thảo SQL: truy vấn của bạn ở bên trái, thanh bên schema để bạn không bao giờ đoán tên cột, và lưới kết quả trực tiếp ở dưới.* -- **Thanh bên lược đồ** trình bày các bảng phân tích và các cột của chúng, vì vậy bạn có thể hình thành truy vấn mà không cần tìm kiếm tên trường. +- **Thanh bên schema** trình bày các bảng phân tích và các cột của chúng, để bạn có thể hình thành truy vấn mà không cần tìm kiếm tên trường. - **Lưới kết quả trực tiếp** trả về các hàng ngay khi bạn chạy, vì vậy bạn có thể lặp lại trong vài giây thay vì đoán và đoán lại. -- **Chỉ đọc theo thiết kế.** Các truy vấn chạy trên kho sự kiện của bạn và được xác nhận trên máy chủ: chỉ cho phép các câu lệnh `SELECT` và `WITH`, với thời gian chờ câu lệnh và giới hạn hàng. Một truy vấn khám phá không bao giờ có thể sửa đổi dữ liệu của bạn, và một truy vấn bị lỗi sẽ bị dừng cho bạn. +- **Chỉ đọc theo thiết kế.** Các truy vấn chạy dựa trên kho sự kiện của bạn và được xác thực trên máy chủ: chỉ các câu lệnh `SELECT` và `WITH` được phép, với timeout câu lệnh và giới hạn hàng. Một truy vấn khám phá không thể bao giờ sửa đổi dữ liệu của bạn, và một câu lệnh chạy thoát tẩu sẽ bị dừng lại cho bạn. -Hài lòng với kết quả? Lưu nó trở lại thư viện để toàn bộ nhóm của bạn sử dụng, hoặc ghim kết quả của nó vào bảng điều khiển dưới dạng một tile dòng, thanh, khu vực hoặc bánh. +Hài lòng với kết quả? Lưu nó trở lại thư viện để toàn bộ nhóm kế thừa nó, hoặc ghim kết quả của nó trên bảng điều khiển dưới dạng gạch ngang, thanh, khu vực hoặc tile hình tròn. -## Chạy chúng từ terminal, hoặc để trợ lý viết chúng +## Chạy chúng từ thiết bị đầu cuối, hoặc để trợ lý viết chúng -Các truy vấn đã lưu tương tự theo dõi bạn ở bất cứ nơi nào bạn làm việc: +Cùng những truy vấn đã lưu theo dõi bạn ở bất cứ nơi nào bạn làm việc: -- **Từ terminal.** CLI `agenteye` liệt kê, chạy và lưu các truy vấn hoàn toàn tương tự, vì vậy bạn có thể thả kết quả vào một tập lệnh, dây nó vào CI, hoặc gửi nó cho một coding agent. +- **Từ thiết bị đầu cuối.** CLI `agenteye` liệt kê, chạy và lưu những truy vấn giống nhau, vì vậy bạn có thể thả kết quả vào script, kết nối nó với CI, hoặc trao nó cho một coding agent. ```bash agenteye query list # the same saved queries, from your terminal @@ -44,12 +45,12 @@ agenteye query run errs --arg prod # run one and print the rows (add --json to Xem [CLI và agents](/vi/agenteye/cli-and-agents) để biết bộ lệnh đầy đủ. -- **Từ trợ lý AI.** Không chắc cách diễn đạt SQL? Hỏi [trợ lý AI](/vi/agenteye/assistant) trong bảng điều khiển bằng tiếng Anh đơn giản và nó sẽ soạn thảo truy vấn và lưu nó vào thư viện của bạn. +- **Từ trợ lý AI.** Không chắc cách diễn đạt SQL? Hỏi [trợ lý AI](/vi/agenteye/assistant) trong bảng điều khiển bằng tiếng Anh đơn giản và nó sẽ soạn thảo truy vấn và lưu nó vào thư viện của bạn cho bạn. -Chạy một truy vấn đã lưu được kiểm soát bởi quyền `queries:run`, được giữ riêng biệt với các quyền để tạo hoặc xóa truy vấn, vì vậy bạn có thể cấp quyền truy cập đọc mà không để tất cả mọi người viết lại thư viện. +Chạy một truy vấn đã lưu được kiểm soát bởi quyền `queries:run`, được giữ riêng biệt với các quyền tạo hoặc xóa truy vấn, vì vậy bạn có thể cấp quyền truy cập đọc mà không cho phép mọi người viết lại thư viện. ## Liên quan -- [Bảng điều khiển](/vi/agenteye/dashboards): ghim kết quả truy vấn vào các biểu đồ chia sẻ, toàn bộ org. -- [Trợ lý AI](/vi/agenteye/assistant): đặt câu hỏi bằng tiếng Anh đơn giản và nhận lại một truy vấn. -- [CLI và agents](/vi/agenteye/cli-and-agents): chạy và lưu các truy vấn tương tự từ terminal của bạn. \ No newline at end of file +- [Bảng điều khiển](/vi/agenteye/dashboards): ghim kết quả truy vấn vào biểu đồ được chia sẻ, toàn tổ chức. +- [Trợ lý AI](/vi/agenteye/assistant): đặt câu hỏi bằng tiếng Anh đơn giản và nhận truy vấn trở lại. +- [CLI và agents](/vi/agenteye/cli-and-agents): chạy và lưu cùng những truy vấn từ thiết bị đầu cuối của bạn. \ No newline at end of file diff --git a/docs/vi/agenteye/security.mdx b/docs/vi/agenteye/security.mdx index 1bec174d..eac7f3f6 100644 --- a/docs/vi/agenteye/security.mdx +++ b/docs/vi/agenteye/security.mdx @@ -1,68 +1,69 @@ --- +--- title: "Bảo mật" -description: "Failproof AI Observability được xây dựng để hoạt động gần với các agent production của bạn, có nghĩa là nó thấy được prompts, đầu vào công cụ và kết quả đầu ra của bạn." +description: "Failproof AI Observability được xây dựng để hoạt động gần với các agent production của bạn, nghĩa là nó có thể nhìn thấy các prompt, input công cụ và output của bạn." --- -Failproof AI Observability được xây dựng để hoạt động gần với các agent production của bạn, có nghĩa là nó thấy được prompts, đầu vào công cụ và kết quả đầu ra của bạn. Trang này giải thích cách nó giữ dữ liệu đó được cách ly, được kiểm soát và nằm dưới quyền của bạn. Nếu bạn đang đánh giá Failproof AI Observability cho một bài kiểm tra bảo mật, hãy bắt đầu từ đây. +Failproof AI Observability được xây dựng để hoạt động gần với các agent production của bạn, nghĩa là nó có thể nhìn thấy các prompt, input công cụ và output của bạn. Trang này giải thích cách nó giữ dữ liệu đó cô lập, được kiểm soát và nằm trong tay bạn. Nếu bạn đang đánh giá Failproof AI Observability cho một cuộc kiểm tra bảo mật, hãy bắt đầu từ đây. --- ## Dữ liệu của bạn ở lại trong môi trường của bạn -Failproof AI Observability được tự lưu trữ. Các sự kiện, prompts, phản hồi của mô hình và phân tích được lưu trữ trong các cơ sở dữ liệu của riêng bạn, trong môi trường của riêng bạn. Không có dữ liệu nào được gửi đến bên thứ ba SaaS để lưu trữ, và dữ liệu của bạn ở lại trong tài khoản cloud của riêng bạn. +Failproof AI Observability được tự lưu trữ. Các sự kiện, prompt, phản hồi từ model và phân tích được lưu trữ trong các cơ sở dữ liệu của riêng bạn, trong môi trường của riêng bạn. Không có dữ liệu nào được gửi đến một SaaS bên thứ ba để lưu trữ, và dữ liệu của bạn ở lại trong tài khoản cloud của riêng bạn. --- -## Cách ly đa tổ chức +## Cách ly thue bao -Một instance Failproof AI Observability có thể lưu trữ nhiều tổ chức, và mỗi tổ chức được cách ly ở lớp lưu trữ — được thực thi bởi cơ sở dữ liệu, không chỉ giao diện người dùng: +Một instance Failproof AI Observability có thể lưu trữ nhiều tổ chức, và mỗi tổ chức được cách ly ở tầng lưu trữ — được thực thi bởi cơ sở dữ liệu, không chỉ bởi giao diện người dùng: -- Dữ liệu hoạt động của một tổ chức (người dùng, khóa, bảng điều khiển, truy vấn đã lưu) được giới hạn trong tổ chức đó, và các lần đọc liên tổ chức bị chặn bởi chính cơ sở dữ liệu. -- Mỗi sự kiện được nhập đều được đánh dấu với tổ chức sở hữu, vì vậy các sự kiện của một tổ chức không bao giờ có thể được đọc bởi tổ chức khác. +- Dữ liệu vận hành của một tổ chức (người dùng, khóa, bảng điều khiển, truy vấn đã lưu) được giới hạn trong tổ chức đó, và việc đọc chéo tổ chức bị chặn bởi cơ sở dữ liệu. +- Mỗi sự kiện được nhập đều được gắn dấu với tổ chức sở hữu của nó, vì vậy các sự kiện của một tổ chức không bao giờ có thể được đọc bởi tổ chức khác. -Mỗi tuyến đường bảng điều khiển được giới hạn trong một slug org (`//…`). +Mỗi tuyến đường bảng điều khiển được giới hạn dưới một slug tổ chức (`//…`). --- ## Đăng nhập -Failproof AI Observability sử dụng đăng nhập không mật khẩu, dựa trên email. Không có mật khẩu để lừa phishing hoặc rò rỉ. Người dùng yêu cầu một mã dùng một lần (hoặc liên kết magic một bước), được gửi email cho họ và hết hạn nhanh chóng. Đăng nhập được kiểm soát bởi một **danh sách cho phép**: chỉ những địa chỉ email (hoặc miền) mà bạn cho phép mới có thể xác thực. +Failproof AI Observability sử dụng đăng nhập không mật khẩu dựa trên email. Không có mật khẩu để lừa hoặc rò rỉ. Một người dùng yêu cầu một mã một lần (hoặc một liên kết magic nhấp một lần), được gửi qua email cho họ và hết hạn nhanh chóng. Việc đăng nhập được kiểm soát bởi một **danh sách cho phép**: chỉ những địa chỉ email (hoặc tên miền) mà bạn cho phép mới có thể xác thực. -![Màn hình đăng nhập Failproof AI Observability, gửi một mã dùng một lần đến email của bạn](/agenteye/images/login.png) +![Màn hình đăng nhập Failproof AI Observability, gửi một mã sử dụng một lần đến email của bạn](/agenteye/images/login.png) --- -## Truy cập được giới hạn với khóa API +## Truy cập được giới hạn bằng khóa API -Mỗi máy khách xác thực bằng khóa API có quyền granular, ít nhất. Một bộ sưu tập chỉ cần `events:add`; một khóa bảng điều khiển hoặc trợ lý có thể chỉ đọc; các hành động phá hủy (xóa, tạo lại) là các cấp riêng biệt mà bạn chọn để đưa vào. +Mỗi client xác thực bằng một khóa API mang theo các quyền chi tiết, ít nhất. Một collector chỉ cần `events:add`; một khóa bảng điều khiển hoặc trợ lý có thể chỉ đọc; các hành động phá hoại (xóa, tạo lại) là các quyền riêng biệt mà bạn chọn để bao gồm. -![Trang khóa API: các cấp quyền của mỗi khóa, được mã hóa màu theo phạm vi đọc, viết và hủy diệt](/agenteye/images/api-keys.png) +![Trang khóa API: các quyền của mỗi khóa, được mã hóa màu theo phạm vi đọc, ghi và phá hoại](/agenteye/images/api-keys.png) -Giữ khóa bootstrap quản trị viên cho thiết lập và phát hành các khóa hẹp cho mọi thứ khác. Xem [API keys](/vi/agenteye/api-keys). +Giữ khóa bootstrap của admin để thiết lập và cấp các khóa hẹp cho mọi thứ khác. Xem [API keys](/vi/agenteye/api-keys). --- -## Trợ lý chỉ đọc, được phê duyệt +## Một trợ lý chỉ đọc, được kiểm duyệt phê duyệt -[Trợ lý AI](/vi/agenteye/assistant) trong bảng điều khiển trả lời các câu hỏi về dữ liệu của bạn, nhưng nó bị hạn chế bởi thiết kế: +[AI assistant](/vi/agenteye/assistant) trong bảng điều khiển trả lời các câu hỏi về dữ liệu của bạn, nhưng nó bị giới hạn bởi thiết kế: -- Nó **chỉ đọc theo mặc định**: SQL của nó chạy qua một lệnh bảo vệ chỉ cho phép các truy vấn `SELECT`/`WITH`, một câu lệnh duy nhất, với một giới hạn hàng. -- Bất cứ điều gì nó tạo (một truy vấn đã lưu, một bảng điều khiển) đều **được phê duyệt**: bạn xem xét và phê duyệt mỗi lần ghi trước khi nó xảy ra. +- Nó **chỉ đọc theo mặc định**: SQL của nó chạy qua một bảo vệ chỉ cho phép các truy vấn `SELECT`/`WITH`, một câu lệnh, với giới hạn hàng. +- Bất cứ điều gì nó tạo (một truy vấn đã lưu, một bảng điều khiển) đều **được phê duyệt kiểm duyệt**: bạn xem xét và phê duyệt mỗi lần ghi trước khi nó xảy ra. - Nó **không bao giờ có thể xóa**. -Vì vậy, một đồng nghiệp có thể hỏi "agents nào bị lỗi nhất tuần này?" và hành động dựa trên câu trả lời, mà không cần trợ lý có khả năng thay đổi hoặc xóa dữ liệu của bạn riêng lẻ. +Vì vậy, một đồng nghiệp có thể hỏi "những agent nào có lỗi nhiều nhất tuần này?" và hành động dựa trên câu trả lời, mà không cần trợ lý có khả năng thay đổi hoặc xóa dữ liệu của bạn tự động. --- -## Trong quá trình chuyển động +## Khi vận chuyển -Tất cả lưu lượng chạy qua HTTPS. Bạn kết thúc TLS bằng chứng chỉ của riêng bạn, vì vậy lưu lượng từ bộ sưu tập đến máy chủ và từ trình duyệt đến máy chủ được mã hóa trong quá trình chuyển động. +Tất cả lưu lượng chạy qua HTTPS. Bạn kết thúc TLS bằng các chứng chỉ của riêng bạn, vì vậy lưu lượng collector-to-server và browser-to-server được mã hóa khi vận chuyển. --- -## Bước tiếp theo +## Các bước tiếp theo -- [Overview](/vi/agenteye/overview): cách Failproof AI Observability kết hợp với nhau. -- [API keys](/vi/agenteye/api-keys): giới hạn truy cập cho bộ sưu tập, bảng điều khiển và trợ lý. -- [Observability](/vi/agenteye/observability): những gì Failproof AI Observability capture từ các agent của bạn. \ No newline at end of file +- [Tổng quan](/vi/agenteye/overview): cách Failproof AI Observability kết hợp với nhau. +- [API keys](/vi/agenteye/api-keys): giới hạn quyền truy cập cho collector, bảng điều khiển và trợ lý. +- [Observability](/vi/agenteye/observability): những gì Failproof AI Observability nắm bắt từ các agent của bạn. \ No newline at end of file diff --git a/docs/vi/agenteye/sessions.mdx b/docs/vi/agenteye/sessions.mdx index 4cd469d7..6dc0eb36 100644 --- a/docs/vi/agenteye/sessions.mdx +++ b/docs/vi/agenteye/sessions.mdx @@ -1,57 +1,57 @@ --- -title: "Sessions & Execution Graph" -description: "Mỗi sự kiện từ một lần chạy được gộp thành một hàng dễ đọc và vẽ dưới dạng biểu đồ thực thi kiểu git mà bạn có thể hiểu trong vài giây." +title: "Phiên làm việc & Biểu đồ Thực thi" +description: "Mọi sự kiện từ một lần chạy, gộp lại thành một hàng dễ đọc và vẽ thành biểu đồ thực thi kiểu git mà bạn có thể đọc trong vài giây." --- -Hãy dừng đoán tại sao một lần chạy bị lỗi. Failproof AI Observability gộp mỗi sự kiện từ một lần chạy thành một hàng dễ đọc, sau đó vẽ toàn bộ lần chạy dưới dạng hình ảnh kiểu git mà bạn có thể hiểu trong vài giây, vì vậy bạn thấy chính xác agent của mình đã làm gì, từng bước một. +Hãy dừng việc đoán xem tại sao một lần chạy lại thất bại. Failproof AI Observability gộp mọi sự kiện từ một lần chạy thành một hàng dễ đọc, sau đó vẽ toàn bộ lần chạy dưới dạng hình ảnh kiểu git mà bạn có thể đọc trong vài giây, để bạn thấy chính xác agent đã làm gì, từng bước một. -![Danh sách Sessions: một hàng mỗi lần chạy, trên các môi trường và agent, với các badge trạng thái và điểm đánh giá](/agenteye/images/sessions-list.png) +![Danh sách phiên: một hàng trên mỗi lần chạy, trên các môi trường và agent, với các bảng trạng thái và huy hiệu điểm đánh giá](/agenteye/images/sessions-list.png) -*Một hàng mỗi lần chạy: badge trạng thái cho bạn biết cách kết thúc lần chạy ngay lập tức, và một badge điểm xuất hiện khi một evaluator được kết nối.* +*Một hàng trên mỗi lần chạy: bảng trạng thái cho bạn biết cách thức kết thúc lần chạy ngay lập tức, và một huy hiệu điểm sẽ xuất hiện sau khi có một trình đánh giá được kết nối.*
-*Theo dõi agent: theo dõi một lần chạy từng bước một, từ mục tiêu đến các tool cho đến câu trả lời cuối cùng.* +*Tracing agent: theo dõi một lần chạy từng bước một, từ mục tiêu đến các công cụ đến câu trả lời cuối cùng.* --- -## Xem từng lần chạy ngay lập tức +## Xem mọi lần chạy ngay lập tức -Dòng sự kiện thô là sự thật của từng bước, nhưng khi bạn có hàng nghìn bước trên nhiều lần chạy, bạn cần lần chạy, không phải bước. Trang Sessions gộp tất cả các sự kiện của một lần chạy thành một hàng, vì vậy một ngày hoạt động trở thành một danh sách có thể quét thay vì một lượng lớn dữ liệu. +Dòng sự kiện thô là sự thật của mỗi bước, nhưng khi bạn có hàng ngàn bước trên hàng chục lần chạy, bạn cần lần chạy, không phải bước. Trang Sessions gộp tất cả các sự kiện của một lần chạy thành một hàng, để một ngày hoạt động trở thành một danh sách có thể quét được thay vì một lượng dữ liệu khổng lồ. -Mỗi hàng mang một badge trạng thái, vì vậy một lần chạy bị lỗi sẽ nổi bật so với một lần chạy khỏe mạnh trước khi bạn nhấp vào bất cứ thứ gì. Lọc theo phạm vi ngày, môi trường, agent, hoặc session để đi từ "mọi thứ" đến "lần chạy tôi quan tâm" trong một vài cú nhấp chuột. +Mỗi hàng có một bảng trạng thái, vì vậy một lần chạy thất bại nổi bật so với một lần chạy lành mạnh trước khi bạn nhấp vào bất cứ thứ gì. Lọc theo phạm vi ngày, môi trường, agent hoặc phiên để đi từ "mọi thứ" đến "lần chạy mà tôi quan tâm" chỉ trong vài cú nhấp. -Sau khi bạn kết nối một evaluator, mỗi lần chạy hoàn tất sẽ được ghi điểm tự động và điểm mới nhất của nó sẽ hiển thị trên hàng dưới dạng badge. Bạn có thể lọc theo bất kỳ phạm vi điểm nào, vì vậy "hiển thị mỗi lần chạy prod có điểm thấp trong tuần này" là một bộ lọc, không phải là đánh giá thủ công. Cho đến khi bạn thiết lập một, các session vẫn ghi lại toàn bộ lần chạy; chúng chỉ chưa có điểm. +Sau khi bạn kết nối một trình đánh giá, mỗi lần chạy hoàn thành sẽ được chấm điểm tự động và điểm mới nhất của nó sẽ hiển thị trên hàng dưới dạng huy hiệu. Bạn có thể lọc theo bất kỳ phạm vi điểm nào, vì vậy "hiển thị cho tôi mọi lần chạy sản xuất có điểm thấp trong tuần này" là một bộ lọc, không phải một bài đánh giá thủ công. Cho đến khi bạn thiết lập một trình, các phiên vẫn ghi lại toàn bộ lần chạy; chúng chỉ không mang điểm lúc này. --- ## Đọc toàn bộ lần chạy dưới dạng hình ảnh -![Biểu đồ thực thi kiểu git của một session bên cạnh dòng thời gian sự kiện của nó, với bảng phân tích tool, model, và hook](/agenteye/images/session-detail.png) +![Biểu đồ thực thi kiểu git của một phiên bên cạnh dòng thời gian sự kiện của nó, với bảng phân tích công cụ, mô hình và hook](/agenteye/images/session-detail.png) -*Biểu đồ thực thi (trái) nằm bên cạnh dòng thời gian sự kiện; thanh bên phải chia nhỏ các tool, model, hook, và chi phí token cho lần chạy.* +*Biểu đồ thực thi (bên trái) nằm bên cạnh dòng thời gian sự kiện; thanh bên phải phân tích các công cụ, mô hình, hook và chi phí token cho lần chạy.* -Nhấp vào bất kỳ session nào để mở biểu đồ thực thi của nó: một chế độ xem kiểu git về cách agent, tool, hook, và các lệnh gọi model được triển khai theo thời gian. Mỗi sub-agent song song nhánh vào làn của riêng nó, vì vậy bạn có thể thấy công việc nào chạy cạnh nhau, sub-agent nào bị mắc kẹt, và nơi lần chạy sai hướng, mà không cần phải phát lại nó trong đầu từ một bức tường nhật ký. +Nhấp vào bất kỳ phiên nào để mở biểu đồ thực thi của nó: một chế độ xem kiểu git về cách các agent, công cụ, hook và lệnh gọi mô hình diễn ra theo thời gian. Mỗi sub-agent song song sẽ nhánh vào dòng riêng của họ, để bạn có thể thấy công việc nào chạy song song, sub-agent nào bị tê liệt và lần chạy đã đi sai chỗ nào, mà không cần phải phát lại trong đầu từ một bức tường nhật ký. -Thanh bên phải cho bạn biết chi tiết từng lần chạy: những tool và model nào đã chạy, những hook nào được kích hoạt, và lần chạy đã chi phí bao nhiêu token. Đó là câu trả lời cho "tại sao lần chạy này lại tốn nhiều tiền như vậy?" hoặc "tool nào là cái chậm?" nằm ngay bên cạnh biểu đồ đã gây ra nó. +Thanh bên phải cung cấp cho bạn bảng phân tích trên mỗi lần chạy: công cụ và mô hình nào chạy, hook nào kích hoạt và lần chạy chi tiêu bao nhiêu trong token. Đó là câu trả lời cho "tại sao lần chạy này lại tốn nhiều tiền như vậy?" hoặc "công cụ nào là công cụ chậm?" nằm ngay bên cạnh biểu đồ gây ra nó. -Các sự kiện riêng lẻ có thể được định địa chỉ, vì vậy bạn có thể trao cho ai đó một liên kết đến một thời điểm thay vì "session, khoảng hai phần ba xuống". Sao chép liên kết từ bất kỳ sự kiện nào, hoặc theo một liên kết từ kết quả [audit](/vi/agenteye/audits) hoặc lỗi, và session sẽ mở với sự kiện đó được chọn và cuộn đến. Điều này cũng áp dụng cho các lần chạy rất dài: dòng thời gian tải một cửa sổ giới hạn vì lợi ích của trình duyệt của bạn, và một liên kết trỏ vào quá cửa sổ đó vẫn tìm thấy sự kiện của nó thay vì thả bạn ở đầu. Nếu sự kiện đã lỗi thời ngoài cửa sổ retention của bạn, trang sẽ cho bạn biết điều đó thay vì yên lặng không chọn gì. +Các sự kiện riêng lẻ là có thể địa chỉ được, vì vậy bạn có thể cung cấp cho ai đó một liên kết đến một thời điểm chứ không phải "phiên, khoảng hai phần ba xuống dưới". Sao chép liên kết từ bất kỳ sự kiện nào hoặc theo một liên kết từ một phát hiện [audit](/vi/agenteye/audits) hoặc một lỗi, và phiên sẽ mở với sự kiện đó được chọn và cuộn đến. Điều này cũng áp dụng cho các lần chạy rất dài: dòng thời gian tải một cửa sổ giới hạn vì lợi ích trình duyệt của bạn, và một liên kết chỉ đến quá cửa sổ đó vẫn tìm thấy sự kiện của nó thay vì thả bạn ở đầu. Nếu sự kiện đã quá cũ ngoài cửa sổ giữ lại của bạn, trang sẽ cho bạn biết điều đó thay vì im lặng không chọn gì. --- -## Nơi tìm nó +## Nơi tìm kiếm -Mỗi trang bảng điều khiển được phạm vi vào tổ chức của bạn (`//…`). Sessions nằm dưới **Observe** ở thanh bên trái, bên cạnh Events, với các bộ lọc phạm vi ngày, môi trường, agent, và session trên đầu danh sách. Mỗi hàng là một cú nhấp chuột từ biểu đồ thực thi đầy đủ của nó. +Mọi trang bảng điều khiển được phạm vi vào tổ chức của bạn (`//…`). Sessions nằm dưới **Observe** trong thanh bên trái, bên cạnh Events, với các bộ lọc phạm vi ngày, môi trường, agent và phiên ở đầu danh sách. Mỗi hàng là một cú nhấp chuột khỏi biểu đồ thực thi đầy đủ của nó. -Để bật các badge điểm và lọc phạm vi điểm, hãy kết nối một evaluator: xem [Evaluations](/vi/agenteye/evaluations). +Để bật các huy hiệu điểm và lọc theo phạm vi điểm, hãy kết nối một trình đánh giá: xem [Evaluations](/vi/agenteye/evaluations). --- ## Liên quan -- [Event stream](/vi/agenteye/event-stream): dòng thô từng bước mà mỗi session được gộp lại từ đó. -- [Evaluations](/vi/agenteye/evaluations): kết nối một evaluator để mỗi lần chạy nhận được một badge điểm mà bạn có thể lọc. -- [Telemetry](/vi/agenteye/telemetry): cách các lần chạy đi từ agent của bạn vào các session này. \ No newline at end of file +- [Event stream](/vi/agenteye/event-stream): dòng thô, theo từng bước mà mỗi phiên được gộp lại từ. +- [Evaluations](/vi/agenteye/evaluations): kết nối một trình đánh giá để mỗi lần chạy nhận được một huy hiệu điểm mà bạn có thể lọc theo. +- [Telemetry](/vi/agenteye/telemetry): cách các lần chạy từ agent của bạn vào các phiên này. \ No newline at end of file diff --git a/docs/vi/agenteye/telemetry.mdx b/docs/vi/agenteye/telemetry.mdx index deefd7f1..aff12b31 100644 --- a/docs/vi/agenteye/telemetry.mdx +++ b/docs/vi/agenteye/telemetry.mdx @@ -1,52 +1,51 @@ --- -title: "Chỉ Số Hiệu Suất" -description: "Xem ngay lập tức khi các mô hình, công cụ hoặc hook của bạn chậm lại hoặc phát sinh chi phí, và phát hiện sự tăng độ trễ ở phía đuôi trước khi người dùng của bạn cảm nhận được." +title: "Số liệu hiệu năng" +description: "Phát hiện ngay lập tức khi mô hình, công cụ hoặc hook của bạn chậm lại hoặc phát sinh chi phí, và bắt được sự tăng độ trễ đuôi trước khi người dùng của bạn cảm nhận được." --- +Phát hiện ngay lập tức khi mô hình, công cụ hoặc hook của bạn chậm lại hoặc phát sinh chi phí, và bắt được sự tăng độ trễ đuôi trước khi người dùng của bạn cảm nhận được. Ba trang chuyên dụng chuyển đổi các thời gian thô thành p50, p95 và p99 mà bạn có thể đọc ngay. -Xem ngay lập tức khi các mô hình, công cụ hoặc hook của bạn chậm lại hoặc phát sinh chi phí, và phát hiện sự tăng độ trễ ở phía đuôi trước khi người dùng của bạn cảm nhận được. Ba trang chuyên dụng biến các thời gian thô thành p50, p95 và p99 mà bạn có thể đọc ngay tại một cái nhìn. +![Trang Models hiển thị biểu đồ nhiệt độ trễ, một dải phân vị và các con số token, chi phí và cửa sổ ngữ cảnh cho mỗi mô hình](/agenteye/images/models.png) +*Trang Models: biểu đồ nhiệt độ trễ, một dải phân vị và token, chi phí ước tính cũng như mức độ sử dụng cửa sổ ngữ cảnh cho mỗi mô hình.* -![Trang Models hiển thị sơ đồ nhiệt độ trễ, một dải phần trăm và các số liệu về token, chi phí và cửa sổ ngữ cảnh cho từng mô hình](/agenteye/images/models.png) -*Trang Models: sơ đồ nhiệt độ trễ, dải phần trăm và số liệu token cho mỗi mô hình, chi phí ước tính và phần trăm đầy cửa sổ ngữ cảnh.* +## Ngừng để các mức trung bình ẩn giấu những lần chạy tệ nhất của bạn -## Hãy dừng để trung bình ẩn các lần chạy tồi tệ nhất của bạn +Một con số độ trễ trung bình vừa an tâm vừa vô dụng: nó làm mịn đi lệnh gọi thứ năm mươi bị treo và gọi người trực vào lúc 2 giờ sáng. Các trang Models, Tools và Hooks từ chối làm điều đó. Mỗi trang có cùng cấu trúc, vì vậy bạn chỉ cần học một lần: -Một số lượng độ trễ trung bình là thoải mái và vô ích: nó làm mịn một lệnh gọi trong năm mươi cái bị treo và gọi trang on-call của bạn vào lúc 2 giờ sáng. Các trang Models, Tools và Hooks từ chối làm như vậy. Mỗi trang chia sẻ hình dáng giống nhau, vì vậy bạn chỉ cần học một lần: +- Một **sparkline 24 bin** cho xu hướng ngay lập tức: điều này có đang trở nên tệ hơn không? +- Một **dải chỉ số sức khỏe** với độ trễ p50, p95 và p99, để lần chạy điển hình và đuôi nằm cạnh nhau. +- Một **biểu đồ nhiệt độ trễ**, 24 khoảng thời gian theo các nhóm độ trễ, cho thấy *khi nào* các lệnh gọi chậm được gom cụm. +- Một **dải phân vị**: đường p50 với các dải bóng p25 đến p75 và p10 đến p90 cộng với các chấm p99, để sự phân tán vẫn hiển thị thay vì được lấy trung bình. -- Một **sparkline 24 thùng** cho xu hướng ngay tại một cái nhìn: điều này có đang trở nên tồi tệ hơn không? -- Một **dải chỉ số quan trọng** với độ trễ p50, p95 và p99, vì vậy lần chạy điển hình và phía đuôi ngồi cạnh nhau. -- Một **sơ đồ nhiệt độ trễ**, 24 thùng thời gian theo các thùng độ trễ, cho thấy *khi nào* các lệnh gọi chậm được nhóm lại. -- Một **dải phần trăm**: một dòng p50 với các dải bóng mờ p25 đến p75 và p10 đến p90 và các chấm p99, vì vậy phạm vi vẫn hiển thị thay vì được lấy trung bình. +Một con trỏ di chuột chéo chia sẻ liên kết biểu đồ nhiệt và dải, để một sự tăng đuôi căn chỉnh theo thời gian trên cả hai thay vì ẩn giấu đằng sau một đường trung bình duy nhất. Tìm cả ba trang trong phần **observe** của bảng điều khiển của bạn, mỗi trang được xác định phạm vi cho tổ chức của bạn và có thể lọc theo phạm vi ngày, môi trường, agent và phiên. -Một chữ thập di chuột được chia sẻ liên kết sơ đồ nhiệt và dải, vì vậy một sự tăng đột ngột ở phía đuôi được xếp chồng lên nhau theo thời gian trên cả hai thay vì ẩn đằng sau một dòng giá trị trung bình duy nhất. Tìm cả ba trang trong phần **observe** trên bảng điều khiển của bạn, mỗi trang có phạm vi cho tổ chức của bạn và có thể lọc theo phạm vi ngày, môi trường, agent và phiên. +## Models: xem chính xác mô hình nào tốn kém nhất cho bạn -## Models: xem chính xác mỗi mô hình có giá bao nhiêu cho bạn +Trang Models (được hiển thị ở trên) trả lời hai câu hỏi mà một hóa đơn luôn đặt ra: mô hình nào và bao nhiêu tiền. Bên cạnh chế độ xem độ trễ dùng chung, nó thêm **mức tiêu thụ token cho mỗi mô hình**, **chi phí ước tính** và **mức độ sử dụng cửa sổ ngữ cảnh**, do đó sự tăng trưởng prompt vượt khỏi tầm kiểm soát và sự chèn nén sắp xảy ra đều hiển thị trước khi chúng làm bạn ngạc nhiên. -Trang Models (hiển thị ở trên) trả lời hai câu hỏi mà một hóa đơn luôn đưa ra: mô hình nào và bao nhiêu tiền. Trên cơ sở khung nhìn độ trễ được chia sẻ, nó thêm **tiêu thụ token cho mỗi mô hình**, **chi phí ước tính** và **phần trăm đầy cửa sổ ngữ cảnh**, vì vậy sự tăng trưởng của prompt bất thường và một sự nén sắp xảy ra là hiển thị trước khi chúng gây bất ngờ cho bạn. +Failproof AI Observability tự động nhận dạng các ID mô hình thông thường. Nếu một cửa sổ trông không đúng, hoặc bạn chạy một mô hình riêng của riêng mình, hãy sửa nó hoặc thêm một trong **Settings**, trong **model context windows**, và các số liệu sử dụng sẽ theo dõi. -Failproof AI Observability nhận ra các ID mô hình phổ biến một cách tự động. Nếu một cửa sổ trông không đúng, hoặc bạn chạy một mô hình riêng của riêng bạn, hãy sửa nó hoặc thêm nó trong **Settings**, trong **model context windows**, và các số liệu phần trăm đầy theo sau. +## Tools: phân biệt cái chậm và cái bị hỏng -## Tools: phân biệt cái chậm với cái bị hỏng +Một lệnh gọi công cụ có thể chậm hoặc nó có thể bị hỏng im lặng, và bạn muốn biết cái nào trong vòng vài giây, không phải sau khi đào sâu thông qua nhật ký. -Một lệnh gọi công cụ có thể chậm, hoặc nó có thể đang im lặng thất bại, và bạn muốn biết cái nào trong vòng vài giây, chứ không phải sau khi đào xung quanh các bản ghi. +![Trang Tools hiển thị biểu đồ nhiệt độ trễ và dải phân vị dùng chung bên cạnh sự phân chia thành công/thất bại và một thanh phân phối công cụ](/agenteye/images/tools.png) +*Trang Tools: cùng biểu đồ nhiệt và dải phân vị, cộng với sự phân chia thành công/thất bại và một thanh phân phối công cụ.* -![Trang Tools hiển thị sơ đồ nhiệt độ trễ và dải phần trăm được chia sẻ bên cạnh một sự phân tích bước đầu và thất bại và một thanh phân phối công cụ](/agenteye/images/tools.png) -*Trang Tools: sơ đồ nhiệt và dải phần trăm giống nhau, cộng với sự phân tích bước đầu và thất bại và thanh phân phối công cụ.* +Bên cạnh chế độ xem độ trễ dùng chung, trang Tools thêm **sự phân chia thành công và thất bại** và **thanh phân phối công cụ**, do đó bạn thấy ngay lập tức những công cụ nào bạn phụ thuộc vào nhiều nhất và những công cụ nào đang tiêu tốn ngân sách lỗi của bạn. -Bên cạnh khung nhìn độ trễ được chia sẻ, trang Tools thêm một **sự phân tích bước đầu và thất bại** và một **thanh phân phối công cụ**, vì vậy bạn thấy ngay tại một cái nhìn những công cụ nào bạn dựa vào nhiều nhất và những công cụ nào đang tiêu thụ ngân sách lỗi của bạn. +## Hooks: xác định chính xác hook và trigger -## Hooks: xác định chính xác hook và kích hoạt +Khi một hook vòng đời làm kéo dài một lần chạy, "hooks chậm" không phải là điều bạn có thể hành động. Trang Hooks sẽ đưa bạn đến cái quan trọng. -Khi một hook vòng đời kéo một lần chạy, "hook rất chậm" không phải là điều gì bạn có thể hành động. Trang Hooks giúp bạn đến cái hook quan trọng. +![Trang Hooks hiển thị độ trễ được phân chia theo tên hook và sự kiện trigger trên biểu đồ nhiệt và dải phân vị dùng chung](/agenteye/images/hooks.png) +*Trang Hooks: độ trễ được phân chia theo tên hook và sự kiện trigger.* -![Trang Hooks hiển thị độ trễ được phân tích theo tên hook và sự kiện kích hoạt trên sơ đồ nhiệt và dải phần trăm được chia sẻ](/agenteye/images/hooks.png) -*Trang Hooks: độ trễ được phân tích theo tên hook và sự kiện kích hoạt.* +Trên cùng biểu đồ nhiệt độ trễ và dải phân vị, trang Hooks chia nhỏ hoạt động theo **tên hook** và **sự kiện trigger**, do đó bạn sẽ hạ cánh trên một hook duy nhất và một sự kiện duy nhất cần chú ý. -Trên cùng sơ đồ nhiệt độ trễ và dải phần trăm, trang Hooks chia hoạt động thành **tên hook** và **sự kiện kích hoạt**, vì vậy bạn hạ cánh trên hook đơn lẻ và sự kiện đơn lẻ cần được chú ý. +## Liên quan -## Liên Quan - -- [Event stream](/vi/agenteye/event-stream): dấu vết của từng sự kiện được mã hóa bằng màu trực tiếp. -- [Sessions](/vi/agenteye/sessions): tổng hợp các sự kiện thành một hàng cho mỗi lần chạy và mở biểu đồ thực thi của nó. -- [Error tracking](/vi/agenteye/error-tracking): một bề mặt phân loại duy nhất cho tất cả những gì bảng điều khiển vẽ màu đỏ. -- [Dashboards](/vi/agenteye/dashboards): xem tổng hợp trên toàn bộ đội của bạn. \ No newline at end of file +- [Event stream](/vi/agenteye/event-stream): đường mòn có mã màu sắc trực tiếp của mọi sự kiện. +- [Sessions](/vi/agenteye/sessions): gom các sự kiện thành một hàng cho mỗi lần chạy và mở biểu đồ thực thi của nó. +- [Error tracking](/vi/agenteye/error-tracking): một bề mặt phân loại duy nhất cho mọi thứ mà bảng điều khiển vẽ màu đỏ. +- [Dashboards](/vi/agenteye/dashboards): chế độ xem gom lại trên toàn bộ đội. \ No newline at end of file diff --git a/docs/vi/architecture.mdx b/docs/vi/architecture.mdx index 495f4c66..c6e1be82 100644 --- a/docs/vi/architecture.mdx +++ b/docs/vi/architecture.mdx @@ -4,18 +4,18 @@ description: "Cách hook handler, config loading, và policy evaluation hoạt icon: sitemap --- -Tài liệu này giải thích cách failproofai hoạt động bên trong: cách hệ thống hook chặn các lệnh gọi tool của agent, cách cấu hình được tải và hợp nhất, cách các policy được đánh giá, và cách dashboard giám sát hoạt động của agent. +Tài liệu này giải thích cách failproofai hoạt động bên trong: cách hệ thống hook chặn các lệnh gọi công cụ của agent, cách configuration được tải và hợp nhất, cách các chính sách được đánh giá, và cách dashboard theo dõi hoạt động của agent. --- ## Tổng quan -failproofai có hai hệ thống độc lập: +failproofai có hai subsystem độc lập: -1. **Hook handler** - Một CLI subprocess nhanh mà Claude Code gọi trên mỗi lệnh gọi tool của agent. Đánh giá các policy và trả về quyết định. -2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để giám sát các phiên làm việc của agent và quản lý các policy. +1. **Hook handler** - Một subprocess CLI nhanh mà Claude Code gọi trên mỗi lệnh gọi công cụ của agent. Đánh giá các chính sách và trả về một quyết định. +2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để theo dõi các phiên làm việc của agent và quản lý các chính sách. -Cả hai hệ thống chia sẻ các tệp cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của dự án, nhưng chúng chạy như các tiến trình riêng biệt và chỉ giao tiếp thông qua hệ thống tệp. +Cả hai subsystem chia sẻ các tệp cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của dự án, nhưng chúng chạy dưới dạng các process riêng biệt và chỉ giao tiếp thông qua hệ thống tệp. --- @@ -23,7 +23,7 @@ Cả hai hệ thống chia sẻ các tệp cấu hình trong `~/.failproofai/` v ### Tích hợp với Claude Code -Khi bạn chạy `failproofai policies --install`, nó ghi các mục nhập như thế này vào `~/.claude/settings.json`: +Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các mục nhập như thế này vào `~/.claude/settings.json`: ```json { @@ -44,9 +44,9 @@ Khi bạn chạy `failproofai policies --install`, nó ghi các mục nhập nh } ``` -Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess trước mỗi lệnh gọi tool, truyền một payload JSON trên stdin. +Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess trước mỗi lệnh gọi công cụ, chuyển một payload JSON trên stdin. -### Định dạng payload +### Định dạng Payload ```json { @@ -60,9 +60,9 @@ Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess } ``` -Đối với các sự kiện `PostToolUse`, payload cũng chứa `tool_result` với đầu ra của tool. +Đối với các sự kiện `PostToolUse`, payload cũng chứa `tool_result` với kết quả đầu ra của công cụ. -Handler áp dụng giới hạn stdin 1 MB. Các payload vượt quá giới hạn này bị loại bỏ và tất cả các policy ngầm cho phép. +Handler áp dụng giới hạn stdin 1 MB. Các payload vượt quá giới hạn này sẽ bị loại bỏ và tất cả các chính sách sẽ ngầm cho phép. ### Định dạng phản hồi @@ -85,7 +85,7 @@ Handler áp dụng giới hạn stdin 1 MB. Các payload vượt quá giới h } ``` -**Instruct (bất kỳ sự kiện nào trừ Stop):** +**Instruct (bất kỳ sự kiện nào ngoại trừ Stop):** ```json { "hookSpecificOutput": { @@ -102,25 +102,25 @@ Handler áp dụng giới hạn stdin 1 MB. Các payload vượt quá giới h - Mã thoát: `0` - stdout trống -**Allow với thông báo:** +**Allow with message:** -`allow(message)` cho phép một policy gửi ngữ cảnh thông tin quay lại Claude ngay cả khi thao tác được phép. Hook handler ghi JSON sau đây vào **stdout** (không phải tệp cấu hình — đây là phản hồi của handler đối với Claude Code, giống như các phản hồi deny và instruct ở trên): +`allow(message)` cho phép một chính sách gửi ngữ cảnh thông tin trở lại Claude ngay cả khi hoạt động được cho phép. Hook handler ghi JSON sau đây vào **stdout** (không phải một tệp cấu hình — đây là phản hồi của handler cho Claude Code, giống như các phản hồi deny và instruct ở trên): ```json -// Được ghi vào stdout bởi tiến trình hook handler +// Written to stdout by the hook handler process { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." } } ``` -- Mã thoát: `0` (thao tác được phép) -- Khi nhiều policy trả về `allow` với một thông báo, các thông báo của chúng được nối với dòng mới thành một chuỗi `additionalContext` duy nhất -- Nếu không có policy nào cung cấp thông báo, stdout trống (giống như trước) +- Mã thoát: `0` (hoạt động được cho phép) +- Khi nhiều chính sách trả về `allow` với một thông báo, các thông báo của chúng được nối bằng dòng mới thành một chuỗi `additionalContext` duy nhất +- Nếu không có chính sách nào cung cấp thông báo, stdout trống (giống như trước đó) -### Quy trình xử lý +### Pipeline xử lý -`src/hooks/handler.ts` triển khai toàn bộ quy trình: +`src/hooks/handler.ts` thực hiện toàn bộ pipeline: ```text stdin JSON @@ -139,13 +139,13 @@ stdin JSON → exit ``` -Toàn bộ quy trình chạy dưới 100ms đối với các payload điển hình mà không có cuộc gọi LLM. +Toàn bộ process chạy dưới 100ms cho các payload điển hình mà không có các lệnh gọi LLM. --- -## Tải cấu hình +## Config loading -`src/hooks/hooks-config.ts` triển khai tải cấu hình ba phạm vi. +`src/hooks/hooks-config.ts` thực hiện config loading ba phạm vi. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -153,40 +153,40 @@ Toàn bộ quy trình chạy dưới 100ms đối với các payload điển hì [3] ~/.failproofai/policies-config.json ← global (lowest priority) ``` -Lôgic hợp nhất: -- `enabledPolicies` - hợp nhất loại bỏ trùng lặp trên cả ba tệp -- `policyParams` - mỗi policy là một khóa, tệp đầu tiên định nghĩa nó sẽ thắng hoàn toàn -- `customPoliciesPath` - tệp đầu tiên định nghĩa nó sẽ thắng -- `llm` - tệp đầu tiên định nghĩa nó sẽ thắng +Merge logic: +- `enabledPolicies` - deduplicated union trên cả ba tệp +- `policyParams` - mỗi chính sách, tệp đầu tiên xác định nó thắng hoàn toàn +- `customPoliciesPath` - tệp đầu tiên xác định nó thắng +- `llm` - tệp đầu tiên xác định nó thắng -Dashboard web sử dụng `readHooksConfig()` (toàn cầu chỉ) để đọc và ghi, vì nó không được gọi với project cwd. +Web dashboard sử dụng `readHooksConfig()` (global only) để đọc và ghi, vì nó không được gọi với một project cwd. --- -## Đánh giá policy +## Policy evaluation -`src/hooks/policy-evaluator.ts` chạy các policy theo thứ tự. +`src/hooks/policy-evaluator.ts` chạy các chính sách theo thứ tự. -Đối với mỗi policy: +Đối với mỗi chính sách: -1. Tra cứu lược đồ `params` của policy (nếu có). -2. Đọc `policyParams[policy.name]` từ cấu hình đã hợp nhất. -3. Hợp nhất các giá trị do người dùng cung cấp lên các giá trị mặc định của lược đồ để tạo `ctx.params`. -4. Gọi `policy.fn(ctx)` với ngữ cảnh đã được giải quyết. +1. Tra cứu schema `params` của chính sách (nếu nó có một). +2. Đọc `policyParams[policy.name]` từ config được hợp nhất. +3. Hợp nhất các giá trị do người dùng cung cấp trên các mặc định của schema để tạo ra `ctx.params`. +4. Gọi `policy.fn(ctx)` với ngữ cảnh đã giải quyết. 5. Nếu kết quả là `deny`, dừng ngay lập tức và trả về quyết định đó. 6. Nếu kết quả là `instruct`, tích lũy thông báo và tiếp tục. -7. Nếu kết quả là `allow`, tiếp tục đến policy tiếp theo. +7. Nếu kết quả là `allow`, tiếp tục chính sách tiếp theo. -Sau khi tất cả các policy chạy: -- Nếu bất kỳ `deny` nào được trả về, phát ra phản hồi deny. -- Nếu bất kỳ giá trị trả về `instruct` nào được thu thập, phát ra một phản hồi instruct duy nhất với tất cả các thông báo được nối. -- Nếu không, phát ra phản hồi allow (stdout trống, thoát 0). +Sau khi tất cả các chính sách chạy: +- Nếu bất kỳ `deny` nào được trả về, phát hành phản hồi deny. +- Nếu bất kỳ kết quả `instruct` nào được thu thập, phát hành một phản hồi instruct duy nhất với tất cả các thông báo được nối. +- Nếu không, phát hành phản hồi allow (stdout trống, exit 0). --- -## Các policy tích hợp +## Builtin policies -`src/hooks/builtin-policies.ts` định nghĩa tất cả 39 policy tích hợp như các đối tượng `BuiltinPolicyDefinition`: +`src/hooks/builtin-policies.ts` xác định tất cả 39 chính sách được xây dựng sẵn dưới dạng các đối tượng `BuiltinPolicyDefinition`: ```typescript interface BuiltinPolicyDefinition { @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -Các policy chấp nhận `params` khai báo `PolicyParamsSchema` với các kiểu và giá trị mặc định cho mỗi tham số. Trình đánh giá policy tiêm các giá trị đã được giải quyết vào `ctx.params` trước khi gọi `fn`. Các hàm policy đọc `ctx.params` mà không cần bảo vệ null vì các giá trị mặc định luôn được áp dụng trước. +Các chính sách chấp nhận `params` khai báo một `PolicyParamsSchema` với các kiểu và giá trị mặc định cho mỗi tham số. Policy evaluator chèn các giá trị đã giải quyết vào `ctx.params` trước khi gọi `fn`. Các hàm chính sách đọc `ctx.params` mà không cần null-guarding vì các giá trị mặc định luôn được áp dụng trước tiên. -So khớp mẫu bên trong các policy sử dụng các token lệnh được phân tích cú pháp (argv), không phải so khớp chuỗi thô. Điều này ngăn chặn vượt qua thông qua injection của toán tử shell (ví dụ: một mẫu cho `sudo systemctl status *` không thể bị vượt qua bằng cách thêm `; rm -rf /` vào lệnh). +Pattern matching bên trong các chính sách sử dụng các token lệnh được phân tích cú pháp (argv), không phải so khớp chuỗi thô. Điều này ngăn chặn bypass thông qua shell operator injection (ví dụ: một pattern cho `sudo systemctl status *` không thể bị bypass bằng cách thêm `; rm -rf /` vào lệnh). --- -## Các policy tùy chỉnh +## Custom policies -`src/hooks/custom-hooks-registry.ts` triển khai một sổ đăng ký được hỗ trợ bởi `globalThis`: +`src/hooks/custom-hooks-registry.ts` thực hiện một registry được hỗ trợ bởi `globalThis`: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` tải tệp policy của người dùng: +`src/hooks/custom-hooks-loader.ts` tải tệp chính sách của người dùng: -1. Đọc `customPoliciesPath` từ cấu hình; bỏ qua nếu không có. -2. Giải quyết đến đường dẫn tuyệt đối; kiểm tra tệp tồn tại. -3. Viết lại tất cả các import `from "failproofai"` thành đường dẫn dist thực tế để `customPolicies` được giải quyết thành cùng một sổ đăng ký `globalThis`. -4. Viết lại một cách đệ quy các import cục bộ chuyển tiếp để đảm bảo tương thích ESM. -5. Ghi các tệp `.mjs` tạm thời và `import()` tệp mục nhập. -6. Gọi `getCustomHooks()` để truy xuất các hook được đăng ký. -7. Dọn sạch tất cả các tệp tạm thời trong khối `finally`. +1. Đọc `customPoliciesPath` từ config; bỏ qua nếu không có. +2. Phân giải thành đường dẫn tuyệt đối; kiểm tra tệp tồn tại. +3. Viết lại tất cả các import `from "failproofai"` thành đường dẫn dist thực tế để `customPolicies` giải quyết thành registry `globalThis` tương tự. +4. Viết lại một cách đệ quy các import cục bộ bắc cầu để đảm bảo tính tương thích ESM. +5. Ghi các tệp `.mjs` tạm thời và `import()` tệp nhập. +6. Gọi `getCustomHooks()` để lấy các hook đã đăng ký. +7. Dọn dẹp tất cả các tệp tạm thời trong một khối `finally`. -Khi có bất kỳ lỗi nào (tệp không tìm thấy, lỗi cú pháp, lỗi import), lỗi được ghi vào `~/.failproofai/hook.log` và trình tải trả về một mảng trống. Các policy tích hợp không bị ảnh hưởng. +Khi có bất kỳ lỗi nào (tệp không được tìm thấy, lỗi cú pháp, lỗi import), lỗi sẽ được ghi vào `~/.failproofai/hook.log` và loader trả về một mảng trống. Các chính sách được xây dựng sẵn không bị ảnh hưởng. -Các policy tùy chỉnh được đánh giá sau tất cả các policy tích hợp. Một policy tùy chỉnh `deny` vẫn làm ngắn mạch các policy tùy chỉnh tiếp theo (nhưng tất cả các policy tích hợp đã chạy tại thời điểm đó). +Các chính sách tùy chỉnh được đánh giá sau tất cả các chính sách được xây dựng sẵn. Một chính sách tùy chỉnh `deny` vẫn short-circuit các chính sách tùy chỉnh khác (nhưng tất cả các builtin đã chạy vào thời điểm đó). --- -## Ghi nhật ký hoạt động +## Activity logging -Sau mỗi sự kiện hook, handler thêm một dòng JSONL vào `~/.failproofai/hook-activity/current.jsonl`, được xoay thành `page--.jsonl` khi nó đạt tới một trang: +Sau mỗi sự kiện hook, handler thêm một dòng JSONL vào `~/.failproofai/hook-activity/current.jsonl`, dòng này xoay vào `page--.jsonl` khi nó đạt một page: ```json { @@ -258,11 +258,11 @@ Sau mỗi sự kiện hook, handler thêm một dòng JSONL vào `~/.failproofai } ``` -Một dòng cho mỗi policy đã đưa ra quyết định không phải allow. Các quyết định Allow không được ghi lại (để giữ tệp nhỏ). +Một dòng cho mỗi chính sách đã đưa ra quyết định không phải allow. Các quyết định Allow không được ghi nhật ký (để giữ tệp nhỏ). --- -## Kiến trúc dashboard +## Kiến trúc Dashboard Dashboard là một ứng dụng **Next.js 16** sử dụng App Router với React Server Components và Server Actions. @@ -284,18 +284,18 @@ app/ download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` -**Luồng dữ liệu:** +**Data flow:** -- Các thành phần Page gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc dữ liệu dự án/phiên trực tiếp từ hệ thống tệp (không có lớp API cho các lần đọc). -- Trang Policies sử dụng Server Actions cho tất cả các thay đổi (toggle, cập nhật params, cài đặt/loại bỏ). -- Trình xem phiên phân tích định dạng JSONL transcript của Claude và hiển thị một dòng thời gian của các thông báo và lệnh gọi tool. +- Page components gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc dữ liệu dự án/phiên trực tiếp từ hệ thống tệp (không có API layer cho đọc). +- Trang Policies sử dụng Server Actions cho tất cả các đột biến (toggle, params update, install/remove). +- Session viewer phân tích định dạng JSONL transcript của Claude và hiển thị một timeline của các thông báo và lệnh gọi công cụ. **Các quyết định thiết kế chính:** -- Không có cơ sở dữ liệu - tất cả trạng thái persistent nằm trong các tệp thuần (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions cho các thay đổi - không cần REST API cho các hoạt động CRUD. -- React Server Components cho các trang đọc - tải ban đầu nhanh hơn, không có client bundle cho việc lấy dữ liệu. -- Chỉ các thành phần client nơi cần tính tương tác (chuyển đổi policy, tìm kiếm hoạt động, trình xem nhật ký). +- Không có cơ sở dữ liệu - tất cả trạng thái liên tục nằm trong các tệp thuần túy (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions cho các đột biến - không cần REST API cho các hoạt động CRUD. +- React Server Components cho các trang đọc - tải ban đầu nhanh hơn, không có client bundle cho việc nạp dữ liệu. +- Client components chỉ khi cần tính tương tác (policy toggles, activity search, log viewer). --- diff --git a/docs/vi/built-in-policies.mdx b/docs/vi/built-in-policies.mdx index d31b4d0d..943d5de0 100644 --- a/docs/vi/built-in-policies.mdx +++ b/docs/vi/built-in-policies.mdx @@ -1,39 +1,39 @@ --- -title: Chính sách tích hợp sẵn -description: "Tất cả 39 chính sách tích hợp sẵn giúp bắt các lỗi phổ biến của agent" +title: Các Chính Sách Tích hợp +description: "Tất cả 39 chính sách tích hợp giúp phát hiện các chế độ hỏng phổ biến của agent" icon: shield --- -failproofai được cung cấp kèm 39 chính sách tích hợp sẵn giúp bắt các lỗi phổ biến của agent. Mỗi chính sách kích hoạt trên một loại sự kiện hook cụ thể và tên công cụ. Mười chín chính sách chấp nhận các tham số cho phép bạn điều chỉnh hành vi của chúng mà không cần viết code. Năm chính sách quy trình làm việc buộc phải thực hiện commit → push → PR → CI trước khi Claude dừng lại. +failproofai được cung cấp với 39 chính sách tích hợp giúp phát hiện các chế độ hỏng phổ biến của agent. Mỗi chính sách hoạt động trên một loại sự kiện hook cụ thể và tên công cụ. Mười chín chính sách chấp nhận các tham số cho phép bạn tinh chỉnh hành vi của chúng mà không cần viết mã. Năm chính sách quy trình làm việc thực thi quy trình commit → push → PR → CI trước khi Claude dừng. --- ## Tổng quan -Các chính sách được nhóm thành các danh mục: +Các chính sách được phân loại thành các danh mục: -| Danh mục | Chính sách | Loại Hook | -|----------|----------|-----------| -| [Lệnh nguy hiểm](#lệnh-nguy-hiểm) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | -| [Lệnh cơ sở hạ tầng](#lệnh-cơ-sở-hạ-tầng) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Bí mật (sanitizer)](#bí-mật-sanitizer) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | -| [Môi trường](#môi-trường) | block-env-files, protect-env-vars | PreToolUse | -| [Truy cập file](#truy-cập-file) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| Danh mục | Chính sách | Loại hook | +|----------|-----------|-----------| +| [Lệnh nguy hiểm](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | +| [Lệnh cơ sở hạ tầng](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [Bí mật (bộ vệ sinh)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Môi trường](#environment) | block-env-files, protect-env-vars | PreToolUse | +| [Truy cập tệp](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | -| [Cơ sở dữ liệu](#cơ-sở-dữ-liệu) | warn-destructive-sql, warn-schema-alteration | PreToolUse | -| [Cảnh báo](#cảnh-báo) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [Trình quản lý gói](#trình-quản-lý-gói) | prefer-package-manager | PreToolUse | -| [Quy trình làm việc](#quy-trình-làm-việc) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | +| [Cơ sở dữ liệu](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | +| [Cảnh báo](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | +| [Trình quản lý gói](#package-managers) | prefer-package-manager | PreToolUse | +| [Quy trình làm việc](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — ngăn agent tiếp tục. -- **`warn-`** — cung cấp bối cảnh bổ sung để agent có thể tự sửa lỗi. -- **`sanitize-`** — xóa sạch dữ liệu nhạy cảm từ đầu ra công cụ trước khi agent nhìn thấy. +- **`block-`** — dừng agent không được tiếp tục. +- **`warn-`** — cung cấp cho agent ngữ cảnh bổ sung để nó có thể tự sửa chữa. +- **`sanitize-`** — xóa dữ liệu nhạy cảm khỏi kết quả công cụ trước khi agent nhìn thấy. ### Không gian tên -Mỗi chính sách tồn tại trong một vị trí `/`. Các chính sách tích hợp sẵn thuộc không gian tên **`failproofai/`** — ví dụ: `failproofai/sanitize-jwt`. Không gian tên ngăn chặn xung đột khi bạn cũng tải các chính sách tùy chỉnh hoặc của bên thứ ba có tên ngắn tương tự. +Mỗi chính sách nằm trong một khe **`/`**. Các chính sách tích hợp thuộc về không gian tên **`failproofai/`** — ví dụ, `failproofai/sanitize-jwt`. Không gian tên ngăn chặn va chạm khi bạn cũng tải các chính sách tùy chỉnh hoặc của bên thứ ba có tên ngắn tương tự. -Trong cấu hình của bạn, bạn có thể tham chiếu đến một chính sách tích hợp bằng tên ngắn hoặc tên đủ tiêu chuẩn; cả hai dạng đều phân giải thành cùng một chính sách: +Trong cấu hình của bạn, bạn có thể tham chiếu một chính sách tích hợp bằng tên ngắn hoặc tên đủ điều kiện; cả hai hình thức đều giải quyết cùng một chính sách: ```json { @@ -44,39 +44,40 @@ Trong cấu hình của bạn, bạn có thể tham chiếu đến một chính } ``` -Nếu tên không có `/`, failproofai coi nó thuộc không gian tên mặc định `failproofai`. Tên đã chứa `/` (ví dụ: `myorg/foo`, `custom/my-hook`) được giữ nguyên. +Nếu tên không có `/`, failproofai sẽ coi nó thuộc về không gian tên mặc định `failproofai`. Tên đã chứa `/` (ví dụ: `myorg/foo`, `custom/my-hook`) được giữ nguyên. + - **`require-`** — chặn sự kiện Stop cho đến khi các điều kiện được đáp ứng. --- -Mỗi chính sách hỗ trợ một trường `hint` tùy chọn trong `policyParams`. Gợi ý được nối thêm vào thông báo từ chối hoặc hướng dẫn mà Claude nhìn thấy, cung cấp hướng dẫn có thể thực hiện được mà không cần sửa đổi code chính sách. Hoạt động với các chính sách tích hợp sẵn, tùy chỉnh và quy ước. Xem [Cấu hình → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. +Mỗi chính sách hỗ trợ một trường `hint` tùy chọn trong `policyParams`. Hint được thêm vào thông báo deny hoặc instruct mà Claude nhìn thấy, cung cấp hướng dẫn có thể hành động mà không cần sửa đổi mã chính sách. Hoạt động với các chính sách tích hợp, tùy chỉnh và quy ước. Xem [Configuration → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. --- ## Lệnh nguy hiểm -Ngăn agent chạy các hoạt động khó hoàn tác hoặc có thể gây hại cho hệ thống chủ. +Ngăn chặn các agent chạy các hoạt động khó hoàn tác hoặc có thể làm hỏng hệ thống chủ. ### `block-sudo` **Sự kiện:** PreToolUse (Bash) **Mặc định:** Từ chối bất kỳ lệnh `sudo` hoặc `doas` nào. -Chặn một lệnh chạy một tệp nhị phân nâng cao quyền **ở vị trí lệnh**. Khớp là có cấu trúc hơn là văn bản: lệnh được chia thành các đoạn theo cách shell, gán tiền tố (`FOO=bar`), chuyển hướng và chạy với cờ của chúng (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) được bỏ qua, và tệp nhị phân kết quả được so sánh theo **tên cơ sở**. Do đó, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` và `bash -c "sudo …"` đều bị từ chối, và `doas` được coi là cùng một khả năng với tên khác. +Chặn một lệnh chạy tệp nhị phân nâng cao **ở vị trí lệnh**. Khớp là cấu trúc chứ không phải văn bản: lệnh được chia thành các phân đoạn theo cách shell sẽ làm, các bài tập tiền tố (`FOO=bar`), chuyển hướng và bộ chạy với các cờ của chúng (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) được loại bỏ, và tệp nhị phân kết quả được so sánh theo **basename**. Vì vậy, `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` và `bash -c "sudo …"` đều bị từ chối, và `doas` được coi là cùng một khả năng dưới một tên khác. -Vì nó neo trên vị trí lệnh thay vì từ xuất hiện ở bất kỳ đâu, nó **không** kích hoạt trên các lệnh chỉ đề cập đến nó — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, hoặc một thay thế `grep` chứa từ này đều chạy bình thường. +Vì nó neo vào vị trí lệnh chứ không phải trên từ xuất hiện ở bất kỳ nơi nào, nó **không** hoạt động trên các lệnh chỉ đề cập đến nó — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, hoặc một phép thay thế `grep` chứa từ đó đều chạy bình thường. -Điều này dừng lại cố gắng rõ ràng; nó không đóng lớp. Một agent có thể chạy shell tùy ý vẫn có thể đạt được nâng cao quyền gián tiếp — thông qua một biến (`S=sudo; $S …`), một pipe giải mã base64 hoặc một tập lệnh wrapper trên đĩa — vì không có kiểm tra chuỗi lệnh duy nhất nào có thể theo dõi những điều đó. Hãy coi đây là một hàng rào bảo vệ chống lại các lỗi và nâng cao quyền bình thường, chứ không phải như một ranh giới bảo mật chống lại một agent quyết tâm. Một ranh giới thực tế phải được thực thi dưới shell. +Điều này dừng nỗ lực rõ ràng; nó không đóng lớp. Một agent có thể chạy shell tùy ý vẫn có thể đạt được nâng cao gián tiếp — thông qua một biến (`S=sudo; $S …`), một đường ống được giải mã base64, hoặc một tập lệnh trình bao quanh trên đĩa — vì không có kiểm tra chuỗi lệnh đơn nào có thể theo dõi những điều đó. Hãy coi đây là một hàng rào bảo vệ chống lại sai lầm và nâng cao thỏa thuận, không phải là ranh giới bảo mật chống lại một agent quyết tâm. Ranh giới thực sự phải được thực thi dưới shell. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh chính xác được phép. Mỗi mục được so sánh với các token argv được phân tích cú pháp. | +| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh chính xác được phép. Mỗi mục được so khớp với các token argv được phân tích cú pháp. | **Ví dụ:** @@ -93,7 +94,7 @@ Vì nó neo trên vị trí lệnh thay vì từ xuất hiện ở bất kỳ đ Với cấu hình này, `sudo systemctl status nginx` được phép, nhưng `sudo rm /etc/hosts` bị từ chối. -Các mẫu được so sánh với các token được phân tích cú pháp, không phải chuỗi lệnh thô. Điều này ngăn chặn bypass thông qua các toán tử shell nối (ví dụ: `sudo systemctl status x; rm -rf /` không khớp với `sudo systemctl status *`). +Các mẫu được so khớp với các token được phân tích cú pháp, không phải chuỗi lệnh thô. Điều này ngăn chặn việc bypass thông qua các toán tử shell được nối thêm (ví dụ: `sudo systemctl status x; rm -rf /` không khớp với `sudo systemctl status *`). --- @@ -107,7 +108,7 @@ Các mẫu được so sánh với các token được phân tích cú pháp, kh | Tham số | Loại | Mặc định | Mô tả | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Các đường dẫn an toàn để xóa đệ quy (ví dụ: `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Đường dẫn an toàn để xóa đệ quy (ví dụ: `/tmp`). | **Ví dụ:** @@ -144,11 +145,11 @@ Không có tham số. ### `block-self-pause` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối `failproofai config --pause`, tạm dừng thực thi cho một phiên. Tạm dừng là quyết định của con người — một agent có khả năng chạy nó có thể tắt mọi chính sách khác bằng một lệnh duy nhất. +**Mặc định:** Từ chối `failproofai config --pause`, tạm dừng thực thi cho một phiên. Tạm dừng là một quyết định của con người — một agent có thể chạy nó có thể tắt mọi chính sách khác bằng một lệnh duy nhất. -Hẹp hơn [`block-failproofai-commands`](#block-failproofai-commands) có mục đích, và không được bao phủ bởi nó: chính sách đó neo trên một ranh giới lệnh, do đó `npx -y failproofai config --pause` không khớp với nó, và vì rộng nên thường bị tắt để agent có thể chạy `failproofai audit`. `--resume` và `--status` được phép — cả hai đều không loại bỏ thực thi. +Hẹp hơn so với [`block-failproofai-commands`](#block-failproofai-commands) có mục đích, và không được bao phủ bởi nó: chính sách đó neo vào ranh giới lệnh, vì vậy `npx -y failproofai config --pause` không khớp với nó, và vì nó rộng nên thường bị tắt để các agent có thể chạy `failproofai audit`. `--resume` và `--status` được cho phép — không ai loại bỏ thực thi. -Điều này dừng lại cố gắng trực tiếp, không phải toàn bộ lớp: một agent vẫn có thể đạt được trạng thái tương tự thông qua một bí danh hoặc tập lệnh wrapper. Đóng nó hoàn toàn yêu cầu tạm dừng không thể tiếp cận từ lệnh công cụ. +Điều này dừng nỗ lực trực tiếp, không phải toàn bộ lớp: một agent vẫn có thể đạt đến cùng một trạng thái thông qua một bí danh hoặc một tập lệnh bao quanh. Đóng nó hoàn toàn yêu cầu tạm dừng không thể truy cập được từ lệnh gọi công cụ. Không có tham số. @@ -156,14 +157,14 @@ Không có tham số. ## Lệnh cơ sở hạ tầng -Ngăn agent mã hóa chạy CLI cơ sở hạ tầng hoặc kích hoạt đường ống CI/CD. Tất cả các chính sách trong danh mục này là **opt-in** (`defaultEnabled: false`) — các agent có nhu cầu hợp pháp để gọi `kubectl`, `terraform`, v.v. sẽ không bị gián đoạn trừ khi bạn bật chính sách. Khi bật, mọi lệnh gọi CLI được khớp bị từ chối trừ khi lệnh khớp với một mục trong `allowPatterns`. +Ngăn chặn các agent mã hóa chạy các CLI cơ sở hạ tầng hoặc kích hoạt đường dẫn CI/CD. Tất cả các chính sách trong danh mục này là **tùy chọn** (`defaultEnabled: false`) — các agent cần gọi `kubectl`, `terraform`, v.v. sẽ không bị gián đoạn trừ khi bạn bật chính sách. Khi được bật, mọi lệnh gọi của CLI phù hợp bị từ chối trừ khi lệnh khớp với một mục trong `allowPatterns`. -Ngữ pháp mẫu giống như [`block-sudo`](#block-sudo): các token được so sánh với argv được phân tích cú pháp, `*` là ký tự đại diện cho một token và bất kỳ lệnh nào chứa một toán tử shell độc lập (`&&`, `||`, `|`, `;`) hoặc token với siêu ký tự shell nhúng bị từ chối trước khớp danh sách cho phép để ngăn chặn bypass tiêm. +Ngữ pháp mẫu giống như [`block-sudo`](#block-sudo): các token được so khớp với argv được phân tích cú pháp, `*` là ký tự đại diện cho một token, và bất kỳ lệnh nào chứa một toán tử shell độc lập (`&&`, `||`, `|`, `;`) hoặc một token có các ký tự metacharacter shell được nhúng bị từ chối trước khi khớp danh sách cho phép để ngăn chặn việc bypass injection. ### `block-kubectl` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối bất kỳ lệnh gọi `kubectl` nào. +**Mặc định:** Từ chối bất kỳ lệnh `kubectl` nào. **Tham số:** @@ -190,7 +191,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply ### `block-terraform` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối bất kỳ lệnh gọi `terraform` hoặc `tofu` (OpenTofu) nào. +**Mặc định:** Từ chối bất kỳ lệnh `terraform` hoặc `tofu` (OpenTofu) nào. **Tham số:** @@ -215,7 +216,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply ### `block-aws-cli` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối bất kỳ lệnh gọi CLI `aws` nào. +**Mặc định:** Từ chối bất kỳ lệnh `aws` CLI nào. **Tham số:** @@ -240,7 +241,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply ### `block-gcloud` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối bất kỳ lệnh gọi CLI `gcloud` (Google Cloud) nào. +**Mặc định:** Từ chối bất kỳ lệnh `gcloud` (Google Cloud) CLI nào. **Tham số:** @@ -265,7 +266,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply ### `block-az-cli` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối bất kỳ lệnh gọi CLI `az` (Azure) nào. +**Mặc định:** Từ chối bất kỳ lệnh `az` (Azure) CLI nào. **Tham số:** @@ -290,7 +291,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply ### `block-helm` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối bất kỳ lệnh gọi `helm` nào. +**Mặc định:** Từ chối bất kỳ lệnh `helm` nào. **Tham số:** @@ -315,7 +316,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply ### `block-gh-pipeline` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối các lệnh con `gh` CLI sau đây thay đổi trạng thái hoặc kích hoạt đường ống: +**Mặc định:** Từ chối các lệnh phụ `gh` CLI sau thay đổi trạng thái hoặc kích hoạt quy trình: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -324,13 +325,13 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply - `gh cache delete` - `gh secret set`, `gh secret delete` -Các lệnh con `gh` chỉ đọc như `gh pr view`, `gh pr list`, `gh run list`, `gh release view` và `gh api repos/.../...` **không** được khớp bởi chính sách này — chúng thường cần thiết cho kiểm tra quy trình làm việc (bao gồm cả `require-ci-green-before-stop` của failproofai). +Các lệnh phụ `gh` chỉ đọc như `gh pr view`, `gh pr list`, `gh run list`, `gh release view` và `gh api repos/.../...` **không** được khớp bởi chính sách này — chúng thường cần cho các kiểm tra quy trình (bao gồm `require-ci-green-before-stop` của chính failproofai). **Tham số:** | Tham số | Loại | Mặc định | Mô tả | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Lệnh gọi tập lệnh cụ thể được phép mặc dù chúng sẽ bị từ chối. | +| `allowPatterns` | `string[]` | `[]` | Các lệnh gọi tập lệnh cụ thể để cho phép mặc dù chúng sẽ bị từ chối. | **Ví dụ:** @@ -346,14 +347,14 @@ Các lệnh con `gh` chỉ đọc như `gh pr view`, `gh pr list`, `gh run list` --- -## Bí mật (sanitizer) +## Bí mật (bộ vệ sinh) -Ngăn agent rò rỉ thông tin xác thực vào bối cảnh hoặc đầu ra của chúng. Các chính sách sanitizer kích hoạt trên các sự kiện **PostToolUse**. Khi Claude chạy lệnh Bash, đọc file hoặc gọi bất kỳ công cụ nào, các chính sách này kiểm tra đầu ra trước khi nó được trả lại cho Claude. Nếu phát hiện mẫu bí mật, chính sách trả lại quyết định từ chối ngăn chặn đầu ra được truyền lại. +Ngăn chặn các agent rò rỉ thông tin xác thực vào ngữ cảnh hoặc đầu ra của chúng. Các chính sách vệ sinh hoạt động trên các sự kiện **PostToolUse**. Khi Claude chạy lệnh Bash, đọc tệp hoặc gọi bất kỳ công cụ nào, các chính sách này kiểm tra kết quả trước khi nó được trả về Claude. Nếu phát hiện mẫu bí mật, chính sách sẽ trả về quyết định từ chối ngăn chặn kết quả được chuyển lại. ### `sanitize-jwt` -**Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redacts các token JWT (ba đoạn base64url được phân tách bằng `.`). +**Sự kiện:** PostToolUse (tất cả các công cụ) +**Mặc định:** Redact các token JWT (ba phân đoạn base64url được phân tách bằng `.`). Không có tham số. @@ -361,8 +362,8 @@ Không có tham số. ### `sanitize-api-keys` -**Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redacts các định dạng khóa API phổ biến: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), khóa truy cập AWS (`AKIA`), khóa Stripe (`sk_live_`, `sk_test_`), và khóa API Google (`AIza`). +**Sự kiện:** PostToolUse (tất cả các công cụ) +**Mặc định:** Redact các định dạng khóa API phổ biến: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), Khóa truy cập AWS (`AKIA`), Khóa Stripe (`sk_live_`, `sk_test_`) và Khóa API Google (`AIza`). **Tham số:** @@ -389,8 +390,8 @@ Không có tham số. ### `sanitize-connection-strings` -**Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redacts chuỗi kết nối cơ sở dữ liệu chứa thông tin xác thực nhúng (ví dụ: `postgresql://user:password@host/db`). +**Sự kiện:** PostToolUse (tất cả các công cụ) +**Mặc định:** Redact các chuỗi kết nối cơ sở dữ liệu chứa thông tin xác thực nhúng (ví dụ: `postgresql://user:password@host/db`). Không có tham số. @@ -398,8 +399,8 @@ Không có tham số. ### `sanitize-private-key-content` -**Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redacts các khối PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, v.v.). +**Sự kiện:** PostToolUse (tất cả các công cụ) +**Mặc định:** Redact các khối PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, v.v.). Không có tham số. @@ -407,8 +408,8 @@ Không có tham số. ### `sanitize-bearer-tokens` -**Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redacts các header `Authorization: Bearer ` trong đó token là 20 hoặc nhiều ký tự. +**Sự kiện:** PostToolUse (tất cả các công cụ) +**Mặc định:** Redact tiêu đề `Authorization: Bearer ` trong đó token là 20 hoặc nhiều ký tự. Không có tham số. @@ -416,14 +417,14 @@ Không có tham số. ## Môi trường -Bảo vệ cấu hình môi trường nhạy cảm khỏi bị agent đọc hoặc làm lộ. +Bảo vệ cấu hình môi trường nhạy cảm khỏi được đọc hoặc tiếp xúc bởi các agent. ### `block-env-files` **Sự kiện:** PreToolUse (Bash, Read) -**Mặc định:** Từ chối đọc file `.env` thông qua `cat .env`, gọi công cụ Read với `.env` làm đường dẫn file, v.v. +**Mặc định:** Từ chối đọc các tệp `.env` thông qua `cat .env`, lệnh gọi công cụ Read với `.env` làm đường dẫn tệp, v.v. -Không chặn `.envrc` hoặc các file liên quan môi trường khác - chỉ các file tên chính xác là `.env`. +Không chặn `.envrc` hoặc các tệp khác liên quan đến môi trường - chỉ các tệp được đặt tên chính xác là `.env`. Không có tham số. @@ -432,26 +433,26 @@ Không có tham số. ### `protect-env-vars` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối các lệnh in ra các biến môi trường: `printenv`, `env`, `echo $VAR`. +**Mặc định:** Từ chối các lệnh in biến môi trường: `printenv`, `env`, `echo $VAR`. Không có tham số. --- -## Truy cập file +## Truy cập tệp -Giữ agent làm việc trong ranh giới dự án và tránh xa file nhạy cảm. +Giữ các agent hoạt động bên trong ranh giới dự án và tránh xa các tệp nhạy cảm. ### `block-read-outside-cwd` **Sự kiện:** PreToolUse (Read, Bash) -**Mặc định:** Từ chối đọc file ngoài thư mục gốc dự án. Ranh giới là `CLAUDE_PROJECT_DIR` (được đặt một lần mỗi phiên bởi Claude Code), với fallback thành thư mục làm việc hiện tại của phiên khi biến đó không được đặt. Sử dụng thư mục gốc dự án thay vì `cwd` trực tiếp có nghĩa là ranh giới vẫn ổn định ngay cả sau khi Claude `cd` vào một thư mục con. +**Mặc định:** Từ chối đọc các tệp bên ngoài thư mục gốc dự án. Ranh giới là `CLAUDE_PROJECT_DIR` (được đặt một lần cho mỗi phiên bởi Claude Code), với fallback đến thư mục làm việc hiện tại của phiên khi biến đó không được đặt. Sử dụng thư mục gốc dự án chứ không phải `cwd` trực tiếp có nghĩa là ranh giới vẫn ổn định ngay cả sau khi Claude `cd` vào một thư mục con. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Tiền tố đường dẫn tuyệt đối được phép ngay cả khi ngoài thư mục gốc dự án. | +| `allowPaths` | `string[]` | `[]` | Tiền tố đường dẫn tuyệt đối được phép ngay cả khi ở bên ngoài thư mục gốc dự án. | **Ví dụ:** @@ -470,13 +471,13 @@ Giữ agent làm việc trong ranh giới dự án và tránh xa file nhạy c ### `block-secrets-write` **Sự kiện:** PreToolUse (Write, Edit) -**Mặc định:** Từ chối ghi vào file thường được dùng cho khóa riêng tư và chứng chỉ: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Mặc định:** Từ chối ghi vào các tệp thường được sử dụng cho khóa riêng tư và chứng chỉ: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Các mẫu tên file bổ sung (kiểu glob) cần chặn. | +| `additionalPatterns` | `string[]` | `[]` | Các mẫu tên tệp bổ sung (kiểu glob) để chặn. | **Ví dụ:** @@ -494,7 +495,7 @@ Giữ agent làm việc trong ranh giới dự án và tránh xa file nhạy c ## Git -Ngăn chặn đẩy ngẫu nhiên, force-push và lỗi nhánh khó hoàn tác. +Ngăn chặn các push accidental, force-push và sai lầm nhánh khó hoàn tác. ### `block-push-master` @@ -520,7 +521,7 @@ Ngăn chặn đẩy ngẫu nhiên, force-push và lỗi nhánh khó hoàn tác. ``` -Để cho phép đẩy đến tất cả các nhánh (tương đương với vô hiệu hóa chính sách này mà không loại bỏ khỏi `enabledPolicies`), đặt `protectedBranches: []`. +Để cho phép đẩy đến tất cả các nhánh (hiệu quả vô hiệu hóa chính sách này mà không loại bỏ nó khỏi `enabledPolicies`), đặt `protectedBranches: []`. --- @@ -528,7 +529,7 @@ Ngăn chặn đẩy ngẫu nhiên, force-push và lỗi nhánh khó hoàn tác. ### `block-work-on-main` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối `git commit`, `git merge`, `git rebase` và `git cherry-pick` khi cây làm việc ở trên `main` hoặc `master`. Tạo và chuyển nhánh (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) không bị ảnh hưởng. +**Mặc định:** Từ chối `git commit`, `git merge`, `git rebase` và `git cherry-pick` trong khi cây làm việc ở trên `main` hoặc `master`. Tạo và chuyển nhánh (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) không bị ảnh hưởng. **Tham số:** @@ -543,7 +544,7 @@ Ngăn chặn đẩy ngẫu nhiên, force-push và lỗi nhánh khó hoàn tác. **Sự kiện:** PreToolUse (Bash) **Mặc định:** Từ chối `git push --force` và `git push -f`. -Không có tham số riêng của chính sách. Sử dụng [`hint`](/vi/configuration#hint-cross-cutting) cross-cutting để gợi ý thay thế: +Không có tham số chính sách cụ thể. Sử dụng [`hint`](/vi/configuration#hint-cross-cutting) cắt ngang để đề xuất các lựa chọn thay thế: ```json { @@ -560,7 +561,7 @@ Không có tham số riêng của chính sách. Sử dụng [`hint`](/vi/configu ### `warn-git-amend` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude cẩn thận khi chạy `git commit --amend`. Không chặn lệnh. +**Mặc định:** Hướng dẫn Claude thận trọng khi chạy `git commit --amend`. Không chặn lệnh. Không có tham số. @@ -578,7 +579,7 @@ Không có tham số. ### `warn-all-files-staged` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude xem lại những gì nó đang tạo staging khi chạy `git add -A` hoặc `git add .`. Không chặn lệnh. +**Mặc định:** Hướng dẫn Claude xem xét những gì nó đang stage khi chạy `git add -A` hoặc `git add .`. Không chặn lệnh. Không có tham số. @@ -586,12 +587,12 @@ Không có tham số. ## Cơ sở dữ liệu -Bắt các hoạt động SQL tàn phá trước khi chúng thực thi chống lại cơ sở dữ liệu của bạn. +Bắt các hoạt động SQL tàn phá trước khi chúng thực thi với cơ sở dữ liệu của bạn. ### `warn-destructive-sql` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy SQL chứa `DROP TABLE`, `DROP DATABASE` hoặc `DELETE` không có mệnh đề `WHERE`. +**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy SQL chứa `DROP TABLE`, `DROP DATABASE` hoặc `DELETE` mà không có mệnh đề `WHERE`. Không có tham số. @@ -600,7 +601,7 @@ Không có tham số. ### `warn-schema-alteration` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy các câu lệnh `ALTER TABLE`. +**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy các lệnh `ALTER TABLE`. Không có tham số. @@ -608,18 +609,18 @@ Không có tham số. ## Cảnh báo -Cung cấp cho agent bối cảnh bổ sung trước các hoạt động có rủi ro tiềm ẩn nhưng không tàn phá. +Cung cấp cho các agent ngữ cảnh bổ sung trước khi thực hiện các hoạt động có tiềm năng rủi ro nhưng không phá hủy. ### `warn-large-file-write` **Sự kiện:** PreToolUse (Write) -**Mặc định:** Hướng dẫn Claude xác nhận trước khi ghi file lớn hơn 1024 KB. +**Mặc định:** Hướng dẫn Claude xác nhận trước khi ghi các tệp lớn hơn 1024 KB. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Ngưỡng kích thước file tính bằng kilobyte trên đó cảnh báo được phát hành. | +| `thresholdKb` | `number` | `1024` | Ngưỡng kích thước tệp (tính bằng kilobyte) trên đó cảnh báo được phát hành. | **Ví dụ:** @@ -634,7 +635,7 @@ Cung cấp cho agent bối cảnh bổ sung trước các hoạt động có r ``` -Trình xử lý hook thực thi giới hạn stdin 1 MB cho các tải trọng. Để kiểm tra chính sách này với nội dung nhỏ, đặt `thresholdKb` thành giá trị tốt dưới 1024. +Trình xử lý hook thực thi giới hạn stdin 1 MB trên tải trọng. Để kiểm tra chính sách này với nội dung nhỏ, đặt `thresholdKb` thành một giá trị tốt dưới 1024. --- @@ -660,7 +661,7 @@ Không có tham số. ### `warn-global-package-install` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy `npm install -g`, `yarn global add` hoặc `pip install` không có môi trường ảo. +**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy `npm install -g`, `yarn global add` hoặc `pip install` mà không có môi trường ảo. Không có tham số. @@ -673,16 +674,16 @@ Thực thi trình quản lý gói nào mà agent được phép sử dụng. ### `prefer-package-manager` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Vô hiệu hóa. Khi bật, chặn bất kỳ lệnh trình quản lý gói nào không có trong danh sách `allowed` và yêu cầu Claude viết lại lệnh bằng trình quản lý được phép. +**Mặc định:** Bị vô hiệu hóa. Khi được bật, chặn bất kỳ lệnh trình quản lý gói nào không trong danh sách `allowed` và hướng dẫn Claude viết lại lệnh sử dụng trình quản lý được phép. Phát hiện: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Tham số | Loại | Mặc định | Mô tả | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Tên trình quản lý gói được phép. Bất kỳ trình quản lý nào được phát hiện không có trong danh sách này bị chặn. Khi trống, chính sách là no-op. | -| `blocked` | string[] | `[]` | Tên trình quản lý bổ sung cần chặn ngoài danh sách tích hợp sẵn (ví dụ: `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Tên trình quản lý gói được phép. Bất kỳ trình quản lý nào được phát hiện nhưng không có trong danh sách này bị chặn. Khi trống, chính sách là vô-op. | +| `blocked` | string[] | `[]` | Tên trình quản lý bổ sung để chặn ngoài danh sách tích hợp (ví dụ: `['pdm', 'pipx']`). | -Danh sách chặn tích hợp sẵn bao gồm: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Sử dụng `blocked` để thêm trình quản lý không có trong danh sách này. +Danh sách chặn tích hợp bao gồm: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Sử dụng `blocked` để thêm các trình quản lý không có trong danh sách này. **Ví dụ cấu hình:** @@ -698,18 +699,18 @@ Danh sách chặn tích hợp sẵn bao gồm: pip, pip3, npm, npx, yarn, pnpm, } ``` -Với cấu hình này, cả `pip install flask` và `pdm install flask` đều bị từ chối với thông báo yêu cầu Claude sử dụng `uv` hoặc `bun`. Các lệnh như `uv pip install flask` được phép vì `uv` nằm trong danh sách cho phép và được kiểm tra trước. +Với cấu hình này, `pip install flask` và `pdm install flask` đều bị từ chối với thông báo hướng dẫn Claude sử dụng `uv` hoặc `bun` thay thế. Các lệnh như `uv pip install flask` được phép vì `uv` ở trong danh sách cho phép và được kiểm tra trước. --- ## Hành vi AI -Phát hiện khi agent bị mắc kẹt hoặc cư xử bất ngờ. +Phát hiện khi các agent bị kẹt hoặc hành xử bất thường. ### `warn-repeated-tool-calls` -**Sự kiện:** PreToolUse (tất cả công cụ) -**Mặc định:** Hướng dẫn Claude xem xét lại khi cùng một công cụ được gọi 3+ lần với cùng các tham số - dấu hiệu phổ biến của agent bị mắc kẹt trong vòng lặp. +**Sự kiện:** PreToolUse (tất cả các công cụ) +**Mặc định:** Hướng dẫn Claude suy xét lại khi cùng một công cụ được gọi 3 lần trở lên với các tham số giống hệt nhau - dấu hiệu phổ biến của agent bị kẹt trong vòng lặp. Không có tham số. @@ -717,39 +718,39 @@ Không có tham số. ## Quy trình làm việc -Thực thi quy trình làm việc cuối phiên có kỷ luật. Các chính sách này kích hoạt trên sự kiện **Stop** và từ chối agent dừng lại cho đến khi mỗi điều kiện được đáp ứng. Chúng theo chuỗi phụ thuộc tự nhiên: commit → push → PR → CI. Nếu chính sách từ chối, các chính sách sau trong chuỗi bị bỏ qua (từ chối ngắn mạch). +Thực thi quy trình làm việc kỷ luật cuối phiên. Các chính sách này hoạt động trên sự kiện **Stop** và từ chối agent dừng lại cho đến khi mỗi điều kiện được đáp ứng. Chúng theo một chuỗi phụ thuộc tự nhiên: commit → push → PR → CI. Nếu chính sách từ chối, các chính sách sau trong chuỗi bị bỏ qua (từ chối ngắt mạch). -Tất cả các chính sách quy trình làm việc **fail-open**: nếu công cụ yêu cầu không khả dụng (ví dụ: `gh` không được cài đặt, không có git remote), chính sách cho phép với thông báo thông tin giải thích tại sao kiểm tra bị bỏ qua. +Tất cả các chính sách quy trình làm việc **fail-open**: nếu công cụ bắt buộc không có sẵn (ví dụ: `gh` không được cài đặt, không có git remote), chính sách cho phép bằng thông báo thông tin giải thích lý do kiểm tra bị bỏ qua. -### Ngữ nghĩa Stop trên mỗi CLI +### Ngữ nghĩa Stop cho mỗi CLI -Thực thi Stop trông hơi khác nhau trên sáu CLI được hỗ trợ vì mỗi CLI đều hiển thị hợp đồng hook "agent hoàn thành" khác. **Kết quả** là như nhau — agent không thoát khỏi việc dừng lại khi cổng quy trình làm việc thất bại — nhưng **cơ chế** khác. Bảng dưới đây tóm tắt; chỉ Pi có một đặc điểm kỳ lạ được nhìn thấy bởi người dùng đáng hiểu trước khi bạn bật một chính sách `require-*-before-stop`. +Thực thi Stop trông hơi khác nhau trên sáu CLI được hỗ trợ vì mỗi CLI tiếp xúc với hợp đồng hook "agent hoàn thành" khác nhau. **Kết quả** là như nhau — agent không thể dừng lại trong khi cổng quy trình làm việc đang thất bại — nhưng **cơ chế** khác nhau. Bảng dưới đây tóm tắt; chỉ Pi có một đặc tính nhất định mà người dùng nhìn thấy được đáng hiểu trước khi bạn bật chính sách `require-*-before-stop`. -| CLI | Khi cổng kích hoạt | Bạn thấy gì | +| CLI | Khi cổng hoạt động | Những gì bạn nhìn thấy | |---|---|---| -| Claude Code | Cùng vòng lặp agent, ngay lập tức | Claude tiếp tục làm việc — sửa chữa vấn đề, sau đó cố gắng hoàn thành lại. Không có sự gián đoạn nào được nhìn thấy từ phía bạn. | +| Claude Code | Cùng vòng lặp agent, ngay lập tức | Claude tiếp tục làm việc — sửa vấn đề, sau đó cố gắng hoàn thành lại. Không có gián đoạn nào nhìn thấy được cho bạn. | | Codex | Cùng vòng lặp agent, ngay lập tức | Giống như Claude. | -| GitHub Copilot CLI | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{decision:"block", reason}` của Copilot — được xác minh theo thực nghiệm chống lại Copilot CLI 1.0.41). | -| Cursor Agent | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{followup_message}` của Cursor — được giới hạn ở `loop_limit`, mặc định 5 lần thử lại). | -| OpenCode | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng SDK gọi `client.session.prompt(...)` được định tuyến qua `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Lượt người dùng tiếp theo** | **Pi dừng lại rõ ràng** khi cổng kích hoạt — vòng lặp agent của nó thoát và bạn được trả về lời nhắc. Cổng kích hoạt vào lần tiếp theo bạn gửi lời nhắc: failproofai thêm vào trước một chỉ thị `MANDATORY ACTION REQUIRED` vào hệ thống prompt của lượt đó, hướng dẫn LLM hoàn thành bước quy trình làm việc (commit, push, v.v.) trước khi làm những gì bạn yêu cầu. | +| GitHub Copilot CLI | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh retry `{decision:"block", reason}` của Copilot — được xác minh bằng thực nghiệm với Copilot CLI 1.0.41). | +| Cursor Agent | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{followup_message}` của Cursor — giới hạn ở `loop_limit`, mặc định 5 lần thử lại). | +| OpenCode | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng lệnh gọi SDK `client.session.prompt(...)` của OpenCode được định tuyến qua `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Lượt người dùng tiếp theo** | **Pi dừng lại một cách rõ ràng** khi cổng hoạt động — vòng lặp agent của nó thoát ra và bạn được trả về lời nhắc. Cổng sau đó hoạt động lần tiếp theo bạn gửi lời nhắc: failproofai thêm tiền tố chỉ thị `MANDATORY ACTION REQUIRED` vào lời nhắc hệ thống của lượt đó, hướng dẫn LLM hoàn thành bước quy trình làm việc (commit, push, v.v.) trước khi thực hiện bất kỳ điều gì bạn yêu cầu. | -**Hạn chế Pi.** `AgentEndEvent` của Pi (tương đương hạ nguồn của Claude `Stop` hook) không có loại Result — khi nó kích hoạt, vòng lặp agent của Pi đã thoát. Pi không thể bị buộc phải thử lại cùng vòng lặp theo cách Claude / Copilot / Cursor / OpenCode có thể. failproofai dịch chuyển cổng đến sự kiện `before_agent_start` của Pi (kích hoạt sau lời nhắc người dùng tiếp theo) để kiểm tra quy trình làm việc vẫn thực thi, chỉ trên lượt tiếp theo thay vì lượt hiện tại. +**Giới hạn Pi.** `AgentEndEvent` của Pi (tương đương ngược dòng của hook `Stop` của Claude) không có loại Result — vào thời điểm nó hoạt động, vòng lặp agent của Pi đã thoát. Pi không thể bị buộc thử lại cùng vòng lặp như Claude / Copilot / Cursor / OpenCode có thể. failproofai chuyển cổng sang sự kiện `before_agent_start` của Pi (hoạt động sau lời nhắc người dùng tiếp theo) để kiểm tra quy trình làm việc vẫn thực thi, chỉ trên lượt tiếp theo chứ không phải lượt hiện tại. -**Điều này có nghĩa gì trong thực tế:** +**Điều này có nghĩa là gì trong thực tế:** -- Sau khi Pi dừng lại, lý do từ chối được nắm bắt trong bộ nhớ được khóa theo id phiên Pi. Lời nhắc rất tiếp theo bạn gửi trong cùng một quy trình Pi thoát nó: LLM thấy chỉ thị `MANDATORY ACTION REQUIRED` ở đầu hệ thống prompt của nó, commits (hoặc pushes / mở PR / chờ CI), và chỉ sau đó tiếp tục với yêu cầu của bạn. Lý do từ chối được nắm bắt là một lần — một khi thoát, cổng rõ ràng. -- Cổng được giới hạn bởi vòng đời quá trình Pi. Nếu bạn `Ctrl+C` Pi hoặc thoát giữa các lượt, mục trong bộ nhớ bị loại bỏ cùng với quá trình và cổng bị bỏ qua. Claude, Copilot, Cursor và OpenCode có giới hạn tương tự (giết agent và cổng bị bỏ qua) — Pi chỉ khiến nó rõ ràng hơn vì agent rõ ràng thoát trước khi cổng kích hoạt. -- Một từ chối đang chờ xử lý cũng bị xóa trên `session_shutdown` vì bất kỳ lý do nào (`new` / `resume` / `fork` / `quit`), do đó một cổng cũ từ phiên trước không thể rò rỉ vào phiên mới được bắt đầu trong cùng quá trình Pi. +- Sau khi Pi dừng, lý do từ chối được chụp trong bộ nhớ được khóa bởi id phiên Pi. Lời nhắc rất tiếp theo mà bạn gửi trong cùng quy trình Pi xả nó: LLM nhìn thấy chỉ thị `MANDATORY ACTION REQUIRED` ở đầu lời nhắc hệ thống của nó, commits (hoặc pushes / mở PR / chờ CI), và chỉ sau đó tiếp tục với yêu cầu của bạn. Lý do từ chối được chụp là một lần — sau khi xả, cổng được xóa. +- Cổng được giới hạn bởi thời gian tồn tại quy trình của Pi. Nếu bạn `Ctrl+C` Pi hoặc bỏ cuộc giữa các lượt, mục trong bộ nhớ sẽ bị loại bỏ cùng với quy trình và cổng bị bỏ qua. Claude, Copilot, Cursor và OpenCode có cùng ràng buộc (tắt agent và cổng bị bỏ qua) — Pi chỉ làm cho nó rõ ràng hơn vì agent thoát một cách rõ ràng trước khi cổng hoạt động. +- Lệnh từ chối đang chờ xử lý cũng được xóa trên `session_shutdown` vì bất kỳ lý do gì (`new` / `resume` / `fork` / `quit`), vì vậy cổng cũ từ phiên trước không thể rò rỉ vào phiên mới được bắt đầu trong cùng quy trình Pi. -Nếu bạn cần retry cùng vòng lặp kiểu Claude, chạy các chính sách `Stop` của bạn dưới bất kỳ năm CLI được hỗ trợ nào khác. Chúng tôi đang theo dõi Pi hạ nguồn để loại Result trong tương lai trên `AgentEndEvent` sẽ cho phép chúng tôi đóng khoảng trống này. +Nếu bạn cần thử lại cùng vòng lặp kiểu Claude, hãy chạy chính sách `Stop` của bạn dưới bất kỳ CLI nào trong năm CLI được hỗ trợ khác. Chúng tôi đang theo dõi Pi ngược dòng cho loại Result trong tương lai trên `AgentEndEvent` sẽ cho phép chúng tôi đóng khoảng trống này. ### `require-commit-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi có các thay đổi chưa được commit (file được sửa, staged hoặc untracked). Trả lại thông báo thông tin khi thư mục làm việc sạch sẽ. +**Mặc định:** Từ chối dừng khi có các thay đổi chưa được commit (tệp được sửa đổi, được stage hoặc chưa được theo dõi). Trả về thông báo thông tin khi thư mục làm việc sạch sẽ. Không có tham số. @@ -758,7 +759,7 @@ Không có tham số. ### `require-push-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi có các commit chưa được đẩy hoặc khi nhánh hiện tại không có nhánh theo dõi từ xa. Gợi ý `git push -u` để tạo nhánh theo dõi nếu cần. Fails open nếu không có remote được cấu hình. +**Mặc định:** Từ chối dừng khi có các commit chưa được đẩy hoặc khi nhánh hiện tại không có nhánh theo dõi từ xa. Đề xuất `git push -u` để tạo nhánh theo dõi nếu cần. Fail open nếu không có remote được cấu hình. **Tham số:** @@ -783,14 +784,14 @@ Không có tham số. ### `require-pr-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi không có pull request cho nhánh hiện tại, hoặc khi PR hiện có bị đóng mà không merge. Hướng dẫn Claude tạo PR với `gh pr create`. Khi PR được **merge**, chính sách cho phép (công việc đã ship) và thông báo gợi ý chuyển đổi nhánh (`git checkout main && git pull`). +**Mặc định:** Từ chối dừng khi không có pull request nào tồn tại cho nhánh hiện tại hoặc khi PR hiện có bị đóng mà không merge. Hướng dẫn Claude tạo PR với `gh pr create`. Khi PR **được merge**, chính sách cho phép (công việc đã ship) và thông báo gợi ý chuyển sang nhánh khác (`git checkout main && git pull`). Không có tham số. Chính sách này yêu cầu [GitHub CLI](https://cli.github.com/) (`gh`) được cài đặt và xác thực. -Chạy `gh auth login` với mã thông báo truy cập cá nhân có phạm vi `repo` để truy cập đọc -pull requests. Nếu `gh` không được cài đặt hoặc chưa được xác thực, chính sách fails open và báo cáo lý do cho Claude. +Chạy `gh auth login` bằng mã thông báo truy cập cá nhân có phạm vi `repo` để có quyền đọc +pull request. Nếu `gh` không được cài đặt hoặc không được xác thực, chính sách fail open và báo cáo lý do cho Claude. --- @@ -798,24 +799,24 @@ pull requests. Nếu `gh` không được cài đặt hoặc chưa được xác ### `require-no-conflicts-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi nhánh hiện tại không thể merge sạch vào nhánh cơ sở. Chính sách trước tiên xác nhận có `OPEN` PR trên GitHub cho nhánh — nếu không có, không có mục tiêu merge để thực thi, do đó toàn bộ chính sách ngắn mạch để cho phép. Một khi xác nhận `OPEN` PR, hai bộ dò độc lập chạy: +**Mặc định:** Từ chối dừng khi nhánh hiện tại không thể merge sạch vào nhánh cơ sở. Chính sách đầu tiên xác nhận có PR `OPEN` trên GitHub cho nhánh — nếu không có, không có mục tiêu merge để thực thi, vì vậy toàn bộ chính sách ngắn mạch để cho phép. Khi PR `OPEN` được xác nhận, hai probe độc lập chạy: -1. **Cục bộ** — `git merge-tree --write-tree --name-only origin/ HEAD`. Xung đột, thông báo từ chối đặt tên các file xung đột để Claude biết chính xác những gì cần giải quyết. -2. **GitHub** — tái sử dụng kết quả `gh pr view --json mergeable,state` đã được lấy trong kiểm tra trước. Bắt xung đột mà `origin/` cũ cuc bộ sẽ bỏ lỡ (ví dụ: ai đó đã công bố PR xung đột trên `main` kể từ lần fetch cuối cùng). Kết quả `CONFLICTING` từ chối. Kết quả `UNKNOWN` cũng từ chối và hướng dẫn Claude chờ ~10 giây và kiểm tra lại trước khi cố gắng dừng lại — điều này ngăn chặn sai âm dương trong khi GitHub tính toán lại. +1. **Địa phương** — `git merge-tree --write-tree --name-only origin/ HEAD`. Khi xung đột, thông báo từ chối liệt kê các tệp xung đột để Claude biết chính xác phải giải quyết cái gì. +2. **GitHub** — tái sử dụng kết quả `gh pr view --json mergeable,state` đã được tìm nạp trong precheck. Bắt xung đột mà `origin/` cũ địa phương sẽ bỏ lỡ (ví dụ: ai đó đã hạ cánh PR xung đột trên `main` kể từ lần tìm nạp cuối cùng). Kết quả `CONFLICTING` từ chối. Kết quả `UNKNOWN` cũng từ chối và hướng dẫn Claude chờ ~10 giây và kiểm tra lại trước khi cố gắng dừng lại — điều này ngăn chặn âm tính giả khi GitHub tính toán lại. -Bỏ qua hoàn toàn (cho phép) khi: `gh` không được cài đặt, không có PR cho nhánh, trạng thái PR không phải `OPEN` (ví dụ: `MERGED`, `CLOSED`), hoặc `gh pr view` trả lại đầu ra không thể phân tích cú pháp. Cũng fails open khi `origin/` bị thiếu cục bộ hoặc khi không có commit nào phía trước cơ sở — các sự rơi qua Tầng 1 đó vẫn tham khảo mergeability PR được lưu trong bộ nhớ đệm trước khi cho phép. +Bỏ qua hoàn toàn (cho phép) khi: `gh` không được cài đặt, không có PR nào cho nhánh, trạng thái PR không phải `OPEN` (ví dụ: `MERGED`, `CLOSED`), hoặc `gh pr view` trả về kết quả không thể phân tích. Cũng fail open khi `origin/` bị thiếu địa phương hoặc khi không có commit nào phía trước cơ sở — những fall-through Lớp 1 đó vẫn tham khảo mergeability PR được lưu trong bộ nhớ đệm trước khi cho phép. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Nhánh cơ sở để kiểm tra xung đột chống lại. | +| `baseBranch` | `string` | `"main"` | Nhánh cơ sở để kiểm tra xung đột. | GitHub CLI (`gh`) là bắt buộc đối với chính sách này. Chính sách sử dụng `gh pr view` để xác nhận -có `OPEN` PR tồn tại trước khi chạy bất kỳ bộ dò xung đột — nếu không có `gh`, chính sách -ngắn mạch để cho phép. Chạy `gh auth login` với mã thông báo truy cập cá nhân có phạm vi -`repo` để truy cập đọc pull requests. +PR `OPEN` tồn tại trước khi chạy bất kỳ probe xung đột nào — không có `gh`, chính sách +ngắn mạch để cho phép. Chạy `gh auth login` bằng mã thông báo truy cập cá nhân có phạm vi +`repo` để có quyền đọc pull request. --- @@ -823,14 +824,14 @@ ngắn mạch để cho phép. Chạy `gh auth login` với mã thông báo truy ### `require-ci-green-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi kiểm tra CI đang thất bại hoặc vẫn đang chạy trên nhánh hiện tại. Kiểm tra cả GitHub Actions workflow chạy và kiểm tra bot của bên thứ ba (ví dụ: CodeRabbit, SonarCloud, Codecov). Coi `skipped`, `cancelled` và `neutral` là kết luận không thất bại (cái sau bao gồm ví dụ: cảnh báo Socket Security trên PR của người đóng góp bên ngoài, nơi ứng dụng có ý định báo cáo neutral thay vì thành công/thất bại). Trả lại thông báo thông tin khi tất cả kiểm tra vượt qua. +**Mặc định:** Từ chối dừng khi kiểm tra CI đang thất bại hoặc vẫn đang chạy trên nhánh hiện tại. Kiểm tra cả GitHub Actions workflow run và kiểm tra bot của bên thứ ba (ví dụ: CodeRabbit, SonarCloud, Codecov). Coi các kết luận `skipped`, `cancelled` và `neutral` là không thất bại (kết luận cuối cùng bao gồm ví dụ: cảnh báo Socket Security trên PR người đóng góp bên ngoài, nơi ứng dụng cố ý báo cáo neutral chứ không phải success/failure). Trả về thông báo thông tin khi tất cả kiểm tra vượt qua. Không có tham số. Chính sách này yêu cầu [GitHub CLI](https://cli.github.com/) (`gh`) được cài đặt và xác thực. -Chạy `gh auth login` với mã thông báo truy cập cá nhân có phạm vi `repo` để truy cập đọc -workflow chạy Actions và Checks API. Nếu `gh` không được cài đặt hoặc chưa được xác thực, chính sách fails open và báo cáo lý do cho Claude. +Chạy `gh auth login` bằng mã thông báo truy cập cá nhân có phạm vi `repo` để có quyền đọc +Actions workflow run và Checks API. Nếu `gh` không được cài đặt hoặc không được xác thực, chính sách fail open và báo cáo lý do cho Claude. --- @@ -839,7 +840,7 @@ workflow chạy Actions và Checks API. Nếu `gh` không được cài đặt h ## Vô hiệu hóa các chính sách riêng lẻ -Loại bỏ một chính sách cụ thể khỏi `enabledPolicies` trong cấu hình của bạn, hoặc chuyển đổi nó tắt trong tab Chính sách của bảng điều khiển. +Loại bỏ một chính sách cụ thể khỏi `enabledPolicies` trong cấu hình của bạn hoặc tắt nó trong tab Policies của bảng điều khiển. ```json { @@ -850,4 +851,4 @@ Loại bỏ một chính sách cụ thể khỏi `enabledPolicies` trong cấu h } ``` -Các chính sách không được liệt kê trong `enabledPolicies` không chạy, ngay cả khi có mục `policyParams` tồn tại cho chúng. \ No newline at end of file +Các chính sách không được liệt kê trong `enabledPolicies` không chạy, ngay cả khi tồn tại các mục `policyParams` cho chúng. \ No newline at end of file diff --git a/docs/vi/cli/audit.mdx b/docs/vi/cli/audit.mdx index a44dbf5a..6f49381d 100644 --- a/docs/vi/cli/audit.mdx +++ b/docs/vi/cli/audit.mdx @@ -1,23 +1,23 @@ --- -title: Kiểm toàn lịch sử phiên (beta) -description: "Đếm tần suất agent thực hiện những điều lãng phí hoặc rủi ro trên các phiên ghi âm trong quá khứ" +title: Kiểm tra các phiên làm việc quá khứ (beta) +description: "Đếm số lần agent thực hiện những việc lãng phí hoặc rủi ro trên các bản ghi quá khứ" --- - **Tính năng beta.** Kiểm toàn được phát hành dưới dạng beta trong khi chúng tôi thu thập phản hồi sớm. - Danh mục detector và định dạng báo cáo có thể thay đổi trước bản phát hành ổn định tiếp theo. - Vui lòng mở một vấn đề nếu bất kỳ điều gì không đúng. + **Tính năng beta.** Audit được phát hành dưới dạng beta trong khi chúng tôi thu thập phản hồi sớm. + Danh mục detector và định dạng báo cáo có thể thay đổi trước bản ổn định tiếp theo. + Vui lòng mở một issue nếu bất cứ điều gì có vẻ sai. -Kiểm toàn phát lại các phiên ghi âm agent-CLI trong quá khứ của bạn thông qua công cụ chính sách của failproofai và hiển thị một báo cáo trực quan có thể chia sẻ trên **trang bảng điều khiển `/audit`** — kiểu hình nguyên mẫu của agent, điểm từ 0–100, và chính xác những chính sách nào sẽ bắt được điều gì. +Audit phát lại các bản ghi phiên làm việc agent-CLI quá khứ của bạn thông qua engine chính sách của failproofai và tạo ra một báo cáo trực quan có thể chia sẻ trên **trang dashboard `/audit`** — kiến trúc của agent, điểm số từ 0–100, và chính xác những chính sách nào sẽ phát hiện được cái gì. ## Chạy nó -Ba cách vào — tất cả đều dẫn đến báo cáo `/audit` giống nhau. +Ba cách — tất cả đều dẫn đến báo cáo `/audit` giống nhau. -```bash npx (không cài đặt) +```bash npx (không cần cài đặt) npx -y failproofai audit ``` @@ -25,96 +25,106 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (bảng điều khiển) +```bash failproofai (dashboard) failproofai ``` - - `npx -y failproofai audit` tìm nạp failproofai, chạy quét và mở bảng điều khiển cho bạn — không cần cài đặt trước. + + `npx -y failproofai audit` tải failproofai, chạy quét và mở dashboard cho bạn — không cần cài đặt trước. - `failproofai audit` chạy quét trong terminal của bạn, sau đó tự động mở `localhost:8020/audit` khi hoàn thành. + `failproofai audit` chạy quét trong terminal của bạn, sau đó tự động mở + `localhost:8020/audit` khi hoàn thành. - - Chạy `failproofai` và nhấp vào **Audit** trong thanh điều hướng (giữa Policies và Projects), hoặc mở `/audit` trực tiếp. + + Chạy `failproofai` và nhấp vào **Audit** trong thanh điều hướng (giữa Policies và + Projects), hoặc mở `/audit` trực tiếp. - Chạy `failproofai audit -h` (hoặc `--help`) để xem cách sử dụng. Kiểm toàn chạy **hoàn toàn ngoại tuyến** — không cần tài khoản hoặc mạng — và bảng điều khiển tiếp tục phục vụ cho đến khi bạn dừng nó bằng `Ctrl+C`. + Chạy `failproofai audit -h` (hoặc `--help`) để xem cách sử dụng. Audit chạy **hoàn toàn offline** — không cần tài khoản hoặc mạng — và dashboard tiếp tục hoạt động cho đến khi bạn dừng nó bằng `Ctrl+C`. -Bảng điều khiển quét các phiên ghi âm agent CLI trong quá khứ trên máy này (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) và báo cáo tần suất agent thực hiện những điều mà failproofai được xây dựng để dừng — kiểm tra biến môi trường, force push, tiền tố `cd ` dư thừa, vòng lặp sleep-polling, đọc lại các tệp vừa được chỉnh sửa, và hơn thế nữa. +Dashboard quét các bản ghi phiên làm việc agent CLI quá khứ trên máy này (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi) và báo cáo tần suất agent thực hiện những việc failproofai được xây dựng để ngăn chặn — kiểm tra biến môi trường, push force, tiền tố `cd ` thừa, vòng lặp sleep-polling, đọc lại tệp vừa chỉnh sửa, và nhiều hơn nữa. -Đối với mỗi phiên ghi âm, mọi sự kiện sử dụng công cụ được phát lại thông qua 39 chính sách tích hợp **và** thông qua 8 detector chỉ dành cho kiểm toàn bắt các mẫu chưa được bao gồm bởi các chính sách thời gian chạy. Số lượng được tổng hợp trên mỗi chính sách/detector trên tất cả các phiên. +Đối với mỗi bản ghi, mọi sự kiện tool-use được phát lại thông qua 39 chính sách tích hợp **và** thông qua 8 detector chỉ dùng cho audit bắt các mẫu chưa được bao phủ bởi chính sách runtime. Số lượng được tổng hợp theo chính sách / detector trên tất cả các phiên. ## Bạn nhận được gì -Trang `/audit` là một **poster** trên một màn hình có thể chia sẻ, theo sau là bốn phần dưới đây nếp gấp: +Trang `/audit` là một **áp phích** toàn màn hình có thể chia sẻ, theo sau bởi bốn phần dưới cuộn: -1. **Poster** — danh tính của agent của bạn trong thoáng qua: **kiểu hình nguyên mẫu** của nó (một trong 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), các từ khóa persona của nó, độ hiếm của kiểu hình nguyên mẫu đó, và **điểm từ 0–100** với dải cấp bậc (`S` xuống `cấp thấp nhất`). Được xây dựng để chia sẻ — đăng trên X hoặc LinkedIn, hoặc tải xuống dưới dạng PNG. -2. **`// strengths`** — những điều mà agent của bạn đã làm tốt, dưới dạng các số thực từ quét (ví dụ: phần trăm clean-tool-call, `0` nỗ lực push-to-main), chỉ hiển thị khi chính sách liên quan có hồ sơ sạch. -3. **`// quirks`** — những gì đã trượt qua: một bảng xếp hạng các hành vi mà failproofai sẽ bắt được — *khi* lần cuối cùng nó xảy ra, *những gì đã trượt* (và tính năng tích hợp sẽ chặn nó), **mức độ nghiêm trọng** của nó, và tần suất *được nhìn thấy* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — danh sách sửa chữa được quy định: một hàng cho mỗi chính sách với `failproofai policy add ` sao chép dán, cộng với nút **cài đặt tất cả** kích hoạt mọi khuyến nghị cùng một lúc và hiển thị **điểm dự báo** của bạn nếu bạn làm như vậy. -5. **`// come back better`** — xây dựng thói quen: đặt **nhắc nhở** kiểm toàn lại qua email (`3d` / `7d` / `14d` / `30d`) hoặc kiểm toàn ngay bây giờ, và **mời một bạn** chạy kiểm toàn của riêng họ (được gửi từ failproof.ai, Cc cho bạn). Nhắc nhở và lời mời yêu cầu đăng nhập. +1. **Áp phích** — nhận dạng agent một cách tức thì: **kiến trúc** của nó (một trong 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), các từ khóa nhân cách, kiến trúc đó hiếm đến mức nào, và **điểm số 0–100** với dải cấp (`S` xuống `bottom tier`). Được xây dựng để chia sẻ — đăng lên X hoặc LinkedIn, hoặc tải xuống dưới dạng PNG. +2. **`// strengths`** — những gì agent của bạn đã làm tốt, dưới dạng các con số thực từ quét (ví dụ: clean-tool-call %, `0` lần thử push-to-main), chỉ hiển thị khi chính sách liên quan có hồ sơ sạch sẽ. +3. **`// quirks`** — những gì lọt qua: bảng xếp hạng các hành vi failproofai sẽ phát hiện — *khi nó xảy ra lần cuối*, *cái gì lọt qua* (và built-in sẽ chặn nó), *mức độ nghiêm trọng* của nó, và tần suất nó *xuất hiện* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — danh sách sửa chữa được quy định: một hàng cho mỗi chính sách có `failproofai policy add ` copy-paste, cộng với nút **install all** bật mọi khuyến nghị cùng lúc và hiển thị **projected score** của bạn nếu bạn làm. +5. **`// come back better`** — xây dựng thói quen: đặt lại **reminder** về audit email (`3d` / `7d` / `14d` / `30d`) hoặc audit ngay bây giờ, và **mời một bạn** chạy audit của họ (được gửi từ failproof.ai, Cc cho bạn). Reminders và invites yêu cầu đăng nhập. -## Kiểm toàn được lên lịch +## Kiểm tra lịch biểu -Nếu bạn chạy **daemon failproofaid** (xem [`failproofai config`](/vi/cli/install-policies)), -nó có thể chạy lại kiểm toàn cho bạn theo lịch trình và làm mới báo cáo `/audit` ở chế độ nền. Nó **tắt theo mặc định**, vì quét đọc *nội dung* -của mọi phiên ghi âm agent session trên máy này — không có gì quét theo bộ hẹn giờ +Nếu bạn chạy **failproofaid daemon** (xem [`failproofai config`](/vi/cli/install-policies)), +nó có thể chạy lại audit cho bạn theo lịch biểu và làm mới báo cáo `/audit` trong +nền. Nó **tắt theo mặc định**, vì quét đọc *nội dung* +của mọi bản ghi phiên làm việc agent trên máy này — không có gì quét theo bộ đếm thời gian cho đến khi bạn yêu cầu. -Bật nó trong `~/.failproofai/config.toml`: +Bật nó trong `~/.failproofai/config.json` — thêm khóa `audit` bên cạnh +bất cứ gì khác tệp đã giữ: -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` | Khóa | Ý nghĩa | |---|---| -| `auto` | `true` kích hoạt quét được lên lịch. Bất cứ điều gì khác — vắng mặt, `false`, `"yes"` — là tắt. | -| `interval_days` | Ngày giữa các lần quét. Được giới hạn từ 1–90; `0`, âm hoặc không phải số sẽ quay lại `7`. | - -- Lịch trình là **wall-clock**, vì vậy nó sống sót qua tạm dừng và khởi động lại: một máy tính xách tay - đã ngủ quá thời gian đến hạn chạy **một lần** trên thức dậy, không bao giờ một khối lượng công việc dữ liệu. -- Mỗi lần chạy là một quá trình riêng biệt, mức độ ưu tiên thấp (`nice 19`) — không bao giờ đường dẫn hook của daemon, vốn luôn sẵn sàng để trả lời các lệnh gọi công cụ. -- Quét bị bỏ qua nếu `failproofai audit` hoặc re-run của bảng điều khiển đã đang hoạt động; nó được thử lại trong thời gian ngắn sau thay vì được coi là một thất bại. -- Tiến độ được ghi vào `~/.failproofai/state/audit-schedule.json` (lần chạy cuối cùng, tiếp theo đến hạn). Daemon sở hữu tệp đó — thay đổi tốc độ trong `config.toml`. +| `auto` | `true` bật quét lịch biểu. Bất cứ thứ gì khác — vắng mặt, `false`, `"yes"` — tắt. | +| `interval_days` | Ngày giữa các lần quét. Được giới hạn từ 1–90; `0`, một số âm hoặc không phải số sẽ quay lại `7`. | + +- Lịch biểu là **wall-clock**, vì vậy nó tồn tại qua suspend và reboot: máy tính xách tay + đã ngủ quá thời gian đến hạn chạy **một lần** khi thức dậy, không bao giờ có tồn đọng. +- Mỗi lần chạy là một quá trình riêng biệt, ưu tiên thấp (`nice 19`) — không bao giờ đường dẫn hook của daemon, + cái nào luôn miễn phí để trả lời các lệnh gọi công cụ. +- Quét bị bỏ qua nếu `failproofai audit` hoặc re-run của dashboard đã + đang chạy; nó được thử lại sớm sau đó thay vì được coi là lỗi. +- Tiến độ được ghi vào `~/.failproofai/state/audit-schedule.json` (lần chạy cuối cùng, + đến hạn tiếp theo). Daemon sở hữu tệp đó — thay đổi nhịp độ trong `config.json`. -Nếu bạn kích hoạt điều này trên máy được thiết lập bởi failproofai cũ hơn, hãy chạy -`failproofai config` một lần. Định nghĩa dịch vụ của daemon cần một bản nhập bổ sung +Nếu bạn đã bật điều này trên máy được thiết lập bởi failproofai cũ hơn, hãy chạy +`failproofai config` một lần. Định nghĩa dịch vụ của daemon cần một mục nhập bổ sung trước khi nó có thể khởi chạy CLI, và làm mới là một phần của lệnh đó. -## Các detector chỉ dành cho kiểm toàn +## Detector chỉ dùng cho audit -Những cái này phát hiện các mẫu hành vi độc xuất không (yet) được thực thi trong thời gian thực. Chúng chỉ chạy trong kiểm toàn và không bao giờ chặn một lệnh gọi công cụ trực tiếp. +Những cái này phát hiện các mẫu hành vi "ngu ngốc" không (chưa) được thực thi trong thời gian thực. Chúng chỉ chạy trong quá trình audit và không bao giờ chặn lệnh gọi công cụ trực tiếp. -| Detector | Những gì nó đếm | +| Detector | Nó đếm cái gì | |---|---| -| `redundant-cd-cwd` | Các lệnh Bash bắt đầu bằng `cd && …` mặc dù các lệnh đã chạy trong `cwd`. | +| `redundant-cd-cwd` | Lệnh Bash bắt đầu với `cd && …` mặc dù lệnh đã chạy trong `cwd`. | | `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` trên một tệp nguồn duy nhất — sử dụng công cụ `Read`. | | `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` chỉnh sửa tại chỗ — sử dụng công cụ `Edit`. | -| `prefer-write-over-heredoc` | Heredoc / đa dòng `echo > file` ghi tệp — sử dụng công cụ `Write`. | -| `sleep-polling-loop` | `sleep N` dài (≥ 30s) hoặc `while …; sleep …; done` vòng lặp polling. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, vv — scope to `cwd` thay thế. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, bỏ qua hooks. | -| `reread-after-edit` | `Read` của một tệp vừa được `Edit`/`Write` trong cùng một phiên. | +| `prefer-write-over-heredoc` | Heredoc / `echo > file` nhiều dòng ghi tệp — sử dụng công cụ `Write`. | +| `sleep-polling-loop` | `sleep N` dài (≥ 30s) hoặc vòng lặp polling `while …; sleep …; done`. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, v.v. — phạm vi đến `cwd` thay thế. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, bỏ qua hook. | +| `reread-after-edit` | `Read` của tệp vừa được `Edit`/`Write` trong cùng một phiên. | -## Bộ nhớ đệm +## Bộ đệm -- **Bộ nhớ đệm trên mỗi phiên ghi âm** tại `~/.failproofai/cache/audit/.json` được khóa bằng `(mtime, size, engineVersion, detectorVersion)` — bất hợp lệ tự động khi phiên ghi âm hoặc code chính sách/detector thay đổi. Mỗi mục cũng lưu trữ dấu thời gian `cachedAt` làm **siêu dữ liệu TTL** (không phải một phần của khóa bộ nhớ đệm); các mục cũ hơn **7 ngày** bị từ chối khi đọc để kết quả lâu dài không sống sót ngoài ý định detector phát triển. -- **Bộ nhớ đệm kết quả toàn bộ** tại `~/.failproofai/audit-dashboard.json` (chế độ 0600). Cho phép bảng điều khiển hiển thị ngay lập tức khi điều hướng mà không cần chạy lại. Cũng bị từ chối khi đọc quá **TTL 7 ngày** — `/audit` sau đó rơi vào trạng thái trống của nó và nhắc nhở chạy lại. Nhấp vào `[ re-audit now ]` gần phía dưới của báo cáo để làm mới — re-audit gửi `noCache: true`, vì vậy nó bỏ qua bộ nhớ đệm trên mỗi phiên ghi âm và quét lại mỗi phiên ghi âm thay vì trả về kết quả được lưu trong bộ nhớ đệm; lần chạy truyền phát tiến độ qua dải trên cùng (sticky) và hoán đổi kết quả tại chỗ khi thành công (không tải lại trang; re-audit thất bại giữ báo cáo trước đó). +- **Bộ đệm mỗi bản ghi** tại `~/.failproofai/cache/audit/.json` được khóa bởi `(mtime, size, engineVersion, detectorVersion)` — vô hiệu hóa tự động khi bản ghi hoặc mã chính sách/detector thay đổi. Mỗi mục nhập cũng lưu trữ một dấu thời gian `cachedAt` dưới dạng **siêu dữ liệu TTL** (không phải là một phần của khóa bộ đệm); các mục cũ hơn **7 ngày** bị từ chối khi đọc để các kết quả lâu dài không tồn tại quá lâu hơn ý định detector phát triển. +- **Bộ đệm kết quả toàn bộ** tại `~/.failproofai/audit-dashboard.json` (chế độ 0600). Cho phép dashboard render tức thì khi điều hướng mà không cần chạy lại. Cũng bị từ chối khi đọc quá **TTL 7 ngày** — `/audit` sau đó rơi vào trạng thái rỗng và nhắc chạy lại. Nhấp vào `[ re-audit now ]` gần dưới cùng của báo cáo để làm mới — re-audit gửi `noCache: true`, vì vậy nó bỏ qua bộ đệm mỗi bản ghi và quét lại mọi bản ghi thay vì trả về kết quả được lưu trong bộ đệm; lần chạy truyền phát tiến độ thông qua dải dính ở trên cùng và trao đổi kết quả tại chỗ khi thành công (không tải lại trang; re-audit thất bại giữ lại báo cáo trước đó). ## Ghi chú -- **Không đột biến.** Kiểm toàn phát lại ở chế độ chỉ đọc. `warn-repeated-tool-calls` bị bỏ qua vì xe đặt hàng sidecar trên mỗi phiên của nó sẽ bị sửa đổi. -- **Chính sách quy trình làm việc bị bỏ qua.** Các chính sách `require-*-before-stop` chỉ kích hoạt trên các sự kiện `Stop` và `execSync` so với trạng thái git trực tiếp — chúng không có diễn giải có ý nghĩa nào (what would have happened in 2025), vì vậy chúng không xuất hiện trong số lượng kiểm toàn. -- **Chính sách tùy chỉnh bị bỏ qua.** Các hook tùy chỉnh do người dùng cung cấp không được phát lại (chúng có thể đã thay đổi kể từ phiên ban đầu). \ No newline at end of file +- **Không có thay đổi.** Audit phát lại ở chế độ chỉ đọc. `warn-repeated-tool-calls` bị bỏ qua vì sidecar cho mỗi phiên của nó sẽ bị sửa đổi. +- **Chính sách quy trình làm việc bị bỏ qua.** Chính sách `require-*-before-stop` chỉ kích hoạt trên sự kiện `Stop` và `execSync` trên trạng thái git trực tiếp — chúng không có giải thích có ý nghĩa "cái gì sẽ xảy ra vào năm 2025", vì vậy chúng không xuất hiện trong số lượng audit. +- **Chính sách tùy chỉnh bị bỏ qua.** Hook tùy chỉnh do người dùng cung cấp không được phát lại (chúng có thể đã thay đổi kể từ phiên làm việc ban đầu). \ No newline at end of file diff --git a/docs/vi/cli/dashboard.mdx b/docs/vi/cli/dashboard.mdx index 4c609fb5..763d36f1 100644 --- a/docs/vi/cli/dashboard.mdx +++ b/docs/vi/cli/dashboard.mdx @@ -1,6 +1,6 @@ --- title: Xem các phiên làm việc -description: "Khởi động bảng điều khiển để duyệt các phiên tác nhân và quản lý chính sách" +description: "Khởi động bảng điều khiển để duyệt các phiên làm việc của agent và quản lý các chính sách" --- ```bash @@ -11,12 +11,12 @@ Khởi động bảng điều khiển web tại `http://localhost:8020`. ## Các tùy chọn -| Cờ | Mô tả | -|------|-------------| +| Flag | Mô tả | +|------|-------| | `--port ` | Cổng để lắng nghe (mặc định: `8020`) | -| `--allowed-origins ` | Các máy chủ/IP được phân tách bằng dấu phẩy được phép truy cập tài nguyên phát triển | +| `--allowed-origins ` | Các máy chủ/IP được phép truy cập tài nguyên dev, cách nhau bằng dấu phẩy | -Để trỏ bảng điều khiển tới thư mục dự án Claude không phải mặc định, hãy đặt biến môi trường `CLAUDE_PROJECTS_PATH` khi khởi động. +Để trỏ bảng điều khiển đến thư mục dự án Claude không phải mặc định, hãy đặt biến môi trường `CLAUDE_PROJECTS_PATH` khi khởi động. ## Ví dụ diff --git a/docs/vi/cli/environment-variables.mdx b/docs/vi/cli/environment-variables.mdx index a0ce709c..c3e2c87e 100644 --- a/docs/vi/cli/environment-variables.mdx +++ b/docs/vi/cli/environment-variables.mdx @@ -9,61 +9,65 @@ description: "Cấu hình hành vi failproofai bằng biến môi trường" |----------|-------------| | `PORT` | Cổng Dashboard (mặc định: `8020`) | | `CLAUDE_PROJECTS_PATH` | Ghi đè vị trí tìm kiếm thư mục dự án Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Các trang dashboard được ẩn, cách nhau bằng dấu phẩy | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Các máy chủ/IP được phép truy cập tài nguyên dev. Giống như `--allowed-origins`. | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Các trang Dashboard được ẩn, phân cách bằng dấu phẩy | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs được phép truy cập tài nguyên dev. Tương tự như `--allowed-origins`. | -## Ghi nhật ký +## Logging | Biến | Mô tả | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Mức độ ghi nhật ký của máy chủ (mặc định: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Đường dẫn tệp nhật ký hook tùy chỉnh, hoặc `true` cho mặc định (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Mức độ log của máy chủ (mặc định: `warn`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Đường dẫn tập tin log hook tùy chỉnh, hoặc `true` cho mặc định (`~/.failproofai/logs/hooks.log`) | -## Dữ liệu kỹ thuật +## Telemetry -failproofai báo cáo dữ liệu kỹ thuật sử dụng ẩn danh theo mặc định. Có hai cách -để tắt nó, và chúng được giải quyết theo cách hạn chế nhất — một biến môi trường -không bao giờ có thể bật lại cái gì mà tệp cấu hình đã tắt. +failproofai báo cáo telemetry sử dụng ẩn danh theo mặc định. Có hai cách để +tắt nó, và chúng sẽ áp dụng theo cách hạn chế nhất — một biến môi trường không +bao giờ có thể kích hoạt lại thứ gì đó mà tập tin cấu hình đã tắt. | Biến | Mô tả | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Vô hiệu hóa dữ liệu kỹ thuật sử dụng ẩn danh cho quy trình này | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Tắt telemetry sử dụng ẩn danh cho quy trình này | -Để vô hiệu hóa nó vĩnh viễn cho máy, hãy thêm điều này vào `~/.failproofai/config.toml`: +Để tắt nó vĩnh viễn cho máy, thêm phần này vào `~/.failproofai/config.json`: -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -Tệp cấu hình là tùy chọn được sử dụng nếu bạn chạy **daemon failproofaid**. -Daemon là một dịch vụ phạm vi hệ thống, và môi trường của nó không bao gồm -các biến được xuất từ shell của bạn — vì vậy `FAILPROOFAI_TELEMETRY_DISABLED` không thể -đến được nó. `[telemetry] enabled = false` được đọc bởi cả CLI và daemon. +Tập tin cấu hình là tùy chọn cần sử dụng nếu bạn chạy daemon **failproofaid**. +Daemon là một dịch vụ ở mức hệ thống, và môi trường của nó không bao gồm +các biến được xuất từ shell của bạn — vì vậy `FAILPROOFAI_TELEMETRY_DISABLED` không +thể được truyền đến nó. `[telemetry] enabled = false` được đọc bởi cả CLI và daemon. -Daemon chỉ báo cáo **vòng đời** của nó: rằng nó đã khởi động (và liệu lần chạy trước có thoát sạch), rằng nó đã dừng, khi công nhân đánh giá của nó được -sinh ra hoặc khởi động lại, khi một tác vụ collector không thành công, và kết quả của một -lần kéo chính sách đám mây. Những cái này mang các giá trị và số lượng có tính chất thấp — không bao giờ là đường dẫn tệp, lệnh, chính sách, lời nhắc, hoặc bất cứ điều gì được đọc từ bản ghi. Không có sự kiện trên mỗi lệnh gọi công cụ. +Daemon chỉ báo cáo **lifecycle** của chính nó: nó được khởi động (và liệu +lần chạy trước đó có thoát sạch hay không), nó bị dừng, khi người công nhân đánh giá của nó được +tạo hoặc khởi động lại, khi một nhiệm vụ bộ sưu tập thất bại, và kết quả của một +lần kéo chính sách đám mây. Những báo cáo này có giá trị và đếm số lượng thấp — không bao giờ là đường dẫn tập tin, lệnh, chính sách, lời nhắc, hoặc bất kỳ thứ gì được đọc từ bản ghi. Không có sự kiện cho mỗi lệnh công cụ. -## Xác thực +## Authentication | Biến | Mô tả | |----------|-------------| -| `FAILPROOF_API_URL` | Ghi đè URL cơ sở máy chủ api được sử dụng bởi hộp thoại xác thực dashboard. Mặc định là `https://api.befailproof.ai`; đặt thành `http://localhost:8080` (hoặc ở đâu đó) khi chạy máy chủ api cục bộ. | -| `FAILPROOFAI_AUTH_DIR` | Ghi đè nơi `auth.json` được lưu trữ (mặc định: `~/.failproofai`). Hầu hết hữu ích cho các bài kiểm tra cách ly. | +| `FAILPROOF_API_URL` | Ghi đè URL cơ sở máy chủ API được sử dụng bởi hộp thoại xác thực Dashboard. Mặc định là `https://api.befailproof.ai`; đặt thành `http://localhost:8080` (hoặc nơi khác) khi chạy máy chủ API cục bộ. | +| `FAILPROOFAI_AUTH_DIR` | Ghi đè nơi `auth.json` được lưu trữ (mặc định: `~/.failproofai`). Hữu ích chủ yếu cho các bài kiểm tra bị cô lập. | -## Lời nhắc chạy lần đầu tiên +## First-run prompt | Biến | Mô tả | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Bỏ qua lời nhắc cung cấp cài đặt chính sách khi gọi failproofai trần lần đầu tiên | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Bỏ qua lời nhắc cung cấp để cài đặt chính sách khi lần gọi failproofai đầu tiên | ## LLM (để đánh giá chính sách) | Biến | Mô tả | |----------|-------------| | `FAILPROOFAI_LLM_BASE_URL` | Điểm cuối API LLM (mặc định: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Khóa API cho chính sách được hỗ trợ bởi LLM | +| `FAILPROOFAI_LLM_API_KEY` | Khóa API cho các chính sách được hỗ trợ bởi LLM | | `FAILPROOFAI_LLM_MODEL` | Tên mô hình (mặc định: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/vi/cli/hook.mdx b/docs/vi/cli/hook.mdx index 814820c4..f6711e87 100644 --- a/docs/vi/cli/hook.mdx +++ b/docs/vi/cli/hook.mdx @@ -1,30 +1,31 @@ --- -title: Hook handler (internal) -description: "Subprocess mà Claude Code gọi trên mỗi sự kiện tool" +--- +title: Hook handler (nội bộ) +description: "Tiến trình con mà Claude Code gọi trên mỗi sự kiện công cụ" --- ```bash failproofai --hook ``` -Đây là lệnh được đăng ký trong `settings.json` của Claude Code bởi `failproofai policies --install`. Bạn thường không gọi lệnh này trực tiếp. +Đây là lệnh được đăng ký trong `settings.json` của Claude Code bởi `failproofai policies --install`. Thường bạn không gọi trực tiếp lệnh này. -Đọc một payload JSON từ stdin, đánh giá tất cả các chính sách được bật, và thoát với một mã chỉ ra quyết định: +Đọc một payload JSON từ stdin, đánh giá tất cả các chính sách được bật, và thoát với mã code chỉ ra quyết định: -| Mã thoát | Quyết định | Hiệu ứng | -|-----------|-----------|---------| +| Mã thoát | Quyết định | Tác dụng | +|---------|-----------|---------| | `0` | `allow` | Cho phép hành động | | `1` | `deny` | Chặn hành động - Claude sẽ thấy lý do từ chối | -| `2` | `instruct` | Chèn hướng dẫn vào ngữ cảnh của Claude | +| `2` | `instruct` | Tiêm hướng dẫn vào ngữ cảnh của Claude | ### Các loại sự kiện được hỗ trợ | Danh mục | Sự kiện | -|----------|---------| -| **Thực thi tool** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | +|---------|--------| +| **Thực thi công cụ** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Vòng đời phiên** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **Tương tác người dùng** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **Subagents & tasks** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **Các đại lý con & tác vụ** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **Cấu hình** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **Hệ thống tệp** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **Ngữ cảnh** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/vi/cli/install-policies.mdx b/docs/vi/cli/install-policies.mdx index acb443e5..f7c4e1af 100644 --- a/docs/vi/cli/install-policies.mdx +++ b/docs/vi/cli/install-policies.mdx @@ -7,7 +7,7 @@ description: "Bật policies để chúng chạy trên mọi lần gọi tool c failproofai policies --install [policy-names...] [options] ``` -Ghi các mục hook vào tệp cài đặt của CLI agent đã cài đặt (Claude Code, OpenAI Codex, hoặc GitHub Copilot CLI _(beta)_) để failproofai có thể chặn các lệnh gọi tool. +Ghi các mục hook vào tệp cài đặt của CLI agent đã cài đặt của bạn (Claude Code, OpenAI Codex, hoặc GitHub Copilot CLI _(beta)_) để failproofai có thể chặn các lệnh gọi tool. Bí danh: `failproofai p -i` @@ -15,43 +15,43 @@ Bí danh: `failproofai p -i` | Cờ | Mô tả | |------|-------------| -| `--cli claude\|codex\|copilot` | CLI agent để cài đặt; cách nhau bằng khoảng trắng (ví dụ: `--cli claude codex copilot`) hoặc lặp lại. Bỏ qua để phát hiện CLI đã cài đặt và nhắc. | +| `--cli claude\|codex\|copilot` | CLI agent để cài đặt; được phân tách bằng dấu cách (ví dụ: `--cli claude codex copilot`) hoặc lặp lại. Bỏ qua để phát hiện CLI đã cài đặt và nhắc. | | `--scope user` | Cài đặt vào tệp cài đặt phạm vi người dùng (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Mặc định. | | `--scope project` | Cài đặt vào tệp cài đặt phạm vi dự án (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | | `--scope local` | Chỉ Claude — cài đặt vào `/.claude/settings.local.json`. Codex và Copilot không có phạm vi `local`. | -| `--custom ` / `-c` | Đường dẫn đến tệp JS chứa các policies hook tùy chỉnh | +| `--custom ` / `-c` | Đường dẫn đến tệp JS chứa custom hook policies | -## Hành động +## Hành vi -- **Không có tên policy** - mở lời nhắc tương tác để chọn policies -- **Tên cụ thể** - bật các policies đó (thêm vào bất kỳ policies nào đã được bật) +- **Không có tên policy** - mở một lời nhắc tương tác để chọn policies +- **Các tên cụ thể** - bật các policies đó (thêm vào bất kỳ policies nào đã được bật) - **`all`** - bật mọi policy có sẵn -Cài đặt là cộng dồn: chạy `--install` lại sẽ thêm các policies mới mà không xóa các policies hiện có. +Cài đặt là bổ sung: chạy `--install` lại sẽ thêm các policies mới mà không loại bỏ các policies hiện có. ## Ví dụ ```bash -# Cài đặt tất cả các policies mặc định toàn cầu (tương tác) +# Install all default policies globally (interactive) failproofai policies --install -# Cài đặt các policies cụ thể cho dự án hiện tại +# Install specific policies for the current project failproofai policies --install block-sudo sanitize-api-keys --scope project -# Bật tất cả các policies cùng một lúc +# Enable all policies at once failproofai policies --install all -# Cài đặt với tệp policies tùy chỉnh +# Install with a custom policies file failproofai policies --install --custom ./my-policies.js -# Cài đặt cho OpenAI Codex (phạm vi dự án) +# Install for OpenAI Codex (project scope) failproofai policies --install --cli codex --scope project -# Cài đặt cho GitHub Copilot CLI (beta) cho dự án hiện tại +# Install for GitHub Copilot CLI (beta) for the current project failproofai policies --install --cli copilot --scope project -# Cài đặt cho cả ba CLI cùng một lúc +# Install for all three CLIs at once failproofai policies --install --cli claude codex copilot ``` -Khi `--custom ` được cung cấp, tệp được xác thực ngay lập tức - nó phải gọi `customPolicies.add()` ít nhất một lần. Đường dẫn được giải quyết được lưu vào `policies-config.json` dưới dạng `customPoliciesPath`. \ No newline at end of file +Khi `--custom ` được cung cấp, tệp sẽ được xác thực ngay lập tức - nó phải gọi `customPolicies.add()` ít nhất một lần. Đường dẫn đã được giải quyết được lưu vào `policies-config.json` dưới dạng `customPoliciesPath`. \ No newline at end of file diff --git a/docs/vi/cli/list-policies.mdx b/docs/vi/cli/list-policies.mdx index db80be3d..10e01528 100644 --- a/docs/vi/cli/list-policies.mdx +++ b/docs/vi/cli/list-policies.mdx @@ -1,16 +1,15 @@ --- ---- -title: Liệt kê các chính sách -description: "Xem các chính sách nào được bật, các tham số của chúng và các chính sách tùy chỉnh" +title: Liệt kê chính sách +description: "Xem những chính sách nào được bật, tham số của chúng và các chính sách tùy chỉnh" --- ```bash failproofai policies ``` -Hiển thị tất cả các chính sách với trạng thái, các tham số được cấu hình và các chính sách tùy chỉnh. +Hiển thị tất cả các chính sách với trạng thái, tham số được cấu hình và các chính sách tùy chỉnh. -## Kết quả mẫu +## Mẫu kết quả ```text Failproof AI Hook Policies (user) diff --git a/docs/vi/cli/migrate.mdx b/docs/vi/cli/migrate.mdx new file mode 100644 index 00000000..675230bd --- /dev/null +++ b/docs/vi/cli/migrate.mdx @@ -0,0 +1,112 @@ +--- +title: Di chuyển thư mục home +description: "Nâng cấp ~/.failproofai lên cấu trúc của phiên bản này, và xem trước những gì sẽ xảy ra" +--- + +```bash +failproofai migrate --dry-run # in ra kế hoạch, không thay đổi gì +failproofai migrate # chạy nó +``` + +Hầu hết mọi người không bao giờ gõ lệnh này. Nó tự chạy trên lệnh đầu tiên sau khi nâng cấp, +và [`failproofai update`](/vi/cli/update) bao gồm nó. Hãy sử dụng nó trực tiếp khi bạn muốn +xem kế hoạch trước khi nó xảy ra, hoặc để chạy quá trình di chuyển một mình. + +## Dựa trên cấu trúc, không phải phiên bản + +`~/.failproofai/VERSION` ghi lại một số **cấu trúc** — hình dạng của thư mục, +không phải bản phát hành đã viết nó. Các quá trình di chuyển được khóa trên số đó, +điều này làm cho một khoảng cách lớn trở nên rẻ: + +- Các phiên bản npm thay đổi trên mỗi bản phát hành, có hàng chục phiên bản giữa hai cấu trúc. +- Vì vậy, một máy bỏ qua ba mươi bản phát hành với **không có thay đổi cấu trúc** sẽ chạy **không có** + quá trình di chuyển, không phải ba mươi hoạt động vô ích. +- Và một máy bỏ qua nhiều cấu trúc cùng một lúc sẽ chạy từng bước theo thứ tự, + mỗi bước chỉ biết hai đầu của chính nó. + +Điều này quan trọng vì npm không thể tự cập nhật một gói đã cài đặt. Một máy +nằm trên một phiên bản trong nhiều tháng và sau đó nhảy qua nhiều cấu trúc là trường hợp bình thường, +không phải trường hợp lạ. + +## Quá trình chạy thử + +`--dry-run` in ra chuỗi chính xác và các tệp sẽ được lưu trước, +và không thay đổi gì cả — không có quá trình di chuyển, không có sao lưu, không có mục nhập sổ cái: + +``` +Layout 2 trên đĩa; phiên bản này nói 3. +1 bước sẽ chạy: + 2 → 3 layout 2 → 3: mang config.toml và credentials.toml vào JSON, di chuyển + custom-policies/ trở lại vào policies/, lồng cấu hình chính sách ở gốc + +Những điều này sẽ được sao chép đến ~/.failproofai/migrations/backup-layout2 trước: + VERSION + config.toml + credentials.toml +``` + +## Điều gì được mang theo, và điều gì được xây dựng lại + +Mỗi đường dẫn trong thư mục khai báo loại dữ liệu nó chứa, và điều đó quyết định +liệu quá trình di chuyển có thể loại bỏ nó hay không. Quy tắc: **những gì có thể suy dẫn và có thể tìm lại được có thể bị xóa; +bất cứ thứ gì bạn gõ, bất cứ thứ gì chưa được gửi, và bất cứ thứ gì xác định máy sẽ được mang theo.** + +| Được mang theo | Được xây dựng lại hoặc tìm lại | +|---|---| +| `config.json` — cài đặt, `daemon.configured`, các đường dẫn capture thêm | Bộ đệm kiểm toán | +| `credentials.json` — quá trình đăng ký đám mây của bạn | Các triển khai được quản lý bởi đám mây (được tìm lại và xác minh được tóm tắt trên lần bình chọn tiếp theo) | +| `policies-config.json` — lựa chọn chính sách và tham số của bạn | Trạng thái công việc daemon | +| `policies/` — các tệp chính sách của riêng bạn và các trợ giúp mà chúng nhập | | +| `hook-activity/` — nhật ký quyết định mà bảng điều khiển đọc | | +| Các sự kiện chưa được gửi vẫn đang chờ trong hàng để tải lên | | +| `cursors/` — dấu nước của bộ thu thập | | +| Nhị phân daemon trong `bin/` | | + + + Các sự kiện chưa được gửi được mang theo chứ không bị xóa vì mất mát sẽ là vĩnh viễn, + không phải chậm: dấu nước của bộ thu thập đã tiến vượt quá bất cứ thứ gì đang nằm trong spool, + vì vậy không có gì bao giờ sẽ đọc lại phạm vi đó của một bản ghi. Quá trình di chuyển cũng yêu cầu daemon + gửi những gì đang nằm trong spool ngay khi nó kết thúc, vì vậy kết quả thông thường là không có gì còn lại để mang theo. + + +Các khóa mà phiên bản **mới hơn** đã viết vào `config.json`, `credentials.json` hoặc +`policies-config.json` cũng được bảo toàn, thay vì bị xóa bởi một trình đọc cũ hơn. + +## Bản ghi nó để lại + +``` +~/.failproofai/migrations/ + applied.json một mục nhập cho mỗi bước: layout, CLI, dấu thời gian, thời lượng, kết quả + backup-layout/ bản sao của các tệp không thể thay thế được, được lấy trước bước đầu tiên +``` + +`applied.json` là những gì trả lời "máy này thực sự đã trải qua những gì" — câu hỏi +đầu tiên đáng hỏi khi có gì đó trông sai sau khi nâng cấp. Đính kèm nó +vào báo cáo lỗi. + +Bản sao được thiết kế có kích thước nhỏ một cách cố ý chứ không phải bản sao của toàn bộ thư mục: +quá trình di chuyển không còn xóa bất cứ thứ gì không thể thay thế được theo thiết kế, +vì vậy điều đáng bảo hiểm là một **khiếm khuyết trong một bước**, và những tệp này là những nơi +mà khiếm khuyết như vậy sẽ gây tổn thương. + +## Nếu một bước không thành công + +Chuỗi dừng ở đó. `VERSION` chỉ được đóng dấu bởi một bước đã hoàn thành, +vì vậy thư mục ở lại được đánh dấu bằng cấu trúc cũ của nó và lệnh tiếp theo sẽ thử lại nó — +một thư mục không bao giờ được đánh dấu hiện tại dựa trên quá trình di chuyển một phần. +Bước được ghi trong `applied.json` với `"ok": false`, và bản sao lưu là nơi nó được lấy. + +## Một thư mục mới hơn bị từ chối, không được di chuyển + +Nếu `~/.failproofai/` được viết bởi một **phiên bản failproofai mới hơn** so với phiên bản bạn đang chạy, +lệnh dừng lại và yêu cầu bạn nâng cấp thay thế. Dữ liệu đó ổn và một CLI mới hơn đọc nó; +di chuyển "tiến lên" từ nó không phải là điều tồn tại, và đặt lại nó sẽ phá hủy thứ gì đó có thể khôi phục. + +``` +Thư mục failproofai của máy này được viết bởi một phiên bản mới hơn (layout 4; +phiên bản này nói 3). Nâng cấp thay vì di chuyển: + npm install -g failproofai@latest +``` + +Daemon áp dụng cùng một quy tắc: `failproofaid` từ chối khởi động so với một cấu trúc +nó không nói, thay vì đọc và viết các đường dẫn đã di chuyển. \ No newline at end of file diff --git a/docs/vi/cli/remove-policies.mdx b/docs/vi/cli/remove-policies.mdx index 87cafc38..6abbb055 100644 --- a/docs/vi/cli/remove-policies.mdx +++ b/docs/vi/cli/remove-policies.mdx @@ -1,43 +1,44 @@ --- -title: Gỡ cài đặt policies -description: "Xóa các hook entries từ settings của Claude Code" +--- +title: Gỡ cài đặt các chính sách +description: "Loại bỏ các hook entries từ settings của Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -Xóa các hook entries của failproofai từ `settings.json` của Claude Code. +Loại bỏ các failproofai hook entries từ `settings.json` của Claude Code. Bí danh: `failproofai p -u` -## Options +## Tùy chọn -| Flag | Description | +| Cờ | Mô tả | |------|-------------| -| `--scope user` | Xóa từ cài đặt toàn cục (mặc định) | -| `--scope project` | Xóa từ cài đặt dự án | -| `--scope local` | Xóa từ cài đặt cục bộ | -| `--scope all` | Xóa từ tất cả các phạm vi cùng một lúc | +| `--scope user` | Loại bỏ từ cài đặt toàn cục (mặc định) | +| `--scope project` | Loại bỏ từ cài đặt dự án | +| `--scope local` | Loại bỏ từ cài đặt cục bộ | +| `--scope all` | Loại bỏ từ tất cả các phạm vi cùng một lúc | | `--custom` / `-c` | Xóa `customPoliciesPath` khỏi cấu hình | -## Behavior +## Hành vi -- **Không có tên policy** - xóa tất cả các hook entries của failproofai khỏi tệp cài đặt -- **Tên cụ thể** - vô hiệu hóa các policies đó nhưng giữ nguyên hooks được cài đặt +- **Không có tên chính sách** - loại bỏ tất cả các failproofai hook entries từ tệp cài đặt +- **Tên cụ thể** - vô hiệu hóa các chính sách đó nhưng giữ các hook được cài đặt -## Examples +## Ví dụ ```bash -# Xóa tất cả hooks toàn cục +# Loại bỏ tất cả các hook toàn cục failproofai policies --uninstall -# Vô hiệu hóa một policy cụ thể (giữ nguyên hooks được cài đặt) +# Vô hiệu hóa một chính sách cụ thể (giữ các hook được cài đặt) failproofai policies --uninstall block-sudo -# Xóa hooks từ mọi phạm vi +# Loại bỏ các hook từ mọi phạm vi failproofai policies --uninstall --scope all -# Xóa đường dẫn custom policies +# Xóa đường dẫn chính sách tùy chỉnh failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/vi/cli/update.mdx b/docs/vi/cli/update.mdx new file mode 100644 index 00000000..3ecc1d10 --- /dev/null +++ b/docs/vi/cli/update.mdx @@ -0,0 +1,64 @@ +--- +title: Cập nhật sau khi nâng cấp +description: "Hoàn thành phần còn lại của quá trình nâng cấp mà npm không thể thực hiện: di chuyển home và đồng bộ hóa daemon" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +Đó là toàn bộ quá trình nâng cấp. `npm` thay thế CLI; `failproofai update` thực hiện phần còn lại. + +## Tại sao cần một lệnh thứ hai + +`npm install -g` thay thế một thứ — CLI. Hai phần khác của bản cài đặt failproofai nằm bên ngoài package có mục đích, và chúng không di chuyển khi npm chạy: + +- **`~/.failproofai/`**, cài đặt, đăng ký cloud, lựa chọn policy và lịch sử của bạn. Một phiên bản mới có thể tổ chức nó khác nhau, và sự tổ chức lại phải được thực hiện bởi code biết cả hai cấu trúc. +- **Binary daemon `failproofaid`**, tại `~/.failproofai/bin/failproofaid-`. Nó được cố ý *không* nằm trong `node_modules`: một quá trình nâng cấp trao đổi file dưới một service đang chạy sẽ trỏ một daemon trực tiếp đến binary được xây dựng từ mã nguồn khác nhau, và xóa package sẽ xóa nó từ dưới một service mà sau đó sẽ bị crash-loop ở mỗi lần khởi động. + +Vì vậy sau `npm install -g` một mình, CLI là mới nhưng daemon thì không. `failproofaid` từ chối khởi động đối với bố cục home mà nó không hiểu — phiên bản lớn của sự không khớp đó thay vì phiên bản im lặng — vì vậy hai phần cần được đưa lại với nhau. `failproofai update` là bước đó. + +## Nó làm gì + + + + Đọc bố cục được ghi lại trong `~/.failproofai/VERSION` và chạy các bước đưa nó đến bố cục mà phiên bản này hiểu. Thường là không có — xem [`failproofai migrate`](/vi/cli/migrate). + + + Từ gói platform mà npm đã tải xuống khi có thể (không có mạng), nếu không thì từ asset phát hành cho phiên bản chính xác này, được xác minh SHA-256 trước khi sử dụng. + + + Được khảo sát thay vì giả định — một service manager báo cáo một process hoạt động ngay khi nó fork, đó không phải là điều tương tự như nó hoạt động. + + + +## Tùy chọn + +| Flag | Hiệu ứng | +|------|---------| +| `--no-daemon` | Chỉ di chuyển home, để daemon ở phiên bản hiện tại của nó. | + + + `--no-daemon` để lại một daemon bị lệch phiên bản tại chỗ. Trên một máy được cấu hình yêu cầu daemon, mỗi sự kiện hook **thất bại đóng** nếu daemon không thể trả lời — và daemon từ chối khởi động đối với home đã di chuyển không thể trả lời. Nên để cho phần daemon chạy. + + +## Nếu có sự cố + +Lệnh thoát với mã khác 0 và nói phần nào thất bại. Hai trường hợp đáng biết: + +- **Một bước migration không hoàn thành.** Home được để lại được đánh dấu với bố cục *cũ* của nó, vì vậy lệnh tiếp theo sẽ thử lại — không home nào được đánh dấu hiện tại dựa trên một phần migration không hoàn thành. Bản sao cài đặt và đăng ký của bạn đã được lưu trước khi bất cứ điều gì chạy, trong `~/.failproofai/migrations/backup-layout/`. +- **Daemon không thể được khởi động lại mà không cần mật khẩu.** `sudo -n` được sử dụng cố ý, vì vậy không gì bao giờ nhắc từ dưới màn hình tiến trình. Lệnh in dòng chính xác để bạn tự chạy. + + + Không có gì ở đây cần trình hướng dẫn thiết lập tương tác. Cài đặt, đăng ký cloud và lựa chọn policy của bạn tồn tại qua một quá trình nâng cấp, vì vậy một máy đã di chuyển thực thi chính xác như trước — điều này quan trọng nhất trên các máy không có ai ngồi ở đó: một CI runner, một hộp fleet, một gateway headless. + + +## Tự động hóa nó + +`failproofai update` là không tương tác và an toàn khi chạy khi không có gì để làm — nó báo cáo "không cần migration" và thoát 0. Đưa nó vào sau mỗi quá trình nâng cấp trong script provisioning hoặc Dockerfile là cách sử dụng dự định: + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +(`--no-daemon` trong xây dựng image, nơi chưa có service để khởi động lại.) \ No newline at end of file diff --git a/docs/vi/configuration.mdx b/docs/vi/configuration.mdx index 28827100..525e4954 100644 --- a/docs/vi/configuration.mdx +++ b/docs/vi/configuration.mdx @@ -1,11 +1,11 @@ --- --- title: Cấu hình -description: "Định dạng tệp cấu hình, hệ thống ba phạm vi, và quy tắc hợp nhất" +description: "Định dạng tệp cấu hình, hệ thống ba phạm vi, và quy tắc gộp" icon: gear --- -failproofai sử dụng các tệp cấu hình JSON để kiểm soát những chính sách nào hoạt động, cách chúng hoạt động và vị trí tải các chính sách tùy chỉnh. Cấu hình được thiết kế dễ dàng để chia sẻ với nhóm của bạn - cam kết nó vào kho của bạn và mọi nhà phát triển sẽ nhận được lưới an toàn agent giống nhau. +failproofai sử dụng các tệp cấu hình JSON để kiểm soát những chính sách nào đang hoạt động, cách hoạt động của chúng, và nơi tải các chính sách tùy chỉnh. Cấu hình được thiết kế để dễ dàng chia sẻ với nhóm của bạn - cam kết nó vào repo của bạn và mọi nhà phát triển sẽ nhận được cùng một lưới bảo vệ agent. --- @@ -14,45 +14,45 @@ failproofai sử dụng các tệp cấu hình JSON để kiểm soát những c Có ba phạm vi cấu hình, được đánh giá theo thứ tự ưu tiên: | Phạm vi | Đường dẫn tệp | Mục đích | -|---------|---------------|---------| -| **dự án** | `.failproofai/policies-config.json` | Cài đặt theo kho, được cam kết vào kiểm soát phiên bản | -| **cục bộ** | `.failproofai/policies-config.local.json` | Ghi đè cục bộ cá nhân theo kho, được gitignore | -| **toàn cục** | `~/.failproofai/policies-config.json` | Giá trị mặc định cấp người dùng trên tất cả các dự án | +|-------|-----------|---------| +| **project** | `.failproofai/policies-config.json` | Cài đặt cho mỗi kho, được cam kết vào kiểm soát phiên bản | +| **local** | `.failproofai/policies-config.local.json` | Ghi đè cá nhân cho mỗi kho, được gitignore | +| **global** | `~/.failproofai/policies-config.json` | Giá trị mặc định ở cấp người dùng trên tất cả các dự án | -Khi failproofai nhận một sự kiện hook, nó tải và hợp nhất cả ba tệp tồn tại cho thư mục làm việc hiện tại. +Khi failproofai nhận sự kiện hook, nó tải và gộp cả ba tệp tồn tại cho thư mục làm việc hiện tại. -### Quy tắc hợp nhất +### Quy tắc gộp -**`enabledPolicies`** - sự hợp nhất của tất cả ba phạm vi. Một chính sách được bật ở bất kỳ mức nào là hoạt động. +**`enabledPolicies`** - hợp của cả ba phạm vi. Chính sách được bật ở bất kỳ cấp nào đều hoạt động. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← hợp nhất được khử trùng +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← hợp loại bỏ trùng lặp ``` -**`policyParams`** - phạm vi đầu tiên xác định tham số cho một chính sách nhất định sẽ thắng hoàn toàn. Không có hợp nhất sâu của các giá trị trong tham số của chính sách. +**`policyParams`** - phạm vi đầu tiên xác định tham số cho chính sách nhất định sẽ thắng hoàn toàn. Không có gộp sâu các giá trị trong tham số của chính sách. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← dự án thắng, toàn cục bị bỏ qua +resolved: { allowPatterns: ["sudo apt-get update"] } ← project thắng, global bị bỏ qua ``` ```text -project: (không có mục block-sudo) -local: (không có mục block-sudo) +project: (không có entry block-sudo) +local: (không có entry block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi xuống toàn cục +resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi xuống global ``` -**`customPoliciesPaths` / `customPoliciesPath`** - phạm vi đầu tiên xác định bất kỳ dạng nào sẽ thắng. +**`customPoliciesPaths` / `customPoliciesPath`** - phạm vi đầu tiên xác định một trong hai dạng sẽ thắng. -**`disabledCustomPolicies`** - sự hợp nhất trên tất cả các phạm vi. Bảng điều khiển ghi một ID được xác định nguồn ở đây khi bạn tắt một chính sách riêng lẻ từ một tệp chính sách rõ ràng hoặc quy ước. Các chính sách không được liệt kê vẫn được bật theo mặc định; ID bao gồm tệp nguồn để các chính sách cùng tên trong nhiều tệp có thể được kiểm soát độc lập. +**`disabledCustomPolicies`** - hợp trên tất cả các phạm vi. Bảng điều khiển ghi một ID có nguồn tại đây khi bạn tắt từng chính sách từ tệp chính sách rõ ràng hoặc quy ước. Các chính sách không được liệt kê vẫn được bật theo mặc định; ID bao gồm tệp nguồn để các chính sách cùng tên trong nhiều tệp có thể được kiểm soát độc lập. **`llm`** - phạm vi đầu tiên xác định nó sẽ thắng. @@ -105,25 +105,25 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi xuống toàn c Loại: `string[]` -Danh sách tên chính sách để bật. Tên phải khớp chính xác với các định danh chính sách được hiển thị bởi `failproofai policies`. Xem [Built-in Policies](/vi/built-in-policies) để xem danh sách đầy đủ. +Danh sách tên chính sách để bật. Tên phải khớp chính xác với các mã định danh chính sách được hiển thị bởi `failproofai policies`. Xem [Chính sách tích hợp sẵn](/vi/built-in-policies) để xem danh sách đầy đủ. -Các chính sách không có trong `enabledPolicies` không hoạt động, ngay cả khi chúng có các mục trong `policyParams`. +Các chính sách không trong `enabledPolicies` không hoạt động, ngay cả khi chúng có mục nhập trong `policyParams`. ### `policyParams` Loại: `Record>` -Ghi đè tham số theo chính sách. Khóa ngoài là tên chính sách; các khóa bên trong là cụ thể cho chính sách. Mỗi chính sách ghi lại các tham số khả dụng của nó trong [Built-in Policies](/vi/built-in-policies). +Ghi đè tham số cho mỗi chính sách. Khóa bên ngoài là tên chính sách; các khóa bên trong là cụ thể cho chính sách. Mỗi chính sách ghi lại các tham số có sẵn của nó trong [Chính sách tích hợp sẵn](/vi/built-in-policies). -Nếu một chính sách có tham số nhưng bạn không chỉ định chúng, thì các giá trị mặc định tích hợp của chính sách sẽ được sử dụng. Người dùng không cấu hình `policyParams` hoàn toàn sẽ nhận được hành vi giống hệt các phiên bản trước. +Nếu chính sách có tham số nhưng bạn không chỉ định chúng, giá trị mặc định tích hợp sẵn của chính sách sẽ được sử dụng. Người dùng không cấu hình `policyParams` hoàn toàn sẽ nhận được hành vi giống hệt như các phiên bản trước đó. -Các khóa không xác định bên trong khối tham số của chính sách được bỏ qua im lặng tại thời điểm kích hoạt hook nhưng được đánh dấu là cảnh báo khi bạn chạy `failproofai policies`. +Các khóa không xác định bên trong khối tham số của chính sách được yên lặng bỏ qua khi hook bắn nhưng được gắn cờ là cảnh báo khi bạn chạy `failproofai policies`. -#### `hint` (liên quan) +#### `hint` (xuyên suốt) Loại: `string` (tùy chọn) -Một thông báo được nối thêm vào lý do khi một chính sách trả về `deny` hoặc `instruct`. Sử dụng nó để cung cấp hướng dẫn có thể hành động cho Claude mà không cần sửa đổi chính sách. +Một tin nhắn được thêm vào lý do khi chính sách trả về `deny` hoặc `instruct`. Sử dụng nó để cung cấp hướng dẫn có thể thực hiện được cho Claude mà không sửa đổi chính sách. Hoạt động với bất kỳ loại chính sách nào — tích hợp sẵn, tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`), hoặc quy ước người dùng (`.failproofai-user/`). @@ -131,60 +131,59 @@ Hoạt động với bất kỳ loại chính sách nào — tích hợp sẵn, { "policyParams": { "block-force-push": { - "hint": "Try creating a fresh branch instead." + "hint": "Hãy thử tạo một nhánh mới thay thế." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Use apt-get directly without sudo." + "hint": "Sử dụng apt-get trực tiếp mà không cần sudo." }, "custom/my-policy": { - "hint": "Ask the user for approval first." + "hint": "Hãy yêu cầu người dùng phê duyệt trước." } } } ``` -Khi `block-force-push` từ chối, Claude sẽ thấy: *"Force-pushing is blocked. Try creating a fresh branch instead."* +Khi `block-force-push` từ chối, Claude sẽ thấy: *"Force-pushing bị chặn. Hãy thử tạo một nhánh mới thay thế."* -Các giá trị không phải chuỗi và chuỗi trống được bỏ qua im lặng. Nếu `hint` không được đặt, hành vi không thay đổi (tương thích ngược). +Các giá trị không phải chuỗi và chuỗi rỗng được yên lặng bỏ qua. Nếu `hint` không được đặt, hành vi không thay đổi (tương thích ngược). ### `customPoliciesPath` Loại: `string` (đường dẫn tuyệt đối) -Đường dẫn đến tệp JavaScript chứa các chính sách hook tùy chỉnh. Điều này được đặt tự động bởi `failproofai policies --install --custom ` (đường dẫn được phân giải thành tuyệt đối trước khi lưu trữ). +Đường dẫn đến tệp JavaScript chứa các chính sách hook tùy chỉnh. Cái này được đặt tự động bởi `failproofai policies --install --custom ` (đường dẫn được phân giải thành tuyệt đối trước khi được lưu trữ). -Tệp được tải mới trên mỗi sự kiện hook - không có bộ nhớ đệm. Xem [Custom Policies](/vi/custom-policies) để biết chi tiết viết tác. +Tệp được tải lại trên mỗi sự kiện hook - không có bộ nhớ đệm. Xem [Chính sách tùy chỉnh](/vi/custom-policies) để biết chi tiết về tác giả. ### Chính sách dựa trên quy ước -Ngoài `customPoliciesPath` rõ ràng, failproofai sẽ tự động khám phá và tải các tệp chính sách từ các thư mục `.failproofai/policies/`: +Ngoài `customPoliciesPath` rõ ràng, failproofai tự động phát hiện và tải các tệp chính sách từ các thư mục `.failproofai/policies/`: -| Mức | Thư mục | Phạm vi | -|-----|---------|--------| +| Cấp | Thư mục | Phạm vi | +|-------|-----------|-------| | Dự án | `.failproofai/policies/` | Chia sẻ với nhóm thông qua kiểm soát phiên bản | -| Người dùng | `~/.failproofai/policies/custom-policies/` | Cá nhân, áp dụng cho tất cả các dự án | +| Người dùng | `~/.failproofai/policies/` | Cá nhân, áp dụng cho tất cả dự án | - Thư mục cấp người dùng đã di chuyển xuống một mức trong tái tổ chức thư mục chính. - Các tệp để lại ở vị trí cũ `~/.failproofai/policies/` sẽ được di chuyển tự động - vào `custom-policies/` lần đầu tiên bạn chạy bất kỳ lệnh `failproofai` nào sau khi nâng cấp, - và lệnh sẽ cho bạn biết những tệp nào đã được di chuyển. + Thả các chính sách của bạn trực tiếp vào `~/.failproofai/policies/`. Thư mục `cloud-policies/` bên cạnh chúng chứa các chính sách mà tổ chức của bạn đã triển khai cho máy này — phát hiện không đi vào thư mục con, vì vậy nó không bao giờ được quét, và không có gì bạn đặt trong `policies/` có thể va chạm với nó. + + Nếu bạn nâng cấp từ một phiên bản sử dụng `~/.failproofai/policies/custom-policies/`, mọi thứ trong thư mục đó — các tệp chính sách của bạn, bất kỳ `lib/` trợ giúp nào mà chúng nhập, và bất kỳ tệp dữ liệu nào mà chúng đọc — được di chuyển lại tự động lần đầu tiên bạn chạy lệnh `failproofai`, và lệnh cho bạn biết nó di chuyển cái gì. -**Khớp tệp:** Chỉ các tệp khớp `*policies.{js,mjs,ts}` được tải (ví dụ: `security-policies.mjs`, `workflow-policies.js`). Các tệp khác trong thư mục sẽ bị bỏ qua. +**Khớp tệp:** Chỉ các tệp khớp với `*policies.{js,mjs,ts}` được tải (ví dụ: `security-policies.mjs`, `workflow-policies.js`). Các tệp khác trong thư mục bị bỏ qua. -**Không cần cấu hình:** Các chính sách quy ước không yêu cầu bất kỳ mục nào trong `policies-config.json`. Chỉ cần thả các tệp vào thư mục và chúng sẽ được nhặt trên sự kiện hook tiếp theo. +**Không cần cấu hình:** Các chính sách quy ước không cần các mục nhập trong `policies-config.json`. Chỉ cần thả tệp vào thư mục và chúng sẽ được nhặt lên vào sự kiện hook tiếp theo. -**Tải kết hợp:** Cả thư mục quy ước dự án và người dùng đều được quét. Tất cả các tệp khớp từ cả hai mức đều được tải (không giống `customPoliciesPath` sử dụng phạm vi thắng đầu tiên). +**Tải hợp:** Cả thư mục quy ước dự án và người dùng đều được quét. Tất cả các tệp phù hợp từ cả hai cấp đều được tải (không giống `customPoliciesPath` sử dụng first-scope-wins). -Xem [Custom Policies](/vi/custom-policies) để biết thêm chi tiết và ví dụ. +Xem [Chính sách tùy chỉnh](/vi/custom-policies) để biết thêm chi tiết và ví dụ. ### `llm` Loại: `object` (tùy chọn) -Cấu hình máy khách LLM cho các chính sách thực hiện các cuộc gọi AI. Không bắt buộc cho hầu hết các thiết lập. +Cấu hình máy khách LLM cho các chính sách thực hiện các lệnh gọi AI. Không bắt buộc cho hầu hết các cài đặt. ```json { @@ -199,24 +198,24 @@ Cấu hình máy khách LLM cho các chính sách thực hiện các cuộc gọ ## Quản lý cấu hình từ CLI -Các lệnh `policies --install` và `policies --uninstall` ghi vào tệp cài đặt hook của CLI agent của bạn (các điểm vào hook), trong khi `policies-config.json` là tệp bạn quản lý trực tiếp. Hai cái này là riêng biệt: +Các lệnh `policies --install` và `policies --uninstall` ghi vào tệp cài đặt hook của CLI agent của bạn (các điểm nhập hook), trong khi `policies-config.json` là tệp bạn quản lý trực tiếp. Hai cái này là riêng biệt: -- **Cài đặt Agent CLI** — yêu cầu agent gọi `failproofai --hook ` trên mỗi lần sử dụng công cụ: +- **Cài đặt CLI Agent** — cho agent biết gọi `failproofai --hook ` trên mỗi lần sử dụng công cụ: - **Claude Code**: `~/.claude/settings.json` (người dùng), `/.claude/settings.json` (dự án), `/.claude/settings.local.json` (cục bộ) - **OpenAI Codex**: `~/.codex/hooks.json` (người dùng), `/.codex/hooks.json` (dự án) — Codex không có phạm vi `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (người dùng), `/.github/hooks/failproofai.json` (dự án) — Copilot không có phạm vi `local`. Các mục hook sử dụng các trường lệnh `bash`/`powershell` được đặt khóa OS của Copilot với `timeoutSec`; tệp mang một đánh dấu cấp cao nhất `version: 1`. Hỗ trợ Copilot CLI là **beta** trong khi chúng tôi xác minh lược đồ bản ghi `events.jsonl` (không được chỉ định trong tài liệu công cộng) so với các phiên thực tế hơn. **Chế độ đại lý VS Code Copilot Chat (Xem trước)** đọc cấu hình hook từ `.github/hooks/*.json`, `~/.copilot/hooks/*.json` và `~/.claude/settings.json` (được chi phối bởi cài đặt `chat.hookFilesLocations`) sử dụng hợp đồng `{hookSpecificOutput:{permissionDecision:"deny",…}}` hình dạng Claude giống nhau — chính xác những đường dẫn mà tích hợp `copilot` và tích hợp `claude` (`~/.claude/settings.json`) đã viết, vì vậy `failproofai policies --install --cli copilot` (hoặc `--cli claude`) **đã thực thi trong chế độ đại lý VS Code** mà không cần tích hợp `vscode` riêng biệt (được xác nhận trực tiếp từ nhật ký khám phá VS Code). - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (người dùng), `/.cursor/hooks.json` (dự án) — Cursor không có phạm vi `local`. Các mục hook sử dụng dạng `{type, command, timeout}` hình dạng Claude (không có chia nhỏ `bash`/`powershell`), nhưng được lưu trữ dưới các khóa sự kiện camelCase (`preToolUse`, `beforeSubmitPrompt`, …) trong một mảng phẳng cho mỗi [lược đồ hook](https://cursor.com/docs/hooks) của Cursor. Tệp mang một đánh dấu cấp cao nhất `version: 1`. Trình xử lý chuẩn hóa camelCase → PascalCase qua `CURSOR_EVENT_MAP` để các chính sách tích hợp sẵn hiện tại kích hoạt không thay đổi. Hỗ trợ Cursor Agent là **beta** trong khi chúng tôi xác minh định dạng bảng điểm Cursor trên đĩa (không được chỉ định trong tài liệu công cộng) so với các cài đặt thực tế hơn. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (người dùng), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (dự án) — OpenCode không có phạm vi `local`. Không giống như năm CLI khác, OpenCode **không có hệ thống hook lệnh bên ngoài**: nó tải các plugin JS/TS được xử lý trong quy trình được đăng ký rõ ràng qua mảng `plugin: []` trong `opencode.json` (tự động khám phá từ `.opencode/plugins/` **không** phải cách các plugin tải trên opencode v1.14.33). Cài đặt thả một shim plugin nhỏ được tạo ra sẽ gọi tệp nhị phân failproofai trong subprocess và dịch phản hồi JSON hình dạng Claude của tệp nhị phân trở lại ngữ nghĩa plugin: `throw new Error()` cho lần từ chối sự kiện công cụ (hủy bỏ lệnh gọi công cụ), `client.session.prompt(...)` cho lệnh **và** cho từ chối `Stop` / `SubagentStop` (gửi lý do từ chối làm thông báo người dùng tiếp theo — kênh buộc thử lại duy nhất vì `session.idle` chỉ là thông báo và ném từ nó là nó không hoạt động), và không hoạt động cho phép. Shim chuẩn hóa cả tên công cụ (chữ thường → PascalCase qua `OPENCODE_TOOL_MAP`) và khóa đối số đầu vào công cụ (camelCase → snake_case qua `OPENCODE_TOOL_INPUT_MAP` cho `Read` / `Write` / `Edit`, ví dụ: `filePath` → `file_path`, `oldString` → `old_string`) trước khi chuyển tiếp đến tệp nhị phân, để kiểm tra đường dẫn các tính năng tích hợp sẵn như `block-read-outside-cwd`, `block-env-files` và `block-secrets-write` kích hoạt không thay đổi trên lệnh gọi công cụ OpenCode. Các phiên sống trong cơ sở dữ liệu SQLite của opencode tại `~/.local/share/opencode/opencode.db`; trình xem phiên của bảng điều khiển đọc chúng qua `opencode db --format json` và `opencode export `. Hỗ trợ OpenCode là **beta** trong khi chúng tôi xác minh hành vi trên các phiên bản và so với các phiên thực tế hơn. Xem [tài liệu plugin OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (người dùng), `/.pi/settings.json` (dự án) — Pi không có phạm vi `local`. Pi tải các gói mở rộng TypeScript tại khởi động; tệp cài đặt là mảng chuỗi phẳng `{"packages": ["./relative/path", …]}`. failproofai ghi một mục mảng gói duy nhất trỏ đến thư mục `pi-extension/` được đóng gói của nó. Phần mở rộng nội bộ đăng ký cho các sự kiện `tool_call` / `user_bash` / `input` / `session_start` của Pi và lệnh shell đến `failproofai --hook --cli pi`; trình xử lý chuẩn hóa snake_case lower case dấu gạch dưới → PascalCase qua `PI_EVENT_MAP` để các chính sách tích hợp sẵn hiện tại kích hoạt không thay đổi. Các đối số đầu vào công cụ cũng được chuẩn hóa qua `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit cung cấp `path` thay vì `file_path`; ánh xạ khóa cấp cao nhất cho phép `block-env-files` và `block-secrets-write` kích hoạt — `block-read-outside-cwd` đã có sự dự phòng `path`). Hỗ trợ Pi là **beta** trong khi API mở rộng Pi và bố cục nhật ký phiên ổn định. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**chỉ phạm vi người dùng** — Hermes không có cấu hình dự án/cục bộ). Hermes là **cổng** Slack/Telegram, vì vậy một cài đặt chặn các cuộc gọi công cụ từ mọi nền tảng (Slack/Telegram/cli/cron) **và** các tác nhân con bên trong. Các mục hook là cặp `{command, timeout}` (thời chờ tính bằng **giây**) dưới bản đồ `hooks:` được khóa bởi các sự kiện snake_case của Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); trình xử lý chuẩn hóa sự kiện qua `HERMES_EVENT_MAP` và tên công cụ qua `HERMES_TOOL_MAP` để các chính sách tích hợp sẵn kích hoạt không thay đổi. Cấu hình được chỉnh sửa thông qua vòng lặp `Document` YAML bảo toàn comment để các cài đặt khác của toán tử sống sót, và cài đặt `hooks_auto_accept: true` để cổng không đầu (không TTY) chạy các hook mà không nhắc yêu cầu sự đồng ý. Người đánh giá phát ra hợp đồng `{"decision":"block","reason"}` stdout của Hermes (Hermes bỏ qua mã thoát). **Hạn chế:** Hermes không có sự kiện `Stop` cuối lượt, vì vậy các tính năng tích hợp sẵn `require-*-before-stop` không bao giờ kích hoạt cho nó (không áp dụng, không bị hỏng); `instruct` giảm xuống cho phép với ghi chú đã ghi (không có kênh ngữ cảnh bổ sung); và redaction bí mật đầu ra (`sanitize-*`) không thể viết lại đầu ra công cụ trên hợp đồng hook shell. Hermes cũng là một nguồn kiểm toán **ngoại tuyến** — bảng điều khiển đọc các phiên cổng của nó trực tiếp từ `~/.hermes/state.db`. - - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**chỉ phạm vi người dùng** — OpenClaw không có cấu hình dự án/cục bộ). Giống như Hermes, OpenClaw là **cổng** đa kênh tự lưu trữ, vì vậy một cài đặt chặn các cuộc gọi công cụ từ mọi kênh và các tác nhân con bên trong của nó. Thực thi chạy qua **các hook plugin được xử lý trong quy trình** của OpenClaw (các hook dựa trên tệp nội bộ của nó chỉ được quan sát và không thể chặn), vì vậy — giống như OpenCode/Pi — failproofai gửi một gói `openclaw-plugin/` tĩnh sẽ async-spawn tệp nhị phân failproofai và dịch phán quyết. Cài đặt đăng ký thư mục plugin được gửi trong `openclaw.json` của `plugins.load.paths[]` và bật nó dưới `plugins.entries.failproofai` (với `hooks.allowConversationAccess: true`, bắt buộc cho các hook cuộc trò chuyện thô). Người đánh giá phát ra phán quyết phẳng `{permission, reason}` và shim ánh xạ nó vào hình dạng trả lại riêng của mỗi hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), và `before_agent_finalize → {action:"revise", reason}` (**Stop** — cổng cuối lượt thực sự, vì vậy các tính năng tích hợp sẵn `require-*-before-stop` **thực thi** trên OpenClaw, không giống Hermes). Các sự kiện và tên công cụ chuẩn hóa phía tệp nhị phân qua `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) để các chính sách tích hợp sẵn kích hoạt không thay đổi; shim không thành công nếu có lỗi spawn/parse/timeout. OpenClaw cũng là một nguồn kiểm toán **ngoại tuyến** — bảng điều khiển đọc các phiên JSONL của nó tại `~/.openclaw/agents//sessions/.jsonl`. - - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (người dùng), `/.factory/hooks.json` (dự án) — Factory không có phạm vi `local`. droid gửi hệ thống hook lệnh bên ngoài hình dạng Claude, nhưng với hai lạ được xác minh trực tiếp với droid v0.171.0: (1) tên sự kiện sống tại **mức cao nhất** của `hooks.json` — có **không có bọc `"hooks"`** (droid từ chối một); các sự kiện công cụ (`PreToolUse`/`PostToolUse`) mang `"matcher": "*"`, các sự kiện không phải công cụ bỏ qua nó. (2) Từ chối được điều hành bởi **mã thoát hook 2 + stderr**, không phải quyết định JSON — nhánh `factory` của người đánh giá trả về thoát 2 cho sự kiện công cụ/nhắc nhở và `{decision:"block", reason}` chỉ trên sự kiện cuối lượt `Stop` (kênh buộc thử lại duy nhất của droid). Các sự kiện đã là PascalCase (không có bản đồ sự kiện) và tải trọng là snake_case Claude; chỉ tên công cụ được chuẩn hóa qua `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory cũng là một nguồn kiểm toán **ngoại tuyến** — bảng điều khiển đọc các phiên JSONL trên đĩa của nó tại `~/.factory/sessions//.jsonl`. - - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (người dùng), `/.devin/config.json` (dự án) — Devin không có phạm vi `local`. Devin là một **Claude-bản sao thuần túy** được xác minh trực tiếp với devin v3000.1.27: nó sử dụng lược đồ `"hooks"`-bọc Claude tiêu chuẩn (ghi giữ hợp nhất để các khóa khác của tệp cấu hình — `org_id`, `theme_mode`, … — sống sót), tên sự kiện đã là PascalCase (không có bản đồ sự kiện, không có nhánh trình xử lý) và tải trọng stdin snake_case Claude (không có chuẩn hóa). Nhánh `devin` của người đánh giá từ chối với JSON `{"decision":"block","reason"}` trên stdout tại thoát 0 cho **mọi** sự kiện (xác minh — khối ghi đè `--permission-mode dangerous`); trên sự kiện `Stop` cuối lượt lý do mang từ ngữ force-retry bắt buộc để các tính năng tích hợp sẵn `require-*-before-stop` thực thi. Chỉ tên công cụ được chuẩn hóa qua `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` đã là chính tắc). Devin cũng là một nguồn kiểm toán **ngoại tuyến** — bảng điều khiển đọc các phiên SQLite của nó tại `~/.local/share/devin/cli/sessions.db` (mỗi hàng `sessions` mang một `working_directory` thực sự, vì vậy các phiên nhóm theo thư mục làm việc dự án như Claude). - - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (người dùng), `/.agents/hooks.json` (dự án) — Antigravity không có phạm vi `local`. Không giống Factory/Devin, Antigravity có **hợp đồng riêng của nó** (không phải Claude-bản sao), được xác minh trực tiếp với agy v1.1.2. `hooks.json` sử dụng **lược đồ hook có tên**: khóa cấp cao nhất là một tên hook *name* (`"failproofai"`) có giá trị là bản đồ sự kiện→trình xử lý — các sự kiện công cụ (`PreToolUse`/`PostToolUse`) bọc trình xử lý trong `{matcher:"*", hooks:[…]}`, trong khi `PreInvocation`/`Stop` là **phẳng** mảng trình xử lý (các hook có tên khác được bảo tồn). Tải trọng stdin là **protojson camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai chuẩn hóa nó thành snake_case trước khi các chính sách chạy và ánh xạ các đối số `run_command` của PascalCase (`CommandLine`/`Cwd`) qua `ANTIGRAVITY_TOOL_INPUT_MAP`. Nhánh `antigravity` của người đánh giá sử dụng **hình dạng phản hồi riêng của Antigravity**: `{decision:"deny", reason}` chặn một công cụ/nhắc nhở (thoát 0), `{decision:"continue", reason}` trên sự kiện `Stop` cuối lượt tái nhập vòng lặp (vì vậy các tính năng tích hợp sẵn `require-*-before-stop` thực thi), và `{injectSteps:[{ephemeralMessage}]}` tiêm một hướng dẫn trên `PreInvocation` (→ `UserPromptSubmit`). Các tên công cụ chuẩn hóa qua `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity cũng là một nguồn kiểm toán **ngoại tuyến** — bảng điều khiển đọc bản ghi phiên JSONL thô của nó tại `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (chỉ mục cuộc trò chuyện trong `conversation_summaries.db`). - - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (người dùng), `/.agents/plugins/failproofai/hooks/hooks.json` (dự án) — Goose không có phạm vi `local`. Thực thi sử dụng hệ thống **hooks** của Goose, **lực đặc biệt Open Plugins** theo tiêu chuẩn: trình cài đặt chỉ thả thư mục plugin `failproofai` và Goose tự động khám phá nó tại khởi động (tự đăng ký nó vào `~/.config/goose/config.yaml`). `hooks.json` sử dụng lược đồ Open Plugins **có** bọc cấp cao nhất `"hooks"`, và các trận đấu được **bỏ qua** trên mọi sự kiện — `"*"` trần là biểu thức chính quy không hợp lệ không khớp bất cứ điều gì (xác minh trực tiếp với goose v1.43.0). Tên sự kiện đã là PascalCase (không có bản đồ sự kiện); tải trọng stdin sử dụng `event`/`working_dir`, mà trình xử lý chuẩn hóa thành `hook_event_name`/`cwd`. Nhánh `goose` của người đánh giá từ chối với JSON `{"decision":"block","reason"}` trên stdout tại thoát 0, được tôn trọng trên sự kiện **`PreToolUse`** duy nhất (được gửi trong goose ≥ v1.37.0) — kích hoạt cho công cụ shell **và bên trong các tác nhân con được ủy quyền**, vì vậy đó là điểm từ chối duy nhất đủ; lỗi hook khác bất kỳ không thành công **mở**. Goose **không có sự kiện `Stop`**, vì vậy các tính năng tích hợp sẵn `require-*-before-stop` không áp dụng (như với Hermes). Các tên công cụ chuẩn hóa qua `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) và khóa đường dẫn qua `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose cũng là một nguồn kiểm toán **ngoại tuyến** — bảng điều khiển đọc các phiên SQLite của nó tại `~/.local/share/goose/sessions/sessions.db` (mỗi hàng `sessions` mang một `working_dir` thực sự, vì vậy các phiên nhóm theo thư mục làm việc dự án như Devin; chạy không phiên `--no-session` được lọc). -- **`policies-config.json`** — yêu cầu failproofai chính sách nào để đánh giá và với những tham số (được chia sẻ trên tất cả CLI agent) - -Chuyển `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` để nhắm đến một agent cụ thể (cách nhau bằng dấu cách hoặc lặp lại cho bất kỳ tập hợp con nào): + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (người dùng), `/.github/hooks/failproofai.json` (dự án) — Copilot không có phạm vi `local`. Các mục hook sử dụng các trường lệnh `bash`/`powershell` được khóa hệ điều hành của Copilot với `timeoutSec`; tệp mang một dấu `version: 1` ở cấp cao nhất. Hỗ trợ Copilot CLI ở trạng thái **beta** khi chúng tôi xác minh lược đồ bản ghi `events.jsonl` (mà tài liệu công khai không chỉ định) so với nhiều phiên làm việc thực tế hơn. **Chế độ agent Copilot Chat VS Code (Xem trước)** đọc cấu hình hook từ `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, và `~/.claude/settings.json` (được kiểm soát bởi cài đặt `chat.hookFilesLocations`) sử dụng cùng một hợp đồng Claude-shaped `{hookSpecificOutput:{permissionDecision:"deny",…}}` — các đường dẫn chính xác mà tích hợp `copilot` và tích hợp `claude` (`~/.claude/settings.json`) đã ghi, vì vậy `failproofai policies --install --cli copilot` (hoặc `--cli claude`) **đã thực thi ở chế độ agent VS Code** mà không cần tích hợp `vscode` riêng biệt (được xác nhận trực tiếp từ nhật ký khám phá VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (người dùng), `/.cursor/hooks.json` (dự án) — Cursor không có phạm vi `local`. Các mục hook sử dụng dạng Claude-shaped `{type, command, timeout}` (không tách `bash`/`powershell`), nhưng được lưu trữ dưới các khóa sự kiện camelCase (`preToolUse`, `beforeSubmitPrompt`, …) trong một mảng phẳng trên mỗi lược đồ hook của Cursor. Tệp mang một dấu `version: 1` ở cấp cao nhất. Trình xử lý chuẩn hóa camelCase → PascalCase thông qua `CURSOR_EVENT_MAP` để các chính sách tích hợp sẵn hiện có bắn không thay đổi. Hỗ trợ Cursor Agent ở trạng thái **beta** khi chúng tôi xác minh định dạng bản ghi của Cursor trên đĩa (không được chỉ định trong tài liệu công khai) so với nhiều cài đặt thực tế hơn. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (người dùng), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (dự án) — OpenCode không có phạm vi `local`. Không giống như năm CLI khác, OpenCode **không có hệ thống hook lệnh bên ngoài**: nó tải các plugin JS/TS trong quá trình được đăng ký rõ ràng thông qua mảng `plugin: []` trong `opencode.json` (tự động phát hiện từ `.opencode/plugins/` **không phải** cách các plugin tải trên opencode v1.14.33). Cài đặt thả một shimcông cụ nhỏ được tạo ra thực thi subprocess-call nhị phân failproofai và dịch phản hồi JSON có dạng Claude của nhị phân trở lại ngữ nghĩa plugin: `throw new Error()` cho từ chối sự kiện công cụ (hủy lệnh gọi công cụ), `client.session.prompt(...)` cho instruct VÀ cho từ chối `Stop` / `SubagentStop` (gửi lý do từ chối làm tin nhắn người dùng tiếp theo — kênh force-retry duy nhất vì `session.idle` là thông báo-chỉ và ném từ nó là không có hoạt động), và không có hoạt động cho allow. Shim chuẩn hóa cả tên công cụ (chữ thường → PascalCase thông qua `OPENCODE_TOOL_MAP`) và khóa đối số đầu vào công cụ (camelCase → snake_case thông qua `OPENCODE_TOOL_INPUT_MAP` cho `Read` / `Write` / `Edit`, ví dụ: `filePath` → `file_path`, `oldString` → `old_string`) trước khi chuyển tiếp đến nhị phân, vì vậy các phần tích hợp kiểm tra đường dẫn như `block-read-outside-cwd`, `block-env-files`, và `block-secrets-write` bắn không thay đổi trên các lệnh gọi công cụ OpenCode. Các phiên được giữ trong cơ sở dữ liệu SQLite của opencode tại `~/.local/share/opencode/opencode.db`; trình xem phiên của bảng điều khiển đọc chúng thông qua `opencode db --format json` và `opencode export `. Hỗ trợ OpenCode ở trạng thái **beta** khi chúng tôi xác minh hành vi trên các phiên bản và so với nhiều phiên làm việc thực tế hơn. Xem [tài liệu plugin OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (người dùng), `/.pi/settings.json` (dự án) — Pi không có phạm vi `local`. Pi tải các gói mở rộng TypeScript khi khởi động; tệp cài đặt là một mảng chuỗi phẳng `{"packages": ["./relative/path", …]}`. failproofai ghi một mục mảng gói đơn trỏ tại thư mục `pi-extension/` được gói của nó. Phần mở rộng được đăng ký nội bộ để đăng ký các sự kiện `tool_call` / `user_bash` / `input` / `session_start` của Pi và yêu cầu đến `failproofai --hook --cli pi`; trình xử lý chuẩn hóa underscore_lower_snake_case → PascalCase thông qua `PI_EVENT_MAP` để các chính sách tích hợp sẵn hiện có bắn không thay đổi. Các đối số đầu vào công cụ cũng được chuẩn hóa thông qua `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit cung cấp `path` thay vì `file_path`; ánh xạ khóa cấp cao nhất cho phép `block-env-files` và `block-secrets-write` bắn — `block-read-outside-cwd` đã có một fallback `path`). Hỗ trợ Pi ở trạng thái **beta** khi API mở rộng của Pi và bố cục nhật ký phiên được ổn định. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**phạm vi người dùng chỉ** — Hermes không có cấu hình dự án/cục bộ). Hermes là một cổng **gateway** Slack/Telegram, vì vậy một cài đặt chặn các lệnh gọi công cụ từ mọi nền tảng (Slack/Telegram/cli/cron) **và** subagent nội bộ. Các mục hook là một cặp `{command, timeout}` (timeout tính bằng **giây**) dưới một bản đồ `hooks:` được khóa bởi các sự kiện snake_case của Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); trình xử lý chuẩn hóa các sự kiện thông qua `HERMES_EVENT_MAP` và tên công cụ thông qua `HERMES_TOOL_MAP` để các chính sách tích hợp sẵn bắn không thay đổi. Cấu hình được chỉnh sửa thông qua vòng dữ liệu YAML `Document` bảo tồn nhận xét để cài đặt khác của nhà điều hành được giữ lại, và cài đặt đặt `hooks_auto_accept: true` để cổng không đầu (không TTY) chạy các hook mà không có lời nhắc đồng ý. Đánh giá phát ra hợp đồng stdout `{"decision":"block","reason"}` của Hermes (Hermes bỏ qua mã thoát). **Hạn chế:** Hermes không có sự kiện `Stop` ở cuối lượt, vì vậy các phần tích hợp `require-*-before-stop` không bao giờ bắn cho nó (không áp dụng, không bị hỏng); `instruct` suy giảm thành allow-with-logged-note (không kênh ngữ cảnh bổ sung); và thay thế bí mật đầu ra (`sanitize-*`) không thể viết lại đầu ra công cụ trên hợp đồng hook-shell. Hermes **cũng** là một nguồn **kiểm toán** ngoại tuyến — bảng điều khiển đọc các phiên gateway của nó trực tiếp từ `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**phạm vi người dùng chỉ** — OpenClaw không có cấu hình dự án/cục bộ). Giống như Hermes, OpenClaw là một cổng **gateway** đa kênh tự lưu trữ, vì vậy một cài đặt chặn các lệnh gọi công cụ từ mọi kênh và subagent nội bộ của nó. Thực thi chạy qua các hook plugin **trong quá trình** của OpenClaw (các hook dựa trên tệp nội bộ của nó chỉ dành cho quan sát và không thể chặn), vì vậy — giống như OpenCode/Pi — failproofai gửi một gói `openclaw-plugin/` tĩnh thực thi async-spawn nhị phân failproofai và dịch bản phán quyết. Cài đặt đăng ký thư mục plugin được gửi trong `openclaw.json` của `plugins.load.paths[]` và kích hoạt nó dưới `plugins.entries.failproofai` (với `hooks.allowConversationAccess: true`, cần thiết cho các hook cuộc trò chuyện thô). Đánh giá phát ra một bản phán quyết phẳng `{permission, reason}` và shim ánh xạ nó đến hình dạng gốc của mỗi hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), và `before_agent_finalize → {action:"revise", reason}` (**Stop** — một lối chặn lượt thực end, vì vậy các phần tích hợp `require-*-before-stop` **thực thi** trên OpenClaw, không giống Hermes). Các sự kiện và tên công cụ chuẩn hóa phía nhị phân thông qua `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) để các chính sách tích hợp sẵn bắn không thay đổi; shim thất bại mở trên bất kỳ lỗi spawn/parse/timeout nào. OpenClaw **cũng** là một nguồn **kiểm toán** ngoại tuyến — bảng điều khiển đọc các phiên JSONL của nó tại `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (người dùng), `/.factory/hooks.json` (dự án) — Factory không có phạm vi `local`. droid gửi một hệ thống hook lệnh bên ngoài kiểu Claude, nhưng với hai tính quirk được xác minh trực tiếp so với droid v0.171.0: (1) tên sự kiện sống ở **cấp cao nhất** của `hooks.json` — có **không có trình bọc `"hooks"`** (droid từ chối cái); các sự kiện công cụ (`PreToolUse`/`PostToolUse`) mang `"matcher": "*"`, các sự kiện không phải công cụ bỏ qua nó. (2) Từ chối được điều khiển bởi hook **exit code 2 + stderr**, không phải quyết định JSON — nhánh `factory` của đánh giá trả về exit 2 cho sự kiện công cụ/nhắc nhở và `{decision:"block", reason}` chỉ trên sự kiện `Stop` ở cuối lượt (kênh force-retry duy nhất của droid). Các sự kiện đã ở PascalCase (không bản đồ sự kiện) và tải trọng là snake_case của Claude; chỉ tên công cụ được chuẩn hóa thông qua `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory **cũng** là một nguồn **kiểm toán** ngoại tuyến — bảng điều khiển đọc các phiên JSONL trên đĩa của nó tại `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (người dùng), `/.devin/config.json` (dự án) — Devin không có phạm vi `local`. Devin là **clone Claude thuần túy** được xác minh trực tiếp so với devin v3000.1.27: nó sử dụng lược đồ `"hooks"`-wrapper tiêu chuẩn của Claude (ghi bảo tồn-hợp nhất để các khóa khác của tệp cấu hình — `org_id`, `theme_mode`, … — được giữ lại), tên sự kiện đã-PascalCase (không bản đồ sự kiện, không nhánh xử lý), và tải trọng stdin snake_case của Claude (không chuẩn hóa). Nhánh `devin` của đánh giá từ chối với JSON `{"decision":"block","reason"}` trên stdout ở exit 0 cho **mỗi** sự kiện (được xác minh — từ chối đã ghi đè `--permission-mode dangerous`); trên sự kiện `Stop` ở cuối lượt lý do mang từ ngữ force-retry bắt buộc để các phần tích hợp `require-*-before-stop` thực thi. Chỉ tên công cụ được chuẩn hóa thông qua `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` đã là chính tắc). Devin **cũng** là một nguồn **kiểm toán** ngoại tuyến — bảng điều khiển đọc các phiên SQLite của nó tại `~/.local/share/devin/cli/sessions.db` (mỗi hàng `sessions` mang một `working_directory` thực, vì vậy các phiên nhóm theo cwd dự án như Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (người dùng), `/.agents/hooks.json` (dự án) — Antigravity không có phạm vi `local`. Không giống Factory/Devin, Antigravity có **hợp đồng riêng của nó** (không phải clone Claude), được xác minh trực tiếp so với agy v1.1.2. `hooks.json` sử dụng lược đồ **hook có tên**: khóa cấp cao nhất là tên hook *name* (`"failproofai"`) có giá trị là bản đồ sự kiện→trình xử lý — các sự kiện công cụ (`PreToolUse`/`PostToolUse`) bọc trình xử lý trong `{matcher:"*", hooks:[…]}`, trong khi `PreInvocation`/`Stop` là mảng trình xử lý **phẳng** (các hook có tên khác được giữ lại). Tải trọng stdin là **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai chuẩn hóa nó thành snake_case trước khi các chính sách chạy, và ánh xạ các đối số PascalCase của `run_command` (`CommandLine`/`Cwd`) thông qua `ANTIGRAVITY_TOOL_INPUT_MAP`. Nhánh `antigravity` của đánh giá sử dụng các hình dạng phản hồi **riêng của Antigravity**: `{decision:"deny", reason}` chặn công cụ/nhắc nhở (exit 0), `{decision:"continue", reason}` trên sự kiện `Stop` ở cuối lượt nhập lại vòng lặp (vì vậy các phần tích hợp `require-*-before-stop` thực thi), và `{injectSteps:[{ephemeralMessage}]}` tiêm hướng dẫn trên `PreInvocation` (→ `UserPromptSubmit`). Tên công cụ chuẩn hóa thông qua `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity **cũng** là một nguồn **kiểm toán** ngoại tuyến — bảng điều khiển đọc các thư viên văn bản JSONL thuần túy của nó tại `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (chỉ mục cuộc trò chuyện trong `conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (người dùng), `/.agents/plugins/failproofai/hooks/hooks.json` (dự án) — Goose không có phạm vi `local`. Thực thi sử dụng hệ thống **hooks** của Goose, đặc tả **Open Plugins** xuyên suốt agent: trình cài đặt chỉ cần thả thư mục plugin `failproofai` và Goose tự động phát hiện nó khi khởi động (tự đăng ký nó vào `~/.config/goose/config.yaml`). `hooks.json` sử dụng lược đồ Open Plugins **với** trình bọc `"hooks"` cấp cao nhất, và matcher bị **bỏ qua** trên mọi sự kiện — một `"*"` trần là regex không hợp lệ không khớp gì (được xác minh trực tiếp so với goose v1.43.0). Tên sự kiện đã ở PascalCase (không bản đồ sự kiện); tải trọng stdin sử dụng `event`/`working_dir`, mà trình xử lý chuẩn hóa thành `hook_event_name`/`cwd`. Nhánh `goose` của đánh giá từ chối với JSON `{"decision":"block","reason"}` trên stdout ở exit 0, được tôn trọng trên sự kiện **`PreToolUse`** chỉ (được gửi trong goose ≥ v1.37.0) — bắn cho công cụ shell **và bên trong subagent được ủy quyền**, vì vậy nó là điểm từ chối duy nhất đủ; bất kỳ lỗi hook nào khác thất bại **mở**. Goose **không có sự kiện `Stop`**, vì vậy các phần tích hợp `require-*-before-stop` không áp dụng (như Hermes). Tên công cụ chuẩn hóa thông qua `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) và khóa đường dẫn thông qua `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose **cũng** là một nguồn **kiểm toán** ngoại tuyến — bảng điều khiển đọc các phiên SQLite của nó tại `~/.local/share/goose/sessions/sessions.db` (mỗi hàng `sessions` mang một `working_dir` thực, vì vậy các phiên nhóm theo cwd dự án như Devin; các lần chạy `--no-session` scratch được lọc). +- **`policies-config.json`** — cho failproofai biết chính sách nào để đánh giá và với tham số nào (chia sẻ trên tất cả CLI agent) + +Truyền `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` để nhắm vào một agent cụ thể (cách nhau bằng dấu cách hoặc lặp lại cho bất kỳ tập con nào): ```bash failproofai policies --install --cli codex --scope project @@ -236,17 +235,35 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her Khi `--cli` bị bỏ qua, `failproofai` phát hiện CLI agent nào được cài đặt (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): - **Một CLI được phát hiện** — tự động chọn CLI đó mà không cần nhắc. -- **Nhiều CLI được phát hiện** trong một thiết bị đầu cuối tương tác — hiển thị lời nhắc lựa chọn đơn lẻ bằng phím mũi tên được nhóm thành phần `Detected (N)` (với hàng tổng hợp `Install for all N detected` + mỗi CLI được phát hiện riêng biệt) và phần `Not installed (M) · install hooks ahead of time` liệt kê mọi CLI hỗ trợ không được phát hiện dưới dạng tùy chọn cài đặt chuyển tiếp (↑↓ để di chuyển, Nhập để chọn, ^C để thoát). Luồng gỡ cài đặt chỉ hiển thị phần Detected. -- **Nhiều CLI được phát hiện** trong chạy không tương tác (CI, không TTY) — cài đặt cho tất cả CLI được phát hiện mà không cần nhắc. -- **Không có cái nào được phát hiện** — quay lại `claude`, với cảnh báo rằng không tìm thấy tệp nhị phân agent nào trong PATH; lệnh hook vẫn được ghi để nó kích hoạt ngay khi bạn cài đặt. +- **Nhiều CLI được phát hiện** trong một thiết bị đầu cuối tương tác — hiển thị lời nhắc chọn một mũi tên khóa được nhóm vào một phần `Detected (N)` (với hàng tổng hợp `Install for all N detected` + mỗi CLI được phát hiện riêng lẻ) và một phần `Not installed (M) · install hooks ahead of time` liệt kê mọi CLI được hỗ trợ không được phát hiện như một lựa chọn forward-install (↑↓ để di chuyển, Enter để chọn, ^C để thoát). Lưu lượng gỡ cài đặt chỉ hiển thị phần Detected. +- **Nhiều CLI được phát hiện** trong một lần chạy không tương tác (CI, không TTY) — cài đặt cho tất cả CLI được phát hiện mà không cần nhắc. +- **Không có nào được phát hiện** — quay lại `claude`, với cảnh báo rằng không tìm thấy nhị phân agent trong PATH; lệnh hook vẫn được ghi để nó kích hoạt ngay khi bạn cài đặt một. Bạn có thể chỉnh sửa `policies-config.json` trực tiếp bất kỳ lúc nào; các thay đổi có hiệu lực ngay lập tức trên sự kiện hook tiếp theo mà không cần khởi động lại. +## Nâng cấp giữ cấu hình của bạn + +Phiên bản mới của failproofai có thể tổ chức `~/.failproofai/` khác nhau. Khi nó làm, lệnh đầu tiên sau nâng cấp di chuyển thư mục, và **cấu hình của bạn được mang theo, không được đặt lại**: + +| Được giữ | Được xây dựng lại | +|---|---| +| Lựa chọn và tham số chính sách của bạn (`policies-config.json`) | Bộ nhớ đệm kiểm toán | +| Cài đặt của bạn, bao gồm `daemon.configured` và đường dẫn bắt buộc bổ sung (`config.json`) | Triển khai chính sách được quản lý đám mây — được lấy lại và xác minh tóm tắt trên cuộc thăm dò tiếp theo | +| Danh sách nhân viên đám mây của bạn (`credentials.json`) | Trạng thái scratch daemon | +| Các tệp chính sách riêng của bạn trong `policies/`, và các trợ giúp mà chúng nhập | | +| Nhật ký quyết định mà bảng điều khiển đọc, và các sự kiện chưa được gửi | | + +Các khóa được ghi bởi một **mới hơn** failproofai cũng được giữ lại, thay vì bị loại bỏ bởi trình đọc cũ hơn — vì vậy di chuyển giữa các phiên bản không yên lặng loại bỏ cài đặt ở cả hai hướng. + +Bạn **không** cần chạy lại cài đặt sau đó: một máy được di chuyển thực thi chính xác như trước đây, đây là điều làm cho nâng cấp an toàn trên máy không có ai ngồi ở đó. Mỗi di chuyển được ghi lại trong `~/.failproofai/migrations/applied.json`, và các tệp không thể thay thế được sao chép vào `~/.failproofai/migrations/backup-layout/` trước khi bất cứ điều gì chạy. + +Xem [`failproofai update`](/vi/cli/update) để nâng cấp một dòng, và [`failproofai migrate`](/vi/cli/migrate) — bao gồm `--dry-run` — để biết chi tiết. + --- -## Ví dụ: cấu hình cấp dự án với giá trị mặc định nhóm +## Ví dụ: cấu hình cấp dự án với mặc định nhóm -Cam kết `.failproofai/policies-config.json` vào kho của bạn: +Cam kết `.failproofai/policies-config.json` vào repo của bạn: ```json { @@ -265,4 +282,4 @@ Cam kết `.failproofai/policies-config.json` vào kho của bạn: } ``` -Mỗi nhà phát triển sau đó có thể tạo `.failproofai/policies-config.local.json` (gitignore) cho các ghi đè cá nhân mà không ảnh hưởng đến các đồng nghiệp. \ No newline at end of file +Mỗi nhà phát triển có thể sau đó tạo `.failproofai/policies-config.local.json` (gitignored) để ghi đè cá nhân mà không ảnh hưởng đến đồng đội. \ No newline at end of file diff --git a/docs/vi/custom-policies.mdx b/docs/vi/custom-policies.mdx index 30e9344d..ddcb6a91 100644 --- a/docs/vi/custom-policies.mdx +++ b/docs/vi/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: Chính sách tùy chỉnh -description: "Viết quy tắc của riêng bạn bằng JavaScript - thực thi các quy ước, ngăn chặn sự thay đổi, phát hiện lỗi, tích hợp với các hệ thống bên ngoài" +description: "Viết các quy tắc riêng của bạn bằng JavaScript - thực thi các 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 agent nào: thực thi các quy ước dự án, ngăn chặn sự thay đổi không mong muốn, kiểm soát các hoạt động phá hoại, phát hiện agent bị kẹt, hoặc tích hợp với Slack, quy trình phê duyệt, v.v. Chúng sử dụng cùng hệ thống sự kiện hook và các quyết định `allow`, `deny`, `instruct` như các chính sách được tích hợp sẵn. +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 agent nào: thực thi các quy ước dự án, ngăn chặn sự trôi dạt, kiểm soát các hoạt động phá hoại, phát hiện các agent bị kẹt, hoặc tích hợp với Slack, quy trình phê duyệt, v.v. Chúng sử dụng cùng một hệ thống sự kiện hook và các quyết định `allow`, `deny`, `instruct` như các chính sách tích hợp sẵn. --- @@ -39,28 +39,28 @@ 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 (khuyến nghị) +### 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ó chỉ hoạt động. +Đặt 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ờ hay thay đổi cấu hình. Cách này hoạt động như git hooks: đặt một tệp, nó sẽ hoạt động. ``` -# Cấp độ dự án — được commit vào git, chia sẻ với nhóm +# Mức dự án — được cam kết vào git, chia sẻ với đội .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 +# Mức cá nhân — tùy chỉnh, áp dụng cho tất cả các dự án ~/.failproofai/policies/my-policies.mjs ``` **Cách hoạt động:** -- Cả hai thư mục dự án và người dùng được quét (hợp lệnh — không phải phạm vi đầu tiên thắng) -- Các tệp được tải theo thứ tự bảng chữ cái trong mỗi thư mục. Đặt 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 trên mỗi tệp) -- Hoạt động cùng với các chính sách `--custom` rõ ràng và các chính sách được tích hợp sẵn +- Cả hai thư mục dự án và người dùng đều được quét (hợp nhất — không phải theo quy tắc phạm vi đầu tiên) +- Các tệp được tải theo thứ tự chữ cái trong mỗi thư mục. Thêm tiền tố `01-`, `02-` để kiểm soát thứ tự +- Chỉ các tệp khớp với `*policies.{js,mjs,ts}` mới được tải; các tệp khác bị bỏ qua +- Mỗi tệp được tải độc lập (mở rộng mỗi tệp) +- Hoạt động cùng với `--custom` rõ ràng và các chính sách tích hợp sẵn -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 giống nhau — không cần thiết lập cho từng nhà phát triển. Khi nhóm của bạn khám phá các chế độ lỗi mới, hãy thêm một chính sách và đẩy lên. Theo thời gian, những chính sách này trở thành một tiêu chuẩn chất lượng sống động không ngừng cải thiện với mỗi đóng góp. +Chính sách quy ước là cách dễ nhất để xây dựng tiêu chuẩn chất lượng cho tổ chức của bạn. Cam kết `.failproofai/policies/` vào git và mỗi thành viên trong nhóm sẽ tự động nhận được cùng các quy tắc — không cần thiết lập cho từng nhà phát triển. Khi đội 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à đẩy lên. Theo thời gian, những chính sách này trở thành tiêu chuẩn chất lượng sống động và tiếp tục cải thiện với mỗi đóng góp. ### Tùy chọn 2: Đường dẫn tệp rõ ràng @@ -69,33 +69,33 @@ Chính sách quy ước là cách dễ nhất để xây dựng một tiêu chu # Cài đặt với tệp chính sách tùy chỉnh failproofai policies --install --custom ./my-policies.js -# Thay thế đường dẫn chính sách tùy chỉnh +# Thay thế các đường dẫn chính sách tùy chỉnh failproofai policies --install --custom ./new-policies.js # Cấu hình nhiều tệp rõ ràng (được tải theo thứ tự cờ) failproofai policies --install --custom ./security.js --custom ./workflow.js -# Xóa tất cả đường dẫn chính sách tùy chỉnh rõ ràng khỏi cấu hình +# Xóa tất cả các đường dẫn chính sách tùy chỉnh rõ ràng khỏi cấu hình failproofai policies --uninstall --custom ``` -Các đường dẫn tuyệt đối được phân giải được lưu trữ trong `policies-config.json` dưới dạng `customPoliciesPaths`. Lặp lại `--custom` để cấu hình nhiều tệp. Các cấu hình hiện có sử dụng trường `customPoliciesPath` cũ tiếp tục hoạt động. Các tệp được tải mới trên mỗi sự kiện hook - không có bộ nhớ đệm giữa các sự kiện. +Các đường dẫn tuyệt đối được phân giải được lưu trữ trong `policies-config.json` dưới dạng `customPoliciesPaths`. Lặp lại `--custom` để cấu hình nhiều tệp. Các cấu hình hiện có sử dụng trường `customPoliciesPath` kế thừa tiếp tục hoạt động. Các tệp được tải mới trên mỗi sự kiện hook — không có bộ nhớ cache giữa các sự kiện. -Mỗi chính sách được đăng ký xuất hiện với bộ chuyển đổi riêng trong bảng điều khiển. Tắt chính sách sẽ ghi ID được xác định bằng nguồn của nó vào `disabledCustomPolicies`; tệp và các chính sách khác của nó tiếp tục được tải, trong khi chính sách bị tắt bị loại trừ trước khi khớp sự kiện. Tên chính sách trùng lặp trên các tệp có các bộ chuyển đổi độc lập. +Mỗi chính sách được đăng ký xuất hiện với bộ chuyển đổi riêng của nó trong bảng điều khiển. Tắt một chính sách sẽ ghi lại ID được xác định theo nguồn của nó trong `disabledCustomPolicies`; tệp và các chính sách khác của nó tiếp tục tải, trong khi chính sách bị tắt bị loại trừ trước khi khớp sự kiện. Tên chính sách trùng lặp trên các tệp có các bộ chuyển đổi độc lập. -### Sử dụng cả hai cùng nhau +### Sử dụng cả hai cách -Chính sách quy ước và các tệp `--custom` rõ ràng có thể coexist. Thứ tự tải: +Chính sách quy ước và các tệp `--custom` rõ ràng có thể cùng tồn tại. Thứ tự tải: 1. Các tệp `customPoliciesPaths` rõ ràng (theo thứ tự đượ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) +2. Các tệp quy ước dự án (`{cwd}/.failproofai/policies/`, theo thứ tự chữ cái) +3. Các tệp quy ước người dùng (`~/.failproofai/policies/`, theo thứ tự chữ cái) --- ## API -### Import +### Nhập ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -103,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Đăng ký một chính sách. Gọi điều này nhiều lần khi cần cho nhiều chính sách trong cùng một tệp. +Đăng ký một chính sách. Gọi điều này bao nhiêu lần cần thiết 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 + name: string; // bắt buộc - định danh duy nhất + description?: string; // hiển thị trong đầu ra `failproofai policies` + match?: { events?: HookEventType[] }; // lọc theo loại sự kiện; bỏ qua để khớp tất cả fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Trợ giúp quyết định +### Trình hỗ trợ quyết định -| Hàm | Hiệu ứng | Sử dụng khi | +| Hàm | Hiệu quả | 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 thông báo | +| `allow()` | Cho phép hoạt động im lặng | Hành động này an toàn, không cần thông báo | | `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 ngữ cảnh bổ sung để agent không mất hướng | +| `instruct(message)` | Thêm ngữ cảnh mà không chặn | Cung cấp ngữ cảnh bổ sung cho agent để duy trì theo dõi | -`deny(message)` - thông báo xuất hiện trước Claude với tiền tố `"Blocked by failproofai:"`. Một `deny` duy nhất sẽ ngắt tất cả các đánh giá tiếp theo. +`deny(message)` - thông báo xuất hiện cho Claude với tiền tố `"Blocked by failproofai:"`. Một lần `deny` duy nhất sẽ làm ngắn mạch tất cả việc đánh giá tiếp theo. `instruct(message)` - thông báo đượ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 thông báo `instruct` được tích lũy và gửi cùng nhau. -Bạn có thể thêm hướng dẫn bổ sung vào bất kỳ thông báo `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 cho các 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 như nhau. Xem [Cấu hình → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. +Bạn có thể thêm hướng dẫn bổ sung vào bất kỳ thông báo `deny` hay `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 cho các 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 chi tiết. -### Thông báo allow thông tin +### Thông báo cho phép thông tin -`allow(message)` cho phép hoạt động **và** gửi một thông báo thông tin trở lại Claude. Thông báo được gửi dưới dạng `additionalContext` trong phản hồi stdout của trình xử lý hook — cơ chế tương tự như `instruct`, nhưng có ý nghĩa khác: đó là một bản cập nhật trạng thái, không phải cảnh báo. +`allow(message)` cho phép hoạt động **và** gửi một thông báo thông tin quay lại Claude. Thông báo được gửi 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 theo nghĩa khác: đó là một cập nhật trạng thái, không phải là cảnh báo. -| Hàm | Hiệu ứng | Sử dụng khi | +| Hàm | Hiệu quả | Sử dụng khi | |----------|--------|----------| -| `allow(message)` | Cho phép và gửi ngữ cảnh tới Claude | Xác nhận một kiểm tra đã vượt qua, hoặc giải thích tại sao kiểm tra bị bỏ qua | +| `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 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ứ là xanh lá cây -- **Giải thích fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — cho Claude biết tại sao kiểm tra bị bỏ qua để nó có ngữ cảnh đầy đủ -- **Nhiều thông báo tích lũy:** nếu nhiều chính sách mỗi thông báo trả về `allow(message)`, tất cả thông báo được nối với dòng mới và gửi cùng nhau +- **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 mở rộng thất bại:** `allow("GitHub CLI not installed, skipping CI check.")` — cho Claude biết tại sao kiểm tra bị bỏ qua để nó có toàn bộ ngữ cảnh +- **Nhiều thông báo tích lũy:** nếu một số chính sách trả về `allow(message)`, tất cả các thông báo sẽ được nối với các dòng mới và gửi cùng nhau ```js customPolicies.add({ @@ -151,7 +151,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... check branch status ... + // ... kiểm tra trạng thái nhánh ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -167,7 +167,7 @@ customPolicies.add({ | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | Công cụ được gọi (ví dụ: `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Các tham số đầu vào của công cụ | -| `payload` | `Record` | Trọng tải sự kiện thô đầy đủ từ Claude Code | +| `payload` | `Record` | Toàn bộ tải trọng sự kiện thô từ Claude Code | | `session` | `SessionMetadata \| undefined` | Ngữ cảnh phiên (xem bên dưới) | ### Các trường `SessionMetadata` @@ -176,16 +176,16 @@ customPolicies.add({ |-------|------|-------------| | `sessionId` | `string` | Định danh phiên Claude Code | | `cwd` | `string` | Thư mục làm việc của phiên Claude Code | -| `transcriptPath` | `string` | Đường dẫn tệp bản ghi JSONL của phiên | +| `transcriptPath` | `string` | Đường dẫn tới tệp bản ghi JSONL của phiên | ### Các loại sự kiện -| Sự kiện | Khi nó xảy ra | Nội dung `toolInput` | +| Sự kiện | Khi nó kích hoạt | Nội dung `toolInput` | |-------|--------------|----------------------| | `PreToolUse` | Trước khi Claude chạy một 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` (đầu ra) | -| `Notification` | Khi Claude gửi một 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 | +| `PostToolUse` | Sau khi công cụ hoàn tất | Đầu vào của công cụ + `tool_result` (đầu ra) | +| `Notification` | Khi Claude gửi một thông báo | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hook 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 | Trống | --- @@ -193,20 +193,20 @@ customPolicies.add({ Chính sách được đánh giá theo thứ tự này: -1. Chính sách được tích hợp sẵn (theo thứ tự định nghĩa) +1. Chính sách tích hợp sẵn (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, `.add()` thứ tự 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, `.add()` thứ tự trong) +3. Chính sách quy ước từ `.failproofai/policies/` dự án (các tệp theo thứ tự chữ cái, thứ tự `.add()` bên trong) +4. Chính sách quy ước từ `~/.failproofai/policies/` người dùng (các tệp theo thứ tự chữ cái, thứ tự `.add()` bên trong) -Lệnh `deny` đầu tiên sẽ ngắt tất cả các chính sách tiếp theo. Tất cả các thông báo `instruct` được tích lũy và gửi cùng nhau. +Lần `deny` đầu tiên sẽ làm ngắn mạch tất cả các chính sách tiếp theo. Tất cả các thông báo `instruct` được tích lũy và gửi cùng nhau. --- ## Nhập bắc cầu -Các tệp chính sách tùy chỉnh có thể nhập các mô-đun cục bộ bằng đường dẫn tương đối: +Các tệp chính sách tùy chỉnh có thể nhập các mô-đun cục bộ bằng cách sử dụng các đường dẫn tương đối: ```js // my-policies.js @@ -223,21 +223,21 @@ customPolicies.add({ }); ``` -Tất cả các nhập tương đối có thể truy cập được từ tệp mục nhập được phân giải. Đ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 tính tương thích ESM. +Tất cả các nhập tương đối có thể truy cập từ tệp đầu vào được phân giải. Đ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 loại sự kiện -Sử dụng `match.events` để giới hạn khi nào chính sách được kích hoạt: +Sử dụng `match.events` để giới hạn khi 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 + // Chỉ kích hoạt khi phiên kết thúc + // ctx.session.transcriptPath chứa toàn bộ nhật ký phiên return allow(); }, }); @@ -249,20 +249,20 @@ 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ế độ lỗi -Chính sách tùy chỉnh là **fail-open**: các lỗi không bao giờ chặn các chính sách được tích hợp sẵn hoặc làm hỏng trình xử lý hook. +Chính sách tùy chỉnh **mở rộng thất bại**: lỗi không bao giờ chặn các chính sách tích hợp sẵn hay 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à các chính sách được tích hợp sẵn 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`; các chính sách được tích hợp sẵn tiếp tục | +| `customPoliciesPath` không được đặt | Không có chính sách tùy chỉnh rõ ràng nào chạy; chính sách quy ước và tích hợp sẵn 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 sẵn tiếp tục | | Lỗi cú pháp/nhập (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 cú pháp/nhập (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 ở runtime | Lỗi được ghi; hook đó được coi là `allow`; các hook khác tiếp tục | -| `fn` mất nhiề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 | +| `fn` ném lỗi khi chạy | Lỗi được ghi; hook đó được coi là `allow`; các hook khác tiếp tục | +| `fn` mất thời gian lâu hơn 10 giây | Hết thời gian được ghi; được coi là `allow` | +| Thư mục quy ước bị mất | Không có chính sách quy ước nào chạy; không có lỗi | -Để gỡ lỗi các lỗi chính sách tùy chỉnh, hãy xem tệp nhật ký: +Để 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 @@ -277,7 +277,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Prevent agent from writing to secrets/ directory +// Ngăn agent viết vào thư mục secrets/ customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -290,7 +290,7 @@ customPolicies.add({ }, }); -// Keep the agent on track: verify tests before committing +// Giữ agent trên theo dõi: xác minh các bài kiểm tra trước khi cam kết customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -305,7 +305,7 @@ customPolicies.add({ }, }); -// Prevent unplanned dependency changes during freeze +// Ngăn chặn những thay đổi phụ thuộc không có kế hoạch trong thời gian đóng băng customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -332,9 +332,9 @@ 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 đầu 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 bắc cầu, cuộc gọi async, loại bỏ đầu ra, và hooks 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/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 bắc cầu, lệnh gọi không đồng bộ, làm sạch đầ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 chặn viết lại lịch sử git) | | `examples/convention-policies/workflow-policies.mjs` | Chính sách quy trình làm việc dựa trên quy ước (nhắc nhở kiểm tra, tệp ghi kiểm tra) | ### Sử dụng các ví dụ tệp rõ ràng @@ -346,13 +346,13 @@ 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 +# Sao chép đến mức dự án mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# Or copy to user level +# Hoặc sao chép đến mức người dùng 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 tải tự động trên sự kiện hook tiếp theo. \ No newline at end of file +Không cần lệnh cài đặt — các tệp được chọn tự động trên sự kiện hook tiếp theo. \ No newline at end of file diff --git a/docs/vi/dashboard.mdx b/docs/vi/dashboard.mdx index 4e9f5525..22fe352c 100644 --- a/docs/vi/dashboard.mdx +++ b/docs/vi/dashboard.mdx @@ -1,10 +1,10 @@ --- title: Bảng điều khiển -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 tool và quản lý chính sách" +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 --- -Bảng điều khiển 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 AI agent và quản lý chính sách. Xem những gì các agent của bạn đã làm khi bạn không có mặt. +Bảng điều khiển 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 AI agent 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. --- @@ -16,7 +16,7 @@ failproofai Mở tại `http://localhost:8020`. -Bảng điều khiển đọc dữ liệu cấu hình dự án, phiên và failproofai cục bộ trực tiếp từ hệ thống tệp. Các tính năng xác thực tùy chọn, chẳng hạn như nhắc nhở kiểm toán và lời mời, gửi thông tin cần thiết cho các yêu cầu đó (bao gồm địa chỉ email) đến các API từ xa. +Bảng điều khiển đọc dữ liệu dự án, phiên làm việc và cấu hình failproofai cục bộ trực tiếp từ hệ thống tệp. Các tính năng được xác thực tùy chọn, chẳng hạn như nhắc nhở kiểm tra và lời mời, gửi thông tin cần thiết cho các yêu cầu đó (bao gồm địa chỉ email) đến các API từ xa. --- @@ -24,23 +24,23 @@ Bảng điều khiển đọc dữ liệu cấu hình dự án, phiên và failp ### Dự án -Liệt kê tất cả Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity và Goose projects được tìm thấy trên máy của bạn. Các dự án Claude được phát hiện từ `~/.claude/projects/` (hoặc đường dẫn được đặt bằng `CLAUDE_PROJECTS_PATH`); các dự án Codex được phát hiện bằng cách quét từng bản ghi tạm nhất dưới `~/.codex/sessions///
/*.jsonl` và nhóm theo `cwd` được ghi lại trong bản ghi đầu tiên của mỗi phiên; các dự án Copilot CLI được phát hiện bằng cách quét từng `~/.copilot/session-state//workspace.yaml` (có thể cấu hình thông qua `COPILOT_HOME`) và nhóm theo trường `cwd` của nó; các dự án Cursor Agent được phát hiện bằng cách quét siêu dữ liệu cho từng phiên dưới `~/.cursor/agent-sessions//` (có thể cấu hình thông qua `CURSOR_HOME`, với `conversations/` và `sessions/` được kiểm tra dự phòng) để tìm `cwd` vô hướng trong `meta.json` / `session.json` / `workspace.yaml`; các dự án OpenCode được phát hiện bằng cách truy vấn cơ sở dữ liệu SQLite của nó tại `~/.local/share/opencode/opencode.db` thông qua `opencode db --format json` (chúng tôi đọc các bảng `session` và `project` và nhóm theo `project_id`); các dự án Pi được phát hiện bằng cách quét các bản ghi tạm nhất JSONL cho từng phiên dưới `~/.pi/agent/sessions//_.jsonl` (có thể cấu hình thông qua `PI_SESSIONS_DIR`) và lấy `cwd` từ bản ghi đầu tiên của mỗi phiên; các phiên cổng Hermes được đọc trực tiếp từ kho lưu trữ SQLite của mỗi hồ sơ — `~/.hermes/state.db` cộng với `~/.hermes/profiles//state.db` (có thể ghi đè thông qua `HERMES_HOME` hoặc `HERMES_DB_PATH` cho một cơ sở dữ liệu duy nhất) — và được nhóm thành các dự án `hermes--` theo hồ sơ và `source` (Slack/Telegram/cli/cron — các phiên cổng không có cwd); các phiên cổng OpenClaw được đọc từ `~/.openclaw/agents//sessions/*.jsonl` và được nhóm thành các dự án `openclaw--` theo agent và kênh (cũng không có cwd); các dự án Factory Droid được phát hiện từ các bản ghi tạm nhất JSONL tại `~/.factory/sessions//*.jsonl` và được nhóm theo cwd; các dự án Devin từ cơ sở dữ liệu SQLite của nó tại `~/.local/share/devin/cli/sessions.db` (được nhóm theo `working_directory` của mỗi phiên); các dự án Antigravity từ các bản ghi tạm nhất JSONL tại `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` và được nhóm theo cwd; và các dự án Goose từ cơ sở dữ liệu SQLite của nó tại `~/.local/share/goose/sessions/sessions.db` (được nhóm theo `working_dir` của mỗi phiên). Một dự án đã được sử dụng bởi nhiều CLI sẽ hiển thị dưới dạng một hàng duy nhất với tất cả các badge phù hợp. Sử dụng dropdown **CLI** phía trên bảng để lọc theo một agent CLI cụ thể; URL sẽ lưu giữ lựa chọn của bạn dưới dạng `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Liệt kê tất cả các dự án Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity và Goose được tìm thấy trên máy của bạn. Các dự án Claude được phát hiện từ `~/.claude/projects/` (hoặc đường dẫn được đặt bởi `CLAUDE_PROJECTS_PATH`); các dự án Codex được phát hiện bằng cách quét mọi bảng ghi chép dưới `~/.codex/sessions///
/*.jsonl` và nhóm theo `cwd` được ghi lại trong bản ghi đầu tiên của mỗi phiên; các dự án Copilot CLI được phát hiện bằng cách quét mỗi `~/.copilot/session-state//workspace.yaml` (có thể cấu hình qua `COPILOT_HOME`) và nhóm theo trường `cwd` của nó; các dự án Cursor Agent được phát hiện bằng cách quét siêu dữ liệu theo phiên dưới `~/.cursor/agent-sessions//` (có thể cấu hình qua `CURSOR_HOME`, với `conversations/` và `sessions/` được dò tìm làm dự phòng) để tìm `cwd` vô hướng trong `meta.json` / `session.json` / `workspace.yaml`; các dự án OpenCode được phát hiện bằng cách truy vấn cơ sở dữ liệu SQLite của nó tại `~/.local/share/opencode/opencode.db` qua `opencode db --format json` (chúng tôi đọc các bảng `session` và `project` và nhóm theo `project_id`); các dự án Pi được phát hiện bằng cách quét các bảng ghi chép JSONL theo phiên dưới `~/.pi/agent/sessions//_.jsonl` (có thể cấu hình qua `PI_SESSIONS_DIR`) và kéo `cwd` từ bản ghi đầu tiên của mỗi phiên; các phiên cổng Hermes được đọc trực tiếp từ kho SQLite của mỗi hồ sơ — `~/.hermes/state.db` cộng `~/.hermes/profiles//state.db` (có thể ghi đè qua `HERMES_HOME`, hoặc `HERMES_DB_PATH` cho một cơ sở dữ liệu duy nhất) — và được nhóm thành các dự án `hermes--` theo hồ sơ và `source` (Slack/Telegram/cli/cron — các phiên cổng không có cwd); các phiên cổng OpenClaw được đọc từ `~/.openclaw/agents//sessions/*.jsonl` và được nhóm thành các dự án `openclaw--` theo agent và kênh (cũng không có cwd); các dự án Factory Droid được phát hiện từ các bảng ghi chép JSONL tại `~/.factory/sessions//*.jsonl` và được nhóm theo cwd; các dự án Devin từ cơ sở dữ liệu SQLite của nó tại `~/.local/share/devin/cli/sessions.db` (được nhóm theo `working_directory` của mỗi phiên); các dự án Antigravity từ các bảng ghi chép JSONL tại `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` và được nhóm theo cwd; và các dự án Goose từ cơ sở dữ liệu SQLite của nó tại `~/.local/share/goose/sessions/sessions.db` (được nhóm theo `working_dir` của mỗi phiên). Một dự án đã được sử dụng bởi nhiều CLI sẽ được hiển thị dưới dạng một hàng duy nhất với tất cả các huy hiệu phù hợp. Sử dụng dropdown **CLI** ở trên bảng để lọc theo một CLI agent cụ thể; URL lưu giữ lựa chọn của bạn dưới dạng `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. -Hermes và OpenClaw là phạm vi người dùng và không có thư mục làm việc để nhóm, vì vậy chúng hiển thị dưới dạng **cây thư mục có thể thu gọn** — hồ sơ (hoặc agent) ở cấp cao nhất, các kênh của nó bên dưới — trong khi mọi CLI dựa trên cwd vẫn là một hàng phẳng. Các hàng thư mục tính tổng số phiên và hoạt động gần đây nhất của mọi thứ bên dưới chúng, các thư mục bị thu gọn được ghi nhớ giữa các lần truy cập, và tìm kiếm từ khóa sẽ mở rộng bất cứ thứ gì nó phù hợp. +Hermes và OpenClaw nằm trong phạm vi người dùng và không có thư mục làm việc để nhóm theo, vì vậy chúng được hiển thị dưới dạng **cây thư mục có thể thu gọn** — hồ sơ (hoặc agent) ở mức đầu tiên, các kênh của nó bên dưới — trong khi mọi CLI dựa trên cwd vẫn là một hàng phẳng. Các hàng thư mục gộp số phiên và hoạt động gần đây nhất của mọi thứ dưới chúng, các thư mục được thu gọn được ghi nhớ giữa các lần truy cập, và tìm kiếm từ khóa mở rộng bất cứ thứ gì nó khớp. Mỗi dự án hiển thị: - Tên dự án (được lấy từ đường dẫn thư mục) -- Một badge CLI — `Claude Code` (cam), `OpenAI Codex` (tím), `GitHub Copilot` (xanh), `Cursor Agent` (xanh lục), `OpenCode` (hổphách), `Pi` (hồng), và/hoặc `Hermes` (chàm) +- Một huy hiệu CLI — `Claude Code` (cam), `OpenAI Codex` (tím), `GitHub Copilot` (xanh), `Cursor Agent` (ngọc lục bảo), `OpenCode` (hổphách), `Pi` (hồng), và/hoặc `Hermes` (chàm) - Ngày hoạt động phiên gần đây nhất -Nhấp vào dự án để xem các phiên của nó. +Nhấp vào một dự án để xem các phiên của nó. -### Các phiên +### Phiên làm việc -Liệt kê tất cả các phiên trong một dự án. Mỗi phiên hiển thị: +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 - Dấu thời gian bắt đầu và kết thúc -- Số lượng lệnh gọi tool +- Số lượng lệnh gọi công cụ - Số lượng hoạt động hook (chính sách đã kích hoạt) Sử dụng bộ lọc phạm vi ngày và tìm kiếm ID phiên để thu hẹp danh sách. Các phiên được phân trang. @@ -49,27 +49,27 @@ Nhấp vào một phiên để mở trình xem phiên. ### Trình xem phiên -Trình xem phiên trả lời câu hỏi chính cho các agent tự trị: agent đã làm gì, và liệu nó có duy trì hướng đúng không? Một badge CLI bên cạnh tiêu đề cho biết phiên là Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity hay Goose transcript. Nó hiển thị một dòng thời gian của mọi thứ đã xảy ra trong một phiên: +Trình xem phiên trả lời câu hỏi chính cho các agent tự chủ: agent đã làm gì và nó có tiếp tục đúng hướng không? Một huy hiệu CLI bên cạnh tiêu đề cho biết phiên là bản ghi Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity hay Goose. Nó hiển thị một dòng thời gian của mọi thứ đã xảy ra trong một phiên: -- **Tin nhắn** - Các phản hồi văn bản của Claude và lời nhắc của người dùng -- **Lệnh gọi tool** - Mọi tool mà Claude đã gọi, với đầu vào và đầu ra của nó -- **Hoạt động chính sách** - Với mỗi lệnh gọi tool, chính sách nào đã kích hoạt và quyết định nào họ trả lại +- **Tin nhắn** - Các phản hồi văn bản của Claude và lời nhắc từ người dùng +- **Lệnh gọi công cụ** - Mọi công cụ mà Claude đã gọi, với đầu vào và đầu ra của nó +- **Hoạt động chính sách** - Đối với mỗi lệnh gọi công cụ, các chính sách nào đã kích hoạt và quyết định nào mà chúng trả về -Thanh thống kê ở đầu trang hiển thị thời lượng phiên, tổng số lệnh gọi tool và một tóm tắt quyết định hook (số lượng allow / deny / instruct). +Thanh thống kê ở trên cùng hiển thị thời lượng phiên, tổng số lệnh gọi công cụ và tóm tắt các quyết định hook (số lượng allow / deny / instruct). -Nhấp vào nút **Download Logs** để xuất phiên. Đối với các phiên Claude Code, Codex, Copilot, Cursor và Pi, bạn sẽ nhận được bản ghi tạm nhất JSONL trên đĩa nguyên gốc theo từng byte; đối với OpenCode (các phiên của nó nằm trong SQLite, không phải trên đĩa), bạn sẽ nhận được một tài liệu JSON phản chiếu các bảng `session` / `messages` / `parts` cơ bản. +Nhấp vào nút **Download Logs** để xuất phiên. Đối với các phiên Claude Code, Codex, Copilot, Cursor và Pi, bạn sẽ nhận được bảng ghi chép JSONL trên đĩa nguyên bản theo từng byte; đối với OpenCode (các phiên của nó nằm trong SQLite, không phải trên đĩa), bạn sẽ nhận được một tài liệu JSON phản ánh các bảng `session` / `messages` / `parts` cơ bản. ### Kiểm toán -Một báo cáo được hướng dẫn bởi tính cách về cách agent của bạn thực sự đã hoạt động trong các phiên quá khứ. Chạy cùng một quét như CLI `failproofai audit` nhưng hiển thị nó dưới dạng một tấm áp phích có thể chia sẻ trên một màn hình + bốn phần phía dưới gấp: +Một báo cáo được điều khiển bởi tính cách về cách agent của bạn thực sự hành xử trong các phiên làm việc trước đó. Chạy quét giống như CLI `failproofai audit` nhưng hiển thị nó dưới dạng một áp phích có thể chia sẻ trên màn hình duy nhất + bốn phần bên dưới nếp gấp: -1. **Tấm áp phích** — điền vào viewport đầu tiên. Vùng tự chứa để chụp PNG với logo từ failproof_ai + nhãn kiểm toán · chỉ số kiểu mẫu (`№ NN of 08`) + ngày kiểm toán · điểm số (0–100) + viên xếp hạng phần trăm (`top 15%`) · tên kiểu mẫu (một trong `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + dải 3 từ khóa · dòng hiếm `// only N% of agents are this archetype` · ô ký tự 8×8 pixel · chân trang `audit yours → failproof.ai`. Ba nút chia sẻ nằm ngoài hộp chụp: `post your archetype` (X intent), `share on linkedin`, `download poster`. Chụp chạy qua `html-to-image` vì vậy PNG khớp với hiển thị trên màn hình pixel-for-pixel (đường viền chấm chấm, SVG logo mask, gradient, số liệu phông chữ — tất cả được bảo toàn). -2. **Điểm mạnh** — calming ✓ danh sách hàng các hành vi mà agent của bạn đã làm đúng, được lấy từ dữ liệu kiểm toán trực tiếp (tỷ lệ lệnh gọi tool sạch sẽ, không có đẩy trực tiếp đến main, không rò rỉ thông tin xác thực, không có trận bão thử lại) — mỗi cái chỉ được hiển thị khi chính sách liên quan có hồ sơ sạch sẽ trên toàn cửa sổ kiểm toán. -3. **Những điều lẻ** — bảng của những gì đã lọt qua, xếp hạng theo mức độ nghiêm trọng: `when · what slipped + the policy that would've caught it · severity pill · seen`, trong đó sự tái diễn đọc `new` (một lần), `N× seen` (2–9 lần), hoặc `recurring` (10+). -4. **Cách để cải thiện** — danh sách hàng tĩnh, một cho mỗi chính sách được quy định: tên chính sách bằng trắng, mô tả một dòng, lệnh cài đặt + nút sao chép ở bên phải. Tiêu đề phần đọc `enable all N → projected · ` (điểm số bạn sẽ đạt được với mọi bản sửa chữa được áp dụng), và nút `[install all]` của nó sao chép lệnh `failproofai policy add a b c …` kết hợp cho mỗi chính sách được quy định. -5. **Quay lại tốt hơn** — hai thẻ cạnh nhau. Bên trái: đặt nhắc nhở (`3d` / `7d` / `14d` / `30d` bộ chọn nhịp độ; tồn tại thông qua `/api/auth/reminder` khi xác thực). Bên phải: mở khóa các quyền lợi failproof — `invite a friend` mở một modal nhận một danh sách email bạn bè được phân tách bằng dấu phẩy/khoảng trắng/dòng mới (tối đa 10 trên mỗi lần gửi), POSTs chúng đến `/api/audit/invite`, được chuyển tiếp đến `POST /v0/invite` của máy chủ api. Máy chủ api gửi một email cho mỗi người nhận từ `invite@failproof.ai` với người gửi được Cc và `Reply-To` được đặt, vì vậy người nhận sẽ thấy ai đã mời họ và người gửi nhận được một bản sao trong hộp thư đến của họ. Người dùng ẩn danh được chuyển hướng qua `AuthDialog` trước tiên để email của người gửi được biết trước khi lời mời được gửi đi. Hoàn thành quyền lợi / quyền lợi là một công việc tiếp theo. +1. **Áp phích** — lấp đầy cửa sổ nhìn đầu tiên. Vùng thu thập PNG tự chứa với wordmark failproof_ai + nhãn kiểm toán · chỉ số nguyên mẫu (`№ NN of 08`) + ngày kiểm toán · điểm số (0–100) + viên xếp hạng phần trăm (`top 15%`) · tên nguyên mẫu (một trong `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + dải 3 từ khóa · dòng hiếm `// only N% of agents are this archetype` · ô sigil 8×8 pixel · footer `audit yours → failproof.ai`. Ba nút chia sẻ ngồi bên ngoài hộp thu thập: `post your archetype` (ý định X), `share on linkedin`, `download poster`. Capture chạy qua `html-to-image` để PNG khớp với render trên màn hình pixel-for-pixel (đường viền nét đứt, mặt nạ logo SVG, gradient, số liệu phông chữ — tất cả được bảo tồn). +2. **Điểm mạnh** — danh sách hàng ✓ bình tĩnh của các hành vi mà agent của bạn đã làm đúng, được lấy từ dữ liệu kiểm toán trực tiếp (tỷ lệ lệnh gọi công cụ sạch sẽ, không có các đẩy trực tiếp đến chính, không rò rỉ thông tin xác thực, không có bão thử lại) — mỗi cách được nêu ra chỉ khi chính sách liên quan có hồ sơ sạch sẽ trong cửa sổ kiểm toán. +3. **Những điều lập dị** — bảng những gì bị rò rỉ, xếp hạng theo mức độ nghiêm trọng: `when · what slipped + the policy that would've caught it · severity pill · seen`, nơi tần suất đọc `new` (một lần), `N× seen` (2–9 lần), hoặc `recurring` (10+). +4. **Cách cải thiện** — danh sách hàng bình tĩnh, mỗi chính sách được quy định: tên chính sách bằng màu trắng, mô tả một dòng, lệnh cài đặt + nút sao chép ở bên phải. Tiêu đề phần đọc `enable all N → projected · ` (điểm bạn sẽ đạt được với mọi bản sửa được áp dụng), và nút `[install all]` của nó sao chép lệnh `failproofai policy add a b c …` kết hợp cho mọi chính sách được quy định. +5. **Quay lại tốt hơn** — hai thẻ cạnh nhau. Trái: đặt nhắc nhở (`3d` / `7d` / `14d` / `30d` công cụ chọn tần suất; tồn tại thông qua `/api/auth/reminder` khi được xác thực). Phải: mở khóa các đặc quyền failproof — `invite a friend` mở một phương thức làm việc dành cho danh sách các email bạn được phân tách bằng dấu phẩy/khoảng trắng/ngắt dòng (tối đa 10 lần gửi), POST chúng đến `/api/audit/invite`, được chuyển tiếp đến `POST /v0/invite` của máy chủ api. Máy chủ api gửi một email cho mỗi người nhận từ `invite@failproof.ai` với người gửi được Cc và `Reply-To` được đặt, vì vậy người nhận thấy ai đã mời họ và người gửi nhận được bản sao trong hộp thư đến của họ. Người dùng ẩn danh được định tuyến thông qua `AuthDialog` trước tiên để email của người gửi được biết trước khi lời mời đi ra. Thỏa thuận quyền lợi / đặc quyền là một công việc tiếp theo. -Được điều khiển bởi quá trình chạy `failproofai audit` — xem [Audit CLI](/vi/cli/audit) để biết công cụ quét cơ bản, các cờ được hỗ trợ và bất biến bộ nhớ cache cho mỗi bản ghi. Bảng điều khiển lưu cache kết quả mới nhất tại `~/.failproofai/audit-dashboard.json` (chế độ `0600`, khe duy nhất, các bộ chạy mới ghi đè) vì vậy các lần truy cập lại là tức thì; **cả bộ nhớ cache cho mỗi bản ghi và toàn bộ kết quả đều bị từ chối khi đọc sau khi chúng cũ hơn 7 ngày** vì vậy bảng điều khiển không bao giờ im lặng cung cấp kết quả cách đây một tuần — quá TTL `/audit` rơi vào trạng thái trống của nó và nhắc nhở một lần chạy tươi. Nhấp vào `[ re-audit now ]` gần dưới cùng của báo cáo POSTs `/api/audit/run` với `noCache: true` — re-audit bỏ qua bộ nhớ cache cho mỗi bản ghi và quét lại mọi bản ghi từ đầu thay vì im lặng trả lại kết quả được lưu cache — và bảng điều khiển thăm dò `/api/audit/status` ở 1Hz cho đến khi lần chạy hoàn thành; một dải tiến trình hồng dính ghép đỉnh viewport trong lần chạy có bộ đếm thời gian trôi qua, và kết quả tươi tho hoán đổi tại chỗ khi thành công (không có tải lại trang đầy đủ; kiểm toán lại không thành công để lại báo cáo trước đó nguyên vẹn). Khi thất bại, dải quay sang màu đỏ với bản sao được tính khóa từ `RerunError.kind` (`timeout` / `network` / `post_failed`). Trạng thái trống (không có bộ nhớ cache hoặc hết hạn) và trạng thái không có phiên (bộ nhớ cache tồn tại nhưng quét không tìm thấy bản ghi nào) được hiển thị riêng biệt. +Được điều khiển bởi runtime `failproofai audit` — xem [Audit CLI](/vi/cli/audit) để biết công cụ quét cơ bản, các cờ được hỗ trợ và bất biến bộ nhớ đệm trên mỗi bảng ghi chép. Bảng điều khiển lưu trong bộ nhớ đệm kết quả mới nhất tại `~/.failproofai/audit-dashboard.json` (chế độ `0600`, khe duy nhất, các lần chạy mới ghi đè) vì vậy các lần truy cập lại là tức thời; **cả bộ nhớ đệm trên mỗi bảng ghi chép và toàn bộ kết quả đều bị từ chối khi đọc một khi chúng cũ hơn 7 ngày** vì vậy bảng điều khiển không bao giờ âm thầm phục vụ một kết quả cũ một tuần — quá TTL `/audit` rơi qua trạng thái trống và nhắc chạy lại. Nhấp vào `[ re-audit now ]` gần dưới cùng của báo cáo POST `/api/audit/run` với `noCache: true` — re-audit bỏ qua bộ nhớ đệm trên mỗi bảng ghi chép và quét lại mọi bảng ghi chép từ đầu thay vì âm thầm trả về kết quả được lưu trong bộ nhớ đệm — và bảng điều khiển thăm dò `/api/audit/status` ở 1Hz cho đến khi chạy hoàn tất; một dải tiến độ hồng dính ghim vào đầu cửa sổ nhìn trong quá trình chạy với bộ hẹn giờ đã trôi qua, và kết quả mới hoán đổi vào vị trí khi thành công (không tải lại toàn trang; re-audit không thành công để lại báo cáo trước đó không thay đổi). Khi thất bại, dải chuyển sang màu đỏ với bản sao được khóa từ `RerunError.kind` (`timeout` / `network` / `post_failed`). Trạng thái trống (không có bộ nhớ đệm hoặc hết hạn) và trạng thái không có phiên (bộ nhớ đệm tồn tại nhưng quét không tìm thấy bảng ghi chép) được nêu ra riêng biệt. ### Chính sách @@ -77,30 +77,30 @@ Một trang hai tab để quản lý chính sách và xem xét hoạt động. - - Chọn nhiều tùy chọn mà CLI agent nào failproofai bảo vệ từ một bảng duy nhất — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi và Hermes đều có một hàng với trạng thái cài đặt (`Active` / `Detected` / `Inactive`), đường dẫn cài đặt phạm vi người dùng và một acent màu thương hiệu. Chọn hoặc bỏ chọn các CLI mà bạn muốn và nhấp vào `Apply changes` để cài đặt/gỡ cài đặt sự khác biệt trong một bước. Các CLI có tệp nhị phân được phát hiện trên PATH sẽ được đánh dấu trước. - - Bật hoặc tắt các chính sách riêng lẻ bằng một cú nhấp duy nhất (ghi vào `~/.failproofai/policies-config.json` — chia sẻ trên mọi CLI được cài đặt) + - Chọn nhiều CLI nào failproofai bảo vệ từ một bảng điều khiển duy nhất — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi và Hermes đều có một hàng với trạng thái cài đặt (`Active` / `Detected` / `Inactive`), đường dẫn cài đặt phạm vi người dùng và nhấn mạnh được thêu bằng thương hiệu. Kiểm tra hoặc bỏ kiểm tra các CLI bạn muốn và nhấp vào `Apply changes` để cài đặt/gỡ cài đặt sự khác biệt trong một bước. Các CLI có tệp nhị phân được phát hiện trên PATH được kiểm tra trước. + - Bật hoặc tắt các chính sách riêng lẻ bằng một lần nhấp chuột (ghi vào `~/.failproofai/policies-config.json` — được chia sẻ trên mọi CLI được cài đặt) - 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`) - Đặt đường dẫn tệp chính sách tùy chỉnh - - Lịch sử trang đầy đủ của mỗi sự kiện hook đã kích hoạt trên tất cả các phiên + - Lịch sử được phân trang đầy đủ của mọi sự kiện hook đã kích hoạt trên tất cả các phiên - Lọc theo quyết định, loại sự kiện, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), tên chính sách hoặc ID phiên - - Mỗi hàng hiển thị: dấu thời gian, tên chính sách, quyết định, badge CLI (cam = Claude Code, tím = OpenAI Codex, xanh = GitHub Copilot, xanh lục = Cursor Agent, hổphách = OpenCode, hồng = Pi, chàm = Hermes, xanh mặt = OpenClaw, hồng nhạt = Factory Droid, tím = Devin, lục = Antigravity, vôi = Goose), tên tool, ID phiên và lý do cho các quyết định deny/instruct - - Nhấp vào ID phiên để mở bản ghi của nó — trình xem tự động phát hiện CLI nào kích hoạt hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) và hiển thị badge CLI phù hợp trong tiêu đề + - Mỗi hàng hiển thị: dấu thời gian, tên chính sách, quyết định, huy hiệu CLI (cam = Claude Code, tím = OpenAI Codex, xanh = GitHub Copilot, ngọc lục bảo = Cursor Agent, hổphách = OpenCode, hồng = Pi, chàm = Hermes, lục lam = OpenClaw, hồng đất = Factory Droid, tím = Devin, lục lam = Antigravity, xanh lá cây vôi = Goose), tên công cụ, ID phiên và lý do cho các quyết định deny/instruct + - Nhấp vào ID phiên để mở bản ghi chép của nó — trình xem tự động phát hiện CLI nào kích hoạt hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) và hiển thị huy hiệu CLI phù hợp trong tiêu đề --- -## Làm mới tự động +## Tự động làm tươi -Bảng điều khiển có một công tắc làm mới tự động trong thanh điều hướng trên cùng. Khi được bật, trang hiện tại làm mới định kỳ để hiển thị các phiên mới và hoạt động chính sách khi chúng xuất hiện. Cần thiết để giám sát các phiên agent tự trị chạy dài. +Bảng điều khiển có chuyển đổi tự động làm tươi trong điều hướng trên cùng. Khi được bật, trang hiện tại làm tươi định kỳ để hiển thị các phiên mới và hoạt động chính sách khi chúng xuất hiện. Cần thiết để giám sát các phiên agent tự chủ chạy lâu dài. --- -## Vô hiệu hóa các trang +## Tắt các trang -Nếu bạn chỉ cần một số phần của bảng điều khiển, hãy đặt `FAILPROOFAI_DISABLE_PAGES` thành một danh sách các tên trang được phân tách bằng dấu phẩy: +Nếu bạn chỉ cần một số phần của bảng điều khiển, hãy đặt `FAILPROOFAI_DISABLE_PAGES` thành danh sách các tên trang được phân tách bằng dấu phẩy: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -122,30 +122,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Truy cập từ máy chủ không phải localhost -Khi chạy bảng điều khiển ở **chế độ dev** (`npm run dev`) và truy cập nó từ tên máy chủ khác với `localhost` - ví dụ, một tên miền tùy chỉnh, một IP từ xa hoặc một URL được kết hợp - bạn có thể thấy một cảnh báo như: +Khi chạy bảng điều khiển ở **chế độ dev** (`npm run dev`) và truy cập nó từ tên máy chủ khác ngoài `localhost` - ví dụ: tên 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 truy cập xuyên nguồn gốc vào HMR (hot module reload) websocket của nó, là một tính năng chỉ dành cho dev. Để cho phép máy chủ của bạn, hãy sử dụng cờ `--allowed-origins`: +Đây là Next.js chặn truy cập từ nhiều nguồn vào websocket HMR (hot module reload) của nó, đây là một tính năng chỉ dành cho dev. Để 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 ``` -Đối với 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: +Đối với nhiều máy chủ hoặc IP, hãy truyền 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`: +Bạn cũng có thể đặt biến môi trường `FAILPROOFAI_ALLOWED_DEV_ORIGINS` thay thế: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Điều này chỉ áp dụng cho chế độ dev. Khi chạy `failproofai` (chế độ production), không có websocket HMR và không có vấn đề tài nguyên dev xuyên nguồn gốc. +Điều này chỉ áp dụng cho chế độ dev. Khi chạy `failproofai` (chế độ sản xuất), không có websocket HMR và không có vấn đề tài nguyên dev từ nhiều nguồn. \ No newline at end of file diff --git a/docs/vi/examples.mdx b/docs/vi/examples.mdx index 28cd0c2a..cd6cb1d1 100644 --- a/docs/vi/examples.mdx +++ b/docs/vi/examples.mdx @@ -5,13 +5,13 @@ description: "Cách thiết lập hooks cho Claude Code và Agents SDK" icon: book-open --- -Các ví dụ sẵn sàng sử dụng cho các tình huống phổ biến. Mỗi ví dụ cho thấy cách cài đặt và những gì bạn có thể mong đợi. +Các ví dụ sẵn sàng sử dụng cho các tình huống thường gặp. Mỗi ví dụ đều cho thấy cách cài đặt và những gì bạn có thể mong đợi. --- ## Thiết lập hooks cho Claude Code -Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) của nó. Khi bạn chạy `failproofai policies --install`, nó đăng ký các lệnh hook trong `settings.json` của Claude Code sẽ kích hoạt trên mỗi lệnh gọi công cụ. +Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) của nó. Khi bạn chạy `failproofai policies --install`, nó sẽ đăng ký các lệnh hook trong `settings.json` của Claude Code kích hoạt trên mỗi lần gọi công cụ. @@ -19,7 +19,7 @@ Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https npm install -g failproofai ``` - + ```bash failproofai policies --install ``` @@ -29,14 +29,14 @@ Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https cat ~/.claude/settings.json | grep failproofai ``` - Bạn sẽ thấy các mục hook cho các sự kiện `PreToolUse`, `PostToolUse`, `Notification`, và `Stop`. + Bạn sẽ thấy các mục hook cho các sự kiện `PreToolUse`, `PostToolUse`, `Notification` và `Stop`. ```bash claude ``` - Các chính sách giờ đây chạy tự động trên mỗi lệnh gọi công cụ. Hãy thử yêu cầu Claude chạy `sudo rm -rf /` - nó sẽ bị chặn. + Các chính sách giờ đây chạy tự động trên mỗi lần gọi công cụ. Hãy thử yêu cầu Claude chạy `sudo rm -rf /` - nó sẽ bị chặn. @@ -44,7 +44,7 @@ Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https ## Thiết lập hooks cho Agents SDK -Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), bạn có thể sử dụng cùng hệ thống hook theo chương trình. +Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), bạn có thể sử dụng cùng hệ thống hook theo lập trình. @@ -53,11 +53,11 @@ Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/d ``` - Truyền các lệnh hook khi tạo quy trình agent của bạn. Các hooks kích hoạt theo cách tương tự như trong Claude Code - thông qua JSON stdin/stdout: + Truyền các lệnh hook khi tạo quy trình agent của bạn. Các hooks kích hoạt theo cách giống như trong Claude Code - thông qua JSON stdin/stdout: ```bash - failproofai --hook PreToolUse # gọi trước mỗi công cụ - failproofai --hook PostToolUse # gọi sau mỗi công cụ + failproofai --hook PreToolUse # called before each tool + failproofai --hook PostToolUse # called after each tool ``` @@ -66,12 +66,12 @@ Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/d customPolicies.add({ name: "limit-to-project-dir", - description: "Giữ agent trong thư mục dự án", + description: "Keep the agent inside the project directory", match: { events: ["PreToolUse"] }, fn: async (ctx) => { const path = String(ctx.toolInput?.file_path ?? ""); if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) { - return deny("Agent bị giới hạn trong thư mục dự án"); + return deny("Agent is restricted to the project directory"); } return allow(); }, @@ -87,9 +87,9 @@ Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/d --- -## Chặn các lệnh phá hủy +## Chặn các lệnh tàn phá -Thiết lập phổ biến nhất - ngăn agents thực hiện các hành động không thể đảo ngược. +Thiết lập phổ biến nhất - ngăn agents thực hiện các hành động không thể hoàn tác. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -97,53 +97,53 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur Điều này làm gì: - `block-sudo` - chặn tất cả các lệnh `sudo` -- `block-rm-rf` - chặn xóa tệp đệ quy +- `block-rm-rf` - chặn xóa file đệ quy - `block-force-push` - chặn `git push --force` -- `block-curl-pipe-sh` - chặn piping các script từ xa tới shell +- `block-curl-pipe-sh` - chặn chuyển đường dẫn scripts từ xa đến shell --- ## Ngăn chặn rò rỉ bí mật -Ngăn agents nhìn thấy hoặc rò rỉ thông tin xác thực trong đầu ra công cụ. +Ngăn agents xem hoặc rò rỉ thông tin xác thực trong đầu ra công cụ. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Những chính sách này kích hoạt trên `PostToolUse` - sau khi một công cụ chạy, chúng sẽ xóa sạch đầu ra trước khi agent nhìn thấy nó. +Những chính sách này kích hoạt trên `PostToolUse` - sau khi một công cụ chạy, chúng làm sạch đầu ra trước khi agent nhìn thấy. --- -## Nhận thông báo Slack khi agents cần chú ý +## Nhận cảnh báo Slack khi agents cần chú ý -Sử dụng hook thông báo để chuyển tiếp các cảnh báo không hoạt động tới Slack. +Sử dụng notification hook để chuyển tiếp cảnh báo chờ đợi đến Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "slack-on-idle", - description: "Cảnh báo Slack khi agent đang chờ đầu vào", + description: "Alert Slack when the agent is waiting for input", match: { events: ["Notification"] }, fn: async (ctx) => { const webhookUrl = process.env.SLACK_WEBHOOK_URL; if (!webhookUrl) return allow(); - const message = String(ctx.payload?.message ?? "Agent đang chờ"); - const project = ctx.session?.cwd ?? "không xác định"; + const message = String(ctx.payload?.message ?? "Agent is waiting"); + const project = ctx.session?.cwd ?? "unknown"; try { await fetch(webhookUrl, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ - text: `*${message}*\nDự án: \`${project}\``, + text: `*${message}*\nProject: \`${project}\``, }), signal: AbortSignal.timeout(5000), }); } catch { - // không bao giờ chặn agent nếu Slack không thể tiếp cận + // never block the agent if Slack is unreachable } return allow(); @@ -161,20 +161,20 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## Giữ agents trên một nhánh -Ngăn agents chuyển đổi nhánh hoặc đẩy tới các nhánh được bảo vệ. +Ngăn agents chuyển đổi nhánh hoặc đẩy lên các nhánh được bảo vệ. ```javascript import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "stay-on-branch", - description: "Ngăn agent kiểm tra các nhánh khác", + description: "Prevent the agent from checking out other branches", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+checkout\s+(?!-b)/.test(cmd)) { - return deny("Ở lại trên nhánh hiện tại. Tạo một nhánh mới với -b nếu cần."); + return deny("Stay on the current branch. Create a new branch with -b if needed."); } return allow(); }, @@ -183,22 +183,22 @@ customPolicies.add({ --- -## Yêu cầu kiểm thử trước commit +## Yêu cầu kiểm tra trước khi commit -Nhắc nhở agents chạy kiểm thử trước khi commit. +Nhắc nhở agents chạy kiểm tra trước khi commit. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "test-before-commit", - description: "Nhắc nhở agent chạy kiểm thử trước khi commit", + description: "Remind the agent to run tests before committing", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+commit/.test(cmd)) { - return instruct("Chạy kiểm thử trước khi commit. Sử dụng `npm test` hoặc `bun test` trước tiên."); + return instruct("Run tests before committing. Use `npm test` or `bun test` first."); } return allow(); }, @@ -207,9 +207,9 @@ customPolicies.add({ --- -## Khóa một kho lưu trữ production +## Khóa chặt kho lưu trữ sản xuất -Commit một cấu hình cấp độ dự án để mọi nhà phát triển trong nhóm của bạn có được cùng các chính sách. +Commit một cấu hình cấp dự án để mỗi nhà phát triển trong đội của bạn nhận được các chính sách giống nhau. Tạo `.failproofai/policies-config.json` trong kho lưu trữ của bạn: @@ -236,19 +236,19 @@ Sau đó commit nó: ```bash git add .failproofai/policies-config.json -git commit -m "Thêm chính sách failproofai của nhóm" +git commit -m "Add failproofai team policies" ``` -Mọi thành viên trong nhóm có cài đặt failproofai sẽ tự động áp dụng các quy tắc này. +Mỗi thành viên trong đội có cài đặt failproofai sẽ tự động áp dụng những quy tắc này. --- -## Xây dựng tiêu chuẩn chất lượng toàn tổ chức bằng các chính sách quy ước +## Xây dựng một tiêu chuẩn chất lượng toàn công ty với các chính sách theo quy ước -Thiết lập có tác động nhất: commit `.failproofai/policies/` tới kho lưu trữ của bạn với các chính sách được điều chỉnh cho dự án của bạn. Mọi thành viên trong nhóm có được chúng tự động — không có lệnh cài đặt, không có thay đổi cấu hình. +Thiết lập có tác động nhất: commit `.failproofai/policies/` vào kho lưu trữ của bạn với các chính sách được điều chỉnh cho dự án của bạn. Mỗi thành viên trong đội sẽ nhận được chúng tự động — không cần lệnh cài đặt, không cần thay đổi cấu hình. - + ```bash mkdir -p .failproofai/policies ``` @@ -257,52 +257,52 @@ Thiết lập có tác động nhất: commit `.failproofai/policies/` tới kho // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Thực thi trình quản lý gói ưa thích của nhóm - // (hoặc bật chính sách prefer-package-manager tích hợp sẵn) + // Enforce your team's preferred package manager + // (or enable the built-in prefer-package-manager policy instead) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); - if (/\bnpm\b/.test(cmd)) return deny("Sử dụng bun thay vì npm."); + if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm."); return allow(); }, }); - // Nhắc nhở agent chạy kiểm thử trước khi commit + // Remind the agent to run tests before committing 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 kiểm thử trước khi commit."); + return instruct("Run tests before committing."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "Thêm chính sách chất lượng của nhóm" + git commit -m "Add team quality policies" ``` - Khi nhóm của bạn gặp phải các chế độ lỗi mới, hãy thêm chính sách và đẩy. Mọi người sẽ nhận được cập nhật trong lần `git pull` tiếp theo của họ. Các chính sách này trở thành một tiêu chuẩn chất lượng sống động phát triển cùng với nhóm của bạn. + Khi đội của bạn gặp phải các chế độ lỗi mới, hãy thêm các chính sách và đẩy lên. Mọi người đều nhận được bản cập nhật trên `git pull` tiếp theo của họ. Những chính sách này trở thành một tiêu chuẩn chất lượng sống động phát triển cùng với đội của bạn. --- -## Các ví dụ khác +## Thêm nhiều ví dụ Thư mục [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) trong kho lưu trữ chứa: -| Tệp | Nó hiển thị cái gì | -|------|---------------| -| `policies-basic.js` | Chính sách khởi đầu - chặn ghi production, force-push, piped scripts | -| `policies-notification.js` | Cảnh báo Slack cho các thông báo không hoạt động và kết thúc phiên | -| `policies-advanced/index.js` | Nhập dịch vụ, hooks async, xóa sạch đầu ra PostToolUse, xử lý sự kiện Stop | \ No newline at end of file +| Tệp | Nội dung | +|------|---------| +| `policies-basic.js` | Các chính sách khởi động - chặn ghi sản xuất, force-push, piped scripts | +| `policies-notification.js` | Cảnh báo Slack cho các thông báo chờ đợi và kết thúc phiên | +| `policies-advanced/index.js` | Nhập transitiv, async hooks, xóa đầu ra PostToolUse, xử lý sự kiện Stop | \ No newline at end of file diff --git a/docs/vi/for-agents.mdx b/docs/vi/for-agents.mdx index 6012a728..79390a4f 100644 --- a/docs/vi/for-agents.mdx +++ b/docs/vi/for-agents.mdx @@ -1,23 +1,22 @@ --- ---- -title: "For agents" -description: "Thêm kiến thức Failproof AI vào agent viết code của bạn chỉ bằng một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và nhiều hơn nữa." +title: "Cho các agent" +description: "Thêm tài liệu tham khảo Failproof AI vào agent code của bạn chỉ với một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và nhiều agent khác." --- -Thêm toàn bộ tài liệu tham khảo Failproof AI vào agent viết code của bạn chỉ bằng một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và bất kỳ agent nào khác hỗ trợ skills. +Thêm toàn bộ tài liệu tham khảo Failproof AI vào agent code của bạn chỉ với một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và bất kỳ agent nào khác hỗ trợ skills. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` phát hiện các agent bạn đã cài đặt và tự động thêm skill ở định dạng phù hợp cho từng agent. +`npx skills` tự động phát hiện những agent bạn đã cài đặt và thêm skill ở định dạng phù hợp cho từng agent. -## Skill bao gồm những gì +## Skill bao gồm nội dung gì | Lĩnh vực | Nội dung bao gồm | -|------|----------------| -| Policies | Tên policy được tích hợp sẵn, loại sự kiện, tham số, bật/tắt | -| Custom policies | `customPolicies.add()`, match filters, API `allow`/`deny`/`instruct` | +|---------|-----------------| +| Policies | Tên policy tích hợp, kiểu sự kiện, tham số, bật/tắt | +| Custom policies | `customPolicies.add()`, bộ lọc match, API `allow`/`deny`/`instruct` | | Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Configuration | Cấu trúc `policies-config.json`, scope merging, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes | @@ -26,9 +25,9 @@ npx skills add https://docs.befailproof.ai ## Skill có hoàn chỉnh không? -Mintlify tạo `llms.txt` từ tất cả các trang trong navigation. Tài liệu Failproof AI bao gồm toàn bộ API - mọi policy, tùy chọn và ví dụ đều có. Nếu bạn thấy thiếu điều gì, nguồn là tại `https://docs.befailproof.ai/llms-full.txt`. +Mintlify tạo `llms.txt` từ tất cả các trang trong navigation. Tài liệu Failproof AI bao gồm toàn bộ API - mọi policy, tùy chọn và ví dụ đều có. Nếu bạn thấy thiếu thứ gì, nguồn nằm tại `https://docs.befailproof.ai/llms-full.txt`. -Để có nội dung được lọc lại, hãy liên kết trực tiếp đến một trang cụ thể: +Để có nội dung cụ thể hơn, liên kết trực tiếp đến một trang cụ thể: ```bash # Chỉ API custom policies diff --git a/docs/vi/getting-started.mdx b/docs/vi/getting-started.mdx index a13664f2..ba097b2d 100644 --- a/docs/vi/getting-started.mdx +++ b/docs/vi/getting-started.mdx @@ -1,7 +1,7 @@ --- --- 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" +description: "Cài đặt failproofai, bật các chính sách, và để các agent của bạn hoạt động một cách đáng tin cậy" icon: rocket --- @@ -32,15 +32,15 @@ bun add -g failproofai - 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. + Chính sách là các quy tắc chạy trước và sau mỗi lần gọi công cụ của agent. Chúng bắt các lệnh phá hoại, rò rỉ bí mật, và các chế độ lỗi khác trước khi chúng gây ra 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. + Điều này ghi các mục hook vào các CLI agent được cài đặt của bạn (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` cộng với một mục đăng ký trong `~/.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 cái hiện diện, bạn sẽ được nhắc nhở; chuyển `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (bất kỳ tập con nào) để bỏ qua lời 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**. + Hỗ trợ GitHub Copilot CLI, Cursor Agent, OpenCode, và Pi ở chế độ **beta** — cài đặt bằng `--cli copilot`, `--cli cursor`, `--cli opencode`, hoặc `--cli pi`. Hermes (hermes-agent, một cổng Slack/Telegram) cài đặt phạm vi người dùng bằng `--cli hermes` và **cũng** là một nguồn kiểm toán ngoại tuyến. OpenClaw (cổng openclaw, một trợ lý đa kênh tự lưu trữ) cài đặt phạm vi người dùng bằng `--cli openclaw` — thực thi chạy qua các hook plugin trong quy trình của nó (`before_agent_finalize` là một cổng kết thúc lượt thực, vì vậy các built-in `require-*-before-stop` thực thi) — và **cũng** là một nguồn kiểm toán ngoại tuyến. Factory Droid (`droid`) cài đặt bằng `--cli factory` (phạm vi người dùng + dự án) và **cũng** là một nguồn kiểm toán ngoại tuyến. Devin CLI (`devin`, Cognition) cài đặt bằng `--cli devin` (phạm vi người dùng + dự án) và **cũng** là một nguồn kiểm toán ngoại tuyến. Antigravity CLI (`agy`) cài đặt bằng `--cli antigravity` (phạm vi người dùng + dự án) và **cũng** là một nguồn kiểm toán ngoại tuyến. Goose (tên mã goose, Block) cài đặt bằng `--cli goose` (phạm vi người dùng + dự án) — trình cài đặt chỉ đặt một thư mục plugin tại `~/.agents/plugins/failproofai/` mà Goose tự động phát hiện, và nó **cũng** là một nguồn kiểm toán ngoại tuyến. ```bash failproofai policies --install --scope project @@ -63,25 +63,25 @@ bun add -g failproofai 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. + Hiển thị mỗi chính sách, cho dù nó có được bật hay không, và bất kỳ tham số được cấu hình nào. ```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. + 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 qua các phiên, kiểm tra các lệnh gọi công cụ, và quản lý các chính sách. - 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. + Khởi động Claude Code như bình thường. Nếu agent cố gắng làm điều gì đó rủi ro, failproofai sẽ ngăn chặn nó tự động. Để nó chạy mà không được giám sát và xem xét những gì đã xảy ra trong bảng điều khiển. --- -## Cách thức hoạt động của các chính sách +## Cách các chính sách hoạt động -Mỗi lần một agent chạy một tool, Claude Code gọi failproofai như một subprocess: +Mỗi khi một agent chạy một công cụ, Claude Code gọi failproofai như một tiến trình con: ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -93,17 +93,17 @@ 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 +- **instruct** - ngữ cảnh bổ sung được thêm vào lời nhắc của agent -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. +Các chính sách chạy trong quy trình cục bộ của bạn. Không có gì được gửi đến dịch vụ từ xa. --- -## Thiết lập chính sách nhóm với chính sách dựa trên quy ước +## Thiết lập các chính sách nhóm với các 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. +Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên toàn bộ nhóm của bạn là quy ước `.failproofai/policies/`. Thả các tệp chính sách vào thư mục này và chúng được tải tự động — không có cờ, không có thay đổi cấu hình, không có lệnh cài đặt. @@ -111,14 +111,14 @@ Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên mkdir -p .failproofai/policies ``` - - Sao chép các ví dụ khởi động hoặc viết chính sách của riêng bạn: + + Sao chép các ví dụ khởi động hoặc viết 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: + Hoặc tạo một cái mới: ```js // .failproofai/policies/team-policies.mjs @@ -137,33 +137,35 @@ Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên }); ``` - + ```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. + Mỗi thành viên nhóm có cài đặt failproofai sẽ nhận các chính sách này tự động. Không cần thiết lập cho mỗi nhà phát triển. -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. +Cam kết `.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 các chế độ lỗi mới, thêm các chính sách và đẩy — mọi người 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 và không ngừng cải thiện. --- ## 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: +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ì | +| Đường dẫn | Nó lưu trữ cái 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/policies-config.json` | Cấu hình chính sách toàn cầu | +| `~/.failproofai/policies/` | Các chính sách của bạn — thả `*-policies.mjs`, không cần cấu hình | +| `~/.failproofai/policies/cloud-policies/` | Chính sách được triển khai cho máy này bởi tổ chức của bạn | +| `~/.failproofai/hook-activity/` | Lịch sử thực thi hook (JSONL được phân trang) | | `~/.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) | +| `.failproofai/policies-config.json` | Cấu hình cho mỗi dự án (được cam kết) | +| `.failproofai/policies-config.local.json` | Ghi đè cá nhân (được gitignore) | --- @@ -173,7 +175,7 @@ Tất cả cấu hình và nhật ký vẫn ở trên máy của bạn: 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. +Loại bỏ các mục hook từ `~/.claude/settings.json`. Các tệp cấu hình trong `~/.failproofai/` được giữ lại. --- @@ -182,7 +184,7 @@ Xóa hook entries từ `~/.claude/settings.json`. Các tệp cấu hình trong ` - Các scopes và định dạng tệp cấu hình + Phạm vi và định dạng tệp cấu hình @@ -190,11 +192,11 @@ Xóa hook entries từ `~/.claude/settings.json`. Các tệp cấu hình trong ` - Viết các chính sách của riêng bạn bằng JavaScript + Viết các chính sách riêng của bạn trong JavaScript - - Giám sát các phiên và xem lại hoạt động chính sách + + Theo dõi các phiên và xem xét hoạt động chính sách \ No newline at end of file diff --git a/docs/vi/introduction.mdx b/docs/vi/introduction.mdx index 66971796..2532eaf7 100644 --- a/docs/vi/introduction.mdx +++ b/docs/vi/introduction.mdx @@ -1,41 +1,41 @@ --- 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." +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ụ tàn phá và hơn thế nữa chỉ bằng 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**. +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 agent AI của bạn đáng tin cậy và chạy tự động 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. +Các agent AI thất bại theo những cách có thể dự đoán được. Chúng chạy các lệnh tàn phá, rò rỉ bí mật, lạc khỏi nhiệm vụ, mắc kẹt trong các vòng lặp, hoặc đẩy trực tiếp lên main. Nếu không được giám sát, những lỗi nhỏ có thể dẫn đến sự cố, 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 đó. +FailproofAI giải quyết vấn đề này bằng các **chính sách**. Những quy tắc này hook vào mọi lệnh gọi công cụ của agent để **phát hiện lỗi**, **giảm nhẹ chúng** (chặn, hướng dẫn, vệ sinh), 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 xét mọi lệnh gọi công cụ, lỗi agent và hành động phục hồi 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. +Các transcript 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 - 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. + Chặn các lệnh tàn phá, ngăn chặn rò rỉ bí mật, giữ các agent trong ranh giới dự án, và hơn thế nữa. Tất cả đều có sẵn. Viết các quy tắc của riêng bạn trong JavaScript với API allow / deny / instruct đơn giản. - - 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. + + Xem những gì các agent của bạn đã làm khi bạn vắng mặt. Duyệt các phiên, kiểm tra các lệnh gọi công cụ, xem xét nơi các chính sách được kích hoạt. - Đ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. + Tinh chỉnh bất kỳ chính sách nào mà không cần code. Đặ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ục. -## Bắt đầu nhanh chóng +## Khởi động nhanh @@ -50,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # enable policies (or skip — `failproofai` will offer to set them up on first run) -failproofai # launch the dashboard +failproofai policies --install # bật các chính sách (hoặc bỏ qua — `failproofai` sẽ đề nghị thiết lập chúng ở lần chạy đầu tiên) +failproofai # khởi chạy bảng điều khiển ``` Xem hướng dẫn [Bắt đầu](/vi/getting-started) để có hướng dẫn đầy đủ. \ No newline at end of file diff --git a/docs/vi/package-aliases.mdx b/docs/vi/package-aliases.mdx index 228b0e3c..9ec26530 100644 --- a/docs/vi/package-aliases.mdx +++ b/docs/vi/package-aliases.mdx @@ -1,83 +1,82 @@ --- ---- 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" +description: "Các bí danh chống lạm dụng tên miền đã được đă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`**: +Gói npm chính thức là **`failproofai`**: ```bash npm install -g failproofai -# hoặc +# or bun add -g failproofai ``` --- -## Tại sao chúng tôi sở hữu các bí danh +## Tại sao chúng tôi sở hữu các tên 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. +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ý một tên gói cách tên gói phổ biến chỉ một lần nhấn phím. Những người dùng không nghi ngờ lỡ nhập 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ế để bảo vệ. -Để 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ế. +Để loại bỏ rủi ro này, **chúng tôi chủ động sở hữu tất cả các lỗi đánh vần 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 đều là một proxy đơn giản để cài đặt và ủy quyền cho gói `failproofai` thực sự. --- -## Các bí danh đã đăng ký +## Các bí danh đã được đăng ký -**Biến thể định dạng** - những cách khác nhau để viết "failproof ai": +**Các 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 | +| `failproof-ai` | ⏳ Đang chờ hỗ trợ npm | +| `fail-proof-ai` | ⏳ Đang chờ hỗ trợ npm | +| `failproof_ai` | ⏳ Đang chờ hỗ trợ npm | +| `fail_proof_ai` | ⏳ Đang chờ hỗ trợ npm | +| `fail-proofai` | ⏳ Đang chờ hỗ trợ npm | -**Lỗi `failprof*`** - thiếu một `o` từ "proof": +**Các 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 | +| `failprofai` | ⏳ Đang chờ hỗ trợ npm | +| `fail-prof-ai` | ⏳ Đang chờ hỗ trợ npm | +| `failprof_ai` | ⏳ Đang chờ hỗ trợ npm | -**Lỗi `faliproof*`** - chữ `a` và `i` bị đảo lộn: +**Các lỗi `faliproof*`** - hoán đổi `a` và `i`: | Gói | Trạng thái | |---------|--------| | `faliproof` | ✅ Đã xuất bản | | `faliproof-ai` | ✅ Đã xuất bản | -| `faliproofai` | ⏳ Chờ hỗ trợ npm | +| `faliproofai` | ⏳ Đang 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. +> **Tại sao đang chờ?** Chính sách chống spam của npm chặn các tên bình thường 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ước các tên này cho mục đích chống squat. 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: +Bạn có thể xác minh rằng bất kỳ bí danh được xuất bản nào đều được sở hữu bởi chúng tôi: ```bash npm info failproof -# Tìm: "ExosphereHost Inc." trong trường maintainers +# Look for: "ExosphereHost Inc." in the maintainers field ``` --- -## Cách các bí danh hoạt động +## Cách hoạt động của các bí danh 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` +1. Liệt kê `failproofai` như một phụ thuộc - vì vậy gói thực sự đượ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ó riêng (ví dụ: `failprof-ai`) ủy quyền 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. +Proxy là một tập lệnh Node hai dòng; không có logic, không có lệnh gọi mạng và không có thu thập dữ liệu ngoài những gì `failproofai` tự thực hiện. --- -## Nếu bạn tìm thấy một tên chúng tôi đã bỏ lỡ +## Nếu bạn tìm thấy một tên mà 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ó. \ No newline at end of file diff --git a/docs/vi/testing.mdx b/docs/vi/testing.mdx index d417c104..b0998da2 100644 --- a/docs/vi/testing.mdx +++ b/docs/vi/testing.mdx @@ -1,27 +1,27 @@ --- --- title: Kiểm thử -description: "Kiểm thử đơn vị, kiểm thử end-to-end và trợ giúp kiểm thử" +description: "Unit tests, E2E tests, và các 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ế). +failproofai có hai bộ kiểm thử: **unit tests** (nhanh, mocked) và **end-to-end tests** (gọi subprocess thực). --- ## Chạy kiểm thử ```bash -# Chạy tất cả kiểm thử đơn vị một lần +# Chạy tất cả unit tests một lần bun run test:run -# Chạy kiểm thử đơn vị ở chế độ watch +# Chạy unit tests ở chế độ watch bun run test -# Chạy kiểm thử E2E (yêu cầu thiết lập - xem bên dưới) +# Chạy E2E tests (yêu cầu cấu hình - xem bên dưới) bun run test:e2e -# Kiểm tra loại mà không cần xây dựng +# Kiểm tra type mà không xây dựng bunx tsc --noEmit # Lint @@ -30,22 +30,22 @@ bun run lint --- -## Kiểm thử đơn vị +## Unit tests -Kiểm thử đơn vị nằm trong `__tests__/` và sử dụng [Vitest](https://vitest.dev) với `jsdom`. +Unit tests 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 + builtin-policies.test.ts # Logic policy cho từng builtin + hooks-config.test.ts # Tải config và gộp scope + policy-evaluator.test.ts # Param injection và thứ tự đánh giá + custom-hooks-registry.test.ts # globalThis registry add/get/clear + custom-hooks-loader.test.ts # ESM loader, transitive imports, xử lý lỗi + manager.test.ts # install/remove/list operations 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 + sessions-list.test.tsx # Session list component + project-list.test.tsx # Project list component ... lib/ logger.test.ts @@ -62,7 +62,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### Viết kiểm thử đơn vị chính sách +### Viết unit test cho policy ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -109,51 +109,51 @@ describe("block-sudo", () => { --- -## Kiểm thử end-to-end +## End-to-end tests -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. +E2E tests gọi binary `failproofai` thực như một subprocess, truyền payload JSON vào stdin, và khẳng định đầu ra stdout và exit code. Đ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 +### Cấu hình -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'`: +E2E tests chạy binary trực tiếp từ mã nguồn repo. Trước lần chạy đầu tiên, hãy xây dựng CJS bundle mà các custom hook files sử dụng khi import từ `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs ``` -Sau đó chạy kiểm thử: +Sau đó chạy các test: ```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`). +Xây dựng lại `dist/` bất cứ khi nào bạn thay đổi public hook API (`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 +### Cấu trúc E2E test ```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 + hook-runner.ts # Sinh binary, truyền payload JSON, nắm bắt exit code + stdout + stderr + fixture-env.ts # Per-test isolated temp directories với config files + payloads.ts # Claude-accurate payload factories cho từng event type 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 + builtin-policies.e2e.test.ts # Từng builtin policy với subprocess thực + custom-hooks.e2e.test.ts # Custom hook loading và evaluation + config-scopes.e2e.test.ts # Config merging trên project/local/global + policy-params.e2e.test.ts # Parameter injection cho từng parameterized policy ``` -### Sử dụng trợ giúp E2E +### Sử dụng E2E helpers -**`FixtureEnv`** - môi trường cách ly cho mỗi kiểm thử: +**`FixtureEnv`** - môi trường isolated per-test: ```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.cwd - temp dir; truyền như payload.cwd để nhặt .failproofai/policies-config.json +// env.home - isolated home dir; không có rò rỉ ~/.failproofai thực env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -163,9 +163,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` tự động đăng ký dọn dẹp `afterEach`. +`createFixtureEnv()` đăng ký `afterEach` cleanup tự động. -**`runHook`** - gọi nhị phân: +**`runHook`** - gọi binary: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -181,7 +181,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - nhà máy payload sẵn sàng: +**`Payloads`** - payload factories sẵn sàng: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -193,7 +193,7 @@ Payloads.notification(message, cwd) Payloads.stop(cwd) ``` -### Viết kiểm thử E2E +### Viết E2E test ```typescript import { describe, it, expect } from "vitest"; @@ -234,28 +234,28 @@ describe("block-rm-rf (E2E)", () => { ### Hình dạng phản hồi E2E -| Quyết định | Mã thoát | stdout | +| Quyết định | Exit code | 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 | +| Stop instruct | `2` | empty stdout; reason in stderr | +| Allow | `0` | empty string | -### Cấu hình Vitest +### Config Vitest -Kiểm thử E2E sử dụng `vitest.config.e2e.mts` với: +E2E tests 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) +- `environment: "node"` - không cần browser globals +- `pool: "forks"` - true process isolation (tests sinh subprocesses) +- `testTimeout: 20_000` - 20s per test (binary startup + hook eval) -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. +Pool `forks` rất quan trọng: thread-based workers chia sẻ `globalThis`, điều này có thể can thiệp vào subprocess-spawning tests. Process-based forks tránh đ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. +CI run đầy đủ (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) cần phải pass trước khi merge. E2E suite chạy như một CI job 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. \ No newline at end of file +Xem [Contributing](../CONTRIBUTING.md) để biết danh sách kiểm tra hoàn chỉnh trước merge. \ No newline at end of file diff --git a/docs/zh/agenteye/alerts.mdx b/docs/zh/agenteye/alerts.mdx index cdd3e3ad..d2843f07 100644 --- a/docs/zh/agenteye/alerts.mdx +++ b/docs/zh/agenteye/alerts.mdx @@ -1,63 +1,63 @@ --- title: "告警" -description: "在问题越过你的底线时立即获知，通过团队已在使用的渠道，而不是等到客户反映才知道。" +description: "在问题越界的第一时间得到通知，通知到达你的团队已在使用的渠道，而不是等到客户来反映。" --- -在问题越过你的底线时立即获知，通过团队已在使用的渠道，而不是等到客户反映才知道。规则只需设置一次，Failproof AI Observability 便会按计划检查，并通过邮件、Slack、webhook 或直接在仪表盘中通知你。 +在问题越界的第一时间得到通知，通知到达你的团队已在使用的渠道，而不是等到客户来反映。只需配置一次规则，Failproof AI Observability 会按计划自动检查，并通过邮件、Slack、Webhook 或仪表板内通知来提醒你。 -![告警页面：告警规则卡片网格，每张卡片显示触发条件、评估窗口、通知渠道，以及信息、警告或严重等级标识](/agenteye/images/alerts.png) -*一览所有告警规则：监控内容、检查频率、通知渠道及紧急程度。* +![告警页面：一组告警规则卡片，每张卡片显示触发条件、评估窗口、通知渠道以及信息、警告或严重级别徽章](/agenteye/images/alerts.png) +*一览所有告警规则：监控内容、检查频率、通知去向以及紧急程度。* -## 在用户发现之前，先行了解问题 +## 在用户发现问题之前先知道 -不必盯着仪表盘刷新，祈祷能碰巧发现问题。只要是你希望在无人值守时也能及时收到通知的信号，就配置一条告警，让通知落到你本来就在用的地方： +不要再盯着仪表板刷新等待问题出现了。只要有你在无人监控时也想及时了解的信号，就设置一个告警，让它推送到你日常使用的地方： -- **邮件**，发给需要知道的人。 -- **Slack**，附带直接跳转到事件的按钮的富文本消息。 -- **Webhook**，向 PagerDuty、Opsgenie 或你自己的端点发送 JSON POST，支持可选签名以便接收方验证来源。 -- **仪表盘内通知**，默认静默，适合在调试规则、暂时不想通知任何人时使用。 +- **邮件**，发送给所有应该知晓的人。 +- **Slack**，一条富文本消息，附带可直接跳转到事件详情的按钮。 +- **Webhook**，向 PagerDuty、Opsgenie 或你自己的端点发送 JSON POST 请求，支持可选签名以便接收方验证来源。 +- **仪表板内通知**，默认静默，适合在调试规则时不想打扰任何人的场景。 -一条规则可以同时绑定多个通知渠道，严重等级（信息、警告或严重）会一并传递，确保紧急告警一眼就能看出来。 +一条规则可同时附加上述任意组合，且严重级别（信息、警告或严重）会随通知一并携带，让紧急事项一眼可辨。 -## 用表单配置规则，而非 JSON +## 用表单配置规则，而非直接编写 JSON -你只需在表单中描述什么叫"出了问题"，Failproof AI Observability 会自动生成底层规则。JSON 格式不过是表单背后生成的产物，你可以通过读它来理解规则，但几乎不需要手写。 +你在表单中描述"异常"的含义，Failproof AI Observability 会自动为你生成底层规则。JSON 规范只是表单在底层产出的结果，你可以阅读它来理解规则，但很少需要手动编写。 -![新建告警表单：名称与描述、启用开关，以及包含指标阈值、自定义 SQL、评估分数、复合评估、单事件条件的触发器选项](/agenteye/images/alert-new.png) -*选择触发器后，表单会自动切换为对应字段；点击保存即写入规则。* +![新建告警表单：名称与描述、启用开关，以及触发类型选择器，提供指标阈值、自定义 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、特定错误类型，或特定消息子字符串 | +| **指标阈值** | 预设指标（错误率、p95 或 p99 延迟、事件或错误计数、Token 用量）在某时间窗口内超过设定值 | +| **自定义 SQL** | 你的只读查询返回了某行结果，或其计算值超过了阈值 | +| **评估分数** | 某评估器的平均分（如幻觉率）超过了阈值 | +| **复合评估** | 多项分数检查通过 any、all 或至少 N 项的逻辑组合，用于捕捉仅在多项分数综合表现下才显现的回归 | +| **逐事件** | 单个匹配事件发生时触发：特定 Agent、特定错误类型或消息中包含特定子字符串 | -已经在[错误页面](/zh/agenteye/error-tracking)盯着某个故障看了？每一行都有一个 **+ alert** 按钮，点击即可打开预填好的表单，专门用于捕获该故障的再次发生——你刚刚排查过的事件，下次出现时就会主动通知你。 +正在[错误页面](/zh/agenteye/error-tracking)查看某个故障？每一行都有一个 **+ 告警**按钮，点击后将打开同一个表单，并预填好用于捕捉该故障再次发生的信息，让你刚刚处理过的事件成为下次自动通知你的规则。 -**在哪里找到它：** 告警位于 `//alerts`。创建、编辑、删除和测试规则需要 **`alerts:write`** 权限；仅查看只需 `alerts:read`。接收人选择器会按姓名列出你组织的成员，无需离开表单即可指定通知对象。 +**访问路径：** 告警位于 `//alerts`。创建、编辑、删除和测试规则需要 **`alerts:write`** 权限；仅查看则只需 `alerts:read`。收件人选择器会按姓名列出组织成员，无需离开表单即可指定通知对象。 -## 只在真正需要时通知我 +## 只在真正出问题时才打扰我 -一次偶发的异常测量不应该把你叫醒。**M of N** 降噪过滤器控制在最近几次检查中，需要有多少次失败才会真正触发告警通知。设为 **3 of 5** 后，只有在最近五次检查中至少有三次超标才会触发告警，从而避免抖动信号频繁误报；保留默认值 **1 of 1** 则在首次超标时立即触发。你还可以选择规则的执行频率，预设选项包括 1 分钟、5 分钟、15 分钟和 1 小时，根据信号的实际变化速度灵活选择。 +单次异常测量不应触发告警。**M of N** 降噪过滤器控制最近几次检查中必须有多少次失败才真正触发通知。设置为 **3 of 5**，规则将在最近五次检查中有三次超出阈值后才触发，避免抖动信号频繁误报；保持默认的 **1 of 1** 则在首次超出时立即触发。你还可以选择规则的运行频率，提供 1m、5m、15m 和 1h 等预设值，以匹配信号实际变化的速度。 ## 告警触发后会发生什么 -一旦触发，系统会创建一个**事件**并通知你的渠道一次。之后由团队确认、分配负责人、跟进处理并最终解决——全程有清晰归属的记录可查。这套分诊流程有专属页面，详见[事件管理](/zh/agenteye/incidents)。 +一次违规将开启一个**事件（Incident）**，并向你的通知渠道发送一次通知。此后，你的团队可以确认事件、分配负责人、进行讨论并最终解决，全程都有清晰且可归因的记录。该分诊工作流有专属页面：请参阅[事件](/zh/agenteye/incidents)。 ## 相关内容 -- [事件管理](/zh/agenteye/incidents)：追踪告警从触发到确认再到解决的全过程。 -- [错误追踪](/zh/agenteye/error-tracking)：对 Agent 故障进行分组，一键将其转化为告警规则。 -- [仪表盘](/zh/agenteye/dashboards)：查看共享看板，告警所依据的阈值均来源于此。 -- [CLI 与 Agents](/zh/agenteye/cli-and-agents)：从终端创建告警、确认事件，或将其脚本化集成到 CI 中。 \ No newline at end of file +- [事件](/zh/agenteye/incidents)：从开启到确认再到解决，全程跟踪告警触发后的处理流程。 +- [错误追踪](/zh/agenteye/error-tracking)：对 Agent 故障进行分组，一键将其升级为告警规则。 +- [仪表板](/zh/agenteye/dashboards)：查看告警阈值所来源的共享看板。 +- [CLI 与 Agents](/zh/agenteye/cli-and-agents)：在终端中创建告警、确认事件，或将其集成到 CI 流程中。 \ No newline at end of file diff --git a/docs/zh/agenteye/api-keys.mdx b/docs/zh/agenteye/api-keys.mdx index 05e82748..aba95945 100644 --- a/docs/zh/agenteye/api-keys.mdx +++ b/docs/zh/agenteye/api-keys.mdx @@ -1,57 +1,57 @@ --- title: "API 密钥" -description: "API 密钥控制谁以及什么可以访问您的 Failproof AI Observability 服务器，使采集器可以发送事件而无需获得读取或管理员权限。" +description: "API 密钥控制谁以及什么可以访问您的 Failproof AI 可观测性服务器，使采集器能够在不获得读取或管理员权限的情况下发送事件。" --- -API 密钥控制谁以及什么可以访问您的 Failproof AI Observability 服务器，使采集器可以发送事件而无需获得读取或管理员权限。每个密钥携带一个或多个权限，每个权限控制特定的服务器路由；您只需授予某项工作所需的少量权限。大多数部署只需创建三种类型的密钥。 +API 密钥控制谁以及什么可以访问您的 Failproof AI 可观测性服务器，使采集器能够在不获得读取或管理员权限的情况下发送事件。每个密钥携带一个或多个权限，每个权限控制特定的服务器路由；您只需授予某个任务所需的最少权限。大多数部署只需创建三类密钥。 -## 大多数部署所需的 3 种密钥 +## 大多数部署所需的 3 类密钥 | 密钥 | 权限 | 使用者 | |---|---|---| | 采集器密钥 | `events:add` | 每台 Agent 机器上的 `agenteye-collector`，用于发送事件。 | -| 仪表板读取密钥 | `events:read`、`keys:read` | 查询数据但不修改数据的只读操作员或集成。 | -| 引导管理员密钥 | 所有权限 | 首次启动实例（及仪表板）的操作员。由 `ADMIN_KEY` 环境变量初始化。参见[引导管理员密钥](#bootstrap-admin-key)。 | +| 仪表盘只读密钥 | `events:read`、`keys:read` | 只读操作员或集成，用于查询数据而不修改数据。 | +| 引导管理员密钥 | 所有权限 | 首次启动实例（及仪表盘）的操作员。从 `ADMIN_KEY` 环境变量中初始化。参见[引导管理员密钥](#bootstrap-admin-key)。 | -从这里开始。仅在需要更窄的自定义作用域密钥时，才参考下方的完整权限目录。另请参阅[推荐密钥布局](#recommended-key-layout)和[创建密钥](#creating-keys)。 +从这里开始。只有在需要更精细的自定义作用域密钥时，才参考下方完整的权限目录。另请参见[推荐密钥布局](#recommended-key-layout)和[创建密钥](#creating-keys)。 --- ## 权限 -服务器执行固定的权限目录；每个权限控制特定的 HTTP 路由。**管理员密钥**拥有所有权限；作用域密钥只拥有您在创建时授予的子集。创建密钥时，未知的权限字符串将被拒绝。 +服务器执行一套固定的权限目录；每个权限控制特定的 HTTP 路由。**管理员密钥**拥有全部权限；作用域密钥仅拥有您在创建时授予的子集。创建密钥时，未知的权限字符串将被拒绝。 -> **注意：** 有两个有效权限仅供人工/仪表板使用，不能授予 API 密钥：`orgs:admin`（实例管理，仅限操作员）和 `keys:update`。尝试授予其中任一权限的 `POST /keys` 或 `PATCH /keys/:id` 请求将被拒绝并返回 HTTP 422。请参阅下方 `keys:update` 行，了解为何持有者密钥可以创建密钥但永远无法编辑密钥。 +> **注意：** 有两个有效权限仅限人工/仪表盘使用，不能授予 API 密钥：`orgs:admin`（实例管理，仅限操作员）和 `keys:update`。向 `POST /keys` 或 `PATCH /keys/:id` 发出的请求如果尝试授予其中任何一个，将被拒绝并返回 HTTP 422。请参阅下方 `keys:update` 行，了解为什么 Bearer 密钥可以创建密钥但不能编辑密钥。 ### 事件摄取与查询 | 权限 | HTTP 路由 | 允许的操作 | |---|---|---| -| `events:add` | `POST /events` | 从采集器摄取批量事件。这是采集器唯一需要的权限。 | -| `events:read` | `GET /events`、`GET /events/latency_aggregate`、`GET /events/environments`、`GET /events/models`、`GET /sessions/:session_id/export` | 查询事件、列出已知环境、列出数据中出现的模型标识符（供模型视图和模型过滤器使用）、计算为热图/百分位带提供支持的延迟聚合，以及将会话导出为 JSONL。共享筛选栏分面端点 `GET /events/environments` 和 `GET /events/agent_ids` 可通过 `events:read` **或** `evaluations:read` 任一权限访问，因此会话页面（受 `evaluations:read` 控制）可复用相同的按组织分面。`GET /events/models` 不在其中：它需要 `events:read`，因此仅持有 `evaluations:read` 的主体访问时将收到 403。 | +| `events:add` | `POST /events` | 从采集器摄取批量事件。这是采集器所需的唯一权限。 | +| `events:read` | `GET /events`、`GET /events/latency_aggregate`、`GET /events/environments`、`GET /events/models`、`GET /sessions/:session_id/export` | 查询事件、列出已知环境、列出数据中出现的模型标识符（供模型视图和模型过滤器使用）、计算热力图/百分位带所使用的延迟聚合，以及将会话导出为 JSONL。共享的筛选栏分面端点 `GET /events/environments` 和 `GET /events/agent_ids` 可通过 **`events:read`** **或** `evaluations:read` 访问，因此会话页面（受 `evaluations:read` 控制）可复用同一个按组织划分的分面。`GET /events/models` 不在其中：它需要 `events:read`，因此仅持有 `evaluations:read` 的主体将从该端点收到 403。 | ### 会话与评估 | 权限 | HTTP 路由 | 允许的操作 | |---|---|---| -| `evaluations:read` | `GET /sessions`、`GET /evaluations`、`GET /evaluations/aggregate`、`GET /evaluations/environments`、`GET /evaluation-jobs` | 列出会话、读取评估结果、仪表板使用的汇总评估健康状况，以及评估任务工作队列状态。 | +| `evaluations:read` | `GET /sessions`、`GET /evaluations`、`GET /evaluations/aggregate`、`GET /evaluations/environments`、`GET /evaluation-jobs` | 列出会话、读取评估结果、仪表盘使用的汇总评估健康状态，以及评估任务工作队列状态。 | | `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | 手动为已完成的会话排队重新评估。 | -### 仪表板 +### 仪表盘 | 权限 | HTTP 路由 | 允许的操作 | |---|---|---| -| `dashboards:read` | `GET /dashboards`、`GET /dashboards/:id`、`GET /dashboards/:id/tiles` | 列出仪表板、加载某个仪表板并读取其磁贴。 | -| `dashboards:write` | `POST /dashboards`、`PUT /dashboards/:id`、`POST /dashboards/:id/tiles`、`PUT /dashboards/:id/tiles/:tile_id`、`DELETE /dashboards/:id/tiles/:tile_id`、`PUT /dashboards/:id/tiles/layout` | 创建和编辑仪表板、添加/编辑/删除磁贴，以及重新排列磁贴网格。 | -| `dashboards:delete` | `DELETE /dashboards/:id` | 删除整个仪表板（磁贴级别的删除属于 `dashboards:write`）。 | +| `dashboards:read` | `GET /dashboards`、`GET /dashboards/:id`、`GET /dashboards/:id/tiles` | 列出仪表盘、加载单个仪表盘，以及读取其图块。 | +| `dashboards:write` | `POST /dashboards`、`PUT /dashboards/:id`、`POST /dashboards/:id/tiles`、`PUT /dashboards/:id/tiles/:tile_id`、`DELETE /dashboards/:id/tiles/:tile_id`、`PUT /dashboards/:id/tiles/layout` | 创建和编辑仪表盘、添加/编辑/删除图块，以及重新排列图块网格。 | +| `dashboards:delete` | `DELETE /dashboards/:id` | 删除整个仪表盘（图块级别的删除属于 `dashboards:write`）。 | ### 已保存查询（SQL 编辑器） | 权限 | HTTP 路由 | 允许的操作 | |---|---|---| -| `queries:read` | `GET /queries`、`GET /queries/:id`、`GET /queries/schema` | 列出已保存的查询、加载某个查询，并检查编辑器所针对的只读架构。 | -| `queries:write` | `POST /queries`、`PUT /queries/:id` | 创建和编辑已保存的查询。SQL 仍然通过与 `queries:run` 调用相同的只读角色和受保护的 SQL 检查进行路由。 | +| `queries:read` | `GET /queries`、`GET /queries/:id`、`GET /queries/schema` | 列出已保存的查询、加载单个查询，以及查看编辑器所针对的只读模式。 | +| `queries:write` | `POST /queries`、`PUT /queries/:id` | 创建和编辑已保存的查询。SQL 仍通过与 `queries:run` 调用相同的只读角色和受保护的 SQL 检查路由。 | | `queries:delete` | `DELETE /queries/:id` | 删除已保存的查询。 | | `queries:run` | `POST /queries/run` | 针对编辑器使用的只读角色执行已保存或临时 SQL。 | @@ -59,39 +59,39 @@ API 密钥控制谁以及什么可以访问您的 Failproof AI Observability 服 | 权限 | HTTP 路由 | 允许的操作 | |---|---|---| -| `agent:use` | `GET /agent/conversations`、`POST /agent/conversations`、`GET /agent/conversations/:id`、`PATCH /agent/conversations/:id`、`DELETE /agent/conversations/:id`、`PUT /agent/conversations/:id/messages` | 与 AI 助手对话并管理您自己的（私人）会话。在**用户**上需要此权限才能看到助手面板；助手自身的密钥为 `dashboard-assistant`，单独初始化（见下文）。 | +| `agent:use` | `GET /agent/conversations`、`POST /agent/conversations`、`GET /agent/conversations/:id`、`PATCH /agent/conversations/:id`、`DELETE /agent/conversations/:id`、`PUT /agent/conversations/:id/messages` | 与 AI 助手对话并管理您自己的（私有）对话。需要在**用户**上设置此权限才能看到助手面板；助手自身的密钥为 `dashboard-assistant`，由系统单独初始化（见下文）。 | ### API 密钥 | 权限 | HTTP 路由 | 允许的操作 | |---|---|---| | `keys:create` | `POST /keys` | 创建新的作用域 API 密钥。**不**授予编辑现有密钥权限的能力（那是 `keys:update`）。 | -| `keys:read` | `GET /keys` | 列出现有密钥。此端点永远不会返回密钥密文。 | -| `keys:update` | `PATCH /keys/:id` | 编辑现有密钥的权限。这是一个**仅供人工/仪表板使用**的权限；不能分配给 API 密钥（持有者密钥可以创建密钥，但永远无法编辑密钥）。 | -| `keys:disable` | `POST /keys/:id/disable` | 吊销密钥。受保护的密钥（`admin`、`dashboard-assistant`）无法被禁用；请通过更改环境变量并重启来轮换它们。 | -| `keys:regenerate` | `POST /keys/:id/regenerate` | 轮换密钥的密文。受保护的密钥无法通过此路由重新生成。 | +| `keys:read` | `GET /keys` | 列出现有密钥。此端点不返回密钥机密。 | +| `keys:update` | `PATCH /keys/:id` | 编辑现有密钥的权限。这是一个**仅限人工/仪表盘使用**的权限，不能分配给 API 密钥（Bearer 密钥可以创建密钥，但永远不能编辑密钥）。 | +| `keys:disable` | `POST /keys/:id/disable` | 吊销密钥。受保护的密钥（`admin`、`dashboard-assistant`）无法被禁用；通过环境变量 + 重启来轮换它们。 | +| `keys:regenerate` | `POST /keys/:id/regenerate` | 轮换密钥的机密。受保护的密钥无法通过此路由重新生成。 | -### 仪表板用户 +### 仪表盘用户 | 权限 | HTTP 路由 | 允许的操作 | |---|---|---| -| `users:create` | `POST /users`、`GET /users/defaults` | 邀请新的仪表板用户（发送电子邮件及一次性密码 (OTP) 登录），并读取用于预填邀请表单的仪表板配置默认权限集。 | +| `users:create` | `POST /users`、`GET /users/defaults` | 邀请新的仪表盘用户（发送邮件 + 一次性密码（OTP）登录），以及读取用于预填充邀请表单的仪表盘配置默认权限集。 | | `users:read` | `GET /users`、`GET /users/:id` | 列出用户并加载单个用户记录。 | -| `users:update` | `PUT /users/:id` | 编辑用户的权限。更新会向受影响的用户发送权限变更邮件，并在其下一次请求时生效；无需重新登录。 | -| `users:delete` | `DELETE /users/:id`、`POST /users/:id/enable` | 禁用用户（立即吊销其会话）并重新启用之前被禁用的用户。 | +| `users:update` | `PUT /users/:id` | 编辑用户的权限。更新会向受影响的用户发送权限变更邮件，并在其下次请求时生效；无需重新登录。 | +| `users:delete` | `DELETE /users/:id`、`POST /users/:id/enable` | 禁用用户（立即吊销其会话）以及重新启用之前被禁用的用户。 | -这些权限支撑仪表板的**用户**页面，每个成员授予的作用域以标签形式显示： +这些权限支撑仪表盘的**用户**页面，其中每位成员被授予的作用域以标签形式显示： -![用户页面：每个仪表板用户一张卡片，显示其电子邮件、已授予的权限以及编辑/禁用控件](/agenteye/images/users.png) +![用户页面：每位仪表盘用户显示为一张卡片，包含其电子邮件、已授予的权限以及编辑/禁用操作](/agenteye/images/users.png) -### 操作设置 +### 运营设置 | 权限 | HTTP 路由 | 允许的操作 | |---|---|---| -| `settings:read` | `GET /settings`、`GET /settings/schema`、`GET /settings/model-context-windows`、`GET /settings/model-context-windows/resolve` | 查看仪表板管理的操作设置及其元数据；列出每个模型的上下文窗口覆盖值；以及解析模型的有效窗口。 | -| `settings:write` | `PUT /settings/:key`、`PUT /settings/model-context-windows`、`DELETE /settings/model-context-windows` | 编辑操作设置，以及添加、更改或删除每个模型的上下文窗口覆盖值。更改会影响新事件，无需重启服务器。 | +| `settings:read` | `GET /settings`、`GET /settings/schema`、`GET /settings/model-context-windows`、`GET /settings/model-context-windows/resolve` | 查看仪表盘管理的运营设置及其元数据；列出每个模型的上下文窗口覆盖值；以及解析某模型的有效窗口大小。 | +| `settings:write` | `PUT /settings/:key`、`PUT /settings/model-context-windows`、`DELETE /settings/model-context-windows` | 编辑运营设置，以及添加、修改或删除每个模型的上下文窗口覆盖值。更改将对新事件生效，无需重启服务器。 | -![设置页面：仪表板管理的操作设置，例如允许的登录方式和会话/OTP 有效期，可在不重启的情况下编辑](/agenteye/images/settings.png) +![设置页面：仪表盘管理的运营设置，例如允许的登录方式和会话/OTP 生命周期，无需重启即可编辑](/agenteye/images/settings.png) ### 告警与事件 @@ -101,7 +101,7 @@ API 密钥控制谁以及什么可以访问您的 Failproof AI Observability 服 | `alerts:write` | `POST /alerts`、`PUT /alerts/:id`、`DELETE /alerts/:id`、`POST /alerts/:id/test` | 创建、编辑、删除和测试触发告警定义。 | | `incidents:read` | `GET /alerts/incidents`、`GET /alerts/incidents/:iid`、`GET /alerts/incidents/:iid/comments`、`GET /alerts/incidents/:iid/subscribers` | 查看事件及其分类记录。 | | `incidents:write` | `POST /alerts/:id/incidents` | 针对现有告警手动开启一个事件。 | -| `incidents:ack` | `POST /alerts/incidents/:iid/ack`、`POST /alerts/incidents/:iid/assign`、`POST /alerts/incidents/:iid/resolve`、`POST /alerts/incidents/:iid/comments`、`POST /alerts/incidents/:iid/subscribe`、`POST /alerts/incidents/:iid/unsubscribe` | 确认、分配、解决事件并对其进行评论。 | +| `incidents:ack` | `POST /alerts/incidents/:iid/ack`、`POST /alerts/incidents/:iid/assign`、`POST /alerts/incidents/:iid/resolve`、`POST /alerts/incidents/:iid/comments`、`POST /alerts/incidents/:iid/subscribe`、`POST /alerts/incidents/:iid/unsubscribe` | 确认、分配、解决和评论事件。 | ### 审计 @@ -110,62 +110,62 @@ API 密钥控制谁以及什么可以访问您的 Failproof AI Observability 服 | `audits:read` | `GET /audits`、`GET /audits/:id`、`GET /audits/:id/runs`、`GET /audits/findings`、`GET /audits/findings/:fid` | 查看审计定义、运行历史和发现结果。 | | `audits:write` | `POST /audits`、`PUT /audits/:id`、`DELETE /audits/:id`、`POST /audits/:id/run`、`POST /audits/findings/:fid/status` | 创建、编辑、删除和运行审计；对发现结果进行分类（确认/静默/忽略/解决/重新开启/分配）。 | -> **注意：** 要为密钥授予审计权限，请显式授予 `audits:*`。有关审计功能上线时现有授权者的迁移方式，请参阅[升级和向后兼容性说明](#upgrade-and-backward-compatibility-notes)。 +> **注意：** 若要给密钥授予审计相关功能，需要显式授予 `audits:*`。有关审计功能上线时现有被授权方如何迁移的说明，请参见[升级与向后兼容性说明](#upgrade-and-backward-compatibility-notes)。 -> 收件人选择器端点 `GET /alerts/recipients`（列出告警编辑器可通知的成员邮箱）可由持有 `alerts:read` **或** `alerts:write` 任一权限的用户访问，因此告警编辑器无需被授予 `users:read` 即可填充选择器。 +> 收件人选择器端点 `GET /alerts/recipients`（列出告警编辑器可通知的成员邮件）可由持有 **`alerts:read`** **或** `alerts:write` 的用户访问，因此告警编辑器无需被授予 `users:read` 即可填充选择器。 -> 仪表板查看者需要**同时具备** `dashboards:read`（加载已保存的视图）和 `evaluations:read`（健康指标从评估数据中计算）。授予 `dashboards:write` 可让用户创建或编辑仪表板，授予 `dashboards:delete` 可删除仪表板。 +> 仪表盘查看者需要**同时**拥有 `dashboards:read`（用于加载已保存的视图）和 `evaluations:read`（健康指标由评估数据计算得出）。授予 `dashboards:write` 以允许用户创建或编辑仪表盘，授予 `dashboards:delete` 以允许删除仪表盘。 -> `/health` 和 `/auth/*`（OTP 请求、OTP 验证、会话检查、登出）在设计上不需要身份验证；它们是登录流程和存活探针。`GET /access-granters` 需要有效密钥但不需要特定权限，因此任何已登录的用户都可以查看哪些管理员可联系以进行访问变更。 +> `/health` 和 `/auth/*`（OTP 请求、OTP 验证、会话检查、登出）按设计不需要身份验证；它们是登录流程和存活探针。`GET /access-granters` 需要有效密钥但不需要特定权限，因此任何已登录用户都可以查看应联系哪些管理员来进行访问变更。 --- ## 权限集 -权限集允许您应用命名角色，而无需每次手动挑选单个令牌。与其为每个新仪表板用户或 API 密钥逐一选择十几个权限，不如选择一个集合，分配到该集合的所有人都持有一致且可审查的授权。编辑自定义集合会将新授权重新应用于已分配该集合的每个用户，因此角色变更只需一次编辑，而无需逐一遍历每个成员。 +权限集允许您应用一个命名角色，而无需每次手动选择单个权限令牌。您无需为每位新仪表盘用户或 API 密钥逐一选择十几个权限，只需选择一个集合，所有分配到该集合的用户都将获得一致且可审查的授权。编辑自定义集合会将新授权重新应用于所有已分配该集合的用户，因此角色变更只需编辑一次，而无需逐一修改每位成员。 -每个组织初始化时都带有三个内置集合： +每个组织都会预置三个内置集合： | 集合 | 权限 | 适用对象 | |---|---|---| -| `read-only` | `events:read`、`keys:read`、`users:read`、`evaluations:read`、`dashboards:read`、`queries:read`、`settings:read`、`alerts:read`、`audits:read`、`incidents:read` | 对所有操作界面的只读访问。 | +| `read-only` | `events:read`、`keys:read`、`users:read`、`evaluations:read`、`dashboards:read`、`queries:read`、`settings:read`、`alerts:read`、`audits:read`、`incidents:read` | 对所有运营界面的只读访问。 | | `standard` | `read-only` 中的所有权限，加上 `evaluations:trigger`、`queries:run`、`incidents:ack`、`agent:use` | 只读权限加上日常值班操作：运行查询、重新评估会话、确认事件以及使用 AI 助手。 | | `admin` | 所有可分配的权限 | 对组织的完全控制。 | -三个内置集合是**不可变的**；其名称始终代表相同含义，因此 `read-only`、`standard` 和 `admin` 可在策略和入职流程中安全引用。操作员可以创建额外的**自定义集合**，以建模特定于您组织的角色（例如"仪表板作者"角色或"仅采集器"角色）。 +三个内置集合是**不可变的**；它们的名称始终代表相同的含义，因此 `read-only`、`standard` 和 `admin` 可安全地在策略和入职流程中引用。操作员可以创建额外的**自定义集合**来模拟特定于您组织的角色（例如"仪表盘作者"角色或"仅采集器"角色）。 -集合在仪表板中展示，并通过 API 进行管理：`GET /permission-sets`（列出，受 `users:read` 控制）以及 `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name`（创建、编辑、删除自定义集合，受 `settings:write` 控制）。删除或编辑内置集合的请求将被拒绝。 +集合通过仪表盘公开，并通过 API 进行管理：`GET /permission-sets`（列表，受 `users:read` 控制）以及 `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name`（创建、编辑、删除自定义集合，受 `settings:write` 控制）。删除或编辑内置集合的操作将被拒绝。 -集合成员资格支撑着另外两项功能： +集合成员资格支撑另外两个功能： -- **`DEFAULT_USER_PERMISSIONS`**（管理员打开 **+ 新用户** 时预选的授权）默认为 `standard` 集合。 -- **`agenteye-orgctl` 上的 `--set` 标志**（操作员成员管理）从命名集合初始化成员，然后您可以使用 `--add` / `--remove` 进行微调。 +- **`DEFAULT_USER_PERMISSIONS`**（管理员打开**+ 新建用户**时预先选定的授权）默认为 `standard` 集合。 +- **`agenteye-orgctl` 上的 `--set` 标志**（操作员成员管理）从命名集合开始为成员初始化权限，然后您可以通过 `--add` / `--remove` 进行微调。 -> **注意：** 当集合包含不可分配给密钥的权限时（例如携带 `keys:update` 的自定义集合），从该集合初始化密钥时会删除不可分配的令牌；否则服务器将以 HTTP 422 拒绝该密钥。仪表板用户不受此限制。 +> **注意：** 当集合包含不可分配给密钥的权限（例如包含 `keys:update` 的自定义集合）时，从该集合初始化密钥会丢弃不可分配的令牌；否则服务器将以 HTTP 422 拒绝该密钥。仪表盘用户不受此限制。 --- ## 引导管理员密钥 -管理员密钥是单一根凭证，允许操作员从零开始建立访问权限：使用它可以创建所有其他作用域密钥、邀请第一批仪表板用户，并在任何其他密钥存在之前配置实例。这是唯一不通过密钥 API 创建的密钥；它从环境中配置，以便服务器在首次启动时即可访问。 +管理员密钥是操作员从零开始建立访问权限的单一根凭证：通过它可以创建所有其他作用域密钥、邀请第一批仪表盘用户，以及在任何其他密钥存在之前配置实例。这是唯一不通过密钥 API 创建的密钥；它从环境中预置，以便服务器在首次启动时可访问。 在服务器上设置 `ADMIN_KEY` 环境变量。每次启动时，服务器会将此值更新插入为具有所有权限的管理员密钥。 -轮换方式：将 `ADMIN_KEY` 更改为新密文并重启服务器。 +轮换方式：将 `ADMIN_KEY` 更改为新机密并重启服务器。 --- ## 组织作用域 -**组织本身由操作员在带外创建和管理，而不是通过此密钥 API。** 组织和成员的生命周期（创建/重命名/删除/清除组织；添加/更新/移除成员）通过 **`agenteye-orgctl`** CLI 完成；没有对应的 HTTP API 或仪表板按钮。**不变的是：按组织的 API 密钥仍由组织成员在仪表板（或通过此密钥 API）中创建。** +**组织本身由操作员通过带外方式创建和管理，而不是通过此密钥 API。** 组织和成员的生命周期（创建/重命名/删除/清除组织；添加/更新/移除成员）通过 **`agenteye-orgctl`** CLI 完成；没有 HTTP API 或仪表盘按钮可以执行这些操作。**保持不变的是：按组织划分的 API 密钥仍由组织成员在仪表盘（或通过此密钥 API）中创建。** -在多组织部署中，组织成员创建的每个密钥（通过此密钥 API 或仪表板**密钥**页面）都属于**一个组织**，只能读取或写入该组织的数据；组织在创建时被标记到密钥上，并在每次请求时强制执行。两个引导密钥是唯一的例外：`admin` 密钥（从 `ADMIN_KEY` 初始化）和 `dashboard-assistant` 密钥（从 `AGENT_API_KEY` 初始化）是**实例作用域**（不携带组织信息）。仪表板使用 `admin` 密钥进行身份验证，以便代表已登录的成员代理每个组织的请求。单租户部署无需考虑这一点；所有密钥都属于内置的 `default` 组织。 +在多组织部署中，组织成员创建的每个密钥（通过此密钥 API 或仪表盘的**密钥**页面）都属于**一个组织**，只能读取或写入该组织的数据；组织在创建时被标记在密钥上，并在每次请求时强制执行。两个引导密钥是唯一的例外：`admin` 密钥（从 `ADMIN_KEY` 初始化）和 `dashboard-assistant` 密钥（从 `AGENT_API_KEY` 初始化）是**实例作用域**的（不携带组织信息）。仪表盘使用 `admin` 密钥进行身份验证，以便代表已登录成员代理按组织划分的请求。单租户部署无需考虑这一点；所有密钥都属于内置的 `default` 组织。 --- ## 创建密钥 -使用管理员密钥（或任何具有 `keys:create` 权限的密钥）来创建其他作用域密钥。 +使用管理员密钥（或任何具有 `keys:create` 权限的密钥）来创建额外的作用域密钥。 ### 采集器密钥（仅摄取） @@ -180,7 +180,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -### 仪表板密钥（只读） +### 仪表盘密钥（只读） ```bash curl -s -X POST http://your-server/keys \ @@ -193,7 +193,7 @@ curl -s -X POST http://your-server/keys \ }' ``` -通过 HTTP API 创建密钥时，您需要自行提供 `key` 值；请选择强密文并安全存储。（仪表板的方式相反：它会为您生成强密文，并在创建时仅显示一次；参见[仪表板中的密钥管理](#key-management-in-the-dashboard)。）响应确认密钥已创建： +通过 HTTP API 创建密钥时，您需要自行提供 `key` 值；请选择强机密并安全存储。（仪表盘的方式相反：它为您生成强机密，并在创建时显示一次；参见[在仪表盘中管理密钥](#key-management-in-the-dashboard)。）响应确认密钥已创建： ```json { @@ -213,13 +213,13 @@ curl -s http://your-server/keys \ -H "Authorization: Bearer $ADMIN_KEY" ``` -列表响应中不返回密钥密文，只返回 ID、名称和权限。 +列表响应不返回密钥机密，只返回 ID、名称和权限。 --- ## 禁用密钥 -禁用会立即吊销访问权限，而不删除密钥记录。 +禁用操作会立即吊销访问权限，而不删除密钥记录。 ```bash curl -s -X POST http://your-server/keys//disable \ @@ -230,24 +230,24 @@ curl -s -X POST http://your-server/keys//disable \ ## 重新生成密钥 -为现有密钥生成新密文。旧密文立即失效。 +为现有密钥生成新机密。旧机密立即失效。 ```bash curl -s -X POST http://your-server/keys//regenerate \ -H "Authorization: Bearer $ADMIN_KEY" ``` -响应包含新的明文密文，**仅显示一次**。 +响应包含新的明文机密，**仅显示一次**。 --- -## 仪表板中的密钥管理 +## 在仪表盘中管理密钥 -仪表板中的**密钥**页面为上述所有操作提供了 UI。您需要具有 `keys:read` 权限的密钥才能查看列表，以及分别具有 `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` 权限才能执行创建/编辑/禁用/重新生成操作。编辑密钥权限（`keys:update`）与创建密钥（`keys:create`）是分开的，因此您可以授予操作员创建密钥的能力，而不授予重新界定现有密钥作用域的能力，反之亦然。管理员密钥涵盖所有这些操作。 +仪表盘中的**密钥**页面提供了上述所有操作的 UI。您需要具有 `keys:read` 权限的密钥来查看列表，以及分别需要 `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` 来执行创建/编辑/禁用/重新生成操作。编辑密钥权限（`keys:update`）与创建密钥（`keys:create`）是分开的，因此您可以授予操作员创建密钥的能力，而不授予重新划定现有密钥作用域的能力，反之亦然。管理员密钥涵盖所有这些操作。 -从仪表板创建密钥时，您无需提供密文；仪表板会为您生成强密文，并在创建时**仅显示一次**。请立即复制并安全存储；与重新生成密钥一样，它不会再次显示。您仍然可以直接选择密钥的权限，或从权限集初始化（见下文）。 +从仪表盘创建密钥时，您无需提供机密；仪表盘会为您生成强机密，并在创建时**显示一次**。请立即复制并安全存储；它不会再次显示，与重新生成操作完全相同。您仍然可以直接选择密钥的权限，或从权限集中初始化权限（见下文）。 -![API 密钥页面：每个密钥一张卡片，显示其名称、已授予的权限和创建时间，以及重新生成和禁用操作；受保护的密钥（如 `admin`）会被标记](/agenteye/images/api-keys.png) +![API 密钥页面：每个密钥显示为一张卡片，包含其名称、已授予的权限和创建时间，以及重新生成和禁用操作；受保护的密钥（如 `admin`）被标记](/agenteye/images/api-keys.png) --- @@ -255,26 +255,26 @@ curl -s -X POST http://your-server/keys//regenerate \ | 密钥 | 权限 | 使用者 | |---|---|---| -| `admin`（通过 `ADMIN_KEY` 环境变量引导） | 所有 | 运维/配置，以及仪表板（使用 `ADMIN_KEY` 进行身份验证，通过权限检查代理用户请求） | -| 每主机采集器密钥 | `events:add` | 每台 Agent 机器上的采集器 | +| `admin`（通过 `ADMIN_KEY` 环境变量引导） | 所有权限 | 运维/设置，以及仪表盘（使用 `ADMIN_KEY` 进行身份验证，通过权限检查代理用户请求） | +| 每台主机采集器密钥 | `events:add` | 每台 Agent 机器上的采集器 | | `dashboard-assistant`（通过 `AGENT_API_KEY` 环境变量引导） | `events:read`、`evaluations:read`、`dashboards:read`、`dashboards:write`、`queries:read`、`queries:write`、`queries:run` | AI 助手，自动初始化，**受保护**；无法通过 API 编辑 | -| 助手遥测密钥（可选） | `events:add` | AI 助手自我检测（如已启用） | +| 助手遥测密钥（可选） | `events:add` | AI 助手自我监测，如已启用 | -> **注意：** 助手的密钥由服务器从 `AGENT_API_KEY` 环境变量**自动初始化**（Agent 以 `AGENTEYE_API_KEY` 形式呈现同一密文）；无需手动创建密钥，也不涉及管理员密钥。其权限在源代码中固定，因此作用域不会因配置错误而被扩展：对事件/评估/仪表板的读取权限，加上用于"让 AI 编写查询"创作流程的仪表板写入和查询读取/写入/运行权限。所有 SQL 仍然通过与用户编写的查询相同的只读角色和受保护 SQL 路径，因此这扩展了*创作界面*，而非数据界面；破坏性操作（`queries:delete`、`dashboards:delete`）刻意不在助手密钥中。与 `admin` 密钥一样，它是**受保护的**：无法通过密钥 API 禁用或重新生成，只能通过更改 `AGENT_API_KEY` 并重启来轮换。仪表板*用户*还需要 `agent:use` 权限才能看到并使用助手。如果您启用了自我检测，请为助手提供一个单独的仅 `events:add` 密钥。 +> **注意：** 助手的密钥由服务器从 `AGENT_API_KEY` 环境变量**自动初始化**（与 Agent 以 `AGENTEYE_API_KEY` 形式呈现的机密相同）；无需手动创建密钥，也不涉及管理员密钥。其权限在源代码中固定，因此作用域不会因配置错误而被扩大：读取事件/评估/仪表盘，加上仪表盘写入和查询读取/写入/运行（用于"让 AI 编写查询"的创作流程）。所有 SQL 仍通过与用户编写的查询相同的只读角色和受保护的 SQL 路径，因此这扩大了*创作界面*，而非数据界面；破坏性操作（`queries:delete`、`dashboards:delete`）被刻意排除在助手密钥之外。与 `admin` 密钥一样，它是**受保护的**：无法通过密钥 API 禁用或重新生成，只能通过更改 `AGENT_API_KEY` 并重启来轮换。仪表盘*用户*还需要 `agent:use` 权限才能看到和使用助手。如果您启用自我监测，请为助手提供一个单独的仅 `events:add` 密钥。 --- -## 升级和向后兼容性说明 +## 升级与向后兼容性说明 -仅在升级现有实例时才需要以下内容；新部署可跳过。 +以下内容仅适用于升级现有实例的用户；新部署可跳过。 -> 审计功能上线时，现有授权者按照与告警相同的角色形态进行了扩展：每个持有 `alerts:read` 的用户和权限集获得了 `audits:read`，每个持有 `alerts:write` 的用户获得了 `audits:write`。现有 API 密钥**未被扩展**。如果密钥需要审计功能，请显式授予 `audits:*`。 +> 审计功能上线时，现有被授权方按照与告警相同的角色形状进行了扩展：每个持有 `alerts:read` 的用户和权限集获得了 `audits:read`，每个持有 `alerts:write` 的用户获得了 `audits:write`。现有 API 密钥**未被**扩展。如果密钥需要审计相关功能，请显式授予 `audits:*`。 -> 旧版 `alerts:ack` 令牌的存储授权被解析为 `incidents:ack`，以便值班人员无需重新创建密钥即可保留访问权限。该令牌不再可从仪表板用户编辑器分配；矩阵现在提供 `incidents:ack`。 +> 存储的旧版 `alerts:ack` 令牌被解析为 `incidents:ack`，因此值班人员无需重新生成密钥即可保留访问权限。该令牌不再可从仪表盘用户编辑器分配；矩阵提供 `incidents:ack` 作为替代。 --- -## 后续步骤 +## 下一步 -- [Python SDK](/zh/agenteye/python-sdk)：您的 Agent 代码在发送事件时如何进行身份验证。 -- [安全性](/zh/agenteye/security)：登录、访问控制和每个组织的数据隔离如何工作。 \ No newline at end of file +- [Python SDK](/zh/agenteye/python-sdk)：了解您的 Agent 代码在发送事件时如何进行身份验证。 +- [安全](/zh/agenteye/security)：了解登录、访问控制以及按组织划分的数据隔离如何工作。 \ No newline at end of file diff --git a/docs/zh/agenteye/assistant.mdx b/docs/zh/agenteye/assistant.mdx index 44ec814e..04cc4d75 100644 --- a/docs/zh/agenteye/assistant.mdx +++ b/docs/zh/agenteye/assistant.mdx @@ -1,15 +1,15 @@ --- title: "AI 助手" -description: "用自然语言向 Agent 数据提问，并直接获取链接到具体证据的答案。" +description: "用自然语言向你的 Agent 数据提问，获取直接链接到证据的答案。" --- -用自然语言向 Agent 数据提问，并直接获取链接到具体证据的答案。无需编写 SQL，无需翻查仪表盘——**Failproof AI Observability** 助手是团队中任何人获取 Agent 相关答案的最快方式。 +用自然语言向你的 Agent 数据提问，获取直接链接到证据的答案。无需编写 SQL，无需翻遍仪表盘——**Failproof AI Observability** 助手是团队中任何人获取 Agent 相关答案的最快途径。 -![Failproof AI Observability 助手在仪表盘中回答自然语言问题的界面，展示了实时 Agent 活动表、按 Agent 划分的模型使用情况，以及文字摘要，所执行的查询也内联显示](/agenteye/images/assistant.png) -*用自然语言提问，答案直接来自你自己的数据。这里它分解了哪些 Agent 最繁忙、它们使用了哪些模型，并展示了执行的查询，方便你核实每一个数字。* +![Failproof AI Observability 助手在仪表盘中回答自然语言问题，展示实时 Agent 活动表、每个 Agent 的模型使用情况分解及文字要点，并内联显示所执行的查询](/agenteye/images/assistant.png) +*用自然语言提问，从你自己的数据中获取答案。这里它分解了哪些 Agent 最繁忙、它们使用了哪些模型，并展示了所执行的查询，让你可以逐一核实每个数字。* -无需任何学习成本。打开对话框，输入你想了解的内容，然后点击它返回的链接： +无需任何学习成本。打开对话框，输入你想了解的内容，点击返回的链接即可： ``` You: which sessions errored today? @@ -24,36 +24,36 @@ AI: This run took 12 steps across 3 tools and failed near the end when a Links: the session, the failing event, and that evaluation. ``` -## 直接提问，直达证据 +## 直接提问，跳转到证据 -你不再需要凭猜测，也不再需要手写查询。问"本周生产环境的质量趋势如何？"、"今天哪些 Session 出错了？"或"总结这个 Session"，几秒钟内便能得到直接答案，而无需自己构建查询并逐行阅读。 +你不再需要猜测，也不再需要编写查询。询问"本周生产环境的质量趋势如何？"、"今天哪些 session 出错了？"或"总结一下这个 session"，几秒钟内即可获得直接答案，而无需自己构建查询并逐一阅读结果。 -每个答案都附有来源依据。助手会链接到它用于得出答案的确切 Session、已保存查询和仪表盘，让你可以点进去核实，而不必盲目信任它的结论。它还具备**页面感知**能力：在查看某个 Session 时询问"这个 Session"，它就已经知道你指的是哪次运行。稍后可以从历史切换器中重新打开任意早期对话，从上次中断的地方继续。 +每个答案都附有来源依据。助手会链接到它用于得出答案的具体 session、已保存的查询和仪表盘，让你可以点击验证，而不是单纯相信它的说法。它还具备**页面感知**能力：当你正在查看某个 session 时询问"这个 session"，它已经知道你指的是哪次运行。稍后通过历史切换器重新打开之前的任何对话，可以从上次中断的地方继续。 -## 将满意的答案保存为查询或仪表盘 +## 将好答案转化为已保存的查询或仪表盘 -当一个答案值得保留时，直接让助手保存它即可。它会起草 SQL 生成已保存查询，或根据这些查询组装仪表盘，然后向你展示一张 **Approve / Reject** 确认卡片。在你点击 Approve 之前，任何内容都不会被写入，因此你既享有"直接提问"的速度，又始终掌握最终决定权。 +当某个答案值得保留时，可以请助手将其保存。它会起草 SQL 以生成已保存的查询，或从这些查询中组装一个仪表盘，然后向你展示**批准 / 拒绝**卡片。在你点击批准之前，不会写入任何内容，因此你既能享受"直接提问"的速度，又始终掌握最终决定权。 -在 **Queries** 页面，助手更进一步，化身 SQL 编写者：描述你想要的查询（"显示过去 7 天内各 Agent 的错误率"），它会将 SQL 直接流式输入编辑器，并打开差异视图，让你在内容落定前选择 **Accept** 或 **Reject**。 +在**查询**页面，它更进一步，成为 SQL 创作者：描述你想要的查询（"按 Agent 显示过去 7 天的错误率"），它会将 SQL 直接流式输出到编辑器中，并打开差异视图，让你在变更落地之前选择**接受**或**拒绝**。 -![Observability Queries 页面及其 SQL 编辑器](/agenteye/images/query-lab.png) -*Queries 页面：编辑器是助手流式生成草稿查询的地方，查询为只读状态，供你接受或拒绝。* +![Observability 查询页面及其 SQL 编辑器](/agenteye/images/query-lab.png) +*查询页面：这个编辑器是助手流式输出草稿只读查询的地方，供你接受或拒绝。* -在此通过提问来编写 SQL 使用的是 `queries:run` 权限，与编辑器中 **Run** 按钮背后的权限相同。其他地方的对话则需要 `agent:use` 权限。 +在此通过提问来创作 SQL 使用的是 `queries:run` 权限，与编辑器的**运行**按钮背后的权限相同。其他地方的对话则需要 `agent:use` 权限。 -## 可以放心开放给整个团队 +## 可安全开放给整个团队 -你可以将助手开放给所有人使用，无需担心它会触碰什么： +你可以将助手开放给所有人，无需担心它可能触及的内容： -- **它只读取你已有权限查看的内容。** 答案受限于你自己的读取权限，因此它不会扩大你的数据访问范围。 -- **每次写入操作都需要你确认。** 已保存查询和仪表盘只有在你明确点击 Approve 后才会创建，且没有任何设置可以关闭这道审批门。 -- **它永远无法删除任何内容。** 没有删除工具暴露给助手，它也不持有删除权限。删除操作始终由你在仪表盘中亲自完成。 -- **它仅限于你的组织内部。** 助手只能查看你当前所在的组织。 -- **你的问题属于你自己。** 提示词和答案存储在你自己的 Observability 数据库中；产品分析功能只记录使用元数据，从不记录你的提示词文本。 +- **它只读取你已有权访问的内容。** 答案的范围限定在你自己的读取权限内，因此它不会扩大你的数据访问面。 +- **每次写入操作都需要你的确认。** 已保存的查询和仪表盘只有在你明确点击批准后才会创建，且没有任何设置可以关闭这道门槛。 +- **它永远无法删除任何内容。** 没有暴露任何删除工具，助手也不持有删除权限。删除操作始终由你在仪表盘中执行。 +- **它仅在你的组织内运作。** 助手只会访问你当前正在查看的组织。 +- **你的问题属于你自己。** 提示和答案存储在你自己的 Observability 数据库中；产品分析仅记录使用元数据，从不记录你的提示文本。 ## 在哪里找到它 -助手常驻于你的组织（`//...`）每个页面的右侧边栏。点击侧边栏，或按 `⌘J` / `Ctrl+J`，即可展开完整的对话面板；拖动边缘可调整大小，宽度设置会在页面刷新后保留。使用助手需要 **`agent:use`** 权限，否则侧边栏将显示为灰色不可用状态。如果你的部署尚未启用助手（需要配置 LLM 连接），你将看到一个静默的侧边栏，而非可用的对话框。 +助手位于你的组织（`//...`）下每个页面的右侧边栏。点击边栏，或按 `⌘J` / `Ctrl+J`，将其展开为完整的对话面板，拖动边缘可调整大小；你设置的宽度在页面刷新后会被记住。使用它需要 **`agent:use`** 权限，否则边栏将显示为灰色。如果你的部署尚未启用该功能（需要 LLM 连接），你将看到一个无响应的边栏，而非正常工作的对话界面。 ## 相关内容 diff --git a/docs/zh/agenteye/audits.mdx b/docs/zh/agenteye/audits.mdx index b1400d83..7024b1f7 100644 --- a/docs/zh/agenteye/audits.mdx +++ b/docs/zh/agenteye/audits.mdx @@ -1,54 +1,54 @@ --- title: "审计：您的自动可靠性分析师" -description: "Failproof AI Observability 会主动发现那些您从未为之编写规则的故障，并为您提供一份按优先级排列、有证据支撑的待办清单，告诉您究竟需要修复什么。" +description: "Failproof AI Observability 会主动发现您从未为之编写规则的故障，并为您提供一份按优先级排列、有据可查的待办清单，告诉您确切需要修复的内容。" --- -Failproof AI Observability 会主动发现那些您从未为之编写规则的故障，并为您提供一份按优先级排列、有证据支撑的待办清单，告诉您究竟需要修复什么。这就像每晚都有一位分析师梳理您的日志，然后在清晨将简短的清单放在您的桌上。 +Failproof AI Observability 会主动发现您从未为之编写规则的故障，并为您提供一份按优先级排列、有据可查的待办清单，告诉您确切需要修复的内容。这就像每晚都有一位分析师梳理您的日志，次日清晨将精简的清单放到您桌上。
-*两分钟概览：从计划运行到可付诸行动的修复方案。* +*两分钟速览：从定时运行到可立即执行的修复方案。* -![审计页面：定期扫描会话以发现故障模式的周期性任务，每项任务都有计划和灵敏度设置](/agenteye/images/audits.png) -*每个审计都是一个周期性任务，负责挖掘您的会话数据并输出按优先级排列、有证据支撑的改进建议。* +![审计页面：定期扫描您的会话以发现故障模式的周期性任务，每个任务都配有计划和灵敏度设置](/agenteye/images/audits.png) +*每次审计都是一个周期性任务，它会挖掘您的会话数据并整理出按优先级排列、有据可查的建议。* -## 不再猜测下一步修复什么 +## 不再猜测下一步该修复什么 -告警捕获的是您已知需要关注的问题。审计捕获的是您尚未意识到的问题。按照您设定的计划，审计会读取所有 Agent 会话，主动寻找值得修复的模式，让您将时间花在处理发现结果上，而不是滚动日志、期望自己碰巧发现问题。 +告警用于捕获您已知需要关注的问题，而审计则用于捕获那些您尚未意识到的问题。按照您设定的计划，审计会遍历您所有的 Agent 会话，主动寻找值得修复的模式——让您把时间花在处理发现上，而不是翻看日志碰运气。 -一次运行会针对生产环境中真正会破坏 Agent 的故障模式展开分析： +单次运行会针对生产环境中真正会导致 Agent 出问题的故障模式： -- **错误聚类**：在共同根因下反复出现的相同故障。 -- **与基线的偏移**：行为悄然偏离已知良好窗口的情况。 -- **对话记录中的目标失败**：技术上已完成但实际上未完成任务的运行。 -- **工具误用**：使用了错误的工具、传入了错误的参数，或陷入消耗调用次数的循环。 -- **质量与成本的权衡**：在本可以更低成本获得相同输出的地方支付了过高费用。 +- **错误聚类**：由同一根本原因反复触发的相同故障。 +- **相对基线的漂移**：行为悄然偏离已知正常窗口。 +- **对话记录中的目标失败**：技术上完成了运行，但从未完成实际任务。 +- **工具误用**：使用了错误的工具、传入了错误的参数，或产生了消耗调用次数的循环。 +- **质量与成本的权衡**：在可以用更低成本获得同等输出的地方过度付费。 - **覆盖盲区**：没有任何评估或告警在监控的行为。 -您可以通过单一的**灵敏度**设置（低、中或高）来决定分析的深度，从而让嘈杂的预发布 Agent 和严格的生产环境 Agent 各自调整到所需的信号水平。 +您只需通过一个**灵敏度**设置（低、中或高）来决定检查的深度，这样嘈杂的预发布环境 Agent 和严格管控的生产环境 Agent 都可以调整到您期望的信噪比。 -## 每条建议都有凭据 +## 每条建议都附有凭证 -您无需凭信任接受任何发现结果。每条建议都会引用其来源的确切会话以及发现该问题所用的 SQL，因此您只需点击一下即可查看证据并确认问题，而无需对某个结论进行反向推导。 +您无需对任何发现盲目信任。每条建议都会引用其来源的具体会话以及发现它所用的 SQL，让您一键查看证据、确认问题，而不必费力反推一个结论。 -当某个发现涉及泄露的凭据时，系统会更进一步，链接到匹配的具体事件。点击后您将直接跳转到会话中的那一精确时刻，且该时刻已被选中——而非需要您从头滚动的冗长对话记录。链接中只显示事件名称，从不将检测到的密钥复制到发现结果中，因此阅读发现结果不会成为您的凭据被记录的第二个地方。如果某个事件因会话已超过您的数据保留期限而不再存在，页面会直接说明，而不是让您疑惑自己是否点错了。 +当某条发现涉及凭证泄露时，还会进一步链接到具体匹配的事件。点击后，您会直接定位到该会话中的那个精确时刻，并已自动选中——而不是跳到一段需要从头滚动的长对话记录。链接会标注事件名称，但不会将检测到的密钥内容复制到发现详情中，因此查看发现并不会成为记录您凭证的第二个地方。如果某个事件因会话已超出您的数据保留窗口而不再存在，页面会明确说明，而不是让您疑惑是否点错了地方。 -这也是审计保持诚实的原因所在。服务器会验证每个被引用的会话确实存在，并**丢弃任何证据不成立的建议**，因此审计只会调查，绝不凭空捏造。出现在您清单上的结果都是真实可复现的，并按其重要性排序，影响最大的改进排在最前面。 +这也是保持审计诚实的关键所在。服务器会验证每个引用的会话确实存在，并**丢弃任何证据无法核实的建议**，因此审计只会调查，不会凭空捏造。出现在您清单上的内容都是真实、可复现的，并按照重要程度排序，影响最大的优化项排在最前面。 -## 将修复转化为安全护栏 +## 将修复转化为防护规则 -修复一个问题只是成功的一半。另一半是确保问题不会悄悄卷土重来。每条发现结果都附带一个**一键快捷方式，可起草一个复现告警**，并预填了一个合理的初始触发条件供您调整。关闭发现结果，启用告警，下次该模式再次出现时，您将收到通知，而不是在未来某次审计中重新发现它。 +修复一个问题只完成了一半。另一半是确保它不会悄悄卷土重来。每条发现都附有一个**一键快捷方式，可起草一条复发告警**，并预填好合理的初始触发条件供您调整。关闭发现、启用告警，下次该模式再次出现时，您将收到通知，而不是在未来的审计中重新发现它。 ## 在哪里找到它 -审计位于仪表板的 **`//audits`** 路径下（侧边栏 → *analyze* → *audits*）。查看运行记录和发现结果需要 **`audits:read`** 权限；创建、编辑和处理审计需要 **`audits:write`** 权限。设置审计的范围和频率，然后在需要立即获得结果而不想等待下一次计划运行时点击 **Run now**。 +审计功能位于仪表板的 **`//audits`**（侧边栏 → *analyze* → *audits*）。查看运行记录和发现需要 **`audits:read`** 权限；创建、编辑和处理审计需要 **`audits:write`** 权限。设置审计的范围和频率，然后在需要立即获取结果时点击 **Run now**，无需等待下一次定时执行。 ## 相关内容 -- [告警](/zh/agenteye/alerts)：在您已知的阈值被触发的瞬间收到通知。 -- [评估](/zh/agenteye/evaluations)：对每次运行进行评分，让质量回归问题自动浮现。 +- [告警](/zh/agenteye/alerts)：在您已知的阈值被突破的第一时间收到通知。 +- [评估](/zh/agenteye/evaluations)：对每次运行评分，让质量回退自动浮现。 - [错误追踪](/zh/agenteye/error-tracking)：对 Agent 抛出的错误进行分组和跟踪。 -- [事件](/zh/agenteye/incidents)：将审计发现的问题追踪至最终修复完成。 \ No newline at end of file +- [事故](/zh/agenteye/incidents)：跟踪审计发现的问题直至修复完成。 \ No newline at end of file diff --git a/docs/zh/agenteye/cli-and-agents.mdx b/docs/zh/agenteye/cli-and-agents.mdx index cec9188c..9a5132f2 100644 --- a/docs/zh/agenteye/cli-and-agents.mdx +++ b/docs/zh/agenteye/cli-and-agents.mdx @@ -1,79 +1,80 @@ --- title: "CLI" -description: "您的整个 Failproof AI 可观测性部署，一条命令即可搞定。" +description: "一条命令，掌控您的整个 Failproof AI Observability 部署。" --- -您的整个 Failproof AI 可观测性部署，一条命令即可搞定。无需离开终端，即可检查生产环境、创建 API 密钥或确认事件，还可以将任意操作编写成 CI 脚本，或者用自然语言让编程智能体替您完成。 + +一条命令，掌控您的整个 Failproof AI Observability 部署。无需离开终端，即可检查生产环境、生成 API 密钥或确认告警事件，还可以将任意操作脚本化集成到 CI 中，或者用自然语言让编码智能体替您完成。 ```bash pipx install agenteye -agenteye login --email you@example.com # 一个 6 位验证码将发送到您的邮箱 -agenteye --json sessions --since 24h # 过去一天的所有智能体运行记录，按最新排序 +agenteye login --email you@example.com # a 6-digit code lands in your inbox +agenteye --json sessions --since 24h # every agent run from the last day, newest first ``` -*`agenteye` CLI 与您的仪表板通信，是一个独立工具，与负责将事件发送到服务器的采集器不同。* +*`agenteye` CLI 与您的控制台通信，是一个独立于采集器（负责将事件发送至服务器）的工具。* -## 您的整个部署，一条命令即可搞定 +## 一条命令，掌控整个部署 -不必再为一个简单问题而反复切换标签页。`agenteye` CLI 通过单一二进制文件读取您的数据并管理您的组织，原本需要在仪表板中点来点去才能完成的检查，现在只需一行命令即可复用、设置别名或粘贴到操作手册中。它提供四个操作入口： +无需在标签页之间跳来跳去只为回答一个简单问题。`agenteye` CLI 通过单一二进制文件读取数据并管理您的组织，原本需要在控制台中点来点去的检查操作，如今只需一行命令，可随时重复执行、设置别名，或粘贴到运维手册中。它提供四个功能模块： - **读取数据：** `sessions`、`events`、`evals` 和 `errors`，支持按时间、智能体和环境过滤。 - **管理组织：** `keys`、`users`、`settings`、`alerts` 和 `incidents`。 -- **运行分析：** 支持保存的 SQL 查询，以及针对事件数据的即席 `query` 执行。 -- **询问助手：** `agent ask` 可访问与仪表板中相同的只读分析助手。 +- **运行分析：** 保存的 SQL 语句，以及针对事件数据的临时 `query` 执行器。 +- **询问助手：** `agent ask` 可调用与控制台中相同的只读分析助手。 -使用 `pipx` 一次性安装，通过邮件发送的 6 位验证码登录，即可开始使用。会话有效期约为一天，过期后重新运行 `agenteye login` 即可。无需打开浏览器，直接用它检查生产环境、创建密钥或快速处理正在触发的事件： +使用 `pipx` 一次性安装，通过邮件发送的 6 位验证码登录，即可开始使用。会话有效期约为一天，过期后重新运行 `agenteye login` 即可。无需打开浏览器，即可快速核查生产环境、创建密钥或处理正在触发的告警事件： ```bash -agenteye errors --since 24h --aggregate # 查看故障情况，按错误类型分组 -agenteye incidents list --state firing # 查看当前正在触发的事件 -agenteye keys create ci --add events:add # 创建一个仅能推送事件的密钥，密钥值仅显示一次 +agenteye errors --since 24h --aggregate # what is breaking, grouped by error type +agenteye incidents list --state firing # what is on fire right now +agenteye keys create ci --add events:add # a key that can only push events, secret shown once ``` -有一个使用习惯需要注意：`--json` 等全局选项必须放在命令之前。`agenteye --json sessions` 是正确的，`agenteye sessions --json` 则不行。 +有一个使用习惯需要注意：`--json` 等全局选项需放在命令之前。`agenteye --json sessions` 是正确写法；`agenteye sessions --json` 则不正确。 -## 编写脚本，集成到 CI +## 脚本化，接入 CI -每条命令都支持 `--json`，这带来了质的变化。干净的 JSON 输出到 stdout，而人类可读的状态信息和警告则输出到 stderr，因此使用 `--json` 捕获的内容可以直接通过管道传给 `jq`，无需过滤多余的行。这也是 CLI 既适合您在终端直接使用，也适合编程智能体解析输出的原因： +每条命令都支持 `--json`，这带来了质的变化。规整的 JSON 输出到 stdout，而供人阅读的状态信息和警告则输出到 stderr，因此带 `--json` 的输出可以直接通过管道传给 `jq`，无需清理多余内容。这也是为什么 CLI 同样适合在命令行提示符下使用，也适合编码智能体解析输出： ```bash agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' ``` -它专为无人值守运行而设计。当没有终端连接时，确认提示会自动跳过，因此在管道中不会卡住，而且每条命令都会返回有意义的退出码：`0` 表示成功，`4` 表示未登录，`5` 表示缺少权限（消息中会指明具体权限，例如 `alerts:write`），`3` 表示仪表板无法访问。脚本可以根据 `4` 进行重新认证，或根据 `5` 精确告知需要向管理员申请哪些权限，而不是盲目失败。 +它专为无人值守运行而设计。当未连接终端时，确认提示会自动跳过，不会在管道中卡住；每条命令都会返回有意义的退出码：`0` 表示成功，`4` 表示未登录，`5` 表示缺少权限（消息中会明确指出，例如 `alerts:write`），`3` 表示控制台不可达。脚本可以根据 `4` 进行重新认证，或根据 `5` 精确告知需要向管理员申请哪项权限，而不是盲目失败。 -## 用自然语言让编程智能体来驱动 +## 用自然语言让编码智能体来操作 -更好的是，您根本不需要记住这些参数。**CLI 技能**是一个名为 `agenteye-cli` 的小型 Agent Skill 文件夹，它可以教会 Claude Code 或 Codex 等编程智能体通过自然语言来驱动 CLI。只需问"今天有什么问题吗？"，智能体就会选择合适的命令，以您的身份执行，并以文字形式给出答复。 +更进一步，您其实根本不需要记住这些参数。**CLI skill** 是一个名为 `agenteye-cli` 的小型 Agent Skill 文件夹，它能让 Claude Code 或 Codex 等编码智能体通过自然语言请求来驱动 CLI。只需问"今天有什么问题吗？"，智能体会自行选择命令、以您的身份运行，并以文字形式给出答复。 -对于 Claude Code，将 `agenteye-cli` 文件夹放入 `~/.claude/skills/` 即可自动发现。Failproof AI 可观测性提供该文件夹；无需额外安装任何内容，因为它只是驱动您已经安装的 CLI。请先自行登录：技能无法替您完成邮件验证码登录流程。 +对于 Claude Code，将 `agenteye-cli` 文件夹放入 `~/.claude/skills/` 即可自动发现。Failproof AI Observability 提供该文件夹，无需额外安装，因为它只是驱动您已安装的 CLI。请先自行登录：skill 无法替您完成邮件验证码登录流程。 -由于智能体以您的身份运行 CLI，它可以执行您的登录权限所允许的一切操作，包括读写：创建密钥、修改设置、解决事件。CLI 的"您确定吗？"提示对智能体不会触发，因此技能的设计是：在执行任何变更操作前，先明确说明将要执行的命令，并等待您确认。您就是那个确认步骤。 +由于智能体以您的身份运行 CLI，它可以执行您登录权限允许的所有操作，包括读取和写入：创建密钥、修改设置、解决事件。CLI 的"确认操作"提示不会对智能体触发，因此 skill 的设计是：在执行任何变更之前，明确说明具体命令并等待您的确认。您就是那道确认步骤。 ```text -您 为什么会话 run-001 失败了？ +you Why did session run-001 fail? -智能体 正在运行：agenteye --json events --session-id run-001 --all - checkout-agent 在第三次工具调用时遇到了 TimeoutError。 +agent Running: agenteye --json events --session-id run-001 --all + The checkout-agent hit a TimeoutError on its third tool call. ``` -读取操作立即完成，所有写入操作都会先等待您确认： +读取操作即时完成，所有写入操作都会暂停等待您确认： ```text -您 给 CI 创建一个只能推送事件的密钥。 +you Give CI a key that can only push events. -智能体 这将创建一个 API 密钥，我将执行： - agenteye keys create ci --add events:add - 确认继续吗？ +agent This creates an API key. I'll run: + agenteye keys create ci --add events:add + OK to proceed? -您 是的 +you yes -智能体 完成。已创建密钥 "ci"，仅具有 events:add 权限。密钥值仅显示一次，请立即保存。 +agent Done. Key "ci" created with events:add only. The secret is shown once, so store it now. ``` -## 相关链接 +## 相关文档 -- [CLI 参考文档](/zh/agenteye/cli)：所有命令、参数和 JSON 格式说明。 -- [面向智能体的 CLI 使用示例](/zh/agenteye/cli-recipes)：可直接复制的 `jq` 模式和退出码处理方法。 -- [CLI 智能体技能](/zh/agenteye/cli-skill)：安装和运行 `agenteye-cli` 技能。 -- [AI 助手](/zh/agenteye/assistant)：仪表板内置分析助手，也是 `agent ask` 的访问目标。 \ No newline at end of file +- [CLI 参考](/zh/agenteye/cli)：所有命令、参数及 JSON 结构说明。 +- [智能体 CLI 使用示例](/zh/agenteye/cli-recipes)：可直接复制使用的 `jq` 模式和退出码处理方法。 +- [CLI 智能体 skill](/zh/agenteye/cli-skill)：安装并运行 `agenteye-cli` skill。 +- [AI 助手](/zh/agenteye/assistant)：控制台内置分析助手，即 `agent ask` 所调用的对象。 \ No newline at end of file diff --git a/docs/zh/agenteye/cli-recipes.mdx b/docs/zh/agenteye/cli-recipes.mdx index f8a55923..62465204 100644 --- a/docs/zh/agenteye/cli-recipes.mdx +++ b/docs/zh/agenteye/cli-recipes.mdx @@ -1,30 +1,30 @@ --- -title: "面向 Agent 的 CLI 实用脚本" -description: "可直接复制粘贴的查询模式和 jq 脚本，将会话、事件和评估数据转化为脚本或 AI Coding Agent 可自动化处理的格式。" +title: "面向 Agent 的 CLI 实用技巧" +description: "可直接复制粘贴的查询模式与 jq 技巧，将 session、事件和评估数据转化为脚本或编码 Agent 可自动化处理的形式。" --- -直接通过脚本或 AI Coding Agent 拉取会话、事件和评估数据（并触发重新评估），输出干净的 JSON 到 stdout，可直接通过管道传入 `jq`。这些脚本将 Failproof AI Observability 的数据转化为终端用户或 AI Coding Agent（Claude Code、Cursor）可以查询和自动化处理的格式，无需点击仪表盘。 +直接在脚本或编码 Agent 中拉取 session、事件和评估数据（并触发重新评估），stdout 输出干净的 JSON，可直接通过管道传入 `jq`。这些技巧将 Failproof AI Observability 的数据转化为终端用户或 AI 编码 Agent（Claude Code、Cursor）可查询和自动化处理的形式，无需在仪表板上点来点去。 -以下模式均可直接复制粘贴，适用于 Failproof AI Observability CLI（`agenteye`）。安装、认证及完整选项列表请参阅 [CLI](/zh/agenteye/cli)；运行 `agenteye -h` 或 `agenteye -h` 查看内置帮助。 +以下模式均可直接复制粘贴，适用于 Failproof AI Observability CLI（`agenteye`）。安装、认证及完整选项列表请参见 [CLI](/zh/agenteye/cli)；运行 `agenteye -h` 或 `agenteye -h` 可查看内置帮助。 -## 基本规则 +## 黄金法则 -1. **全局选项必须放在命令*之前*。** `agenteye --json sessions` 是正确的；`agenteye sessions --json` 则不对。全局选项包括 `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color`。 -2. **解析输出时始终传入 `--json`。** 数据以 JSON 格式输出到 **stdout**；人类可读的状态和错误信息输出到 **stderr**，因此 stdout 保持干净，可直接通过管道传入 `jq`。 -3. **根据退出码而非 stderr 文本做分支判断：** `0` 正常 · `1` 意外错误 · `2` 参数有误 · `3` 无法连接仪表盘 · `4` 未登录或已过期 · `5` 缺少权限 · `6` 资源未找到。 -4. **通过 `-h` 探索命令。** 每个命令都会说明其过滤器、值格式和 JSON 结构。 +1. **全局选项须放在命令*之前*。** `agenteye --json sessions` 是正确的；`agenteye sessions --json` 则不行。全局选项包括 `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color`。 +2. **解析输出时始终传入 `--json`。** 数据以 JSON 格式输出到 **stdout**；人类可读的状态信息和错误信息输出到 **stderr**，从而保持 stdout 干净，便于传入 `jq`。 +3. **根据退出码进行分支判断**，而非 stderr 文本：`0` 成功 · `1` 意外错误 · `2` 参数有误 · `3` 无法连接仪表板 · `4` 未登录或已过期 · `5` 权限不足 · `6` 资源未找到。 +4. **使用 `-h` 探索命令。** 每条命令均记录了其过滤器、值格式和 JSON 结构。 -## 一次性初始化 +## 一次性设置 ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # 避免重复输入 --base-url -agenteye login --email you@example.com # 粘贴邮件中的验证码；有效期约 24h +agenteye login --email you@example.com # 粘贴邮件中的验证码；有效期约 24 小时 ``` ## 执行操作前确认认证状态 -`whoami` 在会话缺失或过期时不会报错，而是返回 `logged_in:false`，因此 Agent 可以安全地探测认证状态。（如果未设置 base URL 或仪表盘不可达，仍可能以非零状态退出。） +`whoami` 在 session 缺失或过期时不会报错，而是返回 `logged_in:false`，因此 Agent 可以安全地探测认证状态。（若未设置 base URL 或仪表板不可达，仍可能以非零状态退出。） ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,43 +32,43 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## 查找失败或低分会话 +## 查找失败或低分 session ```bash -# 过去 24h 中评估出错的会话 +# 过去 24 小时内评估出错的 session agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# 某个 Agent 的 helpfulness 评分 <= 0.5 的评估结果 +# 某个 agent 的 helpfulness 评分 <= 0.5 的评估 agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -评分过滤在 **`evals`** 上进行，而非 `sessions`。`--score KEY:MIN..MAX` 可重复使用，多个条件取 AND；任意一端为可选（`..0.5` 表示 ≤ 0.5，`0.9..` 表示 ≥ 0.9）。每次请求最多可传入 20 个评分过滤条件，超出则返回 HTTP 400。`sessions` 与 `evals` 共享 `--env`、`--status`、`--agent-id`、`--session-id` 以及时间范围过滤器，但不支持 `--score`。 +评分过滤在 **`evals`** 上，而非 `sessions`。`--score KEY:MIN..MAX` 可重复使用，多个条件取 AND；两端均可省略（`..0.5` 表示 ≤ 0.5，`0.9..` 表示 ≥ 0.9）。每个请求最多可传 20 个评分过滤条件，超出则返回 HTTP 400。`sessions` 与 `evals` 共享 `--env`、`--status`、`--agent-id`、`--session-id` 及时间范围过滤器，但不支持 `--score`。 -## 端到端读取一个会话 +## 端到端读取单个 session -没有单独的 `session show` 命令，可将事件轨迹与会话评估结合使用： +没有单独的 `session show` 命令。可将事件轨迹与 session 评估结合使用： ```bash -# 该会话的最新评估结果（状态 + 分数） +# 该 session 的最新评估（状态 + 评分） agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# 该次运行的所有事件（提高 --limit 以获取完整数据） +# 该次运行的所有事件（调大 --limit 可获取完整数据） agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# 会话中仅工具调用的事件（获取原始载荷需加 --full） +# 仅获取 session 中的工具调用（需加 --full 才能获取原始 payload） agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -> **注意：** 默认情况下，`events` 读取的是快速、无载荷的数据流。每个事件包含服务端计算的单行 `summary` 以及 `is_error`、token 计数等标志，但 `payload` 返回为 `{}`。若要获取原始载荷，请添加 `--full`（或 `--fields payload`）。完整数据流在数据量大时速度较慢，因此建议限制范围：将 `--full` 与单个 `--session-id` 配合使用。 +> **注意：** 默认情况下，`events` 读取的是快速、无 payload 的数据流。每个事件包含服务器计算的单行 `summary` 以及 `is_error`、token 计数等标志，但 `payload` 返回为 `{}`。若要获取原始 payload，请添加 `--full`（或 `--fields payload`）。全量数据流在大规模场景下较慢，请保持有界范围：将 `--full` 与单个 `--session-id` 配合使用。 -## 获取全量数据（分页） +## 获取全部数据（分页） -结果按最新优先排序，使用游标分页。 +结果按最新优先排列，使用游标分页。 ```bash -# 一次性获取：以 200 行为一页，最多获取 500 行 +# 一次性获取：以每页 200 条的方式最多获取 500 行 agenteye --json events --session-id run-001 --limit 500 --all > events.json # 手动分页：将 next_cursor 传回 @@ -77,43 +77,43 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## 通过 --fields 精简输出 +## 使用 --fields 精简输出 -限制字段（表格和 `--json` 均适用），减少 Agent 需要读取的内容。 +限制返回的字段（在表格和 `--json` 中均生效），以减少 Agent 需要读取的内容。 ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -未知字段名会被拒绝（退出码 `2`）并附带有效字段列表，这也是探索字段名的便捷方式。 +未知字段名会被拒绝（退出码 `2`），并附带有效字段列表，是一种快速发现字段名的方式。 -## 探索有效过滤器值 +## 发现有效的过滤器值 ```bash -agenteye --json list envs | jq -r '.values[]' # --env 的可用值 +agenteye --json list envs | jq -r '.values[]' # --env 的可选值 agenteye --json list tools | jq -r '.values[]' # 工具名称；以及 agents、models、event_types 等 -agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX 的有效 KEY +agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX 中有效的 KEY ``` ## 选择组织（多租户） -如果你属于多个组织，可在登录时选择当前租户（会保存选择）： +如果您属于多个组织，可在登录时选择当前租户（选择结果会被保存）： ```bash -agenteye login --org acme --email you@corp.com # 登录的同时设置租户 +agenteye login --org acme --email you@corp.com # 在登录的同时设置租户 agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # 单次命令临时覆盖 +agenteye --org globex --json sessions --since 24h # 仅针对单条命令覆盖组织 ``` -多组织登录时若未指定 `--org`，将以非零状态退出并列出可选择的组织。 +多组织登录时若未指定 `--org`，将以非零状态退出并打印可供选择的组织列表。 -## 为 SDK/collector 创建 API 密钥 +## 为 SDK/收集器创建 API 密钥 ```bash -# 密钥仅打印一次，--json 模式下位于 .key 字段 +# 密钥仅打印一次，使用 --json 时位于 .key 字段 key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # 轮换密钥；agenteye keys disable ci-bot --yes 可吊销 +agenteye keys regenerate ci-bot --yes # 轮换密钥；使用 agenteye keys disable ci-bot --yes 可吊销密钥 ``` ## 运行已保存或临时查询 @@ -123,7 +123,7 @@ agenteye --json query run --sql "select count(*) from analytics.events" | jq '.r agenteye --json query run errs --arg prod | jq '.rows' # 已保存的查询 + 位置参数 $1 ``` -## 非交互式故障排查 +## 非交互式处理事故 ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') @@ -132,7 +132,7 @@ agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> **注意：** 在 `--json` 模式下或当 stdin 不是 TTY 时，变更操作会自动跳过确认提示，因此 Agent 不会挂起；在其他情况下可显式传入 `--yes`/`-y` 跳过确认。 +> **注意：** 在 `--json` 模式下或当 stdin 不是 TTY 时，变更操作会自动跳过确认提示，因此 Agent 不会卡住；在其他情况下可显式传入 `--yes`/`-y` 跳过确认。 ## 脚本中的退出码处理 @@ -158,22 +158,22 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}`（`key` 仅显示一次） | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` （`key` 仅显示一次） | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | | create/update/delete（任意） | 资源对象，或删除时返回 `{"deleted": true, "id"}` | -| 失败（任意，使用 `--json`） | stdout 输出 `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | +| 失败（任意，使用 `--json`） | stdout 上输出 `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | -- 每个 **event** 条目（`events`）：`id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`。注意：除非通过 `--full`（或 `--fields payload`）请求完整数据流，否则 `payload` 为 `{}`。 +- 每个 **event** 条目（`events`）：`id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`。注意：除非使用 `--full`（或 `--fields payload`）请求完整数据流，否则 `payload` 为 `{}`。 - 每个 **evaluation** 条目（`evals`）：`id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`。 - 每个 **session** 条目（`sessions`）：`session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`。 -每个命令的 `--fields` 只接受其对应条目的字段名。`sessions` 和 `evals` 的字段集不同，因此对一个命令有效的字段名可能被另一个命令拒绝。 +每条命令的 `--fields` 仅接受其对应条目的字段名。`sessions` 与 `evals` 的字段集不同，因此对某一命令有效的字段名可能会被另一命令拒绝。 -## 下一步 +## 后续步骤 -- [CLI](/zh/agenteye/cli)：安装、认证及每个命令的完整选项参考。 -- [CLI agent skill](/zh/agenteye/cli-skill)：将这些脚本打包为 AI Coding Agent 可加载的技能。 -- [API keys](/zh/agenteye/api-keys)：创建并限定 CLI、SDK 和 collector 认证所用密钥的权限范围。 -- [Python SDK](/zh/agenteye/python-sdk)：向 Failproof AI Observability 发送事件，为上述脚本提供可查询的数据。 \ No newline at end of file +- [CLI](/zh/agenteye/cli)：安装、认证及每条命令的完整选项参考。 +- [CLI agent skill](/zh/agenteye/cli-skill)：将这些技巧打包为编码 Agent 可加载的技能。 +- [API keys](/zh/agenteye/api-keys)：创建密钥并设定作用域，供 CLI、SDK 和收集器进行认证。 +- [Python SDK](/zh/agenteye/python-sdk)：将事件发送到 Failproof AI Observability，为这些技巧提供可查询的数据。 \ No newline at end of file diff --git a/docs/zh/agenteye/cli-skill.mdx b/docs/zh/agenteye/cli-skill.mdx index 75f6023c..8675840c 100644 --- a/docs/zh/agenteye/cli-skill.mdx +++ b/docs/zh/agenteye/cli-skill.mdx @@ -1,159 +1,159 @@ --- -title: "Failproof AI 可观测性 CLI Agent Skill" -description: "向你的编程 Agent 询问「今天有什么问题吗？」，让它直接从你的实时 Failproof AI 可观测性数据中给出答案，无需记忆任何命令。" +title: "Failproof AI 可观测性 CLI Agent 技能" +description: "向你的编程 Agent 询问「今天有什么故障吗？」，让它直接从你的实时 Failproof AI 可观测性数据中给出答案，无需记忆任何命令。" --- -向你的编程 Agent 询问*「今天有什么问题吗？」*，让它直接从你的实时 Failproof AI 可观测性数据中给出答案，无需记忆任何命令。**Failproof AI 可观测性 CLI skill**（`agenteye-cli`）是一种 *Agent Skill*：一个包含说明文件的小型文件夹，供 Claude Code 或 Codex 等编程 Agent 按需加载。它使 Agent 能够通过 [`agenteye` CLI](/zh/agenteye/cli)，以自然语言请求（如*「给 CI 创建一个只能推送事件的密钥」*或*「确认正在触发的告警并将其分配给我」*）来操作你的可观测性部署。 +向你的编程 Agent 询问*「今天有什么故障吗？」*，让它直接从你的实时 Failproof AI 可观测性数据中给出答案，无需记忆任何命令。**Failproof AI 可观测性 CLI 技能**（`agenteye-cli`）是一个 *Agent 技能*：一个小型指令文件夹，供 Claude Code 或 Codex 等编程 Agent 按需加载。它教会 Agent 通过 [`agenteye` CLI](/zh/agenteye/cli) 来响应自然语言请求，例如*「给 CI 创建一个只能推送事件的密钥」*或*「确认正在触发的告警事件并分配给我」*。 -它**不是**服务或独立的二进制文件，无需任何部署。它构建在你已安装的 CLI 之上：Agent 调用 `agenteye --json …`，解析干净的 JSON，然后用自然语言回答你。它能做的一切，你都可以自己输入相同的命令来完成。 +它**不是**一项服务，也不是独立的二进制文件；无需部署任何东西。它建立在你已安装的 CLI 之上：Agent 会调用 `agenteye --json …`，解析返回的 JSON，然后用自然语言回答你。所有它能做的事，你完全可以自己输入相同的命令来完成。 --- -## 与 Failproof AI 可观测性其他接口的关系 +## 与其他 Failproof AI 可观测性界面的关系 -Failproof AI 可观测性提供四种方式访问相同的数据和控制功能，它们相互补充： +Failproof AI 可观测性提供了四种方式来访问相同的数据和控制功能，它们相互补充： -| 接口 | 说明 | 运行环境 | 适用场景 | +| 界面 | 说明 | 运行位置 | 适用场景 | |---|---|---|---| -| **[CLI](/zh/agenteye/cli)** | `agenteye` 的命令与参数参考文档 | 你的终端 | 需要运行或脚本化某个具体命令时 | -| **[CLI 使用示例](/zh/agenteye/cli-recipes)** | 可直接复制的 `jq`/管道模式 | 你的终端 / 脚本 | 将 CLI 集成到自动化流程时 | -| **CLI skill**（本文档） | 基于 CLI 的自然语言入口 | 你工作站上的编程 Agent | 想要直接提问、让 Agent 选择命令时 | -| **[Evaluator skill](/zh/agenteye/evaluator-skill)** | 用于设计和构建评分服务的同类 skill | 你工作站上的编程 Agent | 想要*生成*评估分数而非读取时 | -| **[Python SDK skill](/zh/agenteye/python-sdk-skill)** | 为你的 Agent 添加遥测数据发送能力的同类 skill | 你工作站上的编程 Agent | 想让你的 Agent *生成*本 skill 所读取的事件时 | -| **[仪表盘内置 AI 助手](/zh/agenteye/assistant)** | 内嵌于仪表盘的聊天功能 | 服务端（仪表盘内） | 需要在仪表盘中对数据进行问答时 | +| **[CLI](/zh/agenteye/cli)** | `agenteye` 的命令与参数参考 | 你的终端 | 需要执行或编写特定命令脚本 | +| **[CLI 配方](/zh/agenteye/cli-recipes)** | 可复制粘贴的 `jq`/管道模式 | 你的终端 / 脚本 | 将 CLI 接入自动化流程 | +| **CLI 技能**（本文档） | CLI 的自然语言入口 | 你工作站上的编程 Agent | 只想直接提问，让 Agent 自行选择命令 | +| **[评估器技能](/zh/agenteye/evaluator-skill)** | 用于设计和构建评分服务的姊妹技能 | 你工作站上的编程 Agent | 需要*生成*评估分数，而非读取 | +| **[Python SDK 技能](/zh/agenteye/python-sdk-skill)** | 为你的 Agent 添加遥测埋点的姊妹技能 | 你工作站上的编程 Agent | 需要让你的 Agent *产生*本技能所读取的事件 | +| **[仪表板内置 AI 助手](/zh/agenteye/assistant)** | 嵌入仪表板的对话功能 | 服务器端（仪表板内） | 需要在仪表板中对数据进行问答 | -Skill 本身没有任何特权，它只是将你的语言转化为以你身份运行的 CLI 调用： +该技能本身没有任何特权；它只是将你的话转化为以你身份运行的 CLI 调用： ```mermaid flowchart TD - YOU["你：「确认正在触发的告警」"] --> AGENT["编程 Agent（Claude Code / Codex）
加载 agenteye-cli skill"] + YOU["你：「确认正在触发的告警事件」"] --> AGENT["编程 Agent（Claude Code / Codex）
加载 agenteye-cli 技能"] AGENT --> CLI["agenteye --json incidents ack ..."] - CLI -->|你已认证的 CLI 会话| API["可观测性仪表盘 API"] + CLI -->|你已验证的 CLI 会话| API["可观测性仪表板 API"] ``` -### 与仪表盘内置 AI 助手的重要区别 +### 与仪表板内置 AI 助手的区别：重要说明 -这是两个截然不同的工具，影响范围差异显著： +这是两个不同的工具，操作范围差异显著： -- **仪表盘内置 AI 助手**（[AI 助手](/zh/agenteye/assistant)）是嵌入仪表盘的聊天功能，由 Agent 服务提供支持。它**只读，且写入操作需要明确审批**：可以起草已保存的查询和仪表盘，但每次写入都会暂停并等待你的明确点击确认，且不会执行删除操作。它受 `agent:use` 权限限制，只能查看你当前所在组织的数据。 -- **CLI skill** 在*你的*工作站上运行，在*你的*编程 Agent 内部以**你的身份**驱动 `agenteye` CLI。它可以执行 CLI 的**全部功能，包括变更操作**（创建/轮换/禁用 API 密钥、修改组织设置、解决告警、删除已保存的查询），仅受你的 CLI 登录权限约束。请像对待手动输入这些命令一样谨慎对待它。 +- **仪表板内置 AI 助手**（[AI 助手](/zh/agenteye/assistant)）是嵌入仪表板、由 Agent 服务支持的对话功能。它**只读，且写操作需经审批**：可以起草已保存的查询和仪表板，但每次写入都会暂停等待你的明确点击确认，且永远不会执行删除操作。它受 `agent:use` 权限控制，且只能查看你当前所在组织的数据。 +- **CLI 技能**在*你的*工作站上运行，在*你的*编程 Agent 中驱动 `agenteye` CLI，以**你的身份**执行操作。它可以使用 CLI 的**完整功能，包括变更操作**（创建/轮换/禁用 API 密钥、修改组织设置、解决告警事件、删除已保存查询等），仅受你 CLI 登录权限的约束。请像对待手动输入这些命令一样谨慎对待它。 --- -## 前置条件 +## 前提条件 1. 已安装 **`agenteye` CLI** 并添加到 `PATH`（参见 [CLI](/zh/agenteye/cli) 参考文档：`pipx install agenteye`）。 -2. 已设置**仪表盘 URL**（`AGENTEYE_DASHBOARD_URL`，或由 Agent 传入 `--base-url`）。 -3. 已**登录会话**：需先自行运行 `agenteye login`。Skill **无法**代你完成邮件一次性验证码登录；若会话缺失或过期（CLI 退出码 `4`），它会提示你运行 `agenteye login`。 +2. 已设置**仪表板 URL**（`AGENTEYE_DASHBOARD_URL`，或由 Agent 传入 `--base-url`）。 +3. 已**登录会话**：请先自行运行 `agenteye login`。该技能**无法**替你完成邮件一次性验证码登录；如果会话缺失或已过期（CLI 退出码为 `4`），它会提示你运行 `agenteye login`。 --- ## 获取方式 -Skill 发布于 Failproof AI 的公开 skill 集合中： +该技能发布在 Failproof AI 的公开技能集合中： **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli) -无任何访问限制——该仓库完全公开，skill 本身不需要任何凭证，因为它只是使用*你*登录的会话，通过**公开的** `agenteye` CLI 访问*你的*仪表盘。你无需向任何人申请。 +完全公开，无任何访问限制——仓库是公开的，技能本身也不需要任何凭证，因为它只是使用*你*登录的会话，通过**公开的** `agenteye` CLI 访问*你的*仪表板。无需向任何人申请。 -请注意，它作为独立文件夹发布，**不包含**在 `pipx install agenteye` 包中，请勿在该包中查找。 +注意：它作为独立文件夹发布，**不包含**在 `pipx install agenteye` 包中，请不要在那里查找。 -## 安装 Skill +## 安装技能 -最快捷的方式是使用 [`skills`](https://skills.sh) CLI，它会自动获取文件夹并放置到 Agent 的查找路径中： +最快的方式是使用 [`skills`](https://skills.sh) CLI，它会拉取文件夹并放置到 Agent 的查找路径中： ```bash # Claude Code，仅限当前项目 npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -# 所有项目（安装至 ~/.claude/skills/） +# 所有项目（安装到 ~/.claude/skills/） npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy # 使用 Codex npx skills add FailproofAI/skills --skill agenteye-cli -a codex ``` -管理方式与其他 skill 相同： +然后像管理其他技能一样进行管理： ```bash -npx skills list -a claude-code # 查看已安装的 skill +npx skills list -a claude-code # 查看已安装的技能 npx skills update agenteye-cli # 拉取最新版本 -npx skills remove agenteye-cli # 移除 skill +npx skills remove agenteye-cli # 删除技能 ``` -prefer 手动安装？Agent Skill 本质上只是一个包含 `SKILL.md`（以及可选参考文件）的文件夹，直接复制即可： +倾向于手动安装？Agent 技能就是一个包含 `SKILL.md`（以及可选引用文件）的文件夹，直接复制即可： -- **Claude Code**：将 `agenteye-cli/` 文件夹放入 `~/.claude/skills/`（所有项目）或 `<你的仓库>/.claude/skills/`（仅该仓库）。Claude Code 会自动发现它——通过 `/skills` 列表验证，或直接提问一个与其描述匹配的问题。 -- **Codex（OpenAI）**：Codex 读取相同的 `SKILL.md`。内置的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时 Codex 会自动选择该 skill；否则可通过 `$agenteye-cli` 显式调用。 +- **Claude Code**：将 `agenteye-cli/` 文件夹放入 `~/.claude/skills/`（所有项目）或 `<你的仓库>/.claude/skills/`（仅限该仓库）。Claude Code 会自动发现它——可通过 `/skills` 列表验证，或直接提问一个与其描述匹配的问题。 +- **Codex（OpenAI）**：Codex 读取相同的 `SKILL.md`。内置的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时 Codex 会自动选择该技能；否则可显式调用 `$agenteye-cli`。 --- -## 安全注意事项：Agent 运行 CLI 时变更操作不会出现确认提示 +## 安全须知：Agent 运行 CLI 时变更操作不会提示确认 -> **警告：** 在让 Agent 执行变更操作前，请先阅读本节。 +> **警告：** 在允许 Agent 进行任何更改之前，请先阅读本节。 -`agenteye` CLI 通常会在执行破坏性操作前询问*「确定吗？」*。**当它未连接到终端时（这正是编程 Agent 的运行方式），该确认会被自动跳过；`--json` 参数也会跳过确认。** 因此，安全确认提示对 Agent **不会**触发。 +`agenteye` CLI 通常在执行破坏性操作前会询问*「确定吗？」*。然而，**当它未连接到终端时（编程 Agent 运行它时正是如此），以及使用 `--json` 时，都会自动跳过该确认。** 因此，安全确认提示**不会**在 Agent 运行时触发。 -Skill 的设计已对此进行补偿：它会在执行任何状态变更前，说明将要运行的确切命令，并等待你明确的**确认**。请保持这一规范。当你通过 Agent 操作 Failproof AI 可观测性时，*你*就是确认步骤。需要特别注意的变更类命令： +该技能在设计上已作出补偿：它被指示在任何状态变更前，先说明将要运行的确切命令，并获得你的明确**确认**。请保持这一规范。当你通过 Agent 操作 Failproof AI 可观测性时，*你*就是那个确认步骤。需要重点关注的变更命令包括： - `keys create` / `update` / `disable` / `regenerate` - `users create` / `update` / `disable` / `enable` - `settings set` - `alerts create` / `update` / `delete` / `test` -- 写入类 `incidents` 子命令：`ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` +- 写入型 `incidents` 子命令：`ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe` - `query create` / `update` / `delete` - `agent rename` / `delete` - `orgs switch` -**观测**类命令（`events`、`sessions`、`evals`、`errors`、`list`、`whoami`、`orgs list/current/perms`）均为只读，不会产生任何变更。 +**观察**类操作（`events`、`sessions`、`evals`、`errors`、`list`、`whoami`、`orgs list/current/perms`）全部为只读，不会更改任何内容。 -由于 Agent 以**你的身份**操作，它只能执行你的登录所允许的操作；权限按**组织**级别解析（参见 [API 密钥](/zh/agenteye/api-keys)）。若某个命令超出你的权限，会返回退出码 `5` 并精确说明所缺权限，Agent 可以告诉你需要向管理员申请什么权限，而不是模糊地报错。 +由于 Agent 以**你的身份**行事，它只能执行你的登录权限所允许的操作；权限按**每个组织**解析（参见 [API 密钥](/zh/agenteye/api-keys)）。如果某个命令超出权限范围，会返回退出码 `5` 并附上具体的权限名称，这样 Agent 可以准确告诉你需要向管理员申请什么权限，而不是给出模糊的错误。 --- -## 你可以问它什么 +## 可以提问的内容 -以下是真实的交互示例——先是一次只读查询，然后是一次等待你确认的变更操作： +以下是一次真实的完整交互示例——先是读取操作，然后是需要你确认的变更操作： ```text -you ▸ 最近一天有什么问题吗？ +你 ▸ 过去一天有什么故障吗？ -agent ▸ 正在运行：agenteye --json errors --since 24h --aggregate +Agent ▸ 正在运行：agenteye --json errors --since 24h --aggregate 过去 24 小时内有 3 种错误类型。最多的是 TimeoutError - （18 次，全部发生在 checkout-agent），其次是 RateLimited（5 次）。 + （18 次，全部发生在 checkout-agent 上），其次是 RateLimited（5 次）。 需要查看 TimeoutError 的失败会话吗？ -you ▸ 给 CI 创建一个只能推送事件的密钥。 +你 ▸ 给 CI 创建一个只能推送事件的密钥。 -agent ▸ 这将创建一个 API 密钥。我将运行： +Agent ▸ 这将创建一个 API 密钥。我将运行： agenteye keys create ci --add events:add - 确认继续吗？ + 确认继续？ -you ▸ 是的 +你 ▸ 是的 -agent ▸ 完成。密钥「ci」已创建，仅具有 events:add 权限。 - 密钥只显示一次，请立即保存。我无法再次显示它。 +Agent ▸ 完成。密钥「ci」已创建，权限仅限 events:add。 + 密钥内容只显示一次，请立即保存。我无法再次打印。 ``` -Skill 将每种自然语言意图映射到正确的 `agenteye` 命令，会先查询有效值（`list `、`whoami`）而不是猜测，并在任何变更前说明确切命令。更多示例： +该技能将每个自然语言意图映射到正确的 `agenteye` 命令，先通过 `list `、`whoami` 发现有效值，避免猜测，并在任何变更前说明确切命令。更多示例： -- *「最近 24 小时有什么问题/故障吗？」* → `errors --since 24h --aggregate`，然后给出明细。 -- *「为什么会话 `run-001` 失败了？」* → `events --session-id run-001 --all` + `evals --session-id run-001`。 +- *「过去 24 小时内有什么故障/失败吗？」* → `errors --since 24h --aggregate`，然后给出分类汇总。 +- *「会话 `run-001` 为什么失败？」* → `events --session-id run-001 --all` + `evals --session-id run-001`。 - *「本周质量趋势如何？」* → `evals --aggregate --since 7d`，然后深入查看低分运行。 -- *「给 CI 创建一个只能推送事件的密钥。」* → `keys create ci --add events:add`（说明命令后创建，并捕获一次性密钥）。 -- *「谁有访问权限？将 Dana 设为只读。」* → `users list` → `users update dana@… --permission-set read-only`（向你确认后执行）。 -- *「确认正在触发的告警并分配给我。」* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`。 +- *「给 CI 创建一个只能推送事件的密钥。」* → `keys create ci --add events:add`（先说明命令，确认后创建并捕获一次性密钥）。 +- *「谁有访问权限？将 Dana 设为只读。」* → `users list` → `users update dana@… --permission-set read-only`（与你确认后执行）。 +- *「确认正在触发的告警事件并分配给我。」* → `incidents list --state firing` → `incidents ack ` / `incidents assign you@…`。 -有关这些操作背后的确切命令、参数和 JSON 格式，请参见 [CLI](/zh/agenteye/cli) 参考文档和 [Agent 的 CLI 使用示例](/zh/agenteye/cli-recipes)。 +有关这些操作背后的确切命令、参数和 JSON 结构，请参阅 [CLI](/zh/agenteye/cli) 参考文档和[面向 Agent 的 CLI 配方](/zh/agenteye/cli-recipes)。 --- -## 下一步 +## 后续步骤 -- **[CLI](/zh/agenteye/cli)**：`agenteye` 完整命令与参数参考文档。 -- **[Agent 的 CLI 使用示例](/zh/agenteye/cli-recipes)**：可直接复制的 `jq` 模式和退出码处理方法。 -- **[Evaluator agent skill](/zh/agenteye/evaluator-skill)**：同类 skill，用于构建 `agenteye evals` 读取其分数的评估器。 -- **[Python SDK agent skill](/zh/agenteye/python-sdk-skill)**：同类 skill，用于为 Agent 添加遥测数据发送能力，使 `agenteye` 能够读取相应数据。 -- **[AI 助手](/zh/agenteye/assistant)**：仪表盘内置助手（与本终端 skill 不同）。 -- **[API 密钥](/zh/agenteye/api-keys)**：限定 skill 可执行操作范围的按组织权限模型。 \ No newline at end of file +- **[CLI](/zh/agenteye/cli)**：`agenteye` 的完整命令与参数参考。 +- **[面向 Agent 的 CLI 配方](/zh/agenteye/cli-recipes)**：可复制粘贴的 `jq` 模式和退出码处理。 +- **[评估器 Agent 技能](/zh/agenteye/evaluator-skill)**：姊妹技能，用于构建 `agenteye evals` 所读取分数的评估器。 +- **[Python SDK Agent 技能](/zh/agenteye/python-sdk-skill)**：姊妹技能，用于为 Agent 添加遥测埋点，使其能够发出 `agenteye` 所读取的遥测数据。 +- **[AI 助手](/zh/agenteye/assistant)**：仪表板内置助手（与本终端技能不同）。 +- **[API 密钥](/zh/agenteye/api-keys)**：限定技能操作范围的按组织权限模型。 \ No newline at end of file diff --git a/docs/zh/agenteye/cli.mdx b/docs/zh/agenteye/cli.mdx index f141ed47..ad423c4c 100644 --- a/docs/zh/agenteye/cli.mdx +++ b/docs/zh/agenteye/cli.mdx @@ -1,34 +1,34 @@ --- title: "CLI" -description: "通过终端或脚本驱动所有 Failproof AI Observability 功能，无需往返控制台。" +description: "通过终端或脚本驱动所有 Failproof AI 可观测性功能，无需往返仪表板。" --- -通过终端或脚本驱动所有 Failproof AI Observability 功能，无需往返控制台。`agenteye` CLI 可查询您的数据（会话、事件日志、评估结果）并管理您的组织（API 密钥、用户、设置、告警、事件、已保存查询），非常适合自动化检查、将 Observability 集成到 CI 流程，或让编码智能体检查生产环境。每个命令均支持 `--json` 标志，因此无论是您在终端交互使用，还是编码智能体（Claude Code、Cursor）调用并解析结果，都同样适用。 +通过终端或脚本驱动所有 Failproof AI 可观测性功能，无需往返仪表板。`agenteye` CLI 可以查询你的数据（会话、事件日志、评估结果）并管理你的组织（API 密钥、用户、设置、告警、事件、已保存查询），因此当你需要自动化检查、将可观测性集成到 CI 流程，或让编码代理检查生产环境时，都可以使用它。每个命令都支持 `--json` 标志，无论是你在终端手动操作，还是编码代理（Claude Code、Cursor）执行命令并解析结果，都同样适用。 -使用这一个二进制文件，您可以： +使用这一个工具，你可以： -- **读取数据**：`sessions`、`events`、`evals`、`errors`（按时间、智能体、环境、评分筛选）。 +- **读取数据**：`sessions`、`events`、`evals`、`errors`（按时间、代理、环境、评分筛选）。 - **管理组织**：`keys`、`users`、`settings`、`alerts`、`incidents`。 -- **运行分析**：已保存的 SQL 和临时查询执行器（`query`）。 -- **咨询 AI 助手**：与控制台中相同的只读分析师（`agent`）。 +- **运行分析**：已保存的 SQL 以及临时查询运行器（`query`）。 +- **使用 AI 助手**：与仪表板中相同的只读分析助手（`agent`）。 -> **注意：** 这是 `agenteye` CLI，与采集器守护进程（`agenteye-collector`）是不同的工具。CLI 与您的控制台通信；采集器负责将事件上报到服务器。 +> **注意：** 这是 `agenteye` CLI，与采集器守护进程（`agenteye-collector`）是不同的工具。CLI 与你的仪表板通信；采集器负责将事件发送到服务器。 --- ## 快速开始 -从零到获得第一个结果只需四行命令。将 CLI 指向您的控制台，登录，确认身份，然后拉取最近一天的运行记录： +从零开始，四行命令即可得到第一个结果。将 CLI 指向你的仪表板，登录，确认身份，然后拉取最近一天的运行记录： ```bash pipx install agenteye -agenteye --base-url https://agenteye.example.com login --email you@example.com # 系统会发送6位验证码到您的邮箱 -agenteye whoami # 确认用户 + 当前激活的组织 -agenteye --json sessions --since 24h # 每行对应一次智能体运行，最近24小时 +agenteye --base-url https://agenteye.example.com login --email you@example.com # 邮件发送 6 位验证码 +agenteye whoami # 确认用户及当前组织 +agenteye --json sessions --since 24h # 每行一个代理运行，最近 24 小时 ``` -最后一条命令输出最近会话的 JSON 对象（最新的排在最前，默认最多50条）。可以通过管道传给 `jq` 进行切片处理，或去掉 `--json` 以获得带边框的彩色表格。每行包含运行状态，以及评估器评分后的指标分数（此处为简略版）： +最后一条命令会以 JSON 对象的形式打印最近的会话（最新的排在前面，默认最多 50 条）。可以通过管道传给 `jq` 进行切片处理，或去掉 `--json` 以获得带边框的彩色表格。每行包含该运行的状态，以及评估器对其评分时的指标得分（此处有所省略）： ```json { @@ -48,13 +48,13 @@ agenteye --json sessions --since 24h } ``` -本页其余部分将逐一说明各个环节：[安装](#installation)（隔离安装）、[登录](#authentication)、[配置](#configuration)、所有命令共用的[全局约定](#global-options--conventions)，以及[完整命令参考](#command-reference)。 +本页其余部分将逐一介绍各个环节：[安装](#installation)隔离环境、[登录](#authentication)、[配置](#configuration)、每个命令共用的[全局约定](#global-options--conventions)，以及[完整命令参考](#command-reference)。 --- ## 安装 -CLI 是一个公开的 PyPI 包，名为 **`agenteye`**。建议安装到隔离环境中，以确保其拥有独立的依赖项： +CLI 是一个名为 **`agenteye`** 的公开 PyPI 包。建议在隔离环境中安装，以确保其拥有独立的依赖： ```bash pipx install agenteye @@ -69,44 +69,44 @@ agenteye --version agenteye --help ``` -> **注意：** Failproof AI Observability Python SDK 也使用 `agenteye` 这个发行包名称。使用 `pipx` 或 `uv tool` 安装 CLI（而非 `pip install` 到共享虚拟环境中）可以避免两者冲突。只有在同一环境中未安装 SDK 的情况下，才可以直接使用 `pip install agenteye`。 +> **注意：** Failproof AI 可观测性 Python SDK 也使用 `agenteye` 这一发行包名称。使用 `pipx` 或 `uv tool` 安装 CLI（而非 `pip install` 到共享虚拟环境中），可以避免两者发生冲突。只有在同一环境中未安装 SDK 的情况下，直接 `pip install agenteye` 才不会有问题。 --- ## 认证 -CLI 通过邮件一次性验证码向**控制台**进行身份验证： +CLI 通过邮件一次性验证码向**仪表板**进行认证： ```bash agenteye login --email you@example.com -# 系统会向您的邮箱发送6位验证码，粘贴到提示符处即可。 +# 系统会向你的邮箱发送一个 6 位验证码，粘贴到提示符处即可。 ``` -会话令牌存储在 `~/.agenteye/cli.json` 中（仅您本人可读，权限为 `0600`），默认有效期为 24 小时。过期后，重新运行 `agenteye login` 即可。 +会话令牌存储在 `~/.agenteye/cli.json` 中（仅对你可读，权限为 `0600`），默认有效期为 24 小时。过期后，重新运行 `agenteye login` 即可。 ```bash -agenteye whoami # 显示当前用户、激活的组织及权限 -agenteye logout # 吊销会话并清除存储的令牌 +agenteye whoami # 显示当前用户、活跃组织及权限 +agenteye logout # 吊销会话并清除本机存储的令牌 ``` -`whoami` 在会话缺失或过期时不会报错，而是返回 `logged_in: false`，因此脚本或智能体可以安全地探测认证状态（如果未设置 base URL 或控制台不可达，仍可能以非零状态退出）。 +`whoami` 在会话缺失或过期时不会报错，而是返回 `logged_in: false`，因此脚本或代理可以安全地探测认证状态（如果未设置 base URL 或仪表板不可达，仍然可能以非零状态退出）。 -**要求：** 您的邮箱必须获准登录控制台（请联系您的 Failproof AI Observability 管理员），且控制台必须可通过其 base URL 访问（参见[配置](#configuration)）。如果申请了验证码但未收到，您的邮箱可能尚未开通控制台访问权限。 +**前提条件：** 你的邮箱必须被允许登录仪表板（请联系你的 Failproof AI 可观测性管理员），且仪表板必须可通过其 base URL 访问（参见[配置](#configuration)）。如果请求了验证码但未收到，说明你的邮箱可能尚未开启仪表板访问权限。 --- ## 选择组织（多租户） -如果您的账户属于多个组织，请在**登录时**选择当前激活的组织；该选择会被保存并用于后续所有命令： +如果你的账号属于多个组织，请**在登录时**选择活跃组织；该选择将被保存并用于后续所有命令： ```bash -agenteye login --org acme # 在一步中完成身份验证并设置激活的租户 -agenteye orgs list # 您可访问的组织列表（激活的组织有标记） +agenteye login --org acme # 一步完成认证并设置活跃租户 +agenteye orgs list # 列出你可访问的组织（活跃组织会被标记） agenteye orgs switch globex # 更改已保存的默认组织 -agenteye --org globex sessions # 仅对单条命令覆盖组织 +agenteye --org globex sessions # 仅针对单次命令覆盖组织 ``` -如果您只属于一个组织，系统会自动选中，无需关注 `--org`。如果您属于多个组织但未指定，CLI 会列出所有组织并要求您重新运行并加上 `--org `。激活的组织会随每次请求发送到控制台，权限按**每个组织**单独解析；`agenteye whoami` 会显示激活的组织、您在其中的权限以及您的所有成员资格。 +如果你只属于一个组织，系统会自动选中它，完全不需要使用 `--org`。如果你属于多个组织但未指定，CLI 会列出所有组织并要求你重新运行命令并加上 `--org `。活跃组织会随每个请求一起发送到仪表板，你的权限也会**按组织**进行解析；`agenteye whoami` 会显示活跃组织、你在其中的权限以及所有成员关系。 --- @@ -114,59 +114,59 @@ agenteye --org globex sessions # 仅对单条命令覆盖组织 | 设置项 | 标志 | 环境变量 | 默认值 | |---|---|---|---| -| 控制台 base URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **必填**（无默认值） | -| 激活的组织/租户 | `--org` | `AGENTEYE_ORG` | 登录时选择；保存在 `~/.agenteye/cli.json` | +| 仪表板 base URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **必填**（无默认值） | +| 活跃组织/租户 | `--org` | `AGENTEYE_ORG` | 登录时选择；保存在 `~/.agenteye/cli.json` | | 会话令牌 | `--token` | `AGENTEYE_CLI_TOKEN` | 来自 `~/.agenteye/cli.json` | | JSON 输出 | `--json` | `AGENTEYE_CLI_JSON` | 关闭 | | 跳过 TLS 验证 | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | 关闭（登录时保存） | | 请求超时（秒） | `--timeout` | _（无）_ | 30 | -| 禁用使用遥测 | _（无）_ | `AGENTEYE_ANALYTICS_DISABLED`（或 `DO_NOT_TRACK`） | 遥测目前已禁用；不发送任何数据 | +| 禁用使用遥测 | _（无）_ | `AGENTEYE_ANALYTICS_DISABLED`（或 `DO_NOT_TRACK`） | 遥测当前已禁用；不发送任何数据 | -解析优先级为**标志 → 环境变量 → 配置文件**。没有默认值；您必须将 CLI 指向您的控制台，可以在每条命令中指定（`--base-url https://agenteye.example.com`），也可以通过环境变量设置一次（首次 `login` 后也会自动保存）： +优先级顺序为**标志 → 环境变量 → 配置文件**。没有默认值；你必须将 CLI 指向你的仪表板，可以每次命令时指定（`--base-url https://agenteye.example.com`），也可以通过环境变量一次性设置（首次 `login` 后也会自动保存）： ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` -配置目录遵循 `AGENTEYE_HOME`（与 SDK 和采集器使用相同约定）；如果设置了该变量，`cli.json` 位于 `$AGENTEYE_HOME/cli.json`。 +配置目录遵循 `AGENTEYE_HOME` 约定（与 SDK 和采集器使用相同的约定）；如果设置了该变量，`cli.json` 将位于 `$AGENTEYE_HOME/cli.json`。 -### 自签名或内部 TLS +### 自签名或内部 TLS 证书 -如果您的控制台使用自签名或内部证书通过 HTTPS 提供服务（例如原始负载均衡器主机名），TLS 验证会以 `CERTIFICATE_VERIFY_FAILED` 错误拒绝连接。传入 `--insecure` 可跳过证书验证： +如果你的仪表板使用自签名或内部证书通过 HTTPS 提供服务（例如原始负载均衡器主机名），TLS 验证会因 `CERTIFICATE_VERIFY_FAILED` 错误而失败。使用 `--insecure` 跳过证书验证： ```bash agenteye --base-url https://agenteye.internal --insecure login ``` -**`--insecure` 在登录时会被保存到 `cli.json`**，因此后续命令会自动跳过验证，无需重复传入该标志。传入 `--secure` 可对单次调用进行强制验证，或在下次登录时将验证重新开启并保存。在验证被禁用期间，CLI 在任何联系控制台的命令之前都会向 stderr 打印警告。跳过验证会消除对中间人攻击的防护；请确保在依赖此选项之前，您信任通往控制台的网络路径（VPN、私有子网等）。 +`--insecure` **在登录时会保存到 `cli.json`**，因此后续命令会自动跳过验证，无需重复指定该标志。使用 `--secure` 可进行一次性的验证调用，或在下次登录时将验证状态保存回开启。在验证禁用期间，CLI 会在任何与仪表板通信的命令之前向 stderr 打印警告。跳过验证会去除中间人攻击的防护；在依赖此选项之前，请确保你信任到仪表板的网络路径（VPN、私有子网等）。 --- ## 遥测与隐私 -> **注意：** 目前发布的 CLI **不发送任何使用遥测数据。** 主开关处于关闭状态，无论您的环境如何配置，均不会传输任何数据。以下内容描述了一旦遥测功能启用时的退出机制。 +> **注意：** 当前发布的 CLI **不发送任何使用遥测数据。** 主开关处于关闭状态，无论你的环境如何配置，均不会传输任何数据。以下章节介绍的是退出机制，仅在遥测功能未来启用时适用。 -即使在启用状态下，遥测也**仅为匿名使用分析数据**，绝不包含您的智能体、会话或事件数据： +即使启用，遥测也**仅限匿名使用分析**，绝不包含你的代理、会话或事件数据： -- **您的智能体、会话或事件数据绝不会离开您的基础设施。** 仅上报 CLI 使用情况：命令和子命令名称（例如 `keys create`）、您使用的标志**名称**（绝不包含标志值）、成功/退出状态和耗时，以及变更操作的单次事件（例如 `api_key_created`、`query_run`，仅包含静态名称/枚举和粗略计数）。您的控制台 URL、会话令牌、邮箱、组织 slug、资源 id、SQL、密钥密文和查询过滤器**绝不会被发送**。运营者仅以不透明的内部 id 标识，绝不以邮箱标识。 -- **提前退出**可通过在 CLI 环境中设置 `AGENTEYE_ANALYTICS_DISABLED=1`（CLI 也支持跨工具的 `DO_NOT_TRACK=1` 约定）实现。一旦遥测功能开启，该设置立即生效，因此注重隐私的环境可以永久保持退出状态。 -- 如果遥测功能启用，CLI 会直接向 PostHog（`https://us.i.posthog.com`）发送数据；屏蔽了该主机的机器将静默地不发送任何数据，且 CLI 不受任何影响。 +- **任何代理、会话或事件数据都不会离开你的基础设施。** 仅会上报 CLI 使用情况：命令和子命令名称（例如 `keys create`）、你使用的标志**名称**（绝不包含其值）、成功/退出状态和耗时，以及每次变更操作的事件（例如 `api_key_created`、`query_run`，仅包含静态名称/枚举和粗粒度计数）。你的仪表板 URL、会话令牌、邮箱、组织标识、资源 ID、SQL、密钥机密和查询过滤器**绝不会被发送**。运营商仅通过不透明的内部 ID 进行标识，绝不使用邮箱。 +- **提前退出**可通过在 CLI 环境中设置 `AGENTEYE_ANALYTICS_DISABLED=1` 实现（CLI 同样支持跨工具的 `DO_NOT_TRACK=1` 约定）。一旦遥测功能启用，该设置立即生效，因此注重隐私的环境可以永久保持退出状态。 +- 如果遥测被启用，CLI 会直接向 PostHog（`https://us.i.posthog.com`）发送数据；屏蔽了该主机的机器将静默地不发送任何数据，且 CLI 不受影响。 --- ## 全局选项与约定 -请阅读一遍；以下内容适用于每一条命令。 +请阅读一遍；适用于每条命令。 -- **全局选项必须放在命令之前。** `agenteye --json sessions` 是正确的；`agenteye sessions --json` 会报用法错误。全局选项包括：`--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet` 和 `--no-color`。 -- **`--json` 仅向 stdout 输出纯 JSON，不输出其他内容。** 人类可读的状态行、警告和错误均输出到 **stderr**，因此 `--json` 的 stdout 捕获保持干净，即使显示了状态行也可以直接通过管道传给 `jq`。不使用 `--json` 时，将显示适合人类阅读的带框彩色表格。 -- **通过 `--help` 探索功能。** 每个命令和子命令都支持 `--help`（以及 `-h` 别名）：`agenteye -h`、`agenteye sessions -h`、`agenteye keys create -h`。顶层帮助还列出了退出码和全局选项。没有全局机器可读的接口导出；请使用各命令的 `--help`，以及特定领域的 `agenteye query schema` 和 `agenteye settings schema` 来了解这两个注册表。 -- **确认提示在脚本和智能体中自动跳过。** 创建/更新/删除命令在交互式终端中会提示"确认吗？"，但**在 `--json` 模式下或 stdin 不是 TTY 时会自动跳过该提示**（TTY 是交互式终端会话；管道或 CI 运行器不是），因此脚本和智能体不会挂起。传入 `--yes`/`-y` 可显式跳过提示。由于智能体不会触发提示，智能体应在执行破坏性操作前先与用户确认。 -- **分页：** 结果按最新优先排列，使用游标分页（每页返回一个令牌用于获取下一页）。`--limit N`（别名 `-n`）限制行数，**默认为 50**；`--all` 自动翻页（每次 200 行）**但仍受 `--limit` 限制**，因此单独使用 `--all` 仍会在 50 条时停止。如需完整扫描，请传入较大的显式上限：`--all --limit 1000`。`--page-size N` 控制每次请求的块大小（最大 200）；`--cursor ` 从上一页的 `next_cursor` 恢复。 -- **时间过滤器：** `--since` 接受相对时间窗口：`15m`、`1h`、`6h`、`24h`、`7d` 或 `all`（控制台的预设值）。对于更长或自定义的范围（例如最近 30 天），请使用 `--from`/`--to`：**必须包含 `T` 和时区的** ISO-8601 UTC 时间戳（例如 `2026-06-01T00:00:00Z`），会覆盖 `--since`。以空格分隔或不含时区的值会报用法错误。 -- **`--fields a,b,c`**（适用于 `events`、`sessions`、`evals`、`errors`）将输出限制为指定字段，对表格和 `--json` 均有效。未知字段名称会被拒绝并显示有效列表，这是一种快速探索字段名称的方法。 -- **`--file payload.json`**（或 `--file -` 读取 stdin）用于提供完整的 JSON 请求体，适用于资源结构复杂的情况（`alerts create/update`、`settings set` 和 `users create/update`）。已保存查询的 SQL 使用 `--sql @file.sql` 代替。 -- **多值过滤器** 使用逗号分隔 → 以集合方式匹配（同一过滤器内为并集，跨过滤器为交集）：`--event-type tool_use,tool_result`。Click 选项不支持可变参数，因此 `--add a b` 会出错。请使用 `--add a,b`、重复标志（`--add a --add b`）或加引号（`--add "a b"`）。 +- **全局选项必须放在命令之前。** `agenteye --json sessions` 是正确的；`agenteye sessions --json` 是用法错误。全局选项包括 `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet` 和 `--no-color`。 +- **`--json` 将纯 JSON 打印到 stdout，不输出其他内容。** 人类可读的状态行、警告和错误信息都输出到 **stderr**，因此即使显示了状态行，`--json` 的 stdout 输出仍然干净，可以直接通过管道传给 `jq`。不加 `--json` 则会显示带边框的彩色表格，适合人类阅读。 +- **通过 `--help` 探索命令。** 每个命令和子命令都有 `--help`（以及 `-h` 别名）：`agenteye -h`、`agenteye sessions -h`、`agenteye keys create -h`。顶层帮助还列出了退出码和全局选项。没有全局机器可读的接口清单；请使用各命令的 `--help`，以及 `agenteye query schema` 和 `agenteye settings schema` 分别用于这两个注册表。 +- **脚本和代理会自动跳过确认提示。** 创建/更新/删除命令在交互式终端中会提示"确认吗？"，但**在 `--json` 模式下或 stdin 不是 TTY 时会自动跳过该提示**（TTY 是交互式终端会话；管道或 CI 运行器不是），因此脚本和代理不会挂起。使用 `--yes`/`-y` 可显式跳过提示。由于代理不会触发确认提示，代理在执行破坏性操作前应先与用户确认。 +- **分页：** 结果按最新优先排序，采用游标分页（每页返回一个令牌用于获取下一页）。`--limit N`（别名 `-n`）限制行数，**默认为 50**；`--all` 自动分页（每次 200 行）**直到达到 `--limit`**，因此单独使用 `--all` 仍然会在 50 条时停止。如需完整扫描，请传入较大的显式上限：`--all --limit 1000`。`--page-size N` 控制每次请求的分块大小（最大 200）；`--cursor ` 从上一页的 `next_cursor` 继续。 +- **时间过滤：** `--since` 接受相对时间窗口：`15m`、`1h`、`6h`、`24h`、`7d` 或 `all`（仪表板的预设值）。如需更长或自定义范围（例如最近 30 天），使用 `--from`/`--to`：显式 ISO-8601 UTC 时间戳，**须包含 `T` 和时区**（例如 `2026-06-01T00:00:00Z`），这两个参数会覆盖 `--since`。带空格或不含时区的值属于用法错误。 +- **`--fields a,b,c`**（用于 `events`、`sessions`、`evals`、`errors`）将输出限制为指定字段，对表格和 `--json` 均有效。未知字段名会被拒绝并给出有效字段列表，这也是一种快速发现字段名的方式。 +- **`--file payload.json`**（或 `--file -` 从 stdin 读取）用于为具有复杂结构的资源提供完整 JSON 请求体（适用于 `alerts create/update`、`settings set` 和 `users create/update`）。已保存查询的 SQL 使用 `--sql @file.sql` 替代。 +- **多值过滤器**使用逗号分隔 → 作为集合匹配（同一过滤器内为并集，不同过滤器之间为 AND）：`--event-type tool_use,tool_result`。Click 选项不支持可变参数，因此 `--add a b` 会出错。请使用 `--add a,b`、重复标志（`--add a --add b`），或加引号（`--add "a b"`）。 --- @@ -174,86 +174,86 @@ agenteye --base-url https://agenteye.internal --insecure login ### 最常用的 5 个命令 -日常工作中大多数操作只需用到少数几个读取命令。从这里开始，有需要时再查阅下方完整列表： +日常工作大多通过几个读取命令完成。从这里开始，需要时再查阅下方的完整接口： -| 命令 | 功能 | 示例 | +| 命令 | 功能 | 试一试 | |---|---|---| -| `sessions` | 每行对应一次智能体运行：时间、环境、智能体、状态、最新评分。 | `agenteye --json sessions --since 24h --status error` | -| `events` | 运行内每一步的原始事件流（加 `--full` 获取完整载荷）。 | `agenteye --json events --session-id run-001 --all` | -| `evals` | 评估结果和评分；`--aggregate` 汇总统计。 | `agenteye --json evals --aggregate --since 7d --env prod` | -| `errors` | 仅显示出错事件；`--aggregate` 按类型统计数量。 | `agenteye --json errors --since 24h --aggregate` | -| `list` | 探索有效的过滤器值（智能体、环境、模型……）。 | `agenteye list agents` | +| `sessions` | 每行一个代理运行：时间、环境、代理、状态、最新评分。 | `agenteye --json sessions --since 24h --status error` | +| `events` | 运行内每步的原始事件记录（加 `--full` 查看完整载荷）。 | `agenteye --json events --session-id run-001 --all` | +| `evals` | 评估结果和评分；`--aggregate` 进行汇总。 | `agenteye --json evals --aggregate --since 7d --env prod` | +| `errors` | 仅包含出错的事件；`--aggregate` 按类型统计数量。 | `agenteye --json errors --since 24h --aggregate` | +| `list` | 发现有效的过滤器值（代理、环境、模型等）。 | `agenteye list agents` | ### CLI 的全部功能 -以下是完整功能列表。CLI 共有 **18 个顶层命令**。所有读取命令均支持 `--json` 和上述全局选项；运行 `agenteye -h`（或 ` -h`）可查看任一命令的详细标志列表和 JSON 输出结构。 +以下是完整接口。CLI 共有 **18 个顶层命令**。所有读取命令均支持 `--json` 和上述全局选项；运行 `agenteye -h`（或 ` -h`）可查看任意命令的完整标志列表和 JSON 结构。 -### 身份认证：`login` · `logout` · `whoami` · `orgs` · `version` · `help` +### 身份：`login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash agenteye login --email you@example.com [--org acme] # 邮件一次性验证码；保存会话 agenteye logout # 清除本机保存的会话 -agenteye whoami # 当前用户、激活的组织及权限 -agenteye version # 输出 CLI 版本（与 --version 相同） +agenteye whoami # 当前用户、活跃组织、权限 +agenteye version # 打印 CLI 版本（与 --version 相同） agenteye help # 顶层帮助（与 --help 相同） ``` -`orgs` 用于查看和切换当前激活的租户： +`orgs` 用于查看和切换活跃租户： ```bash -agenteye orgs list # 您的组织列表 + 您在各组织中的角色（激活的已标记） -agenteye orgs switch acme # 更改已保存的激活组织（在 TTY 上省略 slug 可从列表中选择） -agenteye orgs current # 当前激活组织的身份信息 -agenteye orgs perms # 您在当前激活组织中的权限，按资源分组 +agenteye orgs list # 你的组织及在各组织中的角色（活跃组织会被标记） +agenteye orgs switch acme # 更改已保存的活跃组织（在 TTY 中省略 slug 可从列表中选择） +agenteye orgs current # 活跃组织的身份信息 +agenteye orgs perms # 你在活跃组织中的权限，按资源分组 ``` ### 观测（只读）：`events` · `sessions` · `evals` · `errors` · `list` -这些命令均无需确认。共用过滤器：`--session-id`、`--agent-id`、`--env`（**不是** `--environment`）以及时间范围（`--since` / `--from` / `--to`）。 +这些命令无需确认。共用过滤器：`--session-id`、`--agent-id`、`--env`（**不是** `--environment`）以及时间范围（`--since` / `--from` / `--to`）。 ```bash -# events（别名：原始每步事件流），最新优先 +# events（别名：每步原始记录），最新优先 agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' -# sessions：每行对应一次智能体运行（时间/环境/智能体/会话/状态；不支持评分过滤） +# sessions：每行一个代理运行（时间/环境/代理/会话/状态；不支持评分过滤） agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 -# evals：评估结果 + 评分；--score 按指标过滤，--aggregate 汇总统计 +# evals：评估结果 + 评分；--score 按指标过滤，--aggregate 汇总 agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 -agenteye --json evals --aggregate --since 7d --env prod # 状态分布 + 各键评分统计 +agenteye --json evals --aggregate --since 7d --env prod # 状态分布 + 各评分键统计 -# errors：出错事件；--aggregate 统计数量/会话/智能体/最后出现时间 +# errors：出错的事件；--aggregate 统计数量/会话/代理/最后出现时间 agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 -# list：过滤前先探索有效的过滤器值 -agenteye list envs # 还支持：agents event_types score_filters models hooks tools error_types +# list：过滤前先发现有效的过滤器值 +agenteye list envs # 还有：agents event_types score_filters models hooks tools error_types ``` -`--score KEY:MIN..MAX`（适用于 **`evals`**，不适用于 `sessions`）可重复使用，多个条件取交集；任一边界均可省略（`..0.5` 表示 ≤ 0.5，`0.9..` 表示 ≥ 0.9）。每次请求最多支持 20 个评分过滤器。`evals --scores-full` 是**仅适用于人类表格**的显示标志；它会显示所有评分对，而不是前几个加上 `+N` 计数。在 `--json` 模式下无效，`--json` 始终返回完整的评分对象。如需**端到端读取一个会话**，可将事件流与其评估结果结合使用： +`--score KEY:MIN..MAX`（用于 **`evals`**，不适用于 `sessions`）可重复使用并取 AND 关系；任一边界均可省略（`..0.5` 表示 ≤ 0.5，`0.9..` 表示 ≥ 0.9）。每次请求最多 20 个评分过滤器。`evals --scores-full` 是**仅适用于人类表格**的显示标志；它会显示所有评分对，而非前几个加 `+N` 计数。在 `--json` 模式下无效，`--json` 始终返回完整的评分对象。要**端到端读取一个会话**，可将事件记录与其评估结果结合： ```bash agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -agenteye --json evals --session-id run-001 # 对应的评分 + 状态 +agenteye --json evals --session-id run-001 # 其评分 + 状态 ``` ### 管理（需要权限）：`keys` · `users` · `settings` · `alerts` · `incidents` -**`keys`**：API 密钥。密文在本地生成后发送到服务器（服务器仅存储其哈希值），并在创建/重新生成时**仅显示一次**；请立即保存。使用 `--json` 时，密文仅出现在 `key` 字段中。通过**名称**引用。 +**`keys`**：API 密钥。密钥在本地生成，发送给服务器（服务器仅存储其哈希值），并**仅在创建/重新生成时显示一次**；请务必及时保存。使用 `--json` 时，密钥仅出现在 `key` 字段中。通过**名称**引用。 ```bash -agenteye keys list # 先显示激活的密钥，再显示已吊销的 +agenteye keys list # 活跃密钥在前，已吊销的在后 agenteye keys show ci-bot -agenteye keys create ci-bot --add events:read.add # 按需限定权限范围；一次性输出密文 -agenteye keys create ops --permission-set standard --remove queries:run # 从预设开始，再裁剪 +agenteye keys create ci-bot --add events:read.add # 按需限制范围；密钥仅打印一次 +agenteye keys create ops --permission-set standard --remove queries:run # 基于预设再裁剪 agenteye keys update ci-bot --add evaluations:read --yes -agenteye keys regenerate ci-bot --yes # 轮换密文（旧密文立即失效） +agenteye keys regenerate ci-bot --yes # 轮换密钥（旧密钥立即失效） agenteye keys disable ci-bot --yes # 吊销 ``` -权限计算方式为 `(permission-set ∪ --add) − --remove`。令牌格式为 `slug:action`（例如 `events:read`），或 `slug:action.action` 在单个资源上展开多个权限（`events:read.add` → `events:read`、`events:add`）。预设值：`read-only`、`standard`、`admin`。人类专用权限（`keys:update`）不能授予给密钥。 +权限计算规则为 `(permission-set ∪ --add) − --remove`。令牌格式为 `slug:action`（例如 `events:read`）或 `slug:action.action`，用于在一个资源上展开多个操作（`events:read.add` → `events:read`、`events:add`）。预设：`read-only`、`standard`、`admin`。仅限人类使用的权限（`keys:update`）不能授予密钥。 **`users`**：组织成员，通过**邮箱**引用（也接受 UUID id）。 @@ -266,15 +266,15 @@ agenteye users disable dev@corp.com --yes # 有受保护/自身保护 agenteye users enable dev@corp.com ``` -**`settings`**：固定注册表（您只能读取和修改现有键；不能创建新键）。 +**`settings`**：固定注册表（你只能读取和修改已有的键，不能创建新键）。 ```bash -agenteye settings list # 键 · 值 · 类型 · 更新时间（密文已遮蔽） -agenteye settings schema # 每个键的接受规范（类型 · 范围 · 描述） +agenteye settings list # 键 · 值 · 类型 · 更新时间（密钥已遮蔽） +agenteye settings schema # 各键的允许值（类型 · 范围 · 描述） agenteye settings set session_ttl_secs --value 86400 --yes ``` -**`alerts`**：告警定义，通过**名称**引用。`create` 接受位置参数 NAME，以及标志或通过 `--file` 提供的完整 JSON 请求体。 +**`alerts`**：告警定义，通过**名称**引用。`create` 接受位置参数 NAME 以及标志或通过 `--file` 提供的完整 JSON 请求体。 ```bash agenteye alerts list @@ -285,16 +285,16 @@ agenteye alerts test high-errors --yes # 触发测试通 agenteye alerts delete high-errors --yes ``` -**`incidents`**：告警事件，通过 id 引用（支持短 id）。`show` 输出完整的活动日志；在操作前请先阅读。 +**`incidents`**：告警事件，通过 id 引用（支持短 id）。`show` 会打印完整的活动日志；操作前请先查阅。 ```bash -agenteye incidents list --state firing # 还支持：acknowledged, resolved +agenteye incidents list --state firing # 还有：acknowledged, resolved agenteye incidents count agenteye incidents show agenteye incidents ack -agenteye incidents assign you@corp.com # 受托人必须是运营者 +agenteye incidents assign you@corp.com # 受让人必须是运营商 agenteye incidents resolve --yes -agenteye incidents open --alert-id --severity critical # 针对告警手动开启一个事件 +agenteye incidents open --alert-id --severity critical # 针对某个告警手动创建事件 agenteye incidents comment-add "root cause: upstream 5xx" agenteye incidents comment-list ; agenteye incidents comment-delete agenteye incidents subscribe ; agenteye incidents unsubscribe ; agenteye incidents subscribers @@ -302,10 +302,10 @@ agenteye incidents subscribe ; agenteye incidents unsubscribe ; agente ### 分析与助手：`query` · `agent` -**`query`**：针对分析存储的已保存 SQL，以及临时查询执行器。已保存查询通过**名称**引用；SQL 在服务器端验证（仅支持 SELECT/WITH，有语句超时和行数上限）。 +**`query`**：针对分析存储的已保存 SQL 以及临时查询运行器。已保存查询通过**名称**引用；SQL 在服务器端进行验证（仅支持 SELECT/WITH，有语句超时和行数上限）。 ```bash -agenteye query schema [TABLE] # 分析视图的列布局 +agenteye query schema [TABLE] # 分析视图的列结构 agenteye query run --sql "select count(*) from analytics.events" agenteye query run errs --arg prod --limit 100 # 运行已保存查询 + 位置参数 $1 agenteye query list ; agenteye query show errs @@ -313,12 +313,12 @@ agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` -**`agent`**：与内置 **AI 助手**对话（与控制台中相同的只读分析师）。对话通过短 chat-id 引用（支持前缀解析）。 +**`agent`**：与内置 **AI 助手**对话（与仪表板中的只读分析助手相同）。对话通过短 chat-id（支持前缀解析）引用。 ```bash agenteye agent health # AI 助手是否已配置/可访问 -agenteye agent models # 可通过 --model 传入的模型列表（默认已标记） -agenteye agent ask "which agents errored most in the last day?" # 开启对话；输出其短 id +agenteye agent models # 可传给 --model 的模型列表（默认已标记） +agenteye agent ask "which agents errored most in the last day?" # 开启对话；打印其短 id agenteye agent ask --chat "and which tools did they call?" # 继续该对话 agenteye agent chats ; agenteye agent show agenteye agent rename --title "error triage" ; agenteye agent delete @@ -328,23 +328,23 @@ agenteye agent rename --title "error triage" ; agenteye agent delete ## 退出码 -| 代码 | 含义 | +| 码 | 含义 | |---|---| | 0 | 成功 | -| 1 | 意外错误（例如控制台返回 5xx） | +| 1 | 意外错误（例如仪表板返回 5xx） | | 2 | 用法错误（无效参数、未知命令/标志、名称冲突） | -| 3 | 无法连接控制台 | +| 3 | 无法访问仪表板 | | 4 | 未登录或会话已过期；请运行 `agenteye login` | -| 5 | 已认证，但账户缺少所需权限（消息中会指明具体权限） | +| 5 | 已认证，但账号缺少所需权限（错误信息会指出具体权限名） | | 6 | 请求的资源未找到（例如未知的会话或事件 id） | -这些退出码使 CLI 适合脚本化使用：编码智能体可以根据 `4` 提示您重新认证，或根据 `5` 提示缺少的权限。请参阅 [CLI 智能体使用食谱](/zh/agenteye/cli-recipes)，了解退出码处理模式和 JSON 输出结构。 +这些退出码使 CLI 可以安全地用于脚本：编码代理可以根据 `4` 提示用户重新认证，或根据 `5` 提示缺少的权限。有关退出码处理模式和 JSON 输出结构，请参阅 [CLI 代理使用示例](/zh/agenteye/cli-recipes)。 --- -## 下一步 +## 后续步骤 -- **[CLI 智能体使用食谱](/zh/agenteye/cli-recipes)**：可直接复用的查询模式、`jq` 单行命令、`--fields` 投影、退出码处理以及 JSON 输出结构，专为驱动 CLI 的编码智能体编写。 -- **[CLI 智能体技能](/zh/agenteye/cli-skill)**：将此 CLI 打包为可安装的 Claude Code / Codex *技能*，让编码智能体通过自然语言请求驱动 Failproof AI Observability。 +- **[CLI 代理使用示例](/zh/agenteye/cli-recipes)**：可直接复用的查询模式、`jq` 单行命令、`--fields` 投影、退出码处理以及 JSON 输出结构，专为驱动 CLI 的编码代理而写。 +- **[CLI 代理技能](/zh/agenteye/cli-skill)**：将此 CLI 打包为可安装的 Claude Code / Codex *技能*，让编码代理通过自然语言请求驱动 Failproof AI 可观测性。 - **[API 密钥](/zh/agenteye/api-keys)**：`keys create --add …` 背后的权限模型。 -- **[AI 助手](/zh/agenteye/assistant)**：启用 `agent ask` 所使用的助手。 \ No newline at end of file +- **[AI 助手](/zh/agenteye/assistant)**：启用 `agent ask` 所调用的助手。 \ No newline at end of file diff --git a/docs/zh/agenteye/codex-capture.mdx b/docs/zh/agenteye/codex-capture.mdx index 480e4bdb..9fd4402b 100644 --- a/docs/zh/agenteye/codex-capture.mdx +++ b/docs/zh/agenteye/codex-capture.mdx @@ -1,55 +1,55 @@ --- title: "Codex 会话捕获" -description: "将团队本地 OpenAI Codex 会话以普通会话和事件的形式导入 AgentEye，无需改变现有的 Codex 使用方式。" +description: "将团队本地的 OpenAI Codex 会话以普通会话和事件的形式传送至 AgentEye，无需改变任何运行方式。" --- -您的工程师每天都在使用 OpenAI Codex。Codex 会话捕获功能将这些编码会话以普通会话和事件的形式引入 AgentEye，让您可以对其进行搜索、回放，并与其他所有观测数据放在一起进行评估。它与 [Python SDK](/zh/agenteye/python-sdk) 相辅相成：SDK 用于对您自己编写的 Agent 进行埋点，而此功能则捕获团队日常使用 Codex 产生的会话数据——无需任何改动。 +您的工程师每天都在使用 OpenAI Codex。Codex 会话捕获功能将这些编码会话以普通会话和事件的形式引入 AgentEye，让您可以像查看其他所有被观测内容一样，对其进行搜索、回放和评估。它与 [Python SDK](/zh/agenteye/python-sdk) 相辅相成：SDK 用于对您自行编写的 Agent 进行埋点，而此功能则捕获团队日常使用 Codex 的工作内容——无需改变任何运行方式。 -一个轻量级的后台采集器会在 Codex 本地会话记录写入时实时读取，并将其上报至 AgentEye。每台机器只需部署一个采集器，即可同时捕获所有本地 Codex 界面的数据，无需逐一配置。 +一个轻量级的后台采集器会在 Codex 写入本地会话记录时实时读取并传送至 AgentEye。每台机器只需一个采集器，即可同时捕获所有本地 Codex 界面，无需逐一配置。 -同一采集器还支持其他 Agent 的捕获——详见 [OpenClaw](/zh/agenteye/openclaw-capture) 和 [Hermes](/zh/agenteye/hermes-capture)。您可以按需启用，单个采集器能够同时捕获多个来源。 +同一采集器还可捕获其他 Agent——参见 [OpenClaw](/zh/agenteye/openclaw-capture) 和 [Hermes](/zh/agenteye/hermes-capture)。按需启用各项功能；单个采集器可同时捕获多个来源。 --- ## 捕获内容 -所有**本地**运行的 Codex 界面都会生成相同的磁盘会话记录，采集器会统一采集以下来源： +所有**本地**运行的 Codex 界面均会生成相同的磁盘会话记录，采集器会捕获其中的全部内容： - Codex **CLI** 及 `codex exec` - **VS Code / IDE 扩展** -- **桌面应用**（仅限本地执行的会话） +- **桌面应用**（本地运行会话时） -每个 Codex 会话都会成为 AgentEye 中的一个[会话](/zh/agenteye/sessions)；其中的用户消息、助手消息、推理过程、工具调用、工具结果以及 Token 用量将转化为对应的[事件](/zh/agenteye/event-stream)。每个会话的来源界面（CLI、IDE 或桌面应用）均会被记录，便于您加以区分。 +每个 Codex 会话将成为 AgentEye 中的一个[会话](/zh/agenteye/sessions)；其用户和助手消息、推理过程、工具调用、工具结果及 token 用量将转化为对应的[事件](/zh/agenteye/event-stream)。每个会话的来源界面（CLI、IDE 或桌面）均会被记录，方便您加以区分。 -> **云端会话不在捕获范围内。** 桌面应用越来越多地将会话运行在 Codex 云端，本地仅保留元数据，没有可供读取的本地记录。只有本地执行的会话才会被捕获。 +> **云端会话不会被捕获。** 桌面应用越来越多地在 Codex 云端运行会话，本机仅保留其元数据，本地没有可读取的会话记录。仅本地执行的会话会被捕获。 --- -## 启用捕获 +## 开启捕获 -捕获功能默认关闭，需手动启用。请使用具有 `events:add` 权限的 API 密钥（参见 [API 密钥](/zh/agenteye/api-keys)）安装采集器，并开启 Codex 捕获： +捕获功能默认关闭，需手动启用。请使用拥有 `events:add` 权限的 API 密钥（参见 [API keys](/zh/agenteye/api-keys)）安装采集器，并开启 Codex 捕获： ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --codex-enabled ``` -该命令将安装采集器、将其注册为后台服务并立即开始捕获。运行以下命令确认服务正常运行： +该命令将安装采集器、将其注册为后台服务并启动捕获。确认服务正在运行： ```bash agenteye-collector health ``` -首次运行时，现有的 Codex 会话将被一次性回填，此后的新活动将在数秒内实时上报。采集器对 Codex 的本地文件仅执行读取操作，不会对其进行修改、移动或删除，且每个会话只会上报一次，重启后亦然。 +首次运行时，系统会对已有的 Codex 会话进行一次性回填，此后新产生的活动将在数秒内实时传输。采集器仅读取 Codex 的文件，不会对其进行修改、移动或删除；即使服务重启，每个会话也只会被传送一次。 --- -## 数据展示 +## 查看位置 -捕获的会话将出现在 **Sessions** 中，其事件将出现在 **Events** 流中，与您观测的其他 Agent 数据完全一致——因此[会话回放](/zh/agenteye/sessions)、[搜索](/zh/agenteye/queries)、[评估](/zh/agenteye/evaluations)和[告警](/zh/agenteye/alerts)均可正常使用。通过筛选 Codex Agent，可单独查看其数据。 +捕获的会话会显示在**Sessions** 中，其事件显示在 **Events** 流中，与您观测的其他任何 Agent 完全一致——因此[会话回放](/zh/agenteye/sessions)、[搜索](/zh/agenteye/queries)、[评估](/zh/agenteye/evaluations)和[告警](/zh/agenteye/alerts)均可正常使用。通过筛选 Codex Agent 可单独查看这些会话。 --- ## 隐私说明 -Codex 会话记录包含完整的会话内容——包括命令输出、文件内容以及 Codex 读写的所有信息——可能涉及敏感数据。捕获的会话将原样上报，因此请仅在适合将相关内容集中存储至 AgentEye 的机器和团队中启用此功能，并为采集器配置仅限 `events:add` 权限的密钥。数据隔离机制详见[安全说明](/zh/agenteye/security)。 \ No newline at end of file +Codex 会话记录包含完整的会话内容——包括命令输出、文件内容以及 Codex 读取或写入的所有信息——其中可能包含敏感凭证。捕获的会话将原样传送，因此请仅在适合将这些内容集中存储至 AgentEye 的机器和团队中启用捕获功能，并为采集器提供仅限 `events:add` 权限的密钥。有关数据隔离保护的详细信息，请参见 [Security](/zh/agenteye/security)。 \ No newline at end of file diff --git a/docs/zh/agenteye/concepts.mdx b/docs/zh/agenteye/concepts.mdx index 1ec4cb14..09058a08 100644 --- a/docs/zh/agenteye/concepts.mdx +++ b/docs/zh/agenteye/concepts.mdx @@ -1,87 +1,87 @@ --- title: "概念" -description: "Failproof AI 可观测性的术语词汇表——事件、会话、评估、审计、发现与事件单——集中定义于此。" +description: "Failproof AI 可观测性的术语体系——事件、会话、评估、审计、发现与事故——统一定义于此。" --- -本页定义了 Failproof AI 可观测性所使用的术语词汇。如果您在其他指南中遇到不熟悉的术语，可在此查找其定义。无需从头到尾通读：快速浏览即可，或在遇到需要明确含义的词汇时随时跳回查阅。 +本页定义 Failproof AI 可观测性所使用的术语。如果其他指南中出现陌生词汇，可在此查找定义。无需从头到尾通读，浏览即可，或在遇到不熟悉的词时返回查阅。 --- ## 数据模型 **事件（Event）** -最小数据单元。一条事件记录了您的 Agent 执行的单个步骤：一次 `tool_use`、一次 `model_request`、一次 `hook_completed`、一次 `error` 等等。您的 Agent 通过 [Python SDK](/zh/agenteye/python-sdk) 发出事件，这些事件会实时显示在**事件（Events）**页面上。 +最小的数据单元。一个事件记录 agent 执行的单个步骤：`tool_use`、`model_request`、`hook_completed`、`error` 等。Agent 通过 [Python SDK](/zh/agenteye/python-sdk) 发出事件，事件会实时显示在 **Events** 页面。 **会话（Session）** -一次 Agent 运行，以 `session_id` 标识。会话是共享同一 ID 的所有事件的集合，在**会话（Sessions）**页面上汇总为单行，并在详情页上以执行图的形式呈现。会话通常以 `agent_start` 开始，以 `agent_end` 结束。 +一次 agent 运行，由 `session_id` 标识。会话是共享同一 ID 的所有事件的集合，在 **Sessions** 页面汇总为单行记录，并在详情页以执行图的形式呈现。会话通常以 `agent_start` 开始，以 `agent_end` 结束。 **Agent** -一次运行中具名的参与者，以 `agent_id` 标识。一次运行可以涉及多个 Agent：例如一个规划器（planner）派生出一个摘要子 Agent。子 Agent 携带 `parent_id`，正是这个字段使 Failproof AI 可观测性能够在执行图中将它们绘制在各自的泳道上。 +运行中的命名参与者，由 `agent_id` 标识。一次运行可以涉及多个 agent，例如一个规划器（planner）生成一个摘要子 agent。子 agent 携带 `parent_id`，正是这一字段让 Failproof AI 可观测性能够在执行图中将其绘制于独立泳道上。 **环境（Environment）** -标识运行发生位置的标签：`production`、`staging`、`dev`。您在配置 SDK 时设置一次，几乎每个仪表板页面都可以按环境进行筛选。 +标识运行发生位置的标签：`production`、`staging`、`dev`。在配置 SDK 时设置一次，几乎所有仪表板页面均可按环境筛选。 **上下文窗口占用率（Context-window fill）** -模型响应所消耗的上下文窗口百分比。Failproof AI 可观测性会在其识别的模型的 `model_response` 事件上标记该数值，使提示词增长趋势和即将到来的压缩行为直接在事件流中可见。 +某次响应所消耗的模型上下文窗口百分比。Failproof AI 可观测性会将其标注在已识别模型的 `model_response` 事件上，使提示词增长趋势和即将发生的压缩操作在事件流中一目了然。 --- ## 质量 **评估（Evaluation）** -由您运行的评分服务为已完成会话生成的质量分数。评估为选装功能：在接入评估器之前，会话只会被记录，不会被评分。每次评估可以包含多个命名维度的分数（例如 `helpfulness`、`factuality`、`tool_efficiency`），每个维度附带简短的推理说明。请参阅[评估套件（Evaluation suite）](/zh/agenteye/evaluation-suite)。 +由你运行的评分服务对已完成会话生成的质量得分。评估为可选功能：在接入评估器之前，会话仅会被记录而不会被评分。每次评估可包含多个命名维度的得分（例如 `helpfulness`、`factuality`、`tool_efficiency`），每个维度附有简短的推理说明。参见[评估套件](/zh/agenteye/evaluation-suite)。 -**分数键（Score key）** -评估器报告的某一维度名称，例如 `helpfulness`。告警规则和审计可以随时间追踪特定的分数键。 +**得分键（Score key）** +评估器报告的某一维度名称，例如 `helpfulness`。告警规则和审计可以随时间追踪特定得分键。 **评估器（Evaluator）** -您的评分服务。Failproof AI 可观测性会将已完成运行的对话记录以 POST 方式发送给它，并存储其返回的分数。平台不内置默认评估器，评分逻辑由您自行实现。 +你的评分服务。Failproof AI 可观测性会将已完成运行的对话记录以 POST 方式发送至该服务，并存储其返回的得分。平台本身不提供默认评估器，评分逻辑由你自行实现。 --- ## 发现与修复故障 **Hook** -您的 Agent 框架在某个步骤前后运行的守卫或副作用逻辑：内容安全检查、PII 脱敏、预算限制等。Hook 会发出 `hook_triggered` / `hook_completed` 事件，携带 `outcome`（allow、deny、modify），并拥有独立的观测页面。 +Agent 框架在某个步骤前后运行的防护措施或副作用处理逻辑：内容安全检查、PII 脱敏、预算守卫等。Hook 会发出带有 `outcome`（allow、deny、modify）的 `hook_triggered` / `hook_completed` 事件，并拥有专属的观测页面。 **告警规则（Alert rule）** -当指标超过您设定的阈值时触发的规则：错误率、p95 延迟、Token 成本或评估分数。规则触发时，会创建一个事件单并通过您选择的渠道（邮件、Slack、Webhook、仪表板内）发送通知。请参阅[告警（Alerts）](/zh/agenteye/alerts)。 +当指标超过你设定的阈值时触发的规则：错误率、p95 延迟、Token 成本或评估器得分。规则触发时会创建一个事故并通过你选择的渠道（邮件、Slack、Webhook、仪表板内通知）发送通知。参见[告警](/zh/agenteye/alerts)。 -**事件单（Incident）** -告警规则触发时创建的待处理问题。事件单具有生命周期（确认、分配、解决）以及记录每次操作的活动时间线。您也可以手动创建事件单。 +**事故（Incident）** +告警规则触发时创建的待处理问题。事故具有生命周期（确认、分配、解决）和记录每次操作的活动时间线，也可手动创建。 **审计（Audit）** -定期（每小时至每周）运行的调查任务，在*跨会话*的日志中挖掘您尚未编写规则的故障模式：错误聚类、低分、延迟异常值、工具调用循环以及未正常结束的运行。告警监控的是您已知的指标，而审计则告诉您下一步应该关注什么。请参阅[审计（Audits）](/zh/agenteye/audits)。 +定期执行的调查（频率从每小时到每周不等），跨会话挖掘日志中尚未编写规则的故障模式：错误聚类、低分、延迟异常、工具调用循环以及从未完成的运行。告警监控的是你已知的指标，而审计则告诉你下一步应该关注什么。参见[审计](/zh/agenteye/audits)。 **发现（Finding）** -一次审计运行产出的带有排名和证据支撑的结果。发现会描述一种模式，关联到其背后的具体会话，并具有分级处理生命周期（确认、解决、静默、忽略）。Failproof AI 可观测性会对多次运行间的发现进行去重，使已知模式得到更新而不是不断堆积。 +审计运行产生的一条有优先级排序、有证据支撑的结果。发现会命名一种模式，链接到其背后的具体会话，并附有分类处理生命周期（确认、解决、静默、忽略）。Failproof AI 可观测性会在多次运行之间对发现进行去重，使已知模式得到更新而非重复堆积。 **AI 助手（The AI assistant）** -仪表板内的对话工具，能够用自然语言回答关于您的 Agent 的问题，基于您自己的数据。默认为只读模式；其创建的任何内容（已保存的查询、仪表板）均需审批，且无法执行删除操作。请参阅 [AI 助手（AI assistant）](/zh/agenteye/assistant)。 +仪表板内置的对话式助手，能够用自然语言回答关于你的 agent 的问题，并基于你自己的数据进行分析。默认为只读模式；它创建的任何内容（保存的查询、仪表板）均需审批，且永远无法执行删除操作。参见 [AI 助手](/zh/agenteye/assistant)。 --- -## 运行方式 +## 运行架构 -**组织（Organization / 租户）** -隔离的工作空间。一个 Failproof AI 可观测性实例可以托管多个组织，每个组织拥有独立的用户、密钥和数据。所有仪表板 URL 均限定在您的组织标识符下（`//…`）。 +**组织（Organization / Tenant）** +一个隔离的工作空间。一个 Failproof AI 可观测性实例可托管多个组织，每个组织拥有独立的用户、密钥和数据。所有仪表板 URL 均以组织标识符（org slug）为前缀（`//…`）。 **采集器（Collector）** -`agenteye-collector`，运行在每台 Agent 机器上的轻量级守护进程，负责批量处理 SDK 写入磁盘的事件并将其发送到服务器。 +`agenteye-collector`，运行于每台 agent 机器上的轻量级守护进程，负责批量处理 SDK 写入磁盘的事件并将其发送至服务端。 **API 密钥（API key）** -用于向服务器验证客户端身份的作用域令牌。密钥携带细粒度权限（例如，采集器使用 `events:add`，仪表板密钥使用只读作用域）。请参阅 [API 密钥（API keys）](/zh/agenteye/api-keys)。 +用于客户端向服务端进行身份验证的作用域令牌。密钥携带精细化权限（例如采集器使用 `events:add`，仪表板密钥使用只读作用域）。参见 [API 密钥](/zh/agenteye/api-keys)。 -**服务器（Server）** -数据采集和 API 服务。负责采集事件、将运行状态存储到您的数据库中，并提供仪表板和 CLI 服务。 +**服务端（Server）** +数据摄入与 API 服务。负责摄入事件、在数据库中存储运行状态，并为仪表板和 CLI 提供服务。 **仪表板（Dashboard）** -Web 界面。每个页面均限定在某个组织范围内，通过服务器 API 读取数据。 +Web UI。所有页面均以组织为作用域，并通过服务端 API 读取数据。 --- ## 后续步骤 -- [概览（Overview）](/zh/agenteye/overview)：了解各组件如何协同工作。 -- [可观测性（Observability）](/zh/agenteye/observability)：各观测页面（Events、Sessions、Models、Tools、Hooks、Errors）的详细介绍。 \ No newline at end of file +- [概览](/zh/agenteye/overview)：了解这些组件如何协同工作。 +- [可观测性](/zh/agenteye/observability)：观测面板（Events、Sessions、Models、Tools、Hooks、Errors）。 \ No newline at end of file diff --git a/docs/zh/agenteye/dashboards.mdx b/docs/zh/agenteye/dashboards.mdx index 2ba487d6..ebe46bda 100644 --- a/docs/zh/agenteye/dashboards.mdx +++ b/docs/zh/agenteye/dashboards.mdx @@ -1,46 +1,46 @@ --- -title: "仪表板" -description: "将实时智能体数据转化为团队共享的统一视图。" +title: "仪表盘" +description: "将实时 Agent 数据转化为团队共享的统一视图。" --- -将实时智能体数据转化为团队共享的统一视图。将重要查询固定为图表，团队所有人一眼即可看到相同的数据，无需重复执行任何查询。 +将实时 Agent 数据转化为团队共享的统一视图。将重要查询固定为图表，让所有人一眼看到相同的数据，无需重复运行任何查询。 -![基于已保存查询构建的仪表板：每小时事件折线图、按类型划分的错误柱状图、延迟面积图和按模型划分的 token 用量](/agenteye/images/dashboard-fleet.png) +![由已保存查询构建的仪表盘：每小时事件数折线图、按类型分类的错误柱状图、延迟面积图和按模型分类的 Token 用量](/agenteye/images/dashboard-fleet.png) -*一块看板，四个已保存查询：每小时事件数、按类型划分的错误、延迟和按模型划分的 token 用量。* +*一块看板，四个已保存查询：每小时事件数、按类型分类的错误、延迟和按模型分类的 Token 用量。* -## 团队共享同一数据源 +## 让所有人看到同一份真相 -不再需要将截图粘贴到聊天中，也不再需要每天重复运行相同的查询五次。仪表板是一个团队共享的组织级看板，任何团队成员都可以打开查看完全相同的视图。当底层数据发生变化时，图表会随之更新，因此看板始终保持最新状态，无需再为过时的数据争论不休。 +告别在聊天中粘贴截图，也无需每天重复运行同样的查询五次。仪表盘是一块团队共享的组织级看板，任何人打开都能看到完全一致的视图。底层数据变化时，图表随之更新，看板始终保持最新，再也不会为过时数据争论不休。 -上方的集群仪表板是日常运维的良好起点： +上方的 Fleet 仪表盘是日常运营的理想起点： -- **每小时事件数**折线图，用于监控吞吐量并及时发现突发下降 -- **按类型划分的错误**柱状图，让最主要的故障类别一目了然 -- **延迟**面积图，在用户投诉之前提前发现响应变慢的问题 -- **按模型划分的 token 用量**明细，让成本始终可见 +- **每小时事件数**折线图，用于监控吞吐量并及时发现突然下降 +- **按类型分类的错误**柱状图，让最主要的故障类别一目了然 +- **延迟**面积图，在用户投诉之前发现性能下降 +- **按模型分类的 Token 用量**明细，让成本始终在可视范围内 -您可以在 `//dashboards` 找到您的看板。 +你可以在 `//dashboards` 找到你的看板。 ## 固定已保存的查询 -每个图块都从已保存的查询开始。在[查询](/zh/agenteye/queries)库（包含内置预设以及您自定义的查询，覆盖事件和评估数据）中构建并保存您关心的查询，然后将其固定到仪表板，选择最适合数据的图表类型：**折线图**用于展示随时间变化的趋势，**柱状图**用于对比各分类，**面积图**用于展示数据量，**饼图**用于展示占比分布。 +每个图块都从已保存的查询开始。在 [Queries](/zh/agenteye/queries) 库中（包含内置预设和你自己的查询，覆盖事件与评估数据）构建并保存你关心的查询，然后将其以合适的图表类型固定到仪表盘：用**折线图**展示随时间变化的趋势，用**柱状图**对比不同类别，用**面积图**展示数量规模，用**饼图**展示占比分布。 -由于图块本质上就是将已保存的查询渲染为图表，因此无需手动同步任何内容。只需更新一次查询，所有使用该查询的仪表板都会自动更新。 +由于图块本质上就是以图表形式呈现的已保存查询，无需手动保持同步。更新一次查询，所有使用该查询的仪表盘都会自动更新。 ## 关注质量，而不仅仅是数量 -数量告诉您智能体正在忙碌运行，质量才能告诉您它们是否真正完成了工作。将仪表板指向您的[评估分数](/zh/agenteye/evaluations)，即可获得一块追踪运行质量随时间变化的看板，让质量下降以图表曲线低谷的形式呈现，而不是来自用户的意外投诉。 +数量告诉你 Agent 是否繁忙，质量告诉你它们是否真正完成了任务。将仪表盘指向你的[评估分数](/zh/agenteye/evaluations)，即可获得一块持续追踪运行质量的看板，让质量下滑以图表回落的形式呈现，而不是以客户投诉的形式出现。 -![基于已保存评估查询构建的质量仪表板](/agenteye/images/dashboard-quality.png) +![由已保存评估查询构建的质量聚焦仪表盘](/agenteye/images/dashboard-quality.png) -*质量看板将评估分数置于核心位置，与运营数据并排展示。* +*质量看板让你的评估分数始终醒目，与运营数据并排展示。* -将运营看板和质量看板并排放置，团队就拥有了一个统一的地方，既能回答"它运行正常吗？"，也能回答"它表现良好吗？"，而无需任何人重新运行查询。 +将运营看板和质量看板并排放置，团队就有了一个地方同时回答"它是否正常运行？"和"它是否运行良好？"，无需任何人重复运行查询。 ## 相关内容 -- [查询](/zh/agenteye/queries)：构建并保存成为图块的查询。 -- [评估](/zh/agenteye/evaluations)：对运行结果评分，以便随时间追踪质量变化。 -- [告警](/zh/agenteye/alerts)：对任意指标设置阈值并触发通知。 \ No newline at end of file +- [Queries](/zh/agenteye/queries)：构建并保存成为图块的查询。 +- [Evaluations](/zh/agenteye/evaluations)：对运行结果打分，以便随时间追踪质量变化。 +- [Alerts](/zh/agenteye/alerts)：将这些指标的阈值转化为告警通知。 \ No newline at end of file diff --git a/docs/zh/agenteye/error-tracking.mdx b/docs/zh/agenteye/error-tracking.mdx index 7802ac30..3ff1866e 100644 --- a/docs/zh/agenteye/error-tracking.mdx +++ b/docs/zh/agenteye/error-tracking.mdx @@ -1,40 +1,41 @@ --- title: "错误追踪" -description: "在一处查看所有 Agent 产生的失败，并自动归组，让密集的错误爆发呈现为单一问题。" +description: "在一处查看所有 Agent 产生的失败，并将密集爆发的错误合并为单个问题显示。" --- -在一处查看所有 Agent 产生的失败，并自动归组，让密集的错误爆发呈现为单一问题。你只需一键，便能从"某处出现红色报错"直接跳转到确切的出问题运行记录，无需滚动实时日志去寻找。 -![错误页面：顶部是错误随时间分布的直方图，下方是分组的红色错误行，每行都有一键式"+ alert"按钮](/agenteye/images/errors.png) -*错误页面：顶部是错误随时间分布的直方图，重复失败会折叠为每个事件一行。* +在一处查看所有 Agent 产生的失败，并将密集爆发的错误合并为单个问题显示。你只需一键即可从"某处出现红色警报"直达导致问题的具体运行记录，无需在实时日志流中反复翻找。 + +![错误页面：上方是随时间分布的失败直方图，下方是分组的红色错误行，每行都有一个一键"+ alert"按钮](/agenteye/images/errors.png) +*错误页面：随时间分布的失败直方图，重复出现的失败会合并为每个事件一行。* ## 所有失败，自动为你汇总 -Agent 出错时，你不应该还要滚动实时事件流，焦急地等待红色行出现，又担心它们随即消失。**错误**页面替你完成收集工作。它将仪表板中所有标红的内容汇聚到一个统一的分诊界面，让你第一眼看到的是哪里出了问题，而不是去哪里找问题。 +当 Agent 发生故障时，你不应该还要去翻实时事件流，担心红色记录在滚动前被错过。**错误**页面会替你完成汇总工作。它将仪表板上所有会标为红色的内容集中到一个统一的分诊界面，让你第一眼就能看到哪里出了问题，而不是还要去找该看哪里。 -它捕获的不只是显而易见的错误。除了显式的 `error` 事件，Failproof AI Observability 还会把那些悄无声息的失败浮出水面：任何携带失败信息的 `tool_result`、`hook_completed` 或 `agent_end` 都会出现在这里。工具返回了错误，或者 hook 异常退出，即使没有抛出明显的异常，它们也不会再悄悄溜走。 +它捕获的远不止那些显而易见的错误。除了明确的 `error` 事件，Failproof AI Observability 还会呈现那些悄无声息的失败：任何携带失败信息的 `tool_result`、`hook_completed` 或 `agent_end` 都会出现在这里。某个工具返回了错误，或某个 hook 异常退出，都不会再仅仅因为没有抛出响亮的异常就悄悄溜走。 -页面顶部的直方图展示了错误随时间的分布情况。一眼即可判断这是持续的背景噪音，还是几分钟前突然出现的峰值——让你立刻决定是否需要放下手头的工作去处理。 +页面顶部有一张直方图，展示错误随时间的分布情况。一眼扫过，你就能判断这是持续的背景噪音，还是几分钟前突然出现的峰值，从而立刻决定是否需要放下手头的事情。 -与所有观测界面一样，错误页面的数据归属于你的组织，并支持按日期范围、环境、Agent 和会话进行筛选。这意味着你可以从全局列表出发，快速缩小到你真正关心的那一个 Agent 或那一个环境。 +与所有观测界面一样，错误页面的数据范围限定在你的组织内，并支持按日期范围、环境、Agent 和会话进行筛选。这意味着你可以从整个集群的列表出发，快速聚焦到真正关心的某个 Agent 或某个环境。 -## 一个事件，而非数百条相同的行 +## 一个事件，而非数百条相同记录 -一个依赖损坏可能每分钟触发数百次相同的错误。如果原始展示，那就是一大堵几乎相同的日志行，把你真正需要看的信息完全淹没。 +单个损坏的依赖项可能每分钟触发数百次相同的错误。如果原样呈现，就会出现一堵几乎相同的日志墙，将你真正需要看到的信息完全淹没。 -Failproof AI Observability 会将同一会话中相同错误类型的重复失败折叠为一行。一次爆发呈现为一个事件。你数的是问题数，而不是日志行数，关键信号始终置于顶端，不会被自身的数量所淹没。 +Failproof AI Observability 会将同一会话中相同错误类型的重复失败合并为一行。一次密集爆发只显示为一个事件。你统计的是问题数量，而不是日志行数，真正重要的信号会始终置顶，不会被自身的海量输出所淹没。 -## 从"某处出现红色"直达确切事件 +## 从"某处出现红色"直达具体事件 -点击任意一行，即可直接进入该运行的会话，并定位到出错的确切事件。无需复制会话 ID，无需滚动寻找出问题的时刻：你直接就站在那里，完整的执行图一目了然，让你能清楚看到 Agent 在出错前都做了什么。 +点击任意一行，即可直接进入该次运行的会话，并定位到发生失败的确切事件。无需复制会话 ID，无需滚动寻找出错瞬间：你会直接落在问题现场，完整的执行图就在旁边，一眼即可看出 Agent 在出错前做了什么。 -如果你拥有 `alerts:write` 权限，每一行还带有一个 **+ alert** 按钮。点击后，Observability 会打开一条新的告警规则，并预填好内容以捕获相同的失败。你刚刚处理过的事件，下次发生时会主动通知你，而不是再次让你措手不及。 +如果你拥有 `alerts:write` 权限，每一行还会显示一个 **+ alert** 按钮。点击后，Observability 会打开一条新的告警规则，并自动填入捕获该类失败所需的条件。你刚刚处理的事件，下次再发生时就会主动通知你，而不是再次让你措手不及。 -**访问路径：** **错误**页面位于仪表板的观测区域，路径为 `//errors`。 +**访问路径：****错误**页面位于仪表板的观测区，地址为 `//errors`。 ## 相关内容 -- [告警](/zh/agenteye/alerts)：将任何失败转化为通知规则。 -- [事件](/zh/agenteye/incidents)：追踪从触发到解决的完整告警过程。 +- [告警](/zh/agenteye/alerts)：将任意失败转化为通知规则。 +- [事件](/zh/agenteye/incidents)：追踪触发的告警从开启到解决的全过程。 - [会话](/zh/agenteye/sessions)：打开任意错误背后的完整运行记录。 -- [审计](/zh/agenteye/audits)：让 Observability 自动为你发现运行中的失败模式。 \ No newline at end of file +- [审计](/zh/agenteye/audits)：让 Observability 自动在你的运行记录中发现失败模式。 \ No newline at end of file diff --git a/docs/zh/agenteye/evaluation-suite.mdx b/docs/zh/agenteye/evaluation-suite.mdx index 8eb6f0cb..ab7e5612 100644 --- a/docs/zh/agenteye/evaluation-suite.mdx +++ b/docs/zh/agenteye/evaluation-suite.mdx @@ -1,22 +1,22 @@ --- title: "评估套件" -description: "Failproof AI Observability 可以自动对每次已完成的 Agent 运行进行质量评分：您提供一个小型评分服务，Observability 负责其余一切。" +description: "Failproof AI Observability 可自动对每次完成的 Agent 运行进行质量评分：您只需提供一个小型评分服务，其余工作由 Observability 处理。" --- -Failproof AI Observability 可以自动对每次已完成的 Agent 运行进行质量评分：您提供一个小型评分服务，Observability 负责其余一切。使用它来追踪您关心的维度（有用性、工具效率、事实准确性、安全性；由您决定），及早发现回归问题，并一眼比较不同 Agent 或环境的表现。评分功能为可选项：在服务器上设置 `EVALUATOR_ENDPOINT` 之前，该流水线不会执行任何操作。 +Failproof AI Observability 可自动对每次完成的 Agent 运行进行质量评分：您只需提供一个小型评分服务，其余工作由 Observability 处理。使用它来追踪您关心的维度（有用性、工具效率、事实准确性、安全性；由您自定义）、及早发现回归问题，并一目了然地对比不同 Agent 或环境。评分功能为可选项：在服务器上设置 `EVALUATOR_ENDPOINT` 之前，整个流程不会执行任何操作。 -> **注意：** 评分维度由您自行定义。您的评估器可以返回任意数值键；Observability 会存储、趋势分析并展示您返回的所有内容。 +> **注意：** 评分维度由您自定义。您的评估器可以返回任意数值键；Observability 会存储、趋势化并展示您返回的所有内容。 ## 概览 -1. **编写评分器。** 搭建一个小型 HTTP 服务，读取会话转录并返回评分。Observability 附带一个可直接复制使用的参考实现。请参阅[使用 SDK 编写评估器](#writing-an-evaluator-with-the-sdk)。 +1. **编写评分器。** 搭建一个小型 HTTP 服务，读取会话记录并返回评分。Observability 内置了一个可直接复制的参考实现。参见[使用 SDK 编写评估器](#writing-an-evaluator-with-the-sdk)。 2. **将 Observability 指向该服务。** 在服务器进程上设置 `EVALUATOR_ENDPOINT`（以及共享的 `EVALUATOR_TOKEN`）。 -3. **查看评分结果。** 每个已完成的会话都会被自动评分；结果显示在会话详情页、会话列表和已保存的仪表盘上。 +3. **查看评分结果。** 每个已完成的会话都会被自动评分；结果显示在会话详情页、会话列表视图以及已保存的仪表盘上。 -![会话详情视图，右侧边栏显示评估摘要、各维度评分条及推理文本](/agenteye/images/session-detail.png) +![会话详情视图，右侧栏显示评估摘要、各维度评分条和推理文本](/agenteye/images/session-detail.png) -*配置评估器后，每次已完成的运行都会被评分，结果出现在会话的右侧边栏：顶部为摘要，其下为带推理说明的各维度评分条。* +*配置评估器后，每次完成的运行都会被评分，结果显示在会话右侧栏：顶部为摘要，下方为各维度评分条及推理说明。* --- @@ -32,22 +32,22 @@ flowchart LR SRV --> RES["evaluations
terminal results"] ``` -当 Observability SDK 为某个会话发出 `agent_end` 事件时，服务器会调度一次评估。随后它将完整的事件转录以 POST 方式发送到您的评估器服务，评估器可以： +当 Observability SDK 为某个会话发送 `agent_end` 事件时，服务器会调度一次评估。随后将完整的事件记录以 POST 请求发送至您的评估器服务，评估器可以： -- **内联返回结果**，格式为 `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`。结果将追加到该会话的评估时间线中。`reasoning` 和 `summary` 为可选字段。 -- **延迟处理**，返回 `{"status":"pending", "job_id":"abc-123"}`。Observability 随后会轮询 `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123`，直到评估器返回 `{"status":"done", ...}` 或 `{"status":"error", "error":"..."}`。 +- **同步返回结果**，格式为 `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`。结果将追加到该会话的评估时间线。`reasoning` 和 `summary` 为可选字段。 +- **延迟处理**，返回 `{"status":"pending", "job_id":"abc-123"}`。Observability 随后会调用 `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123`，直到您的评估器返回 `{"status":"done", ...}` 或 `{"status":"error", "error":"..."}`。 - 轮询频率按任务设置：`pending` 响应中可包含 `next_poll_secs` 来覆盖默认值；否则 Observability 使用 `GET /config` 返回的 `default_poll_interval_secs`；若未设置则回退到服务器的 `EVALUATOR_POLLING_INTERVAL_SECS`（默认 10 秒）。所有值均被限制在 [1s, 1h] 范围内。 + 轮询频率按任务设置：`pending` 响应中可包含 `next_poll_secs` 来覆盖默认值；否则 Observability 使用 `GET /config` 中的 `default_poll_interval_secs`；若也未设置，则回退到服务器的 `EVALUATOR_POLLING_INTERVAL_SECS`（默认 10 秒）。所有值限制在 [1s, 1h] 范围内。 -从未发出 `agent_end` 的会话（例如 Agent 进程崩溃）也可以被处理：评估器的 `GET /config` 可返回 `{"inactivity_timeout_secs": 1800}`，Observability 将对闲置超过该时长的会话进行评估。将该字段设为 `null` 或省略可禁用此回退机制。 +从未发送 `agent_end`（例如 Agent 进程崩溃）的会话也可被处理：评估器的 `GET /config` 可以返回 `{"inactivity_timeout_secs": 1800}`，Observability 将对闲置时间超过该值的会话进行评估。将该字段设为 `null` 或省略则禁用此回退机制。 -当 `EVALUATOR_ENDPOINT` 未设置时，该流水线完全为空操作。 +当 `EVALUATOR_ENDPOINT` 未设置时，整个流程完全无操作。 -一个会话可以**随时间累积多条终态评估记录**：每个 `agent_end` 事件（以及从仪表盘手动触发的重新评估）都会追加一条新的评估行。这是评估已恢复对话的支持方式：用户结束一个 Agent，稍后返回，发送更多事件，再次结束 Agent，第二次评估将针对完整的更新后转录执行。仪表盘将最新评估显示为主要结果，将之前的评估显示为可折叠的时间线。当某个会话有一次评估正在进行时，该会话后续的 `agent_end` 事件将被忽略；等运行中的评估完成后，下一个 `agent_end` 事件将照常触发新的评估入队。 +一个会话可以随时间累积**多个终态评估**：每次 `agent_end` 事件（以及每次从仪表盘手动触发的重新评估）都会追加一条新的评估记录。这也是评估恢复对话的推荐方式：用户结束一个 Agent，稍后返回并发送更多事件，再次结束 Agent，第二次评估将针对完整更新后的记录进行。仪表盘将最新的评估显示为主要内容，之前的评估则以可折叠时间线的形式呈现。当某个会话有评估正在运行时，该会话后续的 `agent_end` 事件将被忽略；等当前评估完成后，下一个 `agent_end` 事件将照常触发新的评估任务。 -闲置回退机制在已恢复的会话中同样生效：如果在上一次终态评估之后有新事件到达，且会话随后再次闲置超过 `inactivity_timeout_secs`，则会入队一次新的评估。 +非活跃回退机制对恢复的会话同样生效：如果在某次终态评估之后有新事件到达，而会话再次进入闲置状态并超过 `inactivity_timeout_secs`，则会触发新的评估任务。 -暂时性失败（5xx、429、超时、网络错误）将以指数退避方式重试，最多重试 `EVALUATOR_MAX_ATTEMPTS` 次；4xx 响应为终态错误。Observability 支持多实例水平扩展运行，工作会被分区处理，确保同一会话不会被同时分发两次。 +瞬时失败（5xx、429、超时、网络错误）将以指数退避方式重试，最多重试 `EVALUATOR_MAX_ATTEMPTS` 次；4xx 响应为终态错误，不再重试。Observability 支持多实例水平扩展运行，任务会被分区处理，同一会话不会被并发调度两次。 --- @@ -56,18 +56,18 @@ flowchart LR 所有需要认证的路由均使用**Bearer Token 认证**。两端必须配置相同的值： - Observability 服务器：环境变量 `EVALUATOR_TOKEN` -- 评估器服务：以相同方式配置（`agenteye-evaluator` SDK 按惯例读取 `EVALUATOR_TOKEN`） +- 评估器服务：以相同方式配置（`agenteye-evaluator` SDK 按约定读取 `EVALUATOR_TOKEN`） -如果 `EVALUATOR_TOKEN` 未设置，服务器将不发送 `Authorization` 请求头；评估器可以接受匿名请求，这在纯内部网络中是可以接受的，但不建议在公共互联网上使用。 +如果 `EVALUATOR_TOKEN` 未设置，服务器发送请求时不携带 `Authorization` 头；评估器可选择接受匿名请求，这在纯内部网络中可行，但不建议在公网上使用。 ### 评估器必须提供的路由 -| 路由 | 请求体/参数 | 响应 | +| 路由 | 请求体 / 参数 | 响应 | |---|---|---| | `GET /health` | 无 | `{"status":"ok"}`（公开，无需认证） | | `GET /config` | 无 | `{"inactivity_timeout_secs": \| null, "default_poll_interval_secs": \| omitted}` | | `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` 或 `{"status":"pending", "job_id":"..."}` | -| `GET /evaluate/{id}` | 无 | 与 `/evaluate` 相同的响应格式 | +| `GET /evaluate/{id}` | 无 | 与 `/evaluate` 相同的响应结构 | ### 服务器发送的 `EvalRequest` 请求体 @@ -88,7 +88,7 @@ flowchart LR ### 响应格式 -**同步（done）：** +**同步（完成）：** ```json { @@ -102,9 +102,9 @@ flowchart LR } ``` -`reasoning`（每个评分的理由映射）和 `summary`（整体一段式叙述）均为可选字段。`reasoning` 中的键应与 `scores` 中的键对应；仪表盘会在每个评分条下方内联渲染对应条目。只返回 `scores` 的旧版评估器无需修改即可继续使用；`reasoning` 和 `summary` 将显示为 null，对应的 UI 元素将被省略。 +`reasoning`（各评分的推理说明映射）和 `summary`（整体一段式叙述）均为可选字段。`reasoning` 中的键应与 `scores` 中的键对应；仪表盘会在各评分条下方内联渲染每条说明。仅返回 `scores` 的旧版评估器可继续正常使用；`reasoning` 和 `summary` 将读取为 null，对应的 UI 元素将被省略。 -**异步（延迟处理）：** +**异步（延迟）：** ```json { "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 } @@ -112,23 +112,23 @@ flowchart LR `next_poll_secs` 为可选字段；若省略，服务器将回退到评估器 `/config` 中的 `default_poll_interval_secs`，再回退到自身的 `EVALUATOR_POLLING_INTERVAL_SECS` 环境变量。 -**评估器侧终态错误：** +**评估器端终态错误：** ```json { "status": "error", "error": "model service unavailable" } ``` -服务器将任何其他 2xx 响应体视为协议错误，并为该会话记录一条终态 `error`。 +服务器将任何其他 2xx 响应体视为协议错误，并为该会话记录终态 `error`。 --- ## 使用 SDK 编写评估器 -您不必手动实现 HTTP 协议规范。`agenteye-evaluator` Python 包提供了一个带类型的 FastAPI 封装，帮您处理认证、路由以及请求/响应格式。 +您无需手动实现 HTTP 协议。`agenteye-evaluator` Python 包提供了一个类型化的 FastAPI 包装器，为您处理认证、路由以及请求/响应格式。 -Failproof AI Observability 还附带了一个**可直接使用的参考评估器**，它根据转录的结构为 `helpfulness`、`tool_efficiency` 和 `factuality` 进行评分。您可以将其作为起点，替换为自己的逻辑：LLM 裁判、规则引擎，或任何适合您质量标准的方法。 +Failproof AI Observability 还内置了一个**可直接使用的参考评估器**，根据会话记录的结构对 `helpfulness`、`tool_efficiency` 和 `factuality` 进行评分。您可以将其作为起点，替换为自己的逻辑：LLM 评判器、规则引擎，或任何符合您质量标准的方案。 -最小可用评估器示例： +最简可用评估器： ```python import os @@ -149,17 +149,17 @@ def run(req: EvalRequest) -> EvalResponse: `app` 实例可在任何 ASGI 服务器下运行，使用 `uvicorn module:app` 即可启动。 -对于需要延迟执行高开销任务的评估器，可返回 `JobPending` 并注册一个 `@app.job_lookup` 处理器；Observability 服务器会轮询 `GET /evaluate/{job_id}`，直到您返回终态状态或达到 `EVALUATOR_MAX_POLL_DURATION_SECS` 上限（默认 1 小时）。 +对于需要延迟处理耗时任务的评估器，可返回 `JobPending` 并注册 `@app.job_lookup` 处理器；Observability 服务器会轮询 `GET /evaluate/{job_id}`，直到您返回终态状态或超过 `EVALUATOR_MAX_POLL_DURATION_SECS` 上限（默认 1 小时）。 -完整的 API 参考、异步模式和事件模式请参阅 `agenteye-evaluator` SDK 的 README。 +完整的 API 参考、异步模式和事件 schema 文档请参见 `agenteye-evaluator` SDK 的 README。 --- ## 运行您的评估器 -评估器是**您自己的服务** —— Failproof AI Observability 不提供默认评估器，因此您需要在自己的服务基础设施中构建并运行它。它可在任何 ASGI 服务器下运行（例如 `uvicorn my_evaluator:app`）；按照 [HTTP 协议规范](#http-contract) 提供 `/health`、`/config` 和 `/evaluate` 路由，然后将服务器指向该地址（参见[配置服务器](#configuring-the-server)）。 +评估器是**您自己的服务** —— Failproof AI Observability 不提供默认评估器，因此您需要在自己的服务环境中构建和运行它。它可在任何 ASGI 服务器下运行（例如 `uvicorn my_evaluator:app`）；提供 [HTTP 协议规范](#http-contract) 中要求的 `/health`、`/config` 和 `/evaluate` 路由，然后将服务器指向该评估器（参见[配置服务器](#configuring-the-server)）。 -评估器可访问后，`GET /health` 将返回 `{"status":"ok"}`。Agent 完整运行结束后，在服务器上执行 `GET /evaluations` 将返回一条 `status: "done"` 的记录及您的评估器产生的评分。 +评估器可访问后，`GET /health` 将返回 `{"status":"ok"}`。Agent 端到端运行完成后，在服务器上调用 `GET /evaluations` 将返回一条 `status: "done"` 的记录以及您的评估器产生的评分。 --- @@ -169,20 +169,20 @@ def run(req: EvalRequest) -> EvalResponse: | 环境变量 | 说明 | |---|---| -| `EVALUATOR_ENDPOINT` | 评估器的基础 URL（如 `http://evaluator:9000`）。未设置 = 流水线禁用。 | +| `EVALUATOR_ENDPOINT` | 评估器的基础 URL（`http://evaluator:9000`）。未设置时流程禁用。 | | `EVALUATOR_TOKEN` | Bearer Token。必须与评估器服务配置的值相同。 | | `EVALUATOR_WORKERS` | 每个服务器实例的工作任务数（默认 2）。 | -| `EVALUATOR_CLAIM_BATCH` | 每次工作任务轮询时领取的行数（默认 4）。批次**并发**处理；评估器端点的实际并发量为 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`。 | -| `EVALUATOR_POLL_IDLE_SECS` | 当没有待处理评估时，工作任务在两次分发尝试之间的休眠时长（默认 2 秒）。 | -| `EVALUATOR_POLLING_INTERVAL_SECS` | 当响应中的 `next_poll_secs` 和评估器的 `default_poll_interval_secs` 均未设置时，`GET /evaluate/{id}` 轮询频率的最终回退值（默认 10 秒）。 | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | 单次请求超时时间（默认 30000）。 | -| `EVALUATOR_MAX_ATTEMPTS` | 达到此次数的暂时性失败后，结果将记录为终态 `error`（默认 5）。 | -| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` 刷新频率（默认 300）。 | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | 会话在轮询队列中保留的最长实际时间，超出后记录为 `timeout`（默认 3600 秒）。防止评估器持续返回 `pending` 的情况。 | +| `EVALUATOR_CLAIM_BATCH` | 每次工作任务周期领取的行数（默认 4）。批次**并发**处理；评估器端点的实际并发数为 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`。 | +| `EVALUATOR_POLL_IDLE_SECS` | 没有待处理评估任务时，工作任务在两次调度尝试之间的休眠时长（默认 2 秒）。 | +| `EVALUATOR_POLLING_INTERVAL_SECS` | 当响应中既无 `next_poll_secs` 也无评估器 `default_poll_interval_secs` 时，`GET /evaluate/{id}` 轮询频率的最终回退值（默认 10 秒）。 | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | 每个请求的超时时间（默认 30000）。 | +| `EVALUATOR_MAX_ATTEMPTS` | 达到此重试次数后，结果将被记录为终态 `error`（默认 5）。 | +| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` 的刷新频率（默认 300 秒）。 | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | 会话在轮询队列中允许停留的最大实际时间，超时后记录为 `timeout`（默认 3600 秒）。防止评估器持续返回 `pending` 而无终态。 | -要开启自动评分，在服务器上同时设置 `EVALUATOR_ENDPOINT` 和 `EVALUATOR_TOKEN`，然后重启服务器使配置生效。未设置 `EVALUATOR_ENDPOINT` 时，流水线保持空操作状态。 +要开启自动评分，请在服务器上同时设置 `EVALUATOR_ENDPOINT` 和 `EVALUATOR_TOKEN`，然后重启服务器以使配置生效。未设置 `EVALUATOR_ENDPOINT` 时，整个流程保持无操作状态。 -上述调优参数均为可选项；仅在需要覆盖默认值时才在服务器上设置对应的环境变量。 +上述调优参数均为可选项；仅当需要覆盖默认值时，才在服务器上设置对应的环境变量。 --- @@ -190,48 +190,48 @@ def run(req: EvalRequest) -> EvalResponse: | 方法 | 路径 | 所需权限 | 用途 | |---|---|---|---| -| `GET` | `/evaluations` | `evaluations:read` | 查询终态结果。支持 `session_id`、`agent_id`、`environment`、`status`（`done`/`error`/`timeout`）、`ts_from`、`ts_to`、`cursor`、`limit`、`score_filters`、`latest_per_session` 参数。`limit` 默认为 50，上限为 200（注意与 `/events` 不同，后者上限为 1000）。`environment` 接受逗号分隔的列表（如 `environment=prod,staging`）；单个值同样有效。`latest_per_session=true` 时，响应中每个 `session_id` 最多返回一条记录（按 `completed_at` 最新的一条），供会话列表页将会话评估时间线折叠为当前主要结果使用。默认为 false（返回完整历史记录）。 | -| `GET` | `/evaluations/aggregate` | `evaluations:read` | 对过滤后的数据片段进行评估健康状况汇总：总数量、done/error/timeout 分类统计、各评分键的统计数据（count/avg/min/max/p50，针对任意 `scores` 键），以及按时间分桶的趋势时间线。接受与 `/evaluations` **相同的过滤参数**，额外支持 `featured_keys`（要趋势展示的评分键 CSV）和 `latest_per_session`。为仪表盘功能提供数据；指标对整个匹配集进行精确计算，不进行采样。 | -| `GET` | `/evaluations/environments` | `evaluations:read` | 从 `evaluations` 表中获取不重复的 environment 值。用于填充评估数据范围内的过滤下拉菜单。 | -| `GET` | `/evaluation-jobs` | `evaluations:read` | 查看进行中的评估。支持按 `status`（`pending`/`polling`）过滤。 | -| `GET` | `/events` | `events:read` | 流式获取会话的原始事件。支持 `session_id`、`agent_id`、`event_type`（CSV）、`environment`（CSV）、`ts_from`、`ts_to`、`cursor`、`limit` 和 `order` 参数。`order` 为 `desc`（最新优先，默认值）或 `asc`（最旧优先）；无法识别的值将回退为 `desc`。通过响应中的 `next_cursor`（事件 id）进行游标分页：将其作为 `cursor` 传回以获取下一页；`asc` 模式下下一页为该 id 之后的事件，`desc` 模式下为该 id 之前的事件。`limit` 默认为 50，上限为 1000。 | -| `GET` | `/sessions/:session_id/export` | `events:read` | 返回评估器将接收到的该会话的精确 JSON 请求体，以可下载附件形式提供，文件名为 `session-.json`。适用于将生产会话通过 `agenteye-evaluator` 进行离线测试回放。字节内容与评估流水线实际发送的完全一致。 | -| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | 为会话入队一次新的评估；无论是否存在之前的评估均可执行。新结果将**追加**到会话的评估时间线，而不是覆盖之前的结果，因此历史评分仍然可见。入队成功返回 `202`，会话不存在返回 `404`，已有评估正在进行中返回 `409`。适用于部署新评估器后，或对从未发出 `agent_end` 的会话重新评估。 | +| `GET` | `/evaluations` | `evaluations:read` | 查询终态结果。支持 `session_id`、`agent_id`、`environment`、`status`（`done`/`error`/`timeout`）、`ts_from`、`ts_to`、`cursor`、`limit`、`score_filters`、`latest_per_session` 参数。`limit` 默认 50，上限 200（注意与 `/events` 不同，后者上限为 1000）。`environment` 支持逗号分隔的列表（如 `environment=prod,staging`）；单个值仍然有效。设置 `latest_per_session=true` 时，响应中每个 `session_id` 至多返回一条记录（按 `completed_at` 取最新），供会话列表页将会话评估时间线折叠为当前主要评估使用。默认为 false（返回完整历史记录）。 | +| `GET` | `/evaluations/aggregate` | `evaluations:read` | 返回指定筛选范围的评估健康汇总：总数、done/error/timeout 分布、各评分键的统计数据（针对任意 `scores` 键的 count/avg/min/max/p50），以及按时间分桶的趋势数据。接受与 `/evaluations` 相同的过滤参数，另加 `featured_keys`（趋势展示的评分键 CSV）和 `latest_per_session`。为仪表盘功能提供数据支持；指标基于整个匹配集精确计算，而非采样。 | +| `GET` | `/evaluations/environments` | `evaluations:read` | 返回 `evaluations` 表中的不重复环境值，用于填充评估数据范围内的过滤下拉框。 | +| `GET` | `/evaluation-jobs` | `evaluations:read` | 查看正在运行的评估任务。支持按 `status`（`pending`/`polling`）过滤。 | +| `GET` | `/events` | `events:read` | 流式获取会话的原始事件。支持 `session_id`、`agent_id`、`event_type`（CSV）、`environment`（CSV）、`ts_from`、`ts_to`、`cursor`、`limit` 和 `order` 参数。`order` 为 `desc`（最新优先，默认）或 `asc`（最旧优先）；不识别的值回退到 `desc`。通过响应中的 `next_cursor`（事件 ID）进行游标分页：将其作为 `cursor` 传回以获取下一页；`asc` 时获取该 ID 之后的事件，`desc` 时获取该 ID 之前的事件。`limit` 默认 50，上限 1000。 | +| `GET` | `/sessions/:session_id/export` | `events:read` | 返回评估器将收到的该会话的完整 JSON 请求体，以可下载附件形式提供，文件名为 `session-.json`。适用于将生产会话离线导入 `agenteye-evaluator` 进行回放测试。字节内容与评估器流程发送的完全一致。 | +| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | 为会话触发新的评估任务；无论之前是否存在评估记录均可执行。新结果将**追加**到会话的评估时间线，而不会覆盖之前的记录，历史评分仍可查看。成功触发返回 `202`，会话不存在返回 `404`，已有评估正在运行返回 `409`。适用于部署新评估器后，或对从未发送 `agent_end` 的会话进行评估。 | ### 按评分范围过滤：`score_filters` -`GET /evaluations` 接受可选的 `score_filters` 参数，用于按 `scores` 对象中的数值缩小结果范围。该参数为逗号分隔的 `key:min..max` 条目列表；上下界均可省略。多个条目以逻辑 AND 组合。指定键不存在或非数值的行将被排除。单次请求最多可包含 20 条过滤条目；超出后返回 HTTP 400。 +`GET /evaluations` 接受可选的 `score_filters` 参数，用于按 `scores` 对象中的数值缩小结果范围。该参数为逗号分隔的 `key:min..max` 条目列表；上下限均可省略。多个条目以逻辑 AND 组合。指定键不存在或非数值的行将被排除。单个请求最多携带 20 个过滤条目；超出则返回 HTTP 400。 示例： ```text # helpfulness 在 [0.5, 0.8] 范围内 GET /evaluations?score_filters=helpfulness:0.5..0.8 -# tool_efficiency 最高为 0.3（无下限） +# tool_efficiency 最多为 0.3（无下限） GET /evaluations?score_filters=tool_efficiency:..0.3 # helpfulness >= 0.5 且 factuality >= 0.9 GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. ``` -每条 `/evaluations` 响应对象包含以下字段： +每个 `/evaluations` 响应对象包含以下字段： | 字段 | 类型 | 说明 | |---|---|---| -| `evaluation_id` | string (UUID) | 此终态评估的规范标识符。每次终态评估都会获得一个新的 UUID；单个会话可包含多条评估。 | -| `id` | string (UUID) | 向后兼容别名，与 `evaluation_id` 值相同。 | -| `session_id` | string | 此评估所针对的会话。一个会话在时间线中可包含多条评估。 | +| `evaluation_id` | string (UUID) | 该终态评估的唯一标识符。每次终态评估生成一个新的 UUID；单个会话可包含多个。 | +| `id` | string (UUID) | 向后兼容别名，值与 `evaluation_id` 相同。 | +| `session_id` | string | 该评估对应的会话。一个会话的时间线中可包含多个评估。 | | `agent_id` | string | 标识产生该会话的 Agent。 | -| `environment` | string | 从会话中复制的环境标签。 | -| `status` | enum | `"done"`、`"error"` 或 `"timeout"` 之一。 | +| `environment` | string | 从会话复制的环境标签。 | +| `status` | enum | 取值为 `"done"`、`"error"` 或 `"timeout"` 之一。 | | `scores` | object \| null | 评估器返回的评分。 | -| `reasoning` | object \| null | 评估器返回的可选逐评分理由映射。键通常与 `scores` 中的键对应。仪表盘在每个评分条下方渲染各条目。 | -| `summary` | string \| null | 评估器返回的可选整体一段式叙述。仪表盘在各评分详情上方将其渲染为评估的主要标题。 | -| `error` | string \| null | 仅在 `"error"` / `"timeout"` 时填充。 | -| `attempt_count` | integer | 分发尝试次数（≥ 1）。 | +| `reasoning` | object \| null | 评估器返回的可选各评分推理说明映射。键通常与 `scores` 中的键对应。仪表盘在各评分条下方渲染每条说明。 | +| `summary` | string \| null | 评估器返回的可选整体一段式叙述。仪表盘将其渲染在各评分明细上方作为评估的主要展示内容。 | +| `error` | string \| null | 仅在 `"error"` / `"timeout"` 状态时填充。 | +| `attempt_count` | integer | 调度尝试次数（≥ 1）。 | | `duration_ms` | integer \| null | 最后一次尝试的耗时。 | -| `completed_at` | string (ISO 8601 UTC) | 终态结果的记录时间。结果按 `completed_at` 排序（最新优先）。 | -| `created_at` | string (ISO 8601 UTC) | 与 `completed_at` 时间戳相同（写入后不可修改）。 | +| `completed_at` | string (ISO 8601 UTC) | 终态结果记录的时间。结果按 `completed_at` 排序（最新优先）。 | +| `created_at` | string (ISO 8601 UTC) | 与 `completed_at` 携带相同的时间戳（一次性写入语义）。 | --- @@ -239,62 +239,62 @@ GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9.. | 权限 | 授予能力 | |---|---| -| `evaluations:read` | 列出评估结果、在仪表盘中查看评分，以及加载仪表盘健康指标。 | -| `evaluations:trigger` | 通过 `POST /sessions/:session_id/re-evaluate` 或仪表盘的重新评估按钮手动为会话入队评估。 | -| `dashboards:read` | 查看已保存的仪表盘（同时需要 `evaluations:read` 以加载指标）。 | +| `evaluations:read` | 查看评估结果列表、在仪表盘中查看评分以及加载仪表盘健康指标。 | +| `evaluations:trigger` | 通过 `POST /sessions/:session_id/re-evaluate` 或仪表盘的重新评估按钮手动触发会话评估。 | +| `dashboards:read` | 查看已保存的仪表盘（同时需要 `evaluations:read` 以加载其指标）。 | | `dashboards:write` | 创建和编辑仪表盘。 | | `dashboards:delete` | 删除仪表盘。 | -引导管理员（`ADMIN_KEY`、`ADMIN_EMAIL`）会自动获得上述所有权限。 +引导管理员（`ADMIN_KEY`、`ADMIN_EMAIL`）自动获得上述所有权限。 --- ## 查看结果 -- **`/sessions/`**：事件时间线 + 右侧边栏，显示会话的评分及分发尝试中的任何错误。如果您的密钥具有 `evaluations:trigger` 权限，导出按钮旁会出现**重新评估**按钮，适用于从未发出 `agent_end` 的会话，或部署新评估器后刷新评分。仪表盘会轮询新结果，并在结果就绪时更新右侧边栏。 -- **`/sessions`**：可过滤的会话列表；评分列一眼显示每个会话的评估状态和评分。 +- **`/sessions/`**：事件时间线 + 右侧栏显示会话评分及调度尝试中的任何错误。如果您的密钥具有 `evaluations:trigger` 权限，导出按钮旁边将显示**重新评估**按钮，适用于从未发送 `agent_end` 的会话，或在部署新评估器后刷新评分。仪表盘会轮询新结果，并在结果到达时更新右侧栏。 +- **`/sessions`**：可过滤的会话列表；评分列一目了然地展示每个会话的评估状态和评分。 - **`/dashboards`**：已保存的评估健康视图（参见下方[仪表盘](#dashboards)）。 ![会话列表，显示每个会话的评估状态标签和颜色编码的评分徽章（helpfulness、factuality、tool_efficiency、safety、coherence）](/agenteye/images/sessions-list.png) -*会话列表一眼显示每次运行的评估状态和评分；红/黄/绿徽章让低评分一目了然。* +*会话列表一目了然地展示每次运行的评估状态和评分；红/黄/绿徽章使低分一眼可见。* --- ## 仪表盘 -**仪表盘**页面（`/dashboards`）允许您将一组评估过滤条件保存为命名的可复用视图，并一眼了解该数据片段的评估状况。仪表盘在**整个组织内共享**；所有具有 `dashboards:read` 权限的人都能看到相同的仪表盘集合。 +**仪表盘**页面（`/dashboards`）允许您将一组评估过滤条件保存为命名的可复用视图，并一目了然地查看该评估切片的运行状况。仪表盘**在整个组织内共享**；所有拥有 `dashboards:read` 权限的用户都能看到同一组仪表盘。 每个仪表盘固定以下配置： -- **过滤条件**：与会话页面相同的控件：环境、状态、Agent、滚动时间窗口和评分范围过滤器（`key:min..max`）。 -- **显示配置**：要重点展示的评分键、绿/黄/红健康阈值、要显示的面板，以及是否折叠为每个会话的最新评估。 +- **过滤条件**：与会话页面相同的控制项：环境、状态、Agent、滚动时间窗口，以及评分范围过滤条件（`key:min..max`）。 +- **展示配置**：需要突出显示的评分键、绿/黄/红健康阈值、要显示的面板，以及是否折叠为每个会话的最新评估。 -每张卡片显示匹配会话数量、done/error/timeout 分类统计、每个重点评分的平均值，以及小型趋势迷你图。打开仪表盘可查看全尺寸面板；**"在会话中打开"**可跳转至预先过滤到该数据片段的会话页面。指标通过 `GET /evaluations/aggregate` 在服务端对整个匹配集进行精确计算，结果为精确值而非采样值。 +每张卡片显示匹配会话数、done/error/timeout 分布、各重点评分的平均值，以及小型趋势迷你图。打开仪表盘可查看全尺寸面板；**"在会话中打开"**将跳转到会话页面，并预先应用该切片的过滤条件。指标由服务器端基于整个匹配集计算（通过 `GET /evaluations/aggregate`），因此数字是精确值而非采样值。 -![评估健康仪表盘，显示每个评估维度的平均评分条、工具正常/错误分类统计、热门工具及每小时事件趋势](/agenteye/images/dashboard-quality.png) +![评估健康仪表盘，展示各评估维度的平均评分条、工具成功/失败分布、热门工具和每小时事件数趋势](/agenteye/images/dashboard-quality.png) -**权限：** 查看需要同时具备 `dashboards:read` 和 `evaluations:read`；创建和编辑需要 `dashboards:write`；删除需要 `dashboards:delete`。引导管理员会自动获得所有这些权限。 +**权限：** 查看需要同时具备 `dashboards:read` 和 `evaluations:read`；创建和编辑需要 `dashboards:write`；删除需要 `dashboards:delete`。引导管理员自动获得所有这些权限。 --- ## 故障排查 -**会话存在但未创建任何评估。** 确认服务器进程上已设置 `EVALUATOR_ENDPOINT`，服务器和评估器使用相同的 `EVALUATOR_TOKEN` 值，且评估器的 `/health` 端点可从服务器访问。未设置 `EVALUATOR_ENDPOINT` 时，流水线为空操作。 +**会话存在但未创建任何评估。** 请确认服务器进程上已设置 `EVALUATOR_ENDPOINT`，服务器和评估器使用相同的 `EVALUATOR_TOKEN` 值，以及评估器的 `/health` 端点可从服务器访问。未设置 `EVALUATOR_ENDPOINT` 时整个流程为无操作状态。 -**进行中的评估积压。** 查询 `GET /evaluation-jobs` 查看进行中的队列。检查每条记录的 `attempt_count`、`next_attempt_at` 和 `last_error`。常见原因：评估器服务不可达或返回 5xx（以退避方式重试）、`EVALUATOR_TOKEN` 错误（401 为终态错误），或异步评估器无限期返回 `pending`（参见下文）。 +**进行中的评估任务积压。** 通过 `GET /evaluation-jobs` 查看当前队列。检查每行的 `attempt_count`、`next_attempt_at` 和 `last_error`。常见原因：评估器服务不可达或返回 5xx（以退避方式重试）、`EVALUATOR_TOKEN` 错误（401 为终态错误）、或异步评估器持续返回 `pending`（见下文）。 -**会话已完成但无终态评估。** 查询 `GET /evaluation-jobs?status=polling`；结果可能仍在进行中。如果某个任务卡在 `pending` 状态，说明服务器无法访问评估器；检查评估器是否正常运行且 `EVALUATOR_TOKEN` 是否匹配。 +**会话已完成但无终态评估。** 查询 `GET /evaluation-jobs?status=polling`；结果可能仍在处理中。如果某个任务卡在 `pending` 状态，说明服务器无法访问评估器；请检查评估器是否正常运行以及 `EVALUATOR_TOKEN` 是否匹配。 -**`HTTP 401 from evaluator: invalid bearer token`。** 服务器上的 `EVALUATOR_TOKEN` 与评估器服务配置的值不匹配。两者必须完全相同。 +**`HTTP 401 from evaluator: invalid bearer token`。** 服务器上的 `EVALUATOR_TOKEN` 与评估器服务配置的值不匹配。两者必须完全一致。 -**异步评估器持续返回 `pending`。** 服务器会轮询 `GET /evaluate/{job_id}`，直到评估器返回 `done` 或 `error`，或达到 `EVALUATOR_MAX_POLL_DURATION_SECS` 上限（默认 1 小时）。超出上限后，评估将被记录为 `timeout` 并从进行中的队列中移除。如果您的评估器合理地需要超过默认时长，请适当增大 `EVALUATOR_MAX_POLL_DURATION_SECS`。 +**异步评估器持续返回 `pending`。** 服务器会持续轮询 `GET /evaluate/{job_id}`，直到评估器返回 `done` 或 `error`，或超过 `EVALUATOR_MAX_POLL_DURATION_SECS`（默认 1 小时）上限。达到上限后，评估结果被记录为 `timeout` 并从进行中队列中移除。如果您的评估器确实需要超过默认时间，请适当提高 `EVALUATOR_MAX_POLL_DURATION_SECS` 的值。 --- ## 后续步骤 -- [评估器 Agent 技能](/zh/agenteye/evaluator-skill)：让编码 Agent 针对真实会话设计您的评估维度并为您构建该服务。 -- [Python SDK](/zh/agenteye/python-sdk)：发出触发评分的 `agent_end` 事件。 +- [评估器 Agent 技能](/zh/agenteye/evaluator-skill)：让编程 Agent 针对真实会话设计您的评分维度并为您构建此服务。 +- [Python SDK](/zh/agenteye/python-sdk)：发送触发评分的 `agent_end` 事件。 - [API 密钥](/zh/agenteye/api-keys)：`evaluations:read` 和 `evaluations:trigger` 权限。 -- [审计](/zh/agenteye/audits)：Observability 的另一个自动化质量功能，用于基于策略的审查。 \ No newline at end of file +- [审计](/zh/agenteye/audits)：Observability 另一项自动化质量功能，用于基于策略的审查。 \ No newline at end of file diff --git a/docs/zh/agenteye/evaluations.mdx b/docs/zh/agenteye/evaluations.mdx index 72e9c0bd..9def77db 100644 --- a/docs/zh/agenteye/evaluations.mdx +++ b/docs/zh/agenteye/evaluations.mdx @@ -1,51 +1,50 @@ --- title: "评估" -description: "质量问题主动找上门，而不是等到用户投诉时你才得知。" +description: "质量问题会主动找到你，而不是等你从用户投诉中得知。" --- +质量问题会主动找到你，而不是等你从用户投诉中得知。只需接入一次你自己的评分服务，Failproof AI Observability 便会自动对每次完成的运行进行评级——帮助性下降或幻觉激增等问题会在用户感知之前自动浮现。 -质量问题主动找上门，而不是等到用户投诉时你才得知。只需接入一次你自己的评分服务，Failproof AI Observability 就会自动对每一次完成的运行打分——帮助性下降或幻觉激增等问题会在用户察觉之前自动浮现。 +![Sessions 网格中带有评分列：每次运行都显示评估状态标签以及按颜色区分的帮助性、事实准确性和工具效率徽章](/agenteye/images/sessions-list.png) -![Sessions 网格中的分数列：每次运行都带有评估状态标记，以及颜色编码的帮助性、真实性和工具效率徽章](/agenteye/images/sessions-list.png) - -*Sessions 网格中的每次运行都携带其评分；红色、琥珀色和绿色徽章让问题运行一眼可见，无需打开任何一条记录。* +*Sessions 网格中的每次运行都附带其评分；红、橙、绿徽章让你无需打开任何记录就能一眼发现问题运行。* ## 告别手动抽样检查 -过去你只能抽查少数几次运行，然后祈祷其余的没有问题。现在，每一次已完成的会话在结束的那一刻就会按你关心的维度自动评分：帮助性、工具效率、真实性、安全性，以及任何你设定的质量标准。你来定义评分键；Failproof AI Observability 负责存储、追踪并展示评估器返回的所有内容。没有任何运行会漏掉评分，你也不必再从支持工单里得知回归问题。 +过去你只能抽查少量运行，祈祷其余的都没问题。现在，每个完成的会话一结束就会立即在你关心的维度上被评分：帮助性、工具效率、事实准确性、安全性，以及你所定义的任何质量标准。你定义评分键，Failproof AI Observability 负责存储、追踪趋势并展示评估器返回的所有数据。每次运行都不会漏评，你也不必再通过支持工单才能发现回归问题。 -评分会随着会话展示在 **`//sessions`** 的 Sessions 网格上（侧边栏 → *observe* → *sessions*），每行一组徽章簇。只想查看表现不达标的运行？按分数范围筛选，比如帮助性低于 0.5，精准定位值得深入阅读的运行。查看评分需要 `evaluations:read` 权限。 +评分会显示在 **`//sessions`**（侧边栏 → *observe* → *sessions*）的 Sessions 网格中，每行一组徽章。只想看表现不佳的运行？按评分范围筛选，比如帮助性低于 0.5，即可精准拉取值得细读的运行。查看评分需要 `evaluations:read` 权限。 ## 了解运行低分的原因 -数字告诉你某次运行表现不佳；会话页面则告诉你原因。打开任意一次运行，右侧面板首先显示总体摘要，随后按维度展示评分条，每条下方附有评估器自身的推理说明——让你在几秒内从"真实性评分 0.4"定位到具体出错的那个论断。 +数字告诉你某次运行表现欠佳，会话页面则告诉你原因所在。打开任意运行，右侧边栏最上方是摘要总览，下方按每个维度展示评分条，每条下方附有评估器自己的推理说明——从"事实准确性得了 0.4"到具体的错误断言，几秒内即可定位。 -![会话的右侧面板：顶部是评估摘要，下方是各维度评分条及各条推理说明，旁边是完整的事件时间线](/agenteye/images/session-detail.png) +![会话右侧边栏：顶部为评估摘要，下方为各维度评分条（每条附带一行推理说明），旁边是完整的事件时间线](/agenteye/images/session-detail.png) -*会话详情视图：摘要、各维度评分条，以及每项评分背后的推理说明，与运行事件时间线并排显示。* +*会话详情视图：摘要、各维度评分条，以及每项评分背后的推理说明，就在运行事件时间线旁边。* -部署了更精准的评估器，或者遇到运行在评分前崩溃的情况？**重新评估**按钮（需要 `evaluations:trigger` 权限）可以就地对会话重新评分，并将最新结果追加到其时间线中，此前的评分作为历史记录仍然可见。你可以在 **`//sessions/`** 找到该按钮。 +升级了更强的评估器，或者遇到某次运行在评分前就崩溃了？**重新评估**按钮（需要 `evaluations:trigger` 权限）会原地重新为该会话评分，并将最新结果追加到时间线中，之前的评分作为历史记录保留可见。你可以在 **`//sessions/`** 找到此功能。 -## 监控整个队列的质量趋势 +## 追踪整体质量趋势 -单次运行低分是噪声；整个批次下滑才是信号。已保存的仪表板将你的评分转化为可一目了然的趋势：本周与上周的平均帮助性对比，按 Agent、按环境分别呈现。 +单次运行低分只是噪声，整批次下滑才是信号。已保存的仪表盘将你的评分转化为一目了然的趋势视图：本周与上周的平均帮助性对比，可按 Agent、按环境细分。 -![质量仪表板：各评估维度的平均分柱状图，以及时间趋势折线](/agenteye/images/dashboard-quality.png) +![质量仪表盘：各评估维度的平均分柱状图，以及随时间变化的趋势](/agenteye/images/dashboard-quality.png) -*已保存的质量仪表板展示你关注的评分键趋势，让缓慢的下滑在演变为事故之前早早显现。* +*已保存的质量仪表盘追踪你关注的评分键趋势，让缓慢的下滑在演变为事故之前就清晰可见。* -仪表板位于 **`//dashboards`**（侧边栏 → *analyze* → *dashboards*），在整个组织内共享。每张卡片汇总对应的会话数据：运行数量、每个关注评分的平均值，以及趋势迷你折线图。点击"在 Sessions 中打开"可直接跳转到任意数字背后已预筛选的运行列表。查看需要 `dashboards:read` 和 `evaluations:read` 权限。 +仪表盘位于 **`//dashboards`**（侧边栏 → *analyze* → *dashboards*），在整个组织内共享。每个卡片汇总匹配的会话数据：运行数量、各评分键的平均值，以及趋势迷你图。点击"在 Sessions 中打开"可直接跳转到任意数值背后的预过滤运行列表。查看需要 `dashboards:read` 和 `evaluations:read` 权限。 -## 一次接入评估器 +## 一次性接入评估器 -评分功能为可选项，在你将 Failproof AI Observability 指向一个评分服务之前，始终保持关闭状态。你只需搭建一个小型 HTTP 服务（Observability 提供了一个可直接复制的参考实现），在服务器上设置两个值，此后每次运行都会自动获得评分。完整操作指南、评分契约和 SDK 详见深度指南。 +评分功能为可选项，在你将 Failproof AI Observability 指向评分服务之前，默认完全关闭。你只需启动一个小型 HTTP 服务（Observability 提供了可直接复制使用的参考实现），在服务器上设置两个参数，此后每次运行都会自动为你评分。完整操作指南、评分协议及 SDK 详见深度指南。 -不确定该从哪些维度开始评分？[评估器 Agent 技能](/zh/agenteye/evaluator-skill)可以让你的编码 Agent 结合你自己的会话数据找出答案，然后构建并部署该服务。 +不确定哪些维度值得评分？[评估器 Agent 技能](/zh/agenteye/evaluator-skill) 可以让你的编程 Agent 基于你自己的会话数据分析确定评分维度，然后构建并部署该服务。 ## 相关内容 -- [评估套件](/zh/agenteye/evaluation-suite)：接入评估器、评分契约与 SDK。 -- [评估器 Agent 技能](/zh/agenteye/evaluator-skill)：让编码 Agent 选定评分维度并构建评估器。 -- [Sessions](/zh/agenteye/sessions)：展示评分的逐次运行网格。 -- [仪表板](/zh/agenteye/dashboards)：在组织内保存并共享质量趋势。 +- [评估套件](/zh/agenteye/evaluation-suite)：接入评估器、了解评分协议和 SDK。 +- [评估器 Agent 技能](/zh/agenteye/evaluator-skill)：让编程 Agent 选取评分维度并构建评估器。 +- [Sessions](/zh/agenteye/sessions)：显示评分的逐次运行网格。 +- [仪表盘](/zh/agenteye/dashboards)：在组织内保存和共享质量趋势。 - [审计](/zh/agenteye/audits)：Observability 的另一项自动质量功能，用于跨会话调查。 \ No newline at end of file diff --git a/docs/zh/agenteye/evaluator-skill.mdx b/docs/zh/agenteye/evaluator-skill.mdx index eb24fb2d..370b0aa8 100644 --- a/docs/zh/agenteye/evaluator-skill.mdx +++ b/docs/zh/agenteye/evaluator-skill.mdx @@ -1,75 +1,75 @@ --- -title: "Failproof AI 可观测性评估器 Agent 技能" -description: "让您的编程 Agent 既负责决策又负责构建，从「我觉得我们的 Agent 有时表现很差」直接走向部署完毕的评分服务。" +title: "Failproof AI 可观测性评估器智能体技能" +description: "让你的编码智能体既负责决策又负责构建，帮你从「我觉得我们的智能体有时候表现不好」直接到一个已部署的评分服务。" --- -让您的编程 Agent 既负责决策又负责构建，从*「我觉得我们的 Agent 有时表现很差」*直接走向部署完毕的评分服务。**Failproof AI 可观测性评估器技能**（`agenteye-evaluator`）是一种 *Agent Skill*：一个小型指令文件夹，供 Claude Code 或 Codex 等编程 Agent 按需加载。它能引导 Agent 确定哪些质量维度值得为*您的* Agent 跟踪，然后编写、测试并部署对这些维度进行评分的[评估器服务](/zh/agenteye/evaluation-suite)。 +让你的编码智能体既负责决策又负责构建，帮你从*「我觉得我们的智能体有时候表现不好」*直接到一个已部署的评分服务。**Failproof AI 可观测性评估器技能**（`agenteye-evaluator`）是一项*智能体技能*：一个小型指令文件夹，供 Claude Code 或 Codex 等编码智能体按需加载。它教会智能体找出哪些质量维度值得为*你的*智能体进行追踪，然后编写、测试并部署对其进行评分的[评估器服务](/zh/agenteye/evaluation-suite)。 -它**不是**一个托管评分器、一个您上传到的注册表，也不是插件系统。您的评估器始终是运行在您自己基础设施上的 HTTP 服务，与[评估套件](/zh/agenteye/evaluation-suite)指南中所描述的完全一致。该技能只是教您的 Agent 如何把它构建好——它所做的一切，您完全可以自己动手写同样的代码来实现。 +它**不是**一个托管评分器、一个你上传内容的注册中心，也不是一个插件系统。你的评估器始终是你自己基础设施上的 HTTP 服务，与[评估套件](/zh/agenteye/evaluation-suite)指南中描述的完全一致。该技能只是教会你的智能体把它构建好，因此它所做的一切，你都可以自己通过编写相同的代码来完成。 --- ## 难点在于决定评分什么 -SDK 接口很简洁——一个装饰器和两个模型——Agent 仅凭[契约](/zh/agenteye/evaluation-suite#http-contract)就能把代码写出来。评估器真正的失败之处不在这里。它们失败是因为评错了东西，而评错对象的评估器比没有还糟：它产出的仪表盘会让所有人习惯性地无视。 +SDK 接口很小——一个装饰器和两个模型——智能体仅凭[契约](/zh/agenteye/evaluation-suite#http-contract)就能写出来。问题不在这里。评估器失败是因为它们评分了错误的东西，而一个评分错误的评估器比没有更糟：它产出的仪表盘让所有人都学会了忽视它。 -因此，该技能的大部分工作发生在任何代码存在之前。它让 Agent 对您进行访谈（*「描述一次进展顺利的运行；再描述一次进展糟糕的」*），然后通过 [`agenteye` CLI](/zh/agenteye/cli) 提取您的真实会话并从头到尾阅读。这两部分通常会出现分歧，而这个差距正是关键所在：您打算衡量什么，与您的对话记录实际上能支撑什么，往往并不一致。一个维度只有在**可从事件中计算**且**具有区分度**时才能保留——如果它在您的好运行和差运行上都打出 0.9 分，那什么也说明不了，直接剔除。 +因此，该技能的大部分内容都在代码出现之前。它让智能体采访你（*「描述一次进展顺利的运行；再描述一次进展不好的」*），然后通过 [`agenteye` CLI](/zh/agenteye/cli) 拉取你的真实会话并从头到尾阅读。这两部分通常会有出入，而差距正是关键所在：你打算衡量什么，与你的对话记录实际上能支撑什么。一个维度只有在**可从事件中计算**且**具有区分性**时才能保留——如果它在你的好运行和坏运行上都打 0.9 分，它什么都说明不了，就会被剔除。 -最终返回的是一份包含 2-4 个维度的提案，附带推理说明，供您在写下任何一行代码之前确认。 +最终返回的是一个包含 2-4 个维度的提案，附带推理过程，供你在写下任何一行代码之前确认。 ```mermaid flowchart TD - YOU["您：「我想为我的支持机器人做评估」"] --> AGENT["编程 Agent（Claude Code / Codex）
加载 agenteye-evaluator 技能"] - AGENT -->|"访谈：好的表现和差的表现分别是什么样的？"| YOU - AGENT -->|"agenteye --json sessions / events"| DATA["您的真实会话
实际发生的情况"] - DATA --> DIMS["2-4 个维度，由您确认"] - DIMS --> SVC["您的评估器服务
agenteye-evaluator SDK"] - SVC --> SCORES["评分出现在仪表盘
和 agenteye evals 中"] + YOU["你：「我想为我的支持机器人做评估」"] --> AGENT["编码智能体（Claude Code / Codex）
加载 agenteye-evaluator 技能"] + AGENT -->|"采访：好的和坏的表现是什么样的？"| YOU + AGENT -->|"agenteye --json sessions / events"| DATA["你的真实会话
实际发生的情况"] + DATA --> DIMS["2-4 个维度，由你确认"] + DIMS --> SVC["你的评估器服务
agenteye-evaluator SDK"] + SVC --> SCORES["分数显示在仪表盘
和 agenteye evals 中"] ``` --- ## 与其他评估组件的关系 -共有四份文档涵盖评分相关内容，它们按顺序相互衔接： +四份文档涵盖了评分内容，它们按顺序相互衔接： -| 页面 | 内容 | 适用场景 | +| 页面 | 内容 | 何时使用 | |---|---|---| -| **[评估（Evaluations）](/zh/agenteye/evaluations)** | 该功能：会话网格上的评分、仪表盘、重新评估 | 您想了解自动评分能带来什么 | -| **[评估套件（Evaluation suite）](/zh/agenteye/evaluation-suite)** | HTTP 契约、SDK、服务器环境变量 | 您正在自行实现或调试评估器 | -| **评估器技能**（本文档） | 设计*并*构建评分器的自然语言入口 | 您想从「我想要评估」走到一个正在运行的服务 | -| **[CLI 技能](/zh/agenteye/cli-skill)** | `agenteye` CLI 的自然语言入口 | 您想*读取*已有的评分结果 | -| **[Python SDK 技能](/zh/agenteye/python-sdk-skill)** | 为您的 Agent 添加埋点的自然语言入口 | 您的 Agent 尚未输出会话——还没有东西可以评分 | +| **[评估](/zh/agenteye/evaluations)** | 该功能：会话网格上的分数、仪表盘、重新评估 | 你想了解自动评分能带来什么 | +| **[评估套件](/zh/agenteye/evaluation-suite)** | HTTP 契约、SDK、服务器环境变量 | 你正在自己实现或调试评估器 | +| **评估器技能**（本文档） | 设计*并*构建评分器的自然语言入口 | 你想从「我想要评估」到一个运行中的服务 | +| **[CLI 技能](/zh/agenteye/cli-skill)** | `agenteye` CLI 的自然语言入口 | 你想*读取*已有的分数 | +| **[Python SDK 技能](/zh/agenteye/python-sdk-skill)** | 为你的智能体进行埋点的自然语言入口 | 你的智能体还没有发出会话——没有任何内容可供评分 | -### 与 CLI 技能的区别：构建 vs. 读取 +### 与 CLI 技能的对比：构建与读取 -这两个技能在职责上刻意不重叠，同时安装两者是常规配置——Agent 会根据您的提问在二者之间切换： +这两项技能是刻意不重叠的，同时安装两者是正常的配置——智能体根据你的问题在它们之间做出选择： -- **`agenteye-evaluator`**（本文档）构建*产生*评分的东西。它的任务在评分首次出现时结束。 -- **[`agenteye-cli`](/zh/agenteye/cli-skill)** 读取已存在的评分（`agenteye evals`）。「本周质量下降了吗？」是它回答的问题，不是本技能的职责。 +- **`agenteye-evaluator`**（本文档）构建*生产*分数的东西。它的工作在分数首次落地时结束。 +- **[`agenteye-cli`](/zh/agenteye/cli-skill)** 读取已存在的分数（`agenteye evals`）。*「这周质量下降了吗？」*是它的问题，而不是本技能的。 --- ## 前提条件 -1. **已安装并登录 `agenteye` CLI**（`pipx install agenteye`，然后 `agenteye login`）。该技能会用到它两次：拉取真实会话用于设计，以及在最后确认评分是否落地。您的登录账户需要 `events:read` 权限，以及用于最终检查的 `evaluations:read` 权限。与 CLI 技能一样，它**无法**替您完成邮件一次性验证码登录。 -2. **一个放置评估器的地方。** 评估器会被构建成镜像并作为长期运行的服务运行，因此它需要一个真实的代码仓库，而不是临时文件。评估器通常独立存在于自己的仓库中，与被评分的 Agent 分开——该技能会寻找现有仓库，并在搭建新仓库之前征询您的意见。 -3. **`agenteye-evaluator` SDK wheel**——在让您的 Agent 开始输入 `pip` 命令之前，请先阅读下一节。 +1. **已安装并登录 `agenteye` CLI**（`pipx install agenteye`，然后 `agenteye login`）。该技能会用到它两次：一次是拉取设计所依据的真实会话，另一次是在最后确认你的分数已落地。你的登录账号需要 `events:read` 权限，以及用于最终检查的 `evaluations:read` 权限。与 CLI 技能一样，它**无法**替你完成邮件一次性验证码登录。 +2. **评估器的存放位置。** 它被构建成镜像并作为长期运行的服务运行，因此需要一个真实的代码仓库，而不是临时文件。评估器通常有自己独立的仓库，与被评分的智能体分开——该技能会查找现有仓库，并在新建之前征询你的意见。 +3. **`agenteye-evaluator` SDK wheel**——在你的智能体开始输入 `pip` 命令之前，请先阅读下一节。 --- ## 获取方式 -该技能发布于 Failproof AI 的公共技能集合中： +该技能发布在 Failproof AI 的公共技能集合中： **[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator) -该仓库是公开的，技能本身不需要任何凭据——它只是用*您*登录时的会话驱动 `agenteye` CLI，并在*您的*仓库中写代码。请注意，它以独立文件夹的形式发布，**不在** `pipx install agenteye` 包内，请勿在那里寻找它。 +该代码库是公开的，技能本身不需要任何凭证——它只使用*你*登录的 `agenteye` CLI 来驱动操作，并在*你的*代码库中编写代码。请注意，它作为独立文件夹发布，**不在** `pipx install agenteye` 包内，请勿在那里寻找它。 ## 安装技能 -最快的方式是使用 [`skills`](https://skills.sh) CLI，它会拉取文件夹并放到您的 Agent 查找的位置： +最快捷的方式是使用 [`skills`](https://skills.sh) CLI，它会拉取文件夹并将其放置到智能体的查找路径中： ```bash # Claude Code，仅限当前项目 @@ -78,90 +78,90 @@ npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code # 所有项目（安装到 ~/.claude/skills/） npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy -# 改用 Codex +# 使用 Codex npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex ``` 然后像管理其他技能一样管理它： ```bash -npx skills list -a claude-code # 查看已安装的技能 +npx skills list -a claude-code # 查看已安装的内容 npx skills update agenteye-evaluator # 拉取最新版本 npx skills remove agenteye-evaluator # 移除它 ``` -喜欢手动安装？Agent Skill 只是一个包含 `SKILL.md`（以及可选引用文件）的文件夹，直接复制也可以： +更喜欢手动安装？智能体技能只是一个包含 `SKILL.md`（以及可选引用文件）的文件夹，直接复制也可以： -- **Claude Code**：将 `agenteye-evaluator/` 文件夹放入 `~/.claude/skills/`（所有项目）或 `/.claude/skills/`（仅该仓库）。Claude Code 会自动发现它——通过 `/skills` 列表验证，或者直接询问评估相关问题即可。 -- **Codex（OpenAI）**：Codex 读取同一个 `SKILL.md`。捆绑的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时 Codex 会自动选择该技能；否则可以通过 `$agenteye-evaluator` 显式调用它。 +- **Claude Code**：将 `agenteye-evaluator/` 文件夹放入 `~/.claude/skills/`（所有项目）或 `<你的代码库>/.claude/skills/`（仅该代码库）。Claude Code 会自动发现它——通过 `/skills` 列表验证，或者直接询问评估相关的问题即可。 +- **Codex（OpenAI）**：Codex 读取相同的 `SKILL.md`。捆绑的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时 Codex 会自动选择该技能；否则可以明确调用 `$agenteye-evaluator`。 --- ## SDK 不在公共 PyPI 上 -> **警告：** 在让 Agent 安装 SDK 之前，请先阅读本节。 +> **警告：** 在让智能体安装 SDK 之前，请先阅读本节。 -该技能是公开的；它所驱动的 SDK 则不是。`agenteye-evaluator` 仅作为私有发布产物发布，且与 `agenteye` 不同，该名称在**公共 PyPI 上尚未被注册**——因此直接执行 `pip install agenteye-evaluator` 可能会将陌生人的包安装到读取您生产对话记录的服务中。这是一个供应链问题，而不是笔误。 +该技能是公开的；它驱动的 SDK 不是。`agenteye-evaluator` 仅作为私有发布产物提供，与 `agenteye` 不同，该名称在公共 PyPI 上**未被占用**——因此直接 `pip install agenteye-evaluator` 可能会将某个陌生人的包安装到读取你生产环境对话记录的服务中。这是一个供应链问题，而不是笔误。 -该技能了解这一点，因此会按照安装梯队依次尝试，在第一个适用的环节停下：如果您在 AgentEye 仓库内，则使用 monorepo 源码；否则使用 GitHub Releases 上的私有发布 wheel（需要访问权限）；如果两者都无法访问，它会**停止并告诉您联系 Failproof AI 联系人获取 wheel**，而不是自行发挥。 +该技能了解这一点，会按安装阶梯逐步检查，在第一个适用的环节停下：如果你在 AgentEye 代码库内，则使用 monorepo 源码；否则使用 GitHub Releases 上的私有发布 wheel（需要访问权限）；如果两者都无法访问，它**会停下来告诉你向你的 Failproof AI 联系人索取 wheel**，而不是自行发挥。 -因此，如果您的 Agent 提议从公共 PyPI 直接执行 `pip install agenteye-evaluator`，这就说明该技能根本没有加载。请立即停止并检查技能是否已安装。 +因此，如果你的智能体提出从公共 PyPI 直接 `pip install agenteye-evaluator`，这就说明技能从未加载。请在此停下，检查技能是否已安装。 --- -## 可以问它什么 +## 你可以向它提出什么请求 -一次真实的完整流程从模糊的需求开始，以一个经过确认的设计方案结束，而不是直接以代码开始： +一次完整的交互从一个模糊的请求开始，以一个确认好的设计结束，而不是以代码结束： ```text -您 ▸ 我想为我们的支持机器人做评估。我觉得它有时表现很差。 +你 ▸ 我想为我们的支持机器人做评估。我觉得它有时候表现不好。 -Agent ▸ 在我写任何东西之前：描述一次进展顺利的运行， - 以及一次进展糟糕的。 +智能体 ▸ 在我写任何东西之前：描述一次进展顺利的运行， + 以及一次进展不好的。 -您 ▸ 好的情况：它从文档中给出答案。差的情况：它胡编乱造， - 或者放弃并说「请联系支持」。 +你 ▸ 好的情况：它从文档中给出答案。坏的情况：它编造内容， + 或者放弃并说「请联系支持团队」。 -Agent ▸ 正在运行：agenteye --json sessions --status error --since 7d - 读取 5 个会话，包括您认为表现差的两个。 +智能体 ▸ 正在运行：agenteye --json sessions --status error --since 7d + 读取 5 个会话，包括两个你认为表现不好的。 - 您的描述说的是事实性和推诿。对话记录在推诿方面 - 与描述吻合（5 个中有 2 个以转接支持结束， - 在 model_response.content 中清晰可见），但事实性 - 需要您的事件中没有的基准真值。 + 你的描述提到了事实性和回避性。对话记录在回避性上 + 与你的判断一致（5 个中有 2 个以转交支持团队结束， + 在 model_response.content 中清晰可见），但事实性 + 需要你的事件中没有的真实标注数据。 - 因此我会评分三件事： - - deflection 基于规则，成本低，能区分您的两次运行 - - tool_efficiency 基于规则，能捕捉 run-004 中的重试循环 - - groundedness LLM 评判：每个声明都在它检索的文档中吗？ + 因此我建议评分三项： + - deflection 基于规则，代价低，能区分你的两次运行 + - tool_efficiency 基于规则，能发现 run-004 中的重试循环 + - groundedness LLM 评判：每个声明是否都在它检索的文档中？ - 「事实性」需要我们没有的基准真值；groundedness - 是您的对话记录实际上能支撑的最接近的替代。 - 这三个名称可以吗？之后重命名会导致历史记录断裂。 + 「factuality」需要我们没有的真实标注数据；groundedness + 是你的对话记录实际上能支撑的最接近的替代方案。 + 这三个名称可以吗？之后重命名会导致历史数据分裂。 -您 ▸ 好的 +你 ▸ 可以 -Agent ▸ 这个仓库中没有评估器。要在这里搭建一个， - 还是您在别处已经有了？ +智能体 ▸ 这个代码库中没有评估器。我应该在这里新建一个， + 还是你在别处有现成的？ ``` -之后，它会先编写基于规则的维度（免费、即时、确定性），针对真实捕获的会话（包括那些会让朴素评估器崩溃的空会话和未完成会话）进行测试，只在主观维度上才会使用 LLM 评判器。它了解[调度器的限制](/zh/agenteye/evaluation-suite#configuring-the-server)——30 秒请求超时和全局 8 个并发调用——因此如果评判器不能可靠地在时限内完成，它会使用 `JobPending` 异步处理，而不是让您的评判器被取消并以五倍成本重试五次。 +从那里开始，它首先编写基于规则的维度（免费、即时、确定性），针对真实捕获的会话进行测试，包括那些会让简单评估器崩溃的空会话和未完成的会话，并且只在主观维度上才使用 LLM 评判。它了解[调度器的限制](/zh/agenteye/evaluation-suite#configuring-the-server)——30 秒请求超时和全部署范围内 8 个并发调用——因此如果评判器无法可靠地在时限内完成，它会以 `JobPending` 异步处理，而不是让你的评判器被取消后以五倍成本重试五次。 -然后它进行部署，设置两个服务器环境变量，并通过 `agenteye --json evals --session-id ` 确认评分确实落地。评分落地是唯一的证明。 +然后它完成部署，设置两个服务器环境变量，并通过 `agenteye --json evals --session-id ` 确认分数确实已落地。分数落地是唯一的证明。 --- ## 需要注意的事项 -- **维度名称几乎是永久性的。** 评分键是任意字符串，平台会对您发送的任何内容进行趋势分析，这意味着下游没有任何东西能纠正一个错误的选择。之后重命名会导致历史记录断裂：旧会话保留旧键，趋势就此中断。这就是为什么该技能在写代码之前要明确征得您的同意——请认真对待那个提示。 -- **测试夹具是真实的生产对话记录。** 针对真实会话进行设计意味着要将它们拉取到磁盘上，而它们可能包含客户数据。该技能会在将其提交到 git 之前征询您的意见；如有疑虑，请将 `fixtures/` 排除在仓库之外，让每位开发者自行拉取。 -- **Agent 会编写并部署一个读取所有对话记录的服务。** 它以您的身份行事，受您的 CLI 登录权限约束，但请像审查其他接触生产数据的代码一样审查评估器。 +- **维度名称近乎永久性。** 分数键是任意字符串，平台会追踪你发送的任何内容，这意味着下游没有任何机制能纠正错误的选择。之后重命名会导致历史数据分裂：旧会话保留旧键，趋势就断了。这就是为什么该技能在写代码之前会明确征求你的确认——请认真对待那个提示。 +- **测试夹具是真实的生产对话记录。** 针对真实会话进行设计意味着要将它们拉取到磁盘，而它们可能包含客户数据。该技能在将其提交到 git 之前会征询意见；如有疑虑，请将 `fixtures/` 排除在代码库之外，让每位开发者自行拉取。 +- **智能体编写并部署一个读取每条对话记录的服务。** 它以你的身份行事，受你的 CLI 登录权限约束，但请像对待任何接触生产数据的代码一样审查这个评估器。 --- ## 后续步骤 -- **[评估套件（Evaluation suite）](/zh/agenteye/evaluation-suite)**：HTTP 契约、SDK 以及该技能所配置的服务器环境变量。 -- **[评估（Evaluations）](/zh/agenteye/evaluations)**：评分落地后出现的位置。 -- **[CLI 技能](/zh/agenteye/cli-skill)**：与本技能配套的技能，用于读取结果而非构建评分器。 -- **[CLI](/zh/agenteye/cli)**：该技能所依赖的会话数据背后的命令参考。 \ No newline at end of file +- **[评估套件](/zh/agenteye/evaluation-suite)**：技能所配置的 HTTP 契约、SDK 和服务器环境变量。 +- **[评估](/zh/agenteye/evaluations)**：分数落地后显示的位置。 +- **[CLI 技能](/zh/agenteye/cli-skill)**：配套技能，用于读取结果而非构建评分器。 +- **[CLI](/zh/agenteye/cli)**：技能设计所依据的会话数据背后的命令参考。 \ No newline at end of file diff --git a/docs/zh/agenteye/event-stream.mdx b/docs/zh/agenteye/event-stream.mdx index b852b4f2..0bd81c2e 100644 --- a/docs/zh/agenteye/event-stream.mdx +++ b/docs/zh/agenteye/event-stream.mdx @@ -1,50 +1,50 @@ --- title: "事件流" -description: "智能体一有动作，你立刻知晓。" +description: "Agent 的每一个动作，即时可见。" --- -智能体一有动作，你立刻知晓。事件流是你对生产环境中每个智能体的实时脉搏：无需等待，无需翻查日志，无需猜测刚刚发生了什么。 +Agent 的每一个动作，即时可见。事件流是你对生产环境中每个 agent 的实时脉搏：无需等待，无需翻查日志，无需猜测刚刚发生了什么。 -![实时事件流：颜色编码的事件行实时滚动，可按环境、智能体、会话、事件类型和自由文本过滤](/agenteye/images/events-stream.png) +![实时事件流：按颜色区分的事件行实时滚动更新，可按环境、agent、会话、事件类型和自由文本进行过滤](/agenteye/images/events-stream.png) -*来自你组织中每个智能体的所有事件，最新的排在最前，实时更新。* +*组织内所有 agent 的每一条事件，最新优先，实时更新。* -## 对每个智能体的实时脉搏 +## 对每个 agent 的实时脉搏 -当智能体启动一次运行、调用模型、触发工具、执行钩子或遭遇错误时，该行会在事件发生的瞬间出现在流的顶部。它实时追踪你组织中每个智能体的所有事件，最新的排在最前，让你始终掌握当前状态，而非过时信息。 +当一个 agent 启动运行、调用模型、触发工具、执行 hook 或遇到错误时，该行在发生的瞬间就会出现在流的顶端。它实时追踪组织内所有 agent 的每一条事件，最新优先，让你随时掌握当前状态，而不是过时信息。 -这意味着你无需在某台服务器上追踪日志文件，无需跨机器 grep，也无需手动拼凑时间戳。打开一个页面，你就已经在监视生产环境。 +这意味着不再需要在某台服务器上追踪日志文件，不再需要跨机器 grep，不再需要手动拼接时间戳。打开一个页面，你就已经在观察生产环境了。 -各行按类型用颜色编码，你一眼就能读懂流，而不必逐行解析。每行一眼可见： +每行按类型进行颜色编码，让你一眼就能读懂流内容，而无需逐行解析。一眼扫过，每行会告诉你： -- **类型**，颜色编码：`agent_start`、`model_response`、`tool_use`、`hook_completed`、`error` 等。 -- **一行摘要**，描述发生了什么，这样你几乎不需要点开任何内容就能了解要点。 -- **该步骤的 Token 计数**。 -- **上下文窗口占用徽章**（适用时），让提示词增长和即将到来的压缩在造成影响前就清晰可见。 +- **类型**，用颜色区分：`agent_start`、`model_response`、`tool_use`、`hook_completed`、`error` 等。 +- **一行摘要**，说明发生了什么，让你几乎不需要展开就能抓住要点。 +- **该步骤的 token 数量**。 +- **上下文窗口占用徽标**（适用时），让提示词增长和即将触发的压缩在造成影响之前就变得可见。 -实时监视意味着你能在恶性部署、失控循环或错误爆发发生时立即发现，而不是等到明天的日志复查时才知晓。 +实时观察意味着你能在错误部署、失控循环或错误爆发发生时第一时间察觉，而不是等到明天的日志复盘时才发现。 -## 找到那条关键运行记录 +## 找到那一条关键运行记录 -当某些情况看起来不对劲时，你不需要面对海量数据，你需要的是那条出问题的单次运行。事件流的过滤很迅速：按环境、按智能体、按会话、按事件类型，或按自由文本。 +当某些情况看起来不对劲时，你不需要海量信息，你需要的是那一条出问题的运行记录。事件流可以快速过滤：按环境、按 agent、按会话、按事件类型，或按自由文本。 -按会话 ID 或智能体 ID 过滤，可以从第一个事件到最后一个事件追踪一次运行的完整过程。按事件类型过滤，可以隔离某一类活动，例如在一个视图中查看组织内所有的 `error`。叠加过滤条件，几次点击就能从"所有内容、全部范围"缩小到"这个智能体、在生产环境、正在报错"，然后采取相应行动。 +按会话 ID 或 agent ID 过滤，可以从第一条事件追踪到最后一条，完整跟随一次运行。按事件类型过滤，可以隔离某一类活动，例如在一个视图中查看整个组织内的所有 `error`。叠加多个过滤条件，几次点击就能从"所有环境的所有内容"缩小到"这个 agent，在生产环境，正在报错"，然后针对所见采取行动。 -自由文本搜索可以直接定位到某条消息、某个工具名称或你手头已有的 ID，让客户反馈在几秒内变成精确的运行记录。 +自由文本搜索可以直接定位到某条消息、某个工具名称或你手头已有的某个 ID，让一份客户反馈在几秒内精准对应到具体的运行记录。 ## 在哪里找到它 -事件流是你的组织主页。登录后，它是你首先看到的界面，位于 `//`，让你一到达就能立刻开始排查。 +事件流是你的组织主页。登录后，它是你第一个看到的界面，位于 `//`，让你一到达就能立即开始问题排查。 -在其背后，你的智能体通过 SDK 发送事件，收集器将它们传输到你的 Failproof AI 可观测性服务器，流在事件到达时对其进行追踪，整个基础设施由你掌控。如果你需要的是汇总视图而非原始记录，每次运行的事件会在"会话"中折叠为一行，一键即达。 +在其背后，你的 agent 通过 SDK 发出事件，采集器将它们传送到你的 Failproof AI 可观测性服务器，流则在事件抵达时实时追踪——整个基础设施由你掌控。当你想要汇总视图而非原始记录时，每次运行的事件会折叠成 Sessions 中的单行，一键即达。 -这是所有其他观测界面所基于的原始数据来源，因此当其他地方的数字看起来有误时，事件流就是你确认真实情况的地方。 +这是所有其他可观测性界面的原始数据来源，因此当其他地方的数字看起来不对时，事件流就是你确认实际发生了什么的地方。 ## 相关内容 -- [Sessions](/zh/agenteye/sessions)：相同的事件按每次运行汇总为一行，并附有 git 风格的执行图。 -- [Telemetry](/zh/agenteye/telemetry)：你的智能体发送什么内容，以及事件如何到达流。 -- [Error tracking](/zh/agenteye/error-tracking)：统一的错误排查界面，涵盖所有出错情况。 +- [Sessions](/zh/agenteye/sessions)：将相同事件汇总为每次运行一行，附带 git 风格的执行图。 +- [Telemetry](/zh/agenteye/telemetry)：你的 agent 发送什么内容，以及事件如何到达流。 +- [Error tracking](/zh/agenteye/error-tracking)：所有出错内容的统一排查界面。 - [Alerts](/zh/agenteye/alerts)：将任意阈值转化为告警规则。 -- [CLI and agents](/zh/agenteye/cli-and-agents)：从终端获取相同的实时追踪。 \ No newline at end of file +- [CLI and agents](/zh/agenteye/cli-and-agents)：在终端中查看同样的实时记录。 \ No newline at end of file diff --git a/docs/zh/agenteye/hermes-capture.mdx b/docs/zh/agenteye/hermes-capture.mdx index 606645f9..495d7f12 100644 --- a/docs/zh/agenteye/hermes-capture.mdx +++ b/docs/zh/agenteye/hermes-capture.mdx @@ -1,53 +1,53 @@ --- title: "Hermes 会话捕获" -description: "将团队的 Hermes 网关会话（包括 Slack、Telegram、CLI 和定时运行）作为普通会话和事件引入 AgentEye。" +description: "将团队的 Hermes 网关会话（Slack、Telegram、CLI 及定时运行）作为普通会话和事件引入 AgentEye。" --- -[Hermes](https://hermes-agent.nousresearch.com) 可以在团队常用的任意平台上为他们提供解答——Slack、Telegram、CLI 或定时运行。Hermes 会话捕获功能将所有这些内容作为普通会话和事件引入 AgentEye，让团队每天交互的助手与你自己编写的 Agent 一样具备可观测性。 +[Hermes](https://hermes-agent.nousresearch.com) 可以在团队常用的任何地方响应请求——Slack、Telegram、CLI、定时运行。Hermes 会话捕获功能将所有这些内容以普通会话和事件的形式引入 AgentEye，让团队每天交互的助手和自行编写的智能体一样具备可观测性。 -一个小型后台采集器会在 Hermes 本地会话存储写入时读取其内容，并将会话发送至 AgentEye。其工作方式与 [Codex](/zh/agenteye/codex-capture) 和 [OpenClaw](/zh/agenteye/openclaw-capture) 捕获相同，且单个采集器可以同时捕获多个来源。 +一个轻量级后台采集器会在 Hermes 写入本地会话存储时实时读取，并将会话推送至 AgentEye。其工作方式与 [Codex](/zh/agenteye/codex-capture) 和 [OpenClaw](/zh/agenteye/openclaw-capture) 的捕获方式相同，一个采集器可以同时捕获多个来源。 --- ## 捕获内容 -机器上的每一个 Hermes 会话都会被捕获，无论来自哪个渠道。每个会话都会成为 AgentEye 中的一个 [session（会话）](/zh/agenteye/sessions)；其中的用户消息、助手消息、工具调用和工具结果将成为对应的 [events（事件）](/zh/agenteye/event-stream)。 +机器上所有 Hermes 会话均会被捕获，无论来自哪个渠道。每个会话都会成为 AgentEye 的一个[会话](/zh/agenteye/sessions)；其中的用户消息、助手消息、工具调用及工具结果会成为对应的[事件](/zh/agenteye/event-stream)。 -会话的来源渠道——Slack、Telegram、CLI 或定时运行——会被记录在会话上，便于区分和按渠道筛选。同时还会记录会话运行所用的模型、发起会话的聊天窗口和用户，以及当某个会话由另一个会话派生时，其指向父会话的关联链接。 +会话的来源渠道——Slack、Telegram、CLI 或定时运行——会记录在会话上，便于区分和按渠道过滤。同时记录的还有：运行该会话所用的模型、发起会话的聊天频道和人员，以及（如果该会话是由另一个会话派生的）指向父会话的链接。 -无论是否已有消息，只要 Hermes 启动会话，该会话即可立即呈现；每轮对话的回复及其工具调用均按实际发生顺序排列。会话结束时，你还可以获取会话结束的原因、消耗的费用以及使用的 token 数量。 +会话一旦被 Hermes 启动即立即出现，无需等待任何消息发出；一轮对话的回复及其工具调用会按实际发生顺序排列。会话结束时，还会记录结束原因、消耗的费用以及使用的 token 数量。 --- -## 启用方法 +## 开启捕获 -捕获功能默认关闭，需手动启用。使用具有 `events:add` 权限的 API 密钥（参见 [API keys](/zh/agenteye/api-keys)）安装采集器，并开启 Hermes 捕获： +捕获功能默认关闭，需手动启用。请使用具有 `events:add` 权限的 API 密钥（参见 [API 密钥](/zh/agenteye/api-keys)）安装采集器，并开启 Hermes 捕获： ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --hermes-enabled ``` -该命令会安装采集器、将其注册为后台服务并开始捕获。确认其运行状态： +该命令会安装采集器、将其注册为后台服务并开始捕获。确认其正常运行： ```bash agenteye-collector health ``` -需要在同一台机器上捕获多个 Agent？在同一命令中添加各自的标志即可，例如 `--hermes-enabled --codex-enabled`。 +需要在同一台机器上捕获多个智能体？在同一命令中添加各自的标志即可，例如 `--hermes-enabled --codex-enabled`。 -首次运行时，已有的 Hermes 会话会被一次性回填，此后新活动将在数秒内实时流入。Hermes 自身的数据仅会被读取，不会被修改或删除；即使采集器重启，每条消息也只会发送一次。 +首次运行时，现有的 Hermes 会话会被回填一次，此后新活动将在数秒内实时推送。采集器对 Hermes 的数据只读不写，不会进行任何修改或删除，且每条消息仅推送一次，重启后亦然。 -`health` 命令还会显示采集器捕获的内容是否全部成功到达 AgentEye。若某批数据无法投递，会被保留并重试，而非丢弃；只要有任何数据仍在等待中，检查结果就会显示为不健康——因此"健康"意味着数据已成功送达，而非仅仅进程在运行。 +`health` 命令还会告知采集器捕获的数据是否已全部到达 AgentEye。若某批数据无法投递，系统会保留并重试而非丢弃，且在仍有数据待处理时会报告为不健康状态——因此"健康"意味着数据已实际到达，而非仅仅表示进程在运行。 --- -## 数据呈现位置 +## 数据展示位置 -捕获的会话出现在 **Sessions** 中，其事件出现在 **Events** 流中，与其他被观测的 Agent 完全一致——因此 [session replay（会话回放）](/zh/agenteye/sessions)、[search（搜索）](/zh/agenteye/queries)、[evaluations（评估）](/zh/agenteye/evaluations) 和 [alerts（告警）](/zh/agenteye/alerts) 均可对其使用。通过筛选 Hermes Agent 可单独查看这些会话。 +捕获的会话显示在 **Sessions** 中，对应事件显示在 **Events** 流中，与其他任何被观测的智能体完全一致——[会话回放](/zh/agenteye/sessions)、[搜索](/zh/agenteye/queries)、[评估](/zh/agenteye/evaluations)和[告警](/zh/agenteye/alerts)功能均可对其使用。按 Hermes 智能体筛选即可单独查看。 --- ## 隐私说明 -Hermes 会话包含完整的对话记录——包括命令输出、文件内容以及 Agent 读取或写入的任何内容——并可能包含敏感信息。捕获的会话将原样发送，因此请仅在将该内容集中存储至 AgentEye 合适的场景下启用捕获功能，并为采集器提供仅限 `events:add` 权限范围的密钥。数据隔离保护的详细说明请参见 [Security（安全性）](/zh/agenteye/security)。 \ No newline at end of file +Hermes 会话包含完整的对话记录——包括命令输出、文件内容，以及智能体读写的所有内容——并可能含有敏感信息。捕获的会话会原样推送，因此请仅在将相关内容集中存储至 AgentEye 合规的场景下启用捕获功能，并为采集器分配仅限 `events:add` 权限的密钥。数据隔离机制详见[安全说明](/zh/agenteye/security)。 \ No newline at end of file diff --git a/docs/zh/agenteye/incidents.mdx b/docs/zh/agenteye/incidents.mdx index 7937776f..78fd9943 100644 --- a/docs/zh/agenteye/incidents.mdx +++ b/docs/zh/agenteye/incidents.mdx @@ -1,26 +1,26 @@ --- title: "事故" -description: "当告警触发时，所有人都能看到事故已开启、负责人是谁，以及目前发生了什么——一条有归属标注的统一时间线。" +description: "当告警触发时，所有人都能看到事故是否处于开启状态、由谁负责，以及目前发生了什么——所有信息汇聚在一条有归属记录的时间线上。" --- -当告警触发时，第一个问题永远是"谁在处理？"事故功能给出了答案：一旦发生违规，所有人都能立即看到事故已开启、负责人是谁，以及目前已发生的一切——形成一份干净、有归属的记录，可以直接用于事后复盘。 +当告警触发时，第一个问题始终是："谁在处理？"事故功能给出了答案：一旦某项指标突破阈值，所有人都能立即看到事故已开启、由谁负责，以及截至目前的详细经过——并生成一份干净、有归属的记录，可直接用于事后复盘。 -![事故收件箱：与告警关联的事故卡片和手动创建的事故卡片，按状态分组，每张卡片带有严重程度徽章和负责人信息](/agenteye/images/incidents.png) -*收件箱按状态将未处理的事故分组，并支持按严重程度和负责人筛选，让你快速看到当前需要人工介入的内容。* +![事故收件箱：与告警关联或手动创建的事故卡片，按状态分组，每张卡片附有严重程度标识和负责人](/agenteye/images/incidents.png) +*收件箱按状态对开启的事故进行分组，并支持按严重程度和负责人筛选，让你第一时间看到需要人工介入的内容。* -## 一眼知道谁在负责 +## 一目了然，谁在跟进 -再也不用在群聊里问"有人在看这个吗？"。违规发生时会自动创建事故并进入共享收件箱，按状态分组。确认事故后，你的名字就挂在上面，让团队其他成员知道已有人接手。确认操作支持多人同时进行：多名操作员可以各自确认同一个事故，每条记录独立保存，整个作战小组都能按名字显示，而不会互相覆盖。指定一名负责人进行分类处理，再按严重程度或负责人筛选收件箱，快速聚焦到属于自己的事故。 +不必再在聊天群里追问"有没有人在看这个？"。阈值突破后，系统自动创建事故并推送到共享收件箱，按状态分组展示。确认事故后，你的名字就会显示在上面，团队其他成员便知道有人在处理。确认操作支持多人同时进行：多名运营人员可以同时确认同一个事故，每条确认记录独立保存，因此整个"作战室"的参与者都会清晰呈现，互不干扰。可指定单一负责人负责分级处理，同时按严重程度或负责人过滤收件箱，快速锁定属于自己的任务。 -## 完整故事，尽在一条时间线 +## 完整经过，尽在一条时间线 -事故结束时，你已经有了现成的复盘素材。打开任意事故，你会看到违规证据、负责人和订阅者、用于协调沟通的评论线程，以及一条只能追加的活动时间线。 +事故结束后，复盘素材已经准备好了。打开任意事故，即可查看触发证据、负责人与订阅者、就地协调的评论区，以及一条只可追加、不可修改的操作时间线。 -![事故详情视图：父告警与违规摘要、负责人和订阅者、有归属标注的活动时间线，以及评论线程](/agenteye/images/incident-detail.png) -*所有发生过的事，按时间顺序排列，每一行都标注了操作人。* +![事故详情页：父告警与触发摘要、负责人与订阅者、有归属的操作时间线，以及评论区](/agenteye/images/incident-detail.png) +*所有发生的事，按时间顺序排列，每一行都签署了操作人的名字。* -每一个操作（开启、确认、解决等）都会写入时间线，且永远不会被编辑删除。每条记录都有归属：操作员按邮箱标注，由 Failproof AI Observability 自动执行的操作（例如在违规时自动开启事故）则标注为 **automated**。没有匿名记录，没有信息丢失，事后复盘几乎可以自动生成。 +每一个操作（开启、确认、解决等）都会写入时间线，且永不删改。每条记录都有归属：来自某位运营人员的，附上其邮箱；由 Failproof AI Observability 自动触发的（例如在阈值突破时自动开启事故），则标注为 **automated**。没有匿名操作，没有信息丢失，事后复盘因此几乎可以自动完成。 ## 事故的流转方式 @@ -33,18 +33,18 @@ stateDiagram-v2 resolved --> [*] ``` -- **未处理（firing）：** 违规触发事故创建，并向你的渠道发送一次通知。后续重复违规会折叠进同一个事故并刷新证据，不会反复通知。 -- **已确认（acknowledged）：** 操作员接手处理。事故保持开启状态，后续违规会静默更新证据。 -- **已解决（resolved）：** 操作员关闭事故。条件恢复正常后自动解决的功能在规划中，尚未启用，因此事故会保持开启直到有人手动解决——这确保了所有人对实际已恢复情况的诚实判断。之后同一告警可以再次创建新的事故。 +- **开启中（firing）：** 阈值突破后自动创建事故，并向你的渠道发送一次通知。后续重复触发将折叠到同一事故中，仅更新触发证据，不会反复通知。 +- **已确认（acknowledged）：** 某位运营人员接手处理。事故保持开启状态，后续触发将静默更新证据。 +- **已解决（resolved）：** 由运营人员手动关闭。目前尚未启用条件恢复后自动解决的功能，因此事故需由人工解决才会关闭——这确保了所有人对"是否真正恢复"保持清醒认知。同一告警后续可再次开启新的事故。 -同一时间，一条告警最多只能有一个未关闭的事故，因此频繁抖动的规则不会让你淹没在重复事故中。你也可以手动创建事故：既可以是与任何告警无关的独立事故（用于捕捉告警未覆盖的情况），也可以关联到现有告警，前提是你拥有 `incidents:write` 权限。 +同一告警最多同时存在一个开启的事故，因此频繁抖动的规则不会产生大量重复事故。你也可以手动创建事故：可以是独立事故，用于告警未捕获到的情况；也可以附加到已有告警上——前提是拥有 `incidents:write` 权限。 -## 在哪里找到它 +## 如何访问 -事故功能位于 `//incidents`。查看需要 **`incidents:read`** 权限；手动创建事故需要 **`incidents:write`** 权限；确认、分配、评论和解决需要 **`incidents:ack`** 权限。旧版密钥授予的已废弃 `alerts:ack` 权限仍然有效，因为它会被识别为 `incidents:ack`，所以你的值班轮换无需重新下发密钥。 +事故页面位于 `//incidents`。查看需要 **`incidents:read`** 权限；手动创建事故需要 **`incidents:write`** 权限；确认、分配、评论和解决需要 **`incidents:ack`** 权限。已授予已停用的 `alerts:ack` 权限的旧密钥仍可正常使用，因为该权限会被视同 `incidents:ack` 处理，无需重新为值班轮换重新下发密钥。 ## 相关内容 -- [告警](/zh/agenteye/alerts)：当阈值被突破时触发事故的规则。 -- [错误追踪](/zh/agenteye/error-tracking)：在一处查看所有故障，并将其中一个提升为告警。 -- [审计](/zh/agenteye/audits)：定期运行的分析器，用于发现没有规则在监控的故障。 \ No newline at end of file +- [告警](/zh/agenteye/alerts)：当阈值突破时触发事故的规则。 +- [错误追踪](/zh/agenteye/error-tracking)：在一处查看所有故障，并将其提升为告警。 +- [审计](/zh/agenteye/audits)：定期运行的分析器，用于发现任何规则都未覆盖的故障。 \ No newline at end of file diff --git a/docs/zh/agenteye/observability.mdx b/docs/zh/agenteye/observability.mdx index d428e307..7866f370 100644 --- a/docs/zh/agenteye/observability.mdx +++ b/docs/zh/agenteye/observability.mdx @@ -1,23 +1,23 @@ --- -title: "观察" -description: "观察界面让你实时查看 Agent 的运行情况，并深入分析任意单次运行记录。" +title: "观测" +description: "观测界面是您实时查看 Agent 运行状态并深入分析单次运行详情的地方。" --- -观察界面让你实时查看 Agent 的运行情况，并深入分析任意单次运行记录。这里的所有内容都是实时的，以组织为范围，可按日期范围、环境、Agent 和会话进行筛选，让你能在几秒内从"感觉有点不对"定位到具体的运行记录。 +观测界面是您实时查看 Agent 运行状态并深入分析单次运行详情的地方。此处所有内容均为实时数据，按组织范围划分，支持按日期范围、环境、Agent 和会话进行筛选，让您能在几秒内从"感觉有些不对劲"定位到具体的运行记录。 -![实时事件流，按类型进行颜色标注，可按环境、Agent 和会话筛选](/agenteye/images/events-stream.png) +![实时事件流，按类型以颜色区分，支持按环境、Agent 和会话筛选](/agenteye/images/events-stream.png) -四个界面，各有独立页面： +共四个界面，每个界面对应独立页面： -- **[事件流](/zh/agenteye/event-stream)**：所有 Agent 每次运行的实时逐步追踪记录，最新在前。是你组织的首页，也是分诊排查的第一站。 -- **[会话与执行图](/zh/agenteye/sessions)**：将事件汇总为每次运行一行，并以类似 Git 的图形展示每次运行的展开过程。 -- **[性能指标](/zh/agenteye/telemetry)**：模型、工具和 Hook 的延迟热图及 p50/p95/p99 关键指标，让尾部毛刺从中位数中一眼凸显。 -- **[错误追踪](/zh/agenteye/error-tracking)**：统一呈现所有异常情况的分诊界面，一键从触发的告警跳转到出问题的运行记录。 +- **[事件流](/zh/agenteye/event-stream)**：所有 Agent 每次运行的实时逐步记录，最新内容优先显示。这是您的组织主页，也是问题排查的第一站。 +- **[会话与执行图](/zh/agenteye/sessions)**：将事件汇总为每次运行一行的视图，并以类似 git 的图示展示每次运行的展开过程。 +- **[性能指标](/zh/agenteye/telemetry)**：模型、工具和 Hook 的延迟热图及 p50/p95/p99 关键指标，让尾部延迟峰值从中位数中一目了然地凸显出来。 +- **[错误追踪](/zh/agenteye/error-tracking)**：所有异常的统一排查界面，一键从触发的告警跳转到出问题的运行记录。 ## 相关内容 - [评估](/zh/agenteye/evaluations)：对每次运行进行质量评分。 -- [告警](/zh/agenteye/alerts)：将任意阈值转化为告警规则。 -- [审计](/zh/agenteye/audits)：让 Failproof AI Observability 自动为你发现跨会话的故障模式。 +- [告警](/zh/agenteye/alerts)：将任意阈值转化为触发规则。 +- [审计](/zh/agenteye/audits)：让 Failproof AI Observability 自动为您发现跨会话的故障模式。 - [CLI 与 Agent](/zh/agenteye/cli-and-agents)：在终端中获得同等的可观测能力。 \ No newline at end of file diff --git a/docs/zh/agenteye/openclaw-capture.mdx b/docs/zh/agenteye/openclaw-capture.mdx index 0e5b540e..c5883ed0 100644 --- a/docs/zh/agenteye/openclaw-capture.mdx +++ b/docs/zh/agenteye/openclaw-capture.mdx @@ -1,49 +1,49 @@ --- title: "OpenClaw 会话捕获" -description: "将团队本地的 OpenClaw 会话作为普通会话和事件接入 AgentEye，无需更改 OpenClaw 的运行方式。" +description: "将团队本地 OpenClaw 会话以普通会话和事件的形式接入 AgentEye，无需更改 OpenClaw 的任何运行方式。" --- -如果你的团队使用 [OpenClaw](https://docs.openclaw.ai)，OpenClaw 会话捕获功能可将这些会话作为普通会话和事件引入 AgentEye，方便你与其他观测数据一起进行搜索、回放和评估。该功能与 [Python SDK](/zh/agenteye/python-sdk) 互为补充：SDK 用于对你自行编写的 Agent 进行插桩，而本功能则捕获团队日常使用 OpenClaw 所产生的工作内容——无需改变任何使用习惯。 +如果您的团队使用 [OpenClaw](https://docs.openclaw.ai)，OpenClaw 会话捕获功能可将这些会话作为普通会话和事件引入 AgentEye，让您可以与其他所有观测数据一起进行搜索、回放和评估。它与 [Python SDK](/zh/agenteye/python-sdk) 相互补充：SDK 用于对您自己编写的 Agent 进行埋点，而此功能则捕获团队日常 OpenClaw 工作内容——无需改变任何操作方式。 -一个轻量级后台采集器会在 OpenClaw 本地会话记录写入时实时读取，并将其传输至 AgentEye。其工作方式与 [Codex 捕获](/zh/agenteye/codex-capture) 相同，且同一采集器可同时捕获两者。 +一个轻量级后台采集器会实时读取 OpenClaw 在本地写入的会话记录，并将其推送至 AgentEye。其工作方式与 [Codex 捕获](/zh/agenteye/codex-capture) 相同，且单个采集器可同时捕获两者。 --- ## 捕获内容 -机器上 OpenClaw 配置中的每个 Agent 都会被该机器的采集器捕获，无需针对单个 Agent 进行额外配置。 +机器上 OpenClaw 中配置的每个 Agent 均会被该机器的采集器捕获——无需对每个 Agent 单独配置。 -每个 OpenClaw 会话对应 AgentEye 中的一个[会话](/zh/agenteye/sessions)；其用户消息、助手消息、工具调用及工具结果将成为对应的[事件](/zh/agenteye/event-stream)。 +每个 OpenClaw 会话都会成为 AgentEye 中的一个[会话](/zh/agenteye/sessions)；其用户和助手消息、工具调用及工具结果将映射为对应的[事件](/zh/agenteye/event-stream)。 --- -## 开启方式 +## 启用方式 -捕获功能默认关闭，需手动启用。使用具有 `events:add` 权限的 API 密钥（参见 [API 密钥](/zh/agenteye/api-keys)）安装采集器，并开启 OpenClaw 捕获： +捕获功能默认关闭，需手动启用。使用具有 `events:add` 权限的 API 密钥安装采集器（参见 [API 密钥](/zh/agenteye/api-keys)），并开启 OpenClaw 捕获： ```bash curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ | sh -s -- --key --openclaw-enabled ``` -该命令会安装采集器、将其注册为后台服务并开始捕获。确认服务正在运行： +该命令将安装采集器、将其注册为后台服务并开始捕获。确认运行状态： ```bash agenteye-collector health ``` -同一台机器上需捕获多个 Agent？在同一命令中添加各自的标志即可，例如 `--openclaw-enabled --codex-enabled`。 +需要在同一台机器上捕获多个 Agent？在同一命令中添加各自的标志——例如 `--openclaw-enabled --codex-enabled`。 -首次运行时，已有的 OpenClaw 会话会被一次性回填，此后的新活动将在数秒内实时传输。OpenClaw 的本地文件仅供读取，不会被修改、移动或删除；每个会话即使跨越重启也只会被传输一次。 +首次运行时，现有 OpenClaw 会话将被回填一次，之后新活动将在数秒内实时流式传输。采集器对 OpenClaw 的文件仅做读取操作——从不修改、移动或删除——每个会话即使在重启后也只会被推送一次。 --- -## 数据呈现位置 +## 数据呈现 -捕获的会话显示在 **Sessions** 中，其事件显示在 **Events** 流中，与其他被观测的 Agent 完全一致——因此[会话回放](/zh/agenteye/sessions)、[搜索](/zh/agenteye/queries)、[评估](/zh/agenteye/evaluations)和[告警](/zh/agenteye/alerts)均适用。按 OpenClaw Agent 进行筛选可单独查看其数据。 +捕获的会话将出现在 **Sessions** 中，其事件将显示在 **Events** 流中，与其他任何被观测的 Agent 完全一致——因此[会话回放](/zh/agenteye/sessions)、[搜索](/zh/agenteye/queries)、[评估](/zh/agenteye/evaluations)和[告警](/zh/agenteye/alerts)均可对其正常使用。可按 OpenClaw Agent 筛选，单独查看相关内容。 --- ## 隐私说明 -OpenClaw 记录包含完整的会话内容——包括命令输出、文件内容以及 Agent 读写的所有信息——可能涉及敏感数据。捕获的会话将原样传输，因此请仅在适合将相关内容集中存储至 AgentEye 的机器和团队中启用捕获功能，并将采集器的密钥权限限定为仅 `events:add`。有关数据隔离保护措施，请参阅[安全性](/zh/agenteye/security)。 \ No newline at end of file +OpenClaw 记录包含完整的会话内容——包括命令输出、文件内容以及 Agent 读写的所有信息——可能含有敏感凭据。捕获的会话将原样推送，因此请仅在将相关内容集中存储至 AgentEye 确实合适的机器和团队中启用此功能，并为采集器提供仅限 `events:add` 权限的密钥。有关数据隔离机制，请参阅[安全性](/zh/agenteye/security)。 \ No newline at end of file diff --git a/docs/zh/agenteye/overview.mdx b/docs/zh/agenteye/overview.mdx index 14357637..087e454a 100644 --- a/docs/zh/agenteye/overview.mdx +++ b/docs/zh/agenteye/overview.mdx @@ -1,24 +1,24 @@ --- title: "Failproof AI：监控 Agent 故障" -description: "Failproof AI Observability 是一个自托管平台，用于在生产环境中观测、评估和改进您的 AI agent。" +description: "Failproof AI Observability 是一个自托管平台，用于在生产环境中观测、评估和改进您的 AI Agent。" --- -Failproof AI Observability 是一个自托管平台，用于在生产环境中观测、评估和改进您的 AI agent。它记录 agent 的所有行为（每次工具调用、模型请求、hook 和错误），对每次运行的质量进行评分，并在您自己基础设施内运行的仪表板中呈现您未曾预料到的故障。 +Failproof AI Observability 是一个自托管平台，用于在生产环境中观测、评估和改进您的 AI Agent。它记录 Agent 的所有行为（每次工具调用、模型请求、hook 及错误），对每次运行的质量打分，并在您自己基础设施内运行的仪表盘中呈现那些您未曾预料到的故障。 -如果您正在部署 AI agent，并且厌倦了猜测某次运行出错的原因，这就是您的起点。本文将介绍 Failproof AI Observability 能为您提供什么，以及各模块如何协同工作——无需先安装任何东西。 +如果您正在交付 AI Agent，却厌倦了猜测某次运行为何出错，那么这正是您应该开始阅读的页面。它将解释 Failproof AI Observability 能为您提供什么，以及各个模块之间如何协同工作——在您安装任何东西之前。 -> **Failproof AI Observability 是 Failproof AI 的企业级产品。** 想亲眼看看它的效果？申请演示，请发邮件至 [nikita@befailproof.ai](mailto:nikita@befailproof.ai)。 +> **Failproof AI Observability 是 Failproof AI 的企业级产品。** 想亲眼看看效果？请申请演示：发送邮件至 [nikita@befailproof.ai](mailto:nikita@befailproof.ai)。 -![Failproof AI Observability 会话以 git 风格的执行图呈现，旁边是事件时间线，右侧栏按运行维度展示工具、模型和 hook 的详细信息](/agenteye/images/session-detail.png) +![Failproof AI Observability 会话以类似 Git 的执行图形式呈现，旁边是事件时间线，右侧边栏显示每次运行的工具、模型和 hook 详细分解](/agenteye/images/session-detail.png) -*每次 agent 运行均以 git 风格的执行图（左）呈现，旁边配有事件时间线。并行子 agent 各占独立泳道；右侧栏按运行维度列出工具、模型、hook 及 token 消耗明细。* +*每次 Agent 运行都以类似 Git 的执行图（左侧）展示，旁边配有事件时间线。并行子 Agent 各占一条泳道；右侧边栏对该次运行所涉及的工具、模型、hook 及 token 消耗进行明细分解。* --- -## 实际效果演示 +## 观看实际演示 -以下两段简短视频展示了团队最常用的两项功能：追踪单次运行，以及自动发现故障。 +以下两个简短视频展示了团队最常用的两项功能：追踪一次运行，以及自动发现故障。
@@ -30,79 +30,79 @@ Failproof AI Observability 是一个自托管平台，用于在生产环境中
-*Failproof Audit：让 Failproof AI Observability 跨会话挖掘您的日志，并告诉您需要修复的问题。* +*Failproof Audit：让 Failproof AI Observability 挖掘您跨会话的日志，告诉您需要修复什么。* --- -## 团队使用它的理由 +## 为什么团队选择使用它 -- **看清 agent 实际做了什么。** 每次运行都会生成一个可读的 git 风格执行图：哪些工具并行运行、哪些子 agent 分支启动、在哪里卡住，以及消耗了多少资源。 -- **自动捕获质量回归。** 接入一个小型评分服务后，Failproof AI Observability 会对每次完成的运行进行评分，帮助性下降或幻觉激增时会自动浮现。 -- **发现您未曾定义规则的故障。** 周期性审计跨会话挖掘日志，查找错误聚类、延迟异常值、低分运行和卡死任务，并将按优先级排序、附有证据支撑的发现呈现给您。 -- **在关键时刻收到告警。** 基于错误率、延迟、成本或评估分数的阈值规则会触发告警，生成可确认、分配和解决的事件。 -- **用自然语言提问。** 仪表板内置 AI 助手，可以用中文直接询问「本周生产环境的质量趋势如何？」，基于您自己的数据作答。任何变更均需审批方可生效。 -- **数据完全归您所有。** Failproof AI Observability 采用自托管方式：事件、提示词和分析数据始终保存在您掌控的基础设施中。 +- **清晰了解 Agent 的实际行为。** 每次运行都会生成一张可读的、类似 Git 的执行图：哪些工具并行运行，哪些子 Agent 进行了分支，在哪里停滞，以及消耗了什么资源。 +- **自动捕捉质量回退。** 接入一个小型评分服务后，Failproof AI Observability 会对每次完成的运行打分，一旦有用性下降或幻觉率飙升，系统会自动将其呈现出来。 +- **发现您未曾预设规则的故障。** 周期性审计会跨会话挖掘您的日志，寻找错误聚类、延迟异常值、低分项和卡死的运行，然后向您提供有证据支撑的、按优先级排序的发现结果。 +- **在关键时刻及时告警。** 针对错误率、延迟、成本或评估分数的阈值规则触发后，会创建事件，您可以确认、分配和解决。 +- **用普通语言提问。** 仪表盘内置的 AI 助手可以基于您自己的数据回答"本周生产环境中的质量趋势如何？"等问题。它所做的任何变更都需要经过审批。 +- **数据由您掌控。** Failproof AI Observability 采用自托管方式：事件、提示词和分析数据始终保留在您控制的基础设施中。 --- -## 功能概览 +## 您将获得什么 -Failproof AI Observability 围绕三个核心理念组织：**观测（observe）**、**分析（analyze）** 和 **管理（admin）**，并在仪表板左侧边栏中一一对应。 +Failproof AI Observability 围绕三个核心理念（**观测**、**分析**和**管理**）构建，并体现在仪表盘左侧边栏的导航结构中。 -**观测**（运行的原始真相）： +**观测**（还原事实真相）： -- **[事件流](/zh/agenteye/event-stream)**：每次运行的实时逐步记录（工具调用、模型调用、hook、错误）。 -- **[会话](/zh/agenteye/sessions)**：将这些事件汇总为每次运行一行，每行均可评分，并附有 git 风格的执行图。 -- **[性能指标](/zh/agenteye/telemetry)**：按维度划分的延迟热力图，以及模型、工具和 hook 的 p50/p95/p99 关键指标，让尾部延迟从中位数中一眼凸显。 -- **[错误追踪](/zh/agenteye/error-tracking)**：所有异常的统一分类界面，一键直达触发中的告警。 +- **[事件流](/zh/agenteye/event-stream)**：每次运行的实时逐步追踪记录（工具调用、模型调用、hook、错误）。 +- **[会话](/zh/agenteye/sessions)**：将上述事件汇总为每次运行一行，每行均可打分，并附有类似 Git 的执行图。 +- **[性能指标](/zh/agenteye/telemetry)**：针对模型、工具和 hook 的各维度延迟热力图及 p50/p95/p99 关键指标，让尾部延迟峰值从中位数中一目了然地凸显出来。 +- **[错误追踪](/zh/agenteye/error-tracking)**：统一的错误分类处理界面，与触发中的告警仅差一次点击。 -![工具观测页：24 个时间段内的延迟热力图、百分位带和工具分布条形图](/agenteye/images/tools.png) +![工具观测页面：24 个时间段内的延迟热力图、百分位带和工具分布柱状图](/agenteye/images/tools.png) -*每个观测界面均将 p50/p95/p99 关键指标与延迟热力图及百分位带配对展示。图中所示：工具页。* +*每个观测界面均将迷你折线图和 p50/p95/p99 关键指标与延迟热力图及百分位带配对展示。此处显示的是：工具（Tools）。* **分析**（将活动转化为洞察）： -- **[查询](/zh/agenteye/queries)** 和 **[仪表板](/zh/agenteye/dashboards)**：基于事件和评估数据的已保存 SQL 查询，以图表形式呈现在团队共享的组织级仪表板中。 -- **[评估](/zh/agenteye/evaluations)**：由您自己的评估服务产出的质量分数，附带每项评分的推理过程。 -- **[审计](/zh/agenteye/audits)**：周期性调查，跨会话发现故障模式。 -- **[告警](/zh/agenteye/alerts)** 和 **[事件](/zh/agenteye/incidents)**：触发通知的阈值规则，以及用于分类处理的事件工作流。 +- **[查询](/zh/agenteye/queries)** 和 **[仪表盘](/zh/agenteye/dashboards)**：基于您的事件和评估数据的已保存 SQL 查询，以图表形式呈现在组织范围内共享的仪表盘中。 +- **[评估](/zh/agenteye/evaluations)**：由您自己的评估服务产生的质量分数，附带每项分数的推理依据。 +- **[审计](/zh/agenteye/audits)**：周期性调查，跨会话呈现故障模式。 +- **[告警](/zh/agenteye/alerts)** 和 **[事件](/zh/agenteye/incidents)**：触发告警的阈值规则，以及用于分类处理的事件工作流。 -**接口**（以您喜欢的方式访问数据）： +**接口**（以您自己的方式访问数据）： -- **[CLI](/zh/agenteye/cli-and-agents)**：通过终端或脚本驱动整个部署，也可以让编码 agent 用自然语言替您完成操作。 -- **[AI 助手](/zh/agenteye/assistant)**：直接在仪表板内用自然语言询问关于您 agent 的问题。 -- **REST API**：仪表板和 CLI 的所有功能均由 REST API 提供支持，您可以使用有权限范围限制的 [API 密钥](/zh/agenteye/api-keys) 直接调用——摄取事件、查询会话和评估数据、管理仪表板、告警、审计、用户和密钥，将 Failproof AI Observability 接入您自己的工具链。 +- **[CLI](/zh/agenteye/cli-and-agents)**：从终端或脚本驱动整个部署流程，或者让编程 Agent 用普通语言来完成这些操作。 +- **[AI 助手](/zh/agenteye/assistant)**：直接在仪表盘内用普通语言询问关于您的 Agent 的问题。 +- **REST API**：仪表盘和 CLI 的所有功能均由 REST API 支撑，您可以使用有作用域限制的 [API 密钥](/zh/agenteye/api-keys)直接调用——摄取事件、查询会话和评估结果、管理仪表盘、告警、审计、用户和密钥，从而将 Failproof AI Observability 接入您自己的工具链。 -**管理**（为您的团队运维）： +**管理**（为您的团队运营）： -- **[API 密钥](/zh/agenteye/api-keys)**：适用于采集器、仪表板和助手的范围化令牌。 +- **[API 密钥](/zh/agenteye/api-keys)**：用于收集器、仪表盘和助手的作用域令牌。 - **用户**：基于邮件的无密码登录，支持白名单管理。 -- **设置**：组织级配置，包括模型上下文窗口覆盖项。 +- **设置**：组织级配置，包括模型上下文窗口覆盖设置。 --- -## 各模块如何协同 +## 各模块如何协同工作 -数据沿单一方向流动，从您的 agent 代码流向仪表板：您的 agent（通过 Python SDK）将事件发送至 agenteye-collector，后者将事件传输至服务器，服务器再提供仪表板所需的数据。另有两个可选服务作为补充——评分服务（评估）和 AI 助手服务（仪表板内聊天）。 +数据沿单一方向流动，从您的 Agent 代码流向仪表盘：您的 Agent（通过 Python SDK）将事件发送至 agenteye-collector，后者将事件传送至服务器，服务器再为仪表盘提供数据服务。另有两个可选服务作为补充——评分服务（评估）和 AI 助手服务（仪表盘内的对话功能）。 -- **Python SDK**：您在 agent 中添加少量 `agenteye.event.*` 调用，事件会在本地缓冲。 -- **agenteye-collector**：部署在每台 agent 机器上的轻量级守护进程，负责批量打包事件并传输至服务器。 -- **服务器**：接收您的事件，在您自有数据库中维护运营状态，并提供仪表板、CLI 及您自定义集成所使用的 REST API。 -- **仪表板**：您浏览一切数据的地方。 -- **可选服务**：评分服务（评估）和 AI 助手服务（仪表板内聊天）。 +- **Python SDK**：您在 Agent 中添加若干 `agenteye.event.*` 调用；事件会在本地缓冲。 +- **agenteye-collector**：部署在每台 Agent 机器上的轻量级守护进程，负责批量处理事件并将其传送至服务器。 +- **服务器**：摄取您的事件，将运营状态保存在您自己的数据库中，并提供仪表盘、CLI 及您自己的集成所使用的 REST API。 +- **仪表盘**：您探索所有数据的地方。 +- **可选服务**：评分服务（评估）和 AI 助手服务（仪表盘内的对话功能）。 -有关文档中使用的术语（*事件、会话、评估、审计、发现、事件*），请参阅[概念](/zh/agenteye/concepts)。 +关于文档中使用的术语词汇（*事件、会话、评估、审计、发现、事件*），请参阅[概念](/zh/agenteye/concepts)。 --- ## 获取 Failproof AI Observability -Failproof AI Observability 是 Failproof AI 的企业级产品，与 Failproof AI Enforcement（策略与护栏产品）同属 Failproof AI 品牌，并可协同使用。它完全运行在您自己的环境中。如果您尚未获得软件包访问权限，请申请演示，我们将为您完成配置：发送邮件至 [nikita@befailproof.ai](mailto:nikita@befailproof.ai)。 +Failproof AI Observability 是 Failproof AI 的企业级产品，它与 Failproof AI Enforcement（策略与护栏产品）共同归属于 Failproof AI 品牌旗下，完全运行在您自己的环境中。如果您尚未获得软件包访问权限，请申请演示，我们将为您完成配置：发送邮件至 [nikita@befailproof.ai](mailto:nikita@befailproof.ai)。 --- ## 后续步骤 -- [概念](/zh/agenteye/concepts)：Failproof AI Observability 术语的集中说明。 -- [可观测性](/zh/agenteye/observability)：逐次追踪您 agent 的行为。 -- [安全性](/zh/agenteye/security)：Failproof AI Observability 如何确保您的数据隔离并保持在您的掌控之下。 \ No newline at end of file +- [概念](/zh/agenteye/concepts)：Failproof AI Observability 词汇表，一览无余。 +- [可观测性](/zh/agenteye/observability)：逐次运行地追踪您的 Agent 行为。 +- [安全性](/zh/agenteye/security)：Failproof AI Observability 如何确保您的数据隔离并由您掌控。 \ No newline at end of file diff --git a/docs/zh/agenteye/python-sdk-skill.mdx b/docs/zh/agenteye/python-sdk-skill.mdx index 7c99880c..8f2889ac 100644 --- a/docs/zh/agenteye/python-sdk-skill.mdx +++ b/docs/zh/agenteye/python-sdk-skill.mdx @@ -1,76 +1,76 @@ --- title: "Failproof AI Observability Python SDK Agent Skill" -description: "从未插桩的 Agent 到可观测的事件——让你的编码 Agent 找到插桩点、完成编写并验证落地。" +description: "从未插桩的智能体到可观测的事件，由编程智能体找到插桩点、编写代码并验证结果。" --- -告诉你的编码 Agent *"为这个 Agent 添加 Failproof AI Observability"*，让它读取你的循环逻辑，找出插桩位置，完成编写，并在宣告任务完成之前验证事件是否正常产生。 +告诉你的编程智能体 *"为这个智能体添加 Failproof AI Observability"*，让它读取你的循环逻辑，确定插桩位置，编写代码，并在宣告任务完成之前验证事件是否正确落地。 -**Python SDK skill**（`agenteye-python-sdk`）是一个 *Agent Skill*：一个包含指令的文件夹，当任务与之匹配时，Claude Code 或 Codex 等编码 Agent 会按需加载它。它教会 Agent 使用 [Python SDK](/zh/agenteye/python-sdk)——它本身不是一个库，也不会改变 SDK 的任何工作方式。 +**Python SDK skill**（`agenteye-python-sdk`）是一个 *Agent Skill*：一个包含指令的文件夹，供 Claude Code 或 Codex 等编程智能体在任务匹配时按需加载。它教会智能体如何使用 [Python SDK](/zh/agenteye/python-sdk) —— 它本身不是库，也不会改变 SDK 的任何工作方式。 -## 插桩容易写，也容易悄无声息地出错 +## 插桩易写，却也容易悄无声息地出错 -SDK 很小巧：十三个事件方法，全部仅支持关键字参数。编码 Agent 读完 [Python SDK](/zh/agenteye/python-sdk) 参考文档，一分钟内就能写出看似合理的插桩代码。 +SDK 很小巧：十三个事件方法，全部采用仅关键字参数形式。编程智能体阅读 [Python SDK](/zh/agenteye/python-sdk) 参考文档后，能在一分钟内产出看似合理的插桩代码。 -问题在于，这个 SDK 在你出错时不会抛出异常，而错误的插桩和正确的插桩看起来一模一样——直到有人打开仪表板，发现什么都没有。真正浪费时间的错误都是「沉默型」的： +问题在于，这个 SDK 出错时不会抛出异常，错误的插桩看起来与正确的一模一样——直到有人打开仪表盘发现里面空空如也。真正耗费时间的错误全都是沉默： | 错误类型 | 你看到的现象 | |---|---| -| 缺少 `agent_start` | 每个事件都落地，零个 session。 | -| 环境变量从未设置 | 一切正常运行，但都归档在 `dev` 下。 | -| `outcome="failure"` | 运行显示绿色——只有 `failed`、`error`、`timeout`、`rejected` 才会被计入。 | -| 字段名拼写错误 | 被接受并存储为新字段。 | -| 从线程池中发送事件 | 被静默丢弃。 | +| 没有 `agent_start` | 每个事件都落地，但会话数为零。 | +| 环境变量从未设置 | 一切正常运行，但全部归入 `dev`。 | +| `outcome="failure"` 的误用 | 运行显示绿色——只有 `failed`、`error`、`timeout`、`rejected` 才算失败。 | +| 字段名拼写错误 | 被接受并作为新字段存储。 | +| 从线程池中触发事件 | 悄悄丢弃。 | -这些错误都不会抛出异常，也不会在测试中暴露。每一种都已在 skill 中说明，并以合约形式附上对应的检测方法。 +这些错误都不会抛出异常，也不会在测试中暴露。每一种都已写入该 skill，并以合约形式陈述，附有对应的检查项。 ## 它的执行步骤 -该 skill 会执行经验丰富的工程师会做的三个步骤： +该 skill 按照谨慎工程师会采取的三个步骤运行： -1. **规划。** 读取你的 Agent 循环，并提出只有你能回答的两个问题：什么算作一次运行（你的 `session_id`），以及哪些是可区分的执行者（你的 `agent_id`）。它会在开始写代码之前就这些问题达成共识，因为事后修改会导致历史数据分裂，趋势图也会随之断裂。 -2. **编写。** 在每次运行时绑定一次身份，而不是在每个调用点都传递一遍；并选择并发安全的实现方式——这一点很重要，因为看似简便的做法会悄悄地将两个并发运行混入同一个 session，而且毫无提示。 -3. **验证。** 运行你的 Agent，读取生成的事件文件，检查 `agent_start` 是否存在、环境是否正确、一次运行是否对应一个 session。 +1. **规划。** 读取你的智能体循环，并提出只有你能回答的两个问题：什么算作一次运行（你的 `session_id`），以及哪些是可区分的执行者（你的 `agent_id`）。在编写代码之前先就这些达成一致，因为事后修改会拆分历史记录并破坏趋势分析。 +2. **编写。** 每次运行只绑定一次身份，而不是在每个调用点重复传递，并选择并发安全的写法——这个细节很重要，因为显而易见的捷径会悄悄将两个重叠的运行混入同一个会话。 +3. **验证。** 运行你的智能体并读取生成的事件文件，检查 `agent_start` 是否存在、环境是否正确、一次运行是否产生了一个会话。 -第三步是人们最常跳过的。SDK 将事件写入本地文件，因此完整的集成可以在笔记本电脑上、无需服务器、无需 API 密钥、无需网络的情况下得到验证——这正是该 skill 坚持执行这一步的原因。 +第三步是人们最容易跳过的。SDK 将事件写入本地文件，因此完整的集成可以在笔记本电脑上、无需服务器、无需 API 密钥、无需网络的情况下得到验证——这正是该 skill 坚持执行这一步的原因。 -## 它与其他 skill 的关系 +## 与其他 skill 的关系 三个 skill，职责清晰划分： | Skill | 适用场景 | 操作范围 | |---|---|---| -| **Python SDK skill**（本页） | 你想让 Agent *发出*遥测数据——"添加可观测性"、"为什么我的 Agent 没有出现？" | 在你 Agent 的代码仓库中写代码，不读取任何内容。 | -| **[Evaluator skill](/zh/agenteye/evaluator-skill)** | 你想对运行结果*评分*——"我们到底该衡量什么？" | 在你的代码仓库中写代码；读取遥测数据。 | -| **[CLI skill](/zh/agenteye/cli-skill)** | 你想*读取*发生了什么，或者操作你的部署 | 以你的身份驱动 CLI，包括变更操作。 | +| **Python SDK skill**（本页） | 需要让智能体*发出*遥测数据——"添加可观测性"、"为什么我的智能体没有显示？" | 在你的智能体仓库中写代码，不读取任何内容。 | +| **[Evaluator skill](/zh/agenteye/evaluator-skill)** | 需要对运行结果*评分*——"我们到底应该衡量什么？" | 在你的仓库中写代码；读取遥测数据。 | +| **[CLI skill](/zh/agenteye/cli-skill)** | 需要*读取*发生了什么，或操作你的部署 | 以你的身份驱动 CLI，包括变更操作。 | -它们按顺序衔接：本 skill 让事件开始流动，evaluator 对其评分，CLI 读取结果。在你的 Agent 发出 session 之前，没有任何内容可评估，也没有任何内容可读取——所以如果你从零开始，就从这里开始。 +它们按此顺序交接：本 skill 使事件开始流动，evaluator 对其评分，CLI 将其读取回来。在你的智能体开始发出会话之前，既无可评估之物，也无可读取之物——如果你从零开始，就从这里开始。 -## 前置条件 +## 前提条件 -1. **Python 3.10+** 以及你想要插桩的 Agent 代码库。 -2. **SDK。** 它以私有 wheel 包的形式分发给客户，而非通过公共索引——你的入门指南会介绍如何获取和安装它。该 skill 知道安装路径，如果找不到，会向你询问，而不是自行猜测。 -3. **无需其他任何东西。** 不需要登录仪表板、不需要 API 密钥、不需要网络。该 skill 通过 SDK 写入的事件文件进行验证，因此可以在离线状态下完成工作并证明其有效性。 +1. **Python 3.10+** 以及你想要插桩的智能体代码库。 +2. **SDK。** 它以私有 wheel 包的形式分发给客户，而非从公共索引获取——你的入门流程涵盖了如何获取和安装它。该 skill 知道安装路径，如果找不到会询问你，而不是自行猜测。 +3. **无需其他任何东西。** 无需登录仪表盘，无需 API 密钥，无需网络。该 skill 通过 SDK 写入的事件文件进行验证，因此可以在离线状态下完成并证明其工作。 ## 获取方式 -该 skill 位于公开的 [`FailproofAI/skills`](https://github.com/FailproofAI/skills) 集合中： +该 skill 位于公开的 [`FailproofAI/skills`](https://github.com/FailproofAI/skills) 合集中： ```bash npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code ``` -添加 `-g` 可以为所有项目安装，而不仅限于当前项目；如果你的环境不支持符号链接，请添加 `--copy`。对于 Codex，请传入 `-a codex`。 +添加 `-g` 可为所有项目安装，而非仅限当前项目；如果你的环境不支持符号链接，请添加 `--copy`。对于 Codex，传入 `-a codex`。 ## 手动安装 -Agent Skill 是包含 `SKILL.md` 及相关引用文件的文件夹。如果你不想使用安装程序： +Agent Skills 是包含 `SKILL.md` 及相关引用文件的文件夹。如果你不想使用安装程序： -- **Claude Code**：将 `agenteye-python-sdk/` 文件夹复制到 `~/.claude/skills/`（适用于所有项目）或 `/.claude/skills/`（仅适用于该仓库）。Claude Code 会自动发现它——查看 `/skills` 列表，或者直接提问一个与之匹配的问题。 -- **Codex**：Codex 读取相同的 `SKILL.md`。捆绑的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时会自动选中；否则可以通过 `$agenteye-python-sdk` 显式调用。 +- **Claude Code**：将 `agenteye-python-sdk/` 文件夹复制到 `~/.claude/skills/`（所有项目）或 `/.claude/skills/`（仅该仓库）。Claude Code 会自动发现它——查看 `/skills` 列表，或直接提问一个匹配的问题即可。 +- **Codex**：Codex 读取相同的 `SKILL.md`。捆绑的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时会自动选择；否则通过 `$agenteye-python-sdk` 调用。 -**在包含你想要插桩的代码的仓库中**运行你的 Agent——该 skill 在提出任何建议之前会先读取你的 Agent 循环。 +在**包含你要插桩的代码的仓库**中运行你的智能体——该 skill 在提出任何建议之前会先读取你的智能体循环。 -## 一次对话示例 +## 一次会话示例 ```text you ▸ Add Failproof AI Observability to this agent. @@ -103,29 +103,29 @@ agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and Want me to fix those too? ``` -值得关注的模式：它在提出建议之前先读取了代码，只问了你才能回答的问题，复用了你已有的 ID，*因为*看到了线程池而选择了并发安全的实现方式，并且通过**读取实际事件**来验证，而非直接宣告成功——然后还指出了那个已知会悄悄失败的地方。 +值得注意的模式：它在提出建议前先读取了代码，只问了你才能回答的问题，复用了你已有的 ID，*因为*看到了线程池才选择了并发安全的方式，并且**通过读取实际事件来验证**而非直接宣告成功——然后还标记出了它知道会悄悄失败的那一处地方。 ## 你可以问它什么 -- *"为什么我的 Agent 没有出现在仪表板上？"* → 逐层排查：事件是否在写入，`agent_start` 是否存在，环境是否正确，采集器是否在读取同一个位置。 -- *"所有数据都落在 dev 下。"* → 环境变量从未设置，或被后续调用重置了。 -- *"添加 token 追踪。"* → 找到你的 LLM wrapper，记录模型、停止原因和用量。 -- *"也为子 Agent 插桩。"* → 同一个 session，不同的 Agent 标签，嵌套在各自的父级下。 -- *"为插桩代码编写测试。"* → 将 SDK 指向一个临时目录，并对写入的事件进行断言。 +- *"为什么我的智能体没有显示在仪表盘上？"* → 逐层排查：事件是否被写入，`agent_start` 是否存在，环境是否正确，采集器是否读取了同一位置。 +- *"所有内容都落在 dev 下。"* → 环境变量从未设置，或被后续调用重置了。 +- *"添加 token 追踪。"* → 找到你的 LLM 封装并记录模型、停止原因和用量。 +- *"也给子智能体插桩。"* → 一个会话，不同的智能体标签，嵌套在其父级下。 +- *"为插桩写测试。"* → 将 SDK 指向临时目录并对其写入的事件进行断言。 ## 注意事项 -**让它执行验证。** 让这个 skill 物有所值的正是最后一步——运行你的 Agent 并读取事件。一个写完插桩就停下来的 Agent 只做了容易的那一半，而悄悄失败的恰恰是另一半。 +**让它完成验证。** 使这个 skill 有价值的关键在于最后一步——运行你的智能体并读回事件。一个只写插桩代码就停止的智能体只完成了容易的那一半，而悄悄失败的恰恰是另一半。 -**在写代码之前先确定命名。** `session_id` 和 `agent_id` 是所有视图分组的轴。事后重命名会导致历史数据分裂：旧的运行保留旧标签，趋势图随之断裂。该 skill 会主动询问；这个问题值得花一分钟认真思考。 +**在写代码之前先确定好命名。** `session_id` 和 `agent_id` 是每个视图用来分组的轴。事后重命名会拆分历史记录：旧运行保留旧标签，趋势分析随之中断。该 skill 会主动询问，这个问题值得花一分钟认真思考。 -**如果你的 Agent 提议从公共索引安装 SDK，说明 skill 没有加载。** SDK 是私有分发的。这个提议是一个可靠的信号，表明你的编码 Agent 在凭空猜测而非遵循 skill——在那里停下来，检查 skill 是否已正确安装。 +**如果你的智能体提议从公共索引安装 SDK，说明该 skill 未能加载。** SDK 是私有分发的。这种提议是一个可靠的信号，表明你的编程智能体在猜测而非遵循 skill——在那里停下来检查 skill 是否已正确安装。 -除此之外，它的影响范围很小：它在你的工作目录中写代码，在你指定的位置写事件文件。它不读取你的部署内容，也不对其做任何修改。 +除此之外，它的影响范围很小：它只在你的工作目录中写代码，以及在你指定的位置写事件文件。它不读取你的部署中的任何内容，也不对其做任何更改。 ## 下一步 -- **[Python SDK](/zh/agenteye/python-sdk)**：完整的事件参考——本 skill 所自动化的每种事件类型和字段。 -- **[Sessions](/zh/agenteye/sessions)**：事件落地后，你的插桩所产生的内容。 -- **[Evaluator Agent Skill](/zh/agenteye/evaluator-skill)**：运行数据开始积累后的下一步——对其评分。 +- **[Python SDK](/zh/agenteye/python-sdk)**：完整的事件参考文档——本 skill 所自动化处理的每个事件类型和字段。 +- **[Sessions](/zh/agenteye/sessions)**：事件落地后你的插桩所产生的内容。 +- **[Evaluator Agent Skill](/zh/agenteye/evaluator-skill)**：运行数据开始落地后的下一步——对其评分。 - **[CLI Agent Skill](/zh/agenteye/cli-skill)**：读取你的遥测数据。 \ No newline at end of file diff --git a/docs/zh/agenteye/python-sdk.mdx b/docs/zh/agenteye/python-sdk.mdx index 754fb43a..864c08a8 100644 --- a/docs/zh/agenteye/python-sdk.mdx +++ b/docs/zh/agenteye/python-sdk.mdx @@ -1,14 +1,14 @@ --- title: "Python SDK" -description: "精确了解您的 AI 智能体在生产环境中的行为：每次智能体运行、工具调用、模型请求、钩子以及人工干预。" +description: "精确掌握 AI 智能体在生产环境中的每一步行为：每次智能体运行、工具调用、模型请求、hook 及人工干预。" --- -精确了解您的 AI 智能体在生产环境中的行为：每次智能体运行、工具调用、模型请求、钩子以及人工干预。Failproof AI 可观测性 Python SDK 从您的智能体代码内部记录完整的执行轨迹，让您可以调试、审计和评估发生的一切。当您希望 Failproof AI 可观测性监控您的智能体时，请使用此 SDK。 +精确掌握 AI 智能体在生产环境中的每一步行为：每次智能体运行、工具调用、模型请求、hook 及人工干预。Failproof AI 可观测性 Python SDK 从智能体代码内部记录完整追踪链路，便于调试、审计和复盘。如需让 Failproof AI 可观测性监控你的智能体，请使用此 SDK。 -在底层，SDK 将结构化事件写入本地 JSONL 文件，采集器守护进程会自动将这些文件上传到平台。您无需自行管理这些文件。 +SDK 底层将结构化事件写入本地 JSONL 文件，采集器守护进程会自动拾取并上传到平台。你无需自行管理这些文件。 -> **提示：** 刚接触 Failproof AI 可观测性？本页是完整的 SDK 事件参考文档。 +> **提示：** 初次接触 Failproof AI 可观测性？本页即为完整的 SDK 事件参考文档。
@@ -18,15 +18,15 @@ description: "精确了解您的 AI 智能体在生产环境中的行为：每 ## 安装 -SDK 以私有 wheel 包的形式分发给客户，而非通过公共包索引。您的入职培训将涵盖如何获取、安装和固定版本——如需访问权限，请联系您的 Failproof AI 联系人。 +SDK 以私有 wheel 包形式分发给客户，不通过公共包索引发布。获取方式、安装步骤及版本锁定方法均在入门指引中说明——如需获取访问权限，请联系你的 Failproof AI 对接人。 -安装完成后，确认您已成功安装： +安装完成后，执行以下命令确认安装成功： ```bash python -c "import agenteye; print(agenteye.__version__)" ``` -希望让编码智能体完成整个集成工作？[Python SDK Agent Skill](/zh/agenteye/python-sdk-skill) 了解安装路径，能够规划插桩点、编写代码并验证事件是否正确落地。 +希望让编程智能体完成全部集成工作？[Python SDK Agent Skill](/zh/agenteye/python-sdk-skill) 已掌握安装路径，能自动规划埋点位置、编写代码并验证事件是否正确上报。 --- @@ -58,9 +58,9 @@ agenteye.event.tool_result( agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success") ``` -### 为真实调用添加插桩 +### 对真实调用进行插桩 -在实践中，您需要对现有的智能体代码进行包装。在模型调用前后分别发送 `model_request` 和 `model_response` 事件，使这两个事件覆盖真实请求的时间范围，以便 Failproof AI 可观测性将它们配对： +实际使用时，你需要在现有智能体代码外层进行包装。在模型调用前后分别使用 `model_request` 和 `model_response` 进行标记，使这两个事件能够覆盖完整的请求过程，Failproof AI 可观测性便可将它们配对关联： ```python import anthropic @@ -95,11 +95,11 @@ agenteye.event.model_response( ) ``` -工具调用同样使用 `tool_use` 和 `tool_result` 进行包装，并在这一对事件中复用同一个 `tool_call_id`。 +工具调用同理，使用 `tool_use` 和 `tool_result` 进行包装，并在一对事件中复用同一个 `tool_call_id`。 -以下是这些事件到达仪表板后的样式，按类型用颜色区分，并支持按环境、智能体和会话进行筛选： +以下是这些事件在仪表板中的呈现效果——按类型用颜色区分，支持按环境、智能体和会话进行筛选： -![实时事件流，按事件类型颜色编码，可按环境、智能体和会话筛选](/agenteye/images/events-stream.png) +![实时事件流，按事件类型用颜色区分，支持按环境、智能体和会话筛选](/agenteye/images/events-stream.png) --- @@ -107,77 +107,77 @@ agenteye.event.model_response( ```python agenteye.configure( - base_dir=None, # Path | str | None。默认值：$AGENTEYE_HOME 或 ~/.agenteye - flush_interval=0.5, # float，两次刷新之间的秒数 - environment=None, # str | None。部署环境标签 + base_dir=None, # Path | str | None. 默认值：$AGENTEYE_HOME 或 ~/.agenteye + flush_interval=0.5, # float，刷新间隔（秒） + environment=None, # str | None. 部署环境标签 ) ``` -在任何 `event.*` 调用之前调用一次。可以省略；默认值开箱即用。所有参数均为仅限关键字参数；请按上面所示按名称传递。 +在任何 `event.*` 调用之前调用一次。可以省略，开箱即用的默认值即可正常运行。所有参数均为仅关键字参数，请按上述示例以命名方式传入。 -当 `base_dir` 为 `None`（默认值）时，SDK 会读取 `$AGENTEYE_HOME`（如果已设置），否则回退到 `~/.agenteye`。这与采集器自身的解析逻辑一致，因此单个 `AGENTEYE_HOME` 环境变量可同时为 SDK 和采集器配置共享的事件缓冲目录。 +当 `base_dir` 为 `None`（默认值）时，SDK 会优先读取 `$AGENTEYE_HOME` 环境变量（若已设置），否则回退到 `~/.agenteye`。此逻辑与采集器的路径解析一致，因此只需设置一个 `AGENTEYE_HOME` 环境变量，即可同时为 SDK 和采集器配置共享的事件缓冲目录。 --- ## 环境 -为每个事件标记一个部署环境（`production`、`staging`、`qa`、`canary` 等）。设置一次，SDK 会自动将其附加到每个事件上。 +为每个事件标注部署环境（`production`、`staging`、`qa`、`canary` 等）。设置一次后，SDK 会自动将其附加到每个事件上。 -**方式一：通过 `configure()`：** +**方式一：通过 `configure()` 设置：** ```python agenteye.configure(environment="production") ``` -**方式二：通过环境变量：** +**方式二：通过环境变量设置：** ```bash export AGENTEYE_ENVIRONMENT=production ``` -**优先级：** `configure(environment=...)` 优先于环境变量。若两者均未设置，默认为 `"dev"`。 +**优先级：** `configure(environment=...)` 优先于环境变量。若均未设置，默认值为 `"dev"`。 -环境值会作为一级过滤器显示在仪表板中，并存储在服务器上以支持快速查询。 +环境值在仪表板中作为一级筛选条件展示，并存储在服务端以支持快速查询。 -> **警告：** 环境值不得包含字面逗号 `,`。仪表板过滤器在传输时使用逗号分隔的多选格式（`?environment=prod,staging`），因此名为 `prod,blue` 的环境会被拆分为两个值。包含逗号的环境值的事件将在摄取时被拒绝。 +> **警告：** 环境值不得包含英文逗号 `,`。仪表板筛选器在传输层使用逗号分隔的多选格式（`?environment=prod,staging`），因此名为 `prod,blue` 的环境值会被拆分为两个值。包含逗号的环境值在数据摄取时会被拒绝。 --- ## 数据与隐私 -SDK 仅记录您显式传递的字段。提示词、消息、工具输入输出以及模型内容，只有在您将其传递给 `event.*` 调用时才会被捕获。不会从您的进程中读取任何内容，也不会有隐式捕获。您未设置的任何字段将从事件中完全省略，不会写入磁盘。 +SDK 仅记录你显式传入的字段。提示词、消息、工具输入输出及模型内容，只有在你将其传给 `event.*` 调用时才会被捕获。SDK 不会从你的进程中读取任何内容，也不会进行隐式捕获。未设置的字段会从事件中完全省略，不会写入磁盘。 -因此，数据脱敏是您的选择和责任。如果提示词或工具负载中包含您不希望存储的 PII 或密钥，请在将其传递给事件方法之前进行清除或掩码处理。 +因此，数据脱敏是你的选择，也是你的责任。如果提示词或工具载荷中包含你不希望存储的个人信息或密钥，请在传给事件方法之前进行清除或脱敏处理。 --- ## 事件参考 -大多数事件以共享关联 ID 的开始/结束对形式出现：`tool_use` 和 `tool_result` 共享一个 `tool_call_id`，`hook_triggered` 和 `hook_completed` 共享一个 `hook_id`，`human_wait` 和 `human_input` 共享一个 `input_id`。发送开始事件，执行工作，然后使用相同 ID 发送结束事件。Failproof AI 可观测性会自动匹配这一对事件并为您计算 `duration_ms`，因此您无需自行传递 `duration_ms`。 +大多数事件以开始/结束配对的形式出现，并共享一个关联 ID：`tool_use` 和 `tool_result` 共享 `tool_call_id`，`hook_triggered` 和 `hook_completed` 共享 `hook_id`，`human_wait` 和 `human_input` 共享 `input_id`。先触发开始事件，完成操作后再用相同 ID 触发结束事件。Failproof AI 可观测性会自动配对并计算 `duration_ms`，无需你手动传入。 -![会话的 git 风格执行图及其事件时间线（由配对事件重建），以及工具/模型/钩子分解面板](/agenteye/images/session-detail.png) +![会话的类 Git 执行图及其事件时间线（由配对事件重建），附带工具/模型/hook 细分面板](/agenteye/images/session-detail.png) 所有事件方法均需要以下两个字段： | 字段 | 类型 | 描述 | |---|---|---| -| `session_id` | `str` | 标识顶级智能体运行 | -| `agent_id` | `str` | 标识会话中发送该事件的智能体 | +| `session_id` | `str` | 标识顶层智能体运行 | +| `agent_id` | `str` | 标识会话中触发该事件的智能体 | -所有方法还接受任意 `**kwargs` 用于自定义元数据（参见[自定义字段](#custom-fields)）。 +所有方法同样接受任意 `**kwargs` 作为自定义元数据（参见[自定义字段](#custom-fields)）。 --- ### `event.agent_start()` -当智能体开始工作时发送。 +智能体开始工作时触发。 ```python agenteye.event.agent_start( session_id="run-001", agent_id="planner", goal="answer user query", # str | None - parent_id=None, # str | None - 嵌套智能体的父 agent_id + parent_id=None, # str | None - 嵌套智能体的父级 agent_id ) ``` @@ -185,7 +185,7 @@ agenteye.event.agent_start( ### `event.agent_end()` -当智能体完成工作时发送。 +智能体完成工作时触发。 ```python agenteye.event.agent_end( @@ -200,14 +200,14 @@ agenteye.event.agent_end( ### `event.tool_use()` -当智能体调用工具时发送。与 `tool_result` 配对；SDK 自动计算 `duration_ms`。 +智能体调用工具时触发。与 `tool_result` 配对使用，SDK 自动计算 `duration_ms`。 ```python agenteye.event.tool_use( session_id="run-001", agent_id="planner", tool_name="web_search", # str，必填 - tool_call_id="toolu_01", # str，必填 - 与匹配 tool_result 的关联键 + tool_call_id="toolu_01", # str，必填 - 与匹配的 tool_result 的关联键 input={"query": "..."}, # dict | None ) ``` @@ -216,7 +216,7 @@ agenteye.event.tool_use( ### `event.tool_result()` -当工具返回时发送。通过 `tool_call_id` 与 `tool_use` 关联。 +工具返回结果时触发。通过 `tool_call_id` 与 `tool_use` 关联。 ```python agenteye.event.tool_result( @@ -225,8 +225,8 @@ agenteye.event.tool_result( tool_name="web_search", tool_call_id="toolu_01", # 必须与之前的 tool_use 匹配 output={"results": ["..."]}, # Any | None - error=None, # str | None - 若工具抛出异常则设置 - # duration_ms 自动计算 - 请勿传递 + error=None, # str | None - 工具抛出异常时设置 + # duration_ms 自动计算，无需传入 ) ``` @@ -234,36 +234,36 @@ agenteye.event.tool_result( ### `event.model_request()` -在向 LLM 发送提示词之前发送。 +向 LLM 发送提示词之前触发。 ```python agenteye.event.model_request( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串；不做验证 + model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串，不做校验 messages=[ # list[dict] | None - 对话轮次 {"role": "user", "content": "..."}, ], system="You are helpful.", # Any | None - 字符串或内容块列表 - tools=[ # list[dict] | None - 提供给模型的工具模式 + tools=[ # list[dict] | None - 提供给模型的工具 schema {"name": "search", "input_schema": {"type": "object"}}, ], ) ``` -`messages` 条目的 `content` 可以是普通字符串，也可以是 Anthropic 风格的块列表。采样参数（`temperature`、`max_tokens` 等）可作为额外 kwargs 传递。 +`messages` 条目的 `content` 字段支持纯字符串或 Anthropic 风格的内容块列表。采样参数（`temperature`、`max_tokens` 等）可通过额外的 kwargs 传入。 --- ### `event.model_response()` -当 LLM 返回响应时发送。 +LLM 返回响应时触发。 ```python agenteye.event.model_response( session_id="run-001", agent_id="planner", - model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串；不做验证 + model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串，不做校验 stop_reason="end_turn", # str | None input_tokens=1024, # int | None output_tokens=256, # int | None @@ -274,13 +274,13 @@ agenteye.event.model_response( ) ``` -`content` 可以是普通字符串（通用提供商）或 Anthropic 风格的内容块列表。工具调用以 `{"type": "tool_use", ...}` 块的形式存在于 `content` 中，没有单独的 `tool_calls` 字段。 +`content` 支持纯字符串（通用提供商）或 Anthropic 风格的内容块列表。工具调用以 `{"type": "tool_use", ...}` 块的形式存在于 `content` 中，没有单独的 `tool_calls` 字段。 --- ### `event.hook_triggered()` -当钩子触发时发送。与 `hook_completed` 配对；SDK 自动计算 `duration_ms`。 +hook 触发时触发。与 `hook_completed` 配对使用，SDK 自动计算 `duration_ms`。 ```python agenteye.event.hook_triggered( @@ -297,7 +297,7 @@ agenteye.event.hook_triggered( ### `event.hook_completed()` -当钩子完成时发送。通过 `hook_id` 与 `hook_triggered` 关联。 +hook 执行完成时触发。通过 `hook_id` 与 `hook_triggered` 关联。 ```python agenteye.event.hook_completed( @@ -308,7 +308,7 @@ agenteye.event.hook_completed( outcome="allow", # str | None output=None, # Any | None error=None, # str | None - # duration_ms 自动计算 - 请勿传递 + # duration_ms 自动计算，无需传入 ) ``` @@ -316,7 +316,7 @@ agenteye.event.hook_completed( ### `event.error()` -当发生未处理的错误时发送。 +发生未处理的错误时触发。 ```python agenteye.event.error( @@ -330,63 +330,63 @@ agenteye.event.error( --- -## 人在回路事件 +## 人机协作事件 -人在回路事件让您能够监督人员介入智能体执行的关键时刻（等待审批、提供输入、暂停或停止智能体）。通过这些事件，您可以衡量人类响应所需的时间（SDK 会自动为配对事件计算 `duration_ms`），审计谁暂停或中断了智能体，并构建在仪表板中呈现的审批和监督工作流。 +人机协作事件让你能够监控人工介入智能体执行流程的关键时刻（等待审批、提供输入、暂停或终止智能体）。借助这些事件，你可以衡量人工响应时长（SDK 自动计算配对事件的 `duration_ms`）、审计谁暂停或中断了智能体，并构建显示在仪表板上的审批与监督工作流。 ### `event.human_wait()` -当智能体暂停执行以等待人类提供输入时发送。与 `human_input` 配对；SDK 自动计算 `duration_ms`（人类响应所需时间）。 +智能体暂停执行、等待人工输入时触发。与 `human_input` 配对使用，SDK 自动计算 `duration_ms`（即人工响应所用时长）。 ```python agenteye.event.human_wait( session_id="run-001", agent_id="planner", - input_id="inp-abc", # str，必填 - 与匹配 human_input 的关联键 - prompt="Do you approve this action?", # str | None - 展示给人类的问题 - options=["approve", "reject", "defer"], # list[str] | None - 提供给人类的选项 + input_id="inp-abc", # str，必填 - 与匹配的 human_input 的关联键 + prompt="Do you approve this action?", # str | None - 展示给人工的问题 + options=["approve", "reject", "defer"], # list[str] | None - 提供给人工的选项 reason="approval_required", # str | None - 智能体等待的原因 ) ``` ### `event.human_input()` -当人类提供输入且智能体恢复执行时发送。通过 `input_id` 与 `human_wait` 关联。`duration_ms` 自动计算，调用方不得传递。 +人工提供输入、智能体恢复执行时触发。通过 `input_id` 与 `human_wait` 关联。`duration_ms` 自动计算，调用方无需传入。 ```python agenteye.event.human_input( session_id="run-001", agent_id="planner", input_id="inp-abc", # str，必填 - 必须与之前的 human_wait 匹配 - response="approve", # str | None - 人类的回答（自由文本或所选选项） - # duration_ms 自动计算 - 请勿传递 + response="approve", # str | None - 人工的回答（自由文本或所选选项） + # duration_ms 自动计算，无需传入 ) ``` ### `event.human_pause()` -当人类主动暂停智能体时发送（例如通过仪表板控件）。智能体被挂起但未终止。 +人工主动暂停智能体时触发（例如通过仪表板控件）。智能体处于挂起状态，尚未终止。 ```python agenteye.event.human_pause( session_id="run-001", agent_id="planner", reason="user_requested", # str | None - user_id="usr_42", # str | None - 暂停智能体的人 + user_id="usr_42", # str | None - 执行暂停操作的用户 ) ``` ### `event.human_interrupt()` -当人类在执行过程中主动停止智能体时发送。与 `human_pause` 不同，智能体的工作被终止而非挂起。 +人工主动中途停止智能体时触发。与 `human_pause` 不同，智能体的工作被终止而非挂起。 ```python agenteye.event.human_interrupt( session_id="run-001", agent_id="planner", reason="output_incorrect", # str | None - user_id="usr_42", # str | None - 中断智能体的人 - at_step="tool_use:web_search", # str | None - 智能体被停止时正在执行的操作 + user_id="usr_42", # str | None - 执行中断操作的用户 + at_step="tool_use:web_search", # str | None - 被停止时智能体正在执行的操作 ) ``` @@ -394,7 +394,7 @@ agenteye.event.human_interrupt( ## 自定义字段 -任何额外的关键字参数都会在标准字段之后附加到事件中： +任何额外的关键字参数都会追加到标准字段之后： ```python agenteye.event.tool_use( @@ -407,27 +407,27 @@ agenteye.event.tool_use( ) ``` -`timestamp`、`type` 和 `environment` 是保留字段，如果作为自定义字段传递，将引发 `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）。`session_id` 和 `agent_id` 是每个事件方法的必填参数，不能再次提供；若重复传递，Python 会引发 `TypeError`。请使用 `configure(environment=...)` 或 `AGENTEYE_ENVIRONMENT` 变量来设置环境。 +`timestamp`、`type` 和 `environment` 为保留字段，若作为自定义字段传入，将抛出 `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）。`session_id` 和 `agent_id` 是每个事件方法的必填参数，不能二次传入；若重复传入，Python 会抛出 `TypeError`。请通过 `configure(environment=...)` 或 `AGENTEYE_ENVIRONMENT` 环境变量来设置环境值。 -当您希望查询字段内容时，请保持负载为结构化 JSON。JSON 原生不支持的值类型——例如 datetime、UUID、decimal、set、bytes 或模型对象——将被转换为字符串，以确保记录安全继续。 +如需对字段内容进行查询，建议以结构化 JSON 格式存储载荷。JSON 原生不支持的值类型——如 datetime、UUID、Decimal、集合、bytes 或模型对象——会被转换为字符串，确保记录过程不中断。 --- -## 事件的写入方式 +## 事件写入机制 -事件在进程内缓冲，每隔 `flush_interval` 秒（默认 500 毫秒）刷新到磁盘。每次刷新写入一个 JSONL 文件： +事件在进程内缓冲，每隔 `flush_interval` 秒（默认 500 毫秒）刷新一次到磁盘。每次刷新写入一个 JSONL 文件： ```text ~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl ``` -采集器监视此目录并自动上传文件。您无需直接管理这些文件。 +采集器监控该目录并自动上传文件，你无需直接管理这些文件。 -每个文件以原子方式写入：SDK 先写入临时文件，然后将其重命名到位，因此采集器不会看到半写的文件。当您的进程退出时，还会执行最终刷新，确保最后一个间隔内缓冲的事件不会丢失。如果采集器处于离线状态，事件会以文件形式积累在磁盘上，待采集器恢复后自动上传。 +每个文件以原子方式写入：SDK 先写入临时文件，再重命名到目标位置，因此采集器不会读取到写入一半的文件。进程退出时还会执行一次最终刷新，确保最后一个间隔内缓冲的事件不会丢失。如果采集器离线，事件会以文件形式在磁盘上累积，待采集器恢复后统一上传。 --- ## 后续步骤 -- [事件流](/zh/agenteye/event-stream)：实时查看这些事件，按事件类型颜色编码，可按环境、智能体和会话进行筛选。 -- [会话](/zh/agenteye/sessions)：了解配对事件如何将每次智能体运行重建为执行图和时间线。 \ No newline at end of file +- [事件流](/zh/agenteye/event-stream)：实时查看事件到达情况，按类型用颜色区分，支持按环境、智能体和会话筛选。 +- [会话](/zh/agenteye/sessions)：查看配对事件如何将每次智能体运行重建为执行图和时间线。 \ No newline at end of file diff --git a/docs/zh/agenteye/queries.mdx b/docs/zh/agenteye/queries.mdx index b99058fd..5afec845 100644 --- a/docs/zh/agenteye/queries.mdx +++ b/docs/zh/agenteye/queries.mdx @@ -1,56 +1,56 @@ --- title: "查询" -description: "向 Agent 数据提问，秒级获取答案。" +description: "向你的智能体数据提问，几秒内获得答案。" --- -向 Agent 数据提问，秒级获取答案。Failproof AI 可观测性为您提供一个已保存、可直接运行的查询库，覆盖您的事件与评估数据，让您从现成示例出发，而无需面对空白的 SQL 编辑器。 +向你的智能体数据提问，几秒内获得答案。Failproof AI Observability 为你提供一个已保存的、随时可运行的查询库，涵盖你的事件和评估数据，让你从现成的示例出发，而不是面对一个空白的 SQL 编辑器。 -![已保存查询库：一个包含可复用查询的网格视图，涵盖内置预设和自定义查询](/agenteye/images/queries.png) +![已保存查询库：一个可复用查询的网格视图，包含内置预设和自定义查询](/agenteye/images/queries.png) -*您的已保存查询库，位于 `//queries`：内置预设与团队保存的查询并排展示。* +*你的已保存查询库，位于 `//queries`：内置预设与团队自定义保存的查询并排展示。* -## 从预设出发，而非从空白页开始 +## 从预设出发，而不是空白页面 -您无需记忆表名，也无需从零编写 SQL。查询库打开后即展示内置预设，涵盖团队最常提问的问题，并与您团队已保存并命名的查询并排显示。选择一个接近您需求的预设，答案就已触手可及。 +你不需要记住表名，也不需要从头编写 SQL。查询库打开时就展示了内置预设，涵盖团队最常提问的问题，并与你的团队已保存和命名的查询并排显示。选一个接近你需求的预设，大部分问题就迎刃而解。 -每个已保存查询都以组织为作用域并对成员共享，因此您的队友写下的实用查询也会成为您的资源。为查询命名并添加描述后，组织内的任何人都可以找到它、运行它，或将其结果固定到仪表板上。 +每个已保存的查询都属于组织范围并共享，因此团队成员编写的实用查询你也可以直接使用。为查询命名并添加描述后，组织内任何人都可以找到它、运行它，或稍后将其结果固定到仪表盘上。 -访问路径：`//queries`。 +入口地址：`//queries`。 ## 在 SQL 编辑器中调整并运行 -打开任意查询，它会直接加载到 SQL 编辑器中，您可以即时调整并查看结果——无需导出，无需往返传递，无需等待他人。 +打开任意查询，它会直接加载到 SQL 编辑器中，你可以随时调整并立即看到结果：无需导出，无需往返，无需等待他人。 -![SQL 查询编辑器正在运行一个已保存查询，左侧有 Schema 侧边栏，下方有实时结果网格](/agenteye/images/query-lab.png) +![SQL 查询编辑器正在运行一个已保存的查询，左侧为 Schema 侧边栏，下方为实时结果网格](/agenteye/images/query-lab.png) -*SQL 编辑器：左侧是您的查询，Schema 侧边栏让您无需猜测列名，下方是实时结果网格。* +*SQL 编辑器：左侧是你的查询，Schema 侧边栏让你不必猜测列名，下方是实时结果网格。* -- **Schema 侧边栏** 列出分析表及其列名，让您无需翻找字段名即可构建查询。 -- **实时结果网格** 在您运行后立即返回数据行，秒级迭代，告别反复猜测。 -- **只读设计。** 查询在您的事件存储上运行，并在服务器端进行验证：仅允许 `SELECT` 和 `WITH` 语句，同时设有执行超时和行数上限。探索性查询永远不会修改您的数据，失控的查询也会被自动终止。 +- **Schema 侧边栏**列出了分析表及其列名，让你无需到处查找字段名就能构建查询。 +- **实时结果网格**在你运行查询的瞬间返回数据行，让你可以在数秒内迭代，而不是反复猜测。 +- **只读设计。** 查询针对你的事件存储运行，并在服务器端经过验证：仅允许 `SELECT` 和 `WITH` 语句，并设有语句超时和行数上限。探索性查询不会修改你的数据，失控的查询会被自动终止。 -对结果满意？将其保存回查询库，让整个团队共享；或将其输出以折线图、柱状图、面积图或饼图的形式固定到仪表板上。 +对结果满意？将其保存回查询库，让整个团队共享，或将其输出以折线图、柱状图、面积图或饼图的形式固定到仪表盘上。 -## 从终端运行，或让助手来写 +## 从终端运行，或让助手帮你编写 -同样的已保存查询可在您工作的任何地方使用： +已保存的查询可以在你工作的任何地方使用： -- **从终端运行。** `agenteye` CLI 可列出、运行和保存完全相同的查询，您可以将结果输出到脚本中、接入 CI 流程，或传递给编程 Agent。 +- **从终端。** `agenteye` CLI 可以列出、运行和保存完全相同的查询，因此你可以将结果输出到脚本中、接入 CI 流程，或交给编码智能体使用。 ```bash -agenteye query list # 在终端查看相同的已保存查询 -agenteye query run errs --arg prod # 运行并打印数据行（添加 --json 可进行管道传输） +agenteye query list # the same saved queries, from your terminal +agenteye query run errs --arg prod # run one and print the rows (add --json to pipe it) ``` - 完整命令集请参阅 [CLI 与 Agents](/zh/agenteye/cli-and-agents)。 + 完整命令集请参阅 [CLI 与智能体](/zh/agenteye/cli-and-agents)。 -- **从 AI 助手获取。** 不确定如何编写 SQL？用自然语言向仪表板内置的 [AI 助手](/zh/agenteye/assistant) 提问，它会为您起草查询并自动保存到查询库。 +- **从 AI 助手。** 不确定如何表达 SQL？用自然语言向仪表盘内的 [AI 助手](/zh/agenteye/assistant) 提问，它会帮你起草查询并保存到你的查询库中。 -运行已保存查询需要 `queries:run` 权限，该权限与创建或删除查询的权限相互独立，因此您可以授予只读访问权限，而无需允许所有人改写查询库。 +运行已保存查询需要 `queries:run` 权限，该权限与创建或删除查询的权限分开管理，因此你可以授予只读访问权限，而不必让所有人都能修改查询库。 ## 相关内容 -- [仪表板](/zh/agenteye/dashboards)：将查询结果固定为组织共享的图表。 -- [AI 助手](/zh/agenteye/assistant)：用自然语言提问，获取对应查询。 -- [CLI 与 Agents](/zh/agenteye/cli-and-agents)：从终端运行和保存相同的查询。 \ No newline at end of file +- [仪表盘](/zh/agenteye/dashboards)：将查询结果固定为组织共享的图表。 +- [AI 助手](/zh/agenteye/assistant)：用自然语言提问并获得对应查询。 +- [CLI 与智能体](/zh/agenteye/cli-and-agents)：从终端运行和保存相同的查询。 \ No newline at end of file diff --git a/docs/zh/agenteye/security.mdx b/docs/zh/agenteye/security.mdx index 91196f3e..eaf22421 100644 --- a/docs/zh/agenteye/security.mdx +++ b/docs/zh/agenteye/security.mdx @@ -1,68 +1,68 @@ --- title: "安全性" -description: "Failproof AI Observability 被设计为紧邻您的生产环境 Agent 运行，这意味着它能看到您的提示词、工具输入和输出内容。" +description: "Failproof AI Observability 旨在贴近您的生产环境 Agent 运行，因此它能够看到您的提示词、工具输入和输出内容。" --- -Failproof AI Observability 被设计为紧邻您的生产环境 Agent 运行，这意味着它能看到您的提示词、工具输入和输出内容。本页说明它如何确保数据隔离、受控，并始终掌握在您手中。如果您正在对 Failproof AI Observability 进行安全审查评估，请从这里开始。 +Failproof AI Observability 旨在贴近您的生产环境 Agent 运行，因此它能够看到您的提示词、工具输入和输出内容。本页面将介绍它如何保持数据隔离、受控，并始终掌握在您手中。如果您正在对 Failproof AI Observability 进行安全评审，请从这里开始。 --- ## 您的数据保留在您的环境中 -Failproof AI Observability 采用自托管模式。事件、提示词、模型响应和分析数据均存储在您自己的数据库和环境中。数据不会被发送至任何第三方 SaaS 平台存储，始终保留在您自己的云账户内。 +Failproof AI Observability 采用自托管模式。事件、提示词、模型响应和分析数据均存储在您自己的数据库和环境中。不会向任何第三方 SaaS 发送数据进行存储，您的数据始终保留在您自己的云账户中。 --- ## 租户隔离 -一个 Failproof AI Observability 实例可以托管多个组织，每个组织在存储层面相互隔离——这由数据库强制执行，而不仅仅依赖 UI 层面的限制： +一个 Failproof AI Observability 实例可以承载多个组织，每个组织在存储层面相互隔离——由数据库强制执行，而非仅依赖 UI 层面的限制： -- 组织的运营数据（用户、密钥、仪表盘、已保存查询）仅限于该组织访问，跨组织读取由数据库本身拦截阻止。 -- 每个采集的事件都标记了所属组织，因此一个组织的事件永远无法被另一个组织读取。 +- 组织的运营数据（用户、密钥、仪表板、已保存查询）的访问范围限定在该组织内，跨组织读取由数据库本身进行拦截。 +- 每个摄取的事件都带有所属组织的标记，因此一个组织的事件永远不会被另一个组织读取。 -每个仪表盘路由都以组织 slug 为前缀（`//…`）。 +每个仪表板路由都限定在组织 slug 下（`//…`）。 --- ## 登录方式 -Failproof AI Observability 采用无密码、基于邮件的登录方式，不存在可被钓鱼或泄露的密码。用户申请一次性验证码（或一键魔法链接），系统将其发送至用户邮箱，且会在短时间内过期。登录受**白名单**限制：只有您允许的邮箱地址（或域名）才能完成认证。 +Failproof AI Observability 使用基于邮件的无密码登录方式。不存在可被钓鱼或泄露的密码。用户请求一次性验证码（或一键魔法链接），通过邮件发送给用户，且会快速过期。登录受**允许列表**控制：只有您允许的邮箱地址（或域名）才能通过身份验证。 -![Failproof AI Observability 登录界面，将一次性验证码发送至您的邮箱](/agenteye/images/login.png) +![Failproof AI Observability 登录界面，向您的邮箱发送一次性验证码](/agenteye/images/login.png) --- -## 通过 API 密钥实现精细化访问控制 +## 使用 API 密钥进行范围访问 -每个客户端均使用携带精细化最小权限的 API 密钥进行认证。数据采集器只需 `events:add` 权限；仪表盘或助手密钥可设为只读；破坏性操作（删除、重新生成）作为独立权限授予，由您自行决定是否开放。 +每个客户端通过携带精细化最小权限的 API 密钥进行身份验证。数据采集器只需 `events:add` 权限；仪表板或助手密钥可设为只读；破坏性操作（删除、重新生成）是独立的授权项，由您自行决定是否包含。 -![API 密钥页面：每个密钥的权限授予情况，按读取、写入和破坏性范围用颜色区分](/agenteye/images/api-keys.png) +![API 密钥页面：每个密钥的权限授予，按读取、写入和破坏性范围进行颜色标注](/agenteye/images/api-keys.png) -保留管理员引导密钥用于初始配置，其余场景均应颁发权限受限的密钥。详见 [API 密钥](/zh/agenteye/api-keys)。 +管理员引导密钥用于初始设置，其他所有场景请使用权限最小化的密钥。请参阅 [API 密钥](/zh/agenteye/api-keys)。 --- -## 只读、需审批的 AI 助手 +## 只读且需审批的助手 -仪表盘内的 [AI 助手](/zh/agenteye/assistant) 可基于您的数据回答问题，但在设计上受到严格约束： +仪表板内置的 [AI 助手](/zh/agenteye/assistant) 可以对您的数据进行问答，但在设计上受到严格约束： -- **默认只读**：其执行的 SQL 经过守卫过滤，仅允许 `SELECT`/`WITH` 查询，单条语句执行，并设有行数上限。 -- 它创建的任何内容（已保存查询、仪表盘）均需**审批才能生效**：每一次写入操作发生前，您都需要审查并确认。 -- **它永远无法执行删除操作**。 +- **默认只读**：其执行的 SQL 通过守护程序过滤，仅允许 `SELECT`/`WITH` 查询、单条语句，并设有行数上限。 +- 助手创建的任何内容（已保存查询、仪表板）均**需要审批**：每次写操作发生前，您都需要审查并确认。 +- **永远无法执行删除操作**。 -因此，团队成员可以询问"本周哪些 Agent 报错最多？"并基于答案采取行动，而无需担心助手会自行修改或删除您的数据。 +因此，团队成员可以询问"本周哪些 Agent 出错最多？"并根据答案采取行动，而助手无法自行修改或删除您的数据。 --- ## 传输安全 -所有流量均通过 HTTPS 传输。您使用自己的证书终止 TLS，确保采集器到服务器以及浏览器到服务器的流量在传输过程中全程加密。 +所有流量均通过 HTTPS 传输。您使用自己的证书终止 TLS，因此采集器到服务器以及浏览器到服务器的流量在传输过程中均经过加密。 --- ## 后续步骤 - [概览](/zh/agenteye/overview)：了解 Failproof AI Observability 的整体架构。 -- [API 密钥](/zh/agenteye/api-keys)：为采集器、仪表盘和助手配置访问权限。 -- [可观测性](/zh/agenteye/observability)：了解 Failproof AI Observability 从您的 Agent 中采集的数据内容。 \ No newline at end of file +- [API 密钥](/zh/agenteye/api-keys)：为采集器、仪表板和助手设置访问范围。 +- [可观测性](/zh/agenteye/observability)：了解 Failproof AI Observability 从您的 Agent 中捕获哪些数据。 \ No newline at end of file diff --git a/docs/zh/agenteye/sessions.mdx b/docs/zh/agenteye/sessions.mdx index 28d838e0..20dcb59a 100644 --- a/docs/zh/agenteye/sessions.mdx +++ b/docs/zh/agenteye/sessions.mdx @@ -1,56 +1,57 @@ --- title: "会话与执行图" -description: "将一次运行的所有事件汇总为一行可读记录，并以 git 风格的执行图直观呈现，让你几秒内看清全貌。" +description: "将一次运行的所有事件汇总到一行可读记录，并以 git 风格的执行图直观呈现，让你在数秒内掌握全貌。" --- -不再猜测运行失败的原因。Failproof AI 可观测性将一次运行的所有事件汇总为一行可读记录，再将整个运行过程绘制成 git 风格的图示，让你几秒内看清全貌，逐步了解智能体究竟做了什么。 -![会话列表：每次运行占一行，跨越多个环境和智能体，附带状态标签和评估分数徽章](/agenteye/images/sessions-list.png) +不必再猜测运行为何失败。Failproof AI 可观测性功能将一次运行的所有事件汇总为一行可读记录，再将整个运行过程绘制成 git 风格的图示，让你在数秒内清晰看到 Agent 每一步的具体操作。 -*每次运行占一行：状态标签让你一眼看出运行结果，连接评估器后还会显示分数徽章。* +![Sessions 列表：每次运行一行，跨环境与 Agent 展示，附带状态标签和评估分数徽章](/agenteye/images/sessions-list.png) + +*每次运行一行：状态标签让你一眼看出运行结果，接入评估器后还会显示分数徽章。*
-*智能体追踪：从目标到工具调用再到最终答案，逐步跟踪一次完整运行。* +*Agent 追踪：逐步跟踪单次运行，从目标到工具调用，直至最终答案。* --- -## 一眼纵览所有运行 +## 一览所有运行 -原始事件流记录了每一步的真实情况，但当你面对数十次运行中的数千个步骤时，你需要的是运行层面的视图，而不是单步细节。会话页面将一次运行的所有事件汇总为一行，让一天的活动变成一份可快速浏览的列表，而非令人眼花缭乱的信息洪流。 +原始事件流是每个步骤的真实记录，但当你面对数十次运行中的数千个步骤时，你需要的是整次运行的全貌，而不是逐步查看。Sessions 页面将一次运行的所有事件汇总为一行，让一天的活动变成一份可快速浏览的列表，而非铺天盖地的数据流。 -每行都带有状态标签，让失败的运行在你点击之前就能一眼显现。按日期范围、环境、智能体或会话进行筛选，几次点击即可从「全部」缩小到「我关心的那次运行」。 +每行都带有状态标签，让失败的运行在你点击之前就能显眼地与正常运行区分开来。按日期范围、环境、Agent 或会话进行筛选，几次点击即可从"全部显示"定位到"我关心的那次运行"。 -连接评估器后，每次完成的运行都会自动获得评分，最新分数以徽章形式显示在对应行上。你可以按任意分数范围筛选，「显示本周所有低分生产运行」只是一个筛选条件，无需人工逐一查看。在设置评估器之前，会话仍然会完整记录运行过程，只是暂时没有分数。 +接入评估器后，每次已完成的运行都会自动评分，最新分数将以徽章形式显示在对应行上。你可以按任意分数范围筛选，"显示本周所有低分生产运行"只需一个筛选条件，无需人工逐条审查。在设置评估器之前，Sessions 仍会完整记录运行数据，只是暂时不携带分数。 --- -## 以图示读懂整个运行过程 +## 将整次运行读成一张图 -![会话的 git 风格执行图与事件时间线并排显示，右侧面板展示工具、模型和 hook 的详细拆解](/agenteye/images/session-detail.png) +![会话的 git 风格执行图与事件时间轴并排展示，右侧面板展示工具、模型和 hook 的详细分解](/agenteye/images/session-detail.png) -*执行图（左侧）与事件时间线并排显示；右侧栏对本次运行使用的工具、模型、hook 以及 token 消耗进行详细拆解。* +*执行图（左侧）与事件时间轴并排显示；右侧栏按工具、模型、hook 和 Token 消耗对本次运行进行详细分解。* -点击任意会话，即可打开其执行图：这是一个 git 风格的视图，展示了智能体、工具、hook 和模型调用随时间展开的过程。并行的子智能体各自分支到独立的泳道，让你清楚地看到哪些工作是并行执行的、哪个子智能体发生了停滞、以及运行在哪里偏离了预期——无需在脑海中从一堆日志中重新推演。 +点击任意会话可打开其执行图：这是一个 git 风格的视图，展示 Agent、工具、hook 和模型调用随时间展开的完整过程。并行的子 Agent 各自占据独立泳道，让你清晰看到哪些工作是并行进行的、哪个子 Agent 出现了停滞、运行在哪里偏离了预期——无需在脑海中从一墙日志中逐行回放。 -右侧栏提供逐次运行的详细拆解：哪些工具和模型参与了运行、哪些 hook 触发了、以及本次运行消耗了多少 token。「这次运行为什么这么贵？」或「哪个工具最慢？」的答案就在执行图旁边。 +右侧栏提供每次运行的详细分解：运行了哪些工具和模型、触发了哪些 hook、本次运行消耗了多少 Token。这就是"这次运行为什么这么贵？"或"哪个工具最慢？"的答案，就呈现在引发问题的执行图旁边。 -每个单独事件都有固定链接，因此你可以把某一时刻的链接直接分享给他人，而不是说「在那个会话里，大概三分之二的位置」。从任意事件复制链接，或从[审计](/zh/agenteye/audits)发现或错误中跳转，会话将打开并定位到该事件。对于非常长的运行同样适用：时间线出于浏览器性能考虑只加载有限的时间窗口，但指向窗口之外的链接仍然能定位到对应事件，而不是把你扔到最开始。如果该事件已超出你的数据保留窗口，页面会明确提示，而不是静默地选中空白内容。 +每个独立事件都有固定地址，你可以将某一时刻的链接直接分享给他人，而不必说"在这个会话里，大概三分之二的位置"。从任意事件复制链接，或从[审计](/zh/agenteye/audits)发现或错误跳转过来，会话将自动定位并滚动到对应事件。这对于很长的运行同样有效：时间轴会加载一个有限窗口以保证浏览器性能，即便链接指向窗口范围之外的事件，也能精准找到该事件，而不会把你丢在起始位置。如果该事件已超出你的数据保留期，页面会明确告知你，而不是静默地什么都不选中。 --- ## 在哪里找到它 -每个控制台页面都限定在你的组织范围内（`//…`）。会话功能位于左侧边栏的 **Observe** 下，紧邻 Events，列表顶部提供日期范围、环境、智能体和会话等筛选条件。每行点击一次即可进入完整执行图。 +每个仪表板页面都限定在你的组织范围内（`//…`）。Sessions 位于左侧边栏的 **Observe** 下，紧邻 Events，列表顶部提供日期范围、环境、Agent 和会话的筛选条件。每行点击一次即可查看完整执行图。 -要开启分数徽章和按分数范围筛选的功能，请连接评估器，详见[评估](/zh/agenteye/evaluations)。 +要开启分数徽章和分数范围筛选，请接入评估器：参见[评估](/zh/agenteye/evaluations)。 --- ## 相关内容 -- [事件流](/zh/agenteye/event-stream)：每个会话汇总自原始的逐步事件记录。 -- [评估](/zh/agenteye/evaluations)：连接评估器，让每次运行都获得可供筛选的分数徽章。 -- [遥测](/zh/agenteye/telemetry)：了解运行数据如何从你的智能体传入这些会话。 \ No newline at end of file +- [事件流](/zh/agenteye/event-stream)：每个会话汇总所基于的原始逐步事件记录。 +- [评估](/zh/agenteye/evaluations)：接入评估器，为每次运行生成可筛选的分数徽章。 +- [遥测](/zh/agenteye/telemetry)：运行数据如何从你的 Agent 传入这些会话。 \ No newline at end of file diff --git a/docs/zh/agenteye/telemetry.mdx b/docs/zh/agenteye/telemetry.mdx index 11994458..d99e8edb 100644 --- a/docs/zh/agenteye/telemetry.mdx +++ b/docs/zh/agenteye/telemetry.mdx @@ -1,52 +1,52 @@ --- title: "性能指标" -description: "即时发现模型、工具或 hook 的性能下降或费用飙升，在用户察觉之前捕捉尾延迟峰值。" +description: "即时发现模型、工具或 hook 出现性能下降或费用飙升的时刻，在用户感知到长尾延迟峰值之前将其捕获。" --- -即时发现模型、工具或 hook 的性能下降或费用飙升，在用户察觉之前捕捉尾延迟峰值。三个专属页面将原始计时数据转化为一目了然的 p50、p95 和 p99 指标。 +即时发现模型、工具或 hook 出现性能下降或费用飙升的时刻，在用户感知到长尾延迟峰值之前将其捕获。三个专属页面将原始计时数据转化为一目了然的 p50、p95 和 p99 指标。 -![模型页面展示了延迟热力图、百分位数区间，以及每个模型的 token 数量、成本和上下文窗口占用情况](/agenteye/images/models.png) -*模型页面：延迟热力图、百分位数区间，以及每个模型的 token 数量、预估成本和上下文窗口填充情况。* +![Models 页面，展示延迟热力图、百分位带，以及各模型的 token 用量、成本和上下文窗口占用情况](/agenteye/images/models.png) +*Models 页面：延迟热力图、百分位带，以及各模型的 token 用量、预估成本和上下文窗口占用情况。* -## 别让平均值掩盖最糟糕的情况 +## 别让平均值掩盖你的最坏情况 -平均延迟数字看似令人安心，实则毫无意义：它将每五十次调用中那一次导致凌晨两点告警的卡顿全部抹平了。模型、工具和 Hook 页面拒绝这样做。三个页面结构相同，学会一个，其余触类旁通： +平均延迟数字看起来令人安心，实则毫无用处：它掩盖了每五十次调用中那一次让你凌晨两点被叫醒的卡顿。Models、Tools 和 Hooks 页面拒绝这样做。三个页面结构一致，学一次即可掌握： - **24 格迷你折线图**，一眼看出趋势：情况是否在恶化？ -- **核心指标条**，展示 p50、p95 和 p99 延迟，让典型运行时间与尾部延迟并排对比。 -- **延迟热力图**，横轴为 24 个时间段，纵轴为延迟区间，直观呈现慢调用的集中时段。 -- **百分位数区间**：p50 中线配合 p25 至 p75、p10 至 p90 的阴影带以及 p99 散点，让分布情况清晰可见，而非被平均值淹没。 +- **关键指标条**，展示 p50、p95 和 p99 延迟，典型运行和长尾情况并排呈现。 +- **延迟热力图**，横轴为 24 个时间格，纵轴为延迟区间，清晰显示慢速调用的集中时段。 +- **百分位带**：p50 中心线，配以 p25 至 p75 和 p10 至 p90 的阴影色带，以及 p99 散点，让分布情况一目了然而非被平均值掩盖。 -热力图与区间图共享悬停十字准线，尾部延迟峰值在两者中同步对齐，不会藏匿于单一均值线之后。在仪表板的 **observe** 区域可找到这三个页面，均按组织范围划分，支持按日期范围、环境、Agent 和会话进行筛选。 +热力图与百分位带共享悬停十字准线，尾部峰值可在两图中同步对齐，而不会隐藏在单一均值线后面。所有三个页面均位于仪表板的 **observe** 区域，可按组织范围筛选，支持按日期范围、环境、agent 和会话过滤。 -## 模型：精确掌握每个模型的成本 +## Models：精确掌握每个模型的成本 -模型页面（如上图所示）直接回答账单上的两个问题：哪个模型，花了多少钱。在共享延迟视图之上，它还增加了**每模型 token 消耗量**、**预估成本**和**上下文窗口填充情况**，让提示词无节制增长和即将触发的压缩操作在发生之前就能被发现。 +Models 页面（如上图所示）直接回答账单中总会出现的两个问题：用了哪个模型，花了多少钱。在共享延迟视图的基础上，它额外提供**各模型 token 消耗量**、**预估成本**和**上下文窗口占用率**，让失控的 prompt 增长和即将触发的压缩操作在发生前就清晰可见。 -Failproof AI Observability 能自动识别常见的模型 ID。如果某个窗口显示有误，或者您使用的是自有私有模型，可在 **Settings** 的 **model context windows** 中进行修正或添加，填充率读数将随之更新。 +Failproof AI Observability 能自动识别常见的模型 ID。如果某个窗口显示有误，或者你使用的是私有模型，可在 **Settings** 的 **model context windows** 下进行更正或添加，占用率读数将随之更新。 -## 工具：区分慢速与故障 +## Tools：区分慢速与故障 -一次工具调用可能只是速度慢，也可能是在悄悄失败，您希望在几秒内知道是哪种情况，而不是翻遍日志之后才发现。 +一次工具调用可能只是响应慢，也可能是在悄悄失败，你需要在几秒内判断是哪种情况，而不是翻查日志后才弄清楚。 -![工具页面展示了共享的延迟热力图和百分位数区间，以及成功/失败分类统计和工具分布条形图](/agenteye/images/tools.png) -*工具页面：相同的热力图和百分位数区间，加上成功/失败分类统计和工具分布条形图。* +![Tools 页面，展示共享延迟热力图和百分位带，以及成功/失败分布和工具使用分布条](/agenteye/images/tools.png) +*Tools 页面：相同的热力图和百分位带，另加成功/失败分布和工具使用分布条。* -在共享延迟视图的基础上，工具页面额外提供**成功/失败分类统计**和**工具分布条形图**，让您一眼看出哪些工具最常被调用，哪些正在侵蚀您的错误预算。 +在共享延迟视图的基础上，Tools 页面额外提供**成功/失败分布**和**工具使用分布条**，让你一眼看出哪些工具最常被调用，哪些正在消耗你的错误预算。 -## Hook：精准定位具体的 hook 和触发事件 +## Hooks：精准定位具体的 hook 和触发事件 -当某个生命周期 hook 拖慢了运行速度，"hook 太慢了"这样的结论根本无从下手。Hook 页面能帮您直接定位到问题所在。 +当某个生命周期 hook 拖慢了运行速度，"hook 很慢"这个结论无法指导你采取行动。Hooks 页面帮你直接定位到问题所在。 -![Hook 页面在共享热力图和百分位数区间之上，按 hook 名称和触发事件细分延迟数据](/agenteye/images/hooks.png) -*Hook 页面：按 hook 名称和触发事件细分的延迟数据。* +![Hooks 页面，在共享热力图和百分位带上按 hook 名称和触发事件细分延迟](/agenteye/images/hooks.png) +*Hooks 页面：按 hook 名称和触发事件细分的延迟数据。* -在相同的延迟热力图和百分位数区间之上，Hook 页面将活动按 **hook 名称**和**触发事件**进行细分，让您精准锁定需要关注的单个 hook 和单个事件。 +在相同的延迟热力图和百分位带之上，Hooks 页面将活动按 **hook 名称**和**触发事件**细分，让你直接定位到需要关注的那一个 hook 和那一个事件。 ## 相关内容 -- [事件流](/zh/agenteye/event-stream)：每个事件的实时彩色追踪记录。 -- [会话](/zh/agenteye/sessions)：将事件汇总为每次运行一行，并打开其执行图。 -- [错误追踪](/zh/agenteye/error-tracking)：统一处理仪表板标红的所有问题。 -- [仪表板](/zh/agenteye/dashboards)：跨全局的汇总视图。 \ No newline at end of file +- [事件流](/zh/agenteye/event-stream)：每个事件的实时彩色轨迹。 +- [Sessions](/zh/agenteye/sessions)：将事件汇总为每次运行一行记录，并查看其执行图。 +- [错误追踪](/zh/agenteye/error-tracking)：仪表板中所有标红内容的统一分诊界面。 +- [Dashboards](/zh/agenteye/dashboards)：跨整个集群的汇总视图。 \ No newline at end of file diff --git a/docs/zh/architecture.mdx b/docs/zh/architecture.mdx index 4efc2e0c..6cc9127e 100644 --- a/docs/zh/architecture.mdx +++ b/docs/zh/architecture.mdx @@ -1,21 +1,21 @@ --- title: 架构 -description: "Hook 处理器、配置加载和策略评估的内部工作原理" +description: "Hook 处理器、配置加载及策略评估的内部工作原理" icon: sitemap --- -本文档介绍 failproofai 的内部工作机制：Hook 系统如何拦截 Agent 工具调用、配置如何加载与合并、策略如何评估，以及仪表盘如何监控 Agent 活动。 +本文档介绍 failproofai 的内部工作原理：hook 系统如何拦截代理工具调用、如何加载和合并配置、如何评估策略，以及仪表板如何监控代理活动。 --- -## 概述 +## 概览 failproofai 包含两个独立的子系统： -1. **Hook 处理器** - 一个快速的 CLI 子进程，Claude Code 在每次 Agent 工具调用时都会调用它。负责评估策略并返回决策结果。 -2. **Agent 监控器（仪表盘）** - 一个用于监控 Agent 会话和管理策略的 Next.js Web 应用。 +1. **Hook 处理器** - 一个轻量级 CLI 子进程，由 Claude Code 在每次代理工具调用时触发，负责评估策略并返回决策结果。 +2. **Agent Monitor（仪表板）** - 一个 Next.js Web 应用，用于监控代理会话和管理策略。 -两个子系统共享 `~/.failproofai/` 和项目 `.failproofai/` 目录中的配置文件，但它们作为独立进程运行，仅通过文件系统进行通信。 +两个子系统共享 `~/.failproofai/` 和项目 `.failproofai/` 目录中的配置文件，但作为独立进程运行，仅通过文件系统进行通信。 --- @@ -23,7 +23,7 @@ failproofai 包含两个独立的子系统： ### 与 Claude Code 的集成 -运行 `failproofai policies --install` 后，它会在 `~/.claude/settings.json` 中写入如下配置： +运行 `failproofai policies --install` 后，它会将如下条目写入 `~/.claude/settings.json`： ```json { @@ -44,7 +44,7 @@ failproofai 包含两个独立的子系统： } ``` -Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` 作为子进程调用，并通过 stdin 传入 JSON 数据。 +随后，Claude Code 会在每次工具调用前将 `failproofai --hook PreToolUse` 作为子进程调用，并通过 stdin 传入 JSON 数据。 ### 数据格式 @@ -60,9 +60,9 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` } ``` -对于 `PostToolUse` 事件，数据中还包含 `tool_result` 字段，内容为工具的输出。 +对于 `PostToolUse` 事件，数据中还包含 `tool_result` 字段，内含工具的输出内容。 -处理器对 stdin 强制执行 1 MB 的大小限制。超出限制的数据将被丢弃，所有策略默认隐式允许。 +处理器对 stdin 限制最大 1 MB。超出此限制的数据将被丢弃，所有策略默认隐式允许。 ### 响应格式 @@ -85,7 +85,7 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` } ``` -**指令（除 Stop 事件外的任意事件）：** +**指令（除 Stop 事件外的所有事件）：** ```json { "hookSpecificOutput": { @@ -94,7 +94,7 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` } ``` -**Stop 事件的指令：** +**Stop 事件指令：** - 退出码：`2` - 原因写入 stderr（而非 stdout） @@ -102,9 +102,9 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` - 退出码：`0` - stdout 为空 -**携带消息的允许：** +**允许并附带消息：** -`allow(message)` 允许策略在操作被许可时仍向 Claude 发送信息性上下文。Hook 处理器将以下 JSON 写入 **stdout**（这不是配置文件——这是处理器对 Claude Code 的响应，与上述拒绝和指令响应格式相同）： +`allow(message)` 允许策略在操作被允许时仍向 Claude 发送信息性上下文。Hook 处理器将以下 JSON 写入 **stdout**（这不是配置文件——这是处理器向 Claude Code 返回的响应，与 deny 和 instruct 响应的方式相同）： ```json // 由 hook 处理器进程写入 stdout @@ -115,8 +115,8 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` } ``` - 退出码：`0`（操作被允许） -- 当多个策略返回携带消息的 `allow` 时，消息将以换行符拼接为单个 `additionalContext` 字符串 -- 如果没有策略提供消息，stdout 为空（与之前相同） +- 若多个策略均返回带消息的 `allow`，其消息将以换行符连接，合并为单个 `additionalContext` 字符串 +- 若没有策略提供消息，stdout 为空（与原来相同） ### 处理流程 @@ -128,18 +128,18 @@ stdin JSON → 提取会话元数据（session_id、cwd、tool_name、tool_input 等） → readMergedHooksConfig(cwd) ← 合并项目 + 本地 + 全局配置 → 注册已启用的内置策略及其解析后的参数 - → 从 customPoliciesPath 加载自定义策略（如已设置） + → 从 customPoliciesPath 加载自定义策略（若已设置） → 将自定义策略注册到策略注册表 - → 评估所有策略（先内置策略，再自定义策略） - → 首个 deny 触发短路 - → instruct 决策累积 - → allow 消息累积 + → 评估所有策略（先内置策略，后自定义策略） + → 首个 deny 会短路后续评估 + → instruct 决策持续累积 + → allow 消息持续累积 → 将 JSON 决策写入 stdout → 将事件持久化到 ~/.failproofai/hook-activity/current.jsonl → 退出 ``` -对于典型数据，整个过程在 100ms 内完成，无需任何 LLM 调用。 +对于典型数据且无 LLM 调用的情况，整个处理过程在 100ms 以内完成。 --- @@ -154,39 +154,39 @@ stdin JSON ``` 合并逻辑： -- `enabledPolicies` - 对三个文件取去重并集 -- `policyParams` - 按策略键，以第一个定义它的文件为准 -- `customPoliciesPath` - 以第一个定义它的文件为准 -- `llm` - 以第一个定义它的文件为准 +- `enabledPolicies` - 对三个文件进行去重并集 +- `policyParams` - 按策略键，第一个定义该键的文件完全优先 +- `customPoliciesPath` - 第一个定义它的文件优先 +- `llm` - 第一个定义它的文件优先 -Web 仪表盘使用 `readHooksConfig()`（仅全局）进行读写，因为它不以项目 cwd 调用。 +由于 Web 仪表板在调用时没有项目 cwd，因此它使用 `readHooksConfig()`（仅全局）进行读写。 --- ## 策略评估 -`src/hooks/policy-evaluator.ts` 按顺序运行策略。 +`src/hooks/policy-evaluator.ts` 按顺序执行策略。 -对每个策略： +对每条策略： -1. 查找策略的 `params` 模式（如有）。 -2. 从合并配置中读取 `policyParams[policy.name]`。 -3. 将用户提供的值与模式默认值合并，生成 `ctx.params`。 +1. 查找该策略的 `params` schema（如有）。 +2. 从合并后的配置中读取 `policyParams[policy.name]`。 +3. 将用户提供的值覆盖 schema 默认值，生成 `ctx.params`。 4. 以解析后的上下文调用 `policy.fn(ctx)`。 5. 若结果为 `deny`，立即停止并返回该决策。 6. 若结果为 `instruct`，累积消息并继续。 -7. 若结果为 `allow`，继续处理下一个策略。 +7. 若结果为 `allow`，继续评估下一条策略。 -所有策略运行完毕后： -- 若有任何 `deny` 被返回，则发出拒绝响应。 -- 若收集到任何 `instruct` 返回，则将所有消息合并后发出单个指令响应。 -- 否则，发出允许响应（stdout 为空，退出码为 0）。 +所有策略执行完毕后： +- 若有任何 `deny` 被返回，输出 deny 响应。 +- 若收集到任何 `instruct` 返回，将所有消息合并后输出单个 instruct 响应。 +- 否则，输出 allow 响应（stdout 为空，退出码 0）。 --- ## 内置策略 -`src/hooks/builtin-policies.ts` 将全部 39 个内置策略定义为 `BuiltinPolicyDefinition` 对象： +`src/hooks/builtin-policies.ts` 将全部 39 条内置策略定义为 `BuiltinPolicyDefinition` 对象： ```typescript interface BuiltinPolicyDefinition { @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -接受 `params` 的策略会声明一个 `PolicyParamsSchema`，其中包含每个参数的类型和默认值。策略评估器在调用 `fn` 之前会将解析后的值注入 `ctx.params`。策略函数读取 `ctx.params` 时无需空值守护，因为默认值始终会被优先应用。 +接受 `params` 的策略会声明一个 `PolicyParamsSchema`，为每个参数定义类型和默认值。策略评估器在调用 `fn` 前会将解析后的值注入 `ctx.params`。由于默认值始终会先被应用，策略函数读取 `ctx.params` 时无需进行空值检查。 -策略内部的模式匹配使用解析后的命令标记（argv），而非原始字符串匹配。这可以防止通过 shell 运算符注入绕过策略（例如，`sudo systemctl status *` 的匹配模式无法通过在命令末尾追加 `; rm -rf /` 来绕过）。 +策略内部的模式匹配使用已解析的命令 token（argv），而非原始字符串匹配。这可防止通过 shell 操作符注入绕过规则（例如，针对 `sudo systemctl status *` 的模式无法通过在命令后追加 `; rm -rf /` 来绕过）。 --- ## 自定义策略 -`src/hooks/custom-hooks-registry.ts` 实现了一个基于 `globalThis` 的注册表： +`src/hooks/custom-hooks-registry.ts` 实现了基于 `globalThis` 的注册表： ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -229,21 +229,21 @@ export function clearCustomHooks(): void { ... } // 用于测试 1. 从配置中读取 `customPoliciesPath`；若不存在则跳过。 2. 解析为绝对路径；检查文件是否存在。 -3. 将所有 `from "failproofai"` 导入重写为实际的 dist 路径，使 `customPolicies` 解析到同一个 `globalThis` 注册表。 -4. 递归重写传递的本地导入，以确保 ESM 兼容性。 -5. 写入临时 `.mjs` 文件并 `import()` 入口文件。 -6. 调用 `getCustomHooks()` 获取已注册的 Hook。 +3. 将所有 `from "failproofai"` 的导入重写为实际的 dist 路径，使 `customPolicies` 能解析到同一个 `globalThis` 注册表。 +4. 递归重写可传递的本地导入，以确保 ESM 兼容性。 +5. 写入临时 `.mjs` 文件并通过 `import()` 加载入口文件。 +6. 调用 `getCustomHooks()` 获取已注册的 hook。 7. 在 `finally` 块中清理所有临时文件。 -发生任何错误（文件未找到、语法错误、导入失败）时，错误将被记录到 `~/.failproofai/hook.log`，加载器返回空数组。内置策略不受影响。 +任何错误（文件未找到、语法错误、导入失败）都会被记录到 `~/.failproofai/hook.log`，加载器返回空数组，内置策略不受影响。 -自定义策略在所有内置策略之后评估。自定义策略的 `deny` 仍会短路后续自定义策略（但此时所有内置策略已运行完毕）。 +自定义策略在所有内置策略执行完毕后才进行评估。自定义策略的 `deny` 仍会短路后续自定义策略的评估（但此时所有内置策略均已运行完毕）。 --- ## 活动日志 -每次 Hook 事件后，处理器会向 `~/.failproofai/hook-activity/current.jsonl` 追加一行 JSONL 记录，当该文件达到分页大小时，会轮转为 `page--.jsonl`： +每次 hook 事件结束后，处理器会向 `~/.failproofai/hook-activity/current.jsonl` 追加一行 JSONL 记录，当该文件达到分页大小时，会轮转为 `page--.jsonl`： ```json { @@ -258,44 +258,44 @@ export function clearCustomHooks(): void { ... } // 用于测试 } ``` -每行对应一个做出非允许决策的策略。允许决策不会被记录（以保持文件精简）。 +每行记录一条非 allow 决策。Allow 决策不记录（以保持文件体积精简）。 --- -## 仪表盘架构 +## 仪表板架构 -仪表盘是一个 **Next.js 16** 应用，使用 App Router，并结合了 React 服务端组件和服务端 Actions。 +仪表板是一个使用 App Router 的 **Next.js 16** 应用，采用 React Server Components 和 Server Actions。 ```text app/ layout.tsx ← 根布局（主题、遥测、导航） - projects/page.tsx ← 服务端组件：列出所有 Claude 项目 - project/[name]/page.tsx ← 服务端组件：列出项目中的会话 + projects/page.tsx ← Server component：列出所有 Claude 项目 + project/[name]/page.tsx ← Server component：列出项目内的会话 project/[name]/session/ - [sessionId]/page.tsx ← 服务端组件：渲染会话查看器 - policies/page.tsx ← 客户端组件：策略管理 + 活动日志 + [sessionId]/page.tsx ← Server component：渲染会话查看器 + policies/page.tsx ← Client component：策略管理 + 活动日志 actions/ - get-hooks-config.ts ← 读取配置和策略列表 + get-hooks-config.ts ← 读取配置及策略列表 update-hooks-config.ts ← 启用/禁用策略 update-policy-params.ts ← 更新策略参数 get-hook-activity.ts ← 分页/搜索活动日志 - install-hooks-web.ts ← 从浏览器安装/移除 Hook + install-hooks-web.ts ← 通过浏览器安装/移除 hook api/ download/[project]/[session]/route.ts ← 单个 CLI 会话导出（JSONL 或 JSON） ``` **数据流：** -- 页面组件调用 `lib/projects.ts` 和 `lib/log-entries.ts` 直接从文件系统读取项目/会话数据（读操作无需 API 层）。 -- 策略页面使用服务端 Actions 处理所有数据变更（切换、参数更新、安装/移除）。 -- 会话查看器解析 Claude 的 JSONL 转录格式，并渲染消息和工具调用的时间线。 +- 页面组件调用 `lib/projects.ts` 和 `lib/log-entries.ts`，直接从文件系统读取项目/会话数据（读取操作无需 API 层）。 +- Policies 页面使用 Server Actions 处理所有变更操作（切换、参数更新、安装/移除）。 +- 会话查看器解析 Claude 的 JSONL 转录格式，并以时间线方式渲染消息和工具调用。 **关键设计决策：** -- 无数据库——所有持久化状态均存储在纯文本文件中（`~/.failproofai/`、`~/.claude/projects/`）。 -- 数据变更使用服务端 Actions——CRUD 操作无需 REST API。 -- 读取页面使用 React 服务端组件——首次加载更快，无需客户端数据获取 bundle。 -- 仅在需要交互的地方使用客户端组件（策略切换、活动搜索、日志查看器）。 +- 无数据库——所有持久状态均存储在普通文件中（`~/.failproofai/`、`~/.claude/projects/`）。 +- 使用 Server Actions 处理变更——无需为 CRUD 操作构建 REST API。 +- 读取页面使用 React Server Components——更快的首屏加载，数据获取无需客户端 bundle。 +- 仅在需要交互的地方使用 Client Components（策略切换、活动搜索、日志查看器）。 --- @@ -307,26 +307,26 @@ failproofai/ │ └── failproofai.mjs # CLI 路由器（hook / dashboard / install 等） ├── src/hooks/ │ ├── handler.ts # Hook 事件处理流程 -│ ├── builtin-policies.ts # 39 个策略定义 +│ ├── builtin-policies.ts # 39 条策略定义 │ ├── policy-evaluator.ts # 策略执行引擎 │ ├── policy-registry.ts # 策略注册与查找 -│ ├── policy-types.ts # TypeScript 接口 -│ ├── hooks-config.ts # 多作用域配置加载 -│ ├── custom-hooks-registry.ts # 基于 globalThis 的 Hook 注册表 -│ ├── custom-hooks-loader.ts # 用户 JS Hook 的 ESM 加载器 +│ ├── policy-types.ts # TypeScript 接口定义 +│ ├── hooks-config.ts # 多级作用域配置加载 +│ ├── custom-hooks-registry.ts # 基于 globalThis 的 hook 注册表 +│ ├── custom-hooks-loader.ts # 用户 JS hook 的 ESM 加载器 │ ├── manager.ts # 安装/移除/列出操作 │ ├── install-prompt.ts # 交互式策略选择提示 -│ ├── hook-logger.ts # 日志写入 hook.log +│ ├── hook-logger.ts # 写入 hook.log 的日志记录 │ ├── hook-activity-store.ts # 将活动持久化到 hook-activity/ │ └── llm-client.ts # LLM API 客户端（用于 AI 驱动的策略） -├── app/ # Next.js 仪表盘（页面 + 服务端 Actions） -├── lib/ # 共享工具函数 +├── app/ # Next.js 仪表板（页面 + Server Actions） +├── lib/ # 共享工具库 │ ├── projects.ts # 从文件系统枚举 Claude 项目 │ ├── log-entries.ts # 解析 Claude 转录 JSONL 格式 │ ├── paths.ts # 解析系统路径 │ └── ... ├── components/ # 共享 React UI 组件 -├── contexts/ # React 上下文提供者（主题、自动刷新、遥测） -├── examples/ # 自定义 Hook 示例文件 -└── __tests__/ # 单元测试和端到端测试 +├── contexts/ # React context providers（主题、自动刷新、遥测） +├── examples/ # 自定义 hook 示例文件 +└── __tests__/ # 单元测试与端到端测试 ``` \ No newline at end of file diff --git a/docs/zh/built-in-policies.mdx b/docs/zh/built-in-policies.mdx index eb3c82e5..0f82a417 100644 --- a/docs/zh/built-in-policies.mdx +++ b/docs/zh/built-in-policies.mdx @@ -4,19 +4,19 @@ description: "涵盖常见 Agent 故障模式的全部 39 条内置策略" icon: shield --- -failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式。每条策略会在特定的钩子事件类型和工具名称上触发。其中 19 条策略支持参数配置，让你无需编写代码即可调整其行为。5 条工作流策略会在 Claude 停止前强制执行提交 → 推送 → PR → CI 的流水线。 +failproofai 内置 39 条策略，用于捕获常见的 Agent 故障模式。每条策略针对特定的钩子事件类型和工具名称触发。其中 19 条策略支持参数配置，无需编写代码即可调整行为。5 条工作流策略在 Claude 停止前强制执行提交 → 推送 → PR → CI 的流水线。 --- -## 概述 +## 概览 -策略按以下类别分组： +策略按类别分组： | 类别 | 策略 | 钩子类型 | |----------|----------|-----------| | [危险命令](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse | | [基础设施命令](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [密钥（清洗器）](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [密钥（清理器）](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [环境](#environment) | block-env-files, protect-env-vars | PreToolUse | | [文件访问](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | @@ -26,16 +26,14 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 | [工作流](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | - **`block-`** — 阻止 Agent 继续执行。 -- **`warn-`** — 为 Agent 提供额外上下文，使其能够自我纠正。 -- **`sanitize-`** — 在 Agent 看到工具输出之前，清除其中的敏感数据。 +- **`warn-`** — 向 Agent 提供额外上下文，以便其自我纠正。 +- **`sanitize-`** — 在 Agent 看到工具输出之前清除其中的敏感数据。 ### 命名空间 -每条策略都位于 `/` 插槽中。内置策略属于 -**`failproofai/`** 命名空间，例如 `failproofai/sanitize-jwt`。 -命名空间可防止你同时加载具有相似短名称的自定义或第三方策略时发生冲突。 +每条策略都位于一个 `/` 插槽中。内置策略属于 **`failproofai/`** 命名空间，例如 `failproofai/sanitize-jwt`。命名空间可防止当你同时加载短名称相似的自定义或第三方策略时发生冲突。 -在配置中，你可以通过短名称或完整限定名来引用内置策略，两种形式指向同一条策略： +在配置中，你可以用短名称或完全限定名称引用内置策略，两种形式解析到同一条策略： ```json { @@ -46,39 +44,39 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 } ``` -如果名称中不含 `/`，failproofai 会将其视为属于默认命名空间 `failproofai`。已经包含 `/` 的名称（如 `myorg/foo`、`custom/my-hook`）则保持原样。 -- **`require-`** — 阻止 Stop 事件，直到满足相应条件。 +如果名称中没有 `/`，failproofai 会将其视为属于默认命名空间 `failproofai`。已包含 `/` 的名称（例如 `myorg/foo`、`custom/my-hook`）保持原样。 +- **`require-`** — 在条件满足之前阻止 Stop 事件。 --- -每条策略在 `policyParams` 中都支持可选的 `hint` 字段。该提示会附加到 Claude 看到的 deny 或 instruct 消息中，提供可操作的指导，而无需修改策略代码。适用于内置、自定义和约定策略。详见[配置 → hint](/zh/configuration#hint-cross-cutting)。 +每条策略在 `policyParams` 中都支持可选的 `hint` 字段。该提示会附加到 Claude 收到的 deny 或 instruct 消息中，提供可操作的指导，无需修改策略代码。适用于内置策略、自定义策略和约定策略。详见[配置 → hint](/zh/configuration#hint-cross-cutting)。 --- ## 危险命令 -防止 Agent 运行难以撤销或可能损害宿主系统的操作。 +阻止 Agent 执行难以撤销或可能损坏宿主系统的操作。 ### `block-sudo` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝任何 `sudo` 或 `doas` 命令。 -阻止在**命令位置**运行提权二进制文件的命令。匹配方式是结构化的而非文本化的：命令会像 shell 一样被拆分为片段，前缀赋值（`FOO=bar`）、重定向以及带有标志的运行器（`env`、`nohup`、`timeout`、`xargs`、`sh -c` 等）都会被跳过，然后将结果二进制文件按**基本名称**进行比较。因此 `/usr/bin/sudo`、`env sudo`、`timeout 5 sudo`、`"sudo"`、`\sudo` 和 `bash -c "sudo …"` 都会被拒绝，`doas` 则被视为拥有相同能力的不同名称。 +阻止在**命令位置**运行提权二进制文件的命令。匹配基于结构而非文本：命令会按 shell 方式拆分为片段，前缀赋值（`FOO=bar`）、重定向以及带标志的运行器（`env`、`nohup`、`timeout`、`xargs`、`sh -c` 等）会被剥离，然后按**基名**比较最终的二进制文件。因此 `/usr/bin/sudo`、`env sudo`、`timeout 5 sudo`、`"sudo"`、`\sudo` 和 `bash -c "sudo …"` 均会被拒绝，`doas` 也被视为具有相同权限的不同名称。 -由于它锚定在命令位置而非单词出现在任何地方，因此**不会**在仅提及该词的命令上触发——`grep -r sudo /etc`、`cat /etc/sudoers`、`git commit -m "fix sudo handling"` 或包含该词的 `grep` 交替模式都可以正常运行。 +由于策略锚定在命令位置而非单词出现的任意位置，它**不会**在命令中仅提及该词时触发——`grep -r sudo /etc`、`cat /etc/sudoers`、`git commit -m "fix sudo handling"` 或包含该词的 `grep` 交替表达式均可正常运行。 -这只能阻止显而易见的尝试，并不能关闭所有攻击路径。能够运行任意 shell 的 Agent 仍然可以间接实现提权——通过变量（`S=sudo; $S …`）、base64 解码管道或磁盘上的包装脚本——因为对单个命令字符串的检查无法追踪这些路径。请将此视为防止误操作和随意提权的护栏，而非针对蓄意 Agent 的安全边界。真正的安全边界必须在 shell 层之下强制执行。 +此策略阻止的是明显的提权尝试，并不能封闭所有路径。能够运行任意 shell 的 Agent 仍可通过间接方式提权——通过变量（`S=sudo; $S …`）、base64 解码管道或磁盘上的包装脚本——因为对单条命令字符串的检查无法跟踪这些路径。请将此策略视为防范误操作和随意提权的护栏，而非对抗蓄意 Agent 的安全边界。真正的安全边界必须在 shell 层之下强制执行。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许通过的精确命令前缀。每个条目与解析后的 argv 令牌进行匹配。 | +| `allowPatterns` | `string[]` | `[]` | 允许的精确命令前缀。每个条目与解析后的 argv 标记进行匹配。 | **示例：** @@ -92,22 +90,22 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 } ``` -使用此配置后，`sudo systemctl status nginx` 被允许，但 `sudo rm /etc/hosts` 被拒绝。 +使用此配置，`sudo systemctl status nginx` 被允许，但 `sudo rm /etc/hosts` 被拒绝。 -模式匹配的是解析后的令牌，而非原始命令字符串。这可以防止通过附加 shell 操作符绕过（例如 `sudo systemctl status x; rm -rf /` 不匹配 `sudo systemctl status *`）。 +模式与解析后的标记匹配，而非原始命令字符串。这可防止通过追加 shell 运算符绕过（例如 `sudo systemctl status x; rm -rf /` 不匹配 `sudo systemctl status *`）。 --- ### `block-rm-rf` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝 `rm -rf`、`rm -fr` 及类似的递归删除形式。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `allowPaths` | `string[]` | `[]` | 允许递归删除的安全路径（例如 `/tmp`）。 | @@ -127,7 +125,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-curl-pipe-sh` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝 `curl | bash`、`curl | sh`、`wget | bash` 及类似模式。 无参数。 @@ -136,7 +134,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-failproofai-commands` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝会卸载或禁用 failproofai 自身的命令（例如 `npm uninstall failproofai`、`failproofai policies --uninstall`）。 无参数。 @@ -145,12 +143,12 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-self-pause` -**事件：** PreToolUse（Bash） -**默认行为：** 拒绝 `failproofai config --pause`，该命令会在会话中暂停策略执行。暂停应由人工决定——能够运行该命令的 Agent 可以通过一条命令关闭所有其他策略。 +**事件：** PreToolUse (Bash) +**默认行为：** 拒绝 `failproofai config --pause`，该命令会在会话期间暂停策略执行。暂停是人类的决策——能够运行此命令的 Agent 可以通过一条命令关闭所有其他策略。 -比 [`block-failproofai-commands`](#block-failproofai-commands) 范围更窄，且不被其覆盖：该策略锚定在命令边界，因此 `npx -y failproofai config --pause` 不会匹配它；并且由于范围较广，该策略常被关闭以便 Agent 运行 `failproofai audit`。`--resume` 和 `--status` 是被允许的——两者都不会移除策略执行。 +有意比 [`block-failproofai-commands`](#block-failproofai-commands) 更窄，且不被其覆盖：该策略锚定在命令边界，因此 `npx -y failproofai config --pause` 不匹配它；由于范围较宽，它通常被关闭以便 Agent 运行 `failproofai audit`。`--resume` 和 `--status` 被允许——两者均不会移除策略执行。 -这只能阻止直接尝试，而非整个攻击类别：Agent 仍可通过别名或包装脚本达到相同状态。要彻底关闭该漏洞，需要让 pause 操作完全无法通过工具调用触达。 +此策略阻止直接尝试，而非封闭整个类别：Agent 仍可通过别名或包装脚本达到相同状态。要完全封闭，需要在工具调用层面使暂停功能完全不可达。 无参数。 @@ -158,20 +156,20 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ## 基础设施命令 -阻止编码 Agent 运行基础设施 CLI 或触发 CI/CD 流水线。此类别中的所有策略均为**按需启用**（`defaultEnabled: false`）——合理需要调用 `kubectl`、`terraform` 等的 Agent 不会受到影响，除非你明确启用该策略。启用后，匹配 CLI 的每次调用都会被拒绝，除非命令与 `allowPatterns` 中的条目匹配。 +阻止编码 Agent 运行基础设施 CLI 或触发 CI/CD 流水线。此类别中的所有策略均为**按需启用**（`defaultEnabled: false`）——合法需要调用 `kubectl`、`terraform` 等工具的 Agent 不会受到干扰，除非你启用了相应策略。启用后，除非命令匹配 `allowPatterns` 中的条目，否则所有匹配 CLI 的调用均被拒绝。 -模式语法与 [`block-sudo`](#block-sudo) 相同：令牌与解析后的 argv 进行匹配，`*` 为单个令牌的通配符，任何包含独立 shell 操作符（`&&`、`||`、`|`、`;`）或嵌入了 shell 元字符的令牌的命令，在白名单匹配之前都会被拒绝，以防止注入绕过。 +模式语法与 [`block-sudo`](#block-sudo) 相同：标记与解析后的 argv 匹配，`*` 是单个标记的通配符，包含独立 shell 运算符（`&&`、`||`、`|`、`;`）或嵌入 shell 元字符的标记在白名单匹配之前会被拒绝，以防止注入绕过。 ### `block-kubectl` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝任何 `kubectl` 调用。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许通过的 kubectl 命令前缀。 | +| `allowPatterns` | `string[]` | `[]` | 允许的 kubectl 命令前缀。 | **示例：** @@ -185,20 +183,20 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 } ``` -使用此配置后，`kubectl get pods` 被允许，但 `kubectl apply -f deploy.yaml` 被拒绝。 +使用此配置，`kubectl get pods` 被允许，但 `kubectl apply -f deploy.yaml` 被拒绝。 --- ### `block-terraform` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝任何 `terraform` 或 `tofu`（OpenTofu）调用。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许通过的 terraform/tofu 命令前缀。 | +| `allowPatterns` | `string[]` | `[]` | 允许的 terraform/tofu 命令前缀。 | **示例：** @@ -216,14 +214,14 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-aws-cli` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝任何 `aws` CLI 调用。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许通过的 aws CLI 命令前缀。 | +| `allowPatterns` | `string[]` | `[]` | 允许的 aws CLI 命令前缀。 | **示例：** @@ -241,14 +239,14 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-gcloud` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝任何 `gcloud`（Google Cloud）CLI 调用。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许通过的 gcloud 命令前缀。 | +| `allowPatterns` | `string[]` | `[]` | 允许的 gcloud 命令前缀。 | **示例：** @@ -266,14 +264,14 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-az-cli` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝任何 `az`（Azure）CLI 调用。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许通过的 az CLI 命令前缀。 | +| `allowPatterns` | `string[]` | `[]` | 允许的 az CLI 命令前缀。 | **示例：** @@ -291,14 +289,14 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-helm` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝任何 `helm` 调用。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许通过的 helm 命令前缀。 | +| `allowPatterns` | `string[]` | `[]` | 允许的 helm 命令前缀。 | **示例：** @@ -316,7 +314,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-gh-pipeline` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝以下会改变状态或触发流水线的 `gh` CLI 子命令： - `gh workflow run`、`gh workflow enable`、`gh workflow disable` @@ -326,13 +324,13 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 - `gh cache delete` - `gh secret set`、`gh secret delete` -只读的 `gh` 子命令，如 `gh pr view`、`gh pr list`、`gh run list`、`gh release view` 和 `gh api repos/.../...`，**不**在本策略的匹配范围内——它们是工作流检查（包括 failproofai 自身的 `require-ci-green-before-stop`）的常规需求。 +只读的 `gh` 子命令（例如 `gh pr view`、`gh pr list`、`gh run list`、`gh release view` 和 `gh api repos/.../...`）**不**被此策略匹配——它们是工作流检查（包括 failproofai 自身的 `require-ci-green-before-stop`）所必需的常规操作。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许通过的特定脚本调用，即使它们原本会被拒绝。 | +| `allowPatterns` | `string[]` | `[]` | 允许执行的特定脚本化调用，即使它们原本会被拒绝。 | **示例：** @@ -348,14 +346,14 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 --- -## 密钥（清洗器） +## 密钥（清理器） -防止 Agent 将凭据泄露到其上下文或输出中。清洗器策略在 **PostToolUse** 事件上触发。当 Claude 运行 Bash 命令、读取文件或调用任何工具时，这些策略会在输出返回给 Claude 之前对其进行检查。如果检测到密钥模式，策略将返回拒绝决定，阻止输出被传回。 +防止 Agent 将凭据泄露到其上下文或输出中。清理器策略在 **PostToolUse** 事件时触发。当 Claude 运行 Bash 命令、读取文件或调用任何工具时，这些策略会在输出返回给 Claude 之前对其进行检查。如果检测到密钥模式，策略会返回拒绝决定，阻止输出被传回。 ### `sanitize-jwt` **事件：** PostToolUse（所有工具） -**默认行为：** 删除 JWT 令牌（以 `.` 分隔的三段 base64url）。 +**默认行为：** 编辑 JWT 令牌（由 `.` 分隔的三个 base64url 片段）。 无参数。 @@ -364,11 +362,11 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `sanitize-api-keys` **事件：** PostToolUse（所有工具） -**默认行为：** 删除常见 API 密钥格式：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS 访问密钥（`AKIA`）、Stripe 密钥（`sk_live_`、`sk_test_`）以及 Google API 密钥（`AIza`）。 +**默认行为：** 编辑常见 API 密钥格式：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS 访问密钥（`AKIA`）、Stripe 密钥（`sk_live_`、`sk_test_`）和 Google API 密钥（`AIza`）。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | 需要视为密钥的额外正则表达式模式。 | @@ -392,7 +390,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `sanitize-connection-strings` **事件：** PostToolUse（所有工具） -**默认行为：** 删除包含嵌入式凭据的数据库连接字符串（例如 `postgresql://user:password@host/db`）。 +**默认行为：** 编辑包含嵌入凭据的数据库连接字符串（例如 `postgresql://user:password@host/db`）。 无参数。 @@ -401,7 +399,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `sanitize-private-key-content` **事件：** PostToolUse（所有工具） -**默认行为：** 删除 PEM 块（`-----BEGIN PRIVATE KEY-----`、`-----BEGIN RSA PRIVATE KEY-----` 等）。 +**默认行为：** 编辑 PEM 块（`-----BEGIN PRIVATE KEY-----`、`-----BEGIN RSA PRIVATE KEY-----` 等）。 无参数。 @@ -410,7 +408,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `sanitize-bearer-tokens` **事件：** PostToolUse（所有工具） -**默认行为：** 删除令牌长度为 20 个字符及以上的 `Authorization: Bearer ` 请求头。 +**默认行为：** 编辑 `Authorization: Bearer ` 标头中令牌长度达到 20 个或更多字符的情况。 无参数。 @@ -418,14 +416,14 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ## 环境 -防止 Agent 读取或暴露敏感的环境配置。 +保护敏感的环境配置，防止 Agent 读取或暴露它们。 ### `block-env-files` **事件：** PreToolUse（Bash、Read） **默认行为：** 拒绝通过 `cat .env`、以 `.env` 为文件路径的 `Read` 工具调用等方式读取 `.env` 文件。 -不会阻止 `.envrc` 或其他与环境相关的文件，仅针对名称完全为 `.env` 的文件。 +不阻止 `.envrc` 或其他环境相关文件——仅阻止名称完全为 `.env` 的文件。 无参数。 @@ -433,7 +431,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `protect-env-vars` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝打印环境变量的命令：`printenv`、`env`、`echo $VAR`。 无参数。 @@ -442,16 +440,16 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ## 文件访问 -让 Agent 在项目边界内工作，远离敏感文件。 +将 Agent 限制在项目边界内，并阻止其访问敏感文件。 ### `block-read-outside-cwd` **事件：** PreToolUse（Read、Bash） -**默认行为：** 拒绝读取项目根目录以外的文件。边界由 `CLAUDE_PROJECT_DIR`（由 Claude Code 在每个会话开始时设置一次）决定，当该变量未设置时，回退到会话的当前工作目录。使用项目根目录而非实时 `cwd` 意味着即使 Claude `cd` 进入子目录，边界也保持稳定。 +**默认行为：** 拒绝读取项目根目录之外的文件。边界为 `CLAUDE_PROJECT_DIR`（由 Claude Code 在每个会话开始时设置一次），当该变量未设置时，回退到会话的当前工作目录。使用项目根目录而非实时 `cwd` 意味着即使 Claude `cd` 进入子目录，边界也保持稳定。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `allowPaths` | `string[]` | `[]` | 即使在项目根目录之外也允许访问的绝对路径前缀。 | @@ -472,11 +470,11 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-secrets-write` **事件：** PreToolUse（Write、Edit） -**默认行为：** 拒绝向常用于存储私钥和证书的文件写入：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。 +**默认行为：** 拒绝写入通常用于存储私钥和证书的文件：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `additionalPatterns` | `string[]` | `[]` | 需要阻止的额外文件名模式（glob 风格）。 | @@ -500,12 +498,12 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-push-master` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝 `git push origin main` 和 `git push origin master`。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | 不允许直接推送的分支名称。 | @@ -522,19 +520,19 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ``` -要允许推送到所有分支（即在不从 `enabledPolicies` 中移除此策略的情况下禁用它），请设置 `protectedBranches: []`。 +若要允许推送到所有分支（实际上是在不从 `enabledPolicies` 中移除此策略的情况下将其禁用），可将 `protectedBranches` 设置为 `[]`。 --- ### `block-work-on-main` -**事件：** PreToolUse（Bash） -**默认行为：** 在工作树位于 `main` 或 `master` 分支时，拒绝 `git commit`、`git merge`、`git rebase` 和 `git cherry-pick`。分支创建和切换（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）不受影响。 +**事件：** PreToolUse (Bash) +**默认行为：** 当工作树位于 `main` 或 `master` 分支时，拒绝 `git commit`、`git merge`、`git rebase` 和 `git cherry-pick`。分支创建和切换（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）不受影响。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | 禁止执行 commit/merge/rebase/cherry-pick 的分支名称。 | @@ -542,10 +540,10 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `block-force-push` -**事件：** PreToolUse（Bash） +**事件：** PreToolUse (Bash) **默认行为：** 拒绝 `git push --force` 和 `git push -f`。 -无策略专属参数。可使用通用的 [`hint`](/zh/configuration#hint-cross-cutting) 建议替代方案： +无策略特定参数。使用通用 [`hint`](/zh/configuration#hint-cross-cutting) 建议替代方案： ```json { @@ -561,8 +559,8 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `warn-git-amend` -**事件：** PreToolUse（Bash） -**默认行为：** 在运行 `git commit --amend` 时，提示 Claude 谨慎操作。不阻止该命令。 +**事件：** PreToolUse (Bash) +**默认行为：** 当运行 `git commit --amend` 时，指示 Claude 谨慎操作。不阻止该命令。 无参数。 @@ -570,8 +568,8 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `warn-git-stash-drop` -**事件：** PreToolUse（Bash） -**默认行为：** 在运行 `git stash drop` 前，提示 Claude 进行确认。不阻止该命令。 +**事件：** PreToolUse (Bash) +**默认行为：** 在运行 `git stash drop` 之前，指示 Claude 进行确认。不阻止该命令。 无参数。 @@ -579,8 +577,8 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `warn-all-files-staged` -**事件：** PreToolUse（Bash） -**默认行为：** 在运行 `git add -A` 或 `git add .` 时，提示 Claude 检查正在暂存的内容。不阻止该命令。 +**事件：** PreToolUse (Bash) +**默认行为：** 当运行 `git add -A` 或 `git add .` 时，指示 Claude 审查所暂存的内容。不阻止该命令。 无参数。 @@ -588,12 +586,12 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ## 数据库 -在破坏性 SQL 操作对数据库执行之前拦截它们。 +在破坏性 SQL 操作对数据库执行之前将其捕获。 ### `warn-destructive-sql` -**事件：** PreToolUse（Bash） -**默认行为：** 在运行包含 `DROP TABLE`、`DROP DATABASE` 或不带 `WHERE` 子句的 `DELETE` 的 SQL 之前，提示 Claude 进行确认。 +**事件：** PreToolUse (Bash) +**默认行为：** 在运行包含 `DROP TABLE`、`DROP DATABASE` 或不带 `WHERE` 子句的 `DELETE` 的 SQL 之前，指示 Claude 进行确认。 无参数。 @@ -601,8 +599,8 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `warn-schema-alteration` -**事件：** PreToolUse（Bash） -**默认行为：** 在运行 `ALTER TABLE` 语句之前，提示 Claude 进行确认。 +**事件：** PreToolUse (Bash) +**默认行为：** 在运行 `ALTER TABLE` 语句之前，指示 Claude 进行确认。 无参数。 @@ -610,18 +608,18 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ## 警告 -在执行潜在风险但非破坏性操作之前，为 Agent 提供额外上下文。 +在潜在有风险但非破坏性的操作之前为 Agent 提供额外上下文。 ### `warn-large-file-write` -**事件：** PreToolUse（Write） -**默认行为：** 在写入超过 1024 KB 的文件之前，提示 Claude 进行确认。 +**事件：** PreToolUse (Write) +**默认行为：** 在写入大于 1024 KB 的文件之前，指示 Claude 进行确认。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | 触发警告的文件大小阈值（KB）。 | +| `thresholdKb` | `number` | `1024` | 触发警告的文件大小阈值（单位：千字节）。 | **示例：** @@ -636,15 +634,15 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ``` -钩子处理程序对 stdin 载荷强制执行 1 MB 的大小限制。若要使用较小的内容测试此策略，请将 `thresholdKb` 设置为远低于 1024 的值。 +钩子处理器对载荷强制执行 1 MB 的 stdin 限制。若要用小内容测试此策略，请将 `thresholdKb` 设置为远低于 1024 的值。 --- ### `warn-package-publish` -**事件：** PreToolUse（Bash） -**默认行为：** 在运行 `npm publish` 之前，提示 Claude 进行确认。 +**事件：** PreToolUse (Bash) +**默认行为：** 在运行 `npm publish` 之前，指示 Claude 进行确认。 无参数。 @@ -652,8 +650,8 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `warn-background-process` -**事件：** PreToolUse（Bash） -**默认行为：** 在通过 `nohup`、`&`、`disown` 或 `screen` 启动后台进程时，提示 Claude 注意。 +**事件：** PreToolUse (Bash) +**默认行为：** 在通过 `nohup`、`&`、`disown` 或 `screen` 启动后台进程时，指示 Claude 保持谨慎。 无参数。 @@ -661,8 +659,8 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `warn-global-package-install` -**事件：** PreToolUse（Bash） -**默认行为：** 在运行 `npm install -g`、`yarn global add` 或未使用虚拟环境的 `pip install` 之前，提示 Claude 进行确认。 +**事件：** PreToolUse (Bash) +**默认行为：** 在运行 `npm install -g`、`yarn global add` 或未在虚拟环境中使用 `pip install` 之前，指示 Claude 进行确认。 无参数。 @@ -670,21 +668,21 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ## 包管理器 -强制限定 Agent 可以使用的包管理器。 +强制规定 Agent 允许使用的包管理器。 ### `prefer-package-manager` -**事件：** PreToolUse（Bash） -**默认行为：** 禁用。启用后，阻止任何不在 `allowed` 列表中的包管理器命令，并告知 Claude 使用允许的包管理器重写该命令。 +**事件：** PreToolUse (Bash) +**默认行为：** 已禁用。启用后，阻止任何不在 `allowed` 列表中的包管理器命令，并告知 Claude 使用允许的管理器重写该命令。 -可检测：pip、pip3、python -m pip、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。 +检测范围：pip、pip3、python -m pip、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。 -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | 允许使用的包管理器名称。任何检测到的不在此列表中的包管理器都会被阻止。为空时，策略为空操作。 | -| `blocked` | string[] | `[]` | 除内置列表之外需要额外阻止的包管理器名称（例如 `['pdm', 'pipx']`）。 | +| `allowed` | string[] | `[]` | 允许的包管理器名称。任何检测到的不在此列表中的管理器均被阻止。为空时，策略不生效。 | +| `blocked` | string[] | `[]` | 除内置列表之外需要额外阻止的管理器名称（例如 `['pdm', 'pipx']`）。 | -内置阻止列表包含：pip、pip3、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。使用 `blocked` 可追加不在此列表中的包管理器。 +内置阻止列表涵盖：pip、pip3、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。使用 `blocked` 追加不在此列表中的管理器。 **配置示例：** @@ -700,7 +698,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 } ``` -使用此配置后，`pip install flask` 和 `pdm install flask` 都会被拒绝，并提示 Claude 改用 `uv` 或 `bun`。`uv pip install flask` 这样的命令则被允许，因为 `uv` 在白名单中且优先检查。 +使用此配置，`pip install flask` 和 `pdm install flask` 均被拒绝，并提示 Claude 改用 `uv` 或 `bun`。`uv pip install flask` 等命令被允许，因为 `uv` 在白名单中且优先检查。 --- @@ -711,7 +709,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `warn-repeated-tool-calls` **事件：** PreToolUse（所有工具） -**默认行为：** 当同一工具使用相同参数被调用 3 次及以上时，提示 Claude 重新考虑——这通常是 Agent 陷入循环的常见信号。 +**默认行为：** 当同一工具以相同参数被调用 3 次或以上时，指示 Claude 重新考虑——这是 Agent 陷入循环的常见迹象。 无参数。 @@ -719,39 +717,39 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ## 工作流 -强制执行规范的会话结束工作流。这些策略在 **Stop** 事件上触发，在满足各项条件之前阻止 Agent 停止。它们遵循自然的依赖链：提交 → 推送 → PR → CI。如果某条策略拒绝，链中后续策略将被跳过（拒绝短路）。 +强制执行严格的会话结束工作流。这些策略在 **Stop** 事件时触发，在每个条件满足之前阻止 Agent 停止。它们遵循自然的依赖链：提交 → 推送 → PR → CI。如果某条策略拒绝，链中后续策略将被跳过（拒绝短路）。 -所有工作流策略都是**失败开放**的：如果所需工具不可用（例如未安装 `gh`、无 git 远程仓库），策略将允许通过，并附上解释为何跳过检查的信息消息。 +所有工作流策略均为**失败开放**：如果所需工具不可用（例如未安装 `gh`、无 git 远程仓库），策略允许通过并提供信息消息说明跳过检查的原因。 ### 各 CLI 的 Stop 语义 -由于六个支持的 CLI 各自公开了不同的"Agent 完成"钩子契约，Stop 强制执行在各 CLI 上的表现略有不同。**结果**是一致的——Agent 无法在工作流门控失败的情况下停止——但**机制**有所不同。下表作了简要说明；只有 Pi 存在一个值得在启用 `require-*-before-stop` 策略前了解的用户可见行为差异。 +Stop 执行在六种受支持的 CLI 中表现略有不同，因为每种 CLI 暴露的"Agent 完成"钩子契约不同。**结果**是相同的——Agent 在工作流门控失败时无法停止——但**机制**有所差异。下表总结了各 CLI 的情况；只有 Pi 存在一个值得在启用 `require-*-before-stop` 策略前了解的用户可见特性。 -| CLI | 门控触发时机 | 你看到的情况 | +| CLI | 门控触发时机 | 你看到的效果 | |---|---|---| -| Claude Code | 同一 Agent 循环中，立即触发 | Claude 继续工作——修复问题后再次尝试完成。对你不可见。 | -| Codex | 同一 Agent 循环中，立即触发 | 与 Claude 相同。 | -| GitHub Copilot CLI | 同一 Agent 循环中，立即触发 | 与 Claude 相同（使用 Copilot 的 `{decision:"block", reason}` 重试通道——已针对 Copilot CLI 1.0.41 进行实证验证）。 | -| Cursor Agent | 同一 Agent 循环中，立即触发 | 与 Claude 相同（使用 Cursor 的 `{followup_message}` 通道——上限为 `loop_limit`，默认 5 次重试）。 | -| OpenCode | 同一 Agent 循环中，立即触发 | 与 Claude 相同（使用 OpenCode 的 `client.session.prompt(...)` SDK 调用，通过 `hookSpecificOutput.additionalContext` 路由）。 | -| **Pi（pi-coding-agent）** | **下一个用户轮次** | **Pi 会明显停止**——门控触发时其 Agent 循环退出，控制权返回给提示符。门控将在你下次提交提示时触发：failproofai 会在该轮次的系统提示前追加一条 `MANDATORY ACTION REQUIRED` 指令，指示 LLM 在执行你的请求之前先完成工作流步骤（提交、推送等）。 | +| Claude Code | 同一 Agent 循环，立即触发 | Claude 继续工作——修复问题后再次尝试完成。你不会看到中断。 | +| Codex | 同一 Agent 循环，立即触发 | 与 Claude 相同。 | +| GitHub Copilot CLI | 同一 Agent 循环，立即触发 | 与 Claude 相同（使用 Copilot 的 `{decision:"block", reason}` 重试通道——经过 Copilot CLI 1.0.41 实证验证）。 | +| Cursor Agent | 同一 Agent 循环，立即触发 | 与 Claude 相同（使用 Cursor 的 `{followup_message}` 通道——受 `loop_limit` 限制，默认 5 次重试）。 | +| OpenCode | 同一 Agent 循环，立即触发 | 与 Claude 相同（使用 OpenCode 的 `client.session.prompt(...)` SDK 调用，通过 `hookSpecificOutput.additionalContext` 路由）。 | +| **Pi (pi-coding-agent)** | **下一个用户轮次** | **Pi 在门控触发时会明显停止**——其 Agent 循环退出并返回提示符。门控在你下次提交提示时触发：failproofai 会在该轮次的系统提示开头添加 `MANDATORY ACTION REQUIRED` 指令，要求 LLM 在执行你的请求之前完成工作流步骤（提交、推送等）。 | -**Pi 的限制。** Pi 的 `AgentEndEvent`（上游等价于 Claude 的 `Stop` 钩子）没有 Result 类型——触发时 Pi 的 Agent 循环已经退出。Pi 无法像 Claude / Copilot / Cursor / OpenCode 那样被强制重试同一循环。failproofai 将门控转移到 Pi 的 `before_agent_start` 事件（在下一个用户提示之后触发），使工作流检查仍然有效，只是在下一个轮次而非当前轮次执行。 +**Pi 的限制。** Pi 的 `AgentEndEvent`（相当于 Claude 的 `Stop` 钩子的上游等价物）没有 Result 类型——当它触发时，Pi 的 Agent 循环已经退出。Pi 无法像 Claude / Copilot / Cursor / OpenCode 那样被强制重试同一循环。failproofai 将门控转移到 Pi 的 `before_agent_start` 事件（在下一个用户提示后触发），使工作流检查仍然生效，只是在下一轮而非当前轮执行。 **实际影响：** -- Pi 停止后，拒绝原因会以 Pi 会话 ID 为键存储在内存中。你在同一 Pi 进程中提交的下一个提示会将其消费：LLM 在系统提示顶部看到 `MANDATORY ACTION REQUIRED` 指令，先完成提交（或推送/开启 PR/等待 CI），然后才继续处理你的请求。已消费的拒绝原因为一次性使用——消费后门控即清除。 -- 门控的有效期与 Pi 进程的生命周期绑定。如果你在两次轮次之间按下 `Ctrl+C` 或退出 Pi，内存中的条目会随进程一起丢失，门控将被错过。Claude、Copilot、Cursor 和 OpenCode 具有相同的限制（终止 Agent 则门控被错过）——Pi 只是让这一点更加明显，因为 Agent 会在门控触发前可见地退出。 -- 待处理的拒绝也会在任何原因（`new` / `resume` / `fork` / `quit`）导致的 `session_shutdown` 时被清除，因此来自先前会话的过期门控不会泄漏到在同一 Pi 进程中启动的新会话中。 +- Pi 停止后，拒绝原因会以 Pi 会话 ID 为键存储在内存中。你在同一 Pi 进程中提交的下一条提示会清空它：LLM 会在系统提示顶部看到 `MANDATORY ACTION REQUIRED` 指令，先完成提交（或推送/打开 PR/等待 CI），然后再继续处理你的请求。该拒绝原因是一次性的——清空后门控即清除。 +- 门控受 Pi 进程生命周期限制。如果你在两轮之间 `Ctrl+C` Pi 或退出，内存中的条目会随进程一起丢弃，门控将被错过。Claude、Copilot、Cursor 和 OpenCode 有相同的限制（终止 Agent 即错过门控）——Pi 只是让这一点更加明显，因为 Agent 在门控触发前就已可见地退出了。 +- 挂起的拒绝也会在任何原因（`new` / `resume` / `fork` / `quit`）触发 `session_shutdown` 时被清除，因此来自上一个会话的过期门控不会泄露到同一 Pi 进程中启动的新会话里。 -如果你需要 Claude 风格的同循环重试，请在其他五个受支持的 CLI 下运行 `Stop` 策略。我们正在跟踪 Pi 上游，期待未来在 `AgentEndEvent` 上增加 Result 类型以弥合这一差距。 +如果你需要 Claude 风格的同循环重试，请在其他五种受支持的 CLI 下运行 `Stop` 策略。我们正在跟进 Pi 上游，期待 `AgentEndEvent` 未来能有 Result 类型以弥补这一差距。 ### `require-commit-before-stop` **事件：** Stop -**默认行为：** 当存在未提交的更改（已修改、已暂存或未追踪的文件）时，拒绝停止。当工作目录干净时，返回信息消息。 +**默认行为：** 当存在未提交的更改（已修改、已暂存或未跟踪的文件）时，拒绝停止。当工作目录干净时，返回信息消息。 无参数。 @@ -760,13 +758,13 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `require-push-before-stop` **事件：** Stop -**默认行为：** 当存在未推送的提交或当前分支没有远程追踪分支时，拒绝停止。如需要，建议使用 `git push -u` 创建追踪分支。未配置远程仓库时，失败开放。 +**默认行为：** 当存在未推送的提交或当前分支没有远程跟踪分支时，拒绝停止。如需创建跟踪分支，建议使用 `git push -u`。未配置远程仓库时失败开放。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | 推送目标的远程仓库名称。 | +| `remote` | `string` | `"origin"` | 推送的目标远程仓库名称。 | **示例：** @@ -785,13 +783,13 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `require-pr-before-stop` **事件：** Stop -**默认行为：** 当当前分支不存在 Pull Request，或现有 PR 已关闭且未合并时，拒绝停止。指示 Claude 使用 `gh pr create` 创建 PR。当 PR **已合并**时，策略允许通过（工作已交付），并提示切换离开该分支（`git checkout main && git pull`）。 +**默认行为：** 当前分支不存在 Pull Request，或现有 PR 已关闭未合并时，拒绝停止。指示 Claude 使用 `gh pr create` 创建 PR。当 PR **已合并**时，策略允许（工作已交付）并提示切换分支（`git checkout main && git pull`）。 无参数。 -此策略需要安装并已通过身份验证的 [GitHub CLI](https://cli.github.com/)（`gh`）。 -运行 `gh auth login` 时，请使用具有 `repo` 作用域（Pull Request 读取权限）的个人访问令牌。如果未安装 `gh` 或未通过身份验证，策略将失败开放并向 Claude 报告原因。 +此策略需要安装并完成身份验证的 [GitHub CLI](https://cli.github.com/)（`gh`）。 +运行 `gh auth login`，使用具有 `repo` 作用域的个人访问令牌以获得对 Pull Request 的读取权限。如果未安装 `gh` 或未完成身份验证，策略会失败开放并向 Claude 报告原因。 --- @@ -799,21 +797,21 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `require-no-conflicts-before-stop` **事件：** Stop -**默认行为：** 当当前分支无法干净地合并到基础分支时，拒绝停止。策略首先确认 GitHub 上该分支存在 `OPEN` 状态的 PR——若没有，则没有需要强制执行的合并目标，整个策略短路为允许。确认存在 `OPEN` PR 后，两项独立探测会并行运行： +**默认行为：** 当当前分支无法干净地合并到基础分支时，拒绝停止。策略首先确认 GitHub 上该分支存在 `OPEN` 状态的 PR——若没有，则没有合并目标可执行，整个策略短路为允许。一旦确认 `OPEN` PR，两个独立探测会并行运行： -1. **本地** — `git merge-tree --write-tree --name-only origin/ HEAD`。发生冲突时，拒绝消息会列出冲突文件，让 Claude 准确知道需要解决什么。 -2. **GitHub** — 复用在前置检查中已获取的 `gh pr view --json mergeable,state` 结果。可捕获过期的本地 `origin/` 会遗漏的冲突（例如，自上次 fetch 以来有人在 `main` 上合并了冲突 PR）。`CONFLICTING` 结果会触发拒绝。`UNKNOWN` 结果也会触发拒绝，并指示 Claude 等待约 10 秒后在再次尝试停止前重新检查——这可以防止 GitHub 重新计算时产生漏报。 +1. **本地探测** — `git merge-tree --write-tree --name-only origin/ HEAD`。发生冲突时，拒绝消息会列出冲突文件，便于 Claude 明确知道需要解决哪些问题。 +2. **GitHub 探测** — 复用在预检时已获取的 `gh pr view --json mergeable,state` 结果。可捕获本地过期的 `origin/` 会遗漏的冲突（例如自上次 fetch 以来有人在 `main` 上合并了冲突 PR）。`CONFLICTING` 结果会拒绝。`UNKNOWN` 结果也会拒绝，并指示 Claude 等待约 10 秒后重新检查再尝试停止——这可防止 GitHub 重新计算时出现假阴性。 -以下情况跳过检查（允许通过）：未安装 `gh`、该分支不存在 PR、PR 状态不为 `OPEN`（如 `MERGED`、`CLOSED`），或 `gh pr view` 返回无法解析的输出。当 `origin/` 在本地不存在或没有领先于基础分支的提交时也会失败开放——这些第一层回退仍会在允许之前查阅缓存的 PR 可合并性。 +以下情况完全跳过（允许）：未安装 `gh`、该分支不存在 PR、PR 状态不为 `OPEN`（例如 `MERGED`、`CLOSED`），或 `gh pr view` 返回无法解析的输出。当本地缺少 `origin/` 或没有超前于基础的提交时也会失败开放——这些第一层回退仍会在允许前查询缓存的 PR 可合并性。 **参数：** -| 参数 | 类型 | 默认值 | 说明 | +| 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | 检查冲突时使用的基础分支。 | +| `baseBranch` | `string` | `"main"` | 检查冲突所依据的基础分支。 | -此策略需要 GitHub CLI（`gh`）。策略使用 `gh pr view` 在运行任何冲突探测之前确认存在 `OPEN` PR——若没有 `gh`，策略将短路为允许。运行 `gh auth login` 时，请使用具有 `repo` 作用域（Pull Request 读取权限）的个人访问令牌。 +此策略需要 GitHub CLI（`gh`）。策略使用 `gh pr view` 确认存在 `OPEN` PR 后才运行任何冲突探测——没有 `gh` 时，策略短路为允许。运行 `gh auth login`，使用具有 `repo` 作用域的个人访问令牌以获得对 Pull Request 的读取权限。 --- @@ -821,13 +819,13 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ### `require-ci-green-before-stop` **事件：** Stop -**默认行为：** 当当前分支上的 CI 检查失败或仍在运行时，拒绝停止。同时检查 GitHub Actions 工作流运行和第三方机器人检查（例如 CodeRabbit、SonarCloud、Codecov）。将 `skipped`、`cancelled` 和 `neutral` 结论视为非失败（最后一种涵盖了外部贡献者 PR 上 Socket Security 警告等场景，该应用会刻意报告 neutral 而非 success/failure）。所有检查通过时，返回信息消息。 +**默认行为：** 当当前分支的 CI 检查正在失败或仍在运行时，拒绝停止。同时检查 GitHub Actions 工作流运行和第三方机器人检查（例如 CodeRabbit、SonarCloud、Codecov）。将 `skipped`、`cancelled` 和 `neutral` 结论视为非失败（后者涵盖例如外部贡献者 PR 上 Socket Security 告警故意上报 neutral 而非 success/failure 的情况）。所有检查通过时返回信息消息。 无参数。 -此策略需要安装并已通过身份验证的 [GitHub CLI](https://cli.github.com/)（`gh`）。 -运行 `gh auth login` 时，请使用具有 `repo` 作用域（Actions 工作流运行和 Checks API 读取权限）的个人访问令牌。如果未安装 `gh` 或未通过身份验证，策略将失败开放并向 Claude 报告原因。 +此策略需要安装并完成身份验证的 [GitHub CLI](https://cli.github.com/)（`gh`）。 +运行 `gh auth login`，使用具有 `repo` 作用域的个人访问令牌以获得对 Actions 工作流运行和 Checks API 的读取权限。如果未安装 `gh` 或未完成身份验证，策略会失败开放并向 Claude 报告原因。 --- @@ -836,7 +834,7 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 ## 禁用单条策略 -在配置中从 `enabledPolicies` 移除特定策略，或在控制台的策略选项卡中将其关闭。 +从配置的 `enabledPolicies` 中移除特定策略，或在控制台的策略标签页中将其关闭。 ```json { @@ -847,4 +845,4 @@ failproofai 附带 39 条内置策略，用于捕获常见的 Agent 故障模式 } ``` -未列在 `enabledPolicies` 中的策略不会运行，即使 `policyParams` 中存在对应的条目。 \ No newline at end of file +未列入 `enabledPolicies` 的策略不会运行，即使存在对应的 `policyParams` 条目也是如此。 \ No newline at end of file diff --git a/docs/zh/cli/audit.mdx b/docs/zh/cli/audit.mdx index a5b888d4..470f2122 100644 --- a/docs/zh/cli/audit.mdx +++ b/docs/zh/cli/audit.mdx @@ -1,19 +1,17 @@ --- title: 审计历史会话（测试版） -description: "统计 agent 在过去记录中执行浪费性或高风险操作的频率" +description: "统计 Agent 在历史记录中执行过浪费性或高风险操作的频率" --- - **测试版功能。** 审计功能以测试版形式发布，我们正在收集早期反馈。 - 检测器目录和报告格式可能在下一个稳定版本发布前有所变动。 - 如有异常，请提交 issue。 + **测试版功能。** 审计功能目前以测试版形式发布，我们正在收集早期反馈。检测器目录和报告格式可能在下一个稳定版本发布前有所变更。如发现任何异常，欢迎提交 issue。 -审计功能会将你过去的 agent CLI 记录通过 failproofai 的策略引擎重新回放，并在 **`/audit` 控制台页面**生成一份可分享的可视化报告，内容包括：你的 agent 所属原型、0 到 100 的评分，以及哪些策略会捕获哪些问题。 +审计功能会将你过去的 Agent CLI 记录回放到 failproofai 的策略引擎中，并在 **`/audit` 仪表板页面**生成一份可分享的可视化报告——包括 Agent 的行为类型、0–100 分的评分，以及哪些策略能够拦截哪些问题。 ## 运行方式 -有三种入口——最终都会跳转到同一份 `/audit` 报告。 +三种方式均可使用，最终都会跳转到同一份 `/audit` 报告。 @@ -25,7 +23,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (控制台) +```bash failproofai (仪表板) failproofai ``` @@ -33,83 +31,85 @@ failproofai - `npx -y failproofai audit` 会自动获取 failproofai，执行扫描并打开控制台——无需预先安装任何东西。 + `npx -y failproofai audit` 会自动获取 failproofai、执行扫描并为你打开仪表板——无需提前安装任何内容。 - - `failproofai audit` 在终端中运行扫描，完成后自动打开 `localhost:8020/audit`。 + + `failproofai audit` 在终端中执行扫描，完成后自动打开 `localhost:8020/audit`。 - - 运行 `failproofai`，点击导航栏中的 **Audit**（位于 Policies 和 Projects 之间），或直接打开 `/audit`。 + + 运行 `failproofai` 后，点击导航栏中的 **Audit**（位于 Policies 和 Projects 之间），或直接访问 `/audit`。 - 运行 `failproofai audit -h`（或 `--help`）查看使用说明。审计**完全离线**运行——无需账户或网络——控制台会持续服务，直到你按 `Ctrl+C` 停止。 + 运行 `failproofai audit -h`（或 `--help`）查看用法说明。审计**完全离线**运行——无需账号或网络连接——仪表板将持续提供服务，直到你按 `Ctrl+C` 停止。 -控制台会扫描本机上过去的 agent CLI 记录（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi），并报告 agent 执行了多少次 failproofai 所设计拦截的操作——包括环境变量检查、强制推送、多余的 `cd ` 前缀、sleep 轮询循环、重复读取刚刚编辑过的文件等。 +仪表板会扫描本机上过去的 Agent CLI 记录（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi），并报告 Agent 执行了多少次 failproofai 旨在阻止的操作——包括环境变量检查、强制推送、多余的 `cd ` 前缀、轮询式 sleep 循环、重复读取刚编辑过的文件等。 -对于每份记录，所有工具调用事件都会经过 39 条内置策略**以及** 8 个仅限审计的检测器重新回放，这些检测器用于捕获尚未被运行时策略覆盖的模式。计数按策略/检测器在所有会话中汇总。 +对于每份记录，所有工具调用事件都会通过 39 条内置策略以及 8 个仅在审计时运行的检测器进行回放，后者专门捕捉目前尚未被运行时策略覆盖的模式。计数会按策略/检测器在所有会话中汇总。 ## 报告内容 -`/audit` 页面是一个单屏可分享的**海报**，后跟四个滚动区域： +`/audit` 页面是一个单屏可分享的**海报**，下方包含四个折叠区域： -1. **海报** — 一目了然地展示 agent 的身份：**原型**（共 8 种——`optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、persona 关键词、该原型的稀有程度，以及带等级区间的 **0–100 评分**（从 `S` 到 `bottom tier`）。专为分享设计——可发布到 X 或 LinkedIn，或下载为 PNG。 -2. **`// strengths`** — agent 已经做得好的方面，以扫描得出的真实数字呈现（例如：干净工具调用百分比、`0` 次 push-to-main 尝试），仅在相关策略记录完全干净时显示。 -3. **`// quirks`** — 存在的问题：一张按优先级排列的表格，展示 failproofai 本可捕获的行为——*最近一次发生的时间*、*具体内容*（以及会拦截它的内置策略）、*严重程度*，以及*出现频率*（`new` / `recurring` / `N× seen`）。 -4. **`// how to improve`** — 针对性修复列表：每条策略对应一行，附有可直接复制粘贴的 `failproofai policy add ` 命令，以及一键**全部安装**按钮，可同时启用所有建议，并显示执行后的**预期评分**。 -5. **`// come back better`** — 养成习惯：设置重新审计的邮件**提醒**（`3d` / `7d` / `14d` / `30d`）或立即重新审计，并**邀请朋友**进行他们自己的审计（由 failproof.ai 发送，抄送给你）。提醒和邀请功能需要登录。 +1. **海报** — Agent 身份一览：其**行为类型**（共 8 种——`optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、人设关键词、该类型的稀有程度，以及带有等级区间的 **0–100 分**（从 `S` 级到 `bottom tier`）。专为分享设计——可发布到 X 或 LinkedIn，或下载为 PNG。 +2. **`// strengths`** — Agent 已经做得好的方面，以扫描的真实数据呈现（例如干净工具调用占比、`0` 次推送到主分支的尝试），仅在相关策略记录干净时显示。 +3. **`// quirks`** — 存在的问题：一张按优先级排列的行为表，展示 failproofai 本可拦截的内容——*发生时间*、*具体问题*（以及可阻止该问题的内置策略）、*严重程度*，以及出现*频次*（`new` / `recurring` / `N× seen`）。 +4. **`// how to improve`** — 推荐修复列表：每条策略对应一行可复制的 `failproofai policy add ` 命令，以及一个**全部安装**按钮，可一键启用所有建议，并显示执行后的**预计分数**。 +5. **`// come back better`** — 养成习惯：设置重新审计的邮件**提醒**（`3d` / `7d` / `14d` / `30d`）或立即重新审计，并**邀请好友**进行各自的审计（由 failproof.ai 发送，抄送给你）。提醒和邀请功能需要登录。 ## 定时审计 -如果你运行了 **failproofaid 守护进程**（参见 [`failproofai config`](/zh/cli/install-policies)），它可以按计划自动重新运行审计，并在后台刷新 `/audit` 报告。该功能**默认关闭**，因为扫描会读取本机上每个 agent 会话记录的*内容*——在你明确开启之前，不会有任何定时扫描。 +如果你运行了 **failproofaid 守护进程**（参见 [`failproofai config`](/zh/cli/install-policies)），它可以按计划自动重新运行审计，并在后台刷新 `/audit` 报告。**默认关闭**，因为扫描会读取本机上每个 Agent 会话记录的*内容*——在你主动启用之前，不会有任何定时扫描。 -在 `~/.failproofai/config.toml` 中开启： +在 `~/.failproofai/config.json` 中开启——在文件现有内容中添加 `audit` 键： -```toml -[audit] -auto = true -interval_days = 7 +```json +{ + "audit": { + "auto": true, + "interval_days": 7 + } +} ``` -| 键 | 含义 | +| 键名 | 含义 | |---|---| -| `auto` | `true` 启用定时扫描。其他任何值——缺失、`false`、`"yes"`——均为关闭。 | -| `interval_days` | 两次扫描之间的天数。限制在 1–90 之间；`0`、负数或非数字值将回退到 `7`。 | +| `auto` | `true` 启用定时扫描。其他任何值——缺失、`false`、`"yes"`——均为关闭状态。 | +| `interval_days` | 扫描间隔天数。限制在 1–90 之间；`0`、负数或非数字值均回退为 `7`。 | -- 计划基于**挂钟时间**，因此能在休眠和重启后继续：如果笔记本电脑在到期后才唤醒，仅**运行一次**，不会积压。 -- 每次运行都是独立的低优先级（`nice 19`）进程——绝不占用守护进程的 hook 路径，该路径始终保持空闲以响应工具调用。 -- 如果 `failproofai audit` 或控制台的重新运行已在进行中，本次扫描会被跳过；稍后会重试，而不是视为失败。 -- 进度写入 `~/.failproofai/state/audit-schedule.json`（包含上次运行时间和下次计划时间）。该文件由守护进程管理——请在 `config.toml` 中修改周期。 +- 计划基于**挂钟时间**，因此能够在休眠和重启后继续生效：若笔记本电脑在到期时处于睡眠状态，唤醒后**只运行一次**，不会积压执行。 +- 每次运行是一个独立的低优先级（`nice 19`）进程——绝不占用守护进程的 hook 路径，该路径始终空闲以响应工具调用。 +- 如果 `failproofai audit` 或仪表板的重新运行正在进行中，本次扫描将跳过；随后会重试，而不是视为失败。 +- 进度写入 `~/.failproofai/state/audit-schedule.json`（上次运行时间、下次计划时间）。该文件由守护进程管理——在 `config.json` 中修改扫描频率。 -如果你在旧版 failproofai 搭建的机器上启用了此功能，请运行一次 -`failproofai config`。守护进程的服务定义在能启动 CLI 之前需要一个额外条目，刷新操作已包含在该命令中。 +如果你在一台由旧版 failproofai 配置的机器上启用了此功能，请运行一次 `failproofai config`。守护进程的服务定义需要一个额外条目才能启动 CLI，而该刷新操作正是该命令的一部分。 -## 仅限审计的检测器 +## 仅审计时运行的检测器 -这些检测器用于发现"低质量行为"模式，这些模式尚未被实时强制执行。它们仅在审计期间运行，绝不会阻断实时工具调用。 +这些检测器用于发现目前（尚未）被实时执行的「低效行为」模式。它们仅在审计期间运行，永远不会阻断实时工具调用。 -| 检测器 | 计数内容 | +| 检测器 | 检测内容 | |---|---| -| `redundant-cd-cwd` | 以 `cd && …` 开头的 Bash 命令，尽管命令已在 `cwd` 中运行。 | +| `redundant-cd-cwd` | 以 `cd && …` 开头的 Bash 命令，而命令本已在 `cwd` 中运行。 | | `prefer-edit-over-read-cat` | 对单个源文件使用 `cat`/`head`/`tail`/`less`/`more`——应使用 `Read` 工具。 | -| `prefer-edit-over-sed-awk` | 使用 `sed -i` / `awk … > file` 就地编辑——应使用 `Edit` 工具。 | +| `prefer-edit-over-sed-awk` | 使用 `sed -i` / `awk … > file` 进行原地编辑——应使用 `Edit` 工具。 | | `prefer-write-over-heredoc` | 使用 heredoc / 多行 `echo > file` 写入文件——应使用 `Write` 工具。 | | `sleep-polling-loop` | 长时间 `sleep N`（≥ 30 秒）或 `while …; sleep …; done` 轮询循环。 | -| `find-from-root` | 使用 `find /`、`find /home`、`find /usr` 等——应限定在 `cwd` 范围内。 | -| `git-commit-no-verify` | 使用 `git commit … --no-verify` / `-n`，跳过 hook。 | -| `reread-after-edit` | 在同一会话中对刚刚 `Edit`/`Write` 过的文件执行 `Read`。 | +| `find-from-root` | `find /`、`find /home`、`find /usr` 等——应限定在 `cwd` 范围内。 | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`，跳过 hook。 | +| `reread-after-edit` | 在同一会话中，对刚刚通过 `Edit`/`Write` 修改的文件执行 `Read`。 | -## 缓存 +## 缓存机制 -- **逐记录缓存**，位于 `~/.failproofai/cache/audit/.json`，以 `(mtime, size, engineVersion, detectorVersion)` 为键——当记录或策略/检测器代码发生变化时自动失效。每个条目还存储了 `cachedAt` 时间戳作为 **TTL 元数据**（不属于缓存键）；读取时，超过 **7 天**的条目将被拒绝，以防长期缓存的结果与演进中的检测器意图脱节。 -- **完整结果缓存**，位于 `~/.failproofai/audit-dashboard.json`（权限 0600）。让控制台在导航时能立即渲染，无需重新运行。超过 **7 天 TTL** 后读取同样会被拒绝——`/audit` 随后回退到空状态并提示重新运行。点击报告底部附近的 `[ re-audit now ]` 刷新——重新审计会发送 `noCache: true`，绕过逐记录缓存并重新扫描所有记录，而不是返回缓存结果；运行过程通过顶部固定条带显示进度，成功后原地替换结果（无需刷新页面；重新审计失败时保留之前的报告）。 +- **按记录缓存**，路径为 `~/.failproofai/cache/audit/.json`，以 `(mtime, size, engineVersion, detectorVersion)` 为键——当记录或策略/检测器代码发生变化时自动失效。每条缓存还存储了 `cachedAt` 时间戳作为 **TTL 元数据**（不属于缓存键的一部分）；超过 **7 天**的条目在读取时会被拒绝，以防长期缓存的结果与不断更新的检测器意图脱节。 +- **整体结果缓存**，路径为 `~/.failproofai/audit-dashboard.json`（权限 0600）。让仪表板在导航时无需重新运行即可即时渲染。同样在超过 **7 天 TTL** 后被拒绝读取——`/audit` 随后会进入空状态并提示重新运行。点击报告底部附近的 `[ re-audit now ]` 可刷新——重新审计会发送 `noCache: true`，因此会绕过按记录缓存并重新扫描所有记录，而非返回缓存结果；运行进度通过顶部固定条目流式显示，成功后原地替换结果（无需刷新页面；若重新审计失败，则保留之前的报告）。 -## 说明 +## 注意事项 -- **只读操作。** 审计以只读模式回放。`warn-repeated-tool-calls` 会被跳过，否则其每会话附属文件将被修改。 -- **跳过工作流策略。** `require-*-before-stop` 策略仅在 `Stop` 事件时触发，并对实时 git 状态执行 `execSync`——它们对于"2025 年会发生什么"没有实际意义，因此不会出现在审计计数中。 -- **跳过自定义策略。** 用户提供的自定义 hook 不会被回放（它们可能在原始会话之后已发生变更）。 \ No newline at end of file +- **无数据修改。** 审计以只读模式回放。`warn-repeated-tool-calls` 被跳过，否则其每会话的附属文件将被修改。 +- **工作流策略被跳过。** `require-*-before-stop` 策略仅在 `Stop` 事件时触发，并通过 `execSync` 对实时 git 状态执行——对于「2025 年发生了什么」的解读没有实际意义，因此不会出现在审计计数中。 +- **自定义策略被跳过。** 用户提供的自定义 hook 不会被回放（它们可能在原始会话之后已发生变更）。 \ No newline at end of file diff --git a/docs/zh/cli/dashboard.mdx b/docs/zh/cli/dashboard.mdx index 1daf9c3f..56ada76e 100644 --- a/docs/zh/cli/dashboard.mdx +++ b/docs/zh/cli/dashboard.mdx @@ -1,6 +1,6 @@ --- title: 查看会话 -description: "启动仪表板以浏览代理会话并管理策略" +description: "启动仪表板以浏览 Agent 会话并管理策略" --- ```bash @@ -11,7 +11,7 @@ failproofai ## 选项 -| 标志 | 描述 | +| 参数 | 描述 | |------|------| | `--port ` | 监听端口（默认：`8020`） | | `--allowed-origins ` | 允许访问开发资源的主机/IP，以逗号分隔 | diff --git a/docs/zh/cli/environment-variables.mdx b/docs/zh/cli/environment-variables.mdx index 18e07055..294a29e5 100644 --- a/docs/zh/cli/environment-variables.mdx +++ b/docs/zh/cli/environment-variables.mdx @@ -3,13 +3,13 @@ title: 环境变量 description: "通过环境变量配置 failproofai 的行为" --- -## 仪表盘 +## 控制台 | 变量 | 描述 | |----------|-------------| -| `PORT` | 仪表盘端口（默认：`8020`） | +| `PORT` | 控制台端口（默认：`8020`） | | `CLAUDE_PROJECTS_PATH` | 覆盖 Claude Code 项目文件夹的查找路径 | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 以逗号分隔的仪表盘页面名称，用于隐藏对应页面 | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 以逗号分隔的控制台页面列表，用于隐藏指定页面 | | `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | 允许访问开发资源的主机/IP，与 `--allowed-origins` 相同 | ## 日志 @@ -21,42 +21,45 @@ description: "通过环境变量配置 failproofai 的行为" ## 遥测 -failproofai 默认会上报匿名使用遥测数据。有两种方式可以关闭遥测，系统会采用两者中限制更严格的那个——环境变量无法重新启用已被配置文件关闭的功能。 +failproofai 默认会上报匿名使用遥测数据。有两种方式可以关闭它，两者取更严格的那一方生效——环境变量无法重新启用已被配置文件关闭的功能。 | 变量 | 描述 | |----------|-------------| | `FAILPROOFAI_TELEMETRY_DISABLED=1` | 为当前进程禁用匿名使用遥测 | -若要在机器上永久禁用遥测，请将以下内容添加到 `~/.failproofai/config.toml`： +如需永久关闭该机器上的遥测，请将以下内容添加到 `~/.failproofai/config.json`： -```toml -[telemetry] -enabled = false +```json +{ + "telemetry": { + "enabled": false + } +} ``` -如果你运行的是 **failproofaid 守护进程**，推荐使用配置文件的方式。守护进程是系统级服务，其运行环境不包含从 shell 导出的变量，因此 `FAILPROOFAI_TELEMETRY_DISABLED` 对它无效。`[telemetry] enabled = false` 对 CLI 和守护进程均有效。 +如果你运行的是 **failproofaid 守护进程**，建议使用配置文件方式。守护进程是一个系统级服务，其运行环境不包含从 shell 导出的变量，因此 `FAILPROOFAI_TELEMETRY_DISABLED` 对它不起作用。`[telemetry] enabled = false` 可同时被 CLI 和守护进程读取。 -守护进程仅上报自身的**生命周期**事件：启动时（以及上次运行是否正常退出）、停止时、评估 worker 被启动或重启时、采集任务失败时，以及云端策略拉取的结果。这些事件只携带低基数的值和计数——不包含任何文件路径、命令、策略、提示词，或从记录中读取的任何内容，也不存在每次工具调用的事件。 +守护进程仅上报自身的**生命周期**事件：包括启动时间（以及上次运行是否正常退出）、停止时间、评估工作进程的创建或重启、收集任务失败情况，以及云端策略拉取的结果。这些数据仅包含低基数的值和计数，绝不包含文件路径、命令、策略、提示词或从记录中读取的任何内容，也不存在每次工具调用的事件。 ## 认证 | 变量 | 描述 | |----------|-------------| -| `FAILPROOF_API_URL` | 覆盖仪表盘认证对话框使用的 API 服务器基础 URL。默认为 `https://api.befailproof.ai`；在本地运行 API 服务器时，可设置为 `http://localhost:8080`（或对应地址）。 | -| `FAILPROOFAI_AUTH_DIR` | 覆盖 `auth.json` 的存储路径（默认：`~/.failproofai`），主要用于隔离测试。 | +| `FAILPROOF_API_URL` | 覆盖控制台认证对话框使用的 API 服务器基础 URL。默认为 `https://api.befailproof.ai`；在本地运行 api-server 时，可设为 `http://localhost:8080`（或其他地址）。 | +| `FAILPROOFAI_AUTH_DIR` | 覆盖 `auth.json` 的存储位置（默认：`~/.failproofai`），主要用于隔离测试。 | ## 首次运行提示 | 变量 | 描述 | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | 跳过首次裸调用 `failproofai` 时提示安装策略的交互 | +| `FAILPROOFAI_NO_FIRST_RUN=1` | 跳过首次直接执行 `failproofai` 时提示安装策略的交互 | ## LLM（用于策略评估） | 变量 | 描述 | |----------|-------------| | `FAILPROOFAI_LLM_BASE_URL` | LLM API 端点（默认：`https://api.openai.com/v1`） | -| `FAILPROOFAI_LLM_API_KEY` | LLM 驱动策略所需的 API 密钥 | +| `FAILPROOFAI_LLM_API_KEY` | 用于 LLM 驱动策略的 API 密钥 | | `FAILPROOFAI_LLM_MODEL` | 模型名称（默认：`gpt-4o-mini`） | \ No newline at end of file diff --git a/docs/zh/cli/hook.mdx b/docs/zh/cli/hook.mdx index bf18c84d..5225e497 100644 --- a/docs/zh/cli/hook.mdx +++ b/docs/zh/cli/hook.mdx @@ -7,24 +7,24 @@ description: "Claude Code 在每个工具事件上调用的子进程" failproofai --hook ``` -这是由 `failproofai policies --install` 注册到 Claude Code 的 `settings.json` 中的命令，通常无需直接调用。 +这是由 `failproofai policies --install` 注册到 Claude Code 的 `settings.json` 中的命令。通常情况下，你不需要直接调用它。 -该命令从 stdin 读取 JSON 载荷，对所有已启用的策略进行评估，并以退出码的形式返回决策结果： +该命令从 stdin 读取 JSON 载荷，对所有已启用的策略进行评估，并通过退出码返回决策结果： | 退出码 | 决策 | 效果 | |--------|------|------| | `0` | `allow` | 允许该操作 | -| `1` | `deny` | 阻止该操作 —— Claude 将收到拒绝原因 | -| `2` | `instruct` | 向 Claude 的上下文注入指导信息 | +| `1` | `deny` | 阻止该操作 - Claude 将看到拒绝原因 | +| `2` | `instruct` | 向 Claude 的上下文中注入指导信息 | ### 支持的事件类型 -| 类别 | 事件 | +| 分类 | 事件 | |------|------| -| **工具执行** | `PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied` | -| **会话生命周期** | `SessionStart`、`SessionEnd`、`Stop`、`StopFailure` | -| **用户交互** | `UserPromptSubmit`、`Notification`、`Elicitation`、`ElicitationResult` | -| **子代理与任务** | `SubagentStart`、`SubagentStop`、`TaskCreated`、`TaskCompleted`、`TeammateIdle` | -| **配置** | `InstructionsLoaded`、`ConfigChange`、`CwdChanged` | -| **文件系统** | `FileChanged`、`WorktreeCreate`、`WorktreeRemove` | -| **上下文** | `PreCompact`、`PostCompact` | \ No newline at end of file +| **工具执行** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | +| **会话生命周期** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | +| **用户交互** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | +| **子代理与任务** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **配置** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | +| **文件系统** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | +| **上下文** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/zh/cli/install-policies.mdx b/docs/zh/cli/install-policies.mdx index 485127df..2d58f3cb 100644 --- a/docs/zh/cli/install-policies.mdx +++ b/docs/zh/cli/install-policies.mdx @@ -13,21 +13,21 @@ failproofai policies --install [policy-names...] [options] ## 选项 -| 参数 | 描述 | -|------|------| -| `--cli claude\|codex\|copilot` | 要安装的代理 CLI，以空格分隔（例如 `--cli claude codex copilot`）或重复使用。省略时将自动检测已安装的 CLI 并提示选择。 | -| `--scope user` | 安装到用户级设置文件（Claude：`~/.claude/settings.json`；Codex：`~/.codex/hooks.json`；Copilot：`~/.copilot/hooks/failproofai.json`）。默认值。 | -| `--scope project` | 安装到项目级设置文件（Claude：`/.claude/settings.json`；Codex：`/.codex/hooks.json`；Copilot：`/.github/hooks/failproofai.json`）。 | -| `--scope local` | 仅限 Claude — 安装到 `/.claude/settings.local.json`。Codex 和 Copilot 不支持 `local` 作用域。 | +| 标志 | 说明 | +|------|-------------| +| `--cli claude\|codex\|copilot` | 要安装的代理 CLI，以空格分隔（例如 `--cli claude codex copilot`）或重复使用。省略则自动检测已安装的 CLI 并进行提示。 | +| `--scope user` | 安装至用户级设置文件（Claude：`~/.claude/settings.json`；Codex：`~/.codex/hooks.json`；Copilot：`~/.copilot/hooks/failproofai.json`）。默认值。 | +| `--scope project` | 安装至项目级设置文件（Claude：`/.claude/settings.json`；Codex：`/.codex/hooks.json`；Copilot：`/.github/hooks/failproofai.json`）。 | +| `--scope local` | 仅限 Claude — 安装至 `/.claude/settings.local.json`。Codex 和 Copilot 不支持 `local` 作用域。 | | `--custom ` / `-c` | 包含自定义 hook 策略的 JS 文件路径 | -## 行为 +## 行为说明 -- **不指定策略名称** - 打开交互式提示以选择策略 -- **指定具体名称** - 启用这些策略（追加到已启用的策略中） -- **`all`** - 启用所有可用策略 +- **不指定策略名称** — 打开交互式提示以选择策略 +- **指定名称** — 启用对应策略（追加到已启用的策略中） +- **`all`** — 启用所有可用策略 -安装为追加模式：再次运行 `--install` 只会添加新策略，不会移除已有策略。 +安装操作为增量式：再次运行 `--install` 只会添加新策略，不会移除已有策略。 ## 示例 @@ -41,7 +41,7 @@ failproofai policies --install block-sudo sanitize-api-keys --scope project # 一次性启用所有策略 failproofai policies --install all -# 使用自定义策略文件安装 +# 使用自定义策略文件进行安装 failproofai policies --install --custom ./my-policies.js # 为 OpenAI Codex 安装（项目作用域） @@ -54,4 +54,4 @@ failproofai policies --install --cli copilot --scope project failproofai policies --install --cli claude codex copilot ``` -当提供 `--custom ` 时，文件将立即进行验证——至少需要调用一次 `customPolicies.add()`。解析后的路径将作为 `customPoliciesPath` 保存到 `policies-config.json` 中。 \ No newline at end of file +提供 `--custom ` 时，文件会立即进行验证——其中必须至少调用一次 `customPolicies.add()`。解析后的路径将以 `customPoliciesPath` 的形式保存至 `policies-config.json`。 \ No newline at end of file diff --git a/docs/zh/cli/list-policies.mdx b/docs/zh/cli/list-policies.mdx index f3d2988c..97899ff4 100644 --- a/docs/zh/cli/list-policies.mdx +++ b/docs/zh/cli/list-policies.mdx @@ -7,7 +7,7 @@ description: "查看已启用的策略、其参数以及自定义策略" failproofai policies ``` -显示所有策略及其状态、已配置的参数和自定义策略。 +显示所有策略的状态、已配置的参数以及自定义策略。 ## 示例输出 @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -`policyParams` 中未知的键会在此处标记出来，以便你尽早发现拼写错误。 \ No newline at end of file +`policyParams` 中的未知键会在此处标记出来，帮助你及早发现拼写错误。 \ No newline at end of file diff --git a/docs/zh/cli/migrate.mdx b/docs/zh/cli/migrate.mdx new file mode 100644 index 00000000..81c1019c --- /dev/null +++ b/docs/zh/cli/migrate.mdx @@ -0,0 +1,86 @@ +--- +title: 迁移主目录 +description: "将 ~/.failproofai 升级至当前版本所需的目录结构，并可预览迁移计划" +--- + +```bash +failproofai migrate --dry-run # 打印迁移计划，不做任何更改 +failproofai migrate # 执行迁移 +``` + +大多数用户无需手动执行此命令。升级后首次运行任意命令时，迁移会自动触发，[`failproofai update`](/zh/cli/update) 也会自动包含此步骤。仅在需要提前预览迁移计划，或希望单独执行迁移时，才需手动调用此命令。 + +## 基于目录结构版本，而非发布版本 + +`~/.failproofai/VERSION` 记录的是**目录结构**编号——即目录的形态，而非写入该文件的发布版本。迁移操作以此编号为依据，这使得跨越多个版本的迁移代价极低： + +- npm 版本每次发布都会更新，两次目录结构变更之间可能有数十个版本。 +- 因此，一台跳过了三十个发布版本但**目录结构未发生变化**的机器，执行的迁移步骤为**零**，而非三十次空操作。 +- 而一台跨越了多个目录结构版本的机器，则会按顺序逐步执行每个迁移，每一步只需关注自身的起止状态。 + +这一设计至关重要，因为 npm 无法自动更新已安装的包。一台长期停留在某个版本、随后一次性跨越多个目录结构版本的机器，才是常态，而非例外。 + +## 预览模式（Dry Run） + +`--dry-run` 会打印完整的迁移链及迁移前将备份的文件列表，但不做任何实际更改——不执行迁移、不创建备份、不写入日志： + +``` +Layout 2 on disk; this build speaks 3. +1 step(s) would run: + 2 → 3 layout 2 → 3: carry config.toml and credentials.toml into JSON, move + custom-policies/ back up into policies/, nest the policy config at the root + +These would be copied to ~/.failproofai/migrations/backup-layout2 first: + VERSION + config.toml + credentials.toml +``` + +## 哪些数据会被保留，哪些会被重建 + +主目录中的每个路径都声明了其所存储的数据类型，这决定了迁移是否可以丢弃该数据。规则如下：**可派生或可重新获取的数据可被丢弃；凡是由用户手动输入的、尚未投递的，以及用于标识机器身份的数据，均须保留。** + +| 保留 | 重建或重新获取 | +|---|---| +| `config.json` — 设置项、`daemon.configured`、额外的采集路径 | 审计缓存 | +| `credentials.json` — 云端注册凭证 | 云端管理的部署（在下次轮询时重新获取并验证摘要） | +| `policies-config.json` — 策略选择及参数配置 | 守护进程临时状态 | +| `policies/` — 用户自定义策略文件及其引用的辅助模块 | | +| `hook-activity/` — 仪表板读取的决策日志 | | +| 队列中尚未上传的事件 | | +| `cursors/` — 采集器水位标记 | | +| `bin/` 中的守护进程二进制文件 | | + + + 未投递的事件会被保留而非丢弃，原因在于丢失是永久性的，而非仅仅造成延迟：采集器的水位标记已经推进，超过了缓冲池中所有待处理的内容，因此没有任何机制能够再次读取转录文件的那段区间。迁移完成后，守护进程也会立即投递缓冲池中的内容，因此通常不会有任何剩余数据需要保留。 + + +较**新**版本写入 `config.json`、`credentials.json` 或 `policies-config.json` 的键也会被保留，而不会被旧版读取器丢弃。 + +## 迁移留下的记录 + +``` +~/.failproofai/migrations/ + applied.json 每步迁移一条记录：目录结构版本、CLI 版本、时间戳、耗时、结果 + backup-layout/ 执行第一步前，对不可替换文件的备份副本 +``` + +`applied.json` 记录了「此机器究竟经历了哪些迁移」——这是升级后出现异常时首先应查阅的信息。提交 Bug 报告时请附上此文件。 + +备份故意保持精简，而非复制整个目录：迁移设计上不会删除任何不可替换的内容，因此真正需要防范的是**某个步骤存在缺陷**，而这几个文件正是此类缺陷可能造成损害的地方。 + +## 若某步骤失败 + +迁移链会在该步骤处停止。只有成功完成的步骤才会更新 `VERSION`，因此主目录仍会保持旧的目录结构编号，下次执行命令时会重试——主目录绝不会因部分迁移完成而被标记为最新状态。该步骤会以 `"ok": false` 的形式记录在 `applied.json` 中，备份也保留在原处。 + +## 较新的主目录会被拒绝，而非迁移 + +若 `~/.failproofai/` 是由比当前运行版本**更新**的 failproofai 写入的，命令会停止并提示您升级，而非执行迁移。该数据本身没有问题，更新的 CLI 可以正常读取；所谓向前「迁移」并不存在，而重置数据则会销毁本可恢复的内容。 + +``` +This machine's failproofai directory was written by a newer version (layout 4; +this build speaks 3). Upgrade rather than migrate: + npm install -g failproofai@latest +``` + +守护进程遵循相同规则：`failproofaid` 会拒绝以不兼容的目录结构启动，而非尝试读写已变更路径的数据。 \ No newline at end of file diff --git a/docs/zh/cli/remove-policies.mdx b/docs/zh/cli/remove-policies.mdx index 89a3b675..e0627855 100644 --- a/docs/zh/cli/remove-policies.mdx +++ b/docs/zh/cli/remove-policies.mdx @@ -13,29 +13,29 @@ failproofai policies --uninstall [policy-names...] [options] ## 选项 -| 标志 | 描述 | +| 标志 | 说明 | |------|------| | `--scope user` | 从全局设置中移除（默认） | | `--scope project` | 从项目设置中移除 | | `--scope local` | 从本地设置中移除 | -| `--scope all` | 从所有范围中一次性移除 | +| `--scope all` | 同时从所有作用域中移除 | | `--custom` / `-c` | 从配置中清除 `customPoliciesPath` | ## 行为说明 - **不指定策略名称** — 从设置文件中移除所有 failproofai hook 条目 -- **指定具体名称** — 禁用这些策略，但保留已安装的 hooks +- **指定具体名称** — 禁用对应策略，但保留已安装的 hook ## 示例 ```bash -# 全局移除所有 hooks +# 全局移除所有 hook failproofai policies --uninstall -# 禁用特定策略（保留已安装的 hooks） +# 禁用特定策略（保留已安装的 hook） failproofai policies --uninstall block-sudo -# 从所有范围中移除 hooks +# 从所有作用域中移除 hook failproofai policies --uninstall --scope all # 清除自定义策略路径 diff --git a/docs/zh/cli/update.mdx b/docs/zh/cli/update.mdx new file mode 100644 index 00000000..394155e5 --- /dev/null +++ b/docs/zh/cli/update.mdx @@ -0,0 +1,65 @@ +--- +title: 升级后更新 +description: "完成 npm 无法完成的那一半升级：迁移主目录并匹配守护进程" +--- + +```bash +npm install -g failproofai@latest && failproofai update +``` + +这就是完整的升级流程。`npm` 替换 CLI；`failproofai update` 完成其余工作。 + +## 为什么需要第二条命令 + +`npm install -g` 只替换一样东西——CLI。failproofai 安装中还有另外两个组件，它们有意存放在包之外，npm 运行时两者都不会移动： + +- **`~/.failproofai/`**，包含你的设置、云端注册信息、策略选择和历史记录。新版本可能采用不同的目录结构，而重组工作必须由同时了解新旧两种结构的代码来完成。 +- **`failproofaid` 守护进程二进制文件**，位于 `~/.failproofai/bin/failproofaid-`。它有意*不*放在 `node_modules` 中：如果升级时替换了正在运行的服务下的文件，就会让一个活跃的守护进程指向由不同源码构建的二进制文件；而删除该包则会在服务依赖的文件下将其删除，导致每次启动时崩溃循环。 + +因此，单独执行 `npm install -g` 后，CLI 是新的，而守护进程不是。`failproofaid` 拒绝针对它无法识别的主目录布局启动——这是版本不匹配时明显报错的方式，而非静默失败——所以需要将两者对齐。`failproofai update` 就是这个步骤。 + +## 它做了什么 + + + + 读取 `~/.failproofai/VERSION` 中记录的布局，并运行将其升级到当前版本所需格式的步骤。通常不需要任何操作——详见 + [`failproofai migrate`](/zh/cli/migrate)。 + + + 优先从 npm 已下载的平台包中获取（无需网络），否则从该精确版本的发布资产中获取，使用前经过 SHA-256 验证。 + + + 通过探测来确认，而非假设——服务管理器在进程刚 fork 时就会报告其处于活跃状态，这与其正常工作并不等同。 + + + +## 选项 + +| 标志 | 效果 | +|------|--------| +| `--no-daemon` | 仅迁移主目录，将守护进程保留在当前版本。| + + + `--no-daemon` 会保留一个版本不匹配的守护进程。在配置为需要守护进程的机器上，如果守护进程无法响应，每个 hook 事件都会**失败关闭**——而拒绝针对已迁移主目录启动的守护进程将无法响应。建议让守护进程那一半也正常运行。 + + +## 出错时的处理 + +命令以非零值退出，并指明哪一半失败了。有两种情况值得了解： + +- **某个迁移步骤未完成。** 主目录会被标记为*旧的*布局，因此下次运行时会重试——绝不会因部分迁移完成就将主目录标记为最新。在任何操作运行之前，你的设置和注册信息的副本已保存到 `~/.failproofai/migrations/backup-layout/`。 +- **守护进程无法在无密码的情况下重启。** 有意使用 `sudo -n`，因此在进度显示过程中不会有任何提示。命令会打印出需要你自行运行的确切命令行。 + + + 这里的操作不需要交互式设置向导。你的设置、云端注册信息和策略选择在升级后都会保留，因此迁移后的机器将与之前完全相同地执行策略——这对于无人值守的机器尤为重要：CI runner、集群节点、无头网关。 + + +## 自动化执行 + +`failproofai update` 是非交互式的，在没有任何需要处理时运行也是安全的——它会报告"无需迁移"并以 0 退出。建议在预配脚本或 Dockerfile 的每次升级后都加上这条命令： + +```dockerfile +RUN npm install -g failproofai@latest && failproofai update --no-daemon +``` + +（在镜像构建中使用 `--no-daemon`，因为此时还没有需要重启的服务。） \ No newline at end of file diff --git a/docs/zh/configuration.mdx b/docs/zh/configuration.mdx index 7eed068a..3ddfb12d 100644 --- a/docs/zh/configuration.mdx +++ b/docs/zh/configuration.mdx @@ -4,21 +4,21 @@ description: "配置文件格式、三级作用域系统及合并规则" icon: gear --- -failproofai 使用 JSON 配置文件来控制哪些策略处于激活状态、策略的行为方式，以及从何处加载自定义策略。配置设计上便于与团队共享——将其提交到代码仓库，每位开发者都能获得相同的智能体安全防护。 +failproofai 使用 JSON 配置文件来控制哪些策略处于激活状态、策略的行为方式，以及自定义策略的加载路径。配置设计为易于与团队共享——将其提交到代码仓库，每位开发者都能获得相同的智能体安全保障。 --- ## 配置作用域 -配置共有三个作用域，按优先级顺序依次评估： +共有三个配置作用域，按优先级顺序进行评估： | 作用域 | 文件路径 | 用途 | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | 按仓库配置，提交至版本控制 | -| **local** | `.failproofai/policies-config.local.json` | 个人按仓库覆盖配置，已添加至 gitignore | -| **global** | `~/.failproofai/policies-config.json` | 跨所有项目的用户级默认配置 | +| **project（项目）** | `.failproofai/policies-config.json` | 每个仓库的设置，提交到版本控制 | +| **local（本地）** | `.failproofai/policies-config.local.json` | 个人的仓库级覆盖配置，已加入 gitignore | +| **global（全局）** | `~/.failproofai/policies-config.json` | 跨所有项目的用户级默认配置 | -当 failproofai 收到钩子事件时，它会加载并合并当前工作目录下存在的所有三个文件。 +当 failproofai 收到 hook 事件时，它会加载并合并当前工作目录下所有存在的三个配置文件。 ### 合并规则 @@ -32,7 +32,7 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← 去重后的并集 ``` -**`policyParams`** — 对于给定策略，最先定义参数的作用域完全优先。策略参数内部不会进行深度合并。 +**`policyParams`** — 对于某个策略，第一个定义了参数的作用域完全优先。策略参数内部不进行深层合并。 ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -49,11 +49,11 @@ global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退至 global ``` -**`customPoliciesPaths` / `customPoliciesPath`** — 最先定义任意一种形式的作用域优先。 +**`customPoliciesPaths` / `customPoliciesPath`** — 第一个定义了任意一种形式的作用域优先。 -**`disabledCustomPolicies`** — 取所有作用域的并集。当你在仪表板中关闭来自显式或约定策略文件中的某个策略时，仪表板会将带来源限定符的 ID 写入此处。未列出的策略默认保持启用；ID 包含来源文件信息，因此多个文件中同名的策略可以独立控制。 +**`disabledCustomPolicies`** — 取所有作用域的并集。当你在仪表盘中关闭某个来自显式或约定策略文件的单独策略时，仪表盘会在此处写入带来源限定符的 ID。未列出的策略默认保持启用；ID 包含来源文件，因此多个文件中同名的策略可以独立控制。 -**`llm`** — 最先定义的作用域优先。 +**`llm`** — 第一个定义了该字段的作用域优先。 --- @@ -104,25 +104,25 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退至 global 类型：`string[]` -要启用的策略名称列表。名称必须与 `failproofai policies` 所显示的策略标识符完全匹配。完整列表请参见[内置策略](/zh/built-in-policies)。 +要启用的策略名称列表。名称必须与 `failproofai policies` 显示的策略标识符完全匹配。完整列表请参阅[内置策略](/zh/built-in-policies)。 -不在 `enabledPolicies` 中的策略均为非激活状态，即便其在 `policyParams` 中存在条目也是如此。 +未包含在 `enabledPolicies` 中的策略处于非激活状态，即使它们在 `policyParams` 中有对应条目。 ### `policyParams` 类型：`Record>` -按策略的参数覆盖配置。外层键为策略名称，内层键为各策略专有配置项。每个策略的可用参数均在[内置策略](/zh/built-in-policies)中有说明。 +每个策略的参数覆盖。外层键为策略名称，内层键为策略专属参数。各策略的可用参数详见[内置策略](/zh/built-in-policies)。 -若策略有参数但你未指定，则使用策略的内置默认值。未配置 `policyParams` 的用户与旧版本行为完全一致。 +如果策略有参数但未指定，则使用该策略的内置默认值。未配置 `policyParams` 的用户与旧版本的行为完全相同。 -策略参数块中的未知键在钩子触发时会被静默忽略，但在运行 `failproofai policies` 时会被标记为警告。 +策略参数块中的未知键在 hook 触发时会被静默忽略，但运行 `failproofai policies` 时会标记为警告。 -#### `hint`（通用配置项） +#### `hint`（通用） 类型：`string`（可选） -当策略返回 `deny` 或 `instruct` 时，附加到原因中的提示消息。可用于向 Claude 提供可操作的指导，而无需修改策略本身。 +当策略返回 `deny` 或 `instruct` 时，附加到原因信息后面的提示文本。可用于为 Claude 提供可操作的指引，而无需修改策略本身。 适用于所有策略类型——内置策略、自定义策略（`custom/`）、项目约定策略（`.failproofai-project/`）或用户约定策略（`.failproofai-user/`）。 @@ -143,46 +143,47 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退至 global } ``` -当 `block-force-push` 拒绝操作时，Claude 会看到：*"Force-pushing is blocked. Try creating a fresh branch instead."* +当 `block-force-push` 拒绝时，Claude 会看到：*"Force-pushing is blocked. Try creating a fresh branch instead."* -非字符串值和空字符串会被静默忽略。若未设置 `hint`，行为保持不变（向后兼容）。 +非字符串值和空字符串会被静默忽略。如果未设置 `hint`，行为保持不变（向后兼容）。 ### `customPoliciesPath` 类型：`string`（绝对路径） -包含自定义钩子策略的 JavaScript 文件路径。该字段由 `failproofai policies --install --custom ` 自动设置（路径在存储前会被解析为绝对路径）。 +包含自定义 hook 策略的 JavaScript 文件路径。该字段由 `failproofai policies --install --custom ` 自动设置（路径在存储前会被解析为绝对路径）。 -每次钩子事件触发时，该文件都会重新加载，不进行缓存。编写详情请参见[自定义策略](/zh/custom-policies)。 +每次 hook 事件触发时都会重新加载该文件，不进行缓存。编写详情请参阅[自定义策略](/zh/custom-policies)。 ### 基于约定的策略 -除显式的 `customPoliciesPath` 外，failproofai 还会自动发现并加载 `.failproofai/policies/` 目录中的策略文件： +除了显式的 `customPoliciesPath`，failproofai 还会自动发现并加载 `.failproofai/policies/` 目录中的策略文件： | 级别 | 目录 | 作用域 | |-------|-----------|-------| -| 项目级 | `.failproofai/policies/` | 通过版本控制与团队共享 | -| 用户级 | `~/.failproofai/policies/custom-policies/` | 个人使用，适用于所有项目 | +| 项目 | `.failproofai/policies/` | 通过版本控制与团队共享 | +| 用户 | `~/.failproofai/policies/` | 个人使用，适用于所有项目 | - 用户级目录在主目录重组时下移了一层。升级后首次运行任意 `failproofai` - 命令时，旧路径 `~/.failproofai/policies/` 下的文件会自动移入 - `custom-policies/`，且命令会告知你移动了哪些文件。 + 将你的策略文件直接放入 `~/.failproofai/policies/`。同目录下的 + `cloud-policies/` 文件夹存放的是组织部署到该机器的策略——发现机制不会扫描子目录，因此该文件夹永远不会被扫描，你放在 `policies/` 中的文件也不会与之冲突。 + + 如果你正在从使用 `~/.failproofai/policies/custom-policies/` 的旧版本升级，该文件夹中的所有内容——包括你的策略文件、它们导入的任何 `lib/` 辅助文件，以及它们读取的数据文件——在你首次运行 `failproofai` 命令时会自动移回上层目录，命令会告知你移动了哪些内容。 -**文件匹配规则：** 仅加载匹配 `*policies.{js,mjs,ts}` 的文件（例如 `security-policies.mjs`、`workflow-policies.js`），目录中的其他文件会被忽略。 +**文件匹配：** 只加载匹配 `*policies.{js,mjs,ts}` 的文件（例如 `security-policies.mjs`、`workflow-policies.js`）。目录中的其他文件会被忽略。 -**无需配置：** 约定策略无需在 `policies-config.json` 中添加任何条目。只需将文件放入目录，下次钩子事件触发时即会自动加载。 +**无需配置：** 约定策略不需要在 `policies-config.json` 中添加任何条目。只需将文件放入对应目录，下次 hook 事件触发时即可生效。 -**联合加载：** 项目级和用户级约定目录均会被扫描，两个级别的所有匹配文件都会被加载（与 `customPoliciesPath` 使用首个作用域优先的规则不同）。 +**联合加载：** 项目和用户约定目录均会被扫描。两个级别中所有匹配的文件都会被加载（与使用首个作用域优先规则的 `customPoliciesPath` 不同）。 -更多详情和示例请参见[自定义策略](/zh/custom-policies)。 +更多详情和示例请参阅[自定义策略](/zh/custom-policies)。 ### `llm` 类型：`object`（可选） -供需要进行 AI 调用的策略使用的 LLM 客户端配置。大多数场景下无需配置。 +用于进行 AI 调用的策略的 LLM 客户端配置。大多数场景下不需要此配置。 ```json { @@ -197,24 +198,24 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退至 global ## 通过 CLI 管理配置 -`policies --install` 和 `policies --uninstall` 命令写入智能体 CLI 的钩子设置文件（钩子入口点），而 `policies-config.json` 则是你直接管理的文件。两者相互独立： +`policies --install` 和 `policies --uninstall` 命令写入智能体 CLI 的 hook 设置文件（hook 入口点），而 `policies-config.json` 是你直接管理的文件。两者相互独立： - **智能体 CLI 设置** — 告知智能体在每次工具调用时执行 `failproofai --hook `： - - **Claude Code**：`~/.claude/settings.json`（用户级）、`/.claude/settings.json`（项目级）、`/.claude/settings.local.json`（本地级） - - **OpenAI Codex**：`~/.codex/hooks.json`（用户级）、`/.codex/hooks.json`（项目级）——Codex 没有 `local` 作用域 - - **GitHub Copilot CLI _(beta)_**：`~/.copilot/hooks/failproofai.json`（用户级）、`/.github/hooks/failproofai.json`（项目级）——Copilot 没有 `local` 作用域。钩子条目使用 Copilot 的操作系统键控 `bash`/`powershell` 命令字段及 `timeoutSec`；文件带有顶层 `version: 1` 标记。Copilot CLI 支持处于 **beta** 阶段，我们正在针对更多真实会话验证 `events.jsonl` 记录模式（公开文档中未予说明）。**VS Code Copilot Chat 智能体模式（预览版）** 通过 `chat.hookFilesLocations` 设置从 `.github/hooks/*.json`、`~/.copilot/hooks/*.json` 和 `~/.claude/settings.json` 读取钩子配置，使用与 Claude 相同的 `{hookSpecificOutput:{permissionDecision:"deny",…}}` 协议——这正是 `copilot` 集成和 `claude` 集成（`~/.claude/settings.json`）已写入的路径，因此 `failproofai policies --install --cli copilot`（或 `--cli claude`）**无需单独的 `vscode` 集成即可在 VS Code 智能体模式下强制执行**（已通过 VS Code 发现日志实时确认）。 - - **Cursor Agent _(beta)_**：`~/.cursor/hooks.json`（用户级）、`/.cursor/hooks.json`（项目级）——Cursor 没有 `local` 作用域。钩子条目使用 Claude 风格的 `{type, command, timeout}` 格式（无 `bash`/`powershell` 分离），但按照 Cursor 的[钩子模式](https://cursor.com/docs/hooks)以驼峰命名的事件键（`preToolUse`、`beforeSubmitPrompt` 等）存储于每个 Cursor 事件的扁平数组中；文件带有顶层 `version: 1` 标记。处理器通过 `CURSOR_EVENT_MAP` 将驼峰命名规范化为帕斯卡命名，使现有内置策略无需修改即可触发。Cursor Agent 支持处于 **beta** 阶段，我们正在针对更多真实安装验证 Cursor 的磁盘转录格式（公开文档中未予说明）。 - - **OpenCode _(beta)_**：`~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（用户级）、`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（项目级）——OpenCode 没有 `local` 作用域。与其他五个 CLI 不同，OpenCode **没有外部命令钩子系统**：它通过 `opencode.json` 中的 `plugin: []` 数组显式注册来加载进程内 JS/TS 插件（从 `.opencode/plugins/` 自动发现**不是** opencode v1.14.33 上插件加载的方式）。安装时会放置一个小型生成的插件垫片，该垫片以子进程方式调用 failproofai 二进制文件，并将二进制文件的 Claude 风格 JSON 响应转换为插件语义：工具事件拒绝时 `throw new Error()`（取消工具调用），instruct 及 `Stop`/`SubagentStop` 拒绝时 `client.session.prompt(...)`（将拒绝原因作为下一条用户消息提交——这是唯一的强制重试通道，因为 `session.idle` 仅用于通知，从中抛出异常无效），allow 时无操作。垫片在转发给二进制文件前会规范化工具名称（小写转帕斯卡命名，通过 `OPENCODE_TOOL_MAP`）和工具输入参数键（驼峰转蛇形命名，通过 `OPENCODE_TOOL_INPUT_MAP`，适用于 `Read`/`Write`/`Edit`，例如 `filePath` → `file_path`、`oldString` → `old_string`），因此路径检查内置策略如 `block-read-outside-cwd`、`block-env-files` 和 `block-secrets-write` 在 OpenCode 工具调用中可正常触发。会话存储于 `~/.local/share/opencode/opencode.db` 的 opencode SQLite 数据库中；仪表板的会话查看器通过 `opencode db --format json` 和 `opencode export ` 读取它们。OpenCode 支持处于 **beta** 阶段，我们正在跨版本和更多真实会话验证其行为。请参阅 [OpenCode 插件文档](https://opencode.ai/docs/plugins/)。 - - **Pi _(beta)_**：`~/.pi/agent/settings.json`（用户级）、`/.pi/settings.json`（项目级）——Pi 没有 `local` 作用域。Pi 在启动时加载 TypeScript 扩展包；设置文件是一个扁平字符串数组 `{"packages": ["./relative/path", …]}`。failproofai 写入一个指向其捆绑 `pi-extension/` 目录的 packages 数组条目。该扩展在内部订阅 Pi 的 `tool_call`/`user_bash`/`input`/`session_start` 事件，并以子进程方式调用 `failproofai --hook --cli pi`；处理器通过 `PI_EVENT_MAP` 将下划线小写蛇形命名规范化为帕斯卡命名，使现有内置策略无需修改即可触发。工具输入参数也通过 `PI_TOOL_INPUT_MAP` 进行规范化（Pi 的 Read/Write/Edit 传递 `path` 而非 `file_path`；映射顶层键使 `block-env-files` 和 `block-secrets-write` 得以触发——`block-read-outside-cwd` 已有 `path` 回退机制）。Pi 支持处于 **beta** 阶段，待 Pi 的扩展 API 和会话日志布局稳定后会进一步完善。 - - **Hermes (hermes-agent)**：`~/.hermes/config.yaml`（**仅用户作用域**——Hermes 没有项目/本地配置）。Hermes 是一个 Slack/Telegram **网关**，因此一次安装即可拦截来自所有平台（Slack/Telegram/cli/cron）**及**内部子智能体的工具调用。钩子条目是一个 `{command, timeout}` 对（超时单位为**秒**），位于以 Hermes 蛇形命名事件（`pre_tool_call`/`post_tool_call`/`on_session_start`/`on_session_end`/`subagent_stop`）为键的 `hooks:` 映射下；处理器通过 `HERMES_EVENT_MAP` 规范化事件名称，通过 `HERMES_TOOL_MAP` 规范化工具名称，使内置策略无需修改即可触发。配置通过保留注释的 YAML `Document` 往返编辑，以保留运营者的其他设置；安装时设置 `hooks_auto_accept: true`，使无头网关（无 TTY）在无需同意提示的情况下运行钩子。评估器输出 Hermes 的 `{"decision":"block","reason"}` stdout 协议（Hermes 忽略退出码）。**限制：** Hermes 没有轮次结束 `Stop` 事件，因此 `require-*-before-stop` 内置策略对其永不触发（不适用，而非故障）；`instruct` 降级为允许并记录日志（无附加上下文通道）；输出密钥脱敏（`sanitize-*`）无法通过 shell 钩子协议重写工具输出。Hermes **同时也是**离线**审计**来源——仪表板直接从 `~/.hermes/state.db` 读取其网关会话。 - - **OpenClaw (openclaw gateway)**：`~/.openclaw/openclaw.json`（**仅用户作用域**——OpenClaw 没有项目/本地配置）。与 Hermes 类似，OpenClaw 是一个自托管的多渠道**网关**，因此一次安装即可拦截来自所有渠道及其内部子智能体的工具调用。强制执行通过 OpenClaw 的**进程内插件钩子**运行（其基于文件的内部钩子仅用于观察，无法阻止），因此——与 OpenCode/Pi 类似——failproofai 提供了一个静态 `openclaw-plugin/` 包，以异步方式生成 failproofai 二进制文件并转换判决结果。安装时在 `openclaw.json` 的 `plugins.load.paths[]` 中注册所提供的插件目录，并在 `plugins.entries.failproofai` 下启用它（带有 `hooks.allowConversationAccess: true`，原始对话钩子必需）。评估器输出扁平的 `{permission, reason}` 判决，垫片将其映射到每个钩子的原生返回形式：`before_tool_call → {block:true, blockReason}`（**PreToolUse**）、`before_agent_run → {outcome:"block", reason}`（**UserPromptSubmit**）和 `before_agent_finalize → {action:"revise", reason}`（**Stop**——一个真正的轮次结束门控，因此 `require-*-before-stop` 内置策略**在 OpenClaw 上强制执行**，与 Hermes 不同）。事件和工具名称在二进制端通过 `OPENCLAW_EVENT_MAP`/`OPENCLAW_TOOL_MAP`（`exec→Bash`、`read→Read` 等）规范化，使内置策略无需修改即可触发；垫片在任何生成/解析/超时错误时失败并放行。OpenClaw **同时也是**离线**审计**来源——仪表板读取 `~/.openclaw/agents//sessions/.jsonl` 中的 JSONL 会话。 - - **Factory Droid (`droid`)**：`~/.factory/hooks.json`（用户级）、`/.factory/hooks.json`（项目级）——Factory 没有 `local` 作用域。droid 采用 Claude 风格的外部命令钩子系统，但经针对 droid v0.171.0 的实时验证，有两个特殊之处：（1）事件名称位于 `hooks.json` 的**顶层**——**没有 `"hooks"` 包装器**（droid 会拒绝它）；工具事件（`PreToolUse`/`PostToolUse`）带有 `"matcher": "*"`，非工具事件则省略它。（2）拒绝由钩子**退出码 2 + stderr** 驱动，而非 JSON 决策——评估器的 `factory` 分支对工具/提示事件返回退出码 2，仅在轮次结束 `Stop` 事件时返回 `{decision:"block", reason}`（droid 唯一的强制重试通道）。事件已是帕斯卡命名（无事件映射），负载为 Claude 蛇形命名；仅工具名称通过 `FACTORY_TOOL_MAP`（`Execute→Bash`、`Create→Write`、`FetchUrl→WebFetch` 等）规范化。Factory **同时也是**离线**审计**来源——仪表板读取 `~/.factory/sessions//.jsonl` 中的磁盘 JSONL 会话。 - - **Devin CLI (`devin`，Cognition)**：`~/.config/devin/config.json`（用户级）、`/.devin/config.json`（项目级）——Devin 没有 `local` 作用域。经针对 devin v3000.1.27 的实时验证，Devin 是一个**纯 Claude 克隆**：使用标准 Claude `"hooks"` 包装器模式（写入时保留合并，因此配置文件的其他键——`org_id`、`theme_mode` 等——得以保留），已是帕斯卡命名的事件（无事件映射，无处理器分支），以及 Claude 蛇形命名的 stdin 负载（无需规范化）。评估器的 `devin` 分支对**每个**事件在退出码 0 时以 `{"decision":"block","reason"}` JSON 输出到 stdout 进行拒绝（已验证——该块覆盖了 `--permission-mode dangerous`）；在轮次结束 `Stop` 事件中，原因携带 MANDATORY-ACTION 强制重试措辞，使 `require-*-before-stop` 内置策略得以强制执行。仅工具名称通过 `DEVIN_TOOL_MAP`（`exec→Bash`；`tool_input.command` 已是规范形式）规范化。Devin **同时也是**离线**审计**来源——仪表板读取 `~/.local/share/devin/cli/sessions.db` 中的 SQLite 会话（每个 `sessions` 行携带真实的 `working_directory`，因此会话像 Claude 一样按项目工作目录分组）。 - - **Antigravity CLI (`agy`)**：`~/.gemini/config/hooks.json`（用户级）、`/.agents/hooks.json`（项目级）——Antigravity 没有 `local` 作用域。与 Factory/Devin 不同，Antigravity 有其**自己的**协议（非 Claude 克隆），经针对 agy v1.1.2 的实时验证。`hooks.json` 使用**命名钩子**模式：顶层键为钩子*名称*（`"failproofai"`），其值为事件→处理器映射——工具事件（`PreToolUse`/`PostToolUse`）将处理器包装在 `{matcher:"*", hooks:[…]}` 中，而 `PreInvocation`/`Stop` 为**扁平**处理器数组（其他命名钩子得以保留）。stdin 负载为**驼峰命名的 protojson**（`toolCall:{name,args}`、`conversationId`、`workspacePaths`、`transcriptPath`）——failproofai 在策略运行前将其规范化为蛇形命名，并通过 `ANTIGRAVITY_TOOL_INPUT_MAP` 映射 `run_command` 的帕斯卡命名参数（`CommandLine`/`Cwd`）。评估器的 `antigravity` 分支使用 Antigravity **自己的**响应形式：`{decision:"deny", reason}` 阻止工具/提示（退出码 0），`{decision:"continue", reason}` 在轮次结束 `Stop` 时重新进入循环（使 `require-*-before-stop` 内置策略得以强制执行），`{injectSteps:[{ephemeralMessage}]}` 在 `PreInvocation`（→ `UserPromptSubmit`）时注入指令。工具名称通过 `ANTIGRAVITY_TOOL_MAP`（`run_command→Bash`、`view_file→Read` 等）规范化。Antigravity **同时也是**离线**审计**来源——仪表板读取 `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` 中的纯 JSONL 转录（对话索引位于 `conversation_summaries.db`）。 - - **Goose (代号 goose，Block)**：`~/.agents/plugins/failproofai/hooks/hooks.json`（用户级）、`/.agents/plugins/failproofai/hooks/hooks.json`（项目级）——Goose 没有 `local` 作用域。强制执行使用 Goose 的**钩子**系统，即跨智能体的 **Open Plugins** 规范：安装程序只需放置 `failproofai` 插件目录，Goose 在启动时自动发现并将其自注册到 `~/.config/goose/config.yaml`。`hooks.json` 使用带有顶层 `"hooks"` 包装器的 Open Plugins 模式，且每个事件上都**省略**了匹配器——裸 `"*"` 是一个无效正则表达式，不匹配任何内容（经针对 goose v1.43.0 的实时验证）。事件名称已是帕斯卡命名（无事件映射）；stdin 负载使用 `event`/`working_dir`，处理器将其规范化为 `hook_event_name`/`cwd`。评估器的 `goose` 分支在退出码 0 时以 `{"decision":"block","reason"}` JSON 输出到 stdout 进行拒绝，仅在 **`PreToolUse`** 事件上生效（goose ≥ v1.37.0 中提供）——该事件对 shell 工具**以及委托子智能体内部**均会触发，因此它是唯一足够的拒绝点；任何其他钩子错误均**失败并放行**。Goose **没有 `Stop` 事件**，因此 `require-*-before-stop` 内置策略不适用（与 Hermes 相同）。工具名称通过 `GOOSE_TOOL_MAP`（`shell→Bash`、`write→Write`、`todo__todo_write→TodoWrite` 等）规范化，路径键通过 `GOOSE_TOOL_INPUT_MAP`（`path`/`source` → `file_path`）规范化。Goose **同时也是**离线**审计**来源——仪表板读取 `~/.local/share/goose/sessions/sessions.db` 中的 SQLite 会话（每个 `sessions` 行携带真实的 `working_dir`，因此会话像 Devin 一样按项目工作目录分组；`--no-session` 临时运行会被过滤）。 -- **`policies-config.json`** — 告知 failproofai 评估哪些策略以及使用什么参数（跨所有智能体 CLI 共享） - -传入 `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` 以指定目标智能体（多个可用空格分隔或重复传入）： + - **Claude Code**：`~/.claude/settings.json`（用户级），`/.claude/settings.json`（项目级），`/.claude/settings.local.json`（本地级） + - **OpenAI Codex**：`~/.codex/hooks.json`（用户级），`/.codex/hooks.json`（项目级）——Codex 没有 `local` 作用域 + - **GitHub Copilot CLI _（测试版）_**：`~/.copilot/hooks/failproofai.json`（用户级），`/.github/hooks/failproofai.json`（项目级）——Copilot 没有 `local` 作用域。Hook 条目使用 Copilot 的操作系统键控 `bash`/`powershell` 命令字段（含 `timeoutSec`）；文件携带顶层 `version: 1` 标记。Copilot CLI 支持目前处于**测试版**，我们正在对照更多真实会话验证 `events.jsonl` 记录模式（公开文档中未说明）。**VS Code Copilot Chat 智能体模式（预览版）** 从 `.github/hooks/*.json`、`~/.copilot/hooks/*.json` 和 `~/.claude/settings.json`（由 `chat.hookFilesLocations` 设置管理）读取 hook 配置，使用与 Claude 相同的 `{hookSpecificOutput:{permissionDecision:"deny",…}}` 协议——这正是 `copilot` 集成和 `claude` 集成（`~/.claude/settings.json`）已经写入的路径，因此 `failproofai policies --install --cli copilot`（或 `--cli claude`）**已经在 VS Code 智能体模式下生效**，无需单独的 `vscode` 集成（已通过 VS Code 发现日志实时确认）。 + - **Cursor Agent _（测试版）_**：`~/.cursor/hooks.json`（用户级），`/.cursor/hooks.json`（项目级）——Cursor 没有 `local` 作用域。Hook 条目使用 Claude 风格的 `{type, command, timeout}` 格式（无 `bash`/`powershell` 区分），但按照 Cursor 的 [hooks 模式](https://cursor.com/docs/hooks)以驼峰命名事件键（`preToolUse`、`beforeSubmitPrompt` 等）存储在扁平数组中；文件携带顶层 `version: 1` 标记。处理器通过 `CURSOR_EVENT_MAP` 将驼峰命名规范化为帕斯卡命名，使现有内置策略无需修改即可触发。Cursor Agent 支持目前处于**测试版**，我们正在对照更多真实安装验证 Cursor 的磁盘上转录格式（公开文档中未说明）。 + - **OpenCode _（测试版）_**：`~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（用户级），`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（项目级）——OpenCode 没有 `local` 作用域。与其他五个 CLI 不同，OpenCode **没有外部命令 hook 系统**：它通过 `opencode.json` 中 `plugin: []` 数组显式注册的方式加载进程内 JS/TS 插件（从 `.opencode/plugins/` 自动发现**不是** opencode v1.14.33 上插件的加载方式）。安装时会放置一个小型生成的插件 shim，该 shim 通过子进程调用 failproofai 二进制文件，并将二进制文件的 Claude 风格 JSON 响应转换回插件语义：工具事件拒绝时使用 `throw new Error()`（取消工具调用），instruct 以及 `Stop`/`SubagentStop` 拒绝时使用 `client.session.prompt(...)`（将拒绝原因作为下一条用户消息提交——这是唯一的强制重试通道，因为 `session.idle` 仅用于通知，从中抛出异常是无操作），allow 时为无操作。shim 在转发给二进制文件之前，会规范化工具名称（小写→帕斯卡命名，通过 `OPENCODE_TOOL_MAP`）和工具输入参数键（驼峰→下划线命名，通过 `OPENCODE_TOOL_INPUT_MAP` 处理 `Read`/`Write`/`Edit`，例如 `filePath`→`file_path`，`oldString`→`old_string`），因此 `block-read-outside-cwd`、`block-env-files`、`block-secrets-write` 等路径检查内置策略在 OpenCode 工具调用中无需修改即可触发。会话存储在 OpenCode 的 SQLite 数据库 `~/.local/share/opencode/opencode.db` 中；仪表盘的会话查看器通过 `opencode db --format json` 和 `opencode export ` 读取它们。OpenCode 支持目前处于**测试版**，我们正在跨版本和更多真实会话验证其行为。请参阅 [OpenCode 插件文档](https://opencode.ai/docs/plugins/)。 + - **Pi _（测试版）_**：`~/.pi/agent/settings.json`（用户级），`/.pi/settings.json`（项目级）——Pi 没有 `local` 作用域。Pi 在启动时加载 TypeScript 扩展包；设置文件是一个扁平字符串数组 `{"packages": ["./relative/path", …]}`。failproofai 写入一个指向其打包的 `pi-extension/` 目录的 packages 数组条目。该扩展内部订阅 Pi 的 `tool_call`/`user_bash`/`input`/`session_start` 事件，并通过 shell 调用 `failproofai --hook --cli pi`；处理器通过 `PI_EVENT_MAP` 将下划线小写蛇形命名规范化为帕斯卡命名，使现有内置策略无需修改即可触发。工具输入参数也通过 `PI_TOOL_INPUT_MAP` 进行规范化（Pi 的 Read/Write/Edit 使用 `path` 而非 `file_path`；映射顶层键使 `block-env-files` 和 `block-secrets-write` 能够触发——`block-read-outside-cwd` 已有 `path` 回退）。Pi 支持目前处于**测试版**，等待 Pi 的扩展 API 和会话日志布局稳定。 + - **Hermes (hermes-agent)**：`~/.hermes/config.yaml`（**仅用户作用域**——Hermes 没有项目/本地配置）。Hermes 是一个 Slack/Telegram **网关**，因此一次安装即可拦截来自每个平台（Slack/Telegram/cli/cron）**以及**内部子智能体的工具调用。Hook 条目是 `{command, timeout}` 对（超时单位为**秒**），位于以 Hermes 蛇形命名事件（`pre_tool_call`/`post_tool_call`/`on_session_start`/`on_session_end`/`subagent_stop`）为键的 `hooks:` 映射下；处理器通过 `HERMES_EVENT_MAP` 规范化事件，通过 `HERMES_TOOL_MAP` 规范化工具名称，使内置策略无需修改即可触发。配置通过保留注释的 YAML `Document` 往返编辑，使操作者的其他设置得以保留；安装时设置 `hooks_auto_accept: true`，使无头网关（无 TTY）无需同意提示即可运行 hooks。评估器输出 Hermes 的 `{"decision":"block","reason"}` stdout 协议（Hermes 忽略退出码）。**限制：** Hermes 没有回合结束 `Stop` 事件，因此 `require-*-before-stop` 内置策略对其永远不会触发（不适用，而非故障）；`instruct` 降级为允许并记录日志（没有额外上下文通道）；输出密钥脱敏（`sanitize-*`）无法通过 shell-hook 协议改写工具输出。Hermes 也是一个离线**审计**来源——仪表盘直接从 `~/.hermes/state.db` 读取其网关会话。 + - **OpenClaw (openclaw gateway)**：`~/.openclaw/openclaw.json`（**仅用户作用域**——OpenClaw 没有项目/本地配置）。与 Hermes 类似，OpenClaw 是一个自托管的多渠道**网关**，因此一次安装即可拦截来自每个渠道及其内部子智能体的工具调用。执行通过 OpenClaw 的**进程内插件 hooks** 运行（其基于文件的内部 hooks 仅用于观察，无法阻断），因此——与 OpenCode/Pi 类似——failproofai 附带一个静态 `openclaw-plugin/` 包，异步生成 failproofai 二进制文件并转换结果。安装时在 `openclaw.json` 的 `plugins.load.paths[]` 中注册附带的插件目录，并在 `plugins.entries.failproofai` 下启用它（含 `hooks.allowConversationAccess: true`，这是原始对话 hooks 所必需的）。评估器输出扁平的 `{permission, reason}` 结果，shim 将其映射到各 hook 的原生返回形式：`before_tool_call → {block:true, blockReason}`（**PreToolUse**），`before_agent_run → {outcome:"block", reason}`（**UserPromptSubmit**），以及 `before_agent_finalize → {action:"revise", reason}`（**Stop**——这是真实的回合结束门控，因此 `require-*-before-stop` 内置策略**在 OpenClaw 上生效**，不同于 Hermes）。事件和工具名称在二进制端通过 `OPENCLAW_EVENT_MAP`/`OPENCLAW_TOOL_MAP` 规范化（`exec→Bash`、`read→Read` 等），使内置策略无需修改即可触发；shim 在任何生成/解析/超时错误时失败并开放通行。OpenClaw 也是一个离线**审计**来源——仪表盘读取 `~/.openclaw/agents//sessions/.jsonl` 中的 JSONL 会话。 + - **Factory Droid (`droid`)**：`~/.factory/hooks.json`（用户级），`/.factory/hooks.json`（项目级）——Factory 没有 `local` 作用域。droid 附带一个 Claude 风格的外部命令 hook 系统，但经过对 droid v0.171.0 的实时验证，存在两个特殊之处：(1) 事件名称位于 `hooks.json` 的**顶层**——**没有 `"hooks"` 包装器**（droid 会拒绝包装器）；工具事件（`PreToolUse`/`PostToolUse`）携带 `"matcher": "*"`，非工具事件省略它。(2) 拒绝由 hook **退出码 2 + stderr** 驱动，而非 JSON 决策——评估器的 `factory` 分支对工具/提示事件返回退出码 2，仅在回合结束 `Stop` 事件（droid 唯一的强制重试通道）上返回 `{decision:"block", reason}`。事件已为帕斯卡命名（无事件映射），payload 为 Claude 蛇形命名；仅工具名称通过 `FACTORY_TOOL_MAP` 规范化（`Execute→Bash`、`Create→Write`、`FetchUrl→WebFetch` 等）。Factory 也是一个离线**审计**来源——仪表盘从 `~/.factory/sessions//.jsonl` 读取其磁盘上 JSONL 会话。 + - **Devin CLI (`devin`, Cognition)**：`~/.config/devin/config.json`（用户级），`/.devin/config.json`（项目级）——Devin 没有 `local` 作用域。经过对 devin v3000.1.27 的实时验证，Devin 是一个**纯 Claude 克隆**：它使用标准 Claude 的 `"hooks"` 包装器模式（写入时保留合并，使配置文件的其他键——`org_id`、`theme_mode` 等——得以保留），已为帕斯卡命名的事件名称（无事件映射，无处理器分支），以及 Claude 蛇形命名的 stdin payload（无需规范化）。评估器的 `devin` 分支对**每个**事件均以退出码 0 在 stdout 输出 `{"decision":"block","reason"}` JSON 进行拒绝（已验证——该阻断覆盖了 `--permission-mode dangerous`）；在回合结束 `Stop` 事件上，原因携带 MANDATORY-ACTION 强制重试措辞，使 `require-*-before-stop` 内置策略生效。仅工具名称通过 `DEVIN_TOOL_MAP` 规范化（`exec→Bash`；`tool_input.command` 已为规范形式）。Devin 也是一个离线**审计**来源——仪表盘从 `~/.local/share/devin/cli/sessions.db` 读取其 SQLite 会话（每个 `sessions` 行携带真实的 `working_directory`，因此会话像 Claude 一样按项目 cwd 分组）。 + - **Antigravity CLI (`agy`)**：`~/.gemini/config/hooks.json`（用户级），`/.agents/hooks.json`（项目级）——Antigravity 没有 `local` 作用域。与 Factory/Devin 不同，Antigravity 有其**自己的**协议（并非 Claude 克隆），经过对 agy v1.1.2 的实时验证。`hooks.json` 使用**命名 hook** 模式：顶层键是 hook *名称*（`"failproofai"`），其值是事件→处理器映射——工具事件（`PreToolUse`/`PostToolUse`）将处理器包装在 `{matcher:"*", hooks:[…]}` 中，而 `PreInvocation`/`Stop` 是**扁平**处理器数组（其他命名 hooks 得以保留）。stdin payload 为 **驼峰命名 protojson**（`toolCall:{name,args}`、`conversationId`、`workspacePaths`、`transcriptPath`）——failproofai 在策略运行前将其规范化为蛇形命名，并通过 `ANTIGRAVITY_TOOL_INPUT_MAP` 映射 `run_command` 的帕斯卡命名参数（`CommandLine`/`Cwd`）。评估器的 `antigravity` 分支使用 Antigravity **自己的**响应形式：`{decision:"deny", reason}` 阻断工具/提示（退出码 0），`{decision:"continue", reason}` 在回合结束 `Stop` 时重新进入循环（使 `require-*-before-stop` 内置策略生效），`{injectSteps:[{ephemeralMessage}]}` 在 `PreInvocation`（→`UserPromptSubmit`）时注入指令。工具名称通过 `ANTIGRAVITY_TOOL_MAP` 规范化（`run_command→Bash`、`view_file→Read` 等）。Antigravity 也是一个离线**审计**来源——仪表盘从 `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` 读取其纯 JSONL 转录（对话索引在 `conversation_summaries.db` 中）。 + - **Goose (codename goose, Block)**：`~/.agents/plugins/failproofai/hooks/hooks.json`（用户级），`/.agents/plugins/failproofai/hooks/hooks.json`（项目级）——Goose 没有 `local` 作用域。执行使用 Goose 的 **hooks** 系统，即跨智能体的 **Open Plugins** 规范：安装器只需放置 `failproofai` 插件目录，Goose 在启动时自动发现它（并将其自注册到 `~/.config/goose/config.yaml`）。`hooks.json` 使用带顶层 `"hooks"` 包装器的 Open Plugins 模式，且每个事件上的 matcher **均省略**——裸 `"*"` 是无效的正则表达式，什么都匹配不到（经 goose v1.43.0 实时验证）。事件名称已为帕斯卡命名（无事件映射）；stdin payload 使用 `event`/`working_dir`，处理器将其规范化为 `hook_event_name`/`cwd`。评估器的 `goose` 分支以退出码 0 在 stdout 输出 `{"decision":"block","reason"}` JSON 进行拒绝，**仅在 `PreToolUse`** 事件上生效（goose ≥ v1.37.0 中已发布）——该事件对 shell 工具**以及委托子智能体内部**均会触发，因此是唯一充分的拒绝点；任何其他 hook 错误均**开放通行**。Goose **没有 `Stop` 事件**，因此 `require-*-before-stop` 内置策略不适用（与 Hermes 相同）。工具名称通过 `GOOSE_TOOL_MAP` 规范化（`shell→Bash`、`write→Write`、`todo__todo_write→TodoWrite` 等），路径键通过 `GOOSE_TOOL_INPUT_MAP` 规范化（`path`/`source` → `file_path`）。Goose 也是一个离线**审计**来源——仪表盘从 `~/.local/share/goose/sessions/sessions.db` 读取其 SQLite 会话（每个 `sessions` 行携带真实的 `working_dir`，因此会话像 Devin 一样按项目 cwd 分组；`--no-session` 临时运行会被过滤）。 +- **`policies-config.json`** — 告知 failproofai 评估哪些策略以及使用什么参数（在所有智能体 CLI 之间共享） + +使用 `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` 指定目标智能体（空格分隔或重复使用以指定任意子集）： ```bash failproofai policies --install --cli codex --scope project @@ -234,15 +235,33 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her 省略 `--cli` 时，`failproofai` 会检测已安装的智能体 CLI（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`）： - **检测到一个 CLI** — 自动选择该 CLI，无需提示。 -- **在交互式终端中检测到多个 CLI** — 显示方向键单选提示，分组为 `Detected (N)` 区域（包含一个`Install for all N detected` 聚合行及各个已检测到的 CLI）和 `Not installed (M) · install hooks ahead of time` 区域，列出所有未检测到的支持 CLI 作为预安装选项（↑↓ 移动，Enter 选择，^C 退出）。卸载流程仅显示 Detected 区域。 -- **在非交互式运行中检测到多个 CLI**（CI 环境、无 TTY）— 为所有检测到的 CLI 安装，无需提示。 -- **未检测到任何 CLI** — 回退至 `claude`，并警告在 PATH 中未找到智能体二进制文件；钩子命令仍会写入，待安装后立即生效。 +- **在交互式终端中检测到多个 CLI** — 显示方向键单选提示，分组为 `Detected (N)`（已检测到）区域（包含一个 `Install for all N detected` 聚合行 + 每个已检测到的 CLI）和 `Not installed (M) · install hooks ahead of time`（未安装）区域，列出每个未检测到的受支持 CLI 作为预安装选项（↑↓ 移动，Enter 确认，^C 退出）。卸载流程仅显示已检测到的区域。 +- **在非交互式运行中检测到多个 CLI**（CI、无 TTY）— 为所有检测到的 CLI 安装，无需提示。 +- **未检测到任何 CLI** — 回退到 `claude`，并显示警告说明在 PATH 中未找到智能体二进制文件；hook 命令仍然会被写入，一旦你安装了智能体即可激活。 + +你可以随时直接编辑 `policies-config.json`；更改会在下次 hook 事件触发时立即生效，无需重启。 + +## 升级时保留配置 + +新版本的 failproofai 可能会以不同方式组织 `~/.failproofai/` 目录。发生这种情况时，升级后首次运行命令会迁移目录，并且**你的配置会被保留，而不是重置**： + +| 保留 | 重建 | +|---|---| +| 你的策略选择和参数（`policies-config.json`） | 审计缓存 | +| 你的设置，包括 `daemon.configured` 和额外的捕获路径（`config.json`） | 云端管理的策略部署——在下次轮询时重新拉取并验证摘要 | +| 你的云端注册信息（`credentials.json`） | 守护进程临时状态 | +| 你在 `policies/` 中的策略文件及其导入的辅助文件 | | +| 仪表盘读取的决策日志以及尚未投递的事件 | | + +*较新版本* failproofai 写入的键也会被保留，而不是被旧版本读取器丢弃——因此在版本间切换不会在任一方向上静默丢弃设置。 + +升级后**无需重新运行设置**：迁移后的机器的执行效果与之前完全相同，这正是在无人值守的机器上升级安全的原因。每次迁移都记录在 `~/.failproofai/migrations/applied.json` 中，不可替代的文件会在执行任何操作前备份到 `~/.failproofai/migrations/backup-layout/`。 -你可以随时直接编辑 `policies-config.json`；更改会在下次钩子事件时立即生效，无需重启。 +单行升级命令请参阅 [`failproofai update`](/zh/cli/update)，详情请参阅 [`failproofai migrate`](/zh/cli/migrate)——包括 `--dry-run` 选项。 --- -## 示例：带团队默认配置的项目级配置 +## 示例：带团队默认值的项目级配置 将 `.failproofai/policies-config.json` 提交到你的代码仓库： @@ -263,4 +282,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi her } ``` -每位开发者可以创建 `.failproofai/policies-config.local.json`（已添加至 gitignore）用于个人覆盖配置，而不影响其他团队成员。 \ No newline at end of file +每位开发者可以在此基础上创建 `.failproofai/policies-config.local.json`（已加入 gitignore）来进行个人覆盖，而不会影响其他团队成员。 \ No newline at end of file diff --git a/docs/zh/custom-policies.mdx b/docs/zh/custom-policies.mdx index 08c3e0e3..428f12c7 100644 --- a/docs/zh/custom-policies.mdx +++ b/docs/zh/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: 自定义策略 -description: "用 JavaScript 编写自己的策略——强制执行项目规范、防止漂移、检测失败、与外部系统集成" +description: "用 JavaScript 编写自己的策略——强制执行项目规范、防止配置漂移、检测故障、与外部系统集成" icon: code --- -自定义策略让你可以为任意 Agent 行为编写规则：强制执行项目规范、防止状态漂移、拦截破坏性操作、检测卡死的 Agent，或与 Slack、审批工作流等系统集成。它们使用与内置策略相同的 Hook 事件系统以及 `allow`、`deny`、`instruct` 决策机制。 +自定义策略让你能够为任何 Agent 行为编写规则：强制执行项目规范、防止配置漂移、拦截破坏性操作、检测卡住的 Agent，或与 Slack、审批工作流等系统集成。它们使用与内置策略相同的 hook 事件系统以及 `allow`、`deny`、`instruct` 决策机制。 --- @@ -39,53 +39,53 @@ failproofai policies --install --custom ./my-policies.js ## 加载自定义策略的两种方式 -### 方式一：基于约定（推荐） +### 方式一：约定式（推荐） -将 `*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}` 的文件，其他文件会被忽略 -- 每个文件独立加载（单个文件失败不影响其他文件） -- 可与显式 `--custom` 及内置策略共同使用 +- 项目目录和用户目录均会被扫描（取并集，而非先匹配优先） +- 目录内文件按字母顺序加载；可通过 `01-`、`02-` 前缀控制加载顺序 +- 只加载匹配 `*policies.{js,mjs,ts}` 的文件，其他文件会被忽略 +- 每个文件独立加载（单文件失败不影响其他文件） +- 可与显式 `--custom` 和内置策略共存 -基于约定的策略是为团队建立质量标准的最简方式。将 `.failproofai/policies/` 提交到 git，每位团队成员即可自动获得相同的规则——无需逐人配置。随着团队不断发现新的失败模式，只需添加策略并推送。久而久之，这些策略将成为一份随每次贡献持续完善的活质量标准。 +约定式策略是为团队建立质量标准的最简便方式。将 `.failproofai/policies/` 提交到 git，每位团队成员就能自动获得相同的规则，无需任何个人配置。随着团队不断发现新的故障模式，只需添加策略并推送。随着时间推移，这些策略将成为持续迭代的活性质量标准。 -### 方式二：显式指定文件路径 +### 方式二：显式文件路径 ```bash -# 安装时指定自定义策略文件 +# 使用自定义策略文件安装 failproofai policies --install --custom ./my-policies.js # 替换自定义策略路径 failproofai policies --install --custom ./new-policies.js -# 配置多个显式文件（按标志顺序加载） +# 配置多个显式文件（按 flag 顺序加载） failproofai policies --install --custom ./security.js --custom ./workflow.js # 从配置中移除所有显式自定义策略路径 failproofai policies --uninstall --custom ``` -解析后的绝对路径以 `customPoliciesPaths` 字段存储在 `policies-config.json` 中。重复使用 `--custom` 可配置多个文件。使用旧版 `customPoliciesPath` 字段的现有配置仍可正常工作。文件在每次 Hook 事件时重新加载，事件之间不存在缓存。 +解析后的绝对路径会以 `customPoliciesPaths` 字段存储在 `policies-config.json` 中。重复使用 `--custom` 可配置多个文件。使用旧版 `customPoliciesPath` 字段的现有配置仍可正常工作。每次 hook 事件触发时文件都会重新加载，事件之间不存在缓存。 -每个已注册的策略都会在控制台中显示独立的开关。关闭某个策略时，其含源文件限定的 ID 会被记录到 `disabledCustomPolicies`；对应文件及其他策略仍会继续加载，仅禁用的策略会在事件匹配前被排除。跨文件重名的策略拥有独立的开关。 +每个已注册的策略在控制面板中都有独立的开关。关闭某个策略会将其源限定 ID 记录到 `disabledCustomPolicies` 中；该文件及其包含的其他策略继续加载，被禁用的策略会在事件匹配前被排除。不同文件中重名的策略拥有各自独立的开关。 -### 同时使用两种方式 +### 两种方式并用 -基于约定的策略与显式 `--custom` 文件可以共存。加载顺序如下： +约定式策略与显式 `--custom` 文件可以共存。加载顺序如下： 1. 显式 `customPoliciesPaths` 文件（按配置顺序） 2. 项目约定文件（`{cwd}/.failproofai/policies/`，按字母顺序） @@ -117,31 +117,31 @@ customPolicies.add({ ### 决策辅助函数 | 函数 | 效果 | 适用场景 | -|----------|--------|----------| -| `allow()` | 静默允许该操作 | 操作安全，无需任何提示 | -| `deny(message)` | 拦截该操作 | Agent 不应执行此操作 | -| `instruct(message)` | 添加上下文但不拦截 | 为 Agent 提供额外上下文以保持正轨 | +|------|------|----------| +| `allow()` | 静默允许操作 | 操作安全，无需任何提示 | +| `deny(message)` | 阻止操作 | Agent 不应执行此操作 | +| `instruct(message)` | 添加上下文但不阻止 | 为 Agent 提供额外信息以保持正轨 | -`deny(message)` —— 消息会以 `"Blocked by failproofai:"` 为前缀呈现给 Claude。单次 `deny` 会短路所有后续评估。 +`deny(message)` — 消息会以 `"Blocked by failproofai:"` 为前缀显示给 Claude。单个 `deny` 会短路所有后续评估。 -`instruct(message)` —— 消息会附加到 Claude 当前工具调用的上下文中。所有 `instruct` 消息会被累积后统一传递。 +`instruct(message)` — 消息会附加到 Claude 当前工具调用的上下文中。所有 `instruct` 消息会被累积并一并送达。 -你可以通过在 `policyParams` 中添加 `hint` 字段，为任意 `deny` 或 `instruct` 消息追加额外指引——无需修改代码。这对自定义（`custom/`）、项目约定（`.failproofai-project/`）和用户约定（`.failproofai-user/`）策略同样适用。详见[配置 → hint](/zh/configuration#hint-cross-cutting)。 +你可以通过在 `policyParams` 中添加 `hint` 字段，为任意 `deny` 或 `instruct` 消息附加额外说明——无需修改代码。这对自定义（`custom/`）、项目约定（`.failproofai-project/`）和用户约定（`.failproofai-user/`）策略同样适用。详情参见[配置 → hint](/zh/configuration#hint-cross-cutting)。 ### 信息性 allow 消息 -`allow(message)` 在允许操作的同时，向 Claude 发送一条信息性消息。该消息通过 Hook 处理器 stdout 响应中的 `additionalContext` 传递——与 `instruct` 使用相同的机制，但语义不同：它是状态更新，而非警告。 +`allow(message)` 允许操作**并**向 Claude 发送一条信息性消息。该消息通过 hook 处理器的 stdout 响应中的 `additionalContext` 送达——与 `instruct` 使用相同的机制，但语义不同：它是状态通知，而非警告。 | 函数 | 效果 | 适用场景 | -|----------|--------|----------| -| `allow(message)` | 允许操作并向 Claude 发送上下文 | 确认检查通过，或说明某项检查被跳过的原因 | +|------|------|----------| +| `allow(message)` | 允许操作并向 Claude 发送上下文 | 确认检查通过，或说明为何跳过某项检查 | 使用场景： -- **状态确认：** `allow("All CI checks passed.")` —— 告知 Claude 一切正常 -- **失败开放说明：** `allow("GitHub CLI not installed, skipping CI check.")` —— 告知 Claude 某项检查被跳过的原因，使其获得完整上下文 -- **多条消息累积：** 如果多个策略各自返回 `allow(message)`，所有消息将以换行符连接后统一传递 +- **状态确认：** `allow("All CI checks passed.")` — 告知 Claude 一切正常 +- **失败开放说明：** `allow("GitHub CLI not installed, skipping CI check.")` — 告知 Claude 为何跳过检查，使其拥有完整上下文 +- **多条消息累积：** 若多个策略各自返回 `allow(message)`，所有消息将以换行符连接后一并送达 ```js customPolicies.add({ @@ -162,18 +162,18 @@ customPolicies.add({ ### `PolicyContext` 字段 -| 字段 | 类型 | 描述 | -|-------|------|-------------| +| 字段 | 类型 | 说明 | +|------|------|------| | `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` | -| `toolName` | `string \| undefined` | 被调用的工具（如 `"Bash"`、`"Write"`、`"Read"`） | +| `toolName` | `string \| undefined` | 被调用的工具（例如 `"Bash"`、`"Write"`、`"Read"`） | | `toolInput` | `Record \| undefined` | 工具的输入参数 | -| `payload` | `Record` | 来自 Claude Code 的完整原始事件载荷 | +| `payload` | `Record` | 来自 Claude Code 的完整原始事件负载 | | `session` | `SessionMetadata \| undefined` | 会话上下文（见下文） | ### `SessionMetadata` 字段 -| 字段 | 类型 | 描述 | -|-------|------|-------------| +| 字段 | 类型 | 说明 | +|------|------|------| | `sessionId` | `string` | Claude Code 会话标识符 | | `cwd` | `string` | Claude Code 会话的工作目录 | | `transcriptPath` | `string` | 会话 JSONL 记录文件的路径 | @@ -181,25 +181,25 @@ customPolicies.add({ ### 事件类型 | 事件 | 触发时机 | `toolInput` 内容 | -|-------|--------------|----------------------| -| `PreToolUse` | Claude 执行工具前 | 工具的输入（如 Bash 对应 `{ command: "..." }`） | +|------|----------|------------------| +| `PreToolUse` | Claude 运行工具之前 | 工具的输入（例如 Bash 对应 `{ command: "..." }`） | | `PostToolUse` | 工具执行完成后 | 工具的输入 + `tool_result`（输出内容） | -| `Notification` | Claude 发送通知时 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` —— Hook 必须始终返回 `allow()`，无法拦截通知 | +| `Notification` | Claude 发送通知时 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — hook 必须始终返回 `allow()`，不能阻止通知 | | `Stop` | Claude 会话结束时 | 空 | --- ## 评估顺序 -策略按以下顺序进行评估： +策略按以下顺序评估： 1. 内置策略（按定义顺序） -2. 来自 `customPoliciesPath` 的显式自定义策略（按 `.add()` 调用顺序） +2. 来自 `customPoliciesPath` 的显式自定义策略（按 `.add()` 顺序） 3. 项目 `.failproofai/policies/` 中的约定策略（文件按字母顺序，文件内按 `.add()` 顺序） 4. 用户 `~/.failproofai/policies/` 中的约定策略（文件按字母顺序，文件内按 `.add()` 顺序） -首个 `deny` 会短路所有后续策略。所有 `instruct` 消息会被累积后统一传递。 +第一个 `deny` 会短路所有后续策略。所有 `instruct` 消息会被累积并一并送达。 --- @@ -223,7 +223,7 @@ customPolicies.add({ }); ``` -所有从入口文件可达的相对导入均会被解析。其实现方式是将 `from "failproofai"` 的导入重写为实际的 dist 路径，并创建临时 `.mjs` 文件以确保 ESM 兼容性。 +从入口文件可达的所有相对导入均会被解析。实现方式是将 `from "failproofai"` 的导入重写为实际的 dist 路径，并创建临时 `.mjs` 文件以确保 ESM 兼容性。 --- @@ -247,22 +247,22 @@ customPolicies.add({ --- -## 错误处理与失败模式 +## 错误处理与故障模式 -自定义策略采用**失败开放**原则：错误不会阻止内置策略运行，也不会导致 Hook 处理器崩溃。 +自定义策略采用**失败开放**原则：错误不会阻止内置策略执行，也不会导致 hook 处理器崩溃。 -| 失败情况 | 行为 | -|---------|----------| -| `customPoliciesPath` 未设置 | 不运行显式自定义策略；约定策略和内置策略照常继续 | +| 故障情况 | 行为 | +|----------|------| +| `customPoliciesPath` 未设置 | 不运行显式自定义策略；约定策略和内置策略正常继续 | | 文件未找到 | 警告记录到 `~/.failproofai/hook.log`；内置策略继续运行 | -| 语法/导入错误（显式） | 错误记录到 `~/.failproofai/hook.log`；显式自定义策略跳过 | -| 语法/导入错误（约定） | 错误记录；该文件跳过，其他约定文件仍正常加载 | -| `fn` 运行时抛出异常 | 错误记录；该 Hook 视为 `allow`；其他 Hook 继续运行 | -| `fn` 执行超过 10 秒 | 超时记录；视为 `allow` | +| 语法/导入错误（显式） | 错误记录到 `~/.failproofai/hook.log`；跳过显式自定义策略 | +| 语法/导入错误（约定式） | 错误已记录；跳过该文件，其他约定文件仍正常加载 | +| `fn` 运行时抛出异常 | 错误已记录；该 hook 视为 `allow`；其他 hook 继续运行 | +| `fn` 执行超过 10 秒 | 超时已记录；视为 `allow` | | 约定目录不存在 | 不运行约定策略；不报错 | -要调试自定义策略错误，可监听日志文件： +如需调试自定义策略错误，可监视日志文件： ```bash tail -f ~/.failproofai/hook.log @@ -277,7 +277,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// 防止 Agent 写入 secrets/ 目录 +// 阻止 Agent 向 secrets/ 目录写入 customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -305,7 +305,7 @@ customPolicies.add({ }, }); -// 在冻结期内防止计划外的依赖变更 +// 在冻结期间阻止计划外的依赖变更 customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -326,16 +326,16 @@ export { customPolicies }; --- -## 示例文件 +## 示例 `examples/` 目录包含开箱即用的策略文件： | 文件 | 内容 | -|------|----------| -| `examples/policies-basic.js` | 五个入门策略，涵盖常见 Agent 失败模式 | -| `examples/policies-advanced/index.js` | 高级模式：传递性导入、异步调用、输出脱敏和会话结束 Hook | -| `examples/convention-policies/security-policies.mjs` | 基于约定的安全策略（拦截 .env 写入、防止 git 历史重写） | -| `examples/convention-policies/workflow-policies.mjs` | 基于约定的工作流策略（测试提醒、文件写入审计） | +|------|------| +| `examples/policies-basic.js` | 涵盖常见 Agent 故障模式的五个入门策略 | +| `examples/policies-advanced/index.js` | 高级模式：传递性导入、异步调用、输出清理和会话结束 hook | +| `examples/convention-policies/security-policies.mjs` | 约定式安全策略（阻止 .env 写入、防止 git 历史改写） | +| `examples/convention-policies/workflow-policies.mjs` | 约定式工作流策略（测试提醒、审计文件写入） | ### 使用显式文件示例 @@ -343,16 +343,16 @@ export { customPolicies }; failproofai policies --install --custom ./examples/policies-basic.js ``` -### 使用基于约定的示例 +### 使用约定式示例 ```bash -# 复制到项目级别 +# 复制到项目级 mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# 或复制到用户级别 +# 或复制到用户级 mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -无需安装命令——文件将在下次 Hook 事件时自动被识别加载。 \ No newline at end of file +无需安装命令——下次 hook 事件触发时文件会自动被加载。 \ No newline at end of file diff --git a/docs/zh/dashboard.mdx b/docs/zh/dashboard.mdx index 54438c6c..dae65ff5 100644 --- a/docs/zh/dashboard.mdx +++ b/docs/zh/dashboard.mdx @@ -1,22 +1,22 @@ --- -title: 控制台 +title: 仪表盘 description: "监控 Agent 会话、查看工具调用并管理策略" icon: chart-line --- -failproofai 控制台是一个本地 Web 应用，用于监控 AI Agent 会话和管理策略。查看 Agent 在您离开期间所做的一切。 +failproofai 仪表盘是一个本地 Web 应用，用于监控 AI Agent 会话和管理策略。查看 Agent 在你离开期间做了什么。 --- -## 启动控制台 +## 启动仪表盘 ```bash failproofai ``` -访问地址：`http://localhost:8020`。 +在 `http://localhost:8020` 打开。 -控制台直接从文件系统读取本地项目、会话和 failproofai 配置数据。可选的需认证功能（如审计提醒和邀请）会将相关请求所需的信息（包括电子邮件地址）发送至远程 API。 +仪表盘直接从文件系统读取本地项目、会话和 failproofai 配置数据。可选的身份验证功能（如审计提醒和邀请）会将相关请求所需的信息（包括电子邮件地址）发送至远程 API。 --- @@ -24,14 +24,14 @@ failproofai ### 项目 -列出在您计算机上发现的所有 Claude Code、OpenAI Codex、GitHub Copilot CLI _(beta)_、Cursor Agent _(beta)_、OpenCode _(beta)_、Pi _(beta)_、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 和 Goose 项目。Claude 项目从 `~/.claude/projects/`（或由 `CLAUDE_PROJECTS_PATH` 设置的路径）中发现；Codex 项目通过扫描 `~/.codex/sessions///
/*.jsonl` 下的所有记录并按每个会话第一条记录中的 `cwd` 分组来发现；Copilot CLI 项目通过扫描各 `~/.copilot/session-state//workspace.yaml`（可通过 `COPILOT_HOME` 配置）并按其 `cwd` 字段分组来发现；Cursor Agent 项目通过扫描 `~/.cursor/agent-sessions//`（可通过 `CURSOR_HOME` 配置，备用路径为 `conversations/` 和 `sessions/`）下每个会话的元数据，从 `meta.json` / `session.json` / `workspace.yaml` 中查找 `cwd` 标量来发现；OpenCode 项目通过 `opencode db --format json` 查询位于 `~/.local/share/opencode/opencode.db` 的 SQLite 数据库来发现（读取 `session` 和 `project` 表并按 `project_id` 分组）；Pi 项目通过扫描 `~/.pi/agent/sessions//_.jsonl`（可通过 `PI_SESSIONS_DIR` 配置）下每个会话的 JSONL 记录，并从每个会话的第一条记录中提取 `cwd` 来发现；Hermes 网关会话直接从每个配置文件的 SQLite 存储中读取——`~/.hermes/state.db` 以及 `~/.hermes/profiles//state.db`（可通过 `HERMES_HOME` 覆盖，或通过 `HERMES_DB_PATH` 指定单一数据库）——并按配置文件和 `source`（Slack/Telegram/cli/cron——网关会话没有 cwd）分组为 `hermes--` 项目；OpenClaw 网关会话从 `~/.openclaw/agents//sessions/*.jsonl` 读取，并按 agent 和频道分组为 `openclaw--` 项目（同样没有 cwd）；Factory Droid 项目从 `~/.factory/sessions//*.jsonl` 的 JSONL 记录中发现并按 cwd 分组；Devin 项目从 `~/.local/share/devin/cli/sessions.db` 的 SQLite 数据库（按每个会话的 `working_directory` 分组）中发现；Antigravity 项目从 `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` 的 JSONL 记录中发现并按 cwd 分组；Goose 项目从 `~/.local/share/goose/sessions/sessions.db` 的 SQLite 数据库（按每个会话的 `working_dir` 分组）中发现。被多个 CLI 使用过的项目会渲染为带有所有匹配徽章的单行。使用表格上方的 **CLI** 下拉菜单按特定 agent CLI 筛选；URL 会将您的选择保留为 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`。 +列出在你的机器上发现的所有 Claude Code、OpenAI Codex、GitHub Copilot CLI _(beta)_、Cursor Agent _(beta)_、OpenCode _(beta)_、Pi _(beta)_、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 和 Goose 项目。Claude 项目从 `~/.claude/projects/`（或 `CLAUDE_PROJECTS_PATH` 设置的路径）中发现；Codex 项目通过扫描 `~/.codex/sessions///
/*.jsonl` 下的所有记录并按每个会话第一条记录中的 `cwd` 分组来发现；Copilot CLI 项目通过扫描每个 `~/.copilot/session-state//workspace.yaml`（可通过 `COPILOT_HOME` 配置）并按其 `cwd` 字段分组来发现；Cursor Agent 项目通过扫描 `~/.cursor/agent-sessions//`（可通过 `CURSOR_HOME` 配置，备用路径为 `conversations/` 和 `sessions/`）下的会话元数据，从 `meta.json` / `session.json` / `workspace.yaml` 中查找 `cwd` 标量来发现；OpenCode 项目通过 `opencode db --format json` 查询其位于 `~/.local/share/opencode/opencode.db` 的 SQLite 数据库来发现（读取 `session` 和 `project` 表并按 `project_id` 分组）；Pi 项目通过扫描 `~/.pi/agent/sessions//_.jsonl`（可通过 `PI_SESSIONS_DIR` 配置）下的 JSONL 记录并从每个会话的第一条记录中提取 `cwd` 来发现；Hermes 网关会话直接从每个配置文件的 SQLite 存储中读取——`~/.hermes/state.db` 及 `~/.hermes/profiles//state.db`（可通过 `HERMES_HOME` 或单数据库的 `HERMES_DB_PATH` 覆盖）——并按配置文件和 `source`（Slack/Telegram/cli/cron，网关会话没有 cwd）分组为 `hermes--` 项目；OpenClaw 网关会话从 `~/.openclaw/agents//sessions/*.jsonl` 读取并按 Agent 和频道分组为 `openclaw--` 项目（同样没有 cwd）；Factory Droid 项目从 `~/.factory/sessions//*.jsonl` 的 JSONL 记录中发现并按 cwd 分组；Devin 项目从其位于 `~/.local/share/devin/cli/sessions.db` 的 SQLite 数据库中发现（按每个会话的 `working_directory` 分组）；Antigravity 项目从 `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` 的 JSONL 记录中发现并按 cwd 分组；Goose 项目从其位于 `~/.local/share/goose/sessions/sessions.db` 的 SQLite 数据库中发现（按每个会话的 `working_dir` 分组）。被多个 CLI 使用过的项目会渲染为一行，并显示所有匹配的徽章。使用表格上方的 **CLI** 下拉菜单按特定 Agent CLI 筛选；URL 会将你的选择保留为 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`。 -Hermes 和 OpenClaw 是用户范围的，没有可用于分组的工作目录，因此它们渲染为**可折叠的文件夹树**——顶层为配置文件（或 agent），其下为各频道——而所有基于 cwd 的 CLI 保持平铺行。文件夹行汇总其下所有项的会话计数和最近活动，折叠状态在访问间保留，关键字搜索会展开匹配项。 +Hermes 和 OpenClaw 是用户范围的，没有可用于分组的工作目录，因此它们渲染为**可折叠文件夹树**——顶级为配置文件（或 Agent），其下为频道——而所有基于 cwd 的 CLI 保持平铺行显示。文件夹行汇总其下所有内容的会话数和最近活动时间，折叠状态在访问间保持记忆，关键词搜索会展开匹配的内容。 每个项目显示： - 项目名称（从文件夹路径派生） - CLI 徽章——`Claude Code`（橙色）、`OpenAI Codex`（紫色）、`GitHub Copilot`（蓝色）、`Cursor Agent`（翠绿色）、`OpenCode`（琥珀色）、`Pi`（粉色）和/或 `Hermes`（靛蓝色） -- 最近会话活动的日期 +- 最近会话活动日期 点击项目可查看其会话。 @@ -41,52 +41,52 @@ Hermes 和 OpenClaw 是用户范围的，没有可用于分组的工作目录， - 会话 ID - 开始和结束时间戳 - 工具调用次数 -- 钩子活动计数（触发的策略数） +- Hook 活动计数（触发的策略数） -使用日期范围筛选器和会话 ID 搜索来缩小范围。会话支持分页。 +使用日期范围过滤器和会话 ID 搜索来缩小列表范围。会话以分页方式展示。 点击会话可打开会话查看器。 ### 会话查看器 -会话查看器解答自主 Agent 的关键问题：Agent 做了什么，它是否保持在正轨上？标题旁的 CLI 徽章指示会话是 Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 还是 Goose 的记录。它显示会话中发生的所有事件的时间线： +会话查看器回答了自主 Agent 的核心问题：Agent 做了什么，是否保持在正轨上？页眉旁的 CLI 徽章指示该会话是 Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 还是 Goose 的记录。它展示会话中发生的一切的时间线： - **消息** - Claude 的文本响应和用户提示 -- **工具调用** - Claude 调用的每个工具及其输入和输出 +- **工具调用** - Claude 调用的每个工具，包含其输入和输出 - **策略活动** - 每次工具调用触发了哪些策略以及返回了什么决策 -顶部的统计栏显示会话时长、总工具调用次数以及钩子决策摘要（allow / deny / instruct 计数）。 +顶部的统计栏显示会话时长、总工具调用次数以及 Hook 决策摘要（allow / deny / instruct 计数）。 -点击 **下载日志** 按钮导出会话。Claude Code、Codex、Copilot、Cursor 和 Pi 会话将获得磁盘上的原始 JSONL 记录（逐字节）；OpenCode（其会话存储在 SQLite 中而非磁盘上）则获得一个镜像底层 `session` / `messages` / `parts` 表的 JSON 文档。 +点击**下载日志**按钮可导出会话。对于 Claude Code、Codex、Copilot、Cursor 和 Pi 会话，你将获得磁盘上原始 JSONL 记录的逐字节副本；对于 OpenCode（其会话存储在 SQLite 而非磁盘文件中），你将获得一个 JSON 文档，镜像底层的 `session` / `messages` / `parts` 表。 ### 审计 -关于您的 Agent 在过去会话中实际行为表现的个性化报告。运行与 `failproofai audit` CLI 相同的扫描，但以单屏可分享海报 + 四个折叠内容区块的形式呈现： +一份以个性化方式呈现的报告，反映你的 Agent 在过去会话中的实际行为。运行与 `failproofai audit` CLI 相同的扫描，并将其渲染为一张单屏可分享的海报和四个折叠区域： -1. **海报** — 填满第一屏视口。自包含的 PNG 截图区域，包含 failproof_ai 品牌标识 + 审计标签·原型索引（`№ NN of 08`）+ 审计日期·数字评分（0–100）+ 百分位排名徽章（`top 15%`）·原型名称（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` 之一）+ 3 关键词条·`// only N% of agents are this archetype` 稀有度行·8×8 像素印记图块·`audit yours → failproof.ai` 页脚。截图框外有三个分享按钮：`post your archetype`（X 意图）、`share on linkedin`、`download poster`。截图通过 `html-to-image` 运行，因此 PNG 与屏幕上的渲染像素完全一致（虚线边框、SVG logo 遮罩、渐变、字体度量——全部保留）。 -2. **优势** — 列出您的 Agent 已经做得正确的行为，以平和的 ✓ 列表形式展示，数据来源于实时审计数据（干净的工具调用率、无直接推送到主分支、零凭证泄露、零重试风暴）——仅当相关策略在审计窗口内记录清白时才会显示。 -3. **问题** — 列出遗漏问题的表格，按严重程度排序：`时间 · 遗漏内容 + 本可捕获它的策略 · 严重程度徽章 · 出现次数`，其中复发次数显示为 `new`（一次）、`N× seen`（2–9 次）或 `recurring`（10+ 次）。 -4. **改进建议** — 平和的列表行，每个推荐策略一行：左侧为白色策略名称和一行描述，右侧为安装命令和复制按钮。区块标题显示 `enable all N → projected · `（应用所有修复后可达到的评分），其 `[install all]` 按钮会复制针对所有推荐策略的组合 `failproofai policy add a b c …` 命令。 -5. **下次更好** — 两张并排卡片。左侧：设置提醒（`3d` / `7d` / `14d` / `30d` 周期选择器；认证后通过 `/api/auth/reminder` 持久化）。右侧：解锁 failproof 特权——`invite a friend` 打开一个模态框，接受逗号/空格/换行分隔的好友邮件列表（每次最多 10 个），通过 `/api/audit/invite` 发送 POST 请求，转发至 api-server 的 `POST /v0/invite`。api-server 从 `invite@failproof.ai` 向每位收件人发送邮件，同时将发件人抄送，并设置 `Reply-To`，以便收件人知道是谁邀请了他们，发件人也会在收件箱中收到一份副本。匿名用户会先通过 `AuthDialog` 进行路由，以便在发送邀请前获知发件人的邮件地址。权限/特权兑现为后续功能。 +1. **海报** — 占满第一个视口。自包含的 PNG 截图区域，包含 failproof_ai 文字标志 + 审计标签 · 原型索引（`№ NN of 08`）+ 审计日期 · 数字评分（0–100）+ 百分位排名标签（`top 15%`）· 原型名称（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` 之一）+ 3 个关键词条 · `// only N% of agents are this archetype` 稀有度说明 · 8×8 像素印记图块 · `audit yours → failproof.ai` 页脚。截图框外有三个分享按钮：`post your archetype`（X 意图）、`share on linkedin`、`download poster`。截图通过 `html-to-image` 运行，PNG 与屏幕渲染像素级一致（虚线边框、SVG logo 遮罩、渐变、字体度量——全部保留）。 +2. **优势** — 平静的 ✓ 行列表，列出你的 Agent 已经做对的行为，从实时审计数据中派生（工具调用通过率高、未直接推送到主分支、零凭证泄露、零重试风暴）——仅当相关策略在审计窗口内有干净记录时才会显示。 +3. **问题** — 列出漏掉的内容，按严重程度排序：`时间 · 漏掉的内容 + 本可捕获它的策略 · 严重程度标签 · 出现次数`，其中重复次数显示为 `new`（一次）、`N× seen`（2–9 次）或 `recurring`（10 次以上）。 +4. **改进建议** — 平静的行列表，每条对应一项建议策略：策略名称（白色）、单行描述、安装命令 + 右侧复制按钮。该区域标题显示 `enable all N → projected · `（应用所有修复后可达到的分数），其 `[install all]` 按钮会复制针对每项建议策略的合并 `failproofai policy add a b c …` 命令。 +5. **更好地回来** — 两张并排卡片。左侧：设置提醒（`3d` / `7d` / `14d` / `30d` 节奏选择器；通过 `/api/auth/reminder` 在认证后持久化）。右侧：解锁 failproof 特权——`invite a friend` 打开一个模态框，接受逗号/空格/换行符分隔的好友电子邮件列表（每次最多 10 个），将其 POST 到 `/api/audit/invite`，再转发至 api-server 的 `POST /v0/invite`。api-server 以 `invite@failproof.ai` 为每位收件人发送一封电子邮件，发件人抄送并设置 `Reply-To`，收件人能看到邀请者，发件人也会在收件箱中收到副本。匿名用户会先通过 `AuthDialog` 流程，以便在发送邀请前确认发件人邮箱。权益/特权履行为后续功能。 -由 `failproofai audit` 运行时驱动——请参阅 [审计 CLI](/zh/cli/audit) 了解底层扫描引擎、支持的标志和每个记录的缓存不变量。控制台将最新结果缓存在 `~/.failproofai/audit-dashboard.json`（模式 `0600`，单槽，新运行覆盖），以便再次访问时立即加载；**每个记录的缓存和整体结果缓存在读取时若超过 7 天则被拒绝**，因此控制台不会静默返回一周前的结果——超过 TTL 后 `/audit` 会回落到空状态并提示重新运行。点击报告底部附近的 `[ re-audit now ]` 会以 `noCache: true` 向 `/api/audit/run` 发送 POST 请求——重新审计会绕过每个记录的缓存，从头重新扫描每份记录，而不是静默返回缓存结果——控制台以 1Hz 轮询 `/api/audit/status` 直到运行完成；运行期间，一条粉色进度条固定在视口顶部并显示已用时间，完成后新结果会原地替换（无需整页刷新；重新审计失败时保留之前的报告）。失败时进度条变为红色，并根据 `RerunError.kind`（`timeout` / `network` / `post_failed`）显示对应文案。空状态（无缓存或已过期）和零会话状态（缓存存在但扫描未发现任何记录）会分别显示。 +由 `failproofai audit` 运行时驱动——有关底层扫描引擎、支持的标志和每条记录的缓存不变量，请参阅 [Audit CLI](/zh/cli/audit)。仪表盘将最新结果缓存在 `~/.failproofai/audit-dashboard.json`（模式 `0600`，单槽位，新运行覆盖旧结果），以便重访时立即加载；**每条记录的缓存和整体结果缓存在读取时一旦超过 7 天即被拒绝**，因此仪表盘永远不会静默提供一周前的旧结果——超过 TTL 后，`/audit` 会回落到空状态并提示重新运行。点击报告底部附近的 `[ re-audit now ]` 会以 `noCache: true` POST 到 `/api/audit/run`——重新审计会绕过每条记录的缓存，从头重新扫描所有记录，而不是静默返回缓存结果——仪表盘以 1Hz 轮询 `/api/audit/status` 直到运行完成；运行期间视口顶部会固定一条粉色进度条（含已用时间计时器），成功后新结果原地替换（无需整页刷新；重新审计失败则保留之前的报告）。失败时进度条变为红色，显示基于 `RerunError.kind`（`timeout` / `network` / `post_failed`）的提示文案。空状态（无缓存或已过期）和零会话状态（缓存存在但扫描未找到任何记录）分别独立显示。 ### 策略 -一个两标签页面，用于管理策略和查看活动。 +一个包含两个标签页的页面，用于管理策略和查看活动。 - - - 通过单一面板多选要让 failproofai 保护哪些 agent CLI——Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi 和 Hermes 均有各自行，显示安装状态（`Active` / `Detected` / `Inactive`）、用户范围设置路径和品牌色调。勾选或取消勾选您想要的 CLI，然后点击 `Apply changes` 一步完成安装/卸载差异。PATH 上检测到二进制文件的 CLI 会预先勾选。 - - 单击切换单个策略的启用/禁用状态（写入 `~/.failproofai/policies-config.json`——在所有已安装的 CLI 间共享） + + - 在单个面板中多选 failproofai 保护哪些 Agent CLI——Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi 和 Hermes 各有一行，显示安装状态（`Active` / `Detected` / `Inactive`）、用户范围设置路径和品牌配色强调色。勾选或取消勾选所需的 CLI，点击 `Apply changes` 一步安装/卸载差异。在 PATH 中检测到其二进制文件的 CLI 默认预选。 + - 单击一下即可启用或禁用单个策略（写入 `~/.failproofai/policies-config.json`——在所有已安装的 CLI 之间共享） - 展开策略以配置其参数（适用于支持 `policyParams` 的策略） - 设置自定义策略文件路径 - - - 跨所有会话触发的每个钩子事件的完整分页历史记录 - - 按决策、事件类型、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、策略名称或会话 ID 筛选 - - 每行显示：时间戳、策略名称、决策、CLI 徽章（橙色 = Claude Code，紫色 = OpenAI Codex，蓝色 = GitHub Copilot，翠绿色 = Cursor Agent，琥珀色 = OpenCode，粉色 = Pi，靛蓝色 = Hermes，青色 = OpenClaw，玫瑰色 = Factory Droid，紫罗兰色 = Devin，青蓝色 = Antigravity，青柠色 = Goose）、工具名称、会话 ID 以及 deny/instruct 决策的原因 - - 点击会话 ID 可打开其记录——查看器会自动检测触发钩子的 CLI（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state//events.jsonl`、Cursor Agent `~/.cursor/agent-sessions//events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions//.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents//sessions/*.jsonl`、Factory Droid `~/.factory/sessions//.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`）并在标题中渲染对应的 CLI 徽章 + + - 所有会话中已触发的每个 Hook 事件的完整分页历史记录 + - 按决策、事件类型、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、策略名称或会话 ID 过滤 + - 每行显示：时间戳、策略名称、决策、CLI 徽章（橙色 = Claude Code、紫色 = OpenAI Codex、蓝色 = GitHub Copilot、翠绿色 = Cursor Agent、琥珀色 = OpenCode、粉色 = Pi、靛蓝色 = Hermes、青色 = OpenClaw、玫瑰色 = Factory Droid、紫罗兰色 = Devin、青蓝色 = Antigravity、草绿色 = Goose）、工具名称、会话 ID 以及 deny/instruct 决策的原因 + - 点击会话 ID 可打开其记录——查看器自动检测触发 Hook 的 CLI（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state//events.jsonl`、Cursor Agent `~/.cursor/agent-sessions//events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions//.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents//sessions/*.jsonl`、Factory Droid `~/.factory/sessions//.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`）并在页眉中渲染对应的 CLI 徽章 @@ -94,13 +94,13 @@ Hermes 和 OpenClaw 是用户范围的，没有可用于分组的工作目录， ## 自动刷新 -控制台在顶部导航栏中有一个自动刷新切换开关。启用后，当前页面会定期刷新以显示新会话和策略活动。对于监控长时间运行的自主 Agent 会话至关重要。 +仪表盘顶部导航栏中有自动刷新开关。启用后，当前页面会定期刷新以显示新会话和策略活动。对于监控长时间运行的自主 Agent 会话至关重要。 --- ## 禁用页面 -如果您只需要控制台的某些部分，将 `FAILPROOFAI_DISABLE_PAGES` 设置为逗号分隔的页面名称列表： +如果你只需要仪表盘的某些部分，可将 `FAILPROOFAI_DISABLE_PAGES` 设置为以逗号分隔的页面名称列表： ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -112,7 +112,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## 配置项目路径 -默认情况下，控制台从标准 Claude Code 项目目录读取。对于自定义设置可以覆盖： +默认情况下，仪表盘从标准 Claude Code 项目目录读取。可为自定义设置覆盖此路径： ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -122,30 +122,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## 从非 localhost 主机访问 -在**开发模式**（`npm run dev`）下运行控制台，并从 localhost 以外的主机名访问时——例如自定义域名、远程 IP 或隧道 URL——您可能会看到如下警告： +在**开发模式**（`npm run dev`）下运行仪表盘并从 localhost 以外的主机名访问时——例如自定义域名、远程 IP 或隧道 URL——你可能会看到如下警告： ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -这是 Next.js 阻止对其 HMR（热模块重载）WebSocket 的跨域访问，这是一个仅限开发的功能。要允许您的主机，请使用 `--allowed-origins` 标志： +这是 Next.js 阻止对其 HMR（热模块重载）WebSocket 的跨域访问，该功能仅在开发模式下存在。要允许你的主机，请使用 `--allowed-origins` 标志： ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -对于多个主机或 IP，传递逗号分隔的列表： +如需多个主机或 IP，请传入以逗号分隔的列表： ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -您也可以改为设置 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 环境变量： +你也可以改为设置 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 环境变量： ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -这仅适用于开发模式。运行 `failproofai`（生产模式）时，不存在 HMR WebSocket，也没有跨域开发资源问题。 +这仅适用于开发模式。运行 `failproofai`（生产模式）时，不存在 HMR WebSocket，也不存在跨域开发资源问题。 \ No newline at end of file diff --git a/docs/zh/examples.mdx b/docs/zh/examples.mdx index b243454d..f3391b45 100644 --- a/docs/zh/examples.mdx +++ b/docs/zh/examples.mdx @@ -1,16 +1,16 @@ --- title: 示例 -description: "如何为 Claude Code 和 Agents SDK 设置钩子" +description: "如何为 Claude Code 和 Agents SDK 配置 Hook" icon: book-open --- -开箱即用的常见场景示例，每个示例都展示了如何安装以及预期效果。 +适用于常见场景的即用示例，每个示例均说明如何安装及预期效果。 --- -## 为 Claude Code 设置钩子 +## 为 Claude Code 配置 Hook -Failproof AI 通过 Claude Code 的[钩子系统](https://docs.anthropic.com/en/docs/claude-code/hooks)与其集成。运行 `failproofai policies --install` 时，它会在 Claude Code 的 `settings.json` 中注册钩子命令，这些命令会在每次工具调用时触发。 +Failproof AI 通过 Claude Code 的 [Hook 系统](https://docs.anthropic.com/en/docs/claude-code/hooks) 与其集成。运行 `failproofai policies --install` 后，它会在 Claude Code 的 `settings.json` 中注册 Hook 命令，每次工具调用时均会触发。 @@ -23,27 +23,27 @@ Failproof AI 通过 Claude Code 的[钩子系统](https://docs.anthropic.com/en/ failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - 你应该能看到 `PreToolUse`、`PostToolUse`、`Notification` 和 `Stop` 事件的钩子条目。 + 你应该能看到针对 `PreToolUse`、`PostToolUse`、`Notification` 和 `Stop` 事件的 Hook 条目。 ```bash claude ``` - 策略现在会在每次工具调用时自动执行。尝试让 Claude 运行 `sudo rm -rf /`——它将被拦截。 + 策略现在会在每次工具调用时自动执行。可以尝试让 Claude 运行 `sudo rm -rf /`，该操作将被拦截。 --- -## 为 Agents SDK 设置钩子 +## 为 Agents SDK 配置 Hook -如果你正在使用 [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) 进行开发，可以通过编程方式使用相同的钩子系统。 +如果你正在使用 [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) 进行开发，可以通过编程方式使用相同的 Hook 系统。 @@ -51,8 +51,8 @@ Failproof AI 通过 Claude Code 的[钩子系统](https://docs.anthropic.com/en/ npm install failproofai ``` - - 在创建 Agent 进程时传入钩子命令。钩子的触发方式与 Claude Code 中相同——通过 stdin/stdout JSON 进行通信： + + 在创建 Agent 进程时传入 Hook 命令。Hook 的触发方式与 Claude Code 中相同——通过 stdin/stdout JSON： ```bash failproofai --hook PreToolUse # called before each tool @@ -88,7 +88,7 @@ Failproof AI 通过 Claude Code 的[钩子系统](https://docs.anthropic.com/en/ ## 拦截破坏性命令 -最常见的配置——防止 Agent 造成不可逆的损害。 +最常见的配置——防止 Agent 造成不可逆的破坏。 ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -96,27 +96,27 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur 功能说明： - `block-sudo` - 拦截所有 `sudo` 命令 -- `block-rm-rf` - 拦截递归删除文件 +- `block-rm-rf` - 拦截递归删除文件操作 - `block-force-push` - 拦截 `git push --force` -- `block-curl-pipe-sh` - 拦截将远程脚本通过管道传入 shell 执行 +- `block-curl-pipe-sh` - 拦截将远程脚本管道传输到 shell 的操作 --- ## 防止密钥泄露 -阻止 Agent 在工具输出中读取或泄露凭证信息。 +阻止 Agent 在工具输出中查看或泄露凭据。 ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -这些策略在 `PostToolUse` 阶段触发——工具运行后，在 Agent 读取输出之前对其进行脱敏处理。 +这些策略在 `PostToolUse` 阶段触发——工具运行后，在 Agent 看到输出之前对其进行脱敏处理。 --- -## 在 Agent 需要关注时发送 Slack 通知 +## 在 Agent 需要关注时发送 Slack 提醒 -使用通知钩子将空闲提醒转发到 Slack。 +使用通知 Hook 将空闲提醒转发到 Slack。 ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -158,7 +158,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## 将 Agent 限制在指定分支 +## 将 Agent 限制在特定分支 防止 Agent 切换分支或推送到受保护的分支。 @@ -184,7 +184,7 @@ customPolicies.add({ ## 提交前要求运行测试 -提醒 Agent 在提交代码前先运行测试。 +提醒 Agent 在提交前先运行测试。 ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -208,7 +208,7 @@ customPolicies.add({ ## 锁定生产仓库 -在项目中提交一份项目级配置，让团队中的每位开发者都能应用相同的策略。 +将项目级配置提交到代码库，让团队中的每位开发者都使用相同的策略。 在仓库中创建 `.failproofai/policies-config.json`： @@ -238,13 +238,13 @@ git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -所有已安装 failproofai 的团队成员将自动获取这些规则。 +所有已安装 failproofai 的团队成员都会自动应用这些规则。 --- -## 通过约定策略构建全组织质量标准 +## 通过约定策略建立全组织质量标准 -最具影响力的配置：将针对项目定制的策略提交到仓库的 `.failproofai/policies/` 目录。每位团队成员都能自动获取——无需执行安装命令，无需修改配置。 +最具影响力的配置方式：将 `.failproofai/policies/` 目录及针对项目定制的策略一起提交到代码库。团队成员无需执行任何安装命令或修改配置，即可自动获取这些策略。 @@ -289,8 +289,8 @@ git commit -m "Add failproofai team policies" git commit -m "Add team quality policies" ``` - - 每当团队遇到新的故障模式时，添加新策略并推送。所有人在下次 `git pull` 时即可获取更新。这些策略将成为随团队成长而不断演进的质量标准。 + + 随着团队遇到新的问题，持续添加策略并推送。每位成员在下次 `git pull` 时即可获得更新。这些策略将成为随团队一同成长的活态质量标准。 @@ -300,8 +300,8 @@ git commit -m "Add failproofai team policies" 仓库中的 [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) 目录包含以下内容： -| 文件 | 内容说明 | -|------|---------------| -| `policies-basic.js` | 入门策略——拦截生产环境写入、force push、管道脚本 | -| `policies-notification.js` | 空闲通知和会话结束时的 Slack 告警 | -| `policies-advanced/index.js` | 传递导入、异步钩子、PostToolUse 输出脱敏、Stop 事件处理 | \ No newline at end of file +| 文件 | 说明 | +|------|------| +| `policies-basic.js` | 入门策略——拦截生产环境写入、强制推送、管道脚本 | +| `policies-notification.js` | 针对空闲通知和会话结束的 Slack 提醒 | +| `policies-advanced/index.js` | 传递导入、异步 Hook、PostToolUse 输出脱敏、Stop 事件处理 | \ No newline at end of file diff --git a/docs/zh/for-agents.mdx b/docs/zh/for-agents.mdx index d0c1c39e..f5952343 100644 --- a/docs/zh/for-agents.mdx +++ b/docs/zh/for-agents.mdx @@ -1,15 +1,15 @@ --- -title: "面向智能体" -description: "一条命令即可将 Failproof AI 知识添加到你的编程智能体中。支持 Claude Code、Cursor、Windsurf 等。" +title: "适用于智能体" +description: "一条命令即可将 Failproof AI 知识添加到您的编程智能体中。支持 Claude Code、Cursor、Windsurf 等。" --- -一条命令即可将完整的 Failproof AI 参考文档添加到你的编程智能体中。支持 Claude Code、Cursor、Windsurf 以及任何支持技能（skills）的智能体。 +一条命令即可将完整的 Failproof AI 参考文档添加到您的编程智能体中。支持 Claude Code、Cursor、Windsurf 以及任何其他支持技能的智能体。 ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` 会自动检测你已安装的智能体，并以适合各自的格式添加技能。 +`npx skills` 会自动检测您已安装的智能体，并以适合每个智能体的格式添加相应技能。 ## 技能涵盖的内容 @@ -20,19 +20,19 @@ npx skills add https://docs.befailproof.ai | 上下文对象 | `ctx.eventType`、`ctx.toolName`、`ctx.toolInput`、`ctx.session` | | 配置 | `policies-config.json` 结构、作用域合并、`policyParams` | | CLI | `failproofai policies --install`、`--uninstall`、`--custom`、作用域 | -| 仪表盘 | 会话查看器、策略活动、环境变量 | +| 控制台 | 会话查看器、策略活动、环境变量 | | 架构 | Hook 处理器流程、退出码、stdin/stdout 协议 | -## 技能内容是否完整？ +## 技能是否完整？ -Mintlify 会从导航中的所有页面生成 `llms.txt`。Failproof AI 文档涵盖完整的 API——每一条策略、选项和示例均已收录。如果你发现有所遗漏，源文件位于 `https://docs.befailproof.ai/llms-full.txt`。 +Mintlify 从导航中的所有页面生成 `llms.txt`。Failproof AI 文档覆盖了完整的 API——每条策略、每个选项和示例均已包含在内。如果您发现有所遗漏，源文件位于 `https://docs.befailproof.ai/llms-full.txt`。 -如需精准获取特定内容，可直接链接到具体页面： +如需精准的上下文，可直接链接到特定页面： ```bash -# 仅获取自定义策略 API +# 仅自定义策略 API npx skills add https://docs.befailproof.ai/custom-policies -# 仅获取内置策略 +# 仅内置策略 npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/zh/getting-started.mdx b/docs/zh/getting-started.mdx index 99731759..1580fd10 100644 --- a/docs/zh/getting-started.mdx +++ b/docs/zh/getting-started.mdx @@ -1,13 +1,13 @@ --- -title: 快速开始 -description: "安装 failproofai，启用策略，让你的 Agent 稳定运行" +title: 快速入门 +description: "安装 failproofai，启用策略，让你的智能体稳定运行" icon: rocket --- ## 环境要求 - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0（可选，仅在从源码构建时需要） +- **Bun** >= 1.3.0（可选 — 仅在从源码构建时需要） --- @@ -27,19 +27,19 @@ bun add -g failproofai --- -## 快速上手 +## 快速开始 - 策略是在每次 Agent 工具调用前后执行的规则，能够在破坏性命令、密钥泄露及其他故障发生之前将其拦截。 + 策略是在每次智能体工具调用前后执行的规则，能够在造成破坏之前拦截危险命令、密钥泄露及其他故障模式。 ```bash failproofai policies --install ``` - 此命令会将 hook 条目写入你已安装的 Agent CLI 配置文件中（Claude Code 的 `~/.claude/settings.json`、OpenAI Codex 的 `~/.codex/hooks.json`、GitHub Copilot CLI 的 `~/.copilot/hooks/failproofai.json`、Cursor Agent 的 `~/.cursor/hooks.json`、OpenCode 在 `~/.config/opencode/plugins/failproofai.mjs` 生成的插件垫片及 `~/.config/opencode/opencode.json` `plugin` 数组中的注册条目、Pi 的 `~/.pi/agent/settings.json`、Hermes 的 `~/.hermes/config.yaml`、OpenClaw 的 `~/.openclaw/openclaw.json`、Factory Droid 的 `~/.factory/hooks.json`、Devin CLI 的 `~/.config/devin/config.json`、Antigravity CLI 的 `~/.gemini/config/hooks.json`，以及 Goose 自动发现的插件目录 `~/.agents/plugins/failproofai/hooks/hooks.json`）。如果检测到多个 CLI，将弹出选择提示；传入 `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose`（任意子集）可跳过提示。 + 此命令会将 hook 条目写入已安装的智能体 CLI（Claude Code 的 `~/.claude/settings.json`、OpenAI Codex 的 `~/.codex/hooks.json`、GitHub Copilot CLI 的 `~/.copilot/hooks/failproofai.json`、Cursor Agent 的 `~/.cursor/hooks.json`、OpenCode 在 `~/.config/opencode/plugins/failproofai.mjs` 生成的插件垫片及 `~/.config/opencode/opencode.json` 的 `plugin` 数组中的注册条目、Pi 的 `~/.pi/agent/settings.json`、Hermes 的 `~/.hermes/config.yaml`、OpenClaw 的 `~/.openclaw/openclaw.json`、Factory Droid 的 `~/.factory/hooks.json`、Devin CLI 的 `~/.config/devin/config.json`、Antigravity CLI 的 `~/.gemini/config/hooks.json`，或 Goose 在 `~/.agents/plugins/failproofai/hooks/hooks.json` 自动发现的插件目录）。若检测到多个 CLI，系统会提示选择；也可通过 `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose`（任意子集）跳过提示。 - GitHub Copilot CLI、Cursor Agent、OpenCode 和 Pi 的支持目前处于 **Beta** 阶段 —— 分别使用 `--cli copilot`、`--cli cursor`、`--cli opencode` 或 `--cli pi` 安装。Hermes（hermes-agent，一个 Slack/Telegram 网关）使用 `--cli hermes` 以用户级别安装，**同时**也是一个离线审计数据源。OpenClaw（openclaw 网关，一个自托管多渠道助手）使用 `--cli openclaw` 以用户级别安装 —— 执行通过其进程内插件 hook（`before_agent_finalize` 是真正的轮次结束门控，因此 `require-*-before-stop` 内置规则会生效）—— **同时**也是一个离线审计数据源。Factory Droid（`droid`）使用 `--cli factory` 安装（用户 + 项目级别），**同时**也是一个离线审计数据源。Devin CLI（`devin`，Cognition）使用 `--cli devin` 安装（用户 + 项目级别），**同时**也是一个离线审计数据源。Antigravity CLI（`agy`）使用 `--cli antigravity` 安装（用户 + 项目级别），**同时**也是一个离线审计数据源。Goose（代号 goose，Block）使用 `--cli goose` 安装（用户 + 项目级别）—— 安装程序会在 `~/.agents/plugins/failproofai/` 创建插件目录，Goose 会自动发现该目录，**同时**也是一个离线审计数据源。 + GitHub Copilot CLI、Cursor Agent、OpenCode 和 Pi 的支持目前处于 **测试阶段** — 请分别使用 `--cli copilot`、`--cli cursor`、`--cli opencode` 或 `--cli pi` 安装。Hermes（hermes-agent，一个 Slack/Telegram 网关）使用 `--cli hermes` 以用户级别安装，**同时也**是离线审计数据源。OpenClaw（openclaw 网关，一个自托管多渠道助手）使用 `--cli openclaw` 以用户级别安装 — 策略执行通过其进程内插件 hook（`before_agent_finalize` 是真正的轮次结束门控，因此 `require-*-before-stop` 内置策略可正常执行）— **同时也**是离线审计数据源。Factory Droid（`droid`）使用 `--cli factory` 安装（用户级别 + 项目级别），**同时也**是离线审计数据源。Devin CLI（`devin`，Cognition）使用 `--cli devin` 安装（用户级别 + 项目级别），**同时也**是离线审计数据源。Antigravity CLI（`agy`）使用 `--cli antigravity` 安装（用户级别 + 项目级别），**同时也**是离线审计数据源。Goose（代号 goose，Block 出品）使用 `--cli goose` 安装（用户级别 + 项目级别）— 安装程序只需在 `~/.agents/plugins/failproofai/` 创建插件目录，Goose 会自动发现，**同时也**是离线审计数据源。 ```bash failproofai policies --install --scope project @@ -64,23 +64,23 @@ bun add -g failproofai 显示所有策略、是否已启用，以及已配置的参数。 - + ```bash failproofai ``` - 在 `http://localhost:8020` 打开本地控制台，你可以在此浏览会话、查看工具调用详情并管理策略。 + 在 `http://localhost:8020` 打开本地控制面板，可在此浏览会话、检查工具调用并管理策略。 - - 像往常一样启动 Claude Code。如果 Agent 尝试执行危险操作，failproofai 会自动拦截。无需守候，让它在后台运行，事后在控制台查看发生了什么。 + + 像往常一样启动 Claude Code。如果智能体尝试执行危险操作，failproofai 会自动拦截。你可以放心让它无人值守运行，之后在控制面板中查看执行记录。 --- -## 策略工作原理 +## 策略的工作原理 -每次 Agent 运行工具时，Claude Code 都会将 failproofai 作为子进程调用： +每当智能体运行工具时，Claude Code 会将 failproofai 作为子进程调用： ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -90,19 +90,19 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON 每条策略返回以下三种决策之一： -- **allow** —— Agent 正常继续执行 -- **deny** —— 操作被拦截，并告知 Agent 原因 -- **instruct** —— 在 Agent 的提示词中注入额外上下文 +- **allow** — 智能体正常继续执行 +- **deny** — 操作被阻止，并告知智能体原因 +- **instruct** — 向智能体的提示词中添加额外上下文 -策略在本地进程中运行，不会向任何远程服务发送数据。 +策略在本地进程中运行，不会向远程服务发送任何数据。 --- ## 通过约定式策略建立团队规范 -在团队中建立质量标准最快的方式是使用 `.failproofai/policies/` 约定目录。将策略文件放入该目录后即可自动加载 —— 无需任何标志、配置变更或安装命令。 +在团队中快速建立质量标准的最便捷方式是使用 `.failproofai/policies/` 约定目录。只需将策略文件放入该目录，它们会自动加载 — 无需任何标志、配置变更或安装命令。 @@ -111,13 +111,13 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON ``` - 复制示例文件，或自行编写： + 复制示例文件或自行编写： ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - 或者新建一个策略文件： + 或者新建一个： ```js // .failproofai/policies/team-policies.mjs @@ -142,12 +142,12 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON git commit -m "Add team quality policies" ``` - 所有安装了 failproofai 的团队成员都会自动获取这些策略，无需每位开发者单独配置。 + 所有安装了 failproofai 的团队成员都会自动获取这些策略，无需单独配置。 -将 `.failproofai/policies/` 提交到代码仓库，让整个团队共享统一的标准。随着团队发现新的故障模式，只需添加策略并推送 —— 所有人在下次 `git pull` 时即可获得更新。随着时间推移，这些策略将成为持续演进的活质量标准。 +将 `.failproofai/policies/` 提交到仓库，让整个团队共享同一套规范。随着团队发现新的故障模式，只需添加策略并推送 — 所有人在下次 `git pull` 时即可获取更新。随着时间推移，这些策略将成为不断完善的团队质量标准。 --- @@ -158,10 +158,12 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON | 路径 | 存储内容 | |------|----------------| -| `~/.failproofai/policies/local-policies/policies-config.json` | 全局策略配置 | +| `~/.failproofai/policies-config.json` | 全局策略配置 | +| `~/.failproofai/policies/` | 你自己的策略 — 将 `*-policies.mjs` 放入即可，无需任何配置 | +| `~/.failproofai/policies/cloud-policies/` | 由组织部署到本机的策略 | | `~/.failproofai/hook-activity/` | Hook 执行历史（分页 JSONL） | | `~/.failproofai/logs/` | 自定义 hook 错误的调试日志 | -| `.failproofai/policies-config.json` | 项目级配置（可提交到版本控制） | +| `.failproofai/policies-config.json` | 项目级配置（可提交） | | `.failproofai/policies-config.local.json` | 个人覆盖配置（已加入 gitignore） | --- @@ -189,10 +191,10 @@ failproofai policies --uninstall - 用 JavaScript 编写你自己的策略 + 使用 JavaScript 编写你自己的策略 - + 监控会话并查看策略活动 diff --git a/docs/zh/introduction.mdx b/docs/zh/introduction.mdx index 4cc7b60a..850659b3 100644 --- a/docs/zh/introduction.mdx +++ b/docs/zh/introduction.mdx @@ -1,41 +1,41 @@ --- title: "Failproof AI" -description: "FailproofAI 为 AI 智能体内置 39 条失效策略，一次安装即可捕获循环、密钥泄露、破坏性工具调用等问题。" +description: "FailproofAI 内置 39 项故障策略，一键安装即可捕获循环、密钥泄露、破坏性工具调用等问题。" --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -用于 **AI 故障处理**、**错误恢复** 和 **LLM 可靠性** 的钩子与策略。让你的 AI 智能体在 **Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Hermes**、**OpenClaw**、**Factory Droid**、**Devin CLI**、**Antigravity CLI** 以及 **Agents SDK** 上稳定、自主地持续运行。 +专为 **AI 故障处理**、**错误恢复**和 **LLM 可靠性**设计的 Hooks 与策略框架。让你的 AI 智能体在 **Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Hermes**、**OpenClaw**、**Factory Droid**、**Devin CLI**、**Antigravity CLI** 以及 **Agents SDK** 上稳定自主地持续运行。 -AI 智能体的失效方式往往是可预测的：执行破坏性命令、泄露密钥、偏离任务、陷入循环，或直接推送到主分支。若无人值守，小故障会接连引发服务中断、凭证泄露和数据丢失。 +AI 智能体的失败方式往往是可预见的：执行破坏性命令、泄露密钥、偏离任务、陷入死循环，或直接推送到主分支。若无人值守，小问题会迅速级联演变为服务中断、凭证泄露和工作成果丢失。 -FailproofAI 通过**策略**来解决这些问题。这些规则挂钩于智能体的每一次工具调用，**检测故障**、**加以缓解**（阻断、指导、净化），并在需要关注时**及时提醒你**。本地仪表盘让你可以事后回顾每一次工具调用、智能体故障及恢复动作。 +FailproofAI 通过**策略**来解决这一问题。这些规则挂钩于每一次智能体工具调用，**检测故障**、**进行缓解**（拦截、指令纠正、净化处理），并在需要关注时**提醒你**。本地仪表盘让你事后可以审查每一次工具调用、智能体故障及恢复操作。 -会话记录和策略评估均保存在本地。仅当你主动使用在线功能（如认证审计提醒或邀请功能）时，数据才会被发送。 +转录内容和策略评估均保留在你的本地机器上。只有在你明确使用在线功能（如经过身份验证的审计提醒或邀请）时，才会发送数据。 -## 开始使用 +## 快速入门 - - 开箱即用，阻断破坏性命令、防止密钥泄露、将智能体限制在项目边界内，以及更多功能。 + + 开箱即用：拦截破坏性命令、防止密钥泄露、将智能体限制在项目边界内，以及更多防护能力。 - 使用简洁的 allow / deny / instruct API，用 JavaScript 编写你自己的规则。 + 使用 JavaScript 编写专属规则，通过简洁的 allow / deny / instruct API 灵活扩展。 - 查看智能体在你离开期间的操作记录，浏览会话、检查工具调用、了解策略触发情况。 + 查看智能体在你离开期间的所有操作。浏览会话记录、检查工具调用、回顾策略触发情况。 - - 无需编写代码即可调整任意策略。按项目或全局设置允许列表、受保护分支或阈值。 + + 无需编写代码即可调整任意策略。按项目或全局设置白名单、受保护分支或阈值。 -## 快速上手 +## 快速开始 @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -完整流程请参阅[快速入门](/zh/getting-started)指南。 \ No newline at end of file +完整操作流程请参阅[入门指南](/zh/getting-started)。 \ No newline at end of file diff --git a/docs/zh/package-aliases.mdx b/docs/zh/package-aliases.mdx index 69311231..72d5fd50 100644 --- a/docs/zh/package-aliases.mdx +++ b/docs/zh/package-aliases.mdx @@ -6,7 +6,7 @@ icon: copy ## 官方包 -npm 的正式包名为 **`failproofai`**： +npm 的标准包名为 **`failproofai`**： ```bash npm install -g failproofai @@ -16,15 +16,15 @@ bun add -g failproofai --- -## 为什么我们持有这些别名 +## 为什么我们拥有这些别名 -错字抢注是一种常见的供应链攻击手段——恶意行为者注册与热门包名仅差一个按键的包名，毫无防备的用户在安装时一旦拼错命令，就会以完整系统权限运行攻击者控制的代码。这正是 Failproof AI 所要防范的威胁类型。 +错字抢注（Typosquatting）是一种常见的供应链攻击手段——恶意攻击者注册一个与热门包名仅差一个按键的包名。粗心的用户一旦在安装命令中打错字，就会在不知情的情况下以完整的系统权限运行攻击者控制的代码。这正是 Failproof AI 所要防范的威胁。 -为了消除这一攻击面，**我们在 npm 上抢先注册了 `failproofai` 的所有常见拼写错误及格式变体**。这些名称均无法被第三方注册。每个别名都是一个轻量代理，安装后会委托给真正的 `failproofai` 包。 +为了彻底消除这一攻击面，**我们在 npm 上预先注册了 `failproofai` 的所有常见拼写错误和格式变体**。这些包名均无法被第三方注册。每一个别名都是一个轻量级代理，会安装并委托给真正的 `failproofai` 包。 --- -## 已注册别名 +## 已注册的别名 **格式变体** — "failproof ai" 的不同书写方式： @@ -37,7 +37,7 @@ bun add -g failproofai | `fail_proof_ai` | ⏳ 等待 npm 审核 | | `fail-proofai` | ⏳ 等待 npm 审核 | -**`failprof*` 错字** — "proof" 中少了一个 `o`： +**`failprof*` 错字** — "proof" 中漏掉一个 `o`： | 包名 | 状态 | |---------|--------| @@ -47,7 +47,7 @@ bun add -g failproofai | `fail-prof-ai` | ⏳ 等待 npm 审核 | | `failprof_ai` | ⏳ 等待 npm 审核 | -**`faliproof*` 错字** — `a` 和 `i` 互换位置： +**`faliproof*` 错字** — `a` 和 `i` 顺序颠倒： | 包名 | 状态 | |---------|--------| @@ -55,9 +55,9 @@ bun add -g failproofai | `faliproof-ai` | ✅ 已发布 | | `faliproofai` | ⏳ 等待 npm 审核 | -> **为何处于等待状态？** npm 的垃圾内容防范策略会屏蔽在去除标点并经过相似度检测后与已有包名归一化结果相同的包名。我们已联系 npm 支持团队，申请以反抢注为目的保留这些名称，审批通过后将予以激活。 +> **为什么显示"等待审核"？** npm 的防垃圾政策会屏蔽那些在去除标点符号并进行相似度检查后，与已有包名规范化结果相同的包名。我们已联系 npm 支持团队，申请以反抢注为目的保留这些名称，待审批通过后即可激活。 -您可以验证任何已发布的别名是否由我们持有： +你可以验证任何已发布别名均由我们所有： ```bash npm info failproof @@ -70,13 +70,13 @@ npm info failproof 每个别名包： -1. 将 `failproofai` 列为依赖项——因此真正的包会被安装，其二进制文件也会随之可用 -2. 暴露一个与自身同名的二进制文件（例如 `failprof-ai`），将所有参数代理转发给 `failproofai` 二进制文件 +1. 将 `failproofai` 列为依赖项——这样真正的包会被安装，其二进制文件也随之可用 +2. 暴露一个与自身包名匹配的二进制文件（例如 `failprof-ai`），将所有参数代理转发给 `failproofai` 二进制文件 -代理脚本仅有两行 Node 代码，不含任何逻辑处理、网络请求或超出 `failproofai` 本身的数据收集行为。 +代理逻辑仅为两行 Node 脚本，没有任何业务逻辑、网络请求，也不会在 `failproofai` 本身行为之外进行任何数据收集。 --- -## 如果您发现我们遗漏的包名 +## 如果你发现我们遗漏了某个名称 -请在 [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) 提交 Issue，我们会及时注册。 \ No newline at end of file +请在 [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) 提交 issue，我们会及时注册。 \ No newline at end of file diff --git a/docs/zh/testing.mdx b/docs/zh/testing.mdx index f257b035..11062aad 100644 --- a/docs/zh/testing.mdx +++ b/docs/zh/testing.mdx @@ -4,7 +4,7 @@ description: "单元测试、E2E 测试及测试辅助工具" icon: flask-vial --- -failproofai 包含两套测试：**单元测试**（快速、使用 mock）和**端到端测试**（真实子进程调用）。 +failproofai 包含两个测试套件：**单元测试**（快速、使用 mock）和**端到端测试**（真实子进程调用）。 --- @@ -14,13 +14,13 @@ failproofai 包含两套测试：**单元测试**（快速、使用 mock）和** # 单次运行所有单元测试 bun run test:run -# 以监听模式运行单元测试 +# 以监视模式运行单元测试 bun run test -# 运行 E2E 测试（需要先完成配置，见下文） +# 运行 E2E 测试（需要先完成配置，详见下文） bun run test:e2e -# 类型检查（不编译） +# 仅进行类型检查，不构建 bunx tsc --noEmit # 代码检查 @@ -31,16 +31,16 @@ bun run lint ## 单元测试 -单元测试位于 `__tests__/` 目录，使用 [Vitest](https://vitest.dev) 和 `jsdom`。 +单元测试位于 `__tests__/` 目录下，使用 [Vitest](https://vitest.dev) 并配合 `jsdom` 运行。 ```text __tests__/ hooks/ - builtin-policies.test.ts # 各内置策略的逻辑 + builtin-policies.test.ts # 每个内置策略的逻辑测试 hooks-config.test.ts # 配置加载与作用域合并 policy-evaluator.test.ts # 参数注入与求值顺序 - custom-hooks-registry.test.ts # globalThis 注册表的增删改查 - custom-hooks-loader.test.ts # ESM 加载器、传递导入、错误处理 + custom-hooks-registry.test.ts # globalThis 注册表的增删查 + custom-hooks-loader.test.ts # ESM 加载器、传递性导入、错误处理 manager.test.ts # install/remove/list 操作 components/ sessions-list.test.tsx # 会话列表组件 @@ -110,11 +110,11 @@ describe("block-sudo", () => { ## 端到端测试 -E2E 测试将真实的 `failproofai` 二进制文件作为子进程调用，通过 stdin 传入 JSON payload，并对 stdout 输出和退出码进行断言。这覆盖了 Claude Code 所使用的完整集成路径。 +E2E 测试以子进程方式调用真实的 `failproofai` 二进制文件，将 JSON 负载通过 stdin 传入，并对 stdout 输出及退出码进行断言。这测试了 Claude Code 所使用的完整集成路径。 ### 配置 -E2E 测试直接从仓库源码运行二进制文件。在首次运行之前，需要构建自定义 hook 文件在导入 `'failproofai'` 时所依赖的 CJS 包： +E2E 测试直接从仓库源码运行二进制文件。在首次运行前，需要先构建自定义 hook 文件导入 `'failproofai'` 时所使用的 CJS 包： ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,20 +126,20 @@ bun build src/index.ts --outdir dist --target node --format cjs bun run test:e2e ``` -每当修改公共 hook API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts` 或 `src/hooks/policy-types.ts`）后，都需要重新构建 `dist/`。 +每当修改公共 hook API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts` 或 `src/hooks/policy-types.ts`）时，都需要重新构建 `dist/`。 ### E2E 测试结构 ```text __tests__/e2e/ helpers/ - hook-runner.ts # 启动二进制文件、传入 payload JSON、捕获退出码 + stdout + stderr - fixture-env.ts # 每个测试独立的临时目录与配置文件 - payloads.ts # 符合 Claude 格式的各事件类型 payload 工厂函数 + hook-runner.ts # 启动二进制进程，传入负载 JSON，捕获退出码 + stdout + stderr + fixture-env.ts # 每个测试独立的临时目录及配置文件 + payloads.ts # 与 Claude 一致的各事件类型负载工厂函数 hooks/ - builtin-policies.e2e.test.ts # 各内置策略的真实子进程测试 + builtin-policies.e2e.test.ts # 通过真实子进程测试每个内置策略 custom-hooks.e2e.test.ts # 自定义 hook 的加载与求值 - config-scopes.e2e.test.ts # 跨项目/本地/全局的配置合并 + config-scopes.e2e.test.ts # 跨 project/local/global 的配置合并 policy-params.e2e.test.ts # 各参数化策略的参数注入 ``` @@ -151,8 +151,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - 临时目录；作为 payload.cwd 传入，用于加载 .failproofai/policies-config.json -// env.home - 隔离的 home 目录；不会读取真实的 ~/.failproofai +// env.cwd - 临时目录；作为 payload.cwd 传入以加载 .failproofai/policies-config.json +// env.home - 隔离的 home 目录；真实的 ~/.failproofai 不会泄漏进来 env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - 现成的 payload 工厂函数： +**`Payloads`** - 现成的负载工厂函数： ```typescript Payloads.preToolUse.bash(command, cwd) @@ -231,14 +231,14 @@ describe("block-rm-rf (E2E)", () => { }); ``` -### E2E 响应格式 +### E2E 响应结构 | 决策 | 退出码 | stdout | |----------|-----------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Instruct（非 Stop）| `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | 空 stdout；原因输出到 stderr | +| Instruct（非 Stop） | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Stop instruct | `2` | stdout 为空；原因输出至 stderr | | Allow | `0` | 空字符串 | ### Vitest 配置 @@ -247,14 +247,14 @@ E2E 测试使用 `vitest.config.e2e.mts`，配置如下： - `environment: "node"` - 无需浏览器全局变量 - `pool: "forks"` - 真正的进程隔离（测试会启动子进程） -- `testTimeout: 20_000` - 每个测试 20 秒超时（含二进制启动 + hook 求值） +- `testTimeout: 20_000` - 每个测试 20 秒超时（二进制启动 + hook 求值） -`forks` 池非常重要：基于线程的 worker 共享 `globalThis`，可能干扰子进程启动类的测试，而基于进程的 forks 可以避免这一问题。 +`forks` 池模式至关重要：基于线程的 worker 共享 `globalThis`，可能干扰启动子进程的测试，而基于进程的 fork 可以避免这一问题。 --- ## CI -合并前必须通过完整的 CI 流程（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）。E2E 测试套件作为独立的 CI 任务并行运行。 +在合并前，必须通过完整的 CI 流程（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）。E2E 测试套件作为独立的 CI 任务并行运行。 -完整的合并前检查清单请参阅 [Contributing](../CONTRIBUTING.md)。 \ No newline at end of file +完整的合并前检查清单，请参见 [Contributing](../CONTRIBUTING.md)。 \ No newline at end of file diff --git a/scripts/translate-docs/cli.ts b/scripts/translate-docs/cli.ts index 1f23f68e..5096d0d7 100644 --- a/scripts/translate-docs/cli.ts +++ b/scripts/translate-docs/cli.ts @@ -268,7 +268,18 @@ async function main() { if ( !isForce && !isDryRun && - isCached(cache, relPath, lang, pageContents.get(page)!) + isCached(cache, relPath, lang, pageContents.get(page)!) && + // The cache records that a translation was PRODUCED, never that it + // EXISTS. Output lands on an unmerged auto-translate PR branch, so + // until that merges the checked-out tree lacks the file while the + // cache still says "done" — the page is never regenerated, and + // `--update-nav` (which reads the ENGLISH tree) emits a nav entry + // pointing at a file that is not there, so `mintlify validate` fails. + // That is non-convergent: a cache hit fails validation, and only a + // full cache MISS — 120 runner-minutes — produces a green run. + // Statting the output makes the cache self-healing against any + // "translated once, never landed" gap, whatever opened it. + existsSync(join(DOCS_DIR, lang, relPath)) ) { cachedTasks.push(task); } else { @@ -345,7 +356,10 @@ async function main() { if ( !isForce && !isDryRun && - isCached(cache, "README.md", lang, readmeSource) + isCached(cache, "README.md", lang, readmeSource) && + // Same reason as the MDX branch above: cached means translated once, + // not present now. + existsSync(join(DOCS_DIR, "i18n", `README.${lang}.md`)) ) { console.log(` README.${lang}.md -> cached`); results.push({ diff --git a/scripts/translate-docs/mdx-translator.ts b/scripts/translate-docs/mdx-translator.ts index 360cb109..01b1a342 100644 --- a/scripts/translate-docs/mdx-translator.ts +++ b/scripts/translate-docs/mdx-translator.ts @@ -209,7 +209,12 @@ export async function translateMdxPage( // Check cache — use provided cache object or read from disk if (!options.force && !options.dryRun) { const cache = options.cache ?? readCache(); - if (isCached(cache, relPath, lang, sourceContent)) { + // `&& existsSync(outputPath)` for the same reason as the batch path in + // cli.ts: a cache entry says a translation was produced once, not that the + // file is on disk now. This branch is the single-page path — the batch run + // never reaches it for a cached page — so it is guarded separately or the + // two disagree about what "cached" means. + if (isCached(cache, relPath, lang, sourceContent) && existsSync(outputPath)) { return { lang, sourcePath, diff --git a/scripts/translate-docs/readme-translator.ts b/scripts/translate-docs/readme-translator.ts index 681fd165..b2041e0c 100644 --- a/scripts/translate-docs/readme-translator.ts +++ b/scripts/translate-docs/readme-translator.ts @@ -1,4 +1,4 @@ -import { readFileSync, writeFileSync, mkdirSync } from "node:fs"; +import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { LANGUAGES, getLanguageByCode } from "./config"; @@ -220,7 +220,9 @@ export async function translateReadme( // Check cache — use provided cache object or read from disk if (!options.force && !options.dryRun) { const cache = options.cache ?? readCache(); - if (isCached(cache, "README.md", lang, sourceContent)) { + // `&& existsSync(outputPath)` — see the MDX path. Cached records that a + // translation was produced, not that the file is there now. + if (isCached(cache, "README.md", lang, sourceContent) && existsSync(outputPath)) { return { lang, sourcePath: README_PATH,